@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/operator/ticket-source-backend.ts

@@ -0,0 +1,47 @@
+/**
+ * A dispatcher ticket source as the registry's ticket backend (AUT-342):
+ * the tick's turn runner takes an `OperatorToolRegistry`, and
+ * `buildRegistry`'s ticket tools require an `OperatorTicketBackend` — but
+ * the dispatcher's wiring holds a `TicketSource`, not a backend, and
+ * `buildMcpTicketBackend` reads a checkout's autobuild.toml, which cannot
+ * run in origin mode. This adapter hands the dispatcher's
+ * already-constructed source straight through (it was built by
+ * `createTicketSource` from the same effective `[tickets]` config the
+ * `OperatorTicketContext` would derive, for the same repository) and derives
+ * the workflow-state list from the effective config's lifecycle names.
+ */
+import type { Config } from '../config/schema'
+import type { OperatorTicketBackend, OperatorTicketContext } from './tickets'
+import type { TicketSource } from '../ports/types'
+
+/** The dispatcher's resolved triage state (the same default
+ * `processes/dispatcher.ts` applies); inlined rather than imported so this
+ * operator-seam module does not pull the dispatcher's module graph. */
+function defaultTriageState(config: Config): string {
+  return (
+    config.tickets.triageState ??
+    (config.tickets.source === 'linear' || config.tickets.source === 'hosted'
+      ? 'Backlog'
+      : 'Triage')
+  )
+}
+
+export function ticketBackendFromSource(options: {
+  source: TicketSource
+  config: Config
+}): OperatorTicketBackend {
+  return {
+    sourceFor: (_context: OperatorTicketContext) => options.source,
+    statesFor: (_context: OperatorTicketContext, _source: TicketSource): string[] => {
+      const tickets = options.config.tickets
+      const states = [
+        tickets.triageState ?? defaultTriageState(options.config),
+        tickets.readyState,
+        tickets.createState,
+        tickets.claimedState,
+        tickets.proposalState ?? defaultTriageState(options.config),
+      ].filter((state): state is string => typeof state === 'string' && state.trim().length > 0)
+      return [...new Set(states)]
+    },
+  }
+}

package/packages/core/src/orchestrator/approvals.ts

