@the-open-engine/zeroshot 5.4.0

package/src/providers/base-provider.js

@@ -0,0 +1,355 @@
+/**
+ * BaseProvider - Abstract provider interface
+ *
+ * All providers support two execution paths:
+ * 1. SDK (fast) - Direct API calls using provider's SDK (requires API key)
+ * 2. CLI (slower) - Spawns provider's CLI tool (uses OAuth/login auth)
+ *
+ * Use callSimple() for simple prompts - it tries SDK first, falls back to CLI.
+ */
+class BaseProvider {
+  constructor(options = {}) {
+    this.name = options.name || 'base';
+    this.displayName = options.displayName || 'Base';
+    this.cliCommand = options.cliCommand || null;
+  }
+
+  // ============================================================================
+  // ERROR CLASSIFICATION (Retry vs Permanent)
+  // ============================================================================
+  //
+  // Providers currently execute via CLI, so errors are often unstructured strings.
+  // These helpers are used by the agent retry loop to decide whether to retry.
+  //
+
+  /**
+   * Patterns that indicate the error is retryable/transient.
+   * Override in provider implementations to add provider-specific patterns.
+   * @returns {Array<RegExp>} Retryable error patterns
+   */
+  getRetryableErrorPatterns() {
+    return [
+      /rate.?limit/i,
+      /\b429\b/i,
+      /too many requests/i,
+      /overloaded/i,
+      /temporar(?:y|ily)/i,
+      /unavailable/i,
+      /try again/i,
+      /timeout/i,
+      /timed out/i,
+      /deadline exceeded/i,
+      /connection (?:reset|refused)/i,
+      /\b(econnreset|econnrefused|etimedout|eai_again)\b/i,
+      /network/i,
+    ];
+  }
+
+  /**
+   * Patterns that indicate the error is permanent and should not be retried.
+   * Override in provider implementations to add provider-specific patterns.
+   * @returns {Array<RegExp>} Permanent error patterns
+   */
+  getPermanentErrorPatterns() {
+    return [
+      /invalid[_ -]?api[_ -]?key/i,
+      /api[_ -]?key.*invalid/i,
+      /unauthorized/i,
+      /forbidden/i,
+      /authentication/i,
+      /permission denied/i,
+      /invalid argument/i,
+      /unknown option/i,
+      /\busage:\b/i,
+      /command not found/i,
+      /not recognized as an internal or external command/i,
+      /model not found/i,
+      /context length exceeded/i,
+      /insufficient quota/i,
+    ];
+  }
+
+  /**
+   * Classify whether an error is retryable.
+   * Default behavior is conservative: unknown errors are treated as retryable
+   * to prevent stuck clusters from single transient failures.
+   * @param {any} err - Error object (often Error with message)
+   * @returns {boolean} True if retryable
+   */
+  isRetryableError(err) {
+    const status =
+      err?.status ?? err?.statusCode ?? err?.response?.status ?? err?.response?.statusCode ?? null;
+
+    if (typeof status === 'number') {
+      if (status === 429 || status >= 500) return true;
+      if (status >= 400 && status < 500) return false;
+    }
+
+    const code = err?.code || null;
+    if (
+      typeof code === 'string' &&
+      /\b(econnreset|econnrefused|etimedout|eai_again)\b/i.test(code)
+    ) {
+      return true;
+    }
+
+    const message = (err?.message || String(err) || '').trim();
+    if (!message) {
+      return true;
+    }
+
+    const permanent = this.getPermanentErrorPatterns();
+    if (Array.isArray(permanent) && permanent.some((p) => p.test(message))) {
+      return false;
+    }
+
+    const retryable = this.getRetryableErrorPatterns();
+    if (Array.isArray(retryable) && retryable.some((p) => p.test(message))) {
+      return true;
+    }
+
+    return true;
+  }
+
+  // ============================================================================
+  // SDK SUPPORT (Future Extension Point)
+  // ============================================================================
+  //
+  // SDK support is NOT IMPLEMENTED. These methods exist for future extension.
+  // Currently, all providers use CLI (claude, codex, gemini) for execution.
+  //
+  // To add SDK support for a provider:
+  // 1. Override getSDKEnvVar() to return the API key env var
+  // 2. Override callSDK() to implement the actual API call
+  // 3. The callSimple() method will then work automatically
+  //
+  // ============================================================================
+
+  /**
+   * Get the environment variable name for the API key
+   * @returns {string} Environment variable name (e.g., 'ANTHROPIC_API_KEY')
+   */
+  getSDKEnvVar() {
+    throw new Error(`${this.name}: SDK not implemented. Use CLI instead.`);
+  }
+
+  /**
+   * Check if SDK is configured (API key is set)
+   * @returns {boolean} True if API key is available
+   */
+  isSDKConfigured() {
+    try {
+      const envVar = this.getSDKEnvVar();
+      return !!process.env[envVar];
+    } catch {
+      // getSDKEnvVar() throws if not implemented
+      return false;
+    }
+  }
+
+  /**
+   * Make a simple API call via SDK (fast path)
+   * NOT IMPLEMENTED - exists for future extension.
+   *
+   * @param {string} _prompt - The prompt to send
+   * @param {Object} _options - Call options
+   * @returns {Promise<{success: boolean, text: string, usage?: Object, error?: string}>}
+   */
+  callSDK(_prompt, _options) {
+    return Promise.reject(new Error(`${this.name}: SDK not implemented. Use CLI instead.`));
+  }
+
+  /**
+   * Make a simple API call via SDK
+   * NOT IMPLEMENTED - exists for future extension.
+   *
+   * @param {string} _prompt - The prompt to send
+   * @param {Object} _options - Call options
+   * @returns {Promise<{success: boolean, text: string, usage?: Object, error?: string}>}
+   */
+  callSimple(_prompt, _options = {}) {
+    return Promise.reject(new Error(`${this.name}: SDK not implemented. Use CLI instead.`));
+  }
+
+  isAvailable() {
+    throw new Error('Not implemented');
+  }
+
+  getCliPath() {
+    throw new Error('Not implemented');
+  }
+
+  getInstallInstructions() {
+    throw new Error('Not implemented');
+  }
+
+  getAuthInstructions() {
+    throw new Error('Not implemented');
+  }
+
+  getCliFeatures() {
+    throw new Error('Not implemented');
+  }
+
+  getCredentialPaths() {
+    return [];
+  }
+
+  buildCommand(_context, _options) {
+    throw new Error('Not implemented');
+  }
+
+  parseEvent(_line) {
+    throw new Error('Not implemented');
+  }
+
+  getModelCatalog() {
+    throw new Error('Not implemented');
+  }
+
+  getLevelMapping() {
+    throw new Error('Not implemented');
+  }
+
+  resolveModelSpec(level, overrides = {}) {
+    const mapping = this.getLevelMapping();
+    const base = mapping[level] || mapping[this.getDefaultLevel()];
+    if (!base) {
+      throw new Error(`Unknown level "${level}" for provider "${this.name}"`);
+    }
+    const override = overrides[level] || {};
+    const resolvedModel = this.validateModelId(override.model || base.model);
+    return {
+      level,
+      model: resolvedModel,
+      reasoningEffort: override.reasoningEffort || base.reasoningEffort,
+    };
+  }
+
+  validateLevel(level, minLevel, maxLevel) {
+    const mapping = this.getLevelMapping();
+    const rank = (key) => mapping[key]?.rank;
+
+    if (!mapping[level]) {
+      throw new Error(`Invalid level "${level}" for provider "${this.name}"`);
+    }
+
+    if (minLevel && !mapping[minLevel]) {
+      throw new Error(`Invalid minLevel "${minLevel}" for provider "${this.name}"`);
+    }
+
+    if (maxLevel && !mapping[maxLevel]) {
+      throw new Error(`Invalid maxLevel "${maxLevel}" for provider "${this.name}"`);
+    }
+
+    if (minLevel && maxLevel && rank(minLevel) > rank(maxLevel)) {
+      throw new Error(
+        `minLevel "${minLevel}" exceeds maxLevel "${maxLevel}" for provider "${this.name}"`
+      );
+    }
+
+    if (maxLevel && rank(level) > rank(maxLevel)) {
+      throw new Error(
+        `Level "${level}" exceeds maxLevel "${maxLevel}" for provider "${this.name}"`
+      );
+    }
+
+    if (minLevel && rank(level) < rank(minLevel)) {
+      throw new Error(
+        `Level "${level}" is below minLevel "${minLevel}" for provider "${this.name}"`
+      );
+    }
+
+    return level;
+  }
+
+  validateModelId(modelId) {
+    const catalog = this.getModelCatalog();
+    if (modelId && !catalog[modelId]) {
+      const err = new Error(
+        `Invalid model "${modelId}" for provider "${this.name}". ` +
+          `Use a model listed in provider settings/catalog.`
+      );
+      // Permanent misconfiguration/user input error - retries cannot fix this.
+      err.permanent = true;
+      throw err;
+    }
+    return modelId;
+  }
+
+  /**
+   * Resolve a model name to its CLI-compatible identifier.
+   * Override in provider implementations that need model ID transformation
+   * (e.g., Anthropic Bedrock mapping).
+   * @param {string} model - Provider model identifier
+   * @param {Object} _authEnv - Authentication environment variables
+   * @returns {string} CLI-compatible model identifier
+   */
+  resolveCliModel(model, _authEnv = {}) {
+    return model;
+  }
+
+  getDefaultLevel() {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Get default settings for this provider
+   * Override in provider implementations to provide provider-specific defaults
+   * @returns {Object} Default settings object
+   */
+  getDefaultSettings() {
+    return {
+      maxLevel: this.getDefaultMaxLevel?.() || 'level3',
+      minLevel: this.getDefaultMinLevel?.() || 'level1',
+      defaultLevel: this.getDefaultLevel() || 'level2',
+      levelOverrides: {},
+    };
+  }
+
+  /**
+   * Validate provider-specific settings
+   * Override in provider implementations to add custom validation
+   * @param {Object} settings - Settings object to validate
+   * @returns {string|null} Error message if invalid, null if valid
+   */
+  validateSettings(settings) {
+    if (typeof settings !== 'object' || settings === null) {
+      return `providerSettings.${this.name} must be an object`;
+    }
+
+    // Validate level fields
+    const levelMapping = this.getLevelMapping();
+    const validLevels = Object.keys(levelMapping);
+
+    if (settings.maxLevel && !validLevels.includes(settings.maxLevel)) {
+      return `Invalid maxLevel for ${this.name}: ${settings.maxLevel}`;
+    }
+    if (settings.minLevel && !validLevels.includes(settings.minLevel)) {
+      return `Invalid minLevel for ${this.name}: ${settings.minLevel}`;
+    }
+    if (settings.defaultLevel && !validLevels.includes(settings.defaultLevel)) {
+      return `Invalid defaultLevel for ${this.name}: ${settings.defaultLevel}`;
+    }
+
+    if (
+      settings.levelOverrides &&
+      (typeof settings.levelOverrides !== 'object' || Array.isArray(settings.levelOverrides))
+    ) {
+      return `levelOverrides for ${this.name} must be an object`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get the list of setting field names specific to this provider
+   * Override in provider implementations to declare custom fields
+   * @returns {string[]} Array of field names
+   */
+  getSettingsFields() {
+    return ['maxLevel', 'minLevel', 'defaultLevel', 'levelOverrides'];
+  }
+}
+
+module.exports = BaseProvider;

package/src/providers/capabilities.js

@@ -0,0 +1,60 @@
+const { normalizeProviderName } = 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,
+  },
+};
+
+function checkCapability(provider, capability) {
+  const caps = CAPABILITIES[normalizeProviderName(provider)];
+  if (!caps) return false;
+  return caps[capability] === true;
+}
+
+function warnIfExperimental(provider, capability) {
+  const normalized = normalizeProviderName(provider);
+  const caps = CAPABILITIES[normalized];
+  if (caps?.[capability] === 'experimental') {
+    console.warn(`⚠️ ${capability} is experimental for ${normalized} and may not work reliably`);
+  }
+}
+
+module.exports = {
+  CAPABILITIES,
+  checkCapability,
+  warnIfExperimental,
+};

package/src/providers/google/index.js

@@ -0,0 +1,3 @@
+const { createProviderClass } = require('..');
+
+module.exports = createProviderClass('gemini');

package/src/providers/index.js

@@ -0,0 +1,293 @@
+const BaseProvider = require('./base-provider');
+const { getClaudeCommand } = require('../../lib/settings');
+const { normalizeProviderName } = require('../../lib/provider-names');
+const { commandExists, getCommandPath } = require('../../lib/provider-detection');
+const helper = require('../../lib/agent-cli-provider');
+
+const PROVIDER_METADATA = {
+  claude: {
+    displayName: 'Claude',
+    cliCommand: 'claude',
+    helpArgs: () => getClaudeCommand().args,
+    commandParts: () => getClaudeCommand(),
+    installInstructions:
+      'npm install -g @anthropic-ai/claude-code\nOr (macOS): brew install claude',
+    authInstructions: 'claude login',
+    credentialPaths: ['~/.claude'],
+    settingsFields: ['anthropicApiKey', 'bedrockApiKey', 'bedrockRegion'],
+  },
+  codex: {
+    displayName: 'Codex',
+    cliCommand: 'codex',
+    helpArgs: () => ['exec'],
+    commandParts: () => ({ command: 'codex', args: [] }),
+    installInstructions: 'npm install -g @openai/codex',
+    authInstructions: 'codex login',
+    credentialPaths: ['~/.config/codex', '~/.codex'],
+    settingsFields: [],
+  },
+  gemini: {
+    displayName: 'Gemini',
+    cliCommand: 'gemini',
+    helpArgs: () => [],
+    commandParts: () => ({ command: 'gemini', args: [] }),
+    installInstructions: 'npm install -g @google/gemini-cli',
+    authInstructions: 'gemini auth login',
+    credentialPaths: ['~/.config/gcloud', '~/.config/gemini', '~/.gemini'],
+    settingsFields: [],
+  },
+  opencode: {
+    displayName: 'Opencode',
+    cliCommand: 'opencode',
+    helpArgs: () => ['run'],
+    commandParts: () => ({ command: 'opencode', args: [] }),
+    installInstructions: 'See https://opencode.ai for installation instructions.',
+    authInstructions: 'opencode auth login',
+    credentialPaths: ['~/.local/share/opencode'],
+    settingsFields: [],
+  },
+};
+
+const warned = new Set();
+
+function metadataForProvider(name) {
+  const metadata = PROVIDER_METADATA[name];
+  if (!metadata) {
+    throw new Error(`Unknown provider: ${name}. Valid: ${listProviders().join(', ')}`);
+  }
+  return metadata;
+}
+
+class RuntimeProvider extends BaseProvider {
+  constructor(name) {
+    const normalized = normalizeProviderName(name);
+    const metadata = metadataForProvider(normalized);
+    super({
+      name: normalized,
+      displayName: metadata.displayName,
+      cliCommand: metadata.cliCommand,
+    });
+    this._metadata = metadata;
+    this._adapter = helper.getProviderAdapter(normalized);
+    this._cliFeatures = null;
+    this._parserState = this._adapter.createParserState();
+  }
+
+  get adapter() {
+    return this._adapter;
+  }
+
+  isAvailable() {
+    const { command } = this._metadata.commandParts();
+    return commandExists(command);
+  }
+
+  getCliPath() {
+    const { command } = this._metadata.commandParts();
+    return getCommandPath(command) || command;
+  }
+
+  getInstallInstructions() {
+    return this._metadata.installInstructions;
+  }
+
+  getAuthInstructions() {
+    return this._metadata.authInstructions;
+  }
+
+  getCliFeatures() {
+    if (this._cliFeatures) return this._cliFeatures;
+    this._cliFeatures = helper.detectRuntimeProviderCliFeatures(this.name);
+    return this._cliFeatures;
+  }
+
+  getCredentialPaths() {
+    return this._metadata.credentialPaths;
+  }
+
+  buildCommand(context, options = {}) {
+    const prepared = helper.prepareSingleAgentProviderCommand({
+      provider: this.name,
+      context,
+      options,
+    });
+    this._cliFeatures = prepared.cliFeatures;
+    const commandSpec = prepared.commandSpec;
+    this._warnCommandSpec(commandSpec);
+    return commandSpec;
+  }
+
+  _warnCommandSpec(commandSpec) {
+    for (const warning of commandSpec.warnings || []) {
+      const key = `${warning.provider}:${warning.code}`;
+      if (warned.has(key)) continue;
+      warned.add(key);
+      console.warn(`⚠️ ${warning.message}`);
+    }
+  }
+
+  parseEvent(line) {
+    const event = this._adapter.parseEvent(line, this._parserState);
+    return event || null;
+  }
+
+  parseChunk(chunk) {
+    return parseChunkWithProvider(this, chunk);
+  }
+
+  getModelCatalog() {
+    return this._adapter.modelCatalog;
+  }
+
+  getLevelMapping() {
+    return this._adapter.levelMapping;
+  }
+
+  getDefaultLevel() {
+    return this._adapter.defaultLevel;
+  }
+
+  getDefaultMaxLevel() {
+    return this._adapter.defaultMaxLevel;
+  }
+
+  getDefaultMinLevel() {
+    return this._adapter.defaultMinLevel;
+  }
+
+  resolveModelSpec(level, overrides = {}) {
+    return helper.resolveModelSpec(this.name, level, overrides);
+  }
+
+  validateModelId(modelId) {
+    return this._adapter.validateModelId(modelId);
+  }
+
+  isRetryableError(err) {
+    return helper.classifyProviderError(this.name, err).retryable;
+  }
+
+  getDefaultSettings() {
+    const settings = super.getDefaultSettings();
+    if (this.name !== 'claude') return settings;
+    return {
+      ...settings,
+      anthropicApiKey: null,
+      bedrockApiKey: null,
+      bedrockRegion: null,
+    };
+  }
+
+  validateSettings(settings) {
+    const baseError = super.validateSettings(settings);
+    if (baseError) return baseError;
+    if (this.name !== 'claude') return null;
+
+    const { isValidAnthropicKey, ANTHROPIC_KEY_PREFIX } = require('../../lib/settings/claude-auth');
+    for (const field of this._metadata.settingsFields) {
+      if (
+        settings[field] !== undefined &&
+        settings[field] !== null &&
+        typeof settings[field] !== 'string'
+      ) {
+        return `providerSettings.claude.${field} must be a string or null`;
+      }
+    }
+    if (settings.anthropicApiKey && !isValidAnthropicKey(settings.anthropicApiKey)) {
+      return `providerSettings.claude.anthropicApiKey must start with ${ANTHROPIC_KEY_PREFIX}`;
+    }
+    return null;
+  }
+
+  getSettingsFields() {
+    return [...super.getSettingsFields(), ...this._metadata.settingsFields];
+  }
+}
+
+function getProvider(name) {
+  const normalized = normalizeProviderName(name || '');
+  if (!PROVIDER_METADATA[normalized]) {
+    throw new Error(`Unknown provider: ${name}. Valid: ${listProviders().join(', ')}`);
+  }
+  return new RuntimeProvider(normalized);
+}
+
+async function detectProviders() {
+  const results = {};
+  for (const name of listProviders()) {
+    const provider = getProvider(name);
+    results[name] = {
+      available: await provider.isAvailable(),
+    };
+  }
+  return results;
+}
+
+function listProviders() {
+  return helper.listProviderAdapters();
+}
+
+function stripTimestampPrefix(line) {
+  if (!line || typeof line !== 'string') return '';
+  let trimmed = line.trim().replace(/\r$/, '');
+  if (!trimmed) return '';
+
+  const tsMatch = trimmed.match(/^\[(\d{13})\](.*)$/);
+  if (tsMatch) trimmed = (tsMatch[2] || '').trimStart();
+
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    const pipeMatch = trimmed.match(/^[^|]{1,40}\|\s*(.*)$/);
+    if (pipeMatch) {
+      const afterPipe = (pipeMatch[1] || '').trimStart();
+      if (afterPipe.startsWith('{') || afterPipe.startsWith('[')) return afterPipe;
+    }
+  }
+
+  return trimmed;
+}
+
+function collectEvents(events, event) {
+  if (!event) return;
+  if (Array.isArray(event)) {
+    events.push(...event);
+    return;
+  }
+  events.push(event);
+}
+
+function parseChunkWithProvider(providerOrName, chunk) {
+  if (!chunk) return [];
+  const provider =
+    typeof providerOrName === 'string' ? getProvider(providerOrName) : providerOrName;
+  const events = [];
+  const lines = chunk.split('\n');
+
+  for (const line of lines) {
+    const content = stripTimestampPrefix(line);
+    if (!content) continue;
+    collectEvents(events, provider.parseEvent(content));
+  }
+
+  return events;
+}
+
+function parseProviderChunk(providerName, chunk) {
+  return parseChunkWithProvider(providerName || 'claude', chunk);
+}
+
+function createProviderClass(name) {
+  return class ProviderFacade extends RuntimeProvider {
+    constructor() {
+      super(name);
+    }
+  };
+}
+
+module.exports = {
+  getProvider,
+  detectProviders,
+  listProviders,
+  parseProviderChunk,
+  parseChunkWithProvider,
+  createProviderClass,
+};

package/src/providers/openai/index.js

@@ -0,0 +1,3 @@
+const { createProviderClass } = require('..');
+
+module.exports = createProviderClass('codex');