kotools 2026.7.14__py3-none-any.whl

ko/__init__.py

@@ -0,0 +1 @@
+__version__ = "2026.7.14"

ko/_cli_shared.py

@@ -0,0 +1,81 @@
+"""Shared CLI root app and cross-group helper functions."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import NoReturn
+
+import typer
+
+# Last error label from _die() — picked up by cli.main()'s logging so failures via the
+# normal _die() path populate the `error` field. Only the programmer-set `code` label is
+# stored (never the message, which may contain user queries/URLs).
+_last_error: str | None = None
+
+# The root Typer app — imported by all group modules so they can self-register.
+app = typer.Typer(
+    help="ko — Ko's opinionated CLI: web/papers (exa, fetch, arxiv, hf, papers, hn), "
+    "Google (gsheets, gdocs, cal, gmail), llm/agents, publish, and more. `ko doctor` for setup.",
+    no_args_is_help=True,
+    # Agents drive ko over bash: a clean one-line error on stderr + exit 1 is parseable;
+    # Typer's default colorized multi-frame traceback box is not. We catch expected errors
+    # in each command and emit them via _die(); this kills the pretty-traceback fallback.
+    pretty_exceptions_enable=False,
+)
+
+
+def _emit_json(items: list) -> None:
+    """Shared --json path: list of dataclasses -> one JSON array on stdout."""
+    typer.echo(json.dumps([asdict(i) for i in items], default=str))
+
+
+def _die(
+    msg: str, *, as_json: bool = False, code: str = "error", exit_code: int | None = None
+) -> NoReturn:
+    """Error exit: a JSON error object to stderr under --json, else plain text.
+    Exit code follows AGENTS.md — `code="usage"` → 2, everything else → 1 (override with
+    exit_code). Keeps stdout clean so a downstream `... | jq` never sees a half-message.
+    Records the error code label in `_last_error` so cli.main() can populate the log's
+    `error` field without capturing user-data from the message."""
+    global _last_error
+    _last_error = code
+    if as_json:
+        typer.echo(json.dumps({"error": msg, "code": code}), err=True)
+    else:
+        typer.echo(msg, err=True)
+    if exit_code is None:
+        exit_code = 2 if code == "usage" else 1
+    raise typer.Exit(exit_code)
+
+
+def _no_results(note: str, as_json: bool) -> NoReturn:
+    """Empty-result exit (exit 0, not an error): under --json emit `[]` to stdout so the pipe
+    stays valid JSON; the human-readable note always goes to stderr, never stdout."""
+    if as_json:
+        typer.echo("[]")
+    typer.echo(note, err=True)
+    raise typer.Exit(0)
+
+
+def _tsv_cell(value) -> str:
+    """One value rendered safe for a single TSV field: an embedded tab or newline would
+    otherwise split the field / spill the row onto the next line (silently mis-shaping the
+    output an agent parses with `cut -f`). Tabs → `\\t`, newlines → `\\n`; content preserved,
+    one row stays one line. `None` → ''."""
+    if value is None:
+        return ""
+    s = str(value).replace("\r\n", "\n").replace("\r", "\n")
+    return s.replace("\t", "\\t").replace("\n", "\\n")
+
+
+def _fmt_day(iso: str | None) -> str:
+    """An ISO date/datetime string -> human '22 Jun 2018' (day only, no time); '' if missing."""
+    if not iso:
+        return ""
+    from datetime import datetime
+
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00")).strftime("%d %b %Y")
+    except ValueError:
+        return iso[:10]  # fall back to the date portion

ko/agents/__init__.py

@@ -0,0 +1,27 @@
+from ko.agents.ai import agent as ai_agent
+from ko.agents.ai import repl as ai_repl
+from ko.agents.ai import run as ai_run
+from ko.agents.repo import agent as repo_agent
+from ko.agents.repo import repl as repo_repl
+from ko.agents.repo import run as repo_run
+from ko.agents.research import agent as research_agent
+from ko.agents.research import repl as research_repl
+from ko.agents.research import run as research_run
+from ko.agents.tv import agent as tv_agent
+from ko.agents.tv import repl as tv_repl
+from ko.agents.tv import run as tv_run
+
+__all__ = [
+    "ai_agent",
+    "ai_run",
+    "ai_repl",
+    "repo_agent",
+    "repo_run",
+    "repo_repl",
+    "research_agent",
+    "research_run",
+    "research_repl",
+    "tv_agent",
+    "tv_run",
+    "tv_repl",
+]

ko/agents/_files.py

@@ -0,0 +1,200 @@
+"""Read-only file tools for the repo-explorer agent — confined to ~/code.
+
+Read-only **by construction**: no write/edit tools exist at all — stronger than
+guarding writes (nothing to misuse, nothing in the model's tool list to waste
+tokens on). Containment ported from thinker's `resolve_in` (resolve BOTH sides,
+then `is_relative_to` — symlinks resolved before the check, the same TOCTTOU
+ordering pydantic-ai-harness uses). Search shells out to ripgrep.
+
+Every tool returns small, capped output (a cheap model drowns in dumps):
+line-capped reads with continuation pointers, result-capped grep/find,
+binary detection, hidden dirs (.git etc.) skipped everywhere.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from pydantic_ai import ModelRetry
+
+from ko import config
+
+MAX_READ_LINES = 400
+MAX_READ_BYTES = 1_000_000  # refuse whole-file reads beyond this — grep instead
+MAX_LINE_CHARS = 500  # a minified one-liner must not blow the context
+MAX_GREP_LINES = 100
+MAX_LIST_ENTRIES = 200
+MAX_FIND_RESULTS = 200
+OVERVIEW_HEAD_LINES = 150  # refs/CLAUDE.md head injected into instructions
+
+
+def code_root() -> Path:
+    """The explorable root: KO_CODE_DIR → `[code] dir` in config.toml → ~/code."""
+    return Path(
+        config.setting("KO_CODE_DIR", "code", "dir", str(Path.home() / "code"))
+    ).expanduser()
+
+
+def _resolve(path: str) -> Path:
+    """THE containment guard — every path-taking tool routes through here.
+
+    Accepts paths relative to the code root ('refs/llm/setup.py') or absolute
+    ones that land inside it. Both sides are fully resolved (symlinks followed)
+    BEFORE the containment check, so a symlink pointing outside can't escape."""
+    root = code_root().resolve()
+    p = Path(path).expanduser()
+    full = (p if p.is_absolute() else root / p).resolve()
+    if not full.is_relative_to(root):
+        raise ModelRetry(
+            f"'{path}' is outside {root} — this agent only reads inside it. "
+            f"Use paths relative to that root, e.g. 'everx' or 'refs/pydantic-ai'."
+        )
+    if any(part.startswith(".") for part in full.relative_to(root).parts):
+        raise ModelRetry(
+            f"'{path}' is under a hidden directory (.git etc.) — those are off-limits."
+        )
+    return full
+
+
+def list_dir(path: str = ".") -> str:
+    """Entries in a directory: dirs first with a trailing '/', file sizes shown.
+    Hidden entries skipped; capped."""
+    d = _resolve(path)
+    if not d.is_dir():
+        raise ModelRetry(f"'{path}' is not a directory. Try read_file, or list its parent.")
+    entries = sorted(
+        (p for p in d.iterdir() if not p.name.startswith(".")),
+        key=lambda p: (p.is_file(), p.name.lower()),
+    )
+    def _entry(e: Path) -> str:
+        if e.is_dir():
+            return f"{e.name}/"
+        try:
+            size = e.stat().st_size
+        except OSError:  # broken symlink — stat follows the (dead) target
+            return f"{e.name}  (broken symlink)"
+        # ≈tokens (bytes/4) so the model can judge "read it whole" vs "grep first"
+        return f"{e.name}  ({size:,}B ≈{size // 4:,} tok)"
+
+    lines = [_entry(e) for e in entries[:MAX_LIST_ENTRIES]]
+    if len(entries) > MAX_LIST_ENTRIES:
+        lines.append(f"[+{len(entries) - MAX_LIST_ENTRIES} more entries]")
+    return "\n".join(lines) or "(empty)"
+
+
+def read_file(path: str, offset: int = 0, limit: int = MAX_READ_LINES) -> str:
+    """A file's text with line numbers (cite as file:line). Line-capped; call again
+    with `offset` to continue. Binary files return a placeholder, missing ones a
+    listing of what IS there (thinker's self-correction pattern)."""
+    f = _resolve(path)
+    if not f.is_file():
+        parent = f.parent
+        hint = list_dir(str(parent.relative_to(code_root().resolve()) or ".")) if parent.is_dir() else "(parent missing too)"
+        raise ModelRetry(f"'{path}' does not exist. In its directory:\n{hint}")
+    size = f.stat().st_size
+    if size > MAX_READ_BYTES:
+        return (
+            f"(file is {size:,} bytes ≈{size // 4:,} tokens — too large to read whole; "
+            f"grep it to locate the relevant lines instead)"
+        )
+    raw = f.read_bytes()
+    if b"\x00" in raw[:8192]:
+        return f"(binary file, {len(raw):,} bytes — not readable as text)"
+    lines = raw.decode("utf-8", errors="replace").splitlines()
+    window = [
+        ln if len(ln) <= MAX_LINE_CHARS else ln[:MAX_LINE_CHARS] + "…[line truncated]"
+        for ln in lines[offset : offset + limit]
+    ]
+    out = [f"{offset + i + 1}: {ln}" for i, ln in enumerate(window)]
+    remaining = len(lines) - offset - len(window)  # window == the emitted slice
+    if remaining > 0:
+        out.append(f"[+{remaining} more lines — call read_file(path, offset={offset + limit})]")
+    return "\n".join(out) or "(empty file)"
+
+
+def grep(
+    pattern: str,
+    path: str = ".",
+    glob: str | None = None,
+    limit: int = MAX_GREP_LINES,
+    context: int = 0,
+    files_only: bool = False,
+) -> str:
+    """Regex search file CONTENTS via ripgrep (smart-case, respects .gitignore).
+    Thin rg passthrough behind the containment guard — params mirror Claude Code's
+    Grep (glob filter, context lines, files-with-matches mode) so models get the
+    shapes they were trained on. `file:line: text`, at most `limit` matches."""
+    d = _resolve(path)
+    limit = max(1, min(limit, 2 * MAX_GREP_LINES))
+    if files_only:
+        cmd = ["rg", "-l", "-S"]
+    else:
+        cmd = ["rg", "-n", "--no-heading", "-S", "--max-columns", "300"]
+        if context:
+            cmd += ["-C", str(min(context, 10))]
+    if glob:
+        cmd += ["-g", glob]
+    cmd += [pattern, str(d)]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    except FileNotFoundError:
+        raise ModelRetry("ripgrep (rg) is not installed on this machine — use find_files + read_file instead.")
+    except subprocess.TimeoutExpired:
+        raise ModelRetry("search timed out (30s) — scope to a subdirectory or add a glob.")
+    if proc.returncode not in (0, 1):  # 1 = no matches; anything else is a real error
+        raise ModelRetry(f"search failed: {proc.stderr.strip()[:200]}")
+    root = str(code_root().resolve()) + "/"
+    lines = [ln.replace(root, "", 1) for ln in proc.stdout.splitlines()]
+    if not lines:
+        return "(no matches)"
+    out = lines[:limit]
+    if len(lines) > limit:
+        out.append(
+            f"[+{len(lines) - limit} more matches — scope to a subdirectory, add a glob, or tighten the pattern]"
+        )
+    return "\n".join(out)
+
+
+def glob(pattern: str, path: str = ".") -> str:
+    """Find files by NAME glob pattern (e.g. '*.py', '**/test_*.ts') via `rg --files`
+    (respects .gitignore; hidden dirs like .git/.venv and installed packages are
+    excluded). Capped; paths relative to the code root. (Named/shaped like Claude
+    Code's Glob tool — the signature models are trained on.)"""
+    d = _resolve(path)
+    try:
+        proc = subprocess.run(
+            ["rg", "--files", "-g", pattern, str(d)], capture_output=True, text=True, timeout=30
+        )
+    except FileNotFoundError:
+        raise ModelRetry("ripgrep (rg) is not installed — use list_dir to navigate instead.")
+    except subprocess.TimeoutExpired:
+        raise ModelRetry("find timed out (30s) — scope to a subdirectory.")
+    if proc.returncode not in (0, 1):
+        raise ModelRetry(f"find failed: {proc.stderr.strip()[:200]}")
+    root = str(code_root().resolve()) + "/"
+    lines = [ln.replace(root, "", 1) for ln in proc.stdout.splitlines()]
+    if not lines:
+        return "(no files match)"
+    out = lines[:MAX_FIND_RESULTS]
+    if len(lines) > MAX_FIND_RESULTS:
+        out.append(f"[+{len(lines) - MAX_FIND_RESULTS} more — narrow the glob or path]")
+    return "\n".join(out)
+
+
+def refs_overview_head() -> str:
+    """The first OVERVIEW_HEAD_LINES of refs/CLAUDE.md (the curated map of the
+    reference repos + accumulated takeaways), with a pointer to the rest —
+    thinker's memory-head pattern. Injected into the repo agent's instructions."""
+    from ko import refs
+
+    f = refs.claude_md(refs.refs_dir())
+    try:
+        lines = f.read_text().splitlines()
+    except OSError:
+        return "(no refs/CLAUDE.md yet — run `ko refs setup`)"
+    head = lines[:OVERVIEW_HEAD_LINES]
+    if len(lines) > OVERVIEW_HEAD_LINES:
+        rel = f.resolve().relative_to(code_root().resolve())
+        head.append(f"[+{len(lines) - OVERVIEW_HEAD_LINES} more lines — read_file('{rel}')]")
+    return "\n".join(head)

