zilmate 1.7.8 → 1.8.1

package/.agents/skills/composio/rules/tr-framework-mastra.md

@@ -0,0 +1,185 @@
+---
+title: Using Composio with Mastra Framework
+impact: HIGH
+description: Use Tool Router for native tool integration and MCP for multi-tenant scenarios with Mastra agents
+tags: [tool-router, mastra, framework, native-tools, mcp, integration]
+---
+
+# Using Composio with Mastra Framework
+
+Composio integrates with Mastra using **Tool Router sessions**. Use **native tools** (recommended) via `session.tools()`, or **MCP tools** when MCP protocol compliance is required.
+
+## Installation
+
+```bash
+npm install @mastra/core@latest @ai-sdk/openai @composio/core@latest @composio/mastra@latest
+
+# For MCP (optional)
+npm install @mastra/mcp@latest
+```
+
+## ✅ Correct - Native Tools (Recommended)
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+
+const composio = new Composio({
+  apiKey: process.env.COMPOSIO_API_KEY,
+  provider: new MastraProvider()
+});
+
+async function createAgent(userId: string, message: string) {
+  // Create Tool Router session
+  const session = await composio.create(userId, {
+    toolkits: ['gmail', 'slack'],
+    manageConnections: true
+  });
+
+  const tools = await session.tools();
+
+  const agent = new Agent({
+    id: 'composio-agent',
+    name: 'Assistant',
+    instructions: `You have access to Gmail and Slack tools to assist the user with their query`,
+    model: openai('gpt-5.2'),
+    tools: tools
+  });
+
+  return await agent.generate([{ role: 'user', content: message }]);
+}
+```
+
+**Key Points:**
+- Create new sessions per request/conversation
+- Use `session.tools()` for native Mastra tools
+- Import `Composio` from `@composio/core` and `MastraProvider` from `@composio/mastra`
+- Use `openai('gpt-5.2')` from `@ai-sdk/openai`
+
+## ✅ Correct - MCP Tools
+
+When MCP protocol compliance is required, expose Tool Router sessions as MCP servers:
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+import { MCPClient } from '@mastra/mcp';
+import { Composio } from '@composio/core';
+import { MastraProvider } from '@composio/mastra';
+
+const composio = new Composio({
+  apiKey: process.env.COMPOSIO_API_KEY,
+  provider: new MastraProvider()
+});
+
+async function createAgentWithMcp(userId: string, message: string) {
+  // 1. Create Tool Router session
+  const session = await composio.create(userId, {
+    toolkits: ['gmail', 'slack'],
+    manageConnections: true
+  });
+
+  // 2. Create MCP client with session URL and headers
+  const mcpClient = new MCPClient({
+    id: `composio-${session.sessionId}`,
+    servers: {
+      composio: {
+        url: session.mcp.url,
+        requestInit: {
+          headers: session.mcp.headers
+        }
+      }
+    }
+  });
+
+  // 3. Get tools via MCPClient
+  const tools = await mcpClient.listTools();
+
+  const agent = new Agent({
+    id: 'mcp-agent',
+    name: 'MCP Assistant',
+    instructions: 'You have access to Composio tools via MCP.',
+    model: openai('gpt-5.2'),
+    tools: tools
+  });
+
+  return await agent.generate([{ role: 'user', content: message }]);
+}
+```
+
+**For dynamic toolsets (multi-tenant):**
+```typescript
+// Create agent without tools in constructor
+const agent = new Agent({
+  id: 'dynamic-agent',
+  model: openai('gpt-5.2'),
+  instructions: 'You help users with tasks.'
+});
+
+// Pass toolsets per request
+const toolsets = await mcpClient.listToolsets();
+const response = await agent.generate(message, { toolsets });
+```
+
+## ❌ Incorrect Patterns
+
+```typescript
+// ❌ Don't bypass Tool Router sessions
+const mcpClient = new MCPClient({
+  servers: { composio: { url: 'https://mcp.composio.dev' } }
+});
+
+// ❌ Don't use non-existent methods
+const tools = await session.mcpTools(); // Doesn't exist
+const url = session.getMcpServerUrl(); // Doesn't exist
+
+// ❌ Don't cache tools across users
+const cachedTools = await session.tools();
+// Reusing for different users...
+
+// ❌ Don't forget MastraProvider
+const composio = new Composio({ apiKey: key }); // Missing provider
+
+// ❌ Don't use string format for model
+model: 'openai/gpt-5.2' // Wrong - use openai('gpt-5.2')
+```
+
+## Key Principles
+
+**Native Tools:**
+- Use `session.tools()` - best performance, type-safe
+- Recommended for most use cases
+
+**MCP Tools:**
+- Use `session.mcp.url` + `MCPClient` + `listTools()`/`listToolsets()`
+- Only when MCP protocol compliance is required
+- Still uses Tool Router sessions
+
+**Session Management:**
+- Always create sessions via `composio.create()`
+- Create new sessions per request/conversation
+- Don't cache tools or sessions across users
+- Use `manageConnections: true`
+
+**Setup:**
+- Import `Composio` from `@composio/core`
+- Import `MastraProvider` from `@composio/mastra`
+- Use `openai('gpt-5.2')` from `@ai-sdk/openai`
+- Mention tools in agent instructions
+
+## When to Use
+
+| Use Case | Approach | Method |
+|----------|----------|--------|
+| Most scenarios | Native Tools | `session.tools()` |
+| MCP protocol required | MCP Tools | MCP client + `listTools()` |
+| Multi-tenant dynamic auth | MCP Tools | MCP client + `listToolsets()` |
+
+## Reference
+
+- [Mastra Agents](https://mastra.ai/docs/agents/overview)
+- [Mastra MCP](https://mastra.ai/docs/mcp/overview)
+- [Composio Tool Router](https://docs.composio.dev/sdk/typescript/api/tool-router)
+- [Tool Router Sessions](tr-session-lifecycle.md)

package/.agents/skills/composio/rules/tr-mcp-vs-native.md

@@ -0,0 +1,248 @@
+---
+title: Use Native Tools for Performance and Control
+impact: HIGH
+description: Prefer native tools over MCP for faster execution, full control, and modifier support
+tags: [tool-router, mcp, integration, providers, performance]
+---
+
+# Use Native Tools for Performance and Control
+
+Tool Router supports two approaches: **Native tools (recommended)** for performance and control, or MCP clients for framework independence.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Use MCP when you need logging, modifiers, or performance
+const composio = new Composio(); // No provider
+const { mcp } = await composio.create('user_123', {
+  toolkits: ['gmail']
+});
+
+const client = await createMCPClient({
+  transport: { type: 'http', url: mcp.url }
+});
+
+// ❌ No control over tool execution
+// ❌ No modifier support
+// ❌ Extra API calls via MCP server
+// ❌ Slower execution
+const tools = await client.tools();
+```
+
+```python
+# DON'T: Use MCP when you need logging, modifiers, or performance
+composio = Composio()  # No provider
+session = composio.create(user_id="user_123")
+
+# ❌ No control over tool execution
+# ❌ No modifier support
+# ❌ Extra API calls via MCP server
+# ❌ Slower execution
+```
+
+## ✅ Correct - Use Native Tools (Recommended)
+
+```typescript
+// DO: Use native tools for performance and control
+import { Composio } from '@composio/core';
+import { VercelProvider } from '@composio/vercel';
+
+// Add provider for native tools
+const composio = new Composio({
+  provider: new VercelProvider()
+});
+
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack']
+});
+
+// ✅ Direct tool execution (no MCP overhead)
+// ✅ Full modifier support
+// ✅ Logging and telemetry
+// ✅ Faster performance
+const tools = await session.tools();
+```
+
+```python
+# DO: Use native tools for performance and control
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+# Add provider for native tools
+composio = Composio(provider=OpenAIProvider())
+
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"]
+)
+
+# ✅ Direct tool execution (no MCP overhead)
+# ✅ Full modifier support
+# ✅ Logging and telemetry
+# ✅ Faster performance
+tools = session.tools()
+```
+
+## ✅ Correct - Native Tools with Modifiers
+
+```typescript
+// DO: Use modifiers for logging and control
+import { Composio } from '@composio/core';
+import { VercelProvider } from '@composio/vercel';
+import { SessionExecuteMetaModifiers } from '@composio/core';
+
+const composio = new Composio({
+  provider: new VercelProvider()
+});
+
+const session = await composio.create('user_123', {
+  toolkits: ['gmail']
+});
+
+// Add modifiers for logging during execution
+const modifiers: SessionExecuteMetaModifiers = {
+  beforeExecute: ({ toolSlug, sessionId, params }) => {
+    console.log(`[${sessionId}] Executing ${toolSlug}`);
+    console.log('Parameters:', JSON.stringify(params, null, 2));
+    return params;
+  },
+  afterExecute: ({ toolSlug, sessionId, result }) => {
+    console.log(`[${sessionId}] Completed ${toolSlug}`);
+    console.log('Success:', result.successful);
+    return result;
+  }
+};
+
+const tools = await session.tools(modifiers);
+
+// Now when agent executes tools, you see:
+// [session_abc123] Executing GMAIL_FETCH_EMAILS
+// Parameters: { "maxResults": 10, "query": "from:user@example.com" }
+// [session_abc123] Completed GMAIL_FETCH_EMAILS
+// Success: true
+```
+
+```typescript
+// Advanced: Add telemetry and schema customization
+const advancedModifiers: SessionExecuteMetaModifiers = {
+  beforeExecute: ({ toolSlug, sessionId, params }) => {
+    // Send to analytics
+    analytics.track('tool_execution_started', {
+      tool: toolSlug,
+      session: sessionId,
+      params
+    });
+
+    // Validate parameters
+    if (!params) {
+      throw new Error(`Missing parameters for ${toolSlug}`);
+    }
+
+    return params;
+  },
+  afterExecute: ({ toolSlug, sessionId, result }) => {
+    // Track completion and duration
+    analytics.track('tool_execution_completed', {
+      tool: toolSlug,
+      session: sessionId,
+      success: result.successful
+    });
+
+    // Handle errors
+    if (!result.successful) {
+      console.error(`Tool ${toolSlug} failed:`, result.error);
+    }
+
+    return result;
+  },
+  modifySchema: ({ toolSlug, schema }) => {
+    // Simplify schemas for better AI understanding
+    if (toolSlug === 'GMAIL_SEND_EMAIL') {
+      // Remove optional fields for simpler usage
+      delete schema.parameters.properties.cc;
+      delete schema.parameters.properties.bcc;
+    }
+    return schema;
+  }
+};
+```
+
+```python
+# DO: Use modifiers for logging, validation, and telemetry
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"]
+)
+
+# Add modifiers for full control over tool execution
+def before_execute(context):
+    print(f"[{context['session_id']}] Executing {context['tool_slug']}")
+    print(f"Parameters: {context['params']}")
+    # Add custom validation, logging, telemetry
+    return context['params']
+
+def after_execute(context):
+    print(f"[{context['session_id']}] Completed {context['tool_slug']}")
+    print(f"Result: {context['result']}")
+    # Transform results, handle errors, track metrics
+    return context['result']
+
+tools = session.tools(
+    modifiers={
+        "before_execute": before_execute,
+        "after_execute": after_execute
+    }
+)
+```
+
+## Performance Comparison
+
+| Feature | Native Tools | MCP |
+|---------|-------------|-----|
+| Execution Speed | **Fast** (direct) | Slower (extra HTTP calls) |
+| API Overhead | **Minimal** | Additional MCP server roundtrips |
+| Modifier Support | **✅ Full support** | ❌ Not available |
+| Logging & Telemetry | **✅ beforeExecute/afterExecute** | ❌ Limited visibility |
+| Schema Customization | **✅ modifySchema** | ❌ Not available |
+| Framework Lock-in | Yes (provider-specific) | No (universal) |
+
+## When to Use Each
+
+### ✅ Use Native Tools (Recommended) When:
+- **Performance matters**: Direct execution, no MCP overhead
+- **Need logging**: Track tool execution, parameters, results
+- **Need control**: Validate inputs, transform outputs, handle errors
+- **Production apps**: Telemetry, monitoring, debugging
+- **Single framework**: You're committed to one AI framework
+
+### Use MCP Only When:
+- **Multiple frameworks**: Switching between Claude, Vercel AI, LangChain
+- **Framework flexibility**: Not committed to one provider yet
+- **Prototyping**: Quick testing across different AI tools
+
+## Modifier Use Cases
+
+With native tools, modifiers enable:
+
+1. **Logging**: Track every tool execution with parameters and results
+2. **Telemetry**: Send metrics to Datadog, New Relic, etc.
+3. **Validation**: Check parameters before execution
+4. **Error Handling**: Catch and transform errors
+5. **Rate Limiting**: Control tool execution frequency
+6. **Caching**: Cache results for repeated calls
+7. **Schema Customization**: Simplify schemas for specific AI models
+
+## Key Insight
+
+**Native tools eliminate the MCP server middleman**, resulting in faster execution and giving you full control over the tool execution lifecycle. The only trade-off is framework lock-in, which is acceptable in production applications where you've already chosen your AI framework.
+
+## Reference
+
+- [Session Modifiers](https://docs.composio.dev/sdk/typescript/api/tool-router#using-modifiers)
+- [SessionExecuteMetaModifiers](https://docs.composio.dev/sdk/typescript/api/tool-router#sessionexecutemetamodifiers-v040)
+- [Tool Router Performance](https://docs.composio.dev/sdk/typescript/api/tool-router#best-practices)

package/.agents/skills/composio/rules/tr-session-basic.md

@@ -0,0 +1,82 @@
+---
+title: Create Basic Tool Router Sessions
+impact: HIGH
+description: Essential pattern for initializing Tool Router sessions with proper user isolation
+tags: [tool-router, session, initialization, agents]
+---
+
+# Create Basic Tool Router Sessions
+
+Always create isolated Tool Router sessions per user to ensure proper data isolation and scoped tool access.
+
+> 📖 **Before you begin:** Make sure you have set up your API keys. See [Setting Up API Keys](./setup-api-keys.md) for instructions.
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess toolkit names. Always verify toolkit slugs before using them:
+> - Use `composio manage toolkits list` to discover and `composio manage toolkits info "..."` to view toolkit details (CLI)
+> - Use `composio.toolkits.get()` to discover toolkits programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Using shared session for multiple users
+const sharedSession = await composio.create('default', {
+  toolkits: ['gmail']
+});
+// All users share the same session - security risk!
+```
+
+```python
+# DON'T: Using shared session for multiple users
+shared_session = composio.create(
+    user_id="default",
+    toolkits=["gmail"]
+)
+# All users share the same session - security risk!
+```
+
+## ✅ Correct
+
+```typescript
+// DO: Create per-user sessions for isolation
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+// Each user gets their own isolated session
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack']
+});
+
+console.log('Session ID:', session.sessionId);
+console.log('MCP URL:', session.mcp.url);
+```
+
+```python
+# DO: Create per-user sessions for isolation
+from composio import Composio
+
+composio = Composio()
+
+# Each user gets their own isolated session
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"]
+)
+
+print(f"Session ID: {session.session_id}")
+print(f"MCP URL: {session.mcp.url}")
+```
+
+## Key Points
+
+- **User Isolation**: Each user must have their own session
+- **Toolkit Scoping**: Specify which toolkits the session can access
+- **Session ID**: Store the session ID to retrieve it later
+- **MCP URL**: Use this URL with any MCP-compatible AI framework
+
+## Reference
+
+- [Tool Router API Docs](https://docs.composio.dev/sdk/typescript/api/tool-router)
+- [Creating Sessions](https://docs.composio.dev/sdk/typescript/api/tool-router#creating-sessions)

package/.agents/skills/composio/rules/tr-session-config.md

@@ -0,0 +1,172 @@
+---
+title: Configure Tool Router Sessions Properly
+impact: MEDIUM
+description: Use session configuration options to control toolkit access, tools, and behavior
+tags: [tool-router, configuration, toolkits, tools, session]
+---
+
+# Configure Tool Router Sessions Properly
+
+Tool Router sessions support rich configuration for fine-grained control over toolkit and tool access.
+
+> **⚠️ IMPORTANT:** Do NOT make up or guess toolkit or tool names. Always verify slugs before using them:
+> - Use `composio manage toolkits list` / `composio manage toolkits info "..."` to discover and view toolkit details (CLI)
+> - Use `composio manage tools list --toolkits "..."` / `composio manage tools info "..."` to discover and view tool schemas (CLI)
+> - Use `composio.tools.get()` to discover tools programmatically (SDK)
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Enable all toolkits without restrictions
+const session = await composio.create('user_123', {
+  // No toolkit restrictions - exposes everything!
+});
+
+// DON'T: Mix incompatible configuration patterns
+const session = await composio.create('user_123', {
+  toolkits: { enable: ['gmail'] },
+  toolkits: ['slack']  // This will override the first one!
+});
+```
+
+```python
+# DON'T: Enable all toolkits without restrictions
+session = composio.create(
+    user_id="user_123"
+    # No toolkit restrictions - exposes everything!
+)
+```
+
+## ✅ Correct - Basic Configuration
+
+```typescript
+// DO: Explicitly specify toolkits
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+// Simple toolkit list
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack', 'github']
+});
+
+// Explicit enable
+const session2 = await composio.create('user_123', {
+  toolkits: { enable: ['gmail', 'slack'] }
+});
+
+// Disable specific toolkits (enable all others)
+const session3 = await composio.create('user_123', {
+  toolkits: { disable: ['calendar'] }
+});
+```
+
+```python
+# DO: Explicitly specify toolkits
+from composio import Composio
+
+composio = Composio()
+
+# Simple toolkit list
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack", "github"]
+)
+
+# Explicit enable
+session2 = composio.create(
+    user_id="user_123",
+    toolkits={"enable": ["gmail", "slack"]}
+)
+```
+
+## ✅ Correct - Fine-Grained Tool Control
+
+```typescript
+// DO: Control specific tools per toolkit
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack'],
+  tools: {
+    // Only allow reading emails, not sending
+    gmail: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEARCH_EMAILS'],
+
+    // Or use enable/disable
+    slack: {
+      disable: ['SLACK_DELETE_MESSAGE'] // Safety: prevent deletions
+    }
+  }
+});
+```
+
+```python
+# DO: Control specific tools per toolkit
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"],
+    tools={
+        # Only allow reading emails, not sending
+        "gmail": ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"],
+
+        # Or use enable/disable
+        "slack": {
+            "disable": ["SLACK_DELETE_MESSAGE"]  # Safety: prevent deletions
+        }
+    }
+)
+```
+
+## ✅ Correct - Tag-Based Filtering
+
+```typescript
+// DO: Use tags to filter by behavior
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'github'],
+  // Global tags: only read-only tools
+  tags: ['readOnlyHint'],
+
+  // Override tags per toolkit
+  tools: {
+    github: {
+      tags: ['readOnlyHint', 'idempotentHint']
+    }
+  }
+});
+```
+
+```python
+# DO: Use tags to filter by behavior
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "github"],
+    # Global tags: only read-only tools
+    tags=["readOnlyHint"],
+
+    # Override tags per toolkit
+    tools={
+        "github": {
+            "tags": ["readOnlyHint", "idempotentHint"]
+        }
+    }
+)
+```
+
+## Available Tags
+
+- `readOnlyHint` - Tools that only read data
+- `destructiveHint` - Tools that modify or delete data
+- `idempotentHint` - Tools safe to retry
+- `openWorldHint` - Tools operating in open contexts
+
+## Configuration Best Practices
+
+1. **Least Privilege**: Only enable toolkits/tools needed
+2. **Tag Filtering**: Use tags to restrict dangerous operations
+3. **Per-Toolkit Tools**: Fine-tune access per toolkit
+4. **Auth Configs**: Map toolkits to specific auth configurations
+
+## Reference
+
+- [Configuration Options](https://docs.composio.dev/sdk/typescript/api/tool-router#configuration-options)
+- [Tool Tags](https://docs.composio.dev/sdk/typescript/api/tool-router#tags)