coding-agents-sdk 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,242 @@
+# coding-agents-sdk
+
+This is a coding agent orchestration library.
+
+## Install
+
+```bash
+bun add coding-agents-sdk
+```
+
+If you use an SDK adapter or the `e2b` container provider, install that optional peer too.
+
+```bash
+# for claude-code-sdk
+bun add @anthropic-ai/claude-agent-sdk
+
+# for codex-sdk
+bun add @openai/codex-sdk
+
+# for createContainer({ type: "e2b", ... })
+bun add e2b
+```
+
+## Runtime setup
+
+Before you call `await createAgent(...)`, make sure the runtime for that adapter is available.
+
+- `claude-code-cli` runs Claude Code CLI.
+- `claude-code-sdk` uses `@anthropic-ai/claude-agent-sdk` and launches Claude Code locally.
+- `codex-cli` runs Codex CLI.
+- `codex-sdk` uses `@openai/codex-sdk` and launches Codex locally.
+- `gemini-cli` runs Gemini CLI.
+
+SDK adapters and the `e2b` container provider are optional peer dependencies. Install only the ones you use.
+
+If one is missing, awaiting `createAgent()` or `createContainer()` surfaces an error that tells you which package to install.
+
+Set `cwd` when the agent should run somewhere other than the current working directory.
+
+Use `agent.capabilities` when you need to branch on features at runtime.
+
+## Quick start
+
+```ts
+import { createAgent } from "coding-agents-sdk";
+
+await using agent = await createAgent("claude-code-cli");
+
+const result = await agent.run({
+  input: "Read package.json and tell me what this project does.",
+});
+
+if (result.status !== "completed") {
+  throw new Error(result.error.message);
+}
+
+console.log(result.text);
+```
+
+Replace `"claude-code-cli"` with the adapter you want to use.
+Unless noted otherwise, the rest of the snippets assume the same `agent` shape.
+
+## Run results
+
+`run()` returns a `RunResult` with `status: "completed" | "failed" | "cancelled"`.
+
+```ts
+const result = await agent.run({
+  input: "Review the last commit.",
+});
+
+switch (result.status) {
+  case "completed":
+    console.log(result.text);
+    break;
+  case "failed":
+    console.error(result.error.kind, result.error.message);
+    break;
+  case "cancelled":
+    console.error(result.cancelReason, result.error.message);
+    break;
+}
+```
+
+Notes:
+
+- `runOrThrow()` turns non-completed runs into `AgentRunError`
+- `stop()`, `wait()`, `reset()`, and `dispose()` are available on every agent
+
+TypeScript infers the completed-result shape from your request:
+
+- Zod schema: `result.output` is fully typed
+- raw JSON Schema: `result.output` is `unknown`
+- no `schema`: use `result.text`; completed results do not include `output`
+- `runOrThrow()` follows the same inference, but only returns the completed variant
+
+## Input
+
+Most calls just use a string. If you need richer input, pass parts instead.
+
+Image input is currently supported only by `codex-sdk`.
+
+```ts
+await using agent = await createAgent("codex-sdk");
+
+await agent.run({
+  input: [
+    { type: "text", text: "Describe this image." },
+    { type: "image", path: "./ui.png" },
+  ],
+});
+```
+
+## Structured output
+
+Pass `schema` when you want structured output.
+
+If you want typed output, pass a Zod schema.
+If you pass raw JSON Schema, `result.output` is `unknown`.
+If you do not pass a schema, use `result.text`.
+
+```ts
+import { z } from "zod/v4";
+
+const result = await agent.run({
+  input: "Read package.json and return the package name and whether it has a test script.",
+  schema: z
+    .object({
+      name: z.string(),
+      hasTestScript: z.boolean(),
+    })
+    .strict(),
+});
+
+if (result.status === "completed") {
+  console.log(result.output);
+}
+```
+
+If you want to pass Zod schemas, depend on `zod` in your app.
+
+`schema` accepts a raw JSON Schema object or a Zod schema. This wrapper validates only the Zod path. `gemini-cli` does not support structured output.
+
+If you need to name these shapes in your own helpers, import `RunRequest`, `JsonSchemaRunRequest`, `ZodRunRequest`, `RunResult`, or `CompletedRunResult` from the package.
+
+## Sessions
+
+One agent instance keeps one conversation going. Reuse the same instance when you want the next turn to continue the same session.
+
+```ts
+await agent.run({
+  input: "Remember this word: pineapple. Reply with only 'ok'.",
+});
+
+const result = await agent.run({
+  input: "What word did I ask you to remember?",
+});
+```
+
+Useful bits:
+
+- `agent.sessionId` is set once a session exists
+- pass `sessionId` to `await createAgent(type, { sessionId })` to resume one explicitly
+- `reset()` forgets the stored session
+- Claude adapters support `fork()`
+
+## Events
+
+Use `onEvent()` to subscribe to the normalized event stream.
+
+```ts
+const unsubscribe = agent.onEvent((event) => {
+  if (event.type === "tool-call") {
+    console.log(event.toolName);
+  }
+});
+
+await agent.run({
+  input: "Explain the package layout.",
+});
+
+unsubscribe();
+```
+
+All adapters emit `session-start` and `session-end`. Depending on the backend, you may also see `message`, `reasoning`, `tool-call`, `tool-result`, and `stderr`.
+
+## MCP
+
+MCP tool calls can show up in the event stream when the underlying runtime supports them.
+
+This wrapper exposes MCP configuration directly on:
+
+- `claude-code-cli`: `mcpConfig`, `mcpServers`
+- `claude-code-sdk`: `mcpServers`
+- `codex-cli`: `mcpConfig`, `mcpServers`
+
+For `codex-sdk` and `gemini-cli`, use the runtime's own MCP setup. This wrapper does not add separate MCP config options for them.
+
+## Containers
+
+Containers are supported on the CLI adapters: `claude-code-cli`, `codex-cli`, and `gemini-cli`.
+`docker` and `podman` do not need extra package dependencies. `e2b` requires the optional `e2b` peer dependency.
+
+```ts
+import { createAgent, createContainer } from "coding-agents-sdk";
+
+await using container = await createContainer({
+  type: "docker",
+  workdir: "/workspace",
+  image: "my-agent-image",
+  // or instead of image:
+  // build: {
+  //   content: [
+  //     "FROM ubuntu:24.04",
+  //     "RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*",
+  //     "RUN useradd -m -s /bin/bash agent",
+  //     "USER agent",
+  //     "RUN curl -fsSL https://claude.ai/install.sh | bash",
+  //     'ENV PATH="/home/agent/.local/bin:${PATH}"',
+  //     "WORKDIR /workspace",
+  //   ].join("\n"),
+  // },
+  mounts: [{ source: "/absolute/path/to/project", target: "/workspace" }],
+});
+
+await using agent = await createAgent("claude-code-cli", {
+  container,
+  permissionMode: "bypassPermissions",
+});
+
+const result = await agent.run({
+  input: "Run the tests and fix the failing test.",
+});
+
+if (result.status === "completed") {
+  console.log(result.text);
+}
+```
+
+Your image needs the runtime for the adapter you picked available inside the container.
+
+If you omit `cwd`, the agent uses `container.workdir`. The container is started automatically on the first run. Use `snapshotWorkdir()`, `diffWorkdir()`, and `releaseWorkdirSnapshot()` when you need a reliable before/after file diff.

