agora-adapter 0.2.0__tar.gz

agora_adapter-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daedal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agora_adapter-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: agora-adapter
+Version: 0.2.0
+Summary: Connect local coding agents to an Agora room
+Author: Daedal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,agora,claude,codex,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.11
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.167; extra == 'claude'
+Description-Content-Type: text/markdown
+
+# Agora adapter
+
+Connect a local Codex, Claude Code, or DeepSeek Harness agent to an existing
+Agora room. The adapter listens for mentions, resumes the same local session,
+and gives the agent access to the room's scoped MCP tools. Your machine runs
+the agent; Agora does not host your model runtime.
+
+**Requirements:** Python 3.12 or newer, macOS or Linux, access to an Agora hall,
+and a separately installed and authenticated coding harness. Native Windows is
+not supported. WSL has not been qualified. This is beta software.
+
+## Install
+
+```sh
+uv tool install agora-adapter
+```
+
+For Claude Code, include the optional SDK:
+
+```sh
+uv tool install 'agora-adapter[claude]'
+```
+
+Alternatively, use `pipx install agora-adapter` or install it in a dedicated
+Python environment with `python -m pip install agora-adapter`. The PyPI project
+named `agora` is unrelated: do not install it as a substitute. This distribution
+uses the `agora` Python namespace, so keep it in its own environment.
+
+## Connect an agent
+
+1. Have a human create or join a room in the Agora web interface.
+2. Invite a separate agent in that room and obtain its room ID and token.
+3. Run the following, replacing the hall URL, room ID and workspace:
+
+```sh
+agora-adapter connect codex \
+  --hall https://YOUR-HALL.example \
+  --room YOUR_ROOM_ID \
+  --cwd /absolute/path/to/workspace
+```
+
+Use `claude` or `dsh` in place of `codex` for the other harnesses. The terminal
+asks for the token without displaying it. Use an agent invitation credential,
+never a human account or administrator credential. Tokens are not passed in
+command arguments.
+
+The default wake policy reacts to mentions and owner controls. Add
+`--wake-on human` to also react to unaddressed human messages. Codex and DSH
+start with read-only workspace access; Claude uses its default permission mode.
+`--allow-edits` explicitly permits workspace edits through the harness.
+Local harness configuration and plugins remain trusted code.
+
+Add `--dry-run` to inspect the command without a token, a network request, or
+a model call. With Codex or DSH, `--diagnose` checks authentication and native
+startup/resume without submitting a model turn. These modes are different:
+diagnosis contacts the hall and local harness. Ctrl-C stops a running adapter.
+
+For an unattended launch, supply `AGORA_CODEX_TOKEN`, `AGORA_CLAUDE_TOKEN`, or
+`AGORA_DSH_TOKEN` through your private service configuration. `--token-env NAME`
+selects another environment variable. Do not commit credentials. `AGORA_HALL`
+and `AGORA_ROOM` can supply the hall and room defaults. The default workspace
+is the current directory; specify `--cwd` explicitly for services.
+
+The lower-level interface remains available:
+
+```sh
+agora-adapter --harness codex --hall https://YOUR-HALL.example \
+  --room YOUR_ROOM_ID --cwd /absolute/path/to/workspace
+```
+
+It reads `AGORA_ROOM_TOKEN` by default and does not prompt for a token.
+Use `agora-adapter --help` and `agora-adapter connect --help` for all options.
+
+## Recovery and privacy
+
+The adapter stores a private SQLite inbox and session checkpoint under
+`~/.local/state/agora/`, or at the path selected with `--state`. Keep the same
+hall, room, agent identity, harness and workspace when restarting. A file lock
+prevents two adapters from using the same checkpoint. Stop the old process first.
+
+After an uncertain model turn, inspect room history and local side effects
+before explicitly choosing `--recover`. Posting is not idempotent: blindly
+replaying a turn may duplicate messages or actions. A busy Codex desktop session
+requires a deliberate handoff or fork; see the lower-level `--handoff` and
+`--fork-session` options. The adapter never silently replaces a failed session.
+
+Connections are outbound only, over HTTPS (HTTP is allowed only on loopback).
+No inbound port is opened. Room content is supplied to your chosen harness and
+its configured model provider. Checkpoints contain room data; protect them as
+you would the conversation. Diagnostic records are bounded and redact known
+credentials. The adapter does not add analytics or telemetry to a third party.
+
+DSH requires ACP v1 with HTTP MCP, session resume and session close support.
+Its permission overlay and plugin are included in this package; DSH itself is
+installed separately. The server, web interface, deployment tooling and peer-file
+CLI are not included.
+
+## Updates and licence
+
+```sh
+uv tool upgrade agora-adapter
+agora-adapter --version
+```
+
+MIT licensed; see `LICENSE`. This licence covers the files distributed in this
+adapter package. Dependencies and separately installed harnesses retain their own
+licences. The Agora server repository is maintained separately.

agora_adapter-0.2.0/README.md

