@mono-agent/agent-runtime 0.17.1 → 0.18.0

package/src/ai/providers/acp.js

@@ -0,0 +1,523 @@
+// @ts-check
+
+import { isAbsolute } from "node:path";
+import { runtimeCapabilities } from "../runtime/capabilities.js";
+import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+import {
+  AcpClientError,
+  connectAcpProfile,
+} from "./acp-client.js";
+import {
+  decodeAcpProviderSessionId,
+  encodeAcpProviderSessionId,
+  validateAcpProviderSessionId,
+} from "./acp-session-tokens.js";
+import {
+  ownAcpSessionUpdateKind,
+  sanitizeAcpHostValueWithStatus,
+} from "./acp-privacy.js";
+
+/** @param {any} callback @param {any} event */
+function emit(callback, event) {
+  try { callback?.(event); } catch { /* observers cannot break a provider turn */ }
+}
+
+/** @param {any} value */
+function jsonSafe(value) {
+  try { return JSON.parse(JSON.stringify(value)); } catch { return null; }
+}
+
+/** @param {any} content @returns {string} */
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return content == null ? "" : String(content);
+  return content
+    .filter((block) => block?.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("");
+}
+
+/** @param {any} block @param {any} promptCapabilities */
+function normalizePromptBlock(block, promptCapabilities) {
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    throw new AcpClientError("invalid_request", "ACP prompt content blocks must be objects.");
+  }
+  if (block.type === "text" && typeof block.text === "string") {
+    return { type: "text", text: block.text };
+  }
+  // Resource links are ACP baseline content and must survive normalization.
+  if (block.type === "resource_link"
+    && typeof block.uri === "string"
+    && typeof block.name === "string") {
+    return jsonSafe(block);
+  }
+  if (block.type === "image" && promptCapabilities?.image === true) return jsonSafe(block);
+  if (block.type === "audio" && promptCapabilities?.audio === true) return jsonSafe(block);
+  if (block.type === "resource" && promptCapabilities?.embeddedContext === true) return jsonSafe(block);
+  throw new AcpClientError("capability_missing", `ACP agent cannot accept prompt content type '${block.type || "unknown"}'.`);
+}
+
+/**
+ * Convert runtime history to one ACP user prompt. A fresh ACP session has no
+ * protocol method for importing arbitrary prior assistant turns, so the
+ * client-owned path sends them as a labelled transcript while preserving
+ * baseline resource_link blocks as real blocks. A resumed session sends only
+ * the latest user content because the agent already owns prior history.
+ * @param {string} systemPrompt
+ * @param {any[]} messages
+ * @param {{includeHistory: boolean, includeSystem: boolean, promptCapabilities: any}} options
+ */
+function runtimePrompt(systemPrompt, messages, options) {
+  const source = Array.isArray(messages) ? messages : [];
+  const selected = options.includeHistory
+    ? source
+    : (() => {
+        for (let index = source.length - 1; index >= 0; index -= 1) {
+          if (source[index]?.role === "user") return [source[index]];
+        }
+        return source.length > 0 ? [source[source.length - 1]] : [];
+      })();
+  /** @type {any[]} */
+  const blocks = [];
+  if (options.includeSystem && systemPrompt.trim()) {
+    blocks.push({ type: "text", text: `[System]\n${systemPrompt}` });
+  }
+
+  selected.forEach((message, messageIndex) => {
+    const role = typeof message?.role === "string" ? message.role : "user";
+    const content = message?.content;
+    if (Array.isArray(content)) {
+      let labelled = false;
+      for (const block of content) {
+        const normalized = normalizePromptBlock(block, options.promptCapabilities);
+        if (normalized.type === "text") {
+          blocks.push({
+            ...normalized,
+            text: `${labelled ? "" : `[${role}]\n`}${normalized.text}`,
+          });
+          labelled = true;
+        } else {
+          blocks.push(normalized);
+        }
+      }
+      if (content.length === 0) blocks.push({ type: "text", text: `[${role}]\n` });
+      return;
+    }
+    const text = textFromContent(content);
+    if (text || messageIndex === selected.length - 1) {
+      blocks.push({ type: "text", text: `[${role}]\n${text}` });
+    }
+  });
+  if (blocks.length === 0) blocks.push({ type: "text", text: "" });
+  return blocks;
+}
+
+/** @param {unknown} value @param {string} key */
+function ownValue(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, key)) {
+    return undefined;
+  }
+  return /** @type {Record<string, unknown>} */ (value)[key];
+}
+
+/** @param {any} update @param {any} state */
+function normalizeUpdate(update, state) {
+  const protocolBody = update.update;
+  const updateKind = ownAcpSessionUpdateKind(protocolBody);
+  if (updateKind === null) {
+    state.protocolError ||= new AcpClientError("protocol", "ACP session update has no valid own discriminator.");
+    return [{ type: "acp_session_update_rejected", reason: "invalid_discriminator" }];
+  }
+  const sanitized = sanitizeAcpHostValueWithStatus(protocolBody, [update.sessionId]);
+  if (sanitized.truncated) {
+    state.protocolError ||= new AcpClientError(
+      "protocol",
+      "ACP session update exceeded safe host normalization limits.",
+    );
+    return [{ type: "acp_session_update_rejected", reason: "normalization_limit" }];
+  }
+  const publicBody = sanitized.value;
+  /** @param {unknown} value */
+  const publicValue = (value) => sanitizeAcpHostValueWithStatus(value, [update.sessionId]).value;
+  const raw = {
+    type: "acp_session_update",
+    update: jsonSafe({ ...publicBody, sessionUpdate: updateKind }),
+  };
+  /** @type {any[]} */
+  const events = [raw];
+  switch (updateKind) {
+    case "agent_message_chunk": {
+      const content = publicValue(ownValue(protocolBody, "content"));
+      if (content?.type === "text" && typeof content.text === "string") state.text.push(content.text);
+      events.push({ type: "assistant", message: { content: [jsonSafe(content)] } });
+      break;
+    }
+    case "agent_thought_chunk": {
+      const content = publicValue(ownValue(protocolBody, "content"));
+      if (content?.type === "text" && typeof content.text === "string") state.thinking.push(content.text);
+      events.push({
+        type: "assistant",
+        message: { content: [{ type: "thinking", text: content?.type === "text" ? content.text : "" }] },
+      });
+      break;
+    }
+    case "tool_call":
+      events.push({
+        type: "assistant",
+        message: {
+          content: [{
+            type: "tool_use",
+            id: publicValue(ownValue(protocolBody, "toolCallId")),
+            name: publicValue(ownValue(protocolBody, "name"))
+              || publicValue(ownValue(protocolBody, "title"))
+              || "acp_tool",
+            input: jsonSafe(publicValue(ownValue(protocolBody, "rawInput") ?? {})),
+          }],
+        },
+      });
+      break;
+    case "tool_call_update":
+      if (["completed", "failed"].includes(/** @type {any} */ (ownValue(protocolBody, "status")))) {
+        const rawOutput = ownValue(protocolBody, "rawOutput") ?? ownValue(protocolBody, "content") ?? "";
+        const output = publicValue(rawOutput);
+        events.push({
+          type: "user",
+          message: {
+            content: [{
+              type: "tool_result",
+              tool_use_id: publicValue(ownValue(protocolBody, "toolCallId")),
+              content: typeof output === "string" ? output : JSON.stringify(jsonSafe(output)),
+              is_error: ownValue(protocolBody, "status") === "failed",
+            }],
+          },
+        });
+      }
+      break;
+    case "usage_update":
+      state.usage = {
+        totalTokens: Number(ownValue(protocolBody, "used")) || 0,
+        contextWindow: Number(ownValue(protocolBody, "size")) || 0,
+        cost: publicValue(ownValue(protocolBody, "cost")) || null,
+      };
+      events.push({
+        type: "context_usage",
+        model: state.model,
+        source: "acp",
+        context: {
+          used: Number(ownValue(protocolBody, "used")) || 0,
+          window: Number(ownValue(protocolBody, "size")) || 0,
+        },
+        cost: publicValue(ownValue(protocolBody, "cost")) || null,
+      });
+      break;
+    case "plan":
+    case "plan_update":
+    case "plan_removed":
+      events.push({
+        type: "plan",
+        source: "acp",
+        update: jsonSafe({ ...publicBody, sessionUpdate: updateKind }),
+      });
+      break;
+    default:
+      break;
+  }
+  return events;
+}
+
+/** @param {any} descriptor @param {any} req */
+function workspaceFor(descriptor, req) {
+  if (descriptor.workspaceOwner === "agent") return descriptor.workspacePath;
+  const cwd = req.cwd || descriptor.workspacePath || descriptor.cwd || process.cwd();
+  if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+    throw new AcpClientError("invalid_request", "ACP runtime cwd must be absolute.");
+  }
+  return cwd;
+}
+
+/** @param {any} descriptor */
+function sessionConfig(descriptor) {
+  const config = descriptor.sessionConfig || {};
+  return {
+    additionalDirectories: [...(config.additionalDirectories || [])],
+    mcpServers: descriptor.mcpOwner === "agent" ? [] : [...(config.mcpServers || [])],
+  };
+}
+
+/** @param {any} connection @param {string} sessionId @param {any} setupResponse @param {any} descriptor */
+async function applyClientConfiguration(connection, sessionId, setupResponse, descriptor) {
+  if (descriptor.configurationOwner === "agent") return { modeApplied: false, configOptionsApplied: [] };
+  const config = descriptor.sessionConfig || {};
+  let modes = setupResponse?.modes || null;
+  let configOptions = Array.isArray(setupResponse?.configOptions) ? setupResponse.configOptions : [];
+  let modeApplied = false;
+  const applied = [];
+  if (config.modeId !== undefined) {
+    const available = modes?.availableModes?.some((mode) => mode?.id === config.modeId) === true;
+    if (!available) throw new AcpClientError("capability_missing", "Configured ACP session mode was not advertised.");
+    await connection.setSessionMode(sessionId, config.modeId);
+    modeApplied = true;
+  }
+  for (const [configId, value] of Object.entries(config.configOptions || {})) {
+    const option = configOptions.find((candidate) => candidate?.id === configId);
+    if (!option) throw new AcpClientError("capability_missing", "Configured ACP session option was not advertised.");
+    if (option.type === "boolean") {
+      if (typeof value !== "boolean") {
+        throw new AcpClientError("invalid_profile", "ACP boolean config option requires a boolean value.");
+      }
+    } else {
+      if (typeof value !== "string" || !selectValues(option.options).includes(value)) {
+        throw new AcpClientError("invalid_profile", "ACP select config option value was not advertised.");
+      }
+    }
+    const response = await connection.setSessionConfigOption(sessionId, configId, value);
+    configOptions = Array.isArray(response?.configOptions) ? response.configOptions : configOptions;
+    applied.push(configId);
+  }
+  return { modeApplied, configOptionsApplied: applied };
+}
+
+/** @param {any[]} options */
+function selectValues(options) {
+  if (!Array.isArray(options)) return [];
+  const values = [];
+  for (const item of options) {
+    if (typeof item?.value === "string") values.push(item.value);
+    if (Array.isArray(item?.options)) values.push(...selectValues(item.options));
+  }
+  return values;
+}
+
+/** @param {any} connection @param {any} descriptor @param {any} req @param {string} profileId @param {(notification:any)=>void} onUpdate */
+async function openSession(connection, descriptor, req, profileId, onUpdate) {
+  const cwd = workspaceFor(descriptor, req);
+  const config = sessionConfig(descriptor);
+  const baseRequest = { cwd, ...config };
+  if (!req.providerSessionId) {
+    const response = await connection.newSession(baseRequest);
+    return { sessionId: response.sessionId, response, resumed: false, resumeMethod: null };
+  }
+  const decoded = decodeAcpProviderSessionId(req.providerSessionId);
+  if (decoded.profileId !== profileId) {
+    throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
+  }
+  const remove = connection.onSessionUpdate(decoded.sessionId, onUpdate);
+  try {
+    const strategy = descriptor.sessionConfig?.resumeStrategy || "auto";
+    if (strategy === "resume" || (strategy === "auto" && connection.hasCapability("resume"))) {
+      if (!connection.hasCapability("resume")) {
+        throw new AcpClientError("capability_missing", "ACP agent did not advertise session/resume.");
+      }
+      const response = await connection.resumeSession({ sessionId: decoded.sessionId, ...baseRequest });
+      return { sessionId: decoded.sessionId, response, resumed: true, resumeMethod: "resume" };
+    }
+    if (strategy === "load" || (strategy === "auto" && connection.hasCapability("load"))) {
+      if (!connection.hasCapability("load")) {
+        throw new AcpClientError("capability_missing", "ACP agent did not advertise session/load.");
+      }
+      const response = await connection.loadSession({ sessionId: decoded.sessionId, ...baseRequest });
+      return { sessionId: decoded.sessionId, response, resumed: true, resumeMethod: "load" };
+    }
+    if (strategy === "auto") {
+      const response = await connection.newSession(baseRequest);
+      return {
+        sessionId: response.sessionId,
+        response,
+        resumed: false,
+        resumeMethod: "new_fallback",
+      };
+    }
+    throw new AcpClientError("invalid_profile", "Invalid ACP resume strategy.");
+  } finally {
+    remove();
+  }
+}
+
+/** @param {unknown} error @param {boolean} aborted */
+function failureFor(error, aborted) {
+  const coded = /** @type {any} */ (error);
+  if (aborted || coded?.code === "cancelled") return { cancelled: true, failureKind: null, message: null };
+  if (coded?.code === "timeout") return { cancelled: false, failureKind: "timeout", message: coded.message };
+  if (coded?.code === "spawn") return { cancelled: false, failureKind: "spawn", message: coded.message };
+  return {
+    cancelled: false,
+    failureKind: "provider_protocol",
+    message: error instanceof Error ? error.message : "ACP provider protocol failed.",
+  };
+}
+
+/**
+ * Runtime bridge for one ACP v1 profile turn.
+ * @param {string} systemPrompt
+ * @param {any} req
+ */
+export async function generateAcpResponse(systemPrompt, req) {
+  const start = Date.now();
+  const profileId = req?.model?.model;
+  const reference = req?.model?.reference || `acp:${profileId || "unknown"}`;
+  const events = [];
+  const state = { text: [], thinking: [], model: reference, usage: null, protocolError: null };
+  const onEvent = req?.onEvent;
+  const capture = (event) => {
+    events.push(event);
+    emit(onEvent, event);
+  };
+  capture({ type: "provider_request_started", sdk: "acp", model: reference, runtime: "acp-stdio", timestamp: start });
+  let connection;
+  let sessionId = null;
+  let providerSessionId = null;
+  let setup = null;
+  let configuration = { modeApplied: false, configOptionsApplied: [] };
+  try {
+    if (req?.providerSessionId != null) {
+      providerSessionId = validateAcpProviderSessionId(req.providerSessionId, profileId);
+    }
+    connection = await connectAcpProfile(profileId, {
+      resolveAcpProfile: req.resolveAcpProfile,
+      onAcpInteractionRequest: req.onAcpInteractionRequest,
+      sandbox: req.toolContext?.sandbox || req.sandbox,
+      sandboxPolicy: resolveSandboxPolicy(req.toolContext, req.sandboxPolicy),
+      sandboxEngine: req.sandboxEngine || req.toolContext?.sandboxEngine,
+      cwd: req.cwd,
+      signal: req.abortSignal,
+      context: { operation: "run", model: reference },
+      operation: "run",
+    });
+    capture({
+      type: "capabilities_resolved",
+      sdk: "acp",
+      model: reference,
+      capabilitiesUsed: {
+        protocol_version: connection.initializeResult.protocolVersion,
+        agent_capabilities: jsonSafe(connection.initializeResult.agentCapabilities || {}),
+      },
+    });
+    const onUpdate = (notification) => {
+      for (const event of normalizeUpdate(notification, state)) capture(event);
+    };
+    setup = await openSession(connection, connection.descriptor, req, profileId, onUpdate);
+    sessionId = setup.sessionId;
+    providerSessionId = encodeAcpProviderSessionId(profileId, sessionId);
+    configuration = await applyClientConfiguration(
+      connection,
+      sessionId,
+      setup.response,
+      connection.descriptor,
+    );
+    const remove = connection.onSessionUpdate(sessionId, onUpdate);
+    let promptResponse;
+    try {
+      promptResponse = await connection.prompt(
+        sessionId,
+        runtimePrompt(systemPrompt, req.messages || [], {
+          includeHistory: !setup.resumed,
+          includeSystem: !setup.resumed && connection.descriptor.configurationOwner === "client",
+          promptCapabilities: connection.initializeResult.agentCapabilities?.promptCapabilities || {},
+        }),
+        { signal: req.abortSignal },
+      );
+    } finally {
+      remove();
+    }
+    if (state.protocolError) throw state.protocolError;
+    // PromptResponse.usage is explicitly unstable in ACP 1.3.0. The stable
+    // cumulative source is the latest top-level usage_update notification.
+    const usage = state.usage;
+    capture({
+      type: "provider_request_completed",
+      sdk: "acp",
+      model: reference,
+      runtime: "acp-stdio",
+      timestamp: Date.now(),
+      durationMs: Date.now() - start,
+      cancelled: promptResponse.stopReason === "cancelled",
+    });
+    const limited = promptResponse.stopReason === "max_tokens" || promptResponse.stopReason === "max_turn_requests";
+    return {
+      text: state.text.join("") || null,
+      thinking: state.thinking.join(""),
+      events,
+      usage: usage ? {
+        total_tokens: usage.totalTokens || null,
+        context_window: usage.contextWindow || null,
+        cost: usage.cost,
+      } : {},
+      durationMs: Date.now() - start,
+      numTurns: 1,
+      model: reference,
+      effort: req.effort || null,
+      sdk: "acp",
+      cancelled: promptResponse.stopReason === "cancelled",
+      error: limited ? `ACP agent stopped with ${promptResponse.stopReason}.` : null,
+      failureKind: limited ? "usage_limit" : null,
+      providerSessionId,
+      runtimeWarnings: [],
+      diagnostics: {
+        acp_protocol_version: connection.initializeResult.protocolVersion,
+        acp_profile_id: profileId,
+        acp_session_id_encoded: true,
+        acp_stop_reason: promptResponse.stopReason,
+        acp_resume_method: setup.resumeMethod,
+        acp_mode_applied: configuration.modeApplied,
+        acp_config_options_applied: configuration.configOptionsApplied,
+      },
+      capabilitiesUsed: {
+        session_resume: setup.resumed,
+        session_load: setup.resumeMethod === "load",
+        session_config: configuration.modeApplied || configuration.configOptionsApplied.length > 0,
+        mcp: connection.descriptor.mcpOwner === "client"
+          && (connection.descriptor.sessionConfig?.mcpServers || []).length > 0,
+      },
+      structuredResult: undefined,
+      structuredResultSource: null,
+    };
+  } catch (error) {
+    const failure = failureFor(error, req?.abortSignal?.aborted === true);
+    capture({
+      type: "provider_request_completed",
+      sdk: "acp",
+      model: reference,
+      runtime: "acp-stdio",
+      timestamp: Date.now(),
+      durationMs: Date.now() - start,
+      cancelled: failure.cancelled,
+    });
+    return {
+      text: state.text.join("") || null,
+      thinking: state.thinking.join(""),
+      events,
+      usage: {},
+      durationMs: Date.now() - start,
+      numTurns: 0,
+      model: reference,
+      effort: req?.effort || null,
+      sdk: "acp",
+      cancelled: failure.cancelled,
+      error: failure.message,
+      errorDetails: failure.message ? {
+        acp_error_code: typeof error?.code === "string" ? error.code : "protocol",
+      } : null,
+      failureKind: failure.failureKind,
+      providerSessionId,
+      runtimeWarnings: [],
+      diagnostics: {
+        acp_profile_id: typeof profileId === "string" ? profileId : null,
+        acp_session_id_encoded: providerSessionId != null,
+        acp_stop_reason: failure.cancelled ? "cancelled" : "error",
+      },
+      capabilitiesUsed: {},
+      structuredResult: undefined,
+      structuredResultSource: null,
+    };
+  } finally {
+    await connection?.close().catch(() => {});
+  }
+}
+
+export const acpRuntimeBridge = {
+  id: "acp-stdio",
+  kind: "acp",
+  capabilities: runtimeCapabilities("acp"),
+  supports: (ref, options) => ref?.sdk === "acp" && options?.executionMode === "acp",
+  execute: generateAcpResponse,
+};

