@junghanacs/entwurf 0.35.0 → 0.36.0

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -3,8 +3,9 @@
  *
  * WHAT THIS IS. The long-running durable app (`@earendil-works/pi-coding-agent`
  * `experimental/durable`, which upstream omits from its npm distribution — Entwurf's package
- * supplies it as a pinned carrier, #130, not as an operator prerequisite) owns its runtime, TUI,
- * models/auth, storage, prompt and recovery. This module is the whole Entwurf side of its contact:
+ * supplies it as a carrier emitted from its owned source, #130/#141, not as an operator
+ * prerequisite) owns its runtime, TUI, models/auth, storage, prompt and recovery. This module is
+ * the whole Entwurf side of its contact:
  *
  *   createPiDurableContact({ bridgeEntry })
  *     .extension          tools-only durable Extension, handed to the overlay's
@@ -49,14 +50,34 @@
  * bridge whose list differs: the callable bridge schema is the truth, the copy only has to agree.
  *
  * RECEIVE (self-fetch, announce-only). When the bootstrap hands `attach` the overlay's
- * `submitToRoot`, the contact arms a doorbell after the bridge is ready: mailbox, then signal,
+ * `submitToRoot` and `onFailed`, the contact arms a doorbell after the bridge is ready: mailbox, then signal,
  * then the watch, then a check that the record and this process's sender marker still name the
  * session, and only then the receiver marker. A fresh `.msg` is stamped `.msg.delivered` and
  * announced to the ROOT conversation as input; the body stays in the mailbox until the model
  * calls `entwurf_inbox_read`, which is the read receipt. The watch and the sender marker share
  * this process's pid, so the #101 owner join applies (`pi-durable-host`). A watch error, a
