@jini-ai/agent-plugins 0.4.7 → 0.4.8

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

package/dist/lifecycle/tools/definition.js

@@ -0,0 +1,33 @@
+/**
+ * @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 { defineExecutablePluginContribution } from '../contribution-loader.js';
+import { parseAgentPluginToolsFile } from './manifest.js';
+/** The module's export as a tool module, or why not. Shape only; effect rules apply at projection. @complexity O(1). */
+function validateToolModule({ exported }) {
+    if (typeof exported !== 'object' || exported === null)
+        return "its module's default export is not an object";
+    const candidate = exported;
+    if (typeof candidate.invoke !== 'function')
+        return "its module's default export has no invoke()";
+    if (candidate.describeAffectedResources !== undefined && typeof candidate.describeAffectedResources !== 'function')
+        return 'describeAffectedResources must be a function';
+    return exported;
+}
+/**
+ * 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 function defineAgentPluginToolContribution(required, _optional = {}) {
+    return defineExecutablePluginContribution({
+        filename: required.filename, contribution: 'agent tools',
+        parse: parseAgentPluginToolsFile, modulePath: ({ descriptor }) => descriptor.module, validate: validateToolModule,
+        refusal: ({ plugin, descriptor, reason }) => `agent tool '${descriptor.name}' from '${plugin.pluginId}' was not loaded: ${reason}`,
+    });
+}
+//# sourceMappingURL=definition.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * @file Public surface of `@jini-ai/agent-plugins/lifecycle/tools`: executable Agent Plugin tools.
+ * A separate subpath because it needs the optional `@cfworker/json-schema` peer; consumers of
+ * `./lifecycle` alone do not. The plugin tool contract arrives as host ports, never an import. See this folder's README.md.
+ */
+export { parseAgentPluginToolsFile, type AgentPluginToolDescriptor, type AgentPluginToolEffect } from './manifest.js';
+export { defineAgentPluginToolContribution, type AgentPluginToolModule, type LoadedAgentPluginTool } from './definition.js';
+export { WITHHELD_OUTPUT_MESSAGE, createIssuedTokenMemories, type IssuedTokenMemories, type AgentPluginToolCapabilities, type AgentPluginToolCapabilitiesPort, type AgentPluginToolCapabilityScope, type AgentPluginHttpOptions, type AgentPluginLimitResult, type AgentPluginStateReader, type AgentPluginStateValue, } from './capabilities.js';
+export { createAgentPluginToolProjection, type AgentPluginToolDisclosure, type AgentPluginToolProjectionPorts, type AgentPluginAdditionalTool, type AgentPluginToolSnapshot, type AgentPluginContractTool, type AgentPluginToolInvocation, } from './projection.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/tools/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file Public surface of `@jini-ai/agent-plugins/lifecycle/tools`: executable Agent Plugin tools.
+ * A separate subpath because it needs the optional `@cfworker/json-schema` peer; consumers of
+ * `./lifecycle` alone do not. The plugin tool contract arrives as host ports, never an import. See this folder's README.md.
+ */
+export { parseAgentPluginToolsFile } from './manifest.js';
+export { defineAgentPluginToolContribution } from './definition.js';
+export { WITHHELD_OUTPUT_MESSAGE, createIssuedTokenMemories, } from './capabilities.js';
+export { createAgentPluginToolProjection, } from './projection.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * @file Parses an Agent Plugin's tool contribution file: the data half of an executable tool.
+ * Name, description, effect class and input schema are declared as reviewable data so the host can
+ * list, namespace and validate a tool without running plugin code; only `module` points at code.
+ * Pure: no I/O. A file that fails any rule is refused whole, so a plugin never ships half its tools.
+ */
+import type { PluginContributionParseResult } from '../contribution-loader.js';
+/**
+ * Declared change class; `write` and `destructive` tools must also disclose affected resources.
+ * The mirror of `PluginToolEffect` in `@jini-ai/plugins/host` (agent-plugins may not import it); the
+ * projection's contract tool reuses this type, so these two are the only declarations.
+ */
+export type AgentPluginToolEffect = 'read' | 'write' | 'destructive';
+/** One declared tool. `name` is local; the host namespaces it as `p_<plugin>__<name>`. */
+export interface AgentPluginToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly effect: AgentPluginToolEffect;
+    /** Plain-JS module inside the plugin root (`.mjs`); containment is checked on disk at import. */
+    readonly module: string;
+    /** JSON Schema (2020-12) for the tool input; must describe an object. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/**
+ * Parses the raw contribution file. A local name declared twice is refused (duplicate id).
+ * @param required.raw - The file text as read from a trusted package.
+ * @returns Descriptors in declaration order, or the reason the whole file is refused.
+ * @complexity O(t^2 + s) for t declarations (t <= 128) and s total schema size.
+ */
+export declare function parseAgentPluginToolsFile(required: {
+    readonly raw: string;
+}, _optional?: Record<string, never>): PluginContributionParseResult<AgentPluginToolDescriptor>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/lifecycle/tools/manifest.js

