@orkestrel/terminal 0.0.1 → 0.0.2

package/dist/src/core/index.js

@@ -1,7 +1,8 @@
-import { isArray, isBoolean, isNonEmptyString, isNumber, isRecord, isString, literalOf, recordOf } from "@orkestrel/contract";
+import { isArray, isBoolean, isNonEmptyString, isNumber, isRecord, isString, literalOf, rawShape, recordOf, stringShape } from "@orkestrel/contract";
 import { STATUS_ICONS, createStyler, stripControls } from "@orkestrel/console";
 import { Emitter } from "@orkestrel/emitter";
 import { createSSEParser } from "@orkestrel/sse";
+import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 //#region src/core/constants.ts
 /** Carriage return (`\r`, U+000D) — Enter on most terminals. */
 var RETURN = String.fromCharCode(13);
@@ -1033,8 +1034,10 @@ var isPendingPrompt = recordOf({
 	message: isString,
 	options: isRecord,
 	status: isPendingPromptStatus,
-	time: isNumber
-});
+	time: isNumber,
+	from: isString,
+	to: isString
+}, ["from", "to"]);
 /**
 * Rebuild a wire-decoded `validate` payload into a {@link ValidationRules} bag — the inverse of
 * {@link serializeValidationRules}. Keeps only the primitive rule values (`boolean` / `number` /
@@ -1232,6 +1235,37 @@ function isInsecureRemote(url) {
 	const hostname = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0] ?? "";
 	return hostname !== "localhost" && hostname !== "127.0.0.1" && hostname !== "[::1]";
 }
+/** Serialize a parked {@link PendingPrompt} into a {@link WireEvent} — event `'pending'`, `data` the JSON-stringified prompt, `id` the prompt's own id (an SSE bridge sets its frame `id:` from this). */
+function serializePending(prompt) {
+	return {
+		event: "pending",
+		data: JSON.stringify(prompt),
+		id: prompt.id
+	};
+}
+/** Serialize a parked prompt's expiry into a {@link WireEvent} — event `'expire'`, `data` the JSON-stringified `{ id }` payload. */
+function serializeExpire(id) {
+	return {
+		event: "expire",
+		data: JSON.stringify({ id })
+	};
+}
+/** The {@link WireEvent} a broker/manager sends when it is going away — event `'shutdown'`, no payload. */
+function serializeShutdown() {
+	return {
+		event: "shutdown",
+		data: ""
+	};
+}
+/** Narrow an unknown wire payload to an answer POST body — a non-empty `id` string plus a `value` key (of any shape) present. */
+function isAnswerPayload(value) {
+	return isRecord(value) && isNonEmptyString(value.id) && "value" in value;
+}
+/** Narrow an unknown value to a {@link TerminalSnapshot} — a non-empty `id` plus an optional numeric `timeout`. */
+var isTerminalSnapshot = recordOf({
+	id: isNonEmptyString,
+	timeout: isNumber
+}, ["timeout"]);
 //#endregion
 //#region src/core/Prompt.ts
 /**
@@ -1271,12 +1305,14 @@ function isInsecureRemote(url) {
 var Prompt = class {
 	#timeout;
 	#timer;
+	#cap;
 	#parked = /* @__PURE__ */ new Map();
 	#emitter;
 	#destroyed = false;
 	constructor(options) {
 		this.#timeout = options?.timeout ?? 3e5;
 		this.#timer = options?.timer ?? defaultTimer;
+		this.#cap = options?.cap;
 		this.#emitter = new Emitter({
 			on: options?.on,
 			error: options?.error
@@ -1296,43 +1332,44 @@ var Prompt = class {
 	}
 	answer(id, value) {
 		const parked = this.#parked.get(id);
-		if (parked === void 0) return false;
+		if (parked === void 0) return {
+			success: false,
+			error: "unknown"
+		};
 		const accepted = parked.respond(value);
-		if (accepted === void 0) return false;
+		if (accepted === void 0) return {
+			success: false,
+			error: "rejected"
+		};
 		parked.cancel();
 		this.#emitter.emit("answer", id, accepted);
 		this.#parked.delete(id);
-		return true;
+		return {
+			success: true,
+			value: accepted
+		};
+	}
+	park(request) {
+		const gate = this.#gate(request.form, request.options);
+		return this.#park(request.form, request.options.message, request.options, gate, request.from, request.to);
 	}
 	input(options) {
-		const validator = resolveValidation(options.validate);
-		return this.#park("input", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+		return this.#park("input", options.message, options, this.#gate("input", options)).value;
 	}
 	password(options) {
-		const validator = resolveValidation(options.validate);
-		return this.#park("password", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+		return this.#park("password", options.message, options, this.#gate("password", options)).value;
 	}
 	confirm(options) {
-		return this.#park("confirm", options.message, options, (value) => isBoolean(value) ? value : void 0);
+		return this.#park("confirm", options.message, options, this.#gate("confirm", options)).value;
 	}
 	select(options) {
-		const values = new Set(options.choices.map(normalizeChoice).map((choice) => choice.value));
-		return this.#park("select", options.message, options, (value) => isString(value) && values.has(value) ? value : void 0);
+		return this.#park("select", options.message, options, this.#gate("select", options)).value;
 	}
 	checkbox(options) {
-		const values = new Set(options.choices.map(normalizeCheckboxChoice).map((choice) => choice.value));
-		const { min, max } = options;
-		return this.#park("checkbox", options.message, options, (value) => {
-			if (!isArray(value) || !value.every(isString)) return void 0;
-			if (!value.every((item) => values.has(item))) return void 0;
-			if (min !== void 0 && value.length < min) return void 0;
-			if (max !== void 0 && value.length > max) return void 0;
-			return value;
-		});
+		return this.#park("checkbox", options.message, options, this.#gate("checkbox", options)).value;
 	}
 	editor(options) {
-		const validator = resolveValidation(options.validate);
-		return this.#park("editor", options.message, options, (value) => isString(value) && validator(value) === true ? value : void 0);
+		return this.#park("editor", options.message, options, this.#gate("editor", options)).value;
 	}
 	destroy() {
 		if (this.#destroyed) return;
@@ -1341,8 +1378,15 @@ var Prompt = class {
 		this.#parked.clear();
 		this.#emitter.destroy();
 	}
-	#park(form, message, options, gate) {
-		if (this.#destroyed) return Promise.reject(new TerminalError("EXPIRE", "broker destroyed"));
+	#park(form, message, options, gate, from, to) {
+		if (this.#destroyed) return {
+			id: crypto.randomUUID(),
+			value: Promise.reject(new TerminalError("EXPIRE", "broker destroyed"))
+		};
+		if (this.#cap !== void 0 && this.#parked.size >= this.#cap) return {
+			id: crypto.randomUUID(),
+			value: Promise.reject(new TerminalError("LIMIT", `parked-prompt cap (${this.#cap}) reached`, { cap: this.#cap }))
+		};
 		const id = crypto.randomUUID();
 		const prompt = {
 			id,
@@ -1350,35 +1394,83 @@ var Prompt = class {
 			message,
 			options: serializePromptOptions(options),
 			status: "pending",
-			time: Date.now()
+			time: Date.now(),
+			...from !== void 0 ? { from } : {},
+			...to !== void 0 ? { to } : {}
 		};
-		return new Promise((resolve, reject) => {
-			const cancel = this.#timer(() => this.#expire(id), this.#timeout);
-			const respond = (value) => {
-				const accepted = gate(value);
-				if (accepted === void 0) return void 0;
-				const current = this.#parked.get(id);
-				if (current !== void 0) this.#parked.set(id, {
-					...current,
-					prompt: {
-						...current.prompt,
-						status: "answered"
-					}
+		return {
+			id,
+			value: new Promise((resolve, reject) => {
+				const cancel = this.#timer(() => this.#expire(id), this.#timeout);
+				const respond = (answer) => {
+					const accepted = gate(answer);
+					if (accepted === void 0) return void 0;
+					const current = this.#parked.get(id);
+					if (current !== void 0) this.#parked.set(id, {
+						...current,
+						prompt: {
+							...current.prompt,
+							status: "answered"
+						}
+					});
+					resolve(accepted);
+					return accepted;
+				};
+				const expire = () => {
+					reject(new TerminalError("EXPIRE", `prompt ${id} expired`, { id }));
+				};
+				this.#parked.set(id, {
+					prompt,
+					respond,
+					expire,
+					cancel
 				});
-				resolve(accepted);
-				return accepted;
-			};
-			const expire = () => {
-				reject(new TerminalError("EXPIRE", `prompt ${id} expired`, { id }));
-			};
-			this.#parked.set(id, {
-				prompt,
-				respond,
-				expire,
-				cancel
-			});
-			this.#emitter.emit("pending", prompt);
-		});
+				this.#emitter.emit("pending", prompt);
+			})
+		};
+	}
+	#gate(form, options) {
+		switch (form) {
+			case "input":
+			case "password":
+			case "editor": {
+				if (!this.#isTextOptions(form, options)) return () => void 0;
+				const validator = resolveValidation(options.validate);
+				return (value) => isString(value) && validator(value) === true ? value : void 0;
+			}
+			case "confirm":
+				if (!this.#isConfirmOptions(form, options)) return () => void 0;
+				return (value) => isBoolean(value) ? value : void 0;
+			case "select": {
+				if (!this.#isSelectOptions(form, options)) return () => void 0;
+				const values = new Set(options.choices.map(normalizeChoice).map((choice) => choice.value));
+				return (value) => isString(value) && values.has(value) ? value : void 0;
+			}
+			case "checkbox": {
+				if (!this.#isCheckboxOptions(form, options)) return () => void 0;
+				const values = new Set(options.choices.map(normalizeCheckboxChoice).map((choice) => choice.value));
+				const { min, max } = options;
+				return (value) => {
+					if (!isArray(value) || !value.every(isString)) return void 0;
+					if (!value.every((item) => values.has(item))) return void 0;
+					if (min !== void 0 && value.length < min) return void 0;
+					if (max !== void 0 && value.length > max) return void 0;
+					return value;
+				};
+			}
+		}
+	}
+	#isTextOptions(form, _options) {
+		return form === "input" || form === "password" || form === "editor";
+	}
+	#isConfirmOptions(form, _options) {
+		return form === "confirm";
+	}
+	#isSelectOptions(form, _options) {
+		return form === "select";
+	}
+	#isCheckboxOptions(form, _options) {
+		return form === "checkbox";
 	}
 	#expire(id) {
 		const parked = this.#parked.get(id);
