Skip to content

Tool groups, call state, stats and app-wide tools - #2088

Merged
tschellenbach merged 16 commits into
mainfrom
tool-groups
Nov 19, 2026
Merged

tschellenbach merged 16 commits into
mainfrom
tool-groups

Conversation

@tschellenbach

Copy link
Copy Markdown
Member

Why

Customers deciding how to load a tool had no numbers to go on, an agent offered every tool in full every turn, a client could not show what a call was doing, and a tool used by several agents had to be registered once per agent. This PR does all five tool changes together, since they share the session, the spec and the generated clients, and stats and app-wide hosting build on tool groups.

How it works

agent.yaml tools:  - name: weather
                     loading: full | summary | deferred
                     tools: [weather_lookup]
        |
        v
session offers a tool only if a group names it
 ├─ declared by the caller            (400 tool_not_configured if no group)
 ├─ hosted by a worker for the agent  (agent_id)
 └─ hosted for every agent            (every_agent: true, Python client.tools)
        |
        v
each call  -> tool_call.started / progress / finished on the session socket
           -> recorded with loading, definition and summary tokens
        |
        v
GET /v1/stats/agents?agent=<config id>   (Go: client.Agent("x").Stats)
Change Result Test that proves it
Tool groups with loading deferred tools load through search_tool/load_tool; the old tools: mapping is a 400 progressive_tools_test.go, deferred_tools_test.go, tool_groups_migration_test.go
Tool call state Every SDK keeps each call's ToolCallState; clients no longer run a run: false call tool_call_state_test.go, sdks/go/stream/tool_calls_test.go, sdks/js/tests/tool-calls.test.ts, ToolCallStateTests.swift
No update/say on a call Removed in every SDK; the router still takes tool_update from released SDKs each SDK's tool call tests
Tool stats per agent sessions, avg_turns, and per tool session_share, avg_turns_before_use, loading, definition_tokens, summary_tokens, surviving output retention TestToolUsageOfOneAgentIsOutOfThatAgentsSessions, TestTurnsBeforeAToolIsUsedAreTheConversationsOwn, TestARedactedCallStillReportsWhatItAndItsToolCost, TestAnAgentsStatsAreReadForItsConfigOverTheWindow
Tools hosted for every agent Offered only where the config's tool groups name them; an agent's own tool wins; no agent id and no every_agent is still refused TestAToolHostedForEveryAgentIsOfferedWhereAToolGroupNamesIt, TestAnAgentsOwnHostedToolWinsOverOneHostedForEveryAgent, TestToolsHostedForEveryAgentAreTheApps, test_a_clients_tools_are_hosted_for_every_agent
Before After
Registering one tool for three agents agent.register three times, three workers' offers client.tools.register once, enabled per agent in agent.yaml
Reading tool stats Customer-wide, raw endpoint Per agent, Agent.Stats(ctx, from, to) in Go

Changes

  • Router: tool groups and deferred loading, an additive migration for tool_groups, tool call state frames, tool stats queries and API, every_agent hosting.
  • SDKs: call state and the update/say removal in all of them; tools: as groups in Go, Python and JavaScript; Go Agent.Stats; Python Client.tools and Dispatch.host(client). The SDK skill lists what the other SDKs still need.
  • Examples: travel_support, travel_support_js, and Go text and voice agents using tool groups.

Validation

  • dev.py check: ruff, mypy and 2239 tests pass. One failure, test_backend::test_a_user_token_cannot_be_minted_without_a_secret, is in files this PR does not touch and comes from the local environment supplying a secret.
  • Go: router build and vet, the store suite, the API dispatch and stats suites against Postgres and Redis, session, dispatch and node; the Go SDK build, vet and client tests.
  • Removing the config check from every-agent hosting fails TestAToolHostedForEveryAgentIsOfferedWhereAToolGroupNamesIt; removing the rewound_at filter fails the turns test.
  • go run ./cmd/openapi leaves the committed spec unchanged. Swift's generator was not run locally (not installed), so its generated types are unverified.

…sting

agent.yaml tools: is a list of groups loaded full, summary or deferred. Every SDK gets tool call state events and drops a call's update/say. getAgentStats reports per-agent tool stats, read with Go's Agent.Stats. A worker can host tools for every agent (Python client.tools), offered where a tool group names them.

Co-authored-by: Cursor <cursoragent@cursor.com>
tschellenbach and others added 2 commits November 18, 2026 16:56
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Walkthrough

The change replaces agent-wide progressive tool settings with named tool groups and adds full, summary, and deferred loading modes. It adds tool-call lifecycle frames, SDK state accessors, app-wide hosted tools, and expanded agent and tool statistics. Tool-call update and say methods are removed across several SDKs. The change also adds Python and JavaScript travel-support examples.

Merge Risk: Moderate · up to b759d

The tool groups, call-state, stats and app-wide hosting changes mostly work as designed. Several defects should be fixed before merge: tool statistics miscount turn positions, same-named tools can run the wrong handler in Python, concurrent deferred tool loading can drop a tool, existing no-retention settings may not carry over to built-in tools, and some examples fail on a fresh setup. The migration rollback also deletes configured tool groups.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

ast-grep (0.51.1)

ast-grep (0.51.1) exceeded its 180-second time budget. Findings from completed work are retained; remaining checks are incomplete.

sdks/go/acceleration/generated.go

ast-grep was terminated on this file

golangci-lint (2.15.0)

golangci-lint (2.15.0) exceeded its 180-second time budget. Findings from completed work are retained; remaining checks are incomplete.

SkillSpector (2.12.0)

SkillSpector batch scan produced no output

