coding-agents-sdk 0.0.1 → 0.2.0

package/dist/schemas-DwD4pwJB.mjs

@@ -0,0 +1,96 @@
+import { z } from "zod/v4";
+//#region src/schemas/agent.ts
+const textContentPartSchema = z.object({
+	type: z.literal("text"),
+	text: z.string()
+});
+const imageContentPartSchema = z.object({
+	type: z.literal("image"),
+	path: z.string(),
+	mediaType: z.string().optional()
+});
+const contentPartSchema = z.discriminatedUnion("type", [textContentPartSchema, imageContentPartSchema]);
+const agentCapabilitiesSchema = z.object({
+	structuredOutput: z.boolean(),
+	sessionResume: z.boolean(),
+	imageInput: z.boolean(),
+	mcp: z.boolean(),
+	eventStreaming: z.boolean(),
+	sessionFork: z.boolean().optional()
+});
+//#endregion
+//#region src/schemas/events.ts
+const baseEventSchema = z.object({
+	id: z.string(),
+	runId: z.string(),
+	timestamp: z.date()
+});
+const sessionStartEventSchema = baseEventSchema.extend({
+	type: z.literal("session-start"),
+	requestedSessionId: z.string().optional(),
+	sessionId: z.string().optional(),
+	resumed: z.boolean()
+});
+const messageEventSchema = baseEventSchema.extend({
+	type: z.literal("message"),
+	sessionId: z.string().optional(),
+	model: z.string().nullable(),
+	role: z.enum([
+		"system",
+		"user",
+		"assistant"
+	]),
+	content: z.array(contentPartSchema),
+	text: z.string().optional()
+});
+const reasoningEventSchema = baseEventSchema.extend({
+	type: z.literal("reasoning"),
+	sessionId: z.string().optional(),
+	model: z.string().nullable(),
+	content: z.array(contentPartSchema),
+	text: z.string().optional()
+});
+const toolCallEventSchema = baseEventSchema.extend({
+	type: z.literal("tool-call"),
+	sessionId: z.string().optional(),
+	model: z.string().nullable(),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	input: z.unknown().optional()
+});
+const toolResultEventSchema = baseEventSchema.extend({
+	type: z.literal("tool-result"),
+	sessionId: z.string().optional(),
+	toolCallId: z.string(),
+	toolName: z.string().optional(),
+	input: z.unknown().optional(),
+	output: z.unknown(),
+	isError: z.boolean().optional(),
+	error: z.string().optional()
+});
+const stderrEventSchema = baseEventSchema.extend({
+	type: z.literal("stderr"),
+	sessionId: z.string().optional(),
+	text: z.string()
+});
+const sessionEndEventSchema = baseEventSchema.extend({
+	type: z.literal("session-end"),
+	sessionId: z.string().optional(),
+	status: z.enum([
+		"completed",
+		"failed",
+		"cancelled"
+	]),
+	error: z.string().optional()
+});
+const eventSchema = z.discriminatedUnion("type", [
+	sessionStartEventSchema,
+	messageEventSchema,
+	reasoningEventSchema,
+	toolCallEventSchema,
+	toolResultEventSchema,
+	stderrEventSchema,
+	sessionEndEventSchema
+]);
+//#endregion
+export { sessionEndEventSchema as a, toolCallEventSchema as c, contentPartSchema as d, imageContentPartSchema as f, reasoningEventSchema as i, toolResultEventSchema as l, eventSchema as n, sessionStartEventSchema as o, textContentPartSchema as p, messageEventSchema as r, stderrEventSchema as s, baseEventSchema as t, agentCapabilitiesSchema as u };

