zilmate 1.7.8 → 1.8.1

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

@@ -0,0 +1,385 @@
+---
+title: Treat Sessions as Short-Lived and Disposable
+impact: CRITICAL
+description: Create new sessions frequently for better logging, debugging, and configuration management
+tags: [tool-router, session, lifecycle, best-practices, logging]
+---
+
+# Treat Sessions as Short-Lived and Disposable
+
+Tool Router sessions should be **short-lived and disposable**. Create new sessions frequently rather than caching or reusing them across different contexts.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Cache and reuse sessions across messages
+class AgentService {
+  private sessionCache = new Map<string, ToolRouterSession>();
+
+  async handleMessage(userId: string, message: string) {
+    // BAD: Reusing cached session
+    let session = this.sessionCache.get(userId);
+
+    if (!session) {
+      session = await composio.create(userId, {
+        toolkits: ['gmail', 'slack']
+      });
+      this.sessionCache.set(userId, session);
+    }
+
+    // ❌ Configuration changes won't be reflected
+    // ❌ Logs mixed across different conversations
+    // ❌ Stale toolkit connections
+    const tools = await session.tools();
+  }
+}
+```
+
+```python
+# DON'T: Cache and reuse sessions across messages
+class AgentService:
+    def __init__(self):
+        self.session_cache = {}
+
+    async def handle_message(self, user_id: str, message: str):
+        # BAD: Reusing cached session
+        if user_id not in self.session_cache:
+            session = composio.create(
+                user_id=user_id,
+                toolkits=["gmail", "slack"]
+            )
+            self.session_cache[user_id] = session
+
+        session = self.session_cache[user_id]
+
+        # ❌ Configuration changes won't be reflected
+        # ❌ Logs mixed across different conversations
+        # ❌ Stale toolkit connections
+        tools = session.tools()
+```
+
+## ✅ Correct - Create New Session Per Message
+
+```typescript
+// DO: Create fresh session for each message
+import { Composio } from '@composio/core';
+import { VercelProvider } from '@composio/vercel';
+
+const composio = new Composio({
+  provider: new VercelProvider()
+});
+
+async function handleUserMessage(
+  userId: string,
+  message: string,
+  config: { toolkits: string[] }
+) {
+  // Create new session for this message
+  const session = await composio.create(userId, {
+    toolkits: config.toolkits,
+    manageConnections: true
+  });
+
+  const tools = await session.tools();
+
+  // Use tools with agent...
+  const response = await runAgent(message, tools);
+
+  // ✅ Fresh configuration
+  // ✅ Clean logs grouped by session
+  // ✅ Latest connection states
+  return response;
+}
+
+// Each message gets a new session
+await handleUserMessage('user_123', 'Check my emails', { toolkits: ['gmail'] });
+await handleUserMessage('user_123', 'Send a slack message', { toolkits: ['slack'] });
+```
+
+```python
+# DO: Create fresh session for each message
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+
+async def handle_user_message(
+    user_id: str,
+    message: str,
+    config: dict
+):
+    # Create new session for this message
+    session = composio.create(
+        user_id=user_id,
+        toolkits=config["toolkits"],
+        manage_connections=True
+    )
+
+    tools = session.tools()
+
+    # Use tools with agent...
+    response = await run_agent(message, tools)
+
+    # ✅ Fresh configuration
+    # ✅ Clean logs grouped by session
+    # ✅ Latest connection states
+    return response
+
+# Each message gets a new session
+await handle_user_message("user_123", "Check my emails", {"toolkits": ["gmail"]})
+await handle_user_message("user_123", "Send a slack message", {"toolkits": ["slack"]})
+```
+
+## ✅ Correct - Single Session Per Conversation (When Config Stable)
+
+```typescript
+// DO: Use one session for entire conversation if config doesn't change
+async function handleConversation(
+  userId: string,
+  conversationId: string,
+  config: { toolkits: string[] }
+) {
+  // Create ONE session for this conversation/thread
+  const session = await composio.create(userId, {
+    toolkits: config.toolkits,
+    manageConnections: true
+  });
+
+  const tools = await session.tools();
+
+  console.log(`Session ${session.sessionId} for conversation ${conversationId}`);
+
+  // Use the same session for all messages in this conversation
+  for await (const message of conversationStream) {
+    const response = await runAgent(message, tools);
+
+    // ✅ All tool executions logged under same session
+    // ✅ Easy to debug entire conversation flow
+    // ✅ Grouped logs in monitoring tools
+  }
+}
+```
+
+```python
+# DO: Use one session for entire conversation if config doesn't change
+async def handle_conversation(
+    user_id: str,
+    conversation_id: str,
+    config: dict
+):
+    # Create ONE session for this conversation/thread
+    session = composio.create(
+        user_id=user_id,
+        toolkits=config["toolkits"],
+        manage_connections=True
+    )
+
+    tools = session.tools()
+
+    print(f"Session {session.session_id} for conversation {conversation_id}")
+
+    # Use the same session for all messages in this conversation
+    async for message in conversation_stream:
+        response = await run_agent(message, tools)
+
+        # ✅ All tool executions logged under same session
+        # ✅ Easy to debug entire conversation flow
+        # ✅ Grouped logs in monitoring tools
+```
+
+## When to Create New Sessions
+
+### ✅ Always Create New Session When:
+
+1. **Configuration Changes**
+   ```typescript
+   // User connects new toolkit
+   if (userConnectedSlack) {
+     // Create new session with updated toolkits
+     const session = await composio.create(userId, {
+       toolkits: ['gmail', 'slack'] // Added slack
+     });
+   }
+   ```
+
+2. **Connected Accounts Change**
+   ```typescript
+   // User disconnected and reconnected Gmail
+   const session = await composio.create(userId, {
+     toolkits: ['gmail'],
+     // Will use latest connection
+   });
+   ```
+
+3. **Different Toolkit Requirements**
+   ```typescript
+   // Message needs different toolkits
+   const emailSession = await composio.create(userId, {
+     toolkits: ['gmail']
+   });
+
+   const codeSession = await composio.create(userId, {
+     toolkits: ['github', 'linear']
+   });
+   ```
+
+4. **New Conversation/Thread**
+   ```typescript
+   // Starting a new conversation thread
+   const session = await composio.create(userId, {
+     toolkits: config.toolkits,
+     // Fresh session for clean log grouping
+   });
+   ```
+
+### ✅ Can Reuse Session When:
+
+1. **Same conversation/thread**
+2. **Configuration unchanged**
+3. **No toolkit connections changed**
+4. **Actively ongoing interaction**
+
+## Benefits of Short-Lived Sessions
+
+### 1. **Clean Log Grouping**
+```typescript
+// All tool executions in one session are grouped together
+const session = await composio.create(userId, {
+  toolkits: ['gmail', 'slack']
+});
+
+// These executions are grouped under session.sessionId
+await agent.run('Check emails'); // Logs: session_abc123
+await agent.run('Send slack message'); // Logs: session_abc123
+
+// Easy to trace entire conversation flow in monitoring
+console.log(`View logs: /sessions/${session.sessionId}`);
+```
+
+### 2. **Fresh Configuration**
+```typescript
+// Always get latest toolkit connections and auth states
+const session = await composio.create(userId, {
+  toolkits: ['gmail']
+});
+
+// ✅ Uses current connected account
+// ✅ Reflects any new connections user made
+// ✅ Picks up toolkit updates
+```
+
+### 3. **Easier Debugging**
+```typescript
+// Session ID becomes your debug trace ID
+console.log(`Processing message in session ${session.sessionId}`);
+
+// All logs tagged with session ID:
+// [session_abc123] Executing GMAIL_FETCH_EMAILS
+// [session_abc123] Executed GMAIL_FETCH_EMAILS
+// [session_abc123] Executing SLACK_SEND_MESSAGE
+
+// Filter all logs for this specific interaction
+```
+
+### 4. **Simplified Error Tracking**
+```typescript
+try {
+  const session = await composio.create(userId, config);
+  const result = await runAgent(message, session);
+} catch (error) {
+  // Session ID in error context
+  logger.error('Agent failed', {
+    sessionId: session.sessionId,
+    userId,
+    error
+  });
+}
+```
+
+## Pattern: Per-Message Sessions
+
+```typescript
+// Recommended pattern for most applications
+export async function handleAgentRequest(
+  userId: string,
+  message: string,
+  toolkits: string[]
+) {
+  // 1. Create fresh session
+  const session = await composio.create(userId, {
+    toolkits,
+    manageConnections: true
+  });
+
+  // 2. Log session start
+  logger.info('Session started', {
+    sessionId: session.sessionId,
+    userId,
+    toolkits
+  });
+
+  try {
+    // 3. Get tools and run agent
+    const tools = await session.tools();
+    const response = await agent.run(message, tools);
+
+    // 4. Log session completion
+    logger.info('Session completed', {
+      sessionId: session.sessionId
+    });
+
+    return response;
+  } catch (error) {
+    // 5. Log session error
+    logger.error('Session failed', {
+      sessionId: session.sessionId,
+      error
+    });
+    throw error;
+  }
+}
+```
+
+## Pattern: Per-Conversation Sessions
+
+```typescript
+// For long-running conversations with stable config
+export class ConversationSession {
+  private session: ToolRouterSession;
+
+  async start(userId: string, config: SessionConfig) {
+    // Create session once for conversation
+    this.session = await composio.create(userId, config);
+
+    logger.info('Conversation session started', {
+      sessionId: this.session.sessionId
+    });
+  }
+
+  async handleMessage(message: string) {
+    // Reuse session for all messages
+    const tools = await this.session.tools();
+    return await agent.run(message, tools);
+  }
+
+  async end() {
+    logger.info('Conversation session ended', {
+      sessionId: this.session.sessionId
+    });
+  }
+}
+```
+
+## Key Principles
+
+1. **Don't cache sessions** - Create new ones as needed
+2. **Session = Unit of work** - One session per task or conversation
+3. **Short-lived is better** - Fresh state, clean logs, easier debugging
+4. **Session ID = Trace ID** - Use for log correlation and debugging
+5. **Create on demand** - No need to pre-create or warm up sessions
+
+## Reference
+
+- [Tool Router Sessions](https://docs.composio.dev/sdk/typescript/api/tool-router#creating-sessions)
+- [Session Properties](https://docs.composio.dev/sdk/typescript/api/tool-router#session-properties)
+- [Best Practices](https://docs.composio.dev/sdk/typescript/api/tool-router#best-practices)

package/.agents/skills/composio/rules/tr-toolkit-query.md

@@ -0,0 +1,135 @@
+---
+title: Query Toolkit Connection States for UI
+impact: MEDIUM
+description: Use session.toolkits() to build connection management UIs showing which toolkits are connected
+tags: [tool-router, toolkits, connections, ui]
+---
+
+# Query Toolkit Connection States for UI
+
+Use `session.toolkits()` to check connection status and build UIs showing which toolkits are connected. With `manageConnections: true`, agents handle missing connections automatically.
+
+## ❌ Incorrect
+
+```typescript
+// DON'T: Build UI without showing connection status
+async function showToolkits(session) {
+  // Just show toolkit names with no status
+  const toolkits = ['Gmail', 'Slack', 'GitHub'];
+
+  return toolkits.items.map(name => ({
+    name,
+    // Missing: connection status, auth button, etc.
+  }));
+}
+```
+
+```python
+# DON'T: Build UI without showing connection status
+def show_toolkits(session):
+    # Just show toolkit names with no status
+    toolkits = ["Gmail", "Slack", "GitHub"]
+
+    return [{"name": name} for name in toolkits]
+    # Missing: connection status, auth button, etc.
+```
+
+## ✅ Correct
+
+```typescript
+// DO: Query connection states to build connection UI
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+const session = await composio.create('user_123', {
+  toolkits: ['gmail', 'slack', 'github'],
+  manageConnections: true // Agent handles auth automatically
+});
+
+// Get connection states for building UI
+const { items } = await session.toolkits();
+
+// Build connection management UI
+const connectionUI = items.map(toolkit => ({
+  slug: toolkit.slug,
+  name: toolkit.name,
+  logo: toolkit.logo,
+  isConnected: toolkit.connection?.isActive || false,
+  status: toolkit.connection?.connectedAccount?.status,
+  // Show "Connect" button if not connected
+  needsAuth: !toolkit.connection?.isActive && !toolkit.isNoAuth
+}));
+
+console.log('Connection Status:', connectionUI);
+// Use this to render connection cards in your UI
+```
+
+```python
+# DO: Query connection states to build connection UI
+from composio import Composio
+
+composio = Composio()
+session = composio.create(
+    user_id="user_123",
+    toolkits=["gmail", "slack", "github"],
+    manage_connections=True  # Agent handles auth automatically
+)
+
+# Get connection states for building UI
+result = session.toolkits()
+
+# Build connection management UI
+connection_ui = []
+for toolkit in result.items:
+    connection_ui.append({
+        "slug": toolkit.slug,
+        "name": toolkit.name,
+        "logo": toolkit.logo,
+        "is_connected": toolkit.connection.is_active if toolkit.connection else False,
+        "status": toolkit.connection.connected_account.status if toolkit.connection.connected_account else None,
+        # Show "Connect" button if not connected
+        "needs_auth": not (toolkit.connection.is_active if toolkit.connection else False) and not toolkit.is_no_auth
+    })
+
+print(f"Connection Status: {connection_ui}")
+# Use this to render connection cards in your UI
+```
+
+## Response Structure
+
+```typescript
+interface ToolkitConnectionState {
+  slug: string;              // 'gmail'
+  name: string;              // 'Gmail'
+  logo?: string;             // 'https://...'
+  isNoAuth: boolean;         // true if no auth needed
+  connection: {
+    isActive: boolean;       // Is connection active?
+    authConfig?: {
+      id: string;            // Auth config ID
+      mode: string;          // 'OAUTH2', 'API_KEY', etc.
+      isComposioManaged: boolean;
+    };
+    connectedAccount?: {
+      id: string;            // Connected account ID
+      status: string;        // 'ACTIVE', 'INVALID', etc.
+    };
+  };
+}
+```
+
+## Use Cases
+
+- **Build connection UI**: Display connected/disconnected state with auth buttons
+- **Settings pages**: Let users view and manage their connections
+- **Onboarding flows**: Show which toolkits to connect during setup
+- **Status dashboards**: Monitor connection health across toolkits
+
+## Important Note
+
+With `manageConnections: true` (default), you don't need to check connections before agent execution - the agent will prompt users to authenticate when needed. Use `session.toolkits()` primarily for building user-facing connection management UIs.
+
+## Reference
+
+- [session.toolkits()](https://docs.composio.dev/sdk/typescript/api/tool-router#toolkits)
+- [Toolkit Connection State](https://docs.composio.dev/sdk/typescript/api/tool-router#toolkitconnectionstate)