@pasko70/pibo 2.2.5 → 2.4.0

package/dist/subagents/observations.js

@@ -0,0 +1,149 @@
+export const PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES = 4 * 1024;
+export const PIBO_AGENT_OBSERVATION_DETAILS_MAX_BYTES = 32 * 1024;
+export const PIBO_AGENT_OBSERVATION_DEFAULT_LIMIT = 50;
+export const PIBO_AGENT_OBSERVATION_MAX_LIMIT = 200;
+export function piboAgentObservationSourceFromEvent(event) {
+    const source = {
+        eventType: event.type,
+        fallbackText: "toolName" in event && typeof event.toolName === "string" ? event.toolName : event.type,
+    };
+    if ("source" in event && typeof event.source === "string")
+        source.source = event.source;
+    if ("text" in event)
+        source.text = event.text;
+    if (event.type === "session_error")
+        source.error = event.error;
+    if (event.type === "tool_call" || event.type === "tool_execution_started")
+        source.args = event.args;
+    if (event.type === "tool_execution_updated")
+        source.partialResult = event.partialResult;
+    if (event.type === "tool_execution_finished" || event.type === "execution_result" || event.type === "compaction_end")
+        source.result = event.result;
+    if (event.type === "execution_result")
+        source.action = event.action;
+    if (event.type === "compaction_start" || event.type === "compaction_end")
+        source.reason = event.reason;
+    if (event.type === "subagent_session")
+        source.subagentName = event.subagentName;
+    return source;
+}
+export function piboAgentObservationKind(eventType) {
+    if (["message_queued", "message_steered", "message_started", "assistant_delta", "assistant_message", "message_finished"].includes(eventType))
+        return "message";
+    if (eventType.startsWith("thinking_"))
+        return "thinking";
+    if (eventType.startsWith("tool_") || eventType === "subagent_session")
+        return "tool";
+    if (eventType === "session_error")
+        return "error";
+    if (eventType === "execution_result" || eventType.startsWith("compaction_"))
+        return "lifecycle";
+    return "event";
+}
+export function piboAgentObservationRole(source) {
+    const eventType = source.eventType;
+    if (eventType === "assistant_message" || eventType === "assistant_delta" || eventType.startsWith("thinking_"))
+        return "assistant";
+    if (eventType === "message_queued" || eventType === "message_steered" || eventType === "message_started" || eventType === "message_finished")
+        return source.source ?? "actor";
+    if (eventType.startsWith("tool_"))
+        return "tool";
+    if (eventType === "subagent_session")
+        return "agent";
+    if (eventType === "session_error" || eventType === "execution_result" || eventType.startsWith("compaction_"))
+        return "system";
+    return undefined;
+}
+export function piboAgentObservationText(source) {
+    if (typeof source.text === "string")
+        return boundPiboAgentObservationText(source.text);
+    if (typeof source.error === "string")
+        return boundPiboAgentObservationText(source.error);
+    if (source.eventType === "tool_call" || source.eventType === "tool_execution_started") {
+        return stringifyPiboAgentObservationValue(source.args);
+    }
+    if (source.eventType === "tool_execution_updated")
+        return stringifyPiboAgentObservationValue(source.partialResult);
+    if (source.eventType === "tool_execution_finished")
+        return stringifyPiboAgentObservationValue(source.result);
+    if (source.eventType === "subagent_session" && typeof source.subagentName === "string") {
+        return boundPiboAgentObservationText(source.subagentName);
+    }
+    if (source.eventType === "execution_result") {
+        return stringifyPiboAgentObservationValue(source.result) ?? stringifyPiboAgentObservationValue(source.action);
+    }
+    if ((source.eventType === "compaction_start" || source.eventType === "compaction_end") && typeof source.reason === "string") {
+        return boundPiboAgentObservationText(source.reason);
+    }
+    return stringifyPiboAgentObservationValue(source.fallbackText);
+}
+export function boundPiboAgentObservationText(value) {
+    if (Buffer.byteLength(value, "utf8") <= PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES)
+        return value;
+    const suffix = "…";
+    let end = Math.min(value.length, PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES);
+    while (end > 0 && Buffer.byteLength(`${value.slice(0, end)}${suffix}`, "utf8") > PIBO_AGENT_OBSERVATION_TEXT_MAX_BYTES)
+        end -= 1;
+    return `${value.slice(0, end)}${suffix}`;
+}
+export function stringifyPiboAgentObservationValue(value) {
+    if (typeof value === "string")
+        return boundPiboAgentObservationText(value);
+    if (value === undefined)
+        return undefined;
+    try {
+        return boundPiboAgentObservationText(JSON.stringify(value));
+    }
+    catch {
+        return boundPiboAgentObservationText(String(value));
+    }
+}
+export function piboAgentObservationDetails(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? "null";
+    }
+    catch {
+        return { truncated: true, preview: boundPiboAgentObservationText(String(value)) };
+    }
+    if (Buffer.byteLength(serialized, "utf8") <= PIBO_AGENT_OBSERVATION_DETAILS_MAX_BYTES) {
+        return JSON.parse(serialized);
+    }
+    return {
+        truncated: true,
+        preview: boundPiboAgentObservationText(serialized),
+    };
+}
+export function parsePiboAgentObservationTimestamp(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value)) {
+        throw new Error(`Agent observation ${label} must be a valid ISO-8601 timestamp.`);
+    }
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        throw new Error(`Agent observation ${label} must be a valid ISO-8601 timestamp.`);
+    return timestamp;
+}
+export function normalizePiboAgentObservationOrder(value) {
+    if (value === undefined)
+        return "asc";
+    if (value !== "asc" && value !== "desc")
+        throw new Error(`Agent observation order must be "asc" or "desc".`);
+    return value;
+}
+export function normalizePiboAgentObservationLimit(value) {
+    if (value === undefined)
+        return PIBO_AGENT_OBSERVATION_DEFAULT_LIMIT;
+    if (!Number.isInteger(value) || value < 1 || value > PIBO_AGENT_OBSERVATION_MAX_LIMIT) {
+        throw new Error(`Agent observation limit must be an integer from 1 to ${PIBO_AGENT_OBSERVATION_MAX_LIMIT}.`);
+    }
+    return value;
+}
+export function normalizePiboAgentObservationCursor(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error("Agent observation afterSequence must be a non-negative integer.");
+    return value;
+}

