@adonis-agora/agent 0.31.0 → 0.33.1

package/dist/src/mcp-client/importer.js

@@ -0,0 +1,161 @@
+import { McpToolSource } from './tool-source.js';
+/**
+ * Connects to each configured MCP server and registers what it exports into the shared
+ * {@link ToolRegistry} — the same registry `@aiTool` discovery writes to, so an imported tool goes
+ * through every gate a hand-written one does.
+ *
+ * The provider calls {@link start} inside `app.booted()`, AFTER tool discovery has registered the
+ * app's own tools, which is what lets the name-collision check below see them.
+ *
+ * The registry is keyed by name and nothing else, so a name is OWNED by whoever registered it
+ * first: the application, or one named server. A second claimant is refused rather than allowed to
+ * replace a live handler, because the substitution is invisible from everywhere else — the model
+ * goes on calling `deploy`, and `deploy` now reaches somebody else's server.
+ */
+export class McpToolImporter {
+    servers;
+    registry;
+    logger;
+    sources = new Map();
+    /** Local tool name → what is registered under it, so ownership survives a {@link refresh}. */
+    owners = new Map();
+    constructor(servers, registry, logger) {
+        this.servers = servers;
+        this.registry = registry;
+        this.logger = logger;
+        // A name identifies a server in the logs, in `refresh(name)`, in the ownership map and in the
+        // default tool prefix. Two servers sharing one leaves every one of those pointing at a single
+        // arbitrary member of the pair — a collision that IS statically detectable, so it is refused
+        // here rather than surfacing as one server's tools mysteriously missing.
+        const names = servers.map((config) => config.name);
+        const duplicate = names.find((name, index) => names.indexOf(name) !== index);
+        if (duplicate !== undefined) {
+            throw new Error(`Two MCP servers are configured as "${duplicate}". Give each server a distinct name.`);
+        }
+    }
+    /** Open each configured server and import from all of them. */
+    async start() {
+        for (const config of this.servers) {
+            this.sources.set(config.name, new McpToolSource(config, this.logger));
+        }
+        return this.refresh();
+    }
+    async close() {
+        await Promise.all([...this.sources.values()].map((source) => source.close()));
+    }
+    /**
+     * Re-import from one server, or from all of them — the way back for a server that was down at
+     * boot, or whose exports have changed since.
+     *
+     * A re-import is the server's CURRENT answer to `tools/list`, so it removes as well as adds: a
+     * tool the server has dropped or renamed is unregistered, because going on offering the model a
+     * tool whose next call fails remotely is worse than not offering it at all. Only names this
+     * importer registered for THAT server are eligible — never the application's own, never another
+     * server's.
+     *
+     * A server that could not be reached prunes nothing. Its tools are unknown, not gone, and a
+     * network blip is not a reason to withdraw a working tool from the model.
+     *
+     * Returns how many tools the servers it re-imported from just claimed, which is not the
+     * registry's total: a name skipped for a collision is not counted, and a scoped refresh says
+     * nothing about what the other servers hold.
+     */
+    async refresh(serverName) {
+        const configs = this.servers.filter((config) => this.sources.has(config.name) && (serverName === undefined || config.name === serverName));
+        if (serverName !== undefined && configs.length === 0) {
+            // A scoped refresh that matched nothing re-imported nothing, and `0` reads identically to a
+            // server that answered with no tools — so the name is reported rather than left to look like
+            // an answer.
+            const open = [...this.sources.keys()];
+            this.logger?.warn(`MCP refresh("${serverName}") matched no open MCP server — nothing was re-imported. Open servers: ${open.length > 0 ? open.join(', ') : '(none)'}.`);
+            return 0;
+        }
+        // Connecting and listing is the slow part and the servers are independent, so it runs in
+        // parallel — but registration below replays in CONFIGURATION order, because which server owns a
+        // name two of them both export has to be the same answer on every boot.
+        const listed = await Promise.all(configs.map(async (config) => ({ config, tools: await this.importFrom(config) })));
+        // Pruning runs BEFORE any registration, so a name one server has just dropped is free for the
+        // next server in configuration order to claim within this same refresh.
+        for (const { config, tools } of listed) {
+            if (tools !== undefined) {
+                this.prune(config.name, new Set(tools.map((tool) => tool.spec.name)));
+            }
+        }
+        let total = 0;
+        for (const { config, tools } of listed) {
+            if (tools !== undefined) {
+                total += this.register(config, tools);
+            }
+        }
+        return total;
+    }
+    /** Every tool currently imported, and where each came from — what the servers export NOW. */
+    importedTools() {
+        return [...this.owners.values()];
+    }
+    /**
+     * A server that is unreachable costs its own tools and nothing else: the model is simply never
+     * offered them. Booting the whole application on the availability of a third-party process is the
+     * wrong trade — until a server declares `required: true`, which says the app is not useful
+     * without it and should fail loudly instead.
+     *
+     * `undefined` is a server that could not be reached, as distinct from one that exports no tools:
+     * the first has already been reported here, the second is worth reporting on registration.
+     */
+    async importFrom(config) {
+        const source = this.sources.get(config.name);
+        if (source === undefined) {
+            return undefined;
+        }
+        try {
+            return await source.import();
+        }
+        catch (error) {
+            const message = `MCP server "${config.name}" could not be imported: ${error instanceof Error ? error.message : String(error)}`;
+            if (config.required === true) {
+                throw new Error(message, { cause: error });
+            }
+            this.logger?.warn(`${message} — its tools are unavailable in this process.`);
+            return undefined;
+        }
+    }
+    /**
+     * Drop what `serverName` used to export and no longer does. Keyed on ownership rather than on the
+     * name's prefix: `namespace: false` imports under bare names, where a prefix says nothing about
+     * who registered one.
+     */
+    prune(serverName, exported) {
+        for (const [name, owner] of [...this.owners]) {
+            if (owner.serverName !== serverName || exported.has(name)) {
+                continue;
+            }
+            this.owners.delete(name);
+            this.registry.unregister(name);
+            this.logger?.warn(`MCP server "${serverName}": tool "${name}" is no longer exported — unregistered.`);
+        }
+    }
+    register(config, tools) {
+        let count = 0;
+        for (const tool of tools) {
+            const owner = this.owners.get(tool.spec.name);
+            if (owner === undefined && this.registry.has(tool.spec.name)) {
+                this.logger?.warn(`MCP server "${config.name}": tool "${tool.spec.name}" is already registered by this application — skipped. Namespace the server's tools to import it alongside.`);
+                continue;
+            }
+            if (owner !== undefined && owner.serverName !== config.name) {
+                this.logger?.warn(`MCP server "${config.name}": tool "${tool.spec.name}" is already imported from MCP server "${owner.serverName}" — skipped. Namespace one of the two servers to import both.`);
+                continue;
+            }
+            this.registry.register(tool.spec, tool.handler);
+            this.owners.set(tool.spec.name, {
+                name: tool.spec.name,
+                serverName: config.name,
+                remoteName: tool.remoteName,
+                description: tool.spec.description,
+            });
+            count += 1;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=importer.js.map

package/dist/src/mcp-client/importer.js.map

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

package/dist/src/mcp-client/index.d.ts

@@ -0,0 +1,9 @@
+export { type McpRegisteredTool, McpToolImporter } from './importer.js';
+export type { McpCustomTransportConfig, McpHttpTransportConfig, McpLogger, McpServerConfig, McpStdioTransportConfig, McpTransportConfig, } from './options.js';
+export { type McpInputSchemaOptions, mcpInputSchema } from './tool-input.js';
+export { type McpToolAnnotations, type McpToolInfo, type McpToolKindPolicy, resolveMcpToolKind, } from './tool-kind.js';
+export { localToolName, MAX_TOOL_NAME_LENGTH } from './tool-name.js';
+export { type McpImportedTool, McpToolCallError, McpToolSource } from './tool-source.js';
+export { isPreExecutionMcpError, isTransientMcpError } from './transient.js';
+export { findUnsafePattern, isUnsafeRegex } from './unsafe-regex.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/mcp-client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,SAAS,EACT,eAAe,EACf,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,qBAAqB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,KAAK,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/mcp-client/index.js

@@ -0,0 +1,8 @@
+export { McpToolImporter } from './importer.js';
+export { mcpInputSchema } from './tool-input.js';
+export { resolveMcpToolKind, } from './tool-kind.js';
+export { localToolName, MAX_TOOL_NAME_LENGTH } from './tool-name.js';
+export { McpToolCallError, McpToolSource } from './tool-source.js';
+export { isPreExecutionMcpError, isTransientMcpError } from './transient.js';
+export { findUnsafePattern, isUnsafeRegex } from './unsafe-regex.js';
+//# sourceMappingURL=index.js.map

package/dist/src/mcp-client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp-client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,eAAe,EAAE,MAAM,eAAe,CAAC;AASxE,OAAO,EAA8B,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAIL,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAwB,gBAAgB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/mcp-client/options.d.ts

@@ -0,0 +1,99 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { jsonSchemaValidator } from '@modelcontextprotocol/sdk/validation';
+import type { ToolTransientRetrySetting } from '../tool-retry.js';
+import type { McpToolKindPolicy } from './tool-kind.js';
+/** A server this process starts and talks to over its stdin/stdout. */
+export interface McpStdioTransportConfig {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    /** Replaces the inherited environment entirely (the SDK's own semantics), rather than adding to it. */
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** A server reachable over MCP's streamable-HTTP transport. */
+export interface McpHttpTransportConfig {
+    type: 'http';
+    url: string;
+    /** Sent on every request — the usual place for a static bearer token or an API key. */
+    headers?: Record<string, string>;
+}
+/**
+ * Anything else: an OAuth-carrying HTTP transport, the legacy SSE transport, or an in-process
+ * linked pair in a test. Called again for each reconnect, so it must return a FRESH transport —
+ * a `Transport` that has been closed cannot be restarted.
+ */
+export interface McpCustomTransportConfig {
+    type: 'custom';
+    create: () => Transport | Promise<Transport>;
+}
+export type McpTransportConfig = McpStdioTransportConfig | McpHttpTransportConfig | McpCustomTransportConfig;
+/** Somewhere to report a server that misbehaved. Structurally satisfied by AdonisJS's `Logger`. */
+export interface McpLogger {
+    warn(message: string): void;
+}
+/** One MCP server to import tools from, and the policy every tool it exports is imported under. */
+export interface McpServerConfig {
+    /** Identifies the server in logs, and prefixes its tool names by default. */
+    name: string;
+    transport: McpTransportConfig;
+    /**
+     * How an imported tool gets its `kind`. Defaults to `'action'` — every remote tool waits for a
+     * human. See {@link McpToolKindPolicy} for what widening it means.
+     */
+    kind?: McpToolKindPolicy;
+    /** Import only these remote tool names. Omit to import everything the server lists. */
+    include?: string[];
+    /** Import everything except these remote tool names. Applied after {@link include}. */
+    exclude?: string[];
+    /** Prefix for imported tool names: the server name (default), a string, or `false` for none. */
+    namespace?: boolean | string;
+    /** Roles allowed to invoke every tool from this server. Omit → the module's `defaultRoles`. */
+    roles?: string[];
+    /** Ability every tool from this server is checked against by an ability-aware `RolesPolicy`. */
+    ability?: string;
+    /** Cap on the MCP initialize handshake. Default 10s. */
+    connectTimeoutMs?: number;
+    /** Cap on `tools/list` and on every tool call. Default 30s. */
+    requestTimeoutMs?: number;
+    /**
+     * Retry policy for a call that failed transiently, applied around the tool's own invocation with
+     * `invokeWithTransientRetry` — the same in-place retry the agent loop uses for a rolled-back
+     * database step, so a retry never becomes a second durable checkpoint. Defaults to
+     * `{ attempts: 2, backoffMs: 150 }`; `false` surfaces the first failure.
+     *
+     * WHICH FAILURES COUNT DEPENDS ON THE {@link McpServerConfig.kind}. A `read` tool uses
+     * {@link import('./transient.js').isTransientMcpError} — dropped connections, request timeouts,
+     * retryable HTTP statuses, socket errors. An `action` tool uses the narrower
+     * {@link import('./transient.js').isPreExecutionMcpError}, which accepts only failures that PROVE
+     * the tool did not run: a timeout or a 503 may equally be a remote effect whose answer was lost,
+     * and re-issuing that would spend one human approval on two remote side effects.
+     *
+     * Supplying `classify` takes that judgement over for every kind, including `action`.
+     *
+     * Retrying here, rather than by widening the app-wide `toolTransientRetry` classifier, keeps the
+     * two from compounding: a host that would rather retry at the loop layer should pass
+     * `isTransientMcpError` into that classifier AND set this to `false`.
+     */
+    transientRetry?: ToolTransientRetrySetting;
+    /** Compiles each tool's JSON Schema. Defaults to the MCP SDK's AJV adapter. */
+    validator?: jsonSchemaValidator;
+    /**
+     * Skip a tool whose input schema carries a `pattern` that can backtrack exponentially — a string
+     * this server writes and the model fills in, which together can pin the event loop of whichever
+     * process runs the tool. Default `true`. Turn it off only for a `validator` whose regex engine
+     * does not backtrack, where the screen costs tools and buys nothing.
+     */
+    rejectUnsafePatterns?: boolean;
+    /** What this client calls itself in the MCP handshake. Defaults to `adonis-agora-agent-mcp`. */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Fail application boot when this server cannot be reached. Default `false`: an unreachable
+     * server costs its own tools, not the app — see {@link import('./importer.js').McpToolImporter}.
+     */
+    required?: boolean;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/src/mcp-client/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uGAAuG;IACvG,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,kBAAkB,GAC1B,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B,mGAAmG;AACnG,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gGAAgG;IAChG,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gGAAgG;IAChG,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/src/mcp-client/options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=options.js.map

package/dist/src/mcp-client/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/mcp-client/options.ts"],"names":[],"mappings":""}

package/dist/src/mcp-client/tool-input.d.ts

@@ -0,0 +1,39 @@
+import type { jsonSchemaValidator } from '@modelcontextprotocol/sdk/validation';
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+export interface McpInputSchemaOptions {
+    /**
+     * Compiles the JSON Schema. Defaults to the SDK's AJV adapter; swap in
+     * `CfWorkerJsonSchemaValidator` (or your own) on a runtime where AJV's code generation is not
+     * available.
+     */
+    validator?: jsonSchemaValidator;
+    /**
+     * Reject a schema carrying a `pattern` that can backtrack exponentially (see
+     * {@link findUnsafePattern}). Default `true`. Turn it off only for a `validator` whose regex
+     * engine does not backtrack, where the screen costs tools and buys nothing.
+     */
+    rejectUnsafePatterns?: boolean;
+}
+/**
+ * Wraps one MCP tool's JSON Schema as the [Standard Schema](https://standardschema.dev) that
+ * `ToolSpec.inputSchema` requires, so an imported tool goes through the same `~standard.validate`
+ * gate in `ToolRegistry.invoke` as a hand-written `@AiTool`.
+ *
+ * Both halves are the server's real schema, not an approximation of it:
+ *  - `validate` compiles the schema and rejects what it rejects. A tool whose schema cannot be
+ *    compiled THROWS from here — the caller drops that tool, because the alternative (a schema that
+ *    accepts anything) would let the model send a remote tool arbitrary arguments under the
+ *    appearance of a validated call. A schema whose `pattern` can backtrack exponentially throws
+ *    the same way: validating against it is a denial of service on this process, so the tool is
+ *    worth no more than one whose schema does not compile.
+ *  - `jsonSchema.input` hands the schema back verbatim, which is what makes the model see the real
+ *    parameter shapes: `@adonis-agora/agent/ai-sdk` derives tool parameters from Zod or from
+ *    this Standard JSON Schema extension, and degrades any other Standard Schema to an untyped
+ *    object.
+ *
+ * `input` and `output` return the same document because validation here is a pass-through: a valid
+ * value is handed on unchanged, so the input and output types are the same type. The requested
+ * `target` draft is ignored — the server's schema is a document we relay, not one we can transpile.
+ */
+export declare function mcpInputSchema(jsonSchema: Record<string, unknown>, options?: McpInputSchemaOptions): StandardSchemaV1<unknown, Record<string, unknown>> & StandardJSONSchemaV1;
+//# sourceMappingURL=tool-input.d.ts.map

package/dist/src/mcp-client/tool-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/tool-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhG,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAepF,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,GAAE,qBAA0B,GAClC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,oBAAoB,CA8B3E"}

package/dist/src/mcp-client/tool-input.js

@@ -0,0 +1,61 @@
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import { findUnsafePattern } from './unsafe-regex.js';
+/**
+ * The default validator: the SDK's own AJV adapter, which is already configured for the schemas MCP
+ * servers actually emit (non-strict, format-aware, no meta-schema resolution — so a server that
+ * declares draft-2020-12 compiles as readily as one that declares draft-07).
+ */
+let defaultValidator;
+function sharedValidator() {
+    defaultValidator ??= new AjvJsonSchemaValidator();
+    return defaultValidator;
+}
+/**
+ * Wraps one MCP tool's JSON Schema as the [Standard Schema](https://standardschema.dev) that
+ * `ToolSpec.inputSchema` requires, so an imported tool goes through the same `~standard.validate`
+ * gate in `ToolRegistry.invoke` as a hand-written `@AiTool`.
+ *
+ * Both halves are the server's real schema, not an approximation of it:
+ *  - `validate` compiles the schema and rejects what it rejects. A tool whose schema cannot be
+ *    compiled THROWS from here — the caller drops that tool, because the alternative (a schema that
+ *    accepts anything) would let the model send a remote tool arbitrary arguments under the
+ *    appearance of a validated call. A schema whose `pattern` can backtrack exponentially throws
+ *    the same way: validating against it is a denial of service on this process, so the tool is
+ *    worth no more than one whose schema does not compile.
+ *  - `jsonSchema.input` hands the schema back verbatim, which is what makes the model see the real
+ *    parameter shapes: `@adonis-agora/agent/ai-sdk` derives tool parameters from Zod or from
+ *    this Standard JSON Schema extension, and degrades any other Standard Schema to an untyped
+ *    object.
+ *
+ * `input` and `output` return the same document because validation here is a pass-through: a valid
+ * value is handed on unchanged, so the input and output types are the same type. The requested
+ * `target` draft is ignored — the server's schema is a document we relay, not one we can transpile.
+ */
+export function mcpInputSchema(jsonSchema, options = {}) {
+    if (options.rejectUnsafePatterns !== false) {
+        const unsafe = findUnsafePattern(jsonSchema);
+        if (unsafe !== undefined) {
+            throw new Error(`input schema carries a pattern that can backtrack exponentially: /${unsafe}/`);
+        }
+    }
+    // The MCP wire type describes a tool's schema as an open record and the validator SPI describes
+    // it as a typed JSON Schema interface — the same document, typed from two directions.
+    const validate = (options.validator ?? sharedValidator()).getValidator(jsonSchema);
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'adonis-agora-agent-mcp',
+            validate(value) {
+                const result = validate(value);
+                return result.valid
+                    ? { value: result.data }
+                    : { issues: [{ message: result.errorMessage }] };
+            },
+            jsonSchema: {
+                input: () => jsonSchema,
+                output: () => jsonSchema,
+            },
+        },
+    };
+}
+//# sourceMappingURL=tool-input.js.map

package/dist/src/mcp-client/tool-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input.js","sourceRoot":"","sources":["../../../src/mcp-client/tool-input.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAElF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,IAAI,gBAAiD,CAAC;AAEtD,SAAS,eAAe;IACtB,gBAAgB,KAAK,IAAI,sBAAsB,EAAE,CAAC;IAClD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAmC,EACnC,OAAO,GAA0B,EAAE;IAEnC,IAAI,OAAO,CAAC,oBAAoB,KAAK,KAAK,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,qEAAqE,MAAM,GAAG,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,gGAAgG;IAChG,sFAAsF;IACtF,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,eAAe,EAAE,CAAC,CAAC,YAAY,CACpE,UAA4B,CAC7B,CAAC;IACF,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,wBAAwB;YAChC,QAAQ,CAAC,KAAc;gBACrB,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAC/B,OAAO,MAAM,CAAC,KAAK;oBACjB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE;oBACxB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;YACrD,CAAC;YACD,UAAU,EAAE;gBACV,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU;gBACvB,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU;aACzB;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/src/mcp-client/tool-kind.d.ts

@@ -0,0 +1,37 @@
+import type { ToolKind } from '../types.js';
+/**
+ * An MCP server's self-reported behaviour hints for one tool (MCP `ToolAnnotations`). Every field is
+ * a claim made by the remote server, so nothing here is a security boundary — see
+ * {@link McpToolKindPolicy} for why the default policy ignores them.
+ */
+export interface McpToolAnnotations {
+    title?: string | undefined;
+    readOnlyHint?: boolean | undefined;
+    destructiveHint?: boolean | undefined;
+    idempotentHint?: boolean | undefined;
+    openWorldHint?: boolean | undefined;
+}
+/** What a {@link McpToolKindPolicy} decides on: one tool as the remote server described it. */
+export interface McpToolInfo {
+    name: string;
+    description?: string;
+    annotations?: McpToolAnnotations;
+}
+/**
+ * How an imported MCP tool gets its {@link ToolKind}.
+ *
+ * The stakes: the loop auto-executes a `read` tool and pauses the turn for human approval on an
+ * `action` one. A tool imported from an MCP server was written by someone outside this codebase and
+ * its effects are not visible from here, so the DEFAULT (`'action'`) is the conservative one — a
+ * remote tool needs a human before it runs. Widening that is a decision the host makes explicitly:
+ *
+ *  - `'action'` (default) — every imported tool is HITL-gated.
+ *  - `'read'` — every imported tool auto-executes. Only for a server you own and audit.
+ *  - `'trust-annotations'` — believe the server's `readOnlyHint`. The hint is asserted by the very
+ *    party whose effects it describes, so this is a statement of trust in that server, not a check.
+ *  - a predicate — decide per tool (e.g. read for a known-safe name list, action for the rest).
+ */
+export type McpToolKindPolicy = 'action' | 'read' | 'trust-annotations' | ((tool: McpToolInfo) => 'read' | 'action');
+/** Resolves one imported tool's kind. Anything other than an explicit widening stays `action`. */
+export declare function resolveMcpToolKind(tool: McpToolInfo, policy: McpToolKindPolicy | undefined): ToolKind;
+//# sourceMappingURL=tool-kind.d.ts.map

package/dist/src/mcp-client/tool-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kind.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/tool-kind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,MAAM,GACN,mBAAmB,GACnB,CAAC,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,QAAQ,CAAC,CAAC;AAE/C,kGAAkG;AAClG,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,QAAQ,CAiBV"}

package/dist/src/mcp-client/tool-kind.js

@@ -0,0 +1,20 @@
+/** Resolves one imported tool's kind. Anything other than an explicit widening stays `action`. */
+export function resolveMcpToolKind(tool, policy) {
+    if (typeof policy === 'function') {
+        return policy(tool);
+    }
+    if (policy === 'read') {
+        return 'read';
+    }
+    if (policy === 'trust-annotations') {
+        // `destructiveHint` is only meaningful when `readOnlyHint` is false, so a tool claiming both is
+        // describing itself incoherently — resolved on the gated side rather than guessing which half
+        // of the claim to believe.
+        const annotations = tool.annotations;
+        return annotations?.readOnlyHint === true && annotations.destructiveHint !== true
+            ? 'read'
+            : 'action';
+    }
+    return 'action';
+}
+//# sourceMappingURL=tool-kind.js.map

package/dist/src/mcp-client/tool-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kind.js","sourceRoot":"","sources":["../../../src/mcp-client/tool-kind.ts"],"names":[],"mappings":"AA0CA,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAChC,IAAiB,EACjB,MAAqC;IAErC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,mBAAmB,EAAE,CAAC;QACnC,gGAAgG;QAChG,8FAA8F;QAC9F,2BAA2B;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,OAAO,WAAW,EAAE,YAAY,KAAK,IAAI,IAAI,WAAW,CAAC,eAAe,KAAK,IAAI;YAC/E,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,QAAQ,CAAC;IACf,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/mcp-client/tool-name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The tightest tool-name rule among the major model providers (`^[a-zA-Z0-9_-]{1,64}$`). An MCP
+ * server is under no such constraint — `repo/create.issue` is a legal MCP tool name — so a name is
+ * reshaped here rather than being discovered at turn time as a provider-side rejection.
+ */
+export declare const MAX_TOOL_NAME_LENGTH = 64;
+/**
+ * The name the model and the {@link import('../tool-registry.js').ToolRegistry} see for one
+ * imported tool.
+ *
+ * Namespaced under the server by default: the registry is keyed by name, so an un-namespaced import
+ * would let a remote server's `search` silently replace the app's own `search` — the collision would
+ * present itself as the app tool quietly doing something else.
+ *
+ * `namespace: false` opts out (for a server whose names are already qualified), and a string sets
+ * the prefix explicitly.
+ *
+ * The result is stable across restarts, including when truncated: a stored tool call in a thread
+ * refers to a tool by this name, so a name that changed between boots would strand history.
+ */
+export declare function localToolName(serverName: string, remoteName: string, namespace: boolean | string | undefined): string;
+//# sourceMappingURL=tool-name.d.ts.map

package/dist/src/mcp-client/tool-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/tool-name.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAQvC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GACtC,MAAM,CAQR"}

package/dist/src/mcp-client/tool-name.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+/**
+ * The tightest tool-name rule among the major model providers (`^[a-zA-Z0-9_-]{1,64}$`). An MCP
+ * server is under no such constraint — `repo/create.issue` is a legal MCP tool name — so a name is
+ * reshaped here rather than being discovered at turn time as a provider-side rejection.
+ */
+export const MAX_TOOL_NAME_LENGTH = 64;
+const HASH_LENGTH = 6;
+function sanitize(name) {
+    return name.replace(/[^a-zA-Z0-9_-]+/g, '_');
+}
+/**
+ * The name the model and the {@link import('../tool-registry.js').ToolRegistry} see for one
+ * imported tool.
+ *
+ * Namespaced under the server by default: the registry is keyed by name, so an un-namespaced import
+ * would let a remote server's `search` silently replace the app's own `search` — the collision would
+ * present itself as the app tool quietly doing something else.
+ *
+ * `namespace: false` opts out (for a server whose names are already qualified), and a string sets
+ * the prefix explicitly.
+ *
+ * The result is stable across restarts, including when truncated: a stored tool call in a thread
+ * refers to a tool by this name, so a name that changed between boots would strand history.
+ */
+export function localToolName(serverName, remoteName, namespace) {
+    const prefix = namespace === false ? '' : typeof namespace === 'string' ? namespace : serverName;
+    const full = sanitize(prefix === '' ? remoteName : `${prefix}_${remoteName}`);
+    if (full.length <= MAX_TOOL_NAME_LENGTH) {
+        return full;
+    }
+    const digest = createHash('sha1').update(full).digest('hex').slice(0, HASH_LENGTH);
+    return `${full.slice(0, MAX_TOOL_NAME_LENGTH - HASH_LENGTH - 1)}_${digest}`;
+}
+//# sourceMappingURL=tool-name.js.map

package/dist/src/mcp-client/tool-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.js","sourceRoot":"","sources":["../../../src/mcp-client/tool-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,UAAkB,EAClB,SAAuC;IAEvC,MAAM,MAAM,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IACjG,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC;IAC9E,IAAI,IAAI,CAAC,MAAM,IAAI,oBAAoB,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACnF,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,GAAG,WAAW,GAAG,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;AAC9E,CAAC"}

package/dist/src/mcp-client/tool-source.d.ts

@@ -0,0 +1,75 @@
+import type { ToolHandler } from '../spi/tool.js';
+import type { ToolSpec } from '../types.js';
+import type { McpLogger, McpServerConfig } from './options.js';
+/** One remote tool, mapped onto what `ToolRegistry.register` takes, plus where it came from. */
+export interface McpImportedTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+    /** The name on the server, which namespacing and sanitizing may have changed in `spec.name`. */
+    remoteName: string;
+    serverName: string;
+}
+/** A remote tool that answered with `isError` — a business failure of the tool, not of the transport. */
+export declare class McpToolCallError extends Error {
+    readonly serverName: string;
+    readonly toolName: string;
+    constructor(serverName: string, toolName: string, message: string);
+}
+/**
+ * One MCP server, as a source of tools.
+ *
+ * Holds a single client and reconnects on demand. The connection is deliberately not treated as
+ * durable state: a remote server may restart, be redeployed, or drop an idle connection, and the
+ * first symptom is a failed tool call. So a call that fails transiently drops the client, and the
+ * retry — core's `invokeWithTransientRetry`, the same one the agent loop wraps every tool with —
+ * reconnects on its next attempt.
+ *
+ * Every timeout here is the SDK's own per-request timeout rather than a race of our own, so a
+ * timed-out request is also CANCELLED on the wire instead of being abandoned.
+ */
+export declare class McpToolSource {
+    private readonly config;
+    private readonly logger?;
+    private client;
+    private connecting;
+    constructor(config: McpServerConfig, logger?: McpLogger | undefined);
+    get name(): string;
+    /** Connect if needed, list the server's tools, and map the selected ones onto specs + handlers. */
+    import(): Promise<McpImportedTool[]>;
+    close(): Promise<void>;
+    private isSelected;
+    /**
+     * A tool whose schema won't compile — or whose `pattern` can backtrack exponentially — is
+     * dropped, not imported with a permissive stand-in: the model would then be free to send that
+     * remote tool any arguments at all, and the call would still look validated from this side.
+     */
+    private toImportedTool;
+    private callTool;
+    private callOnce;
+    /** The wire call alone, so only a TRANSPORT failure can recycle the client — never a tool's own. */
+    private request;
+    private errorText;
+    private ensureClient;
+    private connect;
+    private createTransport;
+    private dropClient;
+    /**
+     * The configured policy with a classifier filled in. The library's default classifier recognizes
+     * local database lock contention, which is not how a remote server fails — leaving it in place
+     * would mean the policy is on and never matches anything.
+     *
+     * WHICH CLASSIFIER, AND WHY IT DEPENDS ON THE KIND. An `action` is a tool whose effects happen on
+     * somebody else's machine and are invisible from here, which is why one waits for a human at all.
+     * Most of what {@link isTransientMcpError} accepts cannot tell "the request never arrived" from
+     * "it ran and the answer was lost" — a timeout, a reset, a 503 — so retrying on it would spend one
+     * approval on two remote effects. An `action` therefore retries only
+     * {@link isPreExecutionMcpError}: failures that prove nothing ran. A `read` keeps the broader
+     * policy, where a second identical call costs a round trip.
+     *
+     * A host that supplied its own `classify` has taken that judgement over, and it is honoured for
+     * every kind.
+     */
+    private retrySetting;
+    private requestTimeoutMs;
+}
+//# sourceMappingURL=tool-source.d.ts.map