This PR:
- prepares the coordinated September 4 changelog for CLI `0.4.1`, Python
SDK `0.21.1`, and the TypeScript SDK release
- gives DevRel one customer-facing source for credential security, file
transfers, JSON Schema behavior, and custom-tool routing
- records the TypeScript provider and schema-converter package matrix,
including the releases added after #4316 merged
- adds the `@composio/core` `0.18.1` row that the refreshed release PR
#4285 now requires
- corrects the download-limit guidance and documents the fallback for a
`$ref` without matching `$defs`
The listed versions are coordinated release targets. They are not all
published yet, so this changelog and the release PRs still need to be
sequenced together.
## Verification
- `pnpm exec prettier --check
docs/content/changelog/09-04-26-cli-and-sdk-releases.mdx`
- `cd docs && bun run types:check`
- `cd docs && bun run lint:links`
- `cd docs && bun run test` (541 passed)
- `pnpm test:release-workflow`
## 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
The Python SDK treated a custom tool's `original_slug` as globally
unique, rejecting valid custom toolkits that reuse common child names
such as `SEARCH`, `VERSION`, or `GREP` even though the backend-assigned
final slugs are toolkit-qualified (`LOCAL_ALPHA_GREP`,
`LOCAL_BETA_GREP`).
This ports the toolkit-qualified lookup from #3360 to Python, then fixes
three response-mapping bugs found in review and applies the same fixes
to the TypeScript SDK so both stay in parity.
## Changes
### Python (`composio`)
- Scope custom-tool collision detection and response matching by toolkit
plus original slug.
- Keep bare original-slug aliases only when unambiguous;
`session.execute("GREP")` raises with the final slugs to use when the
slug is shared.
- Preserve toolkit-qualified final slugs in `custom_toolkits()`.
- `build_custom_tools_map_from_response`: raise when a response tool has
local handles but no exact toolkit match instead of silently dropping it
or binding another toolkit's handler; only fall back to a bare match
when the response carries no toolkit identity; reject duplicate
qualified response entries; derive bare-slug ambiguity from local
definitions so omitting a sibling in the response never makes the
survivor callable by bare name.
- `custom_toolkits()` only reuses a bare alias that belongs to the same
toolkit.
- Docstring and Python session reference page state that bare-slug
execution requires a unique original slug.
### TypeScript (`@composio/core`)
- Same four fixes in `buildCustomToolsMapFromResponse` and the same
guard in `customToolkits()`.
- JSDoc and TypeScript session reference page updated.
- Changeset: patch for `@composio/core`.
### Not changed
- `COMPOSIO_MULTI_EXECUTE_TOOL` still aborts the whole batch when one
item uses an ambiguous bare slug, matching current TS behavior.
Switching to per-item errors is a cross-SDK design change left for a
follow-up.
## Type of change
- [x] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [ ] Documentation
- [ ] Breaking change
## How Has This Been Tested?
Python:
- `pytest tests/test_custom_tools.py tests/test_tool_router.py`: 181
passed.
- ruff (project config) clean; mypy reports no errors in the touched
files.
- New tests: sibling routing, multi-execute, preload rejection, listing
guard, and five response-mapping cases (no exact match, cross-toolkit
binding, standalone bare fallback, unknown response tools skipped,
ambiguity from local definitions, duplicate qualified entries).
TypeScript:
- `vitest run` in `ts/packages/core`: 53 files, 1251 passed, 2 expected
failures.
- `tsc --noEmit` clean; prettier and oxlint via pre-commit hook.
- New tests: cross-toolkit reuse in `buildCustomToolsMap` and a new
`buildCustomToolsMapFromResponse` block mirroring the Python cases.
Python and TypeScript CI do not run automatically on this fork PR; a
maintainer needs to approve the workflow run.
## 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
Reviewed with a second opinion from Codex (gpt-5.6-sol), which flagged
the wrong-handler binding and response-derived ambiguity bugs fixed in
the follow-up commits.
https://claude.ai/code/session_01Y7Ni3QEBDGShSrEtwQS5bA
EOF -R ComposioHQ/composio
---------
Signed-off-by: CoralGarden52 <2193436736@qq.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
## Summary
Composio's new pricing went live on Aug 15, 2026: **Hobby** ($0) /
**Pro** ($29/mo) / **Enterprise** (custom). This PR updates the public
docs to describe only the current offering and reprices premium tools as
pass-through (provider cost + 5% platform fee).
## Principle
- Docs describe the **current** plans only (Hobby / Pro / Enterprise).
No Starter/Growth tables, no dual documentation.
- Where a legacy note is genuinely useful (rate limits), exactly one
sentence pointing pre-Aug-15 customers to
https://composio.dev/pricing/legacy.
- **Link to https://composio.dev/pricing instead of repeating numbers**,
so future price changes are a one-place edit.
## Files changed
- `docs/content/toolkits/pro-tools.mdx` — replaced the "3x the cost"
line and the Totally Free / Ridiculously Cheap / Serious Business tier
table with pass-through pricing copy: paid third-party providers,
provider price + 5% platform fee (no markup), per-call prices on the
pricing page's "Premium tools" section, Hobby includes up to $2/mo of
premium tool usage, prices depend on provider and can change with
advance notice. Retitled the page from "Pro Tools" to "Premium Tools"
(matches the pricing page and avoids confusion with the new Pro plan).
URL slug `/toolkits/pro-tools` is unchanged so no links break. Rest of
the page (what counts as a premium tool, rate limits) intact.
- `docs/content/reference/rate-limits.mdx` +
`docs/content/reference/v3/rate-limits.mdx` (manual copies, updated
identically) — plan table now Hobby 2,000 req/min · Pro 10,000 req/min ·
Enterprise Custom (kept the doc's existing per-minute unit and "Custom"
wording for Enterprise). No legacy/grandfathering note — docs describe
current plans only; grandfathered customers are served by the dashboard
and composio.dev/pricing/legacy.
- `docs/app/llms.mdx/[[...slug]]/route.ts`,
`docs/components/toolkits/toolkits-landing.tsx` — label text "Pro Tools"
→ "Premium Tools" (link targets unchanged).
## Not changed / notes for reviewers
- `docs/content/docs/common-faq.mdx` no longer exists on `next` (removed
in the sessions-first rewrite, #3637); a grep for self-host / on-prem
across `docs/content` found **no** page advertising self-hosting as an
Enterprise feature, so nothing to remove there.
- Grep sweep (case-insensitive) over `docs/content` for: Starter, Growth
plan/tier, Ridiculously, Serious Business, Totally Free, on-prem,
self-host(ed), $229, $599, 20k tool calls, 200k, per seat, per-seat, 3x
the cost. All customer-facing hits were in the three files above and are
fixed. Left alone:
- `changelog/*` — historical entries (self-hosted Supabase/PostHog
instances, "self-hosted deployments need backend version X"); these
refer to third-party instances or historical SDK notes, not to an
Enterprise plan feature.
- `docs/auth-configuration/custom-auth-configs.mdx:23`,
`docs/authentication/custom-app-vs-managed-app.mdx:30` — "self-hosted"
refers to the *customer's* self-hosted third-party app (e.g. Salesforce
subdomain), unrelated to Composio plans.
- `docs/configuring-sessions.mdx`, `docs/sandbox/remote.mdx` —
"Sandboxes are not billed today" note; not part of this change, flagging
in case sandbox billing status changed with the new pricing.
- `pro-tools.mdx` "Rate limits" table: **fixed in `421789d90`** —
dropped the "Standard Tool Calls" column (100/min · 5,000/min
contradicted `reference/rate-limits.mdx`), kept only the
premium-execution limiter mapped to plan names (Hobby 1,000/hr · Pro
10,000/hr · Enterprise Custom) with a note that it is separate from the
org API limit. Also added Pro's premium allowance bullet.
## Validation
- `bun run lint` (oxlint): passes; only pre-existing warnings in
untouched files.
- `bun run lint:links` (`scripts/validate-links.ts`): 0 errors.
## Related PRs
- landing: https://github.com/ComposioHQ/landing/pull/289
- platform: https://github.com/ComposioHQ/platform/pull/12078
- dashboard: https://github.com/ComposioHQ/dashboard/pull/1326🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01P3JgWs8DcjeQTRKoJd8gmQ
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This PR:
- closes#4323
- removes the unsupported Go SDK setup from the harness integration
example
- removes the dead `ComposioHQ/composio-go` link that breaks the nightly
external-link sweep
- verifies both internal and external docs link validation
## Summary
Explain the motivation and context for this change. Link to any related
issues.
Fixes #
## Changes
-
-
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [ ] Documentation
- [ ] Breaking change
## How Has This Been Tested?
Describe the tests you ran and instructions so reviewers can reproduce.
Include any relevant config/versions.
## Screenshots (if applicable)
## Checklist
- [ ] I have read the Code of Conduct and this PR adheres to it
- [ ] I ran linters/tests locally and they passed
- [ ] I updated documentation as needed
- [ ] I added tests or explain why not applicable
- [ ] I added a changeset if this change affects published packages
## Additional context
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## 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
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@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).
## 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).
MastraProvider strict mode used the root-only, input-mutating
removeNonRequiredProperties, so "strict" meant something different from
the OpenAI providers. It now runs the same toStrictJsonSchema rewrite:
optional parameters become required-nullable, tools strict mode cannot
express keep their original schema with a warning, and null arguments the
tool schema rejects are dropped before execution.
Co-authored-by: AseemPrasad <aseemprasad0520@gmail.com>
Claude-Session: https://claude.ai/code/session_01TDrxCHn2hg51HmxVstSUgs
VercelProvider strict mode now widens optional parameters to nullable
instead of dropping them, keeps the original schema for tools strict mode
cannot express, and drops null arguments the tool schema rejects before
execution. The README and docs page described the old dropping behavior.
Co-authored-by: AseemPrasad <aseemprasad0520@gmail.com>
Claude-Session: https://claude.ai/code/session_01TDrxCHn2hg51HmxVstSUgs
Nightly external-link sweeps (#4205) failed on four KB URLs that are
machine identifiers, not documents: Google OAuth scope URIs
(googleapis.com/auth/meetings.space.*) and Ahrefs API surface roots
(api.ahrefs.com/v3, the wrong-host ahrefs.com/v3). Support prose cites
them bare, the KB generator copied them verbatim, and GFM autolinks
published them as links that 404 by design — unfixable by pointing them
anywhere.
The generation layer now demotes bare citations and <url> autolinks of
these identifier shapes to inline code spans, matching the convention
sibling KB articles already use. Explicit markdown links keep their
authored form. Regenerated the two affected guides.
Verified: bun run test (506 pass), bun run lint:links,
bun run lint:links:external (0 errors — the failing nightly command),
bun run types:check, bun run generate:kb --check.
Follow-up: docs/kb/semantic-index.json needs a rebuild with
OPENAI_API_KEY (bun run build:kb-semantic) because four embedded record
chunks changed.
## 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>
Co-authored-by: jkomyno <alberto@composio.dev>
## Summary
- Adds a `warn` callout under the quickstart's Python install step: the
current package is `composio`; `composio-core` and `composio-openai` are
the legacy v1 SDK — do not install them.
- Names the legacy package names explicitly in the migration guide's
intro, so searches for those names land on the migration path.
## Why (measured)
From the docs-agent-eval transcripts (202 agent runs, waves 4–5): **85%
of agents on prod docs and 63% on the current IA attempt a
legacy-package install first**, then discover the mistake, uninstall,
and redo — **+64s (+14%) mean build time**. The failure mode is visible
verbatim in transcripts: after reading the quickstart, agents search
"how to install **composio-core or composio** python package" — the docs
never disambiguated. LLM training priors will keep suggesting the old
names; the install step is where the correction lands.
## Deliberately out of scope
- Package-registry fixes (PyPI DEPRECATED banner on composio-core,
`python_requires>=3.10` on composio — currently installs on 3.9 then
crashes on import) — SDK-side, being raised separately.
- A machine-readable current-versions manifest — follow-up proposal.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Soumya Medapati <soumyamedapati@mac.local.meter>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
> ### ⚠️ Breaking change
>
> `proxy_execute()` now returns a dict instead of the generated
`SessionProxyExecuteResponse` model. Every caller since `py@0.11.4` that
reads the result with attribute access breaks at runtime with
`AttributeError`.
>
> ```python
> # before
> response.status
>
> # after
> response["status"]
> ```
>
> `data`, `headers`, and `binary_data` follow the same rule. No version
bump or changelog entry ships in this PR. That omission is deliberate,
so the release call stays explicit. Details below.
## Summary
Builds on @AseemPrasad's #4163, which spotted a real problem. Python's
`proxy_execute()` returns the generated client's
`SessionProxyExecuteResponse` directly, while TypeScript's
`proxyExecute()` projects onto a curated shape. Returning the generated
model leaks a regenerated artifact into a public SDK return type.
This PR keeps that fix and resolves the review findings on top. #4163's
commit is preserved with its original authorship. The commits on top
carry the correction and the review fixes.
## What changed relative to #4163
| | #4163 | Here |
|---|---|---|
| Key casing | `binaryData`, `contentType`, `expiresAt` | `binary_data`,
`content_type`, `expires_at` |
| `status` type | declared `int`, returned `200.0` | declared `int`,
returns `200` |
| Test doubles | `SimpleNamespace` | real `SessionProxyExecuteResponse`
/ `BinaryData` |
| `mypy` | fails `nox -s chk` | clean |
| Docs | 3 snippets left broken | fixed |
**Casing.** Python public APIs use snake_case and TypeScript public APIs
use camelCase. The fields and their meanings match across SDKs, and the
spelling follows each language. `session.delete()` already works this
way (`session_id` in Python, `sessionId` in TypeScript), and so does
`RemoteFile` (`expires_at` / `expiresAt`).
**`status` and `size` are narrowed to `int`.** The generated model types
both as `float` and pydantic coerces, so a response read straight off it
renders `200.0` where TypeScript renders `200`. #4163 declared `int` but
still returned `200.0`. That mismatch also failed `nox -s chk`:
```
composio/core/models/session_context.py:56: error: Incompatible types
(expression has type "float", TypedDict item "status" has type "int") [typeddict-item]
```
**Tests use the real generated models again.** `SimpleNamespace` accepts
any attribute name and any type, so it silently tolerates a client
regeneration that renames or retypes a field. It was also what hid the
`float` coercion, since `assert result == {"status": 200}` passes
against `200.0`. The suite now asserts the narrowed types directly. This
matters ahead of the `composio-client` 2.x migration, which types every
response field as `Any` and removes type checking on this projection
entirely. The tests become the only remaining check.
**Simplification.** The projection folds into `proxy_execute_impl`, so
both entry points are a single call rather than an impl-then-normalize
pair. `response.binary_data` is read directly instead of through
`getattr(..., None)`. The defensive default could never fire on a typed
response, but it made mypy infer `Any` and stop checking the projection.
**Docs.** Three Python snippets that read the result as attributes are
fixed, and the response-shape table gets a per-language column. The
follow-up commit also marks `headers` and `data` as nullable in that
table, replaces the "returns the upstream response verbatim" claim with
what the projection actually does, and documents that `expires_at` can
be absent in TypeScript and `None` in Python.
## Breaking change
The method has shipped since `py@0.11.4`. Both directions of the old
access pattern were already inconsistent in the repo.
`python/examples/custom_tools_agent_test.py:95` does `res["status"]`,
which raises `TypeError` on `next` today and is fixed by this PR. The
doc snippets did attribute access and are updated here.
No changelog entry and no version bump are included. That is deliberate,
so the release call stays explicit rather than implied by the merge.
## How Has This Been Tested?
```bash
cd python
mypy --config-file config/mypy.ini composio/ tests/ # clean
ruff check --config config/ruff.toml composio/ tests/ # clean
pytest tests/ # 1336 passed, 33 skipped
```
`ruff format` was run with the repo's pinned toolchain.
## Type of change
- [x] Bug fix
- [ ] New feature
- [ ] Refactor/Chore
- [ ] Documentation
- [x] Breaking change
## Checklist
- [x] I ran linters/tests locally and they passed
- [x] I updated documentation as needed
- [x] I added tests or explain why not applicable
- [ ] I added a changeset if this change affects published packages. Not
applicable: `AGENTS.md` reserves changesets for published TypeScript
packages
https://claude.ai/code/session_01GsD8zvAhrjFwk144oWkD9K
---------
Co-authored-by: AseemPrasad <aseemprasad0520@gmail.com>
Co-authored-by: Kshitij Jhunjhunwala <113939507+KJ-11@users.noreply.github.com>
Consumer product and the backend-provided default redirect URI use the
v1 callback (api/v1/auth-apps/add), but the developer docs instructed the
v3.1 URL (api/v3.1/toolkits/auth/callback). Users copied the wrong URL
into their OAuth app allow lists. Align all instructional docs + the
Python example with v1.
The migration guide (migration-guide/new-sdk.mdx) is left unchanged: it
documents the v1->v3 history and flipping it would make it contradictory.
Fixes UXE-261.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The Auth Screen branding settings now ship a full theme editor (colors,
typefaces, geometry, and per-element styling with a live preview and JSON
mode), so both white-labeling guides need to cover it.
- Split "Customizing the Connect Link" into Logo and name (Branding tab)
and Colors, fonts, and per-element styling (Styling tab).
- Align to the shipped UI: White Labeling nav item, Branding/Styling tabs,
Typefaces, JSON toggle, Save Changes, and the enforced-contrast gate.
- Add the editor screenshot; drop the stale branding-only walkthrough video.
- Mirror the section into the legacy direct-execution page.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Follow-up to #4170 / #4161, deferred until npm publish landed (per
#4098's own follow-up note).
- bumps `docs/package.json` pins: `@composio/core` `^0.15.0` ->
`^0.17.0`, `@composio/anthropic` `^0.10.1` -> `^0.11.0`,
`@composio/openai` `^0.11.0` -> `^0.12.0` — all three are now live on
npm
- removes the `@errors: 2345` Twoslash suppression markers (and their
TODO comments) in the OpenAI and Anthropic provider docs, now that the
session-aware `handleToolCalls`/`executeToolCall` overloads type-check
against the resolved package versions
- regenerates `docs/bun.lock`
## Verification
- `bun install` resolves `@composio/core@0.17.0`,
`@composio/anthropic@0.11.0`, `@composio/openai@0.12.0`
- `bun run types:check` passes
- `bun run build` passes, including Twoslash compilation of the updated
code samples with the suppression markers removed
This PR:
- bumps `composio` and all 13 provider distributions from `0.19.0` to
`0.20.0`, keeping `python/composio/__version__.py` and `uv.lock` aligned
with package metadata
- adds `docs/content/changelog/08-19-26-sdk-releases.mdx`, the combined
customer-facing changelog for both SDKs, documenting the session-aware
provider tool-call helpers from #4098 (Python `composio` 0.20.0,
TypeScript `@composio/core`/`@composio/slim` 0.17.0,
`@composio/anthropic` 0.11.0, `@composio/openai` 0.12.0) and the
API-response URL validation and Python file-handling fixes shipped since
the last train
- documents `@composio/core` `0.17.0` in that entry so the generated
Changesets release PR (#4161) passes the release-workflow guard
## Release sequence
1. Merge this PR.
2. Merge #4161 (the generated "Release: update version" PR) once it goes
green. Merging publishes the TypeScript packages to npm.
3. Tag the resulting `next` commit `py@0.20.0` to publish the Python
packages to PyPI.
4. Follow-up PR: bump `docs/package.json` pins to
`@composio/core@^0.17.0`, `@composio/anthropic@^0.11.0`,
`@composio/openai@^0.12.0` and remove the now-stale `@errors: 2345`
Twoslash TODO markers in the provider docs, once the npm publish lands.
## Verification
- Verified the release-workflow guard reads the new changelog rows for
Python `0.20.0` and TypeScript `@composio/core` `0.17.0`
- All 13 Python `pyproject.toml`/`setup.py` pairs bumped consistently;
`uv.lock` regenerated
## 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>
## Problem
Provider tool-call helpers always used the globally injected direct
`Tools.execute` function. When a model received tools from
`session.tools()`, calling `handleToolCalls` or `handle_tool_calls`
therefore discarded the Tool Router session context and caused session
meta-tools such as `COMPOSIO_SEARCH_TOOLS` to fail.
Calling `session.execute()` manually preserved the session, but bypassed
provider behavior such as Anthropic input normalization and schema-alias
restoration.
## Root fix
- Add an explicit execution target to the non-agentic provider helpers:
- TypeScript: `handleToolCalls(session, response)` and
`executeToolCall(session, call)`
- Python: `handle_tool_calls(response=response, session=session)` and
`execute_tool_call(tool_call=call, session=session)`
- Route normalized provider arguments through the supplied Tool Router
session.
- Map session responses back to each helper's existing result shape.
- Keep provider-specific normalization before execution, including
Anthropic schema-alias restoration.
- Reject direct-only options and modifiers when the selected target is a
session, including plain JavaScript calls that bypass the TypeScript
overloads.
- Update OpenAI and Anthropic examples to use the session-aware helpers.
- Harden the docs policy test so setup and execution split across fences
in one sample are still detected.
## Docs review follow-ups
- Reword the concepts-page prohibition so it forbids user-ID-bound
helper calls, not the helpers themselves, matching the provider pages in
this PR.
- Add minimum-version callouts to the OpenAI and Anthropic provider
pages (Python `composio` newer than 0.19.0; TypeScript `@composio/core`
≥ 0.17.0 with `@composio/openai` ≥ 0.12.0 / `@composio/anthropic` ≥
0.11.0), pointing older versions at `session.execute()`.
- Bump `docs/package.json` to `@composio/core` `^0.15.0` and
`@composio/openai` `^0.11.0` (the published majors at the time of the
bump; `@composio/core` 0.16.0 and `composio` 0.19.0 have since released
from `next` without this PR, so its changeset will publish core 0.17.0
and the next Python minor) and annotate each `@errors: 2345` Twoslash
marker with a TODO naming the minor version that retires it; since this
changeset releases minors, all three pins need a manual range bump to
retire the markers. This version of twoslash only throws on *unlisted*
errors, so a stale marker cannot break the build — it would only mask
future TS2345s, which the TODOs now track.
- Update `SESSION_GUARDRAILS` (the block appended to `.md` responses for
agents): add a session-execution bullet (scoped to the OpenAI and
Anthropic helpers, with `session.execute()` for every other provider)
and qualify the direct-execution list with "with a user ID". The
session-execution static test now scans the guardrail blocks like the
execute-version test already did.
- Tighten the docs detector: the Python branch is bounded to the helper
call's argument list (tolerating one level of nested calls) instead of
running past the closing paren, and the TypeScript branch catches whole
user-ID identifiers (`userId`, `user_id`, `uid`) without flagging
session variables like `userSession` — each edge has a regression test.
- Note on the Google provider page that its `executeToolCall` is not
session-aware yet.
## Compatibility and release
Existing user-ID calls remain unchanged and continue to use direct tool
execution. The new session call forms are additive.
The changeset applies minor releases to `@composio/core`,
`@composio/openai`, and `@composio/anthropic` — the new session
overloads are a type-level break for provider subclasses, so patch was
too small. The configured fixed group also includes `@composio/slim`.
The docs site intentionally checks examples against currently published
SDK declarations. The three new TypeScript calls therefore carry exact
Twoslash `TS2345` release-skew annotations; remove them (per the inline
TODOs) once `docs/package.json` picks up `@composio/core` ≥ 0.17.0,
`@composio/openai` ≥ 0.12.0, and `@composio/anthropic` ≥ 0.11.0.
## Verification
- `@composio/core`: 1,061 tests passed; typecheck passed
- `@composio/openai`: 34 tests passed; typecheck passed
- `@composio/anthropic`: 53 tests passed; typecheck passed
- Python provider and aliasing suites: 40 passed, 4 skipped
- Focused Python mypy and Ruff checks passed
- Docs static suite: 208 tests passed (including the new guardrail-scan
and detector cases)
- Docs production build passed with the bumped `@composio/core` 0.15.0 /
`@composio/openai` 0.11.0, including Twoslash, TypeScript, and all
generated pages
- Docs lint passed; lint reports only existing warnings
- Changeset status reports the expected minor packages
---------
Co-authored-by: Soumya Medapati <soumyamedapati@soumyas-air.local.meter>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Revert the separator split, and the later ---Security--- rename with it.
Each half held exactly one folder whose title near-repeats the heading,
so the sidebar read "Migration" / "Migration guides" and "Security" /
"Security and data", and llms.txt emitted "## Security" immediately
above "### Security and data". content/docs/meta.json is byte-identical
to next again; both folders keep their titles.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four review fixes on the sidebar restore.
Folder headings do not close, so every page emitted after a folder read
as one of that folder's children. Making `authentication` a folder
mid-list swallowed `triggers` and `skills` into `### Authentication`.
Reordering meta.json would fix the output but push Authentication below
Skills in the human sidebar, which is what this PR exists to prevent —
so walkPageTree now buffers each separator section and flushes its plain
pages ahead of its folders. Legacy-separator skipping is unchanged. This
also fixes the pre-existing case where `agent-plugins`, `cli` and
`composio-connect` read as children of `#### Custom providers`.
Drop "index" from authentication/meta.json. Listing it clears
`node.index`, so fumadocs renders the folder as a chevron BUTTON plus a
duplicate child row instead of a SidebarFolderLink — the row a reader
clicks to reach /docs/authentication (1,850 views/month) expanded the
folder instead of navigating. Omitting it matches how `providers` and
`migration-guide` already render. Verified in the built DOM: an A with
href=/docs/authentication, no duplicate row, /docs/authentication.md
still emitted exactly once via node.index.
Rename the ---Security and data--- separator to ---Security---; it
duplicated the folder title directly beneath it, in llms.txt and in the
sidebar.
Point the last three agent/instructions/context.md bullets at canonical
paths rather than redirect-only /docs/authenticating-users/* ones, so
that file is internally consistent.
Extend the llms.txt section test to assert the nearest preceding heading
of any level, and to cover the sibling pages that regressed. It fails
against the old walk.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
PR #4099 dropped 8 auth pages from meta.json. That was a net win for
machines (Loop 5 eval: 84/100 vs 77/100, tool-routing failure mode gone)
but it made the pages unreachable by clicking. PostHog, weekday-matched
and control-adjusted, shows the affected pages down 14-64pp beyond the
site-wide baseline drift.
Restore human navigation without touching the machine-facing wins:
- authentication.mdx becomes authentication/index.mdx and the 7 sibling
auth pages move into the folder. /docs/authentication keeps its URL
(fumadocs serves index.mdx at the folder route), so Core concepts
still shows one row and the top-level sidebar row count stays 20.
- shared-connections moves into extending-sessions: it is experimental
and is a session capability, not a core auth concept.
- "Migration and security" splits into "Migration" and "Security and
data" — separator headings, not clickable rows.
- Drop AUTHENTICATION_GUIDE_URLS from app/llms.txt/route.ts. The pages
are back in the page tree, so they emit automatically under Core
concepts -> Authentication; the hardcoded list would now duplicate.
- 8 permanent redirects for the old URLs (36-42% Google entry rate on
most of them), plus existing redirect destinations repointed so none
of them chain.
- ~90 inbound links rewritten across content, api-overviews, app, lib
and agent instructions. lint:links is the gate: 0 errors.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Custom MCP hardening docs pass from Pelago feedback (Linear PLEN-2931,
origin PLEN-2927), verified against platform code on master.
- Auth config: state explicitly that registration does not create an
auth config; for API-key and DCR OAuth servers creating one (with
`is_enabled_for_tool_router: true`) is a required separate step. Also
fixed the PATCH example: the update body requires `"type": "custom"`
(discriminated union), the previous example would 400.
- v3 gotcha: explain the empty-tools-list symptom, `GET
/api/v3/tools?toolkit_slug=CUSTOM_...` pins a default version without
custom tools; pass `toolkit_versions=latest` or use v3.1.
- Upsert semantics refresh (tracks platform #11598): re-registering an
owned slug now updates mutable fields (name, logo) in place, identical
config is a no-op; `app_url` and `auth_schemes` stay immutable (409,
delete + re-register). Updated the registration callout, logo section,
delete section, and known gaps.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Automated sync of backend data into the docs site. Triggered by:
`schedule`.
## 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
---------
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
Co-authored-by: jkomyno <alberto@composio.dev>
Reverts the quickstart portion of #4099, which replaced the framework
picker (OpenAI Agents, Claude Agent SDK, Vercel AI SDK with Python and
TypeScript tabs) with a Python-only uv flow, leaving TypeScript readers
without a quickstart path.
Keeps the parts of #4099 that improved the page:
- Sharper intro and meta-tools explanation
- Agent instructions that handle Connect Links and confirm destructive
actions, applied to all six code samples (the Claude Agent SDK
TypeScript sample previously had no system prompt)
- "What just happened?" section, dual-language session persistence notes
- Production callout for replacing user_123 with a stable user ID
- Logs API pointer and "Adapt the example" cards
Deletes tests/static/quickstart.test.ts, which was added by #4099 to pin
the Python-only structure.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Applied the repo's good-docs-writing skill. The page broke its two hardest
rules: em-dashes are banned in this style and the page was built on them
(the sibling triggers page has zero), and a page with no example asked the
reader to take the whole mechanism on trust.
It now shows the search response carrying a plan, so the shape is concrete
before the prose explains it. The field names are checked against the
schema in composio_actions/utils/schemas.ts: recommended_plan_steps and
known_pitfalls are string arrays, difficulty is a string, and all three are
optional, present only when a skill covers the use case. The page says so,
since anything else would have readers destructure fields that may be absent.
Also cut the filler the audit checklist flags and made every definition a
sentence rather than a dash fragment.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
- Reframes the docs Welcome page around two intents: build with Composio
or use Composio from an existing agent.
- Replaces the framework picker with a general Python quickstart and
routes other frameworks to focused provider guides.
- Adds a shared Agent plugins page for Codex and Claude Code, with
CLI-first setup and explicit MCP alternatives.
- Simplifies the sidebar into Get Started, Core concepts, Guides, Direct
execution (legacy), and Migration and security.
- Keeps the Welcome page readable through its `.md` endpoint and
clarifies intent routing in `llms.txt`.
## Review order
1. Welcome hero and the two intent cards.
2. Quickstart copy and runnable example.
3. Agent plugins, CLI, and MCP routing.
4. Sidebar grouping and progressive disclosure.
5. Agent-readable Welcome Markdown and regression tests.
## Validation
- `bun run test` — 208 passing
- `bun run types:check`
- `bun run lint:links` — 0 errors
- `bun run lint` — passes with pre-existing warnings only
- Dashboard badge styles compared against the live product UI
## Deliberately out of scope
- Docs eval harnesses or eval result files
- Search ranking, agent-index generation, or agent prompt changes
- Deleting pre-existing unused hero or quickstart components
- Unrelated lint warnings and docs content cleanup
This replaces #4085 with a one-commit, docs-only review surface. The
earlier PR accumulated implementation experiments and bot commentary
that made the intended change difficult to evaluate.
## Summary
- clarify that the SDK fetching examples default to `latest`
- distinguish REST v3 pinned defaults from REST v3.1 latest defaults
- replace the blanket production warning with output-consumer guidance
## Root cause
The legacy fetching guide used an unqualified `API` statement next to
SDK examples. That conflated SDK behavior with two REST API versions and
contradicted the current API reference.
No SDK package changes or changeset are required.
This PR:
- builds on top of https://github.com/ComposioHQ/composio/pull/4094
- bumps `composio` and all 12 provider distributions from `0.18.2` to
`0.19.0`
- keeps `python/composio/__version__.py` and `uv.lock` aligned with
package metadata
- documents recursive provider argument-presence preservation in the
existing cross-SDK changelog
- passes the release-workflow guard, Ruff, mypy, provider type
inference, and 1,167 Python tests
- builds and validates 26 wheel/sdist artifacts with Twine
- must be retargeted to `next` after #4094 merges
Alberto Schiabel