steerable-agent-runtime 0.6.2__tar.gz → 0.6.4__tar.gz

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.2
+Version: 0.6.4
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.6.2"
+version = "0.6.4"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 readme = "README.md"
 requires-python = ">=3.10"

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/__init__.py

@@ -35,6 +35,13 @@ from .ask_user import (
     AskUserHandler,
     make_ask_user_tool,
 )
+from .todo import (
+    TODO_SCHEMA,
+    TODO_TOOL_NAME,
+    TodoStore,
+    make_todo_write_tool,
+    todo_write_tool_descriptor,
+)
 from .config import (
     DEFAULT_CONFIG_PATH,
     ConfigError,
@@ -44,13 +51,23 @@ from .config import (
 )
 from .plugins import (
     STEERABLE_TOOLS_ENTRY_POINT_GROUP,
+    DirectorySource,
+    EntryPointSource,
     PluginLoadError,
+    PluginRecord,
+    PluginRegistry,
+    PluginSource,
+    PluginSpec,
+    PluginStateError,
     load_tool_entry_points,
 )
 from .branch import (
     BranchPoint,
+    FamilyTree,
+    FamilyTreeNode,
     ForkResult,
     branch_label,
+    family_tree,
     fork_record,
     lineage,
     resolve_fork_seq,
@@ -252,11 +269,20 @@ __all__ = [
     "TOOL_SEARCH_NAME",
     "ASK_USER_SCHEMA",
     "ASK_USER_TOOL_NAME",
+    "TODO_SCHEMA",
+    "TODO_TOOL_NAME",
     "STEERABLE_TOOLS_ENTRY_POINT_GROUP",
     "AgentPool",
     "AntiHallucinationConfig",
     "AskUserHandler",
+    "DirectorySource",
+    "EntryPointSource",
     "PluginLoadError",
+    "PluginRecord",
+    "PluginRegistry",
+    "PluginSource",
+    "PluginSpec",
+    "PluginStateError",
     "AntiHallucinationHooks",
     "ApprovalAborted",
     "ApprovalDecision",
@@ -288,6 +314,8 @@ __all__ = [
     "ContextManager",
     "CoreLoop",
     "ExecutionBudget",
+    "FamilyTree",
+    "FamilyTreeNode",
     "FilesystemSkillProvider",
     "FilesystemSpillStore",
     "FilteredToolsExecutor",
@@ -363,6 +391,7 @@ __all__ = [
     "ToolExecutor",
     "ToolExposure",
     "ToolRouter",
+    "TodoStore",
     "TraceRecorder",
     "TranscriptAppend",
     "TransportAdapter",
@@ -393,6 +422,7 @@ __all__ = [
     "export_trace",
     "extract_inline_tool_calls",
     "factor_for_model",
+    "family_tree",
     "fork_record",
     "last_world_state_snapshot",
     "lineage",
@@ -403,6 +433,7 @@ __all__ = [
     "load_recorded_requests",
     "load_transcript",
     "make_ask_user_tool",
+    "make_todo_write_tool",
     "matches_conditions",
     "mcp_invoker",
     "merge_patch",
@@ -436,6 +467,7 @@ __all__ = [
     "system_blocks_with_cache",
     "text_parts",
     "to_otlp_json",
+    "todo_write_tool_descriptor",
     "tool",
     "tool_search_descriptor",
     "upgrade_entry_dict",

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/ask_user.py

@@ -39,16 +39,37 @@ ASK_USER_SCHEMA: dict[str, Any] = {
         },
         "questions": {
             "type": "array",
+            "minItems": 1,
+            "maxItems": 4,
             "items": {
                 "type": "object",
                 "properties": {
                     "id": {"type": "string"},
                     "text": {"type": "string"},
+                    "header": {
+                        "type": "string",
+                        "maxLength": 12,
+                        "description": (
+                            "Short chip label shown above the question "
+                            "(<=12 chars). Optional; the host derives one "
+                            "from `text` when absent."
+                        ),
+                    },
                     "type": {
                         "type": "string",
                         "enum": ["select", "text", "password"],
                     },
-                    "options": {"type": "array", "items": {"type": "string"}},
+                    "options": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "minItems": 2,
+                        "maxItems": 4,
+                        "description": (
+                            "Choices for a select question (2-4). The host "
+                            "auto-appends an 'Other' free-text escape; do "
+                            "not list it yourself."
+                        ),
+                    },
                     "placeholder": {"type": "string"},
                     "multiSelect": {"type": "boolean"},
                 },
@@ -67,8 +88,40 @@ ASK_USER_SCHEMA: dict[str, Any] = {
 _QUESTION_ALIASES = {"id": "name", "text": "message", "options": "choices"}
 
 
+#: Claude Code ``AskUserQuestion`` parity bounds. The card renders a batched
+#: decision, not an interview — cap the question count so the model cannot
+#: bombard the user, and cap select options so it pre-categorizes instead of
+#: dumping a long list. The host auto-appends an "Other" free-text escape, so
+#: the model never lists it (the option space the model thought of is not the
+#: complete space).
+_MIN_QUESTIONS = 1
+_MAX_QUESTIONS = 4
+_MIN_OPTIONS = 2
+_MAX_OPTIONS = 4
+#: ``header`` is the short chip label shown above the question (CC parity).
+#: Optional on the wire; derived from ``text`` when absent.
+_MAX_HEADER_LEN = 12
+
+
+def _derive_header(text: str) -> str:
+    """Derive a <=12-char chip label from the question text when the model did
+    not supply ``header``. Strips trailing punctuation and truncates on a word
+    boundary so the chip stays readable."""
+    cleaned = text.strip().rstrip("?.!。")
+    if len(cleaned) <= _MAX_HEADER_LEN:
+        return cleaned
+    truncated = cleaned[:_MAX_HEADER_LEN]
+    # Prefer cutting on the last space so the chip does not end mid-word.
+    space = truncated.rfind(" ")
+    if space > 0:
+        truncated = truncated[:space]
+    return truncated
+
+
 def _normalize_questions(questions: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """Map known alias keys onto the canonical payload fields and require the
+    """Map known alias keys onto the canonical payload fields, enforce the
+    Claude Code ``AskUserQuestion`` bounds (1-4 questions, 2-4 options per
+    select, ``header`` <=12 chars, ``multiSelect`` explicit), and require the
     two fields the host card cannot render without (``id`` to key the answer,
     ``text`` to label the control). A violation raises ``ToolDispatchError`` —
     the router wraps it as the tool result, so the model sees exactly what to
@@ -77,6 +130,11 @@ def _normalize_questions(questions: list[dict[str, Any]]) -> list[dict[str, Any]
         raise ToolDispatchError(
             f"ask_user: questions must be an array, got {type(questions).__name__}"
         )
+    if not (_MIN_QUESTIONS <= len(questions) <= _MAX_QUESTIONS):
+        raise ToolDispatchError(
+            f"ask_user: questions must contain {_MIN_QUESTIONS}-{_MAX_QUESTIONS} "
+            f"items, got {len(questions)}. Batch a small decision, not an interview."
+        )
     normalized: list[dict[str, Any]] = []
     for index, question in enumerate(questions):
         if not isinstance(question, dict):
@@ -98,6 +156,47 @@ def _normalize_questions(questions: list[dict[str, Any]]) -> list[dict[str, Any]
                 f"ask_user: questions[{index}] is missing a non-empty string "
                 '"text" (the question label shown to the user).'
             )
+        # header: optional on the wire; validate length when present, derive
+        # from text when absent so the card always has a chip label.
+        header = q.get("header")
+        if header is None:
+            q["header"] = _derive_header(q["text"])
+        elif not isinstance(header, str) or not header:
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}].header must be a non-empty string."
+            )
+        elif len(header) > _MAX_HEADER_LEN:
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}].header is {len(header)} chars; "
+                f"the chip label must be <= {_MAX_HEADER_LEN}."
+            )
+        # multiSelect: CC requires the model to commit to single vs multi.
+        # Default to False when absent so existing single-select calls keep
+        # working, but stamp it so hosts always read an explicit boolean.
+        if "multiSelect" not in q or q["multiSelect"] is None:
+            q["multiSelect"] = False
+        elif not isinstance(q["multiSelect"], bool):
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}].multiSelect must be a boolean, "
+                f"got {type(q['multiSelect']).__name__}."
+            )
+        # options: only a select question carries choices; enforce the 2-4
+        # bound so the model pre-categorizes instead of dumping a long list.
+        qtype = q.get("type", "select")
+        options = q.get("options")
+        if qtype == "select":
+            if options is not None:
+                if not isinstance(options, list):
+                    raise ToolDispatchError(
+                        f"ask_user: questions[{index}].options must be an array, "
+                        f"got {type(options).__name__}."
+                    )
+                if not (_MIN_OPTIONS <= len(options) <= _MAX_OPTIONS):
+                    raise ToolDispatchError(
+                        f"ask_user: questions[{index}] has {len(options)} options; "
+                        f"a select question needs {_MIN_OPTIONS}-{_MAX_OPTIONS}. "
+                        "The host auto-appends an 'Other' escape — do not list it."
+                    )
         normalized.append(q)
     return normalized
 

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/branch.py

@@ -19,6 +19,8 @@ This module ties the existing primitives (``load_history_items`` +
   messages, not record seqs (regenerate = fork keeping the last user
   turn, dropping the assistant reply after it).
 - ``lineage`` — walk the seed-provenance chain upwards, cycle-guarded.
+- ``family_tree`` — the full family containing a record: lineage to the
+  root, then every descendant expanded from one storage-wide scan.
 
 Children discovery is deliberately host-side: ``StorageAdapter`` has no
 record enumeration, so stores that can list records implement
@@ -49,8 +51,11 @@ if TYPE_CHECKING:
 
 __all__ = [
     "BranchPoint",
+    "FamilyTree",
+    "FamilyTreeNode",
     "ForkResult",
     "branch_label",
+    "family_tree",
     "fork_record",
     "lineage",
     "resolve_fork_seq",
@@ -60,6 +65,11 @@ __all__ = [
 #: corruption, not a deep tree; fail loud past this depth.
 _MAX_LINEAGE_DEPTH = 32
 
+#: Bound on ``family_tree`` expansion — record enumeration is
+#: storage-wide, so a runaway family is cut off and reported
+#: (``FamilyTree.truncated``) rather than streamed unbounded to the host.
+_MAX_TREE_NODES = 500
+
 #: Reverse-scan page for ``resolve_fork_seq`` — the regen fork point is
 #: almost always in the tail page.
 _FORK_SCAN_PAGE = 128
@@ -95,6 +105,32 @@ class ForkResult:
     messages: list["LLMMessage"]
 
 
+@dataclass(frozen=True, slots=True)
+class FamilyTreeNode:
+    """One node in a full branch-family tree — a ``BranchPoint`` plus its
+    children, recursively. ``depth`` is 0 on the family root, +1 per fork
+    hop, matching the depths ``lineage`` assigns along the chain."""
+
+    record_id: str
+    source_record_id: str | None
+    source_until_seq: int | None
+    label: str
+    depth: int
+    children: tuple["FamilyTreeNode", ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class FamilyTree:
+    """The full branch family containing one record, expanded from the
+    family root. ``truncated`` reports that a safety bound (depth or node
+    count) cut the expansion — the returned tree is still valid, just
+    incomplete below the cut."""
+
+    root: FamilyTreeNode
+    node_count: int
+    truncated: bool
+
+
 def branch_label(messages: list["LLMMessage"], *, max_chars: int = 60) -> str:
     """Derive a branch summary from the forked prefix — deterministic, no
     LLM call: the last user message, whitespace-collapsed and truncated.
@@ -292,3 +328,92 @@ async def lineage(
         )
         for index, point in enumerate(chain)
     ]
+
+
+async def family_tree(
+    storage: "StorageAdapter",
+    record_id: str,
+    *,
+    max_depth: int = _MAX_LINEAGE_DEPTH,
+    max_nodes: int = _MAX_TREE_NODES,
+) -> FamilyTree:
+    """Full branch family containing ``record_id``, expanded from the root.
+
+    Walks seed provenance to the family root (``lineage``), then expands
+    every descendant from ONE storage-wide scan: parent edges live in each
+    record's first-entry seed, so reading that entry per enumerated record
+    (``list_history_records``) yields the children of every family member
+    at once — the same discovery ``agent.session.branches`` does for one
+    level, applied recursively without re-scanning per node.
+
+    Raises ``KeyError`` when the record has no entries (an empty record is
+    indistinguishable from a missing one — records are created by append)
+    and ``ValueError`` on lineage corruption (cycle / over-deep chain),
+    matching ``fork_record`` / ``lineage``. Expansion is bounded twice:
+    ``max_depth`` cuts descendants below that depth from the root (the
+    default matches the lineage corruption bound, so by default only
+    corrupt families are cut) and ``max_nodes`` caps the total — either
+    cut is reported via ``FamilyTree.truncated`` instead of streaming
+    unbounded data. ``max_depth`` does NOT relax the lineage walk itself:
+    a queried record whose own chain exceeds the corruption bound still
+    raises ``ValueError``.
+    """
+
+    if not await storage.list_history(record_id, limit=1):
+        raise KeyError(f"record not found: {record_id}")
+    chain = await lineage(storage, record_id)
+    root_point = chain[0]
+
+    children_of: dict[str, list[BranchPoint]] = {}
+    for candidate in await storage.list_history_records():
+        if candidate == root_point.record_id:
+            continue
+        first = await storage.list_history(candidate, limit=1)
+        if not first:
+            continue
+        entry = entry_from_dict(first[0])
+        if isinstance(entry, HistorySeed) and entry.source_record_id is not None:
+            children_of.setdefault(entry.source_record_id, []).append(
+                BranchPoint(
+                    record_id=candidate,
+                    source_record_id=entry.source_record_id,
+                    source_until_seq=entry.source_until_seq,
+                    label=branch_label(list(entry.messages)),
+                )
+            )
+
+    total = 0
+    truncated = False
+
+    def build(point: BranchPoint, depth: int) -> FamilyTreeNode:
+        nonlocal total, truncated
+        total += 1
+        children: list[FamilyTreeNode] = []
+        if depth >= max_depth:
+            if children_of.get(point.record_id):
+                truncated = True
+        else:
+            for child in children_of.get(point.record_id, []):
+                if total >= max_nodes:
+                    truncated = True
+                    break
+                children.append(build(child, depth + 1))
+        return FamilyTreeNode(
+            record_id=point.record_id,
+            source_record_id=point.source_record_id,
+            source_until_seq=point.source_until_seq,
+            label=point.label,
+            depth=depth,
+            children=tuple(children),
+        )
+
+    root = build(
+        BranchPoint(
+            record_id=root_point.record_id,
+            source_record_id=root_point.source_record_id,
+            source_until_seq=root_point.source_until_seq,
+            label=root_point.label,
+        ),
+        0,
+    )
+    return FamilyTree(root=root, node_count=total, truncated=truncated)

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/compaction.py

@@ -38,8 +38,10 @@ Three trigger paths share the fold/summarize machinery:
   prompt-cache prefix, so the interval trades cache hits for a bounded
   transcript;
 - **manual** (``compact_now``) — the host-command path (CC ``/compact``
-  parity): fold + summarize on demand, bypassing threshold, hysteresis, and
-  the circuit breaker.
+  parity): the host calls the sidecar's ``agent.chat.compact`` RPC, which
+  sets ``CoreLoop.request_compact()``; the loop runs ``compact_now`` at the
+  next pre_step boundary, folding + summarizing on demand, bypassing
+  threshold, hysteresis, and the circuit breaker.
 
 Two safety rails share the machinery:
 

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/harness.py

@@ -128,12 +128,27 @@ class OrchestrationStrategy(Protocol):
 
 
 class _PreStepOnly(NoopHooks):
-    def __init__(self, inner: LoopHooks) -> None:
+    """Project a hooks impl onto the pre_step slice.
+
+    ``forward`` names optional off-protocol capabilities (probed with
+    ``getattr``, e.g. ``compact_now``) that must stay reachable through the
+    projection — without it the wrapper would silently sever the sidecar's
+    ``agent.chat.compact`` path, which probes the assembled chain for the
+    one hook implementing manual compaction.
+    """
+
+    def __init__(self, inner: LoopHooks, *, forward: tuple[str, ...] = ()) -> None:
         self._inner = inner
+        self._forward = forward
 
     async def pre_step(self, transcript: Any, ctx: Any) -> Any:
         return await self._inner.pre_step(transcript, ctx)
 
+    def __getattr__(self, name: str) -> Any:
+        if name in self._forward:
+            return getattr(self._inner, name)
+        raise AttributeError(name)
+
 
 class _OnRequestErrorOnly(NoopHooks):
     def __init__(self, inner: LoopHooks) -> None:
@@ -188,6 +203,12 @@ class PressureCompaction:
     keep_last_tool_results: int = 2
     fold_excerpt_chars: int | None = None
     model: str | None = None
+    # Proactive micro-compaction (CC time-based microcompact parity): fold old
+    # tool results every N rounds regardless of pressure. 0 (default) is off —
+    # each fold invalidates the provider prompt-cache prefix, so the interval
+    # trades cache hits for a bounded transcript. R16 found compaction does not
+    # move the eval score, so this stays opt-in capability, not a default.
+    micro_compact_interval_rounds: int = 0
     name: str = "pressure_compaction"
     assumes: str = (
         "long trajectories exceed the window; older detail is expendable "
@@ -209,8 +230,10 @@ class PressureCompaction:
                 keep_last_tool_results=self.keep_last_tool_results,
                 summarizer=provider,
                 model=self.model,
+                micro_compact_interval_rounds=self.micro_compact_interval_rounds,
                 **extra,
-            )
+            ),
+            forward=("compact_now",),
         )
 
 
@@ -805,8 +828,16 @@ class SingleAgent:
 
 
 @dataclass(frozen=True, slots=True)
-class SubAgentDelegation:
-    """The existing AgentPool six-tool delegation (OrchestrationExecutor)."""
+class PoolOrchestration:
+    """The six-tool orchestration family over AgentPool (OrchestrationExecutor).
+
+    This is the advanced, model-driven orchestration arm: the parent gets
+    ``agent_spawn``/``agent_send``/``agent_wait``/``agent_close``/
+    ``agent_list``/``agent_interrupt`` and drives parallel children
+    explicitly. (The single-tool ``delegate_subagent`` seam —
+    ``SubagentExecutor`` — is the default multi-agent surface on the
+    sidecar chat path; both run on the same AgentPool engine.)
+    """
 
     name: str = "subagent"
     assumes: str = (
@@ -852,5 +883,8 @@ STRATEGY_REGISTRY: dict[str, dict[str, type]] = {
         "progressive": ProgressiveDisclosure,
     },
     "memory": {"stateless": Stateless, "filesystem": FilesystemState},
-    "orchestration": {"single": SingleAgent, "subagent": SubAgentDelegation},
+    # The "subagent" key names the eval arm (harness specs predate the
+    # delegate-on-pool unification); the implementation is the six-tool
+    # pool orchestration family.
+    "orchestration": {"single": SingleAgent, "subagent": PoolOrchestration},
 }

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/hooks.py

@@ -309,6 +309,10 @@ class ChainHooks:
       so a trailing delivery gate still forces writes when an earlier
       validator would only ask for a no-tools summary.
     - ``wrap_up_may_drop_tools``: False if any hook forbids dropping tools.
+    - ``compact_now``: optional capability (not part of the ``LoopHooks``
+      protocol), probed with ``getattr`` like ``on_stream_chunk`` —
+      delegated to the first hook that implements it (CompactionHooks);
+      a chain without one returns a no-op proceed.
 
     This is how a product stacks e.g. compaction + spill + retry without the
     loop knowing about any of them.
@@ -363,6 +367,28 @@ class ChainHooks:
             append_action=append_action,
         )
 
+    async def compact_now(
+        self, transcript: list[LLMMessage], ctx: LoopContext
+    ) -> PreStepAction:
+        """Manual compaction (CC ``/compact`` parity): delegate to the first
+        hook in the chain that implements ``compact_now`` (CompactionHooks).
+
+        ``compact_now`` is an optional capability, not a ``LoopHooks``
+        protocol method, so membership is probed with ``getattr`` — the same
+        pattern the loop uses for ``on_stream_chunk``. ``NoopHooks`` defines
+        no ``compact_now``, so the probe skips it (and any other hook that
+        only has the protocol surface) without a special case. A chain with
+        no compaction hook returns a no-op proceed: a manual compact request
+        must never fail the turn.
+        """
+        for hook in self._hooks:
+            callback = getattr(hook, "compact_now", None)
+            if callable(callback):
+                return await callback(transcript, ctx)
+        return PreStepAction(
+            kind="proceed", reason="compact: no compaction hook in chain"
+        )
+
     async def post_tool_result(
         self, result: ToolResult, call: ToolCall, ctx: LoopContext
     ) -> ToolResult:

{steerable_agent_runtime-0.6.2 → steerable_agent_runtime-0.6.4}/src/steerable_agent_runtime/llm/__init__.py

@@ -159,9 +159,18 @@ from .errors import (
     is_retryable,
 )
 from .openai_compat import OpenAICompatProvider
+from .presets import (
+    PROVIDER_PRESETS,
+    PresetEntry,
+    ProviderPreset,
+    describe_provider_presets,
+    preset_for,
+    register_provider_preset,
+)
 
 __all__ = [
     "PROVIDER_COMPAT_HOSTS",
+    "PROVIDER_PRESETS",
     "RETRYABLE_KINDS",
     "AnthropicProvider",
     "ContentPart",
@@ -174,7 +183,10 @@ __all__ = [
     "LLMStreamChunk",
     "LLMUsage",
     "OpenAICompatFlags",
+    "PresetEntry",
+    "ProviderPreset",
     "describe_compat_flags",
+    "describe_provider_presets",
     "OpenAICompatProvider",
     "TextPart",
     "classify_error",
@@ -182,5 +194,7 @@ __all__ = [
     "compat_for_base_url",
     "content_text",
     "is_retryable",
+    "preset_for",
+    "register_provider_preset",
     "text_parts",
 ]