@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

next
md 90 lines 5.21 KB
Rendered Raw
1 # Toolkit Page Availability
2
3 ## Decision
4
5 Keep generated toolkit snapshots authoritative, but allow an individual toolkit
6 page to query production when its slug is absent from the snapshot. The fallback
7 is snapshot-first and limited to one validated slug. It is not a live catalog
8 and does not change how the toolkit landing page, sitemap, search, KB
9 verification, or `llms.mdx` resolve toolkit data.
10
11 Keep the primary docs-sync GitHub App token limited to repository contents and
12 pull requests. It must not request `issues`. Steps that create, update, or close
13 issues in this repository use `github.token` under the workflow's job-level
14 `issues: write` permission.
15
16 ## Context
17
18 The toolkit pages were coupled to the freshness of
19 `public/data/toolkits.json`. When the docs data sync stopped before generation,
20 valid production toolkits added after the last snapshot returned 404. The
21 [toolkit page decisions](./toolkits.md) establish the generated snapshot as the
22 default data source, and the
23 [KB freshness decision](./kb-freshness-verification.md) relies on the same
24 snapshot architecture. The runtime fallback preserves those decisions while
25 removing snapshot freshness as an availability requirement for individual
26 toolkit pages.
27
28 The sync failure came from requesting a GitHub App permission that the
29 installation did not grant. Issue tracking does not need the App token because
30 it only writes to the current repository. The KB freshness check is optional and
31 non-fatal. A failure there can reduce KB freshness evidence, but it cannot block
32 toolkit, OpenAPI, API index, or meta-tool generation.
33
34 ## Consequences
35
36 - A snapshot hit renders without a production catalog request.
37 - A snapshot miss may issue one production lookup for the validated slug. An
38 invalid, excluded, disabled, custom, or unknown slug still returns 404. The
39 fallback only publishes enabled, Composio-managed toolkits.
40 - Landing, sitemap, search, KB verification, and build behavior remain
41 snapshot-backed.
42 - `/llms.mdx/toolkits/<slug>` parity is deferred. A toolkit available only
43 through the page fallback can still return 404 from that route.
44 - `COMPOSIO_TOOLKIT_LIVE_FALLBACK=0` disables the production lookup and restores
45 snapshot-only page resolution. Changing this Vercel environment variable does
46 not affect the running production deployment. Create a new Vercel deployment
47 after changing it. Re-enable the fallback by removing the value or setting it
48 to a value other than `0`, then deploy again.
49 - The guaranteed code rollback is to revert the toolkit route integration and
50 deploy the reverted revision.
51 - Every docs catalog read (toolkits, tools, trigger types, and the toolkit
52 changelog) goes through `@composio/client` (v3.1), built in
53 `lib/composio-api.ts`. `scripts/fetch-openapi.mjs` and `app/api/proxy` keep
54 raw `fetch`: the first downloads OpenAPI documents, and the second forwards
55 arbitrary playground requests. The toolkit page, `/llms.mdx` and
56 `/api/tools/[slug]` use `Composio.fromEnv`, so `COMPOSIO_BASE_URL` selects
57 the API host; the toolkit generator, `/api/toolkits/instant` and the snapshot-miss
58 lookup always call production. Lists use its
59 helpers, which page with `@composio/client/pagination`: toolkit pages and
60 `/llms.mdx/toolkits/<slug>` at `TOOL_PAGE_SIZE`, `/api/toolkits/instant` at
61 `TOOLKIT_PAGE_SIZE`, and `generate:toolkits` at the API's per-endpoint cap
62 (1000 tools or toolkits, 50 trigger types). Live traversals during a page
63 render abort after `LIVE_TRAVERSAL_TIMEOUT_MS` and fall back to the snapshot.
64 A failed traversal fails `generate:toolkits` instead of publishing an empty
65 list. In
66 Next.js each page is its own Data Cache entry. Next.js does not cache an
67 entry over 2 MiB, and keeps serving the previous entry; an entry holds the body
68 base64-encoded, so a response must stay under about 1.5 MiB. The limit is
69 fixed in Next.js and lifted only by a custom `cacheHandler`. A single
70 unpaginated request froze `tableau.md` at 10 of 436 tools after the toolkit
71 grew, and the snapshot stopped `microsoft_365` at 1000 of 1208 tools. oxlint
72 rejects a raw `fetch`, `fetcher` or `fetchWithRetry` call to `/api/v3*`.
73 - Dropping response fields does not replace paging. The API has no field
74 selection and the Data Cache stores response bodies as received. Even reduced
75 to the fields the pages render, `microsoft_365` measured 2.25 MB.
76 - Run `bun run lint:links` from `docs/` after editing this record.
77 - Dispatch `Docs - Update Data` at the exact reviewed head after changing token
78 permissions.
79 - After deployment, verify one snapshot-backed slug and one valid production
80 slug absent from the committed snapshot both return 200.
81 - `Docs - Toolkit Parity` runs `bun run check:toolkit-parity` every six hours.
82 For the toolkits with the most tools, ranked by production count and by
83 snapshot count, it fails when a deployed `.md` page
84 lists a tool count matching neither production nor the snapshot, when the
85 snapshot stops at the 1000-item page cap below production, when
86 `/api/toolkits/instant` differs from production, or when a production
87 `/tools` or `/toolkits` page would make a cache entry over
88 `PAGE_BYTES_BUDGET` (85% of 2 MiB). A failure opens one
89 `docs-toolkit-parity` issue, posts it to Slack, and the next clean run
90 closes it.