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.mdindex 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 Endpointsdiff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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 onPointerDowndiff --git a/packages/web/src/features/traces/traces-page.tsx b/packages/web/src/features/traces/traces-page.tsxindex 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><TraceFileViewprojectId={projectId}diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.tsindex 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.tsindex 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 dainProgress: "进行中",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 datask_in_progress: "该 Session 已有任务在运行。",version_conflict: "快照版本不高于当前版本。",invalid_title: "标题无效。",+ invalid_trace: "该文件不是有效的 Trace 文件。",+ trace_session_exists: "该 Agent 已存在同名 Session,无法导入重复的 Trace。",},},};