## 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
This PR:
- Closes#4205 (nightly docs external-link check failing)
- demotes bare identifier URLs — Google OAuth scope URIs
(`googleapis.com/auth/*`) and version-only API roots like
`https://api.ahrefs.com/v3` — to inline code spans in the KB generation
layer (`markdownForMdx`), so they stop publishing as links that 404 by
design
- regenerates the two affected guides (`toolkits-ahrefs`,
`toolkits-googlemeet`); explicit markdown links keep their authored form
- adds a regression test covering the exact URLs from #4205 plus
link/autolink/code-span edge cases
- records the rule in `docs/decisions/public-knowledge-base.md`
- makes the scheduled KB workflow rebuild `docs/kb/semantic-index.json`
when it is stale against the checked-in corpus, not only when the
upstream `support-knowledge` commit moves
## Context
The failing URLs are machine identifiers, not documents — fetching them
404s by design, so no link target could ever satisfy the nightly sweep.
Upstream support prose cites them bare, the generator copied them
verbatim, and GFM autolinks published them as clickable links. Sibling
KB articles already used the backtick convention, confirming the
intended presentation.
`check:kb-semantic` is expected to fail on this PR: 4 embedded record
chunks change, and the artifact rebuild needs `OPENAI_API_KEY`
(CI-owned). After merge, the scheduled job (now staleness-aware)
proposes the artifact refresh PR on `docs/auto-update-kb`; until it
merges, that gate stays red for docs PRs.
Verified locally: `bun run lint:links:external` (the failing nightly
command) — 0 errors; `bun test tests/static/` — 506 pass; `lint:links`,
`generate:kb --check`, `types:check`, `lint` — pass.
The docs hero, feature cards, site metadata, and llms.txt all hardcoded
"1,000+" apps, while the published catalog is 1,327 toolkits (the length of
docs/public/data/toolkits-list.json, already rendered by the /toolkits page).
Add a server-only helper docs/lib/toolkit-count.ts that imports that same
JSON and exports TOOLKIT_COUNT_LABEL = Math.floor(len/100)*100 -> "1,300+",
with the locale pinned (toLocaleString('en-US')) so the separator is a comma
on any build host. Six server-side files now consume it. No client bundle
cost: none of the importers is a "use client" module, so the JSON never
reaches the browser.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
## 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: Sushmitha Mallesh <sushdec6@gmail.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>
## 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>
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>
The new AuthDiagram sized its hub (`w-36`) and account cards (`w-44`) with
fixed widths totalling 320px, but the feature-grid pane is not monotonic in
the viewport: ~404px at 1280px, and only ~242px at 640px where the grid goes
two-column. Below ~394px viewport the two blocks shrank until they touched,
`ex === sx` collapsed every wire into `elbowPath`'s straight-line fallback,
and the middle connector became a zero-length, invisible path. The card
rendered as three stray tick marks on every iPhone below Pro Max, and the
account cards overflowed the clip at 360px.
Use proportional widths with caps (`w-[36%] max-w-36` / `w-[52%] max-w-56`)
so ~12% of the pane is always reserved as horizontal run for the elbows.
Measured after: 29px gap at the 242px worst case, 34px at 360px, 50px at
1280px, no overflow and no degenerate paths anywhere in the range. The
account label now hides by container query rather than a viewport
breakpoint, which would gate on the wrong axis.
Also from review:
- Sandbox mock showed `composio.sandbox.run()` in a file chromed `sandbox.ts`.
Per content/docs/sandbox/remote.mdx — where the card links — the sandbox is
a persistent Python environment driven through COMPOSIO_REMOTE_WORKBENCH
with `run_composio_tool` / `invoke_llm`. Rewritten on that real surface and
relabelled `sandbox.py`; `WorkbenchVisual` renamed to `SandboxVisual`.
- `twilio` is not in public/data/toolkits.json, so the tile advertised an app
with no /toolkits page behind it. Swapped for `zendesk`.
- The dark logo was `aria-hidden`, so the heading's accessible name lost
"Composio" in dark mode only. Both variants now carry the same alt.
- Restored the badge style assertions the PR dropped, which still held, and
added regression coverage for the diagram widths, the catalog check, and
the sandbox surface.
- Restored the window resize listener that connection-refresh-visual.tsx
keeps alongside its ResizeObserver.
- Nits: stale "8×2" comment, redundant fragment, shared the duplicated fade
style, renamed the misleading `homeIntentAnchor(title)` parameter.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jkomyno