@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/handlers/resolve-blocks.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { pickVersion } from '@kindgi/tools';
+
+import {
+  type BlockDefinition,
+  MODEL_SETTINGS_SCHEMA,
+  type ModelSettings,
+  type PromptBlockContent,
+  settingsSchemaIssues,
+} from '../blocks.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/** The block versions a turn runs, by kind then id, as `setup` journals them. */
+export interface PinnedBlockVersions {
+  readonly prompts: Readonly<Record<string, string>>;
+  readonly settings: Readonly<Record<string, string>>;
+}
+
+/** The data blocks a turn runs with, loaded at its version. */
+export interface TurnBlocks {
+  /** The prompt block the instructions come from. */
+  readonly prompt?: {
+    readonly id: string;
+    readonly version: string;
+    readonly content: PromptBlockContent;
+  };
+  /** Each settings block's values, by block id (`ToolContext.settings`, `settings` in templates). */
+  readonly settings: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  /** The model-settings block's values, for the turn's model calls. */
+  readonly modelSettings?: ModelSettings;
+  readonly versions: PinnedBlockVersions;
+}
+
+interface Ref {
+  readonly kind: 'prompts' | 'settings';
+  readonly id: string;
+  readonly range: string;
+  readonly role: 'prompt' | 'settings' | 'model-settings';
+}
+
+/**
+ * Load the data blocks the agent references, each at one exact version:
+ * the resumed turn's own (`pinned`, from its `setup`), else the agent
+ * version's pin (`agent.pins`), else its range resolved now by
+ * `pickVersion` (an agent version published before pins). A pinned
+ * version that's unregistered still loads; one that's gone, a range
+ * nothing satisfies, or a runtime with no blocks fails the turn
+ * (`block-unresolvable`). `undefined` when the agent references none.
+ */
+export async function resolveTurnBlocks(
+  ctx: TurnContext,
+  pinned?: PinnedBlockVersions,
+): Promise<TurnBlocks | undefined> {
+  const agent = ctx.input.agent;
+  const refs = blockRefs(ctx);
+  if (refs.length === 0) return undefined;
+  const reader = ctx.bindings.blockReader;
+  if (reader === undefined) {
+    fail(
+      refs[0] as Ref,
+      `agent "${agent.id}" references data blocks, but this runtime serves none`,
+    );
+  }
+
+  const versions = {
+    prompts: {} as Record<string, string>,
+    settings: {} as Record<string, string>,
+  };
+  const loaded = new Map<Ref, BlockDefinition>();
+  for (const ref of refs) {
+    const version =
+      pinned?.[ref.kind][ref.id] ??
+      agent.pins?.[ref.kind][ref.id] ??
+      (await resolveRange(ctx, ref));
+    const block = await reader.getVersion({
+      tenantId: ctx.input.tenantId,
+      blockId: ref.id,
+      version,
+    });
+    if (block === null) {
+      fail(ref, `${describe(ref)} runs version ${version}, which isn't published`);
+    }
+    if (block.kind !== (ref.role === 'prompt' ? 'prompt' : 'settings')) {
+      fail(ref, `${describe(ref)} is a ${block.kind} block`);
+    }
+    versions[ref.kind][ref.id] = version;
+    loaded.set(ref, block);
+  }
+  return turnBlocks(refs, loaded, versions);
+}
+
+function blockRefs(ctx: TurnContext): Ref[] {
+  const agent = ctx.input.agent;
+  const refs: Ref[] = [];
+  if (typeof agent.instructions === 'object') {
+    refs.push({
+      kind: 'prompts',
+      id: agent.instructions.prompt,
+      range: agent.instructions.version,
+      role: 'prompt',
+    });
+  }
+  for (const s of agent.settings ?? []) {
+    refs.push({ kind: 'settings', id: s.id, range: s.version, role: 'settings' });
+  }
+  if (agent.modelSettings !== undefined) {
+    refs.push({
+      kind: 'settings',
+      id: agent.modelSettings.id,
+      range: agent.modelSettings.version,
+      role: 'model-settings',
+    });
+  }
+  return refs;
+}
+
+/** An unpinned reference's range, resolved over the block's active versions. */
+async function resolveRange(ctx: TurnContext, ref: Ref): Promise<string> {
+  const available =
+    (await ctx.bindings.blockReader?.activeVersions({
+      tenantId: ctx.input.tenantId,
+      blockId: ref.id,
+    })) ?? [];
+  const pick = pickVersion(available, ref.range);
+  if (pick.kind === 'ok') return pick.version;
+  return fail(
+    ref,
+    available.length === 0
+      ? `${describe(ref)} has no published version`
+      : `${describe(ref)} has no published version in "${ref.range}" (published: ${available.join(', ')})`,
+  );
+}
+
+function turnBlocks(
+  refs: readonly Ref[],
+  loaded: ReadonlyMap<Ref, BlockDefinition>,
+  versions: PinnedBlockVersions,
+): TurnBlocks {
+  const settings: Record<string, Readonly<Record<string, unknown>>> = {};
+  let prompt: TurnBlocks['prompt'];
+  let modelSettings: ModelSettings | undefined;
+  for (const ref of refs) {
+    const block = loaded.get(ref) as BlockDefinition;
+    if (block.kind === 'prompt') {
+      prompt = { id: block.id, version: block.version, content: block.content };
+    } else if (ref.role === 'model-settings') {
+      const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+      if (issues.length > 0) {
+        fail(
+          ref,
+          `${describe(ref)} version ${block.version} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`,
+        );
+      }
+      modelSettings = block.content.values as ModelSettings;
+    } else {
+      settings[block.id] = block.content.values;
+    }
+  }
+  return {
+    ...(prompt !== undefined && { prompt }),
+    settings,
+    ...(modelSettings !== undefined && { modelSettings }),
+    versions,
+  };
+}
+
+function describe(ref: Ref): string {
+  const what =
+    ref.role === 'prompt'
+      ? 'prompt'
+      : ref.role === 'model-settings'
+        ? 'model-settings'
+        : 'settings';
+  return `${what} block "${ref.id}"`;
+}
+
+function fail(ref: Ref, message: string): never {
+  return throwAgentTurnFailure({
+    code: 'block-unresolvable',
+    message,
+    blockId: ref.id,
+    requestedRange: ref.range,
+  });
+}

