@zvada/agent-server 0.2.0

package/src/core/agents/tool-meta.ts

@@ -0,0 +1,68 @@
+import type { ToolKind, ToolLocation, ToolMeta } from "../../protocol/index.ts";
+
+/**
+ * Maps provider-native tool names onto the normalized ToolKind taxonomy and
+ * extracts touched file locations from tool inputs. Pure best-effort: unknown
+ * tools are `other` and produce no locations.
+ */
+
+const CLAUDE_TOOL_KINDS: Record<string, ToolKind> = {
+	Read: "read",
+	NotebookRead: "read",
+	Edit: "edit",
+	Write: "edit",
+	MultiEdit: "edit",
+	NotebookEdit: "edit",
+	Bash: "execute",
+	BashOutput: "execute",
+	KillShell: "execute",
+	Grep: "search",
+	Glob: "search",
+	LS: "search",
+	WebFetch: "fetch",
+	WebSearch: "fetch",
+	Task: "think",
+	Agent: "think",
+	TodoWrite: "think",
+	ExitPlanMode: "switch_mode",
+	EnterPlanMode: "switch_mode",
+};
+
+export function claudeToolKind(toolName: string): ToolKind {
+	if (CLAUDE_TOOL_KINDS[toolName]) return CLAUDE_TOOL_KINDS[toolName];
+	// MCP tools arrive as mcp__server__tool.
+	if (toolName.startsWith("mcp__")) return "other";
+	return "other";
+}
+
+const PATH_INPUT_KEYS = ["file_path", "filePath", "path", "notebook_path"] as const;
+
+export function toolLocationsFromInput(input: Record<string, unknown>): ToolLocation[] | undefined {
+	for (const key of PATH_INPUT_KEYS) {
+		const v = input[key];
+		if (typeof v === "string" && v) return [{ path: v }];
+	}
+	return undefined;
+}
+
+export function claudeToolMeta(toolName: string, input?: Record<string, unknown>): ToolMeta {
+	return {
+		kind: claudeToolKind(toolName),
+		...(input ? { locations: toolLocationsFromInput(input) } : {}),
+	};
+}
+
+/** Codex tools are already normalized names; kinds are fixed per item type. */
+export const CODEX_TOOL_KINDS = {
+	shell: "execute",
+	apply_patch: "edit",
+	web_search: "fetch",
+	mcp: "other",
+} as const satisfies Record<string, ToolKind>;
+
+export function codexFileChangeLocations(
+	changes: Array<{ path: string }> | undefined,
+): ToolLocation[] | undefined {
+	if (!changes?.length) return undefined;
+	return changes.map((c) => ({ path: c.path }));
+}

package/src/core/agents/types.ts

@@ -0,0 +1,54 @@
+import type { Part, StopReason, TokenUsage } from "../../protocol/index.ts";
+
+/**
+ * The normalized intermediate an adapter emits while consuming raw harness
+ * events. The engine's EventProcessor turns these into wire `LifecycleEvent`s,
+ * assigning message/part indices and ids. Keeping deltas here (rather than
+ * diffing snapshots downstream) lets each adapter express its harness's exact
+ * streaming granularity — token-level for Claude / Codex app-server,
+ * item-level for the Codex SDK.
+ */
+export type AdapterEvent =
+	| { kind: "message-start"; role: "assistant" | "user" }
+	| { kind: "message-end" }
+	/** A new part appears (streaming text begins, a tool call opens, etc.). */
+	| { kind: "part-open"; part: Part }
+	/** A full new snapshot of an existing part (tool -> running/completed, text finalized). */
+	| { kind: "part-update"; part: Part }
+	| { kind: "text-delta"; partId: string; text: string }
+	| { kind: "reasoning-delta"; partId: string; text: string }
+	| {
+			kind: "tool-input-delta";
+			partId: string;
+			toolCallId: string;
+			toolName: string;
+			input: string;
+	  }
+	/** Context-window gauge snapshot (→ `session.usage`). */
+	| { kind: "usage"; used: number; size?: number; cost?: number }
+	/** History-compaction boundary (→ `session.compacted`). */
+	| { kind: "compacted"; trigger?: string; preTokens?: number; postTokens?: number };
+
+/** Terminal result of a turn, surfaced on `turn.ended`. */
+export interface TransformResult {
+	usage: TokenUsage;
+	/** Normalized terminal status, when the harness reported one. The engine
+	 * overrides with `cancelled`/`error` based on what it observed. */
+	stopReason?: StopReason;
+	/** Raw provider finish string, passed through untouched. */
+	finishReason?: string;
+	cost?: number;
+	error?: string;
+	cancelled?: boolean;
+}
+
+/**
+ * Per-turn stateful translator from one harness's raw events to AdapterEvents.
+ * Created fresh per turn (it holds streaming part state).
+ */
+export interface EventTransformer<TEvent = unknown> {
+	process(event: TEvent): AdapterEvent[];
+	finish(): TransformResult;
+}
+
+export type AdapterFactory = (ctx: { sessionId: string }) => EventTransformer;

