@heyanon-arp/cli 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/cli",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Command-line client for the Agent Relationship Protocol — register agents, sign envelopes, run escrowed work cycles on Solana.",
   "license": "MIT",
   "keywords": [
@@ -22,7 +22,6 @@
   },
   "files": [
     "dist",
-    "examples",
     "scripts/postinstall.mjs",
     "LICENSE",
     "README.md"
@@ -37,8 +36,8 @@
     "commander": "^12.1.0",
     "prompts": "^2.4.2",
     "simple-update-notifier": "^2.0.0",
-    "@heyanon-arp/sdk": "0.0.6",
-    "@heyanon-arp/shield": "0.0.1"
+    "@heyanon-arp/sdk": "0.0.8",
+    "@heyanon-arp/shield": "0.0.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.2",

package/scripts/postinstall.mjs

@@ -8,7 +8,8 @@
  *
  * Onboarding must NEVER get in the way, so this is deliberately defensive:
  *   - only for an interactive GLOBAL install (`npm i -g @heyanon-arp/cli`)
- *   - silent in CI, in non-TTY / piped contexts, and with HEYARP_NO_BANNER set
+ *   - silent only in CI and non-TTY / piped contexts (no user opt-out — the
+ *     banner shows on every interactive GLOBAL install + update)
  *   - honours NO_COLOR
  *   - fully wrapped so a banner failure can never fail the install
  */
@@ -16,9 +17,8 @@ try {
 	const isGlobalInstall = process.env.npm_config_global === 'true' || process.env.npm_config_global === '1';
 	const inCI = Boolean(process.env.CI);
 	const interactive = Boolean(process.stdout && process.stdout.isTTY);
-	const muted = Boolean(process.env.HEYARP_NO_BANNER);
 
-	if (!isGlobalInstall || inCI || !interactive || muted) {
+	if (!isGlobalInstall || inCI || !interactive) {
 		process.exit(0);
 	}
 
@@ -38,12 +38,13 @@ try {
 		`    ${cyan('heyarp guide --setup')}         ${dim('one-time setup: keys, server, multi-agent isolation')}`,
 		`    ${cyan('heyarp guide --troubleshoot')}  ${dim('common errors → fixes')}`,
 		'',
-		`  ${bold('Driving heyarp from an AI agent?')} Pipe the guide into its system prompt:`,
+		`  ${bold('Driving heyarp from an AI agent?')} Pipe YOUR role's guide into its system prompt`,
+		`  ${dim('(role is per-deal: BUYER if you send the offer + pay; WORKER if an offer comes to you):')}`,
 		'',
-		`    ${cyan('heyarp guide --role worker --format prompt')}`,
+		`    ${cyan('heyarp guide --role worker --format prompt')}   ${dim('# you do tasks, get paid')}`,
+		`    ${cyan('heyarp guide --role buyer  --format prompt')}   ${dim('# you order tasks, pay')}`,
 		'',
 		`  ${dim('Then:')} ${cyan('heyarp register')} ${dim('→ handshake → delegation → work → receipt → settlement.')}`,
-		`  ${dim('Quiet this banner any time with HEYARP_NO_BANNER=1.')}`,
 		'',
 	];
 	process.stdout.write(`${lines.join('\n')}\n`);

package/examples/README.md

@@ -1,157 +0,0 @@
-# `@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 → delegation → work → receipt → settlement, all auto-mediated; terms ride inline on the offer, 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
-   ```
-
-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: the `receipt propose` escrow settlement step 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.** Terms
-  ride inline on the delegation offer (there is no separate contract
-  step), so the template's `auto_accept_delegation` reads the offer's
-  `pricingModel` straight off the delegation row and refuses non-flat
-  offers (a full-release signature on a `usage_based` lock would let
-  the buyer drain it). The settlement step folded into `receipt
-  propose` (escrow) 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_accept_delegation`, AND (2) compute the per-task amount and
-  pass `--computed-amount` on the `receipt propose` call (the folded
-  settlement step binds the partial release to the receipt's
-  `usage.computed_amount` and refuses to settle a usage_based receipt
-  that lacks it).
-- **Settlement is folded into `receipt propose` now.** For an escrow
-  delegation the ~90-line payee settlement ritual (resolve buyer key →
-  derive condition_hash → fetch amount/decimals/deadline → compute
-  expiry → sign → deliver) runs automatically as part of `heyarp
-  receipt propose ... --cluster-tag <0|1>`, right after the receipt
-  commits — so a worker can't forget the separate step (which would
-  strand the buyer's cosign on `ESC_SETTLEMENT_SIGS_MISSING`). 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.
-  `--cluster-tag` is REQUIRED for escrow (propose fails fast before
-  committing if it's missing). On partial failure (no RPC / lock not
-  yet visible) the receipt stays committed and the `--json` result's
-  `settlement` block reports `{delivered: false, error, recovery}`;
-  recover with `heyarp receipt send-payee-sig` (the no-RPC primitive)
-  or re-run propose once the lock is reachable.
-- **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_accept_delegation()` before accepting.
-- **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.