@pasko70/pibo 3.0.1 → 3.1.0

package/dist/data/schema.js

@@ -1,9 +1,155 @@
-export const PIBO_DATA_SCHEMA_VERSION = 6;
-export function applyPiboDataSchema(db) {
-    const previousVersion = Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+export const PIBO_DATA_SCHEMA_VERSION = 7;
+const retiredScopeColumn = ["owner", "scope"].join("_");
+const retiredScopeTables = [
+    {
+        name: "sessions",
+        columns: [
+            "id", "pi_session_id", "room_id", "root_session_id", "parent_id", "origin_id",
+            "channel", "kind", "profile", "active_model_json", "workspace", "title",
+            "first_message_preview", "status", "archived_at", "deleted_at", "metadata_json",
+            "created_at", "updated_at", "last_activity_at",
+        ],
+        definition: `
+			id TEXT PRIMARY KEY,
+			pi_session_id TEXT UNIQUE,
+			room_id TEXT,
+			root_session_id TEXT,
+			parent_id TEXT,
+			origin_id TEXT,
+			channel TEXT NOT NULL,
+			kind TEXT NOT NULL,
+			profile TEXT NOT NULL,
+			active_model_json TEXT,
+			workspace TEXT,
+			title TEXT NOT NULL DEFAULT 'Untitled Session',
+			first_message_preview TEXT,
+			status TEXT NOT NULL DEFAULT 'idle',
+			archived_at TEXT,
+			deleted_at TEXT,
+			metadata_json TEXT NOT NULL DEFAULT '{}',
+			created_at TEXT NOT NULL,
+			updated_at TEXT NOT NULL,
+			last_activity_at TEXT NOT NULL
+		`,
+    },
+    {
+        name: "rooms",
+        columns: [
+            "id", "name", "topic", "type", "parent_room_id", "workspace", "archived_at",
+            "retention_policy_id", "metadata_json", "created_at", "updated_at",
+        ],
+        definition: `
+			id TEXT PRIMARY KEY,
+			name TEXT NOT NULL,
+			topic TEXT,
+			type TEXT NOT NULL,
+			parent_room_id TEXT,
+			workspace TEXT,
+			archived_at TEXT,
+			retention_policy_id TEXT,
+			metadata_json TEXT NOT NULL DEFAULT '{}',
+			created_at TEXT NOT NULL,
+			updated_at TEXT NOT NULL
+		`,
+    },
+    {
+        name: "session_navigation",
+        columns: [
+            "room_id", "session_id", "root_session_id", "parent_id", "origin_id", "title",
+            "profile", "status", "archived_at", "last_activity_at", "last_message_preview",
+            "child_count", "sort_key", "updated_at",
+        ],
+        definition: `
+			room_id TEXT,
+			session_id TEXT PRIMARY KEY,
+			root_session_id TEXT,
+			parent_id TEXT,
+			origin_id TEXT,
+			title TEXT NOT NULL,
+			profile TEXT NOT NULL,
+			status TEXT NOT NULL,
+			archived_at TEXT,
+			last_activity_at TEXT NOT NULL,
+			last_message_preview TEXT,
+			child_count INTEGER NOT NULL DEFAULT 0,
+			sort_key TEXT NOT NULL,
+			updated_at TEXT NOT NULL
+		`,
+    },
+];
+function retiredScopeTablesToRebuild(db) {
+    return retiredScopeTables.filter((table) => ((db.prepare(`SELECT 1 FROM pragma_table_info('${table.name}') WHERE name = ?`).get(retiredScopeColumn)) !== undefined));
+}
+function rebuildRetiredScopeTables(db, tablesToRebuild) {
+    for (const table of tablesToRebuild) {
+        const replacement = `__pibo_schema_v7_${table.name}`;
+        const columnList = table.columns.join(", ");
+        db.exec(`
+			CREATE TABLE ${replacement} (${table.definition});
+			INSERT INTO ${replacement} (${columnList}) SELECT ${columnList} FROM ${table.name};
+			DROP TABLE ${table.name};
+			ALTER TABLE ${replacement} RENAME TO ${table.name};
+		`);
+    }
+}
+export function assertSupportedPiboDataSchemaVersion(db) {
+    const version = Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+    if (version > PIBO_DATA_SCHEMA_VERSION) {
+        throw new Error(`Pibo database schema version ${version} is newer than supported version ${PIBO_DATA_SCHEMA_VERSION}`);
+    }
+    return version;
+}
+export const PIBO_DATA_SCHEMA_MIGRATION_STEPS = [
+    "schema",
+    "runtime-bindings",
+    "render-high-water",
+    "sequence-repair-selection",
+    "sequence-repair-temporary",
+    "sequence-repair-backfill",
+    "sequence-repair-cleanup",
+    "runtime-binding-metadata",
+    "user-version",
+];
+export function applyPiboDataSchema(db, hooks = {}) {
+    const previousVersion = assertSupportedPiboDataSchemaVersion(db);
+    const tablesToRebuild = retiredScopeTablesToRebuild(db);
+    const ownsTransaction = !db.isTransaction;
+    if (!ownsTransaction && tablesToRebuild.length > 0) {
+        throw new Error("Pibo data schema migration requires an independent transaction");
+    }
+    const foreignKeysEnabled = ownsTransaction
+        && tablesToRebuild.length > 0
+        && Number(db.prepare("PRAGMA foreign_keys").get().foreign_keys ?? 0) === 1;
+    if (foreignKeysEnabled)
+        db.exec("PRAGMA foreign_keys = OFF");
+    try {
+        if (ownsTransaction)
+            db.exec("BEGIN IMMEDIATE");
+        applyPiboDataSchemaInTransaction(db, hooks, previousVersion, tablesToRebuild);
+        if (tablesToRebuild.length > 0) {
+            const violations = db.prepare("PRAGMA foreign_key_check").all();
+            if (violations.length > 0) {
+                throw new Error(`Pibo data schema migration would retain ${violations.length} foreign-key violation(s)`);
+            }
+        }
+        if (ownsTransaction)
+            db.exec("COMMIT");
+    }
+    catch (error) {
+        if (ownsTransaction && db.isTransaction)
+            db.exec("ROLLBACK");
+        throw error;
+    }
+    finally {
+        if (foreignKeysEnabled)
+            db.exec("PRAGMA foreign_keys = ON");
+    }
+}
+function applyPiboDataSchemaInTransaction(db, hooks, previousVersion, tablesToRebuild) {
     const existingSessionCount = db.prepare("SELECT COUNT(*) AS count FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'").get();
     const hadSessionsBeforeMigration = existingSessionCount.count > 0
         && Number(db.prepare("SELECT COUNT(*) AS count FROM sessions").get().count) > 0;
+    rebuildRetiredScopeTables(db, tablesToRebuild);
     db.exec(`
 		CREATE TABLE IF NOT EXISTS sessions (
 			id TEXT PRIMARY KEY,
@@ -46,6 +192,42 @@ export function applyPiboDataSchema(db) {
 			FOREIGN KEY (pibo_session_id) REFERENCES sessions(id) ON DELETE CASCADE
 		);
 
+		CREATE TABLE IF NOT EXISTS session_output_render_high_water (
+			pibo_session_id TEXT PRIMARY KEY,
+			high_water INTEGER NOT NULL CHECK(high_water >= 0),
+			updated_at TEXT NOT NULL,
+			FOREIGN KEY (pibo_session_id) REFERENCES sessions(id) ON DELETE CASCADE
+		);
+
+		CREATE TABLE IF NOT EXISTS session_tool_invocation_counters (
+			pibo_session_id TEXT NOT NULL,
+			event_id TEXT NOT NULL,
+			tool_call_id TEXT NOT NULL,
+			next_ordinal INTEGER NOT NULL CHECK(next_ordinal >= 0),
+			updated_at TEXT NOT NULL,
+			PRIMARY KEY (pibo_session_id, event_id, tool_call_id),
+			FOREIGN KEY (pibo_session_id) REFERENCES sessions(id) ON DELETE CASCADE
+		);
+
+		CREATE TABLE IF NOT EXISTS session_tool_invocations (
+			pibo_session_id TEXT NOT NULL,
+			event_id TEXT NOT NULL,
+			tool_call_id TEXT NOT NULL,
+			invocation_ordinal INTEGER NOT NULL CHECK(invocation_ordinal >= 0),
+			call_fingerprint TEXT,
+			status TEXT NOT NULL CHECK(status IN ('open', 'closed')),
+			seen_call INTEGER NOT NULL DEFAULT 0 CHECK(seen_call IN (0, 1)),
+			seen_started INTEGER NOT NULL DEFAULT 0 CHECK(seen_started IN (0, 1)),
+			seen_updated INTEGER NOT NULL DEFAULT 0 CHECK(seen_updated IN (0, 1)),
+			seen_finished INTEGER NOT NULL DEFAULT 0 CHECK(seen_finished IN (0, 1)),
+			created_at TEXT NOT NULL,
+			updated_at TEXT NOT NULL,
+			PRIMARY KEY (pibo_session_id, event_id, tool_call_id, invocation_ordinal),
+			FOREIGN KEY (pibo_session_id) REFERENCES sessions(id) ON DELETE CASCADE
+		);
+		CREATE INDEX IF NOT EXISTS idx_session_tool_invocations_open
+			ON session_tool_invocations(pibo_session_id, event_id, tool_call_id, status, invocation_ordinal DESC);
+
 		CREATE UNIQUE INDEX IF NOT EXISTS idx_session_runtime_bindings_native
 			ON session_runtime_bindings(runtime_adapter_id, native_session_id)
 			WHERE native_session_id IS NOT NULL;
@@ -516,6 +698,7 @@ export function applyPiboDataSchema(db) {
 		CREATE INDEX IF NOT EXISTS idx_telemetry_tool_calls_retention_updated
 			ON telemetry_tool_calls(retention_class, updated_at);
 	`);
+    hooks.afterStep?.("schema");
     db.exec(`
 		INSERT OR IGNORE INTO session_runtime_bindings (
 			pibo_session_id, runtime_instance_id, runtime_adapter_id, native_session_id,
@@ -536,6 +719,61 @@ export function applyPiboDataSchema(db) {
 			WHERE existing.pibo_session_id = sessions.id
 		);
 	`);
+    hooks.afterStep?.("runtime-bindings");
+    db.exec(`
+		INSERT INTO session_output_render_high_water (pibo_session_id, high_water, updated_at)
+		SELECT
+			id,
+			CAST(json_extract(metadata_json, '$.outputRenderSequenceHighWater') AS INTEGER),
+			updated_at
+		FROM sessions
+		WHERE json_type(metadata_json, '$.outputRenderSequenceHighWater') IN ('integer', 'real')
+			AND CAST(json_extract(metadata_json, '$.outputRenderSequenceHighWater') AS INTEGER) >= 0
+		ON CONFLICT(pibo_session_id) DO UPDATE SET
+			high_water = MAX(session_output_render_high_water.high_water, excluded.high_water),
+			updated_at = CASE
+				WHEN excluded.high_water > session_output_render_high_water.high_water THEN excluded.updated_at
+				ELSE session_output_render_high_water.updated_at
+			END;
+	`);
+    hooks.afterStep?.("render-high-water");
+    // Always inspect for interrupted pre-atomic v7 repairs. A previous process
+    // may have written negative temporary values before setting user_version.
+    db.exec(`
+		DROP TABLE IF EXISTS temp.pibo_v7_sequence_repair_sessions;
+		CREATE TEMP TABLE pibo_v7_sequence_repair_sessions (
+			session_id TEXT PRIMARY KEY
+		);
+		INSERT INTO pibo_v7_sequence_repair_sessions (session_id)
+		SELECT DISTINCT session_id
+		FROM event_log
+		WHERE session_id IS NOT NULL
+			AND (session_sequence IS NULL OR session_sequence <= 0);
+	`);
+    hooks.afterStep?.("sequence-repair-selection");
+    db.exec(`
+		UPDATE event_log
+		SET session_sequence = -stream_id
+		WHERE session_id IN (SELECT session_id FROM pibo_v7_sequence_repair_sessions);
+	`);
+    hooks.afterStep?.("sequence-repair-temporary");
+    db.exec(`
+		WITH ranked AS (
+			SELECT
+				stream_id,
+				ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY stream_id ASC) AS repaired_sequence
+			FROM event_log
+			WHERE session_id IN (SELECT session_id FROM pibo_v7_sequence_repair_sessions)
+		)
+		UPDATE event_log
+		SET session_sequence = (
+			SELECT repaired_sequence FROM ranked WHERE ranked.stream_id = event_log.stream_id
+		)
+		WHERE stream_id IN (SELECT stream_id FROM ranked);
+	`);
+    hooks.afterStep?.("sequence-repair-backfill");
+    db.exec("DROP TABLE pibo_v7_sequence_repair_sessions");
+    hooks.afterStep?.("sequence-repair-cleanup");
     if (previousVersion < PIBO_DATA_SCHEMA_VERSION && hadSessionsBeforeMigration) {
         const rows = db.prepare("SELECT pibo_session_id, metadata_json FROM session_runtime_bindings").all();
         const update = db.prepare("UPDATE session_runtime_bindings SET metadata_json = ? WHERE pibo_session_id = ?");
@@ -558,5 +796,7 @@ export function applyPiboDataSchema(db) {
             }), row.pibo_session_id);
         }
     }
