mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
Alberto Schiabel
661d7b5f83
This PR: - builds on top of https://github.com/ComposioHQ/composio/pull/4015 - makes `COMPOSIO_INSTALL_SHELL=auto` the default: the installer infers the login shell from `$SHELL` (zsh, bash, fish) and always runs idempotent PATH setup for it; `COMPOSIO_INSTALL_SHELL=none` is the documented install-only opt-out for CI, Docker, and dotfile managers - makes the ending truthful for every outcome: Case A/Case B are decided against a pre-install `PATH` snapshot with physical-path identity, startup-file failures never fail the install (warning + runnable absolute-path command, exit 0), and the final action block is always the last output - seeds `~/.bash_profile` (sourcing `~/.profile`) on bash systems with no login file, so login shells actually read the managed block; the documented uninstall deletes that file again when only the block was in it - teaches `composio install` to reconcile a stale managed PATH block (exactly one block per physical file, symlink-aware) and to suppress its boxed restart hint when `COMPOSIO_CLI_INVOCATION_ORIGIN=installer` - verifies delegated shell setup actually reconciled before trusting its exit code, and writes rc files through symlinks with preserved mode and per-process tmp names - covers every output-matrix row with exact final-tail harness assertions under `sh` and `dash`, adds default-flow/`SHELL`-unset/`none` Docker e2e legs, and aligns CI workflows, docs, and the changelog - includes one deliberate cross-cutting refactor (`8b7ebadef`): the per-process atomic tmp-write helper used for rc files is shared with the analytics and tool-permission state writers instead of duplicating it ## Review remediation (2026-08-04) All P1/P2 findings from the stack review are addressed on this head: - **Atomic replacement (P1):** #4016 (`fix/cli-upgrade-atomic-replace`) is merged into this branch. `install.sh` publishes support files first, `release-tag.txt` next, and the `composio` binary last, with aside/rollback recovery and preserved staging on failed restores; `composio upgrade` replaces the running binary via rename-based `atomic-replace` helpers (no `fs.copy`), with running-version precedence and Linux open-handle/changed-inode coverage. - **Safe documented uninstall (P1):** the docs snippet stages each startup-file rewrite in a 0600 `mktemp` file, promotes only on filter success (preserving symlinks, inode, owner, mode), always cleans up, and is extracted verbatim and exercised by `test/install-sh-uninstall-snippet.test.sh` under `sh` and `dash` (symlinks, modes, filter failure/partial output, `.bash_profile` deletion). - **Legacy block migration (P2):** both reconcilers migrate the old three-line block (marker + `export COMPOSIO_INSTALL_DIR` + PATH export, POSIX and fish) as a unit, with shared `legacy-migrate-*`/`legacy-near-miss-*` fixtures run by the TS conformance suite and the shell suite; the uninstall filter removes the legacy lines too. - **Checksum policy (P2):** for the default ComposioHQ GitHub source, a missing `checksums.txt` or missing manifest entry is now a hard error (mismatch/malformed stay fatal everywhere); overridden mirrors keep the lenient path; a missing SHA-256 utility warns that verification was skipped. The changelog claims match this exactly. - **CI (P2):** the scheduled prod E2E stays on the Docker harness but installs through `/install` with `COMPOSIO_INSTALL_SHELL` (the `/install/<shell>` routes are still unprovisioned 404s; a workflow comment records how to restore variant-route coverage), with a new fish leg; the hourly canary installs with `COMPOSIO_BIN_DIR=$HOME/.composio-canary/bin` so its `env -i` login probe passes only when the managed block itself makes `composio` resolvable. ## Context The production installer already auto-configured the shell once, and a first-time user still hit `composio: command not found` four times in a row: the refresh hint printed mid-stream, plugin output buried it, and the final block suggested an unrunnable command. Users execute the last instruction on screen, so auto-setup is only safe together with a truthful, copy-paste-safe ending — that pairing is the core of this PR. The audience now includes non-technical users: one command, no shell vocabulary, and the only follow-up ever needed is "open a new terminal, then run `composio login`". ## Release sequencing and rollback 1. This PR merges into `feat/mise-style-installer-rollout` (#4015) after review; checks and review rerun on the combined head. 2. #4011 merges to `next`; a stable `@composio/cli` containing `install --shell` must be promoted and verified before #4015 moves. 3. #4015 retargets to `next` and merges; `https://composio.dev/install` then serves the new default. Smoke-test the live `auto` and `none` flows before deploying the linked dashboard PR ComposioHQ/dashboard#1204 and announcing. Rollback order is copy-first: restore the previous dashboard/docs copy, then revert installer behavior if needed. The old copy stays compatible with the new installer; the new promise is not compatible with the old install-only default. ## Known Residuals Accepted during review (recorded, not dropped): - **Design observation (matches the plan's output matrix by design):** agent-mode success with an unresolved inherited PATH prints only the new-terminal notice, with no runnable command for automation; consider a follow-up amendment. - **Cross-repo risk:** `$SHELL`-inferred setup may target a different shell than the interpreter driving an agent (e.g. the Claude Code plugin runs bash while `$SHELL` is zsh); verify the plugin's install-then-login sequence end to end before rollout. - Minor: a stale block plus a completions append targeting the same file performs two rewrites and prints `Updated` twice (requires `--completions` and a changed bin dir). - Minor: `test/install-sh-uninstall-snippet.test.sh` runs in the release-validation workflow (like the other install-sh unit suites), not on plain PRs, so docs-snippet drift is caught at release time. - Minor: a legacy file already mangled by an unreleased build of this branch (marker consumed, orphaned exports left) is not migrated — without the marker anchor those lines are indistinguishable from user content. ## Post-Deploy Monitoring & Validation - **Live verification (owner: release driver, before dashboard deploy):** in a fresh container/VM, run the plain `curl -fsSL https://composio.dev/install | sh` with zsh/bash `$SHELL`; a new login shell must resolve `composio`; repeat with `COMPOSIO_INSTALL_SHELL=none` and assert no rc changes. - **Canary:** `cli.install-health-check.yml` (hourly) now asserts the auto contract in isolation — managed block present with the canary bin dir, exact PATH line, `env -i bash -ilc 'command -v composio'` resolving through the managed block only. Healthy = green hourly runs; failure signal = red canary or a `warning: Automatic PATH setup` line in its logs. - **Telemetry:** PostHog `install` events with `invocation_origin: installer` — watch install→login completion rate for regression in the first 48h. - **Rollback trigger:** sustained canary failures or a spike in `command not found` support reports → roll back copy first, installer second (order above). - **Validation window:** 24h of hourly canary runs post-deploy.
composio.dev • Documentation • Quickstart • Changelog
Composio
Composio gives your AI agents 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox, so you can ship agents that turn intent into action.
This is the Composio SDK monorepo. It contains:
@composio/core: TypeScript SDKcomposio: Python SDKcomposioCLI: search, execute, and script tools from your shell- Provider adapters for OpenAI Agents, Claude Agent SDK, Vercel AI SDK, LangChain, and more
Quickstart
Create a session for a user, hand its tools to your agent, and let the agent take action across 1000+ apps. Grab a COMPOSIO_API_KEY from the dashboard first.
TypeScript
npm install @composio/core @composio/openai-agents @openai/agents
@composio/coreintentionally packages its TypeScript source and SDK docs so the installed package is inspectable to coding agents. If you want a smaller install with the same API, use@composio/slim.
import { Composio } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { Agent, run } from "@openai/agents";
const composio = new Composio({ provider: new OpenAIAgentsProvider() });
// Each session is scoped to one of your users
const session = await composio.create("user_123");
const tools = await session.tools();
const agent = new Agent({
name: "Personal Assistant",
instructions: "You are a helpful assistant. Use Composio tools to take action.",
tools,
});
const result = await run(agent, "Summarize my emails from today");
console.log(result.finalOutput);
Python
pip install composio composio-openai-agents openai-agents
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner
composio = Composio(provider=OpenAIAgentsProvider())
# Each session is scoped to one of your users
session = composio.create(user_id="user_123")
tools = session.tools()
agent = Agent(
name="Personal Assistant",
instructions="You are a helpful assistant. Use Composio tools to take action.",
tools=tools,
)
result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today")
print(result.final_output)
By default a session gets meta tools that discover, authenticate, and execute app tools at runtime, so you don't load hundreds of tool definitions into context. Store session.session_id and reuse it with composio.use() across turns. See what a session is and configuring sessions for restricting toolkits, auth configs, and connected accounts.
Prefer MCP? Every session also exposes a hosted MCP endpoint. Pass mcp: true to composio.create() and point Claude, Cursor, or any MCP client at session.mcp.url. See sessions via MCP.
CLI
The composio CLI runs Composio from your shell and gives coding agents like Claude Code a local tool surface.
curl -fsSL https://composio.dev/install | sh
The installer puts composio on your PATH for future terminals. Open a new terminal, then run composio login. See INSTALL.md for shell setup overrides, including COMPOSIO_INSTALL_SHELL=none for install-only runs.
Use composio search to find tools, composio execute to run them, composio link to connect accounts, and composio run to script workflows in TypeScript. See the CLI docs.
Providers
A provider adapts Composio tools to your agent framework's native tool format:
| Provider | TypeScript | Python |
|---|---|---|
| OpenAI | @composio/openai |
composio-openai |
| OpenAI Agents | @composio/openai-agents |
composio-openai-agents |
| Anthropic | @composio/anthropic |
composio-anthropic |
| Claude Agent SDK | @composio/claude-agent-sdk |
composio-claude-agent-sdk |
| Vercel AI SDK | @composio/vercel |
— |
| Google GenAI | @composio/google |
composio-gemini, composio-google |
| Google ADK | — | composio-google-adk |
| LangChain | @composio/langchain |
composio-langchain |
| LangGraph | via @composio/langchain |
composio-langgraph |
| LlamaIndex | @composio/llamaindex |
composio-llamaindex |
| Mastra | @composio/mastra |
— |
| Pi | @composio/experimental* |
— |
| Cloudflare Workers AI | @composio/cloudflare |
— |
| CrewAI | — | composio-crewai |
| AutoGen | — | composio-autogen |
* The Pi provider is experimental and ships from @composio/experimental.
Don't see your framework? Build a custom provider, or skip providers entirely and connect over MCP.
All packages
Everything published from this repo:
| Package | Description |
|---|---|
@composio/core |
TypeScript SDK |
@composio/slim |
@composio/core without packaged source or docs; same API, smaller install |
composio CLI |
Standalone CLI binary: curl -fsSL https://composio.dev/install | sh |
@composio/experimental |
Experimental integrations, including the Pi provider |
@composio/json-schema-to-zod |
JSON Schema to Zod conversion |
@composio/* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel, Google, LangChain, LlamaIndex, Mastra, Cloudflare |
composio |
Python SDK |
composio-* provider adapters |
OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Gemini, Google, Google ADK, LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen |
Repository layout
ts/ TypeScript SDK workspace
packages/core/ @composio/core
packages/providers/ Provider adapters
packages/cli/ Composio CLI
python/ Python SDK and provider packages
docs/ Documentation site (docs.composio.dev)
The TypeScript SDK is tested against Node 22+; the Python SDK supports Python 3.10+.
Development
mise install # pinned toolchain (Node, Python, pnpm)
pnpm install
pnpm build
pnpm test
Python commands run from python/; see python/README.md. We welcome contributions to both SDKs; read the contribution guidelines before submitting pull requests.
Support
License
MIT. See LICENSE.