@kindgi/agents 0.1.3 → 0.1.4-rc.1

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

package/src/handlers/resolve-blocks.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { pickVersion } from '@kindgi/tools';
+
+import {
+  type BlockDefinition,
+  MODEL_SETTINGS_SCHEMA,
+  type ModelSettings,
+  type PromptBlockContent,
+  settingsSchemaIssues,
+} from '../blocks.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.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;
+}
+
+interface Ref {
+  readonly kind: 'prompts' | 'settings';
+  readonly id: string;
+  readonly range: string;
+  readonly role: 'prompt' | 'settings' | 'model-settings';
+}
+
+/**
+ * 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: TurnContext,
+  pinned?: PinnedBlockVersions,
+): Promise<TurnBlocks | undefined> {
+  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] as Ref,
+      `agent "${agent.id}" references data blocks, but this runtime serves none`,
+    );
+  }
+
+  const versions = {
+    prompts: {} as Record<string, string>,
+    settings: {} as Record<string, string>,
+  };
+  const loaded = new Map<Ref, BlockDefinition>();
+  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: TurnContext): Ref[] {
+  const agent = ctx.input.agent;
+  const refs: Ref[] = [];
+  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: TurnContext, ref: Ref): Promise<string> {
+  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: readonly Ref[],
+  loaded: ReadonlyMap<Ref, BlockDefinition>,
+  versions: PinnedBlockVersions,
+): TurnBlocks {
+  const settings: Record<string, Readonly<Record<string, unknown>>> = {};
+  let prompt: TurnBlocks['prompt'];
+  let modelSettings: ModelSettings | undefined;
+  for (const ref of refs) {
+    const block = loaded.get(ref) as BlockDefinition;
+    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 as ModelSettings;
+    } else {
+      settings[block.id] = block.content.values;
+    }
+  }
+  return {
+    ...(prompt !== undefined && { prompt }),
+    settings,
+    ...(modelSettings !== undefined && { modelSettings }),
+    versions,
+  };
+}
+
+function describe(ref: Ref): string {
+  const what =
+    ref.role === 'prompt'
+      ? 'prompt'
+      : ref.role === 'model-settings'
+        ? 'model-settings'
+        : 'settings';
+  return `${what} block "${ref.id}"`;
+}
+
+function fail(ref: Ref, message: string): never {
+  return throwAgentTurnFailure({
+    code: 'block-unresolvable',
+    message,
+    blockId: ref.id,
+    requestedRange: ref.range,
+  });
+}

package/src/handlers/resolve-tools.ts

@@ -2,9 +2,10 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { ModelToolDefinition } from '@kindgi/capabilities';
-import type { Tool, ToolRegistry } from '@kindgi/tools';
+import type { Tool, ToolError, ToolRegistry, ToolResolution } from '@kindgi/tools';
+import type { Result, ToolId } from '@kindgi/types';
 
-import type { Agent } from '../types.js';
+import type { Agent, ToolRef } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
@@ -12,11 +13,16 @@ 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: ToolRegistry,
   agent: Agent,
+  pinned?: Readonly<Record<string, string>>,
 ): NonNullable<TurnContext['tools']> {
   const definitions: ModelToolDefinition[] = [];
   const byName = new Map<
@@ -29,32 +35,16 @@ export function resolveTurnTools(
     // (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 as never, 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 as never, 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({
@@ -66,3 +56,61 @@ export function resolveTurnTools(
   }
   return { definitions, byName };
 }
+
+/** A pinned tool version, retired or not, as a resolution. */
+function exactVersion(
+  registry: ToolRegistry,
+  id: string,
+  version: string,
+): Result<ToolResolution, ToolError> {
+  const found = registry.getVersion(id as ToolId, 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: Agent,
+  ref: ToolRef,
+  err: ToolError,
+  pin: string | undefined,
+  pinnedBy: 'turn' | 'agent',
+): never {
+  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 });
+}

package/src/handlers/result-shape.ts

@@ -7,6 +7,8 @@ import type { RunId } from '@kindgi/types';
 
 import type { ConversationId, ConversationMessage, RetrievedFact } from '../types.js';
 
+import type { ReplayTurnReport } from './replay.js';
+
 /**
  * Public shape returned by `invokeAgent` on success. Extracted from
  * `invoke.ts` into this module so handler code can import the type
@@ -70,6 +72,12 @@ export interface AgentTurnResult {
    * `response.content`.
    */
   readonly status?: 'completed' | 'suspended';
+  /**
+   * A replay turn's report (`InvokeAgentInput.replay`): each tool call and
+   * whether it ran, used the past run's result, or was refused (what the
+   * turn would have done), and how the session approval gate went.
+   */
+  readonly replay?: ReplayTurnReport;
 }
 
 /**