@jini-ai/server 0.0.0-stage → 0.5.0

package/dist/feature.js

@@ -0,0 +1,94 @@
+/**
+ * The runtime half of {@link CapabilityId}.
+ *
+ * Declared as a `Record<CapabilityId, true>` rather than a plain array so drift is a compile error
+ * in **both** directions: a union member missing here fails the `Record`'s exhaustiveness, and a
+ * key here that is not in the union fails the object literal's excess-property check. A validation
+ * list that can silently fall behind the type it validates is worse than none, because it reads as
+ * closed while quietly admitting whatever was added last.
+ */
+const CAPABILITY_ID_SET = Object.freeze({
+    'run:transport': true,
+    'run:inject': true,
+    'agent:discovery': true,
+    'tool:delegated': true,
+    'tool:catalog': true,
+    'host:read': true,
+    'host:exec': true,
+    'db:admin': true,
+    'net:egress': true,
+    'daemon:control': true,
+    'memory:store': true,
+    'routines:schedule': true,
+    'media:generate': true,
+    'ui:session': true,
+});
+/** Every capability this vocabulary declares, for error messages and for exhaustive iteration. */
+export const CAPABILITY_IDS = Object.freeze(Object.keys(CAPABILITY_ID_SET));
+/** Whether `value` names a capability this vocabulary actually declares. */
+export function isCapabilityId(required) {
+    return Object.prototype.hasOwnProperty.call(CAPABILITY_ID_SET, required.value);
+}
+/**
+ * The capabilities a feature may default to *on* under the `core-only` activation policy — the
+ * run transport, installed-agent discovery and the delegated-tool gateway. These are the frozen
+ * embedding contract; adding host execution or network egress would expand the security ceiling.
+ *
+ * A feature qualifies only if **every** capability it provides is in here, so a feature that mixes
+ * a core capability with a non-core one (say `run:transport` plus `host:exec`) does not sneak in on
+ * the strength of its safe half.
+ */
+export const CORE_CAPABILITIES = Object.freeze([
+    'run:transport',
+    'agent:discovery',
+    'tool:delegated',
+]);
+/** Identity helper that pins a feature's shape at the definition site. */
+export function defineJiniFeature(feature) {
+    return feature;
+}
+/**
+ * The shipped profiles. **Versioned and immutable**: a future capability must never silently join
+ * an existing profile's grant set, because a consumer pinned to `local-daemon-v1` chose the
+ * authority surface it had on the day it pinned. A new set is a new id (`-v2`), not an edit.
+ *
+ * Both name a *capability grant*, never a hand-listed feature array — so the active feature list is
+ * always computed from capability semantics and cannot drift away from them when a feature is
+ * added, renamed, or reclassified.
+ */
+export const JINI_PROFILES = Object.freeze({
+    /**
+     * The conservative embedding default: run transport, agent discovery and delegated tools.
+     * Everything that adds host execution, network egress, database administration or daemon control
+     * is outside the grant, so it can be
+     * neither defaulted on nor explicitly enabled without the host first raising the ceiling.
+     */
+    'agent-core-v1': Object.freeze({
+        id: 'agent-core-v1',
+        grants: Object.freeze(['run:transport', 'agent:discovery', 'tool:delegated']),
+        activation: 'core-only',
+    }),
+    /**
+     * `createLocalNodeDaemon`'s historical surface, frozen as a compatibility profile: exactly the
+     * capabilities the standalone daemon has always mounted. `run:inject`, `memory:store`,
+     * `routines:schedule`, `media:generate` and `ui:session` are **absent by design** — those route
+     * families were never wired by that preset, and granting them here would silently expand a
+     * shipped daemon's surface.
+     */
+    'local-daemon-v1': Object.freeze({
+        id: 'local-daemon-v1',
+        grants: Object.freeze([
+            'run:transport',
+            'agent:discovery',
+            'tool:delegated',
+            'tool:catalog',
+            'host:read',
+            'host:exec',
+            'db:admin',
+            'net:egress',
+            'daemon:control',
+        ]),
+        activation: 'all-permitted',
+    }),
+});
+//# sourceMappingURL=feature.js.map

