@yemi33/minions 0.1.2382 → 0.1.2383

package/engine/runtimes/claude.js

@@ -6,23 +6,9 @@
  * everything Claude-CLI-specific: binary resolution, arg construction, prompt
  * preparation, output parsing, and error normalization.
  *
- * Adapter contract (all runtimes must implement):
- *   - name: string
- *   - capabilities: { ... } feature flags consumed by engine code
- *   - resolveBinary() → { bin, native, leadingArgs }
- *   - capsFile: absolute path of the binary-resolution cache for this runtime
- *   - listModels() → Promise<{id,name,provider}[] | null>
- *   - modelsCache: absolute path of the model-list cache for this runtime
- *   - spawnScript: absolute path of the spawn wrapper (or null if direct-only)
- *   - buildArgs(opts) → string[] — CLI args excluding the binary
- *   - buildPrompt(promptText, sysPromptText) → string — final prompt delivered
- *   - getUserAssetDirs(opts) → string[] — runtime-native global asset roots
- *   - getSkillRoots(opts) → {scope,dir,projectName?}[] — skill discovery roots
- *   - getSkillWriteTargets(opts) → {personal,project} — extraction targets
- *   - resolveModel(input) → string|undefined — shorthand expansion / passthrough
- *   - parseOutput(raw) → { text, usage, sessionId, model }
- *   - parseStreamChunk(line) → parsed event object or null
- *   - parseError(rawOutput) → { message, code, retriable }
+ * The versioned adapter contract and compatibility defaults live in
+ * engine/runtimes/contract.js. Keep harness-specific argv, prompt, parser,
+ * workspace, and persistent-worker behavior in this module.
  */
 
 const fs = require('fs');
@@ -36,6 +22,8 @@ const MINIONS_DIR = path.resolve(ENGINE_DIR, '..');
 const _CACHE_DIR = resolveEngineCacheDir(ENGINE_DIR);
 
 const isWin = process.platform === 'win32';
+const RUNTIME_NAME = 'claude';
+const SPAWN_STARTUP_SUBTYPES = new Set(['init', 'hook_started', 'hook_response']);
 
 // ── Binary Resolution ────────────────────────────────────────────────────────
 // Mirrors engine/spawn-agent.js:26-91. Cached at engine/claude-caps.json so the
