@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.1

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

@@ -0,0 +1,196 @@
+"""Observation aging (W2.1): tool results degrade by tier as they age.
+
+Long-horizon trajectories drown the model in stale observations: a 40 KB
+file listing from round 2 is still verbatim in the prompt at round 30,
+outweighing the last three rounds of actual work. Aging applies a graded
+rule table keyed on (age in rounds, size in tokens):
+
+- **fresh** — younger than ``fresh_rounds`` or smaller than
+  ``keep_tokens``: keep verbatim. Recent and cheap observations are the
+  model's working set.
+- **compress** — mid-age and larger than ``compress_tokens``: keep the
+  result envelope's schema keys (``success`` / ``error`` / ``data`` /
+  ``message``) and truncate long string values, so the model can still
+  reason about *what* the result was (W2.1.3).
+- **fold** — at or past ``fold_after_rounds``: replace with a one-line
+  stub naming the tool, original size, originating round, and the tool
+  call id under which the full record lives in session history (W2.1.4).
+
+Both rewrites go through the declared ``RewriteRequest`` path: the loop
+applies them via ``ContextManager.replace_all``, which records a
+``CompactionBoundary`` — the append-only record keeps every original
+byte, only the visible projection shrinks. That is what makes folding
+expandable: the stub's reference resolves against the durable record.
+
+The hook is idempotent across rounds: each call id's applied tier is
+tracked, so a compressed result is not re-compressed every round, and the
+only later transition is compress → fold.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .hooks import NoopHooks, PreStepAction, RewriteRequest
+from .llm import LLMMessage
+from .tokens import estimate_text_tokens
+
+AgingAction = Literal["keep", "compress", "fold"]
+
+
+@dataclass(frozen=True, slots=True)
+class AgingRules:
+    """The (age, size) → action rule table. Ages are rounds since the
+    result was first seen; sizes are estimated tokens of the message."""
+
+    #: Younger than this many rounds: always keep verbatim.
+    fresh_rounds: int = 3
+    #: Smaller than this many tokens: always keep (cheap observations are
+    #: not worth rewriting).
+    keep_tokens: int = 200
+    #: This many rounds old or older: fold to a record reference.
+    fold_after_rounds: int = 8
+    #: Between fresh and fold: compress when larger than this many tokens.
+    compress_tokens: int = 1000
+    #: Per-string-value character budget inside a compressed payload.
+    compress_value_chars: int = 80
+    #: List items kept per list inside a compressed payload.
+    compress_list_items: int = 3
+
+    def decide(self, *, age_rounds: int, size_tokens: int) -> AgingAction:
+        if age_rounds < self.fresh_rounds or size_tokens <= self.keep_tokens:
+            return "keep"
+        if age_rounds >= self.fold_after_rounds:
+            return "fold"
+        if size_tokens > self.compress_tokens:
+            return "compress"
+        return "keep"
+
+
+class ObservationAgingHooks(NoopHooks):
+    """``pre_step`` hook applying the aging table to tool-result messages.
+
+    ``post_tool_result`` records when each call id first appeared;
+    ``pre_step`` walks the visible projection and declares a wholesale
+    rewrite when at least one result crosses a tier boundary. Rounds with
+    no transition return ``proceed`` untouched — no boundary is recorded.
+    """
+
+    def __init__(self, rules: AgingRules | None = None) -> None:
+        self._rules = rules or AgingRules()
+        #: call id → round the result first entered the transcript.
+        self._seen: dict[str, int] = {}
+        #: call id → last applied non-keep action (``folded`` is terminal).
+        self._applied: dict[str, str] = {}
+
+    async def post_tool_result(self, result: Any, call: Any, ctx: Any) -> Any:
+        call_id = getattr(call, "id", None)
+        if isinstance(call_id, str) and call_id:
+            self._seen.setdefault(call_id, getattr(ctx, "round_index", 0))
+        return result
+
+    async def pre_step(
+        self, transcript: list[LLMMessage], ctx: Any
+    ) -> PreStepAction:
+        round_index = getattr(ctx, "round_index", 0)
+        messages: list[LLMMessage] = []
+        transitions = 0
+        for message in transcript:
+            aged = self._age_one(message, round_index)
+            transitions += aged is not message
+            messages.append(aged)
+        if not transitions:
+            return PreStepAction(kind="proceed")
+        return PreStepAction(
+            kind="proceed",
+            rewrite=RewriteRequest(
+                messages=messages,
+                reason=f"observation aging: {transitions} result(s) changed tier",
+                action="observation_aging",
+            ),
+        )
+
+    def _age_one(self, message: LLMMessage, round_index: int) -> LLMMessage:
+        if message.role != "tool" or not message.tool_call_id:
+            return message
+        call_id = message.tool_call_id
+        seen_round = self._seen.get(call_id)
+        if seen_round is None:
+            # Seeded history (resumed session): age unknown, leave verbatim.
+            return message
+        applied = self._applied.get(call_id)
+        if applied == "folded":
+            return message
+        action = self._rules.decide(
+            age_rounds=round_index - seen_round,
+            size_tokens=estimate_text_tokens(message.content_text),
+        )
+        if action == "keep" or applied == action:
+            return message
+        if action == "compress":
+            content = _compress_payload(message.content_text, self._rules)
+        else:
+            content = _fold_stub(
+                tool=message.name or "tool",
+                tokens=estimate_text_tokens(message.content_text),
+                seen_round=seen_round,
+                call_id=call_id,
+            )
+        self._applied[call_id] = "compressed" if action == "compress" else "folded"
+        return LLMMessage.text_of(
+            "tool", content, name=message.name, tool_call_id=call_id
+        )
+
+
+def _compress_payload(text: str, rules: AgingRules) -> str:
+    """Keep the envelope's schema keys; truncate long values (W2.1.3).
+
+    The transcript's tool messages serialize ``{"success", "error"?,
+    "data"?, "message"?}`` — every top-level key survives so the model can
+    still see whether the call failed and what kind of payload it had.
+    Unparseable content (not the envelope shape) degrades to head/tail
+    truncation.
+    """
+    try:
+        payload = json.loads(text)
+    except ValueError:
+        return _head_tail(text, rules.compress_value_chars * 8)
+    if not isinstance(payload, dict):
+        return _head_tail(text, rules.compress_value_chars * 8)
+    compressed = {
+        key: _compress_value(value, rules) for key, value in payload.items()
+    }
+    return json.dumps(compressed, ensure_ascii=False)
+
+
+def _compress_value(value: Any, rules: AgingRules) -> Any:
+    if isinstance(value, str):
+        if len(value) <= rules.compress_value_chars:
+            return value
+        return f"{value[: rules.compress_value_chars]}…[+{len(value) - rules.compress_value_chars} chars]"
+    if isinstance(value, dict):
+        return {key: _compress_value(item, rules) for key, item in value.items()}
+    if isinstance(value, list):
+        kept = [_compress_value(item, rules) for item in value[: rules.compress_list_items]]
+        if len(value) > rules.compress_list_items:
+            kept.append(f"…[+{len(value) - rules.compress_list_items} items]")
+        return kept
+    return value
+
+
+def _fold_stub(*, tool: str, tokens: int, seen_round: int, call_id: str) -> str:
+    """One-line reference to the full record (W2.1.4)."""
+    return (
+        f"[observation folded: {tool} result, ~{tokens} tokens, "
+        f"from round {seen_round}. Full record retained in session history "
+        f"under tool call {call_id}.]"
+    )
+
+
+def _head_tail(text: str, budget: int) -> str:
+    if len(text) <= budget:
+        return text
+    half = max(budget // 2, 1)
+    return f"{text[:half]}\n…[{len(text) - 2 * half} chars omitted]…\n{text[-half:]}"

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

@@ -0,0 +1,462 @@
+"""Multi-agent orchestration — a parent CoreLoop driving parallel children.
+
+Extends the depth-1 delegation seam (``subagent.py``) into the framework's
+orchestration layer (P3.1): a pool of concurrent child ``CoreLoop`` instances
+with coordination primitives the parent model drives through six tools —
+``agent_spawn`` / ``agent_send`` / ``agent_wait`` / ``agent_close`` /
+``agent_list`` / ``agent_interrupt``. The pool itself lives in ``pool.py``
+(re-exported here) and also backs the single-tool delegation seam.
+
+Design:
+- **Lineage as data.** Child ids are ``<lineage>.<seq>`` (root ``0``), so
+  ``0.2`` is the root's second child and ``0.2.1`` its first grandchild.
+  Every tool result carries the id as structured JSON — the parent record
+  alone rebuilds who was spawned and how they ended.
+- **Budgets fail closed.** ``max_parallel`` and ``max_depth`` refuse at the
+  boundary (``orchestration_budget_exceeded`` / no orchestration tools in
+  the child), never silently queue. Depth is structural: a child only has
+  orchestration tools when its own executor nests another
+  ``OrchestrationExecutor``, which happens iff ``depth + 1 < max_depth``.
+- **Coordination reuses loop primitives.** ``agent_send`` to a running child
+  is ``loop.steer``; to a finished child it is a follow-up turn seeded from
+  the clean-finish record snapshot (multi-turn children). ``agent_interrupt``
+  is the cooperative ``loop.cancel()`` that keeps the child addressable;
+  ``agent_close`` adds a hard-cancel backstop and a terminal closed flag —
+  a closed child winds down with a consistent record, same as a
+  user-cancelled turn, and rejects further sends.
+- **Children stay out of the parent record.** A child's transcript is its
+  own loop's; the parent sees spawn/wait/close results. Hosts that want
+  child traces subscribe via ``event_sink`` (lifecycle events with lineage)
+  or wrap children in their own hooks.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from steerable_agent_protocol.generated import ToolCall, ToolResult
+
+from .hooks import ChainHooks, CompletionAction, CompletionDraft, NoopHooks
+from .llm import LLMProvider
+from .loop import CoreLoop, LoopConfig, LoopContext, LoopHooks, ToolExecutor
+from .pool import (
+    AgentPool,
+    ChildOutcome,
+    OrchestrationBudgetExceeded,
+    OrchestrationConfig,
+)
+from .subagent import FilteredToolsExecutor, _schema_name
+
+__all__ = [
+    "AgentPool",
+    "ChildOutcome",
+    "ChildBudgetWrapUp",
+    "OrchestrationBudgetExceeded",
+    "OrchestrationConfig",
+    "OrchestrationExecutor",
+    "orchestration_tool_descriptors",
+]
+
+#: Terminal status of a run stopped by ``max_rounds`` or the token budget.
+_BUDGET_WALL_STATUS = "budget_exhausted"
+
+_BUDGET_WRAP_UP_REQUEST = (
+    "[system notice] This run has used its round budget and tools are now "
+    "withheld. Answer the original task now from what you have already "
+    "gathered: give your concrete findings first, then list what you could "
+    "not finish or verify. Do not describe the steps you took."
+)
+
+_RESUME_HINT = (
+    "The child stopped at its round budget; `answer` is its interim report. "
+    "To continue, agent_send this childId a message naming what is still "
+    "missing — it resumes with its prior context and a fresh budget. Do not "
+    "spawn a new child for the same task."
+)
+
+
+class ChildBudgetWrapUp(NoopHooks):
+    """``before_completion``: one no-tools answer round at a child's budget wall.
+
+    Without it a child stopped by ``max_rounds`` or the token budget returns
+    whatever text its last working round produced — usually a progress note,
+    not an answer. The parent then gets ``budget_exhausted`` with nothing
+    usable. The ``narrate`` action runs one round without tools and keeps the
+    ``budget_exhausted`` status, so the parent can still tell the answer is
+    interim and resume the child with ``agent_send``.
+
+    One instance per child loop. A resumed child runs the same loop with a new
+    ``LoopContext``, so the one-round limit applies per run.
+    """
+
+    def __init__(self) -> None:
+        self._wrapped_run: LoopContext | None = None
+
+    async def before_completion(
+        self, draft: CompletionDraft, ctx: LoopContext
+    ) -> CompletionAction:
+        """Narrate once per run when the draft stops at the budget wall."""
+        if draft.status != _BUDGET_WALL_STATUS or self._wrapped_run is ctx:
+            return CompletionAction(kind="accept")
+        self._wrapped_run = ctx
+        return CompletionAction(
+            kind="narrate",
+            message=_BUDGET_WRAP_UP_REQUEST,
+            reason="child_budget_wrap_up",
+        )
+
+
+def orchestration_tool_descriptors(
+    config: OrchestrationConfig | None = None,
+) -> list[dict[str, Any]]:
+    """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,
+                },
+            },
+        }
+
+    return [
+        fn(
+            config.spawn_tool,
+            "Spawn a sub-agent with its own reasoning loop to work on a "
+            "self-contained task concurrently. Returns immediately with a "
+            "childId; use agent_wait to collect its answer.",
+            {
+                "task": {
+                    "type": "string",
+                    "description": (
+                        "Complete, self-contained instructions for the "
+                        "sub-agent — it sees none of this conversation."
+                    ),
+                },
+                "toolFilter": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Optional allow-list of tool names the child may "
+                        "call; omitted delegates the full tool domain."
+                    ),
+                },
+            },
+            ["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"],
+        ),
+        fn(
+            config.wait_tool,
+            "Wait for a sub-agent to finish and return its outcome. A child "
+            "still running at the timeout returns status 'running'. A child "
+            "that hit its round budget returns status 'budget_exhausted' with "
+            "an interim answer and resumable: true — continue it with "
+            "agent_send instead of spawning a new child.",
+            {
+                "childId": {"type": "string"},
+                "timeoutMs": {"type": "integer"},
+            },
+            ["childId"],
+        ),
+        fn(
+            config.close_tool,
+            "Close a sub-agent terminally: cooperative cancel with a "
+            "hard-cancel backstop, and the child rejects further sends. "
+            "Use agent_interrupt instead to pause a child you still need.",
+            {"childId": {"type": "string"}},
+            ["childId"],
+        ),
+        fn(
+            config.list_tool,
+            "List this pool's sub-agents with their status (running / "
+            "completed / error / cancelled / interrupted / closed), task, "
+            "and a preview of finished answers.",
+            {},
+            [],
+        ),
+        fn(
+            config.interrupt_tool,
+            "Interrupt a running sub-agent's current turn (cooperative "
+            "cancel) while keeping it addressable: its context is preserved "
+            "and a later agent_send resumes it. Unlike agent_close this is "
+            "not terminal.",
+            {"childId": {"type": "string"}},
+            ["childId"],
+        ),
+    ]
+
+
+class OrchestrationExecutor:
+    """ToolExecutor decorator: the six orchestration tools drive an AgentPool.
+
+    ``tools`` is the parent loop's advertised schemas — children advertise
+    the subset their ``toolFilter`` delegates (minus the orchestration
+    family, re-added only when the depth budget allows the child its own
+    pool). Without it children run reasoning-only, matching the legacy
+    subagent seam.
+    """
+
+    def __init__(
+        self,
+        inner: ToolExecutor,
+        provider: LLMProvider,
+        config: OrchestrationConfig | None = None,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        hooks: LoopHooks | None = None,
+        event_sink: Callable[[str, dict[str, Any]], None] | None = None,
+        _depth: int = 0,
+        _lineage: str = "0",
+    ) -> None:
+        self._inner = inner
+        self._provider = provider
+        self._config = config or OrchestrationConfig()
+        self._parent_tools = list(tools or [])
+        self._hooks = hooks
+        self._event_sink = event_sink
+        self._depth = _depth
+        self._lineage = _lineage
+        self._pool = AgentPool(
+            config=self._config,
+            depth=_depth,
+            lineage=_lineage,
+            loop_factory=self._child_loop,
+            event_sink=event_sink,
+        )
+
+    @property
+    def pool(self) -> AgentPool:
+        """This executor's pool — exposed so the delegation seam can share
+        it (one ``max_parallel`` budget and one lineage space across both
+        multi-agent surfaces; see the sidecar wiring)."""
+        return self._pool
+
+    # ------------------------------------------------------------------
+    # child construction
+    # ------------------------------------------------------------------
+
+    def _child_loop(
+        self, child_id: str, tool_filter: frozenset[str] | None
+    ) -> tuple[CoreLoop, list[dict[str, Any]] | None]:
+        base: ToolExecutor = self._inner
+        if tool_filter is not None:
+            base = FilteredToolsExecutor(base, tool_filter)
+        orch_names = self._config.tool_names
+        schemas = [
+            schema
+            for schema in self._parent_tools
+            if _schema_name(schema) not in orch_names
+            and (tool_filter is None or _schema_name(schema) in tool_filter)
+        ]
+        if self._depth + 1 < self._config.max_depth:
+            base = OrchestrationExecutor(
+                base,
+                self._provider,
+                self._config,
+                tools=schemas,
+                hooks=self._hooks,
+                event_sink=self._event_sink,
+                _depth=self._depth + 1,
+                _lineage=child_id,
+            )
+            schemas = [*schemas, *orchestration_tool_descriptors(self._config)]
+        wrap_up = ChildBudgetWrapUp()
+        loop = CoreLoop(
+            self._provider,
+            base,
+            LoopConfig(
+                max_rounds=self._config.child_max_rounds,
+                max_tool_errors=self._config.child_max_tool_errors,
+            ),
+            hooks=wrap_up if self._hooks is None else ChainHooks(self._hooks, wrap_up),
+        )
+        return loop, schemas or None
+
+    # ------------------------------------------------------------------
+    # ToolExecutor
+    # ------------------------------------------------------------------
+
+    async def execute(self, call: ToolCall, ctx: LoopContext) -> ToolResult:
+        if call.name == self._config.spawn_tool:
+            return await self._spawn(call)
+        if call.name == self._config.send_tool:
+            return await self._send(call)
+        if call.name == self._config.wait_tool:
+            return await self._wait(call)
+        if call.name == self._config.close_tool:
+            return await self._close(call)
+        if call.name == self._config.list_tool:
+            return self._list(call)
+        if call.name == self._config.interrupt_tool:
+            return await self._interrupt(call)
+        return await self._inner.execute(call, ctx)
+
+    async def _spawn(self, call: ToolCall) -> ToolResult:
+        task = str(call.arguments.get("task") or "").strip()
+        if not task:
+            return ToolResult(success=False, error="empty task")
+        raw_filter = call.arguments.get("toolFilter")
+        tool_filter = (
+            frozenset(str(t) for t in raw_filter)
+            if isinstance(raw_filter, list)
+            else None
+        )
+        try:
+            handle = self._pool.spawn(task, tool_filter)
+        except OrchestrationBudgetExceeded as exc:
+            return ToolResult(
+                success=False,
+                error=f"orchestration_budget_exceeded: {exc}",
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps(
+                {
+                    "childId": handle.child_id,
+                    "depth": self._depth + 1,
+                    "status": "running",
+                }
+            ),
+            data={"childId": handle.child_id},
+        )
+
+    async def _send(self, call: ToolCall) -> ToolResult:
+        child_id = str(call.arguments.get("childId") or "")
+        message = str(call.arguments.get("message") or "").strip()
+        if not message:
+            return ToolResult(success=False, error="empty message")
+        outcome = self._pool.send(child_id, message)
+        if outcome.startswith("error:"):
+            return ToolResult(
+                success=False,
+                error=outcome[len("error:"):],
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps({"childId": child_id, "delivery": outcome}),
+            data={"childId": child_id, "delivery": outcome},
+        )
+
+    def _list(self, call: ToolCall) -> ToolResult:
+        entries = self._pool.list()
+        return ToolResult(
+            success=True,
+            message=json.dumps({"children": entries}),
+            data={"count": len(entries)},
+        )
+
+    async def _interrupt(self, call: ToolCall) -> ToolResult:
+        child_id = str(call.arguments.get("childId") or "")
+        if not self._pool.interrupt(child_id):
+            return ToolResult(
+                success=False,
+                error=(
+                    f"unknown_or_not_running: {child_id!r} — only a running, "
+                    "unclosed child can be interrupted"
+                ),
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True,
+            message=json.dumps({"childId": child_id, "interrupted": True}),
+            data={"childId": child_id},
+        )
+
+    async def _wait(self, call: ToolCall) -> ToolResult:
+        child_id = str(call.arguments.get("childId") or "")
+        raw_timeout = call.arguments.get("timeoutMs")
+        timeout_s = (
+            float(raw_timeout) / 1000.0
+            if isinstance(raw_timeout, (int, float))
+            else None
+        )
+        outcome = await self._pool.wait(child_id, timeout_s)
+        if outcome is None:
+            return ToolResult(
+                success=False,
+                error=f"unknown_child: {child_id!r}",
+                needsFollowup=True,
+            )
+        payload: dict[str, Any] = {
+            "childId": outcome.child_id,
+            "status": outcome.status,
+            "answer": outcome.answer,
+        }
+        if self._pool.resumable(outcome.child_id):
+            payload["resumable"] = True
+            payload["hint"] = _RESUME_HINT
+        return ToolResult(
+            success=True,
+            message=json.dumps(payload),
+            data={"childId": outcome.child_id, "status": outcome.status},
+        )
+
+    async def _close(self, call: ToolCall) -> ToolResult:
+        child_id = str(call.arguments.get("childId") or "")
+        if not await self._pool.close(child_id):
+            return ToolResult(
+                success=False,
+                error=f"unknown_child: {child_id!r}",
+                needsFollowup=True,
+            )
+        return ToolResult(
+            success=True, message=json.dumps({"childId": child_id, "closed": True})
+        )
+
+    async def shutdown(self) -> None:
+        """Wind down every live child — hosts call this when the parent run ends."""
+        await self._pool.shutdown()
+
+    def dedup_exempt(self, call: ToolCall) -> bool:
+        # Every orchestration tool is stateful: identical args yield different
+        # results as pool state evolves (a second spawn creates a NEW child,
+        # 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:
+            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:
+        # Spawn consumes the bounded parallel-capacity pool, so batching two
+        # spawns makes which call succeeds scheduler-dependent. Wait/list only
+        # observe pool state and may batch.
+        if call.name in {
+            self._config.wait_tool,
+            self._config.list_tool,
+        }:
+            return True
+        if call.name in {
+            self._config.spawn_tool,
+            self._config.send_tool,
+            self._config.close_tool,
+            self._config.interrupt_tool,
+        }:
+            return False
+        inner_safe = getattr(self._inner, "concurrency_safe", None)
+        return bool(inner_safe and inner_safe(call))