steerable-agent-runtime 0.6.74__tar.gz → 0.7.0__tar.gz

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.74
+Version: 0.7.0
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 License: Apache-2.0
 Requires-Python: >=3.10

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.6.74"
+version = "0.7.0"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 license = { text = "Apache-2.0" }
 readme = "README.md"

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/src/steerable_agent_runtime/approval.py

@@ -32,7 +32,7 @@ import tempfile
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, runtime_checkable
 
 from steerable_agent_harness.policy import ToolMode, decide_tool_mode
 from steerable_agent_protocol.generated import ToolCall, ToolResult
@@ -55,6 +55,7 @@ __all__ = [
     "Approver",
     "AutoApprover",
     "WorkspaceAutoApprover",
+    "declared_resolver",
     "InMemoryApprovalStore",
     "JsonApprovalStore",
     "SessionApprovalCache",
@@ -140,6 +141,33 @@ _PATH_ARG_TOOLS = {
 }
 
 
+def _front_load_markers(
+    data: dict[str, Any] | None, approval_marker: dict[str, Any] | None
+) -> dict[str, Any]:
+    """Put sandbox and approval markers ahead of the tool payload.
+
+    A published loop keeps only the first 300 characters of the result
+    preview and, for a sibling that finished before a terminal tool in
+    the same batch, does not copy those markers onto the event. They
+    have to be readable from that prefix.
+    """
+    body = dict(data or {})
+    sandbox = body.pop("_sandbox", None)
+    approval = (
+        approval_marker.get("_approval")
+        if approval_marker is not None
+        else body.get("_approval")
+    )
+    body.pop("_approval", None)
+    ordered: dict[str, Any] = {}
+    if isinstance(sandbox, dict):
+        ordered["_sandbox"] = sandbox
+    if isinstance(approval, dict):
+        ordered["_approval"] = approval
+    ordered.update(body)
+    return ordered
+
+
 def declared_target_paths(request: ApprovalRequest) -> list[str] | None:
     """Filesystem targets of a path-scoped tool, or None when the call is not one.
 
@@ -169,31 +197,53 @@ def declared_target_paths(request: ApprovalRequest) -> list[str] | None:
     return [raw.strip()]
 
 
-def path_inside_writable_roots(raw: str, roots: list[str]) -> bool:
+def path_inside_writable_roots(
+    raw: str,
+    roots: list[str],
+    *,
+    pathmod: Any | None = None,
+    base: str | None = None,
+) -> bool:
     """True when ``raw`` is the configured directory or one of its subdirectories.
 
-    Relative paths are project-relative. A ``..`` segment can leave the
-    project, so those still go to the prompt. Absolute paths must sit under
-    one of ``roots``.
+    Relative paths are project-relative. When ``base`` is the project home,
+    they are joined to that directory and then compared like absolute paths,
+    so a symlink inside the project that points outside is not inside.
+    Without ``base``, a relative path is inside unless it starts with ``..``.
+    Absolute paths must sit under one of ``roots`` after symbolic links are
+    resolved, so ``/tmp`` and ``/private/tmp`` are the same directory.
+    Windows compares paths without letter case, so
+    ``c:\\work\\repo\\a.txt`` is inside ``C:\\Work\\Repo``. ``pathmod`` selects
+    the path implementation; production uses ``os.path``.
     """
-    expanded = os.path.expanduser(raw.strip())
-    if not os.path.isabs(expanded):
-        normalized = os.path.normpath(expanded)
-        return normalized != ".." and not normalized.startswith(".." + os.sep)
-    target = os.path.abspath(expanded)
+    paths = os.path if pathmod is None else pathmod
+    expanded = paths.expanduser(raw.strip())
+    if not paths.isabs(expanded):
+        if isinstance(base, str) and base.strip():
+            expanded = paths.normpath(paths.join(paths.expanduser(base.strip()), expanded))
+        else:
+            normalized = paths.normpath(expanded)
+            return normalized != ".." and not normalized.startswith(".." + paths.sep)
+    target = paths.realpath(expanded)
     for root in roots:
         if not isinstance(root, str) or not root.strip():
             continue
-        root_abs = os.path.abspath(os.path.expanduser(root.strip()))
+        root_abs = paths.realpath(paths.expanduser(root.strip()))
         try:
-            if os.path.commonpath([target, root_abs]) == root_abs:
-                return True
+            common = paths.commonpath([target, root_abs])
         except ValueError:
             continue
+        if paths.normcase(common) == paths.normcase(root_abs):
+            return True
     return False
 
 
-def shell_stays_in_workspace(request: ApprovalRequest, roots: list[str]) -> bool:
+def shell_stays_in_workspace(
+    request: ApprovalRequest,
+    roots: list[str],
+    *,
+    base: str | None = None,
+) -> bool:
     """True when a shell call's working directory is inside a writable root.
 
     The command text is not parsed. Confinement is the OS sandbox's job:
@@ -208,7 +258,7 @@ def shell_stays_in_workspace(request: ApprovalRequest, roots: list[str]) -> bool
         return True
     if not isinstance(cwd, str) or not cwd.strip():
         return True
-    return path_inside_writable_roots(cwd, roots)
+    return path_inside_writable_roots(cwd, roots, base=base)
 
 
 class WorkspaceAutoApprover:
@@ -216,13 +266,13 @@ class WorkspaceAutoApprover:
 
     Embedders may also name host-owned control tools whose effects are limited
     to internal session state and therefore need no interactive consent.
-    Path-scoped tools (``local_write_file``, ``local_edit_file``, reads,
-    ``present_files``) skip when every declared path is inside a writable
-    root. Shell tools skip only when the OS exec sandbox is on and the
-    working directory is inside those roots — the same split Codex uses
-    between ``workspace-write`` and ``on-request``. The allow is
-    request-scoped. The next call is judged again. Anything else falls
-    through to the inner approver.
+    A ``read`` mode call with no filesystem target skips the prompt. Path-scoped
+    tools (``local_write_file``, ``local_edit_file``, reads, ``present_files``)
+    still skip only when every declared path is inside a writable root — a
+    ``read`` declaration does not open a path outside those roots. Shell tools
+    skip only when the OS exec sandbox is on and the working directory is
+    inside those roots. The allow is request-scoped. The next call is judged
+    again. Anything else falls through to the inner approver.
     """
 
     def __init__(
@@ -232,11 +282,13 @@ class WorkspaceAutoApprover:
         *,
         sandbox_enforced: bool = False,
         auto_allow_tools: tuple[str, ...] = (),
+        path_base: str | None = None,
     ) -> None:
         self._inner = inner
         self._roots = [root for root in writable_roots if isinstance(root, str) and root.strip()]
         self._sandbox_enforced = sandbox_enforced
         self._auto_allow_tools = frozenset(auto_allow_tools)
+        self._path_base = path_base.strip() if isinstance(path_base, str) and path_base.strip() else None
 
     def set_sandbox_enforced(self, enforced: bool) -> None:
         """Match a mid-turn sandbox toggle.
@@ -254,10 +306,17 @@ class WorkspaceAutoApprover:
         if (
             self._roots
             and paths is not None
-            and all(path_inside_writable_roots(path, self._roots) for path in paths)
+            and all(
+                path_inside_writable_roots(path, self._roots, base=self._path_base)
+                for path in paths
+            )
         ):
             return ApprovalDecision("allow_once", "path is inside a writable project root")
-        if self._sandbox_enforced and shell_stays_in_workspace(request, self._roots):
+        if request.mode == "read" and paths is None:
+            return ApprovalDecision("allow_once", "declared read-only tool")
+        if self._sandbox_enforced and shell_stays_in_workspace(
+            request, self._roots, base=self._path_base
+        ):
             return ApprovalDecision("allow_once", "command stays inside the workspace sandbox")
         return await self._inner.approve(request)
 
@@ -382,6 +441,86 @@ def _default_resolver(call: ToolCall, ctx: LoopContext) -> ApprovalRequest:
     )
 
 
