zilmate 1.7.8 → 1.8.0

package/.agents/skills/composio/rules/app-user-context.md

@@ -0,0 +1,222 @@
+---
+title: User Context and ID Patterns for Applications
+impact: HIGH
+description: Critical patterns for user identification, multi-tenancy, and data isolation in production applications
+tags: [user-context, security, multi-tenancy, isolation, production]
+---
+
+# User Context and ID Patterns
+
+Every Composio operation requires a `userId` parameter for security and data isolation. Users can only access their own connected accounts.
+
+## The 'default' User ID
+
+`default` refers to your project's default account.
+
+**Only use 'default' for:**
+- Testing and development
+- Single-user applications
+- Internal tools with no external users
+
+**Never use in production multi-user apps** - it bypasses user isolation.
+
+## Production User ID Patterns
+
+### Database UUID (Recommended)
+
+Use your database's primary key:
+
+```typescript
+const userId = user.id; // "550e8400-e29b-41d4-a716-446655440000"
+
+await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: userId,
+  arguments: { owner: 'example', repo: 'repo' },
+});
+```
+
+**Pros:** Stable, immutable, already exists, no mapping needed
+
+### External Auth ID (Acceptable)
+
+Use IDs from Auth0, Firebase, etc:
+
+```typescript
+const userId = user.externalId; // "auth0|507f1f77bcf86cd799439011"
+// Or with prefix
+const userId = `user_${user.id}`; // "user_12345"
+```
+
+**Pros:** Works with external auth, human-readable, allows namespacing
+**Cons:** May require mapping, usernames can change
+
+### Email (Not Recommended)
+
+```typescript
+const userId = user.email; // "user@example.com"
+```
+
+**Only use when:**
+- Email is guaranteed immutable
+- No other unique identifier available
+- SSO requires email-based identification
+
+**Cons:** Emails can change, privacy concerns
+
+## Organization-Based Applications
+
+For team/org-wide tool access, use organization ID as `userId`:
+
+```typescript
+// All users in org share same connected accounts
+const userId = organization.id; // "org_550e8400..."
+
+await composio.tools.execute('SLACK_SEND_MESSAGE', {
+  userId: userId, // organization ID, not individual user
+  arguments: { channel: '#general', text: 'Team message' },
+});
+```
+
+**Use organization IDs when:**
+- Team/org tools (Slack, MS Teams, Jira)
+- Enterprise apps with IT admin connections
+- Shared resources across users
+- Role-based access at org level
+
+**Example:**
+
+```typescript
+// Admin connects Slack for entire org
+async function connectOrgToSlack(orgId: string) {
+  const request = await composio.connectedAccounts.link(orgId, 'slack');
+  return request.redirectUrl;
+}
+
+// Any user in org can use connected tools
+async function sendMessage(orgId: string, message: string) {
+  return await composio.tools.execute('SLACK_SEND_MESSAGE', {
+    userId: orgId,
+    arguments: { channel: '#general', text: message },
+  });
+}
+
+// Check org connections
+async function listOrgConnections(orgId: string) {
+  return await composio.connectedAccounts.list({
+    userIds: [orgId],
+  });
+}
+```
+
+## Shared vs. Isolated Connections
+
+### Isolated (User-Level)
+
+Each user has their own connections:
+
+```typescript
+await composio.connectedAccounts.link('user_123', 'github_config');
+await composio.connectedAccounts.link('user_456', 'github_config');
+
+// Each execution uses that user's account
+await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'user_123', // Uses user_123's GitHub
+  arguments: { ... },
+});
+```
+
+**Use for:** Personal integrations, individual credentials, privacy-critical
+
+### Shared (Organization-Level)
+
+All users share organization connections:
+
+```typescript
+await composio.connectedAccounts.link('org_acme', 'github_config');
+
+// All org users use same connection
+await composio.tools.execute('GITHUB_GET_REPO', {
+  userId: 'org_acme', // All users share
+  arguments: { ... },
+});
+```
+
+**Use for:** Org-wide access, centralized credentials, simplified administration
+
+## Security Best Practices
+
+### Never Expose User IDs to Frontend
+
+```typescript
+// ❌ DON'T: Allow frontend to specify userId
+app.post('/execute-tool', async (req, res) => {
+  await composio.tools.execute(req.body.tool, {
+    userId: req.body.userId, // SECURITY RISK
+    arguments: req.body.arguments,
+  });
+});
+
+// ✅ DO: Derive userId from authenticated session
+app.post('/execute-tool', async (req, res) => {
+  const userId = req.user.id; // From auth session
+  await composio.tools.execute(req.body.tool, {
+    userId: userId,
+    arguments: req.body.arguments,
+  });
+});
+```
+
+### Validate User Ownership
+
+```typescript
+async function executeForUser(authenticatedUserId, targetUserId, tool, args) {
+  if (authenticatedUserId !== targetUserId) {
+    throw new Error('Unauthorized');
+  }
+  return await composio.tools.execute(tool, {
+    userId: targetUserId,
+    arguments: args,
+  });
+}
+```
+
+## Common Patterns
+
+### Express Middleware
+
+```typescript
+app.use((req, res, next) => {
+  req.userId = req.user.id; // From authenticated session
+  next();
+});
+
+app.post('/execute-tool', async (req, res) => {
+  const result = await composio.tools.execute(req.body.tool, {
+    userId: req.userId,
+    arguments: req.body.arguments,
+  });
+  res.json(result);
+});
+```
+
+### Debug User Context
+
+```typescript
+const accounts = await composio.connectedAccounts.list({
+  userIds: [userId],
+});
+
+console.log(`User ${userId} has ${accounts.items.length} accounts`);
+accounts.items.forEach(account => {
+  console.log(`- ${account.toolkit.slug}: ${account.status}`);
+});
+```
+
+## Key Points
+
+- **Use database UUIDs** - Most stable and reliable
+- **Never expose userId** - Always derive from authenticated session
+- **Validate ownership** - Ensure users only access their data
+- **Use consistent format** - Pick one pattern and stick to it
+- **Organization IDs** - For team-wide tool access
+- **Handle changes gracefully** - Maintain mapping if IDs can change

