@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/cli/trace.ts

@@ -4,27 +4,39 @@ import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { clioStatePath } from "../core/xdg.js";
 import {
+	DEFAULT_TRACE_RETENTION_POLICY,
+	resolveTraceRetentionPolicy,
 	TRACE_EVENT_POLL_LIMIT,
 	type TraceEventRow,
 	type TracePhaseRow,
 	type TraceProcessRow,
 	TraceReader,
 	type TraceRunRow,
+	TraceStore,
 	traceDatabasePath,
 } from "../domains/observability/trace-store.js";
+import { runTraceInspect } from "./trace-inspect.js";
 
 const HELP = `Usage:
   clio-coder trace runs [--db PATH] [--limit N] [--json]
+  clio-coder trace inspect --json         a fixed bounded window with no request text
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
+  clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
   clio-coder trace sql <SELECT query> [--db PATH]
   clio-coder trace ui [--db PATH] [--port N]        source checkout only
 
 The viewer ships with the repository, not the npm package, so from an installed
 Clio the subcommands above are the way in. They read the same database.
+Pruning keeps ${DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays} days and at most ${DEFAULT_TRACE_RETENTION_POLICY.maxBytes} bytes by default. Set
+CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the automatic
+policy; prune flags override those values for one command.
 `;
 
