agent-control-panel 0.1.0__py3-none-any.whl

agent_control_panel/__init__.py

@@ -0,0 +1,102 @@
+"""Agent Control Panel SDK: fail-open reporting and remote control for AI agents."""
+
+from __future__ import annotations
+
+import logging
+
+from ._content import MAX_FULL_CHARS, extract_text
+from ._http import assert_secure_url
+from ._transport import Request, Response, Transport
+from ._version import __version__
+from ._webhook import WebhookResult
+from .client import AcpClient
+from .errors import AgentPausedError, AgentStatus
+from .signature import (
+    MAX_SKEW_SECONDS,
+    NONCE_HEADER,
+    PROTOCOL_HEADER,
+    SIG_HEADER,
+    TS_HEADER,
+    HeadersLike,
+    NonceCache,
+    SignedPayload,
+    VerifyResult,
+    sign_payload,
+    verify_signature,
+)
+from .tokens import TokenUsage, extract_tokens
+
+PACKAGE_NAME = "agent-control-panel"
+
+
+def create_client(
+    *,
+    url: str,
+    api_key: str,
+    agent_id: str,
+    webhook_secret: str,
+    webhook_secret_prev: str | None = None,
+    heartbeat_seconds: float = 30.0,
+    flush_seconds: float = 5.0,
+    flush_at: int = 50,
+    max_buffer: int = 200,
+    logger: logging.Logger | None = None,
+    disable_control: bool = False,
+    allow_insecure_http: bool = False,
+    capture_content: bool = True,
+    transport: Transport | None = None,
+) -> AcpClient:
+    """Create a client for one agent. Call ``start()`` (or use ``with``) for heartbeats and flushes.
+
+    ``capture_content=False`` sends metadata only (status, tokens, timings, model, errors): no user input,
+    summaries, full input or answer text, whatever ``report_run`` or ``wrap_agent_run`` is given.
+
+    Raises ``ValueError`` for a missing credential or an insecure URL; nothing else in the client raises
+    into your code except ``AgentPausedError`` from ``wrap_agent_run``.
+    """
+    return AcpClient(
+        url=url,
+        api_key=api_key,
+        agent_id=agent_id,
+        webhook_secret=webhook_secret,
+        webhook_secret_prev=webhook_secret_prev,
+        heartbeat_seconds=heartbeat_seconds,
+        flush_seconds=flush_seconds,
+        flush_at=flush_at,
+        max_buffer=max_buffer,
+        logger=logger,
+        disable_control=disable_control,
+        allow_insecure_http=allow_insecure_http,
+        capture_content=capture_content,
+        transport=transport,
+    )
+
+
+__all__ = [
+    "MAX_FULL_CHARS",
+    "MAX_SKEW_SECONDS",
+    "NONCE_HEADER",
+    "PACKAGE_NAME",
+    "PROTOCOL_HEADER",
+    "SIG_HEADER",
+    "TS_HEADER",
+    "AcpClient",
+    "AgentPausedError",
+    "AgentStatus",
+    "HeadersLike",
+    "NonceCache",
+    "Request",
+    "Response",
+    "SignedPayload",
+    "TokenUsage",
+    "Transport",
+    "VerifyResult",
+    "WebhookResult",
+    "__version__",
+    "assert_secure_url",
+    "create_client",
+    "extract_text",
+    "extract_tokens",
+    "sign_payload",
+    "verify_signature",
+]

agent_control_panel/_content.py

