Simplify Composio tool integration

Author: jahooma

common/src/tools/constants.ts

@@ -1,3 +1,5 @@
+import { COMPOSIO_META_TOOL_NAMES } from '../constants/composio'
+
 import type { ToolResultOutput } from '../types/messages/content-part'
 import type { Tool } from 'ai'
 
@@ -56,6 +58,7 @@ export const toolNames = [
   'web_search',
   'write_file',
   'write_todos',
+  ...COMPOSIO_META_TOOL_NAMES,
 ] as const
 
 export const publishedTools = [

common/src/tools/list.ts

@@ -7,6 +7,7 @@ import { applyPatchParams } from './params/tool/apply-patch'
 import { askUserParams } from './params/tool/ask-user'
 import { browserLogsParams } from './params/tool/browser-logs'
 import { codeSearchParams } from './params/tool/code-search'
+import { composioMetaToolParams } from './params/tool/composio'
 import { createPlanParams } from './params/tool/create-plan'
 import { endTurnParams } from './params/tool/end-turn'
 import { findFilesParams } from './params/tool/find-files'
@@ -77,6 +78,7 @@ export const toolParams = {
   web_search: webSearchParams,
   write_file: writeFileParams,
   write_todos: writeTodosParams,
+  ...composioMetaToolParams,
 } satisfies {
   [K in ToolName]: $ToolParams<K>
 }
@@ -151,6 +153,22 @@ export const clientToolCallSchema = z.discriminatedUnion('toolName', [
     toolName: z.literal('write_file'),
     input: FileChangeSchema,
   }),
+  z.object({
+    toolName: z.literal('COMPOSIO_MANAGE_CONNECTIONS'),
+    input: toolParams.COMPOSIO_MANAGE_CONNECTIONS.inputSchema,
+  }),
+  z.object({
+    toolName: z.literal('COMPOSIO_MULTI_EXECUTE_TOOL'),
+    input: toolParams.COMPOSIO_MULTI_EXECUTE_TOOL.inputSchema,
+  }),
+  z.object({
+    toolName: z.literal('COMPOSIO_SEARCH_TOOLS'),
+    input: toolParams.COMPOSIO_SEARCH_TOOLS.inputSchema,
+  }),
+  z.object({
+    toolName: z.literal('COMPOSIO_GET_TOOL_SCHEMAS'),
+    input: toolParams.COMPOSIO_GET_TOOL_SCHEMAS.inputSchema,
+  }),
 ])
 export const clientToolNames = clientToolCallSchema.def.options.map(
   (opt) => opt.shape.toolName.value,
@@ -163,4 +181,4 @@ export type ClientToolCall<T extends ClientToolName = ClientToolName> = Extract<
 > &
   Pick<ToolCallPart, 'toolCallId' | 'toolName' | 'input' | 'providerOptions'>
 
-export type PublishedClientToolName = ClientToolName & PublishedToolName
+export type PublishedClientToolName = Extract<ClientToolName, PublishedToolName>

common/src/tools/params/tool/composio.ts

@@ -0,0 +1,131 @@
+import { COMPOSIO_META_TOOL_NAMES } from '../../../constants/composio'
+import z from 'zod/v4'
+
+import { jsonToolResultSchema } from '../utils'
+
+import type { $ToolParams } from '../../constants'
+
+const sessionIdParam = z
+  .string()
+  .optional()
+  .describe('Session ID returned by COMPOSIO_SEARCH_TOOLS, when available.')
+
+const composioMetaToolInputSchemas = {
+  COMPOSIO_SEARCH_TOOLS: z
+    .object({
+      queries: z
+        .array(z.unknown())
+        .min(1)
+        .describe(
+          'Structured English search queries. Split independent app/API actions into separate queries.',
+        ),
+      session: z
+        .object({
+          generate_id: z.boolean().optional(),
+          id: z.string().optional(),
+        })
+        .catchall(z.unknown())
+        .describe(
+          'Use { generate_id: true } for a new workflow, or { id } to continue one.',
+        ),
+      model: z.string().optional().describe('Client LLM model name.'),
+    })
+    .catchall(z.unknown()),
+  COMPOSIO_GET_TOOL_SCHEMAS: z
+    .object({
+      tool_slugs: z
+        .array(z.string())
+        .min(1)
+        .describe('Composio tool slugs to retrieve schemas for.'),
+      include: z
+        .array(z.string())
+        .optional()
+        .describe('Schema fields to include, e.g. input_schema/output_schema.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+  COMPOSIO_MANAGE_CONNECTIONS: z
+    .object({
+      toolkits: z
+        .array(z.string())
+        .min(1)
+        .describe('Toolkit slugs to check or connect, such as gmail/github.'),
+      reinitiate_all: z
+        .boolean()
+        .optional()
+        .describe('Force reconnection even if active credentials exist.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+  COMPOSIO_MULTI_EXECUTE_TOOL: z
+    .object({
+      tools: z
+        .array(z.record(z.string(), z.unknown()))
+        .min(1)
+        .describe('Logically independent Composio tools to execute.'),
+      thought: z
+        .string()
+        .optional()
+        .describe('One concise sentence explaining the execution intent.'),
+      sync_response_to_workbench: z
+        .boolean()
+        .default(false)
+        .describe('Always use false. Codebuff disables Composio workbench.'),
+      session_id: sessionIdParam,
+    })
+    .catchall(z.unknown()),
+}
+
+const composioMetaToolDescriptions = {
+  COMPOSIO_SEARCH_TOOLS:
+    'Discover relevant Composio tools across external apps. Use this first for requests involving services like Gmail, GitHub, Slack, Linear, Notion, Google Calendar, or Google Sheets.',
+  COMPOSIO_GET_TOOL_SCHEMAS:
+    'Retrieve complete input schemas for specific Composio tool slugs returned by COMPOSIO_SEARCH_TOOLS.',
+  COMPOSIO_MANAGE_CONNECTIONS:
+    'Check or initiate user authentication for external app toolkits. Use when search/execution indicates a toolkit is not connected.',
+  COMPOSIO_MULTI_EXECUTE_TOOL:
+    'Execute one or more discovered Composio app tools in the current workflow session. Do not use workbench offloading.',
+}
+
+const composioOutputSchema = jsonToolResultSchema(
+  z.union([
+    z.json(),
+    z.object({
+      errorMessage: z.string(),
+      status: z.number().optional(),
+    }),
+  ]),
+)
+
+export const composioMetaToolParams = {
+  COMPOSIO_MANAGE_CONNECTIONS: {
+    toolName: 'COMPOSIO_MANAGE_CONNECTIONS',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.COMPOSIO_MANAGE_CONNECTIONS,
+    inputSchema: composioMetaToolInputSchemas.COMPOSIO_MANAGE_CONNECTIONS,
+    outputSchema: composioOutputSchema,
+  },
+  COMPOSIO_MULTI_EXECUTE_TOOL: {
+    toolName: 'COMPOSIO_MULTI_EXECUTE_TOOL',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.COMPOSIO_MULTI_EXECUTE_TOOL,
+    inputSchema: composioMetaToolInputSchemas.COMPOSIO_MULTI_EXECUTE_TOOL,
+    outputSchema: composioOutputSchema,
+  },
+  COMPOSIO_SEARCH_TOOLS: {
+    toolName: 'COMPOSIO_SEARCH_TOOLS',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.COMPOSIO_SEARCH_TOOLS,
+    inputSchema: composioMetaToolInputSchemas.COMPOSIO_SEARCH_TOOLS,
+    outputSchema: composioOutputSchema,
+  },
+  COMPOSIO_GET_TOOL_SCHEMAS: {
+    toolName: 'COMPOSIO_GET_TOOL_SCHEMAS',
+    endsAgentStep: true,
+    description: composioMetaToolDescriptions.COMPOSIO_GET_TOOL_SCHEMAS,
+    inputSchema: composioMetaToolInputSchemas.COMPOSIO_GET_TOOL_SCHEMAS,
+    outputSchema: composioOutputSchema,
+  },
+} satisfies {
+  [K in (typeof COMPOSIO_META_TOOL_NAMES)[number]]: $ToolParams<K>
+}

packages/agent-runtime/src/tools/handlers/list.ts

@@ -4,6 +4,12 @@ import { handleApplyPatch } from './tool/apply-patch'
 import { handleAskUser } from './tool/ask-user'
 import { handleBrowserLogs } from './tool/browser-logs'
 import { handleCodeSearch } from './tool/code-search'
+import {
+  handleComposioGetToolSchemas,
+  handleComposioManageConnections,
+  handleComposioMultiExecute,
+  handleComposioSearchTools,
+} from './tool/composio'
 import { handleCreatePlan } from './tool/create-plan'
 import { handleEndTurn } from './tool/end-turn'
 import { handleFindFiles } from './tool/find-files'
@@ -53,6 +59,10 @@ export const codebuffToolHandlers = {
   ask_user: handleAskUser,
   browser_logs: handleBrowserLogs,
   code_search: handleCodeSearch,
+  COMPOSIO_MANAGE_CONNECTIONS: handleComposioManageConnections,
+  COMPOSIO_MULTI_EXECUTE_TOOL: handleComposioMultiExecute,
+  COMPOSIO_SEARCH_TOOLS: handleComposioSearchTools,
+  COMPOSIO_GET_TOOL_SCHEMAS: handleComposioGetToolSchemas,
   create_plan: handleCreatePlan,
   end_turn: handleEndTurn,
   find_files: handleFindFiles,

packages/agent-runtime/src/tools/handlers/tool/composio.ts

@@ -0,0 +1,35 @@
+import type { ComposioMetaToolName } from '@codebuff/common/constants/composio'
+import type { CodebuffToolOutput } from '@codebuff/common/tools/list'
+import type { CodebuffToolHandlerFunction } from '../handler-function-type'
+
+function makeComposioHandler<T extends ComposioMetaToolName>() {
+  return (async ({ toolCall, requestClientToolCall }) => {
+    if (!requestClientToolCall) {
+      return {
+        output: [
+          {
+            type: 'json',
+            value: {
+              errorMessage: 'Composio tools are not available in this runtime.',
+            },
+          },
+        ],
+      }
+    }
+
+    return {
+      output: (await (requestClientToolCall as any)(
+        toolCall,
+      )) as CodebuffToolOutput<T>,
+    }
+  }) satisfies CodebuffToolHandlerFunction<T>
+}
+
+export const handleComposioManageConnections =
+  makeComposioHandler<'COMPOSIO_MANAGE_CONNECTIONS'>()
+export const handleComposioMultiExecute =
+  makeComposioHandler<'COMPOSIO_MULTI_EXECUTE_TOOL'>()
+export const handleComposioSearchTools =
+  makeComposioHandler<'COMPOSIO_SEARCH_TOOLS'>()
+export const handleComposioGetToolSchemas =
+  makeComposioHandler<'COMPOSIO_GET_TOOL_SCHEMAS'>()

sdk/src/__tests__/composio.test.ts

@@ -1,27 +1,28 @@
 import { afterEach, describe, expect, mock, test } from 'bun:test'
 
 import { COMPOSIO_META_TOOL_NAMES } from '@codebuff/common/constants/composio'
+import { clientToolNames, toolParams } from '@codebuff/common/tools/list'
 
-import { getComposioMetaToolDefinitions } from '../composio'
+import {
+  executeComposioToolViaServer,
+  normalizeComposioInput,
+} from '../composio'
 
-describe('getComposioMetaToolDefinitions', () => {
+describe('Composio SDK tools', () => {
   const originalFetch = globalThis.fetch
 
   afterEach(() => {
     globalThis.fetch = originalFetch
   })
 
-  test('returns static Composio meta tool definitions without discovery fetch', () => {
+  test('registers Composio meta tools as static client tools without discovery fetch', () => {
     const fetchMock = mock(async () => new Response('{}'))
     globalThis.fetch = fetchMock as unknown as typeof fetch
 
-    const tools = getComposioMetaToolDefinitions({
-      apiKey: 'codebuff-api-key',
-    })
-
-    expect(tools.map((tool) => tool.toolName)).toEqual([
-      ...COMPOSIO_META_TOOL_NAMES,
-    ])
+    for (const toolName of COMPOSIO_META_TOOL_NAMES) {
+      expect(clientToolNames).toContain(toolName)
+      expect(toolParams[toolName].inputSchema).toBeDefined()
+    }
     expect(fetchMock).not.toHaveBeenCalled()
   })
 
@@ -50,16 +51,20 @@ describe('getComposioMetaToolDefinitions', () => {
     )
     globalThis.fetch = fetchMock as unknown as typeof fetch
 
-    const searchTool = getComposioMetaToolDefinitions({
+    const output = await executeComposioToolViaServer({
       apiKey: 'codebuff-api-key',
-    }).find((tool) => tool.toolName === 'COMPOSIO_SEARCH_TOOLS')
-
-    const output = await searchTool?.execute({
-      queries: ['find gmail tools'],
-      session: { generate_id: true },
+      toolName: 'COMPOSIO_SEARCH_TOOLS',
+      input: {
+        queries: ['find gmail tools'],
+        session: { generate_id: true },
+      },
     })
 
     expect(output).toEqual([{ type: 'json', value: { ok: true } }])
     expect(fetchMock).toHaveBeenCalledTimes(1)
   })
+
+  test('normalizes non-object Composio inputs for server execution', () => {
+    expect(normalizeComposioInput('gmail')).toEqual({ value: 'gmail' })
+  })
 })