handler-ai 0.1.0__py3-none-any.whl

handler_contracts/acp_endpoint.py

@@ -0,0 +1,69 @@
+"""Contract C — ACP endpoint and policy (`handler.acp-endpoint/v1`).
+
+Mostly behavioural; these are the wire-level constants every implementation and client share.
+"""
+
+from enum import IntEnum
+from typing import Literal
+from urllib.parse import quote
+
+ACP_ENDPOINT_API_VERSION = "handler.acp-endpoint/v1"
+
+ACP_SUBPROTOCOL = "acp.v1"
+"""WebSocket subprotocol the server must select (C.1)."""
+
+BEARER_SUBPROTOCOL_PREFIX = "bearer."
+"""Prefix of the subprotocol carrying the token: `bearer.<token>` (C.1)."""
+
+DEFAULT_MAX_MESSAGE_BYTES = 16 * 1024 * 1024
+"""Default maximum JSON-RPC message size (C.1)."""
+
+
+class AcpCloseCode(IntEnum):
+    NORMAL = 1000
+    PROTOCOL_ERROR = 1002
+    UNSUPPORTED_DATA = 1003
+    MESSAGE_TOO_BIG = 1009
+    AGENT_EXITED = 1011
+    ATTACHED_ELSEWHERE = 4001  # F.7: more attachments than allowed, the oldest is closed
+    SESSION_STOPPED = 4002  # F.4: stop, idle timeout or agent exit
+    TOO_SLOW = 4003  # F.7: the client did not read its traffic fast enough
+    # remote access to the session was switched off (docs/dev/design/remote.md)
+    REMOTE_DISABLED = 4004
+
+
+class SessionErrorCode(IntEnum):
+    """JSON-RPC errors of a Session's ACP endpoint (F.4)."""
+
+    ONE_SESSION_PER_ATTACHMENT = -32010
+    TURN_IN_PROGRESS = -32011
+    UNATTENDED = -32012  # a run of an agent with an interface takes no prompt (D.18)
+
+
+class PolicyErrorCode(IntEnum):
+    """JSON-RPC error codes emitted by the policy pipeline (C.4); `data.policy` names the rule."""
+
+    CWD_OUTSIDE_SCOPE = -32001  # P2
+    MCP_NOT_ALLOWED = -32002  # P3
+    NOT_PERMITTED = -32003  # P4
+    SESSION_DEFAULTS_FAILED = -32004  # P7
+
+
+PolicyRule = Literal["P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8"]
+
+BLOCKED_AGENT_METHOD_PREFIXES = ("fs/", "terminal/")
+"""Agent→client methods never forwarded (P4)."""
+
+CWD_CHECKED_METHODS = ("session/new", "session/load", "session/resume")
+"""Client→agent methods whose `cwd` is checked against the scope (P2), and which get the
+platform's MCP servers (P8)."""
+
+
+def acp_path(agent_id: str) -> str:
+    """URL path of an agent's ACP endpoint."""
+    return f"/v1/agents/{quote(agent_id, safe='')}/acp"
+
+
+def session_acp_path(session_id: str) -> str:
+    """URL path of a Session's ACP endpoint (F.4)."""
+    return f"/v1/sessions/{quote(session_id, safe='')}/acp"

handler_contracts/addon.py

