handcode 0.3.0rc1__py3-none-any.whl

agentctl/adapters/litellm/__init__.py

@@ -0,0 +1,9 @@
+"""LiteLLM adapter — the Seam A binding (`docs/0008` §3).
+
+Harness-independent by nature: anything speaking the OpenAI-compatible format
+passes through here (`docs/0013` §5). It lives in `adapters/` rather than the
+kernel because the kernel may not import a data plane.
+"""
+from .hook import AgentctlHook
+
+__all__ = ["AgentctlHook"]

agentctl/adapters/litellm/hook.py

@@ -0,0 +1,49 @@
+"""Seam A bound to the LiteLLM proxy. Logic lives in `agentctl.kernel.hook`.
+
+Split out of the kernel because `tests/test_boundaries.py` rightly refuses to
+let the kernel import a data plane (`docs/0008` R6). The kernel keeps the
+decision logic; this file is the ~40 lines that know about LiteLLM.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from litellm.integrations.custom_logger import CustomLogger
+
+from agentctl.kernel.hook import RequestHook
+
+log = logging.getLogger("agentctl.hook")
+
+
+class AgentctlHook(CustomLogger, RequestHook):
+    """The class the proxy loads via `litellm_settings.callbacks`."""
+
+    def __init__(self, telemetry_path: str | Path | None = None):
+        CustomLogger.__init__(self)
+        RequestHook.__init__(self, telemetry_path)
+
+    async def async_pre_call_hook(self, user_api_key_dict, cache, data,
+                                  call_type, **kwargs):
+        try:
+            return self.apply(data)
+        except Exception:                               # noqa: BLE001
+            # Seam A must never break a request. Losing the hook costs
+            # attribution and pinning, not correctness -- the gate at Seams B
+            # and C is what protects effects.
+            log.exception("Seam A pre-call hook failed; passing through")
+            return data
+
+    async def async_log_success_event(self, kwargs, response_obj,
+                                      start_time, end_time):
+        try:
+            self.record(kwargs, response_obj, _epoch(start_time), _epoch(end_time))
+        except Exception:                               # noqa: BLE001
+            log.exception("Seam A telemetry failed")
+
+
+def _epoch(t) -> float | None:
+    try:
+        return t.timestamp()
+    except Exception:                                   # noqa: BLE001
+        return None

agentctl/adapters/litellm/recorder.py

@@ -0,0 +1,187 @@
+r"""Record real completions into a cassette (M6).
+
+A `CustomLogger` registered in-process, not through the proxy. `docs/0021`
+established Seam A as the proxy's callback; `agentctl run` talks to the
+provider directly and never loads it, so a direct run currently produces no
+telemetry at all. Recording therefore attaches to `litellm.callbacks` itself.
+
+The request is rebuilt from the logging callback's `kwargs`, which is the only
+place both the request and its response are visible together. `docs/0021` §4
+is the warning that applies here: what a callback receives is *not* laid out
+the way the call site wrote it.
+
+**Nothing here can break a completion.** A recorder that raises would turn a
+diagnostic into an outage, so every path is swallowed and counted. A cassette
+missing a turn is a bad cassette; a cassette that kills the run is worse.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from litellm.integrations.custom_logger import CustomLogger
+
+from agentctl.control.replay.cassette import SIGNIFICANT_FIELDS, Cassette
+
+log = logging.getLogger("agentctl.recorder")
+
+# Deliberately THE fingerprint's list, not a copy of it. When these were two
+# lists they drifted, and every replay missed on turn 0 (`docs/0029` §4).
+_REQUEST_KEYS = SIGNIFICANT_FIELDS
+
+
+class CassetteRecorder(CustomLogger):
+    """Writes every successful completion to a cassette."""
+
+    def __init__(self, path: str | Path, flush_every: int = 1,
+                 configured_model: str = ""):
+        super().__init__()
+        self.path = Path(path)
+        # litellm strips the provider prefix before a callback sees `model`,
+        # so the routable name has to come from the caller (`docs/0029` §3).
+        self.configured_model = configured_model
+        self.cassette = Cassette()
+        self.flush_every = max(1, flush_every)
+        self.errors = 0
+        # A detached recorder must be inert even if litellm still holds it.
+        # See `detach` -- removing it from the callback lists is not something
+        # this package can guarantee, but refusing to write is.
+        self.closed = False
+
+    # litellm calls one or the other depending on the call path, so both are
+    # implemented and both land in the same place.
+    def log_success_event(self, kwargs, response_obj, start_time, end_time):
+        self._capture(kwargs, response_obj)
+
+    async def async_log_success_event(self, kwargs, response_obj,
+                                      start_time, end_time):
+        self._capture(kwargs, response_obj)
+
+    # ── internals ──────────────────────────────────────────────────────
+    def _capture(self, kwargs: dict, response_obj: Any) -> None:
+        if self.closed:
+            return
+        try:
+            request = _request_from(kwargs)
+            response = _as_dict(response_obj)
+            if not request.get("messages") or not response:
+                # Nothing worth recording, and nothing worth failing over.
+                return
+            turn = self.cassette.append(
+                request, response,
+                model=str(kwargs.get("model") or request.get("model") or ""),
+                provider_model=self.configured_model,
+                usage=_as_dict(_get(response_obj, "usage")) or {})
+            if turn.index % self.flush_every == 0:
+                self.flush()
+        except Exception:                               # noqa: BLE001
+            self.errors += 1
+            log.exception("recorder failed on one turn; continuing")
+
+    def flush(self) -> None:
+        try:
+            self.cassette.save(self.path)
+        except Exception:                               # noqa: BLE001
+            self.errors += 1
+            log.exception("could not write the cassette")
+
+
+def _request_from(kwargs: dict) -> dict:
+    """Rebuild the outgoing request from what the callback was handed.
+
+    `kwargs` carries the call's arguments at the top level for a direct
+    completion, and under `additional_args`/`optional_params` for some proxy
+    paths. Both are checked, nearest-first.
+    """
+    optional = kwargs.get("optional_params") or {}
+    out: dict = {}
+    for key in _REQUEST_KEYS:
+        value = kwargs.get(key)
+        if value is None:
+            value = optional.get(key)
+        if value is not None:
+            out[key] = _as_plain(value)
+    return out
+
+
+def _as_dict(obj: Any) -> dict:
+    """Pydantic model, dict, or something with __dict__ -> a plain dict."""
+    if obj is None:
+        return {}
+    if isinstance(obj, dict):
+        return obj
+    for attr in ("model_dump", "dict", "json"):
+        fn = getattr(obj, attr, None)
+        if callable(fn):
+            try:
+                got = fn()
+                if isinstance(got, dict):
+                    return got
+                if isinstance(got, str):
+                    import json
+                    return json.loads(got)
+            except Exception:                           # noqa: BLE001
+                continue
+    return dict(getattr(obj, "__dict__", {}) or {})
+
+
+def _as_plain(value: Any) -> Any:
+    """Recursively strip pydantic models so the cassette is plain JSON."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if isinstance(value, dict):
+        return {k: _as_plain(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_as_plain(v) for v in value]
+    d = _as_dict(value)
+    return {k: _as_plain(v) for k, v in d.items()} if d else str(value)
+
+
+def _get(obj: Any, name: str) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
+# litellm copies whatever is in `callbacks` into its own per-kind lists the
+# first time it initialises logging. Removing from `callbacks` alone leaves the
+# recorder live in `success_callback`, still writing (`docs/0029` §5).
+_CALLBACK_LISTS = (
+    "callbacks", "success_callback", "_async_success_callback",
+    "input_callback", "_async_input_callback",
+    "failure_callback", "_async_failure_callback",
+    "service_callback", "audit_log_callbacks",
+)
+
+
+def attach(path: str | Path, configured_model: str = "") -> CassetteRecorder:
+    """Register a recorder on litellm's in-process callback list."""
+    import litellm
+
+    rec = CassetteRecorder(path, configured_model=configured_model)
+    if not any(c is rec for c in litellm.callbacks):
+        litellm.callbacks.append(rec)
+    return rec
+
+
+def detach(rec: CassetteRecorder) -> None:
+    """Stop recording, and mean it.
+
+    Two mechanisms, because the first one alone is not sufficient and cannot be
+    made sufficient: litellm decides where to copy a callback, and a version
+    that adds a tenth list would silently resurrect the recorder. Closing the
+    recorder is what actually guarantees it stops, whoever still holds it.
+
+    The bug this fixes: a replay run re-recorded itself into the cassette it
+    was replaying, doubling the file (`docs/0029` §5).
+    """
+    import litellm
+
+    rec.flush()
+    rec.closed = True
+
+    for name in _CALLBACK_LISTS:
+        lst = getattr(litellm, name, None)
+        if isinstance(lst, list):
+            lst[:] = [c for c in lst if c is not rec]

