@pasko70/pibo 3.4.0 → 3.4.2

package/dist/shared/tool-call-metrics.js

@@ -0,0 +1,77 @@
+/** Bounded structural walk; never tokenize, copy or scan large strings. */
+export function estimateToolPayloadTokens(payload) {
+    let budget = 10_000;
+    const seen = new WeakSet();
+    function size(value, depth) {
+        if (--budget < 0 || depth > 64)
+            return NaN;
+        if (typeof value === "string")
+            return value.length;
+        if (value === null)
+            return 4;
+        if (typeof value === "boolean")
+            return value ? 4 : 5;
+        if (typeof value === "number")
+            return String(value).length;
+        if (typeof value !== "object" || seen.has(value))
+            return NaN;
+        seen.add(value);
+        let chars = 2;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                chars += size(item, depth + 1) + 1;
+                if (!Number.isFinite(chars))
+                    return NaN;
+            }
+        }
+        else {
+            const record = value;
+            // Binary/media payloads have no meaningful character-based token count.
+            if (["image", "audio", "document", "resource", "image_url"].includes(String(record.type)))
+                return NaN;
+            for (const key in record) {
+                if (--budget < 0)
+                    return NaN;
+                if (!Object.hasOwn(record, key) || record[key] === undefined)
+                    continue;
+                chars += key.length + 3 + size(record[key], depth + 1) + 1;
+                if (!Number.isFinite(chars))
+                    return NaN;
+            }
+        }
+        seen.delete(value);
+        return chars;
+    }
+    try {
+        const chars = size(payload, 0);
+        return Number.isFinite(chars) ? Math.ceil(chars / 4) : undefined;
+    }
+    catch {
+        // Diagnostics must not turn an otherwise successful tool into a failure.
+        return undefined;
+    }
+}
+export class ToolCallMetricsCollector {
+    active = new Map();
+    start(id, args, now = performance.now()) {
+        if (this.active.has(id))
+            return;
+        this.active.set(id, { startedAt: now, inputTokens: estimateToolPayloadTokens(args) });
+    }
+    finish(id, result, now = performance.now()) {
+        const started = this.active.get(id);
+        this.active.delete(id);
+        // Harness result metadata is not model-visible tool output.
+        const output = result && typeof result === "object" && "content" in result
+            ? result.content : result;
+        return {
+            tokenBasis: "chars/4",
+            durationMs: started ? Math.max(0, now - started.startedAt) : undefined,
+            inputTokens: started?.inputTokens,
+            outputTokens: estimateToolPayloadTokens(output),
+        };
+    }
+    clear() {
+        this.active.clear();
+    }
+}

package/dist/shared/trace-event-projection.js