package/dist/subagents/tool.js

@@ -1,16 +1,168 @@
 import { createHash } from "node:crypto";
 import { Type } from "typebox";
+import { piboStringEnum } from "../tools/schema.js";
 import { definePiboTool } from "../tools/contract.js";
-function hashPart(value) {
-    return createHash("sha256").update(value).digest("hex").slice(0, 12);
+export const PIBO_AGENT_TOOL_NAMES = [
+    "pibo_agents_send_message",
+    "pibo_agents_list_agents",
+    "pibo_agents_observe",
+    "pibo_agents_kill",
+];
+function availableAgentDescription(subagent) {
+    return subagent.description?.trim() || `Targets profile ${subagent.targetProfile}.`;
+}
+export function listAvailableAgents(subagents) {
+    return subagents
+        .filter((subagent) => subagent.enabled !== false)
+        .map((subagent) => ({
+        name: subagent.name,
+        description: availableAgentDescription(subagent),
+        profile: subagent.targetProfile,
+        ...(subagent.model ? { model: { ...subagent.model } } : {}),
+        ...(subagent.thinkingLevel ? { thinkingLevel: subagent.thinkingLevel } : {}),
+    }));
 }
-function toolNamePart(value) {
-    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
-    return normalized || `subagent_${hashPart(value)}`;
+export function formatAvailableAgentsForPrompt(subagents) {
+    return listAvailableAgents(subagents)
+        .map((agent) => `- ${agent.name}: ${agent.description}`)
+        .join("\n");
 }
+function resultText(prefix, value) {
+    return `${prefix}\n${JSON.stringify(value, null, 2)}`;
+}
+export function createAgentToolDefinitions(subagents, controller) {
+    const enabled = subagents.filter((subagent) => subagent.enabled !== false);
+    if (enabled.length === 0)
+        return [];
+    const byName = new Map();
+    for (const subagent of enabled) {
+        if (byName.has(subagent.name))
+            throw new Error(`Duplicate agent name "${subagent.name}"`);
+        byName.set(subagent.name, subagent);
+    }
+    const names = [...byName.keys()];
+    const availableAgents = listAvailableAgents(enabled);
+    const catalog = formatAvailableAgentsForPrompt(enabled);
+    return [
+        definePiboTool({
+            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.",
+                "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.",
+            executionMode: "parallel",
+            inputSchema: Type.Object({
+                name: piboStringEnum(names, { description: "Available delegated agent name" }),
+                message: Type.String({ description: "Message to send to the delegated agent" }),
+                threadKey: Type.Optional(Type.String({
+                    description: "Stable key for continuing one delegated-agent conversation. Omit it to create a new child session.",
+                    maxLength: 256,
+                })),
+            }),
+            async execute(toolCallId, params, signal) {
+                const subagent = byName.get(params.name);
+                if (!subagent)
+                    throw new Error(`Unknown delegated agent "${params.name}"`);
+                const result = await controller.sendMessage({
+                    subagent,
+                    message: params.message,
+                    threadKey: params.threadKey,
+                    toolCallId,
+                    signal,
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Agent ${result.name} (${result.agentId}, thread ${result.threadKey}) replied:\n${result.reply.text}`,
+                        }],
+                    details: result,
+                };
+            },
+        }),
+        definePiboTool({
+            name: "pibo_agents_list_agents",
+            title: "Pibo Agents List Agents",
+            description: "List available delegated-agent profiles and child agent instances owned by this session.",
+            promptSnippet: "List available delegated agents and existing child instances with their agentId, thread, profile, and running, idle, or killed status.",
+            executionMode: "parallel",
+            annotations: { readOnly: true },
+            inputSchema: Type.Object({}),
+            async execute() {
+                const result = { availableAgents, agents: controller.listAgents() };
+                return {
+                    content: [{ type: "text", text: resultText("Delegated agents:", result) }],
+                    details: result,
+                };
+            },
+        }),
+        definePiboTool({
+            name: "pibo_agents_observe",
+            title: "Pibo Agents Observe",
+            description: "Read bounded delegated-agent observations with exact agent, thread, event, kind, time, text, cursor, order, and limit filters.",
+            promptSnippet: "Observe child-agent activity. Array filters use OR within a field and different fields combine with AND. For cursor polling, pass afterSequence from the previous result; pages consume the oldest unseen observations even when order is desc.",
+            executionMode: "parallel",
+            annotations: { readOnly: true },
+            inputSchema: Type.Object({
+                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 })),
+                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" })),
+                afterSequence: Type.Optional(Type.Integer({ description: "Exclusive live observation cursor. Cursor pages consume the oldest unseen observations; desc reverses only the returned page.", minimum: 0 })),
+                order: Type.Optional(piboStringEnum(["asc", "desc"], { default: "asc" })),
+                limit: Type.Optional(Type.Integer({ description: "Maximum observations to return", minimum: 1, maximum: 200, default: 50 })),
+                includeDetails: Type.Optional(Type.Boolean({ description: "Include the normalized source event in each observation" })),
+            }),
+            async execute(_toolCallId, params) {
+                const result = controller.observe(params);
+                return {
+                    content: [{ type: "text", text: resultText("Agent observations:", result) }],
+                    details: result,
+                };
+            },
+        }),
+        definePiboTool({
+            name: "pibo_agents_kill",
+            title: "Pibo Agents Kill",
+            description: "Terminate one owned child agent session subtree and cancel its yielded runs.",
+            promptSnippet: "Kill an owned child agent by agentId when its work is no longer needed. Use pibo_agents_list_agents to find the exact agentId.",
+            executionMode: "parallel",
+            annotations: { destructive: true, idempotent: true },
+            inputSchema: Type.Object({
+                agentId: Type.String({ description: "Exact child agentId returned by send_message or list_agents" }),
+            }),
+            async execute(_toolCallId, params) {
+                const result = await controller.killAgent(params.agentId);
+                return {
+                    content: [{ type: "text", text: resultText(`Killed delegated agent ${params.agentId}.`, result) }],
+                    details: result,
+                };
+            },
+        }),
+    ];
+}
+function legacySubagentToolHash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+/**
+ * @deprecated Runtime-generated per-agent tools are no longer assembled by Pibo runtimes.
+ * This helper remains source-compatible for integrations migrating to PIBO_AGENT_TOOL_NAMES.
+ */
 export function createSubagentToolName(subagentName) {
-    return `pibo_subagent_${toolNamePart(subagentName)}`;
+    const normalized = subagentName.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+    return `pibo_subagent_${normalized || `subagent_${legacySubagentToolHash(subagentName)}`}`;
 }
+/**
+ * @deprecated Use createAgentToolDefinitions with a PiboAgentsController.
+ * Pibo runtimes expose only the four pibo_agents_* tools, but this legacy factory remains available
+ * for external callers during migration.
+ */
 export function createSubagentToolDefinitions(subagents, runner) {
     const seen = new Set();
     const definitions = [];
@@ -18,48 +170,27 @@ export function createSubagentToolDefinitions(subagents, runner) {
         if (subagent.enabled === false)
             continue;
         const toolName = createSubagentToolName(subagent.name);
-        if (seen.has(toolName)) {
+        if (seen.has(toolName))
             throw new Error(`Duplicate subagent tool name "${toolName}"`);
-        }
         seen.add(toolName);
-        definitions.push(createSubagentToolDefinition(subagent, runner));
+        definitions.push(definePiboTool({
+            name: toolName,
+            title: `Pibo Subagent ${subagent.name}`,
+            description: subagent.description ?? `Send a message to the ${subagent.name} subagent. Use threadKey to continue the same subagent session.`,
+            promptSnippet: subagent.description ?? `Send a message to the ${subagent.name} subagent. Pass the same threadKey when you want to continue the same subagent session.`,
+            executionMode: "parallel",
+            inputSchema: Type.Object({
+                message: Type.String({ description: "Message to send to the subagent" }),
+                threadKey: Type.Optional(Type.String({
+                    description: "Stable key for continuing a previous subagent conversation. Omit it to create a new subagent session.",
+                    maxLength: 256,
+                })),
+            }),
+            async execute(toolCallId, params, signal) {
+                const result = await runner.runSubagent({ subagent, message: params.message, threadKey: params.threadKey, toolCallId, signal });
+                return { content: [{ type: "text", text: result.reply.text }], details: result };
+            },
+        }));
     }
     return definitions;
 }
-function createSubagentToolDefinition(subagent, runner) {
-    const name = createSubagentToolName(subagent.name);
-    return definePiboTool({
-        name,
-        title: `Pibo Subagent ${subagent.name}`,
-        description: subagent.description ??
-            `Send a message to the ${subagent.name} subagent. Use threadKey to continue the same subagent session.`,
-        promptSnippet: subagent.description ??
-            `Send a message to the ${subagent.name} subagent. Pass the same threadKey when you want to continue the same subagent session.`,
-        executionMode: "parallel",
-        inputSchema: Type.Object({
-            message: Type.String({ description: "Message to send to the subagent" }),
-            threadKey: Type.Optional(Type.String({
-                description: "Stable key for continuing a previous subagent conversation. Omit it to create a new subagent session.",
-                maxLength: 256,
-            })),
-        }),
-        async execute(toolCallId, params, signal) {
-            const result = await runner.runSubagent({
-                subagent,
-                message: params.message,
-                threadKey: params.threadKey,
-                toolCallId,
-                signal,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: result.reply.text,
-                    },
-                ],
-                details: result,
-            };
-        },
-    });
-}

package/dist/tools/session-service.js

@@ -53,6 +53,7 @@ export class PiboPortableToolService {
                 cwd,
             },
             controllers: {
+                agentsController: input.agentsController,
                 subagentRunner: input.subagentRunner,
                 runToolController: input.runToolController,
                 runtimeToolController: input.runtimeToolController,

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

@@ -1,6 +1,6 @@
 import { createPiboGoalToolDefinitions, PIBO_GOAL_TOOL_NAMES } from "../loops/tools.js";
 import { createRunToolDefinitions } from "../runs/tools.js";
-import { createSubagentToolDefinitions } from "../subagents/tool.js";
+import { createAgentToolDefinitions } from "../subagents/tool.js";
 import { CODEX_BROWSER_TOOL_NAMES, createCodexBrowserToolDefinitions, } from "./codex-browser.js";
 import { createCodexCompatToolDefinitions } from "./codex-compat.js";
 import { createRuntimeToolDefinition } from "./runtime/tool.js";
@@ -18,6 +18,7 @@ export function isEnabledCodexBrowserToolProfile(tool) {
 }
 export function isGeneratedPiboTool(name) {
     return name === "runtime"
+        || name.startsWith("pibo_agents_")
         || name.startsWith("pibo_subagent_")
         || name.startsWith("pibo_run_")
         || PIBO_GOAL_TOOL_NAMES.includes(name);
@@ -33,6 +34,9 @@ function getToolDefinition(tool, context = {}) {
 /** Assemble the selected Pibo-managed tool set without importing any harness package. */
 export function createPiboSessionToolDefinitions(options) {
     const { profile } = options;
+    if (profile.subagents.some((subagent) => subagent.enabled !== false) && options.subagentRunner && !options.agentsController) {
+        throw new Error("CreatePiboSessionToolDefinitionsOptions.subagentRunner is retired. Provide agentsController so the session can expose the four pibo_agents_* management tools.");
+    }
     const runtimeProfileTool = profile.tools.find(isEnabledRuntimeToolProfile);
     const runtimeTool = runtimeProfileTool && options.runtimeToolController
         ? createRuntimeToolDefinition(options.runtimeToolController)
@@ -53,8 +57,8 @@ export function createPiboSessionToolDefinitions(options) {
     const goalTools = profile.toolPackages.goalControl !== false
         ? createPiboGoalToolDefinitions(options.toolContext ?? {})
         : [];
-    const subagentTools = options.subagentRunner
-        ? createSubagentToolDefinitions(profile.subagents, options.subagentRunner)
+    const agentTools = options.agentsController
+        ? createAgentToolDefinitions(profile.subagents, options.agentsController)
         : [];
     const nativeYieldableTools = [...(options.nativeYieldableTools ?? [])];
     const yieldableTools = [
@@ -64,7 +68,7 @@ export function createPiboSessionToolDefinitions(options) {
             .map((tool) => getToolDefinition(tool, options.toolContext)),
         ...(runtimeTool && runtimeProfileTool?.yieldable !== false ? [runtimeTool] : []),
         ...codexBrowserTools.filter((definition) => profile.tools.find((tool) => tool.name === definition.name)?.yieldable !== false),
-        ...subagentTools,
+        ...agentTools,
         ...codexCompatTools,
     ];
     const runTools = profile.toolPackages.runControl === true
@@ -77,7 +81,7 @@ export function createPiboSessionToolDefinitions(options) {
         ...profileToolDefinitions,
         ...(runtimeTool ? [runtimeTool] : []),
         ...codexBrowserTools,
-        ...subagentTools,
+        ...agentTools,
         ...codexCompatTools,
         ...goalTools,
         ...runTools,

package/dist/web/channel.js

@@ -78,7 +78,13 @@ export function stripSocketPeerHeaderFromResponse(response) {
         headers,
     });
 }
-function createRequestBaseURL(nodeRequest, host, port) {
+function createRequestBaseURL(nodeRequest, host, port, canonicalBaseURL) {
+    const requestHost = firstHeaderValue(nodeRequest.headers.host);
+    if (canonicalBaseURL && requestHost) {
+        const canonical = new URL(canonicalBaseURL);
+        if (requestHost.toLowerCase() === canonical.host.toLowerCase())
+            return canonical.origin;
+    }
     if (isLoopbackAddress(nodeRequest.socket.remoteAddress)) {
         const forwardedHost = firstHeaderValue(nodeRequest.headers["x-forwarded-host"]);
         const forwardedProto = firstHeaderValue(nodeRequest.headers["x-forwarded-proto"]);
@@ -86,7 +92,7 @@ function createRequestBaseURL(nodeRequest, host, port) {
             return `${forwardedProto}://${forwardedHost}`;
         }
     }
-    return `http://${nodeRequest.headers.host ?? `${host}:${port}`}`;
+    return `http://${requestHost ?? `${host}:${port}`}`;
 }
 function isActiveRunStatus(status) {
     return typeof status === "string" && ["queued", "starting", "running", "streaming", "waiting", "blocked", "retrying", "compacting", "pausing"].includes(status);
@@ -235,7 +241,7 @@ export function createWebHostChannel(options = {}) {
     };
     const handleRequest = async (nodeRequest, nodeResponse) => {
         try {
-            const baseURL = createRequestBaseURL(nodeRequest, host, port);
+            const baseURL = createRequestBaseURL(nodeRequest, host, port, options.canonicalBaseURL);
             const baseRequest = await nodeRequestToWebRequest(nodeRequest, baseURL);
             // Inject the TCP socket peer into every request so the local auth
             // plugin can apply the same loopback predicate from `getSession`

package/npm-shrinkwrap.json

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

package/package.json

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