@steerable/runtime-win32-x64 0.9.2 → 0.10.0

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

@@ -0,0 +1,345 @@
+"""The child-agent registry: the durable answer to "what did this session spawn".
+
+The ``AgentPool`` only knows the children it is currently driving — it is
+built per turn and shut down with it, so a parent that finished a turn has no
+way to learn what it spawned. This registry is the durable index instead: one
+row per spawned child, written at spawn and settled at each terminal exit.
+
+State is **composed**, never stored as a single truth:
+
+- a terminal status comes from the row (``completed`` / ``error`` /
+  ``cancelled`` / ``budget_exhausted`` / ``closed``);
+- ``running`` is derived from a live in-process handle and is never written,
+  so a killed process cannot leave a permanently running row behind;
+- a row that never reached a terminal write while no handle exists is
+  ``interrupted`` — the parent turn ended or the process died mid-run, and
+  ``agent_send`` can resume it.
+
+That composition is what makes "what happened while the app was closed" a
+question the registry can answer, instead of a question the UI guesses at.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+
+from .child_record import (
+    INTERRUPTED_CHILD_STATUS,
+    RESUMABLE_CHILD_STATUSES,
+    ChildRecord,
+)
+from .llm import LLMUsage
+from .storage import StorageAdapter
+
+__all__ = [
+    "ChildRegistry",
+    "ChildStatusView",
+    "SpawnedChild",
+    "default_record_id",
+    "registry_status",
+]
+
+
+def default_record_id(parent_record_id: str, child_id: str) -> str:
+    """The one place the child record id is spelled.
+
+    ``<parent>:child:<lineage id>`` — hosts read child traces by this id
+    (``child_spawned`` publishes it), so deriving it anywhere else risks two
+    spellings of the same record.
+    """
+    return f"{parent_record_id}:child:{child_id}"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+#: The loop's completion vocabulary → the registry's. ``failed`` is what
+#: ``CoreLoop`` reports for a run that ended in error; ``error`` is what the
+#: pool records for a child whose run raised out of the loop entirely. One
+#: spelling reaches storage so a resumed child is not told "failed" while its
+#: row says "error".
+_COMPLETION_TO_REGISTRY: dict[str, str] = {
+    "completed": "completed",
+    "failed": "error",
+    "error": "error",
+    "cancelled": "cancelled",
+    "budget_exhausted": "budget_exhausted",
+    "closed": "closed",
+}
+
+
+def registry_status(completion_status: str) -> str:
+    """Translate a loop completion status into a registry status.
+
+    An unknown status raises rather than writing a row the resume path cannot
+    interpret: a child whose row says something nobody understands is worse
+    than a loudly failed bookkeeping write, which the caller logs and
+    continues from.
+    """
+    try:
+        return _COMPLETION_TO_REGISTRY[completion_status]
+    except KeyError:
+        raise ValueError(
+            f"unknown child completion status {completion_status!r}; expected one of "
+            f"{sorted(_COMPLETION_TO_REGISTRY)}"
+        ) from None
+
+
+@dataclass(frozen=True, slots=True)
+class SpawnedChild:
+    """What a caller must supply to register one spawn."""
+
+    parent_record_id: str
+    child_id: str
+    depth: int
+    profile: str | None
+    engine: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChildStatusView:
+    """One child as ``agent_list`` / the ``children`` CLI report it.
+
+    ``status`` is the composed answer (see the module docstring); ``live``
+    says whether an in-process handle exists right now, which is the one
+    fact the stored row cannot know.
+    """
+
+    record: ChildRecord
+    status: str
+    live: bool
+
+    @property
+    def resumable(self) -> bool:
+        """True when ``agent_send`` can continue this child.
+
+        A finished child can always be given a follow-up turn; an
+        ``interrupted`` one resumes from its record. A ``closed`` child never
+        does — that is what closing means.
+        """
+        if self.live:
+            return False
+        return (
+            self.status in RESUMABLE_CHILD_STATUSES
+            and self.record.status != "closed"
+        )
+
+    def to_wire(self, *, answer_preview: str | None = None) -> dict[str, object]:
+        """Model/host-facing payload.
+
+        ``answerPreview`` is supplied by the caller (read from the child's own
+        record) rather than stored here, so the registry never duplicates the
+        transcript.
+        """
+        payload: dict[str, object] = {
+            **self.record.to_wire(),
+            "status": self.status,
+            "live": self.live,
+            "resumable": self.resumable,
+        }
+        if answer_preview:
+            payload["answerPreview"] = answer_preview
+        return payload
+
+
+class ChildRegistry:
+    """Durable child-agent index over one ``StorageAdapter``.
+
+    A registry with ``store=None`` is inert: writes are no-ops, reads return
+    nothing. That is the shape a host without a storage adapter gets, and it
+    keeps the pool free of ``if store is not None`` branches.
+    """
+
+    def __init__(self, store: StorageAdapter | None) -> None:
+        self._store = store
+        #: Live handles by record id — the only source of ``running``.
+        self._live: dict[str, Callable[[], bool]] = {}
+        #: Rows noted but not yet written. ``spawn`` must not await, but the
+        #: row has to be visible to an ``agent_list`` issued immediately
+        #: after it, so the note is synchronous and the write happens at the
+        #: child's first await.
+        self._pending: dict[str, ChildRecord] = {}
+
+    # ------------------------------------------------------------------
+    # Writes
+    # ------------------------------------------------------------------
+
+    def note_spawn(
+        self, child: SpawnedChild, *, record_id: str | None = None
+    ) -> str:
+        """Note one spawn without awaiting storage; returns the record id.
+
+        Called inside ``AgentPool.spawn``, which is synchronous. The row is
+        readable at once (reads merge the pending set) and becomes durable at
+        ``flush_spawn``, which ``_run_child`` awaits before the child's first
+        model request — so a crash between the two leaves at worst an
+        unrecorded child, never a row claiming a child that never ran.
+        """
+        resolved = record_id or default_record_id(child.parent_record_id, child.child_id)
+        if self._store is None:
+            return resolved
+        now = _now_iso()
+        existing = self._pending.get(resolved)
+        created_at = existing.created_at if existing is not None else now
+        self._pending[resolved] = ChildRecord(
+            record_id=resolved,
+            parent_record_id=child.parent_record_id,
+            child_id=child.child_id,
+            depth=child.depth,
+            profile=child.profile,
+            engine=child.engine,
+            # ``running`` is never written; the row stays non-terminal until
+            # a real terminal status arrives.
+            status="pending",
+            resumable=False,
+            prompt_tokens=None,
+            completion_tokens=None,
+            usage_known=True,
+            created_at=created_at,
+            updated_at=now,
+        )
+        return resolved
+
+    async def flush_spawn(self, record_id: str) -> None:
+        """Persist a noted spawn. Idempotent; a no-op once written."""
+        record = self._pending.pop(record_id, None)
+        if record is None or self._store is None:
+            return
+        existing = await self._store.get_child(record_id)
+        # A resumed child keeps its original creation time: spawn order is
+        # what the panel and the CLI sort by, so a resumed child must not
+        # jump to the end of the list.
+        if existing is not None:
+            record = replace(record, created_at=existing.created_at)
+        await self._store.upsert_child(record)
+
+    async def spawned(self, child: SpawnedChild, *, record_id: str | None = None) -> str:
+        """Note and immediately persist one spawn; returns the record id."""
+        resolved = self.note_spawn(child, record_id=record_id)
+        await self.flush_spawn(resolved)
+        return resolved
+
+    async def finished(
+        self,
+        record_id: str,
+        *,
+        status: str,
+        usage: LLMUsage | None = None,
+        usage_known: bool = True,
+    ) -> bool:
+        """Settle one child's terminal status and usage.
+
+        ``usage=None`` with ``usage_known=False`` is the external-engine case
+        (ACP reports no token bill); ``usage=None`` with ``usage_known=True``
+        means a local child that reported nothing, which is still "known zero"
+        for budget purposes.
+        """
+        if self._store is None:
+            return False
+        # A child that settled before its row reached disk still needs one.
+        self._pending.pop(record_id, None)
+        prompt = usage.prompt_tokens if usage is not None else None
+        completion = usage.completion_tokens if usage is not None else None
+        return await self._store.finish_child(
+            record_id,
+            status=status,
+            prompt_tokens=prompt,
+            completion_tokens=completion,
+            usage_known=usage_known,
+            resumable=status in RESUMABLE_CHILD_STATUSES,
+            updated_at=_now_iso(),
+        )
+
+    # ------------------------------------------------------------------
+    # Live handles
+    # ------------------------------------------------------------------
+
+    def mark_live(self, record_id: str, is_live: Callable[[], bool]) -> None:
+        """Register the liveness probe for a child that is running now.
+
+        A *probe* rather than a boolean, so a caller that keeps the pool alive
+        across an await boundary cannot leave a stale ``True`` behind: the
+        registry asks the handle whether it is still running when it reports.
+        """
+        self._live[record_id] = is_live
+
+    def mark_settled(self, record_id: str) -> None:
+        """Forget a live handle once its run reached a terminal status."""
+        self._live.pop(record_id, None)
+
+    # ------------------------------------------------------------------
+    # Reads
+    # ------------------------------------------------------------------
+
+    async def get(self, record_id: str) -> ChildStatusView | None:
+        """One child with its composed status, or ``None``."""
+        if self._store is None:
+            return None
+        record = self._pending.get(record_id) or await self._store.get_child(record_id)
+        return self._view(record) if record is not None else None
+
+    async def list_for_parent(
+        self, parent_record_id: str, *, include_finished: bool = True
+    ) -> list[ChildStatusView]:
+        """Every child of one parent, oldest first.
+
+        Filtering happens after composition, not in the query: a row with a
+        non-terminal status and no live handle is ``interrupted``, which is
+        exactly what ``include_finished=False`` must keep.
+        """
+        if self._store is None:
+            return []
+        stored = {r.record_id: r for r in await self._store.list_children(parent_record_id)}
+        # Noted-but-unwritten rows are visible immediately, so a spawn
+        # issued in this same turn is already listed.
+        for record in self._pending.values():
+            if record.parent_record_id == parent_record_id:
+                stored[record.record_id] = record
+        records = sorted(stored.values(), key=lambda r: r.created_at)
+        views = [self._view(record) for record in records]
+        if not include_finished:
+            views = [view for view in views if not view.record.terminal]
+        return views
+
+    async def list_all(self, *, prefix: str | None = None) -> list[ChildStatusView]:
+        """Every child, optionally filtered by a ``parent_record_id`` prefix.
+
+        This is how a host answers "what did this session spawn" after a
+        restart, when no pool exists to ask.
+        """
+        if self._store is None:
+            return []
+        stored = {r.record_id: r for r in await self._store.list_all_children(prefix=prefix)}
+        for record in self._pending.values():
+            if prefix is None or record.parent_record_id.startswith(prefix):
+                stored[record.record_id] = record
+        records = sorted(stored.values(), key=lambda r: r.created_at)
+        return [self._view(record) for record in records]
+
+    async def find_child(self, parent_record_id: str, child_id: str) -> ChildStatusView | None:
+        """Resolve a lineage id (``0.2``) to its child within one parent.
+
+        Resume is addressed by lineage id — that is what the parent model
+        remembers and what tool results carry — so the lookup lives here
+        rather than making every caller scan ``list_for_parent``.
+        """
+        for view in await self.list_for_parent(parent_record_id):
+            if view.record.child_id == child_id:
+                return view
+        return None
+
+    def _view(self, record: ChildRecord) -> ChildStatusView:
+        probe = self._live.get(record.record_id)
+        live = bool(probe()) if probe is not None else False
+        if record.terminal:
+            # Closed is terminal and wins over any stale probe: a closed
+            # child is never "running", even if its task has not settled yet.
+            return ChildStatusView(record=record, status=record.status, live=False)
+        if live:
+            return ChildStatusView(record=record, status="running", live=True)
+        return ChildStatusView(
+            record=record, status=INTERRUPTED_CHILD_STATUS, live=False
+        )

package/python-runtime/python/Lib/site-packages/steerable_agent_runtime/storage/__init__.py

@@ -14,6 +14,8 @@ from steerable_agent_protocol.generated import (
     TraceSpan,
 )
 
+from ..child_record import ChildRecord
+
 
 @runtime_checkable
 class StorageAdapter(Protocol):
@@ -114,6 +116,56 @@ class StorageAdapter(Protocol):
         """
         ...
 
