@steerable/runtime-win32-x64 0.9.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/runtime-win32-x64",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Steerable runtime bundle for win32-x64: Python sidecar and egress proxy.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",

package/python-runtime/manifest.json

@@ -3,6 +3,6 @@
   "pythonBuildStandaloneRelease": "20260510",
   "pythonVersion": "3.12.13",
   "target": "win32-x64",
-  "totalBytes": 109573820,
+  "totalBytes": 109729430,
   "triple": "x86_64-pc-windows-msvc"
 }

package/python-runtime/python/Lib/site-packages/cffi-2.1.1.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/cffi-gen-src.exe,sha256=leHIcoFK5isHjnRFqZeTHLHvlFOM92KC8LHeJeyaqVk,108388
+../../Scripts/cffi-gen-src.exe,sha256=Zivsl8ko9fk244xL-CEH27FnFkFdvIPOeL-Z0KEgla0,108388
 _cffi_backend.cp312-win_amd64.pyd,sha256=mvXk9opB8mtyby6UJPnVik9WZhifaki-lfQGslcQKuw,181248
 cffi-2.1.1.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
 cffi-2.1.1.dist-info/METADATA,sha256=Z7anWV337eIZUBagXShfqn02Ko9XwjiYTtuLtnS1dw0,2594

package/python-runtime/python/Lib/site-packages/httpx-0.28.1.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/httpx.exe,sha256=yFFJb1gr04VEbSqKbkTolRERIO1B_Nj-2xW9rBi13iI,108377
+../../Scripts/httpx.exe,sha256=w2krSROCLDam4SIizZ8h6560s0GWydAOPZQW4BJ-Q3c,108377
 httpx-0.28.1.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
 httpx-0.28.1.dist-info/METADATA,sha256=_rubD48-gNV8gZnDBPNcQzboWB0dGNeYPJJ2a4J5OyU,7052
 httpx-0.28.1.dist-info/RECORD,,

package/python-runtime/python/Lib/site-packages/idna-3.20.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/idna.exe,sha256=NvWwXxrfkaFuMAKPSOgoYT8Ym14k9Crq0-A_LI2S18k,108380
+../../Scripts/idna.exe,sha256=dQJXpAPBYX4AFcNaAmS8VSAnP2mIgB924WkoxxEJx2g,108380
 idna-3.20.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
 idna-3.20.dist-info/METADATA,sha256=29jBTB5MoeDJgkptvHy794iE8461LZEUjNMCX2ceS4U,7207
 idna-3.20.dist-info/RECORD,,

package/python-runtime/python/Lib/site-packages/jsonschema-4.26.0.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/jsonschema.exe,sha256=x2lQEuIYvYFhKJ6pTOU0znGtdatLygLHT-bqsL3sUFM,108386
+../../Scripts/jsonschema.exe,sha256=4oCz5sBzF1xpGTjZmHd21IMH4hSNCs25w70qV2G4w5c,108386
 jsonschema-4.26.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
 jsonschema-4.26.0.dist-info/METADATA,sha256=BbGJhmypipbaOTS_a4NofO0_-FMlJzt34WtwX22LJtI,7592
 jsonschema-4.26.0.dist-info/RECORD,,

package/python-runtime/python/Lib/site-packages/mcp-1.30.0.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/mcp.exe,sha256=9EDqv8TI214EawmpUCthNoqYFei3R0CNaQyqE_VQPiI,108377
+../../Scripts/mcp.exe,sha256=xGljkG9hOH-0gBy8jSzFrq6vzIWwDcddahCaLEpcB5g,108377
 mcp-1.30.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
 mcp-1.30.0.dist-info/METADATA,sha256=OIDCmJYUmGKXGvV5QuPlwK0qkJaWpmuYEcYvbkfmURE,9289
 mcp-1.30.0.dist-info/RECORD,,

package/python-runtime/python/Lib/site-packages/python_dotenv-1.2.4.dist-info/RECORD

@@ -1,4 +1,4 @@
-../../Scripts/dotenv.exe,sha256=agzc8bk5PvhviDKZwIZ8SmQZ7Go-HhbFyrzsYG-0b28,108385
+../../Scripts/dotenv.exe,sha256=Icvj6FrDFpujkrW7N_n1ga_vW45dYpJ_RdMfWzIs_fo,108385
 dotenv/__init__.py,sha256=bhY-iK6wwHZamWII6eSCuCAWXUNdn2TQFmEOuXSU7SM,1230
 dotenv/__main__.py,sha256=N0RhLG7nHIqtlJHwwepIo-zbJPNx9sewCCRGY528h_4,129
 dotenv/__pycache__/__init__.cpython-312.pyc,,

