@heyanon-arp/cli 0.0.6 → 0.0.8

package/examples/worker-template.py

@@ -1,894 +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 → 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()