@devries-cameron20 / composio Mirror · read-only / commits / e305e7369
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 09:45 UTC

feat(core): accept instant.returnPricesInSearch on sessions (#4861)

## Summary The platform added an experimental Session flag, `instant.return_prices_in_search`. When it is set, session search results list each Instant tool's published price at `toolkit_connection_statuses[].instant_account.prices`, keyed by tool slug (`{ description, discount }`). The auto-generated docs PR (#4846) syncs the OpenAPI spec, but neither SDK could send the flag, and the TS search transformer dropped `prices`. This PR adds the SDK side. Designated PR reviewer: [@jkomyno](mailto:alberto@composio.dev). ## Changes - **TypeScript**: - `sessions.create()` and `session.update()` accept `instant.returnPricesInSearch`, sent as `return_prices_in_search`. - `session.search()` returns `toolkitConnectionStatuses[].instantAccount.prices`. The search response schema now includes `prices`, so the Zod parse keeps it. - `session.config.instant.return_prices_in_search` and its config-history equivalent are typed. - New exports: `ToolRouterToolPricing` and `ToolRouterToolPricingSchema`. - **Python**: - `ToolRouterInstantConfig` gains `return_prices_in_search`. - A typing-only `ToolRouterInstantPolicy` Protocol types `session.config.instant.return_prices_in_search`. - Docstrings cover `instant_account.prices` on search results. The generated model keeps it as an extra field. - **Docs**: the Instant guide gets a "Show prices in search" section with Python and TS examples. The TS snippet uses `// @noErrors` because the docs build against the published `@composio/core` 0.23.0. - **Changeset**: `@composio/core` patch, the same scope as the `proxyExecute` option. ### Matches the `return_instant_charge` approach The pinned generated clients (`@composio/client` 2.0.0-rc.13 and `composio-client` 2.0.0rc13) don't type `return_prices_in_search` or `instant_account.prices` yet. Both forward the `instant` body unchanged. As #4694 did for `return_instant_charge`, small SDK-owned types bridge the gap: - TS `SessionInstantBody` - TS `WithInstantReturnPricesInSearch` - Python `ToolRouterInstantPolicy` Each is commented as temporary and can go when the clients regenerate from the new spec. No runtime transport workaround is needed. ## Type of change - [ ] Bug fix - [x] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? - **TS core**: - `pnpm typecheck`, including `type-tests/instant-contract.test-d.ts`: passes. - Full vitest suite: 1819 passed, 2 expected failures. - New tests cover create and update mapping, `session.search()` returning `prices` through the Zod parse, and the raw transformer. All four fail without the source change. - `pnpm lint` and `pnpm validate:changesets`: pass. - **Python**: - `pytest tests/test_tool_router.py`: 201 passed. Transport tests now cover sending `return_prices_in_search` on create and patch, reading it from the returned config, and reading `instant_account.prices` from search through the real generated client. The Python change is typing-only, so these tests pin behavior rather than fail-then-pass. - `ruff check` and `ruff format` with `config/ruff.toml`: pass. - `mypy composio/`: one existing error in `utils/schema_converter.py` that also shows on `next`; no new errors. - **Docs**: `bun test tests/static/`: 626 passed. The full docs build (Twoslash) was not run locally. ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the [third-party links policy](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md#third-party-links-in-docs) - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [x] I added a changeset if this change affects published packages ## Additional context Follow-up to #4846. Python versioning and release notes go in the release commit, per repo convention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Ex46Sq8AkDMMmYyLXbBJhF --- _Generated by [Claude Code](https://claude.ai/code/session_01Ex46Sq8AkDMMmYyLXbBJhF)_ --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: jkomyno <alberto@composio.dev>

Bharath Singh committed Oct 14, 2026 at 22:36 UTC e305e7369a828c2eed5fabf597d5027424f4f450
4 files changed +46 -4
docs/content/docs/instant-tools.mdx
+38 -2
@@ -176,6 +176,44 @@ console.log(result.instantCharge);
176
177 The charge includes `amount`, `currency`, and `charged_by`. The amount is an exact USD decimal string. TypeScript exposes `instantCharge` as `unknown`. Turning charge reporting off does not stop billing or remove charges from logs and usage records.
178
179 +### Show prices in search
180 +
181 +To see what an Instant tool costs before you call it, set `return_prices_in_search` in Python or `returnPricesInSearch` in TypeScript. This option is experimental and off by default. Search results then list each Instant tool's published price under the toolkit's Instant account, keyed by tool slug:
182 +
183 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
184 +<Tab value="Python">
185 +```python
186 +session = composio.sessions.create(
187 + user_id="instant_demo",
188 + toolkits=["firecrawl"],
189 + instant={"return_prices_in_search": True},
190 +)
191 +results = session.search(query="scrape a web page")
192 +for status in results.toolkit_connection_statuses:
193 + if status.instant_account is not None:
194 + print(status.toolkit, status.instant_account.prices)
195 +```
196 +</Tab>
197 +<Tab value="TypeScript">
198 +```typescript
199 +// @noErrors
200 +import { Composio } from "@composio/core";
201 +const composio = new Composio();
202 +// ---cut---
203 +const session = await composio.create("instant_demo", {
204 + toolkits: ["firecrawl"],
205 + instant: { returnPricesInSearch: true },
206 +});
207 +const results = await session.search({ query: "scrape a web page" });
208 +for (const status of results.toolkitConnectionStatuses) {
209 + console.log(status.toolkit, status.instantAccount?.prices);
210 +}
211 +```
212 +</Tab>
213 +</Tabs>
214 +
215 +Each price has a `description` and, when one applies, a `discount`. Like charge reporting, this setting only controls what the response shows. It does not turn Instant usage on or off.
216 +
217 ## Know which account runs the tool
218
219 Composio uses your user's connection first, then an available shared connection, then an Instant account. Only calls through an Instant account incur an Instant charge. Your provider may separately bill calls made with your own account.
@@ -188,8 +226,6 @@ Instant uses shared provider accounts, so tools exposing account history or othe
226
227 Session search returns `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript) for a toolkit served by an Instant account. Other tools in that toolkit need your own connection.
228
191 -To also see each tool's price in search results, set the experimental `return_prices_in_search` option (`returnPricesInSearch` in TypeScript) in the Session's `instant` policy. Prices appear under `instant_account.prices` (`instantAccount.prices`), keyed by tool slug.
192 -
229 To select Instant explicitly, pass `account="instant_account"` to Python `session.execute()`, or `{ account: "instant_account" }` as TypeScript execution options. On a single-account project, this must match an active connection for the toolkit in the Session. Project policy, Session policy, and tool eligibility still apply. A failed call does not fall back to another account.
230
231 Composio-managed auth is different: Composio supplies the OAuth app credentials, but your user still connects their own account. It does not establish Instant support.
python/composio/core/models/tool_router.py
+3
@@ -922,6 +922,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
922 :param instant: Experimental Instant usage policy. The project
923 must allow Instant usage. ``False`` disables it for this
924 Session; a policy can restrict eligible toolkits and tools.
925 + ``return_instant_charge`` returns the charge with each
926 + call, and ``return_prices_in_search`` shows each Instant
927 + tool's price in ``session.search()`` results.
928 :param mcp: When True, the returned session surfaces its hosted MCP
929 endpoint (``session.mcp.url`` / ``session.mcp.headers``) in
930 the type (returns ToolRouterSessionWithMcp). The endpoint
python/composio/core/models/tool_router_session.py
+3 -2
@@ -1186,8 +1186,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1186 ``callback_url=None`` removes only the stored callback URL.
1187 Experimental ``instant`` accepts ``False`` to disable billed
1188 access or an object to set its filters; it does not accept ``None``.
1189 - Any object, even one that only sets ``return_instant_charge``,
1190 - re-enables Instant usage on a Session set to ``False``.
1189 + Any object, even one that only sets ``return_instant_charge`` or
1190 + ``return_prices_in_search``, re-enables Instant usage on a Session
1191 + set to ``False``.
1192 ``proxy_execute`` takes a bool or ``{"enable": bool}``; ``True``
1193 exposes the ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``False`` also turns
1194 off the sandbox ``proxy_execute()`` helper, and ``None`` removes the
ts/packages/core/type-tests/instant-contract.test-d.ts
+2
@@ -37,6 +37,8 @@ async function instantContract(): Promise<void> {
37 if (historical?.config.instant) {
38 const returnedCharge: boolean = historical.config.instant.return_instant_charge;
39 void returnedCharge;
40 + const returnedPrices: boolean = historical.config.instant.return_prices_in_search;
41 + void returnedPrices;
42 }
43
44 const summary = await composio.experimental.usage.summary();