package/dist/frontend-control.d.ts

@@ -0,0 +1,76 @@
+import type { ToolPolicy, ToolRegistration } from '@jini-ai/core';
+import { type FrontendCapabilitySpec } from '@jini-ai/daemon';
+import { type RunCreateRequest, type RunStartHandler } from '@jini-ai/http-kit';
+import type { LocalNodeHttpExtension } from './create-local-node-daemon.js';
+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 `httpExtensions`. */
+    readonly httpExtension: LocalNodeHttpExtension;
+    /** 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.js

@@ -0,0 +1,77 @@
+import { createFrontendCapabilityRegistrations, createFrontendSessionRegistry, } from '@jini-ai/daemon';
+import { registerFrontendSessionRoutes, } from '@jini-ai/http-kit';
+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/host-bootstrap.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module host-bootstrap
+ *
+ * Generic host-lifecycle primitives ported from an origin daemon's CLI-startup module — see
+ * `archived provenance ledger`. Only the two functions with no CLI-flag-parsing or env-var-reading inside their
+ * own bodies are ported here: `parseDaemonCliStartupArgs` (argv/env parsing for a `od <cmd>`-style
+ * CLI) and the higher-level `startDaemonRuntime`/`runDaemonCliStartup` wrappers belong to a future
+ * `@jini-ai/cli` task, not this one — this module is deliberately CLI-shape-agnostic.
+ */
+import type { Server } from 'node:http';
+export declare const DEFAULT_DAEMON_BIND_HOST = "127.0.0.1";
+/**
+ * Trims `input` to a usable bind-host string, falling back to the loopback default for
+ * blank/nullish input.
+ *
+ * @param input - A caller-supplied host value of unknown shape (typically `string | undefined`
+ * from an options object, hence the deliberately loose `unknown` parameter type).
+ * @returns The trimmed stringification of `input`, or {@link DEFAULT_DAEMON_BIND_HOST} when
+ * `input` is nullish or its stringification trims to empty. Nonstrings deliberately retain the
+ * historical coercion, so a supplied number is not silently replaced with the loopback host.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function normalizeDaemonBindHost(input: unknown): string;
+export interface CloseHttpServerOptions {
+    /** Hard ceiling before force-closing every remaining socket. Defaults to 5000ms. */
+    closeTimeoutMs?: number;
+    /** Delay before closing idle (non-active) connections, capped by `closeTimeoutMs`. Defaults to 1000ms. */
+    idleCloseMs?: number;
+}
+/**
+ * Gracefully closes `server`: after a short `idleCloseMs` grace period it closes idle
+ * connections, then force-closes any connection still open once `closeTimeoutMs` elapses. Resolves
+ * immediately, without touching any socket, if `server` is not currently listening.
+ *
+ * @param server - The `node:http` server to close.
+ * @param options.closeTimeoutMs - See {@link CloseHttpServerOptions}.
+ * @param options.idleCloseMs - See {@link CloseHttpServerOptions}.
+ * @returns Resolves once `server.close()`'s callback fires with no error, or once the hard timeout
+ * force-closes connections, whichever happens first. The deadline deliberately bounds shutdown
+ * even if the callback never arrives; any later callback is ignored after settlement.
+ * @throws Rejects with whatever error `server.close()`'s callback reports (e.g. calling `close()`
+ * on a server that was never listening in the first place — guarded against above by the early
+ * return). Errors received before settlement propagate; callbacks after the hard deadline do not
+ * replace its already-settled result.
+ * @complexity O(1) scheduling; the actual wait is bounded by `closeTimeoutMs`.
+ * @overallScore 100/100
+ */
+export declare function closeHttpServer(server: Server, options?: CloseHttpServerOptions): Promise<void>;
+export interface GracefulShutdownOptions {
+    /** Host signal/exit adapter. The default preserves Node's process-global signal handling. */
+    process?: ShutdownProcessPort;
+    /** Node timer ABI, injectable so a host controls shutdown scheduling. */
+    timers?: Pick<typeof globalThis, 'setTimeout' | 'clearTimeout'>;
+    /** Node console ABI; timeout and failure messages retain their historical arguments. */
+    logger?: Pick<Console, 'error'>;
+    /** OS signals to listen for. Defaults to `['SIGTERM', 'SIGINT']` — the two a container runtime,
+     * process manager, or an operator's `kill`/Ctrl-C ordinarily send to stop a long-lived daemon. */
+    signals?: readonly NodeJS.Signals[];
+    /** Hard ceiling, from the first signal, before forcing exit even if `stop()` never settles — a
+     * wedged shutdown must not block the process from ever exiting. Defaults to 10000ms (Docker's own
+     * default grace period before it escalates to `SIGKILL`). */
+    timeoutMs?: number;
+    /** Called exactly once, with `0` if `stop()` resolved or `1` if it rejected or the timeout fired
+     * first. Defaults to the supplied process port's exit (Node process.exit by default). Override to observe or customize the final step (tests always
+     * do this — calling the real `process.exit` from a unit test would kill the test runner). */
+    onExit?: (code: number) => void;
+}
+/** Minimal Node signal ABI; embedders can supply their own process without seizing global listeners. */
+export interface ShutdownProcessPort {
+    on(signal: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): unknown;
+    off(signal: NodeJS.Signals, listener: (signal: NodeJS.Signals) => void): unknown;
+    exit(code: number): unknown;
+}
+export interface GracefulShutdownHandle {
+    /** Removes the installed signal listeners. A later signal is then a plain no-op — Node's own
+     * default behavior applies again, exactly as if this had never been called. */
+    uninstall(): void;
+}
+/**
+ * Wires `stop` to the process's OS shutdown signals so a container stop, process-manager restart, or
+ * operator `kill`/Ctrl-C runs the caller's graceful teardown instead of Node's default immediate
+ * termination. Deliberately opt-in rather than something `createLocalNodeDaemon` installs on every
+ * caller's behalf: a library that unilaterally seizes process-global signal handling can surprise an
+ * embedding host that manages its own process lifecycle (an Electron shell, for one, already owns
+ * its own fatal-exception handling and — per `desktop-host`'s own sidecar shutdown path — asks a
+ * spawned daemon child to stop over HTTP and falls back to `SIGKILL`, never `SIGTERM`, so it neither
+ * needs nor should double up on this). One line at the host's own entrypoint —
+ * `installGracefulShutdown({ stop: daemon.stop })` — is the whole integration.
+ *
+ * Idempotent and re-entrant: a second signal that arrives while a shutdown from the first is still
+ * in flight is ignored outright (not queued, not a second `stop()` call) — the in-flight shutdown
+ * (or, past `timeoutMs`, the forced exit) is left to finish on its own.
+ *
+ * @param stop - The caller's own graceful-shutdown function, e.g. a `LocalNodeDaemon.stop`.
+ * @param options - See {@link GracefulShutdownOptions}.
+ * @returns A handle whose `uninstall()` removes the installed listeners.
+ * @complexity O(1) to install; the signal handler itself is O(1) plus whatever `stop` costs.
+ */
+export declare function installGracefulShutdown({ stop }: {
+    stop: () => Promise<void>;
+}, options?: GracefulShutdownOptions): GracefulShutdownHandle;
+//# sourceMappingURL=host-bootstrap.d.ts.map

