@steerable/runtime-win32-x64 0.10.2 → 0.11.0

package/python-runtime/python/Lib/site-packages/steerable_agent_runtime/orchestration.py

@@ -45,6 +45,7 @@ from .hooks import ChainHooks, CompletionAction, CompletionDraft, NoopHooks
 from .history import completed_turn_prefix
 from .llm import LLMMessage, LLMProvider
 from .loop import CoreLoop, LoopConfig, LoopContext, LoopHooks, ToolExecutor
+from .peer import PeerToolsExecutor, peer_schemas, send_tool_descriptor, tool_schema
 from .pool import (
     AgentPool,
     ChildOutcome,
@@ -55,6 +56,8 @@ from .pool import (
 from .registry import ChildRegistry, default_record_id
 from .resume import load_history_transcript
 from .subagent import FilteredToolsExecutor, _schema_name
+from .team_board import TeamTaskBoard
+from .tree import AgentTree, TreeMember
 
 logger = logging.getLogger(__name__)
 
@@ -66,7 +69,10 @@ __all__ = [
     "OrchestrationBudgetExceeded",
     "OrchestrationConfig",
     "OrchestrationExecutor",
+    "PeerToolsExecutor",
     "orchestration_tool_descriptors",
+    "send_tool_descriptor",
+    "team_tool_descriptors",
 ]
 
 #: Terminal status of a run stopped by ``max_rounds`` or the token budget.
@@ -159,20 +165,7 @@ def orchestration_tool_descriptors(
     """OpenAI tool schemas for the four orchestration tools."""
     config = config or OrchestrationConfig()
 
-    def fn(name: str, description: str, properties: dict, required: list[str]) -> dict:
-        return {
-            "type": "function",
-            "function": {
-                "name": name,
-                "description": description,
-                "parameters": {
-                    "type": "object",
-                    "properties": properties,
-                    "required": required,
-                    "additionalProperties": False,
-                },
-            },
-        }
+    fn = tool_schema
 
     return [
         fn(
@@ -234,18 +227,7 @@ def orchestration_tool_descriptors(
             },
             ["task"],
         ),
-        fn(
-            config.send_tool,
-            "Send a message to a sub-agent. A running child receives it at "
-            "its next round boundary (steer); a finished or interrupted "
-            "child is resumed with the message as a follow-up turn, keeping "
-            "its prior context. Closed children reject sends.",
-            {
-                "childId": {"type": "string"},
-                "message": {"type": "string"},
-            },
-            ["childId", "message"],
-        ),
+        send_tool_descriptor(config),
         fn(
             config.wait_tool,
             "Wait for the first sub-agent to finish and return its outcome. "
@@ -274,9 +256,11 @@ def orchestration_tool_descriptors(
         ),
         fn(
             config.list_tool,
-            "List this pool's sub-agents with their status (running / "
+            "List this job's agents with their status (running / "
             "completed / error / cancelled / interrupted / closed), task, "
-            "and a preview of finished answers.",
+            "and a preview of finished answers. `members` names every live "
+            "agent in this job with the lineage id to message (`self` is "
+            "yours), which is how you address a sibling or the root.",
             {},
             [],
         ),
@@ -292,6 +276,240 @@ def orchestration_tool_descriptors(
     ]
 
 
+def team_tool_descriptors(
+    config: OrchestrationConfig | None = None,
+) -> list[dict[str, Any]]:
+    """OpenAI tool schemas for the shared task board (R8).
+
+    The board moves the plan out of any one context: the agent that split the
+    job writes items down, workers claim them, and anyone can see what is left.
+    The tools are only advertised when a board is wired, so a host that did not
+    opt in never sees them.
+    """
+    config = config or OrchestrationConfig()
+
+    def fn(name: str, description: str, properties: dict, required: list[str]) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": name,
+                "description": description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                    "additionalProperties": False,
+                },
+            },
+        }
+
+    return [
+        fn(
+            config.task_create_tool,
+            "Add a unit of work to the shared board so any agent in this "
+            "job can see it. Use this when splitting work across agents: "
+            "write the items once here instead of repeating them in every "
+            "task you hand out. Returns the task id.",
+            {
+                "title": {
+                    "type": "string",
+                    "description": "One line naming the work.",
+                },
+                "detail": {
+                    "type": "string",
+                    "description": (
+                        "Optional specifics the claimant needs — files, "
+                        "acceptance, constraints."
+                    ),
+                },
+                "dependsOn": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Task ids that must finish before this one can be "
+                        "claimed. Ids come from earlier team_task_create "
+                        "results."
+                    ),
+                },
+            },
+            ["title"],
+        ),
+        fn(
+            config.task_claim_tool,
+            "Claim a task from the shared board before working on it. "
+            "Claiming is what stops two agents doing the same item: it "
+            "fails if the task is taken, done, or still blocked by a "
+            "dependency. Omit taskId to claim the first ready item. A "
+            "refusal lists what is still claimable.",
+            {
+                "taskId": {
+                    "type": "string",
+                    "description": "Exact task id; omit to take the first ready one.",
+                },
+            },
+            [],
+        ),
+        fn(
+            config.task_complete_tool,
+            "Mark a task you claimed as done, optionally recording what you "
+            "found or changed. Completing unblocks tasks that depend on it.",
+            {
+                "taskId": {"type": "string"},
+                "note": {
+                    "type": "string",
+                    "description": "Optional outcome note for whoever reads the board.",
+                },
+            },
+            ["taskId"],
+        ),
+        fn(
+            config.task_list_tool,
+            "List the shared board: every item with its status, owner, and "
+            "dependencies, plus a per-status count.",
+            {},
+            [],
+        ),
+    ]
+
+
+class TeamToolExecutor:
+    """ToolExecutor decorator: the four shared-board tools.
+
+    Its own decorator rather than part of ``OrchestrationExecutor`` because
+    the board is orthogonal to the spawn family: a leaf child has no
+    ``agent_spawn`` but must still see the plan and claim from it. Keeping the
+    two apart is what lets that child be a full participant without gaining
+    the ability to spawn.
+    """
+
+    def __init__(
+        self,
+        inner: ToolExecutor,
+        board: TeamTaskBoard,
+        config: OrchestrationConfig,
+        *,
+        lineage: str,
+    ) -> None:
+        self._inner = inner
+        self._board = board
+        self._config = config
+        #: Who claims and completes — the caller's lineage id, so the board
+        #: answers "who is doing this" without a second registry.
+        self._lineage = lineage
+
+    async def execute(self, call: ToolCall, ctx: LoopContext) -> ToolResult:
+        if call.name == self._config.task_create_tool:
+            return self._create(call)
+        if call.name == self._config.task_claim_tool:
+            return self._claim(call)
+        if call.name == self._config.task_complete_tool:
+            return self._complete(call)
+        if call.name == self._config.task_list_tool:
+            return self._list()
+        return await self._inner.execute(call, ctx)
+
+    def _create(self, call: ToolCall) -> ToolResult:
+        title = str(call.arguments.get("title") or "").strip()
+        if not title:
+            return ToolResult(success=False, error="empty title")
+        raw_deps = call.arguments.get("dependsOn")
+        depends_on = (
+            tuple(str(dep).strip() for dep in raw_deps if str(dep).strip())
+            if isinstance(raw_deps, list)
+            else ()
+        )
+        detail = str(call.arguments.get("detail") or "").strip() or None
+        try:
+            item = self._board.create(
+                title=title,
+                detail=detail,
+                depends_on=depends_on,
+                created_by=self._lineage,
+            )
+        except KeyError as exc:
+            return ToolResult(
+                success=False, error=str(exc.args[0]), needsFollowup=True
+            )
+        return ToolResult(
+            success=True, message=json.dumps(item.to_wire()), data={"taskId": item.id}
+        )
+
+    def _claim(self, call: ToolCall) -> ToolResult:
+        task_id = str(call.arguments.get("taskId") or "").strip()
+        if not task_id:
+            ready = self._board.ready()
+            if not ready:
+                return ToolResult(
+                    success=False,
+                    error=(
+                        "no_ready_task: nothing is unclaimed and unblocked; "
+                        f"board: {json.dumps(self._board.summary())}"
+                    ),
+                    needsFollowup=True,
+                )
+            task_id = ready[0].id
+        try:
+            item = self._board.claim(task_id, owner=self._lineage)
+        except (KeyError, ValueError) as exc:
+            return ToolResult(
+                success=False,
+                error=f"claim_refused: {exc.args[0]}",
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps(item.to_wire()),
+            data={"taskId": item.id, "status": item.status},
+        )
+
+    def _complete(self, call: ToolCall) -> ToolResult:
+        task_id = str(call.arguments.get("taskId") or "").strip()
+        if not task_id:
+            return ToolResult(success=False, error="empty taskId")
+        note = str(call.arguments.get("note") or "").strip() or None
+        try:
+            item = self._board.complete(task_id, owner=self._lineage, note=note)
+        except (KeyError, ValueError) as exc:
+            return ToolResult(
+                success=False,
+                error=f"complete_refused: {exc.args[0]}",
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps(item.to_wire()),
+            data={"taskId": item.id, "status": item.status},
+        )
+
+    def _list(self) -> ToolResult:
+        payload = {
+            "tasks": [item.to_wire() for item in self._board.items()],
+            "summary": self._board.summary(),
+        }
+        return ToolResult(
+            success=True,
+            message=json.dumps(payload),
+            data={"count": len(self._board.items())},
+        )
+
+    def dedup_exempt(self, call: ToolCall) -> bool:
+        # Claim is stateful: the same arguments twice must observe the second
+        # refusal, not a cached first success.
+        if call.name in self._config.team_tool_names:
+            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:
+        # Every board call mutates or reads shared state; running two claim
+        # attempts concurrently would defeat the exclusivity the board exists
+        # for.
+        if call.name in self._config.team_tool_names:
+            return False
+        inner_safe = getattr(self._inner, "concurrency_safe", None)
+        return bool(inner_safe and inner_safe(call))
+
+
 class OrchestrationExecutor:
     """ToolExecutor decorator: the six orchestration tools drive an AgentPool.
 
@@ -318,9 +536,14 @@ class OrchestrationExecutor:
         budget: TreeBudget | None = None,
         parent_route: Callable[[], tuple[str | None, str | None]] | None = None,
         provider_factory: Callable[[str | None, str | None], LLMProvider] | None = None,
+        tree: AgentTree | None = None,
+        team_board: TeamTaskBoard | None = None,
         _depth: int = 0,
         _lineage: str = "0",
     ) -> None:
+        #: The executor children are built from, and peers' tool calls land
+        #: on. Kept unwrapped so the board decorator below is applied exactly
+        #: once per agent.
         self._inner = inner
         self._provider = provider
         self._config = config or OrchestrationConfig()
@@ -351,6 +574,23 @@ class OrchestrationExecutor:
         #: fork needs it; without one, `agent_spawn` cannot change the route
         #: and says so instead of silently ignoring the request.
         self._provider_factory = provider_factory
+        #: Tree-wide addressing (R8). Shared down the whole spawn tree so a
+        #: child can message a sibling, its parent, or its own children. Each
+        #: pool registers only the agents it owns; delivery goes through the
+        #: owner. ``None`` keeps the pre-R8 reach: this pool's children only.
+        self._tree = tree
+        #: The shared board (R8). One per tree, so every member reads and
+        #: writes the same plan. ``None`` leaves the team tools unadvertised.
+        self._team_board = team_board
+        #: The board decorator, built once so this agent's own calls and its
+        #: children's share one implementation.
+        self._team = (
+            TeamToolExecutor(
+                self._inner, team_board, self._config, lineage=_lineage
+            )
+            if team_board is not None
+            else None
+        )
         #: The tree's shared token limit; ``None`` keeps per-run accounting.
         self._budget = budget
         self._depth = _depth
@@ -366,6 +606,7 @@ class OrchestrationExecutor:
             budget=budget,
             # Needed to write a fork seed's provenance into the child's record.
             history_store=history_store,
+            tree=tree,
         )
 
     @property
@@ -441,10 +682,33 @@ class OrchestrationExecutor:
                     own_loop[0].history.projection if own_loop else []
                 ),
                 budget=self._budget,
+                # Same tree and board: a grandchild is as much a member of the
+                # job as its parent, and the plan it reads must be the one the
+                # root wrote.
+                tree=self._tree,
+                team_board=self._team_board,
                 _depth=child_depth,
                 _lineage=child_id,
             )
             schemas = [*schemas, *orchestration_tool_descriptors(self._config)]
+        elif self._tree is not None:
+            # A leaf cannot delegate, but it is still a member of the job:
+            # without a send it could only report through the completion
+            # notice, which carries no reply path. Messaging is a tree
+            # property, not a depth permission.
+            base = PeerToolsExecutor(
+                base, self._tree, self._config, lineage=child_id
+            )
+            schemas = [*schemas, *peer_schemas(self._config)]
+        # The board is advertised to every child regardless of nesting: a
+        # worker that cannot spawn anyone still needs to see the plan and
+        # claim from it, which is why the board is not part of the
+        # orchestration family.
+        if self._team_board is not None:
+            base = TeamToolExecutor(
+                base, self._team_board, self._config, lineage=child_id
+            )
+            schemas = [*schemas, *team_tool_descriptors(self._config)]
         wrap_up = ChildBudgetWrapUp()
         loop = CoreLoop(
             child_provider,
@@ -477,6 +741,20 @@ class OrchestrationExecutor:
             return await self._list(call)
         if call.name == self._config.interrupt_tool:
             return await self._interrupt(call)
+        if call.name in self._config.team_tool_names:
+            # The board layer answers only when a board was wired; otherwise
+            # this agent has no plan to read and says so instead of letting the
+            # call fall through to an executor that does not know the name.
+            if self._team_board is None:
+                return ToolResult(
+                    success=False,
+                    error=(
+                        "team_board_unavailable: this turn has no shared task "
+                        "board; work from the tasks you were given"
+                    ),
+                    needsFollowup=True,
+                )
+            return await self._team.execute(call, ctx)
         return await self._inner.execute(call, ctx)
 
     async def _spawn(self, call: ToolCall) -> ToolResult:
@@ -641,9 +919,14 @@ class OrchestrationExecutor:
             return ToolResult(success=False, error="empty message")
         outcome = self._pool.send(child_id, message)
         if outcome.startswith("error:"):
-            # The pool only knows the children of this turn. A child from an
-            # earlier turn (or before a restart) has no handle here — try the
-            # durable index before telling the model the child is unknown.
+            # The pool only knows the children of this turn. Two other
+            # destinations are legitimate, and both are tried before refusing:
+            # a tree member that some other executor owns (a sibling, or this
+            # agent's own parent), then a child from an earlier turn, which is
+            # rebuilt from its durable row.
+            peer = await self._send_to_tree(child_id, message)
+            if peer is not None:
+                return peer
             resumed = await self._resume_from_registry(child_id, message)
             if resumed is not None:
                 return resumed
@@ -658,6 +941,42 @@ class OrchestrationExecutor:
             data={"childId": child_id, "delivery": outcome},
         )
 
+    async def _send_to_tree(self, target: str, message: str) -> ToolResult | None:
+        """Deliver to a member this pool does not own, if the tree has it.
+
+        Returns ``None`` when there is no tree, or the target is not a member —
+        the caller then falls through to the durable-index resume, so the
+        refusals stay in one place with one wording.
+
+        Delivery goes through the owner, which may steer a running agent or
+        resume a settled one. A resume can take a while (the owner waits for
+        the first step), so the verdict reports what happened rather than
+        pretending the message was merely queued.
+        """
+        if self._tree is None:
+            return None
+        member = self._tree.get(target)
+        if member is None:
+            return None
+        verdict = await self._tree.send(self._lineage, target, message)
+        if verdict.startswith("error:"):
+            return ToolResult(
+                success=False,
+                error=verdict[len("error:"):],
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps(
+                {
+                    "childId": target,
+                    "delivery": verdict,
+                    "depth": member.depth,
+                }
+            ),
+            data={"childId": target, "delivery": verdict},
+        )
+
     async def _resume_from_registry(
         self, child_id: str, message: str
     ) -> ToolResult | None:
@@ -746,12 +1065,18 @@ class OrchestrationExecutor:
         return [*transcript, LLMMessage.text_of("user", message)]
 
     async def _list(self, call: ToolCall) -> ToolResult:
-        """Every child of this session, not just the ones running now.
+        """Every child of this session, plus every agent this one can message.
 
         The pool is per turn, so on its own it answers "what is running"; the
         durable index answers "what did this session spawn". Merging both is
         what makes the tool useful in a later turn, which is the whole point
         of R1 — a child that finished three turns ago is still listed.
+
+        ``members`` is the second answer, and it is the one ``agent_send``
+        needs: it names every live address in this job — this agent's children,
+        its siblings, and the root — because a worker that has to route a
+        finding sideways cannot look up an id it was never told. Both keys are
+        present so a host reading the older one keeps working.
         """
         entries = self._pool.list()
         seen = {entry["childId"] for entry in entries}
