opencrowd 0.1.0 → 0.2.0
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.
- package/README.md +105 -116
- package/bundle/opencrowd.js +43318 -15995
- package/package.json +4 -10
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# OpenCrowd
|
|
2
2
|
|
|
3
|
-
**A CLI agent with its own wallet.** Give it a task and a
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
**A local CLI agent with its own USDC wallet.** Give it a task and a local
|
|
4
|
+
spend cap; it uses local tools when it can, buys external capabilities
|
|
5
|
+
through one enforced purchase lifecycle when it can't, and records work,
|
|
6
|
+
costs, receipts, and reviews on your machine.
|
|
7
7
|
|
|
8
8
|
[](https://github.com/sr33j/opencrowd/actions/workflows/ci.yml)
|
|
9
9
|
[](LICENSE)
|
|
10
10
|
|
|
11
|
-
|
|
12
12
|
|
|
13
13
|
## Try it in 60 seconds (no crypto required)
|
|
14
14
|
|
|
@@ -16,169 +16,158 @@ new, and writing every cent to a local ledger.
|
|
|
16
16
|
npx opencrowd --demo
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
Demo mode runs the
|
|
20
|
-
|
|
19
|
+
Demo mode runs the real enforced lifecycle — discovery, inspection,
|
|
20
|
+
reputation check, approval, payment, receipt, required review — over
|
|
21
|
+
in-memory mock adapters. No real money moves and nothing touches the
|
|
22
|
+
network.
|
|
21
23
|
|
|
22
|
-
##
|
|
24
|
+
## Installation and startup
|
|
23
25
|
|
|
24
26
|
```sh
|
|
25
|
-
npx opencrowd
|
|
27
|
+
npm install -g opencrowd # or: npx opencrowd
|
|
28
|
+
opencrowd
|
|
26
29
|
```
|
|
27
30
|
|
|
31
|
+
The TUI renders immediately from local state; the AgentCash and CrowdCode
|
|
32
|
+
vendors, wallet balance, and model catalog initialize concurrently in the
|
|
33
|
+
background. `opencrowd doctor` diagnoses local dependencies, provider
|
|
34
|
+
authentication, the wallet, vendor connections, and the network explicitly.
|
|
35
|
+
|
|
28
36
|
First launch is two steps — there is no wallet setup:
|
|
29
37
|
|
|
30
|
-
1. **Fund the wallet** — it already exists (
|
|
31
|
-
|
|
32
|
-
Scan the QR or tap the MetaMask link to
|
|
33
|
-
Base. The wallet is the agent's entire
|
|
34
|
-
more than you put in.
|
|
38
|
+
1. **Fund the wallet** — it already exists (AgentCash creates it
|
|
39
|
+
automatically at `~/.agentcash/wallet.json`; OpenCrowd, AgentCash, and
|
|
40
|
+
CrowdCode all draw one balance). Scan the QR or tap the MetaMask link to
|
|
41
|
+
send a few dollars of USDC on Base. The wallet is the agent's entire
|
|
42
|
+
blast radius: it can never spend more than you put in.
|
|
35
43
|
2. **Give it a task** — type what you want. The agent discovers paid
|
|
36
|
-
x402/MPP services
|
|
37
|
-
|
|
44
|
+
x402/MPP services, checks their CrowdCode reputation, and pays per call
|
|
45
|
+
through the enforced lifecycle.
|
|
38
46
|
|
|
39
47
|
```text
|
|
40
|
-
❯ find
|
|
48
|
+
❯ find a service that returns live weather and get today's forecast
|
|
41
49
|
|
|
42
|
-
→
|
|
43
|
-
|
|
44
|
-
$ paid $0.02 → api.weatherstation.xyz (
|
|
50
|
+
→ find_paid_service "live weather forecast"
|
|
51
|
+
→ inspect_paid_service POST api.weatherstation.xyz/forecast
|
|
52
|
+
$ paid $0.02 → api.weatherstation.xyz (paid_success) · saved forecast.json
|
|
53
|
+
→ review_paid_service rating=5
|
|
45
54
|
|
|
46
55
|
Today: 72°F, clear. Full forecast saved to artifacts.
|
|
47
56
|
summary: spent $0.05, remaining $19.95, services 1, artifacts 1
|
|
48
57
|
```
|
|
49
58
|
|
|
50
|
-
|
|
51
|
-
OpenAI-compatible route funded from the same wallet — no API keys, no
|
|
52
|
-
subscriptions.
|
|
53
|
-
|
|
54
|
-
## Safety model
|
|
59
|
+
## Providers
|
|
55
60
|
|
|
56
|
-
|
|
61
|
+
The default provider is the **x402 token proxy** (`x402ProxyUrl`, an
|
|
62
|
+
OpenAI-compatible route metered with x402 micropayments): requests pass
|
|
63
|
+
through unchallenged, and when the route demands payment (HTTP 402) the
|
|
64
|
+
challenge is signed with the shared AgentCash wallet — upto-style, so the
|
|
65
|
+
service settles actual usage against a quoted ceiling. No API keys, no
|
|
66
|
+
prepaid balance, OpenRouter-grade serving latency.
|
|
57
67
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
your main one. Worst case is bounded by what you deposited.
|
|
66
|
-
- **Full ledger** — every LLM call, service payment, and top-up lands in
|
|
67
|
-
`sessions/<id>/ledger.csv` with costs, tx hashes, and artifacts.
|
|
68
|
-
- **No telemetry** — everything stays on your machine.
|
|
68
|
+
**Venice** is the wallet-native backup (`opencrowd config set provider
|
|
69
|
+
venice` or `/provider venice`): SIWX authentication, prepaid Venice credit
|
|
70
|
+
topped up with USDC, at most one bounded automatic top-up per exhausted
|
|
71
|
+
call. **OpenRouter** direct is also available with `OPENROUTER_API_KEY`.
|
|
72
|
+
There is no automatic fallback between providers — switching is always an
|
|
73
|
+
explicit choice, and a provider failure surfaces with a remediation
|
|
74
|
+
message.
|
|
69
75
|
|
|
70
|
-
|
|
71
|
-
|
|
76
|
+
Model preferences are per provider (`auto` resolves from the live catalog at
|
|
77
|
+
session start; resolved IDs are recorded on the session so `run --session`
|
|
78
|
+
reproduces them exactly). Change the running session with `/provider`,
|
|
79
|
+
`/model`, and `/submodel`; change future-session defaults with
|
|
80
|
+
`opencrowd config set`.
|
|
72
81
|
|
|
73
|
-
##
|
|
82
|
+
## Wallet
|
|
74
83
|
|
|
75
|
-
|
|
76
|
-
|
|
84
|
+
There is one wallet: AgentCash's. OpenCrowd shows public addresses,
|
|
85
|
+
balances, and funding links (`/wallet`, `/fund`) and never manages, copies,
|
|
86
|
+
or exports keys. See [SECURITY.md](SECURITY.md) for the enforcement model.
|
|
77
87
|
|
|
78
|
-
|
|
79
|
-
claude mcp add opencrowd -- npx -y opencrowd mcp
|
|
80
|
-
```
|
|
88
|
+
## Budget
|
|
81
89
|
|
|
82
|
-
|
|
90
|
+
The session budget is a local cumulative cap on value consumed — LLM
|
|
91
|
+
inference and paid services both count against it. Reservations are local,
|
|
92
|
+
a budget change never moves money, and the cap can never drop below already
|
|
93
|
+
finalized spend. Defaults come from configuration
|
|
94
|
+
(`opencrowd config set budget 20`); session creation never needs a network
|
|
95
|
+
lookup.
|
|
83
96
|
|
|
84
|
-
|
|
85
|
-
{
|
|
86
|
-
"mcpServers": {
|
|
87
|
-
"opencrowd": { "command": "npx", "args": ["-y", "opencrowd", "mcp"] }
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
```
|
|
97
|
+
## Approval
|
|
91
98
|
|
|
92
|
-
|
|
99
|
+
Approval governs external service purchases only (LLM calls are governed by
|
|
100
|
+
the budget):
|
|
93
101
|
|
|
94
|
-
|
|
95
|
-
|
|
102
|
+
- `ask` (default) — a human approves each new service: allow once,
|
|
103
|
+
always-allow with per-call/session caps, deny, or block.
|
|
104
|
+
- `auto` — no prompts; blocks, caps, reputation checks, the payment
|
|
105
|
+
lifecycle, and the budget still apply.
|
|
106
|
+
- `off` — external purchases are prohibited; local tools and inference keep
|
|
107
|
+
working.
|
|
96
108
|
|
|
97
|
-
|
|
109
|
+
Stored rules are managed with `/approvals`. Every confirmed paid call —
|
|
110
|
+
success or failure — requires a signed CrowdCode review before the next
|
|
111
|
+
purchase; pending reviews survive restarts.
|
|
98
112
|
|
|
99
113
|
## Commands
|
|
100
114
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
| --- | --- |
|
|
105
|
-
| `/budget <usd>` | Set the local session spend cap |
|
|
106
|
-
| `/mode ask_first\|yolo\|blocked` | Set permission mode (shift+tab toggles) |
|
|
107
|
-
| `/wallet list\|balance\|use\|fund\|export` | Manage the shared payment wallet |
|
|
108
|
-
| `/models list\|set <model>` | Pick the x402 LLM model |
|
|
109
|
-
| `/search "<query>"` | Search the x402 service bazaar |
|
|
110
|
-
| `/permissions list\|allow\|block <url>` | Manage allowed/blocked services |
|
|
111
|
-
| `/ledger show` | Show this session's spend ledger |
|
|
112
|
-
| `/summary` | Spend and artifacts so far |
|
|
113
|
-
|
|
114
|
-
One-shot and scripting forms:
|
|
115
|
+
The generated, drift-checked reference is [docs/commands.md](docs/commands.md)
|
|
116
|
+
(`/help` and `opencrowd --help` render the same registry). One-shot and
|
|
117
|
+
scripting forms:
|
|
115
118
|
|
|
116
119
|
```sh
|
|
117
120
|
opencrowd run --budget 1.00 "Find a service and summarize options"
|
|
118
121
|
opencrowd run --session <session-id> "Follow up on the previous result"
|
|
119
|
-
opencrowd
|
|
120
|
-
opencrowd search --json "stock price"
|
|
122
|
+
opencrowd config show
|
|
121
123
|
opencrowd wallet balance
|
|
122
|
-
opencrowd
|
|
124
|
+
opencrowd doctor
|
|
123
125
|
opencrowd evals gaia --tier smoke --harness opencrowd,claude,codex
|
|
124
126
|
```
|
|
125
127
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
128
|
+
## Headless runs
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
opencrowd run --headless --prompt "..." --output json
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Headless execution never waits for UI input: the approval mode comes from
|
|
135
|
+
`--approval ask|auto|off` (or the configured default), and in `ask` mode
|
|
136
|
+
un-ruled purchases are denied with a clear error instead of hanging. The
|
|
137
|
+
JSON output includes the outcome, final message, spend split, turn count,
|
|
138
|
+
resolved model policy, artifacts, and service calls — the same contract the
|
|
139
|
+
eval runner uses.
|
|
133
140
|
|
|
134
141
|
## Local state
|
|
135
142
|
|
|
136
143
|
| What | Where |
|
|
137
144
|
| --- | --- |
|
|
138
|
-
| Config | `~/.config/opencrowd/config.json` |
|
|
139
|
-
| Wallet
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
145
|
+
| Config (defaults for future sessions) | `~/.config/opencrowd/config.json` |
|
|
146
|
+
| Wallet | `~/.agentcash/wallet.json` (owned by AgentCash; never copied) |
|
|
147
|
+
| Approval rules | `~/.config/opencrowd/approvals.json` |
|
|
148
|
+
| Sessions, conversation, ledger, artifacts | `./sessions/<session-id>/` |
|
|
149
|
+
| Purchase receipts (append-only) | `./sessions/<session-id>/purchases.jsonl` |
|
|
143
150
|
|
|
144
151
|
Conversations persist per session and are automatically compacted when they
|
|
145
|
-
outgrow the model's context window (archives kept under
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
- **Model**: defaults to `openai/gpt-5.6-sol` on an x402-metered OpenRouter
|
|
150
|
-
route (`x402LlmBaseUrl` points at any OpenAI-compatible x402 endpoint).
|
|
151
|
-
`opencrowd models list` then `models set <model>` to change it.
|
|
152
|
-
- **Model policy / subagents**: `modelPolicy` in config (`{"mode": "auto"|"manual",
|
|
153
|
-
"main": "<model>|auto", "subagent": "<model>|auto"}`) pairs the main loop
|
|
154
|
-
with a subagent model, both paid over the same x402 route. Defaults:
|
|
155
|
-
`openai/gpt-5.6-sol` main, `openai/gpt-5.6-luna` subagents. The main loop
|
|
156
|
-
gets `spawn_subagent`/`check_subagents` tools (local tools only, one level
|
|
157
|
-
deep, parallel with background mode); resolution is recorded per session
|
|
158
|
-
for reproducibility. Auto mode refuses to run if the catalog has no
|
|
159
|
-
frontier-tier model.
|
|
160
|
-
- **Connectors**: paid capability comes from vendor MCP servers (AgentCash
|
|
161
|
-
for wallet/payments, CrowdCode for reputation), configured under
|
|
162
|
-
`mcpServers` in config with pinned versions. Their tools are ingested
|
|
163
|
-
verbatim (`agentcash_fetch`, `crowdcode_get_service_score`, ...) and their
|
|
164
|
-
own instructions become prompt context. When connectors are unreachable the
|
|
165
|
-
runtime falls back to the legacy Bazaar path.
|
|
166
|
-
- **Discovery (legacy fallback)**: Coinbase CDP Bazaar; custom bazaar URLs
|
|
167
|
-
supported in config.
|
|
168
|
-
- **Env overrides**: `OPENCROWD_BUDGET_CENTS`, `OPENCROWD_PERMISSION_MODE`,
|
|
169
|
-
`OPENCROWD_SHELL_ENABLED`, `OPENCROWD_CONFIG_DIR`, `OPENCROWD_TEST_MODE`.
|
|
152
|
+
outgrow the model's context window (archives kept under
|
|
153
|
+
`sessions/<id>/context/`). `/clear` archives context while keeping the
|
|
154
|
+
session's spend, models, and policy; `/new` starts fresh.
|
|
170
155
|
|
|
171
156
|
## Development
|
|
172
157
|
|
|
173
158
|
```sh
|
|
174
159
|
npm install
|
|
175
|
-
npm run
|
|
160
|
+
npm run typecheck
|
|
176
161
|
npm test
|
|
162
|
+
npm run smoke # build + bundle + demo + headless smoke tests
|
|
163
|
+
npm run deadcode # knip: unused files, exports, dependencies
|
|
177
164
|
```
|
|
178
165
|
|
|
179
|
-
|
|
180
|
-
`packages/
|
|
181
|
-
|
|
182
|
-
|
|
166
|
+
Package layout (see [docs/architecture.md](docs/architecture.md) for the
|
|
167
|
+
full contract): `packages/core` (vendor-neutral sessions, budget, storage,
|
|
168
|
+
tool contracts), `packages/economy` (typed AgentCash/CrowdCode adapters and
|
|
169
|
+
the enforced purchase lifecycle), `packages/agent-runtime` (LLM loop,
|
|
170
|
+
providers, subagents, DI runtime), `packages/evals` (GAIA benchmark
|
|
171
|
+
runner), `apps/cli` (the `opencrowd` binary, TUI, and command registry).
|
|
183
172
|
|
|
184
173
|
See [CONTRIBUTING.md](CONTRIBUTING.md). Licensed [MIT](LICENSE).
|