@@ -0,0 +1,138 @@
+"""Run content: the answer text of LLM responses, and cutting content to what ACP stores."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+MAX_FULL_CHARS = 100_000
+"""What ACP stores per full input/output field, in UTF-16 code units (JavaScript string length)."""
+MAX_SUMMARY_CHARS = 2_000
+"""What ACP stores per summary field."""
+
+
+def _read(obj: Any, key: str) -> Any:
+    """A key or plain attribute. Never calls anything: a callable value (a method) counts as absent."""
+    try:
+        value = obj.get(key) if isinstance(obj, Mapping) else getattr(obj, key, None)
+    except Exception:
+        return None
+    return None if callable(value) else value
+
+
+def _text(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _is_object(value: Any) -> bool:
+    return value is not None and not isinstance(value, (str, bytes, bytearray, int, float, bool, list, tuple))
+
+
+def _join_text(parts: Any) -> str | None:
+    if not isinstance(parts, (list, tuple)):
+        return None
+    texts = [p if isinstance(p, str) else _text(_read(p, "text")) if _is_object(p) else None for p in parts]
+    found = [t for t in texts if t is not None]
+    return "".join(found) if found else None
+
+
+def _extract(result: Any) -> str | None:
+    if isinstance(result, str):
+        return result or None
+    if not _is_object(result):
+        return None
+    output_text = _text(_read(result, "output_text"))
+    if output_text:
+        return output_text
+    choices = _read(result, "choices")
+    if isinstance(choices, (list, tuple)) and choices:
+        message = _read(choices[0], "message") if _is_object(choices[0]) else None
+        content = _read(message, "content") if _is_object(message) else None
+        text = _text(content) or _join_text(content)
+        if text:
+            return text
+    content = _read(result, "content")
+    if isinstance(content, (list, tuple)):
+        blocks = [b for b in content if _is_object(b) and _read(b, "type") == "text"]
+        text = _join_text(blocks)
+        if text:
+            return text
+    response = _read(result, "response")
+    candidates = _read(result, "candidates")
+    if not isinstance(candidates, (list, tuple)) and _is_object(response):
+        candidates = _read(response, "candidates")
+    if isinstance(candidates, (list, tuple)) and candidates and _is_object(candidates[0]):
+        body = _read(candidates[0], "content")
+        text = _join_text(_read(body, "parts")) if _is_object(body) else None
+        if text:
+            return text
+    return _text(_read(result, "text"))
+
+
+def extract_text(result: Any) -> str | None:
+    """The answer text of a common LLM client response (a dict or an SDK object), or None.
+
+    - a string result is the text itself
+    - OpenAI Chat Completions: ``choices[0].message.content`` (a string or text parts)
+    - OpenAI Responses API: ``output_text``
+    - Anthropic Messages: ``content`` blocks of type ``text``
+    - Google Gemini: ``candidates[0].content.parts[].text`` (also under ``response``)
+    - ``text`` (Vercel AI SDK shape)
+
+    Only reads keys and attributes; never calls a method on the result. Never raises.
+    """
+    try:
+        return _extract(result)
+    except Exception:
+        return None
+
+
+def cut_utf16(text: str, limit: int) -> tuple[str, bool]:
+    """Cut ``text`` to ``limit`` UTF-16 code units (how JavaScript and the ACP server count length)."""
+    if len(text) * 2 <= limit or len(text.encode("utf-16-le")) // 2 <= limit:
+        return text, False
+    units = 0
+    for index, char in enumerate(text):
+        units += 2 if ord(char) > 0xFFFF else 1
+        if units > limit:
+            return text[:index], True
+    return text, False
+
+
+def clamp_full(value: Any) -> tuple[str | None, bool]:
+    """Serialise a full-content field like ``JSON.stringify`` and cut it to ACP's limit.
+
+    A value that cannot be serialised (circular, NaN) is left out: (None, False).
+    """
+    if value is None:
+        return None, False
+    if isinstance(value, str):
+        text = value
+    else:
+        try:
+            text = json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False, default=str)
+        except (TypeError, ValueError, RecursionError):
+            return None, False
+    return cut_utf16(text, MAX_FULL_CHARS)
+
+
+def clamp_summary(value: str | None) -> str | None:
+    return None if value is None else cut_utf16(value, MAX_SUMMARY_CHARS)[0]
+
+
+def run_row(fields: dict[str, Any], capture_content: bool) -> dict[str, Any]:
+    """The wire row for one run: content cut (and flagged) or, with capture off, left out; None dropped."""
+    content = ("input_summary", "output_summary", "user_input")
+    row = {k: v for k, v in fields.items() if k not in ("full_input", "full_output")}
+    if not capture_content:
+        for key in content:
+            row.pop(key, None)
+    full_in, in_cut = clamp_full(fields.get("full_input")) if capture_content else (None, False)
+    full_out, out_cut = clamp_full(fields.get("full_output")) if capture_content else (None, False)
+    row.update(full_input=full_in, full_output=full_out)
+    if in_cut:
+        row["full_input_truncated"] = True
+    if out_cut:
+        row["full_output_truncated"] = True
+    return {k: v for k, v in row.items() if v is not None}

agent_control_panel/_control.py

@@ -0,0 +1,202 @@
+"""Control state: status, holds, model override, prompt cache and the webhook nonce cache.
+
+Same rules as the Node SDK (``adoptControlState`` / ``applyCommandFrom``):
+- only an explicit resume/restart clears paused/stopped;
+- a hold ACP set is adopted from, and released by, the heartbeat reply; a hold this app set locally never is;
+- a heartbeat reply sent before the last applied command is ignored (``command_seq``);
+- a model in the heartbeat reply is adopted unless the app set its own; a missing model is no instruction.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .errors import AgentPausedError, AgentStatus
+from .signature import HeadersLike, NonceCache, VerifyResult, verify_signature
+
+Origin = Literal["acp", "local"]
+
+PROMPT_CACHE_SECONDS = 60.0
+MAX_MODEL_LENGTH = 120
+
+
+@dataclass(frozen=True)
+class CachedPrompt:
+    prompt: str
+    version: int
+    composition_hash: str | None = None
+
+
+@dataclass(frozen=True)
+class HeartbeatSnapshot:
+    seq: int
+    status: AgentStatus
+    model: str | None
+
+
+class ControlState:
+    def __init__(self, agent_id: str, disable_control: bool, logger: logging.Logger) -> None:
+        self.agent_id = agent_id
+        self.disable_control = disable_control
+        self._log = logger
+        self._lock = threading.Lock()
+        self._status: AgentStatus = "idle"
+        self._hold_origin: Origin | None = None
+        self._command_seq = 0
+        self._model_override: str | None = None
+        self._model_origin: Origin | None = None
+        self._prompt: CachedPrompt | None = None
+        self._prompt_cached_at: float | None = None
+        self._active_runs = 0
+        self._nonces = NonceCache()
+
+    def reset_lock_after_fork(self) -> None:
+        self._lock = threading.Lock()
+
+    @property
+    def status(self) -> AgentStatus:
+        with self._lock:
+            return self._status
+
+    @property
+    def model_override(self) -> str | None:
+        with self._lock:
+            return self._model_override
+
+    @property
+    def prompt(self) -> CachedPrompt | None:
+        with self._lock:
+            return self._prompt
+
+    # --- runs -------------------------------------------------------------------------------------------
+
+    def begin_run(self) -> None:
+        with self._lock:
+            if self._status in ("paused", "stopped"):
+                raise AgentPausedError(self._status)
+            self._active_runs += 1
+            self._status = "running"
+
+    def end_run(self) -> None:
+        with self._lock:
+            self._active_runs = max(0, self._active_runs - 1)
+            if self._active_runs == 0 and self._status == "running":
+                self._status = "idle"
+
+    # --- commands ---------------------------------------------------------------------------------------
+
+    def apply(self, command: str, payload: Mapping[str, Any] | None, origin: Origin) -> str | None:
+        if self.disable_control:
+            self._log.info("control ignored (disable_control): %s", command[:40])
+            return "ignored"
+        with self._lock:
+            if command not in ("ping", "verify"):
+                self._command_seq += 1
+            if command == "pause":
+                self._status, self._hold_origin = "paused", origin
+                return "paused"
+            if command == "resume":
+                self._status, self._hold_origin = "idle", None
+                return "resumed"
+            if command == "stop":
+                self._status, self._hold_origin = "stopped", origin
+                return "stopped"
+            if command == "restart":
+                self._status, self._hold_origin = "idle", None
+                return "restarted"
+            if command == "update_model":
+                model = payload.get("model") if payload else None
+                if isinstance(model, str) and model:
+                    self._model_override, self._model_origin = model, origin
+                return f"model now {self._model_override if self._model_override is not None else 'null'}"
+            if command == "update_prompt":
+                prompt = payload.get("prompt") if payload else None
+                if isinstance(prompt, str) and prompt:
+                    # The pushed text lacks the agent's skills (ACP composes them into GET /api/prompts), so
+                    # it is only the fallback: the cache is marked stale and the next fetch_prompt() pulls
+                    # the composed prompt.
+                    sent_version = payload.get("version") if payload else None
+                    version = (self._prompt.version if self._prompt else 0) + 1
+                    if isinstance(sent_version, int) and not isinstance(sent_version, bool):
+                        version = sent_version
+                    self._prompt = CachedPrompt(prompt=prompt, version=version)
+                    self._prompt_cached_at = None
+                return "prompt updated"
+            if command in ("ping", "verify"):
+                # Handshake / no-op: never touches agent status.
+                return "pong"
+            return None
+
+    # --- heartbeat --------------------------------------------------------------------------------------
+
+    def heartbeat_snapshot(self) -> HeartbeatSnapshot:
+        with self._lock:
+            return HeartbeatSnapshot(self._command_seq, self._status, self._model_override)
+
+    def adopt(self, reply: Any, seq_at_send: int) -> None:
+        if self.disable_control:
+            return
+        control = reply.get("control") if isinstance(reply, dict) else None
+        agents = control.get("agents") if isinstance(control, dict) else None
+        entry = agents.get(self.agent_id) if isinstance(agents, dict) else None
+        if not isinstance(entry, dict):
+            return
+        with self._lock:
+            if seq_at_send != self._command_seq:
+                return
+            model = entry.get("model")
+            if (
+                isinstance(model, str)
+                and model
+                and len(model) <= MAX_MODEL_LENGTH
+                and self._model_origin != "local"
+                and model != self._model_override
+            ):
+                self._model_override, self._model_origin = model, "acp"
+                self._log.info("model from ACP: %s", model)
+            status = entry.get("status")
+            if not isinstance(status, str):
+                return
+            if status in ("paused", "stopped"):
+                if self._hold_origin == "local" or self._status == status:
+                    return
+                self._status = "paused" if status == "paused" else "stopped"
+                self._hold_origin = "acp"
+                self._log.info("control state from ACP: %s", status)
+            elif self._hold_origin == "acp":
+                self._status, self._hold_origin = "idle", None
+                self._log.info("control state from ACP: released")
+
+    # --- webhooks ---------------------------------------------------------------------------------------
+
+    def verify_webhook(
+        self, headers: HeadersLike, raw_body: bytes, secrets: tuple[str, str | None]
+    ) -> VerifyResult:
+        # Checking and recording the nonce under one lock: two server threads must not both accept a replay.
+        with self._lock:
+            result = verify_signature(
+                secrets=secrets, raw_body=raw_body, headers=headers, seen_nonce=self._nonces.has
+            )
+            if result.ok and result.nonce:
+                self._nonces.add(result.nonce)
+            return result
+
+    # --- prompt cache -----------------------------------------------------------------------------------
+
+    def fresh_prompt(self) -> CachedPrompt | None:
+        with self._lock:
+            if self._prompt is None or self._prompt_cached_at is None:
+                return None
+            if time.monotonic() - self._prompt_cached_at >= PROMPT_CACHE_SECONDS:
+                return None
+            return self._prompt
+
+    def store_prompt(self, prompt: CachedPrompt) -> None:
+        with self._lock:
+            self._prompt = prompt
+            self._prompt_cached_at = time.monotonic()

