@jini-ai/agent-plugins 0.4.7 → 0.6.10

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

@@ -0,0 +1 @@
+{"version":3,"file":"skill-file-reader.js","sourceRoot":"","sources":["../../src/lifecycle/skill-file-reader.ts"],"names":[],"mappings":"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"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/tools/capabilities.ts"],"names":[],"mappings":"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"}

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/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/lifecycle/tools/capabilities.ts"],"names":[],"mappings":"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"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/tools/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAsC,KAAK,wBAAwB,EAAE,KAAK,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACjJ,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAA6B,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1F,mGAAmG;AACnG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,CACf,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,EAClJ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAC7B,OAAO,CAAC;IACb,yGAAyG;IACzG,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,OAAO,CAAC;CACrJ;AAED,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,yBAAyB,EAAE,qBAAqB,CAAC,CAAC;AAW/G;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACvC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GACpC,4BAA4B,CAAC,yBAAyB,EAAE,qBAAqB,CAAC,CAMhF"}

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/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../src/lifecycle/tools/definition.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kCAAkC,EAAoE,MAAM,2BAA2B,CAAC;AAEjJ,OAAO,EAAE,yBAAyB,EAAkC,MAAM,eAAe,CAAC;AAc1F,wHAAwH;AACxH,SAAS,kBAAkB,CAAC,EAAE,QAAQ,EAAkC;IACtE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,8CAA8C,CAAC;IAC7G,MAAM,SAAS,GAAG,QAAiE,CAAC;IACpF,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,6CAA6C,CAAC;IACjG,IAAI,SAAS,CAAC,yBAAyB,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,yBAAyB,KAAK,UAAU;QAAE,OAAO,8CAA8C,CAAC;IAC1K,OAAO,QAAiC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAC/C,QAAuC,EACvC,YAAmC,EAAE;IAErC,OAAO,kCAAkC,CAAmD;QAC1F,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa;QACxD,KAAK,EAAE,yBAAyB,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,kBAAkB;QACjH,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,eAAe,UAAU,CAAC,IAAI,WAAW,MAAM,CAAC,QAAQ,qBAAqB,MAAM,EAAE;KACnI,CAAC,CAAC;AACL,CAAC"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAAE,KAAK,yBAAyB,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtH,OAAO,EAAE,iCAAiC,EAAE,KAAK,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC5H,OAAO,EACL,uBAAuB,EAAE,yBAAyB,EAAE,KAAK,mBAAmB,EAC5E,KAAK,2BAA2B,EAAE,KAAK,+BAA+B,EAAE,KAAK,8BAA8B,EAC3G,KAAK,sBAAsB,EAAE,KAAK,sBAAsB,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,GAClH,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,+BAA+B,EAAE,KAAK,yBAAyB,EAAE,KAAK,8BAA8B,EACpG,KAAK,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,KAAK,uBAAuB,EAAE,KAAK,yBAAyB,GAC3H,MAAM,iBAAiB,CAAC"}

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/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lifecycle/tools/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAA8D,MAAM,eAAe,CAAC;AACtH,OAAO,EAAE,iCAAiC,EAA0D,MAAM,iBAAiB,CAAC;AAC5H,OAAO,EACL,uBAAuB,EAAE,yBAAyB,GAGnD,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,+BAA+B,GAEhC,MAAM,iBAAiB,CAAC"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lifecycle/tools/manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAC;AAE/E;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAErE,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AA+DD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAM,GAAG,6BAA6B,CAAC,yBAAyB,CAAC,CAW7K"}