package/src/core/index.ts

@@ -0,0 +1,114 @@
+// @zvada/agent-server/core — harness-agnostic agent execution engine.
+
+// Runtime
+export { AgentRuntime, type RunSummary } from "./runtime/agent-runtime.ts";
+export {
+	type EventSink,
+	callbackSink,
+	CollectingSink,
+	teeSink,
+} from "./runtime/event-sink.ts";
+export { EventProcessor } from "./runtime/event-processor.ts";
+
+// Agent abstraction
+export {
+	type Agent,
+	type AgentExecuteOptions,
+	type RawAgentEvent,
+	BaseAgent,
+} from "./agents/base.ts";
+export { AgentRegistry } from "./agents/registry.ts";
+export {
+	type ErrorCategory,
+	ERROR_CATEGORIES,
+	classifyError,
+	isRecoverable,
+	isCancellation,
+} from "./agents/error-classifier.ts";
+
+// Adapter contract
+export type {
+	AdapterEvent,
+	AdapterFactory,
+	EventTransformer,
+	TransformResult,
+} from "./agents/types.ts";
+
+// CLI provisioning
+export {
+	CLI_TOOLS,
+	type CliTool,
+	CliProvisioner,
+	DEFAULT_PINS,
+	type PlatformInfo,
+	type ProvisionMode,
+	type ProvisionOptions,
+	type ProvisionerDeps,
+	type ResolvedCli,
+	detectPlatform,
+	toolForHarness,
+} from "./provision/index.ts";
+
+// Harnesses
+export {
+	ClaudeCodeAgent,
+	type ClaudeCodeAgentOptions,
+} from "./agents/claude-code/claude-agent.ts";
+export type { ClaudeSdkOptionOverrides, SdkMcpServers } from "./agents/claude-code/options.ts";
+export type {
+	ClaudeHooksFactory,
+	ClaudeSessionExtras,
+	ClaudeToolPolicy,
+} from "./agents/claude-code/generator-session.ts";
+export {
+	ClaudeCodeTransformer,
+	createClaudeCodeTransformer,
+} from "./agents/claude-code/adapter.ts";
+export {
+	CodexSdkAgent,
+	type CodexSdkAgentOptions,
+} from "./agents/codex-sdk/codex-sdk-agent.ts";
+export { CodexSdkTransformer, createCodexSdkTransformer } from "./agents/codex-sdk/adapter.ts";
+export {
+	CodexAppServerAgent,
+	type CodexAppServerAgentOptions,
+} from "./agents/codex-app-server/codex-app-server-agent.ts";
+export {
+	CodexAppServerTransformer,
+	createCodexAppServerTransformer,
+} from "./agents/codex-app-server/adapter.ts";
+export {
+	CodexAppServerClient,
+	type CodexNotification,
+} from "./agents/codex-app-server/client.ts";
+export {
+	AcpAgent,
+	type AcpAgentOptions,
+} from "./agents/acp/acp-agent.ts";
+export { AcpTransformer, createAcpTransformer } from "./agents/acp/adapter.ts";
+export {
+	AcpClient,
+	type AcpClientOptions,
+	type AcpLaunch,
+	parseAcpLaunch,
+} from "./agents/acp/client.ts";
+export { KNOWN_ACP_AGENTS, resolveAcpLaunch } from "./agents/acp/known-agents.ts";
+
+// Presets
+export {
+	type CreateRegistryOptions,
+	createAgentRegistry,
+	createAgentRuntime,
+} from "./presets.ts";
+
+// Utils
+export {
+	AgentServerError,
+	AgentExecutionError,
+	CliNotFoundError,
+	CliProvisionError,
+	HarnessNotFoundError,
+} from "./utils/errors.ts";
+
+// Re-export the wire contract for convenience.
+export * from "../protocol/index.ts";

