@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/lib/start-cluster.d.ts

@@ -0,0 +1,64 @@
+interface Settings extends Record<string, unknown> {
+}
+interface ClusterConfig extends Record<string, unknown> {
+}
+interface ClusterInput extends Record<string, string> {
+}
+interface OrchestratorFacade {
+    loadConfig(configPath: string): ClusterConfig;
+    start(config: ClusterConfig, input: ClusterInput, options: unknown): unknown;
+}
+interface ProviderOverrideOptions {
+    provider?: string | null;
+    envProvider?: string | null;
+    validateProvider?: unknown;
+}
+interface StartClusterArgs extends Record<string, unknown> {
+    orchestrator?: OrchestratorFacade;
+    config?: ClusterConfig | null;
+    configPath?: string | null;
+    configName?: string | null;
+    settings?: Settings;
+    providerOverride?: string | null;
+    modelOverride?: unknown;
+    forceProvider?: unknown;
+    clusterId?: unknown;
+    options?: Record<string, unknown>;
+    text: string;
+    issue: string;
+    file: string;
+}
+declare function buildTextInput(text: string): ClusterInput;
+declare function buildIssueInput(issue: string): ClusterInput;
+declare function buildFileInput(file: string): ClusterInput;
+declare function detectRunInput(inputArg: string, settings?: Settings, forceProvider?: string | null): ClusterInput;
+declare function isStdinInput(inputArg: string): boolean;
+declare function readStdinText(stream?: AsyncIterable<string | Uint8Array>): Promise<string>;
+declare function encodeStdinEnv(text: string): string;
+declare function decodeStdinEnv(value: string): string;
+declare function resolveProviderOverride(options?: ProviderOverrideOptions): string | null;
+declare function startClusterFromText(args: StartClusterArgs): unknown;
+declare function startClusterFromIssue(args: StartClusterArgs): unknown;
+declare function startClusterFromFile(args: StartClusterArgs): unknown;
+declare const _default: {
+    buildTextInput: typeof buildTextInput;
+    buildIssueInput: typeof buildIssueInput;
+    buildFileInput: typeof buildFileInput;
+    detectRunInput: typeof detectRunInput;
+    isStdinInput: typeof isStdinInput;
+    readStdinText: typeof readStdinText;
+    encodeStdinEnv: typeof encodeStdinEnv;
+    decodeStdinEnv: typeof decodeStdinEnv;
+    resolveProviderOverride: typeof resolveProviderOverride;
+    resolveConfigPath: (configName: string) => string;
+    prepareClusterConfig: (config: ClusterConfig, settings?: Settings, providerOverride?: string | null) => ClusterConfig;
+    loadClusterConfig: (orchestrator: OrchestratorFacade, configPath: string, settings?: Settings, providerOverride?: string | null) => ClusterConfig;
+    buildStartOptions: (args: Record<string, unknown>) => unknown;
+    buildTrustedStartOptions: (args: Record<string, unknown>) => unknown;
+    resolveEffectiveRunPlan: (options?: Record<string, unknown>, settings?: Settings) => unknown;
+    startClusterFromText: typeof startClusterFromText;
+    startClusterFromIssue: typeof startClusterFromIssue;
+    startClusterFromFile: typeof startClusterFromFile;
+    detectGitRepoRoot: () => string;
+};
+export = _default;

package/lib/start-cluster.js

