@karma42/agent 0.0.0-stage → 0.1.0-beta.2

package/runtime/providers.mjs

@@ -0,0 +1,284 @@
+// Provider adapter protocol 1. Local CLI authentication remains owned by the client.
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+export const ADAPTER_PROTOCOL = 1;
+export const PROVIDERS = ['claude', 'codex'];
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const counter = v => Number.isSafeInteger(v) && v >= 0 && v <= 1e15 ? v : null;
+const text = (v, max = 2000) => typeof v === 'string' ? v.slice(0, max) : '';
+const safeName = v => typeof v === 'string' && /^[A-Za-z0-9_:.-]{1,150}$/.test(v) ? v : null;
+const tomlString = value => JSON.stringify(value); // TOML basic strings accept JSON string escaping.
+// Stable identity of the native Codex connection: the kit name and installed kit version, nothing about the operator.
+export const codexClientInfo = version => ({ name: 'karma42_runner', title: 'Karma42 runner', version });
+
+// Claude Code runs these without asking. Other Bash commands need approval, which --permission-prompts none refuses;
+// its built-in read-only commands and acceptEdits file edits inside the checkout still run.
+// Named Git subcommands with origin as the only remote, Issue/PR work and the project's own scripts; no npx, inline node
+// or other gh areas. Rules match command text on a best-effort basis (Claude Code documents argument rules as fragile),
+// and they are not a sandbox: tests, package scripts and Git hooks still run repository code the agent can edit.
+export const CLAUDE_ALLOWED_TOOLS = ['mcp__pilot',
+  ...['status', 'diff', 'log', 'show', 'branch', 'checkout', 'switch', 'restore', 'reset', 'add', 'rm', 'mv', 'commit', 'stash',
+    'merge', 'rebase', 'revert', 'cherry-pick'].map(v => `Bash(git ${v} *)`),
+  ...['log', 'diff', 'show'].map(v => `Bash(git --no-pager ${v} *)`),
+  'Bash(git fetch)', 'Bash(git fetch origin *)', 'Bash(git pull)', 'Bash(git pull origin *)', 'Bash(git pull --ff-only origin *)',
+  'Bash(git push)', 'Bash(git push origin *)', 'Bash(git push -u origin *)', 'Bash(git push --set-upstream origin *)',
+  'Bash(gh issue *)', 'Bash(gh pr *)', 'Bash(gh label list *)',
+  'Bash(npm test *)', 'Bash(npm run *)', 'Bash(npm ci *)', 'Bash(npm install)', 'Bash(npm install --ignore-scripts)', 'Bash(npm i)',
+  'Bash(node --check *)', 'Bash(node --test *)'].join(',');
+
+// Model clients and their preflight checks receive named variables only, never the operator's
+// whole shell. This hides unrelated secrets from the model; it does not isolate files or the keychain.
+const COMMON_ENV = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LANGUAGE', 'TZ',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP', 'USERNAME', 'USERPROFILE', 'HOMEDRIVE',
+  'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'PROGRAMFILES', 'OS', 'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS'];
+const PROVIDER_ENV = {
+  claude: ['CLAUDE_CONFIG_DIR', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_GIT_BASH_PATH'],
+  codex: ['CODEX_HOME', 'OPENAI_API_KEY', 'CODEX_API_KEY', 'DBUS_SESSION_BUS_ADDRESS'],
+};
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+export function passEnvNames(raw = '') {
+  const names = String(raw).split(',').map(v => v.trim()).filter(Boolean);
+  if (names.length > 64 || names.some(v => !ENV_NAME.test(v))) throw new Error('PILOT_PASS_ENV lists at most 64 variable names separated by commas, for example GH_TOKEN,HTTPS_PROXY.');
+  return names;
+}
+
+export function childEnv(id, source, extraNames = [], platform = process.platform) {
+  const key = platform === 'win32' ? v => v.toUpperCase() : v => v;
+  const allowed = new Set([...COMMON_ENV, ...PROVIDER_ENV[id], ...extraNames].map(key));
+  return Object.fromEntries(Object.entries(source).filter(([name, value]) => typeof value === 'string'
+    && (allowed.has(key(name)) || /^LC_[A-Z]+$/.test(name))));
+}
+
+export function createProvider(id, settings) {
+  if (!PROVIDERS.includes(id)) throw new Error('Select PILOT_PROVIDER=claude or codex. Providers never switch automatically.');
+  const command = id === 'codex' ? settings.codex : settings.claude;
+  const newMcpName = () => `project_${randomUUID().replaceAll('-', '')}`;
+  const passEnv = passEnvNames(settings.passEnv);
+  const environment = (extra = {}) => ({ ...childEnv(id, process.env, passEnv), ...extra });
+  // Listed again for every turn: config can change while the runner is up, and disabling a server that is
+  // no longer configured makes App Server refuse to start. Plugin-provided servers have no config entry to
+  // disable, so plugins are off in both the listing and the invocation.
+  const mcpServers = cwd => {
+    const list = spawnSync(command, ['-c', 'features.plugins=false', 'mcp', 'list', '--json'], { cwd, env: environment(), encoding: 'utf8', timeout: 15_000, maxBuffer: 1024 * 1024 });
+    if (list.error || list.status !== 0) throw new Error('Cannot inspect local MCP configuration before isolating the project connection.');
+    let servers; try { servers = JSON.parse(list.stdout); } catch { throw new Error('Invalid local MCP configuration listing.'); }
+    if (!Array.isArray(servers) || servers.length > 128 || servers.some(v => typeof v?.name !== 'string' || !/^[A-Za-z0-9_-]{1,150}$/.test(v.name))) throw new Error('Unsupported local MCP configuration listing.');
+    return servers.map(v => v.name);
+  };
+  return {
+    id, protocol: ADAPTER_PROTOCOL, environment,
+    preflight() {
+      if (id === 'codex' && settings.turnBudgetUsd > 0) throw new Error('Codex CLI cannot enforce a dollar cap. Remove PILOT_TURN_BUDGET_USD or choose Claude explicitly.');
+      if (id === 'codex' && ![undefined, 'acceptEdits', 'bypassPermissions'].includes(settings.permissionMode)) throw new Error('Codex accepts PILOT_PERMISSION_MODE=bypassPermissions only; leave it unset (default acceptEdits) for the workspace-write sandbox with automatic review.');
+      const probe = spawnSync(command, ['--version'], { env: environment(), encoding: 'utf8', timeout: 15_000 });
+      if (probe.error || probe.status !== 0) throw new Error(`Cannot run ${id} --version. Install the local client or set PILOT_${id.toUpperCase()}.`);
+      if (id === 'codex') {
+        const version = /codex-cli (\d+)\.(\d+)\.(\d+)/.exec(probe.stdout);
+        if (!version || +version[1] === 0 && +version[2] < 160) throw new Error('This adapter requires Codex CLI 0.160.0 or newer.');
+        const login = spawnSync(command, ['login', 'status'], { env: environment(), encoding: 'utf8', timeout: 15_000 });
+        if (login.error || login.status !== 0) throw new Error('Sign in locally with codex login, then start the runner again. No credentials were copied.');
+        mcpServers(settings.repoDir);
+      }
+      return { label: text(probe.stdout.trim(), 150) };
+    },
+    newSession(promptHash, repoDir) {
+      return { id: id === 'claude' ? randomUUID() : null, provider: id, promptHash, repoDir, costUsd: null, ...(id === 'codex' ? { mcpName: newMcpName() } : {}) };
+    },
+    canResume(session) { return id === 'claude' ? typeof session?.id === 'string' : session?.provider === id && UUID.test(session?.id ?? ''); },
+    invocation({ prompt, instructionsFile, settingsFile, mcpConfig, bridge, session, resuming, repoDir, clientVersion }) {
+      if (id === 'claude') {
+        const args = ['-p', prompt, '--output-format', 'stream-json', '--verbose', '--append-system-prompt-file', instructionsFile,
+          '--setting-sources=', '--settings', settingsFile, '--disable-slash-commands', '--mcp-config', mcpConfig, '--strict-mcp-config',
+          '--permission-mode', settings.permissionMode, '--permission-prompts', 'none', '--allowedTools', settings.allowedTools,
+          resuming ? '--resume' : '--session-id', session.id];
+        if (settings.turnBudgetUsd > 0) args.push('--max-budget-usd', String(settings.turnBudgetUsd));
+        if (settings.model) args.push('--model', settings.model);
+        return { command, args };
+      }
+      const endpoint = new URL(bridge.url);
+      const token = bridge.headers?.Authorization?.replace(/^Bearer /, '');
+      if (endpoint.protocol !== 'http:' || endpoint.hostname !== '127.0.0.1' || !token) throw new Error('Codex requires the authenticated local project bridge.');
+      if (typeof clientVersion !== 'string' || !clientVersion) throw new Error('Codex requires the installed kit version.');
+      // PILOT_PERMISSION_MODE=bypassPermissions is the operator's explicit choice of full access, never the default:
+      // no Codex sandbox and no approval review, so the project tools must be approved or approval policy never refuses them.
+      const fullAccess = settings.permissionMode === 'bypassPermissions';
+      const access = fullAccess ? { sandbox: 'danger-full-access', approvalPolicy: 'never' }
+        : { sandbox: 'workspace-write', approvalPolicy: 'on-request', approvalsReviewer: 'auto_review' };
+      const config = {
+        model_provider: '"openai"', sandbox_mode: `"${access.sandbox}"`, approval_policy: `"${access.approvalPolicy}"`,
+        ...(fullAccess ? {} : { approvals_reviewer: '"auto_review"' }),
+        developer_instructions: tomlString(readFileSync(instructionsFile, 'utf8')),
+        'features.hooks': 'false', 'features.apps': 'false', 'features.plugins': 'false', 'features.multi_agent': 'false', 'features.goals': 'false',
+        'memories.generate_memories': 'false', 'memories.use_memories': 'false',
+        'shell_environment_policy.filters.PILOT_BRIDGE_TOKEN': '"exclude"',
+      };
+      // App Server exposes resolved model identity, reroutes and full token-usage notifications.
+      // Disable the configured personal MCPs in this invocation only; never edit client config. The project server is
+      // set key by key: a whole mcp_servers table override would replace these disables and re-enable personal servers.
+      const configured = mcpServers(repoDir);
+      for (const name of configured) config[`mcp_servers.${name}.enabled`] = 'false';
+      // The session keeps the project server's name, which the runner saves with it: a thread resumed after a runner
+      // restart remembers its tools by that name. A new name is chosen only if a configured server now uses it.
+      if (!/^project_[0-9a-f]{32}$/.test(session.mcpName ?? '')) session.mcpName = newMcpName();
+      while (configured.includes(session.mcpName)) session.mcpName = newMcpName();
+      const mcpName = session.mcpName;
+      Object.assign(config, { [`mcp_servers.${mcpName}.url`]: tomlString(bridge.url),
+        [`mcp_servers.${mcpName}.bearer_token_env_var`]: '"PILOT_BRIDGE_TOKEN"', [`mcp_servers.${mcpName}.required`]: 'true',
+        ...(fullAccess ? { [`mcp_servers.${mcpName}.default_tools_approval_mode`]: '"approve"' } : {}) });
+      const args = ['app-server', '--stdio', '--strict-config', ...Object.entries(config).flatMap(([key, value]) => ['-c', `${key}=${value}`])];
+      const startParams = { cwd: repoDir, modelProvider: 'openai', ...access,
+        ...(settings.model ? { model: settings.model } : {}),
+        ...(resuming ? { threadId: session.id } : {}) };
+      return { command, args, env: { PILOT_BRIDGE_TOKEN: token }, rpc: { prompt, resuming, startParams, clientInfo: codexClientInfo(clientVersion),
+        baseline: resuming ? session.tokenTotals ?? null : [0, 0, 0, 0] } };
+    },
+    collector(options) { return id === 'codex' ? new CodexStream(options) : new ProviderStream(id, options); },
+    usage(report, init) {
+      const u = report?.usage;
+      let tokens = null;
+      if (u && !(id === 'claude' && report?.is_error && report.num_turns === 0)) {
+        const source = id === 'codex'
+          ? [u.input_tokens, u.output_tokens, u.cached_input_tokens, u.cache_write_input_tokens]
+          : [u.input_tokens, u.output_tokens, u.cache_read_input_tokens, u.cache_creation_input_tokens];
+        if (source.every(v => v === undefined || counter(v) !== null)) {
+          const measured = source.map(counter);
+          if (measured.some(v => v !== null)) tokens = { input: measured[0], output: measured[1], cacheRead: measured[2], cacheWrite: measured[3], modelCalls: null };
+        }
+      }
+      return { provider: id, inputSemantics: id === 'codex' ? 'includes-cache' : 'uncached',
+        model: safeName(init?.model), modelSource: init?.modelSource ?? (init?.model ? 'provider-report' : 'unknown'), tokens };
+    },
+    loginHint(detail) { return /not logged in|\/login|invalid api key|authentication/i.test(detail)
+      ? id === 'codex' ? ' Sign in locally with codex login.' : ' Sign in locally with claude /login.' : ''; },
+    missingSession(stderr) { return id === 'claude' && stderr.includes('No conversation found'); },
+  };
+}
+
+// Retain only session identity, final text, numeric usage and bounded failure metadata.
+// Tool arguments/results and reasoning are never retained or rendered by this collector.
+export class ProviderStream {
+  constructor(provider, { log = () => {}, action = () => {}, session = () => {} } = {}) {
+    this.provider = provider; this.log = log; this.action = action; this.session = session;
+    this.init = null; this.report = null; this.finalText = ''; this.sessionId = null;
+    this.pending = ''; this.dropping = false; this.truncated = false; this.toolCalls = 0; this.toolIds = new Set();
+  }
+  feed(chunk) {
+    for (const part of String(chunk).split(/(?<=\n)/)) {
+      if (!this.dropping && Buffer.byteLength(this.pending) + Buffer.byteLength(part) <= 1024 * 1024) this.pending += part;
+      else { this.pending = ''; this.dropping = true; this.truncated = true; }
+      if (part.endsWith('\n')) {
+        if (!this.dropping) this.line(this.pending);
+        this.pending = ''; this.dropping = false;
+      }
+    }
+  }
+  end() { if (!this.dropping && this.pending.trim()) this.line(this.pending); this.pending = ''; }
+  identify(value) { if (UUID.test(value ?? '')) { this.sessionId = value; this.session(value); } }
+  show(value, label = 'Agent') { if (typeof value === 'string' && value.trim()) this.log(`${label}: ${value.slice(0, 4000)}`); }
+  count(id) { if (!id || this.toolIds.has(id)) return; if (this.toolIds.size >= 4096) { this.truncated = true; return; } this.toolIds.add(id); this.toolCalls++; }
+  act(value) { const name = safeName(value); if (name) { this.log(`Agent action: ${name}`); this.action(name); } }
+  line(line) {
+    let events;
+    try { const parsed = JSON.parse(line); events = Array.isArray(parsed) ? parsed : [parsed]; } catch { return; }
+    for (const e of events) {
+      if (!e || typeof e !== 'object') continue;
+      if (this.provider === 'claude') {
+        if (e.type === 'system' && e.subtype === 'init') this.init = { model: safeName(e.model), effort: safeName(e.effort) };
+        if (e.type === 'assistant') for (const block of e.message?.content ?? []) {
+          if (block.type === 'text') this.show(block.text);
+          if (block.type === 'tool_use') { this.count(block.id ?? `${e.message?.id ?? e.uuid ?? 'unknown'}:${block.name}`); this.act(block.name); }
+        }
+        if (e.type === 'result') {
+          this.identify(e.session_id);
+          this.report = { is_error: e.is_error === true, subtype: safeName(e.subtype), num_turns: counter(e.num_turns),
+            session_id: this.sessionId, usage: e.usage ? { input_tokens: e.usage.input_tokens, output_tokens: e.usage.output_tokens,
+              cache_read_input_tokens: e.usage.cache_read_input_tokens, cache_creation_input_tokens: e.usage.cache_creation_input_tokens } : null,
+            result: text(e.result, 32 * 1024), errors: Array.isArray(e.errors) ? e.errors.slice(0, 5).map(v => text(v)) : [],
+            permission_denials: Array.isArray(e.permission_denials) ? e.permission_denials.slice(0, 100).map(v => ({ tool_name: safeName(v?.tool_name) })) : [] };
+          this.show(e.result, 'Agent result');
+        }
+      }
+    }
+  }
+}
+
+// App Server protocol: initialize → start/resume → turn/start → ordered notifications.
+// Only this thread's scalar metadata survives parsing; no conversation history is requested.
+class CodexStream extends ProviderStream {
+  constructor(options) { super('codex', options); this.rpc = options.rpc; this.threadId = null; this.turnId = null;
+    this.tokenTotals = null; this.closed = false; this.nextId = 10; this.interrupted = false; }
+  attach(process_) {
+    this.process = process_;
+    this.send({ id: 1, method: 'initialize', params: { clientInfo: this.rpc.clientInfo } });
+    this.setupTimer = setTimeout(() => { this.fail('Codex initialization timed out before starting project work.'); }, 45_000);
+  }
+  send(value) { if (!this.closed && !this.process.stdin.destroyed) this.process.stdin.write(JSON.stringify(value) + '\n'); }
+  cleanup() { clearTimeout(this.setupTimer); clearTimeout(this.closeTimer); }
+  finish() {
+    if (this.closed) return; this.closed = true; this.cleanup(); this.process.stdin.end();
+    this.closeTimer = setTimeout(() => this.process.kill('SIGKILL'), 5000);
+  }
+  fail(message) { this.report = { is_error: true, usage: null, result: '', errors: [text(message)] }; this.finish(); }
+  interrupt() {
+    this.interrupted = true;
+    if (this.threadId && this.turnId) this.send({ id: this.nextId++, method: 'turn/interrupt', params: { threadId: this.threadId, turnId: this.turnId } });
+    else this.process.kill('SIGINT');
+  }
+  line(line) {
+    let e; try { e = JSON.parse(line); } catch { return; }
+    if (e.id === 1) {
+      if (e.error) return this.fail(e.error.message);
+      this.send({ method: 'initialized', params: {} });
+      this.send({ id: 2, method: this.rpc.resuming ? 'thread/resume' : 'thread/start', params: this.rpc.startParams });
+      return;
+    }
+    if (e.id === 2) {
+      if (e.error) return this.fail(e.error.message);
+      const r = e.result;
+      if (!UUID.test(r?.thread?.id ?? '') || r.modelProvider !== 'openai') return this.fail('Codex returned an unsupported thread/provider identity.');
+      this.threadId = r.thread.id; this.identify(this.threadId);
+      this.init = { model: safeName(r.model), modelSource: 'client-selected' };
+      this.send({ id: 3, method: 'turn/start', params: { threadId: this.threadId, input: [{ type: 'text', text: this.rpc.prompt }] } });
+      return;
+    }
+    if (e.id === 3) {
+      if (e.error) return this.fail(e.error.message);
+      this.turnId ??= e.result?.turn?.id; clearTimeout(this.setupTimer);
+      if (this.interrupted) this.interrupt(); return;
+    }
+    if (e.method && e.id !== undefined) {
+      // Automatic review handles supported approval requests. Never approve an unexpected
+      // interactive request or keep an unattended turn waiting for a human response.
+      this.send({ id: e.id, error: { code: -32601, message: 'This foreground adapter cannot answer interactive requests.' } });
+      return this.fail(`Codex requested interactive input (${safeName(e.method) ?? 'unknown'}); review the local execution policy.`);
+    }
+    const v = e.params;
+    if (!v || v.threadId !== this.threadId) return;
+    if (e.method === 'turn/started') { this.turnId = v.turn?.id; clearTimeout(this.setupTimer); }
+    if (v.turnId && this.turnId && v.turnId !== this.turnId) return;
+    if (e.method === 'model/rerouted') this.init = { model: safeName(v.toModel), modelSource: 'provider-rerouted' };
+    if (e.method === 'thread/tokenUsage/updated' && this.turnId) {
+      const t = v.tokenUsage?.total;
+      if (t) this.tokenTotals = [t.inputTokens, t.outputTokens, t.cachedInputTokens, t.cacheWriteInputTokens].map(counter);
+    }
+    if (e.method === 'item/started' || e.method === 'item/completed') {
+      const item = v.item;
+      if (['commandExecution', 'mcpToolCall', 'fileChange', 'webSearch', 'dynamicToolCall', 'imageGeneration'].includes(item?.type)) {
+        this.count(item.id); if (e.method === 'item/started') this.act(item.type);
+      }
+      if (e.method === 'item/completed' && item?.type === 'agentMessage') { this.finalText = text(item.text, 32 * 1024); this.show(this.finalText); }
+    }
+    if (e.method === 'turn/completed') {
+      if (this.turnId && v.turn?.id !== this.turnId) return;
+      const baseline = this.rpc.baseline;
+      const values = this.tokenTotals?.map((n, i) => n !== null && baseline?.[i] !== null && counter(baseline?.[i]) !== null && n >= baseline[i] ? n - baseline[i] : undefined);
+      this.report = { is_error: v.turn?.status !== 'completed', result: this.finalText,
+        usage: values ? { input_tokens: values[0], output_tokens: values[1], cached_input_tokens: values[2], cache_write_input_tokens: values[3] } : null,
+        errors: v.turn?.error?.message ? [text(v.turn.error.message)] : [] };
+      this.finish();
+    }
+  }
+}