+/** Rows `trace runs` shows when the operator names no limit. */
+const DEFAULT_TRACE_LIMIT = 50;
+
 interface ParsedTraceArgs {
 	positional: string[];
 	db: string;
@@ -34,6 +46,8 @@ interface ParsedTraceArgs {
 	limit: number;
 	port: number;
 	json: boolean;
+	maxAgeDays: number | undefined;
+	maxBytes: number | undefined;
 }
 
 function parseTraceArgs(args: string[]): ParsedTraceArgs {
@@ -41,14 +55,22 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let db = traceDatabasePath(clioStatePath());
 	let dbExplicit = false;
 	let follow = false;
-	let limit = 50;
+	let limit = DEFAULT_TRACE_LIMIT;
 	let port = 0;
 	let json = false;
+	let maxAgeDays: number | undefined;
+	let maxBytes: number | undefined;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--follow") follow = true;
 		else if (arg === "--json") json = true;
-		else if (arg === "--db" || arg === "--limit" || arg === "--port") {
+		else if (
+			arg === "--db" ||
+			arg === "--limit" ||
+			arg === "--port" ||
+			arg === "--max-age-days" ||
+			arg === "--max-bytes"
+		) {
 			const value = args[index + 1];
 			if (value === undefined) throw new Error(`${arg} requires a value`);
 			index += 1;
@@ -56,20 +78,25 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 				db = resolve(value);
 				dbExplicit = true;
 			} else if (arg === "--limit") limit = parseInteger(value, "--limit", 1, 500);
-			else port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--port") port = parseInteger(value, "--port", 0, 65_535);
+			else if (arg === "--max-age-days") maxAgeDays = parseInteger(value, arg, 1, 36_500);
+			else maxBytes = parseInteger(value, arg, 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		} else if (arg?.startsWith("--db=")) {
 			db = resolve(arg.slice(5));
 			dbExplicit = true;
 		} else if (arg?.startsWith("--limit=")) limit = parseInteger(arg.slice(8), "--limit", 1, 500);
 		else if (arg?.startsWith("--port=")) port = parseInteger(arg.slice(7), "--port", 0, 65_535);
+		else if (arg?.startsWith("--max-age-days=")) maxAgeDays = parseInteger(arg.slice(15), "--max-age-days", 1, 36_500);
+		else if (arg?.startsWith("--max-bytes="))
+			maxBytes = parseInteger(arg.slice(12), "--max-bytes", 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		else if (arg?.startsWith("-")) throw new Error(`unknown trace flag: ${arg}`);
 		else if (arg !== undefined) positional.push(arg);
 	}
-	return { positional, db, dbExplicit, follow, limit, port, json };
+	return { positional, db, dbExplicit, follow, limit, port, json, maxAgeDays, maxBytes };
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "prune", "sql", "ui"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -125,6 +152,22 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 
 	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
 
+	// `inspect` answers ahead of the no-database courtesy below, because its
+	// answer to a state tree nothing has written to is a JSON snapshot saying
+	// the trace database is unavailable, not a sentence on stdout.
+	if (command === "inspect") {
+		return runTraceInspect(
+			parsed.positional.length === 1 &&
+				parsed.json &&
+				!parsed.dbExplicit &&
+				!parsed.follow &&
+				parsed.limit === DEFAULT_TRACE_LIMIT &&
+				parsed.port === 0 &&
+				parsed.maxAgeDays === undefined &&
+				parsed.maxBytes === undefined,
+		);
+	}
+
 	// A database that was never written is the empty state, not a failure. Handing
 	// the absent path to node:sqlite produced "unable to open database file",
 	// which named neither the file nor a next step, and loading the module leaked
@@ -132,6 +175,7 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	// the operator typed is a different claim, so a --db that is not there stays
 	// an error and says which path it means.
 	if (!existsSync(parsed.db)) return missingDatabase(parsed);
+	if (command === "prune") return runTracePrune(parsed);
 
 	let reader: TraceReader;
 	try {
@@ -189,6 +233,42 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	}
 }
 
+function runTracePrune(parsed: ParsedTraceArgs): number {
+	let policy: ReturnType<typeof resolveTraceRetentionPolicy>;
+	try {
+		policy = resolveTraceRetentionPolicy({
+			...(parsed.maxAgeDays === undefined ? {} : { maxAgeDays: parsed.maxAgeDays }),
+			...(parsed.maxBytes === undefined ? {} : { maxBytes: parsed.maxBytes }),
+		});
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	let store: TraceStore;
+	try {
+		store = new TraceStore(parsed.db, { retention: policy });
+	} catch (error) {
+		process.stderr.write(`trace database: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	try {
+		const result = store.prune(policy);
+		if (parsed.json) {
+			process.stdout.write(`${JSON.stringify({ policy, ...result }, null, 2)}\n`);
+		} else {
+			process.stdout.write(
+				`trace prune: removed ${result.runsRemoved.toLocaleString("en-US")} runs and ${result.rowsRemoved.toLocaleString("en-US")} rows; reclaimed ${result.bytesRemoved.toLocaleString("en-US")} bytes; VACUUM ${result.vacuumed ? "ran" : "not needed"}; protected ${result.protectedRuns.toLocaleString("en-US")} live runs\n`,
+			);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	} finally {
+		store.close();
+	}
+}
+
 async function tail(reader: TraceReader, runId: string, follow: boolean): Promise<void> {
 	let cursor = 0;
 	let idleTerminalPolls = 0;

package/src/cli/usage.ts

@@ -12,9 +12,12 @@ import { readEvidenceIndex } from "../domains/observability/evidence-index.js";
 import { type OutOfTurnUsageRow, readOutOfTurnUsageRows } from "../domains/observability/out-of-turn-usage.js";
 import { loadSkills } from "../domains/resources/index.js";
 import {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
 	type LedgerUsageCall,
 	ledgerUsageCalls,
 	listSessionLedgerRefs,
+	type PromptCacheTelemetry,
 	parseSessionEntries,
 	readAuditRows,
 } from "../domains/session/index.js";
@@ -69,6 +72,8 @@ interface SessionUsage {
 	entriesInWindow: number;
 	/** Completed API calls this session recorded in the window, one per call. */
 	usageCalls: LedgerUsageCall[];
+	/** Backend prompt-cache facts persisted on assistant calls in the window. */
+	promptCache: PromptCacheTelemetry;
 }
 
 /** Per-call usage folded over one grouping (a model, or the whole window). */
@@ -102,32 +107,37 @@ function addResponseModelIdObservation(counts: ResponseModelIdObservationCounts,
 
 /**
  * How the folded calls split between the session's own turns and the rounds
- * that were billed beside it. A `/btw` side question and a `/handoff` round are
- * real spend and belong in the token and cost totals, but neither is a turn:
- * they never entered the session. `turns` therefore subtracts them from the
- * folded row count, which is exactly what the `/cost` overlay does.
+ * that were billed beside it. A `/btw` side question, a `/handoff` round, a
+ * session pre-warm, and a proactive-memory step are real spend and belong in
+ * the token and cost totals, but none of them is a turn: they never entered
+ * the session. `turns` therefore subtracts them from the folded row count,
+ * which is exactly what the `/cost` overlay does.
  */
 interface CallOrigins {
 	rows: number;
 	sideQuestions: number;
 	handoffs: number;
+	prewarms: number;
+	backgroundMemory: number;
 }
 
 function emptyCallOrigins(): CallOrigins {
-	return { rows: 0, sideQuestions: 0, handoffs: 0 };
+	return { rows: 0, sideQuestions: 0, handoffs: 0, prewarms: 0, backgroundMemory: 0 };
 }
 
 function turnsOf(origins: CallOrigins): number {
-	return origins.rows - origins.sideQuestions - origins.handoffs;
+	return origins.rows - origins.sideQuestions - origins.handoffs - origins.prewarms - origins.backgroundMemory;
 }
 
 function hasLabelledCall(origins: CallOrigins): boolean {
-	return origins.sideQuestions > 0 || origins.handoffs > 0;
+	return origins.sideQuestions > 0 || origins.handoffs > 0 || origins.prewarms > 0 || origins.backgroundMemory > 0;
 }
 
 function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
 	origins.rows += 1;
 	if (row.label === "side-question") origins.sideQuestions += 1;
+	else if (row.label === "prewarm") origins.prewarms += 1;
+	else if (row.label === "background-memory") origins.backgroundMemory += 1;
 	else origins.handoffs += 1;
 }
 
@@ -435,6 +445,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
+	const cacheSessions = sessions
+		.filter((session) => hasPromptCacheTelemetry(session.promptCache))
+		.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
 
 	const approvedMemory = memoryRecords.filter((record) => record.approved && record.rejectedAt === undefined);
 	const pendingMemory = memoryRecords.filter((record) => !record.approved && record.rejectedAt === undefined);
@@ -515,8 +528,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
 		if (usageMeasurable) {
 			// The origin split is emitted only when something out of turn was
-			// recorded, so a report over an archive with no `/btw` or `/handoff`
-			// round in it stays byte-identical to what it printed before.
+			// recorded, so a report over an archive with no `/btw`, `/handoff`, or
+			// pre-warm round in it stays byte-identical to what it printed before.
 			emit({
 				kind: "fact",
 				fact: "tokens",
@@ -526,6 +539,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 							turns: turnsOf(callOrigins),
 							sideQuestions: callOrigins.sideQuestions,
 							handoffs: callOrigins.handoffs,
+							prewarms: callOrigins.prewarms,
+							backgroundMemorySteps: callOrigins.backgroundMemory,
 						}
 					: {}),
 			});
@@ -540,6 +555,15 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 					...row.totals,
 				});
 			}
+			for (const session of cacheSessions) {
+				emit({
+					kind: "fact",
+					fact: "session-cache",
+					sessionId: session.sessionId,
+					uncachedPrefillTokens: session.promptCache.uncachedPrefillTokens,
+					verdictCounts: session.promptCache.verdictCounts,
+				});
+			}
 		}
 		for (const [tool, totals] of topTools) emit({ kind: "fact", fact: "top-tool", tool, ...totals });
 		for (const [shape, count] of topShapes) {
@@ -600,6 +624,10 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			out(`  turns in window: ${turnsOf(callOrigins)}`);
 			if (callOrigins.sideQuestions > 0) out(`  side questions in window: ${callOrigins.sideQuestions}`);
 			if (callOrigins.handoffs > 0) out(`  handoffs in window: ${callOrigins.handoffs}`);
+			if (callOrigins.prewarms > 0) out(`  pre-warms in window: ${callOrigins.prewarms}`);
+			if (callOrigins.backgroundMemory > 0) {
+				out(`  background memory steps in window: ${callOrigins.backgroundMemory}`);
+			}
 		}
 		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
 	}
@@ -639,6 +667,27 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			),
 		);
 	}
+	if (cacheSessions.length > 0) {
+		out("");
+		out("  prompt cache by session (from backend timings and persisted verdicts)");
+		process.stdout.write(
+			indent(
+				formatColumns([
+					["session", "uncached prefill", "hot/partial/cold/small"],
+					...cacheSessions.map((session) => [
+						session.sessionId,
+						session.promptCache.uncachedPrefillTokens === null ? "n/a" : String(session.promptCache.uncachedPrefillTokens),
+						[
+							session.promptCache.verdictCounts.hot,
+							session.promptCache.verdictCounts.partial,
+							session.promptCache.verdictCounts.cold,
+							session.promptCache.verdictCounts.small,
+						].join("/"),
+					]),
+				]),
+			),
+		);
+	}
 	if (topTools.length > 0) {
 		out("");
 		out("  top tools (from receipt toolStats)");
@@ -865,6 +914,9 @@ async function readSessions(
 		}
 		const parsedEntries = parseSessionEntries(raw, ref.path);
 		diagnostics.malformedSessionLines += parsedEntries.errors.length;
+		const accountingEntries = parsedEntries.entries.filter(
+			(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
+		);
 		const usage: SessionUsage = {
 			sessionId: ref.sessionId,
 			cwdHash: ref.cwdHash,
@@ -874,11 +926,8 @@ async function readSessions(
 			// modelChange rows are kept regardless of the window: they carry no
 			// usage of their own, and dropping the ones that predate the window
 			// would attribute in-window calls to the wrong target.
-			usageCalls: ledgerUsageCalls(
-				parsedEntries.entries.filter(
-					(entry) => entry.kind === "modelChange" || inWindow(entry.timestamp, windowStart, windowEnd),
-				),
-			),
+			usageCalls: ledgerUsageCalls(accountingEntries),
+			promptCache: foldPromptCacheTelemetry(accountingEntries),
 		};
 		for (const entry of parsedEntries.entries) {
 			if (!inWindow(entry.timestamp, windowStart, windowEnd)) continue;