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
compileToolInputSchema still runs inside validateToolInputArgumentsWithDefinition,
so the failure fires on every invocation. What changed is the diagnosis, not the
frequency. Line 153 already made only the diagnosis claim; this aligns line 88 and
the matching CLI changelog line with it.
The previous wording claimed both SDKs surfaced an invalid dynamic-key
schema only when validation descended into it. That is the CLI's lazy
interpreter; Python never read the keywords, so the defect never surfaced
and the new raise is unconditional at wrap time, not payload-dependent.
Also add @composio/slim to the versions table: it is public and in the
fixed Changesets group with @composio/core, so it ships this fix at the
same minor.
Both SDKs surfaced an invalid dynamic-key schema only when validation
descended into it, so a payload that stayed out of the affected branch
ran against a schema that could not fully validate it. Failing at the
schema is the point, but it is a behavior change and the entry framed it
as affecting only already-failing input.
The open-by-default claim and the Backward Compatibility carve-out both
read as unconditional for objects that name no properties. An explicit
additionalProperties: false closes such an object, and Python raises on
unknown keys it previously dropped through Pydantic's default
extra="ignore" - the same drop-to-raise transition already documented
for objects that declare properties.
The wrap-time paragraph named only Python. The CLI now fails the same way
on the two defects its validator can detect, so both the dynamic-keys
section and Backward Compatibility say which SDK does what, and note that
a reference outside a dynamic-key subschema is still left alone.
The Backward Compatibility carve-out claimed objects declaring no
properties were unaffected. On next, the Python converter read neither
patternProperties nor schema-valued additionalProperties, so those
objects became empty Pydantic models and every dynamic key was dropped
in silence. Those keys are now validated and can raise ValidationError.
Document it as the third call-time behavior change, with before/after,
narrow the carve-out to objects with no dynamic-key constraints, and
note that the prior 'unrelated pattern' behavior was TypeScript-only.
Prepares the next SDK train: Python `composio` `0.18.2` and the
TypeScript packages that the pending Changesets will publish
(`@composio/core` and `@composio/slim` `0.15.0`, `@composio/openai`
`0.11.0`, `@composio/experimental` and `@composio/json-schema-to-zod`
`0.2.2`).
No CLI release is part of this train.
## What this PR does
- bumps Python core and all 13 provider packages to `0.18.2`, including
`python/composio/__version__.py` and the root plus per-provider
`uv.lock` files
- adds `docs/content/changelog/08-07-26-sdk-releases.mdx`, the combined
customer-facing changelog for both SDKs
- documents `@composio/core` `0.15.0` in that entry so the generated
release PR passes the release-workflow guard
- leaves the pending Changesets untouched; the generated release PR
remains responsible for npm versioning and publication
## Release sequence
1. Merge this PR.
2. Let Changesets regenerate the "Release: update version" PR, wait for
it to go green, then merge it. Merging publishes the TypeScript
packages.
3. Tag the resulting `next` commit `py@0.18.2` to publish the Python
packages to PyPI.
## Notes
- The root `uv.lock` diff carries ~28 lines of marker-annotation churn
beyond the version bumps. That is the repo-pinned `uv` `0.8.19`
normalising markers the committed lockfile had recorded differently; no
dependency versions change.
- `@composio/mastra` and the TypeScript providers are unchanged: their
declared peer ranges still accept `@composio/core` `0.15.0`, so
Changesets does not bump them.
## Verification
- `pnpm test:release-workflow` — passes (Python package, runtime, and
provider versions agree; both SDK versions documented in the changelog)
- `uv run pytest tests/` in `python/` — 925 passed, 35 skipped
- `uv run --package composio python -c "import composio"` — reports
`0.18.2`
- `bun test tests/static/` in `docs/` — 195 pass, 1 pre-existing failure
(`getLLMText — version pointer`, also fails on a clean tree)
- `bun run types:check` in `docs/` — MDX generation and route typegen
succeed; the final `tsc` step could not run locally because
`typescript-7` is absent from `docs/node_modules`
This PR:
- fixes
[UXE-233](https://linear.app/composio/issue/UXE-233/docs-should-explicitly-direct-agents-to-use-v31-apis)
- makes the agent-facing Markdown channels publish concrete REST v3.1
base URLs and endpoint tables while preserving the supported v3.0
reference tree
- centralizes `REST_VERSION_GUIDANCE`, `TOOL_VERSION_GUIDANCE`, and
raw-spec path matching in `lib/api-version-guidance.ts`
- renders `ApiBaseUrl` and `ApiEndpointsTable` in authored MDX and adds
an explicit version pointer to generated OpenAPI operation Markdown
- separates current and legacy REST references in `llms.txt`, excludes
v3.0 page bodies from `llms-full.txt`, and adds v3.1 selection guidance
to Context7
- validates serialized `ApiEndpointsTable` payloads with Zod before
generation while preserving forward-compatible fields
- addresses review feedback for the renamed authentication page,
SDK-reference pointer scope, generator validation behavior, and stale
OpenAPI tool-version descriptions
## Context
REST v3.0 is superseded but remains supported for existing integrations.
This PR changes what new agent-generated code discovers first; it does
not require existing v3.0 callers to migrate.
Authenticated read-only probes against the deployed API confirmed that
the affected v3 endpoints default to `00000000_00`, while their v3.1
counterparts default to `latest`. `POST /tools/scopes/required` is
available only on v3.1 and defaults to `latest`.
This PR does not move public URLs. A future `/reference/v3/` to
`/reference/v3.0/` migration remains separate because it has independent
compatibility and search-indexing risk.
## Verification
- `bun test tests/static/`
- `bun run build`
- `bun run test:integration`
- `bun run types:check`
- `bun run lint`
## Review follow-up
The version-default guidance is intentionally limited to the five
verified tool endpoints. v3.1 is a structural superset of v3, so this PR
does not claim route parity. Static coverage rejects broad non-tool
parity wording in both the shared guidance and Context7 rules.
## What
In three independent eval runs across two rounds
(ctx.composio.io/soumya/docs-agent-eval/), capable agents classified
this block as prompt injection and deliberately ignored it (round 1,
agent-007: "a prompt injection I had to identify and ignore"; round 3,
two more agents unprompted). The ALWAYS/NEVER imperative framing also
contradicted the sessions-vs-direct-execution page — the block forbade
the API that page documents.
## Change
Rewritten in `docs/lib/llm-guardrails/session.ts` — same facts, no
commands:
- Sessions documented as the recommended default (samples unchanged)
- The provider-import gotcha kept — it's the most common real mistake in
generated code
- The managed-auth default kept
- Direct execution acknowledged as a supported lower-level interface,
with a link to the sessions-vs-direct tradeoffs page (this replaces the
"DISCOURAGED — do not generate tools.execute()" section, which
contradicted the docs one click away)
An AI-steering block only works if AI readers trust it.
## Verification
- `bun test tests/static/` passes (the execute-version policy test also
validates the guardrail blocks)
- Every factual claim from the old block is preserved; only the framing
and the tools.execute() discouragement changed
Split out of #4059 (which now carries only the legacy-flag and
REST/SDK-naming changes) so this piece can be decided on its own.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Three independent eval runs across two rounds show capable agents
classify the CRITICAL INSTRUCTIONS block as prompt injection and ignore
it; its ALWAYS/NEVER framing also contradicted the
sessions-vs-direct-execution page. Same facts, no commands: sessions
stay the recommended default, the provider-import gotcha and
managed-auth default are kept, and direct execution is acknowledged as a
supported lower-level interface with a link to the tradeoffs page.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The provider registered tools through jsonSchemaToZodShape, which returns only
the per-property map. Root-level constraints -- `additionalProperties`, boolean
or schema-valued, and `patternProperties` -- are structurally unrepresentable in
a raw shape, so they were dropped before the Claude Agent SDK ever saw them:
free-form object arguments lost their content, and an unknown key was silently
stripped from tool input rather than rejected.
Registering the complete object schema fixes both. A tool with no input
parameters keeps its closed root explicitly, since a bare `properties: {}` is
now an open object.
Proven at the real SDK boundary rather than against a mocked `tool()`: the new
suite drives createSdkMcpServer over an in-memory MCP transport and asserts on
the advertised inputSchema and on real tools/call results.
Python's unknown-key rejection changes behavior for the langchain, langgraph,
and crewai providers rather than only fixing a defect, so the release carries a
minor bump across both SDKs instead of a patch.
Records the cross-SDK fix and, in particular, the Python behavior change the
release would otherwise ship undocumented: object schemas that name properties
and omit `additionalProperties` now reject unknown keys instead of dropping
them, affecting the langchain, langgraph, and crewai providers.
The 07-31 changelog entry is already published on next and describes the
install-only default that composio.dev/install serves today. Rewriting it
in place would replace a live, accurate description with its opposite
under a date on which that behavior never shipped, and readers who
already saw it would get no notice of the flip.
Restore that entry verbatim and add a dated 08-05 entry carrying the
behavior-change callout, the auto/none bullets, and the created
~/.bash_profile disclosure.
The download-verification section moves to the new entry rather than
staying on 07-31: the strict abort is new here. The live installer warns
and continues when checksums.txt is missing -- the official_release_source
gate that turns that into an abort does not exist there.
Also scope the HTTPS claim, which is_allowed_http_authority contradicts
for loopback and COMPOSIO_INSTALL_ALLOW_HTTP_HOST; document the second
shape of the installer-created ~/.bash_profile, which survives the
documented uninstall when ~/.profile existed; and record the checksum
abort in INSTALL.md, where someone hitting 'Refusing to install' will
look for it.
Keeps this branch's fixture-driven managed-block reconciler
(reconcileManagedPathBlock, pinned byte-for-byte against install.sh's awk
rewrite by test/managed-block-fixtures) and drops next's narrower
replaceManagedPathBlock/applyFileChanges pair, which it supersedes.
Adopts from next: the narrowed unsafe-path character set on both the TS and
sh sides, the removal of the $PATH-reachability write skip, the hedged
no-shell PATH message, and the COMPOSIO_BIN_DIR command documentation.
Runtime testing during eval-rerun prep caught that toolkit_versions
'latest' is rejected by tools.execute() (ToolVersionRequiredError:
'"latest" is not supported in manual execution') — the guides recommended
it anyway; only the TS SDK reference documented the real behavior.
Per SDK team (Abir): pass dangerously_skip_version_check=True /
dangerouslySkipVersionCheck: true when running 'latest' manually. All
direct-execution samples now include the flag with a one-line comment;
the version-required callout explains both paths (skip-check for
LLM-consumed outputs, pinned via toolkits.get(slug).meta.version for
parsed outputs); the toolkit-versioning page's 'latest' claims are
corrected; the execute-version static test now fails any page showing
'latest' without the flag. Both patterns runtime-verified against the
live API before shipping.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
## Problem
Custom MCP docs don't mention logos, so developers don't know they can
replace the default Composio logo their toolkit shows in the dashboard
and on end-user connect screens.
## What this adds
A new "Add a toolkit logo" section on the Custom MCP page, after
registration: the `toolkit_config.logo_file` field (base64 `content` +
`mime_type`), a cURL example with a placeholder base64 value, the
constraints (PNG/JPEG, square 256-1024px, max 3MB, single-line base64),
the default-logo behavior when omitted, and the insert-only implication
that changing a logo means delete + re-register. Follows the docs
convention of language/OS-neutral examples.
## Testing
`bun run lint` (0 errors) and `bun run lint:links` (0 errors) from
`docs/`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_016x2W47caMs6zW4V8uu1M9g
Adds tests/static/execute-version.test.ts: any authored page whose code
fences call tools.execute() must show version configuration, and the LLM
guardrail blocks are held to the same rule. Fixes the five pages the
audit caught (sessions-vs-direct-execution, custom-auth-params,
before/after-execution-modifiers) which shipped version-less samples.
Changelog, generated reference, and migration guides are exempt as
historical/point-in-time records.
This is the durable half of eval finding 1: the content fix landed in
#3999; this test keeps future samples from regressing.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Eval finding 3: 51/97 agents struggled to identify the right toolkit;
15 abandoned the docs for the raw REST API. Links the toolkits catalog
from the quickstart intro, adds a find-your-toolkit pointer to the
executing-tools and fetching-tools pages, and adds a discovery rule to
the direct-execution LLM guardrails.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The uninstall snippet now stages each startup-file rewrite in a 0600
mktemp file, promotes it only when the filter succeeds (preserving
symlinks, inode, owner, and mode), always cleans up, removes legacy
three-line blocks including the fish install-dir export, and deletes an
installer-created ~/.bash_profile left empty so bash regains its default
startup-file selection. A new suite extracts the snippet verbatim from
the docs and exercises it under sh and dash, wired into the install
script unit-test workflow.
Call out the breaking default change (curl | sh now edits startup files
and can create ~/.bash_profile), document COMPOSIO_INSTALL_SHELL=none as
the install-only opt-out, and align the verification claims with the
implemented checksum policy.
# Description
Customers evaluating Composio see references to **LLM tokens** and
assume Composio is handing them an agent/LLM that *replaces* their own —
i.e. that they'd be swapping their agent for ours. It isn't: Composio
discovers, authenticates, and executes tools; it never proxies the
customer's model or runs an agent on their behalf.
The one place Composio itself calls a model is **inside the sandbox**
(the optional `invoke_llm` helper + AI-assisted conveniences like error
correction). The sandbox is opt-in per session (`sandbox: { enable: true
}`), so this LLM usage is entirely optional and can be disabled.
This PR adds a short callout to the **Remote sandbox** docs page
(`docs/content/docs/sandbox/remote.mdx`) that says exactly that — placed
right where `invoke_llm` and the sandbox are introduced, with anchor
links to the `invoke_llm` helper, error correction, and session
configuration. It kills the "are they replacing my agent?" misconception
at its source.
The copy is deliberately accurate to today's state: it does **not**
claim we bill LLM tokens (sandbox billing is still upcoming and the
public pricing page only lists Tool Calls). It frames the point
conceptually — *your agent stays yours; the only Composio-side LLM usage
is optional and sandbox-scoped.*
**Follow-up surfaces (not in this PR — see below):** this same
clarification could be mirrored on the dashboard usage/billing UI and
the marketing pricing page when an "LLM tokens" line item actually
surfaces there. Those live outside this repo.
# How did I test this PR
- Docs-only change (single `.mdx` file); no code or dependency surface.
- Verified all anchor targets referenced in the new callout exist on the
same page / site:
- `#built-in-helpers` → `### Built-in helpers` (the `invoke_llm` row)
- `#error-correction` → `### Error correction`
- `/docs/configuring-sessions` (existing page; documents `sandbox: {
enable: true }`)
- Matches the existing `<Callout title="...">` component usage already
on the page (the "Renamed from workbench" callout), so it renders
consistently in Fumadocs.
- Confirmed against source that `invoke_llm` (docs `Built-in helpers`
table) is the Composio-side LLM entry point and that the sandbox is
opt-in via the `sandbox`/`workbench` session key.
# Security
- **Scope:** documentation-only change — one `.mdx` file, no
dependencies, lockfiles, or executable code added/changed.
- **Socket / Grype:** not applicable to this diff (no package manifests
or code paths introduced); no new fixable CRITICAL/HIGH/MEDIUM findings
possible from a Markdown copy addition.
Triggered by: palash@composio.dev | Source: slack
Session: https://zen.corp.composio.io/dashboard/#/chat/zen-f6a81a5a6764
---------
Co-authored-by: Zen Agent <zen@composio.dev>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## 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>
This PR:
- builds on top of https://github.com/ComposioHQ/composio/pull/3966
- enables `typescript/no-explicit-any` (error, `fixToUnknown`) for docs
in `docs/.oxlintrc.json` and removes every remaining explicit `any` in
docs code
- parses untyped/external data once at the boundary with zod v4 schemas
and lets `z.infer` types flow downstream — no hand-rolled `'x' in obj`
guard chains, no `as`-casts of untyped page data, no
`docs/lib/unknown-value.ts`
- adds domain schema modules: `docs/lib/toolkit-schema.ts` (recursive
JSON-Schema node, raw tool/trigger payloads, list envelopes) and
`docs/lib/reference-page-data.ts` (fumadocs reference page data for both
reference routes)
- rewrites `validate-links.ts`, `generate-toolkits.ts`,
`generate-meta-tools.ts`, the `llms.mdx` route, and
`deprecated-api-sidebar.tsx` on those schemas with identical validation
outcomes
- carries the pure typing improvements from the earlier attempt (typed
reference source in `source.ts`, `LLMPage`/`PageLike`, typed
`ClientLogo[]` in `logo-bar.tsx`, component `any` removals)
- adds `tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts` pinning the transform shapes;
no changeset (docs is not published)
## Context
Second of the three-PR split of #3958, replacing its rejected
structural-guard approach with zod schemas at the data boundaries.
Verified with `bun run lint`, `bun run types:check`, `bun test
tests/static/` (125 pass), `bun run lint:links`, and a full `next
build`.
## Review follow-up
Addressed the regressions reported in [the Zod boundary
re-review](https://github.com/ComposioHQ/composio/pull/3967#issuecomment-5105279224):
scalar JSON Schema enums and auth defaults are preserved as strings,
malformed toolkit page envelopes abort generation, and the pre-refactor
empty-string fallbacks are restored. Regression coverage lives in
`tests/static/toolkit-schema.test.ts` and
`tests/static/generate-toolkits.test.ts`.
Verified on `2f26c40be` with `bun test tests/static/` (125 pass), `bun
run types:check`, and `bun run lint` (0 errors; existing warnings only).
A login bash reads /etc/profile and then only the first existing of
~/.bash_profile, ~/.bash_login, ~/.profile; it never reads ~/.bashrc.
macOS Terminal.app starts exactly such a shell, so a terminal opened
after installation could not resolve composio even though the installer
reported success.
Always configure a login-mode startup file alongside ~/.bashrc: reuse an
existing ~/.bash_profile or ~/.bash_login, otherwise create
~/.bash_profile seeded to keep sourcing ~/.profile, which it shadows.
~/.profile itself is never rewritten.
Also refine the shell setup reporting:
- capture the delegated `composio install --shell` output so the
installer keeps sole ownership of its presentation, replaying it under
COMPOSIO_DEBUG so failures stay diagnosable
- drop the internal (cli)/(fallback) labels from user-facing output
- name the configured startup files from both the delegated and inline
paths, so piped installs disclose which files changed
The **I still need help** section of Composio Connect points users at
`tech@composio.dev`.
It's the only place in the docs that does. Every other reference uses
`support@composio.dev`:
- `docs/content/reference/errors.mdx`
- `docs/content/reference/v3/errors.mdx`
- `docs/content/changelog/12-30-25.mdx`
- `docs/content/changelog/01-29-26-sdk-major-update.mdx`
- `docs/content/changelog/03-25-26-mcp-endpoint-removed.mdx`
Composio Connect is the page consumer users land on when wiring up an
MCP client, so this was the most visible instance of the wrong address.
One line changed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
Replace the base installer's --shell flag with a COMPOSIO_INSTALL_SHELL
environment variable, matching the COMPOSIO_INSTALL_VERSION precedent
and reading more naturally in the curl-pipe form:
curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh
The variable is validated before any network call. Shell variants set
it explicitly when invoking the base installer, so the route stays
authoritative over any inherited value. The composio install --shell
CLI flag and the delegation/fallback behavior are unchanged.
Teach install.sh a --shell <zsh|bash|fish> flag that performs the same
shell setup the /install/<shell> variants do: delegate to
'composio install --shell' when the installed CLI supports it, fall
back to writing the # Composio CLI PATH block inline otherwise.
The shell variants become thin wrappers that fetch the base installer
and append '--shell <name>' to the forwarded arguments, so the
delegation and fallback logic now lives in exactly one script. This
also removes the double-configuration hazard of a variant blindly
forwarding a user-supplied --shell.
Shell setup no longer depends on the composio.dev/install/<shell>
redirect rules existing: post-install guidance, docs, and release
notes now print 'curl -fsSL https://composio.dev/install | sh -s --
--shell <shell>', which works through the single existing redirect.
The variant scripts and their raw-URL preview commands keep working
for when the routes land.
Coverage: direct --shell delegation, fallback on unsupported or
failing CLI, missing and invalid values failing before any network
call, and a Docker e2e leg for the idempotent --shell bash flow.
Session auto-match only considers auth configs with this flag, and the
custom flow has no default (platform#11223 was reverted), so configs
created without it fail session execution with NoActiveConnection. Adds
the auth-config creation step with the flag, a PATCH note for existing
configs, and updates the session and known-gaps guidance from "don't
rely on auto-match" to "auto-match works when the flag is set".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The is_enabled_for_tool_router step is load-bearing: after the revert of
platform#11223 there is no default, and configs created without the flag
make session execution fail with NoActiveConnection.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- make the documented uninstall strip legacy three-line PATH blocks
(dangling 'export PATH' left cwd on PATH) and preserve symlinked rc
files by writing back in place instead of mv
- point readers at Configure your shell before 'composio login' when
~/.local/bin is not on PATH
- restore an Update section covering 'composio upgrade', version
pinning, and --beta
- drop the completions claim from install.sh post-install help; shell
routes configure PATH only
- replace the nonexistent @composio/cli@0.3.1-beta.2 example tag with
the published 0.3.1-beta.329
- add the missing changelog description and note that the uninstall
file list tracks the current release layout
Alberto Schiabel