hrns 0.0.1__py3-none-any.whl

hrns/__init__.py

@@ -0,0 +1,13 @@
+"""hrns: programmable Pydantic AI agents with an ACP terminal and hosting.
+
+The distribution exposes independent subpackages:
+
+- ``hrns.protocol``: versioned contracts and transport framing.
+- ``hrns.config``: shared local settings.
+- ``hrns.runtime``: native agent definitions, sessions, and ACP hosting.
+- ``hrns.client``: Textual terminal, headless runner, and stdio bridge.
+- ``hrns.server``: authenticated deployment catalog and worker hosting.
+
+Importing ``hrns`` does not import any subpackage, so the client and server
+keep their independent dependency boundaries.
+"""

hrns/client/__init__.py

@@ -0,0 +1,120 @@
+"""The standalone hrns client: ACP terminal, headless runner, bridge.
+
+This module does not import ``hrns.runtime``. It speaks ACP v1
+with third-party agents over stdio and with project hosts over the versioned
+WebSocket transport. The UI is Textual; the network layer is ``acp``,
+``websockets`` and ``httpx``.
+"""
+
+from ._version import __version__
+from .catalog import AgentDeployment, AgentPage, CatalogClient
+from .client import HrnsAcpClient
+from .errors import (
+    CatalogError,
+    ConnectionLost,
+    ExtensionUnavailable,
+    HrnsClientError,
+    InteractionRejected,
+    InteractionRequired,
+    ProtocolError,
+    SecretMissing,
+    TransportError,
+)
+from .events import (
+    AgentTextChunk,
+    CapabilitiesListed,
+    CommandsUpdated,
+    ConfigOptionsUpdated,
+    ConfigurationChanged,
+    ConnectionEvent,
+    ModesUpdated,
+    PlanChanged,
+    PluginListed,
+    SessionsListed,
+    ToolEvent,
+    TurnCompleted,
+    TurnStarted,
+    UsageUpdated,
+    UserMessageReplayed,
+)
+from .interactions import (
+    PERMISSION_MODES,
+    READ_ONLY_KINDS,
+    AskUserAnswer,
+    AskUserOption,
+    AskUserQuestion,
+    AskUserRequest,
+    AskUserResponse,
+    ElicitationAnswer,
+    ElicitationRequest,
+    HeadlessInteractions,
+    InteractionPolicy,
+    PermissionDecision,
+    PermissionRequest,
+    RequireInteractions,
+    ask_user_payload,
+    auto_permission,
+    parse_ask_user_request,
+)
+from .profiles import Profile, Profiles, default_profiles_path, secret_value
+from .renderers import RendererRegistry, readable_text
+from .session import SessionProxy
+from .transport import StdioAgentTransport, WebSocketAgentTransport
+
+__all__ = [
+    "__version__",
+    "AgentDeployment",
+    "AgentPage",
+    "AgentTextChunk",
+    "AskUserAnswer",
+    "AskUserOption",
+    "AskUserQuestion",
+    "AskUserRequest",
+    "AskUserResponse",
+    "CapabilitiesListed",
+    "CatalogClient",
+    "CatalogError",
+    "CommandsUpdated",
+    "ConfigOptionsUpdated",
+    "ConfigurationChanged",
+    "ConnectionEvent",
+    "ConnectionLost",
+    "ElicitationAnswer",
+    "ElicitationRequest",
+    "ExtensionUnavailable",
+    "HrnsAcpClient",
+    "HrnsClientError",
+    "HeadlessInteractions",
+    "InteractionPolicy",
+    "InteractionRejected",
+    "InteractionRequired",
+    "ModesUpdated",
+    "PERMISSION_MODES",
+    "PermissionDecision",
+    "PermissionRequest",
+    "PlanChanged",
+    "PluginListed",
+    "Profile",
+    "Profiles",
+    "ProtocolError",
+    "READ_ONLY_KINDS",
+    "RendererRegistry",
+    "RequireInteractions",
+    "SecretMissing",
+    "SessionProxy",
+    "SessionsListed",
+    "StdioAgentTransport",
+    "ToolEvent",
+    "TransportError",
+    "TurnCompleted",
+    "TurnStarted",
+    "UsageUpdated",
+    "UserMessageReplayed",
+    "ask_user_payload",
+    "auto_permission",
+    "parse_ask_user_request",
+    "WebSocketAgentTransport",
+    "default_profiles_path",
+    "readable_text",
+    "secret_value",
+]