@@ -0,0 +1,115 @@
+/**
+ * The turn approval list (AUT-342): which registry tool calls suspend a turn
+ * until the operator answers. Configured as `[orchestrator].approvals` — a
+ * list of registry tool names, optionally qualified by the accepted value of
+ * the tool's discriminator field (`tool:qualifier`).
+ *
+ * Semantics:
+ * - A bare entry (`builds.control`) suspends every call to that tool.
+ * - A qualified entry (`tickets.move:ready`) suspends only calls whose
+ *   discriminator equals the qualifier; other values of the same tool run
+ *   without pause.
+ * - An entry naming an absent or unknown tool is inert by design, never an
+ *   error — the default list is stable while the registry grows.
+ * - A qualified entry for a tool without a declared discriminator never
+ *   matches (there is nothing to compare).
+ *
+ * Nothing here encodes this repository's specifics.
+ */
+import type { ToolApprovalStatus } from 'ai'
+
+/** A per-tool approval configuration value: a static status or a function
+ * deciding from the call's input. (The SDK's per-tool map accepts both.) */
+export type ApprovalDecision = ToolApprovalStatus | ((input: unknown) => ToolApprovalStatus)
+
+/** The registry tools' discriminator fields, for qualified entries. A tool
+ * absent from this map has no discriminator; only bare entries match it. */
+const DISCRIMINATOR_FIELDS: Record<string, string> = {
+  'builds.control': 'action',
+  'builds.answer': 'resolution',
+  'tickets.move': 'state',
+}
+
+export interface ParsedApprovalEntry {
+  tool: string
+  qualifier?: string
+}
+
+/** Parse one configured entry into its tool and optional qualifier. The
+ * config schema already enforces the entry shape syntactically. */
+export function parseApprovalEntry(entry: string): ParsedApprovalEntry {
+  const separator = entry.indexOf(':')
+  if (separator === -1) return { tool: entry }
+  return { tool: entry.slice(0, separator), qualifier: entry.slice(separator + 1) }
+}
+
+/** Parse the whole configured list. Duplicate entries collapse harmlessly:
+ * the resulting matcher is a predicate, not a table. */
+export function parseApprovalEntries(entries: readonly string[]): ParsedApprovalEntry[] {
+  return entries.map(parseApprovalEntry)
+}
+
+/**
+ * The AI SDK `toolApproval` per-tool configuration for the parsed list: a
+ * bare entry maps the whole tool to `user-approval`; a qualified entry maps
+ * to a function that returns `user-approval` when the discriminator equals
+ * one of the tool's configured qualifiers, else `not-applicable`. Tools with
+ * no matching entry get no key at all — the SDK treats an absent key as
+ * not-applicable.
+ */
+export function approvalConfiguration(
+  entries: readonly ParsedApprovalEntry[],
+): Record<string, ApprovalDecision> {
+  const bare = new Set<string>()
+  const qualified = new Map<string, Set<string>>()
+  for (const entry of entries) {
+    if (entry.qualifier === undefined) {
+      bare.add(entry.tool)
+      continue
+    }
+    if (bare.has(entry.tool)) continue
+    const set = qualified.get(entry.tool) ?? new Set<string>()
+    set.add(entry.qualifier)
+    qualified.set(entry.tool, set)
+  }
+  const configuration: Record<string, ApprovalDecision> = {}
+  for (const tool of bare) configuration[tool] = 'user-approval'
+  for (const [tool, qualifiers] of qualified) {
+    if (bare.has(tool)) continue
+    const field = DISCRIMINATOR_FIELDS[tool]
+    configuration[tool] = (input: unknown) => {
+      // A qualified entry for a tool without a declared discriminator never
+      // matches — there is nothing to compare.
+      if (field === undefined) return 'not-applicable'
+      const discriminator =
+        typeof input === 'object' && input !== null
+          ? (input as Record<string, unknown>)[field]
+          : undefined
+      return typeof discriminator === 'string' && qualifiers.has(discriminator)
+        ? 'user-approval'
+        : 'not-applicable'
+    }
+  }
+  return configuration
+}
+
+/** Whether a specific call would be suspended — the mirror of
+ * `approvalConfiguration` for tests and for the runner's own diagnostics. */
+export function callNeedsApproval(
+  entries: readonly ParsedApprovalEntry[],
+  tool: string,
+  input: unknown,
+): boolean {
+  for (const entry of entries) {
+    if (entry.tool !== tool) continue
+    if (entry.qualifier === undefined) return true
+    const field = DISCRIMINATOR_FIELDS[tool]
+    if (field === undefined) continue
+    const discriminator =
+      typeof input === 'object' && input !== null
+        ? (input as Record<string, unknown>)[field]
+        : undefined
+    if (discriminator === entry.qualifier) return true
+  }
+  return false
+}

package/packages/core/src/orchestrator/conversation.ts

