fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/compute/sandbox.py

@@ -0,0 +1,282 @@
+"""Resource limits and the forked job sandbox (rlimits, wall-clock kill).
+
+Separate because the sandbox state (_IN_SANDBOX_CHILD, the availability probe) is module-global and mutated in the forked child, so it must live in exactly one module.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import signal as signal_mod
+import sys
+import tempfile
+import time
+from typing import Any, Callable, Iterator, Optional
+
+import types
+
+try:
+    import resource as _resource_mod
+except ImportError:  # pragma: no cover - resource is POSIX-only
+    _resource_mod = None  # type: ignore[assignment]  # stub types the module as always present; it is absent on Windows
+resource: types.ModuleType | None = _resource_mod
+
+from .common import ComputeError
+
+class ComputeLimits:
+    """Resource bounds for compute execution."""
+
+    def __init__(
+        self,
+        max_fuel: int = 2500000000,
+        max_memory_bytes: int = 1073741824,
+        timeout_seconds: int = 60,
+        max_tokens: int = 4096,
+        max_steps: int = 25,
+    ) -> None:
+        self.max_fuel = max_fuel
+        self.max_memory_bytes = max_memory_bytes
+        self.timeout_seconds = timeout_seconds
+        self.max_tokens = max_tokens
+        self.max_steps = max_steps
+
+
+# Operator ceilings: a job request can ask for less, never more. Override with
+# FLEETMESH_COMPUTE_MAX_TIMEOUT_S / FLEETMESH_COMPUTE_MAX_MEMORY_BYTES.
+NODE_MAX_TIMEOUT_S: int = int(os.environ.get('FLEETMESH_COMPUTE_MAX_TIMEOUT_S', '300'))
+NODE_MAX_MEMORY_BYTES: int = int(os.environ.get('FLEETMESH_COMPUTE_MAX_MEMORY_BYTES', str(1 << 30)))
+_SANDBOX_KILL_GRACE_S: float = 2.0
+
+# How much of a dead child's stderr travels in the error. A panic prints a few
+# lines; a loop printing forever must not become the error message.
+_CHILD_STDERR_CAP: int = 2048
+
+# Signals that really do mean a limit was hit. Everything else - SIGSEGV,
+# SIGABRT, SIGBUS, SIGILL - is a crash in the job or the runtime, and saying
+# "CPU or memory limit exceeded" for those names a cause that has not been
+# established (audit 2026-10-07, I7). SIGKILL is ambiguous on purpose: it is
+# the OOM killer, or this node's own kill on the way out, and the message says
+# both rather than picking one.
+_LIMIT_SIGNALS: dict[int, str] = {
+    getattr(signal_mod, 'SIGXCPU', -1): 'the CPU limit was exceeded',
+    getattr(signal_mod, 'SIGKILL', -1):
+        'killed - the kernel out-of-memory killer, or this node killing it on the way out',
+}
+
+
+def _signal_name(sig: Optional[int]) -> str:
+    """'SIGABRT (6)' where the number is a signal, else just the number."""
+    if sig is None:
+        return 'unknown'
+    try:
+        return '%s (%d)' % (signal_mod.Signals(sig).name, sig)
+    except (ValueError, AttributeError):
+        return str(sig)
+
+
+def _read_child_stderr(fh: Any) -> str:
+    """The last _CHILD_STDERR_CAP bytes the child wrote, and close the file.
+
+    The tail rather than the head: a panic's reason is the last thing printed,
+    and a job that logged for a while before dying would otherwise push it out.
+    """
+    try:
+        fh.seek(0, os.SEEK_END)
+        size = fh.tell()
+        fh.seek(max(0, size - _CHILD_STDERR_CAP))
+        raw = fh.read()
+    except Exception:
+        return ''
+    finally:
+        with contextlib.suppress(Exception):
+            fh.close()
+    text = raw.decode('utf-8', 'replace') if isinstance(raw, bytes) else str(raw)
+    if len(text) >= _CHILD_STDERR_CAP:
+        text = '…' + text[-_CHILD_STDERR_CAP:]
+    return text
+
+
+def _died_message(sig: Optional[int], stderr: str) -> str:
+    """What is actually known about a child that died without answering.
+
+    Before this, every signal got "CPU or memory limit exceeded" stapled to
+    it. Observed in practice: signal 6 is SIGABRT - a wasmtime panic, with the
+    reason printed one line earlier ("cannot use Wasmtime in a forked process
+    when mach ports are configured") - and a SIGSEGV in an executor and a
+    kernel OOM kill read identically. The signal number was always there; the
+    diagnosis beside it was wrong, and it is the half an operator reads.
+    """
+    out = 'job sandbox died (signal/exit %s)' % _signal_name(sig)
+    if sig is not None and sig in _LIMIT_SIGNALS:
+        out += ': %s' % _LIMIT_SIGNALS[sig]
+    if stderr:
+        out += '; it said: %s' % stderr.strip()
+    return out
+# Address space the wasm runtime needs around a job (sigaltstack, JIT pages,
+# guard regions), granted on top of the job's own ceiling; see sandbox_limits.
+_RUNTIME_SLACK_BYTES: int = 64 << 20
+
+# True only inside a forked job child; rlimits are never touched in the node process.
+_IN_SANDBOX_CHILD: bool = False
+
+
+def clamp_limits(limits: ComputeLimits) -> ComputeLimits:
+    """Clamp requester-supplied limits to the node operator's ceilings."""
+    def _c(v: int, cap: int) -> int:
+        v = int(v) if v else cap
+        return max(1, min(v, cap))
+    return ComputeLimits(
+        max_fuel=limits.max_fuel,
+        max_memory_bytes=_c(limits.max_memory_bytes, NODE_MAX_MEMORY_BYTES),
+        timeout_seconds=_c(limits.timeout_seconds, NODE_MAX_TIMEOUT_S),
+        max_tokens=limits.max_tokens,
+        max_steps=limits.max_steps,
+    )
+
+
+def _apply_rlimits(limits: ComputeLimits) -> None:
+    """Set process-wide rlimits. Only ever called in a disposable job child."""
+    if resource is None:
+        return
+    if limits.timeout_seconds and hasattr(resource, 'RLIMIT_CPU'):
+        try:
+            used = int(time.process_time())  # child inherits parent's CPU accounting
+            soft, hard = resource.getrlimit(resource.RLIMIT_CPU)
+            want = used + int(limits.timeout_seconds) + 1
+            if hard != resource.RLIM_INFINITY:
+                want = min(want, hard)
+            resource.setrlimit(resource.RLIMIT_CPU, (want, hard))
+        except (ValueError, OSError):
+            pass
+    if limits.max_memory_bytes and hasattr(resource, 'RLIMIT_AS'):
+        try:
+            soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+            # RLIMIT_AS counts the whole address space, and a child forked
+            # from a running node inherits the node's (thread stacks, sqlite
+            # maps, loaded libraries - often most of a gigabyte). An absolute
+            # cap left a job almost nothing; grant the job its bytes on top
+            # of what it was born with.
+            # The runtime itself also needs room the job did not ask for:
+            # wasmtime allocates a sigaltstack per thread, JIT code pages
+            # and guard regions before the module runs a single
+            # instruction. Without this slack a small ceiling aborted the
+            # child with "failed to allocate memory for sigaltstack" and
+            # the job died at the rlimit instead of trapping cleanly at the
+            # store limit - and whether it did depended on how much address
+            # space the parent happened to hold at fork, which made the
+            # outcome flake with unrelated code. The wasm store limit (set
+            # from max_memory_bytes by the executor) is what bounds the
+            # module; this rlimit only backstops the runtime around it.
+            want = _current_address_space() + int(limits.max_memory_bytes) + _RUNTIME_SLACK_BYTES
+            if hard != resource.RLIM_INFINITY:
+                want = min(want, hard)
+            resource.setrlimit(resource.RLIMIT_AS, (want, hard))
+        except (ValueError, OSError):
+            pass
+
+
+def _current_address_space() -> int:
+    try:
+        with open('/proc/self/statm') as f:
+            return int(f.read().split()[0]) * os.sysconf('SC_PAGE_SIZE')
+    except (OSError, ValueError, IndexError):
+        return 0
+
+
+@contextlib.contextmanager
+def sandbox_limits(limits: Optional[ComputeLimits] = None) -> Iterator[None]:
+    """Apply rlimits for the duration of the block -- inside a job child only.
+
+    rlimits are process-wide: setting them in the node process let one job's
+    RLIMIT_CPU (measured against the node's total CPU time) SIGXCPU-kill the
+    whole node, and RLIMIT_AS cap every thread. Outside a sandbox child this
+    is therefore a no-op; use run_sandboxed() for real isolation.
+    """
+    if resource is None or limits is None or not _IN_SANDBOX_CHILD:
+        yield
+        return
+    _apply_rlimits(limits)
+    yield
+
+
+def _sandbox_available() -> bool:
+    import multiprocessing
+    return resource is not None and 'fork' in multiprocessing.get_all_start_methods()
+
+
+def run_sandboxed(fn: Callable[[], Any], limits: ComputeLimits, *, allow_unsandboxed: bool = False) -> Any:
+    """Run fn() in a forked child with CPU/memory rlimits and a wall-clock kill.
+
+    Limit breaches kill only the child and surface as ComputeError. The return
+    value must be picklable. Where fork/rlimits are unavailable the job is
+    refused unless ``allow_unsandboxed`` is set, in which case it runs
+    in-process with no resource limits: an untrusted module must never get
+    that silently, because the operator would believe it was contained.
+    """
+    limits = clamp_limits(limits)
+    if not _sandbox_available():
+        if not allow_unsandboxed:
+            raise ComputeError('sandbox unavailable on this host (no fork/rlimits); '
+                               'refusing to run the job in-process without allow_unsandboxed=True')
+        return fn()
+    import multiprocessing
+    ctx = multiprocessing.get_context('fork')
+    parent_conn, child_conn = ctx.Pipe(duplex=False)
+
+    # The child's stderr goes to a file so that a native crash - which sends
+    # nothing down the pipe, because it never reaches Python again - still
+    # leaves its reason somewhere the parent can read. Nothing is swallowed:
+    # on success the parent copies whatever was written back to the real
+    # stderr, so a job's own warnings still reach the journal.
+    err_file = tempfile.TemporaryFile()
+
+    def _child() -> None:
+        global _IN_SANDBOX_CHILD
+        _IN_SANDBOX_CHILD = True
+        try:
+            os.dup2(err_file.fileno(), 2)
+        except OSError:
+            pass            # no stderr to redirect: carry on, the pipe still works
+        try:
+            _apply_rlimits(limits)
+            child_conn.send(('ok', fn()))
+        except MemoryError:
+            child_conn.send(('err', 'job exceeded memory limit (%d bytes)' % limits.max_memory_bytes))
+        except BaseException as e:  # noqa: BLE001 - report anything to the parent
+            try:
+                child_conn.send(('err', '%s: %s' % (type(e).__name__, e)))
+            except Exception:
+                pass
+        finally:
+            child_conn.close()
+
+    proc = ctx.Process(target=_child, daemon=True)
+    proc.start()
+    child_conn.close()
+    try:
+        deadline = limits.timeout_seconds + _SANDBOX_KILL_GRACE_S
+        if parent_conn.poll(deadline):
+            try:
+                status, value = parent_conn.recv()
+            except EOFError:
+                status, value = 'err', None
+        else:
+            status, value = 'timeout', None
+    finally:
+        if proc.is_alive():
+            proc.kill()
+        proc.join(5)
+        parent_conn.close()
+    said = _read_child_stderr(err_file)
+    if status == 'ok':
+        if said:
+            # The job ran and had something to say. It is not an error, so it
+            # goes where it would have gone without the redirection.
+            with contextlib.suppress(Exception):
+                sys.stderr.write(said)
+        return value
+    if status == 'timeout':
+        raise ComputeError('job exceeded wall-clock limit (%ss)' % limits.timeout_seconds)
+    if value is None:
+        sig = -proc.exitcode if proc.exitcode and proc.exitcode < 0 else proc.exitcode
+        raise ComputeError(_died_message(sig, said))
+    raise ComputeError('job failed in sandbox: %s' % value)

node/planes/services/compute/types.py

@@ -0,0 +1,84 @@
+"""Types and records for the Compute compartment."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, TypedDict
+
+
+class JobRunResult(TypedDict, total=False):
+    """What run_job hands back to receipt builders and the wire layer.
+
+    result_cid is absent on the custom_runner path (no blob store there); all
+    other keys are always present.
+    """
+    result_hash: str
+    result_cid: Optional[str]
+    raw_output: bytes
+    fuel_used: int
+    engine: str
+    wasi_profile_digest: str
+    counters: Mapping[str, int | float]
+    verification_mode: str
+
+
+class ChatMessage(TypedDict, total=False):
+    """Chat completion message."""
+    role: str
+    content: str
+    name: Optional[str]
+
+
+class OpenAIChatRequest(TypedDict, total=False):
+    """Normalized OpenAI chat completions payload."""
+    model: str
+    messages: list[ChatMessage]
+    max_tokens: int
+    temperature: float
+    top_p: float
+    stream: bool
+    seed: Optional[int]
+    response_format: Optional[Mapping[str, Any]]
+    guided_regex: Optional[str]
+
+
+class BacalhauJobSummary(TypedDict, total=False):
+    """Summary of a Bacalhau job specification."""
+    status: str
+    engine: str
+    image: str
+    entrypoint: str | list[str]
+    parameters: list[str]
+    mounted_paths: list[str]
+    outputs: list[str]
+    bytes_processed: int
+    results: Optional[Mapping[str, Any]]
+
+
+class AgentTraceStep(TypedDict, total=False):
+    """Step in an autonomous agent execution trace."""
+    step: int
+    thought: str
+    action: str
+    observation: str
+    output: Optional[str | Mapping[str, str | int | float | bool]]
+    sub_ask_id: Optional[str]
+
+
+class AgentSubAsk(TypedDict, total=False):
+    """Sub-delegation ask in an agent orchestration tree."""
+    ask_id: str
+    task: str
+    budget_msat: int
+    status: str
+
+
+class ComputeReceiptPayload(TypedDict, total=False):
+    """Payload of a decrypted compute receipt (kind 30811)."""
+    result_hash: str
+    result_cid: Optional[str]
+    raw_output: bytes | str
+    fuel_used: int
+    engine: str
+    wasi_profile_digest: str
+    counters: Mapping[str, int | float]
+    verification_mode: str
+    blinding: Optional[str]

node/planes/services/compute_wire/__init__.py

@@ -0,0 +1,58 @@
+"""compute/1.0: Wire protocol, DIDComm transport lifecycle, accountable settlement, and dispute automation.
+
+Implements the complete compute market wire lifecycle:
+- DIDComm compute/1.0 message types (quote, accept, sealed, settled, refute)
+- Cryptographic sealing under Lightning payment preimage k (NIP-44 v2 / ChaCha20+HMAC)
+- Accountable delivery verification and fault classification (sealed-key-does-not-open,
+  result-hash-mismatch-after-decrypt, rerun-divergence, proof-invalid)
+- Automated bilateral negotiation state machine (buyer and seller sessions)
+- Conformance report generation (Kind 30802) citing signed sealed evidence under fleetmesh_core/reports.py
+"""
+from __future__ import annotations
+
+
+from .messages import (
+    PIURI,
+    PIURI_V11,
+    QUOTE_TYPE,
+    ACCEPT_TYPE,
+    SEALED_TYPE,
+    SETTLED_TYPE,
+    REFUTE_TYPE,
+    STREAM_TYPE,
+    PROGRESS_TYPE,
+    CANCEL_TYPE,
+    MESSAGES,
+    ComputeWireError,
+    make_quote,
+    make_accept,
+    make_sealed,
+    make_settled,
+    make_refute,
+    make_stream_chunk,
+    make_progress,
+    make_cancel,
+)
+from .sealing import seal_result, open_sealed, encrypt_stream_frame, decrypt_stream_frame
+from .verify import vk_is_trusted, evaluate_job_evidence, build_compute_dispute_report
+from .types import (
+    ComputeDisputeRecord,
+    ComputeSessionSummary,
+    ComputeWireStateReport,
+    EvidenceDetail,
+    SealedResult,
+)
+from .session import ComputeSession
+from .compartment import ComputeWire
+
+__all__ = [
+    'PIURI', 'PIURI_V11', 'QUOTE_TYPE', 'ACCEPT_TYPE', 'SEALED_TYPE', 'SETTLED_TYPE',
+    'REFUTE_TYPE', 'STREAM_TYPE', 'PROGRESS_TYPE', 'CANCEL_TYPE', 'MESSAGES',
+    'ComputeWireError', 'make_quote', 'make_accept', 'make_sealed', 'make_settled',
+    'make_refute', 'make_stream_chunk', 'make_progress', 'make_cancel',
+    'seal_result', 'open_sealed', 'encrypt_stream_frame', 'decrypt_stream_frame',
+    'vk_is_trusted', 'evaluate_job_evidence', 'build_compute_dispute_report',
+    'ComputeSession', 'ComputeWire',
+    'ComputeDisputeRecord', 'ComputeSessionSummary', 'ComputeWireStateReport',
+    'EvidenceDetail', 'SealedResult',
+]

node/planes/services/compute_wire/compartment.py

@@ -0,0 +1,256 @@
+"""ComputeWire: the subsystem that routes compute/1.0 envelopes to ComputeSession.
+
+Separate so the subsystem wiring stays a thin adapter over the session and message modules.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from node.config import ComputeConfig
+from node.compartment import Command, Handler, Need, Outbound, WireProtocol
+from node import channels as ch_mod
+from node import metrics as mx_mod
+from node.compartment import stores as st
+from node.planes.services.compute import executors as compute_executors
+from .messages import PIURI, PIURI_V11
+from .session import ComputeSession
+
+
+from .types import (
+    ComputeDisputeRecord,
+    ComputeSessionSummary,
+    ComputeWireStateReport,
+)
+
+
+# -------------------------------------------------------------------------
+# Compute Wire Compartment (Transport Compartment)
+# -------------------------------------------------------------------------
+class ComputeWire(WireProtocol):
+    """The compute/1.0 and compute/1.1 wire transport compartment for meshnode."""
+
+    optional: bool = True
+    enabled_by: Optional[str] = 'compute'
+    name: str = 'compute_wire'
+    reads: tuple[str, ...] = ('compute', 'relays', 'transport')
+    config_cls = ComputeConfig
+    piuris: tuple[str, ...] = (PIURI, PIURI_V11)
+    OUTBOUND = (
+        Outbound('quote', reply=('accept', 'cancel'), doc='quote price and terms for compute task'),
+        Outbound('accept', reply=('sealed', 'cancel'), doc='accept quote and escrow payment'),
+        Outbound('sealed', reply=('settled', 'refute'), doc='deliver encrypted execution payload'),
+        Outbound('settled', doc='reveal payment preimage upon verified settlement'),
+        Outbound('refute', doc='refute execution proof or result divergence'),
+        Outbound('stream', doc='stream output tokens or chunk deltas'),
+        Outbound('progress', doc='stream execution progress heartbeat'),
+        Outbound('cancel', doc='cancel compute task execution'),
+    )
+    COMMANDS = (
+        Command(
+            key='sessions',
+            name='Compute Sessions',
+            description='list active bilateral compute sessions',
+            tags=('compute', 'sessions'),
+            permission='compute_wire/sessions',
+            run='list_sessions',
+            reply='dict',
+        ),
+        Command(
+            key='disputes',
+            name='Compute Disputes',
+            description='list compute refutations and dispute reports filed',
+            tags=('compute', 'disputes'),
+            permission='compute_wire/disputes',
+            run='list_disputes',
+            reply='list',
+        ),
+    )
+
+    HANDLERS = (
+        Handler('quote', run='handle_quote', doc='receive compute quotation'),
+        Handler('accept', run='handle_accept', doc='receive compute job acceptance'),
+        Handler('sealed', run='handle_sealed', doc='receive sealed compute payload'),
+        Handler('settled', run='handle_settled', doc='receive compute settlement preimage'),
+        Handler('refute', run='handle_refute', writes=('disputes',), doc='receive compute refutation dispute'),
+        Handler('stream', run='handle_stream', doc='receive real-time streaming output chunk'),
+        Handler('progress', run='handle_progress', doc='receive long-running progress heartbeat'),
+        Handler('cancel', run='handle_cancel', doc='receive compute job cancellation'),
+    )
+
+    # What it keeps. Each refute a peer sends is kept whole, and any peer
+    # can send one; this was a list that grew by one per refute for the life
+    # of the process. The newest DISPUTES_KEPT now, and `disputes_filed`
+    # still counts every one (the ring's inserts).
+    DISPUTES_KEPT = 256
+    STORES = (
+        st.Store(key='disputes', description='refutes received, as {peer, refute}, newest last',
+                 kind=st.RING, shape=dict, bound=DISPUTES_KEPT),
+    )
+    CHANNELS = (
+        ch_mod.Channel('refute_received', 'A compute refutation dispute was received from a peer',
+                       level=ch_mod.TROUBLE, say='compute dispute from {peer} for receipt {receipt}',
+                       tags=('compute', 'wire', 'dispute')),
+        ch_mod.Channel('quote_received', 'A compute quotation was received from an executor peer',
+                       level=ch_mod.NOTE, say='compute quote from {peer} price {price} msat',
+                       tags=('compute', 'wire')),
+    )
+    METRICS = (
+        mx_mod.Metric(name='compute_wire_disputes', description='Compute disputes and refutations received.',
+                      kind=mx_mod.COUNTER, counts='refute_received', tags=('compute', 'wire', 'disputes')),
+        mx_mod.Metric(name='compute_wire_quotes', description='Compute quotes received from peers.',
+                      kind=mx_mod.COUNTER, counts='quote_received', tags=('compute', 'wire', 'quotes')),
+    )
+
+    NEEDS = (
+        Need('ks', 'ks'),
+    )
+
+    def __init__(self, node: Any = None, ks: Any = None) -> None:
+        super().__init__(node)
+        self.ks: Any = ks if ks is not None else getattr(node, 'ks', None)
+        self.sessions: dict[str, ComputeSession] = {}  # not a store: never written - nothing constructs a ComputeSession yet; the sessions command reads it
+        self.disputes: st.Ring[ComputeDisputeRecord]   # built and bound by the base (see STORES)
+        self.registry: compute_executors.ExecutorRegistry = compute_executors.DEFAULT_REGISTRY
+
+    def pinned_vk_digests(self) -> list[str]:
+        """Operator-pinned Groth16 verification-key digests (cfg compute.zk_pinned_vks)."""
+        return list(ComputeConfig.from_dict(self.config('compute') or {}).zk_pinned_vks)
+
+    def state(self) -> ComputeWireStateReport:
+        return {
+            'active_sessions': len(self.sessions),
+            'disputes_filed': self.disputes.inserts,
+            'refusals': self.refusals.total(),
+        }
+
+    def list_sessions(self) -> dict[str, ComputeSessionSummary]:
+        return {
+            sid: {'role': s.role, 'peer': s.peer_pk, 'state': s.state}
+            for sid, s in self.sessions.items()
+        }
+
+    def list_disputes(self) -> list[ComputeDisputeRecord]:
+        return list(self.disputes)
+
+    def _my_sk(self) -> str:
+        ks = self.ks
+        if ks is not None and getattr(ks, 'node_sk', None):
+            return str(ks.node_sk)
+        return '11' * 32
+
+    def _peer_pk(self, sender: str) -> str:
+        s = str(sender or '').strip()
+        if s.startswith('did:nostr:'):
+            s = s[len('did:nostr:'):]
+        if len(s) == 64:
+            return s.lower()
+        return '22' * 32
+
+    def open_buyer_session(
+        self,
+        ask_id: str,
+        peer_pk: str,
+        job_payload: Optional[Mapping[str, Any]] = None,
+    ) -> ComputeSession:
+        sess = ComputeSession(
+            role='buyer',
+            my_sk=self._my_sk(),
+            peer_pk=self._peer_pk(peer_pk),
+            ask_id=ask_id,
+            job_payload=job_payload,
+        )
+        self.sessions[ask_id] = sess
+        return sess
+
+    def open_seller_session(
+        self,
+        ask_id: str,
+        peer_pk: str,
+    ) -> ComputeSession:
+        sess = ComputeSession(
+            role='seller',
+            my_sk=self._my_sk(),
+            peer_pk=self._peer_pk(peer_pk),
+            ask_id=ask_id,
+        )
+        self.sessions[ask_id] = sess
+        return sess
+
+    def handle_quote(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body') or {}
+        price = body.get('price_msat', 0)
+        thid = str(msg.get('thid') or body.get('ask') or msg.get('id') or '')
+        if thid:
+            sess = self.sessions.get(thid)
+            if sess is None:
+                sess = self.open_buyer_session(thid, sender)
+            sess.quote_msg = dict(msg)
+            sess.payment_hash = body.get('payment_hash')
+            sess.state = 'QUOTED'
+        self.say('quote_received', peer=sender, price=price)
+        return ('quote_received', sender, price)
+
+    def handle_accept(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        thid = msg.get('thid') or msg.get('id')
+        if thid:
+            sid = str(thid)
+            sess = self.sessions.get(sid)
+            if sess is None:
+                sess = self.open_seller_session(sid, sender)
+            sess.accept_msg = dict(msg)
+            sess.state = 'ACCEPTED'
+        return ('accept_received', sender, thid)
+
+    def handle_sealed(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        body = msg.get('body') or {}
+        thid = str(msg.get('thid') or msg.get('id') or '')
+        if thid:
+            sess = self.sessions.get(thid)
+            if sess is None:
+                sess = self.open_buyer_session(thid, sender)
+            sess.sealed_msg = dict(msg)
+            sess.payment_hash = body.get('payment_hash')
+            sess.result_hash = body.get('result')
+            sess.state = 'SEALED'
+        return ('sealed_received', sender, body.get('payment_hash'))
+
+    def handle_settled(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        thid = msg.get('thid') or msg.get('id')
+        if thid and str(thid) in self.sessions:
+            self.sessions[str(thid)].settled_msg = dict(msg)
+            self.sessions[str(thid)].state = 'SETTLED'
+        return ('settled_received', sender, thid)
+
+    def handle_refute(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        self.disputes.append({'peer': sender, 'refute': msg})
+        receipt = (msg.get('body') or {}).get('job_receipt', '')
+        thid = msg.get('thid') or msg.get('id')
+        if thid and str(thid) in self.sessions:
+            self.sessions[str(thid)].state = 'REFUTED'
+        self.say('refute_received', peer=sender, receipt=str(receipt)[:16])
+        return ('refute_received', sender, receipt)
+
+    def handle_stream(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        thid = msg.get('thid') or msg.get('id')
+        return ('stream_received', sender, thid, (msg.get('body') or {}).get('seq'))
+
+    def handle_progress(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        thid = msg.get('thid') or msg.get('id')
+        if thid and str(thid) in self.sessions:
+            self.sessions[str(thid)].progress_history.append(dict(msg))
+        return ('progress_received', sender, thid, (msg.get('body') or {}).get('progress'))
+
+    def handle_cancel(self, inbound: Any, sender: str) -> tuple[Any, ...]:
+        msg = getattr(inbound, 'message', inbound)
+        thid = msg.get('thid') or msg.get('id')
+        if thid and str(thid) in self.sessions:
+            self.sessions[str(thid)].state = 'CANCELLED'
+        return ('cancel_received', sender, thid, (msg.get('body') or {}).get('reason'))
+