handler-ai 0.1.0__py3-none-any.whl

handler_cli/client.py

@@ -0,0 +1,81 @@
+"""Talking to handlerd: the Control API (contract D) over HTTP, ACP (contract C) over WebSocket.
+
+Discovery: `$HANDLER_URL` (default http://127.0.0.1:<DEFAULT_PORT>) and the token file
+`$HANDLER_CONFIG_DIR/token` (default ~/.config/handler-ai/token), written by the daemon on first
+start.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from handler_contracts import DEFAULT_PORT, TOKEN_FILE_NAME
+
+
+class ClientError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        status: int | None = None,
+        title: str | None = None,
+        detail: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status, self.title, self.detail = status, title, detail  # handlerd's answer, if any
+
+
+def base_url() -> str:
+    port = os.environ.get("HANDLER_PORT", str(DEFAULT_PORT))
+    return os.environ.get("HANDLER_URL", f"http://127.0.0.1:{port}").rstrip("/")
+
+
+def token_file() -> Path:
+    xdg = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return Path(os.environ.get("HANDLER_CONFIG_DIR", xdg / "handler-ai")) / TOKEN_FILE_NAME
+
+
+def read_token() -> str:
+    try:
+        return token_file().read_text().strip()
+    except FileNotFoundError:
+        raise ClientError(
+            f"no token at {token_file()}: is handlerd installed and started?"
+        ) from None
+
+
+class Daemon:
+    def __init__(self) -> None:
+        self.url = base_url()
+        self.token = read_token()
+        self.http = httpx.Client(
+            base_url=self.url, headers={"Authorization": f"Bearer {self.token}"}, timeout=60
+        )
+
+    def call(self, method: str, path: str, json: Any = None, timeout: float | None = None) -> Any:
+        r = self.request(method, path, json, timeout)
+        return r.json() if r.content else None
+
+    def text(self, path: str) -> str:
+        """A GET answering plain text (a log, a file)."""
+        return self.request("GET", path).text
+
+    def request(
+        self, method: str, path: str, json: Any = None, timeout: float | None = None
+    ) -> httpx.Response:
+        try:
+            r = self.http.request(method, path, json=json, timeout=timeout or self.http.timeout)
+        except httpx.ConnectError:
+            raise ClientError(
+                f"handlerd is not reachable at {self.url} (handler daemon status)"
+            ) from None
+        if r.status_code >= 400:
+            try:
+                problem = r.json()
+            except ValueError:
+                raise ClientError(f"{r.status_code} {r.text}", r.status_code) from None
+            title, detail = problem.get("title"), problem.get("detail")
+            message = f"{r.status_code} {title}: {detail or ''}".rstrip(": ")
+            raise ClientError(message, r.status_code, title, detail)
+        return r

handler_cli/daemon_commands.py

@@ -0,0 +1,108 @@
+"""`handler daemon …` — handlerd, the daemon that runs your agents, as a systemd user service
+(started with your session). `handler setup` installs it.
+
+handler daemon status                is it up (its version, its address); if not, the service's
+                                     state
+handler daemon install [--dry-run]   write the unit, enable and start it (--dry-run: print it)
+handler daemon uninstall             stop and disable it, remove the unit (configuration and state
+                                     are kept)
+handler daemon log [-f]              its log (journalctl; -f: follow it)
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .client import base_url
+
+UNIT_NAME = "handler-ai.service"
+
+
+def unit_path() -> Path:
+    xdg = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return xdg / "systemd" / "user" / UNIT_NAME
+
+
+def handlerd_path() -> str:
+    sibling = Path(sys.executable).parent / "handlerd"  # same installation as this CLI
+    return str(sibling) if sibling.exists() else (shutil.which("handlerd") or "handlerd")
+
+
+def unit_text() -> str:
+    handlerd = handlerd_path()
+    bin_dir = str(Path(handlerd).parent)
+    return f"""[Unit]
+Description=Handler control plane
+
+[Service]
+ExecStart={handlerd}
+# handlerd finds handler-sandbox-* next to itself; podman must be on PATH.
+Environment=PATH={bin_dir}:/usr/local/bin:/usr/bin:/bin
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _systemctl(*args: str) -> int:
+    return subprocess.run(["systemctl", "--user", *args], check=False).returncode
+
+
+def install(dry_run: bool) -> int:
+    if dry_run:
+        print(f"# {unit_path()}\n{unit_text()}", end="")
+        return 0
+    path = unit_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(unit_text())
+    print(f"wrote {path}")
+    return _systemctl("daemon-reload") or _systemctl("enable", "--now", UNIT_NAME)
+
+
+def uninstall() -> int:
+    _systemctl("disable", "--now", UNIT_NAME)
+    unit_path().unlink(missing_ok=True)
+    return _systemctl("daemon-reload")
+
+
+def status() -> int:
+    try:
+        health = httpx.get(f"{base_url()}/v1/health", timeout=5).json()
+    except httpx.HTTPError:
+        print(f"handlerd is not reachable at {base_url()}")
+        _systemctl("status", "--no-pager", UNIT_NAME)
+        return 1
+    print(f"handlerd {health['version']} up at {base_url()}")
+    return 0
+
+
+def log(follow: bool) -> int:
+    command = ["journalctl", "--user", "-u", UNIT_NAME, "--no-pager", "-n", "200"]
+    return subprocess.run([*command, *(["-f"] if follow else [])], check=False).returncode
+
+
+def add_parser(sub: Any) -> None:
+    daemon = sub.add_parser("daemon", help="handlerd as a user service", description=__doc__,
+                            formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    a = daemon.add_subparsers(dest="daemon_cmd", required=True)
+    a.add_parser("status")
+    a.add_parser("install").add_argument("--dry-run", action="store_true")
+    a.add_parser("uninstall")
+    a.add_parser("log").add_argument("-f", "--follow", action="store_true")
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    if args.daemon_cmd == "install":
+        return install(args.dry_run)
+    if args.daemon_cmd == "uninstall":
+        return uninstall()
+    if args.daemon_cmd == "log":
+        return log(args.follow)
+    return status()

handler_cli/image_commands.py

@@ -0,0 +1,102 @@
+"""`handler image …` — the images agents run in: the toolbox (the base every agent gets), one per
+harness and per addon on top of it, and the network filter. Built locally, through handlerd (D.4,
+G.4), like the web UI.
+
+    handler image list                 every image: built or not, the harness's version, when built
+    handler image rebuild NAME         rebuild a harness image from the files on disk (the
+                                       harness's latest release), check it, then switch agents to
+                                       it; the log streams to the terminal
+    handler image rebuild addon:NAME   same for an addon's image (also its first build)
+    handler image rebuild toolbox      same for the toolbox (system updates), then every harness and
+                                       addon on top of it: all switch, or none
+    handler image rebuild network-filter
+                                       the network filter: what checks where agents connect and adds
+                                       your secrets to their requests (handlerd builds it when it is
+                                       missing)
+
+Ctrl-C during a rebuild cancels it: nothing switches. Running sessions keep the image they started
+on.
+"""
+
+import argparse
+import sys
+import time
+from typing import Any
+
+from .client import Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    image = sub.add_parser("image", help="images", description=__doc__,
+                           formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    i = image.add_subparsers(dest="image_cmd", required=True)
+    i.add_parser("list")
+    i.add_parser("rebuild").add_argument(
+        "target", help="a harness name, 'toolbox', 'network-filter', or 'addon:NAME'"
+    )
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    d = Daemon()
+    if args.image_cmd == "list":
+        print_images(d)
+        return 0
+    return rebuild(d, args.target)
+
+
+def print_images(d: Daemon) -> None:
+    rows = [["NAME", "IMAGE", "VERSION", "BUILT"]]
+
+    def row(name: str, info: dict[str, Any], version: str = "-") -> None:
+        built = (info.get("builtAt") or "-")[:16].replace("T", " ")
+        rows.append([name, info["image"], version if info["imagePresent"] else "not built", built])
+
+    row("toolbox", d.call("GET", "/v1/toolbox"))
+    for h in d.call("GET", "/v1/harnesses"):
+        row(h["name"], h, h.get("version", "-"))
+    for a in d.call("GET", "/v1/addons"):
+        if a.get("image"):
+            row(f"addon:{a['name']}", a, a.get("version", "-"))
+    row("network-filter", d.call("GET", "/v1/network-filter"))
+    table(rows)
+
+
+def path(name: str) -> str:
+    """API path of a harness or `addon:NAME`."""
+    if name.startswith("addon:"):
+        return f"addons/{name.removeprefix('addon:')}"
+    return f"harnesses/{name}"
+
+
+def rebuild(d: Daemon, target: str) -> int:
+    own = target in ("toolbox", "network-filter")
+    return watch(d, d.call("POST", f"/v1/{target if own else path(target)}/rebuild"))
+
+
+def watch(d: Daemon, build: Any) -> int:
+    """Stream a started build's log to its end (Ctrl-C cancels it); 0 when it succeeded."""
+    try:
+        build = follow(d, build["id"])
+    except KeyboardInterrupt:
+        print("\ncancelling…", file=sys.stderr)
+        build = d.call("POST", f"/v1/builds/{build['id']}/cancel")
+    for name, version in build.get("versions", {}).items():
+        print(f"{name}: {version}")
+    error = f" ({build['error']})" if build.get("error") else ""
+    print(f"build {build['id']}: {build['state']}{error}")
+    return 0 if build["state"] == "succeeded" else 1
+
+
+def follow(d: Daemon, build_id: str) -> Any:
+    """Print the log as it grows; return the build once it has ended."""
+    offset = 0
+    while True:
+        chunk = d.call("GET", f"/v1/builds/{build_id}/log?offset={offset}")
+        sys.stdout.write(chunk["text"])
+        sys.stdout.flush()
+        offset = chunk["nextOffset"]
+        if chunk["complete"]:
+            return d.call("GET", f"/v1/builds/{build_id}")
+        if not chunk["text"]:
+            time.sleep(1)

handler_cli/inbox_commands.py

@@ -0,0 +1,33 @@
+"""`handler inbox` — what handler told you: your apps' notifications, your automations' results and
+failures, newest first (the web UI's Inbox)."""
+
+import argparse
+from typing import Any
+
+from .automation_commands import when_at
+from .client import Daemon
+from .output import one_line, table
+
+
+def add_parser(sub: Any) -> None:
+    sub.add_parser("inbox", help="what handler told you", description=__doc__)
+
+
+def dispatch(_: argparse.Namespace) -> int:
+    messages = Daemon().call("GET", "/v1/inbox")
+    if not messages:
+        print("nothing yet")
+        return 0
+    rows = [["AT", "FROM", "STATUS", "TITLE", "SUMMARY"]]
+    for m in messages:
+        source = f"{m['source']} {m['name']}"
+        unread = "" if m.get("read") else "• "
+        rows.append([
+            unread + when_at(m["at"]),
+            source,
+            m.get("status") or "-",
+            one_line(m["title"], 40),
+            one_line(m.get("summary") or "", 70),
+        ])  # fmt: skip
+    table(rows)
+    return 0

handler_cli/output.py

@@ -0,0 +1,12 @@
+"""Plain-text output shared by the commands."""
+
+
+def one_line(text: str, width: int) -> str:
+    flat = " ".join(text.split())
+    return flat if len(flat) <= width else flat[: width - 1] + "…"
+
+
+def table(rows: list[list[str]]) -> None:
+    widths = [max(len(r[i]) for r in rows) for i in range(len(rows[0]))]
+    for r in rows:
+        print("  ".join(cell.ljust(w) for cell, w in zip(r, widths, strict=True)).rstrip())

handler_cli/project_commands.py

@@ -0,0 +1,63 @@
+"""`handler project …` — projects: a folder and its agents (contract D.8), created and edited in
+the web UI. In a project's folder, `handler run`, `terminal` and `acp` use its agents.
+
+handler project list                 projects, most recently used first: context, agents, folder
+handler project show NAME            its agents (`*`: the default one), what each runs on and its
+                                     settings
+"""
+
+import argparse
+from typing import Any
+
+from .agent_commands import describe_agent, runs
+from .client import ClientError, Daemon
+from .output import table
+from .session_commands import agent_label
+
+
+def add_parser(sub: Any) -> None:
+    project = sub.add_parser("project", help="projects", description=__doc__,
+                             formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    p = project.add_subparsers(dest="project_cmd", required=True)
+    p.add_parser("list")
+    p.add_parser("show").add_argument("name")
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    d = Daemon()
+    projects = d.call("GET", "/v1/projects")
+    if args.project_cmd == "list":
+        rows = [["PROJECT", "CONTEXT", "AGENTS", "FOLDER"]]
+        for p in projects:
+            agents = ", ".join(agent_label(a) for a in p["agents"])
+            rows.append([p["name"], p.get("context") or "-", agents, p["folder"]])
+        table(rows) if len(rows) > 1 else print("no project: create one in the web UI (handler ui)")
+        return 0
+    wanted = args.name.lower()
+    found = next((p for p in projects if wanted in (p["name"].lower(), p["id"])), None)
+    if found is None:
+        names = ", ".join(p["name"] for p in projects) or "none"
+        raise ClientError(f"no project '{args.name}': {names}")
+    show(found)
+    return 0
+
+
+def show(p: dict[str, Any]) -> None:
+    context = f" · {p['context']}" if p.get("context") else ""
+    print(f"{p['name']}{context} · {p['folder']}")
+    if p.get("description"):
+        print(f"  {p['description']}")
+    rows = [["AGENT", "ID", "RUNS", "SETTINGS", "LIVE"]]
+    for a in p["agents"]:
+        default = " *" if a["id"] == p.get("defaultAgent") else ""
+        rows.append(
+            [
+                f"{agent_label(a)}{default}",
+                a["id"],
+                runs(a),
+                describe_agent(a, runs_too=False),
+                str(len(a["connections"])),
+            ]
+        )
+    table(rows)
+    print("* the project's default agent")

handler_cli/provider_commands.py

@@ -0,0 +1,113 @@
+"""`handler provider …` — providers (contract D.12): where model calls go when no subscription
+does, an API and its key (Anthropic, OpenAI, Mistral, OpenRouter) or a model server on this
+computer (llama.cpp, Ollama). A provider starts from a template; its key goes to handler's secret
+store, never shown again.
+
+handler provider list                the providers: endpoints, models, key, contexts, agents
+handler provider templates           what a provider can start from
+handler provider add NAME --from TEMPLATE [--key] [--endpoint PROTOCOL=URL …] [--model ID …]
+                     [--context CONTEXT …] [--description TEXT]
+                                     a provider from a template. --key: ask for its key (hidden,
+                                     or read from stdin). --endpoint: another URL for a protocol
+                                     (e.g. a server on another port). --model: the models it offers,
+                                     instead of the template's. --context: the project contexts it
+                                     is made for (Work, Personal…, or any; none: it runs nowhere a
+                                     project has a context)
+handler provider rm NAME             it and its key (agents using it cannot start until given
+                                     another)
+
+Models' details and per-harness files are edited in the web UI (Settings → Model access) or in
+~/.config/handler-ai/providers/NAME.toml.
+"""
+
+import argparse
+from typing import Any
+
+from .account_commands import ask_token
+from .client import ClientError, Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    provider = sub.add_parser("provider", help="providers", description=__doc__,
+                              formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    p = provider.add_subparsers(dest="provider_cmd", required=True)
+    p.add_parser("list")
+    p.add_parser("templates")
+    add = p.add_parser("add")
+    add.add_argument("name")
+    add.add_argument("--from", dest="template", required=True, metavar="TEMPLATE")
+    add.add_argument("--key", action="store_true", help="ask for its key")
+    add.add_argument("--endpoint", action="append", metavar="PROTOCOL=URL", default=[])
+    add.add_argument("--model", action="append", metavar="ID", default=[])
+    add.add_argument("--context", action="append", metavar="CONTEXT", default=[])
+    add.add_argument("--description")
+    p.add_parser("rm").add_argument("name")
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    d = Daemon()
+    if args.provider_cmd == "list":
+        rows = [["NAME", "STATUS", "ENDPOINTS", "MODELS", "KEY", "CONTEXTS", "AGENTS"]]
+        for p in d.call("GET", "/v1/providers"):
+            status = p["status"] if p["status"] == "ready" else "; ".join(
+                p.get("problems") or [p.get("error") or p["status"]])  # fmt: skip
+            rows.append(
+                [
+                    p["name"],
+                    status,
+                    ", ".join(p.get("endpoints", {})),
+                    ", ".join(m["id"] for m in p.get("models", [])),
+                    p.get("key") or "-",
+                    ", ".join(p.get("contexts", [])) or "-",
+                    ", ".join(p.get("agents", [])) or "-",
+                ]
+            )
+        table(rows) if len(rows) > 1 else print("no provider: handler provider templates")
+    elif args.provider_cmd == "templates":
+        rows = [["TEMPLATE", "KEY", "ENDPOINTS", "DESCRIPTION"]]
+        for t in d.call("GET", "/v1/provider-templates"):
+            needs = "needed" if t.get("needsKey") else "-"
+            endpoints = ", ".join(f"{k} {v}" for k, v in t["endpoints"].items())
+            rows.append([t["name"], needs, endpoints, t.get("description") or ""])
+        table(rows)
+    elif args.provider_cmd == "add":
+        made = d.call("POST", "/v1/providers", request(d, args))
+        print(f"{made['name']}: created ({made['status']})")
+    else:
+        d.call("DELETE", f"/v1/providers/{args.name}")
+        print(f"{args.name}: removed")
+    return 0
+
+
+def request(d: Daemon, args: argparse.Namespace) -> dict[str, Any]:
+    """`POST /v1/providers`'s body: the template, changed by the flags typed (as the web UI's form
+    starting from it)."""
+    templates = d.call("GET", "/v1/provider-templates")
+    template = next((t for t in templates if t["name"] == args.template), None)
+    if template is None:
+        names = ", ".join(t["name"] for t in templates)
+        raise ClientError(f"no template '{args.template}': {names}")
+    endpoints = dict(template["endpoints"])
+    for given in args.endpoint:
+        protocol, _, url = given.partition("=")
+        if not url:
+            raise ClientError(f"--endpoint {given}: PROTOCOL=URL, e.g. openai-chat=http://…")
+        endpoints[protocol] = url
+    models = template["models"]
+    if args.model:
+        known = {m["id"]: m for m in models}
+        models = [known.get(model, {"id": model}) for model in args.model]
+    body: dict[str, Any] = {
+        "name": args.name,
+        "description": args.description or template.get("description"),
+        "endpoints": endpoints,
+        "models": models,
+        "contexts": args.context,
+        "files": template.get("files"),
+    }
+    if args.key:
+        body["key"] = ask_token(args.name, "key")
+    elif template.get("needsKey"):
+        raise ClientError(f"{args.template} needs a key: add --key")
+    return body

handler_cli/secret_commands.py

@@ -0,0 +1,64 @@
+"""`handler secret …` — handler's secret store (contract D.14). A value is named by a path after
+what owns it (`providers/openrouter/apiKey`) and referenced from an account, a provider or a binding
+with `{ secret = "<path>" }`. Values are written, never read back. An app's secrets are set with
+`handler app secret`.
+
+handler secret list                  the secrets handler uses (in its store or kept elsewhere):
+                                     where each comes from, what it belongs to, and whether agents
+                                     can read it (else handler adds it to their requests to its
+                                     hosts)
+handler secret set PATH [--description TEXT]
+                                     set a value (asked for, or read from stdin)
+handler secret rm PATH               forget PATH and everything under it (refused while referenced)
+"""
+
+import argparse
+import getpass
+import sys
+from typing import Any
+
+from .client import Daemon
+from .output import table
+
+
+def add_parser(sub: Any) -> None:
+    secret = sub.add_parser("secret", help="the secret store", description=__doc__,
+                            formatter_class=argparse.RawDescriptionHelpFormatter)  # fmt: skip
+    s = secret.add_subparsers(dest="secret_cmd", required=True)
+    s.add_parser("list")
+    put = s.add_parser("set")
+    put.add_argument("path")
+    put.add_argument("--description")
+    s.add_parser("rm").add_argument("path")
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    d = Daemon()
+    if args.secret_cmd == "list":
+        rows = [["PATH", "FROM", "USED BY", "AGENTS", "UPDATED"]]
+        for s in d.call("GET", "/v1/secrets"):
+            source = s["source"] if s["hasValue"] else f"{s['source']} (not set)"
+            used = ", ".join(s["usedBy"]) or "nothing"
+            rows.append([s["path"], source, used, _given(s), (s.get("updatedAt") or "")[:16]])
+        table(rows) if len(rows) > 1 else print("no secret")
+        return 0
+    if args.secret_cmd == "set":
+        prompt = f"{args.path}: "
+        value = getpass.getpass(prompt) if sys.stdin.isatty() else sys.stdin.readline()
+        body = {"value": value.strip(), "description": args.description}
+        s = d.call("PUT", f"/v1/secrets/{args.path}", body)
+        print(f"{s['path']}: set (used by {', '.join(s['usedBy']) or 'nothing yet'})")
+        return 0
+    d.call("DELETE", f"/v1/secrets/{args.path}")
+    print(f"{args.path}: removed")
+    return 0
+
+
+def _given(s: dict[str, Any]) -> str:
+    """What agents get (E3): a stand-in handler swaps for the value on its way to its hosts, or the
+    value itself."""
+    if s.get("visible"):
+        return f"can read it: {s['visible']}"
+    if s["hosts"]:
+        return "never see it, handler adds it for " + ", ".join(s["hosts"])
+    return "-"

handler_cli/session_bridge.py

@@ -0,0 +1,93 @@
+"""`handler attach --stdio` and `handler acp AGENT`: a daemon-held session (F) as a plain stdio ACP
+agent, for editors (Zed) and terminal ACP clients.
+
+Such a client starts a conversation with `session/new`; a session already has one. So the bridge
+answers `session/new` with the session's own: it sends `session/load` instead (the daemon replays
+what was said) and adds the `sessionId` to the answer. A `session/load` of another id is pointed at
+the session's. The daemon's `_handler/*` notifications (state for its own clients) are not passed
+on. Everything else goes through unchanged, and the policy (C.4) applies in the daemon as usual.
+"""
+
+import json
+import sys
+import threading
+from typing import Any
+
+from websockets.exceptions import ConnectionClosed
+from websockets.sync.client import ClientConnection, connect
+from websockets.typing import Subprotocol
+
+from handler_contracts import ACP_SUBPROTOCOL, BEARER_SUBPROTOCOL_PREFIX, AcpCloseCode
+
+from .client import Daemon
+
+
+class SessionBridge:
+    def __init__(self, daemon: Daemon, session_id: str) -> None:
+        self.daemon = daemon
+        self.session_id = session_id
+        self.new_ids: set[Any] = set()  # the client's session/new requests, answered by a load
+        self.lock = threading.Lock()
+
+    def acp_session(self) -> dict[str, Any]:
+        return self.daemon.call("GET", f"/v1/sessions/{self.session_id}")
+
+    def to_daemon(self, msg: dict[str, Any]) -> dict[str, Any]:
+        method = msg.get("method")
+        if method in ("session/new", "session/load") and "id" in msg:
+            info = self.acp_session()  # asked after initialize: the agent runs, its id is known
+            params = {"sessionId": info["acpSessionId"], "cwd": info["scope"], "mcpServers": []}
+            if method == "session/new":
+                with self.lock:
+                    self.new_ids.add(msg["id"])
+            return msg | {"method": "session/load", "params": params}
+        return msg
+
+    def to_client(self, msg: dict[str, Any]) -> dict[str, Any] | None:
+        method = msg.get("method")
+        if isinstance(method, str) and method.startswith("_handler/"):
+            return None
+        with self.lock:
+            answered_new = "method" not in msg and msg.get("id") in self.new_ids
+            self.new_ids.discard(msg.get("id"))
+        if answered_new and isinstance(msg.get("result"), dict):
+            acp_id = self.acp_session()["acpSessionId"]
+            return msg | {"result": msg["result"] | {"sessionId": acp_id}}
+        return msg
+
+    def stdin_to_ws(self, ws: ClientConnection) -> None:
+        try:
+            for line in sys.stdin.buffer:
+                if not line.strip():
+                    continue
+                try:
+                    msg = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(msg, dict):
+                    ws.send(json.dumps(self.to_daemon(msg)))
+        except ConnectionClosed:
+            return
+        ws.close()  # the client closed our stdin: detach (the agent keeps running)
+
+    def run(self, acp_url: str) -> int:
+        token = self.daemon.token
+        protocols = [Subprotocol(ACP_SUBPROTOCOL), Subprotocol(BEARER_SUBPROTOCOL_PREFIX + token)]
+        with connect(acp_url, subprotocols=protocols, max_size=None) as ws:
+            threading.Thread(target=self.stdin_to_ws, args=(ws,), daemon=True).start()
+            try:
+                for message in ws:
+                    for line in str(message).splitlines():
+                        if line.strip() and (out := self.to_client(json.loads(line))) is not None:
+                            sys.stdout.write(json.dumps(out) + "\n")
+                            sys.stdout.flush()
+            except ConnectionClosed:
+                pass
+        if ws.close_code in (None, AcpCloseCode.NORMAL):
+            return 0
+        print(f"handler: session closed ({ws.close_code}) {ws.close_reason}", file=sys.stderr)
+        return 1
+
+
+def run_session_bridge(daemon: Daemon, session: dict[str, Any]) -> int:
+    return SessionBridge(daemon, session["id"]).run(session["acpUrl"])