@devries-cameron20 / composio-1 / commits / a81ccf091
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: restore proxy execute reference with a shared data model (#5155)

This PR: - builds on David's reference work in [#4740](https://github.com/ComposioHQ/composio/pull/4740) ([Glen review](https://app.tryglen.com/ComposioHQ/composio/pull/4740)), retaining the parts missing from `next`. - closes [PLEN-4069](https://linear.app/composio/issue/PLEN-4069). - enables `proxy_execute` in the generator session and regenerates the reference page, index, sidebar, and schema from production; no other tool's data changes. - documents `toolkit_slug`, parameter `type`, `HEAD`, tool failures, upstream non-2xx responses, and sandbox offloading while preserving the existing explicit-`false` behavior. - validates the meta-tool snapshot with recursive Zod schemas and projects it into one display model before rendering; HTML and Markdown consume normalized type labels, defaults, descriptions, and required fields without schema casts or fallback chains. - includes the reference's usage copy in Markdown so agents receive the same argument and failure guidance. Validation: 46 focused tests pass; docs type checks, lint (existing warnings), link checks, and `git diff --check` pass. The new tests reproduce the missing generator opt-in and broken HTML/Markdown type labels before their fixes. A production session lists all seven meta tools. Local Next.js HTTP checks return 200 for all seven meta tools in both HTML and Markdown. The model tests cover unrestricted JSON, nested arrays, required item fields, falsy defaults, scalar enums, and malformed schema rejection. No SDK/runtime changes or changeset. This carries forward the remaining reference scope from #4740; the older PR can be closed after this merges.

Alberto Schiabel committed Oct 29, 2026 at 23:50 UTC a81ccf0914e1f0f4343c92c45322624000cc8ea2
12 files changed +453 -114
docs/app/llms.mdx/[[...slug]]/route.ts
+23 -31
@@ -1158,48 +1158,32 @@ function renderMetaToolParams(
1158 const prefix = ' '.repeat(indent);
1159
1160 for (const [name, param] of Object.entries(properties)) {
1161 - const typeStr =
1162 - param.type === 'array' &&
1163 - param.items &&
1164 - typeof param.items === 'object' &&
1165 - (param.items as Record<string, unknown>).type
1166 - ? `array<${(param.items as Record<string, unknown>).type}>`
1167 - : param.type;
1161 const reqMark = requiredFields.includes(name) ? ' *(required)*' : '';
1162 const desc = param.description
1170 - ? `: ${param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}`
1163 + ? `: ${param.description}`
1164 : '';
1165 const defaultStr =
1173 - param.default !== undefined && param.default !== null && param.default !== ''
1174 - ? ` (default: \`${String(param.default)}\`)`
1166 + param.defaultLabel !== null
1167 + ? ` (default: \`${param.defaultLabel}\`)`
1168 : '';
1169 const enumStr =
1177 - param.enum && param.enum.length > 0
1170 + param.enum.length > 0
1171 ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
1172 : '';
1173
1181 - lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}${defaultStr}${enumStr}`);
1174 + lines.push(`${prefix}- \`${name}\` (${param.typeLabel})${reqMark}${desc}${defaultStr}${enumStr}`);
1175
1183 - if (param.properties && Object.keys(param.properties).length > 0) {
1184 - const nestedRequired = Array.isArray(param.required) ? param.required : [];
1185 - lines.push(...renderMetaToolParams(param.properties, nestedRequired, indent + 1));
1176 + if (Object.keys(param.properties).length > 0) {
1177 + lines.push(...renderMetaToolParams(param.properties, param.required, indent + 1));
1178 }
1179
1188 - const items =
1189 - param.items && typeof param.items === 'object'
1190 - ? (param.items as Record<string, unknown>)
1191 - : null;
1192 - if (
1193 - items?.properties &&
1194 - typeof items.properties === 'object' &&
1195 - Object.keys(items.properties as object).length > 0
1196 - ) {
1197 - const itemsRequired = Array.isArray(items.required) ? (items.required as string[]) : [];
1180 + const items = param.items;
1181 + if (items && Object.keys(items.properties).length > 0) {
1182 lines.push(`${prefix} - Array items:`);
1183 lines.push(
1184 ...renderMetaToolParams(
1201 - items.properties as Record<string, MetaToolParameter>,
1202 - itemsRequired,
1185 + items.properties,
1186 + items.required,
1187 indent + 2
1188 )
1189 );
@@ -1219,17 +1203,25 @@ function metaToolToMarkdown(tool: MetaTool): string {
1203
1204 lines.push('');
1205
1222 - const inputProps = tool.inputParameters?.properties || {};
1206 + lines.push(tool.summary, '');
1207 + if (tool.whenToUse) {
1208 + lines.push('## When to use it', '', tool.whenToUse, '');
1209 + }
1210 + if (tool.usageNote) {
1211 + lines.push(tool.usageNote, '');
1212 + }
1213 +
1214 + const inputProps = tool.inputParameters.properties;
1215 if (Object.keys(inputProps).length > 0) {
1216 lines.push('## Input Parameters', '');
1225 - lines.push(...renderMetaToolParams(inputProps, tool.inputParameters?.required || []));
1217 + lines.push(...renderMetaToolParams(inputProps, tool.inputParameters.required));
1218 lines.push('');
1219 }
1220
1229 - const responseProps = tool.responseSchema?.properties || {};
1221 + const responseProps = tool.responseSchema.properties;
1222 if (Object.keys(responseProps).length > 0) {
1223 lines.push('## Response', '');
1232 - lines.push(...renderMetaToolParams(responseProps, tool.responseSchema?.required || []));
1224 + lines.push(...renderMetaToolParams(responseProps, tool.responseSchema.required));
1225 lines.push('');
1226 }
1227
docs/components/meta-tools/meta-tool-detail.tsx
+14 -28
@@ -25,13 +25,6 @@ const TAG_LABELS: Record<string, { label: string; className: string }> = {
25 },
26 };
27
28 -/** Extract the required field names array from a schema-like object */
29 -function getRequiredFields(schema: unknown): string[] {
30 - if (!schema || typeof schema !== 'object') return [];
31 - const req = (schema as Record<string, unknown>).required;
32 - return Array.isArray(req) ? req : [];
33 -}
34 -
28 function TagBadge({ tag }: { tag: string }) {
29 const info = TAG_LABELS[tag];
30 if (!info) return null;
@@ -43,37 +36,32 @@ function TagBadge({ tag }: { tag: string }) {
36 }
37
38 function ParameterRow({ name, param, isLast, showRequired = true, isRequired = false }: { name: string; param: MetaToolParameter; isLast: boolean; showRequired?: boolean; isRequired?: boolean }) {
46 - const hasNested = param.properties && Object.keys(param.properties).length > 0;
47 - const items = param.items && typeof param.items === 'object' ? param.items as Record<string, unknown> : null;
48 - const itemsHaveProperties = items && typeof items.properties === 'object' && Object.keys(items.properties as object).length > 0;
39 + const hasNested = Object.keys(param.properties).length > 0;
40 + const nestedSchema = hasNested ? param : param.items;
41 + const nestedCount = nestedSchema ? Object.keys(nestedSchema.properties).length : 0;
42 const [isOpen, setIsOpen] = useState(false);
43
51 - // Show array<itemType> for simple item types
52 - const typeLabel = param.type === 'array' && items?.type && !itemsHaveProperties
53 - ? `array<${items.type}>`
54 - : param.type;
55 -
44 return (
45 <div className={cn(!isLast && 'border-b border-fd-border')}>
46 <div className="py-3">
47 <div className="flex flex-wrap items-center gap-2">
48 <code className="text-sm font-semibold font-mono text-fd-foreground">{name}</code>
61 - <span className="text-xs font-mono text-fd-muted-foreground">{typeLabel}</span>
49 + <span className="text-xs font-mono text-fd-muted-foreground">{param.typeLabel}</span>
50 {showRequired && isRequired && (
51 <span className="text-xs font-medium text-red-500 dark:text-red-400">Required</span>
52 )}
65 - {param.default !== undefined && param.default !== null && param.default !== '' && (
53 + {param.defaultLabel !== null && (
54 <span className="text-xs text-fd-muted-foreground">
67 - Default: <code className="rounded border border-fd-border px-1 py-0.5 text-xs">{String(param.default)}</code>
55 + Default: <code className="rounded border border-fd-border px-1 py-0.5 text-xs">{param.defaultLabel}</code>
56 </span>
57 )}
58 </div>
59 {param.description && (
60 <p className="mt-1.5 text-sm text-fd-muted-foreground leading-relaxed">
73 - {param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}
61 + {param.description}
62 </p>
63 )}
76 - {param.enum && param.enum.length > 0 && (
64 + {param.enum.length > 0 && (
65 <div className="mt-2">
66 <span className="text-xs text-fd-muted-foreground">Possible values: </span>
67 <span className="inline-flex flex-wrap gap-1 mt-0.5">
@@ -85,19 +73,17 @@ function ParameterRow({ name, param, isLast, showRequired = true, isRequired = f
73 </span>
74 </div>
75 )}
88 - {(hasNested || itemsHaveProperties) && (
76 + {nestedSchema && nestedCount > 0 && (
77 <Collapsible open={isOpen} onOpenChange={setIsOpen} className="mt-2">
78 <CollapsibleTrigger className="flex items-center gap-1 text-xs text-fd-muted-foreground hover:text-fd-foreground font-medium transition-colors">
79 {isOpen ? <ChevronDown className="h-3 w-3" /> : <ChevronRight className="h-3 w-3" />}
92 - {hasNested
93 - ? `Show ${Object.keys(param.properties!).length} properties`
94 - : `Show ${Object.keys((items!.properties as object)).length} item properties`}
80 + {hasNested ? `Show ${nestedCount} properties` : `Show ${nestedCount} item properties`}
81 </CollapsibleTrigger>
82 <CollapsibleContent>
83 <div className="mt-2 pl-3 border-l-2 border-fd-border">
84 <ParameterList
99 - parameters={(hasNested ? param.properties! : items!.properties) as Record<string, MetaToolParameter>}
100 - requiredFields={getRequiredFields(hasNested ? param : items)}
85 + parameters={nestedSchema.properties}
86 + requiredFields={nestedSchema.required}
87 showRequired={showRequired}
88 />
89 </div>
@@ -121,7 +107,7 @@ function ParameterList({ parameters, requiredFields = [], showRequired = true }:
107 }
108
109 function SchemaSection({ title, schema, showRequired = true }: { title: string; schema: MetaToolSchema; showRequired?: boolean }) {
124 - const properties = schema.properties || {};
110 + const properties = schema.properties;
111 const entries = Object.entries(properties);
112
113 if (entries.length === 0) return null;
@@ -131,7 +117,7 @@ function SchemaSection({ title, schema, showRequired = true }: { title: string;
117 <h2 className="text-base font-semibold text-fd-foreground mb-3">{title}</h2>
118 <div className="rounded-lg border border-fd-border bg-fd-card">
119 <div className="px-4">
134 - <ParameterList parameters={properties} requiredFields={schema.required || []} showRequired={showRequired} />
120 + <ParameterList parameters={properties} requiredFields={schema.required} showRequired={showRequired} />
121 </div>
122 </div>
123 </div>
docs/content/docs/extending-sessions/proxy-execute.mdx
+4
@@ -141,6 +141,10 @@ curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
141
142 The option also accepts `{ enable: true }` (`{"enable": True}` in Python). If you omit it at creation, the meta tool is off and `sandbox.enableProxyExecution` (`sandbox.enable_proxy_execution` in Python) controls the sandbox's `proxy_execute()` helper.
143
144 +The [`COMPOSIO_PROXY_EXECUTE`](/toolkits/meta-tools/proxy_execute) meta tool uses different arguments from `session.proxyExecute()`: pass `toolkit_slug` instead of `toolkit`, put each parameter's location in `type` instead of `in`, and `method` also accepts `HEAD`.
145 +
146 +Failures come back as a tool result with `successful: false` and an `error`. An upstream non-2xx response returns normally in `data`, with its HTTP `status` and body. Large responses can be offloaded to the [sandbox](/docs/sandbox/remote), as with other tool results.
147 +
148 Change the setting with `session.update({ proxyExecute: false })` or Python `session.update(proxy_execute=False)`. Disabling it also disables the sandbox helper. Pass `null` (`None` in Python) on update to remove the stored setting.
149
150 <Callout type="warn">
docs/content/toolkits/meta-tools/index.mdx
+1
@@ -19,6 +19,7 @@ A typical workflow runs in order: call `COMPOSIO_SEARCH_TOOLS` to discover tools
19 | [`COMPOSIO_GET_TOOL_SCHEMAS`](/toolkits/meta-tools/get_tool_schemas) | Returns the full input schema for tools you already know the slug for, so you can build schema-compliant arguments before executing |
20 | [`COMPOSIO_MANAGE_CONNECTIONS`](/toolkits/meta-tools/manage_connections) | Checks connection status for a toolkit and returns a branded authentication link when the user needs to connect, covering OAuth, API keys, and every other auth type |
21 | [`COMPOSIO_MULTI_EXECUTE_TOOL`](/toolkits/meta-tools/multi_execute_tool) | Executes up to 50 tools in parallel and returns structured outputs ready for immediate analysis |
22 +| [`COMPOSIO_PROXY_EXECUTE`](/toolkits/meta-tools/proxy_execute) | Sends a raw HTTP request to a connected app's own API, authenticated with your connected account, for endpoints no Composio tool covers |
23 | [`COMPOSIO_REMOTE_BASH_TOOL`](/toolkits/meta-tools/remote_bash_tool) | Runs bash commands in a remote sandbox for file operations, data processing, and system tasks |
24 | [`COMPOSIO_REMOTE_WORKBENCH`](/toolkits/meta-tools/remote_workbench) | Runs Python in a persistent remote sandbox to process large remote files and script bulk or repeated tool executions |
25 | [`COMPOSIO_SEARCH_TOOLS`](/toolkits/meta-tools/search_tools) | Discovers the right tools across 500+ apps for a task and returns them with an execution plan, connection status, and the `session_id` that ties the rest of the workflow together |
docs/content/toolkits/meta-tools/meta.json
+1
@@ -5,6 +5,7 @@
5 "get_tool_schemas",
6 "manage_connections",
7 "multi_execute_tool",
8 + "proxy_execute",
9 "remote_bash_tool",
10 "remote_workbench",
11 "search_tools"
docs/content/toolkits/meta-tools/proxy_execute.mdx new
+11
@@ -0,0 +1,11 @@
1 +---
2 +title: Proxy Execute
3 +description: "Send a raw HTTP request to a connected app's own API, authenticated with the user's connected account for that toolkit"
4 +keywords: [COMPOSIO_PROXY_EXECUTE, meta tool]
5 +---
6 +
7 +{/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */}
8 +
9 +import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';
10 +
11 +<MetaToolDetailServer slug="COMPOSIO_PROXY_EXECUTE" />
docs/lib/meta-tool-overrides.ts
+8
@@ -20,6 +20,14 @@ export interface MetaToolOverride {
20 }
21
22 export const META_TOOL_OVERRIDES: Record<string, MetaToolOverride> = {
23 + COMPOSIO_PROXY_EXECUTE: {
24 + summary:
25 + "Sends a raw HTTP request to a connected app's own API, authenticated with your connected account, for endpoints no Composio tool covers.",
26 + whenToUse:
27 + 'Use `COMPOSIO_PROXY_EXECUTE` when no tool from `COMPOSIO_SEARCH_TOOLS` covers the endpoint you need. The toolkit needs an active connection first; call `COMPOSIO_MANAGE_CONNECTIONS` if it has none.',
28 + usageNote:
29 + 'Enable it with `proxyExecute: true` in TypeScript or `proxy_execute=True` in Python. Compared with `session.proxyExecute()`, pass `toolkit_slug` instead of `toolkit`, use `type` instead of `in` for each parameter\'s location, and `method` also accepts `HEAD`. Composio attaches credentials. If the request cannot be sent, the tool returns `successful: false` with an `error`; an upstream non-2xx response returns normally in `data`, with its HTTP `status` and body. Large responses can be offloaded to the sandbox.',
30 + },
31 COMPOSIO_SEARCH_TOOLS: {
32 summary:
33 'Discovers the right tools across 500+ apps for a task and returns them with an execution plan, connection status, and the `session_id` that ties the rest of the workflow together.',
docs/lib/meta-tools-data.ts
+107 -55
@@ -1,75 +1,127 @@
1 import { readFile } from 'fs/promises';
2 import { join } from 'path';
3 +import { z } from 'zod';
4 import { getMetaToolOverride } from './meta-tool-overrides';
5
5 -export interface MetaToolParameter {
6 - type: string;
7 - description: string;
8 - required?: string[] | boolean;
9 - default?: unknown;
10 - enum?: string[];
11 - examples?: unknown[];
12 - items?: Record<string, unknown>;
13 - properties?: Record<string, MetaToolParameter>;
14 -}
6 +const jsonTypeSchema = z.enum([
7 + 'string',
8 + 'number',
9 + 'integer',
10 + 'boolean',
11 + 'object',
12 + 'array',
13 + 'null',
14 +]);
15
16 -export interface MetaToolSchema {
17 - type: string;
18 - properties: Record<string, MetaToolParameter>;
19 - required?: string[];
20 -}
21 -
22 -export interface MetaTool {
23 - slug: string;
24 - name: string;
25 - displayName: string;
26 - description: string;
27 - tags: string[];
28 - inputParameters: MetaToolSchema;
29 - responseSchema: MetaToolSchema;
30 - /** Hand-written Modal-voice copy, merged over the API data at read time. */
31 - summary?: string;
32 - whenToUse?: string;
33 - usageNote?: string;
34 -}
16 +// Normalize the schema fields used by the reference renderers. The generated
17 +// snapshot remains unchanged; `any` is a display label for an unrestricted type.
18 +const parameterSchema = z.object({
19 + type: z
20 + .union([jsonTypeSchema, z.array(jsonTypeSchema).min(1)])
21 + .optional()
22 + .transform(type => {
23 + if (type === undefined) return 'any';
24 + return Array.isArray(type) ? type.join(' | ') : type;
25 + }),
26 + description: z
27 + .string()
28 + .default('')
29 + .transform(description =>
30 + description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()
31 + ),
32 + required: z.array(z.string()).default([]),
33 + default: z.unknown().optional(),
34 + enum: z
35 + .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
36 + .default([])
37 + .transform(values => values.map(value => String(value))),
38 + get properties(): z.ZodDefault<z.ZodRecord<z.ZodString, typeof parameterSchema>> {
39 + return z.record(z.string(), parameterSchema).default({});
40 + },
41 + get items(): z.ZodOptional<typeof parameterSchema> {
42 + return parameterSchema.optional();
43 + },
44 +});
45
36 -const META_TOOLS_PATH = join(process.cwd(), 'public/data/meta-tools.json');
46 +type ParsedParameter = z.infer<typeof parameterSchema>;
47
38 -let cached: { list: MetaTool[]; bySlug: Map<string, MetaTool> } | null = null;
48 +export type MetaToolParameter = Omit<
49 + ParsedParameter,
50 + 'type' | 'default' | 'properties' | 'items'
51 +> & {
52 + typeLabel: string;
53 + defaultLabel: string | null;
54 + properties: Record<string, MetaToolParameter>;
55 + items?: MetaToolParameter;
56 +};
57
40 -function buildCache(tools: MetaTool[]) {
41 - cached = {
42 - list: tools,
43 - bySlug: new Map(tools.map(t => [t.slug, t])),
58 +/** Project schema nodes into one display model before they reach either renderer. */
59 +function toDisplayParameter({
60 + type,
61 + default: defaultValue,
62 + properties,
63 + items,
64 + ...parameter
65 +}: ParsedParameter): MetaToolParameter {
66 + const displayItems = items ? toDisplayParameter(items) : undefined;
67 + const typeLabel =
68 + type === 'array' ? `array<${displayItems ? displayItems.typeLabel : 'any'}>` : type;
69 + const defaultLabel =
70 + defaultValue === undefined || defaultValue === null || defaultValue === ''
71 + ? null
72 + : String(defaultValue);
73 + return {
74 + ...parameter,
75 + typeLabel,
76 + defaultLabel,
77 + properties: Object.fromEntries(
78 + Object.entries(properties).map(([name, value]) => [name, toDisplayParameter(value)])
79 + ),
80 + items: displayItems,
81 };
45 - return cached;
82 }
83
48 -/** Merge the hand-written override copy over the API-sourced tool. */
49 -function applyOverride(tool: MetaTool): MetaTool {
50 - const override = getMetaToolOverride(tool.slug);
51 - if (!override) return tool;
52 - return { ...tool, ...override };
53 -}
84 +export type MetaToolSchema = MetaToolParameter;
85
55 -function parse(data: string): MetaTool[] {
56 - const tools = JSON.parse(data) as MetaTool[];
86 +export const metaToolSchema = z
87 + .object({
88 + slug: z.string(),
89 + name: z.string(),
90 + displayName: z.string(),
91 + description: z.string(),
92 + tags: z.array(z.string()),
93 + inputParameters: parameterSchema.transform(toDisplayParameter),
94 + responseSchema: parameterSchema.transform(toDisplayParameter),
95 + })
96 + .transform(tool => {
97 + const override = getMetaToolOverride(tool.slug);
98 + return {
99 + ...tool,
100 + summary: override ? override.summary : tool.description,
101 + whenToUse: override ? override.whenToUse : '',
102 + usageNote: override?.usageNote ?? '',
103 + };
104 + });
105
58 - if (!Array.isArray(tools)) {
59 - throw new Error('meta-tools.json must contain an array');
60 - }
106 +export type MetaTool = z.infer<typeof metaToolSchema>;
107
62 - return tools.map(applyOverride);
108 +const metaToolsSchema = z.array(metaToolSchema);
109 +const META_TOOLS_PATH = join(process.cwd(), 'public/data/meta-tools.json');
110 +
111 +let cached: { list: MetaTool[]; bySlug: Map<string, MetaTool> } | null = null;
112 +
113 +async function getCache() {
114 + if (cached) return cached;
115 + const data = await readFile(META_TOOLS_PATH, 'utf-8');
116 + const list = metaToolsSchema.parse(JSON.parse(data));
117 + cached = { list, bySlug: new Map(list.map(tool => [tool.slug, tool])) };
118 + return cached;
119 }
120
121 export async function getAllMetaTools(): Promise<MetaTool[]> {
66 - if (cached) return cached.list;
67 - const data = await readFile(META_TOOLS_PATH, 'utf-8');
68 - return buildCache(parse(data)).list;
122 + return (await getCache()).list;
123 }
124
125 export async function getMetaToolBySlug(slug: string): Promise<MetaTool | null> {
72 - if (cached) return cached.bySlug.get(slug) ?? null;
73 - const data = await readFile(META_TOOLS_PATH, 'utf-8');
74 - return buildCache(parse(data)).bySlug.get(slug) ?? null;
75 -}
\ No newline at end of file
126 + return (await getCache()).bySlug.get(slug) ?? null;
127 +}
docs/public/data/meta-tools.json
+116
@@ -673,6 +673,122 @@
673 "type": "object"
674 }
675 },
676 + {
677 + "slug": "COMPOSIO_PROXY_EXECUTE",
678 + "name": "proxy_execute",
679 + "displayName": "Proxy Execute",
680 + "description": "\nSend a raw HTTP request to a connected app's own API, authenticated with the user's connected account for that toolkit. Use it only when no existing tool covers the endpoint you need; prefer a dedicated tool when one exists.\n\nThe account is the session's active connection for toolkit_slug; if there is none, connect the toolkit first. The endpoint can be a path relative to the app's API base URL (e.g. /user/repos) or an absolute URL on the app's own API domain. Credentials are attached for you: never put tokens or API keys in parameters or body.\n\nThe result contains the app's HTTP status, response headers and response data. A non-2xx status is the app's own answer, not a tool failure.\nIf the response is large, the full response is saved to a file in the workbench and this tool returns a preview with the file path; read the file from the workbench to process it.\n ",
681 + "tags": [
682 + "openWorldHint"
683 + ],
684 + "toolkit": null,
685 + "inputParameters": {
686 + "type": "object",
687 + "title": "ProxyExecuteRequest",
688 + "properties": {
689 + "toolkit_slug": {
690 + "type": "string",
691 + "description": "Slug of the toolkit whose connected account authenticates the request, e.g. github."
692 + },
693 + "endpoint": {
694 + "type": "string",
695 + "description": "API path relative to the app's API base URL (e.g. /user/repos), or an absolute URL on the app's own API domain."
696 + },
697 + "method": {
698 + "type": "string",
699 + "enum": [
700 + "GET",
701 + "POST",
702 + "PUT",
703 + "DELETE",
704 + "PATCH",
705 + "HEAD"
706 + ],
707 + "description": "HTTP method."
708 + },
709 + "body": {
710 + "description": "JSON request body, for POST, PUT and PATCH requests."
711 + },
712 + "parameters": {
713 + "type": "array",
714 + "description": "Extra HTTP headers or query parameters. Do not include credentials.",
715 + "items": {
716 + "type": "object",
717 + "properties": {
718 + "name": {
719 + "type": "string",
720 + "description": "Header or query parameter name."
721 + },
722 + "value": {
723 + "type": "string",
724 + "description": "Header or query parameter value."
725 + },
726 + "type": {
727 + "type": "string",
728 + "enum": [
729 + "header",
730 + "query"
731 + ],
732 + "description": "Where to send the parameter."
733 + }
734 + },
735 + "required": [
736 + "name",
737 + "value",
738 + "type"
739 + ],
740 + "additionalProperties": false
741 + }
742 + }
743 + },
744 + "required": [
745 + "toolkit_slug",
746 + "endpoint",
747 + "method"
748 + ],
749 + "additionalProperties": false
750 + },
751 + "responseSchema": {
752 + "type": "object",
753 + "title": "ProxyExecuteResponseWrapper",
754 + "properties": {
755 + "data": {
756 + "type": "object",
757 + "properties": {
758 + "status": {
759 + "type": "integer",
760 + "description": "The app's HTTP status code."
761 + },
762 + "headers": {
763 + "type": "object",
764 + "description": "The app's response headers."
765 + },
766 + "data": {
767 + "description": "The app's response body."
768 + },
769 + "binary_data": {
770 + "type": "object",
771 + "description": "Present when the app returned a file: a download URL instead of inline content."
772 + }
773 + }
774 + },
775 + "error": {
776 + "type": "string",
777 + "nullable": true,
778 + "default": null,
779 + "description": "Error if the request could not be sent."
780 + },
781 + "successful": {
782 + "type": "boolean",
783 + "description": "Whether the request was sent and a response received."
784 + }
785 + },
786 + "required": [
787 + "data",
788 + "successful"
789 + ]
790 + }
791 + },
792 {
793 "slug": "COMPOSIO_REMOTE_BASH_TOOL",
794 "name": "remote_bash_tool",
docs/scripts/generate-meta-tools.ts
+2
@@ -94,6 +94,8 @@ async function createSession(): Promise<string> {
94 recipesEnabled: true,
95 enableWaitForConnections: true,
96 },
97 + // Opt-in meta tools are listed only in sessions that enable them.
98 + proxy_execute: { enable: true },
99 }),
100 });
101
docs/tests/static/meta-tools-data.test.ts new
+88
@@ -0,0 +1,88 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { metaToolSchema } from '../../lib/meta-tools-data';
3 +
4 +const tool = {
5 + slug: 'EXAMPLE_TOOL',
6 + name: 'example_tool',
7 + displayName: 'Example Tool',
8 + description: 'Example API description.',
9 + tags: [],
10 + inputParameters: {},
11 + responseSchema: {},
12 +};
13 +
14 +describe('meta-tool display model', () => {
15 + test('normalizes unrestricted JSON and absent schema fields before rendering', () => {
16 + const parsed = metaToolSchema.parse({
17 + ...tool,
18 + inputParameters: { properties: { body: { description: '**Any**\nJSON' } } },
19 + });
20 + expect(parsed.summary).toBe(tool.description);
21 + expect(parsed.inputParameters.properties.body).toEqual({
22 + typeLabel: 'any',
23 + description: 'Any JSON',
24 + defaultLabel: null,
25 + properties: {},
26 + required: [],
27 + enum: [],
28 + });
29 + expect(parsed.responseSchema.properties).toEqual({});
30 + expect(parsed.responseSchema.required).toEqual([]);
31 + });
32 +
33 + test('normalizes nested arrays and retains required item properties', () => {
34 + const parsed = metaToolSchema.parse({
35 + ...tool,
36 + inputParameters: {
37 + properties: {
38 + rows: {
39 + type: 'array',
40 + items: {
41 + type: 'array',
42 + items: {
43 + type: 'object',
44 + required: ['id'],
45 + properties: { id: { type: 'integer' } },
46 + },
47 + },
48 + },
49 + untyped_items: { type: 'array' },
50 + nullable: { type: ['string', 'null'] },
51 + },
52 + },
53 + });
54 + const { rows, untyped_items, nullable } = parsed.inputParameters.properties;
55 + expect(rows.typeLabel).toBe('array<array<object>>');
56 + expect(rows.items?.items?.required).toEqual(['id']);
57 + expect(rows.items?.items?.properties.id.typeLabel).toBe('integer');
58 + expect(untyped_items.typeLabel).toBe('array<any>');
59 + expect(nullable.typeLabel).toBe('string | null');
60 + });
61 +
62 + test('preserves falsy defaults and scalar enum values', () => {
63 + const parsed = metaToolSchema.parse({
64 + ...tool,
65 + inputParameters: {
66 + properties: {
67 + count: { type: 'integer', default: 0, enum: [0, 1] },
68 + enabled: { type: 'boolean', default: false, enum: [false, true] },
69 + },
70 + },
71 + });
72 + expect(parsed.inputParameters.properties.count.defaultLabel).toBe('0');
73 + expect(parsed.inputParameters.properties.count.enum).toEqual(['0', '1']);
74 + expect(parsed.inputParameters.properties.enabled.defaultLabel).toBe('false');
75 + expect(parsed.inputParameters.properties.enabled.enum).toEqual(['false', 'true']);
76 + });
77 +
78 + test.each([{ type: 'invalid' }, { type: 42 }, { required: true }, { items: 'invalid' }])(
79 + 'rejects malformed schema fields instead of silently displaying any (%j)',
80 + parameter => {
81 + const result = metaToolSchema.safeParse({
82 + ...tool,
83 + inputParameters: { properties: { body: parameter } },
84 + });
85 + expect(result.success).toBe(false);
86 + }
87 + );
88 +});
docs/tests/static/proxy-execute-meta-tool.test.tsx new
+78
@@ -0,0 +1,78 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
3 +import { tmpdir } from 'node:os';
4 +import { join, resolve } from 'node:path';
5 +import { renderToStaticMarkup } from 'react-dom/server';
6 +
7 +import { GET } from '../../app/llms.mdx/[[...slug]]/route';
8 +import { MetaToolDetail } from '../../components/meta-tools/meta-tool-detail';
9 +import { getMetaToolBySlug } from '../../lib/meta-tools-data';
10 +
11 +describe('proxy execute meta-tool reference', () => {
12 + test('generation discovers opt-in tools and preserves unrestricted JSON', async () => {
13 + const directory = await mkdtemp(join(tmpdir(), 'composio-meta-tools-'));
14 + const transport = join(directory, 'transport.ts');
15 + await writeFile(transport, `
16 + let enabled = false;
17 + globalThis.fetch = async (_url, options) => {
18 + if (options?.method === 'POST') {
19 + enabled = JSON.parse(options.body).proxy_execute?.enable === true;
20 + return Response.json({ session_id: 'test-session', tool_router_tools: [] });
21 + }
22 + return Response.json(enabled ? [{
23 + slug: 'COMPOSIO_PROXY_EXECUTE', name: 'proxy_execute',
24 + input_parameters: { type: 'object', properties: { body: { description: 'Any JSON' } } },
25 + output_parameters: { type: 'object', properties: {} },
26 + }] : []);
27 + };
28 + `);
29 +
30 + try {
31 + const child = Bun.spawn([
32 + process.execPath, '--preload', transport, resolve('scripts/generate-meta-tools.ts'),
33 + ], {
34 + cwd: directory,
35 + env: { ...process.env, COMPOSIO_API_KEY: 'test-key', COMPOSIO_API_BASE: '' },
36 + stdout: 'pipe',
37 + stderr: 'pipe',
38 + });
39 + const [exitCode, stdout, stderr] = await Promise.all([
40 + child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
41 + ]);
42 + expect(exitCode, `${stdout}\n${stderr}`).toBe(0);
43 + expect(await readFile(join(directory, 'content/toolkits/meta-tools/index.mdx'), 'utf8'))
44 + .toContain('/toolkits/meta-tools/proxy_execute');
45 + expect(await readFile(join(directory, 'content/toolkits/meta-tools/proxy_execute.mdx'), 'utf8'))
46 + .toContain('<MetaToolDetailServer slug="COMPOSIO_PROXY_EXECUTE" />');
47 + const tools = await Bun.file(join(directory, 'public/data/meta-tools.json')).json();
48 + expect(tools[0].inputParameters.properties.body).toEqual({ description: 'Any JSON' });
49 + } finally {
50 + await rm(directory, { recursive: true, force: true });
51 + }
52 + });
53 +
54 + test('HTML labels unrestricted request bodies as any', async () => {
55 + const tool = await getMetaToolBySlug('COMPOSIO_PROXY_EXECUTE');
56 + expect(tool).not.toBeNull();
57 + const html = renderToStaticMarkup(<MetaToolDetail tool={tool!} />);
58 + expect(html).toMatch(/>body<\/code><span[^>]*>any<\/span>/);
59 + expect(html).toMatch(/>parameters<\/code><span[^>]*>array&lt;object&gt;<\/span>/);
60 + expect(html).toContain('HEAD');
61 + });
62 +
63 + test('Markdown includes usage semantics and unrestricted nested response bodies', async () => {
64 + const response = await GET(
65 + new Request('https://docs.composio.dev/toolkits/meta-tools/proxy_execute.md'),
66 + { params: Promise.resolve({ slug: ['toolkits', 'meta-tools', 'proxy_execute'] }) },
67 + );
68 + expect(response.status).toBe(200);
69 + const markdown = await response.text();
70 + expect(markdown).toContain('`body` (any)');
71 + expect(markdown).toContain('`data` (any)');
72 + expect(markdown).toContain('`parameters` (array<object>)');
73 + expect(markdown).not.toContain('(undefined)');
74 + expect(markdown).toContain('`successful: false`');
75 + expect(markdown).toContain('non-2xx');
76 + expect(markdown).toContain('`type` instead of `in`');
77 + });
78 +});