SwiftLint (0.65.1)

SwiftLint (0.65.1) exceeded its 180-second time budget. Findings from completed work are retained; remaining checks are incomplete.

sdks/swift/core/Sources/StreamAgents/AgentEvent.swift

SwiftLint execution failed

sdks/swift/core/Sources/StreamAgents/AgentSession.swift

SwiftLint execution failed

sdks/swift/core/Tests/StreamAgentsTests/ToolCallStateTests.swift

SwiftLint execution failed

PMD (7.29.0)

PMD (7.29.0) exceeded its 180-second time budget. Findings from completed work are retained; remaining checks are incomplete.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 11

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

Minor comments: 32

acceleration/internal/api/server.go: 1

2093-2093: Minor · Functional Correctness · Quick win

Return operational errors from the config lookup instead of mapping them to an unknown config.

The config check in getAgentStats converts every error from s.configs.AgentConfig into errUnknownConfig. The store returns ErrNoAgentConfig only for a missing config. A database failure or a canceled context returns a different error. The handler then reports an existing config as unknown and never reaches the statistics queries that would have returned the real error.

Map only the missing-config sentinel to errUnknownConfig, and return any other error unchanged:

Suggested fix

 		if _, err := s.configs.AgentConfig(ctx, customerID, configID); err != nil {
-			return nil, errUnknownConfig
+			if errors.Is(err, store.ErrNoAgentConfig) {
+				return nil, errUnknownConfig
+			}
+			return nil, err
 		}
acceleration/internal/agent/deferred_tools.go: 2

110-110: Minor · Functional Correctness · Quick win

Normalize restored tool names before recording them.

LoadDeferred accepts " lookup_booking " and loads lookup_booking. This loop instead records the spaces. After RestoreHistory, offeredDeferred cannot match that name, so the successfully loaded tool disappears.

Apply the same trimming and canonical-name deduplication used during loading.


82-82: Minor · Stability & Availability · Quick win

Serialize the offer publication in load so the last published offer includes every loaded tool.

load appends the new names under toolsMu, then builds the offer with availableTools() and publishes it with SetTools after the lock is released. Tool calls run in separate goroutines, so two load_tool calls can overlap. If the earlier call builds its offer before the later call appends, the earlier call can publish a stale offer last. The harness then omits the tool that the later call loaded. A repeated load of that tool returns early and does not publish again. The offer changes only at the next publication.

Hold one lock across appending the names, building availableTools(), and calling SetTools. Each publication then reflects the latest loaded set. Keep this lock order consistent with the existing toolsMu and h.mu usage.

acceleration/internal/agent/telephony.go: 1

984-984: Minor · Functional Correctness · Quick win

Apply the runnable-tool filter to deferred tools.

If ToolRunner is nil, ordinary external tools are filtered out above. Deferred external tools bypass that filter. After load_tool, the model receives a tool that always fails in callTool because no runner exists. Native mode exposes the same unavailable tool immediately.

Filter deferred definitions by the same execution prerequisites before offering them or exposing them through search and load.

acceleration/internal/api/configs_test.go: 1

360-360: Trivial · Maintainability & Code Quality · Quick win

Compare the complete groups after the update.

The PUT could change group names, tool membership or loading and still pass this length check. Those changes can disable tools or change deferred loading.

Compare *saved.Tools with *patched.Tools to prove that omitted groups remain unchanged.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

acceleration/migrations/20270102090000_agent_config_tool_groups.sql: 1

22-22: Minor · Stability & Availability · Quick win

Bound the backfill UPDATE with the same lock timeout as the column addition.

The SET LOCAL lock_timeout = '5s' covers only the ADD COLUMN block. The backfill UPDATE runs as a separate statement with no lock bound. If a concurrent transaction holds a row lock on a qualifying agent_configs row, the UPDATE waits without limit. The header says a lock wait fails the migration and the next router start retries it. This UPDATE does not follow that design, so a stalled wait can delay router startup indefinitely.

Wrap the statement in a DO block with the same bounded wait, as the earlier migrations do.

Suggested fix

+-- +goose StatementBegin
+DO $$
+BEGIN
+    SET LOCAL lock_timeout = '5s';
 UPDATE agent_configs AS config
 SET connectors = (
     SELECT jsonb_agg(
         binding
             || CASE WHEN config.progressive_tools AND NOT binding ? 'loading'
                     THEN '{"loading": "summary"}'::jsonb ELSE '{}'::jsonb END
             || CASE WHEN config.tool_output_retention <> '' AND NOT binding ? 'output_retention'
                     THEN jsonb_build_object('output_retention', config.tool_output_retention) ELSE '{}'::jsonb END
         ORDER BY position)
     FROM jsonb_array_elements(config.connectors) WITH ORDINALITY AS bound(binding, position)
 )
 WHERE (config.progressive_tools OR config.tool_output_retention <> '')
   AND jsonb_typeof(config.connectors) = 'array'
-  AND jsonb_array_length(config.connectors) > 0;
+  AND jsonb_array_length(config.connectors) > 0;
+END $$;
+-- +goose StatementEnd

Source: Coding guidelines

sdks/go/agents/agent_test.go: 1

920-920: Minor · Functional Correctness · Quick win

Assert the booking group's tool list.

If sync drops lookup_booking from booking.Tools, this test still passes. That omission prevents the group from selecting the tool. Assert that booking.Tools equals []string{"lookup_booking"}.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

acceleration/internal/session/tool_call_state.go: 5

115-115: Minor · Functional Correctness · Quick win

Retain approval decisions that arrive before ToolStarted.

