@kindgi/agents 0.1.1 → 0.1.3

package/src/handlers/dispatch-tools.ts

@@ -19,13 +19,15 @@ import {
   type UnresolvedToolError,
   throwAgentTurnFailure,
 } from './errors.js';
+import { TOOL_CALL_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
 import {
   effectiveToolErrorPolicy,
   toolErrorKindOf,
   toolErrorResult,
   toolRetriesSoFar,
 } from './tool-errors.js';
-import { type ToolHitlDecision, computeToolCallWaitToken, hashToolArgs } from './tool-hitl.js';
+import { TOOL_GATE_RECORD_PREFIX, computeToolCallWaitToken, hashToolArgs } from './tool-hitl.js';
+import { addStepToolNodes } from './turn-provenance.js';
 
 /**
  * Resolves the effective HITL mode + reviewer role for a specific
@@ -79,6 +81,55 @@ function agentToolHitl(
   return { mode, requiredRole: defaultRole };
 }
 
+/**
+ * A tool call's gate, as the step records it the first time the gate asks
+ * for a review: the wait it parks on, and the review it asks for.
+ */
+interface ToolGateRecord {
+  readonly argsHash: string;
+  readonly waitTokenId: string;
+  readonly requiredRole: 'standard' | 'senior' | 'admin';
+  readonly timeoutMs: number;
+}
+
+/**
+ * Whether `call` waits for a review, decided once (`NodeContext.record`):
+ * a step resumed after the park reads the gate it parked on back, so a
+ * policy relaxed meanwhile can't skip the reviewer's answer. A call the
+ * gate lets through isn't recorded: it runs, and its stored result is
+ * reused after a park further down the list.
+ */
+async function decideToolGate(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  call: ModelToolCall,
+  tool: Tool,
+): Promise<ToolGateRecord | undefined> {
+  const effectiveHitl = ctx.hitlPolicy;
+  if (effectiveHitl === undefined) {
+    throwAgentTurnFailure({
+      code: 'model-invocation-failed',
+      message: 'dispatch-tools invoked before the turn resolved its approval rules',
+      cause: null,
+    });
+  }
+  return kctx.record(`${TOOL_GATE_RECORD_PREFIX}${call.id}`, (): ToolGateRecord | undefined => {
+    const resolved = resolveEffectiveToolHitl(effectiveHitl, tool);
+    if (resolved.mode === 'never_ask') return undefined;
+    const argsHash = hashToolArgs(call.arguments);
+    return {
+      argsHash,
+      waitTokenId: computeToolCallWaitToken({
+        runId: kctx.runId as unknown as string,
+        callId: call.id,
+        argsHash,
+      }),
+      requiredRole: resolved.requiredRole,
+      timeoutMs: effectiveHitl.timeoutMs,
+    };
+  });
+}
+
 /**
  * Loop-body node #2. If the model returned `finishReason='tool-use'`
  * with a non-empty tool-call list, persist the assistant tool-call
@@ -188,33 +239,22 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
       //
       // Kernel replay: within one run, waitForToken with the same
       // deterministic tokenId returns the resolved decision from the
-      // journal — no re-park. Cross-turn `ask_on_first_use` caching
+      // journal — no re-park. The gate itself is decided once
+      // (`decideToolGate`), so a policy changed during the park can't
+      // skip the reviewer's answer. Cross-turn `ask_on_first_use` caching
       // (via conversation metadata) is not implemented.
-      const effectiveHitl = ctx.hitlPolicy;
-      if (effectiveHitl === undefined) {
-        throwAgentTurnFailure({
-          code: 'model-invocation-failed',
-          message: 'dispatch-tools invoked before the turn resolved its approval rules',
-          cause: null,
-        });
-      }
-      const resolvedHitl = resolveEffectiveToolHitl(effectiveHitl, tool);
+      const gate = await decideToolGate(ctx, kctx, call, tool);
       let toolRejectionPayload: { readonly rationale?: string } | null = null;
-      if (resolvedHitl.mode !== 'never_ask') {
-        const argsHash = hashToolArgs(call.arguments);
-        const waitTokenId = computeToolCallWaitToken({
-          runId: kctx.runId as unknown as string,
-          callId: call.id,
-          argsHash,
-        });
-        const timeoutMs = effectiveHitl.timeoutMs;
+      if (gate !== undefined) {
+        const { argsHash, waitTokenId, timeoutMs } = gate;
         const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
 
         if (ctx.bindings.hitl?.enqueue !== undefined) {
           try {
             await ctx.bindings.hitl.enqueue({
               tenantId: ctx.input.tenantId,
-              subjectKind: 'tool-call:pending',
+              projectId: ctx.input.projectId,
+              subjectKind: TOOL_CALL_GATE_SUBJECT,
               subjectRef: {
                 conversationId: ctx.input.conversationId,
                 agentId: ctx.input.agent.id,
@@ -225,7 +265,7 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
                 argsHash,
                 arguments: call.arguments as never,
               },
-              requiredRole: resolvedHitl.requiredRole,
+              requiredRole: gate.requiredRole,
               title: `HITL review: ${call.name}`,
               description: `Tool call ${call.name} awaiting reviewer approval before dispatch.`,
               waitTokenId,
@@ -238,14 +278,16 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         }
 
         try {
-          const decision = await kctx.waitForToken<ToolHitlDecision>(waitTokenId, {
-            timeoutMs,
-          });
-          if (decision.decided === 'reject') {
+          // Fails closed: only an explicit approve runs the tool. A reject,
+          // or an answer that isn't a decision at all, gives the model a
+          // rejected result instead.
+          const decision = readGateDecision(
+            await kctx.waitForToken<unknown>(waitTokenId, { timeoutMs }),
+          );
+          if (!decision.approved) {
             toolRejectionPayload =
               decision.rationale !== undefined ? { rationale: decision.rationale } : {};
           }
-          // approve → fall through to dispatch
         } catch (cause) {
           if (cause instanceof WaitpointCancelledError) {
             throwAgentTurnFailure({
@@ -335,43 +377,13 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         output: dispatched.value.persisted.content,
         durationMs: Date.now() - toolStarted,
       });
-
-      if (ctx.provenance !== undefined) {
-        const modelCallNodeId = `model-call:${partial.step}`;
-        const toolCallNodeId = `tool-call:${call.id}`;
-        const toolResultNodeId = `tool-result:${call.id}`;
-        ctx.provenance.addNode({
-          id: toolCallNodeId,
-          kind: 'tool-call',
-          timestamp: dispatched.value.persisted.createdAt,
-          attributes: {
-            toolId: call.name,
-            invocationId: call.id,
-            // Capture the exact version the
-            // registry picked at run start + the range the agent asked
-            // for, so a replay can pin against the same version.
-            toolVersion: resolvedVersion,
-            toolVersionRange: requestedRange,
-          },
-        });
-        ctx.provenance.addNode({
-          id: toolResultNodeId,
-          kind: 'tool-result',
-          timestamp: dispatched.value.persisted.createdAt,
-        });
-        ctx.provenance.addEdge({
-          from: toolCallNodeId,
-          to: modelCallNodeId,
-          kind: 'invoked',
-        });
-        ctx.provenance.addEdge({
-          from: toolResultNodeId,
-          to: toolCallNodeId,
-          kind: 'produced',
-        });
-      }
     }
 
+    // Every call's nodes, once the step has all its results: the ones it
+    // ran, the rejected and failed ones, and those it took from before a
+    // park in this step.
+    addStepToolNodes(ctx, partial.step, iterationAppended);
+
     const forwarded: Partial<AgentTurnIterationOutput> & {
       readonly step: number;
       readonly hasToolCalls: true;
@@ -536,6 +548,9 @@ async function dispatchOne(
   const toolCtx: ToolContext = {
     tenantId: ctx.input.tenantId,
     runId,
+    // The run's own project and org, never the model's arguments.
+    projectId: ctx.input.projectId,
+    ...(ctx.input.orgId !== undefined && { orgId: ctx.input.orgId }),
     requestId: call.id,
     abortSignal: ctx.turnAbort.signal,
     // HTTP tools built via defineTool({spec: {kind: 'http'}}) resolve declared

package/src/handlers/errors.ts

@@ -25,7 +25,19 @@ export type InvokeAgentError =
   | GuardrailViolationError
   | UnresolvedGuardrailError
   | OutputSchemaViolationError
-  | TenantPolicyUnavailableError;
+  | TenantPolicyUnavailableError
+  | RunSnapshotError;
+
+/**
+ * A turn being resumed can't be rebuilt from its snapshot:
+ * `run-snapshot-missing`, there is none (its write failed), so it can't
+ * be resumed; `run-snapshot-unreadable`, reading it failed (a passing
+ * storage error), so resuming again may work.
+ */
+export interface RunSnapshotError {
+  readonly code: 'run-snapshot-missing' | 'run-snapshot-unreadable';
+  readonly message: string;
+}
 
 /**
  * A tenant policy the turn must apply couldn't be: its spec doesn't

package/src/handlers/evaluate-guardrails.ts

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { NodeHandler } from '@kindgi/handler';
+import type { UsageSink } from '@kindgi/capabilities';
+import type { EvaluationOutcome } from '@kindgi/guardrails';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
 import type { Timestamp } from '@kindgi/types';
 
 import {
@@ -77,6 +79,7 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       runId: kctx.runId,
       tenantId: ctx.input.tenantId,
       projectId: ctx.input.projectId,
+      ...(ctx.input.orgId !== undefined && { orgId: ctx.input.orgId }),
       conversationId: ctx.input.conversationId,
       turnNumber: (ctx.conversation?.turnCount ?? 0) + 1,
       agent: ctx.input.agent,
@@ -93,7 +96,9 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       ctx.bindings,
       ctx.tenantPolicy,
       ctx.turnAbort.signal,
+      judgeUsageSink(ctx, kctx),
     );
+    throwIfJudgeCallsUnrecorded(outcomes);
     const categorized = categorizeOutcomes(outcomes);
 
     const allViolations = [...categorized.blocking, ...categorized.warnings, ...categorized.other];
@@ -151,3 +156,36 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
     };
   };
 }
+
+/**
+ * The turn's usage sink for its llm-judge calls, adding what only the
+ * turn knows: the step that made them and the agent's version.
+ */
+function judgeUsageSink(ctx: TurnContext, kctx: NodeContext): UsageSink | undefined {
+  const sink = ctx.bindings.usage;
+  if (sink === undefined) return undefined;
+  return {
+    record: (call) =>
+      sink.record({
+        nodeId: kctx.nodeId as unknown as string,
+        agentVersion: ctx.input.agent.version,
+        ...call,
+      }),
+  };
+}
+
+/**
+ * A judge call that answered but couldn't be recorded fails the step, as
+ * the turn's own model calls do: no answered call is left unrecorded.
+ */
+function throwIfJudgeCallsUnrecorded(outcomes: readonly EvaluationOutcome[]): void {
+  for (const outcome of outcomes) {
+    if (outcome.kind === 'err' && outcome.error.code === 'judge-usage-unrecorded') {
+      throwAgentTurnFailure({
+        code: 'persistence-error',
+        message: outcome.error.message,
+        cause: outcome.error,
+      });
+    }
+  }
+}

package/src/handlers/gate-decision.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The reviewer's answer at an agent turn's approval gates: the tool-call
+ * gate (`dispatch-tools`) and the session gate (`setup`). A gate parks the
+ * turn on a waitpoint; the approvals route resumes it with the decision
+ * (`GateDecisionValue`): approve or reject, the reviewer's rationale, and
+ * who decided which approval.
+ *
+ * A gate fails closed. Only an explicit approve lets the tool run (or the
+ * session go on). Anything else blocks: a reject, and also a resume value
+ * that isn't a decision at all (a `value` that replaced it, a malformed
+ * payload), so no answer can be read as consent by omission.
+ */
+
+/** The approval subject an agent's tool-call gate parks on. */
+export const TOOL_CALL_GATE_SUBJECT = 'tool-call:pending';
+
+/** The approval subject an agent's session gate (`afterTurns`) parks on. */
+export const SESSION_GATE_SUBJECT = 'agent-turn:session-hitl-gate';
+
+/**
+ * The approval subjects an agent turn parks on. Their resume value is the
+ * reviewer's decision and nothing else, so the approvals route takes no
+ * `value` for them.
+ */
+export const AGENT_GATE_SUBJECTS: ReadonlySet<string> = new Set([
+  TOOL_CALL_GATE_SUBJECT,
+  SESSION_GATE_SUBJECT,
+]);
+
+/**
+ * A gate's resume value: the reviewer's decision, as the approvals route
+ * (and the runtime, delivering a decision whose delivery was lost) completes
+ * the gate's waitpoint with it. The run's journal keeps it as it came.
+ */
+export interface GateDecisionValue {
+  readonly decided: 'approve' | 'reject';
+  readonly rationale?: string;
+  /**
+   * Who decided, as an actor: `user:<userId>`, the reviewer's user. Absent
+   * from values written before it was recorded.
+   */
+  readonly decidedBy?: string;
+  /** The approval decided. Absent from values written before it was recorded. */
+  readonly approvalId?: string;
+}
+
+/** Who decided a gate, and which approval, when its value says. */
+interface GateDecider {
+  readonly decidedBy?: string;
+  readonly approvalId?: string;
+}
+
+/** What a gate's resume value decides. */
+export type GateDecision = GateDecider &
+  (
+    | { readonly approved: true }
+    | {
+        readonly approved: false;
+        /** `rejected`: the reviewer said no. `unreadable`: the answer wasn't a decision. */
+        readonly reason: 'rejected' | 'unreadable';
+        /** The reviewer's rationale, or why an unreadable answer blocks. */
+        readonly rationale: string | undefined;
+      }
+  );
+
+/** Why a gate blocks on an answer that isn't a decision. */
+export const UNREADABLE_DECISION =
+  "the approval's answer wasn't a decision (approve or reject), so it counts as a rejection";
+
+/**
+ * The decision in a gate's resume value. Fails closed: only
+ * `{ decided: 'approve' }` approves.
+ */
+export function readGateDecision(value: unknown): GateDecision {
+  if (typeof value !== 'object' || value === null) {
+    return { approved: false, reason: 'unreadable', rationale: UNREADABLE_DECISION };
+  }
+  const { decided, rationale, decidedBy, approvalId } = value as {
+    decided?: unknown;
+    rationale?: unknown;
+    decidedBy?: unknown;
+    approvalId?: unknown;
+  };
+  const decider: GateDecider = {
+    ...(typeof decidedBy === 'string' && { decidedBy }),
+    ...(typeof approvalId === 'string' && { approvalId }),
+  };
+  if (decided === 'approve') return { approved: true, ...decider };
+  if (decided === 'reject') {
+    return {
+      approved: false,
+      reason: 'rejected',
+      rationale: typeof rationale === 'string' ? rationale : undefined,
+      ...decider,
+    };
+  }
+  return { approved: false, reason: 'unreadable', rationale: UNREADABLE_DECISION };
+}

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 };
   };