@zvada/agent-server 0.2.0

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

@@ -0,0 +1,385 @@
+import type {
+	AgentCapabilities,
+	AgentInput,
+	PermissionMode,
+	PermissionToolCall,
+} from "../../../protocol/index.ts";
+import { AsyncQueue, codexReasoningEffort } from "../../../protocol/index.ts";
+import type { AgentExecuteOptions, PermissionRequestHandler, RawAgentEvent } from "../base.ts";
+import { BaseAgent } from "../base.ts";
+import { configFingerprint } from "../config-fingerprint.ts";
+import { SessionStore } from "../session-store.ts";
+import {
+	CodexAppServerClient,
+	type CodexAppServerClientOptions,
+	type CodexNotification,
+} from "./client.ts";
+
+const CAPABILITIES: AgentCapabilities = {
+	multiTurn: true,
+	sessionResume: true,
+	// Model/effort are overridable per turn/start, so no restart is needed.
+	modelSwitch: "in-session",
+	thinkingLevels: true,
+	images: true,
+	mcpServers: false,
+	permissionRequests: true,
+};
+
+export interface AppServerSession {
+	client: CodexAppServerClient;
+	threadId: string;
+	cwd: string;
+	approvalPolicy: string;
+	sandbox: string;
+	systemPromptAppend?: string;
+	envFingerprint: string;
+	/** Engine permission broker for the CURRENT turn (set per execute). */
+	permissionHandler?: PermissionRequestHandler;
+	idleTimer?: ReturnType<typeof setTimeout>;
+}
+
+export function appServerSessionCompatible(
+	existing: AppServerSession | undefined,
+	options: AgentExecuteOptions,
+): boolean {
+	return Boolean(
+		existing &&
+			!existing.client.closed &&
+			existing.cwd === options.cwd &&
+			existing.approvalPolicy === approvalPolicyFor(options) &&
+			existing.sandbox === mapSandbox(options.permissionMode) &&
+			(existing.systemPromptAppend ?? "") === (options.systemPromptAppend ?? "") &&
+			existing.envFingerprint === configFingerprint(options.env) &&
+			(!options.resumeSessionId || options.resumeSessionId === existing.threadId),
+	);
+}
+
+type UserInput = { type: "text"; text: string; text_elements: [] } | { type: "image"; url: string };
+
+function mapSandbox(mode: PermissionMode | undefined): string {
+	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 toUserInput(input: AgentInput): UserInput[] {
+	if (typeof input === "string") return [{ type: "text", text: input, text_elements: [] }];
+	const out: UserInput[] = [];
+	for (const part of input) {
+		if (part.type === "text") out.push({ type: "text", text: part.text, text_elements: [] });
+		else if (part.url) out.push({ type: "image", url: part.url });
+	}
+	return out.length ? out : [{ type: "text", text: "", text_elements: [] }];
+}
+
+/**
+ * Ask-the-user only makes sense in `default` mode with an engine broker
+ * attached; every other posture auto-decides (sandbox enforces safety).
+ */
+function approvalPolicyFor(options: AgentExecuteOptions): string {
+	const asks = (options.permissionMode ?? "default") === "default";
+	return asks && options.onPermissionRequest ? "on-request" : "never";
+}
+
+/** Normalize a codex approval request into the engine's PermissionToolCall. */
+function approvalToolCall(method: string, params: Record<string, unknown>): PermissionToolCall {
+	const id =
+		(typeof params.itemId === "string" && params.itemId) ||
+		(typeof params.callId === "string" && params.callId) ||
+		"approval";
+	const reason = typeof params.reason === "string" ? params.reason : undefined;
+	if (method.includes("commandExecution") || method === "execCommandApproval") {
+		const command = Array.isArray(params.command)
+			? (params.command as string[]).join(" ")
+			: typeof params.command === "string"
+				? params.command
+				: "";
+		return {
+			toolCallId: id,
+			toolName: "shell",
+			kind: "execute",
+			...(reason && { title: reason }),
+			rawInput: { command, ...(params.cwd ? { cwd: params.cwd } : {}) },
+		};
+	}
+	// v1 ApplyPatchApprovalParams carries `fileChanges`; v2
+	// FileChangeRequestApprovalParams does not (only itemId/reason/grantRoot),
+	// so `locations` is best-effort and may be empty for v2 edits.
+	const changes = (params.fileChanges ?? params.changes ?? {}) as Record<string, unknown>;
+	const paths = Object.keys(changes);
+	return {
+		toolCallId: id,
+		toolName: "apply_patch",
+		kind: "edit",
+		...(reason && { title: reason }),
+		...(paths.length && { locations: paths.map((path) => ({ path })) }),
+		rawInput: { changes },
+	};
+}
+
+/** Idle time before an unused app-server subprocess is shut down. */
+const IDLE_TIMEOUT_MS = 5 * 60_000;
+
+/** How long a retryable error may go unanswered before the turn is failed. */
+const RETRY_STALL_TIMEOUT_MS = 120_000;
+
+export interface CodexAppServerAgentOptions {
+	createClient?: (options: CodexAppServerClientOptions) => CodexAppServerClient;
+	idleTimeoutMs?: number;
+	/** Fail a turn if the app-server goes silent this long after a retryable error. */
+	retryStallTimeoutMs?: number;
+	/**
+	 * Resolve the `codex` binary to spawn (typically the provisioner's,
+	 * memoized). Falls back to `$CODEX_CLI_PATH`, then PATH. Operator-level
+	 * only — never sourced from the wire.
+	 */
+	resolveCliPath?: () => Promise<string | undefined>;
+}
+
+/** Retryable v2 `error` notifications do not end the turn; Codex keeps going. */
+export function appServerNotificationEndsTurn(notification: CodexNotification): boolean {
+	return (
+		notification.method === "turn/completed" ||
+		(notification.method === "error" && notification.params.willRetry !== true)
+	);
+}
+
+/**
+ * Codex harness backed by a long-lived `codex app-server` subprocess speaking
+ * JSON-RPC. Unlike the SDK harness this streams token-level deltas. A client +
+ * thread is created per logical session and reused for multi-turn; model/effort
+ * are passed per `turn/start`. Resume uses `thread/resume` with the native id.
+ */
+export class CodexAppServerAgent extends BaseAgent {
+	readonly harness = "codex-app-server" as const;
+	readonly capabilities = CAPABILITIES;
+	private readonly sessions = new SessionStore<AppServerSession>();
+
+	constructor(private readonly agentOptions: CodexAppServerAgentOptions = {}) {
+		super();
+	}
+
+	private async resolveSession(options: AgentExecuteOptions): Promise<AppServerSession> {
+		const approvalPolicy = approvalPolicyFor(options);
+		const sandbox = mapSandbox(options.permissionMode);
+		const existing = this.sessions.get(options.sessionId);
+		// Reuse a warm subprocess only when its (immutable) approval posture
+		// matches; otherwise recreate it, resuming the same thread so context
+		// survives. `resumeThreadId` carries that over to the spawn below.
+		let resumeThreadId = options.resumeSessionId;
+		if (existing && !existing.client.closed) {
+			if (appServerSessionCompatible(existing, options)) {
+				this.sessions.clearIdle(existing);
+				return existing;
+			}
+			// Preserve context within the same cwd/env boundary (mirrors the
+			// claude-code restart policy); an explicit resumeSessionId always wins.
+			if (
+				resumeThreadId === undefined &&
+				existing.cwd === options.cwd &&
+				existing.envFingerprint === configFingerprint(options.env)
+			) {
+				resumeThreadId = existing.threadId;
+			}
+			this.sessions.close(options.sessionId);
+		}
+
+		const clientOptions: CodexAppServerClientOptions = {
+			codexPath:
+				(await this.agentOptions.resolveCliPath?.()) ?? process.env.CODEX_CLI_PATH ?? "codex",
+			cwd: options.cwd,
+			env: options.env ? ({ ...process.env, ...options.env } as NodeJS.ProcessEnv) : process.env,
+		};
+		const client =
+			this.agentOptions.createClient?.(clientOptions) ?? new CodexAppServerClient(clientOptions);
+		// Self-heal: if the subprocess ever exits, drop it so the next turn respawns.
+		client.onClose(() => this.sessions.dropIfCurrent(options.sessionId, client));
+		await client.initialize();
+
+		const startParams: Record<string, unknown> = {
+			cwd: options.cwd,
+			sandbox,
+			approvalPolicy,
+			experimentalRawEvents: false,
+			persistExtendedHistory: false,
+		};
+		if (options.model) startParams.model = options.model;
+		if (options.systemPromptAppend) startParams.developerInstructions = options.systemPromptAppend;
+
+		// A dead/unknown resume target ("no rollout found ...") must not kill the
+		// turn: ANY resume failure falls back to a fresh thread, and the fresh id
+		// ≠ requested id makes execute() report resumed:false — the structured
+		// fallback signal (claude/acp parity). Systemic failures (auth, dead
+		// subprocess) fail thread/start identically, so nothing is masked.
+		const startThread = async (): Promise<string> => {
+			const r = (await client.request("thread/start", startParams)) as {
+				thread?: { id?: string };
+			};
+			if (!r?.thread?.id) throw new Error("codex app-server thread/start returned no thread id");
+			return r.thread.id;
+		};
+		let threadId: string | undefined;
+		if (resumeThreadId) {
+			threadId = await client
+				.request("thread/resume", { threadId: resumeThreadId, ...startParams })
+				.then((r) => (r as { thread?: { id?: string } })?.thread?.id ?? resumeThreadId)
+				.catch(() => undefined);
+		}
+		threadId ??= await startThread();
+
+		const session: AppServerSession = {
+			client,
+			threadId,
+			cwd: options.cwd,
+			approvalPolicy,
+			sandbox,
+			systemPromptAppend: options.systemPromptAppend,
+			envFingerprint: configFingerprint(options.env),
+		};
+		// Approval requests (server→client) resolve against the engine broker of
+		// whichever turn is current; thread mismatches and broker-less turns decline.
+		client.setRequestHandler(async (method, params) => {
+			const requestThread = params.threadId ?? params.conversationId;
+			const v2 = method.startsWith("item/");
+			const decline = v2 ? { decision: "decline" } : { decision: "denied" };
+			if (requestThread && requestThread !== session.threadId) return decline;
+			const handler = session.permissionHandler;
+			if (!handler) return decline;
+			const decision = await handler(approvalToolCall(method, params));
+			switch (decision.decision) {
+				case "allow":
+					return v2 ? { decision: "accept" } : { decision: "approved" };
+				case "cancel":
+					return v2 ? { decision: "cancel" } : { decision: "abort" };
+				default:
+					return decline;
+			}
+		});
+		this.sessions.set(options.sessionId, session);
+		return session;
+	}
+
+	async *execute(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+	): AsyncIterableIterator<RawAgentEvent> {
+		const controller = this.trackTurn(options.sessionId, options.signal);
+		const queue = new AsyncQueue<CodexNotification>();
+		// A retryable error promises more notifications. If none arrive, the
+		// subprocess is wedged-but-alive and the turn would hang forever — bound it.
+		let stallTimer: ReturnType<typeof setTimeout> | undefined;
+		const clearStall = () => {
+			if (stallTimer) clearTimeout(stallTimer);
+			stallTimer = undefined;
+		};
+		const unsubscribe: Array<() => void> = [];
+		let session: AppServerSession | undefined;
+		try {
+			session = await this.resolveSession(options);
+			session.permissionHandler = options.onPermissionRequest;
+			options.onNativeSession?.(session.threadId, {
+				resumed: session.threadId === options.resumeSessionId,
+			});
+			const threadId = session.threadId;
+			const client = session.client;
+
+			let turnId: string | undefined;
+			let aborted = false;
+			const interrupt = () => {
+				if (turnId) {
+					void client.request("turn/interrupt", { threadId, turnId }).catch(() => {});
+				}
+			};
+
+			unsubscribe.push(
+				client.onNotification((n) => {
+					if (n.params.threadId && n.params.threadId !== threadId) return;
+					if (n.method === "turn/started") {
+						const turn = n.params.turn as { id?: string } | undefined;
+						if (turn?.id) {
+							turnId = turn.id;
+							if (aborted) interrupt(); // abort arrived before the turn id was known
+						}
+					}
+					queue.push(n);
+					if (appServerNotificationEndsTurn(n)) queue.end();
+					if (n.method === "error" && n.params.willRetry === true) {
+						clearStall();
+						stallTimer = setTimeout(
+							() => queue.fail(new Error("codex app-server went silent after a retryable error")),
+							this.agentOptions.retryStallTimeoutMs ?? RETRY_STALL_TIMEOUT_MS,
+						);
+						stallTimer.unref?.();
+					} else {
+						clearStall();
+					}
+				}),
+			);
+			// If the subprocess dies mid-turn, fail the turn instead of hanging.
+			unsubscribe.push(
+				client.onClose((err) => queue.fail(err ?? new Error("codex app-server exited mid-turn"))),
+			);
+
+			controller.signal.addEventListener(
+				"abort",
+				() => {
+					aborted = true;
+					interrupt();
+					// Surface as a cancellation: the runtime classifies this as aborted.
+					queue.fail(new Error("turn aborted"));
+				},
+				{ once: true },
+			);
+
+			const turnParams: Record<string, unknown> = {
+				threadId,
+				input: toUserInput(input),
+			};
+			if (options.model) turnParams.model = options.model;
+			if (options.thinkingLevel) turnParams.effort = codexReasoningEffort(options.thinkingLevel);
+
+			client.request("turn/start", turnParams).catch((err: unknown) => {
+				queue.push({ method: "error", params: { message: String(err) } });
+				queue.end();
+			});
+
+			for await (const notification of queue) {
+				yield notification as RawAgentEvent;
+			}
+		} finally {
+			clearStall();
+			for (const off of unsubscribe) off();
+			this.endTurn(options.sessionId, controller);
+			if (session && !session.client.closed) {
+				this.sessions.armIdle(
+					options.sessionId,
+					session,
+					this.agentOptions.idleTimeoutMs ?? IDLE_TIMEOUT_MS,
+				);
+			}
+		}
+	}
+
+	override async cancel(sessionId: string): Promise<void> {
+		await super.cancel(sessionId);
+	}
+
+	override async release(sessionId: string): Promise<void> {
+		await super.release(sessionId);
+		this.sessions.close(sessionId);
+	}
+
+	override async terminateAll(): Promise<void> {
+		await super.terminateAll();
+		this.sessions.closeAll();
+	}
+}

package/src/core/agents/codex-items.ts

@@ -0,0 +1,122 @@
+import type { ToolMeta } from "../../protocol/index.ts";
+import { CODEX_TOOL_KINDS, codexFileChangeLocations } from "./tool-meta.ts";
+
+/**
+ * The codex tool-item vocabulary, shared by the Codex SDK adapter
+ * (snake_case fields) and the app-server adapter (camelCase fields, with
+ * snake_case fallbacks for older payloads). Descriptors are pure: adapters
+ * keep their own streaming mechanics and call these for naming, input/meta
+ * shaping, and completion-result extraction.
+ */
+export interface CodexToolItem {
+	id: string;
+	command?: string | string[];
+	aggregatedOutput?: string;
+	aggregated_output?: string;
+	exitCode?: number;
+	exit_code?: number;
+	status?: string;
+	changes?: Array<{ path: string; kind: string }>;
+	server?: string;
+	tool?: string;
+	arguments?: unknown;
+	result?: unknown;
+	error?: { message?: string } | string;
+	query?: string;
+}
+
+export interface CodexToolDescriptor {
+	toolName(item: CodexToolItem): string;
+	input(item: CodexToolItem): Record<string, unknown>;
+	meta(item: CodexToolItem): ToolMeta;
+	result(item: CodexToolItem): { output: string; isError: boolean };
+}
+
+export function pickCodexError(err: CodexToolItem["error"]): string {
+	if (!err) return "";
+	return typeof err === "string" ? err : (err.message ?? "");
+}
+
+/** Join `{text}` blocks of an MCP content array; JSON-stringify anything else. */
+function stringifyMcpResult(result: unknown): string {
+	const content =
+		result && typeof result === "object" && "content" in result
+			? (result as { content?: unknown }).content
+			: result;
+	if (content == null) return "";
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((b) =>
+				b && typeof b === "object" && "text" in b
+					? String((b as { text: unknown }).text)
+					: JSON.stringify(b),
+			)
+			.join("");
+	}
+	return JSON.stringify(content);
+}
+
+const failed = (item: CodexToolItem) => item.status === "failed";
+
+export const CODEX_TOOL_ITEMS: Record<string, CodexToolDescriptor> = {
+	commandExecution: {
+		toolName: () => "shell",
+		input: (item) => ({ command: item.command ?? "" }),
+		meta: () => ({ kind: CODEX_TOOL_KINDS.shell }),
+		result: (item) => ({
+			output: item.aggregatedOutput ?? item.aggregated_output ?? "",
+			isError: failed(item) || (item.exitCode ?? item.exit_code ?? 0) !== 0,
+		}),
+	},
+	fileChange: {
+		toolName: () => "apply_patch",
+		input: (item) => ({ changes: item.changes ?? [] }),
+		meta: (item) => ({
+			kind: CODEX_TOOL_KINDS.apply_patch,
+			locations: codexFileChangeLocations(item.changes),
+		}),
+		result: (item) => ({
+			output: (item.changes ?? []).map((c) => `${c.kind} ${c.path}`).join("\n"),
+			isError: failed(item),
+		}),
+	},
+	mcpToolCall: {
+		toolName: (item) => `${item.server ?? "mcp"}.${item.tool ?? "tool"}`,
+		input: (item) => ({ arguments: item.arguments }),
+		meta: () => ({ kind: CODEX_TOOL_KINDS.mcp }),
+		result: (item) => {
+			const err = pickCodexError(item.error);
+			return {
+				output: err || stringifyMcpResult(item.result),
+				isError: failed(item) || Boolean(err),
+			};
+		},
+	},
+	webSearch: {
+		toolName: () => "web_search",
+		input: (item) => ({ query: item.query ?? "" }),
+		meta: () => ({ kind: CODEX_TOOL_KINDS.web_search }),
+		result: (item) => ({ output: item.query ?? "", isError: failed(item) }),
+	},
+};
+
+/** Map either protocol's item-type spelling onto a descriptor. */
+export function codexToolDescriptor(itemType: string): CodexToolDescriptor | undefined {
+	switch (itemType) {
+		case "command_execution":
+		case "commandExecution":
+			return CODEX_TOOL_ITEMS.commandExecution;
+		case "file_change":
+		case "fileChange":
+			return CODEX_TOOL_ITEMS.fileChange;
+		case "mcp_tool_call":
+		case "mcpToolCall":
+			return CODEX_TOOL_ITEMS.mcpToolCall;
+		case "web_search":
+		case "webSearch":
+			return CODEX_TOOL_ITEMS.webSearch;
+		default:
+			return undefined;
+	}
+}