@jini-ai/server 0.0.0-stage → 0.5.1

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,49 @@
+/**
+ * @module @jini-ai/server
+ *
+ * Node host preset: createLocalNodeDaemon assembles core, daemon, concern-owned
+ * storage and http-kit into a listening service. composeJiniKernel is the same
+ * composition core for hosts mounting their own app without a second listener.
+ *
+ * Composition and lifecycle invariants:
+ * - The preset's two overloads preserve the missing-binding type gate: defaulted
+ *   BoundIds would defeat inference from a custom bindings callback. Core's
+ *   internal token-gate types are reused, rather than reimplemented. The cast
+ *   inside the generic body is protected by both exported overloads' gate.
+ * - resolveBoundPort and resolveReportHost are pure helpers so defensive address
+ *   checks are directly testable without a listener. Wildcard hosts are reported
+ *   as loopback and IPv6 authorities are bracketed so discovery URLs are usable.
+ * - Resource acquisition stays inside cleanup boundaries so a later database
+ *   open cannot leak an earlier handle. Features dispose before caller packs,
+ *   reversing construction; the preset constructed those services and owns
+ *   teardown. Listener-close or onShutdown failures cannot skip storage close,
+ *   feature disposal or discovery removal. Explicit stop callers observe failures;
+ *   requested shutdown failures are reported rather than dropped as rejections.
+ * - Feature and capability keys are runtime-validated: silently accepting a typo
+ *   in a disabled capability would leave the real security-sensitive grant active.
+ * - Bind-host configuration is set before serving requests. The injected env is
+ *   shared with origin middleware and route guards so both enforce the same policy.
+ * - Agent scan cache cleanup checks promise identity so an older failed scan
+ *   cannot clear its replacement. Frontend binding contains resolver and error-sink
+ *   failures so a host binding error cannot fail the underlying run.
+ *
+ * Frontend control belongs to daemon/http; this entry retains its public forwarding
+ * exports. See owning modules and packages/server/README.md for detailed contracts.
+ */
+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

package/dist/index.js

@@ -0,0 +1,11 @@
+export { buildDaemonDbOperations, classifyRunFailureForRetry, createLocalNodeDaemon, projectDetectedAgent, resolveBoundPort, resolveReportHost, } from './create-local-node-daemon.js';
+export { composeJiniKernel, defaultServerMessages } from './compose-jini-kernel.js';
+export { CAPABILITY_IDS, CORE_CAPABILITIES, defineJiniFeature, isCapabilityId, JINI_PROFILES } from './feature.js';
+export { resolveFeatureActivation } from './feature-activation.js';
+export { ANONYMOUS_DELEGATED_PRINCIPAL, createBuiltInFeatures, LOCAL_DAEMON_PRINCIPAL, } from './builtin-features.js';
+export { createJiniKernelBase } from './kernel-base.js';
+// Frontend control belongs to the daemon HTTP surface: hosts that build their own Express app
+// can compose it without the server kernel. This server entry keeps its existing public export.
+export { createFrontendControl } from '@jini-ai/daemon/http';
+export { DEFAULT_DAEMON_BIND_HOST, closeHttpServer, installGracefulShutdown, normalizeDaemonBindHost, } from './host-bootstrap.js';
+//# sourceMappingURL=index.js.map

