otto-cli-agent 0.1.0__py3-none-any.whl

agent/cli/chat.py

@@ -0,0 +1,309 @@
+"""The interactive shell: `otto chat`.
+
+Every turn goes through the pipeline (agent/pipeline/ -- the router/
+planner/solver/summarizer/finder/evaluator graph that replaced the
+orchestrator/worker/evaluate/subtask_consensus/synthesize swarm on
+2026-09-10, which had itself replaced the Phase 11B code hive on
+2026-09-09). There is no `agents` concept anymore -- one router dispatch,
+one specialist, one evaluator, per round -- so there is nothing to size or
+fix for a session; see agent/pipeline/nodes.py's module docstring for the
+design discussion behind the swap.
+
+Mid-run questions (2026-09-10, same day, nodes.py's seventh refinement):
+`_run_turn` used to be a single `for update in run_pipeline_stream(...)`
+loop. A run can now pause partway through (an `{"__ask__": ...}` event,
+not the usual `{"__final__": ...}`) when a specialist or the evaluator
+gets stuck on something only the person can answer -- `_run_turn` is a
+`while` loop around that same `for` now, so it can render the question,
+collect an answer with `_ask_user`, and keep going via
+`resume_pipeline_stream()` for as long as the run keeps asking.
+
+A line that moves (2026-09-12, design call: "optimize latency and steps,
+and improve the tui"): the graph streams one update per NODE, and `agent`
+is a node that spends every model call and every tool call inside itself.
+Measured across the twenty golden items, that is 828 seconds of wall time,
+96% of it inside model requests, with nothing printed in the middle of any
+of them -- the longest item ran 131 seconds against a still terminal.
+`_run_turn` now binds agent/pipeline/progress.py for the length of the
+turn and keeps one transient Rich status line alive underneath it, saying
+what the run is doing and how long it has been doing it. Ctrl-C sets the
+same seam's cancel Event rather than killing the process, so a turn started
+by mistake ends within one model call instead of having to be waited out.
+
+Bounded conversation memory (2026-09-10, same day, Phase 2 of
+docs/design/tiered-memory.md): `_run_turn` used to read `s.history[:-1]` --
+an unbounded, ever-growing raw list `chat()` appended this turn's own
+HumanMessage onto just before calling `_run_turn`, then appended the reply
+onto after. `Session` now keeps that history in a bounded
+`agent.memory.queue.TieredQueue` instead (agent/cli/shell.py); `_run_turn`
+builds its own `HumanMessage(text)` locally rather than reading it back off
+`s.history`, asks `s.history_for_graph()` for this turn's bounded
+`(history, memory_context)`, and records the finished turn with
+`s.record_turn()` once it has both halves -- `chat()`'s own loop no longer
+touches history at all.
+"""
+
+import threading
+import time
+from collections import Counter
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from langchain_core.messages import AIMessage, HumanMessage
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from agent.cli.output import save_final
+from agent.cli.shell import (
+    Session, build_prompt_session, describe_workspace, dispatch, render_transcript,
+    render_update, resolve_workspace,
+)
+from agent.cli.ui import err, out
+from agent.pipeline.progress import Cancelled, Progress, bind_progress
+from agent.pipeline.run import resume_pipeline_stream, run_pipeline_stream
+from agent.pipeline.state import AgentState
+
+
+def _ask_user(prompt_session, question: str, choices: list[str]) -> str:
+    """Block on the person's answer to a mid-run `{"__ask__": ...}` event --
+    print the question, list any choices as a picked-by-number menu
+    (typing the number OR just typing free text both work; empty/Ctrl-C
+    falls back to open text next time), and always accept free text too
+    (the "multi choice + text bar" UX design call, nodes.py's module
+    docstring, seventh refinement -- the REPL's own version of it: no text
+    bar widget here, but the same two ways to answer).
+    """
+    out.print(Panel(Markdown(question), title="[warn]otto is asking[/]", border_style="warn"))
+    if choices:
+        for i, choice in enumerate(choices, start=1):
+            err.print(f"[muted]{i}.[/] {choice}")
+        err.print("[muted]pick a number, or just type your own answer[/]")
+    while True:
+        try:
+            reply = prompt_session.prompt("your answer> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            return ""
+        if not reply:
+            continue
+        if choices and reply.isdigit() and 1 <= int(reply) <= len(choices):
+            return choices[int(reply) - 1]
+        return reply
+
+
+class _Line:
+    """One transient status line under a turn in flight.
+
+    Rich's `Console.status` already draws a spinner that clears itself, so
+    this is only the bookkeeping: what the run last reported, and a clock
+    that keeps moving through a ten-second model call that reports nothing
+    while it runs.
+
+    Every method here runs on the graph's own thread, which for the REPL is
+    the main thread -- the same one Rich is drawing from -- so there is
+    nothing to marshal and no lock to take.
+    """
+
+    def __init__(self, status) -> None:
+        self._status = status
+        self._started = time.monotonic()
+        self.phase = "reading your message"
+        self.model = ""
+        self.tool = ""
+        self.calls = 0
+
+    def __call__(self, update: Progress) -> None:
+        self.calls = update.calls or self.calls
+        if update.kind == "call_start":
+            self.model, self.tool = update.text, ""
+            self.phase = self.phase or "thinking"
+        elif update.kind == "phase":
+            self.phase, self.tool = update.text, ""
+        elif update.kind == "tool":
+            target = (update.detail or {}).get("target", "")
+            self.tool = f"{update.text} {target}".strip()
+        else:
+            # A streamed partial. Nothing to draw for it here -- the REPL
+            # prints the settled answer as one Markdown panel, and redrawing
+            # a growing block above a live prompt is what Rich's own docs
+            # warn against. Still worth the clock tick.
+            pass
+        self.draw()
+
+    def clock(self) -> str:
+        elapsed = int(time.monotonic() - self._started)
+        return f"{elapsed // 60}:{elapsed % 60:02d}"
+
+    def draw(self) -> None:
+        bits = [self.phase or "thinking"]
+        if self.tool:
+            bits.append(f"[chosen]{self.tool}[/]")
+        if self.model:
+            bits.append(f"[muted]{self.model}[/]")
+        if self.calls:
+            bits.append(f"[muted]{self.calls} calls[/]")
+        bits.append(f"[muted]{self.clock()}[/]")
+        bits.append("[muted]ctrl-c to stop[/]")
+        self._status.update(" · ".join(bits))
+
+
+def _run_turn(s: Session, text: str, prompt_session) -> None:
+    """One turn, under a live status line and a cancel key.
+
+    Ctrl-C inside a turn ends the turn, not the session. The REPL runs the
+    graph on the main thread, so an interrupt lands inside whatever model
+    call is in flight and there is nothing to cooperate with -- the cancel
+    Event is still set on the way out, because a run can be several frames
+    deep and the next `_call` must not spend again while the stack unwinds.
+    Ctrl-C at the prompt still exits, which is where a person means it.
+    """
+    cancel = threading.Event()
+    stopped = False
+    with err.status("", spinner="dots") as status:
+        line = _Line(status)
+        line.draw()
+        # Nothing reports anything during a ten-second model call, so the
+        # clock has to move on its own or the line reads as a hung process.
+        ticking = threading.Event()
+        clock = threading.Thread(target=_keep_time, args=(line, ticking), daemon=True)
+        clock.start()
+        try:
+            with bind_progress(line, cancel=cancel):
+                _drive_turn(s, text, prompt_session)
+        except (Cancelled, KeyboardInterrupt):
+            cancel.set()
+            stopped = True
+        finally:
+            ticking.set()
+            clock.join(timeout=2.0)
+    if stopped:
+        err.print("[warn]stopped[/]")
+    err.print(f"[muted]{line.calls} model calls · {line.clock()}[/]")
+
+
+def _keep_time(line: "_Line", done: threading.Event) -> None:
+    """Redraw the status line once a second until the turn ends.
+
+    A thread rather than a signal or an async task: the REPL has no event
+    loop of its own, and Rich's Live is already safe to update from another
+    thread.
+    """
+    while not done.wait(1.0):
+        line.draw()
+
+
+def _drive_turn(s: Session, text: str, prompt_session) -> None:
+    tally: Counter = Counter()
+    final: AgentState | None = None
+    human_message = HumanMessage(text)
+    # Bounded, not the raw ever-growing list -- module docstring. `history`
+    # is however many recent turns still fit verbatim; `memory_context` is
+    # whatever's older than that, already compacted (agent/memory/queue.py).
+    history, memory_context = s.history_for_graph()
+
+    stream = run_pipeline_stream(
+        text, session_id=s.session_id, history=history, memory_context=memory_context,
+        workspace=s.workspace_arg(),
+    )
+    while stream is not None:
+        next_stream = None
+        for update in stream:
+            if "__ask__" in update:
+                ask = update["__ask__"]
+                answer = _ask_user(prompt_session, ask["question"], ask["choices"])
+                out.print(f"[bold]you[/] {answer}")
+                # Breaking out leaves this generator suspended at its yield,
+                # INSIDE bind_budget/bind_store/bind_workspace, so their
+                # contextvar tokens are reset whenever the GC happens to get
+                # to it -- from whatever context is running then, which is not
+                # the one that set them. close() unwinds it here, now, on this
+                # thread, which is the only place the resets are valid.
+                stream.close()
+                next_stream = resume_pipeline_stream(
+                    answer, thread_id=ask["thread_id"], session_id=s.session_id,
+                    workspace=s.workspace_arg(),
+                )
+                break
+            if "__final__" in update:
+                final = update["__final__"]
+                s.trace_id = update.get("__trace_id__")
+                continue
+
+            node, delta = next(iter(update.items()))
+            render_update(node, delta, tally)
+        stream = next_stream
+
+    if final is not None:
+        raw_output = (final.get("final_output") or "").strip()
+        code = raw_output or "*(no output produced)*"
+        out.print(Panel(Markdown(code), title="[spec]final[/]", border_style="ok"))
+        s.record_turn(human_message, AIMessage(code) if raw_output else None)
+        if raw_output:
+            # On disk, not just on screen -- selecting a Rich panel's text
+            # out of a live terminal mangles box-drawing borders and wrapped
+            # lines (13.4's bug hunt). A plain file sidesteps that.
+            path = save_final(s.session_id, s.turn, raw_output, None)
+            err.print(f"[muted]saved to {path}[/]")
+
+
+WORKSPACE_HELP = (
+    "Directory otto's file tools may read and write. Defaults to the current "
+    "directory. See agent/pipeline/workspace.py for what this grants."
+)
+NO_WORKSPACE_HELP = "Give otto no file access at all. Wins over --workspace."
+RESUME_HELP = (
+    "Pick a saved session back up: its id, a unique prefix of it, or 'last'. "
+    "`otto sessions` lists them. Its workspace comes back with it unless "
+    "--workspace/--no-workspace say otherwise."
+)
+
+
+def open_session(ctx_obj, workspace: Optional[Path], no_workspace: bool, resume: Optional[str]) -> Session:
+    """The Session `otto chat` and `otto tui` both start from. Shared so
+    `--resume` means the same thing at both prompts: the saved session, with
+    its saved workspace, unless a workspace flag was given explicitly --
+    which is the one case `resolve_workspace`'s cwd default must NOT win,
+    since a person resuming work on a repository from their home directory
+    did not mean to move it there. Raises LookupError for an unknown ref.
+    """
+    s = Session(ctx=ctx_obj, workspace=resolve_workspace(workspace, no_workspace))
+    if resume is not None:
+        s.load(resume)
+        if workspace is not None or no_workspace:
+            s.workspace = resolve_workspace(workspace, no_workspace)
+    return s
+
+
+def chat(
+    ctx: typer.Context,
+    workspace: Annotated[Optional[Path], typer.Option("--workspace", "-w", help=WORKSPACE_HELP)] = None,
+    no_workspace: Annotated[bool, typer.Option("--no-workspace", help=NO_WORKSPACE_HELP)] = False,
+    resume: Annotated[Optional[str], typer.Option("--resume", "-r", help=RESUME_HELP)] = None,
+) -> None:
+    """Talk to the pipeline."""
+    try:
+        s = open_session(ctx.obj, workspace, no_workspace, resume)
+    except LookupError as exc:
+        err.print(f"[bad]{exc}[/]")
+        raise typer.Exit(1)
+    err.print("[muted]otto:pipeline[/]")
+    err.print(f"[muted]{describe_workspace(s.workspace)}[/]")
+    err.print("[muted]/help for commands[/]")
+    if resume is not None:
+        err.print(f"[muted]resumed {s.session_id[:8]} · {s.title or '(untitled)'} · {s.turn} turn(s)[/]")
+        render_transcript(s)
+
+    prompt_session = build_prompt_session()
+
+    while True:
+        try:
+            text = prompt_session.prompt("you> ")
+        except (EOFError, KeyboardInterrupt):
+            out.print("\n[muted]bye[/]")
+            break
+        if not text.strip():
+            continue
+        if dispatch(s, text):
+            continue
+
+        _run_turn(s, text, prompt_session)

agent/cli/clipboard.py

@@ -0,0 +1,106 @@
+"""Copying text out of the TUI (2026-09-13, design call: "one can copy
+anything from the UI except borders").
+
+Textual already lets a person drag-select across widgets and press ctrl+c;
+what it hands back and where it puts it are the two halves this module owns.
+
+  * `clean()` -- the selection as a person means it. CSS borders are drawn by
+    the compositor and never appear in selected text, but a Rich table's own
+    rules and column bars do. Lines made only of box-drawing are dropped and
+    edge bars are trimmed, so a selection over the doctor table comes out as
+    the words in it.
+  * `copy()` -- two routes at once. OSC 52 (what `App.copy_to_clipboard`
+    writes) works in most terminals and not in macOS Terminal.app; a native
+    command (`pbcopy`, `wl-copy`, `xclip`, `xsel`) works wherever one is
+    installed. Both are tried, and the return value says which landed, so the
+    toast can be honest about it.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+
+__all__ = ["clean", "copy", "native_command", "plain_text_of"]
+
+
+def plain_text_of(content, width: int) -> str:
+    """What a Static is showing, as the plain text a person would read off
+    the screen -- rendered at the widget's width so line breaks match what a
+    selection's coordinates point at. Markup strings and Text are taken as
+    they are; a Rich renderable (Markdown, Table, Group) is rendered."""
+    import io
+
+    from rich.console import Console
+    from rich.text import Text
+
+    if isinstance(content, str):
+        return Text.from_markup(content).plain
+    if isinstance(content, Text):
+        return content.plain
+    buf = io.StringIO()
+    Console(file=buf, width=max(8, width), force_terminal=False, no_color=True,
+            highlight=False, legacy_windows=False).print(content, end="")
+    return buf.getvalue()
+
+_BOX = "─━│┃┄┅┆┇┈┉┊┋┌┍┎┏┐┑┒┓└┕┖┗┘┙┚┛├┝┞┟┠┡┢┣┤┥┦┧┨┩┪┫┬┭┮┯┰┱┲┳┴┵┶┷┸┹┺┻┼┽┾┿╀╁╂╃╄╅╆╇╈╉╊╋╌╍╎╏═║╒╓╔╕╖╗╘╙╚╛╜╝╞╟╠╡╢╣╤╥╦╧╨╩╪╫╬╭╮╯╰╱╲╳╴╵╶╷╸╹╺╻╼╽╾╿"
+_ONLY_BOX = re.compile(rf"^[\s{re.escape(_BOX)}]*$")
+_EDGE_BARS = re.compile(rf"^[{re.escape(_BOX)}]\s?|\s?[{re.escape(_BOX)}]$")
+_INNER_BAR = re.compile(r"\s[│┃║]\s")
+
+
+def clean(text: str) -> str:
+    """Selected text without any box-drawing: rule-only lines go, edge bars
+    go, and a column bar between cells becomes two spaces."""
+    kept: list[str] = []
+    for line in (text or "").splitlines():
+        if _ONLY_BOX.match(line):
+            continue
+        line = _EDGE_BARS.sub("", line)
+        line = _INNER_BAR.sub("  ", line)
+        kept.append(line.rstrip())
+    while kept and not kept[0].strip():
+        kept.pop(0)
+    while kept and not kept[-1].strip():
+        kept.pop()
+    return "\n".join(kept)
+
+
+_NATIVE: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("pbcopy", ()),
+    ("wl-copy", ()),
+    ("xclip", ("-selection", "clipboard")),
+    ("xsel", ("--clipboard", "--input")),
+)
+
+
+def native_command() -> list[str] | None:
+    """The first clipboard command installed here, or None."""
+    for name, args in _NATIVE:
+        path = shutil.which(name)
+        if path:
+            return [path, *args]
+    return None
+
+
+def copy(app, text: str) -> str:
+    """Put `text` on the clipboard by every route available. Returns a short
+    description of what worked, for the toast."""
+    routes: list[str] = []
+    try:
+        app.copy_to_clipboard(text)
+        routes.append("OSC 52")
+    except Exception:
+        pass
+    command = native_command()
+    if command:
+        try:
+            subprocess.run(command, input=text.encode("utf-8"), check=True, timeout=3,
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            routes.append(command[0].rsplit("/", 1)[-1])
+        except (OSError, subprocess.SubprocessError):
+            pass
+    if not routes:
+        return "no clipboard route worked"
+    note = "" if len(routes) > 1 or routes != ["OSC 52"] else " (macOS Terminal.app ignores this; iTerm, Ghostty, kitty, WezTerm honour it)"
+    return "via " + " + ".join(routes) + note

agent/cli/context.py

@@ -0,0 +1,56 @@
+import atexit
+import os
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from agent.router.router import Router
+
+
+def _release() -> str:
+    """Installed version, or 'dev' outside an installed environment."""
+    try:
+        return version("otto-cli-agent")
+    except PackageNotFoundError:
+        return "dev"
+
+
+class AppContext:
+    def __init__(self, *, strict: bool = False) -> None:
+        self.strict = strict
+        self._router: Router | None = None
+        self._handler: Any | None = None
+
+    @property
+    def router(self) -> Router:
+        if self._router is None:
+            self._router = Router(strict=self.strict)
+        return self._router
+    
+    @property
+    def handler(self):
+        if self._handler is None:
+            from langfuse import get_client
+            from langfuse.langchain import CallbackHandler
+
+            # Groups traces by build in the Langfuse UI. setdefault, so a
+            # deploy or CI run can override with a commit SHA:
+            #   LANGFUSE_RELEASE=$GITHUB_SHA otto chat
+            os.environ.setdefault("LANGFUSE_RELEASE", _release())
+
+            self._handler = CallbackHandler()
+            atexit.register(get_client().flush)
+        return self._handler
+
+    @property
+    def client(self):
+        """The Langfuse client itself, for the things a callback cannot do.
+
+        Scores are the main one: the handler reports what happened, but a
+        score is a judgement about it, so it is always an explicit call.
+        Reading `handler` first is deliberate -- that is what sets
+        LANGFUSE_RELEASE and registers the flush at exit.
+        """
+        self.handler
+        from langfuse import get_client
+
+        return get_client()

agent/cli/doctor.py

@@ -0,0 +1,60 @@
+import typer
+from rich.table import Table
+from rich.panel import Panel
+from rich import box
+
+from agent.cli.ui import err, out
+from agent.router.llm_provider import health_report
+from agent.router.llm_provider.base import HealthReport, ProviderStatus
+from agent.router.router import Router
+
+STYLE = {ProviderStatus.OK: "ok", ProviderStatus.NO_KEY: "muted",
+         ProviderStatus.AUTH_FAILED: "bad",
+         ProviderStatus.UNREACHABLE: "warn", ProviderStatus.ERROR: "bad"}
+
+
+def health_table(reports: list[HealthReport]) -> Table:
+    t = Table(box=box.SIMPLE, header_style="muted")
+    t.add_column("provider")
+    t.add_column("status")
+    t.add_column("models", justify="right")
+    t.add_column("detail", style="muted", overflow="fold")
+    for r in reports:
+        t.add_row(
+            r.provider,
+            f"[{STYLE[r.status]}]{r.status.value}[/]",
+            str(r.model_count or ""),
+            r.detail
+        )
+    return t
+
+
+def router_view(router: Router) -> Panel:
+    t = Table(box=None, show_header=False, pad_edge=False)
+    t.add_column(style="muted")
+    t.add_column()
+    state = "[ok]configured[/]" if router.ready() else "[bad]missing -- set INCEPTION_API_KEY (otto tui -> Setup)[/]"
+    t.add_row("required", f"{router.REQUIRED}  {state}")
+    # Every configured provider is usable now -- there is no single "secondary"
+    # seat any more (agent/router/router.py's own docstring for why).
+    optional = tuple(p for p in router.usable() if p != router.REQUIRED)
+    t.add_row("also configured", ", ".join(optional) if optional else "[muted]none[/]")
+    return Panel(t, box=box.ROUNDED, border_style="muted", expand=False)
+
+
+def doctor(ctx: typer.Context) -> None:
+    """Check every provider with a real call, and show the routing policy."""
+
+    with err.status("contacting providers"):
+        reports = health_report()
+
+    out.print(health_table(reports))
+
+    # The table above is the diagnosis; the panel below is the conclusion.
+    # A Router constructs without Inception now (agent/router/router.py), so
+    # the missing-required case is a row in that panel and a non-zero exit,
+    # not an exception that replaces the finding the table built toward.
+    router = ctx.obj.router
+    out.print(router_view(router))
+    if not router.ready():
+        raise typer.Exit(2)

agent/cli/errors.py

@@ -0,0 +1,58 @@
+"""Turn provider-layer exceptions into CLI errors.
+
+The router raises `AuthError` from `Router.require_ready()` (called by
+`resolve()` and the pipeline's entry points) and `NoViableRoute` /
+`RoutingDegraded` from `resolve()`. Those are the right
+exceptions for a library, but a CLI must never answer a user with a traceback:
+it buries the diagnosis and trains people to ignore stack traces.
+
+`friendly` is applied once per command at registration, so a new command can
+never forget it.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import typer
+
+from agent.cli.ui import err
+from agent.router.llm_provider.base import AuthError, ProviderError
+from agent.router.router import NoViableRoute, RoutingDegraded
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+#: Exit codes, so a shell script can tell these apart.
+EXIT_NO_KEY = 2
+EXIT_NO_ROUTE = 3
+EXIT_DEGRADED = 4
+EXIT_PROVIDER = 5
+
+
+def friendly(command: F) -> F:
+    """Render expected failures as CLI errors instead of tracebacks."""
+
+    @functools.wraps(command)          # keeps the signature Typer introspects
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return command(*args, **kwargs)
+        except AuthError as exc:
+            err.print(f"[bad]{exc}[/]")
+            err.print("[muted]run `otto doctor` to see which providers are configured[/]")
+            raise typer.Exit(EXIT_NO_KEY) from None
+        except NoViableRoute as exc:
+            err.print(f"[bad]{exc}[/]")
+            raise typer.Exit(EXIT_NO_ROUTE) from None
+        except RoutingDegraded as exc:
+            err.print(f"[warn]{exc}[/]")
+            err.print("[muted]drop --strict to allow the fallback[/]")
+            raise typer.Exit(EXIT_DEGRADED) from None
+        except ProviderError as exc:
+            # Anything else the provider layer defines: still ours, still not
+            # a traceback the user should have to read.
+            err.print(f"[bad]{type(exc).__name__}: {exc}[/]")
+            raise typer.Exit(EXIT_PROVIDER) from None
+
+    return wrapper  # type: ignore[return-value]