expluro 0.3.0__tar.gz → 0.3.1__tar.gz

{expluro-0.3.0 → expluro-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.3.0
+Version: 0.3.1
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1

{expluro-0.3.0 → expluro-0.3.1}/expluro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: expluro
-Version: 0.3.0
+Version: 0.3.1
 Summary: Expluro CLI — graph layer on top of your AI agent
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.0.1

{expluro-0.3.0 → expluro-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "expluro"
-version = "0.3.0"
+version = "0.3.1"
 description = "Expluro CLI — graph layer on top of your AI agent"
 requires-python = ">=3.10"
 dependencies = [

{expluro-0.3.0 → expluro-0.3.1}/topo/drivers/_branch_detection.py

@@ -97,3 +97,50 @@ def parse_branch_flag(buffered_head: str) -> tuple[float | None, str]:
     except ValueError:
         return None, buffered_head[m.end():]
     return confidence, buffered_head[m.end():]
+
+
+def strip_all_branch_tags(text: str) -> tuple[float | None, str]:
+    """Strip every leading BRANCH tag from `text` and return (confidence, rest).
+
+    Defensive against three model misbehaviours, in one place so every
+    driver inherits the same protection:
+
+      - **Multiple stacked tags** — e.g. `<!--BRANCH:0.0--><!--BRANCH:0.5-->Hi`.
+        We loop `parse_branch_flag` and strip them all; the *first*
+        confidence wins (subsequent tags are usually a model emitting
+        the marker more than once, not actually multiple decisions).
+
+      - **Partial tag at end** — e.g. `<!--BRANCH:0.5` with no closing
+        `-->`. Happens when a tool call interrupts a tag stream. We drop
+        the partial-tag bytes so they don't leak into rendered text.
+
+      - **Malformed digits** — handled inside `parse_branch_flag`
+        (the tag is consumed silently, no confidence reported).
+
+    Returns the first valid confidence found (or None if no parseable
+    tag was at the head), and the remaining text after all leading tags
+    are stripped (or empty string if the remaining content was a
+    partial-tag prefix).
+    """
+    first_confidence: float | None = None
+    buf = text
+    while True:
+        confidence, rest = parse_branch_flag(buf)
+        if confidence is None and rest == buf:
+            # No tag matched at all — buf is plain content.
+            break
+        # A tag was consumed (confidence may still be None if the tag's
+        # digits were malformed). Capture the first valid confidence.
+        if first_confidence is None and confidence is not None:
+            first_confidence = confidence
+        buf = rest
+        if not buf:
+            break
+
+    # If the buffer is now a partial tag prefix (no closing `-->`),
+    # the model started a tag we never saw the end of. Drop it
+    # rather than leak `<!--BRANCH:0.5` to the renderer.
+    if buf.startswith("<!--BRANCH:") and "-->" not in buf:
+        buf = ""
+
+    return first_confidence, buf

{expluro-0.3.0 → expluro-0.3.1}/topo/drivers/acp.py

@@ -48,6 +48,7 @@ from ._branch_detection import (
     BRANCH_FLAG_START_RE,
     HEAD_BUFFER_MAX,
     parse_branch_flag,
+    strip_all_branch_tags,
 )
 from ._permissions import (
     PermissionDecision,
@@ -97,6 +98,27 @@ class ACPDriver(BaseDriver):
         self._event_queue: asyncio.Queue[DriverEvent | object] = asyncio.Queue()
         # Tracks tool calls in flight so we can fire pre/post hooks symmetrically.
         self._active_tool_calls: dict[str, ToolHookPayload] = {}
+        # Every tool_call_id we've ever surfaced as a tool_use event in this
+        # driver's lifetime. After an auto-branch the agent reconnects via
+        # load_session, and Kiro then re-emits ToolCallStart for tool calls
+        # it already ran in the parent — a "synchronization replay." Without
+        # deduping, those land in the new node as phantom tool calls (often
+        # stuck on "running…" because their Progress event is also a replay
+        # the browser can't reconcile). The set lives for the driver's full
+        # lifetime intentionally: replays after subsequent reconnects must
+        # also be filtered. tool_call_ids are random, so collision with a
+        # genuinely new call is effectively impossible.
+        self._seen_tool_call_ids: set[str] = set()
+        # Per-turn assistant text accumulator. ACP doesn't have a protocol-
+        # level "message complete" notification — it just streams chunks
+        # and finishes the prompt. Without an end-of-turn text_complete
+        # event the renderer's rich.Live never flushes (so the terminal
+        # stays blank) and capture's message_ai persistence falls back to
+        # raw chunks (so the browser shows orphan unselectable text outside
+        # any message bubble). We accumulate all text we emit during a turn
+        # and surface it as a single text_complete in _run_prompt's finalize
+        # block, matching the Claude driver's behavior.
+        self._turn_text_buffer: str = ""
         # Set by reset_context() before connect() to ask connect() to load
         # an existing session via session/load_session instead of creating a
         # fresh one. Mirrors ClaudeDriver's _resume_session_id pattern.
@@ -138,6 +160,15 @@ class ACPDriver(BaseDriver):
         logger.debug("ACPDriver: spawning agent: %s", " ".join(self._command))
         binary = self._command[0] if self._command else ""
         try:
+            # `limit` raises asyncio's per-line buffer for the StreamReader
+            # the SDK reads line-delimited JSON-RPC from. Default is 64 KB,
+            # which Kiro can blow past in a single AgentMessageChunk for
+            # long-form answers or large tool outputs. When that happens
+            # asyncio raises LimitOverrunError ("Separator is not found,
+            # and chunk exceed the limit"), the SDK reader dies, and the
+            # session hangs on the next prompt with no recovery path.
+            # 4 MB covers any reasonable agent message; we'd rather pay a
+            # few MB of buffer than break the session on a long answer.
             self._proc = await asyncio.create_subprocess_exec(
                 *self._command,
                 stdin=asyncio.subprocess.PIPE,
@@ -147,6 +178,7 @@ class ACPDriver(BaseDriver):
                 cwd=cwd,
                 env=os.environ.copy(),
                 start_new_session=True,
+                limit=4 * 1024 * 1024,
             )
         except FileNotFoundError as exc:
             # The picker filters by shutil.which, but binaries can be
@@ -380,6 +412,7 @@ class ACPDriver(BaseDriver):
         self._head_buf = ""
         self._head_parsed = False
         self._branch_signal_fired_this_turn = False
+        self._turn_text_buffer = ""
 
         # Fire-and-forget the prompt as a background task. The connection's
         # `prompt()` returns a PromptResponse when the agent finishes. We
@@ -411,6 +444,22 @@ class ACPDriver(BaseDriver):
             # streaming and would otherwise be lost when the turn ends.
             assert self._session_id is not None
             await self._flush_head_buffer(self._session_id)
+            # Emit text_complete with the assembled assistant text. The
+            # renderer needs this to flush its rich.Live buffer (otherwise
+            # short responses stay invisible in the terminal); capture
+            # needs it to persist a clean message_ai event (otherwise the
+            # browser shows orphan unselectable text outside any message
+            # bubble). Note: this fires AFTER _flush_head_buffer above so
+            # any tail-of-turn text the head buffer was holding is included.
+            if self._turn_text_buffer:
+                await self._event_queue.put(
+                    DriverEvent(
+                        type="text_complete",
+                        data={"text": self._turn_text_buffer, "session_id": self._session_id},
+                        raw=None,
+                    )
+                )
+                self._turn_text_buffer = ""
             # Emit a result event capturing usage if present, then end-of-turn.
             data: dict[str, Any] = {}
             if response is not None:
@@ -440,6 +489,16 @@ class ACPDriver(BaseDriver):
     # ------------------------------------------------------------------
 
     async def _emit(self, event: DriverEvent) -> None:
+        # Accumulate every text chunk we emit during this turn so the
+        # finalize block of _run_prompt can surface it as a text_complete
+        # event. The renderer relies on text_complete to flush its
+        # rich.Live; capture relies on it to persist message_ai. Without
+        # this, both surfaces show the assistant text incorrectly (blank
+        # terminal, orphan-text browser bubble).
+        if event.type == "text":
+            chunk = event.data.get("text", "")
+            if chunk:
+                self._turn_text_buffer += chunk
         await self._event_queue.put(event)
 
     async def _handle_text_chunk(self, text: str, session_id: str, raw: Any) -> None:
@@ -478,15 +537,9 @@ class ACPDriver(BaseDriver):
              short post-tool text response (e.g. "Your username is yab"
              with no newline) doesn't get stuck in the buffer and lost.
 
-        Defensive against three model misbehaviours:
-          - Multiple stacked tags (`<!--BRANCH:0.0--><!--BRANCH:0.5-->Hi`):
-            strip ALL leading tags, not just the first, so none leak.
-          - Partial tag at flush time (`<!--BRANCH:0.5` with no `-->`):
-            happens if a tool call interrupts mid-tag-stream. Drop the
-            partial-tag bytes rather than emitting them as visible text.
-          - Malformed digits (`<!--BRANCH:.-->`): handled inside
-            parse_branch_flag — the tag is consumed, no confidence
-            recorded.
+        Multi-tag, partial-tag, and malformed-digit defenses live in
+        `strip_all_branch_tags` so the Claude driver gets the same
+        behaviour for free.
 
         Caller is responsible for resetting `_head_parsed` after this if
         appropriate. We deliberately do not reset state here so the
@@ -494,31 +547,9 @@ class ACPDriver(BaseDriver):
         """
         if not self._head_buf:
             return
-        buf = self._head_buf
+        first_confidence, buf = strip_all_branch_tags(self._head_buf)
         self._head_buf = ""
 
-        first_confidence: float | None = None
-        # Strip every leading tag. Defensive against double-emission.
-        while True:
-            confidence, rest = parse_branch_flag(buf)
-            if confidence is None and rest == buf:
-                # No tag matched at all — buf is plain content.
-                break
-            # A tag was consumed (confidence may still be None if the
-            # tag's digits were malformed). Capture the first valid
-            # confidence we see.
-            if first_confidence is None and confidence is not None:
-                first_confidence = confidence
-            buf = rest
-            if not buf:
-                break
-
-        # If the buffer is now a partial tag prefix (no closing `-->`),
-        # the model started a tag we never saw the end of. Drop it
-        # rather than leak `<!--BRANCH:0.5` to the renderer.
-        if buf.startswith("<!--BRANCH:") and "-->" not in buf:
-            buf = ""
-
         if first_confidence is not None and not self._branch_signal_fired_this_turn:
             self._branch_signal_fired_this_turn = True
             await self._emit(
@@ -701,6 +732,34 @@ class _ACPClient(Client):
             tool_use_id = getattr(update, "tool_call_id", "") or getattr(update, "id", "")
             tool_kind = getattr(update, "kind", None)
             tool_input = _extract_tool_input(update)
+            # INFO so this is captured in cli.log at the default level.
+            # 1–3 entries per turn; the most useful diagnostic data we
+            # have for ACP-side bugs (duplicate tool calls, status
+            # mismatches, etc.).
+            logger.info(
+                "ACPDriver: ToolCallStart id=%s kind=%s status=%s title=%r",
+                tool_use_id,
+                tool_kind,
+                getattr(update, "status", None),
+                tool_name,
+            )
+            # Replay guard: after an auto-branch reconnects via load_session,
+            # Kiro re-emits ToolCallStart for tool calls it ran in the parent.
+            # We've already surfaced those as tool_use events on the parent
+            # node, so re-surfacing them on the child creates phantom entries
+            # (the title degrades to just `kind` — e.g. 'shell' — and the
+            # corresponding Progress also replays, leaving a tool_use with
+            # no real result the user can act on). Skip silently if we've
+            # already seen this id.
+            if tool_use_id and tool_use_id in self._driver._seen_tool_call_ids:
+                logger.info(
+                    "ACPDriver: ToolCallStart REPLAY id=%s skipped "
+                    "(already surfaced earlier in this driver lifetime)",
+                    tool_use_id,
+                )
+                return
+            if tool_use_id:
+                self._driver._seen_tool_call_ids.add(tool_use_id)
             payload = ToolHookPayload(
                 tool_name=tool_name,
                 tool_input=tool_input,
@@ -752,6 +811,24 @@ class _ACPClient(Client):
         if isinstance(update, ToolCallProgress):
             tool_use_id = getattr(update, "tool_call_id", "") or getattr(update, "id", "")
             status = getattr(update, "status", None)
+            logger.info(
+                "ACPDriver: ToolCallProgress id=%s status=%s",
+                tool_use_id, status,
+            )
+            # Replay guard companion to the one in ToolCallStart: if the
+            # corresponding Start was skipped as a replay, _active_tool_calls
+            # has no entry for this id and emitting tool_result here would
+            # surface the phantom completion to the browser even though we
+            # never surfaced the start. Bail unless this id has an active
+            # in-flight payload that THIS driver registered.
+            if tool_use_id and tool_use_id not in self._driver._active_tool_calls:
+                logger.info(
+                    "ACPDriver: ToolCallProgress REPLAY id=%s skipped "
+                    "(no matching in-flight tool_use; either replay or "
+                    "Progress arrived after pop)",
+                    tool_use_id,
+                )
+                return
             # ToolCallStatus values include "in_progress", "completed", "failed".
             if status is not None and str(status).lower() in ("completed", "failed"):
                 payload = self._driver._active_tool_calls.pop(tool_use_id, None)
@@ -801,26 +878,32 @@ class _ACPClient(Client):
         options = kwargs.get("options") or []
         tool_call = kwargs.get("tool_call")
 
-        # Pull tool name + summary out of the ACP tool_call. Kiro fills `title`
-        # with a human-readable description (e.g. "Run command: ls -la"); when
-        # absent we fall back to `kind` ('execute', 'edit', etc.).
-        tool_name = (
-            getattr(tool_call, "title", None)
-            or getattr(tool_call, "kind", None)
-            or "tool"
-        )
-        # Kiro's title already encodes the action, so we leave summary blank
-        # to avoid duplicating the same text twice in the picker header.
-        summary = ""
-
-        # Fast path: prior "always allow this tool" or "bypass all" decision.
+        # Use `kind` as the trust-keying identifier, not `title`. `title` is
+        # the per-invocation description ("Run command: cat /etc/hosts 2>&1")
+        # — keying always-allow on it means the user has to re-approve every
+        # unique command. `kind` is the category ("execute", "read", "edit"),
+        # so "Always allow execute" actually applies to the next shell
+        # command. Mirrors how the Claude driver keys on the Anthropic tool
+        # name ("Bash", "Read"). Closes #55.
+        #
+        # The verbose title moves into `summary`, which the picker shows
+        # underneath the kind label so the user still sees what's actually
+        # about to run before approving.
+        tool_kind = getattr(tool_call, "kind", None) or "tool"
+        title = getattr(tool_call, "title", "") or ""
+        raw_input = getattr(tool_call, "raw_input", None)
+        if not isinstance(raw_input, dict):
+            raw_input = {}
+        summary = _kiro_tool_summary(tool_kind, raw_input, title)
+
+        # Fast path: prior "always allow this kind" or "bypass all" decision.
         state = self._driver._permission_state
-        if state.fast_allow(tool_name):
+        if state.fast_allow(tool_kind):
             return _select_first_allow(options) or _denied_response()
 
         # Show the picker.
         decision = await ask_user_for_permission(
-            tool_name=tool_name,
+            tool_name=tool_kind,
             summary=summary,
             state=state,
         )
@@ -890,6 +973,47 @@ class _ACPClient(Client):
                 logger.exception("ACPDriver: failed to emit write_text_file error event")
 
 
+def _kiro_tool_summary(kind: str, raw_input: dict[str, Any], title: str) -> str:
+    """One-line summary for the permission picker, derived from the tool kind.
+
+    Mirrors `_tool_input_summary` in claude.py — show the action's most
+    relevant parameter (the command, the path, the query) underneath the
+    kind label so the user knows exactly what they're approving without
+    needing the verbose Kiro title.
+
+    Falls back to the title (with the noisy "Run command: " prefix Kiro
+    adds for shell commands stripped) when raw_input doesn't contain a
+    field we recognize. Truncates to 120 chars to keep the picker compact.
+    """
+    text: str = ""
+    if kind == "execute":
+        text = str(raw_input.get("command", "") or raw_input.get("input", "") or "")
+    elif kind in ("read", "edit", "delete", "move"):
+        text = str(raw_input.get("path", "") or raw_input.get("file_path", "") or "")
+    elif kind == "search":
+        text = str(raw_input.get("pattern", "") or raw_input.get("query", "") or "")
+    elif kind == "fetch":
+        text = str(raw_input.get("url", "") or "")
+
+    if not text:
+        # Fallback: try the title, stripping the noisy "Run command: "
+        # prefix Kiro adds for shell commands so it reads like a normal
+        # command line.
+        cleaned_title = title
+        if cleaned_title.startswith("Run command: "):
+            cleaned_title = cleaned_title[len("Run command: "):]
+        text = cleaned_title
+
+    if not text:
+        # Last resort: first stringy value in raw_input.
+        for v in raw_input.values():
+            if isinstance(v, str) and v:
+                text = v
+                break
+
+    return text[:120] + ("…" if len(text) > 120 else "")
+
+
 def _extract_tool_input(update: Any) -> dict[str, Any]:
     """
     Build a tool_input dict from an ACP ToolCall(Start|Update).

{expluro-0.3.0 → expluro-0.3.1}/topo/drivers/claude.py

@@ -53,7 +53,8 @@ from ._branch_detection import (
     BRANCH_DETECTION_INSTRUCTION as _BRANCH_DETECTION_INSTRUCTION,
     BRANCH_FLAG_START_RE as _BRANCH_FLAG_START_RE,
     HEAD_BUFFER_MAX as _HEAD_BUFFER_MAX,
-    parse_branch_flag as _parse_branch_flag,  # noqa: F401  (kept for symmetry; existing logic uses regex directly)
+    parse_branch_flag as _parse_branch_flag,  # noqa: F401  (kept for symmetry)
+    strip_all_branch_tags as _strip_all_branch_tags,
 )
 
 
@@ -75,6 +76,15 @@ class ClaudeDriver(BaseDriver):
         # Branch signal head buffer — accumulates first line to parse the flag before streaming
         self._head_buf: str = ""
         self._head_parsed: bool = False
+        # Defensive replay-guard, mirroring ACPDriver. The Claude Agent SDK
+        # likely doesn't re-emit ToolUseBlocks after --resume (subsequent
+        # receive_response() returns NEW messages, not historical), but
+        # tool_use_ids are unique enough that collision with a real new call
+        # is impossible — so adding the guard is free insurance against any
+        # future SDK change or edge case we haven't observed. If this set
+        # ever fires (logged at INFO), we'll know Claude has the same
+        # phantom-tool-call bug we fixed for ACP and can act accordingly.
+        self._seen_tool_call_ids: set[str] = set()
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -346,39 +356,37 @@ class ClaudeDriver(BaseDriver):
                         if ready:
                             self._head_parsed = True
                             logger.debug("Head buffer resolved: %r", self._head_buf[:60])
-                            m = _BRANCH_FLAG_START_RE.match(self._head_buf)
-                            if m:
-                                confidence = float(m.group(1))
-                                rest = self._head_buf[m.end():]
+                            # Strip every leading BRANCH tag (defensive against
+                            # double-emission, partial tags from interrupted
+                            # streams, and malformed digits) — same logic the
+                            # ACP driver uses, factored into the shared helper.
+                            confidence, rest = _strip_all_branch_tags(self._head_buf)
+                            self._head_buf = ""
+                            if confidence is not None:
                                 events.append(DriverEvent(
                                     type="branch_signal",
                                     data={"confidence": confidence, "session_id": msg.session_id},
                                     raw=msg,
                                 ))
-                                if rest:
-                                    events.append(DriverEvent(
-                                        type="text",
-                                        data={"text": rest, "session_id": msg.session_id},
-                                        raw=msg,
-                                    ))
-                            else:
-                                # No flag — flush buffered head as regular text.
+                            if rest:
                                 events.append(DriverEvent(
                                     type="text",
-                                    data={"text": self._head_buf, "session_id": msg.session_id},
+                                    data={"text": rest, "session_id": msg.session_id},
                                     raw=msg,
                                 ))
-                            self._head_buf = ""
             return events
 
         if isinstance(msg, AssistantMessage):
             for block in msg.content:
                 if isinstance(block, TextBlock):
                     text = block.text
-                    # Strip flag from start for clean persistence — signal already
-                    # emitted during streaming so don't emit it again here.
-                    m = _BRANCH_FLAG_START_RE.match(text)
-                    clean_text = text[m.end():] if m else text
+                    # Strip every leading BRANCH tag for clean persistence.
+                    # Confidence is discarded here — the streaming path
+                    # already emitted branch_signal during head-buffer
+                    # resolution; emitting again would double-fire the
+                    # auto-branch handler. Same multi-tag, partial-tag,
+                    # malformed-digit defenses as the ACP driver.
+                    _, clean_text = _strip_all_branch_tags(text)
                     self._head_buf = ""
                     self._head_parsed = False
                     events.append(DriverEvent(
@@ -393,6 +401,30 @@ class ClaudeDriver(BaseDriver):
                         raw=msg,
                     ))
                 elif isinstance(block, ToolUseBlock):
+                    # INFO-level so cli.log captures the tool-call lifecycle
+                    # at the default log level — matches ACPDriver. Cheap
+                    # diagnostic data: 1–3 entries per turn, the most useful
+                    # signal we have when a tool flow goes sideways.
+                    logger.info(
+                        "ClaudeDriver: ToolUse name=%s id=%s",
+                        block.name, block.id,
+                    )
+                    # Replay-guard mirroring the ACP path. If the SDK ever
+                    # re-emits a ToolUseBlock for an id we've already
+                    # surfaced (e.g. after --resume on a forked session),
+                    # we'd otherwise emit a phantom tool_use the browser
+                    # can't reconcile. Skip the duplicate. If this branch
+                    # ever fires (visible in cli.log), we'll know Claude
+                    # has the same replay behaviour we patched for Kiro.
+                    if block.id and block.id in self._seen_tool_call_ids:
+                        logger.info(
+                            "ClaudeDriver: ToolUse REPLAY id=%s skipped "
+                            "(already surfaced earlier in this driver lifetime)",
+                            block.id,
+                        )
+                        continue
+                    if block.id:
+                        self._seen_tool_call_ids.add(block.id)
                     events.append(DriverEvent(
                         type="tool_use",
                         data={
@@ -404,6 +436,10 @@ class ClaudeDriver(BaseDriver):
                         raw=msg,
                     ))
                 elif isinstance(block, ToolResultBlock):
+                    logger.info(
+                        "ClaudeDriver: ToolResult tool_use_id=%s",
+                        block.tool_use_id,
+                    )
                     events.append(DriverEvent(
                         type="tool_result",
                         data={

expluro-0.3.1/topo/drivers/kiro_session_files.py

@@ -0,0 +1,277 @@
+"""
+Kiro session file forking.
+
+Kiro's ACP server does not implement `session/fork_session` (advertised
+fork capability is null; calling the method returns "Method not found").
+But it does support `session/load_session`, and it accepts session files
+written manually to ~/.kiro/sessions/cli/<uuid>.jsonl + .json.
+
+So we fork the same way the Claude driver does: copy the parent's session
+files to a new UUID, truncate to the branch point, ask Kiro to load_session
+the new UUID. The agent treats it as a real session.
+
+File layout (verified empirically):
+- <uuid>.jsonl: one event per line. Two kinds: Prompt and AssistantMessage.
+  Each carries message_id, content blocks, optional meta.timestamp.
+- <uuid>.json: metadata. Contains session_id, cwd, title, session_state with
+  per-turn telemetry (user_turn_metadatas). Kiro accepts copied/truncated
+  metadata even though some fields like input_token_count, metering_usage
+  reflect the parent's values.
+- <uuid>.lock: process lock. Created by the agent process on open. We do
+  NOT plant a lock file; Kiro creates one when it opens the session.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+KIRO_SESSIONS_DIR = Path.home() / ".kiro" / "sessions" / "cli"
+
+
+def fork_kiro_session(
+    parent_session_id: str,
+    message_count: int,
+    cwd: str,
+) -> str | None:
+    """
+    Create a new Kiro session file by copying the parent's session files,
+    truncated to the first `message_count // 2` complete user turns.
+
+    `message_count` is interpreted the same way Claude's
+    `session_files.fork_at_message_count` does it: the number of {role,
+    content} pairs from `materialized_context` (user prompts + assistant
+    responses, 2 per exchange). We round up so a cut after a user prompt
+    but before its assistant response includes the response — leaving a
+    dangling user prompt in the session file makes Kiro panic with
+    "invalid conversation history received" on resume.
+
+    Why this differs from naive `lines[:message_count]`: a single
+    materialized_context exchange may span many JSONL entries when the
+    turn includes tool calls (Prompt → AssistantMessage → ToolResults →
+    AssistantMessage is one turn but four lines). Naive line truncation
+    cuts mid-turn and leaves either a dangling Prompt (panic) or a
+    truncated AssistantMessage (missing content). Mirrors Claude's
+    `_collect_turns` for the same reason.
+
+    Returns the new session UUID, or None on failure.
+
+    Why we don't use ACP fork_session: Kiro returns "Method not found".
+    Why we generate the UUID ourselves: matches Claude's approach. Lets us
+    return the new id synchronously and write predictable filenames.
+    """
+    parent_jsonl = KIRO_SESSIONS_DIR / f"{parent_session_id}.jsonl"
+    parent_json = KIRO_SESSIONS_DIR / f"{parent_session_id}.json"
+
+    if not parent_jsonl.exists() or not parent_json.exists():
+        logger.warning(
+            "kiro_session_files: parent session files not found for %s in %s",
+            parent_session_id, KIRO_SESSIONS_DIR,
+        )
+        return None
+
+    if message_count <= 0:
+        logger.warning(
+            "kiro_session_files: refusing to fork at message_count=%d (must be > 0)",
+            message_count,
+        )
+        return None
+
+    # materialized_context counts user prompts and assistant responses
+    # equally, so message_count // 2 is the number of real user prompts
+    # to collect. Round up on odd inputs (caller asked for a cut after a
+    # user prompt but before its response — better to include the whole
+    # turn than leave a dangling prompt).
+    user_turns_needed = (message_count + 1) // 2
+
+    # Defensive flush wait: Kiro's session writer is async, and the
+    # ACPDriver's close_session call should make it flush before we get
+    # here. But if the writer hasn't caught up, we'd fork an incomplete
+    # state. Wait up to 2s for the file to contain the requested number
+    # of COMPLETE turns (each having an AssistantMessage following the
+    # Prompt). Beats the previous strategy of waiting for raw line count
+    # because turn boundaries don't map 1:1 to line counts.
+    deadline = time.monotonic() + 2.0
+    new_lines: list[str] = []
+    turn_count: int = 0
+    while time.monotonic() < deadline:
+        try:
+            current_lines = parent_jsonl.read_text().splitlines()
+        except OSError:
+            current_lines = []
+        new_lines, turn_count = _collect_kiro_turns(current_lines, user_turns_needed)
+        if turn_count >= user_turns_needed:
+            break
+        time.sleep(0.05)
+
+    if turn_count < user_turns_needed:
+        # Re-read once more in case of last-instant flush, then proceed
+        # with whatever's there. Logging is loud so we can spot this
+        # in bug reports.
+        try:
+            final_lines = parent_jsonl.read_text().splitlines()
+        except OSError:
+            final_lines = []
+        new_lines, turn_count = _collect_kiro_turns(final_lines, user_turns_needed)
+        if turn_count < user_turns_needed:
+            logger.warning(
+                "kiro_session_files: parent file has %d complete turns but "
+                "expected %d after flush wait; forking with what we have "
+                "(the result may be missing the latest exchange)",
+                turn_count, user_turns_needed,
+            )
+
+    if not new_lines:
+        logger.warning(
+            "kiro_session_files: no complete turns collected from parent %s "
+            "(file may be empty or end with a dangling user prompt)",
+            parent_session_id,
+        )
+        return None
+
+    try:
+        metadata = json.loads(parent_json.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("kiro_session_files: failed to read parent json metadata: %s", exc)
+        return None
+
+    new_uuid = str(uuid.uuid4())
+
+    # Truncate user_turn_metadatas to match the number of complete turns.
+    # Update session_id and conversation_id to the new UUID. Leave other
+    # metadata fields (cwd, title, permissions, model state) as-is. Kiro
+    # accepted this in our test runs.
+    metadata["session_id"] = new_uuid
+    conv_meta = (
+        metadata.setdefault("session_state", {})
+        .setdefault("conversation_metadata", {})
+    )
+    user_turn_metadatas = conv_meta.get("user_turn_metadatas", []) or []
+    conv_meta["user_turn_metadatas"] = user_turn_metadatas[:turn_count]
+    conv_meta["user_turn_start_request"] = None
+    conv_meta["last_request"] = None
+
+    rts_state = metadata.get("session_state", {}).get("rts_model_state")
+    if isinstance(rts_state, dict):
+        rts_state["conversation_id"] = new_uuid
+
+    new_jsonl_path = KIRO_SESSIONS_DIR / f"{new_uuid}.jsonl"
+    new_json_path = KIRO_SESSIONS_DIR / f"{new_uuid}.json"
+
+    try:
+        # Write JSONL and metadata atomically: write to .tmp then rename.
+        # Avoids leaving a half-written file if we crash mid-write.
+        tmp_jsonl = new_jsonl_path.with_suffix(".jsonl.tmp")
+        tmp_json = new_json_path.with_suffix(".json.tmp")
+        tmp_jsonl.write_text("\n".join(new_lines) + "\n")
+        tmp_json.write_text(json.dumps(metadata, indent=2))
+        tmp_jsonl.rename(new_jsonl_path)
+        tmp_json.rename(new_json_path)
+    except OSError as exc:
+        logger.warning("kiro_session_files: failed to write forked session files: %s", exc)
+        # Best-effort cleanup.
+        for p in (new_jsonl_path, new_json_path):
+            try:
+                p.unlink(missing_ok=True)
+            except OSError:
+                pass
+        return None
+
+    logger.info(
+        "kiro_session_files: forked %s -> %s (lines=%d, turns=%d)",
+        parent_session_id, new_uuid, len(new_lines), turn_count,
+    )
+    return new_uuid
+
+
+def kiro_session_exists(session_id: str) -> bool:
+    """Check if a Kiro session file exists locally."""
+    return (KIRO_SESSIONS_DIR / f"{session_id}.jsonl").exists()
+
+
+# ----------------------------------------------------------------------
+# Internal: turn-aware truncation
+# ----------------------------------------------------------------------
+
+def _collect_kiro_turns(
+    raw_lines: list[str],
+    turns_needed: int,
+) -> tuple[list[str], int]:
+    """
+    Walk Kiro JSONL line-strings and collect all lines belonging to the
+    first `turns_needed` COMPLETE user turns.
+
+    A "complete turn" is a `kind: Prompt` entry followed by at least one
+    `kind: AssistantMessage` entry (with any number of `ToolResults` or
+    intermediate `AssistantMessage` entries between the Prompt and the
+    final AssistantMessage). Turns that end with a dangling Prompt — no
+    AssistantMessage yet — are EXCLUDED. Including them produces a
+    session file that Kiro rejects with "invalid conversation history
+    received" on resume.
+
+    Mirrors `session_files._collect_turns` for the Claude driver, adapted
+    to Kiro's schema (`kind: Prompt | AssistantMessage | ToolResults`
+    instead of Claude's `type: user | assistant | attachment`).
+
+    Returns (collected_lines, complete_turns_count). `collected_lines`
+    contains the original raw line strings (unmodified), in order. The
+    caller is responsible for writing them to a new session file.
+
+    Edge cases handled:
+      - Empty input: returns ([], 0).
+      - All turns incomplete (every Prompt has no AssistantMessage):
+        returns ([], 0). Caller bails out.
+      - File ends with dangling Prompt: that final turn is dropped.
+      - Bad JSON line: skipped, doesn't crash.
+      - Unknown `kind` values inside a turn: included (forward-compat
+        with future Kiro schema additions — better to over-include than
+        drop content the agent expects).
+      - Multiple consecutive AssistantMessage entries within one turn
+        (e.g. tool-use → tool-result → final response): all included.
+    """
+    result: list[str] = []
+    pending: list[str] = []
+    pending_has_assistant = False
+    turns_collected = 0
+
+    for raw in raw_lines:
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        try:
+            entry = json.loads(stripped)
+        except json.JSONDecodeError:
+            continue
+        kind = entry.get("kind", "")
+
+        if kind == "Prompt":
+            # New turn boundary. Flush previous turn if it was complete;
+            # otherwise drop the previous (incomplete) turn entirely —
+            # leaving a dangling Prompt would make Kiro panic on resume.
+            if pending and pending_has_assistant:
+                result.extend(pending)
+                turns_collected += 1
+                if turns_collected >= turns_needed:
+                    return result, turns_collected
+            pending = [raw]
+            pending_has_assistant = False
+        else:
+            # Inside an in-progress turn. Include if we've started one;
+            # otherwise drop (entries before the first Prompt are header/
+            # noise we don't want to carry forward).
+            if pending:
+                pending.append(raw)
+                if kind == "AssistantMessage":
+                    pending_has_assistant = True
+
+    # End of file: flush the final turn if it was complete.
+    if pending and pending_has_assistant:
+        result.extend(pending)
+        turns_collected += 1
+
+    return result, turns_collected

{expluro-0.3.0 → expluro-0.3.1}/topo/main.py

@@ -29,8 +29,13 @@ _LOG_FILE = _LOG_DIR / "cli.log"
 
 def _setup_logging() -> Path | None:
     """Configure root logger. Returns the active log file path, or None on fallback."""
-    level_name = os.environ.get("TOPO_LOG_LEVEL", "WARNING").upper()
-    level = getattr(logging, level_name, logging.WARNING)
+    # Default INFO so the rotating file captures session lifecycle events
+    # (auto-branch fires, connect/disconnect, permission decisions, etc.)
+    # without users having to remember TOPO_LOG_LEVEL. WARNING was too
+    # quiet — bug reports came in with empty logs because everything
+    # interesting logs at INFO/DEBUG.
+    level_name = os.environ.get("TOPO_LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
     fmt = logging.Formatter(
         "%(asctime)s %(levelname)s %(name)s: %(message)s"
     )

{expluro-0.3.0 → expluro-0.3.1}/topo/session.py

@@ -55,7 +55,12 @@ DRIVERS = {
 FRONTEND_URL = os.getenv("TOPO_FRONTEND_URL", "https://expluro.com")
 WS_BASE = os.getenv("TOPO_BASE_URL", "https://api.expluro.com").replace("https://", "wss://").replace("http://", "ws://")
 
-AUTO_BRANCH_THRESHOLD = 0.7  # confidence >= this triggers an automatic branch
+AUTO_BRANCH_THRESHOLD = 0.85  # confidence >= this triggers an automatic branch.
+# Aligned with the BRANCH_DETECTION_INSTRUCTION's own confidence bands —
+# 0.85+ is the "clear fork: option chosen, or subject/direction changed
+# substantially" range. Lower confidences (0.50–0.85) cover meaningful but
+# ambiguous shifts, where false-firing destroys the user's active turn and
+# is worse than missing one (the user can always /branch manually).
 
 
 def start_session(driver_name: str = "claude", cwd: str | None = None, no_browser: bool = False) -> None:
@@ -668,8 +673,25 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                 cc_session_id: str | None = None
                 renderer = TerminalRenderer()
                 renderer.start_turn()
+                # Buffer for events that arrive before the branch decision is
+                # resolved. We render them to the terminal immediately (UX
+                # stays live), but defer the durable record until we know
+                # which node owns this turn — parent if no branch fires,
+                # child if it does. Without this, an event that lands before
+                # branch_signal (e.g. a `thinking` block from extended
+                # thinking, which Claude emits as its own AssistantMessage
+                # ahead of the streamed text containing the BRANCH tag)
+                # would force the safety-net flush of pending_user_msg onto
+                # the parent, leaving the pivot message on the wrong node.
+                pre_branch_buffer: list = []
+                branch_decided = False
                 try:
                     async for event in driver.receive():
+                        # Capture cc_session_id from any event regardless of
+                        # buffering, so a turn that defers all events still
+                        # records the session id for /resume.
+                        if not cc_session_id and event.data.get("session_id"):
+                            cc_session_id = event.data["session_id"]
                         if event.type == "branch_signal":
                             confidence = event.data.get("confidence", 0.0)
                             logger.info("Branch signal received (confidence=%.2f, threshold=%.2f, fires=%s)", confidence, AUTO_BRANCH_THRESHOLD, auto_branch_enabled['value'] and confidence >= AUTO_BRANCH_THRESHOLD)
@@ -741,29 +763,50 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                                 except Exception:
                                     logger.warning("Failed to persist deferred user message")
                                 pending_user_msg = None
+                            # Replay any events that arrived before branch_signal
+                            # (e.g. leading `thinking` block) onto whichever node
+                            # we just resolved to. They were rendered live; only
+                            # the durable record was deferred.
+                            for buffered_evt in pre_branch_buffer:
+                                try:
+                                    await capture.record_driver_event(buffered_evt)
+                                except Exception:
+                                    logger.warning("Failed to persist buffered pre-branch event")
+                            pre_branch_buffer = []
+                            branch_decided = True
                             continue  # branch_signal is never persisted or rendered
-                        # Safety net: if the model omitted the BRANCH flag, no
-                        # branch_signal arrived and pending_user_msg was never flushed
-                        # there. Flush it now on the current node before any other
-                        # event lands, so it anchors as the first event on the turn.
-                        if pending_user_msg is not None:
-                            try:
-                                await capture.record_user_message(pending_user_msg)
-                                _label = pending_user_msg[:80]
-                                current_node_label['value'] = _label
-                                node_label_cache[capture.node_id] = _label
-                            except Exception:
-                                logger.warning("Failed to persist deferred user message (no branch_signal path)")
-                            pending_user_msg = None
                         # Render to terminal first (local, instant) — the terminal is the
                         # primary interaction surface and must not be paced by backend latency.
                         # Persistence + browser broadcast runs second.
                         renderer.render(event)
+                        # Defer durable persistence until the branch decision is
+                        # resolved. text/text_complete/result without a prior
+                        # branch_signal proves the model omitted the BRANCH tag —
+                        # commit to the current node now and replay buffer.
+                        if not branch_decided and pending_user_msg is not None:
+                            if event.type in ("text", "text_complete", "result"):
+                                try:
+                                    await capture.record_user_message(pending_user_msg)
+                                    _label = pending_user_msg[:80]
+                                    current_node_label['value'] = _label
+                                    node_label_cache[capture.node_id] = _label
+                                except Exception:
+                                    logger.warning("Failed to persist deferred user message (no branch_signal path)")
+                                pending_user_msg = None
+                                for buffered_evt in pre_branch_buffer:
+                                    try:
+                                        await capture.record_driver_event(buffered_evt)
+                                    except Exception:
+                                        logger.warning("Failed to persist buffered pre-branch event")
+                                pre_branch_buffer = []
+                                branch_decided = True
+                                # Fall through to record current event on this node.
+                            else:
+                                # thinking, tool_use, tool_result, rate_limit, error, etc.
+                                # Buffer for replay once the branch decision is made.
+                                pre_branch_buffer.append(event)
+                                continue
                         await capture.record_driver_event(event)
-                        # Capture the Claude Code session ID from the first event that has it.
-                        # Every message type carries session_id in event.data.
-                        if not cc_session_id and event.data.get("session_id"):
-                            cc_session_id = event.data["session_id"]
                 except KeyboardInterrupt:
                     renderer.stop_spinner_if_active()
                     console.print("\n[yellow]Interrupted.[/yellow]")
@@ -773,12 +816,12 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                     console.print(f"[red]Error: {exc}[/red]")
                 finally:
                     is_streaming['value'] = False
-                    # Last-chance safety net: if the stream errored before any
-                    # event arrived (so neither the branch_signal flush nor the
-                    # pre-event flush ran), persist the user message now on
-                    # whichever node capture is currently on. Avoids losing the
-                    # message from durable history if the response failed
-                    # catastrophically before any tokens streamed.
+                    # Last-chance safety net: if the stream errored before the
+                    # branch decision was resolved (so neither the branch_signal
+                    # path nor the text/result fallback ran), persist the user
+                    # message and any buffered pre-branch events now on whichever
+                    # node capture is currently on. Avoids losing the message
+                    # from durable history if the response failed catastrophically.
                     if pending_user_msg is not None:
                         try:
                             await capture.record_user_message(pending_user_msg)
@@ -788,6 +831,13 @@ async def _run(driver_name: str, cwd: str, no_browser: bool = False) -> None:
                         except Exception:
                             logger.warning("Failed to persist user message in finally")
                         pending_user_msg = None
+                    if pre_branch_buffer:
+                        for buffered_evt in pre_branch_buffer:
+                            try:
+                                await capture.record_driver_event(buffered_evt)
+                            except Exception:
+                                logger.warning("Failed to persist buffered pre-branch event in finally")
+                        pre_branch_buffer = []
                     # Persist the Claude Code session ID so checkout can --resume this node later.
                     if cc_session_id:
                         current_cc_session_id['value'] = cc_session_id

expluro-0.3.0/topo/drivers/kiro_session_files.py

@@ -1,167 +0,0 @@
-"""
-Kiro session file forking.
-
-Kiro's ACP server does not implement `session/fork_session` (advertised
-fork capability is null; calling the method returns "Method not found").
-But it does support `session/load_session`, and it accepts session files
-written manually to ~/.kiro/sessions/cli/<uuid>.jsonl + .json.
-
-So we fork the same way the Claude driver does: copy the parent's session
-files to a new UUID, truncate to the branch point, ask Kiro to load_session
-the new UUID. The agent treats it as a real session.
-
-File layout (verified empirically):
-- <uuid>.jsonl: one event per line. Two kinds: Prompt and AssistantMessage.
-  Each carries message_id, content blocks, optional meta.timestamp.
-- <uuid>.json: metadata. Contains session_id, cwd, title, session_state with
-  per-turn telemetry (user_turn_metadatas). Kiro accepts copied/truncated
-  metadata even though some fields like input_token_count, metering_usage
-  reflect the parent's values.
-- <uuid>.lock: process lock. Created by the agent process on open. We do
-  NOT plant a lock file; Kiro creates one when it opens the session.
-"""
-from __future__ import annotations
-
-import json
-import logging
-import time
-import uuid
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-KIRO_SESSIONS_DIR = Path.home() / ".kiro" / "sessions" / "cli"
-
-
-def fork_kiro_session(
-    parent_session_id: str,
-    message_count: int,
-    cwd: str,
-) -> str | None:
-    """
-    Create a new Kiro session file by copying the parent's session files
-    and truncating to the first `message_count` JSONL events.
-
-    Returns the new session UUID, or None on failure.
-
-    Why we don't use ACP fork_session: Kiro returns "Method not found".
-    Why we generate the UUID ourselves: matches Claude's approach. Lets us
-    return the new id synchronously and write predictable filenames.
-    """
-    parent_jsonl = KIRO_SESSIONS_DIR / f"{parent_session_id}.jsonl"
-    parent_json = KIRO_SESSIONS_DIR / f"{parent_session_id}.json"
-
-    if not parent_jsonl.exists() or not parent_json.exists():
-        logger.warning(
-            "kiro_session_files: parent session files not found for %s in %s",
-            parent_session_id, KIRO_SESSIONS_DIR,
-        )
-        return None
-
-    # Defensive flush wait: Kiro's session writer is async, and the
-    # ACPDriver's close_session call should make it flush before we get
-    # here. But if for any reason the file is still short of expected
-    # size, wait briefly for it to settle. Without this, we'd fork a
-    # half-written file and Kiro would later panic on a dangling user
-    # prompt. Caller passes message_count = expected line count.
-    deadline = time.monotonic() + 2.0
-    while time.monotonic() < deadline:
-        try:
-            current_lines = parent_jsonl.read_text().splitlines()
-        except OSError:
-            current_lines = []
-        if len(current_lines) >= message_count:
-            break
-        time.sleep(0.05)
-
-    try:
-        lines = parent_jsonl.read_text().splitlines()
-    except OSError as exc:
-        logger.warning("kiro_session_files: failed to read parent jsonl: %s", exc)
-        return None
-    if len(lines) < message_count:
-        logger.warning(
-            "kiro_session_files: parent file has %d lines but expected %d after flush wait; "
-            "forking what's there (the result may be missing the last assistant message)",
-            len(lines), message_count,
-        )
-
-    if message_count <= 0:
-        logger.warning(
-            "kiro_session_files: refusing to fork at message_count=%d (must be > 0)",
-            message_count,
-        )
-        return None
-
-    # Cap to actual content length. If caller asks for more messages than the
-    # parent has, we just take everything. Same behavior as Claude.
-    new_lines = lines[: min(message_count, len(lines))]
-    if not new_lines:
-        logger.warning("kiro_session_files: parent jsonl was empty for %s", parent_session_id)
-        return None
-
-    # Count complete turns in the truncated JSONL. A complete turn ends with
-    # an AssistantMessage. user_turn_metadatas has one entry per complete turn.
-    # Robust to tool-call interleavings: we count AssistantMessage events
-    # rather than divide by two.
-    turn_count = sum(1 for line in new_lines if '"kind":"AssistantMessage"' in line)
-
-    try:
-        metadata = json.loads(parent_json.read_text())
-    except (OSError, json.JSONDecodeError) as exc:
-        logger.warning("kiro_session_files: failed to read parent json metadata: %s", exc)
-        return None
-
-    new_uuid = str(uuid.uuid4())
-
-    # Truncate user_turn_metadatas to match the number of complete turns.
-    # Update session_id and conversation_id to the new UUID. Leave other
-    # metadata fields (cwd, title, permissions, model state) as-is. Kiro
-    # accepted this in our test runs.
-    metadata["session_id"] = new_uuid
-    conv_meta = (
-        metadata.setdefault("session_state", {})
-        .setdefault("conversation_metadata", {})
-    )
-    user_turn_metadatas = conv_meta.get("user_turn_metadatas", []) or []
-    conv_meta["user_turn_metadatas"] = user_turn_metadatas[:turn_count]
-    conv_meta["user_turn_start_request"] = None
-    conv_meta["last_request"] = None
-
-    rts_state = metadata.get("session_state", {}).get("rts_model_state")
-    if isinstance(rts_state, dict):
-        rts_state["conversation_id"] = new_uuid
-
-    new_jsonl_path = KIRO_SESSIONS_DIR / f"{new_uuid}.jsonl"
-    new_json_path = KIRO_SESSIONS_DIR / f"{new_uuid}.json"
-
-    try:
-        # Write JSONL and metadata atomically: write to .tmp then rename.
-        # Avoids leaving a half-written file if we crash mid-write.
-        tmp_jsonl = new_jsonl_path.with_suffix(".jsonl.tmp")
-        tmp_json = new_json_path.with_suffix(".json.tmp")
-        tmp_jsonl.write_text("\n".join(new_lines) + "\n")
-        tmp_json.write_text(json.dumps(metadata, indent=2))
-        tmp_jsonl.rename(new_jsonl_path)
-        tmp_json.rename(new_json_path)
-    except OSError as exc:
-        logger.warning("kiro_session_files: failed to write forked session files: %s", exc)
-        # Best-effort cleanup.
-        for p in (new_jsonl_path, new_json_path):
-            try:
-                p.unlink(missing_ok=True)
-            except OSError:
-                pass
-        return None
-
-    logger.info(
-        "kiro_session_files: forked %s -> %s (lines=%d, turns=%d)",
-        parent_session_id, new_uuid, len(new_lines), turn_count,
-    )
-    return new_uuid
-
-
-def kiro_session_exists(session_id: str) -> bool:
-    """Check if a Kiro session file exists locally."""
-    return (KIRO_SESSIONS_DIR / f"{session_id}.jsonl").exists()