+    # -- Child-agent index ------------------------------------------------
+    #
+    # The durable answer to "whose child is this, how deep, what state".
+    # Rows carry no task text and no answer: those live in the child's own
+    # ``history`` record, so each fact has one authoritative copy.
+
+    async def upsert_child(self, record: ChildRecord) -> None:
+        """Write one child record whole, replacing any row with its
+        ``record_id``. Called at spawn; idempotent on retry."""
+        ...
+
+    async def finish_child(
+        self,
+        record_id: str,
+        *,
+        status: str,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        usage_known: bool = True,
+        resumable: bool = False,
+        updated_at: str,
+    ) -> bool:
+        """Record a child's terminal status and usage.
+
+        Returns ``False`` when no row exists for ``record_id`` — the child was
+        spawned without a registry, so there is nothing to finish.
+        """
+        ...
+
+    async def get_child(self, record_id: str) -> ChildRecord | None:
+        """One child record, or ``None``."""
+        ...
+
+    async def list_children(
+        self, parent_record_id: str, *, include_finished: bool = True
+    ) -> list[ChildRecord]:
+        """Direct children of one parent, oldest first."""
+        ...
+
+    async def list_all_children(
+        self, *, prefix: str | None = None
+    ) -> list[ChildRecord]:
+        """Every child record, optionally filtered by a ``parent_record_id``
+        prefix. Oldest first.
+
+        Enumerating all children is how a host answers "what did this session
+        spawn" after a restart, when no live pool exists.
+        """
+        ...
+
 
 from .in_memory import InMemoryStorage  # noqa: E402
 from .sqlite_store import SqliteStorage  # noqa: E402

