handler-ai 0.1.0__py3-none-any.whl

handler_control/policy.py

@@ -0,0 +1,305 @@
+"""ACP policy pipeline — contract C.4, rules P1-P9.
+
+A pure state machine, independent of any transport: feed it one JSON-RPC message at a time
+(`from_client` / `from_agent`) and it returns what to send and to whom. The WebSocket relay
+(relay.py) is just a transport around it.
+
+    P1  initialize: force clientCapabilities fs/terminal off
+    P2  session/new|load|resume: cwd must be inside the agent's scope
+    P3  session/new|load|resume: HTTP MCP servers must be reachable under the network policy
+        (checked after P8, so the platform's own servers are checked too)
+    P4  agent→client fs/* and terminal/*: never forwarded, the agent gets an error
+    P5  client→agent `$/…` notifications (heartbeats): dropped
+    P6  `_…` extension methods: forwarded, logged
+    P7  after session/new or session/load: apply session defaults (mode, config options) before
+        the client sees the session; failure → the client gets an error, never a session in
+        the wrong mode (a loaded session runs in a new sandbox: the agent's mode applies again)
+    P8  session/new|load|resume: add the platform's MCP servers (its addons') to the
+        client's; a client server with the same name is replaced
+    P9  the first session/prompt of a session this connection started (session/new): the
+        agent's instructions before its text (a daemon session does it itself, F.3)
+"""
+
+import itertools
+import json
+import logging
+import posixpath
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from handler_contracts import (
+    BLOCKED_AGENT_METHOD_PREFIXES,
+    CWD_CHECKED_METHODS,
+    FilteredNetwork,
+    NetworkPolicy,
+    NoNetwork,
+    PolicyErrorCode,
+    SessionDefaults,
+    egress_target,
+    is_within,
+)
+
+log = logging.getLogger("handler.policy")
+
+Message = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToAgent:
+    msg: Message
+
+
+@dataclass(frozen=True)
+class ToClient:
+    msg: Message
+
+
+Action = ToAgent | ToClient
+
+
+def parse(line: str) -> Message | None:
+    """One line of an NDJSON stream as a JSON-RPC message; None when it is not a single object
+    (C.1: batches and unparseable lines are dropped)."""
+    try:
+        msg = json.loads(line)
+    except ValueError:
+        return None
+    return msg if isinstance(msg, dict) else None
+
+
+def is_request(m: Message) -> bool:
+    return "method" in m and "id" in m
+
+
+def is_notification(m: Message) -> bool:
+    return "method" in m and "id" not in m
+
+
+def is_response(m: Message) -> bool:
+    return "method" not in m and "id" in m
+
+
+def error_response(req_id: Any, code: PolicyErrorCode, rule: str, message: str) -> Message:
+    error = {"code": int(code), "message": message, "data": {"policy": rule}}
+    return {"jsonrpc": "2.0", "id": req_id, "error": error}
+
+
+def target_allowed(target: str, network: NetworkPolicy) -> bool:
+    """Whether 'host:port' is reachable under the network policy (A.3: the port must match)."""
+    if isinstance(network, NoNetwork):
+        return False
+    if not isinstance(network, FilteredNetwork):
+        return True  # open
+    host, _, port = target.rpartition(":")
+    for entry in network.allow:
+        entry_host, _, entry_port = entry.rpartition(":")
+        if entry_port != port:
+            continue
+        if entry_host.startswith("*.") and host.endswith(entry_host[1:]):
+            return True
+        if host == entry_host:
+            return True
+    return False
+
+
+@dataclass
+class _HeldSession:
+    """A session/new response held back while P7 applies the session defaults."""
+
+    response: Message
+    session_id: str
+    queue: list[Message]  # injected requests still to send, in order
+    failures: list[str] = field(default_factory=list)
+
+
+class AcpPolicy:
+    def __init__(
+        self,
+        *,
+        scope: str,
+        network: NetworkPolicy,
+        session_defaults: SessionDefaults | None = None,
+        instructions: str | None = None,
+        on_event: Callable[[str], None] | None = None,
+    ) -> None:
+        self.scope = scope
+        self.network = network
+        self.defaults = session_defaults
+        self.instructions = instructions
+        self.on_event = on_event or log.info
+        self._session_ids: dict[Any, str | None] = {}  # session/new|load request id → its sessionId
+        self._uninstructed: set[str] = set()  # sessions started here, their first prompt to come
+        self._held: dict[str, _HeldSession] = {}  # injected request id → held session
+        self._ids = itertools.count(1)
+
+    # ── client → agent ──────────────────────────────────────────────────
+
+    def from_client(self, m: Message) -> list[Action]:
+        method = m.get("method")
+        if is_notification(m) and isinstance(method, str) and method.startswith("$/"):
+            return []  # P5
+        if method == "initialize" and is_request(m):
+            return [ToAgent(self._force_capabilities(m))]  # P1
+        if method in CWD_CHECKED_METHODS and is_request(m):
+            m = self._add_mcp_servers(m)  # P8
+            if refusal := self.check_session_params(m):
+                return [ToClient(refusal)]  # P2 / P3
+            if method in ("session/new", "session/load"):
+                self._session_ids[m["id"]] = (m.get("params") or {}).get("sessionId")
+        if method == "session/prompt" and is_request(m):
+            m = self._p9_instruct(m)
+        if isinstance(method, str) and method.startswith("_"):
+            self.on_event(f"extension {method} (client→agent)")  # P6
+        return [ToAgent(m)]
+
+    def _p9_instruct(self, m: Message) -> Message:
+        params = m.get("params") or {}
+        session_id = params.get("sessionId")
+        if not self.instructions or session_id not in self._uninstructed:
+            return m
+        self._uninstructed.discard(session_id)
+        return m | {"params": params | {"prompt": instructed(self.instructions, params)}}
+
+    def _force_capabilities(self, m: Message) -> Message:
+        params = dict(m.get("params") or {})
+        caps = dict(params.get("clientCapabilities") or {})
+        caps["fs"] = {"readTextFile": False, "writeTextFile": False}
+        caps["terminal"] = False
+        params["clientCapabilities"] = caps
+        return m | {"params": params}
+
+    def _add_mcp_servers(self, m: Message) -> Message:
+        platform = (self.defaults.mcp_servers if self.defaults else None) or []
+        if not platform:
+            return m
+        params = dict(m.get("params") or {})
+        theirs = params.get("mcpServers") or []
+        if not isinstance(theirs, list):
+            return m  # malformed: forwarded as is, the agent refuses it
+        names = {s.name for s in platform}
+        client = []
+        for server in theirs:
+            if isinstance(server, dict) and server.get("name") in names:
+                self.on_event(f"client MCP server '{server['name']}' replaced by the platform's")
+            else:
+                client.append(server)
+        own = [s.model_dump(mode="json", by_alias=True, exclude_none=True) for s in platform]
+        params["mcpServers"] = client + own
+        return m | {"params": params}
+
+    def check_session_params(self, m: Message) -> Message | None:
+        params = m.get("params") or {}
+        cwd = params.get("cwd")
+        inside = (
+            isinstance(cwd, str)
+            and cwd.startswith("/")
+            and is_within(posixpath.normpath(cwd), self.scope)
+        )
+        if not inside:
+            return error_response(
+                m["id"], PolicyErrorCode.CWD_OUTSIDE_SCOPE, "P2", f"cwd must be inside {self.scope}"
+            )
+        for server in params.get("mcpServers") or []:
+            url = server.get("url") if isinstance(server, dict) else None
+            if not isinstance(url, str):
+                continue
+            try:
+                target = egress_target(url)
+            except (KeyError, ValueError):  # not http(s), or a bad port
+                target = url
+            if not target_allowed(target, self.network):
+                return error_response(
+                    m["id"], PolicyErrorCode.MCP_NOT_ALLOWED, "P3",
+                    f"MCP server {target} is not reachable under the network policy",
+                )  # fmt: skip
+        return None
+
+    # ── agent → client ──────────────────────────────────────────────────
+
+    def from_agent(self, m: Message) -> list[Action]:
+        method = m.get("method")
+        if isinstance(method, str) and method.startswith(BLOCKED_AGENT_METHOD_PREFIXES):
+            self.on_event(f"blocked agent→client {method}")
+            if is_request(m):  # P4
+                reply = error_response(
+                    m["id"], PolicyErrorCode.NOT_PERMITTED, "P4", "not permitted by sandbox policy"
+                )
+                return [ToAgent(reply)]
+            return []
+        if isinstance(method, str) and method.startswith("_"):
+            self.on_event(f"extension {method} (agent→client)")  # P6
+        if is_response(m):
+            if isinstance(m["id"], str) and m["id"] in self._held:
+                return self._p7_progress(m)
+            if m["id"] in self._session_ids:
+                return self._p7_start(m, self._session_ids.pop(m["id"]))
+        return [ToClient(m)]
+
+    # ── P7: session defaults ────────────────────────────────────────────
+
+    def _p7_start(self, response: Message, loaded: str | None) -> list[Action]:
+        result = response.get("result")
+        session_id = result.get("sessionId", loaded) if isinstance(result, dict) else None
+        if loaded is None and isinstance(session_id, str):
+            self._uninstructed.add(session_id)  # P9: a new session, its first prompt instructed
+        if not self.defaults or not isinstance(session_id, str):
+            return [ToClient(response)]
+        queue: list[Message] = []
+        if self.defaults.mode_id:
+            params = {"sessionId": session_id, "modeId": self.defaults.mode_id}
+            queue.append({"method": "session/set_mode", "params": params})
+        for config_id, value in (self.defaults.config_options or {}).items():
+            params = {"sessionId": session_id, "configId": config_id, "value": value}
+            queue.append({"method": "session/set_config_option", "params": params})
+        if not queue:
+            return [ToClient(response)]
+        held = _HeldSession(response=response, session_id=session_id, queue=queue)
+        return self._p7_send_next(held)
+
+    def _p7_send_next(self, held: _HeldSession) -> list[Action]:
+        request = held.queue.pop(0)
+        req_id = f"handler-p7-{next(self._ids)}"
+        self._held[req_id] = held
+        return [ToAgent({"jsonrpc": "2.0", "id": req_id, **request})]
+
+    def _p7_progress(self, response: Message) -> list[Action]:
+        held = self._held.pop(response["id"])
+        if "error" in response:
+            held.failures.append(str(response["error"].get("message", response["error"])))
+        if held.queue and not held.failures:
+            return self._p7_send_next(held)
+        if held.failures:
+            detail = "; ".join(held.failures)
+            self.on_event(f"session defaults failed for {held.session_id}: {detail}")
+            reply = error_response(
+                held.response["id"], PolicyErrorCode.SESSION_DEFAULTS_FAILED, "P7",
+                f"session defaults could not be applied: {detail}",
+            )  # fmt: skip
+            return [ToClient(reply)]
+        return [ToClient(self._patched(held.response))]
+
+    def _patched(self, response: Message) -> Message:
+        assert self.defaults is not None
+        result = dict(response["result"])
+        if self.defaults.mode_id and isinstance(result.get("modes"), dict):
+            result["modes"] = result["modes"] | {"currentModeId": self.defaults.mode_id}
+        wanted = self.defaults.config_options or {}
+        if wanted and isinstance(result.get("configOptions"), list):
+            result["configOptions"] = [
+                o | {"currentValue": wanted[o["id"]]}
+                if isinstance(o, dict) and o.get("id") in wanted
+                else o
+                for o in result["configOptions"]
+            ]
+        return response | {"result": result}
+
+
+def instructed(instructions: str, params: Message) -> list[Any]:
+    """A prompt's blocks with the agent's instructions before its text, a blank line between
+    them, in one text block: every adapter reads it (some would drop a second one)."""
+    blocks = list(params.get("prompt") or [])
+    if blocks and isinstance(blocks[0], dict) and blocks[0].get("type") == "text":
+        first = blocks[0]
+        return [first | {"text": f"{instructions}\n\n{first.get('text', '')}"}, *blocks[1:]]
+    return [{"type": "text", "text": instructions}, *blocks]

