agent-runtime-py 0.1.0__py3-none-any.whl

agent_runtime/store.py

@@ -0,0 +1,277 @@
+"""Private durable execution state, input receipts, and ordered event cursors."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+
+class Store:
+    def __init__(self, root: Path) -> None:
+        self.root = root.expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        os.chmod(self.root, 0o700)
+        self.path = self.root / "runtime.sqlite3"
+        with self.connect() as db:
+            db.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS executions (
+                    id TEXT PRIMARY KEY, session_id TEXT NOT NULL, created REAL NOT NULL,
+                    value TEXT NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS execution_sessions ON executions(session_id,created);
+                CREATE TABLE IF NOT EXISTS inputs (
+                    session_id TEXT NOT NULL, id TEXT NOT NULL, execution_id TEXT NOT NULL,
+                    digest TEXT NOT NULL, text TEXT NOT NULL, status TEXT NOT NULL,
+                    created REAL NOT NULL, error TEXT, native_uuid TEXT,
+                    PRIMARY KEY(session_id,id)
+                );
+                CREATE TABLE IF NOT EXISTS events (
+                    seq INTEGER PRIMARY KEY AUTOINCREMENT, execution_id TEXT NOT NULL,
+                    session_id TEXT NOT NULL, value TEXT NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS event_sessions ON events(session_id,seq);
+                CREATE TABLE IF NOT EXISTS interactions (
+                    id TEXT PRIMARY KEY, execution_id TEXT NOT NULL,
+                    request TEXT NOT NULL, answer TEXT
+                );
+                CREATE TABLE IF NOT EXISTS controls (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT, execution_id TEXT NOT NULL,
+                    operation TEXT NOT NULL, payload TEXT NOT NULL, state TEXT NOT NULL
+                );
+                """
+            )
+        os.chmod(self.path, 0o600)
+
+    @contextmanager
+    def connect(self) -> Iterator[sqlite3.Connection]:
+        db = sqlite3.connect(self.path, timeout=30)
+        db.row_factory = sqlite3.Row
+        try:
+            with db:
+                yield db
+        finally:
+            db.close()
+
+    def create_execution(self, value: dict[str, Any]) -> bool:
+        with self.connect() as db:
+            cursor = db.execute(
+                "INSERT OR IGNORE INTO executions VALUES(?,?,?,?)",
+                (
+                    value["execution_id"],
+                    value["session_id"],
+                    value["created_at"],
+                    json.dumps(value),
+                ),
+            )
+            return cursor.rowcount == 1
+
+    def execution(self, identity: str) -> dict[str, Any]:
+        with self.connect() as db:
+            row = db.execute("SELECT value FROM executions WHERE id=?", (identity,)).fetchone()
+        if row is None:
+            raise KeyError(f"unknown execution: {identity}")
+        return json.loads(row[0])
+
+    def latest(self, session_id: str) -> dict[str, Any] | None:
+        with self.connect() as db:
+            row = db.execute(
+                "SELECT value FROM executions WHERE session_id=? ORDER BY created DESC LIMIT 1",
+                (session_id,),
+            ).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def update(self, identity: str, **fields: Any) -> dict[str, Any]:
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute("SELECT value FROM executions WHERE id=?", (identity,)).fetchone()
+            if row is None:
+                raise KeyError(identity)
+            value = {**json.loads(row[0]), **fields}
+            db.execute("UPDATE executions SET value=? WHERE id=?", (json.dumps(value), identity))
+        return value
+
+    def accept(
+        self, session_id: str, execution_id: str, identity: str, text: str
+    ) -> dict[str, Any]:
+        if not identity or not text.strip():
+            raise ValueError("message ID and text must be nonempty")
+        digest = hashlib.sha256(text.encode()).hexdigest()
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute(
+                "SELECT * FROM inputs WHERE session_id=? AND id=?", (session_id, identity)
+            ).fetchone()
+            if row is not None:
+                if row["digest"] != digest:
+                    raise ValueError("message ID was already used with different text")
+            else:
+                db.execute(
+                    "INSERT INTO inputs(session_id,id,execution_id,digest,text,status,created) "
+                    "VALUES(?,?,?,?,?,'accepted',?)",
+                    (session_id, identity, execution_id, digest, text, time.time()),
+                )
+        receipt = self.receipt(session_id, identity)
+        assert receipt is not None
+        return receipt
+
+    def receipt(self, session_id: str, identity: str) -> dict[str, Any] | None:
+        with self.connect() as db:
+            row = db.execute(
+                "SELECT id AS message_id,execution_id,status,error,native_uuid,created "
+                "FROM inputs WHERE session_id=? AND id=?",
+                (session_id, identity),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def take_input(self, execution_id: str) -> dict[str, Any] | None:
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute(
+                "SELECT * FROM inputs WHERE execution_id=? AND status='accepted' "
+                "ORDER BY created LIMIT 1",
+                (execution_id,),
+            ).fetchone()
+            if row is not None:
+                db.execute(
+                    "UPDATE inputs SET status='dispatching' WHERE session_id=? AND id=?",
+                    (row["session_id"], row["id"]),
+                )
+        return dict(row) if row else None
+
+    def input_status(
+        self,
+        session_id: str,
+        identity: str,
+        status: str,
+        *,
+        error: str | None = None,
+        native_uuid: str | None = None,
+    ) -> None:
+        with self.connect() as db:
+            db.execute(
+                "UPDATE inputs SET status=?,error=?,native_uuid=COALESCE(?,native_uuid) "
+                "WHERE session_id=? AND id=?",
+                (status, error, native_uuid, session_id, identity),
+            )
+
+    def lose_dispatches(self, execution_id: str) -> None:
+        with self.connect() as db:
+            db.execute(
+                "UPDATE inputs SET status='uncertain',"
+                "error='worker exited before native admission acknowledgement' "
+                "WHERE execution_id=? AND status='dispatching'",
+                (execution_id,),
+            )
+
+    def reject_pending(self, execution_id: str, error: str) -> None:
+        with self.connect() as db:
+            db.execute(
+                "UPDATE inputs SET status='rejected',error=? "
+                "WHERE execution_id=? AND status='accepted'",
+                (error, execution_id),
+            )
+
+    def admit(self, execution_id: str, native_uuid: str) -> str | None:
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute(
+                "SELECT id FROM inputs "
+                "WHERE execution_id=? AND native_uuid=? AND status='dispatching'",
+                (execution_id, native_uuid),
+            ).fetchone()
+            if row is not None:
+                db.execute(
+                    "UPDATE inputs SET status='delivered',error=NULL "
+                    "WHERE execution_id=? AND native_uuid=?",
+                    (execution_id, native_uuid),
+                )
+        return row[0] if row else None
+
+    def append(self, execution_id: str, session_id: str, value: dict[str, Any]) -> int:
+        with self.connect() as db:
+            cursor = db.execute(
+                "INSERT INTO events(execution_id,session_id,value) VALUES(?,?,?)",
+                (execution_id, session_id, json.dumps(value)),
+            )
+            assert cursor.lastrowid is not None
+            return cursor.lastrowid
+
+    def events(self, session_id: str, after: int = 0) -> list[dict[str, Any]]:
+        with self.connect() as db:
+            rows = db.execute(
+                "SELECT * FROM events WHERE session_id=? AND seq>? ORDER BY seq",
+                (session_id, after),
+            ).fetchall()
+        return [
+            {
+                "execution_id": row["execution_id"],
+                "cursor": {"execution_id": row["execution_id"], "offset": row["seq"]},
+                "event": json.loads(row["value"]),
+            }
+            for row in rows
+        ]
+
+    def request(self, execution_id: str, identity: str, value: dict[str, Any]) -> None:
+        with self.connect() as db:
+            db.execute(
+                "INSERT OR IGNORE INTO interactions VALUES(?,?,?,NULL)",
+                (identity, execution_id, json.dumps(value)),
+            )
+
+    def interactions(self, execution_id: str) -> list[dict[str, Any]]:
+        with self.connect() as db:
+            rows = db.execute(
+                "SELECT request FROM interactions WHERE execution_id=? AND answer IS NULL",
+                (execution_id,),
+            ).fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+    def answer(self, execution_id: str, identity: str, value: dict[str, Any]) -> None:
+        encoded = json.dumps(value, sort_keys=True)
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute(
+                "SELECT answer FROM interactions WHERE id=? AND execution_id=?",
+                (identity, execution_id),
+            ).fetchone()
+            if row is None:
+                raise KeyError("unknown interaction")
+            if row[0] is not None and row[0] != encoded:
+                raise ValueError("interaction already has a different answer")
+            db.execute("UPDATE interactions SET answer=? WHERE id=?", (encoded, identity))
+
+    def response(self, identity: str) -> dict[str, Any] | None:
+        with self.connect() as db:
+            row = db.execute("SELECT answer FROM interactions WHERE id=?", (identity,)).fetchone()
+        return json.loads(row[0]) if row and row[0] else None
+
+    def control(self, execution_id: str, operation: str, payload: dict[str, Any]) -> int:
+        with self.connect() as db:
+            cursor = db.execute(
+                "INSERT INTO controls(execution_id,operation,payload,state) "
+                "VALUES(?,?,?,'pending')",
+                (execution_id, operation, json.dumps(payload)),
+            )
+            assert cursor.lastrowid is not None
+            return cursor.lastrowid
+
+    def take_controls(self, execution_id: str) -> list[dict[str, Any]]:
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            rows = db.execute(
+                "SELECT * FROM controls WHERE execution_id=? AND state='pending' ORDER BY id",
+                (execution_id,),
+            ).fetchall()
+            db.execute(
+                "UPDATE controls SET state='dispatched' WHERE execution_id=? AND state='pending'",
+                (execution_id,),
+            )
+        return [{**dict(row), "payload": json.loads(row["payload"])} for row in rows]

agent_runtime/worker.py

@@ -0,0 +1,290 @@
+"""One detached owner for one native Claude process and its durable event stream."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import time
+import uuid
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any
+
+import psutil
+from claude_agent_sdk import (
+    TERMINAL_TASK_STATUSES,
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    ResultMessage,
+    TextBlock,
+    ToolPermissionContext,
+    UserMessage,
+)
+from filelock import FileLock
+
+from agent_runtime.monitors import Monitors
+from agent_runtime.store import Store
+
+log = logging.getLogger(__name__)
+
+
+class Worker:
+    def __init__(self, store: Store, execution_id: str) -> None:
+        self.store = store
+        self.execution_id = execution_id
+        self.execution = store.execution(execution_id)
+        self.session_id = self.execution["session_id"]
+        self.stopping = asyncio.Event()
+        self.active: dict[str, Any] | None = None
+        self.last_activity = time.monotonic()
+        self.background_tasks: set[str] = set()
+        self.presentation_started = False
+
+    def emit(self, kind: str, **fields: Any) -> None:
+        self.store.append(self.execution_id, self.session_id, {"type": kind, **fields})
+
+    async def permission(
+        self, name: str, value: dict[str, Any], context: ToolPermissionContext
+    ) -> Any:
+        identity = "Q" + uuid.uuid4().hex[:12]
+        self.store.request(
+            self.execution_id,
+            identity,
+            {
+                "id": identity,
+                "provider": "claude_code",
+                "method": "agent/question"
+                if name == "AskUserQuestion"
+                else "agent/requestApproval",
+                "params": {
+                    "tool": name,
+                    "input": value,
+                    "title": context.title,
+                    "description": context.description,
+                    "reason": context.decision_reason,
+                    "tool_use_id": context.tool_use_id,
+                    "agent_id": context.agent_id,
+                },
+            },
+        )
+        self.emit("interaction.requested", id=identity)
+        while not self.stopping.is_set():
+            answer = self.store.response(identity)
+            if answer is not None:
+                if name == "AskUserQuestion":
+                    answers = answer.get("answers")
+                    if not isinstance(answers, dict) or not all(
+                        isinstance(k, str) and isinstance(v, str) for k, v in answers.items()
+                    ):
+                        return PermissionResultDeny(
+                            message="invalid question response: expected a string-to-string mapping"
+                        )
+                    return PermissionResultAllow(updated_input={**value, "answers": answers})
+                if answer.get("decision") == "allow":
+                    return PermissionResultAllow(updated_input=value)
+                return PermissionResultDeny(message="The user denied this operation.")
+            await asyncio.sleep(0.1)
+        return PermissionResultDeny(message="Worker is stopping.", interrupt=True)
+
+    async def receive(self, client: ClaudeSDKClient) -> None:
+        async for message in client.receive_messages():
+            self.last_activity = time.monotonic()
+            raw = asdict(message) if is_dataclass(message) else {"description": repr(message)}
+            self.emit("claude.message", message_class=type(message).__name__, message=raw)
+            if isinstance(message, UserMessage) and message.uuid:
+                if admitted := self.store.admit(self.execution_id, message.uuid):
+                    self.emit("input.delivered", message_id=admitted, native_uuid=message.uuid)
+            elif isinstance(message, AssistantMessage) and message.parent_tool_use_id is None:
+                if not self.presentation_started:
+                    self.emit("turn.started", origin="native")
+                    self.presentation_started = True
+                text = "\n".join(
+                    block.text for block in message.content if isinstance(block, TextBlock)
+                )
+                if text:
+                    self.emit("agent.message", text=text, native_uuid=message.uuid)
+            elif isinstance(message, ResultMessage):
+                if message.session_id != self.session_id:
+                    raise RuntimeError("native Claude returned a different session ID")
+                human = message.origin is None or message.origin.get("kind") == "human"
+                active = self.active if human else None
+                status = "failed" if message.is_error else "completed"
+                if message.terminal_reason in {"aborted_streaming", "aborted_tools"}:
+                    status = "interrupted"
+                self.emit(
+                    "agent.turn.completed",
+                    status=status,
+                    origin=message.origin,
+                    terminal_reason=message.terminal_reason,
+                    usage=message.usage,
+                )
+                self.emit(
+                    "work.settled",
+                    status=status,
+                    message=message.result or "",
+                    message_ids=[active["id"]] if active else [],
+                    origin=message.origin,
+                    errors=message.errors,
+                    error="; ".join(message.errors or []) or None,
+                    last_turn_status=status,
+                )
+                self.presentation_started = False
+                if active:
+                    receipt = self.store.receipt(self.session_id, active["id"])
+                    if receipt and receipt["status"] == "dispatching":
+                        # A result does not identify which input UUID it accepted.
+                        # Preserve uncertainty if the expected native echo was lost.
+                        self.store.input_status(
+                            self.session_id,
+                            active["id"],
+                            "uncertain",
+                            error="native result arrived without input UUID acknowledgement",
+                        )
+                    self.active = None
+            else:
+                data = getattr(message, "data", {})
+                subtype = getattr(message, "subtype", "")
+                task_id = data.get("task_id") if isinstance(data, dict) else None
+                if task_id and subtype == "task_started":
+                    self.background_tasks.add(task_id)
+                elif (task_id and subtype == "task_notification") or (
+                    task_id
+                    and subtype == "task_updated"
+                    and data.get("patch", {}).get("status") in TERMINAL_TASK_STATUSES
+                ):
+                    self.background_tasks.discard(task_id)
+        if not self.stopping.is_set():
+            raise RuntimeError("native Claude event stream closed")
+
+    async def run(self) -> None:
+        policy = self.execution["configuration"]
+        options = ClaudeAgentOptions(
+            cwd=policy["cwd"],
+            cli_path=policy["claude"],
+            permission_mode=policy["permission_mode"],
+            allowed_tools=policy["allowed_tools"],
+            model=policy["model"],
+            setting_sources=["user", "project", "local"],
+            system_prompt={
+                "type": "preset",
+                "preset": "claude_code",
+                "append": policy["instructions"] or "",
+            },
+            can_use_tool=self.permission,
+            stderr=lambda line: log.debug("claude: %s", line),
+            extra_args={"replay-user-messages": None},
+            session_id=self.session_id
+            if not self.execution["resume"] or self.execution["fork"]
+            else None,
+            resume=self.execution["resume"],
+            fork_session=self.execution["fork"],
+        )
+        for signum in (signal.SIGTERM, signal.SIGINT):
+            asyncio.get_running_loop().add_signal_handler(signum, self.stopping.set)
+        client = ClaudeSDKClient(options)
+        reader: asyncio.Task[None] | None = None
+        result: dict[str, Any] = {"status": "stopped"}
+        try:
+            await client.connect()
+            self.store.update(self.execution_id, state="running", ready_at=time.time())
+            self.emit("worker.ready", provider="claude_code", session_id=self.session_id)
+            reader = asyncio.create_task(self.receive(client))
+            while not self.stopping.is_set():
+                if reader.done():
+                    await reader
+                    break
+                for control in self.store.take_controls(self.execution_id):
+                    match control["operation"]:
+                        case "stop":
+                            self.stopping.set()
+                        case "interrupt":
+                            await client.interrupt()
+                        case "set_model":
+                            await client.set_model(control["payload"]["model"])
+                        case _:
+                            self.emit(
+                                "control.failed", id=control["id"], error="unsupported operation"
+                            )
+                if self.stopping.is_set():
+                    break
+                if self.active is None:
+                    self.active = self.store.take_input(self.execution_id)
+                    if self.active:
+                        native_uuid = str(uuid.uuid4())
+                        self.store.input_status(
+                            self.session_id,
+                            self.active["id"],
+                            "dispatching",
+                            native_uuid=native_uuid,
+                        )
+                        text = self.active["text"]
+                        input_id = self.active["id"]
+
+                        async def prompt(native_uuid=native_uuid, text=text):
+                            yield {
+                                "type": "user",
+                                "uuid": native_uuid,
+                                "session_id": self.session_id,
+                                "origin": {"kind": "human"},
+                                "message": {"role": "user", "content": text},
+                            }
+
+                        self.emit("turn.started", message_id=input_id, native_uuid=native_uuid)
+                        self.presentation_started = True
+                        await client.query(prompt(), session_id=self.session_id)
+                        self.last_activity = time.monotonic()
+                timeout = policy["idle_timeout_seconds"]
+                if (
+                    timeout
+                    and self.active is None
+                    and not self.background_tasks
+                    and time.monotonic() - self.last_activity >= timeout
+                    and not any(
+                        monitor["status"] in {"starting", "running"}
+                        for monitor in Monitors().list(self.session_id)
+                    )
+                ):
+                    result = {"status": "completed", "reason": "idle_timeout"}
+                    break
+                await asyncio.sleep(0.1)
+        except Exception as error:
+            log.exception("Claude worker failed")
+            result = {"status": "failed", "error": str(error)}
+        finally:
+            self.stopping.set()
+            try:
+                await client.disconnect()
+            except Exception:
+                log.exception("Claude disconnect failed")
+            if reader is not None:
+                reader.cancel()
+                await asyncio.gather(reader, return_exceptions=True)
+            self.store.lose_dispatches(self.execution_id)
+            self.store.reject_pending(self.execution_id, "worker stopped before dispatch")
+            self.store.update(
+                self.execution_id, state="exited", result=result, exited_at=time.time()
+            )
+            self.emit("worker.exited", **result)
+
+
+def main() -> None:
+    os.umask(0o077)
+    logging.basicConfig(
+        level=logging.DEBUG, format="%(asctime)s %(levelname)s %(name)s %(message)s"
+    )
+    store, identity = Store(Path(sys.argv[1])), sys.argv[2]
+    value = store.execution(identity)
+    with FileLock(str(store.root / f"lease-{value['session_id']}.lock"), timeout=0):
+        process = psutil.Process()
+        store.update(identity, pid=process.pid, process_created_at=process.create_time())
+        asyncio.run(Worker(store, identity).run())
+
+
+if __name__ == "__main__":
+    main()

agent_runtime_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: agent-runtime-py
+Version: 0.1.0
+Summary: Reconnectable native agent workers with durable input receipts and events
+Project-URL: Repository, https://github.com/nimashoghi/agent-runtime
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: claude-agent-sdk==0.2.159
+Requires-Dist: filelock<4,>=3.16
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: psutil<8,>=7
+Requires-Dist: typed-agent-hooks<0.3,>=0.2.2
+Description-Content-Type: text/markdown
+
+# Agent runtime
+
+`agent-runtime-py` provides detached Claude Code workers that applications can reconnect to after restarting. Import it as `agent_runtime`. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
+
+This repository is under active development. The current implementation supports macOS and Linux and has been exercised with Claude Code 2.1.281 and Claude Agent SDK 0.2.159. Windows is not supported.
+
+```python
+from pathlib import Path
+from agent_runtime import ClaudeRuntime, LaunchOptions
+
+runtime = ClaudeRuntime(Path.home() / ".local/state/example/claude")
+execution = await runtime.start(
+    "Inspect this project's tests.",
+    message_id="request-123",
+    launch_id="conversation-456:request-123",
+    options=LaunchOptions(cwd=Path.cwd()),
+)
+```
+
+The default permission mode is Claude's ordinary permission behavior. Pending approvals and questions are persisted in `runtime.store.interactions(execution_id)` and remain pending until the application supplies an explicit answer. Applications must present these requests to the user; this library does not auto-approve them.
+
+## Lifetime and delivery
+
+- Each execution is a detached Python worker owning one native Claude SDK connection. Destroying the application client does not stop the worker.
+- A native session can have several executions after explicit stop and resume. A process lease prevents two managed workers from resuming it simultaneously.
+- Message IDs are idempotent within a session. Reusing an ID with different text is an error. A launch ID also fixes the initial prompt and launch configuration.
+- `accepted` means privately journaled, `dispatching` means sent or being sent, and `delivered` requires Claude to echo the exact input UUID. A crash before that acknowledgement produces `uncertain`; the runtime never silently replays that input.
+- Process identity includes PID and process creation time. Restarting a dead worker requires an explicit resume request. A process restart does not imply resubmitting previously delivered work.
+- Events have durable increasing cursors across executions. Native SDK messages are retained as `claude.message`; presentation events include `agent.message`, `agent.turn.completed`, and `work.settled`.
+- A normal turn result leaves the worker available for more requests. The idle timeout applies only when there is no active request or tracked background task or running monitor. Set it to zero to keep the worker open until explicitly stopped.
+- Private SQLite state and logs contain conversation content. Environment variables are passed to the child without being serialized into launch configuration.
+
+`runtime.stop(execution_id)` requests shutdown. `runtime.attach(execution_id)` returns an interactive resume command only after the managed worker has stopped, preventing concurrent native ownership. It must be launched from the recorded working directory.
+
+## Monitors and local peer messages
+
+Install `agent-runtime-hooks` using a typed-agent-hooks `Collection` for both providers. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
+
+`agent_runtime.operations` supplies `monitor_start`, `monitor_list`, `monitor_get`, `monitor_stop`, `monitor_events`, `agents`, and `send`. Codex operations delegate to the installed `codexr` CLI. Claude monitors run a detached foreground Bash command and retain stdout observations in SQLite; stderr goes to a private log. A 1 MiB output limit stops an overly verbose monitor. Delivery batches retain each monitor's launch permission class. Native Claude receives these as peer context and applies its own admission policy, including holding messages if permission modes require approval. `transport-written` confirms only a socket write, not admission or model processing. Interrupted writes remain uncertain and are not replayed automatically.
+
+A normal Claude monitor stops when its owning native process exits or its deadline expires. A persistent monitor has no deadline and continues collecting output after CLI exit; resuming the exact native session starts a new delivery child for pending observations. This does not keep a plain `claude -p` process open or restart processes after a host reboot. Interactive sessions and managed SDK workers receive observations between turns. A managed worker's idle timeout does not end a running monitor.
+
+Cross-session sends identify their source and never use the destination's own-event token. Unknown source permission modes fail closed. Codex receipts preserve its native delivered/queued meanings; Claude socket receipts are transport-only. Native policy or a stopped process can prevent delivery.
+
+Goals use Claude's native `/goal`, including its evaluator, retry limits and resume behavior. There is no second goal store or emulated Codex goal API. An objective can survive native resume while usage baselines reset; unrecoverable errors can clear it. See [Claude goals](https://code.claude.com/docs/en/goal).
+
+## Development
+
+Run `uv run pytest -q`. The integration tests use the real Claude Agent SDK and detached worker processes against a deterministic fake native CLI. They cover application reconnection, stop/resume, duplicate admission, lost acknowledgement, explicit permission decisions, actual shell monitor failure, process-tree shutdown, deadlines, retained observations across native-owner exit/resume, and peer permission labels. They require no model account or API credentials.
+
+Release publishing uses GitHub Actions trusted publishing. Configure a pending PyPI publisher with project `agent-runtime-py`, owner `nimashoghi`, repository `agent-runtime`, workflow `release.yml`, and environment `pypi`. Publishing a GitHub release whose tag matches `v<package-version>` builds and publishes the package.

agent_runtime_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agent_runtime/__init__.py,sha256=s8nyCGrLbrqQiLh_JDfD9hdyEv0TEZ_EPYS6TF8xIDo,177
+agent_runtime/bridge.py,sha256=YBdzf6-qgbnAToxkY-qEPVXB-STQY7CUWlQn7jRyHoM,3224
+agent_runtime/claude.py,sha256=0-NYA_fy6H2KLp-ZStbGGV3ZwK3bTLkQcnA64U_-t5E,9903
+agent_runtime/hooks.py,sha256=rR6RbC6W31sYc04n0W16zurrpSG8FacyVpA_xd52w58,2461
+agent_runtime/monitor_worker.py,sha256=CfTs6ultwMPneoNdhrwCBWUarAKl9je6Z4ahBcOg0Cg,5771
+agent_runtime/monitors.py,sha256=shCIV8q5n0fay63FM6D5BGjczDDaz29ltYFHOXfn9Co,8752
+agent_runtime/operations.py,sha256=FCWL3oj0aoByUF7NzU1lFf_-oyGkDN4pKEmOLI14qoI,4126
+agent_runtime/sessions.py,sha256=bP82Lusb2XyerIx4Pk1N4dDJAbEER74rsWG-0HS-Zko,8131
+agent_runtime/store.py,sha256=Ca0kWe4mx4zO-4-t1cBJhqtYLcV_dejhegp9_vVGN7w,11533
+agent_runtime/worker.py,sha256=b0SJ4ewYuxkX5-QNn58jznGb_3OZIxoZ6u9_JAulUtQ,12816
+agent_runtime_py-0.1.0.dist-info/METADATA,sha256=P_r8Gvk8mKWZSMBLayzZExyJFDPpRkzyY__8bt2DeJE,6553
+agent_runtime_py-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_runtime_py-0.1.0.dist-info/entry_points.txt,sha256=xM6Z54Wl_Ry4eQ835rdGJ0bz92lMXMJW8U1sJd-gkL4,65
+agent_runtime_py-0.1.0.dist-info/licenses/LICENSE,sha256=pLYhRdUXNvcg7DNLI4Ce74hsHeGEOwDXIRjVyI0MxnI,1068
+agent_runtime_py-0.1.0.dist-info/RECORD,,

agent_runtime_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_runtime_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-runtime-hooks = agent_runtime.hooks:main