- * vanished signal, a failed ring, a rejected admission or close retires the doorbell — watch
- * closed, our own marker removed, the reason kept by name — and nothing retries it.
+ * vanished signal, a failed ring, a rejected admission, the session failing (at once, from the
+ * overlay's `onFailed`, not at the next ring — and before `attach` returns when it had already
+ * failed, with no receiver marker left behind) or close retires the doorbell — watch closed, our own
+ * marker removed, the reason kept by name — and nothing retries it.
+ *
+ * WITHDRAW (#140). Each notice is a native `followUp`, placed one per run; a read drains EVERY
+ * unread body. So after a read the notices still queued for that mail would each cost a turn and an
+ * empty read. The contact keeps the native `Submission` handle of each notice it admitted, with the
+ * `.msg` names that notice announced, only while that mail is unread. After every
+ * `entwurf_inbox_read` attempt — whatever its garden id or outcome — it lists its OWN mailbox once
+ * and withdraws, through the native `Submission.abort` and the read's own invocation Context, each
+ * notice none of whose names is still `.msg.delivered`. That per-notice file predicate is the only
+ * authority: no garden-id guard, no requestId lookup, no queue of our own, no rewritten text. A placed
+ * or settled notice answers so and is let go; a withdraw that fails is let go too, named in one
+ * stderr line and on the receiver report, never retried and never retiring the doorbell; a mailbox
+ * that cannot be listed proves nothing absent, so every notice is kept and that is named the same
+ * way. The read's own result or error is returned unchanged — no diagnostic joins it. Ring passes
+ * and reads share one gate: a read waits for an admission in flight (else its drain could beat the
+ * handle it must withdraw), and an arrival during a read is rung once the read lets go. The count
+ * in a notice is its admission-time snapshot. Not covered: notices admitted before a restart (no
+ * handle), mail drained by another process (until this contact's next read), and operator abort,
+ * which natively withdraws queued notices while their mail stays unread.
  *
  * VISIBLE IDENTITY (a static projection). `withGardenIdentity` hands the native TUI a view whose
  * every conversation label carries this citizen's garden id, so the footer the TUI keeps on screen
@@ -79,7 +100,8 @@
  *
  * NOT HERE: crash-safe receive. `entwurf_inbox_read` archives a body before the durable tool
  * result commits, so a crash between the two loses that body to the model; recovery settles the
- * call as interrupted and no doorbell rings again. No resume.
+ * call as interrupted and no doorbell rings again. A drain that fails part-way has archived the
+ * bodies before it (the bridge returns its error), and those too never reach the model. No resume.
  */
 
 import * as fs from "node:fs";
@@ -276,9 +298,14 @@ export interface PiDurableRoots {
 // ---------------------------------------------------------------------------
 // Durable surface, typed NARROWLY and locally — read at pi-durable 1.0.2 @cd32f77 (#129,
 // `harness/types.ts`; historical coordinates, not re-anchored here). The current supply is the
-// carrier `pi/pi-durable/overlay/upstream-pin.json` names (1.1.0 at `abe508e`). `[read 2026-10-08]`
-// v1.0.4 → v1.1.0 `harness/types.ts` adds `models`, `contextRetentionMs` and a `context()` options
-// bag only; none of the shapes typed below moved.
+// carrier emitted from Entwurf's owned source (pi/pi-durable/src, #141) against the 1.2.0 SDK set
+// `pi/pi-durable/overlay/upstream-pin.json` names (origin `abe508e`). `[read 2026-10-13]` at
+// v1.2.0 one shape typed below moved: `ToolExecutionResult.content` is now `output`, beside the new
+// `structuredOutput` (`harness/types.ts`, its CHANGELOG's breaking changes). An omitted `output`
+// gives the model the text a tool retained through `api.output()`; `content` is not read, so a
+// result naming only `content` that retained no output reaches the model as nothing. The contact's
+// tools retain none, so they answer in `output`.
+// The submission draft, its `abort()` answers and the identity `define*` helpers did not move.
 // `defineExtension`/`defineTool` are identity functions (`harness/define.ts:6-17`), so a plain
 // object is the extension.
 // ---------------------------------------------------------------------------
@@ -295,8 +322,9 @@ export interface DurableCallContext {
 	readonly abortSignal?: AbortSignal;
 }
 
+/** `ToolExecutionResult`, narrowed: `output` is what the model reads. */
 export interface DurableToolResult {
-	content: { type: "text"; text: string }[];
+	output: { type: "text"; text: string }[];
 }
 
 export interface DurableTool {
@@ -530,22 +558,32 @@ export interface DurableDoorbellDraft {
 	readonly requestId: string;
 }
 
-/** The part of the native `Submission` handle a doorbell records; admission is not completion. */
+/** What the native `Submission.abort` answers: only a still-queued input is withdrawn. */
+export type DurableWithdrawal = "aborted" | "already_placed" | "settled";
+
+/** The part of the native `Submission` handle a doorbell keeps; admission is not completion. */
 export interface DurableAdmittedSubmission {
 	readonly id: unknown;
+	/** Native `Submission.abort(context)`, handed the read's own invocation Context unchanged. */
+	abort(context: DurableCallContext | undefined): Promise<DurableWithdrawal>;
 }
 
 /** The overlay's `OpenDurableResult.submitToRoot`. */
 export type DurableSubmitToRoot = (draft: DurableDoorbellDraft) => Promise<DurableAdmittedSubmission>;
 
+/** The overlay's `OpenDurableResult.onFailed`: one synchronous call when the session fails and closes itself. */
+export type DurableOnFailed = (listener: () => void) => () => void;
+
 /** What `attach` needs to arm the doorbell. Without it the citizen only sends. */
 export interface DurableRootAdmission {
 	submitToRoot: DurableSubmitToRoot;
+	onFailed: DurableOnFailed;
 }
 
 /** Why an armed doorbell was retired. Nothing re-arms it. */
 export type PiDurableReceiverRetirement =
 	| "closed"
+	| "session-failed"
 	| "watch-error"
 	| "signal-vanished"
 	| "doorbell-failed"
@@ -562,21 +600,40 @@ export interface PiDurableDoorbellAdmission {
 	unread: number;
 }
 
+/**
+ * The LATEST notice withdrawal that failed. `inspection-failed`: the own mailbox could not be listed,
+ * so no notice was judged and every one is kept. `abort-failed`: the native withdraw of the notice
+ * named by `requestId` rejected; that notice is let go, not retried.
+ */
+export interface PiDurableWithdrawalFailure {
+	reason: "inspection-failed" | "abort-failed";
+	requestId?: string;
+	detail: string;
+}
+
 /**
  * The receiver's diagnostic. `admissions` is the LATEST successful admission only — an empty array
  * before the first ring, then exactly one entry, replaced by each later success; a retirement keeps
  * the last one. It is a diagnostic, not a history: it never grows with the host's lifetime, and its
  * length is no count of how often the root was asked (the root's own submissions are that record).
+ * `withdrawalFailure`, present only once a withdrawal failed, is likewise the latest one only.
  */
 export type PiDurableReceiverReport =
 	| { status: "off" }
-	| { status: "armed"; gardenId: string; markerPath: string; admissions: PiDurableDoorbellAdmission[] }
+	| {
+			status: "armed";
+			gardenId: string;
+			markerPath: string;
+			admissions: PiDurableDoorbellAdmission[];
+			withdrawalFailure?: PiDurableWithdrawalFailure;
+	  }
 	| {
 			status: "retired";
 			gardenId: string;
 			reason: PiDurableReceiverRetirement;
 			detail: string;
 			admissions: PiDurableDoorbellAdmission[];
+			withdrawalFailure?: PiDurableWithdrawalFailure;
 	  };
 
 export interface PiDurableAttachment {
@@ -587,7 +644,7 @@ export interface PiDurableAttachment {
 	/** The roots written — and the roots the bridge child was bound to. */
 	roots: PiDurableRoots;
 	bridgePid: number | null;
-	/** The receiver marker this attach published, or null when no root admission was handed in. */
+	/** The receiver marker this attach published; null when no root admission was handed in, or the session had already failed. */
 	receiverMarkerPath: string | null;
 }
 
@@ -639,6 +696,14 @@ interface ArmedDoorbell {
 	markerPath: string;
 	watcher: fs.FSWatcher;
 	submitToRoot: DurableSubmitToRoot;
+	unsubscribeFailed: () => void;
+}
+
+/** One admitted notice: its native handle and the `.msg` names it announced. */
+interface HeldNotice {
+	readonly requestId: string;
+	readonly fresh: readonly string[];
+	readonly submission: DurableAdmittedSubmission;
 }
 
 const TOOL_DESCRIPTIONS: Record<PiDurableToolName, string> = {
@@ -730,9 +795,10 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				throw new Error(`${name} arguments must be an object`);
 			}
 			const client = await waitReady(context?.abortSignal);
-			const result = await client.callTool(name, (args ?? {}) as Record<string, unknown>, context?.abortSignal);
+			const call = () => client.callTool(name, (args ?? {}) as Record<string, unknown>, context?.abortSignal);
+			const result = name === "entwurf_inbox_read" ? await readInbox(call, context) : await call();
 			if (result.isError) throw new Error(result.text || `${name} failed`);
-			return { content: [{ type: "text", text: result.text }] };
+			return { output: [{ type: "text", text: result.text }] };
 		},
 	});
 
@@ -745,8 +811,34 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	let doorbell: ArmedDoorbell | null = null;
 	let report: PiDurableReceiverReport = { status: "off" };
 	const admissions: PiDurableDoorbellAdmission[] = [];
-	let ringing = false;
+	/** The armed mailbox, kept past a retirement so notices admitted before it can still be judged. */
+	let inbox: string | null = null;
+	/** Every admitted notice still owed a withdraw judgement, oldest first. */
+	const notices: HeldNotice[] = [];
+	let withdrawalFailure: PiDurableWithdrawalFailure | undefined;
+	// One gate for ring passes and inbox reads; `pending` is a signal that landed while it was held.
+	let gated = false;
 	let pending = false;
+	const gateWaiters: (() => void)[] = [];
+
+	const enterGate = (): Promise<void> => {
+		if (!gated) {
+			gated = true;
+			return Promise.resolve();
+		}
+		return new Promise<void>((resolve) => gateWaiters.push(resolve));
+	};
+
+	/** Hand the gate to the next waiting read, else open it — and ring once for a signal that landed meanwhile. */
+	const leaveGate = (): void => {
+		const next = gateWaiters.shift();
+		if (next !== undefined) {
+			next();
+			return;
+		}
+		gated = false;
+		if (pending) void ring("signal");
+	};
 
 	/**
 	 * Give the doorbell back: close the watch and remove the marker, in one step, because a
@@ -759,6 +851,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 		const armed = doorbell;
 		if (armed === null) return [];
 		doorbell = null;
+		armed.unsubscribeFailed();
 		const problems: string[] = [];
 		try {
 			armed.watcher.close();
@@ -791,19 +884,19 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	/**
 	 * One contract with the other self-fetch doorbells: a fresh `*.msg` is the trigger, it is
 	 * stamped `.msg.delivered` before the announce, and the announced count is every
-	 * `.msg.delivered`. Events that land while an admission is in flight coalesce into one more
-	 * pass. A failed pass retires the doorbell; it is not retried. Only a fresh `.msg` rings —
-	 * the startup pass included — so a `.msg.delivered` left undrained by an earlier host is not
-	 * announced again on its own; it shows only in the count of the next fresh arrival.
+	 * `.msg.delivered`. Events that land while an admission or an inbox read holds the gate coalesce
+	 * into one more pass. A failed pass retires the doorbell; it is not retried. Only a fresh `.msg`
+	 * rings — the startup pass included — so a `.msg.delivered` left undrained by an earlier host is
+	 * not announced again on its own; it shows only in the count of the next fresh arrival.
 	 */
 	const ring = async (why: PiDurableDoorbellAdmission["why"]): Promise<void> => {
 		const armed = doorbell;
 		if (armed === null) return;
-		if (ringing) {
+		if (gated) {
 			pending = true;
 			return;
 		}
-		ringing = true;
+		gated = true;
 		try {
 			do {
 				pending = false;
@@ -836,11 +929,71 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				}
 				// Latest only: the diagnostic names the LAST success and never grows with the host's lifetime.
 				admissions.splice(0, admissions.length, { why, requestId, submissionId: submission.id, fresh, unread });
+				notices.push({ requestId, fresh, submission });
 			} while (pending && doorbell === armed);
 		} catch (error) {
 			retire("doorbell-failed", describeError(error));
 		} finally {
-			ringing = false;
+			leaveGate();
+		}
+	};
+
+	/**
+	 * One named stderr line per failed withdrawal — stderr ALWAYS, as `entwurf-control` does, since
+	 * nothing in the native app reads the receiver report — and the report keeps the latest one.
+	 */
+	const noteWithdrawalFailure = (failure: PiDurableWithdrawalFailure): void => {
+		withdrawalFailure = failure;
+		const subject = failure.requestId === undefined ? "" : ` ${failure.requestId}`;
+		const detail = failure.detail.replace(/\s+/g, " ");
+		process.stderr.write(`[entwurf pi-durable] notice withdrawal ${failure.reason}${subject}: ${detail}\n`);
+	};
+
+	/**
+	 * Withdraw every held notice none of whose announced `.msg` names is still `.msg.delivered` in the
+	 * armed mailbox, listed once. A mailbox that cannot be listed proves nothing absent: every notice
+	 * is kept and that is named. A judged notice is let go whatever the native withdraw answers — or
+	 * when it rejects, which is named and never retried — so no handle outlives its mail by more
+	 * than one read. Never throws: the read's own answer is what the caller gets.
+	 */
+	const withdrawDrained = async (context: DurableCallContext | undefined): Promise<void> => {
+		if (inbox === null || notices.length === 0) return;
+		let unread: Set<string>;
+		try {
+			unread = new Set(fs.readdirSync(inbox).filter((name) => name.endsWith(".msg.delivered")));
+		} catch (error) {
+			noteWithdrawalFailure({ reason: "inspection-failed", detail: `${inbox}: ${describeError(error)}` });
+			return;
+		}
+		for (const notice of [...notices]) {
+			if (notice.fresh.some((name) => unread.has(`${name}.delivered`))) continue;
+			notices.splice(notices.indexOf(notice), 1);
+			try {
+				await notice.submission.abort(context);
+			} catch (error) {
+				noteWithdrawalFailure({ reason: "abort-failed", requestId: notice.requestId, detail: describeError(error) });
+			}
+		}
+	};
+
+	/**
+	 * An inbox read under the doorbell's gate, then the withdrawal its drain made due — after a
+	 * failed read too, whose partial drain may already have archived mail. The bridge's own answer,
+	 * result or rejection, is returned unchanged.
+	 */
+	const readInbox = async (
+		call: () => Promise<BridgeCallResult>,
+		context: DurableCallContext | undefined,
+	): Promise<BridgeCallResult> => {
+		await enterGate();
+		try {
+			return await call();
+		} finally {
+			try {
+				await withdrawDrained(context);
+			} finally {
+				leaveGate();
+			}
 		}
 	};
 
@@ -848,15 +1001,16 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 	 * Mailbox, signal, watch — then the check that the record and this process's sender marker
 	 * still name the session — and only then the receiver marker, the one fact a sender reads.
 	 * Synchronous, so nothing can close the contact between the check and the publish. Throws,
-	 * after closing whatever it opened, when any step fails.
+	 * after closing whatever it opened, when any step fails. Returns null when the session had
+	 * already failed: the doorbell was retired as `session-failed` before this returned.
 	 */
 	const arm = (
 		gardenId: string,
 		nativeSessionId: string,
 		ownerPid: number,
 		roots: PiDurableRoots,
-		submitToRoot: DurableSubmitToRoot,
-	): string => {
+		root: DurableRootAdmission,
+	): string | null => {
 		if (ownerPid !== process.pid) {
 			throw new Error(
 				`the doorbell's watch lives in this process (${process.pid}); a receiver marker naming owner ${ownerPid} would advertise a watch that pid does not hold`,
@@ -867,6 +1021,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 		fs.mkdirSync(mailbox, { recursive: true });
 		if (!fs.existsSync(signal)) fs.writeFileSync(signal, "", { mode: 0o600 });
 		const watcher = watch(signal, () => void ring("signal"));
+		let unsubscribeFailed = (): void => {};
 		try {
 			watcher.on("error", (error) => retire("watch-error", describeError(error)));
 			const identity = readAddressableMetaIdentity(gardenId, roots.sessionsDir);
@@ -883,6 +1038,21 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 						: `the sender marker for owner ${ownerPid} names ${sender.gardenId}/${sender.nativeSessionId}, not ${gardenId}/${nativeSessionId}`,
 				);
 			}
+			// A failed session admits nothing: retire at once, so no sender reads a marker for a host that cannot wake.
+			// Subscribed before the marker is written, so a registration that throws leaves no marker. A session that
+			// failed before this arm says so during the subscription, before the doorbell exists: that is noted, and
+			// the retirement runs once the doorbell is published below. It is final; nothing re-arms.
+			let published = false;
+			let failedBeforePublished = false;
+			const sessionFailed = (): void => {
+				if (!published) {
+					failedBeforePublished = true;
+					return;
+				}
+				const problems = retire("session-failed", "the durable session failed and closed itself");
+				if (problems.length > 0) throw new Error(`the doorbell did not retire cleanly: ${problems.join("; ")}`);
+			};
+			unsubscribeFailed = root.onFailed(sessionFailed);
 			const markerPath = writeMetaReceiverMarker({
 				gardenId,
 				backend: PI_DURABLE_BACKEND,
@@ -892,16 +1062,37 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				armProvenance: "session-start",
 				receiversDir: roots.receiversDir,
 			});
-			doorbell = { gardenId, ownerPid, mailbox, signal, markerPath, watcher, submitToRoot };
+			doorbell = {
+				gardenId,
+				ownerPid,
+				mailbox,
+				signal,
+				markerPath,
+				watcher,
+				submitToRoot: root.submitToRoot,
+				unsubscribeFailed,
+			};
+			inbox = mailbox;
 			report = { status: "armed", gardenId, markerPath, admissions };
+			published = true;
+			if (failedBeforePublished) {
+				sessionFailed();
+				return null;
+			}
 			return markerPath;
 		} catch (error) {
-			try {
-				watcher.close();
-			} catch (closeError) {
+			const cleanup: unknown[] = [];
+			for (const step of [unsubscribeFailed, () => watcher.close()]) {
+				try {
+					step();
+				} catch (cleanupError) {
+					cleanup.push(cleanupError);
+				}
+			}
+			if (cleanup.length > 0) {
 				throw new AggregateError(
-					[error, closeError],
-					`${describeError(error)} (cleanup also failed: ${describeError(closeError)})`,
+					[error, ...cleanup],
+					`${describeError(error)} (cleanup also failed: ${cleanup.map(describeError).join("; ")})`,
 				);
 			}
 			throw error;
@@ -930,6 +1121,9 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				if (root !== undefined && typeof root.submitToRoot !== "function") {
 					throw new Error("the root admission handed to attach has no submitToRoot function");
 				}
+				if (root !== undefined && typeof root.onFailed !== "function") {
+					throw new Error("the root admission handed to attach has no onFailed function");
+				}
 				const ownerPid = options.ownerPid ?? process.pid;
 				const sendersDir = path.resolve(options.sendersDir ?? defaultMetaSendersDir());
 				const upsert = upsertMetaSession({
@@ -981,7 +1175,7 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 				let receiverMarkerPath: string | null = null;
 				if (root !== undefined) {
 					try {
-						receiverMarkerPath = arm(gardenId, id, ownerPid, roots, root.submitToRoot);
+						receiverMarkerPath = arm(gardenId, id, ownerPid, roots, root);
 					} catch (error) {
 						return await failAfterCleanup(new Error(`the doorbell did not arm: ${describeError(error)}`), () =>
 							client.close(),
@@ -1011,13 +1205,15 @@ export function createPiDurableContact(options: PiDurableContactOptions): PiDura
 			settleFailed(describeError(error));
 		},
 		receiver() {
-			return report;
+			return withdrawalFailure === undefined || report.status === "off" ? report : { ...report, withdrawalFailure };
 		},
 		async close() {
 			const previous = state;
 			settleFailed("the contact closed before attach completed");
 			state = { kind: "closed" };
 			const client = previous.kind === "ready" ? previous.client : undefined;
+			// Queued notices stay native (a continued session places them); this contact judges no more.
+			notices.length = 0;
 			await closeAll(disarmOnClose, async () => {
 				await client?.close();
 			});