@the-open-engine/zeroshot 6.3.0 → 6.5.0

package/src/isolation-manager.js

@@ -16,8 +16,13 @@ const os = require('os');
 const fs = require('fs');
 const { loadSettings } = require('../lib/settings');
 const { CLAUDE_AUTH_ENV_VARS, resolveClaudeAuth } = require('../lib/settings/claude-auth');
-const { normalizeProviderName } = require('../lib/provider-names');
-const { resolveMounts, resolveEnvs, expandEnvPatterns } = require('../lib/docker-config');
+const { normalizeProviderName, getProviderMetadata } = require('../lib/provider-names');
+const {
+  MOUNT_PRESETS,
+  resolveMounts,
+  resolveEnvs,
+  expandEnvPatterns,
+} = require('../lib/docker-config');
 const { getProvider } = require('./providers');
 const { readRepoSettings } = require('../lib/repo-settings');
 const { provisionClaudeCredentials } = require('./claude-credentials');
@@ -98,6 +103,24 @@ function resolveWorktreeSetupTimeoutMs(repoSettings = {}, options = {}) {
 
 const DEFAULT_IMAGE = 'zeroshot-cluster-base';
 
+/**
+ * Shell command that installs a provider's CLI inside the cluster image, or null when the
+ * provider is baked into the base image (e.g. Claude) or has no single-command installer.
+ * Sourced from the provider registry (docker.install) so nothing here is provider-specific.
+ * @param {string} providerName
+ * @returns {string|null}
+ */
+function providerDockerInstall(providerName) {
+  if (!providerName) return null;
+  try {
+    const metadata = getProviderMetadata(providerName);
+    const install = metadata && metadata.docker && metadata.docker.install;
+    return typeof install === 'string' && install.trim() ? install.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 class IsolationManager {
   constructor(options = {}) {
     this.image = options.image || DEFAULT_IMAGE;
@@ -171,7 +194,13 @@ class IsolationManager {
       clusterConfigDir,
     });
 
-    const mountedHosts = this._applyCredentialMounts(args, config, settings, containerHome);
+    const mountedHosts = this._applyCredentialMounts(
+      args,
+      config,
+      settings,
+      containerHome,
+      providerName
+    );
     this._warnMissingProviderCredentials(providerName, mountedHosts, config, containerHome);
 
     args.push('-w', '/workspace', image, 'tail', '-f', '/dev/null');
@@ -285,13 +314,25 @@ class IsolationManager {
     return settings.dockerMounts;
   }
 
-  _applyCredentialMounts(args, config, settings, containerHome) {
+  // Auto-activate the running provider's own credential preset (mount + env) so `--docker` works
+  // without listing it in dockerMounts. Claude is mounted separately, so skip it.
+  _withActiveProviderPreset(mountConfig, providerName) {
+    if (!providerName || providerName === 'claude') return mountConfig;
+    if (!MOUNT_PRESETS[providerName]) return mountConfig;
+    if (mountConfig.some((item) => item === providerName)) return mountConfig;
+    return [...mountConfig, providerName];
+  }
+
+  _applyCredentialMounts(args, config, settings, containerHome, providerName) {
     const mountedHosts = [];
     if (config.noMounts) {
       return mountedHosts;
     }
 
-    const mountConfig = this._resolveMountConfig(config, settings);
+    const mountConfig = this._withActiveProviderPreset(
+      this._resolveMountConfig(config, settings),
+      providerName
+    );
     const mounts = resolveMounts(mountConfig, { containerHome });
     const claudeContainerPath = path.posix.join(containerHome, '.claude');
 
@@ -363,16 +404,40 @@ class IsolationManager {
       return;
     }
 
+    const metadata = getProviderMetadata(providerName);
     const provider = getProvider(providerName);
+
+    // An env token (e.g. COPILOT_GITHUB_TOKEN) is a complete credential on its own.
+    const credentialEnvKeys = metadata.credentialEnvKeys || [];
+    if (credentialEnvKeys.some((key) => process.env[key])) {
+      return;
+    }
+
+    // A mount only counts if it carries the secret (credentialInMount !== false).
+    const credentialInMount = metadata.docker && metadata.docker.credentialInMount === false;
     const credentialPaths = provider.getCredentialPaths ? provider.getCredentialPaths() : [];
     const expandedCreds = credentialPaths.map((cred) => expandHomePath(cred));
-    const hasCredentialMount = mountedHosts.some((hostPath) =>
-      expandedCreds.some(
-        (credPath) => pathContains(hostPath, credPath) || pathContains(credPath, hostPath)
-      )
-    );
+    const hasCredentialMount =
+      !credentialInMount &&
+      mountedHosts.some((hostPath) =>
+        expandedCreds.some(
+          (credPath) => pathContains(hostPath, credPath) || pathContains(credPath, hostPath)
+        )
+      );
+    if (hasCredentialMount) {
+      return;
+    }
+
+    if (credentialInMount && credentialEnvKeys.length > 0) {
+      console.warn(
+        `[IsolationManager] ⚠️  ${provider.displayName} could not find credentials for Docker. ` +
+          `Its login token is not stored in a mountable file — export one of ` +
+          `${credentialEnvKeys.join(', ')} before running with --docker.`
+      );
+      return;
+    }
 
-    if (!hasCredentialMount && expandedCreds.length > 0) {
+    if (expandedCreds.length > 0) {
       const exampleHost = credentialPaths[0];
       const exampleContainer = exampleHost.replace(/^~(?=\/|$)/, containerHome);
       const mountNote = config.noMounts ? 'Credential mounts are disabled. ' : '';
@@ -1230,13 +1295,40 @@ class IsolationManager {
     }
   }
 
+  /**
+   * Resolve the cluster image tag for a provider. Providers baked into the base image (e.g.
+   * Claude) run on the base image directly; providers with a `docker.install` command get a
+   * per-provider image variant `<baseImage>-<providerId>` whose install step is a Docker-cached
+   * layer (built once, reused thereafter).
+   * @param {string} providerName
+   * @param {string} [baseImage]
+   * @returns {string}
+   */
+  static imageForProvider(providerName, baseImage = DEFAULT_IMAGE) {
+    if (!providerDockerInstall(providerName)) {
+      return baseImage;
+    }
+    return `${baseImage}-${normalizeProviderName(providerName)}`;
+  }
+
+  /**
+   * Docker `--build-arg` values that install a provider's CLI into its image variant, or [] when
+   * the provider is baked into the base image or has no installer.
+   * @param {string} providerName
+   * @returns {string[]}
+   */
+  static providerBuildArgs(providerName) {
+    const install = providerDockerInstall(providerName);
+    return install ? [`PROVIDER_INSTALL=${install}`] : [];
+  }
+
   /**
    * Build the Docker image with retry logic
    * @param {string} [image] - Image name to build
    * @param {number} [maxRetries=3] - Maximum retry attempts
    * @returns {Promise<void>}
    */
-  static async buildImage(image = DEFAULT_IMAGE, maxRetries = 3) {
+  static async buildImage(image = DEFAULT_IMAGE, maxRetries = 3, buildArgs = []) {
     // Repository root is one level up from src/
     const repoRoot = path.join(__dirname, '..');
     const dockerfilePath = path.join(repoRoot, 'docker', 'zeroshot-cluster', 'Dockerfile');
@@ -1245,6 +1337,12 @@ class IsolationManager {
       throw new Error(`Dockerfile not found at ${dockerfilePath}`);
     }
 
+    // Each buildArg becomes a `--build-arg KEY=VALUE` pair (e.g. the per-provider install command).
+    const buildArgFlags = [];
+    for (const arg of buildArgs) {
+      buildArgFlags.push('--build-arg', arg);
+    }
+
     console.log(`[IsolationManager] Building Docker image '${image}'...`);
 
     const baseDelay = 3000; // 3 seconds
@@ -1253,11 +1351,18 @@ class IsolationManager {
       try {
         // CRITICAL: Run from repo root so build context includes package.json and src/
         // Use -f flag to specify Dockerfile location
-        runSync('docker', ['build', '-f', 'docker/zeroshot-cluster/Dockerfile', '-t', image, '.'], {
-          cwd: repoRoot,
-          encoding: 'utf8',
-          stdio: 'inherit',
-        });
+        runSync(
+          'docker',
+          ['build', '-f', 'docker/zeroshot-cluster/Dockerfile', ...buildArgFlags, '-t', image, '.'],
+          {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: 'inherit',
+            // No timeout: image builds legitimately take many minutes (apt, tool downloads,
+            // provider install). runSync's 30s default would kill every build (ETIMEDOUT).
+            timeout: 0,
+          }
+        );
 
         console.log(`[IsolationManager] ✓ Image '${image}' built successfully`);
         return;
@@ -1284,7 +1389,7 @@ class IsolationManager {
    * @param {boolean} [autoBuild=true] - Auto-build if missing
    * @returns {Promise<void>}
    */
-  static async ensureImage(image = DEFAULT_IMAGE, autoBuild = true) {
+  static async ensureImage(image = DEFAULT_IMAGE, autoBuild = true, buildArgs = []) {
     if (this.imageExists(image)) {
       return;
     }
@@ -1297,7 +1402,7 @@ class IsolationManager {
     }
 
     console.log(`[IsolationManager] Image '${image}' not found, building automatically...`);
-    await this.buildImage(image);
+    await this.buildImage(image, 3, buildArgs);
   }
 
   /**

package/src/ledger.js

@@ -715,6 +715,9 @@ class Ledger extends EventEmitter {
    * Close the database connection
    */
   close() {
+    if (this._closed) {
+      return;
+    }
     this._closed = true; // Set flag BEFORE closing to prevent race conditions
     this.db.close();
   }

package/src/message-bus.js

@@ -24,12 +24,14 @@ class MessageBus extends EventEmitter {
     this.setMaxListeners(MAX_LISTENERS);
     this.ledger = ledger || new Ledger();
     this.wsClients = new Set();
+    this._closed = false;
 
     // Forward ledger events
-    this.ledger.on('message', (message) => {
+    this._forwardLedgerMessage = (message) => {
       this.emit('message', message);
       this._broadcastToWebSocket(message);
-    });
+    };
+    this.ledger.on('message', this._forwardLedgerMessage);
   }
 
   /**
@@ -241,6 +243,14 @@ class MessageBus extends EventEmitter {
    * Close the message bus
    */
   close() {
+    if (this._closed) {
+      return;
+    }
+    this._closed = true;
+
+    this.ledger.off('message', this._forwardLedgerMessage);
+    this.removeAllListeners();
+
     // Close all WebSocket connections
     for (const ws of this.wsClients) {
       try {

package/src/orchestrator.js

@@ -47,6 +47,7 @@ const configValidator = require('./config-validator');
 const TemplateResolver = require('./template-resolver');
 const { loadSettings } = require('../lib/settings');
 const { normalizeProviderName } = require('../lib/provider-names');
+const { resolveRunPlan } = require('../lib/run-plan');
 const { getProvider } = require('./providers');
 const StateSnapshotter = require('./state-snapshotter');
 const { resolveClusterRequiredQualityGates } = require('./quality-gates');
@@ -212,14 +213,11 @@ function applyPushBlockedRepairTriggers(config) {
   }
 }
 
-function resolveAutoMerge(options) {
-  return Boolean(options.ship) || Boolean(options.autoMerge);
-}
-
 function buildPrOptions(options, requiredQualityGates) {
   // autoMerge must always be persisted (even when no other PR fields are set) so that
   // `zeroshot run --pr` (autoMerge=false) vs `--ship` (autoMerge=true) survives resume.
-  const autoMerge = resolveAutoMerge(options);
+  // Derived from the canonical run plan — never recomputed from ship/pr here.
+  const autoMerge = resolveRunPlan(options).autoMerge;
 
   return {
     prBase: options.prBase || null,
@@ -577,6 +575,12 @@ class Orchestrator {
     // missing - a ledger write. Read-only orchestrators must never write, so they
     // skip it; they only need to read existing snapshots, not produce new ones.
     if (!this.readonly) {
+      this._registerClusterSubscriptions({
+        messageBus,
+        clusterId,
+        isolationManager,
+        containerId: isolation?.containerId || null,
+      });
       this._startSnapshotter(clusterContext);
     }
     this._log(`[Orchestrator] Loaded cluster: ${clusterId} with ${agents.length} agents`);
@@ -1134,11 +1138,12 @@ class Orchestrator {
     const messageBus = new MessageBus(ledger);
 
     // Handle isolation mode (Docker container OR git worktree)
-    const { isolationManager, containerId, worktreeInfo } = await this._initializeIsolation(
-      options,
-      config,
-      clusterId
-    );
+    const {
+      isolationManager,
+      containerId,
+      worktreeInfo,
+      image: resolvedIsolationImage,
+    } = await this._initializeIsolation(options, config, clusterId);
     let requiredQualityGates = resolveClusterRequiredQualityGates(config, options);
     let commandProofs = resolveClusterCommandProofs(config, options);
     options.requiredQualityGates = requiredQualityGates;
@@ -1184,7 +1189,9 @@ class Orchestrator {
         ? {
             enabled: true,
             containerId,
-            image: options.isolationImage || 'zeroshot-cluster-base',
+            // Provider-specific image variant (resolved in _initializeIsolation) so resume
+            // recreates the container on the same image that has the provider CLI installed.
+            image: resolvedIsolationImage || options.isolationImage || 'zeroshot-cluster-base',
             manager: isolationManager,
             workDir: options.cwd || process.cwd(), // Persisted for resume
           }
@@ -1725,20 +1732,30 @@ class Orchestrator {
     let isolationManager = null;
     let containerId = null;
     let worktreeInfo = null;
+    let isolationImage = null;
 
     if (options.isolation) {
       if (!IsolationManager.isDockerAvailable()) {
         throw new Error('Docker is not available. Install Docker to use --docker mode.');
       }
 
-      const image = options.isolationImage || 'zeroshot-cluster-base';
-      await IsolationManager.ensureImage(image);
+      // Resolve the provider first so the cluster runs on that provider's image variant, which
+      // installs the provider CLI as a Docker-cached layer. Providers baked into the base image
+      // (e.g. Claude) resolve back to the base image unchanged.
+      const providerName = this._resolveClusterProvider(config);
+      const baseImage = options.isolationImage || 'zeroshot-cluster-base';
+      const image = IsolationManager.imageForProvider(providerName, baseImage);
+      await IsolationManager.ensureImage(
+        image,
+        true,
+        IsolationManager.providerBuildArgs(providerName)
+      );
+      isolationImage = image;
 
       isolationManager = new IsolationManager({ image });
       this._log(`[Orchestrator] Starting cluster in isolation mode (image: ${image})`);
 
       const workDir = options.cwd || process.cwd();
-      const providerName = this._resolveClusterProvider(config);
       containerId = await isolationManager.createContainer(clusterId, {
         workDir,
         image,
@@ -1766,7 +1783,7 @@ class Orchestrator {
       this._log(`[Orchestrator] Branch: ${worktreeInfo.branch}`);
     }
 
-    return { isolationManager, containerId, worktreeInfo };
+    return { isolationManager, containerId, worktreeInfo, image: isolationImage };
   }
 
   _applyAutoPrConfig(config, inputData, options) {
@@ -1825,7 +1842,7 @@ class Orchestrator {
       mergeQueue: options.mergeQueue,
       closeIssue: options.closeIssue,
       requiredQualityGates: options.requiredQualityGates,
-      autoMerge: resolveAutoMerge(options),
+      autoMerge: resolveRunPlan(options).autoMerge,
       cwd: options.cwd,
     });
 
@@ -2316,6 +2333,9 @@ class Orchestrator {
    * Call before deleting storageDir to prevent ENOENT race conditions during cleanup
    */
   close() {
+    if (this.closed) {
+      return;
+    }
     this.closed = true;
   }
 
@@ -4103,7 +4123,7 @@ Continue from where you left off. Review your previous output to understand what
 
 // Exported for testing (PR options persistence, e.g. autoMerge for --pr vs --ship).
 Orchestrator.buildPrOptions = buildPrOptions;
-Orchestrator.resolveAutoMerge = resolveAutoMerge;
+Orchestrator.resolveRunPlan = resolveRunPlan;
 
 module.exports = Orchestrator;
 module.exports.DuplicateClusterError = DuplicateClusterError;

package/src/preflight.js

@@ -19,7 +19,12 @@ const {
   resolveClaudeAuth,
 } = require('../lib/settings/claude-auth.js');
 const { loadSettings, getClaudeCommand } = require('../lib/settings.js');
-const { normalizeProviderName } = require('../lib/provider-names');
+const {
+  VALID_PROVIDERS,
+  getProviderMetadata,
+  normalizeProviderName,
+  resolveProviderCommand,
+} = require('../lib/provider-names');
 const { detectGitContext } = require('../lib/git-remote-utils');
 const { readKeychainCredentials } = require('./claude-credentials');
 
@@ -343,10 +348,21 @@ function buildClaudeCommand(options) {
   return options.claudeCommand || [command, ...args].join(' ');
 }
 
+function buildRegistryInstallRecovery(metadata, command) {
+  return [
+    ...metadata.installInstructions.split('\n').filter(Boolean),
+    `Then run: ${command} --version`,
+  ];
+}
+
 function validateClaudeProvider(options) {
   const errors = [];
   const warnings = [];
+  const metadata = getProviderMetadata('claude');
   const claudeCommand = buildClaudeCommand(options);
+  const claudeCommandParts = claudeCommand.trim().split(/\s+/);
+  const usesDefaultClaudeCommand =
+    claudeCommandParts.length === 1 && claudeCommandParts[0] === metadata.binary;
 
   const claude = getClaudeVersion(claudeCommand);
   if (!claude.installed) {
@@ -354,12 +370,8 @@ function validateClaudeProvider(options) {
       formatError(
         'Claude command not available',
         claude.error,
-        claudeCommand === 'claude'
-          ? [
-              'Install Claude CLI: npm install -g @anthropic-ai/claude-code',
-              'Or: brew install claude (macOS)',
-              'Then run: claude --version',
-            ]
+        usesDefaultClaudeCommand
+          ? buildRegistryInstallRecovery(metadata, metadata.binary)
           : [
               `Command '${claudeCommand}' not found`,
               'Check settings: zeroshot settings',
@@ -404,41 +416,82 @@ function validateCliProvider(command, title, detail, recovery) {
   return { errors, warnings: [] };
 }
 
-function validateProvider(providerName, options) {
-  const validatorByProvider = {
-    claude: () => validateClaudeProvider(options),
-    codex: () =>
-      validateCliProvider('codex', 'Codex CLI not available', 'Command "codex" not installed', [
-        'Install Codex CLI: npm install -g @openai/codex',
-        'Then run: codex --version',
-      ]),
-    gemini: () =>
-      validateCliProvider('gemini', 'Gemini CLI not available', 'Command "gemini" not installed', [
-        'Install Gemini CLI: npm install -g @google/gemini-cli',
-        'Then run: gemini --version',
-      ]),
-    opencode: () =>
-      validateCliProvider(
-        'opencode',
-        'Opencode CLI not available',
-        'Command "opencode" not installed',
-        ['Install Opencode CLI: see https://opencode.ai', 'Then run: opencode --version']
+function validateGatewayProvider() {
+  const { getProvider } = require('./providers');
+  const provider = getProvider('gateway');
+  if (provider.isAvailable()) {
+    return { errors: [], warnings: [] };
+  }
+  return {
+    errors: [
+      formatError(
+        'Gateway provider not configured',
+        'providerSettings.gateway must define baseUrl, apiKey, model, and toolPolicy before gateway can run.',
+        [
+          'Run: zeroshot settings',
+          'Set providerSettings.gateway.baseUrl to your OpenAI-compatible endpoint base URL',
+          'Set providerSettings.gateway.apiKey and providerSettings.gateway.model',
+          'Set providerSettings.gateway.toolPolicy.roots and toolPolicy.commands explicitly',
+        ]
       ),
+    ],
+    warnings: [],
   };
+}
 
-  const validator = validatorByProvider[providerName];
-  if (!validator) {
+function validateProvider(providerName, options) {
+  let metadata;
+  try {
+    metadata = getProviderMetadata(providerName);
+  } catch {
     return {
       errors: [
         formatError('Unknown provider', `Provider "${providerName}" is not supported`, [
-          'Use claude, codex, gemini, or opencode',
+          `Use ${VALID_PROVIDERS.join(', ')}`,
         ]),
       ],
       warnings: [],
     };
   }
 
-  return validator();
+  if (metadata.command.kind === 'configured-claude') {
+    return validateClaudeProvider(options);
+  }
+  if (providerName === 'gateway') {
+    return validateGatewayProvider();
+  }
+
+  return validateRegistryCliProvider(providerName);
+}
+
+function validateRegistryCliProvider(providerName) {
+  const metadata = getProviderMetadata(providerName);
+  const { command } = resolveProviderCommand(providerName);
+  const installSteps = metadata.installInstructions.split('\n').filter(Boolean);
+  if (!commandExists(command)) {
+    return validateCliProvider(
+      command,
+      `${metadata.displayName} CLI not available`,
+      `Command "${command}" not installed`,
+      [...installSteps, `Then run: ${command} --version`]
+    );
+  }
+
+  const { getProvider } = require('./providers');
+  if (getProvider(providerName).isAvailable()) {
+    return { errors: [], warnings: [] };
+  }
+
+  return {
+    errors: [
+      formatError(
+        `${metadata.displayName} CLI not available`,
+        `Command "${command}" is installed but did not produce usable --help/--version output`,
+        [...installSteps, `Then run: ${command} --version`]
+      ),
+    ],
+    warnings: [],
+  };
 }
 
 function validateGhRequirement() {

package/src/providers/capabilities.js

@@ -1,48 +1,21 @@
-const { normalizeProviderName } = require('../../lib/provider-names');
+const {
+  PROVIDER_CAPABILITIES,
+  normalizeProviderName,
+  providerSupportsCapability,
+} = require('../../lib/provider-names');
 
-const CAPABILITIES = {
-  claude: {
-    dockerIsolation: true,
-    worktreeIsolation: true,
-    mcpServers: true,
-    jsonSchema: true,
-    streamJson: true,
-    thinkingMode: true,
-    reasoningEffort: false,
-  },
-  codex: {
-    dockerIsolation: true,
-    worktreeIsolation: true,
-    mcpServers: true,
-    jsonSchema: true,
-    streamJson: true,
-    thinkingMode: true,
-    reasoningEffort: true,
-  },
-  gemini: {
-    dockerIsolation: true,
-    worktreeIsolation: true,
-    mcpServers: true,
-    jsonSchema: 'experimental',
-    streamJson: true,
-    thinkingMode: true,
-    reasoningEffort: false,
-  },
-  opencode: {
-    dockerIsolation: true,
-    worktreeIsolation: true,
-    mcpServers: true,
-    jsonSchema: 'experimental',
-    streamJson: true,
-    thinkingMode: true,
-    reasoningEffort: true,
-  },
-};
+const CAPABILITIES = Object.freeze(
+  Object.fromEntries(
+    Object.entries(PROVIDER_CAPABILITIES).map(([provider, capabilities]) => [
+      provider,
+      Object.freeze({ ...capabilities }),
+    ])
+  )
+);
 
 function checkCapability(provider, capability) {
-  const caps = CAPABILITIES[normalizeProviderName(provider)];
-  if (!caps) return false;
-  return caps[capability] === true;
+  if (!provider) return false;
+  return providerSupportsCapability(provider, capability);
 }
 
 function warnIfExperimental(provider, capability) {