hrns/client/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m hrns.client``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

hrns/client/_version.py

@@ -0,0 +1,5 @@
+"""Client package version. Kept separate so the CLI can report it without loading the core."""
+
+from importlib.metadata import version
+
+__version__ = version("hrns")

hrns/client/attachments.py

@@ -0,0 +1,167 @@
+"""Explicit, bounded file attachments for ACP prompts.
+
+Attachments are content, not filesystem grants. The caller chooses each path; the
+receiving agent never gains access to the client's working directory from an attachment,
+and a hosted agent receives bytes rather than a local path it cannot read.
+
+Text resources are embedded as UTF-8 text; everything else is embedded as base64 bytes.
+Only regular files are accepted. The aggregate is bounded by the ACP message limit, with
+headroom reserved for the rest of the JSON-RPC envelope.
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+import stat
+from pathlib import Path
+from typing import Any, Sequence
+
+from acp import schema
+
+from .errors import HrnsClientError
+
+__all__ = [
+    "MAX_ATTACHMENT_BYTES",
+    "attachment_summary",
+    "build_prompt_blocks",
+    "validate_attachment",
+]
+
+#: Per-file limit; the client's prompt-size check still applies to the aggregate.
+MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024
+_TEXTUAL_SUFFIXES = {
+    ".json",
+    ".jsonl",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".md",
+    ".txt",
+    ".csv",
+    ".tsv",
+    ".py",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".css",
+    ".html",
+    ".xml",
+    ".sql",
+    ".sh",
+    ".rs",
+    ".go",
+    ".java",
+    ".kt",
+    ".c",
+    ".h",
+    ".cpp",
+    ".hpp",
+    ".rb",
+    ".php",
+}
+
+
+def _media_type(path: Path) -> str:
+    guessed, _ = mimetypes.guess_type(path.name)
+    if guessed:
+        return guessed
+    if path.suffix.lower() in _TEXTUAL_SUFFIXES:
+        return "text/plain"
+    return "application/octet-stream"
+
+
+def _is_text(media_type: str, path: Path) -> bool:
+    return (
+        media_type.startswith("text/")
+        or media_type in {"application/json", "application/xml", "application/yaml"}
+        or path.suffix.lower() in _TEXTUAL_SUFFIXES
+    )
+
+
+def validate_attachment(raw: str | Path) -> Path:
+    """Resolve and validate one explicit attachment without reading its content."""
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        path = path.resolve()
+    try:
+        info = path.stat()
+    except OSError as exc:
+        raise HrnsClientError(f"Cannot attach {path}: {exc}") from exc
+    if not stat.S_ISREG(info.st_mode):
+        raise HrnsClientError(f"Cannot attach {path}: only regular files are supported")
+    if info.st_size > MAX_ATTACHMENT_BYTES:
+        raise HrnsClientError(
+            f"Cannot attach {path}: {info.st_size:,} bytes exceeds the "
+            f"{MAX_ATTACHMENT_BYTES:,}-byte per-file limit"
+        )
+    return path
+
+
+def _read_regular(path: Path) -> bytes:
+    validate_attachment(path)
+    try:
+        return path.read_bytes()
+    except OSError as exc:
+        raise HrnsClientError(f"Cannot read {path}: {exc}") from exc
+
+
+def build_prompt_blocks(prompt: str, attachments: Sequence[str] = ()) -> list[Any]:
+    """Build ACP prompt blocks: the explicit user text followed by embedded resources."""
+    if not prompt.strip():
+        raise HrnsClientError("A prompt needs non-empty text; attachments do not replace it.")
+    blocks: list[Any] = [schema.TextContentBlock(type="text", text=prompt)]
+    total = len(prompt.encode("utf-8"))
+    for raw in attachments:
+        path = Path(raw).expanduser()
+        if not path.is_absolute():
+            path = path.resolve()
+        content = _read_regular(path)
+        total += len(content)
+        # Base64 expands by 4/3; leave room for JSON-RPC fields and other blocks.
+        if total * 4 // 3 > 12 * 1024 * 1024:
+            raise HrnsClientError(
+                "Attachments are too large for one ACP prompt (16 MiB frame limit); "
+                "attach fewer or smaller files."
+            )
+        media_type = _media_type(path)
+        uri = path.as_uri()
+        if _is_text(media_type, path):
+            try:
+                text = content.decode("utf-8")
+            except UnicodeDecodeError:
+                text = None
+            if text is not None:
+                resource: Any = schema.TextResourceContents(
+                    uri=uri, text=text, mime_type=media_type
+                )
+            else:
+                resource = schema.BlobResourceContents(
+                    uri=uri,
+                    blob=base64.b64encode(content).decode("ascii"),
+                    mime_type="application/octet-stream",
+                )
+        else:
+            resource = schema.BlobResourceContents(
+                uri=uri,
+                blob=base64.b64encode(content).decode("ascii"),
+                mime_type=media_type,
+            )
+        blocks.append(schema.EmbeddedResourceContentBlock(type="resource", resource=resource))
+    return blocks
+
+
+def attachment_summary(attachments: Sequence[str]) -> list[dict[str, Any]]:
+    """Non-secret display metadata for the UI and JSON output."""
+    result: list[dict[str, Any]] = []
+    for raw in attachments:
+        path = Path(raw).expanduser().resolve()
+        try:
+            size = path.stat().st_size
+        except OSError:
+            size = None
+        result.append(
+            {"name": path.name, "path": str(path), "size": size, "mimeType": _media_type(path)}
+        )
+    return result

hrns/client/bridge.py

@@ -0,0 +1,250 @@
+"""Stdio ACP bridge to a hosted agent (``hrns bridge``).
+
+The bridge is a framing adapter: newline-delimited ACP JSON-RPC on stdin and
+stdout, one complete JSON object per WebSocket text message on the remote
+side. Any stdio-only ACP client can launch it.
+
+With ``--remote-cwd``, the local client's ``cwd`` on ``session/new``,
+``session/load`` and ``session/resume`` is *replaced* with the remote
+directory. Nothing else is rewritten; paths returned by the agent remain
+clearly remote.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import sys
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from websockets.asyncio.client import ClientConnection
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import ConnectionClosed, InvalidStatus, WebSocketException
+
+from hrns.protocol import HrnsError, decode_frame, encode_frame
+
+from .constants import (
+    MAX_MESSAGE_BYTES,
+    WS_PING_INTERVAL,
+    WS_PING_TIMEOUT,
+    WS_SUBPROTOCOL,
+    WS_WRITE_LIMIT,
+)
+from .errors import HrnsClientError, ProtocolError
+from .profiles import secret_value
+from .url_policy import require_secure_ws_url
+
+__all__ = ["BridgeSession", "rewrite_session_cwd", "run_bridge", "run_bridge_pump"]
+
+SESSION_METHODS = frozenset({"session/new", "session/load", "session/resume"})
+
+EXIT_BRIDGE_OK = 0
+EXIT_BRIDGE_FAILURE = 1
+EXIT_BRIDGE_PROTOCOL = 4
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeSession:
+    """Everything needed to reach the hosted agent."""
+
+    url: str  # ws(s) URL of /v1/agents/{id}/acp
+    token_ref: str = ""
+    token: str | None = None
+    remote_cwd: str | None = None
+    agent_id: str = ""
+
+    def __post_init__(self) -> None:
+        require_secure_ws_url(self.url)
+
+    def headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        token = (
+            self.token
+            if self.token is not None
+            else (secret_value(self.token_ref) if self.token_ref else None)
+        )
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        return headers
+
+
+def rewrite_session_cwd(message: dict[str, Any], remote_cwd: str) -> bool:
+    """Replace ``params.cwd`` on ACP session setup/load/resume. Returns True if rewritten."""
+    if message.get("method") not in SESSION_METHODS:
+        return False
+    params = message.get("params")
+    if not isinstance(params, dict):
+        return False
+    params["cwd"] = remote_cwd
+    return True
+
+
+async def _default_ws_connect(session: BridgeSession) -> ClientConnection:
+    return await ws_connect(
+        session.url,
+        subprotocols=[WS_SUBPROTOCOL],
+        max_size=MAX_MESSAGE_BYTES,
+        ping_interval=WS_PING_INTERVAL,
+        ping_timeout=WS_PING_TIMEOUT,
+        write_limit=WS_WRITE_LIMIT,
+        additional_headers=session.headers(),
+    )
+
+
+async def run_bridge_pump(
+    read_line: Callable[[], Awaitable[bytes]],
+    write_local: Callable[[bytes], Awaitable[None]],
+    connect_remote: Callable[[], Awaitable[ClientConnection]],
+    *,
+    remote_cwd: str | None = None,
+    stderr: Callable[[str], None] | None = None,
+) -> int:
+    """Run both directions until stdin closes or the remote side goes away."""
+    report = stderr or (lambda line: print(f"bridge: {line}", file=sys.stderr, flush=True))
+    try:
+        ws = await connect_remote()
+    except InvalidStatus as exc:
+        status = getattr(getattr(exc, "response", None), "status_code", None)
+        report(f"the server rejected the connection{f' (HTTP {status})' if status else ''}")
+        return EXIT_BRIDGE_FAILURE
+    except (OSError, WebSocketException) as exc:
+        report(f"cannot connect to the remote agent: {exc}")
+        return EXIT_BRIDGE_FAILURE
+    selected = getattr(ws, "subprotocol", None)
+    if selected != WS_SUBPROTOCOL:
+        report(
+            f"the server did not accept the '{WS_SUBPROTOCOL}' subprotocol"
+            + (f" (selected {selected!r})" if selected else "")
+        )
+        await ws.close()
+        return EXIT_BRIDGE_PROTOCOL
+
+    rewritten = False
+    remote_error: str = ""
+
+    async def local_to_remote() -> None:
+        nonlocal rewritten
+        while True:
+            line = await read_line()
+            if not line:
+                return
+            try:
+                message = decode_frame(line)
+            except (HrnsClientError, HrnsError) as exc:
+                report(f"invalid local ACP frame: {exc}")
+                raise ProtocolError(str(exc)) from exc
+            if remote_cwd and rewrite_session_cwd(message, remote_cwd):
+                rewritten = True
+            wire = encode_frame(message)
+            if len(wire.encode("utf-8")) > MAX_MESSAGE_BYTES:
+                report("local message exceeds the 16 MiB transport limit")
+                raise ProtocolError("message too large")
+            await ws.send(wire)
+
+    async def remote_to_local() -> None:
+        nonlocal remote_error
+        try:
+            while True:
+                try:
+                    message = await ws.recv()
+                except ConnectionClosed as exc:
+                    received = getattr(exc, "rcvd", None)
+                    code = getattr(received, "code", None)
+                    remote_error = f"remote connection closed{f' (code {code})' if code else ''}"
+                    if code == 1009:
+                        remote_error = (
+                            "the server closed with status 1009 after an oversized message"
+                        )
+                    return
+                if isinstance(message, bytes):
+                    report("remote sent a binary WebSocket frame; ACP frames must be text")
+                    raise ProtocolError("binary frame")
+                try:
+                    decode_frame(message)
+                except (HrnsClientError, HrnsError) as exc:
+                    report(f"invalid remote ACP frame: {exc}")
+                    raise ProtocolError(str(exc)) from exc
+                await write_local(message.rstrip().encode("utf-8") + b"\n")
+        except WebSocketException as exc:
+            remote_error = f"remote transport failed: {exc}"
+
+    local_task = asyncio.create_task(local_to_remote(), name="hrns-bridge-local")
+    remote_task = asyncio.create_task(remote_to_local(), name="hrns-bridge-remote")
+    errors: list[BaseException] = []
+    try:
+        done, _pending = await asyncio.wait(
+            {local_task, remote_task}, return_when=asyncio.FIRST_COMPLETED
+        )
+        if remote_task in done:
+            # Give a final in-flight local write a moment, then stop.
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(local_task, timeout=0.2)
+        else:
+            # Local EOF: allow trailing responses already in flight, then close.
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(remote_task, timeout=0.2)
+        for task in done:
+            if task.cancelled():
+                continue
+            exc = task.exception()
+            if exc is not None:
+                errors.append(exc)
+    finally:
+        for task in (local_task, remote_task):
+            task.cancel()
+        for task in (local_task, remote_task):
+            with contextlib.suppress(BaseException):
+                await task
+        with contextlib.suppress(Exception):
+            await ws.close(code=1000)
+    if rewritten:
+        report(f"session cwd rewritten to remote path {remote_cwd}")
+    if errors:
+        report(str(errors[0]))
+        return EXIT_BRIDGE_PROTOCOL
+    if remote_error:
+        report(remote_error)
+        return EXIT_BRIDGE_FAILURE
+    return EXIT_BRIDGE_OK
+
+
+async def run_bridge(
+    session: BridgeSession,
+    *,
+    reader: asyncio.StreamReader | None = None,
+    writer: asyncio.StreamWriter | None = None,
+    stderr: Callable[[str], None] | None = None,
+) -> int:
+    """Run the bridge over real (or injected) stdio streams."""
+    own_streams = reader is None and writer is None
+    if own_streams:
+        from acp.stdio import stdio_streams
+
+        reader, writer = await stdio_streams(limit=MAX_MESSAGE_BYTES)
+    assert reader is not None and writer is not None
+
+    async def read_line() -> bytes:
+        return await reader.readline()
+
+    async def write_local(data: bytes) -> None:
+        writer.write(data)
+        await writer.drain()
+
+    async def connect_remote() -> ClientConnection:
+        return await _default_ws_connect(session)
+
+    try:
+        return await run_bridge_pump(
+            read_line,
+            write_local,
+            connect_remote,
+            remote_cwd=session.remote_cwd,
+            stderr=stderr,
+        )
+    finally:
+        if own_streams:
+            with contextlib.suppress(Exception):
+                writer.close()
+                await writer.wait_closed()