package/dist/spawner-Bw9UBEGX.mjs

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+//#region src/core/process/spawner.ts
+const streamToAsyncIterable = (stream) => ({ async *[Symbol.asyncIterator]() {
+	for await (const chunk of stream) {
+		if (chunk instanceof Buffer) {
+			yield new Uint8Array(chunk);
+			continue;
+		}
+		if (typeof chunk === "string") {
+			yield new TextEncoder().encode(chunk);
+			continue;
+		}
+		if (chunk instanceof Uint8Array) {
+			yield chunk;
+			continue;
+		}
+		throw new Error(`Unsupported stdout/stderr chunk type: ${typeof chunk}`);
+	}
+} });
+const spawnProcess = (command, args, options = {}) => {
+	const child = spawn(command, args, {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: options.stdio
+	});
+	const waitPromise = new Promise((resolve, reject) => {
+		const onClose = (exitCode, signal) => {
+			child.removeListener("error", onError);
+			resolve({
+				exitCode,
+				signal
+			});
+		};
+		const onError = (err) => {
+			child.removeListener("close", onClose);
+			reject(err);
+		};
+		child.once("error", onError);
+		child.once("close", onClose);
+	});
+	return {
+		stdout: child.stdout ? streamToAsyncIterable(child.stdout) : null,
+		stderr: child.stderr ? streamToAsyncIterable(child.stderr) : null,
+		stdin: child.stdin ? {
+			write: (chunk) => child.stdin?.write(chunk),
+			end: () => child.stdin?.end()
+		} : null,
+		kill: (signal) => child.kill(signal),
+		wait: () => waitPromise
+	};
+};
+const DEFAULT_SPAWNER = { spawn: spawnProcess };
+//#endregion
+export { DEFAULT_SPAWNER as t };

package/dist/structured-output-BHtr_zpz.mjs

@@ -0,0 +1,19 @@
+//#region src/core/structured-output.ts
+const findStructuredOutputToolCallInput = (toolCalls) => {
+	let latestInput;
+	for (const [, record] of toolCalls) if (record.toolName === "StructuredOutput" && record.input !== void 0) latestInput = record.input;
+	return latestInput;
+};
+const extractClaudeStructuredOutput = (structuredOutput, context, eventMeta, errorMessage) => {
+	if (structuredOutput !== void 0) return { value: structuredOutput };
+	if (!context.schemaRequested) return {};
+	const toolCallOutput = findStructuredOutputToolCallInput(context.toolCalls);
+	if (toolCallOutput !== void 0) return { value: toolCallOutput };
+	if (eventMeta.isSuccess) return { error: {
+		kind: "parse",
+		message: errorMessage
+	} };
+	return {};
+};
+//#endregion
+export { extractClaudeStructuredOutput as t };

package/dist/types-Cb_EXIEe.d.mts

