comodor 0.7.0__tar.gz → 0.8.0__tar.gz

{comodor-0.7.0 → comodor-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comodor
-Version: 0.7.0
+Version: 0.8.0
 Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
 Project-URL: Homepage, https://comodor.ai
 Project-URL: Repository, https://github.com/ifekri/Comodor
@@ -310,8 +310,14 @@ comodor mcp catalogue                      # twelve servers, ready to go
 comodor mcp add filesystem --path ~/work
 comodor mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=…
 comodor mcp custom my-server uvx my-package   # anything else
+comodor mcp remote team https://mcp.example.com/mcp --token …   # a hosted one
 ```
 
+A server can be a command to launch or a URL to reach. Hosted servers are
+spoken to over Streamable HTTP, session header and all, and a plain `http://`
+endpoint that is not on this machine is refused — the token and everything the
+tools return would cross in the clear.
+
 | | |
 |---|---|
 | **Files and code** | Filesystem · Git · GitHub |
@@ -451,6 +457,127 @@ comodor --provider groq --model llama-3.3-70b-versatile
 
 ---
 
+## A browser, and the reason it is not screenshots
+
+Comodor drives a real Chrome — one that runs JavaScript, keeps cookies and can
+log in. It does not download one: it uses the Chrome, Chromium, Edge or Brave
+already on the machine, in a profile of its own that is signed into nothing.
+There is no Playwright, no Selenium, no node. The DevTools protocol is JSON-RPC
+over a WebSocket, and a WebSocket is a handshake and a frame format.
+
+The usual design is to send a screenshot every step and have the model click a
+coordinate. That is wrong twice, and the second time is measurable.
+
+It is wrong on precision, because a model judging pixels on a resized image
+misses — by a little on an empty page and by a whole button on a dense one, with
+nothing in its answer to say which control it meant.
+
+And it is wrong on cost:
+
+| | whole accessibility tree | **only what is on screen** | a screenshot |
+|---|---|---|---|
+| Hacker News | 8,760 | **933** | 1,365 |
+| a GitHub repository | 18,681 | **778** | 1,365 |
+| a Wikipedia article | 32,342 | **414** | 1,365 |
+
+Note the first column: the page's own accessibility tree, sent whole, costs
+*more* than a picture. The advantage comes from filtering, which is a thing you
+can do to text and cannot do to pixels — half a screenshot answers nothing. So
+what the agent gets is the controls a person could actually see and click: on
+screen, visible, not disabled, named, with the same link in the header and the
+footer counted once. Each one numbered, so the model answers with a number and
+cannot miss.
+
+Screenshots are still there, and still necessary — for the questions that are
+genuinely about appearance. *Does this look right. Is the layout broken. What
+does this chart say.* That is the `look` verb, taken when the question is
+visual rather than on every step, which is the difference between a browser an
+agent can afford and one it cannot.
+
+```
+browse open news.ycombinator.com     → title, text, 93 numbered controls
+browse click 7                       → clicks it, returns the new page
+browse type 3 "search terms" submit  → fills a field and presses Enter
+browse look                          → a screenshot, when that is the question
+browse script "…"                    → JavaScript, when nothing else will do
+```
+
+Set `browser.headless = false` to watch it work, or `browser.port` to a Chrome
+you started yourself — which is how you use one you are already logged into
+without handing over your everyday profile.
+
+---
+
+## In a browser, if you want one
+
+```bash
+comodor web
+```
+
+It opens a page, and the page is the same agent: the terminal interface was
+never the agent, it was one subscriber to an event bus, and a browser is a
+second one. Streaming answers, tool calls as they run, permission prompts you
+approve with a click, the mode switch and the running cost.
+
+No new dependency, and the page loads nothing from the internet — no CDN, no
+font host, no analytics — so it works on a machine that can reach the model and
+nothing else.
+
+**Read this part before you put it on a server.** Comodor runs shell commands
+and edits files. A web interface to it is, literally, a remote code execution
+endpoint: that *is* the feature. So
+
+- it listens on `127.0.0.1` and nothing outside your machine can reach it;
+- every request carries a token generated for that run and never written to
+  disk — it arrives once in the URL, then moves into an `HttpOnly`,
+  `SameSite=Strict` cookie so it leaves the address bar, your history and the
+  referrer of anything the page links to;
+- writing requests need a header no cross-origin form can set, and the
+  preflight grants nobody anything.
+
+There is no TLS. If you bind it anywhere else it says so in as many words and
+tells you what to do instead:
+
+```bash
+ssh -N -L 8765:127.0.0.1:8765 you@your-server    # then open it locally
+```
+
+Which is the right way to use it on a server: run it bound to loopback there,
+and reach it through the tunnel.
+
+---
+
+## Reading that does not stay read
+
+Two of the ways a session gets expensive have nothing to do with the model and
+everything to do with what is kept.
+
+**One tool result is paid for many times.** It is written into the conversation
+once and resent with every request after it, so its price is its size times the
+steps still to come. Reading one ordinary module here cost 23,082 tokens.
+Anything past the budget is now *moved* rather than cut: the whole of it goes
+to a file, and what comes back is the head, the tail and the path. Output that
+was already a file on disk is not copied — the pointer names the original.
+Nothing is lost, which truncation cannot say: the middle of a failing test run
+is exactly where the failure was.
+
+```
+one round of six ordinary calls    29,633 → 10,553 tokens
+```
+
+**Some questions take a lot of reading and very little to answer.** *Which
+module owns retries?* might mean opening nine files to produce one sentence,
+and in the main conversation those nine files are permanent. `delegate` hands
+that to a second agent with its own context and brings back only the sentence.
+
+It cannot write unless told to, and it cannot delegate. Told to, and in a git
+project, it works in a checkout of its own: a real worktree at the same commit,
+and what comes back is a patch — applied here if it applies cleanly, kept aside
+with its path if something moved underneath it. Your working tree is never what
+it experiments in.
+
+---
+
 ## It pays for the same tokens once
 
 An agent loop has a shape that is unusually wasteful, and it is not obvious

{comodor-0.7.0 → comodor-0.8.0}/README.md

@@ -284,8 +284,14 @@ comodor mcp catalogue                      # twelve servers, ready to go
 comodor mcp add filesystem --path ~/work
 comodor mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=…
 comodor mcp custom my-server uvx my-package   # anything else
+comodor mcp remote team https://mcp.example.com/mcp --token …   # a hosted one
 ```
 
+A server can be a command to launch or a URL to reach. Hosted servers are
+spoken to over Streamable HTTP, session header and all, and a plain `http://`
+endpoint that is not on this machine is refused — the token and everything the
+tools return would cross in the clear.
+
 | | |
 |---|---|
 | **Files and code** | Filesystem · Git · GitHub |
@@ -425,6 +431,127 @@ comodor --provider groq --model llama-3.3-70b-versatile
 
 ---
 
+## A browser, and the reason it is not screenshots
+
+Comodor drives a real Chrome — one that runs JavaScript, keeps cookies and can
+log in. It does not download one: it uses the Chrome, Chromium, Edge or Brave
+already on the machine, in a profile of its own that is signed into nothing.
+There is no Playwright, no Selenium, no node. The DevTools protocol is JSON-RPC
+over a WebSocket, and a WebSocket is a handshake and a frame format.
+
+The usual design is to send a screenshot every step and have the model click a
+coordinate. That is wrong twice, and the second time is measurable.
+
+It is wrong on precision, because a model judging pixels on a resized image
+misses — by a little on an empty page and by a whole button on a dense one, with
+nothing in its answer to say which control it meant.
+
+And it is wrong on cost:
+
+| | whole accessibility tree | **only what is on screen** | a screenshot |
+|---|---|---|---|
+| Hacker News | 8,760 | **933** | 1,365 |
+| a GitHub repository | 18,681 | **778** | 1,365 |
+| a Wikipedia article | 32,342 | **414** | 1,365 |
+
+Note the first column: the page's own accessibility tree, sent whole, costs
+*more* than a picture. The advantage comes from filtering, which is a thing you
+can do to text and cannot do to pixels — half a screenshot answers nothing. So
+what the agent gets is the controls a person could actually see and click: on
+screen, visible, not disabled, named, with the same link in the header and the
+footer counted once. Each one numbered, so the model answers with a number and
+cannot miss.
+
+Screenshots are still there, and still necessary — for the questions that are
+genuinely about appearance. *Does this look right. Is the layout broken. What
+does this chart say.* That is the `look` verb, taken when the question is
+visual rather than on every step, which is the difference between a browser an
+agent can afford and one it cannot.
+
+```
+browse open news.ycombinator.com     → title, text, 93 numbered controls
+browse click 7                       → clicks it, returns the new page
+browse type 3 "search terms" submit  → fills a field and presses Enter
+browse look                          → a screenshot, when that is the question
+browse script "…"                    → JavaScript, when nothing else will do
+```
+
+Set `browser.headless = false` to watch it work, or `browser.port` to a Chrome
+you started yourself — which is how you use one you are already logged into
+without handing over your everyday profile.
+
+---
+
+## In a browser, if you want one
+
+```bash
+comodor web
+```
+
+It opens a page, and the page is the same agent: the terminal interface was
+never the agent, it was one subscriber to an event bus, and a browser is a
+second one. Streaming answers, tool calls as they run, permission prompts you
+approve with a click, the mode switch and the running cost.
+
+No new dependency, and the page loads nothing from the internet — no CDN, no
+font host, no analytics — so it works on a machine that can reach the model and
+nothing else.
+
+**Read this part before you put it on a server.** Comodor runs shell commands
+and edits files. A web interface to it is, literally, a remote code execution
+endpoint: that *is* the feature. So
+
+- it listens on `127.0.0.1` and nothing outside your machine can reach it;
+- every request carries a token generated for that run and never written to
+  disk — it arrives once in the URL, then moves into an `HttpOnly`,
+  `SameSite=Strict` cookie so it leaves the address bar, your history and the
+  referrer of anything the page links to;
+- writing requests need a header no cross-origin form can set, and the
+  preflight grants nobody anything.
+
+There is no TLS. If you bind it anywhere else it says so in as many words and
+tells you what to do instead:
+
+```bash
+ssh -N -L 8765:127.0.0.1:8765 you@your-server    # then open it locally
+```
+
+Which is the right way to use it on a server: run it bound to loopback there,
+and reach it through the tunnel.
+
+---
+
+## Reading that does not stay read
+
+Two of the ways a session gets expensive have nothing to do with the model and
+everything to do with what is kept.
+
+**One tool result is paid for many times.** It is written into the conversation
+once and resent with every request after it, so its price is its size times the
+steps still to come. Reading one ordinary module here cost 23,082 tokens.
+Anything past the budget is now *moved* rather than cut: the whole of it goes
+to a file, and what comes back is the head, the tail and the path. Output that
+was already a file on disk is not copied — the pointer names the original.
+Nothing is lost, which truncation cannot say: the middle of a failing test run
+is exactly where the failure was.
+
+```
+one round of six ordinary calls    29,633 → 10,553 tokens
+```
+
+**Some questions take a lot of reading and very little to answer.** *Which
+module owns retries?* might mean opening nine files to produce one sentence,
+and in the main conversation those nine files are permanent. `delegate` hands
+that to a second agent with its own context and brings back only the sentence.
+
+It cannot write unless told to, and it cannot delegate. Told to, and in a git
+project, it works in a checkout of its own: a real worktree at the same commit,
+and what comes back is a patch — applied here if it applies cleanly, kept aside
+with its path if something moved underneath it. Your working tree is never what
+it experiments in.
+
+---
+
 ## It pays for the same tokens once
 
 An agent loop has a shape that is unusually wasteful, and it is not obvious

{comodor-0.7.0 → comodor-0.8.0}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.7.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)
 
 __commit_id__ = commit_id = None