@@ -1,485 +1,129 @@
-const path = require('path');
-const { spawnSync } = require('child_process');
-const chalk = require('chalk');
-const { normalizeProviderName, getDefaultProviderId } = require('./provider-names');
-const { getProvider } = require('../src/providers');
-const { detectProvider } = require('../src/issue-providers');
-const TemplateResolver = require('../src/template-resolver');
-const { runModeFromPlan } = require('./run-mode');
-const { resolveRunPlan } = require('./run-plan');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-
-function firstTruthy(...values) {
-  return values.find(Boolean);
-}
-function anyTruthy(...values) {
-  return values.some(Boolean);
-}
-function optionalValue(value) {
-  return value || undefined;
-}
-function resolveTargetCwd() {
-  return firstTruthy(process.env.ZEROSHOT_CWD, detectGitRepoRoot());
-}
-
-function detectGitRepoRoot() {
-  try {
-    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    if (result.status !== 0) {
-      return process.cwd();
-    }
-    return result.stdout.trim();
-  } catch {
-    return process.cwd();
-  }
-}
-
-function resolveOptionalString(value) {
-  if (typeof value !== 'string') return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function resolveEnvBool(value) {
-  if (typeof value !== 'string') return undefined;
-  const trimmed = value.trim().toLowerCase();
-  if (trimmed === '1' || trimmed === 'true' || trimmed === 'yes') return true;
-  if (trimmed === '0' || trimmed === 'false' || trimmed === 'no') return false;
-  return undefined;
-}
-
-function resolveCloseIssueMode(value) {
-  const trimmed = resolveOptionalString(value);
-  if (!trimmed) return undefined;
-  const normalized = trimmed.toLowerCase();
-  if (normalized === 'auto' || normalized === 'always' || normalized === 'never') {
-    return normalized;
-  }
-  return undefined;
-}
-
-function parseRunOptionsEnv() {
-  const raw = resolveOptionalString(process.env.ZEROSHOT_RUN_OPTIONS);
-  if (!raw) return null;
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object') {
-      return null;
-    }
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-function parseMountSpecs(specs) {
-  return specs.map((spec) => {
-    const parts = spec.split(':');
-    if (parts.length < 2) {
-      throw new Error(`Invalid mount spec: "${spec}". Format: host:container[:ro]`);
-    }
-    const host = parts[0];
-    const container = parts[1];
-    const readonly = parts[2] === 'ro';
-    return { host, container, readonly };
-  });
-}
-
+"use strict";
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const providerNames = require('./provider-names');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const providers = require('../src/providers');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const issueProviders = require('../src/issue-providers');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const configHelpers = require('./start-cluster-config');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const runOptionsHelpers = require('./start-cluster-run-options');
+const { normalizeProviderName } = providerNames;
+const { getProvider } = providers;
+const { detectProvider } = issueProviders;
+const { resolveConfigPath, prepareClusterConfig, loadClusterConfig } = configHelpers;
+const { buildStartOptions, buildTrustedStartOptions, resolveEffectiveRunPlan, detectGitRepoRoot } = runOptionsHelpers;
 function buildTextInput(text) {
-  return { text };
+    return { text };
 }
 function buildIssueInput(issue) {
-  return { issue };
+    return { issue };
 }
 function buildFileInput(file) {
-  return { file };
+    return { file };
 }
-
 function detectRunInput(inputArg, settings = {}, forceProvider = null) {
-  const isMarkdownFile = /\.(md|markdown)$/i.test(inputArg);
-  if (isMarkdownFile) {
-    return buildFileInput(inputArg);
-  }
-
-  const ProviderClass = detectProvider(inputArg, settings, forceProvider);
-  if (ProviderClass) {
-    return buildIssueInput(inputArg);
-  }
-
-  return buildTextInput(inputArg);
+    const isMarkdownFile = /\.(md|markdown)$/i.test(inputArg);
+    if (isMarkdownFile) {
+        return buildFileInput(inputArg);
+    }
+    const ProviderClass = detectProvider(inputArg, settings, forceProvider);
+    if (ProviderClass) {
+        return buildIssueInput(inputArg);
+    }
+    return buildTextInput(inputArg);
 }
-
 const STDIN_MARKER = '-';
-
 function isStdinInput(inputArg) {
-  return inputArg === STDIN_MARKER;
+    return inputArg === STDIN_MARKER;
 }
-
 async function readStdinText(stream = process.stdin) {
-  const chunks = [];
-  for await (const chunk of stream) {
-    chunks.push(chunk);
-  }
-  return Buffer.concat(chunks.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))))
-    .toString('utf8')
-    .trim();
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))))
+        .toString('utf8')
+        .trim();
 }
