@pasko70/pibo 2.4.1 → 2.4.3

package/dist/runs/tools.js

@@ -1,8 +1,17 @@
 import { Type } from "typebox";
 import { piboStringEnum } from "../tools/schema.js";
-import { definePiboTool } from "../tools/contract.js";
-import { foregroundServiceWarning, hasMeaningfulTimeoutOutput, isConfiguredTimeoutError, PiboRunExecutionTimeoutError, resolveRunTimeoutMs } from "./lifecycle.js";
+import { definePiboTool, piboToolTerminalStatus, piboToolTimeoutPhase } from "../tools/contract.js";
+import { foregroundServiceWarning, hasMeaningfulTimeoutOutput, isConfiguredTimeoutError, PiboRunCancellationError, PiboRunCancelledError, PiboRunExecutionTimeoutError, resolveRunTimeoutMs, waitForRunCancellationSettlement } from "./lifecycle.js";
 import { PiboRunResourceLimitError, prepareYieldedRunExecution } from "./resource-isolation.js";
+export const PIBO_RUN_TOOL_NAMES = [
+    "pibo_run_start",
+    "pibo_run_list",
+    "pibo_run_status",
+    "pibo_run_wait",
+    "pibo_run_read",
+    "pibo_run_cancel",
+    "pibo_run_ack",
+];
 function resultText(prefix, value) {
     return `${prefix}\n${JSON.stringify(value, null, 2)}`;
 }
@@ -27,22 +36,6 @@ function requireTool(tools, name) {
     }
     return tool;
 }
