@zvada/agent-server 0.2.0

package/src/core/agents/codex-sdk/adapter.ts

@@ -0,0 +1,204 @@
+import {
+	DEFAULT_TOKEN_USAGE,
+	type Part,
+	type ReasoningPart,
+	type StopReason,
+	type StreamContext,
+	type TextPart,
+	type TokenUsage,
+	type ToolPart,
+	completeToolPart,
+	createReasoningPart,
+	createTextPart,
+	createToolPart,
+} from "../../../protocol/index.ts";
+import {
+	type CodexToolDescriptor,
+	type CodexToolItem,
+	codexToolDescriptor,
+} from "../codex-items.ts";
+import type { AdapterEvent, EventTransformer, TransformResult } from "../types.ts";
+
+/**
+ * Parses `@openai/codex-sdk` ThreadEvents into AdapterEvents.
+ *
+ * Codex streams at item granularity (item.started/updated/completed), not token
+ * by token. For agent_message/reasoning items we still synthesize text deltas by
+ * diffing successive snapshots, so downstream consumers get incremental text.
+ * command_execution / file_change / mcp_tool_call / web_search items become tool
+ * parts that complete when the item reaches a terminal status.
+ */
+
+type Phase = "started" | "updated" | "completed";
+
+/** One SDK thread item: the shared codex tool vocabulary plus streaming fields. */
+interface ThreadItem extends CodexToolItem {
+	type: string;
+	text?: string;
+	message?: string;
+}
+interface CodexEvent {
+	type: string;
+	thread_id?: string;
+	item?: ThreadItem;
+	usage?: {
+		input_tokens?: number;
+		cached_input_tokens?: number;
+		output_tokens?: number;
+		reasoning_output_tokens?: number;
+	};
+	error?: { message?: string };
+	message?: string;
+}
+
+export class CodexSdkTransformer implements EventTransformer<unknown> {
+	private readonly ctx: StreamContext;
+	private readonly partByItem = new Map<string, Part>();
+	private readonly textLenByItem = new Map<string, number>();
+
+	private usage: TokenUsage = { ...DEFAULT_TOKEN_USAGE };
+	private stopReason?: StopReason;
+	private finishReason?: string;
+	private error?: string;
+
+	constructor(ctx: { sessionId: string }) {
+		this.ctx = { sessionId: ctx.sessionId, messageId: "" };
+	}
+
+	process(raw: unknown): AdapterEvent[] {
+		const ev = raw as CodexEvent;
+		switch (ev.type) {
+			case "item.started":
+				return ev.item ? this.handleItem(ev.item, "started") : [];
+			case "item.updated":
+				return ev.item ? this.handleItem(ev.item, "updated") : [];
+			case "item.completed":
+				return ev.item ? this.handleItem(ev.item, "completed") : [];
+			case "turn.completed": {
+				// Completion supersedes earlier stream notices: codex emits non-fatal
+				// diagnostics (retry / skills-context-budget notices) as `error`
+				// events; the fatal signal is `turn.failed`, which arrives *instead*
+				// of completion.
+				this.error = undefined;
+				this.finishReason = "completed";
+				this.stopReason = "end_turn";
+				if (!ev.usage) return [];
+				this.usage = {
+					input: ev.usage.input_tokens ?? 0,
+					output: ev.usage.output_tokens ?? 0,
+					reasoning: ev.usage.reasoning_output_tokens ?? 0,
+					cache: { read: ev.usage.cached_input_tokens ?? 0, write: 0 },
+				};
+				// The SDK reports usage only at turn end; input covers the full prompt
+				// context, so it doubles as the context gauge.
+				const used =
+					(ev.usage.input_tokens ?? 0) +
+					(ev.usage.cached_input_tokens ?? 0) +
+					(ev.usage.output_tokens ?? 0);
+				return [{ kind: "usage", used }];
+			}
+			case "turn.failed":
+				this.error = ev.error?.message ?? "codex turn failed";
+				return [];
+			case "error":
+				this.error = ev.message ?? "codex stream error";
+				return [];
+			default:
+				return [];
+		}
+	}
+
+	finish(): TransformResult {
+		return {
+			usage: this.usage,
+			stopReason: this.stopReason,
+			finishReason: this.finishReason,
+			error: this.error,
+		};
+	}
+
+	private handleItem(item: ThreadItem, phase: Phase): AdapterEvent[] {
+		switch (item.type) {
+			case "agent_message":
+				return this.handleText(item, phase, "text");
+			case "reasoning":
+				return this.handleText(item, phase, "reasoning");
+			case "error":
+				this.error = item.message ?? "codex item error";
+				return [];
+			default: {
+				// command_execution / file_change / mcp_tool_call / web_search share
+				// one descriptor vocabulary; unknown item types produce nothing.
+				const d = codexToolDescriptor(item.type);
+				return d ? this.handleTool(item, phase, d) : [];
+			}
+		}
+	}
+
+	private handleText(item: ThreadItem, phase: Phase, kind: "text" | "reasoning"): AdapterEvent[] {
+		const events: AdapterEvent[] = [];
+		let part = this.partByItem.get(item.id) as TextPart | ReasoningPart | undefined;
+		const isNew = !part;
+		if (!part) {
+			part =
+				kind === "text"
+					? createTextPart(this.ctx, "", true)
+					: createReasoningPart(this.ctx, "", true);
+			this.partByItem.set(item.id, part);
+			this.textLenByItem.set(item.id, 0);
+		}
+		// Open the part only while it will keep streaming. When the item is already
+		// complete on first sight (Codex often sends only `item.completed`), emit a
+		// single finalized snapshot below: pushing both part-open and part-update
+		// for the same in-place-mutated object doubles the text, since the processor
+		// clones each at emit time and by then both read as "done".
+		if (isNew && phase !== "completed") events.push({ kind: "part-open", part });
+
+		const text = item.text ?? "";
+		const prevLen = this.textLenByItem.get(item.id) ?? 0;
+		if (text.length > prevLen) {
+			const suffix = text.slice(prevLen);
+			part.text = text;
+			this.textLenByItem.set(item.id, text.length);
+			// Skip the delta for an item that's already complete on first sight: it
+			// never opened a part, so the processor would drop the orphan delta
+			// anyway. The finalized part-update below carries the full text.
+			if (!(isNew && phase === "completed")) {
+				events.push(
+					kind === "text"
+						? { kind: "text-delta", partId: part.id, text: suffix }
+						: { kind: "reasoning-delta", partId: part.id, text: suffix },
+				);
+			}
+		}
+
+		if (phase === "completed") {
+			part.text = text || part.text;
+			part.state = "done";
+			events.push({ kind: "part-update", part });
+		}
+		return events;
+	}
+
+	private handleTool(item: ThreadItem, phase: Phase, d: CodexToolDescriptor): AdapterEvent[] {
+		const events: AdapterEvent[] = [];
+		let part = this.partByItem.get(item.id) as ToolPart | undefined;
+		const isNew = !part;
+		if (!part) {
+			part = createToolPart(this.ctx, item.id, d.toolName(item), d.input(item), d.meta(item));
+			this.partByItem.set(item.id, part);
+		}
+		// As in handleText: skip the open when the tool is already complete on
+		// arrival, so we emit one finalized snapshot rather than two aliased ones.
+		if (isNew && phase !== "completed") events.push({ kind: "part-open", part });
+		if (phase === "completed") {
+			completeToolPart(part, d.result(item));
+			events.push({ kind: "part-update", part });
+		}
+		return events;
+	}
+}
+
+export function createCodexSdkTransformer(ctx: { sessionId: string }): EventTransformer {
+	return new CodexSdkTransformer(ctx);
+}

