pi-session-mail 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-23
+
+### Changed
+
+- `session_mail_ask` no longer holds the turn of a session a person is
+  watching (a TUI without `PI_UNATTENDED=1`): it returns at once with outcome
+  `background`, and the answer arrives as a message that starts a turn, so the
+  user can keep talking to the asker. Unattended sessions, such as delegates,
+  still wait for the answer. The label on an answer to an ask that is not
+  waiting now reads "is not waiting for it" instead of "has stopped waiting",
+  and the test pinning it changed with it.
+
 ## [0.4.0] - 2026-10-20
 
 ### Added
@@ -176,7 +188,8 @@ 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.4.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.5.0...HEAD
+[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
 [0.3.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.1...v0.2.2

package/README.md

@@ -131,7 +131,7 @@ The model gets four tools:
 | Tool | Parameters | What it does |
 | --- | --- | --- |
 | `session_mail_list` | none | Lists every running session, in every agent directory: its name (or short id, the first 8 characters of its id, when it has no name), full id, working directory, idle or busy state and whom it is waiting on, and marks the calling session. |
-| `session_mail_ask` | `to`, `message` | Writes an ask (`kind: "ask"`) and waits for the answer, which is the result: its status and body, labelled as not an answer when the status is `stopped` or `failed`. The wait ends when the answer arrives, after 10 minutes ("no answer yet"), when the target's running record disappears ("stopped running"), or when the user stops the run; `waitingOn` is set while it waits and cleared in every case. Refused at once, writing nothing, when another ask of this session is waiting, when the target is not running, when the target is waiting on this session, at the [hop limit](#hop-limit), and when `to` does not resolve, is ambiguous or is this session. |
+| `session_mail_ask` | `to`, `message` | Writes an ask (`kind: "ask"`). In a TUI session without `PI_UNATTENDED=1` it returns at once with outcome `background`, sets no `waitingOn`, and the answer arrives as a message. Everywhere else (print, JSON and RPC modes, and a TUI marked unattended, such as a pi-squire delegate) it waits for the answer, which is the result: its status and body, labelled as not an answer when the status is `stopped` or `failed`. The wait ends when the answer arrives, after 10 minutes ("no answer yet"), when the target's running record disappears ("stopped running"), or when the user stops the run; `waitingOn` is set while it waits and cleared in every case. Refused at once, writing nothing, when another ask of this session is waiting, when the target is not running, when the target is waiting on this session, at the [hop limit](#hop-limit), and when `to` does not resolve, is ambiguous or is this session. |
 | `session_mail_reply` | `ask`, `message` | Answers one open ask this session received, at once, with status `done` and the turn's hop count, without ending the run; the asker's `session_mail_ask` returns with it. The answer at settle then leaves that ask out, while the sender's other requests and asks are still answered. Refused, sending nothing, for an ask already answered (by this tool or at settle), for a request (answered at settle), a message or a reply, for an id that never reached this session, and for an empty text. |
 | `session_mail_send` | `to`, `message` | Writes a message (`kind: "message"`) and returns its id. To a running session it is delivered at once; to a closed session, by full id, it waits in that session's inbox and the result says so. Refused when `to` does not resolve, is ambiguous or is this session, when the text is empty, and at the [hop limit](#hop-limit). |
 
@@ -168,9 +168,12 @@ listener takes it over, as pi-squire's `delegate` does for its tasks.
 
 A reply to this session's waiting ask goes to the waiting tool call as its
 result: it is neither injected nor emitted on `message:inbound`. A reply to an
-ask that is no longer waiting (it timed out, the user stopped it, or the
-session restarted) is delivered like a message: it starts a turn, and its label
-says the ask stopped waiting.
+ask that is not waiting (a background ask, or one that timed out, that the
+user stopped, or whose session restarted) is delivered like a message: it
+starts a turn, and its label says the ask is not waiting for it. An
+unattended session waits rather than asking in the background because ending
+its turn ends its work: a delegate's settle is its result, and print mode
+exits.
 
 Every injected message opens with a neutral label: `[mailbox] From <name>
 (<full id>, working in <cwd>), another Pi session on this machine.` The short

package/package.json

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

package/src/index.ts

@@ -147,7 +147,7 @@ function inboundText(
 		header.push(
 			`It is waiting for your answer to its ask ${id}. Answer with session_mail_reply (ask ${id}); otherwise this run's last message is sent as the answer.`,
 		);
-	if (lateAnswer) header.push("It answers an ask of yours that has stopped waiting, so it arrives as a message.");
+	if (lateAnswer) header.push("It answers an ask of yours that is not waiting for it, so it arrives as a message.");
 	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)
@@ -388,7 +388,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		// The answer to a waiting ask is that tool call's result, and nothing else.
 		if (tools?.takeAnswer(envelope)) return;
 		const { requests, quotes } = requestQuotes(me, envelope.in_reply_to);
-		// An answer to an ask that stopped waiting is delivered like a message.
+		// An answer to an ask that is not waiting (a background ask, or one that stopped) is delivered like a message.
 		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");

package/src/tools.ts

@@ -5,8 +5,11 @@
 // `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_ask` leaves an ask. In a session a person is watching it
+// returns at once and the answer arrives as a message; elsewhere it waits, one
+// at a time, for the answer, which comes back as its result. An unattended
+// session must wait because ending its turn ends its work: a delegate's settle
+// is its result, and print mode exits.
 // `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
@@ -53,8 +56,14 @@ const ASK_TIMEOUT_MS = 10 * 60 * 1000;
 /** How often a waiting ask checks that its target still runs. */
 const TARGET_CHECK_MS = 1000;
 
-/** How a waiting ask ended. */
+/** Whether a person is watching this session, so an ask need not hold its turn; `PI_UNATTENDED=1` marks a TUI nobody watches. */
+function attended(ctx: ExtensionContext): boolean {
+	return ctx.mode === "tui" && process.env.PI_UNATTENDED !== "1";
+}
+
+/** How an ask's tool call ended: at once in the background, or how its wait ended. */
 type AskOutcome =
+	| { outcome: "background" }
 	| { outcome: "answered"; status: string; body: string }
 	| { outcome: "timed-out" }
 	| { outcome: "stopped-running" }
@@ -66,6 +75,8 @@ type WaitingAsk = { id: string; to: string; finish: (outcome: AskOutcome) => voi
 function askText(ask: Envelope, target: string, outcome: AskOutcome): string {
 	const later = "A later answer arrives as a message.";
 	switch (outcome.outcome) {
+		case "background":
+			return `Sent ask ${ask.id} to ${target}. This session is not waiting: the answer arrives as a message and starts a turn on its own, so go on with other work or end your turn.`;
 		case "answered":
 			return outcome.status === "done"
 				? `${target} answered your ask ${ask.id}:\n\n${outcome.body}`
@@ -166,6 +177,7 @@ const AskResult = Type.Union([
 	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({
@@ -292,14 +304,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 and wait for its answer, which comes back as this tool's result. The answer is the other session's final message when its run settles, or an earlier reply it sends. The wait ends after 10 minutes, when the other session stops running, or when the user stops it; a later answer then arrives as a message. Only one ask waits at a time, and a session that is waiting on this one cannot be asked. `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 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.",
 		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.",
 			}),
 			message: Type.String({
-				description:
-					"The question. The recipient sees it labelled as coming from this session, with this session waiting.",
+				description: "The question. The recipient sees it labelled as coming from this session.",
 			}),
 		}),
 		outputSchema: AskResult,
@@ -332,26 +343,28 @@ export function registerTools(pi: ExtensionAPI, hooks: ToolHooks): Tools {
 			const hops = hooks.hops();
 			checkHops(hops, hooks);
 			const ask = send(me, to, body, { kind: "ask", hops });
-			const outcome = await new Promise<AskOutcome>((resolve) => {
-				const finish = (result: AskOutcome) => {
-					if (waiting?.id !== ask.id) return;
-					waiting = undefined;
-					clearTimeout(timer);
-					clearInterval(check);
-					signal?.removeEventListener("abort", onAbort);
-					hooks.waitingOn("");
-					resolve(result);
-				};
-				const onAbort = () => finish({ outcome: "stopped-by-user" });
-				const timer = setTimeout(() => finish({ outcome: "timed-out" }), ASK_TIMEOUT_MS);
-				const check = setInterval(() => {
-					if (!listRunning().some((r) => r.address === to)) finish({ outcome: "stopped-running" });
-				}, TARGET_CHECK_MS);
-				waiting = { id: ask.id, to, finish };
-				hooks.waitingOn(to);
-				if (signal?.aborted) onAbort();
-				else signal?.addEventListener("abort", onAbort, { once: true });
-			});
+			const outcome: AskOutcome = attended(ctx)
+				? { outcome: "background" }
+				: await new Promise<AskOutcome>((resolve) => {
+						const finish = (result: AskOutcome) => {
+							if (waiting?.id !== ask.id) return;
+							waiting = undefined;
+							clearTimeout(timer);
+							clearInterval(check);
+							signal?.removeEventListener("abort", onAbort);
+							hooks.waitingOn("");
+							resolve(result);
+						};
+						const onAbort = () => finish({ outcome: "stopped-by-user" });
+						const timer = setTimeout(() => finish({ outcome: "timed-out" }), ASK_TIMEOUT_MS);
+						const check = setInterval(() => {
+							if (!listRunning().some((r) => r.address === to)) finish({ outcome: "stopped-running" });
+						}, TARGET_CHECK_MS);
+						waiting = { id: ask.id, to, finish };
+						hooks.waitingOn(to);
+						if (signal?.aborted) onAbort();
+						else signal?.addEventListener("abort", onAbort, { once: true });
+					});
 			const result = { id: ask.id, to, ...outcome };
 			return toolResult(askText(ask, target, outcome), result, result);
 		},