chore: import upstream snapshot with attribution

surfaces/interactive_shell/command_registry/session_cmds/__init__.py

@@ -0,0 +1,58 @@
+"""Session lifecycle slash commands: /clear, /new, /sessions, /resume, /compact."""
+
+from __future__ import annotations
+
+from surfaces.interactive_shell.command_registry.session_cmds.lifecycle import (
+    _cmd_clear,
+    _cmd_compact,
+    _cmd_new,
+)
+from surfaces.interactive_shell.command_registry.session_cmds.list import _cmd_sessions
+from surfaces.interactive_shell.command_registry.session_cmds.resume import (
+    _apply_resume_data,
+    _cmd_resume,
+)
+from surfaces.interactive_shell.command_registry.types import SlashCommand
+
+COMMANDS: list[SlashCommand] = [
+    SlashCommand("/clear", "Clear the screen and re-render the banner.", _cmd_clear),
+    SlashCommand(
+        "/sessions",
+        "List recent REPL sessions.",
+        _cmd_sessions,
+        usage=("/sessions",),
+    ),
+    SlashCommand(
+        "/resume",
+        "Resume a previous session by restoring its conversation context.",
+        _cmd_resume,
+        usage=("/resume <session-id-prefix>", "/resume <session-id-prefix>:<entry-id-prefix>"),
+        notes=(
+            "Restores cli_agent_messages and accumulated infra context from the chosen session.",
+            "Bare /resume opens an interactive session picker in a TTY.",
+            "Accepts a session ID prefix, entry ref, or name substring (e.g. /resume redis).",
+            "Replaces the current session's LLM conversation context; warns if messages exist.",
+        ),
+    ),
+    SlashCommand(
+        "/new",
+        "Start a new session while keeping the current conversation context.",
+        _cmd_new,
+        notes=(
+            "Unlike /clear, /new rotates the session ID and resets state while keeping LLM context.",
+            "Use after /resume to continue a conversation in a clean session file.",
+        ),
+    ),
+    SlashCommand(
+        "/compact",
+        "Compact the current session context into a replayable summary entry.",
+        _cmd_compact,
+        usage=("/compact",),
+        notes=(
+            "Writes a compaction entry and keeps the most recent messages plus a summary.",
+            "Useful before continuing a long-running investigation in the same REPL.",
+        ),
+    ),
+]
+
+__all__ = ["COMMANDS", "_apply_resume_data"]

surfaces/interactive_shell/command_registry/session_cmds/lifecycle.py

