@heyanon-arp/cli 0.0.7 → 0.0.9

package/examples/worker-template.py

@@ -1,834 +0,0 @@
-#!/usr/bin/env python3
-"""
-ARP Worker Template
-===================
-Plug-and-play template for building autonomous ARP (Agent Relationship
-Protocol) workers. Drop your business logic into `handle_work_request()`
-— everything else (handshake → delegation → work → receipt →
-settlement) is auto-mediated.
-
-What this template does:
-  handshake         → auto-accept
-  delegation offer  → auto-accept (terms inline, idempotent, escrow-aware)
-  work_request      → YOUR CUSTOM HANDLER → work_response
-                    → auto receipt propose (for escrow, the SAME command
-                      also signs + delivers the payee settlement signature)
-
-Quick start:
-  1. Register your agent:  heyarp register --name "MyWorker" --tag my-service ...
-  2. Find your settlement key:  heyarp whoami --local
-  3. Edit the CONFIGURATION section below — at minimum set
-     `MY_SETTLEMENT_PUBKEY` (or `ARP_SETTLEMENT_PUBKEY` env var) to YOUR key.
-  4. Edit `handle_work_request()` with your business logic.
-  5. Run:  python3 my-worker.py
-
-Requirements:
-  - Node ≥22, @heyanon-arp/cli installed (`npm i -g @heyanon-arp/cli`)
-  - Python 3.9+
-  - Registered ARP agent identity
-
-Scope and limitations (V1 alpha):
-  - **FLAT pricing only — by THIS template's choice.** `auto_accept_delegation`
-    below refuses to accept non-flat offers (the delegation carries its
-    pricing_model inline now; a full-release signature on a usage_based
-    lock would let the buyer drain it). The folded settlement step in
-    `heyarp receipt propose` (escrow) DOES handle partial release (it
-    auto-detects from the receipt's usage.computed_amount), so to support
-    usage_based work, relax the pricing gate in `auto_accept_delegation`
-    AND pass `--computed-amount` on the propose call — the settlement step
-    then signs the right (partial) digest.
-  - **Native SOL only by default.** SPL-token settlement requires
-    setting `ARP_MINT_PUBKEY` to the token's mint address (passed through
-    to the settlement command).
-  - **Single-tenant.** Events are processed serially through the SSE
-    loop. Running multiple workers against the same agent identity
-    will fight over `sender_sequence`; use distinct DIDs or a single
-    coordinator.
-
-Discoverability:
-  This template ships bundled with the `@heyanon-arp/cli` npm package.
-  Get a local copy via:
-
-      heyarp examples copy worker --output ./my-worker.py
-
-  or pipe directly:
-
-      heyarp examples show worker > ./my-worker.py
-
-Attribution:
-  Original contribution: Darsio Security Audit
-  (did:arp:7znVy3Doi1xpCfQpjUYxx2UipkCtdayTLTqsH8gejxfG).
-  Cleaned up + wired through `--json` flags.
-License: MIT
-"""
-
-# PEP-563: defer evaluation of all annotations to runtime. Lets us
-# use PEP-604 `dict | None` syntax (Python 3.10+) in signatures
-# while still supporting Python 3.9, which is what the header
-# advertises as the minimum version. Drop this when 3.9 EOL ages
-# out of common installs.
-from __future__ import annotations
-
-import base64
-import hashlib
-import json
-import os
-import shutil
-import subprocess
-import sys
-import time
-import uuid
-from datetime import datetime, timezone
-from pathlib import Path
-
-# ═══════════════════════════════════════════════════════════════
-# CONFIGURATION — change these to match your setup
-# ═══════════════════════════════════════════════════════════════
-#
-# Every constant below honours an env var override of the same name
-# prefixed with `ARP_` / `HEYARP_`. That keeps the file editable for
-# the simplest setup (one worker on one machine) while still letting
-# you parameterise via systemd / Docker / .env for production.
-
-# Path to the heyarp CLI binary. Resolution order:
-#   1. `HEYARP_PATH` env var if set (overrides everything)
-#   2. `heyarp` on `$PATH` (the `npm i -g @heyanon-arp/cli` default)
-#   3. `~/.local/bin/heyarp` (per-user pnpm install)
-# The actual resolution happens in `_preflight` so a missing binary
-# fails loudly there rather than as an opaque ENOENT mid-event.
-
-
-def _resolve_heyarp() -> str:
-    explicit = os.environ.get("HEYARP_PATH")
-    if explicit:
-        return os.path.expanduser(explicit)
-    on_path = shutil.which("heyarp")
-    if on_path:
-        return on_path
-    fallback = os.path.expanduser("~/.local/bin/heyarp")
-    return fallback
-
-
-HEYARP = _resolve_heyarp()
-
-# ARP server URL. **Defaults to production.** Override priority chain
-# (same as the CLI's `resolveServerUrl`):
-#
-#   1. `ARP_SERVER_URL` env var
-#   2. `heyarp config set server <url>` (persistent CLI config)
-#   3. The template default below
-#
-# We only export back into `os.environ` when the operator clearly
-# expressed a choice (env var set OR edited this constant); otherwise
-# the CLI's config resolution wins. See `_preflight`.
-_PRODUCTION_DEFAULT_URL = "https://api.heyanon.ai/arp"
-SERVER_URL = os.environ.get("ARP_SERVER_URL", _PRODUCTION_DEFAULT_URL)
-
-# Working directory for job artifacts (cloned repos, temp files,
-# response payloads). Created lazily in `main()` — no import-time
-# side effects.
-WORK_DIR = Path(
-    os.path.expanduser(os.environ.get("ARP_WORKER_DIR", "~/.arp-worker/jobs"))
-)
-
-# Your agent's settlement public key (find via `heyarp whoami --local`).
-# This is your Solana address where escrowed funds arrive after the
-# buyer cosigns the receipt.
-#
-# **MUST be set** before running. The sentinel below makes the worker
-# refuse to start so you don't accidentally route funds elsewhere.
-_SETTLEMENT_SENTINEL = "REPLACE_WITH_YOUR_SETTLEMENT_PUBKEY"
-MY_SETTLEMENT_PUBKEY = os.environ.get("ARP_SETTLEMENT_PUBKEY", _SETTLEMENT_SENTINEL)
-
-# Cluster tag baked into the on-chain settlement digest. Must match
-# the cluster the escrow program's `create_lock` was submitted on,
-# otherwise `release_lock` rejects the signature.
-#   0 = devnet
-#   1 = mainnet-beta
-# Default is `1` (mainnet) so a production worker is safe by default;
-# override via `ARP_CLUSTER_TAG=0` for devnet testing.
-CLUSTER_TAG = os.environ.get("ARP_CLUSTER_TAG", "1")
-
-# Mint pubkey for settlement. Native SOL uses the System Program id
-# (32 ones in base58). SPL-token settlement requires the token's mint
-# address — set `ARP_MINT_PUBKEY` to override.
-NATIVE_SOL_MINT = "11111111111111111111111111111111"
-MINT_PUBKEY = os.environ.get("ARP_MINT_PUBKEY", NATIVE_SOL_MINT)
-
-
-# ═══════════════════════════════════════════════════════════════
-# SHELL HELPERS — thin wrappers around subprocess
-# ═══════════════════════════════════════════════════════════════
-
-def shell(cmd, timeout=120, cwd=None):
-    """
-    Run a CLI command safely (no `shell=True`, no injection).
-    Returns dict: {ok, stdout, stderr, exit_code}.
-
-    Strips Node deprecation warnings (DEP0040) from stderr so real
-    error messages aren't buried.
-    """
-    try:
-        r = subprocess.run(
-            cmd, shell=False, capture_output=True, text=True,
-            timeout=timeout, cwd=cwd,
-        )
-        stderr_clean = "\n".join(
-            line for line in r.stderr.split("\n")
-            if "DEP0040" not in line and "deprecated" not in line.lower()
-        ).strip()
-        return {
-            "ok": r.returncode == 0,
-            "stdout": r.stdout.strip(),
-            "stderr": stderr_clean,
-            "exit_code": r.returncode,
-        }
-    except subprocess.TimeoutExpired:
-        return {"ok": False, "stdout": "", "stderr": "", "error": f"Timeout {timeout}s"}
-    except Exception as e:
-        return {"ok": False, "stdout": "", "stderr": "", "error": str(e)}
-
-
-def shell_json(cmd, timeout=120):
-    """
-    Run a CLI command that emits a single JSON payload on stdout
-    (the `--json` contract) and parse it.
-
-    Returns the parsed object on success, or None on failure.
-    """
-    r = shell(cmd, timeout=timeout)
-    if not r["ok"] or not r["stdout"]:
-        return None
-    try:
-        return json.loads(r["stdout"])
-    except json.JSONDecodeError as e:
-        print(f"[worker] - JSON parse failed for {cmd[:2]}: {e}")
-        return None
-
-
-def error_code(r: dict) -> str | None:
-    """
-    Extract the machine-readable error `code` from a failed `--json`
-    command. On the failure path the CLI emits a single
-    `{"code": ..., "message": ...}` object on stderr, so the worker
-    keys off `code` instead of substring-matching human text.
-
-    Returns the code string, or None if stderr wasn't structured JSON
-    (e.g. the command was run without `--json`, or a non-CLI error).
-    """
-    stderr = r.get("stderr", "")
-    if not stderr:
-        return None
-    try:
-        parsed = json.loads(stderr)
-    except (json.JSONDecodeError, TypeError):
-        return None
-    return parsed.get("code") if isinstance(parsed, dict) else None
-
-
-# ═══════════════════════════════════════════════════════════════
-# FSM AUTO-RESPONDERS — handle the protocol state machine
-# ═══════════════════════════════════════════════════════════════
-#
-# The ARP work cycle is: handshake → delegation → work → receipt.
-# These handlers auto-accept every non-terminal phase so your worker
-# runs without human intervention.
-#
-# All acceptors are IDEMPOTENT — they safely skip already-processed
-# states (SSE re-delivers events, so retries are normal).
-
-def auto_accept_handshake(sender_did: str):
-    """
-    Auto-accept an inbound handshake.
-
-    Accepting establishes the relationship and unlocks the delegation
-    offer from the buyer.
-    """
-    print(f"[worker] Auto-accepting handshake from {sender_did[:30]}...")
-    r = shell([
-        HEYARP, "send-handshake-response", sender_did,
-        "--decision", "accept",
-        "--notes", "Auto-accepted. Ready for work. Send a delegation offer.",
-        "--json",
-    ], timeout=30)
-    if r["ok"]:
-        # The CLI's idempotency probe short-circuits "already
-        # responded" to a SUCCESS ({ok:true, idempotent:true}), so a
-        # benign retry lands here too — no special-casing needed.
-        print("[worker] ✓ handshake accepted")
-    else:
-        # Read the structured `code` instead of substring-
-        # matching the error text. DOM_INVALID_TRANSITION means the
-        # relationship already advanced past the handshake — benign.
-        code = error_code(r)
-        if code == "DOM_INVALID_TRANSITION":
-            print("[worker] - handshake already resolved (idempotent skip)")
-        else:
-            print(f"[worker] ✗ handshake accept failed: {code or r.get('stderr', '')[:200]}")
-
-
-def fetch_delegation_row(rel_id: str, delegation_id: str) -> dict | None:
-    """
-    Look up a single delegation row by id, paginating `delegations
-    --json` (CLI default limit is 20). Returns the matching row or
-    None if the relationship doesn't host it.
-    """
-    after = None
-    for _ in range(50):
-        cmd = [HEYARP, "delegations", rel_id, "--json", "--limit", "100"]
-        if after:
-            cmd += ["--after", after]
-        rows = shell_json(cmd, timeout=15)
-        if rows is None or not rows:
-            return None
-        row = next((d for d in rows if d.get("delegationId") == delegation_id), None)
-        if row is not None:
-            return row
-        if len(rows) < 100:
-            return None
-        after = rows[-1].get("id")
-    return None
-
-
-def auto_accept_delegation(rel_id: str, delegation_id: str):
-    """
-    Auto-accept a delegation offer.
-
-    Terms are INLINE on the offer (there is no separate contract step):
-    the delegation row carries `pricingModel`, `scopeSummary`,
-    `settlementModel`, rate, amount, currency, and `deadline` — the
-    same terms the `condition_hash` binds to the escrow lock. So both
-    policy gates below (pricing model + settleable deadline) read
-    straight off the delegation row.
-
-    Pricing-model gate: this template only handles `flat` offers
-    (full-release settlement). For `usage_based` offers the on-chain
-    `partial_release` ix needs a different digest
-    (`ARP-SOLANA-PARTIAL-RELEASE-v1.5` + `--partial-payee-amount`).
-    The folded settlement step in `receipt propose` DOES generate it
-    (auto-detected from the receipt's usage.computed_amount), but this
-    template's `receipt propose` call doesn't pass `--computed-amount`,
-    so a usage_based settle would refuse downstream and strand the work
-    — refuse the offer up-front instead. To support usage_based work,
-    relax this gate AND pass `--computed-amount` on the propose call.
-
-    Settleability policy gate: this template auto-settles each receipt
-    via the settlement step folded into `receipt propose` (escrow),
-    which derives the payee signature's `expires_at` from the
-    delegation's `deadline` (+ the server-side buffer). A delegation
-    with NO deadline can't be auto-settled — propose refuses to
-    fabricate an expiry that might exceed the on-chain lock (a
-    post-commit server reject that burns a sender_sequence). If we
-    accepted a deadline-less offer we'd do the work, propose a receipt,
-    then fail to settle and strand it — so we read the delegation row
-    and refuse deadline-less offers.
-
-    Read-model lag: the offer SSE event can arrive BEFORE the
-    `delegations` read-model row materializes, so a missing row is
-    almost always a transient timing gap, NOT an invalid offer. We
-    retry with backoff; if it still hasn't appeared we accept anyway
-    rather than permanently drop a valid offer — the settlement step
-    still refuses a deadline-less settle downstream, so funds can't be
-    misrouted (worst case: the operator settles manually with
-    `--expires-at`).
-
-    Error handling (keyed off the structured `code`, not
-    substring matching):
-    - DELEGATION_INVALID_STATE → already accepted → idempotent skip
-    - ESC_* → buyer's lock is broken (insufficient funds, etc.)
-    - Other → logged for debugging
-    """
-    # Policy pre-flight: confirm the delegation carries a deadline we
-    # can settle against. The offer SSE event can land BEFORE the
-    # `delegations` read-model row materializes, so a None here is almost
-    # always transient lag — retry with backoff instead of dropping a
-    # valid offer.
-    row = None
-    for attempt in range(5):  # ~5 tries over ~7.5s to ride out read-model lag
-        row = fetch_delegation_row(rel_id, delegation_id)
-        if row is not None:
-            break
-        if attempt < 4:
-            time.sleep(min(0.5 * (2 ** attempt), 4.0))  # 0.5, 1, 2, 4
-    if row is not None and not row.get("deadline"):
-        print(
-            f"[worker] ✗ refusing delegation {delegation_id[:20]} — "
-            "no deadline set; this template auto-settles via "
-            "deadline+buffer and can't derive a safe settlement expiry. "
-            "Accept manually + run `heyarp receipt propose ... "
-            "--cluster-tag <0|1> --expires-at <unix-secs>` to handle it."
-        )
-        return
-    # Pricing-model gate: terms ride inline on the offer, so the
-    # delegation row carries `pricingModel` directly (no contract
-    # lookup). Default to 'flat' when absent (no-escrow / unpriced
-    # offers). Refuse usage_based — see the docstring for why.
-    if row is not None and str(row.get("pricingModel") or "flat") != "flat":
-        print(
-            f"[worker] ✗ refusing delegation {delegation_id[:20]} — "
-            f"pricingModel={row.get('pricingModel')!r}; this template only "
-            "handles `flat`. Decline manually, or relax this gate AND pass "
-            "`--computed-amount` on the receipt propose call to support "
-            "ARP-SOLANA-PARTIAL-RELEASE-v1.5 settlement."
-        )
-        return
-    if row is None:
-        # Row never materialized within the retry budget — accept anyway
-        # rather than drop a valid offer; the settlement step still
-        # refuses a deadline-less settle, so funds can't be misrouted.
-        print(
-            f"[worker] - delegation {delegation_id[:20]} row not visible yet "
-            "(read-model lag); accepting, deadline check deferred to settlement."
-        )
-
-    print(f"[worker] Auto-accepting delegation {delegation_id[:20]}...")
-    r = shell([HEYARP, "delegation", "accept", rel_id, delegation_id, "--json"], timeout=30)
-    if r["ok"]:
-        print("[worker] ✓ delegation accepted")
-        return
-    code = error_code(r)
-    if code == "DELEGATION_INVALID_STATE":
-        print("[worker] - delegation already accepted (idempotent skip)")
-    elif code and code.startswith("ESC"):
-        print(f"[worker] - escrow issue (buyer-side): {code}")
-    else:
-        print(f"[worker] ✗ delegation accept failed: {code or r.get('stderr', '')[:200]}")
-
-
-# ═══════════════════════════════════════════════════════════════
-# BUSINESS LOGIC — YOUR CUSTOM CODE GOES HERE
-# ═══════════════════════════════════════════════════════════════
-#
-# This is the only function you NEED to customize.
-# It receives the parsed work_request and must return a dict that
-# becomes the work_response output.
-#
-# Input fields:
-#   params     — dict from work_request body.content.params
-#   rel_id     — relationship UUID
-#   del_id     — delegation UUID
-#   req_id     — request UUID
-#   sender_did — buyer's DID
-#
-# Return a dict with your results. The `report` field with base64
-# data is optional — include it when delivering binary artifacts
-# (PDF, image, audio). The `usage` field tells the buyer how to
-# decode them.
-
-def handle_work_request(params: dict, rel_id: str, del_id: str,
-                        req_id: str, sender_did: str) -> dict:
-    """
-    ╔══════════════════════════════════════════════════════════╗
-    ║  YOUR BUSINESS LOGIC GOES HERE                           ║
-    ║  Replace this with your actual service implementation    ║
-    ╚══════════════════════════════════════════════════════════╝
-
-    This example does a trivial text analysis. Swap it for your
-    actual logic: call an API, run a model, process a file.
-
-    The returned dict is the work_response output. Protocol handles
-    signing, hashing, and delivery automatically.
-    """
-    # Extract inputs — support flat `{key}` and nested `{target: {key}}`.
-    task = params.get("task", params.get("target", {}).get("task", "unknown"))
-    text = params.get("text", params.get("target", {}).get("text", ""))
-
-    # Your processing logic.
-    result = {
-        "task": task,
-        "input_length": len(text),
-        "word_count": len(text.split()) if text else 0,
-        "processed_at": datetime.now(timezone.utc).isoformat(),
-    }
-
-    # Optional binary artifact (base64 in the response body).
-    response: dict = {"verdict": "completed", "result": result}
-    if text:
-        report = f"Analysis of: {text[:100]}...\nWords: {result['word_count']}\n"
-        artifact_b64 = base64.b64encode(report.encode()).decode()
-        response["report"] = {
-            "format": "text",
-            "filename": "analysis-report.txt",
-            "data_base64": artifact_b64,
-            "sha256": f"sha256:{hashlib.sha256(report.encode()).hexdigest()}",
-        }
-        response["usage"] = {
-            "how_to_open": "Binary data is base64-encoded in report.data_base64.",
-            "python": (
-                "import base64; "
-                "open('report.txt','wb').write(base64.b64decode(data_base64))"
-            ),
-            "node": (
-                "require('fs').writeFileSync("
-                "'report.txt', Buffer.from(data_base64, 'base64'))"
-            ),
-            "verify_integrity": "sha256sum report.txt  # must match report.sha256",
-        }
-
-    return response
-
-
-# ═══════════════════════════════════════════════════════════════
-# SETTLEMENT
-# ═══════════════════════════════════════════════════════════════
-#
-# To release escrow on Solana the buyer needs BOTH parties' settlement
-# signatures. The payee (us) must generate its signature and deliver it
-# to the buyer.
-#
-# This is now FOLDED into `receipt propose`: for an escrow delegation,
-# the SAME `heyarp receipt propose ... --cluster-tag <0|1>` command that
-# commits the receipt also signs + delivers the payee settlement
-# signature right after — collapsing the whole ~90-line ritual (resolve
-# buyer key → derive condition_hash → fetch amount/decimals/deadline →
-# compute expiry → sign release digest → deliver via settlement_signature
-# envelope) so a worker can't forget the separate step. The main loop
-# below just reads the `settlement` block off the propose --json result.
-# The folded step:
-#   - auto-resolves rel-id, buyer DID, condition_hash, amount,
-#     decimals, deadline, and the receipt hashes
-#   - auto-detects FULL (flat) vs PARTIAL (usage_based, from the
-#     receipt's usage.computed_amount) release
-#   - is idempotent (skips when the payee sig was already delivered)
-#   - on partial failure (no RPC / lock not visible) leaves the receipt
-#     committed and 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.
-#
-# Requires `@heyanon-arp/cli` with the folded `receipt propose` escrow
-# settlement (the standalone `settlement auto-sign-and-deliver` command
-# was removed).
-
-
-# ═══════════════════════════════════════════════════════════════
-# WORK REQUEST PROCESSOR — wires business logic to protocol
-# ═══════════════════════════════════════════════════════════════
-
-def process_work_request(event_data: dict):
-    """
-    Extract parameters from a work_request SSE event and invoke
-    your custom handler.
-
-    Returns (output_dict, rel_id, del_id, req_id, sender_did).
-    """
-    body = event_data.get("body", {})
-    content = body.get("content", {})
-    params = content.get("params", {})
-
-    rel_id = (
-        event_data.get("relationshipId", "")
-        or event_data.get("protectedBlock", {}).get("relationship_id", "")
-        or event_data.get("protected", {}).get("relationship_id", "")
-    )
-    delegation_id = content.get("delegation_id", "")
-    request_id = content.get("request_id", "")
-    sender_did = (
-        event_data.get("senderDid", "")
-        or event_data.get("protectedBlock", {}).get("sender_did", "")
-        or event_data.get("protected", {}).get("sender_did", "")
-    )
-
-    print(f"[worker] === New job: {str(params.get('task', 'unknown'))[:60]} ===")
-    print(f"[worker] From: {sender_did[:30]}...")
-    print(f"[worker] Relationship: {rel_id}")
-
-    output = handle_work_request(params, rel_id, delegation_id, request_id, sender_did)
-    return output, rel_id, delegation_id, request_id, sender_did
-
-
-def send_work_response(rel_id: str, delegation_id: str, request_id: str,
-                       output: dict) -> dict:
-    """
-    Send work_response via heyarp CLI. Writes output to a temp JSON
-    file to dodge shell-quoting issues with large/complex payloads.
-    """
-    tmp_json = WORK_DIR / f"response_{uuid.uuid4().hex[:8]}.json"
-    tmp_json.write_text(json.dumps(output, ensure_ascii=False))
-    try:
-        return shell([
-            HEYARP, "work", "respond",
-            rel_id, delegation_id, request_id,
-            "--output-file", str(tmp_json),
-        ], timeout=30)
-    finally:
-        tmp_json.unlink(missing_ok=True)
-
-
-# ═══════════════════════════════════════════════════════════════
-# MAIN EVENT LOOP — SSE listener + FSM dispatch
-# ═══════════════════════════════════════════════════════════════
-
-def _preflight():
-    """Fail loudly on misconfigurations before connecting to SSE."""
-    if MY_SETTLEMENT_PUBKEY == _SETTLEMENT_SENTINEL:
-        print(
-            "[worker] FATAL: MY_SETTLEMENT_PUBKEY is still the placeholder.\n"
-            "  Set it to YOUR settlement key (from `heyarp whoami --local`)\n"
-            "  either by editing this file or via the ARP_SETTLEMENT_PUBKEY env var.\n"
-            "  Refusing to start — funds would route to the wrong address.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    if CLUSTER_TAG not in ("0", "1"):
-        print(
-            f"[worker] FATAL: ARP_CLUSTER_TAG={CLUSTER_TAG!r} must be '0' (devnet) "
-            "or '1' (mainnet-beta) — the on-chain validator rejects other values.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    WORK_DIR.mkdir(parents=True, exist_ok=True)
-    # Server resolution: if the operator set `ARP_SERVER_URL` we
-    # already inherit it. If they only edited the constant in this
-    # file (SERVER_URL differs from the production default), promote
-    # that into the env so subprocess `heyarp` calls see it. If
-    # neither — leave `os.environ` alone so the CLI's own resolution
-    # (`heyarp config set server`, then the CLI default) takes over.
-    # This preserves config-only setups that don't set env vars.
-    env_set = "ARP_SERVER_URL" in os.environ
-    edited_constant = SERVER_URL != _PRODUCTION_DEFAULT_URL
-    if not env_set and edited_constant:
-        os.environ["ARP_SERVER_URL"] = SERVER_URL
-    # Verify the binary is actually callable. The display string we
-    # store in HEYARP might be `~/.local/bin/heyarp` (fallback) which
-    # doesn't exist on every machine.
-    if not os.path.isabs(HEYARP) and shutil.which(HEYARP) is None:
-        print(
-            f"[worker] FATAL: heyarp CLI not found on $PATH. Install via\n"
-            f"  npm i -g @heyanon-arp/cli\n"
-            f"or set HEYARP_PATH to an absolute path.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    if os.path.isabs(HEYARP) and not os.path.exists(HEYARP):
-        print(
-            f"[worker] FATAL: heyarp binary not at {HEYARP!r}. Install via\n"
-            f"  npm i -g @heyanon-arp/cli\n"
-            f"or set HEYARP_PATH to your install location.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    # Settlement is now signed by the `receipt propose` escrow step
-    # using the AGENT's stored settlement key (resolved from local
-    # heyarp state), NOT the MY_SETTLEMENT_PUBKEY constant. So this
-    # value is only meaningful as an assertion: verify it matches the
-    # key the worker will actually be paid on, otherwise funds would
-    # arrive at the agent's address and you'd only find out after a job
-    # settles. Uses the same sole-agent resolution as the settlement
-    # step (run a single worker per DID — see README caveats).
-    who = shell_json([HEYARP, "whoami", "--local", "--json"], timeout=15)
-    if who is None:
-        print(
-            "[worker] FATAL: couldn't resolve your local agent via\n"
-            "  heyarp whoami --local --json\n"
-            "  (none registered, or more than one without a selector).\n"
-            "  Register one with `heyarp register` and run one worker per DID.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    agent_key = who.get("settlementPublicKeyB58", "")
-    if agent_key != MY_SETTLEMENT_PUBKEY:
-        print(
-            f"[worker] FATAL: MY_SETTLEMENT_PUBKEY ({MY_SETTLEMENT_PUBKEY})\n"
-            f"  does not match your heyarp agent's settlement key ({agent_key}).\n"
-            "  `receipt propose` (escrow) signs with the AGENT's key, so\n"
-            "  funds would route to the agent's address, not the one set here.\n"
-            "  Fix ARP_SETTLEMENT_PUBKEY to match `heyarp whoami --local`, or\n"
-            "  re-register the agent with the intended settlement key.",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-
-
-def _spawn_inbox() -> subprocess.Popen:
-    """Open the SSE stream. Server selection is propagated via
-    `ARP_SERVER_URL` in `_preflight` so we don't need to thread
-    `--server` through every subprocess call."""
-    return subprocess.Popen(
-        [HEYARP, "inbox", "--tail", "--json"],
-        stdout=subprocess.PIPE, stderr=subprocess.PIPE,
-        text=True, bufsize=1,
-    )
-
-
-def main():
-    _preflight()
-
-    print("[worker] === ARP Worker ===")
-    print(f"[worker] Server:        {SERVER_URL}")
-    print(f"[worker] Settlement:    {MY_SETTLEMENT_PUBKEY} (verified == agent key)")
-    print(f"[worker] Cluster tag:   {CLUSTER_TAG} ({'mainnet-beta' if CLUSTER_TAG == '1' else 'devnet'})")
-    print(f"[worker] Mint:          {MINT_PUBKEY} ({'native SOL' if MINT_PUBKEY == NATIVE_SOL_MINT else 'SPL token'})")
-    print(f"[worker] Working dir:   {WORK_DIR}")
-    print("[worker] Auto-accept:   handshake ✓ | delegation ✓")
-    print("[worker] Auto-settle:   receipt → sign → deliver → buyer\n")
-
-    proc = _spawn_inbox()
-
-    try:
-        for line in proc.stdout:
-            line = line.strip()
-            if not line:
-                continue
-
-            try:
-                data = json.loads(line)
-            except json.JSONDecodeError:
-                # Non-JSON line (shouldn't happen with --json, but
-                # Node sometimes leaks a deprecation warning).
-                continue
-
-            event_type = data.get("type", "")
-            envelope = data.get("data", data)
-
-            # Control messages.
-            if event_type in ("tail.started", "connected", "heartbeat"):
-                continue
-
-            if event_type == "stream.ended":
-                print("[worker] SSE stream ended — reconnecting in 5s...")
-                time.sleep(5)
-                proc.terminate()
-                proc.wait()
-                proc = _spawn_inbox()
-                continue
-
-            # Dispatch by body type.
-            body = envelope.get("body", {})
-            body_type = body.get("type", "")
-
-            if body_type == "handshake":
-                sender_did = envelope.get("senderDid", "")
-                print(f"\n[worker] >>> Handshake from {sender_did[:30]}...")
-                auto_accept_handshake(sender_did)
-
-            elif body_type == "delegation":
-                content = body.get("content", {})
-                if content.get("action") == "offer":
-                    rel_id = envelope.get("relationshipId", "")
-                    delegation_id = content.get("delegation_id", "")
-                    print(f"\n[worker] >>> Delegation offer {delegation_id[:20]}...")
-                    auto_accept_delegation(rel_id, delegation_id)
-
-            elif body_type == "work_request":
-                print("\n[worker] >>> Work request received!")
-                rel_id = del_id = req_id = ""
-                try:
-                    # 1. Run your business logic.
-                    output, rel_id, del_id, req_id, sender = process_work_request(envelope)
-
-                    # 2. Send work_response.
-                    print("[worker] Sending work_response...")
-                    r = send_work_response(rel_id, del_id, req_id, output)
-                    if not r["ok"]:
-                        print(f"[worker] ✗ Response failed: {r.get('stderr','')[:200]}")
-                        continue
-                    print("[worker] ✓ work_response sent")
-
-                    # 3. Skip if a receipt already exists for this
-                    #    delegation (one receipt per delegation by FSM).
-                    rc = shell([HEYARP, "receipts", rel_id], timeout=15)
-                    if rc["ok"] and del_id[:20] in rc["stdout"]:
-                        print("[worker] - receipt already exists for delegation, skipping")
-                        continue
-
-                    # 4. Auto-propose receipt AND deliver the payee
-                    #    settlement signature in ONE command (--json output).
-                    #    For an ESCROW delegation, `receipt propose` signs +
-                    #    delivers the payee settlement signature itself right
-                    #    after committing the receipt — the worker can no
-                    #    longer forget a separate step (an undelivered sig
-                    #    would strand the buyer's cosign on
-                    #    ESC_SETTLEMENT_SIGS_MISSING). It resolves the buyer
-                    #    key, condition hash, amount/decimals/deadline, and
-                    #    the receipt hashes itself, signs the release digest,
-                    #    and delivers via a settlement_signature envelope.
-                    #    Idempotent on re-run; auto-detects full (flat) vs
-                    #    partial (usage_based) release.
-                    #
-                    #    --cluster-tag is REQUIRED for an escrow delegation
-                    #    (binds the cluster into the signed release digest;
-                    #    a wrong/defaulted cluster fails at the buyer cosign).
-                    #    --fee-bps-at-lock 0: this template targets no-fee
-                    #    deployments (see README). The release digest binds
-                    #    the lock's fee snapshot; passing 0 makes that
-                    #    assumption explicit. On a fee-CHARGING deployment
-                    #    you must pass the lock's actual fee_bps_at_lock +
-                    #    --fee-recipient-at-lock instead.
-                    print("[worker] Auto-proposing receipt (+ delivering settlement sig for escrow)...")
-                    # Use shell() (not shell_json) so we still capture the
-                    # JSON on a PARTIAL-FAILURE exit: an escrow propose that
-                    # commits the receipt but fails to deliver the settlement
-                    # sig (no RPC / lock not yet visible) exits non-zero while
-                    # still emitting the `settlement` block on stdout. Gating
-                    # on `is None` (shell_json) would skip the recovery handler
-                    # below and loop into RECEIPT_ALREADY_EXISTS.
-                    proposal = shell([
-                        HEYARP, "receipt", "propose", sender,
-                        del_id, "--auto-hashes", "--rel-id", rel_id,
-                        "--request-id", req_id, "--verdict", "accepted",
-                        "--cluster-tag", CLUSTER_TAG, "--mint-pubkey", MINT_PUBKEY,
-                        "--fee-bps-at-lock", "0",
-                        "--json",
-                    ], timeout=30)
-                    receipt = None
-                    if proposal["stdout"]:
-                        try:
-                            receipt = json.loads(proposal["stdout"])
-                        except Exception:
-                            receipt = None
-                    if receipt is None:
-                        print(f"[worker] - receipt propose failed: {proposal.get('stderr') or proposal.get('error') or 'no parseable output'}")
-                        continue
-                    print("[worker] ✓ receipt proposed" + ("" if proposal["ok"] else " (settlement step reported a problem — see below)"))
-
-                    # 5. Report the folded settlement outcome. For an escrow
-                    #    delegation `receipt propose` returns a `settlement`
-                    #    block: {delivered, purpose, ...} on success, or
-                    #    {delivered: false, error, recovery} on partial
-                    #    failure (no RPC / lock not yet visible). The receipt
-                    #    is committed either way; on partial failure re-run
-                    #    propose once the lock is reachable, or follow the
-                    #    `recovery` hint (`heyarp receipt send-payee-sig`).
-                    settle = receipt.get("settlement")
-                    if settle is None:
-                        # Prepaid (non-escrow) delegation — no settlement step.
-                        print("[worker] ✓ no settlement step (prepaid delegation)")
-                    elif settle.get("delivered"):
-                        tag = " (idempotent)" if settle.get("idempotent") else ""
-                        print(f"[worker] ✓ settlement signed + delivered: {settle.get('purpose')}{tag}")
-                    else:
-                        print(
-                            "[worker] ✗ receipt proposed but settlement sig NOT delivered: "
-                            f"{settle.get('error', 'unknown')}. Recover: {settle.get('recovery', '')}"
-                        )
-
-                except Exception as e:
-                    print(f"[worker] ✗ Error: {e}")
-                    # Send error response so the buyer sees something
-                    # went wrong on our side.
-                    if rel_id and del_id and req_id:
-                        try:
-                            shell([
-                                HEYARP, "work", "respond",
-                                rel_id, del_id, req_id,
-                                "--error", f"PROCESSING_ERROR:{str(e)[:200]}",
-                            ], timeout=30)
-                        except Exception:
-                            pass
-
-            else:
-                # Other event types (receipt cosign, dispute, etc.) —
-                # logged but not auto-handled. Add handlers here if you
-                # need them.
-                if body_type:
-                    print(f"[worker] event: {body_type}", end="\r")
-
-    except KeyboardInterrupt:
-        print("\n[worker] Shutting down...")
-    finally:
-        proc.terminate()
-        proc.wait()
-
-
-if __name__ == "__main__":
-    main()