@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/handlers/rehydrate.ts

@@ -10,7 +10,9 @@
  *
  *   - the environment — conversation, approval rules, guardrails, tools,
  *     policies — is resolved again, routed to the provider and model
- *     `setup` journaled;
+ *     `setup` journaled, with the tool versions it journaled (a range
+ *     isn't resolved again: a version published meanwhile doesn't run
+ *     mid-turn);
  *   - the messages the turn stored come back from the conversation, from
  *     the turn's user message (`persist-user-message` journals its
  *     sequence);
@@ -27,26 +29,47 @@
  * 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 { rehydrateReplay } from './replay.js';
+import type { PinnedBlockVersions } from './resolve-blocks.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 +90,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()];
@@ -87,10 +111,12 @@ export async function rehydrateTurnContext(
   journal: readonly JournalEntry[],
 ): Promise<boolean> {
   const steps = completedSteps(journal);
-  const setup = outputOf<{ readonly providerId: string; readonly providerModel: string }>(
-    steps,
-    'setup',
-  );
+  const setup = outputOf<{
+    readonly providerId: string;
+    readonly providerModel: string;
+    readonly toolVersions?: Readonly<Record<string, string>>;
+    readonly blockVersions?: PinnedBlockVersions;
+  }>(steps, 'setup');
   if (setup === undefined) return false;
 
   if (ctx.bindings.provenance?.newBuilder !== undefined) {
@@ -99,7 +125,15 @@ export async function rehydrateTurnContext(
   }
   await loadTurnConversation(ctx);
   ctx.hitlPolicy = await resolveTurnHitlPolicy(ctx);
-  await resolveTurnEnvironment(ctx, { providerId: setup.providerId, model: setup.providerModel });
+  // The route and the tool versions `setup` resolved: a resumed turn
+  // runs those, never a range resolved again (a journal from before
+  // `toolVersions` was recorded resolves the ranges, as it did).
+  await resolveTurnEnvironment(
+    ctx,
+    { providerId: setup.providerId, model: setup.providerModel },
+    setup.toolVersions,
+    setup.blockVersions,
+  );
 
   const userMessage = outputOf<{ readonly sequence: number }>(steps, 'persist-user-message');
   if (userMessage !== undefined) {
@@ -129,9 +163,107 @@ 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);
+  rehydrateReplay(ctx, journal);
   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/render-prompt.ts

@@ -25,14 +25,20 @@ export function buildRenderPromptHandler(ctx: TurnContext): NodeHandler {
         cause: null,
       });
     }