@@ -0,0 +1,167 @@
+/**
+ * Durable conversation reconstruction (AUT-342): a turn runner holds no
+ * process memory. On every invocation the whole conversation is rebuilt from
+ * the session's durable state alone — the finalized artifacts of earlier
+ * turns, the live stream of the open turn, and the session events.
+ *
+ * Ordering rule: a turn's assembled messages attach AT ITS `turn.started`
+ * event, not at its terminal fact. Attaching at the terminal fact would
+ * place a message posted while the turn was suspended BEFORE that turn's
+ * already-generated output, interleaving the new message into the middle of
+ * the checkpoint the original invocation produced — breaking the identical-
+ * input guarantee for a resumed turn in exactly the reachable case (a
+ * message landing during a suspension). Attached at `turn.started`, every
+ * step the original invocation completed appears verbatim and in the
+ * position the model generated it from, and a mid-suspension message reads
+ * as a plain next user message.
+ *
+ * Message-triggered turns contribute no input message of their own (the
+ * `message.posted` fact is the input); wake-triggered turns carry their
+ * input — the event record and the build's reduced state, frozen at wake
+ * time — in the `turn.started` payload, so reconstruction is byte-identical
+ * across invocations even though live build state keeps moving.
+ */
+import { assembleUIMessageDocument } from '../store/streams/assemble'
+import type { StreamPart, StreamRead } from '../store/streams/types'
+import type { UIMessage } from 'ai'
+import type { BuildStore } from '../store/types'
+import type { SessionEvent } from '../events/sessions'
+import type { StreamRecord } from '../store/streams/types'
+
+const STREAM_ARTIFACT_PREFIX = 'stream:'
+
+interface TurnStreamSource {
+  /** The turn's stream id, from its `turn.started` fact. */
+  stream: string
+  /** Durable status of the stream at read time. */
+  status: 'open' | 'closed'
+}
+
+async function readTurnDocument(
+  store: BuildStore,
+  sessionId: string,
+  source: TurnStreamSource,
+): Promise<UIMessage[]> {
+  if (source.status === 'open') {
+    const read: StreamRead = await store.readStream(source.stream)
+    const parts: StreamPart[] = read.chunks.flatMap((chunk) => chunk.parts)
+    const { document } = await assembleUIMessageDocument(parts)
+    return document
+  }
+  // Closed streams finalize into the `stream:<id>` session artifact; the
+  // chunks themselves are retention-pruned, so the artifact is the durable
+  // form a later invocation must read.
+  const artifact = await store.getSessionArtifact(
+    sessionId,
+    `${STREAM_ARTIFACT_PREFIX}${source.stream}`,
+  )
+  if (artifact === null) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(artifact.content))
+  } catch {
+    return []
+  }
+  return Array.isArray(parsed) ? (parsed as UIMessage[]) : []
+}
+
+export interface ReconstructedConversation {
+  messages: UIMessage[]
+  /** Per turn, in start order: the turn id and how many messages its
+   * document contributed. Diagnostics, not contract. */
+  turns: { turn: string; messages: number }[]
+}
+
+/**
+ * Reconstruct the conversation for a session from durable state alone.
+ * `events` must be the complete session event log (seq 1 upward).
+ */
+export async function reconstructConversation(
+  store: BuildStore,
+  sessionId: string,
+  events: SessionEvent[],
+): Promise<ReconstructedConversation> {
+  const messages: UIMessage[] = []
+  const turns: ReconstructedConversation['turns'] = []
+
+  // Resolve each turn's stream status up front so the walk stays ordered:
+  // the open turn reads its live stream, closed turns read their artifacts.
+  const sources = new Map<string, TurnStreamSource>()
+  for (const event of events) {
+    if (event.type !== 'turn.started') continue
+    const record: StreamRecord | null = await store.getStream(event.payload.stream)
+    sources.set(event.payload.turn, {
+      stream: event.payload.stream,
+      status: record?.status === 'open' ? 'open' : 'closed',
+    })
+  }
+
+  for (const event of events) {
+    if (event.type === 'message.posted') {
+      messages.push({
+        id: `msg_${event.seq}`,
+        role: 'user',
+        parts: [{ type: 'text', text: event.payload.text }],
+      })
+    } else if (event.type === 'turn.started') {
+      const source = sources.get(event.payload.turn)
+      if (source === undefined) continue
+      // A wake turn's input is the frozen snapshot carried by its own
+      // `turn.started` fact — recorded before the fact, so every invocation
+      // reconstructs the identical user message.
+      if (event.payload.trigger.kind === 'wake' && event.payload.wake !== undefined) {
+        messages.push(
+          wakeTriggerInputMessage({
+            build: event.payload.trigger.build,
+            journal: event.payload.trigger.journal === true,
+            type: event.payload.trigger.type,
+            event: event.payload.wake.event,
+            buildState: event.payload.wake.buildState,
+          }),
+        )
+      }
+      const document = await readTurnDocument(store, sessionId, source)
+      turns.push({ turn: event.payload.turn, messages: document.length })
+      messages.push(...document)
+    }
+  }
+
+  return { messages, turns }
+}
+
+/**
+ * The user input message a wake trigger delivers to its turn: the attention
+ * event record and — for a build wake — the build's reduced state, as JSON.
+ * A journal wake names the repository journal instead of a build and carries
+ * no build-state section (there is no build; the turn's operator registry
+ * exposes bounded repository reads). The runner embeds the same object in
+ * the `turn.started` payload, so this function and the reconstruction agree
+ * by construction.
+ */
+export function wakeTriggerInputMessage(input: {
+  build?: string
+  journal?: boolean
+  type: string
+  event: { seq: number; ts: string; type: string; payload: unknown }
+  buildState?: unknown
+}): UIMessage {
+  const journal = input.journal === true || input.build === undefined
+  return {
+    id: journal ? `wake_journal_${input.event.seq}` : `wake_${input.build}_${input.event.seq}`,
+    role: 'user',
+    parts: [
+      {
+        type: 'text',
+        text: journal
+          ? `Repository-journal attention event: ${input.type} (seq ${input.event.seq}).\n` +
+            'Event record:\n' +
+            JSON.stringify(input.event, null, 2)
+          : `Attention event on build ${input.build}: ${input.type} (seq ${input.event.seq}).\n` +
+            'Event record:\n' +
+            JSON.stringify(input.event, null, 2) +
+            '\nBuild state:\n' +
+            JSON.stringify(input.buildState, null, 2),
+      },
+    ],
+  }
+}

