agents-relay 1.0.3 → 1.0.5

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

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

@@ -0,0 +1,84 @@
+"""Create a ChatGPT thread through an injected browser-harness port."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Callable, Protocol
+
+try:
+    from .contract import ContractError, project_matches, validate_request
+except ImportError:  # Loaded directly by the lightweight skill test harness.
+    from contract import ContractError, project_matches, validate_request
+
+
+class BrowserPort(Protocol):
+    def select_project(self, project: dict[str, str]) -> dict[str, Any]: ...
+    def set_thinking_level(self, level: str) -> dict[str, Any]: ...
+    def send_prompt(self, prompt: str) -> dict[str, Any]: ...
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _effective_level(observation: Any) -> str:
+    if not isinstance(observation, dict):
+        return "unknown"
+    value = observation.get("effective_thinking_level", observation.get("level"))
+    return value if value in {"default", "low", "medium", "high"} else "unknown"
+
+
+def create_thread(
+    port: BrowserPort,
+    request: Any,
+    *,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Select the requested Project, send the first prompt, and return state.
+
+    The port returns observations from the browser.  It is deliberately not
+    responsible for durable state or contract validation.
+    """
+    request = validate_request(request)
+    if request["operation"] != "create":
+        raise ContractError("create_thread requires operation=create")
+
+    selected = port.select_project(request["project"])
+    if not project_matches(request["project"], selected):
+        raise ContractError("browser observed a different Project after selection")
+
+    thinking_observation: dict[str, Any] = {"requested": "default", "changed": False}
+    effective = "unknown"
+    if request["thinking_level"] != "default":
+        raw = port.set_thinking_level(request["thinking_level"])
+        thinking_observation = dict(raw) if isinstance(raw, dict) else {"observed": raw}
+        thinking_observation["requested"] = request["thinking_level"]
+        thinking_observation["changed"] = True
+        effective = _effective_level(raw)
+
+    sent = port.send_prompt(request["prompt"])
+    if not isinstance(sent, dict) or not isinstance(sent.get("thread_id"), str) or not sent["thread_id"].strip():
+        raise ContractError("browser did not return an observed thread_id")
+
+    timestamp = now()
+    state: dict[str, Any] = {
+        "schema_version": 1,
+        "thread_id": sent["thread_id"].strip(),
+        "project": dict(selected),
+        "status": "running",
+        "requested_thinking_level": request["thinking_level"],
+        "effective_thinking_level": effective,
+        "created_at": timestamp,
+        "updated_at": timestamp,
+        "last_error": None,
+        "evidence": {
+            "project": dict(selected),
+            "thinking": thinking_observation,
+            "thread": {key: value for key, value in sent.items() if key != "text"},
+        },
+    }
+    if "conversation_url" in sent:
+        state["conversation_url"] = sent["conversation_url"]
+    if persist is not None:
+        persist(state)
+    return state

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""Create one ChatGPT thread using the authenticated browser-harness session."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import tempfile
+
+
+BH_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_create_bh.py")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", required=True)
+    parser.add_argument("--prompt", required=True)
+    parser.add_argument("--thinking-level", choices=("default", "low", "medium", "high"), default="default")
+    args = parser.parse_args()
+    config = {"project": {"name": args.project}, "prompt": args.prompt, "thinking_level": args.thinking_level}
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as handle:
+        json.dump(config, handle, ensure_ascii=False)
+        config_path = handle.name
+    try:
+        code = open(BH_SCRIPT, encoding="utf-8").read().replace("__CFG_PATH__", config_path)
+        result = subprocess.run(["browser-harness"], input=code, text=True, timeout=180)
+        return result.returncode
+    finally:
+        os.unlink(config_path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Run one existing-thread operation through the authenticated browser-harness."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import tempfile
+
+
+BH_SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_operate_bh.py")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("operation", choices=("resume", "continue", "status", "result", "delete"))
+    parser.add_argument("--thread-id", required=True)
+    parser.add_argument("--project", required=True)
+    parser.add_argument("--prompt")
+    args = parser.parse_args()
+    if args.operation == "continue" and not args.prompt:
+        parser.error("continue requires --prompt")
+    config = {key: value for key, value in vars(args).items() if value is not None}
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as handle:
+        json.dump(config, handle, ensure_ascii=False)
+        config_path = handle.name
+    try:
+        code = open(BH_SCRIPT, encoding="utf-8").read().replace("__CFG_PATH__", config_path)
+        return subprocess.run(["browser-harness"], input=code, text=True, timeout=180).returncode
+    finally:
+        os.unlink(config_path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,179 @@
+"""Existing-thread operations for an injected browser-harness port."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Callable, Protocol
+
+try:
+    from .contract import ContractError, transition, validate_cleanup_observation, validate_project, validate_request, validate_result, validate_state
+except ImportError:
+    from contract import ContractError, transition, validate_cleanup_observation, validate_project, validate_request, validate_result, validate_state
+
+
+class BrowserPort(Protocol):
+    def open_thread(self, thread_id: str) -> dict[str, Any]: ...
+    def send_prompt(self, prompt: str) -> dict[str, Any]: ...
+    def read_status(self) -> dict[str, Any]: ...
+    def read_result(self) -> dict[str, Any]: ...
+    def delete_thread(self) -> dict[str, Any]: ...
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _project(observation: Any) -> dict[str, Any]:
+    if not isinstance(observation, dict):
+        raise ContractError("browser did not return an observed thread")
+    project = observation.get("project", observation.get("selected_project"))
+    if project is None:
+        raise ContractError("browser did not expose the thread Project")
+    return project
+
+
+def _status(observation: Any, default: str = "awaiting_result") -> str:
+    value = observation.get("status") if isinstance(observation, dict) else None
+    return value if value in {"created", "running", "awaiting_result", "completed", "failed", "blocked"} else default
+
+
+def _same_project(left: Any, right: Any) -> bool:
+    """Compare names always; compare IDs only when both UI boundaries expose them."""
+    expected = validate_project(left)
+    observed = validate_project(right)
+    return expected["name"] == observed["name"] and (
+        "id" not in expected or "id" not in observed or expected["id"] == observed["id"]
+    )
+
+
+def _save(state: dict[str, Any], persist: Callable[[dict[str, Any]], None] | None, now: Callable[[], str]) -> dict[str, Any]:
+    state["updated_at"] = now()
+    if persist is not None:
+        persist(state)
+    return state
+
+
+def _opened(port: BrowserPort, state: dict[str, Any], *, expected_project: dict[str, Any]) -> dict[str, Any]:
+    opened = port.open_thread(state["thread_id"])
+    if not isinstance(opened, dict):
+        raise ContractError("browser did not return an observed thread")
+    observed_id = opened.get("thread_id", state["thread_id"])
+    if observed_id != state["thread_id"]:
+        raise ContractError("browser opened a different thread")
+    observed_project = _project(opened)
+    if not _same_project(expected_project, observed_project):
+        raise ContractError("observed Project does not match durable Project binding")
+    return opened
+
+
+def resume_thread(
+    port: BrowserPort,
+    request: Any,
+    *,
+    state: Any | None = None,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Open and verify an existing thread without sending a new prompt."""
+    request = validate_request(request)
+    if request["operation"] != "resume":
+        raise ContractError("resume_thread requires operation=resume")
+    current = validate_state(state) if state is not None else {
+        "schema_version": 1,
+        "thread_id": request["thread_id"],
+        "project": request["project"],
+        "status": "created",
+        "requested_thinking_level": request.get("thinking_level", "default"),
+        "effective_thinking_level": "unknown",
+    }
+    if current["thread_id"] != request["thread_id"]:
+        raise ContractError("resume request does not match durable thread identity")
+    if current["status"] == "deleted":
+        raise ContractError("deleted thread is terminal")
+    if not _same_project(current["project"], request["project"]):
+        raise ContractError("resume Project does not match durable Project binding")
+    opened = _opened(port, current, expected_project=current["project"])
+    observed_status = _status(opened)
+    if current["status"] == "created":
+        current = transition(current, "running")
+    if observed_status != current["status"]:
+        current = transition(current, observed_status)
+    current["project"] = dict(_project(opened))
+    current.setdefault("evidence", {})["open"] = opened
+    return _save(current, persist, now)
+
+
+def continue_thread(
+    port: BrowserPort,
+    state: Any,
+    prompt: str,
+    *,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Open a durable thread, send one follow-up prompt, and persist running state."""
+    current = validate_state(state)
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise ContractError("prompt must be a non-empty string")
+    _opened(port, current, expected_project=current["project"])
+    if current["status"] != "running":
+        current = transition(current, "running")
+    sent = port.send_prompt(prompt.strip())
+    if not isinstance(sent, dict):
+        raise ContractError("browser did not acknowledge the follow-up prompt")
+    current.setdefault("evidence", {})["prompt"] = sent
+    return _save(current, persist, now)
+
+
+def inspect_thread(
+    port: BrowserPort,
+    state: Any,
+    *,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Read the observable UI status/progress and persist its state transition."""
+    current = validate_state(state)
+    if current["status"] == "deleted":
+        raise ContractError("deleted thread is terminal")
+    observation = port.read_status()
+    observed_status = _status(observation, default="awaiting_result")
+    if observed_status != current["status"]:
+        current = transition(current, observed_status)
+    current.setdefault("evidence", {})["status"] = observation
+    return _save(current, persist, now)
+
+
+def result_thread(
+    port: BrowserPort,
+    state: Any,
+    *,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Return only an observed, normalized assistant result and persist completion."""
+    current = validate_state(state)
+    if current["status"] == "deleted":
+        raise ContractError("deleted thread is terminal")
+    result = validate_result(port.read_result(), thread_id=current["thread_id"])
+    if current["status"] != "completed":
+        current = transition(current, "completed")
+    current.setdefault("evidence", {})["result"] = result
+    _save(current, persist, now)
+    return result
+
+
+def delete_thread(
+    port: BrowserPort,
+    state: Any,
+    *,
+    persist: Callable[[dict[str, Any]], None] | None = None,
+    now: Callable[[], str] = _now,
+) -> dict[str, Any]:
+    """Delete one durable thread and persist its terminal tombstone."""
+    current = validate_state(state)
+    if current["status"] == "deleted":
+        return current
+    observation = validate_cleanup_observation(port.delete_thread(), thread_id=current["thread_id"])
+    current = transition(current, "deleted")
+    current.setdefault("evidence", {})["cleanup"] = observation
+    return _save(current, persist, now)

package/skills/chatgpt-browser-worker/tests/fixtures/relay_lifecycle.json

@@ -0,0 +1,21 @@
+{
+  "job_id": "neo-chatgpt-browser-worker-20260919",
+  "task_id": "chatgpt-thread-1",
+  "project": {"id": "project-1", "name": "neo"},
+  "create": {
+    "operation": "create",
+    "project": {"name": "neo"},
+    "prompt": "Run the assigned task.",
+    "thinking_level": "high"
+  },
+  "thread": {
+    "thread_id": "thread-1",
+    "conversation_url": "https://chatgpt.com/c/thread-1"
+  },
+  "result": {
+    "thread_id": "thread-1",
+    "status": "completed",
+    "text": "The assigned task is complete.",
+    "message_id": "message-1"
+  }
+}

package/skills/chatgpt-browser-worker/tests/test_agent_definition.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+
+AGENT = Path(__file__).parents[1] / "agents" / "browser-worker.agent.md"
+
+
+def test_browser_worker_agent_defines_typed_lifecycle_and_verified_result():
+    text = AGENT.read_text()
+
+    for operation in ("create", "resume", "continue", "status", "result", "delete"):
+        assert f"`{operation}`" in text
+    for field in ("thread_id", "project", "message_id", "verified", "observed_at"):
+        assert f'"{field}"' in text
+    assert "browser-harness" in text
+    assert "authentication_required" in text
+    assert "Do not report success" in text
+
+
+def test_callers_are_directed_to_launch_agent_not_helper_scripts():
+    skill = (AGENT.parents[1] / "SKILL.md").read_text()
+    orchestration = (AGENT.parents[1] / "references" / "orchestration.md").read_text()
+
+    assert "Callers launch that" in skill
+    assert "agent with a typed lifecycle intent" in skill
+    assert "must not directly call" in skill
+    assert "launches the `browser-worker` agent" in orchestration
+    assert "must not directly invoke" in orchestration