@jini-ai/agent-plugins 0.4.6 → 0.4.8

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

package/dist/lifecycle/tools/projection.js

@@ -0,0 +1,283 @@
+/**
+ * @file Projects loaded Agent Plugin tools into the EXISTING plugin tool contribution contract
+ * (`@jini-ai/plugins/host`: `PluginContributionRegistry` → `attachPluginContributionTools`), so these
+ * tools reach the assistant through the same namespaced ids, enablement recheck, auth port, confirmation
+ * and revocable registry scope as every other plugin tool. Nothing here registers tools directly.
+ *
+ * Added at this seam, because only it knows a tool came from an Agent Plugin module:
+ * - schema validation of the input before the module runs (the registry passes schemas through);
+ * - per-call host capabilities, revoked when the plugin's tools are withdrawn;
+ * - the affected-resources disclosure the host shows before confirming a write/destructive call;
+ * - refusal of ambiguous ids (two plugins whose namespaced ids collide) and of write/destructive
+ *   tools that cannot disclose what they change.
+ */
+import { Validator } from '@cfworker/json-schema';
+import { requireInputRecord, ToolInputError } from '@jini-ai/core';
+import { openCapabilitySession, openCredentialScan, REVOKED_MESSAGE } from './capabilities.js';
+const MAX_RESOURCES = 50;
+const MAX_RESOURCE_LENGTH = 300;
+/** Agent Plugin tools have no site-plugin SDK; the contract's slot is filled with one that refuses. */
+const refuse = () => { throw new Error('Agent Plugin tools have no site-plugin SDK.'); };
+const INERT_SDK = Object.freeze({
+    content: Object.freeze({ read: refuse, extend: refuse }), addFilter: refuse, addAction: refuse, addContribution: refuse,
+    routes: Object.freeze({ add: refuse }), tools: Object.freeze({ add: refuse }), widgets: Object.freeze({ add: refuse }),
+});
+/** Compiles the declared schema, or says why it cannot be used. @complexity O(s) schema size. */
+function compileSchema(schema) {
+    try {
+        const validator = new Validator(schema, '2020-12', true);
+        // cfworker resolves references lazily; one probe surfaces a root-level unresolved $ref at load.
+        validator.validate({});
+        return validator;
+    }
+    catch (error) {
+        return `its input schema is invalid (${error instanceof Error ? error.message : String(error)})`;
+    }
+}
+/** Why a loaded tool cannot be projected, or its admitted form. @complexity O(s) schema size. */
+function admitOne(loaded, toolIdFor) {
+    const { descriptor, module } = loaded;
+    if (descriptor.effect !== 'read' && typeof module.describeAffectedResources !== 'function') {
+        return `a ${descriptor.effect} tool must export describeAffectedResources()`;
+    }
+    const validator = compileSchema(descriptor.inputSchema);
+    if (typeof validator === 'string')
+        return validator;
+    return { toolId: toolIdFor({ pluginId: loaded.pluginId, name: descriptor.name }), loaded, validator };
+}
+/** Admits each tool, then drops every id more than one plugin claims ("refusing to guess").
+ * @complexity O(t) tools plus schema compilation. */
+function admitAll(loaded, refusals, toolIdFor) {
+    const admitted = [];
+    for (const entry of loaded) {
+        const result = admitOne(entry, toolIdFor);
+        if (typeof result === 'string')
+            refusals.push(`agent tool '${entry.descriptor.name}' from '${entry.pluginId}' was not loaded: ${result}`);
+        else
+            admitted.push(result);
+    }
+    const claimants = new Map();
+    for (const tool of admitted)
+        claimants.set(tool.toolId, (claimants.get(tool.toolId) ?? new Set()).add(tool.loaded.pluginId));
+    for (const [toolId, owners] of claimants) {
+        if (owners.size > 1)
+            refusals.push(`agent tool '${toolId}' was not loaded: more than one plugin declares it (${[...owners].map(id => `'${id}'`).sort().join(', ')})`);
+    }
+    return admitted.filter(tool => claimants.get(tool.toolId).size === 1);
+}
+/** Validates input against the declared schema; the message names locations, never values.
+ * @complexity O(n) input size. */
+function validatedInput(tool, input) {
+    const record = requireInputRecord({ input });
+    let result;
+    // A schema fault reached only by some inputs (nested $ref, bad pattern) fails closed, not as bad input.
+    try {
+        result = tool.validator.validate(record);
+    }
+    catch (error) {
+        throw new Error(`Plugin tool '${tool.toolId}' has an unusable input schema; report it to the plugin author.`, { cause: error });
+    }
+    if (result.valid)
+        return record;
+    // cfworker roots every instanceLocation at '#' (validate()'s default, children append '/key'), so it
+    // is never empty; pinned by "input failing at the schema root is located at #" in projection.unit.test.ts.
+    const where = [...new Set(result.errors.map(unit => `${unit.instanceLocation} (${unit.keyword})`))].slice(0, 3).join(', ');
+    throw new ToolInputError({ message: `Input for '${tool.toolId}' does not match its schema at ${where}. Fix the input and retry.` });
+}
+/** True when both generations hold the same modules and declarations: no revocation needed. @complexity O(t). */
+function sameTools(previous, next, additional) {
+    if (!previous || previous.tools.length !== next.length || previous.additional.length !== additional.length
+        || !previous.additional.every((tool, index) => tool === additional[index]))
+        return false;
+    return previous.tools.every((tool, index) => tool.loaded.module === next[index].loaded.module
+        && JSON.stringify(tool.loaded.descriptor) === JSON.stringify(next[index].loaded.descriptor));
+}
+/**
+ * Checks a disclosure hook's answer. Its text reaches the confirmation prompt and the transcript,
+ * and module scope may still hold a token from an earlier call, so a list that mentions one is
+ * refused like a malformed one. @complexity O(r) resources plus the token scan.
+ */
+function checkedResources(toolId, value, scan) {
+    const valid = Array.isArray(value) && value.length <= MAX_RESOURCES
+        && value.every(item => typeof item === 'string' && item.length > 0 && item.length <= MAX_RESOURCE_LENGTH)
+        && !scan.mentionsToken({ value });
+    if (!valid)
+        throw new Error(`Plugin tool '${toolId}' returned an invalid affected-resources list; the call cannot be confirmed. Report it to the plugin author.`);
+    return Object.freeze([...value]);
+}
+/** Groups admitted tools and additional contributions in declaration order.
+ * Mutates only the local groups and appends admission failures to refusals. @complexity O(t) plus schema compilation. */
+function groupProjectionTools({ loaded, additionalTools, refusals, toolIdFor }, _options = {}) {
+    const grouped = new Map();
+    for (const tool of admitAll(loaded, refusals, toolIdFor)) {
+        const group = grouped.get(tool.loaded.pluginId);
+        if (group)
+            group.push(tool);
+        else
+            grouped.set(tool.loaded.pluginId, [tool]);
+    }
+    const additional = new Map();
+    for (const entry of additionalTools ?? []) {
+        const group = additional.get(entry.pluginId);
+        if (group)
+            group.push(entry);
+        else
+            additional.set(entry.pluginId, [entry]);
+        if (!grouped.has(entry.pluginId))
+            grouped.set(entry.pluginId, []);
+    }
+    return { grouped, additional };
+}
+/** Counts all declarations, including refused tools, and appends ambiguous-id refusals.
+ * @complexity O(t * (r + 1)) time and O(t) space for t declarations and r prior refusals. */
+function countProjectionClaims({ loaded, additionalTools, refusals, idFor }, _options = {}) {
+    // All claimants lose an ambiguous id, including collisions between executable and surface tools.
+    const counts = new Map();
+    const claimedIds = [...loaded.map(tool => idFor({ pluginId: tool.pluginId, name: tool.descriptor.name })),
+        ...(additionalTools ?? []).map(entry => idFor({ pluginId: entry.pluginId, name: entry.tool.name }))];
+    for (const id of claimedIds)
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    for (const [id, count] of counts) {
+        if (count <= 1)
+            continue;
+        // MOVE: Admission already reports executable collisions with their owners; preserve that diagnostic once.
+        if (refusals.some(reason => reason.startsWith(`agent tool '${id}' was not loaded:`)))
+            continue;
+        refusals.push(`agent tool '${id}' was not loaded: more than one contribution declares it`);
+    }
+    return counts;
+}
+/**
+ * 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 function createAgentPluginToolProjection(required, _optional = {}) {
+    const { registry } = required;
+    let projected = new Map();
+    let additionalById = new Map();
+    let byToolId = new Map();
+    /** One contract tool whose handler validates, scopes capabilities and gates the result. */
+    function contractTool(tool, generationOf) {
+        const { isLive, issued } = generationOf;
+        const { descriptor, module } = tool.loaded;
+        const contribution = {
+            name: descriptor.name, description: descriptor.description, inputSchema: descriptor.inputSchema, effect: descriptor.effect,
+            async handler({ pluginId, auth, input, signal }) {
+                // Defense in depth: the registry rechecks enablement, but a retained handler must not run either.
+                if (!isLive())
+                    throw new Error(REVOKED_MESSAGE);
+                const checked = validatedInput(tool, input);
+                const host = required.capabilities({ pluginId, workspaceId: auth.workspaceId,
+                    ...(auth.principalId === undefined ? {} : { principalId: auth.principalId }), ...(signal === undefined ? {} : { signal }) });
+                const session = openCapabilitySession({ capabilities: host, isLive, issued });
+                try {
+                    const value = await module.invoke({ input: checked, capabilities: session.capabilities, ...(signal === undefined ? {} : { signal }) });
+                    return session.release({ value });
+                }
+                catch (error) {
+                    throw session.sanitize({ error });
+                }
+            },
+        };
+        return Object.freeze(contribution);
+    }
+    /** A fresh generation for one plugin; its tools are live only while the registry holds it. */
+    function generation(pluginId, tools, additional) {
+        let snapshot;
+        const isLive = () => snapshot !== undefined && registry.list({}).includes(snapshot);
+        const issued = required.issuedTokens.forPlugin({ pluginId });
+        snapshot = Object.freeze({ pluginId, sdk: INERT_SDK, routes: Object.freeze([]), widgets: Object.freeze([]),
+            tools: Object.freeze([...tools.map(tool => contractTool(tool, { isLive, issued })), ...additional.map(({ tool }) => Object.freeze({
+                    ...tool,
+                    handler(input) {
+                        if (!isLive())
+                            throw new Error(REVOKED_MESSAGE);
+                        return tool.handler(input);
+                    },
+                }))]) });
+        return { snapshot, tools, additional };
+    }
+    /** Replaces one plugin's generation unless it is unchanged; a refused replacement detaches it. */
+    function place(pluginId, tools, additional, refusals) {
+        const previous = projected.get(pluginId);
+        if (sameTools(previous, tools, additional))
+            return previous;
+        const next = generation(pluginId, tools, additional);
+        try {
+            registry.replace({ contributions: next.snapshot });
+            return next;
+        }
+        catch (error) {
+            registry.detach({ pluginId });
+            refusals.push(`agent tools from '${pluginId}' were not loaded: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    return {
+        /** Projects one load result. @returns The loader's refusals plus this seam's own, in order. */
+        sync(input, _options = {}) {
+            const refusals = [...input.refusals];
+            const { grouped, additional } = groupProjectionTools({
+                loaded: input.loaded, additionalTools: input.additionalTools, refusals, toolIdFor: required.toolIdFor,
+            });
+            const idFor = required.toolIdFor;
+            const counts = countProjectionClaims({ loaded: input.loaded, additionalTools: input.additionalTools, refusals, idFor });
+            const nextProjected = new Map();
+            for (const [pluginId, tools] of grouped) {
+                const unique = tools.filter(tool => counts.get(tool.toolId) === 1);
+                const extras = (additional.get(pluginId) ?? []).filter(entry => counts.get(idFor({ pluginId, name: entry.tool.name })) === 1);
+                const placed = place(pluginId, unique, extras, refusals);
+                if (placed)
+                    nextProjected.set(pluginId, placed);
+            }
+            for (const pluginId of projected.keys())
+                if (!grouped.has(pluginId))
+                    registry.detach({ pluginId });
+            projected = nextProjected;
+            additionalById = new Map([...nextProjected.values()].flatMap(plugin => plugin.additional.map(entry => [idFor({ pluginId: entry.pluginId, name: entry.tool.name }), { entry, snapshot: plugin.snapshot }])));
+            byToolId = new Map([...nextProjected.values()].flatMap(plugin => plugin.tools.map(tool => [tool.toolId, { tool, snapshot: plugin.snapshot }])));
+            return { refusals };
+        },
+        /** 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. */
+        async describeAffectedResources(input, _options = {}) {
+            const extra = additionalById.get(input.toolId);
+            if (extra && registry.list({}).includes(extra.snapshot)) {
+                const scan = openCredentialScan({ issued: required.issuedTokens.forPlugin({ pluginId: extra.entry.pluginId }) });
+                try {
+                    const resources = await extra.entry.describeAffectedResources({ input: input.input });
+                    return { effect: extra.entry.tool.effect ?? 'write', resources: checkedResources(input.toolId, resources, scan) };
+                }
+                catch (error) {
+                    throw scan.sanitize({ error });
+                }
+            }
+            const entry = byToolId.get(input.toolId);
+            if (!entry || !registry.list({}).includes(entry.snapshot))
+                return null;
+            const { tool } = entry;
+            const checked = validatedInput(tool, input.input);
+            const describe = tool.loaded.module.describeAffectedResources;
+            if (!describe)
+                return { effect: tool.loaded.descriptor.effect, resources: [] };
+            // The same per-plugin token memory the plugin's calls feed: its answers and errors are scanned alike.
+            const scan = openCredentialScan({ issued: required.issuedTokens.forPlugin({ pluginId: tool.loaded.pluginId }) });
+            let answer;
+            try {
+                answer = await describe({ input: checked });
+            }
+            catch (error) {
+                throw scan.sanitize({ error });
+            }
+            return { effect: tool.loaded.descriptor.effect, resources: checkedResources(tool.toolId, answer, scan) };
+        },
+    };
+}
+//# sourceMappingURL=projection.js.map

package/dist/lifecycle/types.d.ts

@@ -8,6 +8,8 @@ export interface InstalledAgentPluginSkill {
 export interface InstalledAgentPlugin {
     readonly id?: string | undefined;
     readonly provides?: readonly string[] | undefined;
+    readonly requires?: readonly string[] | undefined;
+    readonly hostRange?: string | undefined;
     readonly pluginId: string;
     readonly version?: (string) | undefined;
     /** the host extension namespace in `plugin.json`: `displayName` — the human-facing title when the id alone reads

package/dist/lifecycle/uninstall.d.ts

@@ -64,7 +64,9 @@ export interface StagedTree {
 export declare function createUninstallModule(ports: AgentPluginLifecyclePorts): {
     previewAgentPluginUninstall: (required: UninstallAgentPluginRequired) => Promise<AgentPluginUninstallPreview>;
     uninstallAgentPlugin: (required: UninstallAgentPluginRequired, optional?: UninstallAgentPluginOptional) => Promise<UninstallAgentPluginResult>;
-    stageForRemoval: (packagesDir: string, packageRoot: string) => Promise<StagedTree>;
+    stageForRemoval: (packagesDir: string, packageRoot: string, optional?: {
+        quarantined?: string;
+    }) => Promise<StagedTree>;
     restoreStagedTrees: (staged: readonly StagedTree[], cause: unknown) => Promise<unknown>;
     removeFrozenPackageTree: (root: string) => Promise<void>;
 };