@@ -0,0 +1,58 @@
+"""Session lifecycle slash commands: /clear, /new, and /compact."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from core.agent_harness.session import SessionManager
+from surfaces.interactive_shell.runtime import Session
+from surfaces.interactive_shell.ui import DIM, HIGHLIGHT
+
+
+def _cmd_clear(session: Session, console: Console, _args: list[str]) -> bool:
+    from surfaces.interactive_shell.ui import render_ready_box
+
+    console.clear()
+    render_ready_box(console, session=session)
+    return True
+
+
+def _cmd_new(session: Session, console: Console, _args: list[str]) -> bool:
+    """Start a new session while preserving the current LLM conversation context.
+
+    Unlike /clear (which only clears the screen), /new rotates the session ID
+    and resets all session state while keeping cli_agent_messages and
+    accumulated_context so a resumed or in-progress conversation continues
+    seamlessly in a fresh session file.
+    """
+    saved_messages = list(session.agent.messages)
+    saved_context = dict(session.accumulated_context)
+    saved_resumed_name = session.resumed_from_name
+
+    SessionManager.for_session(session).rotate_in_place(session)
+
+    session.agent.messages = saved_messages
+    session.accumulated_context = saved_context
+    session.resumed_from_name = saved_resumed_name
+    console.print(
+        f"[{DIM}]new session started[/] [{HIGHLIGHT}]—[/] [{DIM}]conversation context carried forward.[/]"
+    )
+    if saved_messages:
+        console.print(f"[{DIM}]  {len(saved_messages)} messages in context · type to continue[/]")
+    return True
+
+
+def _cmd_compact(session: Session, console: Console, _args: list[str]) -> bool:
+    """Compact the live session branch and persist a compaction entry."""
+    from core.agent_harness.turns.transcript_compaction import compact_session_branch
+
+    result = compact_session_branch(session)
+    if result is None:
+        console.print(f"[{DIM}]Nothing to compact yet.[/]")
+        return True
+    console.print(
+        f"[{HIGHLIGHT}]compacted session context[/] "
+        f"[{DIM}]({result.before_chars} chars -> {result.after_chars} chars)[/]"
+    )
+    session.record("slash", "/compact")
+    return True

surfaces/interactive_shell/command_registry/session_cmds/list.py

@@ -0,0 +1,81 @@
+"""Session listing slash command: /sessions."""
+
+from __future__ import annotations
+
+import contextlib
+
+from rich.console import Console
+from rich.markup import escape
+
+from surfaces.interactive_shell.runtime import Session
+from surfaces.interactive_shell.ui import (
+    BOLD_BRAND,
+    DIM,
+    print_repl_table,
+    repl_table,
+)
+from surfaces.interactive_shell.ui.components.time_format import (
+    format_repl_duration,
+    format_repl_timestamp,
+)
+
+
+def _cmd_sessions(session: Session, console: Console, _args: list[str]) -> bool:
+    from datetime import UTC, datetime
+
+    from core.agent_harness.session import default_session_repo
+
+    entries = default_session_repo().load_recent(20)
+    if not entries:
+        console.print(f"[{DIM}]No sessions recorded yet.[/]")
+        return True
+
+    table = repl_table(title="Recent sessions\n", title_style=BOLD_BRAND)
+    table.add_column("#", style="bold", justify="right")
+    table.add_column("Session ID", style="bold")
+    table.add_column("Name")
+    table.add_column("Started")
+    table.add_column("Duration")
+    table.add_column("Turns", justify="right")
+    table.add_column("Investigations", justify="right")
+
+    for i, entry in enumerate(entries, start=1):
+        sid = entry["session_id"]
+        short_id = sid[:8] if len(sid) >= 8 else sid
+        is_current = sid == session.session_id
+
+        name = entry.get("name") or ""
+        if is_current and not name and session.resumed_from_name:
+            name = f"↩ {session.resumed_from_name}"
+        if is_current:
+            name_col = f"[{DIM}](current)[/]" if not name else f"{escape(name)} [{DIM}](current)[/]"
+        else:
+            name_col = escape(name) if name else f"[{DIM}]—[/]"
+
+        started_str = format_repl_timestamp(entry.get("started_at"), style="table")
+
+        duration_secs = entry.get("duration_secs")
+        if is_current:
+            with contextlib.suppress(OSError, OverflowError, ValueError):
+                elapsed = int(
+                    (
+                        datetime.now(UTC) - datetime.fromtimestamp(session.started_at, tz=UTC)
+                    ).total_seconds()
+                )
+                duration_secs = elapsed
+
+        total = entry.get("total_turns")
+        investigations = entry.get("investigation_turns")
+
+        table.add_row(
+            str(i),
+            short_id,
+            name_col,
+            started_str,
+            format_repl_duration(duration_secs),
+            str(total) if total is not None else "—",
+            str(investigations) if investigations is not None else "—",
+        )
+
+    print_repl_table(console, table)
+    return True

surfaces/interactive_shell/command_registry/session_cmds/resume.py

@@ -0,0 +1,232 @@
+"""Session resume slash command and helpers: /resume."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.markup import escape
+
+from core.agent_harness.session import SessionManager
+from surfaces.interactive_shell.command_registry.session_cmds.resume_rendering import (
+    render_resumed_session_history,
+)
+from surfaces.interactive_shell.runtime import Session
+from surfaces.interactive_shell.ui import DIM, ERROR, HIGHLIGHT, WARNING
+from surfaces.interactive_shell.ui.components.choice_menu import (
+    repl_choose_one,
+    repl_tty_interactive,
+)
+from surfaces.interactive_shell.ui.components.time_format import format_repl_timestamp
+
+
+def _record_resume_slash(
+    session: Session,
+    args: list[str],
+    *,
+    ok: bool = True,
+    picked_id: str | None = None,
+) -> None:
+    """Record /resume in the active session file after identity is settled."""
+    if picked_id:
+        text = f"/resume {picked_id[:8]}"
+    elif args:
+        text = f"/resume {' '.join(args)}"
+    else:
+        text = "/resume"
+    session.record("slash", text, ok=ok)
+
+
+def _interactive_resume_menu(session: Session, console: Console) -> bool:
+    """Show a numbered list of recent sessions and resume the selected one."""
+    from core.agent_harness.session import default_session_repo
+
+    entries = [
+        e for e in default_session_repo().load_recent(10) if e["session_id"] != session.session_id
+    ]
+    if not entries:
+        console.print(f"[{DIM}]No previous sessions to resume.[/]")
+        return True
+
+    choices: list[tuple[str, str]] = []
+    for entry in entries:
+        sid = entry["session_id"]
+        short_id = sid[:8]
+        name = entry.get("name") or f"[{short_id}]"
+        started_str = format_repl_timestamp(entry.get("started_at"), style="compact")
+        label = f"{name[:40]:<40}  {short_id}  {started_str}"
+        choices.append((sid, label))
+    choices.append(("done", "done"))
+
+    picked = repl_choose_one(title="resume session", breadcrumb="/resume", choices=choices)
+    if picked is None or picked == "done":
+        return True
+
+    slash_command = f"/resume {picked[:8]}"
+    if not _do_resume(picked, session, console, slash_command=slash_command):
+        _record_resume_slash(session, [], picked_id=picked, ok=False)
+    return True
+
+
+def _apply_resume_data(
+    data: dict,
+    session: Session,
+    console: Console,
+    *,
+    slash_command: str | None = None,
+) -> bool:
+    """Apply loaded session data into the running session and print a summary."""
+    messages = data.get("cli_agent_messages") or []
+    context = data.get("accumulated_context") or {}
+    history = data.get("history") or []
+    has_snapshot = data.get("has_snapshot", False)
+    sid = data.get("session_id", "")
+    short_id = sid[:8] if len(sid) >= 8 else sid
+    name = data.get("name") or ""
+
+    if not messages and not context:
+        console.print(
+            f"[{DIM}]session {short_id} has no conversation to resume "
+            "(no chat turns or context found).[/]"
+        )
+        if not data.get("turn_details") and not has_snapshot:
+            console.print(
+                f"[{DIM}]tip: turn_detail records are only written when prompt logging is enabled.[/]"
+            )
+        if slash_command:
+            session.record("slash", slash_command, ok=False)
+        return True
+
+    existing = session.agent.messages
+    if existing:
+        console.print(
+            f"[{WARNING}]current session has {len(existing)} messages — "
+            "they will be replaced by the resumed context.[/]"
+        )
+
+    manager = SessionManager.for_session(session)
+    manager.rebind_for_resume(
+        session,
+        session_id=sid,
+        started_at=data.get("started_at"),
+    )
+    manager.restore_context(session, data)
+
+    source = "snapshot" if has_snapshot else "turn records"
+    name_str = f" · {escape(name)}" if name else ""
+    console.print(
+        f"[{HIGHLIGHT}]resumed session {short_id}{name_str}[/] "
+        f"[{DIM}]({len(messages)} messages in context from {source})[/]"
+    )
+
+    render_resumed_session_history(
+        console,
+        history=history,
+        turn_details=data.get("turn_details") or [],
+        messages=list(messages),
+    )
+
+    if context:
+        console.print(
+            f"[{DIM}]accumulated context restored:[/] "
+            + ", ".join(f"{escape(k)}={escape(str(v))}" for k, v in sorted(context.items()))
+        )
+
+    if slash_command:
+        session.record("slash", slash_command)
+
+    return True
+
+
+def _lookup_resume_session_data(
+    prefix: str,
+    session: Session,
+    console: Console,
+) -> dict | None:
+    """Resolve a session to resume by ID prefix or name substring."""
+    from core.agent_harness.session import default_session_repo
+
+    repo = default_session_repo()
+    data = repo.load_session(prefix)
+    if data is None and len(prefix) >= 3:
+        candidates = [
+            e
+            for e in repo.load_recent(20)
+            if prefix.lower() in (e.get("name") or "").lower()
+            and e["session_id"] != session.session_id
+        ]
+        if len(candidates) == 1:
+            data = repo.load_session(candidates[0]["session_id"])
+        elif len(candidates) > 1:
+            console.print(
+                f"[{WARNING}]'{escape(prefix)}' matches {len(candidates)} sessions by name — "
+                "use a session ID prefix or be more specific.[/]"
+            )
+            return None
+
+    if data is not None:
+        return data
+
+    n = repo.count_prefix_matches(prefix)
+    if n > 1:
+        console.print(
+            f"[{WARNING}]ambiguous prefix '{escape(prefix)}' matches {n} sessions — "
+            "use more characters.[/]"
+        )
+    else:
+        console.print(f"[{ERROR}]session '{escape(prefix)}' not found.[/]")
+    return None
+
+
+def _do_resume(
+    prefix: str,
+    session: Session,
+    console: Console,
+    *,
+    slash_command: str | None = None,
+) -> bool:
+    """Load session by ID prefix and restore context into the running session."""
+    data = _lookup_resume_session_data(prefix, session, console)
+    if data is None:
+        return False
+    return _apply_resume_data(data, session, console, slash_command=slash_command)
+
+
+def resume_session_by_prefix(
+    prefix: str,
+    session: Session,
+    console: Console,
+    *,
+    slash_command: str | None = None,
+) -> bool:
+    """Load session by ID prefix and restore context into the running session."""
+    return _do_resume(prefix, session, console, slash_command=slash_command)
+
+
+def _cmd_resume(session: Session, console: Console, args: list[str]) -> bool:
+    if not args and repl_tty_interactive():
+        return _interactive_resume_menu(session, console)
+
+    if not args:
+        console.print(f"[{DIM}]usage: /resume <session-id-prefix>[/]")
+        console.print(f"[{DIM}]run /sessions to list session IDs.[/]")
+        _record_resume_slash(session, args)
+        return True
+
+    prefix = args[0].strip()
+    session_prefix = prefix.split(":", 1)[0]
+
+    if session.session_id.startswith(session_prefix) and ":" not in prefix:
+        console.print(
+            f"[{DIM}]session {session_prefix[:8]} is the current session — "
+            "run /sessions to pick a previous one.[/]"
+        )
+        _record_resume_slash(session, args)
+        return True
+
+    data = _lookup_resume_session_data(prefix, session, console)
+    if data is None:
+        _record_resume_slash(session, args, ok=False)
+        return True
+
+    slash_command = f"/resume {' '.join(args)}" if args else "/resume"
+    _apply_resume_data(data, session, console, slash_command=slash_command)
+    return True

