@kindgi/agents 0.1.3 → 0.1.4-rc.0

package/src/handlers/run-retrievals.ts

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { NodeHandler } from '@kindgi/handler';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
 
 import { runRetrievals } from '../retrieval.js';
 import { emitTurnEvent } from '../streaming.js';
+import type { RetrievedFact } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
@@ -17,7 +18,7 @@ import { addRetrievalNodes } from './turn-provenance.js';
  * is wired.
  */
 export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
-  return async () => {
+  return async (_input, kctx) => {
     if (ctx.conversation === undefined || ctx.userMessage === undefined) {
       throwAgentTurnFailure({
         code: 'model-invocation-failed',
@@ -25,36 +26,56 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
         cause: null,
       });
     }
-    const retrieved = await runRetrievals(
-      ctx.input.agent,
-      ctx.conversation,
-      ctx.input.conversationId,
-      ctx.input.userMessage,
-      {
-        memory: ctx.bindings.memoryBinding,
-        ...(ctx.bindings.embeddingRegistry !== undefined && {
-          embeddingRegistry: ctx.bindings.embeddingRegistry,
-        }),
-        ...(ctx.bindings.embeddingModel !== undefined && {
-          embeddingModel: ctx.bindings.embeddingModel,
-        }),
-      },
-    );
-    if (retrieved.kind === 'err') throwAgentTurnFailure(retrieved.error);
-    ctx.retrieved = retrieved.value;
+    const facts = (await recordedRetrievals(ctx, kctx)) ?? (await retrieveLive(ctx));
+    ctx.retrieved = facts;
 
     await emitTurnEvent(ctx.bindings.onEvent, {
       kind: 'retrieval.completed',
-      count: retrieved.value.length,
-      factIds: retrieved.value.map((r) => r.fact.id),
+      count: facts.length,
+      factIds: facts.map((r) => r.fact.id),
     });
 
     if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-      addRetrievalNodes(ctx.provenance, retrieved.value, ctx.userMessage);
+      addRetrievalNodes(ctx.provenance, facts, ctx.userMessage);
     }
 
     // The facts go in the journal: a resumed turn restores them from it
     // (`rehydrateTurnContext`) rather than retrieving again.
-    return { count: retrieved.value.length, retrieved: retrieved.value };
+    return { count: facts.length, retrieved: facts };
   };
 }
+
+/** A replay's retrievals: what the past run retrieved, when the replay binding has it. */
+async function recordedRetrievals(
+  ctx: TurnContext,
+  kctx: NodeContext,
+): Promise<readonly RetrievedFact[] | undefined> {
+  const replay = ctx.input.replay;
+  if (replay === undefined || ctx.bindings.replay?.retrievals === undefined) return undefined;
+  return ctx.bindings.replay.retrievals({
+    tenantId: ctx.input.tenantId,
+    runId: kctx.runId,
+    replay,
+  });
+}
+
+async function retrieveLive(ctx: TurnContext): Promise<readonly RetrievedFact[]> {
+  if (ctx.conversation === undefined) return [];
+  const retrieved = await runRetrievals(
+    ctx.input.agent,
+    ctx.conversation,
+    ctx.input.conversationId,
+    ctx.input.userMessage,
+    {
+      memory: ctx.bindings.memoryBinding,
+      ...(ctx.bindings.embeddingRegistry !== undefined && {
+        embeddingRegistry: ctx.bindings.embeddingRegistry,
+      }),
+      ...(ctx.bindings.embeddingModel !== undefined && {
+        embeddingModel: ctx.bindings.embeddingModel,
+      }),
+    },
+  );
+  if (retrieved.kind === 'err') throwAgentTurnFailure(retrieved.error);
+  return retrieved.value;
+}

package/src/handlers/run-snapshot.ts

@@ -40,5 +40,6 @@ export async function writeRunSnapshot(ctx: TurnContext, kctx: NodeContext): Pro
     ...(ctx.input.dryRun === true && { dryRun: true }),
     ...(ctx.input.principal !== undefined && { principal: ctx.input.principal }),
     ...(ctx.input.authz !== undefined && { authz: ctx.input.authz }),
