@kindgi/agents 0.1.3 → 0.1.4-rc.1

package/src/define.ts

@@ -9,6 +9,7 @@ import {
   loadZodConverterSync,
   toJSONSchemaSync,
 } from '@kindgi/schema';
+import { pickVersion } from '@kindgi/tools';
 import type { Result, Semver } from '@kindgi/types';
 
 import type { InvalidAgentError } from './errors.js';
@@ -16,8 +17,10 @@ import type {
   Agent,
   AgentId,
   AgentOutputSpec,
+  BlockRef,
   ConversationPolicy,
   PromptParameter,
+  PromptRef,
   RetrievalIntent,
   ToolRef,
   TurnBudget,
@@ -48,9 +51,10 @@ export function defineAgent(spec: DefineAgentSpec): Result<Agent, InvalidAgentEr
   const issues: Issue[] = [
     ...validateIdentity(spec),
     ...validateContent(spec),
+    ...validateBlockRefs(spec),
     ...validateArrays(spec),
     ...validateRetrieval(spec),
-    ...validateParameters(spec.parameters),
+    ...validatePromptParameters(spec.parameters),
     ...validateBudget(spec.budget),
     ...validateConversationPolicy(spec.conversationPolicy),
     ...validateToolErrors(spec.toolErrors),
@@ -126,8 +130,16 @@ export interface DefineAgentSpec {
    * The system prompt. Sent to the model with every turn as the
    * baseline instructions. Load-bearing — this is where you shape
    * the agent's behavior (persona, output format, tool-use policy).
+   *
+   * Or a prompt block by range (`{ prompt: 'acme.intake-prompt',
+   * version: '^1.0.0' }`), whose template and parameters are used
+   * instead; then `parameters` stays unset (the block declares them).
    */
-  readonly instructions: string;
+  readonly instructions: string | PromptRef;
+  /** Settings blocks the agent reads, by range (see `Agent.settings`). */
+  readonly settings?: readonly BlockRef[];
+  /** A model-settings block, by range (see `Agent.modelSettings`). */
+  readonly modelSettings?: BlockRef;
   /**
    * Required capabilities the agent needs from a `ModelProvider`.
    * Typically one entry: `[{ needs: [{ feature: 'tool-use' }] }]`
@@ -248,8 +260,19 @@ function validateIdentity(spec: DefineAgentSpec): Issue[] {
 
 function validateContent(spec: DefineAgentSpec): Issue[] {
   const out: Issue[] = [];
-  if (typeof spec.instructions !== 'string' || spec.instructions.trim().length === 0) {
-    out.push({ path: '/instructions', message: 'instructions must be a non-empty string' });
+  if (typeof spec.instructions === 'object' && spec.instructions !== null) {
+    out.push(...blockRefIssues(spec.instructions, '/instructions', 'prompt'));
+    if (spec.parameters !== undefined) {
+      out.push({
+        path: '/parameters',
+        message: 'the prompt block declares the parameters: leave parameters unset',
+      });
+    }
+  } else if (typeof spec.instructions !== 'string' || spec.instructions.trim().length === 0) {
+    out.push({
+      path: '/instructions',
+      message: 'instructions must be a non-empty string, or a prompt block { prompt, version }',
+    });
   }
   if (!Array.isArray(spec.capabilities) || spec.capabilities.length === 0) {
     out.push({
@@ -260,6 +283,56 @@ function validateContent(spec: DefineAgentSpec): Issue[] {
   return out;
 }
 
+const BLOCK_ID = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/;
+
+/** A block reference: a dotted block id and a valid semver range. */
+function blockRefIssues(ref: unknown, path: string, idKey: 'prompt' | 'id'): Issue[] {
+  if (ref === null || typeof ref !== 'object') {
+    return [{ path, message: `must be { ${idKey}, version }` }];
+  }
+  const r = ref as Record<string, unknown>;
+  const out: Issue[] = [];
+  if (typeof r[idKey] !== 'string' || !BLOCK_ID.test(r[idKey] as string)) {
+    out.push({
+      path: `${path}/${idKey}`,
+      message: 'must be a dotted lowercase block id, e.g. "acme.weights"',
+    });
+  }
+  if (typeof r.version !== 'string' || pickVersion([], r.version).kind === 'invalid-range') {
+    out.push({
+      path: `${path}/version`,
+      message: 'must be a semver range, e.g. "^1.0.0" or "1.2.0"',
+    });
+  }
+  return out;
+}
+
+/** Settings and model-settings references: valid, and each block named once. */
+function validateBlockRefs(spec: DefineAgentSpec): Issue[] {
+  const out: Issue[] = [];
+  const seen = new Set<string>();
+  const once = (id: unknown, path: string) => {
+    if (typeof id !== 'string') return;
+    if (seen.has(id)) out.push({ path, message: `settings block "${id}" is referenced twice` });
+    seen.add(id);
+  };
+  if (spec.settings !== undefined) {
+    if (!Array.isArray(spec.settings)) {
+      out.push({ path: '/settings', message: 'settings must be an array of { id, version }' });
+    } else {
+      spec.settings.forEach((ref, i) => {
+        out.push(...blockRefIssues(ref, `/settings/${i}`, 'id'));
+        once((ref as { id?: unknown }).id, `/settings/${i}/id`);
+      });
+    }
+  }
+  if (spec.modelSettings !== undefined) {
+    out.push(...blockRefIssues(spec.modelSettings, '/modelSettings', 'id'));
+    once((spec.modelSettings as { id?: unknown }).id, '/modelSettings/id');
+  }
+  return out;
+}
+
 function validateArrays(spec: DefineAgentSpec): Issue[] {
   const out: Issue[] = [];
   if (!Array.isArray(spec.tools)) {
@@ -334,9 +407,10 @@ function validateIntent(intent: RetrievalIntent, i: number): Issue[] {
 }
 
 const VALID_PARAM_TYPES = new Set(['string', 'number', 'boolean', 'date']);
-const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation']);
+const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation', 'settings']);
 
-function validateParameters(parameters?: readonly PromptParameter[]): Issue[] {
+/** An agent's or a prompt block's declared parameters: the problems, none when they're valid. */
+export function validatePromptParameters(parameters?: readonly PromptParameter[]): Issue[] {
   if (parameters === undefined) return [];
   const out: Issue[] = [];
   const seen = new Set<string>();
@@ -566,7 +640,10 @@ function buildAgent(spec: DefineAgentSpec, output: AgentOutputSpec | undefined):
     version: spec.version as Semver,
     name: spec.name,
     ...(spec.description !== undefined && { description: spec.description }),
-    instructions: spec.instructions,
+    instructions:
+      typeof spec.instructions === 'string' ? spec.instructions : { ...spec.instructions },
+    ...(spec.settings !== undefined && { settings: spec.settings.map((r) => ({ ...r })) }),
+    ...(spec.modelSettings !== undefined && { modelSettings: { ...spec.modelSettings } }),
     capabilities: spec.capabilities.map((c) => ({ ...c })),
     tools: [...spec.tools],
     retrieval: spec.retrieval.map((r) => ({ ...r })),

package/src/handlers/compose-result.ts

@@ -8,6 +8,7 @@ import type { AgentTurnResult, AgentTurnUsage } from './result-shape.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { replayReport } from './replay.js';
 import { parseJsonAnswer } from './structured-output.js';
 
 /** The final answer as JSON — `budget-check` already validated it against the schema. */
@@ -45,6 +46,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       model: ctx.model?.name ?? 'unknown',
     };
 
+    const replay = replayReport(ctx);
     const result: AgentTurnResult = {
       runId: kctx.runId,
       conversationId: ctx.input.conversationId,
@@ -70,6 +72,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       }),
       ...(ctx.persistedProvenance !== undefined && { provenance: ctx.persistedProvenance }),
       ...(kctx.dryRun && { dryRun: true }),
+      ...(replay !== undefined && { replay }),
     };
 
     await emitTurnEvent(ctx.bindings.onEvent, {

package/src/handlers/context.ts

@@ -19,6 +19,7 @@ import type { ProvenanceBindings } from '../provenance-emit.js';
 import type { Agent, Conversation, ConversationMessage, RetrievedFact } from '../types.js';
 
 import type { HitlBindings, InvokeAgentBindings, InvokeAgentInput } from './public-types.js';
+import type { TurnBlocks } from './resolve-blocks.js';
 import type { ToolErrorPolicy } from './tool-errors.js';
 
 /**
@@ -53,6 +54,8 @@ export interface TurnContext {
    * Populated by `setup` — resolved tools (per-name map + model
    * definitions).
    */
+  /** The data blocks the turn runs with (set by setup; none when the agent references none). */
+  blocks?: TurnBlocks;
   tools?: {
     readonly definitions: readonly ModelToolDefinition[];
     /**
@@ -189,6 +192,13 @@ export interface TurnContext {
    * `AgentTurnResult.violations`.
    */
   nonBlockingViolations?: readonly EvaluationResult[];
+  /**
+   * A replay turn's tool calls so far, and what happened to each
+   * (`decideReplayTool`). Rebuilt from the journal on resume.
+   */
+  replayTrace?: import('./replay.js').ReplayToolTrace[];
+  /** A replay turn's session approval, when it reached the gate (`replaySessionApproval`). */
+  replayApproval?: 'followed' | 'skipped';
   /**
    * Reason recorded when `turnAbort` fires. Used to distinguish
    * external cancellation from wall-clock timeout in the projected

package/src/handlers/dispatch-tools.ts

@@ -20,6 +20,7 @@ import {
   throwAgentTurnFailure,
 } from './errors.js';
 import { TOOL_CALL_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
+import { decideReplayTool } from './replay.js';
 import {
   effectiveToolErrorPolicy,
   toolErrorKindOf,
@@ -244,6 +245,50 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
       // skip the reviewer's answer. Cross-turn `ask_on_first_use` caching
       // (via conversation metadata) is not implemented.
       const gate = await decideToolGate(ctx, kctx, call, tool);
+
+      // A replay turn decides the call first: a recorded or refused call
+      // runs nothing, so it asks for no approval either.
+      const replayed =
+        ctx.input.replay === undefined
+          ? undefined
+          : await decideReplayTool(ctx, kctx, {
+              step: partial.step,
+              callId: call.id,
+              tool,
+              version: resolvedVersion,
+              arguments: call.arguments,
+              gated: gate !== undefined,
+            });
+      if (replayed !== undefined && replayed.kind !== 'live') {
+        const replayStarted = Date.now();
+        await emitTurnEvent(ctx.bindings.onEvent, {
+          kind: 'tool.started',
+          step: partial.step,
+          toolId: call.name,
+          toolVersion: resolvedVersion,
+          toolVersionRange: requestedRange,
+          invocationId: call.id,
+          arguments: call.arguments,
+        });
+        nextMessages = await appendToolResult(ctx, call, replayed.result, {
+          toolId: tool.id as unknown as string,
+          nextMessages,
+          iterationAppended,
+        });
+        await emitTurnEvent(ctx.bindings.onEvent, {
+          kind: 'tool.completed',
+          step: partial.step,
+          toolId: call.name,
+          toolVersion: resolvedVersion,
+          toolVersionRange: requestedRange,
+          invocationId: call.id,
+          output: replayed.result as never,
+          durationMs: Date.now() - replayStarted,
+          replay: replayed.kind,
+        });
+        continue;
+      }
+
       let toolRejectionPayload: { readonly rationale?: string } | null = null;
       if (gate !== undefined) {
         const { argsHash, waitTokenId, timeoutMs } = gate;
@@ -376,6 +421,7 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         invocationId: call.id,
         output: dispatched.value.persisted.content,
         durationMs: Date.now() - toolStarted,
+        ...(replayed !== undefined && { replay: replayed.kind }),
       });
     }
 
@@ -495,7 +541,12 @@ async function appendToolResult(
   target.iterationAppended.push(persisted.value);
   return [
     ...target.nextMessages,
-    { role: 'tool', content: JSON.stringify(output), toolCallId: call.id },
+    {
+      role: 'tool',
+      // As a tool's own result reaches the model: a string as it is.
+      content: typeof output === 'string' ? output : JSON.stringify(output),
+      toolCallId: call.id,
+    },
   ];
 }
 
@@ -557,6 +608,8 @@ async function dispatchOne(
     // secret_refs at invoke time. Present iff the caller wired
     // `bindings.resolveSecret` from a tenant-scoped `SecretBinding`.
     ...(ctx.bindings.resolveSecret !== undefined && { resolveSecret: ctx.bindings.resolveSecret }),
+    // The pinned settings blocks' values, by block id.
+    ...(ctx.blocks !== undefined && { settings: ctx.blocks.settings }),
   };
   const result = await invokeTool(tool, call.arguments, toolCtx);
   if (result.kind === 'err') {

package/src/handlers/errors.ts

@@ -16,6 +16,7 @@ export type InvokeAgentError =
   | AgentError
   | UnresolvedToolError
   | ToolVersionUnresolvableError
+  | BlockUnresolvableError
   | CapabilityRoutingError
   | ModelInvocationError
   | ToolInvocationError
@@ -75,6 +76,18 @@ export interface ToolVersionUnresolvableError {
   readonly availableVersions?: readonly string[];
 }
 
+/**
+ * A data block the agent references can't be loaded: no version in its
+ * range, a pinned version that's gone, the wrong kind, model settings
+ * that aren't, or a runtime that serves no blocks.
+ */
+export interface BlockUnresolvableError {
+  readonly code: 'block-unresolvable';
+  readonly message: string;
+  readonly blockId: string;
+  readonly requestedRange?: string;
+}
+
 export interface CapabilityRoutingError {
   readonly code: 'capability-routing-failed';
   readonly message: string;

package/src/handlers/evaluate-guardrails.ts

@@ -18,6 +18,7 @@ import type { ConversationMessage } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { finalIteration } from './final-iteration.js';
+import { replayTag } from './replay.js';
 import { parseJsonAnswer } from './structured-output.js';
 
 /**
@@ -169,6 +170,7 @@ function judgeUsageSink(ctx: TurnContext, kctx: NodeContext): UsageSink | undefi
       sink.record({
         nodeId: kctx.nodeId as unknown as string,
         agentVersion: ctx.input.agent.version,
+        ...(ctx.input.replay !== undefined && { replay: replayTag(ctx.input.replay) }),
         ...call,
       }),
   };

package/src/handlers/model-call.ts

@@ -18,6 +18,7 @@ import { emitTurnEvent } from '../streaming.js';
 
 import type { AgentTurnIterationOutput, TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { replayTag } from './replay.js';
 import { addModelCallNode } from './turn-provenance.js';
 
 /**
@@ -83,6 +84,7 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
         ...(ctx.tools.definitions.length > 0 && {
           tools: ctx.tools.definitions,
         }),
+        ...modelSettingsOf(ctx),
         abortSignal: ctx.turnAbort.signal,
       };
 
@@ -251,6 +253,7 @@ async function recordCall(
     providerId: ctx.provider.metadata.id,
     model: ctx.model.name,
     ...(ctx.provider.metadata.fallback === true && { fallback: true }),
+    ...(input.replay !== undefined && { replay: replayTag(input.replay) }),
     occurredAt: new Date().toISOString(),
   });
   return recorded.kind === 'err' ? (recorded.error ?? new Error('no detail')) : undefined;
@@ -265,3 +268,14 @@ function describeCause(cause: unknown): string {
   if (text.length === 0) return cause instanceof Error ? cause.name : 'no detail';
   return text.length > MAX_CAUSE_CHARS ? `${text.slice(0, MAX_CAUSE_CHARS - 1)}…` : text;
 }
+
+/** The pinned model-settings block's values, as model-call fields; none when it has none. */
+function modelSettingsOf(
+  ctx: TurnContext,
+): Pick<ModelCallInput, 'temperature' | 'maxOutputTokens'> {
+  const settings = ctx.blocks?.modelSettings;
+  return {
+    ...(settings?.temperature !== undefined && { temperature: settings.temperature }),
+    ...(settings?.maxOutputTokens !== undefined && { maxOutputTokens: settings.maxOutputTokens }),
+  };
+}

package/src/handlers/public-types.ts

@@ -6,10 +6,11 @@ import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabili
 import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
 import type { MemoryQueryBinding } from '@kindgi/memory';
 import type { PolicyRegistry } from '@kindgi/policy-contract';
-import type { ParentRunRef, RunBinding } from '@kindgi/runtime';
+import type { ParentRunRef, RunBinding, RunReplayRef } from '@kindgi/runtime';
 import type { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
 import type { OrgId, ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
+import type { BlockReader } from '../blocks.js';
 import type { ConversationBinding } from '../conversation-binding.js';
 import type { GuardrailsBindings } from '../guardrails-gate.js';
 import type { ProvenanceBindings } from '../provenance-emit.js';
@@ -17,6 +18,8 @@ import type { RunSnapshotBinding } from '../run-snapshot-binding.js';
 import type { OnTurnEvent } from '../streaming.js';
 import type { Agent, ConversationId } from '../types.js';
 
+import type { ReplayBinding } from './replay.js';
+
 /**
  * The user-facing input to `invokeAgent`. Split out from `invoke.ts` so
  * the handler modules can depend on the shape without pulling in the
@@ -54,6 +57,13 @@ export interface InvokeAgentInput {
    * step. Recorded on the turn's run, so the flow can find its child.
    */
   readonly parent?: ParentRunRef;
+  /**
+   * Marks the turn as a replay: an eval run re-running a past run (`of`)
+   * on this agent version. Recorded on the turn's run and in its snapshot.
+   * Its tool calls are decided by `InvokeAgentBindings.replay` (every call
+   * is refused when that isn't wired), and only a read-only tool can run.
+   */
+  readonly replay?: RunReplayRef;
   readonly participantId?: string;
   readonly abortSignal?: AbortSignal;
   /**
@@ -101,6 +111,12 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
    * sees another tenant's tools.
    */
   readonly toolRegistry: ToolRegistry;
+  /**
+   * Data blocks (prompts and settings). Setup loads the blocks the agent
+   * references at their pinned versions. Optional: an agent that
+   * references blocks fails its turn (`block-unresolvable`) without it.
+   */
+  readonly blockReader?: BlockReader;
   /**
    * Caller-plugged data-access surface for memory reads.
    * The Kindgi runtime supplies a Postgres-backed implementation;
@@ -175,6 +191,11 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
    * unaffected.
    */
   readonly resolveSecret?: (ref: ToolSecretRef) => Promise<string>;
+  /**
+   * How replay turns (`InvokeAgentInput.replay`) decide their tool calls,
+   * retrievals and session approval. Consulted only for a replay turn.
+   */
+  readonly replay?: ReplayBinding;
 }
 
 export interface HitlBindings {

package/src/handlers/rehydrate.ts

@@ -10,7 +10,9 @@
  *
  *   - the environment — conversation, approval rules, guardrails, tools,
  *     policies — is resolved again, routed to the provider and model
- *     `setup` journaled;
+ *     `setup` journaled, with the tool versions it journaled (a range
+ *     isn't resolved again: a version published meanwhile doesn't run
+ *     mid-turn);
  *   - the messages the turn stored come back from the conversation, from
  *     the turn's user message (`persist-user-message` journals its
  *     sequence);
@@ -46,6 +48,8 @@ import type { ConversationMessage, RetrievedFact } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
 import { readGateDecision } from './gate-decision.js';
+import { rehydrateReplay } from './replay.js';
+import type { PinnedBlockVersions } from './resolve-blocks.js';
 import { TOOL_GATE_RECORD_PREFIX } from './tool-hitl.js';
 import {
   loadTurnConversation,
@@ -107,10 +111,12 @@ export async function rehydrateTurnContext(
   journal: readonly JournalEntry[],
 ): Promise<boolean> {
   const steps = completedSteps(journal);
-  const setup = outputOf<{ readonly providerId: string; readonly providerModel: string }>(
-    steps,
-    'setup',
-  );
+  const setup = outputOf<{
+    readonly providerId: string;
+    readonly providerModel: string;
+    readonly toolVersions?: Readonly<Record<string, string>>;
+    readonly blockVersions?: PinnedBlockVersions;
+  }>(steps, 'setup');
   if (setup === undefined) return false;
 
   if (ctx.bindings.provenance?.newBuilder !== undefined) {
@@ -119,7 +125,15 @@ export async function rehydrateTurnContext(
   }
   await loadTurnConversation(ctx);
   ctx.hitlPolicy = await resolveTurnHitlPolicy(ctx);
-  await resolveTurnEnvironment(ctx, { providerId: setup.providerId, model: setup.providerModel });
+  // The route and the tool versions `setup` resolved: a resumed turn
+  // runs those, never a range resolved again (a journal from before
+  // `toolVersions` was recorded resolves the ranges, as it did).
+  await resolveTurnEnvironment(
+    ctx,
+    { providerId: setup.providerId, model: setup.providerModel },
+    setup.toolVersions,
+    setup.blockVersions,
+  );
 
   const userMessage = outputOf<{ readonly sequence: number }>(steps, 'persist-user-message');
   if (userMessage !== undefined) {
@@ -151,6 +165,7 @@ export async function rehydrateTurnContext(
   }
   ctx.toolApprovals = toolApprovalsOf(journal);
   rebuildProvenance(ctx, steps, retrievals?.retrieved);
+  rehydrateReplay(ctx, journal);
   return true;
 }
 

package/src/handlers/render-prompt.ts

@@ -25,14 +25,20 @@ export function buildRenderPromptHandler(ctx: TurnContext): NodeHandler {
         cause: null,
       });
     }
-    const rendered = renderInstructions(ctx.input.agent, {
-      parameters: ctx.input.parameters ?? {},
-      ...(ctx.input.input !== undefined && { input: ctx.input.input }),
-      conversation: {
-        id: ctx.input.conversationId,
-        turn: ctx.conversation.turnCount + 1,
+    const rendered = renderInstructions(
+      ctx.input.agent,
+      {
+        parameters: ctx.input.parameters ?? {},
+        ...(ctx.input.input !== undefined && { input: ctx.input.input }),
+        conversation: {
+          id: ctx.input.conversationId,
+          turn: ctx.conversation.turnCount + 1,
+        },
+        ...(ctx.blocks !== undefined && { settings: ctx.blocks.settings }),
       },
-    });
+      // The pinned prompt block, when the instructions come from one.
+      ctx.blocks?.prompt?.content,
+    );
     if (!rendered.ok) {
       throwAgentTurnFailure({
         code: 'model-invocation-failed',