@shivaedev/agent-codex 0.0.0 → 0.2.0

package/src/adapters/delivery.ts

@@ -0,0 +1,137 @@
+import { Deferred, Effect, Schema, Semaphore } from "effect";
+import { type BackendFailure, BackendUnavailable, Rejected, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, Input } from "@shivaedev/agent/run.ts";
+import { deliveryState } from "#adapters/deliveryState.ts";
+import { TurnNotification } from "#adapters/protocol.ts";
+import type { RpcNotification } from "#adapters/rpc.ts";
+import { AppServer } from "#adapters/server.ts";
+import { turnRequests } from "#adapters/turnRequests.ts";
+export const delivery = Effect.fn("Codex.delivery")(function* (
+	threadId: string,
+	settings: { model?: string; effort?: string },
+	remember: (operationId: string) => void,
+) {
+	const server = yield* AppServer;
+	const { state, gate, close, queue } = yield* deliveryState;
+	const requests = yield* turnRequests(threadId, settings);
+	function closedError() {
+		return new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+	}
+	const start = Effect.fn("Codex.start")(function* (input: ImageInput, operationId: string) {
+		if (state.closed) {
+			return yield* closedError();
+		}
+		if (state.uncertain !== undefined) {
+			return yield* new UnknownAcceptance({
+				backend: "codex",
+				message: "Reconcile the previous submission before sending another turn",
+				operationId: state.uncertain,
+			});
+		}
+		remember(operationId);
+		state.active = yield* requests.start(input, operationId).pipe(
+			Effect.tapError((error) =>
+				Effect.sync(() => {
+					if (error._tag !== "Rejected") {
+						state.uncertain = operationId;
+					}
+				}),
+			),
+		);
+
+		if (!state.finished.has(state.active)) {
+			state.finished.set(state.active, yield* Deferred.make<void, BackendFailure>());
+		}
+		return state.active;
+	});
+	const flush = Effect.gen(function* () {
+		if (state.active !== undefined || state.uncertain !== undefined || state.closed) {
+			return;
+		}
+		const next = state.pending.shift();
+		if (next === undefined) {
+			return;
+		}
+		yield* start(next.input, next.input.id ?? crypto.randomUUID()).pipe(
+			Effect.matchEffect({
+				onFailure: (error) => Deferred.fail(next.accepted, error),
+				onSuccess: () => Deferred.succeed(next.accepted, undefined),
+			}),
+		);
+	});
+	const settle = Effect.fn("Codex.settle")(function* (turnId: string) {
+		if (state.active !== turnId) {
+			return;
+		}
+		state.active = undefined;
+		const signal = state.finished.get(turnId);
+		if (signal !== undefined) {
+			yield* Deferred.succeed(signal, undefined);
+		}
+		yield* flush;
+	});
+	const track = Effect.fn("Codex.track")(function* (notification: RpcNotification) {
+		const value = Schema.decodeUnknownOption(TurnNotification)(notification.params);
+		if (value._tag === "None" || value.value.threadId !== threadId) {
+			return;
+		}
+		const id = value.value.turn.id;
+		if (notification.method === "turn/completed") {
+			yield* settle(id);
+			return;
+		}
+		if (notification.method !== "turn/started") {
+			return;
+		}
+		state.active = id;
+		if (!state.finished.has(id)) {
+			state.finished.set(id, yield* Deferred.make<void, BackendFailure>());
+		}
+	});
+
+	yield* Effect.addFinalizer(() => close);
+	yield* Effect.forkScoped(server.exited.pipe(Effect.andThen(close)));
+
+	return {
+		interrupt: (turnId: string) =>
+			Effect.gen(function* () {
+				if (state.active !== turnId) {
+					return;
+				}
+				const outcome = yield* requests.interrupt(turnId);
+				if (outcome === "inactive") {
+					yield* Semaphore.withPermit(gate)(settle(turnId));
+				}
+				const signal = state.finished.get(turnId);
+				if (signal !== undefined) {
+					yield* Deferred.await(signal);
+				}
+			}),
+		queue: (input: Input) => queue(input, flush),
+		recovered: (turnId: string, running: boolean) =>
+			Semaphore.withPermit(gate)(
+				Effect.gen(function* () {
+					state.active = running ? turnId : undefined;
+					state.uncertain = undefined;
+					if (running && !state.finished.has(turnId)) {
+						state.finished.set(turnId, yield* Deferred.make<void, BackendFailure>());
+					}
+					yield* flush;
+				}),
+			),
+		start: (input: ImageInput, operationId: string) => Semaphore.withPermit(gate)(start(input, operationId)),
+		steer: (expected: string, input: Input) =>
+			Semaphore.withPermit(gate)(
+				Effect.gen(function* () {
+					if (state.active !== expected) {
+						return yield* new Rejected({ backend: "codex", message: "The expected turn is no longer active" });
+					}
+					const operationId = input.id ?? crypto.randomUUID();
+					remember(operationId);
+					yield* requests.steer(expected, input, operationId);
+				}),
+			),
+		track: (notification: RpcNotification) => Semaphore.withPermit(gate)(track(notification)),
+	};
+});
+export type Delivery = Effect.Success<ReturnType<typeof delivery>>;

