@mono-agent/agent-runtime 0.1.0

package/src/ai/registry.js

@@ -0,0 +1,5 @@
+export {
+  listRuntimeBridges as listProviders,
+  resolveRuntimeBridge as findProviderForModel,
+  runtimeCapabilities,
+} from "./runtime/registry.js";

package/src/ai/runtime/capabilities-used.js

@@ -0,0 +1,56 @@
+// Per-request capability telemetry. Each provider populates what it can
+// attest to for *this* call; unknown values are `null` (not `false`) so
+// hosts can tell "feature off" from "we don't know". This is the per-call
+// counterpart to the static `runtimeCapabilities()` (which describes the
+// backend in general).
+//
+// Fields:
+//   prompt_cache_active        — true/false/null (null = unknown for this provider)
+//   thinking_enabled           — true/false/null
+//   structured_output_enforced — true/false (request-time signal; never null)
+//   subagent_invoked           — true/false/null
+//   mcp_servers_used           — string[] of MCP server names that ran
+//   native_subagents_used      — string[] of native subagent names that ran
+//   tool_compaction_applied    — true/false (derived from runtimeWarnings)
+//   context_compaction_applied — true/false/null
+
+export const UNKNOWN_CAPABILITY = null;
+
+export function buildCapabilitiesUsed({
+  promptCacheActive = UNKNOWN_CAPABILITY,
+  thinkingEnabled = UNKNOWN_CAPABILITY,
+  structuredOutputEnforced = false,
+  subagentInvoked = UNKNOWN_CAPABILITY,
+  mcpServersUsed = [],
+  nativeSubagentsUsed = [],
+  toolCompactionApplied = false,
+  contextCompactionApplied = UNKNOWN_CAPABILITY,
+} = {}) {
+  return {
+    prompt_cache_active: tristate(promptCacheActive),
+    thinking_enabled: tristate(thinkingEnabled),
+    structured_output_enforced: !!structuredOutputEnforced,
+    subagent_invoked: tristate(subagentInvoked),
+    mcp_servers_used: stringList(mcpServersUsed),
+    native_subagents_used: stringList(nativeSubagentsUsed),
+    tool_compaction_applied: !!toolCompactionApplied,
+    context_compaction_applied: tristate(contextCompactionApplied),
+  };
+}
+
+function tristate(value) {
+  if (value === true || value === false) return value;
+  return UNKNOWN_CAPABILITY;
+}
+
+function stringList(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((entry) => typeof entry === "string" && entry.trim())
+    .map((entry) => entry.trim());
+}
+
+export function toolCompactionAppliedFromWarnings(runtimeWarnings = []) {
+  if (!Array.isArray(runtimeWarnings)) return false;
+  return runtimeWarnings.some((warning) => warning?.warning_kind === "tool_payload_truncated");
+}

package/src/ai/runtime/capabilities.js

@@ -0,0 +1,44 @@
+export const COMMON_CAPABILITIES = {
+  streaming: true,
+  structured_output: true,
+  supports_session_resume: false,
+  native_runtime_config: null,
+  supports_mcp: true,
+  supports_skills: true,
+  supports_builtin_tools: true,
+  supports_live_input: true,
+  supports_native_subagents: true,
+};
+
+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,
+    // The pi bridge keeps a pi-agent-core Session transcript per provider
+    // session id and seeds Agent initialState.messages on resume.
+    supports_session_resume: 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,
+  },
+};
+
+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 };
+}

package/src/ai/runtime/context-windows.js

