dhp-protocol 1.3.0__py3-none-any.whl

dhp/__init__.py

@@ -0,0 +1,143 @@
+"""DHP — Durable Handoff Protocol.
+
+Agent work that survives worker death. Dispatch a handoff, claim it
+from any worker, checkpoint as you go; if the worker dies, a
+supervisor orphans the handoff and a standby recovers from the last
+checkpoint. No lost results, no crossed inputs, no runner lock-in.
+
+Quick start::
+
+    import dhp
+
+    # one-time: create a store + supervisor for your app
+    store = dhp.Store("/var/lib/myapp/dhp")
+
+    # dispatch durable work
+    hid = dhp.dispatch(
+        store,
+        task_kind="prime.census",
+        inputs={"lo": 0, "hi": 16000, "chunk": 100},
+        output_schema={...},
+    )
+
+    # in the worker (any process, any host with the transport log):
+    ctx = dhp.claim(store, hid, worker_id="w1")
+    state = dhp.last_checkpoint(store, hid) or {"next_n": 0}
+    for ...:
+        ... do a chunk of work ...
+        ctx.checkpoint(state); ctx.heartbeat()
+    ctx.complete(result)
+
+    # if the worker dies: supervisor orphans, standby recovers
+    ctx2 = dhp.recover(store, hid, worker_id="w2")  # resumes at last cp
+"""
+from .envelope import build as _build_envelope
+from .store import Store
+from .backend import StoreBackend
+from .runner3 import Runner3, TaskContext
+from .supervisor3 import Supervisor3
+from .config import DHPConfig, DEFAULT
+from .transport import (
+    ship_envelope as transport_ship_envelope,
+    ship_checkpoint as transport_ship_checkpoint,
+    ingest_log as transport_ingest,
+)
+from .net import TransportServer, NetShipper
+from . import validate as _validate
+
+__version__ = "1.3.0"
+__all__ = [
+    "Store", "StoreBackend", "Runner3", "TaskContext", "Supervisor3",
+    "TransportServer", "NetShipper",
+    "dispatch", "claim", "recover", "last_checkpoint", "status",
+    "transport_ship_envelope", "transport_ship_checkpoint",
+    "transport_ingest",
+    "__version__",
+]
+
+_DEFAULT_BUDGET = {
+    "max_steps": 10000,
+    "max_spend_usd": 500.0,
+    "max_wallclock_s": 5400.0,
+    "max_attempts": 5,
+}
+
+_DEFAULT_MAX_STALL_RETRIES = 2
+
+
+def _runner(store: StoreBackend, worker_id: str = "api",
+            cfg: DHPConfig = DEFAULT) -> Runner3:
+    return Runner3(store.root, runner_id=worker_id, store=store, cfg=cfg)
+
+
+def dispatch(store: StoreBackend, task_kind: str, inputs: dict,
+             output_schema: dict, budget: dict | None = None,
+             capabilities: dict | None = None,
+             max_stall_retries: int = _DEFAULT_MAX_STALL_RETRIES,
+             created_by: str = "dhp-api",
+             cfg: DHPConfig = DEFAULT) -> str:
+    """Create a durable handoff. Returns the handoff id."""
+    _validate.check_inputs(inputs, cfg)
+    env = _build_envelope(
+        task_kind=task_kind,
+        inputs={"inline": inputs},
+        output_schema=output_schema,
+        budget={**_DEFAULT_BUDGET, **(budget or {})},
+        max_stall_retries=max_stall_retries,
+        capabilities=capabilities,
+        created_by=created_by)
+    return _runner(store, cfg=cfg).dispatch(env)
+
+
+def claim(store: StoreBackend, hid: str, worker_id: str,
+          cfg: DHPConfig = DEFAULT) -> TaskContext:
+    """Claim a pending handoff for a worker. Returns a TaskContext
+    with .checkpoint(state), .heartbeat(), .complete(result)."""
+    return _runner(store, worker_id, cfg).claim(_validate.check_hid(hid))
+
+
+def recover(store: StoreBackend, hid: str, worker_id: str,
+            cfg: DHPConfig = DEFAULT) -> TaskContext:
+    """Recover an orphaned handoff. Resumes from the last checkpoint."""
+    return _runner(store, worker_id, cfg).recover(_validate.check_hid(hid))
+
+
+def last_checkpoint(store: Store, hid: str):
+    """Return the last checkpointed state, or None."""
+    return _runner(store).last_checkpoint(_validate.check_hid(hid))
+
+
+def status(store: StoreBackend, hid: str) -> dict:
+    """Return a summary: status, checkpoints, owner, result if done."""
+    hid = _validate.check_hid(hid)
+    r = _runner(store)
+    env = r._load(hid)
+    ex = env["execution"]
+    own = store.get_ownership(hid)
+    out = {
+        "handoff_id": hid,
+        "status": ex["status"],
+        "checkpoints": len(ex["checkpoints"]),
+        "attempt": ex.get("attempt", 0),
+        "owner": own["holder"] if own else None,
+        "effects": store.effect_count(hid),
+        "approvals": store.approvals_for(hid),
+        "steps": ex.get("steps", 0),
+        "spend_usd": ex.get("spend_usd", 0.0),
+    }
+    if ex["status"] == "completed":
+        out["result"] = env["delivery"]["result"]
+    if ex.get("error"):
+        out["error"] = ex["error"]
+    return out
+
+
+def approve(store: StoreBackend, approval_id: str) -> bool:
+    """Approve a pending approval request (human / policy engine).
+    Returns True if the decision was recorded."""
+    return store.decide_approval(approval_id, True)
+
+
+def deny(store: StoreBackend, approval_id: str) -> bool:
+    """Deny a pending approval request. Returns True if recorded."""
+    return store.decide_approval(approval_id, False)

