feat(server,web): import and export Trace files in the trace viewer (#73)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/server/src/api/types.ts

@@ -939,6 +939,20 @@ export interface AgentTracesResponse {
   dates: AgentTraceDateGroup[];
 }
 
+export interface TraceImportRequest {
+  /** Base64 of the Trace file content (JSON Lines; the first record must be `session_meta`). */
+  dataBase64: string;
+}
+
+export interface TraceImportResponse {
+  /** Session id taken from the imported file's `session_meta`. */
+  sessionId: string;
+  /** Allocated file index: always 1 — an import creates a new Session (a duplicate session id is rejected with 409 `trace_session_exists`). */
+  index: number;
+  /** Date directory the file landed in (local yyyy-mm-dd from the first record's timestamp, matching the Trace Writer's convention). */
+  date: string;
+}
+
 // ---------------------------------------------------------------------------
 // Usage and cost statistics
 // ---------------------------------------------------------------------------

packages/server/src/http/routes/agent-traces.ts

@@ -1,17 +1,32 @@
 /**
  * Agent-level Trace browsing routes:
  *   - GET /api/projects/:p/agents/:a/traces — drills down Agent -> date -> Session -> index (reverse order);
- *   - GET /api/projects/:p/agents/:a/traces/:sessionId/:index (including /analysis) —
+ *   - GET /api/projects/:p/agents/:a/traces/:sessionId/:index (including /analysis, /download) —
  *     read-only Trace detail endpoints (FD-3): locate the Trace file directly by
  *     (projectId, agentId, sessionId), without depending on the sessions table for
  *     tracking — any entry visible in the directory tree (subagent child Sessions,
  *     CLI-created Sessions) can be opened and read; access is enforced by requireProjectAccess.
+ *   - POST /api/projects/:p/agents/:a/traces/import — uploads a Trace JSONL file (owner
+ *     only, mirroring the Agent snapshot import); the file names itself via its
+ *     session_meta and always becomes index 001 of a new Session — a session id the
+ *     Agent already has is rejected with 409 trace_session_exists.
  */
 import { Hono } from "hono";
 import type { AppEnv } from "../../auth/middleware.js";
-import { paginationQuery, positiveIntParam, requireValidId } from "../validate.js";
+import type { TraceImportResponse } from "../../api/types.js";
+import {
+  badRequest,
+  paginationQuery,
+  positiveIntParam,
+  readJson,
+  requireString,
+  requireValidId,
+} from "../validate.js";
 import type { AppDeps } from "../../app.js";
 
+/** Import file size cap: aligned with the snapshot import (stays within the 20MB body limit after base64). */
+const MAX_TRACE_BYTES = 14 * 1024 * 1024;
+
 export function agentTracesRoutes(deps: AppDeps): Hono<AppEnv> {
   const app = new Hono<AppEnv>();
 
@@ -44,5 +59,47 @@ export function agentTracesRoutes(deps: AppDeps): Hono<AppEnv> {
     return c.json(await deps.traceService.analyze(projectId, agentId, sessionId, index));
   });
 
+  // Raw-file download (any member, like the snapshot export): the file is served verbatim
+  // as an attachment, so what's downloaded can be re-imported byte-compatibly.
+  app.get("/:sessionId/:index/download", async (c) => {
+    const projectId = requireValidId(c, "projectId");
+    const agentId = requireValidId(c, "agentId");
+    const sessionId = requireValidId(c, "sessionId");
+    deps.projectService.requireProjectAccess(c.var.user.userId, projectId);
+    const index = positiveIntParam(c, "index");
+    const bytes = await deps.traceService.readFileRaw(projectId, agentId, sessionId, index);
+    const fileName = `${sessionId}_${String(index).padStart(3, "0")}.jsonl`;
+    return new Response(new Uint8Array(bytes), {
+      headers: {
+        "Content-Type": "application/x-ndjson",
+        "Content-Disposition": `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`,
+        "X-Content-Type-Options": "nosniff",
+      },
+    });
+  });
+
+  // Trace file upload (owner only, mirroring the Agent snapshot import): the route checks the
+  // transport shape (base64, size); the content itself — JSONL, leading session_meta, a
+  // filename-safe session_id — is validated by the service right where the path is built.
+  app.post("/import", async (c) => {
+    const projectId = requireValidId(c, "projectId");
+    const agentId = requireValidId(c, "agentId");
+    deps.projectService.requireProjectOwner(c.var.user.userId, projectId);
+    await deps.agentConfigService.requireExists(projectId, agentId);
+    const body = await readJson(c);
+    const dataBase64 = requireString(body, "dataBase64", { minLen: 1, maxLen: 20 * 1024 * 1024 });
+    const bytes = Buffer.from(dataBase64, "base64");
+    if (bytes.byteLength === 0) throw badRequest("Import file is empty.");
+    if (bytes.byteLength > MAX_TRACE_BYTES) {
+      throw badRequest("Import file exceeds the 14MB limit.");
+    }
+    const res: TraceImportResponse = await deps.traceService.importTraceFile(
+      projectId,
+      agentId,
+      bytes.toString("utf8"),
+    );
+    return c.json(res);
+  });
+
   return app;
 }