package/src/core/presets.ts

@@ -0,0 +1,78 @@
+import { AGENT_HARNESSES, type AgentHarness } from "../protocol/index.ts";
+import { AcpAgent, type AcpAgentOptions } from "./agents/acp/acp-agent.ts";
+import { createAcpTransformer } from "./agents/acp/adapter.ts";
+import { createClaudeCodeTransformer } from "./agents/claude-code/adapter.ts";
+import { ClaudeCodeAgent, type ClaudeCodeAgentOptions } from "./agents/claude-code/claude-agent.ts";
+import { createCodexAppServerTransformer } from "./agents/codex-app-server/adapter.ts";
+import { CodexAppServerAgent } from "./agents/codex-app-server/codex-app-server-agent.ts";
+import { createCodexSdkTransformer } from "./agents/codex-sdk/adapter.ts";
+import { CodexSdkAgent } from "./agents/codex-sdk/codex-sdk-agent.ts";
+import { AgentRegistry } from "./agents/registry.ts";
+import { CliProvisioner, type ProvisionOptions } from "./provision/provisioner.ts";
+import { AgentRuntime } from "./runtime/agent-runtime.ts";
+
+export interface CreateRegistryOptions {
+	/**
+	 * Which harnesses to register. Defaults to the three native harnesses,
+	 * plus `acp` when `acp` config is provided (it has no default launch).
+	 */
+	harnesses?: AgentHarness[];
+	/**
+	 * CLI provisioning policy — how the native `claude`/`codex` binaries are
+	 * found or downloaded (see `CliProvisioner`). Defaults to `auto`.
+	 */
+	provision?: ProvisionOptions;
+	/**
+	 * ACP harness configuration. Required to enable `acp`: the harness needs an
+	 * operator-supplied launch command for the target agent (never wire-driven).
+	 */
+	acp?: AcpAgentOptions;
+	/**
+	 * Claude harness embed-tier options (e.g. in-process `sdkMcpServers`).
+	 * `resolveCliPath` stays provisioner-wired here.
+	 */
+	claudeCode?: Omit<ClaudeCodeAgentOptions, "resolveCliPath">;
+}
+
+/** Build a registry with the standard harnesses wired to their adapters. */
+export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegistry {
+	// Default: every harness that can run unconfigured — acp joins only when its
+	// operator launch config is present (it has nothing to run otherwise).
+	const enabled = new Set<AgentHarness>(
+		opts.harnesses ?? AGENT_HARNESSES.filter((h) => h !== "acp" || Boolean(opts.acp)),
+	);
+	// One provisioner per registry: resolution is memoized per tool, so both
+	// codex harnesses share a single download and every agent logs one source.
+	const provisioner = new CliProvisioner(opts.provision);
+	const claudeCli = () => provisioner.resolve("claude").then((cli) => cli?.path);
+	const codexCli = () => provisioner.resolve("codex").then((cli) => cli?.path);
+
+	const registry = new AgentRegistry();
+	if (enabled.has("claude-code")) {
+		registry.register(
+			new ClaudeCodeAgent({ ...opts.claudeCode, resolveCliPath: claudeCli }),
+			createClaudeCodeTransformer,
+		);
+	}
+	if (enabled.has("codex-sdk")) {
+		registry.register(new CodexSdkAgent({ resolveCliPath: codexCli }), createCodexSdkTransformer);
+	}
+	if (enabled.has("codex-app-server")) {
+		registry.register(
+			new CodexAppServerAgent({ resolveCliPath: codexCli }),
+			createCodexAppServerTransformer,
+		);
+	}
+	if (enabled.has("acp")) {
+		if (!opts.acp) {
+			throw new Error("the acp harness requires CreateRegistryOptions.acp (resolveLaunch)");
+		}
+		registry.register(new AcpAgent(opts.acp), createAcpTransformer);
+	}
+	return registry;
+}
+
+/** Convenience: a ready-to-use runtime with the standard harnesses. */
+export function createAgentRuntime(opts: CreateRegistryOptions = {}): AgentRuntime {
+	return new AgentRuntime(createAgentRegistry(opts));
+}

