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
docs: reconcile polling, proxy permissions, and SDK examples (#5476)
> Written by an AI agent for Brendan, following his spec. Brendan has not reviewed the full diff yet. ## Summary Reconcile the four inconsistencies reported in the [November 14 docs audit thread](https://composioworkspace.slack.com/archives/C0BR8LGHJP8/p1794695300065769) against current `origin/next`, the SDK implementations, the live tool catalog, and the backend permission enforcement code. | Item | Already fixed or verified | This PR | | --- | --- | --- | | Polling | #5149 corrected the managed polling minimum; the trigger overview and troubleshooting already say 2 minutes | Use 2 minutes in remaining maintained trigger examples and state the default explicitly | | Proxy permissions | The backend grants the session proxy route through **either** Session tool execution or Proxy execute with write access | Remove the incorrect exclusive-permission claims from guides, the permission reference, and KB; retain Proxy execute as required for the direct route | | GitHub tool slug | Catalog confirms `GITHUB_CREATE_AN_ISSUE`, required `owner`, `repo`, `title`, optional `body` | Correct maintained guides, API overviews, agent instructions, SDK source comments, and regenerated references; existing concrete arguments match the catalog schema | | Local tools | #5215 implemented local names and deprecated aliases; #5213 renamed the docs page but left old options in examples | Use local options and session methods in current examples; explain deprecated aliases once, Python warnings, and rejection of both names together | Designated reviewer: @jkomyno. Please review the full diff before merging. ## Changes - Keep all changelogs unchanged. The March 2026 polling entries, including whether to correct or supersede them, remain Brendan's decision. Historical examples retain their old spellings under this constraint. - Preserve Pi's unrelated `customTools` option and the server-side Custom MCP `customToolkits` API. API wire fields named `custom_tools` also remain unchanged. - Regenerate SDK references with their owning TypeScript/Python generators and API overviews with `generate:api-index`. SDK source edits are docstrings/comments only; no runtime behavior or public API changes, so no changeset. - Checked merged and open PRs. In particular, #5322's per-app trigger table, #5065's SDK docs automation, and #5474's stale semantic artifact repair are separate work and are not duplicated here. <!-- sdk-release-note-exempt: SDK source edits only correct slugs inside docstrings and comments; runtime code and public API behavior are unchanged. --> ## Type of change - [x] Documentation ## How Has This Been Tested? **Primary source for proxy permissions:** [platform catalog at `3c17ab7b`](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/catalog.ts#L182), [route matching](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/match.ts#L36), and [enforcement](https://github.com/ComposioHQ/platform/blob/3c17ab7b800a75df7cf3f27f6b625754eae86741/apps/apollo/src/lib/apiKeys/project_api_key_permissions/enforce.ts#L48). I downloaded these source files and executed their actual matching/enforcement functions with one permission at a time. Both API versions returned: | Key permission, write access | Session proxy | Direct proxy | | --- | --- | --- | | `session_tool_execution` | allowed | denied | | `proxy_execute` | allowed | allowed | | `session_management` | denied | denied | | `tool_execution` | denied | denied | This verifies source behavior, not a live request with separately scoped keys. The change that would have made Proxy execute exclusive, [platform#12846](https://github.com/ComposioHQ/platform/pull/12846), was closed without merging. The removed claim about sandbox inheritance was not supported by this API-key check: sandbox helpers use a separate WORKBENCH-authenticated internal route. Existing sandbox configuration guidance is retained. **Local checks:** - `composio execute GITHUB_CREATE_AN_ISSUE --get-schema`: catalog version `20261116_01`; inspected schema and concrete example arguments. No tool executed. - `bun run check:code-examples`, `check:api-snippets`, `check:python-snippets`, `check:typescript-snippets`: pass. - `bun run lint`: passes with existing warnings. `bun run lint:links`: 0 errors. The first link check raced SDK reference regeneration; the rerun after regeneration passed. - `bun run types:check`: pass. - `GITHUB_ACTIONS=true timeout 20m bun run build`: exit 0, including Twoslash. Run in the foreground with no overlapping docs build. - Static suite: `bun run test --timeout 30000` passed all 816 tests, 0 failures. Initial run had 811 pass and 5 five-second timeouts while the build ran; the complete rerun passed. - Compared Python runtime ASTs and TypeScript printed ASTs with comments removed: unchanged for every SDK source file edited. - Independent Claude Sonnet 5.5 docs/evidence review found no blocking correctness issue; fixed its finding about old names in handwritten TS SDK guides. ## Checklist - [x] Read and reviewed the diff, including AI-generated changes - [x] Documentation updated; no runtime changes or new dependencies - [x] Third-party links follow the contribution policy - [x] No new tests needed for these prose/example corrections; existing docs checks exercised - [ ] All GitHub checks green before marking ready ## Additional context NEEDS BRENDAN: leave the March 2026 polling changelogs alone, add a correction note, or publish a new entry? This PR makes none of those choices. No unresolved source question remains for the public proxy API-key permission check. ELI5: Some docs used old names or described a restriction the backend never adopted. This makes current examples match the SDK and backend while leaving release-history decisions to Brendan.