@alint-js/model-adapter-acp 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# `@alint-js/model-adapter-acp`
+
+An OpenAI-compatible HTTP gateway for ACP coding agents.
+
+## What it does
+
+The package keeps ACP session semantics outside alint. It exposes configured ACP agents as
+OpenAI-compatible models and implements:
+
+- `GET /v1/models`
+- non-streaming and SSE text chat completions
+- request-scoped OpenAI function tools exposed to ACP through MCP Streamable HTTP
+- deferred `tool_calls` continuation through a later `role: tool` message
+- `tool_choice`, usage, abort, continuation TTL, and permission-denial handling
+
+The integration suite also runs a real `runAlint` file rule through `ctx.model()`, xsAI
+`generateStructured`, this HTTP gateway, an ACP session, and the MCP `reportFindings` tool before
+asserting the diagnostic returned by alint.
+
+The MCP bridge uses a random route and bearer token for each completion turn. When the public
+gateway address is not loopback, configure `mcpBaseUrl`; request Host headers are not trusted to
+choose the authenticated MCP destination.
+
+ACP has no equivalent for OpenAI `temperature`, and final ACP usage is unavailable while a
+deferred tool call is pending. Use `onCompatibilityDiagnostic` to observe those cases. Pending
+tool-call responses report zero usage because xsAI requires the OpenAI `usage` object.
+
+## How to use with a command
+
+`createCommandModel` uses `tinyexec` to start one ACP process per completion. `startGateway` owns the loopback HTTP server and closes active ACP processes when it shuts down.
+
+```ts
+import { createCommandModel, startGateway } from '@alint-js/model-adapter-acp'
+
+const gateway = await startGateway({
+  cwd: process.cwd(),
+  models: [createCommandModel({
+    command: 'codex-acp',
+    cwd: process.cwd(),
+    id: 'codex',
+    name: 'Codex ACP',
+  })],
+})
+
+console.info(gateway.endpoint)
+await gateway.shutdown()
+```
+
+The alint CLI wraps this interface. Users normally set `driver = "acp"` on a provider model in global setup or `.alint/config.toml` instead of starting the gateway themselves.
+
+## How to embed an ACP connection
+
+```ts
+import { createGateway } from '@alint-js/model-adapter-acp'
+import { serve } from 'h3/node'
+
+const app = createGateway({
+  cwd: process.cwd(),
+  mcpBaseUrl: 'http://127.0.0.1:7419',
+  models: [{
+    id: 'reviewer',
+    name: 'Review Agent',
+    openConnection: async () => ({
+      kind: 'stream',
+      stream: await openYourAcpStream(),
+    }),
+  }],
+})
+
+const server = await serve(app, { hostname: '127.0.0.1', port: 7419 }).ready()
+
+// On shutdown, stop accepting HTTP first, then cancel retained ACP continuations.
+await server.close()
+await app.shutdown()
+```
+
+`openConnection` accepts either an official ACP `AgentApp` or `Stream`. An embedding application can own a different transport or lifecycle policy without using the command adapter.
+
+Other OpenAI-compatible consumers can use the resulting ordinary provider endpoint:
+
+```toml
+[[providers]]
+id = "acp"
+type = "openai-compatible"
+endpoint = "http://127.0.0.1:7419/v1"
+```
+
+## When to use
+
+- You need existing OpenAI-compatible consumers to call an ACP coding agent.
+- The ACP agent supports MCP over HTTP when request tools are used.
+- The OpenAI client executes function calls and returns `role: tool` messages.
+
+## When not to use
+
+- Use an alint agent adapter when a rule intentionally depends on agent-specific behavior.
+- Do not use this package as an OpenAI Responses, realtime, audio, or image compatibility layer.
+- Streaming tool calls and parallel tool calls are not implemented yet; text streaming is supported.

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { AgentApp, Stream } from "@agentclientprotocol/sdk";
+import { H3 } from "h3";
+//#region src/gateway.d.ts
+interface CompatibilityDiagnostic {
+  field: string;
+  message: string;
+  value: unknown;
+}
+type GatewayApp = H3 & {
+  shutdown: () => Promise<void>;
+};
+interface GatewayModel {
+  id: string;
+  name: string;
+  openConnection: () => GatewayModelConnection | Promise<GatewayModelConnection>;
+}
+type GatewayModelConnection = {
+  agent: AgentApp;
+  kind: 'agent-app';
+} | {
+  dispose?: () => Promise<void> | void;
+  kind: 'stream';
+  stream: Stream;
+};
+interface GatewayOptions {
+  continuationTtlMs?: number;
+  cwd?: string;
+  mcpBaseUrl?: string;
+  models: GatewayModel[];
+  onCompatibilityDiagnostic?: (diagnostic: CompatibilityDiagnostic) => void;
+}
+interface GatewayServer {
+  endpoint: string;
+  shutdown: () => Promise<void>;
+}
+/** Creates the OpenAI-compatible HTTP interface backed by configured ACP agents. */
+declare function createGateway(options: GatewayOptions): GatewayApp;
+/** Starts an ephemeral loopback gateway for one CLI run. */
+declare function startGateway(options: GatewayOptions): Promise<GatewayServer>;
+//#endregion
+//#region src/command.d.ts
+interface CommandModelOptions {
+  args?: string[];
+  command: string;
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  id: string;
+  name: string;
+  onStderr?: (text: string) => void;
+}
+/** Creates a gateway model whose ACP connection is one CLI process per OpenAI request. */
+declare function createCommandModel(options: CommandModelOptions): GatewayModel;
+//#endregion
+export { type CommandModelOptions, type CompatibilityDiagnostic, type GatewayApp, type GatewayModel, type GatewayModelConnection, type GatewayOptions, type GatewayServer, createCommandModel, createGateway, startGateway };

