@jini-ai/server 0.0.0-stage → 0.5.1

package/dist/create-local-node-daemon.js

@@ -0,0 +1,281 @@
+/**
+ * @module create-local-node-daemon
+ *
+ * The "host preset" (extraction-plan.md §2.4) that lets a brand-new product boot a running daemon
+ * process by implementing zero interfaces: assembles `@jini-ai/sqlite`'s durable `EventLog`,
+ * `@jini-ai/daemon`'s `RunLifecycle` and `AgentExecutor` (the driver that actually spawns an agent
+ * CLI subprocess for 23 of the 24 registered defs — see `@jini-ai/daemon`'s own archived provenance ledger), an HTTP
+ * app wrapped in `@jini-ai/http-kit`'s route-registration guard and security middleware, a caller's own
+ * `@jini-ai/core` packs, and the generic daemon-status routes, then listens and returns `{url, server,
+ * stop}`.
+ *
+ * **As of 2026-07-29 this is a thin listener/discovery wrapper over `composeJiniKernel`** (see
+ * `compose-jini-kernel.ts`). Everything it used to assemble inline — the kernel, the tool registry,
+ * every route family — now comes from the shared feature catalog, pinned to the immutable
+ * `local-daemon-v1` capability profile so this function's mounted surface, route order, tool
+ * registration order and shutdown sequence are byte-for-byte what they have always been. The reason
+ * for the change is not this function; it is that a preset assembling routes and tools inline, next
+ * to a separate composable surface, guarantees the two eventually disagree about what a "feature"
+ * mounts. There is now one path, and this is a caller of it.
+ *
+ * Callers who want a different surface pass `profile`/`capabilities`/`features`; callers who pass
+ * nothing get the historical daemon exactly. `local-daemon-v1` is immutable: a future feature never
+ * silently joins it.
+ *
+ * Also writes (2026-07-21) a `@jini-ai/sidecar`-backed local daemon-registry record — see
+ * `resolveDaemonRegistryPath`'s own doc and this file's `CreateLocalNodeDaemonConfig.discoveryFile`
+ * — once the real bound port is known, and removes it during `stop()`.
+ *
+ * This preset supported a switchable `transport: 'express' | 'fastify'` HTTP transport from
+ * 2026-07-19 through 2026-07-22; it was removed since nothing ever consumed `transport: 'fastify'`
+ * in practice — see `archived provenance ledger`'s dated entry and the `future/fastify-transport` branch.
+ */
+import { createRequire } from 'node:module';
+import express, {} from 'express';
+import { installRouteRegistrationGuard, mountPackHttp } from '@jini-ai/http-kit';
+import { removeDaemonRegistryRecordIfCurrent, resolveDaemonRegistryPath, writeDaemonRegistryRecord } from '@jini-ai/sidecar';
+import { composeJiniKernel } from './compose-jini-kernel.js';
+import { closeHttpServer, normalizeDaemonBindHost } from './host-bootstrap.js';
+const require = createRequire(import.meta.url);
+/** This package's own `package.json` version, echoed back by `GET /api/daemon/status`. */
+const packageVersion = require('../package.json').version;
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_TOKEN_ENV_VAR = 'JINI_API_TOKEN';
+const DEFAULT_DISABLE_ENV_VAR = 'JINI_DISABLE_API_AUTH';
+const DEFAULT_BIND_HOST_ENV_VAR = 'JINI_BIND_HOST';
+// Re-exported from their new home so this module's long-standing public surface is unchanged.
+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 function resolveBoundPort(address) {
+    if (address == null || typeof address === 'string')
+        return null;
+    return address.port > 0 ? address.port : 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 function resolveReportHost(bindHost) {
+    if (bindHost === '0.0.0.0' || bindHost === '::')
+        return '127.0.0.1';
+    // A colon can only mean "IPv6 literal" here: a bind host is a host, never a `host:port` pair, and
+    // no DNS name or IPv4 address contains one.
+    if (bindHost.includes(':') && !bindHost.startsWith('['))
+        return `[${bindHost}]`;
+    return bindHost;
+}
+export async function createLocalNodeDaemon(config) {
+    const env = config.env ?? process.env;
+    const host = normalizeDaemonBindHost(config.host ?? DEFAULT_HOST);
+    const requestedPort = config.port ?? 0;
+    const registryPath = config.discoveryFile === false ? null : (config.discoveryFile ?? resolveDaemonRegistryPath({ dataDir: config.dataDir }));
+    // `@jini-ai/http-kit`'s origin policy resolves `bindHost` from `JINI_BIND_HOST`. Setting it here,
+    // before any request can possibly be served, keeps every same-origin decision in sync with the
+    // host this daemon actually bound to.
+    env[DEFAULT_BIND_HOST_ENV_VAR] = host;
+    const resolvedPortRef = { current: requestedPort };
+    // `env`, not `process.env`: when a caller injects its own environment, the line above wrote the
+    // bind host into *that* object, and `JINI_ALLOWED_ORIGINS`/`JINI_WEB_PORT` come from it too. The
+    // origin-guard middleware is already handed this same `env`; carrying it on the adapter is what
+    // makes the per-route `requireSameOrigin` guard evaluate the same supplied environment.
+    const adapter = { resolvedPortRef, env, allowedOriginsEnvVar: 'JINI_ALLOWED_ORIGINS', webPortEnvVar: 'JINI_WEB_PORT', bindHostEnvVar: 'JINI_BIND_HOST' };
+    let shuttingDown = false;
+    let stopPromise = null;
+    let server;
+    // Owned here rather than by the xai feature so `stop()` observes the same ref the routes wrote to.
+    const xaiListenerRef = { current: null };
+    const app = express();
+    installRouteRegistrationGuard({ app });
+    const kernel = await composeJiniKernel({
+        app,
+        adapter,
+        storage: { kind: 'sqlite', dataDir: config.dataDir, open: config.open },
+        profile: config.profile ?? 'local-daemon-v1',
+        ...(config.capabilities === undefined ? {} : { capabilities: config.capabilities }),
+        ...(config.features === undefined ? {} : { features: config.features }),
+        packs: config.packs,
+        ...(config.bindings === undefined ? {} : { bindings: config.bindings }),
+        ...(config.toolRegistrations === undefined ? {} : { toolRegistrations: config.toolRegistrations }),
+        security: config.security
+            ? { ...config.security, host }
+            : {
+                mode: 'jini-local',
+                host,
+                apiToken: {
+                    tokenEnvVar: config.apiToken?.tokenEnvVar ?? DEFAULT_TOKEN_ENV_VAR,
+                    disableEnvVar: config.apiToken?.disableEnvVar ?? DEFAULT_DISABLE_ENV_VAR,
+                },
+            },
+        env,
+        featureOptions: {
+            health: { getVersion: () => packageVersion, isShuttingDown: () => shuttingDown },
+            runs: {
+                ...(config.onRunStarted === undefined ? {} : { onRunStarted: config.onRunStarted }),
+                ...(config.resolveRunInput === undefined ? {} : { resolveRunInput: config.resolveRunInput }),
+            },
+            ...(config.agentDetector === undefined ? {} : { agents: { detector: config.agentDetector } }),
+            hostTools: {
+                ...(config.resolveWorkspaceRoot === undefined ? {} : { resolveWorkspaceRoot: config.resolveWorkspaceRoot }),
+            },
+            terminal: {
+                ...(config.resolveWorkspaceRoot === undefined ? {} : { resolveWorkspaceRoot: config.resolveWorkspaceRoot }),
+            },
+            ...(config.resolveDelegatedPrincipal === undefined
+                ? {}
+                : { delegatedToolCalls: { resolvePrincipal: config.resolveDelegatedPrincipal } }),
+            xai: { listenerRef: xaiListenerRef },
+            daemonStatus: {
+                getVersion: () => packageVersion,
+                host,
+                getPort: () => resolvedPortRef.current,
+                dataDir: config.dataDir,
+                isShuttingDown: () => shuttingDown,
+                requestShutdown: () => {
+                    // `POST /api/daemon/shutdown` answers before shutdown begins, so nothing downstream can
+                    // ever await this promise. Dropping it with a bare `void` turned any shutdown failure
+                    // into a process-level unhandled rejection — which on Node's default policy terminates
+                    // the very process this was trying to shut down gracefully. Reported here instead; the
+                    // rejection stays on `stopPromise`, so an explicit `stop()` caller still observes it.
+                    void stop().catch((error) => {
+                        // eslint-disable-next-line no-console
+                        console.error('[@jini-ai/server] shutdown requested through POST /api/daemon/shutdown failed', error);
+                    });
+                },
+            },
+        },
+        // Product extensions, then caller-pack routes — the historical position, between the locked
+        // route families and the daemon-status routes.
+        onAfterApiRoutes: (mountedApp, daemon, base) => {
+            for (const registerExtension of config.httpExtensions ?? []) {
+                registerExtension(mountedApp, { adapter, lifecycle: base.lifecycle, dataDir: config.dataDir });
+            }
+            mountPackHttp({ app: mountedApp, packs: config.packs, daemon });
+        },
+    });
+    async function stop() {
+        shuttingDown = true;
+        if (!stopPromise) {
+            stopPromise = (async () => {
+                // `finally`, not a bare sequence: `closeHttpServer` rejects on whatever error
+                // `server.close()`'s callback reports, and a listener that refused to close is a reason to
+                // report, never a reason to abandon every other resource this daemon holds. Skipping the
+                // rest would leave two sqlite handles open, a discovery record pointing at a dying process,
+                // and the host's `onShutdown` never run — a strictly worse outcome than the failure that
+                // caused it. The original rejection still propagates once teardown has finished.
+                try {
+                    await closeHttpServer(server);
+                }
+                finally {
+                    // Feature teardown sits exactly where the inline xAI-listener stop used to: after the
+                    // listener is closed, before the discovery record is removed. `disposePacks` is
+                    // best-effort by contract, so one feature's failure cannot block shutdown.
+                    await kernel.disposeFeatures();
+                    // The kernel built the caller's pack services too, so it releases them — after the
+                    // features that were composed against them.
+                    await kernel.disposeCallerPacks();
+                    if (registryPath !== null) {
+                        // Best-effort: a daemon that already served every request successfully must not fail
+                        // its own shutdown just because its discovery record couldn't be removed.
+                        try {
+                            await removeDaemonRegistryRecordIfCurrent({ registryPath, pid: process.pid });
+                        }
+                        catch {
+                            // Intentionally swallowed — see the try's own comment.
+                        }
+                    }
+                    // A caller-supplied `onShutdown` failing must never leak any sqlite handle this call
+                    // opened: `finally` guarantees the close still runs, then the original rejection (if any)
+                    // propagates to whoever is awaiting `stop()`.
+                    try {
+                        await config.onShutdown?.();
+                    }
+                    finally {
+                        await kernel.closeBase();
+                    }
+                }
+            })();
+        }
+        return stopPromise;
+    }
+    const listen = () => new Promise((resolve, reject) => {
+        let listeningServer;
+        try {
+            listeningServer = app.listen(requestedPort, host);
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        listeningServer.once('listening', () => resolve(listeningServer));
+        // `app.listen` throws synchronously when the port is already in use on some Node versions,
+        // but emits an `error` event on others — wiring both paths means this promise always settles.
+        listeningServer.on('error', (error) => reject(error));
+    });
+    const activeFeatures = kernel.activation.active.map((record) => record.id);
+    return await new Promise((resolve, reject) => {
+        const failToBind = (error) => {
+            // Best-effort: a failed boot must not leave any resource this call already opened dangling.
+            void kernel.close().finally(() => reject(error));
+        };
+        listen()
+            .then((listeningServer) => {
+            server = listeningServer;
+            // Widen the between-request idle window so kept-alive sockets survive gaps between bursts
+            // (e.g. an SSE stream's idle periods); `headersTimeout` must exceed `keepAliveTimeout`.
+            server.keepAliveTimeout = 120_000;
+            server.headersTimeout = 125_000;
+            const boundPort = resolveBoundPort(server.address());
+            if (!boundPort) {
+                failToBind(new Error(`@jini-ai/server: daemon failed to resolve listening port (address=${JSON.stringify(server.address())})`));
+                return;
+            }
+            resolvedPortRef.current = boundPort;
+            const reportedUrl = `http://${resolveReportHost(host)}:${boundPort}`;
+            // Writing the discovery record is async; this promise must not resolve — handing the URL
+            // back to the caller — until the record a same-machine CLI would read is in place.
+            void (async () => {
+                if (registryPath !== null) {
+                    try {
+                        await writeDaemonRegistryRecord({ registryPath, record: {
+                                url: reportedUrl,
+                                host: resolveReportHost(host),
+                                port: boundPort,
+                                pid: process.pid,
+                                startedAt: new Date().toISOString(),
+                            } });
+                    }
+                    catch {
+                        // Best-effort — a daemon that is otherwise fully up must not fail to boot just
+                        // because its discovery record couldn't be written.
+                    }
+                }
+                resolve({ url: reportedUrl, server, stop, activeFeatures });
+            })();
+        })
+            .catch((error) => failToBind(error));
+    });
+}
+//# sourceMappingURL=create-local-node-daemon.js.map

package/dist/feature-activation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module feature-activation
+ *
+ * Decides which features a composition mounts, as a pure function of (profile, capability
+ * overrides, feature overrides, catalog). Separated from `composeJiniKernel` so the whole activation
+ * policy — the part with the security consequences — is unit-testable without booting a kernel,
+ * opening a database, or binding a socket.
+ *
+ * The four rules, in the order they are applied:
+ *
+ * 1. **Capabilities are a ceiling.** `granted` starts at the profile's grant set and is adjusted by
+ *    explicit overrides. A feature is *permitted* only if every capability it provides is granted.
+ * 2. **An explicit enable can never beat a denied capability.** This is the rule that keeps a
+ *    coarse "no network egress" switch meaningful: a caller cannot re-open it one feature at a time
+ *    by naming that feature. Both halves are reported in the error so the fix is unambiguous.
+ * 3. **Permitted is not active.** Under `core-only`, raising the ceiling activates nothing by
+ *    itself — the caller still names what it wants. Under `all-permitted`, the ceiling *is* the
+ *    selection, which is what makes a batteries-included daemon preset expressible.
+ * 4. **Declared dependencies are validated, not documented.** A feature whose `requires` are not all
+ *    active is a boot error naming both ends, never a half-mounted capability.
+ *
+ * An unknown feature id in an override is also a boot error. A silently-ignored typo in a
+ * security-relevant config is the exact failure mode of a documented option that no code reads.
+ */
+import type { CapabilityId, JiniFeature, JiniProfile } from './feature.js';
+/** Why a feature ended up active. */
+export type ActivationReason = 
+/** The profile's activation policy selected it; the caller said nothing. */
+'default'
+/** The caller named it explicitly, and its capabilities were permitted. */
+ | 'opt-in';
+/** Why a feature ended up inactive. */
+export type DeactivationReason = 
+/** At least one capability it provides is not granted. */
+'capability-denied'
+/** Permitted, but the profile's activation policy does not default it on. */
+ | 'not-default'
+/** The caller turned it off explicitly. */
+ | 'opt-out';
+export interface ActiveFeatureRecord {
+    readonly id: string;
+    readonly provides: readonly CapabilityId[];
+    readonly reason: ActivationReason;
+}
+export interface InactiveFeatureRecord {
+    readonly id: string;
+    readonly provides: readonly CapabilityId[];
+    readonly reason: DeactivationReason;
+    /** The specific capabilities that blocked it. Empty unless `reason` is `capability-denied`. */
+    readonly deniedCapabilities: readonly CapabilityId[];
+}
+export interface FeatureActivationInput {
+    /** Every selectable feature, in the order they should compose. */
+    readonly features: readonly JiniFeature[];
+    readonly profile: JiniProfile;
+    /**
+     * Raises (`true`) or lowers (`false`) the profile's ceiling. An explicit `undefined` means "no
+     * opinion" and leaves the profile's own grant untouched — `undefined` is admitted in the type
+     * because building this object by optional spread is the normal way a host assembles it, and a
+     * config that silently denied a capability because a spread produced `undefined` would be a
+     * genuinely dangerous surprise.
+     */
+    readonly capabilities?: Readonly<Partial<Record<CapabilityId, boolean | undefined>>>;
+    /** Names features on or off explicitly, within whatever ceiling the capabilities allow. `undefined` again means "no opinion". */
+    readonly featureOverrides?: Readonly<Record<string, boolean | undefined>>;
+}
+export interface FeatureActivationPlan {
+    /** Active features, in catalog order. */
+    readonly active: readonly ActiveFeatureRecord[];
+    /** Known-but-inactive features — so a host can tell "switched off" from "does not exist". */
+    readonly inactive: readonly InactiveFeatureRecord[];
+    readonly grantedCapabilities: readonly CapabilityId[];
+    /** Every capability some catalogued feature needs that this composition does not grant. */
+    readonly deniedCapabilities: readonly CapabilityId[];
+}
+/**
+ * Resolves the composition's feature plan.
+ *
+ * @throws If an override names an unknown feature id, if an explicitly-enabled feature needs a
+ * denied capability, if two catalogued features share an id, or if an active feature's `requires`
+ * are not satisfied. Every one of these is a composition-time programming/config error that would
+ * otherwise surface as a mysteriously missing (or mysteriously present) route at runtime.
+ * @complexity O(f · c) in features and their declared capabilities.
+ */
+export declare function resolveFeatureActivation(input: FeatureActivationInput): FeatureActivationPlan;
+//# sourceMappingURL=feature-activation.d.ts.map

package/dist/feature-activation.js

@@ -0,0 +1,112 @@
+import { CAPABILITY_IDS, CORE_CAPABILITIES, isCapabilityId } from './feature.js';
+function resolveGrants(input) {
+    const granted = new Set(input.profile.grants);
+    for (const [capability, enabled] of Object.entries(input.capabilities ?? {})) {
+        if (enabled === undefined)
+            continue;
+        if (enabled)
+            granted.add(capability);
+        else
+            granted.delete(capability);
+    }
+    return granted;
+}
+/**
+ * Resolves the composition's feature plan.
+ *
+ * @throws If an override names an unknown feature id, if an explicitly-enabled feature needs a
+ * denied capability, if two catalogued features share an id, or if an active feature's `requires`
+ * are not satisfied. Every one of these is a composition-time programming/config error that would
+ * otherwise surface as a mysteriously missing (or mysteriously present) route at runtime.
+ * @complexity O(f · c) in features and their declared capabilities.
+ */
+export function resolveFeatureActivation(input) {
+    const byId = new Map();
+    for (const feature of input.features) {
+        if (byId.has(feature.id)) {
+            throw new Error(`jini: duplicate feature id "${feature.id}" in the composition catalog`);
+        }
+        byId.set(feature.id, feature);
+    }
+    const overrides = input.featureOverrides ?? {};
+    for (const id of Object.keys(overrides)) {
+        if (!byId.has(id)) {
+            const known = [...byId.keys()].sort().join(', ');
+            throw new Error(`jini: unknown feature "${id}" in features config — known features are: ${known}`);
+        }
+    }
+    // Capability keys are validated for exactly the reason feature ids are, and the consequence is
+    // worse: `{'host:exce': false}` deletes a grant nobody holds, so the correctly-spelled
+    // `host:exec` survives and every feature it gates stays mounted. The typo reads as an applied
+    // denial in the config and is not one — a security switch that fails *open* on a typo. TypeScript
+    // catches this at a typed call site; a config parsed from JSON, YAML or env has no such call site.
+    for (const capability of Object.keys(input.capabilities ?? {})) {
+        if (!isCapabilityId({ value: capability })) {
+            const known = [...CAPABILITY_IDS].sort().join(', ');
+            throw new Error(`jini: unknown capability "${capability}" in capabilities config — known capabilities are: ${known}`);
+        }
+    }
+    const granted = resolveGrants(input);
+    const coreCapabilities = new Set(CORE_CAPABILITIES);
+    const active = [];
+    const inactive = [];
+    const denied = new Set();
+    for (const feature of input.features) {
+        const missing = feature.provides.filter((capability) => !granted.has(capability));
+        for (const capability of missing)
+            denied.add(capability);
+        const permitted = missing.length === 0;
+        const explicit = overrides[feature.id];
+        // Rule 2 — an explicit enable never overrides a denied capability, in either direction.
+        if (explicit === true && !permitted) {
+            throw new Error(`jini: feature "${feature.id}" was explicitly enabled but requires denied ` +
+                `capabilit${missing.length > 1 ? 'ies' : 'y'} [${missing.join(', ')}] under profile ` +
+                `"${input.profile.id}". Grant them via config.capabilities, or remove "${feature.id}" from config.features.`);
+        }
+        if (explicit === false) {
+            inactive.push({ id: feature.id, provides: feature.provides, reason: 'opt-out', deniedCapabilities: [] });
+            continue;
+        }
+        if (explicit === true) {
+            active.push({ id: feature.id, provides: feature.provides, reason: 'opt-in' });
+            continue;
+        }
+        if (!permitted) {
+            inactive.push({
+                id: feature.id,
+                provides: feature.provides,
+                reason: 'capability-denied',
+                deniedCapabilities: missing,
+            });
+            continue;
+        }
+        // Rule 3 — permitted is not active. `core-only` still requires the caller to name it.
+        const defaultOn = input.profile.activation === 'all-permitted' ||
+            feature.provides.every((capability) => coreCapabilities.has(capability));
+        if (defaultOn)
+            active.push({ id: feature.id, provides: feature.provides, reason: 'default' });
+        else
+            inactive.push({ id: feature.id, provides: feature.provides, reason: 'not-default', deniedCapabilities: [] });
+    }
+    // Rule 4 — dependencies validated after the full active set is known, so declaration order in the
+    // catalog never decides whether a legitimate configuration is accepted.
+    const activeIds = new Set(active.map((record) => record.id));
+    for (const record of active) {
+        for (const required of byId.get(record.id).requires ?? []) {
+            if (!byId.has(required)) {
+                throw new Error(`jini: feature "${record.id}" declares requires "${required}", which is not a known feature`);
+            }
+            if (!activeIds.has(required)) {
+                throw new Error(`jini: feature "${record.id}" requires "${required}", which is not active — ` +
+                    `enable "${required}" or disable "${record.id}".`);
+            }
+        }
+    }
+    return {
+        active,
+        inactive,
+        grantedCapabilities: [...granted],
+        deniedCapabilities: [...denied],
+    };
+}
+//# sourceMappingURL=feature-activation.js.map

package/dist/feature.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @module feature
+ *
+ * The capability/selection vocabulary that sits **over** `@jini-ai/core`'s `Pack`, and the two
+ * immutable profiles that name a starting capability grant.
+ *
+ * Why this is a separate layer rather than fields on `Pack` itself: `Pack` is the universal
+ * composition unit every consumer (including third-party packs this package knows nothing about)
+ * builds on, and it must stay free of any one host's security vocabulary. `CapabilityId` is
+ * `@jini-ai/server`'s answer to "what authority does mounting this grant?", which is a *local-host*
+ * question — a different embedder could reasonably classify differently. So the atomicity guarantee
+ * lives in the primitive (`Pack.tools` + `Pack.http` are one contribution, see that module's doc)
+ * while the activation policy lives here.
+ *
+ * **Capabilities are an upper bound, not a trigger.** Granting `net:egress` says "this host is
+ * *permitted* to run features that reach the network"; it does not silently mount the model proxy,
+ * research, connectors and xAI together. What a capability grant does is set the ceiling that a
+ * profile's activation policy and a caller's explicit `features` selection must both stay under.
+ * The inverse is enforced too: explicitly enabling a feature whose capability is denied is a boot
+ * error, never a silent win for either side.
+ */
+import type { Pack } from '@jini-ai/core';
+import type { AdapterContext } from '@jini-ai/http-kit';
+import type { JiniKernelBase } from './kernel-base.js';
+/** Any pack, regardless of its dep/service types — mirrors `@jini-ai/http-kit`'s own local alias. */
+export type AnyPack = Pack<any, any, string>;
+/**
+ * What mounting a feature grants a caller who can reach it. Deliberately coarse and closed: the
+ * value of this vocabulary is that a host can answer "what did I just turn on?" by reading one
+ * list, which stops being true the moment the list is long enough to skim.
+ */
+export type CapabilityId = 
+/** Create, observe, cancel and stream runs. The contract every consumer of this kernel needs. */
+'run:transport'
+/** Write agent events into a run this process does not own. Strictly more authority than
+ * `tool:delegated` (which at least routes through `ToolExecutor`'s policy) — never granted by
+ * any shipped profile. */
+ | 'run:inject'
+/** Enumerate and re-probe the agent CLIs installed on this machine. */
+ | 'agent:discovery'
+/** The agent-facing door onto the shared `ToolRegistry`. */
+ | 'tool:delegated'
+/** Durable, searchable descriptor catalog of the registered tool set. */
+ | 'tool:catalog'
+/** Read host state: installed editors, active resource context. */
+ | 'host:read'
+/** Spawn a process on the host — a pty, or an external application. */
+ | 'host:exec'
+/** Inspect, integrity-check, or rewrite a database file in place. */
+ | 'db:admin'
+/** Outbound calls to third parties, and the credentials that go with them. */
+ | 'net:egress'
+/** Report daemon status and request its shutdown. */
+ | 'daemon:control'
+/** Read/write the durable memory note store. */
+ | 'memory:store'
+/** Create and run scheduled routines. */
+ | 'routines:schedule'
+/** Generate media through a dispatch engine. */
+ | 'media:generate'
+/** Bridge to an attached frontend surface's own capabilities. */
+ | 'ui:session';
+/** Every capability this vocabulary declares, for error messages and for exhaustive iteration. */
+export declare const CAPABILITY_IDS: readonly CapabilityId[];
+/** Whether `value` names a capability this vocabulary actually declares. */
+export declare function isCapabilityId(required: {
+    value: string;
+}): required is {
+    value: CapabilityId;
+};
+/**
+ * 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 declare const CORE_CAPABILITIES: readonly CapabilityId[];
+/**
+ * When a feature's routes mount, relative to the composition's own middleware.
+ *
+ * - `probe` — before the JSON body parser and before any auth/origin middleware. A liveness or
+ *   readiness probe must never need a body parser, a bearer token, or a same-origin `Origin`
+ *   header just to confirm the process is up.
+ * - `api` — the normal position, behind whatever security the composition installed.
+ * - `status` — last, after every product/pack route, so a status surface reports on a fully
+ *   assembled app.
+ */
+export type FeaturePhase = 'probe' | 'api' | 'status';
+/** Everything a feature needs to build its pack. Supplied by `composeJiniKernel`. */
+export interface FeatureBuildContext {
+    /** Kernel-owned infrastructure. Features **borrow** from here; they never own or close it. */
+    readonly kernel: JiniKernelBase;
+    readonly adapter: AdapterContext;
+    readonly env: NodeJS.ProcessEnv;
+}
+/** What a feature contributes once it has been selected for composition. */
+export interface FeatureComposition {
+    /** The atomic unit: this feature's services, tools, routes and teardown, together. */
+    readonly pack: AnyPack;
+    /**
+     * Runs after **every** active feature's tools are in the shared registry, and before any routes
+     * mount. The one ordering a `Pack` cannot express on its own, needed by any feature that derives
+     * something from the complete tool set rather than contributing to it (today: the tool catalog's
+     * durable snapshot, which would be silently partial if it ran during its own pack's `tools`).
+     */
+    readonly afterTools?: () => void;
+}
+/**
+ * A selectable built-in or product feature: capability metadata plus a builder for the one `Pack`
+ * that carries its routes, tools and teardown together.
+ */
+export interface JiniFeature {
+    readonly id: string;
+    /** The authority mounting this feature grants. `[]` means none — always permitted (e.g. health). */
+    readonly provides: readonly CapabilityId[];
+    /** Other feature ids that must also be active. Unmet is a boot error naming both ends. */
+    readonly requires?: readonly string[];
+    /** @default 'api' */
+    readonly phase?: FeaturePhase;
+    readonly compose: (context: FeatureBuildContext) => FeatureComposition;
+}
+/** Identity helper that pins a feature's shape at the definition site. */
+export declare function defineJiniFeature(feature: JiniFeature): JiniFeature;
+/**
+ * How a profile decides which *permitted* features are on by default.
+ *
+ * - `core-only` — only features whose capabilities are all in {@link CORE_CAPABILITIES}. Granting
+ *   an extra capability under this policy raises the ceiling; it activates nothing on its own.
+ * - `all-permitted` — every feature the grant set permits. The coarse, batteries-included posture
+ *   the standalone daemon has always had; denying a capability here turns off everything that
+ *   needed it, in one line.
+ */
+export type ProfileActivation = 'core-only' | 'all-permitted';
+export interface JiniProfile {
+    readonly id: JiniProfileId;
+    readonly grants: readonly CapabilityId[];
+    readonly activation: ProfileActivation;
+}
+export type JiniProfileId = 'agent-core-v1' | 'local-daemon-v1';
+/**
+ * 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 declare const JINI_PROFILES: Readonly<Record<JiniProfileId, JiniProfile>>;
+//# sourceMappingURL=feature.d.ts.map