2b-agent 0.2.3__tar.gz → 0.2.4__tar.gz

{2b_agent-0.2.3 → 2b_agent-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: 2b-agent
-Version: 0.2.3
+Version: 0.2.4
 Summary: A local-first coding agent that keeps small local models focused instead of hallucinating.
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -106,6 +106,14 @@ model has to understand.
 - **Runs things — split by model.** Local models get `run_git` (git only, never a raw shell — no
   chaining/injection); cloud models get a full `run_command` shell (tests, build, git). Read-only git
   runs freely; anything that mutates is confirmation-gated and refused in plan mode.
+- **Delegates read-only exploration (cloud).** On the cloud path the model can `delegate` one or
+  more investigations to run in parallel, each in its own isolated context, and get back short
+  findings — so a big search-and-read never bloats the main conversation. Each sub-agent can only
+  `list_files`, `read_file`, and `search_files`; local models keep their frozen five tools
+  untouched, and delegation is cloud-only for now.
+- **Cheaper multi-turn cloud sessions.** Anthropic requests mark the system prompt and tool
+  definitions as cacheable, so a long conversation pays full price for that stable prefix once
+  instead of on every turn.
 - **MCP tools, curated.** Pull in tools from MCP servers (dart, mempalace, …) — but **per tool**, not
   wholesale, because flooding a small model with tools is exactly what breaks it. You enable a server
   and pick which of its tools the model sees (`/mcp`); local models are capped to a few so their

{2b_agent-0.2.3 → 2b_agent-0.2.4}/README.md

@@ -92,6 +92,14 @@ model has to understand.
 - **Runs things — split by model.** Local models get `run_git` (git only, never a raw shell — no
   chaining/injection); cloud models get a full `run_command` shell (tests, build, git). Read-only git
   runs freely; anything that mutates is confirmation-gated and refused in plan mode.
+- **Delegates read-only exploration (cloud).** On the cloud path the model can `delegate` one or
+  more investigations to run in parallel, each in its own isolated context, and get back short
+  findings — so a big search-and-read never bloats the main conversation. Each sub-agent can only
+  `list_files`, `read_file`, and `search_files`; local models keep their frozen five tools
+  untouched, and delegation is cloud-only for now.
+- **Cheaper multi-turn cloud sessions.** Anthropic requests mark the system prompt and tool
+  definitions as cacheable, so a long conversation pays full price for that stable prefix once
+  instead of on every turn.
 - **MCP tools, curated.** Pull in tools from MCP servers (dart, mempalace, …) — but **per tool**, not
   wholesale, because flooding a small model with tools is exactly what breaks it. You enable a server
   and pick which of its tools the model sees (`/mcp`); local models are capped to a few so their

{2b_agent-0.2.3 → 2b_agent-0.2.4}/src/two_b/__init__.py

@@ -5,4 +5,4 @@ host keeps the model's world simple — a small, native tool schema over the
 provider's own wire format, with all orchestration complexity kept host-side.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"

{2b_agent-0.2.3 → 2b_agent-0.2.4}/src/two_b/orchestrator.py

@@ -33,7 +33,7 @@ from . import diagnostics, mcp_client, planparse, registry, tools
 from .conversation import Conversation, Message, Role, ToolResult
 from .providers.base import ProviderError
 from .session import PendingConfirmation, Session, Task, TaskState
-from .toolspec import TOOL_SPECS, specs_for
+from .toolspec import TOOL_SPECS, specs_for, DELEGATE_SPEC
 
 MAX_TURNS = 40          # generous budget for real multi-step tasks
 DEFAULT_MODEL = "qwen3.5:9b"
@@ -158,11 +158,13 @@ def _project_context() -> str:
 
 def _active_specs(is_local: bool):
     """Base file tools + the model's exec tool + curated MCP tools. Local models
-    get a small MCP cap so a big enabled set can't flood their tool list."""
+    get a small MCP cap so a big enabled set can't flood their tool list.
+    delegate (fan-out to sub-agents) is exposed to cloud models only."""
     mcp = mcp_client.manager.tool_specs()
     if is_local:
         mcp = mcp[:MCP_LOCAL_CAP]
-    return specs_for(is_local) + mcp
+    base = specs_for(is_local) + mcp
+    return base if is_local else base + (DELEGATE_SPEC,)
 
 
 def context_budget(provider, model: str) -> int:
@@ -512,7 +514,12 @@ def run_task(session: Session, task: Task, on_event: Callable[[AgentEvent], None
                 task.status_line = _STATUS.get(tc.name, "Working")
                 shown = {k: (v if k != "content" else f"<{len(v)} chars>") for k, v in tc.arguments.items()}
                 on_event(AgentEvent(EventType.TOOL_CALL_START, task.id, {"name": tc.name, "shown": shown}))
-                result = _dispatch_tool(session, task, tc.name, tc.arguments, read_cap)
+                if tc.name == "delegate" and not is_local:
+                    from . import subagents
+                    result = subagents.delegate(tc.arguments.get("tasks", []), provider, model,
+                                                read_cap=read_cap, on_event=on_event, cancel=task.cancel_flag)
+                else:
+                    result = _dispatch_tool(session, task, tc.name, tc.arguments, read_cap)
                 on_event(AgentEvent(EventType.TOOL_CALL_RESULT, task.id, {"name": tc.name, "result": result}))
                 results.append(ToolResult(tool_call_id=tc.id, content=result))
             conv.append(Message.results(results))

{2b_agent-0.2.3 → 2b_agent-0.2.4}/src/two_b/providers/anthropic.py

@@ -55,11 +55,20 @@ class AnthropicProvider:
         return out
 
     def send(self, conversation: Conversation, model: str, tools: tuple[ToolSpec, ...]) -> ProviderResponse:
+        # Prompt caching (GA — no beta header needed): mark the stable prefix
+        # (system prompt, last tool definition) with cache_control so repeated
+        # requests reuse Anthropic's cache instead of paying full price every
+        # turn. OpenAI-compatible providers cache automatically server-side —
+        # no payload change needed there.
+        tools_json = to_anthropic(tools)
+        if tools_json:
+            tools_json[-1] = {**tools_json[-1], "cache_control": {"type": "ephemeral"}}
         payload = {
             "model": model,
             "max_tokens": 4096,
-            "system": conversation.system_prompt,
-            "tools": to_anthropic(tools),
+            "system": [{"type": "text", "text": conversation.system_prompt,
+                        "cache_control": {"type": "ephemeral"}}],
+            "tools": tools_json,
             "messages": self._messages(conversation),
         }
         raw = post_json(API_URL, payload, headers=self._headers(), provider=self.name)

2b_agent-0.2.4/src/two_b/subagents.py

@@ -0,0 +1,110 @@
+"""Cloud-path subagents: parallel, isolated read-only explorers behind the `delegate`
+tool. Each runs in its own Conversation with only the read tools and returns a distilled
+findings report — heavy file reading happens here and never enters the parent context."""
+from __future__ import annotations
+import concurrent.futures
+import threading
+from . import tools
+from .conversation import Conversation, Message, ToolResult
+
+EXPLORER_PROMPT = (
+    "You are a read-only exploration agent. Investigate the goal using list_files, "
+    "read_file, and search_files, then STOP and reply with a concise findings report: "
+    "what you found, the concrete file:line references, and anything the caller needs. "
+    "You cannot edit, write, or run commands. Keep the report short — it is folded back "
+    "into another agent's context, so summarize; do not paste large file bodies."
+)
+
+def _read_dispatch(name: str, args: dict, read_cap: int | None) -> str:
+    if name == "list_files":
+        return tools.do_list_files(args.get("path", "."), max_chars=read_cap)
+    if name == "read_file":
+        return tools.do_read_file(args["path"], max_chars=read_cap)
+    if name == "search_files":
+        return tools.do_search_files(args["query"], args.get("path", "."))
+    return f"error: '{name}' is not available to an explorer (read-only)"
+
+
+def run_explorer(goal, provider, model, read_cap=None, max_turns=8, cancel=None):
+    conv = Conversation(system_prompt=EXPLORER_PROMPT)
+    conv.append(Message.user(goal))
+    specs = tuple(s for s in _explorer_specs())          # read-only tool specs
+    for _ in range(max_turns):
+        if cancel is not None and cancel.is_set():
+            return "explorer cancelled"
+        resp = provider.stream(conv, model, specs, lambda _c: None)
+        msg = resp.message
+        conv.append(msg)
+        if not msg.tool_calls:
+            return (msg.text or "").strip() or "(explorer produced no findings)"
+        results = [ToolResult(tool_call_id=tc.id,
+                              content=_read_dispatch(tc.name, tc.arguments, read_cap))
+                   for tc in msg.tool_calls]
+        conv.append(Message.results(results))
+    return "(explorer hit its turn limit without a final report)"
+
+
+def _explorer_specs():
+    from .toolspec import TOOL_SPECS
+    keep = {"list_files", "read_file", "search_files"}
+    return [s for s in TOOL_SPECS if s.name in keep]
+
+
+class _AnyEvent:
+    """Read-only OR of several threading.Events: is_set() is True if any is set.
+    Lets an explorer honor both the parent task's cancel (esc) and delegate's own
+    batch-timeout signal, while delegate only ever sets its OWN event."""
+    def __init__(self, *events):
+        self._events = [e for e in events if e is not None]
+    def is_set(self) -> bool:
+        return any(e.is_set() for e in self._events)
+
+
+MAX_PARALLEL = 4
+DELEGATE_TIMEOUT = 180  # seconds, wall-clock budget for the whole batch
+_MAX_SECTION = 4000
+
+
+def delegate(tasks, provider, model, read_cap=None, on_event=None, cancel=None) -> str:
+    tasks = [t for t in (tasks or []) if isinstance(t, dict) and t.get("goal")]
+    if not tasks:
+        return "error: delegate needs at least one {role, goal} task"
+
+    sub_cancel = threading.Event()
+    combined = _AnyEvent(cancel, sub_cancel)
+
+    def _one(t):
+        role, goal = (t.get("role") or "explore"), t["goal"]
+        if role == "work":
+            return role, goal, "(worker delegation is not enabled yet — Phase 2)"
+        try:
+            return role, goal, run_explorer(goal, provider, model, read_cap=read_cap, cancel=combined)
+        except Exception as e:  # a subagent failing must not kill the batch
+            return role, goal, f"(explorer error: {str(e)[:200]})"
+
+    # Not a `with` block on purpose: ThreadPoolExecutor.__exit__ calls
+    # shutdown(wait=True), which would block on any straggler exactly like the
+    # timeout below is meant to avoid. We call shutdown() exactly once, with
+    # wait=False, so this function returns as soon as the batch timeout hits.
+    results: list[tuple[str, str, str] | None] = [None] * len(tasks)
+    ex = concurrent.futures.ThreadPoolExecutor(max_workers=MAX_PARALLEL)
+    futures = {ex.submit(_one, t): i for i, t in enumerate(tasks)}
+    try:
+        for fut in concurrent.futures.as_completed(futures, timeout=DELEGATE_TIMEOUT):
+            results[futures[fut]] = fut.result()
+    except concurrent.futures.TimeoutError:
+        sub_cancel.set()
+    finally:
+        ex.shutdown(wait=False, cancel_futures=True)
+
+    lines = [f"## delegate results ({len(results)} task(s))"]
+    for i, (t, r) in enumerate(zip(tasks, results), 1):
+        if r is None:
+            role, goal = (t.get("role") or "explore"), t["goal"]
+            out = "(timed out)"
+        else:
+            role, goal, out = r
+            if len(out) > _MAX_SECTION:
+                out = out[:_MAX_SECTION] + " …[truncated]"
+        lines.append(f"\n### [{i}] {role}: {goal}\n{out}")
+    return "\n".join(lines)

{2b_agent-0.2.3 → 2b_agent-0.2.4}/src/two_b/toolspec.py

@@ -123,3 +123,30 @@ def to_gemini(specs: tuple[ToolSpec, ...] = TOOL_SPECS) -> list[dict]:
 
 # Guarantee the local-Ollama payload is byte-identical to the proven constant.
 assert to_openai() == tools.TOOLS, "toolspec.to_openai() drifted from tools.TOOLS"
+
+
+DELEGATE_SPEC = ToolSpec(
+    "delegate",
+    "Run one or more independent sub-tasks in parallel, each in its own isolated context. "
+    "role 'explore' investigates read-only and returns a concise findings report — use it to "
+    "locate code or understand a flow without reading everything into this conversation. "
+    "role 'work' is reserved. Returns a digest of each task's result.",
+    raw_schema={
+        "type": "object",
+        "properties": {
+            "tasks": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "role": {"type": "string", "enum": ["explore", "work"]},
+                        "goal": {"type": "string", "description": "What to find/understand (explore) — a clear, self-contained instruction."},
+                    },
+                    "required": ["goal"],
+                },
+                "description": "Independent sub-tasks run in parallel.",
+            }
+        },
+        "required": ["tasks"],
+    },
+)

2b_agent-0.2.4/tests/test_delegate_wiring.py

@@ -0,0 +1,32 @@
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from two_b import orchestrator
+
+
+class Exposure(unittest.TestCase):
+    def test_local_has_no_delegate(self):
+        names = [s.name for s in orchestrator._active_specs(is_local=True)]
+        self.assertNotIn("delegate", names)
+        self.assertEqual(
+            names[:6],
+            ["list_files", "read_file", "search_files", "edit_file", "write_file", "run_git"],
+        )
+
+    def test_cloud_has_delegate(self):
+        names = [s.name for s in orchestrator._active_specs(is_local=False)]
+        self.assertIn("delegate", names)
+
+    def test_frozen_schema_still_holds(self):
+        # two_b.tools import triggers the toolspec.py assert (to_openai() == tools.TOOLS)
+        import two_b.tools as tools
+        from two_b.toolspec import to_openai, TOOL_SPECS
+        self.assertEqual(to_openai(), tools.TOOLS)
+        self.assertNotIn("delegate", [s.name for s in TOOL_SPECS])
+
+
+if __name__ == "__main__":
+    unittest.main()

2b_agent-0.2.4/tests/test_prompt_cache.py

@@ -0,0 +1,16 @@
+import os, sys, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from two_b.providers import anthropic as A
+from two_b.conversation import Conversation
+from two_b.toolspec import TOOL_SPECS
+
+
+class Cache(unittest.TestCase):
+    def test_system_and_tools_cached(self):
+        captured = {}
+        A.post_json = lambda url, payload, **k: captured.setdefault("p", payload) or {"content": [{"type": "text", "text": "ok"}]}
+        os.environ["ANTHROPIC_API_KEY"] = "x"
+        A.AnthropicProvider().send(Conversation(system_prompt="SYS"), "claude-sonnet-5", tuple(TOOL_SPECS))
+        p = captured["p"]
+        self.assertEqual(p["system"][-1]["cache_control"], {"type": "ephemeral"})
+        self.assertEqual(p["tools"][-1]["cache_control"], {"type": "ephemeral"})

2b_agent-0.2.4/tests/test_subagents.py

@@ -0,0 +1,78 @@
+import os, sys, tempfile, unittest
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+from two_b import subagents
+
+class ReadDispatch(unittest.TestCase):
+    def test_write_tools_refused(self):
+        self.assertIn("not available", subagents._read_dispatch("edit_file", {"path":"x"}, None))
+        self.assertIn("not available", subagents._read_dispatch("run_command", {"command":"ls"}, None))
+    def test_read_tools_allowed(self):
+        d = tempfile.mkdtemp()
+        with open(os.path.join(d, "a.py"), "w") as f:
+            f.write("x=1\n")
+        out = subagents._read_dispatch("list_files", {"path": d}, None)
+        self.assertIn("a.py", out)
+
+
+class RunExplorer(unittest.TestCase):
+    def test_loops_then_returns_final_text(self):
+        from two_b.conversation import Message, ToolCall
+        calls = iter([
+            Message.assistant(tool_calls=[ToolCall.new("search_files", {"query":"Widget"})]),
+            Message.assistant(text="Widget is defined in a.py:1"),
+        ])
+        class FakeProvider:
+            name = "anthropic"
+            def stream(self, conv, model, tools_, on_text):
+                from two_b.providers.base import ProviderResponse
+                return ProviderResponse(message=next(calls), raw={})
+        out = subagents.run_explorer("find Widget", FakeProvider(), "m")
+        self.assertEqual(out, "Widget is defined in a.py:1")
+
+
+class Delegate(unittest.TestCase):
+    def setUp(self):
+        self._orig_run_explorer = subagents.run_explorer
+
+    def tearDown(self):
+        subagents.run_explorer = self._orig_run_explorer
+
+    def test_digest_has_one_section_per_task(self):
+        subagents.run_explorer = lambda goal, *a, **k: f"found: {goal}"   # stub
+        out = subagents.delegate(
+            [{"role":"explore","goal":"A"}, {"role":"explore","goal":"B"}],
+            provider=None, model="m")
+        self.assertIn("A", out); self.assertIn("B", out)
+        self.assertIn("found: A", out); self.assertIn("found: B", out)
+
+    def test_work_role_stubbed(self):
+        out = subagents.delegate([{"role":"work","goal":"edit x"}], provider=None, model="m")
+        self.assertIn("not enabled yet", out)
+
+    def test_batch_failure_isolation(self):
+        def flaky(goal, *a, **k):
+            if goal == "bad":
+                raise RuntimeError("boom")
+            return f"found: {goal}"
+        subagents.run_explorer = flaky
+        out = subagents.delegate(
+            [{"role": "explore", "goal": "bad"}, {"role": "explore", "goal": "good"}],
+            provider=None, model="m")
+        self.assertIn("### [1] explore: bad", out)
+        self.assertIn("explorer error", out)
+        self.assertIn("### [2] explore: good", out)
+        self.assertIn("found: good", out)
+
+    def test_batch_timeout_does_not_touch_parent_cancel(self):
+        import threading, time
+        from two_b import subagents
+        parent = threading.Event()
+        subagents.run_explorer = lambda goal, *a, **k: (time.sleep(0.5) or "late")  # slower than the tiny budget
+        orig = subagents.DELEGATE_TIMEOUT
+        subagents.DELEGATE_TIMEOUT = 0.05
+        try:
+            out = subagents.delegate([{"role":"explore","goal":"slow"}], provider=None, model="m", cancel=parent)
+        finally:
+            subagents.DELEGATE_TIMEOUT = orig
+        self.assertFalse(parent.is_set())          # parent task must NOT be cancelled
+        self.assertIn("(timed out)", out)