expluro 0.1.8__tar.gz → 0.2.0__tar.gz

{expluro-0.1.8 → expluro-0.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.1.8
+Version: 0.2.0
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1
+Requires-Dist: agent-client-protocol<0.10.0,>=0.9.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: websockets>=12.0
 Requires-Dist: rich>=13.7

{expluro-0.1.8 → expluro-0.2.0}/expluro.egg-info/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.1.8
+Version: 0.2.0
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1
+Requires-Dist: agent-client-protocol<0.10.0,>=0.9.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: websockets>=12.0
 Requires-Dist: rich>=13.7

{expluro-0.1.8 → expluro-0.2.0}/expluro.egg-info/SOURCES.txt

@@ -19,5 +19,9 @@ topo/session_files.py
 topo/snapshot.py
 topo/update_check.py
 topo/drivers/__init__.py
+topo/drivers/_branch_detection.py
+topo/drivers/_permissions.py
+topo/drivers/acp.py
 topo/drivers/base.py
-topo/drivers/claude.py
+topo/drivers/claude.py
+topo/drivers/kiro_session_files.py

{expluro-0.1.8 → expluro-0.2.0}/expluro.egg-info/requires.txt

@@ -1,4 +1,5 @@
 claude-agent-sdk>=0.0.1
+agent-client-protocol<0.10.0,>=0.9.0
 httpx>=0.27
 websockets>=12.0
 rich>=13.7

{expluro-0.1.8 → expluro-0.2.0}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "expluro"
-version = "0.1.8"
+version = "0.2.0"
 description = "Expluro CLI — graph layer on top of your AI agent"
 requires-python = ">=3.10"
 dependencies = [
     "claude-agent-sdk>=0.0.1",
+    "agent-client-protocol>=0.9.0,<0.10.0",
     "httpx>=0.27",
     "websockets>=12.0",
     "rich>=13.7",

{expluro-0.1.8 → expluro-0.2.0}/topo/backend.py

@@ -72,10 +72,17 @@ class BackendClient:
     # Nodes
     # ------------------------------------------------------------------
 
-    async def create_node(self, graph_id: str, parent_id: str | None = None) -> dict[str, Any]:
+    async def create_node(
+        self,
+        graph_id: str,
+        parent_id: str | None = None,
+        tool: str | None = None,
+    ) -> dict[str, Any]:
         payload: dict[str, Any] = {"graph": graph_id}
         if parent_id:
             payload["parent"] = parent_id
+        if tool:
+            payload["tool"] = tool
         return await self._post("/api/nodes/", payload)
 
     async def patch_node(self, node_id: str, data: dict[str, Any]) -> dict[str, Any]:

{expluro-0.1.8 → expluro-0.2.0}/topo/capture.py

@@ -66,6 +66,16 @@ class EventCapture:
         # (e.g. when a tool is denied mid-response).
         self._streamed_text_buffer: str = ""
         self._text_complete_fired: bool = False
+        # Hook-driven persistence (pre/post_tool_use) fires synchronously
+        # from inside the driver's session_update handler, BEFORE the REPL
+        # loop drains the queued DriverEvent and gets a chance to flush a
+        # deferred user message. To preserve correct conversation order on
+        # the backend, we hold these events in a buffer while a user
+        # message is pending — flush_pending_user_message replays them in
+        # order after the user message is recorded. See session.py for the
+        # deferred-user-message lifecycle.
+        self._pending_user_message_text: str | None = None
+        self._buffered_hook_events: list[dict[str, Any]] = []
 
         SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
         self._log_file = self._open_log(node_id)
@@ -114,6 +124,19 @@ class EventCapture:
         )
         await self._record(event)
 
+    def set_pending_user_message(self, text: str) -> None:
+        """Mark a user message as pending durable persistence.
+
+        While a message is pending, hook-driven persistence (pre/post_tool_use
+        events) is buffered rather than written immediately. Flushing the
+        pending message replays the buffered events in order so the backend
+        sees correct conversation order: user → tool_use → tool_result → ai.
+
+        Only the first set_pending_user_message in a turn matters; subsequent
+        calls overwrite the text but don't reset the buffer.
+        """
+        self._pending_user_message_text = text
+
     async def record_user_message(self, text: str) -> None:
         """Record a user prompt as a durable event on the current node.
 
@@ -123,6 +146,9 @@ class EventCapture:
         no branch fired, child if it did — so the durable record always lands
         on the node that actually owns this message.
 
+        Also flushes any hook events buffered while this message was pending,
+        preserving the order user → tool events on the backend.
+
         For the live browser bubble, see broadcast_user_message_live() — that
         runs *before* the driver send and is non-persistent.
         """
@@ -137,6 +163,20 @@ class EventCapture:
         # The backend generates its own PK — the CLI UUID is never stored in the DB.
         self._last_user_message_event_id = backend_id or event["id"]
 
+        # Done deferring; flush any hook events that fired while we waited.
+        self._pending_user_message_text = None
+        if self._buffered_hook_events:
+            buffered = self._buffered_hook_events
+            self._buffered_hook_events = []
+            for evt in buffered:
+                # Re-anchor each buffered event onto whatever event came last
+                # (the user message we just wrote, or a previous buffered tool
+                # event) by updating parent_event_id from current state.
+                evt["parent_event_id"] = self._last_event_id
+                evt_id = await self._record(evt)
+                if evt_id:
+                    self._last_event_id = evt_id
+
     async def broadcast_user_message_live(self, text: str) -> None:
         """Live (non-persistent) broadcast of the user's just-typed message.
 
@@ -248,6 +288,11 @@ class EventCapture:
             tool_use_id=payload.tool_use_id,
             data={"tool_input": payload.tool_input},
         )
+        if self._pending_user_message_text is not None:
+            # Hold this event back so the user message anchors first on the
+            # backend. record_user_message replays the buffer in order.
+            self._buffered_hook_events.append(event)
+            return
         await self._record(event)
 
     async def _on_post_tool(self, payload: "ToolHookPayload") -> None:
@@ -262,6 +307,9 @@ class EventCapture:
                 "is_side_effecting": is_side_effecting,
             },
         )
+        if self._pending_user_message_text is not None:
+            self._buffered_hook_events.append(event)
+            return
         await self._record(event)
 
     # ------------------------------------------------------------------

expluro-0.2.0/topo/drivers/_branch_detection.py

@@ -0,0 +1,90 @@
+"""
+Branch detection — shared instruction + tag parser used by every driver.
+
+The model is asked to begin every response with `<!--BRANCH:X.XX-->`, where
+X.XX is its 0-1 confidence that the user's last message is a fork point.
+We parse the tag from the front of the streaming response, decide whether
+to fork, and strip the tag before the user ever sees it.
+
+Drivers wire this in two places:
+  - Inject `BRANCH_DETECTION_INSTRUCTION` so the model knows to emit the tag.
+    Claude does this via system_prompt; ACP-based agents (no protocol-level
+    system prompt) prepend it to the user's prompt text on each turn.
+  - Buffer the first chunk of streamed text per turn, call `parse_branch_flag`,
+    and emit a `branch_signal` event before the cleaned text.
+
+A backend copy lives at backend/llm/branch_detection.py for the web playground.
+Keep both in sync until the CLI and backend share a Python package.
+"""
+from __future__ import annotations
+
+import re
+
+BRANCH_DETECTION_INSTRUCTION = (
+    "\n\nIMPORTANT — OUTPUT FORMAT (overrides all other formatting rules):\n"
+    "Every response must begin with <!--BRANCH:X.XX--> on its own line, followed "
+    "by a newline, before any other character. Never skip, explain, or mention "
+    "this tag. If you're about to write anything else first, stop and output the tag.\n\n"
+    "X.XX is your confidence (0.00–1.00) that the user's most recent message is "
+    "a fork point relative to the prior conversation.\n\n"
+    "What a fork point is\n"
+    "A fork point is a turn where — if the user later replaced their message with "
+    "a different one — the resulting conversation would go somewhere meaningfully "
+    "different. It's a decision moment worth being able to revisit.\n\n"
+    "Judge the semantic shift, not the wording. Words like 'fork', 'pivot', "
+    "'different', or 'alternative' are not triggers on their own — 'let's fork into "
+    "option B' and 'let's try option B' are the same signal.\n\n"
+    "Two kinds of fork points\n"
+    "1. Option selection — the user picks one item from a set the assistant raised "
+    "(or that's implicit in the thread). E.g. assistant listed formal/natural/social "
+    "sciences, user says 'let's go deep on formal sciences.'\n"
+    "2. Topic or direction change — the user's message shifts to a substantially "
+    "different subject, goal, or approach. Options don't need to have been presented. "
+    "E.g. prior turn discussed Premier League, next message is 'when did World War I start?'\n\n"
+    "Not fork points\n"
+    "- Follow-up, clarification, or drill-down on the current thread.\n"
+    "- Correction, bug fix, or refinement of the current output.\n"
+    "- Incremental elaboration on the same topic.\n\n"
+    "Confidence bands\n"
+    "- 0.00–0.20 — follow-up, clarification, refinement\n"
+    "- 0.20–0.50 — noticeable shift but on the same general topic\n"
+    "- 0.50–0.70 — meaningful shift, ambiguous whether it's a fork\n"
+    "- 0.70–1.00 — clear fork: option chosen, or subject/direction changed substantially\n\n"
+    "Guardrails\n"
+    "- If fewer than 2 prior assistant responses exist, output ≤ 0.10 (not enough "
+    "context to fork from).\n"
+    "- When uncertain, bias downward. A missed fork is recoverable; a false positive "
+    "fragments the graph.\n\n"
+    "Examples\n"
+    "- Assistant listed options, user says 'dig into option A' → 0.90\n"
+    "- Prior turn on Ethiopian football, user asks 'when did WWII happen?' → 0.85\n"
+    "- 'Let's try a completely different approach' on the current task → 0.85\n"
+    "- Conversation was about database schema, user asks 'how should we handle "
+    "migrations?' (related but distinct decision scope) → 0.70\n"
+    "- User shifts from implementation details to architecture of the same solution → 0.40\n"
+    "- User asks 'how does this work?' on what was just explained → 0.05\n"
+    "- 'This is broken, fix the null case' → 0.10\n"
+    "- 'I just forked the GitHub repo to experiment locally' (mentions 'fork' "
+    "but is describing an action, not expressing branching intent) → 0.10\n"
+    "- First message of the session → 0.00\n\n"
+    "After the tag, on the next line, write your normal response."
+)
+
+BRANCH_FLAG_START_RE = re.compile(r"^<!--BRANCH:([\d.]+)-->\r?\n?")
+
+# Flush the head buffer once we have this many chars without a newline —
+# protects against a model that ignores the instruction and never emits one.
+HEAD_BUFFER_MAX = 40
+
+
+def parse_branch_flag(buffered_head: str) -> tuple[float | None, str]:
+    """Parse the BRANCH tag from a buffered head chunk.
+
+    Returns (confidence, remaining_text). When the head doesn't start with
+    a valid tag, confidence is None and the entire buffered_head is
+    returned as remaining_text — caller should treat it as regular content.
+    """
+    m = BRANCH_FLAG_START_RE.match(buffered_head)
+    if m:
+        return float(m.group(1)), buffered_head[m.end():]
+    return None, buffered_head

expluro-0.2.0/topo/drivers/_permissions.py

@@ -0,0 +1,135 @@
+"""
+Shared interactive permission UI used by every driver (Claude native,
+ACP-based agents, etc.).
+
+The agent-side details differ per driver: Claude uses a PreToolUse hook,
+ACP uses session/request_permission. Both surfaces converge on the same
+question — does the user want to let this tool run? — and the same UI:
+an arrow-key picker offering Allow / Always allow this tool / Deny /
+Bypass all.
+
+Drivers own their own PermissionState (the always-allowed set and
+bypass flag) so each agent has its own trust memory. The helper here
+just shows the picker and tells the driver which choice was made; the
+driver maps that decision to its native protocol response.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class PermissionDecision(Enum):
+    """What the user picked. Drivers translate this to their protocol's response."""
+    ALLOW_ONCE = "allow_once"
+    ALLOW_ALWAYS = "allow_always"
+    DENY = "deny"
+    BYPASS_ALL = "bypass_all"
+
+
+@dataclass
+class PermissionState:
+    """Per-driver memory for permission shortcuts.
+
+    `always_allowed` survives across branches because the user has explicitly
+    granted persistent trust to that tool. `bypass_all` does NOT survive a
+    branch switch — it's too broad to silently inherit on a new branch.
+    Drivers reset `bypass_all` at branch boundaries themselves; this struct
+    just stores it.
+    """
+    always_allowed: set[str] = field(default_factory=set)
+    bypass_all: bool = False
+
+    def fast_allow(self, tool_name: str) -> bool:
+        """Skip the picker entirely if a prior choice already covers this tool."""
+        return self.bypass_all or tool_name in self.always_allowed
+
+
+async def ask_user_for_permission(
+    tool_name: str,
+    summary: str,
+    *,
+    state: PermissionState,
+) -> PermissionDecision:
+    """Show the interactive picker. Mutates `state` on always/bypass choices.
+
+    Caller should check `state.fast_allow(tool_name)` first and skip this
+    function entirely if it returns True. We always show the picker if we
+    get here; we don't second-guess the caller.
+
+    `tool_name` is the short label shown in the header (e.g. "Bash", "Read",
+    or for ACP a generic "execute" / "edit" / etc).
+
+    `summary` is the optional one-line detail shown under the header (e.g.
+    the actual command, file path, query). Empty string if no detail.
+
+    KeyboardInterrupt during the picker is treated as deny — same as the
+    user picking "Deny" — so Ctrl+C is a fast-path no.
+    """
+    # Late imports to avoid cycles with picker / renderer at module-load time.
+    from ..picker import pick_option
+    from ..renderer import pause_active_spinner, resume_active_spinner
+
+    summary_line = (
+        f"\n  <ansibrightblack>  {summary}</ansibrightblack>" if summary else ""
+    )
+    header = (
+        f"  <ansicyan>⚙ {tool_name}</ansicyan>  "
+        f"<ansibrightblack>wants to run:</ansibrightblack>{summary_line}"
+    )
+
+    options: list[tuple[str, str]] = [
+        ("Allow", "allow"),
+        (f"Always allow {tool_name}", "always"),
+        ("Deny", "deny"),
+        ("Bypass all checks", "bypass"),
+    ]
+
+    pause_active_spinner()
+    try:
+        result = await pick_option(header, options)
+    except KeyboardInterrupt:
+        resume_active_spinner()
+        logger.info("Permission: cancelled for %s", tool_name)
+        return PermissionDecision.DENY
+    resume_active_spinner()
+
+    if result == "always":
+        state.always_allowed.add(tool_name)
+        logger.info("Permission: always allow %s", tool_name)
+        return PermissionDecision.ALLOW_ALWAYS
+    if result == "bypass":
+        state.bypass_all = True
+        logger.info("Permission: bypass all remaining checks")
+        return PermissionDecision.BYPASS_ALL
+    if result == "allow":
+        return PermissionDecision.ALLOW_ONCE
+
+    logger.info("Permission: user denied %s", tool_name)
+    return PermissionDecision.DENY
+
+
+def decision_is_allow(decision: PermissionDecision) -> bool:
+    """Convenience for drivers that just want a yes/no signal."""
+    return decision in (
+        PermissionDecision.ALLOW_ONCE,
+        PermissionDecision.ALLOW_ALWAYS,
+        PermissionDecision.BYPASS_ALL,
+    )
+
+
+# Type-only re-export so pydantic / drivers can annotate cleanly.
+__all__ = [
+    "PermissionDecision",
+    "PermissionState",
+    "ask_user_for_permission",
+    "decision_is_allow",
+]
+
+
+# Avoid unused imports linter noise:
+_: Any = None