@adonis-agora/agent 0.30.2 → 0.33.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-source.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/tool-source.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAU/D,gGAAgG;AAChG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;IACrB,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yGAAyG;AACzG,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,MAAM;IAFlC,YACkB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM,EAIhB;CACF;AAoBD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAL1B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAA8B;IAEhD,YACmB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,SAAS,YAAA,EACjC;IAEJ,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mGAAmG;IAC7F,MAAM,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAczC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;IAED,OAAO,CAAC,UAAU;IAQlB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;YAcF,QAAQ;IAgBtB,oGAAoG;YACtF,OAAO;IAgBrB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,YAAY;YAYN,OAAO;IAerB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,UAAU;IAMlB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,gBAAgB;CAGzB"}

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

@@ -0,0 +1,244 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import { invokeWithTransientRetry } from '../tool-retry.js';
+import { mcpInputSchema } from './tool-input.js';
+import { resolveMcpToolKind } from './tool-kind.js';
+import { localToolName } from './tool-name.js';
+import { isPreExecutionMcpError, isTransientMcpError } from './transient.js';
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const CLIENT_INFO = { name: 'adonis-agora-agent-mcp', version: '1.0.0' };
+/** A remote tool that answered with `isError` — a business failure of the tool, not of the transport. */
+export class McpToolCallError extends Error {
+    serverName;
+    toolName;
+    constructor(serverName, toolName, message) {
+        super(message);
+        this.serverName = serverName;
+        this.toolName = toolName;
+        this.name = 'McpToolCallError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * `content` is optional in the compatibility result shape the SDK still accepts, so it is narrowed
+ * rather than trusted: a server that answers without it yields no blocks instead of a crash.
+ */
+function toContentBlocks(content) {
+    return Array.isArray(content) ? content : [];
+}
+/**
+ * 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 class McpToolSource {
+    config;
+    logger;
+    client;
+    connecting;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+    get name() {
+        return this.config.name;
+    }
+    /** Connect if needed, list the server's tools, and map the selected ones onto specs + handlers. */
+    async import() {
+        const client = await this.ensureClient();
+        const { tools } = await client.listTools(undefined, { timeout: this.requestTimeoutMs() });
+        const imported = [];
+        for (const tool of tools) {
+            if (!this.isSelected(tool.name)) {
+                continue;
+            }
+            const mapped = this.toImportedTool(tool);
+            if (mapped !== undefined) {
+                imported.push(mapped);
+            }
+        }
+        return imported;
+    }
+    async close() {
+        const client = this.client ?? (await this.connecting?.catch(() => undefined));
+        this.client = undefined;
+        this.connecting = undefined;
+        await client?.close();
+    }
+    isSelected(remoteName) {
+        const { include, exclude } = this.config;
+        if (include !== undefined && !include.includes(remoteName)) {
+            return false;
+        }
+        return exclude === undefined || !exclude.includes(remoteName);
+    }
+    /**
+     * 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.
+     */
+    toImportedTool(tool) {
+        const name = localToolName(this.config.name, tool.name, this.config.namespace);
+        let inputSchema;
+        try {
+            inputSchema = mcpInputSchema(tool.inputSchema, {
+                ...(this.config.validator !== undefined ? { validator: this.config.validator } : {}),
+                ...(this.config.rejectUnsafePatterns !== undefined
+                    ? { rejectUnsafePatterns: this.config.rejectUnsafePatterns }
+                    : {}),
+            });
+        }
+        catch (error) {
+            this.logger?.warn(`MCP server "${this.config.name}": tool "${tool.name}" has an input schema this process will not validate against — skipped (${error instanceof Error ? error.message : String(error)})`);
+            return undefined;
+        }
+        const spec = {
+            name,
+            kind: resolveMcpToolKind({
+                name: tool.name,
+                ...(tool.description !== undefined ? { description: tool.description } : {}),
+                ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+            }, this.config.kind),
+            description: tool.description ?? `The "${tool.name}" tool on MCP server ${this.config.name}.`,
+            inputSchema,
+            ...(this.config.roles !== undefined ? { roles: this.config.roles } : {}),
+            ...(this.config.ability !== undefined ? { ability: this.config.ability } : {}),
+        };
+        const handler = {
+            execute: (input) => this.callTool(tool.name, input, spec.kind),
+        };
+        return { spec, handler, remoteName: tool.name, serverName: this.config.name };
+    }
+    callTool(remoteName, input, kind) {
+        return invokeWithTransientRetry(() => this.callOnce(remoteName, input), this.retrySetting(kind), {
+            onRetry: (attempt, error) => {
+                this.logger?.warn(`MCP server "${this.config.name}": tool "${remoteName}" failed transiently on attempt ${attempt}, reconnecting (${error instanceof Error ? error.message : String(error)})`);
+            },
+        });
+    }
+    async callOnce(remoteName, input) {
+        const result = await this.request(remoteName, input);
+        const content = toContentBlocks(result.content);
+        if (result.isError === true) {
+            throw new McpToolCallError(this.config.name, remoteName, this.errorText(content));
+        }
+        if (result.structuredContent !== undefined) {
+            return result.structuredContent;
+        }
+        // The overwhelmingly common shape is one text block; handing the model the bare string keeps it
+        // from having to read past an envelope that carries nothing. Anything richer (images, embedded
+        // resources, several blocks) is passed through as MCP modelled it.
+        const only = content.length === 1 ? content[0] : undefined;
+        return only?.type === 'text' ? only.text : { content };
+    }
+    /** The wire call alone, so only a TRANSPORT failure can recycle the client — never a tool's own. */
+    async request(remoteName, input) {
+        const client = await this.ensureClient();
+        try {
+            return await client.callTool({ name: remoteName, ...(isRecord(input) ? { arguments: input } : {}) }, CallToolResultSchema, { timeout: this.requestTimeoutMs() });
+        }
+        catch (error) {
+            if (isTransientMcpError(error)) {
+                this.dropClient();
+            }
+            throw error;
+        }
+    }
+    errorText(content) {
+        const text = content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text ?? '')
+            .join('\n')
+            .trim();
+        return text === '' ? `MCP tool "${this.config.name}" reported an error` : text;
+    }
+    ensureClient() {
+        if (this.client !== undefined) {
+            return Promise.resolve(this.client);
+        }
+        // One in-flight connect shared by every caller: a turn can call several of a server's tools at
+        // once, and each opening its own connection would leave all but one orphaned.
+        this.connecting ??= this.connect().finally(() => {
+            this.connecting = undefined;
+        });
+        return this.connecting;
+    }
+    async connect() {
+        const client = new Client(this.config.clientInfo ?? CLIENT_INFO);
+        const transport = await this.createTransport();
+        await client.connect(transport, {
+            timeout: this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+        });
+        client.onclose = () => {
+            if (this.client === client) {
+                this.client = undefined;
+            }
+        };
+        this.client = client;
+        return client;
+    }
+    createTransport() {
+        const transport = this.config.transport;
+        switch (transport.type) {
+            case 'stdio':
+                return new StdioClientTransport({
+                    command: transport.command,
+                    ...(transport.args !== undefined ? { args: transport.args } : {}),
+                    ...(transport.env !== undefined ? { env: transport.env } : {}),
+                    ...(transport.cwd !== undefined ? { cwd: transport.cwd } : {}),
+                });
+            case 'http':
+                // The SDK's own transports expose `sessionId` as `string | undefined` where the `Transport`
+                // interface declares the property optional, which `exactOptionalPropertyTypes` reads as a
+                // mismatch — the class does implement the interface it is declared against.
+                return new StreamableHTTPClientTransport(new URL(transport.url), transport.headers !== undefined ? { requestInit: { headers: transport.headers } } : {});
+            case 'custom':
+                return transport.create();
+        }
+    }
+    dropClient() {
+        const client = this.client;
+        this.client = undefined;
+        void client?.close().catch(() => undefined);
+    }
+    /**
+     * 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.
+     */
+    retrySetting(kind) {
+        const setting = this.config.transientRetry;
+        if (setting === false) {
+            return false;
+        }
+        const fallback = kind === 'action' ? isPreExecutionMcpError : isTransientMcpError;
+        return { ...setting, classify: setting?.classify ?? fallback };
+    }
+    requestTimeoutMs() {
+        return this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+}
+//# sourceMappingURL=tool-source.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * Transient-error classification for an MCP server, in the shape `toolTransientRetry` already speaks
+ * (`classify: (error) => boolean`). {@link import('../tool-retry.js').isTransientToolError}
+ * recognizes local database lock contention; a remote MCP server fails in a different vocabulary —
+ * JSON-RPC error codes, HTTP statuses, socket errors — which is what this adds.
+ */
+/**
+ * True for a remote-MCP failure that the same call, made again, may well survive: a dropped
+ * connection, a request timeout, a retryable HTTP status, a socket error. Checked on the error and
+ * one level of `cause` — `fetch` reports a socket failure as a bare `TypeError` wrapping the real
+ * one, the same wrapping core's classifier already unwraps for database drivers.
+ *
+ * A protocol-level refusal (`InvalidParams`, `MethodNotFound`) and a server-side `InternalError`
+ * are deliberately NOT transient: the identical request would be refused identically, so retrying
+ * only spends the turn's time budget.
+ */
+export declare function isTransientMcpError(error: unknown): boolean;
+/**
+ * True only for a failure that PROVES the remote tool did not run: the connection was refused, the
+ * host was never reached, or the SDK had no transport to send on. Checked on the error and one level
+ * of `cause`, so `fetch`'s bare `TypeError` wrapper is read through to the socket error underneath.
+ *
+ * Everything {@link isTransientMcpError} also accepts — a request timeout, a dropped connection, a
+ * 500/502/503, a reset mid-flight — is deliberately excluded: in each of those the request may have
+ * arrived and executed, and only the answer was lost. Retrying them would run the tool twice.
+ */
+export declare function isPreExecutionMcpError(error: unknown): boolean;
+//# sourceMappingURL=transient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transient.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/transient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmDH;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW3D;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9D"}

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

@@ -0,0 +1,126 @@
+/**
+ * Transient-error classification for an MCP server, in the shape `toolTransientRetry` already speaks
+ * (`classify: (error) => boolean`). {@link import('../tool-retry.js').isTransientToolError}
+ * recognizes local database lock contention; a remote MCP server fails in a different vocabulary —
+ * JSON-RPC error codes, HTTP statuses, socket errors — which is what this adds.
+ */
+/** JSON-RPC codes whose retry is safe: the request never reached the tool, or its answer was lost. */
+const TRANSIENT_JSONRPC_CODES = new Set([-32000, -32001]); // ConnectionClosed, RequestTimeout
+/** HTTP statuses the streamable-HTTP transport surfaces for "try again", not "you asked wrong". */
+const TRANSIENT_HTTP_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+/** Socket/DNS failures from `fetch` or a spawned stdio server that a reconnect can clear. */
+const TRANSIENT_SYSCALL_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+]);
+/**
+ * The SDK reports "you called while there was no transport" as a plain `Error` with no code, so the
+ * message is the only marker available. Kept narrow on purpose — a message test that matched more
+ * broadly would start retrying a remote tool's ordinary business failures, which are one-shot.
+ */
+const TRANSIENT_MESSAGES = /^not connected$|connection closed|socket hang up|fetch failed/i;
+function hasTransientMcpShape(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    // A tool that answered `isError` failed on its own merits, and its message is text the remote
+    // server wrote — matching it against the markers below would let a tool's prose decide whether
+    // this side retries. Matched by name rather than `instanceof`, which a second copy of this
+    // package (pnpm peer multiplexing, dual ESM/CJS) would not survive.
+    if ('name' in error && error.name === 'McpToolCallError') {
+        return false;
+    }
+    const code = 'code' in error ? error.code : undefined;
+    if (typeof code === 'number') {
+        // `McpError` and the streamable-HTTP transport both surface a `code`, and the two vocabularies
+        // never overlap: JSON-RPC codes are negative, HTTP statuses are positive.
+        return code < 0 ? TRANSIENT_JSONRPC_CODES.has(code) : TRANSIENT_HTTP_STATUSES.has(code);
+    }
+    if (typeof code === 'string' && TRANSIENT_SYSCALL_CODES.has(code)) {
+        return true;
+    }
+    const message = 'message' in error ? error.message : undefined;
+    return typeof message === 'string' && TRANSIENT_MESSAGES.test(message);
+}
+/**
+ * True for a remote-MCP failure that the same call, made again, may well survive: a dropped
+ * connection, a request timeout, a retryable HTTP status, a socket error. Checked on the error and
+ * one level of `cause` — `fetch` reports a socket failure as a bare `TypeError` wrapping the real
+ * one, the same wrapping core's classifier already unwraps for database drivers.
+ *
+ * A protocol-level refusal (`InvalidParams`, `MethodNotFound`) and a server-side `InternalError`
+ * are deliberately NOT transient: the identical request would be refused identically, so retrying
+ * only spends the turn's time budget.
+ */
+export function isTransientMcpError(error) {
+    if (hasTransientMcpShape(error)) {
+        return true;
+    }
+    if (typeof error === 'object' && error !== null && 'cause' in error) {
+        const cause = error.cause;
+        if (cause !== undefined && cause !== error && hasTransientMcpShape(cause)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Syscall codes that mean the request was never delivered: the connection was refused, or the host
+ * was never resolved or reached. A reset, a broken pipe or a timeout does NOT belong here — each of
+ * those can equally well be a reply that was lost after the tool ran.
+ */
+const PRE_EXECUTION_SYSCALL_CODES = new Set([
+    'ECONNREFUSED',
+    'EAI_AGAIN',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+]);
+/** The SDK refusing to send because there is no transport — nothing left this process. */
+const PRE_EXECUTION_MESSAGES = /^not connected$/i;
+function hasPreExecutionShape(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    if ('name' in error && error.name === 'McpToolCallError') {
+        return false;
+    }
+    const code = 'code' in error ? error.code : undefined;
+    if (typeof code === 'string') {
+        return PRE_EXECUTION_SYSCALL_CODES.has(code);
+    }
+    if (code !== undefined) {
+        // A JSON-RPC code or an HTTP status means the wire carried the request far enough to be
+        // answered, so neither can establish that the tool did not run.
+        return false;
+    }
+    const message = 'message' in error ? error.message : undefined;
+    return typeof message === 'string' && PRE_EXECUTION_MESSAGES.test(message);
+}
+/**
+ * True only for a failure that PROVES the remote tool did not run: the connection was refused, the
+ * host was never reached, or the SDK had no transport to send on. Checked on the error and one level
+ * of `cause`, so `fetch`'s bare `TypeError` wrapper is read through to the socket error underneath.
+ *
+ * Everything {@link isTransientMcpError} also accepts — a request timeout, a dropped connection, a
+ * 500/502/503, a reset mid-flight — is deliberately excluded: in each of those the request may have
+ * arrived and executed, and only the answer was lost. Retrying them would run the tool twice.
+ */
+export function isPreExecutionMcpError(error) {
+    if (hasPreExecutionShape(error)) {
+        return true;
+    }
+    if (typeof error === 'object' && error !== null && 'cause' in error) {
+        const cause = error.cause;
+        if (cause !== undefined && cause !== error && hasPreExecutionShape(cause)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=transient.js.map

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

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

package/dist/src/mcp-client/unsafe-regex.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A screen for the one thing a remote JSON Schema can do to the process that validates against it.
+ *
+ * Every validator in the MCP SDK compiles a schema's `pattern` to a native `RegExp`, and JS regex
+ * matching backtracks: `(a+)+$` against 27 a's and a non-matching tail takes ~1s, 30 a's ~8s, 40 a's
+ * longer than anyone will wait — synchronously, on the only thread the process has. The pattern is
+ * written by the remote server and the string is written by the model, which the same server's tool
+ * description is free to steer, so the whole thing fits inside one tool definition.
+ *
+ * What is detected is the shape that makes backtracking EXPONENTIAL: an unbounded repetition whose
+ * body can match one piece of text in more than one way, so a failed match has to try every split.
+ * It is a structural screen and not a decision procedure — `(ab|abc)+` is ambiguous across
+ * alternatives and is not flagged here. A host that needs a guarantee rather than a screen gives
+ * `validator` an engine that does not backtrack (AJV's `code.regExp` option takes an RE2 binding).
+ */
+/** Whether this pattern can be made to backtrack exponentially. See the file comment for the limits. */
+export declare function isUnsafeRegex(pattern: string): boolean;
+/**
+ * The first pattern anywhere in a JSON Schema that {@link isUnsafeRegex} flags — `pattern` at any
+ * depth, and the keys of `patternProperties`, which are regexes too.
+ */
+export declare function findUnsafePattern(schema: unknown): string | undefined;
+//# sourceMappingURL=unsafe-regex.d.ts.map

package/dist/src/mcp-client/unsafe-regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafe-regex.d.ts","sourceRoot":"","sources":["../../../src/mcp-client/unsafe-regex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAwKH,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgCrE"}

package/dist/src/mcp-client/unsafe-regex.js

@@ -0,0 +1,194 @@
+/**
+ * A screen for the one thing a remote JSON Schema can do to the process that validates against it.
+ *
+ * Every validator in the MCP SDK compiles a schema's `pattern` to a native `RegExp`, and JS regex
+ * matching backtracks: `(a+)+$` against 27 a's and a non-matching tail takes ~1s, 30 a's ~8s, 40 a's
+ * longer than anyone will wait — synchronously, on the only thread the process has. The pattern is
+ * written by the remote server and the string is written by the model, which the same server's tool
+ * description is free to steer, so the whole thing fits inside one tool definition.
+ *
+ * What is detected is the shape that makes backtracking EXPONENTIAL: an unbounded repetition whose
+ * body can match one piece of text in more than one way, so a failed match has to try every split.
+ * It is a structural screen and not a decision procedure — `(ab|abc)+` is ambiguous across
+ * alternatives and is not flagged here. A host that needs a guarantee rather than a screen gives
+ * `validator` an engine that does not backtrack (AJV's `code.regExp` option takes an RE2 binding).
+ */
+const QUANTIFIER = /^(?:([*+?])|\{(\d+)(,(\d*))?\})/;
+/**
+ * Enough of a regex parser to see the nesting: alternatives, groups, quantifiers, and one opaque
+ * atom for everything else. Anything it does not recognize is a literal, which makes the parse
+ * total — a pattern this cannot read comes out as a flat list of tight atoms and is not flagged,
+ * rather than throwing where the caller expects a verdict.
+ */
+class PatternParser {
+    pattern;
+    index = 0;
+    constructor(pattern) {
+        this.pattern = pattern;
+    }
+    parse() {
+        const branches = this.parseAlternation();
+        // A `)` with no `(` — the pattern is not valid, and the compiler is about to say so.
+        this.index = this.pattern.length;
+        return branches;
+    }
+    parseAlternation() {
+        const branches = [];
+        let branch = [];
+        while (this.index < this.pattern.length) {
+            const char = this.pattern[this.index];
+            if (char === ')') {
+                break;
+            }
+            if (char === '|') {
+                this.index += 1;
+                branches.push(branch);
+                branch = [];
+                continue;
+            }
+            branch.push(this.parseAtom());
+        }
+        branches.push(branch);
+        return branches;
+    }
+    parseAtom() {
+        const char = this.pattern[this.index];
+        if (char === '(') {
+            this.index += 1;
+            this.skipGroupPrefix();
+            const body = this.parseAlternation();
+            if (this.pattern[this.index] === ')') {
+                this.index += 1;
+            }
+            return this.withQuantifier({ body });
+        }
+        if (char === '[') {
+            this.skipCharacterClass();
+            return this.withQuantifier({});
+        }
+        // An escape is two characters, so `\(` never opens a group and `\\` never escapes the next one.
+        this.index += char === '\\' ? 2 : 1;
+        return this.withQuantifier({});
+    }
+    skipGroupPrefix() {
+        if (this.pattern[this.index] !== '?') {
+            return;
+        }
+        const closing = this.pattern.indexOf('>', this.index);
+        // `(?<name>` — the only prefix whose length is not fixed. Every other one (`?:`, `?=`, `?!`,
+        // `?<=`, `?<!`) ends before the first character of the body.
+        if (this.pattern[this.index + 1] === '<' &&
+            !'=!'.includes(this.pattern[this.index + 2] ?? '')) {
+            this.index = closing === -1 ? this.pattern.length : closing + 1;
+            return;
+        }
+        this.index += this.pattern[this.index + 1] === '<' ? 3 : 2;
+    }
+    skipCharacterClass() {
+        this.index += 1;
+        while (this.index < this.pattern.length && this.pattern[this.index] !== ']') {
+            this.index += this.pattern[this.index] === '\\' ? 2 : 1;
+        }
+        this.index += 1;
+    }
+    withQuantifier(atom) {
+        const match = QUANTIFIER.exec(this.pattern.slice(this.index));
+        if (match === null) {
+            return atom;
+        }
+        this.index += match[0].length;
+        // A trailing `?` makes the repetition lazy, which changes the order the splits are tried and
+        // not how many there are.
+        if (this.pattern[this.index] === '?') {
+            this.index += 1;
+        }
+        return { ...atom, quantifier: toQuantifier(match) };
+    }
+}
+function toQuantifier(match) {
+    const symbol = match[1];
+    if (symbol !== undefined) {
+        return { variable: true, unbounded: symbol !== '?' };
+    }
+    const min = Number(match[2]);
+    const comma = match[3] !== undefined;
+    const max = match[4] === undefined || match[4] === '' ? Number.POSITIVE_INFINITY : Number(match[4]);
+    return {
+        variable: comma ? min < max : false,
+        unbounded: comma && max === Number.POSITIVE_INFINITY,
+    };
+}
+/** Whether this atom can match more than one length — on its own, or through what it contains. */
+function isVariable(atom) {
+    if (atom.quantifier?.variable === true) {
+        return true;
+    }
+    return (atom.body ?? []).some((branch) => branch.some(isVariable));
+}
+/**
+ * Whether repeating these alternatives is ambiguous: one alternative made entirely of parts that
+ * can each stretch, so the boundary between two repetitions can fall in more than one place and a
+ * failed match has to try all of them. `(a+)` qualifies and `(a+b)` does not — the `b` pins every
+ * repetition to one position.
+ */
+function isAmbiguous(branches) {
+    return branches.some((branch) => branch.length > 0 && branch.every(isVariable));
+}
+function containsUnsafeRepeat(branches) {
+    for (const branch of branches) {
+        for (const atom of branch) {
+            if (atom.body === undefined) {
+                continue;
+            }
+            if (atom.quantifier?.unbounded === true && isAmbiguous(atom.body)) {
+                return true;
+            }
+            if (containsUnsafeRepeat(atom.body)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** Whether this pattern can be made to backtrack exponentially. See the file comment for the limits. */
+export function isUnsafeRegex(pattern) {
+    return containsUnsafeRepeat(new PatternParser(pattern).parse());
+}
+/**
+ * The first pattern anywhere in a JSON Schema that {@link isUnsafeRegex} flags — `pattern` at any
+ * depth, and the keys of `patternProperties`, which are regexes too.
+ */
+export function findUnsafePattern(schema) {
+    if (Array.isArray(schema)) {
+        for (const item of schema) {
+            const found = findUnsafePattern(item);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (typeof schema !== 'object' || schema === null) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === 'pattern' && typeof value === 'string') {
+            if (isUnsafeRegex(value)) {
+                return value;
+            }
+            continue;
+        }
+        if (key === 'patternProperties' && typeof value === 'object' && value !== null) {
+            const unsafeKey = Object.keys(value).find(isUnsafeRegex);
+            if (unsafeKey !== undefined) {
+                return unsafeKey;
+            }
+        }
+        const found = findUnsafePattern(value);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=unsafe-regex.js.map