package/dist/Agent-D8WkUilj.mjs

@@ -0,0 +1,262 @@
+import { t as formatError } from "./util-B4RQZkKr.mjs";
+import { a as buildBaseProcessEnv, i as hasMeaningfulEvent, n as AgentCore, o as createAgentEvent, t as classifyRunError } from "./classify-error-pL6jeu4T.mjs";
+import { t as DEFAULT_SPAWNER } from "./spawner-Bw9UBEGX.mjs";
+import { createWriteStream, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/core/process/read-lines.ts
+async function* readDecodedLines(stream) {
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for await (const chunk of stream) {
+		const text = decoder.decode(chunk, { stream: true });
+		buffer += text;
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed) yield trimmed;
+		}
+	}
+	const tail = decoder.decode();
+	if (tail) buffer += tail;
+	const remaining = buffer.trim();
+	if (remaining) yield remaining;
+}
+//#endregion
+//#region src/core/agent/Agent.ts
+const SIGKILL_TIMEOUT_MS = 5e3;
+const rejectedMessage = (result) => {
+	return result.status === "rejected" ? formatError(result.reason) : void 0;
+};
+const resolveFatalError = (run, settled) => {
+	if (run.stopReason) return void 0;
+	const stdoutError = rejectedMessage(settled.stdoutResult);
+	if (stdoutError) return {
+		kind: "process",
+		message: stdoutError
+	};
+	const stderrError = rejectedMessage(settled.stderrResult);
+	if (stderrError) return {
+		kind: "process",
+		message: stderrError
+	};
+	const spawnError = rejectedMessage(settled.processResult);
+	if (spawnError) return {
+		kind: "spawn",
+		message: spawnError
+	};
+	if (!run.status && !run.error) {
+		const processResult = run.processResult;
+		const stderrText = run.stderrLines.join("\n");
+		if (processResult && processResult.exitCode !== null && processResult.exitCode !== 0) return {
+			kind: "process",
+			message: stderrText || `Process exited with code ${processResult.exitCode}.`
+		};
+		if (!hasMeaningfulEvent(run) && run.stderrLines.length > 0) return {
+			kind: "process",
+			message: stderrText
+		};
+	}
+};
+const classifyAgentRuntimeError = (error) => {
+	const classified = classifyRunError(error);
+	return classified.kind === "provider" ? {
+		kind: "process",
+		message: classified.message
+	} : classified;
+};
+var Agent = class extends AgentCore {
+	spawner;
+	defaults;
+	containerRef;
+	autoStartContainer;
+	autoStopContainer;
+	containerStopPromise;
+	logStream;
+	sigkillTimer;
+	constructor(options) {
+		super({
+			type: options.type,
+			capabilities: options.capabilities,
+			sessionId: options.defaults?.sessionId,
+			onEvent: options.onEvent
+		});
+		this.spawner = options.spawner ?? DEFAULT_SPAWNER;
+		this.defaults = options.defaults ?? {};
+		this.containerRef = options.container;
+		this.autoStartContainer = options.autoStartContainer ?? true;
+		this.autoStopContainer = options.autoStopContainer ?? false;
+		if (options.logPath) this.initLogStream(options.logPath);
+	}
+	onParseError(line, error) {
+		this.appendRawLog(`[parse-error] ${formatError(error)} ${line.slice(0, 200)}`);
+	}
+	buildDefaultEnv(propagateEnv) {
+		const env = buildBaseProcessEnv({ propagateEnv });
+		env.CI = env.CI ?? "true";
+		if (this.defaults.env) Object.assign(env, this.defaults.env);
+		return env;
+	}
+	async executeRunCore(run, request) {
+		const lifecycle = this.setupRunLifecycle(run);
+		try {
+			if (lifecycle.abortedBeforeStart) return this.buildResult(run, /* @__PURE__ */ new Date());
+			try {
+				await this.onBeforeRun(run);
+				const mergedRequest = {
+					...request,
+					...run.normalizedRequest
+				};
+				const args = this.buildArgs(mergedRequest, run);
+				const env = this.buildEnv(mergedRequest, run);
+				const command = this.defaults.command?.[0] ?? "claude";
+				const commandArgs = [...this.defaults.command?.slice(1) ?? [], ...args];
+				if (run.stopReason) return this.buildResult(run, /* @__PURE__ */ new Date());
+				this.emitSessionStart(run);
+				run.process = this.spawner.spawn(command, commandArgs, {
+					cwd: run.normalizedRequest.cwd,
+					env,
+					stdio: [
+						"pipe",
+						"pipe",
+						"pipe"
+					]
+				});
+				run.process.stdin?.end();
+				const [stdoutResult, stderrResult, processResult] = await Promise.allSettled([
+					this.watchStdout(run),
+					this.watchStderr(run),
+					run.process.wait()
+				]);
+				if (processResult.status === "fulfilled") run.processResult = processResult.value;
+				const fatalError = resolveFatalError(run, {
+					stdoutResult,
+					stderrResult,
+					processResult
+				});
+				if (fatalError) run.error = fatalError;
+			} catch (error) {
+				if (!run.stopReason && !run.error) run.error = classifyAgentRuntimeError(error);
+			}
+			return this.buildResult(run, /* @__PURE__ */ new Date());
+		} finally {
+			lifecycle.cleanup();
+			if (this.sigkillTimer) {
+				clearTimeout(this.sigkillTimer);
+				this.sigkillTimer = void 0;
+			}
+			try {
+				await this.onRunFinished(run);
+			} catch (error) {
+				this.appendRawLog(`[cleanup-error] ${formatError(error)}`);
+			}
+		}
+	}
+	async watchStdout(run) {
+		const stdout = run.process?.stdout;
+		if (!stdout) return;
+		for await (const line of readDecodedLines(stdout)) {
+			this.appendLog("stdout", line);
+			this.processLine(run, line);
+		}
+	}
+	async watchStderr(run) {
+		const stderr = run.process?.stderr;
+		if (!stderr) return;
+		for await (const line of readDecodedLines(stderr)) {
+			this.appendLog("stderr", line);
+			run.stderrLines.push(line);
+			this.emit(run, createAgentEvent(run.runId, "stderr", {
+				sessionId: run.sessionId,
+				text: line
+			}));
+		}
+	}
+	processLine(run, line) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch (error) {
+			this.onParseError(line, error);
+			return;
+		}
+		let batch;
+		try {
+			batch = this.mapRawEvent(parsed, {
+				runId: run.runId,
+				requestedSessionId: run.requestedSessionId,
+				sessionId: run.sessionId,
+				schemaRequested: run.normalizedRequest.schema.kind !== "none",
+				toolCalls: run.toolCalls
+			});
+		} catch (error) {
+			this.onParseError(line, error);
+			return;
+		}
+		this.applyBatch(run, batch);
+	}
+	get runRequestDefaults() {
+		return this.defaults;
+	}
+	onHandlerError(error) {
+		this.appendRawLog(`[handler-error] ${formatError(error)}`);
+	}
+	async onDispose() {
+		const logStream = this.logStream;
+		this.logStream = void 0;
+		if (!logStream) return;
+		await new Promise((resolve) => {
+			logStream.end(resolve);
+		});
+	}
+	onStopRequested(run) {
+		run.process?.kill();
+		this.sigkillTimer = setTimeout(() => {
+			run.process?.kill("SIGKILL");
+		}, SIGKILL_TIMEOUT_MS);
+		this.sigkillTimer.unref?.();
+	}
+	onBeforeRun(_run) {
+		return this.ensureContainer();
+	}
+	async onRunFinished(_run) {
+		if (this.autoStopContainer && this.containerRef && this.containerRef.status === "running") {
+			this.containerStopPromise = this.containerRef.stop().catch((error) => {
+				this.appendRawLog(`[auto-stop-error] ${formatError(error)}`);
+			});
+			await this.containerStopPromise;
+		}
+	}
+	appendRawLog(data) {
+		if (!this.logStream) return;
+		const text = typeof data === "string" ? data : JSON.stringify(data);
+		this.logStream.write(`${text}\n`);
+	}
+	initLogStream(logPath) {
+		try {
+			mkdirSync(dirname(logPath), { recursive: true });
+			this.logStream = createWriteStream(logPath, { flags: "a" });
+			this.logStream.write(`\n--- ${(/* @__PURE__ */ new Date()).toISOString()} ---\n`);
+		} catch {
+			this.logStream = void 0;
+		}
+	}
+	appendLog(source, chunk) {
+		if (!this.logStream || !chunk) return;
+		const label = source === "stderr" ? "STDERR" : "STDOUT";
+		const ts = (/* @__PURE__ */ new Date()).toISOString();
+		for (const line of chunk.split("\n")) {
+			if (!line) continue;
+			this.logStream.write(`[${ts}] ${label} ${line}\n`);
+		}
+	}
+	async ensureContainer() {
+		if (this.containerStopPromise) {
+			await this.containerStopPromise;
+			this.containerStopPromise = void 0;
+		}
+		if (this.autoStartContainer && this.containerRef && this.containerRef.status !== "running") await this.containerRef.start();
+	}
+};
+//#endregion
+export { Agent as t };