A connector can publish its question and receive approval before Session.consume handles ToolStarted. The question enters early, but the allowed decision is discarded because calls[id] does not exist. The later start becomes waiting, and a successful ToolRan finishes cancelled.

Retain early decisions and apply them after the start, in event order. Add a regression for question → allow → start → successful result.


135-135: Minor · Functional Correctness · Quick win

Use the resolved approval call ID for completion.

If only call-1 waits and the model supplies a different tool_call_id, approvalLocked deliberately selects call-1. confirm then approves and runs call-1. This assignment instead uses the incorrect argument, so completion finds no state and leaves call-1 in progress indefinitely.

Carry the resolved call ID into the completion event. Preserve the normal path where the argument already names the pending call.


79-79: Minor · Functional Correctness · Quick win

Distinguish built-in confirmations from caller-owned tools.

offersConfirm withholds the built-in when a caller declares confirm_tool_call. This name-only check also hides that caller-owned tool. Its result then enters the built-in remapping branch, so watchers receive no lifecycle state for the tool.

Suppress and remap only actual built-in confirmations.


183-184: Minor · Functional Correctness · Quick win

Serialize state observation with publication.

After observe releases its mutex, another goroutine can publish a newer snapshot first. For example, the connector callback can publish progress/waiting before this goroutine publishes its earlier started/in_progress snapshot. SDKs retain the last snapshot, so they show the call as running while approval is still pending.

Serialize observation and publication across all tracker callers. Keep the existing bounded delivery mechanism.


143-144: Minor · Functional Correctness · Quick win

Record approved client tool calls in the tool-call tracker.

When a client call has no command, applyCommand returns at acceleration/internal/api/sessionws.go:486-488 before the tool-call tracker sees the decision. A tool that needs approval stays ToolCallWaiting. When its successful tool_result arrives, the tracker finishes the waiting call as ToolCallCancelled. An approved call therefore reports cancelled.

Pass the approval to the tracker on this path. The durable path already does this in DecideCommandTool through trackToolCall.

sdks/dart/stream_agents/test/core/session_test.dart: 1

459-472: Minor · Functional Correctness · Quick win

Assert stored state before sending the next lifecycle phase.

This test still passes if _apply stores only tool_call.finished. The progress handler receives events independently of toolCalls, and all map assertions inspect the finished state.

Send the phases separately. Assert the stored waiting state, then the stored in_progress state and progress text. Keep the final assertion that omitted progress is cleared.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

sdks/swift/core/Tests/StreamAgentsTests/ToolCallStateTests.swift: 1

51-57: Minor · Functional Correctness · Quick win

Check the stored started and progress states.

This test passes if AgentSession.apply stores only finished states. The progress callbacks still run, and these assertions inspect only the final stored value.

Record session.toolCalls["call-1"] inside the started and progress handlers. Assert each snapshot's status and progress text. Keep the final replacement and cancellation checks.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

sdks/dart/stream_agents/lib/src/core/agent_event.dart: 1

162-162: Minor · Stability & Availability · Quick win

Check that the duration is finite before calling toInt().

A lifecycle frame with "duration_ms":1e400 reaches this numeric branch as infinity. toInt() then throws UnsupportedError instead of using the tolerant fallback. Dart documents this behavior for nonfinite values. (api.dart.dev)

Require ms.isFinite before conversion. Keep the zero fallback for invalid values and preserve normal durations such as 300.

As per coding guidelines, “Treat everything the router, a provider or a model sends as untrusted.”

Source: Coding guidelines

sdks/dart/stream_agents/lib/src/core/agent_session.dart: 1

513-513: Minor · Functional Correctness · Quick win

Return an unmodifiable snapshot from toolCalls.

_apply stores a growable map in _toolCalls, and the public toolCalls getter returns that same map. A caller that mutates chat.toolCalls.value, for example with clear(), changes the state without notifying stream listeners. Publish an unmodifiable snapshot instead, so every change goes through the controller's setter.

Suggested fix

-      _toolCalls.value = {..._toolCalls.value, call.id: call};
+      _toolCalls.value = Map.unmodifiable({..._toolCalls.value, call.id: call});
sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/AgentSessionTest.kt: 2

233-236: Minor · Functional Correctness · Quick win

Make the ownership test reject an extra execution.

If the run=false guard is removed, all three calls can execute. If approved and here answer first, these assertions still pass; the test never checks the third response.

Test run=false separately with an approval-required tool. Subscribe before sending its frame, wait for its tool_call event, then assert that approvals is empty. Without the guard, dispatch adds the approval synchronously before that event.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions


266-267: Minor · Functional Correctness · Quick win

Wait for both independent handlers before asserting.

The finished handler can update finished before the progress handler updates progress. UNDISPATCHED establishes the initial subscription, but later resumptions use the session dispatcher. Waiting only for finished can therefore produce a false failure at Line 267. Wait with a deadline until both expected outputs are present. (kotlinlang.org)

sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/AgentSession.kt: 1

129-130: Minor · Stability & Availability · Quick win

Stop event handlers when the remote socket ends.

When the router closes the socket, start() calls stopped(). That path does not cancel these collector jobs. SharedFlow.collect does not complete normally, so the returned job remains active after the session ends. Explicit close() does not cover this path. Cancel the subscription jobs on remote termination while retaining the final call snapshots. (kotlinlang.org)

sdks/go/stream/tool_calls.go: 1

17-17: Minor · Functional Correctness · Quick win

Clear tool-call state when a pipeline starts a new session.

Leave resets the per-session added, withdrawn, and unsettled state so the next session starts clean. listeners.toolCalls is not cleared anywhere in sdks/go/stream. After Leave and a later Watch on a new session, ToolCall(id) and ToolCalls() can still return calls reported by the previous session. This contradicts the ToolCalls contract, which covers the calls "the session reported."

