agentic-runner 3.6.0__tar.gz → 3.7.0__tar.gz

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.6.0
+Version: 3.7.0
 Summary: The Agentic OS Runner: an activity-only Temporal executor for workspaces, Agent Runtimes and verb seams
 License-Expression: AGPL-3.0-only
 License-File: LICENSE

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/__init__.py

@@ -7,6 +7,6 @@ stay on the platform; this package imports none of them, and a CI partition test
 (``tests/test_package_partition.py``) fails the build if that changes.
 """
 
-__version__ = "3.6.0"
+__version__ = "3.7.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/activities.py

@@ -118,6 +118,7 @@ from agentic_runner.message_store import MessageStore, WorkflowSignaller
 from agentic_runner.registration import RunnerRegistrationError
 from agentic_runner.runtime import verifier_command
 from agentic_runner.runtime.verifier_command import CommandValidationError
+from agentic_runner.usage_windows import UsageWindows
 from agentic_runner.workers._runtime_support import (
     RESERVED_DIRECTIVE_ENV,
     bound_text,
@@ -174,6 +175,7 @@ from agentic_runner_contracts.activity_io import (
     GitHubCallError,
     GitHubCallFailure,
     HarnessHold,
+    HarnessHoldKind,
     LearningDirectiveInput,
     LearningDirectiveOutput,
     MemberDirectiveInput,
@@ -1616,10 +1618,13 @@ class RunnerRalphActivities:
         tool_server_health: ToolServerHealthLog | None = None,
         attempt_records: AttemptRecords | None = None,
         directives_in_flight: DirectivesInFlight | None = None,
+        usage_windows: UsageWindows | None = None,
     ) -> None:
         self._fastapi_client = fastapi_client
         # Read by the harness self-test, which never runs beside a Contract's Directive.
         self._directives_in_flight = directives_in_flight or DirectivesInFlight()
+        # Local-agents 10: None off a user-hosted Runner, which reports no usage windows.
+        self._usage_windows = usage_windows
         # Wall-clock source for per-Directive runtime, accrued against the Budget's
         # wall-clock dimension (ADR-0007). Activities run outside the Temporal sandbox,
         # so a real monotonic clock is allowed here (it must never be used in the
@@ -5273,6 +5278,13 @@ class RunnerRalphActivities:
             error=result.error,
             now=datetime.now(UTC),
         )
+        if self._usage_windows is not None and runtime_state.contract_id:
+            self._usage_windows.after_directive(
+                runtime_state.contract_id,
+                runtime_state.cli_kind,
+                result.usage_windows,
+                usage_limit=hold is not None and hold.kind == HarnessHoldKind.USAGE_LIMIT,
+            )
         if hold is None:
             return None
         await self._fastapi_client.append_evidence(

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/service.py

@@ -98,6 +98,12 @@ from agentic_runner.sealed_box import (
 )
 from agentic_runner.tiny_http import HttpRequest, read_request, write_json
 from agentic_runner.triage_activities import RunnerTriageActivities
+from agentic_runner.usage_windows import (
+    ClaudeUsageScreenProbe,
+    CodexRateLimitsProbe,
+    UsageWindowProbe,
+    UsageWindows,
+)
 from agentic_runner.user_sources import ProxyTriage, UserSourcePoller
 from agentic_runner.workers.acp_runtime import ACP_BRIDGES, AcpRuntime
 from agentic_runner.workers.agent_runtime import AgentRuntime
@@ -581,6 +587,8 @@ class ControlPlaneStream:
     runtimes: Mapping[str, AgentRuntime] = field(default_factory=dict)
     contracts: ContractIsolation | None = None
     self_tests: HarnessSelfTests | None = None
+    # Local-agents 10: each subscription's usage windows; None off a user-hosted Runner.
+    usage_windows: UsageWindows | None = None
     # Local-agents 04b: which delivered references fill the LLM proxy's slot, and where.
     llm_slots: Mapping[str, LlmProvider] = field(default_factory=lambda: dict(LLM_SLOT_REFERENCES))
     # Local-agents 05: the Claude Code sign-ins a relayed code is typed into.
@@ -653,6 +661,11 @@ class ControlPlaneStream:
                 if self.self_tests is not None
                 else None
             ),
+            usage_windows=(
+                self.usage_windows.windows(contract_id, cli_kind)
+                if self.usage_windows is not None and not delivered
+                else None
+            ),
         )
 
     async def directive_token(self, directive_id: str) -> str:
@@ -1016,6 +1029,9 @@ async def _serve_registered(
         served=runtimes,
         monotonic=time.monotonic,
     )
+    usage_windows = build_usage_windows(
+        host_party=state.host_party, runtimes=runtimes, isolation=isolation, in_flight=in_flight
+    )
     stream = ControlPlaneStream(
         client=RunnerRegistrationClient(base_url=control_plane, client=http_client),
         state=state,
@@ -1043,6 +1059,7 @@ async def _serve_registered(
         runtimes=runtimes,
         contracts=isolation,
         self_tests=self_tests,
+        usage_windows=usage_windows,
     )
     stream.sources = UserSourcePoller(
         stream=SignedIntakeStream(stream.client, state),
@@ -1104,6 +1121,7 @@ async def _serve_registered(
                 messages=messages,
                 tool_servers=tool_servers,
                 sign_ins=sign_ins,
+                usage_windows=usage_windows,
                 # The wake signal rides the connection this process polls with: one
                 # namespace, the Organisation's own (PRD issue 52, map ticket 15 §2).
                 signaller=TemporalWorkflowSignaller(client),
@@ -1121,13 +1139,20 @@ async def _serve_registered(
         self_test = asyncio.create_task(
             _self_test_forever(self_tests, isolation, SELF_TEST_SWEEP_SECONDS)
         )
+        sweeps = [beat, poll, self_test]
+        if usage_windows is not None:
+            sweeps.append(
+                asyncio.create_task(
+                    _usage_windows_forever(usage_windows, isolation, proxy, SELF_TEST_SWEEP_SECONDS)
+                )
+            )
         readiness.ready = True
         await run_runner_lifecycle_hook(hooks, HookName.RUNNER_STARTUP)
         try:
             await run_worker_until_terminated(worker, stop=stop)
         finally:
             readiness.ready = False
-            for task in (beat, poll, self_test):
+            for task in sweeps:
                 task.cancel()
                 with contextlib.suppress(asyncio.CancelledError):
                     await task
@@ -1227,6 +1252,56 @@ async def _self_test_forever(
         await asyncio.sleep(interval)
 
 
+def build_usage_windows(
+    *,
+    host_party: str,
+    runtimes: Mapping[str, AgentRuntime],
+    isolation: ContractIsolation,
+    in_flight: DirectivesInFlight,
+) -> UsageWindows | None:
+    """A probe per served harness, or None off a user-hosted Runner (local-agents 10).
+
+    Subscriptions follow the person (local-agents 04): only a user-hosted Runner runs one,
+    so only there is a usage window anyone's to read.
+    """
+
+    if host_party != "user":
+        return None
+    probes: dict[str, UsageWindowProbe] = {
+        "codex_cli": CodexRateLimitsProbe(),
+        "claude_code": ClaudeUsageScreenProbe(),
+    }
+    return UsageWindows(
+        probes={kind: probe for kind, probe in probes.items() if kind in runtimes},
+        sandbox_for=lambda contract_id, cli_kind: isolation.existing_sandbox(
+            contract_id, runtime_kind=cli_kind
+        ),
+        in_flight=in_flight,
+        monotonic=time.monotonic,
+    )
+
+
+async def _usage_windows_forever(
+    usage_windows: UsageWindows, isolation: ContractIsolation, proxy: LlmProxy, interval: float
+) -> None:
+    """Each signed-in harness root's usage windows, whenever its probe falls due
+    (local-agents 10). A root with a delivered key runs on the proxy, not a subscription."""
+
+    while True:
+        delivered = {
+            (str(slot.contract_id), slot.runtime_kind)
+            for slot in proxy.slots.statuses()
+            if slot.present
+        }
+        try:
+            await usage_windows.run_due(
+                [root for root in isolation.harness_roots() if root not in delivered]
+            )
+        except Exception as error:  # noqa: BLE001 - a lost sweep is retried on the next one
+            _logger.warning("usage window sweep failed: %s", error)
+        await asyncio.sleep(interval)
+
+
 def _activities(
     fastapi: RunnerFastApiClient,
     *,
@@ -1245,6 +1320,7 @@ def _activities(
     signaller: TemporalWorkflowSignaller | None = None,
     tool_servers: ToolServerHealthLog | None = None,
     sign_ins: ClaudeSignIns | None = None,
+    usage_windows: UsageWindows | None = None,
 ) -> list[Callable[..., Any]]:
     github_client = GitHubAppClient(
         app_id=os.getenv("GITHUB_APP_ID"),
@@ -1292,6 +1368,7 @@ def _activities(
         tool_server_health=tool_servers,
         attempt_records=attempt_records,
         directives_in_flight=directives_in_flight,
+        usage_windows=usage_windows,
     )
     return [
         *ralph.activity_callables(),

agentic_runner-3.7.0/src/agentic_runner/usage_windows.py

@@ -0,0 +1,529 @@
+"""How much of each subscription usage window a Contract has used (local-agents 10).
+
+Asked of the vendor's own binary, as the Contract's uid in its harness root -- never of the
+vendor's usage endpoint with the person's bearer (Anthropic's ``api/oauth/usage``,
+OpenAI's ``wham/usage``), which would put that bearer in the Runner's hands. No adapter
+spends model tokens. One adapter per harness behind one port (PRD decision 11):
+
+- **Codex:** ``account/rateLimits/read`` over ``codex app-server``. codex-acp keeps rate
+  limits in its session state and says nothing structured about them over ACP.
+- **Claude Code:** the rate-limit events the CLI emits from its responses' headers, which
+  claude-agent-acp (pinned 0.88.0, ``acp-agent.js``) forwards as a ``usage_update`` whose
+  ``_meta["_claude/rateLimit"]`` is the CLI's ``rate_limit_info``. The ACP runtime reads
+  them off the Directive's own stream, and a Contract whose stream has carried them is
+  never probed. Until then, the ``/usage`` screen under a PTY, as Paperclip reads it
+  (``claude-local/src/server/quota.ts``).
+
+At most once per interval per Contract, never while it has a Directive running, and again
+after a Directive that stopped on its usage limit. A probe that fails or times out reports
+nothing until one succeeds; it never touches a Directive.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import fcntl
+import json
+import logging
+import math
+import os
+import pty
+import re
+import signal
+import struct
+import subprocess
+import termios
+from collections.abc import Callable, Mapping, Sequence
+from datetime import UTC, datetime
+from typing import Any, Final, Protocol
+
+from agentic_runner.harness_self_test import DirectivesInFlight, SandboxFor
+from agentic_runner.workers._runtime_support import terminate_process_tree
+from agentic_runner.workers.claude_sign_in import launcher_argv
+from agentic_runner.workers.contract_isolation import ContractIsolationError, DirectiveSandbox
+from agentic_runner.workers.harness_outcome import next_wall_clock, wall_clock_zone
+from agentic_runner_contracts.runner_registration import UsageWindow
+
+__all__ = [
+    "USAGE_PROBE_INTERVAL_SECONDS",
+    "ClaudeUsageScreenProbe",
+    "CodexRateLimitsProbe",
+    "UsageWindowProbe",
+    "UsageWindows",
+    "claude_rate_limit_windows",
+    "claude_usage_screen_windows",
+    "codex_rate_limit_windows",
+]
+
+USAGE_PROBE_INTERVAL_SECONDS: Final = 15 * 60
+_PROBE_TIMEOUT_SECONDS: Final = 20.0
+_NAME: Final = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
+
+_logger = logging.getLogger(__name__)
+
+
+class UsageWindowProbe(Protocol):
+    """One harness's way of saying how much of each window is used, run in ``sandbox``."""
+
+    async def __call__(self, sandbox: DirectiveSandbox) -> list[UsageWindow]: ...
+
+
+class UsageWindows:
+    """The latest windows per ``(contract_id, cli_kind)``, and when the next probe is due."""
+
+    def __init__(
+        self,
+        *,
+        probes: Mapping[str, UsageWindowProbe],
+        sandbox_for: SandboxFor,
+        in_flight: DirectivesInFlight,
+        monotonic: Callable[[], float],
+        clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        interval_seconds: float = USAGE_PROBE_INTERVAL_SECONDS,
+    ) -> None:
+        self._probes = dict(probes)
+        self._sandbox_for = sandbox_for
+        self._in_flight = in_flight
+        self._monotonic = monotonic
+        self._clock = clock
+        self._interval = interval_seconds
+        self._windows: dict[tuple[str, str], list[UsageWindow]] = {}
+        self._last_run: dict[tuple[str, str], float] = {}
+        self._streamed: set[tuple[str, str]] = set()
+
+    def windows(self, contract_id: str, cli_kind: str) -> list[UsageWindow] | None:
+        """``None`` until a window is known; a window whose reset has passed is dropped,
+        since its percentage no longer describes anything."""
+
+        now = self._clock()
+        current = [
+            window
+            for window in self._windows.get((contract_id, cli_kind), [])
+            if window.resets_at is None or window.resets_at > now
+        ]
+        return current or None
+
+    def after_directive(
+        self,
+        contract_id: str,
+        cli_kind: str,
+        streamed: Sequence[UsageWindow],
+        *,
+        usage_limit: bool,
+    ) -> None:
+        """What a subscription Directive's own stream said, and whether issue 08 found it
+        stopped on its usage limit -- which makes the next probe due at once."""
+
+        key = (contract_id, cli_kind)
+        if streamed:
+            self._windows[key] = list(streamed)
+            self._streamed.add(key)
+            self._last_run[key] = self._monotonic()
+        if usage_limit:
+            self._last_run.pop(key, None)
+
+    async def run_due(self, targets: Sequence[tuple[str, str]]) -> None:
+        wanted = set(targets)
+        for gone in (self._windows.keys() | self._last_run.keys() | self._streamed) - wanted:
+            self._forget(gone)
+        for contract_id, cli_kind in targets:
+            key = (contract_id, cli_kind)
+            probe = self._probes.get(cli_kind)
+            if probe is None or key in self._streamed:
+                continue
+            last = self._last_run.get(key)
+            if last is not None and self._monotonic() - last < self._interval:
+                continue
+            if self._in_flight.busy(contract_id):
+                # Not stamped: it runs on the first sweep after the Directive ends.
+                continue
+            self._last_run[key] = self._monotonic()
+            self._windows[key] = await self._probe(probe, contract_id, cli_kind)
+
+    def _forget(self, key: tuple[str, str]) -> None:
+        self._windows.pop(key, None)
+        self._last_run.pop(key, None)
+        self._streamed.discard(key)
+
+    async def _probe(
+        self, probe: UsageWindowProbe, contract_id: str, cli_kind: str
+    ) -> list[UsageWindow]:
+        try:
+            sandbox = self._sandbox_for(contract_id, cli_kind)
+            if sandbox is None:
+                return []
+            return await probe(sandbox)
+        except (
+            ContractIsolationError,
+            OSError,
+            TimeoutError,
+            subprocess.SubprocessError,
+            ValueError,
+        ) as error:
+            # The type only: a harness's error text can carry the account it signed in as.
+            _logger.warning(
+                "usage window probe for %s/%s failed: %s",
+                contract_id,
+                cli_kind,
+                error.__class__.__name__,
+            )
+            return []
+
+
+# ------------------------------------------------------------------ Codex
+
+
+class CodexRateLimitsProbe:
+    """``account/rateLimits/read`` over ``codex app-server``, as the Contract's uid.
+
+    The app-server protocol is JSON-RPC without the ``jsonrpc`` member, one object per
+    line, and interleaves notifications with the responses (codex-cli 0.159.2).
+    """
+
+    def __init__(
+        self,
+        *,
+        argv: Sequence[str] = ("codex", "app-server"),
+        timeout_seconds: float = _PROBE_TIMEOUT_SECONDS,
+    ) -> None:
+        self._argv = list(argv)
+        self._timeout = timeout_seconds
+
+    async def __call__(self, sandbox: DirectiveSandbox) -> list[UsageWindow]:
+        process = await asyncio.create_subprocess_exec(
+            *self._argv,
+            cwd=sandbox.home_dir,
+            env=_harness_env(sandbox, "CODEX_HOME"),
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+            start_new_session=True,
+            limit=1024 * 1024,
+            **sandbox.spawn_kwargs(),
+        )
+        assert process.stdin is not None and process.stdout is not None
+        stdin, stdout = process.stdin, process.stdout
+
+        async def request(request_id: int, method: str, params: object) -> Mapping[str, Any]:
+            stdin.write(_line({"id": request_id, "method": method, "params": params}))
+            await stdin.drain()
+            while line := await stdout.readline():
+                with contextlib.suppress(ValueError):
+                    message = json.loads(line)
+                    if isinstance(message, dict) and message.get("id") == request_id:
+                        return message
+            raise ConnectionError("codex app-server closed its stdout")
+
+        try:
+            async with asyncio.timeout(self._timeout):
+                await request(
+                    1, "initialize", {"clientInfo": {"name": "agentic-runner", "version": "1"}}
+                )
+                stdin.write(_line({"method": "initialized"}))
+                answer = await request(2, "account/rateLimits/read", None)
+        finally:
+            await terminate_process_tree(process)
+        # An error -- ``-32600`` "codex account authentication required" when the root has
+        # no login -- has no ``result``, and so no windows.
+        return codex_rate_limit_windows(answer.get("result"))
+
+
+_CODEX_WINDOW_NAMES: Final[Mapping[int, str]] = {300: "five_hour", 10_080: "seven_day"}
+
+
+def codex_rate_limit_windows(result: object) -> list[UsageWindow]:
+    """``rateLimits.primary``/``secondary`` from a ``GetAccountRateLimitsResponse``.
+
+    Named by their duration where it is a window Codex is known to have, else by slot.
+    ``usedPercent`` is already a percentage, ``resetsAt`` epoch seconds.
+    """
+
+    snapshot = result.get("rateLimits") if isinstance(result, Mapping) else None
+    if not isinstance(snapshot, Mapping):
+        return []
+    windows: list[UsageWindow] = []
+    for slot in ("primary", "secondary"):
+        window = snapshot.get(slot)
+        if not isinstance(window, Mapping):
+            continue
+        used = _number(window.get("usedPercent"))
+        if used is None:
+            continue
+        minutes = window.get("windowDurationMins")
+        name = _CODEX_WINDOW_NAMES.get(minutes, slot) if isinstance(minutes, int) else slot
+        windows.append(
+            UsageWindow(
+                name=name, used_percent=_clamped(used), resets_at=_epoch(window.get("resetsAt"))
+            )
+        )
+    return windows
+
+
+# ------------------------------------------------------------------ Claude Code
+
+
+def claude_rate_limit_windows(info: object) -> list[UsageWindow]:
+    """The windows in one ``rate_limit_info`` (claude 2.1.295's ``rate_limit_event``).
+
+    ``unifiedWindows`` carries every window on every event; without it, the top-level
+    fields describe the one currently limiting. ``utilization`` is a fraction of the window
+    and can run past 1.
+    """
+
+    if not isinstance(info, Mapping):
+        return []
+    unified = info.get("unifiedWindows")
+    if isinstance(unified, Mapping) and unified:
+        pairs = list(unified.items())
+    else:
+        pairs = [(info.get("rateLimitType"), info)]
+    windows: list[UsageWindow] = []
+    for name, window in pairs:
+        if not isinstance(name, str) or not _NAME.match(name) or not isinstance(window, Mapping):
+            continue
+        utilization = _number(window.get("utilization"))
+        if utilization is None:
+            continue
+        windows.append(
+            UsageWindow(
+                name=name,
+                used_percent=_clamped(utilization * 100),
+                resets_at=_epoch(window.get("resetsAt")),
+            )
+        )
+    return windows
+
+
+class ClaudeUsageScreenProbe:
+    """``/usage`` typed into an interactive ``claude`` on a PTY, as the Contract's uid.
+
+    Behind the sign-in launcher, so the CLI reads the Contract's own login and the Runner
+    reads nothing under the harness root. Nothing is prompted: ``/usage`` is a local
+    command and the session is killed once the screen has drawn, or at the timeout.
+    """
+
+    def __init__(
+        self,
+        *,
+        argv: Sequence[str] = ("claude",),
+        timeout_seconds: float = _PROBE_TIMEOUT_SECONDS,
+        settle_seconds: float = 2.0,
+        clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._argv = list(argv)
+        self._timeout = timeout_seconds
+        self._settle = settle_seconds
+        self._clock = clock
+
+    async def __call__(self, sandbox: DirectiveSandbox) -> list[UsageWindow]:
+        master_fd, slave_fd = pty.openpty()
+        try:
+            fcntl.ioctl(slave_fd, termios.TIOCSWINSZ, struct.pack("HHHH", 50, 200, 0, 0))
+            os.set_blocking(master_fd, False)
+            process = await asyncio.create_subprocess_exec(
+                *launcher_argv(sandbox.harness_config_dir, self._argv),
+                cwd=sandbox.home_dir,
+                env=_harness_env(sandbox, "CLAUDE_CONFIG_DIR") | {"TERM": "xterm-256color"},
+                stdin=slave_fd,
+                stdout=slave_fd,
+                stderr=slave_fd,
+                start_new_session=True,
+                **sandbox.spawn_kwargs(),
+            )
+        except BaseException:
+            os.close(master_fd)
+            raise
+        finally:
+            os.close(slave_fd)
+        screen = bytearray()
+        windows: list[UsageWindow] = []
+        try:
+            with contextlib.suppress(TimeoutError):
+                async with asyncio.timeout(self._timeout):
+                    # The prompt must be up before it can take a command.
+                    await asyncio.sleep(self._settle)
+                    _drain(master_fd, screen)
+                    os.write(master_fd, b"/usage")
+                    # Ink reads a command and its Enter as one paste and drops the Enter.
+                    await asyncio.sleep(0.15)
+                    os.write(master_fd, b"\r")
+                    while not _screen_complete(windows):
+                        await asyncio.sleep(0.25)
+                        _drain(master_fd, screen)
+                        windows = claude_usage_screen_windows(
+                            screen.decode("utf-8", errors="replace"), self._clock()
+                        )
+        finally:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.killpg(process.pid, signal.SIGKILL)
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(process.wait(), timeout=2)
+            os.close(master_fd)
+        return windows
+
+
+_SCREEN_LABELS: Final[Mapping[str, str]] = {
+    "currentsession": "five_hour",
+    "currentweekallmodels": "seven_day",
+    "currentweeksonnetonly": "seven_day_sonnet",
+    "currentweeksonnet": "seven_day_sonnet",
+    "currentweekopusonly": "seven_day_opus",
+    "currentweekopus": "seven_day_opus",
+}
+_ANSI: Final = re.compile(
+    r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)"  # OSC, e.g. a hyperlink
+    r"|\x1b(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])"  # CSI and the two-byte escapes
+)
+_PERCENT: Final = re.compile(r"(\d{1,3}(?:\.\d+)?)\s*%\s*(used|left|remaining|available)?", re.I)
+# ``Resets 5pm (America/Chicago)``, ``Resets Mar 18 at 7:59am (America/Chicago)``; Ink can
+# drop the spaces between the parts.
+_RESET: Final = re.compile(
+    r"^resets\s*(?:(?P<month>[a-z]{3})[a-z]*\s*(?P<day>\d{1,2}),?\s*(?:at\s*)?)?"
+    r"(?P<clock>\d{1,2}(?::\d{2})?\s*[ap]\.?\s*m\.?)\s*(?:\((?P<zone>[^)]+)\))?",
+    re.I,
+)
+_MONTHS: Final = (
+    "jan",
+    "feb",
+    "mar",
+    "apr",
+    "may",
+    "jun",
+    "jul",
+    "aug",
+    "sep",
+    "oct",
+    "nov",
+    "dec",
+)
+
+
+def claude_usage_screen_windows(text: str, now: datetime) -> list[UsageWindow]:
+    """The windows on the latest ``/usage`` screen in a PTY capture.
+
+    Each label is followed by its ``N% used`` line and its ``Resets …`` line. A window the
+    screen draws without a percentage -- ``Extra usage``, or one still loading -- is left
+    out, and so is a capture with no such screen at all.
+    """
+
+    lines = [line.strip() for line in _clean(text).split("\n")]
+    starts = [i for i, line in enumerate(lines) if _label(line) == "currentsession"]
+    if not starts:
+        return []
+    windows: dict[str, UsageWindow] = {}
+    name: str | None = None
+    used: float | None = None
+    for line in lines[starts[-1] :]:
+        label = _label(line)
+        if label in _SCREEN_LABELS:
+            name, used = _SCREEN_LABELS[label], None
+        elif name is None or not line:
+            continue
+        elif used is None and (percent := _PERCENT.search(line)):
+            value = float(percent.group(1))
+            remaining = (percent.group(2) or "").lower() in {"left", "remaining", "available"}
+            used = _clamped(100 - value if remaining else value)
+            windows[name] = UsageWindow(name=name, used_percent=used)
+        elif used is not None and (reset := _RESET.match(line)):
+            windows[name] = UsageWindow(
+                name=name, used_percent=used, resets_at=_screen_reset(reset, now)
+            )
+            name = None
+    return list(windows.values())
+
+
+def _screen_complete(windows: Sequence[UsageWindow]) -> bool:
+    names = {window.name for window in windows}
+    return "five_hour" in names and "seven_day" in names
+
+
+def _screen_reset(match: re.Match[str], now: datetime) -> datetime | None:
+    clock, zone = match.group("clock"), match.group("zone")
+    if zone:
+        clock = f"{clock} ({zone})"
+    if match.group("month") is None:
+        at = next_wall_clock(clock, now)
+        return datetime.fromisoformat(at) if at else None
+    month = match.group("month").lower()
+    if month not in _MONTHS:
+        return None
+    # The time on the screen's date: the next such time after the date's midnight.
+    local_now = now.astimezone(wall_clock_zone(zone))
+    try:
+        midnight = local_now.replace(
+            month=_MONTHS.index(month) + 1,
+            day=int(match.group("day")),
+            hour=0,
+            minute=0,
+            second=0,
+            microsecond=0,
+        )
+    except ValueError:
+        return None
+    if midnight.date() < local_now.date():
+        # A reset is never in the past: ``Jan 2`` seen on Dec 30 is next year's.
+        midnight = midnight.replace(year=midnight.year + 1)
+    at = next_wall_clock(clock, midnight)
+    return datetime.fromisoformat(at) if at else None
+
+
+def _clean(text: str) -> str:
+    kept: list[str] = []
+    for char in text:
+        if char == "\b":
+            if kept:
+                kept.pop()
+        else:
+            kept.append(char)
+    return _ANSI.sub("", "".join(kept)).replace("\x00", "").replace("\r", "\n")
+
+
+def _label(line: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "", line.lower())
+
+
+def _drain(master_fd: int, screen: bytearray) -> None:
+    with contextlib.suppress(BlockingIOError, OSError):
+        while chunk := os.read(master_fd, 65_536):
+            screen.extend(chunk)
+            # The latest screen is at the end; a CLI that redraws forever is bounded here.
+            del screen[:-262_144]
+
+
+# ------------------------------------------------------------------ shared
+
+
+def _harness_env(sandbox: DirectiveSandbox, root_env: str) -> dict[str, str]:
+    """The four names every probe gets and nothing else: no bearer, no API key, no proxy."""
+
+    return {
+        "PATH": os.environ.get("PATH") or os.defpath,
+        "HOME": str(sandbox.home_dir),
+        "TMPDIR": str(sandbox.tmp_dir),
+        root_env: str(sandbox.harness_config_dir),
+    }
+
+
+def _line(message: Mapping[str, object]) -> bytes:
+    return (json.dumps(message) + "\n").encode()
+
+
+def _number(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    return float(value) if math.isfinite(value) else None
+
+
+def _clamped(percent: float) -> float:
+    return round(min(100.0, max(0.0, percent)), 1)
+
+
+def _epoch(value: object) -> datetime | None:
+    seconds = _number(value)
+    if seconds is None or seconds <= 0:
+        return None
+    try:
+        return datetime.fromtimestamp(seconds, UTC)
+    except (OverflowError, OSError, ValueError):
+        return None

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/workers/acp_runtime.py

@@ -61,6 +61,7 @@ from agentic_runner.attempts import (
 )
 from agentic_runner.callback import CALLBACK_SOCKET_ENV, CALLBACK_TOKEN_ENV, call
 from agentic_runner.llm_proxy import PROXY_API_KEY_ENV, PROXY_BASE_URL_ENV
+from agentic_runner.usage_windows import claude_rate_limit_windows
 from agentic_runner.workers._runtime_support import (
     apply_extra_env,
     bound_text,
@@ -85,6 +86,7 @@ from agentic_runner.workers.command_policy import CommandPolicy, evaluate_comman
 from agentic_runner.workers.contract_isolation import DirectiveSandbox
 from agentic_runner.workers.mcp_config import McpServerEntry
 from agentic_runner.workers.settings import WorkerSettings
+from agentic_runner_contracts.runner_registration import UsageWindow
 
 __all__ = ["ACP_BRIDGES", "AcpBridge", "AcpRuntime"]
 
@@ -218,6 +220,7 @@ class _Turn:
     output: list[str] = field(default_factory=list)
     notes: list[str] = field(default_factory=list)
     held: bool = False
+    usage_windows: tuple[UsageWindow, ...] = ()
 
 
 class AcpRuntime:
@@ -594,6 +597,7 @@ class AcpRuntime:
                 request, directive_workspace_id, command_hash, guard_mode, notes
             ),
             model_usage=model_usage,
+            usage_windows=turn.usage_windows,
         )
 
     def _evidence(
@@ -883,7 +887,17 @@ def _offers_mode(session: Mapping[str, Any], mode_id: str) -> bool:
 
 def _collect_update(params: Mapping[str, Any], turn: _Turn) -> None:
     update = params.get("update")
-    if not isinstance(update, Mapping) or update.get("sessionUpdate") != "agent_message_chunk":
+    if not isinstance(update, Mapping):
+        return
+    if update.get("sessionUpdate") == "usage_update":
+        # claude-agent-acp's relay of the CLI's rate-limit event; the latest one wins.
+        meta = update.get("_meta")
+        if isinstance(meta, Mapping) and (
+            windows := claude_rate_limit_windows(meta.get("_claude/rateLimit"))
+        ):
+            turn.usage_windows = tuple(windows)
+        return
+    if update.get("sessionUpdate") != "agent_message_chunk":
         return
     content = update.get("content")
     if isinstance(content, Mapping) and content.get("type") == "text":

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/workers/agent_runtime.py

@@ -20,6 +20,7 @@ from typing import Protocol, runtime_checkable
 
 from agentic_runner.workers.contract_isolation import DirectiveSandbox
 from agentic_runner.workers.mcp_config import McpServerEntry
+from agentic_runner_contracts.runner_registration import UsageWindow
 
 
 class AuthMode(StrEnum):
@@ -131,6 +132,9 @@ class DirectiveResult:
     # The harness's own per-model usage, where its protocol carries one (ACP). Empty means
     # the caller reads usage off ``stdout`` as before.
     model_usage: tuple[ModelUsage, ...] = ()
+    # The subscription usage windows the harness's own stream last reported, where it
+    # carries them (claude-agent-acp's rate-limit events, local-agents 10).
+    usage_windows: tuple[UsageWindow, ...] = ()
 
 
 # The permission mode of a runtime whose guard configuration is incomplete: it refuses

{agentic_runner-3.6.0 → agentic_runner-3.7.0}/src/agentic_runner/workers/harness_outcome.py

@@ -23,7 +23,7 @@ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 from agentic_runner.workers.harness_usage import extract_claude_result
 from agentic_runner_contracts.activity_io import HarnessHold, HarnessHoldKind
 
-__all__ = ["classify_harness_outcome"]
+__all__ = ["classify_harness_outcome", "next_wall_clock", "wall_clock_zone"]
 
 _CLAUDE_CODE: Final[str] = "claude_code"
 _CODEX_CLI: Final[str] = "codex_cli"
@@ -121,7 +121,7 @@ def classify_harness_outcome(
     clock = reset.search(text, limit.end())
     return HarnessHold(
         kind=HarnessHoldKind.USAGE_LIMIT,
-        retry_not_before=_next_wall_clock(clock.group("clock"), now) if clock else None,
+        retry_not_before=next_wall_clock(clock.group("clock"), now) if clock else None,
     )
 
 
@@ -185,7 +185,7 @@ def _joined(*parts: str) -> str:
     return "\n".join(part.strip() for part in parts if part and part.strip())
 
 
-def _next_wall_clock(text: str, now: datetime) -> str | None:
+def next_wall_clock(text: str, now: datetime) -> str | None:
     match = _CLOCK_RE.match(text.strip())
     if match is None:
         return None
@@ -193,14 +193,14 @@ def _next_wall_clock(text: str, now: datetime) -> str | None:
     if not 1 <= hour <= 12 or not 0 <= minute <= 59:
         return None
     hour = hour % 12 + (12 if match.group("half").lower() == "p" else 0)
-    local_now = now.astimezone(_zone(match.group("zone")))
+    local_now = now.astimezone(wall_clock_zone(match.group("zone")))
     candidate = local_now.replace(hour=hour, minute=minute, second=0, microsecond=0)
     if candidate <= local_now:
         candidate += timedelta(days=1)
     return candidate.astimezone(UTC).isoformat()
 
 
-def _zone(name: str | None) -> tzinfo | None:
+def wall_clock_zone(name: str | None) -> tzinfo | None:
     """The zone the harness named, or None -- ``astimezone``'s "this host's own"."""
 
     if not name: