@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/operator/sandbox-host.ts

@@ -0,0 +1,140 @@
+/**
+ * The checkout-less operator-sandbox composition helper (AUT-584): builds the
+ * same `createOperatorSandboxService` backend `ab mcp` builds from a checkout,
+ * but from a deposited effective config plus injected seams — for hosted
+ * serving processes that hold no host checkout and never touch host git.
+ *
+ * The module is a SEPARATE subpath (`@defrex/autobuild/operator-sandbox-host`)
+ * on purpose: it pulls the workspace-provider/forge construction closure, and
+ * existing `./operator` consumers (the hosted operator server among them) must
+ * not grow that closure. The hosted store service imports only this subpath.
+ *
+ * Containment contract: every construction failure THROWS. The callers (the
+ * hosted store service's runner factory and the dispatcher tick) contain it —
+ * a broken or unsupported config degrades the sandbox tools of one binding,
+ * never the orchestrator itself.
+ */
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Config } from '../config/schema'
+import type { Forge } from '../ports/types'
+import { createForge } from '../ports/forge/create'
+import { GitHubApiError } from '../ports/forge/github-transport'
+import { createWorkspaceProvider } from '../ports/workspace/create'
+import { createPluginRegistry } from '../plugins/registry'
+import type { BuildStore, Clock } from '../store/types'
+import { createOperatorSandboxService, type OperatorSandboxService } from './sandbox'
+
+export interface HostedOperatorSandboxOptions {
+  store: BuildStore
+  /** The repository identity — already the normalized HTTPS origin the
+   * sandbox providers parse with `cleanGithubOrigin`; passed through as the
+   * provider's `origin` seam so no host git is ever probed. */
+  repo: string
+  /** The repository's effective config (the deposited
+   * `dispatcher-effective-config` artifact, or the checkout's parsed config).
+   * `[orchestrator].enabled` is the CALLER's gate; this helper composes the
+   * backend for any config handed to it. */
+  config: Config
+  /** The serving process's environment. The Vercel SDK credential must be
+   * reachable here for a `vercel-sandbox` workspace (`VERCEL_OIDC_TOKEN`, or
+   * the durable `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID` triple);
+   * a hosted caller merges the request's `x-vercel-oidc-token` under
+   * `VERCEL_OIDC_TOKEN` before calling, with an explicit env token keeping
+   * precedence. */
+  env: Record<string, string | undefined>
+  /** The provider's store authority: an HTTPS store ref reachable from the
+   * sandbox plus a repo-scoped token. The guest environment is always built
+   * from an empty record plus the configured forwarded names, so neither
+   * value ever reaches the sandbox guest. */
+  storeRef: string
+  storeToken: string
+  /** Scratch root for the composition's filesystem seams (worktree root,
+   * repo root, sandbox root). Default: a fresh `mkdtemp` under the OS temp
+   * directory. The builtin providers only touch these paths through host-git
+   * or local-scratch paths the injected seams bypass; a plugin-provider config
+   * fails construction before any path use. */
+  scratchRoot?: string
+  clock?: Clock
+  /** Test seam: an already-constructed forge. Production passes nothing and
+   * the configured forge is built here. The forge is REQUIRED either way —
+   * unlike `ab mcp`, which degrades to `canPublish: false` because its
+   * provider can fall back to host git, a hosted host has no checkout, so a
+   * backend without a forge cannot resolve base heads at all. */
+  forge?: Forge
+}
+
+/** Map a forge onto the provider's checkout-less `remoteBranchHead` seam:
+ * a `GitHubApiError` with status 404 means the branch does not exist and
+ * reads as `undefined`; every other error is rethrown (a transient GitHub
+ * failure must never masquerade as an absent branch and refuse provision).
+ * The forge must expose `remoteBranchSha`; the caller enforces that before
+ * calling with a diagnostic that names the forge. */
+export function remoteBranchHeadFromForge(
+  forge: Forge,
+): (branch: string) => Promise<string | undefined> {
+  const remoteBranchSha = forge.remoteBranchSha
+  if (remoteBranchSha === undefined) {
+    throw new Error('forge does not resolve remote branch heads')
+  }
+  return async (branch: string): Promise<string | undefined> => {
+    try {
+      return await remoteBranchSha.call(forge, branch)
+    } catch (error) {
+      if (error instanceof GitHubApiError && error.status === 404) return undefined
+      throw error
+    }
+  }
+}
+
+/** Build the hosted operator-sandbox backend from the effective config and
+ * injected seams. Throws on every construction failure (unknown provider or
+ * forge, missing Vercel SDK credential, forbidden forwarded env name,
+ * capability-less provider, forge without `remoteBranchSha`) — the caller
+ * contains and degrades to serving without the sandbox tools. */
+export async function createHostedOperatorSandboxService(
+  options: HostedOperatorSandboxOptions,
+): Promise<OperatorSandboxService> {
+  const scratch = options.scratchRoot ?? (await mkdtemp(join(tmpdir(), 'autobuild-sandbox-host-')))
+  const forge =
+    options.forge ??
+    (await createForge({
+      name: options.config.forge,
+      registry: createPluginRegistry(),
+      env: options.env,
+      repoRoot: scratch,
+      repository: options.repo,
+    }))
+  if (forge.remoteBranchSha === undefined) {
+    throw new Error(
+      `the configured forge "${options.config.forge}" does not resolve remote branch heads; ` +
+        'the hosted sandbox backend has no checkout to resolve base heads against',
+    )
+  }
+  // Builtin-only registry: a plugin-provider config fails construction here
+  // (unknown provider in the empty registry) and the caller contains it.
+  const provider = await createWorkspaceProvider(options.config.workspace, {
+    registry: createPluginRegistry(),
+    worktreeRoot: scratch,
+    repoRoot: scratch,
+    env: options.env,
+    storeRef: options.storeRef,
+    storeToken: options.storeToken,
+    origin: async () => options.repo,
+    remoteBranchHead: remoteBranchHeadFromForge(forge),
+    sandboxSetupCommand: options.config.commands.setup,
+    sandboxRoot: join(scratch, 'orchestrator-sandboxes'),
+    sandboxEnvironmentVariables: options.config.orchestrator.sandbox.environmentVariables,
+    orchestratorSandboxEnabled: true,
+  })
+  return createOperatorSandboxService({
+    store: options.store,
+    repo: options.repo,
+    provider,
+    sandbox: options.config.orchestrator.sandbox,
+    baseBranch: options.config.baseBranch,
+    forge,
+    ...(options.clock !== undefined ? { clock: options.clock } : {}),
+  })
+}

