@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/src/ai/runtime/live-input-events.js

@@ -1,68 +1,102 @@
-// Metadata-only live-input acknowledgement instrumentation.
-//
-// Provider bridges already call message.acknowledge() only after their native
-// steering boundary accepts guidance. Wrapping that callback here creates one
-// adapter-neutral `live_input_applied` event without copying the guidance body
-// into runtime telemetry. A wrapper owns one logical-run dedupe set and is
-// intentionally reused by the fallback router across provider attempts.
+// Metadata-only live-input lifecycle instrumentation and logical-run replay fencing.
+// Stable ids identify one logical delivery across provider retries. The first
+// occurrence owns the body and identity; later same-id occurrences are invalid
+// duplicates unless an exact opaque logical-owner token proves they carry a new
+// callback lease for that first owner. Anonymous input remains legal but is
+// never replayed.
 
 // @ts-check
 
-const LIVE_INPUT_APPLIED_INSTRUMENTED = Symbol("mono-agent.live-input-applied-instrumented");
+const LIVE_INPUT_INSTRUMENTED = Symbol("mono-agent.live-input-instrumented");
+const MAX_DIAGNOSTICS_PER_KIND = 100;
 
 /**
- * @typedef {{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (reason?: unknown) => void}} RuntimeLiveInputMessage
- * @typedef {{type: "live_input_applied", inputId: string, receivedAt?: string}} LiveInputAppliedEvent
+ * @typedef {{providerEntryId?: string, providerRunId?: string}} RuntimeLiveInputEvidence
+ * @typedef {{reason: "delivery_uncertain", providerEntryId?: string, providerRunId?: string}} RuntimeLiveInputUncertainty
+ * @typedef {{body: string, id?: string, receivedAt?: string, logicalOwner?: object, accepted?: (evidence?: RuntimeLiveInputEvidence) => unknown, acknowledge?: (evidence?: RuntimeLiveInputEvidence) => unknown, uncertain?: (details: RuntimeLiveInputUncertainty) => unknown, reject?: (reason?: unknown) => unknown}} RuntimeLiveInputMessage
+ * @typedef {{message: RuntimeLiveInputMessage, callbackMessage: RuntimeLiveInputMessage, logicalOwner?: object, inputId: string, receivedAt?: string, phase: "available"|"leased"|"native_accepted"|"consumed"|"uncertain", attempt: number, generation: number}} LiveInputOwner
+ * @typedef {{type: string, [key: string]: unknown}} LiveInputEvent
  */
 
 /**
  * @param {AsyncIterable<RuntimeLiveInputMessage>|undefined} liveInput
- * @param {(event: LiveInputAppliedEvent) => void} onApplied
+ * @param {(event: LiveInputEvent) => void} onEvent
  * @returns {AsyncIterable<RuntimeLiveInputMessage>|undefined}
  */