handler_control/projects.py

@@ -0,0 +1,266 @@
+"""Projects — what you work on: a code folder, its caches setting, the skills it gives to all
+its agents, and its agents.
+
+An agent of a project is an agent (agents.py) with a `project_id`, so its sessions and sandboxes
+are the same as for an ad-hoc one. Its settings are its own; this module keeps in step
+what it gets from its project: the folder, the caches setting and the project's skills.
+
+    ProjectRecord     one project, persisted in <state>/projects.json
+    ProjectRegistry   load, save, create, update, delete; its agents, resolved
+"""
+
+import json
+import secrets
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from handler_contracts import CacheSharing, RemoteAgent, RemoteProject
+
+from .agents import AgentRecord, AgentRegistry, CheckedSettings
+
+
+@dataclass
+class ProjectRecord:
+    id: str
+    name: str
+    folder: str
+    description: str | None = None
+    skills: list[str] = field(default_factory=list)  # given to all its agents (set by D.17)
+    default_agent: str | None = None
+    caches: CacheSharing = "project"  # the toolbox's caches for its agents (caches.py)
+    context: str | None = None  # its context: the accounts and providers it runs (contexts.py)
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    def __post_init__(self) -> None:
+        self.skills = sorted(set(self.skills))
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "folder": self.folder,
+            "description": self.description,
+            "skills": self.skills,
+            "defaultAgent": self.default_agent,
+            "caches": self.caches,
+            "context": self.context,
+            "createdAt": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_json(cls, r: dict[str, Any]) -> "ProjectRecord":
+        return cls(
+            id=r["id"],
+            name=r["name"],
+            folder=r["folder"],
+            description=r.get("description"),
+            skills=r.get("skills", []),
+            default_agent=r.get("defaultAgent"),
+            caches=r.get("caches", "project"),
+            context=r.get("context"),
+            created_at=datetime.fromisoformat(r["createdAt"]),
+        )
+
+
+def folder_name(folder: str) -> str:
+    return folder.rstrip("/").rsplit("/", 1)[-1] or folder
+
+
+class ProjectRegistry:
+    def __init__(self, state_dir: Path, registry: AgentRegistry) -> None:
+        self.file = state_dir / "projects.json"
+        self.registry = registry
+        self.projects: dict[str, ProjectRecord] = {}
+        if self.file.exists():
+            for r in json.loads(self.file.read_text()):
+                self.projects[r["id"]] = ProjectRecord.from_json(r)
+
+    def save(self) -> None:
+        self.file.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.file.with_suffix(".tmp")
+        tmp.write_text(json.dumps([p.to_json() for p in self.projects.values()], indent=2))
+        tmp.replace(self.file)
+
+    def new_id(self) -> str:
+        pid = "p_" + secrets.token_hex(5)
+        while pid in self.projects:
+            pid = "p_" + secrets.token_hex(5)
+        return pid
+
+    # ── reading ─────────────────────────────────────────────────────────
+
+    def get(self, pid: str) -> ProjectRecord | None:
+        return self.projects.get(pid)
+
+    def by_folder(self, folder: str) -> ProjectRecord | None:
+        return next((p for p in self.projects.values() if p.folder == folder), None)
+
+    def agents(self, project: ProjectRecord) -> list[AgentRecord]:
+        """Its agents: the default one first, then by name."""
+        agents = [w for w in list(self.registry.agents.values()) if w.project_id == project.id]
+        return sorted(agents, key=lambda w: (w.id != project.default_agent, (w.name or "").lower()))
+
+    def remote_agents(self) -> list[RemoteProject]:
+        """The projects and their agents paired devices may start sessions with (D.7)."""
+        listed: list[RemoteProject] = []
+        for project in sorted(self.projects.values(), key=lambda p: p.name.lower()):
+            agents = [
+                RemoteAgent(
+                    id=a.id,
+                    name=a.name or a.models[0].harness,
+                    description=a.description,
+                    default=a.id == project.default_agent,
+                )
+                for a in self.agents(project)
+                if a.remote_start
+            ]
+            if agents:
+                listed.append(
+                    RemoteProject(project_id=project.id, project=project.name, agents=agents)
+                )
+        return listed
+
+    def label(self, agent: AgentRecord) -> str | None:
+        """How a session's agent is named in short: "project · agent" for an agent of a
+        project."""
+        project = self.get(agent.project_id or "")
+        if project is None:
+            return agent.name
+        return f"{project.name} · {agent.name or agent.models[0].harness}"
+
+    def last_used(self, project: ProjectRecord) -> datetime | None:
+        used = [w.last_used_at for w in self.agents(project) if w.last_used_at]
+        return max(used) if used else None
+
+    # ── writing ─────────────────────────────────────────────────────────
+
+    def resolve(self, project: ProjectRecord, agent: AgentRecord) -> None:
+        """What the agent gets from its project: its folder, the caches setting, the project's
+        skills and its context."""
+        agent.scope = project.folder
+        agent.caches = project.caches
+        agent.context = project.context
+        agent.project_skills = list(project.skills)
+
+    def add(self, project: ProjectRecord) -> ProjectRecord:
+        self.projects[project.id] = project
+        self.save()
+        return project
+
+    def update(self, project: ProjectRecord, **fields: Any) -> None:
+        """Change its own settings; its agents follow at once (the caller applies what can change
+        in running sandboxes)."""
+        for key, value in fields.items():
+            setattr(project, key, value)
+        project.__post_init__()
+        for agent in self.agents(project):
+            self.resolve(project, agent)
+        self.registry.save()
+        self.save()
+
+    def delete(self, project: ProjectRecord) -> list[AgentRecord]:
+        """Remove it and its agents; returns the agents (the caller stops their sessions)."""
+        agents = self.agents(project)
+        for agent in agents:
+            self.registry.agents.pop(agent.id, None)
+        self.projects.pop(project.id, None)
+        self.registry.save()
+        self.save()
+        return agents
+
+    def add_agent(
+        self,
+        project: ProjectRecord,
+        settings: CheckedSettings,
+        *,
+        name: str,
+        description: str | None,
+        instructions: str | None,
+        default: bool = False,
+        remote_start: bool = False,
+        skills: list[str] | None = None,
+    ) -> AgentRecord:
+        agent = AgentRecord(
+            **settings.model_dump(),
+            name=name,
+            project_id=project.id,
+            description=description,
+            instructions=instructions,
+            remote_start=remote_start,
+            skills=sorted(set(skills or [])),
+        )
+        self.resolve(project, agent)
+        self.registry.add(agent)
+        if default or project.default_agent is None:
+            project.default_agent = agent.id
+            self.save()
+        return agent
+
+    def update_agent(
+        self,
+        project: ProjectRecord,
+        agent: AgentRecord,
+        settings: CheckedSettings,
+        *,
+        name: str,
+        description: str | None,
+        instructions: str | None,
+        default: bool = False,
+        remote_start: bool = False,
+        skills: list[str] | None = None,
+    ) -> None:
+        agent.set_settings(settings)
+        agent.name, agent.description, agent.instructions = name, description, instructions
+        agent.remote_start = remote_start
+        agent.skills = sorted(set(skills or []))
+        self.resolve(project, agent)
+        self.registry.save()
+        if default and project.default_agent != agent.id:
+            project.default_agent = agent.id
+            self.save()
+
+    def remove_agent(self, project: ProjectRecord, agent: AgentRecord) -> None:
+        self.registry.agents.pop(agent.id, None)
+        self.registry.save()
+        if project.default_agent == agent.id:
+            rest = self.agents(project)
+            project.default_agent = rest[0].id if rest else None
+            self.save()
+
+    # ── skills (D.17): the projects that give them to all their agents, the agents picking them ──
+
+    def skill_projects(self, name: str) -> list[ProjectRecord]:
+        """The projects that give a skill to all their agents."""
+        return [p for p in self.projects.values() if name in p.skills]
+
+    def skill_users(self, name: str) -> list[AgentRecord]:
+        return [w for w in self.registry.agents.values() if name in w.skills]
+
+    def give_skill(self, old: str | None, new: str, givers: list[ProjectRecord]) -> None:
+        """Skill `old` (None: a new one) is now `new`, given by `givers` to all their agents: the
+        agents picking it follow a rename, and drop it when their project gives it."""
+        ids = {p.id for p in givers}
+        for p in self.projects.values():
+            given = {new} if p.id in ids else set()
+            p.skills = sorted(({*p.skills} - {old or new, new}) | given)
+        for agent in self.skill_users(old or new):
+            kept: set[str] = set() if agent.project_id in ids else {new}
+            agent.skills = sorted(({*agent.skills} - {old or new}) | kept)
+        self._resolve_all()
+
+    def drop_skill(self, name: str) -> None:
+        """A deleted skill: no project gives it, no agent uses it."""
+        for p in self.projects.values():
+            p.skills = [s for s in p.skills if s != name]
+        for agent in self.skill_users(name):
+            agent.skills = [s for s in agent.skills if s != name]
+        self._resolve_all()
+
+    def _resolve_all(self) -> None:
+        for project in self.projects.values():
+            for agent in self.agents(project):
+                self.resolve(project, agent)
+        self.registry.save()
+        self.save()