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, 08:30 UTC
docs: clarify session.execute result shape and success checks (#4978)
## Summary Clarify the current `session.execute()` result contract in the canonical session guide so integrations do not confuse session results with direct execution results or tool-specific payloads. Source: Gauge action `cmtw6ww2z00460itkggry6bsy`, [underlying run](https://agents.withgauge.com/composio-aclx/runs/cmtvyjvhx000201j6zask5h9f). The run used `@composio/core@0.18.1` and hit a type error after assuming a top-level `successful` field. Its workaround is not the current contract: current sessions expose `resultType` (`result_type` in Python), which is authoritative even when `error` is null or empty. A nested `data.successful` field is tool-specific, not guaranteed. ## Changes - Add explicit Python and TypeScript failure handling to the existing session execution examples, with log IDs in fallback errors. - Document `data`, `error`, `logId`/`log_id`, and `resultType`/`result_type`, plus optional Instant charge reporting. - Distinguish the session envelope from direct execution results and tool payloads; explicitly warn against a general `result.data.successful` check. - Keep existing input-required exception guidance and provider requirements intact. Only `docs/content/docs/how-composio-works.mdx` changes. SDK reference pages are generated and are intentionally not hand-edited. No runtime changes or Changeset. ## Type of change - [x] Documentation ## How Has This Been Tested? From `docs/`, after synchronizing the local dependency tree with `bun install --frozen-lockfile`: - `bun run build` passed, including Twoslash checking of the TypeScript example. - `bun run test`: 732 passed, 0 failed. - `bun run lint` passed with existing warnings in unrelated files. - `bun run types:check` passed. - `bun run lint:links` passed: 0 errors, including SDK links. - `bun run check:kb-semantic --allow-stale` passed with the expected stale-content-hash warning; search falls back to keyword results until the existing rebuild workflow refreshes the artifact. - Opened `/docs/how-composio-works` in Chromium and visually checked the result table and both Python/TypeScript examples. Inspected `/docs/how-composio-works.md` for the same guidance. - Executed the exact edited Python and TypeScript example bodies against three deterministic response fixtures: completed without a nested success flag, failed with a null error, and failed with an empty error plus misleading `data.successful: true`. All six cases passed. The TypeScript fixtures went through the real SDK response transformer and schema. No permanent tests added: this is a docs-only clarification of an existing contract. The example smoke checks were throwaway scripts and made no external tool calls. The first build attempt exposed stale/missing local dependencies, including a pre-resultType SDK and missing icon package. Installing the existing lockfile resolved those failures without dependency or lockfile changes. ## Checklist - [x] Reviewed the change and verified the documented contract against SDK source. - [x] No new third-party documentation links. - [x] Updated documentation and exercised the changed examples. - [x] No Changeset needed for a docs-only change. ## Additional context The original Gauge recommendation to universally check `data.successful` should not be applied to the current SDK. This PR documents `resultType` instead. Please review the full diff before merging.