handler-ai 0.1.0__py3-none-any.whl

handler_control/providers.py

@@ -0,0 +1,180 @@
+"""Providers — contract E, D.12: `~/.config/handler-ai/providers/<name>.toml`, an endpoint for
+each protocol it speaks, its key and its models, one per file, name = file stem. Written through the
+Control API (from a template of `templates/providers/`, or edited), or by hand. Through the API,
+its key goes to the secret store (`providers/<name>/apiKey`); a hand-written file may name an
+`env`, `file` or `command` key instead, which the API keeps as it is and never writes.
+
+Status: `ready` when its key, if it has one, resolves; `incomplete` with the problem otherwise;
+`invalid` when the file is not a valid provider.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomlkit
+from pydantic import ValidationError
+
+from handler_contracts import (
+    PROVIDER_API_VERSION,
+    CommandSecret,
+    Provider,
+    ProviderRequest,
+    ProviderTemplate,
+    StoreSecret,
+)
+from handler_harness import catalog
+
+from . import secrets
+from .files import describe, write_private
+
+
+class ProviderError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class LoadedProvider:
+    name: str
+    path: Path
+    provider: Provider | None
+    error: str | None = None  # set when the file is invalid (its agents are then unusable)
+
+
+def load(path: Path) -> LoadedProvider:
+    name = path.stem
+    if not path.is_file():
+        return LoadedProvider(name, path, None, f"no provider '{name}' ({path})")
+    try:
+        provider = Provider.from_toml(path.read_text())
+    except ValidationError as e:
+        return LoadedProvider(name, path, None, describe(e))
+    except (OSError, ValueError) as e:  # unreadable file, TOML syntax error
+        return LoadedProvider(name, path, None, str(e))
+    return LoadedProvider(name, path, provider)
+
+
+def get(directory: Path, name: str) -> LoadedProvider:
+    if "/" in name or name.startswith("."):
+        return LoadedProvider(name, directory / name, None, f"invalid provider name '{name}'")
+    return load(directory / f"{name}.toml")
+
+
+def load_all(directory: Path) -> list[LoadedProvider]:
+    if not directory.is_dir():
+        return []
+    return [load(p) for p in sorted(directory.glob("*.toml"))]
+
+
+def problems(provider: Provider, store: secrets.SecretStore) -> list[str]:
+    """What keeps it from being used as it is: a key that does not resolve. Resolving a `command`
+    key runs it: only `env` and `file` ones are checked."""
+    ref = provider.api_key
+    if ref is None or isinstance(ref, CommandSecret):
+        return []
+    try:
+        secrets.resolve_all({"apiKey": ref}, store)
+    except secrets.SecretError as e:
+        return [f"apiKey: {e}"]
+    return []
+
+
+def harnesses(provider: Provider) -> list[str]:
+    """The harnesses that speak one of its protocols."""
+    return [
+        h.name
+        for h in catalog.all_harnesses()
+        if provider.endpoint_for(h.descriptor.provider_protocols) is not None
+    ]
+
+
+def templates(templates_dir: Path) -> list[ProviderTemplate]:
+    return [
+        ProviderTemplate(
+            name=loaded.name,
+            description=p.description,
+            endpoints=dict(p.endpoints),
+            models=p.models,
+            needs_key=p.api_key is not None,
+            files=p.files,
+        )
+        for loaded in load_all(templates_dir / "providers")
+        if (p := loaded.provider) is not None
+    ]
+
+
+def key_path(name: str) -> str:
+    return f"providers/{name}/apiKey"
+
+
+def save(
+    directory: Path,
+    store: secrets.SecretStore,
+    request: ProviderRequest,
+    old: LoadedProvider | None,
+) -> LoadedProvider:
+    """Create the provider (`old` None) or replace `old`, renaming it to `request.name`: its key
+    follows. A new key goes to the secret store; without one, the key it has is kept."""
+    name = request.name
+    target = directory / f"{name}.toml"
+    if (old is None or old.name != name) and target.exists():
+        raise ProviderError(f"provider '{name}' exists")
+    key = old.provider.api_key if old is not None and old.provider is not None else None
+    files = old.provider.files if old is not None and old.provider is not None else None
+    if request.files is not None:
+        files = request.files
+    if old is not None and old.name != name:
+        store.rename(f"providers/{old.name}", f"providers/{name}")
+        if isinstance(key, StoreSecret) and key.secret == key_path(old.name):
+            key = StoreSecret(secret=key_path(name))
+    if request.key is not None:
+        store.put(key_path(name), request.key, f"key of the provider {name}")
+        key = StoreSecret(secret=key_path(name))
+    elif request.remove_key:
+        store.delete(key_path(name))
+        key = None
+    provider = Provider(
+        api_version=PROVIDER_API_VERSION,
+        description=request.description,
+        endpoints=request.endpoints,
+        api_key=key,
+        models=request.models,
+        files=files,
+        contexts=list(dict.fromkeys(request.contexts)),
+    )
+    write_private(target, _toml(provider))
+    if old is not None and old.name != name:
+        old.path.unlink(missing_ok=True)
+    return load(target)
+
+
+def delete(directory: Path, store: secrets.SecretStore, name: str) -> None:
+    (directory / f"{name}.toml").unlink(missing_ok=True)
+    store.delete(f"providers/{name}")
+
+
+def _toml(provider: Provider) -> str:
+    data = provider.model_dump(by_alias=True, exclude_defaults=True, mode="json")
+    doc = tomlkit.document()
+    for field in ("apiVersion", "description", "contexts"):
+        if field in data:
+            doc[field] = data[field]
+    if "apiKey" in data:
+        key = tomlkit.inline_table()
+        key.update(data["apiKey"])
+        doc["apiKey"] = key
+    doc["endpoints"] = data["endpoints"]
+    models = tomlkit.aot()
+    for model in data["models"]:
+        models.append(tomlkit.item(model))
+    doc["models"] = models
+    if "files" in data:  # [files.<harness>] slot = { content | file | env = … }
+        files = tomlkit.table(is_super_table=True)
+        for harness, slots in data["files"].items():
+            table = tomlkit.table()
+            for slot, source in slots.items():
+                entry = tomlkit.inline_table()
+                entry.update(source)
+                table[slot] = entry
+            files[harness] = table
+        doc["files"] = files
+    return tomlkit.dumps(doc)

handler_control/relay.py

@@ -0,0 +1,133 @@
+"""ACP relay — contract C transport: one WebSocket ↔ one agent process, through the policy.
+
+Security rules of the transport itself (on top of the policy):
+  - only single JSON objects are forwarded; batches and unparseable lines are dropped, so the
+    policy always sees every message the agent could act on;
+  - forwarded messages are re-serialized from what the policy inspected (no parser differential);
+  - one JSON-RPC message per WebSocket frame; binary frames close with 1003.
+"""
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Any
+
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from handler_contracts import AcpCloseCode
+
+from .agents import AgentRecord, AgentRegistry
+from .launcher import StartedAgent
+from .policy import AcpPolicy, ToAgent, ToClient, parse
+from .sandbox_process import read_stderr, stop
+
+log = logging.getLogger("handler.relay")
+
+
+class Relay:
+    def __init__(
+        self,
+        ws: WebSocket,
+        agent: StartedAgent,
+        policy: AcpPolicy,
+        record: AgentRecord,
+        registry: AgentRegistry,
+    ) -> None:
+        self.ws = ws
+        self.agent = agent
+        self.proc: asyncio.subprocess.Process = agent.process  # ty: ignore[invalid-assignment]
+        self.policy = policy
+        self.record = record
+        self.registry = registry
+        self.ws_lock = asyncio.Lock()
+        self.agent_lock = asyncio.Lock()
+        self.close_code: int = AcpCloseCode.NORMAL
+        self.close_reason = ""
+
+    async def to_client(self, msg: dict[str, Any]) -> None:
+        async with self.ws_lock:
+            await self.ws.send_text(json.dumps(msg))
+
+    async def to_agent(self, msg: dict[str, Any]) -> None:
+        assert self.proc.stdin is not None
+        async with self.agent_lock:
+            self.proc.stdin.write(json.dumps(msg).encode() + b"\n")
+            await self.proc.stdin.drain()
+
+    async def execute(self, actions: list[ToAgent | ToClient]) -> None:
+        for action in actions:
+            if isinstance(action, ToAgent):
+                await self.to_agent(action.msg)
+            else:
+                await self.to_client(action.msg)
+
+    # ── the three pumps ─────────────────────────────────────────────────
+
+    async def client_to_agent(self) -> None:
+        while True:
+            event = await self.ws.receive()
+            if event["type"] == "websocket.disconnect":
+                return
+            if event.get("bytes") is not None:
+                self.close_code, self.close_reason = AcpCloseCode.UNSUPPORTED_DATA, "binary frame"
+                return
+            for line in (event.get("text") or "").splitlines():
+                if not line.strip():
+                    continue
+                msg = parse(line)
+                if msg is None:
+                    log.warning(
+                        "[%s] dropped a non-object client message", self.agent.connection_id
+                    )
+                    continue
+                await self.execute(self.policy.from_client(msg))
+
+    async def agent_to_client(self) -> None:
+        assert self.proc.stdout is not None
+        while True:
+            try:
+                line = await self.proc.stdout.readline()
+            except (ValueError, asyncio.LimitOverrunError):
+                self.close_code, self.close_reason = (
+                    AcpCloseCode.MESSAGE_TOO_BIG,
+                    "agent message too big",
+                )
+                return
+            if not line:
+                code = await self.proc.wait()
+                self.close_code = AcpCloseCode.AGENT_EXITED
+                self.close_reason = f"agent exited ({code})"
+                return
+            msg = parse(line.decode(errors="replace"))
+            if msg is None:
+                log.warning("[%s] dropped a non-object agent message", self.agent.connection_id)
+                continue
+            await self.execute(self.policy.from_agent(msg))
+
+    # ── lifecycle (C.3) ─────────────────────────────────────────────────
+
+    async def serve(self) -> None:
+        pumps = [
+            asyncio.create_task(self.client_to_agent()),
+            asyncio.create_task(self.agent_to_client()),
+        ]
+        cid = self.agent.connection_id
+        stderr = asyncio.create_task(
+            read_stderr(self.proc, cid, lambda e: self.registry.add_event(self.record, cid, e))
+        )
+        try:
+            await asyncio.wait(pumps, return_when=asyncio.FIRST_COMPLETED)
+        except WebSocketDisconnect:
+            pass
+        finally:
+            for task in pumps:
+                task.cancel()
+            await self.stop_agent()
+            stderr.cancel()
+            with contextlib.suppress(Exception):
+                await self.ws.close(code=self.close_code, reason=self.close_reason[:120])
+
+    async def stop_agent(self) -> None:
+        """Closing the connection stops the sandbox (C.3)."""
+        await stop(self.proc)