zidane 7.2.4 → 8.0.4

package/dist/run-summary-CklLiZ4y.js

@@ -0,0 +1,288 @@
+import { i as statsByModel } from "./stats-DAKBEKjc.js";
+//#region src/run-summary-hooks.ts
+function createRunSummaryInstallState() {
+	return {
+		runId: void 0,
+		parentRunId: void 0,
+		depth: 0,
+		agentName: void 0,
+		startedAt: Date.now(),
+		aborted: false,
+		errors: [],
+		blocks: [],
+		validationRejects: [],
+		budgetEvents: [],
+		repeatGuardEvents: [],
+		streamRetries: [],
+		pairingRepairs: {},
+		children: []
+	};
+}
+function resetForNewRun(state) {
+	const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs, children } = state;
+	state.aborted = false;
+	errors.length = 0;
+	blocks.length = 0;
+	validationRejects.length = 0;
+	budgetEvents.length = 0;
+	repeatGuardEvents.length = 0;
+	streamRetries.length = 0;
+	for (const k of Object.keys(pairingRepairs)) delete pairingRepairs[k];
+	children.length = 0;
+}
+/** Every incident-recording handler, `agent:start` through `pairing:repair`. */
+function installRunSummaryEventHooks(hooks, unregisters, state) {
+	const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs } = state;
+	unregisters.push(hooks.hook("agent:start", (ctx) => {
+		resetForNewRun(state);
+		state.runId = ctx.runId;
+		state.parentRunId = ctx.parentRunId;
+		state.depth = ctx.depth;
+		state.agentName = ctx.agentName;
+		state.startedAt = ctx.startedAt;
+	}));
+	unregisters.push(hooks.hook("agent:abort", () => {
+		state.aborted = true;
+	}));
+	unregisters.push(hooks.hook("stream:retry", (ctx) => {
+		const msg = ctx.err instanceof Error ? ctx.err.message : String(ctx.err);
+		streamRetries.push({
+			attempt: ctx.attempt,
+			delayMs: ctx.delayMs,
+			message: msg,
+			...ctx.err instanceof Error ? { errorType: ctx.err.name } : {},
+			...ctx.statusCode !== void 0 ? { statusCode: ctx.statusCode } : {},
+			...ctx.requestId !== void 0 ? { requestId: ctx.requestId } : {},
+			turnId: ctx.turnId
+		});
+	}));
+	unregisters.push(hooks.hook("stream:error", (ctx) => {
+		const msg = ctx.err instanceof Error ? ctx.err.message : String(ctx.err);
+		const errorType = ctx.err instanceof Error ? ctx.err.name : "unknown";
+		errors.push({
+			kind: "stream",
+			message: msg,
+			errorType,
+			turnId: ctx.turnId,
+			...ctx.statusCode !== void 0 ? { statusCode: ctx.statusCode } : {},
+			...ctx.requestId !== void 0 ? { requestId: ctx.requestId } : {}
+		});
+	}));
+	unregisters.push(hooks.hook("tool:error", (ctx) => {
+		errors.push({
+			kind: "tool",
+			message: ctx.error.message,
+			errorType: ctx.error.name,
+			turnId: ctx.turnId,
+			callId: ctx.callId,
+			toolName: ctx.name
+		});
+	}));
+	unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+		errors.push({
+			kind: "mcp-tool",
+			message: ctx.error.message,
+			errorType: ctx.error.name,
+			turnId: ctx.turnId,
+			callId: ctx.callId,
+			server: ctx.server,
+			toolName: ctx.displayName
+		});
+	}));
+	unregisters.push(hooks.hook("mcp:error", (ctx) => {
+		errors.push({
+			kind: "mcp",
+			message: ctx.error.message,
+			errorType: ctx.error.name,
+			server: ctx.name
+		});
+	}));
+	unregisters.push(hooks.hook("spawn:error", (ctx) => {
+		errors.push({
+			kind: "spawn",
+			message: ctx.error.message,
+			errorType: ctx.error.name,
+			childId: ctx.id
+		});
+	}));
+	unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+		if (ctx.outcome === "gate-block" || ctx.outcome === "unknown" || ctx.outcome === "invalid-input") blocks.push({
+			callId: ctx.callId,
+			toolName: ctx.name,
+			outcome: ctx.outcome,
+			...ctx.reason ? { reason: ctx.reason } : {}
+		});
+	}));
+	unregisters.push(hooks.hook("validation:reject", (ctx) => {
+		validationRejects.push({
+			callId: ctx.callId,
+			toolName: ctx.name,
+			reason: ctx.reason
+		});
+	}));
+	unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+		budgetEvents.push({
+			kind: "bytes",
+			observed: ctx.bytes,
+			limit: ctx.budget,
+			turnId: ctx.turnId
+		});
+	}));
+	unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+		budgetEvents.push({
+			kind: "tool-count",
+			toolName: ctx.tool,
+			mode: ctx.mode,
+			observed: ctx.count,
+			limit: ctx.max,
+			turnId: ctx.turnId
+		});
+	}));
+	unregisters.push(hooks.hook("repeat-guard:exceeded", (ctx) => {
+		repeatGuardEvents.push({
+			toolName: ctx.tool,
+			count: ctx.count,
+			threshold: ctx.threshold,
+			action: ctx.action,
+			turnId: ctx.turnId
+		});
+	}));
+	unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+		pairingRepairs[ctx.mode] = (pairingRepairs[ctx.mode] ?? 0) + 1;
+	}));
+}
+/** `agent:done` — assemble the {@link RunSummary} and hand it off. */
+function installRunSummaryDoneHook(hooks, unregisters, state, shared, options) {
+	const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs, children } = state;
+	unregisters.push(hooks.hook("agent:done", (stats) => {
+		const { runId, parentRunId, depth, agentName, startedAt, aborted } = state;
+		const endedAt = Date.now();
+		const byModel = [];
+		for (const [modelId, usage] of statsByModel(stats)) byModel.push({
+			modelId,
+			input: usage.input,
+			output: usage.output,
+			cacheRead: usage.cacheRead,
+			cacheCreation: usage.cacheCreation,
+			cost: usage.cost,
+			turns: usage.turns
+		});
+		for (const c of stats.children ?? []) children.push(minimalSummaryFromStats(c.stats, {
+			depth: c.depth ?? depth + 1,
+			status: c.status === "aborted" ? "aborted" : "completed"
+		}));
+		const summary = {
+			...runId ? { runId } : {},
+			...parentRunId ? { parentRunId } : {},
+			depth,
+			...agentName ? { agentName } : {},
+			startedAt,
+			endedAt,
+			durationMs: endedAt - startedAt,
+			status: aborted ? "aborted" : "completed",
+			turns: stats.turns,
+			totals: buildTotals(stats),
+			byModel,
+			errors: errors.slice(),
+			blocks: blocks.slice(),
+			validationRejects: validationRejects.slice(),
+			budgetEvents: budgetEvents.slice(),
+			streamRetries: streamRetries.slice(),
+			repeatGuardEvents: repeatGuardEvents.slice(),
+			pairingRepairs: { ...pairingRepairs },
+			...children.length > 0 ? { children: children.slice() } : {}
+		};
+		shared.last = summary;
+		try {
+			options.onSummary?.(summary);
+		} catch {}
+	}));
+}
+function buildTotals(stats) {
+	return {
+		input: stats.totalIn,
+		output: stats.totalOut,
+		cacheRead: stats.totalCacheRead,
+		cacheCreation: stats.totalCacheCreation,
+		...typeof stats.cost === "number" ? { cost: stats.cost } : {},
+		...typeof stats.timeTillFirstTokenMs === "number" ? { ttftMs: stats.timeTillFirstTokenMs } : {}
+	};
+}
+function minimalSummaryFromStats(stats, meta) {
+	const byModel = [];
+	for (const [modelId, usage] of statsByModel(stats)) byModel.push({
+		modelId,
+		input: usage.input,
+		output: usage.output,
+		cacheRead: usage.cacheRead,
+		cacheCreation: usage.cacheCreation,
+		cost: usage.cost,
+		turns: usage.turns
+	});
+	const children = [];
+	for (const c of stats.children ?? []) children.push(minimalSummaryFromStats(c.stats, {
+		depth: c.depth ?? meta.depth + 1,
+		status: c.status === "aborted" ? "aborted" : "completed"
+	}));
+	return {
+		depth: meta.depth,
+		startedAt: 0,
+		endedAt: 0,
+		durationMs: stats.elapsed,
+		status: meta.status,
+		turns: stats.turns,
+		totals: buildTotals(stats),
+		byModel,
+		errors: [],
+		blocks: [],
+		validationRejects: [],
+		budgetEvents: [],
+		streamRetries: [],
+		repeatGuardEvents: [],
+		pairingRepairs: {},
+		...children.length > 0 ? { children } : {}
+	};
+}
+//#endregion
+//#region src/run-summary.ts
+/**
+* Build a run-summary collector. State is created fresh inside each
+* `install()` call, so a single collector instance can be installed
+* across multiple agents without attribution cross-talk. `latest()`
+* returns the most-recent summary across **any** install — install
+* per-agent collectors if you need separate post-run snapshots.
+*
+* @example
+* ```ts
+* const collector = createRunSummaryCollector({
+*   onSummary: s => console.log(JSON.stringify(s)),
+* })
+* const uninstall = collector.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*/
+function createRunSummaryCollector(options = {}) {
+	const shared = { last: void 0 };
+	return {
+		latest: () => shared.last,
+		install(hooks) {
+			const state = createRunSummaryInstallState();
+			const unregisters = [];
+			installRunSummaryEventHooks(hooks, unregisters, state);
+			installRunSummaryDoneHook(hooks, unregisters, state, shared, options);
+			let disposed = false;
+			return function uninstall() {
+				if (disposed) return;
+				disposed = true;
+				for (const un of unregisters) try {
+					un();
+				} catch {}
+			};
+		}
+	};
+}
+//#endregion
+export { createRunSummaryCollector as t };
+
+//# sourceMappingURL=run-summary-CklLiZ4y.js.map

