@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/define.ts

@@ -9,6 +9,7 @@ import {
   loadZodConverterSync,
   toJSONSchemaSync,
 } from '@kindgi/schema';
+import { pickVersion } from '@kindgi/tools';
 import type { Result, Semver } from '@kindgi/types';
 
 import type { InvalidAgentError } from './errors.js';
@@ -16,8 +17,10 @@ import type {
   Agent,
   AgentId,
   AgentOutputSpec,
+  BlockRef,
   ConversationPolicy,
   PromptParameter,
+  PromptRef,
   RetrievalIntent,
   ToolRef,
   TurnBudget,
@@ -48,9 +51,10 @@ export function defineAgent(spec: DefineAgentSpec): Result<Agent, InvalidAgentEr
   const issues: Issue[] = [
     ...validateIdentity(spec),
     ...validateContent(spec),
+    ...validateBlockRefs(spec),
     ...validateArrays(spec),
     ...validateRetrieval(spec),
-    ...validateParameters(spec.parameters),
+    ...validatePromptParameters(spec.parameters),
     ...validateBudget(spec.budget),
     ...validateConversationPolicy(spec.conversationPolicy),
     ...validateToolErrors(spec.toolErrors),
@@ -126,8 +130,16 @@ export interface DefineAgentSpec {
    * The system prompt. Sent to the model with every turn as the
    * baseline instructions. Load-bearing — this is where you shape
    * the agent's behavior (persona, output format, tool-use policy).
+   *
+   * Or a prompt block by range (`{ prompt: 'acme.intake-prompt',
+   * version: '^1.0.0' }`), whose template and parameters are used
+   * instead; then `parameters` stays unset (the block declares them).
    */
-  readonly instructions: string;
+  readonly instructions: string | PromptRef;
+  /** Settings blocks the agent reads, by range (see `Agent.settings`). */
+  readonly settings?: readonly BlockRef[];
+  /** A model-settings block, by range (see `Agent.modelSettings`). */
+  readonly modelSettings?: BlockRef;
   /**
    * Required capabilities the agent needs from a `ModelProvider`.
    * Typically one entry: `[{ needs: [{ feature: 'tool-use' }] }]`
@@ -248,8 +260,19 @@ function validateIdentity(spec: DefineAgentSpec): Issue[] {
 
 function validateContent(spec: DefineAgentSpec): Issue[] {
   const out: Issue[] = [];
-  if (typeof spec.instructions !== 'string' || spec.instructions.trim().length === 0) {
-    out.push({ path: '/instructions', message: 'instructions must be a non-empty string' });
+  if (typeof spec.instructions === 'object' && spec.instructions !== null) {
+    out.push(...blockRefIssues(spec.instructions, '/instructions', 'prompt'));
+    if (spec.parameters !== undefined) {
+      out.push({
+        path: '/parameters',
+        message: 'the prompt block declares the parameters: leave parameters unset',
+      });
+    }
+  } else if (typeof spec.instructions !== 'string' || spec.instructions.trim().length === 0) {
+    out.push({
+      path: '/instructions',
+      message: 'instructions must be a non-empty string, or a prompt block { prompt, version }',
+    });
   }
   if (!Array.isArray(spec.capabilities) || spec.capabilities.length === 0) {
     out.push({
@@ -260,6 +283,56 @@ function validateContent(spec: DefineAgentSpec): Issue[] {
   return out;
 }
 
+const BLOCK_ID = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/;
+
+/** A block reference: a dotted block id and a valid semver range. */
+function blockRefIssues(ref: unknown, path: string, idKey: 'prompt' | 'id'): Issue[] {
+  if (ref === null || typeof ref !== 'object') {
+    return [{ path, message: `must be { ${idKey}, version }` }];
+  }
+  const r = ref as Record<string, unknown>;
+  const out: Issue[] = [];
+  if (typeof r[idKey] !== 'string' || !BLOCK_ID.test(r[idKey] as string)) {
+    out.push({
+      path: `${path}/${idKey}`,
+      message: 'must be a dotted lowercase block id, e.g. "acme.weights"',
+    });
+  }
+  if (typeof r.version !== 'string' || pickVersion([], r.version).kind === 'invalid-range') {
+    out.push({
+      path: `${path}/version`,
+      message: 'must be a semver range, e.g. "^1.0.0" or "1.2.0"',
+    });
+  }
+  return out;
+}
+
+/** Settings and model-settings references: valid, and each block named once. */
+function validateBlockRefs(spec: DefineAgentSpec): Issue[] {
+  const out: Issue[] = [];
+  const seen = new Set<string>();
+  const once = (id: unknown, path: string) => {
+    if (typeof id !== 'string') return;
+    if (seen.has(id)) out.push({ path, message: `settings block "${id}" is referenced twice` });
+    seen.add(id);
+  };
+  if (spec.settings !== undefined) {
+    if (!Array.isArray(spec.settings)) {
+      out.push({ path: '/settings', message: 'settings must be an array of { id, version }' });
+    } else {
+      spec.settings.forEach((ref, i) => {
+        out.push(...blockRefIssues(ref, `/settings/${i}`, 'id'));
+        once((ref as { id?: unknown }).id, `/settings/${i}/id`);
+      });
+    }
+  }
+  if (spec.modelSettings !== undefined) {
+    out.push(...blockRefIssues(spec.modelSettings, '/modelSettings', 'id'));
+    once((spec.modelSettings as { id?: unknown }).id, '/modelSettings/id');
+  }
+  return out;
+}
+
 function validateArrays(spec: DefineAgentSpec): Issue[] {
   const out: Issue[] = [];
   if (!Array.isArray(spec.tools)) {
@@ -334,9 +407,10 @@ function validateIntent(intent: RetrievalIntent, i: number): Issue[] {
 }
 
 const VALID_PARAM_TYPES = new Set(['string', 'number', 'boolean', 'date']);
-const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation']);
+const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation', 'settings']);
 
-function validateParameters(parameters?: readonly PromptParameter[]): Issue[] {
+/** An agent's or a prompt block's declared parameters: the problems, none when they're valid. */
+export function validatePromptParameters(parameters?: readonly PromptParameter[]): Issue[] {
   if (parameters === undefined) return [];
   const out: Issue[] = [];
   const seen = new Set<string>();
@@ -448,6 +522,7 @@ function validateConversationPolicy(policy?: ConversationPolicy): Issue[] {
         message: 'hitl.timeoutMs must be a positive integer (ms)',
       });
     }
+    out.push(...validateOnTimeout(h.onTimeout));
     const ROLES: ReadonlySet<string> = new Set(['standard', 'senior', 'admin']);
     if (
       h.defaultReviewerRole !== undefined &&
@@ -490,6 +565,25 @@ function validateConversationPolicy(policy?: ConversationPolicy): Issue[] {
   return out;
 }
 
+/**
+ * `hitl.onTimeout`: only `'escalate'`, what the runtime does when an
+ * approval's time runs out. `'auto-approve'` / `'auto-reject'` aren't
+ * implemented, so they're refused instead of accepted and ignored.
+ */
+function validateOnTimeout(onTimeout: unknown): Issue[] {
+  if (onTimeout === undefined || onTimeout === 'escalate') return [];
+  const path = '/conversationPolicy/hitl/onTimeout';
+  if (onTimeout === 'auto-approve' || onTimeout === 'auto-reject') {
+    return [
+      {
+        path,
+        message: `hitl.onTimeout '${onTimeout}' isn't supported: an approval that times out escalates one reviewer tier, and at admin it expires (the turn fails with hitl-cancelled). Use 'escalate', or leave it out.`,
+      },
+    ];
+  }
+  return [{ path, message: "hitl.onTimeout must be 'escalate'" }];
+}
+
 type OutputOutcome =
   | { readonly kind: 'none' }
   | { readonly kind: 'ok'; readonly value: AgentOutputSpec }
@@ -546,7 +640,10 @@ function buildAgent(spec: DefineAgentSpec, output: AgentOutputSpec | undefined):
     version: spec.version as Semver,
     name: spec.name,
     ...(spec.description !== undefined && { description: spec.description }),
-    instructions: spec.instructions,
+    instructions:
+      typeof spec.instructions === 'string' ? spec.instructions : { ...spec.instructions },
+    ...(spec.settings !== undefined && { settings: spec.settings.map((r) => ({ ...r })) }),
+    ...(spec.modelSettings !== undefined && { modelSettings: { ...spec.modelSettings } }),
     capabilities: spec.capabilities.map((c) => ({ ...c })),
     tools: [...spec.tools],
     retrieval: spec.retrieval.map((r) => ({ ...r })),

package/src/guardrails-gate.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabilities';
 import type { ComplianceProvider } from '@kindgi/compliance';
 import {
   type CheckRegistry,
@@ -15,7 +15,15 @@ import {
   type ToolResultRecord,
   evaluateAll,
 } from '@kindgi/guardrails';
-import type { AgentId, GuardrailId, ProjectId, Result, RunId, TenantId } from '@kindgi/types';
+import type {
+  AgentId,
+  GuardrailId,
+  OrgId,
+  ProjectId,
+  Result,
+  RunId,
+  TenantId,
+} from '@kindgi/types';
 
 import type { Agent, ConversationId, ConversationMessage } from './types.js';
 
@@ -66,6 +74,8 @@ export function buildRunTrace(input: {
   readonly tenantId: TenantId;
   /** Lets the engine record compliance evidence for a failed check. */
   readonly projectId: ProjectId;
+  /** The project's org, when it has one. */
+  readonly orgId?: OrgId;
   readonly conversationId: ConversationId;
   /** 1-based number of this turn in the conversation. */
   readonly turnNumber: number;
@@ -133,6 +143,7 @@ export function buildRunTrace(input: {
     runId: input.runId,
     tenantId: input.tenantId,
     projectId: input.projectId,
+    ...(input.orgId !== undefined && { orgId: input.orgId }),
     agentId: input.agent.id as unknown as AgentId,
     output,
     toolCalls,
@@ -179,7 +190,8 @@ export function resolveGuardrails(
  * doesn't halt on its own. `tenantPolicy` (the policy the turn was
  * routed under) also governs which models llm-judge guardrails may use;
  * `abortSignal` (the turn's) reaches every check, so a slow judge or
- * pack check stops when the turn does.
+ * pack check stops when the turn does. `usage` (the turn's sink) records
+ * every llm-judge call, as the turn's own model calls are.
  */
 export async function evaluateGate(
   guardrails: readonly Guardrail[],
@@ -187,6 +199,7 @@ export async function evaluateGate(
   bindings: GuardrailsBindings,
   tenantPolicy?: TenantPolicy,
   abortSignal?: AbortSignal,
+  usage?: UsageSink,
 ): Promise<readonly EvaluationOutcome[]> {
   if (guardrails.length === 0 || bindings.checks === undefined) return [];
   const evalBindings: EvaluationBindings = {
@@ -194,6 +207,7 @@ export async function evaluateGate(
     ...(bindings.compliance !== undefined && { compliance: bindings.compliance }),
     ...(tenantPolicy !== undefined && { tenantPolicy }),
     ...(abortSignal !== undefined && { abortSignal }),
+    ...(usage !== undefined && { usage }),
   };
   return await evaluateAll(guardrails, bindings.checks, trace, evalBindings);
 }

package/src/handlers/compose-result.ts

@@ -8,6 +8,7 @@ import type { AgentTurnResult, AgentTurnUsage } from './result-shape.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { replayReport } from './replay.js';
 import { parseJsonAnswer } from './structured-output.js';
 
 /** The final answer as JSON — `budget-check` already validated it against the schema. */
@@ -45,6 +46,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       model: ctx.model?.name ?? 'unknown',
     };
 
+    const replay = replayReport(ctx);
     const result: AgentTurnResult = {
       runId: kctx.runId,
       conversationId: ctx.input.conversationId,
@@ -70,6 +72,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       }),
       ...(ctx.persistedProvenance !== undefined && { provenance: ctx.persistedProvenance }),
       ...(kctx.dryRun && { dryRun: true }),
+      ...(replay !== undefined && { replay }),
     };
 
     await emitTurnEvent(ctx.bindings.onEvent, {

package/src/handlers/context.ts

@@ -19,6 +19,7 @@ import type { ProvenanceBindings } from '../provenance-emit.js';
 import type { Agent, Conversation, ConversationMessage, RetrievedFact } from '../types.js';
 
 import type { HitlBindings, InvokeAgentBindings, InvokeAgentInput } from './public-types.js';
+import type { TurnBlocks } from './resolve-blocks.js';
 import type { ToolErrorPolicy } from './tool-errors.js';
 
 /**
@@ -53,6 +54,8 @@ export interface TurnContext {
    * Populated by `setup` — resolved tools (per-name map + model
    * definitions).
    */
+  /** The data blocks the turn runs with (set by setup; none when the agent references none). */
+  blocks?: TurnBlocks;
   tools?: {
     readonly definitions: readonly ModelToolDefinition[];
     /**
@@ -143,6 +146,20 @@ export interface TurnContext {
    * Present only when the builder was wired AND persistence succeeded.
    */
   persistedProvenance?: import('@kindgi/provenance').Provenance;
+  /**
+   * This turn's tool results so far, by invocation id: a model call read
+   * them all (they're in its input), so its provenance node is
+   * `influenced-by` each. Filled by `dispatch-tools`, and by the rebuild
+   * of a resumed turn.
+   */
+  toolResultIds?: string[];
+  /**
+   * The tool-call approvals this turn's journal shows decided, by
+   * invocation id: each call's provenance shows the approval it waited on.
+   * Populated by `rehydrateTurnContext` (a decision only reaches a turn
+   * that parked, and resumes).
+   */
+  toolApprovals?: ReadonlyMap<string, import('./turn-provenance.js').ToolApproval>;
   /**
    * The tenant policy this turn's model was routed under (bound policy
    * merged with the policy registry's). Populated by `setup`; guardrail
@@ -175,6 +192,13 @@ export interface TurnContext {
    * `AgentTurnResult.violations`.
    */
   nonBlockingViolations?: readonly EvaluationResult[];
+  /**
+   * A replay turn's tool calls so far, and what happened to each
+   * (`decideReplayTool`). Rebuilt from the journal on resume.
+   */
+  replayTrace?: import('./replay.js').ReplayToolTrace[];
+  /** A replay turn's session approval, when it reached the gate (`replaySessionApproval`). */
+  replayApproval?: 'followed' | 'skipped';
   /**
    * Reason recorded when `turnAbort` fires. Used to distinguish
    * external cancellation from wall-clock timeout in the projected

package/src/handlers/dispatch-tools.ts

@@ -19,13 +19,16 @@ import {
   type UnresolvedToolError,
   throwAgentTurnFailure,
 } from './errors.js';
+import { TOOL_CALL_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
+import { decideReplayTool } from './replay.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
@@ -111,7 +114,7 @@ async function decideToolGate(
       cause: null,
     });
   }
-  return kctx.record(`tool-hitl-gate:${call.id}`, (): ToolGateRecord | undefined => {
+  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);
@@ -242,6 +245,50 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
       // skip the reviewer's answer. Cross-turn `ask_on_first_use` caching
       // (via conversation metadata) is not implemented.
       const gate = await decideToolGate(ctx, kctx, call, tool);
+
+      // A replay turn decides the call first: a recorded or refused call
+      // runs nothing, so it asks for no approval either.
+      const replayed =
+        ctx.input.replay === undefined
+          ? undefined
+          : await decideReplayTool(ctx, kctx, {
+              step: partial.step,
+              callId: call.id,
+              tool,
+              version: resolvedVersion,
+              arguments: call.arguments,
+              gated: gate !== undefined,
+            });
+      if (replayed !== undefined && replayed.kind !== 'live') {
+        const replayStarted = Date.now();
+        await emitTurnEvent(ctx.bindings.onEvent, {
+          kind: 'tool.started',
+          step: partial.step,
+          toolId: call.name,
+          toolVersion: resolvedVersion,
+          toolVersionRange: requestedRange,
+          invocationId: call.id,
+          arguments: call.arguments,
+        });
+        nextMessages = await appendToolResult(ctx, call, replayed.result, {
+          toolId: tool.id as unknown as string,
+          nextMessages,
+          iterationAppended,
+        });
+        await emitTurnEvent(ctx.bindings.onEvent, {
+          kind: 'tool.completed',
+          step: partial.step,
+          toolId: call.name,
+          toolVersion: resolvedVersion,
+          toolVersionRange: requestedRange,
+          invocationId: call.id,
+          output: replayed.result as never,
+          durationMs: Date.now() - replayStarted,
+          replay: replayed.kind,
+        });
+        continue;
+      }
+
       let toolRejectionPayload: { readonly rationale?: string } | null = null;
       if (gate !== undefined) {
         const { argsHash, waitTokenId, timeoutMs } = gate;
@@ -251,7 +298,8 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
           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,
@@ -275,14 +323,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({
@@ -371,44 +421,15 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         invocationId: call.id,
         output: dispatched.value.persisted.content,
         durationMs: Date.now() - toolStarted,
+        ...(replayed !== undefined && { replay: replayed.kind }),
       });
-
-      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;
@@ -520,7 +541,12 @@ async function appendToolResult(
   target.iterationAppended.push(persisted.value);
   return [
     ...target.nextMessages,
-    { role: 'tool', content: JSON.stringify(output), toolCallId: call.id },
+    {
+      role: 'tool',
+      // As a tool's own result reaches the model: a string as it is.
+      content: typeof output === 'string' ? output : JSON.stringify(output),
+      toolCallId: call.id,
+    },
   ];
 }
 
@@ -573,12 +599,17 @@ 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
     // secret_refs at invoke time. Present iff the caller wired
     // `bindings.resolveSecret` from a tenant-scoped `SecretBinding`.
     ...(ctx.bindings.resolveSecret !== undefined && { resolveSecret: ctx.bindings.resolveSecret }),
+    // The pinned settings blocks' values, by block id.
+    ...(ctx.blocks !== undefined && { settings: ctx.blocks.settings }),
   };
   const result = await invokeTool(tool, call.arguments, toolCtx);
   if (result.kind === 'err') {

package/src/handlers/errors.ts

@@ -16,6 +16,7 @@ export type InvokeAgentError =
   | AgentError
   | UnresolvedToolError
   | ToolVersionUnresolvableError
+  | BlockUnresolvableError
   | CapabilityRoutingError
   | ModelInvocationError
   | ToolInvocationError
@@ -75,6 +76,18 @@ export interface ToolVersionUnresolvableError {
   readonly availableVersions?: readonly string[];
 }
 
+/**
+ * A data block the agent references can't be loaded: no version in its
+ * range, a pinned version that's gone, the wrong kind, model settings
+ * that aren't, or a runtime that serves no blocks.
+ */
+export interface BlockUnresolvableError {
+  readonly code: 'block-unresolvable';
+  readonly message: string;
+  readonly blockId: string;
+  readonly requestedRange?: string;
+}
+
 export interface CapabilityRoutingError {
   readonly code: 'capability-routing-failed';
   readonly message: string;

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 {
@@ -16,6 +18,7 @@ import type { ConversationMessage } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { finalIteration } from './final-iteration.js';
+import { replayTag } from './replay.js';
 import { parseJsonAnswer } from './structured-output.js';
 
 /**
@@ -77,6 +80,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 +97,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 +157,37 @@ 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,
+        ...(ctx.input.replay !== undefined && { replay: replayTag(ctx.input.replay) }),
+        ...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,
+      });
+    }
+  }
+}