@jini-ai/http-kit 0.2.1

package/dist/run-stream.js

@@ -0,0 +1,108 @@
+import { createSseResponse } from './raw-sse.js';
+/** Backward-compatible route path used by the AG-UI composition. The handler itself is encoder-agnostic. */
+export const RUN_STREAM_ROUTE_PATH = '/api/runs/:runId/agui-stream';
+function reportRunStreamInternalError(deps, source, runId, error) {
+    const context = { source, runId, error };
+    try {
+        if (deps.onInternalError) {
+            deps.onInternalError(context);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(`[@jini-ai/http-kit] internal error (run-stream:${source}, runId=${runId})`, error);
+        }
+    }
+    catch (sinkError) {
+        // A diagnostic sink must never turn an already-contained stream failure into an unhandled
+        // rejection of its own.
+        // eslint-disable-next-line no-console
+        console.error(`[@jini-ai/http-kit] internal error sink failed (run-stream:${source}, runId=${runId})`, sinkError);
+    }
+}
+/**
+ * Handles one encoded SSE run-stream request end to end. Opens the SSE connection immediately (an
+ * SSE endpoint commits to `text/event-stream` headers before it can know whether `runId` is
+ * valid), then subscribes to the run: a replay-then-live-subscribe `unknown-run`/`replay-gap`/
+ * `invalid-cursor` result is reported as one `{ error }` SSE data event before closing (there is
+ * no JSON-status-code channel left once SSE headers are already committed). On the happy path,
+ * every event `RunLifecycle` delivers is encoded and forwarded; the connection closes itself once
+ * the run's own terminal `'end'` event has been forwarded (a driver's contract with
+ * `RunLifecycle` guarantees no further events follow a run's `'end')`, so nothing is lost by
+ * closing right after it). If the client disconnects first, `createSseResponse`'s own
+ * `req.on('close', ...)` fires first, which (via `onClose` here) unsubscribes from the run so a
+ * disconnected client never leaves a dangling `RunLifecycle` subscriber.
+ *
+ * @param req - The raw request `createSseResponse` opens the stream against.
+ * @param res - The raw response `createSseResponse` opens the stream against.
+ * @param runId - The run to stream, already resolved by the caller's transport-specific glue.
+ * @param deps.lifecycle - The `RunLifecycle` to subscribe to.
+ * @param deps.encoder - The protocol adapter chosen by the composition root.
+ * @complexity O(1) plus the supplied encoder's per-event cost and `RunLifecycle.stream`'s replay cost.
+ * @overallScore 100/100
+ */
+export async function handleRunStreamRequest(req, res, runId, deps) {
+    let unsubscribe;
+    const connection = createSseResponse(req, res, {
+        onClose: () => unsubscribe?.(),
+    });
+    const encoder = deps.encoder;
+    let result;
+    try {
+        result = await deps.lifecycle.stream(runId, (event) => {
+            if (connection.closed)
+                return;
+            try {
+                const encoded = encoder.encode(event, { runId });
+                if (encoded != null)
+                    connection.send(encoded);
+                if (event.kind === 'end')
+                    connection.close();
+            }
+            catch (error) {
+                reportRunStreamInternalError(deps, 'encoder', runId, error);
+                connection.close();
+            }
+        });
+    }
+    catch (error) {
+        reportRunStreamInternalError(deps, 'lifecycle', runId, error);
+        connection.close();
+        return;
+    }
+    if (result.kind !== 'ok') {
+        connection.send({ error: result.kind });
+        connection.close();
+        return;
+    }
+    // Assigned even when the run was already terminal (in which case the driver-facing 'end' event
+    // was already replayed synchronously above, already closing the connection, and `unsubscribe`
+    // here is `RunLifecycle`'s own no-op stub for that case) — keeping this assignment unconditional
+    // avoids a branch whose two arms would otherwise do the same thing.
+    unsubscribe = result.unsubscribe;
+    // The raw request can close while RunLifecycle is still awaiting durable replay. In that
+    // window `onClose` runs before `unsubscribe` exists, so clean up immediately once it arrives.
+    if (connection.closed)
+        unsubscribe();
+}
+/** Mounts the encoder-driven SSE run-stream route on `app`. */
+export function registerRunStreamRoute(app, deps) {
+    app.get(RUN_STREAM_ROUTE_PATH, async (req, res) => {
+        // `:runId` is a required path segment of RUN_STREAM_ROUTE_PATH — this handler is only ever
+        // reached via a URL that already matched it, so the param is always present at runtime even
+        // though @types/express types every param as possibly `undefined` in general.
+        const runId = req.params.runId;
+        try {
+            await handleRunStreamRequest(req, res, runId, deps);
+        }
+        catch (error) {
+            reportRunStreamInternalError(deps, 'route', runId, error);
+            if (!res.headersSent) {
+                res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: 'an internal error occurred' } });
+            }
+            else if (!res.writableEnded) {
+                res.end();
+            }
+        }
+    });
+}
+//# sourceMappingURL=run-stream.js.map

