@openrouter/agent 0.9.0 → 0.10.0

package/esm/mcp/types.d.ts

@@ -0,0 +1,119 @@
+import type { Tool, ToolLoopKey } from '../lib/tool-types.js';
+import type { MCPAuth } from './auth/auth-types.js';
+import type { MCPCacheStore } from './cache/cache-store.js';
+import type { UnconvertibleSchemaMode } from './schema/json-schema-to-zod.js';
+import type { MCPProtocolNegotiation, MCPProtocolRevision, MCPTransportKind } from './transport-types.js';
+export type { MCPProtocolNegotiation, MCPProtocolRevision, MCPTransportKind };
+/**
+ * Response to a server-initiated elicitation request. `accept` must carry
+ * `content` matching the server's `requestedSchema`.
+ */
+export type ElicitationResponse = {
+    action: 'accept';
+    content: Record<string, unknown>;
+} | {
+    action: 'decline';
+} | {
+    action: 'cancel';
+};
+/**
+ * Handler for server-initiated `elicitation/create` requests during a tool
+ * call. If omitted from options, requests are auto-declined so a tool call
+ * needing input fails gracefully rather than hanging.
+ */
+export type ElicitationHandler = (request: {
+    message: string;
+    requestedSchema: Record<string, unknown>;
+}) => Promise<ElicitationResponse> | ElicitationResponse;
+/** How MCP resources are exposed to the model. */
+export type ResourcesOption = boolean | {
+    mode?: 'synthetic-tools';
+};
+export interface CreateMCPToolsOptions {
+    /** Remote MCP server endpoint. */
+    url: string | URL;
+    /** Transport to use; defaults to `streamableHttp` with SSE fallback. */
+    transport?: MCPTransportKind;
+    /** Authentication, supplied once and reused for discovery + every call. */
+    auth?: MCPAuth;
+    /** Custom fetch implementation for all network requests. */
+    fetch?: typeof fetch;
+    /** Client identity sent during `initialize`. */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Prefix applied to every wrapped tool name (e.g. `"github_"`). */
+    toolNamePrefix?: string;
+    /**
+     * Allow-list of MCP tool names to expose. Applies to discovered MCP tools
+     * only; synthetic `list_resources`/`read_resource` tools are controlled
+     * exclusively by `resources`.
+     */
+    includeTools?: readonly string[];
+    /**
+     * Deny-list of MCP tool names to skip. Applies to discovered MCP tools only;
+     * synthetic `list_resources`/`read_resource` tools are controlled
+     * exclusively by `resources`.
+     */
+    excludeTools?: readonly string[];
+    /** Behavior when a tool's JSON Schema can't be fully represented in Zod. */
+    onUnconvertibleSchema?: UnconvertibleSchemaMode;
+    /** Cache store + key for automatic rehydrate-on-hit / write-on-miss. */
+    cache?: {
+        store: MCPCacheStore;
+        key?: string;
+    };
+    /** Persist resolved tokens/session into the snapshot. Off by default. */
+    cacheCredentials?: boolean;
+    /** Re-list tools when a cached snapshot is older than this. */
+    staleness?: {
+        maxAgeMs?: number;
+    };
+    /** Expose resources as synthetic `list_resources`/`read_resource` tools. */
+    resources?: ResourcesOption;
+    /** Map MCP progress notifications to generator-tool events. Default true. */
+    emitProgress?: boolean;
+    /**
+     * Doom-loop identities for wrapped tools (see the `doomLoop` option on
+     * `callModel`), keyed by the tool's UNPREFIXED MCP name. Any `ToolLoopKey`
+     * form: a function computing key material, a declarative field-name array
+     * (e.g. `{ run_command: ['command', 'cwd'] }`), or `false` to exempt a
+     * tool. Takes precedence over a server-advertised
+     * `_meta['openrouter/loopKey']` declaration. Function forms are
+     * client-side only (they cannot be cached or transported); prefer field
+     * lists where possible.
+     */
+    loopKeys?: Readonly<Record<string, ToolLoopKey<Record<string, unknown>>>>;
+    /** Auto-refresh tools on `tools/list_changed`. Default true when connected. */
+    autoRefreshOnListChanged?: boolean;
+    /** Handler for server-initiated elicitation; auto-declines when omitted. */
+    onElicitation?: ElicitationHandler;
+    /** Protocol-revision negotiation policy; defaults to `auto`. */
+    protocolNegotiation?: MCPProtocolNegotiation;
+    /** Ceiling on the `server/discover` probe, in ms; defaults to 30000. */
+    probeTimeoutMs?: number;
+    /** Abort signal threaded into every underlying `callTool`. */
+    signal?: AbortSignal;
+}
+/**
+ * Handle returned by {@link createMCPTools}/`rehydrateMCPTools`. Holds a live
+ * connection (unless rehydrated offline) and the wrapped tools.
+ */
+export interface MCPToolsHandle {
+    /** Tools ready to pass into `callModel({ tools })`. */
+    readonly tools: readonly Tool[];
+    readonly serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    /** Snapshot for persistence; omits credentials unless `cacheCredentials`. */
+    serialize(): Promise<import('./cache/cache-types.js').SerializedMCPServer>;
+    /** Force a fresh `listTools()` and rebuild the tool set. */
+    refresh(): Promise<readonly Tool[]>;
+    /** Subscribe to auto-refreshes triggered by `tools/list_changed`. */
+    onToolsChanged(listener: (tools: readonly Tool[]) => void): () => void;
+    /** Close the transport and underlying client. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/mcp/types.d.ts.map

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

package/esm/mcp/types.js

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

package/esm/mcp/types.js.map

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

package/esm/mcp/version.d.ts

@@ -0,0 +1,3 @@
+/** This package's version, self-reported to MCP servers as `clientInfo`. */
+export declare const PACKAGE_VERSION = "0.10.0";
+//# sourceMappingURL=version.d.ts.map

package/esm/mcp/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/mcp/version.ts"],"names":[],"mappings":"AAGA,4EAA4E;AAC5E,eAAO,MAAM,eAAe,WAAW,CAAC"}

package/esm/mcp/version.js

@@ -0,0 +1,5 @@
+// DO NOT EDIT — generated from package.json by scripts/gen-version.mjs.
+// Run `pnpm --filter @openrouter/agent gen:version` after bumping the version.
+/** This package's version, self-reported to MCP servers as `clientInfo`. */
+export const PACKAGE_VERSION = '0.10.0';
+//# sourceMappingURL=version.js.map

package/esm/mcp/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/mcp/version.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAE/E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/agent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "author": "OpenRouter",
   "description": "Agent toolkit for building AI applications with OpenRouter — tool orchestration, streaming, multi-turn conversations, and format compatibility.",
   "keywords": [
@@ -92,11 +92,34 @@
       "types": "./esm/lib/turn-context.d.ts",
       "default": "./esm/lib/turn-context.js"
     },
+    "./tool-set": {
+      "types": "./esm/lib/tool-set.d.ts",
+      "default": "./esm/lib/tool-set.js"
+    },
     "./openrouter": {
       "types": "./esm/openrouter.d.ts",
       "default": "./esm/openrouter.js"
     },
-    "./package.json": "./package.json",
+    "./mcp": {
+      "types": "./esm/mcp/index.d.ts",
+      "default": "./esm/mcp/index.js"
+    },
+    "./mcp/create-mcp-tools": {
+      "types": "./esm/mcp/create-mcp-tools.d.ts",
+      "default": "./esm/mcp/create-mcp-tools.js"
+    },
+    "./mcp/types": {
+      "types": "./esm/mcp/types.d.ts",
+      "default": "./esm/mcp/types.js"
+    },
+    "./mcp/schema": {
+      "types": "./esm/mcp/schema/json-schema-to-zod.d.ts",
+      "default": "./esm/mcp/schema/json-schema-to-zod.js"
+    },
+    "./mcp/cache": {
+      "types": "./esm/mcp/cache/cache-store.d.ts",
+      "default": "./esm/mcp/cache/cache-store.js"
+    },
     "./tool-concurrency": {
       "types": "./esm/lib/tool-concurrency.d.ts",
       "default": "./esm/lib/tool-concurrency.js"
@@ -120,7 +143,8 @@
     "./agent-tool": {
       "types": "./esm/lib/agent-tool.d.ts",
       "default": "./esm/lib/agent-tool.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "sideEffects": false,
   "repository": {
@@ -135,20 +159,33 @@
   "files": [
     "esm",
     "package.json",
-    "README.md"
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "dependencies": {
     "@openrouter/sdk": "^0.13.7",
     "zod": "^4.0.0"
   },
+  "peerDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0"
+  },
   "scripts": {
     "lint": "biome check src tests",
     "lint:fix": "biome check --write src tests",
-    "build": "tsc",
+    "build": "node scripts/gen-version.mjs && tsc",
     "test": "vitest --run --project unit",
-    "test:e2e": "vitest --run --project e2e",
+    "test:e2e": "vitest --run --project e2e --coverage.enabled=false",
     "test:watch": "vitest --watch --project unit",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
-    "compile": "tsc"
+    "compile": "node scripts/gen-version.mjs && tsc",
+    "gen:version": "node scripts/gen-version.mjs"
   }
 }