@mono-agent/agent-runtime 0.20.3 → 0.20.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.20.3",
+  "version": "0.20.4",
   "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",

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

@@ -389,7 +389,7 @@ function readSkillTool(skillNames = [], { skillsRoot, dataDir, skills = [] } = {
   return {
     name: "ReadSkill",
     label: "Read Skill",
-    description: "Load the complete instructions for a named skill. Use ReadSkill instead of Read for SKILL.md files.",
+    description: "Load the complete instructions for a named skill. Use ReadSkill instead of Read for SKILL.md files. If a skill's instructions are already present in this conversation, apply those instead of loading it again.",
     parameters: objectSchema({ name: { type: "string", enum: enumNames } }, ["name"]),
     async execute(_toolCallId, { name }) {
       if (sharedRoot) {
@@ -473,6 +473,14 @@ export function getPiBuiltinTools(allowedTools, {
     minimum: 1,
     description: "Exact timeout in milliseconds.",
   };
+  // Shared by Exec and Bash, and injected only when the host supplies a
+  // process-job controller. House style for a tool description is
+  // capability + when-to-prefer + caveat, so the middle sentence is what tells
+  // the model which commands belong here rather than in the foreground.
+  const backgroundSchema = {
+    type: "boolean",
+    description: "Run as a durable background process job and notify this conversation when it finishes. Prefer this for work that outlives a reply — builds, full test suites, long installs, migrations, long-running watchers — and leave it off whenever you need the output to answer right now. Do not use for commands that daemonize into another POSIX process group or session.",
+  };
   // 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 = {
@@ -533,9 +541,7 @@ export function getPiBuiltinTools(allowedTools, {
       timeout_ms: processTimeoutSchema,
       timeout: legacyBashTimeoutSchema,
       max_output_chars: bashLimitSchema,
-      ...(processJobsController ? {
-        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
-      } : {}),
+      ...(processJobsController ? { background: backgroundSchema } : {}),
     }, ["command"]), bashToolRun, toolContext),
     Exec: createBuiltinTool("Exec", "Exec", "Execute one program directly from an argv array without shell parsing. Prefer this for ordinary commands; use Bash only when shell syntax is required.", objectSchema({
       executable: { type: "string", minLength: 1 },
@@ -543,9 +549,7 @@ export function getPiBuiltinTools(allowedTools, {
       workdir: { type: "string" },
       timeout_ms: processTimeoutSchema,
       max_output_chars: bashLimitSchema,
-      ...(processJobsController ? {
-        background: { type: "boolean", description: "Run as a durable background process job and notify this conversation when it finishes. Do not use for commands that daemonize into another POSIX process group or session." },
-      } : {}),
+      ...(processJobsController ? { background: backgroundSchema } : {}),
     }, ["executable"]), execToolRun, toolContext),
     NodeRepl: nodeReplController
       ? createBuiltinTool(

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

@@ -84,7 +84,7 @@ export async function handOffProcessJob({
       started_at: result.startedAt,
     };
     return {
-      text: JSON.stringify(payload),
+      text: `${BACKGROUND_START_GUIDANCE}\n${JSON.stringify(payload)}`,
       outcome: {
         status: "ok",
         code: "background_started",
@@ -111,6 +111,16 @@ export async function handOffProcessJob({
   }
 }
 
+/**
+ * A bare id/state payload leaves the model to guess what happens next, and the
+ * cheapest wrong guess is a polling loop. Completion delivers its own turn, so
+ * the result says so itself rather than relying on the schema line alone. No
+ * operator command is named on purpose: the model has a shell, and naming a
+ * status command invites exactly the polling this forbids.
+ */
+const BACKGROUND_START_GUIDANCE =
+  "Background process job started (tool-authored guidance): this conversation is woken with a new turn when the job reaches a terminal state, and its output arrives with that turn. Do not poll, sleep, wait on it, or re-run the command to check progress, and do not report the work as finished yet.";
+
 const PUBLIC_BACKGROUND_START_FAILURES = Object.freeze({
   background_unsupported: "Background process jobs are unsupported for this tool call.",
   background_unsupported_channel: "Background process jobs are unsupported for this channel.",

package/src/ai/failure.js

@@ -84,7 +84,7 @@ const PROVIDER_AUTH_RE = /(no api key|missing api key|api key required|invalid a
 // like worklab's coordinator, independent of retryableProviderFailureInfo) maps
 // that same terse text to the generic "spawn" kind instead of
 // "provider_unavailable".
-const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
+const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
 const TOOL_FAILURE_RE = /(tool .* failed|mcp tool|permission denied|EACCES|read-only file system)/i;
 const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api key|missing api key|api key required|invalid api key|incorrect api key|provider is not configured:|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
 // pi 0.80's openai-client-style bridge collapses a connection-refused/unreachable
@@ -92,7 +92,15 @@ const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api
 // no fetch failed) — the `\bconnection (?:error|refused|failed)\b|\bcould not connect\b`
 // alternation below is the motivating fix so that case still fails over instead of
 // being classified as non-retryable.
-const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
+// pi-ai 0.83.0 adds a second such bare sentence: openai-completions.js throws
+// "Stream ended without finish_reason" when an SSE stream terminates without a
+// finish_reason chunk. Because pi-models.js pins every custom/OpenAI-compatible
+// provider to the openai-completions api, a truncated gateway response was terminal
+// on the first occurrence — a configured fallback chain never advanced off the
+// primary. Matched as the full sentence on purpose: mono-agent's own TUI/web
+// transports emit a similar "Stream ended without a finish or error frame." that is a
+// local protocol fault and must NOT trigger a provider failover.
+const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b)/i;
 export const PROVIDER_ABORT_RE = /\b(?:terminated|aborted before final output|aborted before final|stream aborted|stream was aborted|stream disconnected|websocket (?:error|disconnected|closed)|socket hang up|und_err_socket|econnreset|premature close)\b/i;
 
 /**
@@ -129,7 +137,12 @@ function retryableProviderSubkind(text) {
   if (/timed? ?out|etimedout/i.test(text)) return "timeout";
   // pi 0.80's terse "Connection error." (no ECONNREFUSED/fetch-failed detail) still
   // needs to land in the "network" subkind so a down provider fails over.
-  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network|\bconnection (?:error|refused|failed)\b|\bcould not connect\b/i.test(text)) return "network";
+  // pi-ai 0.83.0's openai-completions adapter throws the bare sentence
+  // "Stream ended without finish_reason" when an OpenAI-compatible SSE stream closes
+  // cleanly but no chunk ever carried a truthy finish_reason — i.e. a gateway
+  // truncated the response. That is a provider-side outage, so it belongs in the same
+  // "network" subkind as the terse connection error above.
+  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network|\bconnection (?:error|refused|failed)\b|\bcould not connect\b|\bstream ended without finish_reason\b/i.test(text)) return "network";
   if (/500|502|503|504|service unavailable|gateway|internal server error/i.test(text)) return "server_error";
   if (/retry your request|try again later|request id|processing your request/i.test(text)) return "retryable_request";
   return null;