agent-runtime-py 0.2.1__tar.gz → 0.2.2__tar.gz

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.2
+
+- Add `LaunchOptions.effort` (`low`, `medium`, `high`, `xhigh` or `max`), passed to native Claude.
+- A worker that fails adds `native_stderr` to its result: the last lines (at most 20, each at most 500 characters) that native Claude wrote to stderr since its last result. They are often the reason of a failed start, where the SDK's error only says to check stderr. They are not redacted; a consumer decides whether to show them.
+- Fix: `LaunchOptions.claude` and the `claude` found on PATH are used as given (made absolute), not as their link target. A version manager's shim (a link to the manager) was resolved to the manager, which then did not run Claude. A path that is not a file, also a directory, now raises `ValueError`; a missing path raised `FileNotFoundError` before.
+- A repeated launch ID no longer compares the path of the Claude executable, so a launch that 0.2.1 recorded can be repeated.
+
 ## 0.2.1
 
 - Fix: a Claude input that native Claude folded into a turn started by something else (a peer message, a background task) never settled, because that turn's result carries the other origin. The worker then took no further input and never exited on idle. A result now settles the active input when the input's echo arrived before it.

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-runtime-py
-Version: 0.2.1
+Version: 0.2.2
 Summary: Reconnectable native agent workers with durable input receipts and events
 Project-URL: Repository, https://github.com/nimashoghi/agent-runtime
 License-Expression: MIT

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-runtime-py"
-version = "0.2.1"
+version = "0.2.2"
 description = "Reconnectable native agent workers with durable input receipts and events"
 readme = "README.md"
 license = "MIT"

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/src/agent_runtime/claude.py

@@ -33,6 +33,7 @@ class LaunchOptions:
     permission_mode: str = "default"
     allowed_tools: tuple[str, ...] = ()
     model: str | None = None
+    effort: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
 
     def configuration(self) -> dict[str, Any]:
@@ -48,18 +49,34 @@ class LaunchOptions:
             "auto",
         }:
             raise ValueError("unknown Claude permission mode")
+        if self.effort is not None and self.effort not in ("low", "medium", "high", "xhigh", "max"):
+            raise ValueError("unknown Claude effort level")
         cwd = self.cwd.expanduser().resolve(strict=True)
         if not cwd.is_dir():
             raise ValueError("cwd must be a directory")
         executable = str(self.claude) if self.claude else shutil.which("claude")
         if not executable:
             raise ValueError("Claude Code executable not found")
+        # The path as given, not its link target: a version manager's shim is a link to the
+        # manager, which chooses the program by the name it was called with.
+        claude = Path(executable).expanduser().absolute()
+        if not claude.is_file():
+            raise ValueError(f"Claude Code executable not found: {claude}")
         value = asdict(self)
         value.pop("environment")
-        value.update(cwd=str(cwd), claude=str(Path(executable).expanduser().resolve(strict=True)))
+        if self.effort is None:
+            value.pop("effort")  # as a record of a version without the field
+        value.update(cwd=str(cwd), claude=str(claude))
         return json.loads(json.dumps(value))
 
 
+def launch_identity(configuration: dict[str, Any]) -> dict[str, Any]:
+    """The part of a launch configuration that a repeated launch ID must repeat. The path of
+    the Claude executable is not part of it: its spelling changes with the installation and
+    between versions of this package (0.2.1 stored the link's target)."""
+    return {key: value for key, value in configuration.items() if key != "claude"}
+
+
 def process_alive(value: dict[str, Any]) -> bool:
     """PID reuse must never attach a client to an unrelated process."""
     if not value.get("pid") or not value.get("process_created_at"):
@@ -145,15 +162,11 @@ class ClaudeRuntime:
             }
             if not self.store.create_execution(value):
                 existing = self.inspect(execution_id)
-                for key in (
-                    "initial_message_id",
-                    "initial_digest",
-                    "resume",
-                    "fork",
-                    "configuration",
-                ):
+                for key in ("initial_message_id", "initial_digest", "resume", "fork"):
                     if existing[key] != value[key]:
                         raise ValueError(f"launch ID already used with different {key}")
+                if launch_identity(existing["configuration"]) != launch_identity(configuration):
+                    raise ValueError("launch ID already used with different configuration")
                 return existing
             self.store.accept(session_id, execution_id, message_id, text)
             environment = {**os.environ, **options.environment}

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/src/agent_runtime/worker.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import collections
 import logging
 import os
 import signal