package/src/handlers/resolve-tools.ts

@@ -2,9 +2,10 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { ModelToolDefinition } from '@kindgi/capabilities';
-import type { Tool, ToolRegistry } from '@kindgi/tools';
+import type { Tool, ToolError, ToolRegistry, ToolResolution } from '@kindgi/tools';
+import type { Result, ToolId } from '@kindgi/types';
 
-import type { Agent } from '../types.js';
+import type { Agent, ToolRef } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
@@ -12,11 +13,16 @@ import { throwAgentTurnFailure } from './errors.js';
 /**
  * Resolve the agent's tool references against one tenant's registry
  * (`ToolRegistry.forTenant`). Throws the turn failure for an unknown
- * tool or an unsatisfiable version range.
+ * tool or an unsatisfiable version range. A tool in `pinned` (a resumed
+ * turn's, from its `setup`) resolves to exactly that version, and so,
+ * otherwise, does one in the agent version's own pins (`agent.pins`, set
+ * when it was published): one that's gone fails the turn rather than
+ * running another. Without either, the tool's range resolves.
  */
 export function resolveTurnTools(
   registry: ToolRegistry,
   agent: Agent,
+  pinned?: Readonly<Record<string, string>>,
 ): NonNullable<TurnContext['tools']> {
   const definitions: ModelToolDefinition[] = [];
   const byName = new Map<
@@ -29,32 +35,16 @@ export function resolveTurnTools(
     // (npm-compatible semver, backed by `maxSatisfying`); capture `resolvedVersion` in
     // the byName map so `dispatch-tools` can emit it in provenance +
     // telemetry — a replay can then pin against the same version.
-    const resolved = registry.resolve(ref.id as never, ref.version);
+    const turnPin = pinned?.[ref.id];
+    const pin = turnPin ?? agent.pins?.tools[ref.id];
+    // A pin names its exact version, which a retired (unregistered) one
+    // still serves; a range picks among the active versions only.
+    const resolved =
+      pin !== undefined
+        ? exactVersion(registry, ref.id, pin)
+        : registry.resolve(ref.id as never, ref.version);
     if (resolved.kind === 'err') {
-      const err = resolved.error;
-      if (err.code === 'tool-not-found') {
-        throwAgentTurnFailure({
-          code: 'unresolved-tool',
-          message: `Tool "${ref.id}" declared by agent "${agent.id}" is not registered`,
-          toolId: ref.id,
-        });
-      }
-      if (err.code === 'invalid-version-range' || err.code === 'tool-version-unresolvable') {
-        throwAgentTurnFailure({
-          code: 'tool-version-unresolvable',
-          message: err.message,
-          toolId: ref.id,
-          requestedRange: ref.version,
-          ...(err.code === 'tool-version-unresolvable' && {
-            availableVersions: err.availableVersions,
-          }),
-        });
-      }
-      throwAgentTurnFailure({
-        code: 'unresolved-tool',
-        message: err.message,
-        toolId: ref.id,
-      });
+      throwUnresolved(agent, ref, resolved.error, pin, turnPin !== undefined ? 'turn' : 'agent');
     }
     const { tool, resolvedVersion } = resolved.value;
     definitions.push({
@@ -66,3 +56,61 @@ export function resolveTurnTools(
   }
   return { definitions, byName };
 }
+
+/** A pinned tool version, retired or not, as a resolution. */
+function exactVersion(
+  registry: ToolRegistry,
+  id: string,
+  version: string,
+): Result<ToolResolution, ToolError> {
+  const found = registry.getVersion(id as ToolId, version);
+  return found.kind === 'ok'
+    ? { kind: 'ok', value: { tool: found.value, resolvedVersion: version } }
+    : found;
+}
+
+/**
+ * Fail the turn for a tool that didn't resolve. A pinned version that's
+ * gone names whose pin it was: the turn's own (it started with that
+ * version) or the agent version's (it was published with it).
+ */
+function throwUnresolved(
+  agent: Agent,
+  ref: ToolRef,
+  err: ToolError,
+  pin: string | undefined,
+  pinnedBy: 'turn' | 'agent',
+): never {
+  const available = err.code === 'tool-version-unresolvable' && {
+    availableVersions: err.availableVersions,
+  };
+  if (pin !== undefined) {
+    throwAgentTurnFailure({
+      code: 'tool-version-unresolvable',
+      message:
+        pinnedBy === 'turn'
+          ? `Tool "${ref.id}": this turn started with version ${pin}, which is no longer registered; it doesn't run another version mid-turn. ${err.message}`
+          : `Tool "${ref.id}": agent "${agent.id}" version ${agent.version} runs version ${pin} (its pins), which isn't registered; it doesn't run another version. ${err.message}`,
+      toolId: ref.id,
+      requestedRange: ref.version,
+      ...available,
+    });
+  }
+  if (err.code === 'tool-not-found') {
+    throwAgentTurnFailure({
+      code: 'unresolved-tool',
+      message: `Tool "${ref.id}" declared by agent "${agent.id}" is not registered`,
+      toolId: ref.id,
+    });
+  }
+  if (err.code === 'invalid-version-range' || err.code === 'tool-version-unresolvable') {
+    throwAgentTurnFailure({
+      code: 'tool-version-unresolvable',
+      message: err.message,
+      toolId: ref.id,
+      requestedRange: ref.version,
+      ...available,
+    });
+  }
+  throwAgentTurnFailure({ code: 'unresolved-tool', message: err.message, toolId: ref.id });
+}

package/src/handlers/result-shape.ts

@@ -7,6 +7,8 @@ import type { RunId } from '@kindgi/types';
 
 import type { ConversationId, ConversationMessage, RetrievedFact } from '../types.js';
 
+import type { ReplayTurnReport } from './replay.js';
+
 /**
  * Public shape returned by `invokeAgent` on success. Extracted from
  * `invoke.ts` into this module so handler code can import the type
@@ -70,6 +72,12 @@ export interface AgentTurnResult {
    * `response.content`.
    */
   readonly status?: 'completed' | 'suspended';
+  /**
+   * A replay turn's report (`InvokeAgentInput.replay`): each tool call and
+   * whether it ran, used the past run's result, or was refused (what the
+   * turn would have done), and how the session approval gate went.
+   */
+  readonly replay?: ReplayTurnReport;
 }
 
 /**

package/src/handlers/run-retrievals.ts

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { NodeHandler } from '@kindgi/handler';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
 
 import { runRetrievals } from '../retrieval.js';
 import { emitTurnEvent } from '../streaming.js';
+import type { RetrievedFact } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addRetrievalNodes } from './turn-provenance.js';
 
 /**
  * Execute the agent's declared retrieval intents. Populates
@@ -16,7 +18,7 @@ import { throwAgentTurnFailure } from './errors.js';
  * is wired.
  */
 export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
-  return async () => {
+  return async (_input, kctx) => {
     if (ctx.conversation === undefined || ctx.userMessage === undefined) {
       throwAgentTurnFailure({
         code: 'model-invocation-failed',
@@ -24,54 +26,56 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
         cause: null,
       });
     }
-    const retrieved = await runRetrievals(
-      ctx.input.agent,
-      ctx.conversation,
-      ctx.input.conversationId,
-      ctx.input.userMessage,
-      {
-        memory: ctx.bindings.memoryBinding,
-        ...(ctx.bindings.embeddingRegistry !== undefined && {
-          embeddingRegistry: ctx.bindings.embeddingRegistry,
-        }),
-        ...(ctx.bindings.embeddingModel !== undefined && {
-          embeddingModel: ctx.bindings.embeddingModel,
-        }),
-      },
-    );
-    if (retrieved.kind === 'err') throwAgentTurnFailure(retrieved.error);
-    ctx.retrieved = retrieved.value;
+    const facts = (await recordedRetrievals(ctx, kctx)) ?? (await retrieveLive(ctx));
+    ctx.retrieved = facts;
 
     await emitTurnEvent(ctx.bindings.onEvent, {
       kind: 'retrieval.completed',
-      count: retrieved.value.length,
-      factIds: retrieved.value.map((r) => r.fact.id),
+      count: facts.length,
+      factIds: facts.map((r) => r.fact.id),
     });
 
     if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-      for (const r of retrieved.value) {
-        ctx.provenance.addNode({
-          id: `retrieval:${r.fact.id}`,
-          kind: 'retrieval',
-          timestamp: ctx.userMessage.createdAt,
-          ...(r.fact.contentHash !== undefined && { contentHash: r.fact.contentHash }),
-          attributes: {
-            factId: r.fact.id,
-            factType: r.fact.type,
-            intentScope: r.intent.scope,
-            ...(r.score !== undefined && { score: r.score }),
-          },
-        });
-        ctx.provenance.addEdge({
-          from: `retrieval:${r.fact.id}`,
-          to: `input:${ctx.userMessage.sequence}`,
-          kind: 'influenced-by',
-        });
-      }
+      addRetrievalNodes(ctx.provenance, facts, ctx.userMessage);
     }
 
     // The facts go in the journal: a resumed turn restores them from it
     // (`rehydrateTurnContext`) rather than retrieving again.
-    return { count: retrieved.value.length, retrieved: retrieved.value };
+    return { count: facts.length, retrieved: facts };
   };
 }
+
+/** A replay's retrievals: what the past run retrieved, when the replay binding has it. */
+async function recordedRetrievals(
+  ctx: TurnContext,
+  kctx: NodeContext,
+): Promise<readonly RetrievedFact[] | undefined> {
+  const replay = ctx.input.replay;
+  if (replay === undefined || ctx.bindings.replay?.retrievals === undefined) return undefined;
+  return ctx.bindings.replay.retrievals({
+    tenantId: ctx.input.tenantId,
+    runId: kctx.runId,
+    replay,
+  });
+}
+
+async function retrieveLive(ctx: TurnContext): Promise<readonly RetrievedFact[]> {
+  if (ctx.conversation === undefined) return [];
+  const retrieved = await runRetrievals(
+    ctx.input.agent,
+    ctx.conversation,
+    ctx.input.conversationId,
+    ctx.input.userMessage,
+    {
+      memory: ctx.bindings.memoryBinding,
+      ...(ctx.bindings.embeddingRegistry !== undefined && {
+        embeddingRegistry: ctx.bindings.embeddingRegistry,
+      }),
+      ...(ctx.bindings.embeddingModel !== undefined && {
+        embeddingModel: ctx.bindings.embeddingModel,
+      }),
+    },
+  );
+  if (retrieved.kind === 'err') throwAgentTurnFailure(retrieved.error);
+  return retrieved.value;
+}

package/src/handlers/run-snapshot.ts

@@ -40,5 +40,6 @@ export async function writeRunSnapshot(ctx: TurnContext, kctx: NodeContext): Pro
     ...(ctx.input.dryRun === true && { dryRun: true }),
     ...(ctx.input.principal !== undefined && { principal: ctx.input.principal }),
     ...(ctx.input.authz !== undefined && { authz: ctx.input.authz }),
+    ...(ctx.input.replay !== undefined && { replay: ctx.input.replay }),
   });
 }

