This PR:
- follows up on the failed TypeScript audit in
https://github.com/ComposioHQ/composio/pull/4048
- adds patched transitive floors for `fast-uri`, `ip-address`, and
`brace-expansion`
- refreshes `pnpm-lock.yaml` to resolve 3.1.5, 10.4.0, and 5.0.9
respectively
- clears all high-severity findings from `pnpm audit --prod
--audit-level=high`; one low and one moderate advisory remain below the
gate
- verifies the affected CLI dependency graph with a frozen install,
package build, and 1,072 passing tests (1 skipped)
This PR:
- restores missing `0.3.0` and `0.3.1` sections in
`ts/packages/cli/CHANGELOG.md`
- moves the plugin hint and telemetry changes out of `0.2.33`
- records post-`0.3.1` connected-account and login fixes under
`Unreleased`
- rewrites the restored notes as concise, user-facing bullets
- validates the ignored-package boundary with `pnpm validate:changesets`
## What
Runtime testing during eval-rerun prep caught a docs/runtime mismatch:
the guides say `toolkit_versions={"x": "latest"}` works for direct
execution, but `tools.execute()` rejects it —
```
ToolVersionRequiredError: Toolkit version not specified. For manual execution of the
tool please pass a specific toolkit version.
1. Pass the toolkit version as a parameter to the execute function
("latest" is not supported in manual execution)
...
4. Set dangerously_skip_version_check to True
```
Notably, the [TypeScript SDK
reference](/reference/sdk-reference/typescript/tools) already documents
the real behavior — the guides contradicted it. An isolated eval agent
independently hit the same wall and reported it.
Per SDK guidance (@abir-taheer): pass
`dangerously_skip_version_check=True` / `dangerouslySkipVersionCheck:
true` when running `latest` manually.
## Changes
- **All direct-execution samples** (executing-tools,
sessions-vs-direct-execution, custom-auth-params,
before/after-execution-modifiers) keep `"latest"` and add the skip flag
to the execute call with a one-line comment
- **executing-tools warning callout** now presents both paths:
skip-check when an LLM consumes outputs; pinned version (via
`toolkits.get(slug).meta.version`) when code parses them
- **toolkit-versioning page**: the "latest is valid" claims are
corrected to name the manual-execution requirement
- **LLM guardrails** (direct-execution block): same correction — this
block is what AI agents copy verbatim
- **execute-version static test**: now also fails any page showing
`"latest"` in execute samples without the flag (with the runtime
evidence cited in the header comment)
## Verification
- Both patterns executed against the live API before shipping: `latest`
+ flag → success; pinned via `toolkits.get(slug).meta.version` (resolved
`20260615_00`) → success; `latest` alone → the error above
- `bun test tests/static/` — 145 pass; negative check confirmed the new
rule fails with an actionable message when the flag is removed
- `bun run lint:links` — clean
## Note for reviewer
The pinned-version path also returns the *documented* nested response
schema — the "flat response" drift agents reported was a base-version
(`00000000_00`) artifact. Fixing versioning quietly resolves that report
too.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
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
## What
Round 2 of fixes from the 97-agent docs eval (findings:
ctx.composio.io/soumya/docs-agent-eval/findings-97-run.md). Follow-up to
#3999.
## Commit 1 — toolkit-discovery entry points (eval finding 3)
51/97 agents struggled to identify the right toolkit; 15 abandoned the
docs for the raw REST API. The catalog and search already exist and
score well (46/97 praised them once found) — these edits wire them into
the paths readers actually take:
- Quickstart intro: "1000+ apps" now links to the /toolkits catalog
- executing-tools + fetching-tools: a "finding a toolkit and tool"
pointer (catalog, `composio search`, semantic search) before the
parameter-finding guidance
- direct-execution LLM guardrails: a discovery rule, so AI readers stop
inventing their own path via the REST API
## Commit 2 — version-policy static test (the durable half of eval
finding 1)
The content fix for the 72/97 `ToolVersionRequiredError` failure landed
in #3999; this keeps it fixed. New
`tests/static/execute-version.test.ts`: any authored page whose code
fences call `tools.execute()` must show version configuration in its
fences; the LLM guardrail blocks are held to the same rule. Changelog,
generated reference, and migration guides are exempt as
historical/point-in-time records.
Running the new rule against current content caught **five more pages**
shipping version-less execute samples that the eval never visited —
including sessions-vs-direct-execution. Fixed in the same commit.
## Verification
- `bun test tests/static/` — 145 pass (including the new test)
- Negative check verified: removing a version token from a page fails
the test with an actionable message naming the file
- `bun run lint:links` — clean
🤖 Generated with [Claude Code](https://claude.com/claude-code)
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>
Install the no-arg canary with COMPOSIO_BIN_DIR=$HOME/.composio-canary/bin,
a directory Ubuntu's ~/.profile never contributes, so the env -i login
probe passes only when the managed block itself makes composio
resolvable, and assert nothing lands in ~/.local/bin.
The /install/<shell> variant routes still 404 in production, so the
harness's prod mode now selects the shell with COMPOSIO_INSTALL_SHELL on
the base /install route, and the scheduled matrix gains a fish leg. The
Docker harness invocation stays in place; a workflow comment records how
to restore variant-route coverage once the routes ship.
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.
For the default ComposioHQ GitHub source a missing checksums.txt or a
missing manifest entry is now a hard error instead of a warning;
malformed entries and mismatches stay fatal for every source. Overridden
mirrors keep the lenient path, and a missing SHA-256 utility still warns
that verification was skipped.
The previous installer wrote marker + export COMPOSIO_INSTALL_DIR + PATH
export. Both the shell and TypeScript reconcilers now consume that triple
as one managed block instead of orphaning the export lines, with shared
legacy-migrate and near-miss fixtures keeping the two implementations
byte-identical.
Port the atomic replacement work from #4016: support files publish first,
release metadata next, the binary last, with aside/rollback recovery for
directory entries and preserved staging on failed restores.
This PR:
- is refreshed directly onto the current next branch now that #3966 and
#3967 have merged; the PR contains only its intended type-safety work
- enforces no explicit any through the standard .oxlintrc.json, pnpm
lint, and plain oxlint --fix in lint-staged; docs remain covered by
their nested configuration
- replaces the loose JSONSchemaProperty in @composio/core with a
concrete recursive interface, removing explicit any reachable through
Tool.inputParameters and Tool.outputParameters
- includes a minor changeset documenting the type narrowing for
properties, default, and enum consumers
- adds a compile-only public-contract test for recursive schemas,
known-key validation, extension keywords, and Tool reachability
- removes explicit any from FileToolModifier, ts-builders, core and CLI
tests, provider tests, and json-schema-to-zod tests
- keeps TypeScript ESLint-parity rules enabled and closes the
tool-router example lint/typecheck gap
- makes no lockfile changes and no runtime behavior changes
## Context
Final PR from the original #3958 split. The migration foundations are
already on next via #3966 and #3967, so this branch no longer carries a
stacked base commit.
The 'To get started(, now)?, run:' ending was retyped at eight call
sites; extract a recovery_tail() helper next to configured_line() so
the expected ending lives in one place. Fold the quiet_fail and
helpless_fail cases into the inline write-failure case with both
COMPOSIO_QUIET=1 and COMPOSIO_INSTALL_HELP=0 set: all three asserted
the same warning and tail, and both flags only gate the normal-success
final block, so one combined case proves they are no-ops on the
setup-failure path (six installer runs become two across the sh/dash
legs).
Ten comments across install.sh, install.cmd.ts, and the harness cited
KD2/KD3/KD4/KD7 decisions from a plan file that exists on no branch.
Rewrite each comment to carry its constraint inline — the truthful
final action block, delegation trust via physical path comparison,
non-fatal setup failures, and copy-paste-safe endings — and drop the
dangling references.
The CLI and install.sh implemented the managed-PATH-block contract
twice with three divergences: TS matched marker lines after trimming
while the sh awk program matches byte-exact (CRLF or padded markers
reconciled on one side and duplicated on the other), TS replaced stale
blocks in place while sh removes managed lines and appends the fresh
block, and renderWithHome rendered a bin dir equal to $HOME as the
$HOME literal while render_bin_dir left it as the raw path — making
delegated verification permanently stale for that layout.
Align both sides: TS goes byte-exact and remove-then-append (mirroring
the awk program including its newline normalization), and
render_bin_dir learns the $HOME-exact case. A shared fixture suite
under test/managed-block-fixtures now runs against both reconcilers —
vitest drives the exported TS functions, the harness sources
install.sh's definitions and runs write_path_block under sh and dash —
so future edits to one side fail loudly until the other matches byte
for byte.
Three from-scratch tmp-write→rename implementations coexisted
(install.cmd.ts, tool-permissions writeCacheFile, analytics
writeAnalyticsStateFile), and the install ones raced concurrent installs
through a fixed .composio-tmp suffix. Extract src/utils/atomic-write.ts:
the tmp name embeds the pid, an optional preserveMode creates the tmp
with the target's mode and pins it via chmod, and the best-effort tmp
cleanup now also covers a failure of the initial write itself (ENOSPC
mid-write no longer leaves tmp litter). All three call sites migrate
with their semantics intact; tests scan for any .composio-tmp remnant
instead of probing the old fixed name. Extracting the block-append loop
also brings installShellIntegration back under the function-length
lint that the merge had pushed over.
The bash -ilc probe inherited the step PATH, which already contains
~/.local/bin via GITHUB_PATH and Ubuntu's skel ~/.profile, so a
regression in the bash login-file write could not turn the canary red.
Run the probe under env -i with a bare PATH, mirroring the harness's
assert_login_bash_path, and additionally assert the managed block in
the login-mode startup file the login shell actually reads.
# 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>
Both abort branches (unsafe or relative resolved bin dir) printed an error
and returned, so the effect succeeded and the process exited 0. install.sh
gates its inline PATH fallback on a non-zero exit from 'composio install',
so an aborted setup looked green and left the user with no PATH setup at
all. Raise a typed ShellSetupAbortError after printing the abort reason;
cli-main.ts maps it to exit code 1 without printing anything further, so
install.sh now takes its fallback branch.
The tmp copy was written with the default 0644 mode and only chmod'd to the
target's mode afterwards, so a 0600 private rc's contents sat world-readable
in <target>.composio-tmp for the duration of the window. Create the tmp file
with the preserved mode from the start; open(2) masks that mode with the
umask (only ever clearing bits), so the follow-up chmod stays to pin the
exact mode before the rename.
The shell-config assertions only passed for binaries that write the new
CLI-managed PATH line, but every leg of this workflow installs a published
release binary: workflow_dispatch re-verification of existing releases,
workflow_call with the default 'latest', and promote-stable rebuilds of an
older beta all install pre-change binaries that write the legacy
COMPOSIO_INSTALL_DIR block (as does install.sh's own fallback). Accept
either working PATH layout, fail only when neither is present, and keep
rejecting a mixed state where the new PATH line coexists with a persisted
COMPOSIO_INSTALL_DIR.
A bare exists-check let any leftover ~/.local/bin/composio (e.g. a pip or
pipx install) win bin-dir resolution, so the PATH line pointed shells at a
foreign program while the installer reported success. Prefer ~/.local/bin
only when its entry realpath-resolves, following symlinks, to the running
executable; otherwise fall through to the runtime executable's directory.
The COMPOSIO_BIN_DIR override stays highest precedence.
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
Alberto Schiabel