package/packages/core/src/orchestrator/model.ts

@@ -0,0 +1,86 @@
+/**
+ * Model resolution and typed failure classification (AUT-342): the
+ * orchestrator's model comes from `[orchestrator].model`, a provider-
+ * qualified string in the same vocabulary as `[roles]`, resolved through the
+ * deployment's gateway credential. Model failures are typed on
+ * `turn.failed` — provider availability, exhaustion, credentials, and
+ * configuration are distinguished so nothing is ever retried unboundedly and
+ * the class is visible in the session's reduced state.
+ */
+import { LoadAPIKeyError, createGateway } from 'ai'
+import {
+  GatewayAuthenticationError,
+  GatewayInternalServerError,
+  GatewayModelNotFoundError,
+  GatewayRateLimitError,
+} from '@ai-sdk/gateway'
+
+/** Strip the optional `vercel-ai-gateway/` prefix so the value is written
+ * exactly as `[roles]` spells it while the gateway provider receives the
+ * bare model id. */
+export function resolveGatewayModelId(model: string): string {
+  const prefix = 'vercel-ai-gateway/'
+  return model.startsWith(prefix) ? model.slice(prefix.length) : model
+}
+
+/** Resolve the configured model string through the deployment's gateway
+ * credential (`AI_GATEWAY_API_KEY`, read by `createGateway`). Missing or
+ * rejected credentials surface at call time and classify as `credentials`. */
+export function resolveGatewayModel(model: string): ReturnType<ReturnType<typeof createGateway>> {
+  return createGateway()(resolveGatewayModelId(model))
+}
+
+/** The typed model-failure vocabulary, mirroring `turn.failed`'s `kind`. */
+export type TurnFailureKind =
+  | 'provider-unavailable'
+  | 'exhausted'
+  | 'credentials'
+  | 'configuration'
+  | 'internal'
+
+/**
+ * Classify one model error. The gateway's own error classes are the primary
+ * vocabulary: `GatewayModelNotFoundError` (`type: 'model_not_found'`, thrown
+ * at call time — the gateway constructs a model for any id, so unknown-model
+ * is never `NoSuchModelError`) is `configuration`;
+ * `GatewayAuthenticationError` or `LoadAPIKeyError` (which the gateway does
+ * not export; `ai` re-exports it from `@ai-sdk/provider`) is `credentials`;
+ * `GatewayRateLimitError` or any 429 is `exhausted`;
+ * `GatewayInternalServerError` and other 5xx/network/timeout errors are
+ * `provider-unavailable`. Remaining errors classify by their `statusCode`
+ * when present, else `internal`.
+ */
+export function classifyModelError(error: unknown): TurnFailureKind {
+  // `ai` rewrites gateway authentication errors flowing through a stream
+  // into a plain Error (or AISDKError in production) that keeps only the
+  // class NAME — classify those by name before the instanceof checks.
+  const name =
+    typeof (error as { name?: unknown })?.name === 'string'
+      ? ((error as { name?: string }).name ?? '')
+      : ''
+  if (name === 'GatewayAuthenticationError' || name === 'GatewayError') return 'credentials'
+  if (error instanceof GatewayModelNotFoundError) return 'configuration'
+  if (error instanceof GatewayAuthenticationError || error instanceof LoadAPIKeyError) {
+    return 'credentials'
+  }
+  if (error instanceof GatewayRateLimitError) return 'exhausted'
+  if (error instanceof GatewayInternalServerError) return 'provider-unavailable'
+
+  // Non-gateway shapes: classify by what they carry.
+  const candidate = error as { statusCode?: unknown; name?: unknown; message?: unknown }
+  if (typeof candidate?.statusCode === 'number') {
+    if (candidate.statusCode === 401 || candidate.statusCode === 403) return 'credentials'
+    if (candidate.statusCode === 404) return 'configuration'
+    if (candidate.statusCode === 429) return 'exhausted'
+    if (candidate.statusCode >= 500) return 'provider-unavailable'
+  }
+  const text = `${candidate?.name ?? ''} ${candidate?.message ?? ''}`.toLowerCase()
+  if (text.includes('api key') || text.includes('apikey') || text.includes('unauthorized')) {
+    return 'credentials'
+  }
+  if (text.includes('rate limit') || text.includes('too many requests')) return 'exhausted'
+  if (text.includes('timeout') || text.includes('econnrefused') || text.includes('enotfound')) {
+    return 'provider-unavailable'
+  }
+  return 'internal'
+}

