steerable-agent-runtime 0.6.56__tar.gz → 0.6.58__tar.gz

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/PKG-INFO

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

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/pyproject.toml

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

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/src/steerable_agent_runtime/calibration.py

@@ -25,11 +25,14 @@ from __future__ import annotations
 import json
 import os
 import tempfile
+import time
 from collections.abc import AsyncIterator, Iterable, Sequence
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, replace
 from typing import Any
 
+from .errors import StoreAlreadyOwnedError
 from .llm import LLMMessage, LLMProvider, LLMStreamChunk, LLMUsage
+from .storage.write_lease import WriteLease, acquire_write_lease
 from .tokens import estimate_text_tokens, estimate_tokens, register_model_factor
 
 #: Requests needed before a derived factor is trusted and auto-registered.
@@ -70,6 +73,7 @@ class UsageCalibration:
         self.min_samples = min_samples
         self.auto_register = auto_register
         self.models: dict[str, ModelCalibration] = {}
+        self._persisted: dict[str, ModelCalibration] = {}
 
     def record(
         self,
@@ -142,29 +146,84 @@ class UsageCalibration:
         return cal
 
     def save(self, path: str) -> None:
-        """Atomic write: tmp file + rename so a crash mid-write can't corrupt."""
-        directory = os.path.dirname(os.path.abspath(path))
-        os.makedirs(directory, exist_ok=True)
-        fd, tmp = tempfile.mkstemp(dir=directory, suffix=".tmp")
+        """Merge this process's new samples into ``path`` and write atomically.
+
+        The exclusive lease covers the reload and the rename, so two sidecars
+        recording different requests both keep their samples. Samples already
+        written by this object are not added again.
+        """
+        lease = _wait_for_file_lease(path)
         try:
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                json.dump(self.to_dict(), fh)
-            os.replace(tmp, path)
-        except BaseException:
-            try:
-                os.unlink(tmp)
-            except OSError:
-                pass
-            raise
+            disk = UsageCalibration.load(
+                path, min_samples=self.min_samples, auto_register=False
+            )
+            self.models = _merge_models(disk.models, self.models, self._persisted)
+            self._persisted = _snapshot(self.models)
+            _atomic_write(path, self.to_dict())
+        finally:
+            lease.release()
 
     @classmethod
     def load(cls, path: str, **kwargs: Any) -> UsageCalibration:
         """Load aggregates from ``path``; missing/corrupt file → empty."""
         try:
             with open(path, encoding="utf-8") as fh:
-                return cls.from_dict(json.load(fh), **kwargs)
+                cal = cls.from_dict(json.load(fh), **kwargs)
         except (OSError, ValueError):
-            return cls(**kwargs)
+            cal = cls(**kwargs)
+        cal._persisted = _snapshot(cal.models)
+        return cal
+
+
+def _snapshot(models: dict[str, ModelCalibration]) -> dict[str, ModelCalibration]:
+    return {name: replace(entry) for name, entry in models.items()}
+
+
+def _merge_models(
+    disk: dict[str, ModelCalibration],
+    local: dict[str, ModelCalibration],
+    persisted: dict[str, ModelCalibration],
+) -> dict[str, ModelCalibration]:
+    merged: dict[str, ModelCalibration] = {}
+    for name in set(disk) | set(local):
+        on_disk = disk.get(name, ModelCalibration())
+        current = local.get(name, ModelCalibration())
+        base = persisted.get(name, ModelCalibration())
+        merged[name] = ModelCalibration(
+            requests=on_disk.requests + (current.requests - base.requests),
+            est_prompt=on_disk.est_prompt + (current.est_prompt - base.est_prompt),
+            obs_prompt=on_disk.obs_prompt + (current.obs_prompt - base.obs_prompt),
+            est_completion=on_disk.est_completion + (current.est_completion - base.est_completion),
+            obs_completion=on_disk.obs_completion + (current.obs_completion - base.obs_completion),
+        )
+    return merged
+
+
+def _wait_for_file_lease(path: str, timeout_s: float = 5.0) -> WriteLease:
+    deadline = time.monotonic() + timeout_s
+    while True:
+        try:
+            return acquire_write_lease(path)
+        except StoreAlreadyOwnedError:
+            if time.monotonic() >= deadline:
+                raise
+            time.sleep(0.01)
+
+
+def _atomic_write(path: str, payload: dict[str, Any]) -> None:
+    directory = os.path.dirname(os.path.abspath(path))
+    os.makedirs(directory, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=directory, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
 
 
 @dataclass

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/src/steerable_agent_runtime/errors.py

@@ -18,8 +18,12 @@ class StorageError(RuntimeError):
     """Persistence layer failure."""
 
 
+class StorageUpgradeBlockedError(StorageError):
+    """The database is newer than this process, or a migration cannot take the exclusive lock."""
+
+
 class StoreAlreadyOwnedError(StorageError):
-    """Another process already holds the write lease for this database."""
+    """Another process already holds the exclusive lease for this database."""
 
     def __init__(self, path: str) -> None:
         super().__init__(

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/src/steerable_agent_runtime/storage/__init__.py

@@ -117,7 +117,7 @@ class StorageAdapter(Protocol):
 
 from .in_memory import InMemoryStorage  # noqa: E402
 from .sqlite_store import SqliteStorage  # noqa: E402
-from .write_lease import acquire_write_lease, lock_path_for_db  # noqa: E402
+from .write_lease import acquire_shared_lease, acquire_write_lease, lock_path_for_db  # noqa: E402
 from ..errors import StoreAlreadyOwnedError  # noqa: E402
 
 try:
@@ -132,6 +132,7 @@ __all__ = [
     "SqliteStorage",
     "SqlAlchemyStorage",
     "StoreAlreadyOwnedError",
+    "acquire_shared_lease",
     "acquire_write_lease",
     "lock_path_for_db",
 ]

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/src/steerable_agent_runtime/storage/sqlite_store.py

@@ -14,13 +14,13 @@ duplicated as real columns with indexes, so session enumeration and the
 resume tail-scan are indexed lookups, never a table scan over JSON.
 
 Concurrency: like ``InMemoryStorage``, all mutations run under one asyncio
-lock (safe under concurrent ``await`` in a single loop). A sibling
-``*.lock`` file (``fcntl.flock`` / Windows named mutex) makes the writer
-process-exclusive: a second process opening the same path fails loud
-(``StoreAlreadyOwnedError``). Process death releases the kernel lock;
-there is no TTL steal; the lock file is never deleted. WAL remains so a
-reader (e.g. the maintenance CLI) does not block the writer and does not
-take the write lease.
+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.
 """
 
 from __future__ import annotations
@@ -40,8 +40,11 @@ from steerable_agent_protocol.generated import (
     TraceSpan,
 )
 
-from ..errors import StorageError
-from .write_lease import WriteLease, acquire_write_lease
+from ..errors import StorageError, StorageUpgradeBlockedError, StoreAlreadyOwnedError
+from .write_lease import WriteLease, acquire_shared_lease, acquire_write_lease
+
+SCHEMA_VERSION = 1
+_BUSY_TIMEOUT_MS = 5000
 
 _SCHEMA = """
 PRAGMA journal_mode = WAL;
@@ -107,17 +110,75 @@ def _dump(model: Any) -> str:
     return json.dumps(model.model_dump(mode="json"), ensure_ascii=False)
 
 
+def _is_memory(path: str) -> bool:
+    return path == ":memory:" or path.startswith("file::memory:")
+
+
+def _connect(path: str) -> sqlite3.Connection:
+    db = sqlite3.connect(path, timeout=_BUSY_TIMEOUT_MS / 1000, check_same_thread=False)
+    db.row_factory = sqlite3.Row
+    db.execute(f"PRAGMA busy_timeout = {_BUSY_TIMEOUT_MS}")
+    db.execute("PRAGMA journal_mode = WAL")
+    db.execute("PRAGMA synchronous = NORMAL")
+    return db
+
+
+def _read_user_version(path: str) -> int:
+    db = sqlite3.connect(path, timeout=_BUSY_TIMEOUT_MS / 1000)
+    try:
+        row = db.execute("PRAGMA user_version").fetchone()
+        return int(row[0]) if row else 0
+    finally:
+        db.close()
+
+
+def _apply_schema(db: sqlite3.Connection) -> None:
+    db.executescript(_SCHEMA)
+    db.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+    db.commit()
+
+
+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:
+        try:
+            exclusive = acquire_write_lease(path)
+        except StoreAlreadyOwnedError as exc:
+            version = _read_user_version(path)
+            if version < SCHEMA_VERSION:
+                raise StorageUpgradeBlockedError(
+                    "sidecar database needs an upgrade but another process has it open"
+                ) from exc
+        else:
+            try:
+                db = _connect(path)
+                try:
+                    _apply_schema(db)
+                finally:
+                    db.close()
+            finally:
+                exclusive.release()
+    return acquire_shared_lease(path)
+
+
 class SqliteStorage:
     """Stdlib-sqlite3 StorageAdapter. See module docstring for the contract."""
 
     def __init__(self, path: str) -> None:
         self._path = path
         self._lock = asyncio.Lock()
-        self._lease: WriteLease = acquire_write_lease(path)
+        self._lease = WriteLease._unheld()
+        if _is_memory(path):
+            self._db = _connect(path)
+            _apply_schema(self._db)
+            return
+        self._lease = _open_lease(path)
         try:
-            self._db = sqlite3.connect(path, check_same_thread=False)
-            self._db.row_factory = sqlite3.Row
-            self._db.executescript(_SCHEMA)
+            self._db = _connect(path)
         except BaseException:
             self._lease.release()
             raise

steerable_agent_runtime-0.6.58/src/steerable_agent_runtime/storage/write_lease.py

@@ -0,0 +1,173 @@
+"""Cross-process leases for one sqlite database file.
+
+Several processes may hold a shared lease on the sibling ``*.lock`` file
+(``sessions.db`` → ``sessions.lock``) while they have the database open.
+Schema migration takes an exclusive lease and fails immediately when any
+other process holds the file. Process death releases the kernel lock.
+There is no TTL that could steal from a live process. The lock file is
+never deleted: it keeps a stable inode for later lockers.
+
+POSIX uses non-blocking ``fcntl.flock`` (``LOCK_SH`` to register an open
+database, ``LOCK_EX`` to migrate). Windows uses the lock file's share mode,
+the same rule as the Rust sidecar: shared openers allow read and write
+sharing, and an exclusive opener allows none. SQLite byte-range locks do
+not see this file, so only this flock/share-mode pair coordinates Python
+and Rust.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from ..errors import StoreAlreadyOwnedError
+
+_LOCK_ATTEMPTS = 3
+
+
+def lock_path_for_db(db_path: str | os.PathLike[str]) -> Path:
+    """Sibling lock file: ``sessions.db`` → ``sessions.lock``."""
+    return Path(db_path).expanduser().resolve().with_suffix(".lock")
+
+
+def _is_memory(db_path: str) -> bool:
+    return db_path == ":memory:" or db_path.startswith("file::memory:")
+
+
+def acquire_shared_lease(db_path: str | os.PathLike[str]) -> "WriteLease":
+    """Register that this process has ``db_path`` open.
+
+    Other shared holders succeed. An exclusive holder (a migration, or an
+    older sidecar that still locks the whole database) fails loud.
+    ``:memory:`` databases have no file and take no lease.
+    """
+    return _acquire(db_path, shared=True)
+
+
+def acquire_write_lease(db_path: str | os.PathLike[str]) -> "WriteLease":
+    """Acquire the exclusive lease for ``db_path``.
+
+    Used for schema migration. A shared or exclusive holder fails loud.
+    ``:memory:`` databases have no file and take no lease.
+    """
+    return _acquire(db_path, shared=False)
+
+
+def _acquire(db_path: str | os.PathLike[str], *, shared: bool) -> "WriteLease":
+    raw = os.fspath(db_path)
+    if _is_memory(raw):
+        return WriteLease._unheld()
+    lock_path = lock_path_for_db(raw)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "win32":
+        return WriteLease._acquire_win32(lock_path, shared=shared)
+    return WriteLease._acquire_posix(lock_path, shared=shared)
+
+
+class WriteLease:
+    """Held kernel lock. ``release`` closes the descriptor/handle; the file stays."""
+
+    def __init__(self, *, _fd: int | None, _handle: Any, _lock_path: Path | None) -> None:
+        self._fd = _fd
+        self._handle = _handle
+        self._lock_path = _lock_path
+        self._released = False
+
+    @classmethod
+    def _unheld(cls) -> "WriteLease":
+        return cls(_fd=None, _handle=None, _lock_path=None)
+
+    @classmethod
+    def _acquire_posix(cls, lock_path: Path, *, shared: bool) -> "WriteLease":
+        import fcntl
+
+        mode = fcntl.LOCK_SH if shared else fcntl.LOCK_EX
+        for _ in range(_LOCK_ATTEMPTS):
+            fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
+            try:
+                fcntl.flock(fd, mode | fcntl.LOCK_NB)
+            except OSError as exc:
+                os.close(fd)
+                if exc.errno in (errno.EAGAIN, errno.EWOULDBLOCK, errno.EACCES):
+                    raise StoreAlreadyOwnedError(str(lock_path)) from exc
+                raise
+            held = os.fstat(fd)
+            try:
+                current = os.stat(lock_path)
+            except FileNotFoundError:
+                os.close(fd)
+                continue
+            if (held.st_ino, held.st_dev) == (current.st_ino, current.st_dev):
+                return cls(_fd=fd, _handle=None, _lock_path=lock_path)
+            os.close(fd)
+        raise StoreAlreadyOwnedError(str(lock_path))
+
+    @classmethod
+    def _acquire_win32(cls, lock_path: Path, *, shared: bool) -> "WriteLease":
+        import ctypes
+        from ctypes import wintypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        create_file = kernel32.CreateFileW
+        create_file.argtypes = [
+            wintypes.LPCWSTR,
+            wintypes.DWORD,
+            wintypes.DWORD,
+            wintypes.LPVOID,
+            wintypes.DWORD,
+            wintypes.DWORD,
+            wintypes.HANDLE,
+        ]
+        create_file.restype = wintypes.HANDLE
+        generic_read = 0x80000000
+        generic_write = 0x40000000
+        file_share_read = 0x00000001
+        file_share_write = 0x00000002
+        open_always = 4
+        file_attribute_normal = 0x80
+        error_sharing = 32
+        error_lock = 33
+        invalid = wintypes.HANDLE(-1).value
+        share = file_share_read | file_share_write if shared else 0
+        handle = create_file(
+            str(lock_path),
+            generic_read | generic_write,
+            share,
+            None,
+            open_always,
+            file_attribute_normal,
+            None,
+        )
+        if handle is None or int(handle) == int(invalid):
+            err = ctypes.get_last_error()
+            if err in (error_sharing, error_lock):
+                raise StoreAlreadyOwnedError(str(lock_path))
+            raise ctypes.WinError(err)
+        return cls(_fd=None, _handle=handle, _lock_path=lock_path)
+
+    def release(self) -> None:
+        if self._released:
+            return
+        self._released = True
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+        if self._handle is not None:
+            import ctypes
+            from ctypes import wintypes
+
+            kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+            close_handle = kernel32.CloseHandle
+            close_handle.argtypes = [wintypes.HANDLE]
+            close_handle.restype = wintypes.BOOL
+            close_handle(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "WriteLease":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/src/steerable_agent_runtime.egg-info/PKG-INFO

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

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/tests/test_calibration.py

@@ -88,6 +88,46 @@ class TestUsageCalibration:
         assert loaded.factor("m") == pytest.approx(320 / 400)
         assert loaded.models["m"].obs_completion == 40
 
+    def test_two_processes_keep_both_models(self, tmp_path) -> None:
+        import subprocess
+        import sys
+
+        path = tmp_path / "token-calibration.json"
+        script = r"""
+import sys
+import time
+from pathlib import Path
+
+from steerable_agent_runtime import UsageCalibration
+
+path, model, ready, peer = sys.argv[1:5]
+cal = UsageCalibration.load(path, min_samples=1, auto_register=False)
+Path(ready).write_text("ready", encoding="utf-8")
+deadline = time.monotonic() + 5
+while time.monotonic() < deadline and not Path(peer).exists():
+    time.sleep(0.02)
+cal.record(model, est_prompt=100, obs_prompt=80)
+cal.save(path)
+"""
+        ready_a = tmp_path / "a.ready"
+        ready_b = tmp_path / "b.ready"
+        proc_a = subprocess.Popen(
+            [sys.executable, "-c", script, str(path), "model-a", str(ready_a), str(ready_b)]
+        )
+        proc_b = subprocess.Popen(
+            [sys.executable, "-c", script, str(path), "model-b", str(ready_b), str(ready_a)]
+        )
+        try:
+            assert proc_a.wait(timeout=15) == 0
+            assert proc_b.wait(timeout=15) == 0
+        finally:
+            proc_a.kill()
+            proc_b.kill()
+        loaded = UsageCalibration.load(str(path), min_samples=1, auto_register=False)
+        assert set(loaded.models) == {"model-a", "model-b"}
+        assert loaded.models["model-a"].requests == 1
+        assert loaded.models["model-b"].requests == 1
+
     def test_load_missing_or_corrupt_returns_empty(self, tmp_path) -> None:
         assert UsageCalibration.load(str(tmp_path / "nope.json")).models == {}
         bad = tmp_path / "bad.json"

{steerable_agent_runtime-0.6.56 → steerable_agent_runtime-0.6.58}/tests/test_write_lease.py

@@ -7,8 +7,10 @@ import sys
 import time
 from pathlib import Path
 
+import sqlite3
+
 import pytest
-from steerable_agent_runtime.errors import StoreAlreadyOwnedError
+from steerable_agent_runtime.errors import StorageUpgradeBlockedError, StoreAlreadyOwnedError
 from steerable_agent_runtime.storage import SqliteStorage
 from steerable_agent_runtime.storage.write_lease import (
     acquire_write_lease,
@@ -62,7 +64,7 @@ def test_second_process_fails_loud(tmp_path: Path) -> None:
         _wait_held(holder, flag)
         with pytest.raises(StoreAlreadyOwnedError, match="already owned"):
             acquire_write_lease(db)
-        with pytest.raises(StoreAlreadyOwnedError):
+        with pytest.raises(StorageUpgradeBlockedError, match="another process"):
             SqliteStorage(str(db))
         assert lock_path_for_db(db).is_file()
     finally:
@@ -87,6 +89,79 @@ def test_successor_opens_after_holder_is_killed(tmp_path: Path) -> None:
     assert lock_path_for_db(db).is_file()
 
 
+_WRITER = r"""
+import asyncio
+import sys
+
+from steerable_agent_protocol.generated import AgentSession
+from steerable_agent_runtime.storage import SqliteStorage
+
+
+async def main() -> None:
+    store = SqliteStorage(sys.argv[1])
+    await store.upsert_session(
+        AgentSession(
+            sessionId=sys.argv[2],
+            userId="u1",
+            chatId=sys.argv[2],
+            currentStage="chat",
+            isActive=True,
+            createdAt="2026-08-30T00:00:00Z",
+            updatedAt="2026-08-30T00:00:00Z",
+        )
+    )
+    store.close()
+
+
+asyncio.run(main())
+"""
+
+
+def test_two_processes_write_different_sessions(tmp_path: Path) -> None:
+    """Two sidecars can write different sessions in one database."""
+    import asyncio
+
+    from steerable_agent_protocol.generated import AgentSession
+
+    db = tmp_path / "sessions.db"
+    store = SqliteStorage(str(db))
+    try:
+        asyncio.run(
+            store.upsert_session(
+                AgentSession(
+                    sessionId="s1",
+                    userId="u1",
+                    chatId="c1",
+                    currentStage="chat",
+                    isActive=True,
+                    createdAt="2026-08-30T00:00:00Z",
+                    updatedAt="2026-08-30T00:00:00Z",
+                )
+            )
+        )
+        child = subprocess.run(
+            [sys.executable, "-c", _WRITER, str(db), "s2"],
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+        assert child.returncode == 0, child.stderr
+        loaded = asyncio.run(store.get_session("s2"))
+        assert loaded is not None and loaded.sessionId == "s2"
+    finally:
+        store.close()
+
+
+def test_refuses_a_database_newer_than_this_program(tmp_path: Path) -> None:
+    db = tmp_path / "sessions.db"
+    conn = sqlite3.connect(db)
+    conn.execute("PRAGMA user_version = 99")
+    conn.commit()
+    conn.close()
+    with pytest.raises(StorageUpgradeBlockedError, match="newer than this program"):
+        SqliteStorage(str(db))
+
+
 def test_release_does_not_delete_lock_file(tmp_path: Path) -> None:
     db = tmp_path / "sessions.db"
     lease = acquire_write_lease(db)