@kindgi/agents 0.1.2 → 0.1.3

package/src/handlers/model-call.ts

@@ -1,13 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { ModelCallInput, ModelMessage } from '@kindgi/capabilities';
-import type { NodeHandler } from '@kindgi/handler';
+import { randomUUID } from 'node:crypto';
+
+import {
+  type ModelCallInput,
+  type ModelMessage,
+  type ModelProvider,
+  type ModelUsageRecord,
+  recordModelUsage,
+} from '@kindgi/capabilities';
+import { attemptsOf } from '@kindgi/capabilities/attempts';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
+import type { Timestamp } from '@kindgi/types';
 
 import { emitTurnEvent } from '../streaming.js';
 
 import type { AgentTurnIterationOutput, TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addModelCallNode } from './turn-provenance.js';
 
 /**
  * Loop-body node #1. Invoke the model with the current
@@ -15,6 +26,16 @@ import { throwAgentTurnFailure } from './errors.js';
  * `model.call.completed`, records provenance for the model-call node,
  * and accumulates usage on `ctx.usage`.
  *
+ * Every call is recorded in the usage sink (`InvokeAgentBindings.usage`,
+ * the runtime's cost ledger) before the step goes on, a call that threw
+ * included. A sink that fails is tried again (a record is idempotent by
+ * call id); one that still fails fails the step when the call succeeded,
+ * so no answered call is left unrecorded. A call that failed keeps its
+ * own failure, which says it couldn't be recorded too. The call's id goes into
+ * the step's output and its provenance node, which keeps the call's
+ * identity (provider, model) while its usage lives in the ledger. A dry
+ * run spends nothing and records nothing.
+ *
  * Output is a partial `AgentTurnIterationOutput` — `dispatch-tools`
  * receives it and finishes composing the iteration output.
  */
@@ -31,6 +52,8 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
     const nextMessages: readonly ModelMessage[] = shaped?.nextMessages ?? [];
 
     ctx.usage.steps += 1;