+    hooks.afterStep?.("runtime-binding-metadata");
     db.exec(`PRAGMA user_version = ${PIBO_DATA_SCHEMA_VERSION}`);
+    hooks.afterStep?.("user-version");
 }

package/dist/data/session-store.js

@@ -43,10 +43,10 @@ export class SessionStore {
             "workspace = excluded.workspace",
             "title = excluded.title",
             "first_message_preview = COALESCE(sessions.first_message_preview, excluded.first_message_preview)",
-            "status = excluded.status",
+            ...(input.status === undefined ? [] : ["status = excluded.status"]),
             "metadata_json = excluded.metadata_json",
-            "updated_at = excluded.updated_at",
-            "last_activity_at = excluded.last_activity_at",
+            "updated_at = MAX(sessions.updated_at, excluded.updated_at)",
+            "last_activity_at = MAX(sessions.last_activity_at, excluded.last_activity_at)",
         ];
         this.db.prepare(`
 			INSERT INTO sessions (${baseColumns.join(", ")})

package/dist/debug/agents.js

@@ -1,4 +1,5 @@
-import { normalizePiboAgentObservationCursor, normalizePiboAgentObservationLimit, normalizePiboAgentObservationOrder, parsePiboAgentObservationTimestamp, piboAgentObservationDetails, piboAgentObservationKind, piboAgentObservationRole, piboAgentObservationText, } from "../subagents/observations.js";
+import { normalizePiboAgentObservationLimit, piboAgentObservationDetails, piboAgentObservationKind, piboAgentObservationRole, piboAgentObservationText, } from "../subagents/observations.js";
+import { preparePiboAgentObservationQuery, selectPiboAgentObservationPage, } from "../subagents/observation-query.js";
 import { createDebugPayloadStore, hydrateDebugEventRow } from "./persisted-payloads.js";
 import { eventAttributes, eventPayload } from "./payloads.js";
 import { openReadOnlyDebugDatabase, withStorePath } from "./sql.js";
@@ -36,17 +37,21 @@ export async function runDebugAgentsCli(args) {
         return;
     }
     const result = inspectDebugAgentObservations(parentPiboSessionId, store, {
+        toolCallIds: parsed.toolCallIds.length ? parsed.toolCallIds : undefined,
         agentIds: parsed.agentIds.length ? parsed.agentIds : undefined,
         names: parsed.names.length ? parsed.names : undefined,
         threadKeys: parsed.threadKeys.length ? parsed.threadKeys : undefined,
         eventTypes: parsed.eventTypes.length ? parsed.eventTypes : undefined,
         kinds: parsed.kinds.length ? parsed.kinds : undefined,
+        roles: parsed.roles.length ? parsed.roles : undefined,
         since: parsed.since,
         until: parsed.until,
         textContains: parsed.textContains,
         afterSequence: parsed.afterSequence,
         order: parsed.order,
         limit: parsed.limit,
+        includeTools: parsed.includeTools || undefined,
+        toolDetail: parsed.toolDetail,
         includeDetails: parsed.details,
     });
     if (parsed.json)
@@ -75,104 +80,70 @@ export function inspectDebugAgentObservations(parentPiboSessionId, store, input
         throw new Error(`Debug store "pibo-data" not found at ${store.path}`);
     const db = openReadOnlyDebugDatabase(store);
     try {
-        const order = normalizePiboAgentObservationOrder(input.order);
-        const limit = normalizePiboAgentObservationLimit(input.limit);
-        const afterSequence = normalizePiboAgentObservationCursor(input.afterSequence);
-        const since = parsePiboAgentObservationTimestamp(input.since, "since");
-        const until = parsePiboAgentObservationTimestamp(input.until, "until");
-        if (since !== undefined && until !== undefined && since > until)
-            throw new Error("Agent observation since must not be after until.");
+        const query = preparePiboAgentObservationQuery(input);
         const owned = readOwnedAgents(db, parentPiboSessionId);
         const ownedById = new Map(owned.map((agent) => [agent.agentId, agent]));
         for (const agentId of input.agentIds ?? []) {
             if (!ownedById.has(agentId))
                 throw new Error(`Agent "${agentId}" is not owned by Pibo session "${parentPiboSessionId}".`);
         }
-        const agentIds = input.agentIds ? new Set(input.agentIds) : undefined;
-        const names = input.names ? new Set(input.names) : undefined;
-        const threadKeys = input.threadKeys ? new Set(input.threadKeys) : undefined;
-        const eventTypes = input.eventTypes ? new Set(input.eventTypes) : undefined;
-        const kinds = input.kinds ? new Set(input.kinds) : undefined;
         const payloadStore = createDebugPayloadStore(db, store);
         const clauses = ["s.parent_id = ?", "s.channel = 'pibo.subagents'", "s.kind = 'subagent'", "s.deleted_at IS NULL"];
         const values = [parentPiboSessionId];
-        if (afterSequence !== undefined) {
+        if (query.afterSequence !== undefined) {
             clauses.push("e.stream_id > ?");
-            values.push(afterSequence);
+            values.push(query.afterSequence);
+        }
+        if (query.scanEventTypes && query.scanEventTypes.length > 0) {
+            clauses.push(`e.type IN (${query.scanEventTypes.map(() => "?").join(", ")})`);
+            values.push(...query.scanEventTypes);
         }
-        const scanOrder = afterSequence !== undefined ? "ASC" : order.toUpperCase();
         const statement = db.prepare(`
 			SELECT e.stream_id, e.session_id, e.session_sequence, e.event_id, e.type, e.created_at,
 				e.payload_ref, e.preview_text, e.attributes_json, s.profile, s.metadata_json
 			FROM event_log e
 			JOIN sessions s ON s.id = e.session_id
 			WHERE ${clauses.join(" AND ")}
-			ORDER BY e.stream_id ${scanOrder}
+			ORDER BY e.stream_id ${query.scanOrder.toUpperCase()}
 		`);
-        const textContains = input.textContains?.toLowerCase();
-        const matches = [];
-        for (const rawRow of statement.iterate(...values)) {
-            const agent = ownedById.get(rawRow.session_id ?? "");
-            if (!agent)
-                continue;
-            if (agentIds && !agentIds.has(agent.agentId))
-                continue;
-            if (names && !names.has(agent.name))
-                continue;
-            if (threadKeys && (!agent.threadKey || !threadKeys.has(agent.threadKey)))
-                continue;
-            if (eventTypes && !eventTypes.has(rawRow.type))
-                continue;
-            const kind = piboAgentObservationKind(rawRow.type);
-            if (kinds && !kinds.has(kind))
-                continue;
-            const createdAt = Date.parse(rawRow.created_at);
-            if (since !== undefined && createdAt < since)
-                continue;
-            if (until !== undefined && createdAt > until)
-                continue;
-            const row = hydrateDebugEventRow(rawRow, payloadStore);
-            const attributes = eventAttributes(row);
-            const payload = { ...attributes, ...eventPayload(row) };
-            const source = debugAgentObservationSource(row, attributes);
-            const text = piboAgentObservationText(source);
-            if (textContains && !(text ?? "").toLowerCase().includes(textContains))
-                continue;
-            const role = piboAgentObservationRole(source);
-            matches.push({
-                streamId: row.stream_id,
-                createdAt: row.created_at,
-                agentId: agent.agentId,
-                name: agent.name,
-                ...(agent.threadKey ? { threadKey: agent.threadKey } : {}),
-                eventType: row.type,
-                kind,
-                ...(role ? { role } : {}),
-                ...(text ? { text } : {}),
-                ...(typeof payload.toolName === "string" ? { toolName: payload.toolName } : {}),
-                ...(typeof payload.toolCallId === "string" ? { toolCallId: payload.toolCallId } : {}),
-                ...(row.type === "tool_execution_finished" ? { isError: payload.isError === true } : row.type === "session_error" ? { isError: true } : {}),
-                ...(input.includeDetails === true ? { details: piboAgentObservationDetails(debugAgentObservationDetails(row, payload)) } : {}),
-            });
-            if (matches.length > limit)
-                break;
+        function* normalizedObservations() {
+            for (const rawRow of statement.iterate(...values)) {
+                const agent = ownedById.get(rawRow.session_id ?? "");
+                if (!agent)
+                    continue;
+                const row = hydrateDebugEventRow(rawRow, payloadStore);
+                const attributes = eventAttributes(row);
+                const payload = { ...attributes, ...eventPayload(row) };
+                const source = debugAgentObservationSource(row, attributes);
+                const text = piboAgentObservationText(source);
+                const role = piboAgentObservationRole(source);
+                yield {
+                    sequence: row.stream_id,
+                    createdAt: row.created_at,
+                    agentId: agent.agentId,
+                    name: agent.name,
+                    ...(agent.threadKey ? { threadKey: agent.threadKey } : {}),
+                    eventType: row.type,
+                    kind: piboAgentObservationKind(row.type),
+                    ...(role ? { role } : {}),
+                    ...(text ? { text } : {}),
+                    ...(typeof payload.toolName === "string" ? { toolName: payload.toolName } : {}),
+                    ...(typeof payload.toolCallId === "string" ? { toolCallId: payload.toolCallId } : {}),
+                    ...(row.type === "tool_execution_finished" ? { isError: payload.isError === true } : row.type === "session_error" ? { isError: true } : {}),
+                    details: piboAgentObservationDetails(debugAgentObservationDetails(row, payload, source)),
+                };
+            }
         }
-        const truncated = matches.length > limit;
-        const observations = matches.slice(0, limit);
-        if (afterSequence !== undefined && order === "desc")
-            observations.reverse();
+        const page = selectPiboAgentObservationPage(normalizedObservations(), query);
         return {
             parentPiboSessionId,
-            filters: {
-                ...input,
-                ...(afterSequence !== undefined ? { afterSequence } : {}),
-                order,
-                limit,
-                includeDetails: input.includeDetails === true,
-            },
-            observations,
-            nextAfterSequence: observations.reduce((maximum, observation) => Math.max(maximum, observation.streamId), afterSequence ?? 0),
-            truncated,
+            filters: page.filters,
+            observations: page.observations.map(({ sequence, ...observation }) => ({
+                streamId: sequence,
+                ...observation,
+            })),
+            nextAfterSequence: page.nextAfterSequence,
+            truncated: page.truncated,
         };
     }
     catch (error) {
@@ -237,12 +208,15 @@ function debugAgentObservationSource(row, attributes) {
         source.subagentName = attributes.subagentName;
     return source;
 }
-function debugAgentObservationDetails(row, payload) {
+function debugAgentObservationDetails(row, payload, source) {
     return {
         type: row.type,
         ...(row.session_id ? { piboSessionId: row.session_id } : {}),
         ...(row.event_id ? { eventId: row.event_id } : {}),
         ...payload,
+        ...(source.args !== undefined ? { args: source.args } : {}),
+        ...(source.partialResult !== undefined ? { partialResult: source.partialResult } : {}),
+        ...(source.result !== undefined ? { result: source.result } : {}),
     };
 }
 function parseObject(value) {
@@ -306,17 +280,31 @@ Filters use exact values. The command inspects only direct pibo.subagents childr
     console.log(`pibo debug agents ${parentPiboSessionId} observe
 
 Usage:
-  pibo debug agents ${parentPiboSessionId} observe [--agent-id ps_...] [--name name] [--thread-key key]
-    [--event-type type] [--kind message|thinking|tool|error|lifecycle|event]
-    [--since iso] [--until iso] [--contains text] [--after-sequence n]
-    [--order asc|desc] [--limit 1..200] [--details] [--json]
+  pibo debug agents ${parentPiboSessionId} observe [--tool-call-id id] [--agent-id ps_...] [--name name]
+    [--thread-key key] [--event-type type] [--kind message|thinking|tool|error|lifecycle|event]
+    [--role role] [--since iso] [--until iso] [--contains text] [--after-sequence n]
+    [--order asc|desc] [--limit 1..200] [--include-tools]
+    [--tool-detail summary|full] [--details] [--json]
 
-Repeat --agent-id, --name, --thread-key, --event-type, or --kind for OR within that field.
+Default: the newest 20 completed assistant messages, with streaming deltas and tools hidden.
+Use --include-tools for compact tool calls and terminal results. Explicit --event-type or --kind
+filters retain access to progress events. Repeat plural filters for OR within that field.
 Different fields combine with AND. With --after-sequence, pages always consume the oldest unseen rows;
 --order desc reverses only the returned page, so nextAfterSequence remains safe for polling.`);
 }
 function parseAgentDebugOptions(args) {
-    const parsed = { json: false, details: false, agentIds: [], names: [], threadKeys: [], eventTypes: [], kinds: [] };
+    const parsed = {
+        json: false,
+        details: false,
+        includeTools: false,
+        toolCallIds: [],
+        agentIds: [],
+        names: [],
+        threadKeys: [],
+        eventTypes: [],
+        kinds: [],
+        roles: [],
+    };
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === "--json") {
@@ -327,10 +315,16 @@ function parseAgentDebugOptions(args) {
             parsed.details = true;
             continue;
         }
+        if (arg === "--include-tools") {
+            parsed.includeTools = true;
+            continue;
+        }
         const value = args[index + 1];
         if (!value)
             throw new Error(`${arg} requires a value`);
-        if (arg === "--agent-id")
+        if (arg === "--tool-call-id")
+            parsed.toolCallIds.push(value);
+        else if (arg === "--agent-id")
             parsed.agentIds.push(value);
         else if (arg === "--name")
             parsed.names.push(value);
@@ -343,6 +337,8 @@ function parseAgentDebugOptions(args) {
                 throw new Error(`Invalid --kind "${value}"`);
             parsed.kinds.push(value);
         }
+        else if (arg === "--role")
+            parsed.roles.push(value);
         else if (arg === "--status") {
             if (!["running", "idle", "killed"].includes(value))
                 throw new Error(`Invalid --status "${value}"`);
@@ -363,6 +359,11 @@ function parseAgentDebugOptions(args) {
         }
         else if (arg === "--limit")
             parsed.limit = normalizePiboAgentObservationLimit(parseNonNegativeInteger(value, arg));
+        else if (arg === "--tool-detail") {
+            if (value !== "summary" && value !== "full")
+                throw new Error(`Invalid --tool-detail "${value}"`);
+            parsed.toolDetail = value;
+        }
         else
             throw new Error(`Unknown pibo debug agents option "${arg}"`);
         index += 1;
@@ -373,10 +374,11 @@ function validateAgentDebugOptions(command, parsed) {
     if (command === "list") {
         if (parsed.names.length > 1)
             throw new Error("pibo debug agents list accepts at most one --name value");
-        if (parsed.details || parsed.agentIds.length > 0 || parsed.threadKeys.length > 0 || parsed.eventTypes.length > 0
-            || parsed.kinds.length > 0 || parsed.since !== undefined || parsed.until !== undefined
+        if (parsed.details || parsed.includeTools || parsed.toolCallIds.length > 0 || parsed.agentIds.length > 0
+            || parsed.threadKeys.length > 0 || parsed.eventTypes.length > 0 || parsed.kinds.length > 0
+            || parsed.roles.length > 0 || parsed.since !== undefined || parsed.until !== undefined
             || parsed.textContains !== undefined || parsed.afterSequence !== undefined || parsed.order !== undefined
-            || parsed.limit !== undefined)
+            || parsed.limit !== undefined || parsed.toolDetail !== undefined)
             throw new Error("Unsupported option for pibo debug agents list. Run the list command with --help.");
         return;
     }