@mono-agent/agent-runtime 0.4.0 → 0.4.1

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

@@ -1,3 +1,7 @@
+// @ts-check
+
+/** @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"]);
 
@@ -14,6 +18,10 @@ function rejectTierAlias(model) {
   }
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 export function canonicalizeLegacyModelReference(value) {
   if (!value || typeof value !== "string") throw new Error("model reference required");
 
@@ -42,15 +50,27 @@ export function canonicalizeLegacyModelReference(value) {
   return value;
 }
 
+/**
+ * @param {string} value
+ * @returns {RuntimeModelRef}
+ */
 export function normalizeRuntimeModelReference(value) {
   return parseRuntimeModelReference(canonicalizeLegacyModelReference(value));
 }
 
+/**
+ * @param {string} value
+ * @returns {RuntimeModelRef["sdk"]}
+ */
 export function sdkFromModelReference(value) {
   const parsed = parseRuntimeModelReference(value);
   return parsed.sdk;
 }
 
+/**
+ * @param {string} value
+ * @returns {RuntimeModelRef}
+ */
 export function parseRuntimeModelReference(value) {
   if (!value || typeof value !== "string") throw new Error("model reference required");
 
@@ -107,6 +127,11 @@ export const RESERVED_RUNTIME_KINDS = [...RESERVED_RUNTIME_IDS];
 
 // 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 {
@@ -139,6 +164,11 @@ export function executionModeIncompatibilityReason(modelRefOrParsed, executionMo
   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;
 }

package/src/ai/runtime/registry.js

@@ -1,8 +1,29 @@
+// @ts-check
+
 import { COMMON_CAPABILITIES, runtimeCapabilities } from "./capabilities.js";
 
+/**
+ * `RuntimeModelRef` is referenced inline (not aliased with a top-level
+ * `@typedef`) so this barrel does not re-export a second `RuntimeModelRef`
+ * type alongside model-refs.js's — that duplicate `export *` re-export is a
+ * TS2308 ambiguity. The canonical export stays in model-refs.js/types.js.
+ * @typedef {import('../types.js').RuntimeBridge} RuntimeBridge
+ * @typedef {import('../types.js').RuntimeBridgeDescriptor} RuntimeBridgeDescriptor
+ * @typedef {import('../types.js').RuntimeBridgeId} RuntimeBridgeId
+ */
+
+/**
+ * @typedef {Object} BridgeSpec
+ * @property {RuntimeBridgeId} id
+ * @property {(ref: (import('../types.js').RuntimeModelRef|undefined), options?: Object) => boolean} supports
+ * @property {(ref?: import('../types.js').RuntimeModelRef) => Object} capabilities
+ * @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 = {
   "claude-code": {
     id: "claude-code",
@@ -41,6 +62,9 @@ const builtinBridgeSpecs = {
   },
 };
 
+/**
+ * @returns {Array<RuntimeBridgeDescriptor>}
+ */
 export function listRuntimeBridges() {
   return Object.values(builtinBridgeSpecs).map((bridge) => ({
     id: bridge.id,
@@ -49,6 +73,11 @@ export function listRuntimeBridges() {
   }));
 }
 
+/**
+ * @param {import('../types.js').RuntimeModelRef} modelRef
+ * @param {Object} [options]
+ * @returns {Promise<RuntimeBridge>}
+ */
 export async function resolveRuntimeBridge(modelRef, options = {}) {
   for (const spec of Object.values(builtinBridgeSpecs)) {
     if (spec.supports(modelRef, options)) return spec.load(options);

package/src/ai/runtime/router.js

@@ -24,25 +24,74 @@
 // 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"`.
+//   If every eligible retryable/auth entry in the chain fails, returns the last
+//   result with `failureKind: "provider_unavailable_exhausted"`. Terminal
+//   non-retryable failures are returned as-is with their failover history.
+
+// @ts-check
 
 import { createRuntime } from "../../runtime.js";
-import { retryableProviderFailureInfo } from "../failure.js";
+import { isProviderAuthFailureText, retryableProviderFailureInfo } from "../failure.js";
 import { runtimeCapabilities } from "./capabilities.js";
 import { buildTranscriptTailSnapshot, renderResumeSnapshot } from "../../agent/transcript.js";
+import { resolveRuntimeBrand } from "../../runtime-brand.js";
+
+/**
+ * @typedef {import('../types.js').RuntimeModelRef} RuntimeModelRef
+ * @typedef {import('../types.js').AgentRuntimeHostOptions} AgentRuntimeHostOptions
+ * @typedef {import('../types.js').AgentRuntimeInstance} AgentRuntimeInstance
+ * @typedef {import('../types.js').RuntimeRunOptions} RuntimeRunOptions
+ * @typedef {import('../types.js').RuntimeResult} RuntimeResult
+ */
+
+/**
+ * @typedef {Object} RouterChainEntryInput
+ * A chain entry as accepted by createRouterRuntime: either the shorthand bare
+ * RuntimeModelRef, or the full `{model, executionMode?, requires?}` form.
+ * @property {RuntimeModelRef} model
+ * @property {string} [executionMode]
+ * @property {Object<string, *>} [requires]
+ */
 
+/**
+ * @typedef {Object} RouterChainEntry
+ * @property {RuntimeModelRef} model
+ * @property {string|null} executionMode
+ * @property {Object<string, *>|null} requires
+ */
+
+/**
+ * @param {Object} [options]
+ * @param {AgentRuntimeHostOptions} [options.host]
+ * @param {ReadonlyArray<RuntimeModelRef|RouterChainEntryInput>} [options.chain]
+ * @returns {AgentRuntimeInstance & {chain: () => Array<RouterChainEntry>}}
+ */
 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);
+  // The router builds transcript-tail snapshots outside the inner runtime's
+  // bridge call (which is where the per-instance toolContext lives), so resolve
+  // the host brand here to stamp the snapshot schema id with the same brand the
+  // inner runtime uses — createRuntime no longer publishes it to a process global.
+  const runtimeBrand = resolveRuntimeBrand(host.runtimeBrand);
 
   return {
+    /**
+     * @param {string} systemPrompt
+     * @param {Partial<RuntimeRunOptions>} [options] Optional so a bare `{}` call
+     *   is legal; the router always overrides `model`/`executionMode` per chain
+     *   entry (see AgentRuntimeInstance.run for the public, model-required contract).
+     * @returns {Promise<RuntimeResult>}
+     */
     async run(systemPrompt, options = {}) {
+      /** @type {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null|undefined), retryableSubkind?: (string|null|undefined), requirements?: (Object<string,*>|null)}>} */
       const failoverHistory = [];
+      /** @type {RuntimeResult|null} */
       let lastResult = null;
+      /** @type {*} */
       let resumeSnapshot = null;
 
       for (let i = 0; i < entries.length; i += 1) {
@@ -103,6 +152,8 @@ export function createRouterRuntime({ host = {}, chain = [] } = {}) {
           };
         }
 
+        result = normalizeProviderAuthFailure(result);
+
         const retryability = retryableProviderFailureInfo({
           errorText: result.error || "",
           stderrTail: result.stderrTail || "",
@@ -129,15 +180,19 @@ export function createRouterRuntime({ host = {}, chain = [] } = {}) {
         });
         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;
+        // Provider auth is terminal for one provider, but chain-retryable: a
+        // fallback provider may have working credentials. Other non-retryable
+        // provider/request errors remain terminal.
+        const shouldFallback = (retryability.retryable || result.failureKind === "provider_auth")
+          && !result.cancelled;
+        if (!shouldFallback) {
+          return { ...result, failoverHistory };
+        }
 
         // 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);
+        const snapshot = buildTranscriptTailSnapshot(result.events, { runtimeBrand });
         if (snapshot) resumeSnapshot = snapshot;
       }
 
@@ -145,13 +200,13 @@ export function createRouterRuntime({ host = {}, chain = [] } = {}) {
         text: null,
         events: [],
         error: "router chain exhausted with no executions",
-        failureKind: "provider_unavailable_exhausted",
+        failureKind: "skipped_capability_mismatch",
         cancelled: false,
         usage: {},
       };
       return {
         ...exhaustedResult,
-        failureKind: "provider_unavailable_exhausted",
+        failureKind: lastResult ? "provider_unavailable_exhausted" : exhaustedResult.failureKind,
         failoverHistory,
       };
     },
@@ -168,9 +223,15 @@ export function createRouterRuntime({ host = {}, chain = [] } = {}) {
   };
 }
 
+/**
+ * @param {ReadonlyArray<*>} chain ReadonlyArray<RuntimeModelRef|RouterChainEntryInput>, loosened
+ *   here because distinguishing the two shapes is a runtime duck-type check
+ *   (`entry.sdk && entry.model`), not something a union type narrows cleanly.
+ * @returns {Array<RouterChainEntry>}
+ */
 function normaliseChain(chain) {
   if (!Array.isArray(chain)) return [];
-  return chain
+  return /** @type {Array<RouterChainEntry>} */ (chain
     .map((entry) => {
       if (!entry) return null;
       if (entry.sdk && entry.model) {
@@ -186,9 +247,14 @@ function normaliseChain(chain) {
       }
       return null;
     })
-    .filter(Boolean);
+    .filter(Boolean));
 }
 
+/**
+ * @param {RouterChainEntry} entry
+ * @param {Partial<RuntimeRunOptions>} options
+ * @returns {boolean}
+ */
 function entrySatisfiesRequirements(entry, options) {
   const requires = entry.requires;
   // Synthesize effective requirements: merge the entry's own `requires` with
@@ -225,6 +291,24 @@ function entrySatisfiesRequirements(entry, options) {
   return true;
 }
 
+/**
+ * @param {Partial<RuntimeRunOptions>} callOptions
+ * @param {import('../types.js').RuntimeEvent} event
+ * @returns {void}
+ */
 function emit(callOptions, event) {
   try { callOptions.onEvent?.(event); } catch { /* swallow */ }
 }
+
+/**
+ * @param {RuntimeResult} result
+ * @returns {RuntimeResult}
+ */
+function normalizeProviderAuthFailure(result) {
+  if (result.cancelled) return result;
+  const failureKind = result.failureKind || null;
+  if (failureKind && failureKind !== "provider_unavailable") return result;
+  const haystack = `${result.error || ""}\n${result.stderrTail || ""}`;
+  if (!isProviderAuthFailureText(haystack)) return result;
+  return { ...result, failureKind: "provider_auth" };
+}

package/src/ai/runtime/session-liveness.js

@@ -0,0 +1,110 @@
+// @ts-check
+// Synchronous session-liveness primitives over a createSessionRegistry.
+//
+// A provider bridge owns session DURABILITY (pi keeps a Session transcript,
+// codex keeps an app-server thread); this kernel layer owns session LIVENESS —
+// the concurrency claim that keeps two turns from driving one session at once.
+// The primitives here are deliberately SYNCHRONOUS: each does its registry
+// get -> check -> set in a single await-free span, so the "busy claim must be
+// await-free" invariant (I1) and the create-on-miss reservation race (R8) are
+// enforced by construction rather than by careful inline sequencing.
+//
+// The registry stays the storage + idle-TTL + dispose fan-out layer (its
+// exports are unchanged, worklab-compatible); liveness only adds the claim /
+// reserve / release / adoptIfPresent seam that pi-native's session-lifecycle and
+// codex-app both consume.
+
+/**
+ * @typedef {object} SessionRegistryLike
+ * @property {(id: string) => any} get
+ * @property {(id: string, value: any, opts?: {idleTimeoutMs?: number}) => void} set
+ * @property {(id: string) => boolean} delete
+ */
+
+/**
+ * @typedef {{ok: true, entry: any} | {ok: false, reason: "busy" | "missing"}} ClaimResult
+ * @typedef {{ok: true, id: string, release: () => void, commit: (entry: any) => void} | {ok: false, entry: any}} ReserveResult
+ */
+
+/**
+ * @typedef {object} SessionLiveness
+ * @property {(id: string) => ClaimResult} claim
+ * @property {(id: string) => any} adoptIfPresent
+ * @property {(id: string, seed: any, ttl: number|undefined) => ReserveResult} reserve
+ * @property {(id: string) => void} release
+ */
+
+/**
+ * Wrap a session registry with the synchronous liveness primitives. The
+ * explicit return typedef pins the claim/reserve discriminated unions so
+ * callers narrow on `ok` (object-literal inference would otherwise widen `ok`
+ * to boolean and break narrowing).
+ * @param {SessionRegistryLike} registry
+ * @returns {SessionLiveness}
+ */
+export function createSessionLiveness(registry) {
+  return {
+    /**
+     * Claim a live entry for a turn. The registry get -> busy check -> set-busy
+     * span is await-free (I1): a concurrent claim of a busy entry loses and is
+     * told `busy`, never adopting the session mid-turn.
+     * @param {string} id
+     * @returns {{ok: true, entry: any} | {ok: false, reason: "busy" | "missing"}}
+     */
+    claim(id) {
+      const entry = registry.get(id);
+      if (!entry) return { ok: false, reason: "missing" };
+      if (entry.busy) return { ok: false, reason: "busy" };
+      entry.busy = true;
+      return { ok: true, entry };
+    },
+
+    /**
+     * Re-read the registry after an awaited step (F4): a second concurrent cold
+     * resume could have reopened+inserted its own entry in the await window, so
+     * the caller adopts whatever is present (possibly busy) instead of racing a
+     * second insert. Returns null when nothing is present.
+     * @param {string} id
+     * @returns {any | null}
+     */
+    adoptIfPresent(id) {
+      return registry.get(id) ?? null;
+    },
+
+    /**
+     * Reserve an id with a BUSY placeholder before an awaited create (R8). The
+     * get -> check -> set span is await-free, so a second concurrent first turn
+     * observes the placeholder (busy) and loses the reservation — exactly one
+     * create per durable id. On loss the concurrent entry is returned so the
+     * caller can fall into the busy-claim path.
+     * @param {string} id
+     * @param {any} seed BUSY placeholder entry to insert.
+     * @param {number|undefined} ttl per-entry idle timeout.
+     * @returns {{ok: true, id: string, release: () => void, commit: (entry: any) => void} | {ok: false, entry: any}}
+     */
+    reserve(id, seed, ttl) {
+      const concurrent = registry.get(id);
+      if (concurrent) return { ok: false, entry: concurrent };
+      registry.set(id, seed, { idleTimeoutMs: ttl });
+      return {
+        ok: true,
+        id,
+        // Drop the placeholder (drop / error / abort paths). delete() removes
+        // without running onEvict, matching the raw registry.delete it replaces.
+        release: () => { registry.delete(id); },
+        // Overwrite the placeholder with the finalized entry on the keep-alive
+        // success path (same id, same ttl).
+        commit: (entry) => { registry.set(id, entry, { idleTimeoutMs: ttl }); },
+      };
+    },
+
+    /**
+     * Release a session's liveness (remove without running onEvict — the caller
+     * has already cleaned up, or is dropping an uncommitted session).
+     * @param {string} id
+     */
+    release(id) {
+      registry.delete(id);
+    },
+  };
+}

package/src/ai/runtime/sessions.js

@@ -25,6 +25,13 @@ function normalizeTtl(value, fallback) {
   return n;
 }
 
+/**
+ * @param {object} [options]
+ * @param {number} [options.idleTimeoutMs]
+ * @param {(value: any, reason: string) => (void | Promise<void>)} [options.onEvict]
+ * @param {() => number} [options.now]
+ * @param {(value: any) => boolean} [options.isBusy]
+ */
 export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS, onEvict, now = Date.now, isBusy } = {}) {
   const entries = new Map();
   const defaultTtlMs = normalizeTtl(idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS);
@@ -70,6 +77,11 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
       }
       return entry.value;
     },
+    /**
+     * @param {any} id
+     * @param {any} value
+     * @param {{idleTimeoutMs?: number}} [options]
+     */
     set(id, value, { idleTimeoutMs: entryTtl } = {}) {
       const previous = entries.get(id);
       if (previous) clearTimeout(previous.timer);
@@ -77,6 +89,10 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
       entries.set(id, entry);
       armTimer(id, entry);
     },
+    /**
+     * @param {any} id
+     * @param {{idleTimeoutMs?: number}} [options]
+     */
     touch(id, { idleTimeoutMs: entryTtl } = {}) {
       const entry = entries.get(id);
       if (!entry) return;