package/dist/run-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-stream.js","sourceRoot":"","sources":["../src/run-stream.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,4GAA4G;AAC5G,MAAM,CAAC,MAAM,qBAAqB,GAAG,8BAA8B,CAAC;AAoBpE,SAAS,4BAA4B,CACnC,IAAmB,EACnB,MAA+C,EAC/C,KAAa,EACb,KAAc;IAEd,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,kDAAkD,MAAM,WAAW,KAAK,GAAG,EAAE,KAAK,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,0FAA0F;QAC1F,wBAAwB;QACxB,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,8DAA8D,MAAM,WAAW,KAAK,GAAG,EAAE,SAAS,CAAC,CAAC;IACpH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAoB,EACpB,GAAmB,EACnB,KAAa,EACb,IAAmB;IAEnB,IAAI,WAAqC,CAAC;IAC1C,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE;QAC7C,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE;KAC/B,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAE7B,IAAI,MAA6B,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE;YACpD,IAAI,UAAU,CAAC,MAAM;gBAAE,OAAO;YAC9B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACjD,IAAI,OAAO,IAAI,IAAI;oBAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;oBAAE,UAAU,CAAC,KAAK,EAAE,CAAC;YAC/C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,4BAA4B,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;gBAC5D,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4BAA4B,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC9D,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACzB,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACxC,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IACD,+FAA+F;IAC/F,8FAA8F;IAC9F,iGAAiG;IACjG,oEAAoE;IACpE,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACjC,yFAAyF;IACzF,8FAA8F;IAC9F,IAAI,UAAU,CAAC,MAAM;QAAE,WAAW,EAAE,CAAC;AACvC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,sBAAsB,CAAC,GAAY,EAAE,IAAmB;IACtE,GAAG,CAAC,GAAG,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACnE,2FAA2F;QAC3F,4FAA4F;QAC5F,8EAA8E;QAC9E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAM,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAC1D,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,CAAC,CAAC;YACrG,CAAC;iBAAM,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;gBAC9B,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runs.d.ts

@@ -0,0 +1,79 @@
+import type { Express } from 'express';
+import { type RunStatus } from '@jini-ai/protocol';
+import type { RunLifecycle } from '@jini-ai/daemon';
+import { type AdapterContext } from './adapter.js';
+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("./types.js").JsonRouteSpec<RunCreateRequest, RunStartResponse, RunHttpDeps>;
+/** `GET /api/runs` — lists runs, optionally scoped to a `contextRef` query parameter. */
+export declare const runListRoute: import("./types.js").JsonRouteSpec<{
+    contextRef?: string;
+}, RunListResponse, RunHttpDeps>;
+export declare const runStatusRoute: import("./types.js").JsonRouteSpec<string, RunStatusResponse, RunHttpDeps>;
+export declare const runCancelRoute: import("./types.js").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: ServerResponse, runId: string, afterCursor: string | null, deps: RunHttpDeps): 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: Express, deps: RunHttpDeps): void;
+/** Mounts create/status/cancel JSON endpoints and the SSE event stream as one run transport. */
+export declare function registerRunRoutes(app: Express, deps: RunHttpDeps, adapter: AdapterContext): void;
+//# sourceMappingURL=runs.d.ts.map