package/python-runtime/python/Lib/site-packages/pywin32-312.dist-info/RECORD

@@ -1,8 +1,8 @@
 ../../Scripts/__pycache__/pywin32_postinstall.cpython-312.pyc,,
 ../../Scripts/__pycache__/pywin32_testall.cpython-312.pyc,,
-../../Scripts/pywin32_postinstall.exe,sha256=GpPJcr4s7LanQqSeJhIeALwdrmBr_4Dg56n6lpUTA-M,108405
+../../Scripts/pywin32_postinstall.exe,sha256=DXGtSVHBKZkR8yGUbR0l8brfflJp4tABr3oic5np7JU,108405
 ../../Scripts/pywin32_postinstall.py,sha256=RT3RogIBArMUhRCFaivWkl2NsVZwr9cNNd2hcsXUBU4,25576
-../../Scripts/pywin32_testall.exe,sha256=hmLvhF4w_30LM9i2iPqK9JLG2S84AOex1mXgpBeALe0,108401
+../../Scripts/pywin32_testall.exe,sha256=cm5gX-G_W9N1YD_wIaSCpl7G2wFteflaJSH4q6tF6uI,108401
 ../../Scripts/pywin32_testall.py,sha256=FYvjx43thdvbkWaYiLMTX39RxsFL0c-1o-xY2udlBqA,3847
 PyWin32.chm,sha256=X8MAsKaFhJRAzKBn0QR-GEXRoShgndE6NQg6LqhzTVI,2642799
 __pycache__/pythoncom.cpython-312.pyc,,

