patchbai 0.1.0__py3-none-any.whl

patchbai/agents/request_inbox.py

@@ -0,0 +1,65 @@
+import asyncio
+import uuid
+from typing import Callable
+
+
+class RequestInbox:
+    """Per-agent registry of pending ask_orchestrator requests.
+
+    Each registered request_id has an asyncio.Future. The agent's tool call
+    awaits the future (with a timeout); the orchestrator's reply resolves it.
+
+    `on_pending_changed`, if provided, is invoked synchronously after every
+    transition that changes the pending count — i.e., after `register()` and
+    after `wait()` removes a future from the dict. It receives the new
+    pending count.
+    """
+
+    def __init__(
+        self,
+        *,
+        on_pending_changed: Callable[[int], None] | None = None,
+    ) -> None:
+        self._futures: dict[str, asyncio.Future] = {}
+        self._on_pending_changed = on_pending_changed
+
+    def register(self) -> str:
+        request_id = uuid.uuid4().hex[:12]
+        # get_running_loop() instead of get_event_loop(): the latter is
+        # deprecated in Python 3.12+ when called outside a running loop.
+        # All callers run inside an event loop (tool handlers are async).
+        loop = asyncio.get_running_loop()
+        self._futures[request_id] = loop.create_future()
+        self._notify()
+        return request_id
+
+    def resolve(self, request_id: str, response: str) -> None:
+        future = self._futures.get(request_id)
+        if future is not None and not future.done():
+            future.set_result(response)
+
+    async def wait(self, request_id: str, *, timeout_s: float) -> str:
+        future = self._futures.get(request_id)
+        if future is None:
+            raise KeyError(f"unknown request_id: {request_id}")
+        try:
+            return await asyncio.wait_for(future, timeout=timeout_s)
+        finally:
+            self._futures.pop(request_id, None)
+            self._notify()
+
+    def pending(self) -> list[str]:
+        return [rid for rid, fut in self._futures.items() if not fut.done()]
+
+    def _notify(self) -> None:
+        if self._on_pending_changed is None:
+            return
+        try:
+            self._on_pending_changed(len(self._futures))
+        except Exception:
+            # The inbox must not poison its own callers if a subscriber
+            # explodes; mirror EventBus's swallow-and-log posture.
+            import logging
+            logging.getLogger(__name__).exception(
+                "RequestInbox.on_pending_changed handler raised"
+            )

patchbai/agents/sdk_adapter.py

@@ -0,0 +1,49 @@
+from typing import AsyncIterator, Protocol
+
+from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+
+
+class SDKAdapter(Protocol):
+    """Thin wrapping of one Claude Agent SDK session.
+
+    The interface is the surface our AgentSession uses — one query at a
+    time, async stream of messages until the SDK signals completion. The
+    real implementation wraps ClaudeSDKClient; tests use FakeSDKAdapter.
+    """
+
+    async def start(self, *, options: ClaudeAgentOptions) -> None: ...
+    async def query(self, prompt: str) -> None: ...
+    def stream(self) -> AsyncIterator[object]:
+        """Yield messages emitted in response to the most recent query.
+        Iteration ends when the SDK emits ResultMessage."""
+        ...
+    async def interrupt(self) -> None: ...
+    async def stop(self) -> None: ...
+
+
+class RealSDKAdapter:
+    """Wraps a real ClaudeSDKClient instance."""
+
+    def __init__(self) -> None:
+        self._client: ClaudeSDKClient | None = None
+
+    async def start(self, *, options: ClaudeAgentOptions) -> None:
+        self._client = ClaudeSDKClient(options=options)
+        await self._client.__aenter__()
+
+    async def query(self, prompt: str) -> None:
+        assert self._client is not None, "start() must be called before query()"
+        await self._client.query(prompt)
+
+    def stream(self) -> AsyncIterator[object]:
+        assert self._client is not None, "start() must be called before stream()"
+        return self._client.receive_response()
+
+    async def interrupt(self) -> None:
+        if self._client is not None:
+            await self._client.interrupt()
+
+    async def stop(self) -> None:
+        if self._client is not None:
+            await self._client.__aexit__(None, None, None)
+            self._client = None

