feat(agent-tool-set)

[mattapperson]

Summary

• Adds @openrouter/agent-tool-set — a declarative, immutable-by-default ToolSet for activating/deactivating tools with static rules, state/context-aware predicates, and named "situations" (fixed overlay configs), backed by a compile-time three-way partition (enabled / disabled / conditional) of stable tool-set IDs.
• Adds a new activeTools?: readonly string[] option to @openrouter/agent's callModel, so a ToolSet snapshot's callModel sub-object can be spread directly into a request. Filtering is applied once, before both API conversion and executor/ModelResult registration, so excluded tools are neither advertised to the model nor callable. Server tools always bypass this filter.
• Adds stable ids to server tools (ServerToolBase.id, default server:${config.type}, overridable via serverTool(config, { id })) so they can participate in tool-set activation and identity alongside client tools (function.name).
• Adds "correlated" tool event types (CorrelatedToolResultEvent, CorrelatedToolPreliminaryResultEvent, CorrelatedToolEventUnion, CorrelatedResponseStreamEvent, CorrelatedToolStreamEvent) that let consumers narrow event.toolName to recover the exact per-tool result/event payload type for a given tools tuple. The existing wide event shapes (ResponseStreamEvent, ToolResultEvent, ToolPreliminaryResultEvent, ToolStreamEvent) are unchanged in shape but now carry an optional toolName field and a TName generic for back-compat.

Public API (@openrouter/agent-tool-set)

