@mono-agent/agent-runtime 0.11.2 → 0.11.4

package/MIGRATION.md

@@ -190,35 +190,49 @@ 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.x`** (were `^0.79.1`). Compaction is driven natively (section 3).
+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.
 
 ## 11. Exports map: wildcards removed (explicit deep-path map)
 
 The package's `./ai/*` and `./agent/*` **wildcard exports were replaced by an
-explicit `exports` map**: 3 barrels (`.`, `./ai`, `./agent`) plus **21 named deep
-`.js` subpaths**, each carrying its own generated `types` condition. A deep import
-that is not on the map **no longer resolves** — a wildcard used to silently
-resolve anything under `src/`, so a moved/renamed/mistyped subpath is now a loud
-failure (guarded by `scripts/verify-deep-imports.mjs`).
-
-The 21 supported deep paths:
-
-```
-./ai/failure.js                         ./agent/tools/index.js
-./ai/cost.js                            ./agent/tools/shared/runtime-context.js
-./ai/backend.js                         ./agent/tools/shared/ripgrep.js
-./ai/runtime/model-refs.js              ./agent/prompt/skill-index.js
-./ai/runtime/registry.js                ./agent/allowlists.js
-./ai/runtime/context-windows.js         ./agent/transcript.js
-./ai/runtime/fast-mode.js               ./agent/compaction.js
-./ai/streaming/codex-events.js
-./ai/live-input-prompt.js
-./ai/file-change-stats.js
-./ai/providers/claude-sdk.js
-./ai/providers/claude-cli.js
-./ai/providers/codex-app.js
-./ai/providers/opencode-discovery.js
+explicit `exports` map**: 3 barrels (`.`, `./ai`, `./agent`) plus the generated
+deep-path inventory below, with every entry carrying its own `types` condition.
+A deep import that is not on the map **no longer resolves** — a wildcard used to
+silently resolve anything under `src/`, so a moved/renamed/mistyped subpath is
+now a loud failure (guarded by `scripts/verify-deep-imports.mjs`).
+
+<!-- public-api-js-subpaths:start -->
+<!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
+
+The package exposes **22 named deep `.js` subpaths**:
+
+```text
+@mono-agent/agent-runtime/agent/allowlists.js
+@mono-agent/agent-runtime/agent/compaction.js
+@mono-agent/agent-runtime/agent/prompt/skill-index.js
+@mono-agent/agent-runtime/agent/tools/index.js
+@mono-agent/agent-runtime/agent/tools/shared/ripgrep.js
+@mono-agent/agent-runtime/agent/tools/shared/runtime-context.js
+@mono-agent/agent-runtime/agent/transcript.js
+@mono-agent/agent-runtime/ai/backend.js
+@mono-agent/agent-runtime/ai/cost.js
+@mono-agent/agent-runtime/ai/failure.js
+@mono-agent/agent-runtime/ai/file-change-stats.js
+@mono-agent/agent-runtime/ai/live-input-prompt.js
+@mono-agent/agent-runtime/ai/providers/claude-cli.js
+@mono-agent/agent-runtime/ai/providers/claude-sdk-discovery.js
+@mono-agent/agent-runtime/ai/providers/claude-sdk.js
+@mono-agent/agent-runtime/ai/providers/codex-app.js
+@mono-agent/agent-runtime/ai/providers/opencode-discovery.js
+@mono-agent/agent-runtime/ai/runtime/context-windows.js
+@mono-agent/agent-runtime/ai/runtime/fast-mode.js
+@mono-agent/agent-runtime/ai/runtime/model-refs.js
+@mono-agent/agent-runtime/ai/runtime/registry.js
+@mono-agent/agent-runtime/ai/streaming/codex-events.js
 ```
+<!-- public-api-js-subpaths:end -->
 
 **Action:** if you deep-import a subpath not in this list, switch to the closest
 supported one, a barrel (`./ai` / `./agent`), or the public runtime registry.
@@ -254,9 +268,9 @@ Run these before/at the port:
    in `src/`.)*
 2. **Dependencies.** Post-decoupling the kernel has **zero workspace-package
    deps**; only the third-party pins need aligning: `@earendil-works/pi-ai` +
-   `@earendil-works/pi-agent-core` (`^0.80.x`), `@modelcontextprotocol/sdk`,
+   `@earendil-works/pi-agent-core` (`0.80.6`), `@modelcontextprotocol/sdk`,
    `@opencode-ai/sdk`, `@anthropic-ai/claude-agent-sdk`, `zod`.
-3. **Pi bump `^0.74.0` → `^0.80.x` in lockstep.** worklab tests that use old pi
+3. **Pi bump `^0.74.0` → `0.80.6` in lockstep.** worklab tests that use old pi
    APIs are rewritten at the port. Do not restore the old `pi-sdk.js` deep
    import; use `generatePiNativeResponse` from `@mono-agent/agent-runtime/ai`.
 4. **Sandbox.** worklab passes **no** `sandbox` implementation → `passthroughSandbox`,

package/README.md

@@ -10,14 +10,397 @@ Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Op
 
 ## Public API
 
-- `createRuntime` — runtime factory dispatching to the backend bridges
-- `ai/runtime/model-refs.js` — `parseRuntimeModelReference`, `executionModeIncompatibilityReason`
-- `ai/runtime/registry.js` — `listRuntimeBridges`
-- `ai/providers/claude-sdk-discovery.js` — isolated Claude SDK model discovery without importing ambient auth/config
-- `createRouterRuntime({ chain, routeSafety, resolveAttempt })` — ordered fallback routing with exact route effort and bounded safety/failover telemetry
-- Provider bridges for `claude` (SDK + CLI), `codex` (app-server), `pi` (Pi SDK), and `opencode`
-- Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes best-effort disposal, strict cold-refresh, exact-id durable retirement, invalidation, and whole-runtime shutdown operations
-- Sandbox-aware built-in tools and stdio MCP startup through an injectable `RuntimeSandbox` seam (`agent/sandbox-seam.js`) — no direct dependency on `@mono-agent/runtime-adapter`
+<!-- public-api-inventory:start -->
+<!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
+
+Every symbol exported by each public code entrypoint is listed below.
+
+**`@mono-agent/agent-runtime`**
+
+```text
+ACTIVE_RUNTIME_KINDS
+ALLOWLIST_MODE_ALL
+ALLOWLIST_MODE_CUSTOM
+APPROVAL_DECISIONS
+BINARY_BLOAT_TOOLS
+BridgeSpec
+CLAUDE_SDK_CATALOG_VERSION
+DEFAULT_RUNTIME_BRAND
+DEFAULT_TOOL_BLOAT_CONFIG
+MAX_TOOL_RESULT_BYTES
+RESERVED_RUNTIME_KINDS
+RISK_TIERS
+RUNTIME_CAPABILITIES
+RuntimeBridge
+RuntimeBridgeDescriptor
+RuntimeBridgeId
+RuntimeModelRef
+UNKNOWN_CAPABILITY
+buildCapabilitiesUsed
+buildTranscriptTailSnapshot
+canonicalizeLegacyModelReference
+configureToolRuntime
+createApprovalManager
+createClaudeSdkDiscoveryIsolation
+createMetricsObserver
+createObserverHub
+createPiOAuthApiKeyResolver
+createRouterRuntime
+createRuntime
+createSessionRegistry
+curatedClaudeSdkModels
+discoverClaudeSdkModels
+disposeAllProviderSessions
+disposeProviderSession
+executionModeIncompatibilityReason
+findProviderForModel
+generatePiNativeResponse
+inferAllowlistMode
+invalidateProviderSession
+isLikelyContextTermination
+isModelCompatibleWithExecutionMode
+listProviders
+listRuntimeBridges
+normalizeAllowlistMode
+normalizeClaudeSdkCatalog
+normalizeClaudeSdkModelId
+normalizeList
+normalizeRuntimeModelReference
+parseRuntimeModelReference
+parseStoredAllowlist
+piNativeRuntimeBridge
+readRuntimeBrand
+readToolRuntime
+refreshProviderSession
+renderResumeSnapshot
+resetToolRuntime
+resolveAgentCompactionPolicy
+resolveAllowlist
+resolveAllowlistMap
+resolveRuntimeBrand
+resolveRuntimeBridge
+runtimeCapabilities
+sdkFromModelReference
+storedAllowlistMode
+syncProviderSession
+toolCompactionAppliedFromWarnings
+wrapToolsWithApprovalGate
+```
+
+**`@mono-agent/agent-runtime/agent`**
+
+```text
+ALLOWLIST_MODE_ALL
+ALLOWLIST_MODE_CUSTOM
+APPROVAL_DECISIONS
+BINARY_BLOAT_TOOLS
+DEFAULT_TOOL_BLOAT_CONFIG
+MAX_TOOL_RESULT_BYTES
+RISK_TIERS
+buildTranscriptTailSnapshot
+createApprovalManager
+inferAllowlistMode
+isLikelyContextTermination
+normalizeAllowlistMode
+normalizeList
+parseStoredAllowlist
+renderResumeSnapshot
+resolveAgentCompactionPolicy
+resolveAllowlist
+resolveAllowlistMap
+storedAllowlistMode
+wrapToolsWithApprovalGate
+```
+
+**`@mono-agent/agent-runtime/agent/allowlists.js`**
+
+```text
+ALLOWLIST_MODE_ALL
+ALLOWLIST_MODE_CUSTOM
+inferAllowlistMode
+normalizeAllowlistMode
+normalizeList
+parseStoredAllowlist
+resolveAllowlist
+resolveAllowlistMap
+storedAllowlistMode
+```
+
+**`@mono-agent/agent-runtime/agent/compaction.js`**
+
+```text
+AgentCompactionPolicy
+DEPRECATED_SETTINGS_WARNING_KIND
+deprecatedSettingsWarning
+estimateFixedOverheadTokens
+isLikelyContextTermination
+resolveAgentCompactionPolicy
+resolveRuntimePolicyInputs
+```
+
+**`@mono-agent/agent-runtime/agent/prompt/skill-index.js`**
+
+```text
+buildSkillIndex
+buildSkillPathNote
+formatSkillBodyWithPathNote
+getSkillAccessDirs
+inferSkillsRoot
+```
+
+**`@mono-agent/agent-runtime/agent/tools/index.js`**
+
+```text
+bashToolImpl
+editToolImpl
+globToolImpl
+grepToolImpl
+isPathAllowed
+isWorkdirAllowed
+normalizeBashTimeoutMs
+readToolImpl
+resolveRgPath
+webFetchToolImpl
+webSearchToolImpl
+writeToolImpl
+```
+
+**`@mono-agent/agent-runtime/agent/tools/shared/ripgrep.js`**
+
+```text
+cachedRgPath
+capLines
+excludedGlobArgs
+excludedPathSummary
+formatSearchLines
+normalizeGlobPattern
+resolveRgPath
+ripgrepMissingMessage
+```
+
+**`@mono-agent/agent-runtime/agent/tools/shared/runtime-context.js`**
+
+```text
+ToolContext
+ToolRuntimeContext
+configureToolRuntime
+readRuntimeBrand
+readToolRuntime
+resetToolRuntime
+resolveSandboxPolicy
+```
+
+**`@mono-agent/agent-runtime/agent/transcript.js`**
+
+```text
+RESUME_SNAPSHOT_DEFAULTS
+buildTranscriptTailSnapshot
+renderResumeSnapshot
+```
+
+**`@mono-agent/agent-runtime/ai`**
+
+```text
+ACTIVE_RUNTIME_KINDS
+BridgeSpec
+CLAUDE_SDK_CATALOG_VERSION
+RESERVED_RUNTIME_KINDS
+RUNTIME_CAPABILITIES
+RuntimeBridge
+RuntimeBridgeDescriptor
+RuntimeBridgeId
+RuntimeModelRef
+UNKNOWN_CAPABILITY
+buildCapabilitiesUsed
+canonicalizeLegacyModelReference
+createClaudeSdkDiscoveryIsolation
+createMetricsObserver
+createObserverHub
+createSessionRegistry
+curatedClaudeSdkModels
+discoverClaudeSdkModels
+disposeAllProviderSessions
+disposeProviderSession
+executionModeIncompatibilityReason
+findProviderForModel
+generatePiNativeResponse
+invalidateProviderSession
+isModelCompatibleWithExecutionMode
+listProviders
+listRuntimeBridges
+normalizeClaudeSdkCatalog
+normalizeClaudeSdkModelId
+normalizeRuntimeModelReference
+parseRuntimeModelReference
+piNativeRuntimeBridge
+refreshProviderSession
+resolveRuntimeBridge
+runtimeCapabilities
+sdkFromModelReference
+syncProviderSession
+toolCompactionAppliedFromWarnings
+```
+
+**`@mono-agent/agent-runtime/ai/backend.js`**
+
+```text
+BACKEND_CAPABILITIES
+backendCapabilities
+backendSupportsSessionResume
+backendUsesExecenvConfig
+```
+
+**`@mono-agent/agent-runtime/ai/cost.js`**
+
+```text
+NormalizedPricing
+ParsedModelReference
+PricingInputRow
+estimateCost
+isPrivateHost
+normalizePricing
+parseReference
+pricingHasRates
+resolvePricing
+unknownPricing
+zeroPricing
+```
+
+**`@mono-agent/agent-runtime/ai/failure.js`**
+
+```text
+FAILURE_KINDS
+FailureKind
+PROVIDER_ABORT_RE
+RetryableProviderFailureInfo
+classifyFailure
+createStderrTail
+isProviderAuthFailureText
+retryableProviderFailureInfo
+```
+
+**`@mono-agent/agent-runtime/ai/file-change-stats.js`**
+
+```text
+createFileChangePayload
+fileChangeSummary
+readFileChangeSnapshot
+statsForCompletedChange
+```
+
+**`@mono-agent/agent-runtime/ai/live-input-prompt.js`**
+
+```text
+formatLiveInputGuidance
+```
+
+**`@mono-agent/agent-runtime/ai/providers/claude-cli.js`**
+
+```text
+buildCliCommand
+claudeCodeBackend
+claudeCodeRuntimeBridge
+codexCliBackend
+createThinkingBuffer
+generateCliResponse
+normalizeCliEvent
+```
+
+**`@mono-agent/agent-runtime/ai/providers/claude-sdk-discovery.js`**
+
+```text
+CLAUDE_SDK_CATALOG_VERSION
+ClaudeSdkCatalogModel
+ClaudeSdkEffort
+createClaudeSdkDiscoveryIsolation
+curatedClaudeSdkModels
+discoverClaudeSdkModels
+normalizeClaudeSdkCatalog
+normalizeClaudeSdkModelId
+```
+
+**`@mono-agent/agent-runtime/ai/providers/claude-sdk.js`**
+
+```text
+claudeEffortOptions
+claudeRuntimeBridge
+claudeSdkBackend
+claudeSdkModelForQuery
+generateClaudeResponse
+toolPayloadLimit
+```
+
+**`@mono-agent/agent-runtime/ai/providers/codex-app.js`**
+
+```text
+codexAppBackend
+codexAppRuntimeBridge
+createCodexAppServerClient
+generateCodexAppResponse
+```
+
+**`@mono-agent/agent-runtime/ai/providers/opencode-discovery.js`**
+
+```text
+discoverOpencodeProviders
+```
+
+**`@mono-agent/agent-runtime/ai/runtime/context-windows.js`**
+
+```text
+CLAUDE_ONE_MILLION_CONTEXT_MODELS
+DEFAULT_CONTEXT_WINDOW
+ONE_MILLION_CONTEXT_WINDOW
+claudeModelSupportsContextWindow
+claudeModelSupportsOneMillionContext
+hasExplicitOneMillionContextWindow
+modelWithContextWindow
+normalizeContextWindow
+stripContextWindowSuffix
+```
+
+**`@mono-agent/agent-runtime/ai/runtime/fast-mode.js`**
+
+```text
+codexModelSupportsFastMode
+normalizeFastMode
+```
+
+**`@mono-agent/agent-runtime/ai/runtime/model-refs.js`**
+
+```text
+ACTIVE_RUNTIME_KINDS
+RESERVED_RUNTIME_KINDS
+RuntimeModelRef
+canonicalizeLegacyModelReference
+executionModeIncompatibilityReason
+isModelCompatibleWithExecutionMode
+normalizeRuntimeModelReference
+parseRuntimeModelReference
+sdkFromModelReference
+```
+
+**`@mono-agent/agent-runtime/ai/runtime/registry.js`**
+
+```text
+BridgeSpec
+RUNTIME_CAPABILITIES
+RuntimeBridge
+RuntimeBridgeDescriptor
+RuntimeBridgeId
+listRuntimeBridges
+resolveRuntimeBridge
+runtimeCapabilities
+```
+
+**`@mono-agent/agent-runtime/ai/streaming/codex-events.js`**
+
+```text
+normalizeCodexItemEvent
+normalizeCodexItemType
+```
+
+<!-- public-api-inventory:end -->
 
 ## Dependency Boundary
 

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robertsreberski/mono-agent.git",
+    "directory": "packages/agent-runtime"
+  },
   "keywords": [
     "ai",
     "agents",
@@ -132,8 +137,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.206",
     "@anthropic-ai/sdk": "^0.110.0",
-    "@earendil-works/pi-agent-core": "^0.80.5",
-    "@earendil-works/pi-ai": "^0.80.5",
+    "@earendil-works/pi-agent-core": "0.80.6",
+    "@earendil-works/pi-ai": "0.80.6",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opencode-ai/sdk": "^1.15.13",
     "@vscode/ripgrep": "1.18.0",

package/src/agent/index.js

@@ -1,8 +1,7 @@
-// Public surface of the agent kernel. The kernel is consumed by the
-// worker, the assistant, the Slack triage path, and the coordinator's
-// run-spawn path. Everything below is intentionally re-exported; anything
-// not listed here is private to the kernel and should not be imported
-// from edge layers.
+// Public agent-kernel barrel for runtime hosts. Everything below is
+// intentionally re-exported through `@mono-agent/agent-runtime/agent`;
+// agent modules not exposed by the package's exports map remain private
+// implementation details.
 
 export {
   isLikelyContextTermination,

package/src/ai/cost.js

@@ -4,6 +4,7 @@
 // deprecated/compat-only). `getBuiltinModel(provider, id)` from `providers/all`
 // is the non-deprecated replacement with the same signature and the same
 // undefined-on-miss behavior the pricing lookup below relies on.
+import { calculateCost as calculatePiCost } from "@earendil-works/pi-ai";
 import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/all";
 
 /**
@@ -192,9 +193,9 @@ function pricingHasRates(pricing = {}) {
  *   - sdk "claude": looked up under pi's "anthropic" provider (its models carry
  *     `cost`), so pi's live rates win over the static CLAUDE_PRICING fallback.
  * @param {ParsedModelReference|null|undefined} parsed
- * @returns {NormalizedPricing|null}
+ * @returns {import("@earendil-works/pi-ai").Model<any>|null}
  */