agent_control_panel/_http.py

@@ -0,0 +1,99 @@
+"""Talking to ACP: URL rules, fail-open requests and the warnings that tell users what to fix."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+from ._transport import Request, Response, Transport
+
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def assert_secure_url(url: str, allow_insecure_http: bool = False) -> None:
+    """Raise unless ``url`` is https, http to a loopback host, or http with the explicit dev opt-out."""
+    parts = urlsplit(url)
+    if not parts.scheme or not parts.netloc or not parts.hostname:
+        raise ValueError(f"create_client: url is not a valid URL: {url}")
+    if parts.scheme == "https":
+        return
+    if parts.scheme != "http":
+        raise ValueError(f"create_client: url must use https: (got {parts.scheme}:)")
+    if parts.hostname.lower() in LOOPBACK_HOSTS or allow_insecure_http:
+        return
+    raise ValueError(
+        f'create_client: refusing insecure http:// url for host "{parts.hostname}" - the API key would be '
+        "sent in cleartext. Use https://, or set allow_insecure_http=True for local development only."
+    )
+
+
+def clean(text: str, limit: int = 200) -> str:
+    """Safe to log: no control characters (no forged log lines), bounded length."""
+    return _CONTROL_CHARS.sub(" ", text)[:limit]
+
+
+class Api:
+    def __init__(self, url: str, api_key: str, transport: Transport, logger: logging.Logger) -> None:
+        self.url = url
+        self._api_key = api_key
+        self._transport = transport
+        self._log = logger
+        parts = urlsplit(url)
+        self._display_url = urlunsplit(parts._replace(netloc=parts.netloc.rpartition("@")[2]))
+
+    def warn_status(self, label: str, path: str, res: Response, suffix: str = "") -> None:
+        if 300 <= res.status < 400:
+            if res.location:
+                target = clean(urljoin(self.url + path, res.location))
+                moved_to = target[: -len(path)] if target.endswith(path) else target
+                self._log.warning(
+                    "%s -> %d: ACP moved to %s; update your url (currently %s). Redirects are not "
+                    "followed, so the API key is never sent to another host.%s",
+                    label, res.status, moved_to, self._display_url, suffix,
+                )  # fmt: skip
+            else:
+                self._log.warning(
+                    "%s -> %d: redirect without a Location; check your url.%s", label, res.status, suffix
+                )
+        elif res.status == 401:
+            self._log.warning(
+                "%s -> 401: ACP rejected the API key. Check ACP_API_KEY is the full key shown once when it "
+                "was created (not revoked); create a new key on the app page if unsure.%s",
+                label, suffix,
+            )  # fmt: skip
+        else:
+            self._log.warning("%s -> %d%s", label, res.status, suffix)
+
+    def post(self, path: str, body: bytes, timeout: float) -> tuple[bool, Any]:
+        """Fail-open POST: (accepted, parsed JSON reply or None). Never raises."""
+        try:
+            res = self._transport(
+                Request("POST", self.url + path, body, {"Content-Type": "application/json"}, timeout)
+            )
+        except Exception as err:
+            self._log.warning("%s failed (continuing anyway): %s", path, err)
+            return False, None
+        if not 200 <= res.status < 300:
+            self.warn_status(path, path, res)
+            return False, None
+        try:
+            return True, json.loads(res.body) if res.body else None
+        except ValueError:
+            return True, None
+
+    def get_json(self, label: str, path: str, timeout: float, suffix: str) -> Any:
+        """GET with the API key header; the parsed JSON reply, or None (warned). Never raises."""
+        try:
+            res = self._transport(
+                Request("GET", self.url + path, None, {"x-api-key": self._api_key}, timeout)
+            )
+            if 200 <= res.status < 300:
+                return json.loads(res.body)
+            self.warn_status(label, path, res, suffix)
+        except Exception as err:
+            self._log.warning("%s failed%s: %s", label, suffix, err)
+        return None

agent_control_panel/_lifecycle.py

@@ -0,0 +1,131 @@
+"""Background threads for heartbeats and flushes, a time-bounded stop (also at exit), and fork safety."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import threading
+import time
+import weakref
+
+from ._control import ControlState
+from ._reporter import Reporter
+
+_instances: weakref.WeakSet[Background] = weakref.WeakSet()
+
+
+class Background:
+    """Daemon threads never keep the process alive; ``stop()`` and interpreter exit flush with a deadline."""
+
+    _control: ControlState
+    _reporter: Reporter
+    _log: logging.Logger
+
+    def __init__(self, heartbeat_seconds: float, flush_seconds: float) -> None:
+        self._heartbeat_seconds = heartbeat_seconds
+        self._flush_seconds = flush_seconds
+        self._state_lock = threading.Lock()
+        self._closing = threading.Event()
+        self._wake = threading.Event()
+        self._started = False
+        self._restart_after_fork = False
+        self._threads: list[threading.Thread] = []
+        _instances.add(self)
+
+    def _heartbeat(self) -> None:
+        raise NotImplementedError
+
+    def start(self) -> None:
+        """Start heartbeats and periodic flushes on daemon threads (they never keep the process alive)."""
+        with self._state_lock:
+            if self._started:
+                return
+            self._started = True
+            self._closing.clear()
+            self._wake.clear()
+            self._threads = [
+                threading.Thread(target=self._heartbeat_loop, name="acp-heartbeat", daemon=True),
+                threading.Thread(target=self._flush_loop, name="acp-flush", daemon=True),
+            ]
+            for thread in self._threads:
+                thread.start()
+            atexit.register(self._atexit)
+
+    def stop(self, timeout: float = 10.0) -> None:
+        """Stop the background threads and send what is buffered, giving up after ``timeout`` seconds."""
+        deadline = time.monotonic() + timeout
+        with self._state_lock:
+            self._started = False
+            threads, self._threads = self._threads, []
+        self._closing.set()
+        self._wake.set()
+        atexit.unregister(self._atexit)
+        # On a helper thread so that nothing (a hung connection, a slow DNS lookup) holds stop() or the
+        # interpreter's exit past the timeout.
+        flushed: list[bool] = []
+        finisher = threading.Thread(
+            target=lambda: flushed.append(self._reporter.flush(deadline)), daemon=True
+        )
+        try:
+            finisher.start()
+        except RuntimeError:  # threads can no longer be started (interpreter shutting down)
+            flushed.append(self._reporter.flush(deadline))
+        else:
+            finisher.join(max(0.0, deadline - time.monotonic()))
+        if flushed != [True]:
+            self._log.warning("stop: buffered runs could not be sent within %.1f s", timeout)
+        for thread in threads:
+            if thread is not threading.current_thread():
+                thread.join(max(0.0, min(1.0, deadline - time.monotonic())))
+
+    def flush(self) -> None:
+        """Send buffered runs now (blocking). Never raises."""
+        self._reporter.flush()
+
+    def _atexit(self) -> None:
+        self.stop(timeout=5.0)
+
+    def _after_fork_in_child(self) -> None:
+        self._state_lock = threading.Lock()
+        self._closing = threading.Event()
+        self._wake = threading.Event()
+        self._control.reset_lock_after_fork()
+        self._reporter.reset_after_fork()
+        self._restart_after_fork = self._started
+        self._started = False
+        self._threads = []
+
+    def _resume_after_fork(self) -> None:
+        if self._restart_after_fork:
+            self._restart_after_fork = False
+            self.start()
+
+    def _heartbeat_loop(self) -> None:
+        while True:
+            self._heartbeat()
+            if self._closing.wait(self._heartbeat_seconds):
+                return
+
+    def _flush_loop(self) -> None:
+        while not self._closing.is_set():
+            self._wake.wait(self._flush_seconds)
+            self._wake.clear()
+            if self._closing.is_set():
+                return
+            self._reporter.flush()
+
+    def _wake_flusher(self) -> None:
+        if any(t.is_alive() for t in self._threads):
+            self._wake.set()
+        else:
+            threading.Thread(target=self._reporter.flush, name="acp-flush-once", daemon=True).start()
+
+
+def _after_fork_in_child() -> None:
+    for instance in list(_instances):
+        instance._after_fork_in_child()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork_in_child)