agora-adapter 0.2.0__py3-none-any.whl

agora/__init__.py

@@ -0,0 +1 @@
+"""Agora's thin agent adapters. PocketBase owns storage, identity, and realtime."""

agora/adapter/__init__.py

@@ -0,0 +1,3 @@
+"""Outbound-only local harness supervisor; the room relay remains the data plane."""
+
+__version__ = "0.2.0"

agora/adapter/__main__.py

@@ -0,0 +1,3 @@
+from agora.adapter.cli import main
+
+main()

agora/adapter/cli.py

@@ -0,0 +1,261 @@
+"""Run one room-scoped agent on the operator's machine."""
+
+import argparse
+import asyncio
+import contextlib
+import hashlib
+import json
+import logging
+import os
+import signal
+import sqlite3
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+from agora.adapter import __version__
+from agora.adapter.client import AccessLost, Hall
+from agora.adapter.diagnostics import Diagnostics
+from agora.adapter.dsh import DSH
+from agora.adapter.harness import Claude, Codex, HarnessError
+from agora.adapter.state import State
+from agora.adapter.supervisor import Supervisor
+
+
+def parser():
+    result = argparse.ArgumentParser(
+        description=__doc__,
+        epilog="For a hidden token prompt, use: agora-adapter connect --help",
+    )
+    result.add_argument("--version", action="version", version="%(prog)s " + __version__)
+    result.add_argument("--hall", help="Hall origin, e.g. https://hall.example.com")
+    result.add_argument("--room", help="15-character room ID")
+    result.add_argument("--harness", choices=("claude", "codex", "dsh"))
+    result.add_argument("--cwd", type=Path, help="Local workspace exposed to the harness")
+    result.add_argument(
+        "--token-env",
+        default="AGORA_ROOM_TOKEN",
+        help="Environment variable holding the agent token",
+    )
+    result.add_argument("--state", type=Path, help="Private SQLite checkpoint file")
+    result.add_argument("--wake-on", choices=("mentions", "human", "controls"), default="mentions")
+    result.add_argument(
+        "--allow-edits",
+        action="store_true",
+        help="Allow harness-native workspace editing; never bypass approvals",
+    )
+    result.add_argument("--model", help="Optional harness model override")
+    result.add_argument(
+        "--inspect", action="store_true", help="Read local --state without starting a harness"
+    )
+    result.add_argument(
+        "--diagnostics",
+        action="store_true",
+        help="Include the last private diagnostic records with --inspect",
+    )
+    result.add_argument(
+        "--diagnose",
+        action="store_true",
+        help="Check Codex/DSH startup/resume without submitting a model turn",
+    )
+    result.add_argument(
+        "--handoff",
+        action="store_true",
+        help="Wait for the desktop Codex turn to finish before taking over",
+    )
+    result.add_argument(
+        "--handoff-timeout", type=float, default=600, help="Maximum handoff wait in seconds"
+    )
+    result.add_argument(
+        "--fork-session",
+        action="store_true",
+        help="Explicitly fork existing history into an adapter-owned Codex session",
+    )
+    result.add_argument(
+        "--recover",
+        action="store_true",
+        help="Replay an uncertain turn after inspecting its side effects",
+    )
+    return result
+
+
+def inspect_state(path, *, diagnostics=False):
+    with sqlite3.connect(f"file:{path.resolve()}?mode=ro", uri=True) as db:
+        meta = {key: json.loads(value) for key, value in db.execute("SELECT key, value FROM meta")}
+        result = {key: meta.get(key) for key in ("scope", "session", "attempt", "last_failure")}
+        result["inbox"] = [
+            dict(zip(("source", "id", "status"), row, strict=True))
+            for row in db.execute("SELECT source, id, status FROM inbox WHERE status != 'done'")
+        ]
+    journal = Path(str(path) + ".diagnostics.jsonl")
+    result["diagnostics_path"] = str(journal)
+    if diagnostics and journal.exists():
+        # The journal is bounded and redacted at write time; no room transcripts are logged.
+        result["diagnostics"] = [
+            json.loads(line) for line in journal.read_text().splitlines()[-10:]
+        ]
+    print(json.dumps(result, indent=2))
+
+
+async def run(args):
+    token = os.environ.get(args.token_env, "")
+    if not token or any(char.isspace() for char in token):
+        raise ValueError("Set the room token in the selected environment variable.")
+    cwd = args.cwd.resolve(strict=True)
+    if not cwd.is_dir():
+        raise ValueError("The workspace must be a directory.")
+    hall = Hall(args.hall, token, args.room)
+    state = harness = None
+    bootstrap = args.state or Path.home() / ".local/state/agora/startup"
+    diagnostics = Diagnostics(Path(str(bootstrap) + ".diagnostics.jsonl"), secrets=(token,))
+    try:
+        await hall.authenticate()
+        mcp = await hall.discovery()
+        scope = {
+            "hall": hall.url,
+            "room": hall.room,
+            "agent": hall.person["id"],
+            "harness": args.harness,
+            "cwd": str(cwd),
+        }
+        key = hashlib.sha256(repr(sorted(scope.items())).encode()).hexdigest()[:24]
+        path = args.state or Path.home() / ".local/state/agora" / (key + ".sqlite3")
+        diagnostics = Diagnostics(Path(str(path) + ".diagnostics.jsonl"), secrets=(token,))
+        state = State(path, scope, args.recover, hold_uncertain=True)
+        if state.recovery:
+            diagnostics.record("recovery", **state.recovery)
+        harness = {"claude": Claude, "codex": Codex, "dsh": DSH}[args.harness](
+            cwd=cwd,
+            mcp=mcp,
+            token=token,
+            allow_edits=args.allow_edits,
+            model=args.model,
+        )
+        harness.diagnostics = diagnostics
+        supervisor = Supervisor(hall, state, harness, wake_on=args.wake_on)
+        task = asyncio.current_task()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            loop.add_signal_handler(sig, task.cancel)
+        logging.info(
+            "Listening for room activity. Harness: %s. Checkpoints: %s", args.harness, path
+        )
+        try:
+            session = state.get("session")
+            if args.fork_session and session:
+                # Reject a blind replay before creating a replacement session.
+                if state.unfinished():
+                    raise HarnessError("Inspect uncertain work and use --recover before forking.")
+                session = await harness.fork_session(session, lambda sid: state.set("session", sid))
+                state.set("last_failure", None)
+                supervisor.retries = 0
+                logging.info("Adapter-owned Codex session: %s", session)
+            if args.handoff and session:
+                logging.info(
+                    "Handoff waiting for the current Codex turn; do not send more desktop turns."
+                )
+                await hall.activity("error")
+                waiter = asyncio.create_task(harness.wait_for_idle(session, args.handoff_timeout))
+                try:
+                    while not waiter.done():
+                        try:
+                            await asyncio.wait_for(asyncio.shield(waiter), 15)
+                        except TimeoutError:
+                            if waiter.done():
+                                raise
+                            await hall.activity("error")
+                    await waiter
+                finally:
+                    waiter.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await waiter
+            if args.diagnose:
+                if args.harness == "dsh":
+                    await harness.prepare(session, lambda sid: state.set("session", sid))
+                else:
+                    await harness.start()
+                    if session:
+                        await harness.check_idle(session)
+                        await harness.request("thread/resume", harness.thread_params(session))
+                logging.info(
+                    "%s startup/resume succeeded. No model turn was submitted.", args.harness
+                )
+                return
+            await supervisor.run()
+        finally:
+            for sig in (signal.SIGTERM, signal.SIGINT):
+                loop.remove_signal_handler(sig)
+    except Exception as exc:
+        if diagnostics:
+            incident = diagnostics.record(
+                "adapter_failure", exception=type(exc).__name__, message=str(exc)
+            )
+            logging.error("Adapter failure %s. Diagnostics: %s", incident, diagnostics.path)
+            if state and not state.get("last_failure"):
+                state.set(
+                    "last_failure",
+                    {
+                        "incident": incident,
+                        "message": str(exc)
+                        if isinstance(exc, HarnessError)
+                        else "Adapter startup or lifecycle failed.",
+                        "blocked": True,
+                    },
+                )
+            # Without the state lock, another adapter may own this identity. Do not
+            # overwrite its activity merely because this process failed to start.
+            if state:
+                try:
+                    await hall.activity("error")
+                except (AccessLost, httpx.HTTPError):
+                    pass
+        raise
+    finally:
+        if harness:
+            await harness.close()
+        if state:
+            state.close()
+        await hall.close()
+
+
+def main():
+    if sys.argv[1:2] == ["connect"]:
+        from agora.adapter.launcher import main as connect
+
+        connect(sys.argv[2:])
+        return
+    logging.Formatter.converter = time.gmtime
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)sZ %(levelname)s %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S",
+    )
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    argument_parser = parser()
+    args = argument_parser.parse_args()
+    if args.inspect:
+        if not args.state:
+            argument_parser.error("--inspect requires --state")
+        inspect_state(args.state, diagnostics=args.diagnostics)
+        return
+    if not all((args.hall, args.room, args.harness, args.cwd)):
+        argument_parser.error("--hall, --room, --harness and --cwd are required")
+    if (args.handoff or args.fork_session) and args.harness != "codex":
+        argument_parser.error("--handoff and --fork-session require --harness codex")
+    if args.diagnose and args.harness not in ("codex", "dsh"):
+        argument_parser.error("--diagnose requires --harness codex or dsh")
+    if args.handoff_timeout <= 0:
+        argument_parser.error("--handoff-timeout must be positive")
+    try:
+        asyncio.run(run(args))
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    except (ValueError, AccessLost, HarnessError) as exc:
+        raise SystemExit(str(exc)) from None
+    except Exception:
+        # Provider and transport exceptions may contain prompts, URLs, or credentials.
+        raise SystemExit(
+            "Adapter failed; inspect local state and harness logs before restarting."
+        ) from None

