induscode 0.1.0__py3-none-any.whl

induscode/conductor/transcript_store.py

@@ -0,0 +1,449 @@
+"""TranscriptStore — the conductor's persistent, branchable transcript
+(port of TS ``src/conductor/transcript-store/store.ts``).
+
+The transcript is an append-only **tree** of
+:class:`~induscode.conductor.contract.TranscriptEntry` nodes: every node names
+its ``parent``, a single :class:`~induscode.conductor.contract.SessionHead`
+tracks the active ``leaf``, and the active conversation is the ``parent``-chain
+walked from that leaf back to a root.
+
+Design stance (an independent persistence model):
+
+- **Reducer-friendly.** The on-disk form is a flat NDJSON log; the in-memory
+  view is rebuilt by a pure :func:`replay` reducer over that log. State is a
+  value derived from the log, never mutated in place behind the scenes.
+- **Fresh envelope.** Lines carry the ``indus/transcript@1`` schema with our
+  own field names (``prev``, ``at``, ``kind``), delegated to
+  :mod:`induscode.conductor.serialize` — not any framework-internal
+  session-manager schema.
+- **Branch = move the head.** :meth:`TranscriptStore.branch_at` repoints the
+  leaf at an earlier node; the next :meth:`TranscriptStore.append` becomes
+  that node's child, forking a new path without rewriting history.
+- **``path_to`` is the read primitive.** It resolves the root→leaf branch
+  (the message list the agent replays); the conductor's ``resume`` calls it
+  to rehydrate.
+
+The store is storage-pluggable: a :class:`TranscriptBackend` abstracts where
+bytes live, so tests inject an in-memory backend and the conductor binds a
+filesystem one. Construction is synchronous and empty;
+:meth:`TranscriptStore.load` hydrates from a backend.
+
+Port note: the TS plain-object backends/clocks become frozen dataclasses of
+callables — the same "bag of functions" shape, test-injectable field by field.
+Disk I/O runs through :func:`asyncio.to_thread` so the async backend surface
+never blocks the loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ulid import ULID
+
+from induscode.conductor.contract import (
+    TRANSCRIPT_SCHEMA,
+    SessionHead,
+    TranscriptEntry,
+    TranscriptRole,
+)
+from induscode.conductor.serialize import (
+    encode_entry,
+    encode_head,
+    parse_session_text,
+    role_for_message,
+)
+
+__all__ = [
+    "TRANSCRIPT_SCHEMA",
+    "TranscriptBackend",
+    "TranscriptClock",
+    "TranscriptState",
+    "TranscriptStore",
+    "fs_backend",
+    "memory_backend",
+    "replay",
+]
+
+
+# ---------------------------------------------------------------------------
+# Storage backend
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class TranscriptBackend:
+    """Where a transcript's NDJSON log lives (TS ``TranscriptBackend``).
+
+    The store appends lines and, on branch, rewrites the whole file; a backend
+    supplies those three primitives plus a way to resolve a session id to its
+    location. The default :func:`fs_backend` maps a session id to
+    ``<dir>/<sessionId>.ndjson``; tests pass :func:`memory_backend` so no disk
+    is touched.
+    """
+
+    # Absolute location (path/key) a session id persists to.
+    locate: Callable[[str], str]
+    # Read the full NDJSON text for a session, or None if absent.
+    read: Callable[[str], Awaitable[str | None]]
+    # Append one already-encoded NDJSON line (no trailing newline) to a session.
+    append: Callable[[str, str], Awaitable[None]]
+    # Replace the whole NDJSON text for a session (used after a branch).
+    rewrite: Callable[[str, str], Awaitable[None]]
+
+
+def memory_backend() -> TranscriptBackend:
+    """An in-memory backend — the default when no persistence is wired."""
+    files: dict[str, list[str]] = {}
+
+    async def read(session_id: str) -> str | None:
+        lines = files.get(session_id)
+        return "\n".join(lines) if lines is not None else None
+
+    async def append(session_id: str, line: str) -> None:
+        files.setdefault(session_id, []).append(line)
+
+    async def rewrite(session_id: str, text: str) -> None:
+        files[session_id] = [] if len(text) == 0 else text.split("\n")
+
+    return TranscriptBackend(
+        locate=lambda session_id: f"mem:{session_id}",
+        read=read,
+        append=append,
+        rewrite=rewrite,
+    )
+
+
+def fs_backend(dir: str) -> TranscriptBackend:
+    """A filesystem backend rooted at ``dir``."""
+    root = Path(dir)
+
+    def _file_of(session_id: str) -> Path:
+        return root / f"{session_id}.ndjson"
+
+    async def read(session_id: str) -> str | None:
+        def _read() -> str | None:
+            try:
+                return _file_of(session_id).read_text(encoding="utf-8")
+            except OSError:
+                return None
+
+        return await asyncio.to_thread(_read)
+
+    async def append(session_id: str, line: str) -> None:
+        def _append() -> None:
+            root.mkdir(parents=True, exist_ok=True)
+            with open(_file_of(session_id), "a", encoding="utf-8") as fh:
+                fh.write(f"{line}\n")
+
+        await asyncio.to_thread(_append)
+
+    async def rewrite(session_id: str, text: str) -> None:
+        def _rewrite() -> None:
+            root.mkdir(parents=True, exist_ok=True)
+            body = "" if len(text) == 0 else f"{text}\n"
+            _file_of(session_id).write_text(body, encoding="utf-8")
+
+        await asyncio.to_thread(_rewrite)
+
+    return TranscriptBackend(
+        locate=lambda session_id: f"{dir}/{session_id}.ndjson",
+        read=read,
+        append=append,
+        rewrite=rewrite,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Reducer-friendly in-memory shape
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class TranscriptState:
+    """The immutable derived state of a transcript: the node table keyed by
+    id, plus the current head. A pure value produced by :func:`replay`; the
+    store holds one and swaps it wholesale on each mutation rather than
+    mutating fields (TS ``TranscriptState``)."""
+
+    # Every node, keyed by id, in insertion order. Treated as read-only.
+    nodes: Mapping[str, TranscriptEntry]
+    # The active head (session id + current leaf).
+    head: SessionHead
+
+
+@dataclass(frozen=True, slots=True)
+class TranscriptClock:
+    """A clock + id seam so tests get deterministic ids/timestamps
+    (TS ``TranscriptClock``)."""
+
+    # Mint a fresh, sortable node id.
+    id: Callable[[], str]
+    # The current instant as an ISO-8601 string.
+    now: Callable[[], str]
+
+
+def _iso_now() -> str:
+    """``new Date().toISOString()`` — millisecond precision, ``Z`` suffix."""
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+#: The live clock — ULIDs and wall-clock ISO timestamps.
+_LIVE_CLOCK = TranscriptClock(id=lambda: str(ULID()), now=_iso_now)
+
+
+def replay(
+    session_id: str,
+    entries: list[TranscriptEntry] | tuple[TranscriptEntry, ...],
+    leaf: str | None,
+) -> TranscriptState:
+    """Rebuild a :class:`TranscriptState` from an ordered entry list and a leaf.
+
+    Pure and total: the same inputs always yield the same state. The reducer
+    just indexes the entries by id (later ids overwrite earlier — append-only
+    logs never collide, but a rewrite stays idempotent) and pins the head.
+    """
+    nodes: dict[str, TranscriptEntry] = {}
+    for entry in entries:
+        nodes[entry.id] = entry
+    return TranscriptState(nodes=nodes, head=SessionHead(sessionId=session_id, leaf=leaf))
+
+
+# ---------------------------------------------------------------------------
+# TranscriptStore
+# ---------------------------------------------------------------------------
+
+
+class TranscriptStore:
+    """An append-only, branchable transcript bound to one session id.
+
+    Construct (empty), then either :meth:`append` fresh nodes or :meth:`load`
+    a persisted session. Every mutation appends to the backend and swaps the
+    derived :class:`TranscriptState`. Reads (:meth:`path_to`,
+    :meth:`messages`, :attr:`head`) are O(branch depth) walks over the
+    in-memory node table.
+    """
+
+    __slots__ = ("_state", "_backend", "_clock")
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        backend: TranscriptBackend | None = None,
+        clock: TranscriptClock | None = None,
+    ) -> None:
+        self._backend = backend if backend is not None else memory_backend()
+        self._clock = clock if clock is not None else _LIVE_CLOCK
+        self._state = replay(session_id, [], None)
+
+    @property
+    def session_id(self) -> str:
+        """The session id this store is bound to."""
+        return self._state.head.sessionId
+
+    @property
+    def head(self) -> SessionHead:
+        """The current head (session id + active leaf)."""
+        return self._state.head
+
+    @property
+    def size(self) -> int:
+        """Number of nodes currently in the transcript."""
+        return len(self._state.nodes)
+
+    def locate(self, session_id: str | None = None) -> str:
+        """Backend location this session persists to (for diagnostics/UI)."""
+        return self._backend.locate(session_id if session_id is not None else self.session_id)
+
+    def get(self, id: str) -> TranscriptEntry | None:
+        """Look up a single node by id."""
+        return self._state.nodes.get(id)
+
+    async def append(
+        self,
+        content: Any,
+        role: TranscriptRole | None = None,
+        meta: Mapping[str, Any] | None = None,
+    ) -> TranscriptEntry:
+        """Append a framework ``AgentMessage`` as a child of the current leaf
+        and advance the head onto it. The node role is derived from the
+        message (or overridden via ``role``). Persists the new line, then
+        returns the new node.
+
+        This is the conductor's per-message write: one call per produced
+        message in a settled turn.
+        """
+        entry = TranscriptEntry(
+            id=self._clock.id(),
+            parent=self._state.head.leaf,
+            role=role if role is not None else role_for_message(content),
+            content=content,
+            createdAt=self._clock.now(),
+            meta=dict(meta) if meta is not None else None,
+        )
+        await self._backend.append(self.session_id, encode_entry(entry))
+        self._commit(entry)
+        return entry
+
+    async def branch_at(self, id: str) -> None:
+        """Repoint the head at an earlier node, forking a branch. The next
+        :meth:`append` becomes a child of ``id``; existing nodes are
+        untouched. Rewrites the head line.
+
+        Raises ``ValueError`` when ``id`` is not a known node.
+        """
+        if id not in self._state.nodes:
+            raise ValueError(f'TranscriptStore.branch_at: unknown node "{id}"')
+        self._state = TranscriptState(
+            nodes=self._state.nodes,
+            head=SessionHead(sessionId=self.session_id, leaf=id),
+        )
+        await self._flush()
+
+    async def reset(self) -> None:
+        """Reset the head to before any node; the next :meth:`append` starts a
+        new root. Used when re-editing the very first turn."""
+        self._state = TranscriptState(
+            nodes=self._state.nodes,
+            head=SessionHead(sessionId=self.session_id, leaf=None),
+        )
+        await self._flush()
+
+    def start_new_session(self, session_id: str) -> None:
+        """Abandon the current conversation and begin a fresh, empty session
+        under a new id. All nodes are dropped and the leaf is reset to
+        ``None``, so :meth:`messages` is empty and the next :meth:`append`
+        starts a new root; subsequent writes persist to the new session's
+        backing file (the old one is left intact on disk). This is the
+        ``/clear`` (new-session) primitive — distinct from :meth:`reset`,
+        which keeps the nodes and id and only rewinds the head."""
+        self._state = replay(session_id, [], None)
+
+    def path_to(self, from_id: str | None = None) -> list[TranscriptEntry]:
+        """Resolve the active branch: the root→leaf node list reached by
+        walking ``parent`` links up from ``leaf`` (or from ``from_id`` when
+        given), reversed to chronological order.
+
+        This is the conductor's read primitive — ``resume`` rehydrates the
+        agent from ``path_to()``, and the turn loop projects it to messages
+        via :meth:`messages`. Returns ``[]`` for an empty transcript or a
+        dangling leaf.
+        """
+        start_id = from_id if from_id is not None else self._state.head.leaf
+        chain: list[TranscriptEntry] = []
+        cursor: str | None = start_id
+        seen: set[str] = set()
+        while cursor is not None:
+            if cursor in seen:
+                break  # defensive: never loop on a corrupt parent link
+            seen.add(cursor)
+            node = self._state.nodes.get(cursor)
+            if node is None:
+                break
+            chain.append(node)
+            cursor = node.parent
+        chain.reverse()
+        return chain
+
+    def messages(self, from_id: str | None = None) -> list[Any]:
+        """The active branch projected to the framework ``AgentMessage`` list."""
+        return [entry.content for entry in self.path_to(from_id)]
+
+    async def load(self, session_id: str | None = None) -> bool:
+        """Hydrate this store from a persisted session, replacing its current
+        state.
+
+        Reads the backend, parses it with
+        :func:`~induscode.conductor.serialize.parse_session_text`, and
+        rebuilds state via the :func:`replay` reducer. If the file carried no
+        head line, the head is pinned to the deepest leaf reachable from the
+        entries. Returns ``True`` when a session was found and loaded,
+        ``False`` when the backend had nothing.
+        """
+        sid = session_id if session_id is not None else self.session_id
+        text = await self._backend.read(sid)
+        if text is None:
+            return False
+        parsed = parse_session_text(sid, text)
+        leaf = parsed.head.leaf if parsed.head is not None else _deepest_leaf(parsed.entries)
+        self._state = replay(sid, parsed.entries, leaf)
+        return True
+
+    @classmethod
+    async def open(
+        cls,
+        session_id: str,
+        *,
+        backend: TranscriptBackend | None = None,
+        clock: TranscriptClock | None = None,
+    ) -> "TranscriptStore | None":
+        """Open a persisted session by id, returning a hydrated store (or
+        ``None`` if the backend has no such session). The static counterpart
+        to :meth:`load`."""
+        store = cls(session_id, backend=backend, clock=clock)
+        found = await store.load(session_id)
+        return store if found else None
+
+    def state(self) -> TranscriptState:
+        """A point-in-time copy of the derived state (for inspection/testing)."""
+        return self._state
+
+    # -- internals ----------------------------------------------------------
+
+    def _commit(self, entry: TranscriptEntry) -> None:
+        """Fold a freshly appended node into state and advance the leaf onto it."""
+        nodes = dict(self._state.nodes)
+        nodes[entry.id] = entry
+        self._state = TranscriptState(
+            nodes=nodes,
+            head=SessionHead(sessionId=self.session_id, leaf=entry.id),
+        )
+
+    async def _flush(self) -> None:
+        """Rewrite the whole backend file (head line first, then every node line)."""
+        lines = [encode_head(self._state.head)]
+        for entry in self._state.nodes.values():
+            lines.append(encode_entry(entry))
+        await self._backend.rewrite(self.session_id, "\n".join(lines))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _deepest_leaf(entries: list[TranscriptEntry]) -> str | None:
+    """Pick the deepest leaf when a loaded file lacked an explicit head line:
+    the node with the longest ``parent`` chain (ties broken by latest id).
+    Best-effort recovery for hand-edited or legacy-imported transcripts."""
+    if len(entries) == 0:
+        return None
+    by_id = {entry.id: entry for entry in entries}
+
+    def depth_of(id: str) -> int:
+        depth = 0
+        cursor: str | None = id
+        seen: set[str] = set()
+        while cursor is not None and cursor not in seen:
+            seen.add(cursor)
+            node = by_id.get(cursor)
+            if node is None:
+                break
+            depth += 1
+            cursor = node.parent
+        return depth
+
+    best = entries[0]
+    best_depth = depth_of(best.id)
+    for entry in entries:
+        depth = depth_of(entry.id)
+        if depth > best_depth or (depth == best_depth and entry.id > best.id):
+            best = entry
+            best_depth = depth
+    return best.id

induscode/console/__init__.py

@@ -0,0 +1,236 @@
+"""Interactive console package (M5) — public barrel.
+
+Port of TS ``src/console`` (``index.ts``, growing wave by wave). The console
+is the *product shell* wrapped around the framework's rendering library: the
+framework (``indusagi.react_ink``) supplies the message list, streaming
+markdown, footer/status strips, and all dialog bodies; the console adds
+everything that makes those a coding-agent app.
+
+Landed waves:
+
+- **The contract** (:mod:`.contract`) — the frozen type surface: the
+  :class:`ConsoleState` slice (rows/blocks/modal/status/scheme/toggles/busy;
+  the composer buffer/caret/history live in the framework editor), the
+  :data:`ConsoleEvent` union (TS ``domain:verb`` tags verbatim), the 12-kind
+  :data:`ModalKind` machine, the theme vocabulary, and the
+  :class:`ConsoleProps` / :class:`OverlayServices` host shapes. The M1 slash
+  framework types (:mod:`induscode.console_slash`) are re-exported here so
+  console consumers import one surface.
+- **The reducer** (:mod:`.reducer`) — the single pure fold over
+  :class:`ConsoleState`.
+- **The theme engine** (:mod:`.theme`) — four own-authored 9-stop ramps →
+  25 semantic tokens → the framework colour-key projection → one
+  ``ThemeBundle`` per scheme (painter adapter + Textual Theme + Pygments
+  style), assembled once into :data:`THEMES` and resolved through
+  :func:`resolve_theme`.
+- **Startup gathering** (:mod:`.startup`) — the pure resource/changelog
+  survey the banner draws.
+- :mod:`.slash_commands` — the transcript and workbench slash command
+  groups, written against the M1 :mod:`induscode.console_slash` framework.
+- :mod:`.input` — the console input layer: the console-intent vocabulary and
+  the chord→intent table the ``ConsoleApp`` BINDINGS derive from, the
+  double-tap chord latch + Ctrl+C exit-window helpers, and the slash/
+  ``@``-path autocomplete providers feeding the framework ``PromptEditor``
+  (TS ``src/console/input``; ``paste.ts`` collapsed into the framework
+  ``EditorCore`` paste markers).
+- :mod:`.components` — the chrome widgets (``Banner`` / ``Emblem`` /
+  ``StatusBar``); :mod:`.overlays` — the awaited ``push_screen_wait`` flows
+  behind :func:`~induscode.console.overlays.open_overlay`.
+- **The surface** (:mod:`.app`) — :class:`ConsoleApp`, the Textual rewrite
+  of TS ``TerminalConsole.tsx``: the conductor signal→reducer projection,
+  the redesigned streaming-segment bookkeeping (with
+  ``stream_parity_report``), submit routing (``!``/``!!`` → slash → prompt),
+  the INTENT_TABLE-derived BINDINGS + chord/exit-window machines, the
+  overlay workers, and the exit transcript.
+- **The mount** (:mod:`.mount`) — :func:`mount_console`, the single entry
+  point a run mode awaits to take over the terminal; the boot repl runner's
+  default ``set_console_mount`` seam resolves to it.
+"""
+
+from induscode.console_slash import (
+    Handled,
+    OpenModal,
+    Prompt,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    SlashRegistry,
+    SlashRun,
+    Unknown,
+)
+
+from .app import (
+    ConductorSignalMessage,
+    ConsoleApp,
+    count_providers,
+    project_snapshot,
+    read_branch,
+    read_double_escape_action,
+)
+from .contract import (
+    CONSOLE_EVENT_TYPES,
+    DEFAULT_SCHEME,
+    EMPTY_CONSOLE_STATE,
+    MODAL_KINDS,
+    NO_MODAL,
+    THEME_TOKEN_ROLES,
+    BlockAppend,
+    BlocksClear,
+    BusySet,
+    ConductorState,
+    ConsoleDispatch,
+    ConsoleEvent,
+    ConsoleEventType,
+    ConsoleHost,
+    ConsoleProps,
+    ConsoleReducer,
+    ConsoleState,
+    ConsoleTheme,
+    InkThemeAdapter,
+    ModalClose,
+    ModalKind,
+    ModalOpen,
+    ModalState,
+    OverlayServices,
+    RowsAppend,
+    RowsPatch,
+    RowsSet,
+    SchemeSet,
+    SessionConductor,
+    SessionSignal,
+    SessionSnapshot,
+    StartOAuthLogin,
+    StatusClear,
+    StatusMessage,
+    StatusSet,
+    ThemePalette,
+    ThemeScheme,
+    ThemeToken,
+    ThemeTokens,
+    Tick,
+    ToggleImages,
+    ToggleReasoning,
+    ToolExecutionState,
+    UiDisplayBlock,
+    ViewRow,
+    ViewRowKind,
+    is_theme_scheme,
+    transition_modal,
+)
+from .mount import mount_console
+from .reducer import console_reducer, init_console_state
+from .startup import (
+    StartupChangelog,
+    StartupChangelogMode,
+    StartupInputs,
+    StartupMap,
+    StartupNotice,
+    StartupNoticeKind,
+    StartupSection,
+    gather_changelog,
+    gather_startup,
+)
+from .theme import (
+    DAYLIGHT_CB_PALETTE,
+    DAYLIGHT_PALETTE,
+    MIDNIGHT_CB_PALETTE,
+    MIDNIGHT_PALETTE,
+    PALETTES,
+    THEME_SCHEMES,
+    THEMES,
+    derive_tokens,
+    framework_colors,
+    resolve_theme,
+    theme_adapter,
+    theme_bundle,
+)
+
+__all__ = [
+    "BlockAppend",
+    "BlocksClear",
+    "BusySet",
+    "CONSOLE_EVENT_TYPES",
+    "ConductorSignalMessage",
+    "ConductorState",
+    "ConsoleApp",
+    "ConsoleDispatch",
+    "ConsoleEvent",
+    "ConsoleEventType",
+    "ConsoleHost",
+    "ConsoleProps",
+    "ConsoleReducer",
+    "ConsoleState",
+    "ConsoleTheme",
+    "DAYLIGHT_CB_PALETTE",
+    "DAYLIGHT_PALETTE",
+    "DEFAULT_SCHEME",
+    "EMPTY_CONSOLE_STATE",
+    "Handled",
+    "InkThemeAdapter",
+    "MIDNIGHT_CB_PALETTE",
+    "MIDNIGHT_PALETTE",
+    "MODAL_KINDS",
+    "ModalClose",
+    "ModalKind",
+    "ModalOpen",
+    "ModalState",
+    "NO_MODAL",
+    "OpenModal",
+    "OverlayServices",
+    "PALETTES",
+    "Prompt",
+    "RowsAppend",
+    "RowsPatch",
+    "RowsSet",
+    "SchemeSet",
+    "SessionConductor",
+    "SessionSignal",
+    "SessionSnapshot",
+    "SlashCommand",
+    "SlashContext",
+    "SlashOutcome",
+    "SlashRegistry",
+    "SlashRun",
+    "StartOAuthLogin",
+    "StartupChangelog",
+    "StartupChangelogMode",
+    "StartupInputs",
+    "StartupMap",
+    "StartupNotice",
+    "StartupNoticeKind",
+    "StartupSection",
+    "StatusClear",
+    "StatusMessage",
+    "StatusSet",
+    "THEMES",
+    "THEME_SCHEMES",
+    "THEME_TOKEN_ROLES",
+    "ThemePalette",
+    "ThemeScheme",
+    "ThemeToken",
+    "ThemeTokens",
+    "Tick",
+    "ToggleImages",
+    "ToggleReasoning",
+    "ToolExecutionState",
+    "UiDisplayBlock",
+    "Unknown",
+    "ViewRow",
+    "ViewRowKind",
+    "console_reducer",
+    "count_providers",
+    "derive_tokens",
+    "framework_colors",
+    "gather_changelog",
+    "gather_startup",
+    "init_console_state",
+    "is_theme_scheme",
+    "mount_console",
+    "project_snapshot",
+    "read_branch",
+    "read_double_escape_action",
+    "resolve_theme",
+    "theme_adapter",
+    "theme_bundle",
+    "transition_modal",
+]