package/dist/host-bootstrap.js

@@ -0,0 +1,146 @@
+export const DEFAULT_DAEMON_BIND_HOST = '127.0.0.1';
+/**
+ * Trims `input` to a usable bind-host string, falling back to the loopback default for
+ * blank/nullish input.
+ *
+ * @param input - A caller-supplied host value of unknown shape (typically `string | undefined`
+ * from an options object, hence the deliberately loose `unknown` parameter type).
+ * @returns The trimmed stringification of `input`, or {@link DEFAULT_DAEMON_BIND_HOST} when
+ * `input` is nullish or its stringification trims to empty. Nonstrings deliberately retain the
+ * historical coercion, so a supplied number is not silently replaced with the loopback host.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function normalizeDaemonBindHost(input) {
+    const host = String(input ?? '').trim();
+    return host || DEFAULT_DAEMON_BIND_HOST;
+}
+/**
+ * Gracefully closes `server`: after a short `idleCloseMs` grace period it closes idle
+ * connections, then force-closes any connection still open once `closeTimeoutMs` elapses. Resolves
+ * immediately, without touching any socket, if `server` is not currently listening.
+ *
+ * @param server - The `node:http` server to close.
+ * @param options.closeTimeoutMs - See {@link CloseHttpServerOptions}.
+ * @param options.idleCloseMs - See {@link CloseHttpServerOptions}.
+ * @returns Resolves once `server.close()`'s callback fires with no error, or once the hard timeout
+ * force-closes connections, whichever happens first. The deadline deliberately bounds shutdown
+ * even if the callback never arrives; any later callback is ignored after settlement.
+ * @throws Rejects with whatever error `server.close()`'s callback reports (e.g. calling `close()`
+ * on a server that was never listening in the first place — guarded against above by the early
+ * return). Errors received before settlement propagate; callbacks after the hard deadline do not
+ * replace its already-settled result.
+ * @complexity O(1) scheduling; the actual wait is bounded by `closeTimeoutMs`.
+ * @overallScore 100/100
+ */
+export async function closeHttpServer(server, options = {}) {
+    const { closeTimeoutMs = 5_000, idleCloseMs = 1_000 } = options;
+    if (!server.listening)
+        return;
+    await new Promise((resolveClose, rejectClose) => {
+        let resolved = false;
+        const resolveOnce = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(idleTimer);
+            clearTimeout(hardTimer);
+            resolveClose();
+        };
+        const rejectOnce = (error) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(idleTimer);
+            clearTimeout(hardTimer);
+            rejectClose(error);
+        };
+        const idleTimer = setTimeout(() => {
+            server.closeIdleConnections?.();
+        }, Math.min(idleCloseMs, closeTimeoutMs));
+        const hardTimer = setTimeout(() => {
+            server.closeAllConnections?.();
+            resolveOnce();
+        }, closeTimeoutMs);
+        idleTimer.unref?.();
+        hardTimer.unref?.();
+        server.close((error) => (error == null ? resolveOnce() : rejectOnce(error)));
+    }).finally(() => {
+        server.closeIdleConnections?.();
+    });
+}
+/**
+ * Wires `stop` to the process's OS shutdown signals so a container stop, process-manager restart, or
+ * operator `kill`/Ctrl-C runs the caller's graceful teardown instead of Node's default immediate
+ * termination. Deliberately opt-in rather than something `createLocalNodeDaemon` installs on every
+ * caller's behalf: a library that unilaterally seizes process-global signal handling can surprise an
+ * embedding host that manages its own process lifecycle (an Electron shell, for one, already owns
+ * its own fatal-exception handling and — per `desktop-host`'s own sidecar shutdown path — asks a
+ * spawned daemon child to stop over HTTP and falls back to `SIGKILL`, never `SIGTERM`, so it neither
+ * needs nor should double up on this). One line at the host's own entrypoint —
+ * `installGracefulShutdown({ stop: daemon.stop })` — is the whole integration.
+ *
+ * Idempotent and re-entrant: a second signal that arrives while a shutdown from the first is still
+ * in flight is ignored outright (not queued, not a second `stop()` call) — the in-flight shutdown
+ * (or, past `timeoutMs`, the forced exit) is left to finish on its own.
+ *
+ * @param stop - The caller's own graceful-shutdown function, e.g. a `LocalNodeDaemon.stop`.
+ * @param options - See {@link GracefulShutdownOptions}.
+ * @returns A handle whose `uninstall()` removes the installed listeners.
+ * @complexity O(1) to install; the signal handler itself is O(1) plus whatever `stop` costs.
+ */
+export function installGracefulShutdown({ stop }, options = {}) {
+    const signalProcess = options.process ?? process;
+    const timers = options.timers ?? globalThis;
+    const logger = options.logger ?? console;
+    const signals = options.signals ?? ['SIGTERM', 'SIGINT'];
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const onExit = options.onExit ?? ((code) => { signalProcess.exit(code); });
+    let shuttingDown = false;
+    const handleSignal = (signal) => {
+        // A second signal while a shutdown is already in flight must not re-run `stop()` or restart the
+        // timeout — the first attempt (or its forced-exit fallback below) already owns getting the
+        // process to exit.
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        let timedOut = false;
+        const timer = timers.setTimeout(() => {
+            timedOut = true;
+            // eslint-disable-next-line no-console
+            logger.error(`[@jini-ai/server] graceful shutdown did not complete within ${timeoutMs}ms after ${signal}; forcing exit`);
+            onExit(1);
+        }, timeoutMs);
+        timer.unref?.();
+        void stop()
+            .catch((error) => {
+            // eslint-disable-next-line no-console
+            logger.error(`[@jini-ai/server] graceful shutdown failed after ${signal}`, error);
+            // Re-thrown so the `.finally` below still distinguishes success from failure via rejection
+            // state rather than a second flag.
+            throw error;
+        })
+            .then(() => {
+            if (timedOut)
+                return;
+            timers.clearTimeout(timer);
+            onExit(0);
+        }, () => {
+            if (timedOut)
+                return;
+            timers.clearTimeout(timer);
+            onExit(1);
+        });
+    };
+    for (const signal of signals) {
+        signalProcess.on(signal, handleSignal);
+    }
+    return {
+        uninstall() {
+            for (const signal of signals) {
+                signalProcess.off(signal, handleSignal);
+            }
+        },
+    };
+}
+//# sourceMappingURL=host-bootstrap.js.map

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @module @jini-ai/server
+ *
+ * The Node.js host preset (extraction-plan.md §2.4): `createLocalNodeDaemon`, the piece that
+ * assembles `@jini-ai/core`/`@jini-ai/daemon`/concern-owned storage adapters/`@jini-ai/http-kit` into an actually-runnable
+ * daemon process, plus the generic host-lifecycle primitives it's built on. See `archived provenance ledger`
+ * for full provenance and scope-decision notes.
+
+ * Archived provenance rationale:
+ * ## Design decisions
+ *
+ * **1. Two function overloads instead of one generic signature with a defaulted `BoundIds`.** The
+ * task brief's literal shown signature was
+ * `createLocalNodeDaemon<const Packs, BoundIds extends string = KernelBoundIds>(config: ...)`.
+ * Empirically verified against this repo's TypeScript (5.9.3, `strict`) that this shape does not
+ * actually preserve `createDaemon`'s compile-time "missing binding" gate: when a type parameter both
+ * has a default *and* is referenced inside a conditional type in the same position where it also
+ * needs inference from a nested callback's return type, TypeScript resolves it to the default
+ * instead of inferring from the callback — silently defeating the gate on exactly the call shape
+ * (`bindings` customizer provided) where it matters most. Fixed by splitting into two overloads — one
+ * where `bindings` is absent and `BoundIds` is the concrete `KernelBoundIds`, one where `bindings` is
+ * required and `BoundIds` is inferred fresh with no default — which sidesteps the inference conflict
+ * entirely. Both directions (and an under-binding customizer, and a satisfied customizer) are proven
+ * in `create-local-node-daemon.typecheck.ts`. Documented in full inline on the exported function.
+ *
+ * **2. `resolveBoundPort`/`resolveReportHost` extracted as small pure, exported helpers.** The
+ * origin's `.listen()` tail inlined both the "is `server.address()` actually usable" check and the
+ * "substitute 127.0.0.1 for an all-interfaces bind host" substitution directly in the `'listening'`
+ * callback. Pulling them out makes two genuinely-defensive branches (a `server.address()` that is
+ * `null`/a Unix-socket-path string/a non-positive port — provably unreachable via any real TCP
+ * listener once `'listening'` has fired, per the origin's own "belt-and-braces" framing) directly
+ * unit-testable without mocking Express or the underlying socket at all.
+ *
+ * **3. `@jini/core/internal`'s `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-export.** Needed so
+ * this package could re-derive `createDaemon`'s exact compile-time gate rather than duplicate the
+ * type-level logic. See `packages/core/src/internal.ts`'s own module doc and
+ * `packages/core/src/daemon.ts` — these three types are now `export`ed there (previously
+ * module-private) but deliberately *not* re-exported from `@jini/core`'s public `index.ts` (which
+ * switched from a `daemon.js` wildcard re-export to an explicit named list for exactly this reason).
+ *
+ * **4. `createDaemon`'s own compile-time gate is bypassed (via a cast) inside
+ * `createLocalNodeDaemon`'s implementation body**, the same way
+ * `packages/core/src/__tests__/index.test.ts`'s `createDaemonUnsafe` reaches `createDaemon`'s runtime
+ * path directly: `Packs`/`BoundIds` are still abstract, unresolved type parameters inside a generic
+ * function body, so `createDaemon`'s own conditional gate can never collapse to a definite branch
+ * there regardless of which overload the real call site matched. Safety was already established by
+ * this function's own equivalent gate (present on both exported overloads) at the real call site.
+ *
+ * **5. `stop()` always closes the durable `EventLog`, even when the caller's `onShutdown` hook
+ * rejects** — `try { await config.onShutdown?.() } finally { await eventLog.close() }` — so a
+ * caller-supplied hook failing can never leak an open sqlite file handle; the original rejection
+ * still propagates to whoever awaited `stop()`.
+ *
+ * **6. `env[JINI_BIND_HOST]` is set before serving any request — a documented, only-partially-fixable
+ * wrinkle.** `@jini/http`'s own `guardSameOrigin` (used by `registerDaemonStatusRoutes`' shutdown
+ * route) resolves `bindHost` purely from real `process.env.JINI_BIND_HOST`, with **no parameter path**
+ * of its own — unlike most of that module's other functions, it never accepts an injected `env`.
+ * `createLocalNodeDaemon` sets `env[JINI_BIND_HOST] = host` (where `env` is `config.env ??
+ * process.env`) before returning, which correctly fixes the common case (no `env` override — the
+ * default, real `process.env` gets the right value). When a caller *does* inject a distinct `env`
+ * object for full test isolation, this line cannot make `guardSameOrigin`'s hardwired real-`process.env`
+ * read reflect it — a pre-existing `@jini/http` limitation this call cannot reach around without
+ * editing `origin.ts` itself (out of scope here, same reasoning as the origin-validation duplication
+ * flagged in `packages/http/archived provenance ledger`).
+ *
+ * ## 2026-07-29 — post-merge audit fixes (six teardown/config/URL defects)
+ *
+ * Independent review of the `feat/agentic-capability-layer` merge (OpenAI Codex `gpt-5.6-sol` as peer
+ * reviewer, then re-verified against source here) surfaced six real defects in this package. Each was
+ * reproduced with a failing test before any fix landed.
+ *
+ * **1. Caller packs were never disposed.** `composeJiniKernel` calls `createDaemon` on `config.packs`,
+ * so it — not the caller — builds their services; but neither the failure-cleanup path nor `close()`
+ * ever ran their `dispose`. A caller pack whose `services()` opened a socket, timer or database handle
+ * leaked it past `createLocalNodeDaemon().stop()`, and the wrapper exposes no caller daemon for the
+ * host to tear down itself. Added `JiniKernel.disposeCallerPacks()` — memoized, best-effort, symmetric
+ * with `disposeFeatures()` — called by `close()`, by the composition-failure `catch`, and by the
+ * daemon's `stop()`. Disposal order is reverse of construction: features first (they were composed
+ * against an already-built caller daemon), caller packs second.
+ *
+ * **2. `journal.db` opened outside the cleanup block.** `createJiniKernelBase` opened `events.db`, then
+ * `journal.db`, and only *then* entered the `try` whose `catch` closed them. `journal.db` failing (a
+ * corrupt file, or a directory sitting where a database was expected) left the `events.db` handle open
+ * in a process that has no kernel. Every acquisition now happens inside the one block, tracked in an
+ * `opened` array the cleanup drains — the shape the module's own comment already claimed.
+ *
+ * **3. Capability keys were not runtime-validated.** Feature ids in `config.features` threw on a typo;
+ * capability ids in `config.capabilities` did not. `{'host:exce': false}` deleted a grant nobody held,
+ * so `host:exec` survived and `terminal`/`hostTools` stayed mounted — a security switch that fails
+ * *open* on a typo, in the direction that reads as applied. `feature.ts` now carries the runtime half
+ * of `CapabilityId` as a `Record<CapabilityId, true>` (drift is a compile error in both directions, so
+ * the list cannot silently fall behind the union it validates) plus `CAPABILITY_IDS`/`isCapabilityId`;
+ * `resolveFeatureActivation` validates the keys next to where it validates feature ids.
+ *
+ * **4. An injected `config.env` never reached the per-route same-origin guard.** `env[JINI_BIND_HOST] =
+ * host` writes into the caller's object when one is supplied, and `@jini-ai/http-kit`'s `guardSameOrigin`
+ * read real `process.env`. The origin-guard *middleware* was already handed the injected `env`, so the
+ * two halves of one decision read two different environments: the middleware admitted an origin the
+ * host configured through `config.env` and the route then rejected it. Fixed at the seam —
+ * `OriginContext` (and so `AdapterContext`) grew an optional `env`, defaulting to `process.env`, and
+ * this preset sets it. That covers `JINI_BIND_HOST`, `JINI_ALLOWED_ORIGINS` and `JINI_WEB_PORT` alike.
+ *
+ * **5. Shutdown could skip its own teardown, or crash the process.** `closeHttpServer` rejecting (which
+ * its own contract documents) skipped feature disposal, discovery-record removal, `onShutdown` and the
+ * sqlite close — leaving a half-torn-down daemon, strictly worse than the failure that caused it. It is
+ * a `try`/`finally` now; the original rejection still propagates once teardown finishes. Separately,
+ * `requestShutdown` dropped `stop()`'s promise with a bare `void`, so a failing shutdown became an
+ * unhandled rejection — which on Node's default policy terminates the process this was gracefully
+ * shutting down. It is reported through `console.error` now; the rejection stays on `stopPromise` so an
+ * explicit `stop()` caller still observes it.
+ *
+ * **6. `resolveReportHost` produced an unparseable URL for an IPv6 bind host.** `'::1'` passed through
+ * unchanged, so the reported base URL was `http://::1:54321` — which `new URL()` and `fetch` both
+ * reject, and which was written verbatim into the discovery record. It now returns the bracketed
+ * authority form (RFC 3986 §3.2.2), idempotently.
+ *
+ * Two lower-severity items from the same review, also fixed:
+ *
+ * - **`agents`' scan cache was not keyed by promise identity.** A slow scan that failed *after* `POST
+ *   /api/agents/rescan` had already replaced it with a successful one cleared the newer entry, forcing
+ *   a duplicate probe of every agent CLI on the machine. The `catch` now clears only its own entry.
+ * - **`createFrontendControl`'s bind boundary did not cover `resolveBindToken` or its own error sink.**
+ *   A `RunStartHandler` throwing is not a no-op — `@jini-ai/http-kit`'s run-start route marks the run
+ *   `failed` and answers 500 — so a host-supplied `resolveBindToken` throwing (it parses an opaque host
+ *   blob) produced exactly the killed run the `onBindError` doc promises never to cause. Both are inside
+ *   the boundary now; a throwing sink is swallowed, because the reporting channel is what failed.
+ *
+ * **One pre-existing gap closed while here.** The package's committed 100% function-coverage gate was
+ * already failing on `main` (99.09%): `sidecar-strict`'s origin-guard `getResolvedPort` closure had no
+ * end-to-end coverage, because both of that mode's gates are request-time middleware. Added six real
+ * `security: sidecar-strict` tests (unauthenticated 401, authenticated 201, cross-origin 403 with a
+ * valid token, unset-token 503, probe routes reachable tokenless, `exemptPaths`) — the one block in
+ * `compose-jini-kernel.test.ts` that opens a socket, and only because it has to.
+ *
+ * **Verified, personally, this session**: `packages/server` **231/231 passing** across 8 files (was
+ * 215 before the sidecar-strict block), **100/100/100/100 coverage**; `packages/http-kit` 1245/1245 and
+ * 100% ; `packages/chat-core` 261/261; `packages/chat-react` 610/610 and 100%;
+ * `examples/reference-web` 41/41. Repo-wide `pnpm typecheck` and `pnpm guard` clean.
+ */
+export type { CreateLocalNodeDaemonConfig, KernelBoundIds, LocalNodeDaemon, LocalNodeHttpExtension, LocalNodeHttpExtensionContext, } from './create-local-node-daemon.js';
+export { buildDaemonDbOperations, classifyRunFailureForRetry, createLocalNodeDaemon, projectDetectedAgent, resolveBoundPort, resolveReportHost, } from './create-local-node-daemon.js';
+export type { ComposeJiniKernelConfig, JiniKernel, JiniKernelSecurity } from './compose-jini-kernel.js';
+export { composeJiniKernel, defaultServerMessages } from './compose-jini-kernel.js';
+export type { AnyPack, CapabilityId, FeatureBuildContext, FeatureComposition, FeaturePhase, JiniFeature, JiniProfile, JiniProfileId, ProfileActivation, } from './feature.js';
+export { CAPABILITY_IDS, CORE_CAPABILITIES, defineJiniFeature, isCapabilityId, JINI_PROFILES } from './feature.js';
+export type { ActivationReason, ActiveFeatureRecord, DeactivationReason, FeatureActivationInput, FeatureActivationPlan, InactiveFeatureRecord, } from './feature-activation.js';
+export { resolveFeatureActivation } from './feature-activation.js';
+export type { BuiltInFeatureOptions } from './builtin-features.js';
+export { ANONYMOUS_DELEGATED_PRINCIPAL, createBuiltInFeatures, LOCAL_DAEMON_PRINCIPAL, } from './builtin-features.js';
+export type { CreateJiniKernelBaseOptions, JiniKernelBase, JiniKernelStorage, KernelSqliteAccess, } from './kernel-base.js';
+export { createJiniKernelBase } from './kernel-base.js';
+export { createFrontendControl } from '@jini-ai/daemon/http';
+export type { CreateFrontendControlOptions, FrontendBindErrorContext, FrontendControl, FrontendHttpExtension } from '@jini-ai/daemon/http';
+export type { CloseHttpServerOptions, GracefulShutdownHandle, GracefulShutdownOptions } from './host-bootstrap.js';
+export { DEFAULT_DAEMON_BIND_HOST, closeHttpServer, installGracefulShutdown, normalizeDaemonBindHost, } from './host-bootstrap.js';
+//# sourceMappingURL=index.d.ts.map