@@ -0,0 +1,89 @@
+// Bounds mirror the existing tier-3 tool capture (`@jini-ai/plugins/host` contributions.ts) so one
+// plugin tool contract has one set of limits, whichever loader admitted it.
+const NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+const MAX_TOOLS = 128;
+const MAX_DESCRIPTION = 8000;
+const MAX_MODULE_PATH = 256;
+const MAX_SCHEMA_BYTES = 65536;
+const EFFECTS = new Set(['read', 'write', 'destructive']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Why the input schema is unusable, or undefined. Detaches nothing; the caller copies. @complexity O(s) schema size. */
+function schemaProblem(schema) {
+    if (!isRecord(schema) || schema.type !== 'object')
+        return 'inputSchema must be a JSON Schema describing an object';
+    if (new TextEncoder().encode(JSON.stringify(schema)).byteLength > MAX_SCHEMA_BYTES)
+        return 'inputSchema is larger than 64 KiB';
+    return undefined;
+}
+/** Why a description is unusable, or undefined. @complexity O(1). */
+function descriptionProblem(name, description) {
+    if (typeof description === 'string' && description.trim() && description.length <= MAX_DESCRIPTION)
+        return undefined;
+    return `tool '${name}' needs a description of at most ${MAX_DESCRIPTION} characters`;
+}
+/** Why a module path is unusable here, or undefined; containment is checked on disk at import. @complexity O(1). */
+function moduleProblem(name, module) {
+    if (typeof module === 'string' && module.endsWith('.mjs') && module.length <= MAX_MODULE_PATH)
+        return undefined;
+    return `tool '${name}' module must be a .mjs path inside the plugin`;
+}
+/** Why one declaration's scalar fields are invalid, or undefined. @complexity O(1). */
+function fieldProblem(entry) {
+    const { name } = entry;
+    if (typeof name !== 'string' || !NAME_PATTERN.test(name))
+        return 'a tool name must be lower snake case, at most 64 characters';
+    const effectProblem = EFFECTS.has(entry.effect) ? undefined : `tool '${name}' effect must be read, write or destructive`;
+    return descriptionProblem(name, entry.description) ?? effectProblem ?? moduleProblem(name, entry.module);
+}
+/** One declaration, or why it is refused. Unknown keys are ignored. @complexity O(s) schema size. */
+function parseEntry(entry) {
+    if (!isRecord(entry))
+        return 'every tool declaration must be an object';
+    const problem = fieldProblem(entry) ?? schemaProblem(entry.inputSchema);
+    if (problem)
+        return problem;
+    return Object.freeze({
+        name: entry.name, description: entry.description, effect: entry.effect,
+        module: entry.module, inputSchema: JSON.parse(JSON.stringify(entry.inputSchema)),
+    });
+}
+/** The declaration list from the raw file, or why the file is refused. @complexity O(n) file size. */
+function declarations(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return 'not valid JSON';
+    }
+    if (!isRecord(value) || value.schemaVersion !== 1)
+        return 'schemaVersion must be 1';
+    const { tools } = value;
+    if (!Array.isArray(tools) || tools.length === 0 || tools.length > MAX_TOOLS)
+        return `tools must list 1 to ${MAX_TOOLS} declarations`;
+    return tools;
+}
+/**
+ * Parses the raw contribution file. A local name declared twice is refused (duplicate id).
+ * @param required.raw - The file text as read from a trusted package.
+ * @returns Descriptors in declaration order, or the reason the whole file is refused.
+ * @complexity O(t^2 + s) for t declarations (t <= 128) and s total schema size.
+ */
+export function parseAgentPluginToolsFile(required, _optional = {}) {
+    const tools = declarations(required.raw);
+    if (typeof tools === 'string')
+        return { ok: false, reason: tools };
+    const descriptors = [];
+    for (const entry of tools) {
+        const parsed = parseEntry(entry);
+        if (typeof parsed === 'string')
+            return { ok: false, reason: parsed };
+        if (descriptors.some(existing => existing.name === parsed.name))
+            return { ok: false, reason: `tool '${parsed.name}' is declared more than once` };
+        descriptors.push(parsed);
+    }
+    return { ok: true, descriptors };
+}
+//# sourceMappingURL=manifest.js.map

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

