Integration branch for the next docs release: a **sessions-first
documentation rewrite** — new and rewritten guides, example pages,
interactive components, and docs tooling — plus the supporting SDK
changes that the new docs describe.
The bulk of this PR is docs (~24k lines across ~150 commits); the SDK
changes (~5k lines) back the new guides.
## Documentation (the bulk)
- **Sessions-first restructure** — reorganized navigation and section
structure (incl. the "Sandbox (prev workbench)" section), with
v3-reorganization redirects so old URLs keep resolving.
- **Rewritten core guides** — quickstart, configuring sessions, triggers
(creating + subscribing to events), proxy-execute, toolkits
enable/disable, and common FAQ, rewritten in the house voice.
- **New example pages** — local-sandbox PR reviewer, daily standup bot,
and slack bot, with runnable build-ups.
- **New interactive components & diagrams** — triggers flow animation,
manage-connections visual, connection-refresh visual, and the
terminal-kit components.
- **Docs tooling** — a docs-graph link-graph connectivity checker,
search reprioritization (deprioritize legacy pages), and SDK-reference
regeneration.
## Supporting SDK changes
**`@composio/core` → 0.13.0 (minor)**
- `composio.sessions.create()` as the first-class sessions API
(`composio.create()` kept as an alias).
- **MCP is opt-in:** default `create()` / `use()` return native-tool
sessions (`SessionWithoutMcp`); pass `{ mcp: true }` to surface
`session.mcp`. _Migration: read `session.mcp` only after creating with
`{ mcp: true }`._
- `session.sandbox` is the canonical resolved config;
`session.workbench` kept as a deprecated alias. `sandbox` is the
preferred session-config key (`workbench` still accepted).
- `connectedAccounts.updateAcl()` graduated from experimental (alias
kept).
- `triggers.parse()` (parse + optionally verify an incoming webhook) and
`triggers.setWebhookSubscription()`.
**`@composio/experimental` → minor** — local-workbench helpers moved
onto the `@composio/experimental/workbench` subpath (out of
`@composio/core/experimental`), keeping the ~14 KB embedded Python
helper out of core. Plus the experimental Pi provider.
**`@composio/slim` → minor.**
**Python → 0.17.0** — mirrors the TS surface: `composio.sessions` mount
(`tool_router` deprecated), `triggers.parse()` /
`set_webhook_subscription()`, the `sandbox` config key, and
`connected_accounts.update_acl()`.
## Review response (#3664)
Addressed the `@composio/core` review:
- **Security:** `triggers.parse()` no longer fails open — a
present-but-empty `verifySecret` (e.g. unset `COMPOSIO_WEBHOOK_SECRET`)
now throws instead of silently skipping verification; omitting it stays
an explicit opt-out (both SDKs).
- Removed snake_case leakage from `transformWebhookSubscription` (+ the
index signature that allowed it).
- **Removed** the TS-only `connectedAccounts.link()` toolkit
auto-resolve (shipped with cancellability / orphaned-auth-config bugs
and was effectively undocumented; to be reintroduced properly later).
- Unified Python error types on `ValidationError`; added `mcp=True`
Python tests; fixed runtime-portability + error-type test assertions.
- Polished deprecation messages; fixed the backwards `/experimental`
`@deprecated` note and the `SessionWithMcp` JSDoc.
## Testing
- **TS:** `@composio/core` + `@composio/experimental` typecheck pass;
vitest green for the touched suites.
- **Python:** `test_tool_router.py` + `test_triggers.py` pass (161
tests).
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Kshitij Jhunjhunwala <kj@composio.dev>
Co-authored-by: Malay Vasa <malayvasa@gmail.com>
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
The chat app now creates the session once and reuses it across
requests via composio.use(sessionId), which is the correct pattern
for multi-turn chat apps.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Automatic tool file upload/download for `file_uploadable` fields is
**off by default** in TypeScript and Python. Callers must explicitly opt
in, and uploads from local paths are constrained by a fail-closed
allowlist.
## Changes
- **Removed (breaking):** `autoUploadDownloadFiles` (TS) /
`auto_upload_download_files` (Python) — the legacy default-on flag is
gone, not just deprecated.
- **New opt-in:** `dangerouslyAllowAutoUploadDownloadFiles` (TS) /
`dangerously_allow_auto_upload_download_files` (Python). When `true`,
`tools.get(...)` collapses `file_uploadable` schemas to `{ type:
'string', format: 'path' }` and the SDK stages local paths/URLs at
execute time.
- **New:** `fileUploadDirs?: string[] | false` — fail-closed allowlist
for local upload paths. `undefined` → `[<home>/.composio/temp]`; `false`
→ reject all local paths (URLs / `File` objects unaffected); explicit
`string[]` replaces the default. Components are matched on a path
boundary after `realpath`.
- **New:** `fileDownloadDir?: string` — directory where
`file_downloadable` results are staged.
- **New:** `beforeFileUpload` hook receives `source: 'path' | 'url' |
'file'` (TS) / `'path' | 'url'` (Python) so it can branch on input type.
- **New (TS):** when auto-upload is **off** and an LLM-driven
`tools.execute` is called against a tool with `file_uploadable` inputs,
the SDK emits a one-shot warning per tool slug pointing at
`composio.files.upload()` for manual staging.
## Migration
To restore previous behavior:
```ts
new Composio({
apiKey: process.env.COMPOSIO_API_KEY!,
dangerouslyAllowAutoUploadDownloadFiles: true,
// Optional: tighten the allowlist beyond the default ~/.composio/temp
fileUploadDirs: ['/srv/uploads'],
});
```
```python
Composio(api_key="...", dangerously_allow_auto_upload_download_files=True)
```
If you previously passed the legacy flag, remove it. There is no
transitional warning — TS and Python both reject the unknown property at
the type/keyword-arg level.
## Versioning
| Package | Bump |
| ------- | ---- |
| `@composio/core` | minor |
| `composio` (Python) | minor |
| Other `@composio/*` packages | patch (via changesets
`updateInternalDependencies: "patch"`) |
See
`docs/content/changelog/04-24-26-legacy-auto-upload-config-removal.mdx`
for the full migration writeup.
Multi-toolkit session cookbook that searches across GitHub, Slack, Gmail,
and Notion. Teaches manual auth flow with session.authorize() and
wait_for_connection().
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new cookbook showing how to build an AI PR review agent using
OpenAI Agents SDK and Composio. The agent reads CLAUDE.md / AGENTS.md
from the repo root as a review checklist, analyzes diffs, and posts
structured feedback as a PR comment. Includes a GitHub Action workflow
for automatic reviews on every PR.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Autonomous agent that sweeps GitHub, Gmail, and Slack on a schedule.
Uses Vercel AI SDK + OpenAI + Composio. Includes cron and GitHub Actions
deployment examples.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Agentic RAG cookbook showing a CLI agent that triages support issues
using Datadog, Notion, and GitHub tools with scoped sessions,
streaming responses, and multi-turn chat.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace fragmented inline code snippets with a standalone example
script using region markers and <include> tags. The script exposes
three commands: list-tools, toolkit-info, and export.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace non-existent ClaudeSDKClient with the correct query() async
generator from claude_agent_sdk.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Access email fields from data["payload"] instead of data directly.
The SDK subscription callback receives a TriggerEvent where email
data (subject, id, message_text) is nested under the payload key.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace the old LangChain-based cookbook with the session paradigm
(composio.create, session.tools, session.authorize) using the Claude
Agent SDK provider and Composio triggers. Follows the same include-region
pattern as the slack summariser and FastAPI cookbooks.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move ChatRequest into #chat region and ConnectRequest into #connect
region so developers see the model definitions in tutorial snippets.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rewrite slack-summariser cookbook with session API + OpenAI Agents SDK
- Add docs/examples/slack-summariser/main.py with connect and summarize commands
- Replace inline code in FastAPI and Hono cookbooks with <include> using #region markers
- Add no-twoslash meta to Hono region includes (partial snippets lack imports)
- Consolidate docs/example/ into docs/examples/ (single canonical directory)
- Delete superseded tutorial-chat-app.mdx (replaced by chat-app.mdx)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replaces the old direct-execution pattern (composio.tools.get,
authConfigs.create, connectedAccounts.initiate) with the session-based
pattern (composio.create, session.tools, session.authorize,
session.toolkits).
Endpoints:
- POST /chat — agentic loop with OpenAI + Composio meta tools
- GET /connections/:userId — list all toolkit connection statuses
- GET /connections/:userId/:toolkit — check single toolkit
- POST /connect/:toolkit — start OAuth, return redirect URL
Adds docs/examples/hono/server.ts as the standalone example file,
included via <include> tag in the MDX.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add visible Send button to chat forms (page.tsx + page-with-tools.tsx)
- Add "View source on GitHub" link to chat-app cookbook
- Add code review guidelines to CLAUDE.md for tutorial code in examples/
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add jsx: react-jsx compiler option to twoslash config (fixes React UMD global errors)
- Install @ai-sdk/react for useChat type resolution
- Exclude examples/ from tsconfig (twoslash handles type-checking via <include>)
- Allow expected error 2307 for local component import in page-with-tools.tsx
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "Build a Chat App" cookbook with external code files via <include>
- Restructure welcome page: hero cards, Get Started, AI tools banner, Explore
- Create AIToolsBanner component with grid pattern, skills command, and context file links
- Add markdown conversion for AIToolsBanner in LLM endpoint
- Add chat-app to cookbooks navigation after templates
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rahul Tarak