@mono-agent/agent-runtime 0.15.4 → 0.17.0

package/MIGRATION.md

@@ -42,8 +42,8 @@ the configuration schema.
   switch to `listPiBuiltinModels`, `getPiBuiltinModel`,
   `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` from
   `@mono-agent/agent-runtime/ai`. The runtime keeps Pi AI and Pi Agent Core
-  exact-pinned at `0.80.6`; the façade returns cloned model and credential
-  snapshots rather than exposing mutable upstream registries.
+  exact-pinned at `0.83.0`; the façade returns cloned model and credential
+  snapshots rather than exposing upstream provider objects.
 - **Claude test seam:** downstream tests should pass
   `RuntimeRunOptions.claudeAgentQuery` instead of mocking
   `@anthropic-ai/claude-agent-sdk` by package name. Normal runs omit this option
@@ -63,12 +63,35 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.15.x baseline
+## 0.17.x baseline
 
-This is the current published baseline for the detailed pre-1.0 reference
-below. It includes the explicit exports map, the five-bridge lazy registry,
-typed runtime policies, runtime-owned provider dependencies, and the
-public-surface cleanup described in this guide.
+This is the current published baseline. It carries the 0.16.x contract forward
+and adds a host-only, request-scoped `toolEnvironment` boundary. Hosts may pass
+validated values and PATH prefixes through the request, harness, and runtime;
+the runtime applies them only when Bash, Exec, or a nested subagent process is
+spawned. It does not mutate `process.env` or persist the values in prompts,
+metadata, history, traces, or long-lived tool context.
+
+## 0.16.x
+
+This baseline carries the whole 0.15.x contract forward and adds:
+
+- `skills` and `skillsRoot` on the run options. `skills` is the disclosed
+  `{name, description}` set for a run; a non-empty value makes `supports_skills`
+  a routing requirement, so a chain entry lacking it is skipped. `skillsRoot`
+  names the directory holding `<name>/SKILL.md` and is required alongside
+  `skills` for `ReadSkill` to exist. A subagent run now inherits both from its
+  parent unless a host-supplied `run` withholds them, so a child no longer has
+  to rediscover by trial and error what its parent could look up.
+- Provider failover detail reaches whoever is watching the run rather than being
+  flattened at the boundary.
+- Pi SDK 0.83.0.
+
+## 0.15.x
+
+- The explicit exports map, the five-bridge lazy registry, typed runtime
+  policies, runtime-owned provider dependencies, and the public-surface cleanup
+  described in this guide.
 
 ## 0.12.x
 
@@ -313,9 +336,22 @@ falls back to its own env vars, exactly as returning `undefined` from the old ho
 did). **No host action needed** — `resolvePiApiKey` behaves as before.
 
 Dependency bump: **`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core` are
-now `0.80.6`** (the initial Pi 0.80 migration landed at `0.80.5`, from
-`^0.79.1`). Compaction is driven natively (section 3). The `0.80.6` refresh also
-preserves model-native `max` reasoning and Pi's request-wide pricing tiers.
+now `0.83.0`** (the initial Pi 0.80 migration landed at `0.80.5`, from
+`^0.79.1`, and ran at `0.80.6` until the 0.83 upgrade). Compaction is driven
+natively (section 3), and model-native `max` reasoning plus Pi's request-wide
+pricing tiers are preserved.
+
+The 0.83 upgrade carries two upstream removals, both absorbed inside the runtime
+so hosts need no action:
+
+- `@earendil-works/pi-ai/oauth` became a type-only entry point. The generic
+  registry (`getOAuthApiKey`, `getOAuthProvider`, `getOAuthProviders`) is gone,
+  and the per-provider flows are not importable. `src/ai/pi-oauth-compat.js`
+  rebuilds the same contracts over `provider.auth.oauth`, so `resolvePiApiKey`,
+  `resolvePiOAuthApiKey`, and `loginPiOAuth` keep their existing signatures and
+  behaviour, including the refresh-on-expiry trigger.
+- `AgentHarnessOptions.env` was removed in favour of a per-turn `toolContext`.
+  The runtime passes neither: it uses none of Pi's built-in file/shell tools.
 
 ### 11. Exports map: wildcards removed (explicit deep-path map)
 
