@orkestrel/tool 0.0.3 → 0.0.5

package/dist/src/server/index.cjs

@@ -15,188 +15,253 @@ var TERMINAL_ROUTES_PATH = "/terminals/:name";
 */
 var TERMINAL_KEEPALIVE_MS = 15e3;
 //#endregion
-//#region src/server/factories.ts
+//#region src/server/routes/TerminalConnection.ts
 /**
-* Build the two `TerminalManagerInterface` (`@orkestrel/terminal`) routes — a GET SSE stream and
-* a POST answer endpoint, both mounted on the SAME `:name`-templated path — that bridge a manager's
-* endpoints onto the wire, byte-compatible with `PromptClient`.
-*
-* @remarks
-* - **GET (SSE).** Optionally token-gated (`401` on mismatch), `404` when `name` names no
-*   endpoint. Opens a stream, replays every currently-{@link import('@orkestrel/terminal').PendingPrompt}
-*   as a `pending` frame, then live-forwards the manager's own `pending` / `expire` events scoped
-*   to `name`. A `keepalive`-interval `: ` comment ping is armed via the injected `timer` (default
-*   the host `setTimeout`). On the request's `AbortSignal` firing (client disconnect OR server
-*   stop) the keepalive is cancelled, both listeners unsubscribed, and the stream ended — no
-*   `shutdown` frame is sent, so a reconnecting client is never told the endpoint is gone.
-* - **POST (answer).** Same token + `404` checks, then reads the body capped at `options.limit`
-*   bytes (`413` over, `manager.answer` never called — see {@link TerminalRoutesOptions.limit}),
-*   parses the JSON body (`400` on invalid JSON, `422` when it isn't an `{ id, value }`
-*   {@link import('@orkestrel/terminal').isAnswerPayload} shape), and routes it through
-*   `manager.answer` — `204` on success, `404` for `'terminal'`, `422` for `'unknown'` / `'rejected'`.
-*
-* @remarks
-* The `token` option (a string OR a validator function — {@link TerminalToken}) is validated at
-* GET connect, on EVERY POST, and RE-VALIDATED on every keepalive tick of a live SSE stream — a
-* stream whose presented token stops validating is torn down rather than left streaming forever.
-* Concurrent POST answerers race first-write-wins — a late POST for an already-settled prompt
-* returns `422`.
-*
-* @param manager - The `TerminalManagerInterface` (`@orkestrel/terminal`) whose endpoints are bridged
-* @param options - See {@link TerminalRoutesOptions}
-* @returns Exactly two {@link TerminalRoute} records — GET then POST — sharing one path
+* Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.
 *
 * @example
 * ```ts
-* import { createTerminalRoutes } from '@src/server'
-* import { createTerminalManager } from '@orkestrel/terminal'
+* import { TerminalConnection } from '@orkestrel/tool/server'
 *
-* const manager = createTerminalManager()
-* manager.add('assistant')
-* const routes = createTerminalRoutes(manager, { token: 'secret' })
-* // mount `routes` against any router accepting `{ method, path, handler }`
+* const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)
+* const response = connection.open()
 * ```
 */