+    ...(ctx.input.replay !== undefined && { replay: ctx.input.replay }),
   });
 }

package/src/handlers/setup.ts

@@ -12,6 +12,7 @@ import { emitTurnEvent } from '../streaming.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { SESSION_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
+import { followReplaySessionGate } from './replay.js';
 import { writeRunSnapshot } from './run-snapshot.js';
 import {
   loadTurnConversation,
@@ -37,7 +38,7 @@ function computeSessionGateWaitToken(input: {
 }
 
 /** The `record` key of the session gate's decision. */
-const SESSION_GATE_RECORD = 'session-hitl-gate';
+export const SESSION_GATE_RECORD = 'session-hitl-gate';
 
 /**
  * The session gate's decision, as `setup` records it the first time
@@ -140,7 +141,11 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
         timeoutMs: effectiveHitl.timeoutMs,
       };
     });
-    if (gate !== undefined) {
+    if (gate !== undefined && ctx.input.replay !== undefined) {
+      // A replay follows the past run's decision at this gate, or skips it
+      // when none was recorded; it never waits for a reviewer.
+      await followReplaySessionGate(ctx, kctx);
+    } else if (gate !== undefined) {
       const { waitTokenId, timeoutMs } = gate;
       const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
 
@@ -290,6 +295,12 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
       providerId: environment.providerId,
       providerModel: environment.model,
       toolCount: environment.toolCount,
+      // The version each tool resolved to: a resumed turn runs these.
+      toolVersions: environment.toolVersions,
+      // And each data block's.
+      ...(environment.blockVersions !== undefined && {
+        blockVersions: environment.blockVersions,
+      }),
     };
   };
 }

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/index.ts

@@ -17,6 +17,22 @@ 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 {
@@ -28,6 +44,17 @@ export {
 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,
@@ -87,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 {
@@ -105,12 +140,14 @@ export type {
   AgentBindings,
   AgentId,
   AgentOutputSpec,
+  BlockRef,
   Conversation,
   ConversationId,
   ConversationMessage,
   ConversationPolicy,
   MessageRole,
   PromptParameter,
+  PromptRef,
   RetrievalIntent,
   RetrievedFact,
   ToolRef,

package/src/invoke.ts

@@ -90,6 +90,8 @@ export async function invokeAgent(
         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.
@@ -323,5 +325,6 @@ export function turnInputFromSnapshot(
       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;
 }

package/src/run-snapshot-binding.ts

@@ -3,6 +3,8 @@
 
 import type { ProjectId, Result, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
+import type { RunReplayRef } from '@kindgi/runtime';
+
 import type { PersistenceError } from './errors.js';
 import type { AgentId, ConversationId } from './types.js';
 
@@ -37,6 +39,8 @@ export interface RunSnapshotWriteInput {
    * as `principal`.
    */
   readonly authz?: unknown;
+  /** The turn's replay marker (`InvokeAgentInput.replay`): a resumed replay stays one. */
+  readonly replay?: RunReplayRef;
 }
 
 /**
@@ -59,6 +63,8 @@ export interface RunSnapshotRecord {
   readonly dryRun: boolean;
   readonly principal?: unknown;
   readonly authz?: unknown;
+  /** The turn's replay marker (`InvokeAgentInput.replay`): a resumed replay stays one. */
+  readonly replay?: RunReplayRef;
   readonly createdAt: Timestamp;
 }
 

package/src/schema.ts

