comodor 0.1.0__py3-none-any.whl

comodor/__init__.py

@@ -0,0 +1,18 @@
+"""Comodor — a self-improving terminal coding agent.
+
+The package is layered so each piece can be used on its own:
+
+    comodor.net        zero-dependency HTTP + SSE transport
+    comodor.providers  LLM backends and the health-aware model gateway
+    comodor.agent      the reason/act loop, context budgeting, prompts
+    comodor.tools      the capabilities the agent can invoke
+    comodor.safety     permissions, checkpoints, secret redaction
+    comodor.learning   the persistent brain that makes it better over time
+    comodor.session    conversation persistence and export
+    comodor.ui         the Rich terminal interface
+"""
+
+__version__ = "0.1.0"
+APP_NAME = "Comodor"
+
+__all__ = ["__version__", "APP_NAME"]

comodor/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m comodor``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

comodor/agent/__init__.py

@@ -0,0 +1,9 @@
+"""The reasoning core: the loop, the context budget, and the prompts."""
+
+from .context import Conversation
+from .loop import AgentLoop, TurnResult
+from .prompts import build_system_prompt
+from .tokens import TokenCounter, humanise
+
+__all__ = ["AgentLoop", "TurnResult", "Conversation", "build_system_prompt",
+           "TokenCounter", "humanise"]

comodor/agent/context.py