package/src/adapters/deliveryState.ts

@@ -0,0 +1,43 @@
+import { Deferred, Effect, Semaphore } from "effect";
+import { type BackendFailure, BackendUnavailable } from "@shivaedev/agent/failures.ts";
+import type { Input } from "@shivaedev/agent/run.ts";
+
+interface Pending {
+	readonly accepted: Deferred.Deferred<void, BackendFailure>;
+	readonly input: Input;
+}
+interface State {
+	active: string | undefined;
+	closed: boolean;
+	finished: Map<string, Deferred.Deferred<void, BackendFailure>>;
+	pending: Pending[];
+	uncertain: string | undefined;
+}
+export const deliveryState = Effect.gen(function* () {
+	const gate = yield* Semaphore.make(1);
+	const state: State = { active: undefined, closed: false, finished: new Map(), pending: [], uncertain: undefined };
+	const close = Effect.gen(function* () {
+		state.closed = true;
+		const error = new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+		for (const next of state.pending.splice(0)) {
+			yield* Deferred.fail(next.accepted, error);
+		}
+		for (const signal of state.finished.values()) {
+			yield* Deferred.fail(signal, error);
+		}
+	});
+	const queue = Effect.fn("Codex.queue")(function* (input: Input, flush: Effect.Effect<void>) {
+		const accepted = yield* Deferred.make<void, BackendFailure>();
+		yield* Semaphore.withPermit(gate)(
+			Effect.gen(function* () {
+				if (state.closed) {
+					return yield* new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+				}
+				state.pending.push({ accepted, input });
+				yield* flush;
+			}),
+		);
+		yield* Deferred.await(accepted);
+	});
+	return { close, gate, queue, state };
+});

package/src/adapters/engine.ts