+#: Modes a host may declare on a tool. A declared value in this set is kept.
+#: Missing or unknown values fall back to ``decide_tool_mode``. Keeping a
+#: declared ``external`` stops a ``get_`` prefix from widening the call to read.
+TOOL_MODES = frozenset(
+    {
+        "read",
+        "safe_write",
+        "destructive",
+        "other",
+        "external",
+        "local",
+        "ui",
+        "synthetic",
+        "auto_local",
+    }
+)
+
+
+def _tool_declared_name(tool: dict[str, Any]) -> str | None:
+    name = tool.get("name")
+    if isinstance(name, str) and name:
+        return name
+    function = tool.get("function")
+    if isinstance(function, dict):
+        nested = function.get("name")
+        if isinstance(nested, str) and nested:
+            return nested
+    return None
+
+
+def _tool_declared_field(tool: dict[str, Any], key: str) -> Any:
+    if key in tool:
+        return tool.get(key)
+    function = tool.get("function")
+    if isinstance(function, dict) and key in function:
+        return function.get(key)
+    return None
+
+
+def declared_resolver(
+    tools: list[Any] | None,
+) -> Any:
+    """Build an approval resolver from ``agent.chat.stream`` tools.
+
+    Each tool may carry optional ``mode`` and ``approvalCategory``, either on
+    the tool object or under ``function``. Tools without those fields, and
+    calls whose name is absent from the list, use name inference and the tool
+    name as the category. Old hosts that omit the fields keep the previous
+    behavior.
+    """
+    declared: dict[str, tuple[Any, Any]] = {}
+    for tool in tools or []:
+        if not isinstance(tool, dict):
+            continue
+        name = _tool_declared_name(tool)
+        if name is None:
+            continue
+        declared[name] = (
+            _tool_declared_field(tool, "mode"),
+            _tool_declared_field(tool, "approvalCategory"),
+        )
+
+    def resolve(call: ToolCall, ctx: LoopContext) -> ApprovalRequest:
+        mode, category = declared.get(call.name, (None, None))
+        resolved_mode = (
+            mode if isinstance(mode, str) and mode in TOOL_MODES else decide_tool_mode(call.name)
+        )
+        resolved_category = category if isinstance(category, str) and category else call.name
+        return ApprovalRequest(
+            tool_name=call.name,
+            arguments=call.arguments or {},
+            mode=cast(ToolMode, resolved_mode),
+            category=resolved_category,
+            round_index=ctx.round_index,
+            call_id=call.id,
+        )
+
+    return resolve
+
+
 class ToolTimeoutClock:
     """Pauses the loop's tool cap while an approval prompt is unanswered.
 
@@ -457,10 +596,11 @@ 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.
+        stored = self._stored_decision(request)
+        decision = stored
+        # A fresh decision records the wait so the trace can show approval
+        # latency. A session allow reused from the cache carries `cached`
+        # instead, so the tool row can say the call was already allowed.
         waited_ms: int | None = None
         if decision is None:
             ask_started = time.monotonic()
@@ -468,17 +608,24 @@ class ApprovalExecutor:
             waited_ms = int((time.monotonic() - ask_started) * 1000)
             self._persist(request, decision)
 
-        approval_marker = (
-            {
+        if stored is not None and stored.kind == "allow_for_session":
+            approval_marker = {
+                "_approval": {
+                    "kind": "allow_for_session",
+                    "category": request.category,
+                    "cached": True,
+                }
+            }
+        elif waited_ms is not None:
+            approval_marker = {
                 "_approval": {
                     "kind": decision.kind,
                     "category": request.category,
                     "waitMs": waited_ms,
                 }
             }
-            if waited_ms is not None
-            else None
-        )
+        else:
+            approval_marker = None
 
         if decision.kind == "abort":
             raise ApprovalAborted(
@@ -503,9 +650,10 @@ class ApprovalExecutor:
             )
         ctx.consent_granted = True
         result = await self._inner.execute(call, ctx)
-        if approval_marker is not None:
+        data = result.data if isinstance(result.data, dict) else None
+        if approval_marker is not None or (data is not None and "_sandbox" in data):
             result = result.model_copy(
-                update={"data": {**(result.data or {}), **approval_marker}}
+                update={"data": _front_load_markers(data, approval_marker)}
             )
         return result
 

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/src/steerable_agent_runtime/harness.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from pathlib import Path
+from collections.abc import Callable
 from typing import Any, Protocol, runtime_checkable
 
 from .compaction import CompactionHooks
@@ -719,10 +720,12 @@ class DiscoveredNotesState:
 
     Unlike ``FilesystemState`` (one explicit path the model maintains), this
     is read-only discovery: the notes are project/user/managed-owned context
-    the session reads, not a working file it edits.
+    the session reads, not a working file it edits. ``trusted`` gates the
+    ``project`` and ``local`` levels; ``managed`` and ``user`` are always read.
     """
 
     cwd: Path | str
