This PR:
- builds on https://github.com/ComposioHQ/composio/pull/3823 and
https://github.com/ComposioHQ/composio/pull/3824
- bumps the Python SDK and every provider package from `0.17.1` to
`0.18.0`
- synchronizes the runtime version and root `uv.lock`
- adds the canonical July 16 changelog entry, including URL-upload and
telemetry security, trigger connection-resolution behavior, provider
schema fixes, and the `pyautogen` to `ag2` migration
- strengthens release guards for Python workflow invocation, provider
metadata, and current Python and TypeScript changelog coverage
- limits provider packaging to directories containing `pyproject.toml`
- makes provider cleanup, installation, and builds stop on the first
failure
- incorporates the merged TypeScript changelog and missing Changeset
from https://github.com/ComposioHQ/composio/pull/3849
After merging, create and push the annotated `py@0.18.0` tag from the
merged `next` commit.
## Validation
- `pnpm test:release-workflow`
- `uv lock --check`
- `uv run --frozen python -c "import composio; assert
composio.__version__ == \"0.18.0\""`
- `pnpm exec prettier --check
docs/content/changelog/07-16-26-python-sdk-018.mdx
test/release-workflow.test.ts`
- `cd docs && bun run test`
- `cd docs && bun run lint:links`
- `cd docs && bun run types:check`
- `cd python && make build`
- `cd python && uv tool run twine check dist/*`
This PR:
- documents TypeScript `@composio/core` `0.14.0`, prepared in
https://github.com/ComposioHQ/composio/pull/3717
- calls out trigger behavior changes, provider compatibility,
file-upload security, telemetry redaction, and tool-execution
reliability
- adds the missing `@composio/core` patch Changeset for the local-path
fix merged in https://github.com/ComposioHQ/composio/pull/3766
- leaves the Python `0.18.0` changelog with
https://github.com/ComposioHQ/composio/pull/3825 so the release and docs
PRs do not add the same file
- keeps the TypeScript candidate release in the canonical docs changelog
before publishing
After this PR merges into `next`, the Changesets release PR must
regenerate before publishing.
## Validation
- `pnpm test:release-workflow`
- `pnpm changeset status --since=origin/next`
- `bun run test`
- `bun run lint:links`
- `bun run types:check`
- `bun run build`
- `pnpm exec prettier --check
docs/content/changelog/07-15-26-typescript-sdk-014.mdx
.changeset/http-prefixed-local-paths.md`
`bun run lint` remains red on 23 existing React and Next.js errors
outside these files.
## Summary
The LangGraph Python example imports from langchain.agents import
create_agent, but the install command on the same page doesn't include
langchain — and neither langgraph nor langchain_openai pulls it in (they
only depend on langchain-core). Following the docs verbatim in a fresh
environment fails on the example's first import with
ModuleNotFoundError: No module named 'langchain'.
Fixes#3847
## Changes
- docs/content/docs/providers/langchain.mdx: LangGraph Python install
line gains langchain, matching the provider's own README
(python/providers/langgraph/README.md).
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Fresh venv with the documented install set (langgraph==1.2.9,
langchain-openai==1.3.5, Python 3.12): from langchain.agents import
create_agent fails with ModuleNotFoundError.
- Same venv after adding langchain: the docs example constructs the
agent via create_agent and the wrapped tool invokes correctly, with no
deprecation warnings.
- Docs: bun run build and bun run lint:links from docs/: green.
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct and this PR adheres to it
- [x] I ran linters/tests locally and they passed
- [x] I updated documentation as needed
- [ ] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset: docs-only. No tests: one-word install-command fix,
verified manually as above.
## Summary
Deprecated REST endpoints now surface the existing `Legacy` badge in
generated API-reference indexes, with endpoint-specific tooltip copy
instead of the Sessions-specific default. The generator behavior is
covered end to end for both v3 and v3.1, including rendered table
output.
This branch also restores CI compatibility with the organization Actions
policy: workflow tool versions still come from `mise.toml`, but
installation uses the approved, SHA-pinned setup actions. Secret
scanning pins the repaired organization reusable workflow from
ComposioHQ/.github#13.
## Changes
- Read the OpenAPI `deprecated` flag and emit `legacy: true` only for
deprecated operations.
- Render `LegacyBadge` on affected endpoint rows with accurate lifecycle
tooltip copy.
- Regenerate the affected `files` and `connected-accounts` indexes for
v3 and v3.1.
- Cover the real generator output, active-operation omission, badge
count, and tooltip through a focused regression test.
- Replace disallowed transitive Actions dependencies while retaining
`mise.toml` as the single tool-version source.
Endpoint detail pages continue to use `fumadocs-openapi`'s built-in
deprecated marker. The indexed endpoints are `GET /files/list` and `POST
/connected_accounts/{nanoid}/refresh`; internal operations remain
filtered from the docs.
## Spec data
The committed OpenAPI snapshots lagged the live backend for `POST
/connected_accounts/{nanoid}/refresh`. Both snapshots now carry its
current summary, description, and `deprecated: true`; the next
`fetch-openapi.mjs` run will preserve that state from the live spec.
## Validation
- `bun run test`: 25 passed, 0 failed.
- `bun run types:check`: passed.
- Focused ESLint and generated-index drift checks: clean.
- Composite-action and workflow YAML parsed successfully; extracted tool
pins match `mise.toml`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
The Gemini Python example paired composio_google (which wraps tools as
VertexAI FunctionDeclaration objects) with google-genai client.
GenerateContentConfig silently coerces those VertexAI objects into an
empty genai Tool ({}), so the documented flow sends requests with no
tool schemas at all - the model never sees or calls any Composio tool,
with no error surfaced anywhere.
Fixes#3836
## Changes
- docs/content/docs/providers/google.mdx (Gemini tab, Python only):
- install line: composio_google → composio_gemini
- example: GeminiProvider + Automatic Function Calling; the manual while
response.function_calls: loop is gone because the google-genai SDK
executes the wrapped callables itself
- intro paragraph updated to describe the Python (AFC) and TypeScript
(manual loop) flows separately
The TypeScript tab and the Google ADK section are untouched; both
already target the right SDKs. The new Python example matches the
existing quickstart in python/providers/gemini/README.md.
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Offline repro of the bug (issue #3836): with composio_google,
config.tools[0].model_dump(exclude_none=True) is {} and genai's
_transformers.t_tools raises AttributeError on the vertexai type.
- Offline verification of the fix: the exact construction path of the
new example (GeminiProvider().wrap_tools → GenerateContentConfig →
chats.create → t_tools) serializes a complete FunctionDeclaration (name,
description, parameters) with composio==0.17.1, google-genai==2.11.0,
Python 3.12.
- Docs: bun run build and bun run lint:links from docs/: green.
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct, and this PR adheres to it
- [x] I ran linters/tests locally, and they passed
- [x] I updated documentation as needed
- [x] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset: docs-only change, no published package affected.
Regression coverage: `docs/tests/static/content.test.ts` now guards the
documented `composio_gemini` + `google-genai` pairing; the example's
construction path was also exercised offline as described above.
The underlying provider split (composio_google targeting the
upstream-deprecated vertexai generative_models SDK vs composio_gemini
targeting google-genai) is flagged in #3836 as an open question for
maintainers; this PR is the docs-only fix.
---------
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
The AutoGen provider examples still used the legacy
`llm_config={"config_list": [...]}` dict form, which ag2 0.14 (the
distribution `composio-autogen` depends on since #3729) only keeps for
backport compatibility and marks deprecated in
`LLMConfig.ensure_config`. The install command also pulled
`autogen-agentchat` (Microsoft's next-gen AutoGen package), which the
provider never imports, while the `ag2` distribution the examples
actually import from was only installed transitively.
Fixes#3831
## Changes
- `docs/content/docs/providers/autogen.mdx`: example migrated to
`LLMConfig({...})`, install line changed to `composio composio_autogen
ag2`, added `ag2` keyword and a one-line note that the provider runs on
the ag2 distribution
- `python/providers/autogen/README.md`: same quickstart and install
fixes
- `python/providers/autogen/autogen_demo.py`: same `LLMConfig` migration
`initiate_chat` is left as is: it isn't deprecated in ag2 0.14, and it's
the flow `register_tools` (caller/executor) is verified against.
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [x] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Verified in a fresh venv with the local `composio` +
`composio-autogen` packages and `ag2==0.14.0`: the updated example
constructs both agents, wraps a Composio tool via `AutogenProvider`,
registers it with `register_tools`, and executes it through the
executor's function map
- `uv run nox -s chk` (ruff + mypy): green
- `ruff format --check providers/autogen/`: clean
- Docs: `bun run build` and `bun run lint:links` from `docs/`: green
## Screenshots (if applicable)
## Checklist
- [x] I have read the Code of Conduct and this PR adheres to it
- [x] I ran linters/tests locally and they passed
- [x] I updated documentation as needed
- [ ] I added tests or explain why not applicable
- [x] I added a changeset if this change affects published packages
## Additional context
No changeset added: docs and Python-only change, no published TypeScript
package affected. No tests added: example/docs change with no runtime
code paths; the updated example was exercised manually against ag2 0.14
as described above.
---------
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
This PR:
- reverts https://github.com/ComposioHQ/composio/pull/3780
- restores the TypeScript `composio.create()` and `composio.use()`
session aliases, with their runtime and type-test coverage
- restores the prior deprecation state for
`BaseProvider.wrapMcpServerResponse`
- removes the pre-v1 breaking-change changeset so the release PR no
longer advertises this removal
The v1 API-freeze change should be recreated later as a draft PR and
kept out of the merge queue until v1 is ready.
## Summary
Automated documentation updates triggered by new changelog entries
merged to next.
Generated by Codex via GitHub Actions.
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This PR:
- Adds public docs changelog entries for the Python and TypeScript SDK
releases since May 15, 2026, including the previously unmigrated Python
0.13.1 entry.
- Removes the Python-local changelog and replaces it with canonical
changelog links from the repository and Python READMEs.
- Retargets the Python release guard to the docs changelog, documents
its table contract, and covers prior-version plus PEP 440 version
parsing.
Validation:
- pnpm test:release-workflow
- docs: bun run test
- docs: bun run lint:links
- docs: bun run types:check
- docs: bun run build
- pnpm exec prettier --check test/release-workflow.test.ts
docs/agent-guidance/guides/changelog.md docs/content/changelog/*.mdx
Review:
- ce-code-review completed with correctness, testing, maintainability,
project-standards, agent-native, learnings, and adversarial passes. All
actionable findings were fixed; final adversarial re-review found no
remaining P0-P2 issue.
## Summary
- Ports support-workflows toolkit KB into public toolkit FAQ docs for 85
toolkit FAQ files.
- Creates 46 new toolkit FAQ files for toolkits that had KB but no FAQ
file yet.
- Updates existing toolkit FAQ files without deleting current public
answers.
## General docs updates
- Clarifies connected-account credential redaction and reconnect/refresh
semantics.
- Documents Proxy Execute scoped-key and v3.1/current-SDK requirements.
- Adds retry risk guidance for non-idempotent direct tool executions.
- Adds remote sandbox temporary state/file retention guidance.
- Adds Composio Connect vs developer project boundary guidance for MCP
app connections.
## Verification
- Hygiene grep passed on changed files:
`Plain|T-|SUP-|PRO-|Linear|plain.com|linear.app|/Users/|support-workflows|TODO|FIXME|\[eng:|customer`.
- `git diff --check` passed.
- `bun run lint:links` passed: 0 errored files, 0 errors.
- `bun run build` passed. Build emitted the existing Turbopack NFT
warning plus toolkit-detail fetch skips because `COMPOSIO_API_KEY` is
not set locally.
- Render spot checks passed for Gmail, Apollo, SharePoint, Google
Calendar, connected accounts, and remote sandbox pages.
## Deferred
- PowerPoint KB was not added because the current docs toolkit catalog
has no `powerpoint` toolkit slug/page. The KB describes a possible
future file-operations toolkit rather than an existing public toolkit
page.
---------
Co-authored-by: Sarah Simionescu <sarah@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## What and why
This makes the intended v1 API cleanup real rather than postponing it to
v2:
- Remove the TypeScript root aliases `composio.create(...)` and
`composio.use(...)`. Session creation and reuse now live only at
`composio.sessions.create(...)` and `composio.sessions.use(...)`. This
is a deliberate breaking change, reflected by a major changeset.
- Retain `BaseProvider.wrapMcpServerResponse` as the stable v1 provider
SPI. Its earlier deprecation pointed to a method that was never
introduced.
The scope is intentionally narrow: it does **not** remove unrelated
deprecated APIs, and Python keeps its supported `Composio.create/use`
API. The TypeScript docs, examples, providers, runtime fixtures,
generated SDK reference, and API-reference indexes now use the
namespaced TypeScript API. Historical changelog examples are left as
history.
## Verification
- `pnpm typecheck`
- `pnpm --filter @composio/core test -- --run test/core/session.test.ts`
(42 files, 1,018 tests)
- `pnpm exec eslint ts/packages/core/src/composio.ts`
- `pnpm --filter @composio/core generate:docs`
- `cd docs && bun run generate:api-index`
- `cd docs && bun run types:check`
- `git diff --check` and targeted scans for removed TypeScript aliases
I also attempted the affected Node and Cloudflare runtime E2E suites.
They cannot initialize in this checkout without `COMPOSIO_API_KEY` (and,
for Cloudflare, `COMPOSIO_BASE_URL` and `OPENAI_API_KEY`); they did not
report a product assertion failure.
## What
Two changes to the docs install experience:
**1. Package-manager picker on install code blocks.** New
`PackageInstall` client component
(`docs/components/package-install.tsx`): the code block's copy button
opens a dropdown of package managers. Selecting one rewrites the
displayed command and copies it to the clipboard.
- TypeScript blocks: npm (default, `npm install`) / pnpm / bun / yarn
(`<pm> add`)
- Python blocks: uv (default, `uv add`) / pip (`pip install`)
- The menu is portaled to `document.body` so it isn't clipped by the
`Tabs`/`CodeBlock` overflow containers, and closes on outside click,
Escape, or real scroll movement.
**2. `@composio/slim` callout in the quickstart.** The quickstart
TypeScript install blocks carry display-only `#` comment lines noting
that `@composio/core` ships its docs and TypeScript source in the
package (inspectable to coding agents) and that `@composio/slim` is the
smaller install with the same API. Comment lines are rendered muted and
are **never copied** — the picker copies only the command.
## Where
Converted every plain `npm install` / `pip install` code block under
`docs/content` (quickstart, all provider pages, single-toolkit MCP,
custom tools, migration guides, standup example, SDK reference indexes).
The TS reference index's manual npm/pnpm/yarn/bun tabs collapse into one
picker. The two SDK-reference generators
(`ts/packages/core/scripts/generate-docs.ts`,
`python/scripts/generate-docs.py`) emit the new component so
regeneration keeps it. Flagged upgrade commands (`pip install
-U/--upgrade`) and the bun-first examples were left as-is.
## Verification
- `bun run types:check` — pass
- `bun run build` — pass
- `eslint` on touched TS files — clean (remaining repo lint errors are
pre-existing on `next`)
- Visual check via dev server + browser: comment lines render muted
below the command, picker opens npm/pnpm/bun/yarn (uv/pip on Python
tabs), selecting a manager rewrites the command, and the clipboard
receives exactly the command with no comment lines.
Docs-only behavior change; no changeset (generator-script edits don't
touch published code).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This PR:
- supersedes https://github.com/ComposioHQ/composio/pull/3642 and
credits @shamsharoon for the original Eve provider and iMessage work
- rebases the integration onto the current `next` branch and resolves
its lockfile conflicts
- publishes an isolated `@composio/experimental/eve` entry with the
correct Eve 0.12+ peer contract
- adds recoverable per-session discovery, native Eve context
propagation, and durable approval policies for direct and batched side
effects
- centralizes circular-safe auth-link extraction across Eve and Pi and
replaces dense conditional expressions with named control flow
- hardens the iMessage example against `osascript` option injection,
unsafe trigger scoping, and third-party prompt injection
- preserves completed local-tool results when a mixed local/remote batch
loses its remote transport
- consolidates the example documentation onto shared components,
documents direct model-provider credentials, and clarifies that the
browsable source is not yet a standalone fixture
- verifies the change with 999 core tests, 32 experimental tests,
package builds/typechecks, packed peer-isolation smokes, and a
production docs build
---------
Co-authored-by: shams haroon <144290365+shamsharoon@users.noreply.github.com>
Co-authored-by: shams haroon <shamsharoon7@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: shams haroon <shams@composio.dev>
Add a YouTube walkthrough at the top of the Scoped Project API Key
reference page and a short "Create a scoped API key" section with
dashboard steps.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Summary
- Add a Google Ads toolkit FAQ entry for quota errors after a successful
OAuth login.
- Clarify that `RESOURCE_EXHAUSTED` with developer-token rate scope is
tied to the Google Ads developer token quota, not the user's connected
Ads account.
- Recommend retrying after Google's retry window or using a custom
OAuth/client setup with a dedicated Google Ads developer token for
production workloads.
## Tests
- `bun run lint:links`
- `bun run test`
Follow-up doc fixes from a re-audit of the June "Pi Slack-bot friction"
report against the current docs. Low-risk changes across the migration
guides, the example `.md` output, and legacy handling.
## 1. Migration guides: selective legacy + a "Written {date}" stamp
Migration guides are point-in-time documents, but not all are legacy.
Two mechanisms, decoupled:
- **`legacy: true`** (existing Legacy badge) — only on guides that
migrate off something dead: **new-sdk** (deprecated v1 SDK) and
**tool-router-beta** (removed experimental tool router).
- **`written: "{Month YYYY}"`** (new frontmatter field, dates from git
creation) — renders a standalone **"Written {date}"** stamp on *every*
guide, independent of legacy. So current guides (direct-to-sessions,
mcp-servers-to-sessions, toolkit-versioning, the hub) show their date
without being mislabeled legacy.
Files: `source.config.ts` (new `written` field),
`components/legacy-badge.tsx` (plain badge again), docs page (badge +
date row), 6 migration guides.
## 2. Real example code now in the `.md`/llms output
`<FileBuildup>` / `<RepoBrowser>` render an example's actual source
(`bot.ts`, `install.ts`, …) interactively, but they're React components
that don't serialize to markdown — so
`examples/general-agent-with-pi.md` (what an agent fetches) had all the
prose and **no code**. `mdxToCleanMarkdown` now resolves them from the
`FILE_BUILDS` registry. That example's `.md` grows **6.5 KB → 34 KB**
with the real
`createSessionTools`/`proxyExecute`/`waitForConnections`/`verifyWebhook`
code. Also fixes standup-slackbot and local-workbench.
## 3. Legacy pages: flag in `.md`, skip the current-pattern guardrail
`getLLMText` now prepends "Legacy · written {date}" (or "Written {date}"
for current-dated pages) to the `.md`, and **skips the "enforce ONLY the
current patterns" guardrail block on legacy pages** — appending it to a
legacy guide contradicted the guide's own older content (e.g. new-sdk
showing `tools.execute()` as the v3 target).
## 4. Note that `subscribe()` uses Pusher under the hood
Short aside on the triggers subscribe doc, for readers on runtimes that
restrict WebSocket clients.
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
Automated docs update triggered by SDK source changes on `next`.
- Claude reviewed the SDK diff and updated guides, FAQs, or examples
that reference changed APIs or features.
- The docs `@composio/*` dependencies were realigned to their latest
published releases so Twoslash snippets and example apps validate
against versions users can actually install.
## Review checklist
- [ ] Changes accurately reflect the new SDK behavior
- [ ] No unrelated docs were modified
- [ ] Code examples are correct and complete
- [ ] If a documented feature is not published yet, the Twoslash build
will fail — wait for the release instead of working around it
Generated by Claude Code via GitHub Actions.
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
## Summary
- Refresh the checked-in v3.1 and v3 OpenAPI snapshots from the live
backend specs using `bun run scripts/fetch-openapi.mjs`.
- Regenerate API reference index pages with `bun run
generate:api-index`.
- Surfaces `DELETE /api/v3.1/tool_router/session/{session_id}` in the
Tool Router API reference.
- Includes the other upstream generated spec changes from the same
auto-fetch, including generated API Keys and Organization Management
section indexes.
## Verification
- `bun run scripts/fetch-openapi.mjs`
- `bun run generate:api-index`
- `git diff --check`
- `bun run build`
## Notes before merge
- This is intentionally the full auto-generated OpenAPI refresh, not the
surgical two-file patch.
- The generated backend OpenAPI still contains some `internal` wording
in descriptions; left as-is to preserve the auto-generated output.
- Confirm the newly generated API Keys / Organization Management
sections are intended to publish with this refresh.
---------
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
Auto-generated Python SDK reference docs from `python/composio/`.
Regenerates pages at `docs/content/reference/sdk-reference/python/` to
reflect changes in the Python package's public API (new methods, updated
signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Documents session deletion (`session.delete()`) and realigns the docs
site's `@composio/*` dependencies so the new snippet type-checks against
a published SDK.
## Changes
- **`docs/content/docs/configuring-sessions.mdx`** — adds a `###
delete()` section with Python and TypeScript examples and a
version-requirement callout (`@composio/core` ≥ `0.13.1` / `composio` ≥
`0.17.1`).
- **`docs/package.json` + `docs/bun.lock`** — bumps `@composio/core`
`^0.9.1` → `^0.13.1` (the release that adds `delete()`) and aligns the
provider packages to their `^0.10.x`/`^0.11.0` releases (peer
`@composio/core >=0.10.0 <1.0.0`).
## Why the dependency bump
The docs site type-checks every Twoslash snippet against the
`@composio/*` versions pinned in `docs/package.json`. Those pins were
stale (`@composio/core@0.9.1`), and `delete()` only exists on the
`Session` type from `0.13.1`, so the snippet didn't compile. The
original sync run worked around this with a `DeletableSession` cast;
this PR fixes the root cause by bumping the pins to published releases
that expose `delete()` natively and dropping the cast. The full docs
build (Twoslash validation) passes against the bump.
## Review checklist
- [ ] `delete()` examples accurately reflect the SDK behavior
- [ ] Version callout matches the releases that introduce `delete()`
- [ ] No unrelated docs were modified
## Notes
- Originally produced by the `Docs - Sync guides on SDK changes` run.
- Follow-up https://github.com/ComposioHQ/composio/pull/3709 prevents
this pin drift from recurring by realigning the docs `@composio/*` deps
automatically on each SDK sync.
---------
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
## Summary
Auto-generated TypeScript SDK reference docs from
`ts/packages/core/src/`.
Regenerates pages at `docs/content/reference/sdk-reference/typescript/`
to reflect changes in the core package's public API (new methods,
updated signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
This PR:
- normalizes Python SDK reference examples generated from source
docstrings
- rewrites the `Triggers.parse()` docstring so the generated
Flask/FastAPI examples are copy-pasteable
- strips nested Markdown fences before wrapping generated examples in
MDX code fences
- regenerates `docs/content/reference/sdk-reference/python/`
- adds regression coverage for the `Triggers.parse()` generated example
and fenced example normalization
- does not include a changeset because this only changes docs
generation, generated docs, and tests
## Verification
- `cd python && .venv/bin/python -m pytest tests/test_generate_docs.py
-q`
- `cd python && .venv/bin/ruff check --config config/ruff.toml
composio/core/models/triggers.py scripts/generate-docs.py
tests/test_generate_docs.py`
- `cd python && .venv/bin/ruff format --check --config config/ruff.toml
composio/core/models/triggers.py scripts/generate-docs.py
tests/test_generate_docs.py`
- `cd python && .venv/bin/python scripts/generate-docs.py`
- `cd docs && bun install --frozen-lockfile`
- `cd docs && bun run types:check`
## What
Reworks the `/examples` index into a Modal-style **featured gallery**,
styled to the Composio brand (pulled from `~/composio/landing`): flat
editorial cards, sharp corners, mono uppercase category tags in accent
colors, the signature brand offset-shadow on hover, and real toolkit
logos on white chips.
| Light | Dark |
|---|---|
| Big `font-sans` hero, filter pills with live counts, responsive card
grid | Same, brand-consistent |
### Highlights
- **`<ExamplesGallery>`** — hero, category filter pills (Featured /
General agents / Background agents / Coding agents) with live counts,
responsive 1–3 col grid, staggered load-in.
- **Data-driven from frontmatter.** Card title/description come from
each page's own `title`/`description`. Presentation metadata lives in a
new optional `gallery` block in the frontmatter schema:
```yaml
gallery:
categories: [General agents, Background agents]
logos: [slack]
featured: true
order: 0
```
Examples can belong to **multiple category lanes** (the Pi bot is both
General + Background).
- The index route renders the gallery; nested example pages keep the
standard docs renderer.
### Drive-by fix
`PageActions` lifts a **full-width** row over the page title (`-mt-12`)
to place the "Copy page" button beside it. That invisible overlay sat on
top of the title and blocked selecting/copying it. Fixed by making the
overlay `pointer-events-none` and re-enabling them only on the button
wrapper. Affects every docs page.
## Testing
- `bun run types:check` passes.
- Verified in light + dark: titles/descriptions match page frontmatter,
multi-tag cards, filter counts, logo visibility (GitHub on white chips),
title now selectable, Copy button still clickable.
## Notes
- Category lanes are a fixed enum in two spots (`source.config.ts` enum
+ `CATEGORY_STYLES` color map in `examples-gallery.tsx`) — adding a new
lane is a two-place edit.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Adds a **Security and Data** docs section (below Triggers and webhooks)
with two pages:
- **Security** (`/docs/security/overview`) — posture, compliance and the
[Trust Center](https://trust.composio.dev), org/project isolation,
credential protection (AES-256-GCM at rest, TLS), token redaction,
webhook signing, responsibilities, and vulnerability reporting.
- **Data retention** (`/docs/security/data-retention`) — what Composio
stores, **1-year** retention, the per-project **Log storage → "Don't
store data"** option (Composio keeps an audit record but does not store
tool-call payloads), an honest **"Where your data goes"** section (data
still flows to the destination provider and sub-processors during
execution; links the [Trust Center sub-processor
list](https://trust.composio.dev/subprocessors)), and a contact-sales
path for contractual arrangements. Includes a redacted dashboard
screenshot.
Note: "Don't store data" controls what Composio retains; it is not
framed as a zero-data-retention guarantee.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Keep the default 1-hour file TTL description; remove the per-project
Settings → File TTL configurability sentence until that dashboard control
ships.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Split the "Where your data goes" file/trigger bullet: file payloads live in
object storage only for the file TTL (1h default) then expire, distinct from
trigger destinations which receive events in real time.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per the data-storage/privacy review:
- Document that the Log storage setting is forward-looking (pause/resume):
switching to "Don't store data" stops storing new payloads but does NOT
delete logs already stored, and switching back does not backfill the gap.
- Add file availability: tool-execution files are presigned URLs with a
default 1-hour TTL, configurable 1-24h per project in Settings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
New docs page: **Rate limits & usage**
(`docs/content/docs/rate-limits.mdx`, registered under "Other topics").
Closes the recurring "rate limits / suspension / SLA" support questions
(Plain SUP-807 theme) with one canonical, honest answer.
All numbers/headers verified against `apps/apollo/src/lib/ratelimit/`
(constants.ts + middleware.ts):
- **Platform limits:** per-org, fixed 1-min window; live limit in
`X-RateLimit` / `-Remaining` / `-Window-Size`; `429` + `Retry-After` on
exceed. Plan defaults (Hobby/Starter 2k, Growth 10k, Enterprise
effectively unlimited) shown as **defaults with the header as
authoritative**.
- **No automated suspension** — throttle only; the only hard block is a
manual `403`.
- **Upstream provider 429s** (Gmail/Slack/Ads) distinguished from
platform limits → BYO-OAuth (custom auth) for prod.
- **Multi-tenant**: single account + `userId` per end-user is
recommended.
- Honest gaps: **no public status page / health webhook invented**; SLA
routed to Enterprise.
Approach informed by how Nango/OpenAI/Stripe/GitHub document limits
(mechanism + headers as the contract, not a brittle per-plan matrix).
### Before merge
- [ ] **Confirm the Vercel preview build is green.** Local `bun run
build` could not be run this session due to an environment-level `bun`
`CouldntReadCurrentDirectory` fault (reproduced across worktrees,
unrelated to this change). The page **compiled + typechecked** via `node
next build`, and it contains **no twoslash code blocks** (only
python/json/bash fences), so the usual compile-break risk is absent —
but please let the preview confirm full static generation.
- [ ] Sanity-check the plan-default numbers are OK to publish (they're
real but can drift; the doc labels them defaults and points to the
header as source of truth).
- [ ] Decide whether to add a real status-page link if/when one exists
(currently omitted on purpose).
- [ ] Preview: `docs-git-docs-rate-limits-usage.preview.composio.dev`
Adds a changelog entry: the PostHog **region** (`us`/`eu`) is now a
per-connection field instead of an auth-config field. Existing
connections were migrated (default `us` stays default; non-default
values carried over), so no user action and no re-auth.
Pairs with the customer FYI email (Linear PRO-310) and Mercury PR #24717
(field relabel "Region" + corrected `us`/`eu` description).
### Before merge
- [ ] Preview renders + appears in the changelog index:
`docs-git-changelog-06-17-26-posthog-region.preview.composio.dev`
- [ ] Links resolve in preview (Link/Initiate API refs, PostHog toolkit
docs)
- [ ] Publish date `2026-06-17` still correct at merge time
- [ ] Mercury PR #24717 merged (so the dashboard field already reads
"Region" / `us`,`eu`)
Local `bun run build` green (1412/1412 static pages).
## Summary
Automated documentation updates triggered by new changelog entries
merged to next.
Generated by Codex via GitHub Actions.
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Follow-up to #2941. The "Renamed enum slugs" section of the 2026-03-28
changelog
(`docs/content/changelog/03-28-26-tool-consolidation-enum-renames.mdx`)
lists 347 Old Enum → New Enum pairs that don't line up with the actual
class-name-derived slugs delivered by mercury PR #17949 (commit
`12d585aa7e`, "fix: rename low-usage action class names to cleaner
slugs"). This PR replaces that section with the verified table.
### How slugs are formed
```python
enum = inflection.underscore(cls.__name__).upper()
slug = enum if enum.startswith(TOOLKIT) else f"{TOOLKIT}_{enum}"
```
Slug is derived from the **class name** of the action, not the file name
and not the `name` attribute. (Source: `mercury/tools/_base/action.py`
`set_metadata` / `set_tool`.)
### Audit results vs. existing docs section
| Category | Count |
|---|---|
| Original docs pairs that match PR #17949 exactly | 291 |
| Pairs with **wrong New Enum** (PR's actual new differs) | 1 |
| Pairs whose **old class never existed** in any commit | 5 |
| Pairs that refer to renames done in **other PRs** (or tool removals) |
20 |
| Pairs claiming a rename **that never happened** (old class still
present at HEAD with original slug) | 30 |
| **Real PR #17949 renames missing from docs and still valid at HEAD** |
**1,153** |
| Total entries originally listed | 347 |
| Total entries in this rewrite | **1,445** |
### Notable corrections
- `SUPABASE_UPDATES_PROJECT_S_SUPAVISOR_CONFIG` → docs said
`SUPABASE_UPDATE_SUPAVISOR_CONFIG`; **actual** is
`SUPABASE_UPDATE_PROJECT_SUPAVISOR_CONFIG` (class
`UpdateProjectSupavisorConfig` at
`apps/supabase/actions/generated/updates_project_s_supavisor_config.py`).
- `SLACK_DELETE_MESSAGE` is **not a real slug**. The chat-deletion
action is class `DeletesAMessageFromAChat`, slug
`SLACK_DELETES_A_MESSAGE_FROM_A_CHAT`. Removed from the table.
- All eight `PIPEDRIVE_*A_*` entries (`ADD_A_DEAL`, `ADD_A_NOTE`,
`DELETE_A_PERSON`, `GET_DETAILS_OF_A_PERSON`,
`LIST_PARTICIPANTS_OF_A_DEAL`, `UPDATE_A_DEAL`, `UPDATE_A_LEAD`,
`UPDATE_A_PERSON`) still exist at HEAD with their original slugs —
removed from the renames table.
- 14 Slack entries that claimed renames (e.g. `SLACK_FETCH_TEAM_INFO` →
`SLACK_GET_TEAM_INFO`) were never executed; class names still match the
original slug. Removed.
- Whole toolkits previously omitted that PR #17949 actually renamed and
that remain valid at HEAD: PostHog (179), Trello (63), Salesforce (41),
Vercel (39), Twitter (36), Google Analytics (25), Dropbox (18), Icypeas
(5), Reddit (2), YouTube (2), Apollo, Facebook, Hyperbrowser, Telegram
(1 each).
### Front-matter description / intro paragraphs
Updated count from "1,545 enum slugs across 24 toolkits" → "1,445 enum
slugs across 37 toolkits" to match the rewritten table.
### Out of scope
This PR does **not** change the "Deprecated tools" or "Consolidated
(removed) tools" sections — those describe a different consolidation
effort and are unrelated to the class-rename audit.
## Test plan
- [ ] Spot-check 10–20 random entries from the rewritten table against
the actual class definition in `mercury` (`apps/<toolkit>/actions/`) to
confirm `inflection.underscore(cls.__name__).upper()` matches the listed
New Enum.
- [ ] Confirm `<Accordions>...</Accordions>` block renders correctly on
`docs.composio.dev` preview.
- [ ] Confirm none of the 30 "rename never happened" entries listed in
the audit show up in the new table.
---------
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Fold the guide content (platform vs upstream-provider 429s, backoff recipe,
no-automated-suspension note, multi-tenant guidance) into the existing
reference/rate-limits.mdx + its v3 copy. Remove the new docs/rate-limits.mdx
and its nav entry. Single source of truth, no cross-page drift.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Summary\n- show project API key permission endpoints with
/api/{version}/... placeholders instead of duplicating versioned rows\n-
keep proxy execute documented for direct and session proxy paths\n\n##
Verification\n- bun run lint:links from docs/\n- git diff --check
## What
Removes the incorrect `alias` references from the initiate-to-link
migration guide
(`docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx`).
## Why
The `alias` parameter does **not** exist on either method:
- TS: `composio.connectedAccounts.link()` /
`composio.connectedAccounts.initiate()`
- Python: `composio.connected_accounts.link()` /
`composio.connected_accounts.initiate()`
This was verified against the SDK source and the generated client. The
doc should not claim the parameter exists. Real alias/label support may
be added later; this change only corrects the docs for now.
## Changes
- Dropped `alias` from the sentence: `` `callback_url` / `callbackUrl`
works the same way on both methods. ``
- Deleted the `` | `alias` | ✓ | ✓ | `` row from the comparison table.
No other content changed (`callback_url`, `allow_multiple`, `config`
rows are intact).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
- Add a Notion FAQ entry for connection expiry reasons.
- Cover user-initiated revocation/removal from Notion workspace
connections.
- Cover the same-user/same-OAuth-app reconnection pattern that can leave
older Composio-managed connections with stale tokens.
## Validation
- `git diff --check`
- `bun run scripts/validate-links.ts` could not run because `bun install
--frozen-lockfile` fails with existing docs lockfile drift: `lockfile
had changes, but lockfile is frozen`.
## Summary
The TypeScript SDK reference generator (`generate-docs.ts`) strips every
`api/vN/...` substring from JSDoc descriptions to keep raw endpoint
paths out
of user-facing docs. The blanket regex also strips paths that live
**inside
intentional inline-code spans**, mangling them.
Concretely, `ConnectedAccounts.initiate()`'s JSDoc:
> The legacy `` `POST /api/v3/connected_accounts` `` endpoint that this
method …
currently renders in the generated reference as:
> The legacy `` `POST `` endpoint that this method …
— content lost and an unclosed code span. (Visible today in
`docs/content/reference/sdk-reference/typescript/connected-accounts.mdx`.)
## Fix
In `extractDescription`, split the text on inline-code spans and only
strip
bare API paths **outside** backticks; deliberate route references inside
code
spans are left intact. The path regex is also tightened to stop at
code-span
and punctuation boundaries (`` ` ``, `)`, `,`, `.`, `;`).
The single affected reference page is regenerated in the same commit.
## Verification
- `pnpm --filter @composio/core generate:docs` → only
`connected-accounts.mdx`
changes, restoring the full `` `POST /api/v3/connected_accounts` ``
span.
## Context
Salvaged from the now-superseded #3518 — re-derived against the current
generator. The rest of #3518 (drift-gate workflow, regenerated MDX,
generator
rework) is obsoleted by the post-merge auto-regeneration workflow
(`generate-sdk-docs.yml`) and #3613.
## Summary
Auto-generated TypeScript SDK reference docs from
`ts/packages/core/src/`.
Regenerates pages at `docs/content/reference/sdk-reference/typescript/`
to reflect changes in the core package's public API (new methods,
updated signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Auto-generated Python SDK reference docs from `python/composio/`.
Regenerates pages at `docs/content/reference/sdk-reference/python/` to
reflect changes in the Python package's public API (new methods, updated
signatures, changed types).
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
Updates the scoped project API key permissions reference with the routes
cataloged in ComposioHQ/platform#10638 (PLEN-2623):
- **Sessions** — now covers MCP server management (`/mcp/servers*`,
`/mcp/{id}`, instances), the MCP runtime transport, and the tool router
MCP transport
- **Tool execution** — adds `POST /files/upload/response` and `GET
/files/list` (file legs of tool execution)
- **Triggers** — adds the SDK/CLI realtime subscribe endpoints
(`triggers.subscribe()` / `composio triggers listen`)
Tables mirror `PROJECT_API_KEY_PERMISSION_CATALOG` as of the platform
merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Alberto Schiabel