pi-session-mail 0.1.0 → 0.2.1

package/{tools.ts → src/tools.ts}

@@ -1,12 +1,15 @@
 // The model-facing tools of `pi-session-mail`. Internal to the package: tests reach
-// them only through the extension's registration function.
+// them only through the extension's registration function (`settle.ts` is the
+// one module tested directly).
 //
 // `session_mail_list` reports every running Pi session on this machine, in
 // every agent directory, and marks the calling one. `session_mail_send` leaves a plain
 // message, which wakes or steers its recipient and expects no answer.
 // `session_mail_ask` leaves an ask and waits, one at a time, for the answer,
 // which comes back as its result rather than as a message.
-// `session_mail_reply` answers an ask this session received, mid-run. Mail a
+// `session_mail_reply` answers an ask this session received, mid-run; the asks
+// this session owes, and the kind of every envelope it has received, are kept
+// here for it. Mail a
 // tool sends carries the turn's hop count and is refused once the count
 // reaches `hopLimit` from `<agent dir>/session-mail.json`.
 import { readFileSync } from "node:fs";
@@ -15,6 +18,7 @@ import { join } from "node:path";
 import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { DEFAULT_HOP_LIMIT, DEFAULT_PRUNE_AFTER_DAYS, parseConfig } from "./config.ts";
 import { label, listRunning, type RunningRecord, resolveTo } from "./running.ts";
 import { type Envelope, send } from "./store.ts";
 
@@ -28,12 +32,18 @@ export type ToolHooks = {
 	configProblem: (message: string) => void;
 	/** The address this session's ask now waits on, or "" when it waits on none; written to its running record. */
 	waitingOn: (address: string) => void;
-	/** Answer the open ask `id` this session received with `body` at once; throws, sending nothing, when it cannot. */
-	reply: (id: string, body: string) => Envelope;
 };
 
-/** What the extension needs from the tools: the ask that is waiting. */
+/** What the extension needs from the tools: the ask that is waiting, and the asks owed. */
 export type Tools = {
+	/** Remember the kind of a claimed envelope, so a refused reply can say why; never forgotten. */
+	recordKind: (envelope: Envelope) => void;
+	/** Arm an answer for an ask: its sender is owed one. Any other kind is ignored. */
+	armAsk: (envelope: Envelope) => void;
+	/** The session's mailbox address, or undefined when it has none (before a valid start, after shutdown); owed asks are dropped. */
+	setAddress: (address: string | undefined) => void;
+	/** The ask ids still owed an answer, by sender; they are no longer owed afterwards. */
+	takeOwedAsks: () => Map<string, string[]>;
 	/** Hand a reply to the waiting ask it answers; false when it answers none, so it is delivered as usual. */
 	takeAnswer: (envelope: Envelope) => boolean;
 	/** Stop waiting, as when the session shuts down. */
@@ -71,53 +81,37 @@ function askText(ask: Envelope, target: string, outcome: AskOutcome): string {
 	}
 }
 
-/** The hop limit when `session-mail.json` is missing or broken (spec Q14). */
-const DEFAULT_HOP_LIMIT = 5;
+/** Why `session_mail_reply` refuses mail that is not an ask, by the kind of that mail. */
+const NOT_AN_ASK: Record<Exclude<Envelope["kind"], "ask">, string> = {
+	request: "A request is answered automatically when this run settles.",
+	message: "A message expects no answer; session_mail_send sends one if it is wanted.",
+	reply: "A reply is never answered.",
+};
 
 /**
- * `hopLimit` from `<agent dir>/session-mail.json`, read at each send. A
- * missing file, or one without `hopLimit`, means the default; an unreadable
- * or invalid one means the default and a problem report.
+ * The settings from `<agent dir>/session-mail.json`, read at each call; each
+ * problem goes to `onProblem`, which the extension shows once per session.
  */
