# Composio x Pi Extension

Pi package that installs a Pi extension for Composio-backed runtime and trigger-authoring tools.

## Install

Install the published npm package with Pi:

```bash
pi install npm:composio-x-pi
```

For a pinned version:

```bash
pi install npm:composio-x-pi@0.0.1
```

During development, install from a local checkout:

```bash
cd /path/to/composio-x-pi
bun install
pi install /path/to/composio-x-pi
```

Try the extension for one Pi run without adding it to settings:

```bash
pi -e /path/to/composio-x-pi/src/index.ts
```

After editing an installed local checkout, use `/reload` inside Pi.

## Publishing

This package is intended to be installed through Pi's npm package source, so releases should be published to npm under the `composio-x-pi` package name:

```bash
bun run test
bun run typecheck
bun run build
npm publish
```

## Setup

No setup is required by default. The agent provisions a Composio identity for you on first tool use via the `composio_signup` tool. When a Composio tool fails with a missing-credentials error, the model is instructed to call `composio_signup`, which talks to `https://agents.composio.dev/api/signup` and writes the returned credentials to `~/.composio/anonymous_user_data.json` (mode `0600`).

If you already have a Composio API key, you can override the auto-provisioned signup credentials:

```text
/composio-init
```

The command prompts for your key and stores it in `~/.pi/agent/extensions/composio-x-pi.json` with file mode `0600`. You can also pass the key as an argument (`/composio-init <key>`), but the interactive prompt avoids leaving the key in chat history.

Credential precedence:

1. `COMPOSIO_API_KEY` environment variable
2. `/composio-init` stored API key
3. `composio_signup` anonymous credentials

To later hand the auto-provisioned organization over to a human admin, either run `/composio-claim <email>` or ask the agent to call the `composio_claim` tool. Composio sends a 24-hour single-use invite to that email.

Optional environment variables:

- `COMPOSIO_USER_ID` — defaults to `default` when omitted.

## Commands

- `/composio-init` — securely prompt for and store the Composio API key used by this extension.
- `/composio-claim <email>` — hand the auto-provisioned Composio org to a human admin (sends a 24-hour invite to the email).

## Tools

All tools are registered by default:

- `composio_debug_info`
- `composio_signup`
- `composio_claim`
- `composio_search_tools`
- `composio_get_tool_schemas`
- `composio_execute_tool`
- `composio_manage_connections`
- `composio_multi_execute_tool`
- `composio_remote_bash_tool`
- `composio_remote_workbench`
- `composio_list_trigger_types`
- `composio_get_trigger_type_schema`
- `composio_create_trigger`
- `composio_list_triggers`
- `composio_delete_trigger`
- `save_automation_definition`

The multi-execute and remote-workbench tools are thin meta-tool wrappers: pass the raw JSON arguments expected by the corresponding `COMPOSIO_*` meta tool/schema.

### Automation JSON handoff

`save_automation_definition` writes automation metadata for the host application to read.

By default it writes to Pi's global Composio automation handoff file:

```text
~/.config/pi/composio-automations.json
```

Set `PI_COMPOSIO_AUTOMATIONS_JSON` to override the global handoff path. Passing `filePath` to the tool still writes a specific JSON file for that call.

The file contains a JSON array of automation definitions and the tool upserts by `triggerId`.

## Local scripts

- `bun test`
- `bun run test:e2e`
- `bun run typecheck`
- `bun run build`
- `bun run test:integration`
- `bun run test:e2e:signup`
- `bun run dev:pi`

`bun run dev:pi` loads the extension from `src/index.ts` through Pi's embedding API.

## Verification

Automated checks before handoff or release:

```bash
bun run test
bun run test:e2e
bun run typecheck
bun run build
```

`bun run test:e2e` is deterministic: it loads `src/index.ts` through Pi's SDK in an isolated HOME sandbox, verifies registered tools/commands, executes non-network tools, and exercises `/composio-init` without contacting Composio.

Live signup e2e (depends on the external `agents.composio.dev` service):

```bash
bun run test:e2e:signup
```

Integration test with real Composio credentials/config:

```bash
COMPOSIO_API_KEY_TEST=...
COMPOSIO_TEST_TRIGGER_SLUG=...
COMPOSIO_TEST_TRIGGER_CONFIG_JSON='...'
# Optional: bind to a known active connected account/alias/word id.
COMPOSIO_TEST_ACCOUNT=ca_...
bun run test:integration
```

Manual Pi smoke test:

1. Start Pi with the local extension:
   ```bash
   pi -e ./src/index.ts
   ```
2. Ask the agent to run any Composio tool; it will call `composio_signup` automatically on first use. Or run `/composio-init` to store an existing Composio API key.
3. Run `composio_debug_info` and confirm runtime plus authoring tools are listed (and `apiKeySource` is `"signup"`, `"stored"`, or `"env"` depending on setup).
4. Run `composio_list_trigger_types` and `composio_get_trigger_type_schema` for a known trigger.
5. Create a test trigger with `composio_create_trigger`.
6. Confirm it appears via `composio_list_triggers`.
7. Save the automation handoff with `save_automation_definition`.
8. Confirm `~/.config/pi/composio-automations.json` (or `PI_COMPOSIO_AUTOMATIONS_JSON`) contains the expected automation and the host app can read it.
9. Clean up with `composio_delete_trigger`.

Webhook/ngrok delivery verification belongs to the host app: start the app receiver, expose it through ngrok, create/configure the Composio trigger for that URL, cause a real event, and confirm the app receives it.