@orkestrel/tool 0.0.1 → 0.0.2

package/dist/src/server/index.cjs

@@ -0,0 +1,202 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_terminal = require("@orkestrel/terminal");
+let _orkestrel_server = require("@orkestrel/server");
+//#region src/server/constants.ts
+/**
+* The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}
+* mounts its GET (SSE) + POST (answer) routes under.
+*/
+var TERMINAL_ROUTES_PATH = "/terminals/:name";
+/**
+* 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.
+*/
+var TERMINAL_KEEPALIVE_MS = 15e3;
+//#endregion
+//#region src/server/factories.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
+*
+* @example
+* ```ts
+* import { createTerminalRoutes } from '@src/server'
+* import { createTerminalManager } from '@orkestrel/terminal'
+*
+* const manager = createTerminalManager()
+* manager.add('assistant')
+* const routes = createTerminalRoutes(manager, { token: 'secret' })
+* // mount `routes` against any router accepting `{ method, path, handler }`
+* ```
+*/
+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);
+		}
+		const buffer = new Uint8Array(received);
+		let offset = 0;
+		for (const chunk of chunks) {
+			buffer.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return {
+			ok: true,
+			text: new TextDecoder().decode(buffer)
+		};
+	}
+	function valid(presented) {
+		if (token === void 0) return true;
+		try {
+			return typeof token === "function" ? token(presented) : presented === token;
+		} catch {
+			return false;
+		}
+	}
+	function authorized(request) {
+		return 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;
+		}
+	}, {
+		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 });
+		}
+	}];
+}
+//#endregion
+exports.TERMINAL_KEEPALIVE_MS = TERMINAL_KEEPALIVE_MS;
+exports.TERMINAL_ROUTES_PATH = TERMINAL_ROUTES_PATH;
+exports.createTerminalRoutes = createTerminalRoutes;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './constants.js';
+export * from './factories.js';

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

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './constants.js';
+export * from './factories.js';

package/dist/src/server/index.js

@@ -0,0 +1,199 @@
+import { HEADER_TOKEN, defaultTimer, isAnswerPayload, serializeExpire, serializePending } from "@orkestrel/terminal";
+import { DEFAULT_BODY_LIMIT, openStream } from "@orkestrel/server";
+//#region src/server/constants.ts
+/**
+* The default `:name`-templated path {@link import('./factories.js').createTerminalRoutes}
+* mounts its GET (SSE) + POST (answer) routes under.
+*/
+var TERMINAL_ROUTES_PATH = "/terminals/:name";
+/**
+* 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.
+*/
+var TERMINAL_KEEPALIVE_MS = 15e3;
+//#endregion
+//#region src/server/factories.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
+*
+* @example
+* ```ts
+* import { createTerminalRoutes } from '@src/server'
+* import { createTerminalManager } from '@orkestrel/terminal'
+*
+* const manager = createTerminalManager()
+* manager.add('assistant')
+* const routes = createTerminalRoutes(manager, { token: 'secret' })
+* // mount `routes` against any router accepting `{ method, path, handler }`
+* ```
+*/
+function createTerminalRoutes(manager, options) {
+	const path = options?.path ?? "/terminals/:name";
+	const token = options?.token;
+	const keepalive = options?.keepalive ?? 15e3;
+	const timer = options?.timer ?? defaultTimer;
+	const limit = options?.limit ?? 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);
+		}
+		const buffer = new Uint8Array(received);
+		let offset = 0;
+		for (const chunk of chunks) {
+			buffer.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return {
+			ok: true,
+			text: new TextDecoder().decode(buffer)
+		};
+	}
+	function valid(presented) {
+		if (token === void 0) return true;
+		try {
+			return typeof token === "function" ? token(presented) : presented === token;
+		} catch {
+			return false;
+		}
+	}
+	function authorized(request) {
+		return valid(request.headers.get(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(HEADER_TOKEN) ?? void 0;
+			const stream = openStream();
+			for (const prompt of manager.pending(name)) {
+				const wire = 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 = 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 = 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;
+		}
+	}, {
+		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 (!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 });
+		}
+	}];
+}
+//#endregion
+export { TERMINAL_KEEPALIVE_MS, TERMINAL_ROUTES_PATH, createTerminalRoutes };
+
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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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"}

