@8monkey/pi-session-gzip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Infinite Monkey AI
+
+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,53 @@
+# pi-session-gzip
+
+Gzip Pi session files at rest. When a session closes it's compressed to a `.jsonl.gz` file alongside the original and the plain file is removed; `/resume-compressed` restores and reopens it on demand. Plain JSONL stays Pi's working format — nothing changes during a live session.
+
+Built for anyone whose `~/.pi/agent/sessions/` has grown large and wants closed sessions to sit compressed without losing the ability to reopen them.
+
+## How it works
+
+- **Compress on shutdown.** Quitting Pi compresses the closed session's `session.jsonl` to `session.jsonl.gz` and removes the plain file.
+- **Restore on demand.** Run `/resume-compressed` to pick from this project's compressed sessions (newest first); your choice is decompressed and reopened in place. Pass an id or path to skip the picker.
+
+Zero runtime dependencies. Pi loads the TypeScript directly, so there's no build step. Runs under Node or Bun.
+
+## Install
+
+```bash
+pi install npm:@8monkey/pi-session-gzip
+```
+
+That's it — the extension loads on the next `pi` launch. Update with `pi update`.
+
+For development against a local clone, point pi at the file directly in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": [
+    "~/pi-session-gzip/src/index.ts"
+  ]
+}
+```
+
+## Command
+
+| Command | Description |
+|---|---|
+| `/resume-compressed [id\|path]` | Restore a compressed session and reopen it. With no argument, shows a picker of this project's compressed sessions (newest first). Accepts a session id (exact or prefix) or a file path. |
+
+## Behaviour notes
+
+- Compresses on quit only; live sessions, reloads, and switches are left untouched.
+- Restoring is safe to repeat — running compress or restore twice is a no-op.
+- Ephemeral (`--no-session`) and empty sessions are skipped.
+- The `.gz` sits next to the original; the sessions layout is never reorganized.
+
+## Development
+
+```bash
+node --test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@8monkey/pi-session-gzip",
+  "version": "0.1.0",
+  "description": "Pi extension that gzips session files on shutdown and restores them on demand.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/8monkey-ai/pi-session-gzip.git"
+  },
+  "homepage": "https://github.com/8monkey-ai/pi-session-gzip#readme",
+  "bugs": "https://github.com/8monkey-ai/pi-session-gzip/issues",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "gzip",
+    "sessions"
+  ]
+}

package/src/gzip.ts

@@ -0,0 +1,52 @@
+import {
+	closeSync,
+	existsSync,
+	fsyncSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeSync,
+} from "node:fs";
+import { gunzipSync, gzipSync } from "node:zlib";
+
+export const GZ_SUFFIX = ".gz";
+
+// Write via a temp sibling + fsync + atomic rename so readers never observe a
+// half-written file, even across a crash.
+function writeFileDurable(targetPath: string, data: Buffer): void {
+	const tmpPath = `${targetPath}.tmp-${process.pid}`;
+	const fd = openSync(tmpPath, "w");
+	try {
+		writeSync(fd, data);
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmpPath, targetPath);
+}
+
+// Compress `jsonlPath` to a `.gz` file beside it and remove the plain file. The .gz
+// is durably in place before the plain file is unlinked, so a crash leaves at
+// least one intact copy. Returns the .gz path, or null when there is nothing to
+// compress (a session quit before it was ever persisted, or an empty file).
+export function gzipFile(jsonlPath: string): string | null {
+	if (!existsSync(jsonlPath)) return null;
+
+	const plain = readFileSync(jsonlPath);
+	if (plain.length === 0) return null;
+
+	const gzPath = `${jsonlPath}${GZ_SUFFIX}`;
+	writeFileDurable(gzPath, gzipSync(plain));
+
+	rmSync(jsonlPath, { force: true });
+	return gzPath;
+}
+
+// Decompress `gzPath` back to its `.jsonl`, leaving the `.gz` in place. Returns
+// the restored path. Throws (ENOENT) if the .gz is missing.
+export function gunzipFile(gzPath: string): string {
+	const jsonlPath = gzPath.slice(0, -GZ_SUFFIX.length);
+	writeFileDurable(jsonlPath, gunzipSync(readFileSync(gzPath)));
+	return jsonlPath;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { gunzipFile, gzipFile } from "./gzip.ts";
+import { listCompressedSessions, resolveGzPath } from "./session-paths.ts";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_shutdown", async (event, ctx) => {
+		// Only "quit" means pi is done with the file. reload/new/resume/fork
+		// reopen or switch files, so compressing then could remove a file pi
+		// still reads.
+		if (event.reason !== "quit") return;
+
+		const file = ctx.sessionManager.getSessionFile();
+		if (!file) return;
+
+		const gz = gzipFile(file);
+		if (gz && ctx.hasUI) {
+			ctx.ui.notify(`Compressed session to ${gz.split("/").pop()}.`, "info");
+		}
+	});
+
+	pi.registerCommand("resume-compressed", {
+		description: "Decompress a compressed session (.jsonl.gz) and resume it",
+		handler: async (args, ctx) => {
+			const sessionDir = ctx.sessionManager.getSessionDir();
+			const arg = args.trim();
+			const gzPath = arg ? resolveGzPath(arg, sessionDir) : (await pickCompressedSession(ctx, sessionDir))?.gzPath;
+			if (gzPath) await decompressAndResume(gzPath, ctx);
+		},
+	});
+}
+
+async function pickCompressedSession(ctx: ExtensionCommandContext, sessionDir: string) {
+	const sessions = listCompressedSessions(sessionDir);
+	if (sessions.length === 0) {
+		ctx.ui.notify("No compressed sessions in this project.", "info");
+		return undefined;
+	}
+
+	const labels = sessions.map((s) => {
+		const when = new Date(s.modified).toISOString().slice(0, 16).replace("T", " ");
+		const preview = s.preview.replace(/\s+/g, " ").slice(0, 60) || "(no messages)";
+		return `${when}  ${preview}`;
+	});
+	const choice = await ctx.ui.select("Resume compressed session", labels);
+	return choice === undefined ? undefined : sessions[labels.indexOf(choice)];
+}
+
+async function decompressAndResume(gzPath: string, ctx: ExtensionCommandContext) {
+	let restored: string;
+	try {
+		restored = gunzipFile(gzPath);
+	} catch (err) {
+		ctx.ui.notify(`Failed to decompress session: ${(err as Error).message}.`, "warning");
+		return;
+	}
+
+	const { cancelled } = await ctx.switchSession(restored);
+	if (cancelled) ctx.ui.notify("Resume cancelled.", "info");
+}

