@jini-ai/http-kit 0.2.1

package/dist/frontend-control.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @module frontend-control
+ *
+ * Assembles the three halves of agent-driven frontend control into one thing a host can wire up as
+ * a config entry rather than a checklist.
+ *
+ * The parts already existed and none of them composed: `@jini-ai/daemon`'s `FrontendSessionRegistry`
+ * addresses a run to a surface, this package's own frontend-session routes carry invocations to a
+ * browser and answers back, and `createFrontendCapabilityRegistrations` projects a manifest into
+ * gated tools. A host had to construct all three, keep them consistent, and remember to bind a run
+ * when it started. Every one of those is a chance to get it subtly wrong, and one of them —
+ * binding — is a security decision.
+ *
+ * **Moved here from `@jini-ai/server` (2026-07-31).** It never needed that package: its real
+ * dependencies are `core`, `daemon`, `express` and this module's own siblings, all of which
+ * `http-kit` already has. The only thing pinning it there was a *type-only* import of
+ * `LocalNodeHttpExtension` — so a helper any Express host could use sat behind a package that also
+ * pulls in `@jini-ai/sidecar` and `better-sqlite3`. The reference implementation hit exactly this
+ * and hand-reimplemented the composition instead. `@jini-ai/server` re-exports it, so existing
+ * imports keep working.
+ *
+ * **This facade never returns the registry**, and that is its most important property. The
+ * registry's `invoke` executes a capability on a real user's screen with no policy check, no
+ * confirmation, no timeout, and no audit record — it is safe only because the sole thing that can
+ * reach it is a `ToolHandler` that `ToolExecutor` already gated. Handing a host the registry so it
+ * could "wire something custom" would hand it a bypass, and a bypass that exists gets used. The
+ * host gets an HTTP extension, a set of registrations, and a bind hook; none of them can execute a
+ * capability directly.
+ *
+ * **The bind token is not a field on the run DTO.** A run is a neutral kernel noun and a browser
+ * surface is not; putting `frontendBindToken` on `RunCreateRequest` would push a browser concept
+ * into a protocol every consumer shares, to serve one transport. Instead the host supplies
+ * {@link CreateFrontendControlOptions.resolveBindToken}, which reads the token out of whatever
+ * envelope that host already uses — `contextRef` is an opaque host blob precisely so hosts can put
+ * their own metadata in it. The engine stays neutral and the host keeps one place to look.
+ */
+import type { Express } from 'express';
+import type { ToolPolicy, ToolRegistration } from '@jini-ai/core';
+import { type FrontendCapabilitySpec } from '@jini-ai/daemon';
+import type { AdapterContext } from './adapter.js';
+import type { RunCreateRequest, RunStartHandler } from './runs.js';
+/**
+ * The context {@link FrontendControl.httpExtension} actually reads — just the adapter.
+ *
+ * Declared structurally here rather than importing `@jini-ai/server`'s `LocalNodeHttpExtension`,
+ * which is what used to keep this module in that package. A function taking this narrower context
+ * stays assignable to one taking the wider `{adapter, lifecycle, dataDir}`, so passing the result
+ * to `createLocalNodeDaemon`'s `httpExtensions` still typechecks — while a host that builds its own
+ * Express app (and so has no `dataDir` or `LocalNodeHttpExtensionContext` to hand over) can now use
+ * this facade too, instead of reimplementing it. The reference implementation had to do exactly
+ * that.
+ */
+export type FrontendHttpExtension = (app: Express, context: {
+    readonly adapter: AdapterContext;
+}) => void;
+export interface FrontendBindErrorContext {
+    readonly runId: string;
+    readonly error: unknown;
+}
+export interface CreateFrontendControlOptions {
+    /**
+     * The capabilities to expose. `@jini-ai/agentic`'s `PAGE_CAPABILITIES` and `@jini-ai/chat/core`'s
+     * `CHAT_CAPABILITIES` satisfy this structurally — the engine never imports that vocabulary
+     * (see `frontend-capability-tools.ts`'s module doc for why the edge points one way).
+     */
+    readonly capabilities: readonly FrontendCapabilitySpec[];
+    /**
+     * Reads this run's bind token out of the host's own run request, or returns `undefined` when the
+     * run has no originating surface.
+     *
+     * Required, and deliberately not defaulted. A default would have to guess where a host keeps the
+     * token, and guessing wrong fails *open* in the confusing direction: the run starts, the agent
+     * gets its tools, and every page call fails later with "no frontend is bound" — a symptom that
+     * looks like a browser problem and is actually a config one.
+     *
+     * Returning `undefined` is normal, not an error. A run started from a CLI has no surface, and
+     * capabilities whose `surface` is `'server'` do not need one.
+     */
+    readonly resolveBindToken: (request: RunCreateRequest) => string | undefined;
+    /** @default `@jini-ai/daemon`'s `denyAllFrontendCapabilityPolicy` — a host grants access explicitly. */
+    readonly policy?: ToolPolicy;
+    /** @default `@jini-ai/daemon`'s `DEFAULT_FRONTEND_CAPABILITY_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /** Applied to every registration. Frontend output is untrusted page text; bound it. */
+    readonly maxOutputBytes?: number;
+    /**
+     * Host-owned sink for a bind failure. Defaults to `console.error`.
+     *
+     * A failed bind does not fail the run. The run is still legitimate — the agent simply cannot
+     * drive the page, and every capability call it makes will say so by name. Killing a run because
+     * one optional channel could not be established would turn a degraded session into no session.
+     */
+    readonly onBindError?: (context: FrontendBindErrorContext) => void;
+}
+export interface FrontendControl {
+    /**
+     * Mounts the frontend-session stream and response routes. Pass in `createLocalNodeDaemon`'s
+     * `httpExtensions`, or call it directly with `(app, { adapter })` from a host that owns its own
+     * Express app — see {@link FrontendHttpExtension}.
+     */
+    readonly httpExtension: FrontendHttpExtension;
+    /** One gated tool per capability. Pass in `toolRegistrations`. */
+    readonly toolRegistrations: readonly ToolRegistration[];
+    /**
+     * Binds each starting run to the surface that originated it, and releases the binding when the
+     * run reaches a terminal state so a long-lived tab does not accumulate dead bindings.
+     *
+     * Compose it with whatever the host already does on run start — this hook only binds, it never
+     * executes anything:
+     *
+     * ```ts
+     * onRunStarted: (context) => {
+     *   frontend.bindOnStarted(context);
+     *   void startMyAgent(context);
+     * }
+     * ```
+     */
+    readonly bindOnStarted: RunStartHandler;
+}
+/**
+ * Builds the frontend-control bundle.
+ *
+ * @param options - Capabilities to expose, how to find the bind token, and the gate to apply.
+ * @returns An HTTP extension, tool registrations, and a run-start bind hook — never the registry.
+ * @throws Never at construction. A duplicate capability id throws later, when the registrations are
+ * registered, naming the id (`ToolRegistry.register`'s own error).
+ *
+ * @complexity O(n) in `capabilities`.
+ */
+export declare function createFrontendControl(options: CreateFrontendControlOptions): FrontendControl;
+//# sourceMappingURL=frontend-control.d.ts.map