-
 function encodeStdinEnv(text) {
-  return Buffer.from(text, 'utf8').toString('base64');
+    return Buffer.from(text, 'utf8').toString('base64');
 }
-
 function decodeStdinEnv(value) {
-  return Buffer.from(value, 'base64').toString('utf8');
+    return Buffer.from(value, 'base64').toString('utf8');
 }
-
 function resolveProviderOverride(options = {}) {
-  const override = options.provider || options.envProvider || process.env.ZEROSHOT_PROVIDER;
-  if (!override || (typeof override === 'string' && !override.trim())) {
-    return null;
-  }
-  const normalized = normalizeProviderName(override);
-  if (options.validateProvider) {
-    getProvider(normalized);
-  }
-  return normalized;
-}
-
-function resolveConfigPath(configName) {
-  if (path.isAbsolute(configName) || configName.startsWith('./') || configName.startsWith('../')) {
-    return path.resolve(process.cwd(), configName);
-  }
-  if (configName.endsWith('.json')) {
-    return path.join(PACKAGE_ROOT, 'cluster-templates', configName);
-  }
-  return path.join(PACKAGE_ROOT, 'cluster-templates', `${configName}.json`);
-}
-
-function ensureConfigProviderDefaults(config, settings) {
-  if (!config.defaultProvider) {
-    config.defaultProvider = settings.defaultProvider || getDefaultProviderId();
-  }
-  config.defaultProvider = normalizeProviderName(config.defaultProvider) || getDefaultProviderId();
-}
-
-function applyProviderOverrideToConfig(config, providerOverride, settings) {
-  const provider = getProvider(providerOverride);
-  const providerSettings = settings.providerSettings?.[providerOverride] || {};
-  config.forceProvider = providerOverride;
-  config.defaultProvider = providerOverride;
-  config.forceLevel = providerSettings.defaultLevel || provider.getDefaultLevel();
-  config.defaultLevel = config.forceLevel;
-  console.log(chalk.dim(`Provider override: ${providerOverride} (all agents)`));
-}
-
-function resolveParameterizedConfigFile(config) {
-  if (!config?.params || Object.keys(config.params).length === 0) {
-    return config;
-  }
-
-  const resolver = new TemplateResolver(path.join(PACKAGE_ROOT, 'cluster-templates'));
-  return resolver.resolveTemplate(config, {});
-}
-
-function prepareClusterConfig(config, settings = {}, providerOverride) {
-  const prepared = resolveParameterizedConfigFile(config);
-  ensureConfigProviderDefaults(prepared, settings);
-  if (providerOverride) {
-    applyProviderOverrideToConfig(prepared, providerOverride, settings);
-  }
-  return prepared;
-}
-
-function loadClusterConfig(orchestrator, configPath, settings = {}, providerOverride) {
-  return prepareClusterConfig(orchestrator.loadConfig(configPath), settings, providerOverride);
-}
-
-const RUN_MODE_KEYS = ['docker', 'worktree', 'pr', 'ship', 'noIsolation', 'isolation'];
-
-function hasExplicitRunMode(options) {
-  return RUN_MODE_KEYS.some(
-    (key) => options[key] === true || (key === 'isolation' && options[key] === false)
-  );
-}
-
-function mergeRunOptions(options) {
-  const envRunOptions = parseRunOptionsEnv();
-  if (!envRunOptions) return options;
-  if (!hasExplicitRunMode(options)) return { ...envRunOptions, ...options };
-  const withoutEnvMode = { ...envRunOptions };
-  for (const key of RUN_MODE_KEYS) delete withoutEnvMode[key];
-  return { ...withoutEnvMode, ...options };
-}
-
-function validateSavedRunModes(settings) {
-  const isolation = settings.defaultIsolation || 'none';
-  const delivery = settings.defaultDelivery || 'none';
-  if (!['none', 'worktree', 'docker'].includes(isolation)) {
-    throw new Error(`Invalid saved isolation mode: ${isolation}`);
-  }
-  if (!['none', 'pr', 'ship'].includes(delivery)) {
-    throw new Error(`Invalid saved delivery mode: ${delivery}`);
-  }
-  return { isolation, delivery };
-}
-
-function resolveEffectiveIsolation(options, savedIsolation) {
-  if (options.noIsolation === true || options.isolation === false) return 'none';
-  if (options.docker === true) return 'docker';
-  if (options.worktree === true || options.pr === true || options.ship === true) return 'worktree';
-  if (resolveEnvBool(process.env.ZEROSHOT_DOCKER) === true) return 'docker';
-  if (resolveEnvBool(process.env.ZEROSHOT_WORKTREE) === true) return 'worktree';
-  return savedIsolation;
-}
-
-function resolveEffectiveDelivery(options, savedDelivery) {
-  if (options.ship === true || options.autoMerge === true) return 'ship';
-  if (options.pr === true || resolveEnvBool(process.env.ZEROSHOT_PR) === true) return 'pr';
-  return savedDelivery;
-}
-
-function resolveEffectiveRunPlan(options = {}, settings = {}) {
-  const mergedOptions = mergeRunOptions(options);
-  const noIsolation = mergedOptions.noIsolation === true || mergedOptions.isolation === false;
-  const conflicts = ['docker', 'worktree', 'pr', 'ship'].filter(
-    (key) => mergedOptions[key] === true
-  );
-  if (noIsolation && conflicts.length > 0) {
-    throw new Error(`--no-isolation conflicts with --${conflicts.join(', --')}`);
-  }
-
-  const saved = validateSavedRunModes(settings);
-  let isolation = resolveEffectiveIsolation(mergedOptions, saved.isolation);
-  const delivery = resolveEffectiveDelivery(mergedOptions, saved.delivery);
-  if (delivery !== 'none' && isolation === 'none') {
-    if (noIsolation) {
-      throw new Error(`--no-isolation conflicts with saved delivery mode "${delivery}"`);
+    const override = options.provider || options.envProvider || process.env.ZEROSHOT_PROVIDER;
+    if (!override || !override.trim()) {
+        return null;
     }
-    isolation = 'worktree';
-  }
-  return resolveRunPlan({
-    docker: isolation === 'docker',
-    worktree: isolation === 'worktree',
-    pr: delivery === 'pr',
-    ship: delivery === 'ship',
-  });
-}
-
-function resolveMergeQueue(mergedOptions) {
-  if (typeof mergedOptions.mergeQueue === 'boolean') {
-    return mergedOptions.mergeQueue;
-  }
-  return resolveEnvBool(process.env.ZEROSHOT_MERGE_QUEUE);
-}
-
-function resolvePrBase(mergedOptions) {
-  return (
-    resolveOptionalString(mergedOptions.prBase) ||
-    resolveOptionalString(process.env.ZEROSHOT_PR_BASE) ||
-    undefined
-  );
-}
-
-function resolveCloseIssue(mergedOptions) {
-  return (
-    resolveCloseIssueMode(mergedOptions.closeIssue) ||
-    resolveCloseIssueMode(process.env.ZEROSHOT_CLOSE_ISSUE) ||
-    undefined
-  );
-}
-
-function resolveMounts(mergedOptions) {
-  return mergedOptions.mount ? parseMountSpecs(mergedOptions.mount) : undefined;
-}
-
-function buildStartOptions({
-  clusterId,
-  options = {},
-  settings = {},
-  providerOverride,
-  modelOverride,
-  forceProvider,
-}) {
-  const mergedOptions = mergeRunOptions(options);
-  const plan = resolveEffectiveRunPlan(options, settings);
-  return buildStartOptionsFromPlan({
-    clusterId,
-    plan,
-    options: mergedOptions,
-    settings,
-    providerOverride,
-    modelOverride,
-    forceProvider,
-    environment: true,
-  });
-}
-
-function buildStartOptionsFromPlan({
-  clusterId,
-  plan,
-  options,
-  settings,
-  providerOverride,
-  modelOverride,
-  forceProvider,
-  preparedWorktree,
-  environment,
-}) {
-  const targetCwd = environment ? resolveTargetCwd() : options.cwd;
-  return Object.freeze({
-    clusterId,
-    cwd: targetCwd,
-    isolation: plan.isolation === 'docker',
-    isolationImage: environment
-      ? firstTruthy(options.dockerImage, process.env.ZEROSHOT_DOCKER_IMAGE)
-      : optionalValue(options.dockerImage),
-    worktree: plan.isolation === 'worktree',
-    preparedWorktree: preparedWorktree || undefined,
-    autoPr: plan.delivery !== 'none',
-    autoMerge: plan.autoMerge,
-    autoPush: environment ? process.env.ZEROSHOT_PUSH === '1' : options.autoPush === true,
-    modelOverride: optionalValue(modelOverride),
-    providerOverride: optionalValue(providerOverride),
-    noMounts: anyTruthy(options.mounts === false, options.noMounts === true),
-    mounts: resolveMounts(options),
-    containerHome: optionalValue(options.containerHome),
-    forceProvider: optionalValue(forceProvider),
-    prBase: environment ? resolvePrBase(options) : optionalValue(options.prBase),
-    mergeQueue: environment ? resolveMergeQueue(options) : optionalValue(options.mergeQueue),
-    closeIssue: environment ? resolveCloseIssue(options) : optionalValue(options.closeIssue),
-    ship: plan.delivery === 'ship',
-    runMode: runModeFromPlan(plan),
-    requiredQualityGates: options.requiredQualityGates,
-    settings,
-  });
-}
-
-/**
- * Build start options from a registry-owned canonical plan. Unlike the CLI
- * builder, this function never reads ZEROSHOT_RUN_OPTIONS or mode-related
- * environment variables. The caller must resolve and validate the deployment
- * profile before invoking it.
- */
-function buildTrustedStartOptions({
-  clusterId,
-  plan,
-  options = {},
-  settings = {},
-  providerOverride,
-  modelOverride,
-  forceProvider,
-}) {
-  if (!plan || !Object.isFrozen(plan)) {
-    throw new Error('Trusted start requires a frozen canonical run plan');
-  }
-  const canonical = resolveRunPlan({
-    docker: plan.isolation === 'docker',
-    worktree: plan.isolation === 'worktree',
-    pr: plan.delivery === 'pr',
-    ship: plan.delivery === 'ship',
-  });
-  if (
-    canonical.isolation !== plan.isolation ||
-    canonical.delivery !== plan.delivery ||
-    canonical.autoMerge !== plan.autoMerge
-  ) {
-    throw new Error('Trusted start plan is not canonical');
-  }
-  if (canonical.isolation === 'none') {
-    throw new Error('Trusted worker start requires worktree or docker isolation');
-  }
-  if (options.preparedWorktree && canonical.isolation !== 'worktree') {
-    throw new Error('Prepared worktree requires canonical worktree isolation');
-  }
-  return buildStartOptionsFromPlan({
-    clusterId,
-    plan: canonical,
-    options,
-    settings,
-    providerOverride,
-    modelOverride,
-    forceProvider,
-    preparedWorktree: options.preparedWorktree,
-    environment: false,
-  });
+    const normalized = normalizeProviderName(override);
+    if (options.validateProvider) {
+        getProvider(normalized);
+    }
+    return normalized;
 }
-
-function resolveConfigOrThrow({
-  orchestrator,
-  config,
-  configPath,
-  configName,
-  settings,
-  providerOverride,
-}) {
-  if (config) {
-    return config;
-  }
-  const resolvedPath = configPath || (configName ? resolveConfigPath(configName) : null);
-  if (!resolvedPath) {
-    throw new Error('configPath or configName is required when config is not provided');
-  }
-  return loadClusterConfig(orchestrator, resolvedPath, settings, providerOverride);
+function resolveConfigOrThrow({ orchestrator, config, configPath, configName, settings, providerOverride, }) {
+    if (config) {
+        return config;
+    }
+    const resolvedPath = configPath || (configName ? resolveConfigPath(configName) : null);
+    if (!resolvedPath) {
+        throw new Error('configPath or configName is required when config is not provided');
+    }
+    return loadClusterConfig(orchestrator, resolvedPath, settings, providerOverride);
 }
-
 function startClusterWithInput(args, input) {
-  const { orchestrator, config, configPath, configName, settings, providerOverride } = args;
-  if (!orchestrator) {
-    throw new Error('orchestrator is required');
-  }
-  const resolvedConfig = resolveConfigOrThrow({
-    orchestrator,
-    config,
-    configPath,
-    configName,
-    settings,
-    providerOverride,
-  });
-  const startOptions = buildStartOptions({
-    clusterId: args.clusterId,
-    options: args.options || {},
-    settings,
-    providerOverride,
-    modelOverride: args.modelOverride,
-    forceProvider: args.forceProvider,
-  });
-  return orchestrator.start(resolvedConfig, input, startOptions);
+    const { orchestrator, config, configPath, configName, settings, providerOverride } = args;
+    if (!orchestrator) {
+        throw new Error('orchestrator is required');
+    }
+    const resolvedConfig = resolveConfigOrThrow({
+        orchestrator,
+        config,
+        configPath,
+        configName,
+        settings,
+        providerOverride,
+    });
+    const startOptions = buildStartOptions({
+        clusterId: args.clusterId,
+        options: args.options || {},
+        settings,
+        providerOverride,
+        modelOverride: args.modelOverride,
+        forceProvider: args.forceProvider,
+    });
+    return orchestrator.start(resolvedConfig, input, startOptions);
 }
-
 function startClusterFromText(args) {
-  return startClusterWithInput(args, buildTextInput(args.text));
+    return startClusterWithInput(args, buildTextInput(args.text));
 }
-
 function startClusterFromIssue(args) {
-  return startClusterWithInput(args, buildIssueInput(args.issue));
+    return startClusterWithInput(args, buildIssueInput(args.issue));
 }
-
 function startClusterFromFile(args) {
-  return startClusterWithInput(args, buildFileInput(args.file));
+    return startClusterWithInput(args, buildFileInput(args.file));
 }
-
 module.exports = {
-  buildTextInput,
-  buildIssueInput,
-  buildFileInput,
-  detectRunInput,
-  isStdinInput,
-  readStdinText,
-  encodeStdinEnv,
-  decodeStdinEnv,
-  resolveProviderOverride,
-  resolveConfigPath,
-  prepareClusterConfig,
-  loadClusterConfig,
-  buildStartOptions,
-  buildTrustedStartOptions,
-  resolveEffectiveRunPlan,
-  startClusterFromText,
-  startClusterFromIssue,
-  startClusterFromFile,
-  detectGitRepoRoot,
+    buildTextInput,
+    buildIssueInput,
+    buildFileInput,
+    detectRunInput,
+    isStdinInput,
+    readStdinText,
+    encodeStdinEnv,
+    decodeStdinEnv,
+    resolveProviderOverride,
+    resolveConfigPath,
+    prepareClusterConfig,
+    loadClusterConfig,
+    buildStartOptions,
+    buildTrustedStartOptions,
+    resolveEffectiveRunPlan,
+    startClusterFromText,
+    startClusterFromIssue,
+    startClusterFromFile,
+    detectGitRepoRoot,
 };

package/lib/stream-json-parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Provider-agnostic stream-json parser for `zeroshot logs`.
+ *
+ * Provider parsing is delegated to the helper-backed runtime provider facade.
+ */
+type ParsedEvent = Readonly<Record<string, unknown>>;
+type ProviderEvent = ParsedEvent | ParsedEvent[] | null;
+interface ProviderParser {
+    parseEvent(line: string): ProviderEvent;
+}
+declare function parseEvent(line: unknown, providerParsers?: readonly ProviderParser[]): ProviderEvent;
+declare function parseChunk(chunk: unknown): ParsedEvent[];
+declare const _default: {
+    parseEvent: typeof parseEvent;
+    parseChunk: typeof parseChunk;
+};
+export = _default;