@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/api-contracts/core.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const { CC_API_LIMITS, PRESENCE_VISIBILITIES } = require('../cc-api-validation');
+const { CC_API_LIMITS, PRESENCE_VISIBILITIES } = require('../api/cc-api-validation');
+const { CAPABILITY_SCOPE, CAPABILITY_CONFIRM } = require('./capability-protocol');
 
 module.exports = {
   owner: 'core',
@@ -10,6 +11,8 @@ module.exports = {
     'GET /api/status',
     'GET /api/engine-log',
     'GET /api/constellation/v1/snapshot',
+    'GET /api/capabilities/protocol',
+    'GET /api/capabilities',
     'GET /state/<path>',
     'GET /api/metrics',
     'GET /api/tools',
@@ -49,6 +52,22 @@ module.exports = {
     'GET /api/status': {
       audit: 'audited',
       noInputReason: 'Returns the current dashboard snapshot; accepts no caller input.',
+      // Phase-0 allowlist. Since issue #2949 this snapshot is only the small
+      // live envelope — engine health/tick, the ADO+GitHub throttle state,
+      // project git status, autoMode, and the version banner. The heavy work,
+      // plan, and PR slices moved to their own endpoints, each of which is a
+      // separately-declared capability. So the summary projection grants ONE
+      // scope, not the union of every read scope: granting the plan and PR
+      // read scopes here would be over-declaration for a payload that carries
+      // neither.
+      capability: {
+        id: 'status.summary',
+        title: 'Read the engine status summary',
+        description: 'Read the live engine health, throttle, and project summary snapshot.',
+        scopes: [CAPABILITY_SCOPE.WORK_READ],
+        destructive: false,
+        confirm: CAPABILITY_CONFIRM.NONE,
+      },
     },
     'GET /api/engine-log': {
       audit: 'audited',
@@ -62,6 +81,14 @@ module.exports = {
       audit: 'audited',
       noInputReason: 'Returns the versioned bridge snapshot; accepts no caller input.',
     },
+    'GET /api/capabilities/protocol': {
+      audit: 'audited',
+      noInputReason: 'Returns the static capability-protocol artifact for live negotiation; accepts no caller input.',
+    },
+    'GET /api/capabilities': {
+      audit: 'audited',
+      noInputReason: 'Returns the derived capability manifest; accepts no caller input.',
+    },
     'GET /state/<path>': {
       audit: 'audited',
       path: {

package/engine/api-contracts/index.js

@@ -19,6 +19,100 @@ const OWNERS = Object.freeze(OWNER_NAMES);
 const LOCATION_POLICIES = new Set(['none', 'optional', 'required', 'pending-audit']);
 const AUDIT_STATUSES = new Set(['audited', 'pending-audit']);
 
+// The capability vocabulary is owned by the cross-repo protocol contract, never
+// restated here. This module only decides WHICH routes opt in and enforces that
+// each declaration is complete against that contract.
+const {
+  CAPABILITY_SCOPES,
+  CAPABILITY_CONFIRM_MODES,
+  CAPABILITY_CONFIRM,
+  CAPABILITY_ENTRY_FIELDS,
+} = require('./capability-protocol');
+
+const CAPABILITY_SCOPE_SET = new Set(CAPABILITY_SCOPES);
+const CAPABILITY_CONFIRM_SET = new Set(CAPABILITY_CONFIRM_MODES);
+// Derived from the route key or the audited request contract — a hand-typed
+// copy could drift from the route it claims to describe, so these entry fields
+// may not be declared in an override.
+const CAPABILITY_DERIVED_FIELDS = new Set(['method', 'path', 'params']);
+const CAPABILITY_DECLARED_FIELDS = CAPABILITY_ENTRY_FIELDS
+  .filter(entryField => !CAPABILITY_DERIVED_FIELDS.has(entryField.name));
+// Producer-only key: not published in the manifest, it exists so a
+// non-destructive claim on a state-changing route has to be argued rather than
+// assumed (see normalizeCapability).
+const CAPABILITY_PRODUCER_FIELDS = new Set(['nonDestructiveRationale']);
+
+/**
+ * Validate the opt-in `capability` block on a route override.
+ *
+ * Fail-closed in both directions: a route without a block is simply not a
+ * capability (it never reaches the manifest), and a route WITH a block must
+ * declare every required protocol field or the catalog build throws. In
+ * particular `destructive` and `confirm` are always explicit — the remote
+ * authorization posture of a capability must never be inferred from a route's
+ * method, path, or free-text description, because rewording a description
+ * would then silently reclassify it for a remote caller.
+ */
+function normalizeCapability(value, key, stateChanging) {
+  if (value === undefined) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${key} capability must be an object`);
+  }
+  for (const declaredField of Object.keys(value)) {
+    if (CAPABILITY_DERIVED_FIELDS.has(declaredField)) {
+      throw new Error(`${key} capability must not declare "${declaredField}" — it is derived from the route contract`);
+    }
+    if (!CAPABILITY_DECLARED_FIELDS.some(entryField => entryField.name === declaredField)
+        && !CAPABILITY_PRODUCER_FIELDS.has(declaredField)) {
+      throw new Error(`${key} capability declares unknown field "${declaredField}"`);
+    }
+  }
+  for (const entryField of CAPABILITY_DECLARED_FIELDS) {
+    if (entryField.required && value[entryField.name] === undefined) {
+      throw new Error(`${key} capability must explicitly declare "${entryField.name}"`);
+    }
+  }
+  for (const textField of ['id', 'title', 'description']) {
+    if (typeof value[textField] !== 'string' || !value[textField].trim()) {
+      throw new Error(`${key} capability ${textField} must be a non-empty string`);
+    }
+  }
+  if (!Array.isArray(value.scopes) || value.scopes.length === 0) {
+    throw new Error(`${key} capability must declare at least one scope`);
+  }
+  for (const scope of value.scopes) {
+    if (!CAPABILITY_SCOPE_SET.has(scope)) {
+      throw new Error(`${key} capability declares unknown scope "${scope}"; the scope vocabulary is owned by engine/api-contracts/capability-protocol.js`);
+    }
+  }
+  if (typeof value.destructive !== 'boolean') {
+    throw new Error(`${key} capability destructive must be an explicit boolean`);
+  }
+  if (!CAPABILITY_CONFIRM_SET.has(value.confirm)) {
+    throw new Error(`${key} capability declares unknown confirm mode "${value.confirm}"; the confirmation enum is owned by engine/api-contracts/capability-protocol.js`);
+  }
+  if (value.destructive && value.confirm !== CAPABILITY_CONFIRM.PER_CALL) {
+    throw new Error(`${key} capability is destructive and must require per-call confirmation`);
+  }
+  // Corroborating assertion only: `stateChanging` is method-derived, so it can
+  // contradict a `destructive: false` claim but never supply one.
+  const rationale = value.nonDestructiveRationale;
+  const needsRationale = stateChanging && value.destructive === false;
+  if (needsRationale && (typeof rationale !== 'string' || !rationale.trim())) {
+    throw new Error(`${key} capability claims destructive: false on a state-changing route and must justify it with nonDestructiveRationale`);
+  }
+  if (!needsRationale && rationale !== undefined) {
+    throw new Error(`${key} capability declares nonDestructiveRationale where it does not apply`);
+  }
+  const normalized = {};
+  for (const entryField of CAPABILITY_DECLARED_FIELDS) {
+    const declared = value[entryField.name];
+    if (declared === undefined) continue;
+    normalized[entryField.name] = typeof declared === 'string' ? declared.trim() : cloneSerializable(declared);
+  }
+  return normalized;
+}
+
 function canonicalPathTemplate(value) {
   const pathTemplate = String(value || '').trim();
   if (!pathTemplate.startsWith('/')) {
@@ -212,6 +306,8 @@ function buildRouteContract(owner, key, bodyless, override = {}) {
     request,
     negativeTests,
   };
+  const capability = normalizeCapability(override.capability, parsed.key, stateChanging);
+  if (capability) contract.capability = capability;
   if (noInput) {
     contract.noInputReason = override.noInputReason
       || (stateChanging
@@ -301,6 +397,10 @@ function routeContractMetadata(route) {
     ...(contract.noInputReason ? { noInputReason: contract.noInputReason } : {}),
     request: contract.request,
     negativeTests: contract.negativeTests,
+    // Whitelisted explicitly: this clone is the only metadata a consumer sees,
+    // so an un-listed key is silently dropped and the capability manifest would
+    // come back empty.
+    ...(contract.capability ? { capability: contract.capability } : {}),
   });
 }
 

package/engine/api-contracts/orchestration.js

@@ -1,9 +1,9 @@
 'use strict';
 
-const keepProcesses = require('../keep-process-sweep');
-const managedSpawn = require('../managed-spawn');
+const keepProcesses = require('../processes/keep-process-sweep');
+const managedSpawn = require('../processes/managed-spawn');
 const managedSpecNameMax = managedSpawn.validateManagedSpecName('x').maxLength;
-const agentApiValidation = require('../agent-api-validation');
+const agentApiValidation = require('../api/agent-api-validation');
 const paging = require('./paging');
 
 // The optional progressive-load paging window is the ONLY caller-supplied input
@@ -48,6 +48,7 @@ module.exports = {
     'GET /api/pipelines',
     'GET /api/keep-processes',
     'GET /api/worktree-quarantine-refs',
+    'GET /api/worktree-inventory',
     'POST /api/keep-processes/kill',
     'GET /api/managed-processes',
     'GET /api/managed-processes/by-name/<name>',
@@ -159,6 +160,16 @@ module.exports = {
         },
       ],
     },
+    'GET /api/worktree-inventory': {
+      audit: 'audited',
+      noInputReason: 'Read-only classification of configured project worktree roots and git registrations; accepts no caller input.',
+      constraints: [
+        {
+          kind: 'configured-project-membership',
+          source: 'config.projects[].localPath',
+        },
+      ],
+    },
     'GET /api/managed-processes': {
       audit: 'audited',
       query: {
@@ -347,6 +358,7 @@ module.exports = {
           { name: 'participants', type: 'array', required: false, allowedValuesSource: 'config.agents keys' },
           { name: 'priority', type: 'string', required: false, default: 'medium', allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
           { name: 'enabled', type: 'boolean', required: false, default: true },
+          { name: 'executionSurface', type: 'string', required: false, default: 'repo', allowedValuesSource: 'shared.EXECUTION_SURFACE_VALUES' },
         ],
       },
       constraints: [
@@ -373,6 +385,7 @@ module.exports = {
           { name: 'participants', type: 'array', required: false, allowedValuesSource: 'config.agents keys' },
           { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
           { name: 'enabled', type: 'boolean', required: false },
+          { name: 'executionSurface', type: 'string', required: false, allowedValuesSource: 'shared.EXECUTION_SURFACE_VALUES' },
         ],
       },
       constraints: [
@@ -562,7 +575,7 @@ module.exports = {
           { name: 'notify', type: 'string', required: false, default: 'inbox', allowedValues: ['inbox', 'none'] },
           { name: 'stopAfter', type: 'integer', required: false, default: 0, min: 0, max: Number.MAX_SAFE_INTEGER },
           { name: 'onNotMet', type: 'string|null', required: false, allowedValues: ['notify'] },
-          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch-actions registry' },
+          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch action registry' },
           { name: 'requires', type: 'array|null', required: false, allowedValuesSource: 'watches target-type registry requirement conditions' },
         ],
       },
@@ -591,7 +604,7 @@ module.exports = {
           { name: 'notify', type: 'string', required: false, allowedValues: ['inbox', 'none'] },
           { name: 'stopAfter', type: 'integer', required: false, min: 0, max: Number.MAX_SAFE_INTEGER },
           { name: 'onNotMet', type: 'string|null', required: false, allowedValues: ['notify'] },
-          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch-actions registry' },
+          { name: 'action', type: 'object|array|null', required: false, allowedValuesSource: 'watch action registry' },
           { name: 'requires', type: 'array|null', required: false, allowedValuesSource: 'watches target-type registry requirement conditions' },
         ],
       },

package/engine/api-contracts/pull-requests.js

@@ -1,9 +1,10 @@
 'use strict';
 
-const { PR_ACTIONS } = require('../pr-action');
-const { EXECUTION_TARGET_IDS } = require('../pr-fix-target');
-const { PR_FIX_CAUSE } = require('../shared');
+const { PR_ACTIONS } = require('../providers/pr-action');
+const { EXECUTION_TARGET_IDS } = require('../providers/pr-fix-target');
+const { PR_FIX_CAUSE } = require('../core/shared');
 const paging = require('./paging');
+const { CAPABILITY_SCOPE, CAPABILITY_CONFIRM } = require('./capability-protocol');
 
 const PR_REFERENCE_FORMATS = Object.freeze([
   'GitHub PR URL',
@@ -44,6 +45,7 @@ module.exports = {
     'POST /api/pr-action/prepare-create-pr-worktree',
     'POST /api/pr-action/cleanup-create-pr-worktree',
     'POST /api/pull-requests/observe',
+    'POST /api/pull-requests/automation',
     'POST /api/pull-requests/delete',
     'POST /api/pull-requests/clear-paused-cause',
     'POST /api/pull-requests/clear-build-fix-ineffective',
@@ -62,6 +64,14 @@ module.exports = {
         ...paging.listPagingClampConstraints(),
         { kind: 'ignores-unknown-query-params', location: 'query' },
       ],
+      capability: {
+        id: 'pr.list',
+        title: 'List tracked pull requests',
+        description: 'Read the tracked pull-request records with build, review, and merge state.',
+        scopes: [CAPABILITY_SCOPE.PR_READ],
+        destructive: false,
+        confirm: CAPABILITY_CONFIRM.NONE,
+      },
     },
     'GET /api/prs/<id>': {
       audit: 'audited',
@@ -129,7 +139,7 @@ module.exports = {
         type: 'string',
         required: true,
         allowedValues: PR_ACTIONS,
-        allowedValuesSource: 'engine/pr-action.PR_ACTIONS',
+        allowedValuesSource: 'engine/providers/pr-action.PR_ACTIONS',
       },
       { name: 'execute', type: 'boolean', required: false, default: false },
       { name: 'draftOnly', type: 'boolean', required: false, default: false },
@@ -154,7 +164,7 @@ module.exports = {
         type: 'string',
         required: false,
         allowedValues: EXECUTION_TARGET_IDS,
-        allowedValuesSource: 'engine/pr-fix-target.EXECUTION_TARGET_IDS',
+        allowedValuesSource: 'engine/providers/pr-fix-target.EXECUTION_TARGET_IDS',
       },
       { name: 'remember', type: 'boolean', required: false, default: false },
       { name: 'reprompt', type: 'boolean', required: false, default: false },
@@ -249,6 +259,27 @@ module.exports = {
         precedence: ['contextOnly', 'observe'],
       }],
     }),
+    'POST /api/pull-requests/automation': auditedBody([
+      { name: 'host', type: 'string', required: true, allowedValues: ['github', 'ado'] },
+      {
+        name: 'slug',
+        type: 'string',
+        required: true,
+        shapeByHost: {
+          github: 'owner/repo',
+          ado: 'org/project/repo',
+        },
+      },
+      {
+        name: 'number',
+        type: 'integer',
+        required: true,
+        min: 1,
+        max: Number.MAX_SAFE_INTEGER,
+      },
+      { name: 'automation', type: 'string', required: true, allowedValues: ['fix', 'review'] },
+      { name: 'enabled', type: 'boolean', required: true },
+    ], { seam: 'tracked PR automation' }),
     'POST /api/pull-requests/delete': auditedBody([
       {
         name: 'id',
@@ -280,7 +311,7 @@ module.exports = {
         type: 'string',
         required: true,
         allowedValues: Object.values(PR_FIX_CAUSE),
-        allowedValuesSource: 'engine/shared.PR_FIX_CAUSE',
+        allowedValuesSource: 'engine/core/shared.PR_FIX_CAUSE',
       },
     ], { seam: 'tracked PR pause store' }),
     'POST /api/pull-requests/clear-build-fix-ineffective': auditedBody([

package/engine/api-contracts/qa-process.js

@@ -1,11 +1,11 @@
 'use strict';
 
-const qaFromPrd = require('../qa-from-prd');
-const keepProcesses = require('../keep-process-sweep');
-const qaRunbooks = require('../qa-runbooks');
-const qaRuns = require('../qa-runs');
-const qaSessions = require('../qa-sessions');
-const shared = require('../shared');
+const qaFromPrd = require('../qa/from-prd');
+const keepProcesses = require('../processes/keep-process-sweep');
+const qaRunbooks = require('../qa/runbooks');
+const qaRuns = require('../qa/runs');
+const qaSessions = require('../qa/sessions');
+const shared = require('../core/shared');
 
 const sessionIdPath = {
   policy: 'required',
@@ -65,6 +65,7 @@ module.exports = {
     'POST /api/qa/sessions/<id>/dismiss',
     'GET /api/qa/sessions/<id>/test',
     'GET /api/qa/sessions/<id>',
+    'DELETE /api/qa/sessions/<id>',
     'GET /api/qa/runners',
     'POST /api/qa/runners/reload',
     'POST /api/meetings',
@@ -80,6 +81,7 @@ module.exports = {
   bodyless: [
     'DELETE /api/qa/runs/<id>',
     'DELETE /api/qa/runbooks/<id>',
+    'DELETE /api/qa/sessions/<id>',
     'POST /api/qa/sessions/<id>/approve',
     'POST /api/qa/runners/reload',
   ],
@@ -531,6 +533,27 @@ module.exports = {
         { strategy: 'missing-session-or-test-file', expectedStatus: 404 },
       ],
     },
+    'DELETE /api/qa/sessions/<id>': {
+      audit: 'audited',
+      path: sessionIdPath,
+      constraints: [
+        { kind: 'body-forbidden' },
+        { kind: 'terminal-state-required', source: 'qa-sessions.TERMINAL_STATES' },
+        {
+          kind: 'owned-linked-resource-cleanup',
+          source: 'qa-sessions.deleteSession',
+          resources: ['qa-tests/<id>/', 'qa-runs record with runbookId qa-session-<id>'],
+          excludes: ['managed-spawn processes'],
+        },
+      ],
+      negativeTests: [
+        { strategy: 'non-empty-body-before-delete', expectedStatus: 400 },
+        { strategy: 'unsafe-id', expectedStatus: 400 },
+        { strategy: 'well-formed-missing-id', expectedStatus: 404 },
+        { strategy: 'non-terminal-session', expectedStatus: 409 },
+        { strategy: 'snapshot-session-run-and-test-directory-on-rejection', expectedStatus: '4xx' },
+      ],
+    },
     'POST /api/qa/sessions/<id>/approve': {
       audit: 'audited',
       path: sessionIdPath,

package/engine/api-contracts/work-plan-prd.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const paging = require('./paging');
+const { CAPABILITY_SCOPE, CAPABILITY_CONFIRM } = require('./capability-protocol');
 
 const AUDITED_NEGATIVE_TESTS = Object.freeze([{
   strategy: 'isolated-http-invalid-input-state-snapshot',
@@ -77,6 +78,14 @@ module.exports = {
       negativeTests: [
         { strategy: 'reject-unknown-query-param-blaming-the-rejected-name', expectedStatus: 400 },
       ],
+      capability: {
+        id: 'plan.list',
+        title: 'List plans',
+        description: 'Read the plan inventory with each plan\'s lifecycle status.',
+        scopes: [CAPABILITY_SCOPE.PLAN_READ],
+        destructive: false,
+        confirm: CAPABILITY_CONFIRM.NONE,
+      },
     },
     'POST /api/work-items': {
       audit: 'audited',
@@ -279,6 +288,14 @@ module.exports = {
         ...paging.listPagingClampConstraints(),
         { kind: 'ignores-unknown-query-params', location: 'query' },
       ],
+      capability: {
+        id: 'work.list',
+        title: 'List work items',
+        description: 'Read the current work-item queue with its status, agent, and project.',
+        scopes: [CAPABILITY_SCOPE.WORK_READ],
+        destructive: false,
+        confirm: CAPABILITY_CONFIRM.NONE,
+      },
     },
     'GET /api/work-items/archive': {
       // Archived-item listing: reads no query/body. Affirmed input-less.
@@ -412,7 +429,10 @@ module.exports = {
           { name: 'requestedBy', type: 'string', required: false },
         ],
       },
-      constraints: ['feedback must contain non-whitespace text and PRD status must allow revision'],
+      constraints: [
+        'feedback must contain non-whitespace text and PRD status must allow revision',
+        'a live revision operation is rejected with 409 revision-in-progress and the existing work item id',
+      ],
     },
     'POST /api/plans/discuss': {
       audit: 'audited',

package/engine/cloud/contract.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * engine/cloud/contract.js — versioned contract for CLOUD DISPATCH PROVIDERS.
+ *
+ * A cloud provider hands a work item to a REMOTE coding agent (Agency, the
+ * GitHub Copilot coding agent, an ADO work-item assignment picked up by a bot)
+ * and lets Minions track that remote session until a pull request exists.
+ *
+ * ── Why this is NOT a runtime adapter ────────────────────────────────────
+ * `engine/runtimes/contract.js` describes a LOCAL CLI PROCESS: argv building,
+ * prompt-on-stdin, PID tracking, stdout stream parsing, session resume, cost
+ * accounting per turn. A cloud agent has none of those. You submit a task, get
+ * an opaque session handle, poll it, and eventually a PR appears in the repo.
+ * Modelling that as a runtime would force every adapter method to lie
+ * (`buildArgs` for a process that never spawns, `parseStreamChunk` for a stream
+ * that does not exist) and would drag cloud dispatch through the local
+ * spawn/timeout/worktree machinery it must specifically avoid.
+ *
+ * So cloud is its own small contract, reached through its own registry, and
+ * selected by the `cloud` EXECUTION SURFACE rather than by a runtime name.
+ * Orchestration must never import a concrete provider or branch on a provider
+ * id — resolve through `engine/cloud/index.js` and use `capabilities`.
+ *
+ * ── Contract (apiVersion 1) ──────────────────────────────────────────────
+ *   name         : string — registry key; must match the registration key.
+ *   apiVersion   : 1
+ *   capabilities : {
+ *                    cancel?:    boolean — cancelSession() is meaningful.
+ *                    steering?:  boolean — mid-session follow-up messages.
+ *                    liveLog?:   boolean — a human-viewable live session URL.
+ *                  }
+ *
+ *   isConfigured({ config, project }) -> boolean
+ *       Cheap, synchronous, NO network. Answers "could a dispatch to this
+ *       provider possibly work right now for this project?" — credentials
+ *       present, repo binding resolvable, not disabled in config. Used as a
+ *       fail-closed pre-dispatch gate so a misconfigured provider surfaces as
+ *       CLOUD_PROVIDER_UNAVAILABLE at dispatch time instead of a mystery
+ *       session that never starts.
+ *
+ *   createSession({ project, repo, baseBranch, prompt, workItem, workdir })
+ *       -> Promise<{ sessionId, url?, providerRef? }>
+ *       Submits the task. `prompt` is the SAME rendered playbook prompt a
+ *       local agent would have received (minus local-only sections) — that
+ *       rendered instruction block is the entire reason this surface exists.
+ *       `sessionId` must be a stable, non-empty string usable by pollSession.
+ *
+ *   pollSession(sessionId, { project }) -> Promise<CloudSessionStatus>
+ *       Read-only. Must be safe to call every poll tick, and must never throw
+ *       for an ordinary "still running" answer.
+ *
+ *   cancelSession(sessionId, { reason, project }) -> Promise<void>
+ *       Best-effort. Only required when capabilities.cancel is true.
+ *
+ * CloudSessionStatus:
+ *   { state, prUrl?, summary?, error?, raw? }
+ *   state ∈ CLOUD_SESSION_STATE. `prUrl` is what the engine adopts into its PR
+ *   record so the existing ADO/GitHub pollers and review/fix loops take over
+ *   unchanged; a SUCCEEDED status with no `prUrl` is a contract violation and
+ *   is rejected by `normalizeSessionStatus`.
+ */
+
+const CLOUD_PROVIDER_API_VERSION = 1;
+
+const REQUIRED_METHODS = Object.freeze([
+  'isConfigured',
+  'createSession',
+  'pollSession',
+]);
+
+/**
+ * Remote session lifecycle. Deliberately smaller than any one provider's
+ * native state machine — providers map their vocabulary onto these five so
+ * orchestration never learns provider-specific state names.
+ */
+const CLOUD_SESSION_STATE = Object.freeze({
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  SUCCEEDED: 'succeeded',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+});
+
+const CLOUD_SESSION_STATE_VALUES = Object.freeze(Object.values(CLOUD_SESSION_STATE));
+
+const TERMINAL_CLOUD_SESSION_STATES = Object.freeze(new Set([
+  CLOUD_SESSION_STATE.SUCCEEDED,
+  CLOUD_SESSION_STATE.FAILED,
+  CLOUD_SESSION_STATE.CANCELLED,
+]));
+
+function isTerminalCloudSessionState(state) {
+  return TERMINAL_CLOUD_SESSION_STATES.has(String(state || '').trim().toLowerCase());
+}
+
+/**
+ * Validate + normalize a provider at registration time. Strict by design: a
+ * provider that registers successfully is one orchestration can call without
+ * defensive checks at every call site.
+ */
+function normalizeCloudProvider(name, provider) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('registerCloudProvider: name must be a non-empty string');
+  }
+  if (!provider || typeof provider !== 'object' || Array.isArray(provider)) {
+    throw new Error('registerCloudProvider: provider must be an object');
+  }
+  if (provider.name != null && provider.name !== name) {
+    throw new Error(
+      `registerCloudProvider: provider name "${provider.name}" does not match registry key "${name}"`
+    );
+  }
+  if (provider.apiVersion == null) {
+    throw new Error(`Cloud provider "${name}" must declare apiVersion ${CLOUD_PROVIDER_API_VERSION}`);
+  }
+  if (provider.apiVersion !== CLOUD_PROVIDER_API_VERSION) {
+    throw new Error(
+      `Cloud provider "${name}" API version ${provider.apiVersion} is unsupported; `
+      + `expected ${CLOUD_PROVIDER_API_VERSION}`
+    );
+  }
+
+  if (provider.capabilities == null) {
+    provider.capabilities = {};
+  } else if (typeof provider.capabilities !== 'object' || Array.isArray(provider.capabilities)) {
+    throw new Error(`Cloud provider "${name}" member capabilities must be an object`);
+  }
+
+  for (const method of REQUIRED_METHODS) {
+    if (typeof provider[method] !== 'function') {
+      throw new Error(`Cloud provider "${name}" is missing required method ${method}()`);
+    }
+  }
+  if (provider.cancelSession != null && typeof provider.cancelSession !== 'function') {
+    throw new Error(`Cloud provider "${name}" member cancelSession must be a function`);
+  }
+  // A provider that advertises cancellation must actually implement it —
+  // otherwise the session-timeout path would silently leave remote work
+  // running with no way to stop it.
+  if (provider.capabilities.cancel === true && typeof provider.cancelSession !== 'function') {
+    throw new Error(`Cloud provider "${name}" declares capabilities.cancel but does not implement cancelSession()`);
+  }
+
+  provider.name = name;
+  return provider;
+}
+
+/**
+ * Normalize what a provider returned from pollSession into the shape
+ * orchestration is allowed to trust. Throws on a contract violation rather
+ * than guessing, so a broken provider fails loudly at the poll site instead of
+ * silently completing a work item with no PR.
+ */
+function normalizeSessionStatus(providerName, status) {
+  if (!status || typeof status !== 'object' || Array.isArray(status)) {
+    throw new Error(`Cloud provider "${providerName}" pollSession() must return an object`);
+  }
+  const state = String(status.state || '').trim().toLowerCase();
+  if (!CLOUD_SESSION_STATE_VALUES.includes(state)) {
+    throw new Error(
+      `Cloud provider "${providerName}" pollSession() returned unknown state `
+      + `"${status.state}" (expected one of ${CLOUD_SESSION_STATE_VALUES.join(', ')})`
+    );
+  }
+  const prUrl = typeof status.prUrl === 'string' && status.prUrl.trim() ? status.prUrl.trim() : null;
+  if (state === CLOUD_SESSION_STATE.SUCCEEDED && !prUrl) {
+    throw new Error(
+      `Cloud provider "${providerName}" reported state "succeeded" without a prUrl — `
+      + `a cloud dispatch succeeds only when it produced a pull request Minions can adopt`
+    );
+  }
+  return {
+    state,
+    prUrl,
+    summary: typeof status.summary === 'string' ? status.summary : '',
+    error: typeof status.error === 'string' ? status.error : '',
+    raw: status.raw !== undefined ? status.raw : null,
+  };
+}
+
+/**
+ * Normalize a createSession() result. `sessionId` is the handle every later
+ * poll/cancel depends on, so an empty one is a hard error at submit time
+ * rather than an untrackable dispatch discovered minutes later.
+ */
+function normalizeCreatedSession(providerName, created) {
+  if (!created || typeof created !== 'object' || Array.isArray(created)) {
+    throw new Error(`Cloud provider "${providerName}" createSession() must return an object`);
+  }
+  const sessionId = typeof created.sessionId === 'string' ? created.sessionId.trim() : '';
+  if (!sessionId) {
+    throw new Error(`Cloud provider "${providerName}" createSession() must return a non-empty sessionId`);
+  }
+  return {
+    sessionId,
+    url: typeof created.url === 'string' && created.url.trim() ? created.url.trim() : null,
+    providerRef: created.providerRef !== undefined ? created.providerRef : null,
+  };
+}
+
+module.exports = {
+  CLOUD_PROVIDER_API_VERSION,
+  CLOUD_SESSION_STATE,
+  CLOUD_SESSION_STATE_VALUES,
+  TERMINAL_CLOUD_SESSION_STATES,
+  REQUIRED_METHODS,
+  isTerminalCloudSessionState,
+  normalizeCloudProvider,
+  normalizeSessionStatus,
+  normalizeCreatedSession,
+};