package/dist/SdkAgent-B47mJiIE.mjs

@@ -0,0 +1,38 @@
+import { n as AgentCore, t as classifyRunError } from "./classify-error-pL6jeu4T.mjs";
+//#region src/core/agent/SdkAgent.ts
+/**
+* Base class for SDK-based agent adapters (claude-code-sdk, codex-sdk).
+* Provides the shared run lifecycle: abort/timeout wiring, session-start/end emission,
+* error classification, and cleanup. Subclasses implement only the SDK-specific iteration.
+*/
+var SdkAgent = class extends AgentCore {
+	currentAbortController;
+	/** optional cleanup called in finally block (e.g. close SDK query) */
+	cleanupSdkResources() {}
+	onStopRequested(_run) {
+		this.currentAbortController?.abort();
+	}
+	async executeRunCore(run, request) {
+		const runAbortController = new AbortController();
+		this.currentAbortController = runAbortController;
+		const lifecycle = this.setupRunLifecycle(run);
+		try {
+			if (lifecycle.abortedBeforeStart) return this.buildResult(run, /* @__PURE__ */ new Date());
+			if (run.stopReason) return this.buildResult(run, /* @__PURE__ */ new Date());
+			this.emitSessionStart(run);
+			await this.executeSdkRun(run, request, runAbortController);
+			return this.buildResult(run, /* @__PURE__ */ new Date());
+		} catch (error) {
+			if (!run.stopReason && !run.error) run.error = classifyRunError(error);
+			return this.buildResult(run, /* @__PURE__ */ new Date());
+		} finally {
+			lifecycle.cleanup();
+			try {
+				await this.cleanupSdkResources();
+			} catch {}
+			if (this.currentAbortController === runAbortController) this.currentAbortController = void 0;
+		}
+	}
+};
+//#endregion
+export { SdkAgent as t };

package/dist/adapters/claude-code-cli/index.d.mts

@@ -0,0 +1,2 @@
+import { a as ClaudeCodeCliRunOptions, c as ClaudeRateLimitEvent, d as ClaudeUserEvent, i as ClaudeCodeCliPermissionMode, l as ClaudeResultEvent, n as ClaudeCodeCliAgent, o as ClaudeAssistantEvent, r as ClaudeCodeCliAgentOptions, s as ClaudeEvent, t as createClaudeCodeCliAgent, u as ClaudeSystemEvent } from "../../index-C3ZxLAd0.mjs";
+export { ClaudeAssistantEvent, ClaudeCodeCliAgent, ClaudeCodeCliAgentOptions, ClaudeCodeCliPermissionMode, ClaudeCodeCliRunOptions, ClaudeEvent, ClaudeRateLimitEvent, ClaudeResultEvent, ClaudeSystemEvent, ClaudeUserEvent, createClaudeCodeCliAgent };