@mono-agent/agent-runtime 0.15.4 → 0.17.0

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

@@ -32,6 +32,38 @@ export function usageFromMessages(messages = []) {
   return usage;
 }
 
+/**
+ * Add what this run's subagents spent to the run's own usage.
+ *
+ * A delegation is work the run asked for and is billed to the same account, but
+ * `usageFromMessages` only ever sees this agent's transcript — a subagent keeps
+ * its own — so every consumer of the run's usage was short by the whole cost of
+ * every subagent. Folding it in here rather than publishing a separate event
+ * makes the console's cost, the TUI status bar and the exported metrics correct
+ * with no change at any of them. The trade is attribution: a subagent on
+ * another model has its spend reported under this run's model, which is the
+ * right answer for a run total and the wrong one for a per-model breakdown.
+ *
+ * `estimatedCost` is this agent's own fallback price, used when the provider
+ * priced nothing (subscription auth). Adding to the raw `cost` alone in that
+ * case would have replaced this agent's cost with the subagent's rather than
+ * summing them.
+ *
+ * @param {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}} usage
+ * @param {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} delegated
+ * @param {number} estimatedCost
+ * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}}
+ */
+export function withSubagentUsage(usage, delegated, estimatedCost) {
+  return {
+    input: usage.input + delegated.input,
+    output: usage.output + delegated.output,
+    cacheRead: usage.cacheRead + delegated.cacheRead,
+    cacheWrite: usage.cacheWrite + delegated.cacheWrite,
+    cost: delegated.costUsd > 0 ? (usage.cost || estimatedCost) + delegated.costUsd : usage.cost,
+  };
+}
+
 /**
  * Normalize one provider request's usage into an exact context snapshot.
  * Unlike usageFromMessages(), this deliberately does not aggregate earlier

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,15 @@ 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,
+        toolEnvironment: options.toolEnvironment,
       },
       ctx: runCtx,
     }));
@@ -241,7 +249,6 @@ export function toolResultErrorOverride(details) {
 }
 
 export function buildTurnHarness(runState, {
-  cwd,
   session,
   piModels,
   model,
@@ -259,8 +266,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, subagentUsageForRun } 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";
@@ -55,6 +57,7 @@ import {
   emitCapabilitiesResolved,
   emitUsageCostEvents,
   usageFromMessages,
+  withSubagentUsage,
 } from "./pi-native/result-builder.js";
 import {
   cleanupSessionOnThrow,
@@ -481,7 +484,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,
@@ -645,15 +647,24 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     const { runTranscript, lastAssistant, stopReason, finalText, finalThinking } = state;
     const runAssistantCount = state.assistantMessages.length;
 
-    const usage = usageFromMessages(runTranscript);
+    const ownUsage = usageFromMessages(runTranscript);
+    // Priced from this agent's own tokens: it is the fallback for a run the
+    // provider did not price, and only these tokens are this model's.
     const estimatedCost = estimateCost({
       resolveCustomPricing: options.resolveCustomPricing,
       model: reference,
-      inputTokens: usage.input,
-      outputTokens: usage.output,
-      cachedTokens: usage.cacheRead,
-      cacheWriteTokens: usage.cacheWrite,
+      inputTokens: ownUsage.input,
+      outputTokens: ownUsage.output,
+      cachedTokens: ownUsage.cacheRead,
+      cacheWriteTokens: ownUsage.cacheWrite,
     });
+    // Keyed by the same parentRunId the Agent tool stamps its budget under, the
+    // way `subagentInvoked` below reads its count.
+    const usage = withSubagentUsage(
+      ownUsage,
+      subagentUsageForRun(options.subagents, (options.toolContext ?? readToolRuntime())?.runId),
+      estimatedCost,
+    );
     emitUsageCostEvents({
       onEvent,
       resolved,
@@ -709,8 +720,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/capabilities.js

@@ -13,6 +13,7 @@ export const COMMON_CAPABILITIES = {
   supports_builtin_tools: true,
   supports_live_input: true,
   supports_native_subagents: true,
+  supports_request_tool_environment: false,
   supports_fast_mode: false,
   tool_policy: TOOL_POLICY_PROJECTED,
 };
@@ -34,6 +35,7 @@ export const RUNTIME_CAPABILITIES = {
     // The pi-native bridge does not (yet) wire native subagents / an AskAgent
     // tool, so advertise no support rather than letting callers expect it.
     supports_native_subagents: false,
+    supports_request_tool_environment: true,
   },
   codex: {
     runtime: "cli",

package/src/ai/runtime/router.js

@@ -98,7 +98,7 @@ const RESOLVER_PROTECTED_OPTION_KEYS = new Set([
   "sessionId", "providerSessionId", "sessionKeepAlive", "sessionIdleTimeoutMs",
   "diagnosticsSeed", "systemPromptPrefix", "sandboxPolicy", "sandboxEngine", "sandbox",
   "allowedTools", "disallowedTools", "permissionMode", "mcpServers", "skills",
-  "outputSchema", "nativeSubagents", "liveInput", "fastMode",
+  "outputSchema", "nativeSubagents", "liveInput", "fastMode", "toolEnvironment",
 ]);
 
 /**
@@ -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 };
@@ -1038,6 +1046,9 @@ function entrySatisfiesRequirements(entry, options) {
   if (options.liveInput) {
     effectiveRequires.supports_live_input = true;
   }
+  if (options.toolEnvironment !== undefined) {
+    effectiveRequires.supports_request_tool_environment = true;
+  }
   if (options.fastMode === true) {
     effectiveRequires.supports_fast_mode = true;
   }

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]
@@ -155,6 +156,7 @@
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment] Host-only environment for Bash, Exec, and nested subagents in this run.
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
  * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
  * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
@@ -278,6 +280,7 @@
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
  * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
  *   project named allow/deny policies or accepts only a semantically unrestricted

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,14 @@ 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.toolEnvironment === undefined ? {} : { toolEnvironment: request.toolEnvironment }),
     ...(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
@@ -203,6 +211,12 @@ export function createRuntime(host = {}) {
       });
       const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, hub.emit);
       const prompts = resolvePrompts(host.prompts, options.prompts);
+      // A request-scoped environment must never mutate the long-lived runtime's
+      // shared ToolContext. Clone only for this call, preserving configureTools
+      // updates while keeping credentials isolated between concurrent turns.
+      const runToolContext = options.toolEnvironment === undefined
+        ? toolContext
+        : { ...toolContext, toolEnvironment: options.toolEnvironment };
       // Default the nested-run callback so the Agent built-in is usable without
       // host wiring; the depth field is left exactly as the caller set it, since
       // defaultSubagentRun is what increments it for the child.
@@ -219,7 +233,7 @@ export function createRuntime(host = {}) {
         model: options.model,
         executionMode,
         runtimeBrand,
-        toolContext,
+        toolContext: runToolContext,
         observerHub: hub,
         onEvent: hub.emit,
         ...(liveInput === undefined ? {} : { liveInput }),

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

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

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

@@ -30,6 +30,16 @@ export function resetToolContext(ctx: ToolContext): ToolContext;
  * @returns {SandboxPolicy|undefined}
  */
 export function resolveSandboxPolicy(ctx: ToolContext | undefined, requestPolicy?: SandboxPolicy): SandboxPolicy | 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: ToolContext | undefined, base?: Record<string, string | undefined>): Record<string, string | undefined> | undefined;
 export type RuntimeBrand = import("../../../runtime-brand.js").RuntimeBrand;
 export type SandboxPolicy = import("../../sandbox-seam.js").SandboxPolicy;
 export type RuntimeSandboxEngine = import("../../sandbox-seam.js").RuntimeSandboxEngine;
