agentproc 0.7.0__tar.gz → 0.8.0__tar.gz

{agentproc-0.7.0 → agentproc-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.7.0
+Version: 0.8.0
 Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc

{agentproc-0.7.0 → agentproc-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentproc"
-version = "0.7.0"
+version = "0.8.0"
 description = "AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform"
 readme = "README.md"
 license = { text = "MIT" }

{agentproc-0.7.0 → agentproc-0.8.0}/src/agentproc/__init__.py

@@ -166,6 +166,64 @@ class AgentContext:
         sys.stdout.flush()
         return _NoopAwaitable()
 
+    def send_permission_request(self, req: Dict[str, Any]) -> None:
+        """Send a tool-permission request to the bridge.
+
+        Only valid when ``ctx.permission`` is True (the profile set
+        ``permission: true`` and the bridge enabled the channel). The bridge
+        surfaces the request to the user; the matching decision arrives on
+        stdin as a ``{"type":"permission_response",...}`` frame that
+        :meth:`read_permission_response` decodes.
+
+        ``req`` MUST include ``request_id`` (unique within the turn),
+        ``tool_name``, and ``input`` (object). ``description`` and
+        ``tool_use_id`` are optional.
+        """
+        if not self.permission:
+            raise RuntimeError(
+                "ctx.send_permission_request() requires profile.permission: "
+                "true — the bridge would otherwise not honor the request"
+            )
+        if not isinstance(req, dict):
+            raise TypeError("req must be a dict")
+        rid = req.get("request_id")
+        if not isinstance(rid, str) or not rid:
+            raise ValueError("req['request_id'] is required")
+        payload: Dict[str, Any] = {"type": "permission_request"}
+        for k in ("request_id", "tool_name", "input"):
+            payload[k] = req.get(k)
+        for k in ("description", "tool_use_id"):
+            if k in req:
+                payload[k] = req[k]
+        sys.stdout.write(
+            json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+        )
+        sys.stdout.flush()
+
+    def read_permission_response(self) -> Optional[Dict[str, Any]]:
+        """Read the next ``{"type":"permission_response",...}`` frame from stdin.
+
+        Blocks until a frame arrives (or EOF). Returns the parsed object, or
+        ``None`` at EOF.
+
+        Only meaningful when ``ctx.permission`` is True — in the default
+        ``permission: false`` mode the bridge closes stdin after the turn
+        line, so this returns ``None`` immediately.
+        """
+        try:
+            line = sys.stdin.readline()
+        except Exception:
+            return None
+        if not line:
+            return None
+        try:
+            v = json.loads(line.rstrip("\r\n"))
+        except json.JSONDecodeError:
+            return None
+        if isinstance(v, dict):
+            return v
+        return None
+
 
 @dataclass
 class AgentResult:

{agentproc-0.7.0 → agentproc-0.8.0}/src/agentproc/runner.py

@@ -45,6 +45,7 @@ __all__ = [
     "DEFAULT_TIMEOUT_SECS",
     "DEFAULT_KILL_GRACE_SECS",
     "DEFAULT_MAX_REPLY_CHARS",
+    "DEFAULT_TRUNCATION_SUFFIX",
     "EXIT_SUCCESS",
     "EXIT_ERROR",
     "EXIT_TIMEOUT",
@@ -73,6 +74,7 @@ PROTOCOL_VERSION = "0.3"
 DEFAULT_TIMEOUT_SECS = 1800
 DEFAULT_KILL_GRACE_SECS = 5
 DEFAULT_MAX_REPLY_CHARS = 8000
+DEFAULT_TRUNCATION_SUFFIX = "\n\n…(truncated)"
 
 EXIT_SUCCESS = 0
 EXIT_ERROR = 1
@@ -207,6 +209,13 @@ def normalize_profile(raw: Dict[str, Any]) -> Dict[str, Any]:
             int(src["max_reply_chars"]) if _is_int_like(src.get("max_reply_chars"))
             else DEFAULT_MAX_REPLY_CHARS
         ),
+        # Spec profile YAML: optional truncation notice appended when the reply
+        # is capped. Defaults to "\n\n…(truncated)". An empty string disables
+        # the notice entirely (the cap still applies, just no visible marker).
+        "truncation_suffix": (
+            src["truncation_suffix"] if isinstance(src.get("truncation_suffix"), str)
+            else DEFAULT_TRUNCATION_SUFFIX
+        ),
         # Bridge-side hint: when False, the runner ignores {"type":"partial"}
         # events and assembles the reply from {"type":"text"} events only.
         "streaming": src.get("streaming", True) is not False,
@@ -545,6 +554,11 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
 
     result = RunResult()
     text_chunks: List[str] = []
+    # Spec 5.4: once an error event arrives, subsequent partial/text events
+    # MUST be discarded (they cannot contribute to a failed turn's reply).
+    # `session` is exempt — last-wins still applies so the id for the next
+    # turn can be captured even after an error.
+    error_seen = False
     pending_permission_ids: set = set()
     stdin_lock = threading.Lock()
     stdin_closed = False
@@ -552,18 +566,13 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
     _cumulative_partial_chars = 0
     _partials_truncated = False
     _max_chars = profile["max_reply_chars"]
-    _trunc_suffix = "\n\n…(truncated)" if _max_chars == DEFAULT_MAX_REPLY_CHARS else ""
-    # Two views on stderr:
-    #   - stderr_window: bounded sliding window (8 KB) for the on_stderr UI
-    #     callback, so a noisy agent cannot exhaust memory.
-    #   - stderr_full:   bounded head capture (1 MB) used only for post-mortem
-    #     pattern diagnosis. The diagnostic patterns target interpreter-startup
-    #     errors (file/module not found) which appear in the first bytes, so a
-    #     head cap preserves the high-value signal without unbounded growth.
-    #     Beyond the cap the tail is dropped with a one-shot marker.
-    stderr_window: List[str] = []
+    _trunc_suffix = profile["truncation_suffix"]
+    # Bounded head capture (1 MB) used for post-mortem pattern diagnosis.
+    # The diagnostic patterns target interpreter-startup errors (file/module
+    # not found) which appear in the first bytes, so a head cap preserves
+    # the high-value signal without unbounded growth. Beyond the cap the
+    # tail is dropped with a one-shot marker.
     stderr_full: List[str] = []
-    STDERR_CAP = 8192
     STDERR_FULL_CAP = 1 << 20  # 1 MB
     stderr_full_len = 0
     stderr_full_truncated = False
@@ -579,10 +588,6 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
             marker = "\n[agentproc runner] stderr capped at 1 MB; trailing output dropped\n"
             stderr_full.append(marker)
             stderr_full_truncated = True
-        stderr_window.append(text)
-        total = sum(len(s) for s in stderr_window)
-        while total > STDERR_CAP and len(stderr_window) > 1:
-            total -= len(stderr_window.pop(0))
 
     try:
         proc = subprocess.Popen(
@@ -668,7 +673,7 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
     assert proc.stdout is not None
 
     def _handle_line(raw_line: str) -> None:
-        nonlocal _cumulative_partial_chars, _partials_truncated
+        nonlocal _cumulative_partial_chars, _partials_truncated, error_seen
         line = raw_line.rstrip("\r")
         c = classify_line(line)
         kind = c["kind"]
@@ -689,7 +694,15 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
                 if options.on_protocol_line:
                     options.on_protocol_line(line)
         elif kind == "partial":
-            if streaming and options.on_partial and not _partials_truncated:
+            # Spec 5.4: post-error partials are discarded (not forwarded, not
+            # appended). on_protocol_line still fires so debug traces stay
+            # complete.
+            if (
+                not error_seen
+                and streaming
+                and options.on_partial
+                and not _partials_truncated
+            ):
                 remaining = _max_chars - _cumulative_partial_chars
                 if len(c["value"]) >= remaining:
                     if remaining > 0:
@@ -703,11 +716,14 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
             if options.on_protocol_line:
                 options.on_protocol_line(line)
         elif kind == "text":
-            text_chunks.append(c["value"])
+            # Spec 5.4: post-error text is discarded.
+            if not error_seen:
+                text_chunks.append(c["value"])
             if options.on_protocol_line:
                 options.on_protocol_line(line)
         elif kind == "error":
             result.error = c["value"]
+            error_seen = True
             if options.on_error:
                 options.on_error(c["value"])
             if options.on_protocol_line:
@@ -750,20 +766,28 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
                     try:
                         decision = options.on_permission(req)
                         if isinstance(decision, dict):
+                            # Spec: when the bridge omits updated_input, the
+                            # response MUST omit it too — the agent (or wrapped
+                            # CLI) is responsible for falling back to the
+                            # request's original input. Don't auto-fill
+                            # req["input"] here: that would erase the
+                            # distinction between "user accepted unchanged"
+                            # and "user never touched it" for downstream CLIs
+                            # (e.g. Claude Code's updatedInput semantics).
                             updated = decision.get("updated_input")
                             if updated is None and "updatedInput" in decision:
                                 updated = decision.get("updatedInput")
-                            if updated is None:
-                                updated = req.get("input")
-                            _write_permission_response({
+                            response_decision: Dict[str, Any] = {
                                 "request_id": req["request_id"],
                                 "behavior": (
                                     "allow" if decision.get("behavior") == "allow"
                                     else "deny"
                                 ),
-                                "updated_input": updated if isinstance(updated, dict) else req.get("input"),
                                 "message": decision.get("message"),
-                            })
+                            }
+                            if isinstance(updated, dict):
+                                response_decision["updated_input"] = updated
+                            _write_permission_response(response_decision)
                     except Exception as exc:  # noqa: BLE001 — surface to agent as deny
                         if options.on_stderr:
                             options.on_stderr(
@@ -849,23 +873,24 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
         exit_code = proc.wait()
 
     _close_stdin()
-    stdout_thread.join(timeout=5)
-    # Drain stderr fully before running post-mortem diagnosis. The diagnosis
-    # reads the full capture, so we need the drain thread to have caught up.
-    # Generous timeout since the process has already exited — at most we wait
-    # for the pipe buffer to flush.
-    stderr_thread.join(timeout=10)
+    # Process has exited. Drain threads should hit EOF on their pipes within
+    # milliseconds and finish. The hard timeout here is a backstop for the
+    # rare case a grandchild inherited the stderr fd and is still alive — it
+    # keeps the runner from hanging indefinitely without letting drain latency
+    # balloon past the kill_grace_secs budget. 1s each = at most ~2s of extra
+    # latency; diagnosis may be incomplete if it fires, but the post-mortem
+    # stderr patterns target interpreter-startup errors that land in the
+    # first bytes of stderr anyway, well within the 1MB head capture.
+    stdout_thread.join(timeout=1)
+    stderr_thread.join(timeout=1)
     if stderr_thread.is_alive():
-        # Very rare; indicates a pathological agent that keeps stderr open.
-        # The diagnosis may be incomplete, but we don't want to hang forever.
         if options.on_stderr:
             options.on_stderr("[agentproc runner] warning: stderr drain timed out; diagnosis may be incomplete")
 
     # Reply body = concatenation of {"type":"text"} events (direct, no separator).
     result.reply = "".join(text_chunks)
     if len(result.reply) > profile["max_reply_chars"]:
-        suffix = "\n\n…(truncated)" if profile["max_reply_chars"] == DEFAULT_MAX_REPLY_CHARS else ""
-        result.reply = result.reply[: profile["max_reply_chars"]] + suffix
+        result.reply = result.reply[: profile["max_reply_chars"]] + profile["truncation_suffix"]
 
     # If the agent exited non-zero with no error event, peek at its stderr for
     # common "command/file not found" patterns and surface a friendly hint.

{agentproc-0.7.0 → agentproc-0.8.0}/src/agentproc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.7.0
+Version: 0.8.0
 Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc

{agentproc-0.7.0 → agentproc-0.8.0}/src/agentproc.egg-info/SOURCES.txt

@@ -84,6 +84,7 @@ tests/test_bridges.py
 tests/test_conformance.py
 tests/test_diagnostics.py
 tests/test_hub.py
+tests/test_hub_bridge_conformance.py
 tests/test_runner.py
 tests/test_scenarios.py
 tests/test_sdk.py

agentproc-0.8.0/tests/test_hub_bridge_conformance.py

@@ -0,0 +1,144 @@
+"""Hub bridge engine conformance (wire 0.3).
+
+Drives the shared ``hub/_shared/stream_utils.run_bridge`` with a minimal
+identity ``parse_event`` against the shared
+``spec/conformance/hub_bridge.json`` fixture. The Node SDK runs the same
+fixture in ``sdk/node/src/hub_bridge_conformance.test.js``.
+
+Together they guarantee the Python and Node hub bridge engines agree on
+multi-line interaction semantics that ``run_bridge`` owns: error-mid-stream
+preserving session, session-discovered-at-end ordering, empty-message +
+attachment accepted, exit-code mapping, partial-as-reply fallback.
+
+Per-CLI ``parse_event`` variations are NOT covered here — each hub profile
+has its own ``test_bridges.py`` cases for that. This file pins the engine.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pytest
+
+HUB_ROOT = Path(__file__).resolve().parents[3] / "hub"
+SDK_PYTHON_ROOT = Path(__file__).resolve().parents[1]
+if str(HUB_ROOT) not in sys.path:
+    sys.path.insert(0, str(HUB_ROOT))
+
+from _shared.stream_utils import EventResult, run_bridge  # noqa: E402
+
+FIXTURE_PATH = Path(__file__).resolve().parents[3] / "spec" / "conformance" / "hub_bridge.json"
+
+
+def _load_scenarios():
+    data = json.loads(FIXTURE_PATH.read_text(encoding="utf-8"))
+    return [pytest.param(s, id=s["name"]) for s in data["scenarios"]]
+
+
+def _identity_parse_event(event: dict) -> "EventResult | None":
+    t = event.get("type")
+    if t == "partial":
+        return EventResult(partial_text=event.get("text", ""))
+    if t == "text":
+        return EventResult(final_text=event.get("text", ""))
+    if t == "session":
+        sid = event.get("id")
+        return EventResult(session_id=sid) if isinstance(sid, str) else None
+    if t == "error":
+        return EventResult(error=event.get("message", ""))
+    return None
+
+
+def _identity_build_args(_message: str, _session_id: str, _env) -> list[str]:
+    # Returned argv is never actually executed — the test patches
+    # subprocess.Popen with a fake proc. The list just needs a recognizable
+    # argv[0] for error messages.
+    return ["fake-cli"]
+
+
+# ---------------------------------------------------------------------------
+# Fake subprocess for run_bridge
+# ---------------------------------------------------------------------------
+
+
+class _FakePipe:
+    def __init__(self, lines: List[str]):
+        self._lines = list(lines)
+
+    def __iter__(self):
+        for line in self._lines:
+            yield line + "\n"
+
+    def read(self):
+        return ""
+
+
+class _StderrReader:
+    def __init__(self, text: str):
+        self._text = text
+
+    def read(self):
+        return self._text
+
+
+class _FakeProc:
+    def __init__(self, ndjson_lines: List[str], returncode: int, stderr: str):
+        self.stdout = _FakePipe(ndjson_lines)
+        self.stderr = _StderrReader(stderr)
+        self.returncode = returncode
+
+    def wait(self):
+        return self.returncode
+
+
+@pytest.mark.parametrize("scenario", _load_scenarios())
+def test_hub_bridge_conformance(scenario: dict, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture) -> None:
+    turn = scenario["turn"]
+    cli_stdout = scenario.get("cli_stdout", [])
+    cli_exit = scenario.get("cli_exit", 0)
+    cli_stderr = scenario.get("cli_stderr", "")
+
+    def _fake_popen(args, *a, **kw):  # noqa: ANN001 — signature mirrors subprocess.Popen
+        return _FakeProc(cli_stdout, cli_exit, cli_stderr)
+
+    monkeypatch.setattr("subprocess.Popen", _fake_popen)
+
+    exit_code = run_bridge(
+        cli_name="fake-cli",
+        cli_install_hint="install hint",
+        build_args=_identity_build_args,
+        parse_event=_identity_parse_event,
+        turn=turn,
+    )
+
+    captured = capsys.readouterr()
+    actual_lines = [line for line in captured.out.split("\n") if line]
+
+    expect = scenario["expect"]
+    assert exit_code == expect["exit_code"], (
+        f"{scenario['name']}: exit got {exit_code}, expected {expect['exit_code']}"
+    )
+
+    if "stdout_lines" in expect:
+        assert actual_lines == expect["stdout_lines"], (
+            f"{scenario['name']}: stdout got {actual_lines!r}, expected {expect['stdout_lines']!r}"
+        )
+        return
+
+    if "stdout_lines_any_of" in expect:
+        candidates = expect["stdout_lines_any_of"]
+        assert any(actual_lines == cand for cand in candidates), (
+            f"{scenario['name']}: stdout got {actual_lines!r}, expected any of {candidates!r}"
+        )
+        return
+
+    if "stdout_lines_contains" in expect:
+        joined = "\n".join(actual_lines)
+        for needle in expect["stdout_lines_contains"]:
+            assert needle in joined, (
+                f"{scenario['name']}: expected substring {needle!r} in stdout, got {joined!r}"
+            )

{agentproc-0.7.0 → agentproc-0.8.0}/tests/test_runner.py

@@ -97,6 +97,15 @@ class TestPermissionHelpers:
             {"request_id": "2", "behavior": "deny", "message": "nope"}
         ) == '{"type":"permission_response","request_id":"2","behavior":"deny","message":"nope"}'
 
+    def test_format_allow_without_updated_input_omits_field(self):
+        # allow without updated_input MUST omit the field — the agent/CLI is
+        # responsible for falling back to the request's original input. The
+        # runner must not pre-fill it (would erase the "user accepted
+        # unchanged" vs "user never touched it" distinction downstream).
+        assert format_permission_response(
+            {"request_id": "3", "behavior": "allow"}
+        ) == '{"type":"permission_response","request_id":"3","behavior":"allow"}'
+
     def test_is_valid(self):
         assert is_valid_permission_request({"request_id": "1", "tool_name": "Bash", "input": {}})
         assert not is_valid_permission_request({"request_id": "1", "tool_name": "Bash"})
@@ -265,6 +274,22 @@ class TestNormalizeProfile:
         p2 = normalize_profile({"command": "x", "env_inherit": "all"})
         assert "env_inherit" not in p2
 
+    def test_truncation_suffix_defaults_to_ellipsis(self):
+        p = normalize_profile({"command": "x"})
+        assert p["truncation_suffix"] == "\n\n…(truncated)"
+
+    def test_truncation_suffix_custom_value_is_honoured(self):
+        # A custom cap no longer silently strips the truncation notice —
+        # users get the default suffix unless they explicitly override.
+        p = normalize_profile({"command": "x", "max_reply_chars": 100})
+        assert p["truncation_suffix"] == "\n\n…(truncated)"
+        p2 = normalize_profile({"command": "x", "truncation_suffix": " [more]"})
+        assert p2["truncation_suffix"] == " [more]"
+
+    def test_truncation_suffix_empty_string_disables_notice(self):
+        p = normalize_profile({"command": "x", "truncation_suffix": ""})
+        assert p["truncation_suffix"] == ""
+
     def test_permission_defaults_false(self):
         assert normalize_profile({"command": "x"})["permission"] is False
         assert normalize_profile({"command": "x", "permission": True})["permission"] is True

{agentproc-0.7.0 → agentproc-0.8.0}/tests/test_scenarios.py

@@ -75,6 +75,16 @@ def test_scenario_conformance(scenario: dict, tmp_path: Path) -> None:
     assert r.exit_code == expect["exit_code"], (
         f"{scenario['name']}: exit_code got {r.exit_code!r}, expected {expect['exit_code']!r}"
     )
-    assert partials == expect["partials"], (
-        f"{scenario['name']}: partials got {partials!r}, expected {expect['partials']!r}"
-    )
+    # partials comparison: when `partials_any_of` is present, the scenario
+    # accepts any of the listed candidate sequences (used for spec-loose
+    # semantics like whether to emit a tail-truncated chunk vs nothing).
+    # Otherwise the strict `partials` equality applies.
+    if "partials_any_of" in expect:
+        candidates = expect["partials_any_of"]
+        assert any(partials == cand for cand in candidates), (
+            f"{scenario['name']}: partials got {partials!r}, expected any of {candidates!r}"
+        )
+    else:
+        assert partials == expect["partials"], (
+            f"{scenario['name']}: partials got {partials!r}, expected {expect['partials']!r}"
+        )

{agentproc-0.7.0 → agentproc-0.8.0}/tests/test_sdk.py

@@ -42,10 +42,14 @@ def _run_scenario(scenario: dict) -> subprocess.CompletedProcess:
         "PYTHONPATH": str(SRC_DIR),
     }
     turn_line = json.dumps(scenario["turn"]) + "\n"
+    # Scenarios that exercise the optional permission channel follow the turn
+    # with one or more {"type":"permission_response",...} frames the harness
+    # reads via ctx.read_permission_response().
+    extra = "".join(line + "\n" for line in scenario.get("stdin_after_turn", []))
     return subprocess.run(
         [sys.executable, str(HARNESS), scenario["handler"]],
         env=env,
-        input=turn_line,
+        input=turn_line + extra,
         capture_output=True,
         text=True,
     )