@@ -148,6 +148,11 @@ export const agentRunSnapshots = pgTable(
      * Threaded back into the resumed TurnContext.
      */
     authz: jsonb('authz'),
+    /**
+     * The replay marker (`{of, evalRunId}`) of a replay turn, so a resumed
+     * replay stays one: its tool calls are still decided by the replay rules.
+     */
+    replay: jsonb('replay'),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },
   (t) => ({

package/src/streaming.ts

@@ -86,6 +86,11 @@ export interface ToolCompletedEvent {
   readonly invocationId: string;
   readonly output: unknown;
   readonly durationMs: number;
+  /**
+   * In a replay turn: whether the tool ran (`live`), the past run's result
+   * was used (`recorded`), or the call was refused (`refused`).
+   */
+  readonly replay?: 'live' | 'recorded' | 'refused';
 }
 
 export interface ToolFailedEvent {

package/src/types.ts

@@ -6,6 +6,8 @@ import type { Fact, MemoryScope } from '@kindgi/memory';
 import type { ToolErrorsSpec, ToolHitlMode, ToolHitlRule } from '@kindgi/policy-contract';
 import type { Brand, ConversationId, ProjectId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
+import type { AgentDerivation, AgentPins } from './pins.js';
+
 /**
  * Branded agent id. Convention: dotted namespace under the tenant's
  * pack — e.g. `acme.citation-verifier`, `acme.drafting`.
@@ -121,6 +123,22 @@ export interface ToolRef {
   readonly version: string;
 }
 
+/**
+ * A prompt block an agent's instructions come from: its id and a semver
+ * range, resolved like a tool's (`pickVersion`) and pinned when the
+ * agent version is published.
+ */
+export interface PromptRef {
+  readonly prompt: string;
+  readonly version: string;
+}
+
+/** A settings block an agent reads: its id and a semver range, pinned at publish. */
+export interface BlockRef {
+  readonly id: string;
+  readonly version: string;
+}
+
 /**
  * Per-agent behavior for multi-turn conversations. The agent chooses:
  *   - How many prior messages to load (`historyLimit`; unset = all).
@@ -292,8 +310,13 @@ export interface Agent {
    * unresolved reference fails the turn at invoke time
    * (`model-invocation-failed` whose `cause` is the `missing-parameter`
    * render error), never a silent empty string.
+   *
+   * Or a prompt block, by range (`{ prompt: 'acme.intake-prompt',
+   * version: '^1.0.0' }`): its template renders here instead, with the
+   * parameters it declares, and the version that runs is pinned when the
+   * agent version is published (`pins.prompts`).
    */
-  readonly instructions: string;
+  readonly instructions: string | PromptRef;
   /**
    * Typed parameters the caller supplies at invoke time. The UI reads
    * this to build a "configure agent" form; the runtime validates each
@@ -405,6 +428,35 @@ export interface Agent {
    * A tenant's `tool-errors` policy can lower it. See `ToolErrorsSpec`.
    */
   readonly toolErrors?: ToolErrorsSpec;
+  /**
+   * The exact block versions this agent version runs, resolved by the
+   * runtime when the version was published (see `AgentPins`). Never
+   * authored: `defineAgent` doesn't take it. Absent on an agent defined
+   * in code and on a version published before pins existed; its tool
+   * ranges then resolve per run.
+   */
+  readonly pins?: AgentPins;
+  /**
+   * Settings blocks the agent reads, by range. Each block's values reach
+   * its tools as `ToolContext.settings[<block id>]` and its templates as
+   * `settings.<block id>.<key>`; the versions are pinned at publish
+   * (`pins.settings`).
+   */
+  readonly settings?: readonly BlockRef[];
+  /**
+   * A settings block of model settings (`MODEL_SETTINGS_SCHEMA`:
+   * `temperature`, `maxOutputTokens`) the turn's model calls use. Pinned
+   * at publish with the other settings.
+   */
+  readonly modelSettings?: BlockRef;
+  /** `pinsDigest(pins)`, recorded when the version was published. */
+  readonly pinsDigest?: string;
+  /**
+   * Set by the runtime on a version it registered under another number
+   * than the definition's, when a deploy couldn't register that number
+   * as it was (see `AgentDerivation`). Never authored.
+   */
+  readonly derivedFrom?: AgentDerivation;
 }
 
 /**