package/dist/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAyC,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAA8B,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAIpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAQD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,gHAAgH;IAChH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;CAClC;AAED,iGAAiG;AACjG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,gIAAgI;IAChI,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACvE;AAqBD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;CACzB;AA8BD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;CACrC;AA4BD,eAAO,MAAM,aAAa,qFAuBxB,CAAC;AAEH,yFAAyF;AACzF,eAAO,MAAM,YAAY;iBAAkC,MAAM;gCAK/D,CAAC;AAEH,eAAO,MAAM,cAAc,4EAQzB,CAAC;AAEH,eAAO,MAAM,cAAc;WAA4B,MAAM;aAAW,MAAM;kCAU5E,CAAC;AAoBH;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,uKAAuK;AACvK,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAS5E;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAMhG"}

package/dist/runs.js

@@ -0,0 +1,232 @@
+/**
+ * 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 './adapter.js';
+import { validationError } from './request.js';
+import { sendApiError } from './response.js';
+import { createSseChannel, requestedAfterCursor, sendRawApiError } from './sse.js';
+import { err, ok } from './types.js';
+/** 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('INTERNAL_ERROR', '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(validationError('body must be a JSON object'));
+    const contextRef = optionalString(input.body, 'contextRef');
+    if (contextRef === undefined || contextRef === null) {
+        return err(validationError('contextRef must be a non-empty string', [{ 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(validationError('optional string fields must be non-empty when provided'));
+    }
+    return ok({
+        contextRef,
+        ...(agentId === undefined ? {} : { agentId }),
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+}
+function parseRunList(input) {
+    const value = input.query.contextRef;
+    if (value === undefined)
+        return ok({});
+    if (typeof value !== 'string' || value.length === 0) {
+        return err(validationError('contextRef must be a non-empty string when provided', [{ path: 'contextRef', message: 'non-empty string when provided' }]));
+    }
+    return ok({ contextRef: value });
+}
+function parseRunId(input) {
+    const runId = input.params.runId;
+    return typeof runId === 'string' && runId.length > 0
+        ? ok(runId)
+        : err(validationError('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({ runId: parsedRunId.value });
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object when provided'));
+    const reason = optionalString(input.body, 'reason');
+    if (reason === null)
+        return err(validationError('reason must be a non-empty string when provided'));
+    return ok({ runId: parsedRunId.value, ...(reason === undefined ? {} : { reason }) });
+}
+export const runStartRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/runs',
+    requireSameOrigin: true,
+    parse: parseRunCreate,
+    handle: async (input, deps) => {
+        const startInput = input;
+        const started = await deps.lifecycle.start(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(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(started.run.id)) ?? started.run;
+        return ok({ run, started: started.started });
+    },
+    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({ runs: await deps.lifecycle.list(input.contextRef) }),
+});
+export const runStatusRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/runs/:runId',
+    parse: parseRunId,
+    handle: async (runId, deps) => {
+        const run = await deps.lifecycle.get(runId);
+        return run === undefined ? err(createApiError('NOT_FOUND', `run "${runId}" was not found`)) : ok({ run });
+    },
+});
+export const runCancelRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/runs/:runId/cancel',
+    requireSameOrigin: true,
+    parse: parseRunCancel,
+    handle: async (input, deps) => {
+        const run = await deps.lifecycle.get(input.runId);
+        if (run === undefined)
+            return err(createApiError('NOT_FOUND', `run "${input.runId}" was not found`));
+        return ok({ run: await deps.lifecycle.cancel(input) });
+    },
+});
+function sendStreamFailure(res, kind) {
+    if (kind.kind === 'unknown-run') {
+        sendRawApiError(res, 404, createApiError('NOT_FOUND', 'run was not found'));
+        return;
+    }
+    if (kind.kind === 'invalid-cursor') {
+        sendRawApiError(res, 400, createApiError('BAD_REQUEST', `invalid replay cursor "${kind.requestedCursor}"`));
+        return;
+    }
+    sendRawApiError(res, 409, createApiError('CONFLICT', `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) {
+    if (runId.length === 0) {
+        sendRawApiError(res, 400, createApiError('BAD_REQUEST', '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(() => {
+        const stop = unsubscribeFn;
+        unsubscribeFn = null;
+        stop?.();
+    });
+    try {
+        const subscribed = await deps.lifecycle.stream(runId, channel.enqueue, { 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, 500, 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) {
+    app.get(RUN_EVENTS_ROUTE_PATH, async (req, res) => {
+        const runId = req.params.runId;
+        if (typeof runId !== 'string' || runId.length === 0) {
+            sendApiError(res, 400, createApiError('BAD_REQUEST', 'runId must be a non-empty path parameter'));
+            return;
+        }
+        await handleRunEventStreamRequest(res, runId, requestedAfterCursor(req), deps);
+    });
+}
+/** Mounts create/status/cancel JSON endpoints and the SSE event stream as one run transport. */
+export function registerRunRoutes(app, deps, adapter) {
+    mountJsonRoute(app, runStartRoute, deps, adapter);
+    mountJsonRoute(app, runListRoute, deps, adapter);
+    mountJsonRoute(app, runStatusRoute, deps, adapter);
+    mountJsonRoute(app, runCancelRoute, deps, adapter);
+    registerRunEventStream(app, deps);
+}
+//# sourceMappingURL=runs.js.map