package/.agents/skills/composio/rules/building-with-composio.md

@@ -0,0 +1,134 @@
+---
+title: Building Apps and Agents with Composio
+impact: HIGH
+description: SDK-based guide for building AI agents and applications that integrate with external tools via Composio
+tags: [composio, sdk, agents, apps, typescript, python, frameworks]
+---
+
+# Building Apps and Agents with Composio
+
+Use the Composio SDK to build AI agents, chat apps, and backend services that integrate with 200+ external tools.
+
+## Project Setup
+
+Run inside your project directory to initialize and store the API key:
+```bash
+composio init
+```
+
+## Install the SDK
+
+**TypeScript**
+```bash
+pnpm install @composio/core@latest
+```
+
+Provider packages for agentic frameworks:
+- `@composio/vercel` — Vercel AI SDK
+- `@composio/openai-agents` — OpenAI Agents
+- `@composio/langchain` — LangChain
+- `@composio/mastra` — Mastra
+- `@composio/claude-agent-sdk` — Claude Agent SDK
+
+**Python**
+```bash
+pip install composio
+```
+
+Provider packages for agentic frameworks:
+- `composio-openai-agents` — OpenAI Agents
+- `composio-langchain` — LangChain
+- `composio-langgraph` — LangGraph
+- `composio-crewai` — CrewAI
+- `composio-claude-agent-sdk` — Claude Agent SDK
+- `composio-google-adk` — Google ADK
+
+Pass the provider into the Composio constructor:
+```typescript
+import { Composio } from '@composio/core'
+import { VercelProvider } from '@composio/vercel'
+
+const composio = new Composio({ provider: new VercelProvider() })
+```
+```python
+from composio import Composio
+from composio_langchain import LangchainProvider
+
+composio = Composio(provider=LangchainProvider())
+```
+
+---
+
+## Building Agents
+
+Use Tool Router to create isolated MCP sessions per user with scoped tool access and automatic auth management. Compatible with any AI framework.
+
+### Session Management
+- [User ID Best Practices](tr-userid-best-practices.md) — choose user IDs for security and isolation
+- [Creating Basic Sessions](tr-session-basic.md) — initialize Tool Router sessions
+- [Session Lifecycle](tr-session-lifecycle.md) — when to create vs reuse sessions
+- [Session Configuration](tr-session-config.md) — configure toolkits, tools, and filters
+- [Using Native Tools](tr-mcp-vs-native.md) — prefer native tools for performance and control
+
+### Authentication Flows
+- [Auto Authentication in Chat](tr-auth-auto.md) — enable in-chat auth flows
+- [Manual Authorization](tr-auth-manual.md) — use `session.authorize()` for explicit flows
+- [Connection Management](tr-auth-connections.md) — configure `manageConnections`, `waitForConnections`, and callback URLs
+
+### Toolkit Querying & UI Building
+- [Building Chat UIs](tr-building-chat-ui.md) — toolkit selection, connection management, and session handling
+- [Query Toolkit States](tr-toolkit-query.md) — use `session.toolkits()` to check connections and build connection UIs
+
+### Framework Integrations
+- [Framework Integration](tr-framework-integration.md) — LangChain, OpenAI Agents, general patterns
+- [Vercel AI SDK](tr-framework-ai-sdk.md) — native tools, MCP, and React
+- [Mastra](tr-framework-mastra.md) — Mastra agents with native tools and MCP
+
+### Event-Driven Agents (Triggers)
+- [Creating Triggers](triggers-create.md) — set up trigger instances for real-time events
+- [Subscribing to Events](triggers-subscribe.md) — listen to trigger events in real-time
+- [Webhook Verification](triggers-webhook.md) — verify and process incoming webhook payloads
+- [Managing Triggers](triggers-manage.md) — enable, disable, update, and list triggers
+
+---
+
+## Building Apps
+
+Direct tool execution without agent frameworks — full control over auth, execution, and resource management. If building apps with agentic abilities, make sure the auth configs match the session's auth configs.
+
+### Core Operations
+- [Fetching Tools](app-fetch-tools.md) — get tools with filters and search
+- [Direct Tool Execution](app-execute-tools.md) — execute tools manually with parameters
+- [Tool Version Management](app-tool-versions.md) — version pinning strategies for stability
+
+### Resource Management
+- [Connected Accounts CRUD](app-connected-accounts.md) — create, read, update, delete connected accounts
+- [Auth Config Management](app-auth-configs.md) — manage authentication configurations
+- [Toolkit Management](app-toolkits.md) — query toolkits, categories, and auth requirements
+- [Auth Popup UI](app-auth-popup-ui.md) — build popup-based OAuth flows
+
+### Extensibility
+- [Tool Modifiers](app-modifiers.md) — schema modification and execution hooks for logging and modifications
+
+### User Context & Multi-Tenancy
+- [User ID Patterns](app-user-context.md) — user vs organization IDs, shared vs isolated connections
+
+### Event-Driven Applications
+- [Creating Triggers](triggers-create.md) — set up trigger instances
+- [Subscribing to Events](triggers-subscribe.md) — listen to events in real-time
+- [Webhook Verification](triggers-webhook.md) — verify incoming webhooks
+- [Managing Triggers](triggers-manage.md) — enable, disable, update triggers
+
+---
+
+## Verify Tool Slugs Before Use
+
+Never guess toolkit, tool, or trigger names. Always verify:
+
+```bash
+composio search "send email"
+composio manage tools info "GMAIL_SEND_EMAIL"
+composio manage toolkits info "gmail"
+```
+
+Using incorrect slugs causes runtime errors.

