delos-cli 0.1.0__py3-none-any.whl

delos_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Delos CLI — terminal REPL for the Cosmos chat agent."""
+
+__version__ = "0.1.0"

delos_cli/agent/__init__.py

@@ -0,0 +1,34 @@
+"""High-level wrapper around the backend's ``/{app}/agent/*`` routes.
+
+:class:`AgentSession` drives one user turn end-to-end: streams completions,
+detects unresolved tool calls (= client-side tools), resolves them via
+registered handlers, and re-issues continuation requests until the agent
+run is fully complete.
+
+A :class:`ToolRegistry` is the single extension point — apps register:
+
+* **Renderers** — how a server-side tool's events show up in the terminal.
+* **Handlers** — how a client-side tool collects input from the user.
+
+Both have sensible defaults so apps work out of the box.
+"""
+
+from .session import AgentSession
+from .tools import (
+    ToolHandler,
+    ToolRegistry,
+    ToolRenderer,
+    default_handler,
+    default_renderer,
+)
+from .transport import AgentTransport
+
+__all__ = [
+    "AgentSession",
+    "AgentTransport",
+    "ToolHandler",
+    "ToolRegistry",
+    "ToolRenderer",
+    "default_handler",
+    "default_renderer",
+]

delos_cli/agent/session.py

@@ -0,0 +1,111 @@
+"""AgentSession — drives one user turn end-to-end.
+
+A turn may span multiple SSE streams: each client-side tool call ends
+one stream and starts another with ``tool_continuation=true``.  From the
+caller's POV, :meth:`AgentSession.send_turn` is a single async iterator
+of UI events — all the multi-stream stitching is internal.
+
+A :class:`ToolRegistry` resolves both how server-tool events render and
+how client-tool calls collect input from the user.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from delos_cli.ctx import Ctx
+
+    from .tools import ToolRegistry
+    from .transport import AgentTransport
+
+
+class AgentSession:
+    """One session per ``(transport, chat_id)`` pair."""
+
+    def __init__(
+        self,
+        transport: AgentTransport,
+        chat_id: str,
+        registry: ToolRegistry,
+    ) -> None:
+        """Bind to a chat row.  Multiple turns share the same session."""
+        self._transport = transport
+        self._chat_id = chat_id
+        self._registry = registry
+
+    @property
+    def chat_id(self) -> str:
+        """The chat row id this session is bound to."""
+        return self._chat_id
+
+    async def send_turn(
+        self,
+        body: dict[str, Any],
+        ctx: Ctx,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Send one user turn and yield every UI event the agent emits.
+
+        Streams the initial ``/completions`` request.  When the run
+        terminates with unresolved tool calls, treats them as client-side,
+        invokes the registered handler, posts the result via
+        ``/tool-result``, and re-streams a continuation request with
+        ``tool_continuation=true`` and ``messages=[]``.  Loops until no
+        pending calls remain or the user explicitly stopped.
+        """
+        current_body = dict(body)
+        while True:
+            pending: dict[str, dict[str, Any]] = {}
+            stopped = False
+            async for event in self._transport.stream_completions(current_body):
+                etype = event.get("type", "")
+                if etype == "tool-input-available":
+                    tcid = event.get("toolCallId", "")
+                    if tcid:
+                        pending[tcid] = {
+                            "name": event.get("toolName", ""),
+                            "input": event.get("input", {}) or {},
+                        }
+                elif etype == "tool-output-available":
+                    pending.pop(event.get("toolCallId", ""), None)
+                elif etype == "data-stopped":
+                    stopped = True
+                yield event
+
+            if stopped or not pending:
+                return
+
+            for tcid, meta in pending.items():
+                handler = self._registry.handler_for(meta["name"])
+                result = await handler(meta["input"], ctx)
+                await self._transport.submit_tool_result(
+                    self._chat_id, tcid, meta["name"], result,
+                )
+
+            current_body = {**body, "messages": [], "tool_continuation": True}
+
+    async def stop(self) -> None:
+        """Set the backend stop signal.  Idempotent."""
+        await self._transport.stop(self._chat_id)
+
+    async def clear_chat(self) -> None:
+        """Delete the chat row on the backend."""
+        await self._transport.clear_chat(self._chat_id)
+
+    async def queue_message(self, content: str) -> str:
+        """Add a message to the FIFO queue.  Returns the new message id."""
+        return await self._transport.queue_message(self._chat_id, content)
+
+    async def list_queue(self) -> list[dict[str, Any]]:
+        """Return the current queued-messages list."""
+        return await self._transport.list_queue(self._chat_id)
+
+    async def edit_queued(self, message_id: str, content: str) -> None:
+        """Edit a queued message in place."""
+        await self._transport.edit_queued(self._chat_id, message_id, content)
+
+    async def remove_queued(self, message_id: str) -> None:
+        """Remove a queued message."""
+        await self._transport.remove_queued(self._chat_id, message_id)

delos_cli/agent/tools.py

@@ -0,0 +1,131 @@
+"""Tool registry, default renderers, and default handlers.
+
+There are two extension points per tool:
+
+- **Renderer** — called when the agent emits ``tool-input-available``,
+  ``tool-output-available``, or ``data-tool-output-delta`` for that tool.
+  Returns a Rich renderable (``Panel``, ``Text``, …) or ``None`` to skip.
+  Used for server-side tools whose execution happens in the backend.
+
+- **Handler** — called when the agent emits ``tool-input-available`` and
+  the run terminates without a corresponding ``tool-output-available``
+  (= the tool was registered ``client=True`` server-side).  Returns the
+  result string the next agent turn should see.
+
+Defaults:
+
+- :func:`default_renderer` — a one-line ``→ tool_name`` indicator on
+  ``tool-input-available``; nothing on output / delta events.  Custom
+  renderers can opt into args, output, or streaming deltas.
+- :func:`default_handler` — prints the input dict, asks for a free-form
+  text answer via a one-shot prompt_toolkit prompt.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import HTML
+from rich.panel import Panel
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from rich.console import RenderableType
+
+    from delos_cli.ctx import Ctx
+
+
+@runtime_checkable
+class ToolRenderer(Protocol):
+    """Render one tool-related event.
+
+    Return a Rich renderable to print above the live region, or ``None``
+    to skip rendering.  The same renderer instance receives every event
+    for its tool name across the whole REPL session, so it may keep state
+    (e.g. dedupe by ``toolCallId``) if needed.
+    """
+
+    def __call__(self, event: dict[str, Any]) -> RenderableType | None:
+        """Render ``event`` and return a Rich renderable, or ``None`` to skip."""
+        ...
+
+
+@runtime_checkable
+class ToolHandler(Protocol):
+    """Resolve a client-side tool call.
+
+    Receives the tool's ``input`` dict (whatever the agent passed) and the
+    REPL :class:`~delos_cli.ctx.Ctx` for console / HTTP access.  Returns
+    the result string the next agent turn should see.
+    """
+
+    async def __call__(
+        self, tool_input: dict[str, Any], ctx: Ctx,
+    ) -> str:
+        """Collect input from the user and return the result string."""
+        ...
+
+
+def default_renderer(event: dict[str, Any]) -> RenderableType | None:
+    """Show a single ``→ tool_name`` line on ``tool-input-available``; ignore the rest.
+
+    Args are intentionally hidden — most tool calls are noisy enough as JSON
+    that they hurt readability for the default case.  Custom renderers can
+    opt into args, output (``tool-output-available``), and streaming
+    deltas (``data-tool-output-delta``).
+    """
+    if event.get("type") != "tool-input-available":
+        return None
+    name = event.get("toolName", "?")
+    line = Text()
+    line.append("→ ", style="bold cyan")
+    line.append(name, style="cyan")
+    return line
+
+
+async def default_handler(tool_input: dict[str, Any], ctx: Ctx) -> str:
+    """Print the input dict and prompt for a single-line free-form answer.
+
+    A one-shot :class:`PromptSession` is spun up so the user gets the same
+    keybindings as the main REPL (Ctrl+R search, history hints, …) without
+    polluting the chat history file with these tool answers.
+    """
+    try:
+        pretty = json.dumps(tool_input, indent=2, ensure_ascii=False)
+    except (TypeError, ValueError):
+        pretty = str(tool_input)
+    ctx.console.print(
+        Panel(
+            Text(pretty, style="dim"),
+            title="? client tool input",
+            title_align="left",
+            border_style="yellow",
+            expand=False,
+        ),
+    )
+    sess: PromptSession[str] = PromptSession()
+    answer = await sess.prompt_async(HTML("<ansiyellow>tool result › </ansiyellow>"))
+    return answer.strip()
+
+
+@dataclass
+class ToolRegistry:
+    """Per-tool overrides keyed by tool name.
+
+    Lookups fall back to :func:`default_renderer` / :func:`default_handler`
+    when a tool isn't registered.
+    """
+
+    renderers: dict[str, ToolRenderer] = field(default_factory=dict)
+    handlers: dict[str, ToolHandler] = field(default_factory=dict)
+
+    def renderer_for(self, name: str) -> ToolRenderer:
+        """Return the registered renderer for ``name``, or the default."""
+        return self.renderers.get(name, default_renderer)
+
+    def handler_for(self, name: str) -> ToolHandler:
+        """Return the registered handler for ``name``, or the default."""
+        return self.handlers.get(name, default_handler)

delos_cli/agent/transport.py

@@ -0,0 +1,102 @@
+"""HTTP wrappers for the ``/{app}/agent/*`` routes.
+
+One :class:`AgentTransport` instance is bound to ``(app, org)``; the
+``chat_id`` is passed per call.  Methods map 1:1 to the routes the backend
+exposes via ``create_agent_router``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from delos_cli.transport.client import AuthedClient
+
+
+class AgentTransport:
+    """One transport instance per ``(app, org)`` pair."""
+
+    def __init__(
+        self,
+        http: AuthedClient,
+        api_prefix: str,
+        org_uuid: str,
+    ) -> None:
+        """Bind to an app's agent router.
+
+        ``api_prefix`` is the app slug (``"chat"``, ``"code"``, …) — it is
+        what the backend uses to mount each ``create_agent_router`` instance.
+        """
+        self._http = http
+        self._prefix = api_prefix
+        self._org = org_uuid
+
+    def _path(self, suffix: str, chat_id: str | None = None) -> str:
+        base = f"/{self._prefix}/agent/{suffix}/{self._org}"
+        return f"{base}/{chat_id}" if chat_id is not None else base
+
+    async def stream_completions(
+        self, body: dict[str, Any],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """``POST /{app}/agent/completions/{org}`` → parsed SSE events."""
+        async for event in self._http.sse_post(self._path("completions"), body):
+            yield event
+
+    async def stop(self, chat_id: str) -> None:
+        """``POST /stop/{org}/{chat_id}`` — set the Redis stop signal."""
+        await self._http.json_post(self._path("stop", chat_id), {})
+
+    async def submit_tool_result(
+        self,
+        chat_id: str,
+        tool_call_id: str,
+        tool_name: str,
+        content: str,
+    ) -> None:
+        """``POST /tool-result/{org}/{chat_id}`` — persist a client-tool result."""
+        await self._http.json_post(
+            self._path("tool-result", chat_id),
+            {
+                "tool_call_id": tool_call_id,
+                "tool_name": tool_name,
+                "content": content,
+            },
+        )
+
+    async def clear_chat(self, chat_id: str) -> None:
+        """``POST /clear-chat/{org}/{chat_id}`` — delete the chat row."""
+        await self._http.json_post(self._path("clear-chat", chat_id), {})
+
+    async def queue_message(self, chat_id: str, content: str) -> str:
+        """``POST /queue/{org}/{chat_id}`` — append to the FIFO queue.
+
+        Generates a fresh UUID client-side (mirrors the frontend) and returns
+        it so the caller can later edit / remove the queued entry.
+        """
+        message_id = str(uuid.uuid4())
+        await self._http.json_post(
+            self._path("queue", chat_id),
+            {"message_id": message_id, "content": content},
+        )
+        return message_id
+
+    async def list_queue(self, chat_id: str) -> list[dict[str, Any]]:
+        """``GET /queue/{org}/{chat_id}`` — current queue snapshot."""
+        data = await self._http.json_get(self._path("queue", chat_id))
+        queue = data.get("queue") or []
+        return list(queue)
+
+    async def edit_queued(
+        self, chat_id: str, message_id: str, content: str,
+    ) -> None:
+        """``PUT /queue/{org}/{chat_id}/{msg_id}``."""
+        path = f"{self._path('queue', chat_id)}/{message_id}"
+        await self._http.json_request("PUT", path, {"content": content})
+
+    async def remove_queued(self, chat_id: str, message_id: str) -> None:
+        """``DELETE /queue/{org}/{chat_id}/{msg_id}``."""
+        path = f"{self._path('queue', chat_id)}/{message_id}"
+        await self._http.json_request("DELETE", path, None)

delos_cli/apps/__init__.py

@@ -0,0 +1,6 @@
+"""Apps: one agent per module, all implementing :class:`~delos_cli.apps.base.App`."""
+
+from .base import App, Renderer
+from .chat import ChatApp
+
+__all__ = ["App", "ChatApp", "Renderer"]

delos_cli/apps/base.py

@@ -0,0 +1,101 @@
+"""App + Renderer protocols.
+
+Each app (chat, scribe, code, …) implements ``App``. The loop is
+app-agnostic: it only knows how to send a turn, get a renderer, and
+ask for a toolbar fragment.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from delos_cli.commands.base import CommandSpec
+    from delos_cli.ctx import Ctx
+    from delos_cli.ui.output import OutputBuffer
+
+
+@runtime_checkable
+class Renderer(Protocol):
+    """Consumes streamed events and pushes them into the REPL's :class:`OutputBuffer`.
+
+    The renderer no longer prints to a console directly — the
+    :class:`~prompt_toolkit.application.Application` owns the actual
+    terminal drawing.  Renderers only translate v6 events into block /
+    live updates on the buffer.
+    """
+
+    assistant_text: str
+
+    def apply(self, event: dict[str, Any]) -> None:
+        """Handle one streamed event."""
+        ...
+
+    def close(self) -> None:
+        """Finalize any in-flight live block — call at the end of a turn."""
+        ...
+
+
+class App(ABC):
+    """Interface one backend agent needs to implement to plug into the REPL.
+
+    Subclasses own their own state (model choice, selected tools, …).
+    """
+
+    #: Short user-facing name (``"chat"``, ``"scribe"``, …).
+    name: str
+
+    #: Slash commands specific to this app — merged with the global registry.
+    commands: dict[str, CommandSpec]
+
+    @abstractmethod
+    async def on_enter(self, ctx: Ctx) -> None:
+        """Hook called once, on REPL startup.
+
+        Prefetch lists (e.g. available models) or rehydrate state before
+        the loop starts reading input. Implement as ``pass`` if nothing
+        is needed.
+        """
+
+    @abstractmethod
+    def send(
+        self,
+        ctx: Ctx,
+        messages: list[dict[str, str]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Stream one turn's events. The loop will ``async for`` over this."""
+
+    @abstractmethod
+    def make_renderer(self, output: OutputBuffer) -> Renderer:
+        """Build a fresh renderer bound to ``output`` for this turn."""
+
+    def toolbar_fragment(self, ctx: Ctx) -> str:
+        """Optional HTML fragment the bottom toolbar appends after the shared bits.
+
+        Default: empty. Override to show app-specific state (selected model,
+        open document, …).
+        """
+        _ = self, ctx
+        return ""
+
+    async def cancel(self, ctx: Ctx) -> None:
+        """Hook called on Ctrl+C during a turn or when ``/stop`` is invoked.
+
+        Default is a no-op.  Apps that drive a backend agent should override
+        this to send the corresponding stop signal so the run aborts on the
+        server, not just locally.
+        """
+        _ = self, ctx
+
+    async def queue_message(self, ctx: Ctx, content: str) -> bool:
+        """Queue a plain message while a turn is already in flight.
+
+        Default returns ``False`` (caller should fall back to refusing /
+        ignoring).  Apps that wrap a real agent should append to its
+        backend FIFO queue and return ``True`` on success.
+        """
+        _ = self, ctx, content
+        return False

delos_cli/apps/chat/__init__.py

@@ -0,0 +1,5 @@
+"""Chat app package — default agent."""
+
+from .app import ChatApp
+
+__all__ = ["ChatApp"]

delos_cli/apps/chat/app.py

@@ -0,0 +1,149 @@
+"""ChatApp — the delos-cli agent.
+
+Wraps an :class:`AgentSession` against the ``/cli/agent/*`` backend
+endpoints + ``app_cli`` / ``app_cli_messages`` Supabase tables.  The
+chat row is INSERT'd at picker time (cf. :func:`main._run_repl`), so by
+the time we get here the agent always has a row to append messages to.
+
+Owns the per-app :class:`ToolRegistry` (so users can plug in custom
+renderers / handlers per tool).  The :class:`V6Renderer` returned from
+:meth:`make_renderer` is wired to the same registry.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from rich.text import Text
+
+from delos_cli.agent import AgentSession, AgentTransport, ToolRegistry
+from delos_cli.apps.base import App
+from delos_cli.tools import (
+    handle_edit_content,
+    handle_run_shell,
+    handle_write_content,
+    render_edit_content,
+    render_run_shell,
+    render_write_content,
+)
+from delos_cli.transport.client import TransportError
+from delos_cli.transport.models import fetch_models
+
+from .commands import CHAT_COMMANDS
+from .render import V6Renderer
+from .replay import replay_messages
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from delos_cli.commands.base import CommandSpec
+    from delos_cli.ctx import Ctx
+    from delos_cli.ui.output import OutputBuffer
+
+
+def _default_tool_registry() -> ToolRegistry:
+    """Pre-wired registry: client tools the backend can call out of the box."""
+    reg = ToolRegistry()
+    reg.handlers["run_shell"] = handle_run_shell
+    reg.renderers["run_shell"] = render_run_shell
+    reg.handlers["write_content"] = handle_write_content
+    reg.renderers["write_content"] = render_write_content
+    reg.handlers["edit_content"] = handle_edit_content
+    reg.renderers["edit_content"] = render_edit_content
+    return reg
+
+
+@dataclass
+class ChatApp(App):
+    """The CLI chat agent — talks to ``/cli/agent/...``."""
+
+    name: str = "cli"
+    available_models: list[str] = field(default_factory=list)
+    commands: dict[str, CommandSpec] = field(default_factory=lambda: dict(CHAT_COMMANDS))
+    #: Per-tool renderers + handlers.  Built-in entries cover the
+    #: client-side tools the backend exposes (``run_shell`` for now).
+    #: Override / extend by mutating ``tools.handlers`` and
+    #: ``tools.renderers`` after construction.
+    tools: ToolRegistry = field(default_factory=_default_tool_registry)
+    #: OpenAI-style messages staged for replay on the next ``on_enter``.
+    #: Set by ``main._run_repl`` after the picker resolves a chat_id, so
+    #: history is rendered the moment the REPL takes over the screen.
+    pending_replay: list[dict[str, Any]] = field(default_factory=list)
+    _current_session: AgentSession | None = field(default=None, init=False, repr=False)
+
+    async def on_enter(self, ctx: Ctx) -> None:
+        """Prefetch model list, then replay any staged conversation history."""
+        try:
+            self.available_models = await fetch_models(ctx.http)
+        except TransportError as e:
+            sink = ctx.output if ctx.output is not None else ctx.console
+            sink.print(Text(f"(could not fetch models: {e})", style="yellow"))
+
+        if self.pending_replay and ctx.output is not None:
+            replay_messages(self.pending_replay, self, ctx.output)
+        # Always drain — even a failed replay shouldn't replay again next time.
+        self.pending_replay = []
+
+    async def send(
+        self,
+        ctx: Ctx,
+        messages: list[dict[str, str]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Stream one turn through :class:`AgentSession` against ``/cli/agent/...``.
+
+        The ``app_cli`` row is created at picker time (or by ``/clear``),
+        so the backend always finds the chat when this runs — no
+        ``ensure_chat_row`` dance.
+        """
+        transport = AgentTransport(ctx.http, "cli", ctx.cfg.org_uuid)
+        session = AgentSession(transport, ctx.state.conv_id, self.tools)
+
+        # Backend reads model + everything else from ``app_cli``; we only
+        # send what's strictly per-turn.
+        body: dict[str, Any] = {
+            "chat_id": ctx.state.conv_id,
+            "messages": messages,
+            "language": "en",
+        }
+
+        self._current_session = session
+        try:
+            async for event in session.send_turn(body, ctx):
+                yield event
+        finally:
+            self._current_session = None
+
+    def make_renderer(self, output: OutputBuffer) -> V6Renderer:
+        """Build a fresh :class:`V6Renderer` wired to this app's tool registry."""
+        return V6Renderer(output, self.tools)
+
+    async def cancel(self, ctx: Ctx) -> None:
+        """Send the backend stop signal for the in-flight turn, if any.
+
+        No-op when no turn is active — :meth:`send` clears the session ref
+        as soon as the iterator finishes.
+        """
+        _ = ctx
+        if self._current_session is None:
+            return
+        # Best-effort — the loop has already shown an interrupt message.
+        with contextlib.suppress(TransportError):
+            await self._current_session.stop()
+
+    async def queue_message(self, ctx: Ctx, content: str) -> bool:
+        """Append a message to the backend's FIFO queue while a turn is running."""
+        _ = ctx
+        if self._current_session is None:
+            return False
+        try:
+            await self._current_session.queue_message(content)
+        except TransportError:
+            return False
+        return True
+
+    def toolbar_fragment(self, ctx: Ctx) -> str:
+        """Empty for now — model is server-side, no per-app state worth surfacing."""
+        _ = self, ctx
+        return ""

delos_cli/apps/chat/commands.py

@@ -0,0 +1,17 @@
+"""Chat-specific slash commands.
+
+Currently empty — the four global commands (``/help``, ``/clear``,
+``/stop``, ``/resume``, ``/quit``) cover everything we want exposed to
+end users.  Add a new ``CommandSpec`` here and merge it into
+:data:`CHAT_COMMANDS` to wire app-specific actions back in.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from delos_cli.commands.base import CommandSpec
+
+
+CHAT_COMMANDS: dict[str, CommandSpec] = {}