@jini-ai/agent-plugins 0.4.6 → 0.4.8

package/dist/admin-surfaces/theme.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file The host's design tokens for plugin surfaces: which `--jini-*` custom properties a host
+ * shares with every surface frame, how it reads their current values, and the envelope that sends
+ * a change after init.
+ *
+ * Why: a surface is a sandboxed frame without `allow-same-origin`, so it cannot see the admin's
+ * stylesheets, and its CSP allows only its own files. Values posted in a message are the only way
+ * its screens can match the admin and follow a light/dark or admin-theme change. The surface client
+ * applies them as custom properties on its root (CSSOM, which the CSP allows; never a style
+ * attribute or a stylesheet), so a surface writes `var(--jini-primary, <fallback>)` and looks right
+ * with or without a host that sends tokens.
+ *
+ * Values are text a host computed from its own CSS; anything that could fetch (`url(`, `image-set(`)
+ * or leave a declaration (`;`, braces) is dropped here and again in the surface client.
+ */
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION } from './protocol.js';
+/** The shared vocabulary: colours, type, radius, spacing, depth and focus. A host may send fewer. */
+export declare const ADMIN_SURFACE_THEME_TOKENS: readonly ["--jini-bg", "--jini-surface", "--jini-bg-subtle", "--jini-text", "--jini-text-muted", "--jini-border", "--jini-border-strong", "--jini-primary", "--jini-primary-ink", "--jini-link", "--jini-danger", "--jini-danger-bg", "--jini-success", "--jini-success-bg", "--jini-warning", "--jini-warning-bg", "--jini-font-ui", "--jini-font-mono", "--jini-font-size-xs", "--jini-font-size-sm", "--jini-font-size-base", "--jini-font-size-md", "--jini-radius-sm", "--jini-radius", "--jini-radius-md", "--jini-radius-pill", "--jini-space-1", "--jini-space-2", "--jini-space-3", "--jini-space-4", "--jini-shadow-xs", "--jini-shadow-sm", "--jini-control-bg", "--jini-control-border", "--jini-control-shadow-focus", "--jini-overlay-tooltip-bg", "--jini-overlay-tooltip-text", "--jini-overlay-tooltip-border"];
+export type AdminSurfaceThemeToken = (typeof ADMIN_SURFACE_THEME_TOKENS)[number];
+export type AdminSurfaceColorScheme = 'light' | 'dark';
+/** What a surface receives: the scheme for native controls plus the token values. */
+export interface AdminSurfaceTheme {
+    readonly scheme: AdminSurfaceColorScheme;
+    readonly tokens: Readonly<Partial<Record<AdminSurfaceThemeToken, string>>>;
+}
+/** Host page -> surface after init, whenever the admin's theme or colour scheme changes. */
+export interface AdminSurfaceThemeMessage {
+    readonly protocol: typeof ADMIN_SURFACE_PROTOCOL;
+    readonly version: typeof ADMIN_SURFACE_PROTOCOL_VERSION;
+    readonly kind: 'theme';
+    readonly mountId: string;
+    readonly theme: AdminSurfaceTheme;
+}
+/** Whether `value` is plain declaration text that cannot fetch anything or end its declaration.
+ * @complexity O(n) in the value length. */
+export declare function isSafeAdminSurfaceThemeValue(value: unknown): value is string;
+/**
+ * Reads the shared tokens from the host's computed style.
+ * @param required.style - Usually `getComputedStyle(element)` for the element the admin theme is on.
+ * @param optional.sources - Where to read a token when the host draws with its own name for it
+ *   (e.g. `{ '--jini-text': '--fg' }`); unnamed tokens are read under their own name.
+ * @returns Only the tokens with a safe, non-empty value.
+ * @complexity O(t) tokens.
+ */
+export declare function readAdminSurfaceTheme(required: {
+    readonly style: {
+        getPropertyValue(name: string): string;
+    };
+    readonly scheme: AdminSurfaceColorScheme;
+}, optional?: {
+    readonly sources?: Readonly<Partial<Record<AdminSurfaceThemeToken, string>>>;
+}): AdminSurfaceTheme;
+/** Builds the envelope that sends a changed theme to one mount's frame.
+ * @complexity O(1). */
+export declare function adminSurfaceThemeMessage(required: {
+    readonly mountId: string;
+    readonly theme: AdminSurfaceTheme;
+}, _optional?: Record<string, never>): AdminSurfaceThemeMessage;
+//# sourceMappingURL=theme.d.ts.map

