agents-relay 1.0.4 → 1.0.5

package/skills/chatgpt-browser-worker/references/orchestration.md

@@ -0,0 +1,101 @@
+# Neo/Leo orchestration integration
+
+This skill is a worker capability, not an orchestrator or a browser session
+manager. The `browser-worker` agent owns adaptive browser execution. Agents
+Relay (or Leo's owning orchestrator) owns the task, correlation ID, retries,
+events, and durable run location. The worker owns one ChatGPT thread state
+record. `browser-harness` is the only layer that touches the authenticated
+browser.
+
+## Responsibility split
+
+| Layer | Responsibility | Must not do |
+| --- | --- | --- |
+| Agents Relay / Leo | Create the child task, pass the exact `job_id` and `task_id`, consume lifecycle events, and reconcile terminal state | Select DOM elements, infer a thread from a tab, or replace a deleted thread |
+| Browser-worker agent | Load both skills, execute typed lifecycle intents, adapt to ordinary UI drift by re-observing, preserve `thread_id`/Project identity, and return verified observations | Bypass authentication, MFA, consent, ambiguity, or unverifiable results |
+| This skill | Validate requests, preserve `thread_id` state, enforce Project and status transitions, and normalize observed results | Launch a second browser stack, call a ChatGPT API, or depend on MacBridge as a ChatGPT runtime |
+| `browser-harness` adapter | Perform the observable browser actions and return semantic observations | Persist orchestration state, invent success from a process exit, or hide authentication/ambiguity failures |
+
+MacBridge may be the transport used by an outer Leo deployment to start a
+worker, but it is not part of this ChatGPT runtime path. A local worker can
+invoke `browser-harness` directly. No MacBridge ChatGPT MCP tool, copied
+cookie, or ChatGPT API is required.
+
+## Task handoff
+
+The parent creates one child task with the same `job_id` and a task-specific
+`task_id` (nested work also receives `parent_task_id`). The task input contains
+an operation request and a run-local state path; it does not contain browser
+credentials or cookies:
+
+```json
+{
+  "job_id": "neo-chatgpt-browser-worker-20260919",
+  "task_id": "chatgpt-thread-1",
+  "operation": "create",
+  "state_path": "runs/2026-09-19-chatgpt-thread/state.json",
+  "request": {
+    "project": {"name": "neo"},
+    "prompt": "Run the assigned task.",
+    "thinking_level": "high"
+  }
+}
+```
+
+The exact literal IDs must be present in both the worker environment and its
+prompt. Runtime state, prompts containing private data, logs, and browser
+session details stay under the caller's ignored `runs/` directory.
+
+## Lifecycle invocation
+
+The orchestrator launches the `browser-worker` agent with one serial typed
+operation at a time and persists the returned state before acknowledging
+success. It must not directly invoke `create_bh.py` or `operate_bh.py`; those
+are agent implementation helpers. The durable identity is always the
+`thread_id` in `state.json`, never a URL, title, or tab index.
+
+| Intent | Request | Browser-port calls | Success evidence |
+| --- | --- | --- | --- |
+| Start | `create` with `project`, `prompt`, `thinking_level` | `select_project` → optional `set_thinking_level` → `send_prompt` | observed non-empty `thread_id` and Project |
+| Reattach | `resume` with `thread_id`, `project` | `open_thread` and Project verification | opened matching thread and Project |
+| Fetch | `result` with the durable state | `read_result` | normalized assistant message with `message_id` |
+| Clean up | `delete` with the durable state | exact-thread delete plus confirmation | verified `deleted` or idempotent `not_found` |
+
+`status` is the optional polling operation between `resume` and `result`.
+`continue` is a follow-up prompt operation and is not a substitute for
+`resume`. A retry resumes the existing state; it never calls `create` for a
+missing or failed browser action. A `deleted` tombstone is terminal.
+
+The pure entry points are `create_thread`, `resume_thread`, `result_thread`,
+and `delete_thread` in `scripts/create.py` and `scripts/operations.py`. The
+`*_bh.py` scripts are thin helpers the agent may call or replace while running
+one operation through `browser-harness`; they are not an alternate state store,
+orchestrator, or caller-facing runtime.
+
+## Events and terminal handling
+
+The owning orchestrator emits `task.started`, meaningful milestones, and one
+terminal task event using the shared events-bus contract. A worker should
+report routine success as `task.completed` with `visibility: orchestrator`;
+the parent then reconciles the state file and emits the user-visible result.
+Failures involving login, MFA, consent, ambiguous Project selection, or an
+unverified result are `task.failed` or `task.blocked`, not successful relay
+completion. Event payloads contain IDs, statuses, and evidence summaries—not
+credentials, cookies, or full private prompts.
+
+## Minimal relay loop
+
+```text
+watch(job_id)
+launch child with job_id/task_id and operation=create
+persist returned thread state
+resume(thread_id, project) when reattaching
+repeat status(thread_id) until the UI permits a result
+result(thread_id) and validate the normalized assistant message
+delete(thread_id) in the explicit cleanup phase
+consume events until the parent task reaches one terminal state
+```
+
+The browser adapter may fail after a thread has been created. In that case,
+preserve the last known `thread_id` and state, classify the transition as
+`failed` or `blocked`, and let the orchestrator decide when to retry `resume`.

package/skills/chatgpt-browser-worker/scripts/_create_bh.py

@@ -0,0 +1,158 @@
+import json
+import re
+import time
+
+from browser_harness import *
+
+
+CFG = json.load(open("__CFG_PATH__", encoding="utf-8"))
+
+
+def _ax_nodes():
+    return cdp("Accessibility.getFullAXTree").get("nodes", [])
+
+
+def _click_exact(name, roles=()):
+    matches = [node for node in _ax_nodes() if node.get("name", {}).get("value") == name and (not roles or node.get("role", {}).get("value") in roles)]
+    if len(matches) != 1:
+        raise RuntimeError(f"expected one accessible {name!r}, found {len(matches)}")
+    backend_id = matches[0].get("backendDOMNodeId")
+    box = cdp("DOM.getBoxModel", backendNodeId=backend_id).get("model", {}).get("content")
+    if not box:
+        raise RuntimeError(f"accessible {name!r} has no visible box")
+    click_at_xy(sum(box[0::2]) / 4, sum(box[1::2]) / 4)
+    return {"name": name, "role": matches[0].get("role", {}).get("value")}
+
+
+def _click_if_present(name, roles=()):
+    matches = [node for node in _ax_nodes() if node.get("name", {}).get("value") == name and (not roles or node.get("role", {}).get("value") in roles)]
+    if len(matches) > 1:
+        raise RuntimeError(f"ambiguous accessible {name!r}: found {len(matches)}")
+    if matches:
+        return _click_exact(name, roles)
+    return None
+
+
+def _find_composer():
+    selector = js("""(() => {
+      const candidates = [...document.querySelectorAll('textarea,[contenteditable="true"]')];
+      const node = candidates.find(e => {
+        const r = e.getBoundingClientRect();
+        return r.width > 0 && r.height > 0 && !e.disabled;
+      });
+      if (!node) return null;
+      if (node.id) return '#' + CSS.escape(node.id);
+      node.setAttribute('data-agents-relay-composer', 'true');
+      return '[data-agents-relay-composer="true"]';
+    })()""")
+    if not selector:
+        raise RuntimeError("ChatGPT composer was not observed")
+    return selector
+
+
+def _thread_id(existing_hrefs, timeout=20.0):
+    deadline = time.time() + timeout
+    existing_ids = set()
+    for href in existing_hrefs or []:
+        match = re.search(r"/c/([^/?#]+)", href or "")
+        if match:
+            existing_ids.add(match.group(1))
+    while time.time() < deadline:
+        match = re.search(r"/c/([^/?#]+)", page_info().get("url", ""))
+        if match:
+            return match.group(1)
+        links = js("""(() => [...document.querySelectorAll('a[href*="/g/"][href*="/c/"]')].map(a => ({href:a.href,text:(a.textContent||'').trim()})))()""") or []
+        prompt_hint = (CFG.get("prompt") or "").strip()[:60]
+        matching = []
+        for link in links:
+            href = link.get("href") or ""
+            link_match = re.search(r"/c/([^/?#]+)", href)
+            if link_match and prompt_hint and prompt_hint in (link.get("text") or ""):
+                matching.append(link_match.group(1))
+        unique_matching = list(dict.fromkeys(matching))
+        if len(unique_matching) == 1:
+            return unique_matching[0]
+        if len(unique_matching) > 1:
+            new_matching = [value for value in unique_matching if value not in existing_ids]
+            if len(new_matching) == 1:
+                return new_matching[0]
+            raise RuntimeError("multiple prompt-matching durable thread ids were observed after submission")
+        time.sleep(0.25)
+    raise RuntimeError("ChatGPT did not expose a new durable thread id before timeout")
+
+
+ensure_real_tab()
+if "chatgpt.com" not in page_info().get("url", ""):
+    new_tab("https://chatgpt.com/")
+    wait_for_load()
+project = CFG["project"]
+selected = {"name": project["name"], "action": "default_chat"}
+if project["name"].casefold() not in ("unspecified", "default"):
+    # Project rows expose a generic "Open project home" action, so bind that
+    # action to the visible row whose marquee text exactly matches the requested
+    # Project. This avoids relying on the project label itself being clickable.
+    opened_project = js("""(() => {
+      const wanted = %s;
+      const labels = [...document.querySelectorAll('[data-marquee-text]')].filter(e => (e.textContent || '').trim() === wanted);
+      for (const label of labels) {
+        const button = label.closest('li')?.querySelector('button[aria-label="Open project home"]');
+        if (!button) continue;
+        const r = button.getBoundingClientRect();
+        if (r.width > 0 && r.height > 0 && r.bottom > 0 && r.top < innerHeight) { button.click(); return true; }
+      }
+      return false;
+    })()""" % json.dumps(project["name"]))
+    if not opened_project:
+        raise RuntimeError(f"requested Project {project['name']!r} has no visible project-home action")
+    deadline = time.time() + 8
+    visible = ""
+    while time.time() < deadline:
+        info = page_info()
+        visible = js("document.body.innerText") or ""
+        if project["name"].casefold() in visible.casefold() and project["name"].casefold() in info.get("title", "").casefold() and "/project" in info.get("url", ""):
+            break
+        time.sleep(0.25)
+    else:
+        raise RuntimeError("requested Project home was not observed after navigation")
+    selected = {"name": project["name"], "action": "Open project home"}
+
+thinking = {"requested": CFG["thinking_level"], "effective_thinking_level": "unknown", "changed": False}
+if CFG["thinking_level"] != "default":
+    label = {"low": "Low", "medium": "Medium", "high": "High"}[CFG["thinking_level"]]
+    level_buttons = []
+    deadline = time.time() + 5
+    while time.time() < deadline and len(level_buttons) != 1:
+        level_buttons = [node for node in _ax_nodes() if node.get("role", {}).get("value") == "button" and node.get("name", {}).get("value") in ("Low", "Medium", "High")]
+        if len(level_buttons) != 1:
+            time.sleep(0.25)
+    if len(level_buttons) == 1:
+        current = level_buttons[0].get("name", {}).get("value")
+        if current != label:
+            _click_exact(current, roles=("button",))
+            time.sleep(0.25)
+            try:
+                _click_exact(label, roles=("button", "menuitem", "option"))
+                thinking = {"requested": CFG["thinking_level"], "effective_thinking_level": CFG["thinking_level"], "changed": True}
+            except RuntimeError:
+                thinking = {"requested": CFG["thinking_level"], "effective_thinking_level": "unknown", "changed": False}
+        else:
+            thinking = {"requested": CFG["thinking_level"], "effective_thinking_level": CFG["thinking_level"], "changed": False}
+
+existing_hrefs = js("""(() => [...document.querySelectorAll('a[href*="/g/"][href*="/c/"]')].map(a => a.href))()""") or []
+composer = _find_composer()
+fill_input(composer, CFG["prompt"], clear_first=True)
+deadline = time.time() + 5
+sent = False
+while time.time() < deadline:
+    sent = bool(js("""(() => { const button = document.querySelector('button[data-testid="send-button"],button[aria-label="Send prompt"]'); if (!button) return false; const r=button.getBoundingClientRect(); if (!(r.width > 0 && r.height > 0)) return false; button.click(); return true; })()"""))
+    if sent: break
+    time.sleep(0.1)
+if not sent: raise RuntimeError("ChatGPT Send prompt button was not observed after filling composer")
+thread_id = _thread_id(existing_hrefs)
+print(json.dumps({
+    "thread_id": thread_id,
+    "conversation_url": page_info().get("url"),
+    "selected_project": selected,
+    "thinking": thinking,
+    "prompt_sent": True,
+}, ensure_ascii=False))

package/skills/chatgpt-browser-worker/scripts/_operate_bh.py

@@ -0,0 +1,198 @@
+import json
+import time
+
+from browser_harness import *
+
+
+CFG = json.load(open("__CFG_PATH__", encoding="utf-8"))
+THREAD_ID = CFG["thread_id"]
+
+
+def _ax_nodes():
+    return cdp("Accessibility.getFullAXTree").get("nodes", [])
+
+
+def _composer():
+    selector = js("""(() => {
+      const nodes = [...document.querySelectorAll('textarea,[contenteditable="true"]')];
+      const node = nodes.find(e => { const r = e.getBoundingClientRect(); return r.width && r.height && !e.disabled; });
+      if (!node) return null;
+      if (node.id) return '#' + CSS.escape(node.id);
+      if (node.getAttribute('aria-label')) return `${node.tagName.toLowerCase()}[aria-label=${JSON.stringify(node.getAttribute('aria-label'))}]`;
+      return node.tagName === 'TEXTAREA' ? 'textarea' : 'div[contenteditable="true"]';
+    })()""")
+    if not selector:
+        raise RuntimeError("ChatGPT composer was not observed")
+    return selector
+
+
+def _assistant_messages():
+    return js("""(() => [...document.querySelectorAll('[data-message-author-role="assistant"]')]
+      .map(e => ({text: e.innerText.trim(), id: e.getAttribute('data-message-id') || ''}))
+      .filter(e => e.text))()""") or []
+
+
+def _is_generating():
+    return bool(js('!!document.querySelector(\'button[aria-label*="Stop" i],button[data-testid*="stop" i]\')'))
+
+
+def _click_accessible(name, prefer_rightmost=False):
+    visible = []
+    info = page_info()
+    for node in _ax_nodes():
+        if node.get("name", {}).get("value") != name:
+            continue
+        backend_id = node.get("backendDOMNodeId")
+        if not backend_id:
+            continue
+        try:
+            box = cdp("DOM.getBoxModel", backendNodeId=backend_id).get("model", {}).get("content")
+        except Exception:
+            continue
+        if not box:
+            continue
+        x, y = sum(box[0::2]) / 4, sum(box[1::2]) / 4
+        if 0 <= x <= info.get("w", 0) and 0 <= y <= info.get("h", 0):
+            visible.append((x, y))
+    if not visible:
+        raise RuntimeError(f"expected a visible accessible {name!r}, found 0")
+    if len(visible) > 1 and not prefer_rightmost:
+        raise RuntimeError(f"expected one visible accessible {name!r}, found {len(visible)}")
+    click_at_xy(*(max(visible, key=lambda point: point[0]) if prefer_rightmost else visible[0]))
+
+
+def _stable_assistant_result(delay=0.75):
+    if _is_generating():
+        return None
+    first = _assistant_messages()
+    if not first:
+        return None
+    candidate = first[-1]
+    time.sleep(delay)
+    if _is_generating():
+        return None
+    second = _assistant_messages()
+    if not second:
+        return None
+    latest = second[-1]
+    if latest.get("id") != candidate.get("id") or latest.get("text") != candidate.get("text"):
+        return None
+    return latest
+
+
+
+def _wait_stable_assistant_result(timeout=15.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        message = _stable_assistant_result(delay=0.5)
+        if message:
+            return message
+        time.sleep(0.25)
+    return None
+
+
+def _wait_for_requested_thread(timeout=12.0):
+    deadline = time.time() + timeout
+    last_url = ""
+    while time.time() < deadline:
+        info = page_info()
+        last_url = info.get("url", "")
+        body = js("document.body.innerText") or ""
+        title = info.get("title", "")
+        if f"/c/{THREAD_ID}" in last_url and (CFG["project"].casefold() in body.casefold() or CFG["project"].casefold() in title.casefold()):
+            return body
+        time.sleep(0.25)
+    raise RuntimeError(f"requested Project/thread was not observed after navigation: {last_url}")
+
+def _cleanup():
+    """Delete exactly the requested durable thread and verify disappearance."""
+    url = page_info().get("url", "")
+    if f"/c/{THREAD_ID}" not in url:
+        raise RuntimeError("browser is not on the requested durable thread")
+    body = js("document.body.innerText") or ""
+    if CFG["project"].casefold() not in body.casefold() and CFG["project"].casefold() not in page_info().get("title", "").casefold():
+        lower_body = body.lower()
+        missing_markers = ("conversation not found", "conversation doesn't exist", "conversation does not exist", "page not found")
+        if any(marker in lower_body for marker in missing_markers):
+            return {"thread_id": THREAD_ID, "outcome": "not_found", "verified": True, "url_after": url, "reason": "thread was not observable"}
+        raise RuntimeError("requested thread could not be verified; refusing cleanup")
+
+    opened = js("""(() => {
+      const buttons = [...document.querySelectorAll('button[aria-label="More"]')].filter(button => {
+        const r = button.getBoundingClientRect();
+        return r.width > 0 && r.height > 0 && r.top >= 0 && r.bottom <= innerHeight;
+      });
+      if (buttons.length !== 1) return false;
+      buttons[0].click();
+      return true;
+    })()""")
+    if not opened:
+        raise RuntimeError("thread actions menu was not uniquely observed")
+    time.sleep(0.2)
+    selected = js("""(() => {
+      const items = [...document.querySelectorAll('[role="menuitem"]')].filter(item => (item.textContent || '').trim() === 'Delete');
+      if (items.length !== 1) return false;
+      items[0].click();
+      return true;
+    })()""")
+    if not selected:
+        raise RuntimeError("ChatGPT delete action was not uniquely observed")
+
+    deadline = time.time() + 5
+    confirmed = False
+    while time.time() < deadline:
+        confirmed = bool(js("""(() => {
+          const dialogs = [...document.querySelectorAll('[role="dialog"]')].filter(dialog => (dialog.textContent || '').includes('Delete chat?'));
+          if (dialogs.length !== 1) return false;
+          const buttons = [...dialogs[0].querySelectorAll('button')].filter(button => (button.textContent || '').trim() === 'Delete');
+          if (buttons.length !== 1) return false;
+          buttons[0].click();
+          return true;
+        })()"""))
+        if confirmed:
+            break
+        time.sleep(0.2)
+    if not confirmed:
+        raise RuntimeError("ChatGPT delete confirmation was not observed")
+
+    deadline = time.time() + 8
+    while time.time() < deadline:
+        after_url = page_info().get("url", "")
+        after_body = js("document.body.innerText") or ""
+        if f"/c/{THREAD_ID}" not in after_url or "Undo" in after_body:
+            return {"thread_id": THREAD_ID, "outcome": "deleted", "verified": True, "url_after": after_url, "undo_visible": "Undo" in after_body, "archive_visible": "Archive" in after_body}
+        time.sleep(0.25)
+    raise RuntimeError("requested thread is still observable after delete")
+
+
+ensure_real_tab()
+target = f"https://chatgpt.com/c/{THREAD_ID}"
+if f"/c/{THREAD_ID}" not in page_info().get("url", ""):
+    new_tab(target)
+    wait_for_load()
+body = _wait_for_requested_thread()
+operation = CFG["operation"]
+if operation == "delete":
+    print(json.dumps(_cleanup(), ensure_ascii=False))
+    raise SystemExit
+
+base = {"thread_id": THREAD_ID, "conversation_url": page_info().get("url"), "project": {"name": CFG["project"]}}
+if operation == "continue":
+    fill_input(_composer(), CFG["prompt"], clear_first=True)
+    time.sleep(0.1)
+    _click_accessible("Send prompt")
+    print(json.dumps({**base, "prompt_sent": True}, ensure_ascii=False))
+elif operation == "status":
+    messages = _assistant_messages()
+    stable = _stable_assistant_result()
+    status = "completed" if stable else ("running" if _is_generating() or messages else "awaiting_result")
+    print(json.dumps({**base, "status": status, "assistant_message_count": len(messages)}, ensure_ascii=False))
+elif operation == "result":
+    message = _wait_stable_assistant_result()
+    if not message:
+        raise RuntimeError("ChatGPT assistant result was not observed stable and final before timeout")
+    if not message["id"]:
+        raise RuntimeError("assistant result had no observed message id")
+    print(json.dumps({**base, "status": "completed", "text": message["text"], "message_id": message["id"]}, ensure_ascii=False))
+else:
+    print(json.dumps({**base, "status": "completed" if _assistant_messages() else "awaiting_result"}, ensure_ascii=False))

package/skills/chatgpt-browser-worker/scripts/contract.py

@@ -0,0 +1,151 @@
+"""Pure contract helpers for a ChatGPT browser-worker adapter.
+
+This module deliberately has no browser, network, or ChatGPT API dependency.
+An adapter built on browser-harness can use these helpers at its boundary and
+unit-test them with ordinary dictionaries.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+THINKING_LEVELS = frozenset({"default", "low", "medium", "high"})
+EFFECTIVE_LEVELS = THINKING_LEVELS | {"unknown"}
+STATUSES = frozenset(
+    {"created", "running", "awaiting_result", "completed", "failed", "blocked", "deleted"}
+)
+OPERATIONS = frozenset({"create", "resume", "status", "result", "delete"})
+
+
+class ContractError(ValueError):
+    """Raised when an input crosses the worker boundary incorrectly."""
+
+
+def _text(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ContractError(f"{field} must be a non-empty string")
+    return value.strip()
+
+
+def validate_project(project: Any) -> dict[str, str]:
+    if not isinstance(project, dict):
+        raise ContractError("project must be an object")
+    result = {"name": _text(project.get("name"), "project.name")}
+    if project.get("id") is not None:
+        result["id"] = _text(project["id"], "project.id")
+    return result
+
+
+def validate_request(request: Any) -> dict[str, Any]:
+    if not isinstance(request, dict):
+        raise ContractError("request must be an object")
+    operation = _text(request.get("operation"), "operation")
+    if operation not in OPERATIONS:
+        raise ContractError(f"unsupported operation: {operation}")
+    result: dict[str, Any] = {"operation": operation}
+    if operation in {"create", "resume"}:
+        result["project"] = validate_project(request.get("project"))
+    if operation == "create":
+        result["prompt"] = _text(request.get("prompt"), "prompt")
+        level = _text(request.get("thinking_level"), "thinking_level")
+        if level not in THINKING_LEVELS:
+            raise ContractError(f"unsupported thinking_level: {level}")
+        result["thinking_level"] = level
+    elif operation == "resume" and request.get("thinking_level") is not None:
+        level = _text(request["thinking_level"], "thinking_level")
+        if level not in THINKING_LEVELS:
+            raise ContractError(f"unsupported thinking_level: {level}")
+        result["thinking_level"] = level
+    if operation != "create":
+        result["thread_id"] = _text(request.get("thread_id"), "thread_id")
+    return result
+
+
+def validate_state(state: Any) -> dict[str, Any]:
+    if not isinstance(state, dict):
+        raise ContractError("state must be an object")
+    if state.get("schema_version") != 1:
+        raise ContractError("schema_version must be 1")
+    result = deepcopy(state)
+    result["thread_id"] = _text(state.get("thread_id"), "thread_id")
+    result["project"] = validate_project(state.get("project"))
+    status = _text(state.get("status"), "status")
+    if status not in STATUSES:
+        raise ContractError(f"unsupported status: {status}")
+    result["status"] = status
+    requested = _text(state.get("requested_thinking_level"), "requested_thinking_level")
+    if requested not in THINKING_LEVELS:
+        raise ContractError(f"unsupported requested_thinking_level: {requested}")
+    result["requested_thinking_level"] = requested
+    effective = _text(state.get("effective_thinking_level"), "effective_thinking_level")
+    if effective not in EFFECTIVE_LEVELS:
+        raise ContractError(f"unsupported effective_thinking_level: {effective}")
+    result["effective_thinking_level"] = effective
+    return result
+
+
+def validate_result(result: Any, *, thread_id: str | None = None) -> dict[str, Any]:
+    """Accept only a normalized, observed assistant result."""
+    if not isinstance(result, dict):
+        raise ContractError("result must be an object")
+    result_thread_id = _text(result.get("thread_id"), "result.thread_id")
+    if thread_id is not None and result_thread_id != _text(thread_id, "thread_id"):
+        raise ContractError("result belongs to a different thread")
+    if result.get("status") != "completed":
+        raise ContractError("only a completed observed result is reportable")
+    normalized = deepcopy(result)
+    normalized["thread_id"] = result_thread_id
+    normalized["text"] = _text(result.get("text"), "result.text")
+    normalized["message_id"] = _text(result.get("message_id"), "result.message_id")
+    if result.get("observed_at") is not None:
+        normalized["observed_at"] = _text(result["observed_at"], "result.observed_at")
+    return normalized
+
+
+def validate_cleanup_observation(observation: Any, *, thread_id: str) -> dict[str, Any]:
+    """Accept browser evidence that exactly one requested thread is gone."""
+    if not isinstance(observation, dict):
+        raise ContractError("cleanup observation must be an object")
+    expected_id = _text(thread_id, "thread_id")
+    observed_id = observation.get("thread_id")
+    if observed_id is not None and _text(observed_id, "cleanup.thread_id") != expected_id:
+        raise ContractError("cleanup observation belongs to a different thread")
+    outcome = _text(observation.get("outcome"), "cleanup.outcome")
+    if outcome not in {"deleted", "not_found"}:
+        raise ContractError("cleanup was not verified")
+    if observation.get("verified") is not True:
+        raise ContractError("cleanup observation is not verified")
+    return deepcopy(observation)
+
+
+def project_matches(expected: Any, observed: Any) -> bool:
+    expected_project = validate_project(expected)
+    observed_project = validate_project(observed)
+    if expected_project["name"] != observed_project["name"]:
+        return False
+    # A browser boundary may expose only the visible Project name. Compare
+    # opaque IDs only when both sides actually observed one.
+    return not (expected_project.get("id") and observed_project.get("id")) or expected_project["id"] == observed_project["id"]
+
+
+def transition(state: Any, new_status: str, *, observed_project: Any | None = None) -> dict[str, Any]:
+    current = validate_state(state)
+    new_status = _text(new_status, "status")
+    if new_status not in STATUSES:
+        raise ContractError(f"unsupported status: {new_status}")
+    if current["status"] == "deleted":
+        raise ContractError("deleted thread is terminal")
+    if observed_project is not None and not project_matches(current["project"], observed_project):
+        raise ContractError("observed Project does not match durable Project binding")
+    allowed = {
+        "created": {"running", "blocked", "failed", "deleted"},
+        "running": {"awaiting_result", "completed", "blocked", "failed", "deleted"},
+        "awaiting_result": {"completed", "running", "blocked", "failed", "deleted"},
+        "completed": {"running", "blocked", "deleted"},
+        "failed": {"running", "blocked", "deleted"},
+        "blocked": {"running", "blocked", "failed", "deleted"},
+    }
+    if new_status not in allowed[current["status"]]:
+        raise ContractError(f"invalid transition: {current['status']} -> {new_status}")
+    current["status"] = new_status
+    return current