package/src/session-paths.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { GZ_SUFFIX } from "./gzip.ts";
+
+function extractText(content: unknown) {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => (part && typeof part === "object" && "text" in part ? String((part as { text: unknown }).text) : ""))
+			.join(" ")
+			.trim();
+	}
+	return "";
+}
+
+function looksLikePath(arg: string) {
+	return arg.includes("/") || arg.includes("\\") || arg.endsWith(".jsonl") || arg.endsWith(".jsonl.gz");
+}
+
+function gzPathFromArg(arg: string, base: string) {
+	const abs = isAbsolute(arg) ? arg : resolve(base, arg);
+	return abs.endsWith(GZ_SUFFIX) ? abs : `${abs}${GZ_SUFFIX}`;
+}
+
+function gzPathsIn(dir: string) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir)
+		.filter((f) => f.endsWith(`.jsonl${GZ_SUFFIX}`))
+		.map((f) => join(dir, f));
+}
+
+function toInfo(gzPath: string) {
+	try {
+		const lines = gunzipSync(readFileSync(gzPath)).toString("utf8").split("\n");
+		const header = JSON.parse(lines[0]) as { type?: string; id?: unknown };
+		if (header.type !== "session" || typeof header.id !== "string") return undefined;
+
+		let preview = "";
+		for (let i = 1; i < lines.length && !preview; i++) {
+			if (!lines[i]) continue;
+			try {
+				const entry = JSON.parse(lines[i]) as { type?: string; message?: { role?: string; content?: unknown } };
+				if (entry.type === "message" && entry.message?.role === "user") preview = extractText(entry.message.content);
+			} catch {
+				// Skip malformed line.
+			}
+		}
+		return { gzPath, id: header.id, preview, modified: statSync(gzPath).mtimeMs };
+	} catch {
+		return undefined;
+	}
+}
+
+// Compressed sessions in `sessionDir` (the live session's directory), newest first.
+export function listCompressedSessions(sessionDir: string) {
+	return gzPathsIn(sessionDir)
+		.map(toInfo)
+		.filter((s) => s !== undefined)
+		.sort((a, b) => b.modified - a.modified);
+}
+
+// Resolve a `<id|path>` argument to a compressed session's `.gz` path in
+// `sessionDir`. A path resolves directly; an id matches a session header
+// (exact, else prefix). Returns null when no id matches.
+export function resolveGzPath(arg: string, sessionDir: string): string | null {
+	const trimmed = arg.trim();
+	if (looksLikePath(trimmed)) return gzPathFromArg(trimmed, sessionDir);
+
+	const sessions = listCompressedSessions(sessionDir);
+	return (sessions.find((s) => s.id === trimmed) ?? sessions.find((s) => s.id.startsWith(trimmed)))?.gzPath ?? null;
+}