@zvada/agent-server 0.2.0

package/src/core/agents/codex-app-server/adapter.ts

@@ -0,0 +1,214 @@
+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 `codex app-server` v2 notifications into AdapterEvents. This harness
+ * streams token-level deltas (item/agentMessage/delta, item/reasoning/*Delta),
+ * so unlike the Codex SDK adapter no diffing is needed. Items carry camelCase
+ * fields. Tool-like items (commandExecution/fileChange/mcpToolCall/webSearch)
+ * become tool parts that complete on item/completed.
+ */
+
+/** One app-server item: the shared codex tool vocabulary plus streaming fields. */
+interface CodexItem extends CodexToolItem {
+	type: string;
+	text?: string;
+}
+interface Notification {
+	method: string;
+	params: {
+		item?: CodexItem;
+		itemId?: string;
+		delta?: string;
+		tokenUsage?: {
+			total?: Record<string, number>;
+			last?: Record<string, number>;
+			modelContextWindow?: number;
+		};
+		turn?: { error?: { message?: string } | null };
+		error?: { message?: string; additionalDetails?: string | null };
+		willRetry?: boolean;
+		message?: string;
+	};
+}
+
+export class CodexAppServerTransformer implements EventTransformer<unknown> {
+	private readonly ctx: StreamContext;
+	private readonly partByItem = new Map<string, Part>();
+
+	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 { method, params } = raw as Notification;
+		switch (method) {
+			case "item/started":
+				return params.item ? this.openItem(params.item) : [];
+			case "item/completed":
+				return params.item ? this.completeItem(params.item) : [];
+			case "item/agentMessage/delta":
+				return this.textDelta(params.itemId, params.delta, "text");
+			case "item/reasoning/textDelta":
+			case "item/reasoning/summaryTextDelta":
+				return this.textDelta(params.itemId, params.delta, "reasoning");
+			case "thread/tokenUsage/updated": {
+				this.captureUsage(params.tokenUsage?.total);
+				const total = params.tokenUsage?.total;
+				if (!total) return [];
+				const used =
+					total.totalTokens ??
+					(total.inputTokens ?? 0) + (total.cachedInputTokens ?? 0) + (total.outputTokens ?? 0);
+				const size = params.tokenUsage?.modelContextWindow;
+				return [{ kind: "usage", used, ...(size !== undefined && { size }) }];
+			}
+			case "turn/completed":
+				// (A pre-completion non-retry `error` cannot reach here in practice:
+				// the agent's queue ends the turn on that notification.)
+				if (params.turn?.error) this.error = params.turn.error.message ?? "codex turn error";
+				this.finishReason = this.error ? "error" : "completed";
+				if (!this.error) this.stopReason = "end_turn";
+				return [];
+			case "error":
+				// v2 errors carry a nested TurnError and may be transient. A retrying
+				// notification is diagnostic only; turn/completed remains authoritative.
+				if (params.willRetry) return [];
+				this.error = params.error?.message ?? params.message ?? "codex app-server error";
+				this.finishReason = "error";
+				return [];
+			default:
+				return [];
+		}
+	}
+
+	finish(): TransformResult {
+		return {
+			usage: this.usage,
+			stopReason: this.stopReason,
+			finishReason: this.finishReason,
+			error: this.error,
+		};
+	}
+
+	private openItem(item: CodexItem): AdapterEvent[] {
+		switch (item.type) {
+			case "agentMessage": {
+				const part = createTextPart(this.ctx, item.text ?? "", true);
+				this.partByItem.set(item.id, part);
+				return [{ kind: "part-open", part }];
+			}
+			case "reasoning": {
+				const part = createReasoningPart(this.ctx, item.text ?? "", true);
+				this.partByItem.set(item.id, part);
+				return [{ kind: "part-open", part }];
+			}
+			default: {
+				// commandExecution / fileChange / mcpToolCall / webSearch share one
+				// descriptor vocabulary; userMessage and unknown item types produce
+				// no assistant output.
+				const d = codexToolDescriptor(item.type);
+				return d ? this.openTool(item, d) : [];
+			}
+		}
+	}
+
+	private completeItem(item: CodexItem): AdapterEvent[] {
+		const part = this.partByItem.get(item.id);
+		switch (item.type) {
+			case "agentMessage":
+			case "reasoning": {
+				const p = (part ??
+					(item.type === "agentMessage"
+						? createTextPart(this.ctx, item.text ?? "", true)
+						: createReasoningPart(this.ctx, item.text ?? "", true))) as TextPart | ReasoningPart;
+				if (item.text !== undefined) p.text = item.text;
+				p.state = "done";
+				if (!part) this.partByItem.set(item.id, p);
+				return [{ kind: "part-update", part: p }];
+			}
+			default: {
+				const d = codexToolDescriptor(item.type);
+				if (!d) return [];
+				const tool = this.ensureTool(item, d);
+				completeToolPart(tool, d.result(item));
+				return [{ kind: "part-update", part: tool }];
+			}
+		}
+	}
+
+	private textDelta(
+		itemId: string | undefined,
+		delta: string | undefined,
+		kind: "text" | "reasoning",
+	): AdapterEvent[] {
+		if (!itemId || !delta) return [];
+		const events: AdapterEvent[] = [];
+		let part = this.partByItem.get(itemId) as TextPart | ReasoningPart | undefined;
+		if (!part) {
+			part =
+				kind === "text"
+					? createTextPart(this.ctx, "", true)
+					: createReasoningPart(this.ctx, "", true);
+			this.partByItem.set(itemId, part);
+			events.push({ kind: "part-open", part });
+		}
+		part.text += delta;
+		events.push(
+			kind === "text"
+				? { kind: "text-delta", partId: part.id, text: delta }
+				: { kind: "reasoning-delta", partId: part.id, text: delta },
+		);
+		return events;
+	}
+
+	private openTool(item: CodexItem, d: CodexToolDescriptor): AdapterEvent[] {
+		const part = createToolPart(this.ctx, item.id, d.toolName(item), d.input(item), d.meta(item));
+		this.partByItem.set(item.id, part);
+		return [{ kind: "part-open", part }];
+	}
+
+	private ensureTool(item: CodexItem, d: CodexToolDescriptor): ToolPart {
+		const existing = this.partByItem.get(item.id) as ToolPart | undefined;
+		if (existing) return existing;
+		const part = createToolPart(this.ctx, item.id, d.toolName(item), d.input(item), d.meta(item));
+		this.partByItem.set(item.id, part);
+		return part;
+	}
+
+	private captureUsage(total: Record<string, number> | undefined): void {
+		if (!total) return;
+		this.usage = {
+			input: total.inputTokens ?? 0,
+			output: total.outputTokens ?? 0,
+			reasoning: total.reasoningOutputTokens ?? total.reasoningTokens ?? 0,
+			cache: { read: total.cachedInputTokens ?? 0, write: 0 },
+		};
+	}
+}
+
+export function createCodexAppServerTransformer(ctx: { sessionId: string }): EventTransformer {
+	return new CodexAppServerTransformer(ctx);
+}