package/dist/runs.js.map

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

package/dist/sse.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Generic Server-Sent-Events transport primitive.
+ *
+ * Before this file, the only SSE machinery in this package was inlined
+ * directly inside `runs.ts`'s `registerRunEventStream` (a bounded-queue,
+ * backpressure-aware `res.write`/`'drain'` state machine with Last-Event-ID
+ * replay support) — see `source-map.md`'s 2026-07-19 "generic lifecycle SSE
+ * projection" note and the many "requires SSE (deferred)" verdicts against
+ * `chat.ts`/`memory.ts`/`terminal.ts` in the routes-classification table.
+ * `createSseChannel` below is that same state machine, generalized over any
+ * event type (not just `RunProtocolEvent`) so a route only has to describe
+ * *what* to stream, not *how* to stream it. `runs.ts` is refactored to call
+ * this primitive rather than keeping its own copy — the same discipline this
+ * package already applies to `origin-validation.ts`/`compat.ts` (shared
+ * mechanism, one implementation, one set of tests for the mechanism itself).
+ *
+ * OD's own precedent for a shared SSE primitive is `ctx.http.createSseResponse`
+ * (an Express-request-scoped helper both `apps/daemon/src/routes/runs.ts` and
+ * `apps/daemon/src/routes/terminal.ts` receive via dependency injection and
+ * call themselves) — this file is the Jini equivalent of that role, not an
+ * invented-from-scratch design.
+ */
+import type { ServerResponse } from 'node:http';
+import { type ApiError } from '@jini-ai/protocol';
+/** The minimal shape any event needs to flow through an `SseChannel`: an id for `Last-Event-ID` reconnect bookkeeping and a `kind` used as the wire `event:` field. */
+export interface SseEvent {
+    readonly opaqueCursor: string;
+    readonly kind: string;
+}
+/**
+ * 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 declare const DEFAULT_MAX_QUEUED_SSE_EVENTS = 1000;
+export interface CreateSseChannelOptions<E extends SseEvent> {
+    /** Queued-event ceiling before the connection is dropped. Defaults to {@link DEFAULT_MAX_QUEUED_SSE_EVENTS}. */
+    readonly maxQueuedEvents?: number;
+    /** When true for a given event, the channel ends the stream immediately after writing it (matches `runs.ts`'s `'end'`-kind auto-close). Omit for a channel that only ends on client disconnect/overflow/explicit `end()`. */
+    readonly isEndEvent?: (event: E) => boolean;
+    /** Overrides the wire format. Defaults to {@link defaultFormatEvent}. */
+    readonly formatEvent?: (event: E) => string;
+    /** Invoked once, synchronously, if `res.write` throws mid-flush — lets a caller log the real error without it crossing back into whatever produced the event (mirrors `runs.ts`'s `RunHttpDeps.onInternalError` seam, but this primitive itself stays logging-free: silent by default, matching a transport channel's "never throw back through the producer" contract). */
+    readonly onWriteError?: (error: unknown) => void;
+}
+export interface SseChannel<E extends SseEvent> {
+    /**
+     * Queues `event` for delivery. A no-op once the channel is closed. Before
+     * {@link SseChannel.open} is called, events accumulate in the same bounded
+     * queue used for later backpressure, so a caller may safely `enqueue`
+     * replay history before opening the stream — the client's very first
+     * flush then already contains that backlog.
+     */
+    readonly enqueue: (event: E) => void;
+    /**
+     * Writes SSE headers (`200`, `text/event-stream`, `Cache-Control: no-cache,
+     * no-transform`, `Connection: keep-alive`) and starts draining the queue.
+     * Idempotent — a no-op if already open or already closed.
+     */
+    readonly open: () => void;
+    /** True once the channel has closed for any reason (explicit `end()`, client disconnect, queue overflow, or a fatal write). */
+    readonly isClosed: () => boolean;
+    /**
+     * Idempotent: marks the channel closed, unsubscribes nothing itself (a
+     * caller's {@link SseChannel.onClose} callback does that), and ends the
+     * underlying HTTP response if it has not already ended. Calling `res.end()`
+     * a second time (e.g. after the client already disconnected) is safe and
+     * documented as a no-op by Node's `http.ServerResponse` — this method does
+     * not need to distinguish "we are ending it" from "the client already
+     * ended it."
+     */
+    readonly end: () => void;
+    /**
+     * Idempotent: marks the channel closed and runs every registered
+     * {@link SseChannel.onClose} callback — but, unlike {@link SseChannel.end},
+     * never touches `res` itself. For a caller that hits a failure *before*
+     * ever calling {@link SseChannel.open} and wants to send a different,
+     * non-SSE response instead (e.g. a JSON error body) rather than an empty
+     * ended stream. Calling {@link SseChannel.end} in that situation would
+     * end the response first and make the caller's own subsequent
+     * `res.status(...).json(...)` a write-after-end failure; `abandon` avoids
+     * that by leaving `res` completely untouched.
+     */
+    readonly abandon: () => void;
+    /**
+     * Registers a callback invoked exactly once when the channel closes, from
+     * whichever cause fires first (explicit `end()`, a client disconnect
+     * observed via the response's own `'close'` event, or an internal
+     * overflow/write failure). Safe to call after the channel is already
+     * closed — the callback then runs immediately, synchronously.
+     */
+    readonly onClose: (callback: () => void) => void;
+}
+/**
+ * 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 declare function createSseChannel<E extends SseEvent>(res: ServerResponse, options?: CreateSseChannelOptions<E>): SseChannel<E>;
+/** 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 declare function requestedAfterCursor(req: {
+    get(name: string): string | undefined;
+    query: Record<string, unknown>;
+}): string | 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 declare function sendRawApiError(res: ServerResponse, status: number, error: ApiError): void;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE1E,uKAAuK;AACvK,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAOlD,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,QAAQ;IACzD,gHAAgH;IAChH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,6NAA6N;IAC7N,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAC5C,4WAA4W;IAC5W,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,QAAQ;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,+HAA+H;IAC/H,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EACjD,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACvC,UAAU,CAAC,CAAC,CAAC,CA8Ff;AAED,wRAAwR;AACxR,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GAAG,MAAM,GAAG,IAAI,CAKhB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAI1F"}