@@ -45,6 +46,14 @@ class Worker:
         self.last_activity = time.monotonic()
         self.background_tasks: set[str] = set()
         self.presentation_started = False
+        # The last lines that native Claude wrote to stderr since its last result. When the
+        # worker fails, they go into its result apart from the error: they are often the
+        # reason (the SDK's error only says to check stderr), but not always.
+        self.stderr: collections.deque[str] = collections.deque(maxlen=20)
+
+    def native_stderr(self, line: str) -> None:
+        log.debug("claude: %s", line)
+        self.stderr.append(line[:500])
 
     def emit(self, kind: str, **fields: Any) -> None:
         self.store.append(self.execution_id, self.session_id, {"type": kind, **fields})
@@ -123,6 +132,7 @@ class Worker:
             elif isinstance(message, ResultMessage):
                 if message.session_id != self.session_id:
                     raise RuntimeError("native Claude returned a different session ID")
+                self.stderr.clear()  # what it wrote before a result is not about a later failure
                 human = message.origin is None or message.origin.get("kind") == "human"
                 # Native Claude can fold an input into a turn that something else started
                 # (a peer message, a background task); that turn's result carries the other
@@ -189,6 +199,7 @@ class Worker:
             permission_mode=policy["permission_mode"],
             allowed_tools=policy["allowed_tools"],
             model=policy["model"],
+            effort=policy.get("effort"),  # absent in the record of an older version
             setting_sources=["user", "project", "local"],
             system_prompt={
                 "type": "preset",
@@ -196,7 +207,7 @@ class Worker:
                 "append": policy["instructions"] or "",
             },
             can_use_tool=self.permission,
-            stderr=lambda line: log.debug("claude: %s", line),
+            stderr=self.native_stderr,
             extra_args={"replay-user-messages": None},
             session_id=self.session_id
             if not self.execution["resume"] or self.execution["fork"]
@@ -277,6 +288,8 @@ class Worker:
         except Exception as error:
             log.exception("Claude worker failed")
             result = {"status": "failed", "error": str(error)}
+            if self.stderr:
+                result["native_stderr"] = list(self.stderr)
         finally:
             self.stopping.set()
             try:

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/tests/test_claude_runtime.py

@@ -21,6 +21,15 @@ import json, os, sys
 if "--version" in sys.argv:
     print("2.1.281 (Claude Code)")
     raise SystemExit(0)
+if os.environ.get("FAKE_CLAUDE_ARGV"):
+    with open(os.environ["FAKE_CLAUDE_ARGV"], "w") as log:
+        json.dump(sys.argv, log)
+if os.environ.get("FAKE_CLAUDE_FAILS"):
+    for number in range(30):
+        print(f"line {number} " + "x" * 600, file=sys.stderr, flush=True)
+    print("Invalid API key - Please run /login", file=sys.stderr, flush=True)
+    raise SystemExit(1)
+print("warning: a line at the start", file=sys.stderr, flush=True)
 def emit(value):
     print(json.dumps(value), flush=True)
 session = next(a.split("=", 1)[1] for a in sys.argv if a.startswith(("--session-id=", "--resume=")))
@@ -51,6 +60,12 @@ for line in sys.stdin:
             result("answer to both", PEER)
             continue
         emit({"type":"user","uuid":message["uuid"],"message":{"role":"user","content":text},"origin":{"kind":"human"}})
+        if text == "wrong-session":
+            # A failure of the worker's own check, late in a session, with no stderr line.
+            emit({"type":"result", "subtype":"success", "is_error":False, "duration_ms":1,
+                  "duration_api_ms":1, "num_turns":1, "session_id":"another-session",
+                  "result":"x", "origin":{"kind":"human"}, "usage":{}})
+            continue
         if text == "then-a-peer-turn":
             # The input's own turn ends; a peer message then starts a turn that works
             # in silence for longer than the idle timeout.
