@jini-ai/core 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @jini-ai/core
 
+## 0.4.2 — pending release
+
+- Add source-backed `./plugin-directory` publisher identity and live metadata lookup. Warn and omit invalid advisory keywords; scope legacy `unknown/<name>` IDs to each plugin family, with optional family selection for ambiguous lookups.
+
+- Own generic settings at `./settings` and its optional Express adapter at `./settings/express`; keep both out of the root runtime closure. Move the existing permission helper into core, preserving the CMS command denial class through re-export.
+
+- Own the shared surface-exchange interfaces and reserved parameter constants, formerly declared in daemon. Add the `SurfaceAskThenReport` port so UI can consume the existing daemon lifecycle without depending on its runtime.
+
 ## 0.4.1 — 2026-10-05
 
 - New `readToolLimit({ input, max, fallback }, { key })`: an absent limit is `fallback`, one above `max` is capped at `max`, and a non-integer or one below 1 throws `ToolInputError` ("'limit' must be an integer between 1 and <max>").

package/README.md

@@ -15,7 +15,8 @@ set of tokens, and fails to typecheck if any pack's declared dependency is left
 npm install @jini-ai/core
 ```
 
-No peer dependencies — this package is pure TypeScript with no runtime dependencies at all.
+The root has no runtime dependencies and never loads settings or Express. `express` is an optional
+peer used only by `@jini-ai/core/settings/express`; install it in hosts mounting those routes.
 
 ## What you get
 
@@ -93,6 +94,7 @@ Tool handlers receive required execution context first and optional `{ emitSurfa
 
 | subpath | what's behind it |
 |---|---|
+| `./fetch` | Framework-neutral query contracts and `FetchQueryCache`; inject transport callbacks, `Clock`, scheduler and connectivity/focus ports. No React, DOM or TanStack dependency. |
 | `.` | The public surface above: tokens, packs, daemon composition, tool registry (descriptors only), principal, redact, auth primitives. |
 | `./composition` | **Not part of the public contract.** Exposes `authorizeToolInvocation` (resolves a registry's tool and runs its authorization gate — a security-sensitive value export, but one that only ever hands back a handler alongside an `'allow'` decision) plus type-only `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-derivation helpers. Its sole intended consumers are `@jini-ai/daemon`'s `ToolExecutor` and `@jini-ai/server`'s `createLocalNodeDaemon`. Node's resolver will happily let any consumer import it — the boundary is enforced by `scripts/check-engine-boundaries.ts`, not by the exports map — so external adopters should treat it as off-limits regardless. |
 
@@ -239,3 +241,19 @@ Node or reading a working directory. Equality counts as contained. Directory
 prefix siblings and traversal escapes are rejected; a legal `..name` segment is
 allowed. Windows hosts pass `{ caseSensitive: false, separator: "\\\\" }`; POSIX hosts
 retain the default slash separator so backslashes in directory names remain literal.
+
+## Generic settings
+
+`@jini-ai/core/settings` owns scoped definitions, defaults, values, revisions, change feeds,
+boot-time definition registration, dictionaries and agent tools. Hosts inject settings storage,
+active-principal lookup, authorization, clocks and IDs; no CMS or database adapter is required.
+The keys, scopes, permissions and tool IDs are unchanged by the relocation.
+
+`@jini-ai/core/settings/express` exports `registerSettingsRoutes`, HTTP policy contracts and
+`createCmsSettingsService` / `createCmsSettingsChangeFeed` (factory names retained for compatibility).
+Hosts provide route paths, readiness, principal resolution, scheduler, service and feed ports.
+Registration returns a disposer that closes active feeds. The universal settings entry never
+loads this adapter; neither entry is re-exported by the kernel root.
+
+The former `@jini-ai/cms/settings` and `@jini-ai/cms/settings/express` entries re-export these
+owners for one release. New consumers should import the core subpaths directly.

package/dist/agent-tools.d.ts

@@ -16,6 +16,7 @@ export type AgentToolSideEffect = "none" | "mutates-durable-state" | "deletes-du
 export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
 /** Structural catalog contract. Domains may require inputSchema or tighten their own metadata. */
 export interface AgentToolDefinition {
+    readonly metadata?: import('./tool-metadata.js').ToolMetadata;
     name: string;
     description: string;
     sideEffects: AgentToolSideEffect;

package/dist/approval.d.ts

@@ -0,0 +1,134 @@
+import { type HumanConfirmer } from './registration-kit.js';
+import type { ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolRegistration } from './tool-registry.js';
+/** A host describes the action; core owns the decision lifecycle, never the card format. */
+export interface ApprovalPlan<TDescription> {
+    readonly ask: boolean;
+    readonly description: TDescription;
+    /** Only reusable escalation grants receive a key. Irreversible actions omit it. */
+    readonly rememberKey?: string;
+}
+export type ApprovalAnswer = {
+    confirmed: true;
+    choice?: string;
+} | {
+    confirmed: false;
+    reason: 'declined' | 'expired' | 'abandoned';
+};
+/** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
+ * An answer never revives an aborted operation. Transport failures propagate without an effect. */
+export declare function resolveApproval({ signal, askHuman }: {
+    signal: AbortSignal;
+    askHuman: () => Promise<ApprovalAnswer>;
+}, _optional?: {}): Promise<ApprovalAnswer>;
+export interface RememberedApprovalPort {
+    has(required: {
+        ctx: ToolExecutionContext;
+        key: string;
+    }): Promise<boolean>;
+    grant(required: {
+        ctx: ToolExecutionContext;
+        key: string;
+        confirmer: HumanConfirmer;
+    }): Promise<void>;
+}
+export interface ApprovalSteps<TPrepared, TDescription> {
+    prepare(required: {
+        ctx: ToolExecutionContext;
+    }, optional: ToolExecutionOptions): Promise<TPrepared>;
+    describe(required: {
+        ctx: ToolExecutionContext;
+        prepared: TPrepared;
+    }, optional: ToolExecutionOptions): Promise<ApprovalPlan<TDescription>> | ApprovalPlan<TDescription>;
+    askHuman(required: {
+        ctx: ToolExecutionContext;
+        description: TDescription;
+    }, optional: ToolExecutionOptions): Promise<ApprovalAnswer>;
+    run(required: {
+        ctx: ToolExecutionContext;
+        prepared: TPrepared;
+        confirmer: HumanConfirmer;
+        choice?: string | undefined;
+    }, optional: ToolExecutionOptions): Promise<unknown>;
+    /** Abort may happen before preparation; the lifecycle forwards that missing value explicitly. */
+    notConfirmed(required: {
+        reason: 'declined' | 'expired' | 'abandoned';
+        prepared?: TPrepared | undefined;
+    }): unknown;
+}
+/** Extend the branded human-confirm owner with descriptions and optional remembered grants.
+ * Inputs and actor identity are detached before any asynchronous port runs. No input field can
+ * approve an action; only the host transport or the bound grant store can answer. Abort checks
+ * bracket preparation, storage and the human wait, so a completed run never performs an effect.
+ * @param steps Domain preparation/effects and the host's description/transport ports.
+ * @param optional.remembered A persisted escalation store; omission requires a fresh decision.
+ * @returns A handler accepted by the registration kit's human-only actor rule.
+ * @throws Port failures propagate; a failed store cannot silently authorize an action.
+ * @complexity O(input size) for the snapshot plus bounded port calls and the human wait.
+ * @example createApprovalHandler({ prepare, describe, askHuman, run, notConfirmed });
+ */
+export declare function createApprovalHandler<TPrepared, TDescription>(steps: ApprovalSteps<TPrepared, TDescription>, { remembered }?: {
+    remembered?: RememberedApprovalPort;
+}): ToolHandler;
+/** Page-local proposal transport for a browser that must return before its explicit reply arrives.
+ * It carries no principal or tool authorization: the host's execute port must re-check access.
+ * The private action is independent of the rendered snapshot; replies consume it before awaiting
+ * so double clicks/replayed replies cannot execute twice. Abort clears the proposal and listener.
+ * @returns An observable transport for an app dialog and its authenticated reply entry point.
+ * @complexity O(description size) to detach the proposal; O(listeners) to publish a change.
+ */
+export declare function createApprovalProposalStore<TDescription>({ responseTool, messages }: {
+    responseTool: string;
+    messages: {
+        closed: string;
+        pending: string;
+        missing: string;
+    };
+}, { createId }?: {
+    createId?: () => string;
+}): {
+    getSnapshot: (_required?: {}, _optional?: {}) => {
+        pending: {
+            approvalId: string;
+            description: TDescription;
+        } | null;
+        error: string | null;
+    };
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }, _optional?: {}) => () => void;
+    propose({ description, execute, signal }: {
+        description: TDescription;
+        execute: () => Promise<unknown>;
+        signal: AbortSignal;
+    }, _optional?: {}): {
+        status: "approval_required";
+        approvalId: string;
+        description: TDescription;
+        responseTool: string;
+    };
+    respond({ approvalId, approved }: {
+        approvalId: string;
+        approved: boolean;
+    }, _optional?: {}): Promise<unknown>;
+};
+/** Apply a host classification through the same handler owner used by domain plans.
+ * @returns The registration with one approval handler; authorization policy is preserved.
+ */
+export declare function applyApprovalPolicy<TDescription>({ registration, classify, asks, describe, askHuman, notConfirmed }: {
+    registration: ToolRegistration;
+    classify(required: {
+        input: unknown;
+    }): string;
+    asks(required: {
+        class: string;
+    }): boolean;
+    describe(required: {
+        ctx: ToolExecutionContext;
+        class: string;
+    }): Promise<TDescription>;
+    askHuman: ApprovalSteps<string, TDescription>['askHuman'];
+    notConfirmed: ApprovalSteps<string, TDescription>['notConfirmed'];
+}, optional?: {
+    remembered?: RememberedApprovalPort;
+}): ToolRegistration;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -0,0 +1,141 @@
+import { humanConfirmedHandler } from './registration-kit.js';
+/** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
+ * An answer never revives an aborted operation. Transport failures propagate without an effect. */
+export async function resolveApproval({ signal, askHuman }, _optional = {}) {
+    if (signal.aborted)
+        return { confirmed: false, reason: 'abandoned' };
+    let abandon;
+    const aborted = new Promise(resolve => { abandon = () => resolve({ confirmed: false, reason: 'abandoned' }); });
+    signal.addEventListener('abort', abandon, { once: true });
+    try {
+        const answer = await Promise.race([askHuman(), aborted]);
+        return signal.aborted ? { confirmed: false, reason: 'abandoned' } : answer;
+    }
+    finally {
+        signal.removeEventListener('abort', abandon);
+    }
+}
+/** Extend the branded human-confirm owner with descriptions and optional remembered grants.
+ * Inputs and actor identity are detached before any asynchronous port runs. No input field can
+ * approve an action; only the host transport or the bound grant store can answer. Abort checks
+ * bracket preparation, storage and the human wait, so a completed run never performs an effect.
+ * @param steps Domain preparation/effects and the host's description/transport ports.
+ * @param optional.remembered A persisted escalation store; omission requires a fresh decision.
+ * @returns A handler accepted by the registration kit's human-only actor rule.
+ * @throws Port failures propagate; a failed store cannot silently authorize an action.
+ * @complexity O(input size) for the snapshot plus bounded port calls and the human wait.
+ * @example createApprovalHandler({ prepare, describe, askHuman, run, notConfirmed });
+ */
+export function createApprovalHandler(steps, { remembered } = {}) {
+    return humanConfirmedHandler({
+        prepare: async ({ ctx }, options = {}) => {
+            const snapshot = { ...ctx, input: structuredClone(ctx.input), principal: { ...ctx.principal }, run: { ...ctx.run } };
+            if (snapshot.signal.aborted)
+                return { ctx: snapshot };
+            const value = await steps.prepare({ ctx: snapshot }, options);
+            if (snapshot.signal.aborted)
+                return { ctx: snapshot, value };
+            const plan = await steps.describe({ ctx: snapshot, prepared: value }, options);
+            return { ctx: snapshot, value, plan };
+        },
+        askHuman: async ({ prepared }, options = {}) => {
+            const { ctx, plan, value } = prepared;
+            const abandoned = () => ({ confirmed: false, result: steps.notConfirmed({ reason: 'abandoned', prepared: value }) });
+            if (ctx.signal.aborted || !plan)
+                return abandoned();
+            if (!plan.ask)
+                return { confirmed: true };
+            if (plan.rememberKey !== undefined && remembered) {
+                const approved = await remembered.has({ ctx, key: plan.rememberKey });
+                if (ctx.signal.aborted)
+                    return abandoned();
+                if (approved)
+                    return { confirmed: true };
+            }
+            const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) });
+            if (ctx.signal.aborted)
+                return abandoned();
+            if (answer.confirmed !== true)
+                return { confirmed: false, result: steps.notConfirmed({ reason: answer.reason, prepared: value }) };
+            prepared.choice = answer.choice;
+            if (plan.rememberKey !== undefined && remembered) {
+                await remembered.grant({ ctx, key: plan.rememberKey, confirmer: { id: ctx.principal.id, kind: 'user' } });
+            }
+            if (ctx.signal.aborted)
+                return abandoned();
+            return { confirmed: true };
+        },
+        run: ({ prepared }, options = {}) => {
+            const { ctx, value, choice } = prepared;
+            if (ctx.signal.aborted)
+                return Promise.resolve(steps.notConfirmed({ reason: 'abandoned', prepared: value }));
+            return steps.run({ ctx, prepared: value, confirmer: { id: ctx.principal.id, kind: 'user' }, choice }, options);
+        },
+    });
+}
+/** Page-local proposal transport for a browser that must return before its explicit reply arrives.
+ * It carries no principal or tool authorization: the host's execute port must re-check access.
+ * The private action is independent of the rendered snapshot; replies consume it before awaiting
+ * so double clicks/replayed replies cannot execute twice. Abort clears the proposal and listener.
+ * @returns An observable transport for an app dialog and its authenticated reply entry point.
+ * @complexity O(description size) to detach the proposal; O(listeners) to publish a change.
+ */
+export function createApprovalProposalStore({ responseTool, messages }, { createId = () => crypto.randomUUID() } = {}) {
+    let snapshot = { pending: null, error: null };
+    let action = null;
+    let detach = null;
+    const listeners = new Set();
+    const publish = (next) => { snapshot = next; for (const listener of listeners)
+        listener(); };
+    const clear = () => {
+        detach?.();
+        detach = null;
+        action = null;
+        publish({ pending: null, error: null });
+    };
+    return {
+        getSnapshot: (_required = {}, _optional = {}) => snapshot,
+        subscribe: ({ listener }, _optional = {}) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        propose({ description, execute, signal }, _optional = {}) {
+            if (signal.aborted)
+                throw new Error(messages.closed);
+            if (snapshot.pending)
+                throw new Error(messages.pending);
+            const frozenDescription = structuredClone(description);
+            const approvalId = createId();
+            action = { approvalId, execute, signal };
+            signal.addEventListener('abort', clear, { once: true });
+            detach = () => signal.removeEventListener('abort', clear);
+            publish({ pending: { approvalId, description: structuredClone(frozenDescription) }, error: null });
+            return { status: 'approval_required', approvalId, description: frozenDescription, responseTool };
+        },
+        async respond({ approvalId, approved }, _optional = {}) {
+            if (!action || action.approvalId !== approvalId)
+                throw new Error(messages.missing);
+            const prepared = action;
+            clear();
+            const answer = await resolveApproval({ signal: prepared.signal, askHuman: async () => approved === true ? { confirmed: true } : { confirmed: false, reason: 'declined' } });
+            if (!answer.confirmed)
+                return { status: 'declined' };
+            try {
+                return await prepared.execute();
+            }
+            catch (error) {
+                publish({ ...snapshot, error: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+        },
+    };
+}
+/** Apply a host classification through the same handler owner used by domain plans.
+ * @returns The registration with one approval handler; authorization policy is preserved.
+ */
+export function applyApprovalPolicy({ registration, classify, asks, describe, askHuman, notConfirmed }, optional = {}) {
+    return { ...registration, handler: createApprovalHandler({
+            prepare: async ({ ctx }) => classify({ input: ctx.input }),
+            describe: async ({ ctx, prepared }) => ({ ask: asks({ class: prepared }), description: await describe({ ctx, class: prepared }) }),
+            askHuman, notConfirmed,
+            run: ({ ctx }, options) => registration.handler(ctx, options),
+        }, optional) };
+}
+//# sourceMappingURL=approval.js.map

package/dist/fetch/cache.d.ts

@@ -0,0 +1,129 @@
+import type { Clock } from '../primitives/time.js';
+import type { QueryKey } from './types.js';
+/**
+ * Ten seconds covers reading, closing and reopening a record or bouncing between screens
+ * without paying for another identical request. Five seconds was too short for that read
+ * cycle; thirty seconds exposed more other-operator staleness than the conservative initial
+ * shared default should allow. There is no default polling/focus refresh, so this bounds
+ * the extra exposure on a quick revisit. Write invalidation bypasses freshness; reads that
+ * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
+ */
+export declare const DEFAULT_STALE_TIME = 10000;
+/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
+export declare const IDLE_RETENTION: number;
+export interface QueryCacheSchedulerPort {
+    schedule(required: {
+        callback: () => void;
+        delayMs: number;
+    }): unknown;
+    cancel(required: {
+        handle: unknown;
+    }): void;
+}
+/** Host connectivity and focus signals; the cache itself has no DOM dependency. */
+export interface FetchQueryEnvironmentPort {
+    isOnline(): boolean;
+    subscribeOnline(required: {
+        listener: (online: boolean) => void;
+    }): () => void;
+    subscribeFocus(required: {
+        listener: () => void;
+    }): () => void;
+}
+export interface FetchQueryCacheOptions {
+    clock?: Clock;
+    scheduler?: QueryCacheSchedulerPort;
+    environment?: FetchQueryEnvironmentPort;
+}
+export interface QueryState {
+    data: unknown;
+    error: Error | null;
+    status: 'pending' | 'success' | 'error';
+    isFetching: boolean;
+}
+export interface QueryObserver {
+    fetch: () => Promise<unknown>;
+    staleTime: number;
+    focus: boolean;
+}
+export interface CacheEntry {
+    key: QueryKey;
+    state: QueryState;
+    updatedAt: number;
+    invalidated: boolean;
+    replacement: number;
+    pending: Promise<unknown> | undefined;
+    pendingRead: {
+        fetch: () => Promise<unknown>;
+        staleTime: number;
+    } | undefined;
+    refreshAfterPending: boolean;
+    listeners: Set<() => void>;
+    observers: Set<QueryObserver>;
+    retention: number;
+    eviction: unknown;
+}
+export declare function toQueryError(value: unknown): Error;
+/** One provider-owned cache. Requests are shared by structural primitive keys.
+ * Failed reads retain earlier data; replacement writes supersede older requests.
+ * Idle entries live for at least five minutes or their declared freshness period. */
+export declare class FetchQueryCache {
+    private readonly entries;
+    private disposed;
+    private readonly clock;
+    private readonly scheduler;
+    private readonly environment;
+    private online;
+    private readonly onlineWaiters;
+    private releaseEnvironment;
+    constructor(_required?: Record<string, never>, { clock, scheduler, environment }?: FetchQueryCacheOptions);
+    entry({ key }: {
+        key: QueryKey;
+    }, { staleTime }?: {
+        staleTime?: number;
+    }): CacheEntry;
+    fresh({ entry, staleTime }: {
+        entry: CacheEntry;
+        staleTime: number;
+    }): boolean;
+    subscribe({ entry, listener }: {
+        entry: CacheEntry;
+        listener: () => void;
+    }): () => void;
+    observe({ entry, observer }: {
+        entry: CacheEntry;
+        observer: QueryObserver;
+    }): () => void;
+    /** Cache hits respect freshness; explicit refreshes restart background reads.
+     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
+    load<T>({ entry, fetch, staleTime }: {
+        entry: CacheEntry;
+        fetch: () => Promise<T>;
+        staleTime: number;
+    }, { force }?: {
+        force?: boolean;
+    }): Promise<T>;
+    replace({ entry, data }: {
+        entry: CacheEntry;
+        data: unknown;
+    }): void;
+    invalidate({ prefix }: {
+        prefix: QueryKey;
+    }): void;
+    onFocus(): void;
+    /** Execute a read/write once connectivity returns; failures are not retried.
+     * @param required.run Operation to invoke online.
+     * @returns The operation's original result or rejection. */
+    runOnline<T>({ run }: {
+        run: () => Promise<T>;
+    }): Promise<T>;
+    /** Stop timers on provider disposal; reactivate for React's effect replay. */
+    activate(): void;
+    dispose(): void;
+    private onOnline;
+    private refresh;
+    private publish;
+    private cancelEviction;
+    private scheduleEviction;
+}
+//# sourceMappingURL=cache.d.ts.map