-function piCatalogPricing(parsed) {
+function piCatalogModel(parsed) {
   if (!parsed?.model) return null;
   let provider;
   if (parsed.sdk === "pi" && parsed.provider) provider = parsed.provider;
@@ -204,13 +205,21 @@ function piCatalogPricing(parsed) {
     // `provider` may be a caller-supplied id (custom providers included), wider
     // than pi-ai's built-in KnownProvider catalog union; the catalog lookup
     // itself is the runtime check, guarded by the catch below.
-    const model = getPiModel(/** @type {*} */ (provider), parsed.model);
-    return model?.cost ? normalizePricing(model.cost, { source: "pi-catalog" }) : null;
+    return getPiModel(/** @type {*} */ (provider), parsed.model) || null;
   } catch {
     return null;
   }
 }
 
+/**
+ * @param {ParsedModelReference|null|undefined} parsed
+ * @returns {NormalizedPricing|null}
+ */
+function piCatalogPricing(parsed) {
+  const model = piCatalogModel(parsed);
+  return model?.cost ? normalizePricing(model.cost, { source: "pi-catalog" }) : null;
+}
+
 /**
  * @param {ParsedModelReference|null|undefined} parsed
  * @returns {NormalizedPricing|null}
@@ -244,6 +253,19 @@ export function resolvePricing({ resolveCustomPricing, model } = {}) {
     || unknownPricing();
 }
 
+/**
+ * @param {any} model
+ * @param {{input: number, output: number, cacheRead: number, cacheWrite: number}} usage
+ * @returns {number}
+ */
+function estimatePiCatalogCost(model, usage) {
+  return calculatePiCost(model, {
+    ...usage,
+    totalTokens: usage.input + usage.output + usage.cacheRead + usage.cacheWrite,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  }).total;
+}
+
 export { normalizePricing, zeroPricing, unknownPricing, pricingHasRates, isPrivateHost, parseReference };
 
 /**
@@ -266,12 +288,22 @@ export function estimateCost({
   cacheWriteTokens = 0,
   cacheCreationTokens = 0,
 } = {}) {
-  const pricing = resolvePricing({ resolveCustomPricing, model });
-  if (!pricing?.priced) return null;
   const cacheRead = Math.max(0, Number(cachedTokens) || 0);
   const cacheWrite = Math.max(0, Number(cacheWriteTokens ?? cacheCreationTokens) || 0);
   const input = Math.max(0, Number(inputTokens) || 0);
   const output = Math.max(0, Number(outputTokens) || 0);
+  const parsed = parseReference(model);
+  const customPricing = parsed && typeof resolveCustomPricing === "function"
+    ? resolveCustomPricing(parsed)
+    : null;
+  const piModel = customPricing ? null : piCatalogModel(parsed);
+  if (piModel?.cost) {
+    return estimatePiCatalogCost(piModel, { input, output, cacheRead, cacheWrite });
+  }
+  const pricing = customPricing
+    || claudePricing(parsed)
+    || unknownPricing();
+  if (!pricing?.priced) return null;
   const parts = [
     [input, pricing.input],
     [cacheRead, pricing.cacheRead],

package/src/ai/providers/claude-sdk.js

@@ -24,8 +24,11 @@ const MAX_CLAUDE_ERROR_CHARS = 2_000;
 
 /**
  * Preserve the provider default when effort is omitted. The current Agent SDK
- * accepts the five values below verbatim; mono-agent must not infer thinking
- * enablement/disablement from a requested effort level.
+ * public effort contract accepts the five values below. Its shipped JavaScript
+ * currently forwards out-of-contract values to Claude Code, so mono-agent keeps
+ * this route inside the pinned public contract rather than relying on that
+ * untyped pass-through. Mono-agent must not infer thinking enablement/disablement
+ * from a requested effort level.
  * @param {unknown} effort
  * @returns {{effort?: "low" | "medium" | "high" | "xhigh" | "max"}}
  */
@@ -34,12 +37,12 @@ export function claudeEffortOptions(effort) {
   const normalized = String(effort).trim();
   if (normalized === "none") {
     throw new Error(
-      'Claude Agent SDK does not support effort "none". Omit effort to use the provider default, or choose low, medium, high, xhigh, or max.',
+      'Mono-agent\'s Claude SDK route does not support effort "none": the pinned Claude Agent SDK public effort contract starts at "low". Omit effort to use the provider default, or choose low, medium, high, xhigh, or max.',
     );
   }
   if (!CLAUDE_EFFORT_LEVELS.has(normalized)) {
     throw new Error(
-      `Claude Agent SDK does not support effort "${boundedText(normalized, 64)}". Choose low, medium, high, xhigh, or max, or omit effort.`,
+      `Mono-agent's Claude SDK route does not support effort "${boundedText(normalized, 64)}": the pinned Claude Agent SDK public effort contract ends at "max". Choose low, medium, high, xhigh, or max, or omit effort.`,
     );
   }
   return { effort: /** @type {"low" | "medium" | "high" | "xhigh" | "max"} */ (normalized) };

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

@@ -2,6 +2,7 @@
 // deprecated/compat-only. `getBuiltinModel(provider, id)` from `providers/all`
 // is the non-deprecated replacement — same 2-arg signature, and it returns
 // `undefined` on an unknown provider/model exactly like the old `getModel`.
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/all";
 import { readRuntimeBrand } from "../../agent/tools/shared/runtime-context.js";
 
@@ -42,6 +43,18 @@ function customCompat(capabilities, isPrivate) {
   };
 }
 
+/**
+ * Translate Pi's model-native thinking levels to mono-agent's public effort
+ * spelling. Pi calls the disabled level `off`; mono-agent calls it `none`.
+ * Keeping this derived from the model lets new native levels (such as `max`)
+ * flow through without maintaining a second hard-coded catalog.
+ * @param {any} model
+ * @returns {string[]}
+ */
+export function reasoningLevelsForPiModel(model) {
+  return getSupportedThinkingLevels(model).map((level) => level === "off" ? "none" : level);
+}
+
 // Build the pi-runtime view of a custom provider/model from
 // pre-resolved primitives. The caller (core/ai.js#generateResponse) reads
 // the provider/model rows and computes the capabilities + isPrivate flag
@@ -118,7 +131,7 @@ export function resolvePiRuntimeModel(resolved, options) {
       tool_use: true,
       reasoning: !!model.reasoning,
       reasoning_mode: model.reasoning ? "effort" : "none",
-      reasoning_levels: model.reasoning ? ["none", "low", "medium", "high", "xhigh"] : undefined,
+      reasoning_levels: model.reasoning ? reasoningLevelsForPiModel(model) : undefined,
       reasoning_disable_supported: true,
       vision: Array.isArray(model.input) ? model.input.includes("image") : false,
       json_mode: true,

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

@@ -94,9 +94,9 @@ export function emitCapabilitiesResolved(onEvent, { sdk, model, capabilitiesUsed
 
 /**
  * The aborted-run result (entry pre-check / pre-request abort). Pure factory.
- * @param {{resolved: any, options: any, events: any[], runtimeWarnings: any[], start: number, providerSessionId: string}} params
+ * @param {{resolved: any, options: any, events: any[], runtimeWarnings: any[], start: number, providerSessionId: string, piTransport: string}} params
  */
-export function abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId }) {
+export function abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId, piTransport }) {
   return {
     text: null,
     thinking: "",
@@ -116,6 +116,7 @@ export function abortedResult({ resolved, options, events, runtimeWarnings, star
       provider_session_id: providerSessionId,
       pi_stop_reason: "aborted",
       pi_engine: "native",
+      pi_transport_requested: piTransport,
       external_abort: true,
     },
   };
@@ -201,6 +202,7 @@ export function buildErrorResult(params) {
     providerSessionId,
     runtimeWarnings,
     isRetryable,
+    piTransport,
   } = params;
   return {
     text: assistantTexts.join("") || null,
@@ -221,6 +223,7 @@ export function buildErrorResult(params) {
       max_turns_hit: maxTurnsHit,
       provider_session_id: providerSessionId,
       pi_engine: "native",
+      pi_transport_requested: piTransport,
       pi_error_retryable: isRetryable,
     },
     failureKind: externalAbort ? null : failureKindForPiError(errorMessage, {}, { maxTurnsHit }),
@@ -230,6 +233,7 @@ export function buildErrorResult(params) {
       provider_session_id: providerSessionId,
       pi_stop_reason: externalAbort ? "aborted" : "error",
       pi_engine: "native",
+      pi_transport_requested: piTransport,
       max_turns_hit: maxTurnsHit,
       turn_count: turnCount,
       external_abort: externalAbort,
@@ -252,6 +256,7 @@ export function buildDiagnostics(params) {
     runAssistantCount,
     externalAbort,
     maxRetries,
+    piTransport,
     lastToolName,
     structuredRetry,
     contextCompactionDiagnostics,
@@ -265,6 +270,7 @@ export function buildDiagnostics(params) {
     turn_count: turnCount || runAssistantCount,
     external_abort: externalAbort,
     pi_max_retries: maxRetries,
+    pi_transport_requested: piTransport,
     ...(lastToolName ? { last_tool_name: lastToolName } : {}),
     ...structuredOutputRetryDiagnostics(
       structuredRetry.attempts,

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

@@ -177,6 +177,7 @@ function sessionUnavailableResult({
   errorMessage,
   failureKind,
   piErrorCode,
+  piTransport,
 }) {
   return {
     text: null,
@@ -196,6 +197,7 @@ function sessionUnavailableResult({
       provider_session_id: sessionId,
       pi_error_code: piErrorCode,
       pi_engine: "native",
+      pi_transport_requested: piTransport,
     },
   };
 }
@@ -221,6 +223,7 @@ export async function resolveSession(runState, {
   events,
   runtimeWarnings,
   start,
+  piTransport,
 }) {
   // Resume check first: a session miss must stay cheap (no tool/MCP/harness
   // init). This mirrors the legacy bridge's fail-fast contract.
@@ -307,6 +310,7 @@ export async function resolveSession(runState, {
             errorMessage: `Pi session ${requestedSessionId} is not live`,
             failureKind: "session_not_found",
             piErrorCode: "pi_session_not_found",
+            piTransport,
           }),
         };
       }
@@ -344,6 +348,7 @@ export async function resolveSession(runState, {
               : `Pi session ${requestedSessionId} is busy with another turn`,
             failureKind: missing ? "session_not_found" : "session_busy",
             piErrorCode: missing ? "pi_session_not_found" : "pi_session_busy",
+            piTransport,
           }),
         };
       }

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

@@ -0,0 +1,16 @@
+// @ts-check
+
+const PI_TRANSPORTS = new Set(["auto", "sse", "websocket", "websocket-cached"]);
+
+/**
+ * Normalize the public runtime option at the untyped JS boundary. Typed/config
+ * callers already validate it; direct JavaScript callers fail safely to Pi's
+ * compatibility-preserving automatic transport selection.
+ * @param {unknown} value
+ * @returns {"auto" | "sse" | "websocket" | "websocket-cached"}
+ */
+export function resolvePiTransport(value) {
+  return typeof value === "string" && PI_TRANSPORTS.has(value)
+    ? /** @type {"auto" | "sse" | "websocket" | "websocket-cached"} */ (value)
+    : "auto";
+}

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

@@ -147,10 +147,19 @@ export async function buildTurnTools(runState, {
 export function thinkingLevelForEffort(effort, capabilities) {
   if (!capabilities?.reasoning || capabilities.reasoning_mode === "none") return "off";
   if (effort === "none") return "off";
-  if (effort === "max") return "xhigh";
+  // Pi <0.80.6 and older/custom model metadata do not advertise native max.
+  // Preserve the historical xhigh ceiling for those models, but pass max
+  // through when the resolved model explicitly declares it.
+  if (effort === "max") {
+    return Array.isArray(capabilities.reasoning_levels)
+      && capabilities.reasoning_levels.includes("max")
+      ? "max"
+      : "xhigh";
+  }
   if (effort === "xhigh") return "xhigh";
   if (effort === "high") return "high";
   if (effort === "medium") return "medium";
+  if (effort === "minimal") return "minimal";
   return "low";
 }
 
@@ -172,6 +181,7 @@ export function buildTurnHarness(runState, {
   systemPrompt,
   outputSchema,
   tools,
+  transport,
   maxRetries,
   maxRetryDelayMs,
   steeringMode,
@@ -187,7 +197,7 @@ export function buildTurnHarness(runState, {
     thinkingLevel,
     systemPrompt: appendStructuredOutputInstruction(systemPrompt, outputSchema, options.prompts),
     tools,
-    streamOptions: { maxRetries, maxRetryDelayMs },
+    streamOptions: { transport, maxRetries, maxRetryDelayMs },
     steeringMode,
     followUpMode: steeringMode,
   });

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

@@ -34,7 +34,7 @@ import {
 import { closePiMcpClients } from "../../agent/tools/pi-bridge.js";
 import { createApprovalManager } from "../../agent/approval.js";
 import { buildCapabilitiesUsed, toolCompactionAppliedFromWarnings } from "../runtime/capabilities-used.js";
-import { resolvePiRuntimeModel } from "./pi-models.js";
+import { reasoningLevelsForPiModel, resolvePiRuntimeModel } from "./pi-models.js";
 import {
   textFromContent,
   thinkingFromContent,
@@ -76,6 +76,7 @@ import {
   startLiveInput,
   thinkingLevelForEffort,
 } from "./pi-native/turn-runner.js";
+import { resolvePiTransport } from "./pi-native/transport.js";
 
 async function resolveApiKey(provider, { apiKeys, resolvePiApiKey, runtimeWarnings }) {
   if (apiKeys?.has(provider)) return apiKeys.get(provider);
@@ -302,6 +303,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
   let structuredOutputFinalizationRetryAttempts = 0;
   let structuredOutputFinalizationRetryReason = null;
   let structuredOutputFinalizationRetryFailed = false;
+  const piTransport = resolvePiTransport(options.piTransport);
 
   const onEvent = (event) => emitCaptured(events, options.onEvent, event);
   const approvalManager = options.onToolApprovalRequest
@@ -316,7 +318,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     : null;
 
   if (options.abortSignal?.aborted) {
-    return abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId });
+    return abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId, piTransport });
   }
 
   const durableRepo = resolveDurableNativeSessionRepo(options.piSessionsRoot);
@@ -341,6 +343,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       events,
       runtimeWarnings,
       start,
+      piTransport,
     });
     if (resolvedSession.done) return resolvedSession.result;
 
@@ -355,6 +358,9 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
           tool_use: true,
           reasoning: !!options.piResolvedModel.reasoning,
           reasoning_mode: options.piResolvedModel.reasoning ? "effort" : "none",
+          reasoning_levels: options.piResolvedModel.reasoning
+            ? reasoningLevelsForPiModel(options.piResolvedModel)
+            : undefined,
           json_mode: true,
         },
         apiKeys: new Map(),
@@ -432,6 +438,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       systemPrompt,
       outputSchema: options.outputSchema,
       tools,
+      transport: piTransport,
       maxRetries,
       maxRetryDelayMs,
       steeringMode: toolSteeringMode,
@@ -484,7 +491,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       // and closes MCP clients. For a resume no transcript was appended yet
       // (prompt never ran), so the live session needs no rollback.
       await discardUncommittedSession(runState, { durableRepo });
-      return abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId });
+      return abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId, piTransport });
     }
 
     // Compaction policy against the LIVE model's context window, then proactive
@@ -619,6 +626,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       runAssistantCount,
       externalAbort: runState.externalAbort,
       maxRetries,
+      piTransport,
       lastToolName: runState.lastToolName,
       structuredRetry,
       contextCompactionDiagnostics: runState.compaction.diagnostics,
@@ -737,6 +745,7 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       providerSessionId,
       runtimeWarnings,
       isRetryable,
+      piTransport,
     });
   } finally {
     if (runState.sessionEntry) runState.sessionEntry.busy = false;

package/types/ai/providers/claude-sdk.d.ts

@@ -1,7 +1,10 @@
 /**
  * Preserve the provider default when effort is omitted. The current Agent SDK
- * accepts the five values below verbatim; mono-agent must not infer thinking
- * enablement/disablement from a requested effort level.
+ * public effort contract accepts the five values below. Its shipped JavaScript
+ * currently forwards out-of-contract values to Claude Code, so mono-agent keeps
+ * this route inside the pinned public contract rather than relying on that
+ * untyped pass-through. Mono-agent must not infer thinking enablement/disablement
+ * from a requested effort level.
  * @param {unknown} effort
  * @returns {{effort?: "low" | "medium" | "high" | "xhigh" | "max"}}
  */

package/types/ai/providers/pi-models.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Translate Pi's model-native thinking levels to mono-agent's public effort
+ * spelling. Pi calls the disabled level `off`; mono-agent calls it `none`.
+ * Keeping this derived from the model lets new native levels (such as `max`)
+ * flow through without maintaining a second hard-coded catalog.
+ * @param {any} model
+ * @returns {string[]}
+ */
+export function reasoningLevelsForPiModel(model: any): string[];
 export function resolvePiRuntimeModel(resolved: any, options: any): {
     model: {
         id: any;

package/types/ai/providers/pi-native/result-builder.d.ts

@@ -53,15 +53,16 @@ export function emitCapabilitiesResolved(onEvent: (event: any) => void, { sdk, m
 }): void;
 /**
  * The aborted-run result (entry pre-check / pre-request abort). Pure factory.
- * @param {{resolved: any, options: any, events: any[], runtimeWarnings: any[], start: number, providerSessionId: string}} params
+ * @param {{resolved: any, options: any, events: any[], runtimeWarnings: any[], start: number, providerSessionId: string, piTransport: string}} params
  */
-export function abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId }: {
+export function abortedResult({ resolved, options, events, runtimeWarnings, start, providerSessionId, piTransport }: {
     resolved: any;
     options: any;
     events: any[];
     runtimeWarnings: any[];
     start: number;
     providerSessionId: string;
+    piTransport: string;
 }): {
     text: any;
     thinking: string;
@@ -81,6 +82,7 @@ export function abortedResult({ resolved, options, events, runtimeWarnings, star
         provider_session_id: string;
         pi_stop_reason: string;
         pi_engine: string;
+        pi_transport_requested: string;
         external_abort: boolean;
     };
 };
@@ -140,6 +142,7 @@ export function buildErrorResult(params: object): {
         max_turns_hit: any;
         provider_session_id: any;
         pi_engine: string;
+        pi_transport_requested: any;
         pi_error_retryable: any;
     };
     failureKind: string;
@@ -149,6 +152,7 @@ export function buildErrorResult(params: object): {
         provider_session_id: any;
         pi_stop_reason: string;
         pi_engine: string;
+        pi_transport_requested: any;
         max_turns_hit: any;
         turn_count: any;
         external_abort: any;

package/types/ai/providers/pi-native/session-lifecycle.d.ts

@@ -17,7 +17,7 @@ export function retireDurableNativeSession(providerSessionId: any, piSessionsRoo
  * @param {any} params
  * @returns {Promise<{done: true, result: any} | {done: false}>}
  */
-export function resolveSession(runState: any, { requestedSessionId, providerSessionId, durableRepo, sessionTtlMs, cwd, resolved, options, events, runtimeWarnings, start, }: any): Promise<{
+export function resolveSession(runState: any, { requestedSessionId, providerSessionId, durableRepo, sessionTtlMs, cwd, resolved, options, events, runtimeWarnings, start, piTransport, }: any): Promise<{
     done: true;
     result: any;
 } | {

package/types/ai/providers/pi-native/transport.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalize the public runtime option at the untyped JS boundary. Typed/config
+ * callers already validate it; direct JavaScript callers fail safely to Pi's
+ * compatibility-preserving automatic transport selection.
+ * @param {unknown} value
+ * @returns {"auto" | "sse" | "websocket" | "websocket-cached"}
+ */
+export function resolvePiTransport(value: unknown): "auto" | "sse" | "websocket" | "websocket-cached";

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

@@ -30,7 +30,7 @@ export function thinkingLevelForEffort(effort: string, capabilities: any): strin
  * @param {any} params
  * @returns {any}
  */
-export function buildTurnHarness(runState: any, { cwd, session, piModels, model, thinkingLevel, systemPrompt, outputSchema, tools, maxRetries, maxRetryDelayMs, steeringMode, onEvent, options, toolLimits, }: any): any;
+export function buildTurnHarness(runState: any, { cwd, session, piModels, model, thinkingLevel, systemPrompt, outputSchema, tools, transport, maxRetries, maxRetryDelayMs, steeringMode, onEvent, options, toolLimits, }: any): any;
 /**
  * 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