@jini-ai/daemon 0.3.8 → 0.5.1

package/dist/http/run-credentials.js

@@ -0,0 +1,71 @@
+/** Mount before JSON parsing, then again on delegated calls after parsing with body validation.
+ * Only the allowed policy result may replace the principal header; trusted proxy headers remain intact.
+ * Policy exceptions go to Express's error boundary. No request body is accessed in the first gate.
+ * @complexity O(1) adapter work, excluding the injected authorization policy.
+ */
+export function createDaemonAuthMiddleware({ authorize, authorizationHeaderName }, { validateDelegatedRunId = false } = {}) {
+    return (req, res, next) => {
+        try {
+            const decision = authorize({ request: {
+                    method: req.method, path: req.path,
+                    headers: { [authorizationHeaderName]: req.get(authorizationHeaderName) },
+                    ...(validateDelegatedRunId ? { body: req.body } : {}),
+                } }, { validateDelegatedRunId });
+            if (!decision.allowed) {
+                res.status(decision.status).json(decision.body);
+                return;
+            }
+            if (decision.principalHeader)
+                req.headers[decision.principalHeader.name.toLowerCase()] = decision.principalHeader.value;
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/** Mount after authentication on routes with a runId parameter. Denial envelopes pass through intact.
+ * @complexity O(1) adapter work plus the injected ownership lookup; no storage or identity defaults.
+ */
+export function createRunOwnershipMiddleware({ authorize, principalHeaderName, isEventStream }) {
+    return async (req, res, next) => {
+        try {
+            const decision = await authorize({ runId: req.params.runId || undefined, principalId: req.get(principalHeaderName) || undefined, eventStream: isEventStream({ path: req.path }) });
+            if (!decision.allowed) {
+                res.status(decision.status).json(decision.body);
+                return;
+            }
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/** List only the authenticated principal's runs, after the host's context filter.
+ * Missing principals receive the existing 401 envelope before the list port is called.
+ * @complexity O(n) policy filtering for n listed runs; O(1) adapter space excluding results.
+ */
+export function createOwnedRunListHandler({ listRuns, filterOwnedRuns, principalHeaderName }) {
+    return async (req, res, next) => {
+        try {
+            const principalId = req.get(principalHeaderName) || undefined;
+            if (!principalId) {
+                res.status(401).json({ error: { code: 'UNAUTHENTICATED', message: `${principalHeaderName} is required on run-scoped requests` } });
+                return;
+            }
+            const contextRef = typeof req.query.contextRef === 'string' ? req.query.contextRef : undefined;
+            const runs = await listRuns({}, contextRef === undefined ? {} : { contextRef });
+            const decision = filterOwnedRuns({ runs, principalId });
+            if (!decision.allowed) {
+                res.status(decision.status).json(decision.body);
+                return;
+            }
+            res.json({ runs: decision.runs });
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+//# sourceMappingURL=run-credentials.js.map

package/dist/http/runs.d.ts

@@ -0,0 +1,91 @@
+import type { Express } from 'express';
+import { type RunStatus } from '@jini-ai/protocol';
+import type { RunLifecycle } from '../index.js';
+import { type AdapterContext } from '@jini-ai/http-kit';
+import type { ServerResponse } from 'node:http';
+/**
+ * Diagnostic detail for an internal-error response the public API deliberately does not
+ * disclose (SEC-005): spawn/storage/adapter failures can embed executable paths, working
+ * directories, hostnames, or third-party provider text. The correlation id is the only thing
+ * that crosses the boundary; the real `error` goes only to this host-owned sink so an operator
+ * can still find and act on it.
+ */
+export interface RunInternalErrorContext {
+    readonly source: 'run-start' | 'run-stream';
+    readonly runId: string;
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface RunCreateRequest {
+    readonly contextRef: string;
+    readonly agentId?: string;
+    readonly idempotencyKey?: string;
+}
+export interface RunStartContext {
+    readonly request: RunCreateRequest;
+    readonly run: RunStatus;
+    /** The lifecycle this driver must use for emitted events, cancellation observation, and terminal completion. */
+    readonly lifecycle: RunLifecycle;
+}
+/** Host-owned execution hook. It attaches a driver only after a durable run has been created. */
+export type RunStartHandler = (context: RunStartContext) => Promise<void> | void;
+export interface RunHttpDeps {
+    readonly lifecycle: RunLifecycle;
+    readonly onStarted?: RunStartHandler;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: RunInternalErrorContext) => void;
+}
+export interface RunStartResponse {
+    readonly run: RunStatus;
+    readonly started: boolean;
+}
+export interface RunStatusResponse {
+    readonly run: RunStatus;
+}
+export interface RunCancelResponse {
+    readonly run: RunStatus;
+}
+export interface RunListResponse {
+    readonly runs: readonly RunStatus[];
+}
+export declare const runStartRoute: import("@jini-ai/http-kit").JsonRouteSpec<RunCreateRequest, RunStartResponse, RunHttpDeps>;
+/** `GET /api/runs` — lists runs, optionally scoped to a `contextRef` query parameter. */
+export declare const runListRoute: import("@jini-ai/http-kit").JsonRouteSpec<{
+    contextRef?: string;
+}, RunListResponse, RunHttpDeps>;
+export declare const runStatusRoute: import("@jini-ai/http-kit").JsonRouteSpec<string, RunStatusResponse, RunHttpDeps>;
+export declare const runCancelRoute: import("@jini-ai/http-kit").JsonRouteSpec<{
+    runId: string;
+    reason?: string;
+}, RunCancelResponse, RunHttpDeps>;
+/**
+ * The core of `GET /api/runs/:runId/events` — canonical events as SSE, with Last-Event-ID
+ * reconnect support. Takes `runId`/`afterCursor` already resolved by the caller. `res` is typed
+ * against the raw `node:http` `ServerResponse` rather than Express's own `Response` type — Express's
+ * `Response` extends it directly, so this is a no-op widening, the same pattern `run-stream.ts`'s
+ * AG-UI handler already established.
+ */
+export declare function handleRunEventStreamRequest({ res, runId, afterCursor, deps }: {
+    readonly res: ServerResponse;
+    readonly runId: string;
+    readonly afterCursor: string | null;
+    readonly deps: RunHttpDeps;
+}, _optional?: Record<string, never>): Promise<void>;
+/**
+ * Path {@link registerRunEventStream} mounts. Exported as a constant so a caller that needs to know
+ * this route exists — a reverse proxy's forward list, `route-manifest.ts` — references it rather than
+ * restating the literal and later drifting from it.
+ */
+export declare const RUN_EVENTS_ROUTE_PATH = "/api/runs/:runId/events";
+/** Express mounting glue for {@link handleRunEventStreamRequest} — resolves `runId`/`afterCursor` from an Express `Request` and hands the request straight through. */
+export declare function registerRunEventStream({ app, deps }: {
+    readonly app: Express;
+    readonly deps: RunHttpDeps;
+}, _optional?: Record<string, never>): void;
+/** Mounts create/status/cancel JSON endpoints and the SSE event stream as one run transport. */
+export declare function registerRunRoutes({ app, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: RunHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+//# sourceMappingURL=runs.d.ts.map

package/dist/http/runs.js

@@ -0,0 +1,221 @@
+/**
+ * Generic HTTP/SSE projection of the kernel RunLifecycle. The routes own no
+ * agent, tool, or product vocabulary: a host optionally supplies `onStarted`
+ * to attach its chosen driver after the lifecycle has durably recorded start.
+ */
+import { randomUUID } from 'node:crypto';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
+import { validationError } from '@jini-ai/http-kit';
+import { sendApiError } from '@jini-ai/http-kit';
+import { createSseChannel, requestedAfterCursor, sendRawApiError } from '@jini-ai/http-kit';
+import { err, ok } from '@jini-ai/http-kit';
+/** Default sink when a host does not supply `onInternalError`: still observable, never silent. */
+function defaultInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+/**
+ * Logs the real failure server-side and returns the generic, correlation-id-bearing public error
+ * (SEC-005: never the raw exception). `runId` is mandatory — both real call sites (`run-start`,
+ * after a durably-created run's id is already known; `run-stream`, against an already-parsed path
+ * parameter) always have one in hand, so an optional field with an unreachable "no runId" branch
+ * was speculative flexibility no caller ever exercised.
+ */
+function reportInternalError(deps, source, error, runId) {
+    const correlationId = randomUUID();
+    const sink = deps.onInternalError ?? defaultInternalErrorSink;
+    sink({ source, runId, correlationId, error });
+    return createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function optionalString(body, key) {
+    const value = body[key];
+    if (value === undefined)
+        return undefined;
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function parseRunCreate(input) {
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const contextRef = optionalString(input.body, 'contextRef');
+    if (contextRef === undefined || contextRef === null) {
+        return err({ error: validationError({ message: 'contextRef must be a non-empty string' }, { issues: [{ path: 'contextRef', message: 'required non-empty string' }] }) });
+    }
+    const agentId = optionalString(input.body, 'agentId');
+    const idempotencyKey = optionalString(input.body, 'idempotencyKey');
+    if (agentId === null || idempotencyKey === null) {
+        return err({ error: validationError({ message: 'optional string fields must be non-empty when provided' }) });
+    }
+    return ok({
+        value: {
+            contextRef,
+            ...(agentId === undefined ? {} : { agentId }),
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+        }
+    });
+}
+function parseRunList(input) {
+    const value = input.query.contextRef;
+    if (value === undefined)
+        return ok({ value: {} });
+    if (typeof value !== 'string' || value.length === 0) {
+        return err({ error: validationError({ message: 'contextRef must be a non-empty string when provided' }, { issues: [{ path: 'contextRef', message: 'non-empty string when provided' }] }) });
+    }
+    return ok({ value: { contextRef: value } });
+}
+function parseRunId(input) {
+    const runId = input.params.runId;
+    return typeof runId === 'string' && runId.length > 0
+        ? ok({ value: runId })
+        : err({ error: validationError({ message: 'runId must be a non-empty path parameter' }) });
+}
+function parseRunCancel(input) {
+    const parsedRunId = parseRunId(input);
+    if (!parsedRunId.ok)
+        return parsedRunId;
+    if (input.body === undefined || input.body === null)
+        return ok({ value: { runId: parsedRunId.value } });
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object when provided' }) });
+    const reason = optionalString(input.body, 'reason');
+    if (reason === null)
+        return err({ error: validationError({ message: 'reason must be a non-empty string when provided' }) });
+    return ok({ value: { runId: parsedRunId.value, ...(reason === undefined ? {} : { reason }) } });
+}
+export const runStartRoute = defineJsonRoute({
+    method: 'post', path: '/api/runs', parse: parseRunCreate, handle: async ({ input, deps }) => {
+        const startInput = input;
+        const started = await deps.lifecycle.start({ contextRef: startInput.contextRef }, { ...startInput });
+        if (started.started && deps.onStarted) {
+            try {
+                await deps.onStarted({ request: input, run: started.run, lifecycle: deps.lifecycle });
+            }
+            catch (error) {
+                await deps.lifecycle.finish({ runId: started.run.id, status: 'failed', code: null, signal: null, resumable: false });
+                return err({ error: reportInternalError(deps, 'run-start', error, started.run.id) });
+            }
+        }
+        // A host-owned driver may finish immediately (for example, a single-step
+        // run). Return the lifecycle's current view rather than the snapshot
+        // captured before invoking that driver.
+        const run = (await deps.lifecycle.get({ runId: started.run.id })) ?? started.run;
+        return ok({ value: { run, started: started.started } });
+    }
+}, { requireSameOrigin: true, successStatus: 201 });
+/** `GET /api/runs` — lists runs, optionally scoped to a `contextRef` query parameter. */
+export const runListRoute = defineJsonRoute({ method: 'get', path: '/api/runs', parse: parseRunList, handle: async ({ input, deps }) => ok({ value: { runs: await deps.lifecycle.list({}, input.contextRef === undefined ? {} : { contextRef: input.contextRef }) } }) });
+export const runStatusRoute = defineJsonRoute({
+    method: 'get', path: '/api/runs/:runId', parse: parseRunId, handle: async ({ input: runId, deps }) => {
+        const run = await deps.lifecycle.get({ runId });
+        return run === undefined ? err({ error: createApiError({ code: 'NOT_FOUND', message: `run "${runId}" was not found` }) }) : ok({ value: { run } });
+    }
+});
+export const runCancelRoute = defineJsonRoute({
+    method: 'post', path: '/api/runs/:runId/cancel', parse: parseRunCancel, handle: async ({ input, deps }) => {
+        const run = await deps.lifecycle.get({ runId: input.runId });
+        if (run === undefined)
+            return err({ error: createApiError({ code: 'NOT_FOUND', message: `run "${input.runId}" was not found` }) });
+        return ok({ value: { run: await deps.lifecycle.cancel(input) } });
+    }
+}, { requireSameOrigin: true });
+function sendStreamFailure(res, kind) {
+    if (kind.kind === 'unknown-run') {
+        sendRawApiError({ res, status: 404, error: createApiError({ code: 'NOT_FOUND', message: 'run was not found' }) });
+        return;
+    }
+    if (kind.kind === 'invalid-cursor') {
+        sendRawApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: `invalid replay cursor "${kind.requestedCursor}"` }) });
+        return;
+    }
+    sendRawApiError({
+        res, status: 409, error: createApiError({ code: 'CONFLICT', message: `replay gap after cursor "${kind.requestedCursor}"` }, {
+            details: { oldestAvailableCursor: kind.oldestAvailableCursor },
+        })
+    });
+}
+/**
+ * The core of `GET /api/runs/:runId/events` — canonical events as SSE, with Last-Event-ID
+ * reconnect support. Takes `runId`/`afterCursor` already resolved by the caller. `res` is typed
+ * against the raw `node:http` `ServerResponse` rather than Express's own `Response` type — Express's
+ * `Response` extends it directly, so this is a no-op widening, the same pattern `run-stream.ts`'s
+ * AG-UI handler already established.
+ */
+export async function handleRunEventStreamRequest({ res, runId, afterCursor, deps }, _optional = {}) {
+    if (runId.length === 0) {
+        sendRawApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'runId must be a non-empty path parameter' }) });
+        return;
+    }
+    // `createSseChannel` (`sse.ts`) owns the bounded queue, backpressure, and client-disconnect
+    // handling that used to be inlined here — see that module's doc for the generalization.
+    const channel = createSseChannel({ res }, { isEndEvent: ({ event }) => event.kind === 'end' });
+    let unsubscribeFn = null;
+    channel.onClose({
+        callback: () => {
+            const stop = unsubscribeFn;
+            unsubscribeFn = null;
+            stop?.();
+        }
+    });
+    try {
+        const subscribed = await deps.lifecycle.stream({ runId, onEvent: (event) => channel.enqueue({ event }) }, { afterCursor });
+        if (subscribed.kind !== 'ok') {
+            // Nothing was ever subscribed, so `abandon()` has nothing to unsubscribe — it only marks
+            // the channel closed. `res` itself is untouched, leaving `sendStreamFailure` free to send
+            // a normal JSON error response instead of an SSE stream.
+            channel.abandon();
+            sendStreamFailure(res, subscribed);
+            return;
+        }
+        if (channel.isClosed()) {
+            // The client already disconnected (or the bounded queue already gave up) while
+            // `stream()` was resolving — unsubscribe immediately instead of leaking it.
+            subscribed.unsubscribe();
+            return;
+        }
+        unsubscribeFn = subscribed.unsubscribe;
+        channel.open();
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            // `channel.open()` never ran (or never got past `flushHeaders`) — abandon without
+            // touching `res`, so the JSON error response below is the only thing written.
+            // Using `channel.end()` here instead would end the response before this write, turning
+            // it into a write-after-end failure.
+            channel.abandon();
+            sendRawApiError({ res, status: 500, error: reportInternalError(deps, 'run-stream', error, runId) });
+            return;
+        }
+        // Headers were already sent (the stream had started, or `open()` partially ran before
+        // throwing) — end the stream itself rather than attempting a second, incompatible response.
+        channel.end();
+    }
+}
+/**
+ * Path {@link registerRunEventStream} mounts. Exported as a constant so a caller that needs to know
+ * this route exists — a reverse proxy's forward list, `route-manifest.ts` — references it rather than
+ * restating the literal and later drifting from it.
+ */
+export const RUN_EVENTS_ROUTE_PATH = '/api/runs/:runId/events';
+/** Express mounting glue for {@link handleRunEventStreamRequest} — resolves `runId`/`afterCursor` from an Express `Request` and hands the request straight through. */
+export function registerRunEventStream({ app, deps }, _optional = {}) {
+    app.get(RUN_EVENTS_ROUTE_PATH, async (req, res) => {
+        const runId = req.params.runId;
+        if (typeof runId !== 'string' || runId.length === 0) {
+            sendApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'runId must be a non-empty path parameter' }) });
+            return;
+        }
+        await handleRunEventStreamRequest({ res, runId, afterCursor: requestedAfterCursor(req), deps });
+    });
+}
+/** Mounts create/status/cancel JSON endpoints and the SSE event stream as one run transport. */
+export function registerRunRoutes({ app, deps, adapter }, _optional = {}) {
+    mountJsonRoute({ app, spec: runStartRoute, deps, adapter });
+    mountJsonRoute({ app, spec: runListRoute, deps, adapter });
+    mountJsonRoute({ app, spec: runStatusRoute, deps, adapter });
+    mountJsonRoute({ app, spec: runCancelRoute, deps, adapter });
+    registerRunEventStream({ app, deps });
+}
+//# sourceMappingURL=runs.js.map