patchbai/agents/session.py

@@ -0,0 +1,224 @@
+import asyncio
+import dataclasses
+import time
+from typing import Callable, Iterable
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ResultMessage,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+from patchbai.agents.sdk_adapter import SDKAdapter
+from patchbai.agents.state import AgentInfo, AgentState
+from patchbai.events import (
+    AgentMessageAppended,
+    AgentStateChanged,
+    AgentTokensTouched,
+    EventBus,
+)
+from patchbai.persistence.transcript_store import AgentTranscript, TranscriptEntry
+
+
+class AgentSession:
+    """One Claude Agent SDK session: one adapter, one transcript, one state machine."""
+
+    def __init__(
+        self,
+        *,
+        info: AgentInfo,
+        adapter: SDKAdapter,
+        transcript: AgentTranscript,
+        bus: EventBus,
+        on_session_id: "Callable[[str], None] | None" = None,
+    ) -> None:
+        self.info = info
+        self._adapter = adapter
+        self._transcript = transcript
+        self._bus = bus
+        self._on_session_id = on_session_id
+        self._session_id: str | None = None
+        self._stream_task: asyncio.Task | None = None
+        self._idle_event = asyncio.Event()
+        self._idle_event.set()
+        self._send_lock = asyncio.Lock()
+        self._pre_wait_state: AgentState | None = None
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    async def start(self, *, options: ClaudeAgentOptions) -> None:
+        await self._adapter.start(options=options)
+
+    async def send(self, prompt: str) -> None:
+        async with self._send_lock:
+            # If the previous stream is still draining, wait for it before
+            # issuing the next query — the SDK doesn't support overlapping
+            # query() calls on a single session.
+            if self._stream_task is not None and not self._stream_task.done():
+                await self._stream_task
+
+            self._record(role="user", text=prompt)
+            await self._adapter.query(prompt)
+            self._set_state(AgentState.RUNNING)
+            self._idle_event.clear()
+            self._stream_task = asyncio.create_task(self._consume_stream())
+
+    def queue_send(self, prompt: str) -> "asyncio.Task":
+        """Schedule a send() on the running event loop and return the Task.
+
+        Eagerly clears `_idle_event` synchronously so a subsequent wait_idle()
+        in the same task will correctly block until the send completes —
+        without it, wait_idle could return before the send task acquires the
+        send lock.
+        """
+        self._idle_event.clear()
+        return asyncio.create_task(self.send(prompt))
+
+    async def wait_idle(self) -> None:
+        await self._idle_event.wait()
+
+    async def interrupt(self) -> None:
+        await self._adapter.interrupt()
+
+    async def stop(self) -> None:
+        if self._stream_task is not None and not self._stream_task.done():
+            self._stream_task.cancel()
+            try:
+                await self._stream_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        await self._adapter.stop()
+
+    # --- internals --------------------------------------------------------
+
+    async def _consume_stream(self) -> None:
+        try:
+            async for msg in self._adapter.stream():
+                self._handle_message(msg)
+            self._set_state(AgentState.DONE)
+        except Exception:
+            self._set_state(AgentState.ERROR)
+        finally:
+            self._idle_event.set()
+
+    def _handle_message(self, msg: object) -> None:
+        if isinstance(msg, AssistantMessage):
+            for block in msg.content:
+                if isinstance(block, TextBlock):
+                    self._record(role="assistant", text=block.text)
+                elif isinstance(block, ToolUseBlock):
+                    self._record(
+                        role="tool_use",
+                        text=f"[{block.name}] {_short_repr(block.input)}",
+                        tool_id=block.id,
+                        tool_name=block.name,
+                    )
+                elif isinstance(block, ThinkingBlock):
+                    self._record(role="thinking", text=block.thinking)
+        elif isinstance(msg, UserMessage):
+            for block in msg.content:
+                if isinstance(block, ToolResultBlock):
+                    # tool_name not available on result blocks; consumers match via tool_id
+                    self._record(
+                        role="tool_result",
+                        text=_short_repr(block.content),
+                        tool_id=block.tool_use_id,
+                    )
+        elif isinstance(msg, SystemMessage):
+            # Skip — verbose protocol noise.
+            pass
+        elif isinstance(msg, ResultMessage):
+            if self._session_id is None and msg.session_id:
+                self._session_id = msg.session_id
+                if self._on_session_id is not None:
+                    try:
+                        self._on_session_id(msg.session_id)
+                    except Exception:
+                        # Callback errors must not poison the SDK stream.
+                        pass
+            usage = msg.usage or {}
+            tokens_in = int(usage.get("input_tokens", 0) or 0)
+            tokens_out = int(usage.get("output_tokens", 0) or 0)
+            self.info.tokens_in += tokens_in
+            self.info.tokens_out += tokens_out
+            if msg.total_cost_usd is not None:
+                self.info.cost += float(msg.total_cost_usd)
+            if tokens_in or tokens_out or msg.total_cost_usd:
+                self._bus.publish(AgentTokensTouched(agent_id=self.info.id))
+        self.info.last_activity = time.time()
+
+    def _record(
+        self,
+        *,
+        role: str,
+        text: str,
+        tool_id: str | None = None,
+        tool_name: str | None = None,
+    ) -> None:
+        entry = TranscriptEntry(
+            role=role, text=text, tool_id=tool_id, tool_name=tool_name,
+        )
+        self._transcript.append(entry)
+        self._bus.publish(
+            AgentMessageAppended(
+                agent_id=self.info.id, role=role, text=text,
+                tool_id=tool_id, tool_name=tool_name,
+            )
+        )
+        self.info.last_activity = time.time()
+
+    def _mark_waiting(self) -> None:
+        """Enter WAITING state, snapshotting the prior state for restore.
+
+        Idempotent: a second call while already WAITING is a no-op (the
+        snapshot is preserved). Skipped if the session is already in a
+        terminal state.
+        """
+        if self.info.state.is_terminal:
+            return
+        if self.info.state == AgentState.WAITING:
+            return
+        self._pre_wait_state = self.info.state
+        self._set_state(AgentState.WAITING)
+
+    def _mark_unwaiting(self) -> None:
+        """Exit WAITING state, restoring the pre-wait state.
+
+        No-op when not in WAITING. If the session is somehow terminal,
+        the snapshot is dropped without a transition.
+        """
+        if self.info.state != AgentState.WAITING:
+            self._pre_wait_state = None
+            return
+        target = self._pre_wait_state or AgentState.RUNNING
+        self._pre_wait_state = None
+        if target.is_terminal:
+            # Defensive: never resurrect a terminal state.
+            return
+        self._set_state(target)
+
+    def _set_state(self, new_state: AgentState) -> None:
+        old = self.info.state
+        if old == new_state:
+            return
+        self.info.state = new_state
+        if new_state.is_terminal:
+            self.info.ended_at = time.time()
+        # Publish a frozen snapshot so subscribers see the state at publish time,
+        # not a live reference that may mutate before they inspect it.
+        self._bus.publish(
+            AgentStateChanged(info=dataclasses.replace(self.info), old_state=old)
+        )
+
+
+def _short_repr(value: object, limit: int = 200) -> str:
+    s = repr(value)
+    return s if len(s) <= limit else s[: limit - 1] + "…"

