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

.changeset/agent-mcp-subpath.md

@@ -0,0 +1,24 @@
+---
+"@openrouter/agent": minor
+"@openrouter/mcp": minor
+---
+
+Add the full MCP integration under the canonical `@openrouter/agent/mcp` subpath. `@modelcontextprotocol/client` 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/client` 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.
+
+The `@openrouter/mcp` facade continues to install `@modelcontextprotocol/client` transitively for backward compatibility; only direct `@openrouter/agent/mcp` users need to add the optional peer explicitly.

.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';
 
 type AppContext = { accountId: string };

.github/workflows/ci.yaml

@@ -94,6 +94,25 @@ jobs:
           if-no-files-found: ignore
           retention-days: 14
 
+  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:
@@ -166,7 +185,7 @@ jobs:
   ci-status:
     name: CI status
     if: always()
-    needs: [lint, typecheck, unit-tests, e2e-tests, structural-gate]
+    needs: [lint, typecheck, unit-tests, e2e-tests, structural-gate, package-boundaries]
     runs-on: ubuntu-latest
     steps:
       - name: Verify all checks passed
@@ -177,6 +196,7 @@ jobs:
             unit-tests=${{ needs.unit-tests.result }}
             e2e-tests=${{ needs.e2e-tests.result }}
             structural-gate=${{ needs.structural-gate.result }}
+            package-boundaries=${{ needs.package-boundaries.result }}
         run: |
           failed=0
           for entry in $RESULTS; do

.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"