genaicode 2.1.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- `genaicode/agents` subpath (experimental): run installed coding-agent CLIs behind one
+  `CodingAgent` interface. Drivers `claude()`, `codex()`, `muse()`; agent-neutral
+  `AgentEvent` stream and `AgentResult`; abort, timeout and process-group kill;
+  `detectAgents` / `findExecutable`; `cliAgent()` for custom drivers. See
+  [docs/agents.md](docs/agents.md).
+- Live agent sessions over JSON-RPC: `codexLive()` (`codex app-server`) and `museLive()`
+  (`muse serve`) with `AgentRun.steer()` and `AgentTask.onApproval`; `liveAgent()` and
+  `RpcPeer` for custom live drivers; `approval-resolved` event.
+- `AgentTask.mcpServers` (HTTP and stdio) for `claude`, `codex` and `codexLive`; header
+  secrets stay out of argv. Drivers can set up and clean up per task via `prepare`.
+- `scrubEnv`, `withoutProviderCredentials` and `PROVIDER_CREDENTIAL_VARS` for child
+  environments; `runWithVerify` verify-and-repair loop.
+- Drivers `gemini()`, `cursor()` and `opencode()`; `hostedAgent()` adapts a
+  `HostedAgentProvider` (start / poll / send / cancel) to `CodingAgent`.
+- Driver `copilot()` for GitHub Copilot CLI (`--output-format json`), with MCP servers via
+  `--additional-mcp-config` and `allowTools` / `denyTools` permission patterns.
+
+### Notes
+
+- The core `genaicode` entry is unchanged and still spawns nothing.
+
+## 2.2.0 — 2026-07-26
+
+### Added
+
+- Portable `responseFormat` on `GenerationRequest` / request builders
+  (`text` | `json` | `json_schema`), mapped by OpenAI and Google adapters
+- Portable `thinking` controls (`false` | `{ budgetTokens?, level? }`), mapped by
+  Anthropic (budget / disable) and Google (budget or level)
+- `.json()` sets `responseFormat: { type: 'json' }` when no format was already chosen
+- Capability flags: `jsonResponse`, `thinking`
+
+### Notes
+
+- Additive only; provider `generationConfig` / Anthropic `thinking` factory options still
+  work as escape hatches for vendor-only knobs.
+- On Google, `thinking: false` and `budgetTokens: 0` map to `thinkingLevel: MINIMAL`
+  (Gemini 3 rejects `thinkingBudget: 0`). JSON `responseFormat` also defaults Google
+  thinking to `MINIMAL` when unset, so small token budgets are not spent only on thoughts.
+- Provider E2E covers JSON response format and thinking knobs when credentials are set.
+
 ## 2.1.0 — 2026-07-25
 
 Publishes the Phase 3–4 work already on `master`. npm `2.0.0` shipped the 2.0

package/README.md

@@ -12,38 +12,44 @@ GenAIcode is a small TypeScript toolkit for using LLMs in backend code.
 
 It sits between raw provider SDKs and full agent frameworks: one prompt representation,
 thin provider adapters, a convenient request API, and lightweight conversation chains.