package/src/core/provision/extract.ts

@@ -0,0 +1,31 @@
+import { spawn } from "node:child_process";
+import { CliProvisionError } from "../utils/errors.ts";
+
+/**
+ * Extract a .tgz into a directory using the system `tar` (BSD, GNU, and
+ * Windows 10+ libarchive all accept these flags). npm tarballs are small
+ * enough in entry count that shelling out beats maintaining a tar parser.
+ */
+export async function extractTarGz(tgzPath: string, destDir: string): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const proc = spawn("tar", ["-xzf", tgzPath, "-C", destDir], {
+			stdio: ["ignore", "ignore", "pipe"],
+		});
+		let stderr = "";
+		proc.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+		proc.on("error", (error) =>
+			reject(
+				new CliProvisionError(
+					`Failed to run \`tar\` (${error.message}) — provisioning needs tar on PATH`,
+					{ cause: error },
+				),
+			),
+		);
+		proc.on("exit", (code) => {
+			if (code === 0) resolve();
+			else reject(new CliProvisionError(`tar -xzf ${tgzPath} exited ${code}: ${stderr.trim()}`));
+		});
+	});
+}

package/src/core/provision/index.ts

@@ -0,0 +1,10 @@
+// CLI provisioning — resolve/download the native CLIs the harnesses spawn.
+export { CLI_TOOLS, type CliTool, DEFAULT_PINS, toolForHarness } from "./pins.ts";
+export { type PlatformInfo, detectPlatform } from "./platform.ts";
+export {
+	CliProvisioner,
+	type ProvisionMode,
+	type ProvisionOptions,
+	type ProvisionerDeps,
+	type ResolvedCli,
+} from "./provisioner.ts";

