opendot 0.0.1__py3-none-any.whl

opendot/__init__.py

@@ -0,0 +1,18 @@
+"""opendot — an interactive terminal AI agent you can fully undo.
+
+Public SDK surface (so CLI, and future clients, are thin layers over this):
+
+    from opendot import Agent, AgentConfig
+
+    agent = Agent(AgentConfig(model="gpt-4o"))
+    async for event in agent.run("list the python files and summarize them"):
+        ...
+"""
+
+from opendot.agent.loop import Agent
+from opendot.agent.config import AgentConfig
+from opendot.agent.events import Event
+
+__version__ = "0.0.1"
+
+__all__ = ["Agent", "AgentConfig", "Event", "__version__"]

opendot/agent/__init__.py

@@ -0,0 +1 @@
+"""The opendot agent: the model-agnostic ReAct loop, config, events, prompt."""

opendot/agent/config.py

@@ -0,0 +1,27 @@
+"""Agent configuration.
+
+Model IDs are whatever LiteLLM accepts (``gpt-4o``, ``claude-sonnet-4-5``,
+``ollama/qwen2.5``, ``huggingface/...``, etc.) — opendot is model-agnostic and
+does not maintain its own provider list. API keys are read from the environment
+by LiteLLM in the usual way (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# A sensible default that works if the user has an OpenAI key; over/ridden via
+# --model, the OPENDOT_MODEL env var, or config.
+DEFAULT_MODEL = os.environ.get("OPENDOT_MODEL", "gpt-4o")
+
+
+@dataclass
+class AgentConfig:
+    """Everything the agent loop needs. Kept minimal for v1."""
+
+    model: str = DEFAULT_MODEL
+    workdir: str = field(default_factory=os.getcwd)
+    max_steps: int = 40  # hard bound on tool-calling turns per user message
+    temperature: float | None = None
+    system_prompt: str | None = None  # None => use the built-in default

opendot/agent/events.py

@@ -0,0 +1,34 @@
+"""Events streamed by the agent loop.
+
+The loop is an async generator of these. The CLI renders them; a future SDK
+consumer or remote client can consume them just as easily. Keeping this a small,
+stable vocabulary is what lets other surfaces (TUI, web, Slack) be thin adapters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+EventType = Literal[
+    "thinking",    # a streamed chunk of the model's reasoning (reasoning models)
+    "text",        # a streamed chunk of the assistant's answer
+    "tool_start",  # the agent is about to run a tool
+    "tool_end",    # a tool finished (result attached)
+    "final",       # the assistant's turn is complete
+    "error",       # something went wrong
+    # parallel read-only explorers
+    "explorer_start",  # a subagent lane started (text=task, lane=index)
+    "explorer_step",   # a subagent did something (text=summary, lane=index)
+    "explorer_done",   # a subagent finished (text=finding summary, lane=index)
+]
+
+
+@dataclass
+class Event:
+    type: EventType
+    text: str = ""                       # for "text" / "error" / explorer_*
+    tool: str = ""                       # for tool_start / tool_end
+    args: dict[str, Any] = field(default_factory=dict)  # tool_start
+    result: str = ""                     # tool_end
+    lane: int = -1                       # explorer lane index (-1 = main agent)

opendot/agent/explorers.py

