@defrex/autobuild 0.8.0

package/packages/core/src/ports/runner/provider-error.ts

@@ -0,0 +1,121 @@
+import type { AgentTurnFailure } from '../types'
+
+/** Optional structured signals exposed by a runtime in addition to its error
+ * text. Unknown hints are deliberately treated as availability failures: that
+ * preserves the existing bounded retry policy and permits an explicitly
+ * configured alternate without hiding credential evidence. */
+export interface ProviderErrorHints {
+  status?: number | null
+  codes?: readonly (string | number | null | undefined)[]
+}
+
+const EXHAUSTION_CODE_PATTERNS = [
+  /(?:^|[_-])(?:billing|payment|quota|credit|balance|budget)(?:[_-]|$)/,
+  /^(?:insufficient|out_of)_(?:quota|credits?|balance|funds)$/,
+  /^usage_(?:limit|quota)(?:_|$)/,
+] as const
+
+const CREDENTIAL_CODE_PATTERNS = [
+  /^(?:auth|authentication|authorization)(?:_|-)/,
+  /^(?:unauthorized|forbidden)$/,
+  /^(?:invalid|expired|missing|revoked)_(?:api_)?(?:key|token|credential)s?$/,
+  /^(?:permission|access)(?:_|-)(?:denied|error|required)$/,
+  /^oauth_org_not_allowed$/,
+] as const
+
+const EXHAUSTION_TEXT_PATTERNS = [
+  /(?:^|[^a-z0-9])(?:quota(?:[_ -](?:exceeded|exhausted|depleted|refreshes?))?|(?:insufficient|exhausted|depleted)[_ -]quota)(?:$|[^a-z0-9])/i,
+  /\busage[_ -]?(?:limit|quota)\b/i,
+  /\b(?:billing|spending|monthly)\s+(?:limit|cap|cycle)\b/i,
+  /\bbilling(?:_error|\s+(?:error|issue|required|disabled))\b/i,
+  /\bpayment\s+(?:is\s+)?required\b/i,
+  /\bsubscription\s+(?:is\s+)?(?:expired|inactive|required|disabled)\b/i,
+  /\b(?:insufficient|no|out of|exhausted|depleted)\s+(?:credits?|balance|funds)\b/i,
+  /\bcredits?\s+(?:are\s+|is\s+)?(?:required|exhausted|depleted)\b/i,
+  /\bbudget\s+(?:is\s+)?(?:exceeded|exhausted|depleted)\b/i,
+] as const
+
+const CREDENTIAL_TEXT_PATTERNS = [
+  /\b(?:authentication|authorization)[_ -](?:failed|required|error|invalid)\b/i,
+  /\bunauthori[sz]ed\b/i,
+  /\bforbidden\b/i,
+  /\b(?:invalid|expired|missing|revoked)[_ -](?:api[_ -]?)?(?:key|token|credentials?)\b/i,
+  /\b(?:api[- ]?key|token|credentials?)\s+(?:is\s+|are\s+)?(?:invalid|expired|missing|revoked)\b/i,
+  /\bpermission(?:_error|\s+(?:denied|required|error))\b/i,
+  /\b(?:do not|does not|don't|doesn't)\s+have\s+permission\b/i,
+  /\b(?:access|request)\s+(?:is\s+)?(?:denied|not permitted)\b/i,
+] as const
+
+/** Classify a provider/SDK-declared turn error without rewriting its message.
+ * Exhaustion evidence intentionally wins over generic 402/403 and permission
+ * evidence: providers commonly wrap usage-limit responses in those shapes. */
+export function classifyProviderError(
+  message: string,
+  hints: ProviderErrorHints = {},
+): AgentTurnFailure {
+  const codes = hints.codes ?? []
+  const exhaustion =
+    hints.status === 402 ||
+    codes.some((code) => code === 402 || matchesCode(code, EXHAUSTION_CODE_PATTERNS)) ||
+    hasHttpStatus(message, [402]) ||
+    EXHAUSTION_TEXT_PATTERNS.some((pattern) => pattern.test(message))
+  if (exhaustion) return { message, permanent: true, cause: 'exhaustion' }
+
+  const credentials =
+    hints.status === 401 ||
+    hints.status === 403 ||
+    codes.some(
+      (code) => code === 401 || code === 403 || matchesCode(code, CREDENTIAL_CODE_PATTERNS),
+    ) ||
+    hasHttpStatus(message, [401, 403]) ||
+    CREDENTIAL_TEXT_PATTERNS.some((pattern) => pattern.test(message))
+  if (credentials) return { message, permanent: true, cause: 'credentials' }
+
+  return { message, permanent: false, cause: 'availability' }
+}
+
+/** Whether another declared target may be tried inside this phase attempt.
+ * Legacy plugins have no cause: preserve their old safe split. */
+export function isAlternateEligible(failure: AgentTurnFailure): boolean {
+  return failure.cause === undefined
+    ? !failure.permanent
+    : failure.cause === 'availability' || failure.cause === 'exhaustion'
+}
+
+/** Final-failure retry behavior remains governed by the compatibility bit. */
+export function mayRetryPhase(failure: AgentTurnFailure): boolean {
+  return !failure.permanent
+}
+
+/** Explicit local configuration failures bypass both alternates and phase retries. */
+export function configurationFailure(message: string): AgentTurnFailure {
+  return { message, permanent: true, cause: 'configuration' }
+}
+
+/** Explicit credential failures bypass both alternates and phase retries. */
+export function credentialFailure(message: string): AgentTurnFailure {
+  return { message, permanent: true, cause: 'credentials' }
+}
+
+function matchesCode(
+  code: string | number | null | undefined,
+  patterns: readonly RegExp[],
+): boolean {
+  if (code === null || code === undefined || typeof code === 'number') return false
+  const normalized = code.trim().toLowerCase()
+  return patterns.some((pattern) => pattern.test(normalized))
+}
+
+function hasHttpStatus(message: string, statuses: readonly number[]): boolean {
+  const alternatives = statuses.join('|')
+  return (
+    new RegExp(
+      `^\\s*(?:(?:http(?:\\/\\d(?:\\.\\d)?)?|status(?:\\s+code)?)\\s*[:=]?\\s*)?(?:${alternatives})\\b`,
+      'i',
+    ).test(message) ||
+    new RegExp(`\\bhttp(?:\\s+status)?\\s*[:=]?\\s*(?:${alternatives})\\b`, 'i').test(message) ||
+    new RegExp(
+      `["']?(?:status|status_code|statusCode)["']?\\s*[:=]\\s*["']?(?:${alternatives})\\b`,
+    ).test(message)
+  )
+}

