@devries-cameron20 / composio-1 / commits / d24c3210a
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.

docs: use session result status in harness execution examples (#5004)

## Summary Align the harness integration example with the current `session.execute()` result contract. Session results have no top-level `successful` field, and `data.successful` is tool-specific rather than a general success signal. The canonical session guide already documents this correctly, but the harness example still checked only `error`, which misses failed executions with null or empty error text. ## Changes - Check `result.resultType === 'failed'` in TypeScript and `result.result_type == "failed"` in Python. - Preserve upstream error text and include the execution log ID when error text is absent. - Explain the result envelope and link to the canonical result-handling guidance. - Correct the nearby exception guidance to include requests for user input. - Remove unnecessary global toolkit and meta-tool data mocks from the OpenAPI markdown tests. Bun carries module mocks across files; the empty toolkit mock contaminated the knowledge browse catalog when CI loaded this suite first. Docs and test-isolation changes only: no SDK or site runtime changes, generated reference edits, or changeset. ## Verification - `cd docs && bun run build` passed, including TypeScript/Twoslash checks. - `cd docs && bun run lint:links` passed: no link errors. - `cd docs && bun run test` passed: 732 tests, 0 failures. - Forced the OpenAPI suite to load before the knowledge browse and toolkit schema suites in a throwaway runner: 45 passed, 0 failed. The existing browse ordering test covers the regression. - `cd docs && bun run lint` passed with warnings outside the changed test file. - Executed the exact updated Python and TypeScript example bodies with controlled session responses: completed/no error, failed/upstream error, failed/null error, and failed/empty error (8 scenarios total). Both languages reject every failed result and preserve the fallback log ID. - Opened the local docs preview in Chromium, switched to the TypeScript tab, and visually verified the updated failure check. No live external tool action was invoked; execution handling was exercised with controlled responses. No new permanent test was needed: the existing knowledge browse ordering test detected the global mock leak. The ordered smoke runner was removed after verification. The build and link checks above cover the original docs commit; the static suite and lint were run again after the test-isolation fix. ## Context Gauge action `cmtw6ww2z00460itkggry6bsy` identified real result-shape confusion against `@composio/core@0.18.1`. Its suggested blanket `data.successful` check is obsolete; this PR follows the current `resultType` / `result_type` contract instead. Reviewer: @jkomyno.

Brendan O'Leary committed Oct 21, 2026 at 08:06 UTC d24c3210a9ee33c20cdee267f072017541c95dd3
2 files changed +9 -16
docs/content/examples/harness-integration.mdx
+7 -5
@@ -425,8 +425,8 @@ result = session.execute(
425 },
426 )
427
428 -if result.error:
429 - raise RuntimeError(result.error)
428 +if result.result_type == "failed":
429 + raise RuntimeError(result.error or f"Tool execution failed (log ID: {result.log_id})")
430
431 print(result.data)
432 print(result.log_id) # look this up in the dashboard
@@ -445,8 +445,8 @@ const result = await session.execute('GITHUB_CREATE_AN_ISSUE', {
445 body: 'Filed by the harness.',
446 });
447
448 -if (result.error) {
449 - throw new Error(result.error);
448 +if (result.resultType === 'failed') {
449 + throw new Error(result.error || `Tool execution failed (log ID: ${result.logId})`);
450 }
451
452 console.log(result.data);
@@ -455,7 +455,9 @@ console.log(result.logId); // look this up in the dashboard
455 </Tab>
456 </Tabs>
457
458 -Arguments go through untouched: neither SDK validates them locally, so a wrong field reaches the upstream API and comes back as a populated `error` your planner can read and correct on the next turn, not as an exception. Exceptions are for transport failures and cancellation. `logId` ties the call to its entry in the dashboard, which is the fastest way to see what Composio actually sent upstream when a response surprises you.
458 +Check `resultType` (`result_type` in Python), not `error`, to tell whether execution succeeded. A failed execution can have null or empty error text. The tool-specific `data` payload has no guaranteed `successful` field. See [Reading execution results](/docs/how-composio-works#reading-execution-results) for the result envelope.
459 +
460 +Transport failures, cancellation, and [requests for user input](/docs/how-composio-works#handling-requests-for-user-input) can raise exceptions instead of returning a result. `logId` (`log_id` in Python) ties the call to its entry in the dashboard so you can inspect what Composio sent upstream.
461
462 When the thing you need isn't wrapped as a tool, [`session.proxyExecute()`](/docs/extending-sessions/proxy-execute) calls the raw API endpoint under the same connected account.
463
docs/tests/static/llms-openapi.test.ts
+2 -11
@@ -15,17 +15,8 @@ mock.module("next/navigation", () => ({
15 usePathname: () => "/reference/api-reference/tasks",
16 useSearchParams: () => new URLSearchParams(),
17 }));
18 -mock.module("@/lib/toolkit-data", () => ({
19 - getAllToolkits: async () => [],
20 - getAllToolkitsSync: () => [],
21 - getToolkitBySlug: async () => null,
22 -}));
23 -mock.module("@/lib/meta-tools-data", () => ({
24 - getAllMetaTools: async () => [],
25 - getMetaToolBySlug: async () => null,
26 -}));
27 -// Keep toolkit-schema real: module mocks persist across files in Bun and would
28 -// replace the transformations tested by toolkit-schema.test.ts when it runs later.
18 +// Keep catalog loaders and schema helpers real: Bun module mocks persist across
19 +// files and can empty the knowledge catalog or replace transformations in later suites.
20
21 let openapiPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").openapiPageToMarkdown;
22 let degradedPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").degradedPageToMarkdown;