@1aboveio/skills 1.0.15 → 1.0.16

package/skills/engineering/harness-runtime/agent-catalog.mjs

@@ -0,0 +1,928 @@
+// agent-catalog — consumer bridge to the harness-owned agent catalog.
+//
+// The skill side no longer owns a model ladder. A workflow names four roles
+// (implementer, explorer, diagnoser, reviewer) and the *harness* decides which
+// model fills each one and how that role is launched on this host. The resolver
+// is a separate executable spoken to over one versioned JSON request on stdin
+// and one JSON response on stdout:
+//
+//   { version: 1, harness, cwd, available: [{ model, nativeModel?, supportedEfforts? }],
+//     userRoot?, projectTrusted?, foregroundModel?, fallbackToForeground?,
+//     launchCapabilities?: { model, effort, instructions },
+//     hostPreferences?: { developer|explorer|reviewer: { model?, effort? } },
+//     overrides?: { implementer|explorer|diagnoser|reviewer: { model?, effort? } },
+//     tiers?: { tiers: { name: { members: [], candidates: [] } } } }
+//   → { version: 1, ok, harness, catalogDigest, slots: { … }, diagnostics: [] }
+//
+// PRECEDENCE IS THE HARNESS'S, NOT OURS. A task override outranks a host
+// preference, which outranks the role default; the foreground model is only a
+// fallback where the host says it may be used. This module carries those inputs
+// through unchanged and infers none of them: it never states what a host can
+// launch, never invents a tier or a candidate, and never turns an unavailable
+// pin into a nearby substitute.
+//
+// This module is the only place the skill side talks to it. It resolves the
+// command, bounds the child, validates the response, and reports an explicit
+// blocked result — it never falls back to a skill-owned picker, never guesses a
+// model, and never installs or fetches anything.
+//
+// WHY A SCRIPT AND NOT PROSE. "Ask the harness which model to use" degrades, in
+// prose, to the agent re-deriving a ladder from training data: the exact list
+// this change deletes. Mechanized, one module owns the child boundary, the
+// protocol version, and the fail-closed answer, so a missing resolver is a
+// reported block rather than a quiet return to the old behaviour.
+//
+// COMMAND RESOLUTION (no shell, no implicit install — ever):
+//   PI_AGENT_CATALOG_COMMAND  JSON argv array: '["node","/abs/agent-catalog.mjs"]'
+//                             (preferred when arguments are needed), or a bare
+//                             executable token: 'pi-agent-catalog'.
+//   default                   pi-agent-catalog on PATH.
+// A bare token cannot carry arguments — that is deliberate, so no quoting rule
+// sneaks shell semantics in. Nothing here runs npm/npx, resolves a sibling
+// checkout, or reads a registry.
+//
+// SUPPORTED LAYOUTS. The module is imported by first-party consumers as
+// `../../harness-runtime/agent-catalog.mjs` from their own `scripts/` directory,
+// so one specifier resolves both in the source tree
+// (`skills/engineering/{resolve-issues,harness-runtime}`) and in the native flat
+// install (`~/.agents/skills/{resolve-issues,harness-runtime}`). No path in this
+// file is relative to a source-domain layout.
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+
+export const AGENT_CATALOG_PROTOCOL_VERSION = 1
+export const DEFAULT_AGENT_CATALOG_COMMAND = 'pi-agent-catalog'
+export const AGENT_CATALOG_COMMAND_ENV = 'PI_AGENT_CATALOG_COMMAND'
+
+// Bounds: a resolver that floods stdout or hangs is a reported block, never an
+// unbounded read or an indefinite wait.
+export const MAX_AGENT_CATALOG_OUTPUT_BYTES = 256 * 1024
+export const MAX_AGENT_CATALOG_DIAGNOSTIC_CHARS = 4096
+export const DEFAULT_AGENT_CATALOG_TIMEOUT_MS = 30_000
+
+export const CATALOG_HARNESSES = Object.freeze(['pi', 'codex', 'claude-code'])
+export const CATALOG_SLOTS = Object.freeze(['implementer', 'explorer', 'diagnoser', 'reviewer'])
+export const CATALOG_ROLES = Object.freeze(['developer', 'explorer', 'reviewer'])
+// Each slot has one role. `diagnoser` maps the developer role: escalation work is
+// implementation work, and it keeps the developer instructions with it.
+export const CATALOG_SLOT_ROLES = Object.freeze({
+  implementer: 'developer',
+  explorer: 'explorer',
+  diagnoser: 'developer',
+  reviewer: 'reviewer',
+})
+export const CATALOG_EFFORTS = Object.freeze(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+export const AGENT_CATALOG_BLOCK_CODES = Object.freeze({
+  CAPABILITIES_MISSING: 'capabilities-missing',
+  CAPABILITIES_INVALID: 'capabilities-invalid',
+  REQUEST_INVALID: 'catalog-request-invalid',
+  COMMAND_INVALID: 'catalog-command-invalid',
+  COMMAND_UNAVAILABLE: 'catalog-unavailable',
+  COMMAND_FAILED: 'catalog-failed',
+  OUTPUT_INVALID: 'catalog-output-invalid',
+  RESPONSE_INVALID: 'catalog-response-invalid',
+  DECLINED: 'catalog-declined',
+})
+
+const CAPABILITY_FIELDS = new Set([
+  'harness',
+  'available',
+  'foregroundModel',
+  'fallbackToForeground',
+  'launchCapabilities',
+  'hostPreferences',
+  'overrides',
+  'tiers',
+  'userRoot',
+  'projectTrusted',
+  'cwd',
+])
+const AVAILABLE_FIELDS = new Set(['model', 'nativeModel', 'supportedEfforts'])
+const OVERRIDE_FIELDS = new Set(['model', 'effort'])
+// The three controls a native host either exposes or does not. Omission is not
+// "probably fine": a partially advertised set cannot be told apart from an
+// unsupported one, so it is rejected instead of being completed by guesswork.
+const LAUNCH_CAPABILITY_FIELDS = Object.freeze(['model', 'effort', 'instructions'])
+const TIER_POLICY_FIELDS = new Set(['tiers'])
+const TIER_SPEC_FIELDS = new Set(['members', 'candidates'])
+const TIER_CANDIDATE_FIELDS = new Set(['model', 'crossProvider'])
+const WORKER_FIELDS = new Set([
+  'role',
+  'model',
+  'nativeModel',
+  'effort',
+  'instructions',
+  'selection',
+  'launch',
+  'catalogDigest',
+  'diagnostics',
+])
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+/** `provider/model`, the only form the catalog resolves a tier member against. */
+function providerModelId(value) {
+  if (!nonEmptyString(value)) return false
+  const trimmed = value.trim()
+  const slash = trimmed.indexOf('/')
+  return slash > 0 && slash < trimmed.length - 1 && !/\s/.test(trimmed)
+}
+
+function blocked(code, reason, extra = {}) {
+  return { ok: false, blocked: { code, reason, ...extra } }
+}
+
+function snippet(text, limit = 400) {
+  const value = String(text ?? '').replace(/\s+/g, ' ').trim()
+  return value.length > limit ? `${value.slice(0, limit)}…` : value
+}
+
+/** Everything a blocked result may name about the child it tried to run. */
+function commandLabel(command) {
+  return command ? [command.executable, ...command.args].join(' ') : null
+}
+
+/**
+ * Parse a command spec: a JSON argv array (preferred; it can carry arguments),
+ * or one bare executable token resolved on PATH.
+ */
+export function parseCommandSpec(value) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID, 'the catalog command is empty')
+  }
+  if (text.startsWith('[')) {
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch (error) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID,
+        `${AGENT_CATALOG_COMMAND_ENV} is not a valid JSON argv array: ${error.message}`,
+      )
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(nonEmptyString)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID,
+        `${AGENT_CATALOG_COMMAND_ENV} must be a non-empty JSON array of non-empty strings`,
+      )
+    }
+    return {
+      ok: true,
+      command: { executable: parsed[0], args: parsed.slice(1), source: 'json-argv' },
+    }
+  }
+  if (/^[{"]/.test(text)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID,
+      `${AGENT_CATALOG_COMMAND_ENV} must be a JSON argv array or a bare executable token`,
+    )
+  }
+  if (/\s/.test(text)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID,
+      `${AGENT_CATALOG_COMMAND_ENV} holds whitespace; use a JSON argv array so no shell-like quoting is implied`,
+    )
+  }
+  return { ok: true, command: { executable: text, args: [], source: 'executable' } }
+}
+
+/** Resolve `PI_AGENT_CATALOG_COMMAND`, defaulting to `pi-agent-catalog` on PATH. */
+export function resolveCatalogCommand(env = process.env) {
+  const configured = env?.[AGENT_CATALOG_COMMAND_ENV]
+  if (configured !== undefined && typeof configured !== 'string') {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.COMMAND_INVALID,
+      `${AGENT_CATALOG_COMMAND_ENV} must be a string`,
+    )
+  }
+  const spec = configured === undefined || configured.trim() === ''
+    ? DEFAULT_AGENT_CATALOG_COMMAND
+    : configured
+  return parseCommandSpec(spec)
+}
+
+function normalizeAvailable(value, label = 'available') {
+  if (value === undefined) return { ok: true, available: [] }
+  if (!Array.isArray(value)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, `${label} must be an array`)
+  }
+  const available = []
+  for (const [index, entry] of value.entries()) {
+    if (!isRecord(entry)) {
+      return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, `${label}[${index}] must be an object`)
+    }
+    const unknown = Object.keys(entry).filter((field) => !AVAILABLE_FIELDS.has(field))
+    if (unknown.length > 0) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${label}[${index}] has unknown field(s): ${unknown.join(', ')}`,
+      )
+    }
+    if (!nonEmptyString(entry.model)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${label}[${index}].model must be the canonical provider/model id`,
+      )
+    }
+    if (entry.nativeModel !== undefined && !nonEmptyString(entry.nativeModel)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${label}[${index}].nativeModel must be a non-empty host model id`,
+      )
+    }
+    if (entry.supportedEfforts !== undefined) {
+      if (!Array.isArray(entry.supportedEfforts) || entry.supportedEfforts.length === 0) {
+        return blocked(
+          AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+          `${label}[${index}].supportedEfforts must be a non-empty array`,
+        )
+      }
+      const unknownEffort = entry.supportedEfforts.filter((effort) => !CATALOG_EFFORTS.includes(effort))
+      if (unknownEffort.length > 0) {
+        return blocked(
+          AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+          `${label}[${index}].supportedEfforts has unknown value(s): ${unknownEffort.join(', ')}`,
+        )
+      }
+    }
+    available.push({
+      model: entry.model.trim(),
+      ...(entry.nativeModel !== undefined ? { nativeModel: entry.nativeModel.trim() } : {}),
+      ...(entry.supportedEfforts !== undefined ? { supportedEfforts: [...entry.supportedEfforts] } : {}),
+    })
+  }
+  return { ok: true, available }
+}
+
+function normalizeOverride(value, label, allowedFields = OVERRIDE_FIELDS) {
+  if (!isRecord(value)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, `${label} must be an object`)
+  }
+  const unknown = Object.keys(value).filter((field) => !allowedFields.has(field))
+  if (unknown.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} has unknown field(s): ${unknown.join(', ')}`,
+    )
+  }
+  if (value.model !== undefined && !nonEmptyString(value.model)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, `${label}.model must be a model id`)
+  }
+  if (value.effort !== undefined && !CATALOG_EFFORTS.includes(value.effort)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label}.effort must be one of ${CATALOG_EFFORTS.join('|')}`,
+    )
+  }
+  const override = {
+    ...(value.model !== undefined ? { model: value.model.trim() } : {}),
+    ...(value.effort !== undefined ? { effort: value.effort } : {}),
+  }
+  return { ok: true, override: Object.keys(override).length > 0 ? override : null }
+}
+
+/**
+ * One map of `{ model?, effort? }` preferences. Task overrides are keyed by slot
+ * and host preferences by role, so the allowed keys and the label are arguments.
+ */
+function normalizeOverrides(value, { allowed = CATALOG_SLOTS, label = 'overrides' } = {}) {
+  if (value === undefined || value === null) return { ok: true, overrides: {} }
+  if (!isRecord(value)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, `${label} must be an object`)
+  }
+  const overrides = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (!allowed.includes(key)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${label} names unknown key "${key}"; expected ${allowed.join('|')}`,
+      )
+    }
+    const normalized = normalizeOverride(entry, `${label}.${key}`)
+    if (!normalized.ok) return normalized
+    if (normalized.override) overrides[key] = normalized.override
+  }
+  return { ok: true, overrides }
+}
+
+/** The launch controls this host advertises for the current turn. */
+function normalizeLaunchCapabilities(value, label = 'launchCapabilities') {
+  if (value === undefined || value === null) return { ok: true, launchCapabilities: null }
+  if (!isRecord(value)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} must be an object with a boolean ${LAUNCH_CAPABILITY_FIELDS.join(', ')}`,
+    )
+  }
+  const unknown = Object.keys(value).filter((field) => !LAUNCH_CAPABILITY_FIELDS.includes(field))
+  if (unknown.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} has unknown field(s): ${unknown.join(', ')}`,
+    )
+  }
+  const missing = LAUNCH_CAPABILITY_FIELDS.filter((field) => !Object.hasOwn(value, field))
+  if (missing.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} is missing field(s): ${missing.join(', ')}; advertise each control explicitly rather than leaving it to be inferred`,
+    )
+  }
+  for (const field of LAUNCH_CAPABILITY_FIELDS) {
+    if (typeof value[field] !== 'boolean') {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${label}.${field} must be a boolean`,
+      )
+    }
+  }
+  return {
+    ok: true,
+    launchCapabilities: {
+      model: value.model,
+      effort: value.effort,
+      instructions: value.instructions,
+    },
+  }
+}
+
+function normalizeTierCandidates(value, label) {
+  if (!Array.isArray(value)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} must be an array of provider/model ids or { model, crossProvider? } objects`,
+    )
+  }
+  const candidates = []
+  for (const [index, entry] of value.entries()) {
+    const entryLabel = `${label}[${index}]`
+    if (typeof entry === 'string') {
+      if (!providerModelId(entry)) {
+        return blocked(
+          AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+          `${entryLabel} must be a provider/model id; a bare model name is never a tier candidate`,
+        )
+      }
+      candidates.push(entry.trim())
+      continue
+    }
+    if (!isRecord(entry)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${entryLabel} must be a provider/model id or a { model, crossProvider? } object`,
+      )
+    }
+    const unknown = Object.keys(entry).filter((field) => !TIER_CANDIDATE_FIELDS.has(field))
+    if (unknown.length > 0) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${entryLabel} has unknown field(s): ${unknown.join(', ')}`,
+      )
+    }
+    if (!providerModelId(entry.model)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${entryLabel}.model must be a provider/model id`,
+      )
+    }
+    if (entry.crossProvider !== undefined && typeof entry.crossProvider !== 'boolean') {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${entryLabel}.crossProvider must be a boolean`,
+      )
+    }
+    candidates.push({
+      model: entry.model.trim(),
+      ...(entry.crossProvider !== undefined ? { crossProvider: entry.crossProvider } : {}),
+    })
+  }
+  return { ok: true, candidates }
+}
+
+/**
+ * Tier membership and ordered candidates. Membership is a statement about which
+ * models belong together; candidates are the only substitution the catalog may
+ * make, so both are forwarded exactly as given — nothing here completes a tier.
+ */
+function normalizeTierPolicy(value, label = 'tiers') {
+  if (value === undefined || value === null) return { ok: true, tiers: null }
+  if (!isRecord(value)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} must be an object of { tiers: { name: { members, candidates } } }`,
+    )
+  }
+  const unknownPolicy = Object.keys(value).filter((field) => !TIER_POLICY_FIELDS.has(field))
+  if (unknownPolicy.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label} has unknown field(s): ${unknownPolicy.join(', ')}`,
+    )
+  }
+  if (!isRecord(value.tiers)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `${label}.tiers must be an object keyed by tier name`,
+    )
+  }
+  const tiers = {}
+  for (const [name, spec] of Object.entries(value.tiers)) {
+    const specLabel = `${label}.tiers.${name}`
+    if (!isRecord(spec)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${specLabel} must be an object with members and candidates`,
+      )
+    }
+    const unknownSpec = Object.keys(spec).filter((field) => !TIER_SPEC_FIELDS.has(field))
+    if (unknownSpec.length > 0) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${specLabel} has unknown field(s): ${unknownSpec.join(', ')}`,
+      )
+    }
+    if (!Array.isArray(spec.members)) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `${specLabel}.members must be an array of provider/model ids`,
+      )
+    }
+    const members = []
+    for (const [index, member] of spec.members.entries()) {
+      if (!providerModelId(member)) {
+        return blocked(
+          AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+          `${specLabel}.members[${index}] must be a provider/model id`,
+        )
+      }
+      members.push(member.trim())
+    }
+    const candidates = normalizeTierCandidates(spec.candidates, `${specLabel}.candidates`)
+    if (!candidates.ok) return candidates
+    tiers[name] = { members, candidates: candidates.candidates }
+  }
+  return { ok: true, tiers: { tiers } }
+}
+
+/**
+ * Validate one capabilities document: the per-turn host evidence a caller writes
+ * to disk for `--capabilities <path>`. Unknown fields fail closed, because a
+ * silently ignored typo (`avaliable`) would otherwise reach the catalog as an
+ * empty availability list.
+ */
+export function normalizeCapabilities(value, { path = null } = {}) {
+  if (!isRecord(value)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID, 'capabilities must be a JSON object', { path })
+  }
+  const unknown = Object.keys(value).filter((field) => !CAPABILITY_FIELDS.has(field))
+  if (unknown.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `capabilities has unknown field(s): ${unknown.join(', ')}`,
+      { path },
+    )
+  }
+  if (value.harness !== undefined && !CATALOG_HARNESSES.includes(value.harness)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `capabilities.harness must be one of ${CATALOG_HARNESSES.join('|')}`,
+      { path },
+    )
+  }
+  const available = normalizeAvailable(value.available, 'capabilities.available')
+  if (!available.ok) return { ...available, blocked: { ...available.blocked, path } }
+  for (const field of ['foregroundModel', 'userRoot', 'cwd']) {
+    if (value[field] !== undefined && !nonEmptyString(value[field])) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+        `capabilities.${field} must be a non-empty string`,
+        { path },
+      )
+    }
+  }
+  if (value.projectTrusted !== undefined && typeof value.projectTrusted !== 'boolean') {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      'capabilities.projectTrusted must be a boolean',
+      { path },
+    )
+  }
+  const overrides = normalizeOverrides(value.overrides)
+  if (!overrides.ok) return { ...overrides, blocked: { ...overrides.blocked, path } }
+  const hostPreferences = normalizeOverrides(value.hostPreferences, {
+    allowed: CATALOG_ROLES,
+    label: 'capabilities.hostPreferences',
+  })
+  if (!hostPreferences.ok) return { ...hostPreferences, blocked: { ...hostPreferences.blocked, path } }
+  const launchCapabilities = normalizeLaunchCapabilities(value.launchCapabilities, 'capabilities.launchCapabilities')
+  if (!launchCapabilities.ok) return { ...launchCapabilities, blocked: { ...launchCapabilities.blocked, path } }
+  if (value.fallbackToForeground !== undefined && typeof value.fallbackToForeground !== 'boolean') {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      'capabilities.fallbackToForeground must be a boolean',
+      { path },
+    )
+  }
+  const tiers = normalizeTierPolicy(value.tiers, 'capabilities.tiers')
+  if (!tiers.ok) return { ...tiers, blocked: { ...tiers.blocked, path } }
+  return {
+    ok: true,
+    capabilities: {
+      ...(value.harness !== undefined ? { harness: value.harness } : {}),
+      available: available.available,
+      ...(value.foregroundModel !== undefined ? { foregroundModel: value.foregroundModel.trim() } : {}),
+      ...(Object.keys(overrides.overrides).length > 0 ? { overrides: overrides.overrides } : {}),
+      ...(Object.keys(hostPreferences.overrides).length > 0
+        ? { hostPreferences: hostPreferences.overrides }
+        : {}),
+      ...(launchCapabilities.launchCapabilities
+        ? { launchCapabilities: launchCapabilities.launchCapabilities }
+        : {}),
+      ...(value.fallbackToForeground !== undefined
+        ? { fallbackToForeground: value.fallbackToForeground }
+        : {}),
+      ...(tiers.tiers ? { tiers: tiers.tiers } : {}),
+      ...(value.userRoot !== undefined ? { userRoot: value.userRoot.trim() } : {}),
+      ...(value.projectTrusted !== undefined ? { projectTrusted: value.projectTrusted } : {}),
+      ...(value.cwd !== undefined ? { cwd: value.cwd.trim() } : {}),
+    },
+  }
+}
+
+/** Read and validate a `--capabilities <path>` document. Missing is explicit. */
+export function readCapabilitiesFile(filePath) {
+  if (!nonEmptyString(filePath)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_MISSING, 'no capabilities path was given')
+  }
+  const path = resolvePath(String(filePath))
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (error) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_MISSING,
+      `capabilities file ${path} cannot be read: ${error.code || error.message}`,
+      { path },
+    )
+  }
+  let value
+  try {
+    value = JSON.parse(text)
+  } catch (error) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_INVALID,
+      `capabilities file ${path} is not valid JSON: ${error.message}`,
+      { path },
+    )
+  }
+  return normalizeCapabilities(value, { path })
+}
+
+/**
+ * Build the versioned request the resolver reads on stdin. Returns a blocked
+ * result instead of a half-valid request, so a malformed caller cannot reach the
+ * child as an empty availability list.
+ */
+export function buildCatalogRequest({
+  harness,
+  cwd = process.cwd(),
+  available = [],
+  foregroundModel = null,
+  fallbackToForeground = null,
+  launchCapabilities = null,
+  hostPreferences = null,
+  overrides = null,
+  tiers = null,
+  userRoot = null,
+  projectTrusted = null,
+} = {}) {
+  if (!CATALOG_HARNESSES.includes(harness)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID,
+      `harness must be one of ${CATALOG_HARNESSES.join('|')}`,
+      { harness: harness ?? null },
+    )
+  }
+  if (!nonEmptyString(cwd)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'cwd must be a non-empty path')
+  }
+  const normalizedAvailable = normalizeAvailable(available)
+  if (!normalizedAvailable.ok) return normalizedAvailable
+  if (normalizedAvailable.available.length === 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_MISSING,
+      'no current-turn models were supplied; the harness must advertise its available models for this turn',
+    )
+  }
+  if (foregroundModel !== null && foregroundModel !== undefined && !nonEmptyString(foregroundModel)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'foregroundModel must be a model id')
+  }
+  const normalizedOverrides = normalizeOverrides(overrides)
+  if (!normalizedOverrides.ok) return normalizedOverrides
+  if (userRoot !== null && userRoot !== undefined && !nonEmptyString(userRoot)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'userRoot must be a path')
+  }
+  if (projectTrusted !== null && projectTrusted !== undefined && typeof projectTrusted !== 'boolean') {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'projectTrusted must be a boolean')
+  }
+  if (fallbackToForeground !== null && fallbackToForeground !== undefined && typeof fallbackToForeground !== 'boolean') {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'fallbackToForeground must be a boolean')
+  }
+  const normalizedLaunch = normalizeLaunchCapabilities(launchCapabilities)
+  if (!normalizedLaunch.ok) return normalizedLaunch
+  const normalizedHostPreferences = normalizeOverrides(hostPreferences, {
+    allowed: CATALOG_ROLES,
+    label: 'hostPreferences',
+  })
+  if (!normalizedHostPreferences.ok) return normalizedHostPreferences
+  const normalizedTiers = normalizeTierPolicy(tiers)
+  if (!normalizedTiers.ok) return normalizedTiers
+  return {
+    ok: true,
+    request: {
+      version: AGENT_CATALOG_PROTOCOL_VERSION,
+      harness,
+      cwd: String(cwd),
+      ...(userRoot !== null && userRoot !== undefined ? { userRoot: String(userRoot) } : {}),
+      ...(projectTrusted !== null && projectTrusted !== undefined ? { projectTrusted } : {}),
+      available: normalizedAvailable.available,
+      ...(foregroundModel !== null && foregroundModel !== undefined
+        ? { foregroundModel: String(foregroundModel) }
+        : {}),
+      ...(fallbackToForeground !== null && fallbackToForeground !== undefined
+        ? { fallbackToForeground }
+        : {}),
+      ...(normalizedLaunch.launchCapabilities
+        ? { launchCapabilities: normalizedLaunch.launchCapabilities }
+        : {}),
+      ...(Object.keys(normalizedHostPreferences.overrides).length > 0
+        ? { hostPreferences: normalizedHostPreferences.overrides }
+        : {}),
+      ...(Object.keys(normalizedOverrides.overrides).length > 0
+        ? { overrides: normalizedOverrides.overrides }
+        : {}),
+      ...(normalizedTiers.tiers ? { tiers: normalizedTiers.tiers } : {}),
+    },
+  }
+}
+
+/**
+ * Default child runner: `spawnSync` with an argv array, `shell: false`, bounded
+ * output and a deadline. No shell parses the command and nothing is installed.
+ * Injectable so focused tests can drive the protocol without a child process.
+ */
+export function defaultRunner({
+  executable,
+  args = [],
+  input,
+  timeoutMs = DEFAULT_AGENT_CATALOG_TIMEOUT_MS,
+  env = process.env,
+}) {
+  const result = spawnSync(executable, args, {
+    input,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    maxBuffer: MAX_AGENT_CATALOG_OUTPUT_BYTES,
+    env,
+    shell: false,
+    windowsHide: true,
+  })
+  return {
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error ?? null,
+    signal: result.signal ?? null,
+  }
+}
+
+function workerValue(value, label) {
+  if (!isRecord(value)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label} must be an object`)
+  }
+  const unknown = Object.keys(value).filter((field) => !WORKER_FIELDS.has(field))
+  if (unknown.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `${label} has unknown field(s): ${unknown.join(', ')}`,
+    )
+  }
+  const missing = [...WORKER_FIELDS].filter((field) => !Object.hasOwn(value, field))
+  if (missing.length > 0) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `${label} is missing field(s): ${missing.join(', ')}`,
+    )
+  }
+  if (!CATALOG_ROLES.includes(value.role)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `${label}.role must be one of ${CATALOG_ROLES.join('|')}`,
+      { role: value.role ?? null },
+    )
+  }
+  for (const field of ['model', 'nativeModel', 'effort']) {
+    if (value[field] !== null && !nonEmptyString(value[field])) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+        `${label}.${field} must be null or a non-empty string`,
+      )
+    }
+  }
+  if (value.effort !== null && !CATALOG_EFFORTS.includes(value.effort)) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `${label}.effort must be one of ${CATALOG_EFFORTS.join('|')} or null`,
+    )
+  }
+  if (typeof value.instructions !== 'string') {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label}.instructions must be a string`)
+  }
+  if (!isRecord(value.selection)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label}.selection must be an object`)
+  }
+  if (!(value.launch === null || isRecord(value.launch))) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label}.launch must be an object or null`)
+  }
+  if (!nonEmptyString(value.catalogDigest)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label}.catalogDigest must be a string`)
+  }
+  if (!Array.isArray(value.diagnostics)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, `${label}.diagnostics must be an array`)
+  }
+  return { ok: true, worker: value }
+}
+
+function declined(code, reason, response, extra = {}) {
+  return {
+    ok: false,
+    declined: true,
+    harness: response?.harness ?? null,
+    catalogDigest: response?.catalogDigest ?? null,
+    diagnostics: Array.isArray(response?.diagnostics) ? response.diagnostics : [],
+    blocked: { code, reason, ...extra },
+  }
+}
+
+function validateCatalogResponse(response, { harness, command }) {
+  if (!isRecord(response)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, 'the catalog response is not an object', {
+      command: commandLabel(command),
+    })
+  }
+  if (response.version !== AGENT_CATALOG_PROTOCOL_VERSION) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `unsupported catalog protocol version ${JSON.stringify(response.version)}; expected ${AGENT_CATALOG_PROTOCOL_VERSION}`,
+      { command: commandLabel(command) },
+    )
+  }
+  if (typeof response.ok !== 'boolean') {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, 'the catalog response has no boolean `ok`', {
+      command: commandLabel(command),
+    })
+  }
+  if (response.harness !== harness) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+      `the catalog answered for harness ${JSON.stringify(response.harness)}, not ${harness}`,
+      { command: commandLabel(command) },
+    )
+  }
+  if (!nonEmptyString(response.catalogDigest)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, 'the catalog response has no catalogDigest', {
+      command: commandLabel(command),
+    })
+  }
+  if (!Array.isArray(response.diagnostics)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, 'the catalog response has no diagnostics array', {
+      command: commandLabel(command),
+    })
+  }
+  if (response.ok === false) {
+    return declined(
+      AGENT_CATALOG_BLOCK_CODES.DECLINED,
+      'the agent catalog declined to fill every role for this request',
+      response,
+      { command: commandLabel(command) },
+    )
+  }
+  if (!isRecord(response.slots)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID, 'a successful response must carry `slots`', {
+      command: commandLabel(command),
+    })
+  }
+  const slots = {}
+  for (const slot of CATALOG_SLOTS) {
+    const checked = workerValue(response.slots[slot], `slots.${slot}`)
+    if (!checked.ok) return { ...checked, blocked: { ...checked.blocked, command: commandLabel(command) } }
+    if (checked.worker.launch === null) {
+      return blocked(
+        AGENT_CATALOG_BLOCK_CODES.RESPONSE_INVALID,
+        `slots.${slot} reports ok with no launch payload; a successful catalog must say how to launch the role`,
+        { command: commandLabel(command) },
+      )
+    }
+    slots[slot] = checked.worker
+  }
+  return {
+    ok: true,
+    harness,
+    catalogDigest: response.catalogDigest,
+    slots,
+    diagnostics: response.diagnostics,
+    command: commandLabel(command),
+  }
+}
+
+/**
+ * Resolve all four roles through the configured agent-catalog executable.
+ *
+ * Returns `{ ok: true, harness, catalogDigest, slots, diagnostics, command }` or
+ * `{ ok: false, blocked: { code, reason, … }, declined?, diagnostics? }`. A
+ * missing, broken, or declining resolver is always the second shape: there is no
+ * skill-owned fallback path to return to.
+ */
+export function resolveAgentCatalog({
+  request,
+  env = process.env,
+  runner = defaultRunner,
+  timeoutMs = DEFAULT_AGENT_CATALOG_TIMEOUT_MS,
+} = {}) {
+  if (!isRecord(request)) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.REQUEST_INVALID, 'a catalog request object is required')
+  }
+  const commandResult = resolveCatalogCommand(env)
+  if (!commandResult.ok) return commandResult
+  const { command } = commandResult
+
+  let run
+  try {
+    run = runner({
+      executable: command.executable,
+      args: command.args,
+      input: `${JSON.stringify(request)}\n`,
+      timeoutMs,
+      env,
+    })
+  } catch (error) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.COMMAND_UNAVAILABLE,
+      `${commandLabel(command)} could not run: ${snippet(error?.message, 400)}`,
+      { command: commandLabel(command) },
+    )
+  }
+
+  if (run?.error) {
+    const code = run.error.code === 'ENOENT'
+      ? AGENT_CATALOG_BLOCK_CODES.COMMAND_UNAVAILABLE
+      : AGENT_CATALOG_BLOCK_CODES.COMMAND_FAILED
+    const reason = run.error.code === 'ENOENT'
+      ? `${commandLabel(command)} is not installed or not on PATH; set ${AGENT_CATALOG_COMMAND_ENV} to its JSON argv`
+      : `${commandLabel(command)} could not run: ${snippet(run.error.message, 400)}`
+    return blocked(code, reason, { command: commandLabel(command), errorCode: run.error.code ?? null })
+  }
+  if (run.status !== 0) {
+    const stderr = String(run.stderr ?? '')
+    const detail = stderr.length > MAX_AGENT_CATALOG_DIAGNOSTIC_CHARS
+      ? `${stderr.slice(0, MAX_AGENT_CATALOG_DIAGNOSTIC_CHARS)}…`
+      : stderr
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.COMMAND_FAILED,
+      `${commandLabel(command)} exited ${run.status === null ? 'on a signal' : run.status} without a catalog`,
+      {
+        command: commandLabel(command),
+        status: run.status,
+        signal: run.signal ?? null,
+        stderr: detail,
+      },
+    )
+  }
+
+  const stdout = String(run.stdout ?? '').trim()
+  if (!stdout) {
+    return blocked(AGENT_CATALOG_BLOCK_CODES.OUTPUT_INVALID, `${commandLabel(command)} printed no JSON`, {
+      command: commandLabel(command),
+    })
+  }
+  let response
+  try {
+    response = JSON.parse(stdout)
+  } catch (error) {
+    return blocked(
+      AGENT_CATALOG_BLOCK_CODES.OUTPUT_INVALID,
+      `${commandLabel(command)} printed invalid JSON: ${snippet(stdout)}`,
+      { command: commandLabel(command) },
+    )
+  }
+  return validateCatalogResponse(response, { harness: request.harness, command })
+}