agentctl/adapters/openhands/__init__.py

@@ -0,0 +1,169 @@
+"""OpenHands adapter — the harness-specific layer (`docs/0008` §12).
+
+One call wires both seams:
+
+    from agentctl.adapters.openhands import protect
+
+    guard = protect(ledger="./ledger.db", conversation_id=cid,
+                    tools={"commit": CommitTool}, repo_root="./repo")
+    conv = Conversation(agent=agent, callbacks=[guard.seam_b], ...)
+    guard.attach(conv)
+
+Everything below `agentctl.kernel` stays harness-neutral; porting to another
+harness means rewriting this package and nothing else.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from agentctl.kernel.classify import Classifier
+from agentctl.kernel.gate import EffectGate
+from agentctl.kernel.ledger.store import LeaseHeartbeat, LedgerStore
+from agentctl.kernel.reconcile import (
+    IdempotencyProbe,
+    ProbeRegistry,
+    default_registry,
+)
+
+from .handoff import SubstitutionHandoff
+from .seam_b import OpenHandsContext, SeamB
+from .seam_c import gate_tool_class, gate_tools, install as install_seam_c
+
+__all__ = [
+    "protect", "Guard", "SeamB", "OpenHandsContext", "SubstitutionHandoff",
+    "gate_tools", "gate_tool_class", "install_seam_c",
+]
+
+
+@dataclass
+class Guard:
+    """Everything wired together, so callers hold one object."""
+
+    store: LedgerStore
+    gate: EffectGate
+    handoff: SubstitutionHandoff
+    seam_b: SeamB
+    gated_tools: list[str] = field(default_factory=list)
+    heartbeat: LeaseHeartbeat | None = None
+    conversation_id: str = ""
+    _closed: bool = field(default=False, repr=False)
+
+    def attach(self, conversation: Any) -> "Guard":
+        """Bind Seam B to a live conversation. Required."""
+        self.seam_b.attach(conversation)
+        return self
+
+    # ── inspection, for the CLI and the eventual dashboard ────────────
+    def blocked(self):
+        return self.store.blocked(self.seam_b.ctx.conversation_id
+                                  if self.seam_b.ctx else None)
+
+    def pending(self):
+        cid = self.seam_b.ctx.conversation_id if self.seam_b.ctx else None
+        return self.store.pending(cid) if cid else []
+
+    def close(self) -> None:
+        """Stop renewing, give the lease back, close the ledger.
+
+        Releasing on a clean exit is what lets the next `--resume` start
+        straight away. A crash skips this, and the lease then expires within
+        one TTL, or is taken over once its holder is known to be dead.
+        """
+        if self.heartbeat is not None:
+            self.heartbeat.stop()
+            self.heartbeat = None
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            if self.conversation_id:
+                self.store.release(self.conversation_id)
+        finally:
+            self.store.close()
+
+    def __enter__(self) -> "Guard":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+def protect(
+    ledger: str | Path,
+    conversation_id: str,
+    tools: dict[str, type] | None = None,
+    *,
+    matrix: dict | str | Path | None = None,
+    repo_root: str | Path | None = None,
+    probes: ProbeRegistry | None = None,
+    holder: str | None = None,
+    takeover: bool = False,
+    lease_ttl_s: float = 60.0,
+    on_decision: Callable | None = None,
+    heartbeat: bool = True,
+) -> Guard:
+    """Wire the gate, the ledger, and both seams.
+
+    Args:
+        ledger: path to the SQLite effect ledger.
+        conversation_id: the conversation this guard owns the lease for.
+        tools: `{name: ToolDefinition subclass}` to gate at Seam C. Omit to run
+            Seam B only — still correct, but an already-landed effect is
+            blocked rather than resumed cleanly (`docs/0008` §3.5).
+        matrix: capability matrix as a dict, or a path to one. Defaults to the
+            bundled `tools.yaml`.
+        repo_root: workspace repo, used by the git probe.
+        holder: who holds the lease. Defaults to `run@<host>:<pid>`, unique
+            per process, which is what lets a resume tell a dead holder from
+            a live one (`agentctl.runtime.lease`).
+        takeover: steal a LIVE lease. Only right when its holder is known to
+            be dead; fencing then refuses the old holder's writes. A live
+            holder stolen from is two drivers of one conversation
+            (`docs/0042` I-02).
+        heartbeat: renew the lease from a background thread until `close()`.
+
+    Returns a `Guard`. You must call `guard.attach(conversation)` after
+    constructing the Conversation, or Seam B is inert.
+    """
+    if holder is None:
+        from agentctl.runtime.lease import holder_id
+        holder = holder_id()
+    store = LedgerStore(ledger, holder=holder)
+    fence = store.acquire(conversation_id, ttl_s=lease_ttl_s, takeover=takeover)
+    beat = (LeaseHeartbeat(ledger, holder, conversation_id, ttl_s=lease_ttl_s).start()
+            if heartbeat else None)
+
+    if isinstance(matrix, (str, Path)):
+        classifier = Classifier(matrix_path=matrix)
+    elif isinstance(matrix, dict):
+        classifier = Classifier(matrix=matrix)
+    else:
+        classifier = Classifier()
+
+    idem_fields = classifier.idempotency_fields()
+    gate = EffectGate(
+        store,
+        classifier,
+        probes=probes if probes is not None
+        else default_registry(repo_root, idem_fields),
+        fence=fence,
+    )
+
+    handoff = SubstitutionHandoff()
+    gated: list[str] = []
+    if tools:
+        # Seam C must be installed BEFORE the Agent resolves its tools. It also
+        # stamps the idempotency key the EXTERNAL probe depends on.
+        gated = install_seam_c(handoff, tools, IdempotencyProbe(idem_fields))
+
+    seam_b = SeamB(
+        gate,
+        OpenHandsContext(conversation_id),
+        on_decision=on_decision,
+        handoff=handoff if gated else None,
+    )
+    return Guard(store=store, gate=gate, handoff=handoff,
+                 seam_b=seam_b, gated_tools=gated, heartbeat=beat,
+                 conversation_id=conversation_id)

agentctl/adapters/openhands/handoff.py

@@ -0,0 +1,155 @@
+"""Carries a SUBSTITUTE decision from Seam B to Seam C.
+
+Why this exists: `ToolExecutor.__call__(action, conversation)` receives the
+*action*, and `Action` carries no identity — `tool_call_id` lives only on the
+`ActionEvent`, which Seam B sees and Seam C does not. So the seam that can
+*identify* a call is not the seam that can *substitute* for it.
+
+**Seam C is not a second gate.** Seam B makes every decision. Seam C exists
+only to honour the one verdict Seam B cannot: returning a stored observation
+instead of executing. A lookup miss therefore means "Seam B said EXECUTE", and
+passing through is correct — Seam B would already have blocked anything
+dangerous.
+
+Matching is by object identity first (the harness passes the same `action`
+instance the event carried), falling back to a content fingerprint so a
+mismatch degrades to a missed substitution rather than a wrong one.
+
+**The mailbox holds a strong reference to the action, and that is load
+bearing.** `id()` is unique only among *live* objects: CPython reuses
+addresses, so an entry keyed on a bare `id()` whose action had been collected
+could be hit by an unrelated action allocated at the same address — returning
+one call's recorded observation for a different call. Keeping the action alive
+makes the address unreusable for as long as the entry exists, and the identity
+re-check on read is what turns a stale entry into a miss instead of a
+mismatch. Found by CI on 3.12; 3.13's allocator simply did not recycle the
+address (`docs/0028`).
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from collections import defaultdict, deque
+from typing import Any
+
+log = logging.getLogger("agentctl.handoff")
+
+
+class SubstitutionHandoff:
+    """A one-shot mailbox per action, written by Seam B and read by Seam C."""
+
+    def __init__(self) -> None:
+        # The action itself is kept, not just its id. See the module docstring:
+        # without a live reference the address can be recycled under a
+        # different action, and the entry would then be claimed by the wrong
+        # call. The stored action is never read except to compare identity.
+        self._by_identity: dict[int, tuple[Any, Any, bytes | None]] = {}
+        self._by_fingerprint: dict[str, deque] = defaultdict(deque)
+        #: Calls cleared to execute, awaiting a re-capture at Seam C. Holds the
+        #: action for the same reason as `_by_identity` above.
+        self._armed: dict[int, tuple[Any, Any, Any]] = {}
+        self._lock = threading.Lock()
+
+    def offer(self, action: Any, call, observation: bytes | None) -> None:
+        """Seam B: this call already ran; hand Seam C the recorded result."""
+        with self._lock:
+            self._by_identity[id(action)] = (action, call, observation)
+            self._by_fingerprint[call.intent_hash()].append((call, observation))
+
+    def arm(self, action: Any, call, recapture: Any) -> None:
+        """Seam B: this call was cleared to run; let Seam C refresh it first.
+
+        Seam B decides for every call in an assistant message before any of
+        them executes, so the fingerprint it took is the world *before the
+        batch*, not the world this call will act on (`docs/0038` §3). Seam C is
+        the only place that sees a call at its own execution moment.
+
+        What is stored is a bound thunk, not the gate: Seam C still decides
+        nothing, and all knowledge of the kernel stays on this side of the
+        mailbox.
+        """
+        with self._lock:
+            self._armed[id(action)] = (action, call, recapture)
+
+    def before_execute(self, action: Any, tool_name: str, args: dict) -> bool:
+        """Seam C: re-fingerprint the world for this call, if it was armed.
+
+        Consumed on read, and matched by the same identity-then-fingerprint
+        discipline as `claim` — a recycled address must read as a miss.
+        Returns whether a re-capture ran, for logging and tests.
+        """
+        with self._lock:
+            entry = self._armed.get(id(action))
+            if entry is not None and entry[0] is action:
+                del self._armed[id(action)]
+                recapture = entry[2]
+            else:
+                fp = _fingerprint(tool_name, args)
+                hit = next(((k, e) for k, e in self._armed.items()
+                            if e[1].intent_hash() == fp), None)
+                if hit is None:
+                    return False
+                del self._armed[hit[0]]
+                recapture = hit[1][2]
+        # Outside the lock: a re-capture shells out to git, and holding the
+        # mailbox lock across a subprocess would serialise unrelated calls.
+        recapture()
+        return True
+
+    def claim(self, action: Any, tool_name: str, args: dict) -> tuple | None:
+        """Seam C: is there a substitution waiting for this action?
+
+        Consumed on read — a substitution is honoured exactly once, so a
+        genuinely repeated call is not silently short-circuited twice.
+        """
+        with self._lock:
+            entry = self._by_identity.get(id(action))
+            # `is`, not `==`: a recycled address must read as a miss, and the
+            # fingerprint path below is then free to answer correctly.
+            if entry is not None and entry[0] is action:
+                del self._by_identity[id(action)]
+                hit = (entry[1], entry[2])
+                self._drop_fingerprint(hit[0])
+                return hit
+
+            fp = _fingerprint(tool_name, args)
+            q = self._by_fingerprint.get(fp)
+            if q:
+                hit = q.popleft()
+                self._drop_identity(hit[0])
+                log.debug("handoff matched by fingerprint, not identity")
+                return hit
+        return None
+
+    def _drop_identity(self, call) -> None:
+        """Remove the identity entry for `call`, whatever action it was under.
+
+        `id(call)` is not the key — the key is the id of the *action*. Popping
+        `id(call)` removed nothing and left the identity entry behind to be
+        claimed a second time.
+        """
+        for key, (_, c, _obs) in list(self._by_identity.items()):
+            if c is call:
+                del self._by_identity[key]
+                return
+
+    def pending(self) -> int:
+        with self._lock:
+            return len(self._by_identity)
+
+    def _drop_fingerprint(self, call) -> None:
+        q = self._by_fingerprint.get(call.intent_hash())
+        if not q:
+            return
+        for i, (c, _) in enumerate(q):
+            if c is call:
+                del q[i]
+                return
+
+
+def _fingerprint(tool_name: str, args: dict) -> str:
+    import hashlib
+    import json
+    canonical = json.dumps({"t": tool_name, "a": args}, sort_keys=True,
+                           separators=(",", ":"), default=str)
+    return hashlib.sha256(canonical.encode()).hexdigest()