agora/adapter/client.py

@@ -0,0 +1,160 @@
+"""PocketBase SSE is a hint; reconnects replay the durable room records."""
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Sequence
+from typing import cast
+from urllib.parse import urlsplit
+
+import httpx
+
+from agora.adapter.interfaces import Activity, InputRecord
+from agora.contracts import Person, Room
+from agora.validation import record_id
+
+
+class AccessLost(Exception):
+    """The adapter must stop its local harness and require fresh authorization."""
+
+
+def origin_url(value: str) -> str:
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme not in ("http", "https")
+        or not parsed.hostname
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+        or parsed.path not in ("", "/")
+        or (parsed.scheme == "http" and parsed.hostname not in ("127.0.0.1", "localhost", "::1"))
+    ):
+        raise ValueError("Use an HTTPS hall origin (HTTP is supported only on loopback).")
+    return value.rstrip("/")
+
+
+async def sse_events(response: httpx.Response) -> AsyncIterator[tuple[str, dict]]:
+    event = "message"
+    data: list[str] = []
+    async for line in response.aiter_lines():
+        if not line:
+            if data:
+                yield event, json.loads("\n".join(data))
+            event, data = "message", []
+        elif line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:"):
+            data.append(line[5:].lstrip(" "))
+
+
+class Hall:
+    def __init__(self, url: str, token: str, room: str, *, transport=None):
+        self.url, self.room = origin_url(url), record_id(room)
+        self.token = token
+        self.http = httpx.AsyncClient(
+            base_url=self.url,
+            headers={"Authorization": "Bearer " + token},
+            timeout=30,
+            follow_redirects=False,
+            transport=transport,
+        )
+        self.person: Person | None = None
+
+    async def request(self, method, path, **kwargs):
+        response = await self.http.request(method, path, **kwargs)
+        if response.status_code in (401, 403, 404):
+            raise AccessLost("Room or agent access is no longer available.")
+        response.raise_for_status()
+        return response.json() if response.content else None
+
+    async def authenticate(self) -> Room:
+        auth = await self.request("POST", "/api/collections/people/auth-refresh")
+        person = auth["record"]
+        if person.get("kind") != "agent" or person.get("agent_room") != self.room:
+            raise ValueError(
+                "Use an invited agent token for this room, never a human or admin token."
+            )
+        room = await self.request("GET", f"/api/collections/rooms/records/{self.room}")
+        if self.person and self.person["id"] != person["id"]:
+            raise AccessLost("The authenticated identity changed.")
+        self.person = person
+        return cast(Room, room)
+
+    async def discovery(self):
+        data = await self.request("GET", "/.well-known/agora.json")
+        mcp = data.get("mcp", "")
+        parsed = urlsplit(mcp)
+        origin_url(f"{parsed.scheme}://{parsed.netloc}")
+        if parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise ValueError("Invalid MCP discovery URL.")
+        return mcp
+
+    async def activity(self, status: Activity) -> None:
+        await self.request(
+            "POST", "/api/agora/agents/me/activity", json={"status": status}, timeout=5
+        )
+
+    async def records(
+        self, collection: str, cursor: str | int | None = None
+    ) -> AsyncIterator[list[InputRecord]]:
+        filters = f'room="{self.room}"'
+        if collection == "agent_controls":
+            if self.person is None:
+                raise AccessLost("Authenticate before reading control records.")
+            filters += f' && agent="{self.person["id"]}" && sequence > {int(cursor or 0)}'
+            sort = "sequence"
+        else:
+            sort = "created,id"
+            if cursor:
+                filters += " && created >= " + json.dumps(cursor)
+        page = 1
+        while True:
+            result = await self.request(
+                "GET",
+                f"/api/collections/{collection}/records",
+                params={"filter": filters, "sort": sort, "perPage": 100, "page": page},
+            )
+            yield result["items"]
+            if page >= result["totalPages"]:
+                return
+            page += 1
+
+    async def watch(
+        self, dirty: asyncio.Event, *, subscriptions: Sequence[str] | None = None
+    ) -> None:
+        """Subscribe before signalling replay, closing the snapshot/subscription race."""
+        delay = 1
+        while True:
+            try:
+                async with self.http.stream(
+                    "GET", "/api/realtime", timeout=httpx.Timeout(30, read=360)
+                ) as response:
+                    response.raise_for_status()
+                    async for event, data in sse_events(response):
+                        if event == "PB_CONNECT":
+                            await self.request(
+                                "POST",
+                                "/api/realtime",
+                                json={
+                                    "clientId": data["clientId"],
+                                    "subscriptions": subscriptions
+                                    or [
+                                        "messages/*",
+                                        "revisions/*",
+                                        "agent_controls/*",
+                                        f"rooms/{self.room}",
+                                    ],
+                                },
+                            )
+                            delay = 1
+                            dirty.set()
+                        elif data.get("record", {}).get("room", self.room) == self.room:
+                            dirty.set()
+            except (httpx.HTTPError, ValueError, KeyError):
+                # No upstream exception text: URLs may contain credentials in other contexts.
+                pass
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 30)
+
+    async def close(self) -> None:
+        await self.http.aclose()