package/.agents/skills/composio/rules/composio-cli.md

@@ -0,0 +1,223 @@
+---
+title: Composio CLI Guide
+impact: HIGH
+description: Use the Composio CLI to take actions on external apps directly - no code needed
+tags: [cli, composio, tools, toolkits, auth, connected-accounts, direct-use]
+---
+
+# Composio CLI Guide
+
+Use the Composio CLI to search, connect, and execute tools directly — no code writing required. Ideal for agents taking actions on behalf of the user.
+
+## Prerequisites (first-time setup)
+
+If the CLI is not installed or the user is not authenticated:
+
+```bash
+# Install
+curl -fsSL https://composio.dev/install | bash
+composio --version   # verify
+
+# Authenticate
+composio login       # OAuth flow; interactive org/project picker after login (use -y to skip)
+composio whoami      # verify org_id, project_id, user_id (API keys are never displayed)
+# Run upgrade in case you run into errors or starting with a new project
+composio upgrade
+```
+
+> **Note**: Use `whoami` only to verify login status — do not hardcode these values in code. `whoami` shows hints for `composio manage orgs switch` and `composio init` when relevant.
+
+**Login behavior**: By default, `composio login` shows an interactive org/project picker after OAuth. Use `composio login -y` to skip the picker and use session defaults. JSON output is emitted only after the picker finishes (or immediately with `-y`), so piped/scripted usage gets the correct `org_id` and `project_id`.
+
+**Agent login (no direct browser access)**: For agents that cannot open a browser for the user, use a two-step flow:
+
+1. **Get login URL and session key** — Print login URL and JSON (jq-parseable) then exit without opening browser or waiting:
+   ```bash
+   composio login --no-wait | jq
+   ```
+   Share the login URL with the agent's user to complete login in their browser.
+
+2. **Complete login with session key** — Use the `cli_key` from the previous output to check if the user has logged in:
+   ```bash
+   composio login --key "<cli_key>"
+   ```
+   Without `--no-wait`: polls until the session is linked (same as browser flow after printing URL).
+   With `--no-wait`: checks once and fails if not linked. For agents, once the user completes login, run with `--no-wait` to avoid blocking.
+
+## Primary Workflow: search → link → execute
+
+### Step 1 — Find the right tool
+
+```bash
+composio search "send an email"
+composio search "create github issue"
+composio search "post slack message"
+```
+
+The search results include connection status, so you can see immediately if the user is already connected to the required app.
+
+> **Important**: Do not trim the output of `composio search` (e.g. with `head`). Use the full results to pick the right tool — truncating can hide the best match.
+
+### Step 2 — Connect an account (if needed)
+
+If the user is not connected to the app, link their account:
+
+```bash
+composio link gmail
+composio link github
+composio link slack
+```
+
+This opens an OAuth flow or prompts for credentials. Only needed once per app. By default, `composio link` waits until the connected account is ACTIVE (opens browser, polls). Use `--no-wait` for scripted or agent usage: it prints link info and JSON to stdout (JQ-friendly) and exits immediately. Output includes `status`, `connected_account_id`, `redirect_url`, and `toolkit`.
+
+### Step 3 — Execute the tool
+
+```bash
+composio execute GMAIL_SEND_EMAIL --data '{"recipient_email":"you@example.com","subject":"Hello","body":"Test"}'
+composio execute GITHUB_CREATE_AN_ISSUE --data '{"owner":"acme","repo":"my-repo","title":"Bug report"}'
+```
+To see a tool's input parameters before executing:
+```bash
+composio execute GMAIL_SEND_EMAIL --help
+```
+
+### Step 4 — Listen for events (optional)
+
+```bash
+composio listen
+```
+
+Streams real-time trigger events to the terminal.
+
+---
+
+## Tips for Agents
+
+- **All commands output JSON** — pipe to `jq` for filtering and extraction
+- **Agent login** — When the agent has no direct browser access, use `composio login --no-wait` to get the URL and key, share the URL with the user, then `composio login --key <key> --no-wait` once they complete login
+- **Parallel execution** — use `&` and `wait` or shell scripts for complex multi-step tasks
+- The default user context is the project's `test_user_id`. Pass `--user-id <id>` to act on behalf of a specific user.
+
+```bash
+composio execute GMAIL_SEND_EMAIL --user-id "user_123" --data '{"recipient_email":"them@example.com","subject":"Hi"}'
+```
+
+## Best Practices
+
+1. **Use `jq` for JSON** — Pipe CLI output to `jq` for filtering and extraction instead of parsing raw JSON.
+2. **Control output at source** — When fetching large amounts of data, use the tool's filters (if supported) to limit what is returned.
+3. **Offload analysis** — After understanding the schema, use inline bash scripts for heavy data analysis instead of manual inspection. Avoid using composio SDK for personal usecases only use the SDKs when building apps.
+4. **Parallelize independent actions** — For tools/actions that don't depend on each other, run them in parallel with `&` and `wait`. Use `xargs -P` or `parallel` only when the backend can handle the load.
+5. **Avoid large terminal dumps** — Filter, search, and summarize instead of outputting full datasets:
+   - Quick text filtering: `grep -E`, `rg` (ripgrep), `awk`, `sed`
+   - Summarize: `sort | uniq -c | sort -nr`, `wc -l`, `head`, `tail`
+   - For large output: `less`, `lnav` (logs), `tail -f` for streaming
+6. **Minimize file creation** — Use ephemeral files only when needed; create files only when the user explicitly asks.
+7. **Respect rate limits** — Be mindful of pagination and API/CLI rate limits when parallelizing.
+8. **Never invent tool slugs or app names** — Only use tools returned by `composio search`. For app names, use `composio manage toolkits info <slug>` or `composio manage tools info <tool>` to verify.
+9. **Do not trim `composio search` output** — Never pipe search results through `head`, `tail`, or similar. Use the full output to find the best tool match.
+
+---
+
+## Advanced Commands
+
+### Discover Tools (when search isn't enough)
+
+```bash
+# List all toolkits
+composio manage toolkits list
+
+# Get details about a specific toolkit
+composio manage toolkits info "gmail"
+
+# List tools in a toolkit
+composio manage tools list --toolkits "gmail"
+
+# Get a tool's full schema
+composio manage tools info "GMAIL_SEND_EMAIL"
+```
+
+### Connected Accounts
+
+```bash
+# List active connections
+composio manage connected-accounts list --status ACTIVE
+
+# Link an account (full form with options)
+composio manage connected-accounts link --auth-config "ac_..." --user-id "user_123"
+
+# Delete a connection
+composio manage connected-accounts delete <id>
+```
+
+### Auth Configs
+
+> Only needed when building apps with custom OAuth credentials. For personal use and agents, `composio link` handles this automatically.
+
+```bash
+composio manage auth-configs list --toolkits "gmail"
+composio manage auth-configs create
+composio manage auth-configs info <id>
+composio manage auth-configs delete <id>
+```
+
+### Triggers
+
+```bash
+# List available trigger types
+composio manage triggers list
+composio manage triggers info "GMAIL_NEW_GMAIL_MESSAGE"
+
+# Manage trigger instances
+composio manage triggers create <trigger-name>
+composio manage triggers enable <id>
+composio manage triggers disable <id>
+composio manage triggers status
+```
+
+### Debugging & Logs
+
+```bash
+# View recent tool executions
+composio manage logs tools
+
+# Get detailed logs for a specific execution
+composio manage logs tools "log_abc123"
+
+# Monitor trigger events
+composio manage logs triggers
+```
+---
+
+## jq Examples
+
+```bash
+# Extract toolkit slugs
+composio manage toolkits list | jq -r '.[].slug'
+
+# Get tool names from a toolkit
+composio manage tools list --toolkits "gmail" | jq -r '.[].name'
+
+# Filter active connections
+composio manage connected-accounts list --status ACTIVE | jq -r '.[].id'
+
+# Extract login URL and key from agent login flow
+composio login --no-wait | jq -r '.login_url'
+composio login --no-wait | jq -r '.key'
+```
+
+## Command Help
+
+Every command supports `--help` for detailed options:
+
+```bash
+composio --help
+composio login --help
+composio search --help
+composio execute --help
+composio link --help
+composio listen --help
+composio manage tools --help
+composio manage toolkits --help
+composio manage triggers --help
+```