ko/agents/_memory.py

@@ -0,0 +1,170 @@
+"""Per-agent markdown memory — a writable workspace each agent maintains itself.
+
+Design (docs/memory.md "v1 first", researched against thinker/deepagents/hermes):
+each agent gets `~/.local/state/ko/memory/<agent>/` — `memory.md` is the anchor
+(head-injected into instructions every run), and the agent may grow other .md
+notes beside it (read on demand; the injection lists them). One shared
+`~/.config/ko/memory.md` (user preferences / standing context, dotfile-synced)
+is injected into every memory-carrying agent first; v1 keeps it hand-edited.
+
+Guardrails: tools are scoped to the agent's OWN dir, .md files only (this is a
+notes space, not a filesystem); `memory.md` can't be wholesale overwritten —
+append or uniqueness-guarded edit only (thinker's invariant). The pin marker
+(deepagents): lines above `<!-- ko:pin-end -->` always survive injection; the
+tail below is recency-truncated (newest kept), so foundations never age out.
+
+Curation lives in the toolset INSTRUCTIONS, not code — thinker ran 8 months of
+agent-curated memories this way without bloat.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic_ai import ModelRetry
+from pydantic_ai.toolsets import FunctionToolset
+
+from ko.dirs import config_dir, state_dir
+
+MEMORY_FILE = "memory.md"
+PIN_MARKER = "<!-- ko:pin-end -->"
+HEAD_LINES = 200  # max memory lines injected into instructions
+
+
+def memory_dir(agent: str) -> Path:
+    if Path(agent).name != agent or agent.startswith("."):  # factory is public API — keep it honest
+        raise ValueError(f"agent name must be a plain name, got {agent!r}")
+    d = state_dir() / "memory" / agent
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def shared_file() -> Path:
+    return config_dir() / "memory.md"
+
+
+def _resolve_note(agent: str, name: str) -> Path:
+    """Containment for the workspace: the agent's own memory dir is FLAT — plain
+    .md names only (subdir names used to escape into an uncaught FileNotFoundError,
+    and wouldn't show in the injection listing anyway)."""
+    if Path(name).name != name:
+        raise ModelRetry(f"'{name}' — use a plain name like 'memory.md' or 'notes.md' (no folders).")
+    root = memory_dir(agent).resolve()
+    full = (root / name).resolve()
+    if not full.is_relative_to(root):
+        raise ModelRetry(f"'{name}' is outside your memory folder — use plain names like 'memory.md' or 'notes.md'.")
+    if full.suffix.lower() != ".md":
+        raise ModelRetry(f"'{name}' — your memory folder holds markdown only; use a .md name.")
+    return full
+
+
+def _notes(agent: str) -> list[str]:
+    root = memory_dir(agent)
+    return sorted(p.name for p in root.glob("*.md"))
+
+
+def _head(text: str, budget: int = HEAD_LINES, hint: str | None = f"read_note('{MEMORY_FILE}') for all") -> str:
+    """Pin-aware head: pinned lines always included; the tail keeps its NEWEST lines
+    (entries append at the bottom) with a truncation marker pointing at the rest.
+    `hint=None` for files no tool can read back (the shared memory)."""
+    lines = text.splitlines()
+    if len(lines) <= budget:
+        return text
+    if PIN_MARKER in text:
+        cut = next(i for i, ln in enumerate(lines) if PIN_MARKER in ln) + 1
+        pinned, tail = lines[:cut], lines[cut:]
+    else:
+        pinned, tail = [], lines
+    keep = max(budget - len(pinned), 0)
+    dropped = len(tail) - keep
+    if dropped <= 0:  # everything pinned / nothing to drop — no noise marker
+        return text
+    marker = [f"[…{dropped} older lines truncated{' — ' + hint if hint else ''}]"]
+    return "\n".join(pinned + marker + tail[-keep:] if keep else pinned + marker)
+
+
+def instructions_block(agent: str) -> str:
+    """The memory injection for an agent's dynamic instructions: shared memory,
+    then the agent's own memory.md head, then a listing of its other notes."""
+    parts: list[str] = []
+    try:
+        shared = shared_file().read_text(errors="replace").strip()
+        if shared:
+            # hint=None: no tool reads the shared file — a read_note hint would misdirect
+            parts.append(f"## Shared memory (about Ko — {shared_file()})\n\n{_head(shared, hint=None)}")
+    except OSError:
+        pass
+    own = memory_dir(agent) / MEMORY_FILE
+    try:
+        text = own.read_text(errors="replace").strip()
+    except OSError:
+        text = ""
+    parts.append(
+        f"## Your memory ({MEMORY_FILE})\n\n{_head(text) if text else '(empty — you have not saved anything yet)'}"
+    )
+    others = [n for n in _notes(agent) if n != MEMORY_FILE]
+    if others:
+        parts.append("Your other notes (read_note to open): " + ", ".join(others))
+    return "\n\n".join(parts)
+
+
+def memory_toolset(agent: str) -> FunctionToolset:
+    """The write-capable workspace toolset for ONE agent — a factory, not a shared
+    instance (tools close over the agent's own dir)."""
+    ts = FunctionToolset(
+        instructions=(
+            f"Memory: you own the folder behind memory.md (shown above) and may keep other "
+            f".md notes in it. Curation rules — update SLOWLY: save only what will recur; "
+            f"bump dates/counts in-place with edit_note; DELETE stale entries; keep "
+            f"{MEMORY_FILE} under ~100 lines (put durable foundations above the "
+            f"'{PIN_MARKER}' line — they always survive truncation). Topic findings go in "
+            f"your own notes, never in the shared memory."
+        )
+    )
+
+    @ts.tool_plain
+    def read_note(name: str = MEMORY_FILE) -> str:
+        """Read one of your memory-folder notes in full (default: memory.md)."""
+        f = _resolve_note(agent, name)
+        if not f.is_file():
+            have = ", ".join(_notes(agent)) or "(none yet)"
+            raise ModelRetry(f"'{name}' does not exist. Your notes: {have}")
+        return f.read_text()
+
+    @ts.tool_plain
+    def append_memory(text: str) -> str:
+        """Append lines to the BOTTOM of memory.md (newest last — the tail is what
+        survives truncation). For changing existing lines use edit_note."""
+        f = _resolve_note(agent, MEMORY_FILE)
+        with f.open("a") as fh:
+            fh.write(text.rstrip() + "\n")  # every append ends the file with \n — no separator needed
+        return f"appended {len(text.splitlines())} line(s) to {MEMORY_FILE}"
+
+    @ts.tool_plain
+    def write_note(name: str, content: str) -> str:
+        """Create or overwrite one of your notes (NOT memory.md — that anchor only
+        changes via append_memory/edit_note, so it can't be clobbered wholesale)."""
+        f = _resolve_note(agent, name)
+        if f.name.lower() == MEMORY_FILE:  # .lower(): APFS is case-insensitive — 'MEMORY.MD' IS the anchor
+            raise ModelRetry("memory.md can't be overwritten — append_memory or edit_note it.")
+        f.write_text(content.rstrip() + "\n")
+        return f"wrote {len(content.splitlines())} line(s) to {name}"
+
+    @ts.tool_plain
+    def edit_note(old_string: str, new_string: str, name: str = MEMORY_FILE) -> str:
+        """Replace an exact string in a note (default memory.md). `old_string` must
+        occur exactly once — include enough surrounding context to make it unique.
+        Use with new_string='' to delete stale entries."""
+        f = _resolve_note(agent, name)
+        if not f.is_file():
+            raise ModelRetry(f"'{name}' does not exist yet.")
+        text = f.read_text()
+        n = text.count(old_string)
+        if n == 0:
+            raise ModelRetry(f"string not found in {name} — read_note it and retry with the exact text.")
+        if n > 1:
+            raise ModelRetry(f"string occurs {n} times in {name} — add surrounding context to make it unique.")
+        f.write_text(text.replace(old_string, new_string, 1))
+        return "edit applied"
+
+    return ts

ko/agents/_shared.py

@@ -0,0 +1,116 @@
+"""Shared run/stream/repl helpers — generic over any pydantic-ai Agent.
+
+Each ko agent module builds its `Agent` and binds these (`run(agent, prompt, name=...)`),
+so streaming, pipe handling, the REPL loop, model override, and session saving all
+live in one place. Every turn is persisted via `ko.sessions` so any agent gets
+resume + history for free.
+
+`model` is passed per-run (not baked into the Agent) so the `-m` flag actually
+takes effect — the Agent reads its default model at import, before the CLI runs.
+"""
+
+from __future__ import annotations
+
+import readline  # noqa: F401 — enables up-arrow history + line editing in repl
+
+from pydantic_ai import Agent
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+
+from ko import sessions
+from ko.llm import run_cost
+
+_console = Console()
+_err = Console(stderr=True)  # cost notes are notes, not data — stderr keeps pipes clean
+
+
+def _cost_note(messages: list, prior: int = 0) -> None:
+    """Print what the new messages (beyond `prior`) cost — OR actuals when available.
+    markup=False: the note's own [brackets] would otherwise parse as rich tags and
+    silently swallow the whole line."""
+    _err.print(run_cost(messages[prior:]).note, style="dim", markup=False, highlight=False)
+
+
+def _stream(
+    agent: Agent, prompt: str, history: list, model: str | None = None, limits=None
+) -> tuple[str, list]:
+    """Run one turn with live markdown output. Returns (text, full message history).
+
+    v2: run_stream_sync returns the result directly (not a context manager), and
+    stream_text(delta=False) yields the full text so far each tick.
+    """
+    result = agent.run_stream_sync(prompt, message_history=history, model=model, usage_limits=limits)
+    text = ""
+    with Live(console=_console, refresh_per_second=15) as live:
+        for text in result.stream_text():
+            live.update(Markdown(text))
+    return text, result.all_messages()
+
+
+def run(
+    agent: Agent,
+    prompt: str,
+    name: str = "agent",
+    model: str | None = None,
+    resume: str | None = None,
+    limits=None,
+) -> str:
+    """One-shot. Streams pretty markdown to a TTY; plain text when piped. Saves the session.
+
+    `resume` continues a saved session (the prompt becomes its next turn) instead of
+    starting fresh — so `ko a research "follow-up" -r <id>` works as a one-shot continuation.
+    """
+    session_id = resume or sessions.new_id()
+    history = sessions.load(resume) if resume else []
+    if _console.is_terminal:
+        text, messages = _stream(agent, prompt, history, model=model, limits=limits)
+    else:
+        result = agent.run_sync(prompt, message_history=history, model=model, usage_limits=limits)
+        text, messages = result.output, result.all_messages()
+        print(text)
+    _cost_note(messages, prior=len(history))
+    sessions.save(session_id, name, messages)
+    return text
+
+
+def repl(
+    agent: Agent,
+    banner: str = "agent",
+    name: str | None = None,
+    model: str | None = None,
+    resume: str | None = None,
+    limits=None,
+) -> None:
+    """Interactive session; history preserved across turns and saved after each.
+
+    `resume` = a session id to continue an earlier conversation.
+    """
+    name = name or banner
+    if resume:
+        session_id = resume
+        history = sessions.load(resume)
+        _console.print(f"[dim]resumed session {resume} ({len(history)} messages)[/dim]")
+    else:
+        session_id = sessions.new_id()
+        history = []
+    _console.print(f"[dim]ko {banner} — /exit to quit, /clear to reset context[/dim]")
+    while True:
+        try:
+            user_input = input(f"{banner}> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not user_input:
+            continue
+        if user_input == "/exit":
+            break
+        if user_input == "/clear":
+            history = []
+            session_id = sessions.new_id()
+            _console.print("[dim]context cleared (new session)[/dim]")
+            continue
+        prior = len(history)
+        _, history = _stream(agent, user_input, history, model=model, limits=limits)
+        _cost_note(history, prior=prior)
+        sessions.save(session_id, name, history)