induscode 0.1.0__py3-none-any.whl

induscode/console/slash_commands/transcript.py

@@ -0,0 +1,404 @@
+"""Transcript & session-control slash commands.
+
+Port of TS ``src/console/slash/commands/transcript.ts``: the first topic
+group of the console's slash catalog — the verbs that reset, rename, branch,
+inspect, or leave the live session view. Every row is a thin
+:class:`~induscode.console_slash.SlashCommand` whose ``run`` drives the
+injected :class:`~induscode.console_slash.SlashContext` — a reducer event, a
+conductor call, a modal, or an exit request — and settles to ``HANDLED``.
+Nothing here reaches into the TUI, the filesystem, or a provider SDK
+directly; backend work flows through the ``SessionConductor``.
+
+The rename, stats, condense, and reload verbs are backed by real conductor
+surface (``set_session_name`` / ``stats`` / ``condense``). Where the
+conductor cannot accept a richer input (the condense path is parameterless
+on this build), the closest real action is taken and the status line
+explains precisely what was applied.
+
+Async/fire-and-forget translation (the plan's locked cross-cutting rule 3):
+every ``run`` here is ``async def`` and the dispatcher awaits it, so the TS
+``void (async () => {...})()`` bodies of ``/summarize-context`` and
+``/reload`` run *inline* — the busy→done status sequence becomes
+deterministic. Only the conductor reset behind ``/clear`` / ``/new`` stays
+fire-and-forget (it must not delay the success toast); it rides a tracked
+:func:`asyncio.create_task` whose failure is swallowed into a status warn —
+never a bare task, never a crash.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import TYPE_CHECKING, Final
+
+from indusagi.react_ink import StatusMessage, UiDisplayBlock
+
+from induscode.console_slash import (
+    HANDLED,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    info,
+    warn,
+)
+
+if TYPE_CHECKING:
+    from induscode.conductor import SessionStats
+
+__all__ = ["transcript_commands"]
+
+
+# ---------------------------------------------------------------------------
+# Block-id minting (TS `Date.now().toString(36)`)
+# ---------------------------------------------------------------------------
+
+_BASE36_DIGITS: Final = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _base36(value: int) -> str:
+    """Render a non-negative int in base 36 (TS ``Number.toString(36)``)."""
+    if value <= 0:
+        return "0"
+    digits: list[str] = []
+    while value:
+        value, rem = divmod(value, 36)
+        digits.append(_BASE36_DIGITS[rem])
+    return "".join(reversed(digits))
+
+
+def _now_ms() -> int:
+    """Epoch milliseconds (TS ``Date.now()``)."""
+    return int(time.time() * 1000)
+
+
+# ---------------------------------------------------------------------------
+# Fire-and-forget task anchoring
+# ---------------------------------------------------------------------------
+
+#: Strong references to in-flight background tasks so they cannot be
+#: garbage-collected mid-flight (the asyncio create_task anchoring pattern).
+#: Each settled coroutine swallows its own failure into a status warn, so a
+#: task here never raises. The M5 console host may later own this set on its
+#: per-console holder; the anchor-and-discard discipline stays the same.
+_BACKGROUND_TASKS: Final[set[asyncio.Task[None]]] = set()
+
+
+def _spawn(coro) -> None:
+    """Run ``coro`` as a tracked background task (never a bare task)."""
+    task = asyncio.create_task(coro)
+    _BACKGROUND_TASKS.add(task)
+    task.add_done_callback(_BACKGROUND_TASKS.discard)
+
+
+# ---------------------------------------------------------------------------
+# View wipe + session reset
+# ---------------------------------------------------------------------------
+
+
+def _wipe_view(ctx: SlashContext) -> None:
+    """Blank everything the console is rendering: the row list, the display
+    blocks, and the status line. This is the view half of a clear;
+    :func:`_start_new_session` pairs it with the conductor-side conversation
+    reset."""
+    ctx.dispatch({"type": "rows:set", "rows": []})
+    ctx.dispatch({"type": "blocks:clear"})
+    ctx.dispatch({"type": "status:clear"})
+
+
+def _start_new_session(ctx: SlashContext, toast: str) -> SlashOutcome:
+    """Start a fresh session: wipe the rendered view, then drop the
+    conductor's conversation and open a new session id via ``new_session``.
+
+    The conductor reset is what actually empties the transcript — the
+    rendered conversation comes from ``conductor.messages()``, so clearing
+    only the view would leave every prior turn on screen (the old ``/clear``
+    bug). The reset is effectively synchronous internally; fire it without
+    blocking the success toast and only surface a status if it unexpectedly
+    rejects.
+    """
+    _wipe_view(ctx)
+    ctx.set_status(info(toast))
+
+    async def settle() -> None:
+        try:
+            await ctx.conductor.new_session()
+        except Exception:
+            ctx.set_status(warn("Could not start a new session."))
+
+    _spawn(settle())
+    return HANDLED
+
+
+async def _run_clear(ctx: SlashContext) -> SlashOutcome:
+    """Clear the conversation and begin a brand-new session."""
+    return _start_new_session(ctx, "Started a new session.")
+
+
+async def _run_new(ctx: SlashContext) -> SlashOutcome:
+    """Begin a fresh session for a new line of work (same as ``/clear``)."""
+    return _start_new_session(ctx, "Started a new session.")
+
+
+# ---------------------------------------------------------------------------
+# Condense (/summarize-context)
+# ---------------------------------------------------------------------------
+
+
+async def _run_compact(ctx: SlashContext) -> SlashOutcome:
+    """Condense the live transcript to reclaim context window.
+
+    Shows a busy status, then drives the conductor's condense path. With
+    trailing instructions present the command first records them as a
+    session note via the shell-note path so they re-enter the agent's
+    context to steer the next condense, then runs the parameterless
+    ``condense`` — the one condense entry point this build exposes. A
+    completion status reports what ran once the path settles.
+    """
+    instructions = ctx.args.strip()
+    busy_text = (
+        f"Condensing with guidance: {instructions}"
+        if instructions
+        else "Condensing conversation context..."
+    )
+    ctx.set_status(StatusMessage(kind="busy", text=busy_text))
+    try:
+        if instructions:
+            # JSON quoting doubles as shell quoting here, exactly as the TS
+            # `JSON.stringify` interpolation did (ensure_ascii=False keeps
+            # non-ASCII guidance verbatim, like JSON.stringify).
+            quoted = json.dumps(
+                f"Compaction guidance: {instructions}", ensure_ascii=False
+            )
+            await ctx.conductor.execute_bash(f"printf '%s' {quoted}")
+        await ctx.conductor.condense()
+        ctx.set_status(
+            info(
+                "Context condensed (guidance recorded for the agent)."
+                if instructions
+                else "Context condensed."
+            )
+        )
+    except Exception:
+        ctx.set_status(
+            warn("Condense could not complete; the transcript is unchanged.")
+        )
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Pickers (/resume, /branch, /timeline)
+# ---------------------------------------------------------------------------
+
+
+async def _run_resume(ctx: SlashContext) -> SlashOutcome:
+    """Raise the session list to resume a persisted session."""
+    ctx.open_modal("sessions")
+    return HANDLED
+
+
+async def _run_fork(ctx: SlashContext) -> SlashOutcome:
+    """Raise the prior-user-turn picker to branch the transcript."""
+    ctx.open_modal("userTurns")
+    return HANDLED
+
+
+async def _run_tree(ctx: SlashContext) -> SlashOutcome:
+    """Raise the transcript-tree navigator."""
+    ctx.open_modal("tree")
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Session stats (/session)
+# ---------------------------------------------------------------------------
+
+
+def _stats_markdown(stats: SessionStats, name: str | None) -> str:
+    """Render a session-stats tally as a Markdown table for the display
+    block."""
+    dollars = f"${stats.cost:.4f}"
+    t = stats.tokens
+    rows: tuple[tuple[str, str], ...] = (
+        ("Session", f"{name} ({stats.sessionId})" if name else stats.sessionId),
+        ("Messages", str(stats.totalMessages)),
+        ("User / assistant", f"{stats.userMessages} / {stats.assistantMessages}"),
+        ("Tool calls / results", f"{stats.toolCalls} / {stats.toolResults}"),
+        ("Tokens (in / out)", f"{t.input} / {t.output}"),
+        ("Tokens (cache r/w)", f"{t.cacheRead} / {t.cacheWrite}"),
+        ("Tokens (total)", str(t.total)),
+        ("Cost", dollars),
+    )
+    body = "\n".join(f"| {key} | {value} |" for key, value in rows)
+    return f"| Field | Value |\n| --- | --- |\n{body}"
+
+
+async def _run_session(ctx: SlashContext) -> SlashOutcome:
+    """Append a session-statistics display block.
+
+    Reads a live ``SessionStats`` tally from the conductor and renders it as
+    a changelog-kind display block (the only block kind the surface
+    supports), plus a one-line info toast. Distinct from ``/resume``, which
+    opens the session picker.
+    """
+    stats = ctx.conductor.stats()
+    name = ctx.conductor.session_name()
+    block = UiDisplayBlock(
+        id=f"session-stats-{_base36(_now_ms())}",
+        title=f"Session: {name}" if name else "Session statistics",
+        markdown=_stats_markdown(stats, name),
+        timestamp=_now_ms(),
+    )
+    ctx.append_block(block)
+    ctx.set_status(
+        info(
+            f"{stats.totalMessages} messages, {stats.tokens.total} tokens, "
+            f"${stats.cost:.4f}."
+        )
+    )
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Naming (/name)
+# ---------------------------------------------------------------------------
+
+
+async def _run_name(ctx: SlashContext) -> SlashOutcome:
+    """Name the live session, or report its current name.
+
+    With an argument the command stores the label through the conductor's
+    ``set_session_name`` and confirms it. Bare, it reads back the current
+    ``session_name`` as a status line rather than warning, so the verb
+    doubles as an inspector.
+    """
+    label = ctx.args.strip()
+    if len(label) == 0:
+        current = ctx.conductor.session_name()
+        ctx.set_status(
+            info("This session has no name. Set one with /name <label>.")
+            if current is None or len(current) == 0
+            else info(f"Current session name: {current}")
+        )
+        return HANDLED
+    ctx.conductor.set_session_name(label)
+    ctx.set_status(info(f'Session named "{label}".'))
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Reload (/reload)
+# ---------------------------------------------------------------------------
+
+
+async def _run_reload(ctx: SlashContext) -> SlashOutcome:
+    """Re-read the live session's resources.
+
+    Drives the conductor through a no-op tree navigation onto its current
+    leaf, which rebuilds and replays the active branch onto the agent — the
+    closest real "reload session resources" action this surface exposes —
+    then reports it. When the transcript is empty (no leaf yet) there is
+    nothing to rebuild, so the command reports that instead of issuing a
+    navigation.
+    """
+    leaf = ctx.conductor.snapshot().head.leaf
+    if leaf is None:
+        ctx.set_status(info("Session is empty; nothing to reload."))
+        return HANDLED
+    ctx.set_status(StatusMessage(kind="busy", text="Reloading session resources..."))
+    try:
+        await ctx.conductor.navigate_tree(leaf)
+        ctx.set_status(info("Reloaded session resources."))
+    except Exception:
+        ctx.set_status(warn("Could not reload session resources."))
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Leaving (/quit, /exit)
+# ---------------------------------------------------------------------------
+
+
+async def _run_quit(ctx: SlashContext) -> SlashOutcome:
+    """Ask the host process to leave the interactive console."""
+    ctx.request_exit()
+    return HANDLED
+
+
+async def _run_exit(ctx: SlashContext) -> SlashOutcome:
+    """Alternate token for leaving the interactive console."""
+    ctx.request_exit()
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# The group, in listing order
+# ---------------------------------------------------------------------------
+
+#: The transcript / session-control group, in listing order. Appended into
+#: the slash registry by the catalog integrator; this module owns only the
+#: rows, never the wiring.
+transcript_commands: list[SlashCommand] = [
+    SlashCommand(
+        name="clear",
+        summary="Clear the conversation and start a new session",
+        run=_run_clear,
+        aliases=("reset",),
+    ),
+    SlashCommand(
+        name="new",
+        summary="Start a fresh session",
+        run=_run_new,
+    ),
+    SlashCommand(
+        name="summarize-context",
+        summary="Condense the conversation context",
+        run=_run_compact,
+        aliases=("condense", "compact"),
+        takes_args=True,
+    ),
+    SlashCommand(
+        name="resume",
+        summary="Resume a persisted session",
+        run=_run_resume,
+        aliases=("sessions",),
+    ),
+    SlashCommand(
+        name="session",
+        summary="Show live session statistics (ids, counts, tokens, cost)",
+        run=_run_session,
+    ),
+    SlashCommand(
+        name="branch",
+        summary="Branch the transcript from a prior turn",
+        run=_run_fork,
+        aliases=("fork",),
+    ),
+    SlashCommand(
+        name="timeline",
+        summary="Navigate the transcript tree",
+        run=_run_tree,
+        aliases=("tree",),
+    ),
+    SlashCommand(
+        name="name",
+        summary="Name the session, or show the current name",
+        run=_run_name,
+        takes_args=True,
+    ),
+    SlashCommand(
+        name="reload",
+        summary="Reload session resources",
+        run=_run_reload,
+    ),
+    SlashCommand(
+        name="quit",
+        summary="Leave the interactive console",
+        run=_run_quit,
+    ),
+    SlashCommand(
+        name="exit",
+        summary="Leave the interactive console",
+        run=_run_exit,
+    ),
+]