package/packages/core/src/orchestrator/prompt.ts

@@ -0,0 +1,61 @@
+/**
+ * The turn's system prompt (AUT-342): the canonical `ab-operate` skill body,
+ * plus the current `operator-notes` artifact, plus the session's wake
+ * settings, plus the session's repository identity.
+ *
+ * The skill is read from the distribution's `skills/operate/SKILL.md` — the
+ * same tree `ab init` vendors from — through `distributionPath`, and is
+ * shipped into every hosted function that executes a turn (see
+ * packages/hosted-dispatcher/src/ship-packed-distribution.ts). It is
+ * self-contained per the vendored-skill rule and teaches the tool surface,
+ * the attention set, and when to escalate rather than act; nothing
+ * repository-specific may be inlined here.
+ */
+import { readFile } from 'node:fs/promises'
+import { distributionPath } from '../distribution'
+import { OPERATOR_NOTES_REPO_KIND } from '../store/retention'
+import type { BuildStore } from '../store/types'
+import type { OrchestratorConfig } from '../config/schema'
+
+/** Where the canonical skill lives in the distribution tree. */
+export const OPERATE_SKILL_PATH = 'skills/operate/SKILL.md'
+
+/** Read the canonical skill body from the distribution tree. Throws when
+ * the file is missing — a deployment that cannot load the canonical skill
+ * must not run turns with a silently empty system prompt. */
+export async function readOperateSkill(): Promise<string> {
+  return readFile(distributionPath(...OPERATE_SKILL_PATH.split('/')), 'utf8')
+}
+
+export interface TurnPromptInput {
+  store: BuildStore
+  repo: string
+  /** The session's wake globs (already resolved — empty means message-only). */
+  wakeGlobs: readonly string[]
+  config: OrchestratorConfig
+}
+
+/** Assemble the system prompt. The operator-notes artifact is empty when
+ * absent; the skill body is always present (missing file throws). */
+export async function buildTurnSystemPrompt(input: TurnPromptInput): Promise<string> {
+  const skill = await readOperateSkill()
+  const notes = await input.store.getRepoArtifact(input.repo, OPERATOR_NOTES_REPO_KIND)
+  const notesText = notes === null ? '' : new TextDecoder().decode(notes.content).trim()
+  return [
+    skill,
+    '',
+    '## Repository',
+    '',
+    `You operate the repository ${JSON.stringify(input.repo)}. Every tool call is bound to this repository; you never supply a repo argument yourself.`,
+    '',
+    '## Operator notes',
+    '',
+    notesText === '' ? '(none recorded)' : notesText,
+    '',
+    '## Wake settings',
+    '',
+    input.wakeGlobs.length === 0
+      ? 'This session wakes only on operator messages (no attention-event wake sources).'
+      : `This session wakes on these attention-event globs: ${input.wakeGlobs.map((glob) => JSON.stringify(glob)).join(', ')}.`,
+  ].join('\n')
+}

package/packages/core/src/orchestrator/tools.ts

