Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
revert(core): defer v1 session alias removal (#3826)
Alberto Schiabelfbcf08136d3b
diff --git a/.changeset/deprecate-session-aliases-freeze-mcp-spi.md b/.changeset/deprecate-session-aliases-freeze-mcp-spi.mddeleted file mode 100644index 1165c942e..000000000--- a/.changeset/deprecate-session-aliases-freeze-mcp-spi.md+++ /dev/null@@ -1,8 +0,0 @@-----'@composio/core': minor------Two pre-v1 API-hygiene fixes:-- - **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, released as a pre-v1 minor.- - **Un-deprecate `BaseProvider.wrapMcpServerResponse`** and retain it as the intended v1 SPI method. Its `@deprecated` note pointed at a plural `wrapMcpServers` method that was never added; the singular method is the contract we intend to freeze for v1.diff --git a/README.md b/README.mdindex f27f14530..951b2ead5 100644--- a/README.md+++ b/README.md@@ -53,7 +53,7 @@ import { Agent, run } from "@openai/agents";const composio = new Composio({ provider: new OpenAIAgentsProvider() });// Each session is scoped to one of your users-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const agent = new Agent({@@ -93,9 +93,9 @@ result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from tprint(result.final_output)```-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.+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.-**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).+**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).## CLIdiff --git a/docs/agent/instructions.md b/docs/agent/instructions.mdindex 78425a678..6fc4af3b8 100644--- a/docs/agent/instructions.md+++ b/docs/agent/instructions.md@@ -26,7 +26,7 @@ Workflow for anything non-trivial:## Rules- **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.-- 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.+- Prefer the current API in examples: `composio.create(userId)` / `composio.sessions.create(...)`, session tools, meta tools, and `{ mcp: true }` for MCP.- Don't claim something is supported unless a page says so.- Cite **only** as standard Markdown links, e.g. `[Authentication](/docs/authentication)`. Never emit citation markers, reference tokens, or anything like `cite`/`turn0search0`.diff --git a/docs/agent/instructions/context.md b/docs/agent/instructions/context.mdindex 19fc911a4..e0a39e040 100644--- a/docs/agent/instructions/context.md+++ b/docs/agent/instructions/context.md@@ -4,10 +4,10 @@ This is your always-on map of Composio's concepts and the canonical page for eac## Core model-- **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)+- **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)- **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)- **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)-- **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)+- **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)## Tools and toolkitsdiff --git a/docs/agent/knowledge.md b/docs/agent/knowledge.mdindex ed20daa25..cc84a30bd 100644--- a/docs/agent/knowledge.md+++ b/docs/agent/knowledge.md@@ -6,7 +6,7 @@ here to expose more answers to search without changing the docs themselves.## Installing and getting started (/docs/quickstart)-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.+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.## Choosing a provider (/docs/providers)@@ -26,4 +26,4 @@ The sandbox has a persistent file mount at `/mnt/files/` that survives sandbox r## Reusing and updating sessions (/docs/how-composio-works)-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 })`.+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 })`.diff --git a/docs/api-overviews/mcp.mdx b/docs/api-overviews/mcp.mdxindex 0fa88b5f8..257e30798 100644--- a/docs/api-overviews/mcp.mdx+++ b/docs/api-overviews/mcp.mdx@@ -1,9 +1,9 @@<Callout type="warning">-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).+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).</Callout>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.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.-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).+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).diff --git a/docs/api-overviews/tool-router.mdx b/docs/api-overviews/tool-router.mdxindex 16f97518d..1b5300b65 100644--- a/docs/api-overviews/tool-router.mdx+++ b/docs/api-overviews/tool-router.mdx@@ -4,7 +4,7 @@ These are Composio's session endpoints. A **session** is the runtime context youSessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.</Callout>-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.+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.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.diff --git a/docs/api-overviews/webhook-subscriptions.mdx b/docs/api-overviews/webhook-subscriptions.mdxindex 661ba0fcd..e2380205f 100644--- a/docs/api-overviews/webhook-subscriptions.mdx+++ b/docs/api-overviews/webhook-subscriptions.mdx@@ -111,7 +111,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiReconst toolkit = payload.data.toolkit.slug;// Look up the user and send them a re-auth link- const session = await composio.sessions.create(lookupUser(accountId));+ const session = await composio.create(lookupUser(accountId));const connectionRequest = await session.authorize(toolkit);if (connectionRequest.redirectUrl) {notifyUser(connectionRequest.redirectUrl);diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.tsindex 10319bc37..3c2c7a6e6 100644--- a/docs/app/llms.txt/route.ts+++ b/docs/app/llms.txt/route.ts@@ -109,7 +109,7 @@ export async function GET() {> Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.-> **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.+> **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.${docsTree}diff --git a/docs/content/docs/authentication.mdx b/docs/content/docs/authentication.mdxindex 0581766f7..be760c5cf 100644--- a/docs/content/docs/authentication.mdx+++ b/docs/content/docs/authentication.mdx@@ -72,7 +72,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {manageConnections: { callbackUrl: "https://yourapp.com/chat" },});```@@ -124,7 +124,7 @@ print(connection_request.redirect_url)import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const connectionRequest = await session.authorize("gmail");// Send this URL to the user (email, in-app notification, etc.)diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdxindex 878dc5d89..5424788f6 100644--- a/docs/content/docs/configuring-sessions.mdx+++ b/docs/content/docs/configuring-sessions.mdx@@ -17,7 +17,7 @@ session = composio.sessions.create(user_id="user_123")import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");```</Tab></Tabs>@@ -52,12 +52,12 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---// Using array format-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["github", "gmail", "slack"],});// Using object format with enable key-const session2 = await composio.sessions.create("user_123", {+const session2 = await composio.create("user_123", {toolkits: { enable: ["github", "gmail", "slack"] },});```@@ -82,7 +82,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: { disable: ["exa", "firecrawl"] },});```@@ -136,7 +136,7 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],tools: {gmail: {@@ -209,7 +209,7 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],tools: {gmail: {@@ -261,7 +261,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {tools: {// Only these Gmail tools will be availablegmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },@@ -292,7 +292,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {tools: {gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]@@ -323,7 +323,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {tools: {// All Slack tools except deleteslack: { disable: ["SLACK_DELETE_MESSAGE"] },@@ -373,12 +373,12 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---// Only include read-only and idempotent tools-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {tags: ["readOnlyHint", "idempotentHint"]});// Enable some tags, disable others-const sessionWithTagConfig = await composio.sessions.create("user_123", {+const sessionWithTagConfig = await composio.create("user_123", {tags: {enable: ["readOnlyHint"],disable: ["destructiveHint"]@@ -411,7 +411,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {// Global: only read-only toolstags: ["readOnlyHint"],tools: {@@ -484,7 +484,7 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],preload: {tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],@@ -526,7 +526,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {authConfigs: {github: "ac_your_github_config",slack: "ac_your_slack_config",@@ -559,7 +559,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {connectedAccounts: {gmail: ["ca_work_gmail"],github: ["ca_personal_github"],@@ -606,7 +606,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {sandbox: {enable: false,},@@ -659,7 +659,7 @@ session = composio.sessions.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {sandbox: {enable: true,sandboxSize: "large",@@ -693,7 +693,7 @@ tools = session.tools()```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const tools = await session.tools();```@@ -718,7 +718,7 @@ connected_account = connection_request.wait_for_connection()```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const connectionRequest = await session.authorize("github", {callbackUrl: "https://myapp.com/callback",@@ -751,7 +751,7 @@ for toolkit in toolkits.items:```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const toolkits = await session.toolkits();@@ -774,7 +774,7 @@ connected = session.toolkits(is_connected=True)```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const connected = await session.toolkits({ isConnected: true });```@@ -801,7 +801,7 @@ while True:```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const allToolkits: any[] = [];let cursor: string | undefined;@@ -834,7 +834,7 @@ print(result["session_id"], result["deleted"])```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');// ---cut---const result = await session.delete();console.log(result.sessionId, result.deleted);diff --git a/docs/content/docs/controlling-scopes.mdx b/docs/content/docs/controlling-scopes.mdxindex d8df3ca7b..32740149b 100644--- a/docs/content/docs/controlling-scopes.mdx+++ b/docs/content/docs/controlling-scopes.mdx@@ -141,7 +141,7 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const authConfig = { id: 'ac_your_github_config' };// ---cut----const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {authConfigs: { github: authConfig.id },});```diff --git a/docs/content/docs/custom-app-vs-managed-app.mdx b/docs/content/docs/custom-app-vs-managed-app.mdxindex 66555f9c5..8a3f33ddc 100644--- a/docs/content/docs/custom-app-vs-managed-app.mdx+++ b/docs/content/docs/custom-app-vs-managed-app.mdx@@ -91,7 +91,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {authConfigs: {github: "ac_your_github_config",// toolkits not listed here still use Composio managed auth@@ -125,7 +125,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio();// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {authConfigs: {github: "ac_your_github_config",google: "ac_your_google_config",diff --git a/docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdx b/docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdxindex 1394ab979..cd53aff6b 100644--- a/docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdx+++ b/docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdx@@ -132,7 +132,7 @@ declare const getUserProfile: ReturnType<typeof experimental_createTool>;const composio = new Composio({ apiKey: "your_api_key" });// ---cut----const session = await composio.sessions.create("user_1", {+const session = await composio.create("user_1", {experimental: {customTools: [getUserProfile],},@@ -294,7 +294,7 @@ declare const sendPromoEmail: ReturnType<typeof experimental_createTool>;const composio = new Composio({ apiKey: "your_api_key" });// ---cut----const session = await composio.sessions.create("user_1", {+const session = await composio.create("user_1", {toolkits: ["gmail"],experimental: {customTools: [sendPromoEmail],@@ -439,7 +439,7 @@ declare const userManagement: ReturnType<typeof experimental_createToolkit>;const composio = new Composio({ apiKey: "your_api_key" });// ---cut----const session = await composio.sessions.create("user_1", {+const session = await composio.create("user_1", {experimental: {customToolkits: [userManagement],},@@ -500,7 +500,7 @@ const replyGuide = experimental_createTool("GET_REPLY_STYLE_GUIDE", {execute: async ({ topic }) => ({ topic, tone: "concise and helpful" }),});-const session = await composio.sessions.create("user_1", {+const session = await composio.create("user_1", {experimental: {customTools: [replyGuide],},@@ -603,7 +603,7 @@ Use these methods to list registered tools and toolkits. Slugs include their fin```typescriptimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });-const session = await composio.sessions.create("user_1");+const session = await composio.create("user_1");// ---cut---const customTools = session.customTools();const customToolkits = session.customToolkits();@@ -631,7 +631,7 @@ declare const getUserProfile: ReturnType<typeof experimental_createTool>;const composio = new Composio({ apiKey: "your_api_key" });// ---cut----const session = await composio.sessions.use("session_id", {+const session = await composio.use("session_id", {customTools: [getUserProfile],});```@@ -659,7 +659,7 @@ Use `session.execute()` to run custom tools directly, outside of an agent loop.```typescriptimport { Composio } from "@composio/core";const composio = new Composio({ apiKey: "your_api_key" });-const session = await composio.sessions.create("user_1");+const session = await composio.create("user_1");// ---cut---const result = await session.execute("GET_USER_PROFILE");```diff --git a/docs/content/docs/extending-sessions/proxy-execute.mdx b/docs/content/docs/extending-sessions/proxy-execute.mdxindex 7d1b1dc30..3bd30e1c7 100644--- a/docs/content/docs/extending-sessions/proxy-execute.mdx+++ b/docs/content/docs/extending-sessions/proxy-execute.mdx@@ -46,7 +46,7 @@ print(response.data)```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create('user_123', { toolkits: ['github'] });+const session = await composio.create('user_123', { toolkits: ['github'] });// ---cut---const { status, data } = await session.proxyExecute({toolkit: 'github',diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdxindex 90cfbba10..da5dd0590 100644--- a/docs/content/docs/how-composio-works.mdx+++ b/docs/content/docs/how-composio-works.mdx@@ -4,7 +4,7 @@ description: What Composio sessions do, and how they scope users, tools, toolkitkeywords: [session, userID, tools, toolkits, meta tools, mcp, workbench]----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. Create one with `composio.sessions.create(...)` in either SDK. 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.+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.## The basics@@ -23,7 +23,7 @@ tools = session.tools()import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();```@@ -86,9 +86,9 @@ The sandbox is scoped to the session, so files, variables, helper functions, and## How sessions behave-Every session-creation call returns a new session ID. Use it for a fresh task context.+Every `create()` call returns a new session ID. Use it for a fresh task context.-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.+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.<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -102,7 +102,7 @@ tools = session.tools()import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.use("session_id");+const session = await composio.use("session_id");const tools = await session.tools();```</Tab>@@ -124,7 +124,7 @@ session.update(```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.use("session_id");+const session = await composio.use("session_id");// ---cut---await session.update({toolkits: ["gmail", "slack"],diff --git a/docs/content/docs/importing-existing-connections.mdx b/docs/content/docs/importing-existing-connections.mdxindex 873ad5394..f333d78fa 100644--- a/docs/content/docs/importing-existing-connections.mdx+++ b/docs/content/docs/importing-existing-connections.mdx@@ -316,7 +316,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your-api-key' });// ---cut----const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {authConfigs: { gmail: 'ac_your_auth_config' },toolkits: ['gmail'],});diff --git a/docs/content/docs/managing-multiple-connected-accounts.mdx b/docs/content/docs/managing-multiple-connected-accounts.mdxindex 89c1c1115..0436c5d78 100644--- a/docs/content/docs/managing-multiple-connected-accounts.mdx+++ b/docs/content/docs/managing-multiple-connected-accounts.mdx@@ -29,7 +29,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],multiAccount: {enable: true,@@ -76,7 +76,7 @@ personal_connection = personal_auth.wait_for_connection()import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],multiAccount: { enable: true },});@@ -118,7 +118,7 @@ connection_request = session.authorize("gmail", alias="work-gmail")// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const connectionRequest = await session.authorize("gmail", { alias: "work-gmail" });```@@ -176,7 +176,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {connectedAccounts: {gmail: ["ca_work_gmail_id"],github: ["ca_personal_github_id"],@@ -205,7 +205,7 @@ for toolkit in toolkits.items:// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const toolkits = await session.toolkits();diff --git a/docs/content/docs/manually-authenticating.mdx b/docs/content/docs/manually-authenticating.mdxindex 58ccfb393..370de43ab 100644--- a/docs/content/docs/manually-authenticating.mdx+++ b/docs/content/docs/manually-authenticating.mdx@@ -31,7 +31,7 @@ print(f"Connected: {connected_account.id}")import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const connectionRequest = await session.authorize("gmail");@@ -69,7 +69,7 @@ print(connection_request.redirect_url)```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const connectionRequest = await session.authorize("gmail", {callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding",@@ -109,7 +109,7 @@ for toolkit in toolkits.items:```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const toolkits = await session.toolkits();@@ -138,7 +138,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {manageConnections: false,});```@@ -187,7 +187,7 @@ const composio = new Composio({ apiKey: "your-api-key" });const requiredToolkits = ["gmail", "github"];-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {manageConnections: false, // Disable in-chat auth prompts});diff --git a/docs/content/docs/migration-guide/direct-to-sessions.mdx b/docs/content/docs/migration-guide/direct-to-sessions.mdxindex 7e59a37b0..ab0e8cd48 100644--- a/docs/content/docs/migration-guide/direct-to-sessions.mdx+++ b/docs/content/docs/migration-guide/direct-to-sessions.mdx@@ -57,7 +57,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB", "SLACK"] });// After: create a session with your existing auth configs-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {authConfigs: {github: "ac_your_github_config",slack: "ac_your_slack_config",@@ -90,7 +90,7 @@ tools = session.tools()```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---// Before: manually specifying which tools to fetch// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB"] });@@ -130,7 +130,7 @@ connected_account = connection_request.wait_for_connection()```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---// Before: manual auth flow// const connectionRequest = await composio.connectedAccounts.link("user_123", "ac_your_github_config", {@@ -186,7 +186,7 @@ import { Composio } from '@composio/core';// After: no version management neededconst composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");```</Tab></Tabs>@@ -217,7 +217,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["github", "gmail", "slack"],authConfigs: {github: "ac_your_github_config",@@ -252,7 +252,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {authConfigs: {gmail: "ac_your_gmail_config",},diff --git a/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx b/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdxindex 3ee047d96..61a770ed0 100644--- a/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx+++ b/docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx@@ -101,7 +101,7 @@ const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });// const mcpUrl = instance.url;// After: one session, same toolkit + auth config + tools-const session = await composio.sessions.create("user-123", {+const session = await composio.create("user-123", {toolkits: ["gmail"],authConfigs: { gmail: "ac_xyz123" },tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },@@ -158,7 +158,7 @@ import { Composio, SessionPreset } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });// ---cut----const session = await composio.sessions.create("user-123", {+const session = await composio.create("user-123", {toolkits: ["gmail"],authConfigs: { gmail: "ac_xyz123" },tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },@@ -195,7 +195,7 @@ tools = session.tools()```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-const session = await composio.sessions.create("user-123");+const session = await composio.create("user-123");// ---cut---const tools = await session.tools();```@@ -219,7 +219,7 @@ result = session.execute(```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-const session = await composio.sessions.create("user-123");+const session = await composio.create("user-123");// ---cut---const result = await session.execute("GITHUB_CREATE_ISSUE", {owner: "my-org",diff --git a/docs/content/docs/migration-guide/new-sdk.mdx b/docs/content/docs/migration-guide/new-sdk.mdxindex 5826b7c8b..056f5d260 100644--- a/docs/content/docs/migration-guide/new-sdk.mdx+++ b/docs/content/docs/migration-guide/new-sdk.mdx@@ -614,7 +614,7 @@ const getIssueInfo = experimental_createTool("GET_ISSUE_INFO", {},});-const session = await composio.sessions.create("default", {+const session = await composio.create("default", {experimental: { customTools: [getIssueInfo] },});```diff --git a/docs/content/docs/migration-guide/tool-router-beta.mdx b/docs/content/docs/migration-guide/tool-router-beta.mdxindex 16f7e9464..e800db0f7 100644--- a/docs/content/docs/migration-guide/tool-router-beta.mdx+++ b/docs/content/docs/migration-guide/tool-router-beta.mdx@@ -54,7 +54,7 @@ session = composio.create(const session = await composio.experimental.toolRouter.createSession('user_123');// Stable (after)-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');```</Tab></Tabs>@@ -87,7 +87,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create('user_123',+const session = await composio.create('user_123',{authConfigs: {github: "ac_your_github_config",diff --git a/docs/content/docs/programmatic-auth-configs.mdx b/docs/content/docs/programmatic-auth-configs.mdxindex ab3063480..d6cf5367a 100644--- a/docs/content/docs/programmatic-auth-configs.mdx+++ b/docs/content/docs/programmatic-auth-configs.mdx@@ -151,7 +151,7 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });const authConfig = { id: 'ac_your_notion_config' };// ---cut----const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {authConfigs: { notion: authConfig.id },});```diff --git a/docs/content/docs/providers/anthropic.mdx b/docs/content/docs/providers/anthropic.mdxindex fe6613979..f5911ed5e 100644--- a/docs/content/docs/providers/anthropic.mdx+++ b/docs/content/docs/providers/anthropic.mdx@@ -113,7 +113,7 @@ const composio = new Composio({const client = new Anthropic();// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const messages: Anthropic.MessageParam[] = [@@ -236,7 +236,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const toolServer = createSdkMcpServer({name: "composio",diff --git a/docs/content/docs/providers/google.mdx b/docs/content/docs/providers/google.mdxindex 9b343ad3d..52464a7b5 100644--- a/docs/content/docs/providers/google.mdx+++ b/docs/content/docs/providers/google.mdx@@ -87,7 +87,7 @@ const composio = new Composio({const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const chat = ai.chats.create({diff --git a/docs/content/docs/providers/langchain.mdx b/docs/content/docs/providers/langchain.mdxindex d27c02b8c..1d4963990 100644--- a/docs/content/docs/providers/langchain.mdx+++ b/docs/content/docs/providers/langchain.mdx@@ -80,7 +80,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const toolNode = new ToolNode(tools);diff --git a/docs/content/docs/providers/llamaindex.mdx b/docs/content/docs/providers/llamaindex.mdxindex d22c34e80..008c9bf0c 100644--- a/docs/content/docs/providers/llamaindex.mdx+++ b/docs/content/docs/providers/llamaindex.mdx@@ -75,7 +75,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const myAgent = agent({diff --git a/docs/content/docs/providers/mastra.mdx b/docs/content/docs/providers/mastra.mdxindex 208f119d7..8f4c06f18 100644--- a/docs/content/docs/providers/mastra.mdx+++ b/docs/content/docs/providers/mastra.mdx@@ -40,7 +40,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const agent = new Agent({diff --git a/docs/content/docs/providers/openai.mdx b/docs/content/docs/providers/openai.mdxindex 7a51c5092..7e9c803b7 100644--- a/docs/content/docs/providers/openai.mdx+++ b/docs/content/docs/providers/openai.mdx@@ -114,7 +114,7 @@ const composio = new Composio({const client = new OpenAI();// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();let response = await client.responses.create({@@ -254,7 +254,7 @@ const composio = new Composio({const client = new OpenAI();// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [@@ -371,7 +371,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const agent = new Agent({diff --git a/docs/content/docs/providers/vercel.mdx b/docs/content/docs/providers/vercel.mdxindex e5ef6d062..8fbb51d9c 100644--- a/docs/content/docs/providers/vercel.mdx+++ b/docs/content/docs/providers/vercel.mdx@@ -40,7 +40,7 @@ import { generateText, stepCountIs } from "ai";const composio = new Composio({ provider: new VercelProvider() });// Create a session for your user-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();const { text } = await generateText({diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdxindex 5efc13e9b..6ea0f8f45 100644--- a/docs/content/docs/quickstart.mdx+++ b/docs/content/docs/quickstart.mdx@@ -115,12 +115,12 @@ const composio = new Composio({ provider: new OpenAIAgentsProvider() });// Create a session for your userconst userId = "user_123";-const session = await composio.sessions.create(userId);+const session = await composio.create(userId);const tools = await session.tools();// For multi-turn, store the session ID in your db and reuse instead of calling create() again:// const sessionId = session.sessionId;-// const session = await composio.sessions.use(sessionId);+// const session = await composio.use(sessionId);const agent = new Agent({name: "Personal Assistant",@@ -269,12 +269,12 @@ const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });// Create a session for your userconst userId = "user_123";-const session = await composio.sessions.create(userId);+const session = await composio.create(userId);const tools = await session.tools();// For multi-turn, store the session ID in your db and reuse instead of calling create() again:// const sessionId = session.sessionId;-// const session = await composio.sessions.use(sessionId);+// const session = await composio.use(sessionId);const customServer = createSdkMcpServer({name: "composio",@@ -373,12 +373,12 @@ const composio = new Composio({ provider: new VercelProvider() });// Create a session for your userconst userId = "user_123";-const session = await composio.sessions.create(userId);+const session = await composio.create(userId);const tools = await session.tools();// For multi-turn, store the session ID in your db and reuse instead of calling create() again:// const sessionId = session.sessionId;-// const session = await composio.sessions.use(sessionId);+// const session = await composio.use(sessionId);const readline = createInterface({ input: process.stdin, output: process.stdout });diff --git a/docs/content/docs/sandbox/local.mdx b/docs/content/docs/sandbox/local.mdxindex c8f01d579..b0c16b0bf 100644--- a/docs/content/docs/sandbox/local.mdx+++ b/docs/content/docs/sandbox/local.mdx@@ -35,7 +35,7 @@ import { experimental_createLocalWorkbenchSession } from '@composio/experimentalconst composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });// Create the session with the remote sandbox disabled, so code runs in your box.-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['github'],workbench: { enable: false },});diff --git a/docs/content/docs/sandbox/remote.mdx b/docs/content/docs/sandbox/remote.mdxindex c9f01af6a..a3223e9bd 100644--- a/docs/content/docs/sandbox/remote.mdx+++ b/docs/content/docs/sandbox/remote.mdx@@ -90,7 +90,7 @@ report.save("./report.pdf")import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// Upload a local file; the sandbox sees it at /mnt/files/sales.csvconst uploaded = await session.experimental.files.upload("./sales.csv");diff --git a/docs/content/docs/sessions-via-mcp.mdx b/docs/content/docs/sessions-via-mcp.mdxindex c35a433d6..e516fd5b9 100644--- a/docs/content/docs/sessions-via-mcp.mdx+++ b/docs/content/docs/sessions-via-mcp.mdx@@ -30,7 +30,7 @@ mcp_headers = session.mcp.headersimport { Composio } from "@composio/core";const composio = new Composio();-const session = await composio.sessions.create("user_123", { mcp: true });+const session = await composio.create("user_123", { mcp: true });const mcpUrl = session.mcp.url;const mcpHeaders = session.mcp.headers;@@ -41,7 +41,7 @@ const mcpHeaders = session.mcp.headers;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.<Callout type="info">-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.+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.</Callout><Callout type="info">@@ -78,7 +78,7 @@ import { Composio, SessionPreset } from "@composio/core";const composio = new Composio();-const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["gmail"],tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"] } },sessionPreset: SessionPreset.DIRECT_TOOLS,@@ -140,7 +140,7 @@ import { Composio } from "@composio/core";import { createMCPClient } from "@ai-sdk/mcp";const composio = new Composio();-const { mcp } = await composio.sessions.create("user_123", { mcp: true });+const { mcp } = await composio.create("user_123", { mcp: true });const client = await createMCPClient({transport: {diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdxindex 359ac915b..694769d2a 100644--- a/docs/content/docs/sessions-vs-direct-execution.mdx+++ b/docs/content/docs/sessions-vs-direct-execution.mdx@@ -5,7 +5,7 @@ keywords: [session, direct execution, tool router, meta tools, architecture, declegacy: true----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.+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.**Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.@@ -28,7 +28,7 @@ Sessions aren't all-or-nothing. With the [direct tools preset](/docs/configuring## Sessions-Creating a session returns [meta tools](/docs/how-composio-works#meta-tools):+`composio.create()` returns [meta tools](/docs/how-composio-works#meta-tools):<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -52,7 +52,7 @@ const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,provider: new OpenAIProvider(),});-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();// Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,// COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.@@ -101,7 +101,7 @@ session = composio.create(import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut----const session = await composio.sessions.create("user_123", {+const session = await composio.create("user_123", {toolkits: ["github", "gmail"],authConfigs: { github: "ac_my_config" },connectedAccounts: { gmail: ["ca_work"] },diff --git a/docs/content/docs/shared-connections.mdx b/docs/content/docs/shared-connections.mdxindex 6d27b3400..5d417adf4 100644--- a/docs/content/docs/shared-connections.mdx+++ b/docs/content/docs/shared-connections.mdx@@ -120,7 +120,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });// user_alice starts a session that pins the shared Gmail connection.// Gmail tools loaded from this session will resolve to that connection// even though user_alice did not create it.-const session = await composio.sessions.create("user_alice", {+const session = await composio.create("user_alice", {connectedAccounts: {gmail: ["ca_gmail_shared"],},diff --git a/docs/content/docs/white-labeling-authentication.mdx b/docs/content/docs/white-labeling-authentication.mdxindex 7b0e5b05a..94e6621fa 100644--- a/docs/content/docs/white-labeling-authentication.mdx+++ b/docs/content/docs/white-labeling-authentication.mdx@@ -141,7 +141,7 @@ connection_request = session.authorize(```typescriptimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// ---cut---const connectionRequest = await session.authorize("gmail", {callbackUrl: "https://your-app.com/callback",diff --git a/docs/content/reference/api-reference/mcp/index.mdx b/docs/content/reference/api-reference/mcp/index.mdxindex 3fbcaa2e7..edfea205d 100644--- a/docs/content/reference/api-reference/mcp/index.mdx+++ b/docs/content/reference/api-reference/mcp/index.mdx@@ -6,14 +6,14 @@ description: "MCP server management"{/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/mcp.mdx, not this file. */}<Callout type="warning">-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).+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).</Callout>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.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.-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).+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).## Endpointsdiff --git a/docs/content/reference/api-reference/tool-router/index.mdx b/docs/content/reference/api-reference/tool-router/index.mdxindex 48f7bd93c..2423ffd71 100644--- a/docs/content/reference/api-reference/tool-router/index.mdx+++ b/docs/content/reference/api-reference/tool-router/index.mdx@@ -11,7 +11,7 @@ These are Composio's session endpoints. A **session** is the runtime context youSessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.</Callout>-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.+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.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.diff --git a/docs/content/reference/api-reference/webhook-subscriptions/index.mdx b/docs/content/reference/api-reference/webhook-subscriptions/index.mdxindex 1fb3ab5da..3bc0b5fdb 100644--- a/docs/content/reference/api-reference/webhook-subscriptions/index.mdx+++ b/docs/content/reference/api-reference/webhook-subscriptions/index.mdx@@ -118,7 +118,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiReconst toolkit = payload.data.toolkit.slug;// Look up the user and send them a re-auth link- const session = await composio.sessions.create(lookupUser(accountId));+ const session = await composio.create(lookupUser(accountId));const connectionRequest = await session.authorize(toolkit);if (connectionRequest.redirectUrl) {notifyUser(connectionRequest.redirectUrl);diff --git a/docs/content/reference/glossary.mdx b/docs/content/reference/glossary.mdxindex abfaf08bd..d2f6e93a5 100644--- a/docs/content/reference/glossary.mdx+++ b/docs/content/reference/glossary.mdx@@ -88,7 +88,7 @@ An adapter package that transforms Composio tools into the format an AI framewor</GlossaryTerm><GlossaryTerm name="Session">-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).+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).</GlossaryTerm><GlossaryTerm name="Session ID">diff --git a/docs/content/reference/sdk-reference/typescript/composio.mdx b/docs/content/reference/sdk-reference/typescript/composio.mdxindex 784e75c4b..f4631de60 100644--- a/docs/content/reference/sdk-reference/typescript/composio.mdx+++ b/docs/content/reference/sdk-reference/typescript/composio.mdx@@ -53,6 +53,9 @@ const composio = new Composio({|------|------|-------------|| `authConfigs` | `AuthConfigs` | Manage authentication configurations for toolkits || `connectedAccounts` | `ConnectedAccounts` | Manage authenticated connections |+| `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.+Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools+should be exposed directly; see `ToolRouterCreateSessionConfig`. || `experimental` | `Experimental` | Experimental SDK methods whose shape may change in future releases.Prefer domain-specific mounts (for example`composio.connectedAccounts.updateAcl(...)`) when available; this@@ -64,12 +67,13 @@ at the top level. || `provider` | `TProvider` | The tool provider instance used for wrapping tools in framework-specific formats || `sessions` | `Sessions` | Create and reuse Composio sessions.-Use `composio.sessions.create(...)` to create a session and-`composio.sessions.use(...)` to reuse one. |+Prefer `composio.sessions.create(...)` for new code. The top-level+`composio.create(...)` method is kept as an alias. || `toolkits` | `Toolkits` | Retrieve toolkit metadata and authorize user connections || `toolRouter` | `ToolRouter` | Legacy alias for `composio.sessions`. || `tools` | `Tools` | List, retrieve, and execute tools || `triggers` | `Triggers` | Manage webhook triggers and event subscriptions |+| `use` | `(id: string, options: \{ customToolkits?: CustomToolkit[]; customTools?: CustomTool[]; mcp: true \}, requestOptions: ComposioRequestOptions) => Promise<Session>` | Use an existing tool router session |## Methodsdiff --git a/docs/content/reference/sdk-reference/typescript/mcp.mdx b/docs/content/reference/sdk-reference/typescript/mcp.mdxindex 5295ce50c..33bea9e0d 100644--- a/docs/content/reference/sdk-reference/typescript/mcp.mdx+++ b/docs/content/reference/sdk-reference/typescript/mcp.mdx@@ -4,7 +4,7 @@ description: "MCP (Model Control Protocol) class Handles MCP server operations.---<Callout type="warn" title="Deprecated">-Use a session's MCP endpoint instead: `composio.sessions.create(userId, \{ mcp: true \})`+Use a session's MCP endpoint instead: `composio.create(userId, \{ mcp: true \})`returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is nowopt-in per session; the standalone `composio.mcp` server-management API is kept only forbackwards compatibility. Prefer the session MCP endpoint; do not generate new code againstdiff --git a/docs/content/reference/sdk-reference/typescript/session.mdx b/docs/content/reference/sdk-reference/typescript/session.mdxindex 3d1b593a4..8f1727e2c 100644--- a/docs/content/reference/sdk-reference/typescript/session.mdx+++ b/docs/content/reference/sdk-reference/typescript/session.mdx@@ -1,6 +1,6 @@---title: "Session"-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."+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."---## Propertiesdiff --git a/docs/content/reference/sdk-reference/typescript/sessions.mdx b/docs/content/reference/sdk-reference/typescript/sessions.mdxindex 3bec04109..a08670b86 100644--- a/docs/content/reference/sdk-reference/typescript/sessions.mdx+++ b/docs/content/reference/sdk-reference/typescript/sessions.mdx@@ -1,6 +1,6 @@---title: "Sessions"-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."+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(...)`."---## Usagediff --git a/docs/content/reference/v3/api-reference/mcp/index.mdx b/docs/content/reference/v3/api-reference/mcp/index.mdxindex caa4d3a44..6a02813bb 100644--- a/docs/content/reference/v3/api-reference/mcp/index.mdx+++ b/docs/content/reference/v3/api-reference/mcp/index.mdx@@ -6,14 +6,14 @@ description: "MCP server management"{/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/mcp.mdx, not this file. */}<Callout type="warning">-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).+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).</Callout>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.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.-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).+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).## Endpointsdiff --git a/docs/content/reference/v3/api-reference/tool-router/index.mdx b/docs/content/reference/v3/api-reference/tool-router/index.mdxindex e6ff8547a..6f745664a 100644--- a/docs/content/reference/v3/api-reference/tool-router/index.mdx+++ b/docs/content/reference/v3/api-reference/tool-router/index.mdx@@ -11,7 +11,7 @@ These are Composio's session endpoints. A **session** is the runtime context youSessions were formerly called the "tool router", which is why these endpoints live under `tool_router`. They are the same thing.</Callout>-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.+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.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.diff --git a/docs/content/reference/v3/api-reference/webhook-subscriptions/index.mdx b/docs/content/reference/v3/api-reference/webhook-subscriptions/index.mdxindex ecdbe6af5..c04ad2241 100644--- a/docs/content/reference/v3/api-reference/webhook-subscriptions/index.mdx+++ b/docs/content/reference/v3/api-reference/webhook-subscriptions/index.mdx@@ -118,7 +118,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiReconst toolkit = payload.data.toolkit.slug;// Look up the user and send them a re-auth link- const session = await composio.sessions.create(lookupUser(accountId));+ const session = await composio.create(lookupUser(accountId));const connectionRequest = await session.authorize(toolkit);if (connectionRequest.redirectUrl) {notifyUser(connectionRequest.redirectUrl);diff --git a/docs/content/toolkits/managed-auth.mdx b/docs/content/toolkits/managed-auth.mdxindex 9714ff426..80b46feb5 100644--- a/docs/content/toolkits/managed-auth.mdx+++ b/docs/content/toolkits/managed-auth.mdx@@ -27,7 +27,7 @@ session = composio.create(user_id="user_123")import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");// Tools that need an account return a Connect Link automatically```</Tab>diff --git a/docs/decisions/llm-guardrails.md b/docs/decisions/llm-guardrails.mdindex 63b22dda3..450c9eb2b 100644--- a/docs/decisions/llm-guardrails.md+++ b/docs/decisions/llm-guardrails.md@@ -6,7 +6,7 @@ Inject invisible guardrail instructions into every `.md` response so AI code gen## Problem-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()`).+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()`).## Architecture@@ -29,7 +29,7 @@ Pages control which guardrails they get:| Frontmatter value | What gets appended ||---|---|-| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.sessions.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |+| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist || `llmGuardrails: "direct-execution"` | `DIRECT_EXECUTION_GUARDRAILS` — acknowledges direct execution is valid, but strongly recommends sessions unless user explicitly asks for it || `llmGuardrails: "none"` | Nothing |diff --git a/docs/lib/llm-guardrails/direct-execution.ts b/docs/lib/llm-guardrails/direct-execution.tsindex 26a63ae9f..941e2e70e 100644--- a/docs/lib/llm-guardrails/direct-execution.ts+++ b/docs/lib/llm-guardrails/direct-execution.ts@@ -10,7 +10,7 @@ export const DIRECT_EXECUTION_GUARDRAILS = `# Composio SDK — Instructions for AI Code Generators-**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.+**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.---diff --git a/docs/lib/llm-guardrails/session.ts b/docs/lib/llm-guardrails/session.tsindex 4918cffce..38dbe3d3d 100644--- a/docs/lib/llm-guardrails/session.ts+++ b/docs/lib/llm-guardrails/session.ts@@ -2,7 +2,7 @@ import { TERMINOLOGY_MIGRATION } from './terminology';/*** Default guardrails appended to most pages.- * Steers LLMs toward the session-based pattern (composio.sessions.create + session.tools).+ * Steers LLMs toward the session-based pattern (composio.create + session.tools).*/export const SESSION_GUARDRAILS = `@@ -26,7 +26,7 @@ Composio supports two integration modes: **Native Tools** (with a provider packafrom composio import Composiocomposio = Composio()-session = composio.sessions.create(user_id="user_123")+session = composio.create(user_id="user_123")tools = session.tools()# Pass tools to your agent/LLM framework\`\`\`@@ -36,7 +36,7 @@ tools = session.tools()import { Composio } from "@composio/core";const composio = new Composio();-const session = await composio.sessions.create("user_123");+const session = await composio.create("user_123");const tools = await session.tools();// Pass tools to your agent/LLM framework\`\`\`@@ -53,10 +53,10 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie### 2.1 — ALWAYS DO THE FOLLOWING-1. **Use \`composio.sessions.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.+1. **Use \`composio.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.2. **Use \`session.tools()\`** for native tool integration or **\`session.mcp.url\`** for MCP integration.3. **Import** from the correct provider package (\`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript).-4. **Pass \`user_id\` to \`composio.sessions.create()\`**, not to individual tool calls.+4. **Pass \`user_id\` to \`composio.create()\`**, not to individual tool calls.### 2.2 — NEVER DO THE FOLLOWINGdiff --git a/docs/lib/local-workbench-build.ts b/docs/lib/local-workbench-build.tsindex 69056ded4..93a145221 100644--- a/docs/lib/local-workbench-build.ts+++ b/docs/lib/local-workbench-build.ts@@ -49,7 +49,7 @@ const stage3 = `${stage2}// session to the helper, which validates it's local and gives you the pieces to// run code yourself, wherever you choose.async function createWorkbench() {- const session = await composio.sessions.create(userId, {+ const session = await composio.create(userId, {toolkits: ['github'],workbench: { enable: false },});diff --git a/docs/lib/local-workbench-source.json b/docs/lib/local-workbench-source.jsonindex 30a30361a..5f18cc7ea 100644--- a/docs/lib/local-workbench-source.json+++ b/docs/lib/local-workbench-source.json@@ -11,7 +11,7 @@},{"path": "src/workbench.ts",-"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",+"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","composio": true},{diff --git a/docs/lib/slack-bot-build.ts b/docs/lib/slack-bot-build.tsindex 0eb93914a..cfad7f832 100644--- a/docs/lib/slack-bot-build.ts+++ b/docs/lib/slack-bot-build.ts@@ -68,7 +68,7 @@ async function runPi(tools: unknown, prompt: string) {const runAgent = `// The smallest agent: one session, its tools, one prompt.export async function runAgent(userId: string, prompt: string) {- const session = await composio.sessions.create(userId);+ const session = await composio.create(userId);const tools = piProvider.createSessionTools({sessionId: session.sessionId,search: (params) => session.search(params),@@ -88,9 +88,9 @@ const threadKey = (event: IncomingTriggerPayload) =>async function sessionForThread(event: IncomingTriggerPayload) {const key = threadKey(event);const existing = threads.get(key);- if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };+ if (existing) return { session: await composio.use(existing.sessionId), memory: existing };- const session = await composio.sessions.create(event.userId, {+ const session = await composio.create(event.userId, {manageConnections: { enable: true, callbackUrl, waitForConnections: true },});const memory = { sessionId: session.sessionId, history: [] as { role: string; content: string }[] };@@ -109,9 +109,9 @@ const threadKey = (event: IncomingTriggerPayload) =>async function sessionForThread(event: IncomingTriggerPayload) {const key = threadKey(event);const existing = threads.get(key);- if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };+ if (existing) return { session: await composio.use(existing.sessionId), memory: existing };- const session = await composio.sessions.create(event.userId, {+ const session = await composio.create(event.userId, {// Pin the shared Slack connection; the session still resolves every other// toolkit against this user's own connections.connectedAccounts: { slackbot: [SHARED_SLACK_CONNECTION_ID] },@@ -345,7 +345,7 @@ const authConfig = await composio.authConfigs.create('slackbot', {const installAuthorize = `// One connection for the whole workspace: authorize it as SHARED.-const setup = await composio.sessions.create('setup:workspace-bot', {+const setup = await composio.create('setup:workspace-bot', {toolkits: ['slackbot'],authConfigs: { slackbot: authConfig.id },manageConnections: true,diff --git a/docs/lib/slack-bot-source.json b/docs/lib/slack-bot-source.jsonindex 60ed659a6..a2ca03d82 100644--- a/docs/lib/slack-bot-source.json+++ b/docs/lib/slack-bot-source.json@@ -12,12 +12,12 @@{"path": "src/composio/slackbot-setup.ts","composio": true,-"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"+"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"},{"path": "src/composio/routing-with-pi-provider.ts","composio": true,-"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"+"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"},{"path": "src/agent/slack-composio-agent.ts",@@ -32,7 +32,7 @@{"path": "src/slack/transport.ts","composio": true,-"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"+"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"},{"path": "src/slack/acl.ts",diff --git a/docs/lib/standup-bot-build.ts b/docs/lib/standup-bot-build.tsindex bad98cb4c..11c597182 100644--- a/docs/lib/standup-bot-build.ts+++ b/docs/lib/standup-bot-build.ts@@ -24,7 +24,7 @@ const AUTH_CONFIG = process.env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID!;// Connect the bot's own Slack app once, so it can post and DM as the bot.async function main() {- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {authConfigs: { slackbot: AUTH_CONFIG },});@@ -46,7 +46,7 @@ const AUTH_CONFIG = process.env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID!;// Connect the bot's own Slack app once, so it can post and DM as the bot.async function main() {- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {authConfigs: { slackbot: AUTH_CONFIG },});@@ -152,7 +152,7 @@ const TOOLKITS = ['github', 'linear', 'notion', 'googlecalendar', 'slack'];// write their standup. session.tools() returns Composio's research meta-tools// (search / execute / workbench), scoped to those toolkits.export async function generateDraft(memberEmail: string) {- const session = await composio.sessions.create(memberEmail, { toolkits: TOOLKITS });+ const session = await composio.create(memberEmail, { toolkits: TOOLKITS });const tools = await session.tools();const { text } = await generateText({@@ -186,7 +186,7 @@ export async function generateDraft(memberEmail: string) {// manageConnections:false strips the connection meta-tools. The agent drafts// from whatever the member already connected and never starts an OAuth flow// mid-draft: if a tool needs auth, it's simply not in the session.- const session = await composio.sessions.create(memberEmail, {+ const session = await composio.create(memberEmail, {toolkits: TOOLKITS,manageConnections: false,});diff --git a/docs/lib/standup-bot-source.json b/docs/lib/standup-bot-source.jsonindex 7f8ba0296..43939637a 100644--- a/docs/lib/standup-bot-source.json+++ b/docs/lib/standup-bot-source.json@@ -26,7 +26,7 @@},{"path": "api/_utils/composio.ts",- "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",+ "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","composio": true},{@@ -46,7 +46,7 @@},{"path": "scripts/setup.ts",- "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",+ "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","composio": true}]diff --git a/ts/README.md b/ts/README.mdindex 136f0e1d5..fd6b2009a 100644--- a/ts/README.md+++ b/ts/README.md@@ -13,7 +13,7 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();```diff --git a/ts/docs/advanced/modifiers.md b/ts/docs/advanced/modifiers.mdindex 07ce8d9dd..fd6c2df9a 100644--- a/ts/docs/advanced/modifiers.md+++ b/ts/docs/advanced/modifiers.md@@ -575,7 +575,7 @@ import { SessionExecuteMetaModifiers } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'slack'],});diff --git a/ts/docs/api/tool-router-files.md b/ts/docs/api/tool-router-files.mdindex e9b5c6f16..87f3723ff 100644--- a/ts/docs/api/tool-router-files.md+++ b/ts/docs/api/tool-router-files.md@@ -23,7 +23,7 @@ Files are stored in a virtual filesystem attached to the session. Tools executinimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });-const session = await composio.sessions.create('default');+const session = await composio.create('default');// Upload a fileconst file = await session.experimental.files.upload('/path/to/report.pdf');diff --git a/ts/docs/api/tool-router.md b/ts/docs/api/tool-router.mdindex 353cd665f..65a13c289 100644--- a/ts/docs/api/tool-router.md+++ b/ts/docs/api/tool-router.md@@ -39,7 +39,7 @@ import { Composio } from '@composio/core';const composio = new Composio();// Create a session for a user with access to Gmail tools-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -60,7 +60,7 @@ const composio = new Composio({});// Create a session for a user with access to Gmail tools-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -72,7 +72,7 @@ const tools = await session.tools();### Basic Session Creation-Use `composio.sessions.create()` to create a new Tool Router session:+Use `composio.create()` to create a new Tool Router session:```typescriptimport { Composio } from '@composio/core';@@ -80,7 +80,7 @@ import { Composio } from '@composio/core';const composio = new Composio();// Create a session with Gmail access-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -90,10 +90,10 @@ console.log('MCP URL:', session.mcp.url);### Using an Existing Session-If you have an existing session ID, you can retrieve it using `composio.sessions.use()`:+If you have an existing session ID, you can retrieve it using `composio.use()`:```typescript-const session = await composio.sessions.use('existing_session_id');+const session = await composio.use('existing_session_id');// Access session propertiesconsole.log(session.sessionId);@@ -110,17 +110,17 @@ Specify which toolkits to enable or disable in the session.```typescript// Simple array of toolkit slugs to enable-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'slack', 'github'],});// Explicit enabled configuration-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: { enable: ['gmail', 'slack'] },});// Disable specific toolkits (enable all others)-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: { disable: ['calendar'] },});```@@ -130,7 +130,7 @@ const session = await composio.sessions.create('user_123', {Fine-grained control over which tools are available within toolkits. Configure tools per toolkit using the toolkit slug as the key.```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'slack'],tools: {// Configure tools per toolkit@@ -150,7 +150,7 @@ const session = await composio.sessions.create('user_123', {Global tags to filter tools by their behavior hints. Tags can be overridden per toolkit in the `tools` configuration.```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'github'],// Global tags applied to all toolkitstags: ['readOnlyHint', 'idempotentHint'],@@ -169,7 +169,7 @@ Available tags:Map toolkits to specific authentication configurations:```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'github'],authConfigs: {gmail: 'ac_gmail_work',@@ -183,7 +183,7 @@ const session = await composio.sessions.create('user_123', {Map toolkits to specific connected account IDs:```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],connectedAccounts: {gmail: 'ca_abc123',@@ -197,13 +197,13 @@ Control how connections are managed within the session:```typescript// Boolean: enable/disable automatic connection management-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],manageConnections: true, // default});// Object: fine-grained control-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],manageConnections: {enable: true,@@ -218,7 +218,7 @@ const session = await composio.sessions.create('user_123', {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.```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'slack'],manageConnections: {enable: true,@@ -234,7 +234,7 @@ Configure workbench behavior for tool execution:```typescript// Disable workbench entirely — no code execution tools in the session-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],workbench: {enable: false@@ -242,7 +242,7 @@ const session = await composio.sessions.create('user_123', {});// Fine-tune workbench settings-const session2 = await composio.sessions.create('user_123', {+const session2 = await composio.create('user_123', {toolkits: ['gmail'],workbench: {enable: true, // default@@ -265,7 +265,7 @@ Configure experimental features for the session. These features are not stable a#### Assistive Prompt```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],experimental: {assistivePrompt: {@@ -340,7 +340,7 @@ const devTools = experimental_createToolkit('DEV_TOOLS', {**Creating a session with custom tools:**```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],experimental: {customTools: [grep, getImportant],@@ -583,7 +583,7 @@ const composio = new Composio({provider: new VercelProvider(),});-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -613,7 +613,7 @@ import { stepCountIs, streamText } from 'ai';// No provider needed when using MCPconst composio = new Composio();-const { mcp } = await composio.sessions.create('user_123', {+const { mcp } = await composio.create('user_123', {toolkits: ['gmail'],manageConnections: true,tools: {@@ -670,7 +670,7 @@ const llm = new ChatOpenAI({model: 'gpt-4o',});-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -709,7 +709,7 @@ import { Composio } from '@composio/core';// No provider needed when using MCPconst composio = new Composio();-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -752,7 +752,7 @@ import { Composio } from '@composio/core';// No provider needed when using MCPconst composio = new Composio();-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -786,7 +786,7 @@ When a user needs to connect a toolkit, use the `authorize()` method:import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],});@@ -817,7 +817,7 @@ Use the `toolkits()` method to check connection states:import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');// Get all toolkitsconst toolkits = await session.toolkits();@@ -910,13 +910,13 @@ These types include the `sessionId` in their parameters, allowing you to track a```typescript// Store session ID after creation-const session = await composio.sessions.create('user_123', config);+const session = await composio.create('user_123', config);await redis.set(`session:user_123`, session.sessionId);// Retrieve existing sessionconst sessionId = await redis.get(`session:user_123`);if (sessionId) {- const session = await composio.sessions.use(sessionId);+ const session = await composio.use(sessionId);}```@@ -1046,7 +1046,7 @@ interface SessionExecuteMetaModifiers {The new `waitForConnections` property allows sessions to wait for users to complete authentication before proceeding:```typescript-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail', 'slack'],manageConnections: {enable: true,diff --git a/ts/docs/core-concepts.md b/ts/docs/core-concepts.mdindex f96fd8c58..35ae0a07d 100644--- a/ts/docs/core-concepts.md+++ b/ts/docs/core-concepts.md@@ -402,7 +402,7 @@ Use direct execution when:## Custom Tools-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`.+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`.```typescriptimport { Composio, experimental_createTool } from '@composio/core';@@ -422,7 +422,7 @@ const customTool = experimental_createTool('MY_CUSTOM_TOOL', {},});-const session = await composio.sessions.create('default', {+const session = await composio.create('default', {experimental: { customTools: [customTool] },});diff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.mdindex 0655524cd..a883ea0b8 100644--- a/ts/docs/getting-started.md+++ b/ts/docs/getting-started.md@@ -305,7 +305,7 @@ const customTool = experimental_createTool('WEATHER_FORECAST', {},});-const session = await composio.sessions.create('default', {+const session = await composio.create('default', {experimental: { customTools: [customTool] },});diff --git a/ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/src/index.ts b/ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/src/index.tsindex fd3139a76..a66c3d40c 100644--- a/ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/src/index.ts+++ b/ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/src/index.ts@@ -55,7 +55,7 @@ app.get('/test/mcp-client', async c => {provider: new VercelProvider(),});- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {toolkits: ['hackernews'],manageConnections: true,tools: {@@ -98,7 +98,7 @@ app.get('/test/agent', async c => {provider: new VercelProvider(),});- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {toolkits: ['hackernews'],manageConnections: true,preload: { tools: ['HACKERNEWS_GET_USER'] },diff --git a/ts/e2e-tests/runtimes/node/custom-tools/fixtures/index.mjs b/ts/e2e-tests/runtimes/node/custom-tools/fixtures/index.mjsindex 6b3c3ce77..d006e9c10 100644--- a/ts/e2e-tests/runtimes/node/custom-tools/fixtures/index.mjs+++ b/ts/e2e-tests/runtimes/node/custom-tools/fixtures/index.mjs@@ -91,7 +91,7 @@ const composio = new Composio({ apiKey });async function main() {const userId = `e2e-custom-tools-${Date.now()}`;- const session = await composio.sessions.create(userId, {+ const session = await composio.create(userId, {toolkits: ['weathermap'],manageConnections: false,experimental: {diff --git a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/e2e.test.ts b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/e2e.test.tsindex 27372786f..429005f12 100644--- a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/e2e.test.ts+++ b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v3/e2e.test.ts@@ -42,7 +42,7 @@ e2e(import.meta.url, {it('should work with Tool Router',async () => {- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {toolkits: ['hackernews'],mcp: true,manageConnections: true,diff --git a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/e2e.test.ts b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/e2e.test.tsindex 892d40018..85947efe5 100644--- a/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/e2e.test.ts+++ b/ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v4/e2e.test.ts@@ -42,7 +42,7 @@ e2e(import.meta.url, {it('should work with Tool Router',async () => {- const session = await composio.sessions.create('default', {+ const session = await composio.create('default', {toolkits: ['hackernews'],mcp: true,manageConnections: true,diff --git a/ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjs b/ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjsindex b170ef2fa..42dbc125a 100644--- a/ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjs+++ b/ts/e2e-tests/runtimes/node/tool-router-files/fixtures/index.mjs@@ -19,7 +19,7 @@ function isStorageUploadUnavailable(err) {async function main() {// Create a session (hackernews is public, no auth needed; files mount is always available)- const session = await composio.sessions.create('e2e-tool-router-files-user', {+ const session = await composio.create('e2e-tool-router-files-user', {toolkits: ['hackernews'],manageConnections: false,});diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs b/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjsindex eb5132c19..81b9e034d 100644--- a/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs@@ -21,7 +21,7 @@ const composio = new Composio({ apiKey });async function main() {const userId = `e2e-tool-router-pagination-${Date.now()}`;- const session = await composio.sessions.create(userId);+ const session = await composio.create(userId);const page1 = await session.toolkits({ limit: 2 });if (page1.items.length !== 2) {diff --git a/ts/examples/tool-router/src/authorize.ts b/ts/examples/tool-router/src/authorize.tsindex c90e52c5e..d7226864a 100644--- a/ts/examples/tool-router/src/authorize.ts+++ b/ts/examples/tool-router/src/authorize.ts@@ -1,7 +1,7 @@import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create('user_123', { toolkits: ['gmail'] });+const session = await composio.create('user_123', { toolkits: ['gmail'] });const connectionRequest = await session.authorize("gmail", {callbackUrl: "https://google.com"});diff --git a/ts/examples/tool-router/src/claude-agent-sdk.ts b/ts/examples/tool-router/src/claude-agent-sdk.tsindex c4cb92e17..d43279577 100644--- a/ts/examples/tool-router/src/claude-agent-sdk.ts+++ b/ts/examples/tool-router/src/claude-agent-sdk.ts@@ -4,7 +4,7 @@ import 'dotenv/config';const composio = new Composio();-const session = await composio.sessions.create('user_123', { toolkits: ['gmail'], mcp: true });+const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true });const stream = await query({prompt: 'Use composio tools to fetch my last email from gmail',diff --git a/ts/examples/tool-router/src/custom-tools-agent.ts b/ts/examples/tool-router/src/custom-tools-agent.tsindex c1ea6c6cd..c51bbf287 100644--- a/ts/examples/tool-router/src/custom-tools-agent.ts+++ b/ts/examples/tool-router/src/custom-tools-agent.ts@@ -175,8 +175,8 @@ const composio = new Composio({const existingSessionId = process.env.COMPOSIO_SESSION_ID;const session = existingSessionId- ? await composio.sessions.use(existingSessionId, { customTools, customToolkits })- : await composio.sessions.create("custom-tools-agent-user", {+ ? await composio.use(existingSessionId, { customTools, customToolkits })+ : await composio.create("custom-tools-agent-user", {toolkits: ["weathermap", "gmail"],manageConnections: false,experimental: {diff --git a/ts/examples/tool-router/src/custom-tools-e2e.ts b/ts/examples/tool-router/src/custom-tools-e2e.tsindex 494bc4631..e0e05f9ba 100644--- a/ts/examples/tool-router/src/custom-tools-e2e.ts+++ b/ts/examples/tool-router/src/custom-tools-e2e.ts@@ -154,9 +154,9 @@ async function main() {console.log(`Base URL: ${baseURL ?? "(default)"}\n`);// ── Session creation with all 3 tool types ──- let session: Awaited<ReturnType<typeof composio.sessions.create>>;+ let session: Awaited<ReturnType<typeof composio.create>>;try {- session = await composio.sessions.create(userId, {+ session = await composio.create(userId, {toolkits: ["weathermap", "gmail"],manageConnections: false,experimental: {@@ -173,7 +173,7 @@ async function main() {// ── Existing session reuse with local custom definitions ──try {- const reusedSession = await composio.sessions.use(session.sessionId, { customTools, customToolkits });+ const reusedSession = await composio.use(session.sessionId, { customTools, customToolkits });const result = await reusedSession.execute("GET_USER_DETAILS", { user_id: "user-1" });if (result.data?.name !== "Alice Johnson") throw new Error(`Unexpected: ${JSON.stringify(result.data)}`);ok("Use: existing session binds custom tools for local execution");diff --git a/ts/examples/tool-router/src/custom-tools.ts b/ts/examples/tool-router/src/custom-tools.tsindex 1c9d31dce..05975a661 100644--- a/ts/examples/tool-router/src/custom-tools.ts+++ b/ts/examples/tool-router/src/custom-tools.ts@@ -89,7 +89,7 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});-const session = await composio.sessions.create("default", {+const session = await composio.create("default", {toolkits: ["gmail"],experimental: {customTools: [getUser, createDraft],diff --git a/ts/examples/tool-router/src/direct-tools-preset.ts b/ts/examples/tool-router/src/direct-tools-preset.tsindex 304f7f3c4..dfa820a17 100644--- a/ts/examples/tool-router/src/direct-tools-preset.ts+++ b/ts/examples/tool-router/src/direct-tools-preset.ts@@ -59,7 +59,7 @@ const hnResearch = experimental_createToolkit('HN_RESEARCH', {tools: [getUserNote],});-const session = await composio.sessions.create('direct-tools-example-user', {+const session = await composio.create('direct-tools-example-user', {sessionPreset: SessionPreset.DIRECT_TOOLS,toolkits: ['hackernews'],tools: {diff --git a/ts/examples/tool-router/src/index.ts b/ts/examples/tool-router/src/index.tsindex 63bbe5bd0..df109c4b2 100644--- a/ts/examples/tool-router/src/index.ts+++ b/ts/examples/tool-router/src/index.ts@@ -7,7 +7,7 @@ import { modifiers } from './logger';const composio = new Composio({provider: new VercelProvider(),});-const session = await composio.sessions.create('user_123', { toolkits: ['gmail'] });+const session = await composio.create('user_123', { toolkits: ['gmail'] });const tools = await session.tools(modifiers);diff --git a/ts/examples/tool-router/src/langchain.ts b/ts/examples/tool-router/src/langchain.tsindex 5050ee4d2..8eae65e07 100644--- a/ts/examples/tool-router/src/langchain.ts+++ b/ts/examples/tool-router/src/langchain.ts@@ -12,7 +12,7 @@ const llm = new ChatOpenAI({});async function main() {- const session = await composio.sessions.create('user_123', { toolkits: ['gmail'], mcp: true });+ const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true });const client = new MultiServerMCPClient({math: {diff --git a/ts/examples/tool-router/src/mcp.ts b/ts/examples/tool-router/src/mcp.tsindex 2eb6e2ea3..edb5d83b7 100644--- a/ts/examples/tool-router/src/mcp.ts+++ b/ts/examples/tool-router/src/mcp.ts@@ -6,7 +6,7 @@ import ora from 'ora';const composio = new Composio();const trProgress = ora('Creating tool router session...').start();-const { mcp } = await composio.sessions.create('default', {+const { mcp } = await composio.create('default', {toolkits: ['gmail'],manageConnections: true,mcp: true,diff --git a/ts/examples/tool-router/src/multi-account.ts b/ts/examples/tool-router/src/multi-account.tsindex 3e632d69e..88993ca03 100644--- a/ts/examples/tool-router/src/multi-account.ts+++ b/ts/examples/tool-router/src/multi-account.ts@@ -9,7 +9,7 @@ const composio = new Composio({// Enable multi-account mode so the user can connect multiple accounts// per toolkit (e.g. two Gmail accounts).-const session = await composio.sessions.create('user_123', {+const session = await composio.create('user_123', {toolkits: ['gmail'],multiAccount: {enable: true,diff --git a/ts/examples/tool-router/src/openai-agents.ts b/ts/examples/tool-router/src/openai-agents.tsindex fe6f6ff75..9928aad40 100644--- a/ts/examples/tool-router/src/openai-agents.ts+++ b/ts/examples/tool-router/src/openai-agents.ts@@ -3,7 +3,7 @@ import { Agent, hostedMcpTool, run } from '@openai/agents';import { createInterface } from 'node:readline/promises';const composio = new Composio();-const { mcp } = await composio.sessions.create('default', { mcp: true });+const { mcp } = await composio.create('default', { mcp: true });const agent = new Agent({name: 'Personal Assistant',diff --git a/ts/examples/tool-router/src/preload.ts b/ts/examples/tool-router/src/preload.tsindex 7d9ce0339..5c33b757c 100644--- a/ts/examples/tool-router/src/preload.ts+++ b/ts/examples/tool-router/src/preload.ts@@ -112,7 +112,7 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});-const session = await composio.sessions.create('preload-example-user', {+const session = await composio.create('preload-example-user', {toolkits: ['hackernews'],tools: {hackernews: {diff --git a/ts/examples/tool-router/src/session-update.ts b/ts/examples/tool-router/src/session-update.tsindex b8c8a16db..999810ef5 100644--- a/ts/examples/tool-router/src/session-update.ts+++ b/ts/examples/tool-router/src/session-update.ts@@ -16,7 +16,7 @@ const composio = new Composio({});// Create a session with gmail only-const session = await composio.sessions.create("session-update-demo", {+const session = await composio.create("session-update-demo", {toolkits: ["gmail"],manageConnections: false,});diff --git a/ts/examples/tool-router/src/toolkits.ts b/ts/examples/tool-router/src/toolkits.tsindex 1b927e3d9..ea853f7a5 100644--- a/ts/examples/tool-router/src/toolkits.ts+++ b/ts/examples/tool-router/src/toolkits.ts@@ -2,7 +2,7 @@ import { Composio } from '@composio/core';const composio = new Composio();-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const toolkits = await session.toolkits({ toolkits: ["github"]});diff --git a/ts/examples/triggers/src/test.ts b/ts/examples/triggers/src/test.tsindex 56b383fc2..0df24d75f 100644--- a/ts/examples/triggers/src/test.ts+++ b/ts/examples/triggers/src/test.ts@@ -4,7 +4,7 @@ const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,});-const session = await composio.sessions.create('userId', {+const session = await composio.create('userId', {experimental: {assistivePrompt: {userTimezone: 'America/New_York',diff --git a/ts/examples/vercel/src/tool-router-ai.ts b/ts/examples/vercel/src/tool-router-ai.tsindex bacbd39c8..476a9b033 100644--- a/ts/examples/vercel/src/tool-router-ai.ts+++ b/ts/examples/vercel/src/tool-router-ai.ts@@ -11,7 +11,7 @@ const composio = new Composio({// 2. Create an MCP sessionconsole.log('🔄 Creating toolrouter session...');-const session = await composio.sessions.create('default', {+const session = await composio.create('default', {toolkits: ['gmail'],manageConnections: true,mcp: true,diff --git a/ts/packages/core/README.md b/ts/packages/core/README.mdindex 796a13706..4f36d7343 100644--- a/ts/packages/core/README.md+++ b/ts/packages/core/README.md@@ -20,7 +20,7 @@ import { Composio } from '@composio/core';const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });// Each session is scoped to one of your users-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();```@@ -29,7 +29,7 @@ By default a session gives your agent a small set of meta tools that discover, aSessions persist on the server. For multi-turn conversations, store `session.sessionId` and reuse it instead of calling `create()` again:```typescript-const session = await composio.sessions.use(sessionId);+const session = await composio.use(sessionId);```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';const composio = new Composio({ provider: new OpenAIAgentsProvider() });-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools(); // ready to pass to the OpenAI Agents SDK```@@ -55,7 +55,7 @@ Adapters exist for OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel AIEvery 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:```typescript-const session = await composio.sessions.create('user_123', { mcp: true });+const session = await composio.create('user_123', { mcp: true });console.log(session.mcp.url);console.log(session.mcp.headers);diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.tsindex aa8a017a7..cbf69364c 100644--- a/ts/packages/core/src/composio.ts+++ b/ts/packages/core/src/composio.ts@@ -15,6 +15,7 @@ import { checkForLatestVersionFromNPM } from './utils/version';import { OpenAIProvider } from './provider/OpenAIProvider';import { version } from '../package.json';import type { ComposioRequestHeaders } from './types/composio.types';+import type { ComposioRequestOptions } from './types/requestOptions.types';import { Files } from '#files';import { getDefaultHeaders } from './utils/session';import { ToolkitVersionParam } from './types/tool.types';@@ -206,7 +207,7 @@ export class Composio<experimental: Experimental;/*** Model Context Protocol server management.- * @deprecated Use a session's MCP endpoint instead: `composio.sessions.create(userId, { mcp: true })`+ * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`* returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now opt-in* per session; this standalone server-management API is kept only for backwards compatibility.* Prefer the session MCP endpoint; do not generate new code against `composio.mcp`.@@ -216,8 +217,8 @@ export class Composio</*** Create and reuse Composio sessions.*- * Use `composio.sessions.create(...)` to create a session and- * `composio.sessions.use(...)` to reuse one.+ * Prefer `composio.sessions.create(...)` for new code. The top-level+ * `composio.create(...)` method is kept as an alias.*/sessions: Sessions<unknown, unknown, TProvider>;/**@@ -225,6 +226,51 @@ export class Composio<* @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`.*/toolRouter: ToolRouter<unknown, unknown, TProvider>;+ /**+ * Creates a new tool router session for a user.+ * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools+ * should be exposed directly; see `ToolRouterCreateSessionConfig`.+ *+ * @param userId {string} The user id to create the session for+ * @param config {ToolRouterConfig} The config for the tool router session+ * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session+ *+ * @example+ * ```typescript+ * import { Composio } from '@composio/core';+ *+ * const composio = new Composio();+ * const userId = 'user_123';+ *+ * const session = await composio.sessions.create(userId, {+ * manageConnections: true,+ * });+ *+ * // Backwards-compatible alias:+ * const same = await composio.create(userId, {+ * manageConnections: true,+ * });+ *+ * console.log(session.sessionId);+ * console.log(session.url);+ * console.log(session.tools());+ * ```+ */+ create: Sessions<unknown, unknown, TProvider>['create'];++ /**+ * Use an existing tool router session+ *+ * @param id {string} The id of the session to use+ * @param options {object} Custom tools / toolkits to attach to the session+ * @param requestOptions {ComposioRequestOptions} Per-request cancellation+ * options. The supplied AbortSignal aborts the underlying session+ * retrieve/attach call only. Subsequent session method calls accept+ * their own per-call requestOptions.+ * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session+ */+ use: Sessions<unknown, unknown, TProvider>['use'];+/*** Creates a new instance of the Composio SDK.*@@ -318,6 +364,16 @@ export class Composio<this.sessions = new Sessions(this.client, this.config);this.toolRouter = this.sessions;+ /**+ * Initialize session aliases.+ * Properly bind the methods to maintain the correct 'this' context.+ */+ // Cast: Function.prototype.bind collapses the create/use overloads to a+ // single signature; re-assert the overloaded type. Runtime behaviour is+ // unchanged — bind only rebinds `this`.+ this.create = this.sessions.create.bind(this.sessions) as Composio<TProvider>['create'];+ this.use = this.sessions.use.bind(this.sessions) as Composio<TProvider>['use'];+/*** Initialize the client telemetry.*/diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex 1177b2d0a..0dc6ecd68 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -100,7 +100,7 @@ function validateSlugLength(* Create a custom tool for use in tool router sessions.** The returned object is a lightweight reference containing the tool's metadata- * and execute function. Pass it to `composio.sessions.create(userId, { experimental: { customTools: [...] } })`+ * and execute function. Pass it to `composio.create(userId, { experimental: { customTools: [...] } })`* to bind it to a session.** Just return the result data from `execute`, or throw an error.diff --git a/ts/packages/core/src/models/MCP.ts b/ts/packages/core/src/models/MCP.tsindex 1cce7d418..506139858 100644--- a/ts/packages/core/src/models/MCP.ts+++ b/ts/packages/core/src/models/MCP.ts@@ -45,7 +45,7 @@ function transformMCPItemResponse(response: McpUpdateResponse | McpRetrieveRespo* Handles MCP server operations.* When `config.experimental.mcp` is enabled, this class augments the features of `composio.mcp`.*- * @deprecated Use a session's MCP endpoint instead: `composio.sessions.create(userId, { mcp: true })`+ * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`* returns a session that exposes `session.mcp.url` / `session.mcp.headers`. MCP is now* opt-in per session; the standalone `composio.mcp` server-management API is kept only for* backwards compatibility. Prefer the session MCP endpoint; do not generate new code againstdiff --git a/ts/packages/core/src/models/Sessions.ts b/ts/packages/core/src/models/Sessions.tsindex 775e7140a..267b3cce9 100644--- a/ts/packages/core/src/models/Sessions.ts+++ b/ts/packages/core/src/models/Sessions.ts@@ -6,8 +6,9 @@ import { ToolRouter } from './ToolRouter';/*** First-class API for creating and reusing Composio sessions.*- * Use `composio.sessions.create(...)` to create a session and- * `composio.sessions.use(...)` to reuse one.+ * `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(...)`.*/export class Sessions<TToolCollection,diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex efb6ed992..e9ebeac6e 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -94,7 +94,8 @@ const AuthorizeOptionsSchema = z.object({/*** A Composio session — the object returned by `composio.sessions.create(...)`- * and `composio.sessions.use(...)`.+ * 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 isdiff --git a/ts/packages/core/src/provider/BaseProvider.ts b/ts/packages/core/src/provider/BaseProvider.tsindex e633fe254..703619f8c 100644--- a/ts/packages/core/src/provider/BaseProvider.ts+++ b/ts/packages/core/src/provider/BaseProvider.ts@@ -62,15 +62,13 @@ abstract class BaseProvider<TMcpResponse> {/*** @public- * Optional method to transform an MCP URL response into a provider-specific- * format. Providers can override this method to define custom transformation- * logic for MCP server responses.- *- * This is the stable base-provider SPI method for MCP responses in v1. (A- * prior `@deprecated` note pointed at a plural `wrapMcpServers` method that- * was never added; the singular method is the frozen contract.)+ * @deprecated: Will be removed in a future version, once the `experimental.mcp` flag is stabilized. Use `wrapMcpServers` instead.+ * Optional method to transform MCP URL response into provider-specific format.+ * Providers can override this method to define custom transformation logic+ * for MCP server responses.** @param data - The MCP URL response data+* @returns Transformed response in provider-specific format, or undefined to use default transformation*/wrapMcpServerResponse?(data: McpUrlResponse): TMcpResponse;diff --git a/ts/packages/core/src/types/customTool.types.ts b/ts/packages/core/src/types/customTool.types.tsindex 1ab61ca9d..fb358e35e 100644--- a/ts/packages/core/src/types/customTool.types.ts+++ b/ts/packages/core/src/types/customTool.types.ts@@ -115,7 +115,7 @@ export type CreateCustomToolParams<T extends AnyZodSchema> = z.infer</*** Custom tool definition returned from `createCustomTool()`.- * Pass to `composio.sessions.create(userId, { experimental: { customTools: [...] } })` to bind to a session.+ * Pass to `composio.create(userId, { experimental: { customTools: [...] } })` to bind to a session.*/export interface CustomTool {readonly slug: string;@@ -173,7 +173,7 @@ export type CreateCustomToolkitParams = z.infer<typeof CreateCustomToolkitBaseSc/*** Custom toolkit definition returned from `createCustomToolkit()`.- * Pass to `composio.sessions.create(userId, { experimental: { customToolkits: [...] } })`.+ * Pass to `composio.create(userId, { experimental: { customToolkits: [...] } })`.*/export interface CustomToolkit {readonly slug: string;diff --git a/ts/packages/core/test/core/session.test.ts b/ts/packages/core/test/core/session.test.tsindex 80e3902da..663fda647 100644--- a/ts/packages/core/test/core/session.test.ts+++ b/ts/packages/core/test/core/session.test.ts@@ -110,7 +110,7 @@ describe('Composio Session Management', () => {});});- it('should expose sessions.create without bare root aliases', async () => {+ it('should expose sessions.create and keep composio.create as a bound alias', async () => {const composio = new Composio(baseConfig);const client = composio.getClient() as any;client.toolRouter.session.create = vi.fn().mockResolvedValue({@@ -127,16 +127,21 @@ describe('Composio Session Management', () => {expect(composio.toolRouter).toBe(composio.sessions);- const session = await composio.sessions.create('user_123');+ const sessionFromCanonicalApi = await composio.sessions.create('user_123');+ const sessionFromAlias = await composio.create('user_456');expect(client.toolRouter.session.create).toHaveBeenNthCalledWith(1,expect.objectContaining({ user_id: 'user_123' }),undefined);- expect(session.sessionId).toBe('session_123');- expect(composio).not.toHaveProperty('create');- expect(composio).not.toHaveProperty('use');+ expect(client.toolRouter.session.create).toHaveBeenNthCalledWith(+ 2,+ expect.objectContaining({ user_id: 'user_456' }),+ undefined+ );+ expect(sessionFromCanonicalApi.sessionId).toBe('session_123');+ expect(sessionFromAlias.sessionId).toBe('session_123');});});diff --git a/ts/packages/core/type-tests/sessions-mcp.test-d.ts b/ts/packages/core/type-tests/sessions-mcp.test-d.tsindex 035df3fc3..0b318b75e 100644--- a/ts/packages/core/type-tests/sessions-mcp.test-d.ts+++ b/ts/packages/core/type-tests/sessions-mcp.test-d.ts@@ -13,7 +13,7 @@ declare const composio: Composio;async function createGating(): Promise<void> {// Default: no `{ mcp: true }` → `session.mcp` is NOT in the type.- const session = await composio.sessions.create('user_123');+ const session = await composio.create('user_123');// @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passedvoid session.mcp;@@ -21,17 +21,17 @@ async function createGating(): Promise<void> {await session.tools();// Opt-in: `{ mcp: true }` → `session.mcp` is surfaced.- const mcpSession = await composio.sessions.create('user_123', { mcp: true });+ const mcpSession = await composio.create('user_123', { mcp: true });const _url: string = mcpSession.mcp.url;void _url;}async function useGating(): Promise<void> {- const session = await composio.sessions.use('session_123');+ const session = await composio.use('session_123');// @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passedvoid session.mcp;- const mcpSession = await composio.sessions.use('session_123', { mcp: true });+ const mcpSession = await composio.use('session_123', { mcp: true });const _url: string = mcpSession.mcp.url;void _url;}@@ -41,21 +41,13 @@ async function useGating(): Promise<void> {// The `{ mcp: true }` overload refactor previously dropped this from `create()`.async function requestOptionsArg(): Promise<void> {const ctrl = new AbortController();- await composio.sessions.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });- await composio.sessions.create('user_123', { mcp: true }, { signal: ctrl.signal });+ await composio.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });+ await composio.create('user_123', { mcp: true }, { signal: ctrl.signal });await composio.sessions.create('user_123', undefined, { signal: ctrl.signal });- await composio.sessions.use('session_123', { customTools: [] }, { signal: ctrl.signal });- await composio.sessions.use('session_123', { mcp: true }, { signal: ctrl.signal });-}--function bareSessionAliasesAreRemoved(): void {- // @ts-expect-error Session APIs are only available under `composio.sessions`.- void composio.create;- // @ts-expect-error Session APIs are only available under `composio.sessions`.- void composio.use;+ await composio.use('session_123', { customTools: [] }, { signal: ctrl.signal });+ await composio.use('session_123', { mcp: true }, { signal: ctrl.signal });}void createGating;void useGating;void requestOptionsArg;-void bareSessionAliasesAreRemoved;diff --git a/ts/packages/providers/anthropic/README.md b/ts/packages/providers/anthropic/README.mdindex 39d6cdb4e..c1865e2f8 100644--- a/ts/packages/providers/anthropic/README.md+++ b/ts/packages/providers/anthropic/README.md@@ -25,7 +25,7 @@ const composio = new Composio({const client = new Anthropic();// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const messages: Anthropic.MessageParam[] = [diff --git a/ts/packages/providers/claude-agent-sdk/README.md b/ts/packages/providers/claude-agent-sdk/README.mdindex 75f71b104..c48aace3a 100644--- a/ts/packages/providers/claude-agent-sdk/README.md+++ b/ts/packages/providers/claude-agent-sdk/README.md@@ -25,7 +25,7 @@ import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });// Each session is scoped to one of your users-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const customServer = createSdkMcpServer({@@ -49,7 +49,7 @@ for await (const stream of query({}```-For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.## How it worksdiff --git a/ts/packages/providers/cloudflare/README.md b/ts/packages/providers/cloudflare/README.mdindex 07f396877..4d65f386f 100644--- a/ts/packages/providers/cloudflare/README.md+++ b/ts/packages/providers/cloudflare/README.md@@ -26,7 +26,7 @@ export default {});// Create a session for your user- const session = await composio.sessions.create('user_123');+ const session = await composio.create('user_123');const tools = await session.tools();const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {diff --git a/ts/packages/providers/google/README.md b/ts/packages/providers/google/README.mdindex 1458ec17c..7ede63b34 100644--- a/ts/packages/providers/google/README.md+++ b/ts/packages/providers/google/README.md@@ -25,7 +25,7 @@ const composio = new Composio({const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const chat = ai.chats.create({diff --git a/ts/packages/providers/langchain/README.md b/ts/packages/providers/langchain/README.mdindex 1860de4ad..2e8720817 100644--- a/ts/packages/providers/langchain/README.md+++ b/ts/packages/providers/langchain/README.md@@ -27,7 +27,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const toolNode = new ToolNode(tools);diff --git a/ts/packages/providers/llamaindex/README.md b/ts/packages/providers/llamaindex/README.mdindex 38cbfbc9c..696a9ce58 100644--- a/ts/packages/providers/llamaindex/README.md+++ b/ts/packages/providers/llamaindex/README.md@@ -25,7 +25,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const myAgent = agent({diff --git a/ts/packages/providers/mastra/README.md b/ts/packages/providers/mastra/README.mdindex b32499337..6b28fe6af 100644--- a/ts/packages/providers/mastra/README.md+++ b/ts/packages/providers/mastra/README.md@@ -25,7 +25,7 @@ const composio = new Composio({});// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const agent = new Agent({diff --git a/ts/packages/providers/openai-agents/README.md b/ts/packages/providers/openai-agents/README.mdindex f8cab7ef4..6ec1e20d8 100644--- a/ts/packages/providers/openai-agents/README.md+++ b/ts/packages/providers/openai-agents/README.md@@ -25,7 +25,7 @@ import { Agent, run } from '@openai/agents';const composio = new Composio({ provider: new OpenAIAgentsProvider() });// Each session is scoped to one of your users-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const agent = new Agent({@@ -39,7 +39,7 @@ const result = await run(agent, 'Summarize my emails from today');console.log(result.finalOutput);```-For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.## Strict modediff --git a/ts/packages/providers/openai/README.md b/ts/packages/providers/openai/README.mdindex 7424449f0..943fd45f8 100644--- a/ts/packages/providers/openai/README.md+++ b/ts/packages/providers/openai/README.md@@ -25,7 +25,7 @@ const composio = new Composio({const client = new OpenAI();// Create a session for your user-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();let response = await client.responses.create({diff --git a/ts/packages/providers/vercel/README.md b/ts/packages/providers/vercel/README.mdindex 8a6566517..2b27e144e 100644--- a/ts/packages/providers/vercel/README.md+++ b/ts/packages/providers/vercel/README.md@@ -28,7 +28,7 @@ import { generateText, stepCountIs } from 'ai';const composio = new Composio({ provider: new VercelProvider() });// Each session is scoped to one of your users-const session = await composio.sessions.create('user_123');+const session = await composio.create('user_123');const tools = await session.tools();const { text } = await generateText({@@ -41,7 +41,7 @@ const { text } = await generateText({console.log(text);```-For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.## Strict mode