package/packages/core/src/operator/sandbox.ts

@@ -10,7 +10,11 @@
  * environments from empty records); redaction here keeps credential VALUES
  * out of typed error messages that travel to tool callers.
  */
+import { createHash } from 'node:crypto'
 import { humanActor } from '../events/envelope'
+import type { Via } from '../events/envelope'
+import type { RepositoryEvent } from '../events/repository'
+import type { Forge } from '../ports/types'
 import {
   SANDBOX_FORBIDDEN_ENV,
   SandboxOperationError,
@@ -19,6 +23,7 @@ import {
   type SandboxWaitResult,
 } from '../ports/workspace/operator-sandbox'
 import type { WorkspaceProvider } from '../ports/types'
+import { readRepoEventsIfRecorded } from '../processes/harvest'
 import { sandboxStates } from '../processes/sandbox-state'
 import { systemClock, type BuildStore, type Clock } from '../store/types'
 
@@ -107,12 +112,41 @@ function describeError(error: unknown): string {
   return redactSandboxMessage(error instanceof Error ? error.message : String(error))
 }
 
+/** The canonical publication branch grammar every provider adapter enforces. */
+const PUBLICATION_BRANCH_PATTERN = /^ab\/[a-z0-9][a-z0-9-]*$/
+
+/** Deterministic PR branch name for one operator × repository:
+ * `ab/orch-<operator-slug>-<hash8>` where hash8 is the first 8 hex chars of
+ * sha256(`<repo>\0<operator>`) and the slug is the operator lowercased with
+ * non-`[a-z0-9]` runs collapsed to `-` and trimmed. One operator always maps
+ * to one branch per repository, so a later publish updates the same PR's
+ * head. An identity with no `[a-z0-9]` characters yields `ab/orch--<hash8>`,
+ * which still matches the canonical grammar — no fallback token. */
+export function sandboxPublicationBranch(repo: string, operator: string): string {
+  const slug = operator
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  const hash8 = createHash('sha256').update(`${repo}\0${operator}`).digest('hex').slice(0, 8)
+  const branch = `ab/orch-${slug}-${hash8}`
+  if (!PUBLICATION_BRANCH_PATTERN.test(branch)) {
+    throw new SandboxOperationError(
+      'publish',
+      `derived publication branch ${JSON.stringify(branch)} is not a canonical branch name`,
+    )
+  }
+  return branch
+}
+
 export interface OperatorSandboxConfig {
   idleMinutes: number
   environmentVariables: readonly string[]
 }
 
 export interface OperatorSandboxService {
+  /** True when both a forge and the provider's sandbox publication
+   * capability are present, i.e. `publish` is callable. */
+  readonly canPublish: boolean
   exec(
     identity: string,
     input: { repo: string; command: string; cwd?: string; timeoutSeconds?: number },
@@ -133,6 +167,20 @@ export interface OperatorSandboxService {
   /** Destructive: journal `reset`, full teardown + snapshot purge, then a
    * fresh provision from the CURRENT base head. */
   reset(identity: string, input: { repo: string }): Promise<void>
+  /** PR-only publication (AUT-343): push the sandbox checkout's head (or an
+   * explicit commit) to a deterministic operator branch and open or update
+   * the PR against the base branch. The base branch itself is never pushed
+   * to; the sandbox performs no push and receives no credential. */
+  publish(
+    identity: string,
+    input: {
+      repo: string
+      title: string
+      body?: string
+      commit?: string
+      via?: Via
+    },
+  ): Promise<{ branch: string; sha: string; pr: { number: number; url: string; headSha: string } }>
   /** Full teardown + snapshot purge of the operator's environment, without
    * provisioning. A no-op when the journal shows no environment. Used by
    * `reset` and the session-archive hook. */
@@ -148,6 +196,9 @@ export interface OperatorSandboxServiceOptions {
    * branch's current head. A hot baseBranch reload is picked up when the
    * `ab mcp` process restarts. */
   baseBranch: string
+  /** The forge used to open or update the PR. Absent = publication is
+   * unavailable and the service reports `canPublish: false`. */
+  forge?: Forge
   clock?: Clock
   capability?: WorkspaceProvider['orchestratorSandbox']
 }
@@ -165,6 +216,7 @@ export async function createOperatorSandboxService(
     )
   }
   const clock = options.clock ?? systemClock
+  const canPublish = options.forge !== undefined && provider.sandboxPublication !== undefined
   await store.ensureRepo(repo)
 
   /** Per-environment serialization: one in-process promise chain keyed by
@@ -188,7 +240,9 @@ export async function createOperatorSandboxService(
       | 'orchestrator.sandbox.resumed'
       | 'orchestrator.sandbox.activity'
       | 'orchestrator.sandbox.released'
-      | 'orchestrator.sandbox.reset',
+      | 'orchestrator.sandbox.reset'
+      | 'orchestrator.sandbox.published'
+      | 'orchestrator.sandbox.publish-failed',
     payload: Record<string, unknown>,
   ): Promise<void> => {
     await store.appendRepo(repo, {
@@ -198,13 +252,8 @@ export async function createOperatorSandboxService(
     })
   }
 
-  const journalEvents = async (): Promise<Awaited<ReturnType<typeof store.getRepoEvents>>> => {
-    if ((await store.getRepo(repo)) === null) return []
-    return store.getRepoEvents(repo)
-  }
-
   /** The operator's journal state, or undefined when no environment exists. */
-  const operatorState = (identity: string, events: Awaited<ReturnType<typeof journalEvents>>) =>
+  const operatorState = (identity: string, events: RepositoryEvent[]) =>
     sandboxStates(events)
       .filter((state) => state.operator === identity && state.state !== 'released')
       .at(-1)
@@ -227,6 +276,7 @@ export async function createOperatorSandboxService(
         provider: resolved.provider,
         ...(resolved.sessionId !== undefined ? { sessionId: resolved.sessionId } : {}),
         workspacePath: resolved.workspacePath,
+        ...(resolved.baseSha !== undefined ? { baseSha: resolved.baseSha } : {}),
       })
     } else if (state.state === 'stopped') {
       await append(identity, 'orchestrator.sandbox.resumed', {
@@ -255,10 +305,13 @@ export async function createOperatorSandboxService(
     })
   }
 
-  const requireRepo = (inputRepo: string | undefined): void => {
+  const requireRepo = (
+    inputRepo: string | undefined,
+    stage: SandboxOperationError['stage'] = 'exec',
+  ): void => {
     if (inputRepo !== undefined && inputRepo !== repo) {
       throw new SandboxOperationError(
-        'exec',
+        stage,
         `sandbox tools serve repository "${repo}"; refusing "${inputRepo}"`,
       )
     }
@@ -266,7 +319,7 @@ export async function createOperatorSandboxService(
 
   const run = async <T>(
     identity: string,
-    stage: 'provision' | 'resume' | 'exec',
+    stage: 'provision' | 'resume' | 'exec' | 'publish',
     operation: (
       resolved: SandboxEnvironmentIdentity,
       state: ReturnType<typeof operatorState>,
@@ -274,7 +327,7 @@ export async function createOperatorSandboxService(
   ): Promise<T> => {
     const key = `${repo}\0${identity}`
     return serialize(key, async () => {
-      const events = await journalEvents()
+      const events = await readRepoEventsIfRecorded(store, repo)
       const state = operatorState(identity, events)
       const resolved = await ensureWithFacts(identity, state).catch((error: unknown) => {
         if (error instanceof SandboxOperationError) throw error
@@ -284,7 +337,7 @@ export async function createOperatorSandboxService(
           { cause: error },
         )
       })
-      const freshEvents = await journalEvents()
+      const freshEvents = await readRepoEventsIfRecorded(store, repo)
       const freshState = operatorState(identity, freshEvents)
       try {
         const result = await operation(resolved, freshState)
@@ -298,6 +351,10 @@ export async function createOperatorSandboxService(
   }
 
   return {
+    /** True only when both a forge and a sandbox publication capability are
+     * wired; the registry filters `sandbox.publish` when false. */
+    canPublish,
+
     async exec(identity, input) {
       requireRepo(input.repo)
       const timeoutSeconds = validateBoundedInt(
@@ -393,11 +450,187 @@ export async function createOperatorSandboxService(
       })
     },
 
+    async publish(
+      identity,
+      input: {
+        repo: string
+        title: string
+        body?: string
+        commit?: string
+        via?: Via
+      },
+    ) {
+      requireRepo(input.repo, 'publish')
+      const title = input.title.trim()
+      if (title === '') {
+        throw new SandboxOperationError('publish', 'title must not be empty')
+      }
+      if (title.length > 200) {
+        throw new SandboxOperationError('publish', 'title must be at most 200 characters')
+      }
+      if (input.body !== undefined && input.body.length > 65_536) {
+        throw new SandboxOperationError('publish', 'body must be at most 65,536 characters')
+      }
+      if (input.commit !== undefined && input.commit.trim() === '') {
+        throw new SandboxOperationError('publish', 'commit must be a nonempty commit-ish')
+      }
+      if (!canPublish) {
+        throw new SandboxOperationError(
+          'publish',
+          'publication is unavailable: no forge or no sandbox publication capability is wired',
+        )
+      }
+      const forge = options.forge!
+      const publication = provider.sandboxPublication!
+      // run() already serializes per environment; wrapping it in another
+      // serialize on the same key would deadlock the chain.
+      return run(identity, 'publish', async (resolved, freshState) => {
+        let stage: 'checks' | 'push' | 'pr' = 'checks'
+        try {
+          // 1. Resolve the commit inside the sandbox checkout.
+          const commitExpr = input.commit?.trim() || 'HEAD'
+          const resolveResult = await capability.exec(resolved, {
+            // --quiet makes an unresolvable commit-ish exit 1 (the documented
+            // refusal signal below); without it git exits 128 and the refusal
+            // branch is unreachable.
+            command: `git rev-parse --verify --quiet ${commitExpr}^{commit}`,
+            timeoutSeconds: 30,
+          })
+          if (resolveResult.exitCode === 1) {
+            throw new SandboxOperationError(
+              'publish',
+              `commit ${JSON.stringify(commitExpr)} does not resolve to a commit in the sandbox checkout`,
+            )
+          }
+          if (resolveResult.exitCode !== 0) {
+            throw new Error(
+              `git rev-parse --verify ${commitExpr}^{commit} exited ${resolveResult.exitCode}: ${resolveResult.stderr.trim() || resolveResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          const sha = resolveResult.stdout.trim()
+          // 2. Refuse a dirty checkout: staged or unstaged changes to
+          // tracked files, and untracked files — a new file the operator
+          // never committed would otherwise be silently left out of the
+          // published commit. The providers exclude their own
+          // provisioning marker in the checkout's info/exclude, so the
+          // marker itself never counts as dirt (f_c748dc6a).
+          const statusResult = await capability.exec(resolved, {
+            command: 'git status --porcelain',
+            timeoutSeconds: 30,
+          })
+          if (statusResult.exitCode !== 0) {
+            throw new Error(
+              `git status --porcelain exited ${statusResult.exitCode}: ${statusResult.stderr.trim() || statusResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          if (statusResult.stdout.trim() !== '') {
+            throw new SandboxOperationError(
+              'publish',
+              'the sandbox checkout has uncommitted changes; commit or discard them before publishing',
+            )
+          }
+          // 3. Refuse a commit that is not a descendant of the base head
+          // at provision or reset time.
+          const baseSha = freshState?.baseSha
+          if (baseSha === undefined) {
+            throw new SandboxOperationError(
+              'publish',
+              'this environment has no recorded base head; run sandbox.reset to re-provision before publishing',
+            )
+          }
+          if (sha === baseSha) {
+            throw new SandboxOperationError(
+              'publish',
+              'the checkout head is the base commit itself; there is nothing to publish',
+            )
+          }
+          const ancestorResult = await capability.exec(resolved, {
+            command: `git merge-base --is-ancestor ${baseSha} ${sha}`,
+            timeoutSeconds: 30,
+          })
+          if (ancestorResult.exitCode === 1) {
+            throw new SandboxOperationError(
+              'publish',
+              `the commit is not a descendant of the base head ${baseSha} recorded at provision time; rebase onto the current base or run sandbox.reset`,
+            )
+          }
+          if (ancestorResult.exitCode !== 0) {
+            throw new Error(
+              `git merge-base --is-ancestor ${baseSha} ${sha} exited ${ancestorResult.exitCode}: ${ancestorResult.stderr.trim() || ancestorResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          // 4. Deterministic branch; the helper self-validates the grammar.
+          const branch = sandboxPublicationBranch(repo, identity)
+          if (branch === options.baseBranch) {
+            throw new SandboxOperationError(
+              'publish',
+              'the derived publication branch collides with the base branch; refusing',
+            )
+          }
+          // 5. Push-before-fact crash safety, mirroring
+          // publication-settlement: a crashed prior attempt is owed its
+          // completion, not a re-push.
+          const alreadyPublished =
+            (await publication.isPublished?.({
+              ref: resolved.environmentId,
+              sha,
+              branch,
+            })) === true
+          stage = 'push'
+          if (!alreadyPublished) {
+            await publication.publish({ ref: resolved.environmentId, sha, branch })
+          }
+          // 6. Open (or adopt) the PR against the base branch; a later
+          // publish to the same branch moves the same PR's head.
+          stage = 'pr'
+          const session =
+            input.via !== undefined && input.via.kind === 'session' ? input.via.id : undefined
+          const body =
+            (input.body ?? '') +
+            (input.body !== undefined && input.body !== '' ? '\n\n' : '') +
+            `Published from an Autobuild operator sandbox by ${identity}` +
+            (session !== undefined ? ` via orchestrator session ${session}` : '') +
+            ' — agent-authored, not a pipeline build.'
+          const pr = await forge.openPr({
+            workspacePath: resolved.workspacePath,
+            head: branch,
+            base: options.baseBranch,
+            title,
+            body,
+          })
+          // 7. The publication is a repository-journal fact.
+          await append(identity, 'orchestrator.sandbox.published', {
+            operator: identity,
+            environmentId: resolved.environmentId,
+            branch,
+            sha,
+            ...(session !== undefined ? { session } : {}),
+            pr: { number: pr.number, url: pr.url, headSha: pr.headSha },
+          })
+          return { branch, sha, pr: { number: pr.number, url: pr.url, headSha: pr.headSha } }
+        } catch (error) {
+          // 8. Every refusal or failure at steps 1-6 is a journal fact
+          // naming the stage, with credential values redacted from the
+          // message.
+          const message = describeError(error)
+          await append(identity, 'orchestrator.sandbox.publish-failed', {
+            operator: identity,
+            environmentId: resolved.environmentId,
+            stage,
+            message,
+          }).catch(() => {})
+          throw new SandboxOperationError('publish', message, {
+            cause: error instanceof SandboxOperationError ? error.cause : error,
+          })
+        }
+      })
+    },
+
     async reset(identity, input) {
       requireRepo(input.repo)
       const key = `${repo}\0${identity}`
       await serialize(key, async () => {
-        const events = await journalEvents()
+        const events = await readRepoEventsIfRecorded(store, repo)
         const state = operatorState(identity, events)
         const resolved = await capability.describe({ repo, operator: identity })
         await append(identity, 'orchestrator.sandbox.reset', {
@@ -429,7 +662,7 @@ export async function createOperatorSandboxService(
       requireRepo(input.repo)
       const key = `${repo}\0${identity}`
       await serialize(key, async () => {
-        const events = await journalEvents()
+        const events = await readRepoEventsIfRecorded(store, repo)
         const state = operatorState(identity, events)
         // No environment ever provisioned: a no-op, with no fact and no
         // provider traffic beyond the pure describe.

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
+}