zilmate 1.7.8 → 1.8.0

package/.agents/skills/composio/rules/app-modifiers.md

@@ -0,0 +1,148 @@
+---
+title: Tool Modifiers
+impact: MEDIUM
+description: Advanced patterns for customizing tool behavior with schema modifications and execution hooks
+tags: [modifiers, hooks, customization, schema, execution]
+---
+
+# Tool Modifiers
+
+Modifiers customize tool behavior through schema transformations, pre-execution hooks, and post-execution hooks.
+
+## Schema Modification
+
+Customize tool descriptions or parameters at fetch time:
+
+```typescript
+const tools = await composio.tools.get(
+  'default',
+  { toolkits: ['github'] },
+  {
+    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+      // Enhance descriptions for AI
+      schema.description = `[Enhanced] ${schema.description}`;
+
+      // Customize specific parameters
+      if (toolSlug === 'GITHUB_GET_REPO') {
+        schema.inputParameters.properties.owner.description =
+          'GitHub organization or user name (e.g., "composio")';
+      }
+
+      return schema;
+    },
+  }
+);
+```
+
+## Pre-Execution Hooks (beforeExecute)
+
+Modify parameters before execution:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_REPO',
+  {
+    userId: 'default',
+    arguments: { owner: 'Composio', repo: 'sdk' },
+  },
+  {
+    beforeExecute: ({ toolSlug, params }) => {
+      // Normalize inputs
+      params.arguments.owner = params.arguments.owner.toLowerCase();
+
+      // Add defaults
+      params.arguments.branch = params.arguments.branch || 'main';
+
+      return params;
+    },
+  }
+);
+```
+
+**Common uses:**
+- Parameter validation and normalization
+- Adding default values
+- Logging and tracing
+
+## Post-Execution Hooks (afterExecute)
+
+Transform outputs after execution:
+
+```typescript
+const result = await composio.tools.execute(
+  'GITHUB_GET_REPO',
+  {
+    userId: 'default',
+    arguments: { owner: 'composio', repo: 'sdk' },
+  },
+  {
+    afterExecute: ({ result }) => {
+      if (result.successful) {
+        // Remove sensitive data
+        delete result.data.token;
+
+        // Add metadata
+        result.data.fetchedAt = new Date().toISOString();
+      }
+
+      return result;
+    },
+  }
+);
+```
+
+**Common uses:**
+- Filtering sensitive data
+- Data transformation and formatting
+- Adding metadata
+
+## Common Patterns
+
+### Sensitive Data Filtering
+
+```typescript
+const filterSensitive = ({ result }) => {
+  if (result.successful) {
+    ['token', 'secret', 'password', 'api_key'].forEach(field => {
+      delete result.data[field];
+    });
+  }
+  return result;
+};
+```
+
+### Logging & Monitoring
+
+```typescript
+const monitor = {
+  beforeExecute: ({ toolSlug, params }) => {
+    console.log(`[START] ${toolSlug}`, params.arguments);
+    return params;
+  },
+  afterExecute: ({ toolSlug, result }) => {
+    console.log(`[END] ${toolSlug} - Success: ${result.successful}`);
+    return result;
+  },
+};
+```
+
+### Reusable Modifiers
+
+```typescript
+const addTimestamps = ({ result }) => {
+  if (result.successful) result.data.executedAt = new Date().toISOString();
+  return result;
+};
+
+// Use in multiple executions
+await composio.tools.execute('GITHUB_GET_REPO', { ... }, {
+  afterExecute: addTimestamps
+});
+```
+
+## Key Points
+
+- Schema modifiers apply at fetch time, execution modifiers at runtime
+- Always return modified object (don't just mutate)
+- Modifiers are synchronous - keep operations lightweight
+- Must pass modifiers to each execute() call (not persisted)

package/.agents/skills/composio/rules/app-tool-versions.md

@@ -0,0 +1,343 @@
+---
+title: Tool Version Management
+impact: HIGH
+description: Critical strategies for version pinning to ensure workflow stability and prevent runtime errors in production
+tags: [tools, versions, stability, production, pinning]
+---
+
+# Tool Version Management
+
+> **⚠️ CRITICAL:** Never assume or make up toolkit names or version numbers. Always verify before using:
+> - Use `composio manage toolkits list` / `composio manage toolkits info "..."` to discover toolkits (CLI) or `composio.toolkits.get()` (SDK)
+> - Use `composio manage toolkits info "..."` to view available versions (CLI) or `composio.toolkits.get('toolkit_name')` (SDK) or check the [dashboard](https://platform.composio.dev)
+> - Using non-existent toolkit slugs or versions will cause runtime errors
+>
+> See [Composio CLI Reference](./composio-cli.md) for discovery commands.
+
+Tool versions are critical for workflow stability. When manually executing tools, a specific version is **required** to prevent argument mismatches when tool schemas change.
+
+## Why Version Pinning Matters
+
+- **Tool schemas evolve**: Tool argument schemas can change between versions
+- **Prevent runtime errors**: Using `'latest'` in workflows causes errors when tools update
+- **Workflow stability**: Pinned versions ensure predictable behavior
+- **Production safety**: Version validation prevents schema mismatch issues
+
+## Three Version Management Strategies
+
+### Strategy 1: Explicit Version in Execute Call (Recommended for One-off Executions)
+
+Specify the version directly in the execute call:
+
+```typescript
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '12082025_00', // Explicit version for this tool
+});
+```
+
+**Pros:**
+- Clear version visibility at execution point
+- Different versions for different tools
+- Easy to update individual tool versions
+
+**Cons:**
+- Repetitive if executing same tool multiple times
+- Version scattered across codebase
+
+**Use when:**
+- One-off tool executions
+- Testing different tool versions
+- Tool versions need to differ within the same app
+
+### Strategy 2: Configure Toolkit Versions at Initialization (Recommended for Production)
+
+Configure versions once at SDK initialization:
+
+```typescript
+const composio = new Composio({
+  toolkitVersions: {
+    github: '12082025_00',
+    slack: '10082025_01',
+    gmail: '15082025_02'
+  }
+});
+
+// Execute without version parameter - uses pinned version from config
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  // Uses github: '12082025_00' from initialization
+});
+```
+
+**Pros:**
+- Centralized version management
+- Clean execution calls
+- Easy to update all tools from a toolkit
+- Best for production environments
+
+**Cons:**
+- All tools from a toolkit use the same version
+- Requires initialization configuration
+
+**Use when:**
+- Building production applications
+- Managing multiple tools from the same toolkit
+- Want centralized version control
+
+### Strategy 3: dangerouslySkipVersionCheck (NOT Recommended for Production)
+
+Bypass version validation entirely:
+
+```typescript
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  dangerouslySkipVersionCheck: true, // Uses 'latest' version
+});
+```
+
+**⚠️ Warning:** This bypasses version validation and uses `'latest'` version. Can lead to:
+- Unexpected behavior when tool schemas change
+- Argument mismatches in production
+- Runtime errors when tools are updated
+- Workflow breakage without notice
+
+**Only use for:**
+- Development and testing
+- Prototyping
+- When you explicitly want to test latest versions
+
+**NEVER use in:**
+- Production environments
+- Critical workflows
+- User-facing applications
+
+## Version Format
+
+Versions follow the format: `DDMMYYYY_XX`
+
+Examples:
+- `12082025_00` - August 12, 2025, revision 00
+- `10082025_01` - August 10, 2025, revision 01
+- `15082025_02` - August 15, 2025, revision 02
+
+## Finding Available Versions
+
+**⚠️ CRITICAL: Never assume or guess version numbers. Always verify that a version exists before using it.**
+
+### Method 1: Use SDK to List Available Versions
+
+Fetch toolkit metadata to see all available versions:
+
+```typescript
+// Get available versions for a specific toolkit
+const toolkit = await composio.toolkits.get('github');
+console.log('Available versions:', toolkit.versions);
+console.log('Latest version:', toolkit.latestVersion);
+
+// For Gmail
+const gmailToolkit = await composio.toolkits.get('gmail');
+console.log('Gmail versions:', gmailToolkit.versions);
+
+// For Slack
+const slackToolkit = await composio.toolkits.get('slack');
+console.log('Slack versions:', slackToolkit.versions);
+```
+
+### Method 2: Check Dashboard
+
+View versions and changelog on the [Composio dashboard](https://platform.composio.dev):
+- Navigate to Toolkits section
+- Select the specific toolkit (e.g., GitHub, Gmail, Slack)
+- View available versions and their changes
+
+### How to Use Versions Correctly
+
+Once you've found available versions, choose a specific version to test, then pin it in your configuration:
+
+**Step 1: List available versions**
+```typescript
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Available versions:', githubToolkit.versions);
+// Example output: ['12082025_00', '10082025_01', '08082025_00']
+```
+
+**Step 2: Choose and test a specific version**
+```typescript
+// Test with a specific version from the list
+const composio = new Composio({
+  toolkitVersions: {
+    github: '12082025_00', // Choose a specific version to test
+  }
+});
+```
+
+**Step 3: Pin the tested version in production**
+```typescript
+// After testing, pin the version in your production config
+const composio = new Composio({
+  toolkitVersions: {
+    github: '12082025_00',  // Pinned version that you've tested
+    slack: '10082025_01',   // Pinned version that you've tested
+  }
+});
+```
+
+### Using Environment Variables
+
+You can also set toolkit versions using environment variables:
+
+```bash
+# Set specific versions for individual toolkits
+export COMPOSIO_TOOLKIT_VERSION_GITHUB=12082025_00
+export COMPOSIO_TOOLKIT_VERSION_SLACK=10082025_01
+export COMPOSIO_TOOLKIT_VERSION_GMAIL=15082025_00
+```
+
+Then initialize Composio without specifying `toolkitVersions`:
+
+```typescript
+const composio = new Composio({
+  apiKey: 'your-api-key'
+  // Will automatically use environment variables
+});
+```
+
+### IMPORTANT: Don't Auto-Use Latest Version
+
+❌ **DON'T DO THIS:**
+```typescript
+// This defeats the purpose of version pinning!
+const githubToolkit = await composio.toolkits.get('github');
+const composio = new Composio({
+  toolkitVersions: {
+    github: githubToolkit.latestVersion, // Always uses latest - no pinning!
+  }
+});
+
+// Never use made-up version numbers either!
+const composio = new Composio({
+  toolkitVersions: {
+    github: '01012025_00', // Random version - might not exist!
+    slack: '25122024_99',  // Made up version - will fail!
+  }
+});
+```
+
+✅ **DO THIS:**
+```typescript
+// 1. List available versions to find valid options
+const githubToolkit = await composio.toolkits.get('github');
+console.log('Available versions:', githubToolkit.versions);
+
+// 2. Choose and test a specific version from the list
+// 3. Pin that tested version in your code or environment variables
+const composio = new Composio({
+  toolkitVersions: {
+    github: '12082025_00',  // Specific tested version
+    slack: '10082025_01',   // Specific tested version
+  }
+});
+```
+
+**Why this matters:**
+- Automatically using `latestVersion` means your app always uses the newest version, defeating the purpose of pinning
+- Version pinning is about locking to a specific, tested version for stability
+- When you're ready to upgrade, you explicitly choose and test a new version before deploying
+
+## Version Migration Strategy
+
+When updating tool versions:
+
+1. **Test in development first**
+   ```typescript
+   // Dev environment
+   const devComposio = new Composio({
+     toolkitVersions: { github: '20082025_00' } // New version
+   });
+   ```
+
+2. **Validate schema changes**
+   ```typescript
+   const oldTool = await composio.tools.get('default', 'GITHUB_GET_ISSUES');
+   const newTool = await composio.tools.get('default', 'GITHUB_GET_ISSUES');
+   // Compare schemas before migrating
+   ```
+
+3. **Update gradually**
+   - Update one toolkit at a time
+   - Monitor for errors
+   - Roll back if issues occur
+
+4. **Update production**
+   ```typescript
+   // Production environment
+   const prodComposio = new Composio({
+     toolkitVersions: { github: '20082025_00' } // Deploy new version
+   });
+   ```
+
+## Best Practices
+
+1. **Always pin versions in production**: Never use `'latest'` or skip version checks
+2. **Use initialization-level config**: Centralize version management for maintainability
+3. **Document version choices**: Comment why specific versions are used
+4. **Test version updates**: Validate in dev before deploying to production
+5. **Monitor after updates**: Watch for errors after version changes
+6. **Keep versions consistent**: Use same version across environments when possible
+7. **Version control your config**: Track toolkit versions in your repository
+
+## Common Patterns
+
+### Environment-based version config
+
+```typescript
+const toolkitVersions = {
+  development: {
+    github: '12082025_00',
+    slack: '10082025_01',
+  },
+  production: {
+    github: '10082025_00', // Older stable version
+    slack: '08082025_00',
+  }
+};
+
+const composio = new Composio({
+  toolkitVersions: toolkitVersions[process.env.NODE_ENV]
+});
+```
+
+### Override version for specific execution
+
+```typescript
+// Use global config version by default
+const composio = new Composio({
+  toolkitVersions: { github: '12082025_00' }
+});
+
+// Override for specific execution
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+  userId: 'default',
+  arguments: { owner: 'composio', repo: 'sdk' },
+  version: '15082025_00', // Override global version
+});
+```
+
+### Version validation helper
+
+```typescript
+function validateToolVersion(version: string): boolean {
+  // Check format: DDMMYYYY_XX
+  const versionRegex = /^\d{8}_\d{2}$/;
+  return versionRegex.test(version);
+}
+
+const version = '12082025_00';
+if (!validateToolVersion(version)) {
+  throw new Error('Invalid version format');
+}
+```

package/.agents/skills/composio/rules/app-toolkits.md

@@ -0,0 +1,184 @@
+---
+title: Toolkit Management
+impact: MEDIUM
+description: Discover and query toolkits, categories, and authentication requirements for application integration
+tags: [toolkits, discovery, metadata, categories, apps]
+---
+
+# Toolkit Management
+
+Toolkits are collections of related tools (GitHub, Gmail, Slack). Use the `toolkits` API to discover and query toolkit metadata.
+
+**Important:** `toolkits.get()` returns an **array**, not an object with `.items`. Access directly: `toolkits[0]`, `toolkits.length`, etc.
+
+## Get Toolkit Metadata
+
+```typescript
+// Get specific toolkit
+const github = await composio.toolkits.get('github');
+console.log(github.name); // GitHub
+console.log(github.authConfigDetails); // Auth details
+console.log(github.meta.toolsCount); // Number of tools
+console.log(github.meta.triggersCount); // Number of triggers
+
+// Get all toolkits
+const all = await composio.toolkits.get();
+console.log(all.length); // Number of toolkits
+```
+
+**Toolkit properties:**
+- `name`, `slug` - Display name and identifier
+- `meta` - toolsCount, triggersCount, createdAt, updatedAt
+- `authConfigDetails` - Available auth schemes and required fields
+- `composioManagedAuthSchemes` - Composio-managed auth
+- `baseUrl` - API base URL
+- `getCurrentUserEndpoint` - User info endpoint
+
+## Query Parameters
+
+All available filters for `toolkits.get()`:
+
+```typescript
+const toolkits = await composio.toolkits.get({
+  category: 'developer-tools',           // Filter by category ID
+  managedBy: 'composio',                // 'all' | 'composio' | 'project'
+  sortBy: 'usage',                      // 'usage' | 'alphabetically'
+  limit: 10,                            // Results per page
+  cursor: 'next_page_cursor',           // Pagination
+});
+```
+
+### Examples
+
+```typescript
+// Composio-managed only
+const composio = await composio.toolkits.get({ managedBy: 'composio' });
+
+// By category
+const devTools = await composio.toolkits.get({ category: 'developer-tools' });
+
+// Popular toolkits
+const popular = await composio.toolkits.get({ sortBy: 'usage', limit: 10 });
+
+// Paginated
+const page1 = await composio.toolkits.get({ limit: 10 });
+const page2 = await composio.toolkits.get({ limit: 10, cursor: page1Cursor });
+```
+
+## List Categories
+
+```typescript
+const categories = await composio.toolkits.listCategories();
+console.log(categories.items);
+// [
+//   { id: 'developer-tools', name: 'Developer Tools' },
+//   { id: 'communication', name: 'Communication' },
+//   { id: 'productivity', name: 'Productivity' },
+// ]
+```
+
+## Auth Requirements
+
+### Get Auth Config Creation Fields
+
+Find fields needed to create custom auth config:
+
+```typescript
+// All fields for GitHub OAuth2
+const fields = await composio.toolkits.getAuthConfigCreationFields(
+  'github',
+  'OAUTH2'
+);
+
+// Only required fields
+const required = await composio.toolkits.getAuthConfigCreationFields(
+  'github',
+  'OAUTH2',
+  { requiredOnly: true }
+);
+
+console.log(fields);
+// [
+//   { name: 'client_id', displayName: 'Client ID', type: 'string', required: true },
+//   { name: 'client_secret', displayName: 'Client Secret', type: 'string', required: true },
+//   { name: 'scopes', displayName: 'Scopes', type: 'string', default: 'repo,user', required: false }
+// ]
+```
+
+### Get Connected Account Initiation Fields
+
+Find fields needed when calling `initiate()` with custom auth:
+
+```typescript
+const fields = await composio.toolkits.getConnectedAccountInitiationFields(
+  'zendesk',
+  'OAUTH2'
+);
+
+// Only required fields
+const required = await composio.toolkits.getConnectedAccountInitiationFields(
+  'zendesk',
+  'OAUTH2',
+  { requiredOnly: true }
+);
+
+console.log(fields);
+// [
+//   { name: 'subdomain', displayName: 'Subdomain', type: 'string', required: true }
+// ]
+```
+
+**Use case:** Some services (Zendesk, PostHog) require extra parameters during OAuth. These fields tell you what's needed.
+
+## Common Patterns
+
+### Build Toolkit Selection UI
+
+```typescript
+const toolkits = await composio.toolkits.get({
+  sortBy: 'alphabetically'
+});
+
+const toolkitOptions = toolkits.items.map(tk => ({
+  value: tk.slug,
+  label: tk.name,
+  toolCount: tk.meta.toolsCount,
+  authSchemes: tk.composioManagedAuthSchemes,
+}));
+```
+
+### Check If OAuth Requires Extra Fields
+
+```typescript
+async function needsExtraParams(toolkit: string, authScheme: string) {
+  const fields = await composio.toolkits.getConnectedAccountInitiationFields(
+    toolkit,
+    authScheme
+  );
+  return fields.length > 0;
+}
+
+// Usage
+if (await needsExtraParams('zendesk', 'OAUTH2')) {
+  // Show form to collect subdomain
+}
+```
+
+### Filter Toolkits by Category
+
+```typescript
+async function getToolkitsByCategory(categoryId: string) {
+  return await composio.toolkits.get({
+    category: categoryId,
+    sortBy: 'usage',
+  });
+}
+```
+
+## Key Points
+
+- **Returns array** - Not `.items`, access directly
+- **managedBy filter** - 'all', 'composio', or 'project'
+- **sortBy options** - 'usage' or 'alphabetically'
+- **Auth field queries** - Know what's required before creating configs
+- **Extra OAuth params** - Some services need subdomain, region, etc.