@@ -0,0 +1,117 @@
+/**
+ * Registry entries as AI SDK tools (AUT-342): the turn runner binds the
+ * in-process operator registry, so the agent's tools ARE the operator
+ * surface — never a reimplementation.
+ *
+ * Two rules shape the binding:
+ *
+ * 1. **Attribution.** Every call carries the session operator as the human
+ *    actor with `via: {kind: 'session', id}` — the operator's session did
+ *    it, exactly as an MCP client's calls carry `via: {kind: 'mcp', …}`.
+ *
+ * 2. **The model never supplies `repo`.** Every registry entry requires a
+ *    `repo` field and `call()` validates it before the handler runs, but
+ *    nothing in the turn's durable state teaches the model a repository
+ *    identity it could type: message-triggered turns carry no repo fact, the
+ *    canonical skill must stay generic, and the registry has no
+ *    repositories.list tool. The model-facing schema therefore strips `repo`
+ *    (the mirror of the registry's own `extendUnion`), and `execute` injects
+ *    the session's repository into the validated input before
+ *    `registry.call` re-validates it — the session's repository is the only
+ *    value a tool can ever target. The registry's `allowedRepo` guard stays
+ *    bound as defense in depth.
+ *
+ * A thrown `RegistryError` is caught and returned as the operator-API
+ * failure body (`kind`/`error`/`code`) so the model can react to a refusal
+ * instead of the step dying; the registry's JSON-value invariant makes every
+ * output wire-safe.
+ */
+import { tool, type ToolSet } from 'ai'
+import { z } from 'zod'
+import { RegistryError, type OperatorToolRegistry } from '../operator/registry'
+import type { Via } from '../events/envelope'
+import type { ApprovalDecision } from './approvals'
+
+/** The model-facing stand-in for a stripped `repo` on schemas Zod 4 refuses
+ * to `.omit()` — an object carrying refinements (`.refine` locks the shape).
+ * `safeExtend` preserves the refinements while replacing the field with an
+ * optional `never`: absent is fine, any supplied value fails validation, so
+ * the model still cannot point a tool anywhere but the session's
+ * repository. (Checked against the installed zod; `.omit` and `.extend`
+ * both throw on refined objects.) */
+const unsatisfiableRepo = z.optional(z.never())
+
+/** Strip `repo` from a tool's model-facing schema: plain `ZodObject` entries
+ * omit the field; union entries (the `extendUnion` shape) strip each option
+ * and rebuild the union — Zod 4 unions expose no `withOptions`, so the
+ * original union must never be handed through unchanged (its members still
+ * require `repo`, which the model cannot know). Refined objects neutralize
+ * the field instead of omitting it. Returns undefined only for a schema the
+ * entry table never uses. */
+function stripRepoField(schema: z.ZodType): z.ZodType | undefined {
+  const options = (schema as unknown as { options?: readonly z.ZodType[] }).options
+  if (Array.isArray(options) && options.length > 0) {
+    const stripped = options.map((option) => stripRepoField(option) ?? option)
+    return z.union(stripped)
+  }
+  const object = schema as unknown as {
+    omit?: (mask: Record<string, boolean>) => unknown
+    safeExtend?: (patch: Record<string, z.ZodType>) => unknown
+  }
+  if (typeof object.omit === 'function') {
+    try {
+      return object.omit({ repo: true }) as z.ZodType
+    } catch {
+      // A refined object: neutralize `repo` instead of omitting it.
+      if (typeof object.safeExtend === 'function') {
+        return object.safeExtend({ repo: unsatisfiableRepo }) as z.ZodType
+      }
+    }
+  }
+  return undefined
+}
+
+export interface RegistryToolsInput {
+  registry: OperatorToolRegistry
+  /** The session's repository — the only value any tool can target. */
+  repo: string
+  /** The session operator: the human actor every attributed write names. */
+  operator: string
+  /** The session-scoped delegate marker. */
+  via: Via
+  /** Optional per-tool approval configuration (from `approvals.ts`), keyed
+   * by registry tool name; absent keys never suspend. (Kept for signature
+   * symmetry; the agent takes the configuration directly.) */
+  toolApproval?: Record<string, ApprovalDecision>
+}
+
+/** Build the AI SDK tool set from the registry's closed table. */
+export function registryTools(input: RegistryToolsInput): ToolSet {
+  const tools: ToolSet = {}
+  for (const entry of input.registry.entries) {
+    const modelSchema = stripRepoField(entry.inputSchema)
+    if (modelSchema === undefined) continue
+    tools[entry.name] = tool({
+      description: `${entry.description}${entry.outputDescription ? `\n\nReturns: ${entry.outputDescription}` : ''}`,
+      inputSchema: modelSchema,
+      execute: async (modelInput: unknown) => {
+        // Re-inject the session's repository: the registry re-validates the
+        // whole input (with `repo`) before the handler runs.
+        const fullInput =
+          typeof modelInput === 'object' && modelInput !== null
+            ? { ...(modelInput as Record<string, unknown>), repo: input.repo }
+            : { repo: input.repo }
+        try {
+          return await input.registry.call(entry.name, fullInput, {
+            identity: input.operator,
+            via: input.via,
+          })
+        } catch (error) {
+          if (error instanceof RegistryError) return error.body
+          throw error
+        }
+      },
+    })
+  }
+  return tools
+}