package/dist/kernel-base.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module kernel-base
+ *
+ * The infrastructure every composition owns regardless of which features it activates: the durable
+ * (or in-memory) event log, the run lifecycle, the byte journal, the agent executor, the one shared
+ * `ToolRegistry`/`ToolExecutor` pair, and — for sqlite storage — the raw database connection.
+ *
+ * **The database connection belongs here, not to a feature.** It is borrowed by the readiness probe
+ * (`health`), by the raw db-operations tools (`daemonDb`), and by the durable tool catalog
+ * (`toolCatalog`) — three independently-selectable features. Had any one of them owned it, disabling
+ * that feature would have silently broken the others: turning off `daemonDb` would leave `health`'s
+ * readiness probe with nothing to check, which is a much worse failure than the one it was meant to
+ * simplify, because a readiness probe that stops probing still answers `200`. Ownership by the base,
+ * borrowing by features, is what makes the feature set genuinely independent.
+ */
+import { type SqliteDb, type SqliteSyncOpener } from '@jini-ai/db/sqlite';
+import { type ToolRegistry } from '@jini-ai/core';
+import { createAgentExecutor, type AgentExecutor, type EventLog, type RunLifecycle, type RunRetrySideEffectState, type ToolExecutor } from '@jini-ai/daemon';
+/** Where a composition's durable state lives. */
+export type JiniKernelStorage = 
+/** No files touched. Runs and their events vanish with the process — right for tests and for an
+ * embedded host that treats runs as ephemeral. Features needing a real database file
+ * (`daemonDb`, `toolCatalog`, `xai`) cannot be activated against it. */
+{
+    readonly kind: 'memory';
+}
+/** `<dataDir>/events.db` + `<dataDir>/journal.db`. The directory must already exist. */
+ | {
+    readonly kind: 'sqlite';
+    readonly dataDir: string;
+    readonly open: SqliteSyncOpener;
+};
+/** The raw sqlite handle and its path, borrowed by `health`/`daemonDb`/`toolCatalog`. */
+export interface KernelSqliteAccess {
+    readonly connection: SqliteDb;
+    readonly eventsDbPath: string;
+    readonly dataDir: string;
+}
+/**
+ * An `EventLog` that may or may not hold an OS resource. `@jini-ai/daemon/store/event-log/sqlite`'s `SqliteEventLog` adds
+ * `close({})`; `@jini-ai/daemon`'s in-memory reference adapter has nothing to release and so declares
+ * none. Modelling `close` as optional lets the base treat both storage kinds uniformly instead of
+ * branching on which one it happens to hold.
+ */
+export type ClosableEventLog = EventLog & {
+    close?: (requiredArgs: Record<string, never>) => Promise<void>;
+};
+export interface JiniKernelBase {
+    readonly eventLog: ClosableEventLog;
+    readonly journalEventLog: ClosableEventLog;
+    readonly lifecycle: RunLifecycle;
+    readonly agentExecutor: AgentExecutor;
+    /** The single registry every active feature's tools land in, and the only one `toolExecutor` reads. */
+    readonly registry: ToolRegistry;
+    readonly toolExecutor: ToolExecutor;
+    /** `null` under memory storage. Owned here; features borrow and must never close it. */
+    readonly sqlite: KernelSqliteAccess | null;
+    /** Closes every handle this base opened, in the same order the standalone daemon always has. */
+    close(): Promise<void>;
+}
+export interface CreateJiniKernelBaseOptions {
+    readonly storage: JiniKernelStorage;
+    /** Extra `createAgentExecutor` options (e.g. `mcpJsonInjection`). `lifecycle`/`journal`/`classifyFailure` are kernel-owned. */
+    readonly agentExecutor?: Omit<NonNullable<Parameters<typeof createAgentExecutor>[1]>, 'journal' | 'classifyFailure'>;
+}
+/**
+ * The zero-config retry classifier every composition gets. Delegates entirely to `@jini-ai/daemon`'s
+ * `resumableFromProcessExit` — see that function's own doc for the classification policy.
+ */
+export declare function classifyRunFailureForRetry(context: {
+    code: number | null;
+    signal: string | null;
+    sideEffects?: Pick<RunRetrySideEffectState, 'userVisibleOutputSeen' | 'toolCallSeen'>;
+}): boolean;
+/**
+ * Opens every kernel-owned resource and rehydrates durable run history.
+ *
+ * @throws If rehydration fails against a corrupt or unreadable durable history. Every handle this
+ * call had already opened is closed before it rethrows, so a failed boot never leaks a sqlite file
+ * handle — the invariant the standalone daemon has always maintained.
+ */
+export declare function createJiniKernelBase(options: CreateJiniKernelBaseOptions): Promise<JiniKernelBase>;
+//# sourceMappingURL=kernel-base.d.ts.map