package/python-runtime/python/Lib/site-packages/{steerable_agent_harness-0.9.2.dist-info → steerable_agent_harness-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-harness
-Version: 0.9.2
+Version: 0.10.0
 Summary: Steerable harness helpers for Python
 License: Apache-2.0
 Requires-Python: >=3.10

package/python-runtime/python/Lib/site-packages/{steerable_agent_harness-0.9.2.dist-info → steerable_agent_harness-0.10.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-steerable_agent_harness-0.9.2.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
-steerable_agent_harness-0.9.2.dist-info/METADATA,sha256=ReFNPRnnHzBjKI_wfHTCoB6uymt5MlG4SQGY2Q22asg,384
-steerable_agent_harness-0.9.2.dist-info/RECORD,,
-steerable_agent_harness-0.9.2.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-steerable_agent_harness-0.9.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-steerable_agent_harness-0.9.2.dist-info/direct_url.json,sha256=on9xIvaeYpEzpvwPmZq-Ns1O0eUXFoekpr1zaHHxgrI,289
-steerable_agent_harness-0.9.2.dist-info/top_level.txt,sha256=L99GRcOHaeL_gakhZZnmpEbK5yV4fOeIxXzWKW_2lDA,24
+steerable_agent_harness-0.10.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+steerable_agent_harness-0.10.0.dist-info/METADATA,sha256=hezhQUaNKGROfqHgUMQfwBLzvMkqiqhACLvEBXS-liw,385
+steerable_agent_harness-0.10.0.dist-info/RECORD,,
+steerable_agent_harness-0.10.0.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steerable_agent_harness-0.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+steerable_agent_harness-0.10.0.dist-info/direct_url.json,sha256=UXvoylUbK4Lkfuzi3TRjKqrGCVAmNd-ebjMbkos5cAk,290
+steerable_agent_harness-0.10.0.dist-info/top_level.txt,sha256=L99GRcOHaeL_gakhZZnmpEbK5yV4fOeIxXzWKW_2lDA,24
 steerable_agent_harness/__init__.py,sha256=hZK9IhKIFS66jIYH9LKMNuGmdJkLEeE5LsPeRPcLl6E,1253
 steerable_agent_harness/__pycache__/__init__.cpython-312.pyc,,
 steerable_agent_harness/__pycache__/budget.cpython-312.pyc,,

package/python-runtime/python/Lib/site-packages/{steerable_agent_protocol-0.9.2.dist-info → steerable_agent_protocol-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-protocol
-Version: 0.9.2
+Version: 0.10.0
 Summary: Steerable protocol schemas for Python
 License: Apache-2.0
 Requires-Python: >=3.10

package/python-runtime/python/Lib/site-packages/steerable_agent_protocol-0.10.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+steerable_agent_protocol-0.10.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+steerable_agent_protocol-0.10.0.dist-info/METADATA,sha256=IgT9xICSjhelATS_pyfkbK_Ou1UlVBlhn2kPJbItGYg,328
+steerable_agent_protocol-0.10.0.dist-info/RECORD,,
+steerable_agent_protocol-0.10.0.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steerable_agent_protocol-0.10.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+steerable_agent_protocol-0.10.0.dist-info/direct_url.json,sha256=e_xB1q2-B5msly9-DBUbHPG6yqDTLnFuKp6JrevO-rA,291
+steerable_agent_protocol-0.10.0.dist-info/top_level.txt,sha256=K8P6-3hLZwuhUEWM2CS2wjFpBzJ83fyzZbdS2Txh4VU,25
+steerable_agent_protocol/__init__.py,sha256=adci5VbbNw9seedRNj8OsibxVH3B1M531_adq3fIU1c,25
+steerable_agent_protocol/__pycache__/__init__.cpython-312.pyc,,
+steerable_agent_protocol/__pycache__/generated.cpython-312.pyc,,
+steerable_agent_protocol/generated.py,sha256=jeynKncOP0HWEpXcFs7A7y3z4zloR0njCar2gMcBfbo,6005

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

@@ -83,6 +83,7 @@ from .branch import (
     lineage,
     resolve_fork_seq,
 )
+from .budget import SessionBudgetExceeded, TreeBudget, TreeBudgetReport
 from .cache_control import (
     CacheControlProvider,
     CacheDriftMonitor,
@@ -91,6 +92,22 @@ from .cache_control import (
     system_blocks_with_cache,
 )
 from .calibration import CalibratingProvider, ModelCalibration, UsageCalibration
+from .child_record import (
+    INTERRUPTED_CHILD_STATUS,
+    RESUMABLE_CHILD_STATUSES,
+    TERMINAL_CHILD_STATUSES,
+    ChildRecord,
+)
+from .child_notice import CHILD_NOTICE_KIND, ChildNoticeHooks, render_child_notice
+from .engines import (
+    AcpEngineSpec,
+    AcpOutcome,
+    AcpPermissionPolicy,
+    AcpToolBridge,
+    AcpUnavailable,
+    PermissionDiagnostic,
+    run_acp_child,
+)
 from .compaction_policy import (
     CompactionPolicy,
     is_large_window,
@@ -121,6 +138,7 @@ from .history import (
     RecordEntry,
     RecordFormatError,
     SystemPromptFragment,
+    completed_turn_prefix,
     entry_from_dict,
     render_fragment_capped,
     entry_to_dict,
@@ -209,6 +227,13 @@ from .pricing import (
     register_model_price,
 )
 from .pseudo import extract_inline_tool_calls
+from .registry import (
+    ChildRegistry,
+    ChildStatusView,
+    SpawnedChild,
+    default_record_id,
+    registry_status,
+)
 from .recording import (
     DEFAULT_MAX_ITEM_TOKENS,
     InMemoryRequestSink,
@@ -292,6 +317,13 @@ from .world_state import (
 )
 
 __all__ = [
+    "AcpEngineSpec",
+    "AcpOutcome",
+    "AcpPermissionPolicy",
+    "AcpToolBridge",
+    "AcpUnavailable",
+    "PermissionDiagnostic",
+    "run_acp_child",
     "DEFAULT_MAX_ITEM_TOKENS",
     "DEFAULT_MAX_SERVER_TOOLS",
     "DEFAULT_SHELL_TOOLS",
@@ -338,6 +370,21 @@ __all__ = [
     "CacheControlProvider",
     "CacheDriftMonitor",
     "CacheRetention",
+    "ChildRecord",
+    "ChildRegistry",
+    "ChildNoticeHooks",
+    "CHILD_NOTICE_KIND",
+    "SessionBudgetExceeded",
+    "TreeBudget",
+    "TreeBudgetReport",
+    "render_child_notice",
+    "ChildStatusView",
+    "SpawnedChild",
+    "default_record_id",
+    "registry_status",
+    "INTERRUPTED_CHILD_STATUS",
+    "RESUMABLE_CHILD_STATUSES",
+    "TERMINAL_CHILD_STATUSES",
     "CalibratingProvider",
     "ChainHooks",
     "ChildOutcome",
@@ -354,6 +401,7 @@ __all__ = [
     "ContentPart",
     "ContextFragment",
     "ContextManager",
+    "completed_turn_prefix",
     "CoreLoop",
     "DecisionNote",
     "ExecutionBudget",

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

@@ -0,0 +1,124 @@
+"""One token budget for a whole delegating turn tree.
+
+``steerable_agent_harness.budget`` budgets **one loop run**: it charges that
+run's own requests and reports exhaustion to that run. That is the wrong scope
+once a turn can delegate: a parent plus three children would each get the full
+allowance, so a turn's real spend could be four times what the host asked for
+and no single loop would ever notice.
+
+This module is the other scope — one counter shared by every agent in the tree.
+Each request, whoever made it, charges the same state, and the first one to
+cross the limit fails there. The alternative (handing each child a slice of
+the remainder) was considered and rejected: a serial child given 1/(n+1) of
+the budget hits its own wall while the tree still has room, which turns a
+generous budget into a tight one.
+
+Attribution is kept alongside the total because "the turn spent 40k" is not
+actionable when a host needs to know which child spent it.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+
+from .llm import LLMUsage
+
+__all__ = ["SessionBudgetExceeded", "TreeBudget", "TreeBudgetReport"]
+
+
+class SessionBudgetExceeded(Exception):
+    """Raised when a request would take the tree past its token limit.
+
+    Named for the session, not for a child: the limit belongs to the whole
+    turn tree, and the agent that happens to cross it is not the one at fault.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class TreeBudgetReport:
+    """The tree's spend at one point in time.
+
+    ``by_agent`` keys are the caller's own agent labels (``"parent"``,
+    ``"0.1"`` …) — the budget does not know about lineage and must not guess
+    it, so it stores whatever key the caller passes.
+    """
+
+    limit: int
+    spent: int
+    by_agent: dict[str, int]
+
+    @property
+    def remaining(self) -> int:
+        return max(self.limit - self.spent, 0)
+
+    @property
+    def exhausted(self) -> bool:
+        return self.spent >= self.limit
+
+
+@dataclass
+class TreeBudget:
+    """A token limit shared by every agent in one turn tree.
+
+    Thread-safe: the loop hands usage in from both the parent's event loop and
+    the worker thread that drives the native engine, so plain attribute
+    updates would race.
+    """
+
+    limit: int
+    _spent: int = field(default=0, init=False)
+    _by_agent: dict[str, int] = field(default_factory=dict, init=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+
+    def charge(self, usage: LLMUsage | None, *, agent: str) -> int:
+        """Charge one request's usage; returns the tree's spend afterwards.
+
+        ``usage=None`` charges nothing but still records the agent, so a host
+        can tell "this child ran and reported nothing" apart from "this child
+        never ran" — the distinction matters when the bill does not add up.
+
+        Raises:
+            SessionBudgetExceeded: when the charge takes the tree past
+                ``limit``. The spend is recorded **before** raising, so the
+                report a caller shows still includes the request that broke it.
+        """
+        if usage is None:
+            with self._lock:
+                self._by_agent.setdefault(agent, 0)
+            return self._spent
+        # Total, not prompt+completion: providers disagree about whether the
+        # total includes cache reads, and ``usage.total_tokens`` is the one
+        # number every provider reports consistently.
+        billed = max(usage.total_tokens, 0)
+        with self._lock:
+            self._spent += billed
+            self._by_agent[agent] = self._by_agent.get(agent, 0) + billed
+            spent = self._spent
+        if spent > self.limit:
+            raise SessionBudgetExceeded(
+                f"turn tree spent {spent} tokens against a {self.limit}-token "
+                f"budget (agent {agent!r} crossed it)"
+            )
+        return spent
+
+    @property
+    def remaining(self) -> int:
+        """Tokens left, floored at zero."""
+        with self._lock:
+            return max(self.limit - self._spent, 0)
+
+    @property
+    def exhausted(self) -> bool:
+        """True once the tree has spent its whole limit."""
+        with self._lock:
+            return self._spent >= self.limit
+
+    def report(self) -> TreeBudgetReport:
+        """A snapshot, safe to hand to a host mid-turn."""
+        with self._lock:
+            return TreeBudgetReport(
+                limit=self.limit,
+                spent=self._spent,
+                by_agent=dict(self._by_agent),
+            )

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

@@ -0,0 +1,84 @@
+"""Parent-side delivery of child-agent terminal notices.
+
+A parent that spawned children has two ways to learn one finished: poll
+``agent_wait``, or be told. Polling costs a whole model round per check and,
+worse, the model has to *remember* to look. This hook closes that gap: when a
+child of this pool settles, the notice is appended to the parent's transcript
+at its next round boundary.
+
+Design notes that matter for correctness:
+
+- The notice is a **system-role** message with its own record kind
+  (``subagent.notice``). It is not a user message: nothing about it came from
+  the user, and a model that treats it as an instruction from the user would
+  be misreading the conversation.
+- The notice carries **no child text**. The answer still comes from
+  ``agent_wait``; putting the answer here would duplicate the child's output
+  into the parent's context on every finish, and the parent may never read it.
+- Delivery is idempotent per child: each notice is drained exactly once, so a
+  settled child cannot re-notify on every later step.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .hooks import NoopHooks, PreStepAction, TranscriptAppend
+from .llm import LLMMessage
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .loop import LoopContext
+    from .pool import AgentPool
+
+__all__ = ["CHILD_NOTICE_KIND", "ChildNoticeHooks"]
+
+#: Record kind for the injected notice. ``<feature>.<name>`` like the other
+#: injected fragments (``skills.catalog``, ``world_state.patch``), so a replay
+#: can tell it apart from anything the user or the model said.
+CHILD_NOTICE_KIND = "subagent.notice"
+
+
+class ChildNoticeHooks(NoopHooks):
+    """``pre_step``: append notices for children that settled since last step.
+
+    One instance per parent loop. Wrap it in a ``ChainHooks`` with whatever
+    else the host installs — this hook only ever appends; it never rewrites,
+    never rejects, and never changes tool choice.
+    """
+
+    def __init__(self, pool: AgentPool) -> None:
+        self._pool = pool
+
+    async def pre_step(
+        self, transcript: list[LLMMessage], ctx: "LoopContext"
+    ) -> PreStepAction:
+        notices = self._pool.drain_notices()
+        if not notices:
+            return PreStepAction(kind="proceed")
+        appends = [
+            TranscriptAppend(
+                message=LLMMessage.text_of("system", render_child_notice(*notice)),
+                kind=CHILD_NOTICE_KIND,
+            )
+            for notice in notices
+        ]
+        return PreStepAction(
+            kind="proceed",
+            appends=appends,
+            append_action="child_notice",
+        )
+
+
+def render_child_notice(child_id: str, status: str, answer: str) -> str:
+    """The notice text.
+
+    A system message, so it reads as harness bookkeeping rather than as either
+    party speaking. The one line of guidance matters: without it a model that
+    sees "child 0.2 completed" tends to narrate the completion instead of
+    collecting the answer.
+    """
+    settled = "finished" if status == "completed" else f"ended with status {status}"
+    return (
+        f"[sub-agent notice] Sub-agent {child_id} {settled}. "
+        "Its answer is not included here; call agent_wait to read it."
+    )

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

@@ -0,0 +1,174 @@
+"""The child-agent registry record: one shape, shared by every store.
+
+A record answers only "whose child is this, how deep, what built it, and
+where it ended". Task text and answers are deliberately absent — they live
+in the child's own ``history`` record, so each fact has one authoritative
+copy.
+
+This module is a leaf: no storage and no agent imports. Both the registry
+(``registry.py``) and the adapters (``storage/sqlite_store.py``) read these
+definitions, which is what keeps their column mapping from drifting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+#: Statuses that will never change again. ``running`` is absent on purpose:
+#: it is derived from a live in-process handle, never written, so a killed
+#: process cannot leave a permanently "running" row behind.
+TERMINAL_CHILD_STATUSES: frozenset[str] = frozenset(
+    {
+        "completed",
+        "error",
+        "cancelled",
+        "budget_exhausted",
+        "closed",
+    }
+)
+
+#: Derived, never written: the child has no terminal row and no live handle.
+#: The parent turn ended or the process died mid-run; ``agent_send`` resumes it.
+INTERRUPTED_CHILD_STATUS = "interrupted"
+
+#: Statuses that accept a further message. ``closed`` is excluded: it is the
+#: caller's explicit "never again" and must stay that way.
+RESUMABLE_CHILD_STATUSES: frozenset[str] = frozenset(
+    {
+        "completed",
+        "interrupted",
+        "cancelled",
+        "budget_exhausted",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ChildRecord:
+    """One registry row.
+
+    ``record_id`` is the child's own durable record (``<parent>:child:<lineage
+    id>``); ``child_id`` is the lineage id inside the parent's pool. ``depth``
+    and ``profile`` are duplicated from creation time on purpose: resume must
+    rebuild the child's tool domain and nesting from what it was created with,
+    never from current settings — otherwise a depth-1 child that was never
+    allowed to spawn would gain orchestration tools by being resumed.
+    """
+
+    record_id: str
+    parent_record_id: str
+    child_id: str
+    depth: int
+    profile: str | None
+    engine: str
+    status: str
+    resumable: bool
+    prompt_tokens: int | None
+    completion_tokens: int | None
+    usage_known: bool
+    created_at: str
+    updated_at: str
+
+    @property
+    def terminal(self) -> bool:
+        """True when this status will never change again."""
+        return self.status in TERMINAL_CHILD_STATUSES
+
+    def with_terminal_status(
+        self,
+        *,
+        status: str,
+        prompt_tokens: int | None,
+        completion_tokens: int | None,
+        usage_known: bool,
+        resumable: bool,
+        updated_at: str,
+    ) -> ChildRecord:
+        """This record after a run settled."""
+        return replace(
+            self,
+            status=status,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            usage_known=usage_known,
+            resumable=resumable,
+            updated_at=updated_at,
+        )
+
+    def to_wire(self) -> dict[str, Any]:
+        """Camel-case payload shape for ``agent_list`` and the ``children`` CLI.
+
+        The row is already model-facing (it says nothing about storage), so
+        this is the only translation step between disk and the protocol.
+        """
+        return {
+            "recordId": self.record_id,
+            "parentRecordId": self.parent_record_id,
+            "childId": self.child_id,
+            "depth": self.depth,
+            "profile": self.profile,
+            "engine": self.engine,
+            "status": self.status,
+            "resumable": self.resumable,
+            "promptTokens": self.prompt_tokens,
+            "completionTokens": self.completion_tokens,
+            "usageKnown": self.usage_known,
+            "createdAt": self.created_at,
+            "updatedAt": self.updated_at,
+        }
+
+
+#: Record attribute → SQL column, in insert order. Adapters use this to bind
+#: one statement; ``child_row.to_wire`` uses the attribute names for the wire.
+CHILD_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("record_id", "record_id"),
+    ("parent_record_id", "parent_record_id"),
+    ("child_id", "child_id"),
+    ("depth", "depth"),
+    ("profile", "profile"),
+    ("engine", "engine"),
+    ("status", "status"),
+    ("resumable", "resumable"),
+    ("prompt_tokens", "prompt_tokens"),
+    ("completion_tokens", "completion_tokens"),
+    ("usage_known", "usage_known"),
+    ("created_at", "created_at"),
+    ("updated_at", "updated_at"),
+)
+
+_INT_FIELDS = frozenset({"depth"})
+_BOOL_FIELDS = frozenset({"resumable", "usage_known"})
+
+
+def record_to_values(record: ChildRecord) -> tuple[Any, ...]:
+    """Positional values for the insert whose columns are ``CHILD_COLUMNS``.
+
+    SQLite has no boolean type, so flags bind as 0/1 here rather than at each
+    call site.
+    """
+    values: list[Any] = []
+    for attribute, _column in CHILD_COLUMNS:
+        value = getattr(record, attribute)
+        if attribute in _BOOL_FIELDS:
+            values.append(int(bool(value)))
+        else:
+            values.append(value)
+    return tuple(values)
+
+
+def record_from_columns(columns: dict[str, Any]) -> ChildRecord:
+    """Rebuild a record from a store's column mapping.
+
+    Flags arrive as 0/1 from SQLite and as ``bool`` from SQLAlchemy; both are
+    normalised here so callers never branch on the storage engine.
+    """
+    values: dict[str, Any] = {}
+    for attribute, column in CHILD_COLUMNS:
+        value = columns[column]
+        if attribute in _INT_FIELDS:
+            value = int(value)
+        elif attribute in _BOOL_FIELDS:
+            value = bool(value)
+        values[attribute] = value
+    return ChildRecord(**values)