package/python-runtime/python/Lib/site-packages/steerable_agent_runtime/storage/in_memory.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Iterable
 from copy import deepcopy
+from dataclasses import replace
 from typing import Any
 
 from steerable_agent_protocol.generated import (
@@ -16,6 +17,7 @@ from steerable_agent_protocol.generated import (
     TraceSpan,
 )
 
+from ..child_record import TERMINAL_CHILD_STATUSES, ChildRecord
 from ..errors import StorageError
 
 
@@ -32,6 +34,10 @@ class InMemoryStorage:
         self._spans: dict[str, list[TraceSpan]] = {}
         self._events: dict[str, list[TraceEvent]] = {}
         self._history: dict[str, list[dict[str, Any]]] = {}
+        #: Insertion order preserved (dicts are ordered) so ``list_children``
+        #: returns the spawn order a host renders, matching the SQL
+        #: ``ORDER BY created_at, rowid``.
+        self._children: dict[str, ChildRecord] = {}
 
     # ------------------------------------------------------------------
     # Sessions
@@ -213,3 +219,71 @@ class InMemoryStorage:
         if prefix is not None:
             ids = [record_id for record_id in ids if record_id.startswith(prefix)]
         return sorted(ids)
+
+    # ------------------------------------------------------------------
+    # Child-agent index
+    # ------------------------------------------------------------------
+
+    async def upsert_child(self, record: ChildRecord) -> None:
+        async with self._lock:
+            # Re-inserting an existing record keeps its original position:
+            # reassigning an existing key in a dict does not reorder it.
+            self._children[record.record_id] = replace(record)
+
+    async def finish_child(
+        self,
+        record_id: str,
+        *,
+        status: str,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        usage_known: bool = True,
+        resumable: bool = False,
+        updated_at: str,
+    ) -> bool:
+        async with self._lock:
+            existing = self._children.get(record_id)
+            if existing is None:
+                return False
+            self._children[record_id] = existing.with_terminal_status(
+                status=status,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                usage_known=usage_known,
+                resumable=resumable,
+                updated_at=updated_at,
+            )
+            return True
+
+    async def get_child(self, record_id: str) -> ChildRecord | None:
+        async with self._lock:
+            return self._children.get(record_id)
+
+    async def list_children(
+        self, parent_record_id: str, *, include_finished: bool = True
+    ) -> list[ChildRecord]:
+        async with self._lock:
+            records = [
+                record
+                for record in self._children.values()
+                if record.parent_record_id == parent_record_id
+            ]
+        if not include_finished:
+            records = [r for r in records if r.status not in TERMINAL_CHILD_STATUSES]
+        # Parity with the SQL ``ORDER BY created_at, rowid``: sort by
+        # ``created_at`` only — Python's sort is stable, so insertion order
+        # (this dict's order) breaks ties the way ``rowid`` does.
+        records.sort(key=lambda r: r.created_at)
+        return records
+
+    async def list_all_children(
+        self, *, prefix: str | None = None
+    ) -> list[ChildRecord]:
+        async with self._lock:
+            records = list(self._children.values())
+        if prefix is not None:
+            records = [
+                r for r in records if r.parent_record_id.startswith(prefix)
+            ]
+        records.sort(key=lambda r: r.created_at)
+        return records

package/python-runtime/python/Lib/site-packages/steerable_agent_runtime/storage/sqlalchemy_store.py

@@ -36,6 +36,7 @@ except Exception as exc:  # pragma: no cover - optional dep
         "`pip install steerable-agent-runtime[sqlalchemy]`."
     ) from exc
 
