Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Add .agent_cache and cursor rules for bugfix, testing and api updates (#2434)

Musthaq Ahamad4b5f3ac17008
diff --git a/.cursor/commands/api-update.md b/.cursor/commands/api-update.md
new file mode 100644
index 000000000..f9ac7794f
--- /dev/null
+++ b/.cursor/commands/api-update.md
@@ -0,0 +1,138 @@
+# API Update Command
+
+Check for open PRs in the Composio client repositories and create a plan for updating the SDKs.
+
+## Workflow
+
+### Step 1: Check for Open PRs
+
+Fetch open PRs from both client repositories:
+
+1. **TypeScript Client**: `github.com/composiohq/composio-base-ts`
+2. **Python Client**: `github.com/composiohq/composio-base-py`
+
+Use the GitHub CLI (`gh`) to list open PRs:
+```bash
+gh pr list --repo composiohq/composio-base-ts --state open --json number,title,url,headRefName,body
+gh pr list --repo composiohq/composio-base-py --state open --json number,title,url,headRefName,body
+```
+
+### Step 2: Get PR Patches
+
+For each open PR, fetch the diff/patch to understand the changes:
+```bash
+gh pr diff <PR_NUMBER> --repo composiohq/composio-base-ts
+gh pr diff <PR_NUMBER> --repo composiohq/composio-base-py
+```
+
+### Step 3: Analyze Changes
+
+For each PR, analyze the diff to identify:
+
+1. **New API endpoints** - New methods/functions added to the client
+2. **Modified parameters** - Changes to existing function signatures
+3. **Deprecated endpoints** - Removed or deprecated functionality
+4. **Type changes** - Updates to type definitions/schemas
+5. **Breaking changes** - Any backward-incompatible changes
+
+### Step 4: Identify SDK Impact
+
+Map client changes to SDK files that need updates:
+
+**TypeScript SDK (`@composio/core`)**:
+- Check `ts/packages/core/src/` for affected code
+- Types: `ts/packages/core/src/types/`
+- Models: `ts/packages/core/src/models/`
+- Services: `ts/packages/core/src/services/`
+
+> **Important - Naming Convention for TypeScript:**
+> The API uses **kebab-case** (e.g., `connected-accounts`, `auth-configs`, `tool-router`) but the TypeScript SDK uses **camelCase** (e.g., `connectedAccounts`, `authConfigs`, `toolRouter`).
+>
+> When mapping API changes to TypeScript SDK:
+> - Convert all kebab-case parameter names to camelCase
+> - Convert all kebab-case property names to camelCase
+> - Keep the original kebab-case names in comments for reference to the API
+> - Example: API's `callback_url` or `callback-url` becomes `callbackUrl` in TypeScript
+
+**Python SDK (`composio`)**:
+- Check `python/composio/` for affected code
+- Types and models in `python/composio/core/`
+- Python typically uses snake_case which often matches API naming
+
+### Step 5: Check Current Client Versions
+
+Current client dependency versions:
+- **TypeScript**: Check `pnpm-workspace.yaml` catalog for `@composio/client` version
+- **Python**: Check `python/pyproject.toml` for `composio-client` version
+
+### Step 6: Create Update Plan
+
+Create a plan document in `.agent_cache/` folder with the following structure:
+
+```
+.agent_cache/
+└── api-update-plan-<YYYY-MM-DD>.md
+```
+
+## Plan Document Structure
+
+The plan document should contain:
+
+### 1. PR Summary
+- List all open PRs with their numbers, titles, and URLs
+- Brief description of what each PR changes
+
+### 2. Client Version Updates
+- Current versions of both clients
+- Target versions (from PR branch or proposed release)
+- Files to update:
+ - `pnpm-workspace.yaml` (catalog section for `@composio/client`)
+ - `python/pyproject.toml` (dependencies section for `composio-client`)
+
+### 3. TypeScript SDK Changes
+For each change needed:
+- File path
+- Change description
+- Code snippet showing before/after (if applicable)
+- Whether it's a breaking change
+- **Naming mapping**: Show the API name (kebab-case/snake_case) → TypeScript name (camelCase)
+ - Example: `callback_url` → `callbackUrl`
+ - Example: `connected-account-id` → `connectedAccountId`
+
+### 4. Python SDK Changes
+For each change needed:
+- File path
+- Change description
+- Code snippet showing before/after (if applicable)
+- Whether it's a breaking change
+
+### 5. Breaking Changes Summary
+- List all breaking changes
+- Migration steps required
+- Affected public APIs
+
+### 6. Test Updates Required
+- New tests to add
+- Existing tests to update
+
+### 7. Documentation Updates
+- API documentation changes needed
+- Changelog entries to create
+
+## Important Notes
+
+- **DO NOT** apply any changes to the codebase
+- Only create the plan document in `.agent_cache/`
+- Wait for user confirmation before proceeding with any changes
+- If no open PRs are found, report that and exit
+- If PRs exist but have no SDK-impacting changes, note that in the plan
+
+## Example Output Path
+
+`.agent_cache/api-update-plan-2026-01-22.md`
+
+## Error Handling
+
+- If `gh` CLI is not authenticated, prompt user to run `gh auth login`
+- If repositories are not accessible, report the error
+- If PR diff is too large, summarize key changes only
diff --git a/.cursor/rules/bug-fix-testing.mdc b/.cursor/rules/bug-fix-testing.mdc
new file mode 100644
index 000000000..55c8aa319
--- /dev/null
+++ b/.cursor/rules/bug-fix-testing.mdc
@@ -0,0 +1,133 @@
+---
+description: Apply when fixing bugs, addressing issues, or resolving defects in the codebase
+globs:
+alwaysApply: false
+---
+
+# Bug Fix Testing Requirements
+
+When fixing bugs or addressing issues in the codebase, always ensure proper test coverage:
+
+## Required Actions
+
+1. **Identify existing tests** - Check if there are existing tests for the affected code
+ - TypeScript: Look in `ts/packages/<package>/test/` directories
+ - Python: Look in `python/tests/` directory
+
+2. **Add regression tests** - Create tests that:
+ - Reproduce the original bug (the test should fail before the fix)
+ - Verify the fix works correctly (the test should pass after the fix)
+ - Cover edge cases related to the bug
+
+3. **Update existing tests** - If the fix changes expected behavior:
+ - Update affected test assertions
+ - Add new test cases for the changed behavior
+ - Ensure no unrelated tests are broken
+
+## Test Location Guidelines
+
+**Important:** Add regression tests to existing test files that cover the affected feature/module. Do NOT create new test files specifically for regressions.
+
+### TypeScript
+
+**Test Structure:**
+- Tests location: `ts/packages/<package-name>/test/<feature>/<feature>.test.ts`
+- Mocks location: `ts/packages/<package-name>/test/utils/mocks/`
+- E2E tests: `ts/e2e-tests/`
+
+**Framework:** Vitest
+
+**Test Pattern:**
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('FeatureName', () => {
+ beforeEach(() => {
+ // Setup
+ });
+
+ afterEach(() => {
+ // Cleanup
+ });
+
+ describe('methodName', () => {
+ it('should <expected_behavior> when <condition>', async () => {
+ // Arrange
+ // Act
+ // Assert
+ expect(result).toEqual(expected);
+ });
+ });
+});
+```
+
+**Mocking:**
+- Use `vi.mock()` for module mocking
+- Use `vi.spyOn()` for spying on methods
+- Use `vi.fn()` for creating mock functions
+- Store reusable mocks in `test/utils/mocks/`
+
+### Python
+
+**Test Structure:**
+- Tests location: `python/tests/test_<feature>.py`
+- Shared fixtures: `python/tests/conftest.py`
+
+**Framework:** pytest with markers (`core`, `openai`, `langchain`, `vercel`)
+
+**Test Pattern:**
+```python
+import pytest
+from unittest.mock import MagicMock, patch
+
+def mock_client():
+ """Create a mock client."""
+ client = MagicMock()
+ return client
+
+class TestFeatureName:
+ """Test cases for FeatureName."""
+
+ def test_method_expected_behavior_when_condition(self, mock_client):
+ """Test that method behaves correctly when condition."""
+ # Arrange
+ # Act
+ # Assert
+ assert result == expected
+
+ def test_method_handles_error_gracefully(self, mock_client):
+ """Test that method handles errors gracefully."""
+ mock_client.some_method.side_effect = Exception("Error")
+
+ with pytest.raises(Exception, match="Error"):
+ # Act
+ pass
+```
+
+**Mocking:**
+- Use `@pytest.fixture` for reusable test dependencies
+- Use `unittest.mock.MagicMock` for mock objects
+- Use `@patch` decorator for patching modules
+- Use `mock.return_value` and `mock.side_effect` for return values
+
+## Test Naming Conventions
+
+**TypeScript:**
+- `describe()` blocks: Feature/class name
+- `it()` blocks: `'should <expected_behavior> when <condition>'`
+- Example: `it('should throw validation error when both tools and toolkits are provided')`
+
+**Python:**
+- Class: `TestFeatureName`
+- Method: `test_<feature>_<expected_behavior>_when_<condition>`
+- Example: `test_create_session_with_toolkits_list`
+
+## Verification
+
+Before completing the bug fix:
+1. Run the new/updated tests to confirm they pass
+ - TypeScript: `pnpm test` or `cd ts/packages/<package> && pnpm test`
+ - Python: `make tst` or `pytest -m <marker>`
+2. Run the full test suite to ensure no regressions
+3. Document the test in the PR/commit message
diff --git a/.gitignore b/.gitignore
index fae29166e..a194bdf24 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,3 +71,7 @@ fern/llms-txt-worker/public/*
# E2E test node_modules
test/e2e/*/node_modules
.vercel
+
+
+# Agent memory
+.agent_cache
\ No newline at end of file