## Summary
Automated refresh of the toolkit slugs the CLI knows without asking
the API, generated by
`ts/packages/cli/scripts/generate-toolkit-slugs.ts`.
Toolkits added since the last refresh currently cost users one
toolkit-list fetch (~2 s) the first time they run one of that
toolkit's tools. Merging this makes them free.
The generator refuses to write a list that is short, malformed, or
missing staple toolkits, so a bad fetch opens no PR at all.
Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>
This PR:
- addresses the connection-readiness finding from the Sept 2026 SDK +
client hackathon (area 8): `session.authorize()` always starts a new
link flow, even when the session already resolves an ACTIVE connection
for the toolkit — callers ended up with a pending connected account
while `session.toolkits()` reported a different, active one, and nothing
in the SDK reconciled the two
- adds `session.ensureConnected(toolkit, options?)`: it checks the
session's connection state first — an ACTIVE connection (or a no-auth
toolkit) returns immediately with `wasConnected: true` and no link is
created; otherwise it starts the authorization flow and waits for the
new connection to become active (`timeout` option, default 60s)
- keeps `authorize()` unchanged as the primitive for interactive flows
that should surface the redirect URL instead of blocking
- documents the `session.execute()` `account` option's runtime contract:
accepted on every project, and on single-account projects the identifier
must match one of the session's active connections for the toolkit
(matching the API behavior after the Apollo side-fix)
- adds 5 unit tests for `ensureConnected` (already-connected no-op,
no-auth short-circuit, link-and-wait, pending-account relink, option
validation) and a changeset
Verification: `pnpm exec vitest run` in `ts/packages/core` — 1320
passed; `pnpm typecheck` (tsc + type tests) clean; `pnpm lint` clean at
repo root.
## 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
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
Co-authored-by: Sushmithamallesh <19796925+Sushmithamallesh@users.noreply.github.com>
This PR:
- makes `session.update()` resolve to the updated server-side session
configuration instead of `void`
- exposes that configuration as `session.config` (new
`ToolRouterSessionConfig` type) on sessions from `create()`, `use()` and
attach, so the toolkit/tool allowlist is readable without dropping to
the raw client
- renames the private SDK-config member on `ToolRouterSession` to
`sdkConfig`, ending the runtime name clash that made `session.config`
look like the SDK's `ComposioConfig`
- applies the same change to the Python `ToolRouterSession` (`config`
attribute, `update()` returns it)
- adds a minor changeset for `@composio/core`
## Context
After `sessions.use(id)` there was no way to know the session's
allowlist, and `update()` threw the response away except for
`configVersion` / `preload` / `sandbox` / `warnings`. Hackathon feedback
(area 8).
## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
## 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
Adds TypeSafe Jev providers for TypeScript and Python that turn tool
schemas and a request into a call, a partial call, or an abstention.
## What changed
- adds `@composio/typesafe`, a provider for TypeSafe's Jev model. Jev
has no tool calling, so `composio.tools.get()` compiles tools into typed
questions and `decide` returns a `call`, a `partial` call, or an
`abstain`, each with a confidence
- adds `execute` for a user ID or a session: caller arguments complete a
`partial`, and a tool tagged `destructiveHint` routes at a fixed floor
of 0.9 and needs `confirm: true`
- adds the companion helpers `shortlistTools` and `confidenceGate` (a
`beforeExecute` modifier that fails closed) for use with other providers
- adds `composio-typesafe`, the Python counterpart with sync and async
clients; both test suites compile one shared question corpus, so both
SDKs ask Jev the same questions for the same tool
- registers the package in the provider-compatibility release gate, adds
a `minor` changeset, the `ts/examples/typesafe` example, a Python demo,
and a dedicated `py.test.yml` step
- exempts only `@typesafe-ai/sdk@0.6.0` from `minimumReleaseAge`
(publisher, SLSA provenance, and the absence of install scripts were
checked by hand), and sets `engines.node` to `>=24.17.0` for this
package because the SDK terminates the process after a handled
cancellation on older Node.js releases (typesafe-ai/typesafe-sdk-js#2)
## Usage
```typescript
const provider = new TypesafeProvider();
const composio = new Composio({ provider });
const toolSet = await composio.tools.get('user_123', { tools: ['GITHUB_LIST_REPOSITORY_ISSUES'] });
const decision = await provider.decide(toolSet, 'List the closed issues of ComposioHQ/composio');
if (decision.kind !== 'abstain') {
// Jev binds closed-set arguments (enums, booleans, arrays of enums). Free text comes from you.
await provider.execute('user_123', decision, { arguments: { owner: 'ComposioHQ', repo: 'composio' } });
}
```
## Behavior notes
- `abstain` means only that the model judged so. A failed request throws
one `TypesafeApiError` whose `reason` tells rate limits, timeouts, and
rejections apart, and a malformed response throws
`TypesafeMalformedResponseError`. No error holds state, argument values,
response content, or the SDK's own error.
- Routing and the action gate see `request` only, so text in `context`
cannot change which tool is picked. `contextScope: 'all'` opts out.
- State is never truncated: over-budget state, unknown top-level state
keys, and non-JSON values throw.
- The options are `client`, `apiKey`, `model`, `thresholds`, and
`contextScope`. The provider builds its client at log level `warn`, so
`TYPESAFE_LOG_LEVEL=debug` cannot print request bodies.
- Root-level `allOf`, `anyOf`, and `oneOf` schemas are rejected
explicitly in both SDKs, including after `$ref` resolution, so composed
requirements cannot silently disappear. Property-level composition
remains supported as documented.
- Completing a partial decision requires an own, non-`undefined`
argument value in TypeScript; inherited names such as `toString` do not
satisfy required arguments. Supplied `__proto__` keys are preserved as
own data properties.
## Validation
- 147 TypeScript provider tests and 141 Python provider tests pass. The
11 new missing-argument regression cases fail on the original
implementation and pass with the fixes.
- Typecheck, Oxlint, Prettier, the tsdown build with ATTW/publint, Ruff,
mypy, type-inference, and release-gate checks passed locally.
- All 13 opt-in live tests passed across the TypeSafe-only and
Composio-backed suites against real Jev 1.13.0. These tests make
decisions without executing external tools.
- The actual TypeScript and Python Hacker News examples both ran end to
end against production APIs: fetch tools, decide, detect the missing
username, supply `pg`, and execute the read-only lookup. Both returned
the live profile for `pg`.
Not in this PR: the docs page, which needs the first npm publish so its
snippets compile. The first npm and PyPI publishes and a
`TYPESAFE_API_KEY` CI secret are manual steps.
```mermaid
flowchart LR
A[composio.tools.get] --> B[compile tools into questions]
B --> C[decide: state + questions]
C --> D{Jev answers}
D -->|none fits, no action, low confidence| E[abstain]
D -->|required arguments missing| F[partial]
D -->|everything bound| G[call]
F -->|caller arguments| H[execute]
G --> H
H -->|destructive tool| I[needs confirm: true]
```
## Summary
- Order generated API navigation as GET, POST, PATCH or PUT, then
DELETE.
- Preserve authored sidebar items and existing order within each method.
- Add regression coverage for the Auth Configs endpoint list.
## Testing
- `bun test tests/static/api-reference-routes.test.ts`
- `bun ./node_modules/typescript-7/bin/tsc --noEmit`
- `bun test tests/static/` (575 passed; one localhost test cannot bind
inside the sandbox)
- `bun test tests/static/kb-query-analytics.test.ts` outside the sandbox
(14 passed)
Fixes DEVREL-135
Automated knowledge-base refresh for `ComposioHQ/support-knowledge`.
- Source commit: `5eac683455ff252a7a3b62f33ab6566445009b52` (unchanged;
rebuilt a stale semantic artifact)
- Regenerated public KB pages and search records
- Reused unchanged vectors and rebuilt the checked semantic artifact
- Ran KB freshness and semantic-artifact verification
Co-authored-by: sohambasu963 <80603154+sohambasu963@users.noreply.github.com>
- Treat dict/list as their own leaf kind when asserting a redactor masks
only, so a redactor cannot replace a JSON null leaf with an object or
array while the gate would approve the altered call (Python now matches
the TS scalarTypeOf behavior).
- Reject non-number gate thresholds ('', '0.9', true) at construction on
the TS side, matching the strict Python check.
- Omit the gate state context key when getContext returns null, matching
Python and decide's context handling.
- Pin all three with regression tests on both SDKs, and assert the
context key is absent from the sent state when no getContext is given.
Review findings from the TypeSafe (Jev) provider PR, fixed in both SDKs:
- The confidence gate enforces a masking-only redaction contract: the redacted
arguments must keep the original JSON structure (same keys, same array
lengths) with every leaf replaced by a value of the same scalar type, or the
call is blocked. Jev can no longer approve a call that differs from the one
that runs.
- `onUnavailable` is validated when the gate is built, in the companion both
entry points share: a typo'd mode raises TypesafeInvalidOptionsError at
construction instead of failing open at check time.
- `minItems` is carried through classification and compilation into array
arguments, and a selection with fewer members than `minItems` counts as not
stated, so a required array stays missing instead of executing with `[]`.
- The boolean class gains `nullable`: a ['boolean', 'null'] property compiles
to a yes/no/null Choice so Jev can bind null; plain booleans still compile to
yes/no only, and one-boolean enum sets stay open-ended.
- `stable()` rejects `undefined` wherever it appears instead of rewriting it,
and the gate builds its state without a `context` key when there is no
context, so a context-less gate call still works.
- `Probability` and the classify number type accept JSON integers, so an API
score of 0 or 1 and integer `maxItems`/`minItems` parse instead of marking
the property open-ended or the response malformed. Bools, strings, NaN, inf,
and out-of-range values are still rejected.
## Why
Requirement 1 of the PRD: sessions accept all four verdict hints. The
Configuring Sessions tag table listed the four MCP-spec hints, two of
which (idempotentHint, openWorldHint) are set on a minority of tools.
Every tool carries at least one of readOnlyHint, createHint, updateHint,
destructiveHint.
## What
- Tag table leads with the four verdict hints and says every tool
carries at least one; idempotentHint and openWorldHint noted as accepted
with partial coverage.
- Callout: the v3 tools endpoints default to the pinned version
00000000_00, sessions read latest.
- Python example uses createHint. The TypeScript twoslash example stays
on readOnlyHint so docs CI passes against the published SDK; switch it
to createHint when merging, after #4467 is released.
- Python and TypeScript SDK reference docs list the widened enum.
## Merge after
API: platform#12843 (accept createHint and updateHint). SDK:
composio#4467 released.
PRD:
https://app.notion.com/p/composio/Session-Governance-via-hints-Across-toolkits-3daf261a6dfe80df8e0ce337a2b26e08
Linear workstream:
https://linear.app/composio/project/sessions-execution-governance-a0942233a0d0
Stack order (merge top to bottom, each after its API change is
deployed): D1 verdict hints, D2 precedence, D3 proxy execute toolkit
lists, D4 MCP classification, D5 proxy execute API key permission.
Verification, run in `docs/` at the top of the stack (D5 head, which
contains this PR): `bun run types:check` passes, `bun run build`
compiles (twoslash blocks type-check against the published
`@composio/core`), `bun run lint:links` reports 0 errors, `bun run test`
568 pass. `pnpm exec prettier --check` flags the changed mdx files on
`next` already, so no reformatting was applied.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01VHkYsmhteM1jJQoaoruiP3
Automated knowledge-base refresh for `ComposioHQ/support-knowledge`.
- Source commit: `5eac683455ff252a7a3b62f33ab6566445009b52` (unchanged;
rebuilt a stale semantic artifact)
- Regenerated public KB pages and search records
- Reused unchanged vectors and rebuilt the checked semantic artifact
- Ran KB freshness and semantic-artifact verification
## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
## Summary
- Strava is no longer present in the toolkit catalog
(`docs/public/data/toolkits.json` / `toolkits-list.json` have no
`strava` entry), leaving its docs orphaned.
- Removes the Strava toolkit FAQ page
(`docs/content/toolkits/faq/strava.md`).
- Removes the Strava KB guide and its source:
`docs/kb/source/toolkits/strava/public.md`,
`docs/kb/articles/toolkits-strava.md`, the generated
`docs/content/kb/guide/toolkits-strava.mdx`, and the corresponding
entries in `docs/kb/manifest.json` and
`docs/content/kb/guide/meta.json`.
- Removes the Strava OAuth guide entry from
`docs/kb/external-sources/auth-guides.json`.
- Left `docs/content/changelog/*.mdx` untouched (historical release
records).
## Note
- `docs/kb/semantic-index.json` is a generated embeddings artifact and
will now be stale relative to `kb/manifest.json`. It needs `bun run
build:kb-semantic` (requires `OPENAI_API_KEY`) or the "Docs - Rebuild KB
Semantic Artifact" CI workflow to regenerate — I didn't have the
credentials/toolchain in this sandbox to run it, so it's left as-is for
a maintainer/CI to refresh.
## Test plan
- [x] Validated edited JSON files parse correctly (`manifest.json`,
`auth-guides.json`, `meta.json`)
- [x] Confirmed no other registry (toolkits.json, toolkits-list.json,
page routing) references the `strava` slug
- [ ] CI: `check:kb` / `check:kb-semantic` (semantic index rebuild
needed, see note above)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Drop tool_thresholds, describe, and log_level, collapse the API error subclasses, validate decisions against the public TypedDicts, and read the question corpus from the TypeScript package instead of a second copy.
Collapse the TypesafeApiError subclasses into one error with a reason field, consolidate the question corpus to nine tools, and cut the tests that exercised the TypeSafe SDK instead of the provider.
Strava is no longer in the toolkit catalog (public/data/toolkits*.json
has no strava entry), so drop its orphaned FAQ page, KB guide, and
KB source/manifest/registry entries.
kb/semantic-index.json will go stale from the manifest change; it
regenerates via the existing "Docs - Rebuild KB Semantic Artifact"
workflow (or `bun run build:kb-semantic`).
This PR:
- closes
[SEC-1179](https://linear.app/composio/issue/SEC-1179/composio-attacker-can-reach-internal-services-using-ssrf-to-steal)
- routes proxy binary downloads through the core `ssrfSafeFetch` guard
- requires validation-to-connection pinning and fails closed when a
configured dispatcher or proxy prevents it
- reapplies that requirement on every redirect hop while preserving
default SDK proxy compatibility
- covers direct metadata targets, configured-route bypasses, redirects,
and the bundled Bun companion
- verifies the full core and CLI suites plus the TypeScript workspace
typecheck
## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
## Why
Support and customers (e.g. athena) keep asking how to tell apart
multiple connected accounts under one auth config. Platform
[#12507](https://github.com/ComposioHQ/platform/pull/12507) +
[#12519](https://github.com/ComposioHQ/platform/pull/12519) shipped an
auto-populated provider identity for this, but the docs never mention
it. Closes the docs follow-up on
[PLEN-3541](https://linear.app/composio/issue/PLEN-3541).
## What
One line in the **Aliases** section of *Managing multiple connected
accounts*: to identify an account by its provider-side identity (Gmail
address, GitHub username), read the read-only `display_name` Composio
auto-populates at `state.val.displayName` once the connection is active
— distinct from the user-set `alias`.
## Impact
Docs-only. No code, no API change.
## Rollout
The feature is currently in staging; merge/publish once PLEN-3541 is
live in prod.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
Automated sync of backend data into the docs site.
- Trigger: `schedule`
- Dispatch action: `n/a`
- Source commit: `n/a`
## What changed
- **Toolkit catalog** (`docs/public/data/toolkits.json`,
`toolkits-list.json`) — refreshed list of available toolkits, auth
schemes, and tools from the backend API
- **OpenAPI specs** (`docs/public/openapi.json`,
`docs/public/openapi-v3.json`, `docs/public/openapi-webhooks.json`) —
latest v3.1 and v3.0 API specifications plus the webhook-events spec,
fetched from production
- **API reference pages** (`docs/content/reference/api-reference/`,
`docs/content/reference/v3/api-reference/`) — regenerated index pages
for both API versions
- **Meta tools reference** (`docs/public/data/meta-tools.json`,
`docs/content/toolkits/meta-tools/*.mdx`) — updated meta tool schemas
and reference docs
This PR:
- follows https://github.com/ComposioHQ/composio/pull/3901 (merged as
0abc629f5)
- fixes a help-system inconsistency: whole command families (`orgs`,
`signup`, `agent`, `connections`, `triggers`, `artifacts`, `install`)
silently fell through to the framework's raw parser rendering instead of
the curated styled help pages every other family gets
- adds curated help entries for the `agent` children (`agent signup`,
`agent login`, `agent whoami`, `agent inbox`, `agent claim`), mirroring
the `orgs list`/`orgs switch` pattern
- adds `composio help [command] [level]` — the framework has no builtin
help command, so `composio help orgs` now routes to the same curated
page as `composio orgs --help`; bare `composio help` keeps printing the
root help. The spelling resolves targets with the same longest-prefix
scan as `--help` (so `composio help dev toolkits` renders the curated
dev page), and an unknown target falls through to the framework parser
(stderr, "Did you mean?", exit 1) exactly like any other unknown command
- fixes the stale `orgs` description in the contextual-error help
registry
- adds a consistency regression test that walks every visible root
command and fails when any lacks a curated help entry, plus routing
tests for every `composio help` path (bare, family, child, level
suffixes, trailing `--help`, deep-path fallback, and unknown targets)
## Context
Auditing the CLI surfaced that `composio orgs --help` rendered a
completely different page from `composio config --help`: unstyled
headers, a different section layout, and the root-level `--log-level`
flag exposed on a subcommand page. Root cause: `root-help.ts`'s
`SUBCOMMAND_HELP` registry — which drives the curated `--help` pages —
was missing those commands, so they fell through `matchSubcommandHelp`
to v4's default parser rendering. The new consistency test walks the
visible root command graph and locks this class shut; it caught `signup`
and `agent` during development.
Review follow-ups (from code review + prior feedback):
- the `agent` family now has per-command entries, so `composio agent
signup --help` and `composio help agent signup` show signup's own flags
instead of the group page / an "Unknown command" line
- `composio help <unknown>` no longer prints "Unknown command" to stdout
with exit 0; it fails through the framework parser like every other
unknown command, so scripted probes and the stdout data channel stay
honest
- the `help` spelling resolves deep paths with the same longest-prefix
fallback `--help` uses
- the two rendering tests now actually execute (`layer(TestLive())` +
`it.effect`) — previously they returned a bare `Effect` from a plain
`it` and passed vacuously
- the changelog no longer lists `tools` as newly curated (its entry
already existed at the base of this PR)
Guidance-only surface: no parsing, execution, or exit-code behavior
changes beyond the `help` spelling itself — help pages and the new
`help` command only.
Validation:
- `pnpm --filter @composio/cli typecheck` and full suite: 1342 passed
(16 new tests, all executing under `layer(TestLive())`)
- oxlint and prettier clean
- binary smoke-tested: orgs/signup/agent (group +
children)/connections/triggers/tools/artifacts/install help pages, all
`composio help` paths (bare, family, child, level, deep-path, unknown ->
parser error on stderr), and `whoami` against the staging API
Built on top of the merged #3901.
## Summary
Live PostHog (2026-09-15): since auto-setup was restored on Sep 14, 704
installer-triggered `composio setup` runs found no host 397 times (56%);
of the 316 that found one, 282 installed the plugin (89%). The gap is
host detection, and today a real absence is indistinguishable from a
PATH miss. Manual `composio setup` over 30 days: 888 succeeded, 626
failed, and `CLI_SETUP_FAILED` only carried `error_name`. 103 of those
failures (`yes=false, target=auto, stdout_is_tty=false`) are agents
following the daily hint text into "Non-interactive setup requires
`--yes`". No event said whether the CLI was running inside Claude Code
or Codex at all.
Event contract (metrics.composio.io is being built against these names):
- Every CLI event gains `agent_host_env: 'claude' | 'codex' | 'none'`,
derived from `CLAUDECODE` / `CODEX_THREAD_ID` / `CODEX_SANDBOX`.
- `CLI_SETUP_HOST_DETECTED` gains `host_config_dir_present` and
`host_binary_in_known_paths` when `available=false`
(`$CLAUDE_CONFIG_DIR`/`~/.claude`, `$CODEX_HOME`/`~/.codex`;
`~/.claude/local`, `~/.local/bin`, `~/.npm-global/bin`,
`/usr/local/bin`, `/opt/homebrew/bin`). Both omitted when the host is
detected.
- New `CLI_PLUGIN_HINT_SHOWN` (journey stage `setup`) with `source`,
`invocation_origin`, `cli_version`, `command_path`, `agent_host`,
emitted once per printed hint and never on suppression.
- `CLI_SETUP_FAILED` gains `failure_reason_code`:
`all_requires_both_hosts | unsupported_host | target_not_installed |
no_host_detected | non_interactive_requires_yes | marketplace_conflict |
unknown`, carried on `SetupCommandError.reasonCode`.
- Hint text is now `Tip: running under <host> without the Composio
plugin — 'composio setup --yes' installs it.`
Structural notes: `agent_host_env` is stamped in `trackCliEventEffect`
(`analytics/dispatch.ts`) next to `org_id`, so every enqueued envelope
carries it with no module state or bootstrap hook. `SetupCommandError`
and `SetupFailureReasonCode` live in the leaf module
`services/setup-command-error.ts` (imports only `effect`) so
`analytics/events.ts` can use `instanceof` without a cycle;
`setup.cmd.ts` keeps its original `setupCommandError` helper with the
reason code as a third argument, and the two validate-stage failures in
`services/setup.ts` (`marketplace_conflict`, `target_not_installed`) are
raised as `SetupCommandError` directly. The raw host-env read,
`detectPluginHost`, and the known-path install probe live in
`services/agent-host-env.ts`, shared by `dispatch.ts`, `plugin-hint.ts`,
and `setup.ts`. `CLI_SETUP_HOST_DETECTED` passes the two presence
booleans straight through; `setup.ts` only probes an undetected host.
The hint tracks `CLI_PLUGIN_HINT_SHOWN` right where it prints.
## Validation
- `pnpm --filter @composio/cli` `pnpm run test` (validate:skills,
validate:boundaries, vitest): 132 files, 1374 passed, 1 skipped.
- `pnpm run typecheck` (src + test): clean.
- `oxlint` on the 14 changed TS files: clean. `prettier --check` on
changed files: clean. `git diff --check`: clean.
- `pnpm validate:agent-skills` and `pnpm validate:skill-routing`: pass
(skill reference doc changed).
- Manual, built binary with isolated
`HOME`/`COMPOSIO_CACHE_DIR`/`CLAUDE_CONFIG_DIR` and a dummy PostHog key
pointed at a dead local port: `CLAUDECODE=1 composio whoami
--telemetry-debug` printed the new hint once and enqueued
`CLI_PLUGIN_HINT_SHOWN` (`command_path: whoami`, `agent_host: claude`)
plus `CLI_COMMAND_INVOKED`/`SUCCEEDED`, all with `agent_host_env:
claude`; a second run printed no hint and no hint event.
`PATH=/usr/bin:/bin composio setup --target codex --yes
--telemetry-debug` enqueued `CLI_SETUP_HOST_DETECTED` with `available:
false, host_config_dir_present: true, host_binary_in_known_paths: false`
and `CLI_SETUP_FAILED` with `failure_reason_code: target_not_installed`.
Re-run after each simplification pass with identical output; with the
host markers unset the same events carry `agent_host_env: none`.
## Known verification limitations
- No changeset: `@composio/cli` is ignored by Changesets per
`ts/AGENTS.md`; the note went into `ts/packages/cli/CHANGELOG.md`
instead.
- Docker CLI E2E not run; no binary output contract changed except the
hint line.
- `host_binary_in_known_paths` checks two absolute directories, so the
"absent everywhere" test asserts a boolean rather than `false` to stay
machine-independent.
Not included: any change to `composio setup` help text or to the
dashboard side.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Explains how to identify a connected account by its provider-side
identity (state.val.displayName), separate from the user-set alias.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The setup-plugins suite pins the recovery command printed when native
plugin inspection fails. setup remediation messages now carry --yes so
non-interactive agents get a command that completes, so the pinned
'composio setup --target claude' fragment became
'composio setup --yes --target claude'. Matches the exact stderr CI
reported on the failing scratch run.
validateInitialState hardcodes operation 'setup' in its SetupCommandError
while its only caller, the exported inspectSetupTargets, already threads
options.operation for wording. Uninstall skips validation today
(allowMarketplaceConflict: uninstall), so nothing mislabels now, but any
future uninstall caller that validates would get operation 'setup' and the
wrong failure_reason_code in telemetry. Pass options.operation ?? 'setup'
through and use it in both constructions.
The plugin hint learned to say 'composio setup --yes', but the error
messages an agent hits next still suggested bare reruns that deterministically
fail again with non_interactive_requires_yes in a non-TTY shell - the same
103-failure loop this PR set out to fix. Add --yes to the targeted-missing and
no-host messages in setup.cmd, the validate-stage target/marketplace messages,
the verify-stage messages, and the shared recovery-hint command; the most
conflicting case also walked agents through the destructive marketplace
remove before a rerun that could not succeed.
Interactive users can drop the flag; agents get a command that actually
completes. Adds rerun-message assertions for the three reachable failure
paths.
showPluginHint claims the 24h stamp before printing, so a print that did
not succeed left the stamp standing: the hint was never delivered yet both
the hint and CLI_PLUGIN_HINT_SHOWN stayed muted for the full interval.
Capture the print with Effect.exit and remove the just-created stamp on
any non-success exit so the next invocation can retry.
Tracking stays best-effort by contract: trackCliEventEffect never fails,
so a delivered hint with a lost event is accepted and does not un-claim.
resolvePluginHintConfig inlined the same env-override-else-~/.claude and
~/.codex fallback expressions that agent-host-env.ts now owns, leaving the
host-dir default written three times across two files. Use the shared
helper for both file paths and drop the now-unused NodeOs yield.
The 'preserves nonblank path overrides' test asserted verbatim pass-through
of relative overrides, which was the cwd dependence the probe hardening
removes. It now pins absolute overrides preserved as-is plus a new case
asserting relative overrides anchor to the home directory.
CLAUDE_CONFIG_DIR / CODEX_HOME were passed verbatim to the install probe,
so a relative override resolved against the process cwd (making
host_config_dir_present depend on where composio was invoked) and a plain
file at the config path counted as 'present'. Resolve overrides against
the home directory - matching how the known-binary list already resolves -
and probe with stat so presence means an actual directory. Unreadable
paths report false instead of failing the probe.
rawHostEnvironment re-implemented by hand what src/services/config.ts already
provides: a fresh unprefixed ConfigProvider.fromEnv() per execution with
orDie error handling. Build the five host keys as one Config.all and load
them via loadHostConfig, deleting the bespoke readOptionalEnv helper and the
per-call provideServiceEffect override. The fromEnv snapshot rationale now
lives only in config.ts's documented getBaseConfigProvider.
Behavior is unchanged: same live-env semantics (vi.stubEnv stays observable),
same blank-marker handling, same orDie on config failures.
## Summary
Rebuilds the docs social preview (`/api/og`) as one shared shell with a
slot per section, on the docs dark surface.
- **Shell:** dark ground with a faded pixel-grid background, Composio
wordmark top-left, mono uppercase section eyebrow top-right, centered
content. `theme=light` renders the flat light surface.
- **Docs:** balanced title plus description.
- **Toolkits:** Composio mark and toolkit logo in linked tiles, "<Name>
Toolkit" title, description. No tile when there is no logo. Logos load
only from `logos.composio.dev` / `assets.composio.dev` over https and
use the CDN's `theme=dark` variant.
- **API reference:** REST API pill with the version label.
- **Changelog:** date shown once as an eyebrow; multi-entry days use "N
updates" as the title so the date is not repeated.
- **Home:** headline with brand-blue accent and a description that
counts apps from the live catalog label.
Type is Geist Sans / Geist Mono, vendored as TTF with the OFL because
Satori cannot read the site's woff2 files. The wordmark and mark are
sliced from the existing logo SVGs; no new brand asset was added. Fonts,
logos, and the background are added to `outputFileTracingIncludes` so
the route ships them on Vercel.
`getOgImageUrl` now emits `section` and optional `logo`, `date`, and
`version` params; the toolkit, changelog, and reference pages pass them.
## Before / after
Before: charcoal card, orange accent, default sans-serif, identical for
every section.
After (dark by default):
| Home | Toolkit | Reference | Changelog |
| --- | --- | --- | --- |
| headline + description | mark ⟶ logo, title, description | pill +
version, title | date eyebrow, title |
## Notes
- Output PNGs are ~1.5 MB each because of the photographic background; a
flatter texture would bring that down if it matters.
- Typecheck errors in this branch (`LayoutProps`, `PageProps`,
`docs-index`) predate the change and come from missing generated types
without a build.
- The 8 failing static tests are in `kb-update-workflow.test.ts` and are
unrelated.
## Test plan
- [x] `bun test tests/static/og-image.test.ts` — 6 tests: every section
renders a 1200×630 PNG, URL builder forwards params, logo host
allowlist, theme default and override
- [x] Rendered every variant locally and reviewed the PNGs
- [ ] Verify a deployed preview URL renders
`/api/og?section=toolkits&title=GitHub&logo=https%3A%2F%2Flogos.composio.dev%2Fapi%2Fgithub`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
sdkrelease[bot]