@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/dist/handlers/rehydrate.js

@@ -2,7 +2,11 @@
 // Copyright (C) 2026 Kindgi Inc.
 import { bodyStepKey } from '@kindgi/runtime';
 import { throwAgentTurnFailure } from './errors.js';
+import { readGateDecision } from './gate-decision.js';
+import { rehydrateReplay } from './replay.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';
 /** Each step's last completion — a step at one loop iteration counts once. */
 function completedSteps(journal) {
     const byStep = new Map();
@@ -18,6 +22,7 @@ function completedSteps(journal) {
             nodeId: e.nodeId,
             output: payload.output,
             inLoop: payload.loopContext !== undefined,
+            at: e.timestamp,
         });
     }
     return [...byStep.values()];
@@ -41,7 +46,10 @@ export async function rehydrateTurnContext(ctx, runId, journal) {
     }
     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(steps, 'persist-user-message');
     if (userMessage !== undefined) {
         await restoreAppended(ctx, userMessage.sequence);
@@ -59,8 +67,90 @@ export async function rehydrateTurnContext(ctx, runId, journal) {
         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) {
+    const callOf = new Map();
+    const parkedAt = new Map();
+    const resumed = new Map();
+    for (const e of journal) {
+        const gate = toolGateOf(e);
+        if (gate !== undefined)
+            callOf.set(gate.waitTokenId, gate.invocationId);
+        const p = (e.payload ?? {});
+        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();
+    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) {
+    if (e.kind !== 'value.recorded')
+        return undefined;
+    const p = (e.payload ?? {});
+    if (typeof p.key !== 'string' || !p.key.startsWith(TOOL_GATE_RECORD_PREFIX))
+        return undefined;
+    const waitTokenId = p.value?.waitTokenId;
+    return typeof waitTokenId === 'string'
+        ? { waitTokenId, invocationId: p.key.slice(TOOL_GATE_RECORD_PREFIX.length) }
+        : undefined;
+}
+/**
+ * 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, steps, retrieved) {
+    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();
+    for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+        const out = s.output;
+        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 }))
+        .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/dist/handlers/rehydrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../../src/handlers/rehydrate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../../src/handlers/rehydrate.ts"],"names":[],"mappings":"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"}

package/dist/handlers/render-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-prompt.d.ts","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA2BtE"}
+{"version":3,"file":"render-prompt.d.ts","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAiCtE"}

package/dist/handlers/render-prompt.js

@@ -26,7 +26,10 @@ export function buildRenderPromptHandler(ctx) {
                 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/dist/handlers/render-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAgB;IACvD,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACnC,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,8CAA8C;gBACvD,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;YACnD,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;YACtC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChE,YAAY,EAAE;gBACZ,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;gBAC5B,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,SAAS,GAAG,CAAC;aACrC;SACF,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,yBAAyB,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;gBAC1D,KAAK,EAAE,QAAQ,CAAC,KAAK;aACtB,CAAC,CAAC;QACL,CAAC;QACD,GAAG,CAAC,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAgB;IACvD,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACnC,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,8CAA8C;gBACvD,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,kBAAkB,CACjC,GAAG,CAAC,KAAK,CAAC,KAAK,EACf;YACE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;YACtC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChE,YAAY,EAAE;gBACZ,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;gBAC5B,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,SAAS,GAAG,CAAC;aACrC;YACD,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;SACnE;QACD,gEAAgE;QAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAC5B,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,yBAAyB,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;gBAC1D,KAAK,EAAE,QAAQ,CAAC,KAAK;aACtB,CAAC,CAAC;QACL,CAAC;QACD,GAAG,CAAC,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/replay.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 } 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';
+/** 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 declare const REPLAY_TOOL_RECORD_PREFIX = "replay-tool:";
+/** The `record` key of a replay's session approval. */
+export declare const REPLAY_APPROVAL_RECORD = "replay-session-approval";
+/** A tool that declares it changes nothing: `mutating: false`, and no changing effect. */
+export declare function isReadOnlyTool(tool: {
+    readonly mutating?: boolean;
+    readonly effects?: readonly {
+        readonly kind: string;
+    }[] | readonly string[];
+}): boolean;
+/**
+ * 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 declare 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>;
+/** The session approval a replay follows, decided once: the past run's, or none. */
+export declare function replaySessionApproval(ctx: TurnContext, kctx: NodeContext): Promise<ReplayApproval | 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 declare function followReplaySessionGate(ctx: TurnContext, kctx: NodeContext): Promise<void>;
+/**
+ * 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 declare function rehydrateReplay(ctx: TurnContext, journal: readonly JournalEntry[]): void;
+/** The turn's replay report, for its result. */
+export declare function replayReport(ctx: TurnContext): ReplayTurnReport | undefined;
+/** A replay's tag on its usage records (`ModelUsageRecord.replay`). */
+export declare function replayTag(replay: RunReplayRef): {
+    readonly of: string;
+    readonly evalRunId: string;
+};
+//# sourceMappingURL=replay.d.ts.map

package/dist/handlers/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/handlers/replay.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,+DAA+D;QAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChE;;;OAGG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC,CAAC;IACjF;;;;OAIG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CAC7E;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC5C;AAED,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AACxD,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAWhE,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,SAAS,MAAM,EAAE,CAAC;CAC7E,GAAG,OAAO,CAKV;AAgBD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE;IACJ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,GACA,OAAO,CAAC,kBAAkB,CAAC,CAqD7B;AAgBD,oFAAoF;AACpF,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAgBrC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhG;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAYxF;AASD,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAS3E;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAEA"}

package/dist/handlers/replay.js

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { throwAgentTurnFailure } from './errors.js';
+/** 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 = 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) {
+    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) {
+    return { status: 'not-executed', reason };
+}
+/**
+ * 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, kctx, call) {
+    const replay = ctx.input.replay;
+    if (replay === undefined)
+        return { kind: 'live' };
+    const base = {
+        step: call.step,
+        callId: call.callId,
+        toolId: call.tool.id,
+        toolVersion: call.version,
+        arguments: call.arguments,
+    };
+    const refuse = (reason) => ({
+        ...base,
+        source: 'refused',
+        reason,
+        result: refusedResult(reason),
+    });
+    const decided = await kctx.record(`${REPLAY_TOOL_RECORD_PREFIX}${call.callId}`, async () => {
+        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) {
+    const { result: _result, ...trace } = decided;
+    return trace;
+}
+function addReplayTrace(ctx, entry) {
+    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, kctx) {
+    const replay = ctx.input.replay;
+    if (replay === undefined)
+        return undefined;
+    const recorded = await kctx.record(REPLAY_APPROVAL_RECORD, async () => {
+        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, kctx) {
+    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 }),
+    });
+}
+/**
+ * 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, journal) {
+    if (ctx.input.replay === undefined)
+        return;
+    for (const e of journal) {
+        if (e.kind !== 'value.recorded')
+            continue;
+        const p = (e.payload ?? {});
+        if (p.key === REPLAY_APPROVAL_RECORD) {
+            const approval = p.value?.approval;
+            ctx.replayApproval = approval == null ? 'skipped' : 'followed';
+        }
+        else if (p.key?.startsWith(REPLAY_TOOL_RECORD_PREFIX) === true) {
+            restoreDecision(ctx, p.value);
+        }
+    }
+}
+function restoreDecision(ctx, value) {
+    const decided = value;
+    if (decided?.source !== undefined && decided.callId !== undefined) {
+        addReplayTrace(ctx, traceOf(decided));
+    }
+}
+/** The turn's replay report, for its result. */
+export function replayReport(ctx) {
+    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) {
+    return { of: replay.of, evalRunId: replay.evalRunId };
+}
+//# sourceMappingURL=replay.js.map

package/dist/handlers/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/handlers/replay.ts"],"names":[],"mappings":"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"}

package/dist/handlers/resolve-blocks.d.ts

@@ -0,0 +1,32 @@
+import { type ModelSettings, type PromptBlockContent } from '../blocks.js';
+import type { TurnContext } from './context.js';
+/** The block versions a turn runs, by kind then id, as `setup` journals them. */
+export interface PinnedBlockVersions {
+    readonly prompts: Readonly<Record<string, string>>;
+    readonly settings: Readonly<Record<string, string>>;
+}
+/** The data blocks a turn runs with, loaded at its version. */
+export interface TurnBlocks {
+    /** The prompt block the instructions come from. */
+    readonly prompt?: {
+        readonly id: string;
+        readonly version: string;
+        readonly content: PromptBlockContent;
+    };
+    /** Each settings block's values, by block id (`ToolContext.settings`, `settings` in templates). */
+    readonly settings: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /** The model-settings block's values, for the turn's model calls. */
+    readonly modelSettings?: ModelSettings;
+    readonly versions: PinnedBlockVersions;
+}
+/**
+ * Load the data blocks the agent references, each at one exact version:
+ * the resumed turn's own (`pinned`, from its `setup`), else the agent
+ * version's pin (`agent.pins`), else its range resolved now by
+ * `pickVersion` (an agent version published before pins). A pinned
+ * version that's unregistered still loads; one that's gone, a range
+ * nothing satisfies, or a runtime with no blocks fails the turn
+ * (`block-unresolvable`). `undefined` when the agent references none.
+ */
+export declare function resolveTurnBlocks(ctx: TurnContext, pinned?: PinnedBlockVersions): Promise<TurnBlocks | undefined>;
+//# sourceMappingURL=resolve-blocks.d.ts.map

package/dist/handlers/resolve-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-blocks.d.ts","sourceRoot":"","sources":["../../src/handlers/resolve-blocks.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAExB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;KACtC,CAAC;IACF,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AASD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,WAAW,EAChB,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAqCjC"}