package/packages/core/src/ports/runner/routing.ts

@@ -0,0 +1,234 @@
+/**
+ * Eager runtime/model/args role resolution (SPEC §9, §16.1). Primary
+ * fields and the ordered alternate list inherit independently from the
+ * reserved `[roles.default]` entry. A declared role list, including `[]`,
+ * replaces the inherited list wholesale; each entry overlays that concrete
+ * role's effective primary axes and is validated at construction.
+ */
+import type { AgentRunner } from '../types'
+import { serves, type RuntimeRegistration, type RuntimeRegistry } from './runtime'
+
+/** A resolved runtime/model pair plus the adapter to run it (§9). */
+export interface ResolvedRuntime {
+  runner: AgentRunner
+  /** The registry key == the frozen `session.started.runner` value. */
+  runtime: string
+  /** Absent ⇒ the adapter's built-in default model. */
+  model?: string
+  /** Extra CLI argv tokens, preserved in declared order. */
+  args: readonly string[]
+  /** Session-stream capability passthrough from the registration (SPEC §9).
+   * Absent ⇒ this runtime's sessions get no stream. */
+  openSessionStream?: RuntimeRegistration['openSessionStream']
+}
+
+/** A role's primary target plus its failure-triggered targets in declaration order. */
+export interface ResolvedRole extends ResolvedRuntime {
+  /** Wall-clock budget shared by the logical role's primary and alternates. */
+  sessionBudgetSeconds: number
+  alternates: readonly ResolvedRuntime[]
+}
+
+export interface RuntimeAxes {
+  runtime?: string
+  model?: string
+  args?: readonly string[]
+  /** Deprecated compatibility field; accepted by the schema but ignored. */
+  extensions?: readonly string[]
+}
+
+/** One role entry as it arrives from `[roles]`: all fields are optional. */
+export interface RuntimeSpec extends RuntimeAxes {
+  /** Inherits from [roles.default], then the policy fallback. */
+  sessionBudgetSeconds?: number
+  alternates?: readonly RuntimeAxes[]
+}
+
+export class RuntimeConfigError extends Error {
+  constructor(readonly problems: string[]) {
+    super(
+      `invalid runtime/model/args configuration (SPEC §9):\n` +
+        problems.map((p) => `  - ${p}`).join('\n'),
+    )
+    this.name = 'RuntimeConfigError'
+  }
+}
+
+export interface RuntimeResolver {
+  /** Resolve the earliest declared role/alias, otherwise `[roles.default]`. */
+  resolve(role: string, ...aliases: string[]): ResolvedRole
+}
+
+function runtimeNames(registry: RuntimeRegistry): string {
+  return Object.keys(registry).join(', ') || 'none'
+}
+
+/** The declared model families for one runtime, for error messages. */
+function servedModels(registration: RuntimeRegistration): string {
+  return registration.servesModels.join(', ') || 'no models'
+}
+
+function mergeAxes(spec: RuntimeAxes, base: RuntimeAxes): RuntimeAxes {
+  const runtime = spec.runtime ?? base.runtime
+  const model = spec.model ?? base.model
+  return {
+    ...(runtime !== undefined ? { runtime } : {}),
+    ...(model !== undefined ? { model } : {}),
+    args: spec.args ?? base.args ?? [],
+  }
+}
+
+/** Resolve one already-merged raw target. Registry defaults apply only when no
+ * configured model exists on that target. Problems aggregate instead of throw. */
+function resolveAxes(
+  axes: RuntimeAxes,
+  registry: RuntimeRegistry,
+  label: string,
+  problems: string[],
+): ResolvedRuntime | undefined {
+  const runtime = axes.runtime
+  if (runtime === undefined || runtime.trim().length === 0) {
+    problems.push(
+      `${label} is missing required runtime. Add:\n\n` +
+        `[roles.default]\n` +
+        `runtime = "<runtime>"\n\n` +
+        `Available runtimes: ${runtimeNames(registry)}`,
+    )
+    return undefined
+  }
+  if (!Object.hasOwn(registry, runtime)) {
+    problems.push(
+      `${label} resolves to runtime "${runtime}", which is not registered ` +
+        `(registered runtimes: ${runtimeNames(registry)})`,
+    )
+    return undefined
+  }
+  const reg = registry[runtime]!
+
+  const model = axes.model ?? reg.defaultModel
+  const modelValid = model === undefined || serves(reg, model)
+  if (!modelValid) {
+    problems.push(
+      `${label} resolves runtime "${runtime}" with model "${model}", but ` +
+        `"${runtime}" serves only [${servedModels(reg)}]`,
+    )
+  }
+
+  const args = axes.args ?? []
+  const ownedArgs = new Set(reg.ownedArgs ?? [])
+  for (const arg of args) {
+    if (arg === reg.promptBoundary) {
+      problems.push(
+        `${label} argument ${JSON.stringify(arg)} conflicts with the prompt boundary for runtime "${runtime}". ` +
+          'Remove it because Autobuild owns and appends this prompt separator.',
+      )
+      continue
+    }
+
+    const spelling = arg.startsWith('--') ? arg.split('=', 1)[0]! : arg
+    const owned =
+      ownedArgs.has(spelling) ||
+      [...ownedArgs].some(
+        (candidate) =>
+          candidate.startsWith('-') &&
+          !candidate.startsWith('--') &&
+          candidate.length === 2 &&
+          arg.startsWith(candidate) &&
+          arg.length > candidate.length,
+      )
+    if (owned) {
+      problems.push(
+        `${label} argument ${JSON.stringify(arg)} conflicts with an option owned by runtime "${runtime}"`,
+      )
+    }
+  }
+
+  if (!modelValid) return undefined
+
+  return {
+    runner: reg.runner,
+    runtime,
+    ...(model !== undefined ? { model } : {}),
+    args,
+    ...(reg.openSessionStream !== undefined ? { openSessionStream: reg.openSessionStream } : {}),
+  }
+}
+
+function resolveRole(
+  spec: RuntimeSpec,
+  defaultSpec: RuntimeSpec,
+  policySessionBudgetSeconds: number,
+  registry: RuntimeRegistry,
+  label: string,
+  problems: string[],
+): ResolvedRole | undefined {
+  const primaryAxes = mergeAxes(spec, defaultSpec)
+  const primary = resolveAxes(primaryAxes, registry, label, problems)
+  const alternateSpecs = spec.alternates ?? defaultSpec.alternates ?? []
+  const alternates: ResolvedRuntime[] = []
+  alternateSpecs.forEach((alternate, index) => {
+    const resolved = resolveAxes(
+      mergeAxes(alternate, primaryAxes),
+      registry,
+      `${label}.alternates[${index}]`,
+      problems,
+    )
+    if (resolved !== undefined) alternates.push(resolved)
+  })
+  return primary === undefined
+    ? undefined
+    : {
+        ...primary,
+        sessionBudgetSeconds:
+          spec.sessionBudgetSeconds ??
+          defaultSpec.sessionBudgetSeconds ??
+          policySessionBudgetSeconds,
+        alternates,
+      }
+}
+
+/** Build and eagerly validate the complete role resolver. */
+export function createRuntimeResolver(
+  registry: RuntimeRegistry,
+  roles: Record<string, RuntimeSpec>,
+  policySessionBudgetSeconds = 3600,
+): RuntimeResolver {
+  const problems: string[] = []
+  const defaultSpec = roles.default ?? {}
+  const resolvedDefault = resolveRole(
+    defaultSpec,
+    {},
+    policySessionBudgetSeconds,
+    registry,
+    '[roles.default]',
+    problems,
+  )
+
+  const resolvedRoles: Record<string, ResolvedRole> = Object.create(null)
+  for (const [role, spec] of Object.entries(roles)) {
+    if (role === 'default') continue
+    const resolved = resolveRole(
+      spec,
+      defaultSpec,
+      policySessionBudgetSeconds,
+      registry,
+      `[roles.${role}]`,
+      problems,
+    )
+    if (resolved !== undefined) resolvedRoles[role] = resolved
+  }
+
+  if (problems.length > 0) throw new RuntimeConfigError(problems)
+  const fallback = resolvedDefault!
+
+  return {
+    resolve(role: string, ...aliases: string[]): ResolvedRole {
+      for (const key of [role, ...aliases]) {
+        if (key === 'default') return fallback
+        const resolved = resolvedRoles[key]
+        if (resolved !== undefined) return resolved
+      }
+      return fallback
+    },
+  }
+}

