Skip to content

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

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

Alberto Schiabel0de52639c47f
diff --git a/.changeset/deprecate-session-aliases-freeze-mcp-spi.md b/.changeset/deprecate-session-aliases-freeze-mcp-spi.md
new file mode 100644
index 000000000..3ce449e82
--- /dev/null
+++ b/.changeset/deprecate-session-aliases-freeze-mcp-spi.md
@@ -0,0 +1,8 @@
+---
+'@composio/core': major
+---
+
+Two v1 freeze-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.
+- **Un-deprecate `BaseProvider.wrapMcpServerResponse`** and freeze it as the stable v1 SPI method. Its `@deprecated` note pointed at a plural `wrapMcpServers` method that was never added; the singular method is the frozen contract.
diff --git a/README.md b/README.md
index 11f101555..de45b5af9 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,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.create("user_123");
+const session = await composio.sessions.create("user_123");
const tools = await session.tools();
const agent = new Agent({
@@ -92,9 +92,9 @@ result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from t
print(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.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.
+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.
-**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).
+**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).
## CLI
diff --git a/docs/agent/instructions.md b/docs/agent/instructions.md
index 6fc4af3b8..78425a678 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: `composio.create(userId)` / `composio.sessions.create(...)`, session tools, meta tools, and `{ mcp: true }` for MCP.
+- 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.
- 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.md
index e0a39e040..19fc911a4 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. `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)
+- **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)
- **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 with `composio.use(sessionId)`, 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 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)
## Tools and toolkits
diff --git a/docs/agent/knowledge.md b/docs/agent/knowledge.md
index cc84a30bd..ed20daa25 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.create("user_123")`. 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.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.
## 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.use(sessionId)` instead of calling `create()` again. 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.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 })`.
diff --git a/docs/api-overviews/mcp.mdx b/docs/api-overviews/mcp.mdx
index 257e30798..0fa88b5f8 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. 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).
+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).
</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. 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).
+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).
diff --git a/docs/api-overviews/tool-router.mdx b/docs/api-overviews/tool-router.mdx
index 1b5300b65..16f97518d 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 you
Sessions 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. 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.
+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.
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.mdx
index e2380205f..661ba0fcd 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: NextApiRe
const toolkit = payload.data.toolkit.slug;
// Look up the user and send them a re-auth link
- const session = await composio.create(lookupUser(accountId));
+ const session = await composio.sessions.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.ts
index 3c2c7a6e6..10319bc37 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.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.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.
${docsTree}
diff --git a/docs/content/docs/authentication.mdx b/docs/content/docs/authentication.mdx
index be760c5cf..0581766f7 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.create("user_123", {
+const session = await composio.sessions.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.create("user_123");
+const session = await composio.sessions.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.mdx
index 182ce090a..491edd7e5 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -17,7 +17,7 @@ session = composio.create(user_id="user_123")
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123");
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: ["github", "gmail", "slack"],
});
// Using object format with enable key
-const session2 = await composio.create("user_123", {
+const session2 = await composio.sessions.create("user_123", {
toolkits: { enable: ["github", "gmail", "slack"] },
});
```
@@ -82,7 +82,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: { disable: ["exa", "firecrawl"] },
});
```
@@ -136,7 +136,7 @@ const composio = new Composio({
provider: new OpenAIAgentsProvider(),
});
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: ["gmail"],
tools: {
gmail: {
@@ -209,7 +209,7 @@ const composio = new Composio({
provider: new OpenAIAgentsProvider(),
});
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: ["gmail"],
tools: {
gmail: {
@@ -261,7 +261,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
tools: {
// Only these Gmail tools will be available
gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] },
@@ -292,7 +292,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
tools: {
gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
github: ["GITHUB_CREATE_ISSUE", "GITHUB_GET_ISSUE"]
@@ -323,7 +323,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
tools: {
// All Slack tools except delete
slack: { 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.create("user_123", {
+const session = await composio.sessions.create("user_123", {
tags: ["readOnlyHint", "idempotentHint"]
});
// Enable some tags, disable others
-const sessionWithTagConfig = await composio.create("user_123", {
+const sessionWithTagConfig = await composio.sessions.create("user_123", {
tags: {
enable: ["readOnlyHint"],
disable: ["destructiveHint"]
@@ -411,7 +411,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
// Global: only read-only tools
tags: ["readOnlyHint"],
tools: {
@@ -484,7 +484,7 @@ const composio = new Composio({
provider: new OpenAIAgentsProvider(),
});
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: ["gmail"],
preload: {
tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
@@ -526,7 +526,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
authConfigs: {
github: "ac_your_github_config",
slack: "ac_your_slack_config",
@@ -559,7 +559,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
connectedAccounts: {
gmail: ["ca_work_gmail"],
github: ["ca_personal_github"],
@@ -606,7 +606,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
sandbox: {
enable: false,
},
@@ -659,7 +659,7 @@ session = composio.create(
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
-const session = await composio.create("user_123", {
+const session = await composio.sessions.create("user_123", {
sandbox: {
enable: true,
sandboxSize: "large",
@@ -693,7 +693,7 @@ tools = session.tools()
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const tools = await session.tools();
```
@@ -718,7 +718,7 @@ connected_account = connection_request.wait_for_connection()
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const connectionRequest = await session.authorize("github", {
callbackUrl: "https://myapp.com/callback",
@@ -751,7 +751,7 @@ for toolkit in toolkits.items:
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const toolkits = await session.toolkits();
@@ -774,7 +774,7 @@ connected = session.toolkits(is_connected=True)
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const connected = await session.toolkits({ isConnected: true });
```
@@ -801,7 +801,7 @@ while True:
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const allToolkits: any[] = [];
let cursor: string | undefined;
@@ -834,7 +834,7 @@ print(result["session_id"], result["deleted"])
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create('user_123');
+const session = await composio.sessions.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.mdx
index 32740149b..d8df3ca7b 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.create('user_123', {
+const session = await composio.sessions.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.mdx
index 8a3f33ddc..66555f9c5 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.create("user_123", {
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.mdx
index cd53aff6b..1394ab979 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.create("user_1", {
+const session = await composio.sessions.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.create("user_1", {
+const session = await composio.sessions.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.create("user_1", {
+const session = await composio.sessions.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.create("user_1", {
+const session = await composio.sessions.create("user_1", {
experimental: {
customTools: [replyGuide],
},
@@ -603,7 +603,7 @@ Use these methods to list registered tools and toolkits. Slugs include their fin
```typescript
import { Composio } from "@composio/core";
const composio = new Composio({ apiKey: "your_api_key" });
-const session = await composio.create("user_1");
+const session = await composio.sessions.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.use("session_id", {
+const session = await composio.sessions.use("session_id", {
customTools: [getUserProfile],
});
```
@@ -659,7 +659,7 @@ Use `session.execute()` to run custom tools directly, outside of an agent loop.
```typescript
import { Composio } from "@composio/core";
const composio = new Composio({ apiKey: "your_api_key" });
-const session = await composio.create("user_1");
+const session = await composio.sessions.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.mdx
index 3bd30e1c7..7d1b1dc30 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)
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create('user_123', { toolkits: ['github'] });
+const session = await composio.sessions.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.mdx
index 0ea79c22b..22c8523e0 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, toolkit
keywords: [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. 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.
+A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. In TypeScript, you create it with `composio.sessions.create(userId)`; Python uses `composio.create(user_id)`. It ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
## 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.create("user_123");
+const session = await composio.sessions.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 `create()` call returns a new session ID. Use it for a fresh task context.
+Every session-creation 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 `composio.use()` instead of calling `create()` again.
+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.
<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.use("session_id");
+const session = await composio.sessions.use("session_id");
const tools = await session.tools();
```
</Tab>
@@ -124,7 +124,7 @@ session.update(
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.use("session_id");
+const session = await composio.sessions.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.mdx
index f333d78fa..873ad5394 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.create('user_123', {
+const session = await composio.sessions.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.mdx
index 0436c5d78..89c1c1115 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.create("user_123", {
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.create("user_123", {
toolkits: ["gmail"],
multiAccount: { enable: true },
});
@@ -118,7 +118,7 @@ connection_request = session.authorize("gmail", alias="work-gmail")
// @noErrors
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.create("user_123", {
connectedAccounts: {
gmail: ["ca_work_gmail_id"],
github: ["ca_personal_github_id"],
@@ -205,7 +205,7 @@ for toolkit in toolkits.items:
// @noErrors
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.create("user_123");
// ---cut---
const toolkits = await session.toolkits();
diff --git a/docs/content/docs/manually-authenticating.mdx b/docs/content/docs/manually-authenticating.mdx
index 370de43ab..58ccfb393 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.create("user_123");
+const session = await composio.sessions.create("user_123");
const connectionRequest = await session.authorize("gmail");
@@ -69,7 +69,7 @@ print(connection_request.redirect_url)
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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:
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.mdx
index ab0e8cd48..7e59a37b0 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.create("user_123", {
+const session = await composio.sessions.create("user_123", {
authConfigs: {
github: "ac_your_github_config",
slack: "ac_your_slack_config",
@@ -90,7 +90,7 @@ tools = session.tools()
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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()
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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 needed
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.mdx
index 61a770ed0..3ee047d96 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.create("user-123", {
+const session = await composio.sessions.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.create("user-123", {
+const session = await composio.sessions.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()
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
-const session = await composio.create("user-123");
+const session = await composio.sessions.create("user-123");
// ---cut---
const tools = await session.tools();
```
@@ -219,7 +219,7 @@ result = session.execute(
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
-const session = await composio.create("user-123");
+const session = await composio.sessions.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.mdx
index 056f5d260..5826b7c8b 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.create("default", {
+const session = await composio.sessions.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.mdx
index e800db0f7..16f7e9464 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.create('user_123');
+const session = await composio.sessions.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.create('user_123',
+const session = await composio.sessions.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.mdx
index d26372e2e..eecd8a7c0 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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
authConfigs: { notion: authConfig.id },
});
```
diff --git a/docs/content/docs/providers/anthropic.mdx b/docs/content/docs/providers/anthropic.mdx
index f5911ed5e..fe6613979 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.create("user_123");
+const session = await composio.sessions.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.create("user_123");
+const session = await composio.sessions.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.mdx
index 52464a7b5..9b343ad3d 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.create("user_123");
+const session = await composio.sessions.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.mdx
index 1d4963990..d27c02b8c 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.create("user_123");
+const session = await composio.sessions.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.mdx
index 008c9bf0c..d22c34e80 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.create("user_123");
+const session = await composio.sessions.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.mdx
index 8f4c06f18..208f119d7 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.create("user_123");
+const session = await composio.sessions.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.mdx
index 7e9c803b7..7a51c5092 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.create("user_123");
+const session = await composio.sessions.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.create("user_123");
+const session = await composio.sessions.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.create("user_123");
+const session = await composio.sessions.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.mdx
index 8fbb51d9c..e5ef6d062 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.create("user_123");
+const session = await composio.sessions.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.mdx
index b43568f81..5079049af 100644
--- a/docs/content/docs/quickstart.mdx
+++ b/docs/content/docs/quickstart.mdx
@@ -111,12 +111,12 @@ const composio = new Composio({ provider: new OpenAIAgentsProvider() });
// Create a session for your user
const userId = "user_123";
-const session = await composio.create(userId);
+const session = await composio.sessions.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.use(sessionId);
+// const session = await composio.sessions.use(sessionId);
const agent = new Agent({
name: "Personal Assistant",
@@ -265,12 +265,12 @@ const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
// Create a session for your user
const userId = "user_123";
-const session = await composio.create(userId);
+const session = await composio.sessions.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.use(sessionId);
+// const session = await composio.sessions.use(sessionId);
const customServer = createSdkMcpServer({
name: "composio",
@@ -369,12 +369,12 @@ const composio = new Composio({ provider: new VercelProvider() });
// Create a session for your user
const userId = "user_123";
-const session = await composio.create(userId);
+const session = await composio.sessions.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.use(sessionId);
+// const session = await composio.sessions.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.mdx
index b0c16b0bf..c8f01d579 100644
--- a/docs/content/docs/sandbox/local.mdx
+++ b/docs/content/docs/sandbox/local.mdx
@@ -35,7 +35,7 @@ import { experimental_createLocalWorkbenchSession } from '@composio/experimental
const 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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['github'],
workbench: { enable: false },
});
diff --git a/docs/content/docs/sandbox/remote.mdx b/docs/content/docs/sandbox/remote.mdx
index a3223e9bd..c9f01af6a 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.create("user_123");
+const session = await composio.sessions.create("user_123");
// Upload a local file; the sandbox sees it at /mnt/files/sales.csv
const 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.mdx
index 86bcf63f2..074f81c13 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.headers
import { Composio } from "@composio/core";
const composio = new Composio();
-const session = await composio.create("user_123", { mcp: true });
+const session = await composio.sessions.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.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.sessions.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.create("user_123", {
+const session = await composio.sessions.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.create("user_123", { mcp: true });
+const { mcp } = await composio.sessions.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.mdx
index 694769d2a..359ac915b 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, dec
legacy: true
---
-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.
+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.
**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
-`composio.create()` returns [meta tools](/docs/how-composio-works#meta-tools):
+Creating a session 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.create("user_123");
+const session = await composio.sessions.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.create("user_123", {
+const session = await composio.sessions.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.mdx
index f271c526b..27639864a 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.create("user_alice", {
+const session = await composio.sessions.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.mdx
index 94e6621fa..7b0e5b05a 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(
```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
+const session = await composio.sessions.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.mdx
index edfea205d..3fbcaa2e7 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. 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).
+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).
</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. 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).
+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).
## Endpoints
diff --git a/docs/content/reference/api-reference/tool-router/index.mdx b/docs/content/reference/api-reference/tool-router/index.mdx
index 2423ffd71..48f7bd93c 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 you
Sessions 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. 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.
+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.
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.mdx
index 3bc0b5fdb..1fb3ab5da 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: NextApiRe
const toolkit = payload.data.toolkit.slug;
// Look up the user and send them a re-auth link
- const session = await composio.create(lookupUser(accountId));
+ const session = await composio.sessions.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.mdx
index d2f6e93a5..abfaf08bd 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 `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).
+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).
</GlossaryTerm>
<GlossaryTerm name="Session ID">
diff --git a/docs/content/reference/sdk-reference/typescript/composio.mdx b/docs/content/reference/sdk-reference/typescript/composio.mdx
index f4631de60..784e75c4b 100644
--- a/docs/content/reference/sdk-reference/typescript/composio.mdx
+++ b/docs/content/reference/sdk-reference/typescript/composio.mdx
@@ -53,9 +53,6 @@ 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
@@ -67,13 +64,12 @@ 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.
-Prefer `composio.sessions.create(...)` for new code. The top-level
-`composio.create(...)` method is kept as an alias. |
+Use `composio.sessions.create(...)` to create a session and
+`composio.sessions.use(...)` to reuse one. |
| `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 |
## Methods
diff --git a/docs/content/reference/sdk-reference/typescript/mcp.mdx b/docs/content/reference/sdk-reference/typescript/mcp.mdx
index 33bea9e0d..5295ce50c 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.create(userId, \{ mcp: true \})`
+Use a session's MCP endpoint instead: `composio.sessions.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 against
diff --git a/docs/content/reference/sdk-reference/typescript/session.mdx b/docs/content/reference/sdk-reference/typescript/session.mdx
index 8f1727e2c..3d1b593a4 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(...)` (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."
+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."
---
## Properties
diff --git a/docs/content/reference/sdk-reference/typescript/sessions.mdx b/docs/content/reference/sdk-reference/typescript/sessions.mdx
index a08670b86..3bec04109 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. `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(...)`."
+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."
---
## Usage
diff --git a/docs/content/reference/v3/api-reference/mcp/index.mdx b/docs/content/reference/v3/api-reference/mcp/index.mdx
index 6a02813bb..caa4d3a44 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. 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).
+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).
</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. 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).
+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).
## Endpoints
diff --git a/docs/content/reference/v3/api-reference/tool-router/index.mdx b/docs/content/reference/v3/api-reference/tool-router/index.mdx
index 6f745664a..e6ff8547a 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 you
Sessions 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. 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.
+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.
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.mdx
index c04ad2241..ecdbe6af5 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: NextApiRe
const toolkit = payload.data.toolkit.slug;
// Look up the user and send them a re-auth link
- const session = await composio.create(lookupUser(accountId));
+ const session = await composio.sessions.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.mdx
index 80b46feb5..9714ff426 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.create("user_123");
+const session = await composio.sessions.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.md
index 450c9eb2b..63b22dda3 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 (`composio.create()`, `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 (TypeScript's `composio.sessions.create()` and `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.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |
+| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.sessions.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.ts
index 941e2e70e..26a63ae9f 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.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.sessions.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.ts
index 38dbe3d3d..4918cffce 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.create + session.tools).
+ * Steers LLMs toward the session-based pattern (composio.sessions.create + session.tools).
*/
export const SESSION_GUARDRAILS = `
@@ -26,7 +26,7 @@ Composio supports two integration modes: **Native Tools** (with a provider packa
from composio import Composio
composio = Composio()
-session = composio.create(user_id="user_123")
+session = composio.sessions.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.create("user_123");
+const session = await composio.sessions.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.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.
+1. **Use \`composio.sessions.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.create()\`**, not to individual tool calls.
+4. **Pass \`user_id\` to \`composio.sessions.create()\`**, not to individual tool calls.
### 2.2 — NEVER DO THE FOLLOWING
diff --git a/docs/lib/local-workbench-build.ts b/docs/lib/local-workbench-build.ts
index 93a145221..69056ded4 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.create(userId, {
+ const session = await composio.sessions.create(userId, {
toolkits: ['github'],
workbench: { enable: false },
});
diff --git a/docs/lib/local-workbench-source.json b/docs/lib/local-workbench-source.json
index 5f18cc7ea..30a30361a 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.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.sessions.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.ts
index cfad7f832..0eb93914a 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.create(userId);
+ const session = await composio.sessions.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.use(existing.sessionId), memory: existing };
+ if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };
- const session = await composio.create(event.userId, {
+ const session = await composio.sessions.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.use(existing.sessionId), memory: existing };
+ if (existing) return { session: await composio.sessions.use(existing.sessionId), memory: existing };
- const session = await composio.create(event.userId, {
+ const session = await composio.sessions.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.create('setup:workspace-bot', {
+const setup = await composio.sessions.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.json
index a2ca03d82..60ed659a6 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['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"
+"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"
},
{
"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['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"
+"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"
},
{
"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['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"
+"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"
},
{
"path": "src/slack/acl.ts",
diff --git a/docs/lib/standup-bot-build.ts b/docs/lib/standup-bot-build.ts
index 11c597182..bad98cb4c 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.create('default', {
+ const session = await composio.sessions.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.create('default', {
+ const session = await composio.sessions.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.create(memberEmail, { toolkits: TOOLKITS });
+ const session = await composio.sessions.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.create(memberEmail, {
+ const session = await composio.sessions.create(memberEmail, {
toolkits: TOOLKITS,
manageConnections: false,
});
diff --git a/docs/lib/standup-bot-source.json b/docs/lib/standup-bot-source.json
index 43939637a..7f8ba0296 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.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.sessions.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.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.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",
"composio": true
}
]
diff --git a/ts/README.md b/ts/README.md
index fd6b2009a..136f0e1d5 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.create('user_123');
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
```
diff --git a/ts/docs/advanced/modifiers.md b/ts/docs/advanced/modifiers.md
index fd6c2df9a..07ce8d9dd 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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'slack'],
});
diff --git a/ts/docs/api/tool-router-files.md b/ts/docs/api/tool-router-files.md
index 87f3723ff..e9b5c6f16 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 executin
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
-const session = await composio.create('default');
+const session = await composio.sessions.create('default');
// Upload a file
const 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.md
index 65a13c289..353cd665f 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.create('user_123', {
+const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
});
@@ -72,7 +72,7 @@ const tools = await session.tools();
### Basic Session Creation
-Use `composio.create()` to create a new Tool Router session:
+Use `composio.sessions.create()` to create a new Tool Router session:
```typescript
import { 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.create('user_123', {
+const session = await composio.sessions.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.use()`:
+If you have an existing session ID, you can retrieve it using `composio.sessions.use()`:
```typescript
-const session = await composio.use('existing_session_id');
+const session = await composio.sessions.use('existing_session_id');
// Access session properties
console.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'slack', 'github'],
});
// Explicit enabled configuration
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: { enable: ['gmail', 'slack'] },
});
// Disable specific toolkits (enable all others)
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: { disable: ['calendar'] },
});
```
@@ -130,7 +130,7 @@ const session = await composio.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'slack'],
tools: {
// Configure tools per toolkit
@@ -150,7 +150,7 @@ const session = await composio.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'github'],
// Global tags applied to all toolkits
tags: ['readOnlyHint', 'idempotentHint'],
@@ -169,7 +169,7 @@ Available tags:
Map toolkits to specific authentication configurations:
```typescript
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'github'],
authConfigs: {
gmail: 'ac_gmail_work',
@@ -183,7 +183,7 @@ const session = await composio.create('user_123', {
Map toolkits to specific connected account IDs:
```typescript
-const session = await composio.create('user_123', {
+const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
manageConnections: true, // default
});
// Object: fine-grained control
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
manageConnections: {
enable: true,
@@ -218,7 +218,7 @@ const session = await composio.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.create('user_123', {
+const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
workbench: {
enable: false
@@ -242,7 +242,7 @@ const session = await composio.create('user_123', {
});
// Fine-tune workbench settings
-const session2 = await composio.create('user_123', {
+const session2 = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
experimental: {
customTools: [grep, getImportant],
@@ -583,7 +583,7 @@ const composio = new Composio({
provider: new VercelProvider(),
});
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
});
@@ -613,7 +613,7 @@ import { stepCountIs, streamText } from 'ai';
// No provider needed when using MCP
const composio = new Composio();
-const { mcp } = await composio.create('user_123', {
+const { mcp } = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
manageConnections: true,
tools: {
@@ -670,7 +670,7 @@ const llm = new ChatOpenAI({
model: 'gpt-4o',
});
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
});
@@ -709,7 +709,7 @@ import { Composio } from '@composio/core';
// No provider needed when using MCP
const composio = new Composio();
-const session = await composio.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail'],
});
@@ -752,7 +752,7 @@ import { Composio } from '@composio/core';
// No provider needed when using MCP
const composio = new Composio();
-const session = await composio.create('user_123', {
+const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.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.create('user_123');
+const session = await composio.sessions.create('user_123');
// Get all toolkits
const 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.create('user_123', config);
+const session = await composio.sessions.create('user_123', config);
await redis.set(`session:user_123`, session.sessionId);
// Retrieve existing session
const sessionId = await redis.get(`session:user_123`);
if (sessionId) {
- const session = await composio.use(sessionId);
+ const session = await composio.sessions.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.create('user_123', {
+const session = await composio.sessions.create('user_123', {
toolkits: ['gmail', 'slack'],
manageConnections: {
enable: true,
diff --git a/ts/docs/core-concepts.md b/ts/docs/core-concepts.md
index 35ae0a07d..f96fd8c58 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.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.sessions.create()` under `experimental.customTools`.
```typescript
import { Composio, experimental_createTool } from '@composio/core';
@@ -422,7 +422,7 @@ const customTool = experimental_createTool('MY_CUSTOM_TOOL', {
},
});
-const session = await composio.create('default', {
+const session = await composio.sessions.create('default', {
experimental: { customTools: [customTool] },
});
diff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.md
index a883ea0b8..0655524cd 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.create('default', {
+const session = await composio.sessions.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.ts
index a66c3d40c..fd3139a76 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.create('default', {
+ const session = await composio.sessions.create('default', {
toolkits: ['hackernews'],
manageConnections: true,
tools: {
@@ -98,7 +98,7 @@ app.get('/test/agent', async c => {
provider: new VercelProvider(),
});
- const session = await composio.create('default', {
+ const session = await composio.sessions.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.mjs
index d006e9c10..6b3c3ce77 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.create(userId, {
+ const session = await composio.sessions.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.ts
index 429005f12..27372786f 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.create('default', {
+ const session = await composio.sessions.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.ts
index 85947efe5..892d40018 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.create('default', {
+ const session = await composio.sessions.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.mjs
index 42dbc125a..b170ef2fa 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.create('e2e-tool-router-files-user', {
+ const session = await composio.sessions.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.mjs
index 81b9e034d..eb5132c19 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.create(userId);
+ const session = await composio.sessions.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.ts
index d7226864a..c90e52c5e 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.create('user_123', { toolkits: ['gmail'] });
+const session = await composio.sessions.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.ts
index d43279577..c4cb92e17 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.create('user_123', { toolkits: ['gmail'], mcp: true });
+const session = await composio.sessions.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.ts
index c51bbf287..c1ea6c6cd 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.use(existingSessionId, { customTools, customToolkits })
- : await composio.create("custom-tools-agent-user", {
+ ? await composio.sessions.use(existingSessionId, { customTools, customToolkits })
+ : await composio.sessions.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.ts
index e0e05f9ba..494bc4631 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.create>>;
+ let session: Awaited<ReturnType<typeof composio.sessions.create>>;
try {
- session = await composio.create(userId, {
+ session = await composio.sessions.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.use(session.sessionId, { customTools, customToolkits });
+ const reusedSession = await composio.sessions.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.ts
index 05975a661..1c9d31dce 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.create("default", {
+const session = await composio.sessions.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.ts
index dfa820a17..304f7f3c4 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.create('direct-tools-example-user', {
+const session = await composio.sessions.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.ts
index df109c4b2..63bbe5bd0 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.create('user_123', { toolkits: ['gmail'] });
+const session = await composio.sessions.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.ts
index 8eae65e07..5050ee4d2 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.create('user_123', { toolkits: ['gmail'], mcp: true });
+ const session = await composio.sessions.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.ts
index edb5d83b7..2eb6e2ea3 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.create('default', {
+const { mcp } = await composio.sessions.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.ts
index 88993ca03..3e632d69e 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.create('user_123', {
+const session = await composio.sessions.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.ts
index 9928aad40..fe6f6ff75 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.create('default', { mcp: true });
+const { mcp } = await composio.sessions.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.ts
index 5c33b757c..7d9ce0339 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.create('preload-example-user', {
+const session = await composio.sessions.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.ts
index 999810ef5..b8c8a16db 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.create("session-update-demo", {
+const session = await composio.sessions.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.ts
index ea853f7a5..1b927e3d9 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.create('user_123');
+const session = await composio.sessions.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.ts
index 0df24d75f..56b383fc2 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.create('userId', {
+const session = await composio.sessions.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.ts
index 476a9b033..bacbd39c8 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 session
console.log('🔄 Creating toolrouter session...');
-const session = await composio.create('default', {
+const session = await composio.sessions.create('default', {
toolkits: ['gmail'],
manageConnections: true,
mcp: true,
diff --git a/ts/packages/core/README.md b/ts/packages/core/README.md
index 4f36d7343..796a13706 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.create('user_123');
+const session = await composio.sessions.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, a
Sessions persist on the server. For multi-turn conversations, store `session.sessionId` and reuse it instead of calling `create()` again:
```typescript
-const session = await composio.use(sessionId);
+const session = await composio.sessions.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.create('user_123');
+const session = await composio.sessions.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 AI
Every session also exposes a hosted MCP endpoint. Pass `mcp: true` to surface it in the type, then point Claude, Cursor, or any MCP client at it:
```typescript
-const session = await composio.create('user_123', { mcp: true });
+const session = await composio.sessions.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.ts
index cbf69364c..aa8a017a7 100644
--- a/ts/packages/core/src/composio.ts
+++ b/ts/packages/core/src/composio.ts
@@ -15,7 +15,6 @@ 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';
@@ -207,7 +206,7 @@ export class Composio<
experimental: Experimental;
/**
* Model Context Protocol server management.
- * @deprecated Use a session's MCP endpoint instead: `composio.create(userId, { mcp: true })`
+ * @deprecated Use a session's MCP endpoint instead: `composio.sessions.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`.
@@ -217,8 +216,8 @@ export class Composio<
/**
* Create and reuse Composio sessions.
*
- * Prefer `composio.sessions.create(...)` for new code. The top-level
- * `composio.create(...)` method is kept as an alias.
+ * Use `composio.sessions.create(...)` to create a session and
+ * `composio.sessions.use(...)` to reuse one.
*/
sessions: Sessions<unknown, unknown, TProvider>;
/**
@@ -226,51 +225,6 @@ 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.
*
@@ -364,16 +318,6 @@ 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.ts
index 53cb9a5fe..1177b2d0a 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.create(userId, { experimental: { customTools: [...] } })`
+ * and execute function. Pass it to `composio.sessions.create(userId, { experimental: { customTools: [...] } })`
* to bind it to a session.
*
* Just return the result data from `execute`, or throw an error.
@@ -483,9 +483,7 @@ export function buildCustomToolsMapFromResponse(
tools: CustomTool[],
toolkits: CustomToolkit[] | undefined,
experimental:
- | SessionCreateResponse['experimental']
- | SessionRetrieveResponse['experimental']
- | undefined
+ SessionCreateResponse['experimental'] | SessionRetrieveResponse['experimental'] | undefined
): CustomToolsMap {
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
diff --git a/ts/packages/core/src/models/MCP.ts b/ts/packages/core/src/models/MCP.ts
index 506139858..1cce7d418 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.create(userId, { mcp: true })`
+ * @deprecated Use a session's MCP endpoint instead: `composio.sessions.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 against
diff --git a/ts/packages/core/src/models/Sessions.ts b/ts/packages/core/src/models/Sessions.ts
index 267b3cce9..775e7140a 100644
--- a/ts/packages/core/src/models/Sessions.ts
+++ b/ts/packages/core/src/models/Sessions.ts
@@ -6,9 +6,8 @@ import { ToolRouter } from './ToolRouter';
/**
* 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(...)`.
+ * Use `composio.sessions.create(...)` to create a session and
+ * `composio.sessions.use(...)` to reuse one.
*/
export class Sessions<
TToolCollection,
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index e9ebeac6e..efb6ed992 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -94,8 +94,7 @@ const AuthorizeOptionsSchema = z.object({
/**
* 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).
+ * 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
diff --git a/ts/packages/core/src/provider/BaseProvider.ts b/ts/packages/core/src/provider/BaseProvider.ts
index 703619f8c..e633fe254 100644
--- a/ts/packages/core/src/provider/BaseProvider.ts
+++ b/ts/packages/core/src/provider/BaseProvider.ts
@@ -62,13 +62,15 @@ abstract class BaseProvider<TMcpResponse> {
/**
* @public
- * @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.
+ * 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.)
*
* @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.ts
index fb358e35e..1ab61ca9d 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.create(userId, { experimental: { customTools: [...] } })` to bind to a session.
+ * Pass to `composio.sessions.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.create(userId, { experimental: { customToolkits: [...] } })`.
+ * Pass to `composio.sessions.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.ts
index 663fda647..80e3902da 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 and keep composio.create as a bound alias', async () => {
+ it('should expose sessions.create without bare root aliases', async () => {
const composio = new Composio(baseConfig);
const client = composio.getClient() as any;
client.toolRouter.session.create = vi.fn().mockResolvedValue({
@@ -127,21 +127,16 @@ describe('Composio Session Management', () => {
expect(composio.toolRouter).toBe(composio.sessions);
- const sessionFromCanonicalApi = await composio.sessions.create('user_123');
- const sessionFromAlias = await composio.create('user_456');
+ const session = await composio.sessions.create('user_123');
expect(client.toolRouter.session.create).toHaveBeenNthCalledWith(
1,
expect.objectContaining({ user_id: 'user_123' }),
undefined
);
- 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');
+ expect(session.sessionId).toBe('session_123');
+ expect(composio).not.toHaveProperty('create');
+ expect(composio).not.toHaveProperty('use');
});
});
diff --git a/ts/packages/core/type-tests/sessions-mcp.test-d.ts b/ts/packages/core/type-tests/sessions-mcp.test-d.ts
index 0b318b75e..035df3fc3 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.create('user_123');
+ const session = await composio.sessions.create('user_123');
// @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passed
void 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.create('user_123', { mcp: true });
+ const mcpSession = await composio.sessions.create('user_123', { mcp: true });
const _url: string = mcpSession.mcp.url;
void _url;
}
async function useGating(): Promise<void> {
- const session = await composio.use('session_123');
+ const session = await composio.sessions.use('session_123');
// @ts-expect-error mcp is hidden from the type unless `{ mcp: true }` is passed
void session.mcp;
- const mcpSession = await composio.use('session_123', { mcp: true });
+ const mcpSession = await composio.sessions.use('session_123', { mcp: true });
const _url: string = mcpSession.mcp.url;
void _url;
}
@@ -41,13 +41,21 @@ 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.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });
- await composio.create('user_123', { mcp: true }, { signal: ctrl.signal });
+ await composio.sessions.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });
+ await composio.sessions.create('user_123', { mcp: true }, { signal: ctrl.signal });
await composio.sessions.create('user_123', undefined, { signal: ctrl.signal });
- await composio.use('session_123', { customTools: [] }, { signal: ctrl.signal });
- await composio.use('session_123', { mcp: true }, { 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;
}
void createGating;
void useGating;
void requestOptionsArg;
+void bareSessionAliasesAreRemoved;
diff --git a/ts/packages/providers/anthropic/README.md b/ts/packages/providers/anthropic/README.md
index cab3f1695..39d6cdb4e 100644
--- a/ts/packages/providers/anthropic/README.md
+++ b/ts/packages/providers/anthropic/README.md
@@ -25,13 +25,14 @@ const composio = new Composio({
const client = new Anthropic();
// Create a session for your user
-const session = await composio.create('user_123');
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
const messages: Anthropic.MessageParam[] = [
{
role: 'user',
- content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
+ content:
+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
},
];
diff --git a/ts/packages/providers/claude-agent-sdk/README.md b/ts/packages/providers/claude-agent-sdk/README.md
index f67335837..75f71b104 100644
--- a/ts/packages/providers/claude-agent-sdk/README.md
+++ b/ts/packages/providers/claude-agent-sdk/README.md
@@ -18,38 +18,38 @@ Set two environment variables:
Create a session for your user, serve its tools through an SDK MCP server, and query Claude:
```typescript
-import { Composio } from "@composio/core";
-import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
-import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
+import { Composio } from '@composio/core';
+import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
+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.create("user_123");
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
const customServer = createSdkMcpServer({
- name: "composio",
- version: "1.0.0",
+ name: 'composio',
+ version: '1.0.0',
tools,
});
for await (const stream of query({
- prompt: "Summarize my emails from today",
+ prompt: 'Summarize my emails from today',
options: {
mcpServers: { composio: customServer },
- permissionMode: "bypassPermissions",
+ permissionMode: 'bypassPermissions',
},
})) {
- if (stream.type === "assistant") {
+ if (stream.type === 'assistant') {
for (const block of stream.message.content) {
- if (block.type === "text") process.stdout.write(block.text);
+ if (block.type === 'text') process.stdout.write(block.text);
}
}
}
```
-For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.
+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
## How it works
diff --git a/ts/packages/providers/cloudflare/README.md b/ts/packages/providers/cloudflare/README.md
index 4d65f386f..07f396877 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.create('user_123');
+ const session = await composio.sessions.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.md
index f2aa37d19..1458ec17c 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.create('user_123');
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
const chat = ai.chats.create({
@@ -36,7 +36,8 @@ const chat = ai.chats.create({
});
let response = await chat.sendMessage({
- message: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
+ message:
+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
});
// Agentic loop: keep executing tool calls until the model responds with text
diff --git a/ts/packages/providers/langchain/README.md b/ts/packages/providers/langchain/README.md
index 2e8720817..1860de4ad 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.create('user_123');
+const session = await composio.sessions.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.md
index 696a9ce58..38cbfbc9c 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.create('user_123');
+const session = await composio.sessions.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.md
index 6b28fe6af..b32499337 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.create('user_123');
+const session = await composio.sessions.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.md
index 61ff81b87..f8cab7ef4 100644
--- a/ts/packages/providers/openai-agents/README.md
+++ b/ts/packages/providers/openai-agents/README.md
@@ -18,28 +18,28 @@ Set two environment variables:
Create a session for your user, hand its tools to an agent, and run it:
```typescript
-import { Composio } from "@composio/core";
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
-import { Agent, run } from "@openai/agents";
+import { Composio } from '@composio/core';
+import { OpenAIAgentsProvider } from '@composio/openai-agents';
+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.create("user_123");
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
const agent = new Agent({
- name: "Personal Assistant",
- instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
- model: "gpt-5.2",
+ name: 'Personal Assistant',
+ instructions: 'You are a helpful personal assistant. Use Composio tools to take action.',
+ model: 'gpt-5.2',
tools,
});
-const result = await run(agent, "Summarize my emails from today");
+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.use(sessionId)` instead of creating a new session each turn.
+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
## Strict mode
diff --git a/ts/packages/providers/openai/README.md b/ts/packages/providers/openai/README.md
index cf086ee42..7424449f0 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.create('user_123');
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
let response = await client.responses.create({
@@ -34,7 +34,8 @@ let response = await client.responses.create({
input: [
{
role: 'user',
- content: "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
+ content:
+ "Send an email to [email protected] with the subject 'Hello' and body 'Hello from Composio!'",
},
],
});
diff --git a/ts/packages/providers/vercel/README.md b/ts/packages/providers/vercel/README.md
index e628c02eb..8a6566517 100644
--- a/ts/packages/providers/vercel/README.md
+++ b/ts/packages/providers/vercel/README.md
@@ -20,28 +20,28 @@ Set two environment variables:
Create a session for your user, pass its tools to the AI SDK, and cap the run with `stopWhen`:
```typescript
-import { anthropic } from "@ai-sdk/anthropic";
-import { Composio } from "@composio/core";
-import { VercelProvider } from "@composio/vercel";
-import { generateText, stepCountIs } from "ai";
+import { anthropic } from '@ai-sdk/anthropic';
+import { Composio } from '@composio/core';
+import { VercelProvider } from '@composio/vercel';
+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.create("user_123");
+const session = await composio.sessions.create('user_123');
const tools = await session.tools();
const { text } = await generateText({
- model: anthropic("claude-sonnet-4-6"),
+ model: anthropic('claude-sonnet-4-6'),
tools,
- prompt: "Summarize my emails from today",
+ prompt: 'Summarize my emails from today',
stopWhen: stepCountIs(10),
});
console.log(text);
```
-For multi-turn conversations, store `session.sessionId` and reuse it with `composio.use(sessionId)` instead of creating a new session each turn.
+For multi-turn conversations, store `session.sessionId` and reuse it with `composio.sessions.use(sessionId)` instead of creating a new session each turn.
## Strict mode