+    const step = ctx.usage.steps;
+    const callId = randomUUID();
 
     await emitTurnEvent(ctx.bindings.onEvent, {
       kind: 'model.call.started',
@@ -63,25 +86,13 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
         abortSignal: ctx.turnAbort.signal,
       };
 
+      const startedAt = Date.now();
       try {
         callResult = await ctx.provider.invoke(callInput);
       } catch (cause) {
-        if (ctx.turnAbort.signal.aborted) {
-          throwAgentTurnFailure({
-            code: 'agent-turn-aborted',
-            message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}`,
-            reason: ctx.abortReason ?? 'timeout',
-          });
-        }
-        // The provider's own words (a 401's "invalid x-api-key", a 429)
-        // are what the caller needs; they're in `cause` too, but callers
-        // show `message`.
-        throwAgentTurnFailure({
-          code: 'model-invocation-failed',
-          message: `Model call to ${ctx.provider.metadata.id} (${ctx.model.name}) failed: ${describeCause(cause)}`,
-          cause,
-        });
+        return await failCall(ctx, kctx, { callId, step, cause, startedAt });
       }
+      await recordAnswer(ctx, kctx, callId, step, callResult);
     }
 
     ctx.usage.promptTokens += callResult.usage.promptTokens;
@@ -100,32 +111,27 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
     });
 
     if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-      const modelCallNodeId = `model-call:${ctx.usage.steps}`;
-      ctx.provenance.addNode({
-        id: modelCallNodeId,
-        kind: 'model-call',
-        timestamp: new Date().toISOString() as never,
-        modelVersion: `${callResult.provider.id}/${callResult.provider.model}`,
-        attributes: {
+      addModelCallNode(
+        ctx.provenance,
+        {
           step: ctx.usage.steps,
-          promptTokens: callResult.usage.promptTokens,
-          completionTokens: callResult.usage.completionTokens,
-          costUsd: callResult.costUsd,
+          callId,
+          provider: callResult.provider,
           finishReason: callResult.finishReason,
+          at: new Date().toISOString() as Timestamp,
         },
-      });
-      ctx.provenance.addEdge({
-        from: modelCallNodeId,
-        to: `input:${ctx.userMessage.sequence}`,
-        kind: 'caused-by',
-      });
+        ctx.userMessage.sequence,
+        ctx.toolResultIds ?? [],
+      );
     }
 
     // Partial iteration output — `dispatch-tools` finishes it.
     const partial: Omit<AgentTurnIterationOutput, 'iterationAppended' | 'finishedTurn'> & {
       readonly step: number;
+      readonly callId: string;
     } = {
       step: ctx.usage.steps,
+      callId,
       finishReason: callResult.finishReason,
       message: callResult.message,
       iterationUsage: {
@@ -140,6 +146,116 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
   };
 }
 
+/**
+ * A call that answered: record it before the step goes on. A sink that
+ * still fails after its retries fails the step: an answered call isn't
+ * left unrecorded.
+ */
+async function recordAnswer(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  callId: string,
+  step: number,
+  answer: Awaited<ReturnType<ModelProvider['invoke']>>,
+): Promise<void> {
+  const { message: _answer, ...result } = answer;
+  const unrecorded = await recordCall(ctx, kctx, {
+    callId,
+    step,
+    status: 'ok',
+    result,
+    durationMs: answer.durationMs,
+  });
+  if (unrecorded !== undefined) {
+    throwAgentTurnFailure({
+      code: 'persistence-error',
+      message: `The model call couldn't be recorded: ${describeCause(unrecorded)}`,
+      cause: unrecorded,
+    });
+  }
+}
+
+/**
+ * A call that threw: record it, then fail the step with the call's own
+ * failure (aborted, or the provider's words). A record that failed too
+ * is said after it.
+ */
+async function failCall(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  failed: {
+    readonly callId: string;
+    readonly step: number;
+    readonly cause: unknown;
+    readonly startedAt: number;
+  },
+): Promise<never> {
+  const { cause } = failed;
+  const attempts = attemptsOf(cause);
+  const unrecorded = await recordCall(ctx, kctx, {
+    callId: failed.callId,
+    step: failed.step,
+    status: 'failed',
+    error: { message: describeCause(cause), ...(attempts !== undefined && { attempts }) },
+    durationMs: Date.now() - failed.startedAt,
+  });
+  const andUnrecorded =
+    unrecorded === undefined
+      ? ''
+      : ` (and the failed call couldn't be recorded: ${describeCause(unrecorded)})`;
+  if (ctx.turnAbort.signal.aborted) {
+    throwAgentTurnFailure({
+      code: 'agent-turn-aborted',
+      message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}${andUnrecorded}`,
+      reason: ctx.abortReason ?? 'timeout',
+    });
+  }
+  // The provider's own words (a 401's "invalid x-api-key", a 429) are
+  // what the caller needs; they're in `cause` too, but callers show
+  // `message`.
+  throwAgentTurnFailure({
+    code: 'model-invocation-failed',
+    message: `Model call to ${ctx.provider?.metadata.id} (${ctx.model?.name}) failed: ${describeCause(cause)}${andUnrecorded}`,
+    cause,
+  });
+}
+
+/** What the call came to, for `recordCall`. */
+type CallOutcome = Pick<
+  ModelUsageRecord,
+  'callId' | 'step' | 'status' | 'result' | 'error' | 'durationMs'
+>;
+
+/**
+ * Record a model call in the usage sink, when the turn has one, trying
+ * a failing sink again. Resolves with the sink's last failure when it
+ * couldn't record; the caller decides what that means for the step.
+ */
+async function recordCall(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  call: CallOutcome,
+): Promise<unknown | undefined> {
+  const sink = ctx.bindings.usage;
+  if (sink === undefined || ctx.provider === undefined || ctx.model === undefined) return;
+  const { input } = ctx;
+  const recorded = await recordModelUsage(sink, {
+    ...call,
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    runId: kctx.runId,
+    agentId: input.agent.id as unknown as string,
+    agentVersion: input.agent.version,
+    conversationId: input.conversationId as unknown as string,
+    nodeId: kctx.nodeId as unknown as string,
+    providerId: ctx.provider.metadata.id,
+    model: ctx.model.name,
+    ...(ctx.provider.metadata.fallback === true && { fallback: true }),
+    occurredAt: new Date().toISOString(),
+  });
+  return recorded.kind === 'err' ? (recorded.error ?? new Error('no detail')) : undefined;
+}
+
 /** Longest cause text a failure message carries. */
 const MAX_CAUSE_CHARS = 500;
 

package/src/handlers/persist-provenance.ts

@@ -28,7 +28,9 @@ export function buildPersistProvenanceHandler(ctx: TurnContext): NodeHandler {
       // want).
       return { persisted: false };
     }
-    const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings);
+    const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings, {
+      projectId: ctx.input.projectId,
+    });
     if (persisted.kind === 'ok') {
       ctx.persistedProvenance = persisted.value;
       return { persisted: true };

package/src/handlers/persist-user-message.ts

@@ -8,6 +8,7 @@ import type { ConversationMessage } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addInputNode } from './turn-provenance.js';
 
 /**
  * Persist the caller's user message BEFORE the model is called. A
@@ -33,14 +34,7 @@ export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
       ctx.userMessage = synthetic;
       ctx.appended.push(synthetic);
 
-      if (ctx.provenance !== undefined) {
-        ctx.provenance.addNode({
-          id: `input:${synthetic.sequence}`,
-          kind: 'input',
-          timestamp: synthetic.createdAt,
-          ...(synthetic.actor !== undefined && { actor: synthetic.actor }),
-        });
-      }
+      if (ctx.provenance !== undefined) addInputNode(ctx.provenance, synthetic);
       return { sequence: synthetic.sequence };
     }
 
@@ -56,14 +50,7 @@ export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
     ctx.userMessage = persisted.value;
     ctx.appended.push(persisted.value);
 
-    if (ctx.provenance !== undefined) {
-      ctx.provenance.addNode({
-        id: `input:${persisted.value.sequence}`,
-        kind: 'input',
-        timestamp: persisted.value.createdAt,
-        ...(persisted.value.actor !== undefined && { actor: persisted.value.actor }),
-      });
-    }
+    if (ctx.provenance !== undefined) addInputNode(ctx.provenance, persisted.value);
 
     return { sequence: persisted.value.sequence };
   };

package/src/handlers/public-types.ts

@@ -2,13 +2,13 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Principal } from '@kindgi/authz';
-import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabilities';
 import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
 import type { MemoryQueryBinding } from '@kindgi/memory';
 import type { PolicyRegistry } from '@kindgi/policy-contract';
 import type { ParentRunRef, RunBinding } from '@kindgi/runtime';
 import type { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
-import type { ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
+import type { OrgId, ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
 import type { ConversationBinding } from '../conversation-binding.js';
 import type { GuardrailsBindings } from '../guardrails-gate.js';
@@ -32,6 +32,12 @@ export interface InvokeAgentInput {
    * at the caller layer.
    */
   readonly projectId: ProjectId;
+  /**
+   * The project's org, when it belongs to one: the runtime resolves it
+   * from the project, never from input. The turn's tools get it as
+   * `ToolContext.orgId`, its guardrails as `trace.orgId`.
+   */
+  readonly orgId?: OrgId;
   readonly agent: Agent;
   readonly conversationId: ConversationId;
   readonly userMessage: string;
@@ -153,6 +159,12 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
   readonly onEvent?: OnTurnEvent;
   readonly provenance?: ProvenanceBindings;
   readonly hitl?: HitlBindings;
+  /**
+   * Where the turn records each model call (the runtime's cost ledger):
+   * its usage, provider, model, run, agent and step, before the step
+   * that made it goes on. Absent: calls aren't recorded.
+   */
+  readonly usage?: UsageSink;
   /**
    * Declarative HTTP tools: optional secret resolver populated
    * from the deployment's tenant-scoped `SecretBinding`. When present,
@@ -171,6 +183,8 @@ export interface HitlBindings {
 
 export interface HitlEnqueueInput {
   readonly tenantId: TenantId;
+  /** The turn's project: approval lists filter by it. */
+  readonly projectId?: ProjectId;
   readonly subjectKind: string;
   readonly subjectRef: Readonly<Record<string, unknown>>;
   readonly requiredRole?: 'standard' | 'senior' | 'admin';

package/src/handlers/rehydrate.ts

@@ -27,26 +27,45 @@
  * A turn parked inside `setup` (the session gate) re-runs `setup`, and
  * nothing here applies.
  *
- * Not restored: provenance nodes recorded before the park. The resumed
- * turn's provenance covers what happens from the resume on.
+ *   - the provenance nodes of the steps that ran before the park are
+ *     added again from what they left (`turn-provenance.ts`), so a
+ *     resumed turn's DAG is whole: its user message, its retrievals, each
+ *     model call, and the tool calls of each completed step. The step the
+ *     turn parked in adds its own when it runs again;
+ *   - the tool-call approvals decided so far come from the journal (the
+ *     waitpoint each gate recorded, when the call parked, the decision
+ *     and when it came), so each call's provenance shows the approval it
+ *     waited on and who decided it.
  */
 
 import type { LoopContext } from '@kindgi/handler';
-import { type JournalEntry, bodyStepKey } from '@kindgi/runtime';
+import { type JournalEntry, type ValueRecordedPayload, bodyStepKey } from '@kindgi/runtime';
+import type { Timestamp } from '@kindgi/types';
 
 import type { ConversationMessage, RetrievedFact } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { readGateDecision } from './gate-decision.js';
+import { TOOL_GATE_RECORD_PREFIX } from './tool-hitl.js';
 import {
   loadTurnConversation,
   resolveTurnEnvironment,
   resolveTurnHitlPolicy,
 } from './turn-environment.js';
+import {
+  addInputNode,
+  addModelCallNode,
+  addRetrievalNodes,
+  addStepToolNodes,
+} from './turn-provenance.js';
+import type { ToolApproval } from './turn-provenance.js';
 
 interface StepRecord {
   readonly nodeId: string;
   readonly output: unknown;
   readonly inLoop: boolean;
+  /** When the step completed. */
+  readonly at: Timestamp;
 }
 
 /** Each step's last completion — a step at one loop iteration counts once. */
@@ -67,6 +86,7 @@ function completedSteps(journal: readonly JournalEntry[]): readonly StepRecord[]
       nodeId: e.nodeId as unknown as string,
       output: payload.output,
       inLoop: payload.loopContext !== undefined,
+      at: e.timestamp,
     });
   }
   return [...byStep.values()];
@@ -129,9 +149,106 @@ export async function rehydrateTurnContext(
     ctx.usage.totalCostUsd += out.iterationUsage?.costUsd ?? 0;
     if (out.provider !== undefined) ctx.lastProvider = out.provider;
   }
+  ctx.toolApprovals = toolApprovalsOf(journal);
+  rebuildProvenance(ctx, steps, retrievals?.retrieved);
   return true;
 }
 
+/**
+ * The tool-call approvals the journal shows decided, by invocation id: the
+ * waitpoint each call's gate recorded (`dispatch-tools`), when the call
+ * parked on it (`wait.suspended`, the first), and the decision that
+ * resolved it (`wait.resumed`).
+ */
+function toolApprovalsOf(journal: readonly JournalEntry[]): ReadonlyMap<string, ToolApproval> {
+  const callOf = new Map<string, string>();
+  const parkedAt = new Map<string, Timestamp>();
+  const resumed = new Map<string, { readonly at: Timestamp; readonly value: unknown }>();
+  for (const e of journal) {
+    const gate = toolGateOf(e);
+    if (gate !== undefined) callOf.set(gate.waitTokenId, gate.invocationId);
+    const p = (e.payload ?? {}) as { readonly tokenId?: unknown; readonly value?: unknown };
+    if (typeof p.tokenId !== 'string') continue;
+    if (e.kind === 'wait.suspended' && !parkedAt.has(p.tokenId)) {
+      parkedAt.set(p.tokenId, e.timestamp);
+    }
+    if (e.kind === 'wait.resumed') resumed.set(p.tokenId, { at: e.timestamp, value: p.value });
+  }
+  const approvals = new Map<string, ToolApproval>();
+  for (const [waitTokenId, decided] of resumed) {
+    const invocationId = callOf.get(waitTokenId);
+    if (invocationId === undefined) continue;
+    approvals.set(invocationId, {
+      waitTokenId,
+      parkedAt: parkedAt.get(waitTokenId) ?? decided.at,
+      decidedAt: decided.at,
+      decision: readGateDecision(decided.value),
+    });
+  }
+  return approvals;
+}
+
+/** The waitpoint a tool call's gate recorded (`dispatch-tools`), if `e` is that record. */
+function toolGateOf(
+  e: JournalEntry,
+): { readonly waitTokenId: string; readonly invocationId: string } | undefined {
+  if (e.kind !== 'value.recorded') return undefined;
+  const p = (e.payload ?? {}) as Partial<ValueRecordedPayload>;
+  if (typeof p.key !== 'string' || !p.key.startsWith(TOOL_GATE_RECORD_PREFIX)) return undefined;
+  const waitTokenId = (p.value as { readonly waitTokenId?: unknown } | undefined)?.waitTokenId;
+  return typeof waitTokenId === 'string'
+    ? { waitTokenId, invocationId: p.key.slice(TOOL_GATE_RECORD_PREFIX.length) }
+    : undefined;
+}
+
+/** A completed model-call step's output, as far as provenance reads it. */
+interface ModelCallStepOutput {
+  readonly step?: number;
+  readonly callId?: string;
+  readonly finishReason?: string;
+  readonly provider?: { readonly id: string; readonly model: string };
+}
+
+/**
+ * The provenance of the steps that ran before the park, in the order
+ * they ran: the user message, the retrievals, then each model call with
+ * the tool calls its completed step stored.
+ */
+function rebuildProvenance(
+  ctx: TurnContext,
+  steps: readonly StepRecord[],
+  retrieved: readonly RetrievedFact[] | undefined,
+): void {
+  const input = ctx.userMessage;
+  if (ctx.provenance === undefined || input === undefined) return;
+  addInputNode(ctx.provenance, input);
+  if (retrieved !== undefined) addRetrievalNodes(ctx.provenance, retrieved, input);
+
+  const storedByStep = new Map<number, readonly ConversationMessage[]>();
+  for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+    const out = s.output as {
+      readonly step?: number;
+      readonly iterationAppended?: readonly ConversationMessage[];
+    };
+    if (out.step !== undefined) storedByStep.set(out.step, out.iterationAppended ?? []);
+  }
+  const calls = steps
+    .filter((s) => s.nodeId === 'model-call' && s.inLoop)
+    .map((s) => ({ at: s.at, out: s.output as ModelCallStepOutput }))
+    .sort((a, b) => (a.out.step ?? 0) - (b.out.step ?? 0));
+  for (const { at, out } of calls) {
+    const { step, callId, provider, finishReason } = out;
+    if (step === undefined || callId === undefined || provider === undefined) continue;
+    addModelCallNode(
+      ctx.provenance,
+      { step, callId, provider, finishReason: finishReason ?? 'stop', at },
+      input.sequence,
+      [...(ctx.toolResultIds ?? [])],
+    );
+    addStepToolNodes(ctx, step, storedByStep.get(step) ?? []);
+  }
+}
+
 /**
  * The messages no completed step accounts for: those the step the turn
  * parked in stored before it parked.

package/src/handlers/run-retrievals.ts

@@ -8,6 +8,7 @@ import { emitTurnEvent } from '../streaming.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
@@ -49,25 +50,7 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
     });
 
     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, retrieved.value, ctx.userMessage);
     }
 
     // The facts go in the journal: a resumed turn restores them from it

package/src/handlers/setup.ts

@@ -11,12 +11,14 @@ 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 { 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
@@ -51,16 +53,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
@@ -156,7 +148,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 +193,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 +206,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 +223,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 +232,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

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