package/packages/core/src/ports/runner/runtime.ts

@@ -0,0 +1,214 @@
+/**
+ * The runtime registry (SPEC §9): the "adapter registry" the spec says adding
+ * a runtime should touch — and ONLY it. Each registration pairs an AgentRunner
+ * adapter with its capabilities: model families/default for compatibility
+ * validation, plus an
+ * optional tool-free, non-phase one-shot completion. Keeping capabilities HERE, in a
+ * wrapper around the adapter, is deliberate: the `AgentRunner` port itself is
+ * frozen (spec "out of scope" — no renaming/extending it), so capability data
+ * lives beside the registry rather than inside the port. The kernel never
+ * learns a runtime's name; it asks the resolver, and the resolver reads this.
+ *
+ * "runtime" is the config-surface vocabulary for what the code has always
+ * called a runner: the registry KEY is the runtime name (== the frozen
+ * `session.started.runner` value the build-runner records), while the adapter's
+ * own `.name` is a separate, also-frozen thing that fills
+ * `AgentSessionHandle.runner`.
+ */
+import type { AgentRunner, SessionStreamSink } from '../types'
+import type { OneShotCompletion } from './one-shot'
+
+/** Bracket metadata for a session stream's `data-ab-session` part. */
+export interface SessionStreamInfo {
+  session: string
+  role: string
+  runner: string
+  model?: string
+  phase: string
+  round?: number
+}
+
+export interface RuntimeUsabilityInput {
+  cwd: string
+  env: Readonly<Record<string, string | undefined>>
+  /** Exact configured models the prospective init profile will write. */
+  models: readonly string[]
+}
+
+export interface RuntimeUsabilityDiagnostic {
+  usable: boolean
+  /** Human-readable prerequisite/auth result. Must not contain credentials. */
+  reason: string
+}
+
+/** Boolean remains accepted for backward compatibility with plugin probes. */
+export type RuntimeUsabilityResult = boolean | RuntimeUsabilityDiagnostic
+
+/** Optional onboarding probe. Absence means init must not suggest the runtime. */
+export type RuntimeUsabilityProbe = (
+  input: RuntimeUsabilityInput,
+) => Promise<RuntimeUsabilityResult>
+
+export interface RuntimeRegistration {
+  /** The adapter behind this runtime (§9). */
+  runner: AgentRunner
+  /**
+   * Optional tool-free, non-resumable, non-phase completion capability. Its
+   * absence is a normal capability boundary, not a configuration error;
+   * deterministic callers decide their own fail-safe fallback.
+   */
+  oneShot?: OneShotCompletion
+  /**
+   * Optional session-stream capability (SPEC §9): given a bracket-scoped
+   * sink, create the runtime's one stream for this session bracket and
+   * return its store id (or `undefined` to decline streaming for the
+   * bracket). Its absence means the runtime emits no parts and its sessions
+   * have no stream — a supported boundary, not a configuration error.
+   */
+  openSessionStream?: (
+    sink: SessionStreamSink,
+    info: SessionStreamInfo,
+  ) => Promise<string | undefined>
+  /** Runtime-local prerequisite/auth check used only by `ab init`. */
+  initUsable?: RuntimeUsabilityProbe
+  /**
+   * Model-id PREFIXES this runtime can serve, e.g. `['openai/',
+   * 'kimi-coding/']`. Prefix families — not an exhaustive id list — because the
+   * model landscape moves faster than the pipeline and the spec forbids
+   * hardcoding served ids: a new model from either provider validates without
+   * editing this list. These families are validation data only: role resolution
+   * never searches them to choose or substitute a runtime. `serves()` below is
+   * the matcher.
+   */
+  servesModels: string[]
+  /**
+   * This runtime's own default model, used when a step selects the runtime but
+   * names no model. When set, it must match `servesModels` like any other
+   * resolved model. `undefined` ⇒ the adapter's un-named built-in default (e.g.
+   * Claude's subscription default) — the path that preserves no-model behavior.
+   */
+  defaultModel?: string
+  /** Model-selection and parsed protocol/output-mode spellings owned by the
+   * adapter, plus documented aliases of those options. Every other role arg
+   * remains freeform, including options the adapter may also emit. */
+  ownedArgs?: readonly string[]
+  /**
+   * Exact structural token Autobuild appends before the positional prompt.
+   * Role args may not duplicate this boundary.
+   */
+  promptBoundary?: string
+}
+
+/** name → registration. The one place a runtime's name lives (§9). */
+export type RuntimeRegistry = Record<string, RuntimeRegistration>
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/**
+ * Validate an untrusted plugin factory result at the composition boundary.
+ * TypeScript's structural types disappear at runtime, so factories must not be
+ * able to smuggle a partial adapter or inconsistent capability declaration
+ * into the eager role resolver.
+ */
+export function validateRuntimeRegistration(value: unknown): RuntimeRegistration {
+  if (!isObject(value)) {
+    throw new Error('must be an object')
+  }
+
+  const runner = value.runner
+  if (!isObject(runner)) {
+    throw new Error('runner must be an AgentRunner-shaped object')
+  }
+  if (typeof runner.name !== 'string' || runner.name.trim().length === 0) {
+    throw new Error('runner.name must be a nonblank string')
+  }
+  for (const method of ['start', 'continue', 'end'] as const) {
+    if (typeof runner[method] !== 'function') {
+      throw new Error(`runner.${method} must be a function`)
+    }
+  }
+
+  const servesModels = value.servesModels
+  if (
+    !Array.isArray(servesModels) ||
+    servesModels.some(
+      (family) =>
+        typeof family !== 'string' ||
+        family.trim().length === 0 ||
+        (family.includes('*') && family !== '*/*'),
+    )
+  ) {
+    throw new Error(
+      'servesModels must be an array of nonblank strings containing prefixes or the provider-qualified wildcard "*/*"',
+    )
+  }
+
+  const defaultModel = value.defaultModel
+  if (
+    defaultModel !== undefined &&
+    (typeof defaultModel !== 'string' || defaultModel.trim().length === 0)
+  ) {
+    throw new Error('defaultModel must be a nonblank string when provided')
+  }
+
+  const ownedArgs = value.ownedArgs
+  if (
+    ownedArgs !== undefined &&
+    (!Array.isArray(ownedArgs) ||
+      ownedArgs.some(
+        (arg) => typeof arg !== 'string' || !arg.startsWith('-') || arg.trim().length === 0,
+      ) ||
+      new Set(ownedArgs).size !== ownedArgs.length)
+  ) {
+    throw new Error('ownedArgs must be a unique array of nonblank option spellings')
+  }
+
+  const promptBoundary = value.promptBoundary
+  if (
+    promptBoundary !== undefined &&
+    (typeof promptBoundary !== 'string' || promptBoundary.trim().length === 0)
+  ) {
+    throw new Error('promptBoundary must be a nonblank string when provided')
+  }
+
+  const oneShot = value.oneShot
+  if (oneShot !== undefined && (!isObject(oneShot) || typeof oneShot.complete !== 'function')) {
+    throw new Error('oneShot.complete must be a function when provided')
+  }
+
+  if (value.openSessionStream !== undefined && typeof value.openSessionStream !== 'function') {
+    throw new Error('openSessionStream must be a function when provided')
+  }
+
+  if (value.initUsable !== undefined && typeof value.initUsable !== 'function') {
+    throw new Error('initUsable must be a function when provided')
+  }
+
+  const registration = value as unknown as RuntimeRegistration
+  if (typeof defaultModel === 'string' && !serves(registration, defaultModel)) {
+    throw new Error(
+      `defaultModel "${defaultModel}" is not served by servesModels ` +
+        `[${servesModels.join(', ')}]`,
+    )
+  }
+  return registration
+}
+
+/**
+ * Does this registration serve `model`? Prefix-family match:
+ * `openai/gpt-5.6-sol` is served by a registration declaring `openai/`. Empty
+ * `servesModels` serves nothing (a runtime that can run only with its adapter's
+ * un-named built-in default, never with a configured model id).
+ */
+export function serves(reg: RuntimeRegistration, model: string): boolean {
+  return reg.servesModels.some((family) =>
+    family === '*/*' ? isProviderQualified(model) : model.startsWith(family),
+  )
+}
+
+function isProviderQualified(model: string): boolean {
+  const slash = model.indexOf('/')
+  return slash > 0 && slash < model.length - 1
+}