hrns/client/bus.py

@@ -0,0 +1,58 @@
+"""A tiny synchronous event bus for typed client events."""
+
+from __future__ import annotations
+
+import asyncio
+import weakref
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+Subscriber = Callable[[Any], Awaitable[None] | None]
+
+
+class EventBus:
+    """Publishes client events to in-process subscribers.
+
+    Handlers are called synchronously on the loop that publishes. Coroutine
+    handlers are scheduled as tasks so a slow consumer never blocks protocol
+    dispatch. Disabled handlers are pruned.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: list[Subscriber] = []
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    def subscribe(self, handler: Subscriber) -> Callable[[], None]:
+        """Register a handler and return a function that removes it."""
+        if not callable(handler):
+            raise TypeError("Event handlers must be callable")
+        self._subscribers.append(handler)
+        if isinstance(handler, weakref.ref):  # pragma: no cover - defensive
+            raise TypeError("Pass a bound method or closure, not a weakref")
+
+        def unsubscribe() -> None:
+            try:
+                self._subscribers.remove(handler)
+            except ValueError:  # pragma: no cover - already removed
+                pass
+
+        return unsubscribe
+
+    def publish(self, event: Any) -> None:
+        for handler in list(self._subscribers):
+            try:
+                result = handler(event)
+            except Exception:
+                import logging
+
+                logging.getLogger(__name__).exception("Event handler failed")
+                continue
+            if asyncio.iscoroutine(result):
+                task = asyncio.create_task(result)
+                self._tasks.add(task)
+                task.add_done_callback(self._tasks.discard)
+
+    async def drain(self) -> None:
+        """Wait for handler tasks published so far to finish (tests only)."""
+        if self._tasks:
+            await asyncio.gather(*list(self._tasks), return_exceptions=True)