pi-export-my-chat 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The export-my-chat authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# export-my-chat
+
+A [pi](https://github.com/earendil-works/pi-mono) extension that turns a running
+chat into **one complete, lossless, revivable JSON file** — and turns that file
+back into a living pi session on any machine.
+
+Two commands, one contract:
+
+1. **`/export-my-chat`** — writes a single self-contained `.json`: the durable
+   session tree (header, every entry, active branch, active context), **every
+   provider request observed during the session** (deduplicated by content
+   hash, never dropped), usage/cost/context stats, and operation timings.
+   Refuses to run while the agent is mid-turn, never overwrites, writes
+   `0600`.
+2. **`/export-my-chat:revive <path> [--force]`** — validates that export, rebuilds
+   a real pi session file from it, saves it into pi's session directory for the
+   project you're standing in, and switches the current pi window onto it. The
+   chat comes back — named, branchable, listed in `/resume` — on an entirely
+   different machine.
+
+```
+/export-my-chat                              # -> ./pi-my-chat-export-<UTC>.json
+/export-my-chat /abs/path/chat.json         # -> exact file; must NOT exist
+/export-my-chat:revive ~/backups/chat.json  # -> rebuilds + switches this window
+/export-my-chat:revive chat.json --force     # relative paths ok for reads; --force skips the prompt
+```
+
+---
+
+## Why this exists
+
+pi already persists sessions as JSONL under `~/.pi/agent/sessions/` — so why an
+export tool? Because the session file is pi's *internal logical record*. It
+answers "what did pi store." It cannot answer:
+
+- **"What did the model actually receive?"** — the provider-facing request
+  bodies (system prompt rendering, tool schemas, cache markers, the exact
+  context slice the provider saw at every turn) exist only at request time.
+- **"What did the model see *over time*?"** — compaction and branching change
+  the context slice on every request; only a per-request record shows that
+  evolution.
+- **"Can I pick this chat up, move it, and keep working?"** — a session file is
+  machine-local by convention (keyed by its original `cwd`, unlisted in other
+  projects), and carries no usage stats, timings, or request history.
+
+This extension makes the portable artifact the *unit of work*: one JSON that is
+simultaneously a forensic record of the session and a seed from which the
+session can be reborn.
+
+## Design philosophy — every choice, first principles
+
+- **Lossless in content AND count.** The default is *all* requests, not the
+  latest one. Tool-heavy sessions re-send nearly identical context every turn,
+  so literal duplication is factored out by content hash (byte-identical
+  payloads are stored once, referenced by `sha256`) — but no request is ever
+  dropped, and ordering is preserved. "Lossless" is a property of the set of
+  observed requests, not of its most recent member.
+- **Losslessness must be *provable*, not claimed.** The revivable core (header
+  + ordered entries) is serialized by one canonical function — `buildSessionJsonl`
+  — used by *both* export (to compute the checksum) and revive (to rebuild the
+  file). Revive recomputes and refuses on mismatch. Corrupt or edited exports
+  fail loudly, before any state is touched.
+- **The at-rest contract.** Both commands refuse while the agent is mid-turn.
+  A snapshot taken mid-flight describes a moving target; a refused command is
+  cheaper than a subtly-wrong export. (No silent `waitForIdle` — you asked for
+  idle, you get a refusal until idle.)
+- **Strict writes, forgiving reads.** Export destinations must be absolute
+  `.json` paths that don't exist yet, with an existing parent directory —
+  exclusive `0600` creation, no overwrite, no symlink following, partial files
+  cleaned up on failure. Revive *inputs* are read-only, so relative paths and
+  quoting are accepted there. Asymmetry is deliberate: writing is dangerous,
+  reading is not.
+- **The session file IS the wire format.** Revival doesn't need a bespoke
+  importer: pi sessions are header line + ordered entry lines of JSONL, and
+  `ctx.switchSession(path)` loads any session file. Revive reconstructs exactly
+  that shape, then hands it to pi's own machinery. No parallel schema to rot.
+- **Portability with identity, not anonymity.** A revived session keeps its
+  original UUID on a new machine (so it's *the same chat*, not a clone) and
+  mints a fresh one only where the original still exists (same machine —
+  avoiding ambiguous `pi --session <id>` matches). The header `cwd` is
+  re-rooted to the reviving project: the session becomes native to where you
+  are, which is what puts it in the right `/resume` bucket. The original cwd is
+  never lost — it's in the export and in the revive notice.
+- **Versioned on three axes.** Every export records the export format
+  `schemaVersion`, pi's `CURRENT_SESSION_VERSION`, and the extension version.
+  Revive refuses (rather than half-loads) anything newer than what the local
+  machine understands. Older session formats migrate up automatically — pi
+  migrates v1/v2→v3 on load, so *older* is always fine.
+- **The name is data, not metadata.** pi stores the session name as a
+  `session_info` entry *inside the entry tree*, so a faithful rebuild carries
+  the name for free — revived sessions show up in `/resume` with their names.
+  The export also surfaces `session.name` for humans; if the entries somehow
+  lost the name, revive re-attaches it as a trailing `session_info` entry —
+  the same mechanism `/name` uses. No name → nothing appended → pi's default
+  naming applies.
+- **Capture to disk, not RAM.** Every request is appended to a per-session
+  scratch journal in the agent cache dir the moment it's observed. "All
+  requests" can mean tens of MB for a long session; the journal keeps that on
+  disk and only merges + deduplicates at export time. The journal resets on
+  `session_start` (new session, resume, or `/reload`), is written `0600` like
+  the exports themselves, and journals untouched for 30+ days are pruned
+  automatically on `session_start`.
+- **Destructive acts ask.** Reviving replaces the current window's context. A
+  non-empty current session gets a confirmation prompt. Headless callers have
+  no dialog UI, so pi's confirm would silently answer "no" — revive therefore
+  requires `--force` when there is no UI. The old session always stays on disk.
+- **Honest capture metadata.** `requests.note` records the exactness
+  boundaries of `before_provider_request`: auth headers are never in a
+  payload; a response is not part of the request that produced it; later-loaded
+  extensions may mutate the payload after this hook sees it; capture resets
+  when the runtime resets. The export says what it knows *and* what it can't.
+
+## What the JSON contains that a pi session file doesn't
+
+| In the export, not in the session file | Why |
+|---|---|
+| Every provider request body | The session stores *logical* messages; the export stores the provider-shaped JSON the model received — system prompt rendering, tool schemas, thinking config |
+| The full request sequence | Shows how compaction/branching changed the context slice on every turn |
+| Per-request live context snapshots | `used / window / remaining / percentUsed` at the moment of each request |
+| Per-request model metadata | provider / model / api as of each call, plus a request counter |
+| Whole-session + active-branch usage & cost | Cache-token breakdowns, nested tool usage, compaction and branch-summary costs — aggregated, NaN-guarded, timing records excluded to avoid double-counting |
+| Operation timing summaries | Per-kind min/max/avg/status, with overlap notes |
+| The revivable core + checksum | The session tree re-serialized canonically, with a sha256 that proves the rebuild is byte-faithful |
+
+The genuinely unique content is the request payloads and per-request context
+snapshots; the stats and timings are *derived* from records that do live in the
+session file, re-organized for analysis.
+
+## Quick start
+
+1. The extension is auto-discovered at `~/.pi/agent/extensions/export-my-chat/`
+   (or installed as an npm package — see below). Restart pi or run `/reload`.
+2. Chat. Say things, run tools, branch, compact — live your best life.
+3. When the agent is idle, run `/export-my-chat`. Note the reported entry and
+   request counts.
+4. Carry `pi-my-chat-export-….json` wherever it needs to go.
+5. On any machine with this extension: open pi in the project directory,
+   run `/export-my-chat:revive <path/to/export.json>`, confirm, and continue
+   the chat. The revived session is saved in this machine's
+   `~/.pi/agent/sessions/` and listed in `/resume`.
+
+## How the pieces work
+
+### Request capture
+
+`before_provider_request` fires before every HTTP call with the complete
+provider-specific payload. The handler serializes it immediately, records a
+sha256, a live `getContextUsage()` snapshot (unknown token counts are recorded
+as `null`, never as `0` — pi cannot estimate right after compaction), and the
+model metadata, and appends the record to
+`~/.pi/agent/cache/export-my-chat/<sessionId>.jsonl` with mode `0600`.
+`session_start` truncates the journal — the capture window is per-runtime, so
+resuming or `/reload` resets it — and prunes journals untouched for 30+ days.
+At export time the journal is merged: byte-identical payloads collapse into a
+`payloads` map keyed by hash, and the ordered `records` array keeps every
+request with its `payloadSha256` reference.
+
+### The revivable core
+
+`session.header`, `session.entries` (insertion order — the last entry *is* the
+leaf, i.e. the branch position), and `session.leafId`. The checksum is sha256
+over the canonical JSONL built from exactly these. `session.revive` also
+records `matchesOriginalFile`: whether the canonical rebuild is byte-identical
+to pi's own on-disk session file. It's a diagnostic, not a gate — the checksum
+covers what *revive writes*, which is what matters for fidelity.
+
+### Revive, step by step
+
+1. **Guards** — refuses mid-turn (checked first, before any reading); confirms
+   before replacing a non-empty current session (`--force` skips; headless
+   requires it).
+2. **Parse + validate** — path (relative ok, quotes ok), format, schema
+   version, session header version vs this pi's `CURRENT_SESSION_VERSION`,
+   structural integrity (unique ids, resolvable parents, leaf = last entry,
+   declared entry count), and the sha256 checksum. Any failure refuses
+   before touching session state.
+3. **Rebuild** — header re-rooted to `ctx.cwd`, original UUID kept unless it
+   collides locally, name re-attached if the entries lost it, written
+   exclusively `0600` into `ctx.sessionManager.getSessionDir()` using pi's own
+   filename convention (`<timestamp>_<uuid>.jsonl`, same timestamp format pi
+   itself mints).
+4. **Switch** — `ctx.switchSession(path)` makes the revived session the current
+   chat; further messages append to it like any native session. If another
+   extension cancels the switch, the rebuilt file is still safe on disk and the
+   notice points at it. The success notice reports entry count, name changes,
+   and the original cwd.
+
+### Stats
+
+Usage and cost are collected from persisted records — assistant messages,
+nested model usage on tool results, compaction, and branch summaries — with
+NaN/Infinity clamps, provider-reported totals preferred over component sums,
+and timing records excluded (an agent-total timing overlaps its child
+records; counting both would double-count). Stats are reported for both the
+active branch and the whole session, plus a live context snapshot. Timing
+records from the `timings` extension (if installed) are exported raw and
+summarized per kind, with an explicit note that kinds overlap in wall time.
+
+## Security
+
+Treat every export as maximally sensitive. It contains your system prompt,
+context files, full conversations, tool output, source code, base64 images,
+absolute paths, and anything secret that ever entered the chat or a request.
+The export and every revived session file are written `0600`; the scratch
+journals that hold the same request payloads are written `0600` under a `0700`
+cache directory and are pruned automatically after 30 days of inactivity.
+Export refuses existing destinations (including symlinks) and cleans up partial
+files. Revive refuses exports that fail validation. Never commit an export;
+leftover scratch journals can be deleted by hand as well.
+
+## Caveats & limits
+
+- **Requests are only what this runtime observed.** Requests made before the
+  extension loaded (or before a `/reload`) are not in the journal. The export
+  reports `captureStartedAt` and `observedRequestCount` so the window is
+  always visible.
+- **Auth headers are never captured** (they aren't part of the payload), and
+  **responses are not requests** — final assistant replies live in the session
+  tree, not in the payload that produced them.
+- **Later-loaded extensions may mutate payloads** after this hook observes
+  them. The record is exact for what *this* hook saw.
+- **Version skew**: an export made by a newer pi (higher session header
+  version) or newer extension schema is refused on older machines with a clear
+  message. Older exports revive on newer pi via pi's own session migrations.
+- **The working tree doesn't travel.** A revived session *remembers* files
+  from the original machine; the new machine's tree is whatever it is. Revive's
+  notice names the original cwd for exactly this reason.
+- **The `withSession` rebind**: after `ctx.switchSession`, the old extension
+  instance's contexts are stale; all post-switch reporting goes through the
+  fresh `ctx` pi hands back.
+
+## Validation
+
+From the package root:
+
+```bash
+node --test tests/helpers.test.mjs     # 14 unit tests: paths, usage, timings,
+                                       # exclusive write, JSONL, checksum,
+                                       # document validation, revive plan
+pi --list-models >/dev/null             # extension loads without errors
+```
+
+Interactive checklist: run a session with tools and branches; `/export-my-chat`;
+verify mode `0600` (`ls -l`), confirm the entry/request counts in the notice,
+confirm a second export to the same path fails; edit the JSON's entries
+slightly and confirm `revive` refuses on checksum; revive on another machine
+(or `/new` first at home) and confirm the name, tree (`/tree`), and
+`/resume` listing.
+
+## Package
+
+Published as `pi-export-my-chat` (see `package.json`). Install with pi's
+package mechanism:
+
+```
+pi --install pi-export-my-chat
+```
+
+The `pi.extensions` manifest points at `./index.ts`; `helpers.mjs` and
+`tests/` ship alongside. No runtime dependencies — only node builtins and a
+peer dependency on pi itself. `docs/export-format.md` holds the full field
+reference for the export JSON.
+
+## Repository layout
+
+```
+export-my-chat/
+├── index.ts               — the extension: capture, /export-my-chat, /export-my-chat:revive
+├── helpers.mjs            — pure logic: usage, timings, paths, canonical JSONL,
+│                            checksum, document validation, revive planning
+├── tests/helpers.test.mjs — node:test unit tests for all of the above
+├── docs/export-format.md  — complete schema reference for the export JSON
+├── README.md              — this file
+└── package.json           — npm-publishable manifest + pi entry point
+```
+
+MIT license. Sessions are yours.

package/docs/export-format.md

@@ -0,0 +1,140 @@
+# Export format reference
+
+`/export-my-chat` writes one JSON document. This is the complete field
+reference for `format: "pi-my-chat-export"`, `schemaVersion: 1`.
+
+A minimal valid document has: `format`, `schemaVersion`, `session.entries`,
+`session.header`, and `session.revive.checksum` consistent with the entries.
+Everything else is additive — consumers should ignore unknown top-level keys
+and tolerate missing optional fields (forward-compatible minor revisions).
+
+## Top level
+
+| Field | Type | Notes |
+|---|---|---|
+| `format` | `"pi-my-chat-export"` | Discriminator. Revive refuses anything else. |
+| `schemaVersion` | number | Currently `1`. Revive refuses values *newer* than it understands. |
+| `exportedAt` | ISO string | Wall time of the export. |
+| `exportedBy` | object | Provenance — see below. |
+| `session` | object | The durable record + revive data. |
+| `requests` | object | Every observed provider request. |
+| `stats` | object | Derived usage/cost/context totals. |
+| `timings` | object | Operation-timing records and summaries (if a timings extension produced any). |
+
+### `exportedBy`
+
+| Field | Notes |
+|---|---|
+| `extension` | Always `"export-my-chat"`. |
+| `extensionVersion` | Version of the extension that wrote the file. |
+| `sessionHeaderVersion` | `session.header.version` as exported. |
+| `currentSessionVersion` | The *writing* pi's max supported session format (`CURRENT_SESSION_VERSION`). A machine whose pi is older than the *header* version revives nothing — that check is against `session.header.version` itself. |
+
+## `session`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Session UUID. |
+| `name` | string \| null | Latest `session_info` name; **also present in the entries** as a `session_info` entry. Metadata here is for humans and for revive's name fallback. |
+| `cwd` | string | The *exporting* machine's working directory. Revive re-roots the rebuilt header to its own cwd; the original lives on here. |
+| `sessionFile` | string \| null | Path of the session file on the exporting machine (diagnostic). |
+| `header` | object | The session header line, verbatim (`type: "session"`, `version`, `id`, `timestamp`, `cwd`, optionally `parentSession`). |
+| `leafId` | string \| null | Active leaf at export time. |
+| `entries` | array | **The complete entry tree in insertion order.** The last entry is the active leaf. This ordering *is* the branch position; preserve it byte-for-byte when rebuilding. Entry shapes are pi's own (message / model_change / thinking_level_change / compaction / branch_summary / custom / custom_message / label / session_info). |
+| `activeBranchEntryIds` | string[] | Ids of the entries on the active leaf→root path. |
+| `activeContext` | object | `SessionManager.buildSessionContext()` — the message list the LLM would receive at export time, plus model/thinking settings. |
+| `revive` | object | Revival contract — see below. |
+
+### `session.revive`
+
+| Field | Type | Notes |
+|---|---|---|
+| `checksum` | string | **sha256 hex over the canonical JSONL**: `JSON.stringify(header)` line, then one `JSON.stringify(entry)` line per entry in order, joined by `\n` with a trailing `\n`. This is the exact byte sequence revive writes. Revive recomputes and refuses on mismatch. |
+| `headerVersion` | number \| null | The header's `version` (convenience copy). |
+| `entryCount` | number | `session.entries.length`. Revive cross-checks it against the actual entries array. |
+| `lastEntryId` | string \| null | Last entry's id; revive cross-checks it against the actual last entry. |
+| `matchesOriginalFile` | boolean \| null | Whether the canonical rebuild was byte-identical to pi's own on-disk session file at export time. Diagnostic only — a `false` never blocks anything, since the checksum covers what *revive writes*. |
+| `note` | string | Human explanation of the above. |
+
+**Declared revival transformations** (applied by revive *after* checksum
+verification, so they never interact with it):
+
+1. `session.header.cwd` → the reviving machine's cwd.
+2. Session UUID kept as-is, unless a `<timestamp>_<uuid>.jsonl` with that UUID
+   already exists in the target session dir → fresh UUID minted.
+3. If `session.name` is a non-empty string and no `session_info` entry exists in
+   `entries`, one `session_info` entry is appended (parentId = last entry id)
+   — the same mechanism pi's `/name` uses.
+
+The revived file is named with pi's own timestamp convention
+(`<toISOString().replace(/[:.]/g, "-")>_<uuid>.jsonl`, e.g.
+`2026-04-13T12-34-56-789Z_11111111-….jsonl`) so it is indistinguishable from
+sessions pi created itself.
+
+## `requests`
+
+| Field | Type | Notes |
+|---|---|---|
+| `captureStartedAt` | ISO string | Start of the current capture window (resets on session_start / resume / `/reload`). |
+| `observedRequestCount` | number | Total requests seen this window — equals `records.length` unless a capture error occurred. |
+| `scratchFile` | string \| null | The per-session journal under the agent cache dir (diagnostic; safe to prune). |
+| `latestCaptureError` | string \| null | Last capture failure, if any — the export still succeeds with whatever was journaled. |
+| `records` | array | One record per observed request, **in order** — see below. |
+| `payloads` | object | `sha256 → payload` store. Byte-identical payloads appear once; `records[i].payloadSha256` is the join key. Content and count are preserved; only duplicate *bytes* are factored out. |
+| `note` | string | Capture boundaries: auth headers excluded; a response is not part of the request that produced it; later-loaded extensions may mutate the payload after capture; capture resets with the runtime. |
+
+### `requests.records[i]`
+
+| Field | Type | Notes |
+|---|---|---|
+| `n` | number | 1-based request number within the window. |
+| `capturedAt` | ISO string | When `before_provider_request` observed it. |
+| `provider`, `model`, `api` | string \| undefined | Model metadata as of the request. |
+| `contextUsage` | object | Live snapshot at capture: `used`, `window`, `remaining`, `percentUsed` — `used`/`remaining`/`percentUsed` are `null` when pi could not estimate tokens at that moment (e.g. right after compaction); `window` falls back to the usage snapshot's own `contextWindow` when the model's is unknown. |
+| `payloadSha256` | string | Join key into `requests.payloads`. |
+
+## `stats`
+
+| Field | Notes |
+|---|---|
+| `source` | Statement of what was counted. |
+| `activeBranch`, `wholeSession` | Same shape; scope differs. `usageRecords` counts entries that carried usage. Token fields: `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens` (provider-reported total preferred, else component sum). Cost object: per-component plus `total`. Sources: assistant messages, toolResult nested usage, `compaction` and `branch_summary` entries. Timing records never contribute. NaN/Infinity/negative inputs clamp to 0. |
+| `liveContext` | Context snapshot at export time (same shape as `contextUsage` above). |
+
+## `timings`
+
+| Field | Notes |
+|---|---|
+| `source` | Where the records came from (the timings extension's persisted `operation-timing` custom entries). |
+| `activeBranch.records` / `wholeSession.records` | Raw records: `schemaVersion: 1`, `operationId`, `kind`, `startedAt`, `endedAt`, `durationMs`, `status`. |
+| `activeBranch.summary` / `wholeSession.summary` | `recordCount`, `byKind[kind]` = `{ count, totalDurationMs, averageDurationMs, minDurationMs, maxDurationMs, statuses }`, plus an overlap note. Kinds overlap in wall time — never sum across kinds. |
+
+## Revive algorithm (normative)
+
+```
+1. **guard**: pi idle (checked before any reading)
+2. path  := resolve(args)             # relative ok; quotes ok; --force flag
+3. doc   := JSON.parse(read(path))
+4. validate(doc):
+     doc.format == "pi-my-chat-export"
+     doc.schemaVersion <= SCHEMA_VERSION
+     doc.session.header.version <= CURRENT_SESSION_VERSION
+     doc.session.revive.entryCount == session.entries.length (when declared)
+     validateSessionCore(header, entries,
+                         expectedChecksum=doc.session.revive.checksum,
+                         expectedLastEntryId=doc.session.revive.lastEntryId)
+5. guard: non-empty current session -> confirm (or --force; headless has no
+   confirm dialog and must pass --force)
+6. plan := buildRevivePlan(doc):
+     header.cwd := ctx.cwd
+     uuid       := original unless collides in sessionDir, else fresh
+     if session.name and no session_info entry: append one
+     jsonl      := canonical(header', entries')
+     filePath   := <sessionDir>/<pi-format timestamp>_<uuid>.jsonl
+7. write jsonl exclusively, 0600, fsync
+8. switch  := ctx.switchSession(filePath)
+     switch.cancelled -> notify (file is saved and /resume-able)
+```
+
+Everything from step 3 on uses the same `buildSessionJsonl` as the exporter,
+so the checksum is consistent by construction.