+    trusted: Callable[[Path], bool]
     max_chars: int = 8_000
     name: str = "discovered-notes"
     assumes: str = (
@@ -737,15 +740,16 @@ class DiscoveredNotesState:
         return InMemoryStorage()
 
     def hooks(self, *, provider: LLMProvider | None = None) -> LoopHooks:
-        return _DiscoveredNotesInjection(Path(self.cwd), self.max_chars)
+        return _DiscoveredNotesInjection(Path(self.cwd), self.max_chars, self.trusted)
 
 
 class _DiscoveredNotesInjection(NoopHooks):
     """pre_step slice: discover and append the notes union once per turn."""
 
-    def __init__(self, cwd: Path, max_chars: int) -> None:
+    def __init__(self, cwd: Path, max_chars: int, trusted: Callable[[Path], bool]) -> None:
         self._cwd = cwd
         self._max_chars = max_chars
+        self._trusted = trusted
 
     async def pre_step(self, transcript: Any, ctx: Any) -> Any:
         from .hooks import PreStepAction, TranscriptAppend
@@ -755,6 +759,8 @@ class _DiscoveredNotesInjection(NoopHooks):
         sections: list[tuple[str, Path, str]] = []
         budget = self._max_chars
         for level, path in discover_notes_files(self._cwd):
+            if level in ("project", "local") and not self._trusted(path.parent):
+                continue
             if budget <= 0:
                 break
             try:

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/src/steerable_agent_runtime/storage/sqlite_store.py

@@ -17,10 +17,10 @@ Concurrency: like ``InMemoryStorage``, all mutations run under one asyncio
 lock (safe under concurrent ``await`` in a single loop). Across processes
 the database uses WAL, ``busy_timeout``, and a shared lease on the sibling
 ``*.lock`` file, so two sidecars can write different sessions. Schema
-migration takes that file exclusively and fails when another process has
-the database open. A ``user_version`` newer than this process refuses to
-open. Process death releases the kernel lock; the lock file is never
-deleted.
+migration takes that file exclusively. A peer that is applying the schema
+is waited on briefly; a lease that is still held, or a ``user_version``
+newer than this process, refuses to open. Process death releases the
+kernel lock; the lock file is never deleted.
 """
 
 from __future__ import annotations
@@ -28,6 +28,7 @@ from __future__ import annotations
 import asyncio
 import json
 import sqlite3
+import time
 from collections.abc import Iterable
 from typing import Any
 
@@ -45,6 +46,11 @@ from .write_lease import WriteLease, acquire_shared_lease, acquire_write_lease
 
 SCHEMA_VERSION = 1
 _BUSY_TIMEOUT_MS = 5000
+# A second process can observe version 0 while the first still holds the
+# exclusive lease to create the schema. The hold is the migration itself,
+# not a live sidecar, so wait out that window before refusing.
+_PEER_MIGRATION_WAIT_S = 1.0
+_PEER_MIGRATION_POLL_S = 0.02
 
 _SCHEMA = """
 PRAGMA journal_mode = WAL;
@@ -138,31 +144,47 @@ def _apply_schema(db: sqlite3.Connection) -> None:
     db.commit()
 
 
+def _newer_than_this_program(version: int) -> StorageUpgradeBlockedError:
+    return StorageUpgradeBlockedError(
+        f"sidecar database version {version} is newer than this program ({SCHEMA_VERSION})"
+    )
+
+
 def _open_lease(path: str) -> WriteLease:
-    version = _read_user_version(path)
-    if version > SCHEMA_VERSION:
-        raise StorageUpgradeBlockedError(
-            f"sidecar database version {version} is newer than this program ({SCHEMA_VERSION})"
-        )
-    if version < SCHEMA_VERSION:
+    deadline = time.monotonic() + _PEER_MIGRATION_WAIT_S
+    while True:
+        version = _read_user_version(path)
+        if version > SCHEMA_VERSION:
+            raise _newer_than_this_program(version)
+        if version == SCHEMA_VERSION:
+            return acquire_shared_lease(path)
         try:
             exclusive = acquire_write_lease(path)
         except StoreAlreadyOwnedError as exc:
-            version = _read_user_version(path)
-            if version < SCHEMA_VERSION:
+            if time.monotonic() >= deadline:
+                version = _read_user_version(path)
+                if version > SCHEMA_VERSION:
+                    raise _newer_than_this_program(version) from exc
+                if version == SCHEMA_VERSION:
+                    return acquire_shared_lease(path)
                 raise StorageUpgradeBlockedError(
                     "sidecar database needs an upgrade but another process has it open"
                 ) from exc
-        else:
-            try:
+            time.sleep(_PEER_MIGRATION_POLL_S)
+            continue
+        try:
+            version = _read_user_version(path)
+            if version > SCHEMA_VERSION:
+                raise _newer_than_this_program(version)
+            if version < SCHEMA_VERSION:
                 db = _connect(path)
                 try:
                     _apply_schema(db)
                 finally:
                     db.close()
-            finally:
-                exclusive.release()
-    return acquire_shared_lease(path)
+        finally:
+            exclusive.release()
+        return acquire_shared_lease(path)
 
 
 class SqliteStorage:

{steerable_agent_runtime-0.6.74 → steerable_agent_runtime-0.7.0}/src/steerable_agent_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.6.74
+Version: 0.7.0
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 License: Apache-2.0
 Requires-Python: >=3.10