@@ -0,0 +1,177 @@
+import { t as AgentEvent, v as AgentCapabilities, x as JsonSchema, y as ContentPart } from "./events-nxuRbYIu.mjs";
+import { ZodType } from "zod/v4";
+
+//#region src/core/process/types.d.ts
+type StdioOption = "ignore" | "inherit" | "pipe" | number;
+type ProcessSignal = NodeJS.Signals;
+interface SpawnOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  stdio?: [StdioOption, StdioOption, StdioOption];
+}
+interface ProcessResult {
+  exitCode: number | null;
+  signal: ProcessSignal | null;
+}
+interface AgentProcess {
+  stdout: AsyncIterable<Uint8Array> | null;
+  stderr: AsyncIterable<Uint8Array> | null;
+  stdin: {
+    write?: (chunk: Uint8Array | string) => void;
+    end: () => void;
+  } | null;
+  kill: (signal?: ProcessSignal | number) => void;
+  wait: () => Promise<ProcessResult>;
+}
+interface ProcessSpawner {
+  spawn: (command: string, args: string[], options?: SpawnOptions) => AgentProcess;
+}
+//#endregion
+//#region src/core/agent/types.d.ts
+/** Supported agents */
+type AgentType = "claude-code-cli" | "claude-code-sdk" | "codex-cli" | "codex-sdk" | "gemini-cli";
+/** Terminal status of a completed agent run */
+type RunStatus = "cancelled" | "completed" | "failed";
+/** Reason an agent run was stopped before completion */
+type StopReason = "abort" | "timeout" | "user";
+/** Usage and performance statistics from an agent run */
+interface RunStats {
+  durationMs?: number;
+  apiDurationMs?: number;
+  turns: number;
+  costUsd: number;
+  inputTokens?: number;
+  cacheCreationInputTokens?: number;
+  cacheReadInputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+/** Structured error from a failed or cancelled agent run */
+interface RunError {
+  /** Error classification: abort (externally stopped), parse (output parsing), process (non-zero exit), provider (api error), spawn (binary not found) */
+  kind: "abort" | "parse" | "process" | "provider" | "spawn";
+  message: string;
+}
+/** Input parameters for a plain-text agent run. */
+interface RunRequest {
+  input: ContentPart[] | string;
+  cwd?: string;
+  model?: string;
+  systemPrompt?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+/** Input parameters for a raw-JSON-Schema structured-output run. */
+interface JsonSchemaRunRequest extends RunRequest {
+  schema: JsonSchema;
+}
+/** Input parameters for a Zod-backed structured-output run. */
+interface ZodRunRequest<TOutput = unknown> extends RunRequest {
+  schema: ZodType<TOutput>;
+}
+/** Input parameters for a structured-output run. */
+type StructuredRunRequest<TOutput = unknown> = JsonSchemaRunRequest | ZodRunRequest<TOutput>;
+/** Any supported run request shape. */
+type AnyRunRequest = RunRequest | StructuredRunRequest;
+interface RunTiming {
+  startedAt: Date;
+  endedAt: Date;
+  durationMs: number;
+}
+interface RunProcessInfo {
+  exitCode: number | null;
+  signal: ProcessSignal | null;
+  stderr: string;
+}
+interface RunResultBase {
+  type: AgentType;
+  runId: string;
+  sessionId?: string;
+  text: string;
+  events: readonly AgentEvent[];
+  stats?: RunStats;
+  timing: RunTiming;
+  process?: RunProcessInfo;
+}
+interface CancelledRunResult extends RunResultBase {
+  status: "cancelled";
+  output?: undefined;
+  error: RunError;
+  cancelReason: StopReason;
+}
+interface FailedRunResult extends RunResultBase {
+  status: "failed";
+  output?: undefined;
+  error: RunError;
+  cancelReason?: undefined;
+}
+type CompletedRunResult<TOutput = never> = RunResultBase & ([TOutput] extends [never] ? {} : {
+  output: TOutput;
+}) & {
+  status: "completed";
+  error?: undefined;
+  cancelReason?: undefined;
+};
+/** Discriminated union result of an agent run. narrow on `status` to access variant-specific fields. */
+type RunResult<TOutput = never> = CancelledRunResult | CompletedRunResult<TOutput> | FailedRunResult;
+/** Result of a run when the request shape is not known ahead of time. */
+type AnyRunResult = RunResult | RunResult<unknown>;
+/** Completed result of a run when the request shape is not known ahead of time. */
+type AnyCompletedRunResult = CompletedRunResult | CompletedRunResult<unknown>;
+type AgentRun<TRunOptions extends object = {}> = {
+  <TOutput>(request: TRunOptions & ZodRunRequest<TOutput>): Promise<RunResult<TOutput>>;
+  (request: JsonSchemaRunRequest & TRunOptions): Promise<RunResult<unknown>>;
+  (request: RunRequest & TRunOptions): Promise<RunResult>;
+};
+type AgentRunOrThrow<TRunOptions extends object = {}> = {
+  <TOutput>(request: TRunOptions & ZodRunRequest<TOutput>): Promise<CompletedRunResult<TOutput>>;
+  (request: JsonSchemaRunRequest & TRunOptions): Promise<CompletedRunResult<unknown>>;
+  (request: RunRequest & TRunOptions): Promise<CompletedRunResult>;
+};
+/** Thrown by `runOrThrow()` when the run does not complete successfully. carries the full `RunResult` on `.result`. */
+declare class AgentRunError<TOutput = never> extends Error {
+  readonly result: RunResult<TOutput> & {
+    status: "cancelled" | "failed";
+  };
+  constructor(result: RunResult<TOutput> & {
+    status: "cancelled" | "failed";
+  });
+}
+/** Thrown when agent configuration or request parameters are invalid (e.g. unsupported capability, empty input) */
+declare class AgentValidationError extends Error {
+  constructor(message: string);
+}
+type AgentEventHandler = (event: AgentEvent) => void;
+interface AgentMetrics {
+  runCount: number;
+  messagesReceived: number;
+  toolCalls: number;
+  errors: number;
+  startedAt: Date;
+  lastActivityAt: Date;
+}
+/** Excludes keys typed as never (e.g. `systemPrompt?: never` blocker fields) */
+type EffectiveKeys<T> = keyof { [K in keyof T as Required<T>[K] extends never ? never : K]: unknown };
+/** Resolves to T if T has no effective keys overlapping with RunRequest, otherwise never */
+type EnsureDisjoint<T extends object> = EffectiveKeys<T> & keyof RunRequest extends never ? T : never;
+/**
+ * Base interface for all agent types. TRunOptions adds adapter-specific fields to the run request.
+ * TRunOptions keys must not overlap with RunRequest keys (enforced via `EnsureDisjoint`).
+ */
+interface BaseAgent<TRunOptions extends object = {}> {
+  readonly type: AgentType;
+  readonly capabilities: Readonly<AgentCapabilities>;
+  readonly sessionId?: string;
+  readonly isRunning: boolean;
+  readonly metrics: Readonly<AgentMetrics>;
+  run: AgentRun<TRunOptions>;
+  runOrThrow: AgentRunOrThrow<TRunOptions>;
+  stop: () => Promise<AnyRunResult | undefined>;
+  reset: () => void;
+  wait: () => Promise<AnyRunResult>;
+  dispose: () => Promise<void>;
+  [Symbol.asyncDispose]: () => Promise<void>;
+  onEvent: (handler: AgentEventHandler) => () => void;
+}
+//#endregion
+export { StopReason as C, ProcessSpawner as E, RunTiming as S, ZodRunRequest as T, RunRequest as _, AgentValidationError as a, RunStats as b, AnyRunResult as c, CompletedRunResult as d, EnsureDisjoint as f, RunProcessInfo as g, RunError as h, AgentType as i, BaseAgent as l, JsonSchemaRunRequest as m, AgentMetrics as n, AnyCompletedRunResult as o, FailedRunResult as p, AgentRunError as r, AnyRunRequest as s, AgentEventHandler as t, CancelledRunResult as u, RunResult as v, StructuredRunRequest as w, RunStatus as x, RunResultBase as y };

package/dist/types-aNMD8h3x.mjs

@@ -0,0 +1,19 @@
+//#region src/core/agent/types.ts
+/** Thrown by `runOrThrow()` when the run does not complete successfully. carries the full `RunResult` on `.result`. */
+var AgentRunError = class extends Error {
+	result;
+	constructor(result) {
+		super(result.error.message);
+		this.name = "AgentRunError";
+		this.result = result;
+	}
+};
+/** Thrown when agent configuration or request parameters are invalid (e.g. unsupported capability, empty input) */
+var AgentValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AgentValidationError";
+	}
+};
+//#endregion
+export { AgentValidationError as n, AgentRunError as t };

