induscode 0.1.0__py3-none-any.whl

induscode/sessions/library.py

@@ -0,0 +1,350 @@
+"""SessionLibrary — the catalog-and-navigation layer over persisted
+transcripts (port of TS ``src/sessions/library.ts``).
+
+The conductor owns a single session at a time as a
+:class:`~induscode.conductor.transcript_store.TranscriptStore`. The library
+owns the *collection*: it scans the workspace ``sessions/`` directory for the
+NDJSON files the conductor's filesystem backend writes, lists them as
+:class:`~induscode.sessions.contract.SavedSession` catalog rows, opens any
+one back into a live store via the store's own opener +
+:func:`~induscode.conductor.transcript_store.replay` reducer, and offers the
+two read projections a chooser UI needs — a flattened
+:class:`~induscode.sessions.contract.BranchNode` tree for a branch navigator
+and a :class:`~induscode.sessions.contract.PriorTurn` list for re-asking an
+earlier prompt. It also performs the two file-level mutations a manager
+needs: renaming and deleting a session on disk.
+
+The library never re-implements transcript parsing or message serialization —
+it delegates entirely to the conductor's transcript-store surface
+(:class:`TranscriptStore`, :func:`fs_backend`, :func:`replay`). Its own logic
+is purely the directory enumeration, the tree flatten, and the text
+reduction.
+
+Seam note: the per-cwd session scope directory (the ``--<cwd slug>--`` layout
+under the workspace ``sessions/`` root) is **boot's** helper — TS
+``boot/runners/session.ts#sessionScopeDir`` — not the library's. The library
+takes the already-scoped directory; the M4 boot wave ports the slug helper
+and must agree with the conductor (writer) on it.
+
+Port note: disk I/O runs through :func:`asyncio.to_thread` (matching the
+conductor's ``fs_backend`` discipline) so the async surface never blocks the
+loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, Final
+
+from induscode.conductor.contract import TranscriptEntry
+from induscode.conductor.transcript_store import TranscriptStore, fs_backend
+from induscode.sessions.contract import BranchNode, PriorTurn, SavedSession
+
+__all__ = [
+    "SessionLibrary",
+]
+
+
+#: Suffix the conductor's filesystem backend gives every session file.
+_SESSION_FILE_EXT: Final[str] = ".ndjson"
+
+#: Default cap for the single-line previews this library renders.
+_PREVIEW_LIMIT: Final[int] = 72
+
+
+class SessionLibrary:
+    """The collection-level handle over a workspace's persisted sessions.
+
+    Construct it with the resolved ``sessions_dir`` (from the workspace
+    locator, already cwd-scoped by boot), then call :meth:`list` /
+    :meth:`open` / :meth:`rename` / :meth:`remove` to manage files, and
+    :meth:`tree` / :meth:`prior_turns` to project a loaded transcript for
+    navigation and forking.
+    """
+
+    __slots__ = ("_dir", "_backend")
+
+    def __init__(self, *, sessions_dir: str) -> None:
+        """:param sessions_dir: absolute path to the workspace ``sessions/``
+        directory (TS ``SessionLibraryOptions.sessionsDir``)."""
+        self._dir = sessions_dir
+        self._backend = fs_backend(sessions_dir)
+
+    @property
+    def directory(self) -> str:
+        """The sessions directory this library is rooted at."""
+        return self._dir
+
+    async def list(self, *, deep: bool = False) -> list[SavedSession]:
+        """Enumerate persisted sessions as catalog rows, newest-modified
+        first.
+
+        Scans the directory for ``*.ndjson`` files and stats each for its
+        size and modification time. When ``deep`` is set, it also opens each
+        file to fill in ``messageCount`` and the opening-turn ``preview``;
+        otherwise it returns the shallow rows (id/path/size/lastModified) so
+        a large directory lists fast. A missing directory yields an empty
+        list rather than an error.
+        """
+        ids = await self._session_ids()
+        rows = await asyncio.gather(
+            *[self._deep_row(id) if deep else self._shallow_row(id) for id in ids]
+        )
+        return sorted(rows, key=_most_recent_key)
+
+    async def open(self, id: str) -> TranscriptStore | None:
+        """Open a persisted session back into a live, hydrated
+        :class:`TranscriptStore`, or return ``None`` when no file with that
+        id exists.
+
+        Delegates to the store's own opener, which reads the backend and
+        rebuilds state through the ``replay`` reducer — the library adds
+        nothing to the rehydration beyond binding the filesystem backend.
+        """
+        return await TranscriptStore.open(id, backend=self._backend)
+
+    async def rename(self, from_id: str, to_id: str) -> str:
+        """Rename a session file from one id to another, returning the new
+        absolute path. The on-disk identifier *is* the filename stem, so this
+        is a plain file move; the in-file head still names the old id, which
+        the store tolerates on the next load (the head's leaf is what
+        matters, not its session label).
+
+        :raises ValueError: if the source file is missing or the target id
+            already exists.
+        """
+        from_path = self.path_of(from_id)
+        to_path = self.path_of(to_id)
+        if await self._missing(from_path):
+            raise ValueError(f'SessionLibrary.rename: no session "{from_id}"')
+        if not await self._missing(to_path):
+            raise ValueError(f'SessionLibrary.rename: session "{to_id}" already exists')
+
+        def _move() -> None:
+            Path(self._dir).mkdir(parents=True, exist_ok=True)
+            os.rename(from_path, to_path)
+
+        await asyncio.to_thread(_move)
+        return to_path
+
+    async def remove(self, id: str) -> bool:
+        """Delete a session file. Returns ``True`` when a file was removed,
+        ``False`` when there was nothing to delete — never raises on an
+        already-absent session."""
+        path = self.path_of(id)
+        if await self._missing(path):
+            return False
+
+        def _unlink() -> None:
+            Path(path).unlink(missing_ok=True)
+
+        await asyncio.to_thread(_unlink)
+        return True
+
+    def path_of(self, id: str) -> str:
+        """Absolute path a session id persists to."""
+        return str(Path(self._dir) / f"{id}{_SESSION_FILE_EXT}")
+
+    def tree(self, store: TranscriptStore) -> list[BranchNode]:
+        """Flatten a loaded transcript into an ordered :class:`BranchNode`
+        list for a tree navigator.
+
+        Walks every node from each root downward in a stable depth-first
+        order, emitting one row per node with its render label, depth
+        indentation, leaf flag, and a current-marker derived from the store's
+        active head. A node is a leaf when no other node names it as
+        ``parent``. Pure — no I/O.
+        """
+        nodes = list(store.state().nodes.values())
+        current_leaf = store.head.leaf
+
+        children_of: dict[str | None, list[TranscriptEntry]] = {}
+        for node in nodes:
+            children_of.setdefault(node.parent, []).append(node)
+        has_children: set[str] = {node.parent for node in nodes if node.parent is not None}
+
+        out: list[BranchNode] = []
+
+        def walk(entry: TranscriptEntry, depth: int) -> None:
+            out.append(
+                BranchNode(
+                    id=entry.id,
+                    parent=entry.parent,
+                    label=_label_for(entry, depth),
+                    depth=depth,
+                    isLeaf=entry.id not in has_children,
+                    isCurrent=entry.id == current_leaf,
+                )
+            )
+            for child in children_of.get(entry.id, []):
+                walk(child, depth + 1)
+
+        for root in children_of.get(None, []):
+            walk(root, 0)
+        return out
+
+    def prior_turns(self, store: TranscriptStore) -> list[PriorTurn]:
+        """Extract the user prompts along a loaded transcript's active branch
+        as fork candidates, in chronological order.
+
+        Reads the root→leaf branch the store currently points at (the
+        conversation the agent would replay) and keeps only the user-role
+        nodes that carry real text, projecting each to a :class:`PriorTurn` a
+        forking picker can offer. Pure — no I/O.
+        """
+        out: list[PriorTurn] = []
+        for entry in store.path_to():
+            if entry.role != "user":
+                continue
+            text = _message_text(entry.content).strip()
+            if len(text) == 0:
+                continue
+            out.append(PriorTurn(entryId=entry.id, text=text, preview=_preview_of(text)))
+        return out
+
+    # -- internals ------------------------------------------------------------
+
+    async def _session_ids(self) -> list[str]:
+        """Bare session ids present in the directory (no extension), or
+        ``[]``."""
+
+        def _scan() -> list[str]:
+            try:
+                names = os.listdir(self._dir)
+            except OSError:
+                return []
+            return [
+                name[: -len(_SESSION_FILE_EXT)]
+                for name in names
+                if name.endswith(_SESSION_FILE_EXT)
+            ]
+
+        return await asyncio.to_thread(_scan)
+
+    async def _shallow_row(self, id: str) -> SavedSession:
+        """Catalog row from file metadata only — no parse."""
+        path = self.path_of(id)
+        size, last_modified = await self._file_meta(path)
+        return SavedSession(id=id, path=path, size=size, lastModified=last_modified)
+
+    async def _deep_row(self, id: str) -> SavedSession:
+        """Catalog row enriched by opening the transcript and reducing its
+        text."""
+        path = self.path_of(id)
+        size, last_modified = await self._file_meta(path)
+        store = await self.open(id)
+        if store is None:
+            return SavedSession(id=id, path=path, size=size, lastModified=last_modified)
+
+        branch = store.path_to()
+        conversational = [entry for entry in branch if _is_conversational(entry)]
+        opener = next((entry for entry in conversational if entry.role == "user"), None)
+        preview = _preview_of(_message_text(opener.content)) if opener is not None else None
+        has_preview = preview is not None and len(preview) > 0
+        return SavedSession(
+            id=id,
+            path=path,
+            size=size,
+            lastModified=last_modified,
+            messageCount=len(conversational),
+            preview=preview if has_preview else None,
+            name=preview if has_preview else None,
+        )
+
+    async def _file_meta(self, path: str) -> tuple[int | None, float | None]:
+        """Best-effort ``(size, lastModified-ms)``; ``(None, None)`` when the
+        file is gone."""
+
+        def _stat() -> tuple[int | None, float | None]:
+            try:
+                info = os.stat(path)
+                return info.st_size, info.st_mtime * 1000.0
+            except OSError:
+                return None, None
+
+        return await asyncio.to_thread(_stat)
+
+    async def _missing(self, path: str) -> bool:
+        """True when a path does not resolve to a readable file."""
+        return not await asyncio.to_thread(os.path.isfile, path)
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_conversational(entry: TranscriptEntry) -> bool:
+    """Conversational roles count toward a session's message total."""
+    return entry.role in ("user", "assistant", "tool")
+
+
+def _most_recent_key(row: SavedSession) -> tuple[float, str]:
+    """Sort key: most recently modified first, ties broken by id."""
+    return (-(row.lastModified if row.lastModified is not None else 0), row.id)
+
+
+def _label_for(entry: TranscriptEntry, depth: int) -> str:
+    """Build a depth-indented, role-aware label for a transcript node."""
+    indent = "  " * depth
+    match entry.role:
+        case "user":
+            return f"{indent}user: {_preview_of(_message_text(entry.content))}"
+        case "assistant":
+            return f"{indent}assistant"
+        case "tool":
+            return f"{indent}tool: {_tool_name_of(entry.content)}"
+        case "condense":
+            return f"{indent}condense"
+        case "system":
+            return f"{indent}system"
+        case _:
+            return f"{indent}note"
+
+
+def _read(value: Any, name: str) -> Any:
+    """Field access tolerant of both frozen dataclasses and raw mappings."""
+    if isinstance(value, Mapping):
+        return value.get(name)
+    return getattr(value, name, None)
+
+
+def _tool_name_of(message: Any) -> str:
+    """Tool name carried by a tool-result message, or a placeholder."""
+    candidate = _read(message, "toolName")
+    return candidate if isinstance(candidate, str) and len(candidate) > 0 else "tool"
+
+
+def _message_text(message: Any) -> str:
+    """Reduce any framework ``AgentMessage`` to its plain text.
+
+    Messages carry ``content`` as either a raw string or a sequence of typed
+    blocks; we concatenate the text-bearing blocks and ignore images,
+    thinking, and tool calls. Defensive about shape so a malformed or custom
+    message yields ``""`` rather than raising.
+    """
+    content = _read(message, "content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, Sequence) or isinstance(content, (str, bytes)):
+        return ""
+    parts: list[str] = []
+    for block in content:
+        if _read(block, "type") == "text":
+            text = _read(block, "text")
+            if isinstance(text, str):
+                parts.append(text)
+    return "".join(parts)
+
+
+def _preview_of(text: str, limit: int = _PREVIEW_LIMIT) -> str:
+    """Collapse text to a single trimmed line and cap its length for
+    display."""
+    flat = re.sub(r"\s+", " ", text).strip()
+    if len(flat) <= limit:
+        return flat
+    return flat[: max(0, limit - 1)] + "…"

induscode/settings/__init__.py

@@ -0,0 +1,47 @@
+"""Settings subsystem — public barrel (port of the TS ``src/settings``
+barrel).
+
+One import site for the typed :class:`Preferences` record and its
+:data:`SettingKey` / :data:`EscapeAction` / :data:`DeliveryMode` /
+``ThinkingLevel`` vocabularies, the frozen :data:`DEFAULT_PREFERENCES`, the
+explicit snake_case ↔ camelCase alias maps, and the two-tier
+:class:`PreferenceStore` reader/writer. Console surfaces and boot stages
+depend on this module rather than reaching into the individual files.
+"""
+
+from .contract import (
+    DEFAULT_PREFERENCES,
+    DELIVERY_MODES,
+    ESCAPE_ACTIONS,
+    FIELD_TO_JSON_KEY,
+    JSON_TO_FIELD_KEY,
+    SETTING_KEYS,
+    DeliveryMode,
+    EscapeAction,
+    Preferences,
+    SettingKey,
+    ThinkingLevel,
+    canonical_key,
+    is_delivery_mode,
+    is_escape_action,
+)
+from .manager import PreferenceLocations, PreferenceStore
+
+__all__ = [
+    "DEFAULT_PREFERENCES",
+    "DELIVERY_MODES",
+    "DeliveryMode",
+    "ESCAPE_ACTIONS",
+    "EscapeAction",
+    "FIELD_TO_JSON_KEY",
+    "JSON_TO_FIELD_KEY",
+    "PreferenceLocations",
+    "PreferenceStore",
+    "Preferences",
+    "SETTING_KEYS",
+    "SettingKey",
+    "ThinkingLevel",
+    "canonical_key",
+    "is_delivery_mode",
+    "is_escape_action",
+]