@@ -1415,8 +1507,10 @@ var Prompt = class {
 *   never an `as`), dispatched to `terminal`, and its resolved value POSTed back to `url`.
 *   Dispatch is strictly SERIAL: the read loop drives the terminal for ONE prompt at a time and
 *   only reads/dispatches the next event after the current prompt fully settles (its answer
-*   POSTed). A prompt id redelivered by the broker AFTER its prior dispatch has settled is
-*   dispatched again — the client does not dedupe across completion.
+*   POSTed). A prompt id redelivered (e.g. after a reconnect) WHILE its prior dispatch is still
+*   in flight is skipped (a `#seen` set tracks in-flight ids); once that dispatch settles (or the
+*   broker sends `expire` for the id) the id is dropped from `#seen`, so a later redelivery of the
+*   SAME id after completion is dispatched again — the client does not dedupe across completion.
 * - **Server signals.** An `expire` event (the broker dropped a parked prompt) emits `expire`; a
 *   `shutdown` event calls {@link disconnect} (not {@link destroy}) — the client stops streaming
 *   without auto-reconnect but stays reusable; a later {@link connect} recovers it.
@@ -1450,6 +1544,7 @@ var PromptClient = class {
 	#connected = false;
 	#destroyed = false;
 	#warnedInsecureToken = false;
+	#seen = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.url = options.url;
 		this.#terminal = options.terminal;
@@ -1500,6 +1595,7 @@ var PromptClient = class {
 		if (this.#destroyed) return;
 		this.#destroyed = true;
 		this.disconnect();
+		this.#seen.clear();
 		this.#emitter.destroy();
 	}
 	async #stream() {
@@ -1535,22 +1631,28 @@ var PromptClient = class {
 	async #handle(event) {
 		if (event.event === SSE_EVENTS.pending) {
 			const parsed = parseWireJSON(event.data);
-			if (isPendingPrompt(parsed)) await this.#dispatch(parsed.id, parsed);
+			if (isPendingPrompt(parsed) && !this.#seen.has(parsed.id)) await this.#dispatch(parsed.id, parsed);
 			return;
 		}
 		if (event.event === SSE_EVENTS.expire) {
 			const parsed = parseWireJSON(event.data);
-			if (isRecord(parsed) && isString(parsed.id)) this.#emitter.emit("expire", parsed.id);
+			if (isRecord(parsed) && isString(parsed.id)) {
+				this.#seen.delete(parsed.id);
+				this.#emitter.emit("expire", parsed.id);
+			}
 			return;
 		}
 		if (event.event === SSE_EVENTS.shutdown) this.disconnect();
 	}
 	async #dispatch(id, pending) {
+		this.#seen.add(id);
 		try {
 			const value = await dispatchPendingPrompt(this.#terminal, pending);
 			await this.#post(id, value);
 		} catch (error) {
 			this.#emitter.emit("error", error);
+		} finally {
+			this.#seen.delete(id);
 		}
 	}
 	async #post(id, value) {
@@ -1569,8 +1671,11 @@ var PromptClient = class {
 		this.#emitter.emit("disconnect");
 	}
 	#headers(base) {
-		if (this.#token !== void 0) base[HEADER_TOKEN] = this.#token;
-		return base;
+		if (this.#token !== void 0) return {
+			...base,
+			[HEADER_TOKEN]: this.#token
+		};
+		return { ...base };
 	}
 	#wait(ms) {
 		return new Promise((resolve) => {
@@ -1587,6 +1692,345 @@ var PromptClient = class {
 	}
 };
 //#endregion
+//#region src/core/TerminalManager.ts
+/**
+* The multi-endpoint terminal MANAGER — a registry of named {@link PromptInterface} brokers (one
+* per endpoint), so several parties can `ask` prompts of each other by NAME with a `from` → `to`
+* attribution edge on every parked prompt, and a transitive DEADLOCK check across all in-flight
+* asks.
+*
+* @remarks
+* - **Registry.** `add(name, options?)` mints (or, if `name` is already mounted, returns the
+*   EXISTING broker UNCHANGED — idempotent, never clobbers a live/parked endpoint). Every mounted
+*   broker's `pending` / `answer` / `expire` events are re-emitted on the manager, attributed by
+*   `name`.
+* - **`ask`.** The target must already be mounted via {@link add} — `ask` never auto-adds it;
+*   rejects `TARGET` for an unknown `to` (listing the known names). Rejects `DEADLOCK` when parking
+*   `from → to` would close a cycle over the CURRENT in-flight edge set (walked transitively);
+*   otherwise parks through the target's broker and resolves with the ORIGINAL ticket Promise (edge
+*   cleanup is attached via `.then`, never altering the value/rejection the caller observes).
+* - **Durable open / save.** `open(name)` restores an EMPTY broker from the `store` (parked
+*   Promises are process-bound and never resurrected); `save(name)` persists the endpoint's
+*   configured `timeout`.
+* - **Removal.** `remove` drops one endpoint or a batch (§9.2, array overload FIRST), destroying
+*   each broker (which expires every prompt still parked on it). `clear` drops all; `destroy` is
+*   idempotent.
+*
+* @example
+* ```ts
+* const manager = new TerminalManager()
+* manager.add('agent')
+* const name = manager.ask('user', 'agent', 'input', { message: 'Your name' })
+* manager.answer('agent', manager.pending('agent')[0].id, 'Ada')
+* await name // 'Ada'
+* ```
+*/
+var TerminalManager = class {
+	#terminals = /* @__PURE__ */ new Map();
+	#config = /* @__PURE__ */ new Map();
+	#listeners = /* @__PURE__ */ new Map();
+	#edges = /* @__PURE__ */ new Map();
+	#store;
+	#timeout;
+	#timer;
+	#cap;
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#store = options?.store;
+		this.#timeout = options?.timeout;
+		this.#timer = options?.timer;
+		this.#cap = options?.cap;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#terminals.size;
+	}
+	terminal(name) {
+		return this.#terminals.get(name);
+	}
+	terminals() {
+		return [...this.#terminals.keys()];
+	}
+	add(name, options) {
+		if (this.#destroyed) throw new TerminalError("DESTROYED", "manager destroyed");
+		const existing = this.#terminals.get(name);
+		if (existing !== void 0) return existing;
+		const timeout = options?.timeout ?? this.#timeout;
+		const timer = options?.timer ?? this.#timer;
+		const cap = options?.cap ?? this.#cap;
+		const broker = createPrompt({
+			...timeout !== void 0 ? { timeout } : {},
+			...timer !== void 0 ? { timer } : {},
+			...cap !== void 0 ? { cap } : {}
+		});
+		const listeners = {
+			pending: (prompt) => this.#emitter.emit("pending", prompt),
+			answer: (id, value) => this.#emitter.emit("answer", name, id, value),
+			expire: (id) => this.#emitter.emit("expire", name, id)
+		};
+		broker.emitter.on("pending", listeners.pending);
+		broker.emitter.on("answer", listeners.answer);
+		broker.emitter.on("expire", listeners.expire);
+		this.#terminals.set(name, broker);
+		this.#config.set(name, options ?? {});
+		this.#listeners.set(name, listeners);
+		return broker;
+	}
+	ask(from, to, form, options) {
+		const broker = this.#terminals.get(to);
+		if (broker === void 0) {
+			const known = this.terminals();
+			return Promise.reject(new TerminalError("TARGET", `unknown terminal '${to}' (known: ${known.length > 0 ? known.join(", ") : "none"})`, {
+				to,
+				known
+			}));
+		}
+		const cycle = this.#findCycle(from, to);
+		if (cycle !== void 0) return Promise.reject(new TerminalError("DEADLOCK", `ask ${from} -> ${to} would deadlock: ${cycle.join(" -> ")}`, {
+			from,
+			to,
+			path: cycle
+		}));
+		const ticket = broker.park({
+			form,
+			options,
+			from,
+			to
+		});
+		if (broker.pending(ticket.id) !== void 0) {
+			this.#edges.set(ticket.id, {
+				from,
+				to
+			});
+			const clear = () => {
+				this.#edges.delete(ticket.id);
+			};
+			ticket.value.then(clear, clear);
+		}
+		return ticket.value;
+	}
+	pending(to) {
+		if (to !== void 0) {
+			const broker = this.#terminals.get(to);
+			return broker === void 0 ? [] : broker.pending();
+		}
+		const result = [];
+		for (const broker of this.#terminals.values()) result.push(...broker.pending());
+		return result;
+	}
+	answer(to, id, value) {
+		const broker = this.#terminals.get(to);
+		if (broker === void 0) return {
+			success: false,
+			error: "terminal"
+		};
+		return broker.answer(id, value);
+	}
+	async open(name) {
+		if (this.#destroyed) throw new TerminalError("DESTROYED", "manager destroyed");
+		const existing = this.#terminals.get(name);
+		if (existing !== void 0) return existing;
+		if (this.#store === void 0) return void 0;
+		const snapshot = await this.#store.get(name);
+		if (this.#destroyed) throw new TerminalError("DESTROYED", "manager destroyed");
+		if (snapshot === void 0) return void 0;
+		return this.add(name, snapshot.timeout !== void 0 ? { timeout: snapshot.timeout } : {});
+	}
+	async save(name) {
+		const broker = this.#terminals.get(name);
+		if (this.#store === void 0 || broker === void 0) return false;
+		const config = this.#config.get(name);
+		const snapshot = {
+			id: name,
+			...config?.timeout !== void 0 ? { timeout: config.timeout } : {}
+		};
+		await this.#store.set(snapshot);
+		return true;
+	}
+	remove(names) {
+		if (isArray(names)) {
+			let removed = false;
+			for (const name of names) if (this.#removeOne(name)) removed = true;
+			return removed;
+		}
+		return this.#removeOne(names);
+	}
+	clear() {
+		for (const name of [...this.#terminals.keys()]) this.#removeOne(name);
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.clear();
+		this.#emitter.destroy();
+	}
+	#removeOne(name) {
+		const broker = this.#terminals.get(name);
+		if (broker === void 0) return false;
+		broker.destroy();
+		const listeners = this.#listeners.get(name);
+		if (listeners !== void 0) {
+			broker.emitter.off("pending", listeners.pending);
+			broker.emitter.off("answer", listeners.answer);
+			broker.emitter.off("expire", listeners.expire);
+		}
+		this.#terminals.delete(name);
+		this.#config.delete(name);
+		this.#listeners.delete(name);
+		return true;
+	}
+	#findCycle(from, to) {
+		if (from === to) return [from, to];
+		const visited = /* @__PURE__ */ new Set([to]);
+		const queue = [[to]];
+		while (queue.length > 0) {
+			const path = queue.shift();
+			if (path === void 0) break;
+			const last = path[path.length - 1];
+			if (last === void 0) continue;
+			for (const edge of this.#edges.values()) {
+				if (edge.from !== last) continue;
+				if (edge.to === from) return [
+					from,
+					...path,
+					from
+				];
+				if (visited.has(edge.to)) continue;
+				visited.add(edge.to);
+				queue.push([...path, edge.to]);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/core/MemoryTerminalStore.ts
+/**
+* The in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
+* {@link TerminalSnapshot}s keyed by endpoint id, the DEFAULT store
+* {@link import('./factories.js').createMemoryTerminalStore} builds. The EXACT twin of
+* {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}.
+*
+* @remarks
+* A plain `Map<string, TerminalSnapshot>` (AGENTS §21 — the snapshot is already pure, self-contained
+* CONFIG-only JSON, so no encoding is needed for the memory tier). There is NO idle-TTL and NO
+* eviction: a persisted config lives until an explicit `delete`. A durable backend (JSON / SQLite /
+* IndexedDB) swaps in through the SAME interface without touching the manager — its
+* driver-pluggable twin is {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore} (the
+* snapshot as one opaque JSON column).
+*
+* - **`get` resolves the persisted snapshot for an id**, or `undefined` if none is stored.
+* - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
+* - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
+*
+* The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
+* bijection with {@link TerminalStoreInterface}). Hydration is a caller concern: `open` always
+* restores an EMPTY broker — parked Promises are process-bound and never resurrected.
+*
+* @example
+* ```ts
+* import { createMemoryTerminalStore } from '@src/core'
+*
+* const store = createMemoryTerminalStore()
+* await store.set({ id: 'shell', timeout: 5000 })   // persist a config
+* const snapshot = await store.get('shell')
+* await store.delete('shell')                       // drop it
+* ```
+*/
+var MemoryTerminalStore = class {
+	#snapshots = /* @__PURE__ */ new Map();
+	get(id) {
+		return Promise.resolve(this.#snapshots.get(id));
+	}
+	set(snapshot) {
+		this.#snapshots.set(snapshot.id, snapshot);
+		return Promise.resolve();
+	}
+	delete(id) {
+		this.#snapshots.delete(id);
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/core/DatabaseTerminalStore.ts
+/**
+* A {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
+* durable CONFIG state IS a row, so persistence reduces to keyed point-access (`get` / `set` /
+* `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
+* {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}.
+*
+* @remarks
+* The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
+* JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
+* IndexedDB backend swaps in WITHOUT touching the manager — the same seam as
+* {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}. The driver defaults to memory
+* ({@link import('./factories.js').createDatabaseTerminalStore} passes `createMemoryDriver()`), so
+* it ALSO works in memory out of the box; you opt into the durable plumbing by passing a JSON /
+* SQLite / IndexedDB driver.
+*
+* The {@link TerminalSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+* `{ id; snapshot }` ({@link TerminalSnapshotRow}). The snapshot is already a COMPLETE,
+* self-contained, pure-JSON CONFIG payload (no live broker state), so storing it whole is lossless
+* AND keeps the row type flat (`snapshot` reads back as `unknown`).
+*
+* - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
+*   the row `{ id: snapshot.id, snapshot }`.
+* - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
+*   a {@link TerminalSnapshot} ({@link import('./helpers.js').isTerminalSnapshot} — the AGENTS §14
+*   boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+* - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
+*
+* There is NO idle-TTL / eviction — a persisted config lives until an explicit `delete`. The public
+* surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method bijection with
+* {@link TerminalStoreInterface}). Hydration stays a caller concern: `open` always restores an EMPTY
+* broker — parked Promises are process-bound and never resurrected.
+*
+* @example
+* ```ts
+* import { createDatabaseTerminalStore, createMemoryDriver } from '@src/core'
+*
+* const store = createDatabaseTerminalStore(createMemoryDriver()) // a durable driver swaps in here
+* await store.set({ id: 'shell', timeout: 5000 })        // persist the config (one JSON column)
+* const snapshot = await store.get('shell')
+* await store.delete('shell')                            // drop it
+* ```
+*/
+var DatabaseTerminalStore = class {
+	#table;
+	/**
+	* Wrap a table as a terminal store.
+	*
+	* @param table - The {@link TableInterface} holding the snapshots — its row is the
+	*   {@link TerminalSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
+	*/
+	constructor(table) {
+		this.#table = table;
+	}
+	/** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `TerminalSnapshot`. */
+	async get(id) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		return isTerminalSnapshot(row.snapshot) ? row.snapshot : void 0;
+	}
+	/** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+	async set(snapshot) {
+		await this.#table.set({
+			id: snapshot.id,
+			snapshot
+		});
+	}
+	/** Drop a snapshot by id; an absent id is a no-op (no throw). */
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
+//#endregion
 //#region src/core/factories.ts
 /**
 * Create the headless prompt {@link PromptInterface} BROKER — it parks each prompt call as a
@@ -1645,7 +2089,66 @@ function createPrompt(options) {
 function createPromptClient(options) {
 	return new PromptClient(options);
 }
+/**
+* Create the multi-endpoint {@link TerminalManagerInterface} — a named registry of
+* {@link PromptInterface} brokers so several parties can `ask` prompts of each other by name,
+* with a transitive DEADLOCK check across every in-flight ask.
+*
+* @param options - See {@link TerminalManagerOptions}
+* @returns A {@link TerminalManagerInterface}
+*
+* @example
+* ```ts
+* import { createTerminalManager } from '@src/core'
+*
+* const manager = createTerminalManager()
+* manager.add('agent')
+* ```
+*/
+function createTerminalManager(options) {
+	return new TerminalManager(options);
+}
+/**
+* Create the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of endpoint
+* config snapshots, the default store backing a {@link TerminalManagerInterface}'s `open` / `save`.
+*
+* @returns A {@link TerminalStoreInterface}
+*
+* @example
+* ```ts
+* import { createMemoryTerminalStore } from '@src/core'
+*
+* const store = createMemoryTerminalStore()
+* ```
+*/
+function createMemoryTerminalStore() {
+	return new MemoryTerminalStore();
+}
+/**
+* Create a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
+* driver-pluggable twin of {@link createMemoryTerminalStore}, storing each endpoint's config
+* snapshot as one opaque JSON column.
+*
+* @param driver - The {@link DriverInterface} backing the table (default an in-memory driver)
+* @returns A {@link TerminalStoreInterface}
+*
+* @example
+* ```ts
+* import { createDatabaseTerminalStore } from '@src/core'
+*
+* const store = createDatabaseTerminalStore() // in-memory by default
+* ```
+*/
+function createDatabaseTerminalStore(driver = createMemoryDriver()) {
+	return new DatabaseTerminalStore(createDatabase({
+		driver,
+		tables: { terminals: {
+			id: stringShape(),
+			snapshot: rawShape({})
+		} }
+	}).table("terminals"));
+}
 //#endregion
-export { ACCEPT_EVENT_STREAM, ALPHANUMERIC_PATTERN, BACKSPACE, CONTROL_NAMES, CTRL_A, CTRL_C, CTRL_D, CTRL_E, CTRL_U, DEFAULT_MASK, DEFAULT_PROMPT_TIMEOUT_MS, DEFAULT_RECONNECT_DELAY_MS, DELETE, EMAIL_PATTERN, ESCAPE, HEADER_TOKEN, INTEGER_PATTERN, KEY_CSI, KEY_SS3, NEWLINE, NUMERIC_PATTERN, PROMPT_ICONS, Prompt, PromptClient, RETURN, RULE_MESSAGES, SEQUENCE_NAMES, SPACE, SSE_BUFFER_LIMIT, SSE_EVENTS, TAB, TerminalError, URL_PATTERN, appendRule, buildRuleValidator, checkboxReduce, checkboxView, composeValidators, confirmReduce, confirmView, createCheckboxState, createConfirmState, createEditorState, createInputState, createPasswordState, createPrompt, createPromptClient, createSelectState, defaultTimer, dispatchPendingPrompt, editLine, editorReduce, editorView, errorLine, evaluateRule, gateSelection, globalFetch, inputReduce, inputView, isAbortError, isCheckboxChoice, isInsecureRemote, isPendingPrompt, isPendingPromptStatus, isPrintable, isPromptChoice, isPromptType, isTerminalError, normalizeCheckboxChoice, normalizeChoice, parseKey, parseWireJSON, passing, passwordReduce, passwordView, promptHeader, reconstructValidationRules, resolveChoices, resolveOption, resolveValidation, sanitizeChoiceLabels, selectReduce, selectView, serializeChoices, serializePromptOptions, serializeValidationRules, submitHeader, toggleIndex };
+export { ACCEPT_EVENT_STREAM, ALPHANUMERIC_PATTERN, BACKSPACE, CONTROL_NAMES, CTRL_A, CTRL_C, CTRL_D, CTRL_E, CTRL_U, DEFAULT_MASK, DEFAULT_PROMPT_TIMEOUT_MS, DEFAULT_RECONNECT_DELAY_MS, DELETE, DatabaseTerminalStore, EMAIL_PATTERN, ESCAPE, HEADER_TOKEN, INTEGER_PATTERN, KEY_CSI, KEY_SS3, MemoryTerminalStore, NEWLINE, NUMERIC_PATTERN, PROMPT_ICONS, Prompt, PromptClient, RETURN, RULE_MESSAGES, SEQUENCE_NAMES, SPACE, SSE_BUFFER_LIMIT, SSE_EVENTS, TAB, TerminalError, TerminalManager, URL_PATTERN, appendRule, buildRuleValidator, checkboxReduce, checkboxView, composeValidators, confirmReduce, confirmView, createCheckboxState, createConfirmState, createDatabaseTerminalStore, createEditorState, createInputState, createMemoryTerminalStore, createPasswordState, createPrompt, createPromptClient, createSelectState, createTerminalManager, defaultTimer, dispatchPendingPrompt, editLine, editorReduce, editorView, errorLine, evaluateRule, gateSelection, globalFetch, inputReduce, inputView, isAbortError, isAnswerPayload, isCheckboxChoice, isInsecureRemote, isPendingPrompt, isPendingPromptStatus, isPrintable, isPromptChoice, isPromptType, isTerminalError, isTerminalSnapshot, normalizeCheckboxChoice, normalizeChoice, parseKey, parseWireJSON, passing, passwordReduce, passwordView, promptHeader, reconstructValidationRules, resolveChoices, resolveOption, resolveValidation, sanitizeChoiceLabels, selectReduce, selectView, serializeChoices, serializeExpire, serializePending, serializePromptOptions, serializeShutdown, serializeValidationRules, submitHeader, toggleIndex };
 
 //# sourceMappingURL=index.js.map