@@ -0,0 +1,101 @@
+import { Effect, PubSub, Semaphore, Stream } from "effect";
+import type { ConfiguredBackend } from "@shivaedev/agent/backend.ts";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { Rejected, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, StartRequest } from "@shivaedev/agent/run.ts";
+import { features } from "#adapters/features.ts";
+import type { LineProcess } from "#adapters/process.ts";
+import { observe, readRequest } from "#adapters/reads.ts";
+import { receiptOf, recovery } from "#adapters/recovery.ts";
+import { AppServer, openServer } from "#adapters/server.ts";
+import { openSession, type Session } from "#adapters/session.ts";
+import { sweepSpawnedDescendants } from "#adapters/threadSweep.ts";
+import type { CodexConfiguration } from "#config.ts";
+export const engine = Effect.fn("Codex.engine")(function* (config: CodexConfiguration, spawn?: () => LineProcess) {
+	const server = yield* openServer(config, spawn);
+	const sessions = new Map<string, Session>();
+	const { operations, refusals, reconcile } = yield* recovery(sessions).pipe(Effect.provideService(AppServer, server));
+	const submissionGate = yield* Semaphore.make(1);
+	const submit = Effect.fn("Codex.submit")(function* (
+		request: Omit<StartRequest, "input"> & { readonly input: ImageInput },
+		reference?: { value: string; version: number },
+	) {
+		if (operations.has(request.operationId)) {
+			const result = yield* reconcile(request.operationId);
+			if (result.type === "accepted") {
+				return result.receipt;
+			}
+			if (result.type === "not-accepted") {
+				return yield* new Rejected({ backend: "codex", message: result.evidence });
+			}
+			return yield* new UnknownAcceptance({
+				backend: "codex",
+				message: result.reason,
+				operationId: request.operationId,
+			});
+		}
+		if (reference !== undefined && (reference.version !== 1 || server.claims.isNode(reference.value))) {
+			return yield* new Rejected({ backend: "codex", message: "Child threads are observed passively and cannot be resumed" });
+		}
+		operations.set(request.operationId, reference?.value);
+		const session = yield* openSession(config, request, reference?.value, (operationId, threadId) => {
+			operations.set(operationId, threadId);
+		}).pipe(Effect.provideService(AppServer, server));
+		operations.set(request.operationId, session.threadId);
+		sessions.set(session.threadId, session);
+		yield* Effect.addFinalizer(() =>
+			Effect.sync(() => {
+				if (sessions.get(session.threadId) === session) {
+					sessions.delete(session.threadId);
+				}
+			}),
+		);
+		const turnId = yield* session.driver.start(request.input, request.operationId);
+		return receiptOf(request.operationId, session.threadId, turnId);
+	});
+	function start(request: Omit<StartRequest, "input"> & { readonly input: ImageInput }, session?: { value: string; version: number }) {
+		return Semaphore.withPermit(submissionGate)(submit(request, session)).pipe(
+			Effect.tapError((error) =>
+				Effect.sync(() => {
+					if (error._tag === "Rejected") {
+						refusals.set(request.operationId, error.message);
+					}
+				}),
+			),
+		);
+	}
+	const backend: ConfiguredBackend = {
+		backend: "codex",
+		events: (receipt) =>
+			Stream.unwrap(
+				Effect.gen(function* () {
+					const session = sessions.get(receipt.session?.value ?? "");
+					if (session === undefined) {
+						return Stream.empty;
+					}
+					const subscription = yield* PubSub.subscribe(session.events);
+					return Stream.fromIterable<RunEvent>([
+						{ receipt, type: "acknowledged" },
+						{ reference: session.threadId, type: "session.opened" },
+					]).pipe(Stream.concat(Stream.fromSubscription(subscription)), Stream.interruptWhen(server.exited));
+				}),
+			),
+		features: yield* features(sessions, start).pipe(Effect.provideService(AppServer, server)),
+		inspect: (receipt) => observe(receipt).pipe(Effect.provideService(AppServer, server)),
+		reconcile,
+		start,
+	};
+	return {
+		backend: () => Effect.succeed(backend),
+		census: (rootThreadId: string) =>
+			sweepSpawnedDescendants((method, params) => readRequest(method, params).pipe(Effect.provideService(AppServer, server)), rootThreadId).pipe(
+				Effect.tap((children) =>
+					Effect.sync(() => {
+						for (const child of children) {
+							server.claims.claim(rootThreadId, child.threadId);
+						}
+					}),
+				),
+			),
+	};
+});

package/src/adapters/features.ts

@@ -0,0 +1,62 @@
+import type { Scope } from "effect";
+import { Effect } from "effect";
+import type { ConfiguredFeatures, FeatureImplementations } from "@shivaedev/agent/backend.ts";
+import type { BackendFailure } from "@shivaedev/agent/failures.ts";
+import { Rejected } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, Receipt, StartRequest } from "@shivaedev/agent/run.ts";
+import { ModelListResponse } from "#adapters/protocol.ts";
+import { decode, readRequest, transcript } from "#adapters/reads.ts";
+import { AppServer } from "#adapters/server.ts";
+import type { Session } from "#adapters/session.ts";
+export const features = Effect.fn("Codex.features")(function* (
+	sessions: Map<string, Session>,
+	start: (
+		request: Omit<StartRequest, "input"> & { readonly input: ImageInput },
+		session?: { value: string; version: number },
+	) => Effect.Effect<Receipt, BackendFailure, Scope.Scope>,
+) {
+	const server = yield* AppServer;
+	function driverFor(receipt: Receipt) {
+		return Effect.suspend(() => {
+			const session = sessions.get(receipt.session?.value ?? "");
+			return session === undefined
+				? Effect.fail(new Rejected({ backend: "codex", message: "No live session for this receipt" }))
+				: Effect.succeed(session.driver);
+		});
+	}
+	const models: FeatureImplementations["models"] = {
+		list: readRequest("model/list", {}).pipe(
+			Effect.flatMap((value) => decode(ModelListResponse, value)),
+			Effect.map(({ data }) =>
+				data.map((model) => ({
+					defaultEffort: model.defaultReasoningEffort,
+					efforts: model.supportedReasoningEfforts.map((effort) => effort.reasoningEffort),
+					id: model.model,
+					isDefault: model.isDefault,
+					name: model.displayName,
+				})),
+			),
+			Effect.provideService(AppServer, server),
+		),
+	};
+	return {
+		imageInput: { implementation: { start }, support: "supported" },
+		interruption: {
+			implementation: { interrupt: (receipt) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.interrupt(receipt.reference.value))) },
+			support: "supported",
+		},
+		models: { implementation: models, support: "supported" },
+		queuedInput: {
+			implementation: { queue: (receipt, input) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.queue(input))) },
+			support: "supported",
+		},
+		sessions: { implementation: { resume: (session, request) => start(request, session) }, support: "supported" },
+		steering: {
+			implementation: {
+				steer: (receipt, input) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.steer(receipt.reference.value, input))),
+			},
+			support: "supported",
+		},
+		transcript: { implementation: { read: (receipt) => transcript(receipt).pipe(Effect.provideService(AppServer, server)) }, support: "supported" },
+	} satisfies ConfiguredFeatures;
+});