@@ -626,6 +626,7 @@ function traceNodeFromEvent(piboSessionId, event, childByParent, linkedChildByTo
                 toolCallId: event.toolCallId,
                 toolInvocationOrdinal: event.toolInvocationOrdinal ?? 0,
                 intent: event.intent,
+                toolMetrics: event.type === "tool_execution_finished" ? event.toolMetrics : undefined,
                 type: subagentTool ? "agent.delegation" : "tool.call",
                 title: event.toolName,
                 status: event.type === "tool_execution_finished"
@@ -1102,6 +1103,7 @@ function thinkingEventNodeId(event) {
 function mergeToolEvent(target, update) {
     target.status = update.status;
     target.intent = update.intent ?? target.intent;
+    target.toolMetrics = update.toolMetrics ?? target.toolMetrics;
     target.summary = update.summary ?? target.summary;
     target.input = mergeDelegationInput(target, update);
     target.output = update.output ?? target.output;

package/dist/shared/trace-live-reducer.js

@@ -122,6 +122,7 @@ function storedEventFromStreamEvent(event, piboSessionId, nextSequence, now) {
             toolName: event.toolName,
             toolInvocationOrdinal: validOrdinal(event.toolInvocationOrdinal) ? event.toolInvocationOrdinal : undefined,
             result: event.result,
+            toolMetrics: event.toolMetrics,
             isError: Boolean(event.isError),
             ...(event.intent ? { intent: event.intent } : {}),
         };

package/dist/shared/trace-patch-nodes.js

@@ -60,6 +60,10 @@ function traceNodeShallowEqual(left, right) {
         left.startedAt === right.startedAt &&
         left.completedAt === right.completedAt &&
         left.durationMs === right.durationMs &&
+        left.toolMetrics?.durationMs === right.toolMetrics?.durationMs &&
+        left.toolMetrics?.inputTokens === right.toolMetrics?.inputTokens &&
+        left.toolMetrics?.outputTokens === right.toolMetrics?.outputTokens &&
+        left.toolMetrics?.tokenBasis === right.toolMetrics?.tokenBasis &&
         left.summary === right.summary &&
         left.input === right.input &&
         left.output === right.output &&

package/dist/subagents/context.js

@@ -33,14 +33,14 @@ export function getDelegatedAgentContextFile(subagents) {
             "",
             "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], textContains?, textRegex?, afterSequence?, limit?, includeTools?, toolDetail?, ... })",
+            "pibo_agents_observe({ requestIds?: [runId], cursorMode?: \"auto\"|\"history\", textContains?, textRegex?, afterSequence?, limit?, includeTools?, toolDetail?, ... })",
             "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",
             "```",
             "",
-            "Set `sessionName` on every send to a nonblank human-readable child title of at most 40 Unicode code points. Pibo trims surrounding whitespace and rejects missing, blank, non-string, or oversized names before creating a yielded run or child session. Reuse a stable `threadKey` to continue the same child Pibo Session; a new `sessionName` updates its title without changing identity. A wait timeout is only an orchestrator wake-up. Observe defaults to the newest 20 completed assistant messages with streaming deltas, duplicate tool progress events, and tools hidden. Use `textContains` for case-insensitive substring matching or `textRegex` for case-sensitive rg/Rust-regex matching; both must match when supplied together. Set `includeTools: true` for compact tool call/result summaries, `toolDetail: \"full\"` only for bounded diagnostics, and `limit: 50` when a larger page is necessary. Use `afterSequence` from the prior result for polling.",
+            "Set `sessionName` on every send to a nonblank human-readable child title of at most 40 Unicode code points. Pibo trims surrounding whitespace and rejects missing, blank, non-string, or oversized names before creating a yielded run or child session. Reuse a stable `threadKey` to continue the same child Pibo Session; a new `sessionName` updates its title without changing identity. A wait timeout only wakes the orchestrator. Observe uses `cursorMode: \"auto\"` by default: the first equivalent query returns the newest completed assistant messages, and later calls return only unread messages. Use `cursorMode: \"history\"` only to reread earlier observations. Streaming deltas, duplicate tool progress events, and tools are hidden by default. Inspect tools only when a child stalls, reports an error, or needs targeted diagnosis; prefer exact `toolCallIds`, then `includeTools: true`, and use `toolDetail: \"full\"` only when summaries are insufficient. Use `textContains` for case-insensitive substring matching or `textRegex` for rg/Rust-regex matching; both must match when supplied together. Text, regex, identity, and event filters create separate automatic query cursors; an explicit `afterSequence` overrides and advances the matching automatic cursor.",
             "",
             "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.",
             "",

package/dist/subagents/observation-query.js

@@ -1,6 +1,31 @@
-import { PIBO_AGENT_OBSERVATION_DEFAULT_EVENT_TYPES, PIBO_AGENT_OBSERVATION_DEFAULT_TOOL_EVENT_TYPES, normalizePiboAgentObservationCursor, normalizePiboAgentObservationLimit, normalizePiboAgentObservationOrder, normalizePiboAgentObservationToolDetail, parsePiboAgentObservationTimestamp, piboAgentObservationKind, piboAgentObservationToolSummary, } from "./observations.js";
+import { createHash } from "node:crypto";
+import { PIBO_AGENT_OBSERVATION_DEFAULT_EVENT_TYPES, PIBO_AGENT_OBSERVATION_DEFAULT_TOOL_EVENT_TYPES, normalizePiboAgentObservationCursor, normalizePiboAgentObservationCursorMode, normalizePiboAgentObservationLimit, normalizePiboAgentObservationOrder, normalizePiboAgentObservationToolDetail, parsePiboAgentObservationTimestamp, piboAgentObservationKind, piboAgentObservationToolSummary, } from "./observations.js";
 import { PIBO_AGENT_TEXT_REGEX_BATCH_MAX_ITEMS, PIBO_AGENT_TEXT_REGEX_BATCH_TARGET_BYTES, matchPiboAgentObservationTextRegex, preparePiboAgentObservationTextRegex, } from "./observation-text-regex.js";
+function sortedUnique(values) {
+    return values ? [...new Set(values)].sort() : undefined;
+}
+export function piboAgentObservationCursorScopeKey(input) {
+    const scope = {
+        requestIds: sortedUnique(input.requestIds),
+        toolCallIds: sortedUnique(input.toolCallIds),
+        agentIds: sortedUnique(input.agentIds),
+        names: sortedUnique(input.names),
+        threadKeys: sortedUnique(input.threadKeys),
+        eventTypes: sortedUnique(input.eventTypes),
+        kinds: input.kinds ? [...new Set(input.kinds)].sort() : undefined,
+        roles: sortedUnique(input.roles),
+        since: input.since,
+        until: input.until,
+        textContains: input.textContains?.toLowerCase(),
+        textRegex: input.textRegex,
+        includeTools: input.includeTools === true,
+        toolDetail: input.toolDetail ?? "summary",
+        includeDetails: input.includeDetails === true,
+    };
+    return `v1:${createHash("sha256").update(JSON.stringify(scope)).digest("hex")}`;
+}
 export function preparePiboAgentObservationQuery(input = {}) {
+    const cursorMode = normalizePiboAgentObservationCursorMode(input.cursorMode);
     const order = normalizePiboAgentObservationOrder(input.order);
     const limit = normalizePiboAgentObservationLimit(input.limit);
     const toolDetail = normalizePiboAgentObservationToolDetail(input.toolDetail);
@@ -40,6 +65,7 @@ export function preparePiboAgentObservationQuery(input = {}) {
     return {
         filters: {
             ...input,
+            cursorMode,
             ...(defaultMessageView ? { eventTypes: defaultEventTypes } : {}),
             ...(afterSequence !== undefined ? { afterSequence } : {}),
             order,
@@ -49,6 +75,7 @@ export function preparePiboAgentObservationQuery(input = {}) {
             includeDetails: input.includeDetails === true,
         },
         ...(afterSequence !== undefined ? { afterSequence } : {}),
+        cursorMode,
         order,
         scanOrder: afterSequence !== undefined ? "asc" : order,
         limit,

package/dist/subagents/observations.js

@@ -212,6 +212,14 @@ export function normalizePiboAgentObservationOrder(value) {
         throw new Error(`Agent observation order must be "asc" or "desc".`);
     return value;
 }
+export function normalizePiboAgentObservationCursorMode(value) {
+    if (value === undefined)
+        return "auto";
+    if (value !== "auto" && value !== "history") {
+        throw new Error(`Agent observation cursorMode must be "auto" or "history".`);
+    }
+    return value;
+}
 export function normalizePiboAgentObservationToolDetail(value) {
     if (value === undefined)
         return "summary";

package/dist/subagents/tool.js

@@ -60,12 +60,15 @@ function preparePiboDeprecatedSubagentToolInput(input) {
 export function formatAgentObservationsForModel(result) {
     const includeTools = result.filters.includeTools === true;
     const toolDetail = result.filters.toolDetail ?? "summary";
+    const cursorMode = result.filters.cursorMode ?? "auto";
     const lines = [
-        `Agent observations (${result.observations.length}; tools=${includeTools ? toolDetail : "hidden"}; order=${result.filters.order ?? "desc"}; limit=${result.filters.limit ?? 20})`,
-        `nextAfterSequence=${result.nextAfterSequence}; truncated=${result.truncated}`,
+        `Agent observations (${result.observations.length}; cursor=${cursorMode}; tools=${includeTools ? toolDetail : "hidden"}; order=${result.filters.order ?? "desc"}; limit=${result.filters.limit ?? 20})`,
+        `afterSequence=${result.filters.afterSequence ?? "initial"}; nextAfterSequence=${result.nextAfterSequence}${result.autoCursorSequence === undefined ? "" : `; autoCursorSequence=${result.autoCursorSequence}`}; truncated=${result.truncated}`,
     ];
     if (result.observations.length === 0) {
-        lines.push("", "No delegated-agent observations matched the filters.");
+        lines.push("", cursorMode === "auto"
+            ? "No new delegated-agent messages matched since the automatic cursor. Use cursorMode=\"history\" only when you need to reread earlier observations."
+            : "No historical delegated-agent observations matched the filters.");
         return lines.join("\n");
     }
     for (const observation of result.observations) {
@@ -188,10 +191,10 @@ export function createAgentToolDefinitions(subagents, controller) {
             title: "Pibo Agents Observe",
             description: [
                 "Read completed delegated-agent messages with bounded cursor, identity, event, time, substring, regex, order, and limit filters.",
-                "Default: the newest 20 completed assistant messages, with streaming deltas and tools hidden.",
-                "Set includeTools=true to add compact tool calls and terminal results, or pass toolCallIds to retrieve only those exact tool observations. Set toolDetail=full only for bounded diagnostic inspection.",
+                "Default cursorMode=auto: the first equivalent query returns the newest 20 completed assistant messages; later calls return only unread messages. Streaming deltas, duplicate tool progress events, and tools stay hidden.",
+                "Use cursorMode=history only to reread earlier observations. Inspect tools only when an agent appears stuck, reports a problem, or needs targeted diagnosis; prefer exact toolCallIds, then includeTools=true, and use toolDetail=full only when compact summaries are insufficient.",
             ].join("\n"),
-            promptSnippet: "Observe child-agent progress through completed assistant messages. Defaults: newest 20 messages, no streaming deltas, no duplicate tool progress events, no tools. Use textContains for case-insensitive substring matching or textRegex for case-sensitive rg/Rust-regex matching; when both are present, both must match. Set includeTools=true for compact tool call/result summaries, pass up to 50 exact toolCallIds to retrieve only those tool observations, use toolDetail=full for bounded raw tool text, or eventTypes/kinds for explicit progress diagnostics. Compact tool entries expose their toolCallId for follow-up queries. Pass afterSequence from the previous result for cursor polling; cursor pages consume the oldest unseen matches even when order is desc.",
+            promptSnippet: "Observe child progress through completed assistant messages. cursorMode=auto is the default and remembers each equivalent query, so repeated calls return only unread messages; use cursorMode=history to reread earlier observations. Streaming deltas, duplicate tool progress events, and tools are hidden by default. Inspect tools only for stalls, errors, or targeted diagnosis: prefer exact toolCallIds, use includeTools=true only when broader context is needed, and use toolDetail=full only when summaries are insufficient. Use textContains or textRegex for focused matching; different filters use separate automatic cursors. An explicit afterSequence overrides the stored cursor and advances that automatic query cursor.",
             executionMode: "parallel",
             annotations: { readOnly: true },
             inputSchema: Type.Object({
@@ -207,10 +210,11 @@ export function createAgentToolDefinitions(subagents, controller) {
                 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" })),
                 textRegex: Type.Optional(Type.String({ description: "Case-sensitive rg/Rust-regex match against normalized observation text. Use inline flags such as (?i) to change case behavior. Combines with textContains using AND semantics. NUL text and literal or escaped NUL patterns are rejected; regex use requires the optional rg platform binary." })),
-                afterSequence: Type.Optional(Type.Integer({ description: "Exclusive live observation cursor. Cursor pages consume the oldest unseen matches; desc reverses only the returned page.", minimum: 0 })),
+                cursorMode: Type.Optional(piboStringEnum(["auto", "history"], { default: "auto", description: "auto remembers this normalized query and returns only unread observations after its first newest-message snapshot. history ignores and does not change the saved cursor, allowing deliberate rereads." })),
+                afterSequence: Type.Optional(Type.Integer({ description: "Explicit exclusive cursor override. In auto mode it replaces and advances the saved cursor for this normalized query; cursor pages consume the oldest unseen matches and desc reverses only the returned page.", minimum: 0 })),
                 order: Type.Optional(piboStringEnum(["asc", "desc"], { default: "desc", description: "Newest first by default when no cursor is supplied" })),
                 limit: Type.Optional(Type.Integer({ description: "Maximum completed messages or activity records to return. Use 50 explicitly when needed.", minimum: 1, maximum: 200, default: 20 })),
-                includeTools: Type.Optional(Type.Boolean({ description: "Include tools. Default false. With the default message view, true adds tool_call and tool_execution_finished records.", default: false })),
+                includeTools: Type.Optional(Type.Boolean({ description: "Include compact tool calls and terminal results. Default false; enable only for stalls, errors, or targeted diagnosis. Prefer exact toolCallIds when known.", default: false })),
                 toolDetail: Type.Optional(piboStringEnum(["summary", "full"], { default: "summary", description: "Tool text detail when tools are included. summary is compact; full remains bounded to the observation text limit." })),
                 includeDetails: Type.Optional(Type.Boolean({ description: "Include the normalized source event in structured details. Default false; use only for diagnostics.", default: false })),
             }),

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pasko70/pibo",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",