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

feat(core)!: remove bare session aliases; freeze MCP SPI (#3780)

## What and why This makes the intended v1 API cleanup real rather than postponing it to v2: - Remove the TypeScript root aliases `composio.create(...)` and `composio.use(...)`. Session creation and reuse now live only at `composio.sessions.create(...)` and `composio.sessions.use(...)`. This is a deliberate breaking change, reflected by a major changeset. - Retain `BaseProvider.wrapMcpServerResponse` as the stable v1 provider SPI. Its earlier deprecation pointed to a method that was never introduced. The scope is intentionally narrow: it does **not** remove unrelated deprecated APIs, and Python keeps its supported `Composio.create/use` API. The TypeScript docs, examples, providers, runtime fixtures, generated SDK reference, and API-reference indexes now use the namespaced TypeScript API. Historical changelog examples are left as history. ## Verification - `pnpm typecheck` - `pnpm --filter @composio/core test -- --run test/core/session.test.ts` (42 files, 1,018 tests) - `pnpm exec eslint ts/packages/core/src/composio.ts` - `pnpm --filter @composio/core generate:docs` - `cd docs && bun run generate:api-index` - `cd docs && bun run types:check` - `git diff --check` and targeted scans for removed TypeScript aliases I also attempted the affected Node and Cloudflare runtime E2E suites. They cannot initialize in this checkout without `COMPOSIO_API_KEY` (and, for Cloudflare, `COMPOSIO_BASE_URL` and `OPENAI_API_KEY`); they did not report a product assertion failure.

Alberto Schiabel committed Jul 13, 2026 at 13:22 UTC 0de52639c47f642f9ba3aa7fa9e42bdf5afe8a9f
107 files changed +302 -350
.changeset/deprecate-session-aliases-freeze-mcp-spi.md new
+8
@@ -0,0 +1,8 @@
1 +---
2 +'@composio/core': major
3 +---
4 +
5 +Two v1 freeze-hygiene fixes:
6 +
7 +- **Remove the bare `composio.create(...)` / `composio.use(...)` aliases** in favour of `composio.sessions.create(...)` / `composio.sessions.use(...)`, so the root object hosts namespaces rather than generic verbs. This is a breaking TypeScript SDK change.
8 +- **Un-deprecate `BaseProvider.wrapMcpServerResponse`** and freeze it as the stable v1 SPI method. Its `@deprecated` note pointed at a plural `wrapMcpServers` method that was never added; the singular method is the frozen contract.
README.md
+3 -3
@@ -52,7 +52,7 @@ import { Agent, run } from "@openai/agents";
52 const composio = new Composio({ provider: new OpenAIAgentsProvider() });
53
54 // Each session is scoped to one of your users
55 -const session = await composio.create("user_123");
55 +const session = await composio.sessions.create("user_123");
56 const tools = await session.tools();
57
58 const agent = new Agent({
@@ -92,9 +92,9 @@ result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from t
92 print(result.final_output)
93 ```
94
95 -By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store `session.session_id` and reuse it with `composio.use()` across turns. See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.
95 +By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store `session.sessionId` and reuse it with `composio.sessions.use()` in TypeScript; Python uses `session.session_id` and `composio.use()`. See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.
96
97 -**Prefer MCP?** Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to `composio.create()` and point Claude, Cursor, or any MCP client at `session.mcp.url`. See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).
97 +**Prefer MCP?** Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to TypeScript's `composio.sessions.create()` or `mcp=True` to Python's `composio.create()`, then point Claude, Cursor, or any MCP client at `session.mcp.url`. See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).
98
99 ## CLI
100
docs/agent/instructions.md
+1 -1
@@ -26,7 +26,7 @@ Workflow for anything non-trivial:
26 ## Rules
27
28 - **Never lead with or link legacy / direct-execution docs** (`/docs/sessions-vs-direct-execution`, `/docs/tools-direct/*`, `/docs/auth-configuration/*`) unless the user explicitly asks about the low-level direct-execution API. Always answer with the current, session-based model.
29 -- Prefer the current API in examples: `composio.create(userId)` / `composio.sessions.create(...)`, session tools, meta tools, and `{ mcp: true }` for MCP.
29 +- Prefer the current API in examples: TypeScript uses `composio.sessions.create(userId)`, Python uses `composio.create(user_id)`, plus session tools, meta tools, and `{ mcp: true }` / `mcp=True` for MCP.
30 - Don't claim something is supported unless a page says so.
31 - Cite **only** as standard Markdown links, e.g. `[Authentication](/docs/authentication)`. Never emit citation markers, reference tokens, or anything like `cite`/`turn0search0`.
32
docs/agent/instructions/context.md
+2 -2
@@ -4,10 +4,10 @@ This is your always-on map of Composio's concepts and the canonical page for eac
4
5 ## Core model
6
7 -- **Session** — the runtime context for one user. `composio.create(userId)` (or the canonical `composio.sessions.create(...)`) returns a session that ties together the user, toolkits, authentication, connected accounts, and a code-execution sandbox. By default it exposes meta tools the agent calls at runtime to discover, authenticate, and execute tools. → [What is a session?](/docs/how-composio-works)
7 +- **Session** — the runtime context for one user. In TypeScript, `composio.sessions.create(userId)` returns a session; Python uses `composio.create(user_id)`. It ties together the user, toolkits, authentication, connected accounts, and a code-execution sandbox. By default it exposes meta tools the agent calls at runtime to discover, authenticate, and execute tools. → [What is a session?](/docs/how-composio-works)
8 - **Configuring a session** — filter toolkits and tools, set auth configs, select connected accounts, preload tools, the direct-tools preset, sandbox tier, and session methods (`tools()`, `toolkits()`, `authorize()`). → [Configuring sessions](/docs/configuring-sessions)
9 - **Sessions via MCP** — create a session with `{ mcp: true }` to expose `session.mcp.url` / `session.mcp.headers` for any MCP client. → [Using sessions via MCP](/docs/sessions-via-mcp)
10 -- **Reusing sessions** — sessions persist on the server; store the session ID and reuse with `composio.use(sessionId)`, or update in place with `session.update(...)`. → [What is a session?](/docs/how-composio-works)
10 +- **Reusing sessions** — sessions persist on the server; store the session ID and reuse it with TypeScript's `composio.sessions.use(sessionId)` or Python's `composio.use(session_id)`, or update in place with `session.update(...)`. → [What is a session?](/docs/how-composio-works)
11
12 ## Tools and toolkits
13
docs/agent/knowledge.md
+2 -2
@@ -6,7 +6,7 @@ here to expose more answers to search without changing the docs themselves.
6
7 ## Installing and getting started (/docs/quickstart)
8
9 -Install the SDK with `npm install @composio/core` (TypeScript) or `pip install composio` (Python), set `COMPOSIO_API_KEY`, then create a session with `composio.create("user_123")`. The quickstart walks through creating a session, fetching tools for your framework via a provider, and running an agent.
9 +Install the SDK with `npm install @composio/core` (TypeScript) or `pip install composio` (Python), set `COMPOSIO_API_KEY`, then create a session with `composio.sessions.create("user_123")` in TypeScript or `composio.create(user_id="user_123")` in Python. The quickstart walks through creating a session, fetching tools for your framework via a provider, and running an agent.
10
11 ## Choosing a provider (/docs/providers)
12
@@ -26,4 +26,4 @@ The sandbox has a persistent file mount at `/mnt/files/` that survives sandbox r
26
27 ## Reusing and updating sessions (/docs/how-composio-works)
28
29 -Sessions persist on the server and do not expire. For a multi-turn conversation, store the session ID and reuse it with `composio.use(sessionId)` instead of calling `create()` again. You can also change a live session in place with `session.update({ toolkits, authConfigs, connectedAccounts })`.
29 +Sessions persist on the server and do not expire. For a multi-turn conversation, store the session ID and reuse it with `composio.sessions.use(sessionId)` in TypeScript or `composio.use(session_id)` in Python instead of creating another session. You can also change a live session in place with `session.update({ toolkits, authConfigs, connectedAccounts })`.
docs/api-overviews/mcp.mdx
+2 -2
@@ -1,9 +1,9 @@
1 <Callout type="warning">
2 -This API is deprecated. Use a session's MCP endpoint instead. Create a session with `composio.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
2 +This API is deprecated. Use a session's MCP endpoint instead. In TypeScript, create a session with `composio.sessions.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
3 </Callout>
4
5 The MCP API is the standalone, hosted [Model Context Protocol](https://modelcontextprotocol.io) server-management surface. It let you stand up and manage a separate server config per toolkit, then mint a per-user MCP URL that any MCP-compatible client could connect to.
6
7 These endpoints create, list, update, and delete MCP servers, including custom servers spanning multiple apps, generate per-user MCP URLs, and manage per-user server instances and their connected accounts.
8
9 -Sessions replace this. A single `composio.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
9 +Sessions replace this. In TypeScript, a single `composio.sessions.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
docs/api-overviews/tool-router.mdx
+1 -1
@@ -4,7 +4,7 @@ These are Composio's session endpoints. A **session** is the runtime context you
4 Sessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.
5 </Callout>
6
7 -In the SDK you do not call these endpoints directly. Use `composio.create(...)` to start a session and `composio.use(...)` to resume one, then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
7 +In the SDK you do not call these endpoints directly. In TypeScript, use `composio.sessions.create(...)` to start a session and `composio.sessions.use(...)` to resume one; Python uses `composio.create(...)` and `composio.use(...)`. Then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
8
9 Reach for the raw API when you need lower-level control: creating and patching a session config, attaching to an existing session, searching for tools, executing tools and meta tools, opening link sessions for auth, proxying authenticated requests, and reading or writing files in a session mount.
10
docs/api-overviews/webhook-subscriptions.mdx
+1 -1
@@ -111,7 +111,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
111 const toolkit = payload.data.toolkit.slug;
112
113 // Look up the user and send them a re-auth link
114 - const session = await composio.create(lookupUser(accountId));
114 + const session = await composio.sessions.create(lookupUser(accountId));
115 const connectionRequest = await session.authorize(toolkit);
116 if (connectionRequest.redirectUrl) {
117 notifyUser(connectionRequest.redirectUrl);
docs/app/llms.txt/route.ts
+1 -1
@@ -109,7 +109,7 @@ export async function GET() {
109
110 > Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
111
112 -> **For AI agents:** Give your agent tools it can call directly with \`composio.create(user_id)\` + \`session.tools()\` and a provider package (e.g. \`composio_openai\`, \`@composio/openai\`). To connect over MCP instead, create the session with \`mcp: true\` and read \`session.mcp.url\` from any MCP-compatible client. See any page's .md endpoint for full usage instructions.
112 +> **For AI agents:** Give your agent tools it can call directly with \`composio.sessions.create(user_id)\` + \`session.tools()\` and a provider package (e.g. \`composio_openai\`, \`@composio/openai\`). To connect over MCP instead, create the session with \`mcp: true\` and read \`session.mcp.url\` from any MCP-compatible client. See any page's .md endpoint for full usage instructions.
113
114 ${docsTree}
115
docs/content/docs/authentication.mdx
+2 -2
@@ -72,7 +72,7 @@ session = composio.create(
72 import { Composio } from '@composio/core';
73 const composio = new Composio({ apiKey: 'your_api_key' });
74 // ---cut---
75 -const session = await composio.create("user_123", {
75 +const session = await composio.sessions.create("user_123", {
76 manageConnections: { callbackUrl: "https://yourapp.com/chat" },
77 });
78 ```
@@ -124,7 +124,7 @@ print(connection_request.redirect_url)
124 import { Composio } from '@composio/core';
125 const composio = new Composio({ apiKey: 'your_api_key' });
126 // ---cut---
127 -const session = await composio.create("user_123");
127 +const session = await composio.sessions.create("user_123");
128 const connectionRequest = await session.authorize("gmail");
129
130 // Send this URL to the user (email, in-app notification, etc.)
docs/content/docs/configuring-sessions.mdx
+23 -23
@@ -17,7 +17,7 @@ session = composio.create(user_id="user_123")
17 import { Composio } from '@composio/core';
18 const composio = new Composio({ apiKey: 'your_api_key' });
19 // ---cut---
20 -const session = await composio.create("user_123");
20 +const session = await composio.sessions.create("user_123");
21 ```
22 </Tab>
23 </Tabs>
@@ -52,12 +52,12 @@ import { Composio } from '@composio/core';
52 const composio = new Composio({ apiKey: 'your_api_key' });
53 // ---cut---
54 // Using array format
55 -const session = await composio.create("user_123", {
55 +const session = await composio.sessions.create("user_123", {
56 toolkits: ["github", "gmail", "slack"],
57 });
58
59 // Using object format with enable key
60 -const session2 = await composio.create("user_123", {
60 +const session2 = await composio.sessions.create("user_123", {
61 toolkits: { enable: ["github", "gmail", "slack"] },
62 });
63 ```
@@ -82,7 +82,7 @@ session = composio.create(
82 import { Composio } from '@composio/core';
83 const composio = new Composio({ apiKey: 'your_api_key' });
84 // ---cut---
85 -const session = await composio.create("user_123", {
85 +const session = await composio.sessions.create("user_123", {
86 toolkits: { disable: ["exa", "firecrawl"] },
87 });
88 ```
@@ -136,7 +136,7 @@ const composio = new Composio({
136 provider: new OpenAIAgentsProvider(),
137 });
138 // ---cut---
139 -const session = await composio.create("user_123", {
139 +const session = await composio.sessions.create("user_123", {
140 toolkits: ["gmail"],
141 tools: {
142 gmail: {
@@ -209,7 +209,7 @@ const composio = new Composio({
209 provider: new OpenAIAgentsProvider(),
210 });
211 // ---cut---
212 -const session = await composio.create("user_123", {
212 +const session = await composio.sessions.create("user_123", {
213 toolkits: ["gmail"],
214 tools: {
215 gmail: {
@@ -261,7 +261,7 @@ session = composio.create(
261 import { Composio } from '@composio/core';
262 const composio = new Composio({ apiKey: 'your_api_key' });
263 // ---cut---
264 -const session = await composio.create("user_123", {
264 +const session = await composio.sessions.create("user_123", {
265 tools: {
266 // Only these Gmail tools will be available
267 gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
@@ -292,7 +292,7 @@ session = composio.create(
292 import { Composio } from '@composio/core';
293 const composio = new Composio({ apiKey: 'your_api_key' });
294 // ---cut---
295 -const session = await composio.create("user_123", {
295 +const session = await composio.sessions.create("user_123", {
296 tools: {
297 gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
298 github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
@@ -323,7 +323,7 @@ session = composio.create(
323 import { Composio } from '@composio/core';
324 const composio = new Composio({ apiKey: 'your_api_key' });
325 // ---cut---
326 -const session = await composio.create("user_123", {
326 +const session = await composio.sessions.create("user_123", {
327 tools: {
328 // All Slack tools except delete
329 slack: { disable: ["SLACK_DELETE_MESSAGE"] },
@@ -373,12 +373,12 @@ import { Composio } from '@composio/core';
373 const composio = new Composio({ apiKey: 'your_api_key' });
374 // ---cut---
375 // Only include read-only and idempotent tools
376 -const session = await composio.create("user_123", {
376 +const session = await composio.sessions.create("user_123", {
377 tags: ["readOnlyHint", "idempotentHint"]
378 });
379
380 // Enable some tags, disable others
381 -const sessionWithTagConfig = await composio.create("user_123", {
381 +const sessionWithTagConfig = await composio.sessions.create("user_123", {
382 tags: {
383 enable: ["readOnlyHint"],
384 disable: ["destructiveHint"]
@@ -411,7 +411,7 @@ session = composio.create(
411 import { Composio } from '@composio/core';
412 const composio = new Composio({ apiKey: 'your_api_key' });
413 // ---cut---
414 -const session = await composio.create("user_123", {
414 +const session = await composio.sessions.create("user_123", {
415 // Global: only read-only tools
416 tags: ["readOnlyHint"],
417 tools: {
@@ -484,7 +484,7 @@ const composio = new Composio({
484 provider: new OpenAIAgentsProvider(),
485 });
486 // ---cut---
487 -const session = await composio.create("user_123", {
487 +const session = await composio.sessions.create("user_123", {
488 toolkits: ["gmail"],
489 preload: {
490 tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
@@ -526,7 +526,7 @@ session = composio.create(
526 import { Composio } from '@composio/core';
527 const composio = new Composio({ apiKey: 'your_api_key' });
528 // ---cut---
529 -const session = await composio.create("user_123", {
529 +const session = await composio.sessions.create("user_123", {
530 authConfigs: {
531 github: "ac_your_github_config",
532 slack: "ac_your_slack_config",
@@ -559,7 +559,7 @@ session = composio.create(
559 import { Composio } from '@composio/core';
560 const composio = new Composio({ apiKey: 'your_api_key' });
561 // ---cut---
562 -const session = await composio.create("user_123", {
562 +const session = await composio.sessions.create("user_123", {
563 connectedAccounts: {
564 gmail: ["ca_work_gmail"],
565 github: ["ca_personal_github"],
@@ -606,7 +606,7 @@ session = composio.create(
606 import { Composio } from '@composio/core';
607 const composio = new Composio({ apiKey: 'your_api_key' });
608 // ---cut---
609 -const session = await composio.create("user_123", {
609 +const session = await composio.sessions.create("user_123", {
610 sandbox: {
611 enable: false,
612 },
@@ -659,7 +659,7 @@ session = composio.create(
659 import { Composio } from '@composio/core';
660 const composio = new Composio({ apiKey: 'your_api_key' });
661 // ---cut---
662 -const session = await composio.create("user_123", {
662 +const session = await composio.sessions.create("user_123", {
663 sandbox: {
664 enable: true,
665 sandboxSize: "large",
@@ -693,7 +693,7 @@ tools = session.tools()
693 ```typescript
694 import { Composio } from '@composio/core';
695 const composio = new Composio({ apiKey: 'your_api_key' });
696 -const session = await composio.create("user_123");
696 +const session = await composio.sessions.create("user_123");
697 // ---cut---
698 const tools = await session.tools();
699 ```
@@ -718,7 +718,7 @@ connected_account = connection_request.wait_for_connection()
718 ```typescript
719 import { Composio } from '@composio/core';
720 const composio = new Composio({ apiKey: 'your_api_key' });
721 -const session = await composio.create("user_123");
721 +const session = await composio.sessions.create("user_123");
722 // ---cut---
723 const connectionRequest = await session.authorize("github", {
724 callbackUrl: "https://myapp.com/callback",
@@ -751,7 +751,7 @@ for toolkit in toolkits.items:
751 ```typescript
752 import { Composio } from '@composio/core';
753 const composio = new Composio({ apiKey: 'your_api_key' });
754 -const session = await composio.create("user_123");
754 +const session = await composio.sessions.create("user_123");
755 // ---cut---
756 const toolkits = await session.toolkits();
757
@@ -774,7 +774,7 @@ connected = session.toolkits(is_connected=True)
774 ```typescript
775 import { Composio } from '@composio/core';
776 const composio = new Composio({ apiKey: 'your_api_key' });
777 -const session = await composio.create("user_123");
777 +const session = await composio.sessions.create("user_123");
778 // ---cut---
779 const connected = await session.toolkits({ isConnected: true });
780 ```
@@ -801,7 +801,7 @@ while True:
801 ```typescript
802 import { Composio } from '@composio/core';
803 const composio = new Composio({ apiKey: 'your_api_key' });
804 -const session = await composio.create("user_123");
804 +const session = await composio.sessions.create("user_123");
805 // ---cut---
806 const allToolkits: any[] = [];
807 let cursor: string | undefined;
@@ -834,7 +834,7 @@ print(result["session_id"], result["deleted"])
834 ```typescript
835 import { Composio } from '@composio/core';
836 const composio = new Composio({ apiKey: 'your_api_key' });
837 -const session = await composio.create('user_123');
837 +const session = await composio.sessions.create('user_123');
838 // ---cut---
839 const result = await session.delete();
840 console.log(result.sessionId, result.deleted);
docs/content/docs/controlling-scopes.mdx
+1 -1
@@ -141,7 +141,7 @@ import { Composio } from '@composio/core';
141 const composio = new Composio({ apiKey: 'your_api_key' });
142 const authConfig = { id: 'ac_your_github_config' };
143 // ---cut---
144 -const session = await composio.create('user_123', {
144 +const session = await composio.sessions.create('user_123', {
145 authConfigs: { github: authConfig.id },
146 });
147 ```
docs/content/docs/custom-app-vs-managed-app.mdx
+2 -2
@@ -91,7 +91,7 @@ session = composio.create(
91 import { Composio } from '@composio/core';
92
93 const composio = new Composio();
94 -const session = await composio.create("user_123", {
94 +const session = await composio.sessions.create("user_123", {
95 authConfigs: {
96 github: "ac_your_github_config",
97 // toolkits not listed here still use Composio managed auth
@@ -125,7 +125,7 @@ session = composio.create(
125 import { Composio } from '@composio/core';
126 const composio = new Composio();
127 // ---cut---
128 -const session = await composio.create("user_123", {
128 +const session = await composio.sessions.create("user_123", {
129 authConfigs: {
130 github: "ac_your_github_config",
131 google: "ac_your_google_config",
docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdx
+7 -7
@@ -132,7 +132,7 @@ declare const getUserProfile: ReturnType<typeof experimental_createTool>;
132 const composio = new Composio({ apiKey: "your_api_key" });
133 // ---cut---
134
135 -const session = await composio.create("user_1", {
135 +const session = await composio.sessions.create("user_1", {
136 experimental: {
137 customTools: [getUserProfile],
138 },
@@ -294,7 +294,7 @@ declare const sendPromoEmail: ReturnType<typeof experimental_createTool>;
294 const composio = new Composio({ apiKey: "your_api_key" });
295 // ---cut---
296
297 -const session = await composio.create("user_1", {
297 +const session = await composio.sessions.create("user_1", {
298 toolkits: ["gmail"],
299 experimental: {
300 customTools: [sendPromoEmail],
@@ -439,7 +439,7 @@ declare const userManagement: ReturnType<typeof experimental_createToolkit>;
439 const composio = new Composio({ apiKey: "your_api_key" });
440 // ---cut---
441
442 -const session = await composio.create("user_1", {
442 +const session = await composio.sessions.create("user_1", {
443 experimental: {
444 customToolkits: [userManagement],
445 },
@@ -500,7 +500,7 @@ const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {
500 execute: async ({ topic }) => ({ topic, tone: "concise and helpful" }),
501 });
502
503 -const session = await composio.create("user_1", {
503 +const session = await composio.sessions.create("user_1", {
504 experimental: {
505 customTools: [replyGuide],
506 },
@@ -603,7 +603,7 @@ Use these methods to list registered tools and toolkits. Slugs include their fin
603 ```typescript
604 import { Composio } from "@composio/core";
605 const composio = new Composio({ apiKey: "your_api_key" });
606 -const session = await composio.create("user_1");
606 +const session = await composio.sessions.create("user_1");
607 // ---cut---
608 const customTools = session.customTools();
609 const customToolkits = session.customToolkits();
@@ -631,7 +631,7 @@ declare const getUserProfile: ReturnType<typeof experimental_createTool>;
631 const composio = new Composio({ apiKey: "your_api_key" });
632 // ---cut---
633
634 -const session = await composio.use("session_id", {
634 +const session = await composio.sessions.use("session_id", {
635 customTools: [getUserProfile],
636 });
637 ```
@@ -659,7 +659,7 @@ Use `session.execute()` to run custom tools directly, outside of an agent loop.
659 ```typescript
660 import { Composio } from "@composio/core";
661 const composio = new Composio({ apiKey: "your_api_key" });
662 -const session = await composio.create("user_1");
662 +const session = await composio.sessions.create("user_1");
663 // ---cut---
664 const result = await session.execute("GET_USER_PROFILE");
665 ```
docs/content/docs/extending-sessions/proxy-execute.mdx
+1 -1
@@ -46,7 +46,7 @@ print(response.data)
46 ```typescript
47 import { Composio } from '@composio/core';
48 const composio = new Composio({ apiKey: 'your_api_key' });
49 -const session = await composio.create('user_123', { toolkits: ['github'] });
49 +const session = await composio.sessions.create('user_123', { toolkits: ['github'] });
50 // ---cut---
51 const { status, data } = await session.proxyExecute({
52 toolkit: 'github',
docs/content/docs/how-composio-works.mdx
+6 -6
@@ -4,7 +4,7 @@ description: What Composio sessions do, and how they scope users, tools, toolkit
4 keywords: [session, userID, tools, toolkits, meta tools, mcp, workbench]
5 ---
6
7 -A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. You create it with `composio.create(userId)`, and it ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
7 +A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. In TypeScript, you create it with `composio.sessions.create(userId)`; Python uses `composio.create(user_id)`. It ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
8
9 ## The basics
10
@@ -23,7 +23,7 @@ tools = session.tools()
23 import { Composio } from '@composio/core';
24 const composio = new Composio({ apiKey: 'your_api_key' });
25 // ---cut---
26 -const session = await composio.create("user_123");
26 +const session = await composio.sessions.create("user_123");
27
28 const tools = await session.tools();
29 ```
@@ -86,9 +86,9 @@ The sandbox is scoped to the session, so files, variables, helper functions, and
86
87 ## How sessions behave
88
89 -Every `create()` call returns a new session ID. Use it for a fresh task context.
89 +Every session-creation call returns a new session ID. Use it for a fresh task context.
90
91 -Sessions persist on the server and don't expire. For multi-turn conversations, store the session ID and reuse it with `composio.use()` instead of calling `create()` again.
91 +Sessions persist on the server and don't expire. For multi-turn conversations, store the session ID and reuse it with TypeScript's `composio.sessions.use()` or Python's `composio.use()` instead of creating another session.
92
93 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
94 <Tab value="Python">
@@ -102,7 +102,7 @@ tools = session.tools()
102 import { Composio } from '@composio/core';
103 const composio = new Composio({ apiKey: 'your_api_key' });
104 // ---cut---
105 -const session = await composio.use("session_id");
105 +const session = await composio.sessions.use("session_id");
106 const tools = await session.tools();
107 ```
108 </Tab>
@@ -124,7 +124,7 @@ session.update(
124 ```typescript
125 import { Composio } from '@composio/core';
126 const composio = new Composio({ apiKey: 'your_api_key' });
127 -const session = await composio.use("session_id");
127 +const session = await composio.sessions.use("session_id");
128 // ---cut---
129 await session.update({
130 toolkits: ["gmail", "slack"],
docs/content/docs/importing-existing-connections.mdx
+1 -1
@@ -316,7 +316,7 @@ session = composio.create(
316 import { Composio } from '@composio/core';
317 const composio = new Composio({ apiKey: 'your-api-key' });
318 // ---cut---
319 -const session = await composio.create('user_123', {
319 +const session = await composio.sessions.create('user_123', {
320 authConfigs: { gmail: 'ac_your_auth_config' },
321 toolkits: ['gmail'],
322 });
docs/content/docs/managing-multiple-connected-accounts.mdx
+5 -5
@@ -29,7 +29,7 @@ session = composio.create(
29 import { Composio } from '@composio/core';
30 const composio = new Composio({ apiKey: 'your_api_key' });
31 // ---cut---
32 -const session = await composio.create("user_123", {
32 +const session = await composio.sessions.create("user_123", {
33 toolkits: ["gmail"],
34 multiAccount: {
35 enable: true,
@@ -76,7 +76,7 @@ personal_connection = personal_auth.wait_for_connection()
76 import { Composio } from '@composio/core';
77 const composio = new Composio({ apiKey: 'your_api_key' });
78 // ---cut---
79 -const session = await composio.create("user_123", {
79 +const session = await composio.sessions.create("user_123", {
80 toolkits: ["gmail"],
81 multiAccount: { enable: true },
82 });
@@ -118,7 +118,7 @@ connection_request = session.authorize("gmail", alias="work-gmail")
118 // @noErrors
119 import { Composio } from '@composio/core';
120 const composio = new Composio({ apiKey: 'your_api_key' });
121 -const session = await composio.create("user_123");
121 +const session = await composio.sessions.create("user_123");
122 // ---cut---
123 const connectionRequest = await session.authorize("gmail", { alias: "work-gmail" });
124 ```
@@ -176,7 +176,7 @@ session = composio.create(
176 import { Composio } from '@composio/core';
177 const composio = new Composio({ apiKey: 'your_api_key' });
178 // ---cut---
179 -const session = await composio.create("user_123", {
179 +const session = await composio.sessions.create("user_123", {
180 connectedAccounts: {
181 gmail: ["ca_work_gmail_id"],
182 github: ["ca_personal_github_id"],
@@ -205,7 +205,7 @@ for toolkit in toolkits.items:
205 // @noErrors
206 import { Composio } from '@composio/core';
207 const composio = new Composio({ apiKey: 'your_api_key' });
208 -const session = await composio.create("user_123");
208 +const session = await composio.sessions.create("user_123");
209 // ---cut---
210 const toolkits = await session.toolkits();
211
docs/content/docs/manually-authenticating.mdx
+5 -5
@@ -31,7 +31,7 @@ print(f"Connected: {connected_account.id}")
31 import { Composio } from '@composio/core';
32 const composio = new Composio({ apiKey: 'your_api_key' });
33 // ---cut---
34 -const session = await composio.create("user_123");
34 +const session = await composio.sessions.create("user_123");
35
36 const connectionRequest = await session.authorize("gmail");
37
@@ -69,7 +69,7 @@ print(connection_request.redirect_url)
69 ```typescript
70 import { Composio } from '@composio/core';
71 const composio = new Composio({ apiKey: 'your_api_key' });
72 -const session = await composio.create("user_123");
72 +const session = await composio.sessions.create("user_123");
73 // ---cut---
74 const connectionRequest = await session.authorize("gmail", {
75 callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding",
@@ -109,7 +109,7 @@ for toolkit in toolkits.items:
109 ```typescript
110 import { Composio } from '@composio/core';
111 const composio = new Composio({ apiKey: 'your_api_key' });
112 -const session = await composio.create("user_123");
112 +const session = await composio.sessions.create("user_123");
113 // ---cut---
114 const toolkits = await session.toolkits();
115
@@ -138,7 +138,7 @@ session = composio.create(
138 import { Composio } from '@composio/core';
139 const composio = new Composio({ apiKey: 'your_api_key' });
140 // ---cut---
141 -const session = await composio.create("user_123", {
141 +const session = await composio.sessions.create("user_123", {
142 manageConnections: false,
143 });
144 ```
@@ -187,7 +187,7 @@ const composio = new Composio({ apiKey: "your-api-key" });
187
188 const requiredToolkits = ["gmail", "github"];
189
190 -const session = await composio.create("user_123", {
190 +const session = await composio.sessions.create("user_123", {
191 manageConnections: false, // Disable in-chat auth prompts
192 });
193
docs/content/docs/migration-guide/direct-to-sessions.mdx
+6 -6
@@ -57,7 +57,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });
57 // const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB", "SLACK"] });
58
59 // After: create a session with your existing auth configs
60 -const session = await composio.create("user_123", {
60 +const session = await composio.sessions.create("user_123", {
61 authConfigs: {
62 github: "ac_your_github_config",
63 slack: "ac_your_slack_config",
@@ -90,7 +90,7 @@ tools = session.tools()
90 ```typescript
91 import { Composio } from '@composio/core';
92 const composio = new Composio({ apiKey: 'your_api_key' });
93 -const session = await composio.create("user_123");
93 +const session = await composio.sessions.create("user_123");
94 // ---cut---
95 // Before: manually specifying which tools to fetch
96 // const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB"] });
@@ -130,7 +130,7 @@ connected_account = connection_request.wait_for_connection()
130 ```typescript
131 import { Composio } from '@composio/core';
132 const composio = new Composio({ apiKey: 'your_api_key' });
133 -const session = await composio.create("user_123");
133 +const session = await composio.sessions.create("user_123");
134 // ---cut---
135 // Before: manual auth flow
136 // const connectionRequest = await composio.connectedAccounts.link("user_123", "ac_your_github_config", {
@@ -186,7 +186,7 @@ import { Composio } from '@composio/core';
186
187 // After: no version management needed
188 const composio = new Composio({ apiKey: 'your_api_key' });
189 -const session = await composio.create("user_123");
189 +const session = await composio.sessions.create("user_123");
190 ```
191 </Tab>
192 </Tabs>
@@ -217,7 +217,7 @@ session = composio.create(
217 import { Composio } from '@composio/core';
218 const composio = new Composio({ apiKey: 'your_api_key' });
219 // ---cut---
220 -const session = await composio.create("user_123", {
220 +const session = await composio.sessions.create("user_123", {
221 toolkits: ["github", "gmail", "slack"],
222 authConfigs: {
223 github: "ac_your_github_config",
@@ -252,7 +252,7 @@ session = composio.create(
252 import { Composio } from '@composio/core';
253 const composio = new Composio({ apiKey: 'your_api_key' });
254 // ---cut---
255 -const session = await composio.create("user_123", {
255 +const session = await composio.sessions.create("user_123", {
256 authConfigs: {
257 gmail: "ac_your_gmail_config",
258 },
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+4 -4
@@ -101,7 +101,7 @@ const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
101 // const mcpUrl = instance.url;
102
103 // After: one session, same toolkit + auth config + tools
104 -const session = await composio.create("user-123", {
104 +const session = await composio.sessions.create("user-123", {
105 toolkits: ["gmail"],
106 authConfigs: { gmail: "ac_xyz123" },
107 tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },
@@ -158,7 +158,7 @@ import { Composio, SessionPreset } from '@composio/core';
158
159 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
160 // ---cut---
161 -const session = await composio.create("user-123", {
161 +const session = await composio.sessions.create("user-123", {
162 toolkits: ["gmail"],
163 authConfigs: { gmail: "ac_xyz123" },
164 tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },
@@ -195,7 +195,7 @@ tools = session.tools()
195 ```typescript
196 import { Composio } from '@composio/core';
197 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
198 -const session = await composio.create("user-123");
198 +const session = await composio.sessions.create("user-123");
199 // ---cut---
200 const tools = await session.tools();
201 ```
@@ -219,7 +219,7 @@ result = session.execute(
219 ```typescript
220 import { Composio } from '@composio/core';
221 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
222 -const session = await composio.create("user-123");
222 +const session = await composio.sessions.create("user-123");
223 // ---cut---
224 const result = await session.execute("GITHUB_CREATE_ISSUE", {
225 owner: "my-org",
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -614,7 +614,7 @@ const getIssueInfo = experimental_createTool("GET_ISSUE_INFO", {
614 },
615 });
616
617 -const session = await composio.create("default", {
617 +const session = await composio.sessions.create("default", {
618 experimental: { customTools: [getIssueInfo] },
619 });
620 ```
docs/content/docs/migration-guide/tool-router-beta.mdx
+2 -2
@@ -54,7 +54,7 @@ session = composio.create(
54 const session = await composio.experimental.toolRouter.createSession('user_123');
55
56 // Stable (after)
57 -const session = await composio.create('user_123');
57 +const session = await composio.sessions.create('user_123');
58 ```
59 </Tab>
60 </Tabs>
@@ -87,7 +87,7 @@ session = composio.create(
87 import { Composio } from '@composio/core';
88 const composio = new Composio({ apiKey: 'your_api_key' });
89 // ---cut---
90 -const session = await composio.create('user_123',
90 +const session = await composio.sessions.create('user_123',
91 {
92 authConfigs: {
93 github: "ac_your_github_config",
docs/content/docs/programmatic-auth-configs.mdx
+1 -1
@@ -151,7 +151,7 @@ import { Composio } from '@composio/core';
151 const composio = new Composio({ apiKey: 'your_api_key' });
152 const authConfig = { id: 'ac_your_notion_config' };
153 // ---cut---
154 -const session = await composio.create('user_123', {
154 +const session = await composio.sessions.create('user_123', {
155 authConfigs: { notion: authConfig.id },
156 });
157 ```
docs/content/docs/providers/anthropic.mdx
+2 -2
@@ -113,7 +113,7 @@ const composio = new Composio({
113 const client = new Anthropic();
114
115 // Create a session for your user
116 -const session = await composio.create("user_123");
116 +const session = await composio.sessions.create("user_123");
117 const tools = await session.tools();
118
119 const messages: Anthropic.MessageParam[] = [
@@ -236,7 +236,7 @@ const composio = new Composio({
236 });
237
238 // Create a session for your user
239 -const session = await composio.create("user_123");
239 +const session = await composio.sessions.create("user_123");
240 const tools = await session.tools();
241 const toolServer = createSdkMcpServer({
242 name: "composio",
docs/content/docs/providers/google.mdx
+1 -1
@@ -87,7 +87,7 @@ const composio = new Composio({
87 const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });
88
89 // Create a session for your user
90 -const session = await composio.create("user_123");
90 +const session = await composio.sessions.create("user_123");
91 const tools = await session.tools();
92
93 const chat = ai.chats.create({
docs/content/docs/providers/langchain.mdx
+1 -1
@@ -80,7 +80,7 @@ const composio = new Composio({
80 });
81
82 // Create a session for your user
83 -const session = await composio.create("user_123");
83 +const session = await composio.sessions.create("user_123");
84 const tools = await session.tools();
85
86 const toolNode = new ToolNode(tools);
docs/content/docs/providers/llamaindex.mdx
+1 -1
@@ -75,7 +75,7 @@ const composio = new Composio({
75 });
76
77 // Create a session for your user
78 -const session = await composio.create("user_123");
78 +const session = await composio.sessions.create("user_123");
79 const tools = await session.tools();
80
81 const myAgent = agent({
docs/content/docs/providers/mastra.mdx
+1 -1
@@ -40,7 +40,7 @@ const composio = new Composio({
40 });
41
42 // Create a session for your user
43 -const session = await composio.create("user_123");
43 +const session = await composio.sessions.create("user_123");
44 const tools = await session.tools();
45
46 const agent = new Agent({
docs/content/docs/providers/openai.mdx
+3 -3
@@ -114,7 +114,7 @@ const composio = new Composio({
114 const client = new OpenAI();
115
116 // Create a session for your user
117 -const session = await composio.create("user_123");
117 +const session = await composio.sessions.create("user_123");
118 const tools = await session.tools();
119
120 let response = await client.responses.create({
@@ -254,7 +254,7 @@ const composio = new Composio({
254 const client = new OpenAI();
255
256 // Create a session for your user
257 -const session = await composio.create("user_123");
257 +const session = await composio.sessions.create("user_123");
258 const tools = await session.tools();
259
260 const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
@@ -371,7 +371,7 @@ const composio = new Composio({
371 });
372
373 // Create a session for your user
374 -const session = await composio.create("user_123");
374 +const session = await composio.sessions.create("user_123");
375 const tools = await session.tools();
376
377 const agent = new Agent({
docs/content/docs/providers/vercel.mdx
+1 -1
@@ -40,7 +40,7 @@ import { generateText, stepCountIs } from "ai";
40 const composio = new Composio({ provider: new VercelProvider() });
41
42 // Create a session for your user
43 -const session = await composio.create("user_123");
43 +const session = await composio.sessions.create("user_123");
44 const tools = await session.tools();
45
46 const { text } = await generateText({
docs/content/docs/quickstart.mdx
+6 -6
@@ -111,12 +111,12 @@ const composio = new Composio({ provider: new OpenAIAgentsProvider() });
111
112 // Create a session for your user
113 const userId = "user_123";
114 -const session = await composio.create(userId);
114 +const session = await composio.sessions.create(userId);
115 const tools = await session.tools();
116
117 // For multi-turn, store the session ID in your db and reuse instead of calling create() again:
118 // const sessionId = session.sessionId;
119 -// const session = await composio.use(sessionId);
119 +// const session = await composio.sessions.use(sessionId);
120
121 const agent = new Agent({
122 name: "Personal Assistant",
@@ -265,12 +265,12 @@ const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
265
266 // Create a session for your user
267 const userId = "user_123";
268 -const session = await composio.create(userId);
268 +const session = await composio.sessions.create(userId);
269 const tools = await session.tools();
270
271 // For multi-turn, store the session ID in your db and reuse instead of calling create() again:
272 // const sessionId = session.sessionId;
273 -// const session = await composio.use(sessionId);
273 +// const session = await composio.sessions.use(sessionId);
274
275 const customServer = createSdkMcpServer({
276 name: "composio",
@@ -369,12 +369,12 @@ const composio = new Composio({ provider: new VercelProvider() });
369
370 // Create a session for your user
371 const userId = "user_123";
372 -const session = await composio.create(userId);
372 +const session = await composio.sessions.create(userId);
373 const tools = await session.tools();
374
375 // For multi-turn, store the session ID in your db and reuse instead of calling create() again:
376 // const sessionId = session.sessionId;
377 -// const session = await composio.use(sessionId);
377 +// const session = await composio.sessions.use(sessionId);
378
379 const readline = createInterface({ input: process.stdin, output: process.stdout });
380
docs/content/docs/sandbox/local.mdx
+1 -1
@@ -35,7 +35,7 @@ import { experimental_createLocalWorkbenchSession } from '@composio/experimental
35 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
36
37 // Create the session with the remote sandbox disabled, so code runs in your box.
38 -const session = await composio.create('user_123', {
38 +const session = await composio.sessions.create('user_123', {
39 toolkits: ['github'],
40 workbench: { enable: false },
41 });
docs/content/docs/sandbox/remote.mdx
+1 -1
@@ -90,7 +90,7 @@ report.save("./report.pdf")
90 import { Composio } from '@composio/core';
91 const composio = new Composio({ apiKey: 'your_api_key' });
92 // ---cut---
93 -const session = await composio.create("user_123");
93 +const session = await composio.sessions.create("user_123");
94
95 // Upload a local file; the sandbox sees it at /mnt/files/sales.csv
96 const uploaded = await session.experimental.files.upload("./sales.csv");
docs/content/docs/sessions-via-mcp.mdx
+4 -4
@@ -30,7 +30,7 @@ mcp_headers = session.mcp.headers
30 import { Composio } from "@composio/core";
31
32 const composio = new Composio();
33 -const session = await composio.create("user_123", { mcp: true });
33 +const session = await composio.sessions.create("user_123", { mcp: true });
34
35 const mcpUrl = session.mcp.url;
36 const mcpHeaders = session.mcp.headers;
@@ -41,7 +41,7 @@ const mcpHeaders = session.mcp.headers;
41 You don't need a provider package to use the MCP endpoint, so you can drop it from your `Composio()` setup if MCP is all you need.
42
43 <Callout type="info">
44 -Resuming a stored session? Pass the same flag, `composio.use(sessionId, { mcp: true })` (TypeScript) or `composio.use(session_id, mcp=True)` (Python), to surface `session.mcp` on the reused session.
44 +Resuming a stored session? Pass the same flag, `composio.sessions.use(sessionId, { mcp: true })` (TypeScript) or `composio.use(session_id, mcp=True)` (Python), to surface `session.mcp` on the reused session.
45 </Callout>
46
47 <Callout type="info">
@@ -78,7 +78,7 @@ import { Composio, SessionPreset } from "@composio/core";
78
79 const composio = new Composio();
80
81 -const session = await composio.create("user_123", {
81 +const session = await composio.sessions.create("user_123", {
82 toolkits: ["gmail"],
83 tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"] } },
84 sessionPreset: SessionPreset.DIRECT_TOOLS,
@@ -140,7 +140,7 @@ import { Composio } from "@composio/core";
140 import { createMCPClient } from "@ai-sdk/mcp";
141
142 const composio = new Composio();
143 -const { mcp } = await composio.create("user_123", { mcp: true });
143 +const { mcp } = await composio.sessions.create("user_123", { mcp: true });
144
145 const client = await createMCPClient({
146 transport: {
docs/content/docs/sessions-vs-direct-execution.mdx
+4 -4
@@ -5,7 +5,7 @@ keywords: [session, direct execution, tool router, meta tools, architecture, dec
5 legacy: true
6 ---
7
8 -A **session** is the runtime context Composio creates for one of your users with `composio.create(userId)`. It ties together the user, available toolkits, auth, and connected accounts. By default it gives your agent [meta tools](/docs/how-composio-works#meta-tools) so the agent discovers which app tools to use, authenticates users, and executes tools at runtime.
8 +A **session** is the runtime context Composio creates for one of your users. In TypeScript, use `composio.sessions.create(userId)`; Python uses `composio.create(user_id)`. It ties together the user, available toolkits, auth, and connected accounts. By default it gives your agent [meta tools](/docs/how-composio-works#meta-tools) so the agent discovers which app tools to use, authenticates users, and executes tools at runtime.
9
10 **Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.
11
@@ -28,7 +28,7 @@ Sessions aren't all-or-nothing. With the [direct tools preset](/docs/configuring
28
29 ## Sessions
30
31 -`composio.create()` returns [meta tools](/docs/how-composio-works#meta-tools):
31 +Creating a session returns [meta tools](/docs/how-composio-works#meta-tools):
32
33 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
34 <Tab value="Python">
@@ -52,7 +52,7 @@ const composio = new Composio({
52 apiKey: process.env.COMPOSIO_API_KEY,
53 provider: new OpenAIProvider(),
54 });
55 -const session = await composio.create("user_123");
55 +const session = await composio.sessions.create("user_123");
56 const tools = await session.tools();
57 // Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
58 // COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
@@ -101,7 +101,7 @@ session = composio.create(
101 import { Composio } from '@composio/core';
102 const composio = new Composio({ apiKey: 'your_api_key' });
103 // ---cut---
104 -const session = await composio.create("user_123", {
104 +const session = await composio.sessions.create("user_123", {
105 toolkits: ["github", "gmail"],
106 authConfigs: { github: "ac_my_config" },
107 connectedAccounts: { gmail: ["ca_work"] },
docs/content/docs/shared-connections.mdx
+1 -1
@@ -120,7 +120,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });
120 // user_alice starts a session that pins the shared Gmail connection.
121 // Gmail tools loaded from this session will resolve to that connection
122 // even though user_alice did not create it.
123 -const session = await composio.create("user_alice", {
123 +const session = await composio.sessions.create("user_alice", {
124 connectedAccounts: {
125 gmail: ["ca_gmail_shared"],
126 },
docs/content/docs/white-labeling-authentication.mdx
+1 -1
@@ -141,7 +141,7 @@ connection_request = session.authorize(
141 ```typescript
142 import { Composio } from '@composio/core';
143 const composio = new Composio({ apiKey: 'your_api_key' });
144 -const session = await composio.create("user_123");
144 +const session = await composio.sessions.create("user_123");
145 // ---cut---
146 const connectionRequest = await session.authorize("gmail", {
147 callbackUrl: "https://your-app.com/callback",
docs/content/reference/api-reference/mcp/index.mdx
+2 -2
@@ -6,14 +6,14 @@ description: "MCP server management"
6 {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/mcp.mdx, not this file. */}
7
8 <Callout type="warning">
9 -This API is deprecated. Use a session's MCP endpoint instead. Create a session with `composio.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
9 +This API is deprecated. Use a session's MCP endpoint instead. In TypeScript, create a session with `composio.sessions.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
10 </Callout>
11
12 The MCP API is the standalone, hosted [Model Context Protocol](https://modelcontextprotocol.io) server-management surface. It let you stand up and manage a separate server config per toolkit, then mint a per-user MCP URL that any MCP-compatible client could connect to.
13
14 These endpoints create, list, update, and delete MCP servers, including custom servers spanning multiple apps, generate per-user MCP URLs, and manage per-user server instances and their connected accounts.
15
16 -Sessions replace this. A single `composio.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
16 +Sessions replace this. In TypeScript, a single `composio.sessions.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
17
18 ## Endpoints
19
docs/content/reference/api-reference/tool-router/index.mdx
+1 -1
@@ -11,7 +11,7 @@ These are Composio's session endpoints. A **session** is the runtime context you
11 Sessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.
12 </Callout>
13
14 -In the SDK you do not call these endpoints directly. Use `composio.create(...)` to start a session and `composio.use(...)` to resume one, then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
14 +In the SDK you do not call these endpoints directly. In TypeScript, use `composio.sessions.create(...)` to start a session and `composio.sessions.use(...)` to resume one; Python uses `composio.create(...)` and `composio.use(...)`. Then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
15
16 Reach for the raw API when you need lower-level control: creating and patching a session config, attaching to an existing session, searching for tools, executing tools and meta tools, opening link sessions for auth, proxying authenticated requests, and reading or writing files in a session mount.
17
docs/content/reference/api-reference/webhook-subscriptions/index.mdx
+1 -1
@@ -118,7 +118,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
118 const toolkit = payload.data.toolkit.slug;
119
120 // Look up the user and send them a re-auth link
121 - const session = await composio.create(lookupUser(accountId));
121 + const session = await composio.sessions.create(lookupUser(accountId));
122 const connectionRequest = await session.authorize(toolkit);
123 if (connectionRequest.redirectUrl) {
124 notifyUser(connectionRequest.redirectUrl);
docs/content/reference/glossary.mdx
+1 -1
@@ -88,7 +88,7 @@ An adapter package that transforms Composio tools into the format an AI framewor
88 </GlossaryTerm>
89
90 <GlossaryTerm name="Session">
91 -An ephemeral, immutable configuration object returned by `composio.create(userId)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
91 +An ephemeral, immutable configuration object returned by TypeScript's `composio.sessions.create(userId)` or Python's `composio.create(user_id)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
92 </GlossaryTerm>
93
94 <GlossaryTerm name="Session ID">
docs/content/reference/sdk-reference/typescript/composio.mdx
+2 -6
@@ -53,9 +53,6 @@ const composio = new Composio({
53 |------|------|-------------|
54 | `authConfigs` | `AuthConfigs` | Manage authentication configurations for toolkits |
55 | `connectedAccounts` | `ConnectedAccounts` | Manage authenticated connections |
56 -| `create` | `(userId: string, config: \{ authConfigs?: Record<string, string>; connectedAccounts?: Record<string, string \| ...[]>; experimental?: \{ assistivePrompt?: \{ userTimezone?: string \}; customToolkits?: CustomToolkit[]; customTools?: CustomTool[] \}; manageConnections?: boolean \| \{ callbackUrl?: string; enable?: boolean; waitForConnections?: boolean \}; mcp?: boolean; multiAccount?: \{ enable: boolean; maxAccountsPerToolkit?: number; requireExplicitSelection?: boolean \}; preload?: \{ tools?: ...[] \| 'all' \}; sandbox?: \{ autoOffloadThreshold?: number; enable: boolean; enableProxyExecution?: boolean; sandboxSize?: 'standard' \| 'medium' \| 'large' \| 'xlarge' \}; sessionPreset?: 'direct_tools'; tags?: ... \| ... \| ... \| ...[] \| \{ disable?: ...[]; enable?: ...[] \}; toolkits?: string[] \| \{ disable: ...[] \} \| \{ enable: ...[] \}; tools?: Record<string, ...[] \| \{ enable: ... \} \| \{ disable: ... \} \| \{ tags: ... \}>; workbench?: \{ autoOffloadThreshold?: number; enable: boolean; enableProxyExecution?: boolean; sandboxSize?: 'standard' \| 'medium' \| 'large' \| 'xlarge' \} \} & \{ mcp: true \}, requestOptions: ComposioRequestOptions) => Promise<Session>` | Creates a new tool router session for a user.
57 -Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools
58 -should be exposed directly; see `ToolRouterCreateSessionConfig`. |
56 | `experimental` | `Experimental` | Experimental SDK methods whose shape may change in future releases.
57 Prefer domain-specific mounts (for example
58 `composio.connectedAccounts.updateAcl(...)`) when available; this
@@ -67,13 +64,12 @@ at the top level. |
64 | `provider` | `TProvider` | The tool provider instance used for wrapping tools in framework-specific formats |
65 | `sessions` | `Sessions` | Create and reuse Composio sessions.
66
70 -Prefer `composio.sessions.create(...)` for new code. The top-level
71 -`composio.create(...)` method is kept as an alias. |
67 +Use `composio.sessions.create(...)` to create a session and
68 +`composio.sessions.use(...)` to reuse one. |
69 | `toolkits` | `Toolkits` | Retrieve toolkit metadata and authorize user connections |
70 | `toolRouter` | `ToolRouter` | Legacy alias for `composio.sessions`. |
71 | `tools` | `Tools` | List, retrieve, and execute tools |
72 | `triggers` | `Triggers` | Manage webhook triggers and event subscriptions |
76 -| `use` | `(id: string, options: \{ customToolkits?: CustomToolkit[]; customTools?: CustomTool[]; mcp: true \}, requestOptions: ComposioRequestOptions) => Promise<Session>` | Use an existing tool router session |
73
74 ## Methods
75
docs/content/reference/sdk-reference/typescript/mcp.mdx
+1 -1
@@ -4,7 +4,7 @@ description: "MCP (Model Control Protocol) class Handles MCP server operations.
4 ---
5
6 <Callout type="warn" title="Deprecated">
7 -Use a session's MCP endpoint instead: `composio.create(userId, \{ mcp: true \})`
7 +Use a session's MCP endpoint instead: `composio.sessions.create(userId, \{ mcp: true \})`
8 returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now
9 opt-in per session; the standalone `composio.mcp` server-management API is kept only for
10 backwards compatibility. Prefer the session MCP endpoint; do not generate new code against
docs/content/reference/sdk-reference/typescript/session.mdx
+1 -1
@@ -1,6 +1,6 @@
1 ---
2 title: "Session"
3 -description: "A Composio session — the object returned by `composio.sessions.create(...)` and `composio.sessions.use(...)` (also reachable via the top-level `composio.create(...)` / `composio.use(...)` aliases). This is the canonical session surface. Use it to fetch session-scoped tools, authorize toolkits, search, and execute tools. The public return type is `Session` (with `mcp` surfaced, returned when `{ mcp: true }` is passed) or `SessionWithoutMcp` (the default, with `mcp` omitted from the type); this class is the concrete runtime form behind both."
3 +description: "A Composio session — the object returned by `composio.sessions.create(...)` and `composio.sessions.use(...)`. This is the canonical session surface. Use it to fetch session-scoped tools, authorize toolkits, search, and execute tools. The public return type is `Session` (with `mcp` surfaced, returned when `{ mcp: true }` is passed) or `SessionWithoutMcp` (the default, with `mcp` omitted from the type); this class is the concrete runtime form behind both."
4 ---
5
6 ## Properties
docs/content/reference/sdk-reference/typescript/sessions.mdx
+1 -1
@@ -1,6 +1,6 @@
1 ---
2 title: "Sessions"
3 -description: "First-class API for creating and reusing Composio sessions. `composio.sessions.create(...)` is the canonical session creation entrypoint. The top-level `composio.create(...)` method remains as a backwards-compatible alias for `composio.sessions.create(...)`."
3 +description: "First-class API for creating and reusing Composio sessions. Use `composio.sessions.create(...)` to create a session and `composio.sessions.use(...)` to reuse one."
4 ---
5
6 ## Usage
docs/content/reference/v3/api-reference/mcp/index.mdx
+2 -2
@@ -6,14 +6,14 @@ description: "MCP server management"
6 {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/mcp.mdx, not this file. */}
7
8 <Callout type="warning">
9 -This API is deprecated. Use a session's MCP endpoint instead. Create a session with `composio.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
9 +This API is deprecated. Use a session's MCP endpoint instead. In TypeScript, create a session with `composio.sessions.create(userId, { mcp: true })`, then read the hosted URL off `session.mcp.url`. See [Using sessions via MCP](/docs/sessions-via-mcp) and [migrating MCP servers to sessions](/docs/migration-guide/mcp-servers-to-sessions).
10 </Callout>
11
12 The MCP API is the standalone, hosted [Model Context Protocol](https://modelcontextprotocol.io) server-management surface. It let you stand up and manage a separate server config per toolkit, then mint a per-user MCP URL that any MCP-compatible client could connect to.
13
14 These endpoints create, list, update, and delete MCP servers, including custom servers spanning multiple apps, generate per-user MCP URLs, and manage per-user server instances and their connected accounts.
15
16 -Sessions replace this. A single `composio.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
16 +Sessions replace this. In TypeScript, a single `composio.sessions.create(...)` gives you the same MCP URL pattern, keyed by `user_id`, while handling tool discovery, authentication, context, and versioning for you. Your existing tools, auth configs (`ac_…`), and connected accounts carry over with no re-authentication. To pin a session to a fixed tool list the way a server did, use the direct-tools preset described in [Configuring sessions](/docs/configuring-sessions).
17
18 ## Endpoints
19
docs/content/reference/v3/api-reference/tool-router/index.mdx
+1 -1
@@ -11,7 +11,7 @@ These are Composio's session endpoints. A **session** is the runtime context you
11 Sessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.
12 </Callout>
13
14 -In the SDK you do not call these endpoints directly. Use `composio.create(...)` to start a session and `composio.use(...)` to resume one, then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
14 +In the SDK you do not call these endpoints directly. In TypeScript, use `composio.sessions.create(...)` to start a session and `composio.sessions.use(...)` to resume one; Python uses `composio.create(...)` and `composio.use(...)`. Then call `session.tools()`, `session.execute(...)`, and `session.authorize(...)` on the returned object.
15
16 Reach for the raw API when you need lower-level control: creating and patching a session config, attaching to an existing session, searching for tools, executing tools and meta tools, opening link sessions for auth, proxying authenticated requests, and reading or writing files in a session mount.
17
docs/content/reference/v3/api-reference/webhook-subscriptions/index.mdx
+1 -1
@@ -118,7 +118,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
118 const toolkit = payload.data.toolkit.slug;
119
120 // Look up the user and send them a re-auth link
121 - const session = await composio.create(lookupUser(accountId));
121 + const session = await composio.sessions.create(lookupUser(accountId));
122 const connectionRequest = await session.authorize(toolkit);
123 if (connectionRequest.redirectUrl) {
124 notifyUser(connectionRequest.redirectUrl);
docs/content/toolkits/managed-auth.mdx
+1 -1
@@ -27,7 +27,7 @@ session = composio.create(user_id="user_123")
27 import { Composio } from '@composio/core';
28
29 const composio = new Composio();
30 -const session = await composio.create("user_123");
30 +const session = await composio.sessions.create("user_123");
31 // Tools that need an account return a Connect Link automatically
32 ```
33 </Tab>
docs/decisions/llm-guardrails.md
+2 -2
@@ -6,7 +6,7 @@ Inject invisible guardrail instructions into every `.md` response so AI code gen
6
7 ## Problem
8
9 -LLMs that crawl or receive Composio docs generate code using the old direct tool execution pattern (`composio.tools.get()`, `composio.provider.handle_tool_calls()`) instead of the current session-based pattern (`composio.create()`, `session.tools()`).
9 +LLMs that crawl or receive Composio docs generate code using the old direct tool execution pattern (`composio.tools.get()`, `composio.provider.handle_tool_calls()`) instead of the current session-based pattern (TypeScript's `composio.sessions.create()` and `session.tools()`).
10
11 ## Architecture
12
@@ -29,7 +29,7 @@ Pages control which guardrails they get:
29
30 | Frontmatter value | What gets appended |
31 |---|---|
32 -| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |
32 +| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.sessions.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |
33 | `llmGuardrails: "direct-execution"` | `DIRECT_EXECUTION_GUARDRAILS` — acknowledges direct execution is valid, but strongly recommends sessions unless user explicitly asks for it |
34 | `llmGuardrails: "none"` | Nothing |
35
docs/lib/llm-guardrails/direct-execution.ts
+1 -1
@@ -10,7 +10,7 @@ export const DIRECT_EXECUTION_GUARDRAILS = `
10
11 # Composio SDK — Instructions for AI Code Generators
12
13 -**Context:** This page documents the **direct tool execution API**. For most applications, the session-based pattern (\`composio.create(user_id)\` + \`session.tools()\`) is simpler — but if the user is here, they likely want direct execution.
13 +**Context:** This page documents the **direct tool execution API**. For most applications, the session-based pattern (\`composio.sessions.create(user_id)\` + \`session.tools()\`) is simpler — but if the user is here, they likely want direct execution.
14
15 ---
16
docs/lib/llm-guardrails/session.ts
+5 -5
@@ -2,7 +2,7 @@ import { TERMINOLOGY_MIGRATION } from './terminology';
2
3 /**
4 * Default guardrails appended to most pages.
5 - * Steers LLMs toward the session-based pattern (composio.create + session.tools).
5 + * Steers LLMs toward the session-based pattern (composio.sessions.create + session.tools).
6 */
7 export const SESSION_GUARDRAILS = `
8
@@ -26,7 +26,7 @@ Composio supports two integration modes: **Native Tools** (with a provider packa
26 from composio import Composio
27
28 composio = Composio()
29 -session = composio.create(user_id="user_123")
29 +session = composio.sessions.create(user_id="user_123")
30 tools = session.tools()
31 # Pass tools to your agent/LLM framework
32 \`\`\`
@@ -36,7 +36,7 @@ tools = session.tools()
36 import { Composio } from "@composio/core";
37
38 const composio = new Composio();
39 -const session = await composio.create("user_123");
39 +const session = await composio.sessions.create("user_123");
40 const tools = await session.tools();
41 // Pass tools to your agent/LLM framework
42 \`\`\`
@@ -53,10 +53,10 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
53
54 ### 2.1 — ALWAYS DO THE FOLLOWING
55
56 -1. **Use \`composio.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.
56 +1. **Use \`composio.sessions.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.
57 2. **Use \`session.tools()\`** for native tool integration or **\`session.mcp.url\`** for MCP integration.
58 3. **Import** from the correct provider package (\`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript).
59 -4. **Pass \`user_id\` to \`composio.create()\`**, not to individual tool calls.
59 +4. **Pass \`user_id\` to \`composio.sessions.create()\`**, not to individual tool calls.
60
61 ### 2.2 — NEVER DO THE FOLLOWING
62
docs/lib/local-workbench-build.ts
+1 -1
@@ -49,7 +49,7 @@ const stage3 = `${stage2}
49 // session to the helper, which validates it's local and gives you the pieces to
50 // run code yourself, wherever you choose.
51 async function createWorkbench() {
52 - const session = await composio.create(userId, {
52 + const session = await composio.sessions.create(userId, {
53 toolkits: ['github'],
54 workbench: { enable: false },
55 });
docs/lib/local-workbench-source.json
+1 -1
@@ -11,7 +11,7 @@
11 },
12 {
13 "path": "src/workbench.ts",
14 -"contents": "import { Composio } from '@composio/core';\nimport {\n experimental_createLocalWorkbenchSession,\n type LocalWorkbenchSession,\n} from '@composio/experimental/workbench';\nimport type { AppConfig } from './config.js';\n\ntype ConnectedAccount = {\n id: string;\n status?: string;\n};\n\nexport function createComposioClient(config: AppConfig): Composio {\n return new Composio({\n apiKey: config.composioApiKey,\n baseURL: config.composioBaseUrl,\n });\n}\n\nexport async function getActiveGithubConnection(composio: Composio, userId: string): Promise<ConnectedAccount | undefined> {\n const list = (await composio.connectedAccounts.list({\n userIds: [userId],\n toolkitSlugs: ['github'],\n statuses: ['ACTIVE'],\n })) as { items?: ConnectedAccount[] };\n\n return list.items?.[0];\n}\n\nexport async function createGithubConnectUrl(composio: Composio, userId: string): Promise<string> {\n const request = await composio.toolkits.authorize(userId, 'github');\n if (!request.redirectUrl) throw new Error('Composio did not return a GitHub connect URL');\n return request.redirectUrl;\n}\n\nexport async function requireGithubConnection(composio: Composio, userId: string): Promise<ConnectedAccount> {\n const account = await getActiveGithubConnection(composio, userId);\n if (account) return account;\n\n const url = await createGithubConnectUrl(composio, userId);\n throw new Error(\n [\n `No active GitHub connection found for COMPOSIO_USER_ID=\"${userId}\".`,\n 'Open this URL, complete GitHub authorization, then run the reviewer again:',\n url,\n ].join('\\n')\n );\n}\n\nexport async function createLocalWorkbench(composio: Composio, userId: string): Promise<LocalWorkbenchSession> {\n // Create the session with the remote workbench disabled so code execution runs in our own sandbox,\n // then hand it to the helper (which validates workbench.enable === false).\n const session = await composio.create(userId, {\n toolkits: ['github'],\n workbench: { enable: false },\n });\n return experimental_createLocalWorkbenchSession(composio, session);\n}\n",
14 +"contents": "import { Composio } from '@composio/core';\nimport {\n experimental_createLocalWorkbenchSession,\n type LocalWorkbenchSession,\n} from '@composio/experimental/workbench';\nimport type { AppConfig } from './config.js';\n\ntype ConnectedAccount = {\n id: string;\n status?: string;\n};\n\nexport function createComposioClient(config: AppConfig): Composio {\n return new Composio({\n apiKey: config.composioApiKey,\n baseURL: config.composioBaseUrl,\n });\n}\n\nexport async function getActiveGithubConnection(composio: Composio, userId: string): Promise<ConnectedAccount | undefined> {\n const list = (await composio.connectedAccounts.list({\n userIds: [userId],\n toolkitSlugs: ['github'],\n statuses: ['ACTIVE'],\n })) as { items?: ConnectedAccount[] };\n\n return list.items?.[0];\n}\n\nexport async function createGithubConnectUrl(composio: Composio, userId: string): Promise<string> {\n const request = await composio.toolkits.authorize(userId, 'github');\n if (!request.redirectUrl) throw new Error('Composio did not return a GitHub connect URL');\n return request.redirectUrl;\n}\n\nexport async function requireGithubConnection(composio: Composio, userId: string): Promise<ConnectedAccount> {\n const account = await getActiveGithubConnection(composio, userId);\n if (account) return account;\n\n const url = await createGithubConnectUrl(composio, userId);\n throw new Error(\n [\n `No active GitHub connection found for COMPOSIO_USER_ID=\"${userId}\".`,\n 'Open this URL, complete GitHub authorization, then run the reviewer again:',\n url,\n ].join('\\n')\n );\n}\n\nexport async function createLocalWorkbench(composio: Composio, userId: string): Promise<LocalWorkbenchSession> {\n // Create the session with the remote workbench disabled so code execution runs in our own sandbox,\n // then hand it to the helper (which validates workbench.enable === false).\n const session = await composio.sessions.create(userId, {\n toolkits: ['github'],\n workbench: { enable: false },\n });\n return experimental_createLocalWorkbenchSession(composio, session);\n}\n",
15 "composio": true
16 },
17 {
docs/lib/slack-bot-build.ts
+6 -6
@@ -68,7 +68,7 @@ async function runPi(tools: unknown, prompt: string) {
68 const runAgent = `
69 // The smallest agent: one session, its tools, one prompt.
70 export async function runAgent(userId: string, prompt: string) {
71 - const session = await composio.create(userId);
71 + const session = await composio.sessions.create(userId);
72 const tools = piProvider.createSessionTools({
73 sessionId: session.sessionId,
74 search: (params) => session.search(params),
@@ -88,9 +88,9 @@ const threadKey = (event: IncomingTriggerPayload) =>
88 async function sessionForThread(event: IncomingTriggerPayload) {
89 const key = threadKey(event);
90 const existing = threads.get(key);
91 - if (existing) return { session: await composio.use(existing.sessionId), memory: existing };
91 + if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };
92
93 - const session = await composio.create(event.userId, {
93 + const session = await composio.sessions.create(event.userId, {
94 manageConnections: { enable: true, callbackUrl, waitForConnections: true },
95 });
96 const memory = { sessionId: session.sessionId, history: [] as { role: string; content: string }[] };
@@ -109,9 +109,9 @@ const threadKey = (event: IncomingTriggerPayload) =>
109 async function sessionForThread(event: IncomingTriggerPayload) {
110 const key = threadKey(event);
111 const existing = threads.get(key);
112 - if (existing) return { session: await composio.use(existing.sessionId), memory: existing };
112 + if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };
113
114 - const session = await composio.create(event.userId, {
114 + const session = await composio.sessions.create(event.userId, {
115 // Pin the shared Slack connection; the session still resolves every other
116 // toolkit against this user's own connections.
117 connectedAccounts: { slackbot: [SHARED_SLACK_CONNECTION_ID] },
@@ -345,7 +345,7 @@ const authConfig = await composio.authConfigs.create('slackbot', {
345
346 const installAuthorize = `
347 // One connection for the whole workspace: authorize it as SHARED.
348 -const setup = await composio.create('setup:workspace-bot', {
348 +const setup = await composio.sessions.create('setup:workspace-bot', {
349 toolkits: ['slackbot'],
350 authConfigs: { slackbot: authConfig.id },
351 manageConnections: true,
docs/lib/slack-bot-source.json
+3 -3
@@ -12,12 +12,12 @@
12 {
13 "path": "src/composio/slackbot-setup.ts",
14 "composio": true,
15 -"contents": "import { createHash, randomUUID } from 'node:crypto';\n\nimport { Composio } from '@composio/core';\n\nimport { jsonResponse } from '../api/http';\nimport type { AppConfig } from '../config/env';\nimport { htmlPages } from '../html/pages';\nimport { htmlFileResponse, htmlTemplateResponse } from '../html/render';\nimport { proxySlack } from '../slack/transport';\nimport type { Store } from '../store/file-store';\nimport { firstString, jsonObject } from '../utils/decode';\nimport type { JsonObject, JsonValue } from '../utils/json';\nimport { createComposioApiClient } from './api';\n\ntype ComposioSession = Awaited<ReturnType<Composio['create']>>;\n\ninterface SharedSlackbotAuthorizeOptions {\n callbackUrl: string;\n experimental: {\n accountType: 'SHARED';\n };\n}\n\ninterface SlackbotSetupDeps {\n composio: Composio;\n config: AppConfig;\n store: Store;\n}\n\nexport interface SlackbotSetupService {\n completeSetup(url: URL): Promise<Response>;\n ensureSlackbotAuthConfig(): Promise<string | undefined>;\n ensureSlackbotTriggers(connectedAccountId: string): Promise<void>;\n ensureWebhookSubscription(): Promise<void>;\n startSetup(): Promise<Response>;\n}\n\n/**\n * Owns the install-time Slackbot plumbing:\n * - create/reuse a managed Slackbot auth config with the requested scopes\n * - request a shared Slackbot connection\n * - persist the team-scoped connected account\n * - ensure Composio webhook subscription + Slackbot triggers exist\n */\nexport function createSlackbotSetupService({ composio, config, store }: SlackbotSetupDeps): SlackbotSetupService {\n const composioApi = createComposioApiClient(config);\n\n const ensureSlackbotAuthConfig = async (): Promise<string | undefined> => {\n if (config.slackbotAuthConfigId) {\n return config.slackbotAuthConfigId;\n }\n\n const botScopes = uniqueSorted(config.slackbotBotScopes);\n const userScopes = uniqueSorted(config.slackbotUserScopes);\n if (botScopes.length === 0 && userScopes.length === 0) {\n return undefined;\n }\n\n const name = slackbotAuthConfigName(config, botScopes, userScopes);\n const existing = await composio.authConfigs.list({ toolkit: 'slackbot', isComposioManaged: true, limit: 100 });\n const match = authConfigItems(existing).find((item) => item.name === name);\n if (match?.id) {\n return match.id;\n }\n\n const created = await composio.authConfigs.create('slackbot', {\n type: 'use_composio_managed_auth',\n name,\n credentials: {\n scopes: botScopes,\n user_scopes: userScopes,\n },\n });\n console.log(`Created Slackbot Composio auth config ${created.id} (${name})`);\n return created.id;\n };\n\n const ensureWebhookSubscription = async (): Promise<void> => {\n const webhookUrl = `${config.appUrl}/webhooks/composio`;\n const body = {\n webhook_url: webhookUrl,\n enabled_events: ['composio.trigger.message'],\n version: 'V3',\n };\n\n const existing = await composioApi.request('/api/v3.1/webhook_subscriptions', { method: 'GET' });\n const subscription = firstObjectItem(existing?.items);\n const subscriptionId = firstString(subscription?.id);\n\n if (subscriptionId) {\n await composioApi.request(`/api/v3.1/webhook_subscriptions/${subscriptionId}`, {\n method: 'PATCH',\n body,\n });\n return;\n }\n\n await composioApi.request('/api/v3.1/webhook_subscriptions', {\n method: 'POST',\n body,\n });\n };\n\n const ensureSlackbotTriggers = async (connectedAccountId: string): Promise<void> => {\n const connectedAccount = await composioApi.request(`/api/v3/connected_accounts/${connectedAccountId}`, { method: 'GET' });\n const ownerUserId = firstString(connectedAccount?.user_id);\n if (!ownerUserId) {\n throw new Error(`Could not determine owner user_id for connected account ${connectedAccountId}`);\n }\n\n await upsertTrigger(composioApi.request, 'SLACKBOT_CHANNEL_MESSAGE_RECEIVED', connectedAccountId, ownerUserId, {\n is_bot_message: false,\n });\n\n await upsertTrigger(composioApi.request, 'SLACKBOT_DIRECT_MESSAGE_RECEIVED', connectedAccountId, ownerUserId, {});\n };\n\n const startSetup = async (): Promise<Response> => {\n const setupId = randomUUID();\n const setupUserId = `setup:slackbot:${setupId}`;\n const authConfigId = await ensureSlackbotAuthConfig();\n const session = await composio.create(setupUserId, {\n toolkits: ['slackbot'],\n authConfigs: authConfigId ? { slackbot: authConfigId } : {},\n manageConnections: true,\n workbench: { enable: false },\n });\n await store.setSlackbotSetup(setupId, session.sessionId, setupUserId);\n\n const connectionRequest = await session.authorize('slackbot', sharedSlackbotAuthorizeOptions(config, setupId));\n if (!connectionRequest.redirectUrl) {\n return jsonResponse({ ok: false, error: 'missing_redirect_url' }, 500);\n }\n\n return Response.redirect(connectionRequest.redirectUrl, 302);\n };\n\n const completeSetup = async (url: URL): Promise<Response> => {\n const setupId = url.searchParams.get('setup');\n const connectedAccountId = url.searchParams.get('connected_account_id');\n const status = url.searchParams.get('status');\n const setup = setupId ? store.getSlackbotSetup(setupId) : undefined;\n\n if (!setupId || !setup) {\n return htmlFileResponse(htmlPages.slackbotSetupExpired, 400);\n }\n\n if (!connectedAccountId || status !== 'success') {\n return htmlFileResponse(htmlPages.slackbotSetupFailed, 400);\n }\n\n const setupSession = await composio.use(setup.sessionId);\n await setupSession.update({ connectedAccounts: { slackbot: [connectedAccountId] } });\n const slackAuth = await slackAuthTest(setupSession);\n const teamId = slackAuth.teamId;\n await composio.experimental.updateAcl(connectedAccountId, { allowAllUsers: true });\n\n await store.setSlackbotConnection(teamId, connectedAccountId, {\n botUserId: slackAuth.botUserId,\n teamName: slackAuth.teamName,\n });\n await store.deleteSlackbotSetup(setupId);\n\n await ensureWebhookSubscription().catch((error) => {\n console.error('Failed to configure Composio webhook subscription after setup', error);\n });\n await ensureSlackbotTriggers(connectedAccountId).catch((error) => {\n console.error('Failed to create Slackbot triggers after setup', error);\n });\n\n return htmlTemplateResponse(htmlPages.slackbotConnected, { teamName: slackAuth.teamName ?? teamId });\n };\n\n return {\n completeSetup,\n ensureSlackbotAuthConfig,\n ensureSlackbotTriggers,\n ensureWebhookSubscription,\n startSetup,\n };\n}\n\nfunction sharedSlackbotAuthorizeOptions(config: AppConfig, setupId: string): SharedSlackbotAuthorizeOptions {\n const callbackUrl = new URL('/setup/slackbot/callback', config.appUrl);\n callbackUrl.searchParams.set('setup', setupId);\n\n return {\n callbackUrl: callbackUrl.toString(),\n experimental: {\n accountType: 'SHARED',\n },\n };\n}\n\nfunction slackbotAuthConfigName(config: AppConfig, botScopes: string[], userScopes: string[]): string {\n const scopeHash = createHash('sha256')\n .update(JSON.stringify({ botScopes, userScopes }))\n .digest('hex')\n .slice(0, 8);\n return `${config.slackbotAuthConfigName}-${scopeHash}`;\n}\n\nasync function slackAuthTest(session: ComposioSession): Promise<{ botUserId?: string; teamId: string; teamName?: string }> {\n return decodeSlackAuthTest(await proxySlack(session, 'auth.test', {}));\n}\n\nfunction decodeSlackAuthTest(response: unknown): { botUserId?: string; teamId: string; teamName?: string } {\n const responseObject = jsonObject(response) ?? {};\n const data = jsonObject(responseObject.data) ?? responseObject;\n const nestedData = jsonObject(data.data);\n\n if (data.ok === false) {\n throw new Error(`Slack auth.test failed: ${firstString(data.error) ?? JSON.stringify(data)}`);\n }\n\n const teamId = firstString(data.team_id, data.teamId, nestedData?.team_id, nestedData?.teamId);\n if (!teamId) {\n throw new Error(`Slack auth.test did not return team_id: ${JSON.stringify(data)}`);\n }\n\n return {\n botUserId: firstString(data.user_id, data.userId, data.bot_user_id, data.botUserId, nestedData?.user_id),\n teamId,\n teamName: firstString(data.team, data.team_name, data.teamName, nestedData?.team),\n };\n}\n\nfunction authConfigItems(value: unknown): Array<{ id?: string; name?: string }> {\n const record = jsonObject(value) ?? {};\n const items = Array.isArray(record.items) ? record.items : [];\n return items.flatMap((item): Array<{ id?: string; name?: string }> => {\n const object = jsonObject(item);\n if (!object) return [];\n return [\n {\n id: firstString(object.id),\n name: firstString(object.name),\n },\n ];\n });\n}\n\nfunction uniqueSorted(values: string[]): string[] {\n return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();\n}\n\nfunction firstObjectItem(value: JsonValue | undefined): JsonObject | undefined {\n return Array.isArray(value) ? jsonObject(value[0]) : undefined;\n}\n\nasync function upsertTrigger(\n request: (path: string, init: { method: string; body?: JsonValue }) => Promise<JsonObject | undefined>,\n slug: string,\n connectedAccountId: string,\n userId: string,\n triggerConfig: JsonObject,\n): Promise<void> {\n await request(`/api/v3/trigger_instances/${slug}/upsert`, {\n method: 'POST',\n body: {\n connected_account_id: connectedAccountId,\n user_id: userId,\n trigger_config: triggerConfig,\n },\n });\n}\n"
15 +"contents": "import { createHash, randomUUID } from 'node:crypto';\n\nimport { Composio } from '@composio/core';\n\nimport { jsonResponse } from '../api/http';\nimport type { AppConfig } from '../config/env';\nimport { htmlPages } from '../html/pages';\nimport { htmlFileResponse, htmlTemplateResponse } from '../html/render';\nimport { proxySlack } from '../slack/transport';\nimport type { Store } from '../store/file-store';\nimport { firstString, jsonObject } from '../utils/decode';\nimport type { JsonObject, JsonValue } from '../utils/json';\nimport { createComposioApiClient } from './api';\n\ntype ComposioSession = Awaited<ReturnType<Composio['sessions']['create']>>;\n\ninterface SharedSlackbotAuthorizeOptions {\n callbackUrl: string;\n experimental: {\n accountType: 'SHARED';\n };\n}\n\ninterface SlackbotSetupDeps {\n composio: Composio;\n config: AppConfig;\n store: Store;\n}\n\nexport interface SlackbotSetupService {\n completeSetup(url: URL): Promise<Response>;\n ensureSlackbotAuthConfig(): Promise<string | undefined>;\n ensureSlackbotTriggers(connectedAccountId: string): Promise<void>;\n ensureWebhookSubscription(): Promise<void>;\n startSetup(): Promise<Response>;\n}\n\n/**\n * Owns the install-time Slackbot plumbing:\n * - create/reuse a managed Slackbot auth config with the requested scopes\n * - request a shared Slackbot connection\n * - persist the team-scoped connected account\n * - ensure Composio webhook subscription + Slackbot triggers exist\n */\nexport function createSlackbotSetupService({ composio, config, store }: SlackbotSetupDeps): SlackbotSetupService {\n const composioApi = createComposioApiClient(config);\n\n const ensureSlackbotAuthConfig = async (): Promise<string | undefined> => {\n if (config.slackbotAuthConfigId) {\n return config.slackbotAuthConfigId;\n }\n\n const botScopes = uniqueSorted(config.slackbotBotScopes);\n const userScopes = uniqueSorted(config.slackbotUserScopes);\n if (botScopes.length === 0 && userScopes.length === 0) {\n return undefined;\n }\n\n const name = slackbotAuthConfigName(config, botScopes, userScopes);\n const existing = await composio.authConfigs.list({ toolkit: 'slackbot', isComposioManaged: true, limit: 100 });\n const match = authConfigItems(existing).find((item) => item.name === name);\n if (match?.id) {\n return match.id;\n }\n\n const created = await composio.authConfigs.create('slackbot', {\n type: 'use_composio_managed_auth',\n name,\n credentials: {\n scopes: botScopes,\n user_scopes: userScopes,\n },\n });\n console.log(`Created Slackbot Composio auth config ${created.id} (${name})`);\n return created.id;\n };\n\n const ensureWebhookSubscription = async (): Promise<void> => {\n const webhookUrl = `${config.appUrl}/webhooks/composio`;\n const body = {\n webhook_url: webhookUrl,\n enabled_events: ['composio.trigger.message'],\n version: 'V3',\n };\n\n const existing = await composioApi.request('/api/v3.1/webhook_subscriptions', { method: 'GET' });\n const subscription = firstObjectItem(existing?.items);\n const subscriptionId = firstString(subscription?.id);\n\n if (subscriptionId) {\n await composioApi.request(`/api/v3.1/webhook_subscriptions/${subscriptionId}`, {\n method: 'PATCH',\n body,\n });\n return;\n }\n\n await composioApi.request('/api/v3.1/webhook_subscriptions', {\n method: 'POST',\n body,\n });\n };\n\n const ensureSlackbotTriggers = async (connectedAccountId: string): Promise<void> => {\n const connectedAccount = await composioApi.request(`/api/v3/connected_accounts/${connectedAccountId}`, { method: 'GET' });\n const ownerUserId = firstString(connectedAccount?.user_id);\n if (!ownerUserId) {\n throw new Error(`Could not determine owner user_id for connected account ${connectedAccountId}`);\n }\n\n await upsertTrigger(composioApi.request, 'SLACKBOT_CHANNEL_MESSAGE_RECEIVED', connectedAccountId, ownerUserId, {\n is_bot_message: false,\n });\n\n await upsertTrigger(composioApi.request, 'SLACKBOT_DIRECT_MESSAGE_RECEIVED', connectedAccountId, ownerUserId, {});\n };\n\n const startSetup = async (): Promise<Response> => {\n const setupId = randomUUID();\n const setupUserId = `setup:slackbot:${setupId}`;\n const authConfigId = await ensureSlackbotAuthConfig();\n const session = await composio.sessions.create(setupUserId, {\n toolkits: ['slackbot'],\n authConfigs: authConfigId ? { slackbot: authConfigId } : {},\n manageConnections: true,\n workbench: { enable: false },\n });\n await store.setSlackbotSetup(setupId, session.sessionId, setupUserId);\n\n const connectionRequest = await session.authorize('slackbot', sharedSlackbotAuthorizeOptions(config, setupId));\n if (!connectionRequest.redirectUrl) {\n return jsonResponse({ ok: false, error: 'missing_redirect_url' }, 500);\n }\n\n return Response.redirect(connectionRequest.redirectUrl, 302);\n };\n\n const completeSetup = async (url: URL): Promise<Response> => {\n const setupId = url.searchParams.get('setup');\n const connectedAccountId = url.searchParams.get('connected_account_id');\n const status = url.searchParams.get('status');\n const setup = setupId ? store.getSlackbotSetup(setupId) : undefined;\n\n if (!setupId || !setup) {\n return htmlFileResponse(htmlPages.slackbotSetupExpired, 400);\n }\n\n if (!connectedAccountId || status !== 'success') {\n return htmlFileResponse(htmlPages.slackbotSetupFailed, 400);\n }\n\n const setupSession = await composio.sessions.use(setup.sessionId);\n await setupSession.update({ connectedAccounts: { slackbot: [connectedAccountId] } });\n const slackAuth = await slackAuthTest(setupSession);\n const teamId = slackAuth.teamId;\n await composio.experimental.updateAcl(connectedAccountId, { allowAllUsers: true });\n\n await store.setSlackbotConnection(teamId, connectedAccountId, {\n botUserId: slackAuth.botUserId,\n teamName: slackAuth.teamName,\n });\n await store.deleteSlackbotSetup(setupId);\n\n await ensureWebhookSubscription().catch((error) => {\n console.error('Failed to configure Composio webhook subscription after setup', error);\n });\n await ensureSlackbotTriggers(connectedAccountId).catch((error) => {\n console.error('Failed to create Slackbot triggers after setup', error);\n });\n\n return htmlTemplateResponse(htmlPages.slackbotConnected, { teamName: slackAuth.teamName ?? teamId });\n };\n\n return {\n completeSetup,\n ensureSlackbotAuthConfig,\n ensureSlackbotTriggers,\n ensureWebhookSubscription,\n startSetup,\n };\n}\n\nfunction sharedSlackbotAuthorizeOptions(config: AppConfig, setupId: string): SharedSlackbotAuthorizeOptions {\n const callbackUrl = new URL('/setup/slackbot/callback', config.appUrl);\n callbackUrl.searchParams.set('setup', setupId);\n\n return {\n callbackUrl: callbackUrl.toString(),\n experimental: {\n accountType: 'SHARED',\n },\n };\n}\n\nfunction slackbotAuthConfigName(config: AppConfig, botScopes: string[], userScopes: string[]): string {\n const scopeHash = createHash('sha256')\n .update(JSON.stringify({ botScopes, userScopes }))\n .digest('hex')\n .slice(0, 8);\n return `${config.slackbotAuthConfigName}-${scopeHash}`;\n}\n\nasync function slackAuthTest(session: ComposioSession): Promise<{ botUserId?: string; teamId: string; teamName?: string }> {\n return decodeSlackAuthTest(await proxySlack(session, 'auth.test', {}));\n}\n\nfunction decodeSlackAuthTest(response: unknown): { botUserId?: string; teamId: string; teamName?: string } {\n const responseObject = jsonObject(response) ?? {};\n const data = jsonObject(responseObject.data) ?? responseObject;\n const nestedData = jsonObject(data.data);\n\n if (data.ok === false) {\n throw new Error(`Slack auth.test failed: ${firstString(data.error) ?? JSON.stringify(data)}`);\n }\n\n const teamId = firstString(data.team_id, data.teamId, nestedData?.team_id, nestedData?.teamId);\n if (!teamId) {\n throw new Error(`Slack auth.test did not return team_id: ${JSON.stringify(data)}`);\n }\n\n return {\n botUserId: firstString(data.user_id, data.userId, data.bot_user_id, data.botUserId, nestedData?.user_id),\n teamId,\n teamName: firstString(data.team, data.team_name, data.teamName, nestedData?.team),\n };\n}\n\nfunction authConfigItems(value: unknown): Array<{ id?: string; name?: string }> {\n const record = jsonObject(value) ?? {};\n const items = Array.isArray(record.items) ? record.items : [];\n return items.flatMap((item): Array<{ id?: string; name?: string }> => {\n const object = jsonObject(item);\n if (!object) return [];\n return [\n {\n id: firstString(object.id),\n name: firstString(object.name),\n },\n ];\n });\n}\n\nfunction uniqueSorted(values: string[]): string[] {\n return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();\n}\n\nfunction firstObjectItem(value: JsonValue | undefined): JsonObject | undefined {\n return Array.isArray(value) ? jsonObject(value[0]) : undefined;\n}\n\nasync function upsertTrigger(\n request: (path: string, init: { method: string; body?: JsonValue }) => Promise<JsonObject | undefined>,\n slug: string,\n connectedAccountId: string,\n userId: string,\n triggerConfig: JsonObject,\n): Promise<void> {\n await request(`/api/v3/trigger_instances/${slug}/upsert`, {\n method: 'POST',\n body: {\n connected_account_id: connectedAccountId,\n user_id: userId,\n trigger_config: triggerConfig,\n },\n });\n}\n"
16 },
17 {
18 "path": "src/composio/routing-with-pi-provider.ts",
19 "composio": true,
20 -"contents": "import { Composio } from '@composio/core';\nimport { PiProvider, type PiSessionToolCapabilities } from '@composio/experimental';\n\nimport {\n authCallbackUrl,\n isSlackbotToolkit,\n isSlackbotToolSlug,\n isUserSlackToolSlug,\n normalizeRequestedToolkits,\n normalizeSearchToolkits,\n normalizeToolkitKey,\n normalizeToolkitStates,\n toolkitIsConnected,\n} from './helpers';\nimport type { AppConfig } from '../config/env';\nimport { assertSlackbotManualAcl } from '../slack/acl';\nimport type { NormalizedSlackTriggerEvent } from '../slack/events';\nimport type { Store } from '../store/file-store';\nimport type { JsonObject } from '../utils/json';\nimport type { ComposioRouting } from './routing';\n\ntype ComposioSession = Awaited<ReturnType<Composio['create']>>;\ntype HandleAuthLinks = <T>(value: T, sourceTool: string, requestedToolkits?: string[]) => Promise<T>;\n\ninterface ComposioRoutingWithPiProviderDeps {\n composio: Composio;\n config: AppConfig;\n store: Store;\n}\n\ninterface CapabilityDeps {\n config: AppConfig;\n event: NormalizedSlackTriggerEvent;\n handleAuthLinks: HandleAuthLinks;\n userSession: ComposioSession;\n}\n\nconst piProvider = new PiProvider();\n\n/**\n * Side-by-side experiment for using @composio/experimental's Pi provider.\n *\n * This uses the newer capability API rather than a fake session adapter:\n * app code owns search normalization, execution policy, connection state,\n * authorization, auth-link routing, and Slackbot shared-connection ACLs.\n */\nexport function createComposioRoutingWithPiProvider({\n composio,\n config,\n store,\n}: ComposioRoutingWithPiProviderDeps): ComposioRouting {\n const getOrCreateUserSession = async (\n event: NormalizedSlackTriggerEvent,\n userId: string,\n threadKey: string,\n ): Promise<ComposioSession> => {\n const slackbotConnectedAccountId = slackbotConnectedAccountIdForEvent(config, store, event);\n const existing = store.getThreadSession(threadKey);\n if (existing) {\n const session = await composio.use(existing.sessionId);\n await pinSlackbotConnectionIfAllowed(config, event, session, existing.userId, slackbotConnectedAccountId);\n return session;\n }\n\n if (slackbotConnectedAccountId) {\n assertSlackbotManualAcl(event, userId);\n }\n\n const session = await composio.sessions.create(userId, {\n manageConnections: {\n enable: true,\n callbackUrl: authCallbackUrl(config, event),\n waitForConnections: true,\n },\n workbench: {\n enable: config.composioWorkbenchEnabled,\n },\n ...(config.composioToolkits ? { toolkits: withSlackbotToolkit(config.composioToolkits, slackbotConnectedAccountId) } : {}),\n ...(config.composioAuthConfigs ? { authConfigs: config.composioAuthConfigs } : {}),\n ...(slackbotConnectedAccountId\n ? {\n connectedAccounts: {\n slackbot: [slackbotConnectedAccountId],\n },\n }\n : {}),\n });\n\n await store.setThreadSession(threadKey, session.sessionId, userId);\n return session;\n };\n\n const createPiComposioTools: ComposioRouting['createPiComposioTools'] = (event, userSession, handleAuthLinks) =>\n piProvider.createSessionTools(createPiCapabilities({ config, event, handleAuthLinks, userSession }));\n\n return {\n createPiComposioTools,\n getOrCreateUserSession,\n };\n}\n\nfunction createPiCapabilities({ config, event, handleAuthLinks, userSession }: CapabilityDeps): PiSessionToolCapabilities {\n const callbackUrl = authCallbackUrl(config, event);\n const includeWorkbenchTools = config.composioWorkbenchEnabled;\n\n return {\n callbackUrl,\n includeWorkbenchTools,\n sessionId: userSession.sessionId,\n search: (params) =>\n userSession.search({\n query: params.query,\n ...(params.toolkits ? { toolkits: params.toolkits } : {}),\n }),\n execute: async (toolSlug, args, options) => {\n if (isSlackbotToolSlug(toolSlug)) {\n assertSlackbotManualAcl(event, slackUserComposioId(event));\n }\n\n return userSession.execute(toolSlug, args, {\n ...(options?.account ? { account: options.account } : {}),\n });\n },\n connections: {\n getToolkitStates: async (toolkits) => {\n const normalizedToolkits = normalizeRequestedToolkits(toolkits) ?? [];\n const userToolkits = normalizedToolkits.filter(isUserAuthToolkit);\n const userStates = userToolkits.length > 0 ? normalizeToolkitStates(await userSession.toolkits({ toolkits: userToolkits })) : [];\n return {\n items: [\n ...normalizedToolkits.filter((toolkit) => !isUserAuthToolkit(toolkit)).map(syntheticConnectedToolkitState),\n ...userStates,\n ],\n };\n },\n authorizeToolkit: async (toolkit) => {\n if (!isUserAuthToolkit(toolkit)) {\n return slackbotAlreadyConnectedResult([toolkit]);\n }\n\n const request = await userSession.authorize(toolkit, { callbackUrl });\n return {\n status: 'needs_connection',\n redirectUrl: request.redirectUrl ?? null,\n };\n },\n isConnected: (state) => toolkitIsConnectedFromUnknown(state),\n },\n hooks: {\n search: (context, next) => {\n context.request.toolkits = normalizeSearchToolkits(context.request.toolkits) ?? undefined;\n return next();\n },\n execute: (context, next) => {\n const trimmedSlug = context.request.toolSlug.trim();\n\n if (isUserSlackToolSlug(trimmedSlug)) {\n return context.deny(USE_SLACKBOT_INSTEAD_ERROR);\n }\n\n if (trimmedSlug === 'COMPOSIO_MANAGE_CONNECTIONS') {\n return context.deny(USE_DEDICATED_MANAGE_CONNECTIONS_ERROR);\n }\n\n if (isSlackbotToolSlug(trimmedSlug)) {\n assertSlackbotManualAcl(event, slackUserComposioId(event));\n }\n\n context.request.toolSlug = trimmedSlug;\n return next();\n },\n onAuthLink: (context) => handleAuthLinks(context.result, context.sourceTool, context.toolkit ? [context.toolkit] : undefined),\n },\n transformResult: async ({ value, tool, requestedToolkits, context }) => {\n const sourceTool = context?.sourceTool ?? providerToolName(tool);\n return handleAuthLinks(value, sourceTool, requestedToolkits);\n },\n };\n}\n\nasync function pinSlackbotConnectionIfAllowed(\n config: AppConfig,\n event: NormalizedSlackTriggerEvent,\n session: ComposioSession,\n userId: string,\n slackbotConnectedAccountId: string | undefined,\n): Promise<void> {\n if (!slackbotConnectedAccountId) return;\n\n assertSlackbotManualAcl(event, userId);\n await session.update({\n ...(config.composioToolkits ? { toolkits: withSlackbotToolkit(config.composioToolkits, slackbotConnectedAccountId) } : {}),\n connectedAccounts: {\n slackbot: [slackbotConnectedAccountId],\n },\n });\n}\n\nfunction slackbotConnectedAccountIdForEvent(\n config: AppConfig,\n store: Store,\n event: NormalizedSlackTriggerEvent,\n): string | undefined {\n return config.slackbotSharedConnectedAccountId ?? store.getSlackbotConnection(event.teamId)?.connectedAccountId ?? event.connectedAccountId;\n}\n\nfunction withSlackbotToolkit(toolkits: string[], slackbotConnectedAccountId: string | undefined): string[] {\n if (!slackbotConnectedAccountId || toolkits.includes('slackbot')) return toolkits;\n return [...toolkits, 'slackbot'];\n}\n\nfunction isUserAuthToolkit(toolkit: string): boolean {\n const normalized = normalizeToolkitKey(toolkit);\n return Boolean(normalized && normalized !== 'slack' && normalized !== 'slackbot');\n}\n\nfunction syntheticConnectedToolkitState(toolkit: string): JsonObject {\n return {\n slug: normalizeToolkitKey(toolkit) === 'slack' ? 'slackbot' : toolkit,\n isNoAuth: true,\n connection: {\n isActive: true,\n connectedAccount: {\n status: 'ACTIVE',\n },\n },\n };\n}\n\nfunction toolkitIsConnectedFromUnknown(value: unknown): boolean {\n const states = normalizeToolkitStates({ items: [value] });\n return toolkitIsConnected(states[0]);\n}\n\nfunction providerToolName(tool: string): string {\n const names: Record<string, string> = {\n execute: 'composio_execute_tool',\n manageConnections: 'COMPOSIO_MANAGE_CONNECTIONS',\n remoteBash: 'COMPOSIO_REMOTE_BASH_TOOL',\n remoteWorkbench: 'COMPOSIO_REMOTE_WORKBENCH',\n search: 'composio_search_tools',\n };\n return names[tool] ?? tool;\n}\n\nfunction slackUserComposioId(event: NormalizedSlackTriggerEvent): string {\n return `slack:${event.teamId}:${event.userId}`;\n}\n\nfunction slackbotAlreadyConnectedResult(toolkits: string[]): JsonObject {\n return {\n successful: true,\n data: {\n message:\n 'Slack workspace actions use the already-connected shared Slackbot connection. Search the slackbot toolkit and execute SLACKBOT_* tools. Do not ask the user to connect Slack.',\n toolkits,\n },\n };\n}\n\nconst USE_DEDICATED_MANAGE_CONNECTIONS_ERROR =\n 'COMPOSIO_MANAGE_CONNECTIONS is not executable through composio_execute_tool. Use the dedicated composio_manage_connections helper, which checks session.toolkits and calls session.authorize for missing accounts.';\n\nconst USE_SLACKBOT_INSTEAD_ERROR =\n 'Use the slackbot toolkit for Slack workspace actions in this bot. Search with toolkits [\"slackbot\"] and execute a SLACKBOT_* tool instead of using the user-scoped Slack toolkit.';\n"
20 +"contents": "import { Composio } from '@composio/core';\nimport { PiProvider, type PiSessionToolCapabilities } from '@composio/experimental';\n\nimport {\n authCallbackUrl,\n isSlackbotToolkit,\n isSlackbotToolSlug,\n isUserSlackToolSlug,\n normalizeRequestedToolkits,\n normalizeSearchToolkits,\n normalizeToolkitKey,\n normalizeToolkitStates,\n toolkitIsConnected,\n} from './helpers';\nimport type { AppConfig } from '../config/env';\nimport { assertSlackbotManualAcl } from '../slack/acl';\nimport type { NormalizedSlackTriggerEvent } from '../slack/events';\nimport type { Store } from '../store/file-store';\nimport type { JsonObject } from '../utils/json';\nimport type { ComposioRouting } from './routing';\n\ntype ComposioSession = Awaited<ReturnType<Composio['sessions']['create']>>;\ntype HandleAuthLinks = <T>(value: T, sourceTool: string, requestedToolkits?: string[]) => Promise<T>;\n\ninterface ComposioRoutingWithPiProviderDeps {\n composio: Composio;\n config: AppConfig;\n store: Store;\n}\n\ninterface CapabilityDeps {\n config: AppConfig;\n event: NormalizedSlackTriggerEvent;\n handleAuthLinks: HandleAuthLinks;\n userSession: ComposioSession;\n}\n\nconst piProvider = new PiProvider();\n\n/**\n * Side-by-side experiment for using @composio/experimental's Pi provider.\n *\n * This uses the newer capability API rather than a fake session adapter:\n * app code owns search normalization, execution policy, connection state,\n * authorization, auth-link routing, and Slackbot shared-connection ACLs.\n */\nexport function createComposioRoutingWithPiProvider({\n composio,\n config,\n store,\n}: ComposioRoutingWithPiProviderDeps): ComposioRouting {\n const getOrCreateUserSession = async (\n event: NormalizedSlackTriggerEvent,\n userId: string,\n threadKey: string,\n ): Promise<ComposioSession> => {\n const slackbotConnectedAccountId = slackbotConnectedAccountIdForEvent(config, store, event);\n const existing = store.getThreadSession(threadKey);\n if (existing) {\n const session = await composio.sessions.use(existing.sessionId);\n await pinSlackbotConnectionIfAllowed(config, event, session, existing.userId, slackbotConnectedAccountId);\n return session;\n }\n\n if (slackbotConnectedAccountId) {\n assertSlackbotManualAcl(event, userId);\n }\n\n const session = await composio.sessions.create(userId, {\n manageConnections: {\n enable: true,\n callbackUrl: authCallbackUrl(config, event),\n waitForConnections: true,\n },\n workbench: {\n enable: config.composioWorkbenchEnabled,\n },\n ...(config.composioToolkits ? { toolkits: withSlackbotToolkit(config.composioToolkits, slackbotConnectedAccountId) } : {}),\n ...(config.composioAuthConfigs ? { authConfigs: config.composioAuthConfigs } : {}),\n ...(slackbotConnectedAccountId\n ? {\n connectedAccounts: {\n slackbot: [slackbotConnectedAccountId],\n },\n }\n : {}),\n });\n\n await store.setThreadSession(threadKey, session.sessionId, userId);\n return session;\n };\n\n const createPiComposioTools: ComposioRouting['createPiComposioTools'] = (event, userSession, handleAuthLinks) =>\n piProvider.createSessionTools(createPiCapabilities({ config, event, handleAuthLinks, userSession }));\n\n return {\n createPiComposioTools,\n getOrCreateUserSession,\n };\n}\n\nfunction createPiCapabilities({ config, event, handleAuthLinks, userSession }: CapabilityDeps): PiSessionToolCapabilities {\n const callbackUrl = authCallbackUrl(config, event);\n const includeWorkbenchTools = config.composioWorkbenchEnabled;\n\n return {\n callbackUrl,\n includeWorkbenchTools,\n sessionId: userSession.sessionId,\n search: (params) =>\n userSession.search({\n query: params.query,\n ...(params.toolkits ? { toolkits: params.toolkits } : {}),\n }),\n execute: async (toolSlug, args, options) => {\n if (isSlackbotToolSlug(toolSlug)) {\n assertSlackbotManualAcl(event, slackUserComposioId(event));\n }\n\n return userSession.execute(toolSlug, args, {\n ...(options?.account ? { account: options.account } : {}),\n });\n },\n connections: {\n getToolkitStates: async (toolkits) => {\n const normalizedToolkits = normalizeRequestedToolkits(toolkits) ?? [];\n const userToolkits = normalizedToolkits.filter(isUserAuthToolkit);\n const userStates = userToolkits.length > 0 ? normalizeToolkitStates(await userSession.toolkits({ toolkits: userToolkits })) : [];\n return {\n items: [\n ...normalizedToolkits.filter((toolkit) => !isUserAuthToolkit(toolkit)).map(syntheticConnectedToolkitState),\n ...userStates,\n ],\n };\n },\n authorizeToolkit: async (toolkit) => {\n if (!isUserAuthToolkit(toolkit)) {\n return slackbotAlreadyConnectedResult([toolkit]);\n }\n\n const request = await userSession.authorize(toolkit, { callbackUrl });\n return {\n status: 'needs_connection',\n redirectUrl: request.redirectUrl ?? null,\n };\n },\n isConnected: (state) => toolkitIsConnectedFromUnknown(state),\n },\n hooks: {\n search: (context, next) => {\n context.request.toolkits = normalizeSearchToolkits(context.request.toolkits) ?? undefined;\n return next();\n },\n execute: (context, next) => {\n const trimmedSlug = context.request.toolSlug.trim();\n\n if (isUserSlackToolSlug(trimmedSlug)) {\n return context.deny(USE_SLACKBOT_INSTEAD_ERROR);\n }\n\n if (trimmedSlug === 'COMPOSIO_MANAGE_CONNECTIONS') {\n return context.deny(USE_DEDICATED_MANAGE_CONNECTIONS_ERROR);\n }\n\n if (isSlackbotToolSlug(trimmedSlug)) {\n assertSlackbotManualAcl(event, slackUserComposioId(event));\n }\n\n context.request.toolSlug = trimmedSlug;\n return next();\n },\n onAuthLink: (context) => handleAuthLinks(context.result, context.sourceTool, context.toolkit ? [context.toolkit] : undefined),\n },\n transformResult: async ({ value, tool, requestedToolkits, context }) => {\n const sourceTool = context?.sourceTool ?? providerToolName(tool);\n return handleAuthLinks(value, sourceTool, requestedToolkits);\n },\n };\n}\n\nasync function pinSlackbotConnectionIfAllowed(\n config: AppConfig,\n event: NormalizedSlackTriggerEvent,\n session: ComposioSession,\n userId: string,\n slackbotConnectedAccountId: string | undefined,\n): Promise<void> {\n if (!slackbotConnectedAccountId) return;\n\n assertSlackbotManualAcl(event, userId);\n await session.update({\n ...(config.composioToolkits ? { toolkits: withSlackbotToolkit(config.composioToolkits, slackbotConnectedAccountId) } : {}),\n connectedAccounts: {\n slackbot: [slackbotConnectedAccountId],\n },\n });\n}\n\nfunction slackbotConnectedAccountIdForEvent(\n config: AppConfig,\n store: Store,\n event: NormalizedSlackTriggerEvent,\n): string | undefined {\n return config.slackbotSharedConnectedAccountId ?? store.getSlackbotConnection(event.teamId)?.connectedAccountId ?? event.connectedAccountId;\n}\n\nfunction withSlackbotToolkit(toolkits: string[], slackbotConnectedAccountId: string | undefined): string[] {\n if (!slackbotConnectedAccountId || toolkits.includes('slackbot')) return toolkits;\n return [...toolkits, 'slackbot'];\n}\n\nfunction isUserAuthToolkit(toolkit: string): boolean {\n const normalized = normalizeToolkitKey(toolkit);\n return Boolean(normalized && normalized !== 'slack' && normalized !== 'slackbot');\n}\n\nfunction syntheticConnectedToolkitState(toolkit: string): JsonObject {\n return {\n slug: normalizeToolkitKey(toolkit) === 'slack' ? 'slackbot' : toolkit,\n isNoAuth: true,\n connection: {\n isActive: true,\n connectedAccount: {\n status: 'ACTIVE',\n },\n },\n };\n}\n\nfunction toolkitIsConnectedFromUnknown(value: unknown): boolean {\n const states = normalizeToolkitStates({ items: [value] });\n return toolkitIsConnected(states[0]);\n}\n\nfunction providerToolName(tool: string): string {\n const names: Record<string, string> = {\n execute: 'composio_execute_tool',\n manageConnections: 'COMPOSIO_MANAGE_CONNECTIONS',\n remoteBash: 'COMPOSIO_REMOTE_BASH_TOOL',\n remoteWorkbench: 'COMPOSIO_REMOTE_WORKBENCH',\n search: 'composio_search_tools',\n };\n return names[tool] ?? tool;\n}\n\nfunction slackUserComposioId(event: NormalizedSlackTriggerEvent): string {\n return `slack:${event.teamId}:${event.userId}`;\n}\n\nfunction slackbotAlreadyConnectedResult(toolkits: string[]): JsonObject {\n return {\n successful: true,\n data: {\n message:\n 'Slack workspace actions use the already-connected shared Slackbot connection. Search the slackbot toolkit and execute SLACKBOT_* tools. Do not ask the user to connect Slack.',\n toolkits,\n },\n };\n}\n\nconst USE_DEDICATED_MANAGE_CONNECTIONS_ERROR =\n 'COMPOSIO_MANAGE_CONNECTIONS is not executable through composio_execute_tool. Use the dedicated composio_manage_connections helper, which checks session.toolkits and calls session.authorize for missing accounts.';\n\nconst USE_SLACKBOT_INSTEAD_ERROR =\n 'Use the slackbot toolkit for Slack workspace actions in this bot. Search with toolkits [\"slackbot\"] and execute a SLACKBOT_* tool instead of using the user-scoped Slack toolkit.';\n"
21 },
22 {
23 "path": "src/agent/slack-composio-agent.ts",
@@ -32,7 +32,7 @@
32 {
33 "path": "src/slack/transport.ts",
34 "composio": true,
35 -"contents": "import { Composio } from '@composio/core';\n\nimport type { AppConfig } from '../config/env';\nimport type { Store } from '../store/file-store';\nimport { firstString, jsonObject } from '../utils/decode';\nimport type { JsonObject, JsonValue } from '../utils/json';\nimport type { NormalizedSlackTriggerEvent } from './events';\n\ntype ComposioSession = Awaited<ReturnType<Composio['create']>>;\n\ntype CachedSlackUserContext = {\n context: SlackUserContext;\n expiresAt: number;\n refresh?: Promise<SlackUserContext>;\n};\n\nconst USER_CONTEXT_CACHE_TTL_MS = 6 * 60 * 60 * 1000;\n\nexport interface SlackMessageOptions {\n channel: string;\n text: string;\n threadTs?: string;\n}\n\nexport interface SlackUpdateMessageOptions {\n channel: string;\n text: string;\n ts: string;\n}\n\nexport interface SlackThreadStatusOptions {\n channel: string;\n loadingMessages?: string[];\n status: string;\n threadTs: string;\n}\n\nexport interface SlackThreadMessage {\n botId?: string | null;\n isBot: boolean;\n subtype?: string | null;\n text: string;\n ts: string;\n userId?: string;\n username?: string;\n}\n\nexport interface SlackFetchThreadOptions {\n channel: string;\n maxMessages?: number;\n threadTs: string;\n}\n\nexport interface SlackUserContext {\n locale?: string;\n localTime?: string;\n timeZone?: string;\n timeZoneLabel?: string;\n timeZoneOffsetSeconds?: number;\n userId: string;\n}\n\nexport interface SlackTransport {\n addReaction(channel: string, timestamp: string, name: string, event?: NormalizedSlackTriggerEvent): Promise<void>;\n clearThreadStatus(options: Omit<SlackThreadStatusOptions, 'loadingMessages' | 'status'>, event?: NormalizedSlackTriggerEvent): Promise<void>;\n fetchThreadMessages(options: SlackFetchThreadOptions, event?: NormalizedSlackTriggerEvent): Promise<SlackThreadMessage[]>;\n fetchUserContext(userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext>;\n postDm(userId: string, text: string, event?: NormalizedSlackTriggerEvent): Promise<string | undefined>;\n postMessage(options: SlackMessageOptions, event?: NormalizedSlackTriggerEvent): Promise<string | undefined>;\n updateMessage(options: SlackUpdateMessageOptions, event?: NormalizedSlackTriggerEvent): Promise<void>;\n setThreadStatus(options: SlackThreadStatusOptions, event?: NormalizedSlackTriggerEvent): Promise<void>;\n}\n\ninterface SlackTransportDeps {\n config: AppConfig;\n store: Store;\n}\n\n/**\n * Slack transport backed by a Composio Slackbot connected account.\n * The Slack bot token stays in Composio; this app stores only ca_* ids.\n */\nexport function createSlackTransport({ config, store }: SlackTransportDeps): SlackTransport {\n const composio = new Composio({ apiKey: config.composioApiKey });\n const dmChannels = new Map<string, string>();\n const sessions = new Map<string, ComposioSession>();\n const userContexts = new Map<string, CachedSlackUserContext>();\n\n const sessionForEvent = async (event?: NormalizedSlackTriggerEvent): Promise<ComposioSession> => {\n const connectedAccountId = connectedAccountIdForEvent(config, store, event);\n const cached = sessions.get(connectedAccountId);\n if (cached) return cached;\n\n const session = await composio.create(transportUserIdForEvent(config, event), {\n toolkits: ['slackbot'],\n connectedAccounts: {\n slackbot: [connectedAccountId],\n },\n manageConnections: false,\n workbench: { enable: false },\n });\n\n sessions.set(connectedAccountId, session);\n return session;\n };\n\n const openDm = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<string> => {\n const cacheKey = `${connectedAccountIdForEvent(config, store, event)}:${userId}`;\n const cached = dmChannels.get(cacheKey);\n if (cached) return cached;\n\n const session = await sessionForEvent(event);\n const response = await proxySlack(session, 'conversations.open', { users: userId });\n const channelId = decodeOpenDmChannelId(response);\n if (!channelId) {\n throw new Error(`Slack conversations.open did not return a channel id for user ${userId}: ${JSON.stringify(response)}`);\n }\n\n dmChannels.set(cacheKey, channelId);\n return channelId;\n };\n\n const postMessage = async (\n { channel, text, threadTs }: SlackMessageOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<string | undefined> => {\n const session = await sessionForEvent(event);\n const response = await proxySlack(session, 'chat.postMessage', {\n channel,\n text,\n mrkdwn: true,\n thread_ts: threadTs,\n unfurl_links: false,\n unfurl_media: false,\n });\n\n return decodePostMessageTimestamp(response);\n };\n\n const updateMessage = async (\n { channel, text, ts }: SlackUpdateMessageOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<void> => {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'chat.update', {\n channel,\n ts,\n text,\n mrkdwn: true,\n unfurl_links: false,\n unfurl_media: false,\n });\n };\n\n const setThreadStatus = async (\n { channel, threadTs, status, loadingMessages }: SlackThreadStatusOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<void> => {\n try {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'assistant.threads.setStatus', {\n channel_id: channel,\n thread_ts: threadTs,\n status,\n loading_messages: loadingMessages,\n });\n } catch (error) {\n // Status indicators are optional polish. Missing Slack AI app capability should not break replies.\n console.warn('Failed to set Slack assistant thread status', summarizeError(error));\n }\n };\n\n const fetchThreadMessages = async (\n { channel, threadTs, maxMessages = Number.MAX_SAFE_INTEGER }: SlackFetchThreadOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<SlackThreadMessage[]> => {\n const session = await sessionForEvent(event);\n const messages: SlackThreadMessage[] = [];\n let cursor: string | undefined;\n\n do {\n const response = await proxySlackGet(session, 'conversations.replies', {\n channel,\n ts: threadTs,\n limit: Math.min(200, Math.max(1, maxMessages - messages.length)),\n cursor,\n });\n messages.push(...decodeThreadMessages(response));\n cursor = decodeNextCursor(response);\n } while (cursor && messages.length < maxMessages);\n\n return messages.slice(0, maxMessages);\n };\n\n const requestUserContext = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const session = await sessionForEvent(event);\n const response = await proxySlackGet(session, 'users.info', {\n user: userId,\n include_locale: 'true',\n });\n return decodeUserContext(response, userId);\n };\n\n const refreshUserContext = (cacheKey: string, userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const refresh = requestUserContext(userId, event)\n .then((context) => {\n const cached = {\n context,\n expiresAt: Date.now() + USER_CONTEXT_CACHE_TTL_MS,\n };\n userContexts.set(cacheKey, cached);\n return withFreshLocalTime(context);\n })\n .catch((error) => {\n const existing = userContexts.get(cacheKey);\n if (existing) {\n userContexts.set(cacheKey, { context: existing.context, expiresAt: existing.expiresAt });\n }\n throw error;\n });\n\n const existing = userContexts.get(cacheKey);\n if (existing) {\n userContexts.set(cacheKey, { ...existing, refresh });\n }\n return refresh;\n };\n\n const fetchUserContext = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const cacheKey = `${connectedAccountIdForEvent(config, store, event)}:${userId}`;\n const now = Date.now();\n const cached = userContexts.get(cacheKey);\n if (cached && cached.expiresAt > now) {\n return withFreshLocalTime(cached.context);\n }\n\n if (cached) {\n if (!cached.refresh) {\n const refresh = refreshUserContext(cacheKey, userId, event).catch((error) => {\n console.warn('Failed to refresh cached Slack user timezone context', summarizeError(error));\n return withFreshLocalTime(cached.context);\n });\n userContexts.set(cacheKey, { ...cached, refresh });\n }\n return withFreshLocalTime(cached.context);\n }\n\n const fallback = { userId };\n const refresh = refreshUserContext(cacheKey, userId, event).catch((error) => {\n console.warn('Failed to fetch Slack user timezone context', summarizeError(error));\n return fallback;\n });\n userContexts.set(cacheKey, {\n context: fallback,\n expiresAt: 0,\n refresh,\n });\n return fallback;\n };\n\n return {\n addReaction: async (channel, timestamp, name, event) => {\n try {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'reactions.add', { channel, timestamp, name });\n } catch (error) {\n // Reactions are optional polish. Missing scopes or duplicate reactions should not break handling.\n console.warn('Failed to add Slack reaction', summarizeError(error));\n }\n },\n\n clearThreadStatus: async ({ channel, threadTs }, event) => {\n await setThreadStatus({ channel, threadTs, status: '' }, event);\n },\n\n fetchThreadMessages,\n fetchUserContext,\n\n postDm: async (userId, text, event) => {\n const channel = await openDm(userId, event);\n return postMessage({ channel, text }, event);\n },\n\n postMessage,\n setThreadStatus,\n updateMessage,\n };\n}\n\nexport async function proxySlack(\n session: ComposioSession,\n method: string,\n body: Record<string, JsonValue | undefined>,\n): Promise<JsonValue> {\n const response = await session.proxyExecute({\n toolkit: 'slackbot',\n endpoint: `https://slack.com/api/${method}`,\n method: 'POST',\n body: stripUndefined(body),\n });\n\n return decodeSlackApiResponse(method, response);\n}\n\nasync function proxySlackGet(\n session: ComposioSession,\n method: string,\n query: Record<string, string | number | undefined>,\n): Promise<JsonValue> {\n const response = await session.proxyExecute({\n toolkit: 'slackbot',\n endpoint: `https://slack.com/api/${method}`,\n method: 'GET',\n parameters: queryParameters(query),\n });\n\n return decodeSlackApiResponse(method, response);\n}\n\nfunction decodeSlackApiResponse(method: string, response: unknown): JsonValue {\n const responseObject = jsonObject(response) ?? {};\n const slackPayload = jsonObject(responseObject.data) ?? responseObject;\n\n if (slackPayload.ok === false) {\n throw new Error(`Slack API ${method} failed: ${firstString(slackPayload.error) ?? JSON.stringify(slackPayload)}`);\n }\n\n return slackPayload;\n}\n\nfunction decodeOpenDmChannelId(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const channel = jsonObject(payload.channel) ?? jsonObject(jsonObject(payload.data)?.channel);\n return firstString(channel?.id);\n}\n\nfunction decodePostMessageTimestamp(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const data = jsonObject(payload.data);\n const message = jsonObject(payload.message);\n return firstString(payload.ts, data?.ts, message?.ts);\n}\n\nfunction decodeThreadMessages(response: JsonValue): SlackThreadMessage[] {\n const payload = jsonObject(response) ?? {};\n const rawMessages = Array.isArray(payload.messages) ? payload.messages : [];\n\n return rawMessages.flatMap((rawMessage): SlackThreadMessage[] => {\n const message = jsonObject(rawMessage);\n const ts = firstString(message?.ts);\n if (!message || !ts) return [];\n\n return [\n {\n botId: firstString(message.bot_id, message.botId) ?? null,\n isBot: Boolean(firstString(message.bot_id, message.botId)) || typeof message.bot_profile === 'object',\n subtype: firstString(message.subtype) ?? null,\n text: messageTextWithFiles(message),\n ts,\n userId: firstString(message.user, message.user_id, message.userId),\n username: firstString(message.username, message.user_name, message.userName),\n },\n ];\n });\n}\n\nfunction decodeNextCursor(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const metadata = jsonObject(payload.response_metadata) ?? jsonObject(payload.responseMetadata);\n return firstString(metadata?.next_cursor, metadata?.nextCursor);\n}\n\nfunction decodeUserContext(response: JsonValue, fallbackUserId: string): SlackUserContext {\n const payload = jsonObject(response) ?? {};\n const data = jsonObject(payload.data);\n const user = jsonObject(payload.user) ?? jsonObject(data?.user) ?? {};\n const profile = jsonObject(user.profile) ?? {};\n const timeZone = firstString(user.tz, user.timezone, profile.tz, profile.timezone);\n\n return {\n locale: firstString(user.locale, profile.locale),\n localTime: timeZone ? formatLocalTime(timeZone) : undefined,\n timeZone,\n timeZoneLabel: firstString(user.tz_label, user.tzLabel),\n timeZoneOffsetSeconds: firstNumber(user.tz_offset, user.tzOffset),\n userId: firstString(user.id) ?? fallbackUserId,\n };\n}\n\nfunction messageTextWithFiles(message: JsonObject): string {\n const text = firstString(message.text) ?? '';\n const files = Array.isArray(message.files) ? message.files : [];\n const fileSummaries = files.flatMap((rawFile): string[] => {\n const file = jsonObject(rawFile);\n if (!file) return [];\n const title = firstString(file.title, file.name) ?? 'file';\n const url = firstString(file.permalink, file.url_private, file.urlPrivate);\n return [url ? `[file: ${title} ${url}]` : `[file: ${title}]`];\n });\n\n return [text, ...fileSummaries].filter(Boolean).join('\\n');\n}\n\nfunction firstNumber(...values: unknown[]): number | undefined {\n for (const value of values) {\n if (typeof value === 'number' && Number.isFinite(value)) return value;\n if (typeof value !== 'string' || !value.trim()) continue;\n const parsed = Number(value);\n if (Number.isFinite(parsed)) return parsed;\n }\n return undefined;\n}\n\nfunction withFreshLocalTime(context: SlackUserContext): SlackUserContext {\n return {\n ...context,\n localTime: context.timeZone ? formatLocalTime(context.timeZone) : undefined,\n };\n}\n\nfunction formatLocalTime(timeZone: string): string | undefined {\n try {\n return new Intl.DateTimeFormat('en-US', {\n dateStyle: 'full',\n timeStyle: 'long',\n timeZone,\n }).format(new Date());\n } catch {\n return undefined;\n }\n}\n\nfunction connectedAccountIdForEvent(config: AppConfig, store: Store, event?: NormalizedSlackTriggerEvent): string {\n const id =\n config.slackbotSharedConnectedAccountId ??\n event?.connectedAccountId ??\n (event?.teamId ? store.getSlackbotConnection(event.teamId)?.connectedAccountId : undefined);\n if (!id) {\n throw new Error(\n 'Missing Slackbot transport connected account. Open /setup/slackbot/start to install Slackbot or set SLACKBOT_SHARED_CONNECTED_ACCOUNT_ID.',\n );\n }\n return id;\n}\n\nfunction transportUserIdForEvent(config: AppConfig, event?: NormalizedSlackTriggerEvent): string {\n if (config.slackbotTransportUserId) return config.slackbotTransportUserId;\n if (!event?.teamId || event.teamId === 'unknown-team') {\n throw new Error('Missing Slack team id; cannot derive Slackbot transport user id service:${teamId}.');\n }\n return `service:${event.teamId}`;\n}\n\nfunction stripUndefined(value: Record<string, JsonValue | undefined>): JsonObject {\n return Object.fromEntries(Object.entries(value).filter(([, nested]) => nested !== undefined)) as JsonObject;\n}\n\nfunction queryParameters(value: Record<string, string | number | undefined>): Array<{ in: 'query'; name: string; value: string | number }> {\n return Object.entries(value).flatMap(([name, nested]) => (nested === undefined ? [] : [{ in: 'query' as const, name, value: nested }]));\n}\n\nfunction summarizeError(error: Error | unknown): string {\n if (error instanceof Error) return error.message;\n return String(error);\n}\n"
35 +"contents": "import { Composio } from '@composio/core';\n\nimport type { AppConfig } from '../config/env';\nimport type { Store } from '../store/file-store';\nimport { firstString, jsonObject } from '../utils/decode';\nimport type { JsonObject, JsonValue } from '../utils/json';\nimport type { NormalizedSlackTriggerEvent } from './events';\n\ntype ComposioSession = Awaited<ReturnType<Composio['sessions']['create']>>;\n\ntype CachedSlackUserContext = {\n context: SlackUserContext;\n expiresAt: number;\n refresh?: Promise<SlackUserContext>;\n};\n\nconst USER_CONTEXT_CACHE_TTL_MS = 6 * 60 * 60 * 1000;\n\nexport interface SlackMessageOptions {\n channel: string;\n text: string;\n threadTs?: string;\n}\n\nexport interface SlackUpdateMessageOptions {\n channel: string;\n text: string;\n ts: string;\n}\n\nexport interface SlackThreadStatusOptions {\n channel: string;\n loadingMessages?: string[];\n status: string;\n threadTs: string;\n}\n\nexport interface SlackThreadMessage {\n botId?: string | null;\n isBot: boolean;\n subtype?: string | null;\n text: string;\n ts: string;\n userId?: string;\n username?: string;\n}\n\nexport interface SlackFetchThreadOptions {\n channel: string;\n maxMessages?: number;\n threadTs: string;\n}\n\nexport interface SlackUserContext {\n locale?: string;\n localTime?: string;\n timeZone?: string;\n timeZoneLabel?: string;\n timeZoneOffsetSeconds?: number;\n userId: string;\n}\n\nexport interface SlackTransport {\n addReaction(channel: string, timestamp: string, name: string, event?: NormalizedSlackTriggerEvent): Promise<void>;\n clearThreadStatus(options: Omit<SlackThreadStatusOptions, 'loadingMessages' | 'status'>, event?: NormalizedSlackTriggerEvent): Promise<void>;\n fetchThreadMessages(options: SlackFetchThreadOptions, event?: NormalizedSlackTriggerEvent): Promise<SlackThreadMessage[]>;\n fetchUserContext(userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext>;\n postDm(userId: string, text: string, event?: NormalizedSlackTriggerEvent): Promise<string | undefined>;\n postMessage(options: SlackMessageOptions, event?: NormalizedSlackTriggerEvent): Promise<string | undefined>;\n updateMessage(options: SlackUpdateMessageOptions, event?: NormalizedSlackTriggerEvent): Promise<void>;\n setThreadStatus(options: SlackThreadStatusOptions, event?: NormalizedSlackTriggerEvent): Promise<void>;\n}\n\ninterface SlackTransportDeps {\n config: AppConfig;\n store: Store;\n}\n\n/**\n * Slack transport backed by a Composio Slackbot connected account.\n * The Slack bot token stays in Composio; this app stores only ca_* ids.\n */\nexport function createSlackTransport({ config, store }: SlackTransportDeps): SlackTransport {\n const composio = new Composio({ apiKey: config.composioApiKey });\n const dmChannels = new Map<string, string>();\n const sessions = new Map<string, ComposioSession>();\n const userContexts = new Map<string, CachedSlackUserContext>();\n\n const sessionForEvent = async (event?: NormalizedSlackTriggerEvent): Promise<ComposioSession> => {\n const connectedAccountId = connectedAccountIdForEvent(config, store, event);\n const cached = sessions.get(connectedAccountId);\n if (cached) return cached;\n\n const session = await composio.sessions.create(transportUserIdForEvent(config, event), {\n toolkits: ['slackbot'],\n connectedAccounts: {\n slackbot: [connectedAccountId],\n },\n manageConnections: false,\n workbench: { enable: false },\n });\n\n sessions.set(connectedAccountId, session);\n return session;\n };\n\n const openDm = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<string> => {\n const cacheKey = `${connectedAccountIdForEvent(config, store, event)}:${userId}`;\n const cached = dmChannels.get(cacheKey);\n if (cached) return cached;\n\n const session = await sessionForEvent(event);\n const response = await proxySlack(session, 'conversations.open', { users: userId });\n const channelId = decodeOpenDmChannelId(response);\n if (!channelId) {\n throw new Error(`Slack conversations.open did not return a channel id for user ${userId}: ${JSON.stringify(response)}`);\n }\n\n dmChannels.set(cacheKey, channelId);\n return channelId;\n };\n\n const postMessage = async (\n { channel, text, threadTs }: SlackMessageOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<string | undefined> => {\n const session = await sessionForEvent(event);\n const response = await proxySlack(session, 'chat.postMessage', {\n channel,\n text,\n mrkdwn: true,\n thread_ts: threadTs,\n unfurl_links: false,\n unfurl_media: false,\n });\n\n return decodePostMessageTimestamp(response);\n };\n\n const updateMessage = async (\n { channel, text, ts }: SlackUpdateMessageOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<void> => {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'chat.update', {\n channel,\n ts,\n text,\n mrkdwn: true,\n unfurl_links: false,\n unfurl_media: false,\n });\n };\n\n const setThreadStatus = async (\n { channel, threadTs, status, loadingMessages }: SlackThreadStatusOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<void> => {\n try {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'assistant.threads.setStatus', {\n channel_id: channel,\n thread_ts: threadTs,\n status,\n loading_messages: loadingMessages,\n });\n } catch (error) {\n // Status indicators are optional polish. Missing Slack AI app capability should not break replies.\n console.warn('Failed to set Slack assistant thread status', summarizeError(error));\n }\n };\n\n const fetchThreadMessages = async (\n { channel, threadTs, maxMessages = Number.MAX_SAFE_INTEGER }: SlackFetchThreadOptions,\n event?: NormalizedSlackTriggerEvent,\n ): Promise<SlackThreadMessage[]> => {\n const session = await sessionForEvent(event);\n const messages: SlackThreadMessage[] = [];\n let cursor: string | undefined;\n\n do {\n const response = await proxySlackGet(session, 'conversations.replies', {\n channel,\n ts: threadTs,\n limit: Math.min(200, Math.max(1, maxMessages - messages.length)),\n cursor,\n });\n messages.push(...decodeThreadMessages(response));\n cursor = decodeNextCursor(response);\n } while (cursor && messages.length < maxMessages);\n\n return messages.slice(0, maxMessages);\n };\n\n const requestUserContext = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const session = await sessionForEvent(event);\n const response = await proxySlackGet(session, 'users.info', {\n user: userId,\n include_locale: 'true',\n });\n return decodeUserContext(response, userId);\n };\n\n const refreshUserContext = (cacheKey: string, userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const refresh = requestUserContext(userId, event)\n .then((context) => {\n const cached = {\n context,\n expiresAt: Date.now() + USER_CONTEXT_CACHE_TTL_MS,\n };\n userContexts.set(cacheKey, cached);\n return withFreshLocalTime(context);\n })\n .catch((error) => {\n const existing = userContexts.get(cacheKey);\n if (existing) {\n userContexts.set(cacheKey, { context: existing.context, expiresAt: existing.expiresAt });\n }\n throw error;\n });\n\n const existing = userContexts.get(cacheKey);\n if (existing) {\n userContexts.set(cacheKey, { ...existing, refresh });\n }\n return refresh;\n };\n\n const fetchUserContext = async (userId: string, event?: NormalizedSlackTriggerEvent): Promise<SlackUserContext> => {\n const cacheKey = `${connectedAccountIdForEvent(config, store, event)}:${userId}`;\n const now = Date.now();\n const cached = userContexts.get(cacheKey);\n if (cached && cached.expiresAt > now) {\n return withFreshLocalTime(cached.context);\n }\n\n if (cached) {\n if (!cached.refresh) {\n const refresh = refreshUserContext(cacheKey, userId, event).catch((error) => {\n console.warn('Failed to refresh cached Slack user timezone context', summarizeError(error));\n return withFreshLocalTime(cached.context);\n });\n userContexts.set(cacheKey, { ...cached, refresh });\n }\n return withFreshLocalTime(cached.context);\n }\n\n const fallback = { userId };\n const refresh = refreshUserContext(cacheKey, userId, event).catch((error) => {\n console.warn('Failed to fetch Slack user timezone context', summarizeError(error));\n return fallback;\n });\n userContexts.set(cacheKey, {\n context: fallback,\n expiresAt: 0,\n refresh,\n });\n return fallback;\n };\n\n return {\n addReaction: async (channel, timestamp, name, event) => {\n try {\n const session = await sessionForEvent(event);\n await proxySlack(session, 'reactions.add', { channel, timestamp, name });\n } catch (error) {\n // Reactions are optional polish. Missing scopes or duplicate reactions should not break handling.\n console.warn('Failed to add Slack reaction', summarizeError(error));\n }\n },\n\n clearThreadStatus: async ({ channel, threadTs }, event) => {\n await setThreadStatus({ channel, threadTs, status: '' }, event);\n },\n\n fetchThreadMessages,\n fetchUserContext,\n\n postDm: async (userId, text, event) => {\n const channel = await openDm(userId, event);\n return postMessage({ channel, text }, event);\n },\n\n postMessage,\n setThreadStatus,\n updateMessage,\n };\n}\n\nexport async function proxySlack(\n session: ComposioSession,\n method: string,\n body: Record<string, JsonValue | undefined>,\n): Promise<JsonValue> {\n const response = await session.proxyExecute({\n toolkit: 'slackbot',\n endpoint: `https://slack.com/api/${method}`,\n method: 'POST',\n body: stripUndefined(body),\n });\n\n return decodeSlackApiResponse(method, response);\n}\n\nasync function proxySlackGet(\n session: ComposioSession,\n method: string,\n query: Record<string, string | number | undefined>,\n): Promise<JsonValue> {\n const response = await session.proxyExecute({\n toolkit: 'slackbot',\n endpoint: `https://slack.com/api/${method}`,\n method: 'GET',\n parameters: queryParameters(query),\n });\n\n return decodeSlackApiResponse(method, response);\n}\n\nfunction decodeSlackApiResponse(method: string, response: unknown): JsonValue {\n const responseObject = jsonObject(response) ?? {};\n const slackPayload = jsonObject(responseObject.data) ?? responseObject;\n\n if (slackPayload.ok === false) {\n throw new Error(`Slack API ${method} failed: ${firstString(slackPayload.error) ?? JSON.stringify(slackPayload)}`);\n }\n\n return slackPayload;\n}\n\nfunction decodeOpenDmChannelId(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const channel = jsonObject(payload.channel) ?? jsonObject(jsonObject(payload.data)?.channel);\n return firstString(channel?.id);\n}\n\nfunction decodePostMessageTimestamp(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const data = jsonObject(payload.data);\n const message = jsonObject(payload.message);\n return firstString(payload.ts, data?.ts, message?.ts);\n}\n\nfunction decodeThreadMessages(response: JsonValue): SlackThreadMessage[] {\n const payload = jsonObject(response) ?? {};\n const rawMessages = Array.isArray(payload.messages) ? payload.messages : [];\n\n return rawMessages.flatMap((rawMessage): SlackThreadMessage[] => {\n const message = jsonObject(rawMessage);\n const ts = firstString(message?.ts);\n if (!message || !ts) return [];\n\n return [\n {\n botId: firstString(message.bot_id, message.botId) ?? null,\n isBot: Boolean(firstString(message.bot_id, message.botId)) || typeof message.bot_profile === 'object',\n subtype: firstString(message.subtype) ?? null,\n text: messageTextWithFiles(message),\n ts,\n userId: firstString(message.user, message.user_id, message.userId),\n username: firstString(message.username, message.user_name, message.userName),\n },\n ];\n });\n}\n\nfunction decodeNextCursor(response: JsonValue): string | undefined {\n const payload = jsonObject(response) ?? {};\n const metadata = jsonObject(payload.response_metadata) ?? jsonObject(payload.responseMetadata);\n return firstString(metadata?.next_cursor, metadata?.nextCursor);\n}\n\nfunction decodeUserContext(response: JsonValue, fallbackUserId: string): SlackUserContext {\n const payload = jsonObject(response) ?? {};\n const data = jsonObject(payload.data);\n const user = jsonObject(payload.user) ?? jsonObject(data?.user) ?? {};\n const profile = jsonObject(user.profile) ?? {};\n const timeZone = firstString(user.tz, user.timezone, profile.tz, profile.timezone);\n\n return {\n locale: firstString(user.locale, profile.locale),\n localTime: timeZone ? formatLocalTime(timeZone) : undefined,\n timeZone,\n timeZoneLabel: firstString(user.tz_label, user.tzLabel),\n timeZoneOffsetSeconds: firstNumber(user.tz_offset, user.tzOffset),\n userId: firstString(user.id) ?? fallbackUserId,\n };\n}\n\nfunction messageTextWithFiles(message: JsonObject): string {\n const text = firstString(message.text) ?? '';\n const files = Array.isArray(message.files) ? message.files : [];\n const fileSummaries = files.flatMap((rawFile): string[] => {\n const file = jsonObject(rawFile);\n if (!file) return [];\n const title = firstString(file.title, file.name) ?? 'file';\n const url = firstString(file.permalink, file.url_private, file.urlPrivate);\n return [url ? `[file: ${title} ${url}]` : `[file: ${title}]`];\n });\n\n return [text, ...fileSummaries].filter(Boolean).join('\\n');\n}\n\nfunction firstNumber(...values: unknown[]): number | undefined {\n for (const value of values) {\n if (typeof value === 'number' && Number.isFinite(value)) return value;\n if (typeof value !== 'string' || !value.trim()) continue;\n const parsed = Number(value);\n if (Number.isFinite(parsed)) return parsed;\n }\n return undefined;\n}\n\nfunction withFreshLocalTime(context: SlackUserContext): SlackUserContext {\n return {\n ...context,\n localTime: context.timeZone ? formatLocalTime(context.timeZone) : undefined,\n };\n}\n\nfunction formatLocalTime(timeZone: string): string | undefined {\n try {\n return new Intl.DateTimeFormat('en-US', {\n dateStyle: 'full',\n timeStyle: 'long',\n timeZone,\n }).format(new Date());\n } catch {\n return undefined;\n }\n}\n\nfunction connectedAccountIdForEvent(config: AppConfig, store: Store, event?: NormalizedSlackTriggerEvent): string {\n const id =\n config.slackbotSharedConnectedAccountId ??\n event?.connectedAccountId ??\n (event?.teamId ? store.getSlackbotConnection(event.teamId)?.connectedAccountId : undefined);\n if (!id) {\n throw new Error(\n 'Missing Slackbot transport connected account. Open /setup/slackbot/start to install Slackbot or set SLACKBOT_SHARED_CONNECTED_ACCOUNT_ID.',\n );\n }\n return id;\n}\n\nfunction transportUserIdForEvent(config: AppConfig, event?: NormalizedSlackTriggerEvent): string {\n if (config.slackbotTransportUserId) return config.slackbotTransportUserId;\n if (!event?.teamId || event.teamId === 'unknown-team') {\n throw new Error('Missing Slack team id; cannot derive Slackbot transport user id service:${teamId}.');\n }\n return `service:${event.teamId}`;\n}\n\nfunction stripUndefined(value: Record<string, JsonValue | undefined>): JsonObject {\n return Object.fromEntries(Object.entries(value).filter(([, nested]) => nested !== undefined)) as JsonObject;\n}\n\nfunction queryParameters(value: Record<string, string | number | undefined>): Array<{ in: 'query'; name: string; value: string | number }> {\n return Object.entries(value).flatMap(([name, nested]) => (nested === undefined ? [] : [{ in: 'query' as const, name, value: nested }]));\n}\n\nfunction summarizeError(error: Error | unknown): string {\n if (error instanceof Error) return error.message;\n return String(error);\n}\n"
36 },
37 {
38 "path": "src/slack/acl.ts",
docs/lib/standup-bot-build.ts
+4 -4
@@ -24,7 +24,7 @@ const AUTH_CONFIG = process.env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID!;
24
25 // Connect the bot's own Slack app once, so it can post and DM as the bot.
26 async function main() {
27 - const session = await composio.create('default', {
27 + const session = await composio.sessions.create('default', {
28 authConfigs: { slackbot: AUTH_CONFIG },
29 });
30
@@ -46,7 +46,7 @@ const AUTH_CONFIG = process.env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID!;
46
47 // Connect the bot's own Slack app once, so it can post and DM as the bot.
48 async function main() {
49 - const session = await composio.create('default', {
49 + const session = await composio.sessions.create('default', {
50 authConfigs: { slackbot: AUTH_CONFIG },
51 });
52
@@ -152,7 +152,7 @@ const TOOLKITS = ['github', 'linear', 'notion', 'googlecalendar', 'slack'];
152 // write their standup. session.tools() returns Composio's research meta-tools
153 // (search / execute / workbench), scoped to those toolkits.
154 export async function generateDraft(memberEmail: string) {
155 - const session = await composio.create(memberEmail, { toolkits: TOOLKITS });
155 + const session = await composio.sessions.create(memberEmail, { toolkits: TOOLKITS });
156 const tools = await session.tools();
157
158 const { text } = await generateText({
@@ -186,7 +186,7 @@ export async function generateDraft(memberEmail: string) {
186 // manageConnections:false strips the connection meta-tools. The agent drafts
187 // from whatever the member already connected and never starts an OAuth flow
188 // mid-draft: if a tool needs auth, it's simply not in the session.
189 - const session = await composio.create(memberEmail, {
189 + const session = await composio.sessions.create(memberEmail, {
190 toolkits: TOOLKITS,
191 manageConnections: false,
192 });
docs/lib/standup-bot-source.json
+2 -2
@@ -26,7 +26,7 @@
26 },
27 {
28 "path": "api/_utils/composio.ts",
29 - "contents": "import { Composio } from \"@composio/core\";\nimport { VercelProvider } from \"@composio/vercel\";\nimport { TOOLKIT_SLUGS } from \"../../standup.config\";\nimport { env } from \"./env\";\n\nexport const composio = new Composio({\n apiKey: env.COMPOSIO_API_KEY,\n provider: new VercelProvider(),\n});\n\n// The bot's own Composio user. The slackbot OAuth connection lives here, so all\n// bot Slack actions (posting to the channel, DMing members) execute as the bot.\nexport const BOT_USER = \"default\";\n\n/** Active connected accounts for a user, optionally filtered to one toolkit.\n * Filters server-side via `statuses` so we never see stale/expired ones. */\nexport async function listActiveAccounts(userId: string, toolkitSlug?: string) {\n const res = await composio.connectedAccounts.list({\n userIds: [userId],\n statuses: [\"ACTIVE\"],\n ...(toolkitSlug ? { toolkitSlugs: [toolkitSlug] } : {}),\n });\n return res.items;\n}\n\n// The bot's slackbot connected-account ID. proxyExecute needs it so the call\n// authenticates as the bot (the project has several connections, so we can't\n// rely on a default-account fallback). Resolved once and memoized.\nlet botAccountIdPromise: Promise<string | undefined> | undefined;\nfunction getBotAccountId(): Promise<string | undefined> {\n botAccountIdPromise ??= listActiveAccounts(BOT_USER, \"slackbot\")\n .then((accounts) => accounts[0]?.id)\n .then((id) => {\n // Don't cache a miss: if the bot isn't connected yet, retry next call so a\n // later setup/OAuth is picked up without waiting for a cold start.\n if (!id) botAccountIdPromise = undefined;\n return id;\n });\n return botAccountIdPromise;\n}\n\n// Wraps Composio's proxyExecute to call any Slack Web API endpoint as the bot\n// (or a member, via accountId). Covers what the named SLACKBOT_* tools don't,\n// like views.open for modals.\nexport async function slackApi<T = unknown>(\n endpoint: string,\n method: \"GET\" | \"POST\",\n body?: Record<string, unknown>,\n accountId?: string // override the bot account (e.g. post as a member)\n): Promise<T> {\n const connectedAccountId = accountId ?? (await getBotAccountId());\n const res = await composio.tools.proxyExecute({\n endpoint,\n method,\n ...(body ? { body } : {}),\n ...(connectedAccountId ? { connectedAccountId } : {}),\n });\n // proxyExecute wraps Slack's JSON response in `data`.\n return ((res as { data?: unknown }).data ?? res) as T;\n}\n\n/** Run a named Composio tool as a user (the bot by default). This is the normal\n * path for actions a SLACKBOT or SLACK tool covers (sending a message, even\n * one with Block Kit buttons, updating one, posting as a member). Returns the\n * tool's `data`, which is the Slack API response. */\nexport async function slackTool<T = Record<string, unknown>>(\n slug: string,\n args: Record<string, unknown>,\n userId: string = BOT_USER\n): Promise<T> {\n const res = await composio.tools.execute(slug, { userId, arguments: args });\n return (res.data ?? {}) as T;\n}\n\n/** Which catalogue toolkits the member has actively connected. */\nexport async function getConnectedIntegrations(\n memberEmail: string\n): Promise<string[]> {\n const active = await listActiveAccounts(memberEmail);\n const slugs = new Set(active.map((a) => a.toolkit.slug));\n return TOOLKIT_SLUGS.filter((s) => slugs.has(s));\n}\n\n/** Generate an OAuth connect link for one toolkit, for one member. */\nexport async function getConnectLink(\n memberEmail: string,\n toolkitSlug: string\n): Promise<string | null> {\n try {\n const conn = await composio.toolkits.authorize(memberEmail, toolkitSlug);\n return conn.redirectUrl ?? null;\n } catch {\n return null;\n }\n}\n\n/**\n * A tool-router session scoped to the given toolkits. `session.tools()` returns\n * Composio's research meta-tools (search/execute/workbench) limited to these\n * toolkits. `manageConnections: false` strips the connection meta-tools so the\n * draft agent can research but never initiate an OAuth flow mid-draft.\n */\nexport async function createToolRouterSession(\n memberEmail: string,\n toolkitSlugs: string[]\n) {\n return composio.create(memberEmail, {\n toolkits: toolkitSlugs,\n manageConnections: false,\n });\n}\n",
29 + "contents": "import { Composio } from \"@composio/core\";\nimport { VercelProvider } from \"@composio/vercel\";\nimport { TOOLKIT_SLUGS } from \"../../standup.config\";\nimport { env } from \"./env\";\n\nexport const composio = new Composio({\n apiKey: env.COMPOSIO_API_KEY,\n provider: new VercelProvider(),\n});\n\n// The bot's own Composio user. The slackbot OAuth connection lives here, so all\n// bot Slack actions (posting to the channel, DMing members) execute as the bot.\nexport const BOT_USER = \"default\";\n\n/** Active connected accounts for a user, optionally filtered to one toolkit.\n * Filters server-side via `statuses` so we never see stale/expired ones. */\nexport async function listActiveAccounts(userId: string, toolkitSlug?: string) {\n const res = await composio.connectedAccounts.list({\n userIds: [userId],\n statuses: [\"ACTIVE\"],\n ...(toolkitSlug ? { toolkitSlugs: [toolkitSlug] } : {}),\n });\n return res.items;\n}\n\n// The bot's slackbot connected-account ID. proxyExecute needs it so the call\n// authenticates as the bot (the project has several connections, so we can't\n// rely on a default-account fallback). Resolved once and memoized.\nlet botAccountIdPromise: Promise<string | undefined> | undefined;\nfunction getBotAccountId(): Promise<string | undefined> {\n botAccountIdPromise ??= listActiveAccounts(BOT_USER, \"slackbot\")\n .then((accounts) => accounts[0]?.id)\n .then((id) => {\n // Don't cache a miss: if the bot isn't connected yet, retry next call so a\n // later setup/OAuth is picked up without waiting for a cold start.\n if (!id) botAccountIdPromise = undefined;\n return id;\n });\n return botAccountIdPromise;\n}\n\n// Wraps Composio's proxyExecute to call any Slack Web API endpoint as the bot\n// (or a member, via accountId). Covers what the named SLACKBOT_* tools don't,\n// like views.open for modals.\nexport async function slackApi<T = unknown>(\n endpoint: string,\n method: \"GET\" | \"POST\",\n body?: Record<string, unknown>,\n accountId?: string // override the bot account (e.g. post as a member)\n): Promise<T> {\n const connectedAccountId = accountId ?? (await getBotAccountId());\n const res = await composio.tools.proxyExecute({\n endpoint,\n method,\n ...(body ? { body } : {}),\n ...(connectedAccountId ? { connectedAccountId } : {}),\n });\n // proxyExecute wraps Slack's JSON response in `data`.\n return ((res as { data?: unknown }).data ?? res) as T;\n}\n\n/** Run a named Composio tool as a user (the bot by default). This is the normal\n * path for actions a SLACKBOT or SLACK tool covers (sending a message, even\n * one with Block Kit buttons, updating one, posting as a member). Returns the\n * tool's `data`, which is the Slack API response. */\nexport async function slackTool<T = Record<string, unknown>>(\n slug: string,\n args: Record<string, unknown>,\n userId: string = BOT_USER\n): Promise<T> {\n const res = await composio.tools.execute(slug, { userId, arguments: args });\n return (res.data ?? {}) as T;\n}\n\n/** Which catalogue toolkits the member has actively connected. */\nexport async function getConnectedIntegrations(\n memberEmail: string\n): Promise<string[]> {\n const active = await listActiveAccounts(memberEmail);\n const slugs = new Set(active.map((a) => a.toolkit.slug));\n return TOOLKIT_SLUGS.filter((s) => slugs.has(s));\n}\n\n/** Generate an OAuth connect link for one toolkit, for one member. */\nexport async function getConnectLink(\n memberEmail: string,\n toolkitSlug: string\n): Promise<string | null> {\n try {\n const conn = await composio.toolkits.authorize(memberEmail, toolkitSlug);\n return conn.redirectUrl ?? null;\n } catch {\n return null;\n }\n}\n\n/**\n * A tool-router session scoped to the given toolkits. `session.tools()` returns\n * Composio's research meta-tools (search/execute/workbench) limited to these\n * toolkits. `manageConnections: false` strips the connection meta-tools so the\n * draft agent can research but never initiate an OAuth flow mid-draft.\n */\nexport async function createToolRouterSession(\n memberEmail: string,\n toolkitSlugs: string[]\n) {\n return composio.sessions.create(memberEmail, {\n toolkits: toolkitSlugs,\n manageConnections: false,\n });\n}\n",
30 "composio": true
31 },
32 {
@@ -46,7 +46,7 @@
46 },
47 {
48 "path": "scripts/setup.ts",
49 - "contents": "import { Composio } from \"@composio/core\";\nimport { env } from \"../api/_utils/env\";\n\n// One-time setup: connect the bot's Slack (\"slackbot\") account so it can post to\n// the channel and DM members. Run with `npx tsx scripts/setup.ts`, or\n// `--reconnect` to clear and re-do the OAuth (needed after changing Slack scopes).\nconst COMPOSIO_BASE_URL = \"https://backend.composio.dev\";\nconst TOOLKIT_SLUG = \"slackbot\";\n\n// Scopes the bot's OAuth *user* token must carry. Composio freezes the scopes at\n// connect time, so we check them before connecting and tell the user what to add.\nconst REQUIRED_USER_SCOPES = [\"team:read\"];\n\nconst log = {\n ok: (msg: string) => console.log(` ✅ ${msg}`),\n info: (msg: string) => console.log(` · ${msg}`),\n warn: (msg: string) => console.log(` ⚠️ ${msg}`),\n};\n\nfunction errMessage(err: unknown): string {\n if (err && typeof err === \"object\") {\n const e = err as {\n error?: { error?: { message?: string }; message?: string };\n message?: string;\n };\n return e.error?.error?.message ?? e.error?.message ?? e.message ?? String(err);\n }\n return String(err);\n}\n\nasync function main() {\n const RECONNECT = process.argv.includes(\"--reconnect\");\n\n console.log(\"\\n╭─────────────────────────────────────────────────────────╮\");\n console.log(\"│ Daily Standup Bot: One-Time Setup │\");\n console.log(\"╰─────────────────────────────────────────────────────────╯\");\n if (RECONNECT) {\n console.log(\" (--reconnect: will clear and re-do the bot's Slack auth)\");\n }\n\n const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });\n const authConfigId = env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID;\n\n // Check the auth config requests the scopes the bot needs.\n // READ-ONLY on purpose. GET returns secrets MASKED, and a PATCH that echoes\n // those masked values back overwrites the real client_secret with the mask.\n // So we never write credentials here; we only check and warn.\n const cfgRes = await fetch(`${COMPOSIO_BASE_URL}/api/v3/auth_configs/${authConfigId}`, {\n headers: { \"x-api-key\": env.COMPOSIO_API_KEY },\n });\n if (cfgRes.ok) {\n const cfg = (await cfgRes.json().catch(() => ({}))) as {\n credentials?: { user_scopes?: string[] };\n };\n const userScopes = cfg.credentials?.user_scopes ?? [];\n const missing = REQUIRED_USER_SCOPES.filter((s) => !userScopes.includes(s));\n if (missing.length > 0) {\n log.warn(`Auth config is missing required user scope(s): ${missing.join(\", \")}`);\n console.log(\n \" Add them under the auth config's User Token Scopes in the Composio\\n\" +\n \" dashboard (Auth Configs → slackbot), then re-run with --reconnect.\"\n );\n } else {\n log.ok(\"Auth config has the required user scopes.\");\n }\n }\n\n // Ensure the bot's Slack connection is active.\n const session = await composio.create(\"default\", {\n authConfigs: { slackbot: authConfigId },\n });\n\n async function listSlackbotAccounts() {\n try {\n const res = await composio.connectedAccounts.list({\n userIds: [\"default\"],\n toolkitSlugs: [TOOLKIT_SLUG],\n });\n return res.items;\n } catch {\n return [];\n }\n }\n\n if (RECONNECT) {\n const accounts = await listSlackbotAccounts();\n if (accounts.length === 0) {\n log.info(\"No existing connections to clear.\");\n } else {\n for (const acc of accounts) {\n try {\n await composio.connectedAccounts.delete(acc.id);\n log.ok(`Removed old connection ${acc.id}.`);\n } catch (err) {\n log.warn(`Could not remove ${acc.id}: ${errMessage(err)}`);\n }\n }\n }\n }\n\n let connected = false;\n if (!RECONNECT) {\n const toolkits = await session.toolkits({ toolkits: [TOOLKIT_SLUG] });\n connected = !!toolkits.items.find((t) => t.slug === TOOLKIT_SLUG)?.connection\n ?.isActive;\n }\n\n if (connected) {\n log.ok(\"Bot is already connected to Slack.\");\n } else {\n log.info(\"Bot is not connected yet. Generating an authorization link…\");\n // Manual authentication: authorize() returns a Connect Link, then\n // waitForConnection() resolves once the bot finishes OAuth in the browser.\n // https://docs.composio.dev/docs/manually-authenticating\n const connectionRequest = await session.authorize(TOOLKIT_SLUG);\n if (!connectionRequest.redirectUrl) {\n throw new Error(\"Composio did not return an authorization link.\");\n }\n\n console.log(\"\\n Open this URL in your browser to authorize the bot:\\n\");\n console.log(` ${connectionRequest.redirectUrl}\\n`);\n console.log(\" Waiting for you to complete the OAuth flow (Ctrl+C to abort)…\");\n\n const TIMEOUT_MS = 5 * 60 * 1000;\n const account = await connectionRequest.waitForConnection(TIMEOUT_MS);\n log.ok(`Bot connected to Slack (${account.id}).`);\n }\n\n console.log(`\\n${\"─\".repeat(70)}`);\n console.log(\" 🎉 Setup complete. Invite the bot to your standup channel and\");\n console.log(\" point your Slack app's Interactivity Request URL at\");\n console.log(\" https://<your-deployment>/api/interactivity\");\n console.log(`${\"─\".repeat(70)}\\n`);\n}\n\nmain().catch((err) => {\n console.error(`\\n ❌ ${errMessage(err)}\\n`);\n process.exit(1);\n});\n",
49 + "contents": "import { Composio } from \"@composio/core\";\nimport { env } from \"../api/_utils/env\";\n\n// One-time setup: connect the bot's Slack (\"slackbot\") account so it can post to\n// the channel and DM members. Run with `npx tsx scripts/setup.ts`, or\n// `--reconnect` to clear and re-do the OAuth (needed after changing Slack scopes).\nconst COMPOSIO_BASE_URL = \"https://backend.composio.dev\";\nconst TOOLKIT_SLUG = \"slackbot\";\n\n// Scopes the bot's OAuth *user* token must carry. Composio freezes the scopes at\n// connect time, so we check them before connecting and tell the user what to add.\nconst REQUIRED_USER_SCOPES = [\"team:read\"];\n\nconst log = {\n ok: (msg: string) => console.log(` ✅ ${msg}`),\n info: (msg: string) => console.log(` · ${msg}`),\n warn: (msg: string) => console.log(` ⚠️ ${msg}`),\n};\n\nfunction errMessage(err: unknown): string {\n if (err && typeof err === \"object\") {\n const e = err as {\n error?: { error?: { message?: string }; message?: string };\n message?: string;\n };\n return e.error?.error?.message ?? e.error?.message ?? e.message ?? String(err);\n }\n return String(err);\n}\n\nasync function main() {\n const RECONNECT = process.argv.includes(\"--reconnect\");\n\n console.log(\"\\n╭─────────────────────────────────────────────────────────╮\");\n console.log(\"│ Daily Standup Bot: One-Time Setup │\");\n console.log(\"╰─────────────────────────────────────────────────────────╯\");\n if (RECONNECT) {\n console.log(\" (--reconnect: will clear and re-do the bot's Slack auth)\");\n }\n\n const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });\n const authConfigId = env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID;\n\n // Check the auth config requests the scopes the bot needs.\n // READ-ONLY on purpose. GET returns secrets MASKED, and a PATCH that echoes\n // those masked values back overwrites the real client_secret with the mask.\n // So we never write credentials here; we only check and warn.\n const cfgRes = await fetch(`${COMPOSIO_BASE_URL}/api/v3/auth_configs/${authConfigId}`, {\n headers: { \"x-api-key\": env.COMPOSIO_API_KEY },\n });\n if (cfgRes.ok) {\n const cfg = (await cfgRes.json().catch(() => ({}))) as {\n credentials?: { user_scopes?: string[] };\n };\n const userScopes = cfg.credentials?.user_scopes ?? [];\n const missing = REQUIRED_USER_SCOPES.filter((s) => !userScopes.includes(s));\n if (missing.length > 0) {\n log.warn(`Auth config is missing required user scope(s): ${missing.join(\", \")}`);\n console.log(\n \" Add them under the auth config's User Token Scopes in the Composio\\n\" +\n \" dashboard (Auth Configs → slackbot), then re-run with --reconnect.\"\n );\n } else {\n log.ok(\"Auth config has the required user scopes.\");\n }\n }\n\n // Ensure the bot's Slack connection is active.\n const session = await composio.sessions.create(\"default\", {\n authConfigs: { slackbot: authConfigId },\n });\n\n async function listSlackbotAccounts() {\n try {\n const res = await composio.connectedAccounts.list({\n userIds: [\"default\"],\n toolkitSlugs: [TOOLKIT_SLUG],\n });\n return res.items;\n } catch {\n return [];\n }\n }\n\n if (RECONNECT) {\n const accounts = await listSlackbotAccounts();\n if (accounts.length === 0) {\n log.info(\"No existing connections to clear.\");\n } else {\n for (const acc of accounts) {\n try {\n await composio.connectedAccounts.delete(acc.id);\n log.ok(`Removed old connection ${acc.id}.`);\n } catch (err) {\n log.warn(`Could not remove ${acc.id}: ${errMessage(err)}`);\n }\n }\n }\n }\n\n let connected = false;\n if (!RECONNECT) {\n const toolkits = await session.toolkits({ toolkits: [TOOLKIT_SLUG] });\n connected = !!toolkits.items.find((t) => t.slug === TOOLKIT_SLUG)?.connection\n ?.isActive;\n }\n\n if (connected) {\n log.ok(\"Bot is already connected to Slack.\");\n } else {\n log.info(\"Bot is not connected yet. Generating an authorization link…\");\n // Manual authentication: authorize() returns a Connect Link, then\n // waitForConnection() resolves once the bot finishes OAuth in the browser.\n // https://docs.composio.dev/docs/manually-authenticating\n const connectionRequest = await session.authorize(TOOLKIT_SLUG);\n if (!connectionRequest.redirectUrl) {\n throw new Error(\"Composio did not return an authorization link.\");\n }\n\n console.log(\"\\n Open this URL in your browser to authorize the bot:\\n\");\n console.log(` ${connectionRequest.redirectUrl}\\n`);\n console.log(\" Waiting for you to complete the OAuth flow (Ctrl+C to abort)…\");\n\n const TIMEOUT_MS = 5 * 60 * 1000;\n const account = await connectionRequest.waitForConnection(TIMEOUT_MS);\n log.ok(`Bot connected to Slack (${account.id}).`);\n }\n\n console.log(`\\n${\"─\".repeat(70)}`);\n console.log(\" 🎉 Setup complete. Invite the bot to your standup channel and\");\n console.log(\" point your Slack app's Interactivity Request URL at\");\n console.log(\" https://<your-deployment>/api/interactivity\");\n console.log(`${\"─\".repeat(70)}\\n`);\n}\n\nmain().catch((err) => {\n console.error(`\\n ❌ ${errMessage(err)}\\n`);\n process.exit(1);\n});\n",
50 "composio": true
51 }
52 ]
ts/README.md
+1 -1
@@ -13,7 +13,7 @@ import { Composio } from '@composio/core';
13
14 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
15
16 -const session = await composio.create('user_123');
16 +const session = await composio.sessions.create('user_123');
17 const tools = await session.tools();
18 ```
19
ts/docs/advanced/modifiers.md
+1 -1
@@ -575,7 +575,7 @@ import { SessionExecuteMetaModifiers } from '@composio/core';
575
576 const composio = new Composio();
577
578 -const session = await composio.create('user_123', {
578 +const session = await composio.sessions.create('user_123', {
579 toolkits: ['gmail', 'slack'],
580 });
581
ts/docs/api/tool-router-files.md
+1 -1
@@ -23,7 +23,7 @@ Files are stored in a virtual filesystem attached to the session. Tools executin
23 import { Composio } from '@composio/core';
24
25 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
26 -const session = await composio.create('default');
26 +const session = await composio.sessions.create('default');
27
28 // Upload a file
29 const file = await session.experimental.files.upload('/path/to/report.pdf');
ts/docs/api/tool-router.md
+30 -30
@@ -39,7 +39,7 @@ import { Composio } from '@composio/core';
39 const composio = new Composio();
40
41 // Create a session for a user with access to Gmail tools
42 -const session = await composio.create('user_123', {
42 +const session = await composio.sessions.create('user_123', {
43 toolkits: ['gmail'],
44 });
45
@@ -60,7 +60,7 @@ const composio = new Composio({
60 });
61
62 // Create a session for a user with access to Gmail tools
63 -const session = await composio.create('user_123', {
63 +const session = await composio.sessions.create('user_123', {
64 toolkits: ['gmail'],
65 });
66
@@ -72,7 +72,7 @@ const tools = await session.tools();
72
73 ### Basic Session Creation
74
75 -Use `composio.create()` to create a new Tool Router session:
75 +Use `composio.sessions.create()` to create a new Tool Router session:
76
77 ```typescript
78 import { Composio } from '@composio/core';
@@ -80,7 +80,7 @@ import { Composio } from '@composio/core';
80 const composio = new Composio();
81
82 // Create a session with Gmail access
83 -const session = await composio.create('user_123', {
83 +const session = await composio.sessions.create('user_123', {
84 toolkits: ['gmail'],
85 });
86
@@ -90,10 +90,10 @@ console.log('MCP URL:', session.mcp.url);
90
91 ### Using an Existing Session
92
93 -If you have an existing session ID, you can retrieve it using `composio.use()`:
93 +If you have an existing session ID, you can retrieve it using `composio.sessions.use()`:
94
95 ```typescript
96 -const session = await composio.use('existing_session_id');
96 +const session = await composio.sessions.use('existing_session_id');
97
98 // Access session properties
99 console.log(session.sessionId);
@@ -110,17 +110,17 @@ Specify which toolkits to enable or disable in the session.
110
111 ```typescript
112 // Simple array of toolkit slugs to enable
113 -const session = await composio.create('user_123', {
113 +const session = await composio.sessions.create('user_123', {
114 toolkits: ['gmail', 'slack', 'github'],
115 });
116
117 // Explicit enabled configuration
118 -const session = await composio.create('user_123', {
118 +const session = await composio.sessions.create('user_123', {
119 toolkits: { enable: ['gmail', 'slack'] },
120 });
121
122 // Disable specific toolkits (enable all others)
123 -const session = await composio.create('user_123', {
123 +const session = await composio.sessions.create('user_123', {
124 toolkits: { disable: ['calendar'] },
125 });
126 ```
@@ -130,7 +130,7 @@ const session = await composio.create('user_123', {
130 Fine-grained control over which tools are available within toolkits. Configure tools per toolkit using the toolkit slug as the key.
131
132 ```typescript
133 -const session = await composio.create('user_123', {
133 +const session = await composio.sessions.create('user_123', {
134 toolkits: ['gmail', 'slack'],
135 tools: {
136 // Configure tools per toolkit
@@ -150,7 +150,7 @@ const session = await composio.create('user_123', {
150 Global tags to filter tools by their behavior hints. Tags can be overridden per toolkit in the `tools` configuration.
151
152 ```typescript
153 -const session = await composio.create('user_123', {
153 +const session = await composio.sessions.create('user_123', {
154 toolkits: ['gmail', 'github'],
155 // Global tags applied to all toolkits
156 tags: ['readOnlyHint', 'idempotentHint'],
@@ -169,7 +169,7 @@ Available tags:
169 Map toolkits to specific authentication configurations:
170
171 ```typescript
172 -const session = await composio.create('user_123', {
172 +const session = await composio.sessions.create('user_123', {
173 toolkits: ['gmail', 'github'],
174 authConfigs: {
175 gmail: 'ac_gmail_work',
@@ -183,7 +183,7 @@ const session = await composio.create('user_123', {
183 Map toolkits to specific connected account IDs:
184
185 ```typescript
186 -const session = await composio.create('user_123', {
186 +const session = await composio.sessions.create('user_123', {
187 toolkits: ['gmail'],
188 connectedAccounts: {
189 gmail: 'ca_abc123',
@@ -197,13 +197,13 @@ Control how connections are managed within the session:
197
198 ```typescript
199 // Boolean: enable/disable automatic connection management
200 -const session = await composio.create('user_123', {
200 +const session = await composio.sessions.create('user_123', {
201 toolkits: ['gmail'],
202 manageConnections: true, // default
203 });
204
205 // Object: fine-grained control
206 -const session = await composio.create('user_123', {
206 +const session = await composio.sessions.create('user_123', {
207 toolkits: ['gmail'],
208 manageConnections: {
209 enable: true,
@@ -218,7 +218,7 @@ const session = await composio.create('user_123', {
218 The `waitForConnections` property (new in v0.4.0) allows the tool router session to wait for users to complete authentication before proceeding to the next step. When set to `true`, the session will block execution until all required connections are established.
219
220 ```typescript
221 -const session = await composio.create('user_123', {
221 +const session = await composio.sessions.create('user_123', {
222 toolkits: ['gmail', 'slack'],
223 manageConnections: {
224 enable: true,
@@ -234,7 +234,7 @@ Configure workbench behavior for tool execution:
234
235 ```typescript
236 // Disable workbench entirely — no code execution tools in the session
237 -const session = await composio.create('user_123', {
237 +const session = await composio.sessions.create('user_123', {
238 toolkits: ['gmail'],
239 workbench: {
240 enable: false
@@ -242,7 +242,7 @@ const session = await composio.create('user_123', {
242 });
243
244 // Fine-tune workbench settings
245 -const session2 = await composio.create('user_123', {
245 +const session2 = await composio.sessions.create('user_123', {
246 toolkits: ['gmail'],
247 workbench: {
248 enable: true, // default
@@ -265,7 +265,7 @@ Configure experimental features for the session. These features are not stable a
265 #### Assistive Prompt
266
267 ```typescript
268 -const session = await composio.create('user_123', {
268 +const session = await composio.sessions.create('user_123', {
269 toolkits: ['gmail'],
270 experimental: {
271 assistivePrompt: {
@@ -340,7 +340,7 @@ const devTools = experimental_createToolkit('DEV_TOOLS', {
340 **Creating a session with custom tools:**
341
342 ```typescript
343 -const session = await composio.create('user_123', {
343 +const session = await composio.sessions.create('user_123', {
344 toolkits: ['gmail'],
345 experimental: {
346 customTools: [grep, getImportant],
@@ -583,7 +583,7 @@ const composio = new Composio({
583 provider: new VercelProvider(),
584 });
585
586 -const session = await composio.create('user_123', {
586 +const session = await composio.sessions.create('user_123', {
587 toolkits: ['gmail'],
588 });
589
@@ -613,7 +613,7 @@ import { stepCountIs, streamText } from 'ai';
613
614 // No provider needed when using MCP
615 const composio = new Composio();
616 -const { mcp } = await composio.create('user_123', {
616 +const { mcp } = await composio.sessions.create('user_123', {
617 toolkits: ['gmail'],
618 manageConnections: true,
619 tools: {
@@ -670,7 +670,7 @@ const llm = new ChatOpenAI({
670 model: 'gpt-4o',
671 });
672
673 -const session = await composio.create('user_123', {
673 +const session = await composio.sessions.create('user_123', {
674 toolkits: ['gmail'],
675 });
676
@@ -709,7 +709,7 @@ import { Composio } from '@composio/core';
709 // No provider needed when using MCP
710 const composio = new Composio();
711
712 -const session = await composio.create('user_123', {
712 +const session = await composio.sessions.create('user_123', {
713 toolkits: ['gmail'],
714 });
715
@@ -752,7 +752,7 @@ import { Composio } from '@composio/core';
752 // No provider needed when using MCP
753 const composio = new Composio();
754
755 -const session = await composio.create('user_123', {
755 +const session = await composio.sessions.create('user_123', {
756 toolkits: ['gmail'],
757 });
758
@@ -786,7 +786,7 @@ When a user needs to connect a toolkit, use the `authorize()` method:
786 import { Composio } from '@composio/core';
787
788 const composio = new Composio();
789 -const session = await composio.create('user_123', {
789 +const session = await composio.sessions.create('user_123', {
790 toolkits: ['gmail'],
791 });
792
@@ -817,7 +817,7 @@ Use the `toolkits()` method to check connection states:
817 import { Composio } from '@composio/core';
818
819 const composio = new Composio();
820 -const session = await composio.create('user_123');
820 +const session = await composio.sessions.create('user_123');
821
822 // Get all toolkits
823 const toolkits = await session.toolkits();
@@ -910,13 +910,13 @@ These types include the `sessionId` in their parameters, allowing you to track a
910
911 ```typescript
912 // Store session ID after creation
913 -const session = await composio.create('user_123', config);
913 +const session = await composio.sessions.create('user_123', config);
914 await redis.set(`session:user_123`, session.sessionId);
915
916 // Retrieve existing session
917 const sessionId = await redis.get(`session:user_123`);
918 if (sessionId) {
919 - const session = await composio.use(sessionId);
919 + const session = await composio.sessions.use(sessionId);
920 }
921 ```
922
@@ -1046,7 +1046,7 @@ interface SessionExecuteMetaModifiers {
1046 The new `waitForConnections` property allows sessions to wait for users to complete authentication before proceeding:
1047
1048 ```typescript
1049 -const session = await composio.create('user_123', {
1049 +const session = await composio.sessions.create('user_123', {
1050 toolkits: ['gmail', 'slack'],
1051 manageConnections: {
1052 enable: true,
ts/docs/core-concepts.md
+2 -2
@@ -402,7 +402,7 @@ Use direct execution when:
402
403 ## Custom Tools
404
405 -Custom Tools allow you to attach your own local tools to Tool Router sessions. Define them with `experimental_createTool`, then pass them to `composio.create()` under `experimental.customTools`.
405 +Custom Tools allow you to attach your own local tools to Tool Router sessions. Define them with `experimental_createTool`, then pass them to `composio.sessions.create()` under `experimental.customTools`.
406
407 ```typescript
408 import { Composio, experimental_createTool } from '@composio/core';
@@ -422,7 +422,7 @@ const customTool = experimental_createTool('MY_CUSTOM_TOOL', {
422 },
423 });
424
425 -const session = await composio.create('default', {
425 +const session = await composio.sessions.create('default', {
426 experimental: { customTools: [customTool] },
427 });
428
ts/docs/getting-started.md
+1 -1
@@ -305,7 +305,7 @@ const customTool = experimental_createTool('WEATHER_FORECAST', {
305 },
306 });
307
308 -const session = await composio.create('default', {
308 +const session = await composio.sessions.create('default', {
309 experimental: { customTools: [customTool] },
310 });
311
ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/src/index.ts
+2 -2
@@ -55,7 +55,7 @@ app.get('/test/mcp-client', async c => {
55 provider: new VercelProvider(),
56 });
57
58 - const session = await composio.create('default', {
58 + const session = await composio.sessions.create('default', {
59 toolkits: ['hackernews'],
60 manageConnections: true,
61 tools: {
@@ -98,7 +98,7 @@ app.get('/test/agent', async c => {
98 provider: new VercelProvider(),
99 });
100
101 - const session = await composio.create('default', {
101 + const session = await composio.sessions.create('default', {
102 toolkits: ['hackernews'],
103 manageConnections: true,
104 preload: { tools: ['HACKERNEWS_GET_USER'] },
ts/e2e-tests/runtimes/node/custom-tools/fixtures/index.mjs
+1 -1
@@ -91,7 +91,7 @@ const composio = new Composio({ apiKey });
91 async function main() {
92 const userId = `e2e-custom-tools-${Date.now()}`;
93
94 - const session = await composio.create(userId, {
94 + const session = await composio.sessions.create(userId, {
95 toolkits: ['weathermap'],
96 manageConnections: false,
97 experimental: {
ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/e2e.test.ts
+1 -1
@@ -42,7 +42,7 @@ e2e(import.meta.url, {
42 it(
43 'should work with Tool Router',
44 async () => {
45 - const session = await composio.create('default', {
45 + const session = await composio.sessions.create('default', {
46 toolkits: ['hackernews'],
47 mcp: true,
48 manageConnections: true,
ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/e2e.test.ts
+1 -1
@@ -42,7 +42,7 @@ e2e(import.meta.url, {
42 it(
43 'should work with Tool Router',
44 async () => {
45 - const session = await composio.create('default', {
45 + const session = await composio.sessions.create('default', {
46 toolkits: ['hackernews'],
47 mcp: true,
48 manageConnections: true,
ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjs
+1 -1
@@ -19,7 +19,7 @@ function isStorageUploadUnavailable(err) {
19
20 async function main() {
21 // Create a session (hackernews is public, no auth needed; files mount is always available)
22 - const session = await composio.create('e2e-tool-router-files-user', {
22 + const session = await composio.sessions.create('e2e-tool-router-files-user', {
23 toolkits: ['hackernews'],
24 manageConnections: false,
25 });
ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs
+1 -1
@@ -21,7 +21,7 @@ const composio = new Composio({ apiKey });
21
22 async function main() {
23 const userId = `e2e-tool-router-pagination-${Date.now()}`;
24 - const session = await composio.create(userId);
24 + const session = await composio.sessions.create(userId);
25
26 const page1 = await session.toolkits({ limit: 2 });
27 if (page1.items.length !== 2) {
ts/examples/tool-router/src/authorize.ts
+1 -1
@@ -1,7 +1,7 @@
1 import { Composio } from '@composio/core';
2
3 const composio = new Composio();
4 -const session = await composio.create('user_123', { toolkits: ['gmail'] });
4 +const session = await composio.sessions.create('user_123', { toolkits: ['gmail'] });
5 const connectionRequest = await session.authorize("gmail", {
6 callbackUrl: "https://google.com"
7 });
ts/examples/tool-router/src/claude-agent-sdk.ts
+1 -1
@@ -4,7 +4,7 @@ import 'dotenv/config';
4
5 const composio = new Composio();
6
7 -const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true });
7 +const session = await composio.sessions.create('user_123', { toolkits: ['gmail'], mcp: true });
8
9 const stream = await query({
10 prompt: 'Use composio tools to fetch my last email from gmail',
ts/examples/tool-router/src/custom-tools-agent.ts
+2 -2
@@ -175,8 +175,8 @@ const composio = new Composio({
175
176 const existingSessionId = process.env.COMPOSIO_SESSION_ID;
177 const session = existingSessionId
178 - ? await composio.use(existingSessionId, { customTools, customToolkits })
179 - : await composio.create("custom-tools-agent-user", {
178 + ? await composio.sessions.use(existingSessionId, { customTools, customToolkits })
179 + : await composio.sessions.create("custom-tools-agent-user", {
180 toolkits: ["weathermap", "gmail"],
181 manageConnections: false,
182 experimental: {
ts/examples/tool-router/src/custom-tools-e2e.ts
+3 -3
@@ -154,9 +154,9 @@ async function main() {
154 console.log(`Base URL: ${baseURL ?? "(default)"}\n`);
155
156 // ── Session creation with all 3 tool types ──
157 - let session: Awaited<ReturnType<typeof composio.create>>;
157 + let session: Awaited<ReturnType<typeof composio.sessions.create>>;
158 try {
159 - session = await composio.create(userId, {
159 + session = await composio.sessions.create(userId, {
160 toolkits: ["weathermap", "gmail"],
161 manageConnections: false,
162 experimental: {
@@ -173,7 +173,7 @@ async function main() {
173
174 // ── Existing session reuse with local custom definitions ──
175 try {
176 - const reusedSession = await composio.use(session.sessionId, { customTools, customToolkits });
176 + const reusedSession = await composio.sessions.use(session.sessionId, { customTools, customToolkits });
177 const result = await reusedSession.execute("GET_USER_DETAILS", { user_id: "user-1" });
178 if (result.data?.name !== "Alice Johnson") throw new Error(`Unexpected: ${JSON.stringify(result.data)}`);
179 ok("Use: existing session binds custom tools for local execution");
ts/examples/tool-router/src/custom-tools.ts
+1 -1
@@ -89,7 +89,7 @@ const composio = new Composio({
89 provider: new OpenAIAgentsProvider(),
90 });
91
92 -const session = await composio.create("default", {
92 +const session = await composio.sessions.create("default", {
93 toolkits: ["gmail"],
94 experimental: {
95 customTools: [getUser, createDraft],
ts/examples/tool-router/src/direct-tools-preset.ts
+1 -1
@@ -59,7 +59,7 @@ const hnResearch = experimental_createToolkit('HN_RESEARCH', {
59 tools: [getUserNote],
60 });
61
62 -const session = await composio.create('direct-tools-example-user', {
62 +const session = await composio.sessions.create('direct-tools-example-user', {
63 sessionPreset: SessionPreset.DIRECT_TOOLS,
64 toolkits: ['hackernews'],
65 tools: {
ts/examples/tool-router/src/index.ts
+1 -1
@@ -7,7 +7,7 @@ import { modifiers } from './logger';
7 const composio = new Composio({
8 provider: new VercelProvider(),
9 });
10 -const session = await composio.create('user_123', { toolkits: ['gmail'] });
10 +const session = await composio.sessions.create('user_123', { toolkits: ['gmail'] });
11
12
13 const tools = await session.tools(modifiers);
ts/examples/tool-router/src/langchain.ts
+1 -1
@@ -12,7 +12,7 @@ const llm = new ChatOpenAI({
12 });
13
14 async function main() {
15 - const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true });
15 + const session = await composio.sessions.create('user_123', { toolkits: ['gmail'], mcp: true });
16
17 const client = new MultiServerMCPClient({
18 math: {
ts/examples/tool-router/src/mcp.ts
+1 -1
@@ -6,7 +6,7 @@ import ora from 'ora';
6
7 const composio = new Composio();
8 const trProgress = ora('Creating tool router session...').start();
9 -const { mcp } = await composio.create('default', {
9 +const { mcp } = await composio.sessions.create('default', {
10 toolkits: ['gmail'],
11 manageConnections: true,
12 mcp: true,
ts/examples/tool-router/src/multi-account.ts
+1 -1
@@ -9,7 +9,7 @@ const composio = new Composio({
9
10 // Enable multi-account mode so the user can connect multiple accounts
11 // per toolkit (e.g. two Gmail accounts).
12 -const session = await composio.create('user_123', {
12 +const session = await composio.sessions.create('user_123', {
13 toolkits: ['gmail'],
14 multiAccount: {
15 enable: true,
ts/examples/tool-router/src/openai-agents.ts
+1 -1
@@ -3,7 +3,7 @@ import { Agent, hostedMcpTool, run } from '@openai/agents';
3 import { createInterface } from 'node:readline/promises';
4
5 const composio = new Composio();
6 -const { mcp } = await composio.create('default', { mcp: true });
6 +const { mcp } = await composio.sessions.create('default', { mcp: true });
7
8 const agent = new Agent({
9 name: 'Personal Assistant',
ts/examples/tool-router/src/preload.ts
+1 -1
@@ -112,7 +112,7 @@ const composio = new Composio({
112 provider: new OpenAIAgentsProvider(),
113 });
114
115 -const session = await composio.create('preload-example-user', {
115 +const session = await composio.sessions.create('preload-example-user', {
116 toolkits: ['hackernews'],
117 tools: {
118 hackernews: {
ts/examples/tool-router/src/session-update.ts
+1 -1
@@ -16,7 +16,7 @@ const composio = new Composio({
16 });
17
18 // Create a session with gmail only
19 -const session = await composio.create("session-update-demo", {
19 +const session = await composio.sessions.create("session-update-demo", {
20 toolkits: ["gmail"],
21 manageConnections: false,
22 });
ts/examples/tool-router/src/toolkits.ts
+1 -1
@@ -2,7 +2,7 @@ import { Composio } from '@composio/core';
2
3 const composio = new Composio();
4
5 -const session = await composio.create('user_123');
5 +const session = await composio.sessions.create('user_123');
6
7 const toolkits = await session.toolkits({ toolkits: ["github"]});
8
ts/examples/triggers/src/test.ts
+1 -1
@@ -4,7 +4,7 @@ const composio = new Composio({
4 apiKey: process.env.COMPOSIO_API_KEY,
5 });
6
7 -const session = await composio.create('userId', {
7 +const session = await composio.sessions.create('userId', {
8 experimental: {
9 assistivePrompt: {
10 userTimezone: 'America/New_York',
ts/examples/vercel/src/tool-router-ai.ts
+1 -1
@@ -11,7 +11,7 @@ const composio = new Composio({
11
12 // 2. Create an MCP session
13 console.log('🔄 Creating toolrouter session...');
14 -const session = await composio.create('default', {
14 +const session = await composio.sessions.create('default', {
15 toolkits: ['gmail'],
16 manageConnections: true,
17 mcp: true,
ts/packages/core/README.md
+4 -4
@@ -20,7 +20,7 @@ import { Composio } from '@composio/core';
20 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
21
22 // Each session is scoped to one of your users
23 -const session = await composio.create('user_123');
23 +const session = await composio.sessions.create('user_123');
24 const tools = await session.tools();
25 ```
26
@@ -29,7 +29,7 @@ By default a session gives your agent a small set of meta tools that discover, a
29 Sessions persist on the server. For multi-turn conversations, store `session.sessionId` and reuse it instead of calling `create()` again:
30
31 ```typescript
32 -const session = await composio.use(sessionId);
32 +const session = await composio.sessions.use(sessionId);
33 ```
34
35 See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.
@@ -44,7 +44,7 @@ import { OpenAIAgentsProvider } from '@composio/openai-agents';
44
45 const composio = new Composio({ provider: new OpenAIAgentsProvider() });
46
47 -const session = await composio.create('user_123');
47 +const session = await composio.sessions.create('user_123');
48 const tools = await session.tools(); // ready to pass to the OpenAI Agents SDK
49 ```
50
@@ -55,7 +55,7 @@ Adapters exist for OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel AI
55 Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to surface it in the type, then point Claude, Cursor, or any MCP client at it:
56
57 ```typescript
58 -const session = await composio.create('user_123', { mcp: true });
58 +const session = await composio.sessions.create('user_123', { mcp: true });
59
60 console.log(session.mcp.url);
61 console.log(session.mcp.headers);
ts/packages/core/src/composio.ts
+3 -59
@@ -15,7 +15,6 @@ import { checkForLatestVersionFromNPM } from './utils/version';
15 import { OpenAIProvider } from './provider/OpenAIProvider';
16 import { version } from '../package.json';
17 import type { ComposioRequestHeaders } from './types/composio.types';
18 -import type { ComposioRequestOptions } from './types/requestOptions.types';
18 import { Files } from '#files';
19 import { getDefaultHeaders } from './utils/session';
20 import { ToolkitVersionParam } from './types/tool.types';
@@ -207,7 +206,7 @@ export class Composio<
206 experimental: Experimental;
207 /**
208 * Model Context Protocol server management.
210 - * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`
209 + * @deprecated Use a session's MCP endpoint instead: `composio.sessions.create(userId, { mcp: true })`
210 * returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now opt-in
211 * per session; this standalone server-management API is kept only for backwards compatibility.
212 * Prefer the session MCP endpoint; do not generate new code against `composio.mcp`.
@@ -217,8 +216,8 @@ export class Composio<
216 /**
217 * Create and reuse Composio sessions.
218 *
220 - * Prefer `composio.sessions.create(...)` for new code. The top-level
221 - * `composio.create(...)` method is kept as an alias.
219 + * Use `composio.sessions.create(...)` to create a session and
220 + * `composio.sessions.use(...)` to reuse one.
221 */
222 sessions: Sessions<unknown, unknown, TProvider>;
223 /**
@@ -226,51 +225,6 @@ export class Composio<
225 * @deprecated Use `composio.sessions` instead — `toolRouter` was renamed to `sessions` and is kept only for backwards compatibility. Prefer `composio.sessions`; do not generate new code against `composio.toolRouter`.
226 */
227 toolRouter: ToolRouter<unknown, unknown, TProvider>;
229 - /**
230 - * Creates a new tool router session for a user.
231 - * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools
232 - * should be exposed directly; see `ToolRouterCreateSessionConfig`.
233 - *
234 - * @param userId {string} The user id to create the session for
235 - * @param config {ToolRouterConfig} The config for the tool router session
236 - * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
237 - *
238 - * @example
239 - * ```typescript
240 - * import { Composio } from '@composio/core';
241 - *
242 - * const composio = new Composio();
243 - * const userId = 'user_123';
244 - *
245 - * const session = await composio.sessions.create(userId, {
246 - * manageConnections: true,
247 - * });
248 - *
249 - * // Backwards-compatible alias:
250 - * const same = await composio.create(userId, {
251 - * manageConnections: true,
252 - * });
253 - *
254 - * console.log(session.sessionId);
255 - * console.log(session.url);
256 - * console.log(session.tools());
257 - * ```
258 - */
259 - create: Sessions<unknown, unknown, TProvider>['create'];
260 -
261 - /**
262 - * Use an existing tool router session
263 - *
264 - * @param id {string} The id of the session to use
265 - * @param options {object} Custom tools / toolkits to attach to the session
266 - * @param requestOptions {ComposioRequestOptions} Per-request cancellation
267 - * options. The supplied AbortSignal aborts the underlying session
268 - * retrieve/attach call only. Subsequent session method calls accept
269 - * their own per-call requestOptions.
270 - * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
271 - */
272 - use: Sessions<unknown, unknown, TProvider>['use'];
273 -
228 /**
229 * Creates a new instance of the Composio SDK.
230 *
@@ -364,16 +318,6 @@ export class Composio<
318 this.sessions = new Sessions(this.client, this.config);
319 this.toolRouter = this.sessions;
320
367 - /**
368 - * Initialize session aliases.
369 - * Properly bind the methods to maintain the correct 'this' context.
370 - */
371 - // Cast: Function.prototype.bind collapses the create/use overloads to a
372 - // single signature; re-assert the overloaded type. Runtime behaviour is
373 - // unchanged — bind only rebinds `this`.
374 - this.create = this.sessions.create.bind(this.sessions) as Composio<TProvider>['create'];
375 - this.use = this.sessions.use.bind(this.sessions) as Composio<TProvider>['use'];
376 -
321 /**
322 * Initialize the client telemetry.
323 */
ts/packages/core/src/models/CustomTool.ts
+2 -4
@@ -100,7 +100,7 @@ function validateSlugLength(
100 * Create a custom tool for use in tool router sessions.
101 *
102 * The returned object is a lightweight reference containing the tool's metadata
103 - * and execute function. Pass it to `composio.create(userId, { experimental: { customTools: [...] } })`
103 + * and execute function. Pass it to `composio.sessions.create(userId, { experimental: { customTools: [...] } })`
104 * to bind it to a session.
105 *
106 * Just return the result data from `execute`, or throw an error.
@@ -483,9 +483,7 @@ export function buildCustomToolsMapFromResponse(
483 tools: CustomTool[],
484 toolkits: CustomToolkit[] | undefined,
485 experimental:
486 - | SessionCreateResponse['experimental']
487 - | SessionRetrieveResponse['experimental']
488 - | undefined
486 + SessionCreateResponse['experimental'] | SessionRetrieveResponse['experimental'] | undefined
487 ): CustomToolsMap {
488 const byFinalSlug = new Map<string, CustomToolsMapEntry>();
489 const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
ts/packages/core/src/models/MCP.ts
+1 -1
@@ -45,7 +45,7 @@ function transformMCPItemResponse(response: McpUpdateResponse | McpRetrieveRespo
45 * Handles MCP server operations.
46 * When `config.experimental.mcp` is enabled, this class augments the features of `composio.mcp`.
47 *
48 - * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`
48 + * @deprecated Use a session's MCP endpoint instead: `composio.sessions.create(userId, { mcp: true })`
49 * returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now
50 * opt-in per session; the standalone `composio.mcp` server-management API is kept only for
51 * backwards compatibility. Prefer the session MCP endpoint; do not generate new code against
ts/packages/core/src/models/Sessions.ts
+2 -3
@@ -6,9 +6,8 @@ import { ToolRouter } from './ToolRouter';
6 /**
7 * First-class API for creating and reusing Composio sessions.
8 *
9 - * `composio.sessions.create(...)` is the canonical session creation entrypoint.
10 - * The top-level `composio.create(...)` method remains as a backwards-compatible
11 - * alias for `composio.sessions.create(...)`.
9 + * Use `composio.sessions.create(...)` to create a session and
10 + * `composio.sessions.use(...)` to reuse one.
11 */
12 export class Sessions<
13 TToolCollection,
ts/packages/core/src/models/ToolRouterSession.ts
+1 -2
@@ -94,8 +94,7 @@ const AuthorizeOptionsSchema = z.object({
94
95 /**
96 * A Composio session — the object returned by `composio.sessions.create(...)`
97 - * and `composio.sessions.use(...)` (also reachable via the top-level
98 - * `composio.create(...)` / `composio.use(...)` aliases).
97 + * and `composio.sessions.use(...)`.
98 *
99 * This is the canonical session surface. Use it to fetch session-scoped tools,
100 * authorize toolkits, search, and execute tools. The public return type is
ts/packages/core/src/provider/BaseProvider.ts
+7 -5
@@ -62,13 +62,15 @@ abstract class BaseProvider<TMcpResponse> {
62
63 /**
64 * @public
65 - * @deprecated: Will be removed in a future version, once the `experimental.mcp` flag is stabilized. Use `wrapMcpServers` instead.
66 - * Optional method to transform MCP URL response into provider-specific format.
67 - * Providers can override this method to define custom transformation logic
68 - * for MCP server responses.
65 + * Optional method to transform an MCP URL response into a provider-specific
66 + * format. Providers can override this method to define custom transformation
67 + * logic for MCP server responses.
68 + *
69 + * This is the stable base-provider SPI method for MCP responses in v1. (A
70 + * prior `@deprecated` note pointed at a plural `wrapMcpServers` method that
71 + * was never added; the singular method is the frozen contract.)
72 *
73 * @param data - The MCP URL response data
71 -
74 * @returns Transformed response in provider-specific format, or undefined to use default transformation
75 */
76 wrapMcpServerResponse?(data: McpUrlResponse): TMcpResponse;
ts/packages/core/src/types/customTool.types.ts
+2 -2
@@ -115,7 +115,7 @@ export type CreateCustomToolParams<T extends AnyZodSchema> = z.infer<
115
116 /**
117 * Custom tool definition returned from `createCustomTool()`.
118 - * Pass to `composio.create(userId, { experimental: { customTools: [...] } })` to bind to a session.
118 + * Pass to `composio.sessions.create(userId, { experimental: { customTools: [...] } })` to bind to a session.
119 */
120 export interface CustomTool {
121 readonly slug: string;
@@ -173,7 +173,7 @@ export type CreateCustomToolkitParams = z.infer<typeof CreateCustomToolkitBaseSc
173
174 /**
175 * Custom toolkit definition returned from `createCustomToolkit()`.
176 - * Pass to `composio.create(userId, { experimental: { customToolkits: [...] } })`.
176 + * Pass to `composio.sessions.create(userId, { experimental: { customToolkits: [...] } })`.
177 */
178 export interface CustomToolkit {
179 readonly slug: string;
ts/packages/core/test/core/session.test.ts
+5 -10
@@ -110,7 +110,7 @@ describe('Composio Session Management', () => {
110 });
111 });
112
113 - it('should expose sessions.create and keep composio.create as a bound alias', async () => {
113 + it('should expose sessions.create without bare root aliases', async () => {
114 const composio = new Composio(baseConfig);
115 const client = composio.getClient() as any;
116 client.toolRouter.session.create = vi.fn().mockResolvedValue({
@@ -127,21 +127,16 @@ describe('Composio Session Management', () => {
127
128 expect(composio.toolRouter).toBe(composio.sessions);
129
130 - const sessionFromCanonicalApi = await composio.sessions.create('user_123');
131 - const sessionFromAlias = await composio.create('user_456');
130 + const session = await composio.sessions.create('user_123');
131
132 expect(client.toolRouter.session.create).toHaveBeenNthCalledWith(
133 1,
134 expect.objectContaining({ user_id: 'user_123' }),
135 undefined
136 );
138 - expect(client.toolRouter.session.create).toHaveBeenNthCalledWith(
139 - 2,
140 - expect.objectContaining({ user_id: 'user_456' }),
141 - undefined
142 - );
143 - expect(sessionFromCanonicalApi.sessionId).toBe('session_123');
144 - expect(sessionFromAlias.sessionId).toBe('session_123');
137 + expect(session.sessionId).toBe('session_123');
138 + expect(composio).not.toHaveProperty('create');
139 + expect(composio).not.toHaveProperty('use');
140 });
141 });
142
ts/packages/core/type-tests/sessions-mcp.test-d.ts
+16 -8
@@ -13,7 +13,7 @@ declare const composio: Composio;
13
14 async function createGating(): Promise<void> {
15 // Default: no `{ mcp: true }` → `session.mcp` is NOT in the type.
16 - const session = await composio.create('user_123');
16 + const session = await composio.sessions.create('user_123');
17 // @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passed
18 void session.mcp;
19
@@ -21,17 +21,17 @@ async function createGating(): Promise<void> {
21 await session.tools();
22
23 // Opt-in: `{ mcp: true }` → `session.mcp` is surfaced.
24 - const mcpSession = await composio.create('user_123', { mcp: true });
24 + const mcpSession = await composio.sessions.create('user_123', { mcp: true });
25 const _url: string = mcpSession.mcp.url;
26 void _url;
27 }
28
29 async function useGating(): Promise<void> {
30 - const session = await composio.use('session_123');
30 + const session = await composio.sessions.use('session_123');
31 // @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passed
32 void session.mcp;
33
34 - const mcpSession = await composio.use('session_123', { mcp: true });
34 + const mcpSession = await composio.sessions.use('session_123', { mcp: true });
35 const _url: string = mcpSession.mcp.url;
36 void _url;
37 }
@@ -41,13 +41,21 @@ async function useGating(): Promise<void> {
41 // The `{ mcp: true }` overload refactor previously dropped this from `create()`.
42 async function requestOptionsArg(): Promise<void> {
43 const ctrl = new AbortController();
44 - await composio.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });
45 - await composio.create('user_123', { mcp: true }, { signal: ctrl.signal });
44 + await composio.sessions.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });
45 + await composio.sessions.create('user_123', { mcp: true }, { signal: ctrl.signal });
46 await composio.sessions.create('user_123', undefined, { signal: ctrl.signal });
47 - await composio.use('session_123', { customTools: [] }, { signal: ctrl.signal });
48 - await composio.use('session_123', { mcp: true }, { signal: ctrl.signal });
47 + await composio.sessions.use('session_123', { customTools: [] }, { signal: ctrl.signal });
48 + await composio.sessions.use('session_123', { mcp: true }, { signal: ctrl.signal });
49 +}
50 +
51 +function bareSessionAliasesAreRemoved(): void {
52 + // @ts-expect-error Session APIs are only available under `composio.sessions`.
53 + void composio.create;
54 + // @ts-expect-error Session APIs are only available under `composio.sessions`.
55 + void composio.use;
56 }
57
58 void createGating;
59 void useGating;
60 void requestOptionsArg;
61 +void bareSessionAliasesAreRemoved;
ts/packages/providers/anthropic/README.md
+3 -2
@@ -25,13 +25,14 @@ const composio = new Composio({
25 const client = new Anthropic();
26
27 // Create a session for your user
28 -const session = await composio.create('user_123');
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const messages: Anthropic.MessageParam[] = [
32 {
33 role: 'user',
34 - content: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
34 + content:
35 + "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
36 },
37 ];
38
ts/packages/providers/claude-agent-sdk/README.md
+11 -11
@@ -18,38 +18,38 @@ Set two environment variables:
18 Create a session for your user, serve its tools through an SDK MCP server, and query Claude:
19
20 ```typescript
21 -import { Composio } from "@composio/core";
22 -import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
23 -import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
21 +import { Composio } from '@composio/core';
22 +import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
23 +import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
24
25 const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
26
27 // Each session is scoped to one of your users
28 -const session = await composio.create("user_123");
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const customServer = createSdkMcpServer({
32 - name: "composio",
33 - version: "1.0.0",
32 + name: 'composio',
33 + version: '1.0.0',
34 tools,
35 });
36
37 for await (const stream of query({
38 - prompt: "Summarize my emails from today",
38 + prompt: 'Summarize my emails from today',
39 options: {
40 mcpServers: { composio: customServer },
41 - permissionMode: "bypassPermissions",
41 + permissionMode: 'bypassPermissions',
42 },
43 })) {
44 - if (stream.type === "assistant") {
44 + if (stream.type === 'assistant') {
45 for (const block of stream.message.content) {
46 - if (block.type === "text") process.stdout.write(block.text);
46 + if (block.type === 'text') process.stdout.write(block.text);
47 }
48 }
49 }
50 ```
51
52 -For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.
52 +For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
53
54 ## How it works
55
ts/packages/providers/cloudflare/README.md
+1 -1
@@ -26,7 +26,7 @@ export default {
26 });
27
28 // Create a session for your user
29 - const session = await composio.create('user_123');
29 + const session = await composio.sessions.create('user_123');
30 const tools = await session.tools();
31
32 const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
ts/packages/providers/google/README.md
+3 -2
@@ -25,7 +25,7 @@ const composio = new Composio({
25 const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });
26
27 // Create a session for your user
28 -const session = await composio.create('user_123');
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const chat = ai.chats.create({
@@ -36,7 +36,8 @@ const chat = ai.chats.create({
36 });
37
38 let response = await chat.sendMessage({
39 - message: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
39 + message:
40 + "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
41 });
42
43 // Agentic loop: keep executing tool calls until the model responds with text
ts/packages/providers/langchain/README.md
+1 -1
@@ -27,7 +27,7 @@ const composio = new Composio({
27 });
28
29 // Create a session for your user
30 -const session = await composio.create('user_123');
30 +const session = await composio.sessions.create('user_123');
31 const tools = await session.tools();
32
33 const toolNode = new ToolNode(tools);
ts/packages/providers/llamaindex/README.md
+1 -1
@@ -25,7 +25,7 @@ const composio = new Composio({
25 });
26
27 // Create a session for your user
28 -const session = await composio.create('user_123');
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const myAgent = agent({
ts/packages/providers/mastra/README.md
+1 -1
@@ -25,7 +25,7 @@ const composio = new Composio({
25 });
26
27 // Create a session for your user
28 -const session = await composio.create('user_123');
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const agent = new Agent({
ts/packages/providers/openai-agents/README.md
+9 -9
@@ -18,28 +18,28 @@ Set two environment variables:
18 Create a session for your user, hand its tools to an agent, and run it:
19
20 ```typescript
21 -import { Composio } from "@composio/core";
22 -import { OpenAIAgentsProvider } from "@composio/openai-agents";
23 -import { Agent, run } from "@openai/agents";
21 +import { Composio } from '@composio/core';
22 +import { OpenAIAgentsProvider } from '@composio/openai-agents';
23 +import { Agent, run } from '@openai/agents';
24
25 const composio = new Composio({ provider: new OpenAIAgentsProvider() });
26
27 // Each session is scoped to one of your users
28 -const session = await composio.create("user_123");
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 const agent = new Agent({
32 - name: "Personal Assistant",
33 - instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
34 - model: "gpt-5.2",
32 + name: 'Personal Assistant',
33 + instructions: 'You are a helpful personal assistant. Use Composio tools to take action.',
34 + model: 'gpt-5.2',
35 tools,
36 });
37
38 -const result = await run(agent, "Summarize my emails from today");
38 +const result = await run(agent, 'Summarize my emails from today');
39 console.log(result.finalOutput);
40 ```
41
42 -For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.
42 +For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
43
44 ## Strict mode
45
ts/packages/providers/openai/README.md
+3 -2
@@ -25,7 +25,7 @@ const composio = new Composio({
25 const client = new OpenAI();
26
27 // Create a session for your user
28 -const session = await composio.create('user_123');
28 +const session = await composio.sessions.create('user_123');
29 const tools = await session.tools();
30
31 let response = await client.responses.create({
@@ -34,7 +34,8 @@ let response = await client.responses.create({
34 input: [
35 {
36 role: 'user',
37 - content: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
37 + content:
38 + "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'",
39 },
40 ],
41 });
ts/packages/providers/vercel/README.md
+8 -8
@@ -20,28 +20,28 @@ Set two environment variables:
20 Create a session for your user, pass its tools to the AI SDK, and cap the run with `stopWhen`:
21
22 ```typescript
23 -import { anthropic } from "@ai-sdk/anthropic";
24 -import { Composio } from "@composio/core";
25 -import { VercelProvider } from "@composio/vercel";
26 -import { generateText, stepCountIs } from "ai";
23 +import { anthropic } from '@ai-sdk/anthropic';
24 +import { Composio } from '@composio/core';
25 +import { VercelProvider } from '@composio/vercel';
26 +import { generateText, stepCountIs } from 'ai';
27
28 const composio = new Composio({ provider: new VercelProvider() });
29
30 // Each session is scoped to one of your users
31 -const session = await composio.create("user_123");
31 +const session = await composio.sessions.create('user_123');
32 const tools = await session.tools();
33
34 const { text } = await generateText({
35 - model: anthropic("claude-sonnet-4-6"),
35 + model: anthropic('claude-sonnet-4-6'),
36 tools,
37 - prompt: "Summarize my emails from today",
37 + prompt: 'Summarize my emails from today',
38 stopWhen: stepCountIs(10),
39 });
40
41 console.log(text);
42 ```
43
44 -For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.
44 +For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
45
46 ## Strict mode
47