@the-open-engine/zeroshot 5.4.0

package/lib/settings/claude-auth.js

@@ -0,0 +1,78 @@
+/**
+ * Claude authentication settings and helpers
+ * Extracted from settings.js for provider-specific isolation
+ */
+
+/**
+ * Anthropic API key prefix for validation
+ */
+const ANTHROPIC_KEY_PREFIX = 'sk-ant-';
+
+/**
+ * Environment variables used for Claude authentication
+ */
+const CLAUDE_AUTH_ENV_VARS = [
+  'ANTHROPIC_API_KEY',
+  'AWS_BEARER_TOKEN_BEDROCK',
+  'AWS_REGION',
+  'CLAUDE_CODE_USE_BEDROCK',
+];
+
+/**
+ * Validate an Anthropic API key format
+ * @param {string|null|undefined} key - API key to validate
+ * @returns {boolean} True if key is falsy OR starts with valid prefix
+ */
+function isValidAnthropicKey(key) {
+  return !key || key.startsWith(ANTHROPIC_KEY_PREFIX);
+}
+
+/**
+ * Check if Bedrock mode is active based on env and overrides
+ * @param {Object} [envOverrides={}] - Environment variable overrides to check
+ * @returns {boolean} True if Bedrock mode is active
+ */
+function isBedrockMode(envOverrides = {}) {
+  return (
+    envOverrides.CLAUDE_CODE_USE_BEDROCK === '1' || process.env.CLAUDE_CODE_USE_BEDROCK === '1'
+  );
+}
+
+/**
+ * Resolve Claude authentication environment variables from settings
+ * Bedrock takes priority over direct Anthropic API key AND OAuth session
+ * @param {Object} settings - Settings object from loadSettings()
+ * @returns {Object} Environment variables to set for Claude auth
+ */
+function resolveClaudeAuth(settings) {
+  const claudeSettings = settings.providerSettings?.claude || {};
+  const env = {};
+
+  // Bedrock takes priority over everything (including OAuth)
+  if (!process.env.AWS_BEARER_TOKEN_BEDROCK && claudeSettings.bedrockApiKey) {
+    env.AWS_BEARER_TOKEN_BEDROCK = claudeSettings.bedrockApiKey;
+    env.CLAUDE_CODE_USE_BEDROCK = '1';
+    if (claudeSettings.bedrockRegion && !process.env.AWS_REGION) {
+      env.AWS_REGION = claudeSettings.bedrockRegion;
+    }
+  } else if (process.env.AWS_BEARER_TOKEN_BEDROCK && !process.env.CLAUDE_CODE_USE_BEDROCK) {
+    // Auto-set CLAUDE_CODE_USE_BEDROCK if token present in env
+    env.CLAUDE_CODE_USE_BEDROCK = '1';
+  }
+
+  // Anthropic API key only if no Bedrock
+  const hasBedrock = env.AWS_BEARER_TOKEN_BEDROCK || process.env.AWS_BEARER_TOKEN_BEDROCK;
+  if (!process.env.ANTHROPIC_API_KEY && !hasBedrock && claudeSettings.anthropicApiKey) {
+    env.ANTHROPIC_API_KEY = claudeSettings.anthropicApiKey;
+  }
+
+  return env;
+}
+
+module.exports = {
+  ANTHROPIC_KEY_PREFIX,
+  CLAUDE_AUTH_ENV_VARS,
+  isValidAnthropicKey,
+  isBedrockMode,
+  resolveClaudeAuth,
+};

package/lib/settings.js