package/dist/run-summary-CklLiZ4y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-summary-CklLiZ4y.js","names":[],"sources":["../src/run-summary-hooks.ts","../src/run-summary.ts"],"sourcesContent":["/**\n * Hook-group installers behind {@link createRunSummaryCollector}\n * (`./run-summary`).\n *\n * Each installer registers one contiguous slice of the original\n * registration sequence and pushes its unregister fns onto the shared\n * `unregisters` array, so calling them in order reproduces the exact\n * hook registration order of the single-function original.\n */\n\nimport type { Hookable } from 'hookable'\nimport type { AgentHooks } from './agent'\nimport type {\n  RunSummary,\n  RunSummaryBlock,\n  RunSummaryBudget,\n  RunSummaryByModel,\n  RunSummaryCollectorOptions,\n  RunSummaryError,\n  RunSummaryRepeatGuard,\n  RunSummaryRetry,\n  RunSummaryTokens,\n  RunSummaryValidation,\n} from './run-summary'\nimport type { AgentStats } from './types'\nimport { statsByModel } from './stats'\n\n/**\n * Per-run in-progress accumulators. The hookable bus serializes\n * agent.run lifecycles per agent — we reset between runs on\n * `agent:start` and consume on `agent:done`.\n */\nexport interface RunSummaryInstallState {\n  runId: string | undefined\n  parentRunId: string | undefined\n  depth: number\n  agentName: string | undefined\n  startedAt: number\n  aborted: boolean\n  readonly errors: RunSummaryError[]\n  readonly blocks: RunSummaryBlock[]\n  readonly validationRejects: RunSummaryValidation[]\n  readonly budgetEvents: RunSummaryBudget[]\n  readonly repeatGuardEvents: RunSummaryRepeatGuard[]\n  readonly streamRetries: RunSummaryRetry[]\n  readonly pairingRepairs: Record<string, number>\n  readonly children: RunSummary[]\n}\n\n/** Collector-wide (cross-install) state: the most-recent summary. */\nexport interface RunSummaryShared {\n  last: RunSummary | undefined\n}\n\nexport function createRunSummaryInstallState(): RunSummaryInstallState {\n  return {\n    runId: undefined,\n    parentRunId: undefined,\n    depth: 0,\n    agentName: undefined,\n    startedAt: Date.now(),\n    aborted: false,\n    errors: [],\n    blocks: [],\n    validationRejects: [],\n    budgetEvents: [],\n    repeatGuardEvents: [],\n    streamRetries: [],\n    pairingRepairs: {},\n    children: [],\n  }\n}\n\nfunction resetForNewRun(state: RunSummaryInstallState): void {\n  const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs, children } = state\n  state.aborted = false\n  errors.length = 0\n  blocks.length = 0\n  validationRejects.length = 0\n  budgetEvents.length = 0\n  repeatGuardEvents.length = 0\n  streamRetries.length = 0\n  for (const k of Object.keys(pairingRepairs))\n    delete pairingRepairs[k]\n  children.length = 0\n}\n\n/** Every incident-recording handler, `agent:start` through `pairing:repair`. */\nexport function installRunSummaryEventHooks(\n  hooks: Hookable<AgentHooks>,\n  unregisters: Array<() => void>,\n  state: RunSummaryInstallState,\n): void {\n  const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs } = state\n\n  unregisters.push(hooks.hook('agent:start', (ctx) => {\n    resetForNewRun(state)\n    state.runId = ctx.runId\n    state.parentRunId = ctx.parentRunId\n    state.depth = ctx.depth\n    state.agentName = ctx.agentName\n    state.startedAt = ctx.startedAt\n  }))\n\n  unregisters.push(hooks.hook('agent:abort', () => {\n    state.aborted = true\n  }))\n\n  unregisters.push(hooks.hook('stream:retry', (ctx) => {\n    const msg = ctx.err instanceof Error ? ctx.err.message : String(ctx.err)\n    streamRetries.push({\n      attempt: ctx.attempt,\n      delayMs: ctx.delayMs,\n      message: msg,\n      ...(ctx.err instanceof Error ? { errorType: ctx.err.name } : {}),\n      ...(ctx.statusCode !== undefined ? { statusCode: ctx.statusCode } : {}),\n      ...(ctx.requestId !== undefined ? { requestId: ctx.requestId } : {}),\n      turnId: ctx.turnId,\n    })\n  }))\n\n  unregisters.push(hooks.hook('stream:error', (ctx) => {\n    const msg = ctx.err instanceof Error ? ctx.err.message : String(ctx.err)\n    const errorType = ctx.err instanceof Error ? ctx.err.name : 'unknown'\n    errors.push({\n      kind: 'stream',\n      message: msg,\n      errorType,\n      turnId: ctx.turnId,\n      ...(ctx.statusCode !== undefined ? { statusCode: ctx.statusCode } : {}),\n      ...(ctx.requestId !== undefined ? { requestId: ctx.requestId } : {}),\n    })\n  }))\n\n  unregisters.push(hooks.hook('tool:error', (ctx) => {\n    errors.push({\n      kind: 'tool',\n      message: ctx.error.message,\n      errorType: ctx.error.name,\n      turnId: ctx.turnId,\n      callId: ctx.callId,\n      toolName: ctx.name,\n    })\n  }))\n\n  unregisters.push(hooks.hook('mcp:tool:error', (ctx) => {\n    errors.push({\n      kind: 'mcp-tool',\n      message: ctx.error.message,\n      errorType: ctx.error.name,\n      turnId: ctx.turnId,\n      callId: ctx.callId,\n      server: ctx.server,\n      toolName: ctx.displayName,\n    })\n  }))\n\n  unregisters.push(hooks.hook('mcp:error', (ctx) => {\n    errors.push({\n      kind: 'mcp',\n      message: ctx.error.message,\n      errorType: ctx.error.name,\n      server: ctx.name,\n    })\n  }))\n\n  unregisters.push(hooks.hook('spawn:error', (ctx) => {\n    errors.push({\n      kind: 'spawn',\n      message: ctx.error.message,\n      errorType: ctx.error.name,\n      childId: ctx.id,\n    })\n  }))\n\n  unregisters.push(hooks.hook('tool:dispatched', (ctx) => {\n    if (ctx.outcome === 'gate-block' || ctx.outcome === 'unknown' || ctx.outcome === 'invalid-input') {\n      blocks.push({\n        callId: ctx.callId,\n        toolName: ctx.name,\n        outcome: ctx.outcome,\n        ...(ctx.reason ? { reason: ctx.reason } : {}),\n      })\n    }\n  }))\n\n  unregisters.push(hooks.hook('validation:reject', (ctx) => {\n    validationRejects.push({\n      callId: ctx.callId,\n      toolName: ctx.name,\n      reason: ctx.reason,\n    })\n  }))\n\n  unregisters.push(hooks.hook('budget:exceeded', (ctx) => {\n    budgetEvents.push({\n      kind: 'bytes',\n      observed: ctx.bytes,\n      limit: ctx.budget,\n      turnId: ctx.turnId,\n    })\n  }))\n\n  unregisters.push(hooks.hook('tool-budget:exceeded', (ctx) => {\n    budgetEvents.push({\n      kind: 'tool-count',\n      toolName: ctx.tool,\n      mode: ctx.mode,\n      observed: ctx.count,\n      limit: ctx.max,\n      turnId: ctx.turnId,\n    })\n  }))\n\n  unregisters.push(hooks.hook('repeat-guard:exceeded', (ctx) => {\n    repeatGuardEvents.push({\n      toolName: ctx.tool,\n      count: ctx.count,\n      threshold: ctx.threshold,\n      action: ctx.action,\n      turnId: ctx.turnId,\n    })\n  }))\n\n  unregisters.push(hooks.hook('pairing:repair', (ctx) => {\n    pairingRepairs[ctx.mode] = (pairingRepairs[ctx.mode] ?? 0) + 1\n  }))\n}\n\n/** `agent:done` — assemble the {@link RunSummary} and hand it off. */\nexport function installRunSummaryDoneHook(\n  hooks: Hookable<AgentHooks>,\n  unregisters: Array<() => void>,\n  state: RunSummaryInstallState,\n  shared: RunSummaryShared,\n  options: RunSummaryCollectorOptions,\n): void {\n  const { errors, blocks, validationRejects, budgetEvents, repeatGuardEvents, streamRetries, pairingRepairs, children } = state\n\n  unregisters.push(hooks.hook('agent:done', (stats) => {\n    const { runId, parentRunId, depth, agentName, startedAt, aborted } = state\n    const endedAt = Date.now()\n\n    // Build per-model rollup via the existing `statsByModel` helper\n    // so we stay in lockstep with how the rest of the harness\n    // attributes cost and tokens by model id.\n    const byModel: RunSummaryByModel[] = []\n    for (const [modelId, usage] of statsByModel(stats)) {\n      byModel.push({\n        modelId,\n        input: usage.input,\n        output: usage.output,\n        cacheRead: usage.cacheRead,\n        cacheCreation: usage.cacheCreation,\n        cost: usage.cost,\n        turns: usage.turns,\n      })\n    }\n\n    // Flatten child stats into nested summaries. We don't have the\n    // child's full event lists here (those landed on the child's\n    // own hooks), so the nested entry is a minimal totals-only\n    // record — enough for a flat per-run audit trail; consumers\n    // wanting full per-child event lists install a collector on\n    // each subagent.\n    for (const c of stats.children ?? []) {\n      children.push(minimalSummaryFromStats(c.stats, {\n        depth: c.depth ?? depth + 1,\n        status: c.status === 'aborted' ? 'aborted' : 'completed',\n      }))\n    }\n\n    const summary: RunSummary = {\n      ...(runId ? { runId } : {}),\n      ...(parentRunId ? { parentRunId } : {}),\n      depth,\n      ...(agentName ? { agentName } : {}),\n      startedAt,\n      endedAt,\n      durationMs: endedAt - startedAt,\n      status: aborted ? 'aborted' : 'completed',\n      turns: stats.turns,\n      totals: buildTotals(stats),\n      byModel,\n      errors: errors.slice(),\n      blocks: blocks.slice(),\n      validationRejects: validationRejects.slice(),\n      budgetEvents: budgetEvents.slice(),\n      streamRetries: streamRetries.slice(),\n      repeatGuardEvents: repeatGuardEvents.slice(),\n      pairingRepairs: { ...pairingRepairs },\n      ...(children.length > 0 ? { children: children.slice() } : {}),\n    }\n\n    shared.last = summary\n    try {\n      options.onSummary?.(summary)\n    }\n    catch {\n      // Sink errors are not the collector's concern.\n    }\n  }))\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction buildTotals(stats: AgentStats): RunSummaryTokens {\n  return {\n    input: stats.totalIn,\n    output: stats.totalOut,\n    cacheRead: stats.totalCacheRead,\n    cacheCreation: stats.totalCacheCreation,\n    ...(typeof stats.cost === 'number' ? { cost: stats.cost } : {}),\n    ...(typeof stats.timeTillFirstTokenMs === 'number' ? { ttftMs: stats.timeTillFirstTokenMs } : {}),\n  }\n}\n\nfunction minimalSummaryFromStats(\n  stats: AgentStats,\n  meta: { depth: number, status: 'completed' | 'aborted' },\n): RunSummary {\n  const byModel: RunSummaryByModel[] = []\n  for (const [modelId, usage] of statsByModel(stats)) {\n    byModel.push({\n      modelId,\n      input: usage.input,\n      output: usage.output,\n      cacheRead: usage.cacheRead,\n      cacheCreation: usage.cacheCreation,\n      cost: usage.cost,\n      turns: usage.turns,\n    })\n  }\n  const children: RunSummary[] = []\n  for (const c of stats.children ?? []) {\n    children.push(minimalSummaryFromStats(c.stats, {\n      depth: c.depth ?? meta.depth + 1,\n      status: c.status === 'aborted' ? 'aborted' : 'completed',\n    }))\n  }\n  return {\n    depth: meta.depth,\n    startedAt: 0,\n    endedAt: 0,\n    durationMs: stats.elapsed,\n    status: meta.status,\n    turns: stats.turns,\n    totals: buildTotals(stats),\n    byModel,\n    errors: [],\n    blocks: [],\n    validationRejects: [],\n    budgetEvents: [],\n    streamRetries: [],\n    repeatGuardEvents: [],\n    pairingRepairs: {},\n    ...(children.length > 0 ? { children } : {}),\n  }\n}\n","/**\n * Run summary collector — one JSON postmortem per `agent.run()`.\n *\n * `AgentStats` is great for billing and per-turn accounting but doesn't\n * carry a record of the *interesting* events that happened during a run\n * (errors, gate blocks, validation rejects, budget hits, MCP failures).\n * Reconstructing that from a hook stream after the fact is exactly the\n * kind of plumbing every consumer ends up re-implementing.\n *\n * This module ships:\n *\n * - {@link RunSummary} — a serializable shape that bundles totals,\n *   per-model breakdown, and all the per-run incident lists.\n * - {@link createRunSummaryCollector} — installs hook listeners that\n *   build up a {@link RunSummary} during the run and surfaces it on\n *   `agent:done`. Calls an optional `onSummary` callback so the host can\n *   forward to a log aggregator / DB / postmortem dashboard without\n *   touching `agent.run()`'s return value.\n *\n * The collector is purely additive — it doesn't touch the agent loop,\n * doesn't change return shapes, and doesn't suppress any other hook\n * handlers. Drop it in alongside tracing / metrics / logging or use it\n * standalone when you only need the summary.\n */\n\nimport type { Hookable } from 'hookable'\nimport type { AgentHooks } from './agent'\nimport type { RunSummaryShared } from './run-summary-hooks'\nimport { createRunSummaryInstallState, installRunSummaryDoneHook, installRunSummaryEventHooks } from './run-summary-hooks'\n\n// ---------------------------------------------------------------------------\n// Public shape\n// ---------------------------------------------------------------------------\n\nexport interface RunSummaryTokens {\n  input: number\n  output: number\n  cacheRead: number\n  cacheCreation: number\n  cost?: number\n  /** First observable byte from the provider, ms from run start. */\n  ttftMs?: number\n}\n\nexport interface RunSummaryByModel {\n  modelId: string\n  input: number\n  output: number\n  cacheRead: number\n  cacheCreation: number\n  cost: number\n  turns: number\n}\n\nexport interface RunSummaryError {\n  kind: 'stream' | 'tool' | 'mcp-tool' | 'mcp' | 'spawn'\n  message: string\n  errorType?: string\n  turnId?: string\n  callId?: string\n  server?: string\n  toolName?: string\n  childId?: string\n  statusCode?: number\n  requestId?: string\n}\n\nexport interface RunSummaryBlock {\n  callId: string\n  toolName: string\n  outcome: 'gate-block' | 'unknown' | 'invalid-input'\n  reason?: string\n}\n\nexport interface RunSummaryValidation {\n  callId: string\n  toolName: string\n  reason: string\n}\n\nexport interface RunSummaryBudget {\n  kind: 'bytes' | 'tool-count'\n  /** Tool name (for `'tool-count'`); absent for byte budgets. */\n  toolName?: string\n  /** `mode` for `'tool-count'`; absent for byte budgets. */\n  mode?: 'steer' | 'block'\n  observed: number\n  limit: number\n  turnId?: string\n}\n\nexport interface RunSummaryRepeatGuard {\n  toolName: string\n  /** Observed repeat count that tripped the guard. */\n  count: number\n  threshold: number\n  action: 'block' | 'steer' | 'abort'\n  turnId?: string\n}\n\n/**\n * One absorbed provider-stream retry. Retries are invisible in the transcript\n * (no turn, no tool result) yet their backoff is real wall time the user\n * waited — measured in production as unexplained 30-90s gaps before trivial\n * tool calls. Recording them makes \"LLM residual\" stalls attributable.\n */\nexport interface RunSummaryRetry {\n  /** 1-based attempt number that failed and triggered this retry. */\n  attempt: number\n  /** Backoff delay taken before the next attempt (ms, after retry-after/cap). */\n  delayMs: number\n  message: string\n  errorType?: string\n  statusCode?: number\n  requestId?: string\n  turnId?: string\n}\n\n/**\n * Postmortem snapshot of one `agent.run()`. Strictly serializable — every\n * field round-trips through `JSON.stringify` / `JSON.parse` without loss\n * so a log aggregator can ingest it as-is.\n */\nexport interface RunSummary {\n  runId?: string\n  parentRunId?: string\n  depth: number\n  agentName?: string\n  startedAt: number\n  endedAt: number\n  durationMs: number\n  status: 'completed' | 'aborted'\n  turns: number\n  totals: RunSummaryTokens\n  byModel: RunSummaryByModel[]\n  errors: RunSummaryError[]\n  blocks: RunSummaryBlock[]\n  validationRejects: RunSummaryValidation[]\n  budgetEvents: RunSummaryBudget[]\n  /**\n   * Provider-stream retries the loop absorbed. Empty on healthy runs; on\n   * incident runs the summed `delayMs` explains wall time that appears\n   * nowhere else (not in turns, not in tool durations).\n   */\n  streamRetries: RunSummaryRetry[]\n  /**\n   * Repeat-guard escalations. An `action: 'steer'` entry means the tool still\n   * executed and got a steering message appended to its result. An\n   * `action: 'abort'` entry means the guard terminated the run via the agent's\n   * AbortController (the run finalizes as `'aborted'`).\n   */\n  repeatGuardEvents: RunSummaryRepeatGuard[]\n  /** Counts of pairing repairs, keyed by repair mode. */\n  pairingRepairs: Record<string, number>\n  /**\n   * Postmortem snapshots of child runs that bubbled their stats up via\n   * `spawn:complete`. Only present when the run actually spawned.\n   */\n  children?: RunSummary[]\n}\n\n// ---------------------------------------------------------------------------\n// Collector\n// ---------------------------------------------------------------------------\n\nexport interface RunSummaryCollectorOptions {\n  /**\n   * Called with the assembled {@link RunSummary} on every `agent:done`.\n   * Synchronous — heavy I/O should be deferred (e.g. via `setImmediate`).\n   */\n  onSummary?: (summary: RunSummary) => void\n}\n\nexport interface RunSummaryCollector {\n  /** Install the collector's hook handlers. Returns an uninstall fn. */\n  install: (hooks: Hookable<AgentHooks>) => () => void\n  /** Most-recent summary; `undefined` until the first `agent:done` fires. */\n  latest: () => RunSummary | undefined\n}\n\n/**\n * Build a run-summary collector. State is created fresh inside each\n * `install()` call, so a single collector instance can be installed\n * across multiple agents without attribution cross-talk. `latest()`\n * returns the most-recent summary across **any** install — install\n * per-agent collectors if you need separate post-run snapshots.\n *\n * @example\n * ```ts\n * const collector = createRunSummaryCollector({\n *   onSummary: s => console.log(JSON.stringify(s)),\n * })\n * const uninstall = collector.install(agent.hooks)\n * try { await agent.run({ prompt }) }\n * finally { uninstall() }\n * ```\n */\nexport function createRunSummaryCollector(\n  options: RunSummaryCollectorOptions = {},\n): RunSummaryCollector {\n  const shared: RunSummaryShared = { last: undefined }\n\n  return {\n    latest: () => shared.last,\n    install(hooks: Hookable<AgentHooks>): () => void {\n      // Per-run in-progress accumulators. The hookable bus serializes\n      // agent.run lifecycles per agent — we reset between runs on\n      // `agent:start` and consume on `agent:done`.\n      const state = createRunSummaryInstallState()\n\n      const unregisters: Array<() => void> = []\n\n      installRunSummaryEventHooks(hooks, unregisters, state)\n      installRunSummaryDoneHook(hooks, unregisters, state, shared, options)\n\n      let disposed = false\n      return function uninstall() {\n        if (disposed)\n          return\n        disposed = true\n        for (const un of unregisters) {\n          try {\n            un()\n          }\n          catch { /* ignore */ }\n        }\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/{sandbox-BH0WQkXn.d.ts → sandbox-C5dR5DwQ.d.ts}

@@ -1,6 +1,5 @@
-import { b as StreamHandle, m as ExecutionContext, p as ExecResult, v as ListFilesOptions, y as SpawnConfig } from "./isolation-Kfoof0MM.js";
+import { D as TerminalProcess, E as TerminalOptions, b as SpawnConfig, h as ExecutionContext, m as ExecResult, x as StreamHandle, y as ListFilesOptions } from "./isolation-D9L650W5.js";
 import { Buffer } from "node:buffer";
-
 //#region src/contexts/sandbox.d.ts
 interface SandboxProvider {
   name: string;
@@ -29,8 +28,12 @@ interface SandboxProvider {
     env?: Record<string, string>;
     signal?: AbortSignal;
   }) => Promise<StreamHandle>;
+  /** Optional interactive terminal — see {@link ExecutionContext.openTerminal}. */
+  openTerminal?: (sandboxId: string, options: TerminalOptions) => Promise<TerminalProcess>;
+  /** Re-attach to a terminal by id — see {@link ExecutionContext.reconnectTerminal}. */
+  reconnectTerminal?: (sandboxId: string, id: string, options: TerminalOptions) => Promise<TerminalProcess | null>;
 }
 declare function createSandboxContext(provider: SandboxProvider): ExecutionContext;
 //#endregion
 export { createSandboxContext as n, SandboxProvider as t };
-//# sourceMappingURL=sandbox-BH0WQkXn.d.ts.map
+//# sourceMappingURL=sandbox-C5dR5DwQ.d.ts.map

package/dist/sandbox-C5dR5DwQ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-C5dR5DwQ.d.ts","names":[],"sources":["../src/contexts/sandbox.ts"],"mappings":";;;UAgBiB;EACf;EACA,QAAQ,QAAQ,gBAAgB;IAAU;IAAY;;EACtD,OAAO,mBAAmB,iBAAiB;IAAY;IAAc,MAAM;IAAwB;QAAuB,QAAQ;EAClI,WAAW,mBAAmB,iBAAiB;EAC/C,YAAY,mBAAmB,cAAc,kBAAkB,QAAQ,WAAW,mBAAmB;EACrG,YAAY,mBAAmB,cAAc,UAAU,qBAAqB;EAC5E,UAAU,sBAAsB;;;;;;;;EAQhC,cACE,mBACA,iBACA;IAAY;IAAc,MAAM;IAAwB,SAAS;QAC9D,QAAQ;;EAEb,gBAAgB,mBAAmB,SAAS,oBAAoB,QAAQ;;EAExE,qBAAqB,mBAAmB,YAAY,SAAS,oBAAoB,QAAQ;;iBAO3E,qBAAqB,UAAU,kBAAkB"}

package/dist/session/sqlite.d.ts

@@ -1,5 +1,4 @@
-import { Zv as SessionStore } from "../index-BgN1T3lk.js";
-
+import { tx as SessionStore } from "../index-BGe1fQT7.js";
 //#region src/session/sqlite.d.ts
 interface SqliteStoreOptions {
   /** Path to the SQLite database file */

package/dist/session/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","names":[],"sources":["../../src/session/sqlite.ts"],"mappings":";;;UAsHiB,kBAAA;;EAEf,IAAI;AAAA;;;;;;iBAQU,gBAAA,CAAiB,GAAY;;;;;;;;;;;iBAe7B,iBAAA,CAAkB,GAAA,WAAc,MAAc;AAAA,iBAgB9C,iBAAA,CAAkB,OAAA,EAAS,kBAAA,GAAqB,YAAY;;;;;;;;;;;iBA6/B5D,cAAA,CAAe,MAAA,WAAiB,YAAY"}
+{"version":3,"file":"sqlite.d.ts","names":[],"sources":["../../src/session/sqlite.ts"],"mappings":";;UA+HiB;;EAEf;;;;;;;iBAQc,iBAAiB;;;;;;;;;;;iBAejB,kBAAkB,cAAc;iBAgBhC,kBAAkB,SAAS,qBAAqB;;;;;;;;;;;iBA8QhD,eAAe,iBAAiB"}