feat(server,web): import and export Trace files in the trace viewer (#73)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Yaowei Zheng
@@ -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
|
||||
|
||||
|
||||
@@ -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 级接口
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 号文件。
|
||||
|
||||
@@ -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
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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 };
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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 = (
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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}
|
||||
|
||||
@@ -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.",
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
@@ -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。",
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user