Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: enforce toolkit-version policy on execution samples via static test
Soumya Medapati70f6772037e0
diff --git a/docs/content/docs/auth-configuration/custom-auth-params.mdx b/docs/content/docs/auth-configuration/custom-auth-params.mdxindex ba5432362..775ae3f67 100644--- a/docs/content/docs/auth-configuration/custom-auth-params.mdx+++ b/docs/content/docs/auth-configuration/custom-auth-params.mdx@@ -21,7 +21,7 @@ Pass `customAuthParams` in the `tools.execute()` call to inject your own token a```pythonfrom composio import Composio-composio = Composio()+composio = Composio(toolkit_versions={"googlecalendar": "latest"})result = composio.tools.execute(slug="GOOGLECALENDAR_LIST_EVENTS",@@ -46,6 +46,7 @@ import { Composio } from "@composio/core";const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,+ toolkitVersions: { googlecalendar: "latest" },});const result = await composio.tools.execute(@@ -100,7 +101,7 @@ Before Execute Modifiers are a way to modify the parameters of a tool before itfrom composio import Composio, before_executefrom composio.types import ToolExecuteParams-composio = Composio()+composio = Composio(toolkit_versions={"notion": "latest"})@before_execute(toolkits=["NOTION"])diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdxindex 694769d2a..6ded98cb5 100644--- a/docs/content/docs/sessions-vs-direct-execution.mdx+++ b/docs/content/docs/sessions-vs-direct-execution.mdx@@ -122,7 +122,10 @@ Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()`from composio import Composiofrom composio_openai import OpenAIProvider-composio = Composio(provider=OpenAIProvider())+composio = Composio(+ provider=OpenAIProvider(),+ toolkit_versions={"github": "latest"}, # required for direct execution+)# Fetch specific toolstools = composio.tools.get(@@ -153,6 +156,7 @@ import { OpenAIProvider } from '@composio/openai';const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,provider: new OpenAIProvider(),+ toolkitVersions: { github: 'latest' }, // required for direct execution});// Fetch specific toolsdiff --git a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdxindex a20193eb5..b33126b2f 100644--- a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx+++ b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx@@ -122,7 +122,10 @@ from composio import Composio, after_executefrom composio.types import ToolExecutionResponsefrom composio_crewai import CrewAIProvider-composio = Composio(provider=CrewAIProvider())+composio = Composio(+ provider=CrewAIProvider(),+ toolkit_versions={"hackernews": "latest"},+)@after_execute(tools=["HACKERNEWS_GET_USER"])def after_execute_modifier(@@ -156,6 +159,7 @@ import { v4 as uuidv4 } from "uuid";const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,provider: new VercelProvider(),+ toolkitVersions: { hackernews: "latest" },});const userId = uuidv4();diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdxindex 28927521a..ec3208fff 100644--- a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx+++ b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx@@ -34,7 +34,7 @@ from openai import OpenAIfrom composio import Composio, before_executefrom composio.types import ToolExecuteParams-composio = Composio()+composio = Composio(toolkit_versions={"hackernews": "latest"})openai_client = OpenAI()user_id = "[email protected]"@@ -201,7 +201,7 @@ def audit_path(ctx) -> str | bool:# return a new path string, or False to abort the uploadreturn ctx["path"]-composio = Composio()+composio = Composio(toolkit_versions={"googledrive": "latest"})composio.tools.execute("GOOGLEDRIVE_UPLOAD_FILE",{"file_to_upload": "/path/to/document.pdf"},diff --git a/docs/tests/static/execute-version.test.ts b/docs/tests/static/execute-version.test.tsnew file mode 100644index 000000000..383ec5494--- /dev/null+++ b/docs/tests/static/execute-version.test.ts@@ -0,0 +1,116 @@+/**+ * Toolkit-version policy for direct-execution samples.+ *+ * Direct tool execution requires a toolkit version — `tools.execute()`+ * without one raises ToolVersionRequiredError at runtime. A 97-run agent+ * eval of the docs found the top failure (72/97 runs) was readers copying+ * version-less `tools.execute()` samples.+ *+ * Rule: any authored MDX page whose code fences call `tools.execute(` must+ * also show version configuration somewhere in its code fences — one of+ * `toolkit_versions` / `toolkitVersions` (constructor), `version=` /+ * `version:` (per-call), or a `COMPOSIO_TOOLKIT_VERSION_*` env var.+ *+ * Scope: content/docs and content/examples. Excluded: content/reference+ * (generated upstream), changelog (historical records), and+ * docs/migration-guide (point-in-time documents that may show old APIs).+ * The LLM guardrail blocks appended to .md responses are checked too —+ * they are samples agents copy verbatim.+ */+import { describe, test, expect } from "bun:test";+import { readdir, readFile } from "fs/promises";+import { join, relative } from "path";++import {+ SESSION_GUARDRAILS,+ DIRECT_EXECUTION_GUARDRAILS,+} from "../../lib/llm-guardrails";++const CONTENT_DIRS = ["docs", "examples"].map((dir) =>+ join(import.meta.dir, "../../content", dir),+);+const CONTENT_ROOT = join(import.meta.dir, "../../content");+const EXCLUDED_PATH_SEGMENTS = ["docs/migration-guide/"];++const EXECUTE_CALL_RE = /\btools\.execute\s*\(/;+const VERSION_TOKEN_RE =+ /toolkit_versions|toolkitVersions|version\s*[=:]|COMPOSIO_TOOLKIT_VERSION_|dangerously_skip_version_check|dangerouslySkipVersionCheck/;++async function findMdxFiles(dir: string): Promise<string[]> {+ const results: string[] = [];+ let entries;+ try {+ entries = await readdir(dir, { withFileTypes: true });+ } catch {+ return results;+ }++ for (const entry of entries) {+ const fullPath = join(dir, entry.name);+ if (entry.isDirectory()) {+ results.push(...(await findMdxFiles(fullPath)));+ } else if (entry.name.endsWith(".mdx")) {+ results.push(fullPath);+ }+ }+ return results;+}++/** Concatenated contents of all fenced code blocks in a document. */+function fencedCode(content: string): string {+ const fences: string[] = [];+ let inFence = false;+ for (const line of content.split("\n")) {+ if (/^\s*(```|~~~)/.test(line)) {+ inFence = !inFence;+ continue;+ }+ if (inFence) fences.push(line);+ }+ return fences.join("\n");+}++function violates(content: string): boolean {+ const code = fencedCode(content);+ return EXECUTE_CALL_RE.test(code) && !VERSION_TOKEN_RE.test(code);+}++describe("direct-execution samples show toolkit versions", () => {+ test("every authored page with a tools.execute() sample shows version configuration", async () => {+ const files = (+ await Promise.all(CONTENT_DIRS.map((dir) => findMdxFiles(dir)))+ ).flat();+ const failures: string[] = [];++ for (const file of files) {+ const relPath = relative(CONTENT_ROOT, file);+ if (EXCLUDED_PATH_SEGMENTS.some((seg) => relPath.startsWith(seg))) {+ continue;+ }+ const content = await readFile(file, "utf-8");+ if (violates(content)) {+ failures.push(relPath);+ }+ }++ expect(+ failures,+ `Pages with tools.execute() samples but no version configuration ` ++ `(add toolkit_versions/toolkitVersions to the constructor or ` ++ `version= per call — see /docs/tools-direct/toolkit-versioning):\n` ++ failures.map((f) => ` - ${f}`).join("\n"),+ ).toEqual([]);+ });++ test("LLM guardrail blocks with tools.execute() samples show version configuration", () => {+ for (const [name, guardrails] of [+ ["SESSION_GUARDRAILS", SESSION_GUARDRAILS],+ ["DIRECT_EXECUTION_GUARDRAILS", DIRECT_EXECUTION_GUARDRAILS],+ ] as const) {+ expect(+ violates(guardrails),+ `${name} contains a tools.execute() sample without version configuration`,+ ).toBe(false);+ }+ });+});