@kindgi/agents 0.1.3 → 0.1.4-rc.0

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":"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"}

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

package/dist/handlers/resolve-blocks.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { pickVersion } from '@kindgi/tools';
+import { MODEL_SETTINGS_SCHEMA, settingsSchemaIssues, } from '../blocks.js';
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * 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 async function resolveTurnBlocks(ctx, pinned) {
+    const agent = ctx.input.agent;
+    const refs = blockRefs(ctx);
+    if (refs.length === 0)
+        return undefined;
+    const reader = ctx.bindings.blockReader;
+    if (reader === undefined) {
+        fail(refs[0], `agent "${agent.id}" references data blocks, but this runtime serves none`);
+    }
+    const versions = {
+        prompts: {},
+        settings: {},
+    };
+    const loaded = new Map();
+    for (const ref of refs) {
+        const version = pinned?.[ref.kind][ref.id] ??
+            agent.pins?.[ref.kind][ref.id] ??
+            (await resolveRange(ctx, ref));
+        const block = await reader.getVersion({
+            tenantId: ctx.input.tenantId,
+            blockId: ref.id,
+            version,
+        });
+        if (block === null) {
+            fail(ref, `${describe(ref)} runs version ${version}, which isn't published`);
+        }
+        if (block.kind !== (ref.role === 'prompt' ? 'prompt' : 'settings')) {
+            fail(ref, `${describe(ref)} is a ${block.kind} block`);
+        }
+        versions[ref.kind][ref.id] = version;
+        loaded.set(ref, block);
+    }
+    return turnBlocks(refs, loaded, versions);
+}
+function blockRefs(ctx) {
+    const agent = ctx.input.agent;
+    const refs = [];
+    if (typeof agent.instructions === 'object') {
+        refs.push({
+            kind: 'prompts',
+            id: agent.instructions.prompt,
+            range: agent.instructions.version,
+            role: 'prompt',
+        });
+    }
+    for (const s of agent.settings ?? []) {
+        refs.push({ kind: 'settings', id: s.id, range: s.version, role: 'settings' });
+    }
+    if (agent.modelSettings !== undefined) {
+        refs.push({
+            kind: 'settings',
+            id: agent.modelSettings.id,
+            range: agent.modelSettings.version,
+            role: 'model-settings',
+        });
+    }
+    return refs;
+}
+/** An unpinned reference's range, resolved over the block's active versions. */
+async function resolveRange(ctx, ref) {
+    const available = (await ctx.bindings.blockReader?.activeVersions({
+        tenantId: ctx.input.tenantId,
+        blockId: ref.id,
+    })) ?? [];
+    const pick = pickVersion(available, ref.range);
+    if (pick.kind === 'ok')
+        return pick.version;
+    return fail(ref, available.length === 0
+        ? `${describe(ref)} has no published version`
+        : `${describe(ref)} has no published version in "${ref.range}" (published: ${available.join(', ')})`);
+}
+function turnBlocks(refs, loaded, versions) {
+    const settings = {};
+    let prompt;
+    let modelSettings;
+    for (const ref of refs) {
+        const block = loaded.get(ref);
+        if (block.kind === 'prompt') {
+            prompt = { id: block.id, version: block.version, content: block.content };
+        }
+        else if (ref.role === 'model-settings') {
+            const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+            if (issues.length > 0) {
+                fail(ref, `${describe(ref)} version ${block.version} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`);
+            }
+            modelSettings = block.content.values;
+        }
+        else {
+            settings[block.id] = block.content.values;
+        }
+    }
+    return {
+        ...(prompt !== undefined && { prompt }),
+        settings,
+        ...(modelSettings !== undefined && { modelSettings }),
+        versions,
+    };
+}
+function describe(ref) {
+    const what = ref.role === 'prompt'
+        ? 'prompt'
+        : ref.role === 'model-settings'
+            ? 'model-settings'
+            : 'settings';
+    return `${what} block "${ref.id}"`;
+}
+function fail(ref, message) {
+    return throwAgentTurnFailure({
+        code: 'block-unresolvable',
+        message,
+        blockId: ref.id,
+        requestedRange: ref.range,
+    });
+}
+//# sourceMappingURL=resolve-blocks.js.map

package/dist/handlers/resolve-blocks.js.map

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

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

@@ -4,7 +4,11 @@ import type { TurnContext } from './context.js';
 /**
  * Resolve the agent's tool references against one tenant's registry
  * (`ToolRegistry.forTenant`). Throws the turn failure for an unknown
- * tool or an unsatisfiable version range.
+ * tool or an unsatisfiable version range. A tool in `pinned` (a resumed
+ * turn's, from its `setup`) resolves to exactly that version, and so,
+ * otherwise, does one in the agent version's own pins (`agent.pins`, set
+ * when it was published): one that's gone fails the turn rather than
+ * running another. Without either, the tool's range resolves.
  */
-export declare function resolveTurnTools(registry: ToolRegistry, agent: Agent): NonNullable<TurnContext['tools']>;
+export declare function resolveTurnTools(registry: ToolRegistry, agent: Agent, pinned?: Readonly<Record<string, string>>): NonNullable<TurnContext['tools']>;
 //# sourceMappingURL=resolve-tools.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"resolve-tools.d.ts","sourceRoot":"","sources":["../../src/handlers/resolve-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAQ,YAAY,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,KAAK,GACX,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAgDnC"}