@@ -243,3 +258,88 @@ async def test_a_turn_for_another_origin_is_not_ended_by_the_idle_timeout(tmp_pa
         assert settled[1]["message"] == "peer turn done"
     finally:
         await runtime.stop(eid)
+
+
+async def test_effort_reaches_native_claude_and_a_link_to_it_is_not_resolved(tmp_path, native):
+    link = tmp_path / "shim"
+    link.symlink_to(native)
+    opts = LaunchOptions(
+        cwd=tmp_path,
+        claude=link,
+        effort="high",
+        idle_timeout_seconds=0,
+        environment={
+            "FAKE_CLAUDE_LOG": str(tmp_path / "inputs.jsonl"),
+            "FAKE_CLAUDE_ARGV": str(tmp_path / "argv.json"),
+        },
+    )
+    assert opts.configuration()["claude"] == str(link)
+    with pytest.raises(ValueError, match="effort"):
+        LaunchOptions(cwd=tmp_path, claude=native, effort="extreme").configuration()
+    with pytest.raises(ValueError, match="not found"):
+        LaunchOptions(cwd=tmp_path, claude=tmp_path / "missing").configuration()
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    value = await runtime.start("hello", message_id="m1", options=opts, launch_id="effort")
+    try:
+        await wait_for(
+            lambda: runtime.store.receipt(value["session_id"], "m1")["status"] == "delivered"
+        )
+        argv = json.loads((tmp_path / "argv.json").read_text())
+        assert argv[0] == str(link) and argv[argv.index("--effort") + 1] == "high"
+    finally:
+        await runtime.stop(value["execution_id"])
+
+
+async def test_a_native_claude_that_fails_at_its_start_reports_what_it_wrote(tmp_path, native):
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    opts = options(tmp_path, native)
+    opts.environment["FAKE_CLAUDE_FAILS"] = "1"
+    value = await runtime.start("hello", message_id="m1", options=opts, launch_id="fails")
+    result = await wait_for(lambda: runtime.inspect(value["execution_id"])["result"])
+    assert result["status"] == "failed" and "Invalid API key" not in result["error"]
+    # The last 20 lines, each cut to 500 characters, apart from the error.
+    lines = result["native_stderr"]
+    assert len(lines) == 20 and lines[-1] == "Invalid API key - Please run /login"
+    assert all(len(line) <= 500 for line in lines) and lines[0].startswith("line 11 ")
+    assert runtime.store.receipt(value["session_id"], "m1")["status"] == "rejected"
+
+
+async def test_stderr_from_before_a_result_is_not_reported_with_a_later_failure(tmp_path, native):
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    opts = options(tmp_path, native)
+    value = await runtime.start("hello", message_id="m1", options=opts, launch_id="late")
+    sid, eid = value["session_id"], value["execution_id"]
+    await wait_for(lambda: runtime.store.receipt(sid, "m1")["status"] == "delivered")
+    await runtime.submit(sid, "wrong-session", message_id="m2", options=opts, resume=False)
+    result = await wait_for(lambda: runtime.inspect(eid)["result"])
+    assert result["status"] == "failed" and "different session ID" in result["error"]
+    assert "native_stderr" not in result  # the warning at the start came before the first result
+
+
+async def test_a_launch_id_from_an_older_version_can_be_repeated(tmp_path, native):
+    """0.2.1 stored no effort and the link target of the executable; a repeat of that launch
+    by this version must find the same execution."""
+    link = tmp_path / "shim"
+    link.symlink_to(native)
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    opts = LaunchOptions(
+        cwd=tmp_path,
+        claude=link,
+        idle_timeout_seconds=0,
+        environment={"FAKE_CLAUDE_LOG": str(tmp_path / "inputs.jsonl")},
+    )
+    assert "effort" not in opts.configuration()
+    first = await runtime.start("hello", message_id="m1", options=opts, launch_id="old")
+    eid = first["execution_id"]
+    try:
+        stored = dict(runtime.store.execution(eid)["configuration"], claude=str(native.resolve()))
+        runtime.store.update(eid, configuration=stored)
+        again = await runtime.start("hello", message_id="m1", options=opts, launch_id="old")
+        assert again["execution_id"] == eid
+        with pytest.raises(ValueError, match="configuration"):
+            changed = LaunchOptions(
+                cwd=tmp_path, claude=link, effort="high", idle_timeout_seconds=0
+            )
+            await runtime.start("hello", message_id="m1", options=changed, launch_id="old")
+    finally:
+        await runtime.stop(eid)

{agent_runtime_py-0.2.1 → agent_runtime_py-0.2.2}/uv.lock

@@ -9,7 +9,7 @@ resolution-markers = [
 
 [[package]]
 name = "agent-runtime-py"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "filelock" },