package/dist/frontend-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-control.d.ts","sourceRoot":"","sources":["../src/frontend-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAmB,eAAe,EAAE,MAAM,WAAW,CAAC;AAEpF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,KAAK,IAAI,CAAC;AAE1G,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;IAC7E,wGAAwG;IACxG,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACpE;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;IAC9C,kEAAkE;IAClE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;CACzC;AAOD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,eAAe,CA8D5F"}

package/dist/frontend-control.js

@@ -0,0 +1,77 @@
+import { createFrontendCapabilityRegistrations, createFrontendSessionRegistry, } from '@jini-ai/daemon';
+import { registerFrontendSessionRoutes } from './frontend-sessions.js';
+function defaultBindErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/server] could not bind run "${context.runId}" to a frontend surface`, context.error);
+}
+/**
+ * Builds the frontend-control bundle.
+ *
+ * @param options - Capabilities to expose, how to find the bind token, and the gate to apply.
+ * @returns An HTTP extension, tool registrations, and a run-start bind hook — never the registry.
+ * @throws Never at construction. A duplicate capability id throws later, when the registrations are
+ * registered, naming the id (`ToolRegistry.register`'s own error).
+ *
+ * @complexity O(n) in `capabilities`.
+ */
+export function createFrontendControl(options) {
+    // Closed over, never exposed. See the module doc: reaching this is reaching an ungated `invoke`.
+    const registry = createFrontendSessionRegistry();
+    const onBindError = options.onBindError ?? defaultBindErrorSink;
+    const toolRegistrations = createFrontendCapabilityRegistrations({
+        registry,
+        capabilities: options.capabilities,
+        ...(options.policy !== undefined ? { policy: options.policy } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
+    });
+    const httpExtension = (app, context) => {
+        registerFrontendSessionRoutes(app, { registry }, context.adapter);
+    };
+    /**
+     * The error boundary the `onBindError` contract actually needs. A `RunStartHandler` throwing is
+     * not a no-op: `@jini-ai/http-kit`'s run-start route catches it, marks the run `failed` and answers
+     * 500 — so anything inside this hook that can throw can produce exactly the killed run that
+     * contract promises never to cause. `resolveBindToken` is host-supplied and reads an opaque host
+     * blob (a `JSON.parse` away from throwing), and the sink itself is host-supplied too. A sink that
+     * throws leaves nowhere left to report, so that one is swallowed rather than escalated.
+     */
+    const reportBindError = (context) => {
+        try {
+            onBindError(context);
+        }
+        catch {
+            // Deliberately terminal: the reporting channel is what failed.
+        }
+    };
+    const bindOnStarted = ({ request, run, lifecycle }) => {
+        let bindToken;
+        try {
+            bindToken = options.resolveBindToken(request);
+        }
+        catch (error) {
+            reportBindError({ runId: run.id, error });
+            return;
+        }
+        if (bindToken === undefined)
+            return;
+        let release;
+        try {
+            release = registry.bindRunByToken(run.id, bindToken);
+        }
+        catch (error) {
+            reportBindError({ runId: run.id, error });
+            return;
+        }
+        // Release on terminal so a tab that outlives many runs does not accumulate bindings for runs
+        // that ended. `waitForTerminal` rejecting is itself a reason to release, not to keep waiting,
+        // so both paths run it — and the whole chain is swallowed, because a bookkeeping failure must
+        // never surface as an unhandled rejection that takes the process down.
+        void lifecycle
+            .waitForTerminal(run.id)
+            .then(release, release)
+            .catch(() => undefined);
+    };
+    return { httpExtension, toolRegistrations, bindOnStarted };
+}
+//# sourceMappingURL=frontend-control.js.map

package/dist/frontend-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-control.js","sourceRoot":"","sources":["../src/frontend-control.ts"],"names":[],"mappings":"AAsCA,OAAO,EACL,qCAAqC,EACrC,6BAA6B,GAE9B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAmFvE,SAAS,oBAAoB,CAAC,OAAiC;IAC7D,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yCAAyC,OAAO,CAAC,KAAK,yBAAyB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AAChH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IACzE,iGAAiG;IACjG,MAAM,QAAQ,GAAG,6BAA6B,EAAE,CAAC;IACjD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAEhE,MAAM,iBAAiB,GAAG,qCAAqC,CAAC;QAC9D,QAAQ;QACR,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5F,CAAC,CAAC;IAEH,MAAM,aAAa,GAA0B,CAAC,GAAY,EAAE,OAAO,EAAE,EAAE;QACrE,6BAA6B,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,CAAC,CAAC;IAEF;;;;;;;OAOG;IACH,MAAM,eAAe,GAAG,CAAC,OAAiC,EAAQ,EAAE;QAClE,IAAI,CAAC;YACH,WAAW,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,aAAa,GAAoB,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAmB,EAAE,EAAE;QACtF,IAAI,SAA6B,CAAC;QAClC,IAAI,CAAC;YACH,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,eAAe,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QACD,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO;QAEpC,IAAI,OAAmB,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,eAAe,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,6FAA6F;QAC7F,8FAA8F;QAC9F,8FAA8F;QAC9F,uEAAuE;QACvE,KAAK,SAAS;aACX,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;aACvB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC;aACtB,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAC;AAC7D,CAAC"}

package/dist/frontend-sessions.d.ts

@@ -0,0 +1,100 @@
+import type { Express, Request, Response } from 'express';
+import type { FrontendSessionRegistry } from '@jini-ai/daemon';
+import { type AdapterContext } from './adapter.js';
+export declare const FRONTEND_SESSION_STREAM_ROUTE_PATH = "/api/frontend-sessions/stream";
+export declare const FRONTEND_SESSION_RESPONSE_ROUTE_PATH = "/api/frontend-sessions/:sessionId/responses";
+/** First event on the stream, telling the surface the id it must answer under. */
+export interface FrontendSessionAttachedEvent {
+    readonly type: 'attached';
+    readonly sessionId: string;
+    /**
+     * Secret this surface presents to bind a run to itself. Delivered here and nowhere else: this
+     * stream is the one channel already proven to belong to the surface that opened it.
+     *
+     * Never put this in a URL, a query string, or a log. It is separate from `sessionId` precisely
+     * because that id already travels in a request path (`…/:sessionId/responses`) and therefore
+     * leaks into access logs and proxies by design — see `@jini-ai/daemon`'s `FrontendSessionHandle`.
+     */
+    readonly bindToken: string;
+}
+/** One capability call for the surface to execute. */
+export interface FrontendSessionInvocationEvent {
+    readonly type: 'invocation';
+    readonly invocationId: string;
+    readonly capabilityId: string;
+    readonly input: Record<string, unknown>;
+}
+/** Sent instead of `attached` when the request itself was unusable; the stream then closes. */
+export interface FrontendSessionErrorEvent {
+    readonly type: 'error';
+    readonly message: string;
+}
+export type FrontendSessionStreamEvent = FrontendSessionAttachedEvent | FrontendSessionInvocationEvent | FrontendSessionErrorEvent;
+/**
+ * A surface's answer, as a discriminated union rather than a flat record with two optional fields.
+ *
+ * The parser already refuses a failure with no message, so `message?: string` alongside
+ * `ok: boolean` would let the type describe a state the parser guarantees cannot exist — and force
+ * a `?? 'no message'` fallback at the use site that no input could ever reach. Encoding the
+ * guarantee here removes the branch instead of leaving it to be covered by a test that would have
+ * to fabricate an impossible input.
+ */
+export type FrontendSessionResponseRequest = {
+    readonly sessionId: string;
+    readonly invocationId: string;
+    readonly ok: true;
+    readonly output?: unknown;
+} | {
+    readonly sessionId: string;
+    readonly invocationId: string;
+    readonly ok: false;
+    readonly message: string;
+};
+export interface FrontendSessionResponseBody {
+    /** `false` when the invocation was unknown or already settled — a duplicate answer, not an error. */
+    readonly settled: boolean;
+}
+export interface FrontendSessionsHttpDeps {
+    readonly registry: FrontendSessionRegistry;
+    /**
+     * Mints session ids. Defaults to `randomUUID`. A surface never supplies its own: an id the
+     * caller chose could collide with, or deliberately impersonate, a session already attached.
+     */
+    readonly newSessionId?: () => string;
+    /** Host-owned sink for failures that must not escape an async Express handler. Defaults to `console.error`. */
+    readonly onInternalError?: (context: {
+        readonly source: string;
+        readonly error: unknown;
+    }) => void;
+}
+/**
+ * Reads the repeatable `?capability=` query parameter.
+ *
+ * Express gives a single value as a string and repeats as an array; anything else (a nested object
+ * from a bracketed query string) is rejected rather than coerced.
+ */
+export declare function parseCapabilityQuery(raw: unknown): readonly string[] | null;
+/**
+ * Handles one surface's stream from open to close.
+ *
+ * SSE commits `text/event-stream` headers before anything else can be known, so a bad request is
+ * reported as one `{type:'error'}` data event and then closed — there is no status-code channel
+ * left. Same precedent as `run-stream.ts`.
+ */
+export declare function handleFrontendSessionStream(req: Request, res: Response, deps: FrontendSessionsHttpDeps): void;
+/**
+ * `POST /api/frontend-sessions/:sessionId/responses` — delivers a surface's answer to the tool
+ * handler awaiting it. Always `200`; `{settled:false}` reports a duplicate or unknown answer,
+ * which is an expected outcome rather than a transport error.
+ */
+export declare const frontendSessionResponseRoute: import("./types.js").JsonRouteSpec<FrontendSessionResponseRequest, FrontendSessionResponseBody, FrontendSessionsHttpDeps>;
+/**
+ * Mounts both frontend-session routes on `app`.
+ *
+ * The stream route bypasses `mountJsonRoute` (raw `app.get`, for the SSE response shape), so it
+ * does not get `requireSameOrigin` for free the way `frontendSessionResponseRoute` does — the
+ * guard is applied here directly, before the SSE channel is opened, so a cross-origin request
+ * never gets a stream (and, notably, never mints a session id or `bindToken` either).
+ */
+export declare function registerFrontendSessionRoutes(app: Express, deps: FrontendSessionsHttpDeps, adapter: AdapterContext): void;
+//# sourceMappingURL=frontend-sessions.d.ts.map

package/dist/frontend-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-sessions.d.ts","sourceRoot":"","sources":["../src/frontend-sessions.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAyB,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAOpF,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,eAAO,MAAM,oCAAoC,gDAAgD,CAAC;AAElG,kFAAkF;AAClF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,+FAA+F;AAC/F,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,0BAA0B,GAClC,4BAA4B,GAC5B,8BAA8B,GAC9B,yBAAyB,CAAC;AAE9B;;;;;;;;GAQG;AACH,MAAM,MAAM,8BAA8B,GACtC;IACA,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B,GACC;IACA,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEJ,MAAM,WAAW,2BAA2B;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IACrC,+GAA+G;IAC/G,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CACpG;AAcD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAQ3E;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,wBAAwB,GAC7B,IAAI,CAgCN;AAiCD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,2HAmBvC,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,cAAc,GACtB,IAAI,CAmBN"}

package/dist/frontend-sessions.js

@@ -0,0 +1,180 @@
+/**
+ * @module frontend-sessions
+ *
+ * The transport half of `@jini-ai/daemon`'s `FrontendSessionRegistry`: how a browser surface reaches
+ * the daemon, and how the daemon reaches back into it.
+ *
+ * Two routes, because the connection *is* the session:
+ *
+ * - `GET /api/frontend-sessions/stream` opens an SSE channel. The daemon mints the session id,
+ *   attaches the surface, sends `{type:'attached', sessionId}` as the first event, and pushes one
+ *   `{type:'invocation', ...}` per capability call. When the connection closes for any reason —
+ *   navigation, a crashed tab, a pulled network cable — the surface is detached and every
+ *   invocation still awaiting it is failed.
+ * - `POST /api/frontend-sessions/:sessionId/responses` carries the surface's answer back.
+ *
+ * There is deliberately **no separate register/unregister pair**. A surface whose lifetime is a
+ * `POST` to create and a `DELETE` to destroy leaks a session every time a tab dies without running
+ * its unload handler, and those leaked sessions keep claiming capabilities they can no longer
+ * serve. Tying the lifetime to the stream makes the failure mode impossible instead of unlikely.
+ *
+ * **The response route does not execute anything.** It settles a promise that a `ToolHandler` is
+ * already awaiting, so the call it answers has already passed `ToolExecutor`'s authorization,
+ * confirmation, timeout, cancellation, truncation, and audit. An answer for an unknown or
+ * already-settled invocation is reported as `{settled:false}` rather than being an error: a stream
+ * reconnect or a retried POST is expected, not exceptional.
+ *
+ * Binding a run to a session is NOT exposed here. Which surface owns a run is a decision only the
+ * composition root can make (it is the thing that starts runs), so it calls `registry.bindRun`
+ * directly — see `@jini-ai/daemon`'s own module doc for why attach and bind are separate.
+ */
+import { randomUUID } from 'node:crypto';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { guardSameOrigin } from './origin.js';
+import { createSseResponse } from './raw-sse.js';
+import { validationError } from './request.js';
+import { sendApiError, statusForError } from './response.js';
+import { err, ok } from './types.js';
+export const FRONTEND_SESSION_STREAM_ROUTE_PATH = '/api/frontend-sessions/stream';
+export const FRONTEND_SESSION_RESPONSE_ROUTE_PATH = '/api/frontend-sessions/:sessionId/responses';
+function reportInternalError(deps, source, error) {
+    try {
+        if (deps.onInternalError)
+            deps.onInternalError({ source, error });
+        // eslint-disable-next-line no-console
+        else
+            console.error(`[@jini-ai/http-kit] internal error (frontend-sessions:${source})`, error);
+    }
+    catch (sinkError) {
+        // A diagnostic sink must never turn a contained failure into an unhandled rejection of its own.
+        // eslint-disable-next-line no-console
+        console.error(`[@jini-ai/http-kit] internal error sink failed (frontend-sessions:${source})`, sinkError);
+    }
+}
+/**
+ * Reads the repeatable `?capability=` query parameter.
+ *
+ * Express gives a single value as a string and repeats as an array; anything else (a nested object
+ * from a bracketed query string) is rejected rather than coerced.
+ */
+export function parseCapabilityQuery(raw) {
+    const values = raw === undefined ? [] : (Array.isArray(raw) ? raw : [raw]);
+    const capabilities = [];
+    for (const value of values) {
+        if (typeof value !== 'string' || value.trim().length === 0)
+            return null;
+        capabilities.push(value);
+    }
+    return capabilities;
+}
+/**
+ * Handles one surface's stream from open to close.
+ *
+ * SSE commits `text/event-stream` headers before anything else can be known, so a bad request is
+ * reported as one `{type:'error'}` data event and then closed — there is no status-code channel
+ * left. Same precedent as `run-stream.ts`.
+ */
+export function handleFrontendSessionStream(req, res, deps) {
+    const capabilities = parseCapabilityQuery(req.query['capability']);
+    // Assigned below, after the connection exists — `attach` needs something to deliver through, and
+    // `onClose` has to be armed before then so a connection that dies during setup still detaches.
+    let handle;
+    const connection = createSseResponse(req, res, {
+        // Detach on close rather than on an explicit teardown call: this fires for a closed tab and a
+        // dropped connection too, which an unregister route would not.
+        onClose: () => handle?.detach(),
+    });
+    if (capabilities === null) {
+        connection.send({
+            type: 'error',
+            message: 'each "capability" query parameter must be a non-empty string',
+        });
+        connection.close();
+        return;
+    }
+    const sessionId = (deps.newSessionId ?? randomUUID)();
+    handle = deps.registry.attach({ sessionId, capabilities }, (invocation) => connection.send({ type: 'invocation', ...invocation }));
+    connection.send({
+        type: 'attached',
+        sessionId,
+        bindToken: handle.bindToken,
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseFrontendSessionResponse(input) {
+    const sessionId = input.params['sessionId'];
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        return err(validationError('sessionId must be a non-empty string', [{ path: 'sessionId', message: 'required non-empty string' }]));
+    }
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const invocationId = input.body['invocationId'];
+    if (typeof invocationId !== 'string' || invocationId.trim().length === 0) {
+        return err(validationError('invocationId must be a non-empty string', [{ path: 'invocationId', message: 'required non-empty string' }]));
+    }
+    const okFlag = input.body['ok'];
+    if (typeof okFlag !== 'boolean') {
+        return err(validationError('ok must be a boolean', [{ path: 'ok', message: 'required boolean' }]));
+    }
+    if (!okFlag) {
+        const message = input.body['message'];
+        if (typeof message !== 'string' || message.trim().length === 0) {
+            // A failure with no reason gives the agent nothing to act on, which is how a caller ends up
+            // retrying the same refusal forever.
+            return err(validationError('message must be a non-empty string when ok is false', [{ path: 'message', message: 'required when ok is false' }]));
+        }
+        return ok({ sessionId, invocationId, ok: false, message });
+    }
+    return ok({ sessionId, invocationId, ok: true, output: input.body['output'] });
+}
+/**
+ * `POST /api/frontend-sessions/:sessionId/responses` — delivers a surface's answer to the tool
+ * handler awaiting it. Always `200`; `{settled:false}` reports a duplicate or unknown answer,
+ * which is an expected outcome rather than a transport error.
+ */
+export const frontendSessionResponseRoute = defineJsonRoute({
+    method: 'post',
+    path: FRONTEND_SESSION_RESPONSE_ROUTE_PATH,
+    requireSameOrigin: true,
+    parse: parseFrontendSessionResponse,
+    handle: (input, deps) => {
+        const settled = deps.registry.settle(input.sessionId, input.invocationId, input.ok
+            ? { ok: true, output: input.output }
+            : { ok: false, message: input.message });
+        return ok({ settled });
+    },
+});
+/**
+ * Mounts both frontend-session routes on `app`.
+ *
+ * The stream route bypasses `mountJsonRoute` (raw `app.get`, for the SSE response shape), so it
+ * does not get `requireSameOrigin` for free the way `frontendSessionResponseRoute` does — the
+ * guard is applied here directly, before the SSE channel is opened, so a cross-origin request
+ * never gets a stream (and, notably, never mints a session id or `bindToken` either).
+ */
+export function registerFrontendSessionRoutes(app, deps, adapter) {
+    app.get(FRONTEND_SESSION_STREAM_ROUTE_PATH, (req, res) => {
+        const origin = guardSameOrigin(req, adapter);
+        if (!origin.ok) {
+            sendApiError(res, statusForError(origin.error), origin.error);
+            return;
+        }
+        try {
+            handleFrontendSessionStream(req, res, deps);
+        }
+        catch (error) {
+            reportInternalError(deps, 'stream', error);
+            if (!res.headersSent) {
+                res.status(500).json({ error: createApiError('INTERNAL_ERROR', 'an internal error occurred') });
+            }
+            else if (!res.writableEnded) {
+                res.end();
+            }
+        }
+    });
+    mountJsonRoute(app, frontendSessionResponseRoute, deps, adapter);
+}
+//# sourceMappingURL=frontend-sessions.js.map

package/dist/frontend-sessions.js.map

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

package/dist/health.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module health
+ *
+ * `GET /health`, `GET /api/health` (plain liveness — always `200 {ok: true, version}` once the
+ * process is up, no dependency checks), `GET /ready`, `GET /api/ready` (real readiness —
+ * delegates to an injected `checkReadiness`, `503` when it reports `ok: false`), and `GET
+ * /version`, `GET /api/version` (echoes the running build's version). Both the mount-relative
+ * and `/api`-prefixed form of each probe are registered because `api-security-middleware.ts`'s
+ * `OPEN_PROBE_PATHS` already anticipated exactly these six paths as always-open (no bearer token,
+ * no origin check) — this module is what finally makes that anticipated set of paths real routes
+ * instead of an open gate over nothing.
+ *
+ * **Mount before `express.json()`/the bearer-auth/origin-guard middleware** (see
+ * `@jini-ai/server`'s `create-local-node-daemon.ts` wiring): these are simple parameterless GETs
+ * with no request body, so nothing here needs JSON body-parsing, and a monitoring probe should
+ * never need a bearer token or same-origin `Origin` header just to confirm the process is up —
+ * the same reasoning `api-security-middleware.ts`'s own doc already gives for exempting these
+ * paths.
+ *
+ * **`daemon-status.ts#daemonStatusRoute`'s own doc previously called `GET /api/daemon/status` "a
+ * health-check" — this module is the real, purpose-built answer to that now.** `/api/daemon/status`
+ * still exists and still reports version/host/port/data-dir/shutdown state (useful operator
+ * detail), but a liveness/readiness monitor should poll `/health`/`/ready` instead: those are
+ * unauthenticated by design (see above), `/api/daemon/status` is not gated same-origin either
+ * today, but was never *documented* as the liveness contract — see that module's updated doc
+ * comment.
+ *
+ * **OD-parity, verified live 2026-07-22** by booting a real Open Design daemon (`apps/daemon/bin/
+ * od.mjs --no-open`, from a full clone of `nexu-io/open-design`) and curling its real
+ * `/api/health`, `/api/ready`, `/api/version` handlers (`apps/daemon/src/server.ts:2624-2642`).
+ * Live responses observed: `GET /api/health` → `200 {"ok":true,"version":"0.15.1"}`; `GET
+ * /api/ready` → `200 {"ok":true,"ready":true,"version":"0.15.1"}` (the handler's readiness check
+ * is a single `!daemonShuttingDown` boolean, not a pluggable checks map — `server.ts:2629-2637`);
+ * `GET /api/version` → `200 {"version":{"version":"0.15.1","channel":"development",
+ * "packaged":false,"platform":"darwin","arch":"x64"}}` (the full `AppVersionInfo` shape from
+ * `app-version.ts:12-18`, nested under the `version` key — not a bare string). Confirmed OD
+ * registers no bare (non-`/api`-prefixed) `/health`/`/ready`/`/version` routes at all (`GET
+ * /health` 404s live) — this module's mount-relative variants are a deliberate Jini generalization
+ * for hosts that don't prefix their API under `/api`, not an OD-observed route. Also confirmed no
+ * origin/CORS headers appear on any of the three live OD responses — `requireLocalDaemonRequest`
+ * (`http/local-daemon-request.ts`), which is what stamps `Vary: Origin`/`Access-Control-*`
+ * headers on other `/api/daemon/*` routes like shutdown, is never applied to health/ready/version,
+ * matching this module's `requireSameOrigin`-unset routes.
+ *
+ * Two real gaps that live comparison caught and this module now fixes: `livenessRoute` and
+ * `readinessRoute` used to omit `version` entirely, and `readinessRoute`'s success body had no
+ * `ready` field — both now present, sourced from the same `deps.getVersion()` already wired for
+ * `/version`. One gap intentionally left open: `/version`'s response here stays a flat `{version:
+ * string}` (via the same string-returning `getVersion` convention `daemon-status.ts` already
+ * uses) rather than OD's nested `AppVersionInfo` object — the channel/packaged/platform/arch
+ * fields aren't wired anywhere in Jini today (`@jini-ai/server`'s `create-local-node-daemon.ts`
+ * only ever supplies a plain version string), and inventing that plumbing is a host-level decision
+ * out of this file's scope, not something to paper over with an unused type change here.
+ */
+import type { Express } from 'express';
+import { type AdapterContext } from './adapter.js';
+export interface HealthReadinessResult {
+    readonly ok: boolean;
+    readonly checks: Record<string, boolean>;
+}
+export interface HealthHttpDeps {
+    /** Resolves the running build's version string. May be sync or async, matching `daemon-status.ts#DaemonStatusDeps.getVersion`. */
+    readonly getVersion: () => Promise<string> | string;
+    /** Host-owned readiness probe (e.g. "is the sqlite handle healthy and is the process not mid-shutdown"). Defaults to always-ready (`{ok: true, checks: {}}`) — a host with nothing worth checking gets a working route with no wiring required. */
+    readonly checkReadiness?: () => Promise<HealthReadinessResult>;
+}
+export interface LivenessResponse {
+    readonly ok: true;
+    /** The running build's version string. Matches OD's real `/api/health` — see module doc. */
+    readonly version: string;
+}
+export interface ReadinessResponse {
+    readonly ok: true;
+    /** Mirrors `ok` — OD's real `/api/ready` carries both fields; see module doc. */
+    readonly ready: true;
+    /** The running build's version string. Matches OD's real `/api/ready` — see module doc. */
+    readonly version: string;
+    readonly checks: Record<string, boolean>;
+}
+export interface VersionResponse {
+    readonly version: string;
+}
+export declare const healthRoute: import("./types.js").JsonRouteSpec<void, LivenessResponse, HealthHttpDeps>;
+export declare const apiHealthRoute: import("./types.js").JsonRouteSpec<void, LivenessResponse, HealthHttpDeps>;
+export declare const readyRoute: import("./types.js").JsonRouteSpec<void, ReadinessResponse, HealthHttpDeps>;
+export declare const apiReadyRoute: import("./types.js").JsonRouteSpec<void, ReadinessResponse, HealthHttpDeps>;
+export declare const versionInfoRoute: import("./types.js").JsonRouteSpec<void, VersionResponse, HealthHttpDeps>;
+export declare const apiVersionInfoRoute: import("./types.js").JsonRouteSpec<void, VersionResponse, HealthHttpDeps>;
+/** Mounts all six health/readiness/version routes on `app`. Call this before installing `express.json()`/the bearer-auth/origin-guard middleware — see module doc. */
+export declare function registerHealthRoutes(app: Express, deps: HealthHttpDeps, adapter: AdapterContext): void;
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAGpF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,kIAAkI;IAClI,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACpD,mPAAmP;IACnP,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAChE;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAoCD,eAAO,MAAM,WAAW,4EAA2B,CAAC;AACpD,eAAO,MAAM,cAAc,4EAA+B,CAAC;AAC3D,eAAO,MAAM,UAAU,6EAA2B,CAAC;AACnD,eAAO,MAAM,aAAa,6EAA+B,CAAC;AAC1D,eAAO,MAAM,gBAAgB,2EAA2B,CAAC;AACzD,eAAO,MAAM,mBAAmB,2EAA+B,CAAC;AAEhE,sKAAsK;AACtK,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAOtG"}