@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/domains/extensions/resources.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { listInstalledExtensions } from "./state.js";
 import type { ExtensionResourceKind, ExtensionResourceRoot } from "./types.js";
@@ -7,8 +7,24 @@ export function extensionResourcePath(rootPath: string, resourcePath: string): s
 	const root = path.resolve(rootPath);
 	const full = path.resolve(root, resourcePath);
 	const relative = path.relative(root, full);
-	if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return full;
-	return null;
+	if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+		return null;
+	try {
+		const rootReal = realpathSync(root);
+		const fullReal = realpathSync(full);
+		const canonicalRelative = path.relative(rootReal, fullReal);
+		if (
+			canonicalRelative === ".." ||
+			canonicalRelative.startsWith(`..${path.sep}`) ||
+			path.isAbsolute(canonicalRelative)
+		) {
+			return null;
+		}
+		if (!lstatSync(full).isDirectory()) return null;
+		return full;
+	} catch {
+		return null;
+	}
 }
 
 export function enabledExtensionResourceRoots(
@@ -22,15 +38,11 @@ export function enabledExtensionResourceRoots(
 		if (!rel) continue;
 		const full = extensionResourcePath(entry.rootPath, rel);
 		if (!full) continue;
-		try {
-			if (!statSync(full).isDirectory()) continue;
-		} catch {
-			continue;
-		}
 		roots.push({
 			id: entry.id,
 			scope: entry.scope,
 			path: full,
+			rootPath: entry.rootPath,
 			source: `extension:${entry.scope}:${entry.id}`,
 		});
 	}

package/src/domains/extensions/state.ts

@@ -129,7 +129,7 @@ export function installExtension(sourcePath: string, options: ExtensionInstallOp
 	const cwd = options.cwd ?? process.cwd();
 	const source = path.resolve(sourcePath);
 	const candidate = loadManifestFromRoot(source);
-	if (!candidate.manifest) return { diagnostics: candidate.diagnostics };
+	if (!candidate.manifest || !candidate.valid) return { diagnostics: candidate.diagnostics };
 	const targetRoot = path.join(extensionBaseDir(scope, cwd), candidate.manifest.id);
 	if (existsSync(targetRoot)) {
 		if (!options.force) {
@@ -152,7 +152,11 @@ export function installExtension(sourcePath: string, options: ExtensionInstallOp
 		rmSync(backupRoot, { recursive: true, force: true });
 		cpSync(source, stagingRoot, {
 			recursive: true,
-			filter: (src) => path.basename(src) !== "state.json",
+			// `state.json` beside the installed extension directories belongs to
+			// Clio's extension manager. An extension may legitimately ship nested
+			// resources with the same basename (for example a project-state JSON
+			// template), so exclude only a bookkeeping file at the package root.
+			filter: (src) => path.relative(source, src) !== "state.json",
 		});
 		if (existsSync(targetRoot)) {
 			renameSync(targetRoot, backupRoot);

package/src/domains/extensions/types.ts

@@ -1,9 +1,11 @@
 export type ExtensionScope = "user" | "project";
-export type ExtensionResourceKind = "skills" | "prompts" | "themes";
+export type ExtensionResourceKind = "skills" | "prompts" | "agents" | "fleets" | "themes";
 
 export interface ExtensionManifestResources {
 	skills?: string;
 	prompts?: string;
+	agents?: string;
+	fleets?: string;
 	themes?: string;
 }
 
@@ -52,6 +54,7 @@ export interface ExtensionResourceRoot {
 	id: string;
 	scope: ExtensionScope;
 	path: string;
+	rootPath: string;
 	source: string;
 }
 

package/src/domains/lifecycle/doctor.ts

@@ -5,8 +5,11 @@ import { initializeClioHome } from "../../core/init.js";
 import { resolveClioDirs } from "../../core/xdg.js";
 import { readSessionFileEntries, type SessionJsonlWarning } from "../../engine/session.js";
 import { detectInteropAgents, interopAgentKind, resolveOnPath } from "../interop/index.js";
-import { openAuthStorage } from "../providers/auth/index.js";
+import { openAuthStorage, resolveAuthTarget, targetRequiresAuth } from "../providers/auth/index.js";
+import { credentialsPresent } from "../providers/credentials.js";
 import { fingerprintNativeRuntime } from "../providers/probe/fingerprint.js";
+import type { ProbeContext, ProbeResult, RuntimeDescriptor } from "../providers/types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../providers/types/target-descriptor.js";
 import { loadSkills, type SkillSource } from "../resources/skills/loader.js";
 import { readStateInfoResult } from "./state.js";
 import { getVersionInfo } from "./version.js";
@@ -534,3 +537,139 @@ export async function runDoctorRuntimeChecks(): Promise<DoctorFinding[]> {
 	);
 	return results.filter((finding): finding is DoctorFinding => finding !== null);
 }
+
+/** One configured model pointer at a target, named the way settings.yaml spells it. */
+interface ConfiguredModelRole {
+	role: string;
+	model: string;
+}
+
+function configuredModelRoles(
+	settings: ReturnType<typeof readSettings>,
+	target: TargetDescriptor,
+): ConfiguredModelRole[] {
+	const roles: ConfiguredModelRole[] = [];
+	if (target.defaultModel) roles.push({ role: "defaultModel", model: target.defaultModel });
+	if (settings.orchestrator.target === target.id && settings.orchestrator.model) {
+		roles.push({ role: "orchestrator.model", model: settings.orchestrator.model });
+	}
+	if (settings.background.target === target.id && settings.background.model) {
+		roles.push({ role: "background.model", model: settings.background.model });
+	}
+	if (settings.workers.default.target === target.id && settings.workers.default.model) {
+		roles.push({ role: "workers.default.model", model: settings.workers.default.model });
+	}
+	return roles;
+}
+
+/**
+ * Per-request budget for the model sweep. A target that does not answer in
+ * this time falls back to the list configure recorded, so a black-holed
+ * remote costs doctor a bounded wait rather than the probe's full timeout.
+ */
+const DOCTOR_MODEL_PROBE_TIMEOUT_MS = 2_500;
+
+async function doctorProbeContext(target: TargetDescriptor, runtime: RuntimeDescriptor): Promise<ProbeContext> {
+	const ctx: ProbeContext = { credentialsPresent: credentialsPresent(), httpTimeoutMs: DOCTOR_MODEL_PROBE_TIMEOUT_MS };
+	if (!targetRequiresAuth(target, runtime)) return ctx;
+	try {
+		const resolution = await openAuthStorage().resolveForTarget(resolveAuthTarget(target, runtime), {
+			includeFallback: false,
+		});
+		if (resolution.apiKey) ctx.authToken = resolution.apiKey;
+	} catch {
+		// The probe reports its own missing-auth failure; the wireModels fallback covers the check.
+	}
+	return ctx;
+}
+
+/** What the target advertises now, or null when it could not be asked. */
+async function probeAdvertisedModels(
+	target: TargetDescriptor,
+	runtime: RuntimeDescriptor,
+): Promise<{ advertised: string[]; resident: string[] } | null> {
+	if (runtime.kind !== "http" || typeof runtime.probe !== "function" || !target.url) return null;
+	let probe: ProbeResult;
+	try {
+		probe = await runtime.probe(target, await doctorProbeContext(target, runtime));
+	} catch {
+		return null;
+	}
+	if (!probe.ok || !probe.models || probe.models.length === 0) return null;
+	const advertised = [...probe.models];
+	const resident: string[] = [];
+	for (const [id, status] of Object.entries(probe.modelStates ?? {})) {
+		if (!advertised.includes(id)) advertised.push(id);
+		if (status.state === "loaded" || status.state === "loading") resident.push(id);
+	}
+	return { advertised, resident };
+}
+
+/**
+ * Model sweep: every model pointer settings.yaml aims at a target with no
+ * static catalog is checked against what that target advertises. The live
+ * list wins when the target answers; the `wireModels` list configure recorded
+ * stands in when it does not, so an unreachable server still gets the
+ * placeholder id it was saved with called out. A target with neither list is
+ * a WARN, not a pass, because nothing was verified. Network-bound like the
+ * runtime sweep, so it is not part of the synchronous `runDoctor()` core.
+ */
+export async function runDoctorModelChecks(): Promise<DoctorFinding[]> {
+	let settings: ReturnType<typeof readSettings>;
+	try {
+		settings = readSettings();
+	} catch {
+		return [];
+	}
+	if (settings.targets.length === 0) return [];
+	// Every runtime descriptor and the model catalog sit behind these two
+	// imports. They are loaded here, not at module load, so a doctor run on a
+	// home with no targets (the `--fix` seed every CLI test starts from) pays
+	// nothing for a sweep it has nothing to do.
+	const [{ getRuntimeRegistry }, { registerBuiltinRuntimes }, { listKnownModelsForRuntime }] = await Promise.all([
+		import("../providers/registry.js"),
+		import("../providers/runtimes/builtins.js"),
+		import("../providers/support.js"),
+	]);
+	const registry = getRuntimeRegistry();
+	// doctor never loads the providers domain, so the registry is empty here
+	// unless another command in this process filled it.
+	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
+	const results = await Promise.all(
+		settings.targets.map(async (target): Promise<DoctorFinding | null> => {
+			const runtime = registry.get(target.runtime);
+			if (!runtime) return null;
+			// Cloud runtimes are validated against their catalog at configure time.
+			if (listKnownModelsForRuntime(runtime.id).length > 0) return null;
+			const roles = configuredModelRoles(settings, target);
+			if (roles.length === 0) return null;
+			const live = await probeAdvertisedModels(target, runtime);
+			const recorded = target.wireModels ?? [];
+			if (live === null && recorded.length === 0) {
+				return {
+					ok: true,
+					level: "warn",
+					name: `model ${target.id}`,
+					detail: `${roles.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} could not be verified: the target did not answer and configure recorded no model list; run \`clio-coder targets --probe\` once it is up`,
+				};
+			}
+			const advertised = live ? live.advertised : recorded;
+			const source = live ? `advertised by ${target.url ?? target.id} now` : "recorded by configure at last save";
+			const missing = roles.filter((entry) => !advertised.includes(entry.model));
+			if (missing.length === 0) {
+				return {
+					ok: true,
+					name: `model ${target.id}`,
+					detail: `${roles.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} ${source}`,
+				};
+			}
+			const resident = live && live.resident.length > 0 ? live.resident.join(", ") : live ? "none" : "unknown";
+			return {
+				ok: false,
+				name: `model ${target.id}`,
+				detail: `${missing.map((entry) => `${entry.role} '${entry.model}'`).join(", ")} not ${source} (${advertised.length} ids). Resident instances: ${resident}. Re-run \`clio-coder configure --id ${target.id} --model <advertised id>\`; \`clio-coder targets --probe\` lists them`,
+			};
+		}),
+	);
+	return results.filter((finding): finding is DoctorFinding => finding !== null);
+}

package/src/domains/middleware/index.ts

@@ -152,3 +152,18 @@ export type {
 	MiddlewareValidationIssue,
 } from "./validate.js";
 export { validateMiddlewareEffect, validateMiddlewareRule } from "./validate.js";
+export {
+	coalesceTurnDiff,
+	createWatchdogRegistration,
+	WATCHDOG_DIFF_MAX_BYTES,
+	WATCHDOG_PATHS_MAX,
+	WATCHDOG_REGISTRATION_ID,
+	WATCHDOG_TASK,
+	WATCHDOG_TRUNCATION_MARKER,
+	type WatchdogDeps,
+	type WatchdogRegistration,
+	type WatchdogSettingsView,
+	type WatchdogTrigger,
+	type WatchdogTriggerReason,
+	watchdogBriefing,
+} from "./watchdog.js";

package/src/domains/middleware/watchdog.ts

@@ -0,0 +1,281 @@
+/**
+ * The opt-in turn-end watchdog.
+ *
+ * A long agentic turn can leave the tree in a state nobody looked at: the
+ * model reports success, the operator reads the report, and the drift between
+ * what the board asked for and what the diff actually did stays invisible
+ * until someone reads the diff themselves. When `watchdog.enabled` is on, a
+ * turn that changed the tree is handed to one read-only verifier run briefed
+ * with the turn's coalesced diff and the board's current scope. Its blockers
+ * become one transcript notice and nothing else.
+ *
+ * What it deliberately does not do: it never auto-follows, never carries the
+ * turn onward, never queues a turn, and never mutates. A watchdog that could
+ * start work would be a second agent nobody asked for; this one can only tell
+ * the operator what it saw.
+ *
+ * The registration itself emits no middleware effects. It owns the decision of
+ * when to fire and the coalesced diff it fires with; the caller owns the
+ * dispatch and the notice.
+ */
+
+import { ToolNames } from "../../core/tool-names.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import type { MiddlewareEffect, MiddlewareHookInput } from "./types.js";
+
+export const WATCHDOG_REGISTRATION_ID = "observer.watchdog";
+
+/**
+ * Bound on the coalesced diff a watchdog briefing carries, in UTF-8 bytes. The
+ * run is meant to be cheap enough to spend on every mutating turn, so it is
+ * given the shape of the change rather than every byte of it.
+ */
+export const WATCHDOG_DIFF_MAX_BYTES = 12 * 1024;
+
+/** Bound on how many mutated paths the briefing names before it summarizes the rest. */
+export const WATCHDOG_PATHS_MAX = 40;
+
+export const WATCHDOG_TRUNCATION_MARKER = "\n[diff truncated]";
+
+/** Tools whose successful results carry a file diff worth coalescing. */
+const MUTATING_TOOL_NAMES = new Set<string>([ToolNames.Write, ToolNames.Edit, ToolNames.Artifact]);
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+export type WatchdogTriggerReason = "turn_end" | "cadence";
+
+export interface WatchdogTrigger {
+	reason: WatchdogTriggerReason;
+	/** The turn's coalesced diff, one block per mutated path in first-touch order. */
+	diff: string;
+	/** Paths the turn mutated, in first-touch order. */
+	paths: ReadonlyArray<string>;
+	/** The board's current scope, or null when the session has no task board. */
+	scope: string | null;
+	/** Tool calls seen in this turn when the trigger fired. */
+	toolCalls: number;
+}
+
+/** The live settings view the registration reads on every boundary, so a hot reload lands immediately. */
+export interface WatchdogSettingsView {
+	enabled: boolean;
+	target?: string;
+	cadenceToolCalls?: number;
+}
+
+export interface WatchdogDeps {
+	getSettings: () => Readonly<WatchdogSettingsView>;
+	/** The board's current scope line, or null when there is no board. */
+	getScope?: () => string | null;
+	/**
+	 * Dispatch the watchdog run and deliver whatever it found. Resolves when the
+	 * run has settled; the registration awaits only to know the in-flight slot is
+	 * free again, never to hold the turn.
+	 */
+	run: (trigger: WatchdogTrigger) => Promise<void>;
+	/**
+	 * False on a surface that must never fire the watchdog whatever the setting
+	 * says. Headless and ACP runs pass false: neither has an operator watching a
+	 * transcript, so a notice they cannot read is a worker run spent on nothing.
+	 */
+	firesOnThisSurface?: boolean;
+}
+
+export interface WatchdogRegistration extends MiddlewareHookRegistration {
+	/** Triggers dropped because a watchdog run was already in flight. */
+	droppedTriggers(): number;
+	/** True while a watchdog run is outstanding. */
+	runInFlight(): boolean;
+	/** Resolves once no watchdog run is outstanding. */
+	whenIdle(): Promise<void>;
+}
+
+function stringValue(value: unknown): string | null {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function firstPath(details: Readonly<Record<string, unknown>> | undefined): string | null {
+	const paths = details?.paths;
+	if (!Array.isArray(paths)) return null;
+	for (const entry of paths) {
+		const path = stringValue(entry);
+		if (path !== null) return path;
+	}
+	return null;
+}
+
+/**
+ * Coalesce the per-call diffs of one turn into one diff.
+ *
+ * Per-path last-write-wins, in first-touch order. A turn that edited one file
+ * six times produced six diffs against six different base contents; replaying
+ * all of them tells a reviewer the history of the edit rather than its result,
+ * and the result is what the reviewer is being asked about.
+ */
+export function coalesceTurnDiff(
+	byPath: ReadonlyMap<string, string>,
+	maxBytes: number = WATCHDOG_DIFF_MAX_BYTES,
+): string {
+	const blocks: string[] = [];
+	let index = 0;
+	for (const [path, diff] of byPath) {
+		if (index >= WATCHDOG_PATHS_MAX) {
+			blocks.push(`[${byPath.size - WATCHDOG_PATHS_MAX} more changed path(s) omitted]`);
+			break;
+		}
+		blocks.push(`--- ${path}\n${diff}`);
+		index += 1;
+	}
+	const whole = blocks.join("\n\n");
+	if (Buffer.byteLength(whole, "utf8") <= maxBytes) return whole;
+	const room = Math.max(0, maxBytes - Buffer.byteLength(WATCHDOG_TRUNCATION_MARKER, "utf8"));
+	const buffer = Buffer.from(whole, "utf8");
+	let cut = Math.min(room, buffer.byteLength);
+	while (cut > 0) {
+		const next = buffer[cut];
+		if (next === undefined || (next & 0xc0) !== 0x80) break;
+		cut -= 1;
+	}
+	return `${buffer.subarray(0, cut).toString("utf8")}${WATCHDOG_TRUNCATION_MARKER}`;
+}
+
+/** The bounded, fixed task every watchdog run is given. It never varies with the diff. */
+export const WATCHDOG_TASK =
+	"Review the coalesced diff in the briefing against the scope it names. Report one check per concern: " +
+	"a change outside the stated scope, a change the scope required that the diff does not make, or a defect " +
+	"visible in the diff itself. Run no commands and change nothing.";
+
+/** The briefing body a watchdog run receives. Data, never instructions. */
+export function watchdogBriefing(trigger: WatchdogTrigger): string {
+	const scope = trigger.scope === null ? "(no task board; scope is unstated)" : trigger.scope;
+	const paths = trigger.paths.length === 0 ? "(none)" : trigger.paths.join("\n");
+	return [
+		"## Current scope",
+		scope,
+		"",
+		"## Changed paths",
+		paths,
+		"",
+		"## Coalesced diff for this turn",
+		trigger.diff,
+	].join("\n");
+}
+
+/**
+ * Build the registration. It is hooked on `after_tool` and `turn_end`:
+ * `after_tool` is where the diffs and the tool count come from, and `turn_end`
+ * is the boundary a mutating turn fires on.
+ */
+export function createWatchdogRegistration(deps: WatchdogDeps): WatchdogRegistration {
+	const diffByPath = new Map<string, string>();
+	let toolCalls = 0;
+	let dropped = 0;
+	let inFlight = false;
+	let outstanding: Promise<void> = Promise.resolve();
+
+	const active = (): WatchdogSettingsView | null => {
+		if (deps.firesOnThisSurface === false) return null;
+		let settings: Readonly<WatchdogSettingsView>;
+		try {
+			settings = deps.getSettings();
+		} catch {
+			return null;
+		}
+		return settings.enabled ? settings : null;
+	};
+
+	const resetTurn = (): void => {
+		diffByPath.clear();
+		toolCalls = 0;
+	};
+
+	const fire = (reason: WatchdogTriggerReason): void => {
+		if (diffByPath.size === 0) return;
+		// One run at a time. A watchdog slower than the turns that trigger it must
+		// not queue: a queued review describes a tree that has already moved on,
+		// and a backlog of them would outlive the session. The drop is counted so
+		// a starved cadence and a quiet one stay distinguishable.
+		if (inFlight) {
+			dropped += 1;
+			return;
+		}
+		const trigger: WatchdogTrigger = {
+			reason,
+			diff: coalesceTurnDiff(diffByPath),
+			paths: [...diffByPath.keys()].slice(0, WATCHDOG_PATHS_MAX),
+			scope: scopeNow(),
+			toolCalls,
+		};
+		inFlight = true;
+		// Started synchronously, so the in-flight slot is genuinely taken before
+		// this hook returns. Deferring the start to a microtask would let two
+		// triggers in the same tool batch both find the slot free.
+		let started: Promise<void>;
+		try {
+			started = deps.run(trigger);
+		} catch {
+			inFlight = false;
+			return;
+		}
+		outstanding = started
+			.catch(() => {
+				// A failed watchdog run is not a failed turn. The run's own reporting
+				// path already told the operator whatever it could.
+			})
+			.finally(() => {
+				inFlight = false;
+			});
+	};
+
+	const scopeNow = (): string | null => {
+		try {
+			return deps.getScope?.() ?? null;
+		} catch {
+			return null;
+		}
+	};
+
+	return {
+		id: WATCHDOG_REGISTRATION_ID,
+		description: "review a mutating turn's coalesced diff against the board scope with a read-only verifier run",
+		hooks: ["after_tool", "turn_end"],
+		evaluate(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
+			const settings = active();
+			if (settings === null) {
+				// Still clear turn state so a mid-session disable cannot leave a diff
+				// behind that a later enable would fire on.
+				if (input.hook === "turn_end") resetTurn();
+				return NO_EFFECTS;
+			}
+			if (input.hook === "after_tool") {
+				toolCalls += 1;
+				recordMutation(input);
+				const cadence = settings.cadenceToolCalls;
+				// Mid-turn cadence keeps accumulating: turn end still reviews the whole
+				// turn, not just what landed after the last cadence firing.
+				if (cadence !== undefined && cadence >= 1 && toolCalls % cadence === 0) fire("cadence");
+				return NO_EFFECTS;
+			}
+			if (input.hook !== "turn_end") return NO_EFFECTS;
+			// A turn with no file mutations never fires. A middleware continuation
+			// re-evaluates turn_end with the accumulator already cleared, so it
+			// cannot fire a second run for the same change either.
+			fire("turn_end");
+			resetTurn();
+			return NO_EFFECTS;
+		},
+		droppedTriggers: () => dropped,
+		runInFlight: () => inFlight,
+		whenIdle: () => outstanding,
+	};
+
+	function recordMutation(input: MiddlewareHookInput): void {
+		if (input.metadata?.resultKind !== "ok") return;
+		if (input.toolName === undefined || !MUTATING_TOOL_NAMES.has(input.toolName)) return;
+		const diff = stringValue(input.toolResultDetails?.diff);
+		if (diff === null) return;
+		// Map.set on an existing key keeps its insertion position, so the newest
+		// diff for a path wins while the path keeps its first-touch order.
+		diffByPath.set(firstPath(input.toolResultDetails) ?? input.toolName, diff);
+	}
+}

package/src/domains/observability/contract.ts

@@ -2,7 +2,7 @@ import type { ResponseModelIdObservationCounts } from "../../core/response-model
 import type { TargetStatus } from "../providers/contract.js";
 import type { CostProvenance } from "../providers/index.js";
 import type { AccountabilitySummary } from "./accountability.js";
-import type { CostAggregate, CostEntry, UsageBreakdown } from "./cost.js";
+import type { CostAggregate, CostEntry, CostEntryLabel, UsageBreakdown } from "./cost.js";
 import type { MetricsView } from "./metrics.js";
 import type { TelemetrySnapshot } from "./telemetry.js";
 import type { SessionTurnTrace } from "./trace-store.js";
@@ -142,6 +142,8 @@ export interface ObservabilityContract {
 			requestedModelIds: ReadonlyArray<string>;
 			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
 		},
+		/** Marks a priced call that was not an ordinary turn, such as a `/btw` side question. */
+		label?: CostEntryLabel,
 	): void;
 	/** Record final output token throughput for one completed assistant stream. */
 	recordTokenThroughput(snapshot: TokenThroughputSnapshot): void;

package/src/domains/observability/cost.ts

@@ -111,6 +111,13 @@ export interface UsageBreakdown {
 	apiCalls?: number;
 }
 
+/**
+ * What produced a priced call, when it was not an ordinary turn. `/cost` and
+ * the usage surfaces separate these out so an operator can see that money was
+ * spent beside the session rather than inside it.
+ */
+export type CostEntryLabel = "side-question" | "handoff";
+
 export interface CostEntry {
 	providerId: string;
 	attributedModelId: string;
@@ -125,6 +132,8 @@ export interface CostEntry {
 	cacheWrite: number;
 	reasoningTokens: number;
 	apiCalls?: number;
+	/** Absent on an ordinary turn's call. */
+	label?: CostEntryLabel;
 }
 
 export interface CostTracker {
@@ -139,6 +148,7 @@ export interface CostTracker {
 			requestedModelIds: ReadonlyArray<string>;
 			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
 		},
+		label?: CostEntryLabel,
 	): number;
 	sessionTotal(): number;
 	sessionCost(): CostAggregate;
@@ -156,7 +166,7 @@ export function createCostTracker(): CostTracker {
 	let total = 0;
 	const totals = emptyBreakdown();
 	return {
-		accumulate(providerId, attributedModelId, tokens, usd, breakdown, costProvenance, modelIdFacts) {
+		accumulate(providerId, attributedModelId, tokens, usd, breakdown, costProvenance, modelIdFacts, label) {
 			const resolvedUsd = usd ?? 0;
 			const provenance = normalizeCostProvenance(costProvenance);
 			const input = breakdown?.input ?? 0;
@@ -186,6 +196,7 @@ export function createCostTracker(): CostTracker {
 				cacheWrite,
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
+				...(label !== undefined ? { label } : {}),
 			});
 			total += resolvedUsd;
 			totals.input += input;

package/src/domains/observability/extension.ts

@@ -259,9 +259,9 @@ export function createObservabilityBundle(
 			latestThroughput = null;
 			projection.refresh();
 		},
-		recordTokens(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts) {
+		recordTokens(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label) {
 			telemetry.record("counter", "tokens.total", tokens);
-			cost.accumulate(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts);
+			cost.accumulate(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label);
 			projection.refresh();
 		},
 		recordSessionTurn(sessionTurn) {

package/src/domains/observability/index.ts

@@ -30,6 +30,7 @@ export {
 	type CostAggregate,
 	type CostAmount,
 	type CostEntry,
+	type CostEntryLabel,
 	costAggregateForAmount,
 	costWasMeasured,
 	emptyCostAggregate,
@@ -40,6 +41,15 @@ export type { EvidenceIndexRow } from "./evidence-index.js";
 export { EVIDENCE_INDEX_FILE, MAX_EVIDENCE_INDEX_ROWS, readEvidenceIndex } from "./evidence-index.js";
 export { ObservabilityManifest } from "./manifest.js";
 export type { MetricsView } from "./metrics.js";
+export type { OutOfTurnUsage, OutOfTurnUsageReadResult, OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+export {
+	appendOutOfTurnUsageRow,
+	MAX_OUT_OF_TURN_USAGE_ROWS,
+	OUT_OF_TURN_USAGE_DIR,
+	OUT_OF_TURN_USAGE_FILE,
+	outOfTurnUsagePath,
+	readOutOfTurnUsageRows,
+} from "./out-of-turn-usage.js";
 export type { ObservabilityProjection, ProjectionReadModel } from "./projection.js";
 export {
 	createObservabilityProjection,