-function createTerminalRoutes(manager, options) {
-	const path = options?.path ?? "/terminals/:name";
-	const token = options?.token;
-	const keepalive = options?.keepalive ?? 15e3;
-	const timer = options?.timer ?? _orkestrel_terminal.defaultTimer;
-	const limit = options?.limit ?? _orkestrel_server.DEFAULT_BODY_LIMIT;
-	async function readBoundedText(request) {
-		const reader = request.body?.getReader();
-		if (reader === void 0) return {
-			ok: true,
-			text: ""
-		};
-		const chunks = [];
-		let received = 0;
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			received += value.byteLength;
-			if (received > limit) {
-				await reader.cancel();
-				return { ok: false };
-			}
-			chunks.push(value);
+var TerminalConnection = class {
+	#manager;
+	#name;
+	#request;
+	#stream;
+	#accepts;
+	#timer;
+	#keepalive;
+	#presented;
+	#cancel;
+	#destroyHandler;
+	#pendingHandler;
+	#expireHandler;
+	#tickHandler;
+	/**
+	* Create a terminal stream connection.
+	*
+	* @param manager - Terminal manager supplying pending prompts and lifecycle events
+	* @param name - Terminal endpoint streamed by this connection
+	* @param request - Request whose abort signal owns the connection lifetime
+	* @param stream - Open SSE stream
+	* @param accepts - Presented-token validator
+	* @param timer - Keepalive timer implementation
+	* @param keepalive - Keepalive interval in milliseconds
+	*/
+	constructor(manager, name, request, stream, accepts, timer, keepalive) {
+		this.#manager = manager;
+		this.#name = name;
+		this.#request = request;
+		this.#stream = stream;
+		this.#accepts = accepts;
+		this.#timer = timer;
+		this.#keepalive = keepalive;
+		this.#presented = request.headers.get(_orkestrel_terminal.HEADER_TOKEN) ?? void 0;
+		this.#destroyHandler = this.#destroy.bind(this);
+		this.#pendingHandler = this.#pending.bind(this);
+		this.#expireHandler = this.#expire.bind(this);
+		this.#tickHandler = this.#tick.bind(this);
+	}
+	/**
+	* Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.
+	*
+	* @returns The SSE response
+	*/
+	open() {
+		if (this.#stream.closed || this.#request.signal.aborted) {
+			this.#destroy();
+			return this.#stream.response;
 		}
-		const buffer = new Uint8Array(received);
-		let offset = 0;
-		for (const chunk of chunks) {
-			buffer.set(chunk, offset);
-			offset += chunk.byteLength;
+		if (this.#cancel !== void 0) return this.#stream.response;
+		for (const prompt of this.#manager.pending(this.#name)) this.#write((0, _orkestrel_terminal.serializePending)(prompt));
+		this.#manager.emitter.on("pending", this.#pendingHandler);
+		this.#manager.emitter.on("expire", this.#expireHandler);
+		this.#cancel = this.#timer(this.#tickHandler, this.#keepalive);
+		this.#request.signal.addEventListener("abort", this.#destroyHandler);
+		return this.#stream.response;
+	}
+	#write(wire) {
+		this.#stream.write({
+			event: wire.event,
+			data: wire.data,
+			...wire.id === void 0 ? {} : { id: wire.id }
+		});
+	}
+	#pending(prompt) {
+		if (prompt.to !== this.#name) return;
+		if (this.#stream.closed) {
+			this.#destroy();
+			return;
 		}
-		return {
-			ok: true,
-			text: new TextDecoder().decode(buffer)
-		};
+		this.#write((0, _orkestrel_terminal.serializePending)(prompt));
+	}
+	#expire(to, id) {
+		if (to !== this.#name) return;
+		if (this.#stream.closed) {
+			this.#destroy();
+			return;
+		}
+		this.#write((0, _orkestrel_terminal.serializeExpire)(id));
+	}
+	#tick() {
+		if (this.#stream.closed || !this.#accepted()) {
+			this.#destroy();
+			return;
+		}
+		this.#stream.comment("");
+		this.#cancel = this.#timer(this.#tickHandler, this.#keepalive);
+	}
+	#accepted() {
+		try {
+			return this.#accepts(this.#presented);
+		} catch {
+			return false;
+		}
+	}
+	#destroy() {
+		const cancel = this.#cancel;
+		this.#cancel = void 0;
+		cancel?.();
+		this.#manager.emitter.off("pending", this.#pendingHandler);
+		this.#manager.emitter.off("expire", this.#expireHandler);
+		this.#request.signal.removeEventListener("abort", this.#destroyHandler);
+		this.#stream.end();
+	}
+};
+//#endregion
+//#region src/server/routes/TerminalRoutes.ts
+/**
+* Build and serve the terminal manager's GET stream and POST answer routes.
+*
+* @example
+* ```ts
+* import { TerminalRoutes } from '@orkestrel/tool/server'
+*
+* const routes = new TerminalRoutes(manager).routes()
+* ```
+*/
+var TerminalRoutes = class {
+	#manager;
+	#path;
+	#token;
+	#keepalive;
+	#timer;
+	#limit;
+	#accepts;
+	#get;
+	#post;
+	/**
+	* Create a terminal route owner.
+	*
+	* @param manager - Terminal manager bridged onto HTTP
+	* @param options - Shared route, authorization, keepalive, timer, and body-limit options
+	*/
+	constructor(manager, options) {
+		this.#manager = manager;
+		this.#path = options?.path ?? "/terminals/:name";
+		this.#token = options?.token;
+		this.#keepalive = options?.keepalive ?? 15e3;
+		this.#timer = options?.timer ?? _orkestrel_terminal.defaultTimer;
+		const limit = options?.limit;
+		this.#limit = limit === void 0 || !Number.isFinite(limit) ? _orkestrel_server.DEFAULT_BODY_LIMIT : Math.max(0, Math.floor(limit));
+		this.#accepts = this.#valid.bind(this);
+		this.#get = this.#handleGet.bind(this);
+		this.#post = this.#handlePost.bind(this);
+	}
+	/**
+	* Project the bound GET and POST route records.
+	*
+	* @returns The GET stream route followed by the POST answer route
+	*/
+	routes() {
+		return [{
+			method: "GET",
+			path: this.#path,
+			handler: this.#get
+		}, {
+			method: "POST",
+			path: this.#path,
+			handler: this.#post
+		}];
 	}
-	function valid(presented) {
-		if (token === void 0) return true;
+	#valid(presented) {
+		if (this.#token === void 0) return true;
 		try {
-			return typeof token === "function" ? token(presented) : presented === token;
+			return typeof this.#token === "function" ? this.#token(presented) : presented === this.#token;
 		} catch {
 			return false;
 		}
 	}
-	function authorized(request) {
-		return valid(request.headers.get(_orkestrel_terminal.HEADER_TOKEN) ?? void 0);
+	#authorized(request) {
+		return this.#valid(request.headers.get(_orkestrel_terminal.HEADER_TOKEN) ?? void 0);
 	}
-	return [{
-		method: "GET",
-		path,
-		handler(request, context) {
-			if (!authorized(request)) return new Response(null, { status: 401 });
-			const name = context.params.name;
-			if (manager.terminal(name) === void 0) return new Response(null, { status: 404 });
-			const presented = request.headers.get(_orkestrel_terminal.HEADER_TOKEN) ?? void 0;
-			const stream = (0, _orkestrel_server.openStream)();
-			for (const prompt of manager.pending(name)) {
-				const wire = (0, _orkestrel_terminal.serializePending)(prompt);
-				stream.write({
-					event: wire.event,
-					data: wire.data,
-					id: wire.id
-				});
-			}
-			let cancelKeepalive = () => {};
-			const teardown = () => {
-				cancelKeepalive();
-				manager.emitter.off("pending", pendingHandler);
-				manager.emitter.off("expire", expireHandler);
-				request.signal.removeEventListener("abort", teardown);
-				stream.end();
-			};
-			const pendingHandler = (prompt) => {
-				if (prompt.to !== name) return;
-				if (stream.closed) {
-					teardown();
-					return;
-				}
-				const wire = (0, _orkestrel_terminal.serializePending)(prompt);
-				stream.write({
-					event: wire.event,
-					data: wire.data,
-					id: wire.id
-				});
-			};
-			const expireHandler = (to, id) => {
-				if (to !== name) return;
-				if (stream.closed) {
-					teardown();
-					return;
-				}
-				const wire = (0, _orkestrel_terminal.serializeExpire)(id);
-				stream.write({
-					event: wire.event,
-					data: wire.data,
-					id: wire.id
-				});
-			};
-			manager.emitter.on("pending", pendingHandler);
-			manager.emitter.on("expire", expireHandler);
-			cancelKeepalive = timer(function ping() {
-				if (stream.closed) {
-					teardown();
-					return;
-				}
-				if (!valid(presented)) {
-					teardown();
-					return;
-				}
-				stream.comment("");
-				cancelKeepalive = timer(ping, keepalive);
-			}, keepalive);
-			request.signal.addEventListener("abort", teardown);
-			return stream.response;
+	#handleGet(request, context) {
+		if (!this.#authorized(request)) return new Response(null, { status: 401 });
+		const name = context.params.name;
+		if (name === void 0 || this.#manager.terminal(name) === void 0) return new Response(null, { status: 404 });
+		return new TerminalConnection(this.#manager, name, request, (0, _orkestrel_server.openStream)(), this.#accepts, this.#timer, this.#keepalive).open();
+	}
+	async #handlePost(request, context) {
+		if (!this.#authorized(request)) return new Response(null, { status: 401 });
+		const name = context.params.name;
+		if (name === void 0 || this.#manager.terminal(name) === void 0) return new Response(null, { status: 404 });
+		let bytes;
+		try {
+			bytes = await (0, _orkestrel_server.collectRequestBody)(request, Math.max(1, this.#limit));
+		} catch (error) {
+			if (error instanceof _orkestrel_server.ContentTooLargeError) return new Response(null, { status: 413 });
+			throw error;
 		}
-	}, {
-		method: "POST",
-		path,
-		async handler(request, context) {
-			if (!authorized(request)) return new Response(null, { status: 401 });
-			const name = context.params.name;
-			if (manager.terminal(name) === void 0) return new Response(null, { status: 404 });
-			const bounded = await readBoundedText(request);
-			if (!bounded.ok) return new Response(null, { status: 413 });
-			let body;
-			try {
-				body = JSON.parse(bounded.text);
-			} catch {
-				return new Response(null, { status: 400 });
-			}
-			if (!(0, _orkestrel_terminal.isAnswerPayload)(body)) return new Response(null, { status: 422 });
-			const result = manager.answer(name, body.id, body.value);
-			if (result.success) return new Response(null, { status: 204 });
-			if (result.error === "terminal") return new Response(result.error, { status: 404 });
-			return new Response(result.error, { status: 422 });
+		if (bytes.byteLength > 0 && bytes.byteLength > this.#limit) return new Response(null, { status: 413 });
+		let body;
+		try {
+			body = JSON.parse(new TextDecoder().decode(bytes));
+		} catch {
+			return new Response(null, { status: 400 });
 		}
-	}];
+		if (!(0, _orkestrel_terminal.isAnswerPayload)(body)) return new Response(null, { status: 422 });
+		const result = this.#manager.answer(name, body.id, body.value);
+		if (result.success) return new Response(null, { status: 204 });
+		if (result.error === "terminal") return new Response(result.error, { status: 404 });
+		return new Response(result.error, { status: 422 });
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Build the GET SSE stream and POST answer routes that bridge a terminal manager onto the wire.
+*
+* @remarks
+* Both routes share the configured `:name` path and optional token gate. The GET route replays
+* pending prompts, forwards live pending/expire events, and owns abort/keepalive teardown. The
+* POST route bounds the request body before parsing and maps answer outcomes to HTTP statuses.
+*
+* @param manager - The terminal manager whose endpoints are bridged
+* @param options - Route path, token, keepalive, timer, and body-limit options
+* @returns The GET route followed by the POST route
+*
+* @example
+* ```ts
+* import { createTerminalRoutes } from '@src/server'
+* import { createTerminalManager } from '@orkestrel/terminal'
+*
+* const manager = createTerminalManager()
+* manager.add('assistant')
+* const routes = createTerminalRoutes(manager, { token: 'secret' })
+* ```
+*/
+function createTerminalRoutes(manager, options) {
+	return new TerminalRoutes(manager, options).routes();
 }
 //#endregion
 exports.TERMINAL_KEEPALIVE_MS = TERMINAL_KEEPALIVE_MS;
 exports.TERMINAL_ROUTES_PATH = TERMINAL_ROUTES_PATH;
+exports.TerminalConnection = TerminalConnection;
+exports.TerminalRoutes = TerminalRoutes;
 exports.createTerminalRoutes = createTerminalRoutes;
 
 //# sourceMappingURL=index.cjs.map

package/dist/src/server/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/server/constants.ts","../../../src/server/factories.ts"],"sourcesContent":["// Server-package constants — UPPER_SNAKE, `Object.freeze`d where structural, every member\n// exported (AGENTS §5).\n\n/**\n * The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}\n * mounts its GET (SSE) + POST (answer) routes under.\n */\nexport const TERMINAL_ROUTES_PATH = '/terminals/:name'\n\n/**\n * The default SSE keepalive interval (in milliseconds)\n * {@link import('./factories.js').createTerminalRoutes} arms per open connection — a `: `\n * comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an\n * otherwise-idle stream.\n */\nexport const TERMINAL_KEEPALIVE_MS = 15_000\n","import type { PendingPrompt, TerminalManagerInterface, TimerCancel } from '@orkestrel/terminal'\nimport type {\n\tTerminalRoute,\n\tTerminalRouteContext,\n\tTerminalRoutesOptions,\n\tTerminalToken,\n} from './types.js'\nimport {\n\tdefaultTimer,\n\tHEADER_TOKEN,\n\tisAnswerPayload,\n\tserializeExpire,\n\tserializePending,\n} from '@orkestrel/terminal'\nimport { DEFAULT_BODY_LIMIT, openStream } from '@orkestrel/server'\nimport { TERMINAL_KEEPALIVE_MS, TERMINAL_ROUTES_PATH } from './constants.js'\n\n// Server-package factories — the SSE + POST mount over a `TerminalManagerInterface`\n// (`@orkestrel/terminal`), returned as plain structural `TerminalRoute` records (never\n// `@orkestrel/router`'s own `Route`), so a consumer mounts them against ANY router that accepts\n// the two-arg handler shape. Byte-compatible with `@orkestrel/terminal`'s own `PromptClient` —\n// same GET url streams, same POST url answers, same `{ id, value }` body, same `x-orkestrel-token`\n// header name.\n\n/**\n * Build the two `TerminalManagerInterface` (`@orkestrel/terminal`) routes — a GET SSE stream and\n * a POST answer endpoint, both mounted on the SAME `:name`-templated path — that bridge a manager's\n * endpoints onto the wire, byte-compatible with `PromptClient`.\n *\n * @remarks\n * - **GET (SSE).** Optionally token-gated (`401` on mismatch), `404` when `name` names no\n *   endpoint. Opens a stream, replays every currently-{@link import('@orkestrel/terminal').PendingPrompt}\n *   as a `pending` frame, then live-forwards the manager's own `pending` / `expire` events scoped\n *   to `name`. A `keepalive`-interval `: ` comment ping is armed via the injected `timer` (default\n *   the host `setTimeout`). On the request's `AbortSignal` firing (client disconnect OR server\n *   stop) the keepalive is cancelled, both listeners unsubscribed, and the stream ended — no\n *   `shutdown` frame is sent, so a reconnecting client is never told the endpoint is gone.\n * - **POST (answer).** Same token + `404` checks, then reads the body capped at `options.limit`\n *   bytes (`413` over, `manager.answer` never called — see {@link TerminalRoutesOptions.limit}),\n *   parses the JSON body (`400` on invalid JSON, `422` when it isn't an `{ id, value }`\n *   {@link import('@orkestrel/terminal').isAnswerPayload} shape), and routes it through\n *   `manager.answer` — `204` on success, `404` for `'terminal'`, `422` for `'unknown'` / `'rejected'`.\n *\n * @remarks\n * The `token` option (a string OR a validator function — {@link TerminalToken}) is validated at\n * GET connect, on EVERY POST, and RE-VALIDATED on every keepalive tick of a live SSE stream — a\n * stream whose presented token stops validating is torn down rather than left streaming forever.\n * Concurrent POST answerers race first-write-wins — a late POST for an already-settled prompt\n * returns `422`.\n *\n * @param manager - The `TerminalManagerInterface` (`@orkestrel/terminal`) whose endpoints are bridged\n * @param options - See {@link TerminalRoutesOptions}\n * @returns Exactly two {@link TerminalRoute} records — GET then POST — sharing one path\n *\n * @example\n * ```ts\n * import { createTerminalRoutes } from '@src/server'\n * import { createTerminalManager } from '@orkestrel/terminal'\n *\n * const manager = createTerminalManager()\n * manager.add('assistant')\n * const routes = createTerminalRoutes(manager, { token: 'secret' })\n * // mount `routes` against any router accepting `{ method, path, handler }`\n * ```\n */\nexport function createTerminalRoutes(\n\tmanager: TerminalManagerInterface,\n\toptions?: TerminalRoutesOptions,\n): readonly TerminalRoute[] {\n\tconst path = options?.path ?? TERMINAL_ROUTES_PATH\n\tconst token: TerminalToken | undefined = options?.token\n\tconst keepalive = options?.keepalive ?? TERMINAL_KEEPALIVE_MS\n\tconst timer = options?.timer ?? defaultTimer\n\tconst limit = options?.limit ?? DEFAULT_BODY_LIMIT\n\n\t// Bounded body read — `@orkestrel/server`'s own `readBody` decodes by `Content-Type`\n\t// (`application/json` parses, anything else decodes as text), so a bare answer POST that\n\t// omits `Content-Type` (as this route's own byte-compatible `PromptClient` counterpart does)\n\t// would be decoded as TEXT rather than parsed JSON, changing the existing 400/422 status\n\t// mapping. Reading the body ourselves via the `ReadableStream` reader — capped at `limit`,\n\t// ignoring `Content-Length` entirely so a lying header can never bypass the cap — then\n\t// `JSON.parse`ing the accumulated text preserves that mapping exactly while still bounding\n\t// the read.\n\tasync function readBoundedText(\n\t\trequest: Request,\n\t): Promise<{ readonly ok: true; readonly text: string } | { readonly ok: false }> {\n\t\tconst reader = request.body?.getReader()\n\t\tif (reader === undefined) return { ok: true, text: '' }\n\t\tconst chunks: Uint8Array[] = []\n\t\tlet received = 0\n\t\twhile (true) {\n\t\t\tconst { done, value } = await reader.read()\n\t\t\tif (done) break\n\t\t\treceived += value.byteLength\n\t\t\tif (received > limit) {\n\t\t\t\tawait reader.cancel()\n\t\t\t\treturn { ok: false }\n\t\t\t}\n\t\t\tchunks.push(value)\n\t\t}\n\t\tconst buffer = new Uint8Array(received)\n\t\tlet offset = 0\n\t\tfor (const chunk of chunks) {\n\t\t\tbuffer.set(chunk, offset)\n\t\t\toffset += chunk.byteLength\n\t\t}\n\t\treturn { ok: true, text: new TextDecoder().decode(buffer) }\n\t}\n\n\t// Single validation closure covering all three token shapes ({@link TerminalToken}):\n\t// `undefined` disables the check, a string is compared for equality, and a function is a\n\t// consumer-controlled validator — used at GET connect, on every POST, and re-run on every\n\t// keepalive tick against the connection's captured presented header value, so a token that\n\t// rotates or expires mid-stream tears the stream down instead of streaming forever. A\n\t// validator that THROWS is treated as invalid (fail-closed) at all three call sites — a throw\n\t// escaping the keepalive tick's timer callback would otherwise skip teardown entirely and\n\t// crash the timer host.\n\tfunction valid(presented: string | undefined): boolean {\n\t\tif (token === undefined) return true\n\t\ttry {\n\t\t\treturn typeof token === 'function' ? token(presented) : presented === token\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\tfunction authorized(request: Request): boolean {\n\t\treturn valid(request.headers.get(HEADER_TOKEN) ?? undefined)\n\t}\n\n\tconst get: TerminalRoute = {\n\t\tmethod: 'GET',\n\t\tpath,\n\t\thandler(request: Request, context: TerminalRouteContext): Response {\n\t\t\tif (!authorized(request)) return new Response(null, { status: 401 })\n\t\t\tconst name = context.params.name\n\t\t\tif (manager.terminal(name) === undefined) return new Response(null, { status: 404 })\n\t\t\tconst presented = request.headers.get(HEADER_TOKEN) ?? undefined\n\n\t\t\tconst stream = openStream()\n\t\t\tfor (const prompt of manager.pending(name)) {\n\t\t\t\tconst wire = serializePending(prompt)\n\t\t\t\tstream.write({ event: wire.event, data: wire.data, id: wire.id })\n\t\t\t}\n\n\t\t\t// Shared teardown — the ONE place that cancels the keepalive and detaches all\n\t\t\t// listeners (both manager listeners and the request's `abort` listener), so the\n\t\t\t// abort path and the self-heal path (a stream that closed without the request's\n\t\t\t// `AbortSignal` firing, e.g. a consumer that only cancels its reader) can never\n\t\t\t// drift apart. `cancelKeepalive`/`stream.end`/`removeEventListener` are safe\n\t\t\t// no-ops if already run — teardown itself is idempotent.\n\t\t\tlet cancelKeepalive: TimerCancel = () => {}\n\t\t\tconst teardown = (): void => {\n\t\t\t\tcancelKeepalive()\n\t\t\t\tmanager.emitter.off('pending', pendingHandler)\n\t\t\t\tmanager.emitter.off('expire', expireHandler)\n\t\t\t\trequest.signal.removeEventListener('abort', teardown)\n\t\t\t\tstream.end()\n\t\t\t}\n\n\t\t\tconst pendingHandler = (prompt: PendingPrompt): void => {\n\t\t\t\tif (prompt.to !== name) return\n\t\t\t\tif (stream.closed) {\n\t\t\t\t\tteardown()\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tconst wire = serializePending(prompt)\n\t\t\t\tstream.write({ event: wire.event, data: wire.data, id: wire.id })\n\t\t\t}\n\t\t\tconst expireHandler = (to: string, id: string): void => {\n\t\t\t\tif (to !== name) return\n\t\t\t\tif (stream.closed) {\n\t\t\t\t\tteardown()\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tconst wire = serializeExpire(id)\n\t\t\t\tstream.write({ event: wire.event, data: wire.data, id: wire.id })\n\t\t\t}\n\n\t\t\tmanager.emitter.on('pending', pendingHandler)\n\t\t\tmanager.emitter.on('expire', expireHandler)\n\n\t\t\tcancelKeepalive = timer(function ping(): void {\n\t\t\t\tif (stream.closed) {\n\t\t\t\t\tteardown()\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tif (!valid(presented)) {\n\t\t\t\t\tteardown()\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tstream.comment('')\n\t\t\t\tcancelKeepalive = timer(ping, keepalive)\n\t\t\t}, keepalive)\n\n\t\t\trequest.signal.addEventListener('abort', teardown)\n\n\t\t\treturn stream.response\n\t\t},\n\t}\n\n\tconst post: TerminalRoute = {\n\t\tmethod: 'POST',\n\t\tpath,\n\t\tasync handler(request: Request, context: TerminalRouteContext): Promise<Response> {\n\t\t\tif (!authorized(request)) return new Response(null, { status: 401 })\n\t\t\tconst name = context.params.name\n\t\t\tif (manager.terminal(name) === undefined) return new Response(null, { status: 404 })\n\n\t\t\tconst bounded = await readBoundedText(request)\n\t\t\tif (!bounded.ok) return new Response(null, { status: 413 })\n\n\t\t\tlet body: unknown\n\t\t\ttry {\n\t\t\t\tbody = JSON.parse(bounded.text)\n\t\t\t} catch {\n\t\t\t\treturn new Response(null, { status: 400 })\n\t\t\t}\n\t\t\tif (!isAnswerPayload(body)) return new Response(null, { status: 422 })\n\n\t\t\tconst result = manager.answer(name, body.id, body.value)\n\t\t\tif (result.success) return new Response(null, { status: 204 })\n\t\t\tif (result.error === 'terminal') return new Response(result.error, { status: 404 })\n\t\t\treturn new Response(result.error, { status: 422 })\n\t\t},\n\t}\n\n\treturn [get, post]\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["#manager","#name","#request","#stream","#accepts","#timer","#keepalive","#presented","#destroyHandler","#pendingHandler","#expireHandler","#tickHandler","#destroy","#pending","#expire","#tick","#cancel","#write","#accepted","#manager","#path","#token","#keepalive","#timer","#limit","#accepts","#get","#post","#valid","#handleGet","#handlePost","#authorized"],"sources":["../../../src/server/constants.ts","../../../src/server/routes/TerminalConnection.ts","../../../src/server/routes/TerminalRoutes.ts","../../../src/server/factories.ts"],"sourcesContent":["// Server-package constants — UPPER_SNAKE, `Object.freeze`d where structural, every member\n// exported (AGENTS §5).\n\n/**\n * The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}\n * mounts its GET (SSE) + POST (answer) routes under.\n */\nexport const TERMINAL_ROUTES_PATH = '/terminals/:name'\n\n/**\n * The default SSE keepalive interval (in milliseconds)\n * {@link import('./factories.js').createTerminalRoutes} arms per open connection — a `: `\n * comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an\n * otherwise-idle stream.\n */\nexport const TERMINAL_KEEPALIVE_MS = 15_000\n","import type {\n\tPendingPrompt,\n\tTerminalManagerInterface,\n\tTimerCancel,\n\tTimerHandler,\n\tWireEvent,\n} from '@orkestrel/terminal'\nimport type { StreamInterface } from '@orkestrel/server'\nimport { HEADER_TOKEN, serializeExpire, serializePending } from '@orkestrel/terminal'\n\n/**\n * Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.\n *\n * @example\n * ```ts\n * import { TerminalConnection } from '@orkestrel/tool/server'\n *\n * const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)\n * const response = connection.open()\n * ```\n */\nexport class TerminalConnection {\n\treadonly #manager: TerminalManagerInterface\n\treadonly #name: string\n\treadonly #request: Request\n\treadonly #stream: StreamInterface\n\treadonly #accepts: (presented: string | undefined) => boolean\n\treadonly #timer: TimerHandler\n\treadonly #keepalive: number\n\treadonly #presented: string | undefined\n\t#cancel: TimerCancel | undefined\n\treadonly #destroyHandler: () => void\n\treadonly #pendingHandler: (prompt: PendingPrompt) => void\n\treadonly #expireHandler: (to: string, id: string) => void\n\treadonly #tickHandler: () => void\n\n\t/**\n\t * Create a terminal stream connection.\n\t *\n\t * @param manager - Terminal manager supplying pending prompts and lifecycle events\n\t * @param name - Terminal endpoint streamed by this connection\n\t * @param request - Request whose abort signal owns the connection lifetime\n\t * @param stream - Open SSE stream\n\t * @param accepts - Presented-token validator\n\t * @param timer - Keepalive timer implementation\n\t * @param keepalive - Keepalive interval in milliseconds\n\t */\n\tconstructor(\n\t\tmanager: TerminalManagerInterface,\n\t\tname: string,\n\t\trequest: Request,\n\t\tstream: StreamInterface,\n\t\taccepts: (presented: string | undefined) => boolean,\n\t\ttimer: TimerHandler,\n\t\tkeepalive: number,\n\t) {\n\t\tthis.#manager = manager\n\t\tthis.#name = name\n\t\tthis.#request = request\n\t\tthis.#stream = stream\n\t\tthis.#accepts = accepts\n\t\tthis.#timer = timer\n\t\tthis.#keepalive = keepalive\n\t\tthis.#presented = request.headers.get(HEADER_TOKEN) ?? undefined\n\t\tthis.#destroyHandler = this.#destroy.bind(this)\n\t\tthis.#pendingHandler = this.#pending.bind(this)\n\t\tthis.#expireHandler = this.#expire.bind(this)\n\t\tthis.#tickHandler = this.#tick.bind(this)\n\t}\n\n\t/**\n\t * Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.\n\t *\n\t * @returns The SSE response\n\t */\n\topen(): Response {\n\t\tif (this.#stream.closed || this.#request.signal.aborted) {\n\t\t\tthis.#destroy()\n\t\t\treturn this.#stream.response\n\t\t}\n\t\tif (this.#cancel !== undefined) return this.#stream.response\n\t\tfor (const prompt of this.#manager.pending(this.#name)) {\n\t\t\tthis.#write(serializePending(prompt))\n\t\t}\n\t\tthis.#manager.emitter.on('pending', this.#pendingHandler)\n\t\tthis.#manager.emitter.on('expire', this.#expireHandler)\n\t\tthis.#cancel = this.#timer(this.#tickHandler, this.#keepalive)\n\t\tthis.#request.signal.addEventListener('abort', this.#destroyHandler)\n\t\treturn this.#stream.response\n\t}\n\n\t#write(wire: WireEvent): void {\n\t\tthis.#stream.write({\n\t\t\tevent: wire.event,\n\t\t\tdata: wire.data,\n\t\t\t...(wire.id === undefined ? {} : { id: wire.id }),\n\t\t})\n\t}\n\n\t#pending(prompt: PendingPrompt): void {\n\t\tif (prompt.to !== this.#name) return\n\t\tif (this.#stream.closed) {\n\t\t\tthis.#destroy()\n\t\t\treturn\n\t\t}\n\t\tthis.#write(serializePending(prompt))\n\t}\n\n\t#expire(to: string, id: string): void {\n\t\tif (to !== this.#name) return\n\t\tif (this.#stream.closed) {\n\t\t\tthis.#destroy()\n\t\t\treturn\n\t\t}\n\t\tthis.#write(serializeExpire(id))\n\t}\n\n\t#tick(): void {\n\t\tif (this.#stream.closed || !this.#accepted()) {\n\t\t\tthis.#destroy()\n\t\t\treturn\n\t\t}\n\t\tthis.#stream.comment('')\n\t\tthis.#cancel = this.#timer(this.#tickHandler, this.#keepalive)\n\t}\n\n\t#accepted(): boolean {\n\t\ttry {\n\t\t\treturn this.#accepts(this.#presented)\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\t#destroy(): void {\n\t\tconst cancel = this.#cancel\n\t\tthis.#cancel = undefined\n\t\tcancel?.()\n\t\tthis.#manager.emitter.off('pending', this.#pendingHandler)\n\t\tthis.#manager.emitter.off('expire', this.#expireHandler)\n\t\tthis.#request.signal.removeEventListener('abort', this.#destroyHandler)\n\t\tthis.#stream.end()\n\t}\n}\n","import type { TerminalManagerInterface, TimerHandler } from '@orkestrel/terminal'\nimport type {\n\tTerminalRoute,\n\tTerminalRouteContext,\n\tTerminalRoutesOptions,\n\tTerminalToken,\n} from '../types.js'\nimport { defaultTimer, HEADER_TOKEN, isAnswerPayload } from '@orkestrel/terminal'\nimport {\n\tcollectRequestBody,\n\tContentTooLargeError,\n\tDEFAULT_BODY_LIMIT,\n\topenStream,\n} from '@orkestrel/server'\nimport { TERMINAL_KEEPALIVE_MS, TERMINAL_ROUTES_PATH } from '../constants.js'\nimport { TerminalConnection } from './TerminalConnection.js'\n\n/**\n * Build and serve the terminal manager's GET stream and POST answer routes.\n *\n * @example\n * ```ts\n * import { TerminalRoutes } from '@orkestrel/tool/server'\n *\n * const routes = new TerminalRoutes(manager).routes()\n * ```\n */\nexport class TerminalRoutes {\n\treadonly #manager: TerminalManagerInterface\n\treadonly #path: string\n\treadonly #token: TerminalToken | undefined\n\treadonly #keepalive: number\n\treadonly #timer: TimerHandler\n\treadonly #limit: number\n\treadonly #accepts: (presented: string | undefined) => boolean\n\treadonly #get: TerminalRoute['handler']\n\treadonly #post: TerminalRoute['handler']\n\n\t/**\n\t * Create a terminal route owner.\n\t *\n\t * @param manager - Terminal manager bridged onto HTTP\n\t * @param options - Shared route, authorization, keepalive, timer, and body-limit options\n\t */\n\tconstructor(manager: TerminalManagerInterface, options?: TerminalRoutesOptions) {\n\t\tthis.#manager = manager\n\t\tthis.#path = options?.path ?? TERMINAL_ROUTES_PATH\n\t\tthis.#token = options?.token\n\t\tthis.#keepalive = options?.keepalive ?? TERMINAL_KEEPALIVE_MS\n\t\tthis.#timer = options?.timer ?? defaultTimer\n\t\tconst limit = options?.limit\n\t\tthis.#limit =\n\t\t\tlimit === undefined || !Number.isFinite(limit)\n\t\t\t\t? DEFAULT_BODY_LIMIT\n\t\t\t\t: Math.max(0, Math.floor(limit))\n\t\tthis.#accepts = this.#valid.bind(this)\n\t\tthis.#get = this.#handleGet.bind(this)\n\t\tthis.#post = this.#handlePost.bind(this)\n\t}\n\n\t/**\n\t * Project the bound GET and POST route records.\n\t *\n\t * @returns The GET stream route followed by the POST answer route\n\t */\n\troutes(): readonly TerminalRoute[] {\n\t\treturn [\n\t\t\t{ method: 'GET', path: this.#path, handler: this.#get },\n\t\t\t{ method: 'POST', path: this.#path, handler: this.#post },\n\t\t]\n\t}\n\n\t#valid(presented: string | undefined): boolean {\n\t\tif (this.#token === undefined) return true\n\t\ttry {\n\t\t\treturn typeof this.#token === 'function' ? this.#token(presented) : presented === this.#token\n\t\t} catch {\n\t\t\treturn false\n\t\t}\n\t}\n\n\t#authorized(request: Request): boolean {\n\t\treturn this.#valid(request.headers.get(HEADER_TOKEN) ?? undefined)\n\t}\n\n\t#handleGet(request: Request, context: TerminalRouteContext): Response {\n\t\tif (!this.#authorized(request)) return new Response(null, { status: 401 })\n\t\tconst name = context.params.name\n\t\tif (name === undefined || this.#manager.terminal(name) === undefined) {\n\t\t\treturn new Response(null, { status: 404 })\n\t\t}\n\t\tconst connection = new TerminalConnection(\n\t\t\tthis.#manager,\n\t\t\tname,\n\t\t\trequest,\n\t\t\topenStream(),\n\t\t\tthis.#accepts,\n\t\t\tthis.#timer,\n\t\t\tthis.#keepalive,\n\t\t)\n\t\treturn connection.open()\n\t}\n\n\tasync #handlePost(request: Request, context: TerminalRouteContext): Promise<Response> {\n\t\tif (!this.#authorized(request)) return new Response(null, { status: 401 })\n\t\tconst name = context.params.name\n\t\tif (name === undefined || this.#manager.terminal(name) === undefined) {\n\t\t\treturn new Response(null, { status: 404 })\n\t\t}\n\t\tlet bytes: Uint8Array\n\t\ttry {\n\t\t\tbytes = await collectRequestBody(request, Math.max(1, this.#limit))\n\t\t} catch (error) {\n\t\t\tif (error instanceof ContentTooLargeError) return new Response(null, { status: 413 })\n\t\t\tthrow error\n\t\t}\n\t\tif (bytes.byteLength > 0 && bytes.byteLength > this.#limit) {\n\t\t\treturn new Response(null, { status: 413 })\n\t\t}\n\n\t\tlet body: unknown\n\t\ttry {\n\t\t\tbody = JSON.parse(new TextDecoder().decode(bytes))\n\t\t} catch {\n\t\t\treturn new Response(null, { status: 400 })\n\t\t}\n\t\tif (!isAnswerPayload(body)) return new Response(null, { status: 422 })\n\n\t\tconst result = this.#manager.answer(name, body.id, body.value)\n\t\tif (result.success) return new Response(null, { status: 204 })\n\t\tif (result.error === 'terminal') return new Response(result.error, { status: 404 })\n\t\treturn new Response(result.error, { status: 422 })\n\t}\n}\n","import type { TerminalManagerInterface } from '@orkestrel/terminal'\nimport type { TerminalRoute, TerminalRoutesOptions } from './types.js'\nimport { TerminalRoutes } from './routes/TerminalRoutes.js'\n\n/**\n * Build the GET SSE stream and POST answer routes that bridge a terminal manager onto the wire.\n *\n * @remarks\n * Both routes share the configured `:name` path and optional token gate. The GET route replays\n * pending prompts, forwards live pending/expire events, and owns abort/keepalive teardown. The\n * POST route bounds the request body before parsing and maps answer outcomes to HTTP statuses.\n *\n * @param manager - The terminal manager whose endpoints are bridged\n * @param options - Route path, token, keepalive, timer, and body-limit options\n * @returns The GET route followed by the POST route\n *\n * @example\n * ```ts\n * import { createTerminalRoutes } from '@src/server'\n * import { createTerminalManager } from '@orkestrel/terminal'\n *\n * const manager = createTerminalManager()\n * manager.add('assistant')\n * const routes = createTerminalRoutes(manager, { token: 'secret' })\n * ```\n */\nexport function createTerminalRoutes(\n\tmanager: TerminalManagerInterface,\n\toptions?: TerminalRoutesOptions,\n): readonly TerminalRoute[] {\n\treturn new TerminalRoutes(manager, options).routes()\n}\n"],"mappings":"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"}

package/dist/src/server/index.d.cts

@@ -1,3 +1,167 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './factories.js';
+import { StreamInterface } from '@orkestrel/server';
+import { TerminalManagerInterface } from '@orkestrel/terminal';
+import { TimerHandler } from '@orkestrel/terminal';
+
+/**
+ * Build the GET SSE stream and POST answer routes that bridge a terminal manager onto the wire.
+ *
+ * @remarks
+ * Both routes share the configured `:name` path and optional token gate. The GET route replays
+ * pending prompts, forwards live pending/expire events, and owns abort/keepalive teardown. The
+ * POST route bounds the request body before parsing and maps answer outcomes to HTTP statuses.
+ *
+ * @param manager - The terminal manager whose endpoints are bridged
+ * @param options - Route path, token, keepalive, timer, and body-limit options
+ * @returns The GET route followed by the POST route
+ *
+ * @example
+ * ```ts
+ * import { createTerminalRoutes } from '@src/server'
+ * import { createTerminalManager } from '@orkestrel/terminal'
+ *
+ * const manager = createTerminalManager()
+ * manager.add('assistant')
+ * const routes = createTerminalRoutes(manager, { token: 'secret' })
+ * ```
+ */
+export declare function createTerminalRoutes(manager: TerminalManagerInterface, options?: TerminalRoutesOptions): readonly TerminalRoute[];
+
+/** The HTTP method literal a {@link TerminalRoute} declares — the exact 7-literal union `@orkestrel/router`'s `Method` accepts. */
+export declare type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+/**
+ * The default SSE keepalive interval (in milliseconds)
+ * {@link import('./factories.js').createTerminalRoutes} arms per open connection — a `: `
+ * comment ping a conforming SSE parser ignores, keeping intermediary proxies from timing out an
+ * otherwise-idle stream.
+ */
+export declare const TERMINAL_KEEPALIVE_MS = 15000;
+
+/**
+ * The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}
+ * mounts its GET (SSE) + POST (answer) routes under.
+ */
+export declare const TERMINAL_ROUTES_PATH = "/terminals/:name";
+
+/**
+ * Own one terminal SSE connection's replay, subscriptions, keepalive, and teardown.
+ *
+ * @example
+ * ```ts
+ * import { TerminalConnection } from '@orkestrel/tool/server'
+ *
+ * const connection = new TerminalConnection(manager, name, request, stream, accepts, timer, 15_000)
+ * const response = connection.open()
+ * ```
+ */
+export declare class TerminalConnection {
+    #private;
+    /**
+     * Create a terminal stream connection.
+     *
+     * @param manager - Terminal manager supplying pending prompts and lifecycle events
+     * @param name - Terminal endpoint streamed by this connection
+     * @param request - Request whose abort signal owns the connection lifetime
+     * @param stream - Open SSE stream
+     * @param accepts - Presented-token validator
+     * @param timer - Keepalive timer implementation
+     * @param keepalive - Keepalive interval in milliseconds
+     */
+    constructor(manager: TerminalManagerInterface, name: string, request: Request, stream: StreamInterface, accepts: (presented: string | undefined) => boolean, timer: TimerHandler, keepalive: number);
+    /**
+     * Open the connection by replaying pending prompts, subscribing, and arming keepalive handling.
+     *
+     * @returns The SSE response
+     */
+    open(): Response;
+}
+
+/**
+ * One structural route record {@link import('./factories.js').createTerminalRoutes} returns — a
+ * plain `{ method, path, handler }` shape carrying NO dependency on `@orkestrel/router`'s own
+ * `Route` type, so a consumer mounts it against any router that accepts a two-arg
+ * `(request, context) => Response | Promise<Response>` handler keyed by `method` + `path`.
+ */
+export declare interface TerminalRoute {
+    readonly method: Method;
+    readonly path: string;
+    readonly handler: (request: Request, context: TerminalRouteContext) => Response | Promise<Response>;
+}
+
+/**
+ * The minimal route-dispatch context a {@link TerminalRoute} handler reads — exactly the frozen,
+ * URL-decoded `:name` path param slice a router hands a matched handler.
+ */
+export declare interface TerminalRouteContext {
+    readonly params: Readonly<Record<string, string>>;
+}
+
+/**
+ * Build and serve the terminal manager's GET stream and POST answer routes.
+ *
+ * @example
+ * ```ts
+ * import { TerminalRoutes } from '@orkestrel/tool/server'
+ *
+ * const routes = new TerminalRoutes(manager).routes()
+ * ```
+ */
+export declare class TerminalRoutes {
+    #private;
+    /**
+     * Create a terminal route owner.
+     *
+     * @param manager - Terminal manager bridged onto HTTP
+     * @param options - Shared route, authorization, keepalive, timer, and body-limit options
+     */
+    constructor(manager: TerminalManagerInterface, options?: TerminalRoutesOptions);
+    /**
+     * Project the bound GET and POST route records.
+     *
+     * @returns The GET stream route followed by the POST answer route
+     */
+    routes(): readonly TerminalRoute[];
+}
+
+/**
+ * Options for {@link import('./factories.js').createTerminalRoutes}.
+ *
+ * @remarks
+ * - `path` — the shared `:name`-templated path both the GET (SSE) and POST (answer) routes
+ *   mount under; defaults to {@link import('./constants.js').TERMINAL_ROUTES_PATH}.
+ * - `token` — a {@link TerminalToken}: a string is compared for equality against the
+ *   `x-orkestrel-token` header; a function receives the header's value (`undefined` when absent)
+ *   and returns whether it validates, letting the consumer roll/expire tokens out-of-band.
+ *   Validated at GET connect, on EVERY POST, and RE-VALIDATED on every keepalive tick of a live
+ *   SSE stream — a stream whose presented token stops validating (rotated, expired, revoked) is
+ *   torn down (the abort/self-heal teardown path, no `shutdown` frame) rather than left open
+ *   forever; the client reconnects and re-authenticates. Omitted ⇒ no auth check. Because
+ *   re-validation only happens on the keepalive tick, the revocation window equals the keepalive
+ *   interval — a token rejected/expired between ticks keeps streaming until the next one. A
+ *   validator function that THROWS is treated as rejection (fail-closed) at every call site.
+ * - `keepalive` — the SSE comment-ping interval in milliseconds; defaults to
+ *   {@link import('./constants.js').TERMINAL_KEEPALIVE_MS}.
+ * - `timer` — the injected {@link TimerHandler} driving the keepalive interval (default the host
+ *   `setTimeout`/`clearTimeout`), so a test drives the keepalive deterministically.
+ * - `limit` — the maximum POST answer body size in bytes, streamed and enforced BEFORE JSON
+ *   parsing (ignoring any `Content-Length` header, so a lying header can never bypass the cap);
+ *   a body exceeding it is rejected `413` and `manager.answer` is never called. Defaults to
+ *   `@orkestrel/server`'s own `DEFAULT_BODY_LIMIT` (1 MiB).
+ */
+export declare interface TerminalRoutesOptions {
+    readonly path?: string;
+    readonly token?: TerminalToken;
+    readonly keepalive?: number;
+    readonly timer?: TimerHandler;
+    readonly limit?: number;
+}
+
+/**
+ * The `token` gate a {@link TerminalRoutesOptions} may configure — a plain string compared for
+ * equality against the `x-orkestrel-token` header, OR a validator function the consumer fully
+ * controls, enabling expiry/rotation (a JWT `exp` check, a revocation-list lookup, anything
+ * time-varying) that a fixed string cannot express. `undefined` disables the auth check entirely.
+ */
+export declare type TerminalToken = string | ((value: string | undefined) => boolean);
+
+export { }