-async function waitForRunCancellationSettlement(settled, timeoutMs = 15_000) {
-    let timer;
-    try {
-        await Promise.race([
-            settled,
-            new Promise((_resolve, reject) => {
-                timer = setTimeout(() => reject(new Error(`Yielded run did not settle within ${timeoutMs}ms after cancellation.`)), timeoutMs);
-                timer.unref?.();
-            }),
-        ]);
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
 export function createRunToolDefinitions(yieldableTools, controller) {
     const toolNames = yieldableTools.map((tool) => tool.name);
     return [
@@ -73,6 +66,7 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                     resolveExecutionSettled = resolve;
                 });
                 let observedOutput = false;
+                let cancellationFailure;
                 const run = controller.startToolRun({
                     toolName: tool.name,
                     params: params.arguments,
@@ -95,26 +89,38 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                             throw processCancellationError;
                         if (executionStarted)
                             await waitForRunCancellationSettlement(executionSettled);
+                        if (cancellationFailure)
+                            throw cancellationFailure;
                     },
-                    async execute() {
+                    async execute(runId) {
                         executionStarted = true;
                         try {
                             const result = await prepared.execute(() => tool.execute(toolCallId, prepared.params, runSignal, (update) => {
                                 observedOutput ||= hasMeaningfulTimeoutOutput(update);
                                 onUpdate?.(update);
-                            }, ctx));
+                            }, { ...ctx, yieldedRunId: runId }));
                             const resultObject = result;
                             const text = textFromToolResult(resultObject);
                             if (resultObject.isError === true) {
-                                if (timeoutMs !== undefined && isConfiguredTimeoutError(text ?? ""))
+                                const structuredTimeout = piboToolTerminalStatus(resultObject) === "timed_out";
+                                if (structuredTimeout) {
+                                    throw new PiboRunExecutionTimeoutError(text ?? `${tool.name} timed out.`, piboToolTimeoutPhase(resultObject) ?? (observedOutput || hasMeaningfulTimeoutOutput(text) ? "lifetime" : "startup"));
+                                }
+                                if (timeoutMs !== undefined && isConfiguredTimeoutError(text ?? "")) {
                                     throw new PiboRunExecutionTimeoutError(text ?? `${tool.name} timed out.`, observedOutput || hasMeaningfulTimeoutOutput(text) ? "lifetime" : "startup");
+                                }
                                 throw new Error(text ?? `${tool.name} returned an error result.`);
                             }
                             return { text, details: resultObject.details ?? result };
                         }
                         catch (error) {
-                            if (error instanceof PiboRunExecutionTimeoutError || error instanceof PiboRunResourceLimitError)
+                            if (error instanceof PiboRunCancellationError)
+                                cancellationFailure = error;
+                            if (error instanceof PiboRunExecutionTimeoutError || error instanceof PiboRunResourceLimitError || error instanceof PiboRunCancellationError)
                                 throw error;
+                            if (runAbortController.signal.aborted) {
+                                throw new PiboRunCancelledError("Yielded run was cancelled; execution ended after cancellation.", { cause: error });
+                            }
                             if (timeoutMs !== undefined && isConfiguredTimeoutError(error))
                                 throw new PiboRunExecutionTimeoutError(error instanceof Error ? error.message : String(error), observedOutput ? "lifetime" : "startup");
                             throw error;
@@ -223,8 +229,11 @@ export function createRunToolDefinitions(yieldableTools, controller) {
             }),
             async execute(_toolCallId, params) {
                 const run = await controller.cancelRun(params.runId);
+                const prefix = run.status === "cancelled"
+                    ? `Cancelled run ${run.runId}.`
+                    : `Run ${run.runId} reached ${run.status} before cancellation completed.`;
                 return {
-                    content: [{ type: "text", text: resultText(`Cancelled run ${run.runId}.`, run) }],
+                    content: [{ type: "text", text: resultText(prefix, run) }],
                     details: run,
                 };
             },
@@ -240,8 +249,9 @@ export function createRunToolDefinitions(yieldableTools, controller) {
             }),
             async execute(_toolCallId, params) {
                 const run = controller.ackRun(params.runId);
+                const prefix = run.changed ? `Acknowledged run ${run.runId}.` : `Run ${run.runId} was already acknowledged in state ${run.status}; no state changed.`;
                 return {
-                    content: [{ type: "text", text: resultText(`Acknowledged run ${run.runId}.`, run) }],
+                    content: [{ type: "text", text: resultText(prefix, run) }],
                     details: run,
                 };
             },

package/dist/subagents/context.js

@@ -0,0 +1,48 @@
+import { listAvailableAgents } from "./tool.js";
+export const PIBO_DELEGATED_AGENT_CONTEXT_PATH = "pibo://runtime/delegated-agents.md";
+export function getDelegatedAgentContextFile(subagents) {
+    const agents = listAvailableAgents(subagents);
+    if (agents.length === 0)
+        return undefined;
+    const catalog = agents.map((agent) => {
+        const runtime = [
+            agent.model ? `${agent.model.provider}/${agent.model.id}` : undefined,
+            agent.thinkingLevel ? `thinking ${agent.thinkingLevel}` : undefined,
+        ].filter(Boolean).join(", ");
+        return `- \`${agent.name}\` → \`${agent.profile}\`${runtime ? ` (${runtime})` : ""}: ${agent.description}`;
+    }).join("\n");
+    return {
+        path: PIBO_DELEGATED_AGENT_CONTEXT_PATH,
+        content: [
+            "# Delegated Agent Management",
+            "",
+            "This session has Pibo-managed delegated agents. Dispatch is yielded-only: never call `pibo_agents_send_message` directly. Start it through `pibo_run_start`, then manage the returned run ID.",
+            "",
+            "## Available agents",
+            "",
+            catalog,
+            "",
+            "## Required workflow",
+            "",
+            "```text",
+            "pibo_run_start({",
+            "  toolName: \"pibo_agents_send_message\",",
+            "  arguments: { name, message, threadKey? },",
+            "  completionPolicy?: \"tracked\" | \"detached\"",
+            "}) -> { runId }",
+            "",
+            "pibo_run_wait({ runId, timeoutMs? })       # bounded wait only; expiry does not stop the child",
+            "pibo_run_status({ runId })                 # compact lifecycle state",
+            "pibo_agents_observe({ requestIds?: [runId], agentIds?, names?, threadKeys?, kinds?, roles?, ... })",
+            "pibo_run_read({ runId })                   # terminal result, including the complete final agent message",
+            "pibo_run_cancel({ runId })                 # explicit request cancellation",
+            "pibo_agents_list_agents({})                # available definitions and persistent child instances",
+            "pibo_agents_kill({ agentId })              # terminate one persistent child session subtree",
+            "```",
+            "",
+            "Reuse a stable `threadKey` to continue the same child Pibo Session. A wait timeout is only an orchestrator wake-up. Observe progress and decide whether to continue waiting, steer through a new message after the current turn, cancel the request, or kill the child session.",
+            "",
+            "For substantial reports, ask the child to persist a Markdown artifact and include its path in the complete final message.",
+        ].join("\n"),
+    };
+}

package/dist/subagents/runtime-selection.js

@@ -0,0 +1,28 @@
+import { selectRequestedSubagentModelProfile, selectRequestedSubagentThinkingLevel, } from "../core/model-defaults.js";
+export function resolvePiboSubagentRuntimeSelection(subagent, targetProfile, modelDefaults = {}) {
+    const effectiveModel = subagent.model ?? selectRequestedSubagentModelProfile(targetProfile, modelDefaults);
+    const effectiveThinkingLevel = subagent.thinkingLevel ?? selectRequestedSubagentThinkingLevel(targetProfile, modelDefaults);
+    return {
+        ...(subagent.model ? { configuredModel: { ...subagent.model } } : {}),
+        ...(effectiveModel ? { effectiveModel: { ...effectiveModel } } : {}),
+        ...(subagent.thinkingLevel ? { configuredThinkingLevel: subagent.thinkingLevel } : {}),
+        ...(effectiveThinkingLevel ? { effectiveThinkingLevel } : {}),
+    };
+}
+export function resolvePiboSubagentRuntimeSelections(subagents, targetProfileResolver, modelDefaults = {}) {
+    return subagents.map((subagent) => {
+        const targetProfile = targetProfileResolver?.(subagent.targetProfile);
+        const selection = targetProfile
+            ? resolvePiboSubagentRuntimeSelection(subagent, targetProfile, modelDefaults)
+            : {
+                ...(subagent.model ? { configuredModel: { ...subagent.model }, effectiveModel: { ...subagent.model } } : {}),
+                ...(subagent.thinkingLevel ? { configuredThinkingLevel: subagent.thinkingLevel, effectiveThinkingLevel: subagent.thinkingLevel } : {}),
+            };
+        return {
+            name: subagent.name,
+            targetProfile: subagent.targetProfile,
+            enabled: subagent.enabled !== false,
+            ...selection,
+        };
+    });
+}

package/dist/subagents/tool.js

@@ -30,6 +30,13 @@ export function formatAvailableAgentsForPrompt(subagents) {
 function resultText(prefix, value) {
     return `${prefix}\n${JSON.stringify(value, null, 2)}`;
 }
+function normalizeAgentSendMessageResult(result, fallbackRequestId) {
+    return {
+        ...result,
+        requestId: result.requestId?.trim() || fallbackRequestId,
+        finalMessage: typeof result.finalMessage === "string" ? result.finalMessage : result.reply.text,
+    };
+}
 export function createAgentToolDefinitions(subagents, controller) {
     const enabled = subagents.filter((subagent) => subagent.enabled !== false);
     if (enabled.length === 0)
@@ -48,11 +55,11 @@ export function createAgentToolDefinitions(subagents, controller) {
             name: "pibo_agents_send_message",
             title: "Pibo Agents Send Message",
             description: [
-                "Send a message to an available delegated agent. Foreground execution waits for the reply; use pibo_run_start for asynchronous delegation.",
+                "Yielded-only delegated send. Start this tool through pibo_run_start; bounded waits do not limit the child lifetime.",
                 "Available agents:",
                 catalog,
             ].join("\n"),
-            promptSnippet: "Send work to an available delegated agent by name. Reuse threadKey to continue its child session. Use pibo_run_start with this tool for asynchronous work. The tool definition lists the available names and parent-visible descriptions.",
+            promptSnippet: "Start pibo_agents_send_message through pibo_run_start. Reuse threadKey to continue its child session, and use run wait/status/read/cancel plus agent observe for lifecycle control.",
             executionMode: "parallel",
             inputSchema: Type.Object({
                 name: piboStringEnum(names, { description: "Available delegated agent name" }),
@@ -62,22 +69,35 @@ export function createAgentToolDefinitions(subagents, controller) {
                     maxLength: 256,
                 })),
             }),
-            async execute(toolCallId, params, signal) {
+            async execute(toolCallId, params, signal, _onUpdate, context) {
                 const subagent = byName.get(params.name);
                 if (!subagent)
                     throw new Error(`Unknown delegated agent "${params.name}"`);
-                const result = await controller.sendMessage({
+                if (!context.yieldedRunId) {
+                    throw new Error("pibo_agents_send_message is yielded-only. Start it through pibo_run_start.");
+                }
+                const result = normalizeAgentSendMessageResult(await controller.sendMessage({
                     subagent,
                     message: params.message,
                     threadKey: params.threadKey,
                     toolCallId,
+                    requestId: context.yieldedRunId,
+                    parentProvenance: context.getActiveMessage?.()?.provenance,
                     signal,
-                });
+                }), context.yieldedRunId);
                 return {
                     content: [{
                             type: "text",
-                            text: `Agent ${result.name} (${result.agentId}, thread ${result.threadKey}) replied:\n${result.reply.text}`,
+                            text: `Agent request ${result.requestId} completed (${result.name}, ${result.agentId}, thread ${result.threadKey}).\n\n${result.finalMessage}`,
                         }],
+                    structuredContent: {
+                        status: "completed",
+                        requestId: result.requestId,
+                        agentId: result.agentId,
+                        threadKey: result.threadKey,
+                        eventId: result.eventId,
+                        finalMessage: result.finalMessage,
+                    },
                     details: result,
                 };
             },
@@ -106,11 +126,13 @@ export function createAgentToolDefinitions(subagents, controller) {
             executionMode: "parallel",
             annotations: { readOnly: true },
             inputSchema: Type.Object({
+                requestIds: Type.Optional(Type.Array(Type.String({ description: "Exact yielded run/request ID" }), { maxItems: 50 })),
                 agentIds: Type.Optional(Type.Array(Type.String({ description: "Owned child agentId" }), { maxItems: 50 })),
                 names: Type.Optional(Type.Array(piboStringEnum(names), { maxItems: 50 })),
                 threadKeys: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
                 eventTypes: Type.Optional(Type.Array(Type.String({ description: "Exact Pibo output event type" }), { maxItems: 50 })),
                 kinds: Type.Optional(Type.Array(piboStringEnum(["message", "thinking", "tool", "error", "lifecycle", "event"]), { maxItems: 6 })),
+                roles: Type.Optional(Type.Array(Type.String({ description: "Exact normalized role, for example assistant" }), { maxItems: 20 })),
                 since: Type.Optional(Type.String({ description: "Inclusive ISO-8601 lower timestamp bound" })),
                 until: Type.Optional(Type.String({ description: "Inclusive ISO-8601 upper timestamp bound" })),
                 textContains: Type.Optional(Type.String({ description: "Case-insensitive substring match against normalized observation text" })),

package/dist/tools/codex-compat.js

@@ -4,6 +4,7 @@ import { extname, isAbsolute, resolve } from "node:path";
 import { Type } from "typebox";
 import { piboStringEnum } from "./schema.js";
 import { definePiboTool } from "./contract.js";
+export const CODEX_COMPAT_TOOL_NAMES = ["apply_patch", "view_image"];
 function resolveCwd(baseCwd, workdir) {
     if (!workdir || workdir.trim().length === 0)
         return baseCwd;

package/dist/tools/contract.js

@@ -1,3 +1,10 @@
+export function piboToolTerminalStatus(result) {
+    return result.metadata?.piboTerminalStatus === "timed_out" ? "timed_out" : undefined;
+}
+export function piboToolTimeoutPhase(result) {
+    const phase = result.metadata?.piboTimeoutPhase;
+    return phase === "startup" || phase === "lifetime" ? phase : undefined;
+}
 /** Identity helper that preserves schema-derived input types. */
 export function definePiboTool(definition) {
     definition.label ??= definition.title;
@@ -14,8 +21,11 @@ export function isPiboToolDefinition(value) {
 export function normalizePiboToolResult(result) {
     return {
         content: result.content.map((content) => ({ ...content })),
+        ...("structuredContent" in result && result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}),
         ...(result.details !== undefined ? { details: result.details } : {}),
         ...(result.isError !== undefined ? { isError: result.isError } : {}),
+        ...("payloadRefs" in result && result.payloadRefs !== undefined ? { payloadRefs: [...result.payloadRefs] } : {}),
+        ...("metadata" in result && result.metadata !== undefined ? { metadata: { ...result.metadata } } : {}),
     };
 }
 /** Convert a legacy Pi-shaped definition without leaking Pi types into generic code. */

package/dist/tools/mcp-bridge.js

@@ -166,10 +166,12 @@ async function convertContent(items, options) {
     return { content, payloadRefs };
 }
 async function piboResultToMcp(result, options) {
-    const converted = await convertContent(result.content, options);
+    const preserveCompleteRunRead = options.tool.name === "pibo_run_read";
+    const conversionOptions = preserveCompleteRunRead ? { ...options, writer: undefined } : options;
+    const converted = await convertContent(result.content, conversionOptions);
     const payloadRefs = [...new Set([...(result.payloadRefs ?? []), ...converted.payloadRefs])];
     let structuredContent = result.structuredContent ?? toJsonValue(result.details);
-    if (structuredContent !== undefined && options.writer) {
+    if (structuredContent !== undefined && options.writer && !preserveCompleteRunRead) {
         const encoded = JSON.stringify(structuredContent);
         if (Buffer.byteLength(encoded, "utf8") > options.threshold) {
             const stored = await storeLargeContent({

package/dist/tools/runtime/node-backend.js

@@ -68,8 +68,14 @@ export class NodeRuntimeBackend {
     static async start(baseCwd, input) {
         const target = input.target ?? {};
         const backend = new NodeRuntimeBackend(resolveCwd(baseCwd, target.cwd), target.executable ?? process.execPath, target.args ?? [], target.env);
-        await backend.waitReady(input.timeoutMs ?? 10000);
-        return backend;
+        try {
+            await backend.waitReady(input.timeoutMs ?? 10000);
+            return backend;
+        }
+        catch (error) {
+            await backend.close(true).catch(() => undefined);
+            throw error;
+        }
     }
     isAlive() {
         return this.alive && !this.child.killed;

package/dist/tools/runtime/python-backend.js

@@ -68,8 +68,14 @@ export class PythonRuntimeBackend {
     static async start(baseCwd, input) {
         const target = input.target ?? {};
         const backend = new PythonRuntimeBackend(resolveCwd(baseCwd, target.cwd), target.executable ?? (process.platform === "win32" ? "python" : "python3"), target.args ?? [], target.env);
-        await backend.waitReady(input.timeoutMs ?? 10000);
-        return backend;
+        try {
+            await backend.waitReady(input.timeoutMs ?? 10000);
+            return backend;
+        }
+        catch (error) {
+            await backend.close(true).catch(() => undefined);
+            throw error;
+        }
     }
     isAlive() {
         return this.alive && !this.child.killed;

package/dist/tools/runtime/tool.js

@@ -163,6 +163,7 @@ export function createRuntimeToolDefinition(controller) {
                 content: [{ type: "text", text: formatRuntimeResult(result) }],
                 details: result,
                 isError: isErrorStatus(status),
+                ...(status === "timeout" ? { metadata: { piboTerminalStatus: "timed_out", piboTimeoutPhase: "startup" } } : {}),
             };
         },
     });

package/dist/tools/session-tool-set.js

@@ -31,6 +31,12 @@ function getToolDefinition(tool, context = {}) {
         return tool.definition;
     return tool.createDefinition(context);
 }
+export function materializePiboProfileTools(profile, context = {}) {
+    return profile.tools
+        .filter((tool) => !isRuntimeToolProfile(tool) && !isCodexBrowserToolProfile(tool))
+        .filter(hasEnabledToolDefinition)
+        .map((tool) => ({ profile: tool, definition: getToolDefinition(tool, context) }));
+}
 /** Assemble the selected Pibo-managed tool set without importing any harness package. */
 export function createPiboSessionToolDefinitions(options) {
     const { profile } = options;
@@ -47,10 +53,8 @@ export function createPiboSessionToolDefinitions(options) {
     const codexBrowserTools = options.codexBrowserController
         ? createCodexBrowserToolDefinitions(options.codexBrowserController, selectedCodexBrowserToolNames)
         : [];
-    const profileTools = profile.tools
-        .filter((tool) => !isRuntimeToolProfile(tool) && !isCodexBrowserToolProfile(tool))
-        .filter(hasEnabledToolDefinition);
-    const profileToolDefinitions = profileTools.map((tool) => getToolDefinition(tool, options.toolContext));
+    const materializedProfileTools = materializePiboProfileTools(profile, options.toolContext);
+    const profileToolDefinitions = materializedProfileTools.map((tool) => tool.definition);
     const codexCompatTools = profile.toolPackages.codexCompat === true
         ? createCodexCompatToolDefinitions()
         : [];
@@ -60,28 +64,31 @@ export function createPiboSessionToolDefinitions(options) {
     const agentTools = options.agentsController
         ? createAgentToolDefinitions(profile.subagents, options.agentsController)
         : [];
+    const delegatedSendTool = agentTools.find((tool) => tool.name === "pibo_agents_send_message");
+    const directAgentTools = agentTools.filter((tool) => tool !== delegatedSendTool);
     const nativeYieldableTools = [...(options.nativeYieldableTools ?? [])];
     const yieldableTools = [
         ...nativeYieldableTools,
-        ...profileTools
-            .filter((tool) => tool.yieldable !== false)
-            .map((tool) => getToolDefinition(tool, options.toolContext)),
+        ...materializedProfileTools
+            .filter((tool) => tool.profile.yieldable !== false)
+            .map((tool) => tool.definition),
         ...(runtimeTool && runtimeProfileTool?.yieldable !== false ? [runtimeTool] : []),
         ...codexBrowserTools.filter((definition) => profile.tools.find((tool) => tool.name === definition.name)?.yieldable !== false),
         ...agentTools,
         ...codexCompatTools,
     ];
-    const runTools = profile.toolPackages.runControl === true
-        && options.runToolController
-        && yieldableTools.length > 0
-        ? createRunToolDefinitions(yieldableTools, options.runToolController)
+    const runControlYieldableTools = profile.toolPackages.runControl === true
+        ? yieldableTools
+        : delegatedSendTool ? [delegatedSendTool] : [];
+    const runTools = options.runToolController && runControlYieldableTools.length > 0
+        ? createRunToolDefinitions(runControlYieldableTools, options.runToolController)
         : [];
     return [
         ...nativeYieldableTools,
         ...profileToolDefinitions,
         ...(runtimeTool ? [runtimeTool] : []),
         ...codexBrowserTools,
-        ...agentTools,
+        ...directAgentTools,
         ...codexCompatTools,
         ...goalTools,
         ...runTools,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@pasko70/pibo",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pasko70/pibo",
-      "version": "2.4.1",
+      "version": "2.4.3",
       "workspaces": [
         "packages/workflows"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pasko70/pibo",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "type": "module",
   "workspaces": [
     "packages/workflows"