-function hopLimit(hooks: ToolHooks): number {
+export function readSettings(onProblem: (message: string) => void): { hopLimit: number; pruneAfterDays: number } {
 	const path = join(getAgentDir(), "session-mail.json");
-	let text: string;
+	let text: string | undefined;
 	try {
 		text = readFileSync(path, "utf8");
 	} catch (err) {
 		if ((err as NodeJS.ErrnoException).code !== "ENOENT")
-			hooks.configProblem(
-				`could not read ${path} (${(err as Error).message}); using the hop limit ${DEFAULT_HOP_LIMIT}`,
+			onProblem(
+				`could not read ${path} (${(err as Error).message}); using the hop limit ${DEFAULT_HOP_LIMIT} and pruning after ${DEFAULT_PRUNE_AFTER_DAYS} days`,
 			);
-		return DEFAULT_HOP_LIMIT;
-	}
-	let config: unknown;
-	try {
-		config = JSON.parse(text);
-	} catch (err) {
-		hooks.configProblem(
-			`${path} is not valid JSON (${(err as Error).message}); using the hop limit ${DEFAULT_HOP_LIMIT}`,
-		);
-		return DEFAULT_HOP_LIMIT;
-	}
-	if (typeof config !== "object" || config === null || Array.isArray(config)) {
-		hooks.configProblem(`${path} is not a JSON object; using the hop limit ${DEFAULT_HOP_LIMIT}`);
-		return DEFAULT_HOP_LIMIT;
+		text = undefined;
 	}
-	const limit = (config as { hopLimit?: unknown }).hopLimit;
-	if (limit === undefined) return DEFAULT_HOP_LIMIT;
-	if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1) {
-		hooks.configProblem(
-			`hopLimit in ${path} must be a positive integer, not ${JSON.stringify(limit)}; using ${DEFAULT_HOP_LIMIT}`,
-		);
-		return DEFAULT_HOP_LIMIT;
-	}
-	return limit;
+	const { problems, ...settings } = parseConfig(text, path);
+	for (const problem of problems) onProblem(problem);
+	return settings;
 }
 
 /** Refuse, before anything is written, once the turn's hop count has reached the limit. */
 function checkHops(hops: number, hooks: ToolHooks): void {
-	const limit = hopLimit(hooks);
+	const limit = readSettings(hooks.configProblem).hopLimit;
 	if (hops < limit) return;
 	throw new Error(
 		`nothing was sent: this turn is ${hops} hops into a chain of sessions waking each other with nobody typing, and the hop limit of ${limit} is reached. A person typing in either session starts the count again.`,
@@ -144,6 +138,31 @@ function waitLabel(address: string, byAddress: ReadonlyMap<string, RunningRecord
 export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 	/** The one ask of this session that is waiting for its answer (spec Q20). */
 	let waiting: WaitingAsk | undefined;
+	/** The kind of each envelope this session has claimed, by id, so a reply can say why it is refused. */
+	const receivedKinds = new Map<string, Envelope["kind"]>();
+	/** Ask ids awaiting this session's answer, keyed by sender; answered apart from requests. */
+	let owedAsks = new Map<string, string[]>();
+	/** This session's address as the extension last set it; undefined when it has none. */
+	let address: string | undefined;
+
+	/** Answer the open ask `id` with `body` at once; throws, sending nothing, when it cannot. */
+	function reply(id: string, body: string): Envelope {
+		const me = address;
+		if (me === undefined) throw new Error("this session has no mailbox address; nothing was sent");
+		const kind = receivedKinds.get(id);
+		if (kind === undefined)
+			throw new Error(`no mail with id ${JSON.stringify(id)} reached this session; nothing was sent`);
+		if (kind !== "ask") throw new Error(`${id} is a ${kind}, not an ask; nothing was sent. ${NOT_AN_ASK[kind]}`);
+		const from = [...owedAsks].find(([, ids]) => ids.includes(id))?.[0];
+		// An answered ask, by this tool or at settle, is no longer owed.
+		if (from === undefined) throw new Error(`ask ${id} is already answered; nothing was sent`);
+		// Answers carry the turn's count and are never refused by the hop limit.
+		const answer = send(me, from, body, { kind: "reply", hops: hooks.hops(), inReplyTo: [id], status: "done" });
+		const rest = (owedAsks.get(from) ?? []).filter((owedId) => owedId !== id);
+		if (rest.length > 0) owedAsks.set(from, rest);
+		else owedAsks.delete(from);
+		return answer;
+	}
 
 	pi.registerTool({
 		name: "session_mail_list",
@@ -277,11 +296,17 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 			ask: Type.String({ description: "The ask id, as given in the ask's label." }),
 			message: Type.String({ description: "The answer." }),
 		}),
-		async execute(_toolCallId: string, params: { ask: string; message: string }) {
+		async execute(
+			_toolCallId: string,
+			params: { ask: string; message: string },
+			_signal: unknown,
+			_onUpdate: unknown,
+			_ctx: ExtensionContext,
+		) {
 			const id = typeof params.ask === "string" ? params.ask.trim() : "";
 			const body = typeof params.message === "string" ? params.message.trim() : "";
 			if (body === "") throw new Error("the answer is empty; nothing was sent");
-			const answer = hooks.reply(id, body);
+			const answer = reply(id, body);
 			hooks.sent();
 			const sender = listRunning().find((record) => record.address === answer.to);
 			const who = sender === undefined ? answer.to : `${label(sender)} (${answer.to})`;
@@ -294,6 +319,21 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 	});
 
 	return {
+		recordKind(envelope) {
+			receivedKinds.set(envelope.id, envelope.kind);
+		},
+		armAsk(envelope) {
+			if (envelope.kind === "ask") owedAsks.set(envelope.from, [...(owedAsks.get(envelope.from) ?? []), envelope.id]);
+		},
+		setAddress(next) {
+			address = next;
+			owedAsks = new Map();
+		},
+		takeOwedAsks() {
+			const taken = owedAsks;
+			owedAsks = new Map();
+			return taken;
+		},
 		takeAnswer(envelope) {
 			if (waiting === undefined || envelope.kind !== "reply" || !envelope.in_reply_to.includes(waiting.id))
 				return false;

package/store.ts

@@ -1,222 +0,0 @@
-// 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 };
-}