Merge origin/main: resolve replay-buffer, correlated-event and OpenUI conflicts

Author: LukasParke

.changeset/approval-gate-fixes.md

@@ -0,0 +1,34 @@
+---
+'@openrouter/agent': patch
+---
+
+Fix two ways the tool-approval gate could be bypassed.
+
+**`allowFinalResponse` executed pending tool calls with no approval check.** When a `stopWhen` condition halted the loop on a turn that still carried tool calls, the final-response path ran those calls directly — skipping the approval gate the normal loop applies on every round. A tool marked `requireApproval: true` (or gated by a predicate) would execute unguarded, and because the `PermissionRequest` hook's deny bookkeeping lives inside the approval check, hook-based `deny` never fired on this path either. That path now runs the same check as the in-loop call sites, so the run pauses with `status: 'awaiting_approval'` and the gated calls on `pendingToolCalls` instead of executing them.
+
+**Function-based `requireApproval` received unvalidated arguments.** Tool-level and call-level predicates were called with the raw JSON-parsed tool arguments, while `execute` receives the arguments *after* the tool's Zod `inputSchema` runs. Any default, coercion, or transform in the schema made them disagree — e.g. with `inputSchema: z.object({ dangerous: z.boolean().default(true) })`, a model emitting `{}` showed a predicate `dangerous: undefined` (no approval required) and then executed with `dangerous: true`. Predicates now see a parsed copy, so they decide on exactly what `execute` will receive without mutating the original executable call or parsing transformed output a second time. `PreToolUse` now runs before every auto-resolvable call is partitioned, so approval hooks and persisted pending calls see its effective arguments. Pending calls record an additive marker when preparation ran, preventing a resumed `ModelResult` from applying the hook twice while legacy state without the marker retains its prior behavior. Call-level checks remain unconditional and receive raw arguments when parsing fails; tool-level checks fail closed when schema parsing fails because a hook may later repair the input.
+
+**Duplicate approval prompts for the same tool call.** The approval gate could run more than once over the same response — e.g. the pre-loop check plus the post-loop `allowFinalResponse` gate when a stop condition fired on the first iteration — re-emitting the `PermissionRequest` hook and re-running `requireApproval` predicates for calls that were already resolved. Each call occurrence in a response is now gated at most once per run, including responses containing duplicate call IDs and arguments.
+
+```ts
+import { z } from 'zod/v4';
+import { tool, type PendingToolCall } from '@openrouter/agent';
+
+const deploy = tool({
+  name: 'deploy',
+  inputSchema: z.object({
+    environment: z.enum(['staging', 'production']).default('production'),
+  }),
+  requireApproval: ({ environment }) => environment === 'production',
+  execute: async ({ environment }) => deployEnvironment(environment),
+});
+
+// `requireApproval` sees the normalized default: { environment: 'production' }.
+// Persist this additive marker when PreToolUse already produced effective args.
+const pending: PendingToolCall<typeof deploy> = {
+  id: 'call_deploy',
+  name: 'deploy',
+  arguments: { environment: 'production' },
+  preToolUseApplied: true,
+};
+```

.changeset/quiet-replay-streams.md

@@ -0,0 +1,16 @@
+---
+'@openrouter/agent': minor
+---
+
+Add opt-in replay compaction and terminal response-event handling for streamed model calls.
+
+```ts
+import { callModel } from '@openrouter/agent';
+
+const result = callModel(client, {
+  model: 'openai/gpt-4o',
+  input: 'Summarize this document.',
+  // Retain only the history needed by currently attached consumers.
+  streamReplay: 'active-consumers',
+});
+```

.changeset/reusable-stream-subpath-export.md

@@ -0,0 +1,5 @@
+---
+"@openrouter/agent": patch
+---
+
+Add a `./reusable-stream` subpath export so consumers can import `ReusableReadableStream` directly (`@openrouter/agent/reusable-stream`) instead of going through the root barrel or patching the package. Mirrors the existing `./tool-event-broadcaster` entry; both replay classes are the units consumers need when asserting stream-retention behavior against the published package.

.changeset/tool-subpath-startup-cost.md