package/src/core/agents/codex-app-server/client.ts

@@ -0,0 +1,221 @@
+import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+
+/** A JSON-RPC notification (server → client, no id). */
+export interface CodexNotification {
+	method: string;
+	params: Record<string, unknown> & { threadId?: string; turnId?: string };
+}
+type NotificationHandler = (n: CodexNotification) => void;
+
+/** Answers a server→client request (approvals). Throwing rejects the request. */
+export type ServerRequestHandler = (
+	method: string,
+	params: Record<string, unknown>,
+) => Promise<unknown>;
+
+interface PendingRequest {
+	method: string;
+	resolve: (value: unknown) => void;
+	reject: (error: Error) => void;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+interface RpcResponse {
+	id: number;
+	result?: unknown;
+	error?: { code?: number; message?: string };
+}
+
+export interface CodexAppServerClientOptions {
+	codexPath?: string;
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	startupTimeoutMs?: number;
+	/** Default deadline for every JSON-RPC request. */
+	requestTimeoutMs?: number;
+	/** Injectable process boundary for deterministic tests. */
+	spawnProcess?: typeof nodeSpawn;
+}
+
+/**
+ * Newline-delimited (JSONL) JSON-RPC client over a `codex app-server` subprocess.
+ * Requests get monotonic ids resolved against a pending map; notifications fan
+ * out to handlers. Inbound server→client requests (approvals) go to the
+ * registered request handler; without one they are declined (-32601).
+ */
+export class CodexAppServerClient {
+	private proc?: ChildProcess;
+	private nextId = 1;
+	private buffer = "";
+	private readonly decoder = new StringDecoder("utf8");
+	private readonly pending = new Map<number, PendingRequest>();
+	private readonly handlers = new Set<NotificationHandler>();
+	private readonly closeHandlers = new Set<(error?: Error) => void>();
+	private requestHandler?: ServerRequestHandler;
+	private exited = false;
+
+	constructor(private readonly opts: CodexAppServerClientOptions = {}) {}
+
+	onNotification(handler: NotificationHandler): () => void {
+		this.handlers.add(handler);
+		return () => this.handlers.delete(handler);
+	}
+
+	/** Install the answerer for server→client requests (approval round-trips). */
+	setRequestHandler(handler: ServerRequestHandler | undefined): void {
+		this.requestHandler = handler;
+	}
+
+	/** Fires when the subprocess exits or the client is closed — lets callers
+	 * unblock any in-flight turn instead of waiting on notifications that will
+	 * never arrive. */
+	onClose(handler: (error?: Error) => void): () => void {
+		this.closeHandlers.add(handler);
+		return () => this.closeHandlers.delete(handler);
+	}
+
+	get closed(): boolean {
+		return this.exited;
+	}
+
+	async initialize(): Promise<void> {
+		this.start();
+		await this.request(
+			"initialize",
+			{
+				clientInfo: { name: "agent-server", title: null, version: "0.1.0" },
+				capabilities: null,
+			},
+			this.opts.startupTimeoutMs ?? 15_000,
+		);
+	}
+
+	request(method: string, params: unknown, timeoutMs?: number): Promise<unknown> {
+		if (!this.proc || this.exited) return Promise.reject(new Error("codex app-server not running"));
+		const id = this.nextId++;
+		return new Promise<unknown>((resolve, reject) => {
+			const deadline = timeoutMs ?? this.opts.requestTimeoutMs ?? 30_000;
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`codex app-server '${method}' timed out`));
+			}, deadline);
+			this.pending.set(id, { method, resolve, reject, timer });
+			try {
+				this.write({ id, method, params });
+			} catch (error) {
+				clearTimeout(timer);
+				this.pending.delete(id);
+				reject(error);
+			}
+		});
+	}
+
+	close(): void {
+		const proc = this.proc;
+		const wasOpen = !this.exited;
+		this.proc = undefined;
+		this.exited = true;
+		for (const [id, p] of this.pending) {
+			if (p.timer) clearTimeout(p.timer);
+			p.reject(new Error(`codex app-server closed before '${p.method}'`));
+			this.pending.delete(id);
+		}
+		if (proc && !proc.killed) proc.kill("SIGTERM");
+		if (wasOpen) this.notifyClosed();
+	}
+
+	private notifyClosed(error?: Error): void {
+		for (const handler of this.closeHandlers) handler(error);
+		this.closeHandlers.clear();
+	}
+
+	private start(): void {
+		if (this.proc && !this.exited) return;
+		this.exited = false;
+		const spawnProcess = this.opts.spawnProcess ?? nodeSpawn;
+		const proc = spawnProcess(this.opts.codexPath ?? "codex", ["app-server"], {
+			cwd: this.opts.cwd,
+			env: this.opts.env ?? process.env,
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		this.proc = proc;
+		proc.stdout?.on("data", (chunk: Buffer) => this.onStdout(chunk));
+		proc.stdin?.on("error", (err) => this.onExit(err));
+		proc.stdout?.on("error", (err) => this.onExit(err));
+		proc.stderr?.on("data", () => {});
+		proc.on("error", (err) => this.onExit(err));
+		proc.on("exit", (code, signal) =>
+			this.onExit(new Error(`codex app-server exited (code=${code} signal=${signal})`)),
+		);
+	}
+
+	private onStdout(chunk: Buffer): void {
+		this.buffer += this.decoder.write(chunk);
+		let nl = this.buffer.indexOf("\n");
+		while (nl !== -1) {
+			const line = this.buffer.slice(0, nl).trim();
+			this.buffer = this.buffer.slice(nl + 1);
+			if (line) {
+				try {
+					this.handleMessage(JSON.parse(line));
+				} catch {
+					// ignore non-JSON lines
+				}
+			}
+			nl = this.buffer.indexOf("\n");
+		}
+	}
+
+	private handleMessage(msg: unknown): void {
+		if (!msg || typeof msg !== "object") return;
+		const m = msg as { id?: number; method?: string; params?: unknown } & RpcResponse;
+		if (typeof m.id === "number" && m.method === undefined) {
+			const pending = this.pending.get(m.id);
+			if (!pending) return;
+			this.pending.delete(m.id);
+			if (pending.timer) clearTimeout(pending.timer);
+			if (m.error) pending.reject(new Error(m.error.message ?? `error from '${pending.method}'`));
+			else pending.resolve(m.result);
+			return;
+		}
+		if (typeof m.method === "string") {
+			if (typeof m.id === "number") {
+				// Server→client request (approvals). Route to the handler; decline
+				// when none is installed (approvalPolicy "never" turns).
+				const handler = this.requestHandler;
+				const id = m.id;
+				if (!handler) {
+					this.write({ id, error: { code: -32601, message: `unsupported: ${m.method}` } });
+					return;
+				}
+				void handler(m.method, (m.params ?? {}) as Record<string, unknown>)
+					.then((result) => this.write({ id, result }))
+					.catch((err: unknown) =>
+						this.write({ id, error: { code: -32603, message: String(err) } }),
+					);
+				return;
+			}
+			const notification: CodexNotification = {
+				method: m.method,
+				params: (m.params ?? {}) as CodexNotification["params"],
+			};
+			for (const handler of this.handlers) handler(notification);
+		}
+	}
+
+	private onExit(error: Error): void {
+		if (this.exited) return;
+		this.exited = true;
+		for (const [id, p] of this.pending) {
+			if (p.timer) clearTimeout(p.timer);
+			p.reject(error);
+			this.pending.delete(id);
+		}
+		this.notifyClosed(error);
+	}
+
+	private write(payload: unknown): void {
+		this.proc?.stdin?.write(`${JSON.stringify(payload)}\n`);
+	}
+}