This PR:
- bumps Python `composio` and all 13 provider packages to `0.22.0`
- regenerates `uv.lock` and adds the coordinated Python and TypeScript
release changelog
- records the manually published `@composio/typesafe@0.1.0` as the
repository baseline
- replaces the original TypeSafe minor changeset with a patch release
for `0.1.1`, so post-publication runtime fixes ship instead of being
skipped
- keeps the existing Changesets train for `@composio/core@0.19.0`,
`@composio/slim@0.19.0`, and provider updates
- verifies the release workflow, changesets, all 20 TypeScript package
builds, 147 TypeSafe tests, 590 docs static tests, and all 28 Python
distributions with Twine
This PR:
- reopens https://github.com/ComposioHQ/composio/pull/4472 (D3) directly
against `next`; the original was merged into the D2 branch by mistake,
and https://github.com/ComposioHQ/composio/pull/4471 has been trimmed
back to D2 only
- cherry-picks the original D3 commit unchanged onto `next` (ba59d21c9)
- adds a "Session restrictions" section to the Proxy execute page:
toolkit enable and disable lists apply to proxy calls, including from
the sandbox; hint filters and per-toolkit tool rules do not; example
that turns proxy execution off with `sandbox={"enable_proxy_execution":
False}` / `sandbox: { enable: true, enableProxyExecution: false }`
- adds one sentence in the Configuring Sessions sandbox section pointing
to that section
- merge after: ComposioHQ/platform#12847 (enforce toolkit lists on the
session proxy execute route). Kept as a draft until that ships so it
cannot be merged out of order again
PRD:
https://app.notion.com/p/composio/Session-Governance-via-hints-Across-toolkits-3daf261a6dfe80df8e0ce337a2b26e08
Linear workstream:
https://linear.app/composio/project/sessions-execution-governance-a0942233a0d0
Verification, run in `docs/` on this branch: `bun run types:check`
passes, `bun run lint:links` reports 0 errors. `pnpm exec prettier
--check` flags the touched mdx files on `next` already, so no
reformatting was applied.
---------
Co-authored-by: Palash Kala <palash@composio.dev>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Brendan O'Leary <brendan@olearycrew.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
This PR:
- replaces https://github.com/ComposioHQ/composio/pull/4474 (D5), which
was merged into the D2 branch by mistake and conflicted with the
rewritten permissions reference on `next`;
https://github.com/ComposioHQ/composio/pull/4471 has been trimmed back
to D2 only
- rewrites the change against the current "Session tool execution" /
"Proxy execute (Legacy)" layout instead of the pre-rewrite page the
original targeted
- Session tool execution: drops the
`/tool_router/session/{session_id}/proxy_execute` row and says proxy
execution is not included; Proxy execute (Legacy): states it is the only
permission that grants the session proxy route, from
`session.proxyExecute()` or from the session's sandbox
- Proxy execute page callout: requires Proxy execute; Session tool
execution alone does not cover it
- KB article `platform-project-api-key-permissions` (source under
`docs/kb/articles`, generated guide regenerated with `bun run
generate:kb`): same correction
- merge after: ComposioHQ/platform#12846. Until it deploys, `next` is
correct and this page must not go live. Kept as a draft for that reason
PRD:
https://app.notion.com/p/composio/Session-Governance-via-hints-Across-toolkits-3daf261a6dfe80df8e0ce337a2b26e08
Linear workstream:
https://linear.app/composio/project/sessions-execution-governance-a0942233a0d0
Verification, run in `docs/` on this branch: `bun run types:check`
passes, `bun run lint:links` reports 0 errors. `pnpm exec prettier
--check` flags the touched mdx files on `next` already, so no
reformatting was applied.
## 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>
## Summary
Updates the Scoped Project API Key reference page to match the backend
fix in ComposioHQ/platform#13062
([PLEN-3940](https://linear.app/composio/issue/PLEN-3940/scoped-api-keys-post-toolkitsmulti-is-cataloged-as-write-so-read-only)).
`POST /toolkits/multi` only fetches toolkits, but it was cataloged as
the single write route of the Toolkits permission area, so a read-only
key got a 403 on it. The backend now treats it as a read, which leaves
Toolkits with no write routes.
- `/toolkits/multi` row: Write -> Read
- Toolkits available levels: "No access, Read only" (was all four
levels)
- Toolkits description: "View toolkits." (was "View and install
toolkits.")
## Merge order
Merge after ComposioHQ/platform#13062 is deployed, so the page does not
describe behavior that is not live yet.
Not in this PR: a changelog entry. It needs the backend deploy date.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.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>
## 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).
## Why
Requirement 1 of the PRD: sessions accept all four verdict hints. The
Configuring Sessions tag table listed the four MCP-spec hints, two of
which (idempotentHint, openWorldHint) are set on a minority of tools.
Every tool carries at least one of readOnlyHint, createHint, updateHint,
destructiveHint.
## What
- Tag table leads with the four verdict hints and says every tool
carries at least one; idempotentHint and openWorldHint noted as accepted
with partial coverage.
- Callout: the v3 tools endpoints default to the pinned version
00000000_00, sessions read latest.
- Python example uses createHint. The TypeScript twoslash example stays
on readOnlyHint so docs CI passes against the published SDK; switch it
to createHint when merging, after #4467 is released.
- Python and TypeScript SDK reference docs list the widened enum.
## Merge after
API: platform#12843 (accept createHint and updateHint). SDK:
composio#4467 released.
PRD:
https://app.notion.com/p/composio/Session-Governance-via-hints-Across-toolkits-3daf261a6dfe80df8e0ce337a2b26e08
Linear workstream:
https://linear.app/composio/project/sessions-execution-governance-a0942233a0d0
Stack order (merge top to bottom, each after its API change is
deployed): D1 verdict hints, D2 precedence, D3 proxy execute toolkit
lists, D4 MCP classification, D5 proxy execute API key permission.
Verification, run in `docs/` at the top of the stack (D5 head, which
contains this PR): `bun run types:check` passes, `bun run build`
compiles (twoslash blocks type-check against the published
`@composio/core`), `bun run lint:links` reports 0 errors, `bun run test`
568 pass. `pnpm exec prettier --check` flags the changed mdx files on
`next` already, so no reformatting was applied.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01VHkYsmhteM1jJQoaoruiP3
Strava is no longer in the toolkit catalog (public/data/toolkits*.json
has no strava entry), so drop its orphaned FAQ page, KB guide, and
KB source/manifest/registry entries.
kb/semantic-index.json will go stale from the manifest change; it
regenerates via the existing "Docs - Rebuild KB Semantic Artifact"
workflow (or `bun run build:kb-semantic`).
## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
## Why
Support and customers (e.g. athena) keep asking how to tell apart
multiple connected accounts under one auth config. Platform
[#12507](https://github.com/ComposioHQ/platform/pull/12507) +
[#12519](https://github.com/ComposioHQ/platform/pull/12519) shipped an
auto-populated provider identity for this, but the docs never mention
it. Closes the docs follow-up on
[PLEN-3541](https://linear.app/composio/issue/PLEN-3541).
## What
One line in the **Aliases** section of *Managing multiple connected
accounts*: to identify an account by its provider-side identity (Gmail
address, GitHub username), read the read-only `display_name` Composio
auto-populates at `state.val.displayName` once the connection is active
— distinct from the user-set `alias`.
## Impact
Docs-only. No code, no API change.
## Rollout
The feature is currently in staging; merge/publish once PLEN-3541 is
live in prod.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Explains how to identify a connected account by its provider-side
identity (state.val.displayName), separate from the user-set alias.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This PR:
- fixes the raw `:raises ...:` reST directives leaking into the
generated Python SDK reference, flagged by [Greptile on the
auto-generated docs
PR](https://github.com/ComposioHQ/composio/pull/4479#discussion_r4004672537)
- teaches `python/scripts/generate-docs.py` to parse `:raises Exc:`
docstring fields (plus `:raise`/`:except`/`:throws` synonyms) into a
structured `**Raises**` section, with indented continuation-line support
- normalizes inline reST in all rendered prose:
`:class:`/`:func:`/`:meth:`/`:mod:` roles honor `~` short-name
semantics, and double-backtick literals become single-backtick inline
code
- regenerates `docs/content/reference/sdk-reference/python/` pages
- adds regression tests for raises parsing and reST normalization in
`python/tests/test_generate_docs.py`
## Context
The Python SDK reference pages are generated by
`python/scripts/generate-docs.py` (workflow: `generate-sdk-docs.yml`),
so the fix lives in the generator rather than the MDX — hand-edits would
be overwritten by the next auto-regen PR. Unrecognized `:raises` lines
previously fell through into the `:returns:` description text.
## Summary
`PusherService.subscribe` binds `pusher:subscription_error` after the
Pusher subscription call returns. `pusher-js` dispatches this event
asynchronously without catching listener exceptions, so authentication,
permission, server, or network subscription failures could escape as
uncaught exceptions in Node applications.
Fixes#4445
## Changes
- Log asynchronous Pusher subscription errors at the SDK error boundary
instead of throwing from the event callback.
- Add regression coverage that emits `pusher:subscription_error` after
`subscribe()` resolves and verifies that it does not throw.
- Add a patch changeset for the fixed `@composio/core`/`@composio/slim`
package group.
## Type of change
- [x] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [ ] Documentation
- [ ] Breaking change
## How Has This Been Tested?
- Node `v24.17.0` / pnpm `11.8.0`
- `pnpm --filter @composio/core exec vitest run
test/services/pusher.test.ts test/utils/pusher.test.ts` — 2 files, 5
tests passed
- `pnpm --filter @composio/core test` — 55 test files passed; 1,289
tests passed and 2 existing tests reported expected failures; command
exited successfully
- `pnpm --filter @composio/core typecheck`
- `pnpm lint` — passed with existing repository warnings
- `pnpm validate:changesets`
- `pusher-js` `v8.6.0` runtime probe confirmed that an exception thrown
from a `pusher:subscription_error` listener reaches Node's
`uncaughtException` handler; the regression test verifies the SDK
callback no longer throws.
## Screenshots (if applicable)
Not 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
This patch is intentionally limited to the live `PusherService` path.
XHR timeout handling is a separate concern and is not included here. The
older unreferenced `PusherUtils` helper is unchanged to keep this fix
scoped to the path used by `Triggers`.
pysher performs the channel-auth request synchronously inside
pusher.subscribe(), so an auth rejection raised on the websocket thread
before pusher:subscription_error could ever be bound or fire. The new
on_subscription_error callback was skipped for exactly the failures it
documents, and callers waited out the full connect timeout for a
generic ComposioSDKTimeoutError.
- _connection_handler catches subscribe() failures and routes them
through the error path (log + callback with {'error': ...}).
- The failure is recorded on the subscription and the connect() wait
loop re-raises it on its next poll, so subscribe() fails promptly
with the underlying error and still tears down the pusher.
- Update the Python reference, guide, and docstrings; add regression
coverage for the handler routing, the failure record, and fast-fail.
Addresses the Cursor Bugbot comment on triggers.py:1023.
## Summary
Adds canonical guidance for common Composio product-integration
decisions and makes the main paths easy to find from the Knowledge Base
homepage. This PR is independent of #4258 and #4277 and targets `next`
directly.
## Changes
- Add guides for the Composio skill, consumer-agent architecture,
B2B-agent architecture, and moving from prototype to production
- Expand the white-labeling guide with a minimal setup path and FAQ
- Add five Start here cards to `/kb`, before support topics and toolkit
browsing
- Update OAuth callback examples and add relevant sidebar and quickstart
cross-links
## Type of change
- [x] Documentation
## How Has This Been Tested?
- `bun test tests/static/` (528 passed)
- `bun run lint:links`
- `bun run types:check`
- `bun run lint`
- `bun run build`
## 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 and structural homepage coverage
- [x] No changeset is required for docs-only changes
Mirror the TypeScript API surface from the previous commit:
- Triggers.subscribe accepts an optional on_subscription_error callback,
threaded through _SubcriptionBuilder.connect and bound to pysher's
pusher:subscription_error event on the trigger channel.
- TriggerSubscription._handle_subscription_error logs the failure at the
SDK boundary and invokes the callback with the parsed payload (or
{'raw': frame} for malformed frames); callback exceptions are
contained and logged so a faulty handler cannot tear down pysher's
dispatch thread.
- The parameter is optional; existing callers are unaffected.
- Update the Python triggers reference and the subscribing-to-events
guide.
Python never bound pusher:subscription_error at all, so subscription
failures after connect() were previously invisible to hosts.
- PusherService.subscribe and Triggers.subscribe accept an optional
onSubscriptionError callback invoked with the raw pusher
pusher:subscription_error payload, giving hosts a programmatic signal
for post-resolution subscription failures (previously log-only).
- Exceptions thrown from the callback are contained and logged, never
rethrown, so a faulty handler cannot crash the host.
- The parameter is optional; existing callers are unaffected.
- Document the new parameter in the TypeScript triggers reference and
the subscribing-to-events guide; bump the changeset to minor for the
new API surface.
Applies review finding #1 from the PR #4448 review.
Atomic Agent is a local-first agent (CLI and TUI) that ships a built-in
Composio integration: it connects to the hosted tool router over
Streamable HTTP MCP, so tools are registered at startup as
mcp.composio.*.
Setup is done from the Integrations tab or by adding COMPOSIO_API_KEY to
the agent's .env, so the entry documents that flow rather than the CLI
install used by other terminal agents.
- parse :raises Exc: docstring fields (plus Sphinx synonyms) into a
structured Raises section instead of leaking raw directives into the
Returns description
- normalize inline reST in all rendered prose: roles (:class:, :func:,
:meth:, ...) honor ~ short-name semantics; double-backtick literals
become single-backtick inline code
- regenerate docs/content/reference/sdk-reference/python/ pages
- add regression tests for raises parsing and reST normalization
Flagged by Greptile on the legacy-repo auto-PR (ComposioHQ/composio#4479).
`composio --version` goes from 288ms to 199ms, peak RSS from 97.8MB to
77.3MB, and the executable from 85.9MB to 79.7MB. Every command benefits.
A compiled Bun binary parses its whole embedded bundle before the first
line of JavaScript runs, and #4468 had already made sure the TypeScript
compiler and the tokenizer rank table were never *evaluated* unless
`generate`, `run`, or a large `execute` response needed them. They were
still *parsed* on every start: the compiler alone was 44% of the
executable's JavaScript and the o200k rank table another 28%, so
`--version` spent ~75ms reading code it could never call.
Both now ship as companion modules next to the executable, through the
mechanism `composio run` already uses for its own runtime helpers:
- `generation-runtime.mjs` carries `src/generation/*`, the `composio run`
source rewrites, `typescript`, `@composio/ts-builders` and
`openapi-typescript`. `generate ts`, `generate py` and `run` load it
with `loadInstalledCompanionModule`; from a source checkout the loader
resolves the `.ts` next to `run-companion-modules.ts` instead, so tests
and `bun run src/bin.ts` need no build step.
- `execute-output-encoder-runtime.mjs` carries `js-tiktoken/lite` and the
rank table. `execute` loads it only once a response exceeds the 10KB
byte pre-filter.
A companion bundles its own copy of `effect`, and a fiber cannot run
primitives built by another copy of the runtime, so nothing Effect-shaped
crosses the boundary: the generation companion exposes plain functions
and promises, runs its pipelines on its own runtime, and returns failures
as values that `src/generation/errors.ts` rebuilds as the CLI's own error
classes, stack included. Generated output is byte-identical to #4468 for
`generate ts`, `generate ts --transpiled` and `generate py`.
Both modules join `RUN_COMPANION_MODULE_BASENAMES`, so the build, release
packaging, install verification, `upgrade` and the self-repair download
pick them up unchanged. The three hand-maintained uninstall lists and the
upgrade E2E fixture gain the two file names.
Two smaller startup costs go with it:
- `src/constants.ts` imported `constants` from `@composio/core`'s root
entry for two strings and two URLs, which evaluated the whole SDK at
startup (~25ms of module-scope work, mostly zod schemas). The four
values are spelled out and pinned to core's by a test.
- `tool-file-uploads.ts` imported three core helpers at module scope that
only a file upload reaches; they are imported on that path now.
The binary build gains a guard: after bundling the companions it bundles
`src/bin.ts` once more unminified and fails if the executable's graph
reaches `typescript`, `js-tiktoken`, core's root entry, `src/generation/*`
or a companion entry. Without it a stray static import would put the
compiler back into the executable with nothing to notice.
Building also surfaced that `assertBundledRuntimeFiles` blanked string
literals to same-length runs of spaces, which made the import patterns'
`^\s*` backtrack quadratically across the compiler's multi-megabyte
embedded lib strings and stalled the build for over ten minutes. String
bodies are dropped now. (The check itself has never matched a specifier,
since the specifiers it looks for are the string literals it removes;
that is left as it was.)
Measured on the pinned toolchain, Bun 1.4.1+4661e494f, linux-x64, best
of 15, telemetry disabled, both binaries built in the same session:
composio --version 288ms -> 199ms
tools execute --help 287ms -> 202ms
peak RSS 97.8MB -> 77.3MB
executable 85.9MB -> 79.7MB
executable JavaScript 8.3MB -> 2.1MB (minified)
The `execute` tail after `execute.tool_call.end` is unchanged for
responses under 10KB (~10ms) and ~20ms slower above it (351 -> 374ms),
which is the on-demand parse of the 2.2MB encoder companion.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wx9gEjuiHux2weiHjdNcDs
Alberto Schiabel