graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/agents/langgraph/tests/integration/test_approvals_server.py

@@ -0,0 +1,794 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Human approval of gated API calls under the langgraph-server runtime, end to end.
+
+A real LangGraph dev server (`langgraph dev`, a dev dependency of every
+project) serves this app as its custom app, the app's auth handler, and the
+graph of `approval_graph.py`: the agent with one tool whose call the test
+policy gates. The upstream API is a local HTTP server that records every
+request. Principals are JWTs signed with a key made here (`AUTH_POLICY=jwt`).
+The run pauses and resumes through the server's own interrupt and resume.
+Skipped when the LangGraph CLI and its in-memory server are not installed.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+import httpx
+import jwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+PROJECT = Path(__file__).resolve().parents[2]
+AGENT_DIR = PROJECT / "{{cookiecutter.agent_directory}}"
+LANGGRAPH = Path(sys.executable).with_name("langgraph")
+pytestmark = pytest.mark.skipif(
+    not LANGGRAPH.exists() or importlib.util.find_spec("langgraph_api") is None,
+    reason="needs the LangGraph CLI with its in-memory server (langgraph-cli[inmem])",
+)
+
+ISSUER = "https://issuer.test/"
+AUDIENCE = "agent-api"
+KEY = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+A2A_PATH = "/a2a/{{cookiecutter.agent_directory}}"
+TIMEOUT_S = 30  # the policy's approval.timeout_s (its minimum)
+BODY = {"reason": "customer asked"}
+
+POLICY = """
+apis:
+  shop:
+    base_url_env: SHOP_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST]
+    approval:
+      required_for:
+        operations:
+          - operationId: cancelOrder
+            path: /orders/{order_id}/cancel
+            methods: [POST]
+      approvers: [requester, "role:ops"]
+      timeout_s: TIMEOUT
+""".replace("TIMEOUT", str(TIMEOUT_S))
+
+
+def token(user: str, *roles: str) -> dict[str, str]:
+    now = int(time.time())
+    claims = {
+        "sub": user,
+        "iss": ISSUER,
+        "aud": AUDIENCE,
+        "iat": now,
+        "nbf": now,
+        "exp": now + 600,
+        "roles": list(roles or ("user",)),
+    }
+    return {"Authorization": f"Bearer {jwt.encode(claims, KEY, algorithm='RS256')}"}
+
+
+class Upstream(ThreadingHTTPServer):
+    """The API the tool calls: records every request, answers 200."""
+
+    def __init__(self) -> None:
+        self.received: list[tuple[str, str, Any]] = []
+        self.lock = threading.Lock()
+        upstream = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_PATCH(self) -> None:
+                self.do_POST()
+
+            def do_POST(self) -> None:
+                length = int(self.headers.get("content-length") or 0)
+                body = json.loads(self.rfile.read(length) or b"null")
+                with upstream.lock:
+                    upstream.received.append((self.command, self.path, body))
+                payload = json.dumps({"cancelled": self.path}).encode()
+                self.send_response(200)
+                self.send_header("content-type", "application/json")
+                self.send_header("content-length", str(len(payload)))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        super().__init__(("127.0.0.1", 0), Handler)
+
+    def sent_to(self, path: str) -> list[Any]:
+        with self.lock:
+            return [body for _, p, body in self.received if p == path]
+
+
+@dataclass
+class Server:
+    url: str
+    upstream: Upstream
+    body_file: Path
+    log: Path
+    policy: Path
+    expiring: dict[str, Any] = field(default_factory=dict)
+    expiring_native: dict[str, Any] = field(default_factory=dict)
+
+
+def _free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def parse_sse(text: str) -> list[tuple[str, dict[str, Any]]]:
+    events: list[tuple[str, dict[str, Any]]] = []
+    event = None
+    for line in text.splitlines():
+        if line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:") and event:
+            events.append((event, json.loads(line[5:].strip())))
+            event = None
+    return events
+
+
+def post(
+    server: Server, path: str, body: dict[str, Any], headers: dict[str, str]
+) -> httpx.Response:
+    return httpx.post(f"{server.url}{path}", json=body, headers=headers, timeout=60)
+
+
+def pause(server: Server, order: str, user: str = "alice") -> dict[str, Any]:
+    """A run on a new thread that pauses before the gated call; its `message.end`."""
+    return pause_on(server, f"Cancel the order for {order}", user)
+
+
+def pause_on(server: Server, message: str, user: str = "alice") -> dict[str, Any]:
+    """A run on a new thread for `message` that pauses before a gated call; its `message.end`."""
+    r = post(server, "/chat", {"message": message}, token(user))
+    assert r.status_code == 200, r.text
+    events = parse_sse(r.text)
+    assert events[-1][0] == "message.end", events
+    end = events[-1][1]
+    assert end["status"] == "awaiting_approval", end
+    return end
+
+
+def decide(
+    server: Server, end: dict[str, Any], decision: str, headers: dict[str, str]
+) -> httpx.Response:
+    approval = end["approval"]
+    return post(
+        server,
+        f"/threads/{end['thread_id']}/approvals/{approval['approval_id']}",
+        {"decision": decision},
+        headers,
+    )
+
+
+def _write_config(work: Path) -> Path:
+    """The `langgraph.json` a test server runs with: this project, the test graph."""
+    project_config = json.loads((PROJECT / "langgraph.json").read_text(encoding="utf-8"))
+    config = work / "langgraph.json"
+    config.write_text(
+        json.dumps(
+            {
+                "dependencies": [str(PROJECT)],
+                "graphs": {"agent": f"{PROJECT / 'tests/integration/approval_graph.py'}:graph"},
+                "http": {"app": f"{AGENT_DIR / 'fast_api_app.py'}:app"},
+                "auth": {"path": f"{AGENT_DIR / 'app_utils/auth.py'}:auth"},
+                "python_version": project_config.get("python_version", "3.12"),
+            }
+        ),
+        encoding="utf-8",
+    )
+    return config
+
+
+def _server_env(policy: Path, body_file: Path, upstream: Upstream) -> dict[str, str]:
+    pem = (
+        KEY.public_key()
+        .public_bytes(serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo)
+        .decode()
+    )
+    return {
+        **os.environ,
+        "MODEL_PROVIDER": "fake",
+        "MODEL_NAME": "fake",
+        "AUTH_POLICY": "jwt",
+        "AUTH_JWT_PUBLIC_KEY": pem,
+        "AUTH_JWT_ISSUER": ISSUER,
+        "AUTH_JWT_AUDIENCE": AUDIENCE,
+        "APP_ENV": "dev",
+        "RUNTIME": "langgraph-server",
+        "API_POLICY_PATH": str(policy),
+        "SHOP_API_BASE_URL": f"http://127.0.0.1:{upstream.server_address[1]}",
+        "TEST_APPROVAL_BODY_FILE": str(body_file),
+        "TRACING_ENABLED": "false",
+        "LANGSMITH_TRACING": "false",
+        "LANGGRAPH_CLI_NO_ANALYTICS": "1",
+        "PYTHON_DOTENV_DISABLED": "1",
+    }
+
+
+def _start_dev(
+    work: Path, env: dict[str, str], port: int, log: Path, *, reload: bool = False
+) -> subprocess.Popen[bytes]:
+    """`langgraph dev` in `work` (where it keeps its threads, in `.langgraph_api/`), once up.
+
+    With `reload`, a change to a `.py` file under `work` restarts it (a hot reload).
+    """
+    args = [str(LANGGRAPH), "dev", "--config", str(work / "langgraph.json")]
+    args += ["--port", str(port), "--no-browser"] + ([] if reload else ["--no-reload"])
+    with log.open("ab") as out:
+        proc = subprocess.Popen(
+            args, cwd=work, env=env, stdout=out, stderr=subprocess.STDOUT, start_new_session=True
+        )
+    try:
+        _wait_up(proc, f"http://127.0.0.1:{port}", log)
+    except BaseException:
+        _stop(proc)
+        raise
+    return proc
+
+
+def _wait_up(proc: subprocess.Popen[bytes], url: str, log: Path, timeout_s: float = 120) -> None:
+    deadline = time.monotonic() + timeout_s
+    while True:
+        if proc.poll() is not None:
+            pytest.fail(f"langgraph dev exited:\n{log.read_text()[-4000:]}")
+        try:
+            if httpx.get(f"{url}/health", timeout=2).status_code == 200:
+                return
+        except httpx.HTTPError:
+            pass
+        if time.monotonic() > deadline:
+            pytest.fail(f"langgraph dev did not start:\n{log.read_text()[-4000:]}")
+        time.sleep(0.5)
+
+
+@pytest.fixture(scope="module")
+def server(tmp_path_factory: pytest.TempPathFactory) -> Iterator[Server]:
+    work = tmp_path_factory.mktemp("approvals-server")
+    upstream = Upstream()
+    threading.Thread(target=upstream.serve_forever, daemon=True).start()
+    body_file = work / "body.json"
+    body_file.write_text(json.dumps(BODY), encoding="utf-8")
+    policy = work / "api-policy.yaml"
+    policy.write_text(POLICY, encoding="utf-8")
+    _write_config(work)
+    port = _free_port()
+    log = work / "server.log"
+    proc = None
+    try:
+        proc = _start_dev(work, _server_env(policy, body_file, upstream), port, log)
+        url = f"http://127.0.0.1:{port}"
+        running = Server(url=url, upstream=upstream, body_file=body_file, log=log, policy=policy)
+        # Paused first, so they have expired by the time the last tests use them.
+        running.expiring = pause(running, "90")
+        running.expiring_native = pause(running, "91")
+        yield running
+    finally:
+        if proc is not None:
+            _stop(proc)
+        upstream.shutdown()
+        upstream.server_close()
+
+
+def native_run(server: Server, thread: str, body: dict[str, Any]) -> httpx.Response:
+    """A run through the server's own API (not the app's routes), as the thread's owner."""
+    return httpx.post(
+        f"{server.url}/threads/{thread}/runs/wait",
+        json={"assistant_id": "agent", **body},
+        headers=token("alice"),
+        timeout=60,
+    )
+
+
+def paused_checkpoint(server: Server, thread: str) -> str:
+    """The checkpoint where the thread's run paused for the gated call."""
+    r = post(server, f"/threads/{thread}/history", {"limit": 20}, token("alice"))
+    assert r.status_code == 200, r.text
+    return next(
+        h["checkpoint"]["checkpoint_id"]
+        for h in r.json()
+        if any(task.get("interrupts") for task in h.get("tasks") or [])
+    )
+
+
+def rerun_paused_step(server: Server, thread: str, checkpoint: str) -> list[httpx.Response]:
+    """The native runs that run a paused step again: without input, and from its checkpoint."""
+    return [
+        native_run(server, thread, {"input": None}),
+        native_run(server, thread, {"checkpoint_id": checkpoint}),
+    ]
+
+
+def assert_refused_at_the_server(server: Server, thread: str, checkpoint: str) -> None:
+    """Native runs that would run the paused step again, and a copy (which would carry its
+    tool call without the approval), are refused on a thread with approvals."""
+    for r in rerun_paused_step(server, thread, checkpoint):
+        assert r.status_code == 403, r.text
+        assert "the thread has approvals of gated API calls" in r.json()["detail"]
+    r = httpx.post(f"{server.url}/threads/{thread}/copy", headers=token("alice"), timeout=30)
+    assert r.status_code == 403, r.text
+    assert "cannot be copied" in r.json()["detail"]
+
+
+@contextmanager
+def gate_removed(server: Server) -> Iterator[None]:
+    """A new policy that no longer gates the call (a new image, a typo)."""
+    server.policy.write_text(POLICY.split("    approval:")[0], encoding="utf-8")
+    try:
+        yield
+    finally:
+        server.policy.write_text(POLICY, encoding="utf-8")
+
+
+def _stop(proc: subprocess.Popen[bytes]) -> None:
+    """Stop the server and everything it started (its own process group)."""
+    if proc.poll() is not None:
+        return
+    try:
+        os.killpg(proc.pid, signal.SIGTERM)
+        proc.wait(timeout=20)
+    except subprocess.TimeoutExpired:
+        os.killpg(proc.pid, signal.SIGKILL)
+        proc.wait(timeout=10)
+    except ProcessLookupError:
+        pass
+
+
+def test_the_server_pauses_a_gated_call_and_sends_it_once_approved(server: Server) -> None:
+    end = pause(server, "11")
+    approval = end["approval"]
+    assert (approval["method"], approval["path"]) == ("POST", "/orders/11/cancel")
+    assert approval["body"] == BODY and approval["approvers"] == ["requester", "role:ops"]
+    assert server.upstream.sent_to("/orders/11/cancel") == []
+    thread = end["thread_id"]
+    # Pending: no new message on the thread.
+    r = post(server, "/chat", {"message": "hello", "thread_id": thread}, token("alice"))
+    assert r.status_code == 409 and r.json()["code"] == "approval_pending"
+    # Not an approver.
+    r = decide(server, end, "approve", token("bob"))
+    assert r.status_code == 403 and r.json()["code"] == "not_an_approver"
+    # The server's native API cannot resume the run around the approval route.
+    r = httpx.post(
+        f"{server.url}/threads/{thread}/runs/wait",
+        json={
+            "assistant_id": "agent",
+            "command": {"resume": {"x": {"type": "api_approval_decision", "decision": "approve"}}},
+        },
+        headers=token("alice"),
+        timeout=30,
+    )
+    assert r.status_code == 403, r.text
+    # Nor start a new run on it (which would abandon the pending approval): 409, as /chat.
+    r = httpx.post(
+        f"{server.url}/threads/{thread}/runs/wait",
+        json={
+            "assistant_id": "agent",
+            "input": {"messages": [{"role": "user", "content": "hello"}]},
+        },
+        headers=token("alice"),
+        timeout=30,
+    )
+    assert r.status_code == 409, r.text
+    assert "approval_pending" in r.json()["detail"]
+    assert server.upstream.sent_to("/orders/11/cancel") == []
+    # The requester approves: the run resumes and the call is sent, once.
+    r = decide(server, end, "approve", token("alice"))
+    assert r.status_code == 200, r.text
+    events = parse_sse(r.text)
+    assert events[0][1]["approval_id"] == approval["approval_id"]
+    result = next(d for e, d in events if e == "tool.result")
+    assert result["is_error"] is False
+    assert json.loads(result["result"])["acting_as"] == "alice"
+    assert events[-1][1]["status"] == "ok"
+    assert server.upstream.sent_to("/orders/11/cancel") == [BODY]
+    again = decide(server, end, "approve", token("alice"))
+    assert again.status_code == 409 and again.json()["code"] == "approval_not_pending"
+    assert server.upstream.sent_to("/orders/11/cancel") == [BODY]
+    listed = httpx.get(f"{server.url}/threads/{thread}/approvals", headers=token("alice"))
+    assert listed.json()[0]["status"] == "approved"
+
+
+def test_the_server_sends_nothing_on_reject(server: Server) -> None:
+    end = pause(server, "12")
+    r = decide(server, end, "reject", token("carol", "ops"))
+    assert r.status_code == 200, r.text
+    result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+    assert result["is_error"] is True and "was not approved" in result["result"]
+    assert server.upstream.sent_to("/orders/12/cancel") == []
+
+
+def test_a_role_approver_decides_and_the_run_acts_as_the_requester(server: Server) -> None:
+    end = pause(server, "13")
+    r = decide(server, end, "approve", token("carol", "ops"))
+    assert r.status_code == 200, r.text
+    result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+    assert json.loads(result["result"])["acting_as"] == "alice"
+    assert server.upstream.sent_to("/orders/13/cancel") == [BODY]
+
+
+# One API, other approvers for other calls: the requester confirms updates and
+# cancellations, and a second person holding role:admin approves new orders.
+RULES_POLICY = """
+apis:
+  shop:
+    base_url_env: SHOP_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST, PATCH]
+    approval:
+      - required_for:
+          operations:
+            - {operationId: updateOrder, path: "/orders/{order_id}", methods: [PATCH]}
+            - {operationId: cancelOrder, path: "/orders/{order_id}/cancel", methods: [POST]}
+        approvers: [requester]
+      - required_for:
+          operations:
+            - {operationId: createOrder, path: /orders, methods: [POST]}
+        approvers: ["role:admin"]
+        timeout_s: 3600
+"""
+
+
+@contextmanager
+def approval_rules(server: Server) -> Iterator[None]:
+    """The test policy with a list of approval rules, for the time of one test."""
+    server.policy.write_text(RULES_POLICY, encoding="utf-8")
+    try:
+        yield
+    finally:
+        server.policy.write_text(POLICY, encoding="utf-8")
+
+
+def test_each_call_waits_for_the_approvers_of_the_rule_that_gates_it(server: Server) -> None:
+    admin = token("root", "admin")
+    with approval_rules(server):
+        # An update: the requester's rule. Neither another user nor an admin decides it.
+        end = pause_on(server, "Amend the gift note for 61")
+        approval = end["approval"]
+        assert (approval["operation_id"], approval["approvers"]) == ("updateOrder", ["requester"])
+        for headers in (token("bob"), admin):
+            r = decide(server, end, "approve", headers)
+            assert r.status_code == 403 and r.json()["code"] == "not_an_approver", r.text
+        r = decide(server, end, "approve", token("alice"))
+        assert r.status_code == 200, r.text
+        assert server.upstream.sent_to("/orders/61") == [{"note": "gift"}]
+
+        # A cancellation: the requester's rule too; an admin may not decide it either.
+        end = pause_on(server, "Cancel the order for 62")
+        assert end["approval"]["approvers"] == ["requester"]
+        assert decide(server, end, "approve", admin).status_code == 403
+        assert decide(server, end, "approve", token("alice")).status_code == 200
+        assert server.upstream.sent_to("/orders/62/cancel") == [BODY]
+
+        # A new order: role:admin's rule, with its own expiry. The requester may not
+        # approve it, even holding the role (four eyes); another admin may.
+        end = pause_on(server, "Place a new one for GADGET-63")
+        approval = end["approval"]
+        assert (approval["operation_id"], approval["approvers"]) == ("createOrder", ["role:admin"])
+        assert approval["body"] == {"item": "GADGET-63"}
+        lifetime = datetime.fromisoformat(approval["expires_at"]) - datetime.fromisoformat(
+            approval["created_at"]
+        )
+        assert lifetime.total_seconds() == 3600
+        for headers in (token("alice"), token("alice", "admin"), token("bob", "ops")):
+            r = decide(server, end, "approve", headers)
+            assert r.status_code == 403, r.text
+        assert server.upstream.sent_to("/orders") == []
+        r = decide(server, end, "approve", admin)
+        assert r.status_code == 200, r.text
+        result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+        assert json.loads(result["result"])["acting_as"] == "alice"
+        assert server.upstream.sent_to("/orders") == [{"item": "GADGET-63"}]
+
+
+def test_the_server_refuses_a_request_changed_after_approval(server: Server) -> None:
+    end = pause(server, "14")
+    server.body_file.write_text(json.dumps({"reason": "changed"}), encoding="utf-8")
+    try:
+        r = decide(server, end, "approve", token("alice"))
+    finally:
+        server.body_file.write_text(json.dumps(BODY), encoding="utf-8")
+    assert r.status_code == 200, r.text
+    result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+    assert result["is_error"] is True
+    assert "differs from the request that was approved" in result["result"]
+    assert server.upstream.sent_to("/orders/14/cancel") == []
+
+
+def test_the_server_binds_a_decision_to_its_call_when_the_gate_is_removed(
+    server: Server,
+) -> None:
+    """A new policy without the gate while two calls wait: neither decision sends."""
+    rejected, approved = pause(server, "17"), pause(server, "18")
+    server.policy.write_text(POLICY.split("    approval:")[0], encoding="utf-8")
+    try:
+        r = decide(server, rejected, "reject", token("alice"))
+        assert r.status_code == 200, r.text
+        result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+        assert result["is_error"] is True and "an approver rejected it" in result["result"]
+        r = decide(server, approved, "approve", token("carol", "ops"))
+        assert r.status_code == 200, r.text
+        result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+        assert result["is_error"] is True
+        assert "approval gate the policy no longer has" in result["result"]
+    finally:
+        server.policy.write_text(POLICY, encoding="utf-8")
+    assert server.upstream.sent_to("/orders/17/cancel") == []
+    assert server.upstream.sent_to("/orders/18/cancel") == []
+
+
+def test_a_native_replay_does_not_send_a_rejected_call_once_its_gate_is_removed(
+    server: Server,
+) -> None:
+    """Rejected, then un-gated: continuing or replaying the paused step sends nothing."""
+    end = pause(server, "20")
+    thread = end["thread_id"]
+    checkpoint = paused_checkpoint(server, thread)
+    with gate_removed(server):
+        r = decide(server, end, "reject", token("alice"))
+        assert r.status_code == 200, r.text
+        assert_refused_at_the_server(server, thread, checkpoint)
+    assert server.upstream.sent_to("/orders/20/cancel") == []
+
+
+def test_a_native_replay_does_not_send_an_approved_call_a_second_time(server: Server) -> None:
+    """Approved and sent, then un-gated: a replay of the paused step does not send it again."""
+    end = pause(server, "21")
+    thread = end["thread_id"]
+    checkpoint = paused_checkpoint(server, thread)
+    r = decide(server, end, "approve", token("alice"))
+    assert r.status_code == 200, r.text
+    assert server.upstream.sent_to("/orders/21/cancel") == [BODY]
+    with gate_removed(server):
+        assert_refused_at_the_server(server, thread, checkpoint)
+    assert server.upstream.sent_to("/orders/21/cancel") == [BODY]
+
+
+def test_a_thread_without_gated_calls_is_still_copied_and_continued(server: Server) -> None:
+    r = post(server, "/chat", {"message": "hello"}, token("alice"))
+    assert r.status_code == 200, r.text
+    thread = parse_sse(r.text)[-1][1]["thread_id"]
+    r = httpx.post(f"{server.url}/threads/{thread}/copy", headers=token("alice"), timeout=30)
+    assert r.status_code == 200, r.text
+    assert native_run(server, thread, {"input": None}).status_code == 200
+    assert native_run(server, r.json()["thread_id"], {"input": None}).status_code == 200
+
+
+def test_deleting_the_thread_on_the_server_deletes_its_approvals(server: Server) -> None:
+    end = pause(server, "15")
+    thread = end["thread_id"]
+    r = httpx.delete(f"{server.url}/threads/{thread}", headers=token("alice"), timeout=30)
+    assert r.status_code in (200, 204), r.text
+    r = httpx.get(f"{server.url}/threads/{thread}/approvals", headers=token("alice"))
+    assert r.status_code == 404
+    listed = httpx.get(f"{server.url}/approvals", headers=token("alice")).json()
+    assert end["approval"]["approval_id"] not in [a["approval_id"] for a in listed]
+    assert decide(server, end, "approve", token("alice")).status_code == 404
+    assert server.upstream.sent_to("/orders/15/cancel") == []
+
+
+def _rpc(server: Server, method: str, params: dict[str, Any]) -> dict[str, Any]:
+    r = httpx.post(
+        f"{server.url}{A2A_PATH}",
+        json={"jsonrpc": "2.0", "id": "1", "method": method, "params": params},
+        headers={**token("alice"), "A2A-Version": "1.0"},
+        timeout=60,
+    )
+    return r.json()
+
+
+def test_the_server_a2a_task_waits_for_input_and_resumes(server: Server) -> None:
+    sent = _rpc(
+        server,
+        "SendMessage",
+        {
+            "message": {
+                "messageId": "m-1",
+                "role": "ROLE_USER",
+                "parts": [{"text": "Cancel the order for 16"}],
+            }
+        },
+    )
+    task = sent["result"]["task"]
+    assert task["status"]["state"] == "TASK_STATE_INPUT_REQUIRED", task
+    data = next(p["data"] for p in task["status"]["message"]["parts"] if "data" in p)
+    approval = data["approval"]
+    assert approval["path"] == "/orders/16/cancel"
+    done = _rpc(
+        server,
+        "SendMessage",
+        {
+            "message": {
+                "messageId": "m-2",
+                "role": "ROLE_USER",
+                "taskId": task["id"],
+                "contextId": task["contextId"],
+                "parts": [
+                    {"data": {"approval_id": approval["approval_id"], "decision": "approve"}}
+                ],
+            }
+        },
+    )
+    assert done["result"]["task"]["status"]["state"] == "TASK_STATE_COMPLETED", done
+    assert server.upstream.sent_to("/orders/16/cancel") == [BODY]
+
+
+def test_a_tool_output_holding_a_lone_surrogate_completes_the_run(server: Server) -> None:
+    """UTF-8 cannot encode a lone surrogate: the reply holds U+FFFD in its place.
+
+    The server could not send the tool's update on its own stream: the run
+    failed (`run_failed`) after the tool had acted, over /chat and over A2A.
+    """
+    r = post(server, "/chat", {"message": "Check the gauge for Bergen"}, token("alice"))
+    assert r.status_code == 200, r.text
+    events = parse_sse(r.text)
+    assert events[-1][0] == "message.end" and events[-1][1]["status"] == "ok", events
+    assert [d["result"] for e, d in events if e == "tool.result"] == ["gauge at Bergen:\ufffd42"]
+    sent = _rpc(
+        server,
+        "SendMessage",
+        {
+            "message": {
+                "messageId": "m-gauge",
+                "role": "ROLE_USER",
+                "parts": [{"text": "Check the gauge for Oslo"}],
+            }
+        },
+    )
+    task = sent["result"]["task"]
+    assert task["status"]["state"] == "TASK_STATE_COMPLETED", task
+    reply = "".join(p.get("text", "") for a in task["artifacts"] for p in a["parts"])
+    assert "gauge at Oslo:\ufffd42" in reply
+
+
+def _wait_until_expired(end: dict[str, Any]) -> None:
+    expires = datetime.fromisoformat(end["approval"]["expires_at"])
+    wait = expires.timestamp() - time.time() + 1
+    if wait > 0:
+        time.sleep(wait)
+
+
+def test_a_native_run_does_not_send_an_expired_call_once_its_gate_is_removed(
+    server: Server,
+) -> None:
+    """Near last: an approval paused when the server started has expired by now."""
+    end = server.expiring_native
+    _wait_until_expired(end)
+    thread = end["thread_id"]
+    checkpoint = paused_checkpoint(server, thread)
+    with gate_removed(server):
+        assert decide(server, end, "approve", token("alice")).status_code == 410
+        assert_refused_at_the_server(server, thread, checkpoint)
+    assert server.upstream.sent_to("/orders/91/cancel") == []
+
+
+def test_an_expired_approval_on_the_server_sends_nothing(server: Server) -> None:
+    """Last: the approval paused when the server started has expired by now."""
+    end = server.expiring
+    _wait_until_expired(end)
+    r = decide(server, end, "approve", token("alice"))
+    assert r.status_code == 410 and r.json()["code"] == "approval_expired"
+    thread = end["thread_id"]
+    # Expired = rejected: the thread takes a new message, and the paused call's
+    # result says it was not approved.
+    r = post(server, "/chat", {"message": "hello", "thread_id": thread}, token("alice"))
+    assert r.status_code == 200, r.text
+    assert parse_sse(r.text)[-1][1]["status"] == "ok"
+    messages = httpx.get(f"{server.url}/threads/{thread}/messages", headers=token("alice")).json()
+    tool = next(m for m in messages if m["role"] == "tool")
+    assert "approval request expired" in tool["content"]
+    assert server.upstream.sent_to("/orders/90/cancel") == []
+
+
+# The app's log line each time the server starts it (at startup and on a reload).
+APP_STARTED = "chat runtime started"
+
+
+def _reloaded(proc: subprocess.Popen[bytes], url: str, log: Path, starts: int) -> None:
+    """Wait until the server has started its app once more than `starts` times, and is up."""
+    deadline = time.monotonic() + 120
+    while log.read_text(errors="replace").count(APP_STARTED) <= starts:
+        if proc.poll() is not None or time.monotonic() > deadline:
+            pytest.fail(f"langgraph dev did not reload:\n{log.read_text()[-4000:]}")
+        time.sleep(0.5)
+    _wait_up(proc, url, log)
+
+
+def test_the_dev_server_keeps_the_approvals_with_its_threads(tmp_path: Path) -> None:
+    """`langgraph dev` keeps its threads (in `.langgraph_api/`) across a hot reload and a
+    restart, and the approvals that bind their tool calls with them: once the gate is
+    removed, a run without input or a replay of the paused step sends none of a pending,
+    a rejected, a sent, or an approved but refused call."""
+    upstream = Upstream()
+    threading.Thread(target=upstream.serve_forever, daemon=True).start()
+    body_file = tmp_path / "body.json"
+    body_file.write_text(json.dumps(BODY), encoding="utf-8")
+    policy = tmp_path / "api-policy.yaml"
+    gated = POLICY.replace(f"timeout_s: {TIMEOUT_S}", "timeout_s: 3600")  # nothing expires
+    policy.write_text(gated, encoding="utf-8")
+    _write_config(tmp_path)
+    env = _server_env(policy, body_file, upstream)
+    port = _free_port()
+    url = f"http://127.0.0.1:{port}"
+    log = tmp_path / "server.log"
+    proc = _start_dev(tmp_path, env, port, log, reload=True)
+    try:
+        server = Server(url=url, upstream=upstream, body_file=body_file, log=log, policy=policy)
+        waiting = pause(server, "81")
+        rejected = pause(server, "82")
+        assert decide(server, rejected, "reject", token("alice")).status_code == 200
+        sent = pause(server, "83")
+        assert decide(server, sent, "approve", token("alice")).status_code == 200
+        refused = pause(server, "84")
+        denied = "    denied_operations:\n      - path: /orders/84/cancel\n    approval:"
+        policy.write_text(gated.replace("    approval:", denied), encoding="utf-8")
+        r = decide(server, refused, "approve", token("alice"))
+        policy.write_text(gated, encoding="utf-8")
+        result = next(d for e, d in parse_sse(r.text) if e == "tool.result")
+        assert result["is_error"] is True and "denied_operations" in result["result"]
+        paused = {
+            end["thread_id"]: (end, paused_checkpoint(server, end["thread_id"]))
+            for end in (waiting, rejected, sent, refused)
+        }
+        expected = {"81": [], "82": [], "83": [BODY], "84": []}
+
+        def assert_still_bound() -> None:
+            for thread, (end, _) in paused.items():
+                listed = httpx.get(f"{url}/threads/{thread}/approvals", headers=token("alice"))
+                assert listed.status_code == 200, listed.text
+                ids = [a["approval_id"] for a in listed.json()]
+                assert end["approval"]["approval_id"] in ids, listed.text
+            with gate_removed(server):
+                for thread, (_, checkpoint) in paused.items():
+                    for r in rerun_paused_step(server, thread, checkpoint):
+                        assert r.status_code in (403, 409), r.text
+                message = {"message": "hi", "thread_id": waiting["thread_id"]}
+                r = post(server, "/chat", message, token("alice"))
+                assert r.status_code == 409 and r.json()["code"] == "approval_pending"
+            for order, bodies in expected.items():
+                assert upstream.sent_to(f"/orders/{order}/cancel") == bodies, order
+
+        # A hot reload: a code change in the directory the server watches.
+        starts = log.read_text(errors="replace").count(APP_STARTED)
+        (tmp_path / "changed.py").write_text("CHANGED = True\n", encoding="utf-8")
+        _reloaded(proc, url, log, starts)
+        assert_still_bound()
+        # A restart.
+        _stop(proc)
+        proc = _start_dev(tmp_path, env, port, log)
+        assert_still_bound()
+        ledger = tmp_path / ".langgraph_api" / "agent_approvals.json"
+        assert ledger.stat().st_mode & 0o777 == 0o600
+    finally:
+        _stop(proc)
+        upstream.shutdown()
+        upstream.server_close()