package/dist/http/terminals.d.ts

@@ -0,0 +1,138 @@
+import type { Express } from 'express';
+import type { Principal } from '@jini-ai/core';
+import type { TerminalSessionActionResult, TerminalSessionInfo, TerminalSessionManager } from '../index.js';
+import type { ToolExecutor } from '../index.js';
+import { type AdapterContext } from '@jini-ai/http-kit';
+import { type WorkspaceRootResolver } from './workspace-root.js';
+import { type Result } from '@jini-ai/http-kit';
+/** 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("@jini-ai/http-kit").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("@jini-ai/http-kit").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, notFoundMessage }: {
+    readonly result: TerminalSessionActionResult;
+    readonly notFoundMessage: string;
+}, _optional?: Record<string, never>): 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("@jini-ai/http-kit").JsonRouteSpec<{
+    id: string;
+    data: string;
+}, TerminalActionResponse, TerminalsHttpDeps>;
+/** `POST /api/terminals/:id/resize` — resizes the session's pty. */
+export declare const terminalResizeRoute: import("@jini-ai/http-kit").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("@jini-ai/http-kit").JsonRouteSpec<string, TerminalActionResponse, TerminalsHttpDeps>;
+/** `DELETE /api/terminals/:id` — alias for `kill`, matching OD's dual `POST .../kill` / `DELETE` routes. */
+export declare const terminalDeleteRoute: import("@jini-ai/http-kit").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/daemon/http` 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 }: {
+    readonly channel: DeferredEndChannel;
+}, _optional?: Record<string, never>): {
+    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, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: TerminalsHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): 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, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: TerminalsHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+export {};
+//# sourceMappingURL=terminals.d.ts.map