@mono-agent/agent-runtime 0.20.10 → 0.20.14

package/src/ai/runtime/capabilities.js

@@ -1,7 +1,4 @@
-import {
-  TOOL_POLICY_ALLOW_ALL_ONLY,
-  TOOL_POLICY_PROJECTED,
-} from "./tool-policy.js";
+import { TOOL_POLICY_PROJECTED } from "./tool-policy.js";
 
 export const COMMON_CAPABILITIES = {
   streaming: true,
@@ -15,18 +12,9 @@ export const COMMON_CAPABILITIES = {
   supports_live_input: true,
   supports_native_subagents: true,
   supports_request_tool_environment: false,
-  supports_fast_mode: false,
-  tool_policy: TOOL_POLICY_PROJECTED,
 };
 
 export const RUNTIME_CAPABILITIES = {
-  claude: {
-    runtime: "sdk",
-    ...COMMON_CAPABILITIES,
-    // The Claude Agent SDK persists sessions on disk; the bridge resumes
-    // them via queryOptions.resume when options.sessionId is supplied.
-    supports_session_resume: true,
-  },
   pi: {
     runtime: "pi-agent",
     ...COMMON_CAPABILITIES,
@@ -38,50 +26,17 @@ export const RUNTIME_CAPABILITIES = {
     supports_native_subagents: false,
     supports_request_tool_environment: true,
     supports_mcp_apps: true,
-  },
-  codex: {
-    runtime: "cli",
-    ...COMMON_CAPABILITIES,
-    // The codex-app bridge keeps the app-server subprocess + thread alive
-    // when options.sessionKeepAlive is set; resumed turns reuse the thread.
-    supports_session_resume: true,
-    supports_fast_mode: true,
-    tool_policy: TOOL_POLICY_ALLOW_ALL_ONLY,
-  },
-  opencode: {
-    runtime: "cli",
-    ...COMMON_CAPABILITIES,
-    structured_output: false,
-    supports_session_resume: false,
-    supports_mcp: false,
-    supports_skills: false,
-    supports_live_input: false,
-    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,
+    tool_policy: TOOL_POLICY_PROJECTED,
   },
 };
 
-export function runtimeCapabilities(sdkOrModel) {
-  if (!sdkOrModel) throw new Error("runtimeCapabilities requires a model reference or sdk kind");
-  const sdk = typeof sdkOrModel === "string" ? sdkOrModel : sdkOrModel?.sdk;
-  if (!sdk) throw new Error("runtimeCapabilities: unrecognized argument");
-  const caps = RUNTIME_CAPABILITIES[sdk];
-  if (!caps) throw new Error(`unknown provider sdk: ${sdk}`);
-  return { kind: sdk, ...caps };
+/**
+ * @param {*} [_legacySelection]
+ * @returns {{kind: "pi"} & typeof RUNTIME_CAPABILITIES.pi}
+ */
+export function runtimeCapabilities(_legacySelection) {
+  // Capability lookup no longer selects a backend. The ignored optional value
+  // keeps the still-separate router migration type-safe without allowing its
+  // legacy route ids to influence the sole surviving runtime contract.
+  return { kind: "pi", ...RUNTIME_CAPABILITIES.pi };
 }

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

@@ -2,70 +2,139 @@
 
 /** @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", "acp"]);
-const ACP_PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PROVIDER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
-function requirePart(value, message) {
-  if (!value || typeof value !== "string" || value.trim() !== value) {
-    throw new Error(message);
+/**
+ * Control (`Cc`), format (`Cf`), line- and paragraph-separator code points. Every one of them
+ * either moves the cursor or is invisible, which is what lets a model id restyle or extend
+ * the diagnostic that quotes it -- and an *accepted* reference is quoted verbatim, without
+ * re-validation, by `mono-agent validate`, `doctor`, the TUI, the web console, the daemon log
+ * and launchd's captured stdout, all of them line-oriented and durable.
+ *
+ * Deliberately the same set that `DIAGNOSTIC_UNSAFE_CHARACTERS` in @mono-agent/runtime-adapter
+ * escapes when it quotes a *rejected* value: that layer makes an unparseable value safe to
+ * print, this one makes a parsed value safe to print. runtime-adapter's model-reference bound
+ * suite asserts the two agree code point by code point rather than by comment.
+ */
+const UNQUOTABLE_REFERENCE_CHARACTERS = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+/**
+ * @param {string} provider
+ * @param {string} model
+ */
+function rejectRemovedRuntimeReference(provider, model) {
+  if (provider === "codex") {
+    throw new Error(`codex is no longer a runtime backend; use openai-codex:${model}`);
+  }
+  if (provider === "claude" || provider === "claude-code") {
+    throw new Error(`${provider} is no longer a runtime backend; use anthropic:${model}`);
+  }
+  if (provider === "codex-cli") {
+    throw new Error(`codex-cli is no longer a runtime backend; use openai-codex:${model}`);
+  }
+  if (provider === "acp") {
+    throw new Error(
+      "ACP is no longer a runtime backend; use <provider>:<model> for Pi models, or mono-agent bridge acp to serve mono-agent over ACP",
+    );
+  }
+  if (provider === "vercel") {
+    const replacement = model.includes(":") ? model : "<provider>:<model>";
+    throw new Error(`vercel:<provider>:<model> is no longer supported; use ${replacement} directly`);
+  }
+  if (provider === "opencode" && model.includes(":")) {
+    throw new Error(`the opencode:<provider>:<model> runtime form is no longer supported; use ${model}`);
+  }
+}
+
+/** @param {string} provider */
+function requireProvider(provider) {
+  if (!PROVIDER_ID_RE.test(provider)) {
+    throw new Error("invalid provider id; expected [A-Za-z0-9][A-Za-z0-9._-]*");
   }
-  return value;
 }
 
-function rejectTierAlias(model) {
+/** @param {string} model */
+function requireModel(model) {
+  if (!model || model.trim() !== model) {
+    throw new Error("model id must be a non-empty trimmed string");
+  }
   if (["haiku", "sonnet", "opus"].includes(model)) {
-    throw new Error("tier aliases are not valid model references; use an exact model id");
+    throw new Error("tier aliases are not valid model ids; use an exact model id");
   }
 }
 
 /**
- * @param {string} value
- * @returns {string}
+ * The one thing a parsed reference is guaranteed to CONTAIN nothing of.
+ *
+ * A reference this parser returns is handed to every operator surface that names a model and
+ * quoted verbatim by each of them, without re-validation: `mono-agent validate`, `doctor`, the
+ * TUI, the web console, the daemon log, launchd's captured stdout. All of them are
+ * line-oriented and most are durable, so a control or formatting code point in the value is
+ * enough to restyle the diagnostic quoting it or forge a second line inside it. No legitimate
+ * model id contains one, nothing downstream can repair one after the fact, and escaping it at
+ * six renderers is six chances to miss. So it is refused here, at the source, absolutely.
+ *
+ * There is deliberately NO length rule to go with it. A grammar layer does not get to decide
+ * what a provider may call a model, and three rounds of trying produced three wrong answers:
+ * 96 bytes refused a Hugging Face GGUF repo Ollama serves today, 160 bytes refused an
+ * `ollama:<model>:<tag>` reference whose two halves Ollama itself validates at 80 bytes each,
+ * and no maximum is published in common across Ollama, LM Studio, OpenRouter and custom
+ * `openai_compat` endpoints from which a third guess would be any better. mono-agent's own
+ * `discoverLocalProviderModels` was returning ids this parser then refused.
+ *
+ * The requirements that ceiling was carrying are all met by the layers that render or transmit
+ * a reference, where the answer to "too long" is a shorter STRING rather than a lost route:
+ *  - a diagnostic echo is clamped by truncation, marking the cut -- `sanitizeModelReferenceText`
+ *    on `MODEL_REFERENCE_ECHO_MAX_BYTES`, @mono-agent/runtime-adapter;
+ *  - an adapter error body is clamped by `sendJsonError`;
+ *  - the `/v1/info` payload is bounded by per-contributor measured budgets and a total
+ *    serializer fence that sheds whole fields (`channel-drivers/tui.ts`, `sendBoundedInfo`).
+ * Each of those is asserted at its own layer; none of them is asserted here, because none of
+ * them is this function's job.
+ *
+ * Runs last, after `rejectRemovedRuntimeReference`, so a retired backend still gets its
+ * concrete repair named (`codex:x` -> `openai-codex:x`) instead of a generic shape complaint.
+ * Rejection messages are operator-supplied text too, and are bounded where they are rendered.
+ *
+ * @param {string} reference
  */
-export function canonicalizeLegacyModelReference(value) {
-  if (!value || typeof value !== "string") throw new Error("model reference required");
-
-  if (value.startsWith("openai:")) {
-    const model = requirePart(value.slice("openai:".length), "model id required");
-    return `pi:openai:${model}`;
-  }
-  if (value.startsWith("codex:")) {
-    const model = requirePart(value.slice("codex:".length), "model id required");
-    return `codex:${model}`;
-  }
-  if (value.startsWith("vercel:")) {
-    const rest = value.slice("vercel:".length);
-    const i = rest.indexOf(":");
-    if (i <= 0 || i === rest.length - 1) {
-      throw new Error("invalid vercel model reference; expected vercel:<providerId>:<modelName>");
-    }
-    const provider = requirePart(rest.slice(0, i), "provider id required");
-    const model = requirePart(rest.slice(i + 1), "model name required");
-    return `pi:${provider}:${model}`;
-  }
-  if (value.startsWith("claude-code:")) {
-    const model = requirePart(value.slice("claude-code:".length), "model id required");
-    return `claude:${model}`;
+function requireQuotableReference(reference) {
+  if (UNQUOTABLE_REFERENCE_CHARACTERS.test(reference)) {
+    throw new Error("model reference must not contain control or formatting characters");
   }
-  return value;
 }
 
 /**
+ * Parse the provider/model pair after the optional legacy `pi:` wrapper has
+ * been removed. Pi model ids are opaque and commonly contain further colons,
+ * so only the first colon is structural.
+ *
  * @param {string} value
  * @returns {RuntimeModelRef}
  */
-export function normalizeRuntimeModelReference(value) {
-  return parseRuntimeModelReference(canonicalizeLegacyModelReference(value));
+function parseCanonicalReference(value) {
+  const separator = value.indexOf(":");
+  if (separator <= 0 || separator === value.length - 1) {
+    throw new Error("invalid model reference; expected <provider>:<model>");
+  }
+
+  const provider = value.slice(0, separator);
+  const model = value.slice(separator + 1);
+  const reference = `${provider}:${model}`;
+  requireProvider(provider);
+  requireModel(model);
+  rejectRemovedRuntimeReference(provider, model);
+  requireQuotableReference(reference);
+
+  return { provider, model, reference };
 }
 
 /**
  * @param {string} value
- * @returns {RuntimeModelRef["sdk"]}
+ * @returns {RuntimeModelRef}
  */
-export function sdkFromModelReference(value) {
-  const parsed = parseRuntimeModelReference(value);
-  return parsed.sdk;
+export function normalizeRuntimeModelReference(value) {
+  return parseRuntimeModelReference(value);
 }
 
 /**
@@ -73,121 +142,17 @@ export function sdkFromModelReference(value) {
  * @returns {RuntimeModelRef}
  */
 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 (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+    throw new Error("model reference must be a non-empty trimmed string");
   }
 
   if (value.startsWith("pi:")) {
-    const rest = value.slice("pi:".length);
-    const i = rest.indexOf(":");
-    if (i <= 0 || i === rest.length - 1) {
-      throw new Error("invalid pi model reference; expected pi:<providerId>:<modelName>");
-    }
-    const provider = requirePart(rest.slice(0, i), "provider id required");
-    const model = requirePart(rest.slice(i + 1), "model id required");
-    return { sdk: "pi", provider, model, reference: value };
-  }
-
-  if (value.startsWith("opencode:")) {
-    // opencode:<providerID>:<modelID> — providerID/modelID come from OpenCode's own
-    // provider registry (auth.json). Only the first colon separates them; modelID may
-    // contain slashes (e.g. openrouter's `anthropic/claude-3.5-sonnet`).
-    const rest = value.slice("opencode:".length);
-    const i = rest.indexOf(":");
-    if (i <= 0 || i === rest.length - 1) {
-      throw new Error("invalid opencode model reference; expected opencode:<providerId>:<modelId>");
-    }
-    const provider = requirePart(rest.slice(0, i), "provider id required");
-    const model = requirePart(rest.slice(i + 1), "model id required");
-    return { sdk: "opencode", provider, model, reference: value };
-  }
-
-  const i = value.indexOf(":");
-  if (i <= 0 || i === value.length - 1) {
-    throw new Error("invalid model reference; expected <sdk>:<modelId>");
-  }
-  const sdk = value.slice(0, i);
-  const model = requirePart(value.slice(i + 1), "model id required");
-
-  if (RESERVED_RUNTIME_IDS.has(sdk)) {
-    throw new Error(`reserved runtime id: ${sdk}; use a canonical pi:*, claude:*, or codex:* model reference`);
-  }
-  if (!ACTIVE_RUNTIME_IDS.has(sdk)) {
-    throw new Error(`unknown sdk: ${sdk}`);
-  }
-  rejectTierAlias(model);
-  return { sdk, model, reference: value };
-}
-
-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)
-//   sdk='pi'       → SDK only (the pi-native bridge handles openai-codex and other providers)
-
-// Returns null when the combo is fine; otherwise a short reason string the
-// UI / API can show.
-/**
- * @param {string|RuntimeModelRef} modelRefOrParsed
- * @param {string} executionMode
- * @returns {string|null}
- */
-export function executionModeIncompatibilityReason(modelRefOrParsed, executionMode) {
-  let parsed;
-  try {
-    parsed = typeof modelRefOrParsed === "string"
-      ? parseRuntimeModelReference(modelRefOrParsed)
-      : modelRefOrParsed;
-  } catch {
-    return null;
-  }
-  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.";
+    const wrapped = value.slice("pi:".length);
+    if (wrapped.indexOf(":") <= 0 || wrapped.endsWith(":")) {
+      throw new Error("invalid pi model reference; use pi:<provider>:<model>");
     }
-    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" : "";
-    return `Provider \`${provider}\` only runs under SDK execution mode${suffix}.`;
+    return parseCanonicalReference(wrapped);
   }
-  return `sdk \`${parsed.sdk}\` is not supported under CLI execution mode.`;
-}
 
-/**
- * @param {string|RuntimeModelRef} modelRefOrParsed
- * @param {string} executionMode
- * @returns {boolean}
- */
-export function isModelCompatibleWithExecutionMode(modelRefOrParsed, executionMode) {
-  return executionModeIncompatibilityReason(modelRefOrParsed, executionMode) === null;
+  return parseCanonicalReference(value);
 }

package/src/ai/runtime/registry.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { COMMON_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";
+import { runtimeCapabilities } from "./capabilities.js";
 
 /**
  * `RuntimeModelRef` is referenced inline (not aliased with a top-level
@@ -20,64 +20,19 @@ import { COMMON_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";
  * @property {(options?: Object) => Promise<RuntimeBridge>} load
  */
 
-// CLI bridges are checked first when execution_mode='cli'. Without that flag
-// the resolver falls through to the SDK bridges below, preserving the
-// 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",
-    // The claude CLI resumes prior sessions via `--resume <sessionId>`.
-    capabilities: () => ({
-      kind: "claude-code",
-      runtime: "cli",
-      ...COMMON_CAPABILITIES,
-      supports_session_resume: true,
-      // The one-shot CLI bridge has no bidirectional stdin steering channel.
-      supports_live_input: false,
-    }),
-    load: async () => (await import("../providers/claude-cli.js")).claudeCodeRuntimeBridge,
-  },
-  "codex-app": {
-    id: "codex-app",
-    supports: (ref, options) => ref?.sdk === "codex" && options?.executionMode === "cli",
-    // The codex-app bridge keeps the app-server subprocess + thread alive
-    // across turns when options.sessionKeepAlive is set.
-    capabilities: () => {
-      const { kind: _sdkKind, ...capabilities } = runtimeCapabilities("codex");
-      return { kind: "codex-app", ...capabilities };
-    },
-    load: async () => (await import("../providers/codex-app.js")).codexAppRuntimeBridge,
-  },
-  "opencode-app": {
-    id: "opencode-app",
-    supports: (ref, options) => ref?.sdk === "opencode" && options?.executionMode === "cli",
-    capabilities: () => {
-      const { kind: _sdkKind, ...capabilities } = runtimeCapabilities("opencode");
-      return { kind: "opencode-app", ...capabilities };
-    },
-    load: async () => (await import("../providers/opencode-app.js")).opencodeAppRuntimeBridge,
-  },
-  claude: {
-    id: "claude",
-    supports: (ref) => ref?.sdk === "claude",
-    capabilities: () => runtimeCapabilities("claude"),
-    load: async () => (await import("../providers/claude-sdk.js")).claudeRuntimeBridge,
-  },
   pi: {
     id: "pi",
-    supports: (ref) => ref?.sdk === "pi",
-    capabilities: () => runtimeCapabilities("pi"),
-    // The pi-native AgentHarness bridge is the sole pi runtime path. The
-    // hand-rolled pi-sdk bridge was removed once native reached parity.
-    load: async () => (await import("../providers/pi-native.js")).piNativeRuntimeBridge,
+    supports: () => true,
+    capabilities: () => runtimeCapabilities(),
+    load: async () => {
+      const { piNativeRuntimeBridge } = await import("../providers/pi-native.js");
+      // JavaScript widens the bridge object's `id` property to string. Keep the
+      // literal-safe registry contract here so the Pi provider module remains
+      // untouched by this bridge-removal work package.
+      return /** @type {RuntimeBridge} */ (piNativeRuntimeBridge);
+    },
   },
 };
 
@@ -98,10 +53,21 @@ export function listRuntimeBridges() {
  * @returns {Promise<RuntimeBridge>}
  */
 export async function resolveRuntimeBridge(modelRef, options = {}) {
+  // Direct kernel callers may bypass the parser, so malformed references must
+  // still fail before the sole bridge receives them.
+  if (
+    typeof modelRef?.provider !== "string"
+    || modelRef.provider.length === 0
+    || typeof modelRef.model !== "string"
+    || modelRef.model.length === 0
+    || modelRef.reference !== `${modelRef.provider}:${modelRef.model}`
+  ) {
+    throw new Error("unsupported model reference: expected <provider>:<model>");
+  }
   for (const spec of Object.values(builtinBridgeSpecs)) {
     if (spec.supports(modelRef, options)) return spec.load(options);
   }
-  throw new Error(`unsupported sdk: ${modelRef?.sdk || "unknown"}`);
+  throw new Error(`unsupported model reference: ${modelRef.reference}`);
 }
 
 export { RUNTIME_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";