package/dist/util-B4RQZkKr.mjs

@@ -0,0 +1,77 @@
+//#region src/core/util.ts
+const toArray = (value) => {
+	return Array.isArray(value) ? value : [value];
+};
+const formatError = (error) => error instanceof Error ? error.message : String(error);
+const isRecord = (value) => typeof value === "object" && value !== null;
+const sumTokens = (...values) => values.reduce((sum, v) => sum + (v ?? 0), 0);
+const stripMarkdownCodeFence = (value) => {
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("```")) return trimmed;
+	return trimmed.replace(/^```[\w-]*\s*/i, "").replace(/\s*```$/i, "").trim();
+};
+const extractMarkdownCodeBlock = (value) => {
+	return /```[\w-]*\s*([\S\s]*?)\s*```/i.exec(value)?.[1]?.trim();
+};
+const extractBalancedJson = (value) => {
+	let start = -1;
+	const stack = [];
+	let inString = false;
+	let escaped = false;
+	for (let index = 0; index < value.length; index++) {
+		const char = value[index];
+		if (!char) continue;
+		if (start === -1) {
+			if (char === "{" || char === "[") {
+				start = index;
+				stack.push(char);
+			}
+			continue;
+		}
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === "{" || char === "[") {
+			stack.push(char);
+			continue;
+		}
+		if (char === "}" || char === "]") {
+			const open = stack.pop();
+			if (open === "{" && char !== "}" || open === "[" && char !== "]") return;
+			if (stack.length === 0) return value.slice(start, index + 1).trim();
+		}
+	}
+};
+const parseJsonResponseText = (value) => {
+	const trimmed = value.trim();
+	const candidates = [
+		stripMarkdownCodeFence(trimmed),
+		extractMarkdownCodeBlock(trimmed),
+		extractBalancedJson(trimmed)
+	];
+	let lastError;
+	for (const candidate of new Set(candidates)) {
+		if (!candidate) continue;
+		try {
+			return JSON.parse(candidate);
+		} catch (error) {
+			lastError = error;
+		}
+	}
+	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new SyntaxError("Failed to parse JSON response text.");
+};
+//#endregion
+export { toArray as a, sumTokens as i, isRecord as n, parseJsonResponseText as r, formatError as t };

