@mono-agent/agent-runtime 0.20.6 → 0.20.8

package/MIGRATION.md

@@ -74,8 +74,8 @@ the configuration schema.
   `@earendil-works/pi-ai` only for catalog, reasoning, or OAuth behavior should
   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.83.0`; the façade returns cloned model and credential
+  `@mono-agent/agent-runtime/ai`. The runtime exact-pins Pi AI at `0.84.3` and Pi Agent Core 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
@@ -165,7 +165,7 @@ This baseline carries the whole 0.15.x contract forward and adds:
   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.
+- Pi AI 0.84.3 with Pi Agent Core 0.83.0.
 
 ## 0.15.x
 
@@ -422,12 +422,18 @@ key-resolution contract is unchanged**: an `apiKeys` map entry wins, else the ho
 falls back to its own env vars, exactly as returning `undefined` from the old hook
 did). **No host action needed** — `resolvePiApiKey` behaves as before.
 
-Dependency bump: **`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core` are
-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
+Dependency bump: **`@earendil-works/pi-ai` is now `0.84.3`; `@earendil-works/pi-agent-core` remains `0.83.0`**
+(the initial Pi 0.80 migration landed at `0.80.5`, from `^0.79.1`, ran at
+`0.80.6` until the 0.83 upgrade, and then at `0.83.0`). Agent Core 0.84.3 is
+held back because its replacement durable harness does not yet implement the
+prompt, subscription, compaction, or abort paths used here. Compaction is driven
 natively (section 3), and model-native `max` reasoning plus Pi's request-wide
 pricing tiers are preserved.
 
+Packed npm consumers consequently retain Agent Core's nested Pi AI 0.83.0
+compatibility copy beside the runtime-owned Pi AI 0.84.3 catalog/provider copy.
+The release guard resolves and verifies both exact paths independently.
+
 The 0.83 upgrade carries two upstream removals, both absorbed inside the runtime
 so hosts need no action:
 
@@ -510,15 +516,16 @@ Worklab's runtime fork:
 2. **Remove direct provider ownership.** Delete Worklab production imports from
    `@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.83.0` rather than a floating range. Do not restore the
+   that is complete, isolate the fixture or pin its development-only dependencies
+   to the exact Pi AI `0.84.3` and Pi Agent Core `0.83.0` compatibility pins
+   rather than floating ranges. 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 provider objects and the
-   exact `0.83.0` compatibility pin inside the runtime. OAuth login adapters
+   exact Pi AI `0.84.3` and Pi Agent Core `0.83.0` compatibility pins 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.20.6",
+  "version": "0.20.8",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -139,7 +139,7 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.206",
     "@anthropic-ai/sdk": "^0.110.0",
     "@earendil-works/pi-agent-core": "0.83.0",
-    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-ai": "0.84.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "0.6.0",
     "@opencode-ai/sdk": "^1.15.13",

package/src/agent/tools/bash.js

@@ -82,7 +82,7 @@ export function normalizeBackgroundBashTimeoutMs(value) {
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export async function bashToolImpl(params, options = {}) {
@@ -92,12 +92,13 @@ export async function bashToolImpl(params, options = {}) {
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export async function bashToolRun(
   {
     command,
+    description,
     timeout,
     timeout_ms,
     max_output_chars,
@@ -166,6 +167,7 @@ export async function bashToolRun(
       tool: "Bash",
       prepared,
       summary: `Bash command (${command.length} characters; content redacted)`,
+      description,
       timeoutMs: requestedTimeoutMs,
       maxOutputChars: max_output_chars === undefined ? undefined : maxChars,
       startedAt,

package/src/agent/tools/exec.js

@@ -25,7 +25,7 @@ const MAX_EXEC_ARGS = 256;
 /** @typedef {import("./shared/process-jobs.js").ProcessJobsController} ProcessJobsController */
 
 /**
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export async function execToolImpl(params, options = {}) {
@@ -35,7 +35,7 @@ export async function execToolImpl(params, options = {}) {
 /**
  * Execute an argv vector directly, without shell parsing.
  *
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export async function execToolRun(
@@ -43,6 +43,7 @@ export async function execToolRun(
     executable,
     args = [],
     workdir,
+    description,
     timeout_ms,
     max_output_chars,
     background,
@@ -101,6 +102,7 @@ export async function execToolRun(
       tool: "Exec",
       prepared,
       summary: `Exec command (${args.length} argument${args.length === 1 ? "" : "s"}; values redacted)`,
+      description,
       // Re-derived from the raw param: `timeoutMs` carries the foreground
       // ceiling, and a background job is bounded by processJobs instead.
       timeoutMs: timeout_ms === undefined ? undefined : normalizeBackgroundTimeoutMs(timeout_ms),

package/src/agent/tools/pi-bridge.js

@@ -515,6 +515,10 @@ export function getPiBuiltinTools(allowedTools, {
         : ` This host runs a background job for up to ${formatDurationForModel(backgroundLimitMs)}; \`timeout_ms\` may lower that but never raise it, and the start receipt reports \`max_runtime_ms\`, the budget actually granted — check it, because a job is killed at that limit.`
     }`,
   };
+  const processDescriptionSchema = {
+    type: "string",
+    description: "Short present-participle phrase describing what the command is doing, shown in tool activity and background-job lifecycle messages (for example, \"Running the full repository test suite\"). Always provide this when background=true. Describe the purpose, not command syntax; never include arguments, paths, credentials, or secrets.",
+  };
   // Per-tool closure config (cwd/event sink/limits/policy) plus the per-instance
   // ToolContext `ctx` that the tool impls and shared helpers read from.
   const toolContext = {
@@ -571,7 +575,7 @@ export function getPiBuiltinTools(allowedTools, {
     Bash: createBuiltinTool("Bash", "Bash", "Execute a shell command for pipelines, redirection, conditionals, or other shell syntax. Prefer Exec for one executable with an argv array. This is macOS: do not assume GNU-only commands or flags.", objectSchema({
       command: { type: "string" },
       workdir: { type: "string" },
-      description: { type: "string" },
+      description: processDescriptionSchema,
       timeout_ms: processTimeoutSchema,
       timeout: legacyBashTimeoutSchema,
       max_output_chars: bashLimitSchema,
@@ -581,6 +585,7 @@ export function getPiBuiltinTools(allowedTools, {
       executable: { type: "string", minLength: 1 },
       args: { type: "array", items: { type: "string" }, maxItems: 256 },
       workdir: { type: "string" },
+      description: processDescriptionSchema,
       timeout_ms: processTimeoutSchema,
       max_output_chars: bashLimitSchema,
       ...(processJobsController ? { background: backgroundSchema } : {}),

package/src/agent/tools/shared/process-jobs.js

@@ -13,6 +13,7 @@ import { startPreparedProcess } from "./process-runner.js";
  *   tool: "Exec"|"Bash",
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
+ *   description?: string,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
@@ -28,6 +29,7 @@ import { startPreparedProcess } from "./process-runner.js";
  *   tool: "Exec"|"Bash",
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
+ *   description?: string,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   startedAt: number,
@@ -39,6 +41,7 @@ export async function handOffProcessJob({
   tool,
   prepared,
   summary,
+  description,
   timeoutMs,
   maxOutputChars,
   startedAt,
@@ -52,6 +55,7 @@ export async function handOffProcessJob({
       tool,
       prepared: ownedPrepared,
       summary,
+      ...(description === undefined ? {} : { description }),
       ...(timeoutMs === undefined ? {} : { timeoutMs }),
       ...(maxOutputChars === undefined ? {} : { maxOutputChars }),
       launch(options = {}) {

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

@@ -24,7 +24,7 @@ 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").ProviderAuthInteraction} ProviderAuthInteraction
  * @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
@@ -112,7 +112,10 @@ export async function resolveOAuthApiKey(providerId, credentials) {
 
   if (Date.now() >= credential.expires) {
     try {
-      credential = await oauth.refresh(credential);
+      // Pi 0.84 requires provider refreshes to receive an AbortSignal. This
+      // legacy resolver has no cancellation input, so give the refresh its own
+      // non-aborted signal while keeping the public contract unchanged.
+      credential = await oauth.refresh(credential, new AbortController().signal);
     } catch {
       throw new Error(`Failed to refresh OAuth token for ${providerId}`);
     }
@@ -126,15 +129,17 @@ export async function resolveOAuthApiKey(providerId, credentials) {
 }
 
 /**
- * Bridge the legacy six-callback OAuth surface onto 0.83.0's single
- * `prompt`/`notify` pair.
+ * Bridge the legacy six-callback OAuth surface onto Pi's single
+ * `prompt`/`notify` pair. Pi 0.84 requires every provider login interaction to
+ * carry an AbortSignal, so callbacks without one receive a private non-aborted
+ * signal.
  *
  * `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}
