@steerable/runtime-darwin-arm64 0.10.3 → 0.11.0

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/peer.py

@@ -0,0 +1,192 @@
+"""Tree-wide messaging, as a tool layer any agent in the job can carry.
+
+The spawn tree (``tree.py``) decides who is reachable; this module is what
+puts that decision in front of a model. It lives apart from
+``orchestration.py`` because messaging and delegating are different
+permissions that happen to share a tree:
+
+- delegating is bounded by depth — a ``max_depth=1`` child must not spawn;
+- messaging is not — the whole point of a shared tree is that a worker can
+  hand a finding to a sibling or answer the agent that spawned it.
+
+Two surfaces carry it. ``OrchestrationExecutor`` answers these names where it
+advertises the full family; ``PeerToolsExecutor`` wraps a child that gets no
+family at all (a depth-limited worker, or a ``delegate_subagent`` child),
+giving it exactly ``agent_send`` and ``agent_list``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from steerable_agent_protocol.generated import ToolCall, ToolResult
+
+from .loop import LoopContext, ToolExecutor
+from .pool import OrchestrationConfig
+from .tree import AgentTree
+
+__all__ = [
+    "PeerToolsExecutor",
+    "peer_schemas",
+    "send_tool_descriptor",
+    "tool_schema",
+]
+
+
+def tool_schema(
+    name: str, description: str, properties: dict, required: list[str]
+) -> dict[str, Any]:
+    """One OpenAI function schema.
+
+    Shared by the three tool families so their JSON has one shape — a host
+    that strict-validates ``additionalProperties: false`` should not have to
+    special-case which family a schema came from.
+    """
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+                "additionalProperties": False,
+            },
+        },
+    }
+
+
+def send_tool_descriptor(config: OrchestrationConfig) -> dict[str, Any]:
+    """Schema for ``agent_send``, described as tree-wide rather than downward.
+
+    The description is the documentation a model actually reads: it has to say
+    that a sibling and the root are addressable, or a worker will keep routing
+    every fact through the parent — the behaviour this slice exists to remove.
+    """
+    return tool_schema(
+        config.send_tool,
+        "Send a message to another agent in this job. A running agent "
+        "receives it at its next round boundary (steer); a finished or "
+        "interrupted one is resumed with the message as a follow-up turn, "
+        "keeping its prior context. Any member of the job is addressable by "
+        "lineage id — `0` is the agent that started it, `0.2` a sibling, "
+        "`0.2.1` a child — so workers can hand facts to each other instead of "
+        "routing everything through the parent. Call agent_list to see the "
+        "ids. Closed agents reject sends.",
+        {
+            "childId": {
+                "type": "string",
+                "description": "Lineage id of the target agent (`0`, `0.2`, `0.2.1`).",
+            },
+            "message": {"type": "string"},
+        },
+        ["childId", "message"],
+    )
+
+
+def peer_schemas(config: OrchestrationConfig) -> list[dict[str, Any]]:
+    """The two schemas a leaf agent is advertised: send and list."""
+    return [
+        send_tool_descriptor(config),
+        tool_schema(
+            config.list_tool,
+            "List the agents in this job with their lineage id, depth and "
+            "profile — the ids `agent_send` accepts. `self` is your own id.",
+            {},
+            [],
+        ),
+    ]
+
+
+class PeerToolsExecutor:
+    """ToolExecutor decorator: ``agent_send`` / ``agent_list`` over a tree.
+
+    For an agent that has no orchestration family — a depth-limited worker, or
+    a ``delegate_subagent`` child — and therefore no other way to speak to a
+    peer. Nested agents do not use it: their ``OrchestrationExecutor`` already
+    answers both names, and wrapping twice would answer once too often.
+    """
+
+    def __init__(
+        self,
+        inner: ToolExecutor,
+        tree: AgentTree,
+        config: OrchestrationConfig,
+        *,
+        lineage: str,
+    ) -> None:
+        self._inner = inner
+        self._tree = tree
+        self._config = config
+        #: Who this agent is on the tree, so the tree can refuse a self-send
+        #: and the result can name the sender.
+        self._lineage = lineage
+
+    async def execute(self, call: ToolCall, ctx: LoopContext) -> ToolResult:
+        if call.name == self._config.send_tool:
+            return await self._send(call)
+        if call.name == self._config.list_tool:
+            return self._list()
+        return await self._inner.execute(call, ctx)
+
+    async def _send(self, call: ToolCall) -> ToolResult:
+        target = str(call.arguments.get("childId") or "").strip()
+        message = str(call.arguments.get("message") or "").strip()
+        if not message:
+            return ToolResult(success=False, error="empty message")
+        # The tree owns reachability: its refusal already names every address
+        # this agent has (and covers a self-send), which is what lets a model
+        # that guessed an id correct itself in the same turn.
+        verdict = await self._tree.send(self._lineage, target, message)
+        if verdict.startswith("error:"):
+            return ToolResult(
+                success=False,
+                error=verdict[len("error:"):],
+                needsFollowup=True,
+            )
+        member = self._tree.get(target)
+        return ToolResult(
+            success=True,
+            message=json.dumps(
+                {
+                    "childId": target,
+                    "delivery": verdict,
+                    **({"depth": member.depth} if member is not None else {}),
+                }
+            ),
+            data={"childId": target, "delivery": verdict},
+        )
+
+    def _list(self) -> ToolResult:
+        """Every live member, with this agent's own id.
+
+        ``children`` is present and empty so a leaf and a nested agent answer
+        the same tool with the same keys; a host that reads only that key sees
+        an honest "none", not a missing field.
+        """
+        members = [member.to_wire() for member in self._tree.members()]
+        return ToolResult(
+            success=True,
+            message=json.dumps(
+                {"children": [], "members": members, "self": self._lineage}
+            ),
+            data={"count": 0},
+        )
+
+    def dedup_exempt(self, call: ToolCall) -> bool:
+        # A send is stateful: the same message twice is two deliveries, and a
+        # repeated list must observe what a send changed.
+        if call.name in {self._config.send_tool, self._config.list_tool}:
+            return True
+        inner_exempt = getattr(self._inner, "dedup_exempt", None)
+        return bool(inner_exempt and inner_exempt(call))
+
+    def concurrency_safe(self, call: ToolCall) -> bool:
+        # A send mutates another agent's inbox and, on resume, awaits its
+        # first step; serial execution keeps the order the model emitted.
+        if call.name in {self._config.send_tool, self._config.list_tool}:
+            return False
+        inner_safe = getattr(self._inner, "concurrency_safe", None)
+        return bool(inner_safe and inner_safe(call))

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/pool.py

@@ -54,6 +54,7 @@ from .history import HistorySeed, entry_to_dict
 from .llm import LLMMessage, LLMUsage
 from .loop import CoreLoop
 from .registry import ChildRegistry, SpawnedChild, default_record_id, registry_status
+from .tree import AgentTree, TreeMember
 
 logger = logging.getLogger(__name__)
 
@@ -101,6 +102,12 @@ class OrchestrationConfig:
     close_tool: str = "agent_close"
     list_tool: str = "agent_list"
     interrupt_tool: str = "agent_interrupt"
+    #: R8 shared task board. Advertised only when a board is wired; the names
+    #: are configurable so a host can avoid colliding with its own tools.
+    task_create_tool: str = "team_task_create"
+    task_claim_tool: str = "team_task_claim"
+    task_complete_tool: str = "team_task_complete"
+    task_list_tool: str = "team_task_list"
 
     @property
     def tool_names(self) -> frozenset[str]:
@@ -115,6 +122,19 @@ class OrchestrationConfig:
             }
         )
 
+    @property
+    def team_tool_names(self) -> frozenset[str]:
+        """The four board tools — separate so a nested child narrows its
+        orchestration family without losing the shared plan."""
+        return frozenset(
+            {
+                self.task_create_tool,
+                self.task_claim_tool,
+                self.task_complete_tool,
+                self.task_list_tool,
+            }
+        )
+
 
 @dataclass(frozen=True, slots=True)
 class ChildOutcome:
@@ -226,6 +246,7 @@ class AgentPool:
         parent_record_id: str | None = None,
         budget: TreeBudget | None = None,
         history_store: Any | None = None,
+        tree: AgentTree | None = None,
     ) -> None:
         self._config = config
         self._depth = depth
@@ -264,6 +285,22 @@ class AgentPool:
         #: into the child's own record; ``None`` keeps the legacy behaviour
         #: (the seed is just the child's opening messages).
         self._history_store = history_store
+        #: Tree-wide addressing, shared by every pool in one spawn tree. Each
+        #: pool registers the children it owns, so a peer message reaches an
+        #: agent through the owner that can actually steer or resume it.
+        #: ``None`` keeps the pre-R8 behaviour: only this pool's own children
+        #: are addressable.
+        self._tree = tree
+
+    @property
+    def tree(self) -> AgentTree | None:
+        """The tree this pool's children register into, or ``None``.
+
+        Exposed so another surface that shares this pool (the delegation seam)
+        can give its own children the same peer-addressing tools: membership
+        is a property of the tree, not of which executor built the child.
+        """
+        return self._tree
 
     def _emit(self, kind: str, data: dict[str, Any]) -> None:
         if self._event_sink is not None:
@@ -378,6 +415,7 @@ class AgentPool:
         if system_prompt:
             child_seed.insert(0, LLMMessage.text_of("system", system_prompt))
         handle.task = asyncio.ensure_future(self._run_child(handle, child_seed))
+        self._join_tree(child_id, profile=profile)
         loop_record_id = loop.record_id if loop is not None else None
         self._emit(
             "child_spawned",
@@ -448,6 +486,7 @@ class AgentPool:
         )
         self._watch_child(handle, loop)
         handle.task = asyncio.ensure_future(self._run_child(handle, list(seed)))
+        self._join_tree(child_id, profile=profile)
         self._emit(
             "child_resumed",
             {
@@ -459,8 +498,7 @@ class AgentPool:
         )
         return handle
 
-    def _write_seed_entry(
-        self,
+    def _write_seed_entry(        self,
         loop: CoreLoop,
         seed: list[LLMMessage],
         provenance: SeedProvenance,
@@ -493,6 +531,57 @@ class AgentPool:
         except Exception as exc:  # noqa: BLE001 — bookkeeping never fails a spawn
             logger.warning("fork seed provenance write failed: %s", exc)
 
+    def _join_tree(self, child_id: str, *, profile: str | None) -> None:
+        """Make this child addressable by peers while it exists.
+
+        The pool owns the loop, so it is also the thing that can deliver a
+        message to it — registering here is what lets a sibling reach this
+        child without knowing which executor built it.
+        """
+        if self._tree is None:
+            return
+        self._tree.register(
+            TreeMember(
+                lineage=child_id,
+                depth=self._depth + 1,
+                parent=self._lineage or None,
+                profile=profile,
+            ),
+            lambda message, cid=child_id: self._deliver_to_peer(cid, message),
+        )
+
+    def _leave_tree(self, child_id: str) -> None:
+        """Stop resolving this child's address (closed or wound down)."""
+        if self._tree is not None:
+            self._tree.unregister(child_id)
+
+    async def _deliver_to_peer(self, child_id: str, message: str) -> str:
+        """Deliver a peer's message to one child, asynchronously.
+
+        ``AgentPool.send`` is synchronous because a tool call runs inside the
+        loop and must answer in one step; a peer message instead arrives from
+        another agent's tool call, and resuming that child means awaiting its
+        new run's first step. So this routes through the same vocabulary
+        ``send`` returns (``steered`` / ``resumed`` / ``error:*``) while
+        allowing the resume to await.
+        """
+        verdict = self.send(child_id, message)
+        if verdict != "resumed":
+            return verdict
+        handle = self._children.get(child_id)
+        if handle is None or handle.task is None:
+            return "resumed"
+        # The resumed child is running; wait for it to settle so the sender
+        # learns the outcome rather than a bare "accepted". Shielded: a
+        # timeout on the sender's side must not cancel the work.
+        try:
+            await asyncio.shield(handle.task)
+        except asyncio.CancelledError:
+            raise
+        except Exception:  # noqa: BLE001 — the child's own outcome carries it
+            pass
+        return verdict
+
     def _register_child(
         self,
         child_id: str,
@@ -1039,6 +1128,10 @@ class AgentPool:
         if handle is None:
             return False
         handle.closed = True
+        # Closing is the caller's "never again": the address stops resolving
+        # so a peer's message reports an unknown member instead of resuming an
+        # agent the owner already gave up on.
+        self._leave_tree(child_id)
         if handle.outcome is not None:
             return True
         self._cancel_handle(handle)
@@ -1071,6 +1164,7 @@ class AgentPool:
         live = [h for h in self._children.values() if h.outcome is None]
         for handle in self._children.values():
             handle.closed = True
+            self._leave_tree(handle.child_id)
         for handle in live:
             self._cancel_handle(handle)
         for handle in live:

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/subagent.py

@@ -69,6 +69,7 @@ from .history import completed_turn_prefix
 from .llm import LLMMessage, LLMProvider
 from .loop import CoreLoop, LoopConfig, LoopContext, LoopHooks, ToolExecutor
 from .engines import AcpEngineSpec, AcpPermissionPolicy, AcpToolBridge
+from .peer import PeerToolsExecutor, peer_schemas
 from .pool import (
     AgentPool,
     LoopFactory,
@@ -441,8 +442,7 @@ class SubagentExecutor:
         #: which row is waiting on the user.
         self._event_sink = event_sink
         #: Where an external child's file and terminal requests land. ``None``
-        #: means this host grants none (a bridge with no capabilities refuses
-        #: everything), which is the safe default for a spawned process.
+        #: means this host grants none (a bridge with no capabilities refuses        #: everything), which is the safe default for a spawned process.
         self._acp_tool_bridge = acp_tool_bridge
         #: The parent's model-visible transcript, read at delegation time.
         #: ``None`` means this host cannot fork, and the tool schema omits the
@@ -655,6 +655,30 @@ class SubagentExecutor:
                     and (tool_filter is None or _schema_name(schema) in tool_filter)
                 ]
             schemas.append(parent_input_tool_descriptor())
+            base: ToolExecutor = _ParentInputExecutor(
+                self._child_executor(config),
+                lambda payload: self._parent_input_requests.__setitem__(
+                    child_id, payload
+                ),
+            )
+            # A delegated child is a member of the turn's job: it registers in
+            # the same tree the orchestration children do (the pool's
+            # ``_join_tree`` does that), so it can hand a finding to a sibling
+            # or answer the parent instead of routing everything back through
+            # the tool result. Read from the pool rather than a constructor
+            # argument because ``attach_pool`` adopts the shared pool after
+            # construction — the tree is whatever that pool has.
+            tree = self._pool.tree
+            if tree is not None:
+                # Same names as the orchestration family: a delegated child
+                # and an orchestration child are one kind of peer.
+                peer_config = OrchestrationConfig(
+                    max_parallel=self._config.max_parallel
+                )
+                base = PeerToolsExecutor(
+                    base, tree, peer_config, lineage=child_id
+                )
+                schemas = [*schemas, *peer_schemas(peer_config)]
             # A child writes its own durable record when the host gave us a
             # store and a prefix, so the delegation's process can be read
             # back afterwards (`<parent record>:child:<lineage id>`). The
@@ -668,12 +692,7 @@ class SubagentExecutor:
             return (
                 CoreLoop(
                     provider,
-                    _ParentInputExecutor(
-                        self._child_executor(config),
-                        lambda payload: self._parent_input_requests.__setitem__(
-                            child_id, payload
-                        ),
-                    ),
+                    base,
                     LoopConfig(
                         max_rounds=config.max_rounds,
                         max_tool_errors=config.max_tool_errors,

package/python-runtime/python/lib/python3.12/site-packages/steerable_agent_runtime/team_board.py

@@ -0,0 +1,229 @@
+"""The shared task board: one plan the whole spawn tree works from.
+
+Without it, splitting a job means the parent hands out self-contained tasks
+and then **remembers** who is doing what. That memory is the parent's context,
+which is exactly the thing that gets long when a job is big enough to need four
+agents. A board moves the plan out of any one context: the parent writes down
+the work, workers claim items, and anyone can see what is still unclaimed.
+
+Two decisions worth naming:
+
+- **Claiming is atomic.** Two workers that both see "auth refactor: todo" must
+  not both start it; ``claim`` either binds the caller or fails. That is the
+  whole point of a board over a list in a prompt.
+- **The board does not block.** ``claim`` returning "nothing free" is
+  information, not a reason to wait. A worker that waits on the board would
+  idle a slot the parent is budgeting for, so the caller decides what to do
+  next — and ``team_task_list`` shows what exists.
+
+Ownership is the caller's lineage id (``0.2``), so the board also answers "who
+is doing this" without a second registry.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+
+__all__ = ["TaskItem", "TeamTaskBoard"]
+
+logger = logging.getLogger(__name__)
+
+#: Statuses in the order work moves through them. ``todo`` is unclaimed; the
+#: rest exist so a reader can tell "nobody took it" from "someone has it" from
+#: "it is done" without reading every entry.
+TASK_STATUSES = ("todo", "claimed", "done")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True, slots=True)
+class TaskItem:
+    """One unit of work on the board.
+
+    ``owner`` is the claimant's lineage id (``None`` while ``todo``), and
+    ``depends_on`` names other task ids — the shape DSH's team board uses, so a
+    worker can tell "I can start" from "I am waiting on someone".
+    """
+
+    id: str
+    title: str
+    status: str
+    owner: str | None = None
+    detail: str | None = None
+    depends_on: tuple[str, ...] = ()
+    created_by: str | None = None
+    created_at: str = ""
+    updated_at: str = ""
+
+    @property
+    def blocked(self) -> bool:
+        """True while a dependency is still unfinished.
+
+        Computed by the board (which can see the others), not here: an item
+        alone cannot know whether its dependencies are done.
+        """
+        return bool(self.depends_on)
+
+    def to_wire(self) -> dict[str, object]:
+        """Camel-case payload for a tool result."""
+        return {
+            "id": self.id,
+            "title": self.title,
+            "status": self.status,
+            **({"owner": self.owner} if self.owner else {}),
+            **({"detail": self.detail} if self.detail else {}),
+            **({"dependsOn": list(self.depends_on)} if self.depends_on else {}),
+            **({"createdBy": self.created_by} if self.created_by else {}),
+        }
+
+
+@dataclass
+class TeamTaskBoard:
+    """One board per spawn tree, shared by every member.
+
+    The board is plain in-process state: it belongs to a turn tree, and a
+    tree does not outlive the turn that started it. Nothing here is durable on
+    purpose — a finished turn's plan has no reader, and persisting it would
+    create a second place where "what was this job" lives.
+    """
+
+    _items: dict[str, TaskItem] = field(default_factory=dict)
+    _seq: int = 0
+
+    def create(
+        self,
+        *,
+        title: str,
+        detail: str | None = None,
+        depends_on: tuple[str, ...] = (),
+        created_by: str | None = None,
+    ) -> TaskItem:
+        """Add one unclaimed item and return it.
+
+        Dependencies are validated here rather than at claim time: an item
+        that names a task nobody created would never become claimable, and the
+        author is the one who can fix the typo.
+        """
+        missing = [dep for dep in depends_on if dep not in self._items]
+        if missing:
+            raise KeyError(
+                f"unknown dependenc{'y' if len(missing) == 1 else 'ies'}: "
+                f"{', '.join(missing)}"
+            )
+        self._seq += 1
+        now = _now_iso()
+        item = TaskItem(
+            id=f"t{self._seq}",
+            title=title,
+            status="todo",
+            detail=detail,
+            depends_on=tuple(depends_on),
+            created_by=created_by,
+            created_at=now,
+            updated_at=now,
+        )
+        self._items[item.id] = item
+        return item
+
+    def get(self, task_id: str) -> TaskItem | None:
+        """One item, or ``None`` when the id is unknown."""
+        return self._items.get(task_id)
+
+    def items(self) -> list[TaskItem]:
+        """Every item, in creation order."""
+        return list(self._items.values())
+
+    def ready(self) -> list[TaskItem]:
+        """Unclaimed items whose dependencies are all done.
+
+        This is what a worker without a specific id should claim: the answer
+        "nothing ready, three blocked" is actionable in a way that a flat
+        unclaimed list is not.
+        """
+        done = {item.id for item in self._items.values() if item.status == "done"}
+        return [
+            item
+            for item in self._items.values()
+            if item.status == "todo" and all(dep in done for dep in item.depends_on)
+        ]
+
+    def claim(self, task_id: str, *, owner: str) -> TaskItem:
+        """Bind one ready item to ``owner``.
+
+        Raises:
+            KeyError: the id is unknown.
+            ValueError: the item is not claimable (already claimed, done, or
+                still blocked) — the message says which, because "cannot
+                claim" alone tells the caller nothing about whether to wait,
+                pick another item, or fix a dependency.
+
+        Claiming is the one operation that must not race: two workers reading
+        the same ``todo`` and both proceeding would duplicate the work, so the
+        check and the bind happen in one step here and nowhere else.
+        """
+        item = self._items.get(task_id)
+        if item is None:
+            raise KeyError(f"unknown task {task_id!r}")
+        if item.status == "done":
+            raise ValueError(f"task {task_id} is already done")
+        if item.status == "claimed":
+            raise ValueError(
+                f"task {task_id} is already claimed by {item.owner}"
+            )
+        done = {other.id for other in self._items.values() if other.status == "done"}
+        blocked = [dep for dep in item.depends_on if dep not in done]
+        if blocked:
+            raise ValueError(
+                f"task {task_id} is blocked by {', '.join(blocked)}"
+            )
+        claimed = replace(
+            item, status="claimed", owner=owner, updated_at=_now_iso()
+        )
+        self._items[task_id] = claimed
+        return claimed
+
+    def complete(
+        self, task_id: str, *, owner: str | None = None, note: str | None = None
+    ) -> TaskItem:
+        """Mark one claimed item done.
+
+        ``owner`` is checked when given: a worker finishing another worker's
+        item is far more often a mistake (wrong id) than intent, and the
+        message names the real owner so the caller can correct itself.
+
+        Raises:
+            KeyError: the id is unknown.
+            ValueError: the item is not claimed, or claimed by someone else.
+        """
+        item = self._items.get(task_id)
+        if item is None:
+            raise KeyError(f"unknown task {task_id!r}")
+        if item.status == "done":
+            return item
+        if item.status != "claimed":
+            raise ValueError(
+                f"task {task_id} is {item.status}, not claimed; claim it first"
+            )
+        if owner is not None and item.owner is not None and item.owner != owner:
+            raise ValueError(
+                f"task {task_id} is claimed by {item.owner}, not {owner}"
+            )
+        detail = item.detail if note is None else (
+            f"{item.detail}\n{note}" if item.detail else note
+        )
+        done = replace(
+            item, status="done", detail=detail, updated_at=_now_iso()
+        )
+        self._items[task_id] = done
+        return done
+
+    def summary(self) -> dict[str, int]:
+        """Counts by status, for a one-line board overview."""
+        counts = {status: 0 for status in TASK_STATUSES}
+        for item in self._items.values():
+            counts[item.status] = counts.get(item.status, 0) + 1
+        return counts