induscode 0.1.0__py3-none-any.whl

induscode/runtime_bridge/sink.py

@@ -0,0 +1,351 @@
+"""The single :class:`~induscode.runtime_bridge.contract.BridgeEventSink`
+implementation (port of TS ``src/runtime-bridge/sink.ts``) — the one place
+the imperative push-stream idiom every bridge shares is written down.
+
+Each external runtime emits its own wire dialect; a bridge's parser maps
+that dialect onto the provider-neutral
+:data:`~induscode.runtime_bridge.contract.NormalizedEvent` union and drives a
+sink. This module owns everything else:
+
+- the accumulating ``AssistantMessage`` every framework event carries as its
+  ``partial``;
+- the content-block index bookkeeping (a block's index is its position in
+  the content sequence, opened lazily on first emission of its kind);
+- the lazily-started lifecycle (``start`` is implicit on first emission, and
+  idempotent) and the terminal ``finish_success`` / ``finish_error`` settle;
+- the ``NormalizedEvent -> framework event`` mapping, in :meth:`BridgeSink.emit`,
+  so the per-bridge code stays a pure parser.
+
+Frozen-message adaptation (the port's one structural change — PLAN M2 /
+analysis 01 risk-1)
+--------------------------------------------------------------------------
+The TS sink mutates one shared ``partial`` ``AssistantMessage`` in place
+(``block.text += delta``) and hands the *same object* to every push call.
+The Python framework's ``AssistantMessage`` is a **frozen** dataclass whose
+``content`` is a **tuple** of frozen parts — in-place mutation is
+impossible. So this port keeps a **mutable builder** (a plain list of
+``["text", buffer]`` / ``["thinking", buffer]`` / ``["toolCall", ToolCall]``
+parts whose string buffers accumulate across deltas) and **materializes a
+fresh frozen ``AssistantMessage`` snapshot per push** — the exact idiom the
+framework's own facade stream uses (``indusagi.ai.stream._Accumulator``:
+"Snapshots materialize a fresh frozen ``AssistantMessage`` per event …
+consumers only ever read it at delivery time, which snapshots reproduce
+exactly"). A block's index is its position in the builder list, so the
+content-index bookkeeping is unchanged from TS.
+
+The framework push surface this writes through — ``push_start /
+push_text_start / push_text_delta / push_text_end / push_thinking_start /
+push_thinking_delta / push_thinking_end / push_tool_call_start /
+push_tool_call_delta / push_tool_call_end / push_done / push_error`` on
+``AssistantMessageEventStream`` (verified against
+``indusagi/ai/events.py``) — is consumed verbatim from the framework via
+:func:`indusagi.ai.create_assistant_message_event_stream`; this module never
+re-derives event shapes.
+
+Streaming contract honored (matching the framework's own adapters): a text
+or thinking block opens with a ``*_start`` once the block has been appended
+to the builder, streams ``*_delta``\\ s while the running content
+accumulates, and closes with a ``*_end`` carrying the final content. A tool
+call is a single self-contained block (``start -> delta(args) -> end``). The
+terminal ``done`` / ``error`` event carries the fully-accumulated message.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Final, Literal
+
+# The push stream is constructed through the framework's factory value; the
+# message/content types come from the same barrel.
+from indusagi.ai import (
+    AssistantMessage,
+    AssistantMessageEventStream,
+    TextContent,
+    ThinkingContent,
+    ToolCall,
+    create_assistant_message_event_stream,
+    create_zero_usage,
+)
+
+from induscode.runtime_bridge.contract import (
+    NORMALIZED_EVENT_KINDS,
+    BridgeEventSink,
+    BridgeFailure,
+    FinishReason,
+    NormalizedEvent,
+    NormalizedEventKind,
+)
+
+__all__ = [
+    "BridgeMessageSeed",
+    "create_bridge_sink",
+]
+
+
+# ---------------------------------------------------------------------------
+# Message identity seed
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeMessageSeed:
+    """The model-identity fields stamped onto every ``partial``
+    ``AssistantMessage`` the sink emits (TS ``BridgeMessageSeed``). A bridge
+    supplies these from the bound model so a runtime-backed turn reports the
+    same ``api`` / ``provider`` / ``model`` triple a network turn would —
+    keeping the accumulated message uniform regardless of which path
+    produced it."""
+
+    #: The bound model's ``api`` dialect identifier.
+    api: str
+    #: The bound model's provider slug.
+    provider: str
+    #: The bound model's id (the value stamped into ``AssistantMessage.model``).
+    model: str
+
+
+# ---------------------------------------------------------------------------
+# Internal: open-block tracking
+# ---------------------------------------------------------------------------
+
+# The currently-open streamable content block: ("text" | "thinking", index).
+# Text and thinking blocks stay open across their deltas so a later delta of
+# a *different* kind first closes the prior block (emitting its `*_end`)
+# before opening its own — mirroring the framework's one-block-at-a-time
+# content stream. A tool call never lingers as the open block (it opens and
+# closes atomically), so it is not tracked here.
+_OpenBlock = tuple[Literal["text", "thinking"], int]
+
+
+def _now_ms() -> int:
+    """Milliseconds since the Unix epoch (TS ``Date.now()``)."""
+    return int(time.time() * 1000)
+
+
+# ---------------------------------------------------------------------------
+# Sink implementation
+# ---------------------------------------------------------------------------
+
+
+class BridgeSink:
+    """The concrete :class:`BridgeEventSink`. Private to the module; bridges
+    construct one through :func:`create_bridge_sink`."""
+
+    __slots__ = (
+        "_error_message",
+        "_open",
+        "_parts",
+        "_seed",
+        "_settled",
+        "_started",
+        "_stop_reason",
+        "_stream",
+        "_timestamp",
+    )
+
+    def __init__(self, seed: BridgeMessageSeed) -> None:
+        self._stream: AssistantMessageEventStream = create_assistant_message_event_stream()
+        self._seed = seed
+        # The MUTABLE builder behind the frozen snapshots. Each part:
+        #   ["text", buffer] | ["thinking", buffer] | ["toolCall", ToolCall]
+        # A block's index is its position in this list (== its contentIndex).
+        self._parts: list[list[Any]] = []
+        #: The currently-open streamable block, if any.
+        self._open: _OpenBlock | None = None
+        #: Whether :meth:`start` has pushed the framework ``start`` event.
+        self._started = False
+        #: Whether a terminal ``done`` / ``error`` has been pushed.
+        self._settled = False
+        # Snapshot fields the TS sink mutated on the shared partial.
+        self._stop_reason: str = "stop"
+        self._error_message: str | None = None
+        # One message identity per exchange, like the TS partial's timestamp.
+        self._timestamp = _now_ms()
+
+    # ---- snapshot construction ----
+
+    def _snapshot(self) -> AssistantMessage:
+        """Materialize a fresh frozen ``AssistantMessage`` from the mutable
+        builder — the per-push ``partial``. External runtimes do not report
+        framework token accounting on the streamed event surface (a CLI owns
+        its own metering), so the message carries a zeroed usage rather than
+        fabricated numbers."""
+        content: list[TextContent | ThinkingContent | ToolCall] = []
+        for part in self._parts:
+            if part[0] == "text":
+                content.append(TextContent(text=part[1]))
+            elif part[0] == "thinking":
+                content.append(ThinkingContent(thinking=part[1]))
+            else:  # ["toolCall", ToolCall] — already frozen, reused as-is.
+                content.append(part[1])
+        return AssistantMessage(
+            content=tuple(content),
+            api=self._seed.api,
+            provider=self._seed.provider,
+            model=self._seed.model,
+            usage=create_zero_usage(),
+            stopReason=self._stop_reason,  # type: ignore[arg-type]
+            errorMessage=self._error_message,
+            timestamp=self._timestamp,
+        )
+
+    # ---- lifecycle ----
+
+    @property
+    def stream(self) -> AssistantMessageEventStream:
+        """The framework push stream handed back to the broker's caller."""
+        return self._stream
+
+    def start(self) -> None:
+        if self._started or self._settled:
+            return
+        self._started = True
+        self._stream.push_start(self._snapshot())
+
+    # ---- text ----
+
+    def text(self, delta: str) -> None:
+        if self._settled:
+            return
+        self.start()
+        index = self._ensure_open("text")
+        self._parts[index][1] += delta
+        self._stream.push_text_delta(index, delta, self._snapshot())
+
+    # ---- thinking ----
+
+    def thinking(self, delta: str) -> None:
+        if self._settled:
+            return
+        self.start()
+        index = self._ensure_open("thinking")
+        self._parts[index][1] += delta
+        self._stream.push_thinking_delta(index, delta, self._snapshot())
+
+    # ---- tool call ----
+
+    def tool_call(self, call: ToolCall) -> None:
+        if self._settled:
+            return
+        self.start()
+        # A tool call is a self-contained block: close any open text/thinking
+        # block first so content ordering stays linear, then open/stream/close
+        # atomically.
+        self._close_open()
+        index = len(self._parts)
+        block = ToolCall(
+            id=call.id,
+            name=call.name,
+            arguments=call.arguments,
+            thoughtSignature=call.thoughtSignature,
+        )
+        self._parts.append(["toolCall", block])
+        self._stream.push_tool_call_start(index, self._snapshot())
+        self._stream.push_tool_call_delta(
+            index,
+            json.dumps(dict(block.arguments), separators=(",", ":")),
+            self._snapshot(),
+        )
+        self._stream.push_tool_call_end(index, block, self._snapshot())
+
+    # ---- normalized-event dispatch ----
+
+    def emit(self, event: NormalizedEvent) -> None:
+        _EMIT_DISPATCH[event.kind](self, event)
+
+    # ---- terminal: success ----
+
+    def finish_success(self, reason: FinishReason = "stop") -> None:
+        if self._settled:
+            return
+        self.start()
+        self._close_open()
+        self._settled = True
+        self._stop_reason = reason
+        self._stream.push_done(reason, self._snapshot())
+
+    # ---- terminal: error ----
+
+    def finish_error(self, error: BridgeFailure) -> None:
+        if self._settled:
+            return
+        self.start()
+        self._close_open()
+        self._settled = True
+        reason: Literal["aborted", "error"] = "aborted" if error.aborted else "error"
+        self._stop_reason = reason
+        self._error_message = error.message
+        self._stream.push_error(reason, self._snapshot())
+
+    # ------------------------------------------------------------------
+    # Internal block management
+    # ------------------------------------------------------------------
+
+    def _ensure_open(self, kind: Literal["text", "thinking"]) -> int:
+        """Ensure the open block is of ``kind``, returning its content index.
+        If a block of a different kind is open it is closed first; if none is
+        open (or the kind differs), a fresh block is appended and its
+        ``*_start`` is pushed."""
+        if self._open is not None:
+            if self._open[0] == kind:
+                return self._open[1]
+            self._close_open()
+        index = len(self._parts)
+        if kind == "text":
+            self._parts.append(["text", ""])
+            self._stream.push_text_start(index, self._snapshot())
+        else:
+            self._parts.append(["thinking", ""])
+            self._stream.push_thinking_start(index, self._snapshot())
+        self._open = (kind, index)
+        return index
+
+    def _close_open(self) -> None:
+        """Close the currently-open text/thinking block, pushing its
+        ``*_end`` with the accumulated content. No-op when nothing is open."""
+        open_ = self._open
+        if open_ is None:
+            return
+        self._open = None
+        kind, index = open_
+        if kind == "text":
+            self._stream.push_text_end(index, self._parts[index][1], self._snapshot())
+        else:
+            self._stream.push_thinking_end(index, self._parts[index][1], self._snapshot())
+
+
+# The NormalizedEvent -> sink-method dispatch (the TS exhaustive `switch`).
+# Keys are pinned against NORMALIZED_EVENT_KINDS by a key-coverage test
+# (PLAN rule 1: exhaustiveness via tests, not types). A `resume` event is
+# informational: the bridge persists the resume token out-of-band; the event
+# stream carries no resume signal, so it is a no-op here.
+_EMIT_DISPATCH: Final[dict[NormalizedEventKind, Callable[[BridgeSink, Any], None]]] = {
+    "text": lambda sink, event: sink.text(event.delta),
+    "thinking": lambda sink, event: sink.thinking(event.delta),
+    "tool_call": lambda sink, event: sink.tool_call(event.call),
+    "resume": lambda sink, event: None,
+    "finish": lambda sink, event: sink.finish_success(event.reason),
+    "failed": lambda sink, event: sink.finish_error(event.error),
+}
+
+assert set(_EMIT_DISPATCH) == set(NORMALIZED_EVENT_KINDS)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def create_bridge_sink(seed: BridgeMessageSeed) -> BridgeEventSink:
+    """Construct a :class:`BridgeEventSink` seeded with the bound model's
+    identity (TS ``createBridgeSink``). The single sanctioned way a bridge
+    obtains a sink: it creates one, drives it with normalized events (or the
+    convenience emitters), and returns :attr:`BridgeEventSink.stream`. The
+    imperative push idiom lives entirely inside the returned sink.
+
+    :param seed: the bound model's ``api`` / ``provider`` / ``model`` identity
+    """
+    return BridgeSink(seed)

