@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{settings-validation.js → api/settings-validation.js}

@@ -1,10 +1,11 @@
 'use strict';
 
 const apiValidation = require('./api-validation');
-const features = require('./features');
-const modelDiscovery = require('./model-discovery');
-const runtimes = require('./runtimes');
-const shared = require('./shared');
+const features = require('../core/features');
+const modelDiscovery = require('../agents/model-discovery');
+const runtimes = require('../runtimes');
+const cloudProviders = require('../cloud');
+const shared = require('../core/shared');
 
 const MAX_SETTINGS_ERRORS = 25;
 const SETTINGS_TOP_LEVEL_FIELDS = new Set(['engine', 'claude', 'agents', 'projects', 'features']);
@@ -57,6 +58,9 @@ const ENGINE_NUMERIC_RANGES = Object.freeze({
   worktreeCreateTimeout: { min: 60000 },
   worktreeCreateRetries: { min: 0, max: 3 },
   worktreeMinFreeSpaceBytes: { min: 0, max: 10 * 1024 * 1024 * 1024 * 1024 },
+  // W-ms5tb6ha016fda10 — 0 disables (keep protected quarantine dirs forever);
+  // cap at 365 days so a typo cannot silently mean "never".
+  worktreeProtectedQuarantineRetentionMs: { min: 0, max: 365 * 24 * 60 * 60 * 1000 },
   assertCleanStatusTimeoutMs: { min: 1000, max: 120000 },
   restartHealthTimeoutMs: { min: 15000, max: 300000 },
   orphanHolderScanTimeoutMs: { min: 1000, max: 30000 },
@@ -72,9 +76,17 @@ const ENGINE_NUMERIC_RANGES = Object.freeze({
   versionCheckInterval: { min: 60000 },
   prPollStatusEvery: { min: 1 },
   prPollCommentsEvery: { min: 1 },
+  // W-msav5edk00g81710 — bounded re-probe window for `abandoned` PR records so a
+  // reopened PR can leave the terminal stamp. 0 disables re-probing entirely;
+  // cap at 90 days so a typo cannot turn a bounded window into a permanent one.
+  abandonedPrRepollWindowMs: { min: 0, max: 90 * 24 * 60 * 60 * 1000 },
   agentBusyReassignMs: { min: 0 },
   maxRetriesPerAgent: { min: 1, max: 20 },
   ccTurnTimeoutMs: { min: 10000, max: 3600000 },
+  // Issue #1105 — cold ACP worker handshake budget. Bounds are single-sourced
+  // from engine/shared.js so the validator and resolveAcpHandshakeTimeoutMs()
+  // can never disagree about the legal range.
+  acpHandshakeTimeoutMs: { min: shared.ACP_HANDSHAKE_TIMEOUT_MIN_MS, max: shared.ACP_HANDSHAKE_TIMEOUT_MAX_MS },
   preDispatchEvalConcurrency: { min: 1, max: 20 },
   memoryRetrievalTopK: { min: 1, max: 30 },
   memoryRetrievalMaxBytes: { min: 1024, max: 65536 },
@@ -110,6 +122,7 @@ const ENGINE_SPECIAL_FIELDS = new Set([
   'maxTurnsByType',
   'evalMaxCost',
   'ignoredCommentAuthors',
+  'cloudProvider',
 ]);
 const ENGINE_ALLOWED_FIELDS = new Set([
   ...Object.keys(ENGINE_NUMERIC_RANGES),
@@ -337,6 +350,21 @@ function applyEngineSettings(candidate, bodyEngine, errors) {
     if (!CLEAR_SENTINELS.has(bodyEngine[key]) && value === undefined) continue;
     setOrDelete(engine, key, value);
   }
+  // Cloud dispatch default provider. Validated against the REGISTERED provider
+  // list rather than accepted as free text: an id that resolves to nothing
+  // would produce a work item that dispatches nowhere, discovered only when
+  // the engine refuses it. Fail-closed here instead. (While no providers are
+  // registered, the only accepted value is the clear sentinel — which is the
+  // honest answer to "configure cloud dispatch" on a build that has none.)
+  if (hasOwn(bodyEngine, 'cloudProvider')) {
+    if (CLEAR_SENTINELS.has(bodyEngine.cloudProvider)) {
+      delete engine.cloudProvider;
+    } else {
+      const registered = cloudProviders.listCloudProviders();
+      const value = parseEnum(bodyEngine.cloudProvider, 'engine.cloudProvider', registered, errors);
+      if (value !== undefined) engine.cloudProvider = value;
+    }
+  }
   if (hasOwn(bodyEngine, 'copilotStreamMode')) {
     if (CLEAR_SENTINELS.has(bodyEngine.copilotStreamMode)) {
       delete engine.copilotStreamMode;

package/engine/api-contracts/agent-content.js

@@ -1,9 +1,9 @@
 'use strict';
 
-const agentApiValidation = require('../agent-api-validation');
-const steeringConstraints = require('../steering-constraints');
-const steeringStore = require('../steering-store');
-const { LIMITS, PIN_LEVELS } = require('../content-api-validation');
+const agentApiValidation = require('../api/agent-api-validation');
+const steeringConstraints = require('../agents/steering-constraints');
+const steeringStore = require('../persistence/steering-store');
+const { LIMITS, PIN_LEVELS } = require('../api/content-api-validation');
 
 function rejectsInvalid(...fields) {
   return [{

package/engine/api-contracts/capability-manifest.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * engine/api-contracts/capability-manifest.js — the PRODUCER half of the
+ * cross-repo capability protocol (P-c4a1f7b2).
+ *
+ * Minions publishes a typed capability manifest; Constellation consumes it.
+ * This module owns the BUILDER and nothing else: every piece of vocabulary
+ * (scope list, confirmation enum, parameter types, capability-entry field list,
+ * envelope field list, protocol name/version) is imported from
+ * ./capability-protocol, which is the single owner of all of it.
+ *
+ * Two properties make the manifest safe to hand to a remote caller:
+ *
+ *   1. OPT-IN, FAIL-CLOSED. A route reaches the manifest only when its owning
+ *      contract module declares an explicit `capability` block. A route that
+ *      declares nothing is invisible here — there is no heuristic, no
+ *      derived-by-default entry, and no partial entry.
+ *   2. NO INFERRED AUTHORIZATION. `destructive` and `confirm` are read straight
+ *      from that declaration. They are deliberately NOT derived from the route
+ *      registry's `_routeDestructive()` classification in dashboard.js, which
+ *      is a fail-open regex over the route path AND its free-text description:
+ *      rewording a description would otherwise silently reclassify a
+ *      capability's safety posture for a remote caller.
+ *
+ * Parameters are projected from the audited route contract (the same
+ * `request.{path,query,body,headers}.fields` that GET /api/routes exposes
+ * through `_routeContractParameters`), so a published parameter type cannot
+ * drift from the contract the route actually validates against.
+ */
+
+const {
+  CAPABILITY_PROTOCOL_NAME,
+  CAPABILITY_PROTOCOL_VERSION,
+  CAPABILITY_PARAM_TYPES,
+  CAPABILITY_ENTRY_FIELDS,
+  CAPABILITY_PARAM_FIELDS,
+  CAPABILITY_MANIFEST_FIELDS,
+  validateCapabilityManifest,
+} = require('./capability-protocol');
+
+const { listRouteContracts } = require('./index');
+
+// Route contracts speak a slightly wider type vocabulary than the protocol
+// (`identifier`, `basename` and `path` are all string refinements). This is a
+// TRANSLATION table, not a second copy of the protocol's type set: every target
+// below is verified against CAPABILITY_PARAM_TYPES at module load, and an
+// unmapped contract type throws rather than degrading to a guessed type.
+const PARAM_TYPE_FROM_CONTRACT = Object.freeze({
+  string: 'string',
+  identifier: 'string',
+  basename: 'string',
+  path: 'string',
+  number: 'number',
+  integer: 'integer',
+  boolean: 'boolean',
+  array: 'array',
+  object: 'object',
+});
+
+for (const [contractType, protocolType] of Object.entries(PARAM_TYPE_FROM_CONTRACT)) {
+  if (!CAPABILITY_PARAM_TYPES.includes(protocolType)) {
+    throw new Error(`capability-manifest: contract type "${contractType}" maps to "${protocolType}", which is not in the protocol parameter-type set`);
+  }
+}
+
+/**
+ * Resolve a route-contract field type to a protocol parameter type.
+ *
+ * `array<string>` / `array<object>` normalize to `array`: the protocol has no
+ * way to express an item type, so dropping the parameterization loses nothing a
+ * consumer could have used. A UNION (`string|array<string>`) is a different
+ * matter — there is no honest single type for it, so it throws. That is a real
+ * signal, not an obstacle: a capability published to a remote caller has to
+ * have an unambiguous parameter type, and the route contract is where the
+ * ambiguity should be resolved.
+ */
+function protocolParamType(contractType) {
+  const raw = String(contractType || '').trim();
+  if (!raw) return null;
+  if (raw.includes('|')) return null;
+  const normalized = raw.replace(/<.*>$/, '');
+  return PARAM_TYPE_FROM_CONTRACT[normalized] || null;
+}
+
+// Same locations, in the same order, that dashboard.js#_routeContractParameters
+// walks when it projects contract metadata onto GET /api/routes.
+const PARAM_LOCATIONS = Object.freeze(['path', 'query', 'body', 'headers']);
+
+const PARAM_FIELD_NAMES = Object.freeze(CAPABILITY_PARAM_FIELDS.map(entryField => entryField.name));
+
+function fail(message) {
+  throw new Error(`capability-manifest: ${message}`);
+}
+
+/**
+ * Project one contract request field onto a protocol parameter descriptor.
+ * Only fields the protocol declares are copied — contract-only annotations such
+ * as `allowedValuesSource` are producer bookkeeping and would be rejected by
+ * the protocol's strict unknown-field check.
+ */
+function capabilityParam(contractField, contract, location) {
+  const name = String(contractField?.name || '').trim();
+  if (!name) fail(`${contract.key} declares an unnamed ${location} field`);
+  const type = protocolParamType(contractField.type);
+  if (!type) {
+    fail(`${contract.key} ${location} field "${name}" has contract type "${contractField.type}", which has no unambiguous protocol parameter type`);
+  }
+  const param = { name, type, required: contractField.required === true };
+  if (typeof contractField.description === 'string' && contractField.description.trim()) {
+    param.description = contractField.description;
+  }
+  if (Array.isArray(contractField.allowedValues)) {
+    param.allowedValues = [...contractField.allowedValues];
+  }
+  if (Number.isInteger(contractField.maxLength)) {
+    param.maxLength = contractField.maxLength;
+  }
+  for (const key of Object.keys(param)) {
+    if (!PARAM_FIELD_NAMES.includes(key)) fail(`${contract.key} produced an out-of-contract parameter field "${key}"`);
+  }
+  return param;
+}
+
+/**
+ * Typed parameters for one capability, sourced from the merged route contract.
+ * The protocol's parameter descriptor has no location discriminator, so a name
+ * declared in two locations collapses to its first occurrence — path first,
+ * which is the canonical selector for every route that has one.
+ */
+function capabilityParams(contract) {
+  const params = [];
+  const seen = new Set();
+  for (const location of PARAM_LOCATIONS) {
+    const fields = contract?.request?.[location]?.fields;
+    if (!Array.isArray(fields)) continue;
+    for (const contractField of fields) {
+      const param = capabilityParam(contractField, contract, location);
+      if (seen.has(param.name)) continue;
+      seen.add(param.name);
+      params.push(param);
+    }
+  }
+  return params;
+}
+
+/**
+ * Assemble one capability entry. The emitted key set is generated by walking
+ * CAPABILITY_ENTRY_FIELDS, so it is the protocol's field list by construction
+ * and can never become a hand-maintained copy that drifts from it.
+ */
+function buildCapabilityEntry(contract) {
+  const declared = contract.capability;
+  const derived = {
+    method: contract.method,
+    path: contract.path,
+    params: capabilityParams(contract),
+  };
+  const entry = {};
+  for (const entryField of CAPABILITY_ENTRY_FIELDS) {
+    const value = Object.hasOwn(derived, entryField.name) ? derived[entryField.name] : declared[entryField.name];
+    if (value === undefined) {
+      if (entryField.required) fail(`${contract.key} capability is missing required field "${entryField.name}"`);
+      continue;
+    }
+    entry[entryField.name] = value;
+  }
+  return entry;
+}
+
+function resolveMinionsVersion() {
+  try {
+    const version = require('../../package.json').version;
+    return typeof version === 'string' && version.trim() ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the capability manifest.
+ *
+ * THROWS on any contract violation — an out-of-vocabulary scope, an unknown
+ * confirmation mode, an unmapped parameter type or a duplicate capability id is
+ * a producer bug, never a warning that ships a manifest the consumer cannot
+ * generate against.
+ *
+ * @param {object} [options]
+ * @param {function} [options.listContracts] contract source (tests inject one)
+ * @param {string}   [options.generatedAt]   ISO timestamp override
+ * @param {string}   [options.minionsVersion] producer version override
+ */
+function buildCapabilityManifest(options = {}) {
+  const contracts = typeof options.listContracts === 'function'
+    ? options.listContracts()
+    : listRouteContracts();
+  if (!Array.isArray(contracts)) fail('contract source must return an array');
+
+  const capabilities = contracts
+    .filter(contract => contract && contract.capability)
+    .map(buildCapabilityEntry)
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const minionsVersion = options.minionsVersion === undefined
+    ? resolveMinionsVersion()
+    : options.minionsVersion;
+
+  const values = {
+    protocol: CAPABILITY_PROTOCOL_NAME,
+    protocolVersion: CAPABILITY_PROTOCOL_VERSION,
+    generatedAt: options.generatedAt || new Date().toISOString(),
+    minionsVersion,
+    capabilities,
+  };
+
+  const manifest = {};
+  for (const envelopeField of CAPABILITY_MANIFEST_FIELDS) {
+    const value = values[envelopeField.name];
+    if (value === undefined || value === null) {
+      if (envelopeField.required) fail(`manifest is missing required envelope field "${envelopeField.name}"`);
+      continue;
+    }
+    manifest[envelopeField.name] = value;
+  }
+
+  validateCapabilityManifest(manifest);
+  return manifest;
+}
+
+module.exports = {
+  buildCapabilityManifest,
+  // exported for testing
+  PARAM_TYPE_FROM_CONTRACT,
+  PARAM_LOCATIONS,
+  protocolParamType,
+};

package/engine/api-contracts/capability-protocol.js

@@ -0,0 +1,333 @@
+'use strict';
+
+/**
+ * engine/api-contracts/capability-protocol.js — the canonical, versioned
+ * cross-repo capability protocol contract.
+ *
+ * Minions is the PRODUCER of the capability manifest and Constellation is the
+ * CONSUMER. Without a single owned vocabulary the two repos independently
+ * invent the scope strings, the confirmation enum, the parameter types and the
+ * version rules, and drift silently. This module is that single owned
+ * vocabulary: the scope list, confirmation enum, parameter-type set,
+ * capability-entry/envelope field lists and the version-compatibility rule are
+ * defined HERE and nowhere else in this repo.
+ *
+ * Constraints that shape the design:
+ *
+ *   1. Minions has zero runtime dependencies (package.json declares none; the
+ *      engine is built entirely on Node built-ins). So the contract is a plain
+ *      CommonJS module — no schema library, no build step, no transpile.
+ *   2. Constellation cannot import CommonJS from this repo, so the contract is
+ *      also emitted as a machine-readable artifact:
+ *
+ *          node engine/api-contracts/capability-protocol.js --emit
+ *
+ *      writes docs/contracts/capability-protocol.v1.json, which is checked in
+ *      and guarded by a drift test. Consumers GENERATE code from that artifact
+ *      (pinning `protocolVersion` + `checksum`); they never transcribe it.
+ *   3. The artifact is content-addressed, not time-stamped: regenerating it
+ *      from unchanged sources must reproduce the same bytes, so the drift test
+ *      can compare byte-for-byte.
+ *
+ * The module intentionally requires only Node built-ins so a generator in
+ * another repo can load it standalone without dragging in the engine.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CAPABILITY_PROTOCOL_NAME = 'minions.capability.manifest';
+const CAPABILITY_PROTOCOL_VERSION = 1;
+
+/**
+ * Stated ONCE, and deliberately byte-identical to the rule already published
+ * for the bridge snapshot in docs/constellation-bridge.md. Restating it in
+ * different words is exactly the drift this contract exists to prevent, so a
+ * unit test asserts this string appears verbatim in that document.
+ */
+const CAPABILITY_VERSION_RULE = '`protocolVersion` changes only for a breaking schema change. Additive optional fields do not require a version bump.';
+
+/**
+ * The complete scope vocabulary. A capability declares the scopes it consumes;
+ * a consumer grants or withholds them. Adding a scope is additive (no version
+ * bump); removing or repurposing one is breaking (version bump).
+ */
+const CAPABILITY_SCOPES = Object.freeze([
+  'work:read',
+  'work:write',
+  'plan:read',
+  'plan:write',
+  'pr:read',
+  'notes:write',
+  'watch:write',
+  'engine:control',
+  'cc:converse',
+  'docchat:write',
+  'qa:read',
+]);
+
+/**
+ * Confirmation policy for invoking a capability.
+ *   none     — the consumer may invoke without asking the operator.
+ *   per-call — the consumer must obtain operator confirmation for every call.
+ */
+const CAPABILITY_CONFIRM_MODES = Object.freeze(['none', 'per-call']);
+
+/**
+ * Parameter types. Deliberately a small JSON-native set drawn from the
+ * vocabulary already used by the route contracts in this directory, so a
+ * generated consumer type maps onto it without a translation table. Value
+ * constraints are expressed with `allowedValues` / `maxLength`, not with more
+ * types.
+ */
+const CAPABILITY_PARAM_TYPES = Object.freeze([
+  'string',
+  'number',
+  'integer',
+  'boolean',
+  'array',
+  'object',
+]);
+
+/**
+ * Symbolic accessors DERIVED from the vocabularies above — never a second copy.
+ * A producer that has to name one scope or confirmation mode writes
+ * `CAPABILITY_SCOPE.WORK_READ` rather than transcribing `'work:read'`, so the
+ * "defined exactly once" property survives contact with the route declarations
+ * that consume it. The repo-wide scan in test/unit/capability-protocol.test.js
+ * treats a transcribed scope literal anywhere else as drift, and these
+ * accessors are what make declaring a capability possible without tripping it.
+ */
+function symbolicIndex(values) {
+  return Object.freeze(Object.fromEntries(
+    values.map(value => [value.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase(), value]),
+  ));
+}
+
+const CAPABILITY_SCOPE = symbolicIndex(CAPABILITY_SCOPES);
+const CAPABILITY_CONFIRM = symbolicIndex(CAPABILITY_CONFIRM_MODES);
+
+function field(name, type, required, options) {
+  return Object.freeze({ name, type, required, ...(options || {}) });
+}
+
+/** Field list for one capability entry. */
+const CAPABILITY_ENTRY_FIELDS = Object.freeze([
+  field('id', 'string', true, { description: 'Stable capability identifier, unique within a manifest.' }),
+  field('title', 'string', true, { description: 'Short human-readable label.' }),
+  field('description', 'string', true, { description: 'One-line description of the effect.' }),
+  field('method', 'string', true, { description: 'HTTP method of the backing Minions route.' }),
+  field('path', 'string', true, { description: 'Canonical route path template of the backing Minions route.' }),
+  field('scopes', 'array', true, { itemsOf: 'scopes', description: 'Scopes consumed, drawn from the scope vocabulary.' }),
+  field('destructive', 'boolean', true, { description: 'Whether invoking the capability destroys or irreversibly mutates state. A consumer authorization input, so it is always declared explicitly and never inferred from the route name, method, or description.' }),
+  field('confirm', 'string', true, { allowedValuesOf: 'confirmModes', description: 'Confirmation policy for invocation.' }),
+  field('params', 'array', true, { itemsOf: 'capabilityParamFields', description: 'Parameter descriptors; may be empty.' }),
+]);
+
+/** Field list for one parameter descriptor inside a capability entry. */
+const CAPABILITY_PARAM_FIELDS = Object.freeze([
+  field('name', 'string', true, { description: 'Parameter name as sent to the route.' }),
+  field('type', 'string', true, { allowedValuesOf: 'paramTypes', description: 'Parameter type from the parameter-type set.' }),
+  field('required', 'boolean', true, { description: 'Whether the caller must supply the parameter.' }),
+  field('description', 'string', false, { description: 'Optional one-line parameter description.' }),
+  field('allowedValues', 'array', false, { description: 'Optional closed value set.' }),
+  field('maxLength', 'integer', false, { description: 'Optional maximum length for string parameters.' }),
+]);
+
+/** Field list for the manifest envelope that wraps the capability entries. */
+const CAPABILITY_MANIFEST_FIELDS = Object.freeze([
+  field('protocol', 'string', true, { constant: CAPABILITY_PROTOCOL_NAME, description: 'Protocol identifier.' }),
+  field('protocolVersion', 'integer', true, { constant: CAPABILITY_PROTOCOL_VERSION, description: 'Protocol version; see versionRule.' }),
+  field('generatedAt', 'string', true, { description: 'ISO-8601 UTC timestamp of manifest generation.' }),
+  field('minionsVersion', 'string', false, { description: 'Optional Minions package version of the producer.' }),
+  field('capabilities', 'array', true, { itemsOf: 'capabilityEntryFields', description: 'Capability entries.' }),
+]);
+
+const SCOPE_SET = new Set(CAPABILITY_SCOPES);
+const CONFIRM_SET = new Set(CAPABILITY_CONFIRM_MODES);
+const PARAM_TYPE_SET = new Set(CAPABILITY_PARAM_TYPES);
+
+const ARTIFACT_RELATIVE_PATH = `docs/contracts/capability-protocol.v${CAPABILITY_PROTOCOL_VERSION}.json`;
+const GENERATOR_RELATIVE_PATH = 'engine/api-contracts/capability-protocol.js';
+
+/**
+ * The version-compatibility rule, executable. A manifest is compatible only
+ * when its `protocolVersion` equals ours: per CAPABILITY_VERSION_RULE the
+ * number moves solely on a breaking schema change, so an exact match is the
+ * whole rule — and additive optional fields keep the number (and therefore
+ * compatibility) unchanged.
+ */
+function isCompatibleProtocolVersion(version) {
+  return version === CAPABILITY_PROTOCOL_VERSION;
+}
+
+function fail(message) {
+  throw new Error(`capability-protocol: ${message}`);
+}
+
+function typeMatches(type, value) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array': return Array.isArray(value);
+    case 'object': return !!value && typeof value === 'object' && !Array.isArray(value);
+    default: return false;
+  }
+}
+
+function assertFields(target, fields, label, itemLabel) {
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    fail(`${label} must be an object`);
+  }
+  const known = new Set(fields.map(entry => entry.name));
+  for (const key of Object.keys(target)) {
+    if (!known.has(key)) fail(`unknown ${itemLabel} field: ${key}`);
+  }
+  for (const entry of fields) {
+    const value = target[entry.name];
+    if (value === undefined) {
+      if (entry.required) fail(`missing required ${itemLabel} field: ${entry.name}`);
+      continue;
+    }
+    if (!typeMatches(entry.type, value)) {
+      fail(`${itemLabel} field ${entry.name} must be of type ${entry.type}`);
+    }
+  }
+}
+
+function validateCapabilityParam(param, capabilityId) {
+  assertFields(param, CAPABILITY_PARAM_FIELDS, `capability ${capabilityId} parameter`, 'parameter');
+  if (!PARAM_TYPE_SET.has(param.type)) {
+    fail(`unknown parameter type "${param.type}" on capability ${capabilityId}; allowed: ${CAPABILITY_PARAM_TYPES.join(', ')}`);
+  }
+  if (!param.name.trim()) fail(`capability ${capabilityId} has a parameter with an empty name`);
+}
+
+function validateCapabilityEntry(entry, index) {
+  assertFields(entry, CAPABILITY_ENTRY_FIELDS, `capability at index ${index}`, 'capability');
+  const id = entry.id;
+  if (!id.trim()) fail(`capability at index ${index} has an empty id`);
+  if (!entry.scopes.length) fail(`capability ${id} must declare at least one scope`);
+  for (const scope of entry.scopes) {
+    if (!SCOPE_SET.has(scope)) {
+      fail(`unknown capability scope "${scope}" on capability ${id}; allowed: ${CAPABILITY_SCOPES.join(', ')}`);
+    }
+  }
+  if (!CONFIRM_SET.has(entry.confirm)) {
+    fail(`unknown confirm mode "${entry.confirm}" on capability ${id}; allowed: ${CAPABILITY_CONFIRM_MODES.join(', ')}`);
+  }
+  for (const param of entry.params) validateCapabilityParam(param, id);
+  const paramNames = entry.params.map(param => param.name);
+  if (new Set(paramNames).size !== paramNames.length) {
+    fail(`capability ${id} declares duplicate parameter names`);
+  }
+  return id;
+}
+
+/**
+ * Validate a capability manifest against this contract. THROWS on any
+ * violation — an out-of-contract scope, confirmation mode or parameter type is
+ * a build-time failure for the producer, never a warning that ships a manifest
+ * the consumer cannot generate against. Returns `true` on success so callers
+ * can assert on it.
+ */
+function validateCapabilityManifest(manifest) {
+  assertFields(manifest, CAPABILITY_MANIFEST_FIELDS, 'manifest', 'manifest');
+  if (manifest.protocol !== CAPABILITY_PROTOCOL_NAME) {
+    fail(`manifest protocol must be "${CAPABILITY_PROTOCOL_NAME}", got "${manifest.protocol}"`);
+  }
+  if (!isCompatibleProtocolVersion(manifest.protocolVersion)) {
+    fail(`incompatible protocolVersion ${manifest.protocolVersion}; this contract emits ${CAPABILITY_PROTOCOL_VERSION}`);
+  }
+  const ids = [];
+  manifest.capabilities.forEach((entry, index) => { ids.push(validateCapabilityEntry(entry, index)); });
+  if (new Set(ids).size !== ids.length) fail('manifest declares duplicate capability ids');
+  return true;
+}
+
+// Recursively sort object keys so the checksum is independent of key order and
+// reproducible from any language that can sort strings.
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Content checksum over every field except `checksum` itself, so a consumer can
+ * pin the artifact it generated from and detect a swapped or edited copy.
+ */
+function computeArtifactChecksum(artifact) {
+  const { checksum, ...rest } = artifact || {};
+  void checksum;
+  const digest = crypto.createHash('sha256').update(JSON.stringify(canonicalize(rest))).digest('hex');
+  return `sha256:${digest}`;
+}
+
+/** Build the machine-readable artifact from this module. Deterministic. */
+function buildProtocolArtifact() {
+  const body = {
+    protocol: CAPABILITY_PROTOCOL_NAME,
+    protocolVersion: CAPABILITY_PROTOCOL_VERSION,
+    generator: GENERATOR_RELATIVE_PATH,
+    versionRule: CAPABILITY_VERSION_RULE,
+    scopes: [...CAPABILITY_SCOPES],
+    confirmModes: [...CAPABILITY_CONFIRM_MODES],
+    paramTypes: [...CAPABILITY_PARAM_TYPES],
+    manifestEnvelopeFields: CAPABILITY_MANIFEST_FIELDS.map(entry => ({ ...entry })),
+    capabilityEntryFields: CAPABILITY_ENTRY_FIELDS.map(entry => ({ ...entry })),
+    capabilityParamFields: CAPABILITY_PARAM_FIELDS.map(entry => ({ ...entry })),
+  };
+  return { ...body, checksum: computeArtifactChecksum(body) };
+}
+
+/** Exact bytes of the checked-in artifact (LF, trailing newline). */
+function serializeProtocolArtifact() {
+  return `${JSON.stringify(buildProtocolArtifact(), null, 2)}\n`;
+}
+
+/** Write the artifact next to this module's repo root. Returns the path written. */
+function emitProtocolArtifact(repoRoot) {
+  const root = repoRoot || path.resolve(__dirname, '..', '..');
+  const target = path.join(root, ...ARTIFACT_RELATIVE_PATH.split('/'));
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, serializeProtocolArtifact());
+  return target;
+}
+
+if (require.main === module) {
+  if (process.argv.includes('--emit')) {
+    console.log(emitProtocolArtifact());
+  } else {
+    process.stdout.write(serializeProtocolArtifact());
+  }
+}
+
+module.exports = Object.freeze({
+  CAPABILITY_PROTOCOL_NAME,
+  CAPABILITY_PROTOCOL_VERSION,
+  CAPABILITY_VERSION_RULE,
+  CAPABILITY_SCOPES,
+  CAPABILITY_CONFIRM_MODES,
+  CAPABILITY_PARAM_TYPES,
+  CAPABILITY_SCOPE,
+  CAPABILITY_CONFIRM,
+  CAPABILITY_ENTRY_FIELDS,
+  CAPABILITY_PARAM_FIELDS,
+  CAPABILITY_MANIFEST_FIELDS,
+  ARTIFACT_RELATIVE_PATH,
+  GENERATOR_RELATIVE_PATH,
+  isCompatibleProtocolVersion,
+  validateCapabilityManifest,
+  computeArtifactChecksum,
+  buildProtocolArtifact,
+  serializeProtocolArtifact,
+  emitProtocolArtifact,
+});

package/engine/api-contracts/cc-ops.js

@@ -5,7 +5,7 @@ const {
   CC_IMAGE_MIME_TYPES,
   TRANSCRIPT_ROLES,
   TRIAGE_EFFORTS,
-} = require('../cc-api-validation');
+} = require('../api/cc-api-validation');
 
 const transcriptField = () => ({
   name: 'transcript',

package/engine/api-contracts/config-runtime.js

@@ -10,6 +10,7 @@ module.exports = {
     'POST /api/projects/add',
     'POST /api/projects/remove',
     'GET /api/runtimes',
+    'GET /api/cloud-providers',
     'POST /api/runtimes/<runtime>/models/refresh',
     'GET /api/runtimes/<runtime>/models',
     'GET /api/settings',
@@ -136,6 +137,10 @@ module.exports = {
       audit: 'audited',
       noInputReason: 'Lists the canonical runtime registry and accepts no caller input.',
     },
+    'GET /api/cloud-providers': {
+      audit: 'audited',
+      noInputReason: 'Lists the canonical cloud dispatch provider registry and accepts no caller input.',
+    },
     'POST /api/runtimes/<runtime>/models/refresh': {
       audit: 'audited',
       path: {