-export function instrumentLiveInputAppliedEvents(liveInput, onApplied) {
+export function instrumentLiveInputAppliedEvents(liveInput, onEvent) {
   if (liveInput === undefined || isInstrumented(liveInput)) return liveInput;
 
-  const appliedInputIds = new Set();
+  /** @type {Map<string, LiveInputOwner>} */
+  const owners = new Map();
+  const diagnosticCounts = new Map();
+  let generation = 0;
+
   const instrumented = {
-    [LIVE_INPUT_APPLIED_INSTRUMENTED]: true,
+    [LIVE_INPUT_INSTRUMENTED]: true,
     [Symbol.asyncIterator]() {
+      generation += 1;
+      const iteratorGeneration = generation;
       const iterator = liveInput[Symbol.asyncIterator]();
+      const yieldedIds = new Set();
       let ordinal = 0;
+
       return {
         async next() {
-          const next = await iterator.next();
-          if (next.done === true) return next;
-          ordinal += 1;
-          const message = next.value;
-          const inputId = stableInputId(message?.id, ordinal);
-          const receivedAt = typeof message?.receivedAt === "string" && message.receivedAt.length > 0
-            ? message.receivedAt
-            : undefined;
-          const acknowledge = typeof message?.acknowledge === "function"
-            ? message.acknowledge.bind(message)
-            : undefined;
-          return {
-            done: false,
-            value: {
-              ...message,
-              acknowledge: () => {
-                acknowledge?.();
-                if (appliedInputIds.has(inputId)) return;
-                appliedInputIds.add(inputId);
-                try {
-                  onApplied({
-                    type: "live_input_applied",
-                    inputId,
-                    ...(receivedAt === undefined ? {} : { receivedAt }),
-                  });
-                } catch {
-                  // Telemetry must never turn accepted guidance into a provider
-                  // failure after the native steering call already succeeded.
-                }
-              },
-            },
-          };
+          while (true) {
+            const next = await iterator.next();
+            if (next.done === true) return next;
+            ordinal += 1;
+            const message = next.value;
+            const stableId = normalizedStableId(message?.id);
+
+            if (stableId === undefined) {
+              if (iteratorGeneration > 1) {
+                emitBounded("anonymous_identity", {
+                  type: "live_input_replay_suppressed",
+                  reason: "anonymous_identity",
+                  generation: iteratorGeneration,
+                  ordinal,
+                });
+                continue;
+              }
+              const owner = createOwner(message, `anonymous:${iteratorGeneration}:${ordinal}`, iteratorGeneration);
+              return { done: false, value: lease(owner) };
+            }
+
+            const existing = owners.get(stableId);
+            if (existing === undefined) {
+              const owner = createOwner(message, stableId, iteratorGeneration);
+              owners.set(stableId, owner);
+              yieldedIds.add(stableId);
+              return { done: false, value: lease(owner) };
+            }
+
+            emitBounded("duplicate_id", {
+              type: "live_input_duplicate_suppressed",
+              inputId: stableId,
+              generation: iteratorGeneration,
+            });
+            if (
+              iteratorGeneration > existing.generation
+              && existing.phase === "available"
+              && !yieldedIds.has(stableId)
+            ) {
+              // Suppress the later occurrence itself. It merely reveals that the
+              // first owner is present in this replay generation; replay the
+              // first owner's immutable body and identity.
+              yieldedIds.add(stableId);
+              existing.generation = iteratorGeneration;
+              if (
+                existing.logicalOwner !== undefined
+                && existing.logicalOwner === validLogicalOwner(message?.logicalOwner)
+              ) {
+                // The logical owner remains the first occurrence. This is only
+                // its fresh, independently fenced host callback lease.
+                existing.callbackMessage = message;
+              }
+              return { done: false, value: lease(existing) };
+            }
+          }
         },
         async return(value) {
           return typeof iterator.return === "function"
@@ -76,19 +110,181 @@ export function instrumentLiveInputAppliedEvents(liveInput, onApplied) {
       };
     },
   };
+
   return /** @type {AsyncIterable<RuntimeLiveInputMessage>} */ (instrumented);
+
+  /** @param {RuntimeLiveInputMessage} message @param {string} inputId @param {number} ownerGeneration */
+  function createOwner(message, inputId, ownerGeneration) {
+    const receivedAt = validString(message?.receivedAt);
+    const logicalOwner = validLogicalOwner(message?.logicalOwner);
+    return {
+      message,
+      callbackMessage: message,
+      ...(logicalOwner === undefined ? {} : { logicalOwner }),
+      inputId,
+      ...(receivedAt === undefined ? {} : { receivedAt }),
+      phase: /** @type {const} */ ("available"),
+      attempt: 0,
+      generation: ownerGeneration,
+    };
+  }
+
+  /** @param {LiveInputOwner} owner */
+  function lease(owner) {
+    owner.phase = "leased";
+    owner.attempt += 1;
+    const attempt = owner.attempt;
+    const host = owner.callbackMessage;
+    const base = eventBase(owner);
+
+    /** @type {RuntimeLiveInputMessage} */
+    const wrapped = {
+      ...owner.message,
+      accepted(evidence) {
+        if (!isCurrent(owner, attempt, "leased")) return "ignored";
+        owner.phase = "native_accepted";
+        const disposition = callHost(host.accepted, host, evidence);
+        emit({
+          type: "live_input_native_accepted",
+          ...base,
+          ...safeEvidence(evidence),
+          settlementDisposition: disposition,
+        });
+        return publicDisposition(disposition);
+      },
+      acknowledge(evidence) {
+        if (!isCurrent(owner, attempt, "leased", "native_accepted")) {
+          emit({ type: "live_input_consumed", ...base, ...safeEvidence(evidence), late: true });
+          return "ignored";
+        }
+        owner.phase = "consumed";
+        emit({ type: "live_input_consumed", ...base, ...safeEvidence(evidence) });
+        const disposition = callHost(host.acknowledge, host, evidence);
+        if (disposition === "recorded") {
+          emit({ type: "live_input_applied", ...base, ...safeEvidence(evidence) });
+        } else {
+          emit({
+            type: "live_input_settlement_unconfirmed",
+            ...base,
+            phase: "consumed",
+            settlementDisposition: disposition,
+          });
+        }
+        return publicDisposition(disposition);
+      },
+      uncertain(details) {
+        if (!isCurrent(owner, attempt, "leased", "native_accepted")) return "ignored";
+        owner.phase = "uncertain";
+        const normalized = {
+          reason: /** @type {const} */ ("delivery_uncertain"),
+          ...safeEvidence(details),
+        };
+        const disposition = callHost(host.uncertain, host, normalized);
+        emit({
+          type: "live_input_uncertain",
+          ...base,
+          ...normalized,
+          settlementDisposition: disposition,
+        });
+        return publicDisposition(disposition);
+      },
+      reject(reason) {
+        if (!isCurrent(owner, attempt, "leased", "native_accepted")) return "ignored";
+        if (owner.phase === "native_accepted" && !isNativeQueueRemoved(reason)) {
+          return wrapped.uncertain?.({ reason: "delivery_uncertain" });
+        }
+        const disposition = callHost(host.reject, host, reason);
+        // "ignored" is affirmative host evidence that this attempt no longer
+        // owns settlement (normally because the mailbox already sealed it).
+        // Legacy void and thrown callbacks remain replay-compatible because
+        // native removal still proves the provider did not consume the input.
+        owner.phase = disposition === "ignored" ? "uncertain" : "available";
+        return publicDisposition(disposition);
+      },
+    };
+    return wrapped;
+  }
+
+  /** @param {string} kind @param {LiveInputEvent} event */
+  function emitBounded(kind, event) {
+    const count = diagnosticCounts.get(kind) ?? 0;
+    if (count >= MAX_DIAGNOSTICS_PER_KIND) return;
+    diagnosticCounts.set(kind, count + 1);
+    emit(event);
+  }
+
+  /** @param {LiveInputEvent} event */
+  function emit(event) {
+    try { onEvent(event); } catch { /* telemetry never changes delivery */ }
+  }
+}
+
+/** @param {unknown} callback @param {RuntimeLiveInputMessage} receiver @param {unknown} argument */
+function callHost(callback, receiver, argument) {
+  if (typeof callback !== "function") return "unconfirmed";
+  try {
+    const result = callback.call(receiver, argument);
+    return result === "recorded" || result === "ignored" ? result : "unconfirmed";
+  } catch {
+    return "threw";
+  }
+}
+
+/** @param {string} disposition */
+function publicDisposition(disposition) {
+  return disposition === "recorded" || disposition === "ignored" ? disposition : undefined;
+}
+
+/** @param {LiveInputOwner} owner */
+function eventBase(owner) {
+  return {
+    inputId: owner.inputId,
+    ...(owner.receivedAt === undefined ? {} : { receivedAt: owner.receivedAt }),
+  };
+}
+
+/** @param {LiveInputOwner} owner @param {number} attempt @param  {...string} phases */
+function isCurrent(owner, attempt, ...phases) {
+  return owner.attempt === attempt && phases.includes(owner.phase);
 }
 
 /** @param {unknown} value */
-function isInstrumented(value) {
-  return typeof value === "object"
-    && value !== null
-    && value[LIVE_INPUT_APPLIED_INSTRUMENTED] === true;
+function normalizedStableId(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
 }
 
-/** @param {unknown} value @param {number} ordinal */
-function stableInputId(value, ordinal) {
-  return typeof value === "string" && value.trim().length > 0
+/** @param {unknown} value */
+function validLogicalOwner(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function")
     ? value
-    : `anonymous:${ordinal}`;
+    : undefined;
+}
+
+/** @param {unknown} value */
+function validString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** @param {unknown} value */
+function safeEvidence(value) {
+  if (typeof value !== "object" || value === null) return {};
+  const evidence = /** @type {{providerEntryId?: unknown, providerRunId?: unknown}} */ (value);
+  return {
+    ...(validString(evidence.providerEntryId) === undefined ? {} : { providerEntryId: evidence.providerEntryId }),
+    ...(validString(evidence.providerRunId) === undefined ? {} : { providerRunId: evidence.providerRunId }),
+  };
+}
+
+/** @param {unknown} reason */
+function isNativeQueueRemoved(reason) {
+  return typeof reason === "object"
+    && reason !== null
+    && /** @type {{code?: unknown}} */ (reason).code === "native_queue_removed";
+}
+
+/** @param {unknown} value */
+function isInstrumented(value) {
+  return typeof value === "object"
+    && value !== null
+    && value[LIVE_INPUT_INSTRUMENTED] === true;
 }

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);
 }