@@ -773,9 +1098,15 @@ class OrchestrationExecutor:
                         **({"resumable": True} if view.resumable else {}),
                     }
                 )
+        payload: dict[str, Any] = {"children": entries}
+        if self._tree is not None:
+            payload["members"] = [
+                member.to_wire() for member in self._tree.members()
+            ]
+            payload["self"] = self._lineage
         return ToolResult(
             success=True,
-            message=json.dumps({"children": entries}),
+            message=json.dumps(payload),
             data={"count": len(entries)},
         )
 
@@ -888,8 +1219,12 @@ class OrchestrationExecutor:
         # a second wait observes the resumed run). The loop's same-turn
         # duplicate_call guard would break legitimate sequences like
         # wait → send → wait, so the family opts out; inner tools keep the
-        # guard unless the inner executor exempts them.
-        if call.name in self._config.tool_names:
+        # guard unless the inner executor exempts them. The board tools are in
+        # the same family for the same reason: two `team_task_claim` calls
+        # without a taskId are distinct claims of different items, and the
+        # second must observe the board's new state rather than a cached
+        # first result.
+        if call.name in self._config.tool_names or call.name in self._config.team_tool_names:
             return True
         inner_exempt = getattr(self._inner, "dedup_exempt", None)
         return bool(inner_exempt and inner_exempt(call))
@@ -921,5 +1256,9 @@ class OrchestrationExecutor:
             self._config.interrupt_tool,
         }:
             return False
+        if call.name in self._config.team_tool_names:
+            # A claim must see the board a sibling claim left behind, so a
+            # round that emits several of them runs them in order.
+            return False
         inner_safe = getattr(self._inner, "concurrency_safe", None)
         return bool(inner_safe and inner_safe(call))