@@ -0,0 +1,38 @@
+export const DEFAULT_CONTEXT_WINDOW = "default";
+export const ONE_MILLION_CONTEXT_WINDOW = "1m";
+
+export const CLAUDE_ONE_MILLION_CONTEXT_MODELS = new Set([
+  "claude-opus-4-7",
+  "claude-opus-4-6",
+]);
+
+export function normalizeContextWindow(value) {
+  return value === ONE_MILLION_CONTEXT_WINDOW
+    ? ONE_MILLION_CONTEXT_WINDOW
+    : DEFAULT_CONTEXT_WINDOW;
+}
+
+export function stripContextWindowSuffix(model) {
+  return String(model || "").replace(/\[1m\]$/i, "");
+}
+
+export function claudeModelSupportsOneMillionContext(model) {
+  return CLAUDE_ONE_MILLION_CONTEXT_MODELS.has(stripContextWindowSuffix(model));
+}
+
+export function claudeModelSupportsContextWindow(model, contextWindow) {
+  const normalized = normalizeContextWindow(contextWindow);
+  if (normalized === DEFAULT_CONTEXT_WINDOW) return true;
+  return claudeModelSupportsOneMillionContext(model);
+}
+
+export function modelWithContextWindow(model, contextWindow) {
+  const base = stripContextWindowSuffix(model);
+  if (
+    normalizeContextWindow(contextWindow) === ONE_MILLION_CONTEXT_WINDOW
+    && claudeModelSupportsOneMillionContext(base)
+  ) {
+    return `${base}[1m]`;
+  }
+  return base;
+}

package/src/ai/runtime/fast-mode.js

@@ -0,0 +1,8 @@
+export function codexModelSupportsFastMode(model) {
+  return String(model || "").trim().toLowerCase().startsWith("gpt-");
+}
+
+export function normalizeFastMode(value, fallback = true) {
+  if (value === undefined || value === null || value === "") return !!fallback;
+  return value === true || value === 1;
+}

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

@@ -0,0 +1,144 @@
+const RESERVED_RUNTIME_IDS = new Set(["openai", "vercel", "claude-code", "codex-cli"]);
+const ACTIVE_RUNTIME_IDS = new Set(["claude", "pi", "codex", "opencode"]);
+
+function requirePart(value, message) {
+  if (!value || typeof value !== "string" || value.trim() !== value) {
+    throw new Error(message);
+  }
+  return value;
+}
+
+function rejectTierAlias(model) {
+  if (["haiku", "sonnet", "opus"].includes(model)) {
+    throw new Error("tier aliases are not valid model references; use an exact model id");
+  }
+}
+
+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}`;
+  }
+  return value;
+}
+
+export function normalizeRuntimeModelReference(value) {
+  return parseRuntimeModelReference(canonicalizeLegacyModelReference(value));
+}
+
+export function sdkFromModelReference(value) {
+  const parsed = parseRuntimeModelReference(value);
+  return parsed.sdk;
+}
+
+export function parseRuntimeModelReference(value) {
+  if (!value || typeof value !== "string") throw new Error("model reference required");
+
+  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='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 (pi-sdk handles openai-codex and other providers)
+
+// Returns null when the combo is fine; otherwise a short reason string the
+// UI / API can show.
+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 === "sdk") {
+    if (parsed.sdk === "codex") {
+      return "Codex CLI requires CLI execution mode.";
+    }
+    if (parsed.sdk === "opencode") {
+      return "OpenCode CLI requires CLI 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 === "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 `sdk \`${parsed.sdk}\` is not supported under CLI execution mode.`;
+}
+
+export function isModelCompatibleWithExecutionMode(modelRefOrParsed, executionMode) {
+  return executionModeIncompatibilityReason(modelRefOrParsed, executionMode) === null;
+}

package/src/ai/runtime/registry.js