surfaces/interactive_shell/command_registry/session_cmds/resume_rendering.py

@@ -0,0 +1,90 @@
+"""Presentation for /resume: render a resumed session's prior activity.
+
+Pure rendering — takes a console plus already-loaded session data and prints it
+in REPL turn order. Holds no lookup or orchestration logic so the resume command
+module stays focused on the resume flow.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+from rich.console import Console
+from rich.markup import escape
+
+from surfaces.interactive_shell.ui import DIM, HIGHLIGHT
+
+_HISTORY_DISPLAY_CHAT_KINDS: frozenset[str] = frozenset(
+    {"chat", "cli_agent", "follow_up", "alert", "incoming_alert"}
+)
+
+
+def _response_for_prompt(turn_details: list[dict], prompt: str) -> str:
+    for detail in turn_details:
+        if detail.get("prompt") == prompt:
+            return str(detail.get("response") or "")
+    return ""
+
+
+def render_resumed_session_history(
+    console: Console,
+    *,
+    history: list[dict],
+    turn_details: list[dict],
+    messages: list[tuple[str, str]],
+) -> None:
+    """Render prior session activity in REPL turn order, including slash commands."""
+    from rich.markdown import Markdown
+
+    from platform.terminal.theme import MARKDOWN_THEME
+    from surfaces.interactive_shell.ui.streaming import render_response_header
+
+    if not history and not messages:
+        return
+
+    console.print(f"[{DIM}]─── conversation history ─────────────────────────────────[/]")
+
+    if history:
+        assistant_by_user: dict[str, deque[str]] = {}
+        pending_user: str | None = None
+        for role, text in messages:
+            if role == "user":
+                pending_user = text
+            elif role == "assistant" and pending_user is not None:
+                assistant_by_user.setdefault(pending_user, deque()).append(text)
+                pending_user = None
+
+        for rec in history:
+            kind = rec.get("kind", "")
+            text = rec.get("text") or ""
+            if kind == "slash":
+                console.print(f"[bold]$ {escape(text)}[/bold]")
+                continue
+            if kind not in _HISTORY_DISPLAY_CHAT_KINDS or not text:
+                continue
+            console.print(f"[bold {HIGHLIGHT}]❯[/] {escape(text)}")
+            response = _response_for_prompt(turn_details, text)
+            if not response:
+                queued = assistant_by_user.get(text)
+                response = queued.popleft() if queued else ""
+            if response:
+                render_response_header(console, "assistant")
+                with console.use_theme(MARKDOWN_THEME):
+                    console.print(Markdown(response, code_theme="ansi_dark"))
+        console.print(f"[{DIM}]─────────────────────────────────────────────────────────[/]")
+        return
+
+    has_pending_user = False
+    for role, text in messages:
+        if role == "user":
+            console.print(f"[bold {HIGHLIGHT}]❯[/] {escape(text)}")
+            has_pending_user = True
+        elif role == "assistant" and has_pending_user:
+            render_response_header(console, "assistant")
+            with console.use_theme(MARKDOWN_THEME):
+                console.print(Markdown(text, code_theme="ansi_dark"))
+            has_pending_user = False
+    console.print(f"[{DIM}]─────────────────────────────────────────────────────────[/]")
+
+
+__all__ = ["render_resumed_session_history"]