package/packages/core/src/ports/runner/session-env.ts

@@ -0,0 +1,34 @@
+/**
+ * Build the environment passed to an agent runtime for one turn.
+ *
+ * Scoped values (AB_STORE, AB_PHASE, and so on) override the ambient process
+ * environment. The distribution-owned launcher is then forced to the front of
+ * PATH so an inherited executable with the public `ab` name cannot shadow the
+ * Autobuild CLI. A fresh object is returned on every call; neither input nor
+ * process.env is mutated, which keeps concurrent builds isolated.
+ */
+import { delimiter } from 'node:path'
+import { distributionPath } from '../../distribution'
+
+/** Private command directory shipped by this Autobuild distribution. */
+export const AGENT_BIN_DIR = distributionPath('bin', 'agent')
+
+export function sessionEnv(
+  scoped: Readonly<Record<string, string>>,
+  ambient: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(ambient)) {
+    if (value !== undefined) env[key] = value
+  }
+  Object.assign(env, scoped)
+
+  const inheritedPath = env.PATH
+  const inheritedEntries =
+    inheritedPath === undefined || inheritedPath === ''
+      ? []
+      : inheritedPath.split(delimiter).filter((entry) => entry !== AGENT_BIN_DIR)
+  env.PATH = [AGENT_BIN_DIR, ...inheritedEntries].join(delimiter)
+
+  return env
+}