zilmate 1.7.8 → 1.8.1

package/.agents/skills/composio/rules/setup-api-keys.md

@@ -0,0 +1,230 @@
+---
+title: Setting Up API Keys for Your Project
+impact: CRITICAL
+description: Configure Composio, OpenAI, and Anthropic API keys to enable your AI agent projects
+tags: [setup, api-keys, configuration, environment, composio, openai, anthropic]
+---
+
+# Setting Up API Keys for Your Project
+
+Before building AI agents with Composio, you need to configure the necessary API keys. This includes Composio for tool access and your preferred LLM provider (OpenAI or Anthropic).
+
+## Setting Up Composio API Key
+
+### Step 1: Get Your Composio API Key
+
+1. Visit [Composio Platform](https://platform.composio.dev)
+2. Sign up or log in to your account
+3. Select or create a project
+4. Navigate to **Project Settings**
+5. Switch to the **API Keys** tab
+6. Copy your project-level API key
+
+### Step 2: Add to Environment Variables
+
+Create a `.env` file in your project root (if it doesn't exist) and add:
+
+```bash
+COMPOSIO_API_KEY=your_composio_api_key_here
+```
+
+## Setting Up LLM Provider API Keys
+
+### OpenAI API Key
+
+If you're using OpenAI models (GPT-4, GPT-4o, etc.):
+
+1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
+2. Sign in or create an account
+3. Navigate to API Keys section
+4. Create a new API key or copy an existing one
+5. Add to your `.env` file:
+
+```bash
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+### Anthropic API Key
+
+If you're using Anthropic models (Claude, Claude Sonnet, etc.):
+
+1. Visit [Anthropic Console](https://console.anthropic.com/settings/keys)
+2. Sign in or create an account
+3. Navigate to API Keys section
+4. Create a new API key or copy an existing one
+5. Add to your `.env` file:
+
+```bash
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+```
+
+## ❌ Incorrect - Hardcoding API Keys
+
+```typescript
+// DON'T: Never hardcode API keys in your code
+const composio = new Composio({
+  apiKey: 'sk_composio_abc123xyz' // ❌ Security risk!
+});
+
+const openai = new OpenAI({
+  apiKey: 'sk-proj-abc123' // ❌ Will be exposed in version control
+});
+```
+
+```python
+# DON'T: Never hardcode API keys
+composio = Composio(api_key="sk_composio_abc123xyz")  # ❌ Security risk!
+
+client = OpenAI(api_key="sk-proj-abc123")  # ❌ Will be exposed in version control
+```
+
+## ✅ Correct - Using Environment Variables
+
+```typescript
+// DO: Load API keys from environment variables
+import { Composio } from '@composio/core';
+import { OpenAI } from 'openai';
+
+const composio = new Composio({
+  apiKey: process.env.COMPOSIO_API_KEY // ✅ Secure
+});
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY // ✅ Secure
+});
+```
+
+```python
+# DO: Load API keys from environment variables
+import os
+from composio import Composio
+from openai import OpenAI
+
+composio = Composio(api_key=os.environ["COMPOSIO_API_KEY"])  # ✅ Secure
+
+openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])  # ✅ Secure
+```
+
+## Complete .env File Example
+
+```bash
+# Composio Configuration
+COMPOSIO_API_KEY=your_composio_api_key_here
+
+# LLM Provider (choose one or both based on your needs)
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Optional: Other configurations
+NODE_ENV=development
+PORT=3000
+```
+
+## Loading Environment Variables
+
+### Node.js / TypeScript
+
+Install `dotenv`:
+
+```bash
+npm install dotenv
+```
+
+Load at the top of your entry file:
+
+```typescript
+import 'dotenv/config';
+// Or
+require('dotenv').config();
+```
+
+### Python
+
+Install `python-dotenv`:
+
+```bash
+pip install python-dotenv
+```
+
+Load in your code:
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+## Security Best Practices
+
+1. **Never commit `.env` files** - Add `.env` to your `.gitignore`:
+   ```
+   # .gitignore
+   .env
+   .env.local
+   .env.*.local
+   ```
+
+2. **Use different keys for different environments** - Create separate API keys for development, staging, and production
+
+3. **Rotate keys regularly** - Periodically regenerate API keys for security
+
+4. **Restrict key permissions** - Use the minimum required permissions for each API key
+
+5. **Use secret management in production** - Consider using services like:
+   - AWS Secrets Manager
+   - Google Cloud Secret Manager
+   - HashiCorp Vault
+   - Vercel Environment Variables
+   - Railway Environment Variables
+
+## Verifying Your Setup
+
+After setting up your API keys, verify they work:
+
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({
+  apiKey: process.env.COMPOSIO_API_KEY
+});
+
+// Test the connection
+const apps = await composio.apps.list();
+console.log('✅ Composio API key is working!');
+```
+
+```python
+from composio import Composio
+
+composio = Composio(api_key=os.environ["COMPOSIO_API_KEY"])
+
+# Test the connection
+apps = composio.apps.list()
+print("✅ Composio API key is working!")
+```
+
+## Troubleshooting
+
+### "API key not found" error
+
+- Ensure your `.env` file is in the project root
+- Verify you're loading environment variables before using them
+- Check for typos in variable names (`COMPOSIO_API_KEY`, not `COMPOSIO_KEY`)
+
+### "Invalid API key" error
+
+- Verify you copied the complete API key
+- Check that you're using a project-level API key from Composio
+- Ensure the key hasn't been revoked or expired
+
+### Environment variables not loading
+
+- Restart your development server after modifying `.env`
+- Ensure `dotenv` is installed and configured correctly
+- Check that `.env` is in the correct directory
+
+## Reference
+
+- [Composio Platform](https://platform.composio.dev)
+- [OpenAI API Keys](https://platform.openai.com/api-keys)
+- [Anthropic Console](https://console.anthropic.com/settings/keys)
+- [Composio Documentation](https://docs.composio.dev)

package/.agents/skills/composio/rules/tr-auth-auto.md

@@ -0,0 +1,110 @@
+---
+title: Enable Auto Authentication in Chat
+impact: HIGH
+description: Allow users to authenticate toolkits directly within chat conversations
+tags: [authentication, tool-router, user-experience, oauth]
+---
+
+# Enable Auto Authentication in Chat
+
+Enable `manageConnections` to allow users to authenticate toolkits on-demand during agent conversations.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Disable connection management for interactive apps
+const session = await composio.create('user_123', {
+  toolkits: ['gmail'],
+  manageConnections: false // User can't authenticate!
+});
+
+// Agent tries to use Gmail but user isn't connected
+// Tool execution will fail with no way to fix it
+```
+
+```python
+# DON'T: Disable connection management for interactive apps
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"],
+    manage_connections=False  # User can't authenticate!
+)
+
+# Agent tries to use Gmail but user isn't connected
+# Tool execution will fail with no way to fix it
+```
+
+## ✅ Correct
+
+```typescript
+// DO: Enable connection management for interactive apps
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack'],
+  manageConnections: true // Users can authenticate in chat
+});
+
+// When agent needs Gmail and user isn't connected:
+// 1. Agent calls COMPOSIO_MANAGE_CONNECTIONS tool
+// 2. User receives auth link in chat
+// 3. User authenticates via OAuth
+// 4. Agent continues with Gmail access
+```
+
+```python
+# DO: Enable connection management for interactive apps
+from composio import Composio
+
+composio = Composio()
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"],
+    manage_connections=True  # Users can authenticate in chat
+)
+
+# When agent needs Gmail and user isn't connected:
+# 1. Agent calls COMPOSIO_MANAGE_CONNECTIONS tool
+# 2. User receives auth link in chat
+# 3. User authenticates via OAuth
+# 4. Agent continues with Gmail access
+```
+
+## Advanced: Custom Callback URL
+
+```typescript
+// Configure custom callback for OAuth flow
+const session = await composio.create('user_123', {
+  toolkits: ['gmail'],
+  manageConnections: {
+    enable: true,
+    callbackUrl: 'https://your-app.com/auth/callback'
+  }
+});
+```
+
+```python
+# Configure custom callback for OAuth flow
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"],
+    manage_connections={
+        "enable": True,
+        "callback_url": "https://your-app.com/auth/callback"
+    }
+)
+```
+
+## How It Works
+
+1. Agent detects missing connection for a toolkit
+2. Agent automatically calls meta tool `COMPOSIO_MANAGE_CONNECTIONS`
+3. Tool returns OAuth redirect URL
+4. User authenticates via the URL
+5. Agent resumes with access granted
+
+## Reference
+
+- [Connection Management](https://docs.composio.dev/sdk/typescript/api/tool-router#manageconnections)
+- [Authorization Flow](https://docs.composio.dev/sdk/typescript/api/tool-router#authorization-flow)

package/.agents/skills/composio/rules/tr-auth-connections.md

@@ -0,0 +1,167 @@
+---
+title: Configure Connection Management Properly
+impact: CRITICAL
+description: Understand manageConnections settings to control authentication behavior in Tool Router
+tags: [authentication, tool-router, connections, configuration]
+---
+
+# Configure Connection Management Properly
+
+The `manageConnections` setting determines how Tool Router handles missing toolkit connections. Configure it correctly based on your application type.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Disable connections in interactive applications
+const session = await composio.create('user_123', {
+  toolkits: ['gmail'],
+  manageConnections: false // Tools will FAIL if user not connected!
+});
+
+// When agent tries to use Gmail:
+// ❌ Error: No connected account found for gmail
+// User has no way to authenticate
+```
+
+```python
+# DON'T: Disable connections in interactive applications
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"],
+    manage_connections=False  # Tools will FAIL if user not connected!
+)
+
+# When agent tries to use Gmail:
+# ❌ Error: No connected account found for gmail
+# User has no way to authenticate
+```
+
+## ✅ Correct - Enable Auto Authentication (Default)
+
+```typescript
+// DO: Enable connection management for interactive apps
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+// Option 1: Use default (manageConnections: true)
+const session1 = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack']
+  // manageConnections defaults to true
+});
+
+// Option 2: Explicitly enable with boolean
+const session2 = await composio.create('user_123', {
+  toolkits: ['gmail'],
+  manageConnections: true // Agent can prompt for auth
+});
+
+// How it works:
+// 1. Agent tries to use Gmail tool
+// 2. No connection exists
+// 3. Agent calls COMPOSIO_MANAGE_CONNECTIONS meta tool
+// 4. User receives auth link in chat
+// 5. User authenticates
+// 6. Agent continues with Gmail access
+```
+
+```python
+# DO: Enable connection management for interactive apps
+from composio import Composio
+
+composio = Composio()
+
+# Option 1: Use default (manage_connections: True)
+session1 = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"]
+    # manage_connections defaults to True
+)
+
+# Option 2: Explicitly enable with boolean
+session2 = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"],
+    manage_connections=True  # Agent can prompt for auth
+)
+
+# How it works:
+# 1. Agent tries to use Gmail tool
+# 2. No connection exists
+# 3. Agent calls COMPOSIO_MANAGE_CONNECTIONS meta tool
+# 4. User receives auth link in chat
+# 5. User authenticates
+# 6. Agent continues with Gmail access
+```
+
+## ✅ Correct - Advanced Configuration
+
+```typescript
+// DO: Configure with object for fine-grained control
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack'],
+  manageConnections: {
+    enable: true, // Allow in-chat authentication
+    callbackUrl: 'https://your-app.com/auth/callback', // Custom OAuth callback
+    waitForConnections: true // Wait for user to complete auth before proceeding
+  }
+});
+
+// With waitForConnections: true
+// Session creation waits until user completes authentication
+// Perfect for workflows where connections are required upfront
+```
+
+```python
+# DO: Configure with object for fine-grained control
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"],
+    manage_connections={
+        "enable": True,  # Allow in-chat authentication
+        "callback_url": "https://your-app.com/auth/callback",  # Custom OAuth callback
+        "wait_for_connections": True  # Wait for user to complete auth before proceeding
+    }
+)
+
+# With wait_for_connections: True
+# Session creation waits until user completes authentication
+# Perfect for workflows where connections are required upfront
+```
+
+## Configuration Options
+
+```typescript
+manageConnections: boolean | {
+  enable?: boolean;           // Enable/disable connection management (default: true)
+  callbackUrl?: string;       // Custom OAuth callback URL
+  waitForConnections?: boolean; // Block until connections complete (default: false)
+}
+```
+
+## When to Use Each Setting
+
+**`manageConnections: true` (Default)**
+- Interactive chat applications
+- User can authenticate on-demand
+- Flexible, user-friendly experience
+
+**`manageConnections: { waitForConnections: true }`**
+- Workflows requiring connections upfront
+- Onboarding flows
+- Critical operations needing guaranteed access
+
+**`manageConnections: false`**
+- Backend automation (no user interaction)
+- Pre-connected accounts only
+- System-to-system integrations
+- ⚠️ Tools WILL FAIL if connections are missing
+
+## Key Insight
+
+With `manageConnections: true`, **you never need to check connections before agent execution**. The agent intelligently prompts users for authentication only when needed. This creates the smoothest user experience.
+
+## Reference
+
+- [Connection Management](https://docs.composio.dev/sdk/typescript/api/tool-router#manageconnections)
+- [Wait for Connections](https://docs.composio.dev/sdk/typescript/api/tool-router#wait-for-connections)

package/.agents/skills/composio/rules/tr-auth-manual.md

@@ -0,0 +1,161 @@
+---
+title: Use Manual Authorization for Explicit Control
+impact: MEDIUM
+description: Control authentication flows explicitly using session.authorize() for onboarding and settings pages
+tags: [authentication, tool-router, authorization, oauth]
+---
+
+# Use Manual Authorization for Explicit Control
+
+Use `session.authorize()` to explicitly control when users authenticate toolkits - perfect for onboarding flows, settings pages, or when you want authentication before starting agent workflows.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Mix auto and manual auth without clear purpose
+const session = await composio.create('user_123', {
+  toolkits: ['gmail'],
+  manageConnections: true // Agent handles auth
+});
+
+// Then immediately force manual auth (redundant)
+await session.authorize('gmail');
+// Agent could have handled this automatically
+```
+
+```python
+# DON'T: Mix auto and manual auth without clear purpose
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail"],
+    manage_connections=True  # Agent handles auth
+)
+
+# Then immediately force manual auth (redundant)
+session.authorize("gmail")
+# Agent could have handled this automatically
+```
+
+## ✅ Correct - Onboarding Flow
+
+```typescript
+// DO: Use manual auth for onboarding before agent starts
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+// Step 1: Create session for onboarding
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack']
+});
+
+// Step 2: Explicitly connect required toolkits during onboarding
+async function onboardUser() {
+  const requiredToolkits = ['gmail', 'slack'];
+
+  for (const toolkit of requiredToolkits) {
+    const connectionRequest = await session.authorize(toolkit, {
+      callbackUrl: 'https://your-app.com/onboarding/callback'
+    });
+
+    console.log(`Connect ${toolkit}:`, connectionRequest.redirectUrl);
+
+    // Wait for user to complete each connection
+    await connectionRequest.waitForConnection();
+    console.log(`✓ ${toolkit} connected`);
+  }
+
+  console.log('Onboarding complete! All toolkits connected.');
+}
+```
+
+```python
+# DO: Use manual auth for onboarding before agent starts
+from composio import Composio
+
+composio = Composio()
+
+# Step 1: Create session for onboarding
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack"]
+)
+
+# Step 2: Explicitly connect required toolkits during onboarding
+async def onboard_user():
+    required_toolkits = ["gmail", "slack"]
+
+    for toolkit in required_toolkits:
+        connection_request = session.authorize(
+            toolkit,
+            callback_url="https://your-app.com/onboarding/callback"
+        )
+
+        print(f"Connect {toolkit}: {connection_request.redirect_url}")
+
+        # Wait for user to complete each connection
+        connection_request.wait_for_connection()
+        print(f"✓ {toolkit} connected")
+
+    print("Onboarding complete! All toolkits connected.")
+```
+
+## ✅ Correct - Settings Page
+
+```typescript
+// DO: Manual auth for connection management in settings
+async function settingsPageHandler(userId: string, toolkit: string) {
+  const session = await composio.create(userId, {
+    toolkits: [toolkit]
+  });
+
+  // User clicked "Connect" button in settings
+  const connectionRequest = await session.authorize(toolkit, {
+    callbackUrl: 'https://your-app.com/settings/callback'
+  });
+
+  // Redirect user to OAuth flow
+  return { redirectUrl: connectionRequest.redirectUrl };
+}
+```
+
+```python
+# DO: Manual auth for connection management in settings
+async def settings_page_handler(user_id: str, toolkit: str):
+    session = composio.create(
+        user_id=user_id,
+        toolkits=[toolkit]
+    )
+
+    # User clicked "Connect" button in settings
+    connection_request = session.authorize(
+        toolkit,
+        callback_url="https://your-app.com/settings/callback"
+    )
+
+    # Redirect user to OAuth flow
+    return {"redirect_url": connection_request.redirect_url}
+```
+
+## When to Use Manual Authorization
+
+**Use `session.authorize()` for:**
+- **Onboarding flows**: Connect required toolkits before user can proceed
+- **Settings pages**: User explicitly manages connections via UI
+- **Pre-authentication**: Ensure critical connections exist before starting workflows
+- **Re-authorization**: Handle expired or revoked connections
+
+**Use `manageConnections: true` (auto) for:**
+- **Interactive agents**: Let agent prompt for auth when needed
+- **Flexible workflows**: User may or may not have connections
+- **Just-in-time auth**: Only authenticate when toolkit is actually used
+
+## Key Difference
+
+- **Manual auth** = You control WHEN authentication happens
+- **Auto auth** = Agent handles authentication ON-DEMAND when tools need it
+
+## Reference
+
+- [session.authorize()](https://docs.composio.dev/sdk/typescript/api/tool-router#authorize)
+- [Authorization Flow](https://docs.composio.dev/sdk/typescript/api/tool-router#authorization-flow)