feat!: one search tool and one execute tool spanning the account scope (ENG-3175)

Merged
WI
21d ago
+1455-1040

Part of ENG-3175. Draft: depends on the server serving the trio to API keys (unified-cloud-api#9417 (merged)) and on StackOneHQ/sdk-conformance#9. Lands before the 3.0.0 release (#200), so the breaking change ships inside 3.0.0.

In search_execute mode the SDK now gives a model one stackone_search_actions and one stackone_execute_action (with stackone_list_accounts) across every account in scope, instead of one pair per account.

  • Listing: one MCP request for the whole scope, with the account ids as repeated x-account-id query parameters and recorded end users as repeated x-end-user-id. A failure raises; there is one request, so nothing to skip.
  • search(): one stackone_search_actions call. Hits are as served, with available_accounts; an action linked on two accounts is one hit, not two, and there is no account_id per hit.
  • execute(): one stackone_execute_action call. A single id in account_ids becomes stackone_account_id. An ambiguous action is refused by the server (StackOneAPIError), not the SDK.
  • Removed: the per-connector fan-out, connector-name parsing, cross-connector re-ranking, and the failed-account retry and provider-miss tracking in execute().
  • Pydantic AI: FunctionModel-driven Agent tests run a tool end to end against the mock MCP server in individual and search_execute modes. The example runs an agent in each mode. Removes a stale _build_tools mock.
  • README, MIGRATION and examples show available_accounts; vectors vendored from sdk-conformance@65e1286.

Checks: 850 tests pass; ruff and ty clean; the sdk-conformance suite passes.

Live (production API, Gemini 3.1 Pro, a Google Calendar account): Pydantic AI agents passed in both modes. Production still serves the per-account pair, so the trio itself was exercised only against mocks.

Follow-up once sdk-conformance merges: bump the pinned conformance ref (5f60cc0) and NODE_SDK_REF in CI.

Update: on the merged server (unified-cloud-api#9417)

Stu's #9417 is merged and replaces unified-cloud-api#9398. It takes the accounts as a comma-separated x-account-id, serves the trio for two or more, and serves the account's own pair (<provider>_<accountId>_search_actions / _execute_action) for one, capped at 50. So now:

  • Listing: one comma-separated x-account-id query value (sorted, deduped) instead of repeated parameters; end users stay repeated x-end-user-id.
  • One account: the served pair is presented as stackone_search_actions / stackone_execute_action. Served names are rewritten in descriptions, schemas, results and error text, and hits gain available_accounts and provider. A stackone_account_id or provider naming that account is dropped (null too); any other raises ToolArgumentsError (account-outside-scope, provider-outside-scope) before any call. No stackone_list_accounts is invented.
  • More than 50 accounts in scope: too-many-accounts config error before any request.

The full sdk-conformance suite passes against both SDK branches, cross-SDK wire equality included; so do the sdk / pydantic / adk smoke scripts.