package/src/ai/runtime/capabilities.js

@@ -57,6 +57,22 @@ export const RUNTIME_CAPABILITIES = {
     supports_native_subagents: false,
     tool_policy: TOOL_POLICY_ALLOW_ALL_ONLY,
   },
+  acp: {
+    runtime: "acp-stdio",
+    ...COMMON_CAPABILITIES,
+    structured_output: false,
+    supports_session_resume: true,
+    // Runtime request-scoped MCP servers are not projected into ACP sessions.
+    // Profiles may own static ACP MCP configuration, but that is not the
+    // supports_mcp contract advertised to the route capability gate.
+    supports_mcp: false,
+    supports_skills: false,
+    supports_builtin_tools: false,
+    supports_live_input: false,
+    supports_native_subagents: false,
+    supports_request_tool_environment: false,
+    tool_policy: TOOL_POLICY_ALLOW_ALL_ONLY,
+  },
 };
 
 export function runtimeCapabilities(sdkOrModel) {

package/src/ai/runtime/model-refs.js

@@ -3,7 +3,8 @@
 /** @typedef {import('../types.js').RuntimeModelRef} RuntimeModelRef */
 
 const RESERVED_RUNTIME_IDS = new Set(["openai", "vercel", "claude-code", "codex-cli"]);
-const ACTIVE_RUNTIME_IDS = new Set(["claude", "pi", "codex", "opencode"]);
+const ACTIVE_RUNTIME_IDS = new Set(["claude", "pi", "codex", "opencode", "acp"]);
+const ACP_PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
 function requirePart(value, message) {
   if (!value || typeof value !== "string" || value.trim() !== value) {
@@ -74,6 +75,14 @@ export function sdkFromModelReference(value) {
 export function parseRuntimeModelReference(value) {
   if (!value || typeof value !== "string") throw new Error("model reference required");
 
+  if (value.startsWith("acp:")) {
+    const profileId = requirePart(value.slice("acp:".length), "ACP profile id required");
+    if (!ACP_PROFILE_ID_RE.test(profileId)) {
+      throw new Error("invalid acp model reference; expected acp:<profile-id>");
+    }
+    return { sdk: "acp", model: profileId, reference: value };
+  }
+
   if (value.startsWith("pi:")) {
     const rest = value.slice("pi:".length);
     const i = rest.indexOf(":");
@@ -120,6 +129,7 @@ export const ACTIVE_RUNTIME_KINDS = [...ACTIVE_RUNTIME_IDS];
 export const RESERVED_RUNTIME_KINDS = [...RESERVED_RUNTIME_IDS];
 
 // intelligence-ramp: which model refs can run under which execution_mode.
+//   sdk='acp'      → ACP only (dedicated stdio client mode)
 //   sdk='claude'   → CLI (claude binary) or SDK (Anthropic)
 //   sdk='codex'    → CLI only (codex app-server)
 //   sdk='opencode' → CLI only (opencode server via @opencode-ai/sdk)
@@ -143,6 +153,11 @@ export function executionModeIncompatibilityReason(modelRefOrParsed, executionMo
   }
   if (!parsed) return null;
   if (!executionMode) return null;
+  if (executionMode === "acp") {
+    return parsed.sdk === "acp"
+      ? null
+      : `sdk \`${parsed.sdk}\` is not supported under ACP execution mode.`;
+  }
   if (executionMode === "sdk") {
     if (parsed.sdk === "codex") {
       return "Codex CLI requires CLI execution mode.";
@@ -150,12 +165,16 @@ export function executionModeIncompatibilityReason(modelRefOrParsed, executionMo
     if (parsed.sdk === "opencode") {
       return "OpenCode CLI requires CLI execution mode.";
     }
+    if (parsed.sdk === "acp") {
+      return "ACP profiles require ACP execution mode.";
+    }
     return null;
   }
   if (executionMode !== "cli") return null;
   if (parsed.sdk === "claude") return null;
   if (parsed.sdk === "codex") return null;
   if (parsed.sdk === "opencode") return null;
+  if (parsed.sdk === "acp") return "ACP profiles require ACP execution mode.";
   if (parsed.sdk === "pi") {
     const provider = parsed.provider || "unknown";
     const suffix = provider === "openai-codex" ? "; use codex:<model> for Codex CLI" : "";

package/src/ai/runtime/registry.js

@@ -25,6 +25,12 @@ import { COMMON_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";
 // pre-Phase-2 behaviour for any agent that hasn't opted in.
 /** @type {Object<string, BridgeSpec>} */
 const builtinBridgeSpecs = {
+  "acp-stdio": {
+    id: "acp-stdio",
+    supports: (ref, options) => ref?.sdk === "acp" && options?.executionMode === "acp",
+    capabilities: () => runtimeCapabilities("acp"),
+    load: async () => (await import("../providers/acp.js")).acpRuntimeBridge,
+  },
   "claude-code": {
     id: "claude-code",
     supports: (ref, options) => ref?.sdk === "claude" && options?.executionMode === "cli",

package/src/ai/runtime/router.js

@@ -20,7 +20,7 @@
 //     so the router is a drop-in replacement for createRuntime(host).
 //
 //   chain entries:
-//     { model: ModelRef, executionMode?: "sdk" | "cli", effort?: string|null,
+//     { model: ModelRef, executionMode?: "sdk" | "cli" | "acp", effort?: string|null,
 //       requires?: Capabilities }
 //   shorthand: a bare ModelRef is also accepted (no requirements).
 //   effort string = fixed for that route, undefined = inherit the legacy run
@@ -683,6 +683,8 @@ function routeSafetyContract(mode, entry, piSandboxPolicy) {
       return { mode, sandbox: "codex-native", tools: "exact-allow-all" };
     case "opencode":
       return { mode, sandbox: "provider-native", tools: "exact-allow-all" };
+    case "acp":
+      return { mode, sandbox: "provider-native", tools: "exact-allow-all" };
     default:
       return { mode, sandbox: "unsupported", tools: "unsupported" };
   }
@@ -852,6 +854,7 @@ function projectPerRouteNativeOptions(entry, options) {
       return projected;
     case "codex":
     case "opencode":
+    case "acp":
       delete projected.sandboxPolicy;
       delete projected.sandboxEngine;
       projected.allowedTools = ["*"];