{comodor-0.7.0 → comodor-0.8.0}/src/comodor/agent/loop.py

@@ -257,10 +257,17 @@ class AgentLoop:
             results = [self._run_one(call, context) for call in calls]
 
         for call, result in zip(calls, results):
-            self.conversation.add(Message.tool(
+            message = Message.tool(
                 call_id=call.id, name=call.name,
                 content=result.content, is_error=not result.ok,
-            ))
+            )
+            # A tool that produced a picture — a screenshot of a page — sends
+            # it as one. Where the dialect allows an image beside a tool result
+            # it goes there; where it does not, the adapter moves it.
+            picture = result.meta.get("image")
+            if isinstance(picture, str) and picture:
+                message.images = [picture]
+            self.conversation.add(message)
 
     def _run_one(self, call: ToolCall, context: ToolContext) -> ToolResult:
         self.bus.emit(Kind.TOOL_START, id=call.id, name=call.name,
@@ -416,10 +423,21 @@ class AgentLoop:
         if not matched:
             return ""
 
-        self._skills_used = matched
-        self.bus.emit(Kind.MEMORY, action="skills",
-                      items=[skill.as_dict() for skill in matched])
-        return self.skills.render(matched, max_tokens=settings.max_tokens)
+        kept, dropped = self.skills.fit(matched, settings.max_tokens)
+        for skill in dropped:
+            # Naming the setting, because the fix is one number and the user
+            # has no other way to discover that their skill never arrived.
+            self._note(f"{skill.name} matched but is too large for the "
+                       f"{settings.max_tokens:,}-token skill budget — raise "
+                       f"skills.max_tokens to use it.")
+
+        # Announced from what actually travelled. Announcing the match instead
+        # tells the user a skill is shaping the answer when it was discarded.
+        self._skills_used = kept
+        if kept:
+            self.bus.emit(Kind.MEMORY, action="skills",
+                          items=[skill.as_dict() for skill in kept])
+        return self.skills.render(kept, max_tokens=settings.max_tokens)
 
     def _learn(self, user_text: str, result: TurnResult) -> None:
         """Credit the lessons that were in play, then reflect on the episode."""

comodor-0.8.0/src/comodor/agent/spawn.py

@@ -0,0 +1,64 @@
+"""Building a delegate, which the tool layer must not know how to do.
+
+The `delegate` tool needs a whole second agent — a gateway, a tool registry, a
+permission engine, a conversation — and a tool has none of those and should not
+learn. So it is handed a callable and knows only that calling it returns
+something with a ``run``.
+
+What a delegate does *not* inherit is as deliberate as what it does:
+
+* **No brain.** It does not recall lessons and it does not reflect afterwards.
+  A delegate's episode is half a task seen out of context, and reflecting on it
+  teaches the brain about a fragment. The parent's own turn is the episode
+  worth learning from, and it still is one.
+* **No delegating.** One level deep. A tree of agents is a way to spend an
+  afternoon's budget in ninety seconds, and nothing else in the design stops it.
+* **No history search.** It cannot see this conversation; letting it search
+  every past one instead is a strange kind of amnesia.
+* **The parent's cancellation.** Escape stops the whole thing, not the outer
+  loop while a delegate keeps working somewhere with a shell open.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from ..events import Cancellation, EventBus
+from ..paths import Paths
+from ..safety import PermissionEngine
+from ..tools import ToolRegistry
+
+
+def spawner(config: Any, gateway: Any, bus: EventBus, skills: Any = None,
+            mcp: Any = None) -> Any:
+    """Return the callable the `delegate` tool is constructed with."""
+
+    def spawn(cwd: Path, mode: str = "plan", max_steps: int = 8,
+              max_seconds: float = 300.0,
+              cancel: Cancellation | None = None) -> Any:
+        from .context import Conversation
+        from .loop import AgentLoop
+
+        settings = copy.deepcopy(config)
+        settings.paths = replace(settings.paths, project=Path(cwd)) \
+            if isinstance(settings.paths, Paths) else settings.paths
+        settings.agent.mode = mode
+        settings.agent.max_steps = max_steps
+        settings.agent.max_seconds = max_seconds
+        settings.agent.loop = True
+        # Its answer is prose for another agent to read, not a report for a
+        # person, so it does not need the parent's output allowance.
+        settings.agent.max_output_tokens = min(settings.agent.max_output_tokens, 4096)
+
+        tools = ToolRegistry(skills=skills, mcp=mcp)
+        loop = AgentLoop(settings, gateway, tools, bus,
+                         PermissionEngine(settings, bus), Conversation(),
+                         memory=None, skills=skills)
+        if cancel is not None:
+            loop.cancel = cancel
+        return loop
+
+    return spawn

comodor-0.8.0/src/comodor/browser/__init__.py

@@ -0,0 +1,7 @@
+"""A real browser, driven with nothing but the standard library."""
+
+from .cdp import BrowserError, Session
+from .launch import Browser
+from .page import Element, Page, Snapshot
+
+__all__ = ["Browser", "BrowserError", "Element", "Page", "Session", "Snapshot"]