pi-session-mail 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "pi-session-mail",
+	"version": "0.1.0",
+	"description": "A file mailbox between Pi sessions on the same machine",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension"
+	],
+	"license": "MIT",
+	"author": "Gage Vander Clay <gvanderclay@gmail.com>",
+	"homepage": "https://github.com/gvanderclay/pi-session-mail#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gvanderclay/pi-session-mail.git"
+	},
+	"bugs": {
+		"url": "https://github.com/gvanderclay/pi-session-mail/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"packageManager": "pnpm@10.33.0",
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"files": [
+		"index.ts",
+		"store.ts",
+		"running.ts",
+		"tools.ts",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"lint": "biome ci .",
+		"typecheck": "tsc -p .",
+		"test": "node --test test/*.test.ts",
+		"check": "pnpm lint && pnpm typecheck && pnpm test",
+		"release": "node scripts/release.mjs"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.14",
+		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@types/node": "26.6.3",
+		"typebox": "1.3.27",
+		"typescript": "7.0.2"
+	}
+}

package/running.ts

@@ -0,0 +1,156 @@
+// Running-session records and `to` resolution. Internal to `pi-session-mail`: tests
+// reach it only through the extension's registration function.
+//
+// Each running session announces itself in `<root>/running/<address>.json`:
+// its address, Pi session name, working directory, process id, idle or busy,
+// the address it waits on, and when the record last changed. A record whose
+// process is gone counts as not running, and the reader that finds it deletes
+// it. The root is the mail root, so every agent directory sees every session.
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { isAddress, mailRoot } from "./store.ts";
+
+export type State = "idle" | "busy";
+
+export type RunningRecord = {
+	address: string;
+	/** The Pi session name; absent when none is set. */
+	name?: string;
+	cwd: string;
+	pid: number;
+	state: State;
+	/** The address this session's pending ask waits on; empty when none. */
+	waitingOn: string;
+	/** When the record last changed, as an ISO timestamp. */
+	updated: string;
+};
+
+/** How many leading characters of a session id name it in lists and errors. */
+export const SHORT_ID = 8;
+
+export const shortId = (address: string) => address.slice(0, SHORT_ID);
+
+/** A record's display label: its session name, or its short id when it has none. */
+export const label = (record: Pick<RunningRecord, "address" | "name">) => record.name ?? shortId(record.address);
+
+const runningDir = () => join(mailRoot(), "running");
+
+const recordPath = (address: string) => {
+	if (!isAddress(address)) throw new Error(`invalid mailbox address: ${JSON.stringify(address)}`);
+	return join(runningDir(), `${address}.json`);
+};
+
+/** Write `record` owner-only, through a temporary file so a reader never sees half of it. */
+export function writeRecord(record: RunningRecord): void {
+	mkdirSync(runningDir(), { recursive: true, mode: 0o700 });
+	const path = recordPath(record.address);
+	const tmp = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+	renameSync(tmp, path);
+}
+
+/** Remove `address`'s record, unless another process has since taken it over. */
+export function removeRecord(address: string): void {
+	const path = recordPath(address);
+	const current = readRecord(path);
+	if (current !== undefined && current.pid !== process.pid) return;
+	rmSync(path, { force: true });
+}
+
+/** Whether a process with this id exists; one we may not signal still exists. */
+function alive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+function readRecord(path: string): RunningRecord | undefined {
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8")) as Partial<RunningRecord>;
+		if (!isAddress(value.address)) return undefined;
+		if (typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid <= 0) return undefined;
+		if (typeof value.cwd !== "string") return undefined;
+		return {
+			address: value.address,
+			...(typeof value.name === "string" && value.name !== "" ? { name: value.name } : {}),
+			cwd: value.cwd,
+			pid: value.pid,
+			state: value.state === "busy" ? "busy" : "idle",
+			waitingOn: typeof value.waitingOn === "string" ? value.waitingOn : "",
+			updated: typeof value.updated === "string" ? value.updated : "",
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/** Every running session's record, sorted by label; records of dead processes are deleted. */
+export function listRunning(): RunningRecord[] {
+	let names: string[];
+	try {
+		names = readdirSync(runningDir()).filter((name) => name.endsWith(".json"));
+	} catch {
+		return [];
+	}
+	const out: RunningRecord[] = [];
+	for (const name of names) {
+		const path = join(runningDir(), name);
+		const record = readRecord(path);
+		if (record === undefined || `${record.address}.json` !== name) continue; // not ours to judge or delete
+		if (!alive(record.pid)) {
+			rmSync(path, { force: true });
+			continue;
+		}
+		out.push(record);
+	}
+	return out.sort((a, b) => label(a).localeCompare(label(b)) || a.address.localeCompare(b.address));
+}
+
+/** A Pi session id as Pi writes it: a UUID. */
+const FULL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const candidates = (records: readonly RunningRecord[]) =>
+	records.map((record) => `${label(record)} (${record.address})`).join(", ");
+
+/**
+ * Resolve a `to` typed by a person or a model to an address.
+ *
+ * A running session's address, or any full session id, resolves as given, so a
+ * closed session is still reached by its full id. Otherwise `to` matches
+ * running sessions by exact name, then by an id prefix of at least 8
+ * characters. Several matches, no match, and `me` itself are refused with an
+ * error that says why.
+ */
+export function resolveTo(to: string, me: string): string {
+	const wanted = to.trim();
+	if (wanted === "") throw new Error("no recipient given");
+	const running = listRunning();
+	let address: string | undefined;
+	if (running.some((record) => record.address === wanted) || (FULL_ID.test(wanted) && isAddress(wanted))) {
+		address = wanted;
+	} else {
+		const byName = running.filter((record) => record.name === wanted);
+		const byPrefix =
+			byName.length === 0 && wanted.length >= SHORT_ID
+				? running.filter((record) => record.address.startsWith(wanted))
+				: [];
+		const matches = byName.length > 0 ? byName : byPrefix;
+		if (matches.length > 1)
+			throw new Error(
+				`${JSON.stringify(wanted)} matches several running sessions: ${candidates(matches)}; use a full id`,
+			);
+		if (matches.length === 0)
+			throw new Error(
+				`no running session is named ${JSON.stringify(wanted)} or has an id starting with it${
+					wanted.length < SHORT_ID ? ` (an id prefix needs at least ${SHORT_ID} characters)` : ""
+				}; a closed session is reached by its full id`,
+			);
+		address = matches[0].address;
+	}
+	if (address === me) throw new Error("that is this session; a session cannot send mail to itself");
+	return address;
+}

package/store.ts

@@ -0,0 +1,222 @@
+// The mailbox's directories and envelopes on disk. Internal to `pi-session-mail`:
+// tests reach it only through the extension's registration function.
+//
+// Layout: <root>/<address>/{tmp,new,cur,sent}/<ms>-<id>.json, where the root
+// is `$XDG_STATE_HOME/pi-session-mail/` (or `~/.local/state/pi-session-mail/`)
+// and is shared by every Pi agent directory on this machine.
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+/** What an envelope is: answered at settle, waited on, plain, or an answer. */
+export type Kind = "request" | "ask" | "message" | "reply";
+const KINDS: readonly Kind[] = ["request", "ask", "message", "reply"];
+
+export type Envelope = {
+	id: string;
+	from: string;
+	to: string;
+	kind: Kind;
+	/** How many times this chain of mail has woken or steered a session with no person typing. */
+	hops: number;
+	/** Request ids this envelope answers; empty for a request. */
+	in_reply_to: string[];
+	status: string;
+	ts: string;
+	body: string;
+};
+
+type Box = "tmp" | "new" | "cur" | "sent";
+const BOXES: Box[] = ["tmp", "new", "cur", "sent"];
+
+const ADDRESS = /^[A-Za-z0-9_-]+$/;
+
+/** An address is a single safe path segment: letters, digits, `-` and `_`. */
+export const isAddress = (value: unknown): value is string => typeof value === "string" && ADDRESS.test(value);
+
+/**
+ * The mail root, read at call time so a changed `XDG_STATE_HOME` is honoured.
+ * A relative `XDG_STATE_HOME` is ignored, as the XDG spec requires.
+ */
+export function mailRoot(): string {
+	const state = process.env.XDG_STATE_HOME;
+	const base = state !== undefined && isAbsolute(state) ? state : join(homedir(), ".local", "state");
+	return join(base, "pi-session-mail");
+}
+
+export function boxPath(address: string, box: Box): string {
+	if (!isAddress(address)) throw new Error(`invalid mailbox address: ${JSON.stringify(address)}`);
+	return join(mailRoot(), address, box);
+}
+
+/** Create the root and `address`'s boxes; every directory made here is owner-only. */
+export function ensureBoxes(address: string): void {
+	mkdirSync(mailRoot(), { recursive: true, mode: 0o700 });
+	for (const box of BOXES) mkdirSync(boxPath(address, box), { recursive: true, mode: 0o700 });
+}
+
+// Names sort in send order: a strictly increasing millisecond stamp in this
+// process, zero-padded, then the id.
+let lastMs = 0;
+function stamp(): number {
+	lastMs = Math.max(Date.now(), lastMs + 1);
+	return lastMs;
+}
+
+const fileName = (ms: number, id: string) => `${String(ms).padStart(15, "0")}-${id}.json`;
+
+/** How `send` writes an envelope. A reply names what it answers in `inReplyTo`. */
+export type SendOptions = { kind: Kind; hops: number; inReplyTo?: string[]; status?: string };
+
+/**
+ * Write an envelope to `to`'s inbox: into its `tmp/`, then renamed into its
+ * `new/`. A request is also copied into the sender's `sent/`. Synchronous,
+ * so a `pi.events` caller sees the result as soon as `emit` returns.
+ * A reply's `status` is `done` unless given; any other kind's is empty.
+ */
+export function send(from: string, to: string, body: string, options: SendOptions): Envelope {
+	if (!isAddress(from)) throw new Error(`invalid sender address: ${JSON.stringify(from)}`);
+	if (!isAddress(to)) throw new Error(`invalid address: ${JSON.stringify(to)} (expected a session id)`);
+	if (!KINDS.includes(options.kind)) throw new Error(`invalid kind: ${JSON.stringify(options.kind)}`);
+	if (!isHops(options.hops)) throw new Error(`invalid hops: ${JSON.stringify(options.hops)}`);
+	const inReplyTo = options.inReplyTo ?? [];
+	const ms = stamp();
+	const envelope: Envelope = {
+		id: randomUUID(),
+		from,
+		to,
+		kind: options.kind,
+		hops: options.hops,
+		in_reply_to: inReplyTo,
+		status: options.kind === "reply" ? (options.status ?? "done") : "",
+		ts: new Date(ms).toISOString(),
+		body,
+	};
+	const name = fileName(ms, envelope.id);
+	const text = `${JSON.stringify(envelope, null, 2)}\n`;
+	ensureBoxes(to);
+	const tmp = join(boxPath(to, "tmp"), name);
+	writeFileSync(tmp, text);
+	renameSync(tmp, join(boxPath(to, "new"), name));
+	if (options.kind !== "reply") {
+		ensureBoxes(from);
+		writeFileSync(join(boxPath(from, "sent"), name), text);
+	}
+	return envelope;
+}
+
+/** Regular `.json` files waiting in `new/`, in send order. */
+export function listNew(address: string): string[] {
+	const dir = boxPath(address, "new");
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return names
+		.filter((name) => name.endsWith(".json"))
+		.filter((name) => {
+			try {
+				return lstatSync(join(dir, name)).isFile();
+			} catch {
+				return false;
+			}
+		})
+		.sort();
+}
+
+/** Claim a file by renaming it from `new/` into `cur/`; null when another scanner got it first. */
+export function claim(address: string, name: string): string | null {
+	const target = join(boxPath(address, "cur"), name);
+	try {
+		renameSync(join(boxPath(address, "new"), name), target);
+		return target;
+	} catch {
+		return null;
+	}
+}
+
+/** A request's copy in its sender's `sent/`, with its path. */
+export type SentCopy = { envelope: Envelope; path: string };
+
+const isHops = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 0;
+
+/**
+ * Parse an envelope file; throws when it is not a well-formed envelope from a
+ * valid address. An envelope written before `kind` and `hops` existed is read
+ * as a reply when it answers something and as a request otherwise, with hops 0.
+ */
+export function readEnvelope(path: string): Envelope {
+	const value = JSON.parse(readFileSync(path, "utf8")) as Partial<Envelope>;
+	if (typeof value !== "object" || value === null) throw new Error("not an object");
+	if (typeof value.id !== "string" || value.id === "") throw new Error("missing id");
+	if (!isAddress(value.from)) throw new Error(`invalid from address ${JSON.stringify(value.from)}`);
+	if (!Array.isArray(value.in_reply_to) || !value.in_reply_to.every((id) => typeof id === "string"))
+		throw new Error("in_reply_to is not a list of ids");
+	if (typeof value.body !== "string") throw new Error("missing body");
+	if (value.kind === undefined) value.kind = value.in_reply_to.length > 0 ? "reply" : "request";
+	else if (!KINDS.includes(value.kind)) throw new Error(`invalid kind ${JSON.stringify(value.kind)}`);
+	if (value.hops === undefined) value.hops = 0;
+	else if (!isHops(value.hops)) throw new Error(`invalid hops ${JSON.stringify(value.hops)}`);
+	return value as Envelope;
+}
+
+/**
+ * Find this session's `sent/` copy of the request with envelope id `id`;
+ * undefined when no readable copy exists. Only names matching the id are read,
+ * because `sent/` is never pruned and grows with the address's age.
+ */
+export function findSent(address: string, id: string): SentCopy | undefined {
+	const dir = boxPath(address, "sent");
+	let names: string[];
+	try {
+		names = readdirSync(dir).filter((name) => name.endsWith(`-${id}.json`));
+	} catch {
+		return undefined;
+	}
+	for (const name of names) {
+		const path = join(dir, name);
+		try {
+			const envelope = readEnvelope(path);
+			if (envelope.id === id) return { envelope, path };
+		} catch {
+			// an unreadable copy is no copy
+		}
+	}
+	return undefined;
+}
+
+function envelopesIn(address: string, box: Box): Partial<Envelope>[] {
+	const dir = boxPath(address, box);
+	let names: string[];
+	try {
+		names = readdirSync(dir).filter((name) => name.endsWith(".json"));
+	} catch {
+		return [];
+	}
+	const out: Partial<Envelope>[] = [];
+	for (const name of names) {
+		try {
+			out.push(JSON.parse(readFileSync(join(dir, name), "utf8")));
+		} catch {
+			out.push({});
+		}
+	}
+	return out;
+}
+
+/**
+ * Counts derived from disk: files still in `new/`, envelopes in `cur/`, and
+ * requests (not messages) in `sent/` that no envelope in `cur/` answers.
+ */
+export function diskCounts(address: string): { unclaimed: number; read: number; awaiting: number } {
+	const cur = envelopesIn(address, "cur");
+	const answered = new Set(cur.flatMap((e) => (Array.isArray(e.in_reply_to) ? e.in_reply_to : [])));
+	// A message expects no answer, so it never counts as awaiting one.
+	const awaiting = envelopesIn(address, "sent").filter(
+		(e) => typeof e.id === "string" && e.kind !== "message" && !answered.has(e.id),
+	).length;
+	return { unclaimed: listNew(address).length, read: cur.length, awaiting };
+}