@jini-ai/agent-plugins 0.4.7 → 0.4.8

package/dist/lifecycle/search.js

@@ -1,4 +1,39 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+/** These describe the conversation or target, not a plugin's topic. Prose-only hits remain
+ * available to explicit search without silently loading unrelated guidance. */
+const INCIDENTAL_TERMS = new Set('a an and are as at be build can could create do for from get help i in is it make me my new of on or please the this to use want we with you your site sites page pages website websites plugin plugins tell which load just don t anything'.split(' '));
+const DEPLOYMENT_TERMS = new Set('deploy deployment deploying deployed publish publishing published host hosting hosted'.split(' '));
+function automaticTerms(query) {
+    return [...new Set((query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).filter(term => !INCIDENTAL_TERMS.has(term)))];
+}
+/** A dedicated deployment provider (only `deploy-*` and `credential-scheme:*` capabilities) matches only a
+ * query naming both a deployment action and one of its vendor terms; any other plugin passes. */
+function passesDeploymentGate({ candidate, capabilities, terms }, _options = {}) {
+    const deployment = capabilities.filter(capability => capability.startsWith('deploy-'));
+    const dedicatedDeployment = deployment.length > 0 && capabilities.every(capability => capability.startsWith('deploy-') || capability.startsWith('credential-scheme:'));
+    if (!dedicatedDeployment)
+        return true;
+    const vendors = automaticTerms([candidate.pluginId, candidate.displayName ?? '', ...deployment.map(capability => capability.split(':')[1] ?? '')].join(' '))
+        .filter(term => !DEPLOYMENT_TERMS.has(term));
+    return terms.some(term => DEPLOYMENT_TERMS.has(term)) && terms.some(term => vendors.includes(term));
+}
+/** Score complete authored terms only: long descriptions must not manufacture relevance.
+ * Dedicated deployment providers additionally need both the action and their declared vendor.
+ * Mixed-purpose plugins can still match their other capabilities (for example source control).
+ */
+function automaticScore({ candidate, terms }, _options = {}) {
+    if (!candidate.enabled)
+        return 0;
+    const capabilities = candidate.provides ?? [];
+    if (!passesDeploymentGate({ candidate, capabilities, terms }))
+        return 0;
+    const fields = [
+        { terms: automaticTerms(capabilities.join(' ')), weight: 6 },
+        { terms: automaticTerms(`${candidate.pluginId} ${candidate.id ?? ''} ${candidate.displayName ?? ''}`), weight: 5 },
+        { terms: automaticTerms(candidate.keywords.join(' ')), weight: 4 },
+    ];
+    return terms.reduce((score, term) => score + fields.reduce((sum, field) => sum + (field.terms.includes(term) ? field.weight : 0), 0), 0);
+}
 function buildModule(ports) {
     const ID_FIELD_WEIGHT = 5;
     const KEYWORD_FIELD_WEIGHT = 4;
@@ -18,7 +53,7 @@ function buildModule(ports) {
    *  plain, independently-readable list rather than interleaved with the scoring loop itself. */
     function fieldHaystacks(candidate) {
         return [
-            { text: `${candidate.pluginId} ${candidate.id ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
+            { text: `${candidate.pluginId} ${candidate.id ?? ""} ${candidate.displayName ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
             { text: [...candidate.keywords, ...(candidate.provides ?? [])].join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
             { text: (candidate.description ?? "").toLowerCase(), weight: DESCRIPTION_FIELD_WEIGHT },
             {
@@ -48,20 +83,23 @@ function buildModule(ports) {
    * @param limit - Max matches to return, already clamped by the caller (mirrors
    * `component-catalog-tool.ts`'s handler, which owns the clamp so this function can stay a pure
    * "given these inputs, rank them" step with no knowledge of the tool's own schema bounds).
-   * @returns Matches with score > 0, sorted by score descending, truncated to `limit`. A candidate
+   * @returns Matches with score > 0, sorted by score descending then plugin id, truncated to `limit`. A candidate
    * that scores 0 (no term matched anything) is dropped, not returned at the bottom — the caller's own
    * "N installed, 0 matched" framing is what tells the model the workspace is not empty even when a
    * query matches nothing.
    * @complexity See this file's header.
    */
-    function rankInstalledAgentPlugins(query, candidates, limit) {
-        const terms = tokenize(query);
+    function rankInstalledAgentPlugins(query, candidates, limit, automatic = false) {
+        const terms = automatic ? automaticTerms(query) : tokenize(query);
         if (terms.length === 0)
             return [];
-        return candidates
-            .map((candidate) => ({ ...candidate, score: scoreCandidate(candidate, terms) }))
+        const ranked = candidates
+            .map((candidate) => ({ ...candidate, score: automatic ? automaticScore({ candidate, terms }) : scoreCandidate(candidate, terms) }))
             .filter((match) => match.score > 0)
-            .sort((a, b) => b.score - a.score)
+            .sort((a, b) => b.score - a.score || a.pluginId.localeCompare(b.pluginId));
+        // A weak shared keyword must not ride alongside a substantially stronger task owner.
+        const threshold = automatic ? Math.max(4, (ranked[0]?.score ?? 0) * 0.6) : 0;
+        return ranked.filter(match => match.score >= threshold)
             .slice(0, Math.max(limit, 0));
     }
     return { rankInstalledAgentPlugins };

package/dist/lifecycle/set-enabled.d.ts

@@ -20,9 +20,10 @@ export interface SetAgentPluginEnabledResult {
     readonly pluginId: string;
     /** As actually written and read back, not as requested. */
     readonly enabled: boolean;
+    readonly warnings?: readonly string[];
 }
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createSetEnabledModule(ports: AgentPluginLifecyclePorts): {
-    setAgentPluginEnabled: (input: SetAgentPluginEnabledInput) => Promise<SetAgentPluginEnabledResult>;
+    setAgentPluginEnabled: (input: SetAgentPluginEnabledInput, _optional?: Record<string, never>) => Promise<SetAgentPluginEnabledResult>;
 };
 //# sourceMappingURL=set-enabled.d.ts.map

package/dist/lifecycle/set-enabled.js

@@ -1,6 +1,9 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import { createPersistentStateModule } from './persistent-state.js';
+import { AgentPluginHostIncompatibleError, describeAgentPluginCompatibility, agentPluginDependentWarnings } from './compatibility.js';
 import { createActivationModule } from "./activation.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
+import { createAgentPluginUpdateStore, settleAgentPluginUpdateJournal } from "./update-store.js";
 /**
  * The id named is not installed in this workspace. A distinct class rather than a bare `Error` so
  * each caller can map it to its own boundary's vocabulary — 404 `AGENT_PLUGIN_NOT_FOUND` at the
@@ -13,21 +16,62 @@ export class AgentPluginNotInstalledError extends Error {
     }
 }
 function buildModule(ports) {
-    const { setAgentPluginActivation } = createActivationModule(ports);
+    const { setAgentPluginActivation, readAgentPluginActivations } = createActivationModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
-    async function setAgentPluginEnabled(input) {
-        const workspaceLayout = ports.layout.forWorkspace({ workspaceId: input.workspaceId });
-        const installed = await listInstalledPlugins(workspaceLayout.root);
-        if (!installed.some((plugin) => plugin.pluginId === input.pluginId)) {
-            throw new AgentPluginNotInstalledError({ pluginId: input.pluginId });
+    const persistentState = createPersistentStateModule(ports);
+    async function findInstalled({ workspaceRoot, pluginId }) {
+        const installed = await listInstalledPlugins(workspaceRoot);
+        const plugin = installed.find(candidate => candidate.pluginId === pluginId);
+        if (!plugin) {
+            throw new AgentPluginNotInstalledError({ pluginId });
         }
+        return { installed, plugin };
+    }
+    /** Refuses a host-incompatible enable; otherwise returns advisory warnings, never blocking. */
+    async function enablementWarnings({ input, workspaceRoot, installed, plugin }) {
+        const activations = await readAgentPluginActivations(workspaceRoot);
+        if (!input.enabled)
+            return agentPluginDependentWarnings({ plugin, installed, activations, nextProvides: [] });
+        const compatibility = describeAgentPluginCompatibility({ plugin, installed, activations });
+        // Several digests of one id can be installed (a bundled upgrade lands beside the old one), and
+        // the listing order is arbitrary, so every installed revision must be host-compatible.
+        const revisions = installed.filter(candidate => candidate.pluginId === plugin.pluginId);
+        if (revisions.some(revision => !describeAgentPluginCompatibility({ plugin: revision, installed, activations }).hostOk)) {
+            throw new AgentPluginHostIncompatibleError({ pluginId: input.pluginId });
+        }
+        return compatibility.missingRequires.map(id => `Needs ${id}`);
+    }
+    async function setEnabledLocked({ input, workspaceRoot }) {
+        // Re-read under the lock: an uninstall or update may have finished while this call waited.
+        const { installed, plugin } = await findInstalled({ workspaceRoot, pluginId: input.pluginId });
+        // Boot recovery of an unfinished update would overwrite this decision, so it refuses
+        // (PLUGIN_UPDATE_PENDING) until a boot recovers it.
+        await settleAgentPluginUpdateJournal({ store: createAgentPluginUpdateStore({ ports, workspaceId: input.workspaceId, pluginId: input.pluginId }) });
+        const warnings = await enablementWarnings({ input, workspaceRoot, installed, plugin });
         const written = await setAgentPluginActivation({
-            workspaceRoot: workspaceLayout.root,
+            workspaceRoot,
             pluginId: input.pluginId,
             enabled: input.enabled,
             actor: input.actor,
         });
-        return { pluginId: input.pluginId, enabled: written.plugins[input.pluginId]?.enabled ?? input.enabled };
+        // Always present: setAgentPluginActivation asserts the same id grammar its normalizer keeps and
+        // writes a boolean `enabled`, so the record it returns holds this entry (the former
+        // `?? input.enabled` fallback was unreachable).
+        return { pluginId: input.pluginId, enabled: written.plugins[input.pluginId].enabled, ...(warnings.length ? { warnings } : {}) };
+    }
+    /**
+     * Serialized with install/update/uninstall of the same plugin by the per-plugin state lock, so a
+     * toggle never judges compatibility against a package that is mid-swap. The lock is a
+     * non-reentrant file lock: no caller holds it around this function (checked 2026-10-21 in this
+     * package and in Tovu's admin route / `plugins_set_enabled` tool).
+     */
+    async function setAgentPluginEnabled(input, _optional = {}) {
+        const workspaceRoot = ports.layout.forWorkspace({ workspaceId: input.workspaceId }).root;
+        // Checked once before locking so an unknown or ungrammatical id stays a not-installed refusal
+        // and never creates workspace or lock directories (the lock path re-asserts the id grammar).
+        await findInstalled({ workspaceRoot, pluginId: input.pluginId });
+        return persistentState.withPluginLock({ workspaceRoot, pluginId: input.pluginId,
+            run: () => setEnabledLocked({ input, workspaceRoot }) });
     }
     return { setAgentPluginEnabled };
 }

package/dist/lifecycle/skill-file-reader.js

@@ -6,6 +6,36 @@ const TEXT_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".json", ".yaml", ".yml"
 const MAX_FILE_BYTES = 256 * 1024;
 const MAX_WALK_ENTRIES = 4096;
 const MAX_WALK_DEPTH = 32;
+const TOO_LARGE = "File request refused: exceeds the 256 KiB text limit; no content returned.";
+const UNREADABLE = "File request refused: file is missing or unreadable.";
+/** Reads an opened regular file of at most the cap; a file that grows past it after `stat` is still refused. */
+async function readOpened(handle) {
+    const stat = await handle.stat();
+    if (!stat.isFile())
+        return { refusal: "File request refused: only regular text files are readable." };
+    if (stat.size > MAX_FILE_BYTES)
+        return { refusal: TOO_LARGE };
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+        if (!bytesRead)
+            break;
+        length += bytesRead;
+    }
+    return length > MAX_FILE_BYTES ? { refusal: TOO_LARGE } : decodeText(buffer.subarray(0, length));
+}
+/** Admit only control-free UTF-8 text (tab, LF and CR allowed). */
+function decodeText(bytes) {
+    if (bytes.some(byte => (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) || byte === 127))
+        return { refusal: "File request refused: binary content cannot be read as text." };
+    try {
+        return { text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) };
+    }
+    catch {
+        return { refusal: "File request refused: binary or invalid UTF-8 content cannot be read as text." };
+    }
+}
 /**
  * Progressive disclosure for plugin AND standalone skills, with a skill-folder trust boundary.
  * Uses the lifecycle containment owner, native bounded reads and injected async filesystem effects.
@@ -14,67 +44,48 @@ const MAX_WALK_DEPTH = 32;
  */
 export function createSkillFileReader({ skillRoot, filesystem }, _options = {}) {
     const { assertContainedOnDisk } = createPackagePathsModule({ filesystem });
-    /** Reject traversal even when normalization would leave it inside the folder. */
+    /** Reject traversal even when normalization would leave it inside the folder.
+     * @returns The refusal message, or `undefined` for an admissible name. */
     function validateFile(file) {
         if (!file || file.includes("\0") || file.includes("\\") || path.posix.isAbsolute(file) || /^[a-zA-Z]:/.test(file) || file.split("/").some(segment => segment === "..")) {
-            throw new Error("File request refused: use a path relative to this skill folder, without traversal or absolute paths.");
+            return "File request refused: use a path relative to this skill folder, without traversal or absolute paths.";
         }
         if (!TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) {
-            throw new Error("File request refused: only supported text extensions are readable.");
+            return "File request refused: only supported text extensions are readable.";
         }
+        return undefined;
     }
-    /** Open the resolved target with no-follow and read at most cap + 1, including growing files. */
-    async function readText(file) {
-        validateFile(file);
-        let absolute;
+    /** The canonical contained target of `file`, or `undefined` when it is missing or escapes the folder. */
+    async function resolveTarget(file) {
         try {
-            absolute = await filesystem.realpath(await assertContainedOnDisk(skillRoot, file));
+            const absolute = await filesystem.realpath(await assertContainedOnDisk(skillRoot, file));
             // Recheck the canonical target through the same owner before opening it.
             const relative = path.relative(await filesystem.realpath(skillRoot), absolute);
             await assertContainedOnDisk(skillRoot, relative);
-            validateFile(relative.split(path.sep).join("/"));
+            return validateFile(relative.split(path.sep).join("/")) === undefined ? absolute : undefined;
         }
         catch {
-            throw new Error("File request refused: file is missing, unreadable, or resolves outside this skill folder.");
-        }
-        let handle;
-        try {
-            handle = await filesystem.open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-            const stat = await handle.stat();
-            if (!stat.isFile())
-                throw new Error("File request refused: only regular text files are readable.");
-            if (stat.size > MAX_FILE_BYTES)
-                throw new Error("File request refused: exceeds the 256 KiB text limit; no content returned.");
-            const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
-            let length = 0;
-            while (length < buffer.length) {
-                const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
-                if (!bytesRead)
-                    break;
-                length += bytesRead;
-            }
-            if (length > MAX_FILE_BYTES)
-                throw new Error("File request refused: exceeds the 256 KiB text limit; no content returned.");
-            const bytes = buffer.subarray(0, length);
-            if (bytes.some(byte => (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) || byte === 127))
-                throw new Error("File request refused: binary content cannot be read as text.");
-            try {
-                return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
-            }
-            catch {
-                throw new Error("File request refused: binary or invalid UTF-8 content cannot be read as text.");
-            }
-        }
-        catch (error) {
-            // Never reflect native errors or caller paths: either can contain an absolute host path.
-            if (error instanceof Error && error.message.startsWith("File request refused:"))
-                throw error;
-            throw new Error("File request refused: file is missing or unreadable.");
-        }
-        finally {
-            await handle?.close().catch(() => { });
+            return undefined;
         }
     }
+    /** Validate, resolve, then read one file; every refusal is a value, never a thrown native error. */
+    async function readText(file) {
+        const invalid = validateFile(file);
+        if (invalid !== undefined)
+            return { refusal: invalid };
+        const absolute = await resolveTarget(file);
+        if (absolute === undefined)
+            return { refusal: "File request refused: file is missing, unreadable, or resolves outside this skill folder." };
+        return readContained(absolute);
+    }
+    /** Open the resolved target with no-follow and read at most cap + 1, including growing files. */
+    async function readContained(absolute) {
+        const handle = await filesystem.open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(() => undefined);
+        if (!handle)
+            return { refusal: UNREADABLE };
+        // Never reflect native errors or caller paths: either can contain an absolute host path.
+        return readOpened(handle).catch(() => ({ refusal: UNREADABLE })).finally(() => handle.close().catch(() => { }));
+    }
     /** Skip directory symlinks (including cycles); contained file symlinks use the same read guard. */
     async function listFiles() {
         const files = [];
@@ -85,45 +96,48 @@ export function createSkillFileReader({ skillRoot, filesystem }, _options = {})
                 incomplete = true;
                 return;
             }
-            let entries;
-            try {
-                const directory = relative ? await assertContainedOnDisk(skillRoot, relative) : await filesystem.realpath(skillRoot);
-                entries = await filesystem.readdir(directory, { withFileTypes: true });
-            }
-            catch {
+            const entries = await readDirectory(relative);
+            if (!entries) {
                 incomplete = true;
                 return;
             }
-            for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            for (const entry of entries) {
                 if (remaining-- <= 0) {
                     incomplete = true;
                     break;
                 }
-                const file = relative ? `${relative}/${entry.name}` : entry.name;
-                if (entry.isDirectory())
-                    await walk(file, depth + 1);
-                else if (file !== "SKILL.md" && (entry.isFile() || entry.isSymbolicLink())) {
-                    try {
-                        await readText(file);
-                        files.push(file);
-                    }
-                    catch { /* Refused files must not be advertised as readable. */ }
-                }
+                await visit(entry, relative ? `${relative}/${entry.name}` : entry.name, depth);
             }
         }
+        async function visit(entry, file, depth) {
+            if (entry.isDirectory())
+                return walk(file, depth + 1);
+            if (file === "SKILL.md" || !(entry.isFile() || entry.isSymbolicLink()))
+                return;
+            // Refused files must not be advertised as readable.
+            if ("text" in await readText(file))
+                files.push(file);
+        }
         await walk("", 0);
         return { files: files.sort(), ...(incomplete ? { note: "Supporting-file inventory is incomplete: traversal limit reached or a directory is unreadable." } : {}) };
     }
+    /** One directory's entries in code-unit name order, or `undefined` when it cannot be read. */
+    async function readDirectory(relative) {
+        try {
+            const directory = relative ? await assertContainedOnDisk(skillRoot, relative) : await filesystem.realpath(skillRoot);
+            return (await filesystem.readdir(directory, { withFileTypes: true })).sort((a, b) => Number(a.name > b.name) - Number(a.name < b.name));
+        }
+        catch {
+            return undefined;
+        }
+    }
     return {
         async read(_input, options = {}) {
             const listing = await listFiles();
-            try {
-                return { ...listing, text: await readText(options.file ?? "SKILL.md") };
-            }
-            catch (error) {
-                const refusal = error instanceof Error ? error.message : "File request refused.";
-                return { files: listing.files, text: "", note: [refusal, `Valid supporting files: ${listing.files.join(", ") || "(none)"}. Omit file to request SKILL.md.`, listing.note].filter(Boolean).join(" ") };
-            }
+            const outcome = await readText(options.file ?? "SKILL.md");
+            if ("text" in outcome)
+                return { ...listing, text: outcome.text };
+            return { files: listing.files, text: "", note: [outcome.refusal, `Valid supporting files: ${listing.files.join(", ") || "(none)"}. Omit file to request SKILL.md.`, listing.note].filter(Boolean).join(" ") };
         },
     };
 }

package/dist/lifecycle/tools/capabilities.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @file Host capabilities a plugin tool receives at invocation, typed as ports: the host supplies
+ * every implementation (token store, guarded HTTP, limiter, artifact store) and Jini never names a
+ * provider. A per-call session wraps them so that (1) every capability stops working the moment the
+ * plugin's tools are revoked, even for a module that kept a reference, and (2) an access token the
+ * call obtained can never leave through the tool's result or error text. Those two gates are
+ * `openCapabilityGate`, shared with the admin-surface session so both enforce them identically.
+ *
+ * Plugin state reaches a tool read-only: the plugin's admin surface writes its settings (for example
+ * which of its products are on), and its tools must honor them, but an agent tool never changes them.
+ */
+/** Options for guarded HTTP; mirrors `@jini-ai/platform`'s guarded fetch, buffered bodies only. */
+export interface AgentPluginHttpOptions {
+    readonly method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}
+/** Mirrors `@jini-ai/http-kit`'s `RateLimitResult`, so a host can pass its limiter straight through. */
+export type AgentPluginLimitResult = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly retryAfterSeconds: number;
+};
+/** Plain JSON a plugin keeps in its plugin- and workspace-scoped state. */
+export type AgentPluginStateValue = null | boolean | number | string | readonly AgentPluginStateValue[] | {
+    readonly [key: string]: AgentPluginStateValue;
+};
+/**
+ * The read-only view of a plugin's own state: what its tools get, and what a host hands any other
+ * plugin execution context (form delivery, for example) that must honor the plugin's settings. A
+ * host handing it elsewhere passes an object with `get` only, never its whole store.
+ */
+export interface AgentPluginStateReader {
+    get(required: {
+        readonly key: string;
+    }, optional?: Record<string, never>): Promise<AgentPluginStateValue | null>;
+}
+export interface AgentPluginToolCapabilities {
+    /** Resolves a fresh access token for a connection the host has scoped to this plugin and workspace.
+     *  Never a refresh token. The host refuses a connectionRef the calling plugin does not own. */
+    readonly connections: {
+        getAccessToken(required: {
+            readonly connectionRef: string;
+        }, optional?: Record<string, never>): Promise<string>;
+    };
+    /** Outbound HTTP through the host's guarded client (allow-list, redirect refusal, deadlines). */
+    readonly http: {
+        fetch(required: {
+            readonly url: string;
+        }, optional?: AgentPluginHttpOptions): Promise<Response>;
+    };
+    /** Plugin-declared budgets; the host keys and sizes them. */
+    readonly limiter: {
+        check(required: {
+            readonly key: string;
+        }, optional?: Record<string, never>): Promise<AgentPluginLimitResult>;
+    };
+    /** Stores a file the run can hand to the user; returns an opaque reference, never a path. Absent
+     *  when the host has no artifact store, so a tool checks `capabilities.artifacts` before relying on it. */
+    readonly artifacts?: {
+        write(required: {
+            readonly name: string;
+            readonly mediaType: string;
+            readonly content: string | Uint8Array;
+        }, optional?: Record<string, never>): Promise<{
+            readonly artifactRef: string;
+        }>;
+    };
+    /** The SAME store the plugin's admin-surface state writes, keyed by the same plugin and workspace
+     *  scope. Read-only here: the session exposes `get` alone whatever object the host passes. */
+    readonly state: AgentPluginStateReader;
+}
+/** Context the host uses to scope capabilities: which plugin, which workspace/principal, which call. */
+export interface AgentPluginToolCapabilityScope {
+    readonly pluginId: string;
+    readonly workspaceId: string;
+    readonly principalId?: string;
+    readonly signal?: AbortSignal;
+}
+/** Host port: builds the capabilities for one call. Called once per invocation. */
+export type AgentPluginToolCapabilitiesPort = (required: AgentPluginToolCapabilityScope, optional?: Record<string, never>) => AgentPluginToolCapabilities;
+/** One limit for every reader and writer of plugin state; the admin-surface limits reuse it. */
+export declare const PLUGIN_STATE_MAX_KEY_LENGTH = 128;
+export declare const REVOKED_MESSAGE = "This plugin tool was disabled; its capabilities are revoked. Re-enable the plugin and retry.";
+export declare const WITHHELD_OUTPUT_MESSAGE = "The plugin tool result was withheld because it contained a connection credential.";
+export declare const WITHHELD_ERROR_MESSAGE = "The plugin tool failed and its error was withheld because it contained a connection credential.";
+/**
+ * Access tokens one plugin obtained, across all of its calls: plugin code that keeps a token in module
+ * scope must not be able to return or store it in a later call unseen.
+ */
+export type IssuedTokenMemory = Set<string>;
+/** Newest tokens kept; access tokens are short-lived, so older ones matter less than bounded memory. */
+export declare const ISSUED_TOKEN_MEMORY_LIMIT = 64;
+/** The host's one source of token memories, passed to its tool projection AND its admin-surface host. */
+export interface IssuedTokenMemories {
+    forPlugin(required: {
+        readonly pluginId: string;
+    }, optional?: Record<string, never>): IssuedTokenMemory;
+}
+/**
+ * One token memory per plugin, shared by every context that runs that plugin's code: its tools, its
+ * surface handlers and their state writes. Why per plugin and not per context or generation: those
+ * contexts can share module scope (a common lib module), and Node caches an imported module, so its
+ * scope outlives a re-sync; a memory per context or per generation would let a token obtained in one
+ * leave through the other. A host creates ONE and passes it to both seams.
+ * @complexity O(1) per lookup; space O(plugins * ISSUED_TOKEN_MEMORY_LIMIT).
+ */
+export declare function createIssuedTokenMemories(_required?: Record<string, never>, _optional?: Record<string, never>): IssuedTokenMemories;
+/**
+ * The credential scans alone, for plugin answers that need no capabilities (a tool's
+ * affected-resources disclosure): `mentionsToken`, and `sanitize` (an error, or a credential-free
+ * replacement without `cause`, since the cause may hold the token).
+ * @param required.issued - The plugin's token memory (see `createIssuedTokenMemories`).
+ * @complexity O(1) to open; the scans are O(scanned size * remembered tokens).
+ */
+export declare function openCredentialScan(required: {
+    readonly issued: IssuedTokenMemory;
+}, _optional?: Record<string, never>): {
+    mentionsToken: ({ value }: {
+        readonly value: unknown;
+    }) => boolean;
+    sanitize({ error }: {
+        readonly error: unknown;
+    }): unknown;
+};
+export type AgentPluginCredentialScan = ReturnType<typeof openCredentialScan>;
+/**
+ * The revocation and credential gates every capability session shares: this file's tool session and
+ * the admin-surface session (`../../admin-surfaces/surface-capabilities.ts`), so both revoke and scan
+ * the same way.
+ * @param required.isLive - False once the contributing plugin's contributions are revoked.
+ * @param required.issued - The plugin's token memory (see `createIssuedTokenMemories`).
+ * @returns `guard` (wraps a capability so it refuses once revoked), `noteToken` (records a token the
+ * call obtained), `mentionsToken`, and the `release` (result) and `sanitize` (error) gates.
+ * @complexity O(1) to open; the scans are O(serialized size * remembered tokens).
+ */
+export declare function openCapabilityGate(required: {
+    readonly isLive: () => boolean;
+    readonly issued: IssuedTokenMemory;
+}, _optional?: Record<string, never>): {
+    /** The result, unless it mentions a token this plugin obtained. */
+    release<T>({ value }: {
+        readonly value: T;
+    }): T;
+    mentionsToken: ({ value }: {
+        readonly value: unknown;
+    }) => boolean;
+    sanitize({ error }: {
+        readonly error: unknown;
+    }): unknown;
+    guard: <A extends unknown[], R>(call: (...args: A) => Promise<R>) => (...args: A) => Promise<R>;
+    noteToken({ token }: {
+        readonly token: string;
+    }): string;
+};
+export type AgentPluginCapabilityGate = ReturnType<typeof openCapabilityGate>;
+/** The host capabilities every session wraps the same way: guarded HTTP, limiter and artifacts
+ * (artifacts only when the host gives a store: absent stays absent, never a wrapper that throws). @complexity O(1). */
+export declare function guardSharedCapabilities(required: {
+    readonly gate: AgentPluginCapabilityGate;
+    readonly host: Pick<AgentPluginToolCapabilities, 'http' | 'limiter' | 'artifacts'>;
+}, _optional?: Record<string, never>): Pick<AgentPluginToolCapabilities, 'http' | 'limiter' | 'artifacts'>;
+/** The key shape every plugin state call shares, so a key never reaches the host as a path or a scope. */
+export declare function checkedStateKey(required: {
+    readonly key: unknown;
+}, _optional?: Record<string, never>): string;
+/**
+ * The read-only state view a session hands out: `get` alone, the key checked and passed on by itself
+ * (so plugin code cannot add a scope the host might honor), revoked with the session's gate.
+ * @complexity O(1) plus the key check.
+ */
+export declare function guardStateReader(required: {
+    readonly gate: AgentPluginCapabilityGate;
+    readonly state: AgentPluginStateReader;
+}, _optional?: Record<string, never>): AgentPluginStateReader;
+/**
+ * Opens the capability session for one tool call.
+ * @param required.capabilities - The host's capabilities for this call.
+ * @param required.isLive - False once the contributing plugin's tools are revoked.
+ * @param required.issued - The plugin's token memory, shared by all its calls and its surface handlers.
+ * @returns Wrapped capabilities plus `release` (result gate) and `sanitize` (error gate).
+ * @complexity O(1) to open; gates are O(serialized size).
+ */
+export declare function openCapabilitySession(required: {
+    readonly capabilities: AgentPluginToolCapabilities;
+    readonly isLive: () => boolean;
+    readonly issued: IssuedTokenMemory;
+}, _optional?: Record<string, never>): {
+    capabilities: AgentPluginToolCapabilities;
+    release: <T>({ value }: {
+        readonly value: T;
+    }) => T;
+    sanitize: ({ error }: {
+        readonly error: unknown;
+    }) => unknown;
+};
+//# sourceMappingURL=capabilities.d.ts.map