dhp/a2a_bridge.py

@@ -0,0 +1,189 @@
+"""DHP ↔ A2A bridge: durable execution under the A2A task lifecycle.
+
+The A2A gap (from protocol_gaps.md): "A planner may mark a subtask
+failed because its deadline expired while the remote agent later posts
+a completed artifact… A2A exposes state. It does not provide consensus
+or global transaction semantics." When the remote worker dies mid-task,
+stock A2A leaves the task hanging in WORKING — the work is lost.
+
+The bridge: the A2A Task ID is the stable identity; DHP handoffs are
+the execution attempts underneath. Worker death becomes a transient
+DHP-internal event (orphan → recover) invisible at the A2A layer.
+
+Lifecycle mapping:
+  DHP pending/running/orphaned → A2A WORKING  (orphaned is transient:
+      a standby is coming; stock A2A would hang here forever)
+  DHP completed               → A2A COMPLETED (+ Artifact from result)
+  DHP failed (DLQ)            → A2A FAILED
+
+Uses the real a2a-sdk types (Task/TaskStatus/Artifact). Transport is
+in-process for the prototype; the A2A JSON-RPC/HTTP layer is orthogonal
+to the durability question.
+"""
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+from a2a.types import (
+    Artifact,
+    Message,
+    Part,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+)
+
+from . import envelope as E
+from .runner3 import Runner3
+from .supervisor3 import Supervisor3
+
+
+def _text_part(text: str) -> Part:
+    return Part(text=text)
+
+
+def _now_ts():
+    from google.protobuf.timestamp_pb2 import Timestamp
+    ts = Timestamp()
+    ts.GetCurrentTime()
+    return ts
+
+
+class DHPBridge:
+    """Binds A2A tasks to DHP handoffs. One bridge per host/store."""
+
+    def __init__(self, root: str, bridge_id: Optional[str] = None):
+        self.runner = Runner3(root, runner_id=bridge_id or "bridge")
+        self.supervisor = Supervisor3(
+            root, supervisor_id=(bridge_id or "bridge") + "-sup")
+        self.tasks: Dict[str, Task] = {}          # a2a_task_id -> Task
+        self.task_handoff: Dict[str, str] = {}    # a2a_task_id -> dhp hid
+        self.handoff_task: Dict[str, str] = {}    # dhp hid -> a2a_task_id
+        self._rebuild_mapping()
+
+    def _rebuild_mapping(self) -> None:
+        """Recover the A2A<->DHP binding from durable envelope provenance.
+        A fresh bridge instance (new process, after a crash) rebuilds
+        everything from the store — no in-memory state is load-bearing."""
+        for hid in self.runner.store.all_hids():
+            try:
+                env = self.runner._load(hid)
+            except Exception:
+                continue
+            tid = env.get("provenance", {}).get("a2a_task_id")
+            if tid:
+                self.task_handoff[tid] = hid
+                self.handoff_task[hid] = tid
+                if tid not in self.tasks:
+                    # rehydrate a Task shell; _refresh_task fills status
+                    task = Task(id=tid,
+                                context_id=env["provenance"].get("trace_id", ""),
+                                status=TaskStatus(
+                                    state=TaskState.TASK_STATE_SUBMITTED,
+                                    timestamp=_now_ts()))
+                    self.tasks[tid] = task
+
+    # ---- A2A-facing ----
+    def submit_task(self, message_text: str,
+                    task_kind: str = "prime.census",
+                    inputs: Optional[Dict[str, Any]] = None,
+                    output_schema: Optional[Dict[str, Any]] = None,
+                    context_id: Optional[str] = None) -> Task:
+        """Client submits work. Returns the A2A Task (SUBMITTED)."""
+        task_id = f"task-{uuid.uuid4().hex[:12]}"
+        task = Task(
+            id=task_id,
+            context_id=context_id or f"ctx-{uuid.uuid4().hex[:8]}",
+            status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED,
+                              timestamp=_now_ts()),
+        )
+        # Wrap in a DHP handoff: the durable execution underneath.
+        schema = output_schema or {
+            "type": "object",
+            "properties": {
+                "lo": {"type": "integer"}, "hi": {"type": "integer"},
+                "prime_count": {"type": "integer"},
+                "prime_sum": {"type": "integer"},
+                "chunks_done": {"type": "integer"}},
+            "required": ["lo", "hi", "prime_count", "prime_sum",
+                         "chunks_done"]}
+        env = E.build(
+            task_kind=task_kind,
+            inputs={"inline": inputs or {}},
+            output_schema=schema,
+            budget={"max_steps": 2000, "max_spend_usd": 500.0,
+                    "max_wallclock_s": 5400.0, "max_attempts": 5},
+            created_by=f"a2a-bridge:{task_id}")
+        # record the A2A binding in the envelope metadata
+        hid = self.runner.dispatch(env)
+        self.tasks[task_id] = task
+        self.task_handoff[task_id] = hid
+        self.handoff_task[hid] = task_id
+        # store the binding durably in the envelope
+        e2 = self.runner._load(hid)
+        e2["provenance"]["a2a_task_id"] = task_id
+        self.runner._save(e2)
+        self._refresh_task(task_id)
+        return task
+
+    def get_task(self, task_id: str) -> Task:
+        """Client polls. Always reflects current DHP state."""
+        self._refresh_task(task_id)
+        return self.tasks[task_id]
+
+    def _refresh_task(self, task_id: str) -> None:
+        task = self.tasks[task_id]
+        hid = self.task_handoff[task_id]
+        env = self.runner._load(hid)
+        st = env["execution"]["status"]
+        if st == "completed":
+            result = env["delivery"]["result"]
+            artifact = Artifact(
+                artifact_id=f"artifact-{hid[:12]}",
+                name="result",
+                description="DHP handoff result",
+                parts=[_text_part(json.dumps(result))],
+            )
+            task.status.state = TaskState.TASK_STATE_COMPLETED
+            task.status.timestamp.CopyFrom(_now_ts())
+            # avoid duplicate artifacts on repeated refresh
+            if not any(a.artifact_id == artifact.artifact_id
+                       for a in task.artifacts):
+                task.artifacts.append(artifact)
+        elif st == "failed":
+            task.status.state = TaskState.TASK_STATE_FAILED
+            task.status.timestamp.CopyFrom(_now_ts())
+            task.status.message.CopyFrom(Message(
+                message_id=f"msg-{uuid.uuid4().hex[:8]}",
+                role=Role.ROLE_AGENT,
+                parts=[_text_part(
+                    env["execution"].get("error", "handoff failed"))]))
+        else:
+            # pending / running / orphaned / suspended -> WORKING.
+            # Orphaned is the key: stock A2A would hang here; DHP is
+            # already reassigning underneath.
+            task.status.state = TaskState.TASK_STATE_WORKING
+            task.status.timestamp.CopyFrom(_now_ts())
+
+    # ---- worker-facing (what agents B, C, ... call) ----
+    def claim_for_task(self, task_id: str, worker_id: str):
+        hid = self.task_handoff[task_id]
+        r = Runner3(self.runner.store.root, runner_id=worker_id,
+                    store=self.runner.store)
+        return r.claim(hid), hid
+
+    def recover_for_task(self, task_id: str, worker_id: str):
+        hid = self.task_handoff[task_id]
+        r = Runner3(self.runner.store.root, runner_id=worker_id,
+                    store=self.runner.store)
+        return r.recover(hid), hid
+
+    def supervisor_scan(self):
+        return self.supervisor.scan()
+
+    def task_state(self, task_id: str) -> str:
+        return TaskState.Name(self.get_task(task_id).status.state)