@@ -0,0 +1,90 @@
+import { type AgentPluginToolCapabilitiesPort, type IssuedTokenMemories } from './capabilities.js';
+import type { LoadedAgentPluginTool } from './definition.js';
+import type { AgentPluginToolEffect } from './manifest.js';
+/** What one call receives from the plugin tool contract. Structural: the host owns that contract. */
+export interface AgentPluginToolInvocation {
+    readonly pluginId: string;
+    readonly auth: {
+        readonly workspaceId: string;
+        readonly principalId?: string;
+    };
+    readonly input: unknown;
+    readonly signal?: AbortSignal;
+}
+/** One tool in the contract's shape (`PluginToolContribution` in `@jini-ai/plugins/host`). */
+export interface AgentPluginContractTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /** Always set here; optional so the host's own snapshot type (where it is optional) fits the port. */
+    readonly effect?: AgentPluginToolEffect;
+    handler(required: AgentPluginToolInvocation, optional?: Record<string, never>): unknown;
+}
+/** A host adapter over another admitted contribution, using its existing execution owner. */
+export interface AgentPluginAdditionalTool {
+    readonly pluginId: string;
+    readonly tool: AgentPluginContractTool;
+    readonly describeAffectedResources: (required: {
+        readonly input: unknown;
+    }) => readonly string[] | Promise<readonly string[]>;
+}
+/** One plugin's generation in the contract's snapshot shape; routes and widgets stay empty. */
+export interface AgentPluginToolSnapshot {
+    readonly pluginId: string;
+    readonly sdk: object;
+    readonly routes: readonly unknown[];
+    readonly widgets: readonly unknown[];
+    readonly tools: readonly AgentPluginContractTool[];
+}
+/** Host ports: its contribution registry and its tool-id namespacing rule (`pluginToolIdFor`). */
+export interface AgentPluginToolProjectionPorts {
+    readonly registry: {
+        replace(required: {
+            readonly contributions: AgentPluginToolSnapshot;
+        }, optional?: Record<string, never>): void;
+        detach(required: {
+            readonly pluginId: string;
+        }, optional?: Record<string, never>): void;
+        list(required: Record<string, never>, optional?: Record<string, never>): readonly unknown[];
+    };
+    readonly toolIdFor: (required: {
+        readonly pluginId: string;
+        readonly name: string;
+    }, optional?: Record<string, never>) => string;
+    readonly capabilities: AgentPluginToolCapabilitiesPort;
+    /** The host's ONE token memory source, also passed to its admin-surface host (see `createIssuedTokenMemories`). */
+    readonly issuedTokens: IssuedTokenMemories;
+}
+/** What the host shows before confirming a call. */
+export interface AgentPluginToolDisclosure {
+    readonly effect: AgentPluginToolEffect;
+    readonly resources: readonly string[];
+}
+/**
+ * Creates the projection for one dedicated contribution registry (keyed by plugin id, so it must not
+ * be shared with site plugins whose ids could match). Call `sync` after every load: on boot and on
+ * every activation change. A plugin missing from a load is detached: its tools disappear and its
+ * calls' capabilities are revoked.
+ * @param required.registry - Registry the host attached with `attachPluginContributionTools`.
+ * @param required.toolIdFor - The contract's namespacing rule (`pluginToolIdFor`), so ids match the registry's.
+ * @param required.capabilities - Host port building one call's capabilities.
+ * @param required.issuedTokens - Per-plugin token memory shared with the plugin's admin-surface handlers.
+ * @complexity sync is O(t) tools plus schema compilation; disclosure lookup is O(1).
+ */
+export declare function createAgentPluginToolProjection(required: AgentPluginToolProjectionPorts, _optional?: Record<string, never>): {
+    /** Projects one load result. @returns The loader's refusals plus this seam's own, in order. */
+    sync(input: {
+        readonly loaded: readonly LoadedAgentPluginTool[];
+        readonly refusals: readonly string[];
+        readonly additionalTools?: readonly AgentPluginAdditionalTool[];
+    }, _options?: Record<string, never>): {
+        readonly refusals: readonly string[];
+    };
+    /** What a call would change, for the confirmation prompt; null for an unknown or withdrawn tool.
+     * @throws ToolInputError for input that fails the schema; Error for an invalid hook answer. */
+    describeAffectedResources(input: {
+        readonly toolId: string;
+        readonly input: unknown;
+    }, _options?: Record<string, never>): Promise<AgentPluginToolDisclosure | null>;
+};
+//# sourceMappingURL=projection.d.ts.map