@graphorin/agent 0.5.0

package/dist/run-state/index.js

@@ -0,0 +1,311 @@
+import { RunStateMalformedError, RunStateVersionUnsupportedError } from "../errors/index.js";
+import { zeroUsage } from "@graphorin/core";
+
+//#region src/run-state/index.ts
+/**
+* Canonical schema id for serialized {@link RunState} payloads.
+*
+* @stable
+*/
+const RUN_STATE_SCHEMA_VERSION = "graphorin-run-state/1.1";
+/**
+* Reader-supported schema id range. Major version 1 only for v0.1.
+*
+* @stable
+*/
+const RUN_STATE_SCHEMA_MAJOR_SUPPORTED = 1;
+/**
+* Render a JSON-stable snapshot of the supplied {@link RunState}.
+* The returned value is plain JSON (no `Map`, `Set`, `Date`, ...).
+*
+* @stable
+*/
+function serializeRunState(state, options = {}) {
+	const out = {
+		version: RUN_STATE_SCHEMA_VERSION,
+		id: state.id,
+		agentId: state.agentId,
+		currentAgentId: state.currentAgentId,
+		sessionId: state.sessionId,
+		...state.userId !== void 0 ? { userId: state.userId } : {},
+		status: state.status,
+		steps: state.steps,
+		messages: state.messages,
+		pendingApprovals: state.pendingApprovals,
+		handoffs: state.handoffs,
+		usage: state.usage,
+		...state.usageByModel !== void 0 ? { usageByModel: state.usageByModel } : {},
+		...state.taintSummary !== void 0 ? { taintSummary: state.taintSummary } : {},
+		...state.promotedTools !== void 0 ? { promotedTools: state.promotedTools } : {},
+		startedAt: state.startedAt,
+		...state.finishedAt !== void 0 ? { finishedAt: state.finishedAt } : {},
+		...state.error !== void 0 ? { error: state.error } : {}
+	};
+	const detached = JSON.parse(JSON.stringify(out));
+	if (options.stripTracingApiKey === true) redactSecretKeysInPlace(detached);
+	return detached;
+}
+/**
+* Key names whose values are redacted by
+* `serializeRunState(state, { stripTracingApiKey: true })`.
+*/
+const SECRET_KEY_PATTERN = /^(api[-_]?key|tracing[-_]?api[-_]?key|x-api-key|authorization|bearer[-_]?token|access[-_]?token|refresh[-_]?token|secret|password|passphrase)$/i;
+const REDACTED = "[redacted]";
+function redactSecretKeysInPlace(value) {
+	if (typeof value !== "object" || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) redactSecretKeysInPlace(item);
+		return;
+	}
+	const record = value;
+	if (record.role === "tool" && typeof record.content === "string") record.content = redactJsonString(record.content);
+	for (const [key, inner] of Object.entries(record)) {
+		if (SECRET_KEY_PATTERN.test(key)) {
+			record[key] = REDACTED;
+			continue;
+		}
+		redactSecretKeysInPlace(inner);
+	}
+}
+function redactJsonString(content) {
+	try {
+		const parsed = JSON.parse(content);
+		if (typeof parsed !== "object" || parsed === null) return content;
+		redactSecretKeysInPlace(parsed);
+		return JSON.stringify(parsed);
+	} catch {
+		return content;
+	}
+}
+/**
+* Render the canonical JSON string representation of the supplied
+* {@link RunState}. `JSON.stringify(serializeRunState(state))` —
+* provided as a convenience.
+*
+* @stable
+*/
+function runStateToJSON(state, options) {
+	return JSON.stringify(serializeRunState(state, options));
+}
+function isRecord(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+* Rehydrate a {@link RunState} from the on-disk payload. Throws
+* {@link RunStateVersionUnsupportedError} when the payload version
+* is from a future major; throws
+* {@link RunStateMalformedError} when the payload is structurally
+* invalid.
+*
+* Backwards-compat: a payload that omits `usageByModel` is accepted
+* and the field is synthesized from the aggregate `usage` with
+* `attemptCount: 1` for the primary model.
+*
+* @stable
+*/
+function deserializeRunState(payload, options = {}) {
+	if (!isRecord(payload)) throw new RunStateMalformedError("payload must be an object");
+	const versionRaw = payload.version;
+	if (typeof versionRaw !== "string") throw new RunStateMalformedError("missing 'version' field");
+	const versionMatch = /^graphorin-run-state\/(\d+)\.(\d+)$/.exec(versionRaw);
+	if (versionMatch === null) throw new RunStateMalformedError(`unrecognized version '${versionRaw}'`);
+	if (Number(versionMatch[1]) > RUN_STATE_SCHEMA_MAJOR_SUPPORTED) throw new RunStateVersionUnsupportedError(versionRaw, RUN_STATE_SCHEMA_VERSION);
+	const requiredString = (key) => {
+		const v = payload[key];
+		if (typeof v !== "string") throw new RunStateMalformedError(`missing string '${key}' field`);
+		return v;
+	};
+	const requiredArray = (key) => {
+		const v = payload[key];
+		if (!Array.isArray(v)) throw new RunStateMalformedError(`missing array '${key}' field`);
+		return v;
+	};
+	const id = requiredString("id");
+	const agentId = requiredString("agentId");
+	const currentAgentId = typeof payload.currentAgentId === "string" ? payload.currentAgentId : agentId;
+	const sessionId = requiredString("sessionId");
+	const status = requiredString("status");
+	const steps = requiredArray("steps");
+	const messages = requiredArray("messages");
+	const pendingApprovals = requiredArray("pendingApprovals");
+	const handoffs = requiredArray("handoffs");
+	const usageRaw = payload.usage;
+	if (!isRecord(usageRaw)) throw new RunStateMalformedError("missing object 'usage' field");
+	const usage = {
+		promptTokens: Number(usageRaw.promptTokens ?? 0),
+		completionTokens: Number(usageRaw.completionTokens ?? 0),
+		totalTokens: Number(usageRaw.totalTokens ?? 0),
+		...usageRaw.reasoningTokens !== void 0 ? { reasoningTokens: Number(usageRaw.reasoningTokens) } : {},
+		...isRecord(usageRaw.cost) ? { cost: {
+			amount: Number(usageRaw.cost.amount ?? 0),
+			currency: String(usageRaw.cost.currency ?? "USD")
+		} } : {}
+	};
+	const startedAt = requiredString("startedAt");
+	const userIdRaw = payload.userId;
+	const finishedAtRaw = payload.finishedAt;
+	const errorRaw = payload.error;
+	let error;
+	if (isRecord(errorRaw)) error = {
+		message: typeof errorRaw.message === "string" ? errorRaw.message : "unknown",
+		code: typeof errorRaw.code === "string" ? errorRaw.code : "unknown",
+		...errorRaw.details !== void 0 ? { details: errorRaw.details } : {}
+	};
+	let usageByModel;
+	if (isRecord(payload.usageByModel)) {
+		const m = {};
+		for (const [modelId, entryRaw] of Object.entries(payload.usageByModel)) {
+			if (!isRecord(entryRaw)) continue;
+			m[modelId] = {
+				promptTokens: Number(entryRaw.promptTokens ?? 0),
+				completionTokens: Number(entryRaw.completionTokens ?? 0),
+				totalTokens: Number(entryRaw.totalTokens ?? 0),
+				attemptCount: Number(entryRaw.attemptCount ?? 1),
+				...entryRaw.reasoningTokens !== void 0 ? { reasoningTokens: Number(entryRaw.reasoningTokens) } : {},
+				...isRecord(entryRaw.cost) ? { cost: {
+					amount: Number(entryRaw.cost.amount ?? 0),
+					currency: String(entryRaw.cost.currency ?? "USD")
+				} } : {}
+			};
+		}
+		usageByModel = m;
+	} else if (options.synthesizeUsageByModel !== false && Number.isFinite(usage.totalTokens)) {
+		usageByModel = { [agentId]: {
+			...usage,
+			attemptCount: 1
+		} };
+		options.logger?.(`[graphorin/agent] RunState v0.1-alpha synthesis: per-model breakdown derived from aggregate usage for agent '${agentId}'.`);
+	}
+	let taintSummary;
+	if (isRecord(payload.taintSummary)) {
+		const ts = payload.taintSummary;
+		taintSummary = {
+			untrustedSeen: ts.untrustedSeen === true,
+			sensitiveSeen: ts.sensitiveSeen === true,
+			untrustedSourceKinds: Array.isArray(ts.untrustedSourceKinds) ? ts.untrustedSourceKinds.filter((k) => typeof k === "string") : []
+		};
+	}
+	const promotedTools = Array.isArray(payload.promotedTools) ? payload.promotedTools.filter((t) => typeof t === "string") : void 0;
+	return {
+		id,
+		agentId,
+		currentAgentId,
+		sessionId,
+		...typeof userIdRaw === "string" ? { userId: userIdRaw } : {},
+		status,
+		steps,
+		messages,
+		pendingApprovals,
+		handoffs,
+		usage,
+		...usageByModel !== void 0 ? { usageByModel } : {},
+		...taintSummary !== void 0 ? { taintSummary } : {},
+		...promotedTools !== void 0 ? { promotedTools } : {},
+		startedAt,
+		...typeof finishedAtRaw === "string" ? { finishedAt: finishedAtRaw } : {},
+		...error !== void 0 ? { error } : {}
+	};
+}
+/** Convenience JSON-string parser pairing with {@link runStateToJSON}. */
+function runStateFromJSON(serialized, options) {
+	let parsed;
+	try {
+		parsed = JSON.parse(serialized);
+	} catch (cause) {
+		throw new RunStateMalformedError(`invalid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	return deserializeRunState(parsed, options);
+}
+/**
+* Build a fresh, minimal {@link RunState} for a new run. Helper used
+* by `createAgent({...})` so consumers can construct deterministic
+* run state in tests.
+*
+* @stable
+*/
+function createInitialRunState(args) {
+	return {
+		id: args.id,
+		agentId: args.agentId,
+		currentAgentId: args.agentId,
+		sessionId: args.sessionId,
+		...args.userId !== void 0 ? { userId: args.userId } : {},
+		status: "running",
+		steps: [],
+		messages: [],
+		pendingApprovals: [],
+		handoffs: [],
+		usage: zeroUsage(),
+		startedAt: args.startedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* Append a per-model usage entry to {@link RunState.usageByModel}.
+* Mutates the supplied state in place — used by the agent runtime's
+* per-step retry loop. Pure callers that need an immutable update
+* should clone the state first.
+*
+* @stable
+*/
+function addModelUsage(state, modelId, delta) {
+	const current = state.usageByModel ?? {};
+	const prev = current[modelId];
+	current[modelId] = prev ? {
+		promptTokens: prev.promptTokens + delta.promptTokens,
+		completionTokens: prev.completionTokens + delta.completionTokens,
+		totalTokens: prev.totalTokens + delta.totalTokens,
+		...delta.reasoningTokens !== void 0 || prev.reasoningTokens !== void 0 ? { reasoningTokens: (prev.reasoningTokens ?? 0) + (delta.reasoningTokens ?? 0) } : {},
+		attemptCount: prev.attemptCount + 1,
+		...prev.cost !== void 0 ? { cost: prev.cost } : {}
+	} : {
+		...delta,
+		attemptCount: 1
+	};
+	state.usageByModel = current;
+}
+/**
+* Recompute the aggregate usage from `usageByModel`. Returns the
+* sum that callers can compare against `state.usage` to verify the
+* per-step retry loop maintained the documented invariant.
+*
+* @stable
+*/
+function aggregateUsageFromByModel(byModel) {
+	if (byModel === void 0) return zeroUsage();
+	let pt = 0;
+	let ct = 0;
+	let tt = 0;
+	let rt = 0;
+	let hasReasoning = false;
+	for (const entry of Object.values(byModel)) {
+		pt += entry.promptTokens;
+		ct += entry.completionTokens;
+		tt += entry.totalTokens;
+		if (entry.reasoningTokens !== void 0) {
+			rt += entry.reasoningTokens;
+			hasReasoning = true;
+		}
+	}
+	return {
+		promptTokens: pt,
+		completionTokens: ct,
+		totalTokens: tt,
+		...hasReasoning ? { reasoningTokens: rt } : {}
+	};
+}
+/**
+* The "tools used" surface of a completed run. Cheap to compute
+* from `RunState.steps`; surfaced as a stand-alone helper for
+* Phase 17 example apps and operator-facing dashboards.
+*
+* @stable
+*/
+function completedToolCallsFromState(state) {
+	const out = [];
+	for (const step of state.steps) for (const tc of step.toolCalls) out.push(tc);
+	return out;
+}
+
+//#endregion
+export { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState };
+//# sourceMappingURL=index.js.map

package/dist/run-state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["out: SerializedRunState","usage: Usage","error: RunState['error']","usageByModel: RunStateUsageByModel | undefined","m: Record<string, Usage & { attemptCount: number }>","taintSummary: RunTaintSummary | undefined","parsed: unknown","out: CompletedToolCall[]"],"sources":["../../src/run-state/index.ts"],"sourcesContent":["/**\n * `RunState` JSON serialization and rehydration.\n *\n * The on-disk shape carries an explicit `version` field so future\n * schema bumps can detect older payloads. v0.1 ships\n * `'graphorin-run-state/1.0'` — additive fields that older readers\n * do not understand are ignored under the lenient-forward-parse\n * discipline.\n *\n * @packageDocumentation\n */\n\nimport type {\n  CompletedToolCall,\n  HandoffRecord,\n  Message,\n  RunState,\n  RunStateUsageByModel,\n  RunStatus,\n  RunStep,\n  RunTaintSummary,\n  ToolApproval,\n  Usage,\n} from '@graphorin/core';\nimport { zeroUsage } from '@graphorin/core';\nimport { RunStateMalformedError, RunStateVersionUnsupportedError } from '../errors/index.js';\n\n/**\n * Canonical schema id for serialized {@link RunState} payloads.\n *\n * @stable\n */\nexport const RUN_STATE_SCHEMA_VERSION = 'graphorin-run-state/1.1' as const;\n\n/**\n * Reader-supported schema id range. Major version 1 only for v0.1.\n *\n * @stable\n */\nexport const RUN_STATE_SCHEMA_MAJOR_SUPPORTED = 1;\n\n/**\n * On-disk payload returned by {@link serializeRunState} and accepted\n * by {@link deserializeRunState}. The shape is JSON-stable.\n *\n * @stable\n */\nexport interface SerializedRunState {\n  readonly version: typeof RUN_STATE_SCHEMA_VERSION;\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly status: RunStatus;\n  readonly steps: ReadonlyArray<RunStep>;\n  readonly messages: ReadonlyArray<Message>;\n  readonly pendingApprovals: ReadonlyArray<ToolApproval>;\n  readonly handoffs: ReadonlyArray<HandoffRecord>;\n  readonly usage: Usage;\n  readonly usageByModel?: RunStateUsageByModel;\n  /** AG-19: coarse data-flow taint summary (no untrusted text). */\n  readonly taintSummary?: RunTaintSummary;\n  /** AG-19: deferred tools promoted by `tool_search` this run. */\n  readonly promotedTools?: ReadonlyArray<string>;\n  readonly startedAt: string;\n  readonly finishedAt?: string;\n  readonly error?: { readonly message: string; readonly code: string; readonly details?: unknown };\n}\n\n/**\n * Options accepted by {@link serializeRunState}.\n *\n * @stable\n */\nexport interface SerializeRunStateOptions {\n  /**\n   * Deep-redact secret-named keys (`apiKey`, `authorization`,\n   * `bearerToken` / `accessToken` / `refreshToken`, `password`,\n   * `secret`, …) anywhere in the snapshot — tool results and messages\n   * included — replacing their values with `'[redacted]'`. Defaults to\n   * `false` for the round-trip canonical helper; the agent runtime\n   * passes `true` when persisting through the checkpoint store\n   * (AG-23). Redaction is best-effort by key name: secrets stored\n   * under unrelated keys are not detected.\n   */\n  readonly stripTracingApiKey?: boolean;\n}\n\n/**\n * Render a JSON-stable snapshot of the supplied {@link RunState}.\n * The returned value is plain JSON (no `Map`, `Set`, `Date`, ...).\n *\n * @stable\n */\nexport function serializeRunState(\n  state: RunState,\n  options: SerializeRunStateOptions = {},\n): SerializedRunState {\n  const out: SerializedRunState = {\n    version: RUN_STATE_SCHEMA_VERSION,\n    id: state.id,\n    agentId: state.agentId,\n    currentAgentId: state.currentAgentId,\n    sessionId: state.sessionId,\n    ...(state.userId !== undefined ? { userId: state.userId } : {}),\n    status: state.status,\n    steps: state.steps,\n    messages: state.messages,\n    pendingApprovals: state.pendingApprovals,\n    handoffs: state.handoffs,\n    usage: state.usage,\n    ...(state.usageByModel !== undefined ? { usageByModel: state.usageByModel } : {}),\n    ...(state.taintSummary !== undefined ? { taintSummary: state.taintSummary } : {}),\n    ...(state.promotedTools !== undefined ? { promotedTools: state.promotedTools } : {}),\n    startedAt: state.startedAt,\n    ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),\n    ...(state.error !== undefined ? { error: state.error } : {}),\n  };\n  // AG-23: the snapshot must be DETACHED from the live MutableRunState —\n  // a post-suspend mutation must never reach an already-persisted\n  // checkpoint. The JSON round-trip doubles as the plain-JSON guarantee\n  // this function documents (no Map/Set/Date survive it).\n  const detached = JSON.parse(JSON.stringify(out)) as SerializedRunState;\n  if (options.stripTracingApiKey === true) {\n    redactSecretKeysInPlace(detached);\n  }\n  return detached;\n}\n\n/**\n * Key names whose values are redacted by\n * `serializeRunState(state, { stripTracingApiKey: true })`.\n */\nconst SECRET_KEY_PATTERN =\n  /^(api[-_]?key|tracing[-_]?api[-_]?key|x-api-key|authorization|bearer[-_]?token|access[-_]?token|refresh[-_]?token|secret|password|passphrase)$/i;\n\nconst REDACTED = '[redacted]';\n\nfunction redactSecretKeysInPlace(value: unknown): void {\n  if (typeof value !== 'object' || value === null) return;\n  if (Array.isArray(value)) {\n    for (const item of value) redactSecretKeysInPlace(item);\n    return;\n  }\n  const record = value as Record<string, unknown>;\n  // Tool messages embed the tool output as a JSON STRING in `content` —\n  // parse, redact, and re-stringify so a secret inside the string form\n  // is caught too.\n  if (record.role === 'tool' && typeof record.content === 'string') {\n    record.content = redactJsonString(record.content);\n  }\n  for (const [key, inner] of Object.entries(record)) {\n    if (SECRET_KEY_PATTERN.test(key)) {\n      record[key] = REDACTED;\n      continue;\n    }\n    redactSecretKeysInPlace(inner);\n  }\n}\n\nfunction redactJsonString(content: string): string {\n  try {\n    const parsed = JSON.parse(content) as unknown;\n    if (typeof parsed !== 'object' || parsed === null) return content;\n    redactSecretKeysInPlace(parsed);\n    return JSON.stringify(parsed);\n  } catch {\n    return content;\n  }\n}\n\n/**\n * Render the canonical JSON string representation of the supplied\n * {@link RunState}. `JSON.stringify(serializeRunState(state))` —\n * provided as a convenience.\n *\n * @stable\n */\nexport function runStateToJSON(state: RunState, options?: SerializeRunStateOptions): string {\n  return JSON.stringify(serializeRunState(state, options));\n}\n\ninterface DeserializeOptions {\n  /**\n   * Synthesize `usageByModel` from a v0.1-alpha state that omits\n   * the field. Defaults to `true` so callers can rehydrate older\n   * states without explicit migration.\n   */\n  readonly synthesizeUsageByModel?: boolean;\n  /**\n   * Logger callback for one-time INFO messages emitted on\n   * backwards-compat synthesis. Defaults to a no-op.\n   */\n  readonly logger?: (message: string) => void;\n}\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\n/**\n * Rehydrate a {@link RunState} from the on-disk payload. Throws\n * {@link RunStateVersionUnsupportedError} when the payload version\n * is from a future major; throws\n * {@link RunStateMalformedError} when the payload is structurally\n * invalid.\n *\n * Backwards-compat: a payload that omits `usageByModel` is accepted\n * and the field is synthesized from the aggregate `usage` with\n * `attemptCount: 1` for the primary model.\n *\n * @stable\n */\nexport function deserializeRunState(payload: unknown, options: DeserializeOptions = {}): RunState {\n  if (!isRecord(payload)) {\n    throw new RunStateMalformedError('payload must be an object');\n  }\n  const versionRaw = payload.version;\n  if (typeof versionRaw !== 'string') {\n    throw new RunStateMalformedError(\"missing 'version' field\");\n  }\n  const versionMatch = /^graphorin-run-state\\/(\\d+)\\.(\\d+)$/.exec(versionRaw);\n  if (versionMatch === null) {\n    throw new RunStateMalformedError(`unrecognized version '${versionRaw}'`);\n  }\n  const major = Number(versionMatch[1]);\n  if (major > RUN_STATE_SCHEMA_MAJOR_SUPPORTED) {\n    throw new RunStateVersionUnsupportedError(versionRaw, RUN_STATE_SCHEMA_VERSION);\n  }\n  const requiredString = (key: string): string => {\n    const v = payload[key];\n    if (typeof v !== 'string') {\n      throw new RunStateMalformedError(`missing string '${key}' field`);\n    }\n    return v;\n  };\n  const requiredArray = <T>(key: string): T[] => {\n    const v = payload[key];\n    if (!Array.isArray(v)) {\n      throw new RunStateMalformedError(`missing array '${key}' field`);\n    }\n    return v as T[];\n  };\n  const id = requiredString('id');\n  const agentId = requiredString('agentId');\n  const currentAgentId =\n    typeof payload.currentAgentId === 'string' ? payload.currentAgentId : agentId;\n  const sessionId = requiredString('sessionId');\n  const status = requiredString('status') as RunStatus;\n  const steps = requiredArray<RunStep>('steps');\n  const messages = requiredArray<Message>('messages');\n  const pendingApprovals = requiredArray<ToolApproval>('pendingApprovals');\n  const handoffs = requiredArray<HandoffRecord>('handoffs');\n  const usageRaw = payload.usage;\n  if (!isRecord(usageRaw)) {\n    throw new RunStateMalformedError(\"missing object 'usage' field\");\n  }\n  const usage: Usage = {\n    promptTokens: Number(usageRaw.promptTokens ?? 0),\n    completionTokens: Number(usageRaw.completionTokens ?? 0),\n    totalTokens: Number(usageRaw.totalTokens ?? 0),\n    ...(usageRaw.reasoningTokens !== undefined\n      ? { reasoningTokens: Number(usageRaw.reasoningTokens) }\n      : {}),\n    ...(isRecord(usageRaw.cost)\n      ? {\n          cost: {\n            amount: Number(usageRaw.cost.amount ?? 0),\n            currency: String(usageRaw.cost.currency ?? 'USD'),\n          },\n        }\n      : {}),\n  };\n  const startedAt = requiredString('startedAt');\n  const userIdRaw = payload.userId;\n  const finishedAtRaw = payload.finishedAt;\n  const errorRaw = payload.error;\n  let error: RunState['error'];\n  if (isRecord(errorRaw)) {\n    error = {\n      message: typeof errorRaw.message === 'string' ? errorRaw.message : 'unknown',\n      code: typeof errorRaw.code === 'string' ? errorRaw.code : 'unknown',\n      ...(errorRaw.details !== undefined ? { details: errorRaw.details } : {}),\n    };\n  }\n\n  // Backwards-compat synthesis for usageByModel.\n  let usageByModel: RunStateUsageByModel | undefined;\n  if (isRecord(payload.usageByModel)) {\n    const m: Record<string, Usage & { attemptCount: number }> = {};\n    for (const [modelId, entryRaw] of Object.entries(payload.usageByModel)) {\n      if (!isRecord(entryRaw)) continue;\n      m[modelId] = {\n        promptTokens: Number(entryRaw.promptTokens ?? 0),\n        completionTokens: Number(entryRaw.completionTokens ?? 0),\n        totalTokens: Number(entryRaw.totalTokens ?? 0),\n        attemptCount: Number(entryRaw.attemptCount ?? 1),\n        ...(entryRaw.reasoningTokens !== undefined\n          ? { reasoningTokens: Number(entryRaw.reasoningTokens) }\n          : {}),\n        ...(isRecord(entryRaw.cost)\n          ? {\n              cost: {\n                amount: Number(entryRaw.cost.amount ?? 0),\n                currency: String(entryRaw.cost.currency ?? 'USD'),\n              },\n            }\n          : {}),\n      };\n    }\n    usageByModel = m;\n  } else if (options.synthesizeUsageByModel !== false && Number.isFinite(usage.totalTokens)) {\n    usageByModel = {\n      [agentId]: { ...usage, attemptCount: 1 },\n    };\n    options.logger?.(\n      `[graphorin/agent] RunState v0.1-alpha synthesis: per-model breakdown derived from aggregate usage for agent '${agentId}'.`,\n    );\n  }\n\n  // AG-19: rehydrate the coarse taint summary + promoted-tool set (additive;\n  // absent on older v1.0 payloads).\n  let taintSummary: RunTaintSummary | undefined;\n  if (isRecord(payload.taintSummary)) {\n    const ts = payload.taintSummary;\n    taintSummary = {\n      untrustedSeen: ts.untrustedSeen === true,\n      sensitiveSeen: ts.sensitiveSeen === true,\n      untrustedSourceKinds: Array.isArray(ts.untrustedSourceKinds)\n        ? ts.untrustedSourceKinds.filter((k): k is string => typeof k === 'string')\n        : [],\n    };\n  }\n  const promotedTools = Array.isArray(payload.promotedTools)\n    ? payload.promotedTools.filter((t): t is string => typeof t === 'string')\n    : undefined;\n\n  const out: RunState = {\n    id,\n    agentId,\n    currentAgentId,\n    sessionId,\n    ...(typeof userIdRaw === 'string' ? { userId: userIdRaw } : {}),\n    status,\n    steps,\n    messages,\n    pendingApprovals,\n    handoffs,\n    usage,\n    ...(usageByModel !== undefined ? { usageByModel } : {}),\n    ...(taintSummary !== undefined ? { taintSummary } : {}),\n    ...(promotedTools !== undefined ? { promotedTools } : {}),\n    startedAt,\n    ...(typeof finishedAtRaw === 'string' ? { finishedAt: finishedAtRaw } : {}),\n    ...(error !== undefined ? { error } : {}),\n  };\n  void zeroUsage; // kept available; some callers prefer zeroUsage as a default.\n  return out;\n}\n\n/** Convenience JSON-string parser pairing with {@link runStateToJSON}. */\nexport function runStateFromJSON(serialized: string, options?: DeserializeOptions): RunState {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(serialized);\n  } catch (cause) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n    throw new RunStateMalformedError(`invalid JSON: ${message}`);\n  }\n  return deserializeRunState(parsed, options);\n}\n\n/**\n * Build a fresh, minimal {@link RunState} for a new run. Helper used\n * by `createAgent({...})` so consumers can construct deterministic\n * run state in tests.\n *\n * @stable\n */\nexport function createInitialRunState(args: {\n  readonly id: string;\n  readonly agentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly startedAt?: string;\n}): RunState {\n  return {\n    id: args.id,\n    agentId: args.agentId,\n    currentAgentId: args.agentId,\n    sessionId: args.sessionId,\n    ...(args.userId !== undefined ? { userId: args.userId } : {}),\n    status: 'running',\n    steps: [],\n    messages: [],\n    pendingApprovals: [],\n    handoffs: [],\n    usage: zeroUsage(),\n    startedAt: args.startedAt ?? new Date().toISOString(),\n  };\n}\n\n/**\n * Append a per-model usage entry to {@link RunState.usageByModel}.\n * Mutates the supplied state in place — used by the agent runtime's\n * per-step retry loop. Pure callers that need an immutable update\n * should clone the state first.\n *\n * @stable\n */\nexport function addModelUsage(state: RunState, modelId: string, delta: Usage): void {\n  const current = (state.usageByModel ?? {}) as Record<string, Usage & { attemptCount: number }>;\n  const prev = current[modelId];\n  const merged: Usage & { attemptCount: number } = prev\n    ? {\n        promptTokens: prev.promptTokens + delta.promptTokens,\n        completionTokens: prev.completionTokens + delta.completionTokens,\n        totalTokens: prev.totalTokens + delta.totalTokens,\n        ...(delta.reasoningTokens !== undefined || prev.reasoningTokens !== undefined\n          ? {\n              reasoningTokens: (prev.reasoningTokens ?? 0) + (delta.reasoningTokens ?? 0),\n            }\n          : {}),\n        attemptCount: prev.attemptCount + 1,\n        ...(prev.cost !== undefined ? { cost: prev.cost } : {}),\n      }\n    : { ...delta, attemptCount: 1 };\n  current[modelId] = merged;\n  // Mutate via the writable typing — `usageByModel` is declared\n  // optional; the runtime owns the field's lifecycle.\n  (state as { usageByModel?: RunStateUsageByModel }).usageByModel = current;\n}\n\n/**\n * Recompute the aggregate usage from `usageByModel`. Returns the\n * sum that callers can compare against `state.usage` to verify the\n * per-step retry loop maintained the documented invariant.\n *\n * @stable\n */\nexport function aggregateUsageFromByModel(byModel: RunStateUsageByModel | undefined): Usage {\n  if (byModel === undefined) return zeroUsage();\n  let pt = 0;\n  let ct = 0;\n  let tt = 0;\n  let rt = 0;\n  let hasReasoning = false;\n  for (const entry of Object.values(byModel)) {\n    pt += entry.promptTokens;\n    ct += entry.completionTokens;\n    tt += entry.totalTokens;\n    if (entry.reasoningTokens !== undefined) {\n      rt += entry.reasoningTokens;\n      hasReasoning = true;\n    }\n  }\n  return {\n    promptTokens: pt,\n    completionTokens: ct,\n    totalTokens: tt,\n    ...(hasReasoning ? { reasoningTokens: rt } : {}),\n  };\n}\n\n/**\n * The \"tools used\" surface of a completed run. Cheap to compute\n * from `RunState.steps`; surfaced as a stand-alone helper for\n * Phase 17 example apps and operator-facing dashboards.\n *\n * @stable\n */\nexport function completedToolCallsFromState(state: RunState): ReadonlyArray<CompletedToolCall> {\n  const out: CompletedToolCall[] = [];\n  for (const step of state.steps) {\n    for (const tc of step.toolCalls) out.push(tc);\n  }\n  return out;\n}\n"],"mappings":"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"}

package/dist/tooling/adapters.js

@@ -0,0 +1,154 @@
+import { countTokensHeuristic } from "@graphorin/tools/result";
+import { createGuard } from "@graphorin/security/guard";
+import "@graphorin/security/sandbox";
+import { parseSecretRef, resolveSecret } from "@graphorin/security/secrets";
+
+//#region src/tooling/adapters.ts
+/**
+* Adapter A — build the executor's `secretResolver` hook.
+*
+* This is a thin **value resolver**. The executor's secrets accessor
+* (`@graphorin/tools` `tool-context.ts`) already (1) enforces the
+* per-tool `secretsAllowed` ACL via `enforceSecretAcl(key)` inside a
+* `withChildToolSecretsContext(...)` scope and (2) maps a `null` result
+* onto the optional/required-secret error contract. This adapter must
+* therefore **not** re-implement ACL — it only resolves a key to a
+* value.
+*/
+function buildSecretResolver(options = {}) {
+	const backend = options.backend ?? (async (key) => resolveSecret(parseSecretRef(key)));
+	return Object.freeze({ resolve: backend });
+}
+/**
+* Adapter C — build the executor's `memoryGuardFactory` (+ an optional
+* `memoryRegionReader`) from the agent's configured `Memory`.
+*
+* When `memory` is `undefined`, the factory returns `null` for every
+* tier and no reader is supplied — the executor degrades to its
+* audit-only baseline (the guard step is skipped).
+*/
+function buildMemoryGuard(memory, options = {}) {
+	if (memory === void 0) return Object.freeze({ memoryGuardFactory: () => null });
+	const memoryGuardFactory = (tier) => {
+		switch (tier) {
+			case "pure":
+			case "side-effecting-no-memory": return createGuard({ tier });
+			case "unknown": return createGuard({
+				tier,
+				...options.auditOnly ?? {}
+			});
+			case "untrusted": return createGuard({
+				tier,
+				...options.strictFull ?? {}
+			});
+			case "memory-aware": return options.apiBoundary === void 0 ? null : createGuard({
+				tier,
+				...options.apiBoundary
+			});
+			default: return null;
+		}
+	};
+	return Object.freeze(options.regionReader === void 0 ? { memoryGuardFactory } : {
+		memoryGuardFactory,
+		memoryRegionReader: options.regionReader
+	});
+}
+/**
+* Construct a `MemoryRegionReader` from an explicit region list and a
+* read function. WI-03 uses this to bind the agent's `Memory` tiers to
+* named regions once a run scope exists; exposed here so the reader
+* contract is unit-testable in isolation.
+*/
+function createMemoryRegionReader(regions, read) {
+	return Object.freeze({
+		regions: Object.freeze([...regions]),
+		read
+	});
+}
+/**
+* Adapter D — build the **synchronous** token counter the executor's
+* truncation pipeline requires.
+*
+* DESIGN DECISION (impedance mismatch §1.6.1): `@graphorin/tools`'
+* `TokenCounter.count(text): number` is synchronous, while
+* `@graphorin/provider`'s `createDefaultCounter().count(input): Promise<number>`
+* is asynchronous (and also accepts `Message[]`). The truncation path
+* runs inside `executeBatch` and must not `await`, so we never wire the
+* provider's async counter here. We default to the tools heuristic
+* (deterministic, offline) and allow a *synchronous* tokenizer (e.g.
+* js-tiktoken's `encode`) to be injected when a caller wants
+* vendor-accurate counts without blocking. The async provider counter
+* stays reserved for budget accounting elsewhere (WI-09), not for
+* executor truncation.
+*/
+function buildToolTokenCounter(options = {}) {
+	const { tokenize } = options;
+	if (tokenize === void 0) return countTokensHeuristic;
+	return Object.freeze({ count: (text) => tokenize(text).length });
+}
+/**
+* Adapter E — bridge the executor's `streamingSink` callback to an
+* async iterator via a bounded queue.
+*/
+function createExecutorEventBridge(options = {}) {
+	const queueDepth = options.queueDepth ?? 256;
+	const buffer = [];
+	let pending = null;
+	let closed = false;
+	let dropped = 0;
+	const sink = (event) => {
+		if (closed) return;
+		if (pending !== null) {
+			const resolve = pending;
+			pending = null;
+			resolve({
+				value: event,
+				done: false
+			});
+			return;
+		}
+		buffer.push(event);
+		if (buffer.length > queueDepth) {
+			buffer.shift();
+			dropped += 1;
+		}
+	};
+	async function* drain() {
+		for (;;) {
+			if (buffer.length > 0) {
+				const event = buffer.shift();
+				if (event !== void 0) yield event;
+				continue;
+			}
+			if (closed) return;
+			const next = await new Promise((resolve) => {
+				pending = resolve;
+			});
+			if (next.done === true) return;
+			yield next.value;
+		}
+	}
+	const close = () => {
+		closed = true;
+		if (pending !== null) {
+			const resolve = pending;
+			pending = null;
+			resolve({
+				value: void 0,
+				done: true
+			});
+		}
+	};
+	return Object.freeze({
+		sink,
+		drain,
+		close,
+		get dropped() {
+			return dropped;
+		}
+	});
+}
+
+//#endregion
+export { buildMemoryGuard, buildSecretResolver, buildToolTokenCounter, createExecutorEventBridge, createMemoryRegionReader };
+//# sourceMappingURL=adapters.js.map

package/dist/tooling/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","names":["backend: SecretBackend","memoryGuardFactory: MemoryGuardFactory","buffer: T[]","pending: ((result: IteratorResult<T, undefined>) => void) | null"],"sources":["../../src/tooling/adapters.ts"],"sourcesContent":["/**\n * Integration adapters (A–E) that let the `@graphorin/tools` executor\n * consume the agent's `@graphorin/security` / `@graphorin/memory` /\n * `@graphorin/provider` surfaces.\n *\n * These are built and unit-tested in isolation (WI-01). The run loop\n * wires them into `createToolExecutor(...)` in a later work item\n * (WI-03); nothing here is exported from the package entrypoint yet.\n *\n * Every adapter is typed against the executor's `ExecutorOptions` via\n * indexed access, so the values they produce are guaranteed assignable\n * to the hooks `createToolExecutor(...)` expects — without depending on\n * which individual hook types `@graphorin/tools` happens to re-export.\n *\n * @packageDocumentation\n */\n\nimport type { Memory } from '@graphorin/memory';\nimport {\n  type ApiBoundaryGuardOptions,\n  type AuditOnlyGuardOptions,\n  createGuard,\n  type StrictFullGuardOptions,\n} from '@graphorin/security/guard';\nimport {\n  createDockerSandbox,\n  createIsolatedVMSandbox,\n  createWorkerThreadsSandbox,\n  type SandboxImpl,\n} from '@graphorin/security/sandbox';\nimport { parseSecretRef, resolveSecret } from '@graphorin/security/secrets';\nimport type { ExecutorOptions } from '@graphorin/tools/executor';\nimport { countTokensHeuristic } from '@graphorin/tools/result';\n\n// --- Executor hook shapes (derived from `ExecutorOptions`) ------------------\n// Indexed access keeps these in lock-step with what the executor expects.\n\n/** The executor's secret-resolver hook: `{ resolve(key): Promise<SecretValue | null> }`. */\ntype SecretResolver = NonNullable<ExecutorOptions['secretResolver']>;\n/** A resolved `SecretValue`, or `null` when the backing store has no value. */\ntype SecretValueOrNull = Awaited<ReturnType<SecretResolver['resolve']>>;\n/** The executor's sandbox-dispatch resolver: `(policy) => Sandbox | null`. */\ntype SandboxResolver = NonNullable<ExecutorOptions['sandboxResolver']>;\n/** The executor's memory-guard factory: `(tier) => MemoryModificationGuard | null`. */\ntype MemoryGuardFactory = NonNullable<ExecutorOptions['memoryGuardFactory']>;\n/** The discriminator the guard factory receives (`'pure' | … | 'untrusted'`). */\ntype MemoryGuardTier = Parameters<MemoryGuardFactory>[0];\n/** A guard instance, or `null` when the tier needs no guard / cannot be built. */\ntype MemoryModificationGuardOrNull = ReturnType<MemoryGuardFactory>;\n/** The reader the guard hashes pre/post execution: `{ regions; read(region) }`. */\ntype MemoryRegionReader = NonNullable<ExecutorOptions['memoryRegionReader']>;\n/** The executor's **synchronous** truncation token counter: `{ count(text): number }`. */\ntype ToolTokenCounter = NonNullable<ExecutorOptions['tokenCounter']>;\n/** A value the executor's `streamingSink` receives (a `tool.execute.*` event). */\ntype ExecutorEvent = Parameters<NonNullable<ExecutorOptions['streamingSink']>>[0];\n\n// ---------------------------------------------------------------------------\n// Adapter A — `secretResolver`\n// ---------------------------------------------------------------------------\n\n/**\n * Backend that turns a secret reference into a resolved value (or\n * `null` when the backing store represents \"absent\" as null). Defaults\n * to `@graphorin/security`'s global resolver registry\n * (`resolveSecret(parseSecretRef(key))`), which **rejects** on a\n * malformed ref / unknown scheme / resolution failure and never returns\n * null — those rejections surface as tool errors through the executor's\n * secrets accessor.\n */\nexport type SecretBackend = (key: string) => Promise<SecretValueOrNull>;\n\n/** Options for {@link buildSecretResolver}. */\nexport interface SecretResolverOptions {\n  /** Resolution backend. Defaults to `resolveSecret(parseSecretRef(key))`. */\n  readonly backend?: SecretBackend;\n}\n\n/**\n * Adapter A — build the executor's `secretResolver` hook.\n *\n * This is a thin **value resolver**. The executor's secrets accessor\n * (`@graphorin/tools` `tool-context.ts`) already (1) enforces the\n * per-tool `secretsAllowed` ACL via `enforceSecretAcl(key)` inside a\n * `withChildToolSecretsContext(...)` scope and (2) maps a `null` result\n * onto the optional/required-secret error contract. This adapter must\n * therefore **not** re-implement ACL — it only resolves a key to a\n * value.\n */\nexport function buildSecretResolver(options: SecretResolverOptions = {}): SecretResolver {\n  const backend: SecretBackend =\n    options.backend ?? (async (key) => resolveSecret(parseSecretRef(key)));\n  return Object.freeze({ resolve: backend });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter B — `sandboxResolver`\n// ---------------------------------------------------------------------------\n\n/** Isolation kinds the default resolver knows how to construct. */\ntype IsolatedKind = 'worker-threads' | 'isolated-vm' | 'docker';\n\n/** Factory producing a concrete sandbox for a given isolation kind. */\nexport type SandboxFactory = () => SandboxImpl;\n\n/** Per-kind sandbox factory overrides (e.g. fakes in tests, custom adapters). */\nexport type SandboxFactoryMap = Partial<Record<IsolatedKind, SandboxFactory>>;\n\n/** Options for {@link buildSandboxResolver}. */\nexport interface SandboxResolverOptions {\n  /**\n   * Per-kind factory overrides. Defaults wire the three out-of-process\n   * `@graphorin/security` adapters. Tests inject fakes so unit runs\n   * never spawn real worker threads / containers (offline; R4). The\n   * factories are invoked **lazily** — never at build time — so the\n   * production default costs nothing until a tool actually needs that\n   * isolation kind.\n   */\n  readonly factories?: SandboxFactoryMap;\n}\n\n/**\n * Adapter B — build the executor's `sandboxResolver`.\n *\n * Maps a `ResolvedSandboxPolicy.kind` to a cached `SandboxImpl`,\n * lazily constructing **one instance per kind**. Returns `null` for\n * `'none'` (run the tool inline) and for any kind without a registered\n * factory (custom kinds need a custom resolver).\n */\nexport function buildSandboxResolver(options: SandboxResolverOptions = {}): SandboxResolver {\n  const factories: Record<IsolatedKind, SandboxFactory> = {\n    'worker-threads': options.factories?.['worker-threads'] ?? (() => createWorkerThreadsSandbox()),\n    'isolated-vm': options.factories?.['isolated-vm'] ?? (() => createIsolatedVMSandbox()),\n    docker: options.factories?.docker ?? (() => createDockerSandbox()),\n  };\n  // Look up factories by the (open) policy kind. `SandboxKind` carries a\n  // `(string & {})` member that defeats literal narrowing, so we index a\n  // string-keyed view: a miss (incl. `'none'` and custom kinds) runs inline.\n  const lookup = factories as Record<string, SandboxFactory | undefined>;\n  const cache = new Map<string, SandboxImpl>();\n\n  return (policy) => {\n    const kind = policy.kind;\n    const factory = lookup[kind];\n    if (factory === undefined) {\n      return null;\n    }\n    let impl = cache.get(kind);\n    if (impl === undefined) {\n      impl = factory();\n      cache.set(kind, impl);\n    }\n    return impl;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Adapter C — `memoryGuardFactory` + `memoryRegionReader`\n// ---------------------------------------------------------------------------\n\n/** Options for {@link buildMemoryGuard}. */\nexport interface MemoryGuardOptions {\n  /**\n   * Options for the `'memory-aware'` API-boundary guard. The guard\n   * requires an operation allowlist + a recorder of observed\n   * `<scope>.<op>` calls, both supplied by the runtime once a run scope\n   * exists (WI-03). When omitted, the factory returns `null` for the\n   * `'memory-aware'` tier and the executor skips the guard.\n   */\n  readonly apiBoundary?: ApiBoundaryGuardOptions;\n  /** Options for the `'unknown'` (audit-only) guard. */\n  readonly auditOnly?: AuditOnlyGuardOptions;\n  /** Options for the `'untrusted'` (strict-full) guard. */\n  readonly strictFull?: StrictFullGuardOptions;\n  /**\n   * The region reader the guard hashes pre/post execution. The reader\n   * is **scope-bound** (it materialises memory regions for a specific\n   * run scope), so the runtime supplies it in WI-03 — the `Memory`\n   * facade exposes no scope-free read surface. When omitted, the\n   * executor skips the snapshot/verify cycle (it only runs the guard\n   * when the reader is present).\n   */\n  readonly regionReader?: MemoryRegionReader;\n}\n\n/** The executor wiring produced by {@link buildMemoryGuard}. */\nexport interface MemoryGuardWiring {\n  readonly memoryGuardFactory: MemoryGuardFactory;\n  readonly memoryRegionReader?: MemoryRegionReader;\n}\n\n/**\n * Adapter C — build the executor's `memoryGuardFactory` (+ an optional\n * `memoryRegionReader`) from the agent's configured `Memory`.\n *\n * When `memory` is `undefined`, the factory returns `null` for every\n * tier and no reader is supplied — the executor degrades to its\n * audit-only baseline (the guard step is skipped).\n */\nexport function buildMemoryGuard(\n  memory: Memory | undefined,\n  options: MemoryGuardOptions = {},\n): MemoryGuardWiring {\n  if (memory === undefined) {\n    return Object.freeze({ memoryGuardFactory: () => null });\n  }\n\n  const memoryGuardFactory: MemoryGuardFactory = (\n    tier: MemoryGuardTier,\n  ): MemoryModificationGuardOrNull => {\n    switch (tier) {\n      case 'pure':\n      case 'side-effecting-no-memory':\n        return createGuard({ tier });\n      case 'unknown':\n        return createGuard({ tier, ...(options.auditOnly ?? {}) });\n      case 'untrusted':\n        return createGuard({ tier, ...(options.strictFull ?? {}) });\n      case 'memory-aware':\n        return options.apiBoundary === undefined\n          ? null\n          : createGuard({ tier, ...options.apiBoundary });\n      default:\n        return null;\n    }\n  };\n\n  return Object.freeze(\n    options.regionReader === undefined\n      ? { memoryGuardFactory }\n      : { memoryGuardFactory, memoryRegionReader: options.regionReader },\n  );\n}\n\n/**\n * Construct a `MemoryRegionReader` from an explicit region list and a\n * read function. WI-03 uses this to bind the agent's `Memory` tiers to\n * named regions once a run scope exists; exposed here so the reader\n * contract is unit-testable in isolation.\n */\nexport function createMemoryRegionReader(\n  regions: ReadonlyArray<string>,\n  read: (region: string) => Promise<Uint8Array | string>,\n): MemoryRegionReader {\n  return Object.freeze({ regions: Object.freeze([...regions]), read });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter D — `tokenCounter` (the sync/async impedance mismatch)\n// ---------------------------------------------------------------------------\n\n/** A synchronous tokenizer (e.g. js-tiktoken's `encode`) returning a token array. */\nexport type SyncTokenize = (text: string) => { readonly length: number };\n\n/** Options for {@link buildToolTokenCounter}. */\nexport interface ToolTokenCounterOptions {\n  /**\n   * Optional synchronous tokenizer. When provided, the token count is\n   * `tokenize(text).length`. Defaults to the `@graphorin/tools`\n   * heuristic (4 chars/token).\n   */\n  readonly tokenize?: SyncTokenize;\n}\n\n/**\n * Adapter D — build the **synchronous** token counter the executor's\n * truncation pipeline requires.\n *\n * DESIGN DECISION (impedance mismatch §1.6.1): `@graphorin/tools`'\n * `TokenCounter.count(text): number` is synchronous, while\n * `@graphorin/provider`'s `createDefaultCounter().count(input): Promise<number>`\n * is asynchronous (and also accepts `Message[]`). The truncation path\n * runs inside `executeBatch` and must not `await`, so we never wire the\n * provider's async counter here. We default to the tools heuristic\n * (deterministic, offline) and allow a *synchronous* tokenizer (e.g.\n * js-tiktoken's `encode`) to be injected when a caller wants\n * vendor-accurate counts without blocking. The async provider counter\n * stays reserved for budget accounting elsewhere (WI-09), not for\n * executor truncation.\n */\nexport function buildToolTokenCounter(options: ToolTokenCounterOptions = {}): ToolTokenCounter {\n  const { tokenize } = options;\n  if (tokenize === undefined) {\n    return countTokensHeuristic;\n  }\n  return Object.freeze({\n    count: (text: string): number => tokenize(text).length,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter E — `streamingSink` → `AgentEvent` stream bridge\n// ---------------------------------------------------------------------------\n\n/** Options for {@link createExecutorEventBridge}. */\nexport interface ExecutorEventBridgeOptions {\n  /**\n   * Maximum buffered events before backpressure drops the **oldest**\n   * event (preserving the most-recent window). Defaults to `256`, matching\n   * the executor's `streamingEventQueueDepth` default. Under normal\n   * operation the consumer drains faster than the producer and nothing\n   * is ever dropped; this bound is a safety valve.\n   */\n  readonly queueDepth?: number;\n}\n\n/**\n * Bridges the executor's synchronous `streamingSink` callback into an\n * async iterable the run loop can `for await` over.\n *\n * Single-producer / single-consumer: `sink` is the producer (called by\n * the executor); one `drain()` iterator is the consumer (the loop). It\n * is generic over the event type (defaulting to the executor's\n * `ExecutorEvent`) so the queue mechanics can be exercised in isolation.\n */\nexport interface ExecutorEventBridge<T = ExecutorEvent> {\n  /**\n   * Synchronous sink handed to the executor's `streamingSink`. Never\n   * throws and never blocks; events emitted after {@link close} are\n   * dropped.\n   */\n  readonly sink: (event: T) => void;\n  /**\n   * Async iterable yielding events in arrival order. Completes once\n   * {@link close} has been called **and** the buffer is drained.\n   */\n  drain(): AsyncIterableIterator<T>;\n  /** Signal end-of-stream; `drain()` finishes after the buffer drains. */\n  close(): void;\n  /** Count of events dropped under backpressure (oldest-dropped). */\n  readonly dropped: number;\n}\n\n/**\n * Adapter E — bridge the executor's `streamingSink` callback to an\n * async iterator via a bounded queue.\n */\nexport function createExecutorEventBridge<T = ExecutorEvent>(\n  options: ExecutorEventBridgeOptions = {},\n): ExecutorEventBridge<T> {\n  const queueDepth = options.queueDepth ?? 256;\n  const buffer: T[] = [];\n  let pending: ((result: IteratorResult<T, undefined>) => void) | null = null;\n  let closed = false;\n  let dropped = 0;\n\n  const sink = (event: T): void => {\n    if (closed) {\n      return;\n    }\n    if (pending !== null) {\n      // A consumer is parked — hand the event off directly.\n      const resolve = pending;\n      pending = null;\n      resolve({ value: event, done: false });\n      return;\n    }\n    buffer.push(event);\n    if (buffer.length > queueDepth) {\n      buffer.shift();\n      dropped += 1;\n    }\n  };\n\n  async function* drain(): AsyncIterableIterator<T> {\n    for (;;) {\n      if (buffer.length > 0) {\n        const event = buffer.shift();\n        if (event !== undefined) {\n          yield event;\n        }\n        continue;\n      }\n      if (closed) {\n        return;\n      }\n      const next = await new Promise<IteratorResult<T, undefined>>((resolve) => {\n        pending = resolve;\n      });\n      if (next.done === true) {\n        return;\n      }\n      yield next.value;\n    }\n  }\n\n  const close = (): void => {\n    closed = true;\n    if (pending !== null) {\n      const resolve = pending;\n      pending = null;\n      resolve({ value: undefined, done: true });\n    }\n  };\n\n  return Object.freeze({\n    sink,\n    drain,\n    close,\n    get dropped(): number {\n      return dropped;\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwFA,SAAgB,oBAAoB,UAAiC,EAAE,EAAkB;CACvF,MAAMA,UACJ,QAAQ,YAAY,OAAO,QAAQ,cAAc,eAAe,IAAI,CAAC;AACvE,QAAO,OAAO,OAAO,EAAE,SAAS,SAAS,CAAC;;;;;;;;;;AA2G5C,SAAgB,iBACd,QACA,UAA8B,EAAE,EACb;AACnB,KAAI,WAAW,OACb,QAAO,OAAO,OAAO,EAAE,0BAA0B,MAAM,CAAC;CAG1D,MAAMC,sBACJ,SACkC;AAClC,UAAQ,MAAR;GACE,KAAK;GACL,KAAK,2BACH,QAAO,YAAY,EAAE,MAAM,CAAC;GAC9B,KAAK,UACH,QAAO,YAAY;IAAE;IAAM,GAAI,QAAQ,aAAa,EAAE;IAAG,CAAC;GAC5D,KAAK,YACH,QAAO,YAAY;IAAE;IAAM,GAAI,QAAQ,cAAc,EAAE;IAAG,CAAC;GAC7D,KAAK,eACH,QAAO,QAAQ,gBAAgB,SAC3B,OACA,YAAY;IAAE;IAAM,GAAG,QAAQ;IAAa,CAAC;GACnD,QACE,QAAO;;;AAIb,QAAO,OAAO,OACZ,QAAQ,iBAAiB,SACrB,EAAE,oBAAoB,GACtB;EAAE;EAAoB,oBAAoB,QAAQ;EAAc,CACrE;;;;;;;;AASH,SAAgB,yBACd,SACA,MACoB;AACpB,QAAO,OAAO,OAAO;EAAE,SAAS,OAAO,OAAO,CAAC,GAAG,QAAQ,CAAC;EAAE;EAAM,CAAC;;;;;;;;;;;;;;;;;;AAoCtE,SAAgB,sBAAsB,UAAmC,EAAE,EAAoB;CAC7F,MAAM,EAAE,aAAa;AACrB,KAAI,aAAa,OACf,QAAO;AAET,QAAO,OAAO,OAAO,EACnB,QAAQ,SAAyB,SAAS,KAAK,CAAC,QACjD,CAAC;;;;;;AAkDJ,SAAgB,0BACd,UAAsC,EAAE,EAChB;CACxB,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAMC,SAAc,EAAE;CACtB,IAAIC,UAAmE;CACvE,IAAI,SAAS;CACb,IAAI,UAAU;CAEd,MAAM,QAAQ,UAAmB;AAC/B,MAAI,OACF;AAEF,MAAI,YAAY,MAAM;GAEpB,MAAM,UAAU;AAChB,aAAU;AACV,WAAQ;IAAE,OAAO;IAAO,MAAM;IAAO,CAAC;AACtC;;AAEF,SAAO,KAAK,MAAM;AAClB,MAAI,OAAO,SAAS,YAAY;AAC9B,UAAO,OAAO;AACd,cAAW;;;CAIf,gBAAgB,QAAkC;AAChD,WAAS;AACP,OAAI,OAAO,SAAS,GAAG;IACrB,MAAM,QAAQ,OAAO,OAAO;AAC5B,QAAI,UAAU,OACZ,OAAM;AAER;;AAEF,OAAI,OACF;GAEF,MAAM,OAAO,MAAM,IAAI,SAAuC,YAAY;AACxE,cAAU;KACV;AACF,OAAI,KAAK,SAAS,KAChB;AAEF,SAAM,KAAK;;;CAIf,MAAM,cAAoB;AACxB,WAAS;AACT,MAAI,YAAY,MAAM;GACpB,MAAM,UAAU;AAChB,aAAU;AACV,WAAQ;IAAE,OAAO;IAAW,MAAM;IAAM,CAAC;;;AAI7C,QAAO,OAAO,OAAO;EACnB;EACA;EACA;EACA,IAAI,UAAkB;AACpB,UAAO;;EAEV,CAAC"}

package/dist/tooling/catalogue.js

@@ -0,0 +1,37 @@
+//#region src/tooling/catalogue.ts
+/**
+* A7 (SOTA): prompt-cache-aware tool-catalogue ordering.
+*
+* The per-step catalogue is `[...eagerTools, ...promotedTools, ...handoffTools]`.
+* The eager prefix is already stable (the registry lists in insertion order), so
+* the only source of churn is the promoted section: building it from the
+* registry's `listDeferred` order means a tool promoted on a later step can sort
+* BEFORE one promoted earlier, shifting the serialized suffix and invalidating
+* the provider's prompt-cache prefix on every subsequent step.
+*
+* `orderPromotedTools` instead emits promoted tools in PROMOTION order (the
+* insertion order of the promoted-name set), so a newly promoted tool always
+* joins the END — the catalogue grows append-only and earlier promotions keep
+* their byte position. A long-running assistant re-pays only for the new tail.
+*
+* @packageDocumentation
+*/
+/**
+* Resolve `promotedNames` (insertion-ordered) to the matching `deferred`
+* entries, preserving promotion order. Names absent from the pool (e.g. a tool
+* removed mid-run) are skipped.
+*/
+function orderPromotedTools(promotedNames, deferred) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const tool of deferred) byName.set(tool.name, tool);
+	const out = [];
+	for (const name of promotedNames) {
+		const tool = byName.get(name);
+		if (tool !== void 0) out.push(tool);
+	}
+	return out;
+}
+
+//#endregion
+export { orderPromotedTools };
+//# sourceMappingURL=catalogue.js.map

package/dist/tooling/catalogue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.js","names":["out: T[]"],"sources":["../../src/tooling/catalogue.ts"],"sourcesContent":["/**\n * A7 (SOTA): prompt-cache-aware tool-catalogue ordering.\n *\n * The per-step catalogue is `[...eagerTools, ...promotedTools, ...handoffTools]`.\n * The eager prefix is already stable (the registry lists in insertion order), so\n * the only source of churn is the promoted section: building it from the\n * registry's `listDeferred` order means a tool promoted on a later step can sort\n * BEFORE one promoted earlier, shifting the serialized suffix and invalidating\n * the provider's prompt-cache prefix on every subsequent step.\n *\n * `orderPromotedTools` instead emits promoted tools in PROMOTION order (the\n * insertion order of the promoted-name set), so a newly promoted tool always\n * joins the END — the catalogue grows append-only and earlier promotions keep\n * their byte position. A long-running assistant re-pays only for the new tail.\n *\n * @packageDocumentation\n */\n\n/**\n * Resolve `promotedNames` (insertion-ordered) to the matching `deferred`\n * entries, preserving promotion order. Names absent from the pool (e.g. a tool\n * removed mid-run) are skipped.\n */\nexport function orderPromotedTools<T extends { readonly name: string }>(\n  promotedNames: Iterable<string>,\n  deferred: ReadonlyArray<T>,\n): ReadonlyArray<T> {\n  const byName = new Map<string, T>();\n  for (const tool of deferred) byName.set(tool.name, tool);\n  const out: T[] = [];\n  for (const name of promotedNames) {\n    const tool = byName.get(name);\n    if (tool !== undefined) out.push(tool);\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBACd,eACA,UACkB;CAClB,MAAM,yBAAS,IAAI,KAAgB;AACnC,MAAK,MAAM,QAAQ,SAAU,QAAO,IAAI,KAAK,MAAM,KAAK;CACxD,MAAMA,MAAW,EAAE;AACnB,MAAK,MAAM,QAAQ,eAAe;EAChC,MAAM,OAAO,OAAO,IAAI,KAAK;AAC7B,MAAI,SAAS,OAAW,KAAI,KAAK,KAAK;;AAExC,QAAO"}