+ * @returns {ProviderAuthInteraction}
  */
 export function toAuthInteraction(callbacks) {
   if (callbacks === null || typeof callbacks !== "object") {
@@ -142,7 +147,7 @@ export function toAuthInteraction(callbacks) {
   }
 
   return {
-    ...(callbacks.signal === undefined ? {} : { signal: callbacks.signal }),
+    signal: callbacks.signal ?? new AbortController().signal,
 
     /** @param {AuthPrompt} prompt */
     async prompt(prompt) {

package/types/agent/tools/bash.d.ts

@@ -24,11 +24,12 @@ export function normalizeBackgroundBashTimeoutMs(value: any): number;
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export function bashToolImpl(params: {
     command: string;
+    description?: string;
     timeout?: number;
     timeout_ms?: number;
     max_output_chars?: number;
@@ -44,11 +45,12 @@ export function bashToolImpl(params: {
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
-export function bashToolRun({ command, timeout, timeout_ms, max_output_chars, workdir, background, }: {
+export function bashToolRun({ command, description, timeout, timeout_ms, max_output_chars, workdir, background, }: {
     command: string;
+    description?: string;
     timeout?: number;
     timeout_ms?: number;
     max_output_chars?: number;

package/types/agent/tools/exec.d.ts

@@ -1,12 +1,13 @@
 /** @typedef {import("./shared/process-jobs.js").ProcessJobsController} ProcessJobsController */
 /**
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export function execToolImpl(params: {
     executable: string;
     args?: string[];
     workdir?: string;
+    description?: string;
     timeout_ms?: number;
     max_output_chars?: number;
     background?: boolean;
@@ -20,13 +21,14 @@ export function execToolImpl(params: {
 /**
  * Execute an argv vector directly, without shell parsing.
  *
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
-export function execToolRun({ executable, args, workdir, timeout_ms, max_output_chars, background, }: {
+export function execToolRun({ executable, args, workdir, description, timeout_ms, max_output_chars, background, }: {
     executable: string;
     args?: string[];
     workdir?: string;
+    description?: string;
     timeout_ms?: number;
     max_output_chars?: number;
     background?: boolean;

package/types/agent/tools/shared/process-jobs.d.ts

@@ -7,6 +7,7 @@
  *   tool: "Exec"|"Bash",
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
+ *   description?: string,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
@@ -21,17 +22,19 @@
  *   tool: "Exec"|"Bash",
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
+ *   description?: string,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   startedAt: number,
  *   failed: (text: string, code: string, startedAt: number) => any,
  * }} input
  */
-export function handOffProcessJob({ controller, tool, prepared, summary, timeoutMs, maxOutputChars, startedAt, failed, }: {
+export function handOffProcessJob({ controller, tool, prepared, summary, description, timeoutMs, maxOutputChars, startedAt, failed, }: {
     controller: ProcessJobsController;
     tool: "Exec" | "Bash";
     prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
     summary: string;
+    description?: string;
     timeoutMs?: number;
     maxOutputChars?: number;
     startedAt: number;
@@ -46,6 +49,7 @@ export type ProcessJobsController = {
         tool: "Exec" | "Bash";
         prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
         summary: string;
+        description?: string;
         timeoutMs?: number;
         maxOutputChars?: number;
         launch: (options?: {

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

@@ -38,20 +38,22 @@ export function resolveOAuthApiKey(providerId: string, credentials: Record<strin
     apiKey: string | undefined;
 } | null>;
 /**
- * Bridge the legacy six-callback OAuth surface onto 0.83.0's single
- * `prompt`/`notify` pair.
+ * Bridge the legacy six-callback OAuth surface onto Pi's single
+ * `prompt`/`notify` pair. Pi 0.84 requires every provider login interaction to
+ * carry an AbortSignal, so callbacks without one receive a private non-aborted
+ * signal.
  *
  * `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}
+ * @returns {ProviderAuthInteraction}
  */
-export function toAuthInteraction(callbacks: OAuthLoginCallbacks): AuthInteraction;
+export function toAuthInteraction(callbacks: OAuthLoginCallbacks): ProviderAuthInteraction;
 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 ProviderAuthInteraction = import("@earendil-works/pi-ai").ProviderAuthInteraction;
 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;