• createToolSet<T, TShared?>({ tools, mutable? }) — build a set from an ordered tool array. Duplicate tool-set IDs throw at construction. Immutable by default; mutable: true mutates in place (partition type parameters may widen, but runtime state stays exact).
• .tools — full tools tuple in construction order, regardless of activation.
• .activate(id | id[]) / .deactivate(id | id[]) — static flip, last-call-wins, accepts client names and server IDs.
• .activateWhen(id, predicate) / .activateWhen({ [id]: predicate }) and .deactivateWhen(...) (same two call shapes) — conditional activation driven by { state?, context? }; moves the ID into the compile-time conditional partition.
• .defineSituations({ [name]: { enabled?, disabled?, conditional? } }) — named declarative overlays; unmentioned IDs keep the base partition state. Unknown/duplicate/conflicting IDs within one situation throw.
• .resolve(input?) → ResolvedToolSnapshot — resolve against the base partition (see below).
• .resolveSituation(name, input?) → ResolvedToolSnapshot — resolve with a named situation's overlay applied first. Fully static situations produce an exact tool tuple at compile time.
• .inferTools(input?) — back-compat alias for .resolve(); returns { tools, activeTools, enabled, disabled, statusByTool } (not just { tools, activeTools }). Prefer .resolve() in new code.
• .clone({ mutable? }) — copy state, optionally flipping mutability.
• Inference utilities: InferAllIds, InferEnabledIds, InferDisabledIds, InferConditionalIds (compile-time ID sets recovered from a ToolSet instance), and InferToolSet<T> (alias of the agent's CorrelatedToolEventUnion<T>).
• Supporting types: ActivationInput, ActivationPredicate, Partition/EmptyPartition/InitialPartition/ActivatePartition/DeactivatePartition/ConditionalPartition/ApplySituationPartition, SituationConfig/SituationMap/SituationNames/SituationConditionalRule/InferSituationEntry/InferSituationMap/EmptySituations, StatusReason/ToolStatusEntry/StatusByToolMap, ResolvedToolSnapshot, ToolSetLike, identity/filter helpers (ClientToolName, ClientToolNamesOfTuple, ServerToolIdOf, ServerToolIdsOfTuple, ToolById, ToolIdOf, ToolIdsOfTuple, FilterToolsByIds).

Server tool IDs

Every tool gets a stable tool-set ID: client tools use function.name; server tools default to server:${config.type} and can be overridden with serverTool(config, { id: 'server:public_search' }). serverTool() throws if options.id === ''. IDs are namespace-prefixed so a server tool can never collide with a client function name, and duplicate IDs across the tuple throw at createToolSet construction.

resolve / resolveSituation / partitions

Partition tracks every tool-set ID in exactly one of three compile-time buckets — enabled, disabled, conditional — refined as .activate/.deactivate (static) and .activateWhen/.deactivateWhen (conditional) are called; .defineSituations + .resolveSituation overlay a named, fixed configuration onto that base partition (ApplySituationPartition). When a partition is purely static (no conditional IDs), .resolve()/.resolveSituation() return an exact active-tool tuple at compile time; conditional IDs widen the compile-time upper bound to enabled | conditional, while the runtime snapshot (tools, activeTools, enabled, disabled, statusByTool) is always exhaustive and exact — every known ID appears in statusByTool with its resolved { enabled, reason, directive?, predicate? }.

Spread-safe .callModel

ResolvedToolSnapshot includes a nested callModel: { tools, activeTools } sub-object in addition to the top-level tools/activeTools/enabled/disabled/statusByTool fields. Spreading ...snapshot.callModel into callModel(client, { ...snapshot.callModel, model, input }) passes only tools/activeTools; spreading the top-level snapshot instead would leak enabled/disabled/statusByTool as unrecognized callModel request fields. This is the fix for the metadata-leak footgun.

Agent changes (@openrouter/agent)

• BaseCallModelInput gains activeTools?: readonly string[], listed in clientOnlyFields. callModel computes the filtered tool list once and uses it for both convertToolsToAPIFormat and the tools passed toward ModelResult/the executor, so excluded tools are neither advertised to the model nor executable. The filter predicate short-circuits true for server tools (isServerTool(t) || activeSet.has(t.function.name)), so server tools always remain active regardless of activeTools.
• ServerToolBase gains an id: string field; serverTool<T, TId>(config, options?: { id?: TId }) accepts an optional id override, defaulting to server:${config.type} and throwing on an empty-string override.
• New correlated event types in tool-types.ts: CorrelatedToolPreliminaryResultEvent, CorrelatedToolResultEvent, CorrelatedToolEventUnion, CorrelatedResponseStreamEvent, CorrelatedToolStreamEvent. ToolPreliminaryResultEvent, ToolResultEvent, ResponseStreamEvent, ToolStreamEvent, and ChatStreamEvent each gain a TName extends string = string generic and (where applicable) a toolName: TName field, preserving the existing wide/untyped shapes as the default.

API example

import { OpenRouter, tool, serverTool, callModel } from '@openrouter/agent';
import { createToolSet } from '@openrouter/agent-tool-set';
import { z } from 'zod/v4';

type AppContext = { isAuthenticated: boolean; isAdmin: boolean };

const listOrders = tool({ name: 'list_orders', inputSchema: z.object({}), execute: async () => ({ orders: [] }) });
const cancelOrder = tool({ name: 'cancel_order', inputSchema: z.object({ id: z.string() }), execute: async () => ({ ok: true }) });
const login = tool({ name: 'login', inputSchema: z.object({}), execute: async () => ({ token: '…' }) });
const webSearch = serverTool({ type: 'web_search_2025_08_26' }); // id defaults to 'server:web_search_2025_08_26'

const toolSet = createToolSet<[typeof listOrders, typeof cancelOrder, typeof login, typeof webSearch], AppContext>({
  tools: [listOrders, cancelOrder, login, webSearch],
})
  .deactivate('cancel_order')
  .activateWhen('list_orders', ({ context }) => context?.isAuthenticated === true)
  .defineSituations({
    guest: { enabled: ['login', 'server:web_search_2025_08_26'], disabled: ['list_orders', 'cancel_order'] },
    authenticated: {
      enabled: ['list_orders', 'server:web_search_2025_08_26'],
      disabled: ['login'],
      conditional: { cancel_order: ({ context }) => context?.isAdmin === true },
    },
  });

const authenticated = toolSet.resolveSituation('authenticated', {
  context: { isAuthenticated: true, isAdmin: false },
});
// authenticated.tools / .activeTools / .enabled / .disabled / .statusByTool are exhaustive.

const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const result = await callModel(client, {
  model: 'openai/gpt-4o-mini',
  input: 'List my orders.',
  ...authenticated.callModel, // spread-safe: only { tools, activeTools }, no metadata leaks in
});

Test plan

• pnpm build — both packages compile
• pnpm typecheck — strict mode clean
• pnpm test — 775 unit tests pass (660 across 54 files in @openrouter/agent + 41 across 1 file in @openrouter/agent-tool-set)
  • packages/agent-tool-set/src/tool-set.test.ts — 41 cases across createToolSet, activate/deactivate, activateWhen/deactivateWhen, last-call-wins semantics, immutability vs mutability, clone, resolve/inferTools input shapes, exhaustive statusByTool snapshots, compile-time partition inference, server tools, defineSituations/resolveSituation, the TShared generic, InferToolSet/event narrowing, and the callModel-oriented spread shape.
  • packages/agent/tests/unit/call-model-active-tools.test.ts — cases verifying the outbound request body via a capturing HTTPClient, including that server tools bypass the activeTools filter.
• pnpm lint — Biome clean
• pnpm changeset status — both packages bumped minor

Release

.changeset/agent-tool-set.md — minor bump for both @openrouter/agent-tool-set (0.1.0 initial release) and @openrouter/agent (new activeTools option, server tool id, correlated event types).

---

[robert-j-y]

needs a rebase onto the current turborepo-migration — PR #30 landed and widened Tool to ClientTool | ServerToolBase. After rebase, two sites break:

1. packages/agent/src/inner-loop/call-model.ts:102 — produces TS2339: Property 'function' does not exist on type 'Tool'. Property 'function' does not exist on type 'ServerToolBase'. at compile time, and TypeError: Cannot read properties of undefined (reading 'name') at runtime if any serverTool(...) is in the array. Change:

const filteredTools = activeSet ? tools?.filter((t) => activeSet.has(t.function.name)) : tools;

to:

const filteredTools = activeSet
  ? tools?.filter((t) => isServerTool(t) || activeSet.has(t.function.name))
  : tools;

(import isServerTool from ../lib/tool-types.js)

2. packages/agent-tool-set/src/tool-set.ts buildToolsMap (lines 32–42) — same root cause. Compile error doesn't surface yet only because agent-tool-set resolves @openrouter/agent through the stale compiled .d.ts; runtime t.function.name still throws on any server tool passed to createToolSet. Change:

for (const t of tools) {
  const name = t.function.name;
  if (map.has(name)) throw new Error(`Duplicate tool name: "${name}"`);
  map.set(name, t);
}

to:

for (const t of tools) {
  if (isServerTool(t)) continue;
  const name = t.function.name;
  if (map.has(name)) throw new Error(`Duplicate tool name: "${name}"`);
  map.set(name, t);
}

(import isServerTool from @openrouter/agent)

Server tools have no name to activate by, so skipping them keeps ToolSet client-tool-only while still allowing users to pass a mixed array through.

3. PR description: InferActiveTools and InferInactiveTools are listed under "Types:" but are not exported from packages/agent-tool-set/src/index.ts. Remove or add.

[mattapperson]

Two concerns on the new ToolSet surface worth a look before merge.

[mattapperson]

reviewed, no issues found

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[cortex-github-agent]

Summary

Re-reviewed the head commit (769c98c) for the toolkits branch. The diff is functionally the same shape as previously assessed: @openrouter/agent-tool-set (new package) plus the activeTools filter wired into callModel before convertToolsToAPIFormat and before the executor's tools list (packages/agent/src/inner-loop/call-model.ts:99-119). I traced the filter path, isServerTool short-circuiting, and the last-call-wins activation resolver in packages/agent-tool-set/src/tool-set.ts, and found no correctness or security regressions. No functional changes since the prior pass were evident in this diff, so I'm treating any earlier design-level concerns as still open (see findings) rather than newly introduced or resolved, since neither the filtering logic nor the ToolSet activation semantics changed.

Findings (3)

🟡 minor · packages/agent/src/lib/async-params.ts:64-70
activeTools is typed as plain readonly string[] with no constraint against the tool names actually present in TTools. A typo (or a stale name after a tool is renamed/removed) silently drops that tool from the request instead of erroring — confirmed intentional by the 'silently ignores unknown activeTools names' test in call-model-active-tools.test.ts. Worth at least a dev-mode warning when a name in activeTools matches nothing in tools, since this is the kind of bug that fails silently rather than loudly.

🟡 minor · packages/agent-tool-set/src/tool-set.ts:214-226
inferTools()/activate()/deactivate() only validate tool names against #clientToolsByName, so a caller mixing a ToolSet's activeTools output with an unrelated/mutated tools array in callModel gets no cross-check that the two lists actually correspond — the two must be kept in sync by convention only. Not a bug given current usage (README pattern spreads {tools, activeTools} together), but worth a doc callout for anyone splitting the two fields.

⚪ nit · packages/agent-tool-set/package.json:14
License is declared Apache-2.0 for a package whose core logic is a port of MIT-licensed ai-tool-set; THIRD_PARTY_NOTICES.md covers attribution correctly, so this is fine as-is, just flagging for legal sign-off consistency with any other ported code in the repo.

[cortex-github-agent]

Summary

This head commit (cd8c1dd) is functionally identical to the previously-reviewed commit; the only diff is packages/agent-tool-set/package.json dropping the test:e2e script entry (vitest.config.ts still defines the e2e project via --project e2e, just no longer exposed as a top-level pnpm script). No source, type, or test logic changed in tool-set.ts, types.ts, call-model.ts, model-result.ts, tool-types.ts, or tool.ts since my last approval.

Findings (1)

🟡 minor · packages/agent-tool-set/package.json:34
test:e2e script was removed while vitest.config.ts still declares an 'e2e' vitest project (tests/e2e/**/*.test.ts). If any e2e tests are ever added to this package, there's no longer a documented entrypoint to run them via pnpm — CI/docs relying on pnpm --filter agent-tool-set test:e2e would break silently. Carried forward from my prior review: the unenforced correspondence between a ToolSet's activeTools output and an externally-supplied tools array, and the silent no-op on unknown activeTools names in callModel, both remain open as advisory (non-blocking) points.

[LukasParke]

Addressed the latest review feedback in 2f5ee6e:

• removed the stale e2e Vitest project from @openrouter/agent-tool-set, matching the package’s lack of an e2e script/suite
• documented that snapshot tools and activeTools should stay coupled via .callModel
• documented the established behavior that unknown activeTools names are ignored

Fresh forced lint, typecheck, unit tests, build, and root e2e all pass (98 agent e2e tests; MCP conditional tests skipped as designed).

[cortex-github-agent]

Summary

This head commit (2f5ee6e) makes only two changes since my last-reviewed commit: it removes the now-unused e2e vitest project block from packages/agent-tool-set/vitest.config.ts, and it adds two Notes bullets to the README documenting the tools/activeTools correspondence caveat and callModel's silent-ignore-of-unknown-names behavior. All source, type, and test files are otherwise byte-identical to the previously approved state.

Findings (1)

🟡 minor · packages/agent-tool-set/README.md:207-209
RESOLVED (as documentation): the two Notes bullets now explicitly call out that callModel cannot verify activeTools against an unrelated tools array, and that unknown activeTools names are silently ignored — directly addressing my prior advisory findings. The underlying runtime behavior is unchanged (still no cross-check), but callers are now warned and pointed at the safe .callModel spread pattern, which is the right mitigation for a library-level API like this.

[devin-ai-integration]

Devin Review found 0 new potential issues.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: --- context after this hunk ---). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: File: packages/agent/src/lib/async-params.ts). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: File: packages/agent/src/lib/async-params.ts). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: --- context after this hunk ---). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: [... rest of file omitted ...]). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: File: packages/agent/src/lib/async-params.ts). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: --- context after this hunk ---). Manual update needed; label cortex-merge-conflict added.

[cortex-github-agent]

⚠️ cortex keep-fresh: could not auto-merge packages/agent/src/lib/async-params.ts (resolver produced a line not present on any side: File: packages/agent/src/lib/async-params.ts). Manual update needed; label cortex-merge-conflict added.

Agent: Dismissing stale automated review. The cited Biome failures are fixed and current lint/typecheck/tests pass; the UnifiedToolFunction TName suggestion is implemented with semantically checked unified-tool narrowing coverage.