package/src/adapters/handshake.ts

@@ -0,0 +1,35 @@
+import { Effect, Option, Schema } from "effect";
+import { InitializeResponse } from "#adapters/protocol.ts";
+import type { Request } from "#adapters/Request.ts";
+
+const CLIENT_INFO = { name: "platform_agent_codex", title: "Platform Codex", version: "0.0.0" };
+
+export const MUTED_NOTIFICATIONS = [
+	"item/agentMessage/delta",
+	"item/commandExecution/outputDelta",
+	"item/fileChange/outputDelta",
+	"item/fileChange/patchUpdated",
+	"item/plan/delta",
+	"item/reasoning/summaryPartAdded",
+	"item/reasoning/summaryTextDelta",
+	"item/reasoning/textDelta",
+	"turn/diff/updated",
+];
+
+const decodeInitialize = Schema.decodeUnknownOption(InitializeResponse);
+
+function versionOf(response: unknown): Option.Option<string> {
+	return Option.map(decodeInitialize(response), ({ userAgent }) => userAgent.split(" ")[0]?.split("/")[1] ?? "");
+}
+
+// Codex requires one initialize followed by initialized, with experimentalApi enabled for dynamic tools.
+export function handshake(request: Request) {
+	return request("initialize", {
+		capabilities: {
+			experimentalApi: true,
+			optOutNotificationMethods: MUTED_NOTIFICATIONS,
+			requestAttestation: false,
+		},
+		clientInfo: CLIENT_INFO,
+	}).pipe(Effect.map(versionOf));
+}

package/src/adapters/items.ts

