zilmate 1.7.8 → 1.8.1

package/.agents/skills/composio/rules/app-custom-tools.md

@@ -0,0 +1,220 @@
+---
+title: Creating Custom Tools
+impact: MEDIUM
+description: Build standalone and toolkit-based custom tools with proper authentication and validation
+tags: [custom-tools, extensibility, authentication, zod, development]
+---
+
+# Creating Custom Tools
+
+Create your own tools that integrate with Composio:
+- **Standalone tools** - No external authentication required
+- **Toolkit-based tools** - Use toolkit credentials for API requests
+
+> **⚠️ IMPORTANT:** When creating toolkit-based tools, do NOT make up or guess toolkit slugs. Always verify:
+> - Use `composio manage toolkits list` to discover and `composio manage toolkits info "..."` to view toolkit details and auth schemes (CLI)
+> - Use `composio.toolkits.get()` to discover toolkits programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## Standalone Tools
+
+For tools that don't need external authentication:
+
+```typescript
+import { z } from 'zod';
+
+const tool = await composio.tools.createCustomTool({
+  slug: 'CALCULATE_SQUARE',
+  name: 'Calculate Square',
+  description: 'Calculates the square of a number',
+  inputParams: z.object({
+    number: z.number().describe('The number to calculate the square of'),
+  }),
+  execute: async (input) => {
+    return {
+      data: { result: input.number * input.number },
+      error: null,
+      successful: true,
+    };
+  },
+});
+```
+
+**Use for:** Math, string operations, data transformations, internal logic.
+
+## Toolkit-Based Tools
+
+For tools that call authenticated APIs.
+
+### Using executeToolRequest (Recommended)
+
+Automatically handles authentication and baseURL:
+
+```typescript
+const tool = await composio.tools.createCustomTool({
+  slug: 'GITHUB_STAR_REPOSITORY',
+  name: 'Star GitHub Repository',
+  toolkitSlug: 'github',
+  description: 'Star a repository under composiohq',
+  inputParams: z.object({
+    repository: z.string().describe('Repository name'),
+    page: z.number().optional().describe('Page number'),
+  }),
+  execute: async (input, connectionConfig, executeToolRequest) => {
+    return await executeToolRequest({
+      endpoint: `/user/starred/composiohq/${input.repository}`,
+      method: 'PUT',
+      parameters: [
+        {
+          name: 'page',
+          value: input.page?.toString() || '1',
+          in: 'query', // Adds ?page=1
+        },
+      ],
+    });
+  },
+});
+```
+
+### Using connectionConfig (Direct API Calls)
+
+For custom HTTP requests:
+
+```typescript
+const tool = await composio.tools.createCustomTool({
+  slug: 'GITHUB_DIRECT_API',
+  name: 'Direct GitHub API',
+  toolkitSlug: 'github',
+  inputParams: z.object({
+    repo: z.string().describe('Repository name'),
+  }),
+  execute: async (input, connectionConfig) => {
+    const response = await fetch(`https://api.github.com/repos/${input.repo}`, {
+      headers: {
+        Authorization: `Bearer ${connectionConfig.val?.access_token}`,
+      },
+    });
+
+    const data = await response.json();
+
+    return {
+      data: data,
+      error: response.ok ? null : 'API request failed',
+      successful: response.ok,
+    };
+  },
+});
+```
+
+## Input Validation with Zod
+
+Define and validate parameters using Zod:
+
+```typescript
+inputParams: z.object({
+  // Required string
+  name: z.string().describe('User name'),
+
+  // Optional with default
+  count: z.number().optional().default(10).describe('Number of items'),
+
+  // With validation
+  email: z.string().email().describe('Email address'),
+
+  // Enum
+  status: z.enum(['active', 'inactive']).describe('Status'),
+
+  // Array
+  tags: z.array(z.string()).describe('Tags'),
+
+  // Nested object
+  metadata: z.object({
+    key: z.string(),
+    value: z.string(),
+  }).optional().describe('Metadata'),
+})
+```
+
+**Always use `.describe()`** - helps AI understand parameter purpose.
+
+## Headers and Query Parameters
+
+Add headers and query params via `parameters` array:
+
+```typescript
+execute: async (input, connectionConfig, executeToolRequest) => {
+  return await executeToolRequest({
+    endpoint: '/search/repositories',
+    method: 'GET',
+    parameters: [
+      // Query parameters
+      {
+        name: 'q',
+        value: input.query,
+        in: 'query', // ?q=value
+      },
+      // Headers
+      {
+        name: 'Accept',
+        value: 'application/vnd.github.v3+json',
+        in: 'header',
+      },
+    ],
+  });
+}
+```
+
+## Executing Custom Tools
+
+```typescript
+// Standalone tool
+await composio.tools.execute('CALCULATE_SQUARE', {
+  userId: 'default',
+  arguments: { number: 5 },
+});
+
+// Toolkit-based tool (uses userId to find account)
+await composio.tools.execute('GITHUB_STAR_REPOSITORY', {
+  userId: 'user_123',
+  arguments: { repository: 'composio' },
+});
+
+// With explicit connected account
+await composio.tools.execute('GITHUB_STAR_REPOSITORY', {
+  userId: 'user_123',
+  connectedAccountId: 'conn_abc123',
+  arguments: { repository: 'composio' },
+});
+```
+
+## Error Handling
+
+Always return structured responses:
+
+```typescript
+execute: async (input) => {
+  try {
+    const result = performOperation(input);
+    return {
+      data: result,
+      error: null,
+      successful: true,
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: error.message,
+      successful: false,
+    };
+  }
+}
+```
+
+## Key Points
+
+- **Naming:** Use `TOOLKIT_ACTION_DESCRIPTION` format for slugs
+- **Prefer executeToolRequest:** Handles auth and baseURL automatically
+- **Describe parameters:** AI agents need clear descriptions
+- **Not persisted:** Custom tools exist in memory only, recreate on restart
+- **Single toolkit scope:** executeToolRequest only works within same toolkit

package/.agents/skills/composio/rules/app-execute-tools.md

@@ -0,0 +1,202 @@
+---
+title: Direct Tool Execution for Applications
+impact: HIGH
+description: Core patterns for manually executing Composio tools in applications without agent frameworks
+tags: [tools, execute, execution, apps, manual]
+---
+
+# Direct Tool Execution for Applications
+
+When building applications without agent frameworks, use `composio.tools.execute()` to manually execute tools.
+
+## Basic Execution
+
+```typescript
+// Execute with a specific version (REQUIRED)
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00', // Specific version required
+});
+```
+
+## Discovering Available Tools
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess tool or toolkit names/versions. Always verify slugs before using them:
+> - Use `composio manage tools list --toolkits "..."` to discover and `composio manage tools info "..."` to view tool schema (CLI)
+> - Use `composio.tools.get()` to discover available tools programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+```typescript
+// Get all available tools in a toolkit
+const githubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100 // Set appropriate limit
+});
+
+console.log('Available GitHub tools:', githubTools.map(t => t.name));
+```
+
+```python
+# Get all available tools in a toolkit
+github_tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100  # Set appropriate limit
+)
+
+print("Available GitHub tools:", [t.name for t in github_tools])
+```
+
+## Version Management
+
+**CRITICAL**: When manually executing tools (especially in workflows), a **specific version is required**. Using `'latest'` will throw an error.
+
+**How to discover available versions:**
+Use `composio.toolkits.get()` to see available versions for a toolkit:
+
+```typescript
+// Get toolkit information to see available versions
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Available versions:', githubToolkit.versions);
+// e.g., ["12082025_00", "10082025_01", "08082025_00"]
+console.log('Current version:', githubToolkit.version); // e.g., "12082025_00"
+
+// ✅ DO: Pin to a specific version string for stability
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00', // Pinned version string
+});
+```
+
+```python
+# Get toolkit information to see available versions
+github_toolkit = composio.toolkits.get("github")
+print(f"Available versions: {github_toolkit.versions}")
+# e.g., ["12082025_00", "10082025_01", "08082025_00"]
+print(f"Current version: {github_toolkit.version}")  # e.g., "12082025_00"
+
+# ✅ DO: Pin to a specific version string for stability
+result = composio.tools.execute(
+    tool="GITHUB_GET_ISSUES",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # Pinned version string
+)
+```
+
+**Why version pinning is required:**
+- Tool argument schemas can change between versions
+- Using `'latest'` in workflows can cause runtime errors when tools are updated
+- Pinned versions ensure workflow stability and predictability
+- Version validation prevents production issues from schema mismatches
+- **Don't use `githubToolkit.version` dynamically** - this always returns the latest version, defeating the purpose of pinning
+
+See [Tool Version Management](app-tool-versions.md) for detailed version strategies.
+
+## Parameters
+
+### ExecuteParams Object
+
+```typescript
+{
+  userId: string,           // User ID for connected account lookup
+  arguments: object,        // Tool-specific input parameters
+  version?: string,         // Toolkit version (required for manual execution)
+  dangerouslySkipVersionCheck?: boolean  // Bypass version validation (NOT recommended)
+}
+```
+
+### Execution Modifiers
+
+Transform requests and responses with modifiers:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_ISSUES',
+  {
+    userId: 'default',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00',
+  },
+  {
+    beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
+      // Modify params before execution
+      console.log('Executing:', toolSlug);
+      return {
+        ...params,
+        arguments: {
+          ...params.arguments,
+          per_page: 100 // Add default parameter
+        }
+      };
+    },
+    afterExecute: ({ toolSlug, toolkitSlug, result }) => {
+      // Transform result after execution
+      console.log('Completed:', toolSlug);
+      return {
+        ...result,
+        timestamp: new Date().toISOString()
+      };
+    },
+  }
+);
+```
+
+## Response Format
+
+```typescript
+interface ToolExecuteResponse {
+  data: any;           // Tool-specific response data
+  error: string | null;  // Error message if execution failed
+  successful: boolean;   // Whether execution succeeded
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+    userId: 'user_123',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00',
+  });
+
+  if (!result.successful) {
+    console.error('Tool execution failed:', result.error);
+    // Handle error case
+    return;
+  }
+
+  // Process successful result
+  console.log('Issues:', result.data);
+} catch (error) {
+  if (error.name === 'ComposioToolNotFoundError') {
+    console.error('Tool not found');
+  } else if (error.name === 'ComposioToolExecutionError') {
+    console.error('Execution error:', error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Common Error Types
+
+- `ComposioCustomToolsNotInitializedError`: Custom tools instance not initialized
+- `ComposioToolNotFoundError`: Tool with the given slug not found
+- `ComposioToolExecutionError`: Error during tool execution
+- Version validation errors: Thrown when version is missing or `'latest'` is used
+
+## Best Practices
+
+1. **Always specify versions**: Use explicit versions or configure at initialization
+2. **Handle errors gracefully**: Check `successful` flag and handle `error` field
+3. **Validate arguments**: Ensure all required parameters are provided
+4. **Use modifiers sparingly**: Only add modifiers when necessary for transformation
+5. **Log execution details**: Track which tools are executed for debugging
+6. **Test with real data**: Validate execution with actual connected accounts
+7. **Handle authentication errors**: User may not have connected account for toolkit

package/.agents/skills/composio/rules/app-fetch-tools.md

@@ -0,0 +1,292 @@
+---
+title: Fetching Tools for Applications
+impact: HIGH
+description: Essential patterns for discovering and retrieving tools from Composio for direct execution in applications
+tags: [tools, fetch, discovery, apps, providers]
+---
+
+# Fetching Tools for Applications
+
+When building applications (non-agent workflows), use direct tool fetching methods to discover and retrieve tools from Composio.
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess tool or toolkit names. Always verify slugs before using them:
+> - Use `composio manage toolkits list` / `composio manage toolkits info "..."` and `composio manage tools list --toolkits "..."` / `composio manage tools info "..."` (CLI)
+> - Use `composio.tools.get()` to discover available tools programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## Methods Overview
+
+- **`tools.get()`** - Use when working with a provider (OpenAI, Vercel, etc.). Returns tools wrapped in provider-specific format.
+- **`tools.getRawComposioTools()`** - Use for standalone applications and building UIs. Returns raw tool metadata without provider wrapping.
+
+### 1. tools.get() - For Provider-Based Applications
+
+Use `tools.get()` when you're using Composio with a provider like OpenAI, Vercel AI SDK, or LangChain. This method wraps tools in the format expected by your provider.
+
+**Get tools from a toolkit:**
+```typescript
+// Get important tools only (auto-applies important filter)
+const importantGithubTools = await composio.tools.get('default', {
+  toolkits: ['github']
+});
+
+// Get a limited number of tools (does NOT auto-apply important filter)
+const githubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 10
+});
+```
+
+**Get a specific tool by slug:**
+```typescript
+const tool = await composio.tools.get('default', 'GITHUB_GET_REPO');
+```
+
+### 2. tools.getRawComposioTools() - For Standalone Applications & UIs
+
+Use `getRawComposioTools()` for standalone applications and building UIs. This method returns raw tool metadata without provider-specific wrapping, making it ideal for:
+- Building tool selection UIs
+- Creating tool catalogs or documentation
+- Direct tool execution workflows (without providers)
+- Custom tool management interfaces
+
+```typescript
+// Get important tools (auto-applies important filter)
+const importantTools = await composio.tools.getRawComposioTools({
+  toolkits: ['github']
+});
+
+// Get specific tools by slug
+const specificTools = await composio.tools.getRawComposioTools({
+  tools: ['GITHUB_GET_REPOS', 'SLACK_SEND_MESSAGE']
+});
+
+// Get limited tools (does NOT auto-apply important)
+const limitedTools = await composio.tools.getRawComposioTools({
+  toolkits: ['slack'],
+  limit: 5
+});
+```
+
+## Important Filter Behavior
+
+The `important` filter auto-applies to show only the most commonly used tools.
+
+**Auto-applies when:**
+- Only `toolkits` filter is provided (no other filters)
+
+**Does NOT auto-apply when:**
+- `limit` is specified
+- `search` is used
+- `tools` (specific slugs) are provided
+- `tags` are specified
+- `important` is explicitly set to `false`
+
+```typescript
+// Auto-applies important=true
+await composio.tools.get('default', { toolkits: ['github'] });
+
+// Does NOT auto-apply important (limit specified)
+await composio.tools.get('default', { toolkits: ['github'], limit: 10 });
+
+// Does NOT auto-apply important (search used)
+await composio.tools.get('default', { search: 'repo' });
+
+// Explicitly disable important filter
+await composio.tools.get('default', { toolkits: ['github'], important: false });
+```
+
+## Filter Parameters
+
+Available filters for both `tools.get()` and `tools.getRawComposioTools()`:
+
+- `toolkits`: Array of toolkit names (e.g., `['github', 'slack']`)
+- `tools`: Array of specific tool slugs (e.g., `['GITHUB_GET_REPO']`)
+- `search`: Search string for tool names/descriptions
+- `limit`: Maximum number of tools to return
+- `tags`: Array of tags to filter by
+- `scopes`: Array of scopes to filter by
+- `authConfigIds`: Array of auth config IDs to filter tools by specific auth configs
+- `important`: Boolean to explicitly control important filter (auto-applies in some cases)
+
+**Note:** You cannot use `tools` and `toolkits` filters together.
+
+## Schema Modification
+
+Customize tool schemas at fetch time:
+
+```typescript
+const customizedTools = await composio.tools.get('default', {
+  toolkits: ['github']
+}, {
+  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+    return { ...schema, description: 'Custom description' };
+  }
+});
+```
+
+## Best Practices
+
+1. **Choose the right method:**
+   - Use `tools.get()` when working with providers (OpenAI, Vercel, LangChain)
+   - Use `tools.getRawComposioTools()` for standalone apps, UIs, and catalogs
+
+2. **Use important filter for UIs**: Show important tools first, then allow users to discover all tools
+
+3. **Cache tool metadata**: Tools don't change frequently, cache the results
+
+4. **Filter by toolkit**: Group tools by toolkit for better organization
+
+5. **Don't mix tools and toolkits filters**: Cannot use both filters together
+
+## Complete Discovery Workflow
+
+Here's the recommended workflow for discovering and using tools:
+
+```typescript
+// Step 1: Get toolkit information (to discover available versions)
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Toolkit:', githubToolkit.name);
+console.log('Available versions:', githubToolkit.versions);
+console.log('Current version:', githubToolkit.version);
+console.log('Description:', githubToolkit.description);
+
+// Step 2: Discover all available tools in the toolkit
+const allGithubTools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100 // Adjust based on your needs
+});
+
+console.log('\nAvailable tools:');
+allGithubTools.forEach(tool => {
+  console.log(`- ${tool.name}: ${tool.description}`);
+});
+
+// Step 3: Find the tool you need
+const repoTool = allGithubTools.find(t => t.name === 'GITHUB_GET_REPO');
+if (!repoTool) {
+  throw new Error('Tool not found');
+}
+
+// Step 4: Execute the tool with a pinned version string
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00' // ✅ Pinned version string for stability
+});
+```
+
+```python
+# Step 1: Get toolkit information (to discover available versions)
+github_toolkit = composio.toolkits.get("github")
+print(f"Toolkit: {github_toolkit.name}")
+print(f"Available versions: {github_toolkit.versions}")
+print(f"Current version: {github_toolkit.version}")
+print(f"Description: {github_toolkit.description}")
+
+# Step 2: Discover all available tools in the toolkit
+all_github_tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100  # Adjust based on your needs
+)
+
+print("\nAvailable tools:")
+for tool in all_github_tools:
+    print(f"- {tool.name}: {tool.description}")
+
+# Step 3: Find the tool you need
+repo_tool = next((t for t in all_github_tools if t.name == "GITHUB_GET_REPO"), None)
+if not repo_tool:
+    raise Exception("Tool not found")
+
+# Step 4: Execute the tool with a pinned version string
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPO",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # ✅ Pinned version string for stability
+)
+```
+
+## ❌ Common Mistakes
+
+```typescript
+// DON'T: Guess or make up tool names
+const result = await composio.tools.execute('GITHUB_GET_REPOSITORY', { // ❌ Wrong name
+  userId: 'user_123',
+  arguments: { repo: 'sdk' },
+  version: '12082025_00'
+});
+
+// DON'T: Use hardcoded versions without checking
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'user_123',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00' // ❌ This might be outdated, use `composio manage toolkits info "github"` to get the latest version
+});
+```
+
+```python
+# DON'T: Guess or make up tool names
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPOSITORY",  # ❌ Wrong name
+    user_id="user_123",
+    arguments={"repo": "sdk"},
+    version="12082025_00"
+)
+
+# DON'T: Use hardcoded versions without checking
+result = composio.tools.execute(
+    tool="GITHUB_GET_REPO",
+    user_id="user_123",
+    arguments={"owner": "composio", "repo": "sdk"},
+    version="12082025_00"  # ❌ This might be outdated
+)
+```
+
+## ✅ Best Practices
+
+```typescript
+// DO: Discover available versions and tools first
+const toolkit = await composio.toolkits.get('github');
+console.log('Available versions:', toolkit.versions);
+
+const tools = await composio.tools.get('default', {
+  toolkits: ['github'],
+  limit: 100
+});
+
+// DO: Use discovered tool names and pin to a specific version string
+const toolName = tools.find(t => t.description.includes('repository'))?.name;
+if (toolName) {
+  const result = await composio.tools.execute(toolName, {
+    userId: 'user_123',
+    arguments: { owner: 'composio', repo: 'sdk' },
+    version: '12082025_00' // ✅ Pinned version string for stability
+  });
+}
+```
+
+```python
+# DO: Discover available versions and tools first
+toolkit = composio.toolkits.get("github")
+print(f"Available versions: {toolkit.versions}")
+
+tools = composio.tools.get(
+    user_id="default",
+    toolkits=["github"],
+    limit=100
+)
+
+# DO: Use discovered tool names and pin to a specific version string
+tool_name = next((t.name for t in tools if "repository" in t.description), None)
+if tool_name:
+    result = composio.tools.execute(
+        tool=tool_name,
+        user_id="user_123",
+        arguments={"owner": "composio", "repo": "sdk"},
+        version="12082025_00"  # ✅ Pinned version string for stability
+    )
+```