@@ -0,0 +1,149 @@
+"""Conversation state and the context budget.
+
+A long agent session will always outgrow its context window — tool output is
+verbose and there is a lot of it. When usage crosses the configured fraction of
+the window, the oldest middle section is replaced by an LLM-written brief.
+
+The subtle part is *where* to cut. Every assistant message that requests tools
+must keep its matching tool results, or the next request is rejected outright by
+the provider. So compaction only ever cuts at a boundary where no tool call is
+outstanding, and the original request is always preserved — losing the goal is
+the one failure a summary cannot recover from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from ..providers.base import Message, Role, ToolSpec, Usage
+from .tokens import TokenCounter
+
+Summariser = Callable[[list[Message]], str]
+
+
+@dataclass
+class Conversation:
+    """The message history plus everything we track about its size."""
+
+    messages: list[Message] = field(default_factory=list)
+    counter: TokenCounter = field(default_factory=TokenCounter)
+    usage: Usage = field(default_factory=Usage)
+    compactions: int = 0
+
+    # -- basics ----------------------------------------------------------- #
+
+    def add(self, message: Message) -> Message:
+        self.messages.append(message)
+        return message
+
+    def extend(self, messages: list[Message]) -> None:
+        self.messages.extend(messages)
+
+    def clear(self) -> None:
+        self.messages.clear()
+        self.usage = Usage()
+        self.compactions = 0
+
+    def render(self, system_prompt: str) -> list[Message]:
+        """The full payload for one request."""
+        return [Message.system(system_prompt), *self.messages]
+
+    @property
+    def last_user_text(self) -> str:
+        for message in reversed(self.messages):
+            if message.role is Role.USER:
+                return message.content
+        return ""
+
+    # -- accounting ------------------------------------------------------- #
+
+    def used_tokens(self, system_prompt: str = "", tools: list[ToolSpec] | None = None) -> int:
+        payload = self.render(system_prompt) if system_prompt else self.messages
+        return self.counter.count(payload, tools)
+
+    def record_usage(self, usage: Usage) -> None:
+        self.usage = self.usage.merge(usage)
+
+    def fill(self, limit: int, system_prompt: str = "",
+             tools: list[ToolSpec] | None = None) -> float:
+        """How full the context window is, as a fraction."""
+        if limit <= 0:
+            return 0.0
+        return min(1.0, self.used_tokens(system_prompt, tools) / limit)
+
+    # -- compaction ------------------------------------------------------- #
+
+    def needs_compaction(self, limit: int, threshold: float,
+                         system_prompt: str = "",
+                         tools: list[ToolSpec] | None = None) -> bool:
+        return self.fill(limit, system_prompt, tools) >= threshold
+
+    def safe_cut(self, keep_recent: int = 8) -> int:
+        """Index up to which messages may be summarised away.
+
+        A cut is only safe where the conversation is *settled*: a user turn
+        with no assistant tool call still awaiting its result. Returns 0 when
+        no safe point exists, which simply means compaction waits a turn.
+        """
+        if len(self.messages) <= keep_recent + 2:
+            return 0
+
+        latest_allowed = len(self.messages) - keep_recent
+        pending: set[str] = set()
+        last_safe = 0
+
+        for index, message in enumerate(self.messages):
+            if message.role is Role.ASSISTANT and message.tool_calls:
+                pending.update(call.id for call in message.tool_calls)
+            elif message.role is Role.TOOL:
+                pending.discard(message.tool_call_id)
+
+            # A user message with nothing outstanding is a clean seam.
+            if (index > 0 and not pending and message.role is Role.USER
+                    and index <= latest_allowed):
+                last_safe = index
+
+        return last_safe
+
+    def compact(self, summarise: Summariser, keep_recent: int = 8) -> int:
+        """Replace the middle of the history with a brief. Returns messages removed."""
+        cut = self.safe_cut(keep_recent)
+        if cut <= 1:
+            return 0
+
+        head = self.messages[0]            # the original request stays verbatim
+        middle = self.messages[1:cut]
+        tail = self.messages[cut:]
+        if not middle:
+            return 0
+
+        try:
+            brief = summarise(middle).strip()
+        except Exception:
+            # A failed summary must not lose messages; better a full context
+            # and a hard error later than silently discarded work now.
+            return 0
+        if not brief:
+            return 0
+
+        marker = Message(
+            role=Role.USER,
+            content=("[Earlier in this session — compacted summary]\n\n" + brief),
+            meta={"compacted": True, "replaced": len(middle)},
+        )
+        self.messages = [head, marker, *tail]
+        self.compactions += 1
+        return len(middle)
+
+    # -- introspection ---------------------------------------------------- #
+
+    def summary_line(self) -> str:
+        roles = {role: 0 for role in ("user", "assistant", "tool")}
+        for message in self.messages:
+            key = message.role.value
+            if key in roles:
+                roles[key] += 1
+        return (f"{len(self.messages)} messages "
+                f"({roles['user']} user, {roles['assistant']} assistant, "
+                f"{roles['tool']} tool)")

comodor/agent/loop.py

@@ -0,0 +1,409 @@
+"""The reason/act loop.
+
+One turn is: assemble context, stream a response, run whatever tools it asked
+for, feed the results back, repeat. It ends when the model stops asking for
+tools, or when a guard trips — step count, wall clock, or spend.
+
+Three details are worth knowing:
+
+*Loop off means one step.* The ``Loop`` switch in the status bar decides whether
+the agent may iterate after the first round of tools or must hand control back.
+
+*Read-only tools run in parallel.* When a round contains only ``SAFE`` calls and
+they need no approval, they execute concurrently — several file reads should not
+cost several round trips of latency. Results are still reported in call order so
+the transcript stays deterministic.
+
+*Cancellation is cooperative and checked everywhere.* Between steps, between
+stream chunks, and inside the shell tool, so Esc stops the agent within a
+fraction of a second rather than at the end of the current model response.
+"""
+
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from ..config import Config
+from ..events import Cancellation, Cancelled, EventBus, Kind
+from ..providers.base import (
+    EventType,
+    Message,
+    ProviderError,
+    ToolCall,
+    ToolSpec,
+    Usage,
+)
+from ..providers.gateway import Gateway
+from ..safety import PermissionEngine, Risk
+from ..tools import ToolContext, ToolRegistry, ToolResult
+from .context import Conversation
+from .prompts import COMPACT_PROMPT, build_system_prompt
+
+MAX_PARALLEL_TOOLS = 6
+
+
+@dataclass
+class TurnResult:
+    """What one user turn produced."""
+
+    text: str = ""
+    steps: int = 0
+    tool_calls: int = 0
+    usage: Usage = field(default_factory=Usage)
+    stopped: str = "done"        # done | max_steps | budget | cancelled | error
+    error: str = ""
+    elapsed: float = 0.0
+
+    @property
+    def ok(self) -> bool:
+        return self.stopped in ("done", "max_steps")
+
+
+class AgentLoop:
+    """Drives one conversation against one gateway and one tool set."""
+
+    def __init__(self, config: Config, gateway: Gateway, tools: ToolRegistry,
+                 bus: EventBus, permissions: PermissionEngine,
+                 conversation: Conversation | None = None,
+                 memory: Any = None) -> None:
+        self.config = config
+        self.gateway = gateway
+        self.tools = tools
+        self.bus = bus
+        self.permissions = permissions
+        self.conversation = conversation or Conversation()
+        self.memory = memory                     # LearningEngine, or None
+        self.cancel = Cancellation()
+        self.tool_context: ToolContext | None = None
+        self._recalled: list[Any] = []
+
+    # -- public API ------------------------------------------------------- #
+
+    def run(self, user_text: str, images: list[str] | None = None) -> TurnResult:
+        """Handle one user message from start to finish."""
+        started = time.monotonic()
+        self.cancel.reset()
+        result = TurnResult()
+
+        self.conversation.add(Message.user(user_text, images=images or []))
+        self.bus.emit(Kind.TURN_START, text=user_text)
+
+        playbook = self._recall(user_text)
+        deadline = started + self.config.agent.max_seconds
+
+        try:
+            result = self._iterate(playbook, deadline)
+        except Cancelled:
+            result.stopped = "cancelled"
+            self.bus.emit(Kind.CANCELLED)
+        except ProviderError as exc:
+            result.stopped = "error"
+            result.error = str(exc)
+            self.bus.emit(Kind.ERROR, text=str(exc))
+        except Exception as exc:                  # a bug here must not kill the UI
+            result.stopped = "error"
+            result.error = f"{type(exc).__name__}: {exc}"
+            self.bus.emit(Kind.ERROR, text=result.error)
+
+        result.elapsed = time.monotonic() - started
+        result.usage = self.conversation.usage
+        self.bus.emit(Kind.TURN_END, stopped=result.stopped, steps=result.steps,
+                      elapsed=result.elapsed, error=result.error)
+
+        self._learn(user_text, result)
+        return result
+
+    def interrupt(self) -> None:
+        self.cancel.cancel()
+
+    # -- the loop --------------------------------------------------------- #
+
+    def _iterate(self, playbook: str, deadline: float) -> TurnResult:
+        result = TurnResult()
+        agent = self.config.agent
+
+        while True:
+            self.cancel.raise_if_cancelled()
+            result.steps += 1
+
+            specs = self.tools.specs(agent.mode)
+            system_prompt = build_system_prompt(self.config, playbook)
+            self._maybe_compact(system_prompt, specs)
+
+            completion = self._stream_once(system_prompt, specs)
+            assistant = completion["message"]
+            self.conversation.add(assistant)
+
+            calls: list[ToolCall] = assistant.tool_calls
+            if not calls:
+                result.text = assistant.content
+                result.stopped = "done"
+                return result
+
+            result.tool_calls += len(calls)
+            self._execute(calls)
+            self.bus.emit(Kind.STEP, step=result.steps, tool_calls=len(calls))
+
+            if not agent.loop:
+                # Loop off: run the tools the model asked for, then stop and
+                # let the user decide whether to continue.
+                result.stopped = "done"
+                result.text = assistant.content
+                return result
+
+            if result.steps >= agent.max_steps:
+                result.stopped = "max_steps"
+                self._note(f"Stopped after {agent.max_steps} steps — the step limit "
+                           f"for one task. Say 'continue' to keep going.")
+                return result
+
+            if time.monotonic() > deadline:
+                result.stopped = "budget"
+                self._note(f"Stopped after {agent.max_seconds:.0f}s — the time limit "
+                           f"for one task.")
+                return result
+
+            spent = self.conversation.usage.cost_usd
+            if agent.max_cost_usd and spent >= agent.max_cost_usd:
+                result.stopped = "budget"
+                self._note(f"Stopped at ${spent:.2f} — the spend limit for one task.")
+                return result
+
+    # -- model call ------------------------------------------------------- #
+
+    def _stream_once(self, system_prompt: str, specs: list[ToolSpec]) -> dict[str, Any]:
+        """One streamed assistant response, surfaced to the UI as it arrives."""
+        payload = self.conversation.render(system_prompt)
+        agent = self.config.agent
+
+        self.bus.emit(Kind.ASSISTANT_START)
+        text_parts: list[str] = []
+        reasoning_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        usage = Usage()
+
+        stream = self.gateway.stream(
+            payload,
+            tools=specs or None,
+            model=self.config.model,
+            temperature=agent.temperature,
+            max_tokens=agent.max_output_tokens,
+        )
+
+        for event in stream:
+            self.cancel.raise_if_cancelled()
+            if event.type is EventType.TEXT:
+                text_parts.append(event.text)
+                self.bus.emit(Kind.ASSISTANT_DELTA, text=event.text)
+            elif event.type is EventType.REASONING:
+                reasoning_parts.append(event.text)
+                self.bus.emit(Kind.REASONING_DELTA, text=event.text)
+            elif event.type is EventType.TOOL_CALL and event.tool_call:
+                tool_calls.append(event.tool_call)
+            elif event.type is EventType.USAGE and event.usage:
+                usage = usage.merge(event.usage)
+
+        text = "".join(text_parts)
+        self.bus.emit(Kind.ASSISTANT_END, text=text,
+                      tool_calls=[call.name for call in tool_calls])
+
+        self.conversation.record_usage(usage)
+        if usage.input_tokens:
+            self.conversation.counter.observe_usage(payload, specs, usage.input_tokens)
+        self._emit_usage(system_prompt, specs)
+
+        message = Message.assistant(text, tool_calls)
+        if reasoning_parts:
+            message.meta["reasoning"] = "".join(reasoning_parts)
+        route = self.gateway.last_route
+        if route:
+            message.meta["provider"] = route.provider
+            message.meta["model"] = route.model
+            if route.failed_over_from:
+                self._note(f"{', '.join(route.failed_over_from)} failed — "
+                           f"served by {route.provider}.")
+        return {"message": message, "usage": usage}
+
+    # -- tools ------------------------------------------------------------ #
+
+    def _execute(self, calls: list[ToolCall]) -> None:
+        context = self._tool_context()
+        parallel = self._can_parallelise(calls)
+
+        if parallel and len(calls) > 1:
+            with ThreadPoolExecutor(max_workers=min(MAX_PARALLEL_TOOLS, len(calls))) as pool:
+                futures = [pool.submit(self._run_one, call, context) for call in calls]
+                results = [future.result() for future in futures]
+        else:
+            results = [self._run_one(call, context) for call in calls]
+
+        for call, result in zip(calls, results):
+            self.conversation.add(Message.tool(
+                call_id=call.id, name=call.name,
+                content=result.content, is_error=not result.ok,
+            ))
+
+    def _run_one(self, call: ToolCall, context: ToolContext) -> ToolResult:
+        self.bus.emit(Kind.TOOL_START, id=call.id, name=call.name,
+                      arguments=call.arguments,
+                      summary=self._describe(call))
+        if self.cancel.cancelled:
+            result = ToolResult.failure("cancelled before the tool ran")
+        else:
+            result = self.tools.invoke(call.name, context, call.arguments)
+        self.bus.emit(Kind.TOOL_END, id=call.id, name=call.name, ok=result.ok,
+                      content=result.content, display=result.rendered,
+                      elapsed=result.elapsed, meta=result.meta)
+        return result
+
+    def _describe(self, call: ToolCall) -> str:
+        tool = self.tools.get(call.name)
+        return tool.summary(call.arguments) if tool else call.name
+
+    def _can_parallelise(self, calls: list[ToolCall]) -> bool:
+        """Only when nothing in the batch could stop to ask a question."""
+        if not self.config.safety.auto_approve_safe:
+            return False
+        for call in calls:
+            tool = self.tools.get(call.name)
+            if tool is None or tool.risk is not Risk.SAFE:
+                return False
+        return True
+
+    def _tool_context(self) -> ToolContext:
+        if self.tool_context is None:
+            from ..safety import CheckpointStore, Redactor
+
+            secrets = [entry.api_key for entry in self.config.providers.values()
+                       if entry.api_key]
+            self.tool_context = ToolContext(
+                config=self.config,
+                permissions=self.permissions,
+                checkpoints=CheckpointStore(self.config.paths.checkpoints),
+                bus=self.bus,
+                redact=Redactor(secrets),
+                cancel=self.cancel,
+                cwd=Path(self.config.paths.project),
+                emit_output=lambda text: self.bus.emit(Kind.TOOL_OUTPUT, text=text),
+            )
+        return self.tool_context
+
+    # -- context management ----------------------------------------------- #
+
+    def _maybe_compact(self, system_prompt: str, specs: list[ToolSpec]) -> None:
+        agent = self.config.agent
+        limit = agent.context_limit or 128_000
+        if not self.conversation.needs_compaction(limit, agent.compact_at,
+                                                  system_prompt, specs):
+            return
+
+        removed = self.conversation.compact(self._summarise)
+        if removed:
+            self._note(f"Compacted {removed} earlier messages to free context.")
+            self._emit_usage(system_prompt, specs)
+
+    def _summarise(self, messages: list[Message]) -> str:
+        """Ask the model to write the brief that replaces old history."""
+        from ..providers.base import collapse
+
+        transcript = "\n\n".join(
+            f"[{message.role.value}] {message.content[:2000]}"
+            for message in messages if message.content
+        )
+        completion = collapse(self.gateway.stream(
+            [Message.system(COMPACT_PROMPT), Message.user(transcript)],
+            model=self.config.model, temperature=0.2, max_tokens=1500,
+        ))
+        return completion.text
+
+    def _emit_usage(self, system_prompt: str, specs: list[ToolSpec]) -> None:
+        limit = self.config.agent.context_limit or 128_000
+        used = self.conversation.used_tokens(system_prompt, specs)
+        usage = self.conversation.usage
+        self.bus.emit(
+            Kind.USAGE,
+            context_used=used,
+            context_limit=limit,
+            fill=min(1.0, used / limit) if limit else 0.0,
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            cost_usd=usage.cost_usd,
+        )
+
+    def _note(self, text: str) -> None:
+        self.bus.emit(Kind.NOTICE, text=text)
+
+    # -- learning --------------------------------------------------------- #
+
+    def _recall(self, user_text: str) -> str:
+        """Apply anything the user changed, then build the memory block.
+
+        The order matters. Corrections are folded in *before* recall, so a fix
+        the user made a minute ago governs the answer they are about to get,
+        rather than the one after that.
+        """
+        if self.memory is None or not self.config.learning.enabled:
+            return ""
+
+        try:
+            self.memory.before_turn(user_text)
+        except Exception:
+            pass
+
+        try:
+            # The UI usually computed this while the user was still typing.
+            lessons = self.memory.take_prefetched(user_text)
+            if lessons is None:
+                lessons = self.memory.recall(user_text)
+            rules = self.memory.active_rules()
+        except Exception:
+            return ""
+
+        self._recalled = lessons
+        if lessons:
+            self.bus.emit(Kind.MEMORY, action="recalled",
+                          items=[lesson.as_dict() for lesson in lessons],
+                          rules=len(rules))
+        if not lessons and not rules:
+            return ""
+        return self.memory.render_playbook(lessons, rules=rules)
+
+    def _learn(self, user_text: str, result: TurnResult) -> None:
+        """Credit the lessons that were in play, then reflect on the episode."""
+        if self.memory is None or not self.config.learning.enabled:
+            return
+        approvals, _ = self.permissions.take_stats()
+        try:
+            self.memory.record_outcome(
+                goal=user_text,
+                messages=self.conversation.messages,
+                recalled=self._recalled,
+                success=result.ok and result.stopped == "done",
+                stopped=result.stopped,
+                steps=result.steps,
+                elapsed=result.elapsed,
+                approvals=approvals,
+                tokens=self.conversation.usage.total,
+            )
+        except Exception:
+            # Learning is a background nicety; it must never break a turn.
+            pass
+
+
+def make_summariser(gateway: Gateway, model: str) -> Callable[[list[Message]], str]:
+    """Standalone summariser, used by session export and tests."""
+    from ..providers.base import collapse
+
+    def summarise(messages: list[Message]) -> str:
+        transcript = "\n\n".join(f"[{m.role.value}] {m.content[:2000]}"
+                                 for m in messages if m.content)
+        return collapse(gateway.stream(
+            [Message.system(COMPACT_PROMPT), Message.user(transcript)],
+            model=model, temperature=0.2, max_tokens=1500,
+        )).text
+
+    return summarise