steerable-agent-runtime 0.3.0__tar.gz → 0.4.0__tar.gz

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.3.0
+Version: 0.4.0
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -13,14 +13,14 @@ Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.110; extra == "fastapi"
 Requires-Dist: starlette>=0.37; extra == "fastapi"
 Provides-Extra: openai
-Requires-Dist: httpx>=0.27; extra == "openai"
+Requires-Dist: httpx[socks]>=0.27; extra == "openai"
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.40; extra == "anthropic"
 Provides-Extra: all
 Requires-Dist: sqlalchemy>=2.0; extra == "all"
 Requires-Dist: fastapi>=0.110; extra == "all"
 Requires-Dist: starlette>=0.37; extra == "all"
-Requires-Dist: httpx>=0.27; extra == "all"
+Requires-Dist: httpx[socks]>=0.27; extra == "all"
 Requires-Dist: anthropic>=0.40; extra == "all"
 
 # steerable-agent-runtime

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.3.0"
+version = "0.4.0"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -18,13 +18,17 @@ dependencies = [
 [project.optional-dependencies]
 sqlalchemy = ["sqlalchemy>=2.0"]
 fastapi = ["fastapi>=0.110", "starlette>=0.37"]
-openai = ["httpx>=0.27"]
+# The `socks` extra is not optional in practice: httpx builds a transport for
+# every proxy the environment declares while the client is constructed, so a
+# host exporting `all_proxy=socks5://…` — the common shell proxy snippet — makes
+# construction raise without it, failing provider calls that never reach a URL.
+openai = ["httpx[socks]>=0.27"]
 anthropic = ["anthropic>=0.40"]
 all = [
   "sqlalchemy>=2.0",
   "fastapi>=0.110",
   "starlette>=0.37",
-  "httpx>=0.27",
+  "httpx[socks]>=0.27",
   "anthropic>=0.40",
 ]
 
@@ -38,6 +42,12 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+# default.harness.yaml/.json ship inside the wheel: the sidecar resolves
+# the spec relative to the installed package (Harbor trial containers
+# pip-install the wheels, so a repo-relative path would not exist there).
+[tool.setuptools.package-data]
+steerable_agent_runtime = ["*.yaml", "*.json"]
+
 [tool.uv.sources]
 steerable-agent-protocol = { workspace = true }
 steerable-agent-harness = { workspace = true }

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/src/steerable_agent_runtime/__init__.py

@@ -22,6 +22,13 @@ from .approval import (
     JsonApprovalStore,
     SessionApprovalCache,
 )
+from .approval_policy import (
+    ApprovalPolicy,
+    ApprovalRule,
+    JsonApprovalPolicyStore,
+    PolicyApprover,
+    rule_from_amendment,
+)
 from .branch import (
     BranchPoint,
     ForkResult,
@@ -59,10 +66,13 @@ from .history import (
     HistoryStore,
     RecordEntry,
     RecordFormatError,
+    SystemPromptFragment,
     entry_from_dict,
+    render_fragment_capped,
     entry_to_dict,
     message_from_dict,
     message_to_dict,
+    upgrade_entry_dict,
 )
 from .hooks import (
     ChainHooks,
@@ -150,7 +160,12 @@ from .replay import (
     build_step_decision_event,
     reduce_execution_state,
 )
-from .resume import load_history_transcript, load_transcript, project_transcript
+from .resume import (
+    close_dangling_tool_calls,
+    load_history_transcript,
+    load_transcript,
+    project_transcript,
+)
 from .retry import RetryHooks
 from .sandboxed import (
     DEFAULT_SHELL_TOOLS,
@@ -221,7 +236,9 @@ __all__ = [
     "ApprovalAborted",
     "ApprovalDecision",
     "ApprovalExecutor",
+    "ApprovalPolicy",
     "ApprovalRequest",
+    "ApprovalRule",
     "ApprovalStore",
     "Approver",
     "AutoApprover",
@@ -255,6 +272,7 @@ __all__ = [
     "InMemoryApprovalStore",
     "InMemoryRequestSink",
     "InMemorySpillStore",
+    "JsonApprovalPolicyStore",
     "JsonApprovalStore",
     "JsonlRequestSink",
     "LLMMessage",
@@ -277,6 +295,7 @@ __all__ = [
     "OrchestrationBudgetExceeded",
     "OrchestrationConfig",
     "OrchestrationExecutor",
+    "PolicyApprover",
     "PolicyDeniedError",
     "PreStepAction",
     "PrivacyMode",
@@ -296,6 +315,7 @@ __all__ = [
     "SessionApprovalCache",
     "SkillConfig",
     "SkillDefinition",
+    "SystemPromptFragment",
     "SkillExecutor",
     "SkillHooks",
     "SkillProvider",
@@ -329,6 +349,7 @@ __all__ = [
     "branch_label",
     "build_step_decision_event",
     "clamp_reasoning_effort",
+    "close_dangling_tool_calls",
     "detect_claimed_execution",
     "detect_deferred_execution",
     "detect_deferred_execution_eager",
@@ -367,9 +388,11 @@ __all__ = [
     "register_model_info",
     "register_model_price",
     "register_tool_search",
+    "render_fragment_capped",
     "render_skill_catalog",
     "resolve_fork_seq",
     "resolve_model_info",
+    "rule_from_amendment",
     "select_catalog",
     "select_skills",
     "should_run_grounding_judge",
@@ -381,6 +404,7 @@ __all__ = [
     "to_otlp_json",
     "tool",
     "tool_search_descriptor",
+    "upgrade_entry_dict",
 ]
 
 __version__ = "0.1.0"

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/src/steerable_agent_runtime/approval.py

@@ -28,6 +28,7 @@ import json
 import logging
 import os
 import tempfile
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
@@ -101,6 +102,11 @@ class ApprovalRequest:
     calls sharing a category share a cached decision. It defaults to the tool
     name; hosts with parameterized risk (e.g. a shell tool) can pass a
     resolver that categorizes by command class instead.
+
+    ``call_id`` is the originating tool call's id, for approver channels that
+    correlate the prompt with the tool call in the UI (ACP
+    ``session/request_permission`` requires it). Empty for synthesized
+    requests.
     """
 
     tool_name: str
@@ -108,6 +114,7 @@ class ApprovalRequest:
     mode: ToolMode
     category: str
     round_index: int = 0
+    call_id: str = ""
 
 
 @runtime_checkable
@@ -238,6 +245,7 @@ def _default_resolver(call: ToolCall, ctx: LoopContext) -> ApprovalRequest:
         mode=decide_tool_mode(call.name),
         category=call.name,
         round_index=ctx.round_index,
+        call_id=call.id,
     )
 
 
@@ -282,10 +290,28 @@ class ApprovalExecutor:
     async def execute(self, call: ToolCall, ctx: LoopContext) -> ToolResult:
         request = self._resolve(call, ctx)
         decision = self._stored_decision(request)
+        # W2.7.2: when the decision required asking (cache miss), record the
+        # wait on the result so the trace can show approval latency as its
+        # own span. Cache hits carry no marker — no wait happened.
+        waited_ms: int | None = None
         if decision is None:
+            ask_started = time.monotonic()
             decision = await self._ask(request)
+            waited_ms = int((time.monotonic() - ask_started) * 1000)
             self._persist(request, decision)
 
+        approval_marker = (
+            {
+                "_approval": {
+                    "kind": decision.kind,
+                    "category": request.category,
+                    "waitMs": waited_ms,
+                }
+            }
+            if waited_ms is not None
+            else None
+        )
+
         if decision.kind == "abort":
             raise ApprovalAborted(
                 decision.reason or f"tool call '{request.tool_name}' aborted by approval"
@@ -300,6 +326,7 @@ class ApprovalExecutor:
                     "approval": decision.kind,
                     "category": request.category,
                     "reason": reason,
+                    **(approval_marker or {}),
                     "message": (
                         f"Tool call '{request.tool_name}' was denied "
                         f"({decision.kind}): {reason}"
@@ -307,7 +334,12 @@ class ApprovalExecutor:
                 },
             )
         ctx.consent_granted = True
-        return await self._inner.execute(call, ctx)
+        result = await self._inner.execute(call, ctx)
+        if approval_marker is not None:
+            result = result.model_copy(
+                update={"data": {**(result.data or {}), **approval_marker}}
+            )
+        return result
 
     def _stored_decision(self, request: ApprovalRequest) -> ApprovalDecision | None:
         """Durable wins over session: it is the stronger commitment."""

steerable_agent_runtime-0.4.0/src/steerable_agent_runtime/approval_policy.py

@@ -0,0 +1,243 @@
+"""Approval policy rules: pattern-matched auto-decisions orthogonal to the
+8-variant lattice (W2.4).
+
+Reference: codex execpolicy — durable rules mapping command patterns to
+allow/deny verdicts, consulted before the interactive prompt. The lattice's
+category caches answer "this KIND of call, decided before"; policy rules
+answer "calls matching this PATTERN, decided in advance" — a shell category
+covers every command, while a rule can carve out ``git status`` precisely.
+
+Resolution order inside ``ApprovalExecutor`` is unchanged (durable store →
+session cache → approver); ``PolicyApprover`` sits at the approver seam, so
+rules are consulted after the lattice's own caches and before the host
+prompt. Rule hits return request-scoped variants (``allow_once`` /
+``deny_once``): the rule itself is the durable grant, so the lattice must
+not double-record it into a category cache.
+
+Amendments (W2.4.2): a host approval reply may carry an ``amendment``
+payload — "allow, and keep allowing commands like this". The sidecar turns
+it into a rule in the durable policy store; the user is not re-asked.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shlex
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from .approval import ApprovalDecision, ApprovalRequest, Approver
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "ApprovalPolicy",
+    "ApprovalRule",
+    "JsonApprovalPolicyStore",
+    "PolicyApprover",
+    "rule_from_amendment",
+]
+
+RuleDecision = Literal["allow", "deny"]
+_RULE_DECISIONS = frozenset({"allow", "deny"})
+
+#: Conventional arguments key holding the shell command string (mirrors the
+#: sidecar's default ``commandArg``).
+_DEFAULT_COMMAND_ARG = "command"
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalRule:
+    """One pattern → verdict rule.
+
+    ``tool`` is an exact tool name. ``command_prefix`` is an argv token
+    prefix matched against the call's command string (shlex-split); empty
+    means "every call of this tool". A rule with a prefix never matches a
+    call whose command is missing or unparseable — fail closed, the inner
+    approver decides instead.
+    """
+
+    tool: str
+    decision: RuleDecision
+    command_prefix: tuple[str, ...] = ()
+    command_arg: str = _DEFAULT_COMMAND_ARG
+
+    def __post_init__(self) -> None:
+        if not self.tool:
+            raise ValueError("rule tool must be non-empty")
+        if self.decision not in _RULE_DECISIONS:
+            raise ValueError(f"rule decision must be allow|deny, got {self.decision!r}")
+
+    def matches(self, request: ApprovalRequest) -> bool:
+        if request.tool_name != self.tool:
+            return False
+        if not self.command_prefix:
+            return True
+        raw = request.arguments.get(self.command_arg)
+        if not isinstance(raw, str) or not raw.strip():
+            return False
+        try:
+            argv = shlex.split(raw)
+        except ValueError:  # unbalanced quotes etc. — no match, fail closed
+            return False
+        prefix = list(self.command_prefix)
+        return argv[: len(prefix)] == prefix
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tool": self.tool,
+            "decision": self.decision,
+            "commandPrefix": list(self.command_prefix),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ApprovalRule:
+        tool = data.get("tool")
+        decision = data.get("decision")
+        prefix = data.get("commandPrefix") or []
+        if not isinstance(tool, str) or not isinstance(prefix, list):
+            raise ValueError(f"invalid rule entry: {data!r}")
+        return cls(
+            tool=tool,
+            decision=decision,  # validated in __post_init__
+            command_prefix=tuple(str(token) for token in prefix),
+        )
+
+
+@dataclass(slots=True)
+class ApprovalPolicy:
+    """Ordered rule list; the first matching rule decides."""
+
+    rules: list[ApprovalRule] = field(default_factory=list)
+
+    def decide(self, request: ApprovalRequest) -> ApprovalDecision | None:
+        for rule in self.rules:
+            if rule.matches(request):
+                pattern = (
+                    " ".join(rule.command_prefix) if rule.command_prefix else "*"
+                )
+                reason = f"policy rule: {rule.tool} {pattern} → {rule.decision}"
+                return ApprovalDecision(
+                    "allow_once" if rule.decision == "allow" else "deny_once",
+                    reason,
+                )
+        return None
+
+    def add(self, rule: ApprovalRule) -> None:
+        """Append a rule. An identical existing rule is a no-op (amendments
+        are idempotent — re-approving the same pattern must not grow the
+        file)."""
+        if rule not in self.rules:
+            self.rules.append(rule)
+
+
+class JsonApprovalPolicyStore:
+    """File-backed durable policy: one JSON object ``{"version", "rules"}``.
+
+    Writes are atomic (tmp file + rename), mirroring ``JsonApprovalStore`` —
+    a crash mid-write must not corrupt the policy every future run loads.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def load(self) -> ApprovalPolicy:
+        if not self._path.exists():
+            return ApprovalPolicy()
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            rules = [ApprovalRule.from_dict(r) for r in data.get("rules") or []]
+        except (ValueError, KeyError, AttributeError) as exc:
+            # A corrupt policy fails closed: no rules, so every call falls
+            # through to the interactive approver — never an auto-allow.
+            logger.warning("ignoring unreadable approval policy %s: %s", self._path, exc)
+            return ApprovalPolicy()
+        return ApprovalPolicy(rules)
+
+    def save(self, policy: ApprovalPolicy) -> None:
+        payload = {
+            "version": 1,
+            "rules": [rule.to_dict() for rule in policy.rules],
+        }
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(
+            dir=str(self._path.parent), prefix=self._path.name, suffix=".tmp"
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(payload, handle, ensure_ascii=False, indent=2)
+                handle.write("\n")
+            os.replace(tmp, self._path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+
+    def add_rule(self, rule: ApprovalRule) -> None:
+        """Load → add → save. The policy is small (user-authored rules), so
+        read-modify-write per amendment is fine and keeps the file the single
+        source of truth across processes."""
+        policy = self.load()
+        policy.add(rule)
+        self.save(policy)
+
+
+class PolicyApprover:
+    """``Approver`` decorator consulting the policy before the inner approver.
+
+    A rule hit short-circuits (no host round-trip); a miss delegates. The
+    inner approver is typically ``HostApprover`` (interactive) or
+    ``AutoApprover`` (headless) — the policy composes with either.
+    """
+
+    def __init__(self, inner: Approver, policy: ApprovalPolicy) -> None:
+        self._inner = inner
+        self._policy = policy
+
+    async def approve(self, request: ApprovalRequest) -> ApprovalDecision:
+        decision = self._policy.decide(request)
+        if decision is not None:
+            return decision
+        return await self._inner.approve(request)
+
+
+def rule_from_amendment(
+    request: ApprovalRequest, amendment: Any
+) -> ApprovalRule | None:
+    """Decode a host reply's ``amendment`` payload into a rule (W2.4.2).
+
+    Wire shape::
+
+        {"decision": "allow" | "deny", "commandPrefix": ["git", "status"]?}
+
+    The rule's tool is the approved call's tool — an amendment can only
+    widen/narrow the pattern, never retarget another tool. Invalid payloads
+    return ``None`` (the decision itself still stands; only the persistence
+    is dropped), never raise into the approval path.
+    """
+    if not isinstance(amendment, dict):
+        return None
+    decision = amendment.get("decision")
+    if decision not in _RULE_DECISIONS:
+        logger.warning("ignoring approval amendment with bad decision: %r", amendment)
+        return None
+    prefix_raw = amendment.get("commandPrefix") or []
+    if not isinstance(prefix_raw, list) or not all(
+        isinstance(t, str) for t in prefix_raw
+    ):
+        logger.warning("ignoring approval amendment with bad commandPrefix: %r", amendment)
+        return None
+    try:
+        return ApprovalRule(
+            tool=request.tool_name,
+            decision=decision,
+            command_prefix=tuple(prefix_raw),
+        )
+    except ValueError:
+        return None

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/src/steerable_agent_runtime/compaction.py

@@ -47,8 +47,15 @@ _FOLD_EXCERPT_CHARS = 160
 __all__ = ["CompactionHooks", "estimate_tokens"]
 
 
-def _fold_content(content: str | None) -> str:
-    excerpt = " ".join((content or "").split())[:_FOLD_EXCERPT_CHARS]
+def _fold_content(content: str | None, excerpt_chars: int = _FOLD_EXCERPT_CHARS) -> str:
+    text = content or ""
+    if len(text) <= excerpt_chars:
+        excerpt = text
+    else:
+        head = max(excerpt_chars // 5, 1)
+        tail = excerpt_chars - head
+        omitted = len(text) - excerpt_chars
+        excerpt = f"{text[:head]}\n...[{omitted} chars truncated]...\n{text[-tail:]}"
     if excerpt:
         return f"{_FOLDED_TOOL_MARKER} excerpt: {excerpt}"
     return _FOLDED_TOOL_MARKER
@@ -67,6 +74,7 @@ class CompactionHooks(NoopHooks):
         summarizer: LLMProvider | None = None,
         model: str | None = None,
         recompact_margin_ratio: float = 0.1,
+        fold_excerpt_chars: int = _FOLD_EXCERPT_CHARS,
     ) -> None:
         if not 0 < threshold_ratio <= 1:
             raise ValueError("threshold_ratio must be in (0, 1]")
@@ -76,6 +84,7 @@ class CompactionHooks(NoopHooks):
         self._threshold = threshold_ratio
         self._keep_last = keep_last_messages
         self._keep_last_tools = keep_last_tool_results
+        self._fold_excerpt_chars = fold_excerpt_chars
         self._summarizer = summarizer
         #: Model name used for calibrated token estimates (see tokens.py).
         self._model = model
@@ -219,7 +228,7 @@ class CompactionHooks(NoopHooks):
         return [
             LLMMessage.text_of(
                 "tool",
-                _fold_content(m.content_text),
+                _fold_content(m.content_text, self._fold_excerpt_chars),
                 name=m.name,
                 tool_call_id=m.tool_call_id,
             )
@@ -266,12 +275,23 @@ class CompactionHooks(NoopHooks):
             # discarded: never write it into the prompt cache (pi's
             # retention=none rule). The kwarg is consumed by
             # CacheControlProvider; providers without it ignore the key.
-            message, _usage = await self._summarizer.complete(
-                prompt, cache_retention="none"
-            )
-            return message.content_text
-        # No summarizer configured: deterministic fallback keeps role + a short
-        # excerpt per message so the thread of actions survives.
+            try:
+                message, _usage = await self._summarizer.complete(
+                    prompt, cache_retention="none"
+                )
+            except Exception:
+                # Transport/protocol errors here run outside the stream
+                # retry loop. Falling back keeps wrap-up running so Harbor
+                # still scores files instead of a NonZeroAgentExit.
+                return self._excerpt_summary(middle)
+            text = (message.content_text or "").strip()
+            if text:
+                return text
+        return self._excerpt_summary(middle)
+
+    def _excerpt_summary(self, middle: list[LLMMessage]) -> str:
+        # No summarizer, empty model reply, or a failed complete(): keep
+        # role + a short excerpt per message so the thread of actions survives.
         lines = []
         for m in middle:
             excerpt = m.content_text.replace("\n", " ")[:200]

steerable_agent_runtime-0.4.0/src/steerable_agent_runtime/default.harness.json

@@ -0,0 +1,30 @@
+{
+  "context": [
+    {
+      "impl": "pressure_compaction"
+    },
+    {
+      "impl": "spill"
+    }
+  ],
+  "retry": [
+    {
+      "impl": "informed_backtrack"
+    },
+    {
+      "impl": "simple",
+      "params": {
+        "max_attempts": 3
+      }
+    }
+  ],
+  "validator": "null",
+  "tools": "full",
+  "memory": "stateless",
+  "orchestration": "single",
+  "loop": {
+    "max_rounds": 80,
+    "max_tool_errors": 16,
+    "tool_dedup": false
+  }
+}

steerable_agent_runtime-0.4.0/src/steerable_agent_runtime/default.harness.yaml

@@ -0,0 +1,28 @@
+# The framework's default harness (W1.2.4): a declaration of what the
+# sidecar chat path has always assembled by hand —
+#   ChainHooks(CompactionHooks, SpillHooks, RetryHooks) + InMemoryStorage
+#   + full tool surface + no delegation.
+# `max_context_tokens` is intentionally absent: the host resolves it from
+# the model catalog at assembly time (runtime_params), per-model.
+context:
+  - impl: pressure_compaction
+  - impl: spill
+retry:
+  # Order matters: overflow backtrack first (it declines non-overflow
+  # errors), then taxonomy-routed backoff. Mirrors ChainHooks ordering.
+  - impl: informed_backtrack
+  # max_attempts 3 pins the production default (RetryHooks()); the strategy
+  # default of 4 would silently diverge the spec from the sidecar chat path.
+  - impl: simple
+    params: {max_attempts: 3}
+# Quoted: bare `null` is YAML's null literal, not the implementation name.
+validator: "null"
+tools: full
+memory: stateless
+orchestration: single
+# Loop limits the harness pins (W3.4.2.4): entrypoints read these instead of
+# hardcoding knobs. Absent fields fall back to the entrypoint's baseline.
+loop:
+  max_rounds: 80
+  max_tool_errors: 16
+  tool_dedup: false

{steerable_agent_runtime-0.3.0 → steerable_agent_runtime-0.4.0}/src/steerable_agent_runtime/errors.py

@@ -18,6 +18,17 @@ class StorageError(RuntimeError):
     """Persistence layer failure."""
 
 
+class StoreAlreadyOwnedError(StorageError):
+    """Another process already holds the write lease for this database."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(
+            f"store already owned: {path} "
+            "(another process has this sqlite database open for write)"
+        )
+        self.path = path
+
+
 class ToolDispatchError(RuntimeError):
     """Tool router could not satisfy a ToolCall."""