@pasko70/pibo 3.5.0 → 3.6.0

package/dist/data/storage-maintenance.js

@@ -0,0 +1,344 @@
+import { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+const ROW_SAMPLE_LIMIT = 10_000;
+const TABLE_LIMIT = 64;
+const DEFAULT_DB_WARN_BYTES = 8 * 1024 ** 3;
+const DEFAULT_WAL_WARN_BYTES = 256 * 1024 ** 2;
+const DEFAULT_PAYLOAD_WARN_BYTES = 8 * 1024 ** 3;
+const MAINTENANCE_LOG_SUFFIX = ".maintenance.jsonl";
+export function inspectStorageStatus(input) {
+    const path = resolve(input.path);
+    const thresholds = {
+        databaseBytes: validThreshold(input.databaseWarnBytes, DEFAULT_DB_WARN_BYTES),
+        walBytes: validThreshold(input.walWarnBytes, DEFAULT_WAL_WARN_BYTES),
+        payloadBytes: validThreshold(input.payloadWarnBytes, DEFAULT_PAYLOAD_WARN_BYTES),
+    };
+    if (!existsSync(path))
+        return { resultType: "storage.status", readOnly: true, path, exists: false, health: "degraded", sizes: { database: 0, wal: 0, shm: 0, payloadStoreMetadataSample: 0, payloadStoreSampleComplete: true }, pages: { pageSize: 0, pageCount: 0, freelistCount: 0, freelistRatio: 0 }, wal: { busy: 0, logPages: 0, checkpointedPages: 0, pressure: false }, rows: [], payloads: { rows: 0, rowsComplete: true, sampledRows: 0, referencedRows: 0, metadataOrphans: 0, brokenReferences: 0, integrityComplete: true }, thresholds, last: {}, warnings: ["Database does not exist"] };
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 50");
+        const pageSize = pragmaNumber(db, "page_size"), pageCount = pragmaNumber(db, "page_count"), freelistCount = pragmaNumber(db, "freelist_count");
+        const walRow = { busy: 0, logPages: pageSize ? Math.ceil(fileSize(`${path}-wal`) / pageSize) : 0, checkpointedPages: 0 };
+        const schemas = db.prepare("SELECT name, type FROM sqlite_schema WHERE type IN ('table','index') AND name NOT LIKE 'sqlite_%' ORDER BY CASE type WHEN 'table' THEN 0 ELSE 1 END, name LIMIT ?").all(TABLE_LIMIT);
+        const estimates = statEstimates(db);
+        const rows = schemas.map((schema) => {
+            if (schema.type === "index")
+                return { name: schema.name, kind: "index", ...(estimates.get(schema.name) !== undefined ? { estimatedRows: estimates.get(schema.name) } : {}) };
+            const count = boundedCount(db, schema.name);
+            return { name: schema.name, kind: "table", boundedCount: count.count, countComplete: count.complete, ...(estimates.get(schema.name) !== undefined ? { estimatedRows: estimates.get(schema.name) } : {}) };
+        });
+        const payload = inspectPayloadReferencesBounded(db);
+        const sizes = {
+            database: fileSize(path),
+            wal: fileSize(`${path}-wal`),
+            shm: fileSize(`${path}-shm`),
+            payloadStoreMetadataSample: payload.metadataBytes,
+            payloadStoreSampleComplete: payload.rowsComplete && payload.sampledRows === payload.rows,
+        };
+        const walPressure = sizes.wal >= thresholds.walBytes;
+        const warnings = [
+            ...(sizes.database >= thresholds.databaseBytes ? ["database_size_threshold"] : []),
+            ...(sizes.wal >= thresholds.walBytes ? ["wal_size_threshold"] : []),
+            ...(sizes.payloadStoreSampleComplete && sizes.payloadStoreMetadataSample >= thresholds.payloadBytes ? ["payload_size_threshold"] : []),
+            ...(!sizes.payloadStoreSampleComplete ? ["payload_size_threshold_indeterminate"] : []),
+            ...(walPressure ? ["wal_checkpoint_pressure"] : []),
+            ...(payload.metadataOrphans ? ["payload_metadata_orphans_sample"] : []),
+            ...(payload.brokenReferences ? ["broken_payload_references_sample"] : []),
+        ];
+        return {
+            resultType: "storage.status", readOnly: true, path, exists: true, health: warnings.length ? "degraded" : "healthy", sizes,
+            pages: { pageSize, pageCount, freelistCount, freelistRatio: pageCount ? freelistCount / pageCount : 0 },
+            wal: { ...walRow, pressure: walPressure }, rows,
+            payloads: { rows: payload.rows, rowsComplete: payload.rowsComplete, sampledRows: payload.sampledRows, referencedRows: payload.referencedRows, metadataOrphans: payload.metadataOrphans, brokenReferences: payload.brokenReferences, integrityComplete: payload.integrityComplete },
+            thresholds, last: readMaintenanceMetadata(path), warnings,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export async function verifyStorage(input) {
+    const path = resolve(input.path), mode = input.mode ?? "quick", timeoutMs = input.timeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3_600_000)
+        throw new Error("Verification timeout must be between 1 and 3600000 ms");
+    const started = Date.now(), progress = [];
+    const record = (stage, elapsedMs = Date.now() - started) => { const item = { stage, elapsedMs }; if (progress.length < 32)
+        progress.push(item); input.onProgress?.(item); };
+    const resultFor = (status, healthy, reason, messages = []) => ({ resultType: "storage.verification", path, mode, status, healthy, elapsedMs: Date.now() - started, progress, messages, ...(reason ? { reason } : {}) });
+    record("starting", 0);
+    if (input.signal?.aborted)
+        return resultFor("partial", false, "cancelled");
+    const result = await new Promise((resolveResult) => {
+        let child;
+        let settled = false;
+        let operationTimer;
+        let pendingPartialReason;
+        const startupTimer = setTimeout(() => requestStop("startup_timeout"), Math.min(5_000, Math.max(1_000, timeoutMs)));
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(startupTimer);
+            if (operationTimer)
+                clearTimeout(operationTimer);
+            input.signal?.removeEventListener("abort", cancel);
+            resolveResult(value);
+        };
+        const requestStop = (reason) => {
+            if (settled || pendingPartialReason)
+                return;
+            pendingPartialReason = reason;
+            record("terminating");
+            if (!child?.kill("SIGKILL"))
+                finish(resultFor("failed", false, "verification_process_not_terminated"));
+        };
+        const cancel = () => requestStop("cancelled");
+        input.signal?.addEventListener("abort", cancel, { once: true });
+        child = fork(fileURLToPath(new URL("./storage-verification-worker.js", import.meta.url)), [path, mode, ...(input.testNativeLongRunning ? ["native-long"] : [])], { stdio: ["ignore", "ignore", "ignore", "ipc"] });
+        child.on("message", (message) => {
+            if (!message || typeof message !== "object")
+                return;
+            const item = message;
+            if (item.type === "progress") {
+                const stage = String(item.stage);
+                record(stage, Number(item.elapsedMs));
+                if (stage.endsWith("_check") && !operationTimer) {
+                    clearTimeout(startupTimer);
+                    operationTimer = setTimeout(() => requestStop("timeout"), timeoutMs);
+                }
+                return;
+            }
+            if (item.type === "result") {
+                record("complete", Number(item.elapsedMs));
+                const messages = Array.isArray(item.messages) ? item.messages.map(String).slice(0, 100) : [];
+                finish(item.ok === true ? resultFor("complete", true, undefined, messages) : resultFor("failed", false, "integrity_errors", messages));
+            }
+            else if (item.type === "error")
+                finish(resultFor("failed", false, String(item.message ?? "verification_failed")));
+        });
+        child.on("error", (error) => finish(resultFor("failed", false, (error instanceof Error ? error.message : String(error)).slice(0, 500))));
+        child.on("exit", (code, signal) => {
+            if (pendingPartialReason) {
+                record("terminated");
+                finish(resultFor("partial", false, pendingPartialReason));
+            }
+            else if (!settled && code !== 0)
+                finish(resultFor("failed", false, `verification_process_exit_${code ?? signal ?? "unknown"}`));
+        });
+    });
+    if (result.status !== "partial") {
+        try {
+            recordMaintenance(path, { operation: "verification", at: new Date().toISOString(), mode, status: result.status, healthy: result.healthy, elapsedMs: result.elapsedMs });
+        }
+        catch { /* A read-only verification result remains valid when metadata storage is unavailable. */ }
+    }
+    return result;
+}
+export function checkpointStorage(input) {
+    const path = resolve(input.path), mode = input.mode ?? "passive";
+    if (!existsSync(path))
+        throw new Error(`Checkpoint database does not exist: ${path}`);
+    if (mode !== "passive" && mode !== "restart" && mode !== "truncate")
+        throw new Error("Checkpoint mode must be passive, restart, or truncate");
+    if (!input.apply)
+        return { resultType: "storage.checkpoint", mode: "dry-run", path, checkpointMode: mode, mutation: false };
+    const db = new DatabaseSync(path);
+    try {
+        db.exec("PRAGMA busy_timeout = 100");
+        const row = db.prepare(`PRAGMA wal_checkpoint(${mode.toUpperCase()})`).get();
+        const result = { resultType: "storage.checkpoint", mode: "apply", path, checkpointMode: mode, mutation: true, busy: Number(row.busy ?? 0), logPages: Number(row.log ?? 0), checkpointedPages: Number(row.checkpointed ?? 0), at: new Date().toISOString() };
+        recordMaintenance(path, { operation: "checkpoint", ...result });
+        return result;
+    }
+    finally {
+        db.close();
+    }
+}
+export async function maintainStorageRetention(input) {
+    const path = resolve(input.path), limit = input.limit ?? 1000;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)
+        throw new Error("Retention limit must be between 1 and 10000");
+    if (!Number.isFinite(Date.parse(input.before)))
+        throw new Error("Retention --before must be an ISO date");
+    const db = new DatabaseSync(path, { readOnly: !input.apply });
+    const target = tableExists(db, "event_log") ? { table: "event_log", time: "created_at" } : tableExists(db, "pibo_event_stream") ? { table: "pibo_event_stream", time: "created_at" } : undefined;
+    try {
+        if (!target)
+            return { resultType: "storage.retention", mode: input.apply ? "apply" : "dry-run", path, eligible: 0, deleted: 0, policy: "live_delta_only", preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads"] };
+        const eligibility = retentionEligibilitySql(target.table);
+        const eligible = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time} LIMIT ?)`).get(input.before, limit).count);
+        const plan = retentionPlan(db, target.table, target.time, input.before, limit);
+        if (!input.apply)
+            return { resultType: "storage.retention", mode: "dry-run", path, eligible, deleteLimit: limit, policy: "live_delta_only", plan, preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads"] };
+        const auditId = `storage_retention_${randomUUID()}`;
+        const at = new Date().toISOString();
+        db.exec("PRAGMA busy_timeout = 100; BEGIN IMMEDIATE");
+        try {
+            db.exec(`CREATE TABLE IF NOT EXISTS storage_maintenance_audit (
+				id TEXT PRIMARY KEY,
+				operation TEXT NOT NULL,
+				status TEXT NOT NULL,
+				details_json TEXT NOT NULL,
+				created_at TEXT NOT NULL
+			)`);
+            const candidates = db.prepare(`SELECT rowid, ${target.table === "event_log" ? "payload_ref AS payloadRef" : "NULL AS payloadRef"} FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time}, rowid LIMIT ?`).all(input.before, limit);
+            const deletion = db.prepare(`DELETE FROM ${target.table} WHERE rowid IN (SELECT rowid FROM ${target.table} WHERE ${eligibility} AND ${target.time} < ? ORDER BY ${target.time}, rowid LIMIT ?)`).run(input.before, limit);
+            const deleted = Number(deletion.changes);
+            if (deleted !== candidates.length)
+                throw new Error("Retention candidate/delete count changed while holding the write transaction");
+            const releasedPayloadIds = [...new Set(candidates.flatMap((row) => row.payloadRef ? [row.payloadRef] : []))];
+            const payloads = inspectReleasedPayloadsBounded(db, releasedPayloadIds);
+            const result = { resultType: "storage.retention", mode: "apply", path, eligible, deleted, deleteLimit: limit, policy: "live_delta_only", plan, payloads, auditId, preserved: ["chat_message", "audit_event", "idempotency_evidence", "referenced_payloads", "orphan_payload_files"], at };
+            db.prepare("INSERT INTO storage_maintenance_audit (id, operation, status, details_json, created_at) VALUES (?, 'retention', 'complete', ?, ?)").run(auditId, JSON.stringify(result), at);
+            db.exec("COMMIT");
+            try {
+                recordMaintenance(path, { operation: "retention", ...result });
+            }
+            catch { /* Transactional audit is authoritative. */ }
+            return result;
+        }
+        catch (error) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function retentionEligibilitySql(table) {
+    return table === "event_log"
+        ? "retention_class = 'live_delta' AND idempotency_key IS NULL"
+        : "retention_class = 'live_delta' AND idempotency_key IS NULL AND event_id IS NULL";
+}
+function retentionPlan(db, table, time, before, limit) {
+    const classes = ["live_delta", "trace_event", "chat_message", "audit_event"];
+    return classes.map((retentionClass) => {
+        const rows = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${table} WHERE retention_class=? AND ${time} < ? LIMIT ?)`).get(retentionClass, before, limit + 1).count);
+        return {
+            retentionClass,
+            rows: Math.min(rows, limit),
+            bounded: rows > limit,
+            disposition: retentionClass === "live_delta" ? "eligible" : retentionClass === "trace_event" ? "deferred_requires_policy" : "preserve",
+        };
+    });
+}
+function inspectPayloadReferencesBounded(db) {
+    if (!tableExists(db, "payloads"))
+        return { rows: 0, rowsComplete: true, sampledRows: 0, metadataBytes: 0, referencedRows: 0, metadataOrphans: 0, brokenReferences: 0, integrityComplete: true };
+    const rowCount = boundedCount(db, "payloads");
+    const payloadRows = db.prepare("SELECT id, COALESCE(compressed_byte_size, byte_size) AS bytes FROM payloads ORDER BY id LIMIT 1001").all();
+    const sample = payloadRows.slice(0, 1000);
+    const references = discoverPayloadReferenceColumns(db);
+    const sampledReferenceIds = new Set();
+    let brokenReferences = 0;
+    let referenceSamplesComplete = true;
+    for (const reference of references) {
+        const table = quoteIdentifier(reference.table), column = quoteIdentifier(reference.column);
+        // Do not filter here: LIMIT bounds rows examined even when references are sparse.
+        const rows = db.prepare(`SELECT ${column} AS id FROM ${table} LIMIT 1001`).all();
+        if (rows.length > 1000)
+            referenceSamplesComplete = false;
+        for (const row of rows.slice(0, 1000)) {
+            if (!row.id)
+                continue;
+            sampledReferenceIds.add(row.id);
+            if (!db.prepare("SELECT 1 FROM payloads WHERE id = ?").get(row.id))
+                brokenReferences += 1;
+        }
+    }
+    const referencedRows = sample.filter((payload) => sampledReferenceIds.has(payload.id)).length;
+    const integrityComplete = rowCount.complete && payloadRows.length <= 1000 && referenceSamplesComplete;
+    return {
+        rows: rowCount.count,
+        rowsComplete: rowCount.complete,
+        sampledRows: sample.length,
+        metadataBytes: sample.reduce((total, row) => total + Number(row.bytes ?? 0), 0),
+        referencedRows,
+        metadataOrphans: integrityComplete ? sample.length - referencedRows : 0,
+        brokenReferences,
+        integrityComplete,
+    };
+}
+function inspectReleasedPayloadsBounded(_db, candidateIds) {
+    const bounded = [...new Set(candidateIds)].slice(0, 1000);
+    return {
+        releasedReferenceCandidates: candidateIds.length,
+        candidatesReported: bounded.length,
+        candidatesTruncated: candidateIds.length > bounded.length,
+        referenceState: "not_scanned_online",
+        retainedMetadata: bounded.length,
+        retainedFiles: bounded.length,
+        action: "report_only",
+    };
+}
+function discoverPayloadReferenceColumns(db) {
+    const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name LIMIT 128").all();
+    const references = [];
+    for (const { name } of tables) {
+        const columns = db.prepare("SELECT name FROM pragma_table_info(?) LIMIT 128").all(name);
+        for (const column of columns) {
+            if (column.name === "payload_ref" || column.name === "content_payload_ref" || column.name === "payload_preview_ref")
+                references.push({ table: name, column: column.name });
+        }
+    }
+    return references.slice(0, 64);
+}
+function quoteIdentifier(value) { return `"${value.replaceAll('"', '""')}"`; }
+function statEstimates(db) { const result = new Map(); if (!tableExists(db, "sqlite_stat1"))
+    return result; try {
+    for (const row of db.prepare("SELECT tbl, idx, stat FROM sqlite_stat1 LIMIT 256").all()) {
+        const estimate = Number.parseInt(row.stat.split(" ")[0] ?? "", 10);
+        if (Number.isFinite(estimate)) {
+            result.set(row.tbl, estimate);
+            if (row.idx)
+                result.set(row.idx, estimate);
+        }
+    }
+}
+catch { } return result; }
+function boundedCount(db, name) { const quoted = `"${name.replaceAll('"', '""')}"`; try {
+    const count = Number(db.prepare(`SELECT COUNT(*) AS count FROM (SELECT 1 FROM ${quoted} LIMIT ?)`).get(ROW_SAMPLE_LIMIT + 1).count);
+    return { count: Math.min(count, ROW_SAMPLE_LIMIT), complete: count <= ROW_SAMPLE_LIMIT };
+}
+catch {
+    return { count: 0, complete: false };
+} }
+function pragmaNumber(db, name) { return Number(Object.values(db.prepare(`PRAGMA ${name}`).get() ?? { value: 0 })[0] ?? 0); }
+function tableExists(db, table) { return Boolean(db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table)); }
+function columnExists(db, table, column) { return Boolean(db.prepare(`SELECT 1 FROM pragma_table_info(?) WHERE name=?`).get(table, column)); }
+function fileSize(path) { try {
+    return statSync(path).size;
+}
+catch {
+    return 0;
+} }
+function validThreshold(value, fallback) { return Number.isSafeInteger(value) && value > 0 ? value : fallback; }
+export function recordStorageMaintenance(path, value) { appendFileSync(`${resolve(path)}${MAINTENANCE_LOG_SUFFIX}`, `${JSON.stringify(value)}\n`, { mode: 0o600 }); }
+function recordMaintenance(path, value) { recordStorageMaintenance(path, value); }
+function readMaintenanceMetadata(path) { const result = {}; try {
+    const metadataPath = `${path}${MAINTENANCE_LOG_SUFFIX}`;
+    const bytes = statSync(metadataPath).size;
+    if (bytes > 1024 * 1024)
+        return result;
+    const lines = readFileSync(metadataPath, "utf8").trim().split("\n").slice(-100);
+    for (const line of lines) {
+        const row = JSON.parse(line);
+        const operation = row.operation;
+        if (operation === "checkpoint")
+            result.checkpoint = row;
+        else if (operation === "backup")
+            result.backup = row;
+        else if (operation === "verification")
+            result.verification = row;
+        else if (operation === "retention")
+            result.retention = row;
+    }
+}
+catch { } return result; }