package/src/handlers/setup.ts

@@ -11,12 +11,15 @@ import { emitTurnEvent } from '../streaming.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { SESSION_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
+import { followReplaySessionGate } from './replay.js';
 import { writeRunSnapshot } from './run-snapshot.js';
 import {
   loadTurnConversation,
   resolveTurnEnvironment,
   resolveTurnHitlPolicy,
 } from './turn-environment.js';
+import { decisionOf } from './turn-provenance.js';
 
 /**
  * Deterministic waitpoint token — must produce the same value on every
@@ -35,7 +38,7 @@ function computeSessionGateWaitToken(input: {
 }
 
 /** The `record` key of the session gate's decision. */
-const SESSION_GATE_RECORD = 'session-hitl-gate';
+export const SESSION_GATE_RECORD = 'session-hitl-gate';
 
 /**
  * The session gate's decision, as `setup` records it the first time
@@ -51,16 +54,6 @@ interface SessionGateRecord {
   readonly timeoutMs: number;
 }
 
-/**
- * Shape the setup handler expects when a session-gate waitpoint
- * resolves. Approvals-complete route materializes this from the
- * reviewer's decision (see packages/api/src/routes/approvals.ts).
- */
-interface SessionGateDecision {
-  readonly decided: 'approve' | 'reject';
-  readonly rationale?: string;
-}
-
 /**
  * The first node in the flow. Runs every precondition check in one
  * gate so the run either commits to a full turn or fails fast before
@@ -148,7 +141,11 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
         timeoutMs: effectiveHitl.timeoutMs,
       };
     });
-    if (gate !== undefined) {
+    if (gate !== undefined && ctx.input.replay !== undefined) {
+      // A replay follows the past run's decision at this gate, or skips it
+      // when none was recorded; it never waits for a reviewer.
+      await followReplaySessionGate(ctx, kctx);
+    } else if (gate !== undefined) {
       const { waitTokenId, timeoutMs } = gate;
       const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
 
@@ -156,7 +153,8 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
         try {
           await ctx.bindings.hitl.enqueue({
             tenantId: ctx.input.tenantId,
-            subjectKind: 'agent-turn:session-hitl-gate',
+            projectId: ctx.input.projectId,
+            subjectKind: SESSION_GATE_SUBJECT,
             subjectRef: {
               conversationId: ctx.input.conversationId,
               agentId: ctx.input.agent.id,
@@ -200,9 +198,11 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
       }
 
       try {
-        const decision = await kctx.waitForToken<SessionGateDecision>(waitTokenId, {
-          timeoutMs,
-        });
+        // Fails closed: only an explicit approve lets the turn go on
+        // (`readGateDecision`).
+        const decision = readGateDecision(
+          await kctx.waitForToken<unknown>(waitTokenId, { timeoutMs }),
+        );
         // Post-resume: emit the resume node + resumed-from edge. Only
         // runs on the REPLAY path — the first execution throws
         // SuspensionSignal inside waitForToken and never gets here.
@@ -211,11 +211,14 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
             id: resumeNodeId,
             kind: 'resume',
             timestamp: new Date().toISOString() as never,
-            actor: `agent:${ctx.input.agent.id as unknown as string}`,
+            // Whoever decided; a decision recorded before it named them, the agent.
+            actor: decision.decidedBy ?? `agent:${ctx.input.agent.id as unknown as string}`,
             attributes: {
               gate: 'session-hitl',
-              decision: decision.decided,
-              ...(decision.rationale !== undefined && { rationale: decision.rationale }),
+              decision: decisionOf(decision),
+              ...(!decision.approved &&
+                decision.rationale !== undefined && { rationale: decision.rationale }),
+              ...(decision.approvalId !== undefined && { approvalId: decision.approvalId }),
             },
           });
           ctx.provenance.addEdge({
@@ -225,7 +228,7 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
           });
         }
 
-        if (decision.decided === 'reject') {
+        if (!decision.approved) {
           throwAgentTurnFailure({
             code: 'hitl-rejected',
             message: `Reviewer rejected the session-HITL gate${
@@ -234,8 +237,7 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
             ...(decision.rationale !== undefined && { rationale: decision.rationale }),
           } as never);
         }
-        // decision.decided === 'approve' → fall through, turn proceeds
-        // normally through the rest of setup.
+        // Approved: the turn proceeds through the rest of setup.
       } catch (cause) {
         if (cause instanceof WaitpointCancelledError) {
           // Emit resume node with cancelled attribute so the DAG still
@@ -293,6 +295,12 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
       providerId: environment.providerId,
       providerModel: environment.model,
       toolCount: environment.toolCount,
+      // The version each tool resolved to: a resumed turn runs these.
+      toolVersions: environment.toolVersions,
+      // And each data block's.
+      ...(environment.blockVersions !== undefined && {
+        blockVersions: environment.blockVersions,
+      }),
     };
   };
 }

package/src/handlers/tool-hitl.ts

@@ -83,6 +83,12 @@ function canonicalStringify(value: unknown): string {
   return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`).join(',')}}`;
 }
 
+/**
+ * The `NodeContext.record` key of a tool call's gate, before its call id:
+ * the journal names the waitpoint a call parked on under this key.
+ */
+export const TOOL_GATE_RECORD_PREFIX = 'tool-hitl-gate:';
+
 /**
  * Deterministic waitpoint token for a tool-call gate. Includes both
  * the model-generated call id (unique per iteration) AND the args hash
@@ -100,16 +106,6 @@ export function computeToolCallWaitToken(input: {
     .slice(0, 40);
 }
 
-/**
- * Shape the tool-level waitpoint resolves to when the reviewer decides.
- * Same shape as session-gate decisions — the approvals-complete route
- * materializes it identically.
- */
-export interface ToolHitlDecision {
-  readonly decided: 'approve' | 'reject';
-  readonly rationale?: string;
-}
-
 /**
  * In-conversation cache of decisions for `ask_on_first_use`. Persisted
  * on `agent_conversations.metadata.hitlToolDecisions` — a flat map of