A local-first multi-agent app development platform, built on PenguinHarness
/**
* Unit tests for the Trace service: multi-file history concatenation, file
* listing, pagination (following a growing file), performance-analysis derivation
* (including the head's context window), and Agent-level drill-down browsing.
*/
import fs from "node:fs/promises";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
DEEPSEEK_OFF_PEAK,
abortEvent,
approvalDecision,
assistantText,
buildBackgroundTaskDoneMessage,
catalogEntryFor,
compactionBegin,
compactionEnd,
imageUrlMessage,
mcpConnectBegin,
mcpConnectEnd,
offPeakAt,
requestBegin,
requestEnd,
sessionMeta,
thinkingMessage,
tokenUsage,
toolCall,
toolCallOutput,
userText,
withOrigin,
} from "@adelie/core";
import type { OmniMessage, SessionMetaPayload, TokenCounts, StopReason } from "@adelie/core";
// Traces written before the stop-reason convergence carry the retired spellings; analysis
// must keep reading them, so these fixtures write them through a cast.
const legacyEnd = (status: string) => requestEnd(status as StopReason);
import type { TraceService } from "../src/services/trace-service.js";
import type { SessionRow } from "../src/db/repos/sessions.js";
import { openDatabase } from "../src/db/database.js";
import { wire } from "@adelie/core/kernel";
import { ErrorsRepo } from "../src/db/repos/errors.js";
import { UsageRepo } from "../src/db/repos/usage.js";
import { SessionSources } from "../src/runtime/session-sources.js";
import { UsageRecorder } from "../src/runtime/usage-recorder.js";
import { UsageService, requestCostUsd } from "../src/services/usage-service.js";
import type { PricingLookup } from "../src/services/usage-service.js";
import { makeTempRoot, makeTraceHarness, writeTraceFile } from "./helpers.js";
const P = "project-t";
const A = "agent-t";
const S = "session-2026-07-05-10-00-00-aabbccdd";
function at(ts: string, msg: OmniMessage): OmniMessage {
return { ...msg, timestamp: ts };
}
function counts(total: number): TokenCounts {
return { cache_read: 0, cache_write: 0, output: 0, total };
}
/** Request usage with real three-bucket counts (both the context snapshot and the TPS numerator are derived from this). */
function buckets(cacheRead: number, cacheWrite: number, output: number): TokenCounts {
return {
cache_read: cacheRead,
cache_write: cacheWrite,
output,
total: cacheRead + cacheWrite + output,
};
}
function metaPayload(over: Partial<SessionMetaPayload> = {}): SessionMetaPayload {
return {
session_id: S,
model_id: "m1",
provider: "custom",
model_context_window: 1000,
system_prompt: "sp",
agent_state: "/tmp/a",
workspace: "/tmp/w",
source: "user",
...over,
};
}
/** A sessions-table row for the paginated listing's index fake (only the listing-relevant fields vary per test). */
function dbRow(over: Partial<SessionRow> & { sessionId: string }): SessionRow {
return {
projectId: P,
agentId: A,
provider: "custom",
modelId: "m1",
workspace: "/tmp/w",
approvalMode: "allow-all",
title: null,
createdAt: "2026-07-05T10:00:00.000Z",
lastActiveAt: "2026-07-05T10:00:00.000Z",
...over,
};
}
describe("trace-service", () => {
let root: string;
let service: TraceService;
let harness: ReturnType<typeof makeTraceHarness>;
beforeEach(async () => {
root = await makeTempRoot();
harness = makeTraceHarness(root);
service = harness.service;
});
afterEach(async () => {
harness.close();
await fs.rm(root, { recursive: true, force: true });
});
it("messages: all index files concatenated in order (across date directories)", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
userText("first file"),
]);
await writeTraceFile(root, P, A, "2026-07-06", S, 2, [
sessionMeta(metaPayload()),
userText("second file"),
]);
const messages = await service.readMessages(P, A, S);
expect(messages).toHaveLength(4);
expect((messages[1]!.payload as { text: string }).text).toBe("first file");
expect((messages[3]!.payload as { text: string }).text).toBe("second file");
});
it("messages: tolerates a truncated last line", async () => {
const file = await writeTraceFile(root, P, A, "2026-07-05", S, 1, [userText("ok")]);
await fs.appendFile(file, '{"timestamp":"2026', "utf8");
const messages = await service.readMessages(P, A, S);
expect(messages).toHaveLength(1);
});
it("traces listing: index / date / size / mtime", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [userText("a")]);
await writeTraceFile(root, P, A, "2026-07-06", S, 2, [userText("bb")]);
const files = await service.listTraceFiles(P, A, S);
expect(files.map((f) => f.index)).toEqual([1, 2]);
expect(files[0]!.date).toBe("2026-07-05");
expect(files[0]!.sizeBytes).toBeGreaterThan(0);
expect(Date.parse(files[0]!.mtime)).not.toBeNaN();
});
it("paginated line reads: offset/limit and total", async () => {
const messages = Array.from({ length: 10 }, (_, i) => userText(`m${i}`));
await writeTraceFile(root, P, A, "2026-07-05", S, 1, messages);
const page = await service.readEvents(P, A, S, 1, 3, 4);
expect(page.total).toBe(10);
expect(page.offset).toBe(3);
expect(page.events).toHaveLength(4);
expect((page.events[0]!.payload as { text: string }).text).toBe("m3");
const notFound = await service.readEvents(P, A, S, 99, 0, 10).catch((e: unknown) => e);
expect((notFound as { status: number }).status).toBe(404);
});
it("paginated line reads follow a file the running Task appends to", async () => {
const file = await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
userText("m0"),
userText("m1"),
]);
expect((await service.readEvents(P, A, S, 1, 0, 10)).total).toBe(2);
await fs.appendFile(file, `${JSON.stringify(userText("m2"))}\n`, "utf8");
const grown = await service.readEvents(P, A, S, 1, 1, 10);
expect(grown.total).toBe(3);
expect(grown.events.map((e) => (e.payload as { text: string }).text)).toEqual(["m1", "m2"]);
});
it("the analysis carries the context window its file's head names, and none when the head names none", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload({ model_context_window: 200_000 })),
userText("hi"),
]);
await writeTraceFile(root, P, A, "2026-07-05", S, 2, [userText("no head")]);
expect((await service.analyze(P, A, S, 1)).modelContextWindow).toBe(200_000);
expect((await service.analyze(P, A, S, 2)).modelContextWindow).toBeUndefined();
});
it("performance analysis: Request pairing, tool durations, reconnect / compaction counts, Token trend", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:03.000Z", requestEnd("retryable")), // reconnect +1
at("2026-07-05T10:00:03.500Z", requestBegin()),
at(
"2026-07-05T10:00:04.000Z",
toolCall({ name: "exec_command", arguments: "{}", toolCallId: "tc-1" }),
),
at("2026-07-05T10:00:05.000Z", requestEnd("completed")),
at("2026-07-05T10:00:06.500Z", toolCallOutput({ output: "done", toolCallId: "tc-1" })),
at("2026-07-05T10:00:07.000Z", tokenUsage(counts(1000), counts(400))),
at(
"2026-07-05T10:00:08.000Z",
compactionBegin({ reason: "manual", mode: "summarize", context: 400, turns: 2 }),
),
at(
"2026-07-05T10:00:09.000Z",
compactionEnd({ reason: "manual", mode: "summarize", status: "aborted" }),
),
at("2026-07-05T10:00:10.000Z", abortEvent()),
at("2026-07-05T10:00:11.000Z", requestBegin()), // unclosed (process exited)
]);
const analysis = await service.analyze(P, A, S, 1);
expect(analysis.requests).toHaveLength(3);
expect(analysis.requests[0]!.status).toBe("retryable");
expect(analysis.requests[0]!.durationMs).toBe(2000);
expect(analysis.requests[1]!.status).toBe("completed");
expect(analysis.requests[1]!.durationMs).toBe(1500);
expect(analysis.requests[2]!.endTs).toBeUndefined();
// A timeout is auto-reconnected by core within the same run, so the resent
// Request still belongs to **the same user turn**: req0(timeout) and
// req1(retry succeeded) are both Task 0 — they must not be split into two
// turns. Compaction interrupts continuation, so req2 starts a new turn.
expect(analysis.requests.map((r) => r.taskIndex)).toEqual([0, 0, 1]);
expect(analysis.toolCalls).toHaveLength(1);
expect(analysis.toolCalls[0]!.name).toBe("exec_command");
expect(analysis.toolCalls[0]!.durationMs).toBe(2500);
expect(analysis.toolCalls[0]!.stopReason).toBe("completed");
expect(analysis.reconnectCount).toBe(1);
expect(analysis.compactionCount).toBe(1);
expect(analysis.usageTrend).toEqual([
{ ts: "2026-07-05T10:00:07.000Z", requestTotal: 400, sessionTotal: 1000 },
]);
});
/** One completed text turn: Prompt, one Request, and its usage stamped at `ts` plus three seconds. */
const priceTurn = (ts: string, request: TokenCounts): OmniMessage[] => {
const t = Date.parse(ts);
const plus = (s: number) => new Date(t + s * 1000).toISOString();
return [
at(ts, userText("go")),
at(plus(1), requestBegin()),
at(plus(2), assistantText("ok")),
at(plus(3), requestEnd("completed")),
at(plus(3), tokenUsage(request, request)),
];
};
it("prices each Request at the tier its own timestamp ran in, and the file adds up to what the cost center fixed for the same rows", async () => {
// A DeepSeek reference still storing the catalog's peak price bills by the catalog's
// Beijing-hours schedule, so the lookup answers as project-config-service does for such a
// row: the peak rate inside the windows, half of it outside, for the instant it is asked for.
const REF = { provider: "deepseek", model_id: "deepseek-flash" };
const peak = catalogEntryFor(REF.provider, REF.model_id)!.pricing!;
const stored = {
cacheRead: peak.cache_read,
cacheWrite: peak.cache_write,
output: peak.output,
};
const half = (v: number): number => Math.round(v * 0.5 * 1e6) / 1e6;
const offPeakRates = {
cacheRead: half(stored.cacheRead),
cacheWrite: half(stored.cacheWrite),
output: half(stored.output),
};
const lookups: string[] = [];
const lookup: PricingLookup = async (projectId, provider, modelId, at) => {
lookups.push(`${projectId}/${provider}/${modelId}@${at.toISOString()}`);
return offPeakAt(DEEPSEEK_OFF_PEAK, at) ? offPeakRates : stored;
};
const priced = makeTraceHarness(root, { lookupPricing: lookup });
const usage = buckets(10, 1, 5);
const counts = { cacheRead: 10, cacheWrite: 1, output: 5 };
// Tuesday 10:30 Beijing (peak), Tuesday 21:00 Beijing (off-peak), Sunday 11:00 Beijing (an
// hour a weekday bills at peak, off-peak on a weekend) and ten minutes after that last one,
// which must share its lookup rather than read the Project's config again.
const stamps = [
"2026-07-07T02:30:00.000Z",
"2026-07-07T13:00:00.000Z",
"2026-07-12T03:00:00.000Z",
"2026-07-12T03:10:00.000Z",
];
/** The instant a turn's usage is stamped at: its request plus the three seconds of `priceTurn`. */
const usageAt = (ts: string): string => new Date(Date.parse(ts) + 3000).toISOString();
try {
await writeTraceFile(root, P, A, "2026-07-07", S, 1, [
sessionMeta(metaPayload(REF)),
...stamps.flatMap((ts) => priceTurn(ts, usage)),
]);
const a = await priced.service.analyze(P, A, S, 1);
const peakCost = requestCostUsd(counts, stored);
const offPeakCost = requestCostUsd(counts, offPeakRates);
expect(offPeakCost).toBeLessThan(peakCost);
expect(a.tasks.map((t) => t.cost)).toEqual([peakCost, offPeakCost, offPeakCost, offPeakCost]);
expect(a.cost).toBeCloseTo(peakCost + offPeakCost * 3, 12);
// One lookup per hour a Trace spans, not one per Request: the four stamps fall in three
// hours (two of them off-peak for different reasons), and each is asked for at its own
// instant.
expect(lookups).toEqual([
`${P}/deepseek/deepseek-flash@${usageAt(stamps[0]!)}`,
`${P}/deepseek/deepseek-flash@${usageAt(stamps[1]!)}`,
`${P}/deepseek/deepseek-flash@${usageAt(stamps[2]!)}`,
]);
// The same Requests as the recorder fixes them — each priced at its own completion,
// from the same lookup — summed by the cost center's session grouping (the figure the
// conversation toolbar shows) land on the file's total.
const db = openDatabase(":memory:");
try {
const rows = wire(UsageRepo, { db });
for (const ts of stamps) {
const done = new Date(Date.parse(ts) + 3000);
const event = tokenUsage(usage, usage);
const recorder = wire(UsageRecorder, {
usage: rows,
clock: { now: () => done },
lookupPricing: lookup,
});
await recorder.record(
{
projectId: P,
agentId: A,
sessionId: S,
provider: REF.provider,
modelId: REF.model_id,
},
event,
);
}
const center = wire(UsageService, {
usage: rows,
errors: wire(ErrorsRepo, { db }),
lookupPricing: lookup,
clock: { now: () => new Date() },
});
const res = await center.query(P, { groupBy: "session" });
expect(res.groups.find((g) => g.key === S)?.cost).toBeCloseTo(a.cost!, 12);
} finally {
db.close();
}
} finally {
priced.close();
}
});
it("a model with no schedule bills every hour at its one rate; no pricing, or a head naming no provider, means no cost at all", async () => {
const lookups: string[] = [];
const priced = makeTraceHarness(root, {
lookupPricing: async (_projectId, provider, modelId) => {
lookups.push(`${provider}/${modelId}`);
return modelId === "m1" ? { cacheRead: 1, cacheWrite: 1, output: 1 } : undefined;
},
});
try {
// Sunday 11:00 Beijing: off-peak for a scheduled model, just an hour for this one.
await writeTraceFile(root, P, A, "2026-07-12", S, 1, [
sessionMeta(metaPayload()),
...priceTurn("2026-07-12T03:00:00.000Z", buckets(10, 1, 5)),
at("2026-07-12T03:01:00.000Z", userText("interrupted before any request")),
]);
const flat = await priced.service.analyze(P, A, S, 1);
expect(flat.tasks.map((t) => t.cost)).toEqual([(10 + 1 + 5) / 1e6, 0]);
expect(flat.cost).toBeCloseTo((10 + 1 + 5) / 1e6, 12);
await writeTraceFile(root, P, A, "2026-07-12", S, 2, [
sessionMeta(metaPayload({ model_id: "m-unpriced" })),
...priceTurn("2026-07-12T03:10:00.000Z", buckets(10, 1, 5)),
]);
const unpriced = await priced.service.analyze(P, A, S, 2);
expect(unpriced.tasks.map((t) => t.cost)).toEqual([undefined]);
expect(unpriced.cost).toBeUndefined();
const legacy = metaPayload({ model_id: "m1" }) as Partial<SessionMetaPayload>;
delete legacy.provider;
await writeTraceFile(root, P, A, "2026-07-12", S, 3, [
sessionMeta(legacy as SessionMetaPayload),
...priceTurn("2026-07-12T03:20:00.000Z", buckets(10, 1, 5)),
]);
const noProvider = await priced.service.analyze(P, A, S, 3);
expect(noProvider.cost).toBeUndefined();
expect(lookups).toEqual(["custom/m1", "custom/m-unpriced"]);
} finally {
priced.close();
}
// The default harness has no lookup: nothing is priced.
const plain = await service.analyze(P, A, S, 1);
expect(plain.cost).toBeUndefined();
expect(plain.tasks.every((t) => t.cost === undefined)).toBe(true);
});
it("the Task context snapshot takes the turn's last Request, not a sum across its Requests", async () => {
// Two Requests within one Task (a tool call triggers another round): each
// input **re-carries the entire history**, so 60k → 65k is the context
// growing, not a 60k + 65k = 125k sum of usage. Summing them would double-count
// the context — a few rounds of tool calls would blow the context window past
// 100% and overflow the ring.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at(
"2026-07-05T10:00:02.000Z",
toolCall({ name: "exec_command", arguments: "{}", toolCallId: "tc-1" }),
),
at("2026-07-05T10:00:03.000Z", requestEnd("completed")),
at("2026-07-05T10:00:03.100Z", tokenUsage(counts(60_000), buckets(50_000, 8_000, 2_000))),
at("2026-07-05T10:00:03.500Z", toolCallOutput({ output: "ok", toolCallId: "tc-1" })),
// Continuation round (same Task): context grows to 65k
at("2026-07-05T10:00:04.000Z", requestBegin()),
at("2026-07-05T10:00:06.000Z", requestEnd("completed")),
at("2026-07-05T10:00:06.100Z", tokenUsage(counts(65_000), buckets(58_000, 4_000, 3_000))),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0]); // tool call → continues the same Task
expect(a.tasks).toHaveLength(1);
const t = a.tasks[0]!;
// Snapshot = the last Request (58k/4k/3k = 65k), not the sum of both (108k/12k/5k = 125k).
expect(t.context).toEqual({ cacheRead: 58_000, cacheWrite: 4_000, output: 3_000 });
// The running total (used for Token/cost, with output doubling as the TPS
// numerator) IS summed: the three-bucket sum across both Requests. It and the
// snapshot above are two different measures — the frontend used to feed the
// running total into the ring as if it were the snapshot, which is how "two
// rounds of 60k/65k" ended up displaying as 125k.
expect(t.tokens).toEqual({ cacheRead: 108_000, cacheWrite: 12_000, output: 5_000 });
expect(t.llmMs).toBe(2000 + 2000);
});
it("human approval waits don't count toward LLM generation time (the TPS denominator)", async () => {
// core does `await approve(tc)` inside the streaming loop: until approval
// returns, the next chunk isn't consumed and request_end can't fire, so the
// entire human wait sits between request_begin and request_end. Without
// subtracting it, "2s of generation + 30s of approval wait" would drop the
// TPS to a fifteenth of the real value.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at(
"2026-07-05T10:00:02.000Z",
toolCall({ name: "exec_command", arguments: "{}", toolCallId: "tc-1" }),
),
at("2026-07-05T10:00:32.000Z", approvalDecision("allow", "tc-1")), // human left it hanging for 30s
at("2026-07-05T10:00:33.000Z", requestEnd("completed")),
at("2026-07-05T10:00:33.100Z", tokenUsage(counts(1000), buckets(0, 0, 1_000))),
]);
const a = await service.analyze(P, A, S, 1);
const rq = a.requests[0]!;
expect(rq.durationMs).toBe(32_000); // wall clock: includes the approval wait
expect(rq.approvalWaitMs).toBe(30_000);
expect(rq.activeMs).toBe(2_000); // generation: 1s→2s (emits tool_call) + 32s→33s (wrap-up)
expect(a.tasks[0]!.llmMs).toBe(2_000); // the denominator uses only activeMs
expect(a.tasks[0]!.tokens.output).toBe(1_000); // → 500 tok/s, not 31 tok/s
});
it("splits a turn's duration into API time and tool wall time, counting parallel tools once", async () => {
// Two tools run concurrently: 10:00:03→10:00:09 and 10:00:04→10:00:11. Summing their
// durations would claim 13s of tool work; the clock only ever spent 8s (03→11), which is
// what "wall time" has to mean once tools can overlap.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at(
"2026-07-05T10:00:02.000Z",
toolCall({ name: "exec_command", arguments: "{}", toolCallId: "tc-1" }),
),
at(
"2026-07-05T10:00:02.000Z",
toolCall({ name: "read_file", arguments: "{}", toolCallId: "tc-2" }),
),
// Approvals land inside the Request span (core awaits them in the streaming loop), so the
// waits come off API time; execution then starts at each approval, not at the call.
at("2026-07-05T10:00:03.000Z", approvalDecision("allow", "tc-1")),
at("2026-07-05T10:00:04.000Z", approvalDecision("allow", "tc-2")),
at("2026-07-05T10:00:05.000Z", requestEnd("completed")),
at("2026-07-05T10:00:09.000Z", toolCallOutput({ output: "a", toolCallId: "tc-1" })),
at("2026-07-05T10:00:11.000Z", toolCallOutput({ output: "b", toolCallId: "tc-2" })),
at("2026-07-05T10:00:11.000Z", requestBegin()),
at("2026-07-05T10:00:13.000Z", requestEnd("completed")),
at("2026-07-05T10:00:13.100Z", tokenUsage(counts(1000), buckets(0, 0, 1_000))),
]);
const a = await service.analyze(P, A, S, 1);
const t = a.tasks[0]!;
// API: 01→05 minus the two approval waits (1s + 2s), plus 11→13.
expect(t.llmMs).toBe(1_000 + 2_000);
// Tools: the union of [03,09] and [04,11] — 8s, not the 6s + 7s the two spans add up to.
expect(t.toolMs).toBe(8_000);
// The components are measurements, not a partition: here they overlap nothing, but they
// still fall short of the turn's span, which also covers the gap the harness spent.
expect(t.llmMs + t.toolMs).toBeLessThanOrEqual(a.elapsedMs);
// The file-wide figures are the sum of the per-turn ones, exactly as elapsedMs is.
expect(a.apiMs).toBe(a.tasks.reduce((sum, x) => sum + x.llmMs, 0));
expect(a.toolMs).toBe(a.tasks.reduce((sum, x) => sum + x.toolMs, 0));
});
it("a tool still running when the trace ends contributes no tool time", async () => {
// No tool_call_output ever arrives: the execution has no measured end, and extrapolating it
// to "now" would grow a finished file's figures every time it is read.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at(
"2026-07-05T10:00:02.000Z",
toolCall({ name: "exec_command", arguments: "{}", toolCallId: "tc-1" }),
),
at("2026-07-05T10:00:03.000Z", requestEnd("completed")),
at("2026-07-05T10:00:03.100Z", tokenUsage(counts(1000), buckets(0, 0, 1_000))),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.tasks[0]!.toolMs).toBe(0);
expect(a.toolMs).toBe(0);
expect(a.tasks[0]!.llmMs).toBe(2_000);
});
it("compaction is its own turn: its TPS is its own and doesn't pollute user turns; the context snapshot still takes only non-compaction Requests", async () => {
// Compaction's request_begin/end and token_usage all sit between
// compaction_begin and compaction_end (see core's context-engine summarize
// flow). Both sides of the Chat page exclude compaction, so Trace must use
// the same accounting, or the two pages would compute different TPS for the
// same Session.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:03.000Z", requestEnd("completed")),
at("2026-07-05T10:00:03.100Z", tokenUsage(counts(30_000), buckets(20_000, 9_000, 1_000))),
at(
"2026-07-05T10:00:04.000Z",
compactionBegin({ reason: "context", mode: "summarize", context: 30_000, turns: 2 }),
),
at("2026-07-05T10:00:05.000Z", requestBegin()), // the compaction request
at("2026-07-05T10:00:15.000Z", requestEnd("completed")), // slow: 10s
at("2026-07-05T10:00:15.100Z", tokenUsage(counts(32_000), buckets(29_000, 0, 3_000))),
at(
"2026-07-05T10:00:16.000Z",
compactionEnd({ reason: "context", mode: "summarize", status: "completed" }),
),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.requests[1]!.compaction).toBe(true);
expect(a.requests[0]!.compaction).toBeUndefined();
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// User turn: TPS counts only its own Request — none of the compaction's 3k output or 10s of generation time bleeds in.
const t = a.tasks[0]!;
expect(t.context).toEqual({ cacheRead: 20_000, cacheWrite: 9_000, output: 1_000 });
expect(t.tokens.output).toBe(1_000);
expect(t.llmMs).toBe(2_000);
// The compaction turn: it IS **a turn**, with its own TPS (how fast the summary was generated) — it shouldn't be blanked out as "—".
const ct = a.tasks[1]!;
expect(ct.llmMs).toBe(10_000);
// But it has no context snapshot: the tokens compaction consumes aren't the
// post-compaction context size (the frontend uses this to skip drawing a ring for the compaction turn).
expect(ct.context).toBeUndefined();
// The running total is still recorded (output also serves as the compaction
// turn's own TPS numerator): compaction's tokens are genuinely paid for, so the cost must not be dropped.
expect(ct.tokens).toEqual({ cacheRead: 29_000, cacheWrite: 0, output: 3_000 });
// The compaction turn is flagged (the UI shows a "compaction" badge); its
// duration is measured from its request_begin (10:00:05) to compaction_end (10:00:16).
expect(ct.compaction).toBe(true);
// ...and carries WHICH compaction it was, so the round card can name the operation rather
// than calling every mode "compaction". The flag stays the sole gate on "is this a
// compaction turn", so a client that only knows the boolean is unaffected.
expect(ct.compactionMode).toBe("summarize");
expect(t.compaction).toBeUndefined();
expect(t.compactionMode).toBeUndefined();
expect(Date.parse(ct.endTs) - Date.parse(ct.startTs)).toBe(11_000);
// Overall elapsed time = **the sum of every turn (including compaction turns)**,
// matching the same scope as the per-turn display — adding up the durations
// shown on each turn's card must equal the total. User turn 2.1s (request_begin
// 10:00:01 → token_usage 10:00:03.1) + compaction turn 11s.
expect(Date.parse(t.endTs) - Date.parse(t.startTs)).toBe(2_100);
expect(a.elapsedMs).toBe(2_100 + 11_000);
});
it("a discard compaction turn is flagged and carries mode 'discard', though it issues no request", async () => {
// `discard` drops the old context outright instead of summarizing it, and core emits
// compaction_begin/compaction_end back-to-back with **no request in between** (see
// context-engine's discardContext). It still forms its own turn — so the round card must
// be flagged from the compaction_begin itself, not from a compaction request that never
// happens, or a discarded round renders as a bare unlabelled card with no stats.
await writeTraceFile(root, P, A, "2026-07-06", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-06T10:00:00.000Z", userText("hi")),
at("2026-07-06T10:00:01.000Z", requestBegin()),
at("2026-07-06T10:00:03.000Z", requestEnd("completed")),
at("2026-07-06T10:00:03.100Z", tokenUsage(counts(30_000), buckets(20_000, 9_000, 1_000))),
at(
"2026-07-06T10:00:04.000Z",
compactionBegin({ reason: "context", mode: "discard", context: 30_000, turns: 2 }),
),
at(
"2026-07-06T10:00:04.100Z",
compactionEnd({ reason: "context", mode: "discard", status: "completed" }),
),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.compactionCount).toBe(1);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// The user turn is untouched...
expect(a.tasks[0]!.compaction).toBeUndefined();
expect(a.tasks[0]!.compactionMode).toBeUndefined();
// ...and the discard turn is flagged and named, so the badge reads "clear", not "compaction".
const ct = a.tasks[1]!;
expect(ct.compaction).toBe(true);
expect(ct.compactionMode).toBe("discard");
// It really did run no request: no duration to report, which is exactly why the badge is
// the only thing on the card that explains what the round was.
expect(ct.startTs).toBe("");
expect(ct.llmMs).toBe(0);
});
it("a compaction request exhausting retries (ending in timeout) doesn't fold the next user turn into the compaction Task", async () => {
// The intersection of "timeout → continuation" and "compaction is its own
// turn": when a compaction request exhausts its retries and ends in timeout,
// it would be classified as continuing; compaction_end must clear that
// continuation flag, or the user turn after compaction would be folded into
// the compaction Task.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
at("2026-07-05T10:00:00.000Z", userText("hi")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", requestEnd("completed")),
at("2026-07-05T10:00:02.100Z", tokenUsage(counts(1000), buckets(0, 0, 500))),
at(
"2026-07-05T10:00:03.000Z",
compactionBegin({ reason: "context", mode: "summarize", context: 1000, turns: 1 }),
),
at("2026-07-05T10:00:04.000Z", requestBegin()), // the compaction request
at("2026-07-05T10:00:05.000Z", requestEnd("retryable")), // retries exhausted
at(
"2026-07-05T10:00:06.000Z",
compactionEnd({ reason: "context", mode: "summarize", status: "aborted" }),
),
at("2026-07-05T10:00:07.000Z", userText("next turn")),
at("2026-07-05T10:00:08.000Z", requestBegin()),
at("2026-07-05T10:00:10.000Z", requestEnd("completed")),
at("2026-07-05T10:00:10.100Z", tokenUsage(counts(1200), buckets(0, 0, 700))),
]);
const a = await service.analyze(P, A, S, 1);
// Task 0 = the first turn; Task 1 = compaction (its own turn); Task 2 = the
// user turn after compaction, which must not be folded into Task 1.
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 1, 2]);
// The compaction turn is also in the list (it has a start/end time and token
// cost, just no TPS or context snapshot) — if the table were built only from
// turns with "model output or a tool call", this kind of turn would disappear
// entirely and its events would get folded into the previous turn.
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1, 2]);
expect(a.tasks[1]!.tokens.output).toBe(0); // the compaction request timed out, producing nothing
expect(a.tasks[1]!.context).toBeUndefined();
expect(a.tasks[2]!.tokens.output).toBe(700);
});
it("the user Prompt joins this turn's message range, but duration starts at the first request_begin; empty turns still make the list", async () => {
// Message **attribution** (messageFrom/To) and **duration** (startTs/endTs)
// are two different things: the Prompt belongs to this turn's message range
// (the frontend uses this to list it on this turn's card), but the duration
// only looks at the LLM request — the start point is the first request_begin,
// and the user text's timestamp doesn't participate (the compaction summary
// `[context_summary]` is created during compaction but only persisted on the
// next run; using it as the start point would stretch the first turn out for
// no reason). Also, if the turn list were built only from turns with "a model
// segment or a tool span", a turn that fails outright with no output at all
// would disappear entirely, and its events would get folded into the previous
// turn — this must be backstopped by the server-side tasks logic too.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("question one")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", requestEnd("completed")),
at("2026-07-05T10:00:02.100Z", tokenUsage(counts(1000), buckets(0, 900, 100))),
// Second turn: the Prompt precedes the Request; this turn's request fails outright, with no model output or tool call at all.
at("2026-07-05T10:01:00.000Z", userText("question two")),
at("2026-07-05T10:01:01.000Z", requestBegin()),
at("2026-07-05T10:01:04.000Z", requestEnd("retryable")),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]); // the empty turn is present too
// Message attribution: starting from "question two" (index 5), it belongs to the second turn, not the tail of the previous one.
expect(a.tasks[0]!.messageTo).toBe(4);
expect(a.tasks[1]!.messageFrom).toBe(5);
// Duration start = request_begin (10:01:01), not the Prompt (10:01:00).
expect(a.tasks[1]!.startTs).toBe("2026-07-05T10:01:01.000Z");
expect(a.tasks[1]!.endTs).toBe("2026-07-05T10:01:04.000Z");
expect(a.tasks[1]!.tokens.output).toBe(0); // nothing was produced
expect(a.tasks[0]!.startTs).toBe("2026-07-05T10:00:01.000Z");
// Overall elapsed time = **the sum of each turn's duration**, not "last minus
// first": this example spans 64s overall, but 58s of that is the gap between
// turns where the user was thinking/away — not time the Agent spent working.
// Turn 0 = 1.1s, turn 1 = 3s, total 4.1s.
expect(Date.parse(a.tasks[0]!.endTs) - Date.parse(a.tasks[0]!.startTs)).toBe(1_100);
expect(Date.parse(a.tasks[1]!.endTs) - Date.parse(a.tasks[1]!.startTs)).toBe(3_000);
expect(a.elapsedMs).toBe(4_100);
});
it("a legacy-trace `failed` request the engine retried stays inside the same turn (reconnect, not a turn end)", async () => {
// Traces from the pre-convergence era spell a retried request `failed`; segmentation
// must keep reading it as a reconnect, or one gateway blip would split a single turn's
// Tokens, duration and TPS across two Tasks and inflate the Task count.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("question one")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", legacyEnd("failed")), // a gateway error → that era's engine reconnected
at("2026-07-05T10:00:03.000Z", requestBegin()),
at("2026-07-05T10:00:05.000Z", requestEnd("completed")),
at("2026-07-05T10:00:05.100Z", tokenUsage(counts(1000), buckets(0, 900, 100))),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0]); // one turn, two Requests
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0]);
expect(a.reconnectCount).toBe(1);
expect(a.tasks[0]!.tokens.output).toBe(100);
});
it("a legacy-trace `failed` compaction request is NOT a reconnect: that era failed fast on it", async () => {
// Legacy segmentation nuance: the pre-convergence turn loop retried `failed`, its
// compaction loop deliberately did not. Counting the give-up as a reconnect would
// invent an attempt that never happened in that Trace.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("question one")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", requestEnd("completed")),
at("2026-07-05T10:00:02.100Z", tokenUsage(counts(1000), buckets(0, 900, 100))),
at(
"2026-07-05T10:00:03.000Z",
compactionBegin({ reason: "context", mode: "summarize", context: 1000, turns: 1 }),
),
at("2026-07-05T10:00:04.000Z", requestBegin()),
at("2026-07-05T10:00:05.000Z", legacyEnd("failed")), // compaction gives up here
at(
"2026-07-05T10:00:06.000Z",
// Legacy Trace spelling for an abandoned compaction (see legacyEnd).
compactionEnd({ reason: "context", mode: "summarize", status: "failed" as StopReason }),
),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.reconnectCount).toBe(0);
});
it("after the previous turn's retries are exhausted, a new user message starts a new turn", async () => {
// "retryable → continuation" holds only for **automatic retries within the
// same run**. Once retries are exhausted and the engine gives up, a message
// the user sends afterward starts a new turn — if continuation were still
// stuck at true, this turn would get folded into the failed one, mixing
// together both turns' messages, Tokens, TPS, and duration. A user Prompt
// always breaks continuation, regardless of how the previous turn wrapped up.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("question one")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", requestEnd("retryable")), // retries exhausted → gives up
at("2026-07-05T10:00:03.000Z", abortEvent()),
// A new user send
at("2026-07-05T10:01:00.000Z", userText("question two")),
at("2026-07-05T10:01:01.000Z", requestBegin()),
at("2026-07-05T10:01:03.000Z", requestEnd("completed")),
at("2026-07-05T10:01:03.100Z", tokenUsage(counts(1000), buckets(0, 900, 100))),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 1]);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
expect(a.tasks[1]!.startTs).toBe("2026-07-05T10:01:01.000Z"); // duration start = this turn's request_begin
expect(a.tasks[1]!.tokens.output).toBe(100); // the second turn's usage isn't folded into the first
});
it("one send with text + multiple images: turn attribution starts at the **first** message, not the last image", async () => {
// One send = multiple messages (user text + some number of image_url). If the
// pending index were overwritten on every message, turn attribution would
// start from the last image, with the preceding text and images assigned to
// the previous turn — completely at odds with "the user clicked send once".
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("question one")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at("2026-07-05T10:00:02.000Z", requestEnd("completed")),
at("2026-07-05T10:00:02.100Z", tokenUsage(counts(500), buckets(0, 400, 100))),
// Second send: text + two images
at("2026-07-05T10:01:00.000Z", userText("look at these two images")),
at("2026-07-05T10:01:00.500Z", imageUrlMessage("data:image/png;base64,AAAA")),
at("2026-07-05T10:01:01.000Z", imageUrlMessage("data:image/png;base64,BBBB")),
at("2026-07-05T10:01:02.000Z", requestBegin()),
at("2026-07-05T10:01:04.000Z", requestEnd("completed")),
at("2026-07-05T10:01:04.100Z", tokenUsage(counts(900), buckets(0, 800, 100))),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// The message-attribution start = the text (index 5), not the last image (index 7) — all three messages belong to the second turn.
expect(a.tasks[1]!.messageFrom).toBe(5);
expect(a.tasks[0]!.messageTo).toBe(4);
expect(a.tasks[1]!.startTs).toBe("2026-07-05T10:01:02.000Z"); // duration start = request_begin
expect(a.tasks[0]!.endTs).toBe("2026-07-05T10:00:02.100Z"); // the second send's messages don't land in the first turn
});
it("messages attributed one by one, never guessed from timestamps: same-millisecond \"this turn's reply / compaction begin / compaction Prompt / next turn's request\" each land on their own turn", async () => {
// Automatic compaction triggered at turn wrap-up crams these messages into
// **the same millisecond**: this turn's last reply, compaction_begin, the
// compaction Prompt, and the compaction turn's request_begin. Attributing by
// time boundary simply can't separate them — this turn's reply would get
// assigned to the compaction turn. A single sequential server-side scan
// already knows which turn each message belongs to, so the frontend can just
// use messageFrom/messageTo for attribution.
const T = "2026-07-05T10:00:05.000Z"; // same millisecond
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
at("2026-07-05T10:00:00.000Z", sessionMeta(metaPayload())),
at("2026-07-05T10:00:00.000Z", userText("q")),
at("2026-07-05T10:00:01.000Z", requestBegin()),
at(T, assistantText("this turn's reply")), // ← this turn's own reply, same millisecond as the entries below
at(T, tokenUsage(counts(500), buckets(0, 400, 100))),
at(T, requestEnd("completed")),
at(T, compactionBegin({ reason: "context", mode: "summarize", context: 500, turns: 1 })),
at(T, userText("You have a partial transcript…")), // the compaction Prompt (also user text)
at(T, requestBegin()), // the compaction request
at("2026-07-05T10:00:25.000Z", requestEnd("completed")), // slow compaction: 20s
at(
"2026-07-05T10:00:25.000Z",
compactionEnd({ reason: "context", mode: "summarize", status: "completed" }),
),
]);
const a = await service.analyze(P, A, S, 1);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// Turn 0 = session_meta..request_end (index 0..5): **this turn's reply stays in this turn**.
expect([a.tasks[0]!.messageFrom, a.tasks[0]!.messageTo]).toEqual([0, 5]);
// Turn 1 = compaction_begin..compaction_end (index 6..10): the compaction
// Prompt belongs to the compaction turn, not the tail of the previous one.
expect([a.tasks[1]!.messageFrom, a.tasks[1]!.messageTo]).toEqual([6, 10]);
// Duration is attributed to each turn separately: this turn is 4s
// (request_begin 10:00:01 → request_end 10:00:05, excluding compaction's 20s),
// the compaction turn is 20s (the compaction request's request_begin →
// compaction_end, both starting at 10:00:05).
expect(Date.parse(a.tasks[0]!.endTs) - Date.parse(a.tasks[0]!.startTs)).toBe(4_000);
expect(Date.parse(a.tasks[1]!.endTs) - Date.parse(a.tasks[1]!.startTs)).toBe(20_000);
});
it("Agent-level drill-down browsing: dates descending, Sessions descending, file index ascending", async () => {
const s2 = "session-2026-07-06-09-00-00-11112222";
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [userText("a")]);
await writeTraceFile(root, P, A, "2026-07-05", S, 2, [userText("b")]);
await writeTraceFile(root, P, A, "2026-07-06", s2, 1, [userText("c")]);
const res = await service.agentTraces(P, A);
expect(res.dates.map((d) => d.date)).toEqual(["2026-07-06", "2026-07-05"]);
expect(res.dates[1]!.sessions[0]!.sessionId).toBe(S);
expect(res.dates[1]!.sessions[0]!.files.map((f) => f.index)).toEqual([1, 2]);
// No `limit` -> the legacy full shape only: the paging fields must stay absent
// (existing consumers see a byte-identical response).
expect(res.sessions).toBeUndefined();
expect(res.totalSessions).toBeUndefined();
});
it("Agent-level paging: slices Session groups newest-first, merges one Session's files across dates, and carries the total", async () => {
const s2 = "session-2026-07-06-09-00-00-11112222";
const s3 = "session-2026-07-07-08-00-00-33334444";
// S spans two date directories: the paged entry must merge them with a per-file date.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [userText("a")]);
await writeTraceFile(root, P, A, "2026-07-06", S, 2, [userText("b")]);
await writeTraceFile(root, P, A, "2026-07-06", s2, 1, [userText("c")]);
await writeTraceFile(root, P, A, "2026-07-07", s3, 1, [userText("d")]);
const page1 = await service.agentTraces(P, A, { offset: 0, limit: 2 });
expect(page1.totalSessions).toBe(3);
expect(page1.dates).toEqual([]); // paged responses are session-centric; per-file stats happen only for the slice
expect(page1.sessions!.map((s) => s.sessionId)).toEqual([s3, s2]);
const page2 = await service.agentTraces(P, A, { offset: 2, limit: 2 });
expect(page2.totalSessions).toBe(3);
expect(page2.sessions!.map((s) => s.sessionId)).toEqual([S]);
expect(page2.sessions![0]!.files.map((f) => ({ index: f.index, date: f.date }))).toEqual([
{ index: 1, date: "2026-07-05" },
{ index: 2, date: "2026-07-06" },
]);
expect(page2.sessions![0]!.files.every((f) => f.sizeBytes > 0)).toBe(true);
// Paging an empty Agent stays well-formed.
const empty = await service.agentTraces(P, "agent-none", { offset: 0, limit: 2 });
expect(empty.sessions).toEqual([]);
expect(empty.totalSessions).toBe(0);
});
it("Agent-level paging: the sessions DB title wins over the first-prompt fallback", async () => {
const withTitles = makeTraceHarness(root, {
sessions: { listByAgent: () => [dbRow({ sessionId: S, title: "已生成的标题" })] },
});
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload()),
userText("raw prompt text"),
]);
const res = await withTitles.service.agentTraces(P, A, { offset: 0, limit: 10 });
expect(res.sessions![0]!.title).toBe("已生成的标题");
withTitles.close();
});
it("Agent-level paging: category/workspace come from the DB row (archived wins; a registry-known source fills its bucket)", async () => {
const s2 = "session-2026-07-06-09-00-00-11112222";
const s3 = "session-2026-07-07-08-00-00-33334444";
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [userText("a")]);
await writeTraceFile(root, P, A, "2026-07-06", s2, 1, [userText("b")]);
await writeTraceFile(root, P, A, "2026-07-07", s3, 1, [userText("c")]);
const sources = new SessionSources();
sources.set(s2, "subagent");
sources.set(s3, "user"); // meta seen, a person's conversation
const h = makeTraceHarness(root, {
sources,
sessions: {
listByAgent: () => [
dbRow({ sessionId: S, workspace: "/ws/one", archivedAt: "2026-07-08T00:00:00.000Z" }),
dbRow({ sessionId: s3, workspace: "/ws/two" }),
],
},
});
const res = await h.service.agentTraces(P, A, { offset: 0, limit: 10 });
const byId = new Map(res.sessions!.map((x) => [x.sessionId, x]));
expect(byId.get(S)!.category).toBe("archived");
expect(byId.get(S)!.workspace).toBe("/ws/one");
expect(byId.get(s2)!.category).toBe("background"); // untracked but registry-known
expect(byId.get(s3)!.category).toBe("active");
expect(res.counts).toEqual({ active: 1, background: 1, archived: 1 });
expect(res.workspaceCounts!["/ws/one"]).toEqual({ active: 0, background: 0, archived: 1 });
expect(res.workspaceCounts!["/ws/two"]).toEqual({ active: 1, background: 0, archived: 0 });
// The category filter pages within one bucket; totalSessions is the bucket's count.
const active = await h.service.agentTraces(
P,
A,
{ offset: 0, limit: 10 },
{ category: "active" },
);
expect(active.sessions!.map((x) => x.sessionId)).toEqual([s3]);
expect(active.totalSessions).toBe(1);
expect(active.counts).toEqual({ active: 1, background: 1, archived: 1 });
const archived = await h.service.agentTraces(
P,
A,
{ offset: 0, limit: 10 },
{ category: "archived" },
);
expect(archived.sessions!.map((x) => x.sessionId)).toEqual([S]);
h.close();
});
it("Agent-level paging: an untracked Session is classified at registration (head-read once), so the FIRST listing is exact", async () => {
// No DB row, nothing pre-registered: the reconciler registers the file and reads the
// earliest shard's session_meta ONCE; the listing itself then serves category /
// workspace / title from the index with no per-request head-reads.
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [
sessionMeta(metaPayload({ source: "subagent", workspace: "/ws/child" })),
userText("child prompt"),
]);
const first = await service.agentTraces(P, A, { offset: 0, limit: 10 });
expect(first.sessions![0]!.category).toBe("background");
expect(first.sessions![0]!.workspace).toBe("/ws/child");
expect(first.counts).toEqual({ active: 0, background: 1, archived: 0 });
// The observation landed in the shared registry (single source of truth) at registration.
expect(harness.sources.get(S)).toBe("subagent");
const reads = harness.traceIndex.counters.headReads;
const second = await service.agentTraces(P, A, { offset: 0, limit: 10 });
expect(second.sessions![0]!.category).toBe("background");
expect(harness.traceIndex.counters.headReads).toBe(reads); // classification never re-reads
});
it("Agent-level paging: every Session is listed whichever client created it (no CLI filter)", async () => {
const cliSid = "session-2026-07-06-09-00-00-11112222"; // untracked, user-created meta (a legacy CLI-direct run)
const childSid = "session-2026-07-07-08-00-00-33334444"; // untracked but subagent-sourced -> Background
await writeTraceFile(root, P, A, "2026-07-06", cliSid, 1, [
sessionMeta(metaPayload({ session_id: cliSid })),
userText("cli run"),
]);
await writeTraceFile(root, P, A, "2026-07-07", childSid, 1, [
sessionMeta(metaPayload({ session_id: childSid, source: "subagent" })),
userText("child run"),
]);
const webSid = S;
await writeTraceFile(root, P, A, "2026-07-05", webSid, 1, [
sessionMeta(metaPayload()),
userText("web run"),
]);
const h = makeTraceHarness(root, {
sessions: { listByAgent: () => [dbRow({ sessionId: webSid, workspace: "/ws/web" })] },
});
const listed = await h.service.agentTraces(P, A, { offset: 0, limit: 10 });
expect(listed.sessions!.map((x) => x.sessionId)).toEqual([childSid, cliSid, webSid]);
expect(listed.totalSessions).toBe(3);
expect(listed.counts).toEqual({ active: 2, background: 1, archived: 0 });
h.close();
});
it("Agent-level paging: a Session whose head has no user text gets no title (the client falls back to its default)", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S, 1, [sessionMeta(metaPayload())]);
const res = await service.agentTraces(P, A, { offset: 0, limit: 10 });
expect(res.sessions![0]!.title).toBeUndefined();
});
it("every endpoint returns empty when there is no Trace", async () => {
expect(await service.readMessages(P, A, S)).toEqual([]);
expect(await service.listTraceFiles(P, A, S)).toEqual([]);
expect((await service.agentTraces(P, A)).dates).toEqual([]);
});
it("execution timeline: serial model segments (start = previous event), tool approval/execution phases, the next round anchored on request_begin", async () => {
const T = (sec: string) => `2026-07-05T10:00:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 7, [
sessionMeta(metaPayload()),
at(T("00.000"), userText("q")), // the user input is sent instantly, so it occupies no segment
at(T("01.000"), requestBegin()),
at(T("03.000"), thinkingMessage("think", "completed")),
at(T("04.000"), toolCall({ name: "exec_command", arguments: "{}", toolCallId: "t1" })),
// Two async tools: t1 is already in approval/execution while the model keeps decoding t2
at(T("04.500"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t2" })),
at(T("05.000"), requestEnd("completed")),
at(T("05.500"), approvalDecision("allow", "t1")),
at(T("06.000"), approvalDecision("allow", "t2")),
at(T("07.000"), toolCallOutput({ output: "o1", toolCallId: "t1" })),
at(T("08.000"), toolCallOutput({ output: "o2", toolCallId: "t2" })),
// The model starts the next round only after all outputs are back: the new segment is anchored on request_begin
at(T("08.500"), requestBegin()),
at(T("10.000"), assistantText("answer")),
at(T("10.100"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 7);
// A single user turn containing two rounds of Requests (the first calls a
// tool, the second produces the answer) is merged into the same Task (taskIndex 0).
expect(a.modelSegments).toEqual([
{ kind: "thinking", startTs: T("01.000"), endTs: T("03.000"), taskIndex: 0 },
{
kind: "tool_call",
startTs: T("03.000"),
endTs: T("04.000"),
toolCallId: "t1",
name: "exec_command",
taskIndex: 0,
},
{
kind: "tool_call",
startTs: T("04.000"),
endTs: T("04.500"),
toolCallId: "t2",
name: "read_file",
taskIndex: 0,
},
{ kind: "text", startTs: T("08.500"), endTs: T("10.000"), taskIndex: 0 },
]);
expect(a.toolSpans).toEqual([
{
toolCallId: "t1",
name: "exec_command",
callTs: T("04.000"),
approvalTs: T("05.500"),
decision: "allow",
outputTs: T("07.000"),
stopReason: "completed",
taskIndex: 0,
},
{
toolCallId: "t2",
name: "read_file",
callTs: T("04.500"),
approvalTs: T("06.000"),
decision: "allow",
outputTs: T("08.000"),
stopReason: "completed",
taskIndex: 0,
},
]);
});
it("Task grouping: plain text with no further tool call → the next user turn enters a new Task (taskIndex increments)", async () => {
const T = (sec: string) => `2026-07-05T10:01:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 9, [
sessionMeta(metaPayload()),
// Task 0: one round calls a tool + one round produces the answer.
at(T("00.000"), userText("q1")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "o", toolCallId: "t1" })),
at(T("03.500"), requestBegin()),
at(T("04.000"), assistantText("answer 1")),
at(T("04.500"), requestEnd("completed")),
// Task 1: a new user turn (the previous turn ended in plain text, not a continuation).
at(T("20.000"), userText("q2")),
at(T("21.000"), requestBegin()),
at(T("22.000"), assistantText("answer 2")),
at(T("22.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 9);
expect(a.modelSegments.map((s) => s.taskIndex)).toEqual([0, 0, 1]);
expect(a.toolSpans.map((s) => s.taskIndex)).toEqual([0]);
// The first round calls a tool → the continuation round stays in Task 0; after ending in plain text, the new user turn goes into Task 1.
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0, 1]);
});
it("MCP connect pair becomes an other-span attached to the following Task", async () => {
const T = (sec: string) => `2026-07-05T10:04:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 13, [
sessionMeta(metaPayload()),
// First run's bootstrap precedes any request: the pair closes before Task 0 begins.
at(T("00.000"), mcpConnectBegin(["fx"])),
at(
T("01.200"),
mcpConnectEnd({
status: "completed",
results: [
{ server: "fx", transport: "stdio", status: "completed", duration_ms: 1150, tools: 3 },
],
}),
),
at(T("02.000"), requestBegin()),
at(T("03.000"), assistantText("answer")),
at(T("03.100"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 13);
// An "other" span, not a tool span: nothing was called.
expect(a.toolSpans).toEqual([]);
expect(a.otherSpans).toEqual([
{
key: `mcp-connect-${T("00.000")}`,
name: "mcp connect",
startTs: T("00.000"),
endTs: T("01.200"),
taskIndex: 0,
},
]);
});
it("Task grouping: [user_steering] user texts never start a new Task (steering continuation stays in the same Task)", async () => {
const T = (sec: string) => `2026-07-05T10:03:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 12, [
sessionMeta(metaPayload()),
// Task 0, round 1: calls a tool; a steering message rides alongside the tool output.
at(T("00.000"), userText("q1")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "o", toolCallId: "t1" })),
at(T("03.200"), userText("[user_steering]\nalso check the tests\n[/user_steering]")),
at(T("03.500"), requestBegin()),
at(T("04.000"), assistantText("answer 1")),
at(T("04.500"), requestEnd("completed")),
// Loop-end steering: the answer round produced no tool call — a plain user text here
// would start a new Task, but the steering continuation stays in Task 0.
at(T("05.000"), userText("[user_steering]\none more thing\n[/user_steering]")),
at(T("05.500"), requestBegin()),
at(T("06.000"), assistantText("answer 2")),
at(T("06.500"), requestEnd("completed")),
// A real new user turn afterwards starts Task 1 as usual.
at(T("20.000"), userText("q2")),
at(T("21.000"), requestBegin()),
at(T("22.000"), assistantText("answer 3")),
at(T("22.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 12);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0, 0, 1]);
expect(a.modelSegments.map((s) => s.taskIndex)).toEqual([0, 0, 0, 1]);
});
// The Web's live-stream twin of this case lives in stream-model.test.ts.
it("Task grouping: a steered background notice stays in the same Task; an unstamped notice task keeps its own turn", async () => {
const T = (sec: string) => `2026-07-05T10:05:${sec}Z`;
const steered = buildBackgroundTaskDoneMessage(
{
kind: "command",
id: "proc-1",
status: "completed",
detail: "exit code 0",
delivery: "steering",
},
"Background command finished",
);
const plain = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-2", status: "failed", detail: "exit code 1" },
"Background command failed",
);
await writeTraceFile(root, P, A, "2026-07-05", S, 14, [
sessionMeta(metaPayload()),
// Task 0: the reply round produced no tool call — the steered notice is exactly what
// continues the loop, and it must not open a turn of its own.
at(T("00.000"), userText("build it")),
at(T("01.000"), requestBegin()),
at(T("02.000"), assistantText("kicked off")),
at(T("02.500"), requestEnd("completed")),
at(T("08.000"), userText(steered, "harness")),
at(T("08.500"), requestBegin()),
at(T("09.000"), assistantText("finished cleanly")),
at(T("09.500"), requestEnd("completed")),
// Idle delivery later: the unstamped notice is a task's own input — independent turn.
at(T("20.000"), userText(plain, "harness")),
at(T("21.000"), requestBegin()),
at(T("22.000"), assistantText("reacting to the failure")),
at(T("22.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 14);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0, 1]);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// Injected messages never move the duration start (first request_begin rule).
expect(a.tasks[0]!.startTs).toBe(T("01.000"));
expect(a.tasks[1]!.startTs).toBe(T("21.000"));
});
it("Task grouping: an UNSTAMPED notice in a tool-continuation gap merges too (pre-stamp traces)", async () => {
// Legacy shape (0.2.4 core, no delivery stamp): the notice sits between a tool-calling
// request and its continuation, where a Task cannot end — position alone proves it is
// in-task, and the round must not split at it (the reducer and the window scanner apply
// the identical fallback).
const T = (sec: string) => `2026-07-05T10:07:${sec}Z`;
const plain = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-4", status: "completed", detail: "exit code 0" },
"Background command finished",
);
await writeTraceFile(root, P, A, "2026-07-05", S, 16, [
sessionMeta(metaPayload()),
at(T("00.000"), userText("build it")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "exec_command", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "launched", toolCallId: "t1" })),
at(T("08.000"), userText(plain, "harness")),
at(T("08.500"), requestBegin()),
at(T("09.000"), assistantText("finished cleanly")),
at(T("09.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 16);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0]);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0]);
});
it("Task grouping: a notice drained at run start rides behind the fresh Prompt without merging turns", async () => {
// A notice queued while the session sat idle can be consumed by a user run's start
// instead of the idle launcher: core writes it right after the Prompt, steering-stamped.
// The Prompt's own continuation break must win — the new turn opens normally, with the
// notice inside its span rather than gluing it onto the previous turn.
const T = (sec: string) => `2026-07-05T10:06:${sec}Z`;
const steered = buildBackgroundTaskDoneMessage(
{
kind: "command",
id: "proc-3",
status: "completed",
detail: "exit code 0",
delivery: "steering",
},
"Background command finished",
);
await writeTraceFile(root, P, A, "2026-07-05", S, 15, [
sessionMeta(metaPayload()),
at(T("00.000"), userText("q1")),
at(T("01.000"), requestBegin()),
at(T("02.000"), assistantText("a1")),
at(T("02.500"), requestEnd("completed")),
// The next send: Prompt, then the ride-along notice, then the request.
at(T("10.000"), userText("q2")),
at(T("10.100"), userText(steered, "harness")),
at(T("11.000"), requestBegin()),
at(T("12.000"), assistantText("a2")),
at(T("12.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 15);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 1]);
expect(a.tasks.map((t) => t.taskIndex)).toEqual([0, 1]);
// Both the Prompt and the ride-along notice belong to the second turn's span.
expect(a.tasks[1]!.messageFrom).toBe(5);
});
it("Task grouping: images sent with a steering message don't start a Task either (a Prompt's do)", async () => {
const T = (sec: string) => `2026-07-05T10:04:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 13, [
sessionMeta(metaPayload()),
// Task 0: a normal turn that calls a tool.
at(T("00.000"), userText("q1")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "o", toolCallId: "t1" })),
// Steering with two images: core delivers them right behind the text, and the whole
// batch stays inside Task 0 — an image is a turn starter everywhere except here.
at(T("03.200"), userText("[user_steering]\nlike this mock\n[/user_steering]")),
at(T("03.300"), imageUrlMessage("data:image/png;base64,AAAA")),
// A subagent message belongs to another session's stream and says nothing about this
// one's grouping, so it leaves the window open (the Web skips these even earlier).
at(T("03.350"), withOrigin(assistantText("child thinking"), "child-1")),
at(T("03.400"), imageUrlMessage("data:image/png;base64,BBBB")),
at(T("03.500"), requestBegin()),
at(T("04.000"), assistantText("answer 1")),
at(T("04.500"), requestEnd("completed")),
// An images-only Prompt after all that is a genuine new turn.
at(T("20.000"), imageUrlMessage("data:image/png;base64,CCCC")),
at(T("21.000"), requestBegin()),
at(T("22.000"), assistantText("answer 2")),
at(T("22.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 13);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 0, 1]);
});
// Compaction is its own turn: the previous turn called a tool and would
// otherwise "continue", but compaction_begin breaks that continuation, so the
// compaction request lands on a new taskIndex. A successful compaction splits
// the Trace into a new file, so this file ends at compaction_end.
it("Task grouping: the compaction request isn't folded into the previous turn (successful compaction; this file ends at compaction_end)", async () => {
const T = (sec: string) => `2026-07-05T10:02:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 10, [
sessionMeta(metaPayload()),
// Task 0: calls a tool, which would normally continue the turn.
at(T("00.000"), userText("q")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "o", toolCallId: "t1" })),
// Task 1: the compaction request.
at(
T("04.000"),
compactionBegin({ reason: "context", mode: "summarize", context: 1, turns: 1 }),
),
at(T("04.500"), requestBegin()),
at(T("05.000"), assistantText("[summary]…[/summary]")),
at(T("05.500"), requestEnd("completed")),
at(T("06.000"), compactionEnd({ reason: "context", mode: "summarize", status: "completed" })),
]);
const a = await service.analyze(P, A, S, 10);
expect(a.modelSegments.map((s) => s.taskIndex)).toEqual([0, 1]);
expect(a.toolSpans.map((s) => s.taskIndex)).toEqual([0]);
expect(a.requests.map((r) => r.taskIndex)).toEqual([0, 1]);
expect(a.compactionCount).toBe(1);
});
// A failed compaction doesn't split the file: the continuation request is
// still in the same file, and it starts a new turn (the compaction request
// doesn't call a tool, and request_end has already broken continuation).
it("Task grouping: the continuation request after a failed compaction starts a new turn", async () => {
const T = (sec: string) => `2026-07-05T10:03:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 11, [
sessionMeta(metaPayload()),
at(T("00.000"), userText("q")),
at(T("01.000"), requestBegin()),
at(T("02.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t1" })),
at(T("02.500"), requestEnd("completed")),
at(T("03.000"), toolCallOutput({ output: "o", toolCallId: "t1" })),
at(
T("04.000"),
compactionBegin({ reason: "context", mode: "summarize", context: 1, turns: 1 }),
),
at(T("04.500"), requestBegin()),
at(T("05.000"), assistantText("bad summary")),
at(T("05.500"), requestEnd("retryable")),
at(T("06.000"), compactionEnd({ reason: "context", mode: "summarize", status: "retryable" })),
at(T("07.000"), requestBegin()),
at(T("08.000"), assistantText("answer")),
at(T("08.500"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 11);
expect(a.modelSegments.map((s) => s.taskIndex)).toEqual([0, 1, 2]);
expect(a.toolSpans.map((s) => s.taskIndex)).toEqual([0]);
});
it("interrupt-compensation tool_calls (stop_reason not completed) stay out of the timeline lanes (no phantom execution segments)", async () => {
const T = (sec: string) => `2026-07-05T10:00:${sec}Z`;
await writeTraceFile(root, P, A, "2026-07-05", S, 8, [
sessionMeta(metaPayload()),
at(T("00.000"), userText("q")),
at(T("01.000"), requestBegin()),
at(
T("02.000"),
toolCall({
name: "exec_command",
arguments: "{}",
toolCallId: "t1",
stopReason: "retryable",
}),
),
at(T("02.500"), requestEnd("retryable")),
at(T("03.000"), requestBegin()),
at(T("04.000"), toolCall({ name: "read_file", arguments: "{}", toolCallId: "t2" })),
at(T("04.500"), toolCallOutput({ output: "ok", toolCallId: "t2" })),
at(T("05.000"), requestEnd("completed")),
]);
const a = await service.analyze(P, A, S, 8);
// A phantom call gets no lane: only t2 goes into toolSpans.
expect(a.toolSpans.map((sp) => sp.toolCallId)).toEqual(["t2"]);
// But the duration list still records t1 (flagged with the interrupted status).
expect(a.toolCalls.find((c) => c.toolCallId === "t1")?.stopReason).toBe("retryable");
});
});