package/src/core/agents/codex-sdk/codex-sdk-agent.ts

@@ -0,0 +1,236 @@
+import type { Codex, Thread, ThreadEvent, ThreadOptions } from "@openai/codex-sdk";
+import type { AgentCapabilities, AgentInput, PermissionMode } from "../../../protocol/index.ts";
+import { codexReasoningEffort } from "../../../protocol/index.ts";
+import type { AgentExecuteOptions, RawAgentEvent } from "../base.ts";
+import { BaseAgent } from "../base.ts";
+import { configFingerprint } from "../config-fingerprint.ts";
+
+const CAPABILITIES: AgentCapabilities = {
+	multiTurn: true,
+	sessionResume: true,
+	// A Codex thread's model/effort is fixed at creation; changing them restarts it.
+	modelSwitch: "restart-session",
+	thinkingLevels: true,
+	images: false,
+	mcpServers: false,
+	// Codex exec mode has no approval callback — the sandbox is the gate.
+	permissionRequests: false,
+};
+
+export interface LiveThread {
+	thread: Thread;
+	model?: string;
+	thinkingLevel?: string;
+	cwd: string;
+	permissionMode?: PermissionMode;
+	credentialsFingerprint: string;
+	systemPromptAppend?: string;
+	additionalDirectoriesFingerprint: string;
+}
+
+function credentialsFingerprint(options: Pick<AgentExecuteOptions, "apiKey" | "env">): string {
+	return configFingerprint({ apiKey: options.apiKey, env: options.env });
+}
+
+/** Sandbox surface identity — a changed directory set must restart the thread. */
+function directoriesFingerprint(
+	options: Pick<AgentExecuteOptions, "additionalDirectories">,
+): string {
+	// Order and duplicates don't change the sandbox surface — don't churn threads.
+	return configFingerprint([...new Set(options.additionalDirectories ?? [])].sort());
+}
+
+/**
+ * Instance identity: credentials plus constructor-level config. The SDK fixes
+ * `developer_instructions` at `new Codex(...)`, so a different append needs a
+ * different instance; the thread restarts too (`codexThreadCompatible`) but
+ * keeps its context via the auto-resume path — restart-with-resume, matching
+ * the claude-code policy for systemPromptAppend changes.
+ */
+function instanceFingerprint(
+	options: Pick<AgentExecuteOptions, "apiKey" | "env" | "systemPromptAppend">,
+): string {
+	return configFingerprint({
+		apiKey: options.apiKey,
+		env: options.env,
+		// One equality convention with codexThreadCompatible: absent == empty.
+		systemPromptAppend: options.systemPromptAppend ?? "",
+	});
+}
+
+export function codexThreadCompatible(
+	existing: LiveThread | undefined,
+	options: AgentExecuteOptions,
+): boolean {
+	return Boolean(
+		existing &&
+			existing.cwd === options.cwd &&
+			existing.model === options.model &&
+			existing.thinkingLevel === options.thinkingLevel &&
+			existing.permissionMode === options.permissionMode &&
+			existing.credentialsFingerprint === credentialsFingerprint(options) &&
+			(existing.systemPromptAppend ?? "") === (options.systemPromptAppend ?? "") &&
+			existing.additionalDirectoriesFingerprint === directoriesFingerprint(options) &&
+			(!options.resumeSessionId || options.resumeSessionId === existing.thread.id),
+	);
+}
+
+function mapSandbox(mode: PermissionMode | undefined): ThreadOptions["sandboxMode"] {
+	switch (mode) {
+		case "bypassPermissions":
+			return "danger-full-access";
+		case "acceptEdits":
+		case "dontAsk":
+			// Never-ask posture, but inside the normal sandbox — danger-full is
+			// reserved for the explicitly dangerous mode.
+			return "workspace-write";
+		default:
+			return "read-only";
+	}
+}
+
+function toCodexInput(input: AgentInput): string {
+	if (typeof input === "string") return input;
+	return input
+		.filter((p) => p.type === "text")
+		.map((p) => (p.type === "text" ? p.text : ""))
+		.join("\n\n");
+}
+
+function threadOptions(options: AgentExecuteOptions): ThreadOptions {
+	const opts: ThreadOptions = {
+		workingDirectory: options.cwd,
+		skipGitRepoCheck: true,
+		approvalPolicy: "never",
+		sandboxMode: mapSandbox(options.permissionMode),
+		...(options.additionalDirectories?.length
+			? { additionalDirectories: options.additionalDirectories }
+			: {}),
+	};
+	if (options.model) opts.model = options.model;
+	if (options.thinkingLevel)
+		opts.modelReasoningEffort = codexReasoningEffort(options.thinkingLevel);
+	return opts;
+}
+
+export interface CodexSdkAgentOptions {
+	/**
+	 * Resolve the `codex` binary to spawn (typically the provisioner's,
+	 * memoized). `undefined` defers to the SDK's own lookup. Operator-level
+	 * only — never sourced from the wire.
+	 */
+	resolveCliPath?: () => Promise<string | undefined>;
+}
+
+/**
+ * Codex harness backed by `@openai/codex-sdk` (which runs the `codex` CLI in
+ * exec mode). A `Thread` is reused per logical session for multi-turn; model or
+ * effort changes recreate it (restart-session). Resume across processes uses
+ * `resumeThread(nativeId)`. Streams at item granularity — the adapter derives
+ * text deltas by diffing successive item snapshots.
+ */
+export class CodexSdkAgent extends BaseAgent {
+	readonly harness = "codex-sdk" as const;
+	readonly capabilities = CAPABILITIES;
+	private readonly threads = new Map<string, LiveThread>();
+	// Instance-level config (credentials AND developer_instructions) is fixed
+	// at construction, so one instance per distinct (apiKey, env, append) —
+	// keying by a fingerprint prevents one session's key or instructions from
+	// bleeding into another's.
+	private readonly codexByCreds = new Map<string, Codex>();
+
+	constructor(private readonly agentOptions: CodexSdkAgentOptions = {}) {
+		super();
+	}
+
+	private async getCodex(options: AgentExecuteOptions): Promise<Codex> {
+		const fingerprint = instanceFingerprint(options);
+		const cached = this.codexByCreds.get(fingerprint);
+		if (cached) return cached;
+		const codexPathOverride = await this.agentOptions.resolveCliPath?.();
+		const { Codex } = await import("@openai/codex-sdk");
+		const codex = new Codex({
+			...(codexPathOverride ? { codexPathOverride } : {}),
+			...(options.apiKey ? { apiKey: options.apiKey } : {}),
+			...(options.env ? { env: { ...process.env, ...options.env } as Record<string, string> } : {}),
+			...(options.systemPromptAppend
+				? { config: { developer_instructions: options.systemPromptAppend } }
+				: {}),
+		});
+		this.codexByCreds.set(fingerprint, codex);
+		return codex;
+	}
+
+	private async resolveThread(options: AgentExecuteOptions): Promise<LiveThread> {
+		const existing = this.threads.get(options.sessionId);
+		const effort = options.thinkingLevel;
+		if (existing && codexThreadCompatible(existing, options)) return existing;
+
+		const codex = await this.getCodex(options);
+		const fingerprint = credentialsFingerprint(options);
+		// Preserve context within the same cwd/credential boundary (mirrors the
+		// claude-code restart policy); an explicit resumeSessionId always wins.
+		const resumeThreadId =
+			options.resumeSessionId ??
+			(existing && existing.cwd === options.cwd && existing.credentialsFingerprint === fingerprint
+				? existing.thread.id
+				: undefined);
+		const thread = resumeThreadId
+			? codex.resumeThread(resumeThreadId, threadOptions(options))
+			: codex.startThread(threadOptions(options));
+		const live: LiveThread = {
+			thread,
+			model: options.model,
+			thinkingLevel: effort,
+			cwd: options.cwd,
+			permissionMode: options.permissionMode,
+			credentialsFingerprint: fingerprint,
+			systemPromptAppend: options.systemPromptAppend,
+			additionalDirectoriesFingerprint: directoriesFingerprint(options),
+		};
+		this.threads.set(options.sessionId, live);
+		return live;
+	}
+
+	async *execute(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+	): AsyncIterableIterator<RawAgentEvent> {
+		const controller = this.trackTurn(options.sessionId, options.signal);
+		try {
+			const live = await this.resolveThread(options);
+			// Codex keeps the thread id on resume, so honored = same id came back.
+			const resumeInfo = (id: string) => ({ resumed: id === options.resumeSessionId });
+			if (live.thread.id) options.onNativeSession?.(live.thread.id, resumeInfo(live.thread.id));
+
+			const { events } = await live.thread.runStreamed(toCodexInput(input), {
+				signal: controller.signal,
+			});
+
+			let reported = Boolean(live.thread.id);
+			for await (const event of events as AsyncGenerator<ThreadEvent>) {
+				if (!reported && event.type === "thread.started" && event.thread_id) {
+					reported = true;
+					options.onNativeSession?.(event.thread_id, resumeInfo(event.thread_id));
+				}
+				yield event as RawAgentEvent;
+			}
+			// thread.id is populated once the turn has started.
+			if (!reported && live.thread.id)
+				options.onNativeSession?.(live.thread.id, resumeInfo(live.thread.id));
+		} finally {
+			this.endTurn(options.sessionId, controller);
+		}
+	}
+
+	override async release(sessionId: string): Promise<void> {
+		await super.release(sessionId);
+		this.threads.delete(sessionId);
+	}
+
+	override async terminateAll(): Promise<void> {
+		await super.terminateAll();
+		this.threads.clear();
+		this.codexByCreds.clear();
+	}
+}