induscode/sessions/__init__.py

@@ -0,0 +1,25 @@
+"""Sessions subsystem — public barrel (port of TS ``src/sessions/index.ts``).
+
+Exposes the :class:`SessionLibrary` (the catalog-and-navigation layer over
+the conductor's persisted transcripts) and its value contract — the
+:class:`SavedSession` catalog row, the :class:`BranchNode` navigator row, and
+the :class:`PriorTurn` fork candidate. Consumers import the session-library
+surface from ``induscode.sessions`` rather than reaching into the individual
+modules.
+
+(The per-cwd ``--<cwd slug>--`` scope-dir helper is **not** here — it is
+boot's, ported with ``boot/runners/session.py`` in the M4 launch/boot wave;
+the library takes the already-scoped directory.)
+"""
+
+from __future__ import annotations
+
+from induscode.sessions.contract import BranchNode, PriorTurn, SavedSession
+from induscode.sessions.library import SessionLibrary
+
+__all__ = [
+    "BranchNode",
+    "PriorTurn",
+    "SavedSession",
+    "SessionLibrary",
+]

induscode/sessions/contract.py

@@ -0,0 +1,119 @@
+"""Session Library contract — the value types the library surface speaks in
+(port of TS ``src/sessions/contract.ts``).
+
+The library sits on top of the conductor's persistent transcript store: it
+enumerates the session files a workspace has accumulated, opens one back into
+a live :class:`~induscode.conductor.transcript_store.TranscriptStore`, and
+projects the resulting node tree into the flat shapes a navigator and a
+forking picker consume.
+
+These records are the *catalog/navigation* projections — the minimum a
+chooser UI needs. They deliberately hold no framework message objects: text
+is already reduced to a short preview, and identity is carried by stable
+string ids so a caller can list, rename, delete, walk, and fork without
+rehydrating payloads.
+
+Field names keep the TS camelCase spelling (``lastModified``,
+``messageCount``, ``entryId``, ``isLeaf``, ``isCurrent``) per the port
+convention.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "BranchNode",
+    "PriorTurn",
+    "SavedSession",
+]
+
+
+# ---------------------------------------------------------------------------
+# Saved-session catalog record
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SavedSession:
+    """One persisted session as the library catalogs it — what a chooser
+    shows in a list before anything is opened.
+
+    ``id`` is the bare session identifier (the filename stem the conductor's
+    filesystem backend writes to); ``path`` is its absolute on-disk location.
+    The remaining fields are best-effort enrichments filled when the library
+    is asked to peek inside a file: a derived ``name``, file
+    ``lastModified``/``size``, the ``messageCount`` of conversational nodes,
+    and a short ``preview`` of the opening user turn. Any of them may be
+    ``None`` when only a shallow listing was taken.
+    """
+
+    #: Bare session identifier — the filename stem, no extension or directory.
+    id: str
+    #: Absolute on-disk path the session persists to.
+    path: str
+    #: Human-facing label for the session, when one could be derived.
+    name: str | None = None
+    #: Last-modified wall-clock time of the file, in epoch milliseconds.
+    lastModified: float | None = None
+    #: Byte size of the session file on disk.
+    size: int | None = None
+    #: Count of conversational (user/assistant/tool) nodes in the transcript.
+    messageCount: int | None = None
+    #: Short single-line excerpt of the opening turn, for at-a-glance
+    #: recognition.
+    preview: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Transcript-tree navigation node
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class BranchNode:
+    """One row in the flattened view of a loaded transcript tree.
+
+    The conductor stores a branchable tree of nodes; a navigator wants a
+    single ordered list it can render and select against. Each
+    :class:`BranchNode` names its ``id``, its ``parent`` link (so a caller
+    can still reconstruct the tree), a render-ready ``label``, the
+    indentation ``depth`` from the root, and two flags: ``isLeaf`` for a tip
+    of the tree and ``isCurrent`` for the node the active head points at.
+    """
+
+    #: Stable id of the underlying transcript node.
+    id: str
+    #: Parent node id, or ``None`` for a transcript root.
+    parent: str | None
+    #: Render-ready, depth-indented one-line label.
+    label: str
+    #: Distance from the root (a root is depth 0).
+    depth: int
+    #: True when this node has no children — a tip of the tree.
+    isLeaf: bool
+    #: True when the active head currently points at this node.
+    isCurrent: bool
+
+
+# ---------------------------------------------------------------------------
+# Prior-turn fork candidate
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PriorTurn:
+    """A past user turn offered as a fork point.
+
+    To re-ask or re-edit an earlier prompt, a caller picks one of these and
+    the conductor branches the transcript at ``entryId``. ``text`` is the
+    full prompt text; ``preview`` is the trimmed single-line form a picker
+    renders.
+    """
+
+    #: Id of the transcript node this user turn lives on (the fork target).
+    entryId: str
+    #: Full text of the user prompt.
+    text: str
+    #: Trimmed single-line excerpt of ``text``, for display.
+    preview: str