@@ -0,0 +1,93 @@
+"""Parallel read-only explorer subagents.
+
+The main agent can call `spawn_explorers([task, task, ...])` to fan out several
+independent *read-only* investigations at once — each a full reasoning agent
+restricted to grep/glob/read/list (NO write, edit, or shell). They run
+concurrently and each returns a short findings summary, which is fed back to the
+main agent.
+
+Why read-only: opendot's guarantee is a clean, sequential, undoable action
+ledger. Parallel *writers* would race the filesystem and make "undo the last
+action" ambiguous. Explorers never mutate anything, so they parallelize the safe
+part (understanding the project) without touching that guarantee.
+
+Events are lane-tagged (lane = subagent index) so the TUI can show parallel
+"Explore Task" lanes like opencode.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator
+
+from opendot.agent.events import Event
+
+MAX_EXPLORERS = 6
+
+_EXPLORER_SYSTEM = """\
+You are a read-only explorer subagent. Your ONLY job is to investigate and \
+report — you cannot change anything. You have grep, glob, read_file, and \
+list_files. Use them to answer the task, then give a concise findings summary \
+(a few bullet points with the key files/lines). Do not attempt to write or run \
+anything; those tools are not available to you.
+"""
+
+
+async def run_explorers(
+    tasks: list[str], *, model: str, workdir: str
+) -> AsyncIterator[Event]:
+    """Run each task as a concurrent read-only subagent, yielding lane-tagged
+    events, and finally a merged findings summary the caller can use."""
+    from opendot.agent.config import AgentConfig
+    from opendot.agent.loop import Agent
+
+    tasks = [t for t in tasks if t.strip()][:MAX_EXPLORERS]
+    if not tasks:
+        yield Event("error", text="spawn_explorers: no tasks given")
+        return
+
+    # A queue lets concurrent lanes interleave their events into one stream.
+    q: asyncio.Queue = asyncio.Queue()
+    findings: dict[int, str] = {}
+
+    async def one(lane: int, task: str) -> None:
+        await q.put(Event("explorer_start", text=task, lane=lane))
+        agent = Agent(AgentConfig(
+            model=model, workdir=workdir, system_prompt=_EXPLORER_SYSTEM,
+        ))
+        # Force a read-only toolbox regardless of defaults.
+        from opendot.tools.local import Toolbox
+        agent.toolbox = Toolbox(workdir, reversibility=None, read_only=True)
+        answer_parts: list[str] = []
+        try:
+            async for ev in agent.run(task):
+                if ev.type == "tool_start":
+                    await q.put(Event("explorer_step", text=f"{ev.tool}", lane=lane))
+                elif ev.type == "text":
+                    answer_parts.append(ev.text)
+                elif ev.type == "error":
+                    await q.put(Event("explorer_step", text=f"error: {ev.text}", lane=lane))
+        except Exception as exc:  # noqa: BLE001
+            answer_parts.append(f"(explorer failed: {exc})")
+        summary = "".join(answer_parts).strip() or "(no findings)"
+        findings[lane] = summary
+        await q.put(Event("explorer_done", text=summary, lane=lane))
+
+    async def run_all() -> None:
+        await asyncio.gather(*(one(i, t) for i, t in enumerate(tasks)))
+        await q.put(None)  # sentinel
+
+    runner = asyncio.create_task(run_all())
+    while True:
+        ev = await q.get()
+        if ev is None:
+            break
+        yield ev
+    await runner
+
+    # Attach the merged findings as the tool's textual result via a final event.
+    merged = "\n\n".join(
+        f"[explorer {i+1}] {tasks[i]}\n{findings.get(i, '(no findings)')}"
+        for i in range(len(tasks))
+    )
+    yield Event("tool_end", tool="spawn_explorers", result=merged)

opendot/agent/loop.py

@@ -0,0 +1,263 @@
+"""The agent loop — a model-agnostic ReAct loop over LiteLLM.
+
+`Agent.run(user_message)` is an async generator of `Event`s. It keeps a running
+conversation (`self.messages`) across turns so the CLI REPL is just repeated
+`run(...)` calls. Tool calls are executed locally via the `Toolbox` and fed back
+to the model until it produces a final answer (no more tool calls).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, AsyncIterator
+
+from opendot.agent.config import AgentConfig
+from opendot.agent.events import Event
+from opendot.agent.prompt import DEFAULT_SYSTEM_PROMPT
+from opendot.tools.local import Toolbox
+
+
+_SPAWN_EXPLORERS_SPEC = {
+    "type": "function",
+    "function": {
+        "name": "spawn_explorers",
+        "description": (
+            "Investigate several INDEPENDENT questions about the project in "
+            "parallel. Each task runs as a read-only subagent (grep/glob/read "
+            "only — it cannot change anything) and returns findings. Use this to "
+            "understand a codebase fast by splitting distinct questions across "
+            "lanes. For anything that changes files, do it yourself."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "tasks": {
+                    "type": "array", "items": {"type": "string"},
+                    "description": "2-6 independent, self-contained investigation tasks.",
+                }
+            },
+            "required": ["tasks"],
+        },
+    },
+}
+
+
+class _StreamUnsupported(Exception):
+    """Raised when a provider's stream can't yield structured tool calls."""
+
+
+@dataclass
+class _Assembled:
+    """Sentinel yielded at the end of a turn carrying the assembled result."""
+
+    assistant_msg: dict[str, Any]
+    tool_calls: list[dict[str, Any]]
+
+
+def _assistant_msg(content: str, calls: list[dict[str, Any]]) -> dict[str, Any]:
+    msg: dict[str, Any] = {"role": "assistant", "content": content or None}
+    if calls:
+        msg["tool_calls"] = [
+            {"id": c["id"], "type": "function",
+             "function": {"name": c["name"], "arguments": c["args"] or "{}"}}
+            for c in calls
+        ]
+    return msg
+
+
+class Agent:
+    def __init__(self, config: AgentConfig | None = None, confirm=None,
+                 mcp_manager=None) -> None:
+        self.config = config or AgentConfig()
+        self.mcp = mcp_manager
+
+        # The reversibility engine snapshots + logs before every mutating action.
+        # Snapshot include/exclude rules come from OPENDOT.md (or defaults).
+        from opendot.reversibility.engine import Reversibility
+        from opendot.reversibility.rules import load_rules
+
+        self.reversibility = Reversibility(
+            workdir=self.config.workdir, rules=load_rules(self.config.workdir)
+        )
+        self.toolbox = Toolbox(
+            self.config.workdir,
+            reversibility=self.reversibility,
+            confirm=confirm,
+            mcp_manager=mcp_manager,
+        )
+        system = self.config.system_prompt or DEFAULT_SYSTEM_PROMPT
+        self.messages: list[dict[str, Any]] = [{"role": "system", "content": system}]
+
+        from opendot.agent.usage import Usage
+
+        self.usage = Usage()  # running token/cost totals for the session
+
+        # The main agent can fan out read-only explorer subagents; explorers
+        # themselves cannot (no recursive spawning). Read-only toolboxes = explorer.
+        self.explorers_enabled = not getattr(self.toolbox, "read_only", False)
+
+    def reset(self) -> None:
+        """Clear the conversation (the /clear context-reset barrier), keeping system."""
+        self.messages = self.messages[:1]
+
+    def compact(self, keep_recent: int = 6) -> int:
+        """Trim old turns to fight context bloat, keeping the system prompt and
+        the most recent messages. Returns how many messages were dropped.
+
+        v1 is a simple truncation (honest and predictable). A summarizing
+        compaction can replace this later without changing the interface.
+        """
+        if len(self.messages) <= keep_recent + 1:
+            return 0
+        system, tail = self.messages[:1], self.messages[-keep_recent:]
+        dropped = len(self.messages) - len(system) - len(tail)
+        self.messages = system + tail
+        return dropped
+
+    async def run(self, user_message: str) -> AsyncIterator[Event]:
+        """Run one user turn to completion, yielding events."""
+        import litellm
+
+        # Keep litellm/provider chatter out of the user's terminal.
+        litellm.suppress_debug_info = True
+        litellm.set_verbose = False
+
+        self.messages.append({"role": "user", "content": user_message})
+        tools = self.toolbox.specs()
+        if self.explorers_enabled:
+            tools = tools + [_SPAWN_EXPLORERS_SPEC]
+
+        for _ in range(self.config.max_steps):
+            # Stream the turn: reasoning ("thinking") and answer ("text") arrive
+            # live, and tool-call deltas are reassembled. Streaming is what makes
+            # the UX feel alive. If streaming fails for a provider, fall back to
+            # a single non-streaming call (some local models emit tool calls as
+            # text in streaming mode).
+            try:
+                gen = None
+                async for ev in self._stream_turn(litellm, tools):
+                    if isinstance(ev, _Assembled):
+                        gen = ev
+                    else:
+                        yield ev
+            except _StreamUnsupported:
+                gen = None
+                async for ev in self._nonstream_turn(litellm, tools):
+                    if isinstance(ev, _Assembled):
+                        gen = ev
+                    else:
+                        yield ev
+            except Exception as exc:  # noqa: BLE001
+                yield Event("error", text=f"model call failed: {exc}")
+                return
+
+            if gen is None:  # an error event was already yielded
+                return
+
+            self.messages.append(gen.assistant_msg)
+
+            if not gen.tool_calls:
+                yield Event("final")
+                return
+
+            for i, c in enumerate(gen.tool_calls):
+                name, call_id, raw_args = c["name"], c["id"], c["args"]
+                try:
+                    args = json.loads(raw_args or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+
+                # spawn_explorers is handled by the runtime (parallel read-only
+                # subagents), not the toolbox — it streams lane-tagged events.
+                if name == "spawn_explorers" and self.explorers_enabled:
+                    from opendot.agent.explorers import run_explorers
+
+                    result = "(no findings)"
+                    async for ev in run_explorers(
+                        args.get("tasks", []), model=self.config.model,
+                        workdir=self.config.workdir,
+                    ):
+                        if ev.type == "tool_end" and ev.tool == "spawn_explorers":
+                            result = ev.result  # merged findings
+                        else:
+                            yield ev
+                    self.messages.append(
+                        {"role": "tool", "tool_call_id": call_id, "content": result}
+                    )
+                    continue
+
+                yield Event("tool_start", tool=name, args=args)
+                # Run the (synchronous) tool off the event loop. This is what lets
+                # a confirm-callback safely block for a UI prompt (e.g. the TUI
+                # modal) without freezing the loop.
+                import asyncio
+                result = await asyncio.to_thread(self.toolbox.call, name, args)
+                yield Event("tool_end", tool=name, result=result)
+                self.messages.append(
+                    {"role": "tool", "tool_call_id": call_id, "content": result}
+                )
+
+        yield Event("error", text=f"stopped: hit max_steps ({self.config.max_steps})")
+
+    async def _stream_turn(self, litellm, tools):
+        """Stream one model turn. Yields Events, then a final _Assembled sentinel.
+
+        Raises _StreamUnsupported if the stream looks like a provider that emits
+        tool calls as plain text (so the caller can fall back to non-streaming).
+        """
+        stream = await litellm.acompletion(
+            model=self.config.model, messages=self.messages, tools=tools,
+            temperature=self.config.temperature, stream=True,
+            stream_options={"include_usage": True},
+        )
+        content_parts: list[str] = []
+        tool_calls: dict[int, dict[str, Any]] = {}
+
+        async for chunk in stream:
+            # The final usage chunk (include_usage) has no choices.
+            if getattr(chunk, "usage", None) and not chunk.choices:
+                self.usage.add_response(chunk, litellm)
+                continue
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+            # reasoning models expose reasoning separately
+            reasoning = getattr(delta, "reasoning_content", None)
+            if reasoning:
+                yield Event("thinking", text=reasoning)
+            if getattr(delta, "content", None):
+                content_parts.append(delta.content)
+                yield Event("text", text=delta.content)
+            for tc in getattr(delta, "tool_calls", None) or []:
+                slot = tool_calls.setdefault(tc.index, {"id": "", "name": "", "args": ""})
+                if tc.id:
+                    slot["id"] = tc.id
+                if tc.function and tc.function.name:
+                    slot["name"] = tc.function.name
+                if tc.function and tc.function.arguments:
+                    slot["args"] += tc.function.arguments
+
+        calls = [
+            {"id": c["id"] or f"call_{i}", "name": c["name"], "args": c["args"]}
+            for i, c in sorted(tool_calls.items()) if c["name"]
+        ]
+        yield _Assembled(_assistant_msg("".join(content_parts), calls), calls)
+
+    async def _nonstream_turn(self, litellm, tools):
+        """Non-streaming fallback (reliable tool calls; no live tokens)."""
+        resp = await litellm.acompletion(
+            model=self.config.model, messages=self.messages, tools=tools,
+            temperature=self.config.temperature, stream=False,
+        )
+        self.usage.add_response(resp, litellm)
+        msg = resp.choices[0].message
+        raw = getattr(msg, "tool_calls", None) or []
+        calls = [
+            {"id": tc.id or f"call_{i}", "name": tc.function.name,
+             "args": tc.function.arguments or "{}"}
+            for i, tc in enumerate(raw)
+        ]
+        if msg.content:
+            yield Event("text", text=msg.content)
+        yield _Assembled(_assistant_msg(msg.content or "", calls), calls)

opendot/agent/prompt.py

@@ -0,0 +1,30 @@
+"""The default system prompt. Lean by design — a big product-framing prompt is
+what bloats other agents; opendot's keeps it to role, tools, and safety posture.
+An OPENDOT.md in the working dir (loaded by the caller) is appended for
+project-specific guidance.
+"""
+
+DEFAULT_SYSTEM_PROMPT = """\
+You are opendot, an AI agent operating in the user's terminal. You work directly \
+on their real files and shell in the current working directory.
+
+Tools:
+- list_files, read_file — inspect the project
+- grep — search file contents by regex
+- glob — find files by pattern (e.g. **/*.py)
+- edit — make a targeted find-and-replace in a file (PREFER THIS for changes)
+- write_file — create a new file or fully rewrite one
+- run_shell — anything else (npm, git, build, mv, cp, tests, …)
+
+How to work:
+- Narrate briefly BEFORE each action: say what you're about to do and why, in one \
+line, so the user can follow your reasoning. Then take the action.
+- Explore before you change: read/grep/glob to understand the code first.
+- Prefer `edit` (surgical find-replace) over `write_file` (full rewrite) so changes \
+are small and reviewable. Only write_file for new files or genuine rewrites.
+- Keep shell commands scoped to the working directory.
+
+Every change you make is snapshotted and can be undone, so work confidently — but \
+if a request is destructive or reaches outside the workspace (deleting outside \
+files, network, git push), call it out first. When done, give a short summary.
+"""

opendot/agent/usage.py

@@ -0,0 +1,36 @@
+"""Token + cost accounting for a session.
+
+LiteLLM computes per-response cost via ``litellm.completion_cost`` and reports
+token counts in the response usage. We accumulate both across a session so the
+TUI sidebar can show "N tokens · $X spent" like the tools people expect.
+
+Best-effort: if a provider/model has no cost data, cost stays 0 but tokens still
+accumulate. Never raises.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Usage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+
+    def add_response(self, resp, litellm) -> None:
+        """Fold one LiteLLM response's usage + cost into the running totals."""
+        try:
+            u = getattr(resp, "usage", None)
+            if u:
+                self.prompt_tokens += int(getattr(u, "prompt_tokens", 0) or 0)
+                self.completion_tokens += int(getattr(u, "completion_tokens", 0) or 0)
+                self.total_tokens += int(getattr(u, "total_tokens", 0) or 0)
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            self.cost_usd += float(litellm.completion_cost(completion_response=resp) or 0.0)
+        except Exception:  # noqa: BLE001
+            pass