package/dist/data/storage-verification-worker.js

@@ -0,0 +1,25 @@
+import { DatabaseSync } from "node:sqlite";
+const [path, mode, fixture] = process.argv.slice(2);
+const started = Date.now();
+const send = (message) => process.send?.(message);
+let db;
+try {
+    send({ type: "progress", stage: "opened", elapsedMs: 0 });
+    db = new DatabaseSync(path, { readOnly: true });
+    db.exec("PRAGMA busy_timeout = 50");
+    const pragma = mode === "full" ? "integrity_check" : "quick_check";
+    send({ type: "progress", stage: pragma, elapsedMs: Date.now() - started });
+    if (fixture === "native-long") {
+        db.prepare("WITH RECURSIVE counter(value) AS (VALUES(0) UNION ALL SELECT value + 1 FROM counter WHERE value < 1000000000) SELECT SUM(value) FROM counter").get();
+    }
+    const rows = db.prepare(`PRAGMA ${pragma}`).all();
+    const messages = rows.slice(0, 100).flatMap((row) => Object.values(row).map(String));
+    send({ type: "result", ok: messages.length === 1 && messages[0] === "ok", messages, elapsedMs: Date.now() - started });
+}
+catch (error) {
+    send({ type: "error", message: error instanceof Error ? error.message.slice(0, 500) : "Verification failed", elapsedMs: Date.now() - started });
+}
+finally {
+    db?.close();
+    process.disconnect?.();
+}