package/dist/admin-surfaces/theme.js

@@ -0,0 +1,57 @@
+/**
+ * @file The host's design tokens for plugin surfaces: which `--jini-*` custom properties a host
+ * shares with every surface frame, how it reads their current values, and the envelope that sends
+ * a change after init.
+ *
+ * Why: a surface is a sandboxed frame without `allow-same-origin`, so it cannot see the admin's
+ * stylesheets, and its CSP allows only its own files. Values posted in a message are the only way
+ * its screens can match the admin and follow a light/dark or admin-theme change. The surface client
+ * applies them as custom properties on its root (CSSOM, which the CSP allows; never a style
+ * attribute or a stylesheet), so a surface writes `var(--jini-primary, <fallback>)` and looks right
+ * with or without a host that sends tokens.
+ *
+ * Values are text a host computed from its own CSS; anything that could fetch (`url(`, `image-set(`)
+ * or leave a declaration (`;`, braces) is dropped here and again in the surface client.
+ */
+import { ADMIN_SURFACE_PROTOCOL, ADMIN_SURFACE_PROTOCOL_VERSION } from './protocol.js';
+/** The shared vocabulary: colours, type, radius, spacing, depth and focus. A host may send fewer. */
+export const ADMIN_SURFACE_THEME_TOKENS = Object.freeze([
+    '--jini-bg', '--jini-surface', '--jini-bg-subtle', '--jini-text', '--jini-text-muted',
+    '--jini-border', '--jini-border-strong', '--jini-primary', '--jini-primary-ink', '--jini-link',
+    '--jini-danger', '--jini-danger-bg', '--jini-success', '--jini-success-bg', '--jini-warning', '--jini-warning-bg',
+    '--jini-font-ui', '--jini-font-mono', '--jini-font-size-xs', '--jini-font-size-sm', '--jini-font-size-base', '--jini-font-size-md',
+    '--jini-radius-sm', '--jini-radius', '--jini-radius-md', '--jini-radius-pill',
+    '--jini-space-1', '--jini-space-2', '--jini-space-3', '--jini-space-4',
+    '--jini-shadow-xs', '--jini-shadow-sm', '--jini-control-bg', '--jini-control-border', '--jini-control-shadow-focus',
+    '--jini-overlay-tooltip-bg', '--jini-overlay-tooltip-text', '--jini-overlay-tooltip-border',
+]);
+const MAX_VALUE_LENGTH = 200;
+const UNSAFE_VALUE = /url\(|image\(|image-set\(|[;{}<>\\@]/i;
+/** Whether `value` is plain declaration text that cannot fetch anything or end its declaration.
+ * @complexity O(n) in the value length. */
+export function isSafeAdminSurfaceThemeValue(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= MAX_VALUE_LENGTH && !UNSAFE_VALUE.test(value);
+}
+/**
+ * Reads the shared tokens from the host's computed style.
+ * @param required.style - Usually `getComputedStyle(element)` for the element the admin theme is on.
+ * @param optional.sources - Where to read a token when the host draws with its own name for it
+ *   (e.g. `{ '--jini-text': '--fg' }`); unnamed tokens are read under their own name.
+ * @returns Only the tokens with a safe, non-empty value.
+ * @complexity O(t) tokens.
+ */
+export function readAdminSurfaceTheme(required, optional = {}) {
+    const tokens = {};
+    for (const token of ADMIN_SURFACE_THEME_TOKENS) {
+        const value = required.style.getPropertyValue(optional.sources?.[token] ?? token).trim();
+        if (isSafeAdminSurfaceThemeValue(value))
+            tokens[token] = value;
+    }
+    return { scheme: required.scheme, tokens };
+}
+/** Builds the envelope that sends a changed theme to one mount's frame.
+ * @complexity O(1). */
+export function adminSurfaceThemeMessage(required, _optional = {}) {
+    return { protocol: ADMIN_SURFACE_PROTOCOL, version: ADMIN_SURFACE_PROTOCOL_VERSION, kind: 'theme', mountId: required.mountId, theme: required.theme };
+}
+//# sourceMappingURL=theme.js.map

package/dist/folder-zip-node.d.ts

@@ -0,0 +1,11 @@
+/** Reads a local folder into the browser upload encoder. Refuses links/special files and bounds
+ * entries and bytes before allocation; the resulting ZIP still requires the install validator.
+ * @throws {FolderZipError} Empty, unreadable, linked, or over-limit folders.
+ * @complexity O(e log e + b) time for e entries and b bytes; O(e + b) space,
+ * bounded to 4096 entries and maxBytes. No network I/O.
+ */
+export declare function zipLocalFolder(required: {
+    path: string;
+    maxBytes: number;
+}, _optional?: Record<string, never>): Promise<Uint8Array>;
+//# sourceMappingURL=folder-zip-node.d.ts.map

package/dist/folder-zip-node.js

@@ -0,0 +1,84 @@
+import * as fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { FOLDER_MAX_FILES, FOLDER_UNREADABLE, FolderZipError, zipFolderFiles } from "./folder-zip.js";
+async function readLocalFile(required, _optional = {}) {
+    const { filesystem, root, filename, name, maxBytes } = required;
+    if (await filesystem.realpath(filename) !== filename)
+        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+    // O_NOFOLLOW refuses a file replaced with a symlink between enumeration and opening.
+    const file = await filesystem.open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const info = await file.stat();
+        if (!info.isFile())
+            throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+        const total = required.total + info.size;
+        if (total > maxBytes)
+            throw new FolderZipError("too-large", "Folder is over the upload limit.");
+        // One extra byte detects growth without an unbounded readFile allocation.
+        const bytes = Buffer.alloc(info.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const read = await file.read(bytes, length, bytes.length - length, null);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        if (length !== info.size)
+            throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+        const picked = new File([new Uint8Array(bytes.subarray(0, length))], name);
+        Object.defineProperty(picked, "webkitRelativePath", { value: `folder/${path.relative(root, filename).split(path.sep).join("/")}` });
+        return { file: picked, total };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function collectDirectory(required, _optional = {}) {
+    const { filesystem, root, directory, collection, maxBytes } = required;
+    if (!(await filesystem.lstat(directory)).isDirectory() || await filesystem.realpath(directory) !== directory)
+        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+    const handle = await filesystem.opendir(directory);
+    // Mutate the traversal's owned buffers so visiting directories does not copy accumulated files.
+    for await (const entry of handle) {
+        if (++collection.entries > FOLDER_MAX_FILES)
+            throw new FolderZipError("too-many", `More than ${FOLDER_MAX_FILES} entries.`);
+        const filename = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            collection.pending.push(filename);
+            continue;
+        }
+        if (!entry.isFile())
+            throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+        const result = await readLocalFile({ filesystem, root, filename, name: entry.name, total: collection.total, maxBytes });
+        collection.total = result.total;
+        collection.files.push(result.file);
+    }
+}
+/** Reads a local folder into the browser upload encoder. Refuses links/special files and bounds
+ * entries and bytes before allocation; the resulting ZIP still requires the install validator.
+ * @throws {FolderZipError} Empty, unreadable, linked, or over-limit folders.
+ * @complexity O(e log e + b) time for e entries and b bytes; O(e + b) space,
+ * bounded to 4096 entries and maxBytes. No network I/O.
+ */
+export async function zipLocalFolder(required, _optional = {}) {
+    const collection = { files: [], pending: [], entries: 0, total: 0 };
+    try {
+        const root = await fs.realpath(required.path);
+        collection.pending.push(root);
+        while (collection.pending.length) {
+            const directory = collection.pending.pop();
+            await collectDirectory({ filesystem: fs, root, directory, collection, maxBytes: required.maxBytes });
+        }
+        const { files } = collection;
+        // Stable order gives repeat local-folder installs identical ZIP digests.
+        files.sort((a, b) => a.webkitRelativePath < b.webkitRelativePath ? -1 : a.webkitRelativePath > b.webkitRelativePath ? 1 : 0);
+        return new Uint8Array(await (await zipFolderFiles({ files, maxBytes: required.maxBytes })).arrayBuffer());
+    }
+    catch (error) {
+        if (error instanceof FolderZipError)
+            throw error;
+        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+    }
+}
+//# sourceMappingURL=folder-zip-node.js.map

package/dist/folder-zip.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Packs a folder the operator picked (`<input type=file webkitdirectory>`) into one `.zip`
+ * `File`, so "Upload a folder" travels the exact path a `.zip` upload does: same size limit, same
+ * server-side archive checks, same Preview trust review. The install routes only take
+ * `application/zip`, so zipping here keeps one server path instead of adding a second upload format.
+ *
+ * Stored mode (no compression): the upload limit is on the archive, and a plugin folder is small
+ * text, so deflate would add a dependency for little gain. `@jini-ai/ui` has a stored-mode
+ * `buildZip`, but it is text-only (it would corrupt an image) and not exported, so this is the
+ * binary-safe twin, extracted to Jini so browser and local-folder uploads use the same encoder.
+ */
+/** Refusals, as dictionary keys the caller translates. */
+export declare const FOLDER_EMPTY = "That folder is empty.";
+export declare const FOLDER_UNREADABLE = "Could not read that folder. Try again.";
+/** The archive readers' entry cap (`install-archive.ts`, the Agent Plugins reader): refused here
+ *  before any bytes are read. */
+export declare const FOLDER_MAX_FILES = 4096;
+export declare class FolderZipError extends Error {
+    readonly reason: "empty" | "too-large" | "too-many" | "unreadable";
+    constructor(reason: "empty" | "too-large" | "too-many" | "unreadable", message: string);
+}
+/** @complexity O(n) in the byte count. */
+export declare function crc32(bytes: Uint8Array): number;
+/**
+ * Zips the files of one picked folder.
+ *
+ * @param required.files - Every file the folder picker returned.
+ * @param required.maxBytes - The upload limit; the folder's raw size alone over it is refused before
+ *   reading, and the finished zip is checked again (headers add a little).
+ * @returns `<folder>.zip`, typed `application/zip`.
+ * @throws {FolderZipError} empty folder, too many files, too large, or a file that could not be read.
+ * @complexity O(total bytes).
+ */
+export declare function zipFolderFiles(required: {
+    files: readonly File[];
+    maxBytes: number;
+}, _optional?: Record<string, never>): Promise<File>;
+//# sourceMappingURL=folder-zip.d.ts.map

package/dist/folder-zip.js

@@ -0,0 +1,134 @@
+/**
+ * @file Packs a folder the operator picked (`<input type=file webkitdirectory>`) into one `.zip`
+ * `File`, so "Upload a folder" travels the exact path a `.zip` upload does: same size limit, same
+ * server-side archive checks, same Preview trust review. The install routes only take
+ * `application/zip`, so zipping here keeps one server path instead of adding a second upload format.
+ *
+ * Stored mode (no compression): the upload limit is on the archive, and a plugin folder is small
+ * text, so deflate would add a dependency for little gain. `@jini-ai/ui` has a stored-mode
+ * `buildZip`, but it is text-only (it would corrupt an image) and not exported, so this is the
+ * binary-safe twin, extracted to Jini so browser and local-folder uploads use the same encoder.
+ */
+/** Refusals, as dictionary keys the caller translates. */
+export const FOLDER_EMPTY = "That folder is empty.";
+export const FOLDER_UNREADABLE = "Could not read that folder. Try again.";
+/** The archive readers' entry cap (`install-archive.ts`, the Agent Plugins reader): refused here
+ *  before any bytes are read. */
+export const FOLDER_MAX_FILES = 4096;
+export class FolderZipError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** 1980-01-01, the earliest DOS date: a fixed stamp, so the same folder always zips to the same
+ *  bytes (an all-zero date is month 0, which some readers refuse). */
+const DOS_DATE_1980 = (1 << 5) | 1;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+/** @complexity O(n) in the byte count. */
+export function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** A picked file's path inside the picked folder: `webkitRelativePath` minus the folder's own name,
+ *  so the package's files sit at the top of the zip — what a server-path install of that same
+ *  folder reads, and where both install routes look for the manifest. */
+function entryPath(file) {
+    const relative = (file.webkitRelativePath || file.name).replaceAll("\\", "/");
+    const slash = relative.indexOf("/");
+    return slash < 0 ? { folder: "", path: relative } : { folder: relative.slice(0, slash), path: relative.slice(slash + 1) };
+}
+async function readFolderFile(required, _optional = {}) {
+    try {
+        return new Uint8Array(await required.file.arrayBuffer());
+    }
+    catch {
+        throw new FolderZipError("unreadable", FOLDER_UNREADABLE);
+    }
+}
+/**
+ * Zips the files of one picked folder.
+ *
+ * @param required.files - Every file the folder picker returned.
+ * @param required.maxBytes - The upload limit; the folder's raw size alone over it is refused before
+ *   reading, and the finished zip is checked again (headers add a little).
+ * @returns `<folder>.zip`, typed `application/zip`.
+ * @throws {FolderZipError} empty folder, too many files, too large, or a file that could not be read.
+ * @complexity O(total bytes).
+ */
+export async function zipFolderFiles(required, _optional = {}) {
+    const { files, maxBytes } = required;
+    if (files.length === 0)
+        throw new FolderZipError("empty", FOLDER_EMPTY);
+    if (files.length > FOLDER_MAX_FILES)
+        throw new FolderZipError("too-many", `More than ${FOLDER_MAX_FILES} files.`);
+    if (files.reduce((sum, file) => sum + file.size, 0) > maxBytes)
+        throw new FolderZipError("too-large", "Folder is over the upload limit.");
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    let folder = "";
+    for (const file of files) {
+        const entry = entryPath(file);
+        folder ||= entry.folder;
+        const data = await readFolderFile({ file });
+        const name = encoder.encode(entry.path);
+        const crc = crc32(data);
+        // Bit 11: the name is UTF-8, so a reader never decodes it as CP437.
+        const flags = name.some((b) => b > 0x7f) ? 0x0800 : 0;
+        const local = new Uint8Array(30 + name.length);
+        const lv = new DataView(local.buffer);
+        lv.setUint32(0, 0x04034b50, true);
+        lv.setUint16(4, 20, true);
+        lv.setUint16(6, flags, true);
+        lv.setUint16(12, DOS_DATE_1980, true);
+        lv.setUint32(14, crc, true);
+        lv.setUint32(18, data.length, true);
+        lv.setUint32(22, data.length, true);
+        lv.setUint16(26, name.length, true);
+        local.set(name, 30);
+        // Version-made-by 20 (MS-DOS, external attributes 0): a plain file to every reader, so the
+        // server's Unix special-entry guard never sees a mode to refuse.
+        const header = new Uint8Array(46 + name.length);
+        const cv = new DataView(header.buffer);
+        cv.setUint32(0, 0x02014b50, true);
+        cv.setUint16(4, 20, true);
+        cv.setUint16(6, 20, true);
+        cv.setUint16(8, flags, true);
+        cv.setUint16(14, DOS_DATE_1980, true);
+        cv.setUint32(16, crc, true);
+        cv.setUint32(20, data.length, true);
+        cv.setUint32(24, data.length, true);
+        cv.setUint16(28, name.length, true);
+        cv.setUint32(42, offset, true);
+        header.set(name, 46);
+        chunks.push(local, data);
+        central.push(header);
+        offset += local.length + data.length;
+    }
+    const centralSize = central.reduce((sum, part) => sum + part.length, 0);
+    const end = new Uint8Array(22);
+    const ev = new DataView(end.buffer);
+    ev.setUint32(0, 0x06054b50, true);
+    ev.setUint16(8, files.length, true);
+    ev.setUint16(10, files.length, true);
+    ev.setUint32(12, centralSize, true);
+    ev.setUint32(16, offset, true);
+    if (offset + centralSize + end.length > maxBytes)
+        throw new FolderZipError("too-large", "Folder is over the upload limit.");
+    return new File([...chunks, ...central, end], `${folder || "folder"}.zip`, { type: "application/zip" });
+}
+//# sourceMappingURL=folder-zip.js.map

package/dist/lifecycle/automatic-use.d.ts

@@ -0,0 +1,79 @@
+/** Automatic-use policy for one execution context. Catalog, trust, consent and presentation are ports. */
+import type { AgentPluginSearchCandidate, AgentPluginSearchMatch } from './search.js';
+export type ChatAgentPlugins = 'auto' | 'ask' | 'off';
+export declare const DEFAULT_CHAT_AGENT_PLUGINS: ChatAgentPlugins;
+/** Browser-owned, per-conversation state. Clearing it deliberately permits a fresh question. */
+export interface ChatAgentPluginState {
+    decision: {
+        selected: readonly string[];
+        asked?: boolean;
+    } | null;
+    excluded: readonly string[];
+}
+export interface AutomaticAgentPluginMatch {
+    id: string;
+    name: string;
+    why: string;
+}
+export interface AutomaticAgentPluginPorts {
+    list(input: Record<string, never>, options?: Record<string, never>): Promise<readonly AgentPluginSearchCandidate[]>;
+    rank(input: {
+        query: string;
+        candidates: readonly AgentPluginSearchCandidate[];
+        limit: number;
+    }, options?: Record<string, never>): readonly AgentPluginSearchMatch[];
+    /** Must recheck activation/trust and return real guidance, never a pointer to unopened guidance. */
+    resolve(input: {
+        pluginId: string;
+    }, options?: Record<string, never>): Promise<string>;
+    /** Only a principal-bound human exchange may return action=auto. */
+    ask(input: {
+        matches: readonly AutomaticAgentPluginMatch[];
+        signal?: AbortSignal;
+    }, options?: Record<string, never>): Promise<{
+        action: 'use' | 'skip' | 'auto';
+        selected: readonly string[];
+    }>;
+    saveAuto(input: Record<string, never>, options?: Record<string, never>): Promise<void>;
+    publish(input: {
+        state: ChatAgentPluginState;
+        plugins: readonly {
+            id: string;
+            name: string;
+        }[];
+    }, options?: Record<string, never>): Promise<void>;
+}
+/** Validate the request's small browser state; malformed state means no previous decision.
+ * @returns A fresh state; no caller input is mutated. @complexity O(n) in saved identities.
+ */
+export declare function readChatAgentPluginState({ value }: {
+    value: unknown;
+}, _options?: {}): ChatAgentPluginState;
+/** Create one run's preparation owner. Calls serialize so parallel tool writes share one question.
+ * @param required Host effects and the person's mode; browser state is advisory selection only.
+ * @returns prepare(): a relevance note or capability guidance; load(): one plugin's real guidance.
+ * @complexity O(p*t) ranking plus at most one resolve per admitted plugin; relevance, not a count, bounds it.
+ * @example const use = createAutomaticAgentPluginUse({ mode: 'auto', ports });
+ */
+export declare function createAutomaticAgentPluginUse({ mode, state: initialState, ports }: {
+    mode: ChatAgentPlugins;
+    state?: ChatAgentPluginState | undefined;
+    ports: AutomaticAgentPluginPorts;
+}, _options?: {}): {
+    /** Suggest relevant metadata for a query; capability calls load only their providers. */
+    prepare: (input: {
+        query?: string;
+        capabilities?: readonly string[];
+        loaded?: readonly string[];
+        signal?: AbortSignal;
+    }, _options?: {}) => Promise<string>;
+    /** Resolve one active, permitted id and publish usage only after real guidance is read.
+     * Returns an empty string for denied, unavailable, or already-delivered guidance.
+     * @example await controller.load({ pluginId: 'my-plugin' });
+     */
+    load: (input: {
+        pluginId: string;
+        signal?: AbortSignal;
+    }, _options?: {}) => Promise<string>;
+};
+//# sourceMappingURL=automatic-use.d.ts.map

package/dist/lifecycle/automatic-use.js

@@ -0,0 +1,165 @@
+export const DEFAULT_CHAT_AGENT_PLUGINS = 'auto';
+/** Use the same one-line metadata reason in consent and progressive disclosure. */
+function describeMatch({ plugin }, _options = {}) {
+    return { id: plugin.pluginId, name: (plugin.displayName ?? plugin.pluginId).replace(/\s+/g, ' '),
+        why: (plugin.summary ?? plugin.description ?? `Provides ${(plugin.provides ?? plugin.keywords).join(', ')}`).split(/[\n.]/)[0].replace(/\s+/g, ' ').slice(0, 180) };
+}
+/** Present metadata only. A byte is a conservative upper bound on a UTF-8 text token, so
+ * this stays below 600 tokens without a model-specific tokenizer or a plugin-count limit.
+ * @returns A bounded note in relevance order, with discovery for every omitted match.
+ * @complexity O(p) metadata formatting; output is bounded independently of plugin count.
+ */
+function relevantPluginNote({ matches }, _options = {}) {
+    if (!matches.length)
+        return '';
+    const header = 'Relevant agent plugins for this request:\n';
+    const footer = '\nLoad one with load_agent_plugin({ pluginId }) before acting on that part.';
+    const more = (remaining) => remaining ? `\n+${remaining} more relevant: search_agent_plugin_local({ query: <same request>, offset: 0 }); page with nextOffset` : '';
+    const lines = [];
+    const bytes = (text) => new TextEncoder().encode(text).length;
+    for (const match of matches) {
+        const { id, name, why } = describeMatch({ plugin: match });
+        const line = `${name} (${id}) — ${why}`;
+        if (bytes(header + [...lines, line].join('\n') + more(matches.length - lines.length - 1) + footer) > 600)
+            break;
+        lines.push(line);
+    }
+    return header + lines.join('\n') + more(matches.length - lines.length) + footer;
+}
+/** An explicit id or a guarded capability admits its providers outright; a query is ranked for relevance. */
+function rankCandidates({ candidates, input, ports }, _options = {}) {
+    const { pluginId, capabilities } = input;
+    const admit = (plugins) => plugins.map(plugin => ({ ...plugin, score: 4 }));
+    if (pluginId !== undefined)
+        return admit(candidates.filter(plugin => plugin.pluginId === pluginId));
+    if (capabilities)
+        return admit(candidates.filter(plugin => plugin.provides?.some(capability => capabilities.includes(capability))));
+    return ports.rank({ query: input.query ?? '', candidates, limit: candidates.length }, {});
+}
+/** Validate the request's small browser state; malformed state means no previous decision.
+ * @returns A fresh state; no caller input is mutated. @complexity O(n) in saved identities.
+ */
+export function readChatAgentPluginState({ value }, _options = {}) {
+    const empty = { decision: null, excluded: [] };
+    if (!value || typeof value !== 'object')
+        return empty;
+    const record = value;
+    const ids = (raw) => Array.isArray(raw) && raw.every(id => typeof id === 'string' && id.length > 0 && id.length <= 160);
+    if (!ids(record.excluded))
+        return empty;
+    const decision = record.decision;
+    if (decision !== null && (!decision || !ids(decision.selected)))
+        return empty;
+    return { decision: decision ? { selected: [...new Set(decision.selected)], ...(typeof decision.asked === 'boolean' ? { asked: decision.asked } : {}) } : null, excluded: [...new Set(record.excluded)] };
+}
+/** Create one run's preparation owner. Calls serialize so parallel tool writes share one question.
+ * @param required Host effects and the person's mode; browser state is advisory selection only.
+ * @returns prepare(): a relevance note or capability guidance; load(): one plugin's real guidance.
+ * @complexity O(p*t) ranking plus at most one resolve per admitted plugin; relevance, not a count, bounds it.
+ * @example const use = createAutomaticAgentPluginUse({ mode: 'auto', ports });
+ */
+export function createAutomaticAgentPluginUse({ mode, state: initialState, ports }, _options = {}) {
+    let state = readChatAgentPluginState({ value: initialState });
+    const delivered = new Map();
+    const alreadyLoaded = new Set();
+    let publishedSize;
+    let queue = Promise.resolve();
+    /** Ask mode admits only consented matches; the first non-empty match set asks the person once. */
+    async function applyConsent({ matches }, { signal } = {}) {
+        if (mode !== 'ask')
+            return matches;
+        const { decision } = state;
+        if (decision === null || decision.asked === false)
+            return matches.length ? askConsent({ matches }, { signal }) : matches;
+        // Consent survives cold runs; relevance still comes from this request or write capability.
+        // Later matches do not inherit consent, and exclusions were applied before ranking.
+        return matches.filter(plugin => decision.selected.includes(plugin.pluginId));
+    }
+    async function askConsent({ matches }, { signal } = {}) {
+        const offered = matches.map(plugin => describeMatch({ plugin }));
+        const answer = await ports.ask({ matches: offered, ...(signal ? { signal } : {}) }, {});
+        const selected = answer.action === 'skip' ? [] : answer.selected.filter(id => matches.some(plugin => plugin.pluginId === id));
+        state = { decision: { selected, asked: true }, excluded: [...new Set([...state.excluded, ...matches.filter(plugin => !selected.includes(plugin.pluginId)).map(plugin => plugin.pluginId)])] };
+        if (answer.action === 'auto') {
+            await ports.saveAuto({}, {});
+            mode = 'auto';
+        }
+        // Consent changes only this person's preference, never a workspace default.
+        return matches.filter(plugin => selected.includes(plugin.pluginId));
+    }
+    async function resolveGuidance({ matches }, { signal } = {}) {
+        const guidance = [];
+        for (const match of matches) {
+            if (signal?.aborted)
+                break;
+            try {
+                const text = await ports.resolve({ pluginId: match.pluginId }, {});
+                if (!text.trim())
+                    continue;
+                delivered.set(match.pluginId, match.displayName ?? match.pluginId);
+                guidance.push(text);
+            }
+            catch {
+                // Automatic guidance is advisory; unavailable plugins must not block the run.
+            }
+        }
+        return guidance;
+    }
+    /** Auto mode records everything delivered as selected, keeping any earlier selection and asked flag. */
+    function rememberAutoSelection() {
+        if (mode !== 'auto' || !delivered.size)
+            return;
+        const { decision } = state;
+        state = { ...state, decision: { selected: [...new Set([...(decision?.selected ?? []), ...delivered.keys()])], asked: decision?.asked ?? false } };
+    }
+    /** Initialize usage after a decision (including Skip), then publish only loaded-set changes.
+     * Empty discovery must not consume that initial publication: a later Ask answer must persist.
+     */
+    async function publishUsage() {
+        if (publishedSize === delivered.size || (delivered.size === 0 && state.decision === null))
+            return;
+        publishedSize = delivered.size;
+        try {
+            await ports.publish({ state, plugins: [...delivered].map(([id, name]) => ({ id, name })) }, {});
+        }
+        catch {
+            // Usage publication is advisory; losing its event must not discard resolved model guidance.
+        }
+    }
+    /** Query preflight suggests; only an explicit id or guarded capability resolves guidance.
+     * Effects serialize with loads so a suggestion never consumes a backstop's delivery.
+     */
+    async function prepare(input) {
+        if (mode === 'off' || input.signal?.aborted)
+            return '';
+        for (const id of input.loaded ?? [])
+            alreadyLoaded.add(id);
+        const candidates = (await ports.list({}, {})).filter(plugin => plugin.enabled && !state.excluded.includes(plugin.pluginId));
+        const ranked = rankCandidates({ candidates, input, ports });
+        // Owner decision 2026-10-18: no per-chat plugin count; the relevance threshold and vendor gate decide.
+        const relevant = ranked.filter(plugin => !delivered.has(plugin.pluginId) && !alreadyLoaded.has(plugin.pluginId));
+        const matches = await applyConsent({ matches: relevant }, { signal: input.signal });
+        // Relevance is disclosure, never evidence that the model has read any guidance.
+        const shouldLoad = input.pluginId !== undefined || !!input.capabilities?.length;
+        const result = shouldLoad ? (await resolveGuidance({ matches }, { signal: input.signal })).join('\n\n') : relevantPluginNote({ matches });
+        rememberAutoSelection();
+        await publishUsage();
+        return result;
+    }
+    /** Share one queue between preflight, explicit reads and simultaneous guarded writes. */
+    function enqueue(input) {
+        const next = queue.then(() => prepare(input));
+        queue = next.catch(() => undefined);
+        return next;
+    }
+    return {
+        /** Suggest relevant metadata for a query; capability calls load only their providers. */
+        prepare: (input, _options = {}) => enqueue(input),
+        /** Resolve one active, permitted id and publish usage only after real guidance is read.
+         * Returns an empty string for denied, unavailable, or already-delivered guidance.
+         * @example await controller.load({ pluginId: 'my-plugin' });
+         */
+        load: (input, _options = {}) => enqueue(input),
+    };
+}
+//# sourceMappingURL=automatic-use.js.map

package/dist/lifecycle/compatibility-metadata.d.ts

@@ -0,0 +1,19 @@
+/** Stored in place of a present-but-unusable range so the plugin stays listable but never enables. */
+export declare const INVALID_AGENT_PLUGIN_HOST_RANGE = "<invalid>";
+/** A blank string is a semver wildcard, so blank is rejected here rather than silently allowed.
+ * The same holds for a blank `||` alternative: semver reads '>=99 ||' as '*', i.e. allow-all. */
+export declare function isValidAgentPluginHostRange({ range }: {
+    readonly range: string;
+}, _optional?: Record<string, never>): boolean;
+/** Reads metadata in the host-selected namespace. A present malformed range stays incompatible;
+ * malformed `requires` is advisory only, so it is dropped with a warning.
+ * @returns Normalized advisory metadata and parse warnings. @complexity O(r).
+ */
+export declare function readAgentPluginCompatibilityMetadata({ extension }: {
+    readonly extension: Readonly<Record<string, unknown>>;
+}, _optional?: Record<string, never>): {
+    requires?: readonly string[];
+    hostRange?: string;
+    warnings: string[];
+};
+//# sourceMappingURL=compatibility-metadata.d.ts.map