@heyanon-arp/cli 0.0.4 → 0.0.6

package/examples/README.md

@@ -0,0 +1,147 @@
+# `@heyanon-arp/cli` — bundled examples
+
+This directory ships with the npm package and is reachable from
+inside a working CLI install via `heyarp examples`:
+
+```bash
+heyarp examples list                                # list bundled examples
+heyarp examples show worker                         # print to stdout
+heyarp examples show worker > my-worker.py          # pipe to file
+heyarp examples copy worker --output ./my-worker.py # copy to disk
+```
+
+The CLI resolves bundled paths relative to its own runtime location
+(`<node_modules>/@heyanon-arp/cli/examples/...`), so you do not need
+network access or a checkout of the source repository — `npm i -g
+@heyanon-arp/cli` is enough.
+
+## Current examples
+
+| File | Subject | Status |
+|---|---|---|
+| [`worker-template.py`](./worker-template.py) | Autonomous Python worker (handshake → contract → delegation → work → receipt → settlement, all auto-mediated; you fill in `handle_work_request()`) | Reference; FLAT pricing + full-release settlement only. MIT. |
+
+## How to use the worker template
+
+1. Register an agent (one-time):
+
+   ```bash
+   heyarp register --name "MyWorker" --tag my-service --endpoint-url https://my-agent.example/inbox
+   ```
+
+2. Copy the template:
+
+   ```bash
+   heyarp examples copy worker --output ./my-worker.py
+   ```
+
+3. Edit `handle_work_request(params, rel_id, del_id, req_id, sender_did)` in
+   the copied file — that is the only function with your business logic.
+   Everything else (FSM mediation, signing, settlement) is policy.
+
+4. Set your agent's settlement public key. Either edit
+   `MY_SETTLEMENT_PUBKEY` at the top of the file, or set the
+   `ARP_SETTLEMENT_PUBKEY` env var. Find your key via:
+
+   ```bash
+   heyarp whoami --local
+   ```
+
+   The worker refuses to start while the placeholder is still in place
+   (so funds can never accidentally route to the template's default).
+   It also refuses if the value does not match your agent's actual
+   settlement key: `settlement auto-sign-and-deliver` signs with the
+   agent's stored key, so a mismatch would route funds to the agent's
+   address rather than the one you set here. The preflight resolves the
+   real key via `heyarp whoami --local` and compares.
+
+5. Pick your cluster. Defaults to **mainnet-beta** (cluster tag `1`).
+   Override for devnet testing:
+
+   ```bash
+   export ARP_CLUSTER_TAG=0
+   ```
+
+6. Run:
+
+   ```bash
+   python3 my-worker.py
+   ```
+
+   The worker connects to the server's inbox SSE stream and starts
+   accepting offers per the policy in the file.
+
+## Environment variables
+
+The template honours every override below — set them in the shell
+that launches the worker, or in a process supervisor (systemd /
+Docker / launchd).
+
+| Variable | Default | Notes |
+|---|---|---|
+| `ARP_SETTLEMENT_PUBKEY` | _(required)_ | Your Solana settlement address from `heyarp whoami --local`. Worker refuses to start without it. |
+| `ARP_SERVER_URL` | `https://api.heyanon.ai/arp` | Override to point at dev / staging / self-hosted. |
+| `ARP_CLUSTER_TAG` | `1` (mainnet-beta) | `0` for devnet. Must match the cluster where the on-chain lock lives. |
+| `ARP_MINT_PUBKEY` | System Program id (native SOL) | Set to the SPL token's mint address for non-SOL settlement. |
+| `ARP_WORKER_DIR` | `~/.arp-worker/jobs` | Working directory for temp response payloads. Created lazily. |
+| `HEYARP_PATH` | `heyarp` (from `$PATH`) | Absolute path to the CLI binary if it isn't on `$PATH`. |
+
+## Caveats
+
+- **Pricing model coverage — FLAT by the template's choice.** The
+  template's `auto_sign_contract` refuses to sign non-flat contracts
+  (a full-release signature on a `usage_based` lock would let the
+  buyer drain it). The settlement step itself —
+  `heyarp settlement auto-sign-and-deliver` — DOES handle
+  both: it auto-detects full (flat) vs partial (`usage_based`, from
+  the receipt's `usage.computed_amount`) release and signs the right
+  digest (`ARP-SOLANA-RELEASE-v1.5` / `ARP-SOLANA-PARTIAL-RELEASE-v1.5`).
+  To support `usage_based` work, TWO changes are needed — not just
+  one: (1) relax the FLAT-only gate in `auto_sign_contract`, AND
+  (2) compute the per-task amount and pass `--computed-amount` on the
+  `receipt propose` call (the settlement command binds the partial
+  release to the receipt's `usage.computed_amount` and refuses to
+  settle a usage_based receipt that lacks it).
+- **Settlement is one command now.** The ~90-line payee settlement
+  ritual (resolve buyer key → derive condition_hash → fetch
+  amount/decimals/deadline → compute expiry → sign → deliver)
+  collapses to `heyarp settlement auto-sign-and-deliver
+  --delegation-id <id> --cluster-tag <0|1>`. It auto-resolves the rest
+  from the delegation id, signs the release digest (reusing `wallet
+  sign-settlement-release`), and delivers via a `settlement_signature`
+  envelope the buyer consumes with `receipt cosign
+  --auto-resolve-payee-sig`. Idempotent — safe to re-run.
+- **Policy is hard-coded.** The auto-accept criteria live inline in
+  the Python file. A future `heyarp worker run --policy worker-policy.yaml`
+  worker daemon would move those into a
+  declarative config + add budget caps, observability, dry-run mode.
+  Until that ships, treat this template as a quick way to validate
+  the protocol against your business logic, not as a production
+  runner — at minimum, add a price ceiling check in
+  `auto_sign_contract()` before signing.
+- **Single-tenant.** Events are processed serially in the SSE loop;
+  if you need parallelism, run multiple workers under **distinct DIDs**
+  (running two against the same identity will fight over
+  `sender_sequence`).
+
+## Contributing an example
+
+Drop a new file in this directory + update both this README and the
+`heyarp examples list` registry (see
+`packages/cli/src/commands/examples.ts`). Templates should:
+
+- Carry an attribution header (author, license, status).
+- Be self-contained (single file, no external repo checkouts).
+- Document any `MY_*` constants the user must set before running.
+- Default any "real money" parameters to **fail-fast sentinels**, not
+  the contributor's own keys / endpoints. The worker refuses to start
+  if a sentinel survives — the test that lands in `examples.spec.ts`
+  pins this contract.
+- Use `--json` flags on every CLI invocation that has them (the
+  `--json` consistency pass); avoid regex parsing of
+  human-formatted output.
+- Read error **codes**, not error text. In `--json` mode a failing
+  command emits `{"code": "...", "message": "..."}` on stderr.
+  Branch on `code` (the template's `error_code(r)` helper
+  parses it) rather than substring-matching the message — codes are
+  stable, messages are not.