@yemi33/minions 0.1.2382 → 0.1.2384

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

@@ -32,11 +32,19 @@ const https = require('https');
 const os = require('os');
 const path = require('path');
 const { execSync } = require('child_process');
-const { FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shared');
+const { ENGINE_DEFAULTS, FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shared');
 
 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,84 @@ 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
+      ?? ENGINE_DEFAULTS.copilotDisableBuiltinMcps;
+  }
+  if (resolved.reasoningSummaries == null) {
+    resolved.reasoningSummaries = engineConfig.copilotReasoningSummaries;
+  }
+  if (failureClass === FAILURE_CLASS.MODEL_UNAVAILABLE && engineConfig.copilotFallbackModel) {
+    resolved.model = engineConfig.copilotFallbackModel;
+  }
+  if (Array.isArray(resolved.disabledMcpServers)) {
+    resolved.disabledMcpServers = [...new Set(
+      resolved.disabledMcpServers.filter(Boolean).map(String)
+    )].sort();
+  }
+  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(options = {}) {
+  const maxTurns = Number(options.maxTurns);
+  const args = [
+    '--acp',
+    '--allow-all',
+    '--max-autopilot-continues',
+    String(Number.isFinite(maxTurns) && maxTurns > 0 ? Math.floor(maxTurns) : 1),
+  ];
+  if (options.disableBuiltinMcps === true) args.push('--disable-builtin-mcps');
+  if (options.reasoningSummaries === true) args.push('--enable-reasoning-summaries');
+  for (const name of options.disabledMcpServers || []) {
+    if (name) args.push('--disable-mcp-server', String(name));
+  }
+  return args;
+}
+
+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 +1450,8 @@ function getMcpConfigPaths({ homeDir = os.homedir(), project = null } = {}) {
 }
 
 module.exports = {
-  name: 'copilot',
+  apiVersion: 1,
+  name: RUNTIME_NAME,
   capabilities,
   resolveBinary,
   capsFile: CAPS_FILE,
@@ -1379,7 +1460,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 +1484,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 +1506,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,
 };