feat(agent-tool-set) by mattapperson · Pull Request #31 · OpenRouterTeam/typescript-agent

mattapperson · 2026-04-20T18:44:41Z

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

Adds a new workspace package with declarative activate/deactivate/ activateWhen/deactivateWhen for tools, with predicates that receive the SDK's ConversationState and typed shared context. Also adds an `activeTools?: readonly string[]` option to callModel so inferTools() output can be spread directly into a request. Port of ai-tool-set v1.0.0 (MIT (C) zirkelc).

Drops the record-mapping InferToolSet and its InferActiveTools / InferInactiveTools aliases (faithful-port artifacts without true partition narrowing). The streaming-events discriminated union takes the InferToolSet name.

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.

…er and buildToolsMap Addresses review feedback on PR #31 after rebasing onto current main (PR #30 widened `Tool` to `ClientTool | ServerToolBase`). - call-model.ts: filter keeps server tools unconditionally; name matching only applies to client tools, preventing `t.function.name` access on `ServerToolBase`. - tool-set.ts: `buildToolsMap` skips server tools since they have no name to activate by; `createToolSet` remains client-tool-only while accepting mixed arrays.

mattapperson

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

Addresses review feedback on PR #31: - Server tools are no longer silently dropped. ToolSet now tracks the full ordered list separately from the client-tool name index, so `.tools` and `.inferTools()` return both client and server tools. Server tools are always active (no name to filter by) and never appear in the `activeTools` list returned by `inferTools()`. - `createToolSet` now exposes the `TShared` generic (`createToolSet<T, TShared>`), so predicates type `context` as the user's context shape instead of `Record<string, unknown>`.

mattapperson

reviewed, no issues found

…er and buildToolsMap Addresses review feedback on PR #31 after rebasing onto current main (PR #30 widened `Tool` to `ClientTool | ServerToolBase`). - call-model.ts: filter keeps server tools unconditionally; name matching only applies to client tools, preventing `t.function.name` access on `ServerToolBase`. - tool-set.ts: `buildToolsMap` skips server tools since they have no name to activate by; `createToolSet` remains client-tool-only while accepting mixed arrays.

Addresses review feedback on PR #31: - Server tools are no longer silently dropped. ToolSet now tracks the full ordered list separately from the client-tool name index, so `.tools` and `.inferTools()` return both client and server tools. Server tools are always active (no name to filter by) and never appear in the `activeTools` list returned by `inferTools()`. - `createToolSet` now exposes the `TShared` generic (`createToolSet<T, TShared>`), so predicates type `context` as the user's context shape instead of `Record<string, unknown>`.

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.

…pshots Add a compile-time enabled/disabled/conditional ID partition on ToolSet, exhaustive resolve()/resolveSituation() snapshots with statusByTool, and declarative defineSituations. Server tools get stable IDs (default server:${type}, overridable via serverTool options) so they participate in activation. InferToolSet now aliases CorrelatedToolEventUnion.

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 · 2026-07-23T19:28:58Z

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.

cortex-github-agent · 2026-08-04T14:52:21Z