pi-session-mail 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -6,6 +6,23 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-11-01
+
+### Changed
+
+- Shorter declarations for the four session-mail tools reduce model context use.
+  Delivery, ask waits, reply rules, result fields, and errors are unchanged.
+
+## [0.6.1] - 2026-10-31
+
+### Changed
+
+- The label on the answer to an ask now calls it an ask: "It is a reply to your
+  ask …" and "[mailbox] Your ask …, quoted from …" (and "Ask cut at 2 KiB").
+  It said "request" before, which now names a different kind of mail. A reply
+  to a request, or to an id with no copy in `sent/`, keeps the request wording.
+  The test that pinned the old wording for an ask's answer is updated.
+
 ## [0.6.0] - 2026-10-31
 
 ### Added
@@ -240,7 +257,9 @@ author's dotfiles; the changes below are against that copy.
 - CI on Node 22.19 and 24: lint, typecheck, tests, and a check of the
   published file list.
 
-[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/gvanderclay/pi-session-mail/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/gvanderclay/pi-session-mail/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.3.0...v0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-session-mail",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "A file mailbox between Pi sessions on the same machine",
 	"keywords": [
 		"pi-package",

package/src/index.ts

@@ -75,14 +75,15 @@ function cap(text: string, max: number): string | undefined {
  */
 const plain = (text: string): string => text.replace(/[\p{Cc}\u2028\u2029]/gu, " ");
 
-/** A reply quotes each request it answers: the id, the copy's path, then the capped body. */
+/** A reply quotes each request or ask it answers: the id, the copy's path, then the capped body. */
 function quoteRequest(request: SentCopy): string {
+	const ask = request.envelope.kind === "ask";
 	const cut = cap(request.envelope.body, QUOTE_CAP);
 	const body =
 		cut === undefined
 			? request.envelope.body
-			: `${cut}\n[mailbox] Request cut at 2 KiB; the full copy is ${plain(request.path)}`;
-	return `[mailbox] Your request ${plain(request.envelope.id)}, quoted from ${plain(request.path)}:\n${body
+			: `${cut}\n[mailbox] ${ask ? "Ask" : "Request"} cut at 2 KiB; the full copy is ${plain(request.path)}`;
+	return `[mailbox] Your ${ask ? "ask" : "request"} ${plain(request.envelope.id)}, quoted from ${plain(request.path)}:\n${body
 		.split("\n")
 		.map((line) => `> ${line}`)
 		.join("\n")}`;
@@ -136,10 +137,10 @@ function inboundText(
 	envelope: Envelope,
 	path: string,
 	quotes: readonly string[],
-	opts: { lateAnswer: boolean; byUser: boolean },
+	opts: { lateAnswer: boolean; byUser: boolean; answersAsks: boolean },
 	senderRecord: RunningRecord | undefined,
 ): string {
-	const { lateAnswer, byUser } = opts;
+	const { lateAnswer, byUser, answersAsks } = opts;
 	const sender = senderLine(envelope.from, senderRecord);
 	const id = plain(envelope.id);
 	const replyIds = envelope.in_reply_to.map(plain);
@@ -152,7 +153,9 @@ function inboundText(
 	if (envelope.kind === "message")
 		header.push(`It expects no answer; if one is wanted, send it with session_mail_send to ${envelope.from}.`);
 	if (envelope.in_reply_to.length > 0)
-		header.push(`It is a reply to your request${envelope.in_reply_to.length > 1 ? "s" : ""} ${replyIds.join(", ")}.`);
+		header.push(
+			`It is a reply to your ${answersAsks ? "ask" : "request"}${envelope.in_reply_to.length > 1 ? "s" : ""} ${replyIds.join(", ")}.`,
+		);
 	if (byUser)
 		header.push("The user made that request, typing it with /mailbox or through an extension such as delegate.");
 	if (envelope.in_reply_to.length > 0 && envelope.status !== "done")
@@ -395,6 +398,9 @@ export default function mailbox(pi: ExtensionAPI) {
 		const lateAnswer = envelope.kind === "reply" && requests.some((copy) => copy.envelope.kind === "ask");
 		const wakes = envelope.kind !== "reply" || lateAnswer;
 		const byUser = envelope.kind === "reply" && requests.some((copy) => copy.envelope.kind === "request");
+		// The label says "ask" only when every id it answers is a known ask; otherwise "request", as before.
+		const answersAsks =
+			requests.length === envelope.in_reply_to.length && requests.every((copy) => copy.envelope.kind === "ask");
 		// Listeners run synchronously inside emit, so `handled` is final when it returns.
 		const inbound: InboundPayload = { envelope, path, requests, handled: false };
 		pi.events.emit(INBOUND, inbound);
@@ -415,7 +421,7 @@ export default function mailbox(pi: ExtensionAPI) {
 					envelope,
 					path,
 					quotes,
-					{ lateAnswer, byUser },
+					{ lateAnswer, byUser, answersAsks },
 					listRunning().find((r) => r.address === envelope.from),
 				),
 				display: true,

package/src/tools.ts

@@ -126,49 +126,54 @@ const SENDS_MAIL = { readOnlyHint: false, destructiveHint: false, idempotentHint
 const SessionList = Type.Object({
 	sessions: Type.Array(
 		Type.Object({
-			id: Type.String({ description: "The session's full id; pass it as `to`" }),
-			name: Type.Optional(Type.String({ description: "The session name; absent when none is set" })),
+			id: Type.String({ description: "Full session id; usable as `to`" }),
+			name: Type.Optional(Type.String()),
 			cwd: Type.String(),
 			state: Type.Union([Type.Literal("idle"), Type.Literal("busy")]),
 			waitingOn: Type.Optional(
-				Type.String({ description: "The full id of the session this one's ask waits on; absent when none" }),
+				Type.String({ description: "Full session id this session's ask waits on; absent if none" }),
 			),
-			self: Type.Boolean({ description: "True for the calling session" }),
+			self: Type.Boolean({ description: "True for the caller" }),
 		}),
 	),
 });
 
 const SendResult = Type.Object({
-	id: Type.String({ description: "The message's id" }),
-	to: Type.String({ description: "The recipient's full id" }),
-	running: Type.Boolean({ description: "False when the message waits in a closed session's inbox" }),
+	id: Type.String({ description: "Message id" }),
+	to: Type.String({ description: "Recipient's full session id" }),
+	running: Type.Boolean({ description: "False if queued in a closed session's inbox" }),
 });
 
 const asked = {
-	id: Type.String({ description: "The ask's id" }),
-	to: Type.String({ description: "The asked session's full id" }),
+	id: Type.String({ description: "Ask id" }),
+	to: Type.String({ description: "Asked session's full id" }),
 };
 
-/** One variant per {@link AskOutcome}, told apart by `outcome`. */
-const AskResult = Type.Union([
-	Type.Object({
-		...asked,
-		outcome: Type.Literal("answered"),
-		status: Type.String({
-			description: '"done" for an answer; any other status means the run ended otherwise, and body is not an answer',
+const AskResult = Type.Intersect([
+	Type.Object(asked),
+	Type.Union([
+		Type.Object({
+			outcome: Type.Literal("answered"),
+			status: Type.String({
+				description: '"done" means an answer; otherwise the run ended without an answer and body is not one',
+			}),
+			body: Type.String(),
+		}),
+		Type.Object({
+			outcome: Type.Union([
+				Type.Literal("timed-out"),
+				Type.Literal("stopped-running"),
+				Type.Literal("stopped-by-user"),
+				Type.Literal("background"),
+			]),
 		}),
-		body: Type.String(),
-	}),
-	Type.Object({ ...asked, outcome: Type.Literal("timed-out") }),
-	Type.Object({ ...asked, outcome: Type.Literal("stopped-running") }),
-	Type.Object({ ...asked, outcome: Type.Literal("stopped-by-user") }),
-	Type.Object({ ...asked, outcome: Type.Literal("background") }),
+	]),
 ]);
 
 const ReplyResult = Type.Object({
-	id: Type.String({ description: "The reply's id" }),
-	ask: Type.String({ description: "The id of the ask it answers" }),
-	to: Type.String({ description: "The asker's full id" }),
+	id: Type.String({ description: "Reply id" }),
+	ask: Type.String({ description: "Answered ask id" }),
+	to: Type.String({ description: "Asker's full session id" }),
 });
 
 /** One running session as the list shows it. */
@@ -215,7 +220,7 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		name: "session_mail_list",
 		label: "Session mail: list",
 		description:
-			"List the Pi sessions running on this machine, in every agent root: each one's name (or short id when it has none), full id, working directory, idle or busy state, and whom it is waiting on. The calling session is marked. A session is addressed by its name, its full id, or an id prefix of at least 8 characters.",
+			"List running Pi sessions across all agent roots on this machine, with name (short id if unnamed), full id, cwd, idle/busy state and whom each waits on. Marks the caller. Address running sessions by name, full id or 8+ character id prefix.",
 		parameters: Type.Object({}),
 		outputSchema: SessionList,
 		// Listing deletes the records of sessions whose process is gone, which is housekeeping, not a change.
@@ -249,13 +254,13 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		name: "session_mail_send",
 		label: "Session mail: send",
 		description:
-			"Send a message to another Pi session on this machine. A running recipient that is idle starts a turn on it; a busy one reads it at its next gap between tool calls. The message expects no answer and nothing is sent back automatically; the recipient answers, if at all, with its own session_mail_send. `to` is a running session's name, an id prefix of at least 8 characters, or a full session id; a closed session is reached only by its full id, and the message waits in its inbox until it starts. session_mail_list shows who is running.",
+			"Send mail to a Pi session on this machine. An idle recipient starts a turn; a busy one reads it at the next tool-call gap. No answer is expected or automatic; any answer uses session_mail_send. Address running sessions by name, full id or 8+ character id prefix. Closed sessions require a full id; mail queues until they start. Discover running sessions with session_mail_list.",
 		parameters: Type.Object({
 			to: Type.String({
-				description: "The recipient: a running session's name, an id prefix of 8+ characters, or a full session id.",
+				description: "Recipient's name or 8+ character id prefix if running; full session id otherwise.",
 			}),
 			message: Type.String({
-				description: "The message text. The recipient sees it labelled as coming from this session.",
+				description: "Message text, labelled as from this session.",
 			}),
 		}),
 		outputSchema: SendResult,
@@ -286,13 +291,13 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		name: "session_mail_ask",
 		label: "Session mail: ask",
 		description:
-			"Ask another running Pi session on this machine a question. The answer is the other session's final message when its run settles, or an earlier reply it sends. In a session a person is watching, the ask returns at once and the answer arrives later as a message that starts a turn. In an unattended session, such as a delegate, the ask waits up to 10 minutes and the answer comes back as this tool's result. `to` is a running session's name, an id prefix of at least 8 characters, or a full session id; session_mail_list shows who is running. For a note that needs no answer, use session_mail_send.",
+			"Ask a running Pi session on this machine. Its final message at run settle or an early reply answers. In a watched TUI, returns at once; the later answer starts a turn. Unattended sessions, including delegates, wait up to 10 minutes for the answer as this tool's result. Address by name, full id or 8+ character id prefix; discover with session_mail_list. Use session_mail_send for notes needing no answer.",
 		parameters: Type.Object({
 			to: Type.String({
-				description: "The running session to ask: its name, an id prefix of 8+ characters, or its full session id.",
+				description: "Running recipient's name, full id or 8+ character id prefix.",
 			}),
 			message: Type.String({
-				description: "The question. The recipient sees it labelled as coming from this session.",
+				description: "Question, labelled as from this session.",
 			}),
 		}),
 		outputSchema: AskResult,
@@ -354,10 +359,10 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 		name: "session_mail_reply",
 		label: "Session mail: reply",
 		description:
-			"Answer an ask another Pi session sent this session, at once, without ending this run. The asker is waiting, and gets the message as the answer to its ask; the answer this run's last message would otherwise send is then skipped for that ask. `ask` is the ask id its label gives. Each ask is answered once; requests are answered by the extension that consumes them, and messages expect no answer.",
+			"Answer a received ask at once without ending this run. Each ask allows one reply, replacing this run's final-settle answer for it. Use the ask id from its label. Only asks qualify; requests are answered by their consuming extension, and messages expect no answer.",
 		parameters: Type.Object({
-			ask: Type.String({ description: "The ask id, as given in the ask's label." }),
-			message: Type.String({ description: "The answer." }),
+			ask: Type.String({ description: "Ask id from its label." }),
+			message: Type.String({ description: "Answer text." }),
 		}),
 		outputSchema: ReplyResult,
 		// A repeated reply to the same ask is refused and sends nothing.