package/src/core/agents/config-fingerprint.ts

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+
+function canonicalize(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value as Record<string, unknown>)
+				.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+				.map(([key, item]) => [key, canonicalize(item)]),
+		);
+	}
+	return value;
+}
+
+/** Stable, non-reversible identity for config that may contain credentials. */
+export function configFingerprint(value: unknown): string {
+	const canonical = JSON.stringify(canonicalize(value)) ?? "undefined";
+	return createHash("sha256").update(canonical).digest("hex");
+}

package/src/core/agents/error-classifier.ts

@@ -0,0 +1,68 @@
+/**
+ * Maps a raw harness error into a stable category, so callers can react
+ * (retry on `network`/`rate_limit`, surface `auth` prominently, treat `abort`
+ * as success). Distilled from deus-machine's lifecycle classifier.
+ */
+export const ERROR_CATEGORIES = [
+	"auth",
+	"rate_limit",
+	"context_limit",
+	"network",
+	"abort",
+	"process_exit",
+	"usage_limit",
+	"unknown",
+] as const;
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+
+const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
+	["abort", ["aborted", "aborterror", "cancelled", "canceled", "interrupted", "sigint"]],
+	[
+		"auth",
+		[
+			"unauthorized",
+			"401",
+			"authentication",
+			"invalid api key",
+			"invalid_api_key",
+			"not logged in",
+			"login required",
+			"forbidden",
+			"403",
+		],
+	],
+	["rate_limit", ["rate limit", "rate_limit", "429", "too many requests"]],
+	["usage_limit", ["usage limit", "quota", "insufficient_quota", "billing", "credit"]],
+	["context_limit", ["context length", "context_length", "maximum context", "too many tokens"]],
+	[
+		"network",
+		[
+			"econnrefused",
+			"econnreset",
+			"etimedout",
+			"enotfound",
+			"network",
+			"fetch failed",
+			"socket hang up",
+		],
+	],
+	["process_exit", ["exited with code", "process exited", "spawn", "enoent", "killed"]],
+];
+
+export function classifyError(error: unknown): ErrorCategory {
+	const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+	for (const [category, needles] of RULES) {
+		if (needles.some((n) => message.includes(n))) return category;
+	}
+	return "unknown";
+}
+
+/** Whether a turn can plausibly be retried after this error. */
+export function isRecoverable(category: ErrorCategory): boolean {
+	return category === "rate_limit" || category === "network";
+}
+
+/** Abort is a user action, not a failure to report. */
+export function isCancellation(error: unknown): boolean {
+	return classifyError(error) === "abort";
+}

