runfence 0.1.1__tar.gz

runfence-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naveen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runfence-0.1.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: runfence
+Version: 0.1.1
+Summary: Cancel, deadline and budget limits for agent runs that actually stop the work
+Author: Naveen
+License: MIT
+Project-URL: Homepage, https://github.com/Chenjigaram/runfence
+Project-URL: Source, https://github.com/Chenjigaram/runfence
+Keywords: agents,llm,cancellation,timeout,budget,asyncio,adk,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# runfence
+
+Cancel, deadline and budget limits for agent runs — that actually stop the work.
+
+Every agent framework hands you an async generator of events. When you stop consuming
+it, the work it started **keeps running**. Model calls keep streaming, tools keep
+executing, and you keep paying. `break` does not mean stop.
+
+```python
+from runfence import run_scope, Cancelled
+
+scope = run_scope(deadline=30, tokens=50_000, usd=0.25)
+
+async with scope:
+    try:
+        async for event in scope.stream(runner.run_async(...)):
+            handle(event)
+    except Cancelled:
+        ...          # scope.cancel() was called, from anywhere
+```
+
+`scope.stream()` takes any async iterator, so it works with whatever framework produced
+it. There is no adapter to install and nothing to register.
+
+## What it costs to get this wrong
+
+Cancelling a real streaming run against `llama-3.3-70b`, two runs on different days:
+
+| | Wall clock | Events |
+|---|---|---|
+| Run to completion | 262.3s / 42.6s | 1369 / 1366 |
+| `scope.cancel()` at 1.5s | **1.8s / 1.5s** | 1 |
+
+The completion time swings with provider load, which is the point: you cannot predict
+how long a run will take, so the ceiling has to be enforced rather than assumed. No
+framework tasks were left alive after cancelling in either run.
+
+Reproduce it with `examples/live_cancel.py`, or see the mechanism with no API key at all:
+
+```bash
+python examples/stop_means_stop.py
+```
+
+```
+  break + aclose()      -> tools that still finished: ['search', 'summarise', 'draft']
+  inside a run_scope    -> tools that still finished: none
+  anything left behind? no
+```
+
+## Limits
+
+```python
+scope = run_scope(
+    deadline=30,        # seconds of wall clock for the whole run
+    tokens=50_000,      # stop once this many tokens are spent
+    usd=0.25,           # stop once this much money is spent
+)
+```
+
+Usage has to come from somewhere, so tell the scope how to read it off an event:
+
+```python
+async for event in scope.stream(source, usage=lambda e: {"tokens": e.usage.total_tokens}):
+    ...
+```
+
+Stopping raises, and the exception carries what was spent:
+
+```python
+except BudgetExceeded as stopped:
+    log.warning("stopped after %.1fs and %d tokens", stopped.elapsed, stopped.tokens)
+```
+
+`Cancelled`, `DeadlineExceeded` and `BudgetExceeded` all derive from `RunStopped`.
+
+## Work started inside the scope
+
+Anything spawned through the scope is cancelled with it:
+
+```python
+async with run_scope(deadline=10) as scope:
+    scope.spawn(background_tool())
+    async for event in scope.stream(source):
+        ...
+```
+
+Anything spawned *outside* it cannot be cancelled by it — but it is reported rather
+than ignored:
+
+```python
+print(scope.leaked)   # names of tasks still running when the scope closed
+```
+
+That list is the honest answer to "did my framework clean up?", and it is usually the
+first thing you want to know when a run refuses to die.
+
+## Why this exists
+
+Stopping an agent is unsolved across the ecosystem, not in one framework:
+
+- google/adk-python — 52 reactions across its three top cancellation issues, the oldest
+  open since August 2025, with three community PRs unmerged
+- langchain-ai/langgraph — 25 open issues mentioning cancel, interrupt or abort; the
+  most discussed is about cancellation losing state that was not yet checkpointed
+- strands-agents — 21 open issues on the same theme
+
+## What it does not do
+
+- It cannot cancel work a framework spawned as an orphan task. Nothing outside that
+  framework can. It detects and reports those instead, in `scope.leaked`.
+- It does not price tokens. Pass `usd` yourself, from your provider's numbers or a
+  library like `tokencost`.
+- Verified against the OpenAI Agents SDK on real streaming traffic. Google ADK exposes
+  the same async-generator shape and is expected to work, but is **not yet tested**.
+
+## Install
+
+```bash
+pip install runfence
+```
+
+No dependencies. Python 3.11+ (it uses `asyncio.timeout` semantics and modern task APIs).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```

runfence-0.1.1/README.md

@@ -0,0 +1,130 @@
+# runfence
+
+Cancel, deadline and budget limits for agent runs — that actually stop the work.
+
+Every agent framework hands you an async generator of events. When you stop consuming
+it, the work it started **keeps running**. Model calls keep streaming, tools keep
+executing, and you keep paying. `break` does not mean stop.
+
+```python
+from runfence import run_scope, Cancelled
+
+scope = run_scope(deadline=30, tokens=50_000, usd=0.25)
+
+async with scope:
+    try:
+        async for event in scope.stream(runner.run_async(...)):
+            handle(event)
+    except Cancelled:
+        ...          # scope.cancel() was called, from anywhere
+```
+
+`scope.stream()` takes any async iterator, so it works with whatever framework produced
+it. There is no adapter to install and nothing to register.
+
+## What it costs to get this wrong
+
+Cancelling a real streaming run against `llama-3.3-70b`, two runs on different days:
+
+| | Wall clock | Events |
+|---|---|---|
+| Run to completion | 262.3s / 42.6s | 1369 / 1366 |
+| `scope.cancel()` at 1.5s | **1.8s / 1.5s** | 1 |
+
+The completion time swings with provider load, which is the point: you cannot predict
+how long a run will take, so the ceiling has to be enforced rather than assumed. No
+framework tasks were left alive after cancelling in either run.
+
+Reproduce it with `examples/live_cancel.py`, or see the mechanism with no API key at all:
+
+```bash
+python examples/stop_means_stop.py
+```
+
+```
+  break + aclose()      -> tools that still finished: ['search', 'summarise', 'draft']
+  inside a run_scope    -> tools that still finished: none
+  anything left behind? no
+```
+
+## Limits
+
+```python
+scope = run_scope(
+    deadline=30,        # seconds of wall clock for the whole run
+    tokens=50_000,      # stop once this many tokens are spent
+    usd=0.25,           # stop once this much money is spent
+)
+```
+
+Usage has to come from somewhere, so tell the scope how to read it off an event:
+
+```python
+async for event in scope.stream(source, usage=lambda e: {"tokens": e.usage.total_tokens}):
+    ...
+```
+
+Stopping raises, and the exception carries what was spent:
+
+```python
+except BudgetExceeded as stopped:
+    log.warning("stopped after %.1fs and %d tokens", stopped.elapsed, stopped.tokens)
+```
+
+`Cancelled`, `DeadlineExceeded` and `BudgetExceeded` all derive from `RunStopped`.
+
+## Work started inside the scope
+
+Anything spawned through the scope is cancelled with it:
+
+```python
+async with run_scope(deadline=10) as scope:
+    scope.spawn(background_tool())
+    async for event in scope.stream(source):
+        ...
+```
+
+Anything spawned *outside* it cannot be cancelled by it — but it is reported rather
+than ignored:
+
+```python
+print(scope.leaked)   # names of tasks still running when the scope closed
+```
+
+That list is the honest answer to "did my framework clean up?", and it is usually the
+first thing you want to know when a run refuses to die.
+
+## Why this exists
+
+Stopping an agent is unsolved across the ecosystem, not in one framework:
+
+- google/adk-python — 52 reactions across its three top cancellation issues, the oldest
+  open since August 2025, with three community PRs unmerged
+- langchain-ai/langgraph — 25 open issues mentioning cancel, interrupt or abort; the
+  most discussed is about cancellation losing state that was not yet checkpointed
+- strands-agents — 21 open issues on the same theme
+
+## What it does not do
+
+- It cannot cancel work a framework spawned as an orphan task. Nothing outside that
+  framework can. It detects and reports those instead, in `scope.leaked`.
+- It does not price tokens. Pass `usd` yourself, from your provider's numbers or a
+  library like `tokencost`.
+- Verified against the OpenAI Agents SDK on real streaming traffic. Google ADK exposes
+  the same async-generator shape and is expected to work, but is **not yet tested**.
+
+## Install
+
+```bash
+pip install runfence
+```
+
+No dependencies. Python 3.11+ (it uses `asyncio.timeout` semantics and modern task APIs).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```