@@ -0,0 +1,7 @@
+---
+"@openrouter/agent": patch
+---
+
+Remove the runtime `@openrouter/sdk/models` import from `turn-context.ts`. The namespace import existed only to read `EasyInputMessageRoleUser.User` (the string `'user'`), but it made every consumer that statically imports `@openrouter/agent/tool` (via `agent-tool` → `conversation-state` → `turn-context`) evaluate the entire Speakeasy models barrel — hundreds of modules of top-level Zod schema construction — at module load. On Cloudflare Workers this added ~200ms of startup CPU per worker and pushed large workers past the 1s script-validation ceiling (error 10021).
+
+The import is now type-only (erased at compile time) and the role literal is inlined, keeping behavior identical. A new unit test walks the static runtime import graph of the hot subpaths (`/tool`, `/tool-types`, `/stop-conditions`) and fails if any of them ever reaches `@openrouter/sdk` at runtime again.

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

packages/agent/CHANGELOG.md

@@ -1,5 +1,108 @@
 # @openrouter/agent
 
+## 0.10.0
+
+### Minor Changes
+
+- [#102](https://github.com/OpenRouterTeam/typescript-agent/pull/102) [`787cbf8`](https://github.com/OpenRouterTeam/typescript-agent/commit/787cbf8b22bf2b8071e81e2dbf84ecd871a5e824) Thanks [@LukasParke](https://github.com/LukasParke)! - 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.
+
+- [#31](https://github.com/OpenRouterTeam/typescript-agent/pull/31) [`8d2ed61`](https://github.com/OpenRouterTeam/typescript-agent/commit/8d2ed61964aa063936763c7b80f6b5bf389fa144) Thanks [@mattapperson](https://github.com/mattapperson)! - 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 { z } from "zod/v4";
+
+  type AppContext = { accountId: string };
+
+  // Curried form preserves the literal name for correlated tool event types.
+  const listOrders = tool<AppContext>()({
+    name: "list_orders",
+    inputSchema: z.object({}),
+    execute: async (_params, ctx) => ({
+      accountId: ctx?.shared.accountId,
+      orders: [],
+    }),
+  });
+  // override the default `server:${type}` id
+  const search = serverTool(
+    { type: "web_search_2025_08_26" },
+    { id: "public_search" }
+  );
+
+  const toolSet = createToolSet({
+    tools: [listOrders, search] as const,
+  }).deactivate("list_orders");
+
+  const client = new OpenRouter({ apiKey: process.env["OPENROUTER_API_KEY"] });
+  const resolved = toolSet.resolve();
+
+  // resolved.callModel is `{ tools, activeTools }` — spread it straight in
+  const result = callModel(client, {
+    model: "openai/gpt-4o-mini",
+    input: "Search for OpenRouter pricing.",
+    ...resolved.callModel,
+  });
+  ```
+
+- [#114](https://github.com/OpenRouterTeam/typescript-agent/pull/114) [`66d7232`](https://github.com/OpenRouterTeam/typescript-agent/commit/66d7232d53d9881c5842c77f8bc342314724bf3b) Thanks [@mattapperson](https://github.com/mattapperson)! - Add `toolChoice` to `nextTurnParams`, so a tool can change which tools the model may call on the following turn without touching the `tools` array.
+
+  This is what a tool-search tool needs: declare every tool up front, keep the not-yet-needed ones out of reach behind an `allowed_tools` choice, and widen that choice as the model discovers what it wants. Because `tools` is byte-identical across turns, the provider's prompt-cache prefix survives — which is the whole reason to withhold tools rather than send them all.
+
+  ```ts
+  import { callModel, OpenRouter, tool } from "@openrouter/agent";
+  import { z } from "zod/v4";
+
+  const allowed = (names: string[]) => ({
+    type: "allowed_tools" as const,
+    mode: "auto" as const,
+    tools: names.map((name) => ({ type: "function", name })),
+  });
+
+  const toolSearch = tool({
+    name: "tool_search",
+    inputSchema: z.object({ pattern: z.string() }),
+    execute: ({ pattern }) => findMatchingToolNames(pattern),
+    nextTurnParams: {
+      // Append, never rebuild: dropping a name revokes a tool the model may
+      // already have used, and reordering churns the request for nothing.
+      toolChoice: ({ pattern }, context) =>
+        allowed([
+          ...namesIn(context.toolChoice),
+          ...findMatchingToolNames(pattern),
+        ]),
+    },
+  });
+
+  const client = new OpenRouter({ apiKey: process.env["OPENROUTER_API_KEY"] });
+
+  const result = callModel(client, {
+    model: "openai/gpt-4o-mini",
+    input: "What is the weather in Tokyo?",
+    tools: [toolSearch, getWeather, sendEmail, listRepos],
+    // Only the search tool is reachable until it finds something.
+    toolChoice: allowed(["tool_search"]),
+  });
+  ```
+
 ## 0.9.0
 
 ### Minor Changes