package/dist/index.mjs

@@ -0,0 +1,786 @@
+import { Readable, Writable } from "node:stream";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { PROTOCOL_VERSION, client, methods, ndJsonStream } from "@agentclientprotocol/sdk";
+import { x } from "tinyexec";
+import process from "node:process";
+import { H3, defineEventHandler, getRouterParam } from "h3";
+import { serve } from "h3/node";
+import { array, boolean, literal, looseObject, number, object, optional, record, safeParse, string, union, unknown } from "valibot";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { fromJSONSchema } from "zod";
+//#region src/command.ts
+/** Creates a gateway model whose ACP connection is one CLI process per OpenAI request. */
+function createCommandModel(options) {
+	return {
+		id: options.id,
+		name: options.name,
+		openConnection: () => openCommandConnection(options)
+	};
+}
+/**
+* Releases the stdio observers and process owned by one command connection.
+*
+* Triggering workflow:
+*
+* {@link createGateway}
+*   -> `GatewayModelConnection.dispose`
+*     -> {@link disposeCommandConnection}
+*
+* Upstream:
+* - {@link openCommandConnection}
+*
+* Downstream:
+* - {@link stopProcess}
+*/
+async function disposeCommandConnection(child, handleStderr, terminate) {
+	child.stderr?.off("data", handleStderr);
+	child.stdin?.end();
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	const closed = waitForClose(child);
+	terminate();
+	if (await Promise.race([closed.then(() => true), setTimeout$1(1e3, false)])) return;
+	child.kill("SIGKILL");
+	await closed;
+}
+async function openCommandConnection(options) {
+	const execution = x(options.command, options.args ?? [], {
+		nodeOptions: {
+			cwd: options.cwd,
+			env: options.env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		},
+		nodePath: false
+	});
+	const child = execution.process;
+	if (!child?.stdin || !child.stdout || !child.stderr) {
+		execution.kill();
+		throw new Error(`ACP command "${options.command}" did not expose stdin, stdout, and stderr pipes.`);
+	}
+	const handleStderr = (chunk) => {
+		options.onStderr?.(chunk.toString());
+	};
+	child.stderr.on("data", handleStderr);
+	return {
+		dispose: () => disposeCommandConnection(child, handleStderr, execution.kill.bind(execution)),
+		kind: "stream",
+		stream: ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout))
+	};
+}
+function waitForClose(child) {
+	return new Promise((resolve) => {
+		if (child.exitCode !== null || child.signalCode !== null) {
+			resolve();
+			return;
+		}
+		child.once("close", () => resolve());
+	});
+}
+//#endregion
+//#region src/tool-bridge.ts
+var ToolBridge = class {
+	id = crypto.randomUUID();
+	token = crypto.randomUUID();
+	#closed = false;
+	#deferred = /* @__PURE__ */ new Map();
+	#onCall;
+	#server;
+	#tools;
+	#transport;
+	constructor(tools, onCall) {
+		this.#tools = tools;
+		this.#onCall = onCall;
+		this.#server = new McpServer({
+			name: "alint-openai-tools",
+			version: "0.3.2"
+		}, { capabilities: { tools: {} } });
+		this.#transport = new WebStandardStreamableHTTPServerTransport({
+			enableJsonResponse: true,
+			sessionIdGenerator: () => crypto.randomUUID()
+		});
+		for (const tool of this.#tools) this.#server.registerTool(tool.function.name, {
+			description: tool.function.description,
+			inputSchema: fromJSONSchema(inputSchema(tool))
+		}, (arguments_) => this.#call(tool.function.name, arguments_));
+	}
+	async close(reason = /* @__PURE__ */ new Error("The ACP turn ended before the tool returned.")) {
+		if (this.#closed) return;
+		this.#closed = true;
+		for (const deferred of this.#deferred.values()) deferred.reject(reason);
+		this.#deferred.clear();
+		await this.#server.close();
+	}
+	config(origin) {
+		return {
+			headers: [{
+				name: "authorization",
+				value: `Bearer ${this.token}`
+			}],
+			name: "openai-request-tools",
+			type: "http",
+			url: new URL(`/_alint/mcp/${this.id}`, origin).href
+		};
+	}
+	/**
+	* Routes the gateway's authenticated MCP endpoint into the request-scoped
+	* transport. Tool calls then enter `#call` through `McpServer.registerTool`.
+	*/
+	handleRequest(request) {
+		return this.#transport.handleRequest(request);
+	}
+	resolve(callId, content) {
+		const deferred = this.#deferred.get(callId);
+		if (!deferred) return false;
+		this.#deferred.delete(callId);
+		deferred.resolve(content);
+		return true;
+	}
+	start() {
+		return this.#server.connect(this.#transport);
+	}
+	/**
+	* Handles an MCP `tools/call` request from the ACP agent. It records one pending
+	* result, emits the equivalent OpenAI tool call through `#onCall`, and completes
+	* when `resolve` receives the next request's tool result. Unknown tools and
+	* parallel calls fail before any OpenAI-visible state is emitted.
+	*/
+	async #call(name, arguments_) {
+		if (!this.#tools.some((tool) => tool.function.name === name)) throw new McpError(ErrorCode.InvalidParams, `Unknown request tool: ${name}`);
+		if (this.#deferred.size > 0) throw new McpError(ErrorCode.InvalidRequest, "Parallel request tool calls are not supported.");
+		const id = `call_${crypto.randomUUID()}`;
+		const content = new Promise((resolve, reject) => {
+			this.#deferred.set(id, {
+				reject,
+				resolve
+			});
+		});
+		this.#onCall({
+			arguments: JSON.stringify(arguments_),
+			id,
+			name
+		});
+		return { content: [{
+			text: await content,
+			type: "text"
+		}] };
+	}
+};
+function inputSchema(tool) {
+	return {
+		...tool.function.parameters,
+		properties: tool.function.parameters?.properties ?? {},
+		type: "object"
+	};
+}
+//#endregion
+//#region src/gateway.ts
+const openAIFunctionToolSchema = object({
+	function: object({
+		description: optional(string()),
+		name: string(),
+		parameters: optional(record(string(), unknown())),
+		strict: optional(boolean())
+	}),
+	type: literal("function")
+});
+const chatCompletionRequestSchema = looseObject({
+	messages: array(unknown()),
+	model: string(),
+	parallel_tool_calls: optional(literal(false), false),
+	stream: optional(boolean(), false),
+	stream_options: optional(unknown()),
+	temperature: optional(number()),
+	tool_choice: optional(union([
+		literal("auto"),
+		literal("none"),
+		literal("required"),
+		object({
+			function: object({ name: string() }),
+			type: literal("function")
+		})
+	])),
+	tools: optional(array(openAIFunctionToolSchema), [])
+});
+var PromiseQueue = class {
+	#failed = false;
+	#failure;
+	#items = [];
+	#reject;
+	#removeAbortListener;
+	#resolve;
+	fail(reason) {
+		this.#failed = true;
+		this.#failure = reason;
+		if (this.#reject) {
+			const reject = this.#reject;
+			this.#clearWaiter();
+			reject(reason);
+		}
+	}
+	next(signal) {
+		const item = this.#items.shift();
+		if (item) return Promise.resolve(item);
+		if (this.#failed) return Promise.reject(this.#failure);
+		if (signal?.aborted) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			this.#resolve = resolve;
+			this.#reject = reject;
+			if (signal) {
+				const abort = () => {
+					this.#clearWaiter();
+					reject(signal.reason);
+				};
+				signal.addEventListener("abort", abort, { once: true });
+				this.#removeAbortListener = () => signal.removeEventListener("abort", abort);
+			}
+		});
+	}
+	push(item) {
+		if (this.#resolve) {
+			const resolve = this.#resolve;
+			this.#clearWaiter();
+			resolve(item);
+			return;
+		}
+		this.#items.push(item);
+	}
+	#clearWaiter() {
+		this.#removeAbortListener?.();
+		this.#removeAbortListener = void 0;
+		this.#reject = void 0;
+		this.#resolve = void 0;
+	}
+};
+var CompletionTurn = class {
+	get modelId() {
+		return this.#options.model.id;
+	}
+	#bridge;
+	#cancelled;
+	#cancelSession;
+	#connection;
+	#connectionDisposed = false;
+	#finished = false;
+	#options;
+	#outputs = new PromiseQueue();
+	#pendingCalls = /* @__PURE__ */ new Map();
+	#timer;
+	#toolCallCount = 0;
+	constructor(options) {
+		this.#options = options;
+		if (options.tools.length > 0) {
+			this.#bridge = new ToolBridge(options.tools, (call) => {
+				this.#toolCallCount += 1;
+				this.#pendingCalls.set(call.id, call);
+				options.onPending(call, this);
+				this.#outputs.push({
+					call,
+					type: "tool-call"
+				});
+			});
+			options.bridges.set(this.#bridge.id, this.#bridge);
+		}
+	}
+	armContinuation(callId) {
+		if (!this.#pendingCalls.has(callId) || this.#timer) return;
+		this.#timer = setTimeout(() => {
+			this.cancel(/* @__PURE__ */ new Error(`Tool call ${callId} expired.`));
+		}, this.#options.continuationTtlMs);
+		this.#timer.unref?.();
+	}
+	async cancel(reason) {
+		if (this.#cancelled) return;
+		this.#cancelled = reason;
+		this.#outputs.fail(reason);
+		this.#cancelSession?.().catch(() => {});
+		await this.#bridge?.close(reason);
+		await this.#disposeConnection();
+		this.#finish();
+	}
+	async nextOutput(signal) {
+		try {
+			return await this.#outputs.next(signal);
+		} catch (error) {
+			if (signal?.aborted) await this.cancel(/* @__PURE__ */ new Error("The OpenAI request was aborted."));
+			throw error;
+		}
+	}
+	resume(request, result) {
+		if (!this.#matchesContinuation(request, result.toolCallId)) return false;
+		const resumed = this.#bridge?.resolve(result.toolCallId, result.content) ?? false;
+		if (resumed && this.#timer) {
+			clearTimeout(this.#timer);
+			this.#timer = void 0;
+		}
+		if (resumed) this.#pendingCalls.delete(result.toolCallId);
+		return resumed;
+	}
+	start() {
+		this.#run().catch((error) => this.#outputs.fail(error));
+	}
+	#assertActive() {
+		if (this.#cancelled) throw this.#cancelled;
+	}
+	async #disposeConnection() {
+		if (this.#connectionDisposed || this.#connection?.kind !== "stream") return;
+		this.#connectionDisposed = true;
+		await this.#connection.dispose?.();
+	}
+	#finish() {
+		if (this.#finished) return;
+		this.#finished = true;
+		this.#options.onFinished(this, [...this.#pendingCalls.keys()]);
+	}
+	#matchesContinuation(request, toolCallId) {
+		const initialMessages = this.#options.request.messages;
+		const initialPrefix = request.messages.slice(0, initialMessages.length);
+		const assistantMessage = request.messages.at(-2);
+		const pendingCall = this.#pendingCalls.get(toolCallId);
+		if (!pendingCall || request.model !== this.#options.model.id || JSON.stringify(request.tools) !== JSON.stringify(this.#options.request.tools) || JSON.stringify(request.toolChoice) !== JSON.stringify(this.#options.request.toolChoice) || JSON.stringify(initialPrefix) !== JSON.stringify(initialMessages) || !isRecord(assistantMessage)) return false;
+		const toolCalls = assistantMessage.tool_calls;
+		return Array.isArray(toolCalls) && toolCalls.some((call) => isRecord(call) && call.id === toolCallId && isRecord(call.function) && call.function.name === pendingCall.name && call.function.arguments === pendingCall.arguments);
+	}
+	async #run() {
+		const { cwd, model, origin, request } = this.#options;
+		try {
+			const connection = await model.openConnection();
+			this.#connection = connection;
+			this.#assertActive();
+			const acpClient = authorizeRequestTools(client({ name: "alint-model-adapter-acp" }));
+			await this.#bridge?.start();
+			this.#assertActive();
+			await connectWith(acpClient, connection, async (context) => {
+				await context.request(methods.agent.initialize, {
+					clientCapabilities: {},
+					clientInfo: {
+						name: "alint-model-adapter-acp",
+						version: "0.3.2"
+					},
+					protocolVersion: PROTOCOL_VERSION
+				});
+				this.#assertActive();
+				await context.buildSession({
+					...sessionExtensions(request.extensions),
+					cwd,
+					mcpServers: this.#bridge ? [this.#bridge.config(origin)] : []
+				}).withSession(async (session) => {
+					this.#cancelSession = () => context.notify(methods.agent.session.cancel, { sessionId: session.sessionId });
+					this.#assertActive();
+					for (let attempt = 0; attempt < 2; attempt += 1) {
+						const callCountBeforePrompt = this.#toolCallCount;
+						const prompt = session.prompt(attempt === 0 ? renderMessages(request) : "The request requires a tool call. Call the available function before returning an answer.");
+						let text = "";
+						for (;;) {
+							const message = await session.nextUpdate();
+							if (message.kind === "stop") {
+								await prompt;
+								if (message.stopReason === "cancelled") throw new Error("The ACP agent cancelled the prompt.");
+								if (requiresTool(request.toolChoice) && this.#toolCallCount === callCountBeforePrompt) break;
+								this.#outputs.push({
+									stopReason: message.stopReason,
+									text,
+									type: "completion",
+									usage: message.response.usage
+								});
+								return;
+							}
+							if (message.update.sessionUpdate === "agent_message_chunk" && message.update.content.type === "text") if (request.stream) this.#outputs.push({
+								text: message.update.content.text,
+								type: "text-delta"
+							});
+							else text += message.update.content.text;
+						}
+					}
+					throw new Error("The ACP agent did not satisfy tool_choice after one retry.");
+				});
+			});
+		} finally {
+			if (this.#timer) clearTimeout(this.#timer);
+			if (this.#bridge) {
+				this.#options.bridges.delete(this.#bridge.id);
+				await this.#bridge.close();
+			}
+			this.#finish();
+			await this.#disposeConnection();
+		}
+	}
+};
+/** Creates the OpenAI-compatible HTTP interface backed by configured ACP agents. */
+function createGateway(options) {
+	const models = new Map(options.models.map((model) => [model.id, model]));
+	const activeTurns = /* @__PURE__ */ new Set();
+	const bridges = /* @__PURE__ */ new Map();
+	const pendingTurns = /* @__PURE__ */ new Map();
+	const configuredMcpOrigin = options.mcpBaseUrl ? new URL(options.mcpBaseUrl).origin : void 0;
+	const app = new H3();
+	app.get("/v1/models", defineEventHandler(() => ({
+		data: options.models.map((model) => ({
+			created: 0,
+			id: model.id,
+			object: "model",
+			owned_by: model.name
+		})),
+		object: "list"
+	})));
+	app.all("/_alint/mcp/:bridgeId", defineEventHandler(async (event) => {
+		const bridge = bridges.get(getRouterParam(event, "bridgeId") ?? "");
+		if (!bridge || event.req.headers.get("authorization") !== `Bearer ${bridge.token}`) return new Response(null, { status: 404 });
+		return bridge.handleRequest(event.req);
+	}));
+	app.post("/v1/chat/completions", defineEventHandler(async (event) => {
+		const request = chatCompletionRequest(await event.req.json().catch(() => void 0));
+		if (!request) {
+			event.res.status = 400;
+			return openAIError("Invalid chat completion request.", "invalid_request_error");
+		}
+		if (request.temperature !== void 0) options.onCompatibilityDiagnostic?.({
+			field: "temperature",
+			message: "ACP has no temperature equivalent; the configured agent controls sampling.",
+			value: request.temperature
+		});
+		const model = models.get(request.model);
+		if (!model) {
+			event.res.status = 404;
+			return openAIError(`Unknown model: ${request.model}`, "invalid_request_error");
+		}
+		const toolResult = lastToolResult(request.messages);
+		let turn;
+		if (request.stream && (request.tools.length > 0 || toolResult)) {
+			event.res.status = 400;
+			return openAIError("Streaming tool calls are not supported.", "invalid_request_error");
+		}
+		if (toolResult) {
+			const pendingTurn = pendingTurns.get(toolResult.toolCallId);
+			if (!pendingTurn || !pendingTurn.resume(request, toolResult)) {
+				event.res.status = 400;
+				return openAIError(`Unknown tool call: ${toolResult.toolCallId}`, "invalid_request_error");
+			}
+			pendingTurns.delete(toolResult.toolCallId);
+			turn = pendingTurn;
+		} else {
+			const selectedTools = toolsForChoice(request.tools, request.toolChoice);
+			const origin = mcpOrigin(event.req.url, configuredMcpOrigin);
+			if (requiresTool(request.toolChoice) && selectedTools.length === 0) {
+				event.res.status = 400;
+				return openAIError("tool_choice requires a function present in tools.", "invalid_request_error");
+			}
+			if (selectedTools.length > 0 && !origin) {
+				event.res.status = 500;
+				return openAIError("mcpBaseUrl is required when the gateway is not accessed through loopback.", "server_error");
+			}
+			turn = new CompletionTurn({
+				bridges,
+				continuationTtlMs: options.continuationTtlMs ?? 3e4,
+				cwd: options.cwd ?? process.cwd(),
+				model,
+				onFinished: (finishedTurn, pendingCallIds) => {
+					activeTurns.delete(finishedTurn);
+					for (const callId of pendingCallIds) pendingTurns.delete(callId);
+				},
+				onPending: (call, pendingTurn) => pendingTurns.set(call.id, pendingTurn),
+				origin: origin ?? new URL(event.req.url).origin,
+				request,
+				tools: selectedTools
+			});
+			activeTurns.add(turn);
+			turn.start();
+		}
+		if (request.stream) return streamCompletion(turn, model.id);
+		let output;
+		try {
+			output = await turn.nextOutput(event.req.signal);
+		} catch {
+			event.res.status = 500;
+			return openAIError("The ACP agent could not complete the request.", "server_error");
+		}
+		if (output.type === "tool-call") {
+			turn.armContinuation(output.call.id);
+			options.onCompatibilityDiagnostic?.({
+				field: "usage",
+				message: "ACP usage is unavailable while a deferred tool call is pending; zero usage was reported.",
+				value: null
+			});
+			return chatCompletion(turn.modelId, {
+				finishReason: "tool_calls",
+				message: {
+					content: null,
+					role: "assistant",
+					tool_calls: [{
+						function: {
+							arguments: output.call.arguments,
+							name: output.call.name
+						},
+						id: output.call.id,
+						type: "function"
+					}]
+				}
+			}, {
+				inputTokens: 0,
+				outputTokens: 0,
+				totalTokens: 0
+			});
+		}
+		if (output.type === "text-delta") throw new Error("Text deltas are only emitted for streaming requests.");
+		return chatCompletion(turn.modelId, {
+			finishReason: finishReason(output.stopReason),
+			message: {
+				content: output.text,
+				role: "assistant"
+			}
+		}, output.usage);
+	}));
+	return Object.assign(app, { 
+	/**
+	* Cancels turns retained by the H3 application.
+	*
+	* Triggering workflow:
+	*
+	* {@link startGateway}
+	*   -> `GatewayApp.shutdown`
+	*     -> {@link CompletionTurn.cancel}
+	*
+	* Upstream:
+	* - {@link startGateway}
+	*
+	* Downstream:
+	* - {@link CompletionTurn.cancel}
+	*/
+async shutdown() {
+		await Promise.all([...activeTurns].map((turn) => turn.cancel(/* @__PURE__ */ new Error("The gateway is shutting down."))));
+		bridges.clear();
+		pendingTurns.clear();
+	} });
+}
+/** Starts an ephemeral loopback gateway for one CLI run. */
+async function startGateway(options) {
+	const app = createGateway(options);
+	const server = await serve(app, {
+		hostname: "127.0.0.1",
+		port: 0,
+		silent: true
+	}).ready();
+	let stopped = false;
+	return {
+		endpoint: new URL("/v1/", server.url).href,
+		/**
+		* Stops adapter work before closing the loopback listener.
+		*
+		* Triggering workflow:
+		*
+		* `ModelAdapterRuntime.shutdown`
+		*   -> `GatewayServer.shutdown`
+		*     -> {@link GatewayApp.shutdown}
+		*
+		* Upstream:
+		* - {@link startGateway}
+		*
+		* Downstream:
+		* - {@link GatewayApp.shutdown}
+		* - `Server.close`
+		*/
+		async shutdown() {
+			if (stopped) return;
+			stopped = true;
+			await app.shutdown();
+			await server.close(true);
+		}
+	};
+}
+/**
+* Allows an agent to invoke only the request-scoped tools supplied by the OpenAI caller.
+*
+* Triggering workflow:
+*
+* {@link CompletionTurn.#run}
+*   -> ACP `session/request_permission`
+*     -> {@link authorizeRequestTools}
+*
+* The ACP Codex adapter marks MCP tool approvals with `is_mcp_tool_approval`. Other
+* permission requests can execute commands or edit files, so they remain cancelled.
+*
+* Upstream:
+* - {@link CompletionTurn.#run}
+*
+* Downstream:
+* - ACP permission response
+*/
+function authorizeRequestTools(client) {
+	return client.onRequest(methods.client.session.requestPermission, ({ params }) => {
+		const meta = params._meta;
+		const allowOnce = params.options.find((option) => option.kind === "allow_once");
+		if (isRecord(meta) && meta.is_mcp_tool_approval === true && allowOnce) return { outcome: {
+			optionId: allowOnce.optionId,
+			outcome: "selected"
+		} };
+		return { outcome: { outcome: "cancelled" } };
+	});
+}
+function chatCompletion(model, choice, usage) {
+	return {
+		choices: [{
+			finish_reason: choice.finishReason,
+			index: 0,
+			message: choice.message
+		}],
+		created: Math.floor(Date.now() / 1e3),
+		id: `chatcmpl-${crypto.randomUUID()}`,
+		model,
+		object: "chat.completion",
+		...usage ? { usage: {
+			completion_tokens: usage.outputTokens,
+			prompt_tokens: usage.inputTokens,
+			total_tokens: usage.totalTokens
+		} } : {}
+	};
+}
+function chatCompletionChunk(id, created, model, choices) {
+	return {
+		choices,
+		created,
+		id,
+		model,
+		object: "chat.completion.chunk"
+	};
+}
+function chatCompletionRequest(value) {
+	const result = safeParse(chatCompletionRequestSchema, value);
+	if (!result.success) return;
+	const { messages, model, parallel_tool_calls: _parallelToolCalls, stream, stream_options: _streamOptions, temperature, tool_choice: toolChoice, tools, ...extensions } = result.output;
+	return {
+		extensions,
+		messages,
+		model,
+		stream,
+		temperature,
+		toolChoice,
+		tools
+	};
+}
+function connectWith(client, connection, operation) {
+	return connection.kind === "agent-app" ? client.connectWith(connection.agent, operation) : client.connectWith(connection.stream, operation);
+}
+function enqueueSse(controller, encoder, value) {
+	controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
+}
+function finishReason(stopReason) {
+	switch (stopReason) {
+		case "cancelled":
+		case "end_turn": return "stop";
+		case "max_tokens":
+		case "max_turn_requests": return "length";
+		case "refusal": return "content_filter";
+	}
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function lastToolResult(messages) {
+	const message = messages.at(-1);
+	if (!isRecord(message) || message.role !== "tool" || typeof message.tool_call_id !== "string") return;
+	return {
+		content: typeof message.content === "string" ? message.content : JSON.stringify(message.content),
+		toolCallId: message.tool_call_id
+	};
+}
+function mcpOrigin(requestUrl, configuredOrigin) {
+	if (configuredOrigin) return configuredOrigin;
+	const url = new URL(requestUrl);
+	return [
+		"127.0.0.1",
+		"[::1]",
+		"localhost"
+	].includes(url.hostname) ? url.origin : void 0;
+}
+function openAIError(message, type) {
+	return { error: {
+		message,
+		type
+	} };
+}
+function renderMessages(request) {
+	const requiredTool = request.toolChoice && typeof request.toolChoice === "object" ? request.toolChoice.function.name : void 0;
+	return [
+		"Process this OpenAI chat transcript. Preserve message order and role intent.",
+		"Return only the assistant response requested by the transcript.",
+		request.toolChoice === "required" ? "You must call one of the supplied tools before answering." : "",
+		requiredTool ? `You must call the ${JSON.stringify(requiredTool)} tool before answering.` : "",
+		"",
+		JSON.stringify({ messages: request.messages })
+	].join("\n");
+}
+function requiresTool(choice) {
+	return choice === "required" || typeof choice === "object";
+}
+function sessionExtensions(extensions) {
+	const { _meta: explicitMeta, ...fields } = extensions;
+	if (Object.keys(fields).length === 0 && !isRecord(explicitMeta)) return {};
+	return {
+		...fields,
+		_meta: {
+			...fields,
+			...isRecord(explicitMeta) ? explicitMeta : {}
+		}
+	};
+}
+function streamCompletion(turn, model) {
+	const encoder = new TextEncoder();
+	const id = `chatcmpl-${crypto.randomUUID()}`;
+	const created = Math.floor(Date.now() / 1e3);
+	const body = new ReadableStream({
+		async cancel() {
+			await turn.cancel(/* @__PURE__ */ new Error("The OpenAI stream consumer cancelled the request."));
+		},
+		async start(controller) {
+			try {
+				for (;;) {
+					const output = await turn.nextOutput();
+					if (output.type === "text-delta") {
+						enqueueSse(controller, encoder, chatCompletionChunk(id, created, model, [{
+							delta: {
+								content: output.text,
+								role: "assistant"
+							},
+							index: 0
+						}]));
+						continue;
+					}
+					if (output.type === "tool-call") throw new Error("Streaming tool calls are not supported.");
+					enqueueSse(controller, encoder, chatCompletionChunk(id, created, model, [{
+						delta: {},
+						finish_reason: finishReason(output.stopReason),
+						index: 0
+					}]));
+					if (output.usage) enqueueSse(controller, encoder, {
+						...chatCompletionChunk(id, created, model, []),
+						usage: {
+							completion_tokens: output.usage.outputTokens,
+							prompt_tokens: output.usage.inputTokens,
+							total_tokens: output.usage.totalTokens
+						}
+					});
+					controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+					controller.close();
+					return;
+				}
+			} catch (error) {
+				controller.error(error);
+			}
+		}
+	});
+	return new Response(body, { headers: {
+		"cache-control": "no-cache",
+		"content-type": "text/event-stream; charset=utf-8"
+	} });
+}
+function toolsForChoice(tools, choice) {
+	if (choice === "none") return [];
+	if (typeof choice === "object") return tools.filter((tool) => tool.function.name === choice.function.name);
+	return tools;
+}
+//#endregion
+export { createCommandModel, createGateway, startGateway };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@alint-js/model-adapter-acp",
+  "type": "module",
+  "version": "0.4.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "h3": "2.0.1-rc.25",
+    "tinyexec": "^1.2.4",
+    "valibot": "^1.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@alint-js/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  }
+}