dhp/backend.py

@@ -0,0 +1,88 @@
+"""DHP storage backend interface.
+
+The durability substrate is pluggable. ``SQLiteStore`` (dhp.store.Store)
+is the default: zero-dependency, crash-safe, single-writer. For
+multi-writer / multi-host deployments, implement ``StoreBackend``
+against Postgres (advisory locks + FOR UPDATE SKIP LOCKED give you the
+same CAS semantics) or any store that can provide:
+
+- atomic compare-and-set on (holder, fence)
+- monotonic fence increments
+- ordered, deduplicated checkpoint log
+
+The protocol logic (runner, supervisor, transport) only talks to this
+interface — never to SQL directly.
+"""
+from __future__ import annotations
+
+import abc
+from typing import Any, Dict, List, Optional
+
+
+class StoreBackend(abc.ABC):
+    """Durability substrate for DHP."""
+
+    # -- handoffs --
+    @abc.abstractmethod
+    def create_handoff(self, hid: str, envelope: Dict[str, Any]) -> None: ...
+
+    @abc.abstractmethod
+    def get_envelope(self, hid: str) -> Dict[str, Any]: ...
+
+    @abc.abstractmethod
+    def save_envelope(self, hid: str, envelope: Dict[str, Any]) -> None: ...
+
+    @abc.abstractmethod
+    def all_hids(self) -> List[str]: ...
+
+    # -- checkpoints --
+    @abc.abstractmethod
+    def add_checkpoint(self, hid: str, state: Dict[str, Any]) -> int: ...
+
+    @abc.abstractmethod
+    def last_checkpoint_state(self, hid: str) -> Optional[Dict[str, Any]]: ...
+
+    @abc.abstractmethod
+    def checkpoint_count(self, hid: str) -> int: ...
+
+    @abc.abstractmethod
+    def get_checkpoints(self, hid: str) -> List[Dict[str, Any]]: ...
+
+    @abc.abstractmethod
+    def import_checkpoints(self, hid: str,
+                           items: List[Dict[str, Any]]) -> int: ...
+
+    # -- ownership / leases / fencing --
+    @abc.abstractmethod
+    def acquire_ownership(self, hid: str, holder: str,
+                          lease_s: float) -> int: ...
+
+    @abc.abstractmethod
+    def get_ownership(self, hid: str) -> Optional[Dict[str, Any]]: ...
+
+    @abc.abstractmethod
+    def refresh_lease(self, hid: str, holder: str, fence: int) -> float: ...
+
+    @abc.abstractmethod
+    def release_ownership(self, hid: str, holder: str,
+                          fence: int) -> None: ...
+
+    @abc.abstractmethod
+    def force_orphan(self, hid: str, orphan_holder: str) -> bool: ...
+
+    @abc.abstractmethod
+    def expired_leases(self,
+                       now: Optional[float] = None) -> List[str]: ...
+
+    # -- supervisor leadership --
+    @abc.abstractmethod
+    def acquire_leadership(self, holder: str, ttl_s: float) -> bool: ...
+
+    @abc.abstractmethod
+    def renew_leadership(self, holder: str, ttl_s: float) -> bool: ...
+
+    @abc.abstractmethod
+    def get_leadership(self) -> Optional[Dict[str, Any]]: ...
+
+    @abc.abstractmethod
+    def close(self) -> None: ...