agora/adapter/diagnostics.py

@@ -0,0 +1,76 @@
+"""Bounded, private operator diagnostics; never a room transcript or reasoning log."""
+
+import json
+import logging
+import os
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import uuid4
+
+
+class Diagnostics:
+    def __init__(self, path: Path, *, secrets=(), limit=1024 * 1024):
+        self.path, self.secrets, self.limit = path, tuple(filter(None, secrets)), limit
+
+    def clean(self, value):
+        if isinstance(value, dict):
+            return {
+                str(key): "[REDACTED]"
+                if any(
+                    word in str(key).lower()
+                    for word in (
+                        "token",
+                        "secret",
+                        "password",
+                        "authorization",
+                        "api_key",
+                        "apikey",
+                        "credential",
+                        "cookie",
+                    )
+                )
+                else self.clean(item)
+                for key, item in value.items()
+            }
+        if isinstance(value, (list, tuple)):
+            return [self.clean(item) for item in value[:50]]
+        if not isinstance(value, str):
+            return value
+        for secret in self.secrets:
+            value = value.replace(secret, "[REDACTED]")
+        value = re.sub(r"(?i)\bBearer\s+[^\s\"'<>]+", "Bearer [REDACTED]", value)
+        value = re.sub(
+            r"(?i)(\b(?:api[_-]?key|token|password|secret)\s*[=:]\s*)[^\s&,;\"']+",
+            r"\1[REDACTED]",
+            value,
+        )
+        value = re.sub(r"\bsk-[\w-]+", "[REDACTED]", value)
+        return value[:8000]
+
+    def record(self, event, **fields):
+        record = self.clean(
+            {
+                "id": uuid4().hex[:12],
+                "at": datetime.now(UTC).isoformat(),
+                "event": event,
+                **fields,
+            }
+        )
+        try:
+            self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            if self.path.exists() and self.path.stat().st_size >= self.limit:
+                self.path.replace(self.path.with_suffix(self.path.suffix + ".previous"))
+            fd = os.open(self.path, os.O_CREAT | os.O_WRONLY | os.O_APPEND, 0o600)
+            with os.fdopen(fd, "w") as handle:
+                os.fchmod(handle.fileno(), 0o600)
+                handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+        except OSError as exc:
+            # Diagnostic failure must be visible without replacing the original failure.
+            logging.error(
+                "Cannot persist adapter diagnostics at %s (errno %s).", self.path, exc.errno
+            )
+            return None
+        return record["id"]

