agent-supervisor 0.2.0__tar.gz → 0.3.0__tar.gz

{agent_supervisor-0.2.0 → agent_supervisor-0.3.0}/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "agent-supervisor"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "futures",
  "landlock",
@@ -19,6 +19,7 @@ dependencies = [
  "thiserror 1.0.69",
  "tokio",
  "tokio-util",
+ "uuid",
  "wasmi",
  "wat",
  "windows-sys",
@@ -340,6 +341,17 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "js-sys"
+version = "0.3.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "landlock"
 version = "0.4.7"
@@ -984,6 +996,18 @@ version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ca718471876992059f251e33aafc334346ada08042b7661dd1fe313a9bced557"
 
+[[package]]
+name = "uuid"
+version = "1.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a0e2d11620c50695fe12bbbfde96b3477fe606e7284c22d505c12ce51214514"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "serde_core",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"
@@ -1014,6 +1038,50 @@ dependencies = [
  "wit-bindgen",
 ]
 
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
+dependencies = [
+ "cfg-if",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.5",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.130"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
+dependencies = [
+ "unicode-ident",
+]
+
 [[package]]
 name = "wasm-encoder"
 version = "0.262.0"

{agent_supervisor-0.2.0 → agent_supervisor-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-supervisor"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "Policy-driven process isolation and supervision for RooAGI runtimes"
@@ -19,6 +19,7 @@ tokio-util = "0.7"
 portable-pty = "0.9"
 wasmi = { version = "2", optional = true }
 serde_json = "1"
+uuid = { version = "1", features = ["v4", "serde"] }
 
 [features]
 default = []

{agent_supervisor-0.2.0 → agent_supervisor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-supervisor
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: MacOS
@@ -31,11 +31,11 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 
 Python bindings for the `agent-supervisor` native process supervisor.
 
-Version 0.2.0 source provides bounded one-shot execution and output-event
-streaming through the native Linux, macOS, and Windows backends. The latest
-published PyPI version is 0.1.2. Its wheels target Apple Silicon macOS,
-x86-64 Windows, and x86-64 Linux with glibc 2.39 or newer. The Rust crate's
-optional WASM runner is not exposed by the Python binding.
+Version 0.3.0 source provides bounded one-shot execution, output-event
+streaming, manager-owned background jobs, supervisor-scoped process IDs, and
+agent-run lifecycle management through the native Linux, macOS, and Windows
+backends. The Rust crate's optional WASM runner is not exposed by the Python
+binding.
 
 Install the published package with `python -m pip install agent-supervisor`.
 To use the current repository source, build it from this checkout:
@@ -55,9 +55,8 @@ The API and supported platform behavior are documented in
 optional stdio adapters for the official MCP Python SDK and Prefect FastMCP; see
 [`../docs/mcp.md`](../docs/mcp.md) for complete server examples and installation steps.
 
-The 0.2.0 repository source includes optional run adapters for OpenAI Agents
-SDK, Microsoft Agent Framework, LangGraph, PydanticAI, and Google ADK. The
-published PyPI package is 0.1.2 and does not include these adapters yet. From a
+The 0.3.0 source includes optional run adapters for OpenAI Agents SDK,
+Microsoft Agent Framework, LangGraph, PydanticAI, and Google ADK. From a
 checkout, install an adapter with its matching extra, for example:
 
 ```bash
@@ -66,7 +65,7 @@ python -m pip install -e '.[langgraph]'
 ```
 
 Use `openai`, `microsoft`, `pydantic-ai`, or `google-adk` for the other
-adapters. They share the Rust run scope,
+adapters. They share the Rust agent run,
 apply the same default deadline and cleanup behavior, and clean up local tool
 processes started through Agent Supervisor. Agent code remains in your app
 process. See the

{agent_supervisor-0.2.0 → agent_supervisor-0.3.0}/README.md

@@ -20,7 +20,7 @@ application remains responsible for identity, authentication, authorization,
 and orchestration. Enforcement depends on the operating system and selected
 policy; inspect the execution result and platform capabilities.
 
-The current version in this checkout is **0.2.0**.
+The current version in this checkout is **0.3.0**.
 
 ## Who it is for
 
@@ -178,7 +178,7 @@ Add the crate:
 
 ```toml
 [dependencies]
-agent-supervisor = "0.2.0"
+agent-supervisor = "0.3.0"
 ```
 
 
@@ -217,16 +217,14 @@ and [using agent SDKs](docs/api-boundaries.md) for the integration example.
 
 ## Python bindings
 
-The Python package is published on PyPI as `agent-supervisor` 0.1.2. Prebuilt
-wheels are available for Apple Silicon macOS, x86-64 Windows, and x86-64 Linux
-with glibc 2.39 or newer:
+Install the Python package from PyPI:
 
 ```bash
-python -m pip install agent-supervisor==0.1.2
+python -m pip install agent-supervisor
 ```
 
-The current repository source is 0.2.0 and can be built with maturin; it has
-not yet been published to PyPI.
+To use the current 0.3.0 source from this checkout, build it with maturin; the
+build steps are in [`python/README.md`](python/README.md).
 
 See the [Python API guide](docs/python-api.md) for capture, streaming,
 cancellation, and platform behavior.
@@ -282,7 +280,8 @@ behavior, and release notes:
 
 ## Release
 
-See the [0.2.0 release notes](docs/releases/0.2.0.md) for agent-run scopes and
+See the [0.3.0 release notes](docs/releases/0.3.0.md) for manager-owned jobs,
+supervisor-scoped process IDs, and store/resume behavior; the [0.2.0 release notes](docs/releases/0.2.0.md) cover agent-run scopes and
 MCP integrations, the [0.1.3 notes](docs/releases/0.1.3.md) for the optional WASM
 runner, the [0.1.2 notes](docs/releases/0.1.2.md) for Python bindings, and the
 [0.1.1 notes](docs/releases/0.1.1.md) for the separate OpenShell developer

agent_supervisor-0.3.0/agent_supervisor/__init__.py

@@ -0,0 +1,165 @@
+"""Python bindings for agent-supervisor."""
+
+import asyncio
+
+from ._native import (
+    CancellationToken,
+    Command,
+    OutputEvent,
+    Policy,
+    Process,
+    RunResult,
+    SupervisorProcessId,
+    SupervisorError,
+    SupervisorEvent,
+    SupervisorHandle,
+    platform_capabilities,
+    run as _run_native,
+)
+from .agent_run import AgentRun, AgentRunPolicy
+
+
+class Supervisor:
+    """Own agent runs and local child processes for the application.
+
+    Use ``start_agent_run`` to create a deadline and cleanup boundary for one
+    framework invocation. The supervisor also owns background jobs that can
+    continue between agent runs.
+    """
+
+    def __init__(self):
+        self._native = SupervisorHandle()
+
+    def start_agent_run(self, policy=None):
+        """Create one agent run owned by this supervisor."""
+        if policy is None:
+            policy = AgentRunPolicy()
+        if not isinstance(policy, AgentRunPolicy):
+            raise TypeError("policy must be an AgentRunPolicy")
+        native = self._native.start_agent_run(policy.timeout, policy.shutdown_grace)
+        return AgentRun(native, self, policy)
+
+    def active_agent_runs(self):
+        """Return the number of agent runs currently owned by this supervisor."""
+        return self._native.active_agent_runs()
+
+    def active_processes(self):
+        """Return the number of child processes registered with this supervisor."""
+        return self._native.active_processes()
+
+    async def start(self, command, *, policy=None):
+        """Start a persistent child and return its interactive Process handle."""
+        run = _current_run_context()
+        if run is not None:
+            return await run.start(command, policy=policy)
+        return await self._native.start(command, policy=policy)
+
+    def stream(self, *, run=None, process=None):
+        """Watch this supervisor's work as one ordered stream of events.
+
+        ``async for event in supervisor.stream(...)``. This only observes:
+        launch work with :func:`run`, :meth:`start`, :meth:`start_background`,
+        or a framework adapter. Stopping the watcher stops nothing, and a slow
+        watcher never slows a process.
+
+        - ``stream()`` watches everything, until the supervisor is dropped.
+        - ``stream(run=run)`` watches one agent run, including its framework
+          events, and ends when the run ends.
+        - ``stream(process=process_id)`` watches one process or background job
+          and ends when it exits.
+
+        A watcher starts with the oldest retained event, so opening one just
+        after starting work does not miss it.
+        """
+        native_run = run._native if run is not None else None
+        return self._native.stream(run=native_run, process=process)
+
+    async def start_background(self, command, *, policy=None):
+        """Start a manager-owned job and return its stable SupervisorProcessId.
+
+        Persistent jobs are stopped explicitly with ``shutdown_process`` or
+        ``shutdown_all``; ``Command.timeout`` does not end a background job.
+        The command's stdout and stderr byte limits still apply.
+        """
+        return await self._native.start_background(command, policy=policy)
+
+    def process_status(self, process_id):
+        """Return ``running``, ``completed``, ``failed``, or ``None`` if unknown."""
+        return self._native.process_status(process_id)
+
+    def process_result(self, process_id):
+        """Return a completed RunResult snapshot, or ``None`` while active/unknown."""
+        return self._native.process_result(process_id)
+
+    async def wait_process(self, process_id):
+        """Wait for a background job; return ``None`` if its ID is unknown."""
+        return await self._native.wait_process(process_id)
+
+    def take_process_result(self, process_id):
+        """Remove and return a completed result, or ``None`` if not completed."""
+        return self._native.take_process_result(process_id)
+
+    def forget_process(self, process_id):
+        """Forget a completed/failed result. Active jobs cannot be forgotten."""
+        return self._native.forget_process(process_id)
+
+    async def write_process_stdin(self, process_id, data):
+        """Write bytes to a managed job's stdin."""
+        return await self._native.write_process_stdin(process_id, data)
+
+    async def close_process_stdin(self, process_id):
+        """Close a managed job's stdin and deliver EOF."""
+        return await self._native.close_process_stdin(process_id)
+
+    async def shutdown_process(self, process_id, *, grace=5.0):
+        """Stop one process tree; return the stop request outcome string."""
+        return await self._native.shutdown_process(process_id, grace=grace)
+
+    async def shutdown_all(self, *, grace=5.0):
+        """Stop all jobs and return ``[(process_id, RunResult), ...]`` results."""
+        return await self._native.shutdown_all(grace=grace)
+
+
+def _current_run_context():
+    from ._run_context import current_run
+    return current_run()
+
+
+async def run(command, *, policy=None, input=None, cancellation=None):
+    """Run one command, collecting bounded stdout and stderr bytes."""
+    token = cancellation if cancellation is not None else CancellationToken()
+    run = _current_run_context()
+    operation = asyncio.ensure_future(
+        run.run_command(command, policy=policy, input=input) if run is not None
+        else _run_native(command, policy=policy, input=input, cancellation=token)
+    )
+    try:
+        return await asyncio.shield(operation)
+    except asyncio.CancelledError:
+        if run is not None:
+            await run.cancel()
+        else:
+            token.cancel()
+        try:
+            await asyncio.shield(operation)
+        except SupervisorError:
+            pass
+        raise
+
+
+__all__ = [
+    "CancellationToken",
+    "AgentRunPolicy",
+    "AgentRun",
+    "Command",
+    "OutputEvent",
+    "Policy",
+    "Process",
+    "RunResult",
+    "SupervisorProcessId",
+    "SupervisorError",
+    "SupervisorEvent",
+    "Supervisor",
+    "platform_capabilities",
+    "run",
+]

agent_supervisor-0.3.0/agent_supervisor/_lifecycle.py

@@ -0,0 +1,248 @@
+"""Shared lifecycle helpers for optional agent framework adapters."""
+
+import asyncio
+import inspect
+import math
+
+from .agent_run import AgentRunPolicy
+from ._run_context import active_run
+
+
+def supervision_settings(supervision):
+    if supervision is None:
+        return 300.0, 5.0
+    if not isinstance(supervision, dict):
+        raise TypeError("supervision must be a dict or None")
+    unknown = set(supervision) - {"timeout", "shutdown_grace"}
+    if unknown:
+        raise TypeError(f"unexpected supervision option: {sorted(unknown)[0]}")
+    timeout = supervision.get("timeout", 300.0)
+    grace = supervision.get("shutdown_grace", 5.0)
+    if (
+        not isinstance(timeout, (int, float))
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ValueError("timeout must be a finite positive number of seconds")
+    if not isinstance(grace, (int, float)) or not 0 <= grace <= 60:
+        raise ValueError("shutdown_grace must be between 0 and 60")
+    return float(timeout), float(grace)
+
+
+def new_run(supervision, supervisor=None):
+    timeout, grace = supervision_settings(supervision)
+    if supervisor is None:
+        from . import Supervisor
+
+        supervisor = Supervisor()
+    return supervisor.start_agent_run(AgentRunPolicy(timeout, grace))
+
+
+async def invoke_run(operation, supervision=None, supervisor=None):
+    """Call a framework operation within a run owned by ``supervisor``."""
+    run = new_run(supervision, supervisor)
+    try:
+        return await run.run(operation())
+    finally:
+        await asyncio.shield(run.cancel())
+
+
+_DONE = object()
+
+
+class AgentEventPump:
+    """Read a framework's stream in the background.
+
+    Each event is published to watchers of the run and queued for the caller,
+    so watchers see agent events whether or not the caller reads the stream.
+    The queue is unbounded because dropping events would change what the caller
+    receives; the run's deadline limits how long it can grow.
+
+    ``on_finish(exc, completed)`` runs once when reading stops, in this task.
+    """
+
+    def __init__(self, iterator, run, deadline, on_finish):
+        self._iterator = iterator
+        self._run = run
+        self._deadline = deadline
+        self._on_finish = on_finish
+        self._queue = asyncio.Queue()
+        self._stop_exc = None
+        self._task = asyncio.ensure_future(self._read())
+
+    async def _read(self):
+        token = active_run.set(self._run)
+        loop = asyncio.get_running_loop()
+        failure = None
+        completed = False
+        try:
+            while True:
+                remaining = self._deadline - loop.time()
+                if remaining <= 0:
+                    raise asyncio.TimeoutError("agent run exceeded its deadline")
+                try:
+                    event = await asyncio.wait_for(self._iterator.__anext__(), remaining)
+                except StopAsyncIteration:
+                    completed = True
+                    break
+                self._run.publish_agent_event(event)
+                self._queue.put_nowait(event)
+        except asyncio.CancelledError:
+            failure = self._stop_exc
+        except BaseException as exc:
+            failure = exc
+        finally:
+            active_run.reset(token)
+        try:
+            await self._on_finish(failure, completed)
+        except BaseException as exc:
+            failure = failure or exc
+        self._queue.put_nowait(_Failure(failure) if failure is not None else _DONE)
+
+    async def get(self):
+        """Return the next event, or raise when the stream has ended."""
+        item = await self._queue.get()
+        if item is _DONE or isinstance(item, _Failure):
+            # Keep the end marker so later reads end the same way.
+            self._queue.put_nowait(item)
+            if item is _DONE:
+                raise StopAsyncIteration
+            raise item.exc
+        return item
+
+    async def wait(self):
+        """Wait until the framework's stream has been fully read."""
+        await asyncio.gather(self._task, return_exceptions=True)
+
+    async def stop(self, exc=None):
+        """Stop reading early. Cleanup runs in the reading task."""
+        if not self._task.done():
+            self._stop_exc = exc
+            self._task.cancel()
+        await self.wait()
+
+
+class _Failure:
+    def __init__(self, exc):
+        self.exc = exc
+
+
+def run_iterator(iterator, supervision=None, on_close=None, supervisor=None):
+    """Keep a native agent run alive while a framework's stream is read."""
+    timeout, grace = supervision_settings(supervision)
+    if supervisor is None:
+        from . import Supervisor
+
+        supervisor = Supervisor()
+    run = supervisor.start_agent_run(AgentRunPolicy(timeout, grace))
+    return AgentRunAsyncIterator(iterator, run, timeout, on_close)
+
+
+def run_context_manager(open_context, supervision=None, supervisor=None):
+    """Keep a run active across ``open_context(run)``'s context manager."""
+    timeout, grace = supervision_settings(supervision)
+    run = new_run({"timeout": timeout, "shutdown_grace": grace}, supervisor)
+    return AgentRunAsyncContextManager(open_context(run), run, timeout)
+
+
+class AgentRunAsyncIterator:
+    def __init__(self, iterator, run, timeout, on_close=None):
+        self._iterator = iterator.__aiter__()
+        self._run = run
+        self.agent_run = run
+        self._on_close = on_close
+        self._closed = False
+        deadline = asyncio.get_running_loop().time() + timeout
+        self._pump = AgentEventPump(self._iterator, run, deadline, self._finish)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        try:
+            return await self._pump.get()
+        except StopAsyncIteration:
+            raise
+        except BaseException as exc:
+            await self.aclose(exc)
+            raise
+
+    async def aclose(self, exc=None):
+        await self._pump.stop(exc)
+
+    async def _finish(self, exc, completed):
+        if self._closed:
+            return
+        self._closed = True
+        token = active_run.set(self._run)
+        try:
+            if self._on_close is not None:
+                result = self._on_close(exc, completed)
+                if inspect.isawaitable(result):
+                    await result
+            close = getattr(self._iterator, "aclose", None)
+            if close is not None:
+                await close()
+        finally:
+            await asyncio.shield(self._run.cancel())
+            active_run.reset(token)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, traceback):
+        await self.aclose(exc)
+
+
+class AgentRunAsyncContextManager:
+    """Keep the run active across a native async context manager's body."""
+
+    def __init__(self, context_manager, run, timeout):
+        self._context_manager = context_manager
+        self._run = run
+        self.agent_run = run
+        self._timeout = timeout
+        self._token = None
+        self._timeout_context = None
+        self._entered = False
+        self._task = None
+        self._timer = None
+        self._expired = False
+
+    async def __aenter__(self):
+        self._token = active_run.set(self._run)
+        self._task = asyncio.current_task()
+        self._timer = asyncio.get_running_loop().call_later(
+            self._timeout, self._expire
+        )
+        try:
+            result = await self._context_manager.__aenter__()
+            self._entered = True
+            return result
+        except BaseException as exc:
+            await self._finish(type(exc), exc, exc.__traceback__)
+            raise
+
+    async def __aexit__(self, exc_type, exc, traceback):
+        return await self._finish(exc_type, exc, traceback)
+
+    async def _finish(self, exc_type, exc, traceback):
+        suppress = False
+        try:
+            if self._entered:
+                suppress = await self._context_manager.__aexit__(exc_type, exc, traceback)
+        finally:
+            if self._timer is not None:
+                self._timer.cancel()
+            if self._token is not None:
+                active_run.reset(self._token)
+                self._token = None
+            await asyncio.shield(self._run.cancel())
+        if self._expired and exc_type is asyncio.CancelledError:
+            raise asyncio.TimeoutError("agent run exceeded its deadline") from None
+        return suppress
+
+    def _expire(self):
+        self._expired = True
+        if self._task is not None:
+            self._task.cancel()

agent_supervisor-0.3.0/agent_supervisor/_run_context.py

@@ -0,0 +1,11 @@
+"""Context shared by framework adapters and supervised local tools."""
+
+from contextvars import ContextVar
+
+
+active_run = ContextVar("agent_supervisor_run_context", default=None)
+
+
+def current_run():
+    """Return the agent run active in this async context, if any."""
+    return active_run.get()