@@ -0,0 +1,147 @@
+"""Contract G — Addon (`handler.addon/v1`) and binding (`handler.binding/v1`),
+docs/dev/design/addons.md.
+
+An addon says how to use a kind of system (a tool image, skills, env, slots, egress); it is
+platform-owned data in `addons/<name>/addon.toml`, like a harness descriptor. A binding is one
+addon bound to one instance of that system with its settings and secret references; it is
+user-owned TOML in `~/.config/handler-ai/bindings/<name>.toml`, like an account or a provider.
+"""
+
+import tomllib
+from typing import Annotated, Literal, Self
+
+from pydantic import Field, model_validator
+
+from .common import (
+    Document,
+    EgressEntry,
+    EnvMap,
+    EnvName,
+    SecretRef,
+    StrictDocument,
+)
+from .harness import ImageRepository, NonEmpty
+from .sandbox import CA_ENV
+
+ADDON_API_VERSION = "handler.addon/v1"
+BINDING_API_VERSION = "handler.binding/v1"
+
+# An addon's image is mounted read-only at <ADDONS_ROOT>/<name>; its `bin/` goes on PATH (G.2).
+ADDONS_ROOT = "/opt/addons"
+# Every addon image records what it installed here (relative to its root), like IMAGE_VERSION_FILE.
+ADDON_VERSION_FILE = "version"
+
+AddonName = Annotated[str, Field(pattern=r"^[a-z0-9][a-z0-9-]*$")]
+BindingName = Annotated[str, Field(pattern=r"^[a-z0-9][a-z0-9_.-]*$")]
+SlotName = Annotated[str, Field(pattern=r"^[a-z][a-z0-9_]*$")]
+CommandName = Annotated[str, Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9_.+-]*$")]
+
+# Env vars the platform owns: an addon may not set them (PATH is extended through `bin/`; the CA
+# variables point at the roots the sandbox trusts when its proxy gives secrets, A.3).
+RESERVED_ENV = frozenset({"PATH", "HOME", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY"}) | CA_ENV
+
+
+class AddonSlot(Document):
+    """A setting or secret slot: the binding's value is exported as `env`."""
+
+    env: EnvName
+    required: bool = False
+    description: str | None = None
+
+
+class AddonSecretSlot(AddonSlot):
+    """A secret slot: its value reaches the agent's sandbox as a phantom its proxy swaps back
+    towards `hosts` (E3, A.3), or with `delivery = "env"` as it is, for a tool that cannot be
+    given a phantom (it signs its requests with the secret, or speaks something else than HTTP)."""
+
+    hosts: list[EgressEntry] | None = None  # where the secret goes: some of `egress` (default all)
+    delivery: Literal["proxy", "env"] = "proxy"
+
+
+class AddonMcp(Document):
+    """An MCP server the addon provides, over stdio, started from one of its own `commands`
+    (installed at build time). Added to the agent's MCP servers under the addon's name."""
+
+    command: Annotated[list[NonEmpty], Field(min_length=1)]
+
+
+class AddonManifest(Document):
+    api_version: Literal["handler.addon/v1"]
+    name: AddonName
+    description: str | None = None
+    image: ImageRepository | None = None  # None: an addon without a tool (skills, env, egress)
+    commands: list[CommandName] = []  # exactly what the image's bin/ provides (checked at build)
+    check: Annotated[list[NonEmpty], Field(min_length=1)] | None = None  # run by a rebuild (G.4)
+    env: EnvMap | None = None
+    settings: dict[SlotName, AddonSlot] = {}
+    secret_slots: dict[SlotName, AddonSecretSlot] = {}
+    egress: list[EgressEntry] = []
+    mcp: AddonMcp | None = None
+
+    @model_validator(mode="after")
+    def _consistent(self) -> Self:
+        if self.image is None and (self.commands or self.check):
+            raise ValueError("'commands' and 'check' need an 'image'")
+        if self.mcp and self.mcp.command[0] not in self.commands:
+            raise ValueError("'mcp.command' must start with one of the addon's 'commands'")
+        if self.image is not None and not self.commands:
+            raise ValueError("an addon with an 'image' must declare its 'commands'")
+        if len(set(self.commands)) != len(self.commands):
+            raise ValueError("'commands' has duplicates")
+        names = [
+            *(self.env or {}),
+            *(s.env for s in self.settings.values()),
+            *(s.env for s in self.secret_slots.values()),
+        ]
+        if reserved := sorted(set(names) & RESERVED_ENV):
+            raise ValueError(f"env vars owned by the platform: {', '.join(reserved)}")
+        if len(set(names)) != len(names):
+            raise ValueError("an env var is set twice (env, settings and secretSlots must differ)")
+        if clash := sorted(self.settings.keys() & self.secret_slots.keys()):
+            raise ValueError(f"slot names used for both a setting and a secret: {', '.join(clash)}")
+        for name, slot in self.secret_slots.items():
+            if slot.hosts is not None and slot.delivery == "env":
+                raise ValueError(f"secret {name}: 'hosts' are for the proxy, not 'env' delivery")
+            if outside := sorted(set(slot.hosts or []) - set(self.egress)):
+                raise ValueError(f"secret {name}: hosts not in 'egress': {', '.join(outside)}")
+        return self
+
+    def secret_hosts(self, slot: str) -> list[str] | None:
+        """Where a secret slot's value goes through the proxy (A.3); None: given as it is."""
+        declared = self.secret_slots[slot]
+        if declared.delivery == "env":
+            return None
+        return list(self.egress if declared.hosts is None else declared.hosts)
+
+    @property
+    def mount_target(self) -> str:
+        return f"{ADDONS_ROOT}/{self.name}"
+
+    @property
+    def bin_dir(self) -> str:
+        return f"{self.mount_target}/bin"
+
+
+class Binding(StrictDocument):
+    api_version: Literal["handler.binding/v1"]
+    addon: AddonName
+    description: str | None = None
+    settings: dict[SlotName, str] | None = None
+    secrets: dict[SlotName, SecretRef] | None = None  # references only, never values (E2)
+
+    @classmethod
+    def from_toml(cls, text: str) -> "Binding":
+        return cls.model_validate(tomllib.loads(text))
+
+
+def check_binding(binding: Binding, manifest: AddonManifest) -> None:
+    """G1: a binding only fills slots its addon declares, and fills every required one.
+    Raises ValueError with a readable message."""
+    for kind, bound, slots in (
+        ("setting", binding.settings or {}, manifest.settings),
+        ("secret", binding.secrets or {}, manifest.secret_slots),
+    ):
+        if unknown := sorted(bound.keys() - slots.keys()):
+            raise ValueError(f"{kind} {', '.join(unknown)} not declared by addon '{manifest.name}'")
+        if missing := sorted(n for n, s in slots.items() if s.required and n not in bound):
+            raise ValueError(f"required {kind} {', '.join(missing)} is missing")

handler_contracts/agent_spec.py

@@ -0,0 +1,75 @@
+"""Contract E — what an agent runs as: a harness, the account (`handler.account/v1`, account.py) or
+the provider (`handler.provider/v1`, provider.py) its model calls use, and a model. An agent (D.8)
+names them; `AgentSpec` is them resolved (the account's login and plan, the provider and its files
+for this harness): what `render` takes (B.3)."""
+
+from typing import Annotated, Self
+
+from pydantic import Field, model_validator
+
+from .account import Account
+from .common import FileSource, HostPath, ResourceName, StrictDocument
+from .provider import Provider
+
+HarnessName = Annotated[str, Field(min_length=1, pattern=r"^[a-z0-9][a-z0-9-]*$")]
+
+
+class NeutralConfig(StrictDocument):
+    """Harness-neutral agent configuration (B.2)."""
+
+    model: Annotated[str, Field(min_length=1)] | None = None
+    account_connectors: bool = False  # decision 1: off by default (the account's `connectors`)
+
+
+class AgentSpec(StrictDocument):
+    """An agent's harness with its account or its provider (exactly one), resolved."""
+
+    harness: HarnessName
+    account: ResourceName | None = None  # its name (accounts/<name>.toml)...
+    provider: ResourceName | None = None  # ...or this one's (providers/<name>.toml)
+    # the account's credential file, when its harness's login leaves one and it exists (set by
+    # the control plane, which keeps it); a token login is resolved at launch
+    account_login: HostPath | None = None
+    account_plan: str | None = None  # the account's plan (told to the harness, B.3)
+    provider_spec: Provider | None = None
+    files: dict[str, FileSource] | None = None  # the provider's for this harness (config slots)
+    config: NeutralConfig = NeutralConfig()
+
+    @model_validator(mode="after")
+    def _account_or_provider(self) -> Self:
+        if (self.account is None) == (self.provider is None):
+            raise ValueError("name exactly one of 'account' (its login) and 'provider' (its model)")
+        return self
+
+    @classmethod
+    def resolve(
+        cls,
+        harness: str,
+        model: str | None = None,
+        *,
+        account: tuple[str, Account] | None = None,
+        provider: tuple[str, Provider] | None = None,
+    ) -> "AgentSpec":
+        """`account` / `provider`: (name, document). ValueError when the account is another
+        harness's."""
+        if account is not None:
+            name, found = account
+            if found.harness != harness:
+                other = found.harness
+                raise ValueError(f"account '{name}' is for harness '{other}', not '{harness}'")
+            return cls(
+                harness=harness,
+                account=name,
+                account_plan=found.plan,
+                config=NeutralConfig(model=model, account_connectors=found.connectors),
+            )
+        if provider is None:
+            raise ValueError("name exactly one of 'account' (its login) and 'provider' (its model)")
+        name, spec = provider
+        return cls(
+            harness=harness,
+            provider=name,
+            provider_spec=spec,
+            files=(spec.files or {}).get(harness),
+            config=NeutralConfig(model=model),
+        )

handler_contracts/automation.py

@@ -0,0 +1,285 @@
+"""Contract I — Automations (`handler.automation/v1`): *when this happens, run that*. When a session
+stops or a schedule comes, handlerd runs the automation's run: the user's script in a sandbox (which
+may call models through handlerd's `llm` service, and whose files handlerd appends to knowledge
+notes), an agent with an interface (its result goes to the inbox), or a mini app's route.
+
+`Automation` is hand-written TOML (`<config>/automations/<name>/automation.toml`): unknown keys
+are errors. The rest is exchanged: the Control API's views and requests (I.9), and the `llm/v1`
+service's one tool, `llm_complete` (I.5).
+"""
+
+import tomllib
+from typing import Annotated, Any, Literal, Self
+
+from pydantic import AfterValidator, AwareDatetime, Field, model_validator
+
+from .common import Document, StrictDocument
+from .miniapp import AppName
+
+AUTOMATION_API_VERSION = "handler.automation/v1"
+AUTOMATION_FILE = "automation.toml"
+
+AutomationName = Annotated[str, Field(pattern=r"^[a-z0-9][a-z0-9-]{0,63}$")]
+AutomationEvent = Literal["session.stopped"]  # an event `when` (I.2); a schedule is the other
+# a provider's model, "provider/model": the provider's name, then its model's id
+LlmModel = Annotated[str, Field(pattern=r"^[a-z0-9][a-z0-9_.-]*/.+$")]
+RunState = Literal["queued", "running", "succeeded", "failed", "cancelled", "interrupted"]
+Day = Literal["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
+
+MIN_EVERY_MINUTES = 5
+DEFAULT_TIMEOUT_SEC = 600  # a script's (I.3)
+MAX_LLM_INPUT = 256 * 1024  # system + prompt + input, in bytes (I.5)
+MAX_LLM_SCHEMA = 64 * 1024
+MAX_APPEND = 256 * 1024  # one `from` file (I.6)
+
+
+def _output_path(p: str) -> str:
+    if p.startswith("/") or ".." in p.split("/"):
+        raise ValueError("must be relative to the run's output folder, without '..'")
+    return p
+
+
+class Schedule(StrictDocument):
+    """A `when` that is a time (I.2): every N minutes or hours, or at a local time of day."""
+
+    every: Annotated[str, Field(pattern=r"^[1-9]\d{0,3}[mh]$")] | None = None  # "30m", "2h"
+    at: Annotated[str, Field(pattern=r"^([01]\d|2[0-3]):[0-5]\d$")] | None = None  # local time
+    days: list[Day] | None = None  # with `at`; default every day
+
+    @model_validator(mode="after")
+    def _one_rule(self) -> Self:
+        if (self.every is None) == (self.at is None):
+            raise ValueError("a schedule has either 'every' or 'at'")
+        if self.days is not None and self.at is None:
+            raise ValueError("'days' goes with 'at'")
+        if not (self.days is None or self.days):
+            raise ValueError("'days' lists at least one day")
+        if self.every_minutes is not None and self.every_minutes < MIN_EVERY_MINUTES:
+            raise ValueError(f"'every' is at least {MIN_EVERY_MINUTES}m")
+        return self
+
+    @property
+    def every_minutes(self) -> int | None:
+        if self.every is None:
+            return None
+        return int(self.every[:-1]) * (60 if self.every.endswith("h") else 1)
+
+    @property
+    def label(self) -> str:
+        """ "every 1h", "at 08:30", "at 08:30 mon,fri"."""
+        if self.every is not None:
+            return f"every {self.every}"
+        return " ".join(x for x in (f"at {self.at}", ",".join(self.days or [])) if x)
+
+
+class AutomationOnly(StrictDocument):
+    """The sessions an automation is for: by their project's name, their agent's; absent: any."""
+
+    project: list[str] | None = None
+    agent: list[str] | None = None
+
+
+class AutomationServices(StrictDocument):
+    llm: list[LlmModel] = []  # the models the script may call (I.5)
+
+
+class AutomationAppend(StrictDocument):
+    """A file the run wrote, appended by handlerd to a knowledge note once the run succeeded
+    (I.6)."""
+
+    from_: Annotated[str, Field(alias="from", min_length=1), AfterValidator(_output_path)]
+    to: Annotated[str, Field(min_length=1)]  # a markdown note, relative to the knowledge root
+
+
+class AutomationSubject(StrictDocument):
+    skill: Annotated[str, Field(min_length=1)]  # a skill of the library (D.17)
+
+
+class AutomationAgentInput(StrictDocument):
+    """What the agent's run is started with (D.18 `SessionInput`)."""
+
+    fields: dict[str, Any] = {}
+    subject: AutomationSubject | None = None
+
+
+class AutomationAgentRun(StrictDocument):
+    """`run = { agent, project?, input? }`: a run of an agent with an interface (I.3, D.18)."""
+
+    agent: Annotated[str, Field(min_length=1)]  # its name
+    project: str | None = None  # its project's name; absent: an agent of no project
+    input: AutomationAgentInput = AutomationAgentInput()
+
+
+class AutomationAppCall(StrictDocument):
+    """`run = { app, call }`: a call to a mini app's route, as the owner (I.3, H.9)."""
+
+    app: AppName
+    call: Annotated[str, Field(pattern=r"^POST /api/[A-Za-z0-9/_.-]*$")]
+
+
+class Automation(StrictDocument):
+    """automation.toml (I.1)."""
+
+    api_version: Literal["handler.automation/v1"]
+    description: str | None = None
+    when: AutomationEvent | Schedule
+    only: AutomationOnly | None = None  # with `session.stopped`
+    # a script: a command line (`sh -c`), in its folder; or an agent run; or an app's route
+    run: Annotated[str, Field(min_length=1)] | AutomationAgentRun | AutomationAppCall
+    timeout_sec: Annotated[int, Field(ge=1, le=3600)] | None = None  # a script's, default 600
+    services: AutomationServices | None = None  # a script's
+    append: list[AutomationAppend] = []  # a script's
+
+    @model_validator(mode="after")
+    def _fits(self) -> Self:
+        if self.only is not None and self.schedule is not None:
+            raise ValueError("'only' goes with when = \"session.stopped\"")
+        if self.script is None:
+            for key, value in (
+                ("timeoutSec", self.timeout_sec),
+                ("services", self.services),
+                ("append", self.append or None),
+            ):
+                if value is not None:
+                    raise ValueError(f"'{key}' goes with a script run")
+        return self
+
+    @property
+    def schedule(self) -> Schedule | None:
+        return self.when if isinstance(self.when, Schedule) else None
+
+    @property
+    def script(self) -> str | None:
+        return self.run if isinstance(self.run, str) else None
+
+    @property
+    def agent_run(self) -> AutomationAgentRun | None:
+        return self.run if isinstance(self.run, AutomationAgentRun) else None
+
+    @property
+    def app_call(self) -> AutomationAppCall | None:
+        return self.run if isinstance(self.run, AutomationAppCall) else None
+
+    @classmethod
+    def from_toml(cls, text: str) -> Self:
+        return cls.model_validate(tomllib.loads(text))
+
+
+class AutomationLlmUsage(Document):
+    calls: int = 0
+    in_tokens: int = 0
+    out_tokens: int = 0
+
+
+class AutomationAppended(Document):
+    to: str
+    bytes: int
+    text: str | None = None  # a try's preview: the first 4 KiB of what it would append
+
+
+class AutomationRun(Document):
+    id: str  # "a_" + 16 hex
+    automation: AutomationName
+    trial: bool = False
+    session_id: str | None = None  # the stopped session it read (I.4)
+    seq_from: int | None = None
+    seq_to: int | None = None
+    slot: AwareDatetime | None = None  # the schedule's slot it ran for
+    missed: int = 0  # slots before it, missed while handlerd was not running (only the last runs)
+    agent_session_id: str | None = None  # an agent run's session (D.18)
+    state: RunState
+    exit_code: int | None = None
+    ms: int | None = None
+    llm: AutomationLlmUsage = AutomationLlmUsage()
+    appended: list[AutomationAppended] = []
+    error: str | None = None
+    created_at: AwareDatetime
+    ended_at: AwareDatetime | None = None
+
+
+class AutomationView(Document):
+    name: AutomationName
+    description: str | None = None
+    definition: Automation | None = None  # absent when it does not parse
+    directory: str  # its folder, where its files are edited
+    files: list[str] = []  # relative to it
+    problems: list[str] = []
+    enabled: bool = False
+    permissions: list[str] = []  # what it may touch and what starts it, in sentences (I.7)
+    warnings: list[str] = []  # what to know before turning it on (an account's terms, I.7)
+    next_at: AwareDatetime | None = None  # a scheduled one's next slot, while it is on
+    pending: int = 0  # runs waiting
+    behind: AutomationName | None = None  # what runs now, when its runs wait (one at a time)
+    capped: bool = False  # the daily cap is reached
+    last_run: AutomationRun | None = None
+
+
+class AutomationExample(Document):
+    """An example automation handler ships (I.1), copied by `POST /v1/automations`."""
+
+    name: AutomationName
+    description: str | None = None
+
+
+class CreateAutomationRequest(Document):
+    """A new automation, off: a shipped example copied, or a definition handler writes as its
+    automation.toml (the web UI's form, I.1). With `enable`, turned on at once (I.7)."""
+
+    name: AutomationName
+    from_: Annotated[AutomationName | None, Field(alias="from")] = None  # a shipped example
+    definition: Automation | None = None
+    enable: bool = False
+
+    @model_validator(mode="after")
+    def _one_source(self) -> Self:
+        if (self.from_ is None) == (self.definition is None):
+            raise ValueError("give either 'from' (an example) or 'definition'")
+        if self.from_ is not None and self.enable:
+            raise ValueError("an example is created off: edit it, then turn it on")
+        return self
+
+
+class AutomationDefinitionRequest(Document):
+    """A definition to check (`POST /v1/automations/check`) or to write over an automation's
+    automation.toml (`PUT /v1/automations/{name}`: the web UI's form, I.1)."""
+
+    definition: Automation
+
+
+class AutomationCheck(Document):
+    """What a definition would do before it is saved (I.9): what `AutomationView` would say."""
+
+    problems: list[str] = []
+    warnings: list[str] = []
+    permissions: list[str] = []
+    next_at: AwareDatetime | None = None  # a schedule's first slot if it were turned on now
+
+
+class TryAutomationRequest(Document):
+    session_id: str | None = None  # the session read, for `when = "session.stopped"` (I.8)
+
+
+class LlmUsage(StrictDocument):
+    in_tokens: int
+    out_tokens: int
+
+
+class LlmRequest(StrictDocument):
+    """`llm_complete`'s input (I.5)."""
+
+    model: LlmModel  # one of the automation's `services.llm`
+    system: str | None = None
+    prompt: Annotated[str, Field(min_length=1)]
+    input: str | None = None
+    schema_: Annotated[dict[str, Any] | None, Field(alias="schema")] = None
+
+
+class LlmResponse(StrictDocument):
+    """`llm_complete`'s output (I.5)."""
+
+    valid: bool
+    value: Any = None  # with a schema: the parsed answer
+    text: str | None = None  # without one: the answer
+    error: str | None = None  # why it is not valid (its JSON, after the repair turn)
+    usage: LlmUsage
+    ms: int