@covibes/zeroshot 5.2.1 → 5.3.0

package/src/providers/base-provider.js

@@ -0,0 +1,181 @@
+/**
+ * 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;
+  }
+
+  // ============================================================================
+  // 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] || {};
+    return {
+      level,
+      model: override.model || base.model,
+      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]) {
+      throw new Error(`Invalid model "${modelId}" for provider "${this.name}"`);
+    }
+    return modelId;
+  }
+
+  getDefaultLevel() {
+    throw new Error('Not implemented');
+  }
+}
+
+module.exports = BaseProvider;

package/src/providers/capabilities.js

@@ -0,0 +1,51 @@
+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,
+  },
+};
+
+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/cli-builder.js

@@ -0,0 +1,55 @@
+function buildCommand(context, options = {}) {
+  const { modelSpec, outputFormat, jsonSchema, cwd, autoApprove, cliFeatures = {} } = options;
+
+  // Augment context with schema if provided (Gemini CLI doesn't support native schema enforcement)
+  let finalContext = context;
+  if (jsonSchema) {
+    // CRITICAL: Inject schema into prompt since Gemini CLI has no --output-schema flag
+    // Without this, model outputs free-form text instead of JSON
+    const schemaStr =
+      typeof jsonSchema === 'string' ? jsonSchema : JSON.stringify(jsonSchema, null, 2);
+    finalContext =
+      context +
+      `\n\n## OUTPUT FORMAT (CRITICAL - REQUIRED)
+
+You MUST respond with a JSON object that exactly matches this schema. NO markdown, NO explanation, NO code blocks. ONLY the raw JSON object.
+
+Schema:
+\`\`\`json
+${schemaStr}
+\`\`\`
+
+Your response must be ONLY valid JSON. Start with { and end with }. Nothing else.`;
+  }
+
+  const args = ['-p', finalContext];
+
+  if (
+    (outputFormat === 'stream-json' || outputFormat === 'json') &&
+    cliFeatures.supportsStreamJson
+  ) {
+    args.push('--output-format', 'stream-json');
+  }
+
+  if (modelSpec?.model) {
+    args.push('-m', modelSpec.model);
+  }
+
+  if (cwd && cliFeatures.supportsCwd) {
+    args.push('--cwd', cwd);
+  }
+
+  if (autoApprove && cliFeatures.supportsAutoApprove) {
+    args.push('--yolo');
+  }
+
+  return {
+    binary: 'gemini',
+    args,
+    env: {},
+  };
+}
+
+module.exports = {
+  buildCommand,
+};

package/src/providers/google/index.js

@@ -0,0 +1,116 @@
+const BaseProvider = require('../base-provider');
+const { commandExists, getCommandPath, getHelpOutput } = require('../../../lib/provider-detection');
+const { buildCommand } = require('./cli-builder');
+const { parseEvent } = require('./output-parser');
+const {
+  MODEL_CATALOG,
+  LEVEL_MAPPING,
+  DEFAULT_LEVEL,
+  DEFAULT_MAX_LEVEL,
+  DEFAULT_MIN_LEVEL,
+} = require('./models');
+
+const warned = new Set();
+
+class GoogleProvider extends BaseProvider {
+  constructor() {
+    super({ name: 'gemini', displayName: 'Gemini', cliCommand: 'gemini' });
+    this._cliFeatures = null;
+    this._unknownEventCounts = new Map();
+    this._parserState = { lastToolId: null };
+  }
+
+  // SDK not implemented - uses CLI only
+  // See BaseProvider for SDK extension point documentation
+
+  isAvailable() {
+    return commandExists(this.cliCommand);
+  }
+
+  getCliPath() {
+    return getCommandPath(this.cliCommand) || this.cliCommand;
+  }
+
+  getInstallInstructions() {
+    return 'npm install -g @google/gemini-cli';
+  }
+
+  getAuthInstructions() {
+    return 'gemini auth login';
+  }
+
+  getCliFeatures() {
+    if (this._cliFeatures) return this._cliFeatures;
+    const help = getHelpOutput(this.cliCommand);
+    const unknown = !help;
+
+    const features = {
+      supportsStreamJson: unknown ? true : /--output-format\b/.test(help),
+      supportsAutoApprove: unknown ? true : /--yolo\b/.test(help),
+      supportsCwd: unknown ? true : /--cwd\b/.test(help),
+      supportsModel: unknown ? true : /\s-m\b/.test(help) || /--model\b/.test(help),
+      unknown,
+    };
+
+    this._cliFeatures = features;
+    return features;
+  }
+
+  getCredentialPaths() {
+    return ['~/.config/gcloud', '~/.config/gemini', '~/.gemini'];
+  }
+
+  buildCommand(context, options) {
+    const cliFeatures = options.cliFeatures || {};
+
+    if (options.autoApprove && cliFeatures.supportsAutoApprove === false) {
+      this._warnOnce(
+        'gemini-auto-approve',
+        'Gemini CLI does not support --yolo; continuing without auto-approve.'
+      );
+    }
+
+    return buildCommand(context, { ...options, cliFeatures });
+  }
+
+  parseEvent(line) {
+    return parseEvent(line, this._parserState, {
+      onUnknown: (type) => this._logUnknown(type),
+    });
+  }
+
+  getModelCatalog() {
+    return MODEL_CATALOG;
+  }
+
+  getLevelMapping() {
+    return LEVEL_MAPPING;
+  }
+
+  getDefaultLevel() {
+    return DEFAULT_LEVEL;
+  }
+
+  getDefaultMaxLevel() {
+    return DEFAULT_MAX_LEVEL;
+  }
+
+  getDefaultMinLevel() {
+    return DEFAULT_MIN_LEVEL;
+  }
+
+  _warnOnce(key, message) {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn(`⚠️ ${message}`);
+  }
+
+  _logUnknown(type) {
+    const current = this._unknownEventCounts.get(type) || 0;
+    if (current >= 5) return;
+    this._unknownEventCounts.set(type, current + 1);
+    console.debug(`[gemini] Unknown event type: ${type}`);
+  }
+}
+
+module.exports = GoogleProvider;

package/src/providers/google/models.js

@@ -0,0 +1,24 @@
+// Gemini CLI model names
+// Model is optional - Gemini defaults to best available
+const MODEL_CATALOG = {
+  'gemini-2.5-pro': { rank: 3 },
+  'gemini-2.0-flash': { rank: 1 },
+};
+
+const LEVEL_MAPPING = {
+  level1: { rank: 1, model: null },
+  level2: { rank: 2, model: null },
+  level3: { rank: 3, model: null },
+};
+
+const DEFAULT_LEVEL = 'level2';
+const DEFAULT_MAX_LEVEL = 'level3';
+const DEFAULT_MIN_LEVEL = 'level1';
+
+module.exports = {
+  MODEL_CATALOG,
+  LEVEL_MAPPING,
+  DEFAULT_LEVEL,
+  DEFAULT_MAX_LEVEL,
+  DEFAULT_MIN_LEVEL,
+};

package/src/providers/google/output-parser.js

@@ -0,0 +1,92 @@
+function normalizeMessageContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((item) => (typeof item === 'string' ? item : item?.text || '')).join('');
+  }
+  if (content && typeof content === 'object') {
+    if (typeof content.text === 'string') return content.text;
+  }
+  return '';
+}
+
+function parseEvent(line, state = {}, options = {}) {
+  let event;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  switch (event.type) {
+    case 'init':
+      return null;
+
+    case 'message':
+      if (event.role === 'assistant') {
+        const text = normalizeMessageContent(event.content);
+        if (text) {
+          return { type: 'text', text };
+        }
+      }
+      return null;
+
+    case 'tool_use': {
+      const toolId = event.tool_call_id || event.tool_id || event.id || state.lastToolId;
+      const toolName = event.tool_name || event.name;
+      state.lastToolId = toolId;
+      return {
+        type: 'tool_call',
+        toolName,
+        toolId,
+        input: event.parameters || event.input || {},
+      };
+    }
+
+    case 'tool_result': {
+      const toolId = event.tool_call_id || event.tool_id || event.id || state.lastToolId;
+      return {
+        type: 'tool_result',
+        toolId,
+        content: event.output ?? event.content ?? '',
+        isError: event.success === false,
+      };
+    }
+
+    case 'result':
+      return {
+        type: 'result',
+        success: event.success !== false,
+        result: event.result || '',
+        error: event.success === false ? event.error || 'Result failed' : null,
+      };
+
+    default:
+      if (options.onUnknown) {
+        options.onUnknown(event.type, event);
+      }
+      return null;
+  }
+}
+
+function parseChunk(chunk, state = {}, options = {}) {
+  const events = [];
+  const lines = chunk.split('\n');
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const event = parseEvent(line, state, options);
+    if (!event) continue;
+    if (Array.isArray(event)) {
+      events.push(...event);
+    } else {
+      events.push(event);
+    }
+  }
+
+  return events;
+}
+
+module.exports = {
+  parseEvent,
+  parseChunk,
+};

package/src/providers/index.js

@@ -0,0 +1,75 @@
+const AnthropicProvider = require('./anthropic');
+const OpenAIProvider = require('./openai');
+const GoogleProvider = require('./google');
+const { normalizeProviderName } = require('../../lib/provider-names');
+
+const PROVIDERS = {
+  claude: AnthropicProvider,
+  codex: OpenAIProvider,
+  gemini: GoogleProvider,
+};
+
+function getProvider(name) {
+  const normalized = normalizeProviderName(name || '');
+  const Provider = PROVIDERS[normalized];
+  if (!Provider) {
+    throw new Error(`Unknown provider: ${name}. Valid: ${Object.keys(PROVIDERS).join(', ')}`);
+  }
+  return new Provider();
+}
+
+async function detectProviders() {
+  const results = {};
+  for (const [name, Provider] of Object.entries(PROVIDERS)) {
+    const provider = new Provider();
+    results[name] = {
+      available: await provider.isAvailable(),
+    };
+  }
+  return results;
+}
+
+function listProviders() {
+  return Object.keys(PROVIDERS);
+}
+
+function stripTimestampPrefix(line) {
+  if (!line || typeof line !== 'string') return '';
+  const trimmed = line.trim().replace(/\r$/, '');
+  if (!trimmed) return '';
+  const match = trimmed.match(/^\[(\d{13})\](.*)$/);
+  return match ? match[2] : trimmed;
+}
+
+function parseChunkWithProvider(provider, chunk) {
+  if (!chunk) return [];
+  const events = [];
+  const lines = chunk.split('\n');
+
+  for (const line of lines) {
+    const content = stripTimestampPrefix(line);
+    if (!content) continue;
+    const event = provider.parseEvent(content);
+    if (!event) continue;
+    if (Array.isArray(event)) {
+      events.push(...event);
+    } else {
+      events.push(event);
+    }
+  }
+
+  return events;
+}
+
+function parseProviderChunk(providerName, chunk) {
+  const provider = getProvider(providerName || 'claude');
+  return parseChunkWithProvider(provider, chunk);
+}
+
+module.exports = {
+  getProvider,
+  detectProviders,
+  listProviders,
+  parseProviderChunk,
+  parseChunkWithProvider,
+};