+{"version":3,"file":"resolve-tools.d.ts","sourceRoot":"","sources":["../../src/handlers/resolve-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAmB,YAAY,EAAkB,MAAM,eAAe,CAAC;AAGnF,OAAO,KAAK,EAAE,KAAK,EAAW,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAgCnC"}

package/dist/handlers/resolve-tools.js

@@ -4,9 +4,13 @@ import { throwAgentTurnFailure } from './errors.js';
 /**
  * Resolve the agent's tool references against one tenant's registry
  * (`ToolRegistry.forTenant`). Throws the turn failure for an unknown
- * tool or an unsatisfiable version range.
+ * tool or an unsatisfiable version range. A tool in `pinned` (a resumed
+ * turn's, from its `setup`) resolves to exactly that version, and so,
+ * otherwise, does one in the agent version's own pins (`agent.pins`, set
+ * when it was published): one that's gone fails the turn rather than
+ * running another. Without either, the tool's range resolves.
  */
-export function resolveTurnTools(registry, agent) {
+export function resolveTurnTools(registry, agent, pinned) {
     const definitions = [];
     const byName = new Map();
     for (const ref of agent.tools) {
@@ -15,32 +19,15 @@ export function resolveTurnTools(registry, agent) {
         // (npm-compatible semver, backed by `maxSatisfying`); capture `resolvedVersion` in
         // the byName map so `dispatch-tools` can emit it in provenance +
         // telemetry — a replay can then pin against the same version.
-        const resolved = registry.resolve(ref.id, ref.version);
+        const turnPin = pinned?.[ref.id];
+        const pin = turnPin ?? agent.pins?.tools[ref.id];
+        // A pin names its exact version, which a retired (unregistered) one
+        // still serves; a range picks among the active versions only.
+        const resolved = pin !== undefined
+            ? exactVersion(registry, ref.id, pin)
+            : registry.resolve(ref.id, ref.version);
         if (resolved.kind === 'err') {
-            const err = resolved.error;
-            if (err.code === 'tool-not-found') {
-                throwAgentTurnFailure({
-                    code: 'unresolved-tool',
-                    message: `Tool "${ref.id}" declared by agent "${agent.id}" is not registered`,
-                    toolId: ref.id,
-                });
-            }
-            if (err.code === 'invalid-version-range' || err.code === 'tool-version-unresolvable') {
-                throwAgentTurnFailure({
-                    code: 'tool-version-unresolvable',
-                    message: err.message,
-                    toolId: ref.id,
-                    requestedRange: ref.version,
-                    ...(err.code === 'tool-version-unresolvable' && {
-                        availableVersions: err.availableVersions,
-                    }),
-                });
-            }
-            throwAgentTurnFailure({
-                code: 'unresolved-tool',
-                message: err.message,
-                toolId: ref.id,
-            });
+            throwUnresolved(agent, ref, resolved.error, pin, turnPin !== undefined ? 'turn' : 'agent');
         }
         const { tool, resolvedVersion } = resolved.value;
         definitions.push({
@@ -52,4 +39,49 @@ export function resolveTurnTools(registry, agent) {
     }
     return { definitions, byName };
 }
+/** A pinned tool version, retired or not, as a resolution. */
+function exactVersion(registry, id, version) {
+    const found = registry.getVersion(id, version);
+    return found.kind === 'ok'
+        ? { kind: 'ok', value: { tool: found.value, resolvedVersion: version } }
+        : found;
+}
+/**
+ * Fail the turn for a tool that didn't resolve. A pinned version that's
+ * gone names whose pin it was: the turn's own (it started with that
+ * version) or the agent version's (it was published with it).
+ */
+function throwUnresolved(agent, ref, err, pin, pinnedBy) {
+    const available = err.code === 'tool-version-unresolvable' && {
+        availableVersions: err.availableVersions,
+    };
+    if (pin !== undefined) {
+        throwAgentTurnFailure({
+            code: 'tool-version-unresolvable',
+            message: pinnedBy === 'turn'
+                ? `Tool "${ref.id}": this turn started with version ${pin}, which is no longer registered; it doesn't run another version mid-turn. ${err.message}`
+                : `Tool "${ref.id}": agent "${agent.id}" version ${agent.version} runs version ${pin} (its pins), which isn't registered; it doesn't run another version. ${err.message}`,
+            toolId: ref.id,
+            requestedRange: ref.version,
+            ...available,
+        });
+    }
+    if (err.code === 'tool-not-found') {
+        throwAgentTurnFailure({
+            code: 'unresolved-tool',
+            message: `Tool "${ref.id}" declared by agent "${agent.id}" is not registered`,
+            toolId: ref.id,
+        });
+    }
+    if (err.code === 'invalid-version-range' || err.code === 'tool-version-unresolvable') {
+        throwAgentTurnFailure({
+            code: 'tool-version-unresolvable',
+            message: err.message,
+            toolId: ref.id,
+            requestedRange: ref.version,
+            ...available,
+        });
+    }
+    throwAgentTurnFailure({ code: 'unresolved-tool', message: err.message, toolId: ref.id });
+}
 //# sourceMappingURL=resolve-tools.js.map