@@ -253,7 +241,7 @@ function buildArgs(opts = {}) {
 }
 
 function buildSpawnFlags(opts = {}) {
-  const flags = ['--runtime', 'claude'];
+  const flags = ['--runtime', RUNTIME_NAME];
   if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
   if (opts.model) flags.push('--model', String(opts.model));
   if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
@@ -268,12 +256,13 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
-// Stamped into every session.json this adapter writes so the pre-spawn resume
-// path can detect "session was produced by a different runtime" — Claude
-// rejects Copilot session IDs (and vice versa) with "No conversation found",
-// which would otherwise burn a retry slot before the post-failure cleanup at
-// engine.js:1195 fires. See W-mot9fwya000d09cb.
-const RUNTIME_NAME = 'claude';
+function resolveInvocationOptions({ options = {}, engineConfig = {} } = {}) {
+  const resolved = { ...options };
+  if (resolved.fallbackModel == null && engineConfig.claudeFallbackModel) {
+    resolved.fallbackModel = engineConfig.claudeFallbackModel;
+  }
+  return resolved;
+}
 
 /**
  * Compute the directory Claude CLI uses to persist a project's conversation
@@ -934,6 +923,81 @@ function getMcpConfigPaths({ homeDir = os.homedir(), project = null } = {}) {
   return paths;
 }
 
+function prepareWorkspace({
+  worktreePath,
+  homeDir,
+  engineConfig,
+  mutateJsonFileLocked,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+} = {}) {
+  if (engineConfig && engineConfig.claudePreApproveWorkspaceMcps === false) {
+    return { wrote: false, reason: 'flag-off', servers: [] };
+  }
+  if (!worktreePath || typeof worktreePath !== 'string') {
+    return { wrote: false, reason: 'no-worktree', servers: [] };
+  }
+  const workspaceMcpPath = path.join(worktreePath, '.mcp.json');
+  if (!existsSync(workspaceMcpPath)) {
+    return { wrote: false, reason: 'no-workspace-mcp', servers: [] };
+  }
+  let workspaceMcp;
+  try {
+    workspaceMcp = JSON.parse(readFileSync(workspaceMcpPath, 'utf8'));
+  } catch {
+    return { wrote: false, reason: 'invalid-workspace-mcp', servers: [] };
+  }
+  const serversObj = workspaceMcp && typeof workspaceMcp === 'object' ? workspaceMcp.mcpServers : null;
+  const servers = serversObj && typeof serversObj === 'object' && !Array.isArray(serversObj)
+    ? Object.keys(serversObj).filter(name => typeof name === 'string' && name.length > 0)
+    : [];
+  if (servers.length === 0) {
+    return { wrote: false, reason: 'no-servers', servers: [] };
+  }
+  if (!homeDir || typeof mutateJsonFileLocked !== 'function') {
+    return { wrote: false, reason: 'no-home-or-mutator', servers };
+  }
+
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  let didWrite = false;
+  mutateJsonFileLocked(claudeJsonPath, (data) => {
+    const root = data && typeof data === 'object' ? data : {};
+    if (!root.projects || typeof root.projects !== 'object') root.projects = {};
+    const projectState = root.projects[worktreePath] && typeof root.projects[worktreePath] === 'object'
+      ? root.projects[worktreePath]
+      : {};
+    const enabled = Array.isArray(projectState.enabledMcpjsonServers)
+      ? projectState.enabledMcpjsonServers.slice()
+      : [];
+    const disabled = Array.isArray(projectState.disabledMcpjsonServers)
+      ? projectState.disabledMcpjsonServers.slice()
+      : [];
+    const enabledSet = new Set(enabled.filter(name => typeof name === 'string'));
+    let mutated = false;
+    for (const name of servers) {
+      if (!enabledSet.has(name)) {
+        enabledSet.add(name);
+        mutated = true;
+      }
+    }
+    const nextDisabled = disabled.filter(name => typeof name === 'string' && !servers.includes(name));
+    if (nextDisabled.length !== disabled.length) mutated = true;
+    if (!mutated) return data;
+    projectState.enabledMcpjsonServers = [...enabledSet];
+    projectState.disabledMcpjsonServers = nextDisabled;
+    root.projects[worktreePath] = projectState;
+    didWrite = true;
+    return root;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+
+  return { wrote: didWrite, reason: 'ok', servers, target: claudeJsonPath };
+}
+
+function isSpawnStartupEvent(event) {
+  if (!event || event.type !== 'system') return false;
+  return SPAWN_STARTUP_SUBTYPES.has(typeof event.subtype === 'string' ? event.subtype : '');
+}
+
 // Heuristic: does `model` look like a Claude model identifier? Powers the
 // preflight "stale model after CLI switch" warning in cli.js. Returning false
 // means "this looks wrong for Claude" — gpt-5.4 / o3-* / codex etc. Keep this
@@ -948,7 +1012,8 @@ function modelLooksFamiliar(model) {
 }
 
 module.exports = {
-  name: 'claude',
+  apiVersion: 1,
+  name: RUNTIME_NAME,
   capabilities,
   resolveBinary,
   capsFile: CAPS_FILE,
@@ -956,6 +1021,7 @@ module.exports = {
   modelsCache: MODELS_CACHE,
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  resolveInvocationOptions,
   buildSpawnFlags,
   buildArgs,
   buildPrompt,
@@ -964,6 +1030,8 @@ module.exports = {
   getSkillWriteTargets,
   getCommandRoots,
   getMcpConfigPaths,
+  prepareWorkspace,
+  isSpawnStartupEvent,
   getResumeSessionId,
   saveSession,
   detectPermissionGate,
@@ -981,4 +1049,5 @@ module.exports = {
   _CLAUDE_SHORTHANDS,
   _extractInvalidModelName,
   THINKING_BLOCK_TYPES,
+  SPAWN_STARTUP_SUBTYPES,
 };

package/engine/runtimes/codex.js

@@ -929,6 +929,7 @@ const INSTALL_HINT = 'install Codex CLI with `npm install -g @openai/codex` or `
 const PERMISSION_BYPASS_FLAGS = ['--sandbox'];
 
 module.exports = {
+  apiVersion: 1,
   name: RUNTIME_NAME,
   capabilities,
   resolveBinary,

package/engine/runtimes/contract.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const ADAPTER_API_VERSION = 1;
+const RUNTIME_OPTIONS_FLAG = '--runtime-options';
+const RUNTIME_IMAGES_FILE_OPTION = '_minionsImagesFile';
+const legacyAdapters = new WeakSet();
+
+const CORE_METHODS = Object.freeze([
+  'resolveBinary',
+  'listModels',
+  'buildArgs',
+  'buildPrompt',
+  'resolveModel',
+  'parseOutput',
+  'parseStreamChunk',
+  'parseError',
+]);
+
+function normalizeRuntimeAdapter(name, adapter, { strict = false } = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('registerRuntime: name must be a non-empty string');
+  }
+  if (!adapter || typeof adapter !== 'object' || Array.isArray(adapter)) {
+    throw new Error('registerRuntime: adapter must be an object');
+  }
+  if (adapter.name != null && adapter.name !== name) {
+    throw new Error(`registerRuntime: adapter name "${adapter.name}" does not match registry key "${name}"`);
+  }
+  const hasExplicitApiVersion = adapter.apiVersion != null;
+  if (strict && !hasExplicitApiVersion) {
+    throw new Error(`Runtime "${name}" adapter must declare apiVersion ${ADAPTER_API_VERSION}`);
+  }
+  if (hasExplicitApiVersion && adapter.apiVersion !== ADAPTER_API_VERSION) {
+    throw new Error(
+      `Runtime "${name}" adapter API version ${adapter.apiVersion} is unsupported; expected ${ADAPTER_API_VERSION}`
+    );
+  }
+
+  adapter.name = name;
+  adapter.apiVersion = ADAPTER_API_VERSION;
+  if (!hasExplicitApiVersion) legacyAdapters.add(adapter);
+  if (adapter.capabilities == null) {
+    adapter.capabilities = {};
+  } else if (typeof adapter.capabilities !== 'object' || Array.isArray(adapter.capabilities)) {
+    throw new Error(`Runtime "${name}" adapter member capabilities must be an object`);
+  }
+
+  for (const method of CORE_METHODS) {
+    if (adapter[method] != null && typeof adapter[method] !== 'function') {
+      throw new Error(`Runtime "${name}" adapter member ${method} must be a function`);
+    }
+    if (strict && typeof adapter[method] !== 'function') {
+      throw new Error(`Runtime "${name}" adapter is missing required method ${method}()`);
+    }
+  }
+
+  if (adapter.capabilities.streamConsumer === true && typeof adapter.createStreamConsumer !== 'function') {
+    throw new Error(`Runtime "${name}" declares streamConsumer but does not implement createStreamConsumer()`);
+  }
+  if (adapter.capabilities.acpWorkerPool === true) {
+    for (const method of ['buildWorkerArgs', 'encodePooledOutput']) {
+      if (typeof adapter[method] !== 'function') {
+        throw new Error(`Runtime "${name}" declares acpWorkerPool but does not implement ${method}()`);
+      }
+    }
+  }
+  return adapter;
+}
+
+function sanitizeInvocationOptions(runtime, options = {}) {
+  const caps = runtime?.capabilities || {};
+  const sanitized = { ...(options || {}) };
+  if (!caps.effortLevels) delete sanitized.effort;
+  if (!caps.sessionResume
+      || typeof sanitized.sessionId !== 'string'
+      || !sanitized.sessionId.trim()) {
+    delete sanitized.sessionId;
+  } else {
+    sanitized.sessionId = sanitized.sessionId.trim();
+  }
+  if (!caps.budgetCap) delete sanitized.maxBudget;
+  if (!caps.bareMode) delete sanitized.bare;
+  if (!caps.fallbackModel) delete sanitized.fallbackModel;
+  if (!caps.imageInput) {
+    delete sanitized.images;
+    delete sanitized[RUNTIME_IMAGES_FILE_OPTION];
+  }
+  return sanitized;
+}
+
+function resolveInvocationOptions(runtime, options = {}, context = {}) {
+  if (!runtime || typeof runtime !== 'object') throw new Error('resolveInvocationOptions: runtime adapter is required');
+  let resolved = { ...(options || {}) };
+  if (typeof runtime.resolveInvocationOptions === 'function') {
+    resolved = runtime.resolveInvocationOptions({
+      ...context,
+      options: resolved,
+    });
+  }
+  if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) {
+    throw new Error(`Runtime "${runtime.name}" resolveInvocationOptions() must return an object`);
+  }
+  return sanitizeInvocationOptions(runtime, resolved);
+}
+
+function encodeRuntimeOptions(options = {}) {
+  return Buffer.from(JSON.stringify(options || {}), 'utf8').toString('base64url');
+}
+
+function decodeRuntimeOptions(encoded) {
+  if (typeof encoded !== 'string' || !encoded) {
+    throw new Error(`${RUNTIME_OPTIONS_FLAG} requires a non-empty base64url value`);
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8'));
+  } catch (err) {
+    throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: ${err.message}`);
+  }
+  if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
+    throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: expected a JSON object`);
+  }
+  for (const key of ['__proto__', 'prototype', 'constructor']) {
+    if (Object.prototype.hasOwnProperty.call(decoded, key)) {
+      throw new Error(`Invalid ${RUNTIME_OPTIONS_FLAG} payload: forbidden key "${key}"`);
+    }
+  }
+  return decoded;
+}
+
+function buildSpawnFlags(runtime, options = {}) {
+  if (!runtime || typeof runtime !== 'object') throw new Error('buildSpawnFlags: runtime adapter is required');
+  const isLegacy = runtime.apiVersion !== ADAPTER_API_VERSION || legacyAdapters.has(runtime);
+  if (isLegacy && typeof runtime.buildSpawnFlags === 'function') {
+    const legacyFlags = runtime.buildSpawnFlags(options || {});
+    if (!Array.isArray(legacyFlags) || legacyFlags.some(flag => typeof flag !== 'string')) {
+      throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() must return string[]`);
+    }
+    return legacyFlags;
+  }
+
+  const sanitized = sanitizeInvocationOptions(runtime, options);
+  let flags;
+  if (typeof runtime.buildSpawnFlags === 'function') {
+    flags = runtime.buildSpawnFlags(sanitized);
+  } else {
+    const caps = runtime.capabilities || {};
+    flags = ['--runtime', String(runtime.name)];
+    if (sanitized.maxTurns != null) flags.push('--max-turns', String(sanitized.maxTurns));
+    if (sanitized.model) flags.push('--model', String(sanitized.model));
+    if (sanitized.allowedTools) flags.push('--allowedTools', String(sanitized.allowedTools));
+    if (caps.effortLevels && sanitized.effort) flags.push('--effort', String(sanitized.effort));
+    if (caps.sessionResume && sanitized.sessionId) flags.push('--resume', String(sanitized.sessionId));
+    if (caps.budgetCap && sanitized.maxBudget != null) flags.push('--max-budget-usd', String(sanitized.maxBudget));
+    if (caps.bareMode && sanitized.bare === true) flags.push('--bare');
+    if (caps.fallbackModel && sanitized.fallbackModel) {
+      flags.push('--fallback-model', String(sanitized.fallbackModel));
+    }
+    if (sanitized.stream === 'on' || sanitized.stream === 'off') {
+      flags.push('--stream', sanitized.stream);
+    }
+    if (sanitized.disableBuiltinMcps === true) flags.push('--disable-builtin-mcps');
+    if (sanitized.reasoningSummaries === true) flags.push('--enable-reasoning-summaries');
+  }
+  if (!Array.isArray(flags) || flags.some(flag => typeof flag !== 'string')) {
+    throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() must return string[]`);
+  }
+  if (flags[0] !== '--runtime') flags = ['--runtime', String(runtime.name), ...flags];
+  if (flags[1] !== runtime.name) {
+    throw new Error(`Runtime "${runtime.name}" buildSpawnFlags() emitted mismatched runtime "${flags[1]}"`);
+  }
+  if (isLegacy) return flags;
+  return [...flags, RUNTIME_OPTIONS_FLAG, encodeRuntimeOptions(sanitized)];
+}
+
+function prepareWorkspace(runtime, context = {}) {
+  if (!runtime || typeof runtime.prepareWorkspace !== 'function') {
+    return { wrote: false, reason: 'unsupported-runtime', servers: [] };
+  }
+  return runtime.prepareWorkspace(context);
+}
+
+function isSpawnStartupEvent(runtime, event) {
+  if (!runtime || typeof runtime.isSpawnStartupEvent !== 'function') return false;
+  try {
+    return runtime.isSpawnStartupEvent(event) === true;
+  } catch {
+    return false;
+  }
+}
+
+function shouldSuppressPostMutationError(runtime, context = {}) {
+  if (!runtime || typeof runtime.shouldSuppressPostMutationError !== 'function') return false;
+  try {
+    return runtime.shouldSuppressPostMutationError(context) === true;
+  } catch {
+    return false;
+  }
+}
+
+function buildWorkerArgs(runtime, options = {}) {
+  if (runtime?.capabilities?.acpWorkerPool !== true) {
+    throw new Error(`Runtime "${runtime?.name || '<unknown>'}" does not support persistent ACP workers`);
+  }
+  const args = runtime.buildWorkerArgs(options);
+  if (!Array.isArray(args) || args.some(arg => typeof arg !== 'string')) {
+    throw new Error(`Runtime "${runtime.name}" buildWorkerArgs() must return string[]`);
+  }
+  return args;
+}
+
+function encodePooledOutput(runtime, event) {
+  if (runtime?.capabilities?.acpWorkerPool !== true) {
+    throw new Error(`Runtime "${runtime?.name || '<unknown>'}" does not support pooled output`);
+  }
+  const encoded = runtime.encodePooledOutput(event);
+  if (typeof encoded !== 'string') {
+    throw new Error(`Runtime "${runtime.name}" encodePooledOutput() must return a string`);
+  }
+  return encoded;
+}
+
+module.exports = {
+  ADAPTER_API_VERSION,
+  RUNTIME_OPTIONS_FLAG,
+  RUNTIME_IMAGES_FILE_OPTION,
+  CORE_METHODS,
+  normalizeRuntimeAdapter,
+  sanitizeInvocationOptions,
+  resolveInvocationOptions,
+  encodeRuntimeOptions,
+  decodeRuntimeOptions,
+  buildSpawnFlags,
+  prepareWorkspace,
+  isSpawnStartupEvent,
+  shouldSuppressPostMutationError,
+  buildWorkerArgs,
+  encodePooledOutput,
+};

package/engine/runtimes/copilot.js

@@ -37,6 +37,14 @@ const { FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shar
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const _CACHE_DIR = resolveEngineCacheDir(ENGINE_DIR);
 const isWin = process.platform === 'win32';
+const RUNTIME_NAME = 'copilot';
+const SPAWN_STARTUP_TYPES = new Set([
+  'session.mcp_server_status_changed',
+  'session.mcp_servers_loaded',
+  'session.skills_loaded',
+  'session.tools_updated',
+  'session.info',
+]);
 
 // ── Binary Resolution ───────────────────────────────────────────────────────
 //
@@ -529,7 +537,7 @@ function buildArgs(opts = {}) {
 }
 
 function buildSpawnFlags(opts = {}) {
-  const flags = ['--runtime', 'copilot'];
+  const flags = ['--runtime', RUNTIME_NAME];
   if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
   if (opts.model) flags.push('--model', String(opts.model));
   if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
@@ -552,12 +560,66 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
-// Stamped into every session.json this adapter writes so the pre-spawn resume
-// path can detect "session was produced by a different runtime" — Copilot
-// rejects Claude session IDs (and vice versa) with "No conversation found",
-// which would otherwise burn a retry slot before the post-failure cleanup at
-// engine.js:1195 fires. See W-mot9fwya000d09cb.
-const RUNTIME_NAME = 'copilot';
+function resolveInvocationOptions({
+  options = {},
+  engineConfig = {},
+  failureClass = null,
+} = {}) {
+  const resolved = { ...options };
+  if (resolved.stream == null) resolved.stream = engineConfig.copilotStreamMode;
+  if (resolved.disableBuiltinMcps == null) {
+    resolved.disableBuiltinMcps = engineConfig.copilotDisableBuiltinMcps;
+  }
+  if (resolved.reasoningSummaries == null) {
+    resolved.reasoningSummaries = engineConfig.copilotReasoningSummaries;
+  }
+  if (failureClass === FAILURE_CLASS.MODEL_UNAVAILABLE && engineConfig.copilotFallbackModel) {
+    resolved.model = engineConfig.copilotFallbackModel;
+  }
+  return resolved;
+}
+
+function isSpawnStartupEvent(event) {
+  return !!event && SPAWN_STARTUP_TYPES.has(event.type);
+}
+
+function shouldSuppressPostMutationError({ mutationApplied, error } = {}) {
+  if (mutationApplied !== true || !error) return false;
+  return error.errorClass === 'unknown-model' || error.errorClass === 'model-unavailable';
+}
+
+function buildWorkerArgs() {
+  return ['--acp', '--allow-all', '--max-autopilot-continues', '1'];
+}
+
+function encodePooledOutput(event = {}) {
+  if (event.kind === 'model') {
+    return JSON.stringify({
+      type: 'session.tools_updated',
+      data: { model: event.model || null },
+    }) + '\n';
+  }
+  if (event.kind === 'chunk') {
+    return JSON.stringify({
+      type: 'assistant.message_delta',
+      data: { deltaContent: event.text || '' },
+    }) + '\n';
+  }
+  if (event.kind === 'result') {
+    return JSON.stringify({
+      type: 'result',
+      sessionId: event.sessionId || null,
+      usage: {
+        totalApiDurationMs: event.durationMs,
+        stopReason: event.stopReason || null,
+      },
+    }) + '\n';
+  }
+  throw new Error(`Unsupported pooled output event kind: ${event.kind || '<missing>'}`);
+}
+
+// RUNTIME_NAME is stamped into every session.json so the pre-spawn resume path
+// can reject session IDs produced by another adapter before invoking the CLI.
 
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
@@ -1370,7 +1432,8 @@ function getMcpConfigPaths({ homeDir = os.homedir(), project = null } = {}) {
 }
 
 module.exports = {
-  name: 'copilot',
+  apiVersion: 1,
+  name: RUNTIME_NAME,
   capabilities,
   resolveBinary,
   capsFile: CAPS_FILE,
@@ -1379,7 +1442,11 @@ module.exports = {
   // Use the same wrapper as Claude — spawn-agent.js is runtime-agnostic per P-9c4f2d6a
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  workerErrorHint: 'copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete',
+  resolveInvocationOptions,
   buildSpawnFlags,
+  buildWorkerArgs,
+  encodePooledOutput,
   buildArgs,
   buildPrompt,
   getUserAssetDirs,
@@ -1399,6 +1466,8 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  isSpawnStartupEvent,
+  shouldSuppressPostMutationError,
   permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — engine code MUST go through resolveRuntime + the
   // adapter contract; never reach into these helpers directly.
@@ -1419,4 +1488,5 @@ module.exports = {
   _extractInvalidModelName,
   CAPS_SCHEMA_VERSION,
   KNOWN_EVENT_TYPES,
+  SPAWN_STARTUP_TYPES,
 };

package/engine/runtimes/index.js

@@ -7,18 +7,16 @@
  * runtime name fails loudly with a clear list of registered options.
  *
  * Adding a new runtime:
- *   1. Implement the full adapter contract documented in claude.js.
- *   2. `registry.set('<name>', require('./<name>'));` below.
+ *   1. Implement API version 1 from contract.js.
+ *   2. `registerRuntime('<name>', require('./<name>'), { strict: true });`.
  *   3. Expose its capabilities via the `/api/runtimes` endpoint (free).
  *
  * Engine code MUST gate behavior on `runtime.capabilities.*` flags, not on
  * `runtime.name === 'claude'` comparisons. The whole point of this layer.
  */
 
+const contract = require('./contract');
 const registry = new Map();
-registry.set('claude', require('./claude'));
-registry.set('codex', require('./codex'));
-registry.set('copilot', require('./copilot'));
 
 /**
  * Look up a runtime adapter by name. Throws when the name is unknown so
@@ -47,16 +45,46 @@ function listRuntimes() {
  * Register a runtime adapter. Exposed for tests and for downstream tooling
  * that wants to register a custom runtime without editing this file.
  */
-function registerRuntime(name, adapter) {
-  if (!name || typeof name !== 'string') throw new Error('registerRuntime: name must be a non-empty string');
-  if (!adapter || typeof adapter !== 'object') throw new Error('registerRuntime: adapter must be an object');
-  registry.set(name, adapter);
+function registerRuntime(name, adapter, options) {
+  const normalized = contract.normalizeRuntimeAdapter(name, adapter, options);
+  registry.set(name, normalized);
+  return normalized;
 }
 
+function resolveRuntimeByCapability(capability) {
+  const matches = listRuntimes()
+    .map(name => registry.get(name))
+    .filter(adapter => adapter?.capabilities?.[capability] === true);
+  if (matches.length === 0) {
+    throw new Error(
+      `No registered runtime declares capability "${capability}"`
+    );
+  }
+  return matches[0];
+}
+
+registerRuntime('claude', require('./claude'), { strict: true });
+registerRuntime('codex', require('./codex'), { strict: true });
+registerRuntime('copilot', require('./copilot'), { strict: true });
+
 module.exports = {
+  ADAPTER_API_VERSION: contract.ADAPTER_API_VERSION,
+  RUNTIME_OPTIONS_FLAG: contract.RUNTIME_OPTIONS_FLAG,
+  RUNTIME_IMAGES_FILE_OPTION: contract.RUNTIME_IMAGES_FILE_OPTION,
   resolveRuntime,
+  resolveRuntimeByCapability,
   listRuntimes,
   registerRuntime,
+  sanitizeInvocationOptions: contract.sanitizeInvocationOptions,
+  resolveInvocationOptions: contract.resolveInvocationOptions,
+  decodeRuntimeOptions: contract.decodeRuntimeOptions,
+  buildSpawnFlags: contract.buildSpawnFlags,
+  prepareWorkspace: contract.prepareWorkspace,
+  isSpawnStartupEvent: contract.isSpawnStartupEvent,
+  shouldSuppressPostMutationError: contract.shouldSuppressPostMutationError,
+  buildWorkerArgs: contract.buildWorkerArgs,
+  encodePooledOutput: contract.encodePooledOutput,
+  validateRuntimeAdapter: contract.normalizeRuntimeAdapter,
   // Exposed for tests — engine code MUST go through resolveRuntime/listRuntimes
   _registry: registry,
 };