runfence-0.1.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "runfence"
+version = "0.1.1"
+description = "Cancel, deadline and budget limits for agent runs that actually stop the work"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Naveen" }]
+keywords = ["agents", "llm", "cancellation", "timeout", "budget", "asyncio", "adk", "langgraph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Framework :: AsyncIO",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/Chenjigaram/runfence"
+Source = "https://github.com/Chenjigaram/runfence"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 110
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

runfence-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runfence-0.1.1/src/runfence/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .budget import Budget, Usage
+from .errors import BudgetExceeded, Cancelled, DeadlineExceeded, RunStopped
+from .scope import RunScope, run_scope
+
+__version__ = "0.1.0"
+__all__ = ["Budget", "Usage", "RunScope", "run_scope", "RunStopped",
+           "Cancelled", "DeadlineExceeded", "BudgetExceeded"]

runfence-0.1.1/src/runfence/budget.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Usage:
+    """What a run has spent so far."""
+
+    tokens: int = 0
+    usd: float = 0.0
+
+    def add(self, tokens: int = 0, usd: float = 0.0) -> None:
+        if tokens < 0 or usd < 0:
+            raise ValueError("usage cannot decrease")
+        self.tokens += tokens
+        self.usd += usd
+
+
+@dataclass(frozen=True)
+class Budget:
+    """A ceiling for one run. None means no limit for that dimension."""
+
+    tokens: int | None = None
+    usd: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.tokens is not None and self.tokens <= 0:
+            raise ValueError("token budget must be positive")
+        if self.usd is not None and self.usd <= 0:
+            raise ValueError("cost budget must be positive")
+
+    def exceeded_by(self, usage: Usage) -> str | None:
+        if self.tokens is not None and usage.tokens > self.tokens:
+            return f"token budget spent: {usage.tokens} > {self.tokens}"
+        if self.usd is not None and usage.usd > self.usd:
+            return f"cost budget spent: ${usage.usd:.4f} > ${self.usd:.2f}"
+        return None
+
+    @property
+    def unlimited(self) -> bool:
+        return self.tokens is None and self.usd is None

runfence-0.1.1/src/runfence/errors.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+class RunStopped(Exception):
+    """Base for every reason a run was stopped by the scope rather than by finishing."""
+
+    def __init__(self, message: str, *, elapsed: float, tokens: int, usd: float) -> None:
+        super().__init__(message)
+        self.elapsed = elapsed
+        self.tokens = tokens
+        self.usd = usd
+
+
+class Cancelled(RunStopped):
+    """cancel() was called."""
+
+
+class DeadlineExceeded(RunStopped):
+    """The wall-clock deadline passed."""
+
+
+class BudgetExceeded(RunStopped):
+    """The token or cost budget was spent."""

runfence-0.1.1/src/runfence/scope.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+
+from .budget import Budget, Usage
+from .errors import BudgetExceeded, Cancelled, DeadlineExceeded
+
+
+class RunScope:
+    """A boundary around one agent run: it can be stopped, and it stops for real.
+
+    Abandoning an async generator does not stop work the generator started; those tasks
+    keep running, and for an agent that means live model calls that still cost money.
+    Work spawned through this scope is cancelled with it, and anything left behind is
+    reported rather than ignored.
+    """
+
+    def __init__(self, deadline: float | None = None, budget: Budget | None = None) -> None:
+        if deadline is not None and deadline <= 0:
+            raise ValueError("deadline must be positive")
+        self.deadline = deadline
+        self.budget = budget or Budget()
+        self.usage = Usage()
+        self.leaked: list[str] = []
+        self._started: float | None = None
+        self._stop = asyncio.Event()
+        self._reason = ""
+        self._children: set[asyncio.Task[Any]] = set()
+        self._known: set[asyncio.Task[Any]] = set()
+
+    # ---- lifecycle -------------------------------------------------------
+
+    async def __aenter__(self) -> RunScope:
+        self._started = time.monotonic()
+        self._known = set(asyncio.all_tasks())
+        return self
+
+    async def __aexit__(self, *exc: object) -> bool:
+        for task in list(self._children):
+            if not task.done():
+                task.cancel()
+        if self._children:
+            await asyncio.gather(*self._children, return_exceptions=True)
+        strays = [t for t in asyncio.all_tasks()
+                  if t not in self._known and t not in self._children
+                  and not t.done() and t is not asyncio.current_task()]
+        self.leaked = [t.get_name() for t in strays]
+        return False
+
+    # ---- controls --------------------------------------------------------
+
+    def spawn(self, coro: Any) -> asyncio.Task[Any]:
+        """Run child work inside the scope so cancelling the scope cancels it too."""
+        task = asyncio.ensure_future(coro)
+        self._children.add(task)
+        task.add_done_callback(self._children.discard)
+        return task
+
+    def cancel(self, reason: str = "cancelled by caller") -> None:
+        """Stop the run. Safe to call from another task."""
+        self._reason = reason
+        self._stop.set()
+
+    @property
+    def elapsed(self) -> float:
+        return 0.0 if self._started is None else time.monotonic() - self._started
+
+    @property
+    def remaining(self) -> float | None:
+        return None if self.deadline is None else self.deadline - self.elapsed
+
+    def record(self, tokens: int = 0, usd: float = 0.0) -> None:
+        """Add usage and stop the run if that puts it over budget."""
+        self.usage.add(tokens=tokens, usd=usd)
+        breach = self.budget.exceeded_by(self.usage)
+        if breach:
+            raise self._stopped(BudgetExceeded, breach)
+
+    # ---- consumption -----------------------------------------------------
+
+    async def stream(
+        self,
+        source: AsyncIterator[Any],
+        usage: Callable[[Any], dict[str, Any]] | None = None,
+    ) -> AsyncIterator[Any]:
+        """Yield from `source` while enforcing cancellation, deadline and budget.
+
+        The deadline is applied to each wait for the next item rather than wrapped
+        around the yields, because a timeout that fires while a generator is suspended
+        is delivered to whoever happens to be running it.
+        """
+        iterator = source.__aiter__()
+        waiter = asyncio.ensure_future(self._stop.wait())
+        try:
+            while True:
+                left = self.remaining
+                if left is not None and left <= 0:
+                    raise self._stopped(DeadlineExceeded, f"deadline of {self.deadline}s passed")
+                step = asyncio.ensure_future(iterator.__anext__())
+                done, _ = await asyncio.wait({step, waiter}, timeout=left,
+                                             return_when=asyncio.FIRST_COMPLETED)
+                if waiter in done:
+                    step.cancel()
+                    await asyncio.gather(step, return_exceptions=True)
+                    raise self._stopped(Cancelled, self._reason)
+                if step not in done:
+                    step.cancel()
+                    await asyncio.gather(step, return_exceptions=True)
+                    raise self._stopped(DeadlineExceeded, f"deadline of {self.deadline}s passed")
+                try:
+                    item = step.result()
+                except StopAsyncIteration:
+                    return
+                if usage is not None:
+                    self.record(**usage(item))
+                yield item
+        finally:
+            waiter.cancel()
+            closer = getattr(source, "aclose", None)
+            if closer is not None:
+                await closer()
+
+    # ---- internals -------------------------------------------------------
+
+    def _stopped(self, kind: type, message: str):
+        return kind(message, elapsed=self.elapsed, tokens=self.usage.tokens, usd=self.usage.usd)
+
+
+def run_scope(deadline: float | None = None, tokens: int | None = None,
+              usd: float | None = None) -> RunScope:
+    """A scope with a deadline in seconds and optional token and cost ceilings."""
+    return RunScope(deadline=deadline, budget=Budget(tokens=tokens, usd=usd))

runfence-0.1.1/src/runfence.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: runfence
+Version: 0.1.1
+Summary: Cancel, deadline and budget limits for agent runs that actually stop the work
+Author: Naveen
+License: MIT
+Project-URL: Homepage, https://github.com/Chenjigaram/runfence
+Project-URL: Source, https://github.com/Chenjigaram/runfence
+Keywords: agents,llm,cancellation,timeout,budget,asyncio,adk,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# runfence
+
+Cancel, deadline and budget limits for agent runs — that actually stop the work.
+
+Every agent framework hands you an async generator of events. When you stop consuming
+it, the work it started **keeps running**. Model calls keep streaming, tools keep
+executing, and you keep paying. `break` does not mean stop.
+
+```python
+from runfence import run_scope, Cancelled
+
+scope = run_scope(deadline=30, tokens=50_000, usd=0.25)
+
+async with scope:
+    try:
+        async for event in scope.stream(runner.run_async(...)):
+            handle(event)
+    except Cancelled:
+        ...          # scope.cancel() was called, from anywhere
+```
+
+`scope.stream()` takes any async iterator, so it works with whatever framework produced
+it. There is no adapter to install and nothing to register.
+
+## What it costs to get this wrong
+
+Cancelling a real streaming run against `llama-3.3-70b`, two runs on different days:
+
+| | Wall clock | Events |
+|---|---|---|
+| Run to completion | 262.3s / 42.6s | 1369 / 1366 |
+| `scope.cancel()` at 1.5s | **1.8s / 1.5s** | 1 |
+
+The completion time swings with provider load, which is the point: you cannot predict
+how long a run will take, so the ceiling has to be enforced rather than assumed. No
+framework tasks were left alive after cancelling in either run.
+
+Reproduce it with `examples/live_cancel.py`, or see the mechanism with no API key at all:
+
+```bash
+python examples/stop_means_stop.py
+```
+
+```
+  break + aclose()      -> tools that still finished: ['search', 'summarise', 'draft']
+  inside a run_scope    -> tools that still finished: none
+  anything left behind? no
+```
+
+## Limits
+
+```python
+scope = run_scope(
+    deadline=30,        # seconds of wall clock for the whole run
+    tokens=50_000,      # stop once this many tokens are spent
+    usd=0.25,           # stop once this much money is spent
+)
+```
+
+Usage has to come from somewhere, so tell the scope how to read it off an event:
+
+```python
+async for event in scope.stream(source, usage=lambda e: {"tokens": e.usage.total_tokens}):
+    ...
+```
+
+Stopping raises, and the exception carries what was spent:
+
+```python
+except BudgetExceeded as stopped:
+    log.warning("stopped after %.1fs and %d tokens", stopped.elapsed, stopped.tokens)
+```
+
+`Cancelled`, `DeadlineExceeded` and `BudgetExceeded` all derive from `RunStopped`.
+
+## Work started inside the scope
+
+Anything spawned through the scope is cancelled with it:
+
+```python
+async with run_scope(deadline=10) as scope:
+    scope.spawn(background_tool())
+    async for event in scope.stream(source):
+        ...
+```
+
+Anything spawned *outside* it cannot be cancelled by it — but it is reported rather
+than ignored:
+
+```python
+print(scope.leaked)   # names of tasks still running when the scope closed
+```
+
+That list is the honest answer to "did my framework clean up?", and it is usually the
+first thing you want to know when a run refuses to die.
+
+## Why this exists
+
+Stopping an agent is unsolved across the ecosystem, not in one framework:
+
+- google/adk-python — 52 reactions across its three top cancellation issues, the oldest
+  open since August 2025, with three community PRs unmerged
+- langchain-ai/langgraph — 25 open issues mentioning cancel, interrupt or abort; the
+  most discussed is about cancellation losing state that was not yet checkpointed
+- strands-agents — 21 open issues on the same theme
+
+## What it does not do
+
+- It cannot cancel work a framework spawned as an orphan task. Nothing outside that
+  framework can. It detects and reports those instead, in `scope.leaked`.
+- It does not price tokens. Pass `usd` yourself, from your provider's numbers or a
+  library like `tokencost`.
+- Verified against the OpenAI Agents SDK on real streaming traffic. Google ADK exposes
+  the same async-generator shape and is expected to work, but is **not yet tested**.
+
+## Install
+
+```bash
+pip install runfence
+```
+
+No dependencies. Python 3.11+ (it uses `asyncio.timeout` semantics and modern task APIs).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```

runfence-0.1.1/src/runfence.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/runfence/__init__.py
+src/runfence/budget.py
+src/runfence/errors.py
+src/runfence/scope.py
+src/runfence.egg-info/PKG-INFO
+src/runfence.egg-info/SOURCES.txt
+src/runfence.egg-info/dependency_links.txt
+src/runfence.egg-info/requires.txt
+src/runfence.egg-info/top_level.txt
+tests/test_scope.py

runfence-0.1.1/src/runfence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runfence-0.1.1/src/runfence.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7
+pytest-asyncio>=0.23
+ruff>=0.4

runfence-0.1.1/src/runfence.egg-info/top_level.txt

@@ -0,0 +1 @@
+runfence

runfence-0.1.1/tests/test_scope.py

@@ -0,0 +1,146 @@
+import asyncio
+
+import pytest
+
+from runfence import (
+    Budget,
+    BudgetExceeded,
+    Cancelled,
+    DeadlineExceeded,
+    RunScope,
+    run_scope,
+)
+
+
+async def ticker(n=10, delay=0.01, spawn=None, work=None):
+    """Stands in for an agent run: yields events and may start background work."""
+    if spawn is not None:
+        for i in range(3):
+            spawn(work(i))
+    for i in range(n):
+        await asyncio.sleep(delay)
+        yield {"step": i, "tokens": 100}
+
+
+@pytest.mark.asyncio
+async def test_work_started_in_the_scope_stops_with_it():
+    """The regression case: abandoning a generator normally leaves its work running."""
+    finished = []
+
+    async def slow(i):
+        await asyncio.sleep(1)
+        finished.append(i)
+
+    async with run_scope() as scope:
+        async for event in scope.stream(ticker(spawn=scope.spawn, work=slow)):
+            if event["step"] == 1:
+                break
+    await asyncio.sleep(1.2)
+    assert finished == []
+
+
+@pytest.mark.asyncio
+async def test_without_the_scope_the_same_work_leaks():
+    """Documents why the scope exists; this is plain asyncio behaviour."""
+    finished = []
+
+    async def slow(i):
+        await asyncio.sleep(0.3)
+        finished.append(i)
+
+    gen = ticker(spawn=asyncio.ensure_future, work=slow)
+    async for event in gen:
+        if event["step"] == 1:
+            break
+    await gen.aclose()
+    await asyncio.sleep(0.5)
+    assert finished == [0, 1, 2]
+
+
+@pytest.mark.asyncio
+async def test_cancel_stops_the_stream():
+    scope = run_scope()
+
+    async def stopper():
+        await asyncio.sleep(0.05)
+        scope.cancel("user pressed stop")
+
+    async with scope:
+        asyncio.ensure_future(stopper())
+        with pytest.raises(Cancelled, match="user pressed stop"):
+            async for _ in scope.stream(ticker(n=100)):
+                pass
+
+
+@pytest.mark.asyncio
+async def test_deadline_stops_the_stream():
+    async with run_scope(deadline=0.08) as scope:
+        with pytest.raises(DeadlineExceeded):
+            async for _ in scope.stream(ticker(n=100, delay=0.02)):
+                pass
+
+
+@pytest.mark.asyncio
+async def test_token_budget_stops_the_stream():
+    async with run_scope(tokens=250) as scope:
+        with pytest.raises(BudgetExceeded, match="token budget"):
+            async for _ in scope.stream(ticker(n=100), usage=lambda e: {"tokens": e["tokens"]}):
+                pass
+    assert scope.usage.tokens == 300
+
+
+@pytest.mark.asyncio
+async def test_cost_budget_stops_the_stream():
+    async with run_scope(usd=0.02) as scope:
+        with pytest.raises(BudgetExceeded, match="cost budget"):
+            async for _ in scope.stream(ticker(n=100), usage=lambda e: {"usd": 0.01}):
+                pass
+
+
+@pytest.mark.asyncio
+async def test_a_run_inside_its_limits_completes():
+    async with run_scope(deadline=5, tokens=10_000) as scope:
+        seen = [e async for e in scope.stream(ticker(n=3), usage=lambda e: {"tokens": e["tokens"]})]
+    assert len(seen) == 3
+    assert scope.usage.tokens == 300
+
+
+@pytest.mark.asyncio
+async def test_stopping_reports_what_was_spent():
+    async with run_scope(tokens=150) as scope:
+        try:
+            async for _ in scope.stream(ticker(n=10), usage=lambda e: {"tokens": e["tokens"]}):
+                pass
+        except BudgetExceeded as stopped:
+            assert stopped.tokens == 200
+            assert stopped.elapsed > 0
+
+
+@pytest.mark.asyncio
+async def test_tasks_left_running_outside_the_scope_are_reported():
+    async def stray():
+        await asyncio.sleep(5)
+
+    async with run_scope() as scope:
+        task = asyncio.ensure_future(stray())      # deliberately not scope.spawn
+        await asyncio.sleep(0.01)
+    assert scope.leaked, "a task started outside the scope should be reported"
+    task.cancel()
+
+
+def test_budget_rejects_nonsense():
+    with pytest.raises(ValueError):
+        Budget(tokens=0)
+    with pytest.raises(ValueError):
+        Budget(usd=-1)
+
+
+def test_deadline_must_be_positive():
+    with pytest.raises(ValueError):
+        RunScope(deadline=0)
+
+
+def test_usage_cannot_decrease():
+    scope = RunScope()
+    with pytest.raises(ValueError):
+        scope.record(tokens=-5)