package/src/core/agents/registry.ts

@@ -0,0 +1,40 @@
+import type { AgentHarness } from "../../protocol/index.ts";
+import { HarnessNotFoundError } from "../utils/errors.ts";
+import type { Agent } from "./base.ts";
+import type { AdapterFactory } from "./types.ts";
+
+/** Pairs each harness with its agent implementation and event adapter. */
+export class AgentRegistry {
+	private readonly agents = new Map<AgentHarness, Agent>();
+	private readonly adapters = new Map<AgentHarness, AdapterFactory>();
+
+	register(agent: Agent, adapter: AdapterFactory): this {
+		this.agents.set(agent.harness, agent);
+		this.adapters.set(agent.harness, adapter);
+		return this;
+	}
+
+	getAgent(harness: AgentHarness): Agent {
+		const agent = this.agents.get(harness);
+		if (!agent) throw new HarnessNotFoundError(harness);
+		return agent;
+	}
+
+	getAdapter(harness: AgentHarness): AdapterFactory {
+		const adapter = this.adapters.get(harness);
+		if (!adapter) throw new HarnessNotFoundError(harness);
+		return adapter;
+	}
+
+	has(harness: AgentHarness): boolean {
+		return this.agents.has(harness);
+	}
+
+	list(): AgentHarness[] {
+		return [...this.agents.keys()];
+	}
+
+	async terminateAll(): Promise<void> {
+		await Promise.all([...this.agents.values()].map((a) => a.terminateAll()));
+	}
+}

