Alberto Schiabel
100d56866f
This PR: - Closes https://github.com/ComposioHQ/composio/issues/4343 - stamps eve's durable callback descriptors on every tool `EveProvider` wraps, via the new internal `withDurableClosure(closure, callback)` helper — eve only stamps them on `defineTool` calls its build transform finds in the agent's own source, which never runs on this package inside `node_modules`, so eve discarded the whole resolver result and the agent silently lost every Composio tool - persists `{ slug, binding }` per callback, where `binding` is an id minted per `wrapTools` call and prefixed with a per-process token, and re-attaches it to that resolve's Composio executor through a module-level binding map. `executeTool` is bound to one Composio session, so a slug-only closure would have routed a call to whichever session resolved last; sessions for different users share one provider, and eve's callback registry is keyed by tool name only, so the map lives at module level rather than on the instance - covers `execute` and, when `needsApproval` is set, `approvalRequest`; the descriptor key is the global-registry symbol `Symbol.for('eve:durable-dynamic-callback')`, so no eve internal is imported and the stamp is inert on eve versions that predate the contract - adds 9 regression tests: descriptor presence and shape, JSON-serializability of the closure, replay of execute and approval from the closure alone, per-resolve executor isolation when sessions share a provider, hooks of the producing provider on replay, the unknown-slug and unknown-binding errors, that two fresh module instances never mint the same binding id, and one suite that loads eve 0.52.1's own `validateDurableDynamicToolCallbacks`, `replayDynamicTools`, and callback registry from the installed package to validate and replay a wrapped tool end to end. Before the change eve threw `Dynamic tool "..." callback "execute" does not have a durable descriptor` ## Context The reporter hit this on eve 0.50 as `non-serializable capture`; 0.52.1 reports the same root cause as a missing descriptor. eve exports no public durable-callback helper (tracked at vercel/eve#2967), so the provider stamps the descriptor itself rather than pinning users to an older eve. Bindings are kept for the life of the process: eve can resume a parked call at any time. A binding lives only in the process that resolved the tools, so a call parked across a restart cannot be replayed; the per-process token in the id makes the stale closure fail the lookup loudly instead of matching whichever resolve reused its counter value in the new process. Growth is one entry per `session.tools()` resolve. Docs (`/docs/providers/eve`) now state the contract, the restart limit, and the real reason the `step.started` resolver runs each step (principal re-evaluation and retry, cached per session). Also unblocks `Docs - Tests` on this branch: the catalog refresh in #4330 renamed Stripe's triggers, so the Stripe knowledge-base guide cited two dead slugs and the corpus verifier failed for any PR touching docs. The guide now cites only the renamed slug the catalog lists, and `generate-toolkits.ts` fetches trigger types with `limit=1000` so the catalog stops truncating every toolkit to its first 20 triggers. https://claude.ai/code/session_019wRk1S4Z6V6FWr4UsybGvR EOF -R ComposioHQ/composio
OpenAPI Scripts
fetch-with-retry.ts
Shared fetchWithRetry helper used by the data-generation scripts
(generate-toolkits.ts, generate-meta-tools.ts). It wraps the global fetch
with rate-limit-aware retry/backoff: it retries 429 and transient 5xx
responses, honors the Retry-After header when present, otherwise falls back to
exponential backoff with jitter, and caps attempts so CI still fails fast when
the backend is genuinely down.
This matters because generate-toolkits.ts issues ~6500 requests per run
(a few catalog pages + 3 per toolkit across a ~2.1k catalog), which can exceed
the backend request limit.
Before this helper, runs failed with 429, and generate-meta-tools.ts — which
runs immediately after — inherited the exhausted rate-limit window.
Toolkit versions
generate-toolkits.ts owns the complete toolkit catalog and always sources it
from the production API. For a version-only repair, run the narrower generator:
COMPOSIO_API_KEY=... bun run generate:toolkit-versions
Both paths share toolkit-versions.ts, so they fetch and apply changelog values
with identical semantics: a toolkit missing from the production changelog gets
version: null. Any COMPOSIO_API_BASE override must normalize to
https://backend.composio.dev/api/v3; non-production sources fail before a
request is made.
fetch-openapi.mjs
Fetches the Composio OpenAPI spec and filters it for use in Fumadocs API reference documentation.
Usage
bun run scripts/fetch-openapi.mjs
This outputs public/openapi.json which is used by lib/openapi.ts.
Why Filtering is Needed
The raw OpenAPI spec from https://backend.composio.dev/api/v3/openapi.json has issues that break documentation generators:
- Endpoints with multiple tags - Causes duplicate entries in sidebar
- Internal endpoints exposed - CLI, Admin, Profiling endpoints shouldn't be in public docs
See OPENAPI_IMPROVEMENTS.md in the fumadocs root for planned fixes to the spec itself.
What Gets Filtered
Ignored Paths
These endpoints are completely removed:
/api/v3/mcp/validate/{uuid}/api/v3/cli/get-session/api/v3/cli/create-session/api/v3/auth/session/logout
Ignored Tags
Endpoints with only these tags are removed:
CLIAdminProfiling
Duplicate Prevention
If an endpoint has multiple tags, only the first tag is kept. This prevents the same endpoint appearing in multiple sidebar sections.
Configuration
The script uses environment variables:
| Variable | Default | Description |
|---|---|---|
OPENAPI_SPEC_URL |
https://backend.composio.dev/api/v3/openapi.json |
Source OpenAPI spec URL |
For staging deployments, set:
OPENAPI_SPEC_URL=https://staging.composio.dev/api/v3/openapi.json
verify-kb.ts
Checks published KB guides against the production data this repo already
refreshes. Runs inside docs-update-data.yml right after the catalog and
OpenAPI specs are regenerated, so freshness is verified on every production
deploy instead of on a review calendar.
bun run verify:kb # catalog checks only, no network
bun run verify:kb --check-links # also probe provider doc links
bun run verify:kb --json # machine-readable report
bun run verify:kb --markdown out.md # write the report to a file
Exits non-zero when any finding is an error. --warnings-as-errors promotes
warnings too. See docs/decisions/kb-freshness-verification.md for what is
checked and why placeholders, bare URLs, and 5xx responses are excluded.
A guide that deliberately cites a removed identifier declares it in
verifyIgnoreToolSlugs in kb/manifest.json.
--check-source-pin resolves manifest.source.commit against the upstream KB
repository. It needs GH_TOKEN/GITHUB_TOKEN with read access there; without
it the check reports "unverifiable" and emits nothing, so a narrow token
degrades quietly instead of reporting false provenance breakage.