@pasko70/pibo 1.1.0 → 1.2.0

package/dist/debug/index.js

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { getPiboHome } from "../core/pibo-home.js";
 import { resolveDebugStore, resolveDebugStores } from "./stores.js";
 export async function runDebugCli(argv = process.argv) {
     try {
@@ -18,6 +20,26 @@ export async function runDebugCli(argv = process.argv) {
             await runDebugTrace(args.slice(1));
             return;
         }
+        if (args[0] === "summary") {
+            await runDebugSummary(args.slice(1));
+            return;
+        }
+        if (args[0] === "messages") {
+            await runDebugMessages(args.slice(1));
+            return;
+        }
+        if (args[0] === "final") {
+            await runDebugFinal(args.slice(1));
+            return;
+        }
+        if (args[0] === "tool") {
+            await runDebugTool(args.slice(1));
+            return;
+        }
+        if (args[0] === "failures") {
+            await runDebugFailures(args.slice(1));
+            return;
+        }
         if (args[0] === "events") {
             await runDebugEvents(args.slice(1));
             return;
@@ -30,6 +52,24 @@ export async function runDebugCli(argv = process.argv) {
             await runDebugRuns(args.slice(1));
             return;
         }
+        if (args[0] === "signals") {
+            await runDebugSignals(args.slice(1));
+            return;
+        }
+        if (args[0] === "telemetry") {
+            await runDebugTelemetry(args.slice(1));
+            return;
+        }
+        if (args[0] === "web") {
+            const { runDebugWeb } = await import("./web.js");
+            await runDebugWeb(args.slice(1));
+            return;
+        }
+        if (args[0] === "pty") {
+            const { runDebugPty } = await import("./pty.js");
+            await runDebugPty(args.slice(1));
+            return;
+        }
         throw new Error(`Unknown pibo debug command "${args[0]}". Run pibo debug --help.`);
     }
     catch (error) {
@@ -50,7 +90,7 @@ async function runDebugDb(args) {
             console.log(JSON.stringify({ stores }, null, 2));
             return;
         }
-        console.log(["store\tpath\texists\tdescription", ...stores.map((store) => `${store.name}\t${store.defaultPath}\t${store.exists}\t${store.description}`)].join("\n"));
+        console.log(["store\tpath\texists\tdescription", ...stores.map((store) => `${store.name}\t${store.path}\t${store.exists}\t${store.description}`)].join("\n"));
         return;
     }
     const storeName = options.positionals[0];
@@ -111,6 +151,250 @@ async function runDebugSession(args) {
     else
         console.log(formatDebugSessionSummary(summary));
 }
+async function runDebugSummary(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugSummaryDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const input = options.positionals[0];
+    if (!input)
+        throw new Error("pibo debug summary requires <pibo-session-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugSummary, inspectDebugSummary } = await import("./summary.js");
+    const result = await inspectDebugSummary(input, { sessions: resolveDebugStore("sessions"), chat: resolveDebugStore("chat") });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatDebugSummary(result));
+}
+async function runDebugMessages(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugMessagesDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const piboSessionId = options.positionals[0];
+    const command = options.positionals[1] ?? "list";
+    if (!piboSessionId)
+        throw new Error("pibo debug messages requires <pibo-session-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugMessageShow, formatDebugMessagesList, inspectDebugMessageShow, inspectDebugMessagesList } = await import("./messages.js");
+    if (command === "list") {
+        const result = inspectDebugMessagesList(piboSessionId, resolveDebugStore("chat"), { limit: options.limit });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatDebugMessagesList(result));
+        return;
+    }
+    if (command === "show") {
+        const selector = options.positionals[2];
+        if (!selector)
+            throw new Error("pibo debug messages <pibo-session-id> show requires <selector>");
+        const result = inspectDebugMessageShow(piboSessionId, resolveDebugStore("chat"), selector, detailOptions(options));
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatDebugMessageShow(result, { plain: options.plain }));
+        return;
+    }
+    throw new Error(`Unknown pibo debug messages command "${command}". Run pibo debug messages --help.`);
+}
+async function runDebugFinal(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugFinalDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const piboSessionId = options.positionals[0];
+    if (!piboSessionId)
+        throw new Error("pibo debug final requires <pibo-session-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugMessageShow, inspectDebugMessageShow } = await import("./messages.js");
+    const result = inspectDebugMessageShow(piboSessionId, resolveDebugStore("chat"), "assistant:last", { ...detailOptions(options), final: true });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatDebugMessageShow(result, { plain: options.plain, final: true }));
+}
+async function runDebugTool(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugToolDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const piboSessionId = options.positionals[0];
+    const toolCallId = options.positionals[1];
+    if (!piboSessionId || !toolCallId)
+        throw new Error("pibo debug tool requires <pibo-session-id> <tool-call-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugTool, inspectDebugTool } = await import("./tools.js");
+    const result = inspectDebugTool(piboSessionId, resolveDebugStore("chat"), toolCallId, { ...detailOptions(options), args: options.args, output: options.output, error: options.error });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatDebugTool(result, { args: options.args, output: options.output, error: options.error }));
+}
+async function runDebugFailures(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugFailuresDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const piboSessionId = options.positionals[0];
+    if (!piboSessionId)
+        throw new Error("pibo debug failures requires <pibo-session-id>");
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugFailures, inspectDebugFailures } = await import("./failures.js");
+    const result = await inspectDebugFailures(piboSessionId, { sessions: resolveDebugStore("sessions"), chat: resolveDebugStore("chat") }, { limit: options.limit });
+    if (options.json)
+        console.log(formatJson(result));
+    else
+        console.log(formatDebugFailures(result));
+}
+async function runDebugSignals(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugSignalsDiscovery();
+        return;
+    }
+    const command = args[0];
+    const options = parseOptions(args.slice(1));
+    const piboSessionId = options.positionals[0];
+    if ((command !== "session" && command !== "tree") || !piboSessionId) {
+        throw new Error("pibo debug signals requires session <pibo-session-id> or tree <root-pibo-session-id>");
+    }
+    const baseUrl = process.env.PIBO_GATEWAY_URL ?? process.env.PIBO_WEB_URL;
+    if (!baseUrl)
+        throw new Error("Set PIBO_GATEWAY_URL to inspect live signal state through Chat Web APIs.");
+    const url = new URL(`/api/chat/signals/${command}/${encodeURIComponent(piboSessionId)}`, baseUrl);
+    const headers = new Headers();
+    if (options.cookie)
+        headers.set("cookie", readCookieHeaderFile(options.cookie));
+    if (options.authHeader)
+        headers.set("authorization", options.authHeader);
+    const response = await fetch(url, { headers });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok)
+        throw new Error(payload && typeof payload === "object" && "error" in payload ? String(payload.error) : `Request failed: ${response.status}`);
+    if (options.json) {
+        const { formatJson } = await import("./sql.js");
+        console.log(formatJson(payload));
+    }
+    else {
+        console.log(formatSignalSnapshotText(payload));
+    }
+}
+async function runDebugTelemetry(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printDebugTelemetryDiscovery();
+        return;
+    }
+    const command = args[0];
+    const options = parseOptions(args.slice(1));
+    const { formatJson } = await import("./sql.js");
+    const { formatTelemetryProvider, formatTelemetryProviderEvents, formatTelemetryProviderPayload, formatTelemetryPrune, formatTelemetrySession, formatTelemetrySessions, formatTelemetryStale, formatTelemetryStats, formatTelemetryTool, formatTelemetryTurn, inspectTelemetryProvider, inspectTelemetryProviderEvents, inspectTelemetryProviderPayload, inspectTelemetryPrune, inspectTelemetrySession, inspectTelemetrySessions, inspectTelemetryStale, inspectTelemetryStats, inspectTelemetryTool, inspectTelemetryTurn, } = await import("./telemetry.js");
+    const store = resolveDebugStore("pibo-data");
+    if (command === "sessions") {
+        const result = inspectTelemetrySessions(store, { limit: options.limit, active: options.active, stale: options.stale });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetrySessions(result));
+        return;
+    }
+    if (command === "session") {
+        const piboSessionId = options.positionals[0];
+        if (!piboSessionId)
+            throw new Error("pibo debug telemetry session requires <pibo-session-id>");
+        const result = inspectTelemetrySession(store, piboSessionId, { limit: options.limit });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetrySession(result));
+        return;
+    }
+    if (command === "turn") {
+        const turnIdOrEventId = options.positionals[0];
+        if (!turnIdOrEventId)
+            throw new Error("pibo debug telemetry turn requires <turn-id-or-event-id>");
+        const result = inspectTelemetryTurn(store, turnIdOrEventId, { limit: options.limit, events: options.events });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryTurn(result));
+        return;
+    }
+    if (command === "provider") {
+        const providerRequestId = options.positionals[0];
+        if (!providerRequestId)
+            throw new Error("pibo debug telemetry provider requires <provider-request-id>");
+        const subcommand = options.positionals[1];
+        if (subcommand === "events") {
+            const result = inspectTelemetryProviderEvents(store, providerRequestId, { limit: options.limit, after: options.after, fields: options.fields });
+            if (options.json)
+                console.log(formatJson(result));
+            else
+                console.log(formatTelemetryProviderEvents(result));
+            return;
+        }
+        if (subcommand === "payload") {
+            const payloadRef = options.positionals[2];
+            if (!payloadRef)
+                throw new Error("pibo debug telemetry provider <provider-request-id> payload requires <preview-or-event-summary-id>");
+            const result = inspectTelemetryProviderPayload(store, providerRequestId, payloadRef);
+            if (options.json)
+                console.log(formatJson(result));
+            else
+                console.log(formatTelemetryProviderPayload(result));
+            return;
+        }
+        if (subcommand)
+            throw new Error(`Unknown pibo debug telemetry provider subcommand "${subcommand}". Run pibo debug telemetry --help.`);
+        const result = inspectTelemetryProvider(store, providerRequestId);
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryProvider(result));
+        return;
+    }
+    if (command === "tool") {
+        const toolCallId = options.positionals[0];
+        if (!toolCallId)
+            throw new Error("pibo debug telemetry tool requires <tool-call-id>");
+        const result = inspectTelemetryTool(store, toolCallId);
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryTool(result));
+        return;
+    }
+    if (command === "stale") {
+        const result = inspectTelemetryStale(store, { limit: options.limit, thresholdMs: options.thresholdMs });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryStale(result));
+        return;
+    }
+    if (command === "stats") {
+        const result = inspectTelemetryStats(store, { retention: options.retention });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryStats(result));
+        return;
+    }
+    if (command === "prune") {
+        const result = inspectTelemetryPrune(store, { retention: options.retention, before: options.before, apply: options.apply });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatTelemetryPrune(result));
+        return;
+    }
+    throw new Error(`Unknown pibo debug telemetry command "${command}". Run pibo debug telemetry --help.`);
+}
 async function runDebugTrace(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugTraceDiscovery();
@@ -120,32 +404,60 @@ async function runDebugTrace(args) {
     const piboSessionId = options.positionals[0];
     if (!piboSessionId)
         throw new Error("pibo debug trace requires <pibo-session-id>");
-    const { formatJson } = await import("./sql.js");
-    const { formatDebugTrace, inspectDebugTrace } = await import("./trace.js");
-    const result = await inspectDebugTrace(piboSessionId, {
+    const stores = {
         sessions: resolveDebugStore("sessions"),
         chat: resolveDebugStore("chat"),
-    }, {
+    };
+    const { formatJson } = await import("./sql.js");
+    const { formatDebugTrace, formatDebugTraceNode, inspectDebugTrace, inspectDebugTraceNode } = await import("./trace.js");
+    if (options.positionals[1] === "show") {
+        const nodeId = options.positionals[2];
+        if (!nodeId)
+            throw new Error("pibo debug trace <pibo-session-id> show requires <node-id>");
+        const result = await inspectDebugTraceNode(piboSessionId, stores, nodeId);
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatDebugTraceNode(result));
+        return;
+    }
+    const result = await inspectDebugTrace(piboSessionId, stores, {
         runningOnly: options.runningOnly,
         check: options.check,
     });
     if (options.json)
         console.log(formatJson(result));
     else
-        console.log(formatDebugTrace(result));
+        console.log(formatDebugTrace(result, { medium: options.medium }));
 }
 async function runDebugEvents(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugEventsDiscovery();
         return;
     }
+    if (args[0] === "compact-deltas") {
+        const options = parseOptions(args.slice(1));
+        const { formatJson } = await import("./sql.js");
+        const { formatDeltaCompaction, runDeltaCompaction } = await import("./delta-compaction.js");
+        const result = runDeltaCompaction({
+            apply: options.apply,
+            store: options.store,
+            session: options.key,
+            json: options.json,
+        });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatDeltaCompaction(result));
+        return;
+    }
     if (args[0] === "stream") {
         const options = parseOptions(args.slice(1));
         const { formatJson, formatRows } = await import("./sql.js");
         const { PiboReliabilityStore } = await import("../reliability/store.js");
         const store = resolveDebugStore("reliability");
         if (!store.exists)
-            throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+            throw new Error(`Debug store "reliability" not found at ${store.path}`);
         const reliability = new PiboReliabilityStore(store.path);
         try {
             const events = reliability.list({
@@ -169,7 +481,7 @@ async function runDebugEvents(args) {
         const { PiboReliabilityStore } = await import("../reliability/store.js");
         const store = resolveDebugStore("reliability");
         if (!store.exists)
-            throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+            throw new Error(`Debug store "reliability" not found at ${store.path}`);
         const reliability = new PiboReliabilityStore(store.path);
         try {
             const counts = reliability.countEvents({
@@ -193,7 +505,7 @@ async function runDebugEvents(args) {
         const { PiboReliabilityStore } = await import("../reliability/store.js");
         const store = resolveDebugStore("reliability");
         if (!store.exists)
-            throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+            throw new Error(`Debug store "reliability" not found at ${store.path}`);
         if (!options.topic || !options.retention || !options.before) {
             throw new Error("pibo debug events prune requires --topic, --retention, and --before");
         }
@@ -229,7 +541,7 @@ async function runDebugEvents(args) {
         const { PiboReliabilityStore } = await import("../reliability/store.js");
         const store = resolveDebugStore("reliability");
         if (!store.exists)
-            throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+            throw new Error(`Debug store "reliability" not found at ${store.path}`);
         const reliability = new PiboReliabilityStore(store.path);
         try {
             const consumers = reliability.listConsumers();
@@ -244,11 +556,29 @@ async function runDebugEvents(args) {
         return;
     }
     const options = parseOptions(args);
-    const piboSessionId = options.positionals[0];
+    let piboSessionId = options.positionals[0];
+    let command = options.positionals[1] ?? "list";
+    if (piboSessionId === "list") {
+        piboSessionId = options.positionals[1];
+        command = "list";
+    }
     if (!piboSessionId)
         throw new Error("pibo debug events requires <pibo-session-id>");
     const { formatJson } = await import("./sql.js");
-    const { formatDebugEvents, inspectDebugEvents } = await import("./events.js");
+    const { formatDebugEventShow, formatDebugEvents, inspectDebugEventShow, inspectDebugEvents } = await import("./events.js");
+    if (command === "show") {
+        const selector = options.positionals[2];
+        if (!selector)
+            throw new Error("pibo debug events <pibo-session-id> show requires <stream-id-or-event-id>");
+        const result = inspectDebugEventShow(piboSessionId, resolveDebugStore("chat"), selector, { ...detailOptions(options), payload: options.payload, raw: options.raw, field: options.field });
+        if (options.json)
+            console.log(formatJson(result));
+        else
+            console.log(formatDebugEventShow(result));
+        return;
+    }
+    if (command !== "list")
+        throw new Error(`Unknown pibo debug events command "${command}". Run pibo debug events --help.`);
     const result = inspectDebugEvents(piboSessionId, resolveDebugStore("chat"), {
         type: options.type,
         fields: options.fields,
@@ -270,7 +600,7 @@ async function runDebugJobs(args) {
     const { PiboReliabilityStore } = await import("../reliability/store.js");
     const store = resolveDebugStore("reliability");
     if (!store.exists)
-        throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+        throw new Error(`Debug store "reliability" not found at ${store.path}`);
     const reliability = new PiboReliabilityStore(store.path);
     try {
         if (command === "list") {
@@ -317,14 +647,14 @@ async function runDebugRuns(args) {
     const { PiboReliabilityStore } = await import("../reliability/store.js");
     const store = resolveDebugStore("reliability");
     if (!store.exists)
-        throw new Error(`Debug store "reliability" not found at ${store.defaultPath}`);
+        throw new Error(`Debug store "reliability" not found at ${store.path}`);
     const reliability = new PiboReliabilityStore(store.path);
     try {
         if (command === "list") {
             const piboSessionId = options.positionals[0];
             if (!piboSessionId)
                 throw new Error("pibo debug runs list requires <pibo-session-id>");
-            const runs = reliability.listRuns({ ownerPiboSessionId: piboSessionId, includeConsumed: true, includeDetached: true });
+            const runs = reliability.listRuns({ controllerPiboSessionId: piboSessionId, includeConsumed: true, includeDetached: true });
             if (options.json)
                 console.log(formatJson({ runs }));
             else
@@ -350,8 +680,27 @@ async function runDebugRuns(args) {
         reliability.close();
     }
 }
+function readCookieHeaderFile(path) {
+    const content = readFileSync(path, "utf8").trim();
+    const cookies = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .flatMap((line) => {
+        const normalized = line.startsWith("#HttpOnly_") ? line.slice("#HttpOnly_".length) : line;
+        if (normalized.startsWith("#"))
+            return [];
+        const fields = normalized.split("\t");
+        if (fields.length >= 7)
+            return [`${fields[5]}=${fields[6]}`];
+        return [normalized];
+    });
+    if (cookies.length === 0)
+        throw new Error(`Cookie file "${path}" does not contain any cookies`);
+    return cookies.join("; ");
+}
 function parseOptions(args) {
-    const parsed = { positionals: [], json: false, events: false, runningOnly: false, check: false, destructive: false };
+    const parsed = { positionals: [], json: false, events: false, runningOnly: false, check: false, medium: false, destructive: false, apply: false, dryRun: false, full: false, noTruncate: false, plain: false, raw: false, payload: false, args: false, output: false, error: false, active: false, stale: false };
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === "--json") {
@@ -370,7 +719,43 @@ function parseOptions(args) {
             parsed.check = true;
             continue;
         }
-        if (arg === "--children") {
+        if (arg === "--medium") {
+            parsed.medium = true;
+            continue;
+        }
+        if (arg === "--full") {
+            parsed.full = true;
+            continue;
+        }
+        if (arg === "--no-truncate") {
+            parsed.noTruncate = true;
+            continue;
+        }
+        if (arg === "--plain") {
+            parsed.plain = true;
+            continue;
+        }
+        if (arg === "--raw") {
+            parsed.raw = true;
+            continue;
+        }
+        if (arg === "--payload") {
+            parsed.payload = true;
+            continue;
+        }
+        if (arg === "--args") {
+            parsed.args = true;
+            continue;
+        }
+        if (arg === "--output") {
+            parsed.output = true;
+            continue;
+        }
+        if (arg === "--error") {
+            parsed.error = true;
+            continue;
+        }
+        if (arg === "--children" || arg === "--tool-output") {
             continue;
         }
         if (arg === "--limit") {
@@ -397,6 +782,14 @@ function parseOptions(args) {
             index += 1;
             continue;
         }
+        if (arg === "--field") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--field requires a value");
+            parsed.field = value;
+            index += 1;
+            continue;
+        }
         if (arg === "--topic") {
             const value = args[index + 1];
             if (!value)
@@ -441,6 +834,78 @@ function parseOptions(args) {
             parsed.destructive = true;
             continue;
         }
+        if (arg === "--apply") {
+            parsed.apply = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            parsed.dryRun = true;
+            continue;
+        }
+        if (arg === "--active") {
+            parsed.active = true;
+            continue;
+        }
+        if (arg === "--stale") {
+            parsed.stale = true;
+            continue;
+        }
+        if (arg === "--cookie") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--cookie requires a path");
+            parsed.cookie = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--auth-header") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--auth-header requires a value");
+            parsed.authHeader = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--threshold-ms") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--threshold-ms requires a value");
+            parsed.thresholdMs = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--store") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--store requires a value");
+            parsed.store = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--max-bytes") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--max-bytes requires a value");
+            parsed.maxBytes = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--from") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--from requires a value");
+            parsed.from = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--bytes") {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error("--bytes requires a value");
+            parsed.bytes = value;
+            index += 1;
+            continue;
+        }
         if (arg === "--queue") {
             const value = args[index + 1];
             if (!value)
@@ -453,6 +918,15 @@ function parseOptions(args) {
     }
     return parsed;
 }
+function detailOptions(options) {
+    return {
+        maxBytes: options.maxBytes,
+        from: options.from,
+        bytes: options.bytes,
+        noTruncate: options.noTruncate,
+        full: options.full,
+    };
+}
 function compactEventRow(event) {
     return {
         streamId: event.streamId,
@@ -488,7 +962,7 @@ function compactDeadJobRow(job) {
 function compactRunRow(run) {
     return {
         runId: run.runId,
-        piboSessionId: run.ownerPiboSessionId,
+        piboSessionId: run.controllerPiboSessionId,
         status: run.status,
         toolName: run.toolName,
         policy: run.completionPolicy,
@@ -497,6 +971,21 @@ function compactRunRow(run) {
         summary: run.summary,
     };
 }
+function formatSignalSnapshotText(snapshot) {
+    const sessions = Object.values(snapshot.sessions ?? {});
+    const nodes = Object.values(snapshot.nodes ?? {});
+    const activeNodes = nodes.filter((node) => ["queued", "starting", "running", "streaming", "waiting", "blocked", "retrying", "compacting", "pausing"].includes(node.status));
+    const errors = sessions.filter((session) => session.hasError || session.hasErrorDescendant);
+    return [
+        `root\t${snapshot.rootPiboSessionId ?? "unknown"}`,
+        `version\t${snapshot.version ?? 0}`,
+        `sessions\t${sessions.length}`,
+        `nodes\t${nodes.length}`,
+        `active_nodes\t${activeNodes.length}`,
+        `error_sessions\t${errors.length}`,
+        ...sessions.map((session) => `${session.piboSessionId}\tlocal=${session.localStatus}\taggregate=${session.aggregateStatus}\tphase=${session.phase ?? "-"}\tactive=${session.isTreeActive}`),
+    ].join("\n");
+}
 function payloadType(payload) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload))
         return undefined;
@@ -509,28 +998,95 @@ function printDebugDiscovery() {
 Commands:
   db       Inspect and query local SQLite stores
   session  Inspect one Pibo Session by id or Chat URL
+  summary  Show compact session diagnosis and drill-down commands
+  messages List or show stored user/assistant messages
+  final    Show the latest assistant message
   trace    Rebuild the Chat Web trace view for one Pibo Session
   events   Inspect compact event payload fields for one Pibo Session
+  tool     Inspect one grouped tool call
+  failures List failed tool calls and trace/session errors
   jobs     Inspect durable Pibo jobs and DLQ
   runs     Inspect durable yielded runs
+  signals  Inspect live session signal snapshots through Chat Web APIs
+  telemetry Inspect runtime observability telemetry
+  web      Inspect browser render state via CDP
+  pty      Run and inspect interactive CLI/TUI commands under a PTY
 
 Next:
   pibo debug db
-  pibo debug session <url-or-pibo-session-id>
+  pibo debug summary <pibo-session-id>
+  pibo debug final <pibo-session-id>
+  pibo debug messages <pibo-session-id> list
   pibo debug trace <pibo-session-id> --running-only
   pibo debug events stream --topic pibo.output
+  pibo debug signals tree ps_...
+  pibo debug telemetry sessions --active
+  pibo debug web targets
+  pibo debug pty run -- pibo tui:sessions --demo
+`);
+}
+function printDebugSignalsDiscovery() {
+    console.log(`pibo debug signals - inspect live Session Signal snapshots
+
+Usage:
+  pibo debug signals session <pibo-session-id> [--json] [--cookie <path>]
+  pibo debug signals tree <root-pibo-session-id> [--json] [--cookie <path>]
+
+Environment:
+  PIBO_GATEWAY_URL=http://127.0.0.1:4788
+
+Auth:
+  --cookie <path> reads a Cookie header value from a local file.
+  --auth-header <value> sends an Authorization header. Values are not printed.
+
+Next:
+  pibo debug signals tree ps_...
+`);
+}
+function printDebugTelemetryDiscovery() {
+    console.log(`pibo debug telemetry - inspect bounded runtime observability telemetry
+
+Usage:
+  pibo debug telemetry sessions [--active] [--stale] [--limit n] [--json]
+  pibo debug telemetry session <pibo-session-id> [--limit n] [--json]
+  pibo debug telemetry turn <turn-id-or-event-id> [--events] [--limit n] [--json]
+  pibo debug telemetry provider <provider-request-id> [--json]
+  pibo debug telemetry provider <provider-request-id> events [--after seq] [--fields a,b] [--limit n] [--json]
+  pibo debug telemetry provider <provider-request-id> payload <preview-or-event-summary-id> [--json]
+  pibo debug telemetry tool <tool-call-id> [--json]
+  pibo debug telemetry stale [--threshold-ms n] [--limit n] [--json]
+  pibo debug telemetry stats [--retention class] [--json]
+  pibo debug telemetry prune --retention class --before iso-date [--dry-run|--apply] [--json]
+
+Commands:
+  sessions  List recent, active, or stale telemetry sessions
+  session   Show compact session telemetry and next turn/provider/tool commands
+  turn      Show a phase timeline for one turn or event id
+  provider  Show provider request summary, event pages, and preview-unavailable diagnostics
+  tool      Show tool-call argument and execution telemetry
+  stale     List read-only stale active work
+  stats     Show telemetry retention counts and byte estimates
+  prune     Dry-run telemetry retention cleanup unless --apply is explicit
+
+Next:
+  pibo debug telemetry sessions --active
+  pibo debug telemetry session ps_...
+  pibo debug telemetry turn turn_...
+  pibo debug telemetry provider pr_... events --limit 20
 `);
 }
 function printDebugDbDiscovery() {
     console.log(`pibo debug db - inspect local SQLite stores
 
 Stores:
-  sessions  .pibo/pibo-sessions.sqlite
-  chat      .pibo/web-chat.sqlite
-  agents    .pibo/chat-agents.sqlite
-  auth      .pibo/auth.sqlite
-  bindings  .pibo/session-bindings.sqlite
-  reliability .pibo/pibo-events.sqlite
+  home        ${getPiboHome()}
+  pibo-data   pibo.sqlite        unified sessions, rooms, events, messages, observations, navigation, stats
+  sessions    pibo.sqlite        V2 alias for session metadata
+  chat        pibo.sqlite        V2 alias for Chat Web data
+  agents      chat-agents.sqlite
+  auth        auth.sqlite
+  bindings    session-bindings.sqlite
+  reliability pibo-events.sqlite
 
 Commands:
   stores               List known stores and paths
@@ -539,8 +1095,8 @@ Commands:
   query <store> <sql>  Run read-only SQL
 
 Next:
-  pibo debug db schema sessions
-  pibo debug db query sessions "select id, profile from pibo_sessions limit 5"
+  pibo debug db schema pibo-data
+  pibo debug db query pibo-data "select id, profile from sessions limit 5"
 `);
 }
 function printDebugSessionDiscovery() {
@@ -558,11 +1114,75 @@ Next:
   pibo debug session ps_...
 `);
 }
+function printDebugSummaryDiscovery() {
+    console.log(`pibo debug summary - compact diagnosis with drill-down commands
+
+Usage:
+  pibo debug summary <pibo-session-id> [--json]
+
+Next:
+  pibo debug final ps_...
+  pibo debug failures ps_...
+  pibo debug messages ps_... list
+`);
+}
+function printDebugMessagesDiscovery() {
+    console.log(`pibo debug messages - list or show stored chat messages
+
+Usage:
+  pibo debug messages <pibo-session-id> list [--limit n] [--json]
+  pibo debug messages <pibo-session-id> show <selector> [--full|--no-truncate] [--from n --bytes n] [--max-bytes n] [--plain] [--json]
+
+Selectors:
+  1, last, assistant:last, user:last, stream:<stream-id>, msg:<event-id>
+
+Next:
+  pibo debug messages ps_... list
+  pibo debug messages ps_... show assistant:last --full
+`);
+}
+function printDebugFinalDiscovery() {
+    console.log(`pibo debug final - show the latest assistant message
+
+Usage:
+  pibo debug final <pibo-session-id> [--max-bytes n] [--from n --bytes n] [--no-truncate] [--plain] [--json]
+
+Note:
+  Full messages may contain private data. Use --no-truncate intentionally.
+
+Next:
+  pibo debug final ps_...
+  pibo debug final ps_... --no-truncate
+`);
+}
+function printDebugToolDiscovery() {
+    console.log(`pibo debug tool - inspect one grouped tool call
+
+Usage:
+  pibo debug tool <pibo-session-id> <tool-call-id> [--args|--output|--error] [--no-truncate] [--json]
+
+Next:
+  pibo debug failures ps_...
+  pibo debug tool ps_... call_... --output --no-truncate
+`);
+}
+function printDebugFailuresDiscovery() {
+    console.log(`pibo debug failures - list failed tool calls and trace/session errors
+
+Usage:
+  pibo debug failures <pibo-session-id> [--limit n] [--json]
+
+Next:
+  pibo debug failures ps_...
+  pibo debug tool ps_... <tool-call-id> --output
+`);
+}
 function printDebugTraceDiscovery() {
     console.log(`pibo debug trace - rebuild one Chat Web trace view
 
 Usage:
-  pibo debug trace <pibo-session-id> [--running-only] [--check] [--json]
+  pibo debug trace <pibo-session-id> [--running-only] [--check] [--medium] [--json]
+  pibo debug trace <pibo-session-id> show <node-id> [--json]
 
 Output:
   Compact trace nodes from the same buildTraceView logic used by /api/chat/trace.
@@ -570,24 +1190,29 @@ Output:
 
 Next:
   pibo debug trace ps_... --check
-  pibo debug trace ps_... --running-only
+  pibo debug trace ps_... --medium
+  pibo debug trace ps_... show <node-id>
 `);
 }
 function printDebugEventsDiscovery() {
     console.log(`pibo debug events - inspect compact event payload fields and Pibo event streams
 
 Usage:
-  pibo debug events <pibo-session-id> [--type name] [--fields a,b.c] [--limit n] [--json]
+  pibo debug events <pibo-session-id> [list] [--type name] [--fields a,b.c] [--limit n] [--json]
+  pibo debug events <pibo-session-id> show <stream-id-or-event-id> [--payload|--raw] [--field path] [--no-truncate] [--json]
   pibo debug events stream [--topic topic] [--after stream_id] [--limit n] [--json]
   pibo debug events stats [--topic topic] [--session pibo-session-id] [--retention class] [--json]
   pibo debug events prune --topic topic --retention class --before iso-date [--limit n] [--destructive] [--json]
+  pibo debug events compact-deltas [--dry-run|--apply] [--store pibo-data|chat|reliability] [--session ps_...] [--json]
   pibo debug events consumers [--json]
 
 Examples:
   pibo debug events ps_... --type tool_execution_finished --fields toolName,toolCallId,result.details.status
+  pibo debug events ps_... show 356910 --field attributes_json.inlinePayload
 
 Next:
   pibo debug events ps_... --limit 20
+  pibo debug events ps_... show <stream-id> --payload
   pibo debug events stats --topic pibo.output --retention live_delta
   pibo debug events stream --topic pibo.output --after 123
 `);