package/dist/src/server/types.d.ts

@@ -0,0 +1,60 @@
+import { TimerHandler } from '@orkestrel/terminal';
+/** The HTTP method literal a {@link TerminalRoute} declares — the exact 7-literal union `@orkestrel/router`'s `Method` accepts. */
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * 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 interface TerminalRouteContext {
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * 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 interface TerminalRoute {
+    readonly method: Method;
+    readonly path: string;
+    readonly handler: (request: Request, context: TerminalRouteContext) => Response | Promise<Response>;
+}
+/**
+ * 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 type TerminalToken = string | ((value: string | undefined) => boolean);
+/**
+ * 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 interface TerminalRoutesOptions {
+    readonly path?: string;
+    readonly token?: TerminalToken;
+    readonly keepalive?: number;
+    readonly timer?: TimerHandler;
+    readonly limit?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/tool",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Concrete LLM-callable tools for the @orkestrel line — workflow authoring, workspace editing, and sub-agent delegation, over the agent tool runtime, with pluggable stores. Part of the @orkestrel line.",
 	"keywords": [
 		"agent",
@@ -37,6 +37,16 @@
 				"default": "./dist/src/core/index.cjs"
 			}
 		},
+		"./server": {
+			"import": {
+				"types": "./dist/src/server/index.d.ts",
+				"default": "./dist/src/server/index.js"
+			},
+			"require": {
+				"types": "./dist/src/server/index.d.cts",
+				"default": "./dist/src/server/index.cjs"
+			}
+		},
 		"./package.json": "./package.json"
 	},
 	"publishConfig": {
@@ -48,37 +58,42 @@
 		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
 		"lint": "oxlint --config .oxlintrc.json --fix .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
-		"check:src": "npm run check:src:core",
+		"check:src": "npm run check:src:core && npm run check:src:server",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
+		"check:src:server": "tsc --noEmit -p configs/src/tsconfig.server.json",
 		"format": "oxfmt --config .oxfmtrc.json --write .",
 		"format:check": "oxfmt --config .oxfmtrc.json --check .",
 		"lint:check": "oxlint --config .oxlintrc.json .",
 		"test": "npm run test:src && npm run test:guides",
-		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core --project src:server",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:src:server": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
 		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
 		"build": "npm run clean && npm run build:src",
-		"build:src": "npm run build:src:core",
+		"build:src": "npm run build:src:core && npm run build:src:server",
 		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"build:src:server": "vite build --config configs/src/vite.server.config.ts && npm run copy dist/src/server/index.d.ts dist/src/server/index.d.cts",
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"dependencies": {
-		"@orkestrel/agent": "^0.0.4",
-		"@orkestrel/contract": "^0.0.1",
-		"@orkestrel/workflow": "^0.0.4"
+		"@orkestrel/agent": "^0.0.5",
+		"@orkestrel/contract": "^0.0.2",
+		"@orkestrel/server": "^0.0.5",
+		"@orkestrel/terminal": "^0.0.2",
+		"@orkestrel/workflow": "^0.0.5"
 	},
 	"devDependencies": {
-		"@microsoft/api-extractor": "^7.58.9",
-		"@orkestrel/guide": "^0.0.1",
+		"@microsoft/api-extractor": "^7.58.11",
+		"@orkestrel/guide": "^0.0.2",
 		"@types/node": "^26.1.1",
-		"oxfmt": "^0.58.0",
-		"oxlint": "^1.73.0",
+		"oxfmt": "^0.59.0",
+		"oxlint": "^1.74.0",
 		"typescript": "^6.0.3",
-		"vite": "^8.1.4",
+		"vite": "^8.1.5",
 		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=24"
+		"node": ">=22"
 	}
 }