package/dist/debug/cache.js

@@ -0,0 +1,136 @@
+import { cacheUsageWarningText } from "../shared/cache-observability.js";
+import { compareInferenceCompletion, modelInferenceCacheReadRatio, modelInferenceCachedInputTokens, modelInferenceInputTokens, modelInferenceUncachedInputTokens, } from "../shared/model-inference-metrics.js";
+import { inspectDebugTrace } from "./trace.js";
+import { formatNextCommands } from "./next-commands.js";
+function finiteToken(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+export async function inspectDebugCache(piboSessionId, stores, options = {}) {
+    const trace = await inspectDebugTrace(piboSessionId, stores);
+    const byId = new Map();
+    for (const node of trace.nodes) {
+        for (const record of node.modelInferences ?? [])
+            byId.set(record.id, { nodeId: node.id, nodeTitle: node.title, record });
+    }
+    const located = [...byId.values()].sort((left, right) => compareInferenceCompletion(left.record, right.record));
+    let reportedInput = 0;
+    let reportedRead = 0;
+    let reportedCount = 0;
+    let unreportedCount = 0;
+    let writeTotal = 0;
+    let writeReported = false;
+    let possibleDropCount = 0;
+    for (const { record } of located) {
+        const input = modelInferenceInputTokens(record.metrics);
+        const read = modelInferenceCachedInputTokens(record.metrics);
+        if (input !== undefined && input > 0 && read !== undefined && read <= input) {
+            reportedInput += input;
+            reportedRead += read;
+            reportedCount++;
+        }
+        else {
+            unreportedCount++;
+        }
+        const write = finiteToken(record.metrics.cacheWriteTokens);
+        if (write !== undefined) {
+            writeTotal += write;
+            writeReported = true;
+        }
+        if (record.cacheObservation?.warning === "possible-cache-read-drop")
+            possibleDropCount++;
+    }
+    const limit = options.limit ?? 20;
+    const selected = located.slice(Math.max(0, located.length - limit));
+    return {
+        piboSessionId,
+        runtimeInstanceId: trace.runtimeInstanceId,
+        runtimeAdapterId: trace.runtimeAdapterId,
+        source: "provider-reported-usage",
+        summary: {
+            inferenceCount: located.length,
+            cacheReadReportedCount: reportedCount,
+            cacheReadUnreportedCount: unreportedCount,
+            possibleDropCount,
+            ...(reportedCount ? {
+                inputTokens: reportedInput,
+                cacheReadTokens: reportedRead,
+                uncachedInputTokens: reportedInput - reportedRead,
+                cacheReadRatio: reportedRead / reportedInput,
+            } : {}),
+            ...(writeReported ? { cacheWriteTokens: writeTotal } : {}),
+        },
+        inferences: selected.map(({ nodeId, nodeTitle, record }) => ({
+            id: record.id,
+            nodeId,
+            nodeTitle,
+            completedAt: record.completedAt,
+            inputTokens: modelInferenceInputTokens(record.metrics),
+            cacheReadTokens: modelInferenceCachedInputTokens(record.metrics),
+            cacheWriteTokens: finiteToken(record.metrics.cacheWriteTokens),
+            uncachedInputTokens: modelInferenceUncachedInputTokens(record.metrics),
+            cacheReadRatio: modelInferenceCacheReadRatio(record.metrics),
+            previousCacheReadRatio: record.cacheObservation?.previousCacheReadRatio,
+            elapsedMs: record.cacheObservation?.elapsedMs,
+            cacheState: record.cacheObservation?.cacheState ?? "unknown",
+            warning: record.cacheObservation?.warning ?? "none",
+            warningText: record.cacheObservation ? cacheUsageWarningText(record.cacheObservation) : undefined,
+            explanation: record.cacheObservation?.explanation ?? "insufficient-data",
+        })),
+        limitations: [
+            "Cache counters are reported by the runtime or provider; missing counters remain unknown.",
+            "A cache-read drop does not identify whether Pibo, the runtime, the provider, or eviction caused it.",
+            "This command does not inspect or alter runtime source code, prompts, or provider cache keys.",
+        ],
+        nextCommands: [
+            `pibo debug trace ${piboSessionId} --medium`,
+            `pibo debug events ${piboSessionId} --type assistant_usage --fields inputTokens,cacheReadTokens,cacheWriteTokens,totalTokens`,
+        ],
+    };
+}
+function metric(value) {
+    return value === undefined ? "unknown" : String(value);
+}
+function ratio(value) {
+    return value === undefined ? "unknown" : `${(value * 100).toFixed(1)}%`;
+}
+export function formatDebugCache(result) {
+    const lines = [
+        `piboSessionId: ${result.piboSessionId}`,
+        ...(result.runtimeInstanceId ? [`runtimeInstanceId: ${result.runtimeInstanceId}`] : []),
+        ...(result.runtimeAdapterId ? [`runtimeAdapterId: ${result.runtimeAdapterId}`] : []),
+        `source: ${result.source}`,
+        `inferences: ${result.summary.inferenceCount}`,
+        `cacheReadReported: ${result.summary.cacheReadReportedCount}`,
+        `cacheReadUnreported: ${result.summary.cacheReadUnreportedCount}`,
+        `possibleDrops: ${result.summary.possibleDropCount}`,
+        `inputTokens: ${metric(result.summary.inputTokens)}`,
+        `cacheReadTokens: ${metric(result.summary.cacheReadTokens)}`,
+        `uncachedInputTokens: ${metric(result.summary.uncachedInputTokens)}`,
+        `cacheWriteTokens: ${metric(result.summary.cacheWriteTokens)}`,
+        `cacheReadRatio: ${ratio(result.summary.cacheReadRatio)}`,
+        "",
+    ];
+    if (result.inferences.length) {
+        lines.push("completedAt\tstate\tinput\tcacheRead\tuncached\tcacheWrite\tratio\tid\tnode");
+        for (const inference of result.inferences) {
+            lines.push([
+                inference.completedAt ?? "unknown",
+                inference.cacheState,
+                metric(inference.inputTokens),
+                metric(inference.cacheReadTokens),
+                metric(inference.uncachedInputTokens),
+                metric(inference.cacheWriteTokens),
+                ratio(inference.cacheReadRatio),
+                inference.id,
+                inference.nodeTitle,
+            ].join("\t"));
+        }
+    }
+    for (const inference of result.inferences) {
+        if (inference.warningText)
+            lines.push(`cache-warning\t${inference.id}\t${inference.warningText}`);
+    }
+    lines.push("", "Limitations:", ...result.limitations.map((item) => `- ${item}`));
+    lines.push(...formatNextCommands(result.nextCommands));
+    return lines.join("\n");
+}