Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

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

Yaowei Zhengf192db338e99
diff --git a/packages/docs/content/server-api.en.md b/packages/docs/content/server-api.en.md
index 3fd5254c..673577c4 100644
--- a/packages/docs/content/server-api.en.md
+++ b/packages/docs/content/server-api.en.md
@@ -134,6 +134,10 @@ On Session creation, `modelId` and `provider` are both-or-neither: send the comp
| GET | /agents/:agentId/traces | Date → Session drill-down structure of Trace files |
| GET | /agents/:agentId/traces/:sessionId/:index | Read Trace events (`offset` / `limit` pagination) |
| GET | /agents/:agentId/traces/:sessionId/:index/analysis | Trace performance analysis |
+| GET | /agents/:agentId/traces/:sessionId/:index/download | Download the raw Trace file (JSONL attachment) |
+| POST | /agents/:agentId/traces/import | Import a Trace file: `{dataBase64}` → `{sessionId, index, date}` |
+
+Trace download is available to any member; import is owner-only (like the Agent snapshot import, capped at 14MB). An imported file must be valid Trace JSONL whose first record is a `session_meta` with a filename-safe `session_id`; a session id the Agent already has is rejected (409 `trace_session_exists`), so an imported file always becomes index 001 of a new Session, landing in the local date directory of its first record's timestamp.
### Session-Level Endpoints
diff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.md
index 8fb8ffa7..a631a5ec 100644
--- a/packages/docs/content/server-api.zh.md
+++ b/packages/docs/content/server-api.zh.md
@@ -134,6 +134,10 @@ Schedule 写操作仅限 Owner。新建 Session 模式的任务,`modelId` 与
| GET | /agents/:agentId/traces | Trace 文件的日期 → Session 下钻结构 |
| GET | /agents/:agentId/traces/:sessionId/:index | 读取 Trace 事件(`offset` / `limit` 分页) |
| GET | /agents/:agentId/traces/:sessionId/:index/analysis | Trace 性能分析结果 |
+| GET | /agents/:agentId/traces/:sessionId/:index/download | 下载 Trace 原始文件(JSONL 附件) |
+| POST | /agents/:agentId/traces/import | 导入 Trace 文件:`{dataBase64}` → `{sessionId, index, date}` |
+
+Trace 下载对任意成员开放;导入仅限 owner(同 Agent 快照导入,上限 14MB)。导入文件必须是合法的 Trace JSONL,且首条记录为携带文件名安全 `session_id` 的 `session_meta`;若该 Agent 已存在同名 Session,导入将被拒绝(409 `trace_session_exists`),因此导入文件总是成为一个新 Session 的 001 号文件,并按首条记录时间戳的本地日期落入对应日期目录。
### Session 级接口
diff --git a/packages/docs/content/sessions-and-traces.en.md b/packages/docs/content/sessions-and-traces.en.md
index 032286c4..1daf5e67 100644
--- a/packages/docs/content/sessions-and-traces.en.md
+++ b/packages/docs/content/sessions-and-traces.en.md
@@ -89,4 +89,4 @@ Each content message's opaque provider `fidelity` payload (thinking signatures,
## Observability
-Every approval decision (`approval_decision`), abort (`abort`), compaction (`compaction_begin` / `compaction_end`), and `token_usage` lands in the Trace as an event. The Web Trace view and the usage/cost statistics are both derived from this same data — there is no second source of truth; see the [Web App Guide](/web-app). The approval mechanism itself is covered in [Tools & Approval](/tools).
+Every approval decision (`approval_decision`), abort (`abort`), compaction (`compaction_begin` / `compaction_end`), and `token_usage` lands in the Trace as an event. The Web Trace view and the usage/cost statistics are both derived from this same data — there is no second source of truth; see the [Web App Guide](/web-app). The approval mechanism itself is covered in [Tools & Approval](/tools). Trace files can also be moved across deployments from the Web Traces page: any file can be exported (downloaded verbatim as JSONL) and imported back under an Agent — an import whose session id already exists under that Agent is rejected, so an imported file always becomes index 001 of a new Session.
diff --git a/packages/docs/content/sessions-and-traces.zh.md b/packages/docs/content/sessions-and-traces.zh.md
index 60f312c3..ecc3bafe 100644
--- a/packages/docs/content/sessions-and-traces.zh.md
+++ b/packages/docs/content/sessions-and-traces.zh.md
@@ -89,4 +89,4 @@ Web 的 `/model` 命令按 @ handoff 的方式换模型:用普通的会话创
## 可观测性
-每一次审批决策(`approval_decision`)、中断(`abort`)、压缩(`compaction_begin` / `compaction_end`)与 `token_usage` 都作为事件落入 Trace。Web 的 Trace 视图与用量、成本统计均由这同一份数据派生,不存在第二事实来源;见 [Web App 指南](/web-app)。审批机制本身见[工具与审批](/tools)。
+每一次审批决策(`approval_decision`)、中断(`abort`)、压缩(`compaction_begin` / `compaction_end`)与 `token_usage` 都作为事件落入 Trace。Web 的 Trace 视图与用量、成本统计均由这同一份数据派生,不存在第二事实来源;见 [Web App 指南](/web-app)。审批机制本身见[工具与审批](/tools)。Trace 文件还可以在部署之间迁移:在 Web 轨迹观测页可将任意文件导出(按原样下载为 JSONL),也可导入到某个 Agent 下——若该 Agent 已存在同名 Session 则导入被拒绝,因此导入文件总是成为一个新 Session 的 001 号文件。
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index 20b49234..8cd25889 100644
--- a/packages/server/src/api/types.ts
+++ b/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
// ---------------------------------------------------------------------------
diff --git a/packages/server/src/http/routes/agent-traces.ts b/packages/server/src/http/routes/agent-traces.ts
index 49a3cae5..84f6df1b 100644
--- a/packages/server/src/http/routes/agent-traces.ts
+++ b/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;
}
diff --git a/packages/server/src/services/trace-service.ts b/packages/server/src/services/trace-service.ts
index 45343aed..6fc43c76 100644
--- a/packages/server/src/services/trace-service.ts
+++ b/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 };
}
}
diff --git a/packages/server/test/trace-import-export.test.ts b/packages/server/test/trace-import-export.test.ts
new file mode 100644
index 00000000..58dfa4b3
--- /dev/null
+++ b/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);
+ });
+});
diff --git a/packages/web/src/api/endpoints.ts b/packages/web/src/api/endpoints.ts
index 58c42713..4053a5b1 100644
--- a/packages/web/src/api/endpoints.ts
+++ b/packages/web/src/api/endpoints.ts
@@ -57,6 +57,8 @@ import type {
TaskCreateResponse,
TraceAnalysisResponse,
TraceEventsResponse,
+ TraceImportRequest,
+ TraceImportResponse,
UiPrefs,
UsageGroupBy,
UsageResponse,
@@ -332,6 +334,23 @@ export const getAgentTraceAnalysis = (
`/traces/${encodeURIComponent(sessionId)}/${index}/analysis`,
);
+/** Trace file download URL: the server sets Content-Disposition attachment, usable directly in <a download>. */
+export const agentTraceDownloadUrl = (
+ projectId: string,
+ agentId: string,
+ sessionId: string,
+ index: number,
+): string =>
+ `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
+ `/traces/${encodeURIComponent(sessionId)}/${index}/download`;
+
+/** Imports a Trace JSONL file (owner only); the response says where the file landed (sessionId / index / date). */
+export const importAgentTrace = (projectId: string, agentId: string, body: TraceImportRequest) =>
+ apiFetch<TraceImportResponse>(
+ `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/traces/import`,
+ { method: "POST", body },
+ );
+
// Usage statistics ----------------------------------------------------------------------
export const getUsage = (
diff --git a/packages/web/src/components/ui/icons.tsx b/packages/web/src/components/ui/icons.tsx
index 00167f33..cf178057 100644
--- a/packages/web/src/components/ui/icons.tsx
+++ b/packages/web/src/components/ui/icons.tsx
@@ -70,6 +70,50 @@ export function PlusIcon({
);
}
+/** Download glyph (tray with a down arrow), used by export/download affordances. */
+export function DownloadIcon({ size = 13, className = "" }: { size?: number; className?: string }) {
+ return (
+ <svg
+ width={size}
+ height={size}
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ aria-hidden
+ className={`shrink-0 ${className}`}
+ >
+ <path
+ d="M12 4v11m0 0l-5-5m5 5l5-5M4 20h16"
+ strokeWidth="1.7"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+}
+
+/** Upload glyph (tray with an up arrow), used by import/upload affordances. */
+export function UploadIcon({ size = 13, className = "" }: { size?: number; className?: string }) {
+ return (
+ <svg
+ width={size}
+ height={size}
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ aria-hidden
+ className={`shrink-0 ${className}`}
+ >
+ <path
+ d="M12 15V4m0 0L7 9m5-5l5 5M4 20h16"
+ strokeWidth="1.7"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+}
+
/**
* The X close button shared by the Modal / Drawer / Sheet headers: same glyph,
* padding and hover treatment. Extra button props (e.g. Sheet's onPointerDown
diff --git a/packages/web/src/features/traces/traces-page.tsx b/packages/web/src/features/traces/traces-page.tsx
index 3659b482..ea07f1a6 100644
--- a/packages/web/src/features/traces/traces-page.tsx
+++ b/packages/web/src/features/traces/traces-page.tsx
@@ -6,6 +6,7 @@
* analysis (an execution timeline) + an event timeline.
*/
import { useEffect, useRef, useState } from "react";
+import type { ChangeEvent } from "react";
import { useSearchParams } from "react-router";
import type { AgentTracesResponse } from "@prismshadow/penguin-server/api";
import * as api from "../../api/endpoints";
@@ -16,6 +17,8 @@ import { formatBytes } from "../../lib/format";
import { agentDisplayName, useProject } from "../../state/project";
import { AgentAvatar } from "../../components/ui/agent-avatar";
import { Chevron } from "../../components/ui/chevron";
+import { DownloadIcon, UploadIcon } from "../../components/ui/icons";
+import { toastError } from "../../components/ui/toast";
import { Truncated } from "../../components/ui/truncated";
import { useSessions } from "../../state/sessions";
import { EmptyState } from "../../components/ui/empty-state";
@@ -23,6 +26,14 @@ import { SkeletonList } from "../../components/ui/skeleton";
import { TraceFileView } from "./trace-file-view";
import type { TraceHighlight } from "./timeline-chart";
+/**
+ * Import file size cap, mirroring the server's route-side limit (agent-traces.ts).
+ * Checked on the raw picked file before it is read: base64-encoding an oversized
+ * pick and uploading it just to receive the server's 400 would materialize and
+ * send many times the cap for nothing.
+ */
+const MAX_TRACE_BYTES = 14 * 1024 * 1024;
+
interface TraceFileRef {
index: number;
date: string;
@@ -67,6 +78,7 @@ function AgentNode({
name,
defaultOpen,
focusSessionId,
+ canImport,
titleOf,
selection,
onSelect,
@@ -78,6 +90,8 @@ function AgentNode({
defaultOpen: boolean;
/** ?sessionId= deep link (jumped to directly from the evaluation center's runs): auto-selects that Session once the list is ready (only once). */
focusSessionId?: string;
+ /** Trace import is owner-only on the server; non-owners don't get the button. */
+ canImport: boolean;
titleOf: (agentId: string, sessionId: string) => string | undefined;
selection: Selection | null;
onSelect: (sel: Selection) => void;
@@ -85,6 +99,9 @@ function AgentNode({
const [open, setOpen] = useState(defaultOpen);
const [groups, setGroups] = useState<SessionGroup[] | null>(null);
const [error, setError] = useState<string | null>(null);
+ const [importing, setImporting] = useState(false);
+ /** Session to auto-select once the refreshed list arrives (the import response's sessionId). */
+ const importedSession = useRef<string | null>(null);
useEffect(() => {
if (!open || groups) return;
@@ -106,6 +123,53 @@ function AgentNode({
if (target) onSelect({ agentId, sessionId: target.sessionId, files: target.files });
}, [groups, focusSessionId, agentId, onSelect]);
+ // Post-import selection: once the refreshed list is in, select the imported
+ // Session — an import always creates a new Session whose only file is the
+ // imported one, so the default file pick is the imported file.
+ useEffect(() => {
+ const sid = importedSession.current;
+ if (sid === null || !groups) return;
+ importedSession.current = null;
+ const target = groups.find((g) => g.sessionId === sid);
+ if (target) onSelect({ agentId, sessionId: target.sessionId, files: target.files });
+ }, [groups, agentId, onSelect]);
+
+ const runImport = async (dataBase64: string) => {
+ setImporting(true);
+ try {
+ const res = await api.importAgentTrace(projectId, agentId, { dataBase64 });
+ // Drop the cached list so the fetch effect above reloads it; the effect
+ // watching `groups` then jumps to the imported Session.
+ importedSession.current = res.sessionId;
+ setGroups(null);
+ setOpen(true);
+ } catch (e: unknown) {
+ // Transient action failure → toast (the app's one notification rule; a
+ // rejected import isn't a state of the tree, unlike the load error below).
+ toastError(apiErrorText(e));
+ } finally {
+ setImporting(false);
+ }
+ };
+
+ const onPickFile = (e: ChangeEvent<HTMLInputElement>) => {
+ const file = e.target.files?.[0];
+ // Reset before reading so re-picking the same file fires change again.
+ e.target.value = "";
+ if (!file) return;
+ if (file.size > MAX_TRACE_BYTES) {
+ toastError(S.traces.fileTooLarge);
+ return;
+ }
+ const reader = new FileReader();
+ reader.onload = () => {
+ const url = reader.result as string;
+ void runImport(url.slice(url.indexOf(",") + 1)); // strip the data:...;base64, prefix
+ };
+ reader.onerror = () => toastError(S.common.unknownError);
+ reader.readAsDataURL(file);
+ };
+
// The group header and Session row styling matches the sidebar
// (components/layout/sidebar.tsx): the same information appearing in two
// places with a different shape would make it look like two different things.
@@ -126,9 +190,29 @@ function AgentNode({
<Chevron open={open} size={12} className="text-gray-400" />
<span className="min-w-0 flex-1" />
</button>
+ {canImport && (
+ <label
+ title={importing ? S.traces.importing : S.traces.importTrace}
+ className={`shrink-0 cursor-pointer rounded p-1 text-gray-400 transition-colors duration-150 hover:bg-gray-200/50 hover:text-gray-600 dark:hover:bg-gray-800/50 dark:hover:text-gray-300 ${
+ importing ? "pointer-events-none opacity-60" : ""
+ }`}
+ >
+ {/* sr-only rather than hidden: keeps it keyboard-Tab-focusable (same as the snapshot import). */}
+ <input
+ type="file"
+ accept=".jsonl"
+ className="sr-only"
+ disabled={importing}
+ onChange={onPickFile}
+ />
+ <UploadIcon size={13} />
+ <span className="sr-only">{importing ? S.traces.importing : S.traces.importTrace}</span>
+ </label>
+ )}
</div>
{open && (
<div className="anim-fade">
+ {/* Load failure of the tree itself stays inline (the one-notification-rule keeps load states with their content, not in a disappearing toast). */}
{error && <p className="px-2.5 py-1 text-xs text-red-500">{error}</p>}
{!groups && !error && (
<p className="px-2.5 py-1 text-xs text-gray-400">{S.common.loading}</p>
@@ -232,6 +316,7 @@ export function TracesPage() {
{...(focusSessionId !== null && focusAgentId === a.agentId
? { focusSessionId }
: {})}
+ canImport={currentProject?.role === "owner"}
titleOf={titleOf}
selection={selection}
onSelect={(sel) => {
@@ -275,9 +360,25 @@ export function TracesPage() {
))}
</div>
</div>
- <p className="truncate font-mono text-xs text-gray-400">
- {selection.sessionId} · {activeFile.date} · {formatBytes(activeFile.sizeBytes)}
- </p>
+ <div className="flex flex-wrap items-center gap-2">
+ <p className="min-w-0 flex-1 truncate font-mono text-xs text-gray-400">
+ {selection.sessionId} · {activeFile.date} · {formatBytes(activeFile.sizeBytes)}
+ </p>
+ {/* Raw-file download for the selected Trace file (same styling as the inactive file pills). */}
+ <a
+ href={api.agentTraceDownloadUrl(
+ projectId,
+ selection.agentId,
+ selection.sessionId,
+ activeFile.index,
+ )}
+ download
+ className="inline-flex shrink-0 items-center gap-1 rounded-md border border-gray-200 px-2 py-0.5 text-xs text-gray-500 transition-colors duration-150 hover:bg-gray-100 dark:border-gray-800 dark:text-gray-400 dark:hover:bg-gray-800/60"
+ >
+ <DownloadIcon size={12} />
+ {S.traces.exportFile}
+ </a>
+ </div>
<TraceFileView
projectId={projectId}
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index a9accd7e..42e85466 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -846,6 +846,11 @@ When done, open index.html in a browser and self-test once.`,
inProgress: "in progress",
systemPrompt: "System prompt",
toolDefs: (n: number) => `Tool definitions (${n})`,
+ exportFile: "Export",
+ importTrace: "Import Trace",
+ importing: "Importing…",
+ /** Client-side pre-check before reading the picked file (same cap as the server's import route). */
+ fileTooLarge: "The file exceeds the 14MB limit.",
},
benchmark: {
@@ -899,6 +904,9 @@ When done, open index.html in a browser and self-test once.`,
task_in_progress: "This Session already has a task running.",
version_conflict: "The snapshot's version is not newer than the current one.",
invalid_title: "The title is invalid.",
+ invalid_trace: "This file is not a valid Trace file.",
+ trace_session_exists:
+ "This agent already has a Session with that id; a duplicate Trace cannot be imported.",
},
},
};
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 796ad946..e2c2821e 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -825,6 +825,11 @@ Penguin 视觉风格(见 web-design 技能),深色/浅色主题(<html da
inProgress: "进行中",
systemPrompt: "系统提示词",
toolDefs: (n: number) => `工具定义(${n})`,
+ exportFile: "导出",
+ importTrace: "导入 Trace",
+ importing: "导入中…",
+ /** Client-side pre-check before reading the picked file (same cap as the server's import route). */
+ fileTooLarge: "文件超过 14MB 上限。",
},
benchmark: {
@@ -882,6 +887,8 @@ Penguin 视觉风格(见 web-design 技能),深色/浅色主题(<html da
task_in_progress: "该 Session 已有任务在运行。",
version_conflict: "快照版本不高于当前版本。",
invalid_title: "标题无效。",
+ invalid_trace: "该文件不是有效的 Trace 文件。",
+ trace_session_exists: "该 Agent 已存在同名 Session,无法导入重复的 Trace。",
},
},
};