@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/src/handlers/persist-final-message.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+import type { NodeId, Timestamp } from '@kindgi/types';
+
+import { AGENT_LOOP_NODE } from '../agent-turn-flow.js';
+import { emitTurnEvent } from '../streaming.js';
+import type { ConversationMessage } from '../types.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { finalIteration } from './final-iteration.js';
+
+/**
+ * Persist the turn's terminal assistant message (non-intermediate —
+ * increments `turnCount`). Runs after `evaluate-guardrails`, so only a
+ * response that no `halt` guardrail rejected is stored. Reads the
+ * response from the agent loop's output.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1`. `turnCount` is NOT
+ * incremented (no persistence happened).
+ */
+export function buildPersistFinalMessageHandler(ctx: TurnContext): NodeHandler {
+  return async (_input: unknown, kctx) => {
+    const final = finalIteration(
+      kctx.nodeOutputs.get(AGENT_LOOP_NODE as NodeId),
+      'persist-final-message',
+    );
+
+    const assistantMsg = final.message;
+
+    let finalMessage: ConversationMessage;
+    if (kctx.dryRun) {
+      finalMessage = {
+        sequence: -1,
+        role: 'agent',
+        content: assistantMsg.content ?? '',
+        createdAt: new Date().toISOString() as Timestamp,
+        actor: ctx.input.agent.id,
+      };
+    } else {
+      const persist = await ctx.bindings.conversationBinding.appendMessage({
+        tenantId: ctx.input.tenantId,
+        conversationId: ctx.input.conversationId,
+        role: 'agent',
+        content: assistantMsg.content ?? '',
+        actor: ctx.input.agent.id,
+      });
+      if (persist.kind === 'err') throwAgentTurnFailure(persist.error);
+      finalMessage = persist.value;
+    }
+
+    ctx.appended.push(finalMessage);
+    ctx.finalMessage = finalMessage;
+
+    await emitTurnEvent(ctx.bindings.onEvent, {
+      kind: 'agent.message',
+      step: ctx.usage.steps,
+      isFinal: true,
+      message: finalMessage,
+    });
+
+    return { sequence: finalMessage.sequence };
+  };
+}

package/src/handlers/persist-provenance.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+
+import { persistProvenance } from '../provenance-emit.js';
+
+import type { TurnContext } from './context.js';
+
+/**
+ * Persist the completed provenance DAG. Best-effort: a persistence
+ * failure here does NOT fail the run (the turn already succeeded and
+ * the DAG was built in memory); the result then carries no
+ * `provenance`.
+ *
+ * Skipped entirely when no provenance builder was wired.
+ */
+export function buildPersistProvenanceHandler(ctx: TurnContext): NodeHandler {
+  return async (_input, kctx) => {
+    if (ctx.provenance === undefined || ctx.provenanceBindings === undefined) {
+      return { persisted: false };
+    }
+    if (kctx.dryRun) {
+      // Dry-run: DAG was built in-memory; skip the write. The
+      // returned `AgentTurnResult.provenance` is left undefined
+      // (unpersisted provenance is not surfaced on the result —
+      // callers can inspect the in-memory builder via bindings if they
+      // want).
+      return { persisted: false };
+    }
+    const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings);
+    if (persisted.kind === 'ok') {
+      ctx.persistedProvenance = persisted.value;
+      return { persisted: true };
+    }
+    // Silently swallow — persistence is best-effort (see above).
+    return { persisted: false };
+  };
+}