-It does not inspect repositories, execute shell commands, edit files, or run an agent UI.
+The core does not inspect repositories, execute shell commands, edit files, or run an agent UI.
+The opt-in [`genaicode/agents`](#coding-agents) subpath drives the coding-agent CLIs you
+already have (Claude Code, Codex, GitHub Copilot CLI, Cursor, Gemini CLI, opencode, Muse)
+behind one task and event API, so you can orchestrate them from backend code.
 
-## GenAIcode 2.0 is a new direction
+**Like jQuery**, the common case starts with one small function and becomes more specific
+through chaining—configure a request, follow up across multiple prompts, and keep history
+portable without adopting a full agent framework.
 
-GenAIcode 1.x was a coding agent. Version 2.0 deliberately replaces that product with a
-small backend LLM toolkit: a jQuery-like layer for portable prompts, provider adapters,
-conversation chains, and plugins.
+GenAIcode 1.x was a coding agent; see [Migration from 1.x](#migration-from-1x) if you need
+the old product or the 2.0 scope decisions.
 
-The coding-agent CLI, browser UI, repository tools, shell execution, and agent
-orchestration are not deprecated compatibility features; they have been removed from
-2.0. The GenAIcode name, `PromptItem` model, provider converters, and extensibility
-continue here in a smaller and more focused form.
-
-The original coding agent remains available from the preserved
-[`1.x` branch](https://github.com/gtanczyk/genaicode/tree/1.x) and the 1.x npm releases:
+## Install
 
 ```bash
-npx genaicode@1
+npm install genaicode
 ```
 
-Running `npx genaicode` with version 2.x prints this migration guidance instead of
-starting the old agent.
+Node.js 20 or newer is required.
 
-See [the pivot plan](docs/pivot.md) for the full scope and migration decisions.
+## Why this vs a raw SDK
 
-## Install
+Provider SDKs are the right tool when you call one vendor and own every request shape
+yourself. The cost shows up when the same backend needs a second provider, a test double,
+or shared policy (timeouts, JSON parsing, rate limits, fallback) without copying glue.
 
-```bash
-npm install genaicode
-```
+GenAIcode is that thin shared layer:
 
-Node.js 20 or newer is required.
+- One portable prompt/tool IR (`PromptItem`) instead of OpenAI messages vs Anthropic
+  blocks vs Gemini contents.
+- One request API (`.text()`, `.json()`, `.stream()`, chains) over those adapters.
+- A tiny `ModelProvider` seam so tests and custom gateways do not mock vendor HTTP.
+- Opt-in middleware and retry helpers—no hidden tool runners, no silent retries, no
+  agent loop.
+
+If you are happy importing one SDK and never swapping models or providers, stay on the
+SDK. If you want the call site to look the same while the edge stays replaceable, use
+GenAIcode.
 
 ## A prompt in three lines
 
@@ -55,8 +61,9 @@ const ai = genaicode(openai({ model: 'your-model-name' }));
 const answer = await ai('Explain why the sky is blue in two sentences.').text();
 ```
 
-The client is callable on purpose. Like jQuery, the common case starts with one small
-function and becomes more specific through chaining:
+The client is callable on purpose. Configuration is ordinary method chaining—system
+instructions, temperature, token limits, and more—without a separate options object or
+framework setup:
 
 ```ts
 const result = await ai('Create a release note from these commits')
@@ -66,12 +73,68 @@ const result = await ai('Create a release note from these commits')
   .text();
 ```
 
-Builders are immutable, so a configured base request can be safely reused.
+Builders are immutable, so a configured base request can be safely reused:
+
+```ts
+const releaseNote = ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2);
+
+const short = await releaseNote.maxOutputTokens(200).text();
+const long = await releaseNote.maxOutputTokens(800).text();
+```
+
+## Coding agents
+
+`genaicode/agents` turns the coding-agent CLIs installed on a machine into one API. Give
+any of them a task (a prompt and a working directory) and get back the same event stream
+and result, whichever agent does the work. It is how you script, compare, or chain coding
+agents from a job, a bot, or a CI step without writing a parser per vendor.
+
+```ts
+import { claude, codex, copilot, cursor, detectAgents } from 'genaicode/agents';
+
+const [found] = detectAgents([claude(), codex(), copilot(), cursor()]).filter(({ path }) => path);
+if (!found) throw new Error('No coding agent installed.');
+
+const run = found.agent.run({ prompt: 'Add a unit test for parseDate', cwd: '/path/to/repo', timeoutMs: 20 * 60_000 });
+for await (const event of run) {
+  if (event.type === 'tool-start') console.log('⚙', event.name);
+  if (event.type === 'file-change') console.log('edited', event.paths.join(', '));
+}
+const result = await run.result; // { status, ok, text, sessionId, usage, error, ... }
+```
+
+| Agent            | Driver                        | Extras                                     |
+| ---------------- | ----------------------------- | ------------------------------------------ |
+| Claude Code      | `claude()`                    | MCP servers, max turns, effort, cost       |
+| Codex            | `codex()`, `codexLive()`      | MCP servers; live: `steer()`, approvals    |
+| GitHub Copilot   | `copilot()`                   | MCP servers, allow/deny tool patterns      |
+| Cursor           | `cursor()`                    | streamed text deltas                       |
+| Gemini CLI       | `gemini()`                    | approval mode                              |
+| opencode         | `opencode()`                  | `provider/model` ids, variants             |
+| Muse             | `muse()`, `museLive()`        | max turns; live: `steer()`                 |
+| Your own CLI/API | `cliAgent()`, `hostedAgent()` | plug in any JSON-lines CLI or hosted agent |
+
+On top of the drivers:
+
+- **Steer a running task** with `run.steer(text)`, and answer permission prompts with
+  `onApproval` (live drivers).
+- **Attach MCP servers per task** with `mcpServers`. Header secrets stay out of argv.
+- **Verify and repair**: `runWithVerify` runs your check (tests, lint) after the agent and
+  sends failures back for another attempt.
+- **Keep credentials apart**: `withoutProviderCredentials()` strips your app's LLM API keys
+  from the agent's environment, so it bills its own login.
+
+Importing `genaicode` never spawns anything; only `genaicode/agents` does. The agent uses
+its own credentials, billing, and permission settings. GenAIcode does not sandbox it,
+choose a model, or retry it. See [docs/agents.md](docs/agents.md) for events, options per
+driver, and writing your own driver.
 
 ## Chaining prompts
 
 A chain remembers successful user and assistant turns. Each new prompt sees the complete
-history:
+history, so multi-step work stays in ordinary application code:
 
 ```ts
 import { system } from 'genaicode';
@@ -145,6 +208,37 @@ const value = await ai('Return {"count": 3}.').json({
 });
 ```
 
+Calling `.json()` also sets `responseFormat: { type: 'json' }` on the request when you have
+not already chosen a format, so providers that support JSON mode (OpenAI, Gemini/Vertex)
+are asked for JSON rather than free text.
+
+## Response format and thinking
+
+Portable request fields cover the two knobs backends usually poke through provider-specific
+config:
+
+```ts
+const verdict = await ai(promptText)
+  .responseFormat({ type: 'json' })
+  .thinking({ level: 'minimal' }) // or { budgetTokens: 0 } / false to disable
+  .temperature(0)
+  .json((value) => VerdictSchema.parse(value));
+```
+
+- `responseFormat`: `{ type: 'text' | 'json' }` or
+  `{ type: 'json_schema', name, schema, strict? }`.
+- `thinking`: `false` to disable, or `{ budgetTokens?, level? }` (`minimal` |
+  `low` | `medium` | `high`). Prefer one of budget or level — some providers reject both.
+  On Google/Gemini, `false` and `budgetTokens: 0` map to `thinkingLevel: MINIMAL`
+  (or `LOW` for models like Gemini 3.7 and Gemini 3 Pro where `MINIMAL` is unsupported)
+  because Gemini 3 rejects `thinkingBudget: 0`. JSON `responseFormat` without an
+  explicit `thinking` setting or provider `generationConfig.thinkingConfig` default also
+  defaults Google thinking to `MINIMAL` (or `LOW` on Gemini 3.7 / Pro).
+
+Providers map what they support and ignore the rest. `ProviderCapabilities.jsonResponse`
+and `ProviderCapabilities.thinking` advertise support. Vendor-specific escapes such as
+Vertex `generationConfig` remain available for anything not covered here.
+
 ## PromptItem: the portable prompt IR
 
 `PromptItem` is GenAIcode's provider-neutral intermediate representation:
@@ -226,13 +320,7 @@ Hook-style plugins remain the extension point. Built-in helpers cover common bac
 needs without restoring a global registry:
 
 ```ts
-import {
-  cachePlugin,
-  fallbackPlugin,
-  genaicode,
-  rateLimitPlugin,
-  timingPlugin,
-} from 'genaicode';
+import { cachePlugin, fallbackPlugin, genaicode, rateLimitPlugin, timingPlugin } from 'genaicode';
 import { anthropic, openai } from 'genaicode/providers';
 
 const ai = genaicode(openai({ model: 'your-model-name' }), {
@@ -341,6 +429,9 @@ are set:
 - Anthropic: `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`
 - Gemini: `GEMINI_API_KEY`, `GEMINI_MODEL`
 
+Beyond the smoke call, E2E also covers portable `responseFormat: { type: 'json' }`
+(OpenAI, Gemini) and `thinking` (Anthropic disable; Gemini disable / `level: 'minimal'`).
+
 CI/CD is configured in `.github/workflows/provider-e2e.yaml`. Each provider runs in its own
 job and only starts when both required secrets are configured in GitHub Actions.
 
@@ -397,13 +488,37 @@ Framework-shaped examples live under `examples/` (`http-handler`, `queue-worker`
 
 ## Design boundaries
 
-- Backend library, not a coding agent.
+- Backend library, not a coding agent. `genaicode/agents` drives external agent CLIs; it
+  adds no agent loop, prompts, or repository tools of its own.
 - Provider-neutral core with no global configuration.
 - Explicit models and credentials; environment variables are only provider defaults.
 - Immutable request builders.
 - Conversation history is explicit; loops remain ordinary application code.
 - No hidden tool execution or hidden retries.
 - Third-party providers and middleware use stable TypeScript contracts.
-- Provider SDKs stay behind the `genaicode/providers` subpath.
+- Provider SDKs stay behind the `genaicode/providers` subpath; process spawning stays
+  behind `genaicode/agents`.
+
+## Migration from 1.x
+
+GenAIcode 1.x was a coding agent. Version 2.0 deliberately replaces that product with a
+small backend LLM toolkit: a jQuery-like layer for portable prompts, provider adapters,
+conversation chains, and plugins.
+
+The coding-agent CLI, browser UI, repository tools, shell execution, and agent
+orchestration are not deprecated compatibility features; they have been removed from
+2.0. The GenAIcode name, `PromptItem` model, provider converters, and extensibility
+continue here in a smaller and more focused form.
+
+The original coding agent remains available from the preserved
+[`1.x` branch](https://github.com/gtanczyk/genaicode/tree/1.x) and the 1.x npm releases:
+
+```bash
+npx genaicode@1
+```
+
+Running `npx genaicode` with version 2.x prints this migration guidance instead of
+starting the old agent.
 
-See [the pivot plan](docs/pivot.md) for product scope, migration decisions, and the roadmap.
+See [the pivot plan](docs/pivot.md) for the full scope, migration decisions, and the
+roadmap.

package/dist/agents/cli-agent.d.ts

@@ -0,0 +1,28 @@
+import { type PreparedRun } from './prepare.js';
+import { type AgentOutcome } from './runtime.js';
+import type { AgentCapabilities, AgentEvent, AgentTask, CodingAgent } from './types.js';
+export type { AgentOutcome } from './runtime.js';
+/** Per-run decoder for one vendor's JSON event stream. */
+export interface AgentOutputParser {
+    /** Map one parsed stdout JSON value to zero or more events. */
+    event(value: unknown): AgentEvent[];
+    /** The terminal verdict the agent itself reported, if it reported one. */
+    outcome?(): AgentOutcome | undefined;
+}
+export interface CliAgentDefinition {
+    name: string;
+    command: string;
+    capabilities?: AgentCapabilities;
+    /** Full argument list for a task, prompt included. */
+    args(task: AgentTask): string[];
+    /** Replaces `args` when a task needs setup: extra env, temp files to clean up. */
+    prepare?(task: AgentTask): PreparedRun;
+    createParser(): AgentOutputParser;
+    /** Adjust the child environment (the caller's `task.env` or `process.env`). */
+    env?(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+}
+/**
+ * Build a `CodingAgent` from a headless CLI: spawn, decode its JSON lines, and
+ * fold them into an `AgentResult`. Drivers such as `claude()` are thin definitions.
+ */
+export declare function cliAgent(definition: CliAgentDefinition): CodingAgent;

package/dist/agents/cli-agent.js

@@ -0,0 +1,57 @@
+import { planSpawn } from './prepare.js';
+import { startProcess } from './process.js';
+import { invalidCwd, RunRecorder } from './runtime.js';
+/**
+ * Build a `CodingAgent` from a headless CLI: spawn, decode its JSON lines, and
+ * fold them into an `AgentResult`. Drivers such as `claude()` are thin definitions.
+ */
+export function cliAgent(definition) {
+    return {
+        name: definition.name,
+        command: definition.command,
+        capabilities: definition.capabilities ?? {},
+        run: (task) => runCliAgent(definition, task),
+    };
+}
+function runCliAgent(definition, task) {
+    const recorder = new RunRecorder(definition.name, definition.command);
+    const iterate = () => recorder.events.iterate();
+    const plan = planSpawn(definition, task, invalidCwd(task.cwd));
+    if (!plan.ok) {
+        const result = recorder.finish({ exitCode: null, signal: null, reason: 'spawn-error', error: new Error(plan.error) }, undefined);
+        return { result: Promise.resolve(result), abort() { }, [Symbol.asyncIterator]: iterate };
+    }
+    const parser = definition.createParser();
+    const handle = startProcess({
+        command: definition.command,
+        args: plan.args,
+        cwd: task.cwd,
+        env: plan.env,
+        timeoutMs: task.timeoutMs,
+        signal: task.signal,
+        onLine(line) {
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                recorder.emit({ type: 'raw', line });
+                return;
+            }
+            for (const event of parser.event(value))
+                recorder.emit(event);
+        },
+        onStderr: (text) => recorder.emit({ type: 'stderr', text }),
+    });
+    // A consumer that falls behind pauses the agent instead of buffering its output without bound.
+    recorder.events.onPressure = (paused) => (paused ? handle.pause() : handle.resume());
+    return {
+        result: handle.exit.then((exit) => {
+            plan.cleanup();
+            return recorder.finish(exit, parser.outcome?.());
+        }),
+        abort: handle.kill,
+        [Symbol.asyncIterator]: iterate,
+    };
+}
+//# sourceMappingURL=cli-agent.js.map

package/dist/agents/cli-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-agent.js","sourceRoot":"","sources":["../../src/agents/cli-agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/discovery.d.ts

@@ -0,0 +1,10 @@
+import type { CodingAgent } from './types.js';
+/** Resolve an executable the way a shell would: absolute path, or the first match on PATH. */
+export declare function findExecutable(command: string, env?: NodeJS.ProcessEnv): string | null;
+export interface AgentAvailability {
+    agent: CodingAgent;
+    /** Resolved executable, or null when the agent's command is not installed. */
+    path: string | null;
+}
+/** Report which agents have their CLI installed. Presence only; login and flags are the agent's concern. */
+export declare function detectAgents(agents: readonly CodingAgent[], env?: NodeJS.ProcessEnv): AgentAvailability[];

package/dist/agents/discovery.js

@@ -0,0 +1,31 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** Resolve an executable the way a shell would: absolute path, or the first match on PATH. */
+export function findExecutable(command, env = process.env) {
+    const windows = process.platform === 'win32';
+    const extensions = windows ? ['', ...(env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';')] : [''];
+    const candidates = isAbsolute(command)
+        ? extensions.map((extension) => command + extension)
+        : (env.PATH ?? env.Path ?? '')
+            .split(delimiter)
+            .filter(Boolean)
+            .flatMap((dir) => extensions.map((extension) => join(dir, command + extension)));
+    for (const candidate of candidates) {
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            if (!windows)
+                accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** Report which agents have their CLI installed. Presence only; login and flags are the agent's concern. */
+export function detectAgents(agents, env = process.env) {
+    return agents.map((agent) => ({ agent, path: findExecutable(agent.command, env) }));
+}
+//# sourceMappingURL=discovery.js.map

package/dist/agents/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/agents/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGxD,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,MAAyB,OAAO,CAAC,GAAG;IAClF,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,qBAAqB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/F,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC;QACpC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,GAAG,SAAS,CAAC;QACpD,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;aACzB,KAAK,CAAC,SAAS,CAAC;aAChB,MAAM,CAAC,OAAO,CAAC;aACf,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACvF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE;gBAAE,SAAS;YAC5C,IAAI,CAAC,OAAO;gBAAE,UAAU,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD,4GAA4G;AAC5G,MAAM,UAAU,YAAY,CAC1B,MAA8B,EAC9B,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACtF,CAAC"}

package/dist/agents/drivers/claude.d.ts

@@ -0,0 +1,25 @@
+import { type AgentOutputParser } from '../cli-agent.js';
+import type { AgentTask, CodingAgent, McpServer } from '../types.js';
+export type ClaudePermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'dontAsk' | 'manual' | 'plan' | (string & Record<never, never>);
+export interface ClaudeAgentOptions {
+    /** Executable name or path. Default `claude`. */
+    command?: string;
+    /** Default `acceptEdits`: file edits run unattended, other tools follow Claude Code settings. */
+    permissionMode?: ClaudePermissionMode;
+    /** Passed as `--allowedTools`. */
+    allowedTools?: readonly string[];
+    /** Passed as `--disallowedTools`. */
+    disallowedTools?: readonly string[];
+    /** With `task.mcpServers`: ignore MCP servers from the user's own Claude Code config. Default false. */
+    strictMcpConfig?: boolean;
+    /** With `task.mcpServers`: pre-allow every tool of those servers. Default true (headless runs cannot ask). */
+    allowMcpTools?: boolean;
+}
+/** Claude Code in print mode (`claude -p --output-format stream-json`). */
+export declare function claude(options?: ClaudeAgentOptions): CodingAgent;
+/** The `--mcp-config` document for a set of servers. */
+export declare function claudeMcpConfig(servers: readonly McpServer[]): {
+    mcpServers: Record<string, unknown>;
+};
+export declare function claudeArgs(task: AgentTask, options?: ClaudeAgentOptions, mcpConfigPath?: string): string[];
+export declare function createClaudeParser(): AgentOutputParser;

package/dist/agents/drivers/claude.js

@@ -0,0 +1,184 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { cliAgent } from '../cli-agent.js';
+import { isHttpServer } from '../prepare.js';
+import { isObject, numberField, positionalPrompt, stringField } from './json.js';
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+/** Claude Code in print mode (`claude -p --output-format stream-json`). */
+export function claude(options = {}) {
+    return cliAgent({
+        name: 'claude',
+        command: options.command ?? 'claude',
+        capabilities: { effort: ['low', 'medium', 'high', 'xhigh', 'max'], maxTurns: true, usage: true, mcp: true },
+        args: (task) => claudeArgs(task, options),
+        prepare: (task) => prepareClaude(task, options),
+        createParser: createClaudeParser,
+    });
+}
+/** Write the task's MCP servers to a private temp file, so header secrets stay out of argv. */
+function prepareClaude(task, options) {
+    if (!task.mcpServers?.length)
+        return { args: claudeArgs(task, options) };
+    const dir = mkdtempSync(join(tmpdir(), 'genaicode-claude-mcp-'));
+    const file = join(dir, 'mcp.json');
+    writeFileSync(file, JSON.stringify(claudeMcpConfig(task.mcpServers)), { mode: 0o600 });
+    return {
+        args: claudeArgs(task, options, file),
+        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}
+/** The `--mcp-config` document for a set of servers. */
+export function claudeMcpConfig(servers) {
+    const mcpServers = {};
+    for (const server of servers) {
+        mcpServers[server.name] = isHttpServer(server)
+            ? { type: 'http', url: server.url, ...(server.headers ? { headers: server.headers } : {}) }
+            : {
+                command: server.command,
+                args: [...(server.args ?? [])],
+                ...(server.env ? { env: server.env } : {}),
+            };
+    }
+    return { mcpServers };
+}
+export function claudeArgs(task, options = {}, mcpConfigPath) {
+    const args = ['-p', '--verbose'];
+    // Multi-value flags come first: a single-value flag must follow them before the prompt.
+    if (mcpConfigPath)
+        args.push('--mcp-config', mcpConfigPath);
+    if (mcpConfigPath && options.strictMcpConfig)
+        args.push('--strict-mcp-config');
+    const allowed = [
+        ...(options.allowedTools ?? []),
+        ...(mcpConfigPath && (options.allowMcpTools ?? true) ? (task.mcpServers ?? []).map((s) => `mcp__${s.name}`) : []),
+    ];
+    if (allowed.length)
+        args.push('--allowedTools', allowed.join(','));
+    if (options.disallowedTools?.length)
+        args.push('--disallowedTools', options.disallowedTools.join(','));
+    args.push('--output-format', 'stream-json', '--permission-mode', options.permissionMode ?? 'acceptEdits');
+    if (task.model)
+        args.push('--model', task.model);
+    if (task.effort)
+        args.push('--effort', task.effort);
+    if (task.maxTurns !== undefined)
+        args.push('--max-turns', String(task.maxTurns));
+    if (task.extraArgs)
+        args.push(...task.extraArgs);
+    return [...args, ...positionalPrompt(task.prompt)];
+}
+export function createClaudeParser() {
+    const toolNames = new Map();
+    let outcome;
+    let sessionSent = false;
+    let lastMessage;
+    return {
+        outcome: () => outcome,
+        event(value) {
+            if (!isObject(value))
+                return [];
+            const events = [];
+            const sessionId = stringField(value, 'session_id');
+            if (sessionId && !sessionSent) {
+                sessionSent = true;
+                events.push({ type: 'session', sessionId, ...modelOf(value) });
+            }
+            switch (value.type) {
+                case 'assistant':
+                    for (const block of contentBlocks(value.message)) {
+                        if (block.type === 'text' && typeof block.text === 'string' && block.text.trim()) {
+                            lastMessage = block.text;
+                            events.push({ type: 'message', text: block.text });
+                        }
+                        else if (block.type === 'tool_use' && typeof block.name === 'string') {
+                            const id = typeof block.id === 'string' ? block.id : undefined;
+                            if (id)
+                                toolNames.set(id, block.name);
+                            events.push({ type: 'tool-start', ...(id ? { id } : {}), name: block.name, input: block.input });
+                            const path = stringField(block.input, 'file_path') ?? stringField(block.input, 'notebook_path');
+                            if (EDIT_TOOLS.has(block.name) && path)
+                                events.push({ type: 'file-change', paths: [path] });
+                        }
+                    }
+                    break;
+                case 'user':
+                    for (const block of contentBlocks(value.message)) {
+                        if (block.type !== 'tool_result')
+                            continue;
+                        const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+                        const name = id ? toolNames.get(id) : undefined;
+                        const output = toolOutput(block.content);
+                        events.push({
+                            type: 'tool-end',
+                            ...(id ? { id } : {}),
+                            ...(name ? { name } : {}),
+                            isError: block.is_error === true,
+                            ...(output !== undefined ? { output } : {}),
+                        });
+                    }
+                    break;
+                case 'stream_event': {
+                    const delta = isObject(value.event) ? value.event.delta : undefined;
+                    const text = stringField(delta, 'text');
+                    if (stringField(delta, 'type') === 'text_delta' && text)
+                        events.push({ type: 'text-delta', text });
+                    break;
+                }
+                case 'result': {
+                    const failed = value.is_error === true || (value.subtype !== undefined && value.subtype !== 'success');
+                    const text = stringField(value, 'result');
+                    outcome = failed
+                        ? { ok: false, error: text || `Claude stopped: ${String(value.subtype ?? 'error')}.` }
+                        : { ok: true };
+                    const usage = value.usage;
+                    if (isObject(usage)) {
+                        const inputTokens = numberField(usage, 'input_tokens');
+                        const outputTokens = numberField(usage, 'output_tokens');
+                        const cachedInputTokens = numberField(usage, 'cache_read_input_tokens');
+                        const costUsd = numberField(value, 'total_cost_usd');
+                        events.push({
+                            type: 'usage',
+                            usage: {
+                                ...(inputTokens !== undefined ? { inputTokens } : {}),
+                                ...(outputTokens !== undefined ? { outputTokens } : {}),
+                                ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+                                ...(inputTokens !== undefined && outputTokens !== undefined
+                                    ? { totalTokens: inputTokens + outputTokens }
+                                    : {}),
+                            },
+                            ...(costUsd !== undefined ? { costUsd } : {}),
+                        });
+                    }
+                    // The result repeats the last assistant message; only surface it when it differs.
+                    if (!failed && text && text !== lastMessage)
+                        events.push({ type: 'message', text });
+                    if (failed)
+                        events.push({ type: 'error', message: outcome.error });
+                    break;
+                }
+            }
+            return events;
+        },
+    };
+}
+function contentBlocks(message) {
+    const content = isObject(message) ? message.content : undefined;
+    return Array.isArray(content) ? content.filter(isObject) : [];
+}
+function modelOf(value) {
+    const model = stringField(value, 'model');
+    return model ? { model } : {};
+}
+function toolOutput(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content
+        .map((part) => stringField(part, 'text'))
+        .filter((part) => part !== undefined)
+        .join('\n');
+    return text || undefined;
+}
+//# sourceMappingURL=claude.js.map