@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/handlers/turn-environment.ts

@@ -21,6 +21,7 @@ import { mergeTenantPolicies } from '../tenant-policy.js';
 import type { Conversation } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { type PinnedBlockVersions, resolveTurnBlocks } from './resolve-blocks.js';
 import { resolveTurnTools } from './resolve-tools.js';
 import { type ToolErrorPolicy, effectiveToolErrorPolicy } from './tool-errors.js';
 
@@ -61,16 +62,33 @@ export interface PinnedRoute {
   readonly model: string;
 }
 
+/**
+ * The tool version each of the agent's tool references resolved to, by
+ * tool id, as `setup` journals it: a resumed turn runs these versions,
+ * whatever the registry holds by then.
+ */
+export type PinnedToolVersions = Readonly<Record<string, string>>;
+
 /**
  * Resolve the turn's guardrails, tools, tenant policy, tool-error policy
  * and model onto `ctx`. With `pinned`, the route is that provider and
  * model, still under the tenant's current policy; one no longer
- * registered or allowed fails the turn.
+ * registered or allowed fails the turn. With `pinnedTools`, each tool is
+ * that exact version, not its range resolved again; one no longer
+ * registered fails the turn.
  */
 export async function resolveTurnEnvironment(
   ctx: TurnContext,
   pinned?: PinnedRoute,
-): Promise<PinnedRoute & { readonly toolCount: number }> {
+  pinnedTools?: PinnedToolVersions,
+  pinnedBlocks?: PinnedBlockVersions,
+): Promise<
+  PinnedRoute & {
+    readonly toolCount: number;
+    readonly toolVersions: PinnedToolVersions;
+    readonly blockVersions?: PinnedBlockVersions;
+  }
+> {
   const invResolution = resolveGuardrails(ctx.input.agent, ctx.bindings);
   if (invResolution.missing.length > 0) {
     throwAgentTurnFailure({
@@ -84,7 +102,10 @@ export async function resolveTurnEnvironment(
   // This turn's tools come from the tenant's own registry — never a
   // registry shared across concurrent turns of other tenants.
   const tenantTools = await ctx.bindings.toolRegistry.forTenant(ctx.input.tenantId);
-  ctx.tools = resolveTurnTools(tenantTools, ctx.input.agent);
+  ctx.tools = resolveTurnTools(tenantTools, ctx.input.agent, pinnedTools);
+  // The data blocks, at the versions pinned (the turn's own on resume).
+  const blocks = await resolveTurnBlocks(ctx, pinnedBlocks);
+  if (blocks !== undefined) ctx.blocks = blocks;
 
   const capability = ctx.input.agent.capabilities[0];
   if (capability === undefined) {
@@ -151,6 +172,10 @@ export async function resolveTurnEnvironment(
     providerId: routed.value.provider.metadata.id,
     model: routed.value.model.name,
     toolCount: ctx.tools.definitions.length,
+    toolVersions: Object.fromEntries(
+      [...ctx.tools.byName].map(([id, binding]) => [id, binding.resolvedVersion]),
+    ),
+    ...(blocks !== undefined && { blockVersions: blocks.versions }),
   };
 }
 

package/src/handlers/turn-provenance.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The provenance nodes and edges an agent turn records, in one place:
+ * the steps add them as they run, and a turn resumed after a park
+ * (`rehydrate.ts`) adds those of the steps that ran before it from what
+ * they left durable (the conversation, the journal). Either way the DAG
+ * is the same.
+ */
+
+import type { ProvenanceBuilder } from '@kindgi/provenance';
+import type { Timestamp } from '@kindgi/types';
+
+import type { ConversationMessage, RetrievedFact } from '../types.js';
+import type { TurnContext } from './context.js';
+import type { GateDecision } from './gate-decision.js';
+
+/** The turn's user message. */
+export function addInputNode(provenance: ProvenanceBuilder, message: ConversationMessage): void {
+  provenance.addNode({
+    id: `input:${message.sequence}`,
+    kind: 'input',
+    timestamp: message.createdAt,
+    ...(message.actor !== undefined && { actor: message.actor }),
+  });
+}
+
+/** The facts the turn retrieved for its user message. */
+export function addRetrievalNodes(
+  provenance: ProvenanceBuilder,
+  retrieved: readonly RetrievedFact[],
+  input: ConversationMessage,
+): void {
+  for (const r of retrieved) {
+    provenance.addNode({
+      id: `retrieval:${r.fact.id}`,
+      kind: 'retrieval',
+      timestamp: input.createdAt,
+      ...(r.fact.contentHash !== undefined && { contentHash: r.fact.contentHash }),
+      attributes: {
+        factId: r.fact.id,
+        factType: r.fact.type,
+        intentScope: r.intent.scope,
+        ...(r.score !== undefined && { score: r.score }),
+      },
+    });
+    provenance.addEdge({
+      from: `retrieval:${r.fact.id}`,
+      to: `input:${input.sequence}`,
+      kind: 'influenced-by',
+    });
+  }
+}
+
+/** One model call: its identity; its usage is the cost ledger's, by `callId`. */
+export interface ModelCallFacts {
+  readonly step: number;
+  readonly callId: string;
+  readonly provider: { readonly id: string; readonly model: string };
+  readonly finishReason: string;
+  readonly at: Timestamp;
+}
+
+/**
+ * A model call, `caused-by` the turn's user message and `influenced-by`
+ * each of this turn's tool results it read: all of them so far, since
+ * the call's input holds every message of the turn before it.
+ */
+export function addModelCallNode(
+  provenance: ProvenanceBuilder,
+  call: ModelCallFacts,
+  inputSequence: number,
+  toolResultIds: readonly string[],
+): void {
+  const id = `model-call:${call.step}`;
+  provenance.addNode({
+    id,
+    kind: 'model-call',
+    timestamp: call.at,
+    modelVersion: `${call.provider.id}/${call.provider.model}`,
+    attributes: {
+      step: call.step,
+      callId: call.callId,
+      providerId: call.provider.id,
+      model: call.provider.model,
+      finishReason: call.finishReason,
+    },
+  });
+  provenance.addEdge({ from: id, to: `input:${inputSequence}`, kind: 'caused-by' });
+  for (const invocationId of toolResultIds) {
+    provenance.addEdge({ from: id, to: `tool-result:${invocationId}`, kind: 'influenced-by' });
+  }
+}
+
+/**
+ * A tool call the model at `step` made, and its result: the stored tool
+ * message (a tool's output, a rejected approval's, or a failed call's).
+ * `version` is the tool the agent's binding resolved, when it has one.
+ */
+export function addToolNodes(
+  provenance: ProvenanceBuilder,
+  step: number,
+  result: ConversationMessage,
+  version: { readonly resolvedVersion: string; readonly requestedRange: string } | undefined,
+): void {
+  const call = result.toolCall;
+  if (call === undefined) return;
+  const callNodeId = `tool-call:${call.invocationId}`;
+  const resultNodeId = `tool-result:${call.invocationId}`;
+  provenance.addNode({
+    id: callNodeId,
+    kind: 'tool-call',
+    timestamp: result.createdAt,
+    attributes: {
+      toolId: call.toolId,
+      invocationId: call.invocationId,
+      // The version the registry picked for the turn and the range the
+      // agent asked for, so a replay can pin against the same version.
+      ...(version !== undefined && {
+        toolVersion: version.resolvedVersion,
+        toolVersionRange: version.requestedRange,
+      }),
+    },
+  });
+  provenance.addNode({ id: resultNodeId, kind: 'tool-result', timestamp: result.createdAt });
+  provenance.addEdge({ from: callNodeId, to: `model-call:${step}`, kind: 'invoked' });
+  provenance.addEdge({ from: resultNodeId, to: callNodeId, kind: 'produced' });
+}
+
+/**
+ * The tool calls of one model step: a node pair for each result the step
+ * stored, and their invocation ids added to the turn's tool results.
+ */
+export function addStepToolNodes(
+  ctx: TurnContext,
+  step: number,
+  stored: readonly ConversationMessage[],
+): void {
+  for (const result of stored) {
+    if (result.role !== 'tool' || result.toolCall === undefined) continue;
+    const { invocationId, toolId } = result.toolCall;
+    if (ctx.provenance !== undefined) {
+      addToolNodes(ctx.provenance, step, result, versionOf(ctx, toolId));
+      const approval = ctx.toolApprovals?.get(invocationId);
+      if (approval !== undefined) {
+        addToolApprovalNodes(
+          ctx.provenance,
+          invocationId,
+          approval,
+          ctx.input.agent.id as unknown as string,
+        );
+      }
+    }
+    ctx.toolResultIds ??= [];
+    ctx.toolResultIds.push(invocationId);
+  }
+}
+
+/** A tool call's approval, decided: the wait it parked on and the answer. */
+export interface ToolApproval {
+  readonly waitTokenId: string;
+  /** When the call parked on the approval. */
+  readonly parkedAt: Timestamp;
+  /** When the decision reached the run. */
+  readonly decidedAt: Timestamp;
+  readonly decision: GateDecision;
+}
+
+/**
+ * The approval a tool call waited on, as the session gate records its own:
+ * a `wait` node (the agent parked) `resumed-from` a `resume` node (the
+ * decision, its actor whoever decided). The call `waited-on` the wait, and
+ * its result was `caused-by` the decision: the tool's output when approved,
+ * the rejection when not.
+ */
+export function addToolApprovalNodes(
+  provenance: ProvenanceBuilder,
+  invocationId: string,
+  approval: ToolApproval,
+  agentId: string,
+): void {
+  const waitId = `tool-hitl-gate-wait:${invocationId}`;
+  const resumeId = `tool-hitl-gate-resume:${invocationId}`;
+  const { decision } = approval;
+  provenance.addNode({
+    id: waitId,
+    kind: 'wait',
+    timestamp: approval.parkedAt,
+    actor: `agent:${agentId}`,
+    attributes: { gate: 'tool-call', invocationId, waitTokenId: approval.waitTokenId },
+  });
+  provenance.addNode({
+    id: resumeId,
+    kind: 'resume',
+    timestamp: approval.decidedAt,
+    ...(decision.decidedBy !== undefined && { actor: decision.decidedBy }),
+    attributes: {
+      gate: 'tool-call',
+      decision: decisionOf(decision),
+      ...(!decision.approved &&
+        decision.reason === 'rejected' &&
+        decision.rationale !== undefined && { rationale: decision.rationale }),
+      ...(decision.approvalId !== undefined && { approvalId: decision.approvalId }),
+    },
+  });
+  provenance.addEdge({ from: `tool-call:${invocationId}`, to: waitId, kind: 'waited-on' });
+  provenance.addEdge({ from: waitId, to: resumeId, kind: 'resumed-from' });
+  provenance.addEdge({ from: `tool-result:${invocationId}`, to: resumeId, kind: 'caused-by' });
+}
+
+/** A gate decision as a `resume` node records it. */
+export function decisionOf(decision: GateDecision): 'approve' | 'reject' | 'unreadable' {
+  if (decision.approved) return 'approve';
+  return decision.reason === 'rejected' ? 'reject' : 'unreadable';
+}
+
+/** The version the agent's binding of `toolId` resolved, if it has one. */
+function versionOf(
+  ctx: TurnContext,
+  toolId: string,
+): { readonly resolvedVersion: string; readonly requestedRange: string } | undefined {
+  const bindings = [...(ctx.tools?.byName.values() ?? [])];
+  const binding =
+    ctx.tools?.byName.get(toolId) ??
+    bindings.find((b) => (b.tool.id as unknown as string) === toolId);
+  return binding === undefined
+    ? undefined
+    : { resolvedVersion: binding.resolvedVersion, requestedRange: binding.requestedRange };
+}

package/src/index.ts

@@ -17,10 +17,44 @@ export type {
   RunSnapshotWriteInput,
 } from './run-snapshot-binding.js';
 export { defineAgent } from './define.js';
+export {
+  BLOCK_KINDS,
+  MODEL_SETTINGS_SCHEMA,
+  settingsSchemaIssues,
+  validateBlock,
+} from './blocks.js';
+export type {
+  BlockDefinition,
+  BlockIssue,
+  BlockKind,
+  BlockReader,
+  InvalidBlock,
+  ModelSettings,
+  PromptBlockContent,
+  SettingsBlockContent,
+} from './blocks.js';
 export type { DefineAgentSpec } from './define.js';
 export { resolveEffectiveHitlPolicy } from './hitl-policy.js';
+export {
+  AGENT_GATE_SUBJECTS,
+  SESSION_GATE_SUBJECT,
+  TOOL_CALL_GATE_SUBJECT,
+  readGateDecision,
+} from './handlers/gate-decision.js';
+export type { GateDecision, GateDecisionValue } from './handlers/gate-decision.js';
 export type { EffectiveHitlPolicy } from './hitl-policy.js';
 export { agentStepOutput, invokeAgent, resumeAgentTurn } from './invoke.js';
+export { isReadOnlyTool } from './handlers/replay.js';
+export { SESSION_GATE_RECORD } from './handlers/setup.js';
+export type {
+  ReplayApproval,
+  ReplayBinding,
+  ReplayToolDecision,
+  ReplayToolInput,
+  ReplayToolTrace,
+  ReplayTurnRef,
+  ReplayTurnReport,
+} from './handlers/replay.js';
 export type {
   AgentStepOutput,
   AgentTurnAbortedError,
@@ -80,6 +114,14 @@ export type {
   RenderFailureError,
   RenderResult,
 } from './prompt.js';
+export { pinChanges, pinsDigest } from './pins.js';
+export type {
+  AgentDerivation,
+  AgentDerivationReason,
+  AgentPins,
+  PinChange,
+  PinSet,
+} from './pins.js';
 export { createAgentRegistry } from './registry.js';
 export type { AgentRegistry } from './registry.js';
 export {
@@ -98,12 +140,14 @@ export type {
   AgentBindings,
   AgentId,
   AgentOutputSpec,
+  BlockRef,
   Conversation,
   ConversationId,
   ConversationMessage,
   ConversationPolicy,
   MessageRole,
   PromptParameter,
+  PromptRef,
   RetrievalIntent,
   RetrievedFact,
   ToolRef,

package/src/invoke.ts

@@ -3,7 +3,7 @@
 
 import type { Principal } from '@kindgi/authz';
 import type { KernelError, RunResult } from '@kindgi/runtime';
-import type { Result, RunId, TenantId } from '@kindgi/types';
+import type { OrgId, Result, RunId, TenantId } from '@kindgi/types';
 
 import { AGENT_TURN_FLOW } from './agent-turn-flow.js';
 import { DEFAULT_MAX_WALL_MS } from './handlers/constants.js';
@@ -14,6 +14,7 @@ import type { InvokeAgentBindings, InvokeAgentInput } from './handlers/public-ty
 import { rehydrateTurnContext } from './handlers/rehydrate.js';
 import type { AgentTurnResult } from './handlers/result-shape.js';
 import { projectRunResult } from './project-run-result.js';
+import type { RunSnapshotRecord } from './run-snapshot-binding.js';
 import type { Agent } from './types.js';
 
 /**
@@ -82,7 +83,15 @@ export async function invokeAgent(
       flow: AGENT_TURN_FLOW,
       handlers,
       input: input.userMessage,
+      // The run's record names the agent, its version and the conversation.
+      agent: {
+        id: input.agent.id,
+        version: input.agent.version,
+        conversationId: input.conversationId,
+      },
       ...(input.parent !== undefined && { parent: input.parent }),
+      // A replay's run says so, and which eval run and past run it is for.
+      ...(input.replay !== undefined && { replay: input.replay }),
       ...(input.dryRun === true && { options: { dryRun: true } }),
       // Authorization — carry principal + authz into the run so every
       // tool invocation inside the agent's turn is checked.
@@ -106,6 +115,12 @@ export interface ResumeAgentTurnInput {
    * handler's agent-version-mismatch guard).
    */
   readonly agent: Agent;
+  /**
+   * The org of the run's project (the snapshot's `projectId`), when it has
+   * one. The caller resolves it from the project, as for `invokeAgent`'s
+   * `orgId`, so the resumed turn's tools and guardrails see it too.
+   */
+  readonly orgId?: OrgId;
 }
 
 /**
@@ -203,25 +218,7 @@ export async function resumeAgentTurn(
   }
 
   // 3. Reconstruct the InvokeAgentInput envelope from the snapshot.
-  const reconstructedInput: InvokeAgentInput = {
-    tenantId: snapshot.tenantId,
-    projectId: snapshot.projectId,
-    agent: input.agent,
-    conversationId: snapshot.conversationId,
-    userMessage: snapshot.userMessage,
-    ...(snapshot.parameters !== undefined && { parameters: snapshot.parameters }),
-    ...(snapshot.input !== undefined && { input: snapshot.input }),
-    ...(snapshot.participantId !== undefined && { participantId: snapshot.participantId }),
-    ...(snapshot.dryRun && { dryRun: true }),
-    ...(snapshot.principal !== undefined &&
-      snapshot.principal !== null && {
-        principal: snapshot.principal as Principal,
-      }),
-    ...(snapshot.authz !== undefined &&
-      snapshot.authz !== null && {
-        authz: snapshot.authz as { readonly fgaApiUrl: string },
-      }),
-  };
+  const reconstructedInput = turnInputFromSnapshot(snapshot, input);
 
   // 4. Build the same TurnContext + handlers as invokeAgent().
   const started = Date.now();
@@ -299,3 +296,35 @@ export type {
   InvokeAgentBindings,
   InvokeAgentInput,
 } from './handlers/public-types.js';
+
+/**
+ * The `InvokeAgentInput` a resumed turn runs with: the one captured in its
+ * snapshot at run start, the agent the caller resolved, and the org of the
+ * run's project, which the caller resolves as for `invokeAgent`.
+ */
+export function turnInputFromSnapshot(
+  snapshot: RunSnapshotRecord,
+  input: Pick<ResumeAgentTurnInput, 'agent' | 'orgId'>,
+): InvokeAgentInput {
+  return {
+    tenantId: snapshot.tenantId,
+    projectId: snapshot.projectId,
+    ...(input.orgId !== undefined && { orgId: input.orgId }),
+    agent: input.agent,
+    conversationId: snapshot.conversationId,
+    userMessage: snapshot.userMessage,
+    ...(snapshot.parameters !== undefined && { parameters: snapshot.parameters }),
+    ...(snapshot.input !== undefined && { input: snapshot.input }),
+    ...(snapshot.participantId !== undefined && { participantId: snapshot.participantId }),
+    ...(snapshot.dryRun && { dryRun: true }),
+    ...(snapshot.principal !== undefined &&
+      snapshot.principal !== null && {
+        principal: snapshot.principal as Principal,
+      }),
+    ...(snapshot.authz !== undefined &&
+      snapshot.authz !== null && {
+        authz: snapshot.authz as { readonly fgaApiUrl: string },
+      }),
+    ...(snapshot.replay !== undefined && snapshot.replay !== null && { replay: snapshot.replay }),
+  };
+}

package/src/pins.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { createHash } from 'node:crypto';
+
+import { canonicalize } from '@kindgi/schema';
+import type { VersionDerivation, VersionDerivationReason } from '@kindgi/types';
+
+/**
+ * The exact version of each block an agent version runs: its lockfile.
+ *
+ * An agent names its tools by range (`{ id: 'acme.lookup', version:
+ * '^1.0.0' }`), like `package.json`. When a version of the agent is
+ * published, the runtime resolves each range once, and every run of that
+ * version uses the versions recorded here. So a new tool version reaches
+ * an agent only through a new agent version, and two runs of one agent
+ * version always run the same blocks.
+ *
+ * Set by the runtime at publish, never authored. A version published
+ * before pins existed has none and resolves its ranges per run.
+ */
+export interface AgentPins {
+  /** Tool id → the exact version this agent version runs. */
+  readonly tools: Readonly<Record<string, string>>;
+  /** Prompt block id → exact version. Empty until the agent references prompt blocks. */
+  readonly prompts: Readonly<Record<string, string>>;
+  /** Settings block id → exact version. Empty until the agent references settings blocks. */
+  readonly settings: Readonly<Record<string, string>>;
+}
+
+/**
+ * One string naming a set of pins: `sha256:<hex>` of the pins'
+ * canonical JSON (keys sorted, no whitespace). Two agent versions with
+ * the same digest run the same blocks; the digest is what a comparison
+ * of versions, or a gate, records and compares. The Python SDK's
+ * `pins_digest` computes the same string.
+ */
+export function pinsDigest(pins: AgentPins): string {
+  const canonical = canonicalize({
+    tools: pins.tools,
+    prompts: pins.prompts,
+    settings: pins.settings,
+  });
+  return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+
+/** Why a deploy registered an agent version under another number (`VersionDerivationReason`). */
+export type AgentDerivationReason = VersionDerivationReason;
+
+/** The version an agent version was registered in place of, and why. */
+export type AgentDerivation = VersionDerivation;
+
+/** One pin that differs between two versions of an agent or a flow. */
+export interface PinChange {
+  readonly kind: 'tool' | 'prompt' | 'setting' | 'agent';
+  readonly id: string;
+  /** The earlier version's pin; absent when it didn't pin this block. */
+  readonly from?: string;
+  /** The later version's pin; absent when it doesn't pin this block. */
+  readonly to?: string;
+}
+
+const PIN_KINDS = [
+  ['tools', 'tool'],
+  ['prompts', 'prompt'],
+  ['settings', 'setting'],
+  ['agents', 'agent'],
+] as const;
+
+/** A version's pins by kind: an agent's (`AgentPins`) or a flow's (`FlowPins`). */
+export type PinSet = Partial<
+  Record<(typeof PIN_KINDS)[number][0], Readonly<Record<string, string>>>
+>;
+
+/**
+ * The pins that differ from `before` to `after`, by kind then id. With
+ * no `before` (a version published before pins), every pin of `after`
+ * is a change.
+ */
+export function pinChanges(before: PinSet | undefined, after: PinSet): PinChange[] {
+  const changes: PinChange[] = [];
+  for (const [key, kind] of PIN_KINDS) {
+    const was = before?.[key] ?? {};
+    const now = after[key] ?? {};
+    for (const id of [...new Set([...Object.keys(was), ...Object.keys(now)])].sort()) {
+      const from = was[id];
+      const to = now[id];
+      if (from === to) continue;
+      changes.push({
+        kind,
+        id,
+        ...(from !== undefined && { from }),
+        ...(to !== undefined && { to }),
+      });
+    }
+  }
+  return changes;
+}

package/src/prompt.ts

@@ -3,7 +3,8 @@
 
 import { Liquid } from 'liquidjs';
 
-import type { Agent, PromptParameter } from './types.js';
+import type { PromptBlockContent } from './blocks.js';
+import type { Agent, PromptParameter, PromptRef } from './types.js';
 
 /**
  * Reserved variable namespaces the runtime injects automatically.
@@ -20,8 +21,18 @@ import type { Agent, PromptParameter } from './types.js';
  *   - `input`             — the turn's structured input (`InvokeAgentInput.input`),
  *                           e.g. `{{ input.grievance.summary }}`; unset when
  *                           the turn has none.
+ *   - `settings`          — the agent's settings blocks' values, by block id:
+ *                           `{{ settings["acme.weights"].recency }}` reads
+ *                           block `acme.weights`; unset when it has none.
  */
-export const AUTO_INJECTED_VARS = ['today', 'now', 'agent', 'conversation', 'input'] as const;
+export const AUTO_INJECTED_VARS = [
+  'today',
+  'now',
+  'agent',
+  'conversation',
+  'input',
+  'settings',
+] as const;
 
 /**
  * Shape passed to `renderInstructions`. Framework auto-vars are
@@ -37,6 +48,8 @@ export interface RenderContext {
   };
   /** The turn's structured input, rendered as `{{ input.* }}`. */
   readonly input?: unknown;
+  /** The agent's settings blocks' values, by block id: `{{ settings["<id>"].<key> }}`. */
+  readonly settings?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   /**
    * Optional clock override — tests inject a fixed date. Defaults to
    * `new Date()`.
@@ -84,14 +97,21 @@ export interface RenderFailureError {
  * Uses `strictVariables: true` so an unresolved `{{ var }}` is an error
  * — never a silent empty string. This is load-bearing for correctness
  * (a system prompt with a missing firm name is worse than a hard fail).
+ *
+ * When the instructions come from a prompt block, `prompt` is the
+ * version the turn runs (its template and declared parameters); an
+ * agent whose instructions are a prompt block can't render without it.
  */
 export function renderInstructions(
   agent: Agent,
   context: RenderContext,
+  prompt?: PromptBlockContent,
 ):
   | { readonly ok: true; readonly value: RenderResult }
   | { readonly ok: false; readonly error: PromptRenderError } {
-  const declared = agent.parameters ?? [];
+  const source = instructionsSource(agent, prompt);
+  if (!source.ok) return source;
+  const { template, declared } = source.value;
   const missing = requiredMissing(declared, context.parameters);
   if (missing.length > 0) {
     return {
@@ -107,7 +127,7 @@ export function renderInstructions(
   const merged = mergeContext(agent, declared, context);
   const liquid = new Liquid({ strictVariables: true, strictFilters: true });
   try {
-    const rendered = liquid.parseAndRenderSync(agent.instructions, merged);
+    const rendered = liquid.parseAndRenderSync(template, merged);
     return { ok: true, value: { rendered, context: merged } };
   } catch (cause) {
     // LiquidJS throws UndefinedVariableError for unresolved refs — surface
@@ -135,6 +155,33 @@ export function renderInstructions(
   }
 }
 
+/** The template to render and the parameters it declares: the prompt block's, or the agent's own. */
+function instructionsSource(
+  agent: Agent,
+  prompt: PromptBlockContent | undefined,
+):
+  | {
+      readonly ok: true;
+      readonly value: { readonly template: string; readonly declared: readonly PromptParameter[] };
+    }
+  | { readonly ok: false; readonly error: PromptRenderError } {
+  if (prompt !== undefined) {
+    return { ok: true, value: { template: prompt.template, declared: prompt.parameters ?? [] } };
+  }
+  if (typeof agent.instructions === 'string') {
+    return { ok: true, value: { template: agent.instructions, declared: agent.parameters ?? [] } };
+  }
+  const ref: PromptRef = agent.instructions;
+  return {
+    ok: false,
+    error: {
+      code: 'render-failure',
+      message: `The instructions come from prompt block "${ref.prompt}" (${ref.version}), which wasn't loaded`,
+      cause: null,
+    },
+  };
+}
+
 function requiredMissing(
   declared: readonly PromptParameter[],
   supplied: Readonly<Record<string, unknown>>,
@@ -181,5 +228,6 @@ function mergeContext(
     };
   }
   if (context.input !== undefined) values.input = context.input;
+  if (context.settings !== undefined) values.settings = context.settings;
   return values;
 }