pi-export-my-chat 1.0.0

package/index.ts

@@ -0,0 +1,510 @@
+/**
+ * export-my-chat — complete, lossless, revivable session export for pi
+ *
+ *   /export-my-chat [<absolute .json path>]
+ *     Writes ONE self-contained JSON file: the durable session (header + the
+ *     complete ordered entry tree, active branch, active context), EVERY
+ *     provider request observed this runtime (deduplicated by content hash),
+ *     usage/cost/context stats, and operation timings. Refuses to run while
+ *     pi is not idle (the "at rest" contract), never overwrites, writes 0600.
+ *
+ *   /export-my-chat:revive [<path to a previous export>] [--force]
+ *     Rebuilds a valid pi session file from the export, saves it into pi's
+ *     session directory for the current project, and switches the running
+ *     pi window onto it — the chat comes back, named, branchable, resumable
+ *     via /resume. Header cwd is re-rooted to the current project; the session
+ *     UUID is kept across machines and re-minted where it would collide;
+ *     integrity is proven by a sha256 over the canonical JSONL that both
+ *     export and revive build with the same code.
+ *
+ * Design invariants (see README for the full rationale):
+ *   - Lossless in content AND count: every observed request is recorded;
+ *     byte-identical payloads are stored once and referenced by sha256.
+ *   - The revivable core (header + ordered entries) carries a checksum that
+ *     revive recomputes and refuses to proceed without.
+ *   - Versioned on three axes (export schema, session header version,
+ *     extension version) so a newer source never silently half-loads.
+ *   - Writes are strict (absolute, .json, exclusive, 0600); reads are
+ *     forgiving (revive accepts relative paths).
+ */
+
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { promises as fsp } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CURRENT_SESSION_VERSION, buildSessionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+    EXPORT_FORMAT,
+    SCHEMA_VERSION,
+    buildRevivePlan,
+    buildSessionJsonl,
+    collectTimingRecords,
+    collectUsage,
+    contextUsageSnapshot,
+    errorMessage,
+    parseReviveArgs,
+    resolveExportPath,
+    sha256Hex,
+    summarizeTimings,
+    timestampedExportName,
+    validateExportDocument,
+    writeExclusiveJson,
+} from "./helpers.mjs";
+
+const EXTENSION_VERSION = "1.0.0";
+const SCRATCH_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+// ─── Request capture (scratch journal) ───────────────────────────────
+//
+// Every provider request is serialized and appended to a per-session scratch
+// file the moment it is observed. Keeping the journal on disk (rather than in
+// memory) bounds RAM: a tool-heavy session re-sends nearly identical context on
+// every turn, so "all requests" can mean tens of MB that never needs to sit in
+// a heap. The journal is reset on session_start and only merged + deduplicated
+// at export time. It lives under the pi agent cache dir, is written 0600 (it
+// holds the same sensitive payloads the export does), and journals untouched
+// for more than SCRATCH_MAX_AGE_MS are pruned on session_start.
+
+function scratchDir(): string {
+    return join(getAgentDir(), "cache", "export-my-chat");
+}
+
+function scratchPathFor(sessionId: string): string {
+    return join(scratchDir(), `${sessionId}.jsonl`);
+}
+
+/** Best-effort removal of stale journals; never fatal, never touches the active one. */
+function pruneScratchJournals(now = Date.now()): void {
+    let names: string[];
+    try {
+        names = readdirSync(scratchDir());
+    } catch {
+        return; // cache dir absent — nothing to prune
+    }
+    for (const name of names) {
+        try {
+            const info = statSync(join(scratchDir(), name));
+            if (info.isFile() && now - info.mtimeMs > SCRATCH_MAX_AGE_MS) {
+                unlinkSync(join(scratchDir(), name));
+            }
+        } catch {
+            // A raced deletion or an unreadable entry is ignored.
+        }
+    }
+}
+
+type ContextUsageSnapshot = {
+    used: number | null;
+    window: number;
+    remaining: number | null;
+    percentUsed: number | null;
+};
+
+type ScratchRecord = {
+    n: number;
+    capturedAt: string;
+    provider?: string;
+    model?: string;
+    api?: string;
+    contextUsage: ContextUsageSnapshot;
+    payloadSha256: string;
+    serializedPayload: string;
+};
+
+function readScratchRecords(scratchPath: string | undefined): ScratchRecord[] {
+    if (!scratchPath || !existsSync(scratchPath)) return [];
+    const records: ScratchRecord[] = [];
+    const content = readFileSync(scratchPath, "utf8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+            records.push(JSON.parse(trimmed) as ScratchRecord);
+        } catch {
+            // A torn final line (crash mid-append) is skipped, never fatal.
+        }
+    }
+    return records;
+}
+
+// ─── Formatting helpers ──────────────────────────────────────────────────────
+
+function formatBytes(bytes: number): string {
+    if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(2)} GiB`;
+    if (bytes >= 1024 ** 2) return `${(bytes / 1024 ** 2).toFixed(2)} MiB`;
+    if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${bytes} B`;
+}
+
+// ─── Argument autocompletion ──────────────────────────────────────────────────
+
+/** Offer .json files (as absolute paths) from the current project directory. */
+function jsonFileCompletions(cwd: string, prefix: string): AutocompleteItem[] | null {
+    try {
+        const files = readdirSync(cwd)
+            .filter((name) => name.toLowerCase().endsWith(".json"))
+            .map((name) => join(cwd, name));
+        const filtered = files.filter((file) => file.startsWith(prefix));
+        if (filtered.length === 0) return null;
+        return filtered.map((file) => ({ value: file, label: file }));
+    } catch {
+        return null;
+    }
+}
+
+// ─── Extension ───────────────────────────────────────────────────────────────
+
+export default function exportMyChat(pi: ExtensionAPI): void {
+    let captureStartedAt = new Date().toISOString();
+    let observedRequestCount = 0;
+    let latestCaptureError: string | undefined;
+    let scratchPath: string | undefined;
+    let currentCwd: string | undefined;
+
+    /**
+     * Create/truncate the journal for the current session without touching
+     * the capture counters or window (those belong to session_start).
+     */
+    const ensureScratch = (ctx: any): void => {
+        if (scratchPath) return;
+        try {
+            const id = ctx?.sessionManager?.getSessionId?.();
+            if (typeof id === "string" && id.length > 0) {
+                scratchPath = scratchPathFor(id);
+                mkdirSync(dirname(scratchPath), { recursive: true, mode: 0o700 });
+                writeFileSync(scratchPath, "", { mode: 0o600 }); // truncate: fresh journal
+            }
+        } catch {
+            scratchPath = undefined; // capture is best-effort; export still works
+        }
+    };
+
+    const resetCapture = (ctx: any): void => {
+        captureStartedAt = new Date().toISOString();
+        observedRequestCount = 0;
+        latestCaptureError = undefined;
+        scratchPath = undefined;
+        ensureScratch(ctx);
+        pruneScratchJournals();
+    };
+
+    pi.on("session_start", (_event, ctx) => {
+        currentCwd = ctx?.cwd ?? currentCwd;
+        resetCapture(ctx);
+    });
+
+    pi.on("before_provider_request", (event: any, ctx: any) => {
+        observedRequestCount++;
+        // Late initialization (e.g. session id became available after load):
+        // the journal is created, but the capture window and counters — which
+        // belong to session_start — are left untouched.
+        ensureScratch(ctx);
+        if (!scratchPath) {
+            latestCaptureError =
+                "Request journal unavailable (no session id); requests are counted but not recorded.";
+            return;
+        }
+        try {
+            const serializedPayload = JSON.stringify(event.payload);
+            if (serializedPayload === undefined) throw new Error("provider payload serialized to undefined");
+            const model = ctx?.model as { provider?: string; id?: string; api?: string; contextWindow?: number } | undefined;
+            const record: ScratchRecord = {
+                n: observedRequestCount,
+                capturedAt: new Date().toISOString(),
+                provider: model?.provider,
+                model: model?.id,
+                api: model?.api,
+                contextUsage: contextUsageSnapshot(ctx?.getContextUsage?.(), model?.contextWindow),
+                payloadSha256: sha256Hex(serializedPayload),
+                serializedPayload,
+            };
+            appendFileSync(scratchPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+            latestCaptureError = undefined;
+        } catch (error) {
+            latestCaptureError = errorMessage(error);
+        }
+    });
+
+    // ─── /export-my-chat ──────────────────────────────────────────────────────
+
+    pi.registerCommand("export-my-chat", {
+        description:
+            "Export the complete session (durable tree + every provider request + stats + timings) to one lossless, revivable JSON file",
+        getArgumentCompletions: (prefix: string): AutocompleteItem[] | null =>
+            currentCwd ? jsonFileCompletions(currentCwd, prefix) : null,
+        handler: async (args, ctx) => {
+            try {
+                // "At rest" contract: export refuses while a turn is running.
+                if (ctx.isIdle() !== true) {
+                    ctx.ui.notify(
+                        "Export refused: pi is not idle. Wait for the current turn (or press Esc), then run /export-my-chat again.",
+                        "error",
+                    );
+                    return;
+                }
+                currentCwd = ctx.cwd;
+
+                const destination = resolveExportPath(args ?? "", ctx.cwd);
+
+                const sessionManager: any = ctx.sessionManager;
+                const header = sessionManager.getHeader();
+                if (!header || typeof header !== "object") {
+                    ctx.ui.notify("Export failed: no session header is available yet.", "error");
+                    return;
+                }
+                const entries = sessionManager.getEntries();
+                const activeBranch = sessionManager.getBranch();
+                const name = sessionManager.getSessionName() ?? null;
+                const sessionFile = sessionManager.getSessionFile() ?? null;
+                const leafId = sessionManager.getLeafId() ?? null;
+                // buildSessionContext is pi's own exported, pure context
+                // builder (the live sessionManager also exposes it as a
+                // method, but the free function is the type-safe route).
+                const activeContext = buildSessionContext(entries, leafId);
+
+                // The revivable core and its proof, built with the exact
+                // serialization revive will use. Also compare against pi's own
+                // on-disk file as a diagnostic: a mismatch never blocks the
+                // export (the checksum is over OUR canonical form, which is
+                // what revive writes), but it tells you the file drifted from
+                // the entries — e.g. an in-flight write or an edited .jsonl.
+                const canonicalJsonl = buildSessionJsonl(header, entries);
+                let matchesOriginalFile: boolean | null = null;
+                if (typeof sessionFile === "string" && existsSync(sessionFile)) {
+                    try {
+                        matchesOriginalFile = readFileSync(sessionFile, "utf8") === canonicalJsonl;
+                    } catch {
+                        matchesOriginalFile = null;
+                    }
+                }
+
+                // Every observed provider request, with byte-identical
+                // payloads deduplicated into a store keyed by sha256. The
+                // request list keeps content AND count; only literal duplicate
+                // bytes are factored out.
+                const scratchRecords = readScratchRecords(scratchPath);
+                const payloads: Record<string, unknown> = {};
+                const requestRecords = scratchRecords.map((record) => {
+                    if (!(record.payloadSha256 in payloads)) {
+                        payloads[record.payloadSha256] = JSON.parse(record.serializedPayload);
+                    }
+                    const { serializedPayload: _omit, ...publicRecord } = record;
+                    return publicRecord;
+                });
+
+                const activeTimings = collectTimingRecords(activeBranch);
+                const wholeSessionTimings = collectTimingRecords(entries);
+
+                const document = {
+                    format: EXPORT_FORMAT,
+                    schemaVersion: SCHEMA_VERSION,
+                    exportedAt: new Date().toISOString(),
+                    exportedBy: {
+                        extension: "export-my-chat",
+                        extensionVersion: EXTENSION_VERSION,
+                        sessionHeaderVersion: typeof header?.version === "number" ? header.version : null,
+                        currentSessionVersion: CURRENT_SESSION_VERSION,
+                    },
+                    session: {
+                        id: sessionManager.getSessionId(),
+                        name,
+                        cwd: sessionManager.getCwd(),
+                        sessionFile,
+                        header,
+                        leafId,
+                        entries,
+                        activeBranchEntryIds: activeBranch
+                            .map((entry: any) => entry?.id)
+                            .filter((id: unknown): id is string => typeof id === "string"),
+                        activeContext,
+                        revive: {
+                            checksum: sha256Hex(canonicalJsonl),
+                            headerVersion: typeof header?.version === "number" ? header.version : null,
+                            entryCount: entries.length,
+                            lastEntryId: entries.length > 0 ? entries[entries.length - 1]?.id ?? null : null,
+                            matchesOriginalFile,
+                            note:
+                                "Rebuild with /export-my-chat:revive. The checksum is sha256 over the canonical JSONL (header line + one compact JSON line per entry, insertion order) that revive writes; it covers the lossless core only — declared revival transformations (cwd re-root, name re-attach) are applied after verification.",
+                        },
+                    },
+                    requests: {
+                        captureStartedAt,
+                        observedRequestCount,
+                        scratchFile: scratchPath ?? null,
+                        latestCaptureError: latestCaptureError ?? null,
+                        records: requestRecords,
+                        payloads,
+                        note:
+                            "Every provider request observed by this extension instance, in order, each with a live context-usage snapshot. Byte-identical payloads are stored once in payloads, keyed by sha256 of the serialized request — content and count are preserved, only duplicate bytes are factored out. Auth headers are never part of a request payload; a response is not part of the request that produced it; later-loaded extensions may mutate the payload after this hook observes it. Capture resets on session_start, reload, or resume.",
+                    },
+                    stats: {
+                        source:
+                            "Persisted assistant, tool-result, compaction, and branch-summary usage; timing records are excluded to avoid double counting.",
+                        activeBranch: collectUsage(activeBranch),
+                        wholeSession: collectUsage(entries),
+                        liveContext: contextUsageSnapshot(ctx.getContextUsage(), ctx.model?.contextWindow),
+                    },
+                    timings: {
+                        source: "Persisted operation-timing records produced by the timings extension, if installed.",
+                        activeBranch: {
+                            records: activeTimings,
+                            summary: summarizeTimings(activeTimings),
+                        },
+                        wholeSession: {
+                            records: wholeSessionTimings,
+                            summary: summarizeTimings(wholeSessionTimings),
+                        },
+                    },
+                };
+
+                const bytes = await writeExclusiveJson(destination, document);
+                ctx.ui.notify(
+                    `Exported ${entries.length} session entries, ${requestRecords.length} provider requests ` +
+                        `(${Object.keys(payloads).length} unique payloads), ${wholeSessionTimings.length} timing records ` +
+                        `— ${formatBytes(bytes)} — to:\n${destination}`,
+                    "info",
+                );
+            } catch (error) {
+                ctx.ui.notify(`Export failed: ${errorMessage(error)}`, "error");
+            }
+        },
+    });
+
+    // ─── /export-my-chat:revive ───────────────────────────────────────────────
+
+    pi.registerCommand("export-my-chat:revive", {
+        description:
+            "Revive a chat from an /export-my-chat JSON: rebuilds a session file into pi's session dir and switches this window onto it",
+        getArgumentCompletions: (prefix: string): AutocompleteItem[] | null =>
+            currentCwd ? jsonFileCompletions(currentCwd, prefix) : null,
+        handler: async (args, ctx) => {
+            try {
+                // Same "at rest" contract as export — checked first so a
+                // mid-turn revive fails fast, before any reading.
+                if (ctx.isIdle() !== true) {
+                    ctx.ui.notify(
+                        "Revive refused: pi is not idle. Wait for the current turn (or press Esc), then run it again.",
+                        "error",
+                    );
+                    return;
+                }
+                currentCwd = ctx.cwd;
+
+                const parsedArgs = parseReviveArgs(args ?? "", ctx.cwd);
+                if (!parsedArgs.ok) {
+                    ctx.ui.notify(parsedArgs.error ?? "Invalid arguments.", "error");
+                    return;
+                }
+
+                // Read and validate the export before touching any state.
+                let raw: string;
+                try {
+                    const info = statSync(parsedArgs.path);
+                    if (!info.isFile()) throw new Error("path is not a regular file");
+                    raw = await fsp.readFile(parsedArgs.path, "utf8");
+                } catch (error) {
+                    ctx.ui.notify(`Cannot read export: ${errorMessage(error)}`, "error");
+                    return;
+                }
+
+                let doc: any;
+                try {
+                    doc = JSON.parse(raw);
+                } catch (error) {
+                    ctx.ui.notify(`Export is not valid JSON: ${errorMessage(error)}`, "error");
+                    return;
+                }
+
+                const validation = validateExportDocument(doc, { maxHeaderVersion: CURRENT_SESSION_VERSION });
+                if (!validation.ok) {
+                    ctx.ui.notify(`Refusing to revive — ${validation.errors.join(" ")}`, "error");
+                    return;
+                }
+
+                // Replacing a non-empty chat is destructive to the current
+                // window's context (the old session stays on disk). Confirm
+                // unless --force. Headless mode (no dialog UI) cannot confirm,
+                // so it must pass --force — ui.confirm exists everywhere but is
+                // a silent no-op returning false without a UI.
+                const currentEntries = ctx.sessionManager.getEntries();
+                if (currentEntries.length > 0 && !parsedArgs.force) {
+                    let confirmed = false;
+                    if (ctx.hasUI) {
+                        confirmed = await ctx.ui.confirm(
+                            "Revive into this window?",
+                            `The current session has ${currentEntries.length} entries and will be replaced ` +
+                                `(it remains saved on disk). Continue?`,
+                        );
+                    }
+                    if (!confirmed) {
+                        ctx.ui.notify(
+                            "Revive cancelled. Use /export-my-chat:revive --force to skip this prompt " +
+                                "(required in headless mode).",
+                            "info",
+                        );
+                        return;
+                    }
+                }
+
+                const sessionManager: any = ctx.sessionManager;
+                const sessionDir: string = sessionManager.getSessionDir();
+                const uuidExists = (uuid: string): boolean => {
+                    try {
+                        return readdirSync(sessionDir).some((name) => name.endsWith(`_${uuid}.jsonl`));
+                    } catch {
+                        return false;
+                    }
+                };
+
+                const plan = buildRevivePlan(doc, {
+                    cwd: ctx.cwd,
+                    sessionDir,
+                    uuidExists,
+                    newUUID: () => randomUUID(),
+                });
+
+                // Exclusive, private write into pi's session dir, then switch
+                // this window onto the revived session. All post-switch work
+                // must go through the withSession ctx (the old ctx is stale).
+                mkdirSync(sessionDir, { recursive: true }); // defensive; pi normally creates it
+                let handle: any;
+                try {
+                    handle = await fsp.open(plan.filePath, "wx", 0o600);
+                    await handle.writeFile(plan.jsonl, "utf8");
+                    await handle.sync();
+                    await handle.close();
+                    handle = undefined;
+                } catch (error) {
+                    await handle?.close().catch(() => {});
+                    ctx.ui.notify(`Failed to write revived session: ${errorMessage(error)}`, "error");
+                    return;
+                }
+
+                const summary =
+                    `Revived ${plan.entryCount} entries` +
+                    (plan.appendedName ? `, re-attached name "${plan.appendedName}"` : "") +
+                    ` → ${plan.filePath}. The session remembers files from ${doc.session.cwd ?? "(unknown cwd)"}.`;
+
+                // Another extension (or a project-trust prompt) can cancel the
+                // switch. The revived file is already safely on disk, so say so
+                // instead of failing silently.
+                const result = await ctx.switchSession(plan.filePath, {
+                    withSession: async (revivedCtx) => {
+                        revivedCtx.ui.notify(summary, "info");
+                    },
+                });
+                if (result.cancelled) {
+                    ctx.ui.notify(
+                        `Switch to the revived session was cancelled — the rebuilt session is saved and ` +
+                            `available via /resume:\n${plan.filePath}`,
+                        "warning",
+                    );
+                }
+            } catch (error) {
+                ctx.ui.notify(`Revive failed: ${errorMessage(error)}`, "error");
+            }
+        },
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pi-export-my-chat",
+  "version": "1.0.0",
+  "description": "pi extension that exports a running chat to one complete, lossless, revivable JSON — the full session tree, every provider request observed (content-hash deduplicated), usage/cost/context stats, and timings — and revives that JSON back into a live, named pi session on any machine via /export-my-chat:revive.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "session",
+    "export",
+    "backup",
+    "portable",
+    "resume"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "files": ["*"],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "node --test tests/helpers.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}