Peekaboo MCP

--- summary: 'Document the minimal interactive chat loop for peekaboo agent' read_when: - 'planning work related to the agent chat loop' - 'debugging or extending the interactive agent shell' --- # Minimal Agent Chat Mode This document captures the initial design for a dependency-free interactive chat shell built on top of `peekaboo agent`. The goal is to let operators hold a live conversation—enter a prompt, let the agent act, then immediately enter another prompt—without reinventing the retired TermKit UI. ## How You Enter Chat Mode - `peekaboo agent "<task>"` keeps the existing single-shot behavior. - Running `peekaboo agent` **without** a task drops you into chat mode automatically when stdout is an interactive TTY. - In non-interactive environments the command just prints the chat help menu and exits so scripted agents know what to send next. - `--chat` always forces the interactive loop (even when piped) and doubles as the discoverable/explicit switch for documentation and tooling. - If you pass a task alongside `--chat`, that text becomes the first turn before the prompt reappears. ## Command Surface - Introduce a `--chat` flag on `peekaboo agent`. - When present, the command enters an interactive loop instead of executing once and exiting. - All existing options (`--model`, `--max-steps`, `--resume-session`, `--no-cache`, etc.) still apply at launch; their values remain in effect for the entire chat session. ## Session Lifecycle 1. Starting the chat loop either resumes an explicit session (`--resume-session <id>`), resumes the most recent session when `--resume` is supplied, or creates a fresh one. 2. The resolved session ID is reused for every turn so the agent maintains context. 3. Exiting the loop leaves the session in the cache so the standard `agent` command can resume it later. ## Control Flow ```text polter peekaboo -- agent --chat → print header (model, session ID, exit instructions) loop { prompt with `chat> ` read a line from stdin (skip empty lines) run the existing agent pipeline with that line as the task text display the usual transcript (enhanced/compact/minimal) until completion } ``` - `readLine()` is sufficient for v1; pasted multi-line text will arrive line-by-line but still accumulate because each line triggers a run. - When the loop opens it prints “Type /help for chat commands” and immediately dumps the `/help` menu so operators know what to expect. - `/help` can be entered at any time to reprint the built-in menu. - End-of-file (Ctrl+D) or a SIGINT while idle breaks out of the loop. Ctrl+C while a task is running cancels that turn and returns to the prompt. - Press `Esc` during an active turn to cancel the in-flight run immediately and return to the prompt. ## Prompt & Output - Display a simple ASCII prompt: `chat> `. - After each turn, optionally print a one-line summary (model, duration, tool count) before reprinting the prompt. This avoids repeating the full banner every time. - `Type /help …` banner plus the help menu are shown automatically the moment interactive mode starts, even before the first task (or immediately after running the optional seeded task supplied with `--chat`). - Reuse the existing output-mode machinery so enhanced/compact/minimal renderings continue to work automatically. ## Error Handling - Failed executions (missing credentials, tool errors, etc.) bubble through the current `displayResult` / error printers so behavior matches the one-shot command. - If the agent reports a fatal error, the loop stays alive unless the error indicates initialization failure (e.g., no provider configured), in which case we exit immediately. ## Exit Semantics - Ctrl+C while idle → exit the loop cleanly. - Ctrl+C while running → cancel the active task and return to the prompt (press again to exit entirely if desired). - Ctrl+D (EOF) → exit after the current prompt. - Non-interactive invocations without `--chat` just print the help text once and exit. ## Future Enhancements (Out of Scope for Minimal Version) - Slash commands (`/model`, `/stats`, `/clear`). - Multi-line paste blocks (triple quotes) or heredoc-style delimiters. - Richer terminal UI (colors in the prompt, live tool streaming columns, etc.). - Dedicated transcript panes or scrolling history. The minimal design above provides a usable chat workflow immediately while keeping the implementation lean enough to land incrementally.