@@ -0,0 +1,133 @@
+import type { Raw as RawSchema } from "@shivaedev/agent/eventData.ts";
+import type { RunEvent as AgentEvent } from "@shivaedev/agent/events.ts";
+
+type RawPayload = typeof RawSchema.Type;
+
+import { Option, Schema } from "effect";
+import { KnownItem } from "#adapters/protocolItems.ts";
+import { userMessageEvent } from "#adapters/userMessageEvent.ts";
+
+type Item<T extends KnownItem["type"]> = Extract<KnownItem, { type: T }>;
+
+const decodeItem = Schema.decodeUnknownOption(KnownItem);
+
+type Started = Extract<AgentEvent, { type: "tool.started" }>;
+
+function toolIdentity(item: KnownItem): Pick<Started, "name" | "providerName"> {
+	if (item.type === "mcpToolCall") {
+		return { name: `${item.server}: ${item.tool}`, providerName: `${item.server}/${item.tool}` };
+	}
+	return item.type === "dynamicToolCall" ? { name: item.tool } : { name: item.type };
+}
+
+function toolInput(item: KnownItem): string {
+	switch (item.type) {
+		case "commandExecution":
+			return item.command;
+		case "dynamicToolCall":
+			return JSON.stringify(item.arguments);
+		case "fileChange":
+			return item.changes.map((change) => change.path).join("\n");
+		case "mcpToolCall":
+			return JSON.stringify(item.arguments);
+		case "webSearch":
+			return item.query;
+		default:
+			return "";
+	}
+}
+
+function isTool(
+	item: KnownItem,
+): item is Item<"commandExecution"> | Item<"dynamicToolCall"> | Item<"fileChange"> | Item<"mcpToolCall"> | Item<"webSearch"> {
+	return (
+		item.type === "commandExecution"
+		|| item.type === "dynamicToolCall"
+		|| item.type === "fileChange"
+		|| item.type === "mcpToolCall"
+		|| item.type === "webSearch"
+	);
+}
+
+function commandOk(item: Item<"commandExecution">): boolean {
+	return item.status === "completed" && (item.exitCode ?? 0) === 0;
+}
+
+function dynamicOutcome(item: Item<"dynamicToolCall">) {
+	return {
+		ok: item.success ?? item.status === "completed",
+		output: (item.contentItems ?? []).map((part) => part.text ?? "").join("\n"),
+	};
+}
+
+function toolOutcome(item: Item<"commandExecution" | "dynamicToolCall" | "fileChange" | "mcpToolCall" | "webSearch">): {
+	ok: boolean;
+	output: string;
+} {
+	switch (item.type) {
+		case "commandExecution":
+			return { ok: commandOk(item), output: item.aggregatedOutput ?? "" };
+		case "dynamicToolCall":
+			return dynamicOutcome(item);
+		case "fileChange":
+			return {
+				ok: item.status === "completed",
+				output: item.changes.map((change) => change.diff).join("\n"),
+			};
+		case "mcpToolCall":
+			return {
+				ok: item.status === "completed",
+				output: JSON.stringify(item.error ?? item.result ?? null),
+			};
+		case "webSearch":
+			return { ok: true, output: "" };
+	}
+}
+
+function reasoningText(item: Item<"reasoning">): string {
+	return [...(item.summary ?? []), ...(item.content ?? [])].join("\n");
+}
+
+function knownStarted(raw: RawPayload, item: KnownItem): AgentEvent[] {
+	if (isTool(item)) {
+		return [
+			{
+				input: toolInput(item),
+				...toolIdentity(item),
+				raw,
+				toolId: item.id,
+				type: "tool.started",
+			},
+		];
+	}
+	return item.type === "agentMessage" || item.type === "reasoning" || item.type === "userMessage" ? [] : [{ raw, type: "raw" }];
+}
+
+function knownCompleted(raw: RawPayload, item: KnownItem): AgentEvent[] {
+	if (isTool(item)) {
+		return [{ ...toolOutcome(item), raw, toolId: item.id, type: "tool.completed" }];
+	}
+	switch (item.type) {
+		case "agentMessage":
+			return [{ parts: [{ text: item.text, type: "text" }], raw, role: "agent", type: "message" }];
+		case "userMessage":
+			return [userMessageEvent(item, raw)];
+		case "reasoning": {
+			const text = reasoningText(item);
+			return text.length === 0 ? [] : [{ raw, text, type: "thinking" }];
+		}
+		default:
+			return [{ raw, type: "raw" }];
+	}
+}
+
+function projectItem(project: (raw: RawPayload, item: KnownItem) => AgentEvent[]) {
+	return (raw: RawPayload, item: unknown): AgentEvent[] =>
+		Option.match(decodeItem(item), {
+			onNone: () => [{ raw, type: "raw" }],
+			onSome: (known) => project(raw, known),
+		});
+}
+
+export const itemStarted = projectItem(knownStarted);
+export const itemCompleted = projectItem(knownCompleted);

package/src/adapters/mapping.ts