@@ -45,4 +55,9 @@ export type ToolContext = {
     sandboxEngine?: RuntimeSandboxEngine;
     sandbox: RuntimeSandbox;
     runtimeBrand: RuntimeBrand;
+    toolEnvironment?: {
+        schema: 1;
+        values: Readonly<Record<string, string>>;
+        pathPrepend?: readonly string[];
+    };
 };

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/result-builder.d.ts

@@ -10,6 +10,47 @@ export function usageFromMessages(messages?: Array<any>): {
     cacheWrite: number;
     cost: number;
 };
+/**
+ * Add what this run's subagents spent to the run's own usage.
+ *
+ * A delegation is work the run asked for and is billed to the same account, but
+ * `usageFromMessages` only ever sees this agent's transcript — a subagent keeps
+ * its own — so every consumer of the run's usage was short by the whole cost of
+ * every subagent. Folding it in here rather than publishing a separate event
+ * makes the console's cost, the TUI status bar and the exported metrics correct
+ * with no change at any of them. The trade is attribution: a subagent on
+ * another model has its spend reported under this run's model, which is the
+ * right answer for a run total and the wrong one for a per-model breakdown.
+ *
+ * `estimatedCost` is this agent's own fallback price, used when the provider
+ * priced nothing (subscription auth). Adding to the raw `cost` alone in that
+ * case would have replaced this agent's cost with the subagent's rather than
+ * summing them.
+ *
+ * @param {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}} usage
+ * @param {{costUsd: number, input: number, output: number, cacheRead: number, cacheWrite: number}} delegated
+ * @param {number} estimatedCost
+ * @returns {{input: number, output: number, cacheRead: number, cacheWrite: number, cost: number}}
+ */
+export function withSubagentUsage(usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}, delegated: {
+    costUsd: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}, estimatedCost: number): {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+};
 /**
  * Normalize one provider request's usage into an exact context snapshot.
  * Unlike usageFromMessages(), this deliberately does not aggregate earlier

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/runtime/capabilities.d.ts

@@ -9,6 +9,7 @@ export namespace COMMON_CAPABILITIES {
     export let supports_builtin_tools: boolean;
     export let supports_live_input: boolean;
     export let supports_native_subagents: boolean;
+    export let supports_request_tool_environment: boolean;
     export let supports_fast_mode: boolean;
     export { TOOL_POLICY_PROJECTED as tool_policy };
 }
@@ -23,6 +24,8 @@ export namespace RUNTIME_CAPABILITIES {
         export { supports_session_resume_2 as supports_session_resume };
         let supports_native_subagents_1: boolean;
         export { supports_native_subagents_1 as supports_native_subagents };
+        let supports_request_tool_environment_1: boolean;
+        export { supports_request_tool_environment_1 as supports_request_tool_environment };
         let runtime_1: string;
         export { runtime_1 as runtime };
     }

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]
@@ -126,6 +127,7 @@
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
+ * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment] Host-only environment for Bash, Exec, and nested subagents in this run.
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
  * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
  * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
@@ -242,6 +244,7 @@
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
  * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
  *   project named allow/deny policies or accepts only a semantically unrestricted
@@ -578,9 +581,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;
@@ -588,6 +598,14 @@ export type RuntimeRunOptions = {
     outputSchema?: any;
     runArtifactDir?: string;
     abortSignal?: AbortSignal;
+    /**
+     * Host-only environment for Bash, Exec, and nested subagents in this run.
+     */
+    toolEnvironment?: {
+        schema: 1;
+        values: Readonly<Record<string, string>>;
+        pathPrepend?: readonly string[];
+    };
     /**
      * Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
      */
@@ -829,6 +847,7 @@ export type RuntimeCapabilities = {
     supports_builtin_tools?: boolean;
     supports_live_input?: boolean;
     supports_native_subagents?: boolean;
+    supports_request_tool_environment?: boolean;
     supports_fast_mode?: boolean;
     /**
      * Whether the bridge can