dhp/bridge_worker.py

@@ -0,0 +1,71 @@
+"""bridge_worker.py — worker driver for the A2A+DHP demo.
+
+Works an A2A task through the DHP bridge: claims/recovers the task's
+DHP handoff, runs the prime-census chunk loop with per-chunk
+heartbeats, completes. The A2A task ID is stable; DHP handles worker
+swaps underneath.
+
+  python3 bridge_worker.py --root R --task <a2a-task-id> --worker <id>
+      [--chunk N] [--pace S] (claim|recover)
+"""
+import argparse
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from dhp.a2a_bridge import DHPBridge  # noqa: E402
+from dhp.prime_chunk import chunk  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True)
+    ap.add_argument("--task", required=True)
+    ap.add_argument("--worker", required=True)
+    ap.add_argument("--chunk", type=int, default=100)
+    ap.add_argument("--pace", type=float, default=0.4)
+    ap.add_argument("mode", choices=["claim", "recover"])
+    a = ap.parse_args()
+
+    b = DHPBridge(a.root, bridge_id="demo-bridge")
+    if a.mode == "claim":
+        ctx, hid = b.claim_for_task(a.task, a.worker)
+    else:
+        ctx, hid = b.recover_for_task(a.task, a.worker)
+    env = b.runner._load(hid)
+    lo = env["task"]["inputs"]["inline"]["lo"]
+    hi = env["task"]["inputs"]["inline"]["hi"]
+
+    st = b.runner.last_checkpoint(hid)
+    if st is None:
+        nxt, count, total, done = lo, 0, 0, 0
+    else:
+        nxt, count, total = st["next_n"], st["count"], st["total"]
+        done = 0
+    t0 = time.time()
+    while nxt < hi:
+        chi = min(nxt + a.chunk, hi)
+        c = chunk(nxt, chi)
+        count += c["count"]
+        total += c["sum"]
+        nxt = chi
+        done += 1
+        ctx.checkpoint({"next_n": nxt, "count": count, "total": total})
+        ctx.note_step()
+        ctx.heartbeat()
+        if a.pace:
+            time.sleep(a.pace)
+    ctx.complete({"lo": lo, "hi": hi, "prime_count": count,
+                  "prime_sum": total, "chunks_done": done})
+    print(json.dumps({"completed": True, "task_id": a.task,
+                      "worker": a.worker, "prime_count": count,
+                      "prime_sum": total, "chunks_done": done,
+                      "elapsed_s": round(time.time() - t0, 1),
+                      "a2a_state": b.task_state(a.task)}))
+
+
+if __name__ == "__main__":
+    main()