package/src/handlers/persist-user-message.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+import type { Timestamp } from '@kindgi/types';
+
+import type { ConversationMessage } from '../types.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/**
+ * Persist the caller's user message BEFORE the model is called. A
+ * crash mid-turn leaves the question intact for a later replay. Also
+ * seeds the provenance DAG with the `input:<sequence>` node — every
+ * subsequent model/tool node ties back through that root.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1` (sentinel — real sequences
+ * are always ≥ 0). Provenance node is still seeded so downstream
+ * dry-run handlers can build a plausible plan DAG.
+ */
+export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
+  return async (_input, kctx) => {
+    if (kctx.dryRun) {
+      const synthetic: ConversationMessage = {
+        sequence: -1,
+        role: 'user',
+        content: ctx.input.userMessage,
+        createdAt: new Date().toISOString() as Timestamp,
+        ...(ctx.input.participantId !== undefined && { actor: ctx.input.participantId }),
+      };
+      ctx.userMessage = synthetic;
+      ctx.appended.push(synthetic);
+
+      if (ctx.provenance !== undefined) {
+        ctx.provenance.addNode({
+          id: `input:${synthetic.sequence}`,
+          kind: 'input',
+          timestamp: synthetic.createdAt,
+          ...(synthetic.actor !== undefined && { actor: synthetic.actor }),
+        });
+      }
+      return { sequence: synthetic.sequence };
+    }
+
+    const persisted = await ctx.bindings.conversationBinding.appendMessage({
+      tenantId: ctx.input.tenantId,
+      conversationId: ctx.input.conversationId,
+      role: 'user',
+      content: ctx.input.userMessage,
+      ...(ctx.input.participantId !== undefined && { actor: ctx.input.participantId }),
+    });
+    if (persisted.kind === 'err') throwAgentTurnFailure(persisted.error);
+
+    ctx.userMessage = persisted.value;
+    ctx.appended.push(persisted.value);
+
+    if (ctx.provenance !== undefined) {
+      ctx.provenance.addNode({
+        id: `input:${persisted.value.sequence}`,
+        kind: 'input',
+        timestamp: persisted.value.createdAt,
+        ...(persisted.value.actor !== undefined && { actor: persisted.value.actor }),
+      });
+    }
+
+    return { sequence: persisted.value.sequence };
+  };
+}

package/src/handlers/public-types.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Principal } from '@kindgi/authz';
+import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+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 { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
+import type { ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
+
+import type { ConversationBinding } from '../conversation-binding.js';
+import type { GuardrailsBindings } from '../guardrails-gate.js';
+import type { ProvenanceBindings } from '../provenance-emit.js';
+import type { RunSnapshotBinding } from '../run-snapshot-binding.js';
+import type { OnTurnEvent } from '../streaming.js';
+import type { Agent, ConversationId } from '../types.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
+ * orchestration entrypoint (would cause a circular import).
+ */
+export interface InvokeAgentInput {
+  readonly tenantId: TenantId;
+  /**
+   * Content-scope anchor. REQUIRED — every
+   * agent turn is a run bound to exactly one project inside the
+   * tenant. Callers without a natural project id resolve to the tenant's
+   * Default via `projectBinding.getDefault(tenantId)` (`@kindgi/api`)
+   * at the caller layer.
+   */
+  readonly projectId: ProjectId;
+  readonly agent: Agent;
+  readonly conversationId: ConversationId;
+  readonly userMessage: string;
+  readonly parameters?: Readonly<Record<string, string | number | boolean>>;
+  /**
+   * Structured input for this turn — what a flow step hands its agent.
+   * Available to the instructions as `{{ input.* }}`, kept in the run
+   * snapshot for resume, and passed to guardrails as
+   * `trace.attributes.stepInput`.
+   */
+  readonly input?: unknown;
+  /**
+   * The flow run and node that started this turn, when it is a flow
+   * step. Recorded on the turn's run, so the flow can find its child.
+   */
+  readonly parent?: ParentRunRef;
+  readonly participantId?: string;
+  readonly abortSignal?: AbortSignal;
+  /**
+   * When `true`, executes the turn as a plan preview: no side effects
+   * to the conversation, memory, or provenance. Retrievals + guardrails
+   * still run for real (pure reads); the model call is skipped and
+   * returns a fixed mock response with no tool calls, so no tools run;
+   * every `persist-*` node skips its write. The returned
+   * `AgentTurnResult` carries `dryRun: true`, and the underlying run is
+   * journaled as a dry run.
+   */
+  readonly dryRun?: boolean;
+  /**
+   * Authorization — the Principal on whose authority this agent turn
+   * runs. When set together with `authz`, the underlying run checks
+   * every tool invocation (and subgraph dispatch, if any) against this
+   * principal at its enforcement point.
+   *
+   * Typical caller construction:
+   *   principal = delegate(
+   *     { kind: 'agent', id: input.agent.id, tenantId },
+   *     userPrincipalFromSession
+   *   )
+   * — establishes the confused-deputy-safe intersection semantic.
+   *
+   * Absent = tool invocations are not authorization-checked.
+   */
+  readonly principal?: Principal;
+  readonly authz?: {
+    readonly fgaApiUrl: string;
+  };
+}
+
+export interface InvokeAgentBindings extends GuardrailsBindings {
+  /**
+   * Model providers. Setup hydrates the tenant's providers (when the
+   * registry supports it) and routes the agent's first capability over
+   * `list(tenantId)` under the merged tenant policy; llm-judge
+   * guardrails route through it too.
+   */
+  readonly providerRegistry: ProviderRegistry;
+  /**
+   * Tools. Setup calls `forTenant(tenantId)` and resolves the agent's
+   * tool refs on the returned tenant-bound registry, so a turn never
+   * sees another tenant's tools.
+   */
+  readonly toolRegistry: ToolRegistry;
+  /**
+   * Caller-plugged data-access surface for memory reads.
+   * The Kindgi runtime supplies a Postgres-backed implementation;
+   * any object satisfying the interface works (tests, custom stores).
+   * Retrieval (listFacts / searchByKeyword / searchBySemantic) inside
+   * the agent runtime routes through this binding — the runtime never
+   * touches a database client directly for memory operations.
+   */
+  readonly memoryBinding: MemoryQueryBinding;
+  /**
+   * Caller-plugged conversation store. Every open / get / list /
+   * close / delete / appendMessage / readMessages inside the agent
+   * runtime routes through this binding — the runtime never touches
+   * a database client directly for conversation ops. The Kindgi runtime
+   * supplies a Postgres-backed implementation; any conforming object
+   * works. Required.
+   */
+  readonly conversationBinding: ConversationBinding;
+  /**
+   * Caller-plugged run-snapshot store. Writes the reconstruction
+   * envelope on run-start (idempotent under replay); reads it
+   * on `resumeAgentTurn` to rebuild the suspended TurnContext.
+   * The Kindgi runtime supplies a
+   * Postgres-backed implementation; any conforming object works. Required.
+   */
+  readonly runSnapshotBinding: RunSnapshotBinding;
+  /**
+   * Run-lifecycle binding (`RunBinding` from `@kindgi/runtime`). Every
+   * agent turn spawns a `runGraph` (or `resumeRun`) through it. The
+   * Kindgi runtime supplies an implementation; a bespoke one can be
+   * plugged in.
+   *
+   * Optional in the type, but `invokeAgent` and `resumeAgentTurn`
+   * throw when it is missing — every caller MUST supply it.
+   */
+  readonly runBinding?: RunBinding;
+  /**
+   * Statically-injected tenant policy for model routing. When a
+   * `policyRegistry` also yields a policy, the two are MERGED so the
+   * result is at least as strict as each: allow lists intersect, deny
+   * lists union, cost/token caps take the smaller value.
+   *
+   * Absent-and-registry-absent = router runs without any tenant policy.
+   */
+  readonly tenantPolicy?: TenantPolicy;
+  /**
+   * Optional policy registry. When present, the agent setup step calls
+   * `policyRegistry.evaluate('model-routing', {tenantId})` and merges
+   * the result with `tenantPolicy` before routing. Without a registry
+   * (or without an executor for that kind), `tenantPolicy` applies
+   * alone.
+   */
+  readonly policyRegistry?: PolicyRegistry;
+  readonly embeddingRegistry?: EmbeddingProviderRegistry;
+  readonly embeddingModel?: string;
+  readonly onEvent?: OnTurnEvent;
+  readonly provenance?: ProvenanceBindings;
+  readonly hitl?: HitlBindings;
+  /**
+   * Declarative HTTP tools: optional secret resolver populated
+   * from the deployment's tenant-scoped `SecretBinding`. When present,
+   * `dispatch-tools` threads it into every `ToolContext` so
+   * declarative HTTP tools (spec kind 'http') can resolve declared `secret_ref`s at
+   * invoke time. Absent → HTTP tools that declare `authorization`
+   * throw a clear "resolveSecret is not wired" error; native tools
+   * unaffected.
+   */
+  readonly resolveSecret?: (ref: ToolSecretRef) => Promise<string>;
+}
+
+export interface HitlBindings {
+  readonly enqueue: (input: HitlEnqueueInput) => Promise<HitlEnqueueResult>;
+}
+
+export interface HitlEnqueueInput {
+  readonly tenantId: TenantId;
+  readonly subjectKind: string;
+  readonly subjectRef: Readonly<Record<string, unknown>>;
+  readonly requiredRole?: 'standard' | 'senior' | 'admin';
+  readonly title?: string;
+  readonly description?: string;
+  readonly context?: Readonly<Record<string, unknown>>;
+  /**
+   * Waitpoint token this approval resolves on approve/reject
+   * (park-and-resume). The session gate (setup handler) and the tool
+   * gate (dispatch-tools handler) compute it as a deterministic hash —
+   * of (runId, gate scope, turnCount) and of (runId, callId, argsHash)
+   * respectively. Enqueue is idempotent on this — handler replay is
+   * safe.
+   */
+  readonly waitTokenId?: string;
+  /**
+   * Provenance reference for the parent run. Required for the
+   * approvals-complete route to invoke `completeToken(runId, ...)` +
+   * `resumeRun(runId)` on decision. Absent = the approval decides in
+   * place, no waitpoint resolution.
+   */
+  readonly provenanceRef?: {
+    readonly runId: RunId;
+    readonly provenanceId?: ProvenanceId;
+  };
+  /**
+   * Absolute deadline surfaced to reviewers; an approval still pending
+   * after it can be expired. Materialized at enqueue time from the
+   * effective HITL policy's `timeoutMs`.
+   */
+  readonly expiresAt?: Timestamp;
+}
+
+export interface HitlEnqueueResult {
+  readonly approvalId: string;
+}

package/src/handlers/rehydrate.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Rebuild a resumed turn's in-memory context. The turn's handlers keep
+ * what they resolve and accumulate on the `TurnContext`, and the kernel
+ * doesn't re-run a step that completed before the park — so a turn
+ * parked after `setup` (on a tool-call approval) would resume with none
+ * of it. From the durable record:
+ *
+ *   - the environment — conversation, approval rules, guardrails, tools,
+ *     policies — is resolved again, routed to the provider and model
+ *     `setup` journaled;
+ *   - the messages the turn stored come back from the conversation, from
+ *     the turn's user message (`persist-user-message` journals its
+ *     sequence);
+ *   - the retrieved facts come from `run-retrievals`' journaled output;
+ *   - usage is summed from the journaled model calls, so the step and
+ *     cost budgets count the whole turn.
+ *
+ * The loop's steps that completed aren't run again either: the runtime
+ * hands each its journaled result (`DerivedRunState.completedBodySteps`
+ * in `@kindgi/runtime`). The step the turn parked in
+ * (`dispatch-tools`, on the approval) runs again, and reuses the messages
+ * it already stored (`TurnContext.storedBeforePark`).
+ *
+ * A turn parked inside `setup` (the session gate) re-runs `setup`, and
+ * nothing here applies.
+ *
+ * Not restored: provenance nodes recorded before the park. The resumed
+ * turn's provenance covers what happens from the resume on.
+ */
+
+import type { LoopContext } from '@kindgi/handler';
+import { type JournalEntry, bodyStepKey } from '@kindgi/runtime';
+
+import type { ConversationMessage, RetrievedFact } from '../types.js';
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+import {
+  loadTurnConversation,
+  resolveTurnEnvironment,
+  resolveTurnHitlPolicy,
+} from './turn-environment.js';
+
+interface StepRecord {
+  readonly nodeId: string;
+  readonly output: unknown;
+  readonly inLoop: boolean;
+}
+
+/** Each step's last completion — a step at one loop iteration counts once. */
+function completedSteps(journal: readonly JournalEntry[]): readonly StepRecord[] {
+  const byStep = new Map<string, StepRecord>();
+  for (const e of journal) {
+    if (e.kind !== 'step.completed' || e.nodeId === undefined) continue;
+    const payload = (e.payload ?? {}) as {
+      readonly output?: unknown;
+      readonly loopContext?: LoopContext;
+    };
+    const key =
+      payload.loopContext === undefined
+        ? (e.nodeId as unknown as string)
+        : bodyStepKey(e.nodeId, payload.loopContext);
+    byStep.delete(key);
+    byStep.set(key, {
+      nodeId: e.nodeId as unknown as string,
+      output: payload.output,
+      inLoop: payload.loopContext !== undefined,
+    });
+  }
+  return [...byStep.values()];
+}
+
+/** The output of an outer step that completed, if it did. */
+function outputOf<T>(steps: readonly StepRecord[], nodeId: string): T | undefined {
+  return steps.find((s) => s.nodeId === nodeId && !s.inLoop)?.output as T | undefined;
+}
+
+/**
+ * Restore `ctx` for a turn being resumed. Returns `false` when `setup`
+ * hasn't completed (it will run, and resolve everything itself).
+ */
+export async function rehydrateTurnContext(
+  ctx: TurnContext,
+  runId: string,
+  journal: readonly JournalEntry[],
+): Promise<boolean> {
+  const steps = completedSteps(journal);
+  const setup = outputOf<{ readonly providerId: string; readonly providerModel: string }>(
+    steps,
+    'setup',
+  );
+  if (setup === undefined) return false;
+
+  if (ctx.bindings.provenance?.newBuilder !== undefined) {
+    ctx.provenance = ctx.bindings.provenance.newBuilder({ runId, tenantId: ctx.input.tenantId });
+    ctx.provenanceBindings = ctx.bindings.provenance;
+  }
+  await loadTurnConversation(ctx);
+  ctx.hitlPolicy = await resolveTurnHitlPolicy(ctx);
+  await resolveTurnEnvironment(ctx, { providerId: setup.providerId, model: setup.providerModel });
+
+  const userMessage = outputOf<{ readonly sequence: number }>(steps, 'persist-user-message');
+  if (userMessage !== undefined) {
+    await restoreAppended(ctx, userMessage.sequence);
+    ctx.storedBeforePark = storedBeforePark(ctx, steps);
+  }
+
+  const retrievals = outputOf<{ readonly retrieved?: readonly RetrievedFact[] }>(
+    steps,
+    'run-retrievals',
+  );
+  if (retrievals?.retrieved !== undefined) ctx.retrieved = retrievals.retrieved;
+
+  for (const s of steps.filter((s) => s.nodeId === 'model-call' && s.inLoop)) {
+    const out = s.output as {
+      readonly step?: number;
+      readonly iterationUsage?: {
+        readonly promptTokens?: number;
+        readonly completionTokens?: number;
+        readonly costUsd?: number;
+      };
+      readonly provider?: { readonly id: string; readonly model: string };
+    };
+    ctx.usage.steps = Math.max(ctx.usage.steps, out.step ?? 0);
+    ctx.usage.promptTokens += out.iterationUsage?.promptTokens ?? 0;
+    ctx.usage.completionTokens += out.iterationUsage?.completionTokens ?? 0;
+    ctx.usage.totalCostUsd += out.iterationUsage?.costUsd ?? 0;
+    if (out.provider !== undefined) ctx.lastProvider = out.provider;
+  }
+  return true;
+}
+
+/**
+ * The messages no completed step accounts for: those the step the turn
+ * parked in stored before it parked.
+ */
+function storedBeforePark(ctx: TurnContext, steps: readonly StepRecord[]): ConversationMessage[] {
+  const accounted = new Set<number>();
+  if (ctx.userMessage !== undefined) accounted.add(ctx.userMessage.sequence);
+  for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+    const out = s.output as { readonly iterationAppended?: readonly ConversationMessage[] };
+    for (const m of out.iterationAppended ?? []) accounted.add(m.sequence);
+  }
+  return ctx.appended.filter((m) => !accounted.has(m.sequence));
+}
+
+/** The messages the turn stored before the park, from its user message on. */
+async function restoreAppended(ctx: TurnContext, fromSequence: number): Promise<void> {
+  const read = await ctx.bindings.conversationBinding.readMessages({
+    tenantId: ctx.input.tenantId,
+    conversationId: ctx.input.conversationId,
+    sinceSequence: fromSequence - 1,
+  });
+  if (read.kind === 'err') throwAgentTurnFailure(read.error);
+  const turnMessages: ConversationMessage[] = read.value.filter((m) => m.sequence >= fromSequence);
+  ctx.appended.push(...turnMessages);
+  const user = turnMessages.find((m) => m.sequence === fromSequence && m.role === 'user');
+  if (user !== undefined) ctx.userMessage = user;
+}

package/src/handlers/render-prompt.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+
+import { renderInstructions } from '../prompt.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/**
+ * Render the agent's instructions template with caller-supplied
+ * parameters + framework auto-vars. Fails the run with a
+ * `model-invocation-failed` (surfaced through `AgentTurnFailure`) if
+ * required parameters are missing or the template throws.
+ *
+ * Setup must have run first — `ctx.conversation` is required.
+ */
+export function buildRenderPromptHandler(ctx: TurnContext): NodeHandler {
+  return async () => {
+    if (ctx.conversation === undefined) {
+      throwAgentTurnFailure({
+        code: 'model-invocation-failed',
+        message: 'render-prompt invoked before setup completed',
+        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,
+      },
+    });
+    if (!rendered.ok) {
+      throwAgentTurnFailure({
+        code: 'model-invocation-failed',
+        message: `Prompt render failed: ${rendered.error.message}`,
+        cause: rendered.error,
+      });
+    }
+    ctx.renderedPrompt = rendered.value.rendered;
+    return { rendered: rendered.value.rendered };
+  };
+}

package/src/handlers/resolve-tools.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ModelToolDefinition } from '@kindgi/capabilities';
+import type { Tool, ToolRegistry } from '@kindgi/tools';
+
+import type { Agent } from '../types.js';
+
+import type { TurnContext } from './context.js';
+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.
+ */
+export function resolveTurnTools(
+  registry: ToolRegistry,
+  agent: Agent,
+): NonNullable<TurnContext['tools']> {
+  const definitions: ModelToolDefinition[] = [];
+  const byName = new Map<
+    string,
+    { readonly tool: Tool; readonly resolvedVersion: string; readonly requestedRange: string }
+  >();
+  for (const ref of agent.tools) {
+    // Agent references tools by (id, range).
+    // Resolve at run start via `resolve` on the tenant-bound registry
+    // (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);
+    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,
+      });
+    }
+    const { tool, resolvedVersion } = resolved.value;
+    definitions.push({
+      name: tool.id,
+      description: tool.description,
+      inputSchema: tool.input as Readonly<Record<string, unknown>>,
+    });
+    byName.set(tool.id, { tool, resolvedVersion, requestedRange: ref.version });
+  }
+  return { definitions, byName };
+}