refactor(agent): nest tool-set and MCP under agent subpaths

.changeset/agent-mcp-subpath.md

@@ -0,0 +1,22 @@
+---
+"@openrouter/agent": minor
+"@openrouter/mcp": minor
+---
+
+Add the full MCP integration under the canonical `@openrouter/agent/mcp` subpath. `@modelcontextprotocol/sdk` is an optional peer, so base agent installations and imports do not install or load MCP support. The existing `@openrouter/mcp` package remains as a compatibility facade and now re-exports the canonical agent subpaths.
+
+```ts
+import { callModel, OpenRouter } from '@openrouter/agent';
+import { createMCPTools } from '@openrouter/agent/mcp';
+
+const mcp = await createMCPTools({ url: 'https://mcp.example.com/mcp' });
+const result = callModel(new OpenRouter(), {
+  model: 'openai/gpt-4o-mini',
+  input: 'Use the remote tools.',
+  tools: mcp.tools,
+});
+```
+
+Install `@modelcontextprotocol/sdk` alongside `@openrouter/agent` when using `/mcp`. The SDK is loaded lazily, so importing the base agent or the MCP entry point does not require the peer; the first MCP connection attempt without it throws an actionable `MCPMissingPeerDependencyError`.
+
+Existing `@openrouter/mcp` imports continue to work as tooling-visible deprecated migration facades, but new code should prefer `@openrouter/agent/mcp`. The facade would only be removed in a future breaking release after migration notice.

.changeset/agent-tool-set.md

@@ -1,13 +1,12 @@
 ---
-"@openrouter/agent-tool-set": minor
 "@openrouter/agent": minor
 ---
 
-Add `@openrouter/agent-tool-set` (port of ai-tool-set v1.0.0, MIT © Chris Cook): declarative activate / deactivate / activateWhen / deactivateWhen for tools with state- and context-aware predicates. Integrates with a new `activeTools?: readonly string[]` option on `callModel` that filters which tools are sent to the model for a given call.
+Add `@openrouter/agent/tool-set` (port of ai-tool-set v1.0.0, MIT © Chris Cook): declarative activate / deactivate / activateWhen / deactivateWhen for tools with state- and context-aware predicates. Integrates with a new `activeTools?: readonly string[]` option on `callModel` that filters which tools are sent to the model for a given call.
 
 ```ts
 import { callModel, OpenRouter, serverTool, tool } from '@openrouter/agent';
-import { createToolSet } from '@openrouter/agent-tool-set';
+import { createToolSet } from '@openrouter/agent/tool-set';
 import { z } from 'zod/v4';
 
 const listOrders = tool({

.changeset/mcp-loop-key.md

@@ -7,7 +7,7 @@ Doom-loop `loopKey` support for MCP-wrapped tools (pairs with `@openrouter/agent
 Two ways to declare a wrapped tool's call identity: a client-side `loopKeys` map on `createMCPTools`/`rehydrateMCPTools` (keyed by unprefixed MCP tool name; any `ToolLoopKey` form — function, field-name array, or `false` to exempt), and a server-advertised `_meta['openrouter/loopKey']` on the tool definition (data-only: field-name array or `false`). Client config takes precedence. Server-advertised declarations ride the cache snapshot (`SerializedMCPToolDef.loopKey`), so rehydrated tool sets keep their identities without a `listTools()` round-trip; function forms are client-side only and cannot be cached.
 
 ```ts
-import { createMCPTools } from '@openrouter/mcp';
+import { createMCPTools } from '@openrouter/agent/mcp';
 
 const mcp = await createMCPTools({
   url: 'https://mcp.example.com/mcp',

.github/workflows/ci.yaml

@@ -65,6 +65,25 @@ jobs:
       - name: Tests
         run: pnpm run test
 
+  package-boundaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Verify packed package boundaries
+        run: pnpm verify:packages
+
   e2e-tests:
     runs-on: ubuntu-latest
     steps:

.sentrux/rules.toml

@@ -43,3 +43,23 @@ reason = "api-shape-helpers is a leaf layer; it must not depend on anything abov
 from = "packages/agent/src/lib/*"
 to = "packages/agent/src/inner-loop/*"
 reason = "lib is a utility layer; it must not depend on the inner-loop entry point."
+
+[[boundaries]]
+from = "packages/agent/src/inner-loop/*"
+to = "packages/agent/src/mcp/*"
+reason = "The core agent loop must not load the optional MCP integration."
+
+[[boundaries]]
+from = "packages/agent/src/lib/*"
+to = "packages/agent/src/mcp/*"
+reason = "Core agent utilities must not load the optional MCP integration."
+
+[[boundaries]]
+from = "packages/agent/src/api-shape-helpers/*"
+to = "packages/agent/src/mcp/*"
+reason = "Leaf API-shape definitions must remain independent of optional MCP support."
+
+[[boundaries]]
+from = "packages/agent/src/mcp/*"
+to = "packages/agent/src/inner-loop/*"
+reason = "MCP wraps public tool primitives and must not depend on the model loop."

README.md

@@ -8,7 +8,8 @@ Monorepo for the OpenRouter TypeScript agent ecosystem.
 
 | Package | Path | Description |
 | --- | --- | --- |
-| [`@openrouter/agent`](./packages/agent) | `packages/agent` | Agent toolkit for building AI applications with OpenRouter — tool orchestration, streaming, multi-turn conversations, and format compatibility. |
+| [`@openrouter/agent`](./packages/agent) | `packages/agent` | Agent toolkit with optional `@openrouter/agent/tool-set` and `@openrouter/agent/mcp` subpaths. |
+| [`@openrouter/mcp`](./packages/mcp) | `packages/mcp` | Compatibility facade for the canonical `@openrouter/agent/mcp` integration. |
 
 ## Development
 

package.json

@@ -11,6 +11,7 @@
     "lint": "turbo run lint",
     "lint:fix": "biome check --write packages/*/src packages/*/tests",
     "typecheck": "turbo run typecheck",
+    "verify:packages": "node scripts/verify-package-boundaries.mjs",
     "changeset": "changeset",
     "version": "changeset version && turbo run gen:version",
     "prepare": "husky"