@@ -0,0 +1,57 @@
+import { COMMON_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";
+
+// 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.
+const builtinBridgeSpecs = {
+  "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 }),
+    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: () => ({ kind: "codex-app", runtime: "cli", ...COMMON_CAPABILITIES, supports_session_resume: true }),
+    load: async () => (await import("../providers/codex-app.js")).codexAppRuntimeBridge,
+  },
+  "opencode-app": {
+    id: "opencode-app",
+    supports: (ref, options) => ref?.sdk === "opencode" && options?.executionMode === "cli",
+    capabilities: () => ({ kind: "opencode-app", runtime: "cli", ...COMMON_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"),
+    load: async () => (await import("../providers/pi-sdk.js")).piRuntimeBridge,
+  },
+};
+
+export function listRuntimeBridges() {
+  return Object.values(builtinBridgeSpecs).map((bridge) => ({
+    id: bridge.id,
+    supports: bridge.supports,
+    capabilities: bridge.capabilities,
+  }));
+}
+
+export async function resolveRuntimeBridge(modelRef, options = {}) {
+  for (const spec of Object.values(builtinBridgeSpecs)) {
+    if (spec.supports(modelRef, options)) return spec.load();
+  }
+  throw new Error(`unsupported sdk: ${modelRef?.sdk || "unknown"}`);
+}
+
+export { RUNTIME_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";

package/src/ai/runtime/router.js

@@ -0,0 +1,214 @@
+// Provider fallback router.
+//
+// Wraps `createRuntime` with an ordered chain of model references. If a run
+// fails with a retryable provider error (per `retryableProviderFailureInfo`),
+// the router retries the same logical run with the next chain entry,
+// prepending the transcript-tail snapshot of the previous attempt to the
+// system prompt so the next provider can continue rather than restart.
+//
+// Inspired by zeroclaw's RouterProvider hint-resolution pattern, but goes
+// further: zeroclaw's router resolves a hint to one provider and never
+// falls back automatically. This router does, using the failure-kind
+// taxonomy and capability matrix we already maintain.
+//
+// API:
+//   createRouterRuntime({ host, chain })
+//     returns { run(systemPrompt, options) } plus configureTools /
+//     disposeSession / disposeAllSessions delegated to the inner runtime,
+//     so the router is a drop-in replacement for createRuntime(host).
+//
+//   chain entries:
+//     { model: ModelRef, executionMode?: "sdk" | "cli", requires?: Capabilities }
+//   shorthand: a bare ModelRef is also accepted (no requirements).
+//
+// Result:
+//   The success run's result, with `failoverHistory` appended describing every
+//   prior attempt: [{ model, failureKind, requestId, retryableSubkind }].
+//   If every entry in the chain fails, returns the last result with
+//   `failureKind: "provider_unavailable_exhausted"`.
+
+import { createRuntime } from "../../runtime.js";
+import { retryableProviderFailureInfo } from "../failure.js";
+import { runtimeCapabilities } from "./capabilities.js";
+import { buildTranscriptTailSnapshot, renderResumeSnapshot } from "../../agent/transcript.js";
+
+export function createRouterRuntime({ host = {}, chain = [] } = {}) {
+  const entries = normaliseChain(chain);
+  if (entries.length === 0) {
+    throw new Error("createRouterRuntime requires a non-empty chain");
+  }
+  const inner = createRuntime(host);
+
+  return {
+    async run(systemPrompt, options = {}) {
+      const failoverHistory = [];
+      let lastResult = null;
+      let resumeSnapshot = null;
+
+      for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (!entrySatisfiesRequirements(entry, options)) {
+          failoverHistory.push({
+            model: entry.model,
+            failureKind: "skipped_capability_mismatch",
+            requirements: entry.requires,
+          });
+          continue;
+        }
+
+        const callOptions = {
+          ...options,
+          model: entry.model,
+          executionMode: entry.executionMode || options.executionMode,
+        };
+        if (resumeSnapshot) {
+          callOptions.diagnosticsSeed = {
+            ...(callOptions.diagnosticsSeed || {}),
+            resume_snapshot: resumeSnapshot,
+          };
+          // Also prepend the rendered snapshot to the system prompt so SDK
+          // backends that don't read diagnosticsSeed still continue from the
+          // previous attempt.
+          const rendered = renderResumeSnapshot(resumeSnapshot);
+          if (rendered) {
+            callOptions.systemPromptPrefix = rendered;
+            systemPrompt = `${rendered}\n\n${systemPrompt}`;
+          }
+        }
+
+        if (failoverHistory.length > 0) {
+          emit(callOptions, {
+            type: "provider_failover_started",
+            from: failoverHistory[failoverHistory.length - 1]?.model,
+            to: entry.model,
+            attemptIndex: i,
+          });
+        }
+
+        let result;
+        try {
+          result = await inner.run(systemPrompt, callOptions);
+        } catch (err) {
+          // The inner runtime usually surfaces errors as structured result
+          // fields, but a bridge can still throw synchronously (e.g. spawn
+          // failures). Convert to a result-like shape so the chain logic
+          // is uniform.
+          result = {
+            text: null,
+            error: err?.message || String(err),
+            failureKind: "provider_unavailable",
+            events: [],
+            cancelled: false,
+            usage: {},
+          };
+        }
+
+        const retryability = retryableProviderFailureInfo({
+          errorText: result.error || "",
+          stderrTail: result.stderrTail || "",
+          failureKind: result.failureKind,
+        });
+
+        const successful = !result.error && !result.failureKind && !result.cancelled;
+        if (successful) {
+          if (failoverHistory.length > 0) {
+            emit(callOptions, {
+              type: "provider_failover_completed",
+              attemptIndex: i,
+              model: entry.model,
+            });
+          }
+          return { ...result, failoverHistory };
+        }
+
+        failoverHistory.push({
+          model: entry.model,
+          failureKind: result.failureKind || null,
+          requestId: retryability.requestId,
+          retryableSubkind: retryability.subkind,
+        });
+        lastResult = result;
+
+        // Bail early on non-retryable failures (auth, billing, cancellation,
+        // invalid_result). Only retryable provider errors trigger fallback.
+        const shouldFallback = retryability.retryable && !result.cancelled;
+        if (!shouldFallback) break;
+
+        // Build a transcript-tail snapshot from this run's events so the
+        // next provider can continue. If the run produced no usable events,
+        // skip the snapshot (the next attempt starts fresh).
+        const snapshot = buildTranscriptTailSnapshot(result.events);
+        if (snapshot) resumeSnapshot = snapshot;
+      }
+
+      const exhaustedResult = lastResult || {
+        text: null,
+        events: [],
+        error: "router chain exhausted with no executions",
+        failureKind: "provider_unavailable_exhausted",
+        cancelled: false,
+        usage: {},
+      };
+      return {
+        ...exhaustedResult,
+        failureKind: "provider_unavailable_exhausted",
+        failoverHistory,
+      };
+    },
+    chain: () => entries.slice(),
+    configureTools(next) {
+      inner.configureTools?.(next);
+    },
+    async disposeSession(providerSessionId) {
+      return inner.disposeSession?.(providerSessionId);
+    },
+    async disposeAllSessions() {
+      await inner.disposeAllSessions?.();
+    },
+  };
+}
+
+function normaliseChain(chain) {
+  if (!Array.isArray(chain)) return [];
+  return chain
+    .map((entry) => {
+      if (!entry) return null;
+      if (entry.sdk && entry.model) {
+        // ModelRef shorthand: { sdk, model, ... }
+        return { model: entry, executionMode: null, requires: null };
+      }
+      if (entry.model) {
+        return {
+          model: entry.model,
+          executionMode: typeof entry.executionMode === "string" ? entry.executionMode : null,
+          requires: entry.requires && typeof entry.requires === "object" ? entry.requires : null,
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+}
+
+function entrySatisfiesRequirements(entry, options) {
+  const requires = entry.requires;
+  if (!requires) return true;
+  let caps;
+  try {
+    caps = runtimeCapabilities(entry.model);
+  } catch {
+    return false;
+  }
+  for (const [key, expected] of Object.entries(requires)) {
+    if (caps[key] !== expected) return false;
+  }
+  // Honour request-time outputSchema → require structured_output unless
+  // already specified.
+  if (options.outputSchema && requires.structured_output !== false && caps.structured_output === false) {
+    return false;
+  }
+  return true;
+}
+
+function emit(callOptions, event) {
+  try { callOptions.onEvent?.(event); } catch { /* swallow */ }
+}