diff --git a/EXPORT-MANIFEST.json b/EXPORT-MANIFEST.json index f8f2aa4..d9eb5c4 100644 --- a/EXPORT-MANIFEST.json +++ b/EXPORT-MANIFEST.json @@ -187,8 +187,8 @@ "bytes": 6137 }, "adapters/aor_session.py": { - "sha256": "c45b530b131a3c592a3abbf4a24da9747e40c9a75e02d7782338450c89eb97ef", - "bytes": 12484 + "sha256": "facff6b954394fda2eab4cf391a0764bec3fa5593dae3712398ace651cbbdf03", + "bytes": 12573 }, "adapters/approval_store.py": { "sha256": "6d31137b5febcf04574ce4d21e57eac8157c03a0ef4823e0277acf0ba34030e0", @@ -251,8 +251,8 @@ "bytes": 25742 }, "adapters/mcp_stdio_server.py": { - "sha256": "433e7e59d43e85743c43b6039107fface3a206002c8246f72f754ef54ff06b22", - "bytes": 12830 + "sha256": "85ec747279ea6f903b4f7679888e2b65ee123dda793acf7469702b81169f8b34", + "bytes": 15858 }, "adapters/memory/README.md": { "sha256": "30dd166af5d401519d2acd28f357c51f2a0fa0b98a0cd445449d4c95963b183e", @@ -326,6 +326,10 @@ "sha256": "26f8e1d9126f1a31605165d7dccbe739b9a1d06a93f8439de0c1fe482496b261", "bytes": 23322 }, + "adapters/work_tree.py": { + "sha256": "f0ed712cbb7875e4d1b971d23c7d3e2ce7cbebbe14c023b54598dc6d46dce378", + "bytes": 27540 + }, "adapters/workcell-toolchain/package-lock.json": { "sha256": "3880db67325516ae75fee04451b4988990f733930d524ed2d950382994883af0", "bytes": 1897 @@ -495,8 +499,8 @@ "bytes": 5889 }, "bootstrap.py": { - "sha256": "7c4b19e2e25b70dac12e953339d97bb00e30fbb293841f57c2e27fcfff523daa", - "bytes": 28554 + "sha256": "10e9324e0cb65b82647a4951b6d64a37bf3d1e69814025862dd11d58016bfa1c", + "bytes": 29254 }, "ci/host-only.txt": { "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", @@ -527,8 +531,8 @@ "bytes": 8349 }, "contracts/ADAPTERS.json": { - "sha256": "93adda92a1835f6582051827bbb1bea07d85c0025de50c45f1d6eae0ab395334", - "bytes": 34803 + "sha256": "84bd10645ccdaab28761a4c9df4cf69cf6d637100ae3e26eb32421422b48eed6", + "bytes": 35716 }, "contracts/CONTRACT.json": { "sha256": "05848bff545d839bdcc9e30f4c8d2352f768e0298129e4bc57cbb68ed9e0c0c5", @@ -599,8 +603,8 @@ "bytes": 7304 }, "docs/architecture/architecture.md": { - "sha256": "c2f3e1176b61a4b736ce1fbb458d6685afe456511bcca57461178c8c73cf2eea", - "bytes": 23563 + "sha256": "e6e3c6a05b91175d341311f09c4421d6f8f6aa58d660435be713423c5c2a5833", + "bytes": 23821 }, "docs/assurance/assurance-record.md": { "sha256": "125c34adde85a2d1e2ffecc200fdc6836d1a694e7d7e09cb15505930323cdd00", @@ -611,8 +615,8 @@ "bytes": 16687 }, "docs/data/data-dictionary.md": { - "sha256": "d9bba09a36862ca00df6d7952c492484f26971ca655b69a6134e644a117a7982", - "bytes": 25475 + "sha256": "fb3f92aa10724aa5cd93ec35426e330c6ecb8f0c001aff830afc58298e6ad027", + "bytes": 25575 }, "docs/guides/SUM-MAP.md": { "sha256": "374d3bd14d81457b27bf2231509788cddd7f4851be9d325356a56099f558242a", @@ -635,8 +639,8 @@ "bytes": 4034 }, "docs/guides/explanation/server-and-adapters.md": { - "sha256": "8756fa75134d603696266069d266aaff3d87f658c2b74d4d8b4f14b244399183", - "bytes": 7455 + "sha256": "eb965c36bfe337d16bfbf0352a3f3bb42ff9312bd085af5a6762268027847d53", + "bytes": 9984 }, "docs/guides/explanation/starter-agents.md": { "sha256": "d8dd4e95440680d7d3ba8b1e2a39a1c2f72b47486f204e39e716a6d2395ed7c4", @@ -735,8 +739,8 @@ "bytes": 5760 }, "docs/requirements/requirements.md": { - "sha256": "66c1afb8e4f49f5826d924ebaa502c8dc6bb2c8160a072ecbd3cf839c6a1817e", - "bytes": 56513 + "sha256": "0feffe4dbefb951a4ed5e01ef22d7a80a77440bc9c2a521c869d1c88a48f09dd", + "bytes": 58652 }, "docs/rules/no-comments.md": { "sha256": "cd0aac16b8119228bb5b7e79d38e71ddcc430679916a9f7080d7b3bd88fb4a90", @@ -843,8 +847,8 @@ "bytes": 9734 }, "docs/verification/verification-matrix.md": { - "sha256": "3ab4f04b2caccea8d15d3129263073113e3dcfb5b6aba0e2b4600f3b64658f74", - "bytes": 25638 + "sha256": "615a7476e3c1eb135f0c1f031ec22f25076fa7290f29a85bf4f7d8193ca303c6", + "bytes": 25908 }, "docs/verification/wiring-acceptance.md": { "sha256": "a063e0580bf60ca41b37d473f1df7989b12c7e0aa915cecef30b916a4c4720d8", @@ -2246,6 +2250,10 @@ "sha256": "c20830e7e722a39c1a8fad60d90f6dcdbbbf3719fb517adfc1a6f3ab875af572", "bytes": 2712 }, + "tests/fixtures/mcp_tools_list_handoff.json": { + "sha256": "648be48581e9522f891dbf22fc242e809a9bdb43ea29569fb9230928aef7173d", + "bytes": 5900 + }, "tests/forge_fixtures.py": { "sha256": "286c885a68db8531c05796825cc7edf27fe2380c90b582d6017030f387319e49", "bytes": 5630 @@ -2598,6 +2606,10 @@ "sha256": "fdd0dd815cdba00a9ce7b8c46d95b5337d14837e09c6057420e73467662e9dd9", "bytes": 23004 }, + "tests/test_work_tree.py": { + "sha256": "cf4ff3e78b5365e11adb51679a8c1e1e20140f445adba45e1ed978c4cf3f6571", + "bytes": 26799 + }, "tests/test_workcell_film_robotics.py": { "sha256": "0f66b5c9094d4b0a4e2da41af42cb7658be7e50290c160a27addf5c70ae71d4f", "bytes": 10073 diff --git a/adapters/aor_session.py b/adapters/aor_session.py index 8e7a702..28c3170 100644 --- a/adapters/aor_session.py +++ b/adapters/aor_session.py @@ -110,6 +110,7 @@ def effective_class(bot, device, effect, shields_up): class AorSession: mail = None # Host-configured fleet-mail port, enabled only by --fleet-mail. + handoff = None def __init__(self, *, fleet, bot_slug, hostname, state_dir, domains, make_core, ledger_label, shields_file): """domains: {domain_id: (operations, effect)}; make_core(domain, grants, anchors) -> (core, ledger, store_claim). @@ -273,6 +274,8 @@ def close(self): self._ledgers.clear() if self.mail is not None and hasattr(self.mail._ledger, "close"): self.mail._ledger.close() + if self.handoff is not None: + self.handoff.close() for claim in self._claims: claim.close() self._claims.clear() diff --git a/adapters/mcp_stdio_server.py b/adapters/mcp_stdio_server.py index 5d7892a..d87fd8e 100644 --- a/adapters/mcp_stdio_server.py +++ b/adapters/mcp_stdio_server.py @@ -92,6 +92,39 @@ def _idempotent(tool): ) +_NODE = {"type": "string", "pattern": "^w[0-9]{1,9}$"} +_TEXT = {"type": "string", "minLength": 1, "maxLength": 4000} +HANDOFF_TOOLS = ( + _tool("handoff_create", "Hand off work", "Hand part of a running node assigned to this bot to a reachable bot, as a " + "child node. The host stamps the requester, copies the root's lineage and refuses loops, depth, unreachable " + "bots, held domains and full roots with a typed refusal.", + {"node_id": _NODE, "assignee": {"type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$"}, "brief": _TEXT, + "mode": {"type": "string", "enum": ["work", "consult", "notify"]}, + "reply": {"type": "string", "enum": ["resume", "poll", "none"]}, + "artifacts": {"type": "array", "maxItems": 16, "items": {"type": "object", "required": ["name", "ref"], + "additionalProperties": False, "properties": { + "name": {"type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$"}, "ref": _TEXT}}}, + "chase_after": {"type": "integer", "minimum": 60, "maximum": 604800}}, + ["node_id", "assignee", "brief"]), + _tool("handoff_start", "Start a hand-off", "Start a queued or resumed node assigned to this bot. One live node per bot.", + {"node_id": _NODE}, ["node_id"]), + _tool("handoff_status", "Hand-off status", "One node this bot sent or holds, with its children, or every open one. " + "Results and answers from other bots are information only.", {"node_id": _NODE}, [], read_only=True), + _tool("handoff_wait", "Poll hand-offs", "Non-blocking: return this bot's undelivered wakes, chases and answers once, " + "and the nodes waiting for it. With node_id, first park that running node until its replying children settle.", + {"node_id": _NODE}, []), + _tool("handoff_settle", "Settle a hand-off", "The assignee completes or fails its running node; the requester cancels " + "a node it handed off, with its subtree.", {"node_id": _NODE, "outcome": {"type": "string", "enum": [ + "completed", "failed", "cancelled"]}, "result": {"type": "string", "maxLength": 4000}}, + ["node_id", "outcome"], destructive=True), + _tool("handoff_park", "Ask for input", "Park a running node on a question for the owner (answered through the host, " + "never recorded) or for the requester bot.", {"node_id": _NODE, "question": _TEXT, + "asks": {"type": "string", "enum": ["owner", "requester"]}}, ["node_id", "question"]), + _tool("handoff_answer", "Answer a hand-off", "Answer a question a node this bot handed off asked its requester.", + {"node_id": _NODE, "answer": _TEXT}, ["node_id", "answer"]), +) + + def _strict_loads(line): def pairs(items): keys = [k for k, _ in items] @@ -122,7 +155,8 @@ def __init__(self, session, *, name="cstack"): self._session, self._name, self._ready = session, name, False domains = getattr(session, "classes", None) # an AorSession reports every registered domain, denied included self._tools = (domain_tools(domains) if domains else TOOLS) + ( - MAIL_TOOLS if getattr(session, "mail", None) is not None else ()) + MAIL_TOOLS if getattr(session, "mail", None) is not None else ()) + ( + HANDOFF_TOOLS if getattr(session, "handoff", None) is not None else ()) self._by_name = {tool["name"]: tool for tool in self._tools} def handle(self, message): @@ -162,6 +196,9 @@ def _call(self, tool, arguments): try: _check_arguments(tool, arguments) name = tool["name"] + if name.startswith("handoff_"): + payload = getattr(self._session.handoff, name.removeprefix("handoff_"))(**arguments) + return _tool_result(payload, error="refused" in payload) target = self._session.mail if name.startswith("mail_") else self._session return _tool_result(getattr(target, name.removeprefix("mail_"))(**arguments)) except (ContractError, ValueError, TypeError) as error: diff --git a/adapters/work_tree.py b/adapters/work_tree.py new file mode 100644 index 0000000..095dd55 --- /dev/null +++ b/adapters/work_tree.py @@ -0,0 +1,606 @@ +from contextlib import contextmanager +from dataclasses import dataclass, field, replace +import fcntl +import json +import os +from pathlib import Path +from threading import RLock +import time + +from poodo_core.models import ContractError, identifier + +STATUSES = ("queued", "running", "needs_input", "waiting", "resume", "completed", "failed", "cancelled") +TERMINAL = ("completed", "failed", "cancelled") +MODES = ("work", "consult", "notify") +REPLIES = ("resume", "poll", "none") +ORIGINS = ("owner", "routine", "outside") +ASKS = ("owner", "requester") +REFUSALS = ("held", "depth", "loop", "unreachable", "root_full", "busy", "state", "not_yours", "shields", "artifact", + "mode", "unknown") +MARK = "[From" +MAX_TEXT = 4000 +MAX_ARTIFACTS = 16 +POLICY_KEYS = {"tree", "max_open_per_root", "max_depth", "reachable", "artifact_names", "max_chase_after"} + + +class Refused(ContractError): + def __init__(self, code, reason): + if code not in REFUSALS: + raise ContractError(f"Unknown refusal code {code!r}") + super().__init__(f"{code}: {reason}") + self.code, self.reason = code, reason + + def typed(self): + return {"refused": self.code, "reason": self.reason} + + +@dataclass(frozen=True) +class HandoffPolicy: + max_open_per_root: int = 4 + max_depth: int = 3 + reachable: dict = field(default_factory=dict) + artifact_names: tuple | None = None + max_chase_after: int = 7 * 86400 + + def __post_init__(self): + for name in ("max_open_per_root", "max_depth", "max_chase_after"): + if type(getattr(self, name)) is not int or getattr(self, name) < 1: + raise ContractError(f"{name} is a positive integer") + if type(self.reachable) is not dict: + raise ContractError("reachable maps a sender to the bots it may hand off to") + for sender, targets in self.reachable.items(): + identifier(sender) + if type(targets) not in (list, tuple): + raise ContractError("reachable maps a sender to a list of bots") + for target in targets: + identifier(target) + if self.artifact_names is not None: + for name in self.artifact_names: + identifier(name) + + def routes(self, sender): + return tuple(self.reachable.get(sender, ())) + + +def load_policy(path): + config = json.loads(Path(path).read_text(encoding="utf-8")) + if type(config) is not dict or not set(config) <= POLICY_KEYS or type(config.get("tree")) is not str: + raise ContractError(f"handoff.json takes {sorted(POLICY_KEYS)} and names its tree file") + names = config.get("artifact_names") + policy = HandoffPolicy(**{k: v for k, v in config.items() if k not in ("tree", "artifact_names")}, + artifact_names=None if names is None else tuple(names)) + return Path(path).parent / config["tree"], policy + + +@dataclass(frozen=True) +class Node: + id: str + root_id: str + parent_id: str | None + depth: int + origin: str + owner_quote: str + owner_message_id: str | None + requester: str + assignee: str + domain: str + mode: str + reply: str + brief: str + artifacts: list + chase_at: int | None + status: str = "queued" + outcome: str | None = None + result: str | None = None + evidence: dict = field(default_factory=dict) + question: str | None = None + asks: str | None = None + answer: str | None = None + idle_continues: int = 0 + reported: bool = False + chased: bool = False + + +def _text(value, name): + if type(value) is not str or len(value) > MAX_TEXT: + raise ContractError(f"{name} is text of at most {MAX_TEXT} characters") + return value + + +def quote(text): + return json.dumps(_text(text, "quoted text").replace(MARK, "[from"))[1:-1] + + +def _artifacts(items, names): + if type(items) not in (list, tuple) or len(items) > MAX_ARTIFACTS: + raise Refused("artifact", f"artifacts is a list of at most {MAX_ARTIFACTS}") + out = [] + for item in items: + if type(item) is not dict or set(item) != {"name", "ref"}: + raise Refused("artifact", "each artifact is {name, ref}") + identifier(item["name"]) + if names is not None and item["name"] not in names: + raise Refused("artifact", f"artifact {item['name']!r} is not in the host's artifact table") + out.append({"name": item["name"], "ref": _text(item["ref"], "artifact ref")}) + return out + + +class WorkTree: + def __init__(self, path=None, *, clock=time.time, policy=None, witness=None, holds=()): + self._path = None if path is None else str(path) + self._clock, self.policy, self._witness = clock, policy or HandoffPolicy(), witness + self.nodes, self.events, self.holds = {}, [], {} + self.witness_warnings = [] + self._offset, self._depth, self._lock = 0, 0, RLock() + if self._path is not None: + Path(self._path).parent.mkdir(parents=True, exist_ok=True, mode=0o700) + with self._synced(): + for domain, reason in holds: + if domain not in self.holds: + self._hold(domain, reason) + + @contextmanager + def _synced(self): + with self._lock: + if self._depth or self._path is None: + self._depth += 1 + try: + yield + finally: + self._depth -= 1 + return + fd = os.open(self._path + ".lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600) + try: + fcntl.flock(fd, fcntl.LOCK_EX) + self._catch_up() + self._depth += 1 + try: + yield + finally: + self._depth -= 1 + finally: + os.close(fd) + + def _catch_up(self): + if not os.path.exists(self._path): + return + fd = os.open(self._path, os.O_RDONLY | os.O_NOFOLLOW) + try: + os.lseek(fd, self._offset, os.SEEK_SET) + chunks = [] + while chunk := os.read(fd, 1 << 16): + chunks.append(chunk) + finally: + os.close(fd) + raw = b"".join(chunks) + end = raw.rfind(b"\n") + 1 + if end < len(raw): + self._set_aside(raw[end:], self._offset + end) + for line in raw[:end].splitlines(): + self._apply(json.loads(line)) + self._offset += end + + def _set_aside(self, tail, keep): + side = os.open(f"{self._path}.torn-{keep}", os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600) + try: + os.write(side, tail) + os.fsync(side) + finally: + os.close(side) + os.truncate(self._path, keep) + + def _write(self, line): + fd = os.open(self._path, os.O_WRONLY | os.O_CREAT | os.O_APPEND | os.O_NOFOLLOW, 0o600) + try: + os.write(fd, line) + os.fsync(fd) + finally: + os.close(fd) + self._offset += len(line) + + def _apply(self, event): + if event.get("seq") != len(self.events) + 1: + raise ContractError(f"Work tree event {event.get('seq')} out of order after {len(self.events)}") + self.events.append(event) + kind, nid = event["kind"], event.get("id") + if kind == "enqueued": + self.nodes[nid] = Node(**event["node"]) + elif kind == "held": + self.holds[event["domain"]] = event["reason"] + elif kind == "released": + self.holds.pop(event["domain"], None) + elif kind == "chased": + self.nodes[nid] = replace(self.nodes[nid], chased=True) + elif kind == "reported": + self.nodes[nid] = replace(self.nodes[nid], reported=True) + elif kind == "status": + changes = {k: event[k] for k in ("status", "outcome", "result", "evidence", "question", "asks", "answer", + "idle_continues") if k in event} + self.nodes[nid] = replace(self.nodes[nid], **changes) + elif kind not in ("woken", "delivered", "answered"): + raise ContractError(f"Unknown work tree event {kind!r}") + + def _event(self, kind, **data): + event = {"seq": len(self.events) + 1, "kind": kind, "at": int(self._clock()), **data} + line = (json.dumps(event, sort_keys=True, ensure_ascii=True) + "\n").encode("ascii") + event = json.loads(line) + if self._witness is not None: + self._witness.reserve(1, 2 * len(line) + 1024) + if self._path is not None: + self._write(line) + self._apply(event) + if self._witness is not None: + try: + self._witness.append("observation", {"work_tree": event}) + except (ContractError, OSError) as error: + self.witness_warnings.append(f"event {event['seq']} not witnessed: {error}") + return event + + def refresh(self): + with self._synced(): + return len(self.events) + + def node(self, nid): + with self._synced(): + if nid not in self.nodes: + raise Refused("unknown", f"no work node {nid!r}") + return self.nodes[nid] + + def children(self, nid): + return [c for c in self.nodes.values() if c.parent_id == nid] + + def _open_resume_children(self, nid): + return [c for c in self.children(nid) if c.reply == "resume" and c.status not in TERMINAL] + + def _move(self, nid, allowed, status, **data): + if self.node(nid).status not in allowed: + raise Refused("state", f"node {nid} is {self.nodes[nid].status}, not {' or '.join(allowed)}") + return self._event("status", id=nid, status=status, **data) + + def enqueue(self, *, requester, assignee, domain, brief, mode="work", reply="resume", parent_id=None, + origin=None, owner_quote="", owner_message_id=None, chase_at=None, artifacts=()): + with self._synced(): + for value in (requester, assignee, domain): + identifier(value) + if mode not in MODES or reply not in REPLIES: + raise Refused("mode", "mode is work, consult or notify; reply is resume, poll or none") + if mode == "notify" and reply != "none": + raise Refused("mode", "a notify hand-off takes reply none") + if domain in self.holds: + raise Refused("held", f"domain {domain} is held by the owner: {self.holds[domain]}") + if parent_id is None: + if origin not in ORIGINS: + raise ContractError("A root names its origin: owner, routine or outside") + if owner_message_id is not None: + identifier(owner_message_id) + root, depth, lineage = None, 0, (origin, _text(owner_quote, "owner quote"), owner_message_id) + else: + parent = self.node(parent_id) + self._check_child(parent, requester, assignee, mode) + root, depth = parent.root_id, parent.depth + 1 + lineage = (parent.origin, parent.owner_quote, parent.owner_message_id) + if chase_at is not None and type(chase_at) is not int: + raise ContractError("chase_at is an integer time") + nid = f"w{sum(1 for e in self.events if e['kind'] == 'enqueued') + 1}" + node = Node(nid, root or nid, parent_id, depth, *lineage, requester, assignee, domain, mode, reply, + _text(brief, "brief"), _artifacts(artifacts, self.policy.artifact_names), chase_at) + self._event("enqueued", id=nid, node=vars(node)) + return self.nodes[nid] + + def _check_child(self, parent, requester, assignee, mode): + if parent.assignee != requester: + raise Refused("not_yours", f"node {parent.id} is assigned to {parent.assignee}, not {requester}") + if parent.status != "running": + raise Refused("state", "only a running node hands out work") + if parent.mode != "work" and mode != parent.mode: + raise Refused("mode", f"a {parent.mode} node hands out only {parent.mode} work") + if parent.depth + 1 > self.policy.max_depth: + raise Refused("depth", f"hand-off depth is capped at {self.policy.max_depth}") + branch, cursor = {parent.assignee}, parent + while cursor.parent_id is not None: + cursor = self.nodes[cursor.parent_id] + branch.add(cursor.assignee) + if assignee in branch: + raise Refused("loop", f"{assignee} is already on this branch; work does not go back up it") + if assignee not in self.policy.routes(requester): + raise Refused("unreachable", f"{requester} may hand off only to {list(self.policy.routes(requester))}") + open_in_root = sum(1 for n in self.nodes.values() if n.root_id == parent.root_id and n.status not in TERMINAL) + if open_in_root >= self.policy.max_open_per_root: + raise Refused("root_full", f"at most {self.policy.max_open_per_root} open nodes per root") + + def start(self, nid): + with self._synced(): + node = self.node(nid) + if node.domain in self.holds: + raise Refused("held", f"domain {node.domain} is held by the owner") + busy = [n.id for n in self.nodes.values() if n.assignee == node.assignee and n.status == "running"] + if node.status in ("queued", "resume") and busy: + raise Refused("busy", f"{node.assignee} already runs {busy[0]}; one live instance per bot") + return self._move(nid, ("queued", "resume"), "running") + + def park(self, nid, question, asks="owner"): + with self._synced(): + if asks not in ASKS: + raise Refused("mode", "a question asks the owner or the requester") + return self._move(nid, ("running",), "needs_input", question=_text(question, "question"), asks=asks) + + def answer_owner(self, nid, value): + with self._synced(): + if self.node(nid).asks != "owner": + raise Refused("state", f"node {nid} is not waiting on the owner") + self._move(nid, ("needs_input",), "resume", question=None, asks=None) + self._event("answered", id=nid, by="owner") + return value + + def answer_requester(self, nid, answer): + with self._synced(): + if self.node(nid).asks != "requester": + raise Refused("state", f"node {nid} is not waiting on its requester") + event = self._move(nid, ("needs_input",), "resume", question=None, asks=None, + answer=_text(answer, "answer")) + self._event("answered", id=nid, by="requester", bot=self.nodes[nid].assignee) + return event + + def continue_turn(self, nid, ok_tool_calls): + with self._synced(): + idle = self.node(nid).idle_continues + 1 if ok_tool_calls == 0 else 0 + if idle >= 2: + return self.settle(nid, "failed", "stalled: two continuations with no progress") + return self._move(nid, ("running",), "queued", idle_continues=idle) + + def wait(self, nid): + with self._synced(): + if not self._open_resume_children(nid): + raise Refused("state", "a node waits only on an open child that replies; read its status") + return self._move(nid, ("running",), "waiting") + + def settle(self, nid, outcome, result="", evidence=None): + with self._synced(): + if outcome not in TERMINAL: + raise ContractError("An outcome is completed, failed or cancelled") + if self.node(nid).status in TERMINAL: + raise Refused("state", f"node {nid} is already settled") + self._event("status", id=nid, status=outcome, outcome=outcome, result=_text(result, "result"), + evidence=dict(evidence or {}), question=None, asks=None) + self._report(nid) + return self.nodes[nid] + + def cancel(self, nid, reason): + with self._synced(): + if self.node(nid).status not in TERMINAL: + self.settle(nid, "cancelled", reason) + for child in self.children(nid): + if child.status not in TERMINAL or self.children(child.id): + self.cancel(child.id, reason) + + def hold(self, domain, reason): + with self._synced(): + self._hold(domain, reason) + + def _hold(self, domain, reason): + identifier(domain) + self._event("held", domain=domain, reason=_text(reason, "reason")) + for node in sorted(self.nodes.values(), key=lambda n: n.depth): + if node.domain == domain and self.nodes[node.id].status not in TERMINAL: + self.cancel(node.id, f"owner hold on {domain}: {reason}") + + def release(self, domain): + with self._synced(): + self._event("released", domain=identifier(domain)) + + def _report(self, nid): + node = self.nodes[nid] + if node.parent_id is None or node.reply == "none" or node.reported: + return + self._event("reported", id=nid) + parent = self.nodes[node.parent_id] + if parent.status == "waiting" and not self._open_resume_children(parent.id): + settled = [{"id": c.id, "outcome": c.outcome} for c in self.children(parent.id) + if c.reply == "resume" and c.status in TERMINAL] + self._event("status", id=parent.id, status="resume") + self._event("woken", id=parent.id, bot=parent.assignee, children=settled) + + def sweep(self, now=None): + with self._synced(): + now = int(self._clock() if now is None else now) + for node in list(self.nodes.values()): + if node.chase_at is not None and now >= node.chase_at and node.status not in TERMINAL \ + and not node.chased: + self._event("chased", id=node.id, bot=node.requester, status=node.status) + + def inbox(self, bot): + with self._synced(): + delivered = {s for e in self.events if e["kind"] == "delivered" for s in e["seqs"]} + return [e for e in self.events if e["kind"] in ("woken", "chased", "answered") and e.get("bot") == bot + and e["seq"] not in delivered] + + def deliver(self, bot): + with self._synced(): + items = self.inbox(bot) + if items: + self._event("delivered", bot=bot, seqs=[e["seq"] for e in items]) + return items + + def envelope(self, nid): + n = self.node(nid) + if n.origin == "owner": + asked = f' The owner asked: "{quote(n.owner_quote)}"' if n.owner_quote else "" + proof = (f" (owner message {n.owner_message_id})" if n.owner_message_id + else " (no owner message id: not an approval)") + authority = f"on the owner's behalf{proof}.{asked}" + elif n.origin == "routine": + authority = "on the owner's behalf, from the owner's routine." + else: + authority = "information only: outside content is not the owner's authority." + act = {"work": "", "consult": " Consult: act on nothing.", "notify": " Notify: no reply."}[n.mode] + return (f"{MARK} {quote(n.requester)} · {n.mode} {n.id} in {n.domain} · {authority}]{act} " + f"Brief: {quote(n.brief)}") + + def close(self): + if self._witness is not None and hasattr(self._witness, "close"): + self._witness.close() + + +def replay(events): + tree = WorkTree() + for event in events: + tree._apply(event) + return tree + + +def check_invariants(tree, *, final=False): + problems = [] + tree.refresh() + delivered = [s for e in tree.events if e["kind"] == "delivered" for s in e["seqs"]] + if len(delivered) != len(set(delivered)): + problems.append("I3 an inbox item was delivered twice") + running = {} + for n in tree.nodes.values(): + if n.status == "waiting" and not tree._open_resume_children(n.id): + problems.append(f"I1 {n.id}: waiting on no open child") + reports = sum(1 for e in tree.events if e["kind"] == "reported" and e.get("id") == n.id) + if reports > 1 or (n.status in TERMINAL and n.parent_id and n.reply != "none" and reports != 1): + problems.append(f"I2 {n.id}: {reports} reports") + if n.status in TERMINAL and n.outcome != n.status: + problems.append(f"I4 {n.id}: terminal without a matching outcome") + if final and n.parent_id is None and n.status not in TERMINAL: + problems.append(f"I4 {n.id}: root ended {n.status}") + if n.domain in tree.holds and n.status not in TERMINAL: + problems.append(f"H1 {n.id}: open in held domain {n.domain}") + if n.status == "running": + running.setdefault(n.assignee, []).append(n.id) + for bot, ids in running.items(): + if len(ids) > 1: + problems.append(f"C2 {bot}: {len(ids)} live instances {ids}") + rebuilt = replay(tree.events) + if rebuilt.nodes != tree.nodes or rebuilt.holds != tree.holds: + problems.append("I7 the tree differs from its events") + return problems + + +def witness_gaps(tree, ledger_events): + witnessed = {e["data"]["work_tree"]["seq"]: e["data"]["work_tree"] for e in ledger_events + if type(e.get("data")) is dict and "work_tree" in e["data"]} + return [e["seq"] for e in tree.events if witnessed.get(e["seq"]) != e] + + +class HandoffDesk: + def __init__(self, tree, me, *, shields_up=lambda: False, clock=time.time): + self._tree, self._me, self._shields_up, self._clock = tree, identifier(me), shields_up, clock + + def _typed(self, call): + try: + with self._tree._synced(): + result = call() + except Refused as refusal: + return refusal.typed() + if self._tree.witness_warnings: + result = {**result, "witness_warnings": list(self._tree.witness_warnings)} + return result + + def _mine(self, nid): + node = self._tree.node(nid) + if self._me not in (node.assignee, node.requester): + raise Refused("not_yours", f"node {nid} is not assigned to or by {self._me}") + return node + + def _view(self, node): + view = {"id": node.id, "root_id": node.root_id, "parent_id": node.parent_id, "depth": node.depth, + "requester": node.requester, "assignee": node.assignee, "domain": node.domain, "mode": node.mode, + "reply": node.reply, "status": node.status, "artifacts": node.artifacts} + if node.assignee == self._me: + view["envelope"] = self._tree.envelope(node.id) + if node.answer is not None: + view["answer"] = {"from": node.requester, "authority": "information only", + "text": quote(node.answer)} + if node.question is not None: + view["question"] = {"from": node.assignee, "asks": node.asks, "text": quote(node.question)} + if node.status in TERMINAL: + view["outcome"] = node.outcome + view["result"] = {"from": node.assignee, "authority": "information only", "text": quote(node.result)} + return view + + def create(self, node_id, assignee, brief, mode="work", reply="resume", artifacts=(), chase_after=None): + def call(): + if self._shields_up(): + raise Refused("shields", "shields are up: no new hand-offs until the host lowers them") + parent = self._mine(node_id) + chase_at = None + if chase_after is not None: + if type(chase_after) is not int or not 60 <= chase_after <= self._tree.policy.max_chase_after: + raise ContractError(f"chase_after is 60..{self._tree.policy.max_chase_after} seconds") + chase_at = int(self._clock()) + chase_after + node = self._tree.enqueue(parent_id=node_id, requester=self._me, assignee=assignee, + domain=parent.domain, brief=brief, mode=mode, reply=reply, + artifacts=artifacts, chase_at=chase_at) + return {"created": self._view(node)} + return self._typed(call) + + def start(self, node_id): + def call(): + if self._mine(node_id).assignee != self._me: + raise Refused("not_yours", f"node {node_id} is not assigned to {self._me}") + self._tree.start(node_id) + return {"started": self._view(self._tree.node(node_id))} + return self._typed(call) + + def status(self, node_id=None): + def call(): + if node_id is not None: + node = self._mine(node_id) + return {"node": self._view(node), + "children": [self._view(c) for c in self._tree.children(node.id)]} + self._tree.refresh() + mine = [n for n in self._tree.nodes.values() if self._me in (n.assignee, n.requester) + and n.status not in TERMINAL] + return {"open": [self._view(n) for n in mine]} + return self._typed(call) + + def wait(self, node_id=None): + def call(): + if node_id is not None: + if self._mine(node_id).assignee != self._me: + raise Refused("not_yours", f"node {node_id} is not assigned to {self._me}") + self._tree.wait(node_id) + items = self._tree.deliver(self._me) + self._tree.refresh() + assigned = [self._view(n) for n in self._tree.nodes.values() + if n.assignee == self._me and n.status in ("queued", "resume")] + return {"inbox": [{k: e[k] for k in ("seq", "kind", "id", "children", "status", "by") if k in e} + for e in items], "assigned": assigned} + return self._typed(call) + + def settle(self, node_id, outcome, result=""): + def call(): + node = self._mine(node_id) + if outcome == "cancelled": + if node.requester != self._me: + raise Refused("not_yours", "only the requester cancels a hand-off") + self._tree.cancel(node_id, _text(result, "result") or f"cancelled by {self._me}") + elif outcome in ("completed", "failed"): + if node.assignee != self._me or node.status != "running": + raise Refused("state", "only the assignee settles its running node") + self._tree.settle(node_id, outcome, result) + else: + raise ContractError("outcome is completed, failed or cancelled") + return {"settled": self._view(self._tree.node(node_id))} + return self._typed(call) + + def park(self, node_id, question, asks="owner"): + def call(): + if self._mine(node_id).assignee != self._me: + raise Refused("not_yours", f"node {node_id} is not assigned to {self._me}") + self._tree.park(node_id, question, asks) + return {"parked": self._view(self._tree.node(node_id))} + return self._typed(call) + + def answer(self, node_id, answer): + def call(): + if self._mine(node_id).requester != self._me: + raise Refused("not_yours", "only the requester answers its hand-off's question") + self._tree.answer_requester(node_id, answer) + return {"answered": node_id} + return self._typed(call) + + def close(self): + self._tree.close() diff --git a/bootstrap.py b/bootstrap.py index c7c1f38..aa47320 100644 --- a/bootstrap.py +++ b/bootstrap.py @@ -480,6 +480,19 @@ def make_core(domain, grants, anchors): ledger.close() session.close() raise + if (state_root / "handoff.json").exists(): + ledger = None + try: + from adapters.work_tree import HandoffDesk, WorkTree, load_policy + tree_path, policy = load_policy(state_root / "handoff.json") + ledger = make_ledger("handoff", {}, paths["log"] if witnessed else None) + session.handoff = HandoffDesk(WorkTree(tree_path, clock=clock, policy=policy, witness=ledger), + session.bot.slug, shields_up=session.shields_up, clock=clock) + except BaseException: + if ledger is not None and hasattr(ledger, "close"): + ledger.close() + session.close() + raise return session diff --git a/contracts/ADAPTERS.json b/contracts/ADAPTERS.json index 98abd35..c8c5827 100644 --- a/contracts/ADAPTERS.json +++ b/contracts/ADAPTERS.json @@ -622,6 +622,20 @@ "strategic_dependency_adr": null, "notes": "One file per forge session, so a later session's core can replay a lost controller's attempts. Local fsync only.", "fake_reason": "MemoryLedger is the EvidenceFace fake; this adds only file persistence." + }, + { + "adapter_id": "handoff-work-tree", + "lane": "TruthFace", + "port": "none", + "port_reason": "Host work state for hand-offs between bots, beside the per-domain cores; no TruthFace work-state port exists yet (ADR 005 item 11c). It witnesses through the session's LedgerPort.", + "vendor": "cstack (in-repo), append-only JSON lines chosen by the host in handoff.json", + "kind": "python_module", + "path": "adapters/work_tree.py", + "fake": null, + "fake_reason": "LANE_SUITES has no TruthFace work-state fake; tests/test_work_tree.py drives it in memory and in temporary files with a fixed clock.", + "status": "hard_wired", + "strategic_dependency_adr": null, + "notes": "Optional host-bound hand-off tools: one node per hand-off with immutable lineage, wake-once, chase, owner holds, loop, depth, per-root and one-live-instance limits, reachability from host config. Grants no authority." } ], "not_an_adapter": [ diff --git a/docs/architecture/architecture.md b/docs/architecture/architecture.md index 0b1ab0a..2688374 100644 --- a/docs/architecture/architecture.md +++ b/docs/architecture/architecture.md @@ -84,6 +84,7 @@ Each component lists the requirements allocated to it. `python -B tools/check_tr | SDD-C24 | Examples and placeholders | `examples/`, `products/`, `workshop/`, `cstack.config.example.json` | Example documents and configuration; empty component areas | Infrastructure | | SDD-C26 | Starter agent organization | `agents/`, `contracts/agent.schema.json`, `contracts/agent-org.schema.json`, `tools/agent_profiles.py`, `tools/agent_guard.py`, `tools/check_options.py`, `.claude/agents/` | Engine-neutral agent definitions and templates, the single-writer hand-off table, the Claude Code subagent generator, the guard hook that applies AOR effects to built-in tools and the twenty-option record check | CS-REQ-080, CS-REQ-081, CS-REQ-082, CS-REQ-083 | | SDD-C28 | Local setup (`cstack init`) | `adapters/local_setup.py`, `tools/cstack_init.py` | Creates and checks one machine's private state folder, device name and witnessed-ledger keys, roster and settings; resolves the device name with or without Tailscale | CS-REQ-084, CS-REQ-086 | +| SDD-C29 | Hand-off channel | `adapters/work_tree.py` | Event-sourced work tree beside the cores: one node per hand-off, lineage, wake-once, chase, holds, loop and fan-out limits, witnessed in the session ledger, offered to bots as MCP tools | CS-REQ-087 | | SDD-C31 | Foundations MCP server | `adapters/foundations_mcp.py`, `tools/foundations_mcp.py` | Host-launched MCP server exposing the chosen pinned Foundations' tools to one bot, each call decided and executed through its AOR session | CS-REQ-091 | ```mermaid diff --git a/docs/data/data-dictionary.md b/docs/data/data-dictionary.md index 138ea86..cd3918c 100644 --- a/docs/data/data-dictionary.md +++ b/docs/data/data-dictionary.md @@ -232,6 +232,8 @@ Module-level numeric limits found in the code. Names state the quantity; bytes u | `INPUT_FRAME_BYTES` | 65,536 | `adapters/foundation_stdio.py` | | `OUTPUT_FRAME_BYTES` | 1,048,576 | `adapters/foundation_stdio.py` | | `MAX_FRAME` | 1,048,576 | `adapters/mcp_stdio_server.py` | +| `MAX_TEXT` | 4,000 | `adapters/work_tree.py` | +| `MAX_ARTIFACTS` | 16 | `adapters/work_tree.py` | | `MAX_BYTES` | 268,435,456 | `adapters/workspace_snapshots.py` | | `MAX_FILES` | 50,000 | `adapters/workspace_snapshots.py` | | `MAX_DOCUMENT_BYTES` | 2,097,152 | `poodo_core/models.py` | diff --git a/docs/guides/explanation/server-and-adapters.md b/docs/guides/explanation/server-and-adapters.md index 1a7c3c7..81926e7 100644 --- a/docs/guides/explanation/server-and-adapters.md +++ b/docs/guides/explanation/server-and-adapters.md @@ -29,6 +29,24 @@ What makes it safe to hand to a bot: An AOR session composes Foundations (`bootstrap.DOMAINS`) only. The forge runtime is in `bootstrap.RUNTIMES`, so being on the registry gives a bot no run authority. +### Hand-off tools + +With a `handoff.json` under `--state-root`, the server adds the hand-off tools of CS-REQ-087 (`adapters/work_tree.py`). Bots whose `handoff.json` names the same tree file share one work tree, kept consistent by a file lock; each node is one hand-off. The tree lives beside the POODO cores, not inside one: a core is per-domain and single-caller with no parent or completion API. + +`handoff.json` is host configuration: `tree` (the log file, relative to the state root), `reachable` (sender slug to the bot slugs it may hand off to), and optionally `max_open_per_root` (default 4), `max_depth` (default 3), `max_chase_after` (seconds, default 7 days) and `artifact_names` (the only artifact names a hand-off may carry). Unknown keys are refused. + +| Tool | Caller | Effect | +|---|---|---| +| `handoff_create` | assignee of a running node | Adds a child for a reachable bot with `mode` (`work`, `consult`, `notify`), `reply` (`resume`, `poll`, `none`), artifacts and an optional chase delay. The requester is the session's bot | +| `handoff_start` | assignee | Runs a queued or resumed node; one running node per bot | +| `handoff_status` | requester or assignee | One node with its children, or every open node of this bot. Results and answers are marked information only | +| `handoff_wait` | assignee | Non-blocking. With `node_id`, parks the node until its replying children settle; always returns undelivered wakes, chases and answers once, and the nodes queued for this bot | +| `handoff_settle` | assignee (`completed`, `failed`) or requester (`cancelled`, with the subtree) | Ends a node and reports it to its parent once | +| `handoff_park` | assignee | Asks the owner (answered through the host, never recorded) or the requester | +| `handoff_answer` | requester | Answers its child's question | + +A refusal is a tool error whose payload is `{"refused": code, "reason": text}`, with `code` one of `held`, `depth`, `loop`, `unreachable`, `root_full`, `busy`, `state`, `not_yours`, `shields`, `artifact`, `mode` or `unknown`. Owner holds and releases, chase sweeps, idle-continuation counting, owner answers and root creation are host calls on `WorkTree`, not tools. The assignee sees each node through a harness-written line (`[From · in · ]`) in which model text is escaped and cannot open a second line of its own. Every event is also appended as an observation to the session's ledger on stream `.handoff`, the witnessed node log when `ledger.json` exists. + ### The cockpit DECISION-006 and the docstrings of `adapters/host_read_models.py` and `adapters/relay_outbox.py` refer to a "cstack server" cockpit. That server isn't in this repository. What is here are its read-only projections (`adapters/read_models.py`, `adapters/host_read_models.py`, printed by `tools/read_models.py`) and the relay's append-only outbox (`adapters/relay_outbox.py`). An outbox message is an intent, not authority, and approvals never pass through it. diff --git a/docs/requirements/requirements.md b/docs/requirements/requirements.md index 5898f81..69ecab3 100644 --- a/docs/requirements/requirements.md +++ b/docs/requirements/requirements.md @@ -709,6 +709,16 @@ The device name shall be `--device` when given, else the name `cstack init` reco - Verification: T - Status: Draft +### CS-REQ-087 — Hand-off channel + +The work tree shall record every hand-off between bots as one node in an append-only, locked event log that rebuilds the same tree on reopen, sets a torn last line aside and refuses an event out of order. A node's lineage (owner, routine or outside, and the owner message id) shall be set at the root and copied unchanged to every child; only owner lineage with a message id, or routine lineage, shall be described as acting on the owner's behalf, and the harness-written provenance line shall escape model text that imitates it. A requester waiting on its children shall be woken once, when every child that replies has settled; an overdue child shall chase its requester once. Hand-offs shall be refused, with a typed refusal, when they go back to a bot already on the branch, pass the depth cap, target a bot the host does not list as reachable for the sender, would exceed the open nodes allowed per root (default 4), come from a bot that is not the running assignee, or arrive while shields are up; a bot shall run at most one node at a time. A node shall fail after two continuations in a row with no successful tool call. An owner hold on a domain shall cancel every open node in it and refuse new ones. An owner answer shall be returned to the caller and never written to the log or the ledger. Every event shall also be appended to the session's ledger as an observation, and a missed witness shall be reported. The MCP hand-off tools shall be listed only when the host configures `handoff.json`, shall stamp the requester from the session, and shall not offer owner holds, releases, sweeps or owner answers. + +- Rationale: hand-offs that never come back, chatter loops, fan-out, routines that override the owner's stop, borrowed authority and secrets in transcripts are the failure modes of persistent bot fleets. The tree lives beside the POODO core because a core is per-domain and single-caller with no parent or completion API. +- Derivation: `adapters/work_tree.py`; `adapters/mcp_stdio_server.py`; `bootstrap.py` +- Allocated to: SDD-C29 +- Verification: T +- Status: Baselined + ### 3.8 Memory, read models and watchers ### CS-REQ-062 — Memory store @@ -907,7 +917,7 @@ Every agent definition and template shall fix `poodo.options` at 20 and `poodo.r ## 4. Interface requirements -The interface requirements are the ones above that name an interface: Foundation stdio bridges (CS-REQ-003 to CS-REQ-008, CS-REQ-064, CS-REQ-065; [Foundation ICD](../icd/icd-foundations.md)), EndoForge evidence and runtime (CS-REQ-020 to CS-REQ-035, CS-REQ-068, CS-REQ-069; [EndoForge ICD](../icd/icd-endoforge.md), [EndoForge pin ICD](../icd/icd-endoforge-pin.md)), POODO snapshot (CS-REQ-019; [POODO ICD](../icd/icd-poodo.md)), CLI (CS-REQ-016 to CS-REQ-018, CS-REQ-067; [commands reference](../guides/reference/commands.md)), MCP (CS-REQ-052, CS-REQ-053; [server and adapters](../guides/explanation/server-and-adapters.md)) and the adapter inventory (CS-REQ-036; [`contracts/INTERFACES.md`](../../contracts/INTERFACES.md)). +The interface requirements are the ones above that name an interface: Foundation stdio bridges (CS-REQ-003 to CS-REQ-008, CS-REQ-064, CS-REQ-065; [Foundation ICD](../icd/icd-foundations.md)), EndoForge evidence and runtime (CS-REQ-020 to CS-REQ-035, CS-REQ-068, CS-REQ-069; [EndoForge ICD](../icd/icd-endoforge.md), [EndoForge pin ICD](../icd/icd-endoforge-pin.md)), POODO snapshot (CS-REQ-019; [POODO ICD](../icd/icd-poodo.md)), CLI (CS-REQ-016 to CS-REQ-018, CS-REQ-067; [commands reference](../guides/reference/commands.md)), MCP (CS-REQ-052, CS-REQ-053, CS-REQ-087; [server and adapters](../guides/explanation/server-and-adapters.md)) and the adapter inventory (CS-REQ-036; [`contracts/INTERFACES.md`](../../contracts/INTERFACES.md)). ## 5. Non-functional requirements diff --git a/docs/verification/verification-matrix.md b/docs/verification/verification-matrix.md index 31cae91..ed08b93 100644 --- a/docs/verification/verification-matrix.md +++ b/docs/verification/verification-matrix.md @@ -90,6 +90,7 @@ The matrix does not embed pass counts. A mapped test shows the requirement is ex | CS-REQ-091 | T | `tests/test_foundations_mcp.py` | Every vendored Foundation called once over the real pinned bridges; tampered manifest; stdio launcher | Not yet in a recorded run | | CS-REQ-054 | T | `tests/test_fleet_mail.py`; `tests/test_fleet_mail_budget.py` | Uses a fake `gh`; no network | [STR-baseline](reports/STR-baseline.md) | | CS-REQ-055 | T | `tests/test_relay_outbox.py` | Several processes, torn tails | [STR-baseline](reports/STR-baseline.md) | +| CS-REQ-087 | T | `tests/test_work_tree.py` | Scenario suite and seeded random walk checked against invariants I1, I2, I3, I4, I7, H1 and C2 after every step; temporary log files; MCP tests require the `cryptography` package | [STR-baseline](reports/STR-baseline.md) | | CS-REQ-056 | T | `tests/test_scheduled_approvals.py` | SQLite and witnessed node logs | [STR-baseline](reports/STR-baseline.md) | | CS-REQ-057 | T | `tests/test_runtime_watch.py` | Byte and time identity after a watch | [STR-baseline](reports/STR-baseline.md) | | CS-REQ-058 | T | `tests/test_witness_watch.py` | Deadman boundaries | [STR-baseline](reports/STR-baseline.md) | diff --git a/tests/fixtures/mcp_tools_list_handoff.json b/tests/fixtures/mcp_tools_list_handoff.json new file mode 100644 index 0000000..abad0d6 --- /dev/null +++ b/tests/fixtures/mcp_tools_list_handoff.json @@ -0,0 +1,262 @@ +{ + "tools": [ + { + "name": "handoff_create", + "title": "Hand off work", + "description": "Hand part of a running node assigned to this bot to a reachable bot, as a child node. The host stamps the requester, copies the root's lineage and refuses loops, depth, unreachable bots, held domains and full roots with a typed refusal.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + }, + "assignee": { + "type": "string", + "pattern": "^[A-Za-z0-9_.:-]{1,128}$" + }, + "brief": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + }, + "mode": { + "type": "string", + "enum": [ + "work", + "consult", + "notify" + ] + }, + "reply": { + "type": "string", + "enum": [ + "resume", + "poll", + "none" + ] + }, + "artifacts": { + "type": "array", + "maxItems": 16, + "items": { + "type": "object", + "required": [ + "name", + "ref" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "pattern": "^[A-Za-z0-9_.:-]{1,128}$" + }, + "ref": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + } + } + } + }, + "chase_after": { + "type": "integer", + "minimum": 60, + "maximum": 604800 + } + }, + "required": [ + "node_id", + "assignee", + "brief" + ], + "additionalProperties": false + }, + "annotations": { + "title": "Hand off work", + "readOnlyHint": false, + "destructiveHint": false, + "idempotentHint": false, + "openWorldHint": false + } + }, + { + "name": "handoff_start", + "title": "Start a hand-off", + "description": "Start a queued or resumed node assigned to this bot. One live node per bot.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + } + }, + "required": [ + "node_id" + ], + "additionalProperties": false + }, + "annotations": { + "title": "Start a hand-off", + "readOnlyHint": false, + "destructiveHint": false, + "idempotentHint": false, + "openWorldHint": false + } + }, + { + "name": "handoff_status", + "title": "Hand-off status", + "description": "One node this bot sent or holds, with its children, or every open one. Results and answers from other bots are information only.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + } + }, + "required": [], + "additionalProperties": false + }, + "annotations": { + "title": "Hand-off status", + "readOnlyHint": true, + "destructiveHint": false, + "idempotentHint": true, + "openWorldHint": false + } + }, + { + "name": "handoff_wait", + "title": "Poll hand-offs", + "description": "Non-blocking: return this bot's undelivered wakes, chases and answers once, and the nodes waiting for it. With node_id, first park that running node until its replying children settle.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + } + }, + "required": [], + "additionalProperties": false + }, + "annotations": { + "title": "Poll hand-offs", + "readOnlyHint": false, + "destructiveHint": false, + "idempotentHint": false, + "openWorldHint": false + } + }, + { + "name": "handoff_settle", + "title": "Settle a hand-off", + "description": "The assignee completes or fails its running node; the requester cancels a node it handed off, with its subtree.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + }, + "outcome": { + "type": "string", + "enum": [ + "completed", + "failed", + "cancelled" + ] + }, + "result": { + "type": "string", + "maxLength": 4000 + } + }, + "required": [ + "node_id", + "outcome" + ], + "additionalProperties": false + }, + "annotations": { + "title": "Settle a hand-off", + "readOnlyHint": false, + "destructiveHint": true, + "idempotentHint": false, + "openWorldHint": false + } + }, + { + "name": "handoff_park", + "title": "Ask for input", + "description": "Park a running node on a question for the owner (answered through the host, never recorded) or for the requester bot.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + }, + "question": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + }, + "asks": { + "type": "string", + "enum": [ + "owner", + "requester" + ] + } + }, + "required": [ + "node_id", + "question" + ], + "additionalProperties": false + }, + "annotations": { + "title": "Ask for input", + "readOnlyHint": false, + "destructiveHint": false, + "idempotentHint": false, + "openWorldHint": false + } + }, + { + "name": "handoff_answer", + "title": "Answer a hand-off", + "description": "Answer a question a node this bot handed off asked its requester.", + "inputSchema": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "pattern": "^w[0-9]{1,9}$" + }, + "answer": { + "type": "string", + "minLength": 1, + "maxLength": 4000 + } + }, + "required": [ + "node_id", + "answer" + ], + "additionalProperties": false + }, + "annotations": { + "title": "Answer a hand-off", + "readOnlyHint": false, + "destructiveHint": false, + "idempotentHint": false, + "openWorldHint": false + } + } + ] +} diff --git a/tests/test_work_tree.py b/tests/test_work_tree.py new file mode 100644 index 0000000..7f930dd --- /dev/null +++ b/tests/test_work_tree.py @@ -0,0 +1,568 @@ +import io +import json +import os +from pathlib import Path +import random +import sys +import tempfile +import unittest + +from adapters.memory_ledger import MemoryLedger +from adapters.work_tree import (MARK, REFUSALS, TERMINAL, HandoffDesk, HandoffPolicy, Refused, WorkTree, check_invariants, + load_policy, replay, witness_gaps) +from poodo_core import ContractError +from tests.aor_fixtures import HAVE_CRYPTO, NO_CRYPTO, golden_tools, write_fleet, write_witnessed_config + +ROOT = Path(__file__).resolve().parents[1] +GOLDEN = ROOT / "tests/fixtures/mcp_tools_list.json" +HANDOFF_GOLDEN = ROOT / "tests/fixtures/mcp_tools_list_handoff.json" +ROUTES = {"chief": ["worker-a", "worker-b", "reviewer", "archive"], "worker-a": ["worker-b", "reviewer", "chief"], + "worker-b": ["worker-c"], "worker-c": ["worker-d"], "reviewer": ["chief", "worker-a"]} +HOST_ONLY = ("hold", "release", "sweep", "continue_turn", "answer_owner", "enqueue") + + +def setUpModule(): + global McpServer, TOOLS, HANDOFF_TOOLS, build_aor_session + from adapters.mcp_stdio_server import HANDOFF_TOOLS, TOOLS, McpServer + from bootstrap import build_aor_session + + +def tearDownModule(): + sys.modules.pop("adapters.mcp_stdio_server", None) + + +def policy(**kw): + return HandoffPolicy(**{"reachable": ROUTES, **kw}) + + +class Scenario(unittest.TestCase): + def tree(self, path=None, **kw): + kw.setdefault("policy", policy()) + t = WorkTree(path, clock=lambda: 1000, **kw) + self.addCleanup(self.assert_sound, t) + return t + + def tmp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + return tmp.name + + def assert_sound(self, t): + self.assertEqual(check_invariants(t), []) + + def root(self, t, **kw): + args = dict(requester="owner", assignee="chief", domain="ops", brief="run the week", origin="owner", + owner_quote="run the week", owner_message_id="msg-1") + args.update(kw) + node = t.enqueue(**args) + t.start(node.id) + return node + + def child(self, t, parent, assignee, **kw): + return t.enqueue(parent_id=parent.id, requester=parent.assignee, assignee=assignee, + domain=kw.pop("domain", parent.domain), brief=kw.pop("brief", "part"), **kw) + + def refused(self, code, call, *args, **kw): + with self.assertRaises(Refused) as caught: + call(*args, **kw) + self.assertEqual(caught.exception.code, code) + return caught.exception + + +class WakeOnce(Scenario): + def test_a_waiting_requester_wakes_once_with_every_settled_child(self): + t = self.tree() + r = self.root(t) + a, b = self.child(t, r, "worker-a"), self.child(t, r, "worker-b") + t.wait(r.id) + for c in (a, b): + t.start(c.id) + t.settle(a.id, "completed", "done") + self.assertEqual(t.inbox("chief"), []) + t.settle(b.id, "failed", "no data") + [wake] = t.inbox("chief") + self.assertEqual((wake["kind"], wake["children"]), + ("woken", [{"id": a.id, "outcome": "completed"}, {"id": b.id, "outcome": "failed"}])) + self.assertEqual(t.node(r.id).status, "resume") + self.assertEqual(t.deliver("chief"), [wake]) + self.assertEqual(t.deliver("chief"), []) + + def test_poll_and_notify_children_do_not_hold_the_wake(self): + t = self.tree() + r = self.root(t) + a = self.child(t, r, "worker-a") + self.child(t, r, "worker-b", reply="poll") + self.child(t, r, "reviewer", mode="notify", reply="none") + t.wait(r.id) + t.start(a.id) + t.settle(a.id, "completed") + self.assertEqual([e["children"] for e in t.inbox("chief")], [[{"id": a.id, "outcome": "completed"}]]) + t.cancel(r.id, "done") + + def test_waiting_needs_an_open_child_that_replies(self): + t = self.tree() + r = self.root(t) + self.child(t, r, "worker-a", reply="poll") + self.refused("state", t.wait, r.id) + + def test_an_overdue_hand_off_chases_its_requester_once(self): + t = self.tree() + r = self.root(t) + c = self.child(t, r, "worker-a", chase_at=1500) + t.sweep(now=1400) + self.assertEqual(t.inbox("chief"), []) + t.sweep(now=1600) + t.sweep(now=1700) + self.assertEqual([(e["kind"], e["id"], e["status"]) for e in t.inbox("chief")], [("chased", c.id, "queued")]) + + +class Loops(Scenario): + def test_work_cannot_go_back_up_the_branch(self): + t = self.tree() + r = self.root(t) + c = self.child(t, r, "reviewer") + t.start(c.id) + self.refused("loop", self.child, t, c, "chief") + self.refused("loop", self.child, t, r, "chief") + + def test_depth_is_capped(self): + t = self.tree(policy=policy(max_depth=2)) + r = self.root(t) + a = self.child(t, r, "worker-a") + t.start(a.id) + b = self.child(t, a, "worker-b") + t.start(b.id) + self.refused("depth", self.child, t, b, "worker-c") + + def test_two_idle_continuations_fail_the_node(self): + t = self.tree() + r = self.root(t) + t.continue_turn(r.id, ok_tool_calls=0) + t.start(r.id) + t.continue_turn(r.id, ok_tool_calls=0) + self.assertEqual((t.node(r.id).status, t.node(r.id).result), + ("failed", "stalled: two continuations with no progress")) + + def test_progress_resets_the_loop_guard(self): + t = self.tree() + r = self.root(t) + t.continue_turn(r.id, ok_tool_calls=0) + t.start(r.id) + t.continue_turn(r.id, ok_tool_calls=3) + t.start(r.id) + t.continue_turn(r.id, ok_tool_calls=0) + self.assertEqual(t.node(r.id).status, "queued") + t.cancel(r.id, "done") + + def test_two_reviewers_that_would_loop_stop_at_the_guards(self): + t = self.tree() + r = self.root(t) + review = self.child(t, r, "reviewer", brief="review the draft") + t.start(review.id) + fix = self.child(t, review, "worker-a", brief="fix the finding") + t.start(fix.id) + self.refused("loop", self.child, t, fix, "reviewer", brief="review again") + t.settle(fix.id, "completed") + t.settle(review.id, "completed") + t.settle(r.id, "completed") + + +class Modes(Scenario): + def test_notify_takes_no_reply_and_consult_hands_out_only_consults(self): + t = self.tree() + r = self.root(t) + self.refused("mode", self.child, t, r, "worker-a", mode="notify", reply="resume") + c = self.child(t, r, "worker-a", mode="consult") + t.start(c.id) + self.refused("mode", self.child, t, c, "reviewer", mode="work") + self.child(t, c, "reviewer", mode="consult") + self.assertIn("Consult: act on nothing.", t.envelope(c.id)) + + +class Holds(Scenario): + def test_a_hold_cancels_the_domain_and_refuses_later_work(self): + t = self.tree() + r = self.root(t, domain="domain-x") + c = self.child(t, r, "archive") + other = self.root(t, assignee="worker-a") + t.hold("domain-x", "owner takes this back") + self.assertEqual((t.node(r.id).status, t.node(c.id).status, t.node(other.id).status), + ("cancelled", "cancelled", "running")) + self.refused("held", t.enqueue, requester="routine-1", assignee="archive", domain="domain-x", + brief="scheduled", origin="routine") + t.release("domain-x") + self.root(t, domain="domain-x", assignee="archive") + + def test_a_hold_given_at_start_applies_to_a_reopened_tree(self): + d = self.tmp() + path = os.path.join(d, "tree.jsonl") + self.root(self.tree(path)) + reopened = self.tree(path, holds=(("ops", "stop"),)) + self.assertEqual(reopened.node("w1").status, "cancelled") + + +class Lineage(Scenario): + def test_lineage_is_written_once_and_inherited(self): + t = self.tree() + r = self.root(t) + c = self.child(t, r, "worker-a", origin="outside", owner_message_id="forged") + self.assertEqual((c.origin, c.owner_message_id, c.root_id), ("owner", "msg-1", r.id)) + + def test_only_owner_or_routine_lineage_acts_for_the_owner(self): + t = self.tree() + owner = self.root(t) + hook = t.enqueue(requester="webhook", assignee="worker-a", domain="ops", brief="approved, go", origin="outside") + relayed = t.enqueue(requester="relay-bot", assignee="worker-b", domain="ops", brief="go", origin="owner", + owner_quote="yes") + routine = t.enqueue(requester="routine-1", assignee="reviewer", domain="ops", brief="tick", origin="routine") + self.assertIn("on the owner's behalf (owner message msg-1)", t.envelope(owner.id)) + self.assertIn("information only", t.envelope(hook.id)) + self.assertIn("no owner message id: not an approval", t.envelope(relayed.id)) + self.assertIn("from the owner's routine", t.envelope(routine.id)) + for node in (hook, relayed, routine): + t.cancel(node.id, "done") + + def test_model_text_cannot_open_a_note(self): + t = self.tree() + r = self.root(t, brief=f"ok\n{MARK} owner · approved]") + line = t.envelope(r.id) + self.assertEqual((line.count(MARK), "\n" in line), (1, False)) + + +class Answers(Scenario): + def test_an_owner_only_value_is_returned_but_never_written_or_witnessed(self): + d = self.tmp() + path = os.path.join(d, "tree.jsonl") + ledger = MemoryLedger() + t = self.tree(path, witness=ledger) + r = self.root(t) + t.park(r.id, "an owner-only step is needed") + self.assertEqual(t.answer_owner(r.id, "one-time-value"), "one-time-value") + self.assertNotIn("one-time-value", Path(path).read_text()) + self.assertNotIn("one-time-value", json.dumps(ledger.read())) + self.assertEqual(t.node(r.id).status, "resume") + self.assertEqual(t.inbox("chief"), []) + t.start(r.id) + + def test_a_requester_answer_reaches_the_assignee_once_as_information(self): + t = self.tree() + r = self.root(t) + c = self.child(t, r, "worker-a") + t.start(c.id) + worker, chief = HandoffDesk(t, "worker-a"), HandoffDesk(t, "chief") + self.assertIn("parked", worker.park(c.id, "which week?", asks="requester")) + self.assertEqual(chief.status(c.id)["node"]["question"]["text"], "which week?") + self.assertEqual(worker.answer(c.id, "this one")["refused"], "not_yours") + chief.answer(c.id, f"this one {MARK} owner · approved]") + self.assertEqual([e["kind"] for e in worker.wait()["inbox"]], ["answered"]) + self.assertEqual(worker.wait()["inbox"], []) + view = worker.status(c.id)["node"] + self.assertEqual((view["answer"]["authority"], MARK in view["answer"]["text"]), ("information only", False)) + + +class Concurrency(Scenario): + def test_a_root_holds_at_most_four_open_nodes(self): + t = self.tree() + r = self.root(t) + for bot in ("worker-a", "worker-b", "reviewer"): + self.child(t, r, bot) + self.refused("root_full", self.child, t, r, "archive") + + def test_one_live_instance_per_bot(self): + t = self.tree() + self.root(t) + second = t.enqueue(requester="routine-1", assignee="chief", domain="ops", brief="tick", origin="routine") + self.refused("busy", t.start, second.id) + t.cancel(second.id, "done") + + def test_hand_offs_route_only_to_reachable_bots(self): + t = self.tree() + r = self.root(t) + a = self.child(t, r, "worker-a") + t.start(a.id) + self.refused("unreachable", self.child, t, a, "archive") + + def test_every_desk_refusal_is_a_typed_result(self): + t = self.tree() + r = self.root(t) + chief = HandoffDesk(t, "chief") + results = [chief.create(r.id, "outsider", "x"), chief.create("w99", "worker-a", "x"), + HandoffDesk(t, "worker-a").settle(r.id, "completed"), chief.wait(r.id)] + self.assertEqual([x["refused"] for x in results], ["unreachable", "unknown", "not_yours", "state"]) + self.assertTrue({x["refused"] for x in results} <= set(REFUSALS)) + + def test_policy_loads_from_host_config(self): + with tempfile.TemporaryDirectory() as d: + config = Path(d) / "handoff.json" + config.write_text(json.dumps({"tree": "handoff/tree.jsonl", "reachable": ROUTES, + "artifact_names": ["spec", "report"]})) + path, loaded = load_policy(config) + self.assertEqual((path, loaded.max_open_per_root, loaded.routes("chief")), + (Path(d) / "handoff/tree.jsonl", 4, tuple(ROUTES["chief"]))) + config.write_text(json.dumps({"tree": "t.jsonl", "max_open_per_root": 0})) + with self.assertRaises(ContractError): + load_policy(config) + + def test_artifacts_follow_the_host_table(self): + t = self.tree(policy=policy(artifact_names=("spec",))) + r = self.root(t) + c = self.child(t, r, "worker-a", artifacts=[{"name": "spec", "ref": "docs/spec.md"}]) + self.assertEqual(c.artifacts, [{"name": "spec", "ref": "docs/spec.md"}]) + self.refused("artifact", self.child, t, r, "worker-b", artifacts=[{"name": "secrets", "ref": "x"}]) + + +class Durability(Scenario): + def test_a_reopened_tree_equals_the_one_that_wrote_it(self): + d = self.tmp() + path = os.path.join(d, "state", "tree.jsonl") + t = self.tree(path) + r = self.root(t) + c = self.child(t, r, "worker-a") + t.wait(r.id) + t.start(c.id) + t.settle(c.id, "completed", "ok", {"outward": ["outward-action"]}) + again = self.tree(path) + self.assertEqual((again.nodes, again.holds, again.events), (t.nodes, t.holds, t.events)) + self.assertEqual(os.stat(path).st_mode & 0o777, 0o600) + + def test_two_hosts_on_one_file_see_each_others_events(self): + d = self.tmp() + path = os.path.join(d, "tree.jsonl") + first, second = self.tree(path), self.tree(path) + r = self.root(first) + c = self.child(second, second.node(r.id), "worker-a") + self.assertEqual(first.node(c.id).parent_id, r.id) + HandoffDesk(second, "worker-a").start(c.id) + self.assertEqual(first.node(c.id).status, "running") + self.assertEqual([e["seq"] for e in first.events], list(range(1, len(first.events) + 1))) + + def test_a_torn_last_line_is_set_aside(self): + d = self.tmp() + path = os.path.join(d, "tree.jsonl") + self.root(self.tree(path)) + with open(path, "ab") as handle: + handle.write(b'{"seq": 3, "kind": "sta') + again = self.tree(path) + self.assertEqual(again.node("w1").status, "running") + self.assertEqual(len([n for n in os.listdir(d) if ".torn-" in n]), 1) + again.cancel("w1", "done") + self.assertEqual(self.tree(path).node("w1").status, "cancelled") + + def test_an_event_out_of_order_is_refused(self): + t = self.tree() + self.root(t) + with self.assertRaisesRegex(ContractError, "out of order"): + replay([t.events[1]]) + + def test_replay_detects_a_tree_that_drifted_from_its_events(self): + t = WorkTree(policy=policy(), clock=lambda: 1000) + r = self.root(t) + t.nodes[r.id] = t.nodes[r.id].__class__(**{**vars(t.nodes[r.id]), "status": "completed", + "outcome": "completed"}) + self.assertIn("I7 the tree differs from its events", check_invariants(t)) + self.assertEqual(replay(t.events).node(r.id).status, "running") + + +class FailingLedger(MemoryLedger): + def append(self, kind, data): + raise OSError("disk full") + + +class Witness(Scenario): + def test_every_event_is_witnessed_in_order(self): + ledger = MemoryLedger() + t = self.tree(witness=ledger) + r = self.root(t) + c = self.child(t, r, "worker-a") + t.wait(r.id) + t.start(c.id) + t.settle(c.id, "completed") + t.hold("ops", "stop") + self.assertEqual(witness_gaps(t, ledger.read()), []) + self.assertEqual({e["kind"] for e in ledger.read()}, {"observation"}) + self.assertEqual([e["data"]["work_tree"]["kind"] for e in ledger.read()][:3], ["enqueued", "status", "enqueued"]) + + def test_a_ledger_out_of_budget_refuses_before_anything_changes(self): + t = self.tree(witness=MemoryLedger(max_events=1)) + r = t.enqueue(requester="owner", assignee="worker-a", domain="ops", brief="x", origin="owner") + with self.assertRaisesRegex(ContractError, "budget"): + t.start(r.id) + self.assertEqual((len(t.events), t.node(r.id).status), (1, "queued")) + + def test_a_failed_witness_is_reported_and_detectable(self): + t = self.tree(witness=FailingLedger()) + r = t.enqueue(requester="owner", assignee="chief", domain="ops", brief="x", origin="owner") + self.assertEqual(len(t.witness_warnings), 1) + self.assertEqual(witness_gaps(t, []), [1]) + self.assertIn("witness_warnings", HandoffDesk(t, "chief").start(r.id)) + t.cancel(r.id, "done") + + +class RandomWalk(Scenario): + def test_random_desk_traffic_keeps_every_invariant(self): + bots = ("chief", "worker-a", "worker-b", "reviewer", "archive") + for seed in range(12): + rng = random.Random(seed) + t = WorkTree(policy=policy(), clock=lambda: 1000, witness=MemoryLedger(max_events=100_000)) + desks = {b: HandoffDesk(t, b) for b in bots} + outcomes = {} + self.root(t) + for _ in range(3): + t.enqueue(requester="routine-1", assignee="chief", domain="ops", brief="tick", origin="routine") + for step in range(250): + busy = [n.assignee for n in t.nodes.values() if n.status not in TERMINAL] + bot = rng.choice(busy) if busy and rng.random() < 0.85 else rng.choice(bots) + desk = desks[bot] + mine = [n.id for n in t.nodes.values() if bot in (n.assignee, n.requester)] + nid = rng.choice(mine) if mine and rng.random() < 0.9 else rng.choice(list(t.nodes)) + op = rng.randrange(10) + if op == 0: + desk.create(nid, rng.choice([*ROUTES.get(bot, ()), "chief", "outsider"]), "part", reply=rng.choice(["resume", "poll"]), + chase_after=rng.choice([None, 60])) + elif op == 1: + desk.start(nid) + elif op == 2: + ready = [n.id for n in t.nodes.values() if n.assignee == bot and n.status == "running" + and any(c.parent_id == n.id and c.status not in TERMINAL for c in t.nodes.values())] + desk.wait(rng.choice(ready) if ready else None) + elif op == 3: + desk.settle(nid, rng.choice(["completed", "failed", "cancelled"]), "r") + elif op == 4: + desk.park(nid, "q", asks=rng.choice(["owner", "requester"])) + elif op == 5: + desk.answer(nid, "a") + elif op == 6 and t.nodes[nid].asks == "owner": + t.answer_owner(nid, "v") + elif op == 7: + t.sweep(now=rng.randrange(2000)) + elif op == 8 and ("ops" in t.holds or rng.random() < 0.05): + t.hold("ops", "stop") if "ops" not in t.holds else t.release("ops") + elif op == 9 and "ops" not in t.holds and sum(n.parent_id is None and n.status not in TERMINAL + for n in t.nodes.values()) < 3: + t.enqueue(requester="routine-1", assignee=rng.choice(bots), domain="ops", brief="tick", + origin="routine") + outcomes[op] = outcomes.get(op, 0) + 1 + problems = check_invariants(t) + self.assertEqual(problems, [], f"seed {seed} step {step}") + self.assertEqual(witness_gaps(t, t._witness.read()), []) + for n in [n for n in t.nodes.values() if n.parent_id is None]: + t.cancel(n.id, "end of walk") + self.assertEqual(check_invariants(t, final=True), [], f"seed {seed}") + + +def frames(*messages): + return io.BytesIO(b"".join(json.dumps(m).encode() + b"\n" for m in messages)) + + +class Mcp(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.dir = Path(tmp.name) + self.state = self.dir / "aor" + self.state.mkdir() + self.fleet = write_fleet(self.dir) + + def configure(self, **kw): + (self.state / "handoff.json").write_text(json.dumps( + {"tree": "handoff/tree.jsonl", "reachable": {"alpha": ["beta"], "beta": []}, **kw})) + + def session(self, slug): + session = build_aor_session(slug, state_root=self.state, hostname="testbox", fleet_path=self.fleet, + enforce=False) + self.addCleanup(session.close) + return session + + def server(self, session): + server = McpServer(session) + server.handle({"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {}}) + + def call(name, **arguments): + reply = server.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": name, "arguments": arguments}}) + return reply["result"]["isError"], reply["result"]["structuredContent"] + return server, call + + def tools(self, session): + out = io.StringIO() + McpServer(session).serve(frames({"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {}}, + {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}), out) + return json.loads(out.getvalue().splitlines()[1])["result"]["tools"] + + def test_tools_are_listed_only_with_host_config_and_match_the_golden_schema(self): + base = golden_tools(GOLDEN) + self.assertEqual(self.tools(self.session("alpha")), base) + self.configure() + listed = self.tools(self.session("beta")) + self.assertEqual(listed, base + json.loads(HANDOFF_GOLDEN.read_text())["tools"]) + names = [t["name"] for t in listed if t["name"].startswith("handoff_")] + self.assertEqual(names, ["handoff_create", "handoff_start", "handoff_status", "handoff_wait", + "handoff_settle", "handoff_park", "handoff_answer"]) + self.assertFalse([n for n in names if n.removeprefix("handoff_") in HOST_ONLY]) + for tool in HANDOFF_TOOLS: + self.assertNotIn("requester", tool["inputSchema"]["properties"]) + self.assertNotIn("origin", tool["inputSchema"]["properties"]) + + def test_a_hand_off_round_trip_between_two_bots(self): + self.configure() + alpha, beta = self.session("alpha"), self.session("beta") + tree = alpha.handoff._tree + root = tree.enqueue(requester="owner", assignee="alpha", domain="ops", brief="ship it", origin="owner", + owner_quote="ship it", owner_message_id="msg-7") + _, a = self.server(alpha) + _, b = self.server(beta) + self.assertEqual(a("handoff_start", node_id=root.id)[0], False) + error, created = a("handoff_create", node_id=root.id, assignee="beta", brief="write the notes", + artifacts=[{"name": "notes", "ref": "docs/notes.md"}], chase_after=600) + self.assertFalse(error) + child = created["created"]["id"] + self.assertEqual(a("handoff_wait", node_id=root.id)[1]["inbox"], []) + error, polled = b("handoff_wait") + self.assertEqual([n["id"] for n in polled["assigned"]], [child]) + self.assertIn("on the owner's behalf (owner message msg-7)", polled["assigned"][0]["envelope"]) + b("handoff_start", node_id=child) + error, settled = b("handoff_settle", node_id=child, outcome="completed", result="notes written") + self.assertFalse(error) + error, woke = a("handoff_wait") + self.assertEqual(woke["inbox"], [{"seq": woke["inbox"][0]["seq"], "kind": "woken", "id": root.id, + "children": [{"id": child, "outcome": "completed"}]}]) + self.assertEqual(a("handoff_status", node_id=root.id)[1]["children"][0]["result"]["text"], "notes written") + a("handoff_start", node_id=root.id) + a("handoff_settle", node_id=root.id, outcome="completed", result="shipped") + self.assertEqual(check_invariants(tree, final=True), []) + + def test_refusals_are_typed_tool_errors_and_the_requester_is_never_an_argument(self): + self.configure() + alpha = self.session("alpha") + root = alpha.handoff._tree.enqueue(requester="owner", assignee="alpha", domain="ops", brief="x", + origin="owner") + _, a = self.server(alpha) + a("handoff_start", node_id=root.id) + self.assertEqual(a("handoff_create", node_id=root.id, assignee="gamma", brief="x"), + (True, {"refused": "unreachable", "reason": "alpha may hand off only to ['beta']"})) + self.assertTrue(a("handoff_create", node_id=root.id, assignee="beta", brief="x", requester="owner")[0]) + (self.state / "SHIELDS_UP").touch() + self.assertEqual(a("handoff_create", node_id=root.id, assignee="beta", brief="x")[1]["refused"], "shields") + + @unittest.skipUnless(HAVE_CRYPTO, NO_CRYPTO) + def test_witnessed_hosts_log_every_node_event_to_the_ledger(self): + log = write_witnessed_config(self.state, bots=("alpha", "beta")) + self.configure() + alpha, beta = self.session("alpha"), self.session("beta") + root = alpha.handoff._tree.enqueue(requester="owner", assignee="alpha", domain="ops", brief="x", + origin="owner") + alpha.handoff.start(root.id) + child = alpha.handoff.create(root.id, "beta", "part")["created"]["id"] + beta.handoff.start(child) + beta.handoff.settle(child, "completed", "done") + witnessed = alpha.handoff._tree._witness.read() + beta.handoff._tree._witness.read() + self.assertEqual(witness_gaps(alpha.handoff._tree, witnessed), []) + self.assertEqual({e["data"]["work_tree"]["kind"] for e in beta.handoff._tree._witness.read()}, + {"status", "reported"}) + text = log.read_text() + self.assertIn('"stream":"alpha.handoff"', text.replace(" ", "")) + self.assertIn('"stream":"beta.handoff"', text.replace(" ", "")) + + +if __name__ == "__main__": + unittest.main()