-    const rendered = renderInstructions(ctx.input.agent, {
-      parameters: ctx.input.parameters ?? {},
-      ...(ctx.input.input !== undefined && { input: ctx.input.input }),
-      conversation: {
-        id: ctx.input.conversationId,
-        turn: ctx.conversation.turnCount + 1,
+    const rendered = renderInstructions(
+      ctx.input.agent,
+      {
+        parameters: ctx.input.parameters ?? {},
+        ...(ctx.input.input !== undefined && { input: ctx.input.input }),
+        conversation: {
+          id: ctx.input.conversationId,
+          turn: ctx.conversation.turnCount + 1,
+        },
+        ...(ctx.blocks !== undefined && { settings: ctx.blocks.settings }),
       },
-    });
+      // The pinned prompt block, when the instructions come from one.
+      ctx.blocks?.prompt?.content,
+    );
     if (!rendered.ok) {
       throwAgentTurnFailure({
         code: 'model-invocation-failed',

package/src/handlers/replay.ts

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Replay turns: an eval run re-running a past run (`InvokeAgentInput.replay`)
+ * on an agent version, without doing anything the past run didn't already
+ * do. Each tool call is decided by the deployment's `ReplayBinding`:
+ *
+ *   - `live`: the tool runs. Only a tool declared read-only (see
+ *     `isReadOnlyTool`) with no approval to wait for can; a `live`
+ *     decision for any other is refused here, whatever the binding says;
+ *   - `recorded`: the past run's result for the same call is used;
+ *   - `refused`: the tool doesn't run, and the model gets the given result.
+ *
+ * A turn marked as a replay with no binding refuses every call. Each
+ * decision is journaled (`NodeContext.record`), so a resumed turn keeps
+ * the decisions it made, and the turn's result lists them
+ * (`AgentTurnResult.replay`).
+ */
+
+import type { NodeContext } from '@kindgi/handler';
+import type { RunReplayRef } from '@kindgi/runtime';
+import type { JournalEntry, ValueRecordedPayload } from '@kindgi/runtime';
+import type { Tool } from '@kindgi/tools';
+import type { RunId, TenantId } from '@kindgi/types';
+
+import type { RetrievedFact } from '../types.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/** The replay turn a `ReplayBinding` is asked about. */
+export interface ReplayTurnRef {
+  readonly tenantId: TenantId;
+  /** The replay turn's own run. */
+  readonly runId: RunId;
+  readonly replay: RunReplayRef;
+}
+
+export interface ReplayToolInput extends ReplayTurnRef {
+  readonly tool: {
+    readonly id: string;
+    readonly version: string;
+    /** As the tool declares it; absent means it changes things. */
+    readonly mutating?: boolean;
+    readonly effects?: readonly string[];
+  };
+  readonly arguments: unknown;
+  /** The model's id for the call. */
+  readonly callId: string;
+  /** `true` when the tool's approval rules would ask for a review before it runs. */
+  readonly gated: boolean;
+}
+
+export type ReplayToolDecision =
+  | { readonly kind: 'live' }
+  | { readonly kind: 'recorded'; readonly result: unknown }
+  | { readonly kind: 'refused'; readonly result: unknown; readonly reason: string };
+
+/** An approval decision the past run recorded. */
+export interface ReplayApproval {
+  readonly approved: boolean;
+  readonly rationale?: string;
+}
+
+/**
+ * How a deployment replays turns. Consulted only for a turn marked as a
+ * replay (`InvokeAgentInput.replay`).
+ */
+export interface ReplayBinding {
+  /** Decide one tool call. */
+  decideTool(input: ReplayToolInput): Promise<ReplayToolDecision>;
+  /**
+   * What the turn's retrievals return: the past run's, or `undefined` to
+   * retrieve live. Absent: retrieve live.
+   */
+  retrievals?(input: ReplayTurnRef): Promise<readonly RetrievedFact[] | undefined>;
+  /**
+   * The past run's decision at the session approval gate, when the replay
+   * reaches that gate: the replay follows it. `undefined` (or absent): the
+   * gate is skipped, and the result says so.
+   */
+  sessionApproval?(input: ReplayTurnRef): Promise<ReplayApproval | undefined>;
+}
+
+/** One tool call of a replay turn, and what happened to it. */
+export interface ReplayToolTrace {
+  readonly step: number;
+  readonly callId: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+  readonly arguments: unknown;
+  readonly source: 'live' | 'recorded' | 'refused';
+  /** Why it was refused. A refused call is what the turn would have done. */
+  readonly reason?: string;
+}
+
+/** What a replay turn did differently from a live one (`AgentTurnResult.replay`). */
+export interface ReplayTurnReport extends RunReplayRef {
+  readonly tools: readonly ReplayToolTrace[];
+  /**
+   * The session approval gate, when the replay reached it: `followed` the
+   * past run's recorded decision, or `skipped` (none was recorded).
+   */
+  readonly approval?: 'followed' | 'skipped';
+}
+
+/** The `record` key of a replay's tool decision, per call. */
+export const REPLAY_TOOL_RECORD_PREFIX = 'replay-tool:';
+/** The `record` key of a replay's session approval. */
+export const REPLAY_APPROVAL_RECORD = 'replay-session-approval';
+
+/** Effects a read-only tool can't declare. */
+const CHANGING_EFFECTS: ReadonlySet<string> = new Set([
+  'writes',
+  'deletes',
+  'spawns-run',
+  'emits-event',
+  'external-side-effect',
+]);
+
+/** A tool that declares it changes nothing: `mutating: false`, and no changing effect. */
+export function isReadOnlyTool(tool: {
+  readonly mutating?: boolean;
+  readonly effects?: readonly { readonly kind: string }[] | readonly string[];
+}): boolean {
+  if (tool.mutating !== false) return false;
+  return !(tool.effects ?? []).some((e) =>
+    CHANGING_EFFECTS.has(typeof e === 'string' ? e : e.kind),
+  );
+}
+
+/** What the model gets for a call a replay refuses because nothing decided it. */
+const NO_BINDING_REASON = 'replay: no replay binding is wired, so no tool runs';
+const CHANGES_REASON = 'replay: this call changes things and has no recorded result';
+const GATED_REASON = 'replay: this call needs an approval and has no recorded result';
+
+function refusedResult(reason: string): Readonly<Record<string, unknown>> {
+  return { status: 'not-executed', reason };
+}
+
+/** The journaled decision of one call: its trace entry, and the result the model got. */
+interface RecordedDecision extends ReplayToolTrace {
+  readonly result?: unknown;
+}
+
+/**
+ * Decide one tool call of a replay turn, once: the binding's decision,
+ * held to `isReadOnlyTool`, journaled, and added to the turn's trace.
+ */
+export async function decideReplayTool(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  call: {
+    readonly step: number;
+    readonly callId: string;
+    readonly tool: Tool;
+    readonly version: string;
+    readonly arguments: unknown;
+    readonly gated: boolean;
+  },
+): Promise<ReplayToolDecision> {
+  const replay = ctx.input.replay;
+  if (replay === undefined) return { kind: 'live' };
+  const base = {
+    step: call.step,
+    callId: call.callId,
+    toolId: call.tool.id as unknown as string,
+    toolVersion: call.version,
+    arguments: call.arguments,
+  };
+  const refuse = (reason: string): RecordedDecision => ({
+    ...base,
+    source: 'refused',
+    reason,
+    result: refusedResult(reason),
+  });
+  const decided = await kctx.record(
+    `${REPLAY_TOOL_RECORD_PREFIX}${call.callId}`,
+    async (): Promise<RecordedDecision> => {
+      const binding = ctx.bindings.replay;
+      if (binding === undefined) return refuse(NO_BINDING_REASON);
+      const decision = await binding.decideTool({
+        tenantId: ctx.input.tenantId,
+        runId: kctx.runId,
+        replay,
+        tool: {
+          id: base.toolId,
+          version: call.version,
+          ...(call.tool.mutating !== undefined && { mutating: call.tool.mutating }),
+          ...(call.tool.effects !== undefined && {
+            effects: call.tool.effects.map((e) => e.kind),
+          }),
+        },
+        arguments: call.arguments,
+        callId: call.callId,
+        gated: call.gated,
+      });
+      if (decision.kind === 'recorded') {
+        return { ...base, source: 'recorded', result: decision.result };
+      }
+      if (decision.kind === 'refused') {
+        return { ...base, source: 'refused', reason: decision.reason, result: decision.result };
+      }
+      // `live` runs only a read-only tool, and never waits for an approval.
+      if (!isReadOnlyTool(call.tool)) return refuse(CHANGES_REASON);
+      if (call.gated) return refuse(GATED_REASON);
+      return { ...base, source: 'live' };
+    },
+  );
+  addReplayTrace(ctx, traceOf(decided));
+  if (decided.source === 'live') return { kind: 'live' };
+  if (decided.source === 'recorded') return { kind: 'recorded', result: decided.result };
+  return { kind: 'refused', result: decided.result, reason: decided.reason ?? CHANGES_REASON };
+}
+
+/** A journaled decision's trace entry (without the result). */
+function traceOf(decided: RecordedDecision): ReplayToolTrace {
+  const { result: _result, ...trace } = decided;
+  return trace;
+}
+
+function addReplayTrace(ctx: TurnContext, entry: ReplayToolTrace): void {
+  const trace = ctx.replayTrace ?? [];
+  ctx.replayTrace = trace;
+  // A step run again after a resume decides its calls again (from the journal).
+  if (trace.some((t) => t.callId === entry.callId)) return;
+  trace.push(entry);
+}
+
+/** The session approval a replay follows, decided once: the past run's, or none. */
+export async function replaySessionApproval(
+  ctx: TurnContext,
+  kctx: NodeContext,
+): Promise<ReplayApproval | undefined> {
+  const replay = ctx.input.replay;
+  if (replay === undefined) return undefined;
+  const recorded = await kctx.record(
+    REPLAY_APPROVAL_RECORD,
+    async (): Promise<{ readonly approval: ReplayApproval | null }> => {
+      const approval = await ctx.bindings.replay?.sessionApproval?.({
+        tenantId: ctx.input.tenantId,
+        runId: kctx.runId,
+        replay,
+      });
+      return { approval: approval ?? null };
+    },
+  );
+  ctx.replayApproval = recorded.approval === null ? 'skipped' : 'followed';
+  return recorded.approval ?? undefined;
+}
+
+/**
+ * A replay at the session approval gate: it goes on when the past run's
+ * reviewer approved (or none was recorded), and fails as the past run did
+ * (`hitl-rejected`) when they rejected.
+ */
+export async function followReplaySessionGate(ctx: TurnContext, kctx: NodeContext): Promise<void> {
+  const approval = await replaySessionApproval(ctx, kctx);
+  if (approval === undefined || approval.approved) return;
+  throwAgentTurnFailure({
+    code: 'hitl-rejected',
+    message: `The replayed run's reviewer rejected the session-HITL gate${
+      approval.rationale !== undefined ? `: ${approval.rationale}` : ''
+    }`,
+    ...(approval.rationale !== undefined && { rationale: approval.rationale }),
+  } as never);
+}
+
+/**
+ * A resumed replay turn's trace and approval, from the journal: every call
+ * decided before the park, and the session approval if `setup` reached it.
+ * The step the turn parked in decides its calls again, from the journal.
+ */
+export function rehydrateReplay(ctx: TurnContext, journal: readonly JournalEntry[]): void {
+  if (ctx.input.replay === undefined) return;
+  for (const e of journal) {
+    if (e.kind !== 'value.recorded') continue;
+    const p = (e.payload ?? {}) as Partial<ValueRecordedPayload>;
+    if (p.key === REPLAY_APPROVAL_RECORD) {
+      const approval = (p.value as { readonly approval?: unknown } | undefined)?.approval;
+      ctx.replayApproval = approval == null ? 'skipped' : 'followed';
+    } else if (p.key?.startsWith(REPLAY_TOOL_RECORD_PREFIX) === true) {
+      restoreDecision(ctx, p.value);
+    }
+  }
+}
+
+function restoreDecision(ctx: TurnContext, value: unknown): void {
+  const decided = value as RecordedDecision | undefined;
+  if (decided?.source !== undefined && decided.callId !== undefined) {
+    addReplayTrace(ctx, traceOf(decided));
+  }
+}
+
+/** The turn's replay report, for its result. */
+export function replayReport(ctx: TurnContext): ReplayTurnReport | undefined {
+  const replay = ctx.input.replay;
+  if (replay === undefined) return undefined;
+  return {
+    of: replay.of,
+    evalRunId: replay.evalRunId,
+    tools: [...(ctx.replayTrace ?? [])].sort((a, b) => a.step - b.step),
+    ...(ctx.replayApproval !== undefined && { approval: ctx.replayApproval }),
+  };
+}
+
+/** A replay's tag on its usage records (`ModelUsageRecord.replay`). */
+export function replayTag(replay: RunReplayRef): {
+  readonly of: string;
+  readonly evalRunId: string;
+} {
+  return { of: replay.of as unknown as string, evalRunId: replay.evalRunId };
+}