package/src/core/provision/npm.ts

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { createWriteStream } from "node:fs";
+import { CliProvisionError } from "../utils/errors.ts";
+
+export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+
+/** The subset of npm packument `dist` we need to fetch a package verifiably. */
+export interface NpmDist {
+	tarball: string;
+	/** Subresource integrity, e.g. `sha512-<base64>`. */
+	integrity: string;
+}
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** One retry on network-level failures; 4xx/5xx are not retried. */
+async function fetchOk(fetchImpl: FetchLike, url: string): Promise<Response> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			const res = await fetchImpl(url);
+			if (!res.ok) {
+				throw new CliProvisionError(`GET ${url} failed: ${res.status} ${res.statusText}`);
+			}
+			return res;
+		} catch (error) {
+			if (error instanceof CliProvisionError) throw error;
+			lastError = error;
+		}
+	}
+	throw new CliProvisionError(`GET ${url} failed: ${String(lastError)}`, { cause: lastError });
+}
+
+/**
+ * Fetch the registry metadata for one exact package version and return its
+ * tarball location + integrity. The returned tarball URL is the registry's own
+ * (works with mirrors/private registries that rewrite hosts).
+ */
+export async function fetchDist(
+	registry: string,
+	packageName: string,
+	version: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<NpmDist> {
+	// Scoped names keep the literal `@` but escape the inner slash.
+	const base = registry.replace(/\/+$/, "");
+	const url = `${base}/${packageName.replace("/", "%2F")}/${version}`;
+	const res = await fetchOk(fetchImpl, url);
+	const body = (await res.json()) as { dist?: { tarball?: string; integrity?: string } };
+	const { tarball, integrity } = body.dist ?? {};
+	if (!tarball || !integrity) {
+		throw new CliProvisionError(
+			`Registry metadata for ${packageName}@${version} has no dist.tarball/integrity — is this version published for your platform?`,
+		);
+	}
+	return { tarball, integrity };
+}
+
+/**
+ * Stream a tarball to disk, hashing as it lands, and reject on integrity
+ * mismatch. Only sha512 (what the npm registry publishes) is supported.
+ * Returns the byte count for progress logs.
+ */
+export async function downloadWithIntegrity(
+	url: string,
+	destFile: string,
+	integrity: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<number> {
+	const expected = /^sha512-([A-Za-z0-9+/=]+)$/.exec(integrity)?.[1];
+	if (!expected) {
+		throw new CliProvisionError(`Unsupported integrity format (want sha512-…): ${integrity}`);
+	}
+	const res = await fetchOk(fetchImpl, url);
+	if (!res.body) throw new CliProvisionError(`GET ${url} returned no body`);
+
+	const hash = createHash("sha512");
+	const out = createWriteStream(destFile);
+	// One persistent listener: an unobserved WriteStream 'error' would crash the
+	// process, and per-chunk `once("error")` listeners would accumulate instead.
+	let streamError: unknown;
+	out.on("error", (error) => {
+		streamError = error;
+	});
+	let bytes = 0;
+	try {
+		for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+			if (streamError) throw streamError;
+			hash.update(chunk);
+			bytes += chunk.byteLength;
+			// events.once rejects on 'error' and removes its listeners either way.
+			if (!out.write(chunk)) await once(out, "drain");
+		}
+		if (streamError) throw streamError;
+		// Reject on 'error' too: a failure during the terminal flush (e.g.
+		// ENOSPC on the last buffered chunk) never fires the end callback, and
+		// without this listener the await would hang instead of surfacing it.
+		await new Promise<void>((resolve, reject) => {
+			out.once("error", reject);
+			out.end(() => (streamError ? reject(streamError as Error) : resolve()));
+		});
+	} catch (error) {
+		out.destroy();
+		throw error;
+	}
+	const actual = hash.digest("base64");
+	if (actual !== expected) {
+		throw new CliProvisionError(
+			`Integrity mismatch for ${url}: expected sha512-${expected}, got sha512-${actual}`,
+		);
+	}
+	return bytes;
+}

package/src/core/provision/pins.ts

@@ -0,0 +1,51 @@
+import type { AgentHarness } from "../../protocol/index.ts";
+
+/**
+ * The managed CLIs. Each native harness maps onto exactly one of these; the
+ * `acp` harness maps onto none (its agent binaries are arbitrary third-party
+ * commands the operator supplies, not something we pin or download).
+ */
+export const CLI_TOOLS = ["claude", "codex"] as const;
+export type CliTool = (typeof CLI_TOOLS)[number];
+
+/**
+ * The CLI versions this engine release is tested against — the versions
+ * `agent-server install` (and on-demand provisioning) downloads.
+ *
+ * - `claude` is the version of the `@anthropic-ai/claude-agent-sdk-<platform>`
+ *   packages, which carry the native CLI matched to the SDK JS we bundle. It
+ *   MUST track the lockfile's claude-agent-sdk version (a test enforces this);
+ *   bump both together. When the SDK is resolvable on disk, its real installed
+ *   version wins over this pin so the pair can never skew.
+ * - `codex` is the `@openai/codex` platform-package version the
+ *   codex-app-server adapter's protocol snapshot was verified against (see
+ *   CLAUDE.md "Verifying harness protocols"). Bump after re-verifying. Note
+ *   the codex-sdk harness normally never reaches this pin: host resolution
+ *   prefers the build vendored by the installed `@openai/codex-sdk` (its own
+ *   pair). The pin governs downloads (compiled binaries / bare sandboxes /
+ *   `pinned` mode); embedders wanting an exact codex-sdk pairing there can
+ *   set `provision.pins.codex` to their SDK's vendored version.
+ */
+export const DEFAULT_PINS: Record<CliTool, string> = {
+	claude: "0.3.168",
+	// 0.146.1 re-verified 2026-08-06: generate-ts snapshot carries our full
+	// surface unchanged (thread/turn/item methods, tokenUsage w/ window,
+	// approvals) and a live turn ran clean incl. the gpt-5.6-sol default.
+	codex: "0.146.1",
+};
+
+/**
+ * Which managed CLI a harness runs on — `undefined` for unmanaged harnesses
+ * (`acp`). Exhaustive by construction: adding a harness fails to compile here
+ * until someone decides whether it is provisioner-managed.
+ */
+const TOOL_FOR_HARNESS: Record<AgentHarness, CliTool | undefined> = {
+	"claude-code": "claude",
+	"codex-sdk": "codex",
+	"codex-app-server": "codex",
+	acp: undefined,
+};
+
+export function toolForHarness(harness: AgentHarness): CliTool | undefined {
+	return TOOL_FOR_HARNESS[harness];
+}

package/src/core/provision/platform.ts

@@ -0,0 +1,73 @@
+import { constants, accessSync, existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/** The facts about this machine that pick a CLI build. Injectable in tests. */
+export interface PlatformInfo {
+	/** `process.platform` value (darwin | linux | win32 | …). */
+	platform: string;
+	/** `process.arch` value (arm64 | x64 | …). */
+	arch: string;
+	/** linux only: glibc absent (Alpine et al.) — selects `-musl` builds. */
+	musl: boolean;
+}
+
+/**
+ * Musl detection mirrors the Claude SDK's own check: a Node process report
+ * without `glibcVersionRuntime` means musl. Runtimes without process.report
+ * (or partial implementations) fall back to the Alpine marker file.
+ */
+function isMusl(): boolean {
+	if (process.platform !== "linux") return false;
+	try {
+		const report = process.report?.getReport?.() as
+			| { header?: { glibcVersionRuntime?: string } }
+			| undefined;
+		if (report?.header) return !report.header.glibcVersionRuntime;
+	} catch {
+		// fall through to the filesystem heuristic
+	}
+	return existsSync("/etc/alpine-release");
+}
+
+export function detectPlatform(): PlatformInfo {
+	return { platform: process.platform, arch: process.arch, musl: isMusl() };
+}
+
+/**
+ * Suffix of `@anthropic-ai/claude-agent-sdk-<suffix>` — the platform package
+ * carrying the native `claude` binary. Claude ships dedicated musl builds.
+ */
+export function claudePackageSuffix(p: PlatformInfo): string {
+	return `${p.platform}-${p.arch}${p.musl ? "-musl" : ""}`;
+}
+
+/**
+ * Suffix of `@openai/codex@<version>-<suffix>` — codex publishes platform
+ * builds as version suffixes of the main package. Its linux builds are static
+ * (musl) already, so there is no separate musl variant.
+ */
+export function codexPackageSuffix(p: PlatformInfo): string {
+	return `${p.platform}-${p.arch}`;
+}
+
+/** Locate an executable on PATH (the `which` we can unit-test and run anywhere). */
+export function findOnPath(
+	name: string,
+	env: Record<string, string | undefined> = process.env,
+	platform: string = process.platform,
+): string | undefined {
+	const paths = (env.PATH ?? "").split(delimiter).filter(Boolean);
+	const names = platform === "win32" ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+	for (const dir of paths) {
+		for (const file of names) {
+			const candidate = join(dir, file);
+			try {
+				accessSync(candidate, constants.X_OK);
+				return candidate;
+			} catch {
+				// not here — keep walking
+			}
+		}
+	}
+	return undefined;
+}