@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/src/ai/cost.js

@@ -9,8 +9,7 @@ import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/a
 
 /**
  * @typedef {Object} ParsedModelReference
- * @property {string|null} sdk
- * @property {string} [provider]
+ * @property {string} provider
  * @property {string} model
  */
 
@@ -40,25 +39,6 @@ import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/a
  * @property {number|string} [output_per_million]
  */
 
-// STATIC FALLBACK, consulted only AFTER pi's live catalog (piCatalogPricing via
-// getBuiltinModel("anthropic", ...)). pi's anthropic catalog already carries the
-// same per-million rates for the currently-shipping models, so this table only
-// wins for Claude ids pi's catalog does not (yet) know — newer/renamed models
-// added here before they land in a pinned pi-ai release. STALENESS: these are
-// hand-maintained USD/1M-token rates and can drift from Anthropic's published
-// pricing; treat them as a best-effort backstop for cost DIAGNOSTICS only (never
-// control flow), and refresh when bumping pi-ai or when Anthropic reprices.
-const CLAUDE_PRICING = {
-  "claude-haiku-4-5-20251001": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
-  "claude-haiku-4-5": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
-  "claude-sonnet-4-6": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
-  "claude-sonnet-4-5": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
-  "claude-sonnet-4": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
-  "claude-opus-4-7": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
-  "claude-opus-4-6": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
-  "claude-opus-4-5": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
-};
-
 /**
  * @param {*} value
  * @returns {number|null}
@@ -126,26 +106,13 @@ function unknownPricing() {
  * @returns {ParsedModelReference|null}
  */
 function parseReference(reference) {
-  if (typeof reference !== "string" || !reference.trim()) return null;
-  if (reference.startsWith("vercel:")) {
-    const rest = reference.slice("vercel:".length);
-    const i = rest.indexOf(":");
-    return i > 0 ? { sdk: "pi", provider: rest.slice(0, i), model: rest.slice(i + 1) } : null;
-  }
-  if (reference.startsWith("codex:")) {
-    return { sdk: "pi", provider: "openai-codex", model: reference.slice("codex:".length) };
-  }
-  if (reference.startsWith("openai:")) {
-    return { sdk: "pi", provider: "openai", model: reference.slice("openai:".length) };
-  }
-  if (reference.startsWith("pi:")) {
-    const rest = reference.slice("pi:".length);
-    const i = rest.indexOf(":");
-    return i > 0 ? { sdk: "pi", provider: rest.slice(0, i), model: rest.slice(i + 1) } : null;
-  }
-  const i = reference.indexOf(":");
-  if (i <= 0) return { sdk: null, model: reference };
-  return { sdk: reference.slice(0, i), model: reference.slice(i + 1) };
+  if (typeof reference !== "string" || reference.length === 0 || reference.trim() !== reference) return null;
+  const separator = reference.indexOf(":");
+  if (separator <= 0 || separator === reference.length - 1) return null;
+  const provider = reference.slice(0, separator);
+  const model = reference.slice(separator + 1);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(provider) || model.trim() !== model) return null;
+  return { provider, model };
 }
 
 /**
@@ -182,30 +149,19 @@ function pricingHasRates(pricing = {}) {
 }
 
 /**
- * Live pricing from pi-ai's builtin catalog (getBuiltinModel). Handles two
- * shapes:
- *   - sdk "pi": `parsed.provider` is the pi provider id (openai, openai-codex,
- *     github-copilot, custom, ...). Codex/openai references route here via
- *     parseReference (codex:* -> openai-codex, openai:* -> openai), so they get
- *     the SAME catalog treatment — priced when pi's catalog has that model
- *     (openai gpt-* do), unpriced (-> falls through to unknown) when it does not
- *     (e.g. openai-codex `gpt-5-codex` is not in the pinned catalog).
- *   - sdk "claude": looked up under pi's "anthropic" provider (its models carry
- *     `cost`), so pi's live rates win over the static CLAUDE_PRICING fallback.
+ * Live pricing from pi-ai's builtin catalog (getBuiltinModel). The parsed
+ * provider is already the Pi catalog provider id; the model remains opaque and
+ * may contain additional colons or slashes.
  * @param {ParsedModelReference|null|undefined} parsed
  * @returns {import("@earendil-works/pi-ai").Model<any>|null}
  */
 function piCatalogModel(parsed) {
-  if (!parsed?.model) return null;
-  let provider;
-  if (parsed.sdk === "pi" && parsed.provider) provider = parsed.provider;
-  else if (parsed.sdk === "claude") provider = "anthropic";
-  else return null;
+  if (!parsed?.provider || !parsed.model) return null;
   try {
     // `provider` may be a caller-supplied id (custom providers included), wider
     // than pi-ai's built-in KnownProvider catalog union; the catalog lookup
     // itself is the runtime check, guarded by the catch below.
-    return getPiModel(/** @type {*} */ (provider), parsed.model) || null;
+    return getPiModel(/** @type {*} */ (parsed.provider), parsed.model) || null;
   } catch {
     return null;
   }
@@ -220,15 +176,6 @@ function piCatalogPricing(parsed) {
   return model?.cost ? normalizePricing(model.cost, { source: "pi-catalog" }) : null;
 }
 
-/**
- * @param {ParsedModelReference|null|undefined} parsed
- * @returns {NormalizedPricing|null}
- */
-function claudePricing(parsed) {
-  if (parsed?.sdk !== "claude") return null;
-  return normalizePricing(CLAUDE_PRICING[parsed.model], { source: "claude-table" });
-}
-
 // `resolveCustomPricing(parsed) -> NormalizedPricing | null` lets a host plug
 // in user-defined pricing tables. Hosts query custom model/provider stores
 // in src/core/custom-pricing.js and passes the closure in via `generateResponse`.
@@ -249,7 +196,6 @@ export function resolvePricing({ resolveCustomPricing, model } = {}) {
     : null;
   return custom
     || piCatalogPricing(parsed)
-    || claudePricing(parsed)
     || unknownPricing();
 }
 
@@ -301,7 +247,6 @@ export function estimateCost({
     return estimatePiCatalogCost(piModel, { input, output, cacheRead, cacheWrite });
   }
   const pricing = customPricing
-    || claudePricing(parsed)
     || unknownPricing();
   if (!pricing?.priced) return null;
   const parts = [

package/src/ai/failure.js

@@ -72,19 +72,19 @@ export const FAILURE_KINDS = [
 ];
 
 const CONTEXT_LIMIT_RE = /(?:context[_ ](?:length|window|budget)|token[_ ]limit|(?:input|prompt)(?:[_ ]tokens?)?[_ ](?:is[_ ])?too[_ ]long|(?:input|prompt|request)(?:[_ ]tokens?)?[_ ]exceeds?[_ ](?:the[_ ])?(?:context|maximum|max|limit|allowed[_ ]size)|too[_ ]many[_ ](?:input[_ ])?tokens?|tokens?[_ ]exceed(?:s|ed)?[_ ](?:the[_ ])?(?:context|maximum|max|(?:model[_ ])?limit))/i;
-const USAGE_LIMIT_RE = /(rate limit|usage limit|max(?:imum)?(?:[_ ]output)?[_ ]tokens?|max turns)/i;
+const USAGE_LIMIT_RE = /(rate limit|usage limit|insufficient[_ ]quota|quota exceeded|billing limit|too many requests|429|max(?:imum)?(?:[_ ]output)?[_ ]tokens?|max turns)/i;
 // Pi's Models layer emits the exact `Provider is not configured: <id>` message
 // only after it has found the provider but cannot resolve that provider's auth.
 // Treating it as availability left credential fallbacks pinned to the dead
 // route because the router only advances on provider_auth or retryable outages.
-const PROVIDER_AUTH_RE = /(no api key|missing api key|api key required|invalid api key|incorrect api key|provider is not configured:|authentication|authorization|not authorized|forbidden|oauth (?:refresh|auth|authentication|token).*failed|credential store (?:read|modify) failed|401|403)/i;
+const PROVIDER_AUTH_RE = /(no api key|missing api key|api key required|invalid api key|incorrect api key|provider is not configured:|authentication failed|authorization failed|unauthorized|oauth (?:refresh|auth|authentication|token).*failed|credential store (?:read|modify) failed|invalid[_ ]grant|token[_ ]revoked|revoked (?:oauth )?token|invalidated (?:oauth )?token|encountered invalidated oauth token|\b401\b)/i;
 // Mirrors the conservative connection-error/refused/failed alternation added to
 // RETRYABLE_PROVIDER_RE / retryableProviderSubkind below for pi 0.80's terse
 // "Connection error." — without it, classifyFailure (used directly by hosts
 // like worklab's coordinator, independent of retryableProviderFailureInfo) maps
 // that same terse text to the generic "spawn" kind instead of
 // "provider_unavailable".
-const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
+const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|forbidden|\b403\b|model[_ ]not[_ ]found|unsupported model|no access to (?:the )?model|\b404\b|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
 const TOOL_FAILURE_RE = /(tool .* failed|mcp tool|permission denied|EACCES|read-only file system)/i;
 const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api key|missing api key|api key required|invalid api key|incorrect api key|provider is not configured:|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
 // pi 0.80's openai-client-style bridge collapses a connection-refused/unreachable

package/src/ai/index.js

@@ -12,23 +12,11 @@ export {
 } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
-export { generateAcpResponse, acpRuntimeBridge } from "./providers/acp.js";
-export * from "./providers/acp-public.js";
-export {
-  getPiBuiltinModel,
-  listPiBuiltinModels,
-  loginPiOAuth,
-  reasoningLevelsForPiModel,
-  resolvePiOAuthApiKey,
-} from "./pi-interop.js";
-export {
-  CLAUDE_SDK_CATALOG_VERSION,
-  createClaudeSdkDiscoveryIsolation,
-  curatedClaudeSdkModels,
-  discoverClaudeSdkModels,
-  normalizeClaudeSdkCatalog,
-  normalizeClaudeSdkModelId,
-} from "./providers/claude-sdk-discovery.js";
+// Re-exported with `export *` so the JSDoc-declared snapshot types
+// (PiBuiltinModelSnapshot, PiBuiltinProviderSnapshot, …) travel with the
+// functions; runtime-adapter re-exports these for host-side catalog builders.
+export * from "./pi-interop.js";
+export * from "./provider-check.js";
 export {
   buildCapabilitiesUsed,
   toolCompactionAppliedFromWarnings,

package/src/ai/observer.js

@@ -21,6 +21,7 @@
  * @typedef Observer
  * @property {string=} name
  * @property {(event: object) => void} recordEvent
+ * @property {(event: object) => void=} recordToolLifecycle Synchronous native lifecycle admission before queued persistence.
  * @property {(metric: object) => void=} recordMetric
  * @property {() => (void | Promise<void>)=} flush
  */
@@ -42,6 +43,12 @@ export function createObserverHub({ observers = [], onEvent = null } = {}) {
     }
   }
 
+  function recordToolLifecycle(event) {
+    for (const obs of list) {
+      try { obs.recordToolLifecycle?.(event); } catch { /* observers remain best-effort */ }
+    }
+  }
+
   function recordMetric(metric) {
     if (!metric) return;
     for (const obs of list) {
@@ -62,6 +69,7 @@ export function createObserverHub({ observers = [], onEvent = null } = {}) {
   return {
     emit,
     recordMetric,
+    recordToolLifecycle,
     flush,
     observers: () => list.slice(),
   };

package/src/ai/pi-interop.js

@@ -2,7 +2,13 @@
 // surfaces. Consumers should use these functions instead of importing pi-ai
 // directly so the runtime's known-good Pi version remains authoritative.
 
-import { getBuiltinModel, getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
+import {
+  builtinModels,
+  builtinProviders,
+  getBuiltinModel,
+  getBuiltinModels,
+  getBuiltinProviders,
+} from "@earendil-works/pi-ai/providers/all";
 import { getPiOAuthAuth, resolveOAuthApiKey, toAuthInteraction } from "./pi-oauth-compat.js";
 import { reasoningLevelsForPiModel as resolveReasoningLevels } from "./providers/pi-models.js";
 
@@ -41,6 +47,13 @@ import { reasoningLevelsForPiModel as resolveReasoningLevels } from "./providers
  * @typedef {"none"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max"} PiReasoningLevel
  */
 
+/**
+ * @typedef {{
+ *   id: string,
+ *   label: string
+ * }} PiBuiltinProviderSnapshot
+ */
+
 /**
  * @typedef {{
  *   refresh: string,
@@ -61,6 +74,37 @@ import { reasoningLevelsForPiModel as resolveReasoningLevels } from "./providers
  * @property {AbortSignal} [signal]
  */
 
+/**
+ * @typedef {{
+ *   providerId: string,
+ *   label: string,
+ *   methods: Array<{type: "oauth"|"api_key", label: string, interactive: boolean}>
+ * }} PiProviderAuthDescription
+ */
+
+/**
+ * @typedef {{source: "stored"|"environment"|"ambient", type: "oauth"|"api_key"}} PiProviderAuthCheck
+ */
+
+/**
+ * @typedef {{
+ *   type: "text"|"secret"|"select"|"manual_code",
+ *   message: string,
+ *   placeholder?: string,
+ *   allowEmpty?: boolean,
+ *   options?: ReadonlyArray<{id: string, label: string, description?: string}>,
+ *   signal?: AbortSignal
+ * }} PiProviderAuthPrompt
+ */
+
+/**
+ * @typedef {{
+ *   signal?: AbortSignal,
+ *   prompt: (prompt: PiProviderAuthPrompt) => Promise<string>,
+ *   notify: (event: *) => void
+ * }} PiProviderAuthInteraction
+ */
+
 /**
  * Clone provider-owned data before it crosses the public runtime boundary.
  * Pi's built-in models and OAuth credentials are structured data on the
@@ -103,6 +147,182 @@ export function getPiBuiltinModel(providerId, modelId) {
     : /** @type {PiBuiltinModelSnapshot} */ (cloneInteropValue(model));
 }
 
+let builtinProviderLabels;
+function builtinProviderLabelMap() {
+  // `getBuiltinProviders()` is the authoritative static catalog set (39 ids),
+  // but it returns bare ids — the human display label lives on the constructed
+  // `Provider.name`, which only `builtinProviders()` exposes. Build the name
+  // lookup once from the constructed providers and gate what we ADVERTISE on
+  // the static id set below, so the dynamic "radius" gateway (present in
+  // `builtinProviders()` but absent from `getBuiltinProviders()`) never enters
+  // the advertised catalog. A throwing construction degrades to id-as-label.
+  builtinProviderLabels ??= (() => {
+    try {
+      return new Map(builtinProviders().map((provider) => [provider.id, provider.name]));
+    } catch {
+      return new Map();
+    }
+  })();
+  return builtinProviderLabels;
+}
+
+/**
+ * List defensive snapshots of Pi's static built-in providers (id + display
+ * label). The dynamic "radius" gateway is deliberately excluded: it has no
+ * static catalog and must not be advertised as a browsable provider.
+ *
+ * @returns {PiBuiltinProviderSnapshot[]}
+ */
+export function listPiBuiltinProviders() {
+  const labels = builtinProviderLabelMap();
+  return getBuiltinProviders().map((id) => ({
+    id,
+    label: labels.get(id) ?? id,
+  }));
+}
+
+/**
+ * Describe one static Pi built-in provider by id, or `undefined` for unknown
+ * ids (including the dynamic "radius" gateway).
+ *
+ * @param {string} providerId
+ * @returns {PiBuiltinProviderSnapshot|undefined}
+ */
+export function describePiBuiltinProvider(providerId) {
+  const id = String(providerId);
+  if (!getBuiltinProviders().includes(/** @type {any} */ (id))) {
+    return undefined;
+  }
+  return {
+    id,
+    label: builtinProviderLabelMap().get(id) ?? id,
+  };
+}
+
+/**
+ * Describe one provider's supported authentication methods without exposing
+ * Pi provider objects across the runtime boundary.
+ *
+ * @param {string} providerId
+ * @returns {PiProviderAuthDescription|undefined}
+ */
+export function describePiProviderAuth(providerId) {
+  let provider;
+  try {
+    provider = builtinProviders().find((candidate) => candidate.id === providerId);
+  } catch {
+    return undefined;
+  }
+  if (provider === undefined) return undefined;
+  const methods = [];
+  if (provider.auth.oauth !== undefined) {
+    methods.push({
+      type: /** @type {const} */ ("oauth"),
+      label: provider.auth.oauth.loginLabel ?? provider.auth.oauth.name,
+      interactive: true,
+    });
+  }
+  if (provider.auth.apiKey !== undefined) {
+    methods.push({
+      type: /** @type {const} */ ("api_key"),
+      label: provider.auth.apiKey.name,
+      interactive: typeof provider.auth.apiKey.login === "function",
+    });
+  }
+  return cloneInteropValue({ providerId: provider.id, label: provider.name, methods });
+}
+
+/**
+ * Run Pi's side-effect-free `Models.checkAuth()` against a caller-provided
+ * credential/environment snapshot. OAuth refresh and live provider requests do
+ * not occur. Only the non-secret source/type result crosses this facade.
+ *
+ * @param {string} providerId
+ * @param {*} credential
+ * @param {Readonly<Record<string, string|undefined>>} [environment]
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<PiProviderAuthCheck|undefined>}
+ */
+export async function checkPiProviderAuth(providerId, credential, environment = {}, signal) {
+  const credentials = memoryCredentialStore(credential === undefined ? {} : { [providerId]: credential });
+  const models = builtinModels({
+    credentials,
+    authContext: {
+      async env(name) { return environment[name]; },
+      async fileExists(path) {
+        try {
+          const fs = await import("node:fs/promises");
+          let resolved = path;
+          if (resolved.startsWith("~")) {
+            const os = await import("node:os");
+            resolved = os.homedir() + resolved.slice(1);
+          }
+          await fs.access(resolved);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    },
+  });
+  const result = await models.checkAuth(providerId, signal === undefined ? undefined : { signal });
+  if (result === undefined) return undefined;
+  const source = result.type === "oauth" || result.source === "stored credential"
+    ? "stored"
+    : typeof result.source === "string"
+      && typeof environment[result.source] === "string"
+      && environment[result.source].trim().length > 0
+      ? "environment"
+      : "ambient";
+  return cloneInteropValue({ source, type: result.type });
+}
+
+/**
+ * Run a provider-owned Pi login into a process-local store. The returned
+ * credential is a defensive snapshot; the caller remains responsible for its
+ * hardened durable transaction.
+ *
+ * @param {string} providerId
+ * @param {"oauth"|"api_key"} type
+ * @param {PiProviderAuthInteraction} interaction
+ * @returns {Promise<*>}
+ */
+export async function loginPiProviderAuth(providerId, type, interaction) {
+  if (type !== "oauth" && type !== "api_key") {
+    throw new TypeError("Pi provider auth type must be oauth or api_key");
+  }
+  if (typeof interaction?.prompt !== "function" || typeof interaction?.notify !== "function") {
+    throw new TypeError("Pi provider auth interaction requires prompt() and notify()");
+  }
+  const models = builtinModels({ credentials: memoryCredentialStore({}) });
+  const credential = await models.login(providerId, type, {
+    signal: interaction.signal,
+    prompt: async (prompt) => await interaction.prompt(prompt),
+    notify: (event) => interaction.notify(cloneInteropValue(event)),
+  });
+  return cloneInteropValue(credential);
+}
+
+/** @param {Record<string, *>} initial */
+function memoryCredentialStore(initial) {
+  const held = new Map(Object.entries(initial));
+  return {
+    async read(providerId) { return held.get(providerId); },
+    async list() {
+      return [...held.entries()].flatMap(([providerId, credential]) =>
+        credential?.type === "oauth" || credential?.type === "api_key"
+          ? [{ providerId, type: credential.type }]
+          : []);
+    },
+    async modify(providerId, fn) {
+      const next = await fn(held.get(providerId));
+      if (next !== undefined) held.set(providerId, next);
+      return held.get(providerId);
+    },
+    async delete(providerId) { held.delete(providerId); },
+  };
+}
+
 /**
  * Translate Pi's model-native thinking levels to mono-agent effort spelling.
  *

package/src/ai/pi-oauth-compat.js

@@ -10,7 +10,7 @@
 // they cannot be imported. The supported surface is `provider.auth.oauth`,
 // reached through the provider factories.
 //
-// mono-agent resolves providers dynamically from `pi:<provider>:<model>`, so it
+// mono-agent resolves providers dynamically from `<provider>:<model>`, so it
 // needs a lookup by id — this module rebuilds that over `builtinProviders()` and
 // preserves the old call contracts exactly, keeping the migration confined here.
 //

package/src/ai/provider-check.js

@@ -0,0 +1,131 @@
+// @ts-check
+
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+
+import { generatePiNativeResponse } from "./providers/pi-native.js";
+
+const SYSTEM_PROMPT = "Provider connectivity check. Reply OK.";
+const USER_PROMPT = "OK";
+
+/** @typedef {"passed"|"auth_failed"|"network_failed"|"quota_limited"|"model_not_entitled"|"inconclusive"} ProviderCheckOutcome */
+/** @typedef {"passed"|"credential_rejected"|"provider_unavailable"|"quota_limited"|"model_not_entitled"|"forbidden"|"inconclusive"|"cancelled"} ProviderCheckCode */
+
+/**
+ * Execute one target-only Pi request. This intentionally bypasses the router:
+ * a different provider or model must never prove the requested target healthy.
+ * Provider output and raw errors are consumed here and never returned.
+ *
+ * @param {{
+ *   model: {provider: string, model: string, reference?: string},
+ *   resolvePiApiKey?: Function,
+ *   runtimeOptions?: Record<string, unknown>,
+ *   environment?: Readonly<Record<string, string|undefined>>,
+ *   abortSignal?: AbortSignal,
+ *   execute?: typeof generatePiNativeResponse,
+ * }} input
+ * @returns {Promise<{state: ProviderCheckOutcome, code: ProviderCheckCode, message: string}>}
+ */
+export async function runPiProviderCheck(input) {
+  const execute = input.execute ?? generatePiNativeResponse;
+  const runtimeOptions = providerConstructionOptions(input.runtimeOptions);
+  let result;
+  try {
+    result = await execute(SYSTEM_PROMPT, {
+      ...runtimeOptions,
+      model: {
+        provider: input.model.provider,
+        model: input.model.model,
+        reference: input.model.reference ?? `${input.model.provider}:${input.model.model}`,
+      },
+      messages: [{ role: "user", content: USER_PROMPT }],
+      effort: "none",
+      allowedTools: [],
+      disallowedTools: [],
+      mcpServers: {},
+      maxTurns: 1,
+      piMaxRetries: 0,
+      providerCheckMaxTokens: 4,
+      providerCheckAuthContext: {
+        async env(name) { return input.environment?.[name]; },
+        async fileExists(path) {
+          try {
+            await access(path.startsWith("~") ? homedir() + path.slice(1) : path);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+      },
+      ...(input.resolvePiApiKey === undefined ? {} : { resolvePiApiKey: input.resolvePiApiKey }),
+      ...(input.abortSignal === undefined ? {} : { abortSignal: input.abortSignal }),
+    });
+  } catch (error) {
+    return classifyProviderCheckFailure(error instanceof Error ? error.message : "", undefined);
+  }
+  if (result?.cancelled === true || input.abortSignal?.aborted === true) {
+    return { state: "inconclusive", code: "cancelled", message: "The provider check did not complete." };
+  }
+  if (!result?.error && result?.failureKind == null) {
+    return { state: "passed", code: "passed", message: "Provider request succeeded." };
+  }
+  return classifyProviderCheckFailure(
+    typeof result?.error === "string" ? result.error : "",
+    typeof result?.failureKind === "string" ? result.failureKind : undefined,
+  );
+}
+
+/**
+ * Classify raw provider text inside the runtime boundary. The returned strings
+ * are closed, fixed projections and contain no provider-controlled content.
+ * @param {string} text
+ * @param {string|undefined} failureKind
+ * @returns {{state: ProviderCheckOutcome, code: ProviderCheckCode, message: string}}
+ */
+export function classifyProviderCheckFailure(text, failureKind) {
+  const value = String(text || "");
+  if (failureKind === "provider_auth"
+    || /(invalid api key|incorrect api key|no api key|missing api key|authentication failed|authorization failed|unauthorized|invalid[_ ]grant|token[_ ]revoked|revoked (?:oauth )?token|invalidated (?:oauth )?token|\b401\b)/i.test(value)) {
+    return { state: "auth_failed", code: "credential_rejected", message: "Provider rejected the configured credential." };
+  }
+  if (failureKind === "usage_limit"
+    || /(rate limit|too many requests|insufficient[_ ]quota|quota exceeded|billing limit|\b429\b)/i.test(value)) {
+    return { state: "quota_limited", code: "quota_limited", message: "Provider quota or rate limit prevented the check." };
+  }
+  if (/(model[_ -]?not[_ -]?found|unsupported model|no access to (?:the )?model|model entitlement|model[^\n]{0,120}(?:does not exist|not found|unavailable))/i.test(value)) {
+    return { state: "model_not_entitled", code: "model_not_entitled", message: "The credential could not use the selected model." };
+  }
+  if (/forbidden|\b403\b/i.test(value)) {
+    return { state: "inconclusive", code: "forbidden", message: "The provider refused the check for an unspecified reason." };
+  }
+  if (failureKind === "provider_unavailable"
+    || /(econn|enotfound|etimedout|timed? ?out|service unavailable|gateway|fetch failed|network|websocket|\b5\d\d\b|\bconnection (?:error|refused|failed)\b)/i.test(value)) {
+    return { state: "network_failed", code: "provider_unavailable", message: "The provider could not be reached." };
+  }
+  return { state: "inconclusive", code: "inconclusive", message: "The provider check failed without a safe diagnosis." };
+}
+
+/**
+ * Keep the public check facade isolated from ordinary run state. These are the
+ * only provider/model construction seams required by configured local
+ * providers and deterministic faux-provider tests.
+ * @param {Record<string, unknown>|undefined} options
+ * @returns {Record<string, unknown>}
+ */
+function providerConstructionOptions(options) {
+  if (options === undefined) return {};
+  const allowed = [
+    "customProvider",
+    "customModel",
+    "modelCapabilities",
+    "isPrivateProvider",
+    "piResolvedModel",
+    "piResolvedModels",
+    "piResolvedCapabilities",
+  ];
+  return Object.fromEntries(allowed
+    .filter((key) => Object.hasOwn(options, key))
+    .map((key) => [key, options[key]]));
+}
+
+export const PROVIDER_CHECK_PROMPT = Object.freeze({ system: SYSTEM_PROMPT, user: USER_PROMPT, maxOutputTokens: 4 });