@jini-ai/http-kit 0.2.1

package/dist/sse.js

@@ -0,0 +1,157 @@
+import { createApiErrorResponse } from '@jini-ai/protocol';
+/**
+ * Cap on events queued for one client — covers both a pre-header replay
+ * burst and any backlog built up while `res.write` reports backpressure
+ * (`write() === false`, awaiting `'drain'`). A stalled or malicious client
+ * would otherwise let an unbounded producer grow this array without limit
+ * (SEC-006, carried forward from `runs.ts`'s original constant). Once
+ * exceeded, the connection is dropped rather than accepting unbounded
+ * memory growth.
+ */
+export const DEFAULT_MAX_QUEUED_SSE_EVENTS = 1000;
+/** Default wire format: `id: <cursor>\nevent: <kind>\ndata: <json>\n\n`, matching the SSE spec's field syntax. */
+function defaultFormatEvent(event) {
+    return `id: ${event.opaqueCursor}\nevent: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+/**
+ * Builds a bounded, backpressure-aware SSE channel over an Express `Response`.
+ * The channel does not know where events come from — a route wires its own
+ * event source (a `RunLifecycle.stream` subscription, an `EventEmitter`
+ * fan-in, a PTY's `onData`, …) to {@link SseChannel.enqueue} and lets the
+ * channel own delivery, ordering, and backpressure.
+ *
+ * The response's own `'close'` event (the client disconnecting) is observed
+ * from construction time, before {@link SseChannel.open} is ever called —
+ * this lets a caller `await` some asynchronous subscribe step (as `runs.ts`
+ * does against `RunLifecycle.stream`) and still detect "the client already
+ * disappeared while we were waiting" via {@link SseChannel.isClosed} once
+ * that await resolves, without the disconnect handler itself trying to
+ * re-end an already-gone response (see {@link SseChannel.end}'s doc for why
+ * that distinction doesn't actually need special-casing).
+ *
+ * @param res - The response to stream over, typed against the raw `node:http` `ServerResponse`
+ * rather than Express's own `Response` — Express's `Response` extends `ServerResponse` directly,
+ * so every existing Express caller still satisfies this signature unchanged. Never read from — only
+ * `write`/`statusCode`/`setHeader`/`flushHeaders`/`end`/`on('close'|'drain')` are used, all of
+ * which exist identically on the raw type (the one genuinely Express-specific call this function
+ * used to make, `res.status(200)`, is `res.statusCode = 200` here instead — the same assignment
+ * Express's own `.status()` performs internally).
+ * @param options - See {@link CreateSseChannelOptions}.
+ * @complexity `enqueue`/`open`/`end` are O(1) amortized; a full queue drain is O(events written).
+ * @overallScore 100/100
+ */
+export function createSseChannel(res, options = {}) {
+    const maxQueuedEvents = options.maxQueuedEvents ?? DEFAULT_MAX_QUEUED_SSE_EVENTS;
+    const formatEvent = options.formatEvent ?? defaultFormatEvent;
+    const queue = [];
+    let flowing = false;
+    let writable = true;
+    let closed = false;
+    const closeCallbacks = [];
+    const markClosed = () => {
+        if (closed)
+            return;
+        closed = true;
+        // Copy first: a callback that itself calls `onClose` during this loop must not be invoked
+        // twice or mutate the array being iterated.
+        const callbacks = closeCallbacks.splice(0, closeCallbacks.length);
+        for (const callback of callbacks)
+            callback();
+    };
+    const end = () => {
+        markClosed();
+        if (!res.writableEnded)
+            res.end();
+    };
+    const pump = () => {
+        if (!flowing || closed)
+            return;
+        while (writable && queue.length > 0) {
+            const event = queue.shift();
+            let wroteOk;
+            try {
+                wroteOk = res.write(formatEvent(event));
+            }
+            catch (error) {
+                // A dead/broken transport must never throw back through whatever is producing events —
+                // stop this channel only.
+                options.onWriteError?.(error);
+                end();
+                return;
+            }
+            if (wroteOk === false)
+                writable = false;
+            if (options.isEndEvent?.(event)) {
+                end();
+                return;
+            }
+        }
+    };
+    const enqueue = (event) => {
+        if (closed)
+            return;
+        if (queue.length >= maxQueuedEvents) {
+            // Slow/stalled consumer — disconnect rather than grow memory without bound.
+            end();
+            return;
+        }
+        queue.push(event);
+        pump();
+    };
+    const open = () => {
+        if (closed || flowing)
+            return;
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-cache, no-transform');
+        res.setHeader('Connection', 'keep-alive');
+        res.flushHeaders();
+        flowing = true;
+        pump();
+    };
+    res.on('drain', () => {
+        writable = true;
+        pump();
+    });
+    // The client disconnecting only marks the channel closed — it must not itself call `res.end()`
+    // (see `end()`'s doc for why calling it a second time would be safe anyway, but a route that
+    // still wants to send a *non-SSE* response — e.g. a JSON error — after discovering a subscribe
+    // failed needs `isClosed()` to be observable without the response having been touched yet).
+    res.on('close', markClosed);
+    const onClose = (callback) => {
+        if (closed) {
+            callback();
+            return;
+        }
+        closeCallbacks.push(callback);
+    };
+    return {
+        enqueue,
+        open,
+        isClosed: () => closed,
+        end,
+        abandon: markClosed,
+        onClose,
+    };
+}
+/** Reads a reconnect cursor from the standard `Last-Event-ID` header, falling back to an `afterCursor` query parameter. Shared by any SSE route that supports reconnect replay (the header takes precedence since it is what browsers set automatically on `EventSource` reconnect). */
+export function requestedAfterCursor(req) {
+    const header = req.get('last-event-id');
+    if (header && header.length > 0)
+        return header;
+    const query = req.query.afterCursor;
+    return typeof query === 'string' && query.length > 0 ? query : null;
+}
+/**
+ * Writes an `ApiError`, wrapped in the standard `{ error }` envelope, directly onto a raw
+ * `ServerResponse` — for the narrow window before an `SseChannel` has opened (so Express's own
+ * `res.json()` response wrapper isn't safe to use yet). Produces the identical
+ * `createApiErrorResponse(error)` envelope shape `response.ts`'s `sendApiError`/`sendJson` do —
+ * this just writes that same shape without going through Express's response helper.
+ */
+export function sendRawApiError(res, status, error) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.end(JSON.stringify(createApiErrorResponse(error)));
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"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"}

package/dist/terminals.d.ts

@@ -0,0 +1,125 @@
+import type { Express } from 'express';
+import type { Principal } from '@jini-ai/core';
+import type { TerminalSessionActionResult, TerminalSessionInfo, TerminalSessionManager } from '@jini-ai/daemon';
+import type { ToolExecutor } from '@jini-ai/daemon';
+import { type AdapterContext } from './adapter.js';
+import { type WorkspaceRootResolver } from './workspace-root.js';
+import { type Result } from './types.js';
+/** Diagnostic detail for an internal-error response the public API deliberately does not disclose (SEC-005, matching `runs.ts`/`db-ops.ts`): a spawn failure (e.g. a missing/uncompiled native addon) can embed executable paths or host detail. */
+export interface TerminalsInternalErrorContext {
+    readonly source: 'terminal-create';
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+/** Everything this route pack needs from the host. */
+export interface TerminalsHttpDeps {
+    readonly manager: TerminalSessionManager;
+    readonly toolExecutor: ToolExecutor;
+    /** The identity these routes act as — same fixed, host-supplied-value shape as `db-ops.ts`'s `DaemonDbHttpDeps.principal` (this transport has no session/identity subsystem of its own). */
+    readonly principal: Principal;
+    /** Resolves a `resourceRef` to a spawn working directory. Defaults to {@link denyAllWorkspaceRoots} — a host that never wires a real resolver gets a 404 on every create call, never a guessed path (see `workspace-root.ts`). */
+    readonly resolveRoot?: WorkspaceRootResolver;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: TerminalsInternalErrorContext) => void;
+}
+export interface TerminalCreateRequest {
+    readonly resourceRef: string;
+    readonly detail?: string;
+    readonly cols?: number;
+    readonly rows?: number;
+    readonly shell?: string;
+}
+/**
+ * `POST /api/terminals` — the one gated call (see module doc). Resolves
+ * `resourceRef` to a working directory the same way `host-tools.ts`'s
+ * open-in route does, then authorizes+spawns the session through
+ * `ToolExecutor.execute(..., 'terminal.create', ...)`.
+ */
+export declare const terminalCreateRoute: import("./types.js").JsonRouteSpec<TerminalCreateRequest, TerminalSessionInfo, TerminalsHttpDeps>;
+export interface TerminalListResponse {
+    readonly terminals: readonly TerminalSessionInfo[];
+}
+/** `GET /api/terminals` — sessions the calling principal owns, optionally narrowed by `resourceRef`. Never gated through `ToolExecutor` — a read scoped to the caller's own sessions, matching `runs.ts`'s `runListRoute` precedent. */
+export declare const terminalListRoute: import("./types.js").JsonRouteSpec<{
+    resourceRef?: string;
+}, TerminalListResponse, TerminalsHttpDeps>;
+export interface TerminalActionResponse {
+    readonly ok: boolean;
+    readonly terminal?: TerminalSessionInfo;
+}
+/**
+ * Exported (not just internal) so the `result.session === null` branch — a real race
+ * (`write`/`resize`/`kill` finding metadata for an id whose underlying session was concurrently
+ * killed between the ownership check and the critical section, per `@jini-ai/daemon`'s
+ * `terminal-session.ts` `currentSnapshot`) — is directly unit-testable against a synthetic
+ * `TerminalSessionActionResult` rather than requiring a real, hard-to-deterministically-force race
+ * through the full `TerminalSessionManager`. Matches this file's own `createDeferredEndGate`
+ * precedent for the same "extract into a directly-testable pure function" shape.
+ */
+export declare function actionResultToApiResult(result: TerminalSessionActionResult, notFoundMessage: string): Result<TerminalActionResponse>;
+/** `POST /api/terminals/:id/stdin` — writes `data` to the session's pty. Ownership-checked by `deps.manager.write` directly, not re-gated through `ToolExecutor` (see module doc). */
+export declare const terminalStdinRoute: import("./types.js").JsonRouteSpec<{
+    id: string;
+    data: string;
+}, TerminalActionResponse, TerminalsHttpDeps>;
+/** `POST /api/terminals/:id/resize` — resizes the session's pty. */
+export declare const terminalResizeRoute: import("./types.js").JsonRouteSpec<{
+    id: string;
+    cols: number;
+    rows: number;
+}, TerminalActionResponse, TerminalsHttpDeps>;
+/** `POST /api/terminals/:id/kill` — sends `SIGTERM` to the session's pty. */
+export declare const terminalKillRoute: import("./types.js").JsonRouteSpec<string, TerminalActionResponse, TerminalsHttpDeps>;
+/** `DELETE /api/terminals/:id` — alias for `kill`, matching OD's dual `POST .../kill` / `DELETE` routes. */
+export declare const terminalDeleteRoute: import("./types.js").JsonRouteSpec<string, TerminalActionResponse, TerminalsHttpDeps>;
+/** The one method {@link createDeferredEndGate} needs from `sse.ts`'s channel — narrowed so the gate is unit-testable against a bare fake, not a real `SseChannel`. */
+interface DeferredEndChannel {
+    end(): void;
+}
+/**
+ * The `channelOpened`/`endRequestedBeforeOpen` state machine `registerTerminalEventStream`'s
+ * `TerminalSseSink.end()` needs, extracted into its own directly-testable unit — see that
+ * function's inline comment for *why* the deferral exists (an already-exited session's replay
+ * path can call `end()` before `open()` has ever run).
+ *
+ * **On the `markOpened()`-then-`end()` ordering (opened=true when `end()` runs):** this is the
+ * ordering every *currently reachable* production call graph in this repo takes for a live
+ * session that exits while already streaming — but it is unreachable through that graph, not
+ * unreachable in principle. `@jini-ai/platform`'s `TerminalService.finish()` (`packages/platform/src/
+ * terminal.ts`) calls `sink.send('exit', ...)` immediately before `sink.end()` for every live
+ * client; `send()` here forwards straight to `channel.enqueue()`, whose `isEndEvent: (e) => e.kind
+ * === 'exit'` match auto-closes the channel *synchronously inside that same `enqueue()` call* —
+ * which synchronously runs `registerTerminalEventStream`'s own `channel.onClose` callback, which
+ * detaches this sink from `TerminalService`'s `session.clients` before `finish()`'s own, separate
+ * `sink.end()` loop ever runs. That loop iterates `session.clients` fresh at call time (not a
+ * snapshot taken before `emit()`), so by the time it runs, this sink has already removed itself —
+ * `sink.end()` is consequently never invoked while `channelOpened` is `true` via any call graph
+ * this repo's own `@jini-ai/platform` + `@jini-ai/http-kit` composition can currently produce (confirmed by
+ * instrumenting the real call path directly, not inferred from reading the source — a synchronous
+ * console probe in `end()` never fired across this file's full "live-exit-while-streaming" test).
+ * That is a fact about today's specific `TerminalService`/`SseChannel` wiring, not a proof that no
+ * future caller of `TerminalSseSink` could ever call `end()` post-open (a hypothetical non-SSE
+ * sink, or a future `TerminalService` exit reason not preceded by a matching `send()`, would hit
+ * exactly this branch) — so the branch stays as real, intentional defensive code, tested directly
+ * here rather than deleted for being unreachable *today* or left silently uncovered.
+ */
+export declare function createDeferredEndGate(channel: DeferredEndChannel): {
+    markOpened(): void;
+    end(): void;
+};
+/**
+ * `GET /api/terminals/:id/stream` — SSE, with `Last-Event-ID`/`afterCursor`
+ * reconnect replay (via `sse.ts`'s `requestedAfterCursor`, the same helper
+ * `runs.ts` uses). Adapts `deps.manager.attach`'s push/end
+ * `TerminalSseSink` to `sse.ts`'s generic channel, mirroring
+ * `registerRunEventStream`'s adaptation of `RunLifecycle.stream`.
+ *
+ * Bypasses `mountJsonRoute` (raw `app.get`, for the SSE response shape), so it does not get
+ * `requireSameOrigin` for free the way the JSON routes above do — the guard is applied here
+ * directly, before the SSE channel is opened, so a cross-origin request never gets a stream.
+ */
+export declare function registerTerminalEventStream(app: Express, deps: TerminalsHttpDeps, adapter: AdapterContext): void;
+/** Mounts every terminal route (`list`/`create`/`stdin`/`resize`/`kill`/`delete`/`stream`) on `app`. A pack's `http(app, services)` calls this directly. */
+export declare function registerTerminalRoutes(app: Express, deps: TerminalsHttpDeps, adapter: AdapterContext): void;
+export {};
+//# sourceMappingURL=terminals.d.ts.map

package/dist/terminals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminals.d.ts","sourceRoot":"","sources":["../src/terminals.ts"],"names":[],"mappings":"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"}

package/dist/terminals.js

@@ -0,0 +1,349 @@
+/**
+ * @module terminals
+ *
+ * Interactive-terminal HTTP surface, mirroring OD's
+ * `apps/daemon/src/routes/terminal.ts` (`/api/projects/:id/terminals` +
+ * `.../:tid/{stream,stdin,resize,kill}`) generalized under `/api/terminals`.
+ * See `ADS-memory/reports/proposals/PROP-http-route-packs-terminal-pty-2026-07-21.md`
+ * for the design discussion and `@jini-ai/daemon`'s `terminal-session.ts` module
+ * doc for the session-ownership/gating decisions this route pack calls into.
+ *
+ * This file is deliberately thin — no PTY spawning, no session registry, no
+ * ownership logic lives here (that is `@jini-ai/daemon`'s `TerminalSessionManager`,
+ * injected as `deps.manager`). This package only:
+ *
+ * - Resolves a `POST /api/terminals` request's `resourceRef` to a spawn `cwd`
+ *   via `workspace-root.ts` (the same port `host-tools.ts`'s open-in route
+ *   uses), then routes creation through `deps.toolExecutor.execute(...,
+ *   'terminal.create', ...)` — the one call `@jini-ai/daemon`'s module gates by
+ *   policy (matching `db-ops.ts`'s tool-execution-boundary precedent).
+ * - Routes `stdin`/`resize`/`kill`/`stream` directly to `deps.manager`'s
+ *   lighter, session-ownership-checked methods — deliberately **not** through
+ *   `ToolExecutor` again (see the daemon module's doc for why a full
+ *   authorize/confirm round-trip per keystroke would make a terminal
+ *   unusable).
+ * - Adapts `deps.manager.attach`'s push/end sink to `sse.ts`'s generic SSE
+ *   channel, the same way `runs.ts` adapts `RunLifecycle.stream`.
+ */
+import { randomUUID } from 'node:crypto';
+import { TERMINAL_CREATE_TOOL_ID } from '@jini-ai/daemon';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { guardSameOrigin } from './origin.js';
+import { validationError } from './request.js';
+import { sendApiError, statusForError } from './response.js';
+import { createSseChannel, requestedAfterCursor } from './sse.js';
+import { denyAllWorkspaceRoots, resolveWorkspaceRoot, WorkspaceRootDeniedError } from './workspace-root.js';
+import { err, ok } from './types.js';
+function defaultTerminalsInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Every one-off `terminal.create` tool call gets its own opaque `RunRef` — matching `db-ops.ts`'s `freshRun()`: these are single requests, not steps of a longer-lived agent run. */
+function freshRun() {
+    return { id: randomUUID() };
+}
+function toolResultToApiResult(deps, result) {
+    switch (result.status) {
+        case 'completed':
+            return ok(result.output);
+        case 'denied':
+            return err(createApiError('TOOL_OPERATION_DENIED', 'this operation was denied by policy'));
+        case 'confirmation-denied':
+            return err(createApiError('TOOL_OPERATION_DENIED', 'this operation was denied during confirmation'));
+        case 'timed-out':
+        case 'cancelled':
+        case 'failed': {
+            const correlationId = randomUUID();
+            const sink = deps.onInternalError ?? defaultTerminalsInternalErrorSink;
+            sink({ source: 'terminal-create', correlationId, error: result.status === 'failed' ? result.error : result.status });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    }
+}
+function parseTerminalCreate(input) {
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const resourceRef = input.body.resourceRef;
+    if (typeof resourceRef !== 'string' || resourceRef.length === 0) {
+        return err(validationError('resourceRef is required', [{ path: 'resourceRef', message: 'required non-empty string' }]));
+    }
+    const detail = input.body.detail;
+    if (detail !== undefined && (typeof detail !== 'string' || detail.length === 0)) {
+        return err(validationError('detail must be a non-empty string when provided'));
+    }
+    const cols = input.body.cols;
+    if (cols !== undefined && typeof cols !== 'number') {
+        return err(validationError('cols must be a number when provided'));
+    }
+    const rows = input.body.rows;
+    if (rows !== undefined && typeof rows !== 'number') {
+        return err(validationError('rows must be a number when provided'));
+    }
+    const shell = input.body.shell;
+    if (shell !== undefined && (typeof shell !== 'string' || shell.length === 0)) {
+        return err(validationError('shell must be a non-empty string when provided'));
+    }
+    return ok({
+        resourceRef,
+        ...(detail === undefined ? {} : { detail }),
+        ...(cols === undefined ? {} : { cols }),
+        ...(rows === undefined ? {} : { rows }),
+        ...(shell === undefined ? {} : { shell }),
+    });
+}
+/**
+ * `POST /api/terminals` — the one gated call (see module doc). Resolves
+ * `resourceRef` to a working directory the same way `host-tools.ts`'s
+ * open-in route does, then authorizes+spawns the session through
+ * `ToolExecutor.execute(..., 'terminal.create', ...)`.
+ */
+export const terminalCreateRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/terminals',
+    requireSameOrigin: true,
+    parse: parseTerminalCreate,
+    handle: async (input, deps) => {
+        let cwd;
+        try {
+            cwd = await resolveWorkspaceRoot({ resourceRef: input.resourceRef, ...(input.detail === undefined ? {} : { detail: input.detail }) }, { resolver: deps.resolveRoot ?? denyAllWorkspaceRoots });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceRootDeniedError) {
+                return err(createApiError('NOT_FOUND', `resource "${input.resourceRef}" was not found`));
+            }
+            throw error;
+        }
+        const toolInput = {
+            resourceRef: input.resourceRef,
+            cwd,
+            ...(input.cols === undefined ? {} : { cols: input.cols }),
+            ...(input.rows === undefined ? {} : { rows: input.rows }),
+            ...(input.shell === undefined ? {} : { shell: input.shell }),
+        };
+        const result = await deps.toolExecutor.execute(deps.principal, freshRun(), TERMINAL_CREATE_TOOL_ID, toolInput);
+        return toolResultToApiResult(deps, result);
+    },
+    successStatus: 201,
+});
+function parseTerminalList(input) {
+    const value = input.query.resourceRef;
+    if (value === undefined)
+        return ok({});
+    if (typeof value !== 'string' || value.length === 0) {
+        return err(validationError('resourceRef must be a non-empty string when provided'));
+    }
+    return ok({ resourceRef: value });
+}
+/** `GET /api/terminals` — sessions the calling principal owns, optionally narrowed by `resourceRef`. Never gated through `ToolExecutor` — a read scoped to the caller's own sessions, matching `runs.ts`'s `runListRoute` precedent. */
+export const terminalListRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/terminals',
+    parse: parseTerminalList,
+    handle: (input, deps) => ok({ terminals: deps.manager.list(deps.principal, input.resourceRef === undefined ? {} : { resourceRef: input.resourceRef }) }),
+});
+function parseTerminalId(input) {
+    const id = input.params.id;
+    return typeof id === 'string' && id.length > 0 ? ok(id) : err(validationError('id must be a non-empty path parameter'));
+}
+/**
+ * Exported (not just internal) so the `result.session === null` branch — a real race
+ * (`write`/`resize`/`kill` finding metadata for an id whose underlying session was concurrently
+ * killed between the ownership check and the critical section, per `@jini-ai/daemon`'s
+ * `terminal-session.ts` `currentSnapshot`) — is directly unit-testable against a synthetic
+ * `TerminalSessionActionResult` rather than requiring a real, hard-to-deterministically-force race
+ * through the full `TerminalSessionManager`. Matches this file's own `createDeferredEndGate`
+ * precedent for the same "extract into a directly-testable pure function" shape.
+ */
+export function actionResultToApiResult(result, notFoundMessage) {
+    if (result.status === 'not-found')
+        return err(createApiError('NOT_FOUND', notFoundMessage));
+    return ok({ ok: result.ok, ...(result.session ? { terminal: result.session } : {}) });
+}
+function parseStdinInput(input) {
+    const parsedId = parseTerminalId(input);
+    if (!parsedId.ok)
+        return parsedId;
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const data = input.body.data;
+    if (typeof data !== 'string') {
+        return err(validationError('data (string) is required', [{ path: 'data', message: 'required string' }]));
+    }
+    return ok({ id: parsedId.value, data });
+}
+/** `POST /api/terminals/:id/stdin` — writes `data` to the session's pty. Ownership-checked by `deps.manager.write` directly, not re-gated through `ToolExecutor` (see module doc). */
+export const terminalStdinRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/terminals/:id/stdin',
+    requireSameOrigin: true,
+    parse: parseStdinInput,
+    handle: async (input, deps) => {
+        const result = await deps.manager.write(deps.principal, input.id, input.data);
+        return actionResultToApiResult(result, `terminal "${input.id}" was not found`);
+    },
+});
+function parseResizeInput(input) {
+    const parsedId = parseTerminalId(input);
+    if (!parsedId.ok)
+        return parsedId;
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const cols = Number(input.body.cols);
+    const rows = Number(input.body.rows);
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) {
+        return err(validationError('cols and rows (numbers) are required'));
+    }
+    return ok({ id: parsedId.value, cols, rows });
+}
+/** `POST /api/terminals/:id/resize` — resizes the session's pty. */
+export const terminalResizeRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/terminals/:id/resize',
+    requireSameOrigin: true,
+    parse: parseResizeInput,
+    handle: async (input, deps) => {
+        const result = await deps.manager.resize(deps.principal, input.id, input.cols, input.rows);
+        return actionResultToApiResult(result, `terminal "${input.id}" was not found`);
+    },
+});
+function handleKill(id, deps) {
+    return deps.manager.kill(deps.principal, id, 'SIGTERM').then((result) => actionResultToApiResult(result, `terminal "${id}" was not found`));
+}
+/** `POST /api/terminals/:id/kill` — sends `SIGTERM` to the session's pty. */
+export const terminalKillRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/terminals/:id/kill',
+    requireSameOrigin: true,
+    parse: parseTerminalId,
+    handle: (id, deps) => handleKill(id, deps),
+});
+/** `DELETE /api/terminals/:id` — alias for `kill`, matching OD's dual `POST .../kill` / `DELETE` routes. */
+export const terminalDeleteRoute = defineJsonRoute({
+    method: 'delete',
+    path: '/api/terminals/:id',
+    requireSameOrigin: true,
+    parse: parseTerminalId,
+    handle: (id, deps) => handleKill(id, deps),
+});
+/**
+ * The `channelOpened`/`endRequestedBeforeOpen` state machine `registerTerminalEventStream`'s
+ * `TerminalSseSink.end()` needs, extracted into its own directly-testable unit — see that
+ * function's inline comment for *why* the deferral exists (an already-exited session's replay
+ * path can call `end()` before `open()` has ever run).
+ *
+ * **On the `markOpened()`-then-`end()` ordering (opened=true when `end()` runs):** this is the
+ * ordering every *currently reachable* production call graph in this repo takes for a live
+ * session that exits while already streaming — but it is unreachable through that graph, not
+ * unreachable in principle. `@jini-ai/platform`'s `TerminalService.finish()` (`packages/platform/src/
+ * terminal.ts`) calls `sink.send('exit', ...)` immediately before `sink.end()` for every live
+ * client; `send()` here forwards straight to `channel.enqueue()`, whose `isEndEvent: (e) => e.kind
+ * === 'exit'` match auto-closes the channel *synchronously inside that same `enqueue()` call* —
+ * which synchronously runs `registerTerminalEventStream`'s own `channel.onClose` callback, which
+ * detaches this sink from `TerminalService`'s `session.clients` before `finish()`'s own, separate
+ * `sink.end()` loop ever runs. That loop iterates `session.clients` fresh at call time (not a
+ * snapshot taken before `emit()`), so by the time it runs, this sink has already removed itself —
+ * `sink.end()` is consequently never invoked while `channelOpened` is `true` via any call graph
+ * this repo's own `@jini-ai/platform` + `@jini-ai/http-kit` composition can currently produce (confirmed by
+ * instrumenting the real call path directly, not inferred from reading the source — a synchronous
+ * console probe in `end()` never fired across this file's full "live-exit-while-streaming" test).
+ * That is a fact about today's specific `TerminalService`/`SseChannel` wiring, not a proof that no
+ * future caller of `TerminalSseSink` could ever call `end()` post-open (a hypothetical non-SSE
+ * sink, or a future `TerminalService` exit reason not preceded by a matching `send()`, would hit
+ * exactly this branch) — so the branch stays as real, intentional defensive code, tested directly
+ * here rather than deleted for being unreachable *today* or left silently uncovered.
+ */
+export function createDeferredEndGate(channel) {
+    let opened = false;
+    let endRequestedBeforeOpen = false;
+    return {
+        markOpened() {
+            opened = true;
+            // Idempotent-safe even if the queued 'exit' event already auto-closed the channel via
+            // `isEndEvent` during `open()`'s own drain (`channel.end()` is documented safe to call twice).
+            if (endRequestedBeforeOpen)
+                channel.end();
+        },
+        end() {
+            if (opened) {
+                channel.end();
+            }
+            else {
+                endRequestedBeforeOpen = true;
+            }
+        },
+    };
+}
+/**
+ * `GET /api/terminals/:id/stream` — SSE, with `Last-Event-ID`/`afterCursor`
+ * reconnect replay (via `sse.ts`'s `requestedAfterCursor`, the same helper
+ * `runs.ts` uses). Adapts `deps.manager.attach`'s push/end
+ * `TerminalSseSink` to `sse.ts`'s generic channel, mirroring
+ * `registerRunEventStream`'s adaptation of `RunLifecycle.stream`.
+ *
+ * Bypasses `mountJsonRoute` (raw `app.get`, for the SSE response shape), so it does not get
+ * `requireSameOrigin` for free the way the JSON routes above do — the guard is applied here
+ * directly, before the SSE channel is opened, so a cross-origin request never gets a stream.
+ */
+export function registerTerminalEventStream(app, deps, adapter) {
+    app.get('/api/terminals/:id/stream', (req, res) => {
+        const origin = guardSameOrigin(req, adapter);
+        if (!origin.ok) {
+            sendApiError(res, statusForError(origin.error), origin.error);
+            return;
+        }
+        const id = req.params.id;
+        if (typeof id !== 'string' || id.length === 0) {
+            sendApiError(res, 400, createApiError('BAD_REQUEST', 'id must be a non-empty path parameter'));
+            return;
+        }
+        const cursor = requestedAfterCursor(req);
+        const lastEventId = cursor === null ? 0 : Number(cursor);
+        const channel = createSseChannel(res, { isEndEvent: (event) => event.kind === 'exit' });
+        // `deps.manager.attach` can call `sink.end()` synchronously, from inside the very call below
+        // (an already-exited session's replay path) — before the channel has ever been `open()`ed. If
+        // `end()` mapped straight to `channel.end()`, that would end the response with the queued
+        // backlog never flushed (headers never even sent). `createDeferredEndGate` defers the actual
+        // `channel.end()` call until after `open()` has drained whatever `send()` already queued — see
+        // that function's own doc for the full reachability analysis of its other branch.
+        const deferredEnd = createDeferredEndGate(channel);
+        const sink = {
+            send(event, data, eventId) {
+                channel.enqueue({ opaqueCursor: String(eventId), kind: event, data });
+            },
+            end() {
+                deferredEnd.end();
+            },
+        };
+        let attachedSink = null;
+        channel.onClose(() => {
+            if (attachedSink)
+                deps.manager.detach(id, attachedSink);
+        });
+        const result = deps.manager.attach(deps.principal, id, lastEventId, sink);
+        if (result === 'not-found') {
+            channel.abandon();
+            sendApiError(res, 404, createApiError('NOT_FOUND', `terminal "${id}" was not found`));
+            return;
+        }
+        if (result === 'attached') {
+            attachedSink = sink;
+        }
+        channel.open();
+        deferredEnd.markOpened();
+    });
+}
+/** Mounts every terminal route (`list`/`create`/`stdin`/`resize`/`kill`/`delete`/`stream`) on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerTerminalRoutes(app, deps, adapter) {
+    mountJsonRoute(app, terminalListRoute, deps, adapter);
+    mountJsonRoute(app, terminalCreateRoute, deps, adapter);
+    mountJsonRoute(app, terminalStdinRoute, deps, adapter);
+    mountJsonRoute(app, terminalResizeRoute, deps, adapter);
+    mountJsonRoute(app, terminalKillRoute, deps, adapter);
+    mountJsonRoute(app, terminalDeleteRoute, deps, adapter);
+    registerTerminalEventStream(app, deps, adapter);
+}
+//# sourceMappingURL=terminals.js.map