+from ..child_record import TERMINAL_CHILD_STATUSES, ChildRecord
 from ..errors import StorageError
 
 metadata = MetaData()
@@ -156,6 +157,26 @@ history_table = Table(
     UniqueConstraint("recordId", "seq", name="steerable_history_entry_seq_uniq"),
 )
 
+# Schema v2: the child-agent index. Only the edge and the state — task text
+# and answers live in the child's own history record.
+children_table = Table(
+    "steerable_child",
+    metadata,
+    Column("recordId", String(191), primary_key=True),
+    Column("parentRecordId", String(191), nullable=False, index=True),
+    Column("childId", String(191), nullable=False),
+    Column("depth", Integer, nullable=False),
+    Column("profile", String(191), nullable=True),
+    Column("engine", String(32), nullable=False),
+    Column("status", String(32), nullable=False),
+    Column("resumable", Boolean, nullable=False, default=False),
+    Column("promptTokens", Integer, nullable=True),
+    Column("completionTokens", Integer, nullable=True),
+    Column("usageKnown", Boolean, nullable=False, default=True),
+    Column("createdAt", DateTime, nullable=False),
+    Column("updatedAt", DateTime, nullable=False),
+)
+
 
 def _model_to_row(model: Any, table: Table) -> dict[str, Any]:
     """Dump only the columns the table persists, coercing value types.
@@ -193,6 +214,62 @@ def _row_to_model(table: Table, row: dict[str, Any]) -> dict[str, Any]:
     return out
 
 
+def _child_to_row(record: ChildRecord) -> dict[str, Any]:
+    """``ChildRecord`` → the ``children_table`` column values.
+
+    Timestamps cross from ISO strings to the table's ``DateTime`` columns,
+    the same bridge ``_model_to_row`` makes for protocol models.
+    """
+    return {
+        "recordId": record.record_id,
+        "parentRecordId": record.parent_record_id,
+        "childId": record.child_id,
+        "depth": record.depth,
+        "profile": record.profile,
+        "engine": record.engine,
+        "status": record.status,
+        "resumable": record.resumable,
+        "promptTokens": record.prompt_tokens,
+        "completionTokens": record.completion_tokens,
+        "usageKnown": record.usage_known,
+        "createdAt": _as_datetime(record.created_at),
+        "updatedAt": _as_datetime(record.updated_at),
+    }
+
+
+def _child_from_row(row: dict[str, Any]) -> ChildRecord:
+    """Inverse of ``_child_to_row``."""
+    return ChildRecord(
+        record_id=row["recordId"],
+        parent_record_id=row["parentRecordId"],
+        child_id=row["childId"],
+        depth=int(row["depth"]),
+        profile=row["profile"],
+        engine=row["engine"],
+        status=row["status"],
+        resumable=bool(row["resumable"]),
+        prompt_tokens=row["promptTokens"],
+        completion_tokens=row["completionTokens"],
+        usage_known=bool(row["usageKnown"]),
+        created_at=_as_iso(row["createdAt"]),
+        updated_at=_as_iso(row["updatedAt"]),
+    )
+
+
+def _as_datetime(value: str | datetime) -> datetime:
+    """ISO string or ``datetime`` → ``datetime`` (idempotent)."""
+    if isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _as_iso(value: str | datetime) -> str:
+    """``datetime`` or ISO string → ISO string (idempotent)."""
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
 class SqlAlchemyStorage:
     """SQLAlchemy 2.0 async StorageAdapter."""
 
@@ -411,6 +488,82 @@ class SqlAlchemyStorage:
             )
             return sorted(row[0] for row in result.all())
 
+    # ------------------------------------------------------------------
+    # Child-agent index (schema v2)
+    # ------------------------------------------------------------------
+
+    async def upsert_child(self, record: ChildRecord) -> None:
+        await self._upsert(
+            children_table,
+            "recordId",
+            record.record_id,
+            _child_to_row(record),
+        )
+
+    async def finish_child(
+        self,
+        record_id: str,
+        *,
+        status: str,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        usage_known: bool = True,
+        resumable: bool = False,
+        updated_at: str,
+    ) -> bool:
+        existing = await self._get_one(
+            children_table, children_table.c.recordId == record_id
+        )
+        if existing is None:
+            return False
+        async with self._sessionmaker() as session:
+            await session.execute(
+                children_table.update()
+                .where(children_table.c.recordId == record_id)
+                .values(
+                    status=status,
+                    resumable=resumable,
+                    promptTokens=prompt_tokens,
+                    completionTokens=completion_tokens,
+                    usageKnown=usage_known,
+                    updatedAt=datetime.fromisoformat(updated_at.replace("Z", "+00:00")),
+                )
+            )
+            await session.commit()
+        return True
+
+    async def get_child(self, record_id: str) -> ChildRecord | None:
+        row = await self._get_one(
+            children_table, children_table.c.recordId == record_id
+        )
+        return _child_from_row(row) if row else None
+
+    async def list_children(
+        self, parent_record_id: str, *, include_finished: bool = True
+    ) -> list[ChildRecord]:
+        clauses = [children_table.c.parentRecordId == parent_record_id]
+        if not include_finished:
+            clauses.append(children_table.c.status.not_in(TERMINAL_CHILD_STATUSES))
+        rows = await self._select_many(
+            children_table,
+            clauses=clauses,
+            order_by=[children_table.c.createdAt.asc()],
+        )
+        return [_child_from_row(row) for row in rows]
+
+    async def list_all_children(
+        self, *, prefix: str | None = None
+    ) -> list[ChildRecord]:
+        clauses = []
+        if prefix is not None:
+            clauses.append(children_table.c.parentRecordId.startswith(prefix))
+        rows = await self._select_many(
+            children_table,
+            clauses=clauses,
+            order_by=[children_table.c.createdAt.asc()],
+        )
+        return [_child_from_row(row) for row in rows]
+
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------