package/src/core/agents/session-store.ts

@@ -0,0 +1,72 @@
+/** The slice of a session a SessionStore manages: a closable client + idle timer. */
+export interface StoredSession {
+	client: { closed: boolean; close(): void };
+	idleTimer?: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Per-logical-session bookkeeping shared by subprocess-backed harnesses
+ * (codex-app-server, acp): the sessionId → session map, idle-eviction timers,
+ * self-healing when a client dies underneath us, and whole-store teardown.
+ * Harnesses own what a session *is*; this owns when one goes away.
+ */
+export class SessionStore<S extends StoredSession> {
+	private readonly sessions = new Map<string, S>();
+
+	get(sessionId: string): S | undefined {
+		return this.sessions.get(sessionId);
+	}
+
+	set(sessionId: string, session: S): void {
+		this.sessions.set(sessionId, session);
+	}
+
+	values(): IterableIterator<S> {
+		return this.sessions.values();
+	}
+
+	/** Self-heal: drop the mapping when this exact client closed underneath us. */
+	dropIfCurrent(sessionId: string, client: S["client"]): void {
+		const current = this.sessions.get(sessionId);
+		if (current && current.client === client) {
+			this.clearIdle(current);
+			this.sessions.delete(sessionId);
+		}
+	}
+
+	/** Tear down one session: cancel its idle timer, unmap it, close its client. */
+	close(sessionId: string): void {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		this.clearIdle(session);
+		this.sessions.delete(sessionId);
+		session.client.close();
+	}
+
+	/** Tear down every session (process shutdown). */
+	closeAll(): void {
+		for (const session of this.sessions.values()) {
+			this.clearIdle(session);
+			session.client.close();
+		}
+		this.sessions.clear();
+	}
+
+	/** Shut the session down after `idleMs` unless another turn claims it first. */
+	armIdle(sessionId: string, session: S, idleMs: number): void {
+		this.clearIdle(session);
+		session.idleTimer = setTimeout(() => {
+			if (this.sessions.get(sessionId) !== session) return;
+			this.sessions.delete(sessionId);
+			session.client.close();
+		}, idleMs);
+		session.idleTimer.unref?.();
+	}
+
+	clearIdle(session: S): void {
+		if (session.idleTimer) {
+			clearTimeout(session.idleTimer);
+			session.idleTimer = undefined;
+		}
+	}
+}