@heyanon-arp/cli 0.0.3 → 0.0.5

package/examples/worker-template.py

@@ -0,0 +1,894 @@
+#!/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 → contract → delegation → work → receipt
+→ settlement) is auto-mediated.
+
+What this template does:
+  handshake         → auto-accept
+  contract proposal → auto-sign
+  delegation offer  → auto-accept (idempotent, escrow-aware)
+  work_request      → YOUR CUSTOM HANDLER → work_response
+                    → auto receipt propose
+                    → settlement auto-sign-and-deliver (one command)
+
+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_sign_contract`
+    below refuses to sign non-flat contracts (a full-release signature on
+    a usage_based lock would let the buyer drain it). The underlying
+    `heyarp settlement auto-sign-and-deliver` command 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_sign_contract` — the settlement step already does the right thing.
+  - **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 contract'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 → contract → 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 contract
+    proposals 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 contract proposal.",
+        "--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 fetch_contract_row(rel_id: str, contract_id: str) -> dict | None:
+    """
+    Look up the latest-version row for `contract_id` and return it
+    (dict with `state`, `pricingModel`, `version`, ...). Returns None
+    if the row is missing or the server rejects the list call.
+
+    Paginates through `contracts --json` with the maximum page size
+    (100). The CLI default is 20, which would miss a contract on a
+    long-lived relationship — this loop walks until pages exhaust,
+    bounded at 50 pages × 100 rows = 5000 contracts (any real-world
+    relationship beyond that is anomalous and worth manual inspection).
+    """
+    matches = []
+    after = None
+    for _ in range(50):
+        cmd = [HEYARP, "contracts", rel_id, "--json", "--limit", "100"]
+        if after:
+            cmd += ["--after", after]
+        rows = shell_json(cmd, timeout=15)
+        if rows is None:
+            return None
+        if not rows:
+            break
+        matches.extend(r for r in rows if r.get("contractId") == contract_id)
+        if len(rows) < 100:
+            break
+        after = rows[-1].get("id")
+    if not matches:
+        return None
+    # Pick the LATEST version of this contract id (matches the same
+    # rule `escrow derive-condition-hash` uses).
+    return max(matches, key=lambda r: r.get("version", 0))
+
+
+def fetch_contract_pricing(rel_id: str, contract_id: str) -> str:
+    """`pricingModel` of the latest contract version ("" if missing)."""
+    row = fetch_contract_row(rel_id, contract_id)
+    return str(row.get("pricingModel") or "") if row else ""
+
+
+def auto_sign_contract(rel_id: str, contract_id: str):
+    """
+    Auto-sign a contract proposal.
+
+    Pricing-model guard: this template only handles `flat` contracts
+    (full-release settlement). For `usage_based` contracts the
+    on-chain `partial_release` ix needs a different digest
+    (`ARP-SOLANA-PARTIAL-RELEASE-v1.5` + `--partial-payee-amount`)
+    that this template doesn't generate — auto-signing one of those
+    here would let the buyer release the FULL lock amount via the
+    payee signature we ship in `auto_settlement_sign`. **Refuse to
+    sign so funds can't be misrouted.**
+
+    Other policy gates (price ceiling, scope match, deadline window)
+    should go here too — this template signs anything `flat`.
+    """
+    row = fetch_contract_row(rel_id, contract_id)
+    if row is None:
+        # Couldn't fetch the row — refuse rather than guess. The
+        # operator can investigate (e.g. server rejected the list)
+        # and sign manually.
+        print(
+            f"[worker] ✗ refusing to sign contract {contract_id[:20]} — "
+            "couldn't fetch the contract row from contracts --json. "
+            "Run `heyarp contracts <rel-id>` manually to investigate."
+        )
+        return
+    # Proactive idempotency: a contract that's already `active` was
+    # signed by a previous (re-delivered) event. Detecting it here by
+    # STATE is cleaner than reacting to a sign-time error — `contract
+    # sign` with no `--version` fails inside resolveTargetVersion (no
+    # PROPOSED row) with a generic CLI_ERROR that can't be told apart
+    # from a real failure. `replaced` (superseded by a counter) and
+    # `declined` are also terminal — nothing to sign.
+    state = row.get("state")
+    if state in ("active", "replaced", "declined"):
+        print(f"[worker] - contract already {state} (idempotent skip)")
+        return
+    pricing = str(row.get("pricingModel") or "")
+    if pricing != "flat":
+        print(
+            f"[worker] ✗ refusing to sign contract {contract_id[:20]} — "
+            f"pricingModel={pricing!r}; this template only handles `flat`. "
+            "Decline manually or upgrade to a template that signs "
+            "ARP-SOLANA-PARTIAL-RELEASE-v1.5 digests."
+        )
+        return
+    print(f"[worker] Auto-signing FLAT contract {contract_id[:20]}...")
+    # Pin the exact version we just read as PROPOSED. Without
+    # `--version`, `contract sign` auto-resolves the latest PROPOSED
+    # row — and if a concurrent signer flipped it to active in the
+    # gap, that auto-resolve fails with an ambiguous CLI_ERROR (no
+    # PROPOSED row) that's indistinguishable from a real failure.
+    # Pinning the version turns that race into a clean contract-state
+    # reject the handler below recognises.
+    cmd = [HEYARP, "contract", "sign", rel_id, contract_id, "--json"]
+    version = row.get("version")
+    if version is not None:
+        cmd += ["--version", str(version)]
+    r = shell(cmd, timeout=30)
+    if r["ok"]:
+        print("[worker] ✓ contract signed")
+    else:
+        # Rare race: a concurrent signer flipped the pinned version to
+        # active between our state read and our sign. The server
+        # rejects with a contract-state code; anything else is a
+        # genuine failure.
+        code = error_code(r)
+        if code in ("CONTRACT_INVALID_STATE", "DOM_INVALID_TRANSITION"):
+            print("[worker] - contract signed concurrently (race; idempotent skip)")
+        else:
+            print(f"[worker] ✗ contract sign failed: {code or r.get('stderr', '')[:200]}")
+
+
+def auto_accept_delegation(rel_id: str, delegation_id: str):
+    """
+    Auto-accept a delegation offer.
+
+    Settleability policy gate: this template auto-settles each receipt
+    with `settlement auto-sign-and-deliver`, 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 — the settle command 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 `settlement auto-sign-and-deliver "
+            "--expires-at <unix-secs>` to handle it."
+        )
+        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
+# ═══════════════════════════════════════════════════════════════
+#
+# After receipt propose, the buyer needs BOTH parties' settlement
+# signatures to release escrow on Solana. The payee (us) must
+# generate its signature and deliver it to the buyer.
+#
+# A single command collapses 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) into ONE command:
+#
+#     heyarp settlement auto-sign-and-deliver --delegation-id <id>
+#
+# The main loop below calls it directly after `receipt propose` —
+# there's nothing left to hand-orchestrate here. The command:
+#   - auto-resolves rel-id, buyer DID, condition_hash, amount,
+#     decimals, deadline, and the receipt hashes from --delegation-id
+#   - 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)
+#
+# Requires `@heyanon-arp/cli` ≥ 0.0.5.
+
+
+# ═══════════════════════════════════════════════════════════════
+# 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 `settlement auto-sign-and-deliver`
+    # 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
+    # command (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"
+            "  `settlement auto-sign-and-deliver` 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 ✓ | contract ✓ | delegation ✓")
+    print("[worker] Auto-settle:   receipt → sign → memory → 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 == "contract":
+                content = body.get("content", {})
+                if content.get("action") == "proposal":
+                    rel_id = envelope.get("relationshipId", "")
+                    contract_id = content.get("contract_id", "")
+                    print(f"\n[worker] >>> Contract proposal {contract_id[:20]}...")
+                    auto_sign_contract(rel_id, contract_id)
+
+            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 (--json output).
+                    print("[worker] Auto-proposing receipt...")
+                    receipt = shell_json([
+                        HEYARP, "receipt", "propose", sender,
+                        del_id, "--auto-hashes", "--rel-id", rel_id,
+                        "--request-id", req_id, "--verdict", "accepted",
+                        "--json",
+                    ], timeout=30)
+                    if receipt is None:
+                        print("[worker] - receipt propose failed")
+                        continue
+                    print("[worker] ✓ receipt proposed")
+
+                    # 5. Sign + deliver the payee settlement signature in
+                    #    ONE command. It resolves the buyer key,
+                    #    condition hash, amount/decimals/deadline, and the
+                    #    receipt hashes itself, signs the release digest,
+                    #    and delivers it to the buyer via a
+                    #    settlement_signature envelope. Idempotent:
+                    #    re-running after delivery is a no-op. Auto-detects
+                    #    full (flat) vs partial (usage_based) release.
+                    #
+                    #    Pass --receipt-event-hash from the propose result
+                    #    so the command targets the EXACT receipt we just
+                    #    created — required when a delegation has more than
+                    #    one proposed receipt (multiple work requests).
+                    #    --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.
+                    settle_cmd = [
+                        HEYARP, "settlement", "auto-sign-and-deliver",
+                        "--delegation-id", del_id, "--rel-id", rel_id,
+                        "--cluster-tag", CLUSTER_TAG, "--mint-pubkey", MINT_PUBKEY,
+                        "--fee-bps-at-lock", "0",
+                        "--json",
+                    ]
+                    if receipt.get("receiptEventHash"):
+                        settle_cmd += ["--receipt-event-hash", receipt["receiptEventHash"]]
+                    settle = shell_json(settle_cmd, timeout=30)
+                    if settle is not None:
+                        tag = " (idempotent)" if settle.get("idempotent") else ""
+                        print(f"[worker] ✓ settlement signed + delivered: {settle.get('purpose')}{tag}")
+                    else:
+                        print("[worker] - settlement auto-sign-and-deliver failed (see stderr)")
+
+                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, memory_delta,
+                # 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()