Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import skills
Rahul Tarakb5fbec7ed053
diff --git a/.agents/skills/bug-fixing-guide/SKILL.md b/.agents/skills/bug-fixing-guide/SKILL.mdnew file mode 100644index 000000000..a67f55b81--- /dev/null+++ b/.agents/skills/bug-fixing-guide/SKILL.md@@ -0,0 +1,92 @@+# Bug Fixing Guide++Standard practices for fixing bugs in Composio SDK. Always add regression tests for major bugs.++## Bug Fix Process++### 1. Understand the Bug++- **Reproduce the issue** - Create a minimal reproduction case+- **Identify root cause** - Debug and trace the issue to its source+- **Check existing tests** - See if tests exist for the affected code+- **Review related code** - Check for similar issues elsewhere++### 2. Fix the Bug++- **Implement the fix** - Make minimal changes to address the root cause+- **Avoid scope creep** - Don't refactor unrelated code+- **Follow coding standards** - Maintain consistency with existing code+- **Test locally** - Verify the fix works as expected++### 3. Verify the Fix (Quick Functional Testing)++**Optional but Recommended:** Test actual functionality before adding unit tests.++For bugs affecting framework integrations or real-world usage:++- Use **ephemeral E2E tests** to quickly verify the fix works end-to-end+- Read `ephemeral-e2e-sdk-tests` skill for quick verification setup+- Test in `.agent_cache/test-<bug-description>` (never commit these)+- Example: `.agent_cache/test-fix-openai-tool-execution`++### 4. Add Regression Tests (Required for Major Bugs)++**Critical:** For major bugs, always add tests to prevent regressions.++See `.Codex/rules/bug-fix-testing.mdc` for detailed testing requirements:++- Where to add tests (TypeScript: `ts/packages/<package>/test/`, Python: `python/tests/`)+- How to structure tests (Vitest for TS, pytest for Python)+- Test naming conventions and patterns+- Mocking strategies++**Key Points:**++- Add tests to **existing test files** for the affected feature+- Tests should **fail before the fix** and **pass after**+- Cover edge cases related to the bug+- Run tests before committing: `pnpm test` (TS) or `make tst` (Python)++### 5. Document the Fix++- **Clear commit message** - Describe what was fixed and why+- **Reference issues** - Link to GitHub issues or tickets+- **Update docs** - If the bug exposed unclear documentation+- **Add comments** - Explain non-obvious fixes in the code++## When to Add Tests++**Always add tests for:**++- Logic errors and incorrect behavior+- Edge cases and boundary conditions+- Race conditions and async issues+- Security vulnerabilities+- Data corruption or loss issues++**Consider tests for:**++- Type errors (if not caught by TypeScript/mypy)+- Minor UI/UX issues+- Performance optimizations++**May skip tests for:**++- Trivial typo fixes in comments/docs+- Formatting or linting issues++## Testing Resources++- **Quick verification**: Read `ephemeral-e2e-sdk-tests` skill (test in `.agent_cache/`)+- **Full testing guidelines**: `.Codex/rules/bug-fix-testing.mdc`+- **TypeScript tests**: `ts/packages/<package>/test/`+- **Python tests**: `python/tests/`+- **E2E tests**: `ts/e2e-tests/` (for runtime compatibility issues)++## Common Pitfalls++- Fixing symptoms instead of root cause+- Not adding regression tests for major bugs+- Breaking existing tests without updating them+- Adding tests in new files instead of existing ones+- Not running the full test suite before committingdiff --git a/.agents/skills/building-agents-using-anthropic/SKILL.md b/.agents/skills/building-agents-using-anthropic/SKILL.mdnew file mode 100644index 000000000..39be4aadf--- /dev/null+++ b/.agents/skills/building-agents-using-anthropic/SKILL.md@@ -0,0 +1,134 @@+# Building Agents using Anthropic with Composio++Build AI agents using Anthropic's Codex API with Composio tools.++## Installation++```bash+npm install @composio/core @composio/anthropic @anthropic-ai/sdk+npm install @composio/Codex-agent-sdk @anthropic-ai/Codex-agent-sdk # For Agent SDK+```++```bash+pip install composio-anthropic+```++**Find Latest Versions:**+```bash+npm view @anthropic-ai/sdk version+pip index versions anthropic | grep "Available versions" | head -1+```++## Integration Method++**Anthropic Messages API is non-agentic** - uses direct tools. **Codex Agent SDK is agentic** - uses Tool Router.++### Messages API (Non-Agentic)++```typescript+import { Composio } from '@composio/core';+import { AnthropicProvider } from '@composio/anthropic';+import Anthropic from '@anthropic-ai/sdk';++const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });+const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new AnthropicProvider({ cacheTools: true }),+});++// Get tools+const tools = await composio.tools.get('default', { toolkits: ['github'] });++// Use with Codex+const message = await anthropic.messages.create({+ model: 'Codex-3-7-sonnet-latest',+ max_tokens: 1024,+ tools: tools,+ messages: [{ role: 'user', content: 'Create a GitHub issue' }],+});++// Handle tool calls+const toolResults = await composio.provider.handleToolCalls('default', message);+```++```python+from composio_anthropic import ComposioToolSet, Action+from anthropic import Anthropic++client = Anthropic(api_key="YOUR_KEY")+composio_toolset = ComposioToolSet(api_key="YOUR_KEY")++# Get tools+tools = composio_toolset.get_tools(actions=[Action.GITHUB_CREATE_ISSUE])++# Use with Codex+message = client.messages.create(+ model="Codex-3-7-sonnet-latest",+ max_tokens=1024,+ tools=tools,+ messages=[{"role": "user", "content": "Create a GitHub issue"}]+)++# Handle tool calls+tool_results = composio_toolset.handle_tool_calls(message)+```++### Codex Agent SDK (Agentic - Requires Tool Router)++```typescript+import { Composio } from '@composio/core';+import { ClaudeAgentSDKProvider } from '@composio/Codex-agent-sdk';+import { query } from '@anthropic-ai/Codex-agent-sdk';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new ClaudeAgentSDKProvider()+});++async function runAgent(userId: string, prompt: string) {+ // Create session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ // Use with Codex Agent SDK+ const stream = await query({+ prompt,+ options: {+ model: 'Codex-sonnet-4-5-20250929',+ permissionMode: 'bypassPermissions',+ tools+ }+ });++ for await (const event of stream) {+ if (event.type === 'result' && event.subtype === 'success') {+ console.log(event.result);+ }+ }+}+```++## Key Resources++- **Anthropic Docs**: https://docs.anthropic.com/+- **Tool Use Guide**: https://docs.anthropic.com/en/docs/build-with-Codex/tool-use+- **Codex Agent SDK**: https://docs.anthropic.com/en/docs/agents+- **Messages API (Non-Agentic)**: Direct tools+- **Codex Agent SDK (Agentic)**: Use Tool Router++## Environment Variables++```bash+ANTHROPIC_API_KEY=sk-ant-...+COMPOSIO_API_KEY=...+```++## Next Steps++1. For Agent SDK (agentic), use `/building-agents`+2. Check `ts/examples/anthropic/` for complete examples+3. See [Anthropic docs](https://docs.anthropic.com/) for Codex featuresdiff --git a/.agents/skills/building-agents-using-autogen/SKILL.md b/.agents/skills/building-agents-using-autogen/SKILL.mdnew file mode 100644index 000000000..67e674f8e--- /dev/null+++ b/.agents/skills/building-agents-using-autogen/SKILL.md@@ -0,0 +1,143 @@+# Building Agents using Microsoft AutoGen with Composio++Build multi-agent conversational systems using AutoGen with Composio Tool Router.++## Installation++```bash+# For AgentChat (conversational agents)+pip install composio-autogen autogen-agentchat autogen-ext[openai]++# For AutoGen Studio (UI-based)+pip install autogenstudio+```++**Find Latest Versions:**+```bash+pip index versions autogen-agentchat | grep "Available versions" | head -1+pip index versions composio-autogen | grep "Available versions" | head -1+```++## Integration Method++**AutoGen is an agentic provider** - use Tool Router for user isolation.++### Native Tools with Tool Router++```python+import asyncio+from autogen_agentchat.agents import AssistantAgent+from autogen_ext.models.openai import OpenAIChatCompletionClient+from composio_autogen import ComposioToolSet, App++toolset = ComposioToolSet()++async def create_agent(user_id: str):+ # Create session+ session = toolset.create(+ user_id=user_id,+ toolkits=["github"],+ manage_connections=True+ )++ tools = session.tools()++ # Create agent with tools+ agent = AssistantAgent(+ name="github_agent",+ model_client=OpenAIChatCompletionClient(model="gpt-4o"),+ tools=tools,+ system_message="You manage GitHub repositories"+ )++ return agent++async def main():+ agent = await create_agent("user_123")+ result = await agent.run(task="Create a GitHub issue titled 'Bug Report'")+ print(result)++asyncio.run(main())+```++### Multi-Agent Conversation++```python+import asyncio+from autogen_agentchat.agents import AssistantAgent+from autogen_agentchat.teams import RoundRobinGroupChat+from autogen_ext.models.openai import OpenAIChatCompletionClient+from composio_autogen import ComposioToolSet, App++toolset = ComposioToolSet()++async def create_team(user_id: str):+ # Create session+ session = toolset.create(+ user_id=user_id,+ toolkits=["github", "slack"],+ manage_connections=True+ )++ tools = session.tools()++ # Create specialized agents+ github_agent = AssistantAgent(+ name="github_agent",+ model_client=OpenAIChatCompletionClient(model="gpt-4o"),+ tools=tools,+ system_message="You manage GitHub"+ )++ slack_agent = AssistantAgent(+ name="slack_agent",+ model_client=OpenAIChatCompletionClient(model="gpt-4o"),+ tools=tools,+ system_message="You manage Slack"+ )++ # Create team+ team = RoundRobinGroupChat(+ [github_agent, slack_agent],+ max_turns=10+ )++ return team++async def main():+ team = await create_team("user_123")+ result = await team.run(+ task="Create a GitHub issue and notify team on Slack"+ )+ print(result)++asyncio.run(main())+```++## Key Features++- **Multi-Agent Conversations**: Agents collaborate and communicate+- **AutoGen Studio**: No-code UI for prototyping+- **Multiple Layers**: Studio, AgentChat, Core for different needs+- **Team Patterns**: RoundRobin, Swarm, custom orchestration++## Key Resources++- **AutoGen Docs**: https://microsoft.github.io/autogen/stable/+- **Tool Router Guide**: `/building-agents`+- **GitHub**: https://github.com/microsoft/autogen+- **Microsoft Agent Framework**: Successor to AutoGen++## Environment Variables++```bash+OPENAI_API_KEY=sk-... # Or other LLM provider+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `python/providers/autogen/` for complete examples+3. See [AutoGen docs](https://microsoft.github.io/autogen/stable/) for conversation patterns+4. Consider [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/) for new projectsdiff --git a/.agents/skills/building-agents-using-cloudflare/SKILL.md b/.agents/skills/building-agents-using-cloudflare/SKILL.mdnew file mode 100644index 000000000..b8da7fb90--- /dev/null+++ b/.agents/skills/building-agents-using-cloudflare/SKILL.md@@ -0,0 +1,124 @@+# Building Agents using Cloudflare with Composio++Build edge-deployed AI agents using Cloudflare Workers AI with Composio Tool Router.++## Installation++```bash+npm install @composio/core @composio/cloudflare agents @cloudflare/ai-utils+npm install wrangler -D # For development+```++**Find Latest Versions:**+```bash+npm view agents version+npm view @composio/cloudflare version+```++## Integration Method++**Cloudflare is an agentic provider** - use Tool Router for user isolation.++### Native Tools with Tool Router++```typescript+import { Agent } from 'agents';+import { Composio } from '@composio/core';+import { CloudflareProvider } from '@composio/cloudflare';++export class MyAgent extends Agent {+ private composio: Composio;++ constructor(state: DurableObjectState, env: Env) {+ super(state, env);++ this.composio = new Composio({+ apiKey: env.COMPOSIO_API_KEY,+ provider: new CloudflareProvider(),+ });+ }++ async onStart() {+ // Initialize with user-specific session+ const session = await this.composio.create(this.userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ this.tools = await session.tools();+ }++ async handleMessage(message: string) {+ // Use tools with Cloudflare AI+ const response = await this.ai.run('@cf/meta/llama-3.1-70b-instruct', {+ messages: [+ { role: 'system', content: 'You are a helpful assistant' },+ { role: 'user', content: message },+ ],+ tools: this.tools,+ });++ return response;+ }+}+```++### wrangler.toml Configuration++```toml+name = "my-agent"+main = "src/index.ts"+compatibility_date = "2024-01-01"++[[durable_objects.bindings]]+name = "MY_AGENT"+class_name = "MyAgent"++[ai]+binding = "AI"++[vars]+COMPOSIO_API_KEY = "your-key-here"++[[migrations]]+tag = "v1"+new_sqlite_classes = ["MyAgent"]+```++## Key Features++- **Edge Deployment**: Low-latency worldwide+- **Durable Objects**: Persistent agent state+- **Workers AI**: Run models at the edge+- **Embedded Function Calling**: AI executes functions automatically++## Key Resources++- **Cloudflare Agents SDK**: https://developers.cloudflare.com/agents/+- **Tool Router Guide**: `/building-agents`+- **Workers AI**: https://developers.cloudflare.com/workers-ai/+- **Function Calling**: https://developers.cloudflare.com/workers-ai/features/function-calling/++## Environment Variables++```bash+COMPOSIO_API_KEY=...+CLOUDFLARE_ACCOUNT_ID=...+CLOUDFLARE_API_TOKEN=...+```++## Deployment++```bash+# Deploy with Wrangler+npx wrangler deploy++# Tail logs+npx wrangler tail+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `ts/examples/cloudflare-wrangler/` for complete examples+3. See [Cloudflare docs](https://developers.cloudflare.com/agents/) for edge featuresdiff --git a/.agents/skills/building-agents-using-crewai/SKILL.md b/.agents/skills/building-agents-using-crewai/SKILL.mdnew file mode 100644index 000000000..019a021d3--- /dev/null+++ b/.agents/skills/building-agents-using-crewai/SKILL.md@@ -0,0 +1,147 @@+# Building Agents using CrewAI with Composio++Build multi-agent teams using CrewAI with Composio Tool Router.++## Installation++```bash+pip install composio-crewai crewai crewai-tools+```++**Find Latest Versions:**+```bash+pip index versions crewai | grep "Available versions" | head -1+pip index versions composio-crewai | grep "Available versions" | head -1+```++## Integration Method++**CrewAI is an agentic provider** - use MCP for multi-agent teams.++### MCP Integration++```python+from crewai import Agent, Task, Crew+from crewai.mcp import MCPServerHTTP+from composio import Composio++composio = Composio()++def create_crew(user_id: str):+ # Create session+ session = composio.create(user_id=user_id, toolkits=["github"])++ # Create agent with MCP server+ agent = Agent(+ role="GitHub Manager",+ goal="Manage GitHub repositories",+ backstory="You are an expert at GitHub operations",+ mcps=[+ MCPServerHTTP(+ url=session.mcp.url,+ headers=session.mcp.headers+ )+ ]+ )++ # Define task+ task = Task(+ description="Create a GitHub issue titled 'Bug Report'",+ expected_output="Confirmation of issue creation",+ agent=agent+ )++ # Execute crew+ crew = Crew(agents=[agent], tasks=[task])+ return crew++crew = create_crew("user_123")+result = crew.kickoff()+print(result)+```++### Multi-Agent Team Example++```python+from crewai import Agent, Task, Crew, Process+from crewai.mcp import MCPServerHTTP+from composio import Composio++composio = Composio()++def create_team(user_id: str):+ session = composio.create(user_id=user_id, toolkits=["github", "slack"])++ # Create MCP server connection+ mcp_server = MCPServerHTTP(+ url=session.mcp.url,+ headers=session.mcp.headers+ )++ # Create specialized agents+ researcher = Agent(+ role="GitHub Researcher",+ goal="Analyze repositories",+ backstory="Expert at code analysis",+ mcps=[mcp_server]+ )++ reporter = Agent(+ role="Report Writer",+ goal="Create reports",+ backstory="Expert at documentation",+ mcps=[mcp_server]+ )++ # Define tasks+ research_task = Task(+ description="Analyze the repository",+ expected_output="Analysis report",+ agent=researcher+ )++ report_task = Task(+ description="Create a summary report",+ expected_output="Markdown report",+ agent=reporter,+ context=[research_task]+ )++ crew = Crew(+ agents=[researcher, reporter],+ tasks=[research_task, report_task],+ process=Process.sequential+ )++ return crew++team = create_team("user_123")+result = team.kickoff()+```++## Key Features++- **Multi-Agent Teams**: Agents collaborate on tasks+- **Task Dependencies**: Sequential or hierarchical execution+- **YAML Configs**: Clean agent/task definitions+- **Production Ready**: Mature framework++## Key Resources++- **CrewAI Docs**: https://docs.crewai.com/+- **Tool Router Guide**: `/building-agents`+- **Quickstart**: https://docs.crewai.com/en/quickstart+- **GitHub**: https://github.com/crewAIInc/crewAI++## Environment Variables++```bash+OPENAI_API_KEY=sk-... # Or other LLM provider+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `python/providers/crewai/` for complete examples+3. See [CrewAI docs](https://docs.crewai.com/) for multi-agent patternsdiff --git a/.agents/skills/building-agents-using-google/SKILL.md b/.agents/skills/building-agents-using-google/SKILL.mdnew file mode 100644index 000000000..9df3f64e5--- /dev/null+++ b/.agents/skills/building-agents-using-google/SKILL.md@@ -0,0 +1,107 @@+# Building Agents using Google Gemini with Composio++Build AI agents using Google's Gemini API with Composio tools.++## Installation++```bash+npm install @composio/core @composio/google @google/genai+```++```bash+pip install composio-google google-genai+```++**Find Latest Versions:**+```bash+npm view @google/genai version+pip index versions google-genai | grep "Available versions" | head -1+```++## Integration Method++**Google Gemini is a non-agentic provider** - uses direct tools (no Tool Router support).++### TypeScript Example++```typescript+import { Composio } from '@composio/core';+import { GoogleProvider } from '@composio/google';+import { GoogleGenAI } from '@google/genai';++const genai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });+const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new GoogleProvider(),+});++// Get tools+const tools = await composio.tools.get('default', { toolkits: ['github'] });++// Use with Gemini+const response = await genai.models.generateContent({+ model: 'gemini-3-flash-preview',+ contents: 'Create a GitHub issue',+ config: {+ tools: tools,+ temperature: 1.0 // Required for Gemini 3+ },+});++// Handle function calls+if (response.functionCalls) {+ const results = await composio.provider.handleToolCalls('default', response);+}+```++### Python Example++```python+from composio_google import ComposioToolSet, Action+from google import genai+from google.genai import types++client = genai.Client(api_key="YOUR_KEY")+composio_toolset = ComposioToolSet(api_key="YOUR_KEY")++# Get tools+tools = composio_toolset.get_tools(actions=[Action.GITHUB_CREATE_ISSUE])++# Use with Gemini+response = client.models.generate_content(+ model="gemini-3-flash-preview",+ contents="Create a GitHub issue",+ config=types.GenerateContentConfig(+ tools=tools,+ temperature=1.0+ )+)++# Handle function calls+tool_results = composio_toolset.handle_tool_calls(response)+```++## Key Features++- **Compositional Function Calling**: Chain multiple functions automatically+- **Parallel Execution**: Execute independent functions simultaneously+- **Internal Thinking**: Gemini 3 models reason through complex requests++## Key Resources++- **Gemini API Docs**: https://ai.google.dev/gemini-api/docs+- **Function Calling**: https://ai.google.dev/gemini-api/docs/function-calling+- **Available Models**: Gemini 3 Pro/Flash, Gemini 2.5 Pro/Flash++## Environment Variables++```bash+GOOGLE_API_KEY=...+COMPOSIO_API_KEY=...+```++## Next Steps++1. Check `ts/examples/google/` for complete examples+2. See [Gemini docs](https://ai.google.dev) for API features+3. Note: Temperature must be 1.0 for Gemini 3 modelsdiff --git a/.agents/skills/building-agents-using-langchain/SKILL.md b/.agents/skills/building-agents-using-langchain/SKILL.mdnew file mode 100644index 000000000..bc7648da1--- /dev/null+++ b/.agents/skills/building-agents-using-langchain/SKILL.md@@ -0,0 +1,123 @@+# Building Agents using LangChain with Composio++Build AI agents using LangChain/LangGraph with Composio Tool Router.++## Installation++```bash+npm install @composio/core @composio/langchain langchain @langchain/core @langchain/openai+```++```bash+pip install composio-langchain langchain langchain-openai+```++**Find Latest Versions:**+```bash+npm view langchain version+pip index versions langchain | grep "Available versions" | head -1+```++## Integration Method++**LangChain is an agentic provider** - use Tool Router (or MCP for flexibility).++### Native Tools with Tool Router++```typescript+import { ChatOpenAI } from '@langchain/openai';+import { Composio } from '@composio/core';+import { LangchainProvider } from '@composio/langchain';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new LangchainProvider(),+});++async function runAgent(userId: string, prompt: string) {+ // Create session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ // Use with LangChain+ const llm = new ChatOpenAI({ model: 'gpt-4o' });+ const agent = llm.bindTools(tools);++ const result = await agent.invoke(prompt);+ return result;+}+```++```python+from langchain_openai import ChatOpenAI+from composio_langchain import ComposioToolSet, App++composio_toolset = ComposioToolSet()++def run_agent(user_id: str, prompt: str):+ # Create session+ session = composio_toolset.create(+ user_id=user_id,+ toolkits=["github"],+ manage_connections=True+ )++ tools = session.tools()++ # Use with LangChain+ llm = ChatOpenAI(model="gpt-4o")+ agent = llm.bind_tools(tools)++ result = agent.invoke(prompt)+ return result+```++### MCP Integration++```typescript+import { MultiServerMCPClient } from '@langchain/mcp-adapters';+import { Composio } from '@composio/core';++const composio = new Composio();++async function runAgentMCP(userId: string) {+ const session = await composio.create(userId, {+ toolkits: ['github']+ });++ const client = new MultiServerMCPClient({+ composio: {+ transport: 'http',+ url: session.mcp.url,+ headers: session.mcp.headers+ }+ });++ const tools = await client.getTools();+ // Use tools with LangChain+}+```++## Key Resources++- **LangChain Docs**: https://python.langchain.com/docs/introduction/+- **Tool Router Guide**: `/building-agents`+- **Agents Documentation**: https://docs.langchain.com/oss/python/langchain/agents+- **Use LangGraph for production**: More flexible agent runtime++## Environment Variables++```bash+OPENAI_API_KEY=sk-... # Or other LLM provider+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Use `/building-agents-using-langgraph` for stateful agents+3. Check `ts/examples/langchain/` for complete examplesdiff --git a/.agents/skills/building-agents-using-langgraph/SKILL.md b/.agents/skills/building-agents-using-langgraph/SKILL.mdnew file mode 100644index 000000000..a290d4531--- /dev/null+++ b/.agents/skills/building-agents-using-langgraph/SKILL.md@@ -0,0 +1,140 @@+# Building Agents using LangGraph with Composio++Build stateful, durable AI agents using LangGraph with Composio Tool Router.++## Installation++```bash+npm install @composio/core @composio/langchain @langchain/langgraph @langchain/core+```++```bash+pip install composio-langchain langgraph langgraph-checkpoint-sqlite+```++**Find Latest Versions:**+```bash+npm view @langchain/langgraph version+pip index versions langgraph | grep "Available versions" | head -1+```++## Integration Method++**LangGraph is an agentic provider** - use Tool Router for user isolation.++### Python Example with Tool Router++```python+from langgraph.graph import StateGraph, MessagesAnnotation, START, END+from langgraph.prebuilt import ToolNode+from langgraph.checkpoint.sqlite import SqliteSaver+from langchain_openai import ChatOpenAI+from composio_langchain import ComposioToolSet++toolset = ComposioToolSet()++def create_agent(user_id: str):+ # Create session+ session = toolset.create(+ user_id=user_id,+ toolkits=["github"],+ manage_connections=True+ )++ tools = session.tools()++ # Create graph+ tool_node = ToolNode(tools)+ model = ChatOpenAI(model="gpt-4o").bind_tools(tools)++ def should_continue(state):+ last_message = state["messages"][-1]+ return "tools" if hasattr(last_message, "tool_calls") and last_message.tool_calls else END++ def call_model(state):+ return {"messages": [model.invoke(state["messages"])]}++ workflow = StateGraph(MessagesAnnotation)+ workflow.add_node("agent", call_model)+ workflow.add_node("tools", tool_node)+ workflow.add_edge(START, "agent")+ workflow.add_edge("tools", "agent")+ workflow.add_conditional_edges("agent", should_continue)++ # Compile with checkpointer for durability+ memory = SqliteSaver.from_conn_string(":memory:")+ app = workflow.compile(checkpointer=memory)++ return app++# Use with thread_id for persistence+app = create_agent("user_123")+result = app.invoke(+ {"messages": [{"role": "user", "content": "Create a GitHub issue"}]},+ config={"configurable": {"thread_id": "user-123"}}+)+```++### TypeScript Example with Tool Router++```typescript+import { StateGraph, MessagesAnnotation, START, END } from '@langchain/langgraph';+import { ToolNode } from '@langchain/langgraph/prebuilt';+import { ChatOpenAI } from '@langchain/openai';+import { Composio } from '@composio/core';+import { LangchainProvider } from '@composio/langchain';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new LangchainProvider(),+});++async function createAgent(userId: string) {+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();+ const toolNode = new ToolNode(tools);+ const model = new ChatOpenAI({ model: 'gpt-4o' }).bindTools(tools);++ const workflow = new StateGraph(MessagesAnnotation)+ .addNode('agent', async (state) => ({ messages: [await model.invoke(state.messages)] }))+ .addNode('tools', toolNode)+ .addEdge(START, 'agent')+ .addEdge('tools', 'agent')+ .addConditionalEdges('agent', (state) => {+ const last = state.messages[state.messages.length - 1];+ return last.tool_calls?.length ? 'tools' : END;+ });++ return workflow.compile();+}+```++## Key Features++- **Durable Execution**: Agents persist through failures+- **Human-in-the-Loop**: Pause for approvals+- **Persistent Memory**: State saved across sessions+- **Production Ready**: v1.0 released late 2025++## Key Resources++- **LangGraph Docs**: https://docs.langchain.com/oss/python/langgraph/+- **Tool Router Guide**: `/building-agents`+- **LangGraph v1.0**: https://www.blog.langchain.com/langchain-langgraph-1dot0/++## Environment Variables++```bash+OPENAI_API_KEY=sk-...+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `ts/examples/langchain/` for complete examples+3. See [LangGraph docs](https://docs.langchain.com/oss/python/langgraph/) for advanced featuresdiff --git a/.agents/skills/building-agents-using-llamaindex/SKILL.md b/.agents/skills/building-agents-using-llamaindex/SKILL.mdnew file mode 100644index 000000000..12bdf1bdc--- /dev/null+++ b/.agents/skills/building-agents-using-llamaindex/SKILL.md@@ -0,0 +1,128 @@+# Building Agents using LlamaIndex with Composio++Build RAG-enhanced AI agents using LlamaIndex with Composio Tool Router.++## Installation++```bash+npm install @composio/core @composio/llamaindex llamaindex+```++```bash+pip install composio-llamaindex llama-index llama-index-llms-openai+```++**Find Latest Versions:**+```bash+npm view llamaindex version+pip index versions llama-index | grep "Available versions" | head -1+```++## Integration Method++**LlamaIndex is an agentic provider** - use Tool Router for user isolation.++### Python Example with Tool Router++```python+from llama_index.core.agent import ReActAgent+from llama_index.llms.openai import OpenAI+from composio_llamaindex import ComposioToolSet, App++toolset = ComposioToolSet()++def create_agent(user_id: str):+ # Create session+ session = toolset.create(+ user_id=user_id,+ toolkits=["github"],+ manage_connections=True+ )++ tools = session.tools()++ # Create agent+ llm = OpenAI(model="gpt-4o")+ agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)++ return agent++agent = create_agent("user_123")+response = agent.chat("Create a GitHub issue titled 'Bug Report'")+print(response)+```++### TypeScript Example with Tool Router++```typescript+import { Composio } from '@composio/core';+import { LlamaIndexProvider } from '@composio/llamaindex';+import { OpenAI, FunctionCallingAgent } from 'llamaindex';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new LlamaIndexProvider(),+});++async function createAgent(userId: string) {+ // Create session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ // Create agent+ const llm = new OpenAI({ model: 'gpt-4o' });+ const agent = new FunctionCallingAgent({+ llm,+ tools,+ verbose: true,+ });++ return agent;+}++const agent = await createAgent('user_123');+const response = await agent.chat({ message: 'Create a GitHub issue' });+```++### MCP Integration++```python+# LlamaIndex also supports MCP for framework flexibility+from composio import Composio++composio = Composio()+session = composio.create(user_id="user_123", toolkits=["github"])++# Use session.mcp.url with LlamaIndex MCP adapters+```++## Key Features++- **ReAct Agents**: Reasoning + Acting pattern+- **RAG + Tools**: Combine retrieval with actions+- **Workflows 1.0**: Event-driven orchestration+- **Query Engines**: Tools for advanced RAG++## Key Resources++- **LlamaIndex Docs**: https://developers.llamaindex.ai/python/framework/+- **Tool Router Guide**: `/building-agents`+- **Agents Guide**: https://developers.llamaindex.ai/python/framework/use_cases/agents/+- **Workflows**: https://www.llamaindex.ai/blog/announcing-workflows-1-0-a-lightweight-framework-for-agentic-systems++## Environment Variables++```bash+OPENAI_API_KEY=sk-...+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `ts/examples/llamaindex/` for complete examples+3. See [LlamaIndex docs](https://developers.llamaindex.ai/) for RAG patternsdiff --git a/.agents/skills/building-agents-using-mastra/SKILL.md b/.agents/skills/building-agents-using-mastra/SKILL.mdnew file mode 100644index 000000000..70504248b--- /dev/null+++ b/.agents/skills/building-agents-using-mastra/SKILL.md@@ -0,0 +1,121 @@+# Building Agents using Mastra with Composio++Build AI agents using Mastra with Composio Tool Router.++## Installation++```bash+npm install @composio/core @composio/mastra @mastra/core+```++**Find Latest Versions:**+```bash+npm view @mastra/core version+npm view @composio/mastra version+```++## Integration Method++**Mastra is an agentic provider** - use Tool Router for user isolation.++### Native Tools with Tool Router++```typescript+import { Composio } from '@composio/core';+import { MastraProvider } from '@composio/mastra';+import { Agent } from '@mastra/core/agent';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new MastraProvider(),+});++async function createAgent(userId: string) {+ // Create session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ // Create agent+ const agent = new Agent({+ id: 'github-agent',+ name: 'GitHub Agent',+ instructions: 'You manage GitHub repositories',+ model: 'openai/gpt-4o',+ tools: {+ ...tools, // Spread Composio tools+ },+ });++ return agent;+}++const agent = await createAgent('user_123');+const result = await agent.generate({+ prompt: 'Create a GitHub issue titled "Bug Report"',+});++console.log(result.text);+```++### Streaming with Tool Router++```typescript+async function streamAgent(userId: string, prompt: string) {+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ const agent = new Agent({+ id: 'agent',+ model: 'openai/gpt-4o',+ tools: { ...tools },+ maxSteps: 10,+ });++ // Stream response+ const stream = await agent.stream({+ prompt,+ onStepFinish: (step) => {+ console.log('Step completed:', step);+ },+ });++ for await (const chunk of stream) {+ process.stdout.write(chunk);+ }+}+```++## Key Features++- **40+ Model Providers**: OpenAI, Anthropic, Google, Mistral, Groq, etc.+- **Autonomous Agents**: Solve open-ended tasks+- **Streaming Support**: Real-time responses+- **v1.0 Released**: January 2026 - production ready++## Key Resources++- **Mastra Docs**: https://mastra.ai/docs+- **Tool Router Guide**: `/building-agents`+- **Agents Guide**: https://mastra.ai/docs/agents/overview+- **GitHub**: https://github.com/mastra-ai/mastra++## Environment Variables++```bash+OPENAI_API_KEY=sk-... # Or other model provider+COMPOSIO_API_KEY=...+```++## Next Steps++1. Use `/building-agents` for comprehensive guide+2. Check `ts/examples/mastra/` for complete examples+3. See [Mastra docs](https://mastra.ai/docs) for multi-provider routingdiff --git a/.agents/skills/building-agents-using-openai/SKILL.md b/.agents/skills/building-agents-using-openai/SKILL.mdnew file mode 100644index 000000000..762054a95--- /dev/null+++ b/.agents/skills/building-agents-using-openai/SKILL.md@@ -0,0 +1,125 @@+# Building Agents using OpenAI with Composio++Build AI agents using OpenAI's APIs with Composio tools.++## Installation++```bash+npm install @composio/core @composio/openai openai+npm install @composio/openai-agents @openai/agents # For Agents API+```++```bash+pip install composio-openai+```++**Find Latest Versions:**+```bash+npm view openai version+pip index versions openai | grep "Available versions" | head -1+```++## Integration Method++**OpenAI is a non-agentic provider** - uses direct tools (no Tool Router support).++### Chat Completions API++```typescript+import { Composio } from '@composio/core';+import { OpenAI } from 'openai';++const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });++// Get tools+const tools = await composio.tools.get('default', { toolkits: ['github'] });++// Use with OpenAI+const response = await openai.chat.completions.create({+ model: 'gpt-4o',+ messages: [{ role: 'user', content: 'Create a GitHub issue' }],+ tools: tools,+});++// Handle tool calls+if (response.choices[0].message.tool_calls) {+ const result = await composio.provider.handleToolCalls('default', response);+}+```++```python+from composio_openai import ComposioToolSet, Action+from openai import OpenAI++openai_client = OpenAI(api_key="YOUR_KEY")+composio_toolset = ComposioToolSet(api_key="YOUR_KEY")++# Get tools+tools = composio_toolset.get_tools(actions=[Action.GITHUB_CREATE_ISSUE])++# Use with OpenAI+response = openai_client.chat.completions.create(+ model="gpt-4o",+ messages=[{"role": "user", "content": "Create a GitHub issue"}],+ tools=tools,+)++# Handle tool calls+result = composio_toolset.handle_tool_calls(response)+```++### OpenAI Agents API (Agentic - Requires Tool Router)++```typescript+import { Composio } from '@composio/core';+import { OpenAIAgentsProvider } from '@composio/openai-agents';+import { Agent, run } from '@openai/agents';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new OpenAIAgentsProvider()+});++async function createAgent(userId: string) {+ // Create session for user+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ const tools = await session.tools();++ const agent = new Agent({+ name: 'GitHub Agent',+ model: 'gpt-4o',+ instructions: 'You help with GitHub operations',+ tools+ });++ return agent;+}++const agent = await createAgent('user_123');+const result = await run(agent, 'Create a GitHub issue');+```++## Key Resources++- **OpenAI Docs**: https://platform.openai.com/docs+- **Function Calling**: https://platform.openai.com/docs/guides/function-calling+- **Agents API**: https://platform.openai.com/docs/agents+- **OpenAI Agents SDK (Agentic)**: Use Tool Router with `@composio/openai-agents`++## Environment Variables++```bash+OPENAI_API_KEY=sk-...+COMPOSIO_API_KEY=...+```++## Next Steps++1. For Agents API (agentic), use `/building-agents`+2. Check `ts/examples/openai/` for complete examples+3. See [OpenAI docs](https://platform.openai.com/docs) for API featuresdiff --git a/.agents/skills/building-agents-using-vercel/SKILL.md b/.agents/skills/building-agents-using-vercel/SKILL.mdnew file mode 100644index 000000000..05b264779--- /dev/null+++ b/.agents/skills/building-agents-using-vercel/SKILL.md@@ -0,0 +1,116 @@+# Building Agents using Vercel AI SDK with Composio++Build AI agents using Vercel AI SDK with Composio Tool Router for user-isolated tool sessions.++## Installation++```bash+npm install @composio/core @composio/vercel ai @ai-sdk/openai+```++**Find Latest Versions:**+```bash+npm view ai version+npm view @composio/vercel version+```++## Integration Method++**Vercel AI SDK is an agentic provider** - use Tool Router for user isolation.++### Native Tools (Recommended)++```typescript+import { Composio } from '@composio/core';+import { VercelProvider } from '@composio/vercel';+import { openai } from '@ai-sdk/openai';+import { generateText } from 'ai';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new VercelProvider(),+});++async function runAgent(userId: string, prompt: string) {+ // Create user session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ // Get native Vercel-formatted tools+ const tools = await session.tools();++ // Use with Vercel AI SDK+ const result = await generateText({+ model: openai('gpt-4o'),+ prompt,+ tools,+ maxSteps: 10,+ });++ return result.text;+}++await runAgent('user_123', 'Create a GitHub issue');+```++### MCP Integration (Optional)++```typescript+import { Composio } from '@composio/core';+import { experimental_createMCPClient as createMCPClient } from '@ai-sdk/mcp';+import { streamText } from 'ai';++const composio = new Composio();++async function runAgentMCP(userId: string, prompt: string) {+ // Create session+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true+ });++ // Connect via MCP+ const client = await createMCPClient({+ transport: {+ type: 'http',+ url: session.mcp.url,+ headers: session.mcp.headers+ }+ });++ const tools = await client.tools();++ // Use with any framework+ const stream = await streamText({+ model: openai('gpt-4o'),+ prompt,+ tools,+ });++ for await (const chunk of stream.textStream) {+ process.stdout.write(chunk);+ }+}+```++## Key Resources++- **Vercel AI SDK Docs**: https://ai-sdk.dev/docs/introduction+- **Tool Router Guide**: `/building-agents`+- **Building Agents Guide**: https://vercel.com/kb/guide/how-to-build-ai-agents-with-vercel-and-the-ai-sdk+- **Native vs MCP**: Use native tools for better performance, MCP for framework flexibility++## Environment Variables++```bash+COMPOSIO_API_KEY=...+OPENAI_API_KEY=... # Or other model provider+```++## Next Steps++1. Use `/building-agents` for comprehensive Tool Router documentation+2. Check `ts/examples/vercel/` for complete examples+3. See [Vercel AI SDK docs](https://ai-sdk.dev) for framework-specific featuresdiff --git a/.agents/skills/building-agents/SKILL.md b/.agents/skills/building-agents/SKILL.mdnew file mode 100644index 000000000..46836c464--- /dev/null+++ b/.agents/skills/building-agents/SKILL.md@@ -0,0 +1,440 @@+# Building AI Agents with Composio SDK++This skill provides comprehensive guidance for building AI agents using Composio SDK with various provider frameworks.++## Overview++Composio integrates with 10+ major AI agent frameworks, allowing you to add tools and external integrations to your agents. Each framework-specific skill provides:+- Installing and setting up the provider SDK+- Finding latest SDK versions (NPM/PyPI)+- Official documentation links and latest examples+- Code examples for building agents with Composio tools+- Best practices and troubleshooting tips++## Installing Composio Packages++### Working in Composio SDK Repository (This Workspace)++If you're working within the Composio SDK repository itself, install packages from the workspace:++**TypeScript:**+```bash+pnpm i @composio/core @composio/<provider> --workspace+```++**Example:**+```bash+pnpm i @composio/core @composio/openai --workspace+```++### External Projects (Outside SDK Repository)++For projects outside the Composio SDK repository, install from NPM/PyPI:++**TypeScript:**+```bash+npm install @composio/core @composio/<provider>+```++**Python:**+```bash+pip install composio-<provider>+# or+uv pip install composio-<provider>+```++**Examples:**+```bash+# TypeScript+npm install @composio/core @composio/openai++# Python+pip install composio-openai+```++## Available Framework Skills++Use `/building-agents-using-<framework>` to access specific guides:++### 1. **building-agents-using-openai**+Build agents using OpenAI's Chat Completions API, Assistants API, and Agents API.+- **Languages**: TypeScript, Python+- **Key Features**: Function calling, streaming, parallel tool calls+- **Models**: GPT-4o, GPT-4o-mini, GPT-4 Turbo+- **Use Cases**: General-purpose agents, chatbots, automation++**Invoke:** `/building-agents-using-openai`++### 2. **building-agents-using-anthropic**+Build agents using Anthropic's Codex API and Codex Agent SDK.+- **Languages**: TypeScript, Python+- **Key Features**: Prompt caching, long context, thinking blocks+- **Models**: Codex 3.7 Sonnet, Codex 3.5 Sonnet, Codex 3 Opus+- **Use Cases**: Complex reasoning, code analysis, long documents++**Invoke:** `/building-agents-using-anthropic`++### 3. **building-agents-using-langchain**+Build agents using LangChain and LangGraph for production workflows.+- **Languages**: TypeScript, Python+- **Key Features**: Graph-based agents, middleware, state management+- **Framework**: LangGraph recommended for production+- **Use Cases**: Multi-step workflows, RAG with actions, complex agents++**Invoke:** `/building-agents-using-langchain`++### 4. **building-agents-using-langgraph**+Build stateful, durable agents using LangGraph (v1.0).+- **Languages**: TypeScript, Python+- **Key Features**: Durable execution, human-in-the-loop, persistent memory+- **Status**: Production-ready (v1.0 released late 2025)+- **Use Cases**: Long-running workflows, supervised agents, multi-agent systems++**Invoke:** `/building-agents-using-langgraph`++### 5. **building-agents-using-google**+Build agents using Google's Gemini API and GenAI SDK.+- **Languages**: TypeScript, Python+- **Key Features**: Compositional function calling, parallel execution, thinking+- **Models**: Gemini 3 Flash/Pro, Gemini 2.5 Flash/Pro+- **Use Cases**: Multi-step workflows, location-based services, data analysis++**Invoke:** `/building-agents-using-google`++### 6. **building-agents-using-vercel**+Build agents using Vercel AI SDK for TypeScript/JavaScript applications.+- **Languages**: TypeScript, JavaScript+- **Key Features**: ToolLoopAgent, streaming, multi-provider support (40+)+- **Frameworks**: Next.js, Node.js, React, Vue, Svelte+- **Use Cases**: AI chatbots, web applications, full-stack AI++**Invoke:** `/building-agents-using-vercel`++### 7. **building-agents-using-llamaindex**+Build RAG-enhanced agents using LlamaIndex.+- **Languages**: TypeScript, Python+- **Key Features**: ReAct agents, query engines as tools, workflows+- **Framework**: Workflows 1.0 for complex agentic systems+- **Use Cases**: RAG + actions, documentation bots, code assistants++**Invoke:** `/building-agents-using-llamaindex`++### 8. **building-agents-using-mastra**+Build agents using Mastra, the modern TypeScript framework from the Gatsby team.+- **Languages**: TypeScript+- **Key Features**: Autonomous agents, 40+ model providers, streaming+- **Status**: v1.0 released January 2026+- **Use Cases**: GitHub automation, web search, multi-tool workflows++**Invoke:** `/building-agents-using-mastra`++### 9. **building-agents-using-cloudflare**+Build edge-deployed agents using Cloudflare Workers AI and Agents SDK.+- **Languages**: TypeScript, JavaScript+- **Key Features**: Edge deployment, embedded function calling, Durable Objects+- **Platform**: Cloudflare Workers, Workers AI+- **Use Cases**: Low-latency agents, real-time chat, API orchestration++**Invoke:** `/building-agents-using-cloudflare`++### 10. **building-agents-using-crewai**+Build multi-agent teams using CrewAI for collaborative AI.+- **Languages**: Python+- **Key Features**: Role-based agents, task dependencies, YAML configs+- **Framework**: Lean, fast, independent of LangChain+- **Use Cases**: Research & reporting, content creation, data analysis++**Invoke:** `/building-agents-using-crewai`++### 11. **building-agents-using-autogen**+Build multi-agent conversational systems using Microsoft AutoGen.+- **Languages**: Python+- **Key Features**: Multi-agent chat, AutoGen Studio, event-driven core+- **Status**: Microsoft Agent Framework is the successor+- **Use Cases**: Multi-agent conversations, research, customer support++**Invoke:** `/building-agents-using-autogen`++## Finding Latest SDK Versions++Each skill includes commands to find the latest versions of both Composio packages and provider SDKs.++### Find Latest Composio Package Version++**NPM (TypeScript):**+```bash+npm view @composio/<provider> version+# Example+npm view @composio/openai version+```++**PyPI (Python):**+```bash+pip index versions composio-<provider> | grep "Available versions" | head -1+# Example+pip index versions composio-openai | grep "Available versions" | head -1+```++### Find Latest Provider SDK Version++**NPM (TypeScript):**+```bash+npm view <provider-package> version+# Example+npm view openai version+```++**PyPI (Python):**+```bash+pip index versions <provider-package> | grep "Available versions" | head -1+# Example+pip index versions openai | grep "Available versions" | head -1+```++## Tool Router vs Direct Tools++Composio SDK supports two integration methods based on the provider type:++### 🤖 Agentic Providers (Tool Router ONLY)++These frameworks support full modifier capabilities and **MUST use Tool Router** for user-isolated sessions:++| Framework | Package | Why Tool Router |+|-----------|---------|----------------|+| **Vercel AI SDK** | `@composio/vercel` | Multi-agent support, modifiers |+| **LangChain** | `@composio/langchain` | Complex chains, state management |+| **LangGraph** | `@composio/langchain` | Stateful workflows, durability |+| **Mastra** | `@composio/mastra` | Multi-provider routing |+| **LlamaIndex** | `@composio/llamaindex` | RAG + agents, workflows |+| **Codex Agent SDK** | `@composio/Codex-agent-sdk` | Codex agents framework |+| **OpenAI Agents** | `@composio/openai-agents` | OpenAI Agents API |+| **Cloudflare** | `@composio/cloudflare` | Edge agents, Durable Objects |+| **CrewAI** | Python | Multi-agent teams |+| **AutoGen** | Python | Multi-agent conversations |++**Tool Router Benefits:**+- ✅ **User Isolation**: Each user gets their own tool session+- ✅ **Auto-Authentication**: In-chat OAuth flows+- ✅ **Scoped Access**: Control toolkits per user+- ✅ **Connection Management**: Automatic OAuth handling+- ✅ **Production Ready**: Built for multi-user applications++### 📦 Non-Agentic Providers (Direct Tools)++These providers only support schema modifiers and use **direct tools** approach:++| Framework | Package | Why Direct Tools |+|-----------|---------|-----------------|+| **OpenAI** | `@composio/openai` | Chat Completions, Assistants API |+| **Anthropic** | `@composio/anthropic` | Codex Messages API |+| **Google Gemini** | `@composio/google` | GenAI SDK |++**Direct Tools Characteristics:**+- ✅ Simpler for single-user apps+- ✅ No session management needed+- ⚠️ Not suitable for multi-user production apps+- ⚠️ Manual authentication required++### Tool Router Quick Start++```typescript+import { Composio } from '@composio/core';+import { OpenAI } from 'openai';++const composio = new Composio();+const openai = new OpenAI();++async function runAgent(userId: string, prompt: string) {+ // Create isolated session for user+ const session = await composio.create(userId, {+ toolkits: ['github'],+ manageConnections: true // Enable auto-authentication+ });++ // Get tools from session+ const tools = await session.tools();++ // Use with OpenAI+ const response = await openai.chat.completions.create({+ model: 'gpt-4o',+ messages: [{ role: 'user', content: prompt }],+ tools: tools,+ });++ // Handle tool calls+ if (response.choices[0].message.tool_calls) {+ const result = await composio.provider.handleToolCalls(userId, response);+ return result;+ }+}++// Each user gets isolated tools+await runAgent('user_123', 'Create a GitHub issue');+await runAgent('user_456', 'Check my Gmail'); // Different user, different session+```++### Tool Router with Framework Integration++Each framework skill includes Tool Router examples. See:+- `/building-agents-using-openai` - Tool Router with OpenAI+- `/building-agents-using-anthropic` - Tool Router with Codex+- `/building-agents-using-vercel` - Tool Router with Vercel AI SDK+- And all other framework skills++### Learn More About Tool Router++For comprehensive Tool Router documentation, use:+```bash+/composio-tool-router+```++## Quick Start Example++Here's a quick example using OpenAI with direct tools (single-user):++### TypeScript++```typescript+import { Composio } from '@composio/core';+import { OpenAI } from 'openai';++const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });++// Get tools+const tools = await composio.tools.get('default', { toolkits: ['github'] });++// Use with OpenAI+const response = await openai.chat.completions.create({+ model: 'gpt-4o',+ messages: [{ role: 'user', content: 'Create a GitHub issue' }],+ tools: tools,+});++// Handle tool calls+if (response.choices[0].message.tool_calls) {+ const result = await composio.provider.handleToolCalls('default', response);+ console.log(result);+}+```++### Python++```python+from composio_openai import ComposioToolSet, Action+from openai import OpenAI++openai_client = OpenAI(api_key="YOUR_OPENAI_KEY")+composio_toolset = ComposioToolSet(api_key="YOUR_COMPOSIO_KEY")++# Get tools+tools = composio_toolset.get_tools(actions=[Action.GITHUB_CREATE_ISSUE])++# Use with OpenAI+response = openai_client.chat.completions.create(+ model="gpt-4o",+ messages=[{"role": "user", "content": "Create a GitHub issue"}],+ tools=tools,+)++# Handle tool calls+result = composio_toolset.handle_tool_calls(response)+```++## Provider Comparison++| Provider | Languages | Best For | Complexity | Maturity |+|----------|-----------|----------|------------|----------|+| OpenAI | TS, Py | General purpose, function calling | Low | Mature |+| Anthropic | TS, Py | Complex reasoning, long context | Low | Mature |+| LangChain | TS, Py | Prototyping multi-agent workflows | Medium | Mature |+| LangGraph | TS, Py | Production stateful agents | High | Mature (v1.0) |+| Google Gemini | TS, Py | Compositional function calling | Low | Mature |+| Vercel AI SDK | TS | Full-stack web applications | Low | Mature (v6.0) |+| LlamaIndex | TS, Py | RAG + agents | Medium | Mature |+| Mastra | TS | Modern TypeScript apps | Low | New (v1.0 2026) |+| Cloudflare | TS | Edge-deployed agents | Medium | Growing |+| CrewAI | Py | Multi-agent teams | Medium | Mature |+| AutoGen | Py | Research multi-agent systems | High | Mature |++## Common Composio Features++All frameworks support these Composio features:++### 1. Tool Management+```typescript+// Get tools by app+const tools = await composio.tools.get('default', { apps: ['github', 'slack'] });++// Get specific actions+const tools = await composio.tools.get('default', { actions: ['GITHUB_CREATE_ISSUE'] });++// Get by toolkit+const tools = await composio.tools.get('default', { toolkits: ['github'] });+```++### 2. Connected Accounts+```typescript+// Manage user integrations+const account = await composio.connectedAccounts.initiate({+ integrationId: 'github',+ entityId: 'user-123',+});+```++### 3. Custom Tools+```typescript+// Create custom tools+const customTool = await composio.tools.createCustomTool({+ name: 'My Tool',+ description: 'Tool description',+ execute: async (input) => {+ // Implementation+ return { data: 'result' };+ },+});+```++## Environment Variables++Most examples require:++```bash+# Composio+COMPOSIO_API_KEY=...++# LLM Provider (choose one or more)+OPENAI_API_KEY=sk-...+ANTHROPIC_API_KEY=sk-ant-...+GOOGLE_API_KEY=...+```++## Documentation Resources++- **Composio Docs**: https://docs.composio.dev/+- **Composio GitHub**: https://github.com/composiohq/composio-sdk+- **API Reference**: https://docs.composio.dev/api-reference+- **Examples**: Check `ts/examples/` and `python/examples/` in this repository++## Getting Help++- **Discord**: https://discord.gg/composio+- **GitHub Issues**: https://github.com/composiohq/composio-sdk/issues+- **Documentation**: https://docs.composio.dev/++## Next Steps++1. Choose a framework from the list above+2. Invoke the corresponding skill (e.g., `/building-agents-using-openai`)+3. Follow the installation and setup instructions+4. Try the code examples+5. Build your agent!++## Tips++- **Start simple** - Begin with OpenAI or Anthropic for easiest setup+- **Use LangGraph** for production stateful agents+- **Try Vercel AI SDK** for full-stack web applications+- **Use CrewAI** for multi-agent collaborative systems+- **Check examples** in the repository for working code+- **Read framework docs** linked in each skill for advanced featuresdiff --git a/.agents/skills/create-cli-e2e/SKILL.md b/.agents/skills/create-cli-e2e/SKILL.mdnew file mode 100644index 000000000..49a566956--- /dev/null+++ b/.agents/skills/create-cli-e2e/SKILL.md@@ -0,0 +1,438 @@+---+description: Write end-to-end tests for CLI commands using the Docker-based test framework in ts/e2e-tests/cli/.+---++# CLI E2E Test Development++Write, expand, and maintain end-to-end tests for CLI commands in `ts/e2e-tests/cli/`.++## When to Use++- Adding a new e2e test suite for a CLI command+- Modifying or extending an existing CLI e2e test+- Debugging a failing CLI e2e test+- Reviewing whether a CLI command's output contract is properly tested++For CLI **design** (arguments, flags, help text, UX), see the `create-cli` skill.+For CLI **implementation** (Effect patterns, services, command registration), see the `implement-cli-command` skill.++## Architecture++Each CLI e2e test runs the compiled `composio` binary inside a **scratch Debian Docker container**. The binary is self-contained (built via `bun build --compile`) — no Node, Bun, or pnpm exists in the runtime image.++Key properties:++- Each test suite = a directory under `ts/e2e-tests/cli/<suite-name>/`+- Use `runCmd` only. Never use `runFixture` (throws an error for CLI tests). Never set `usesFixtures`.+- **Each `runCmd` call creates a fresh container.** No state persists between calls.+- Commands run inside `sh -c '...'` — POSIX shell only, no bash-isms.+- Containers have network access — API-calling commands work.+- `HOME=/tmp`, cache dir is `/tmp/.composio/` — auth passes via env vars only.+- `process.stdout.isTTY` is always `false` inside Docker — the CLI always runs in piped mode.++### What "piped mode" means for tests++Inside Docker, the composio binary's stdout is never a TTY. This triggers the CLI's piped-mode behavior (see `ts/packages/cli/AGENTS.md` § "Output Conventions"):+- `ui.output()` writes to stdout+- All Clack decoration is suppressed+- stderr is empty for successful commands++## File Structure++For a new test suite `<suite-name>`, create 2 files:++```+ts/e2e-tests/cli/<suite-name>/+├── e2e.test.ts # Test file+└── package.json # Package manifest+```++### Naming Conventions++- **Directory**: hyphen-separated lowercase matching the command structure+ - `version`, `whoami`, `toolkits-list`, `tools-info`, `auth-configs-list`, `connected-accounts-link`+- **Package name**: `@e2e-tests/cli-<suite-name>`+ - `@e2e-tests/cli-version`, `@e2e-tests/cli-toolkits-list`++### package.json Template++```json+{+ "name": "@e2e-tests/cli-<suite-name>",+ "version": "0.0.0",+ "private": true,+ "type": "module",+ "scripts": {+ "typecheck": "tsc --noEmit",+ "test:e2e": "bun test e2e.test.ts",+ "test:e2e:cli": "bun test e2e.test.ts"+ },+ "devDependencies": {+ "@e2e-tests/utils": "workspace:*"+ }+}+```++## Choosing a Test Pattern++Use this decision tree to select the right pattern:++```+Does the command need env vars (e.g., COMPOSIO_API_KEY)?+├─ No → Is the output deterministic (exact value known at test time)?+│ ├─ Yes → Pattern A (simple command, exact assertions)+│ └─ No → Pattern D (fuzzy assertions: toContain, toBeGreaterThan)+└─ Yes → Is the output deterministic given the env?+ ├─ Yes → Pattern B (env vars + exact assertions)+ └─ No → Pattern D (env vars + fuzzy assertions)++Are you testing an error case (missing args, invalid input)?+└─ Yes → Pattern C (non-zero exit code, stderr non-empty)++Does the command perform an action with no machine-readable output?+└─ Yes → Pattern E (exitCode=0, stdout empty, no redirect test)+```++## Test Patterns++### Pattern A: Simple Command, No Env Vars (Canonical)++For commands that produce deterministic output without needing authentication. This is the base pattern — all other patterns are variations of this.++**Reference**: `ts/e2e-tests/cli/version/e2e.test.ts`++```typescript+/**+ * CLI version command e2e test+ *+ * Verifies that the compiled composio CLI behaves correctly in a scratch container.+ */++import { e2e, sanitizeOutput, type E2ETestResult, type E2ETestResultWithFiles } from '@e2e-tests/utils';+import { TIMEOUTS } from '@e2e-tests/utils/const';+import { describe, it, expect, beforeAll } from 'bun:test';+import cliPkg from '../../../packages/cli/package.json' with { type: 'json' };++e2e(import.meta.url, {+ versions: {+ cli: ['current'],+ },+ defineTests: ({ runCmd }) => {+ const expectedVersion = String(cliPkg.version ?? '').trim();+ let versionResult: E2ETestResult;+ let redirectedResult: E2ETestResultWithFiles<'out.txt'>;++ beforeAll(async () => {+ versionResult = await runCmd('composio version');+ redirectedResult = await runCmd({+ command: 'composio version > out.txt',+ files: ['out.txt'],+ });+ }, TIMEOUTS.FIXTURE);++ describe('composio version', () => {+ it('exits successfully', () => {+ expect(versionResult.exitCode).toBe(0);+ });++ it('stdout matches snapshot', () => {+ expect(sanitizeOutput(versionResult.stdout)).toBe(expectedVersion);+ });++ it('stderr matches snapshot', () => {+ expect(versionResult.stderr).toBe('');+ });+ });++ describe('stdout redirection to out.txt', () => {+ it('exits successfully', () => {+ expect(redirectedResult.exitCode).toBe(0);+ });++ it('stdout is empty', () => {+ expect(redirectedResult.stdout).toBe('');+ });++ it('stderr is empty', () => {+ expect(redirectedResult.stderr).toBe('');+ });++ it('out.txt matches snapshot', () => {+ expect(sanitizeOutput(redirectedResult.files['out.txt'])).toBe(expectedVersion);+ });+ });+ },+});+```++**Structure summary:**+- Two test groups: **command execution** (stdout has data, stderr empty) + **stdout redirection** (file has data, Docker stdout/stderr both empty)+- Use `sanitizeOutput()` on stdout and file contents before assertions+- Use `TIMEOUTS.FIXTURE` for the `beforeAll` that runs Docker commands++### Pattern B: Command Requiring Env Vars++**Same as Pattern A**, with three additions:++**Reference**: `ts/e2e-tests/cli/whoami/e2e.test.ts`++1. **Type augmentation** for compile-time safety on `Bun.env`:+ ```typescript+ declare module 'bun' {+ interface Env {+ COMPOSIO_API_KEY: string;+ }+ }+ ```++2. **Pass env vars** in the config:+ ```typescript+ env: {+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,+ },+ ```++3. **Derive expected values** from the env:+ ```typescript+ const expectedApiKey = Bun.env.COMPOSIO_API_KEY.trim();+ ```++The rest follows the same two-group structure (command execution + stdout redirection).++### Pattern C: Error Case Testing++**Differences from Pattern A:**+- No stdout redirection test needed — error cases don't produce data output+- Assert non-zero exit code with `not.toBe(0)` (don't hardcode a specific error code)+- Assert stderr is non-empty; optionally use `toContain()` for specific error message fragments+- Import only `E2ETestResult`, not `E2ETestResultWithFiles`++```typescript+import { e2e, sanitizeOutput, type E2ETestResult } from '@e2e-tests/utils';+import { TIMEOUTS } from '@e2e-tests/utils/const';+import { describe, it, expect, beforeAll } from 'bun:test';++e2e(import.meta.url, {+ versions: { cli: ['current'] },+ defineTests: ({ runCmd }) => {+ let missingArgResult: E2ETestResult;++ beforeAll(async () => {+ missingArgResult = await runCmd('composio manage tools info');+ }, TIMEOUTS.FIXTURE);++ describe('composio manage tools info (missing argument)', () => {+ it('exits with non-zero code', () => {+ expect(missingArgResult.exitCode).not.toBe(0);+ });+ it('stderr contains an error message', () => {+ expect(missingArgResult.stderr).not.toBe('');+ });+ });+ },+});+```++Pattern C can be combined with A or B in the same test file to test both success and error paths.++### Pattern D: Multi-line / API-dependent Output++**Same structure as Pattern A or B** (depending on whether env vars are needed), with different assertion strategies:++- **Never use exact-match assertions** (`toBe`) on API data — the data changes over time.+- Use `toContain()` for known, stable items (e.g., `github`, `gmail` are always present).+- Use `toBeGreaterThan()` for structural checks (line count, length).+- Use `toMatch()` with regex for format validation.++```typescript+// Instead of:+expect(sanitizeOutput(listResult.stdout)).toBe(exactValue);++// Use fuzzy assertions:+expect(sanitizeOutput(listResult.stdout).length).toBeGreaterThan(0);+expect(sanitizeOutput(listResult.stdout)).toContain('github');+const lines = sanitizeOutput(listResult.stdout).split('\n').filter(Boolean);+expect(lines.length).toBeGreaterThan(1);+```++The redirect test group is identical to Pattern A — assert the file contains data, Docker stdout/stderr are empty.++### Pattern E: Action Command, No Stdout Data++For commands that perform an action but produce no machine-readable output (e.g., `logout`, `upgrade`).++**Differences from Pattern A:**+- No redirection test — there's no data to redirect+- stdout should be literally empty (no `sanitizeOutput()` needed)+- Import only `E2ETestResult`, not `E2ETestResultWithFiles`++```typescript+e2e(import.meta.url, {+ versions: { cli: ['current'] },+ defineTests: ({ runCmd }) => {+ let logoutResult: E2ETestResult;++ beforeAll(async () => {+ logoutResult = await runCmd('composio logout');+ }, TIMEOUTS.FIXTURE);++ describe('composio logout', () => {+ it('exits successfully', () => {+ expect(logoutResult.exitCode).toBe(0);+ });++ it('stdout is empty', () => {+ expect(logoutResult.stdout).toBe('');+ });++ it('stderr is empty', () => {+ expect(logoutResult.stderr).toBe('');+ });+ });+ },+});+```++## Commands NOT Testable with This Framework++Do not attempt to write e2e tests for:++| Category | Examples | Why |+|---|---|---|+| **Interactive commands** | `login`, `init` (with prompts) | No TTY in Docker — Clack prompts hang |+| **Long-running commands** | `triggers listen` | No mechanism to stop the process |+| **Browser-dependent commands** | `login` (without `--no-browser`) | No browser in Docker |+| **Host filesystem writers** | `generate` (writes to project dir) | Docker container is isolated |++## Environment Variables++### Auto-passed vars++`COMPOSIO_API_KEY` and `OPENAI_API_KEY` are automatically forwarded to Docker containers if present on the host (defined in `WELL_KNOWN_ENV_VARS`).++### Declaring required vars++For tests that need env vars:++1. Add the `declare module 'bun'` augmentation (compile-time safety).+2. Pass via `E2EConfig.env` (runtime delivery to Docker).+3. If any `E2EConfig.env` value is `undefined`, the test fails fast at startup — before any Docker container runs.++### Multiple env vars++```typescript+declare module 'bun' {+ interface Env {+ COMPOSIO_API_KEY: string;+ COMPOSIO_BASE_URL: string;+ }+}++e2e(import.meta.url, {+ env: {+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,+ COMPOSIO_BASE_URL: Bun.env.COMPOSIO_BASE_URL,+ },+ // ...+});+```++## Shell Quoting++Commands run inside `sh -c '...'` in a POSIX shell. Rules:++- Use double quotes for flag values with spaces or special chars:+ ```typescript+ runCmd('composio manage tools info "GMAIL_SEND_EMAIL"')+ ```+- Use single quotes inside double-quoted contexts for literal strings.+- **No bash-isms**: no `[[`, no `$()`, no arrays.+- `PATH` is `/usr/local/bin:/bin` — set in the Dockerfile.++## Checklist for Adding a New Test Suite++1. **Create directory**: `ts/e2e-tests/cli/<suite-name>/`+2. **Create `package.json`**: Use the template above with name `@e2e-tests/cli-<suite-name>`+3. **Create `e2e.test.ts`**: Follow the appropriate pattern (A through E)+4. **Run `pnpm install`** from the monorepo root to resolve the workspace link+5. **Run `pnpm test:e2e:cli`** to verify the test passes+6. **Update `ts/e2e-tests/cli/README.md`**: Add a new row to the test suites table++### README table format++```markdown+| [suite-name](./suite-name/) | `composio <command>` description | `ENV_VAR_1`, `ENV_VAR_2` (or None) |+```++## Troubleshooting++### Reading DEBUG.log++Each test suite generates a `DEBUG.log` in its directory with Docker execution details: container name, command, duration, exit code, stdout, stderr. Read this first when a test fails.++### Stale Docker image++If CLI code changed but tests show old behavior, the Docker image is cached. Rebuild:++```bash+docker rmi composio-e2e-cli:$(jq -r .version ts/packages/cli/package.json)+```++### Shell quoting issues++Check the command string in `DEBUG.log`. Look for unescaped special characters that break `sh -c` parsing.++### Missing env vars++The error appears at test startup (before any Docker container runs), not during execution. Verify `Bun.env.*` values are set in your shell.++### Container statelessness++Each `runCmd` call runs in a fresh container. If you need to test a multi-step workflow (e.g., "set config then run command"), you must chain commands in a single `runCmd` call:++```typescript+runCmd('composio logout && composio whoami')+```++## API Reference++### `runCmd` (two overloads)++```typescript+// Simple: returns { exitCode, stdout, stderr }+const result: E2ETestResult = await runCmd('composio version');++// With file capture: returns { exitCode, stdout, stderr, files }+const result: E2ETestResultWithFiles<'out.txt'> = await runCmd({+ command: 'composio version > out.txt',+ files: ['out.txt'],+});+// Access: result.files['out.txt']+```++### `TIMEOUTS`++Defined in `ts/e2e-tests/_utils/src/const.ts`:++```typescript+TIMEOUTS.DEFAULT // 5_000ms — individual test timeout+TIMEOUTS.FIXTURE // 120_000ms — beforeAll timeout (Docker startup + command execution)+TIMEOUTS.LLM_SHORT // 30_000ms — commands involving LLM calls+TIMEOUTS.LLM_LONG // 60_000ms — commands involving longer LLM calls+```++Use `TIMEOUTS.FIXTURE` for the `beforeAll` that runs Docker commands. Use `TIMEOUTS.DEFAULT` for individual `it()` blocks (the default).++## Reference Files++| File | Purpose |+|---|---|+| `ts/e2e-tests/cli/version/e2e.test.ts` | Pattern A reference |+| `ts/e2e-tests/cli/whoami/e2e.test.ts` | Pattern B reference |+| `ts/e2e-tests/_utils/src/types.ts` | `E2EConfig`, `E2ETestResult`, `DefineTestsContext` types |+| `ts/e2e-tests/_utils/src/const.ts` | `TIMEOUTS`, `WELL_KNOWN_ENV_VARS` |+| `ts/e2e-tests/_utils/src/sanitize.ts` | `sanitizeOutput()` |+| `ts/e2e-tests/_utils/Dockerfile.cli` | Docker image definition |+| `ts/e2e-tests/cli/README.md` | Test suites table |+| `CLI.md` | Planned CLI commands |+| `ts/packages/cli/AGENTS.md` | CLI architecture and output conventions |diff --git a/.agents/skills/create-cli/SKILL.md b/.agents/skills/create-cli/SKILL.mdnew file mode 100644index 000000000..0afdb46a1--- /dev/null+++ b/.agents/skills/create-cli/SKILL.md@@ -0,0 +1,240 @@+---+description: CLI design guidelines — arguments, flags, subcommands, help, output, errors, interactivity, config precedence. Apply when designing new commands or reviewing CLI UX.+globs:+ - "ts/packages/cli/src/**/*.ts"+alwaysApply: false+---++# CLI Design Guidelines++Design CLI surface area (syntax + behavior), human-first, script-friendly.+Adapted from [clig.dev](https://clig.dev/) for our TypeScript + Effect.ts + Clack stack.++## When to Use++- Designing a CLI spec (before implementation) or refactoring CLI surface area.+- Adding new commands, flags, or interactive prompts.+- Reviewing CLI UX decisions.++After designing a command, use the `implement-cli-command` skill to build it.+After implementation, use the `create-cli-e2e` skill to write end-to-end tests.++## Stack & Architecture++See `ts/packages/cli/AGENTS.md` for the full architecture reference, including dependencies, services, effects, and vendor submodule locations.++## Output Conventions++The CLI separates human-readable decoration from machine-readable data. See `ts/packages/cli/AGENTS.md` § "Output Conventions" for the full specification.++Key rule: when adding a command, ask "Does this produce a value scripts should capture?"+- **Yes** → `ui.output(value)` for data, `ui.log.*` / `ui.note()` for context.+- **No** → Only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()`.++**Show state changes.** When a command modifies state, say what changed and the new state:++```typescript+// After logout:+yield* ui.log.info('Removed API key from ~/.composio/user-config.json');++// After generate:+yield* ui.log.success('Generated 42 tools across 5 toolkits → src/generated/');+```++## Arguments & Flags++Define options via `@effect/cli`:++```typescript+const toolkits = Options.text('toolkits').pipe(+ Options.optional,+ Options.withDescription('Comma-separated toolkit slugs'),+);+const force = Options.boolean('force').pipe(+ Options.withAlias('f'),+ Options.withDefault(false),+);+```++Principles:+- Prefer flags over positional args for clarity and extensibility.+- Provide long versions of all flags; one-letter aliases only for the most common.+- Default values should be right for most users.+- Never accept secrets via flags — they leak to `ps` output and shell history. Use `--password-file`, stdin, or a secret manager instead.+- Support `-` for stdin/stdout when input/output is a file path.++Standard flag names:++| Flag | Short | Purpose |+| ---- | ----- | ------- |+| `--help` | `-h` | Show help (built-in via @effect/cli) |+| `--version` | | Print version to stdout |+| `--quiet` | `-q` | Less output |+| `--verbose` | `-v` | More output (never use `-v` for version) |+| `--debug` | `-d` | Debug output |+| `--force` | `-f` | Skip confirmations |+| `--dry-run` | `-n` | Preview only |+| `--json` | | Structured output |+| `--output` | `-o` | Output file path |+| `--no-input` | | Disable prompts; fail if required input missing |+| `--no-browser` | | Skip browser-open steps |+| `--no-color` | | Disable color output |++## Subcommands++```typescript+const login = Command.make('login', { noBrowser }, handler);+const generate = Command.make('generate', { toolkits, typeTools }, handler);+const root = Command.make('composio').pipe(+ Command.withSubcommands([login, generate, /* ... */]),+);+```++- Follow verb-noun pattern consistently: `composio login`, `composio generate`.+- Share global flags via parent command composition.+- Support `composio help <subcmd>` and `composio <subcmd> --help`.+- Avoid ambiguous pairs (`update` vs `upgrade`) unless sharply differentiated.++## Interactivity++Use `@clack/prompts` for all interactive UI. All Clack output goes to stderr via `{ output: process.stderr }`.++| Prompt | When to use |+| ------ | ----------- |+| `text()` | Free-form text input |+| `password()` | Secret input (echo disabled) |+| `confirm()` | Yes/no decisions |+| `select()` | Choose one from a list |+| `multiselect()` | Choose multiple from a list |+| `spinner()` | Long-running operations |+| `log.info/warn/error/step()` | Styled status messages |+| `note()` | Boxed contextual info |+| `intro()` / `outro()` | Session start/end markers |++Rules:+- Prompt only if stdin is a TTY.+- `--no-input`: never prompt; fail with actionable message if required input missing.+- Make escape hatches obvious (Ctrl-C).+- Destructive operations: interactive confirmation + non-interactive requires `--force`.++## Error Handling++- Use the `effect-errors/` module for capture and formatting.+- Catch and rewrite expected errors for humans; no stack traces by default.+- Put the most important info last; use red intentionally.+- For unexpected crashes: provide debug info path + bug report instructions.++**Write actionable error messages.** Tell the user *what went wrong* and *how to fix it*:++```+// Bad:+Error: EACCES++// Good:+Can't write to ~/.composio/user-config.json.+You might need to fix permissions: chmod +w ~/.composio/user-config.json++// Bad:+Error: 401++// Good:+API key is invalid or expired.+Run `composio login` to authenticate again.+```++**Suggest corrections** when the user mistypes a subcommand or flag. If they ran `composio genrate`, suggest `composio generate`.++Exit codes:++| Code | Meaning |+| ---- | ------- |+| `0` | Success |+| `1` | Generic failure |+| `2` | Invalid usage (parse/validation error) |++## Help & Documentation++- `@effect/cli` generates help text from Command/Options declarations.+- If run with missing required args, show concise help + 1–2 examples + "use --help for more".+- Lead with examples; show common flags first.+- Link to docs URL per subcommand when applicable.+- Provide both terminal help (offline, version-synced) and web docs (searchable, linkable).++Good help text structure:++```+USAGE+ $ composio generate [--toolkits <slugs>] [--type-tools]++OPTIONS+ --toolkits <slugs> Comma-separated toolkit slugs (default: all)+ --type-tools Generate full type definitions+ -o, --output <dir> Output directory (default: @composio/core/generated)++EXAMPLES+ $ composio generate+ $ composio generate --toolkits github,slack --type-tools++COMMANDS+ composio generate ts Generate TypeScript stubs+ composio generate py Generate Python stubs+```++**Suggest next commands** when it helps the user's flow:++```+✔ Logged in as [email protected]+ Next: run `composio generate` to generate type stubs for your toolkits.+```++## Configuration Precedence++High to low: **flags > process env > project config > user config > system config**.++- Composio prefixes: `COMPOSIO_*` for app config, `DEBUG_OVERRIDE_*` for debug.+- User config stored in `~/.composio/`.+- Respect common env vars: `NO_COLOR`, `DEBUG`, `EDITOR`, `PAGER`, `TERM`, `TMPDIR`, `HOME`.++## Naming++- Subcommand names: simple, lowercase, single word when possible.+- Avoid too-generic names that collide with system tools.+- Keep names short but not cryptic — easy to type matters.+- Never create implicit catch-all subcommands that prevent future expansion.+- Don't allow arbitrary abbreviations (reserving `g` for `generate` blocks future `g`-commands).+- Use explicit aliases only when there's a clear, stable mapping.++## Robustness & Performance++- Validate early; fail fast with good error messages.+- Print something within ~100ms (especially before network I/O). Start a Clack spinner immediately before any network call.+- Show progress for long tasks (interactive only) via Clack spinners.+- Use timeouts for network calls; allow configuration.+- Make reruns safe: idempotent where possible; recoverable on failure.+- **Crash-only design**: assume cleanup might not run. Defer cleanup to the next invocation rather than relying on shutdown hooks. If a cache file is half-written, the next run should detect and rebuild it.++## Example Invocations++```bash+# Interactive — user sees Clack decoration on stderr+composio login+composio generate --toolkits github,slack++# Piped — only data on stdout, no decoration+composio whoami | pbcopy+API_KEY=$(composio whoami)+composio version | cat++# Non-interactive with force+composio logout --force --no-input++# Debug mode+composio generate --debug --verbose+```++## References++- Community CLI Guidelines: https://clig.dev/+- CLI architecture: `ts/packages/cli/AGENTS.md`+- @effect/cli source: `ts/vendor/effect/packages/cli/src/`+- @clack/prompts source: `ts/vendor/clack/packages/prompts/src/`diff --git a/.agents/skills/ephemeral-e2e-sdk-tests/SKILL.md b/.agents/skills/ephemeral-e2e-sdk-tests/SKILL.mdnew file mode 100644index 000000000..8c0b402a3--- /dev/null+++ b/.agents/skills/ephemeral-e2e-sdk-tests/SKILL.md@@ -0,0 +1,49 @@+# Ephemeral E2E SDK Tests++Quick ephemeral verification tests for Composio SDK with AI frameworks. Never commit these tests.++## Important Distinction++- **Ephemeral tests** (this skill): Quick verification in `.agent_cache/test-<usecase>` - never committed+- **Actual E2E tests that run in CI**: Use `ts/e2e-tests/` - committed to repository++## Quick Setup++```bash+# Use descriptive usecase names (e.g., openai-direct-tools, vercel-tool-router, anthropic-mcp)+TEST_DIR=".agent_cache/test-<usecase>"+mkdir -p "$TEST_DIR" && cd "$TEST_DIR"+npm init -y+npm install @composio/core # Add framework-specific packages as needed+```++## What to Test++- **Direct Tools (Non-Agentic)**: SDK integration with AI frameworks without Tool Router+- **Tool Router (Agentic)**: User-isolated sessions with Tool Router+- **MCP Integration**: MCP protocol compatibility+- **Framework Compatibility**: Different AI frameworks (OpenAI, Vercel, Anthropic, etc.)++## Implementation Examples++For implementation examples, refer to existing skills:++- **Tool Router basics**: Read `building-agents` skill+- **OpenAI integration**: Read `building-agents-using-openai` skill+- **Vercel AI SDK**: Read `building-agents-using-vercel` skill+- **Anthropic**: Read `building-agents-using-anthropic` skill+- **LangChain**: Read `building-agents-using-langchain` skill+- **Other frameworks**: Check respective `building-agents-using-*` skills++## Clean Up++```bash+cd .. && rm -rf "$TEST_DIR"+```++## Best Practices++- **Always use .agent_cache** - These are ephemeral, never commit+- **For CI E2E tests** - Use `ts/e2e-tests/` instead (see `ts/e2e-tests/README.md`)+- **Use non-auth apps** - HackerNews, Public APIs for quick testing+- **Report critical issues** - Add proper test cases to `ts/e2e-tests/` if neededdiff --git a/.agents/skills/implement-cli-command/SKILL.md b/.agents/skills/implement-cli-command/SKILL.mdnew file mode 100644index 000000000..2ce528966--- /dev/null+++ b/.agents/skills/implement-cli-command/SKILL.md@@ -0,0 +1,545 @@+---+description: Implement new CLI commands in ts/packages/cli/ using Effect.ts patterns, service wiring, and @effect/cli declarations.+---++# Implement CLI Command++Implement new commands and subcommands in `ts/packages/cli/`. Covers file creation, Effect patterns, service wiring, option declaration, output conventions, and registration.++## When to Use++- Implementing a new CLI command from a spec or design+- Adding a subcommand to an existing command group+- Wiring a new command into the command tree+- Understanding how existing commands work to extend them++For CLI **design** (arguments, flags, help text, UX), see the `create-cli` skill instead.+For CLI **e2e tests**, see the `create-cli-e2e` skill instead.++## Architecture++The CLI uses `@effect/cli` for command declaration, `effect` for the runtime, and a service-oriented architecture with dependency injection via Effect layers.++See `ts/packages/cli/AGENTS.md` for the full architecture reference (services, effects, models, dependencies, vendor submodule locations).++```+src/+├── bin.ts # Entry point — layer composition, error handling, runtime+├── commands/+│ ├── index.ts # Command tree — registers all commands+│ ├── $default.cmd.ts # Root command with global options (--log-level)+│ ├── version.cmd.ts # Simple data command+│ ├── whoami.cmd.ts # Data command with service dependency+│ ├── login.cmd.ts # Complex command (options, spinner, polling)+│ ├── logout.cmd.ts # Action command (no stdout data)+│ ├── upgrade.cmd.ts # Action command (delegates to service)+│ ├── generate/+│ │ ├── generate.cmd.ts # Parent command group for `composio generate`+│ │ ├── generate-py.cmd.ts # `composio generate py`+│ │ └── generate-ts.cmd.ts # `composio generate ts`+│ ├── manage/+│ │ └── manage.cmd.ts # Parent command group for `composio manage`+│ ├── ts/+│ │ ├── ts.cmd.ts # Existing TS generation internals, referenced from generate/+│ │ └── commands/+│ │ └── ts.generate.cmd.ts # Reusable TS generation logic+│ └── py/+│ ├── py.cmd.ts # Existing Python generation internals, referenced from generate/+│ └── commands/+│ └── py.generate.cmd.ts+├── services/ # Effect services (dependency injection)+├── effects/ # Reusable Effect computations+├── models/ # Effect Schema definitions+├── generation/ # Code generation pipeline+├── effect-errors/ # Error capture and formatting+└── ui/ # Terminal output helpers+```++### File Naming Convention++- Command files: `<name>.cmd.ts` (e.g., `version.cmd.ts`, `login.cmd.ts`)+- Subcommand implementation files: `<parent>.<name>.cmd.ts` inside `commands/` (e.g., `ts.generate.cmd.ts`)+- Parent command groups: `<name>.cmd.ts` at the group level (e.g., `generate/generate.cmd.ts`, `manage/manage.cmd.ts`)+- Wrapper subcommand entrypoints can also live beside their parent group (e.g., `generate/generate-py.cmd.ts`, `generate/generate-ts.cmd.ts`)++## Creating a New Command+### Step 1: Create the Command File++Create `src/commands/<name>.cmd.ts`.++**Minimal template** (data command, no options):++```typescript+import { Command } from '@effect/cli';+import { Effect } from 'effect';+import { TerminalUI } from 'src/services/terminal-ui';++export const myCmd = Command.make('my-command', {}).pipe(+ Command.withDescription('Brief description of what the command does.'),+ Command.withHandler(() =>+ Effect.gen(function* () {+ const ui = yield* TerminalUI;++ // Compute result...+ const result = 'some-value';++ yield* ui.log.info(result); // Decoration → stderr+ yield* ui.output(result); // Data → stdout (for scripts)+ })+ )+);+```++**Template with options:**++```typescript+import { Command, Options } from '@effect/cli';+import { Effect, Option } from 'effect';+import { TerminalUI } from 'src/services/terminal-ui';+import { ComposioToolkitsRepository } from 'src/services/composio-clients';++// Define options at module level+const toolkitSlug = Options.text('toolkit').pipe(+ Options.withDescription('Toolkit slug to look up.')+);++const searchOpt = Options.optional(+ Options.text('search')+).pipe(+ Options.withDescription('Search query to filter results.')+);++export const myCmd = Command.make('my-command', { toolkitSlug, searchOpt }).pipe(+ Command.withDescription('Brief description.'),+ Command.withHandler(({ toolkitSlug, searchOpt }) =>+ Effect.gen(function* () {+ const ui = yield* TerminalUI;+ const client = yield* ComposioToolkitsRepository;++ yield* ui.intro('composio my-command');++ // Use options — searchOpt is Option<string>+ const search = Option.getOrUndefined(searchOpt);++ // Fetch data with spinner+ const result = yield* ui.withSpinner(+ 'Fetching data...',+ client.getToolkits(),+ { successMessage: 'Done', errorMessage: 'Failed to fetch' }+ );++ // Output+ yield* ui.note(formatResult(result), 'Result');+ yield* ui.output(formatResult(result));+ yield* ui.outro('Done');+ })+ )+);+```++### Step 2: Register the Command++Add the command to `src/commands/index.ts`:++```typescript+import { myCmd } from './my-command.cmd';++const $cmd = $defaultCmd.pipe(+ Command.withSubcommands([+ versionCmd,+ upgradeCmd,+ whoamiCmd,+ loginCmd,+ logoutCmd,+ generateCmd,+ manageCmd,+ myCmd, // Add here+ ])+);+```++### Step 3: Add Required Service Layers (if any)++If your command uses a new service not already in `bin.ts`, add its layer:++```typescript+// In src/bin.ts+const layers = Layer.mergeAll(+ // ... existing layers+ MyNewServiceLive, // Add if needed+);+```++Most commands only use services already provided. The `ComposioToolkitsRepository` service is provided by `ComposioToolkitsRepositoryCachedLive` in `bin.ts` — you do not need to add a separate layer for the base repository.++## Creating a Subcommand Group++For commands like `composio manage toolkits list`, `composio manage toolkits info`:++### Step 1: Create the Directory Structure++```+src/commands/manage/toolkits/+├── toolkits.cmd.ts # Parent command group under `manage`+└── commands/+ ├── toolkits.list.cmd.ts # composio manage toolkits list+ └── toolkits.info.cmd.ts # composio manage toolkits info+```++### Step 2: Create the Parent Command++`src/commands/manage/toolkits/toolkits.cmd.ts`:+```typescript+import { Command } from '@effect/cli';+import { toolkitsCmd$List } from './commands/toolkits.list.cmd';+import { toolkitsCmd$Info } from './commands/toolkits.info.cmd';++export const toolkitsCmd = Command.make('toolkits').pipe(+ Command.withDescription('Discover and inspect available toolkits.'),+ Command.withSubcommands([toolkitsCmd$List, toolkitsCmd$Info])+);+```++### Step 3: Create Each Subcommand++`src/commands/manage/toolkits/commands/toolkits.list.cmd.ts`:+```typescript+import { Command, Options } from '@effect/cli';+import { Effect, Option } from 'effect';+import { TerminalUI } from 'src/services/terminal-ui';+import { ComposioToolkitsRepository } from 'src/services/composio-clients';++const searchOpt = Options.optional(+ Options.text('search')+).pipe(+ Options.withDescription('Search toolkits by name or description.')+);++export const toolkitsCmd$List = Command.make('list', { searchOpt }).pipe(+ Command.withDescription('List available toolkits.'),+ Command.withHandler(({ searchOpt }) =>+ Effect.gen(function* () {+ const ui = yield* TerminalUI;+ const client = yield* ComposioToolkitsRepository;++ const toolkits = yield* ui.withSpinner(+ 'Fetching toolkits...',+ client.getToolkits(),+ { successMessage: 'Toolkits loaded' }+ );++ // Format and output+ const output = toolkits+ .map(t => `${t.slug} - ${t.meta.description}`)+ .join('\n');++ yield* ui.log.info(output);+ yield* ui.output(output);+ })+ )+);+```++### Step 4: Register the Parent in `manage/manage.cmd.ts`++```typescript+import { Command } from '@effect/cli';+import { toolkitsCmd } from './toolkits/toolkits.cmd';++export const manageCmd = Command.make('manage').pipe(+ Command.withDescription('Manage existing Composio resources.'),+ Command.withSubcommands([+ // ... existing manage subcommands+ toolkitsCmd,+ ])+);+```++## Option Declaration Patterns+Options are declared at module level using `@effect/cli`'s `Options` API. The template above demonstrates the most common types (required text, optional text). For other option types, see `ts/vendor/effect/packages/cli/src/Options.ts`.++Both `Options.optional(Options.text(...))` (wrapping) and `Options.text(...).pipe(Options.optional)` (piped) are valid. Use whichever reads better.++### Common patterns:++```typescript+import { Options } from '@effect/cli';++// Boolean flag (with default)+const verbose = Options.boolean('verbose').pipe(+ Options.withDefault(false),+ Options.withDescription('Enable verbose output.')+);++// Text with alias+const output = Options.optional(+ Options.text('output')+).pipe(+ Options.withAlias('o'),+ Options.withDescription('Output path.')+);++// Choice from fixed set+const format = Options.choice('format', ['json', 'table', 'plain']).pipe(+ Options.withDefault('table'),+ Options.withDescription('Output format.')+);+```++### Using Options in Handler++```typescript+Command.make('my-cmd', { search, verbose }).pipe(+ Command.withHandler(({ search, verbose }) =>+ Effect.gen(function* () {+ // search: Option<string> — use Option.getOrUndefined, Option.match, Option.isSome+ const searchValue = Option.getOrUndefined(search);++ // verbose: boolean — direct use+ if (verbose) { yield* Effect.logDebug('Verbose mode'); }+ })+ )+);+```++## Output Conventions++Follow the output conventions in `ts/packages/cli/AGENTS.md` § "Output Conventions" (stdout for data via `ui.output()`, stderr for decoration).++**Data commands** — produce a value scripts should capture:++```typescript+yield* ui.note(apiKey, 'API Key'); // Decoration → stderr (pretty box)+yield* ui.output(apiKey); // Data → stdout (scripts capture)+```++**Action commands** — perform a side effect, no data:++```typescript+yield* ui.log.success('Logged out successfully.');+// NO ui.output() call — nothing for scripts to capture+```++## TerminalUI Spinners++The `TerminalUI` service provides two spinner APIs. For output/decoration methods (`output`, `log.*`, `note`, `intro`, `outro`), see `ts/packages/cli/src/services/terminal-ui.ts`.++```typescript+// Automatic: wraps an Effect, auto-stops on success/error+const result = yield* ui.withSpinner(+ 'Loading...',+ someEffect,+ { successMessage: 'Done!', errorMessage: 'Failed!' }+);++// Manual: full control over message updates+const result = yield* ui.useMakeSpinner('Loading...', spinner =>+ Effect.gen(function* () {+ yield* spinner.message('Step 1...');+ const data = yield* fetchStep1;+ yield* spinner.message('Step 2...');+ const result = yield* fetchStep2(data);+ yield* spinner.stop('All done!');+ return result;+ })+);+```++## Creating a New Service++If your command requires functionality not covered by existing services (see `ts/packages/cli/AGENTS.md` for the full list):++1. Define the service interface and tag in `src/services/<name>.ts`+2. Create a `Live` layer implementation+3. Register the layer in `src/bin.ts`++Reference `src/services/upgrade-binary.ts` for a simple service pattern, or `src/services/composio-clients.ts` for a complex one with caching.++## Error Handling Patterns++### Optional Values++```typescript+yield* ctx.data.apiKey.pipe(+ Option.match({+ onNone: () => ui.log.warn('Not logged in. Run `composio login`.'),+ onSome: apiKey =>+ Effect.gen(function* () {+ yield* ui.output(apiKey);+ }),+ })+);+```++### Typed Errors with catchTag++```typescript+yield* client.getToolkitsBySlugs(slugs).pipe(+ Effect.catchTag('services/InvalidToolkitsError', error =>+ Effect.gen(function* () {+ yield* ui.log.error(`Invalid toolkits: ${error.invalidToolkits.join(', ')}`);+ return yield* Effect.fail(error);+ })+ )+);+```++### Logging Non-Fatal Errors++```typescript+yield* riskyOperation.pipe(+ Effect.catchAll(error =>+ Effect.logWarning(`Non-critical failure: ${error.message}`)+ )+);+```++## Parallel Data Fetching++Use `Effect.all` with `concurrency` for parallel API calls:++```typescript+const [toolkits, tools, triggerTypes] = yield* Effect.all(+ [+ client.getToolkits(),+ client.getTools(slugs),+ client.getTriggerTypes(slugs),+ ],+ { concurrency: 'unbounded' }+);+```++## Extracting Reusable Logic++For commands that share logic (e.g., `composio generate` delegates to `composio generate ts`):+```typescript+// In ts.generate.cmd.ts — export the logic separately+export function generateTypescriptTypeStubs(params: { ... }) {+ return Effect.gen(function* () {+ const ui = yield* TerminalUI;+ // ... implementation+ });+}++// The command uses it+export const tsCmd$Generate = Command.make('generate', { ... }).pipe(+ Command.withHandler(params => generateTypescriptTypeStubs(params))+);++// Other commands can reuse it+// In generate/generate-ts.cmd.ts+import { generateTypescriptTypeStubs } from '../ts/commands/ts.generate.cmd';+yield* Match.value(envLang).pipe(+ Match.when('TypeScript', () => generateTypescriptTypeStubs({ ... })),+ Match.when('Python', () => generatePythonTypeStubs({ ... })),+ Match.exhaustive+);+```++## Retry with Exponential Backoff++For polling operations (e.g., waiting for OAuth):++```typescript+import { Schedule } from 'effect';++const result = yield* ui.useMakeSpinner('Waiting...', spinner =>+ Effect.retry(+ Effect.gen(function* () {+ const status = yield* client.getSession(session);+ if (status.status === 'linked') return status;+ return yield* Effect.fail(new Error('Still pending'));+ }),+ Schedule.exponential('0.3 seconds').pipe(+ Schedule.intersect(Schedule.recurs(15)),+ Schedule.intersect(Schedule.spaced('5 seconds'))+ )+ ).pipe(+ Effect.tap(() => spinner.stop('Success!')),+ Effect.tapError(() => spinner.error('Timed out'))+ )+);+```++## Checklist++When implementing a new command:++1. Create `src/commands/<name>.cmd.ts` (or `src/commands/<group>/commands/<group>.<name>.cmd.ts` for subcommands)+2. Define options at module level using `Options.*`+3. Create the command with `Command.make(name, options).pipe(Command.withDescription(...), Command.withHandler(...))`+4. In the handler, resolve services with `yield* ServiceName`+5. Follow the output convention: `ui.output()` for data, `ui.log.*` for decoration+6. Register in `src/commands/index.ts` (or in the parent group's command file)+7. If using a new service, add its layer to `src/bin.ts`+8. Build to verify: `cd ts/packages/cli && pnpm build`+9. Add recordings for the new command (see **Recording** below)++If the build fails, check for: (1) missing service imports, (2) `Option<string>` being used where `string` is expected (use `Option.getOrUndefined` or `Option.match`), (3) the command not being exported from its file.++## Recording++New commands should have VHS recordings for documentation. Recordings produce SVGs and asciicasts that demonstrate the command in action.++### Step 1: Add Entries to recordings.yaml++Add recording entries to `ts/packages/cli/recordings/recordings.yaml` under the appropriate group:++```yaml+recordings:+ my-command:+ - name: help+ description: Show my-command help+ command: "composio my-command --help"+ height: dynamic # Use for commands whose output exceeds 750px++ - name: basic+ description: Run my-command with default options+ command: "composio my-command"+```++Each entry has:+- `name` — filename for the recording (produces `<name>.svg`, `<name>.ascii`, `<name>.tape`)+- `command` — the exact shell command to record+- `description` — (optional) comment shown instantly above the command+- `sleepAfterEnter` — (optional) override the default wait time after Enter (default: `6s`)+- `height` — (optional) `'dynamic'` for auto-sizing via two-pass recording, or a fixed pixel number. Omit to use the default height (750px)++Use `height: dynamic` for commands that produce long output (help text, full listings). Fixed height is fine for short-output commands (version, no-results, limited queries).++### Step 2: Run the Recorder++```bash+cd ts/packages/cli+bun scripts/record.ts+```++Requires `COMPOSIO_API_KEY` in the environment and `vhs` + `composio` on `PATH`.++### Output Structure++```+recordings/+├── recordings.yaml # Config+├── tapes/<group>/<name>.tape # Generated VHS tape files (committed)+├── svgs/<group>/<name>.svg # SVG recordings+└── ascii/<group>/<name>.ascii # Asciicast recordings+```++## Reference Files++| File | Purpose |+|---|---|+| `src/commands/version.cmd.ts` | Simplest command (no options, no services beyond TerminalUI) |+| `src/commands/whoami.cmd.ts` | Data command with service dependency |+| `src/commands/login.cmd.ts` | Complex command (options, spinner, polling, retry) |+| `src/commands/logout.cmd.ts` | Action command (no stdout data) |+| `src/commands/upgrade.cmd.ts` | Action command delegating to service |+| `src/commands/generate/generate.cmd.ts` | Parent `generate` command and delegation entrypoint |+| `src/commands/manage/manage.cmd.ts` | Parent `manage` command and subcommand registration |+| `src/commands/ts/commands/ts.generate.cmd.ts` | Reusable TS generation logic used by `generate ts` |+| `src/commands/index.ts` | Command tree registration |+| `src/bin.ts` | Entry point, layer composition, error handling |+| `src/services/terminal-ui.ts` | TerminalUI service interface |+| `src/services/composio-clients.ts` | API client service (HTTP, pagination, metrics) |+| `ts/packages/cli/AGENTS.md` | CLI architecture, services, effects, output conventions |\ No newline at end of filediff --git a/.agents/skills/test-sdk-in-realworld/SKILL.md b/.agents/skills/test-sdk-in-realworld/SKILL.mdnew file mode 100644index 000000000..d8174c6c0--- /dev/null+++ b/.agents/skills/test-sdk-in-realworld/SKILL.md@@ -0,0 +1,216 @@+# Testing Composio SDK in Real-World Scenarios++Test the Composio SDK viability using ephemeral test projects. Never commit these tests.++## Overview++This skill helps validate SDK functionality by creating temporary test projects that:+- Test both agentic (Tool Router) and non-agentic (Direct Tools) approaches+- Use non-auth apps like HackerNews for quick validation+- Identify bugs and quality issues in SDK or providers+- Clean up automatically - never committed to repository++## Testing Approach++### 1. Create Ephemeral Test Project++Always use the .agent_cache directory for tests:+```bash+# Create test directory in .agent_cache (gitignored)+TEST_DIR=".agent_cache/sdk-test-$(date +%s)"+mkdir -p "$TEST_DIR"+cd "$TEST_DIR"++# Initialize project+npm init -y+npm install @composio/core openai+```++### 2. Test Non-Agentic Providers (Direct Tools)++Test simple tool execution without Tool Router:++```typescript+// test-direct-tools.ts+import { Composio } from '@composio/core';+import OpenAI from 'openai';++const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });++async function testDirectTools() {+ // Get HackerNews tools (no auth required)+ const tools = await composio.tools.get('default', {+ toolkits: ['hackernews']+ });++ console.log(`✓ Got ${tools.length} HackerNews tools`);++ // Test with OpenAI+ const response = await openai.chat.completions.create({+ model: 'gpt-5.2',+ messages: [{ role: 'user', content: 'Get top 5 HackerNews stories' }],+ tools: tools,+ });++ // Handle tool calls+ if (response.choices[0].message.tool_calls) {+ const result = await composio.provider.handleToolCalls('default', response);+ console.log('✓ Tool execution successful');+ return result;+ }+}++testDirectTools().catch(console.error);+```++### 3. Test Agentic Providers (Tool Router)++Test user-isolated sessions with Tool Router:++```typescript+// test-tool-router.ts+import { Composio } from '@composio/core';+import { VercelProvider } from '@composio/vercel';+import { openai } from '@ai-sdk/openai';+import { generateText } from 'ai';++const composio = new Composio({+ apiKey: process.env.COMPOSIO_API_KEY,+ provider: new VercelProvider(),+});++async function testToolRouter() {+ // Create session for test user+ const session = await composio.create('test-user-001', {+ toolkits: ['hackernews'],+ manageConnections: false, // Non-auth app+ });++ console.log('✓ Created Tool Router session');++ const tools = await session.tools();+ console.log(`✓ Got ${Object.keys(tools).length} tools from session`);++ // Test with Vercel AI SDK+ const result = await generateText({+ model: openai('gpt-5.2'),+ prompt: 'Get the top 3 HackerNews stories',+ tools,+ maxSteps: 5,+ });++ console.log('✓ Tool Router execution successful');+ return result.text;+}++testToolRouter().catch(console.error);+```++### 4. Test MCP Integration++Test MCP protocol compatibility:++```typescript+// test-mcp.ts+import { Composio } from '@composio/core';++const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });++async function testMCP() {+ const session = await composio.create('test-user-mcp', {+ toolkits: ['hackernews'],+ manageConnections: false,+ });++ console.log('✓ MCP Session created');+ console.log(' URL:', session.mcp.url);+ console.log(' Headers:', Object.keys(session.mcp.headers));++ // Test MCP endpoint accessibility+ const response = await fetch(session.mcp.url + '/tools', {+ headers: session.mcp.headers,+ });++ console.log('✓ MCP endpoint accessible:', response.ok);+ return response.ok;+}++testMCP().catch(console.error);+```++## Running Tests++```bash+# Run direct tools test+npx tsx test-direct-tools.ts++# Run Tool Router test+npm install @composio/vercel ai @ai-sdk/openai+npx tsx test-tool-router.ts++# Run MCP test+npx tsx test-mcp.ts++# Clean up (always run after testing)+cd .. && rm -rf "$TEST_DIR"+```++## What to Test++1. **Installation**: Does `npm install @composio/core` work?+2. **Type Safety**: Are TypeScript types correct?+3. **Tool Discovery**: Can we fetch tools from toolkits?+4. **Tool Execution**: Do tools execute successfully?+5. **Error Handling**: Are errors informative?+6. **Session Management**: Does Tool Router create sessions?+7. **MCP Protocol**: Is MCP endpoint accessible?+8. **Provider Integration**: Do provider packages work?++## Reporting Issues++When you find bugs or quality issues:++1. **SDK Core Issues**: Report in GitHub Issues with:+ - Minimal reproduction code+ - Expected vs actual behavior+ - SDK version and environment++2. **Provider Issues**: Note which provider package has issues++3. **Documentation Issues**: Flag missing or incorrect docs++## Best Practices++- **Always use .agent_cache**: Never create tests in the main repository+- **Use non-auth apps**: HackerNews, Public APIs for quick testing+- **Test incrementally**: Start with simple tools, then complex workflows+- **Clean up**: Always delete test directory after testing+- **Check latest versions**: Use `npm view @composio/core version`++## Available Environment Variables++Assume these are available:+```bash+COMPOSIO_API_KEY # Composio API key+OPENAI_API_KEY # OpenAI API key+ANTHROPIC_API_KEY # Anthropic API key+```++## Quick Test Template++```bash+# One-liner to create and test+TEST_DIR=".agent_cache/sdk-test-$(date +%s)" && \+mkdir -p "$TEST_DIR" && cd "$TEST_DIR" && \+npm init -y && npm install @composio/core openai && \+echo "console.log('SDK Test Ready')" > test.ts && \+npx tsx test.ts && \+cd .. && rm -rf "$TEST_DIR"+```++## Next Steps++1. Read `/building-agents` for comprehensive Tool Router documentation+2. Check provider-specific skills for integration examples+3. Report any bugs found during testing to the teamdiff --git a/ts/packages/cli/skills/composio-cli/SKILL.md b/ts/packages/cli/skills/composio-cli/SKILL.mdnew file mode 100644index 000000000..92101e40a--- /dev/null+++ b/ts/packages/cli/skills/composio-cli/SKILL.md@@ -0,0 +1,118 @@+---+name: composio-cli+description: Help users operate the published Composio CLI to find the right tool, connect accounts, inspect schemas, execute tools, script workflows with `composio run`, and call authenticated app APIs with `composio proxy`. Use when the user asks how to do something with `composio`, wants to run a known tool slug, needs to discover a slug with `composio search`, fix a missing connection with `composio link`, inspect tool inputs with `--get-schema` or `--dry-run`, troubleshoot top-level CLI flows, or explicitly needs `composio dev` guidance.+---++# Composio CLI++Use the shortest loop that gets the job done: `execute` first, `search` when the slug is unknown, `link` when a connection is missing, then retry `execute`.++## Use The Default Workflow++1. Start with `composio execute <slug>` whenever the slug is known.+2. Let `execute` do the work. It already validates inputs and checks connection state.+3. If `execute` says the toolkit is not connected, run `composio link <toolkit>` and retry.+4. If the arguments are unclear, run `composio execute <slug> --get-schema` or `--dry-run` before guessing.+5. Reach for `composio search "<task>"` only when the slug is unknown.++## Treat Auth As A Footnote++Use auth checks as quick preflight, not as the main workflow.++```bash+composio whoami+```++If `composio whoami` fails, run `composio login` and then move straight back to `execute`.++## Use `execute` First++Run a known slug:++```bash+composio execute GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'+```++Inspect required inputs without executing:++```bash+composio execute GITHUB_CREATE_AN_ISSUE --get-schema+```++Preview safely:++```bash+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'+```++Pass data from a file or stdin:++```bash+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d @issue.json+cat issue.json | composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d -+```++Recover from missing connections:++```bash+composio execute GMAIL_FETCH_EMAILS -d '{ max_results: 1 }'+composio link gmail --no-browser+```++After the auth flow completes, rerun the original `execute` command.++Prefer `composio tools info` and `composio tools list` only when `search`, `--get-schema`, or the error message still leave the user stuck.++## Use `search` To Find The Slug++When the user knows the task but not the tool name, search first and then execute the best match.++```bash+composio search "create a github issue"+composio search "send an email" --toolkits gmail+```++Read the returned slugs, choose the best match, and immediately move back to `execute`.++## Use `link` Only To Unblock `execute`++Use `link` when `execute` reports that the toolkit is not connected, or when the user explicitly wants to authorize an account.++```bash+composio link gmail+composio link googlecalendar --no-browser+```++After linking, retry the original `execute` command instead of changing strategies.++## Use Power Tools Deliberately++Use `composio run` when one tool call is not enough and the user needs chaining, batching, lightweight automation, or sub-agent orchestration.++```bash+composio run '+ const [me, emails] = await Promise.all([+ execute("GITHUB_GET_THE_AUTHENTICATED_USER"),+ execute("GMAIL_FETCH_EMAILS", { max_results: 1 }),+ ]);++ console.log({+ login: me.data.login,+ fetchedEmails: !!emails.data,+ });+'+```++Use `composio proxy` when the toolkit supports a raw API operation that is easier than finding a dedicated tool.++```bash+composio proxy https://api.github.com/user --toolkit github --method GET </dev/null+```++For richer `run`, `subAgent()`, `result.prompt()`, `Promise.all`, and mixed `execute()` plus `proxy()` patterns, load [references/power-user-examples.md](references/power-user-examples.md).++## Escalate Only When Needed++If the user is stuck on top-level commands or needs fallback inspection commands, load [references/troubleshooting.md](references/troubleshooting.md).++If the user explicitly asks about developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects, load [references/composio-dev.md](references/composio-dev.md). `composio dev` is not the default end-user path.diff --git a/ts/packages/cli/skills/composio-cli/agents/openai.yaml b/ts/packages/cli/skills/composio-cli/agents/openai.yamlnew file mode 100644index 000000000..ef1b71194--- /dev/null+++ b/ts/packages/cli/skills/composio-cli/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "Composio CLI"+ short_description: "Execute-first help for the Composio CLI"+ default_prompt: "Use $composio-cli to find the right Composio CLI command and run it safely."diff --git a/ts/packages/cli/skills/composio-cli/references/composio-dev.md b/ts/packages/cli/skills/composio-cli/references/composio-dev.mdnew file mode 100644index 000000000..e460b30df--- /dev/null+++ b/ts/packages/cli/skills/composio-cli/references/composio-dev.md@@ -0,0 +1,71 @@+# Composio Dev++Load this file only when the user explicitly needs developer-project workflows. Do not lead with `composio dev` for ordinary top-level CLI usage.++## Use `dev init` To Bind A Directory++Use `composio dev init` when the user wants to attach the current directory to a developer project.++```bash+composio dev init -y --no-browser+```++If later commands complain about missing developer project context, come back to `dev init`.++## Inspect Toolkits And Versions++Use toolkit commands to inspect developer-scoped capabilities:++```bash+composio dev toolkits list+composio dev toolkits info github+composio dev toolkits search "email"+composio dev toolkits version github+```++## Manage Auth Configs++Use auth-config commands when the user is configuring developer-project authentication behavior:++```bash+composio dev auth-configs list+```++## Manage Connected Accounts++Use developer connected-account commands when the user is working with developer-project users or auth-config-specific flows.++```bash+composio dev connected-accounts list+```++Top-level `composio link` is consumer-only. Use `dev connected-accounts link` for developer-project flows.++## Work With Triggers++Use trigger commands when the user is creating, inspecting, or listening to developer-project triggers.++```bash+composio dev triggers list+composio dev triggers info AGENT_MAIL_NEW_EMAIL_TRIGGER+```++## Inspect Logs++Use logs when the user is debugging tool executions or trigger deliveries inside a developer project.++```bash+composio dev logs tools+composio dev logs triggers+```++## Switch Or Inspect Org And Project Context++Use these commands when the user needs to confirm or change the active developer scope:++```bash+composio dev orgs list+composio dev projects list+```++If the user only wants to connect and execute tools as an end user, return to the top-level workflow instead of staying in `composio dev`.diff --git a/ts/packages/cli/skills/composio-cli/references/power-user-examples.md b/ts/packages/cli/skills/composio-cli/references/power-user-examples.mdnew file mode 100644index 000000000..649fc03d5--- /dev/null+++ b/ts/packages/cli/skills/composio-cli/references/power-user-examples.md@@ -0,0 +1,125 @@+# Power-User Examples++Load this file when the user needs more than one top-level command, wants to script workflows, or wants to use `subAgent()` inside `composio run`.++## Use `run` To Chain Tool Calls++Fetch from multiple connected tools in one script:++```bash+composio run '+ const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");+ const emails = await execute("GMAIL_FETCH_EMAILS", {+ max_results: 2,+ });++ console.log({+ login: me.data.login,+ emailCount: Array.isArray(emails.data?.messages) ? emails.data.messages.length : null,+ });+'+```++## Use `Promise.all` To Fan Out++Fetch from multiple services at once:++```bash+composio run '+ const [me, emails] = await Promise.all([+ execute("GITHUB_GET_THE_AUTHENTICATED_USER"),+ execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),+ ]);++ console.log({+ login: me.data.login,+ emailCount: emails.data.messages?.length ?? null,+ });+'+```++## Use `search()` Before `execute()` Inside A Script++Discover a candidate slug, then execute it:++```bash+composio run '+ const results = await search("get the authenticated github user", {+ toolkits: "github",+ limit: 1,+ });++ const slug = results.results?.[0]?.primary_tool_slugs?.[0];+ if (!slug) throw new Error("No candidate tool found.");++ const output = await execute(slug);++ console.log(output.data.login);+'+```++## Use `subAgent()` With `z` And `result.prompt()`++Turn a tool result into structured output:++```bash+composio run --logs-off '+ const emails = await execute("GMAIL_FETCH_EMAILS", { max_results: 2 });++ const brief = await subAgent(+ `Return only valid JSON matching the schema. Summarize these emails in one sentence and report how many items were returned.\n\n${emails.prompt()}`,+ {+ schema: z.object({+ summary: z.string(),+ count: z.number(),+ }),+ }+ );++ console.log(brief.structuredOutput);+'+```++Use `result.prompt()` when the helper result is too noisy for a raw object dump but you still want to feed it into `subAgent()`.++## Use `proxy()` For Raw API Access++`proxy(toolkit)` returns a fetch-compatible function bound to the connected account. Name it like `fetch` if that keeps the script clearer. It returns a real `Response`, so call `.json()` or `.text()`.++```bash+composio run '+ const fetch = await proxy("github");+ const profile = await (await fetch("https://api.github.com/user")).json();+ console.log(profile);+'+```++## Mix `execute()` And `proxy()`++Use dedicated tools where they exist, then drop down to raw API calls for the missing step:++```bash+composio run '+ const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");++ const fetch = await proxy("github");+ const repos = await (await fetch("https://api.github.com/user/repos?per_page=3")).json();++ console.log({+ login: me.data.login,+ repoCount: Array.isArray(repos) ? repos.length : null,+ });+'+```++## Use `run` Flags Intentionally++- Use `--dry-run` to preview every `execute()` call in the script.+- Use `--debug` to see helper steps while the script runs.+- Use `--logs-off` when `subAgent()` streaming logs are too noisy for the task.++Example:++```bash+composio run --dry-run --debug 'await execute("GITHUB_CREATE_AN_ISSUE", { owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." })'+```diff --git a/ts/packages/cli/skills/composio-cli/references/troubleshooting.md b/ts/packages/cli/skills/composio-cli/references/troubleshooting.mdnew file mode 100644index 000000000..23bcba425--- /dev/null+++ b/ts/packages/cli/skills/composio-cli/references/troubleshooting.md@@ -0,0 +1,110 @@+# Troubleshooting++Load this file when the user is stuck on top-level Composio CLI flows.++## Not Logged In++Symptoms:++- `composio` commands fail because there is no user session+- the user is unsure which account the CLI is using++Fix:++```bash+composio whoami+```++If `composio whoami` fails, run `composio login` and then return to the original `execute` or `search` flow.++## No Active Connection Found++Symptoms:++- `execute` reports that no active connection exists for a toolkit++Fix:++```bash+composio link gmail --no-browser --no-wait+composio link googlecalendar --no-browser --no-wait+```++After linking, retry the exact same `execute` command.++## Invalid JSON Input++Symptoms:++- `execute` rejects `-d` input+- the payload is not valid JSON or JS-style object syntax++Fix:++- Pass JSON or a JS-style object literal to `-d`+- Use `@file` for large payloads+- Use `-` to read from stdin++Examples:++```bash+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{"owner":"acme","repo":"app","title":"Bug report","body":"Steps to reproduce..."}'+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d @payload.json+cat payload.json | composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d -+```++## Unknown Or Wrong Slug++Symptoms:++- the user does not know the tool slug+- the slug exists but is not the right tool for the job++Fix:++```bash+composio search "create a github issue"+composio search "send an email" --toolkits gmail+```++Use `composio tools list <toolkit>` only when the user already knows the toolkit and needs to browse the available slugs manually.++## Confusion About Required Inputs++Symptoms:++- the user is unsure what fields a tool accepts+- the first payload attempt failed validation++Fix:++```bash+composio execute GITHUB_CREATE_AN_ISSUE --get-schema -d '{}'+composio execute GITHUB_CREATE_AN_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'+```++Use `composio tools info <slug>` only when the user wants a compact summary of a known slug and the `execute --get-schema` output is still not enough.++## `tools info` And `tools list` Are Fallbacks++Treat these commands as secondary inspection tools:++```bash+composio tools info GMAIL_SEND_EMAIL+composio tools list gmail+```++Do not lead with them when `execute`, `search`, `--get-schema`, or `--dry-run` can get the user unstuck faster.++## Consumer Vs `composio dev`++Use the top-level commands for normal end-user flows:++- `composio execute`+- `composio search`+- `composio link`+- `composio run`+- `composio proxy`++Load [composio-dev.md](composio-dev.md) only when the user explicitly needs developer projects, auth configs, connected accounts, triggers, logs, orgs, or projects.