@@ -0,0 +1,542 @@
+/**
+ * Settings management for zeroshot
+ * Persistent user preferences stored in ~/.zeroshot/settings.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { validateMountConfig, validateEnvPassthrough } = require('./docker-config');
+const {
+  VALID_PROVIDERS,
+  normalizeProviderName,
+  normalizeProviderSettings,
+} = require('./provider-names');
+
+// Lazy-loaded to avoid circular dependency (issue-providers → settings → issue-providers)
+let _issueProviderFns = null;
+function getIssueProviderFns() {
+  if (!_issueProviderFns) {
+    _issueProviderFns = require('../src/issue-providers');
+  }
+  return _issueProviderFns;
+}
+
+/**
+ * Get settings file path (dynamically reads env var for testing)
+ * Using a getter ensures tests can override the path at runtime
+ * @returns {string}
+ */
+function getSettingsFile() {
+  return (
+    process.env.ZEROSHOT_SETTINGS_FILE || path.join(os.homedir(), '.zeroshot', 'settings.json')
+  );
+}
+
+// Import provider defaults from separate module to avoid circular dependency
+const { getProviderDefaults, clearProviderDefaultsCache } = require('./provider-defaults');
+
+/**
+ * Model hierarchy for cost ceiling validation
+ * Higher number = more expensive/capable model
+ */
+const MODEL_HIERARCHY = {
+  opus: 3,
+  sonnet: 2,
+  haiku: 1,
+};
+
+const VALID_MODELS = Object.keys(MODEL_HIERARCHY);
+const LEVEL_RANKS = { level1: 1, level2: 2, level3: 3 };
+
+/**
+ * Validate a requested model against the maxModel ceiling and minModel floor
+ * @param {string} requestedModel - Model the agent wants to use
+ * @param {string} maxModel - Maximum allowed model (cost ceiling)
+ * @param {string|null} minModel - Minimum required model (cost floor)
+ * @returns {string} The validated model
+ * @throws {Error} If requested model exceeds ceiling or falls below floor
+ */
+function validateModelAgainstMax(requestedModel, maxModel, minModel = null) {
+  if (!requestedModel) return maxModel; // Default to ceiling if unspecified
+
+  if (!VALID_MODELS.includes(requestedModel)) {
+    throw new Error(`Invalid model "${requestedModel}". Valid: ${VALID_MODELS.join(', ')}`);
+  }
+  if (!VALID_MODELS.includes(maxModel)) {
+    throw new Error(`Invalid maxModel "${maxModel}". Valid: ${VALID_MODELS.join(', ')}`);
+  }
+
+  if (MODEL_HIERARCHY[requestedModel] > MODEL_HIERARCHY[maxModel]) {
+    throw new Error(
+      `Agent requests "${requestedModel}" but maxModel is "${maxModel}". ` +
+        `Either lower agent's model or raise maxModel.`
+    );
+  }
+
+  if (minModel) {
+    if (!VALID_MODELS.includes(minModel)) {
+      throw new Error(`Invalid minModel "${minModel}". Valid: ${VALID_MODELS.join(', ')}`);
+    }
+    if (MODEL_HIERARCHY[minModel] > MODEL_HIERARCHY[maxModel]) {
+      throw new Error(`minModel "${minModel}" cannot be higher than maxModel "${maxModel}".`);
+    }
+    if (MODEL_HIERARCHY[requestedModel] < MODEL_HIERARCHY[minModel]) {
+      throw new Error(
+        `Agent requests "${requestedModel}" but minModel is "${minModel}". ` +
+          `Either raise agent's model or lower minModel.`
+      );
+    }
+  }
+
+  return requestedModel;
+}
+
+// Default settings (base - without issue provider settings which are added dynamically)
+const DEFAULT_SETTINGS_BASE = {
+  maxModel: 'opus', // Cost ceiling - agents cannot use models above this
+  minModel: null, // Cost floor - agents cannot use models below this (null = no minimum)
+  defaultProvider: 'claude',
+  get providerSettings() {
+    // Dynamically build from providers on first access
+    return getProviderDefaults();
+  },
+  defaultConfig: 'conductor-bootstrap',
+  defaultDocker: false,
+  strictSchema: true, // true = reliable json output (default), false = live streaming (may crash - see bold-meadow-11)
+  logLevel: 'normal',
+  // Auto-update settings
+  autoCheckUpdates: true, // Check npm registry for newer versions
+  lastUpdateCheckAt: null, // Unix timestamp of last check (null = never checked)
+  lastSeenVersion: null, // Don't re-prompt for same version
+  // Claude command - customize how to invoke Claude CLI (default: 'claude')
+  // Example: 'ccr code' for claude-code-router integration
+  claudeCommand: 'claude',
+  // Docker isolation mounts - preset names or {host, container, readonly?} objects
+  // Valid presets: gh, git, ssh, aws, azure, kube, terraform, gcloud, claude, codex, gemini, opencode
+  dockerMounts: ['gh', 'git', 'ssh'],
+  // Extra env vars to pass to Docker container (in addition to preset-implied ones)
+  // Supports: VAR (if set), VAR_* (pattern), VAR=value (forced), VAR= (empty)
+  dockerEnvPassthrough: [],
+  // Container home directory - where $HOME resolves in container paths
+  // Default: /home/node (matches zeroshot-cluster-base image)
+  dockerContainerHome: '/home/node',
+  // Retry/restart robustness defaults
+  maxRetries: 3, // Agent task retries (per execution) for retryable errors
+  maxRestartAttempts: 3, // Agent restarts since last TASK_COMPLETED
+  maxTotalRestarts: 10, // Safety valve (never resets)
+  staleWarningsBeforeKill: 2, // Consecutive stale warnings before restart
+  backoffBaseMs: 2000, // Initial retry backoff
+  backoffMaxMs: 30000, // Max retry backoff
+  jitterFactor: 0.2, // Random jitter ±20%
+  // Issue provider settings - defaultIssueSource is here, others come from providers
+  defaultIssueSource: 'github', // 'github' | 'gitlab' | 'jira' | 'azure-devops'
+};
+
+// Cache for merged defaults (base + issue provider settings)
+let _defaultSettingsCache = null;
+
+/**
+ * Get DEFAULT_SETTINGS with issue provider settings merged in
+ * Lazy-loaded to avoid circular dependency at module load time
+ */
+function getDefaultSettings() {
+  if (!_defaultSettingsCache) {
+    const issueProviderDefaults = getIssueProviderFns().getIssueProviderSettingsDefaults();
+    _defaultSettingsCache = {
+      ...DEFAULT_SETTINGS_BASE,
+      ...issueProviderDefaults,
+    };
+  }
+  return _defaultSettingsCache;
+}
+
+// For backward compatibility, export DEFAULT_SETTINGS as a getter
+const DEFAULT_SETTINGS = new Proxy(DEFAULT_SETTINGS_BASE, {
+  get(target, prop) {
+    // For known base properties, return from base
+    if (prop in target) {
+      return target[prop];
+    }
+    // For issue provider settings, get from merged defaults
+    const merged = getDefaultSettings();
+    return merged[prop];
+  },
+  has(target, prop) {
+    if (prop in target) return true;
+    const merged = getDefaultSettings();
+    return prop in merged;
+  },
+  ownKeys() {
+    const merged = getDefaultSettings();
+    return Object.keys(merged);
+  },
+  getOwnPropertyDescriptor(target, prop) {
+    const merged = getDefaultSettings();
+    if (prop in merged) {
+      return { enumerable: true, configurable: true, value: merged[prop] };
+    }
+    return undefined;
+  },
+});
+
+function mapLegacyModelToLevel(model) {
+  switch (model) {
+    case 'haiku':
+      return 'level1';
+    case 'sonnet':
+      return 'level2';
+    case 'opus':
+      return 'level3';
+    default:
+      return null;
+  }
+}
+
+function mergeProviderSettings(current, overrides) {
+  // Ensure current has all providers with their defaults
+  const providerDefaults = getProviderDefaults();
+  const merged = {};
+
+  for (const provider of VALID_PROVIDERS) {
+    merged[provider] = {
+      ...(providerDefaults[provider] || {}),
+      ...(current[provider] || {}),
+      ...(overrides?.[provider] || {}),
+    };
+    if (!merged[provider].levelOverrides) {
+      merged[provider].levelOverrides = {};
+    }
+  }
+  return merged;
+}
+
+function applyLegacyModelBounds(settings) {
+  if (!settings.providerSettings) return settings;
+  const claude = settings.providerSettings.claude || {};
+  const legacyMaxLevel = mapLegacyModelToLevel(settings.maxModel);
+  const legacyMinLevel = mapLegacyModelToLevel(settings.minModel);
+
+  if (legacyMaxLevel) {
+    claude.maxLevel = legacyMaxLevel;
+  }
+
+  if (legacyMinLevel) {
+    claude.minLevel = legacyMinLevel;
+  }
+
+  const minRank = LEVEL_RANKS[claude.minLevel] || LEVEL_RANKS.level1;
+  const maxRank = LEVEL_RANKS[claude.maxLevel] || LEVEL_RANKS.level3;
+  const defaultRank = LEVEL_RANKS[claude.defaultLevel] || LEVEL_RANKS.level2;
+
+  if (minRank > maxRank) {
+    claude.minLevel = 'level1';
+    claude.maxLevel = 'level3';
+  } else if (defaultRank < minRank) {
+    claude.defaultLevel = claude.minLevel;
+  } else if (defaultRank > maxRank) {
+    claude.defaultLevel = claude.maxLevel;
+  }
+
+  settings.providerSettings.claude = claude;
+  return settings;
+}
+
+function normalizeLoadedSettings(parsed) {
+  const normalized = { ...parsed };
+  if (parsed.defaultProvider) {
+    normalized.defaultProvider = normalizeProviderName(parsed.defaultProvider);
+  }
+  if (parsed.providerSettings) {
+    normalized.providerSettings = normalizeProviderSettings(parsed.providerSettings);
+  }
+  return normalized;
+}
+
+/**
+ * Load settings from disk, merging with defaults
+ */
+function loadSettings() {
+  const settingsFile = getSettingsFile();
+  if (!fs.existsSync(settingsFile)) {
+    // Return a copy with resolved providerSettings
+    return {
+      ...DEFAULT_SETTINGS,
+      providerSettings: getProviderDefaults(),
+    };
+  }
+  try {
+    const data = fs.readFileSync(settingsFile, 'utf8');
+    const parsed = normalizeLoadedSettings(JSON.parse(data));
+    const merged = { ...DEFAULT_SETTINGS, ...parsed };
+    merged.defaultProvider =
+      normalizeProviderName(merged.defaultProvider) || DEFAULT_SETTINGS.defaultProvider;
+    merged.providerSettings = mergeProviderSettings(getProviderDefaults(), parsed.providerSettings);
+    return applyLegacyModelBounds(merged);
+  } catch {
+    console.error('Warning: Could not load settings, using defaults');
+    return {
+      ...DEFAULT_SETTINGS,
+      providerSettings: getProviderDefaults(),
+    };
+  }
+}
+
+/**
+ * Save settings to disk
+ */
+function saveSettings(settings) {
+  const settingsFile = getSettingsFile();
+  const dir = path.dirname(settingsFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2), 'utf8');
+}
+
+/**
+ * Validate claudeCommand setting
+ * @returns {string|null} Error message if invalid, null if valid
+ */
+function validateClaudeCommand(value) {
+  if (typeof value !== 'string') {
+    return 'claudeCommand must be a string';
+  }
+  if (value.trim().length === 0) {
+    return 'claudeCommand cannot be empty';
+  }
+  return null;
+}
+
+/**
+ * Validate providerSettings structure by delegating to provider implementations
+ * @returns {string|null} Error message if invalid, null if valid
+ */
+function validateProviderSettings(value) {
+  const normalizedSettings = normalizeProviderSettings(value);
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return 'providerSettings must be an object';
+  }
+
+  // Lazy require to avoid circular dependency
+  const { getProvider } = require('../src/providers');
+
+  for (const [providerName, settings] of Object.entries(normalizedSettings || {})) {
+    if (!VALID_PROVIDERS.includes(providerName)) {
+      return `Unknown provider in providerSettings: ${providerName}`;
+    }
+
+    // Delegate validation to the provider
+    try {
+      const provider = getProvider(providerName);
+      const error = provider.validateSettings(settings);
+      if (error) return error;
+    } catch (err) {
+      return `Failed to validate ${providerName} settings: ${err.message}`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate a setting value
+ * @returns {string|null} Error message if invalid, null if valid
+ */
+function validateSetting(key, value) {
+  if (!(key in DEFAULT_SETTINGS)) {
+    return `Unknown setting: ${key}`;
+  }
+
+  if (
+    [
+      'maxRetries',
+      'maxRestartAttempts',
+      'maxTotalRestarts',
+      'staleWarningsBeforeKill',
+      'backoffBaseMs',
+      'backoffMaxMs',
+    ].includes(key)
+  ) {
+    if (!Number.isFinite(value)) {
+      return `${key} must be a number`;
+    }
+    if (!Number.isInteger(value)) {
+      return `${key} must be an integer`;
+    }
+    const min = ['backoffBaseMs', 'backoffMaxMs'].includes(key) ? 0 : 1;
+    if (value < min) {
+      return `${key} must be >= ${min}`;
+    }
+  }
+
+  if (key === 'jitterFactor') {
+    if (!Number.isFinite(value)) {
+      return 'jitterFactor must be a number';
+    }
+    if (value < 0 || value > 1) {
+      return 'jitterFactor must be between 0 and 1';
+    }
+  }
+
+  if (key === 'maxModel' && !VALID_MODELS.includes(value)) {
+    return `Invalid model: ${value}. Valid models: ${VALID_MODELS.join(', ')}`;
+  }
+
+  if (key === 'minModel' && value !== null && !VALID_MODELS.includes(value)) {
+    return `Invalid model: ${value}. Valid models: ${VALID_MODELS.join(', ')}, null`;
+  }
+
+  if (key === 'logLevel' && !['quiet', 'normal', 'verbose'].includes(value)) {
+    return `Invalid log level: ${value}. Valid levels: quiet, normal, verbose`;
+  }
+
+  if (key === 'claudeCommand') {
+    return validateClaudeCommand(value);
+  }
+
+  if (key === 'defaultProvider') {
+    const normalized = normalizeProviderName(value);
+    if (!VALID_PROVIDERS.includes(normalized)) {
+      return `Invalid provider: ${value}. Valid providers: ${VALID_PROVIDERS.join(', ')}`;
+    }
+  }
+
+  if (key === 'providerSettings') {
+    return validateProviderSettings(value);
+  }
+
+  if (key === 'dockerMounts') {
+    return validateMountConfig(value);
+  }
+
+  if (key === 'dockerEnvPassthrough') {
+    return validateEnvPassthrough(value);
+  }
+
+  // Issue source settings validation (grouped for maintainability)
+  const issueSourceError = validateIssueSourceSetting(key, value);
+  if (issueSourceError !== undefined) {
+    return issueSourceError;
+  }
+
+  return null;
+}
+
+/**
+ * Validate issue source related settings
+ * Delegates to issue providers for provider-specific settings
+ * @param {string} key - Setting key
+ * @param {any} value - Setting value
+ * @returns {string|null|undefined} Error message, null if valid, undefined if not an issue source setting
+ */
+function validateIssueSourceSetting(key, value) {
+  // defaultIssueSource is handled here (not provider-specific)
+  if (key === 'defaultIssueSource') {
+    const { listProviders } = getIssueProviderFns();
+    const validSources = listProviders();
+    if (!validSources.includes(value)) {
+      return `Invalid issue source: ${value}. Valid: ${validSources.join(', ')}`;
+    }
+    return null;
+  }
+
+  // Delegate to issue providers for provider-specific settings
+  const { validateIssueProviderSetting } = getIssueProviderFns();
+  return validateIssueProviderSetting(key, value);
+}
+
+/**
+ * Coerce value to correct type based on default value type
+ */
+function coerceValue(key, value) {
+  const defaultValue = DEFAULT_SETTINGS[key];
+
+  // Handle null values for minModel
+  if (key === 'minModel' && (value === 'null' || value === null)) {
+    return null;
+  }
+
+  if (typeof defaultValue === 'boolean') {
+    return value === 'true' || value === '1' || value === 'yes' || value === true;
+  }
+
+  if (typeof defaultValue === 'number') {
+    const parsed = parseFloat(value);
+    if (isNaN(parsed)) {
+      throw new Error(`Invalid number: ${value}`);
+    }
+    return parsed;
+  }
+
+  // Handle array settings (dockerMounts, dockerEnvPassthrough)
+  if (Array.isArray(defaultValue)) {
+    if (typeof value === 'string') {
+      try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed)) {
+          throw new Error(`${key} must be an array`);
+        }
+        return parsed;
+      } catch (e) {
+        if (e instanceof SyntaxError) {
+          throw new Error(`Invalid JSON for ${key}: ${value}`);
+        }
+        throw e;
+      }
+    }
+    return value;
+  }
+
+  if (key === 'providerSettings') {
+    if (typeof value === 'string') {
+      try {
+        return normalizeProviderSettings(JSON.parse(value));
+      } catch {
+        throw new Error(`Invalid JSON for providerSettings: ${value}`);
+      }
+    }
+    return normalizeProviderSettings(value);
+  }
+
+  if (key === 'defaultProvider') {
+    return normalizeProviderName(value);
+  }
+
+  return value;
+}
+
+/**
+ * Get parsed Claude command from settings/env
+ * Supports space-separated commands like 'ccr code'
+ * @returns {{ command: string, args: string[] }}
+ */
+function getClaudeCommand() {
+  const settings = loadSettings();
+  const raw = process.env.ZEROSHOT_CLAUDE_COMMAND || settings.claudeCommand || 'claude';
+  const parts = raw.trim().split(/\s+/);
+  return {
+    command: parts[0],
+    args: parts.slice(1),
+  };
+}
+
+module.exports = {
+  loadSettings,
+  saveSettings,
+  validateSetting,
+  coerceValue,
+  DEFAULT_SETTINGS,
+  getSettingsFile,
+  getClaudeCommand,
+  // Model validation exports
+  MODEL_HIERARCHY,
+  VALID_MODELS,
+  validateModelAgainstMax,
+  // Provider defaults exports
+  clearProviderDefaultsCache,
+  // Backward compatibility: SETTINGS_FILE as getter (reads env var dynamically)
+  get SETTINGS_FILE() {
+    return getSettingsFile();
+  },
+};