@devries-cameron20 / composio-1 / commits / 0833c1ba4
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.

Add hosted account support and premium charge tracking (#4617)

## Summary This PR adds support for Composio hosted accounts and premium usage charge tracking across the API and SDK. It introduces the ability to explicitly route tool calls to hosted accounts, track premium charges in responses, and exposes hosted account allowlists in toolkit connection statuses. ## Changes - **Hosted Account Routing**: Updated `connected_account_id` parameter to accept `"hosted_account"` as a special value to explicitly route tool execution to Composio's hosted account for a toolkit, with request failure rather than fallback on error - **Premium Charge Tracking**: Added `premium_charge` object to tool execution responses (containing amount, currency, and charged_by fields) and `premium_usage_charge` to usage aggregates - **Toolkit Connection Status**: Renamed `composio_managed` to `hosted_account` in toolkit connection statuses and exposed `allowedToolSlugs` to indicate which tools are available via the hosted account - **Payment Required Responses**: Added 402 HTTP status code handling for exhausted wallet balance across multiple endpoints - **API Documentation**: Added examples for Google Calendar and Jira scope recommendations, improved grant context documentation - **SDK Updates**: Updated TypeScript types and response transformers to handle hosted account allowlists in `session.search()` results ## Type of change - [x] New feature - [x] Documentation ## How Has This Been Tested? - Added unit tests in `toolRouterResponseTransform.test.ts` to verify hosted account allowlist mapping - Added unit tests in `toolRouter.test.ts` to verify hosted account allowlist exposure in search results - Updated TypeScript schemas to reflect new fields - OpenAPI specs updated and validated for both v3 and v3.1 formats ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff - [x] I updated documentation as needed - [x] I added tests for the new functionality - [x] I added a changeset for the published package changes ## Additional context The changes enable better control over which account credentials are used for tool execution and provide visibility into premium usage costs. The hosted account feature allows users to leverage Composio-managed credentials for specific tools while maintaining explicit control over credential selection. https://claude.ai/code/session_01SCJLmKE3JMrC3RRKDPAV1h --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com> Co-authored-by: jkomyno <alberto@composio.dev>

Bharath Singh committed Sep 24, 2026 at 13:39 UTC 0833c1ba4a2bff3fd2fbf6b995308ea0f7dee312
9 files changed +440 -22
.changeset/search-hosted-account-status.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': minor
3 +---
4 +
5 +Expose `hostedAccount.allowedToolSlugs` on `session.search()` toolkit connection statuses for toolkits served by a Composio hosted account.
docs/content/docs/instant-tools.mdx
+2
@@ -167,6 +167,8 @@ A hosted account is a provider account held by Composio for specific tools. It i
167
168 If you select a connected account explicitly, that route wins and does not fall back to the hosted account on failure. Otherwise, available user, shared, or developer connections take priority over a hosted account. If the chosen tool is not supported by a hosted account, it follows the normal connection flow.
169
170 +Session search tells you when a hosted account serves a toolkit. The toolkit's connection status includes `hosted_account.allowed_tool_slugs` (`hostedAccount.allowedToolSlugs` in TypeScript), which lists the tools that run on it. Any other tool in that toolkit needs the user's own connection.
171 +
172 Hosted accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
173
174 See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/api-reference/tool-router/postToolRouterSession) for the complete request schema.
docs/public/openapi-v3.json
+136 -5
@@ -10773,8 +10773,19 @@
10773 "type": "object",
10774 "properties": {
10775 "connected_account_id": {
10776 - "type": "string",
10777 - "description": "Unique identifier for the connected account to use for authentication",
10776 + "anyOf": [
10777 + {
10778 + "type": "string",
10779 + "enum": [
10780 + "hosted_account"
10781 + ]
10782 + },
10783 + {
10784 + "type": "string",
10785 + "format": "connectedAccountId"
10786 + }
10787 + ],
10788 + "description": "Unique identifier for the connected account to use for authentication. Pass `hosted_account` to run the tool on the Composio hosted account for its toolkit, even when the user has connected the toolkit themselves; the request fails rather than falling back to another credential.",
10789 "example": "ca_1a2b3c4d5e6f"
10790 },
10791 "entity_id": {
@@ -11213,6 +11224,16 @@
11224 }
11225 }
11226 },
11227 + "402": {
11228 + "description": "Payment required - Wallet balance is exhausted; add credits to resume premium tool calls or connect your account",
11229 + "content": {
11230 + "application/json": {
11231 + "schema": {
11232 + "$ref": "#/components/schemas/Error"
11233 + }
11234 + }
11235 + }
11236 + },
11237 "403": {
11238 "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",
11239 "content": {
@@ -18403,6 +18424,36 @@
18424 "schema": {
18425 "type": "object",
18426 "properties": {
18427 + "premium_charge": {
18428 + "type": "object",
18429 + "properties": {
18430 + "amount": {
18431 + "type": "string",
18432 + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
18433 + "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
18434 + },
18435 + "currency": {
18436 + "type": "string",
18437 + "enum": [
18438 + "USD"
18439 + ],
18440 + "description": "Currency of the premium charge. Always USD."
18441 + },
18442 + "charged_by": {
18443 + "type": "string",
18444 + "enum": [
18445 + "composio"
18446 + ],
18447 + "description": "Entity charging for premium usage. Always composio."
18448 + }
18449 + },
18450 + "required": [
18451 + "amount",
18452 + "currency",
18453 + "charged_by"
18454 + ],
18455 + "description": "Returned only when the session enables premium_usage.return_premium_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
18456 + },
18457 "data": {
18458 "type": "object",
18459 "additionalProperties": {},
@@ -18452,6 +18503,16 @@
18503 }
18504 }
18505 },
18506 + "402": {
18507 + "description": "Payment required",
18508 + "content": {
18509 + "application/json": {
18510 + "schema": {
18511 + "$ref": "#/components/schemas/Error"
18512 + }
18513 + }
18514 + }
18515 + },
18516 "403": {
18517 "description": "Forbidden",
18518 "content": {
@@ -18602,6 +18663,36 @@
18663 "schema": {
18664 "type": "object",
18665 "properties": {
18666 + "premium_charge": {
18667 + "type": "object",
18668 + "properties": {
18669 + "amount": {
18670 + "type": "string",
18671 + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
18672 + "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
18673 + },
18674 + "currency": {
18675 + "type": "string",
18676 + "enum": [
18677 + "USD"
18678 + ],
18679 + "description": "Currency of the premium charge. Always USD."
18680 + },
18681 + "charged_by": {
18682 + "type": "string",
18683 + "enum": [
18684 + "composio"
18685 + ],
18686 + "description": "Entity charging for premium usage. Always composio."
18687 + }
18688 + },
18689 + "required": [
18690 + "amount",
18691 + "currency",
18692 + "charged_by"
18693 + ],
18694 + "description": "Returned only when the session enables premium_usage.return_premium_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
18695 + },
18696 "data": {
18697 "type": "object",
18698 "additionalProperties": {},
@@ -18651,6 +18742,16 @@
18742 }
18743 }
18744 },
18745 + "402": {
18746 + "description": "Payment required",
18747 + "content": {
18748 + "application/json": {
18749 + "schema": {
18750 + "$ref": "#/components/schemas/Error"
18751 + }
18752 + }
18753 + }
18754 + },
18755 "403": {
18756 "description": "Forbidden",
18757 "content": {
@@ -21438,6 +21539,16 @@
21539 }
21540 }
21541 },
21542 + "402": {
21543 + "description": "Payment required",
21544 + "content": {
21545 + "application/json": {
21546 + "schema": {
21547 + "$ref": "#/components/schemas/Error"
21548 + }
21549 + }
21550 + }
21551 + },
21552 "403": {
21553 "description": "Forbidden",
21554 "content": {
@@ -21741,6 +21852,16 @@
21852 }
21853 }
21854 },
21855 + "402": {
21856 + "description": "Payment required",
21857 + "content": {
21858 + "application/json": {
21859 + "schema": {
21860 + "$ref": "#/components/schemas/Error"
21861 + }
21862 + }
21863 + }
21864 + },
21865 "403": {
21866 "description": "Forbidden",
21867 "content": {
@@ -22120,7 +22241,7 @@
22241 ],
22242 "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."
22243 },
22123 - "composio_managed": {
22244 + "hosted_account": {
22245 "type": "object",
22246 "properties": {
22247 "allowed_tool_slugs": {
@@ -22128,13 +22249,13 @@
22249 "items": {
22250 "type": "string"
22251 },
22131 - "description": "Tools of this toolkit that run on the Composio managed account"
22252 + "description": "Tools of this toolkit that run on the Composio hosted account"
22253 }
22254 },
22255 "required": [
22256 "allowed_tool_slugs"
22257 ],
22137 - "description": "Present when the toolkit is connected through the Composio managed account rather than a connected account of the user."
22258 + "description": "Present when the toolkit is connected through the Composio hosted account rather than a connected account of the user."
22259 },
22260 "status_message": {
22261 "type": "string",
@@ -22314,6 +22435,16 @@
22435 }
22436 }
22437 },
22438 + "402": {
22439 + "description": "Payment required",
22440 + "content": {
22441 + "application/json": {
22442 + "schema": {
22443 + "$ref": "#/components/schemas/Error"
22444 + }
22445 + }
22446 + }
22447 + },
22448 "403": {
22449 "description": "Forbidden",
22450 "content": {
docs/public/openapi.json
+229 -10
@@ -3369,8 +3369,19 @@
3369 "type": "object",
3370 "properties": {
3371 "connected_account_id": {
3372 - "type": "string",
3373 - "description": "Unique identifier for the connected account to use for authentication",
3372 + "anyOf": [
3373 + {
3374 + "type": "string",
3375 + "enum": [
3376 + "hosted_account"
3377 + ]
3378 + },
3379 + {
3380 + "type": "string",
3381 + "format": "connectedAccountId"
3382 + }
3383 + ],
3384 + "description": "Unique identifier for the connected account to use for authentication. Pass `hosted_account` to run the tool on the Composio hosted account for its toolkit, even when the user has connected the toolkit themselves; the request fails rather than falling back to another credential.",
3385 "example": "ca_1a2b3c4d5e6f"
3386 },
3387 "entity_id": {
@@ -3809,6 +3820,16 @@
3820 }
3821 }
3822 },
3823 + "402": {
3824 + "description": "Payment required - Wallet balance is exhausted; add credits to resume premium tool calls or connect your account",
3825 + "content": {
3826 + "application/json": {
3827 + "schema": {
3828 + "$ref": "#/components/schemas/Error"
3829 + }
3830 + }
3831 + }
3832 + },
3833 "403": {
3834 "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",
3835 "content": {
@@ -5485,6 +5506,17 @@
5506 "tools"
5507 ],
5508 "x-experimental": true
5509 + },
5510 + "examples": {
5511 + "googlecalendar": {
5512 + "summary": "Google Calendar: list and create events",
5513 + "value": {
5514 + "tools": [
5515 + "GOOGLECALENDAR_EVENTS_LIST",
5516 + "GOOGLECALENDAR_CREATE_EVENT"
5517 + ]
5518 + }
5519 + }
5520 }
5521 }
5522 }
@@ -5579,6 +5611,41 @@
5611 "scopes"
5612 ],
5613 "x-experimental": true
5614 + },
5615 + "examples": {
5616 + "googlecalendar": {
5617 + "summary": "Google Calendar: list and create events",
5618 + "value": {
5619 + "auth_scheme": "OAUTH2",
5620 + "toolkit_version": "20260915_00",
5621 + "grant_context": {},
5622 + "scopes": {
5623 + "least_privilege": [
5624 + "https://www.googleapis.com/auth/calendar.calendars.readonly",
5625 + "https://www.googleapis.com/auth/calendar.events"
5626 + ],
5627 + "fewest": [
5628 + "https://www.googleapis.com/auth/calendar"
5629 + ],
5630 + "conditional": [
5631 + {
5632 + "scope": "https://www.googleapis.com/auth/calendar.calendars.readonly",
5633 + "when": {
5634 + "param.eventType": [
5635 + "default"
5636 + ],
5637 + "param.exclude_organizer": [
5638 + "falsy"
5639 + ]
5640 + },
5641 + "for": [
5642 + "GOOGLECALENDAR_CREATE_EVENT"
5643 + ]
5644 + }
5645 + ]
5646 + }
5647 + }
5648 + }
5649 }
5650 }
5651 }
@@ -5650,7 +5717,7 @@
5717 "/api/v3.1/toolkits/{toolkit_slug}/scopes/grant_context": {
5718 "get": {
5719 "summary": "List grant contexts",
5653 - "description": "Experimental: this endpoint is in beta and its contract may change.\n\nList of contexts in which you want to grant scopes to your user. Pass a dimension and its selected value in the `grant_context` field of the [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) request to tailor the scope recommendation.",
5720 + "description": "Experimental: this endpoint is in beta and its contract may change.\n\nList of contexts in which you want to grant scopes to your user. Pass a dimension and its selected value in the `grant_context` field of the [Get required scopes](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes) request to tailor the scope recommendation.\n\nIn the Jira example, `default_grant_context` is `{\"scope_family\": \"classic\"}`, so a recommendation with no `grant_context` uses classic scopes. Pass `{\"scope_family\": \"granular\"}` to get granular scopes instead.",
5721 "tags": [
5722 "Toolkits"
5723 ],
@@ -5773,6 +5840,28 @@
5840 "default_grant_context"
5841 ],
5842 "x-experimental": true
5843 + },
5844 + "examples": {
5845 + "jira": {
5846 + "summary": "Jira: classic or granular scopes",
5847 + "value": {
5848 + "auth_scheme": "OAUTH2",
5849 + "toolkit_version": "20260917_00",
5850 + "grant_context_dimensions": [
5851 + {
5852 + "dimension": "scope_family",
5853 + "description": "Which Atlassian OAuth scope catalog to draw from: classic scopes cover broad product areas, granular scopes name individual operations. Defaults to classic, matching the scopes our Jira OAuth app requests today.",
5854 + "values": [
5855 + "classic",
5856 + "granular"
5857 + ]
5858 + }
5859 + ],
5860 + "default_grant_context": {
5861 + "scope_family": "classic"
5862 + }
5863 + }
5864 + }
5865 }
5866 }
5867 }
@@ -11227,7 +11316,7 @@
11316 ],
11317 "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."
11318 },
11230 - "composio_managed": {
11319 + "hosted_account": {
11320 "type": "object",
11321 "properties": {
11322 "allowed_tool_slugs": {
@@ -11235,13 +11324,13 @@
11324 "items": {
11325 "type": "string"
11326 },
11238 - "description": "Tools of this toolkit that run on the Composio managed account"
11327 + "description": "Tools of this toolkit that run on the Composio hosted account"
11328 }
11329 },
11330 "required": [
11331 "allowed_tool_slugs"
11332 ],
11244 - "description": "Present when the toolkit is connected through the Composio managed account rather than a connected account of the user."
11333 + "description": "Present when the toolkit is connected through the Composio hosted account rather than a connected account of the user."
11334 },
11335 "status_message": {
11336 "type": "string",
@@ -11421,6 +11510,16 @@
11510 }
11511 }
11512 },
11513 + "402": {
11514 + "description": "Payment required",
11515 + "content": {
11516 + "application/json": {
11517 + "schema": {
11518 + "$ref": "#/components/schemas/Error"
11519 + }
11520 + }
11521 + }
11522 + },
11523 "403": {
11524 "description": "Forbidden",
11525 "content": {
@@ -11854,6 +11953,36 @@
11953 "schema": {
11954 "type": "object",
11955 "properties": {
11956 + "premium_charge": {
11957 + "type": "object",
11958 + "properties": {
11959 + "amount": {
11960 + "type": "string",
11961 + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
11962 + "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
11963 + },
11964 + "currency": {
11965 + "type": "string",
11966 + "enum": [
11967 + "USD"
11968 + ],
11969 + "description": "Currency of the premium charge. Always USD."
11970 + },
11971 + "charged_by": {
11972 + "type": "string",
11973 + "enum": [
11974 + "composio"
11975 + ],
11976 + "description": "Entity charging for premium usage. Always composio."
11977 + }
11978 + },
11979 + "required": [
11980 + "amount",
11981 + "currency",
11982 + "charged_by"
11983 + ],
11984 + "description": "Returned only when the session enables premium_usage.return_premium_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
11985 + },
11986 "data": {
11987 "type": "object",
11988 "additionalProperties": {},
@@ -11903,6 +12032,16 @@
12032 }
12033 }
12034 },
12035 + "402": {
12036 + "description": "Payment required",
12037 + "content": {
12038 + "application/json": {
12039 + "schema": {
12040 + "$ref": "#/components/schemas/Error"
12041 + }
12042 + }
12043 + }
12044 + },
12045 "403": {
12046 "description": "Forbidden",
12047 "content": {
@@ -12229,6 +12368,36 @@
12368 "schema": {
12369 "type": "object",
12370 "properties": {
12371 + "premium_charge": {
12372 + "type": "object",
12373 + "properties": {
12374 + "amount": {
12375 + "type": "string",
12376 + "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,12})?$",
12377 + "description": "Premium charge in USD as an exact non-negative decimal string, with up to 12 fractional digits."
12378 + },
12379 + "currency": {
12380 + "type": "string",
12381 + "enum": [
12382 + "USD"
12383 + ],
12384 + "description": "Currency of the premium charge. Always USD."
12385 + },
12386 + "charged_by": {
12387 + "type": "string",
12388 + "enum": [
12389 + "composio"
12390 + ],
12391 + "description": "Entity charging for premium usage. Always composio."
12392 + }
12393 + },
12394 + "required": [
12395 + "amount",
12396 + "currency",
12397 + "charged_by"
12398 + ],
12399 + "description": "Returned only when the session enables premium_usage.return_premium_charge and a charge is available. Failed individual tool calls omit it. Multi-execute returns one aggregate of reported charges from eligible successful calls, even if another call fails."
12400 + },
12401 "data": {
12402 "type": "object",
12403 "additionalProperties": {},
@@ -12278,6 +12447,16 @@
12447 }
12448 }
12449 },
12450 + "402": {
12451 + "description": "Payment required",
12452 + "content": {
12453 + "application/json": {
12454 + "schema": {
12455 + "$ref": "#/components/schemas/Error"
12456 + }
12457 + }
12458 + }
12459 + },
12460 "403": {
12461 "description": "Forbidden",
12462 "content": {
@@ -12445,12 +12624,17 @@
12624 "event_count": {
12625 "type": "integer",
12626 "minimum": 0
12627 + },
12628 + "premium_usage_charge": {
12629 + "type": "string",
12630 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12631 }
12632 },
12633 "required": [
12634 "unit",
12635 "total_quantity",
12453 - "event_count"
12636 + "event_count",
12637 + "premium_usage_charge"
12638 ]
12639 }
12640 }
@@ -12640,6 +12824,10 @@
12824 "type": "integer",
12825 "minimum": 0
12826 },
12827 + "premium_usage_charge": {
12828 + "type": "string",
12829 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12830 + },
12831 "groups": {
12832 "type": "array",
12833 "items": {
@@ -12654,12 +12842,17 @@
12842 "event_count": {
12843 "type": "integer",
12844 "minimum": 0
12845 + },
12846 + "premium_usage_charge": {
12847 + "type": "string",
12848 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12849 }
12850 },
12851 "required": [
12852 "key",
12853 "total_quantity",
12662 - "event_count"
12854 + "event_count",
12855 + "premium_usage_charge"
12856 ]
12857 }
12858 }
@@ -12669,6 +12862,7 @@
12862 "unit",
12863 "total_quantity",
12864 "event_count",
12865 + "premium_usage_charge",
12866 "groups"
12867 ]
12868 }
@@ -12813,12 +13007,17 @@
13007 "event_count": {
13008 "type": "integer",
13009 "minimum": 0
13010 + },
13011 + "premium_usage_charge": {
13012 + "type": "string",
13013 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13014 }
13015 },
13016 "required": [
13017 "unit",
13018 "total_quantity",
12821 - "event_count"
13019 + "event_count",
13020 + "premium_usage_charge"
13021 ]
13022 }
13023 }
@@ -12999,6 +13198,10 @@
13198 "type": "integer",
13199 "minimum": 0
13200 },
13201 + "premium_usage_charge": {
13202 + "type": "string",
13203 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13204 + },
13205 "groups": {
13206 "type": "array",
13207 "items": {
@@ -13013,12 +13216,17 @@
13216 "event_count": {
13217 "type": "integer",
13218 "minimum": 0
13219 + },
13220 + "premium_usage_charge": {
13221 + "type": "string",
13222 + "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13223 }
13224 },
13225 "required": [
13226 "key",
13227 "total_quantity",
13021 - "event_count"
13228 + "event_count",
13229 + "premium_usage_charge"
13230 ]
13231 }
13232 }
@@ -13028,6 +13236,7 @@
13236 "unit",
13237 "total_quantity",
13238 "event_count",
13239 + "premium_usage_charge",
13240 "groups"
13241 ]
13242 }
@@ -27464,6 +27673,16 @@
27673 }
27674 }
27675 },
27676 + "402": {
27677 + "description": "Payment required",
27678 + "content": {
27679 + "application/json": {
27680 + "schema": {
27681 + "$ref": "#/components/schemas/Error"
27682 + }
27683 + }
27684 + }
27685 + },
27686 "403": {
27687 "description": "Forbidden",
27688 "content": {
docs/tests/static/llms-openapi.test.ts
-7
@@ -24,13 +24,6 @@ mock.module("@/lib/meta-tools-data", () => ({
24 getAllMetaTools: async () => [],
25 getMetaToolBySlug: async () => null,
26 }));
27 -mock.module("@/lib/toolkit-schema", () => ({
28 - apiToolListSchema: { safeParse: (value: unknown) => ({ success: true, data: value }) },
29 - apiTriggerListSchema: { safeParse: (value: unknown) => ({ success: true, data: value }) },
30 - processSchema: (schema: unknown) => schema,
31 - toolFromApi: (tool: unknown) => tool,
32 - triggerFromApi: (trigger: unknown) => trigger,
33 -}));
27
28 let openapiPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").openapiPageToMarkdown;
29 let degradedPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").degradedPageToMarkdown;
ts/packages/core/src/types/toolRouter.types.ts
+2
@@ -556,6 +556,8 @@ const ToolRouterSessionSearchToolkitConnectionStatusSchema = z.object({
556 statusMessage: z.string(),
557 connectionDetails: z.record(z.string(), z.unknown()).optional(),
558 currentUserInfo: z.record(z.string(), z.unknown()).optional(),
559 + /** Present when the toolkit runs on a Composio hosted account; only these tools run on it. */
560 + hostedAccount: z.object({ allowedToolSlugs: z.array(z.string()) }).optional(),
561 });
562
563 export const ToolRouterSessionSearchResponseSchema = z.object({
ts/packages/core/src/utils/transformers/toolRouterResponseTransform.ts
+4
@@ -51,6 +51,7 @@ interface RawToolkitConnectionStatus {
51 status_message: string;
52 connection_details?: Record<string, unknown>;
53 current_user_info?: Record<string, unknown>;
54 + hosted_account?: { allowed_tool_slugs: string[] };
55 }
56
57 interface RawSearchResponse {
@@ -115,6 +116,9 @@ function transformToolkitConnectionStatus(raw: RawToolkitConnectionStatus) {
116 statusMessage: raw.status_message,
117 connectionDetails: raw.connection_details,
118 currentUserInfo: raw.current_user_info,
119 + ...(raw.hosted_account !== undefined && {
120 + hostedAccount: { allowedToolSlugs: raw.hosted_account.allowed_tool_slugs },
121 + }),
122 };
123 }
124
ts/packages/core/test/models/toolRouter.test.ts
+23
@@ -2670,6 +2670,29 @@ describe('ToolRouter', () => {
2670 );
2671 });
2672
2673 + it('should return the hosted account allowlist on toolkit connection statuses', async () => {
2674 + mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2675 + mockClient.toolRouter.session.search.mockResolvedValueOnce({
2676 + ...mockSearchResponse,
2677 + toolkit_connection_statuses: [
2678 + {
2679 + toolkit: 'exa',
2680 + description: 'Exa',
2681 + has_active_connection: true,
2682 + hosted_account: { allowed_tool_slugs: ['EXA_SEARCH'] },
2683 + status_message: 'Connected via the Composio hosted account.',
2684 + },
2685 + ],
2686 + });
2687 +
2688 + const session = await toolRouter.create(userId);
2689 + const result = await session.search({ query: 'search the web' });
2690 +
2691 + expect(result.toolkitConnectionStatuses[0].hostedAccount).toEqual({
2692 + allowedToolSlugs: ['EXA_SEARCH'],
2693 + });
2694 + });
2695 +
2696 it('should propagate search API errors', async () => {
2697 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2698 mockClient.toolRouter.session.search.mockRejectedValueOnce(new Error('Search failed'));
ts/packages/core/test/utils/toolRouterResponseTransform.test.ts
+39
@@ -131,6 +131,45 @@ describe('toolRouterResponseTransform', () => {
131 tool: 'COMPOSIO_GET_TOOL_SCHEMAS',
132 });
133 });
134 +
135 + it('maps the hosted account allowlist only when the API sends one', () => {
136 + const raw = {
137 + success: true,
138 + error: null,
139 + results: [],
140 + tool_schemas: {},
141 + toolkit_connection_statuses: [
142 + {
143 + toolkit: 'exa',
144 + description: 'Exa',
145 + has_active_connection: true,
146 + status_message: 'Connected via the Composio hosted account.',
147 + hosted_account: { allowed_tool_slugs: ['EXA_SEARCH'] },
148 + },
149 + {
150 + toolkit: 'gmail',
151 + description: 'Gmail',
152 + has_active_connection: false,
153 + status_message: 'No connection',
154 + },
155 + ],
156 + next_steps_guidance: [],
157 + session: {
158 + id: 'trs_1',
159 + generate_id: false,
160 + instructions: 'Use session',
161 + },
162 + time_info: {
163 + current_time_utc: '2025-03-09T12:00:00.000Z',
164 + current_time_utc_epoch_seconds: 1741521600,
165 + message: 'UTC',
166 + },
167 + };
168 +
169 + const [hosted, notHosted] = transformSearchResponse(raw).toolkitConnectionStatuses;
170 + expect(hosted.hostedAccount).toEqual({ allowedToolSlugs: ['EXA_SEARCH'] });
171 + expect(notHosted).not.toHaveProperty('hostedAccount');
172 + });
173 });
174
175 describe('transformExecuteResponse', () => {