Clear the tool-call state at the session boundary. States from a previous session must not be returned once the next session starts. Choose the reset point so that late events from the previous watcher cannot repopulate the map after the reset. awaitHangup shows that the previous watcher can still run after Leave begins.

sdks/js/tests/tool-calls.test.ts: 1

136-136: Trivial · Maintainability & Code Quality · Quick win

Test React updates after mounting.

This assertion reads state populated before renderToString. Server rendering uses getServerSnapshot, so broken subscriptions would still pass. (react.dev)

Keep the SSR check. Add a mounted test that receives another frame and checks the updated output. Also check cleanup after unmounting. As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

sdks/dotnet/tests/GetStream.VisionAgents.Tests/AgentTests.cs: 1

352-354: Minor · Functional Correctness · Quick win

Start the cancellation timer only after the send is admitted.

The 300 ms token starts before the 32 MiB string is allocated and before SayAsync serializes it. WriteAsync checks the token at _sending.WaitAsync, before the frame is queued. If the token expires during allocation or serialization, the send throws without writing the frame. The cancellation assertion still passes, but the later frame receive fails. On a slow runner, this failure occurs without a product defect.

The test must not depend on how long allocation and serialization take. Cancel only after the send has been admitted, or otherwise keep the token from expiring before admission. The test must still show that the caller stops waiting and that the complete say frame still arrives.

sdks/js/src/react.ts: 1

33-33: Minor · Functional Correctness · Quick win

Update the handler ref only after commit.

If a transition renders session B and then suspends, this assignment installs B's handler while session A's subscription remains active. An event from A then invokes B's handler although B never committed. React permits abandoned renders and prohibits render-time ref writes for this reason. (react.dev)

Move the assignment into a commit-phase layout effect. Keep the previous handler until the new render commits. (react.dev)

Source: Linters/SAST tools

plugins/stream/vision_agents/plugins/stream/dispatch.py: 1

244-244: Minor · Functional Correctness · Quick win

Reject an empty name when hosting an agent.

Client.agent("") is permitted by the supplied constructor. Hosting that agent stores an empty ID. _host then sends every_agent: true, so unrelated agents with matching tool groups can receive its tools.

Reject an empty target.name in the agent branch. Keep the empty selector only for explicit Client hosting.

acceleration/internal/api/dispatch_test.go: 1

389-393: Minor · Functional Correctness · Quick win

Create the agent before the conflicting-selector declaration.

TestHostedToolsNeedAnAgentToBeFor never creates stream-support. Shared setup does not create it either, so the request at lines 389-393 is refused as an unknown agent when the conflict guard at dispatchws.go:410-411 is removed. The test still receives hosting_refused and passes. Create the agent with agentNamed first. The guard then decides the refusal, and removing it makes the reply hosting.

Suggested fix

 	s.Empty(tools, "an agent id left out offered the tools to every agent")
 