@@ -0,0 +1,66 @@
+import { Option, Schema } from "effect";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { itemCompleted, itemStarted } from "#adapters/items.ts";
+import {
+	ItemNotification,
+	ModelReroutedNotification,
+	ThreadStatusNotification,
+	TokenUsageNotification,
+	TurnNotification,
+} from "#adapters/protocol.ts";
+import { RATE_LIMITS_METHOD, rateLimitEvents } from "#adapters/rateLimits.ts";
+import type { RpcNotification } from "#adapters/rpc.ts";
+export function rawOf(kind: string, payload: unknown) {
+	return { kind, payload: JSON.stringify(payload), source: "codex" };
+}
+function mapped<A, E>(schema: Schema.Codec<A, E>, notification: RpcNotification, project: (value: A) => RunEvent[]): RunEvent[] {
+	return Option.match(Schema.decodeUnknownOption(schema)(notification.params), {
+		onNone: () => [{ raw: rawOf(notification.method, notification.params), type: "raw" }],
+		onSome: project,
+	});
+}
+export function toAgentEvents(notification: RpcNotification, model: string): RunEvent[] {
+	const { method, params } = notification;
+	const raw = rawOf(method, params);
+	switch (method) {
+		case RATE_LIMITS_METHOD:
+			return rateLimitEvents(raw, params);
+		case "item/started":
+			return mapped(ItemNotification, notification, ({ item }) => itemStarted(raw, item));
+		case "item/completed":
+			return mapped(ItemNotification, notification, ({ item }) => itemCompleted(raw, item));
+		case "turn/started":
+			return mapped(TurnNotification, notification, () => [{ raw, state: "running", type: "execution" }]);
+		case "turn/completed":
+			return mapped(TurnNotification, notification, ({ turn }) => [
+				{ raw, state: turn.status === "inProgress" ? "running" : turn.status, type: "execution" },
+			]);
+		case "thread/status/changed":
+			return mapped(ThreadStatusNotification, notification, ({ status }) =>
+				status.type === "active"
+					? [{ raw, state: status.activeFlags.length > 0 ? "awaiting-input" : "running", type: "execution" }]
+					: [{ raw, type: "raw" }],
+			);
+		case "thread/tokenUsage/updated":
+			return mapped(TokenUsageNotification, notification, ({ tokenUsage }) => {
+				const tokens = tokenUsage.total;
+				return [
+					{
+						cacheReadTokens: tokens.cachedInputTokens,
+						inputTokens: tokens.inputTokens,
+						outputTokens: tokens.outputTokens,
+						scope: "cumulative",
+						type: "usage",
+						unit: "session",
+						...(model.length === 0 ? {} : { model }),
+						...(tokens.cacheWriteInputTokens === undefined ? {} : { cacheWriteTokens: tokens.cacheWriteInputTokens }),
+						raw,
+					},
+				];
+			});
+		case "model/rerouted":
+			return mapped(ModelReroutedNotification, notification, ({ toModel, reason }) => [{ model: toModel, raw, reason, type: "model.changed" }]);
+		default:
+			return [{ raw, type: "raw" }];
+	}
+}

package/src/adapters/process.ts

@@ -0,0 +1,69 @@
+import { spawn } from "node:child_process";
+
+export interface LineProcess {
+	readonly kill: () => void;
+	readonly onExit: (listener: (code: number | null) => void) => void;
+	readonly onLine: (listener: (line: string) => void) => void;
+	readonly onStderr: (listener: (text: string) => void) => void;
+	readonly write: (line: string) => void;
+}
+
+interface SpawnLineProcessOptions {
+	readonly args: readonly string[];
+	readonly command: string;
+	readonly cwd: string;
+}
+
+// Codex app-server uses newline-delimited JSON over stdio.
+export function spawnLineProcess(options: SpawnLineProcessOptions): LineProcess {
+	const child = spawn(options.command, [...options.args], {
+		cwd: options.cwd,
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+	let lineListener: ((line: string) => void) | null = null;
+	let stderrListener: ((text: string) => void) | null = null;
+	const exitListeners: ((code: number | null) => void)[] = [];
+	function emitExit(code: number | null): void {
+		for (const listener of exitListeners) {
+			listener(code);
+		}
+	}
+	let buffer = "";
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", (chunk: string) => {
+		buffer += chunk;
+		let newline = buffer.indexOf("\n");
+		while (newline >= 0) {
+			const line = buffer.slice(0, newline).trim();
+			buffer = buffer.slice(newline + 1);
+			if (line.length > 0) {
+				lineListener?.(line);
+			}
+			newline = buffer.indexOf("\n");
+		}
+	});
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk: string) => stderrListener?.(chunk));
+	child.on("exit", (code) => emitExit(code));
+	child.on("error", () => emitExit(null));
+	child.stdin.on("error", () => emitExit(null));
+	return {
+		// Closing stdin lets app-server exit cleanly; SIGTERM handles a child that remains alive.
+		kill: () => {
+			child.stdin.end();
+			child.kill("SIGTERM");
+		},
+		onExit: (listener) => {
+			exitListeners.push(listener);
+		},
+		onLine: (listener) => {
+			lineListener = listener;
+		},
+		onStderr: (listener) => {
+			stderrListener = listener;
+		},
+		write: (line) => {
+			child.stdin.write(`${line}\n`);
+		},
+	};
+}