@mono-agent/agent-runtime 0.15.4 → 0.16.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,27 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.15.x baseline
+## 0.16.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.
+below. It 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 +328,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 +394,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.15.x` package contract. Keep
+This guide describes the published `0.16.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 +415,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.16.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,12 +93,21 @@ 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}`;
 }
 
 /**
@@ -125,6 +134,27 @@ function budgetForRun(subagents, parentRunId) {
   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;
+}
+
 /** @param {*} value @param {number} fallback @returns {number} */
 function positiveInt(value, fallback) {
   return Number.isInteger(value) && value > 0 ? value : fallback;
@@ -134,7 +164,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, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents, context = {}) {
@@ -326,6 +356,11 @@ 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 }),
           abortSignal: controller.signal,
           maxTurns,
           callId: toolCallId,

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

package/src/ai/providers/pi-native/turn-runner.js

@@ -8,7 +8,6 @@
 // caller-owned runState.
 
 import { AgentHarness } from "@earendil-works/pi-agent-core";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import {
   createStructuredOutputTool,
   getPiBuiltinTools,
@@ -134,6 +133,14 @@ export async function buildTurnTools(runState, {
         // child is never less sandboxed than the parent that spawned it.
         sandboxPolicy: options.sandboxPolicy,
         sandboxEngine,
+        // The same skills this turn was disclosed. A child runs OUTSIDE the
+        // harness, so without this it gets no index and — because ReadSkill is
+        // only built when `skills` is non-empty — no way to read one either. It
+        // then rediscovers by trial and error whatever its parent could simply
+        // have looked up. Pass-through only: whether the child actually receives
+        // them is the host's decision, not this layer's.
+        skills: options.skills,
+        skillsRoot: options.skillsRoot,
       },
       ctx: runCtx,
     }));
@@ -241,7 +248,6 @@ export function toolResultErrorOverride(details) {
 }
 
 export function buildTurnHarness(runState, {
-  cwd,
   session,
   piModels,
   model,
@@ -259,8 +265,12 @@ export function buildTurnHarness(runState, {
   sdk,
   reference,
 }) {
+  // pi-agent-core 0.83.0 removed `env` from AgentHarnessOptions: an
+  // ExecutionEnv now reaches tools through the generic per-turn `toolContext`
+  // instead. mono-agent needs neither — it uses none of pi's built-in
+  // file/shell tools, and its own tools close over what they need — so the
+  // option is dropped rather than migrated.
   const harness = new AgentHarness({
-    env: new NodeExecutionEnv({ cwd: cwd || process.cwd() }),
     session,
     models: piModels,
     model,

package/src/ai/providers/pi-native.js

@@ -31,7 +31,9 @@ import {
   resolveAgentCompactionPolicy,
   resolveRuntimePolicyInputs,
 } from "../../agent/compaction.js";
+import { subagentInvocationCount } from "../../agent/tools/agent-tool.js";
 import { closePiMcpClients } from "../../agent/tools/pi-bridge.js";
+import { readToolRuntime } from "../../agent/tools/shared/runtime-context.js";
 import { createApprovalManager } from "../../agent/approval.js";
 import { buildCapabilitiesUsed, toolCompactionAppliedFromWarnings } from "../runtime/capabilities-used.js";
 import { reasoningLevelsForPiModel, resolvePiRuntimeModel } from "./pi-models.js";
@@ -481,7 +483,6 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // external abort handler (which sets runState.externalAbort and aborts the
     // harness). Sets runState.harness + runState.removeAbortHandler.
     harness = buildTurnHarness(runState, {
-      cwd: options.cwd,
       session: runState.session,
       piModels,
       model: runtime.model,
@@ -709,8 +710,23 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       promptCacheActive: usage.cacheRead > 0 || usage.cacheWrite > 0,
       thinkingEnabled: effectiveThinkingLevel !== "off" && effectiveThinkingLevel !== "low",
       structuredOutputEnforced: !!options.outputSchema,
-      subagentInvoked: false,
+      // What actually happened, not what was configured. This used to be a
+      // hardcoded `false`, which reported "no subagent ran" for runs that had
+      // just spawned several — the one signal that would have shown delegation
+      // working said it never happened.
+      //
+      // The count is keyed by the same parentRunId the Agent tool stamps its
+      // budget under (turn-runner threads `runCtx?.runId`); `runId` survives the
+      // sandbox-branch spread there, so reading it off the tool context directly
+      // yields the same key.
+      subagentInvoked: subagentInvocationCount(
+        options.subagents,
+        (options.toolContext ?? readToolRuntime())?.runId,
+      ) > 0,
       mcpServersUsed: mcpClients.map((entry) => entry?.name).filter(Boolean),
+      // Empty by contract, not by omission: "native" means provider-native
+      // subagents (Claude's Task tool). mono-agent's `Agent` is its own, so pi
+      // has none — `subagent_invoked` above is where pi delegation is reported.
       nativeSubagentsUsed: [],
       toolCompactionApplied: toolCompactionAppliedFromWarnings(runtimeWarnings),
       // Tristate: true = a compaction fired this run (proactive or reactive),

package/src/ai/runtime/router.js

@@ -335,11 +335,16 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
           // A same-model retry is not a failover: only the first attempt of a new
           // route announces a transition.
           if (retryIndex === 0 && failoverHistory.length > 0) {
+            const previous = failoverHistory[failoverHistory.length - 1];
             emit(callOptions, {
               type: "provider_failover_started",
-              from: modelKey(failoverHistory[failoverHistory.length - 1]?.model),
+              from: modelKey(previous?.model),
               to: modelKey(entry.model),
               attemptIndex: i,
+              // Why the route changed, in the same vocabulary provider_retry_started
+              // uses. Operators reading a transcript need the cause next to the
+              // transition, not only in the run artifact's failoverHistory.
+              reason: previous?.retryableSubkind || previous?.failureKind || null,
             });
           }
 
@@ -378,9 +383,12 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
             // (failover)" when X is still the route the operator asked for.
             if (failoverHistory.some((attempt) => modelKey(attempt.model) !== modelKey(entry.model))) {
               emit(callOptions, {
+                // modelKey, not the ModelRef: every consumer of this event reads
+                // `model` as a string (responder.ts's stringField is string-only),
+                // so an object here is dropped silently rather than rendered.
                 type: "provider_failover_completed",
                 attemptIndex: i,
-                model: entry.model,
+                model: modelKey(entry.model),
               });
             }
             return { ...result, failoverHistory, routeSafetyHistory };

package/src/ai/types.js

@@ -147,7 +147,8 @@
  * @property {boolean} [fastMode]
  * @property {string} [cwd]
  * @property {Object<string, Object>} [mcpServers]
- * @property {ReadonlyArray<Object>} [skills]             Runtime skill metadata for progressive disclosure.
+ * @property {ReadonlyArray<{name: string, description?: string}>} [skills] Skills disclosed to this run, as `{name, description}`. Non-empty makes `supports_skills` a routing requirement (see router.js), so a chain entry that lacks it is skipped.
+ * @property {string} [skillsRoot]                       Directory holding `<name>/SKILL.md`. Required alongside `skills` for `ReadSkill` to be built.
  * @property {ReadonlyArray<string>} [allowedTools]
  * @property {ReadonlyArray<string>} [disallowedTools]
  * @property {string} [permissionMode]

package/src/pi-auth.js

@@ -4,7 +4,7 @@ import { realpathSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 
-import { getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
+import { resolveOAuthApiKey } from "./ai/pi-oauth-compat.js";
 
 /**
  * @typedef {{type: "api_key", key?: string, env?: Object<string, *>}} PiApiKeyCredential
@@ -41,7 +41,7 @@ export function createPiOAuthApiKeyResolver(options = {}) {
         return undefined;
       }
 
-      const result = await getOAuthApiKey(provider, cloneAuth(auth));
+      const result = await resolveOAuthApiKey(provider, cloneAuth(auth));
       if (result === null || result === undefined || typeof result.apiKey !== "string" || result.apiKey.length === 0) {
         return undefined;
       }

package/src/runtime.js

@@ -165,6 +165,13 @@ export function createRuntime(host = {}) {
     // WebSearch, so even a read-only profile could bypass network policy.
     ...(request.sandboxPolicy === undefined ? {} : { sandboxPolicy: request.sandboxPolicy }),
     ...(request.sandboxEngine === undefined ? {} : { sandboxEngine: request.sandboxEngine }),
+    // The parent's disclosed skills, for the same reason: they are a per-run
+    // option, so a child that does not receive them has no ReadSkill tool and no
+    // index, and must rediscover by trial and error what its parent could look
+    // up. A host-supplied `run` may gate this; the default has no route or deny
+    // list of its own to consult, so it forwards what it was given.
+    ...(request.skills === undefined ? {} : { skills: request.skills }),
+    ...(request.skillsRoot === undefined ? {} : { skillsRoot: request.skillsRoot }),
     ...(request.executionMode === undefined ? {} : { executionMode: request.executionMode }),
     ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
     // A profile that pins effort — declared or authored at call time — means it

package/types/agent/tools/agent-tool.d.ts

@@ -1,8 +1,23 @@
+/**
+ * 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: any, parentRunId: string | undefined): number;
 /**
  * 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, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents: RuntimeSubagentsOptions | null | undefined, context?: {
@@ -12,6 +27,11 @@ export function createAgentTool(subagents: RuntimeSubagentsOptions | null | unde
     parentRunId?: string;
     sandboxPolicy?: any;
     sandboxEngine?: any;
+    skills?: {
+        name: string;
+        description?: string;
+    }[];
+    skillsRoot?: string;
     onEvent?: (event: any) => void;
 }): any | null;
 /**

package/types/ai/pi-oauth-compat.d.ts

@@ -0,0 +1,57 @@
+/** @internal Exported only so tests can force a rebuild of the memoized index. */
+export function resetPiProviderIndexForTests(): void;
+/**
+ * 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: string): OAuthAuth | undefined;
+/**
+ * Every Pi provider id that supports OAuth. Replaces
+ * `getOAuthProviders().map((provider) => provider.id)`.
+ *
+ * @returns {string[]}
+ */
+export function getPiOAuthProviderIds(): string[];
+/**
+ * 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 function resolveOAuthApiKey(providerId: string, credentials: Record<string, any> | undefined): Promise<{
+    newCredentials: OAuthCredential;
+    apiKey: string | undefined;
+} | null>;
+/**
+ * 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: OAuthLoginCallbacks): AuthInteraction;
+export type OAuthAuth = import("@earendil-works/pi-ai").OAuthAuth;
+export type OAuthCredential = import("@earendil-works/pi-ai").OAuthCredential;
+export type AuthInteraction = import("@earendil-works/pi-ai").AuthInteraction;
+export type AuthPrompt = import("@earendil-works/pi-ai").AuthPrompt;
+export type AuthEvent = import("@earendil-works/pi-ai").AuthEvent;
+export type OAuthLoginCallbacks = import("@earendil-works/pi-ai/oauth").OAuthLoginCallbacks;

package/types/ai/providers/pi-native/turn-runner.d.ts

@@ -45,8 +45,7 @@ export function thinkingLevelForEffort(effort: string, capabilities: any): strin
 export function toolResultErrorOverride(details: any): {
     isError: true;
 } | undefined;
-export function buildTurnHarness(runState: any, { cwd, session, piModels, model, thinkingLevel, systemPrompt, outputSchema, tools, transport, maxRetries, maxRetryDelayMs, steeringMode, onEvent, options, toolLimits, sdk, reference, }: {
-    cwd: any;
+export function buildTurnHarness(runState: any, { session, piModels, model, thinkingLevel, systemPrompt, outputSchema, tools, transport, maxRetries, maxRetryDelayMs, steeringMode, onEvent, options, toolLimits, sdk, reference, }: {
     session: any;
     piModels: any;
     model: any;
@@ -63,7 +62,7 @@ export function buildTurnHarness(runState: any, { cwd, session, piModels, model,
     toolLimits: any;
     sdk: any;
     reference: any;
-}): AgentHarness<import("@earendil-works/pi-agent-core").Skill, import("@earendil-works/pi-agent-core").PromptTemplate, import("@earendil-works/pi-agent-core").AgentTool<import("@earendil-works/pi-ai").TSchema, any>>;
+}): AgentHarness<undefined, import("@earendil-works/pi-agent-core").Skill, import("@earendil-works/pi-agent-core").PromptTemplate, import("@earendil-works/pi-agent-core").AgentHarnessTool<undefined>>;
 /**
  * Start the live-input steering consumer. Consumes follow-up messages and steers
  * the harness mid-run; the consumer is tied to run completion (an internal

package/types/ai/types.d.ts

@@ -118,7 +118,8 @@
  * @property {boolean} [fastMode]
  * @property {string} [cwd]
  * @property {Object<string, Object>} [mcpServers]
- * @property {ReadonlyArray<Object>} [skills]             Runtime skill metadata for progressive disclosure.
+ * @property {ReadonlyArray<{name: string, description?: string}>} [skills] Skills disclosed to this run, as `{name, description}`. Non-empty makes `supports_skills` a routing requirement (see router.js), so a chain entry that lacks it is skipped.
+ * @property {string} [skillsRoot]                       Directory holding `<name>/SKILL.md`. Required alongside `skills` for `ReadSkill` to be built.
  * @property {ReadonlyArray<string>} [allowedTools]
  * @property {ReadonlyArray<string>} [disallowedTools]
  * @property {string} [permissionMode]
@@ -578,9 +579,16 @@ export type RuntimeRunOptions = {
         [x: string]: any;
     };
     /**
-     * Runtime skill metadata for progressive disclosure.
+     * Skills disclosed to this run, as `{name, description}`. Non-empty makes `supports_skills` a routing requirement (see router.js), so a chain entry that lacks it is skipped.
      */
-    skills?: ReadonlyArray<any>;
+    skills?: ReadonlyArray<{
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * Directory holding `<name>/SKILL.md`. Required alongside `skills` for `ReadSkill` to be built.
+     */
+    skillsRoot?: string;
     allowedTools?: ReadonlyArray<string>;
     disallowedTools?: ReadonlyArray<string>;
     permissionMode?: string;

package/types/ai/backend.d.ts

@@ -1,57 +0,0 @@
-export function backendCapabilities(sdkOrModel: any): any;
-export function backendUsesExecenvConfig(sdk: any): boolean;
-export function backendSupportsSessionResume(sdk: any): boolean;
-export const BACKEND_CAPABILITIES: {
-    claude: {
-        supports_session_resume: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-    pi: {
-        supports_session_resume: boolean;
-        supports_native_subagents: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-    codex: {
-        supports_session_resume: boolean;
-        supports_fast_mode: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        runtime: string;
-    };
-    opencode: {
-        structured_output: boolean;
-        supports_session_resume: boolean;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        streaming: boolean;
-        native_runtime_config: any;
-        supports_builtin_tools: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-};

package/types/ai/registry.d.ts

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