opencrowd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Srijith Poduval and OpenCrowd contributors
+
+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

@@ -0,0 +1,184 @@
+# OpenCrowd
+
+**A CLI agent with its own wallet.** Give it a task and a budget; it finds paid
+[x402](https://www.x402.org/) services on the open market, pays for them in
+USDC on Base, and gets the job done — asking you before it spends on anything
+new, and writing every cent to a local ledger.
+
+[![CI](https://github.com/sr33j/opencrowd/actions/workflows/ci.yml/badge.svg)](https://github.com/sr33j/opencrowd/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+![OpenCrowd demo: the agent asks permission, pays an x402 service, and accounts for every cent](docs/demo.gif)
+
+## Try it in 60 seconds (no crypto required)
+
+```sh
+npx opencrowd --demo
+```
+
+Demo mode runs the full loop — service discovery, payment, artifacts, ledger —
+against a mock wallet, mock x402 services, and a mock LLM. No real money moves.
+
+## Run it for real
+
+```sh
+npx opencrowd
+```
+
+First launch is two steps — there is no wallet setup:
+
+1. **Fund the wallet** — it already exists (created automatically, shared
+   with the AgentCash and CrowdCode tools so everything draws one balance).
+   Scan the QR or tap the MetaMask link to send a few dollars of USDC on
+   Base. The wallet is the agent's entire blast radius: it can never spend
+   more than you put in.
+2. **Give it a task** — type what you want. The agent discovers paid
+   x402/MPP services through its connectors, checks their CrowdCode
+   reputation, and pays per call.
+
+```text
+❯ find an x402 service that returns live weather and get today's forecast
+
+  → search_services query="live weather forecast"
+  ← search_services found 7 candidates; top: WeatherStation ($0.02 USDC)
+  $ paid $0.02 → api.weatherstation.xyz (HTTP 200) · saved forecast.json
+
+  Today: 72°F, clear. Full forecast saved to artifacts.
+  summary: spent $0.05, remaining $19.95, services 1, artifacts 1
+```
+
+The LLM itself is paid the same way: OpenCrowd uses an x402-metered,
+OpenAI-compatible route funded from the same wallet — no API keys, no
+subscriptions.
+
+## Safety model
+
+Real money demands real guardrails. The defaults:
+
+- **`ask_first` permission mode** — the agent must show you the service URL,
+  reason, and cost caps before its first payment to any service. Approve with
+  one key. Shift+tab toggles to `yolo` (auto-approve) when you want speed.
+- **Session budgets** — default `min($20, wallet balance)`, enforced locally
+  with reserve/finalize accounting around every paid call. Unused budget never
+  leaves the wallet.
+- **Burner-wallet design** — the agent has its own low-value wallet, never
+  your main one. Worst case is bounded by what you deposited.
+- **Full ledger** — every LLM call, service payment, and top-up lands in
+  `sessions/<id>/ledger.csv` with costs, tx hashes, and artifacts.
+- **No telemetry** — everything stays on your machine.
+
+Read [SECURITY.md](SECURITY.md) for the full threat model, including how we
+treat marketplace content as prompt-injection input.
+
+## Use it from Claude, Codex, or any MCP client
+
+OpenCrowd doubles as an MCP server, so your existing coding agent can search
+the bazaar, make x402 payments, and manage budgets using OpenCrowd's wallet:
+
+```sh
+claude mcp add opencrowd -- npx -y opencrowd mcp
+```
+
+Or in any MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "opencrowd": { "command": "npx", "args": ["-y", "opencrowd", "mcp"] }
+  }
+}
+```
+
+There's also a localhost HTTP API: `opencrowd api --port 8787`.
+
+Here's Claude Code discovering a live weather service on the Bazaar and paying
+it 0.001 USDC on Base through OpenCrowd — real money, real on-chain settlement:
+
+![Claude Code paying a real x402 service through the OpenCrowd MCP server](docs/mcp-demo.gif)
+
+## Commands
+
+Inside the interactive UI (`/help` shows this live):
+
+| Command | What it does |
+| --- | --- |
+| `/budget <usd>` | Set the local session spend cap |
+| `/mode ask_first\|yolo\|blocked` | Set permission mode (shift+tab toggles) |
+| `/wallet list\|balance\|use\|fund\|export` | Manage the shared payment wallet |
+| `/models list\|set <model>` | Pick the x402 LLM model |
+| `/search "<query>"` | Search the x402 service bazaar |
+| `/permissions list\|allow\|block <url>` | Manage allowed/blocked services |
+| `/ledger show` | Show this session's spend ledger |
+| `/summary` | Spend and artifacts so far |
+
+One-shot and scripting forms:
+
+```sh
+opencrowd run --budget 1.00 "Find a service and summarize options"
+opencrowd run --session <session-id> "Follow up on the previous result"
+opencrowd run --headless --prompt "..." --output json   # programmatic run contract
+opencrowd search --json "stock price"
+opencrowd wallet balance
+opencrowd wallet send 0x... 5.00 --network base          # send USDC anywhere (confirmed interactively)
+opencrowd evals gaia --tier smoke --harness opencrowd,claude,codex
+```
+
+`wallet send` signs a plain ERC-20 USDC transfer with the shared wallet key
+(the wallet needs a one-time ~$0.20 ETH deposit for gas; x402 payments stay
+gasless). It requires an interactive confirmation and is never retried
+automatically. `evals gaia` runs the GAIA validation split
+against OpenCrowd — and optionally Claude Code and Codex with the same prompt
+template and scorer — reporting accuracy and cost per question (OpenCrowd's
+cost is measured on-chain spend; comparators are estimates).
+
+## Local state
+
+| What | Where |
+| --- | --- |
+| Config | `~/.config/opencrowd/config.json` |
+| Wallet metadata | `~/.config/opencrowd/wallets.json` (no secrets) |
+| Seed phrases | OS credential store (Keychain on macOS) |
+| Service permissions | `~/.config/opencrowd/permissions.json` |
+| Sessions, ledger, artifacts | `./sessions/<session-id>/` |
+
+Conversations persist per session and are automatically compacted when they
+outgrow the model's context window (archives kept under `sessions/<id>/context/`).
+
+## Configuration notes
+
+- **Model**: defaults to `openai/gpt-5.6-sol` on an x402-metered OpenRouter
+  route (`x402LlmBaseUrl` points at any OpenAI-compatible x402 endpoint).
+  `opencrowd models list` then `models set <model>` to change it.
+- **Model policy / subagents**: `modelPolicy` in config (`{"mode": "auto"|"manual",
+  "main": "<model>|auto", "subagent": "<model>|auto"}`) pairs the main loop
+  with a subagent model, both paid over the same x402 route. Defaults:
+  `openai/gpt-5.6-sol` main, `openai/gpt-5.6-luna` subagents. The main loop
+  gets `spawn_subagent`/`check_subagents` tools (local tools only, one level
+  deep, parallel with background mode); resolution is recorded per session
+  for reproducibility. Auto mode refuses to run if the catalog has no
+  frontier-tier model.
+- **Connectors**: paid capability comes from vendor MCP servers (AgentCash
+  for wallet/payments, CrowdCode for reputation), configured under
+  `mcpServers` in config with pinned versions. Their tools are ingested
+  verbatim (`agentcash_fetch`, `crowdcode_get_service_score`, ...) and their
+  own instructions become prompt context. When connectors are unreachable the
+  runtime falls back to the legacy Bazaar path.
+- **Discovery (legacy fallback)**: Coinbase CDP Bazaar; custom bazaar URLs
+  supported in config.
+- **Env overrides**: `OPENCROWD_BUDGET_CENTS`, `OPENCROWD_PERMISSION_MODE`,
+  `OPENCROWD_SHELL_ENABLED`, `OPENCROWD_CONFIG_DIR`, `OPENCROWD_TEST_MODE`.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+```
+
+Monorepo layout: `packages/core` (wallets, x402, sessions, budgets, ledger),
+`packages/agent-runtime` (LLM loop + tools + subagents), `packages/evals`
+(GAIA benchmark runner), `packages/mcp`, `packages/local-api`, `apps/cli`
+(the `opencrowd` binary and TUI).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Licensed [MIT](LICENSE).