handcode 0.3.0rc1__py3-none-any.whl

agentctl/adapters/openhands/seam_b.py

@@ -0,0 +1,259 @@
+"""Seam B binding for OpenHands. Spec: `docs/0008` §3.5, `docs/0012` §3.2.1.
+
+Binds BLOCK and ESCALATE via `ConversationState.block_action`, which fires from
+the event callback when an `ActionEvent` is emitted — before the tool runs
+(`docs/0015` §2).
+
+This is the whole of M2a. No executor wrapping, no fork, and it already gives
+correct fail-closed behaviour: a dangerous effect whose outcome is unknown is
+refused rather than repeated. What it cannot do is SUBSTITUTE a stored
+observation — that needs Seam C (M2b).
+
+Usage — note the two-step, forced by a chicken-and-egg: callbacks are passed at
+construction, but the callback needs the conversation it is attached to.
+
+    seam = SeamB(gate)
+    conv = Conversation(agent=..., callbacks=[seam])
+    seam.attach(conv)
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable
+
+from agentctl.kernel.gate import EffectGate
+from agentctl.kernel.ledger.models import GateDecision, ToolCall, Verdict
+
+log = logging.getLogger("agentctl.seam_b")
+
+
+class OpenHandsContext:
+    """Everything harness-specific lives here.
+
+    Keeping the translation in one small class is what makes porting to another
+    harness cheap (`docs/0008` §12).
+    """
+
+    def __init__(self, conversation_id: str):
+        self.conversation_id = conversation_id
+
+    def to_tool_call(self, event: Any) -> ToolCall | None:
+        """Normalise an ActionEvent into a harness-neutral ToolCall."""
+        tool_call_id = getattr(event, "tool_call_id", None)
+        if not tool_call_id:
+            tc = getattr(event, "tool_call", None)
+            tool_call_id = getattr(tc, "id", None) if tc else None
+        if not tool_call_id:
+            return None
+
+        action = getattr(event, "action", None)
+        args: dict = {}
+        if action is not None:
+            try:
+                args = action.model_dump()
+            except Exception:                           # noqa: BLE001
+                args = {k: v for k, v in vars(action).items()
+                        if not k.startswith("_")}
+        args.pop("kind", None)
+
+        return ToolCall(
+            tool_call_id=str(tool_call_id),
+            conversation_id=self.conversation_id,
+            turn_id=str(getattr(event, "id", "") or ""),
+            tool_name=str(getattr(event, "tool_name", "") or ""),
+            args=args,
+        )
+
+    @staticmethod
+    def serialize(event_or_observation: Any) -> bytes:
+        """Serialize the Observation, not the wrapping ObservationEvent.
+
+        Seam C revives this with `observation_type.model_validate_json`, so it
+        must be the observation's own shape.
+        """
+        obj = getattr(event_or_observation, "observation", None) or event_or_observation
+        try:
+            return obj.model_dump_json().encode()
+        except Exception:                               # noqa: BLE001
+            return json.dumps(str(obj)).encode()
+
+
+def is_action_event(event: Any) -> bool:
+    """Duck-typed so nothing here needs the SDK imported."""
+    return (
+        type(event).__name__ == "ActionEvent"
+        and getattr(event, "action", None) is not None
+    )
+
+
+def is_observation_event(event: Any) -> bool:
+    return type(event).__name__ in ("ObservationEvent", "AgentErrorEvent")
+
+
+class SeamB:
+    """Event callback that enforces the gate's BLOCK/ESCALATE verdicts.
+
+    Relies on the ordering contract in `docs/0006:V1`: the ActionEvent is
+    persisted, and callbacks fire, *before* the tool executes. Blocking here
+    prevents execution rather than merely recording disapproval.
+    """
+
+    def __init__(
+        self,
+        gate: EffectGate,
+        ctx: OpenHandsContext | None = None,
+        on_decision: Callable[[ToolCall, GateDecision], None] | None = None,
+        handoff: Any = None,
+    ):
+        self.gate = gate
+        self.ctx = ctx
+        self.on_decision = on_decision
+        # When Seam C is installed, SUBSTITUTE is handed to it instead of being
+        # downgraded to a block. Without it, behaviour degrades to M2a:
+        # still correct, just a rejection where a result was possible.
+        self.handoff = handoff
+        self._state: Any = None
+        self._pending: dict[str, str] = {}    # action_event_id -> tool_call_id
+        # action_event_id -> the record whose result Seam C is handing back.
+        # Its ObservationEvent is when that result reaches the model.
+        self._substituted: dict[str, str] = {}
+
+    def attach(self, conversation: Any) -> "SeamB":
+        """Bind to a live conversation. Call immediately after construction."""
+        self._state = conversation.state
+        if self.ctx is None:
+            self.ctx = OpenHandsContext(str(conversation.state.id))
+        return self
+
+    # ── the callback ───────────────────────────────────────────────────
+    def __call__(self, event: Any) -> None:
+        try:
+            if is_observation_event(event):
+                self._close(event)
+                return
+            if not is_action_event(event):
+                return
+            if self._state is None:
+                log.error("SeamB not attached; the gate is INERT. "
+                          "Call seam.attach(conversation) after construction.")
+                return
+            self._decide(event)
+        except Exception:                               # noqa: BLE001
+            # A callback bug must not take down the agent loop, but it must
+            # never silently disable the guard either. Log loudly.
+            log.exception("seam B callback failed for %r", event)
+
+    # ── internals ──────────────────────────────────────────────────────
+    def _decide(self, event: Any) -> None:
+        assert self.ctx is not None
+        call = self.ctx.to_tool_call(event)
+        if call is None:
+            return
+
+        decision = self.gate.guard(call)
+
+        if decision.verdict is Verdict.EXECUTE:
+            self._pending[str(event.id)] = call.tool_call_id
+            if self.handoff is not None:
+                # The fingerprint just taken describes the world before this
+                # whole batch. Let Seam C refresh it at the moment this call
+                # actually runs (`docs/0038` §3). Without Seam C the batch
+                # hazard remains, and the gate's `_sole_writer` check is what
+                # keeps that failing closed rather than silently wrong.
+                self.handoff.arm(event.action, call,
+                                 lambda c=call: self.gate.recapture(c))
+
+        elif decision.verdict in (Verdict.BLOCK, Verdict.ESCALATE):
+            reason = decision.reason or "blocked by agentctl"
+            self._state.block_action(event.id, reason)
+            log.warning("BLOCKED %s (%s): %s",
+                        call.tool_name, call.tool_call_id, reason)
+
+        elif decision.verdict is Verdict.SUBSTITUTE:
+            if self.handoff is not None:
+                # Seam C will return the recorded observation. Let the harness
+                # proceed to the executor -- it never reaches the real tool.
+                self.handoff.offer(event.action, call, decision.observation)
+                if decision.record_id:
+                    self._substituted[str(event.id)] = decision.record_id
+                log.info("handing %s to Seam C for substitution", call.tool_call_id)
+            else:
+                # No Seam C: block instead. Correctness preserved, resume
+                # quality is not. docs/0008 §3.5 -- degrade, never fail open.
+                reason = (
+                    f"{call.tool_name} already ran and its result was recorded; "
+                    f"agentctl blocked a repeat. Install the Seam C executor "
+                    f"wrap to resume cleanly instead of blocking."
+                )
+                self._state.block_action(event.id, reason)
+                log.warning("SUBSTITUTE needed, Seam B can only block: %s",
+                            call.tool_call_id)
+
+        if self.on_decision:
+            self.on_decision(call, decision)
+
+    def _close(self, event: Any) -> None:
+        """Close the ledger record. Pure observation, so Seam B can do it.
+
+        Everything here runs AFTER the SDK has persisted `event`: its default
+        callback appends and fsyncs before any caller callback, and if that
+        raises none of them run (`docs/0042` §8.2, checked in SDK 1.45.0 and
+        1.50.1). That ordering is what lets this record the result as
+        OBSERVED -- in the history the model reads -- rather than merely
+        returned (`docs/0045`).
+        """
+        action_id = getattr(event, "action_id", None)
+        if (rid := self._substituted.pop(action_id, None)) is not None:
+            self.gate.mark_observed(rid)
+            return
+        tcid = self._pending.pop(action_id, None)
+        if tcid is None:
+            return
+        assert self.ctx is not None
+        if type(event).__name__ == "AgentErrorEvent":
+            self.gate.record_failure_by_id(
+                tcid, str(getattr(event, "error", "tool error"))[:500])
+            return
+
+        # The event type is not the whole story. A tool that RAN and failed
+        # still arrives as an ordinary ObservationEvent, and committing it
+        # tells a resume the work is done. A real run recorded five `exit=1`
+        # shell commands as COMMITTED (`docs/0031` §10). So the error travels
+        # with the observation, and the record says the tool reported failure.
+        self.gate.record_observation(tcid, self.ctx.serialize(event),
+                                     error=_tool_error(event))
+
+
+def make_seam_b_callback(
+    conversation: Any,
+    gate: EffectGate,
+    ctx: OpenHandsContext | None = None,
+    on_decision: Callable[[ToolCall, GateDecision], None] | None = None,
+) -> SeamB:
+    """Convenience for when the conversation already exists."""
+    return SeamB(gate, ctx, on_decision).attach(conversation)
+
+
+def _tool_error(event: Any) -> str | None:
+    """Did the tool report failure? Returns why, or None if it succeeded.
+
+    `Observation.is_error` is the SDK's own flag and the only honest source:
+    the event type is `ObservationEvent` either way, so reading the type alone
+    cannot tell a success from a failure (`docs/0031` §10).
+
+    Returns None when there is no observation or no flag, because "cannot tell"
+    must not become "failed" -- treating every unreadable event as an error
+    would block work for no reason.
+    """
+    obs = getattr(event, "observation", None)
+    if obs is None or not getattr(obs, "is_error", False):
+        return None
+
+    # Prefer the tool's own text; it names the actual shell error.
+    for attr in ("output", "status", "file_text"):
+        if (v := getattr(obs, attr, None)):
+            return str(v)[:300]
+    if (code := getattr(obs, "exit_code", None)) is not None:
+        return f"exit={code}"
+    return "the tool reported an error"

agentctl/adapters/openhands/seam_c.py

@@ -0,0 +1,209 @@
+"""Seam C binding for OpenHands — the substitution channel.
+
+Spec: `docs/0008` §3.5, `docs/0012` §4, corrected by `docs/0014` C1.
+
+Binds by replacing the `executor` field on a resolved `ToolDefinition`. No
+subclassing of `ToolExecutor` to re-register, no fork:
+
+    gated = tool.model_copy(update={"executor": GatedExecutor(...)})
+
+What it adds over Seam B alone:
+
+1. **Substitution** — when an effect already landed, the agent receives the
+   recorded observation instead of a rejection, so the loop continues as though
+   the crash never happened.
+2. **Idempotency-key injection** — Seam C is the only place that can modify a
+   call before it executes, and injecting a stable key is the only general way
+   to make a remote effect replay-safe (`docs/0020`).
+
+The second is a deliberate widening of Seam C's role, and it stays narrow: the
+key is *computed by the kernel* and merely written onto the call here. Seam C
+still decides nothing.
+
+It remains thin — a lookup, a branch, an optional field write, and the inner
+call. All policy lives in the gate; all decisions are made at Seam B
+(`handoff.py`). Keeping this small is the whole portability argument in
+`docs/0008` §12.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from openhands.sdk.tool import ToolDefinition, ToolExecutor, register_tool
+
+from .handoff import SubstitutionHandoff
+
+log = logging.getLogger("agentctl.seam_c")
+
+
+class GatedExecutor(ToolExecutor):
+    """Wraps a real executor. Substitutes when Seam B says the effect landed."""
+
+    def __init__(self, inner: ToolExecutor, handoff: SubstitutionHandoff,
+                 observation_type: type | None = None, tool_name: str = "",
+                 idempotency: Any = None):
+        self._inner = inner
+        self._handoff = handoff
+        self._observation_type = observation_type
+        self._tool_name = tool_name
+        #: An `IdempotencyProbe`, when this tool declares a key field.
+        self._idempotency = idempotency
+
+    def __call__(self, action, conversation=None):
+        claim = self._handoff.claim(action, self._tool_name, _args(action))
+        if claim is not None:
+            _call, raw = claim
+            if (obs := self._revive(raw)) is not None:
+                log.info("substituted recorded observation for %s", self._tool_name)
+                return obs
+            if (obs := self._synthesize()) is not None:
+                log.info("synthesized a recovery observation for %s", self._tool_name)
+                return obs
+            # It landed, we cannot describe it, and re-running would duplicate
+            # the effect. Raising is the safe end: the harness surfaces an
+            # error, and the ledger already says COMMITTED.
+            raise RuntimeError(
+                f"{self._tool_name} already executed, but its result could not "
+                f"be recovered or described. It was NOT re-run."
+            )
+
+        # No claim means Seam B said EXECUTE. Seam C never decides.
+        #
+        # It does, however, re-fingerprint: Seam B decided for the whole batch,
+        # and this is the only point at which a call is seen at its own
+        # execution moment (`docs/0038` §3). Still no decision -- the kernel
+        # captures, this only says when.
+        self._handoff.before_execute(action, self._tool_name, _args(action))
+        return self._inner(self._stamp_idempotency_key(action), conversation)
+
+    def _stamp_idempotency_key(self, action):
+        """Write the kernel's stable key onto the call before it goes out.
+
+        Without this the IdempotencyProbe declines and the effect fails closed,
+        so the injection is not an optimisation -- it IS the mechanism
+        (`docs/0020`).
+        """
+        if self._idempotency is None:
+            return action
+        try:
+            from agentctl.kernel.ledger.models import ToolCall
+            call = ToolCall("stamp", "", "", self._tool_name, _args(action))
+            field = self._idempotency.key_field(call)
+            if field is None:
+                return action
+            existing = getattr(action, field, None)
+            if existing:
+                # The caller already supplied a key. It is stable across a
+                # resume for the same reason ours is, so leave it alone.
+                return action
+            return action.model_copy(
+                update={field: self._idempotency.key_for(call)})
+        except Exception:                               # noqa: BLE001
+            # A failed stamp means the probe declines and the effect fails
+            # closed. Safe, but say so loudly: it silently costs protection.
+            log.exception("could not stamp an idempotency key on %s",
+                          self._tool_name)
+            return action
+
+    def _revive(self, raw: bytes | None):
+        """Rebuild the observation actually recorded at commit time."""
+        if not raw or self._observation_type is None:
+            return None
+        try:
+            return self._observation_type.model_validate_json(raw)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not revive observation for %s", self._tool_name)
+            return None
+
+    def _synthesize(self):
+        """Describe a recovered effect when no observation was ever recorded.
+
+        A probe-reconciled effect has this shape: the crash happened *before*
+        the observation was written, so the ledger knows the effect landed but
+        holds no result. There is nothing to revive.
+
+        The agent still needs something truthful to continue on, so say plainly
+        what is known — it ran, its output is unavailable — rather than
+        inventing a plausible result or re-running the tool.
+        """
+        if self._observation_type is None:
+            return None
+        note = (
+            f"[agentctl] {self._tool_name} already completed before an "
+            f"interruption. The effect is confirmed; its original output was "
+            f"not recorded and is unavailable. It was not run again."
+        )
+        try:
+            obs = self._observation_type()          # defaults only
+        except Exception:                           # noqa: BLE001
+            return None                             # required fields: cannot describe
+        try:
+            # Observation.content is list[TextContent | ImageContent], not a
+            # string. Assigning a bare str validates here and then explodes
+            # later when the message is assembled.
+            from openhands.sdk.llm import TextContent
+            return obs.model_copy(update={"content": [TextContent(text=note)]})
+        except Exception:                           # noqa: BLE001
+            log.exception("could not attach a recovery note to %s", self._tool_name)
+            return obs
+
+    # Delegate lifecycle so the wrapper is transparent.
+    def close(self) -> None:
+        getattr(self._inner, "close", lambda: None)()
+
+    def interrupt(self) -> None:
+        getattr(self._inner, "interrupt", lambda: None)()
+
+
+def gate_tools(tools, handoff: SubstitutionHandoff, idempotency: Any = None):
+    """Replace each tool's executor with a gated one. `docs/0014` C1."""
+    out = []
+    for t in tools:
+        if t.executor is None:
+            out.append(t)
+            continue
+        out.append(t.model_copy(update={"executor": GatedExecutor(
+            t.executor, handoff, t.observation_type, t.name, idempotency)}))
+    return out
+
+
+def gate_tool_class(inner_cls: type[ToolDefinition], handoff: SubstitutionHandoff,
+                    idempotency: Any = None):
+    """Build a subclass whose `create()` returns gated tools."""
+
+    class Gated(inner_cls):                             # type: ignore[misc,valid-type]
+        @classmethod
+        def create(cls, conv_state=None, **params):
+            return gate_tools(
+                inner_cls.create(conv_state=conv_state, **params),
+                handoff, idempotency)
+
+    Gated.__name__ = f"Gated{inner_cls.__name__}"
+    Gated.__qualname__ = Gated.__name__
+    return Gated
+
+
+def install(handoff: SubstitutionHandoff, tools: dict[str, type],
+            idempotency: Any = None) -> list[str]:
+    """Re-register each named tool with a gated executor.
+
+    Call before constructing the Agent. Returns the names that were gated.
+    """
+    gated = []
+    for name, cls in tools.items():
+        try:
+            register_tool(name, gate_tool_class(cls, handoff, idempotency))
+            gated.append(name)
+        except Exception:                               # noqa: BLE001
+            log.exception("could not gate tool %s", name)
+    return gated
+
+
+def _args(action: Any) -> dict:
+    try:
+        d = action.model_dump()
+    except Exception:                                   # noqa: BLE001
+        d = {k: v for k, v in vars(action).items() if not k.startswith("_")}
+    d.pop("kind", None)
+    return d