+	s.serverClient.agentNamed("stream-support")
 	s.Require().NoError(worker.WriteJSON(frame{
 		"type": "host_tools", "agent_id": "stream-support", "every_agent": true,
 		"tools": []frame{{"name": "investigate_sdk", "description": "Read SDK source"}},

Source: Path instructions

acceleration/internal/store/store.go: 2

1509-1509: Minor · Functional Correctness · Quick win

Select definition metadata by the call timestamp.

at comes from the tool result, not the matched tool call. If an older call finishes after a newer call, this ordering reports the older definition as the latest definition. The cross-shard merge repeats that selection.

Carry started.at as the offer timestamp and use it for metadata ordering. Keep r.at for completion-window filtering.


1499-1499: Minor · Data Integrity & Integration · Quick win

Align the session populations behind SessionShare.

The numerator and denominator count different sessions for the same window. CustomerToolUsage counts a session when one of its tool results completes in [from, to) (store.go:1499), even if the session's response started before from. CustomerTurns counts a session only when a top-level response was created in [from, to) (store.go:1613-1615). A session in the numerator but not the denominator makes share exceed 1. share does not clamp (server.go:2142-2148), and the documented range is 0 to 1 (server.go:2610).

Both queries must count the same sessions for the same window, so every session in Sessions also appears in the turn denominator. Choose a single time basis for both. The current code uses created_at for turns and r.at for tool results, so either the tool side or the turn side must change.

sdks/ruby/test/tool_call_test.rb: 1

72-72: Trivial · Maintainability & Code Quality · Quick win

Check for frames after the rejected hold.

Move assert_empty sent after assert_raises. An implementation that sends tool_hold and then raises CallNotHeldError passes both current assertions.

As per path instructions, flag “tests that would still pass on a broken implementation.”

Source: Path instructions

examples/text_agents/travel_support/travel_support.py: 1

84-84: Minor · Data Integrity & Integration · Quick win

Read all connection pages before creating another connection.

If tablejourney is on a later page, this check misses it and creates another connection with the same label. sync_agent searches all pages and rejects multiple matching labels, so setup cannot complete. Follow next_cursor before deciding that the connection is absent. (raw.githubusercontent.com)

examples/text_agents/travel_support_js/index.mjs: 2

70-72: Minor · Data Integrity & Integration · Quick win

Read all connection pages before creating another connection.

If the existing tablejourney connection is on a later page, this check misses it and creates a duplicate label. The endpoint returns next_cursor for additional pages. The supplied fixedConnection() implementation then reads every page and rejects the ambiguous label during sync. Follow the cursor before deciding that no connection exists. (raw.githubusercontent.com)


73-74: Minor · Data Integrity & Integration · Quick win

Resume the credential step for a labeled connection that is not yet connected.

The label check returns before the credential PUT (index.mjs:73-74). The router records a new connection as pending. The PUT at index.mjs:81-84 stores the credentials that complete a connection to a connector without a login. If a run stops between the POST and the PUT, the next run finds the labeled connection and returns without storing its credentials. The connection can then stay unconnected, and later TableJourney calls can fail.

When a labeled connection exists, check whether it is connected. If it is not, store its empty credentials before returning. Return early only for a connection that is already connected.

sdks/go/acceleration/generated.go: 1

102903-102904: Minor · Functional Correctness · Poor tradeoff

Keep malformed JSON 404 refusals on the RouterError path.

This PR adds a 404 case to GetAgentStats. When a 404 has Content-Type: application/json and the body is not valid JSON, the case returns the decoding error. Agent.Stats then wraps that error and returns before it calls failure, so callers cannot read the status through *stream.RouterError. Before this PR, the operation had no 404 case, and the same response reached failure. This breaks the SDK rule that every refusal is a *stream.RouterError.

Change the generator template, then regenerate. The decode branch follows the same return-on-error shape as every other generated parser, so a hand edit to generated.go would be overwritten on regeneration. The generated 404 branch should keep the raw response when decoding fails, and it should keep populating JSON404 for valid bodies.

Nitpick comments: 6

sdks/js/src/session.ts: 1

208-208: Trivial · Maintainability & Code Quality · Heavy lift

Keep call state in the existing conversation store.

ToolCalls adds another snapshot, subscriber set and notification-error loop beside the existing session stores. Put the call-state map in Conversation, and expose call-specific selectors for the current API and React hooks. This keeps session observation in one state owner and avoids maintaining another notification implementation.

As per coding guidelines, “Extend one of these rather than adding a store.”

Source: Coding guidelines

sdks/js/tests/tools.test.ts: 1

274-274: Trivial · Maintainability & Code Quality · Quick win

Replace the preset hold implementation with real hold behavior.

This test double ignores the call id and returns a selected boolean. The test still passes if disallowInterruptions sends the wrong id.

Use the stand-in router. Check that the selected call survives interruption after a successful hold, and that a stopped call rejects. As per coding guidelines, “Never mock” and “Assert on outputs, state and what reached the far end.”

Source: Coding guidelines

acceleration/internal/session/hosted_tools_test.go: 2

149-149: Trivial · Maintainability & Code Quality · Heavy lift

Exercise hosted routing through a real dispatch pool.

The new tests use fakeHosts, whose RunHosted always returns success. The routing assertions inspect hosts.agents, not a worker result. They cannot establish that the selected hosting scope reaches a worker.

Use a real dispatch pool and return distinct outputs from agent-specific and every-agent workers. Assert those outputs.

As per coding guidelines, “Never mock” and “Assert on outputs and state, never on which method was called.”

Source: Coding guidelines


134-134: Trivial · Maintainability & Code Quality · Quick win

Put the new hosted-tool tests in a testify suite.

The three new standalone tests repeat Manager setup and use raw testing checks. Move their shared setup into a suite and use suite assertions.

As per coding guidelines, “Group tests in a testify suite (suite.Suite). Shared setup lives in the suite, in one place.” Outside a suite, “check with require.”

Source: Coding guidelines

examples/text_agents/travel_support/travel_support.py: 1

80-80: Trivial · Maintainability & Code Quality · Heavy lift

Expose connector setup through named SDK resource methods.

This example performs four raw HTTP operations and maintains their paths and payloads itself. Add named connector and connection resource methods, then use them here. Keep transport and generated-model handling inside the SDK.

As per coding guidelines, “Users, examples and docs never write” raw requests; “Every resource gets a clean, named API.”

Source: Coding guidelines

examples/text_agents/travel_support_js/index.mjs: 1

68-68: Trivial · Maintainability & Code Quality · Quick win

Move connector setup behind named resource methods.

This public example embeds four raw HTTP operations. Add minimal connector and connection resource methods, then use those methods here. This keeps route templates and payload contracts in the SDK instead of teaching callers to depend on request-layer plumbing. The SDK identifies that layer as internal resource plumbing. (raw.githubusercontent.com)

As per coding guidelines, “Users, examples and docs never write client.post.”

Also applies to: 70-72, 77-79, 81-84

Source: Coding guidelines

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between bbff046 and b759d42.

Files ignored due to path filters: 23

  • examples/text_agents/travel_support_js/package-lock.json is excluded by !**/package-lock.json
  • plugins/stream/vision_agents/plugins/stream/_generated/api/default/get_agent_stats.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/api/default/watch_session.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/__init__.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_config.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_config_patch.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_config_request.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_connector_binding.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_stats.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/agent_tools.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/error_detail.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/offered_tool.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/policy.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/sync_agent_request.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_call_frame_type.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_call_state.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_call_status.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_group.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_loading.py is excluded by !**/_generated/**
  • plugins/stream/vision_agents/plugins/stream/_generated/models/tool_stats.py is excluded by !**/_generated/**
  • sdks/js/package-lock.json is excluded by !**/package-lock.json
  • sdks/js/src/generated/api.ts is excluded by !**/generated/**
  • sdks/ruby/lib/getstream/vision_agents/generated/spec.rb is excluded by !**/generated/**
Files selected for processing: 146

  • .claude/skills/sdk/SKILL.md
  • CHANGELOG.md
  • acceleration/api/openapi.yaml
  • acceleration/internal/agent/agent.go
  • acceleration/internal/agent/approval.go
  • acceleration/internal/agent/deferred_tools.go
  • acceleration/internal/agent/deferred_tools_test.go
  • acceleration/internal/agent/events.go
  • acceleration/internal/agent/telephony.go
  • acceleration/internal/api/apierror.go
  • acceleration/internal/api/config_patch.go
  • acceleration/internal/api/configs.go
  • acceleration/internal/api/configs_test.go
  • acceleration/internal/api/dispatch_test.go
  • acceleration/internal/api/dispatchws.go
  • acceleration/internal/api/handwritten.go
  • acceleration/internal/api/money.go
  • acceleration/internal/api/policies.go
  • acceleration/internal/api/scheduled_tasks_test.go
  • acceleration/internal/api/server.go
  • acceleration/internal/api/server_test.go
  • acceleration/internal/api/session_tools.go
  • acceleration/internal/api/sessionws.go
  • acceleration/internal/api/sessionws_frames_test.go
  • acceleration/internal/api/sync.go
  • acceleration/internal/api/sync_test.go
  • acceleration/internal/api/tool_output_retention_test.go
  • acceleration/internal/dispatch/tools.go
  • acceleration/internal/harness/AGENTS.md
  • acceleration/internal/harness/deferred.go
  • acceleration/internal/harness/deferred_test.go
  • acceleration/internal/harness/tools.go
  • acceleration/internal/llm/composition.go
  • acceleration/internal/node/workers.go
  • acceleration/internal/session/caller_tools.go
  • acceleration/internal/session/connector_approval.go
  • acceleration/internal/session/hosted_tools.go
  • acceleration/internal/session/hosted_tools_test.go
  • acceleration/internal/session/logs.go
  • acceleration/internal/session/manager.go
  • acceleration/internal/session/progressive_tools.go
  • acceleration/internal/session/progressive_tools_test.go
  • acceleration/internal/session/records_test.go
  • acceleration/internal/session/session.go
  • acceleration/internal/session/spec.go
  • acceleration/internal/session/tool_call_state.go
  • acceleration/internal/session/tool_call_state_test.go
  • acceleration/internal/session/tool_loading.go
  • acceleration/internal/session/tool_policy_test.go
  • acceleration/internal/store/agents.go
  • acceleration/internal/store/models.go
  • acceleration/internal/store/sessions.go
  • acceleration/internal/store/sessions_test.go
  • acceleration/internal/store/store.go
  • acceleration/internal/store/tool_groups_migration_test.go
  • acceleration/internal/store/usage_test.go
  • acceleration/migrations/20270102090000_agent_config_tool_groups.sql
  • examples/text_agents/mcp_plugins/agent.yaml
  • examples/text_agents/travel_support/README.md
  • examples/text_agents/travel_support/__init__.py
  • examples/text_agents/travel_support/agent.yaml
  • examples/text_agents/travel_support/instructions.md
  • examples/text_agents/travel_support/knowledge/travel_policy.md
  • examples/text_agents/travel_support/pyproject.toml
  • examples/text_agents/travel_support/skills/itinerary.md
  • examples/text_agents/travel_support/travel_support.py
  • examples/text_agents/travel_support_js/.gitignore
  • examples/text_agents/travel_support_js/README.md
  • examples/text_agents/travel_support_js/agent.yaml
  • examples/text_agents/travel_support_js/index.mjs
  • examples/text_agents/travel_support_js/instructions.md
  • examples/text_agents/travel_support_js/knowledge/travel_policy.md
  • examples/text_agents/travel_support_js/package.json
  • examples/text_agents/travel_support_js/skills/itinerary.md
  • plugins/stream/README.md
  • plugins/stream/tests/test_accelerated.py
  • plugins/stream/tests/test_client.py
  • plugins/stream/tests/test_config.py
  • plugins/stream/tests/test_dispatch.py
  • plugins/stream/tests/test_folder.py
  • plugins/stream/tests/test_sts.py
  • plugins/stream/vision_agents/plugins/stream/_tool_line.py
  • plugins/stream/vision_agents/plugins/stream/client.py
  • plugins/stream/vision_agents/plugins/stream/config.py
  • plugins/stream/vision_agents/plugins/stream/dispatch.py
  • plugins/stream/vision_agents/plugins/stream/folder.py
  • sdks/dart/stream_agents/lib/src/core/agent_event.dart
  • sdks/dart/stream_agents/lib/src/core/agent_session.dart
  • sdks/dart/stream_agents/test/core/session_test.dart
  • sdks/dotnet/README.md
  • sdks/dotnet/src/GetStream.VisionAgents/ToolCallContext.cs
  • sdks/dotnet/tests/GetStream.VisionAgents.Tests/AgentTests.cs
  • sdks/dotnet/tests/GetStream.VisionAgents.Tests/ToolCallTests.cs
  • sdks/go/README.md
  • sdks/go/acceleration/generated.go
  • sdks/go/agents/agent_test.go
  • sdks/go/agents/config.go
  • sdks/go/agents/folder.go
  • sdks/go/agents/folder_test.go
  • sdks/go/client/client.go
  • sdks/go/client/client_test.go
  • sdks/go/client/sessions.go
  • sdks/go/examples/caregiving/main.go
  • sdks/go/examples/quickstart/agents/myagent/agent.yaml
  • sdks/go/examples/text/agents/jean/agent.yaml
  • sdks/go/examples/voice/agents/jean/agent.yaml
  • sdks/go/stream/accelerated.go
  • sdks/go/stream/hosted_test.go
  • sdks/go/stream/tool_calls.go
  • sdks/go/stream/tool_calls_test.go
  • sdks/go/stream/tool_line.go
  • sdks/go/stream/tool_progress_test.go
  • sdks/go/tools/call.go
  • sdks/go/tools/tools_test.go
  • sdks/js/README.md
  • sdks/js/package.json
  • sdks/js/src/index.ts
  • sdks/js/src/react.ts
  • sdks/js/src/session.ts
  • sdks/js/src/tool-calls.ts
  • sdks/js/src/tool_line.ts
  • sdks/js/src/tools.ts
  • sdks/js/tests/dispatch.test.ts
  • sdks/js/tests/session.test.ts
  • sdks/js/tests/tool-calls.test.ts
  • sdks/js/tests/tools.test.ts
  • sdks/js/tsconfig.json
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/AgentEvent.kt
  • sdks/kotlin/core/src/main/kotlin/io/getstream/agents/android/core/AgentSession.kt
  • sdks/kotlin/core/src/test/kotlin/io/getstream/agents/android/core/AgentSessionTest.kt
  • sdks/php/README.md
  • sdks/php/src/ToolCallContext.php
  • sdks/php/tests/Unit/ToolCallTest.php
  • sdks/python/vision_agents/core/llm/tool_call.py
  • sdks/ruby/README.md
  • sdks/ruby/lib/getstream/vision_agents/tool_call.rb
  • sdks/ruby/test/agent_test.rb
  • sdks/ruby/test/dispatch_test.rb
  • sdks/ruby/test/tool_call_test.rb
  • sdks/rust/README.md
  • sdks/rust/src/tool_call.rs
  • sdks/rust/tests/session.rs
  • sdks/swift/core/Sources/StreamAgents/AgentEvent.swift
  • sdks/swift/core/Sources/StreamAgents/AgentSession.swift
  • sdks/swift/core/Tests/StreamAgentsTests/ToolCallStateTests.swift
  • tests/test_tool_call.py
Files with no reviewable changes: 15

  • plugins/stream/README.md
  • plugins/stream/tests/test_accelerated.py
  • plugins/stream/tests/test_client.py
  • plugins/stream/tests/test_sts.py
  • plugins/stream/vision_agents/plugins/stream/_tool_line.py
  • sdks/dotnet/src/GetStream.VisionAgents/ToolCallContext.cs
  • sdks/go/examples/caregiving/main.go
  • sdks/go/stream/tool_line.go
  • sdks/go/stream/tool_progress_test.go
  • sdks/js/README.md
  • sdks/js/src/tool_line.ts
  • sdks/js/src/tools.ts
  • sdks/php/src/ToolCallContext.php
  • sdks/ruby/lib/getstream/vision_agents/tool_call.rb
  • sdks/rust/src/tool_call.rs

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Comment on lines +2169 to +2170
case slices.Contains(harness.DeferredToolNames, name):
return fmt.Sprintf("%s.tools: %s is the router's own tool for loading deferred ones, so no function may take the name", at, name), false

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Security & Privacy · Quick win

Prevent function groups from overriding connector retention.

A group can name linear__search while the linear connector binding sets output_retention: none. This validator accepts that configuration. toolLoading.retention checks the group before the binding, so an omitted group retention causes the connector arguments and result to be retained when no policy restricts them.

Reject group names that identify tools in a configured connector namespace, or ensure the binding's retention still applies. Keep unrelated SDK function names valid.

EpisodeCardsRecord: config.EpisodeCardsRecord,
ProgressiveTools: config.ProgressiveTools,
ToolGroups: config.ToolGroups,
ResumeHistory: config.ResumeHistory,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Security & Privacy · Heavy lift

Preserve existing config retention during migration.

If an existing config sets tool_output_retention: none, removing this assignment drops that restriction for built-in tools such as search. The migration copies the restriction only to connector bindings. With no app or organization restriction, the new session records the built-in tool's arguments and result instead of redacting them.

Preserve the legacy restriction until an explicit replacement is saved. Configs without a legacy restriction can keep the new defaults.

FROM agent_responses AS a
JOIN agent_sessions AS s ON s.id = a.session_id
WHERE a.customer_id = ?3 AND (?6 = '' OR s.config_id = ?6) AND a.created_at < ?5
AND a.parent_response_id IS NULL AND a.rewound_at IS NULL

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Heavy lift

Do not use conversation ancestry to identify delegated responses.

ParentResponseID identifies the previous response, not just a delegated task's owner. session.go sets it to s.leaf for ordinary follow-up turns.

For R1 → R2 → R3, these predicates count only R1. A tool first called on R3 gets no turn position because R2 is absent from turns. A tool called on R2 incorrectly gets position zero.

Use the actual delegation relationship to exclude and attribute task responses. Count ordinary follow-up responses and preserve the rewind filter. Add a regression fixture with production parent links.

Also applies to: 1490-1490, 1615-1615

DO $$
BEGIN
SET LOCAL lock_timeout = '5s';
ALTER TABLE agent_configs DROP COLUMN IF EXISTS tool_groups;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

Preserve tool groups across rollback.

If configurations contain tool groups, Down deletes those groups. A later Up recreates the column as NULL and restores none of them. Configured sessions then lose their enabled functions until the configurations are restored or synced again.

Retain the column for rollback compatibility, or preserve and restore its values. Verify a populated Down/Up cycle, not only column removal.

As per coding guidelines, flag “a down migration that loses data.”

Source: Coding guidelines

description: Travel customer support that answers policy questions and plans itineraries.
mode: text
llm: llm-fast
connectors:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Heavy lift

Configure and sync a group for lookup_booking.

On a fresh app, this config has no function group. The router therefore excludes the hosted lookup_booking tool from dashboard sessions. Registering it with Dispatch.host() does not bypass the group check. The documented booking lookup cannot work. (raw.githubusercontent.com)

Add a booking group and ensure the JS SDK parses and syncs it. At this revision, the JS parser rejects a top-level tools key, so a YAML-only fix is insufficient. Keep the connector allowlist unchanged. (raw.githubusercontent.com)

Comment on lines +88 to +89
if any(c.get("label") == CONNECTION_LABEL for c in listed.json()["items"]):
return

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Functional Correctness · Quick win

Finish connecting an existing pending connection.

If setup stops after connection creation but before the credentials PUT succeeds, the connection remains pending. On every later run, this label check returns before activation. The itinerary tools remain unavailable. Connection creation and credential storage are separate operations. (raw.githubusercontent.com)

Keep the matched connection. If it is pending, store its empty credentials using its current revision. Return unchanged only when it is connected.

"""
self._hosted.append(_Hosting(agent.name, agent.functions, tool_timeout))
if isinstance(target, Client):
self._hosted.append(_Hosting("", target.tools, tool_timeout))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Heavy lift

Preserve the selected hosting scope when running a tool.

If a client and an agent both register search_docs, hosting the client first makes _call_hosted run the client handler even when the router selected the agent-specific offer. _call_hosted selects the first registry with that name. toolCallFrame sends no hosting selector.

Carry the selected hosting scope through the call frame and use it to select the registry. Add a round-trip test with different outputs for the same-named handlers. Check both registration orders and another agent's every-agent call.

Comment on lines +2 to +4
tools:
- name: weather
tools: [get_weather]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Functional Correctness · Quick win

Load this group in the voice example.

The documented command runs from sdks/go, but agents.New only checks agents/jean/agent.yaml there. It does not load this file. On a fresh router, Sync creates Jean without the group, so the router rejects the session's get_weather declaration. Set Dir in the voice example to load this directory for the documented command. (raw.githubusercontent.com)

}

event := eventOf(frame)
p.observe(event)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Stability & Availability · Heavy lift

Keep On subscriptions independent of an undrained Events channel.

If a caller uses On without reading Events(), the 64-slot channel fills. The reader invokes callbacks for event 65, then blocks at Line 1016. It never reads event 66 or later tool calls.

Provide a bounded delivery path that does not require callback users to drain a second event API. Preserve ordered callbacks and cancellation.

status: ToolCallState.Status(rawValue: string("status")),
progress: string("progress"),
startedAt: date("started_at"),
durationMS: Int(self["duration_ms"].numberValue ?? 0),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Stability & Availability · Quick win

Use a checked conversion for duration_ms.

A lifecycle event with "duration_ms":1e30 reaches Int(...) with an out-of-range value. Swift 6 checks this conversion and traps, which terminates the app instead of reporting a socket error. (raw.githubusercontent.com)

Use a failable conversion, such as Int(exactly:), with the existing zero fallback. Preserve valid integer durations such as 300.

As per coding guidelines, “Treat everything the router, a provider or a model sends as untrusted.”

Source: Coding guidelines

tschellenbach and others added 12 commits November 19, 2026 11:20
Co-authored-by: Cursor <cursoragent@cursor.com>

# Conflicts:
#	acceleration/api/openapi.yaml
#	acceleration/internal/session/session.go
#	plugins/stream/vision_agents/plugins/stream/_generated/api/default/watch_session.py
#	sdks/go/acceleration/generated.go
#	sdks/go/stream/accelerated.go
#	sdks/js/src/generated/api.ts
#	sdks/swift/core/Sources/StreamAgents/AgentEvent.swift
…nDispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
…run_dispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
…runDispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
…nDispatchAsync

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…h run_dispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
…ith run_dispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…h runDispatch

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…el_support

Co-authored-by: Cursor <cursoragent@cursor.com>
@tschellenbach
tschellenbach marked this pull request as ready for review November 19, 2026 19:07
@tschellenbach
tschellenbach merged commit ccc66d5 into main Nov 19, 2026
11 of 19 checks passed
@tschellenbach
tschellenbach deleted the tool-groups branch November 19, 2026 19:08
tschellenbach added a commit that referenced this pull request Nov 19, 2026
## Why

Main has two migrations at version `20270102090000`:
`agent_config_tool_groups` (from #2088) and `ui_instructions`. Goose
refuses a duplicate version, so a fresh database cannot migrate, and a
database that applied one of them skips the other. Locally that showed
up as `column "ui_instructions" of relation "agent_configs" does not
exist` in every API suite.

## How it works

```
before                                after
20270101090000 caller_tools           20270101090000 caller_tools
20270102090000 ui_instructions        20270102090000 ui_instructions
20270102090000 tool_groups  <- dup    20270103090000 tool_groups
```

## Changes

- Renames the tool groups migration to `20270103090000`, so it runs
after `ui_instructions`.
- `tool_groups_migration_test.go` migrates to the version before it and
then to it, using the new numbers.
- `store/usage_test.go`'s redact test writes through `ShardDB()`, since
the rows it changes live in the shard, and a comment in `models.go`
names the new version.

## Validation

- `go test -tags integration ./internal/store` passes against a fresh
Postgres.
- `TestToolGroupsMigrationSuite` migrates from `20270102090000` to
`20270103090000` and checks the configs it rewrites, a rerun after a
half-finished run, and the down migration.
- A database that already applied the old `20270102090000` as tool
groups is missing `ui_instructions`. Local test databases in that state
need dropping. Whether a hosted environment migrated while main had the
duplicate is unverified.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant