npm - @connortessaro/pai - Versions diffs - 0.4.1 - Mend

@connortessaro/pai 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/LICENSE +21 -0
package/README.md +308 -0
package/bin.mjs +14 -0
package/dist/pai.mjs +3083 -0
package/package.json +83 -0
package/skills/phantom-ai/SKILL.md +134 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Connor Tessaro
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,308 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset=".github/assets/logo-light.svg">
+    <img alt="Phantom Logo" src=".github/assets/logo-dark.svg" width="56" height="62">
+  </picture>
+</p>
+<h1 align="center">pai</h1>
+<p align="center">
+  <strong>Keys, money, and subagent controls for AI agents</strong><br>
+  Built by <a href="https://phantom.codes">Phantom AI</a>
+</p>
+<p align="center">
+  <a href="https://github.com/connortessaro/pai/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/connortessaro/pai/ci.yml?branch=main&label=CI&color=161b22&labelColor=0d1117" alt="CI"></a>&nbsp;
+  <a href="package.json"><img src="https://img.shields.io/badge/version-0.3.0-161b22?labelColor=0d1117" alt="Version 0.3.0"></a>&nbsp;
+  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D24-161b22?labelColor=0d1117" alt="Node >= 24"></a>&nbsp;
+  <a href="docs/reference.md#mcp-tools"><img src="https://img.shields.io/badge/MCP-16_tools-161b22?labelColor=0d1117" alt="MCP Compatible"></a>&nbsp;
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-161b22?labelColor=0d1117" alt="MIT License"></a>
+</p>
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#how-it-works">How It Works</a> •
+  <a href="#features">Features</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#use-with-an-mcp-client">MCP Server</a> •
+  <a href="docs/reference.md">API Reference</a>
+</p>
+---
+`pai` runs on your machine and manages a [Phantom AI](https://phantom.codes) key.
+Your agent can hand each subagent a child key with its own spending limit, lifetime, and rate cap.
+It also sets plans and model routing, pays for credit from an agent wallet, and checks which model answered a call.
+`pi`, `Claude Code`, `Codex`, and `Cursor` drive it through a skill, and any MCP client can use `pai mcp`.
+The CLI is MIT licensed. The Phantom AI API it calls is a hosted service.
+## How It Works
+```text
+                       ┌────────────────────────┐
+                       │    Main Phantom Key    │
+                       │   (prepaid, no id)     │
+                       └───────────┬────────────┘
+                                   │
+           ┌───────────────────────┼───────────────────────┐
+           │ pai child             │ pai child             │ pai wallet
+           ▼                       ▼                       ▼
+    ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
+    │  Researcher  │        │  Code Agent  │        │ Agent Wallet │
+    │  Claude Code │        │    Cursor    │        │  (Solana)    │
+    │  $0.50 limit │        │  $1.00 limit │        │  auto-topup  │
+    │  6 hour TTL  │        │  $0.10 / min │        │  below $1.00 │
+    └──────┬───────┘        └──────┬───────┘        └──────────────┘
+           │                       │
+           └───────────┬───────────┘
+                       ▼
+           ┌───────────────────────┐
+           │   Phantom AI Gateway  │  ──> https://phantom.codes/v1
+           │   (zero prompt logs)  │  ──> Ed25519 signed receipts
+           └───────────────────────┘
+```
+## Features
+- **Scoped Subagent Keys** — Create child keys that spend the parent's balance up to a limit, with lifetimes and rate caps (`pai child`). Revoke one with `pai burn`.
+- **Autonomous Agent Wallet** — Local Solana keypairs allow running agents to self-fund inference on chain. Capped by environment-only limits (`PHANTOM_WALLET_MAX_USD`).
+- **Multi-Agent Skill & MCP** — Native skill installation for `pi`, `Claude Code`, `Codex`, and `Cursor`, plus a 16-tool Model Context Protocol (MCP) server over stdio.
+- **Cryptographic Receipts** — Upstream responses return an Ed25519 signature verifying the model served, actual token counts, and cost (`pai verify`).
+- **Local Tooling Suite** — Private local markdown memory notebooks, throwaway Docker sandboxes, and safe IMAP/SMTP mail drafting.
+## Install
+```bash
+npm i -g @connortessaro/pai
+# or, without npm's registry:
+npx github:connortessaro/pai --help
+```
+The package also installs the same CLI as `phantom-key`, its earlier name.
+## Quickstart
+```bash
+# 1. Login once and install the skill for your installed agents
+pai login          # paste your key once; pai saves it with mode 600
+pai setup          # configures pi, Claude Code, Codex, and Cursor
+# 2. Check balance and active caps
+pai balance
+# 3. Mint a child key for an autonomous subagent
+pai child --limit 0.50 --ttl 6 --rate 0.10 --save researcher
+# 4. Run the subagent as the scoped child
+PHANTOM_KEY_NAME=researcher claude
+```
+## Use It From an Agent
+`pai setup` installs the `phantom-ai` skill for each agent it finds in your
+home directory (`pi`, `Claude Code`, `Codex`, `Cursor`). You can then prompt your agent in
+plain words, for example:
+> *"Give a subagent $0.50 for 6 hours with a $0.10/min rate cap."*
+- `--agent pi` (or `claude`, `codex`, `cursor`) sets up one agent.
+- `--mcp` also registers the MCP server with Claude Code, Codex, and Cursor.
+- `--agent claude --provider` runs Claude Code's own model calls on Phantom AI: it sets `ANTHROPIC_BASE_URL`, turns on tool search, and gives Claude Code the key through `apiKeyHelper` (`pai key show`), so the key never lands in `settings.json`. Add `--model auto` or any model id; `--provider off` undoes it.
+- `pi` has no MCP and uses the CLI through the skill; install there with:
+  ```bash
+  pi install npm:@connortessaro/pai
+  ```
+## Commands
+`pai --help` prints every command and flag. [docs/reference.md](docs/reference.md)
+has the complete text, the MCP tools, and the environment variables, all generated
+from the code.
+| Group | Commands | What they do |
+| --- | --- | --- |
+| **Setup** | `login`, `logout`, `setup` | Save your key, and install the skill for your agents |
+| **Keys** | `balance`, `child`, `children`, `key`, `rotate`, `burn` | Show credit, create child keys paid from this key, save keys by name, and replace or revoke a key |
+| **Caps and plans** | `budget`, `plan` | Set a monthly cap and a per-minute cap, or money for a period |
+| **Routing** | `route` | Choose which models `model: "auto"` can run, and the rules that pick one |
+| **Credit** | `buy`, `payment` | Buy credit with crypto |
+| **Agent wallet** | `wallet`, `autotopup`, `buy --pay` | Keep Solana wallets and pay for credit from them. See [Let the agent pay](#let-the-agent-pay) |
+| **Receipts** | `verify` | Check which model answered a call, from its signed receipt |
+| **Local tools** | `memory`, `mail`, `browser`, `sandbox` | See the sections below |
+| **MCP** | `mcp` | Run an MCP server over stdio. See [Use with an MCP client](#use-with-an-mcp-client) |
+A command runs as the saved key named by `PHANTOM_KEY_NAME` if it is set, then
+as `PHANTOM_API_KEY`, then as the `login` key. A subagent started with
+`PHANTOM_KEY_NAME=<child>` runs as the child even when your parent key is exported.
+## Memory
+Each agent gets a private notebook on this machine. Notes are markdown files in
+`~/.config/phantom-key/memory/<space>/`, so you can read, edit, or commit them.
+`pai` sends none of them anywhere.
+| Command | What it does |
+| --- | --- |
+| `memory add "text" [--tag a,b] [--title t]` | Keeps a note. Pipe long notes on stdin |
+| `memory search <words> [--tag t] [--any] [--limit n]` | Notes with every word (or any word with `--any`), best match first. Returns 10 by default |
+| `memory list [--tag t] [--limit n]` / `memory show <id>` / `memory rm <id>` | The newest notes (50 by default), one note, or delete one |
+| `memory spaces` | Each notebook and how many notes it holds |
+`pai` picks the notebook from `--space`, then `PAI_MEMORY_SPACE`, then the saved
+key name (`PHANTOM_KEY_NAME`), then `main`, so each subagent keeps its own.
+## Mail
+`pai` reads your own mailbox over IMAP and SMTP. It saves the login, with an app
+password, in `~/.config/phantom-key/mail.json` (mode 600). Gmail, Outlook,
+iCloud, and Fastmail addresses have presets; for any other provider, pass
+`--imap host:port --smtp host:port`.
+| Command | What it does |
+| --- | --- |
+| `mail setup --user you@gmail.com` | Checks the login by listing one message, then saves it. A wrong password is not saved. The password comes from a prompt or `PAI_MAIL_PASSWORD` |
+| `mail status` | Shows the mailbox and whether sending is on |
+| `mail list [--unread] [--from x] [--limit n] [--folder f]` / `mail search <words>` / `mail read <uid>` | Reads mail from `INBOX` by default. `list` returns 20 messages by default. `read` cuts a message at 20,000 characters |
+| `mail draft --to a --subject s [--reply <uid>] [--body "..."]` | Saves a draft in your Drafts folder and sends nothing. Without `--body`, pai reads the body from stdin |
+| `mail send` (same flags) | Sends only when `PAI_MAIL_SEND=1`, to at most `PAI_MAIL_MAX_PER_DAY` recipients (default 10) in 24 hours, and only to `PAI_MAIL_SEND_TO` (addresses or `@domain`s) when set. pai reads all three from the environment, so an agent can't turn sending on with a flag. With sending on, the `create_child_key` tool requires `save_as`, so a new key never lands in the agent's context. SMTP on 587 and IMAP on 143 require STARTTLS |
+## Browser and Sandbox
+`pai` wraps two existing tools:
+| Command | What it does |
+| --- | --- |
+| `browser setup [--install]` | Checks for [agent-browser](https://github.com/vercel-labs/agent-browser), a headless Chrome built for agents. `--install` installs it with npm |
+| `browser <command>` | Runs agent-browser (`open <url>`, `snapshot -i`, `click @e1`, `fill @e2 "text"`, `screenshot`). Each space gets its own session and Chrome profile in `~/.config/phantom-key/browser/<space>/`, so a subagent keeps its own logins. `AGENT_BROWSER_PROFILE=Default` uses your own Chrome profile instead |
+| `sandbox check` | Reports whether Docker or Podman is running |
+| `sandbox run [--image i] [--net] [--write] [--timeout s] -- <command>` | Runs a command in a throwaway container (default image `node:24-slim`). The container has no network unless `--net`, and mounts this folder read-only unless `--write`. It runs as an unprivileged user with all capabilities dropped, 2 CPUs and 2 GB of memory. It stops after 300 seconds by default and exits 124 on timeout |
+## Output Format
+Commands print JSON on stdout, so you can pipe into `jq`. `--table` prints
+a formatted table for human inspection. `browser` and `sandbox run` pass through the exit code of the
+command they ran.
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Any other error |
+| `2` | Key rejected (401/403). Get a new key; a retry fails the same way |
+## Use With an MCP Client
+`pai mcp` starts an MCP server over stdio. Add it to your client's config:
+```json
+{
+  "mcpServers": {
+    "phantom": {
+      "command": "npx",
+      "args": ["-y", "@connortessaro/pai", "mcp"]
+    }
+  }
+}
+```
+[docs/reference.md](docs/reference.md#mcp-tools) lists every tool with its
+inputs and whether it is read-only or destructive.
+`delete_key` authenticates as the key you pass in `api_key` or `key_name` and
+deletes that key. It refuses the key the server runs as; use `pai burn` for
+that.
+## Let the Agent Pay
+The agent can maintain its own Solana wallets and buy credit with them. Each wallet
+is a Solana keypair in `~/.config/phantom-key/wallets/` (mode 600). The wallet
+pays Phantom AI's Solana address, and Phantom AI finds the payment on chain.
+1. **Create a wallet**, and back up its file:
+   ```bash
+   pai wallet create --table              # saved as "main"
+   pai wallet create --name work --table  # a second one
+   ```
+2. **Fund the address** with USDC on Solana, plus some SOL for fees (at least 0.003 SOL).
+3. **Set the safety cap**:
+   ```bash
+   export PHANTOM_WALLET_MAX_USD=10
+   ```
+   Without this variable, `pai` refuses to pay. The total over 24 hours is
+   capped by `PHANTOM_WALLET_MAX_USD_PER_DAY`, which defaults to the same
+   amount: one payment a day. Raise it for `autotopup`.
+4. **Pay**:
+   ```bash
+   pai buy --amount 5 --pay
+   ```
+   With more than one wallet saved, `pai` asks in a terminal which one pays. It
+   then reports each step:
+   1. Getting a payment request from Phantom AI (amount, recipient, and unique reference)
+   2. Sending USDC or SOL from your wallet
+   3. Confirming on Solana
+   4. Phantom AI finding the payment on chain by its reference
+   5. Credit balance before and after
+   A payment request expires after 30 minutes.
+You can also prompt your agent: *"Top up my Phantom AI key with $5 from my Phantom agent wallet."*
+Over MCP it calls `list_wallets`, asks which wallet if not specified, then calls `pay_for_credit`.
+To refill automatically when the balance runs low:
+```bash
+pai autotopup --below 1 --amount 5 --wallet main --every 10
+```
+### Safeguards
+- `pai` pays the recipient and exact amount the payment request names, with that request's reference attached.
+- `pai` reads `PHANTOM_WALLET_MAX_USD` and `PHANTOM_WALLET_MAX_USD_PER_DAY` strictly from the environment; no flag or tool argument can raise them.
+- Before signing, `pai` checks the payment request against what it asked for: the coin, the USDC mint, and an amount no more than requested (for SOL, within 10% of Coinbase's price). A wrong or hostile `PHANTOM_BASE_URL` cannot make it sign more.
+- One payment runs at a time, across processes.
+- `pai` verifies the wallet balance before requesting a payment.
+- `pai` records payments in `~/.config/phantom-key` before sending, and keeps the record until Phantom AI reports the payment credited or dead. If a run crashes, times out or loses the connection, the next run waits for that payment instead of paying again.
+- These limits bind an agent that reaches pai through MCP. An agent with its own shell can set environment variables and edit the state folder, so give such an agent a wallet holding only what you are willing for it to spend.
+- Store wallet secrets in a local secrets manager (e.g. [KRU](https://github.com/omaekumiko2-create/kru)) and inject `PHANTOM_WALLET_KEY` at runtime.
+## Configuration
+`pai` reads its settings from environment variables. Run `pai --help` or see
+[docs/reference.md#environment-variables](docs/reference.md#environment-variables) for the full list,
+including secrets, environment-only flags, and caps.
+## Requirements
+- **Node 24** or newer
+- Runtime dependencies: `@modelcontextprotocol/sdk` and `zod` for `mcp`, `@solana/kit` for wallet payments, and `imapflow`, `mailparser`, `nodemailer` for `mail`.
+Read [phantom.codes/docs/concepts](https://phantom.codes/docs/concepts) for key lifecycle and subagent hierarchy details.
+## Development
+```bash
+npm ci
+npm test                # vitest
+npm run typecheck
+npm run docs            # regenerate docs/reference.md
+node src/pai.mts --help # run from source
+```
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, style, and how to add a
+command or MCP tool. [CHANGELOG.md](CHANGELOG.md) lists changes by release.
+## Security
+Report vulnerabilities privately through a
+[GitHub security advisory](https://github.com/connortessaro/pai/security/advisories/new).
+See [SECURITY.md](SECURITY.md).
+## License
+[MIT](LICENSE)

package/bin.mjs ADDED Viewed

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * The installed entry point.
+ *
+ * Two reasons this is plain JS rather than the .mts itself. Node refuses to
+ * strip types from anything under node_modules at all, so a published
+ * TypeScript source cannot run in a dependency; and npm links the bin as an
+ * extensionless `pai`, which Node would not recognise as TypeScript
+ * even if it would. So `npm run build` compiles the source to dist/ and this
+ * file, which never needs compiling, is what npm points at.
+ */
+import { main } from './dist/pai.mjs';
+await main();