@@ -366,7 +402,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.15.x` package contract. Keep
+This guide describes the published `0.17.x` package contract. Keep
 `@mono-agent/agent-runtime`, `@mono-agent/runtime-adapter`, and other
 `@mono-agent/*` packages on the same lockstep version when upgrading. The paired
 runtime adapter no longer exposes `piReasoningSummary` in its run-options type.
@@ -387,14 +423,14 @@ Worklab's runtime fork:
    `@earendil-works/pi-ai`, its separate Pi version constraint, and local copies
    of provider bridge code. Move tests off Pi's faux-provider helpers too; until
    that is complete, isolate the fixture or pin its development-only Pi
-   dependency to exact `0.80.6` rather than a floating range. Do not restore the
+   dependency to exact `0.83.0` rather than a floating range. Do not restore the
    removed `pi-sdk.js` subpath.
 3. **Use the public Pi surfaces.** Run models through
    `generatePiNativeResponse` or the runtime registry. Use
    `listPiBuiltinModels`, `getPiBuiltinModel`,
    `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` for
-   catalog and OAuth integration. Those façades keep Pi mutable state and the
-   exact `0.80.6` compatibility pin inside the runtime. OAuth login adapters
+   catalog and OAuth integration. Those façades keep Pi provider objects and the
+   exact `0.83.0` compatibility pin inside the runtime. OAuth login adapters
    must supply `onAuth`, `onDeviceCode`, `onPrompt`, and `onSelect`; the façade
    rejects an incomplete callback contract before starting provider login.
 4. **Inject Claude tests.** Replace package-level mocks of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.15.4",
+  "version": "0.17.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -133,8 +133,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.206",
     "@anthropic-ai/sdk": "^0.110.0",
-    "@earendil-works/pi-agent-core": "0.80.6",
-    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "0.6.0",
     "@opencode-ai/sdk": "^1.15.13",

package/src/agent/tools/agent-tool.js

@@ -93,16 +93,38 @@ function toolDescription(subagents, definitions, ceiling) {
   const named = definitions.length === 0
     ? ""
     : `\n\nAvailable subagents:\n${definitions.map((d) => `- ${d.name}: ${d.description}`).join("\n")}\n- ${GENERAL_PURPOSE_SUBAGENT}: read-only researcher inheriting the main model. Used when \`name\` is omitted.`;
+  // With authoring on, `name` is a free string rather than an enum, so it is
+  // the model's only signal for which of the two shapes it is writing. Left
+  // implicit, a caller that wants a configured profile AND a descriptive label
+  // splits those across two fields — label into `name`, profile into an
+  // invented one — and the closed schema rejects the whole call before any of
+  // the handler's precise errors can run.
+  const shapes = ceiling === null
+    ? ""
+    : `\n\nExactly two ways to call this, and \`name\` carries the agent's identity in both:\n- Use a configured one: set \`name\` to a name from the list above. Nothing else.\n- Build one for this task: set \`name\` to a NEW kebab-case name AND \`systemPrompt\` to its full instructions (optionally \`tools\`, \`effort\`). Do that when no configured one fits — a dedicated prompt beats stuffing constraints into \`prompt\`.\n\n\`description\` is the short label shown in the activity log, never the agent's name. There is no separate field for choosing a configured agent.`;
   // The ceiling is listed because the model has no other way to discover it: a
   // tool it cannot see is indistinguishable from one it forgot to ask for.
   const inline = ceiling === null
     ? ""
-    : `\n\nYou can also build a specialist on the spot instead of picking a profile: pass \`systemPrompt\` with its full instructions, a kebab-case \`name\`, and the \`tools\` it needs. Do that when no profile fits the task — a dedicated prompt beats stuffing constraints into \`prompt\`. Tools you may grant: ${ceiling.join(", ")}. Anything else is dropped. Omit \`tools\` for a read-only helper.`;
-  return `${DESCRIPTION_BASE}${parallel}${named}${inline}`;
+    : `\n\nTools you may grant a subagent you build: ${ceiling.join(", ")}. Anything else is dropped. Omit \`tools\` for a read-only helper.`;
+  return `${DESCRIPTION_BASE}${parallel}${named}${shapes}${inline}`;
+}
+
+/** @param {*} value @returns {number} */
+function numberOrZero(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+/** @returns {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} */
+function emptyUsage() {
+  return { costUsd: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 }
 
 /**
- * Per-logical-run call and byte budget, shared across router attempts.
+ * Per-logical-run call, byte and subagent-usage budget, shared across router
+ * attempts. `usage` rides the same entry so delegated spend inherits the
+ * existing per-run keying and eviction instead of needing a second store.
  * @param {*} subagents The run-scoped options object, stable across attempts.
  * @param {string|undefined} parentRunId
  */
@@ -120,11 +142,58 @@ function budgetForRun(subagents, parentRunId) {
     if (oldest.done) break;
     store.delete(oldest.value);
   }
-  const fresh = { total: 0, bytes: 0, warnedQueued: false };
+  const fresh = { total: 0, bytes: 0, warnedQueued: false, usage: emptyUsage() };
   store.set(key, fresh);
   return fresh;
 }
 
+/**
+ * How many subagents this logical run actually spawned.
+ *
+ * A read-only accessor so a provider can report `subagent_invoked` truthfully
+ * without reaching into `__budgets`, which is a deliberately private,
+ * non-enumerable implementation detail. Returns 0 when nothing was ever
+ * registered — a run with no `Agent` tool never creates a budget entry, and that
+ * is indistinguishable from one that had the tool and never used it, which is
+ * exactly what "no subagent was invoked" means for this signal.
+ *
+ * @param {*} subagents The run-scoped options object, or undefined.
+ * @param {string|undefined} parentRunId
+ * @returns {number}
+ */
+export function subagentInvocationCount(subagents, parentRunId) {
+  const store = subagents?.__budgets;
+  if (!(store instanceof Map)) return 0;
+  const entry = store.get(parentRunId ?? "unkeyed");
+  return Number.isInteger(entry?.total) ? entry.total : 0;
+}
+
+/**
+ * What this logical run's subagents spent, summed across every delegation.
+ *
+ * A delegation is work the run asked for, so its cost belongs to the run's
+ * total — a provider folds this into its own usage before reporting, which is
+ * what makes the console's cost, the TUI status bar and the exported metrics
+ * agree with the bill. Same read-only-accessor contract as
+ * `subagentInvocationCount`: `__budgets` stays private. All zeroes when nothing
+ * delegated, which is the truthful answer for a run that never used the tool.
+ *
+ * @param {*} subagents The run-scoped options object, or undefined.
+ * @param {string|undefined} parentRunId
+ * @returns {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}}
+ */
+export function subagentUsageForRun(subagents, parentRunId) {
+  const store = subagents?.__budgets;
+  const usage = store instanceof Map ? store.get(parentRunId ?? "unkeyed")?.usage : undefined;
+  return {
+    costUsd: numberOrZero(usage?.costUsd),
+    input: numberOrZero(usage?.input),
+    output: numberOrZero(usage?.output),
+    cacheRead: numberOrZero(usage?.cacheRead),
+    cacheWrite: numberOrZero(usage?.cacheWrite),
+  };
+}
+
 /** @param {*} value @param {number} fallback @returns {number} */
 function positiveInt(value, fallback) {
   return Number.isInteger(value) && value > 0 ? value : fallback;
@@ -134,7 +203,7 @@ function positiveInt(value, fallback) {
  * Build the `Agent` tool, or null when subagents are unavailable for this run.
  *
  * @param {RuntimeSubagentsOptions|null|undefined} subagents
- * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, onEvent?: (event: *) => void}} [context]
+ * @param {{model?: *, executionMode?: string, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents, context = {}) {
@@ -306,6 +375,15 @@ export function createAgentTool(subagents, context = {}) {
         callIndex,
         ...(params.description === undefined ? {} : { label: params.description }),
         ...(context.onEvent === undefined ? {} : { emit: context.onEvent }),
+        // Summed, not replaced: a turn can delegate a dozen times and the run
+        // owns all of it. Lives on the run budget so router attempts share it.
+        recordUsage: (spent) => {
+          budget.usage.costUsd += spent.costUsd;
+          budget.usage.input += spent.input;
+          budget.usage.output += spent.output;
+          budget.usage.cacheRead += spent.cacheRead;
+          budget.usage.cacheWrite += spent.cacheWrite;
+        },
       });
       collector.started();
       const startedAt = Date.now();
@@ -326,6 +404,12 @@ export function createAgentTool(subagents, context = {}) {
           // Inherited, never widened: a profile cannot loosen confinement.
           ...(context.sandboxPolicy === undefined ? {} : { sandboxPolicy: context.sandboxPolicy }),
           ...(context.sandboxEngine === undefined ? {} : { sandboxEngine: context.sandboxEngine }),
+          // The parent's disclosed skills. Offered, not imposed — the host's
+          // `run` decides whether this child may have them, since only it knows
+          // the child's resolved route and deny lists.
+          ...(context.skills === undefined ? {} : { skills: context.skills }),
+          ...(context.skillsRoot === undefined ? {} : { skillsRoot: context.skillsRoot }),
+          ...(context.toolEnvironment === undefined ? {} : { toolEnvironment: context.toolEnvironment }),
           abortSignal: controller.signal,
           maxTurns,
           callId: toolCallId,
@@ -518,13 +602,15 @@ const WIRE_CONTENT_MAX_CHARS = 2_000;
  * answer body, so forwarding them would splice a subagent's prose into the
  * main agent's reply. Its text reaches the parent through the tool result.
  *
- * @param {{callId: string, profileName: string, callIndex: number, label?: string, emit?: (event: *) => void}} options
+ * @param {{callId: string, profileName: string, callIndex: number, label?: string, emit?: (event: *) => void, recordUsage?: (usage: {costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}) => void}} options
  */
-function createActivityCollector({ callId, profileName, callIndex, label, emit }) {
+function createActivityCollector({ callId, profileName, callIndex, label, emit, recordUsage }) {
   /** @type {Map<string, {name: string, args: unknown, startedAt: number, ms?: number}>} */
   const open = new Map();
   /** @type {Array<{name: string, args: unknown, ms?: number, isError: boolean}>} */
   const done = [];
+  /** What the child reported spending, so the parent run can own it. */
+  const usage = emptyUsage();
   const subagent = { id: callId, name: profileName, callIndex, ...(label === undefined ? {} : { label }) };
 
   /** @param {*} event */
@@ -550,10 +636,17 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit }
     },
     /** @param {{status: string, durationMs: number}} outcome */
     finished({ status, durationMs }) {
+      // Before the bookend, so the run's own usage report can already include
+      // it, and so an abandoned child still hands over whatever it spent.
+      recordUsage?.(usage);
       publish({
         phase: "agent_completed",
         id: `agent:${callId}`,
         name: `Agent(${profileName})`,
+        // The one place the child's price is knowable per delegation: operator
+        // surfaces show it on the row so an expensive one is identifiable, not
+        // just visible in the run total it disappears into.
+        ...(usage.costUsd > 0 ? { subagent: { ...subagent, costUsd: usage.costUsd } } : {}),
         isError: status !== "ok",
         executionMs: durationMs,
         content: `${status} · ${done.length} tool call${done.length === 1 ? "" : "s"}`,
@@ -618,8 +711,25 @@ function createActivityCollector({ callId, profileName, callIndex, label, emit }
         }
         return;
       }
+      if (type === "cost_accumulated") {
+        // Read as a running total, not a delta — the same rule
+        // `ai/observer.js` applies to the parent's own events, because a bridge
+        // emits one of these per completed provider run carrying that run's
+        // totals. Keeping one rule means a child that failed over undercounts
+        // exactly as its parent does today rather than inventing a second.
+        // Not republished on the parent stream: consumers treat `usage_update`
+        // as the run's cumulative figure, and a child's smaller total arriving
+        // last would read as the run getting cheaper.
+        const tokens = event.tokens && typeof event.tokens === "object" ? event.tokens : {};
+        usage.costUsd = numberOrZero(event.cumulativeUsd);
+        usage.input = numberOrZero(tokens.input);
+        usage.output = numberOrZero(tokens.output);
+        usage.cacheRead = numberOrZero(tokens.cacheReadTokens);
+        usage.cacheWrite = numberOrZero(tokens.cacheCreationTokens);
+        return;
+      }
       // Child warnings are worth surfacing; everything else (context usage,
-      // partial tool output, cost) stays inside the subagent for now.
+      // partial tool output) stays inside the subagent for now.
       if (type === "runtime_warning" && emit !== undefined) {
         try {
           emit({ ...event, subagentId: callId });

package/src/agent/tools/bash.js

@@ -15,7 +15,7 @@ import {
   runPreparedProcess,
 } from "./shared/process-runner.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
-import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_BASH_TIMEOUT_MS = 120_000;
 const BASH_STARTUP_ENV_KEYS = new Set([
@@ -120,7 +120,7 @@ export async function bashToolRun(
         command: "/bin/bash",
         args: ["--noprofile", "--norc", "-c", command],
         cwd,
-        env: cleanBashEnvironment(),
+        env: requestToolProcessEnvironment(resolvedCtx, cleanBashEnvironment()),
       },
     });
   } catch (error) {

package/src/agent/tools/exec.js

@@ -16,7 +16,7 @@ import {
   runPreparedProcess,
 } from "./shared/process-runner.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
-import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { requestToolProcessEnvironment, resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const DEFAULT_EXEC_TIMEOUT_MS = 120_000;
 const MAX_EXEC_ARGS = 256;
@@ -75,6 +75,7 @@ export async function execToolRun(
   const maxChars = positiveInteger(max_output_chars, DEFAULT_MAX_BASH_OUTPUT_CHARS);
   let prepared;
   try {
+    const requestEnvironment = requestToolProcessEnvironment(resolvedCtx);
     prepared = await sandbox.prepareCommand({
       policy,
       engine: sandboxEngine ?? resolvedCtx.sandboxEngine ?? undefined,
@@ -82,6 +83,7 @@ export async function execToolRun(
         command: executable,
         args: [...args],
         cwd,
+        ...(requestEnvironment === undefined ? {} : { env: requestEnvironment }),
       },
     });
   } catch (error) {

package/src/agent/tools/shared/tool-context.js

@@ -38,6 +38,8 @@
 
 // @ts-check
 
+import { delimiter } from "node:path";
+
 import { passthroughSandbox } from "../../sandbox-seam.js";
 import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-brand.js";
 
@@ -58,6 +60,7 @@ import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-bra
  * @property {RuntimeSandboxEngine} [sandboxEngine]
  * @property {RuntimeSandbox} sandbox
  * @property {RuntimeBrand} runtimeBrand
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment]
  */
 
 // The data keys (everything except the always-resolved runtimeBrand). A fixed
@@ -155,3 +158,22 @@ export function resolveSandboxPolicy(ctx, requestPolicy = undefined) {
   const merged = sandbox.mergePolicies(ctx?.sandboxPolicy ?? undefined, requestPolicy ?? undefined);
   return merged && merged.mode !== "off" ? merged : undefined;
 }
+
+/**
+ * Compose the process environment overlay for Bash/Exec. The caller-supplied
+ * base carries each tool's own hardening values; request values are applied
+ * only at this final process boundary. No global environment is mutated.
+ *
+ * @param {ToolContext|undefined} ctx
+ * @param {Record<string, string|undefined>} [base]
+ * @returns {Record<string, string|undefined>|undefined}
+ */
+export function requestToolProcessEnvironment(ctx, base = undefined) {
+  const request = ctx?.toolEnvironment;
+  if (request === undefined) return base;
+  const env = { ...(base ?? {}), ...request.values };
+  if (Array.isArray(request.pathPrepend) && request.pathPrepend.length > 0) {
+    env.PATH = [...request.pathPrepend, process.env.PATH].filter(Boolean).join(delimiter);
+  }
+  return env;
+}

package/src/ai/pi-interop.js

@@ -3,7 +3,7 @@
 // directly so the runtime's known-good Pi version remains authoritative.
 
 import { getBuiltinModel, getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
-import { getOAuthApiKey, getOAuthProvider } from "@earendil-works/pi-ai/oauth";
+import { getPiOAuthAuth, resolveOAuthApiKey, toAuthInteraction } from "./pi-oauth-compat.js";
 import { reasoningLevelsForPiModel as resolveReasoningLevels } from "./providers/pi-models.js";
 
 /**
@@ -122,7 +122,7 @@ export function reasoningLevelsForPiModel(model) {
  * @returns {Promise<{apiKey: string, newCredentials: PiOAuthCredentialsSnapshot}|null>}
  */
 export async function resolvePiOAuthApiKey(providerId, credentials) {
-  const result = await getOAuthApiKey(
+  const result = await resolveOAuthApiKey(
     providerId,
     /** @type {any} */ (cloneInteropValue(credentials)),
   );
@@ -142,8 +142,8 @@ export async function resolvePiOAuthApiKey(providerId, credentials) {
  * @returns {Promise<PiOAuthCredentialsSnapshot>}
  */
 export async function loginPiOAuth(providerId, callbacks) {
-  const provider = getOAuthProvider(providerId);
-  if (!provider || typeof provider.login !== "function") {
+  const oauth = getPiOAuthAuth(providerId);
+  if (!oauth || typeof oauth.login !== "function") {
     throw new Error(`Pi OAuth provider is unavailable: ${providerId}`);
   }
   for (const callbackName of ["onAuth", "onDeviceCode", "onPrompt", "onSelect"]) {
@@ -151,6 +151,8 @@ export async function loginPiOAuth(providerId, callbacks) {
       throw new TypeError(`loginPiOAuth requires callbacks.${callbackName}()`);
     }
   }
-  const credentials = await provider.login(/** @type {any} */ ({ ...callbacks }));
+  const credentials = await oauth.login(
+    toAuthInteraction(/** @type {any} */ ({ ...callbacks })),
+  );
   return cloneInteropValue(credentials);
 }

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

@@ -0,0 +1,193 @@
+// @ts-check
+
+// Adapter over pi-ai's provider-owned OAuth surface.
+//
+// pi-ai 0.83.0 removed the generic OAuth registry — `getOAuthApiKey`,
+// `getOAuthProvider` and `getOAuthProviders` are gone, and the
+// `@earendil-works/pi-ai/oauth` entry point is now type-only (`export {}` at
+// runtime). The per-provider implementations (`anthropicOAuth`, …) live under
+// `dist/auth/oauth/*`, which has no entry in the package's `exports` map, so
+// 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
+// needs a lookup by id — this module rebuilds that over `builtinProviders()` and
+// preserves the old call contracts exactly, keeping the migration confined here.
+//
+// Deliberately NOT using `createModels({credentials})`: that hands credential
+// locking and persistence to pi, while mono-agent already owns `auth.json`
+// through `pi-auth.js` (serialized writes, atomic 0600 rename). `refresh()` and
+// `toAuth()` are callable directly, so the pure caller-persists contract stays.
+
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+
+/**
+ * @typedef {import("@earendil-works/pi-ai").OAuthAuth} OAuthAuth
+ * @typedef {import("@earendil-works/pi-ai").OAuthCredential} OAuthCredential
+ * @typedef {import("@earendil-works/pi-ai").AuthInteraction} AuthInteraction
+ * @typedef {import("@earendil-works/pi-ai").AuthPrompt} AuthPrompt
+ * @typedef {import("@earendil-works/pi-ai").AuthEvent} AuthEvent
+ * @typedef {import("@earendil-works/pi-ai/oauth").OAuthLoginCallbacks} OAuthLoginCallbacks
+ */
+
+/** @type {Map<string, import("@earendil-works/pi-ai").Provider>|undefined} */
+let providerIndexCache;
+
+/**
+ * `builtinProviders()` freshly constructs every provider (~37 objects) on each
+ * call, and `pi-auth.js` sits on the per-request credential path. The catalog is
+ * static for the process lifetime, so index it once.
+ *
+ * @returns {Map<string, import("@earendil-works/pi-ai").Provider>}
+ */
+function providerIndex() {
+  if (providerIndexCache === undefined) {
+    providerIndexCache = new Map(builtinProviders().map((provider) => [provider.id, provider]));
+  }
+  return providerIndexCache;
+}
+
+/** @internal Exported only so tests can force a rebuild of the memoized index. */
+export function resetPiProviderIndexForTests() {
+  providerIndexCache = undefined;
+}
+
+/**
+ * The OAuth implementation for a Pi provider id, or undefined when the provider
+ * is unknown or supports only API-key auth (e.g. `opencode-go`).
+ *
+ * @param {string} providerId
+ * @returns {OAuthAuth|undefined}
+ */
+export function getPiOAuthAuth(providerId) {
+  if (typeof providerId !== "string" || providerId.length === 0) return undefined;
+  return providerIndex().get(providerId)?.auth?.oauth;
+}
+
+/**
+ * Every Pi provider id that supports OAuth. Replaces
+ * `getOAuthProviders().map((provider) => provider.id)`.
+ *
+ * @returns {string[]}
+ */
+export function getPiOAuthProviderIds() {
+  const ids = [];
+  for (const [id, provider] of providerIndex()) {
+    if (provider.auth?.oauth !== undefined) ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Resolve an API key from stored OAuth credentials, refreshing first when the
+ * token has expired.
+ *
+ * Reproduces pi-ai 0.80.6's `getOAuthApiKey(providerId, credentials)` contract
+ * so its call sites keep their shape: takes the whole provider-keyed credential
+ * map, returns `null` when this provider has no stored credential, and is
+ * *pure* — the refreshed credential comes back as `newCredentials` for the
+ * caller to persist rather than being written here.
+ *
+ * The refresh trigger is deliberately the old exact-expiry check. pi's own
+ * `Models.getAuth()` refreshes five minutes ahead of expiry; matching that would
+ * change live token rotation timing, which this migration does not intend.
+ *
+ * @param {string} providerId
+ * @param {Record<string, *>|undefined} credentials Provider-keyed credential map.
+ * @returns {Promise<{newCredentials: OAuthCredential, apiKey: string|undefined}|null>}
+ */
+export async function resolveOAuthApiKey(providerId, credentials) {
+  const oauth = getPiOAuthAuth(providerId);
+  if (oauth === undefined) {
+    throw new Error(`Unknown OAuth provider: ${providerId}`);
+  }
+
+  const stored = credentials?.[providerId];
+  if (stored === undefined || stored === null) return null;
+
+  // 0.83.0's OAuthCredential carries a `type: "oauth"` discriminant that the
+  // 0.80.6 shape did not. Stored entries written by mono-agent already have it;
+  // tag defensively so hand-edited or externally written files still work.
+  let credential = /** @type {OAuthCredential} */ ({ ...stored, type: "oauth" });
+
+  if (Date.now() >= credential.expires) {
+    try {
+      credential = await oauth.refresh(credential);
+    } catch {
+      throw new Error(`Failed to refresh OAuth token for ${providerId}`);
+    }
+  }
+
+  // `toAuth()` also derives a per-credential baseUrl (GitHub Copilot's
+  // per-account proxy). 0.80.6 discarded it and callers here have no field for
+  // it, so it stays dropped — behaviour preserved, worth revisiting separately.
+  const auth = await oauth.toAuth(credential);
+  return { newCredentials: credential, apiKey: auth?.apiKey };
+}
+
+/**
+ * Bridge the legacy six-callback OAuth surface onto 0.83.0's single
+ * `prompt`/`notify` pair.
+ *
+ * `manual_code` must stay wired to `onManualCodeInput`: Anthropic races its
+ * localhost callback against a pasted redirect URL, and that path is the reason
+ * `agent-app`'s `runPiOAuthLogin` exists at all.
+ *
+ * @param {OAuthLoginCallbacks} callbacks
+ * @returns {AuthInteraction}
+ */
+export function toAuthInteraction(callbacks) {
+  if (callbacks === null || typeof callbacks !== "object") {
+    throw new TypeError("toAuthInteraction requires an OAuthLoginCallbacks object");
+  }
+
+  return {
+    ...(callbacks.signal === undefined ? {} : { signal: callbacks.signal }),
+
+    /** @param {AuthPrompt} prompt */
+    async prompt(prompt) {
+      if (prompt.type === "select") {
+        const selected = await callbacks.onSelect({
+          message: prompt.message,
+          options: prompt.options.map((option) => ({ id: option.id, label: option.label })),
+        });
+        // The legacy callback resolves undefined when the user cancels; the new
+        // contract requires a string and rejects on cancel.
+        if (typeof selected !== "string") {
+          throw new Error("OAuth provider selection was cancelled.");
+        }
+        return selected;
+      }
+
+      if (prompt.type === "manual_code" && typeof callbacks.onManualCodeInput === "function") {
+        return await callbacks.onManualCodeInput();
+      }
+
+      return await callbacks.onPrompt({
+        message: prompt.message,
+        ...(prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder }),
+      });
+    },
+
+    /** @param {AuthEvent} event */
+    notify(event) {
+      if (event.type === "auth_url") {
+        callbacks.onAuth({
+          url: event.url,
+          ...(event.instructions === undefined ? {} : { instructions: event.instructions }),
+        });
+        return;
+      }
+      if (event.type === "device_code") {
+        callbacks.onDeviceCode({
+          userCode: event.userCode,
+          verificationUri: event.verificationUri,
+          ...(event.intervalSeconds === undefined ? {} : { intervalSeconds: event.intervalSeconds }),
+          ...(event.expiresInSeconds === undefined ? {} : { expiresInSeconds: event.expiresInSeconds }),
+        });
+        return;
+      }
+      callbacks.onProgress?.(event.message);
+    },
+  };
+}