patchbai/agents/sort.py

@@ -0,0 +1,66 @@
+"""Default sort order for the AgentTable widget.
+
+The sort surfaces agents that need attention at the top:
+
+  WAITING (blocked on user/orchestrator) → RUNNING/IDLE (live)
+  → ERROR (triage) → DONE (terminal, least interesting)
+
+Within a bucket, rows order by recent-activity desc, with `started_at`
+asc as a stable final tiebreaker. Archived agents always sink to the
+bottom regardless of state.
+
+This is the v1 default sort. User-overridable column-click sort is
+deliberately out of scope; see plan
+`docs/superpowers/plans/2026-05-07-agent-table-default-sort.md`.
+
+When `AWAITING_PERMISSION` (currently only on the approval-modals
+branch) merges, add it to STATE_PRIORITY at priority 0 — same
+semantic as WAITING.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from patchbai.agents.state import AgentInfo, AgentState
+
+STATE_PRIORITY: dict[AgentState, int] = {
+    AgentState.WAITING: 0,
+    AgentState.RUNNING: 1,
+    AgentState.IDLE: 2,
+    AgentState.ERROR: 3,
+    AgentState.DONE: 4,
+}
+
+
+def _sort_key(info: AgentInfo) -> tuple:
+    # Archived agents sink past every live row regardless of state.
+    archived_bucket = 1 if info.archived else 0
+
+    # Within the archived bucket, state ordering doesn't matter — every
+    # archived row is "out of sight". Collapse them into a single state
+    # bucket so they sort purely by ended_at desc among themselves.
+    if info.archived:
+        state_bucket = 0
+    else:
+        state_bucket = STATE_PRIORITY.get(info.state, len(STATE_PRIORITY))
+
+    # For terminal/archived rows, prefer ended_at as the "when" timestamp;
+    # last_activity is the fallback so legacy rows without ended_at still sort.
+    if info.archived or info.state == AgentState.DONE:
+        when = info.ended_at if info.ended_at is not None else info.last_activity
+    else:
+        when = info.last_activity
+
+    # Tuple-compare: smaller archived/state buckets win; -when sorts desc;
+    # started_at asc breaks ties stably.
+    return (archived_bucket, state_bucket, -when, info.started_at)
+
+
+def sort_agents(infos: Iterable[AgentInfo]) -> list[AgentInfo]:
+    """Return `infos` ordered for default AgentTable display.
+
+    Pure: no side effects, no Textual coupling. Caller passes whatever
+    snapshot they want sorted (live, persisted, mixed).
+    """
+    return sorted(infos, key=_sort_key)

patchbai/agents/state.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class AgentState(str, Enum):
+    IDLE = "idle"
+    RUNNING = "running"
+    WAITING = "waiting"
+    DONE = "done"
+    ERROR = "error"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (AgentState.DONE, AgentState.ERROR)
+
+
+@dataclass
+class AgentInfo:
+    id: str
+    name: str
+    cwd: str
+    started_at: float
+    state: AgentState = AgentState.IDLE
+    ended_at: float | None = None
+    last_activity: float = field(default=0.0)
+    cost: float = 0.0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    archived: bool = False
+    # SDK session id observed from the first ResultMessage. Required to
+    # resume the conversation in a fresh process after a crash/restart.
+    session_id: str | None = None
+    # JSON-serializable kwargs needed to reconstruct ClaudeAgentOptions on
+    # resume (cwd, model, allowed_tools, disallowed_tools, system_prompt).
+    # None means this record was written before the resume feature existed
+    # and cannot be auto-resumed.
+    spawn_options: dict | None = None
+
+    def __post_init__(self) -> None:
+        if self.last_activity == 0.0:
+            self.last_activity = self.started_at
+
+    def elapsed_seconds(self) -> float:
+        end = self.ended_at if self.ended_at is not None else self.last_activity
+        return end - self.started_at
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "cwd": self.cwd,
+            "started_at": self.started_at,
+            "state": self.state.value,
+            "ended_at": self.ended_at,
+            "last_activity": self.last_activity,
+            "cost": self.cost,
+            "tokens_in": self.tokens_in,
+            "tokens_out": self.tokens_out,
+            "archived": self.archived,
+            "session_id": self.session_id,
+            "spawn_options": self.spawn_options,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentInfo":
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            cwd=d["cwd"],
+            started_at=d["started_at"],
+            state=AgentState(d["state"]),
+            ended_at=d.get("ended_at"),
+            last_activity=d.get("last_activity", d["started_at"]),
+            cost=d.get("cost", 0.0),
+            tokens_in=d.get("tokens_in", 0),
+            tokens_out=d.get("tokens_out", 0),
+            archived=d.get("archived", False),
+            session_id=d.get("session_id"),
+            spawn_options=d.get("spawn_options"),
+        )