package/package.json

@@ -1,15 +1,92 @@
 {
   "name": "coding-agents-sdk",
-  "version": "0.0.1",
-  "license": "UNLICENSED",
-  "main": "index.js",
+  "version": "0.2.0",
+  "type": "module",
+  "types": "./dist/index.d.mts",
   "exports": {
-    ".": "./index.js"
-  },
-  "publishConfig": {
-    "access": "public"
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.mts",
+      "default": "./dist/schemas/index.mjs"
+    },
+    "./container": {
+      "types": "./dist/container/index.d.mts",
+      "default": "./dist/container/index.mjs"
+    },
+    "./adapters/claude-code-cli": {
+      "types": "./dist/adapters/claude-code-cli/index.d.mts",
+      "default": "./dist/adapters/claude-code-cli/index.mjs"
+    },
+    "./adapters/claude-code-sdk": {
+      "types": "./dist/adapters/claude-code-sdk/index.d.mts",
+      "default": "./dist/adapters/claude-code-sdk/index.mjs"
+    },
+    "./adapters/codex-cli": {
+      "types": "./dist/adapters/codex-cli/index.d.mts",
+      "default": "./dist/adapters/codex-cli/index.mjs"
+    },
+    "./adapters/codex-sdk": {
+      "types": "./dist/adapters/codex-sdk/index.d.mts",
+      "default": "./dist/adapters/codex-sdk/index.mjs"
+    },
+    "./adapters/gemini-cli": {
+      "types": "./dist/adapters/gemini-cli/index.d.mts",
+      "default": "./dist/adapters/gemini-cli/index.mjs"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
-    "index.js"
-  ]
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown && bun run test:package",
+    "start": "bun run examples/claude-code-cli/simple.ts",
+    "test": "bun test",
+    "test:agent": "bun test ./tests",
+    "test:package": "bun run test:package:runtime",
+    "test:package:runtime": "bun test ./tests/package-exports.smoke.ts",
+    "test:agent:claude-code-cli": "CODE_WORKFLOW_TEST_AGENTS=claude-code-cli bun run test:agent",
+    "test:agent:claude-code-sdk": "CODE_WORKFLOW_TEST_AGENTS=claude-code-sdk bun run test:agent",
+    "test:agent:codex-cli": "CODE_WORKFLOW_TEST_AGENTS=codex-cli bun run test:agent",
+    "test:agent:codex-sdk": "CODE_WORKFLOW_TEST_AGENTS=codex-sdk bun run test:agent",
+    "test:agent:gemini-cli": "CODE_WORKFLOW_TEST_AGENTS=gemini-cli bun run test:agent",
+    "knip": "knip",
+    "tsc": "tsc --noEmit --pretty",
+    "typecheck": "bun run tsc"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
+    "@openai/codex-sdk": "^0.114.0",
+    "@types/bun": "latest",
+    "@types/node": "^25.5.0",
+    "e2b": "^2.14.1",
+    "knip": "^5.87.0",
+    "picoprint": "^1.0.6",
+    "tsdown": "^0.21.4"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
+    "@openai/codex-sdk": "^0.114.0",
+    "e2b": "^2.14.1",
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@openai/codex-sdk": {
+      "optional": true
+    },
+    "e2b": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
 }

package/index.js

@@ -1,7 +0,0 @@
-"use strict";
-
-function getCodingAgentNames() {
-  return ["claude-code-cli", "codex-cli"];
-}
-
-module.exports = getCodingAgentNames;