@pasko70/pibo 2.4.2 → 2.5.0

package/dist/loops/store.js

@@ -4,7 +4,7 @@ import { dirname, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { piboHomePath } from '../core/pibo-home.js';
 import { isPiboThinkingLevel } from '../core/thinking.js';
-import { newGoalTokenAccounting, normalizeLoopTokenAccounting } from './accounting.js';
+import { addLoopAssistantUsage, newGoalTokenAccounting, normalizeLoopTokenAccounting } from './accounting.js';
 function nowIso(now = new Date()) { return now.toISOString(); }
 function parseJson(json) { return JSON.parse(json); }
 function defaultName(prompt) { const normalized = prompt.replace(/\s+/g, ' ').trim(); return normalized ? normalized.slice(0, 80) : 'Loop job'; }
@@ -418,29 +418,65 @@ export class PiboLoopStore {
         this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = ?, state_json = ?, updated_at = ? WHERE id = ?').run(budgetLimited ? 0 : job.enabled ? 1 : 0, JSON.stringify(state), timestamp, id);
         return this.getJob(id);
     }
-    recordGoalTurnUsage(id, runId, tokens, now = new Date()) {
+    recordGoalAssistantUsage(id, runId, input, now = new Date()) {
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            const job = this.recordGoalProgress(id, { tokens }, now);
-            if (job?.mode === 'goal') {
-                const row = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ? AND job_id = ?').get(runId, id);
-                if (row) {
-                    const accounting = parseRunAccounting(row.accounting_json) ?? { tokenAccounting: normalizeLoopTokenAccounting(job.state.tokenAccounting) };
-                    const turnTokens = (accounting.tokensUsed ?? 0) + Math.max(0, Math.floor(tokens));
-                    const budget = accounting.tokenBudget;
-                    const before = accounting.tokensUsedBefore ?? 0;
-                    const nextAccounting = { ...accounting, tokensUsed: turnTokens, ...(budget !== undefined ? { overshootTokens: Math.max(0, before + turnTokens - budget) } : {}) };
-                    this.db.prepare('UPDATE pibo_ralph_runs SET accounting_json = ?, updated_at = ? WHERE id = ?').run(runAccountingJson(nextAccounting), nowIso(now), runId);
-                }
+            const job = this.getJob(id);
+            if (!job || job.mode !== 'goal') {
+                this.db.exec('COMMIT');
+                return job;
+            }
+            const tokens = Math.max(0, Math.floor(input.budgetTokens));
+            const nextTokens = (job.state.tokensUsed ?? 0) + tokens;
+            const currentStatus = goalStatus(job) ?? 'active';
+            const budgetLimited = currentStatus === 'active' && job.tokenBudget !== undefined && nextTokens >= job.tokenBudget;
+            const timestamp = nowIso(now);
+            const state = {
+                ...job.state,
+                tokensUsed: nextTokens,
+                usage: addLoopAssistantUsage(job.state.usage, input.usage, {
+                    piboSessionId: input.piboSessionId,
+                    descendant: input.descendant,
+                }),
+                goalStatus: budgetLimited ? 'budget_limited' : currentStatus,
+            };
+            if (budgetLimited)
+                state.goalEndedAt = job.state.goalEndedAt ?? timestamp;
+            this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = ?, state_json = ?, updated_at = ? WHERE id = ?').run(budgetLimited ? 0 : job.enabled ? 1 : 0, JSON.stringify(state), timestamp, id);
+            const row = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ? AND job_id = ?').get(runId, id);
+            if (row) {
+                const accounting = parseRunAccounting(row.accounting_json) ?? { tokenAccounting: normalizeLoopTokenAccounting(state.tokenAccounting) };
+                const turnTokens = (accounting.tokensUsed ?? 0) + tokens;
+                const budget = accounting.tokenBudget;
+                const before = accounting.tokensUsedBefore ?? 0;
+                const nextAccounting = {
+                    ...accounting,
+                    tokensUsed: turnTokens,
+                    usage: addLoopAssistantUsage(accounting.usage, input.usage, {
+                        piboSessionId: input.piboSessionId,
+                        descendant: input.descendant,
+                    }),
+                    ...(budget !== undefined ? { overshootTokens: Math.max(0, before + turnTokens - budget) } : {}),
+                };
+                this.db.prepare('UPDATE pibo_ralph_runs SET accounting_json = ?, updated_at = ? WHERE id = ?').run(runAccountingJson(nextAccounting), timestamp, runId);
             }
             this.db.exec('COMMIT');
-            return job;
+            return this.getJob(id);
         }
         catch (error) {
             this.db.exec('ROLLBACK');
             throw error;
         }
     }
+    recordGoalTurnUsage(id, runId, tokens, now = new Date()) {
+        const run = this.getRun(runId);
+        return this.recordGoalAssistantUsage(id, runId, {
+            usage: { type: 'assistant_usage', piboSessionId: run?.piboSessionId ?? 'unknown', totalTokens: Math.max(0, Math.floor(tokens)) },
+            budgetTokens: tokens,
+            piboSessionId: run?.piboSessionId ?? 'unknown',
+            descendant: false,
+        }, now);
+    }
     recordGoalRunTime(id, runId, activeTimeSeconds, now = new Date()) {
         const seconds = Math.max(0, Math.floor(activeTimeSeconds));
         this.db.exec('BEGIN IMMEDIATE');

package/dist/runs/lifecycle.js

@@ -1,3 +1,4 @@
+export const PIBO_RUN_CANCELLATION_SETTLEMENT_TIMEOUT_MS = 15_000;
 export class PiboRunExecutionTimeoutError extends Error {
     timeoutPhase;
     constructor(message, timeoutPhase) {
@@ -18,6 +19,22 @@ export class PiboRunCancelledError extends Error {
         this.name = "PiboRunCancelledError";
     }
 }
+export async function waitForRunCancellationSettlement(settled, timeoutMs = PIBO_RUN_CANCELLATION_SETTLEMENT_TIMEOUT_MS) {
+    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 resolveRunTimeoutMs(toolName, params) {
     if (!params || typeof params !== "object" || Array.isArray(params))
         return undefined;
@@ -38,7 +55,15 @@ export function foregroundServiceWarning(toolName, params, timeoutMs) {
 }
 export function isConfiguredTimeoutError(error) {
     const message = error instanceof Error ? error.message : String(error);
-    return /(?:timed?\s*out|timeout)/i.test(message);
+    const terminalLines = message.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-5);
+    return terminalLines.some((line) => {
+        const normalized = line.replace(/^error:\s*/i, "");
+        return /^(?:command|process|tool execution|yielded run)\s+timed?\s*out\b.*$/i.test(normalized)
+            || /^timed?\s*out(?:\s+after\s+.+)?[.!]?$/i.test(normalized)
+            || /^timeout(?:\s+error)?[.!]?$/i.test(normalized)
+            || /^timeout(?::|\s+)(?:occurred|expired|exceeded|elapsed|reached)\b.*$/i.test(normalized)
+            || /^timeout(?::|\s+)(?:after\s+)?\d+(?:\.\d+)?\s*(?:ms|milliseconds?|s|secs?|seconds?|m|mins?|minutes?|h|hours?)\b.*$/i.test(normalized);
+    });
 }
 export function hasMeaningfulTimeoutOutput(value) {
     const text = extractText(value);

package/dist/runs/registry.js

@@ -10,12 +10,21 @@ function runTimeoutAt(createdAt, timeoutMs) {
 function sameOrigin(left, right) {
     if (!left || !right)
         return left === right;
-    return left.eventId === right.eventId
-        && left.provenance.kind === right.provenance.kind
-        && left.provenance.jobId === right.provenance.jobId
-        && left.provenance.runId === right.provenance.runId
-        && left.provenance.cause === right.provenance.cause
-        && left.provenance.rootEventId === right.provenance.rootEventId;
+    if (left.eventId !== right.eventId || left.provenance.kind !== right.provenance.kind)
+        return false;
+    if (left.provenance.kind === "loop-run" && right.provenance.kind === "loop-run") {
+        return left.provenance.jobId === right.provenance.jobId
+            && left.provenance.runId === right.provenance.runId
+            && left.provenance.cause === right.provenance.cause
+            && left.provenance.rootEventId === right.provenance.rootEventId;
+    }
+    if (left.provenance.kind === "subagent-request" && right.provenance.kind === "subagent-request") {
+        return left.provenance.requestId === right.provenance.requestId
+            && left.provenance.controllerPiboSessionId === right.provenance.controllerPiboSessionId
+            && left.provenance.loopJobId === right.provenance.loopJobId
+            && left.provenance.loopRunId === right.provenance.loopRunId;
+    }
+    return false;
 }
 function formatTimeout(timeoutMs) {
     if (timeoutMs === undefined)
@@ -218,6 +227,16 @@ export class PiboRunRegistry {
             .filter((record) => options.includeDetached || record.completionPolicy !== "detached")
             .map(snapshot);
     }
+    listActiveControllerRuns(controllerPiboSessionId) {
+        return [...this.runs.values()]
+            .filter((record) => record.controllerPiboSessionId === controllerPiboSessionId && !terminal(record.status))
+            .map(snapshot);
+    }
+    listActiveRuns() {
+        return [...this.runs.values()]
+            .filter((record) => !terminal(record.status))
+            .map(snapshot);
+    }
     status(controllerPiboSessionId, runId) {
         return snapshot(this.requireRunForController(controllerPiboSessionId, runId));
     }
@@ -270,21 +289,22 @@ export class PiboRunRegistry {
             output.error = record.error;
         return output;
     }
-    cancel(controllerPiboSessionId, runId) {
+    cancel(controllerPiboSessionId, runId, reason = "Run was cancelled.") {
         const record = this.requireRunForController(controllerPiboSessionId, runId);
         const previousStatus = record.status;
         if (!terminal(record.status)) {
             record.status = "cancelled";
+            record.error = reason;
             record.summary = `${record.toolName} run cancelled.`;
             this.finish(record);
             if (record.jobId)
-                this.options.store?.fail(record.jobId, this.workerId, "Run was cancelled.");
+                this.options.store?.fail(record.jobId, this.workerId, reason);
         }
         record.consumed = true;
         record.updatedAt = now();
         this.options.store?.updateRun(runId, record);
         const output = snapshot(record);
-        this.notify({ type: "run_changed", run: output, previousStatus, reason: "Run was cancelled." });
+        this.notify({ type: "run_changed", run: output, previousStatus, reason });
         return output;
     }
     ack(controllerPiboSessionId, runId) {
@@ -356,44 +376,6 @@ export class PiboRunRegistry {
     hasPendingNotification(controllerPiboSessionId, options = {}) {
         return [...this.runs.values()].some((record) => this.needsNotification(record, controllerPiboSessionId, options));
     }
-    cancelControllerRuns(controllerPiboSessionId, reason = "Controller Pibo session was disposed.") {
-        const cancelled = [];
-        for (const record of this.runs.values()) {
-            if (record.controllerPiboSessionId !== controllerPiboSessionId || terminal(record.status))
-                continue;
-            record.status = "cancelled";
-            record.error = reason;
-            record.consumed = true;
-            record.summary = `${record.toolName} run cancelled.`;
-            this.finish(record);
-            this.options.store?.updateRun(record.runId, record);
-            if (record.jobId)
-                this.options.store?.fail(record.jobId, this.workerId, reason);
-            const output = snapshot(record);
-            this.notify({ type: "run_changed", run: output, previousStatus: "running", reason });
-            cancelled.push(output);
-        }
-        return cancelled;
-    }
-    cancelAll(reason = "Run registry was disposed.") {
-        const cancelled = [];
-        for (const record of this.runs.values()) {
-            if (terminal(record.status))
-                continue;
-            record.status = "cancelled";
-            record.error = reason;
-            record.consumed = true;
-            record.summary = `${record.toolName} run cancelled.`;
-            this.finish(record);
-            this.options.store?.updateRun(record.runId, record);
-            if (record.jobId)
-                this.options.store?.fail(record.jobId, this.workerId, reason);
-            const output = snapshot(record);
-            this.notify({ type: "run_changed", run: output, previousStatus: "running", reason });
-            cancelled.push(output);
-        }
-        return cancelled;
-    }
     prune(options = {}) {
         const nowMs = options.nowMs ?? Date.now();
         const consumedTerminalTtlMs = options.consumedTerminalTtlMs ??

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, PiboRunCancellationError, PiboRunCancelledError, 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 [
@@ -99,18 +92,23 @@ export function createRunToolDefinitions(yieldableTools, controller) {
                         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 };
@@ -231,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,
                 };
             },

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" } } : {}),
             };
         },
     });