@jini-ai/server 0.0.0-stage → 0.5.0

package/dist/compose-jini-kernel.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @module compose-jini-kernel
+ *
+ * The one composition path. Everything this package can mount goes through here — including
+ * `createLocalNodeDaemon`, which is now a listener/discovery wrapper over this function rather than
+ * a second, independently-drifting assembly.
+ *
+ * That single-path property is the point. When a preset assembles routes and tools inline *and* a
+ * separate "composable" surface exists beside it, the two disagree the moment someone adds a family
+ * to one and forgets the other — and the disagreement is invisible, because both compile. Here a
+ * new family is a `JiniFeature` in the catalog, and every consumer picks it up or explicitly does
+ * not; there is no second place to forget.
+ *
+ * Mounting order is fixed and load-bearing:
+ *
+ * 1. `probe`-phase routes — before the body parser and before any auth, so liveness/readiness never
+ *    depends on either.
+ * 2. `sidecar-strict`'s bearer gate, when that mode is active — ahead of the body parser, so a
+ *    request this gate will reject never has its body parsed at all. It needs only `req.path` and the
+ *    `Authorization` header.
+ * 3. the JSON body parser, then (when this composition owns security) the remaining gates:
+ *    `sidecar-strict`'s origin guard, or `jini-local`'s bearer + origin pair.
+ * 4. `api`-phase routes, in catalog order.
+ * 5. the caller's own `onAfterApiRoutes` hook — product HTTP extensions and pack routes.
+ * 6. `status`-phase routes, last, so a status surface reports on a fully assembled app.
+ *
+ * Tools are registered for every active feature **before any route mounts**, so a feature's routes
+ * can assume its own tools exist, and `afterTools` hooks (the tool catalog's durable snapshot) see
+ * the complete registry rather than a partial one.
+ */
+import { type Express } from 'express';
+import { type Bindings, type Daemon, type Pack, type ToolRegistration } from '@jini-ai/core';
+import { type AdapterContext } from '@jini-ai/http-kit';
+import { type BuiltInFeatureOptions } from './builtin-features.js';
+import { type AnyPack, type CapabilityId, type JiniFeature, type JiniProfileId } from './feature.js';
+import { type FeatureActivationPlan } from './feature-activation.js';
+import { createJiniKernelBase, type JiniKernelBase, type JiniKernelStorage } from './kernel-base.js';
+/** Replaceable server validation wording shared by every composition entry. */
+export declare const defaultServerMessages: {
+    invalidSecurityMode: string;
+};
+/** The token ids every composition binds before any caller customization runs. */
+export type KernelBoundIds = 'jini.eventLog' | 'jini.runLifecycle' | 'jini.agentExecutor';
+/** How this composition's `/api` surface is guarded. */
+export type JiniKernelSecurity = 
+/** The caller's app already owns authentication/origin policy. Nothing is installed. */
+{
+    readonly mode: 'host';
+}
+/** This composition installs the loopback-daemon bearer gate and origin guard. */
+ | {
+    readonly mode: 'jini-local';
+    readonly host: string;
+    readonly apiToken?: {
+        readonly tokenEnvVar?: string;
+        readonly disableEnvVar?: string;
+    };
+}
+/**
+ * Like `jini-local`, but for a daemon whose threat model is **another process running as the same
+ * OS user**, not a remote attacker: every `/api` request must carry the bearer token, including
+ * one arriving from `127.0.0.1`, and an unconfigured token fails closed with 503 rather than
+ * silently serving unauthenticated callers.
+ *
+ * Use this when the daemon holds authority a co-resident process should not be able to borrow —
+ * starting real agent runs, executing tools against a real database. A loopback bind keeps remote
+ * hosts out but does nothing about a sibling process, which is precisely what `jini-local`'s
+ * loopback short-circuit trusts.
+ *
+ * `probe`-phase routes (health/readiness/version) mount before this gate and therefore stay
+ * reachable without a token — monitoring never needs a secret.
+ */
+ | {
+    readonly mode: 'sidecar-strict';
+    readonly host: string;
+    /**
+     * Env var carrying the required bearer token. Required with no default — this package does
+     * not name a host's secret, matching every other host-resolved seam in the engine.
+     */
+    readonly tokenEnvVar: string;
+    /**
+     * Exact `req.path` values this gate does not apply to. Defaults to none. Every entry is a hole
+     * in the gate, so each one belongs at the mount site with a stated reason — the intended use
+     * is a callback route whose only legitimate caller cannot yet present a credential.
+     */
+    readonly exemptPaths?: readonly string[];
+};
+export interface ComposeJiniKernelConfig {
+    /** The app to mount onto. Always caller-supplied — this function never opens a listener. */
+    readonly app: Express;
+    readonly adapter: AdapterContext;
+    readonly storage: JiniKernelStorage;
+    /** @default 'agent-core-v1' — the conservative embedding posture. */
+    readonly profile?: JiniProfileId;
+    /** Raises or lowers the profile's capability ceiling. A denial here always wins. */
+    readonly capabilities?: Readonly<Partial<Record<CapabilityId, boolean | undefined>>>;
+    /** Names built-in (or `extraFeatures`) features on/off within that ceiling. */
+    readonly features?: Readonly<Record<string, boolean | undefined>>;
+    readonly featureOptions?: BuiltInFeatureOptions;
+    /** Product features. Same shape, same activation rules, same atomicity — no second path. */
+    readonly extraFeatures?: readonly JiniFeature[];
+    /** Host-contributed tools, registered after every active feature's own. */
+    readonly toolRegistrations?: readonly ToolRegistration[];
+    /** Caller-owned `@jini-ai/core` packs, composed against the kernel bindings. */
+    readonly packs?: readonly AnyPack[];
+    readonly bindings?: (b: Bindings<KernelBoundIds>) => Bindings<string>;
+    readonly agentExecutor?: Parameters<typeof createJiniKernelBase>[0]['agentExecutor'];
+    /** Explicit trust policy; omitted and unknown modes are rejected before opening resources. */
+    readonly security: JiniKernelSecurity;
+    /** @default true — set false when the caller's app already parses JSON bodies. */
+    readonly installJsonBodyParser?: boolean;
+    /**
+     * Runs after `api`-phase routes and before `status`-phase ones.
+     *
+     * Receives `base` explicitly rather than letting the caller close over the `JiniKernel` this
+     * function returns: the hook fires *during* composition, so that binding does not exist yet and
+     * reading it would be a temporal-dead-zone `ReferenceError` at boot.
+     */
+    readonly onAfterApiRoutes?: (app: Express, daemon: Daemon<readonly AnyPack[]>, base: JiniKernelBase) => void;
+    /** @default process.env */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface JiniKernel {
+    readonly base: JiniKernelBase;
+    /** The composed caller packs' services, exactly as `createDaemon` returns them. */
+    readonly daemon: Daemon<readonly AnyPack[]>;
+    /** What was mounted, why, and what it grants — the machine-readable answer to "is X on?". */
+    readonly activation: FeatureActivationPlan;
+    /**
+     * Runs every active feature pack's `dispose`, in reverse composition order, best-effort. Separate
+     * from {@link closeBase} so a composition root can interleave its own shutdown steps between the
+     * two — which is exactly what the standalone daemon does.
+     */
+    disposeFeatures(): Promise<void>;
+    /**
+     * Runs every **caller** pack's `dispose`, in reverse composition order, best-effort. Idempotent.
+     *
+     * This composition called `createDaemon` on `config.packs`, so it — not the caller — is what
+     * built their services; a pack whose `services()` opened a socket, a timer or a database handle
+     * has no other owner to release it. Kept separate from {@link disposeFeatures} for the same
+     * reason that one is separate from {@link closeBase}: a composition root shuts down in its own
+     * order, and the standalone daemon interleaves discovery-record removal and the host's
+     * `onShutdown` hook between these steps.
+     */
+    disposeCallerPacks(): Promise<void>;
+    /** Closes the kernel-owned sqlite handles. Idempotent. */
+    closeBase(): Promise<void>;
+    /** {@link disposeFeatures}, then {@link disposeCallerPacks}, then {@link closeBase}. */
+    close(): Promise<void>;
+}
+/**
+ * Composes the kernel, the selected feature set, and the caller's own packs onto `config.app`.
+ *
+ * @throws For any activation error (unknown feature id, denied capability under an explicit enable,
+ * unmet `requires`), any missing required feature option, a duplicate tool id, or a failed
+ * rehydration. Every kernel resource opened before the failure is disposed and closed before the
+ * error propagates, so a failed composition never leaks a sqlite file handle or a pty manager.
+ */
+export declare function composeJiniKernel(config: ComposeJiniKernelConfig): Promise<JiniKernel>;
+/** Re-exported so a caller can name the pack type without reaching into `@jini-ai/core`'s internals. */
+export type { Pack };
+//# sourceMappingURL=compose-jini-kernel.d.ts.map

package/dist/compose-jini-kernel.js

@@ -0,0 +1,208 @@
+/**
+ * @module compose-jini-kernel
+ *
+ * The one composition path. Everything this package can mount goes through here — including
+ * `createLocalNodeDaemon`, which is now a listener/discovery wrapper over this function rather than
+ * a second, independently-drifting assembly.
+ *
+ * That single-path property is the point. When a preset assembles routes and tools inline *and* a
+ * separate "composable" surface exists beside it, the two disagree the moment someone adds a family
+ * to one and forgets the other — and the disagreement is invisible, because both compile. Here a
+ * new family is a `JiniFeature` in the catalog, and every consumer picks it up or explicitly does
+ * not; there is no second place to forget.
+ *
+ * Mounting order is fixed and load-bearing:
+ *
+ * 1. `probe`-phase routes — before the body parser and before any auth, so liveness/readiness never
+ *    depends on either.
+ * 2. `sidecar-strict`'s bearer gate, when that mode is active — ahead of the body parser, so a
+ *    request this gate will reject never has its body parsed at all. It needs only `req.path` and the
+ *    `Authorization` header.
+ * 3. the JSON body parser, then (when this composition owns security) the remaining gates:
+ *    `sidecar-strict`'s origin guard, or `jini-local`'s bearer + origin pair.
+ * 4. `api`-phase routes, in catalog order.
+ * 5. the caller's own `onAfterApiRoutes` hook — product HTTP extensions and pack routes.
+ * 6. `status`-phase routes, last, so a status surface reports on a fully assembled app.
+ *
+ * Tools are registered for every active feature **before any route mounts**, so a feature's routes
+ * can assume its own tools exist, and `afterTools` hooks (the tool catalog's durable snapshot) see
+ * the complete registry rather than a partial one.
+ */
+import express, {} from 'express';
+import { bindings, assertValidAllowedOrigins, configuredAllowedOrigins, createDaemon, disposePacks, registerPackTools, } from '@jini-ai/core';
+import { AgentExecutorToken, EventLogToken, RunLifecycleToken } from '@jini-ai/daemon';
+import { mountPackHttp, registerApiBearerAuthMiddleware, registerApiOriginGuardMiddleware, requireStrictBearerToken, } from '@jini-ai/http-kit';
+import { createBuiltInFeatures } from './builtin-features.js';
+import { JINI_PROFILES, } from './feature.js';
+import { resolveFeatureActivation } from './feature-activation.js';
+import { createJiniKernelBase } from './kernel-base.js';
+/** Replaceable server validation wording shared by every composition entry. */
+export const defaultServerMessages = { invalidSecurityMode: 'an explicit supported security mode is required' };
+function mountPhase(phase, app, composed, daemon) {
+    for (const entry of composed) {
+        if ((entry.feature.phase ?? 'api') !== phase)
+            continue;
+        mountPackHttp({ app, packs: [entry.pack], daemon });
+    }
+}
+/**
+ * Composes the kernel, the selected feature set, and the caller's own packs onto `config.app`.
+ *
+ * @throws For any activation error (unknown feature id, denied capability under an explicit enable,
+ * unmet `requires`), any missing required feature option, a duplicate tool id, or a failed
+ * rehydration. Every kernel resource opened before the failure is disposed and closed before the
+ * error propagates, so a failed composition never leaks a sqlite file handle or a pty manager.
+ */
+export async function composeJiniKernel(config) {
+    const security = config.security;
+    if (!security || !['host', 'jini-local', 'sidecar-strict'].includes(security.mode)) {
+        throw new Error(defaultServerMessages.invalidSecurityMode);
+    }
+    const env = config.env ?? process.env;
+    // Boot-time, unconditional — deliberately not scoped to `security.mode === 'sidecar-strict' |
+    // 'jini-local'` the way the two `configuredAllowedOrigins({ config, env })` calls below are. Those compute
+    // `extraAllowedOrigins` once at composition time too, but only for the two modes that mount
+    // `registerApiOriginGuardMiddleware`; the explicit `'host'` mode never reaches either call, so a
+    // malformed `JINI_ALLOWED_ORIGINS` would otherwise go undetected at boot regardless of mode and
+    // only surface later, inside `isLocalSameOrigin` (via `guardSameOrigin`, which every
+    // `mountJsonRoute` route and the attachment/model-proxy routes call), on whichever request
+    // happened to be first to need a same-origin decision. Asserting here — before any resource
+    // opens, matching the "fails before a single resource is opened" convention just below — turns
+    // that into a fail-fast boot error instead. `configuredAllowedOrigins` itself no longer throws
+    // (see its own doc): this is the ONE place that still does, deliberately.
+    const originConfig = { allowedOriginsEnvVar: 'JINI_ALLOWED_ORIGINS', webPortEnvVar: 'JINI_WEB_PORT', bindHostEnvVar: 'JINI_BIND_HOST' };
+    assertValidAllowedOrigins({ config: originConfig, env });
+    const profile = JINI_PROFILES[config.profile ?? 'agent-core-v1'];
+    const catalog = [
+        ...createBuiltInFeatures(config.featureOptions ?? {}),
+        ...(config.extraFeatures ?? []),
+    ];
+    // Pure, and first: an invalid selection fails before a single resource is opened.
+    const activation = resolveFeatureActivation({
+        features: catalog,
+        profile,
+        ...(config.capabilities === undefined ? {} : { capabilities: config.capabilities }),
+        ...(config.features === undefined ? {} : { featureOverrides: config.features }),
+    });
+    const base = await createJiniKernelBase({
+        storage: config.storage,
+        ...(config.agentExecutor === undefined ? {} : { agentExecutor: config.agentExecutor }),
+    });
+    const composed = [];
+    let featureDaemon = { services: {} };
+    let callerDaemon = { services: {} };
+    const callerPacks = config.packs ?? [];
+    try {
+        const kernelBindings = bindings({})
+            .bind({ token: EventLogToken, impl: base.eventLog })
+            .bind({ token: RunLifecycleToken, impl: base.lifecycle })
+            .bind({ token: AgentExecutorToken, impl: base.agentExecutor });
+        const boundBindings = config.bindings ? config.bindings(kernelBindings) : kernelBindings;
+        callerDaemon = createDaemon({ packs: callerPacks, bindings: boundBindings });
+        const featureContext = { kernel: base, adapter: config.adapter, env };
+        const byId = new Map(catalog.map((feature) => [feature.id, feature]));
+        for (const record of activation.active) {
+            const feature = byId.get(record.id);
+            const composition = feature.compose(featureContext);
+            composed.push({
+                feature,
+                pack: composition.pack,
+                ...(composition.afterTools === undefined ? {} : { afterTools: composition.afterTools }),
+            });
+        }
+        const featurePacks = composed.map((entry) => entry.pack);
+        featureDaemon = createDaemon({ packs: featurePacks, bindings: bindings({}) });
+        // Every tool, from every source, before any route mounts.
+        registerPackTools({ registry: base.registry, packs: featurePacks, daemon: featureDaemon });
+        // Host-contributed tools after the features' own, so a collision names the host's id rather
+        // than silently shadowing a built-in.
+        for (const registration of config.toolRegistrations ?? [])
+            base.registry.register(registration);
+        registerPackTools({ registry: base.registry, packs: callerPacks, daemon: callerDaemon });
+        // Only now is the registry complete — see `toolCatalog`'s own `afterTools` doc.
+        for (const entry of composed)
+            entry.afterTools?.();
+        const { app } = config;
+        mountPhase('probe', app, composed, featureDaemon);
+        // `sidecar-strict`'s bearer gate mounts BEFORE the body parser, unlike `jini-local`'s: a caller
+        // this gate is going to reject with 401 should never have had its body parsed in the first place.
+        // The gate reads only `req.path` and the `Authorization` header, so it needs nothing the parser
+        // provides. Its origin guard still mounts below, alongside `jini-local`'s.
+        if (security.mode === 'sidecar-strict') {
+            app.use(requireStrictBearerToken({
+                tokenEnvVar: security.tokenEnvVar,
+                env,
+            }, security.exemptPaths !== undefined ? { exemptPaths: security.exemptPaths } : {}));
+        }
+        if (config.installJsonBodyParser !== false)
+            app.use(express.json());
+        if (security.mode === 'sidecar-strict') {
+            registerApiOriginGuardMiddleware({ app, deps: {
+                    host: security.host,
+                    extraAllowedOrigins: configuredAllowedOrigins({ config: originConfig, env }),
+                    getResolvedPort: () => config.adapter.resolvedPortRef.current,
+                    env,
+                    ...originConfig,
+                } });
+        }
+        if (security.mode === 'jini-local') {
+            registerApiBearerAuthMiddleware({ app,
+                tokenConfig: {
+                    tokenEnvVar: security.apiToken?.tokenEnvVar ?? 'JINI_API_TOKEN',
+                    disableEnvVar: security.apiToken?.disableEnvVar ?? 'JINI_DISABLE_API_AUTH',
+                },
+                env,
+            });
+            registerApiOriginGuardMiddleware({ app, deps: {
+                    host: security.host,
+                    extraAllowedOrigins: configuredAllowedOrigins({ config: originConfig, env }),
+                    getResolvedPort: () => config.adapter.resolvedPortRef.current,
+                    env,
+                    ...originConfig,
+                } });
+        }
+        mountPhase('api', app, composed, featureDaemon);
+        config.onAfterApiRoutes?.(app, callerDaemon, base);
+        mountPhase('status', app, composed, featureDaemon);
+    }
+    catch (error) {
+        // Reverse of the order they were built: features composed against an already-constructed caller
+        // daemon, so they release first. The caller's packs are disposed here too — `createDaemon` ran
+        // their `services()` before the first feature composed, so a failure anywhere after that point
+        // leaves whatever those services opened with no owner at all.
+        await disposePacks({
+            packs: composed.map((entry) => entry.pack),
+            daemon: featureDaemon,
+        });
+        await disposePacks({ packs: callerPacks, daemon: callerDaemon });
+        await base.close();
+        throw error;
+    }
+    let disposedFeatures = null;
+    const disposeFeatures = () => {
+        disposedFeatures ??= disposePacks({
+            packs: composed.map((entry) => entry.pack),
+            daemon: featureDaemon,
+        }).then(() => undefined);
+        return disposedFeatures;
+    };
+    let disposedCallerPacks = null;
+    const disposeCallerPacks = () => {
+        disposedCallerPacks ??= disposePacks({ packs: callerPacks, daemon: callerDaemon }).then(() => undefined);
+        return disposedCallerPacks;
+    };
+    return {
+        base,
+        daemon: callerDaemon,
+        activation,
+        disposeFeatures,
+        disposeCallerPacks,
+        closeBase: () => base.close(),
+        async close() {
+            await disposeFeatures();
+            await disposeCallerPacks();
+            await base.close();
+        },
+    };
+}
+//# sourceMappingURL=compose-jini-kernel.js.map

package/dist/create-local-node-daemon.d.ts

@@ -0,0 +1,209 @@
+import type { SqliteSyncOpener } from '@jini-ai/db/sqlite';
+import type { Server } from 'node:http';
+import { type Express } from 'express';
+import type { DetectedAgent } from '@jini-ai/agent-runtime';
+import type { Bindings, Principal, ToolRegistration } from '@jini-ai/core';
+import type { AnyPack, MissingTokenIds } from '@jini-ai/core/composition';
+import type { ResolveRunInput, RunLifecycle } from '@jini-ai/daemon';
+import { type AdapterContext } from '@jini-ai/http-kit';
+import { type DelegatedToolExecuteRequest, type RunStartHandler, type WorkspaceRootResolver } from '@jini-ai/daemon/http';
+import { type JiniKernelSecurity, type KernelBoundIds } from './compose-jini-kernel.js';
+import type { CapabilityId, JiniProfileId } from './feature.js';
+export { buildDaemonDbOperations, projectDetectedAgent } from './builtin-features.js';
+export { classifyRunFailureForRetry } from './kernel-base.js';
+/**
+ * Extracts the real bound TCP port from `server.address()`'s result once a `'listening'` event
+ * has fired.
+ *
+ * @param address - The raw return value of `server.address()`.
+ * @returns The bound port, or `null` if `address` is `null` (not yet listening), a string (a Unix
+ * domain socket path — this module never listens on one), or an `AddressInfo` with a non-positive port.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function resolveBoundPort(address: {
+    port: number;
+} | string | null): number | null;
+/**
+ * The host a daemon's reported base URL should use: binding to every interface (`0.0.0.0` / `::`)
+ * is not itself a connectable address, so callers are told to use the IPv4 loopback address
+ * instead; and an IPv6 literal is returned in bracketed authority form.
+ *
+ * The brackets are not cosmetic. `http://${'::1'}:5000` is not a URL — `new URL()` throws on it and
+ * so does `fetch`, which made a daemon bound to `::1` hand back a base URL nothing could use and
+ * write that same unusable string into its discovery record. RFC 3986 §3.2.2 requires the brackets
+ * for any IPv6 literal in an authority, precisely so the address's own colons cannot be read as the
+ * port separator.
+ *
+ * @param bindHost - The literal host `createLocalNodeDaemon` bound to (already normalized).
+ * @returns `'127.0.0.1'` for an all-interfaces bind host, `'[…]'` for an IPv6 literal (already-
+ * bracketed input is returned unchanged), otherwise `bindHost` unchanged.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function resolveReportHost(bindHost: string): string;
+export type { KernelBoundIds };
+/**
+ * Product-level HTTP composition seam. Incubating capabilities register their routes here instead
+ * of becoming downward dependencies of this locked host preset.
+ */
+export interface LocalNodeHttpExtensionContext {
+    readonly adapter: AdapterContext;
+    readonly lifecycle: RunLifecycle;
+    readonly dataDir: string;
+}
+export type LocalNodeHttpExtension = (app: Express, context: LocalNodeHttpExtensionContext) => void;
+export interface CreateLocalNodeDaemonConfig<Packs extends readonly AnyPack[], BoundIds extends string = KernelBoundIds> {
+    /** Directory the daemon's durable state lives in. The directory itself must already exist. */
+    dataDir: string;
+    /** The external host supplies its driver; Jini never autoloads SQLite. */
+    open: SqliteSyncOpener;
+    packs: Packs;
+    /**
+     * Extends the kernel's own pre-bound `EventLog`/`RunLifecycle` bindings with whatever a pack's
+     * own deps require. A callback rather than a pre-built `Bindings` instance because
+     * `Bindings.bind()` mutates and returns `this`.
+     */
+    bindings?: (b: Bindings<KernelBoundIds>) => Bindings<BoundIds>;
+    /** TCP port to listen on. Defaults to `0` (ask the OS for an ephemeral free port). */
+    port?: number;
+    /** Host/address to bind to. Defaults to `'127.0.0.1'` (loopback-only). */
+    host?: string;
+    /** Env var names for the optional bearer-token gate. Defaults to `JINI_API_TOKEN` / `JINI_DISABLE_API_AUTH`. Ignored when `security` below selects `sidecar-strict`. */
+    apiToken?: {
+        tokenEnvVar?: string;
+        disableEnvVar?: string;
+    };
+    /**
+     * Raises this preset's default `jini-local` gate to `sidecar-strict` — see
+     * {@link JiniKernelSecurity}'s own doc for what that changes: every `/api` request must carry the
+     * bearer token, including one from `127.0.0.1`, and an unconfigured token fails closed rather than
+     * serving unauthenticated callers. `host` is supplied automatically from this config's own `host`
+     * (there is nowhere else for it to disagree with, so it is not this option's to set again).
+     * Omitted (the default) keeps `jini-local` exactly as every existing caller already has it.
+     */
+    security?: Omit<Extract<JiniKernelSecurity, {
+        readonly mode: 'sidecar-strict';
+    }>, 'host'>;
+    /** Invoked once the HTTP listener has fully closed, before the durable `EventLog` is closed. */
+    onShutdown?: () => Promise<void> | void;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Optional detector override for a host with custom PATH/env policy or a deterministic test fixture. */
+    agentDetector?: () => Promise<readonly DetectedAgent[]>;
+    /**
+     * Optional host-owned driver attached immediately after `POST /api/runs` durably starts a run.
+     * Takes full precedence over {@link resolveRunInput} when both are supplied.
+     */
+    onRunStarted?: RunStartHandler;
+    /**
+     * Host-owned prompt/cwd/env composition seam. When supplied and `onRunStarted` is not, this
+     * daemon builds a default `RunStartHandler` that resolves each run's input through this seam and
+     * drives it straight to the zero-config `AgentExecutor`. Ignored when `onRunStarted` is supplied.
+     */
+    resolveRunInput?: ResolveRunInput;
+    /**
+     * Resolves a `resourceRef` to a filesystem working directory for `POST /api/resources/:resourceRef/open-in`.
+     * Defaults to `denyAllWorkspaceRoots`: the route exists and is reachable but denies every call
+     * with `404`, never fabricating or guessing a path.
+     */
+    resolveWorkspaceRoot?: WorkspaceRootResolver;
+    /**
+     * Optional product/capability route registrars. They run after the host's security middleware
+     * and locked route packs, before caller packs and daemon-status routes.
+     */
+    httpExtensions?: readonly LocalNodeHttpExtension[];
+    /**
+     * Host-contributed `{descriptor, handler, policy}` triples, registered into the same internal
+     * registry this preset's own gated tools (`jini.terminal.create`, `daemon.db.*`) use — and so
+     * executed through the same `ToolExecutor`, inheriting its authorization, confirmation, timeout,
+     * cancellation, output truncation, and audit trail.
+     *
+     * @throws At startup if a `descriptor.id` is already registered — by another entry here, or by
+     * one of the preset's own tools. The registry is append-only by design.
+     */
+    toolRegistrations?: readonly ToolRegistration[];
+    /**
+     * Resolves the `Principal` one `POST /api/delegated-tool-calls` request executes as.
+     *
+     * @default the anonymous, role-less delegated principal — inertness comes from deny-by-default
+     * tool policies, not from the identity.
+     */
+    resolveDelegatedPrincipal?: (request: DelegatedToolExecuteRequest) => Principal | Promise<Principal>;
+    /**
+     * Where this daemon's local discovery record (URL/host/port/pid) is written once it starts
+     * listening. Defaults to `<dataDir>/daemon.json`. Pass `false` to disable. Best-effort: a failure
+     * here never fails daemon startup or shutdown.
+     */
+    discoveryFile?: string | false;
+    /**
+     * Capability profile this daemon composes against.
+     *
+     * @default 'local-daemon-v1' — the immutable compatibility profile holding exactly the surface
+     * this preset has always mounted. Changing it changes which route families exist; see
+     * `feature.ts` for the vocabulary and why profiles are versioned rather than edited.
+     */
+    profile?: JiniProfileId;
+    /**
+     * Raises or lowers the profile's capability ceiling. A denial always wins: explicitly enabling a
+     * feature whose capability is denied here is a startup error naming both, never a silent
+     * re-opening of a coarse switch.
+     */
+    capabilities?: Readonly<Partial<Record<CapabilityId, boolean | undefined>>>;
+    /**
+     * Turns individual features on or off within whatever the capability ceiling permits — e.g.
+     * `{ terminal: false, daemonDb: false }`. A feature turned off here registers **neither its
+     * routes nor its tools**, so a disabled capability is absent from the shared registry rather than
+     * merely unrouted.
+     */
+    features?: Readonly<Record<string, boolean | undefined>>;
+}
+export interface LocalNodeDaemon {
+    /** The daemon's real, resolved base URL (reflects the actual bound port even when `port: 0` was requested). */
+    readonly url: string;
+    readonly server: Server;
+    /**
+     * Gracefully shuts the daemon down: closes the HTTP listener, disposes every composed feature
+     * (releasing e.g. an in-flight xAI OAuth loopback listener), removes the discovery record, runs
+     * the caller's `onShutdown` hook, then closes the durable sqlite handles. Idempotent and safe to
+     * call more than once, or concurrently.
+     */
+    stop(): Promise<void>;
+    /** Every feature actually composed, with why and what it grants. */
+    readonly activeFeatures: readonly string[];
+}
+/**
+ * Boots a complete, runnable `@jini-ai/core` daemon process.
+ *
+ * Preserves `createDaemon`'s compile-time "missing binding" error through this wrapper: the same
+ * `MissingTokenIds<Packs, BoundIds>` conditional gate `createDaemon` itself uses forces a call site
+ * with an unbound pack dependency to fail to typecheck with the missing token id(s) visible.
+ *
+ * **Why two overloads instead of one generic signature:** when a type parameter both has a default
+ * and is referenced inside a conditional type in the same parameter position where it also needs to
+ * be inferred 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` provided) where it matters most. Splitting into two overloads sidesteps the inference
+ * conflict entirely. Both directions are covered by `@ts-expect-error` proofs in
+ * `create-local-node-daemon.typecheck.ts`.
+ *
+ * @param config - See {@link CreateLocalNodeDaemonConfig}.
+ * @returns A promise resolving to `{url, server, stop, activeFeatures}` once the daemon is listening.
+ * @throws Rejects if the port is already in use (`EADDRINUSE`), the host can't be bound
+ * (`EACCES`/`EADDRNOTAVAIL`), the OS reports a listening socket with no resolvable port, or the
+ * composition itself is invalid. On any of these every sqlite handle already opened is closed
+ * before rejecting, so a failed boot never leaks an open file handle.
+ * @complexity O(1) beyond the packs' own `services()`/`http()` costs.
+ * @overallScore 100/100
+ */
+export declare function createLocalNodeDaemon<const Packs extends readonly AnyPack[]>(config: CreateLocalNodeDaemonConfig<Packs, KernelBoundIds> & {
+    bindings?: undefined;
+} & (MissingTokenIds<Packs, KernelBoundIds> extends never ? unknown : {
+    readonly __missingBindings: MissingTokenIds<Packs, KernelBoundIds>;
+})): Promise<LocalNodeDaemon>;
+export declare function createLocalNodeDaemon<const Packs extends readonly AnyPack[], BoundIds extends string>(config: CreateLocalNodeDaemonConfig<Packs, BoundIds> & {
+    bindings: (b: Bindings<KernelBoundIds>) => Bindings<BoundIds>;
+} & (MissingTokenIds<Packs, BoundIds> extends never ? unknown : {
+    readonly __missingBindings: MissingTokenIds<Packs, BoundIds>;
+})): Promise<LocalNodeDaemon>;
+//# sourceMappingURL=create-local-node-daemon.d.ts.map