packages/server/src/services/trace-service.ts

@@ -13,6 +13,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import {
   agentsDir,
+  isSessionMeta,
+  parseTraceLines,
   parseUserSteeringText,
   readTraceTolerant,
   tracesDir,
@@ -25,15 +27,24 @@ import type {
   TraceAnalysisResponse,
   TraceEventsResponse,
   TraceFileInfo,
+  TraceImportResponse,
   TraceModelSegment,
   TraceTaskStats,
   TraceToolSpan,
   UsageTrendPointInTrace,
 } from "../api/types.js";
 import { HttpError } from "../http/errors.js";
+import { formatLocalDate } from "../internal/dates.js";
 
 const TRACE_FILE_RE = /^(.+)_(\d{3})\.jsonl$/;
 
+/**
+ * session_id an imported Trace file may declare: same alphabet as resource ids plus a length
+ * cap. The value becomes part of the target **filename**, so this is a path-traversal defense,
+ * checked right next to the path construction — never trust the caller to have validated it.
+ */
+const IMPORT_SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+
 /** Recursion depth cap for sub-session expansion (run_subagent depth is already constrained by the SDK; this is just a defensive backstop against cycles). */
 const MAX_SUBAGENT_DEPTH = 4;
 
@@ -687,6 +698,16 @@ export class TraceService {
     sessionId: string,
     index: number,
   ): Promise<OmniMessage[]> {
+    const file = await this.locateByIndex(projectId, agentId, sessionId, index);
+    return readTraceTolerant(file.path);
+  }
+
+  private async locateByIndex(
+    projectId: string,
+    agentId: string,
+    sessionId: string,
+    index: number,
+  ): Promise<LocatedFile> {
     const files = await this.locateAll(projectId, agentId, sessionId);
     const file = files.find((f) => f.index === index);
     if (!file) {
@@ -696,6 +717,80 @@ export class TraceService {
         `This Session has no Trace file with index ${index}.`,
       );
     }
-    return readTraceTolerant(file.path);
+    return file;
+  }
+
+  /** Raw bytes of the Trace file at the given index (export/download: the file is served verbatim). */
+  async readFileRaw(
+    projectId: string,
+    agentId: string,
+    sessionId: string,
+    index: number,
+  ): Promise<Buffer> {
+    const file = await this.locateByIndex(projectId, agentId, sessionId, index);
+    return fs.readFile(file.path);
+  }
+
+  /**
+   * Imports an uploaded Trace file (raw JSONL content). Validates the content itself —
+   * parseable JSONL whose first record is a `session_meta` carrying a filename-safe
+   * `session_id` (400 invalid_trace otherwise) — then writes it under the Agent's traces
+   * directory as a **new Session**: a session id the Agent already has is rejected with
+   * 409 `trace_session_exists` (splicing a further index into an existing Session would
+   * corrupt its concatenated transcript, silently become its resume point, and could
+   * collide with a live Writer's rotation), so the imported file is always index 1. The
+   * date dir comes from the first record's timestamp (falling back to now), formatted as
+   * a **local** date — the same convention as core's Trace Writer — so an export →
+   * import round-trip lands in the same date dir on non-UTC servers.
+   */
+  async importTraceFile(
+    projectId: string,
+    agentId: string,
+    content: string,
+  ): Promise<TraceImportResponse> {
+    const invalid = (message: string) => new HttpError(400, "invalid_trace", message);
+    let records: OmniMessage[];
+    try {
+      records = parseTraceLines(content);
+    } catch {
+      throw invalid("The file is not valid Trace JSONL.");
+    }
+    if (records.length === 0) throw invalid("The file contains no Trace records.");
+    const first = records[0]!;
+    if (!isSessionMeta(first))
+      throw invalid("The first record of a Trace file must be session_meta.");
+    // The payload type declares session_id: string, but the value came from user-supplied JSON —
+    // re-check the runtime shape before it becomes part of a filename.
+    const sessionId: unknown = (first.payload as { session_id?: unknown }).session_id;
+    if (typeof sessionId !== "string" || !IMPORT_SESSION_ID_RE.test(sessionId)) {
+      throw invalid("session_meta carries a missing or invalid session_id.");
+    }
+    const duplicate = () =>
+      new HttpError(
+        409,
+        "trace_session_exists",
+        `This Agent already has a Session with id ${sessionId}; a duplicate Trace cannot be imported.`,
+      );
+    if ((await this.locateAll(projectId, agentId, sessionId)).length > 0) throw duplicate();
+    const ts = Date.parse(first.timestamp);
+    const date = formatLocalDate(Number.isNaN(ts) ? new Date() : new Date(ts));
+    const index = 1;
+    const dir = path.join(tracesDir(this.root, projectId, agentId), date);
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${sessionId}_${String(index).padStart(3, "0")}.jsonl`);
+    try {
+      // Normalize to exactly one trailing newline (the JSONL convention the writer
+      // follows). `wx` closes the check-then-write race: two concurrent imports of the
+      // same new session id both pass the locateAll check, but only one can create the
+      // file — the loser's EEXIST maps to the same 409 as the pre-check.
+      await fs.writeFile(file, content.replace(/\n+$/, "") + "\n", {
+        encoding: "utf8",
+        flag: "wx",
+      });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "EEXIST") throw duplicate();
+      throw err;
+    }
+    return { sessionId, index, date };
   }
 }

packages/server/test/trace-import-export.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Trace file export/import integration tests:
+ * export serves the raw JSONL verbatim as an attachment (any member); import validates the
+ * uploaded content (parseable JSONL, leading session_meta, filename-safe session_id) and
+ * always stores it as index 1 of a new Session — a session id the Agent already has is
+ * rejected with 409 trace_session_exists — and the file is then browsable through the
+ * existing tree/detail endpoints. Import is owner-only, mirroring the Agent snapshot import.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { OmniMessage, SessionMetaPayload } from "@prismshadow/penguin-core";
+import type {
+  AgentTracesResponse,
+  ProjectCreateResponse,
+  TraceEventsResponse,
+  TraceImportResponse,
+} from "../src/api/types.js";
+import { apiClient, createTestApp, provisionUser, writeTraceFile } from "./helpers.js";
+import type { TestApp } from "./helpers.js";
+
+const SID = "session-2026-07-06-09-00-00-feed0001";
+
+function metaPayload(sessionId: string): SessionMetaPayload {
+  return {
+    session_id: sessionId,
+    model_id: "m",
+    provider: "custom",
+    model_context_window: 1000,
+    system_prompt: "",
+    tools: [],
+    agent_state: "/tmp/a",
+    workspace: "/tmp/w",
+  };
+}
+
+/** Envelope with a fixed timestamp (the builders stamp "now"; import derives the date dir from it). */
+const rec = (timestamp: string, type: OmniMessage["type"], payload: unknown): OmniMessage =>
+  ({ timestamp, type, payload }) as OmniMessage;
+
+/** First record's timestamp: 02:00 UTC, so on runners west of UTC the local date differs from the UTC date. */
+const FIRST_TS = "2026-07-06T02:00:00.000Z";
+
+function sampleTrace(sessionId: string): OmniMessage[] {
+  return [
+    rec(FIRST_TS, "session_meta", metaPayload(sessionId)),
+    rec("2026-07-06T02:00:01.000Z", "model_msg", {
+      type: "text",
+      role: "user",
+      text: "imported input",
+    }),
+    rec("2026-07-06T02:00:02.000Z", "event_msg", { type: "request_begin" }),
+    rec("2026-07-06T02:00:03.000Z", "event_msg", { type: "request_end", status: "completed" }),
+  ];
+}
+
+/**
+ * Local yyyy-mm-dd of a timestamp — the import derives its date dir with local-date
+ * formatting (core Trace Writer convention), not UTC. Computing the expectation the same
+ * way keeps these tests timezone-independent, and on a non-UTC runner they fail if the
+ * import regresses to UTC (FIRST_TS is chosen so the two dates differ west of UTC).
+ */
+function localDateOf(iso: string): string {
+  const d = new Date(iso);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+const toContent = (messages: OmniMessage[]): string =>
+  messages.map((m) => JSON.stringify(m)).join("\n") + "\n";
+const b64 = (s: string): string => Buffer.from(s, "utf8").toString("base64");
+
+async function errorCode(res: Response): Promise<string> {
+  const body = (await res.json()) as { error: { code: string } };
+  return body.error.code;
+}
+
+describe("trace-import-export", () => {
+  let t: TestApp;
+  let owner: ReturnType<typeof apiClient>;
+  let member: ReturnType<typeof apiClient>;
+  let outsider: ReturnType<typeof apiClient>;
+  let projectId: string;
+  const base = () => `/api/projects/${projectId}/agents/default_agent/traces`;
+
+  beforeEach(async () => {
+    t = await createTestApp();
+    const a = await provisionUser(t.app, "owner");
+    const b = await provisionUser(t.app, "member_b");
+    const c = await provisionUser(t.app, "outsider");
+    owner = apiClient(t.app, a.cookie);
+    member = apiClient(t.app, b.cookie);
+    outsider = apiClient(t.app, c.cookie);
+    const created = (await (
+      await owner.post("/api/projects", { projectId: "owner-trace_io", name: "Trace IO" })
+    ).json()) as ProjectCreateResponse;
+    projectId = created.project.projectId;
+    expect(
+      (await owner.post(`/api/projects/${projectId}/members`, { userId: "member_b" })).status,
+    ).toBe(201);
+  });
+  afterEach(async () => {
+    await t.cleanup();
+  });
+
+  it("export: serves the raw file with attachment headers (any member)", async () => {
+    const messages = sampleTrace(SID);
+    await writeTraceFile(t.root, projectId, "default_agent", "2026-07-06", SID, 1, messages);
+    const res = await owner.get(`${base()}/${SID}/1/download`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("application/x-ndjson");
+    expect(res.headers.get("content-disposition")).toBe(
+      `attachment; filename*=UTF-8''${SID}_001.jsonl`,
+    );
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(await res.text()).toBe(toContent(messages));
+    // A plain member can export too (same rule as the snapshot export).
+    expect((await member.get(`${base()}/${SID}/1/download`)).status).toBe(200);
+  });
+
+  it("export: unknown index → 404 trace_not_found; outsider → 404", async () => {
+    await writeTraceFile(
+      t.root,
+      projectId,
+      "default_agent",
+      "2026-07-06",
+      SID,
+      1,
+      sampleTrace(SID),
+    );
+    const missing = await owner.get(`${base()}/${SID}/9/download`);
+    expect(missing.status).toBe(404);
+    expect(await errorCode(missing)).toBe("trace_not_found");
+    // No Project access → uniform 404 (requireProjectAccess does not leak existence).
+    expect((await outsider.get(`${base()}/${SID}/1/download`)).status).toBe(404);
+  });
+
+  it("import: stores the file as index 1 and it becomes browsable through the existing endpoints", async () => {
+    const content = toContent(sampleTrace(SID)).trimEnd(); // uploaded without a trailing newline
+    const res = await owner.post(`${base()}/import`, { dataBase64: b64(content) });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as TraceImportResponse;
+    expect(body).toEqual({ sessionId: SID, index: 1, date: localDateOf(FIRST_TS) });
+    // Appears in the drill-down tree under the local date derived from the first record's timestamp.
+    const tree = (await (await owner.get(base())).json()) as AgentTracesResponse;
+    expect(tree.dates).toHaveLength(1);
+    expect(tree.dates[0]!.date).toBe(localDateOf(FIRST_TS));
+    expect(tree.dates[0]!.sessions[0]!.sessionId).toBe(SID);
+    expect(tree.dates[0]!.sessions[0]!.files.map((f) => f.index)).toEqual([1]);
+    // Events are readable via the existing detail endpoint.
+    const events = (await (await owner.get(`${base()}/${SID}/1`)).json()) as TraceEventsResponse;
+    expect(events.total).toBe(4);
+    expect((events.events[1]!.payload as { text: string }).text).toBe("imported input");
+    // Round-trip: the stored content is normalized to exactly one trailing newline.
+    expect(await (await owner.get(`${base()}/${SID}/1/download`)).text()).toBe(content + "\n");
+  });
+
+  it("import: duplicate session id → 409 trace_session_exists, nothing written", async () => {
+    const original = sampleTrace(SID);
+    // An existing file in any date dir counts — even a different date than the upload's.
+    await writeTraceFile(t.root, projectId, "default_agent", "2026-07-05", SID, 1, original);
+    const res = await owner.post(`${base()}/import`, {
+      dataBase64: b64(toContent(sampleTrace(SID))),
+    });
+    expect(res.status).toBe(409);
+    expect(await errorCode(res)).toBe("trace_session_exists");
+    // Nothing was written: the tree still shows only the pre-existing file, intact.
+    const tree = (await (await owner.get(base())).json()) as AgentTracesResponse;
+    expect(tree.dates).toHaveLength(1);
+    expect(tree.dates[0]!.date).toBe("2026-07-05");
+    expect(tree.dates[0]!.sessions[0]!.files.map((f) => f.index)).toEqual([1]);
+    expect(await (await owner.get(`${base()}/${SID}/1/download`)).text()).toBe(toContent(original));
+  });
+
+  it("import: concurrent imports of the same new session id — exactly one wins", async () => {
+    // Whichever request loses is rejected either by the pre-check (locateAll) or by the
+    // exclusive `wx` write (EEXIST → the same 409), so the observable outcome is
+    // deterministic even though the internal interleaving isn't: one 200, one 409, and
+    // exactly one stored file.
+    const content = toContent(sampleTrace(SID));
+    const [a, b] = await Promise.all([
+      owner.post(`${base()}/import`, { dataBase64: b64(content) }),
+      owner.post(`${base()}/import`, { dataBase64: b64(content) }),
+    ]);
+    expect([a.status, b.status].sort((x, y) => x - y)).toEqual([200, 409]);
+    expect(await errorCode(a.status === 409 ? a : b)).toBe("trace_session_exists");
+    const tree = (await (await owner.get(base())).json()) as AgentTracesResponse;
+    expect(tree.dates).toHaveLength(1);
+    expect(tree.dates[0]!.sessions[0]!.files.map((f) => f.index)).toEqual([1]);
+  });
+
+  it("import: malformed middle line → 400 invalid_trace", async () => {
+    const lines = toContent(sampleTrace(SID)).split("\n");
+    lines[1] = "{not json"; // corrupt a middle line (non-final: parseTraceLines throws loudly)
+    const res = await owner.post(`${base()}/import`, { dataBase64: b64(lines.join("\n")) });
+    expect(res.status).toBe(400);
+    expect(await errorCode(res)).toBe("invalid_trace");
+  });
+
+  it("import: first record not session_meta → 400 invalid_trace", async () => {
+    const content = toContent([
+      rec("2026-07-06T09:00:00.000Z", "model_msg", { type: "text", role: "user", text: "x" }),
+    ]);
+    const res = await owner.post(`${base()}/import`, { dataBase64: b64(content) });
+    expect(res.status).toBe(400);
+    expect(await errorCode(res)).toBe("invalid_trace");
+  });
+
+  it("import: session_meta with a filename-unsafe session_id → 400 invalid_trace", async () => {
+    const content = toContent([
+      rec("2026-07-06T09:00:00.000Z", "session_meta", metaPayload("../../escape")),
+    ]);
+    const res = await owner.post(`${base()}/import`, { dataBase64: b64(content) });
+    expect(res.status).toBe(400);
+    expect(await errorCode(res)).toBe("invalid_trace");
+  });
+
+  it("import: payload over 14MB → 400 (same cap style as the snapshot import)", async () => {
+    const res = await owner.post(`${base()}/import`, {
+      dataBase64: b64("a".repeat(14 * 1024 * 1024 + 1)),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("import: owner only — member 403, outsider 404, unknown agent 404", async () => {
+    const body = { dataBase64: b64(toContent(sampleTrace(SID))) };
+    expect((await member.post(`${base()}/import`, body)).status).toBe(403);
+    expect((await outsider.post(`${base()}/import`, body)).status).toBe(404);
+    expect(
+      (await owner.post(`/api/projects/${projectId}/agents/ghost/traces/import`, body)).status,
+    ).toBe(404);
+  });
+});