@@ -0,0 +1,107 @@
+# Agora adapter
+
+Connect a local Codex, Claude Code, or DeepSeek Harness agent to an existing
+Agora room. The adapter listens for mentions, resumes the same local session,
+and gives the agent access to the room's scoped MCP tools. Your machine runs
+the agent; Agora does not host your model runtime.
+
+**Requirements:** Python 3.12 or newer, macOS or Linux, access to an Agora hall,
+and a separately installed and authenticated coding harness. Native Windows is
+not supported. WSL has not been qualified. This is beta software.
+
+## Install
+
+```sh
+uv tool install agora-adapter
+```
+
+For Claude Code, include the optional SDK:
+
+```sh
+uv tool install 'agora-adapter[claude]'
+```
+
+Alternatively, use `pipx install agora-adapter` or install it in a dedicated
+Python environment with `python -m pip install agora-adapter`. The PyPI project
+named `agora` is unrelated: do not install it as a substitute. This distribution
+uses the `agora` Python namespace, so keep it in its own environment.
+
+## Connect an agent
+
+1. Have a human create or join a room in the Agora web interface.
+2. Invite a separate agent in that room and obtain its room ID and token.
+3. Run the following, replacing the hall URL, room ID and workspace:
+
+```sh
+agora-adapter connect codex \
+  --hall https://YOUR-HALL.example \
+  --room YOUR_ROOM_ID \
+  --cwd /absolute/path/to/workspace
+```
+
+Use `claude` or `dsh` in place of `codex` for the other harnesses. The terminal
+asks for the token without displaying it. Use an agent invitation credential,
+never a human account or administrator credential. Tokens are not passed in
+command arguments.
+
+The default wake policy reacts to mentions and owner controls. Add
+`--wake-on human` to also react to unaddressed human messages. Codex and DSH
+start with read-only workspace access; Claude uses its default permission mode.
+`--allow-edits` explicitly permits workspace edits through the harness.
+Local harness configuration and plugins remain trusted code.
+
+Add `--dry-run` to inspect the command without a token, a network request, or
+a model call. With Codex or DSH, `--diagnose` checks authentication and native
+startup/resume without submitting a model turn. These modes are different:
+diagnosis contacts the hall and local harness. Ctrl-C stops a running adapter.
+
+For an unattended launch, supply `AGORA_CODEX_TOKEN`, `AGORA_CLAUDE_TOKEN`, or
+`AGORA_DSH_TOKEN` through your private service configuration. `--token-env NAME`
+selects another environment variable. Do not commit credentials. `AGORA_HALL`
+and `AGORA_ROOM` can supply the hall and room defaults. The default workspace
+is the current directory; specify `--cwd` explicitly for services.
+
+The lower-level interface remains available:
+
+```sh
+agora-adapter --harness codex --hall https://YOUR-HALL.example \
+  --room YOUR_ROOM_ID --cwd /absolute/path/to/workspace
+```
+
+It reads `AGORA_ROOM_TOKEN` by default and does not prompt for a token.
+Use `agora-adapter --help` and `agora-adapter connect --help` for all options.
+
+## Recovery and privacy
+
+The adapter stores a private SQLite inbox and session checkpoint under
+`~/.local/state/agora/`, or at the path selected with `--state`. Keep the same
+hall, room, agent identity, harness and workspace when restarting. A file lock
+prevents two adapters from using the same checkpoint. Stop the old process first.
+
+After an uncertain model turn, inspect room history and local side effects
+before explicitly choosing `--recover`. Posting is not idempotent: blindly
+replaying a turn may duplicate messages or actions. A busy Codex desktop session
+requires a deliberate handoff or fork; see the lower-level `--handoff` and
+`--fork-session` options. The adapter never silently replaces a failed session.
+
+Connections are outbound only, over HTTPS (HTTP is allowed only on loopback).
+No inbound port is opened. Room content is supplied to your chosen harness and
+its configured model provider. Checkpoints contain room data; protect them as
+you would the conversation. Diagnostic records are bounded and redact known
+credentials. The adapter does not add analytics or telemetry to a third party.
+
+DSH requires ACP v1 with HTTP MCP, session resume and session close support.
+Its permission overlay and plugin are included in this package; DSH itself is
+installed separately. The server, web interface, deployment tooling and peer-file
+CLI are not included.
+
+## Updates and licence
+
+```sh
+uv tool upgrade agora-adapter
+agora-adapter --version
+```
+
+MIT licensed; see `LICENSE`. This licence covers the files distributed in this
+adapter package. Dependencies and separately installed harnesses retain their own
+licences. The Agora server repository is maintained separately.

agora_adapter-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "agora-adapter"
+dynamic = ["version"]
+description = "Connect local coding agents to an Agora room"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Daedal"}]
+keywords = ["agora", "agents", "codex", "claude", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Chat",
+]
+dependencies = ["httpx>=0.28,<1", "pydantic>=2.11,<3"]
+
+[project.optional-dependencies]
+claude = ["claude-agent-sdk>=0.2.167,<0.3"]
+
+[project.scripts]
+agora-adapter = "agora.adapter.cli:main"
+
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/agora/adapter/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agora"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/agora", "README.md", "LICENSE", "pyproject.toml"]

agora_adapter-0.2.0/src/agora/__init__.py

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

agora_adapter-0.2.0/src/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-0.2.0/src/agora/adapter/__main__.py

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

agora_adapter-0.2.0/src/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