@jini-ai/agent-plugins 0.4.6 → 0.4.8

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

package/dist/lifecycle/tools/capabilities.js

@@ -0,0 +1,213 @@
+/**
+ * @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.
+ */
+/** One limit for every reader and writer of plugin state; the admin-surface limits reuse it. */
+export const PLUGIN_STATE_MAX_KEY_LENGTH = 128;
+const STATE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export const REVOKED_MESSAGE = 'This plugin tool was disabled; its capabilities are revoked. Re-enable the plugin and retry.';
+export const WITHHELD_OUTPUT_MESSAGE = 'The plugin tool result was withheld because it contained a connection credential.';
+export const WITHHELD_ERROR_MESSAGE = 'The plugin tool failed and its error was withheld because it contained a connection credential.';
+/** Newest tokens kept; access tokens are short-lived, so older ones matter less than bounded memory. */
+export const ISSUED_TOKEN_MEMORY_LIMIT = 64;
+/**
+ * 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 function createIssuedTokenMemories(_required = {}, _optional = {}) {
+    const byPlugin = new Map();
+    return Object.freeze({
+        forPlugin({ pluginId }) {
+            let issued = byPlugin.get(pluginId);
+            if (issued === undefined)
+                byPlugin.set(pluginId, issued = new Set());
+            return issued;
+        },
+    });
+}
+/** Records `token` as newest, dropping the oldest beyond the limit. @complexity O(1) amortized. */
+function remember(issued, token) {
+    issued.delete(token);
+    issued.add(token);
+    if (issued.size > ISSUED_TOKEN_MEMORY_LIMIT)
+        issued.delete(issued.values().next().value);
+}
+/** True when `text` holds any issued token, raw or JSON-escaped. @complexity O(n * t). */
+function textMentions(text, issued) {
+    for (const token of issued)
+        if (text.includes(token) || text.includes(JSON.stringify(token).slice(1, -1)))
+            return true;
+    return false;
+}
+/** True when `value` (serialized) mentions any issued token. Unserializable values fail closed.
+ * @complexity O(n * t) for serialized size n and t issued tokens (t ≤ ISSUED_TOKEN_MEMORY_LIMIT). */
+function mentionsToken(value, issued) {
+    if (issued.size === 0)
+        return false;
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        return true;
+    }
+    return text !== undefined && textMentions(text, issued);
+}
+/**
+ * Objects an error scan visits before it gives up and withholds the error. Generous for any real
+ * error (a few causes, an `AggregateError` of a few dozen), small enough to bound a hostile graph.
+ */
+const ERROR_SCAN_NODE_LIMIT = 256;
+/**
+ * Everything one object can hold a token in: every own property, non-enumerable and symbol-keyed
+ * ones too (`message`, `stack`, `cause`, `AggregateError.errors`), plus Map and Set contents.
+ * Null when reading it threw (a hostile getter or proxy): the caller fails closed.
+ * @complexity O(own properties + entries).
+ */
+function childrenOf(value) {
+    try {
+        const own = Reflect.ownKeys(value).map(key => value[key]);
+        if (value instanceof Map)
+            return [...own, ...value.keys(), ...value.values()];
+        return value instanceof Set ? [...own, ...value.values()] : own;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when any string reachable from `error` mentions an issued token. JSON would miss the
+ * non-enumerable `cause` and `AggregateError.errors`, and errors held in plain objects, so this walks
+ * the object graph instead, to any depth. It fails closed: an unreadable object, or a graph past
+ * `ERROR_SCAN_NODE_LIMIT` objects, counts as mentioning a token.
+ * @complexity O(v * t) for v visited values (objects bounded by the node limit) and t issued tokens.
+ */
+function errorMentionsToken(error, issued) {
+    if (issued.size === 0)
+        return false;
+    const seen = new Set();
+    const pending = [error];
+    while (pending.length > 0) {
+        const next = scanStep(pending.pop(), issued, seen);
+        if (next === true)
+            return true;
+        // A loop, not push(...next): a huge array would exceed the engine's argument limit.
+        for (const child of next)
+            pending.push(child);
+    }
+    return false;
+}
+/** One value of the scan: `true` when it mentions a token or cannot be scanned, else what it holds. */
+function scanStep(value, issued, seen) {
+    if (typeof value === 'string')
+        return textMentions(value, issued) || [];
+    if (typeof value !== 'object' || value === null || seen.has(value))
+        return [];
+    seen.add(value);
+    return (seen.size > ERROR_SCAN_NODE_LIMIT ? null : childrenOf(value)) ?? true;
+}
+/**
+ * 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 function openCredentialScan(required, _optional = {}) {
+    const { issued } = required;
+    return {
+        mentionsToken: ({ value }) => mentionsToken(value, issued),
+        sanitize({ error }) {
+            return errorMentionsToken(error, issued) ? new Error(WITHHELD_ERROR_MESSAGE) : error;
+        },
+    };
+}
+/**
+ * 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 function openCapabilityGate(required, _optional = {}) {
+    const { isLive, issued } = required;
+    return {
+        guard: (call) => async (...args) => {
+            if (!isLive())
+                throw new Error(REVOKED_MESSAGE);
+            return call(...args);
+        },
+        noteToken({ token }) {
+            if (token)
+                remember(issued, token);
+            return token;
+        },
+        ...openCredentialScan({ issued }),
+        /** The result, unless it mentions a token this plugin obtained. */
+        release({ value }) {
+            if (mentionsToken(value, issued))
+                throw new Error(WITHHELD_OUTPUT_MESSAGE);
+            return value;
+        },
+    };
+}
+/** 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 function guardSharedCapabilities(required, _optional = {}) {
+    const { gate: { guard }, host } = required;
+    const { artifacts } = host;
+    return {
+        http: Object.freeze({ fetch: guard((input, options) => host.http.fetch(input, options)) }),
+        limiter: Object.freeze({ check: guard((input) => host.limiter.check(input)) }),
+        ...(artifacts !== undefined && { artifacts: Object.freeze({ write: guard((input) => artifacts.write(input)) }) }),
+    };
+}
+/** The key shape every plugin state call shares, so a key never reaches the host as a path or a scope. */
+export function checkedStateKey(required, _optional = {}) {
+    const { key } = required;
+    if (typeof key !== 'string' || !STATE_KEY_PATTERN.test(key))
+        throw new Error(`A settings key must be a short name of at most ${PLUGIN_STATE_MAX_KEY_LENGTH} characters.`);
+    return key;
+}
+/**
+ * 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 function guardStateReader(required, _optional = {}) {
+    const { gate, state } = required;
+    return Object.freeze({ get: gate.guard(({ key }) => state.get({ key: checkedStateKey({ key }) })) });
+}
+/**
+ * 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 function openCapabilitySession(required, _optional = {}) {
+    const { capabilities: host, isLive, issued } = required;
+    const gate = openCapabilityGate({ isLive, issued });
+    const capabilities = Object.freeze({
+        connections: Object.freeze({ getAccessToken: gate.guard(async (input) => gate.noteToken({ token: await host.connections.getAccessToken({ connectionRef: input.connectionRef }) })) }),
+        ...guardSharedCapabilities({ gate, host }),
+        state: guardStateReader({ gate, state: host.state }),
+    });
+    return { capabilities, release: gate.release, sanitize: gate.sanitize };
+}
+//# sourceMappingURL=capabilities.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * @file The executable tool contribution, defined on the lifecycle's one executable loader
+ * (`defineExecutablePluginContribution`) so tool modules pass the same gates as every other seam
+ * that runs plugin code: active plugin, bundled digest, contained `.mjs` path. No second loader.
+ * The filename is the host's: Jini never names a product's contribution file.
+ */
+import { type LoadedPluginContribution, type PluginContributionDefinition } from '../contribution-loader.js';
+import type { AgentPluginToolCapabilities } from './capabilities.js';
+import { type AgentPluginToolDescriptor } from './manifest.js';
+/** What a tool module's default export must be. `input` has already passed the declared schema. */
+export interface AgentPluginToolModule {
+    readonly invoke: (required: {
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly capabilities: AgentPluginToolCapabilities;
+        readonly signal?: AbortSignal;
+    }, optional?: Record<string, never>) => unknown;
+    /** Human-readable resources the call would change, shown before confirmation. Required unless `read`. */
+    readonly describeAffectedResources?: (required: {
+        readonly input: Readonly<Record<string, unknown>>;
+    }, optional?: Record<string, never>) => unknown;
+}
+export type LoadedAgentPluginTool = LoadedPluginContribution<AgentPluginToolDescriptor, AgentPluginToolModule>;
+/**
+ * Defines the tool contribution for a host-chosen filename (e.g. `<product>-agent-tools.json`).
+ * @param required.filename - The file a plugin ships at its package root to contribute tools.
+ * @returns A definition for `loadPluginContributions`; executable, so activation is always required.
+ * @complexity O(1); each load is one contained import per declared tool (Node caches per file URL).
+ */
+export declare function defineAgentPluginToolContribution(required: {
+    readonly filename: string;
+}, _optional?: Record<string, never>): PluginContributionDefinition<AgentPluginToolDescriptor, LoadedAgentPluginTool>;
+//# sourceMappingURL=definition.d.ts.map