agora/adapter/dsh-policy.mjs

@@ -0,0 +1,13 @@
+// Apply the operator's choice before both fresh and restored Agents are published.
+// DSH otherwise preserves a resumed session's earlier permission events.
+export const inject = ['permissionPresets'];
+
+export function apply(ctx) {
+  const mode = process.env.AGORA_DSH_PERMISSION_MODE;
+  if (!['read-only', 'workspace-write'].includes(mode)) {
+    throw new Error('Agora requires an explicit read-only or workspace-write policy.');
+  }
+  ctx.on('agent/prepare', ({ agent }) => {
+    ctx.permissionPresets.set(agent.session, mode);
+  });
+}

agora/adapter/dsh.patch.yml

@@ -0,0 +1,21 @@
+# Invocation-only policy; room credentials are passed over ACP, never stored here.
+- id: sandbox-policy
+  config:
+    mode: !!js process.env.AGORA_DSH_PERMISSION_MODE
+    workspaceRoot: !!js process.cwd()
+
+- id: approval
+  config:
+    policy: never
+
+- id: permission
+  config:
+    defaultPreset: !!js process.env.AGORA_DSH_PERMISSION_MODE
+    presets:
+      read-only: {sandbox: read-only, approval: never}
+      workspace-write: {sandbox: workspace-write, approval: never}
+      danger-full-access: {sandbox: danger-full-access, approval: never}
+
+- insert:
+    - id: agora-permission
+      name: ./dsh-policy.mjs