zonrad-sdk 0.1.0__tar.gz

zonrad_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: zonrad-sdk
+Version: 0.1.0
+Summary: Python SDK for the Zonrad platform (/platform/v1/) — agents, sessions, runs, tools, and connections.
+Author: Zonrad
+License: Proprietary
+Project-URL: Homepage, https://zonrad.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# Zonrad Python SDK — Quickstart
+
+The Zonrad SDK talks to the `/platform/v1/` boundary of your Zonrad workspace:
+create agents, run them, stream their output, and inspect what they did —
+all from a Python script, with no Django code in sight.
+
+This guide is copy-paste runnable end to end.
+
+## 1. Install
+
+```bash
+pip install zonrad-sdk
+```
+
+The package on PyPI is named `zonrad-sdk` (`zonrad` was already taken), but
+the import is unaffected: `from zonrad import Zonrad`, exactly as below.
+
+Working against an unreleased local checkout of this repo instead? Use
+`pip install -e sdk/python` — same import, no PyPI round trip.
+
+## 2. Get an API key
+
+Every request needs a `PlatformAPIKey`, scoped to exactly one workspace.
+Mint one with an authenticated session (e.g. your zonrad-ui login) against
+the key-management endpoint:
+
+```bash
+curl -X POST https://<your-zonrad-host>/platform/v1/workspaces/<workspace_id>/api-keys \
+  -H "Authorization: Bearer <your JWT access token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my laptop"}'
+```
+
+The response looks like:
+
+```json
+{
+  "id": 1,
+  "name": "my laptop",
+  "prefix": "zk_live_7792c540",
+  "key": "zk_live_7792c540_9dQwhgufdWlqEkq5hZy-fD5IaZffHAHy",
+  "workspace_id": 38,
+  "last_used_at": null,
+  "revoked_at": null,
+  "created_at": "2026-09-18T11:29:08.140046Z"
+}
+```
+
+**Save the `key` and `workspace_id` now** — the raw key is shown exactly
+once and can never be retrieved again (only its prefix, for identifying it
+later). If you lose it, mint a new one and revoke the old.
+
+## 3. Your first agent, session, and run
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+agent = z.agents.create(
+    name="Release Notes Bot",
+    instructions="Summarize engineering updates concisely for a non-technical audience.",
+)
+
+session = z.sessions.new(agent_id=agent["id"])  # lazy — no request sent yet
+run = session.run("Say hello in exactly three words.")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+    elif event["event"] == "response.completed":
+        print()  # final newline
+
+print("session id (assigned by the server):", session.id)
+print("run id:", run.id)
+```
+
+`workspace_id` is set once, at client construction — every resource call
+uses it automatically, since your API key is already scoped to that one
+workspace.
+
+`z.sessions.new()` is lazy: no HTTP request happens until the first
+`.run()`. Use `z.sessions.create(agent_id=...)` instead if you want the
+conversation to exist before you send the first message (e.g. to save its
+`id` before running anything).
+
+## 4. Inspecting a trace
+
+Every run is recorded. If something looks wrong, pull the full trace —
+every model call and tool call, in order, with token counts:
+
+```python
+trace = z.runs.get_trace(run.id)
+for span in trace["spans"]:
+    print(span["type"], span["name"], span.get("total_tokens"))
+```
+
+## 5. Running your own Python function as a tool
+
+`@z.tools.local(...)` registers a plain Python function that runs **on
+this machine** — the agent calls it mid-run, the SDK executes it locally,
+and the conversation continues automatically. No backend deploy, no new
+tool registration anywhere except this script:
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+@z.tools.local()
+def get_local_file(path: str) -> dict:
+    """Reads a file from this machine's filesystem."""
+    with open(path) as f:
+        return {"content": f.read()}
+
+agent = z.agents.create(
+    name="File Assistant",
+    instructions="Use get_local_file to answer questions about files on the user's machine.",
+)
+session = z.sessions.new(agent_id=agent["id"])
+run = session.run("What's in ~/notes.txt?")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+```
+
+That's the whole thing — `run.stream()` sees the model call
+`get_local_file`, runs your function, sends the result back, and keeps
+streaming. You never handle the pause yourself.
+
+The function's parameter types (`str`, `int`, `float`, `bool`, `list`,
+`dict`, `Optional[...]`) are turned into the schema the model sees — same
+rule as the backend's own `register_tool()` below, so a function looks the
+same either way. Every parameter needs a type hint. Give the tool an
+explicit name/description if the function's own name/docstring aren't
+what you want the model to see: `@z.tools.local(name="read_file",
+description="...")`.
+
+**What this can't do:** a name that collides with an existing server-side
+tool, or one your workspace has denied via policy, is rejected with a
+clear error the moment you call `.run()` — not silently ignored. And a
+local tool only exists for runs started by *this* process; it's not
+visible to other users or other scripts, and `z.tools.list()` still only
+shows the server-side registry (see below).
+
+## 6. Adding a tool for everyone (backend registration)
+
+If a tool should be available to any agent in the workspace, not just from
+your own script, register it in the backend repo instead:
+
+```python
+# backend_django/apps/custom_agents/tools/my_tool.py
+from apps.custom_agents.tool_registry import register_tool
+
+@register_tool(
+    id="fetch_release_notes",
+    name="Fetch Release Notes",
+    description="Fetches the latest release notes for a given repo.",
+    risk_level="low",
+)
+def fetch_release_notes(repo: str) -> dict:
+    ...
+    return {"notes": "..."}
+```
+
+This requires a backend deploy and then shows up in `z.tools.list()` for
+everyone — unlike `@z.tools.local(...)`, which is private to the process
+that registered it and needs no deploy at all.
+
+## What's not supported yet
+
+- **Non-Python SDKs.** Python only, for now.
+- **Streaming partial output *from* a local tool.** Your function's return
+  value is submitted as one complete result — there's no equivalent of
+  `response.chunk` for a tool's own execution.
+
+## Reference
+
+```python
+z.agents.list() / .create(**fields) / .get(id) / .update(id, **fields) / .delete(id)
+z.sessions.create(agent_id) / .new(agent_id) / .get(session_id)
+session.run(prompt) -> Run
+run.stream()               # generator of {"event": ..., "data": {...}} dicts — auto-handles local tool calls
+run.get() / .get_trace() / .resume(decision, reason="")
+z.runs.get(run_id) / .get_trace(run_id) / .resume(run_id, decision, reason="")
+z.tools.list() / z.toolkits.list()             # server-side registry (read-only)
+z.tools.local(name=None, description=None, parameters=None)  # decorator — registers a local function
+z.connections.list()
+z.models.list()
+z.policies.get() / .update(**fields)
+z.api_keys.list() / .create(name="") / .revoke(key_id)
+```
+
+A `tool.execution_requested` event your own code never has to handle
+raises `zonrad.ZonradToolNotRegisteredError` internally if no matching
+`@z.tools.local(...)` handler exists — the SDK catches this itself and
+submits it as that call's error, so the run continues rather than your
+script crashing.
+
+Errors raise `zonrad.ZonradAPIError` with `.status_code`, `.error_code`
+(when the server sent one, e.g. `"insufficient_credits"`), and `.body`
+(the full parsed response).

zonrad_sdk-0.1.0/QUICKSTART.md

@@ -0,0 +1,203 @@
+# Zonrad Python SDK — Quickstart
+
+The Zonrad SDK talks to the `/platform/v1/` boundary of your Zonrad workspace:
+create agents, run them, stream their output, and inspect what they did —
+all from a Python script, with no Django code in sight.
+
+This guide is copy-paste runnable end to end.
+
+## 1. Install
+
+```bash
+pip install zonrad-sdk
+```
+
+The package on PyPI is named `zonrad-sdk` (`zonrad` was already taken), but
+the import is unaffected: `from zonrad import Zonrad`, exactly as below.
+
+Working against an unreleased local checkout of this repo instead? Use
+`pip install -e sdk/python` — same import, no PyPI round trip.
+
+## 2. Get an API key
+
+Every request needs a `PlatformAPIKey`, scoped to exactly one workspace.
+Mint one with an authenticated session (e.g. your zonrad-ui login) against
+the key-management endpoint:
+
+```bash
+curl -X POST https://<your-zonrad-host>/platform/v1/workspaces/<workspace_id>/api-keys \
+  -H "Authorization: Bearer <your JWT access token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my laptop"}'
+```
+
+The response looks like:
+
+```json
+{
+  "id": 1,
+  "name": "my laptop",
+  "prefix": "zk_live_7792c540",
+  "key": "zk_live_7792c540_9dQwhgufdWlqEkq5hZy-fD5IaZffHAHy",
+  "workspace_id": 38,
+  "last_used_at": null,
+  "revoked_at": null,
+  "created_at": "2026-09-18T11:29:08.140046Z"
+}
+```
+
+**Save the `key` and `workspace_id` now** — the raw key is shown exactly
+once and can never be retrieved again (only its prefix, for identifying it
+later). If you lose it, mint a new one and revoke the old.
+
+## 3. Your first agent, session, and run
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+agent = z.agents.create(
+    name="Release Notes Bot",
+    instructions="Summarize engineering updates concisely for a non-technical audience.",
+)
+
+session = z.sessions.new(agent_id=agent["id"])  # lazy — no request sent yet
+run = session.run("Say hello in exactly three words.")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+    elif event["event"] == "response.completed":
+        print()  # final newline
+
+print("session id (assigned by the server):", session.id)
+print("run id:", run.id)
+```
+
+`workspace_id` is set once, at client construction — every resource call
+uses it automatically, since your API key is already scoped to that one
+workspace.
+
+`z.sessions.new()` is lazy: no HTTP request happens until the first
+`.run()`. Use `z.sessions.create(agent_id=...)` instead if you want the
+conversation to exist before you send the first message (e.g. to save its
+`id` before running anything).
+
+## 4. Inspecting a trace
+
+Every run is recorded. If something looks wrong, pull the full trace —
+every model call and tool call, in order, with token counts:
+
+```python
+trace = z.runs.get_trace(run.id)
+for span in trace["spans"]:
+    print(span["type"], span["name"], span.get("total_tokens"))
+```
+
+## 5. Running your own Python function as a tool
+
+`@z.tools.local(...)` registers a plain Python function that runs **on
+this machine** — the agent calls it mid-run, the SDK executes it locally,
+and the conversation continues automatically. No backend deploy, no new
+tool registration anywhere except this script:
+
+```python
+from zonrad import Zonrad
+
+z = Zonrad(api_key="zk_live_...", workspace_id=38)
+
+@z.tools.local()
+def get_local_file(path: str) -> dict:
+    """Reads a file from this machine's filesystem."""
+    with open(path) as f:
+        return {"content": f.read()}
+
+agent = z.agents.create(
+    name="File Assistant",
+    instructions="Use get_local_file to answer questions about files on the user's machine.",
+)
+session = z.sessions.new(agent_id=agent["id"])
+run = session.run("What's in ~/notes.txt?")
+
+for event in run.stream():
+    if event["event"] == "response.chunk":
+        print(event["data"]["content"], end="", flush=True)
+```
+
+That's the whole thing — `run.stream()` sees the model call
+`get_local_file`, runs your function, sends the result back, and keeps
+streaming. You never handle the pause yourself.
+
+The function's parameter types (`str`, `int`, `float`, `bool`, `list`,
+`dict`, `Optional[...]`) are turned into the schema the model sees — same
+rule as the backend's own `register_tool()` below, so a function looks the
+same either way. Every parameter needs a type hint. Give the tool an
+explicit name/description if the function's own name/docstring aren't
+what you want the model to see: `@z.tools.local(name="read_file",
+description="...")`.
+
+**What this can't do:** a name that collides with an existing server-side
+tool, or one your workspace has denied via policy, is rejected with a
+clear error the moment you call `.run()` — not silently ignored. And a
+local tool only exists for runs started by *this* process; it's not
+visible to other users or other scripts, and `z.tools.list()` still only
+shows the server-side registry (see below).
+
+## 6. Adding a tool for everyone (backend registration)
+
+If a tool should be available to any agent in the workspace, not just from
+your own script, register it in the backend repo instead:
+
+```python
+# backend_django/apps/custom_agents/tools/my_tool.py
+from apps.custom_agents.tool_registry import register_tool
+
+@register_tool(
+    id="fetch_release_notes",
+    name="Fetch Release Notes",
+    description="Fetches the latest release notes for a given repo.",
+    risk_level="low",
+)
+def fetch_release_notes(repo: str) -> dict:
+    ...
+    return {"notes": "..."}
+```
+
+This requires a backend deploy and then shows up in `z.tools.list()` for
+everyone — unlike `@z.tools.local(...)`, which is private to the process
+that registered it and needs no deploy at all.
+
+## What's not supported yet
+
+- **Non-Python SDKs.** Python only, for now.
+- **Streaming partial output *from* a local tool.** Your function's return
+  value is submitted as one complete result — there's no equivalent of
+  `response.chunk` for a tool's own execution.
+
+## Reference
+
+```python
+z.agents.list() / .create(**fields) / .get(id) / .update(id, **fields) / .delete(id)
+z.sessions.create(agent_id) / .new(agent_id) / .get(session_id)
+session.run(prompt) -> Run
+run.stream()               # generator of {"event": ..., "data": {...}} dicts — auto-handles local tool calls
+run.get() / .get_trace() / .resume(decision, reason="")
+z.runs.get(run_id) / .get_trace(run_id) / .resume(run_id, decision, reason="")
+z.tools.list() / z.toolkits.list()             # server-side registry (read-only)
+z.tools.local(name=None, description=None, parameters=None)  # decorator — registers a local function
+z.connections.list()
+z.models.list()
+z.policies.get() / .update(**fields)
+z.api_keys.list() / .create(name="") / .revoke(key_id)
+```
+
+A `tool.execution_requested` event your own code never has to handle
+raises `zonrad.ZonradToolNotRegisteredError` internally if no matching
+`@z.tools.local(...)` handler exists — the SDK catches this itself and
+submits it as that call's error, so the run continues rather than your
+script crashing.
+
+Errors raise `zonrad.ZonradAPIError` with `.status_code`, `.error_code`
+(when the server sent one, e.g. `"insufficient_credits"`), and `.body`
+(the full parsed response).

zonrad_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zonrad-sdk"
+version = "0.1.0"
+description = "Python SDK for the Zonrad platform (/platform/v1/) — agents, sessions, runs, tools, and connections."
+readme = "QUICKSTART.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Zonrad" }]
+dependencies = [
+    "requests>=2.28",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://zonrad.ai"
+
+[tool.setuptools.packages.find]
+include = ["zonrad*"]

zonrad_sdk-0.1.0/setup.cfg

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

zonrad_sdk-0.1.0/tests/test_client_tools.py

@@ -0,0 +1,239 @@
+import json
+from typing import Optional
+
+import pytest
+
+from zonrad._schema import ToolSchemaError, build_schema_from_function
+from zonrad.exceptions import ZonradToolNotRegisteredError
+from zonrad.resources.runs import Run
+from zonrad.resources.tools import ToolsResource
+
+
+class _FakeClient:
+    workspace_id = 1
+
+    def __init__(self):
+        self.tools = ToolsResource(self)
+        self.submitted = None
+        self._next_continuation_lines = None
+
+    class _HTTP:
+        def __init__(self, outer):
+            self.outer = outer
+
+        def stream(self, method, path, json):
+            self.outer.submitted = {"method": method, "path": path, "json": json}
+            return _FakeStreamResponse(self.outer._next_continuation_lines or [])
+
+    def __getattr__(self, item):
+        if item == "_http":
+            return self._HTTP(self)
+        raise AttributeError(item)
+
+
+class _FakeStreamResponse:
+    def __init__(self, lines):
+        self._lines = lines
+
+    def iter_lines(self, decode_unicode=True):
+        yield from self._lines
+
+
+def _sse_line(event, data):
+    return f"data: {json.dumps({'event': event, 'data': data})}"
+
+
+class TestBuildSchemaFromFunction:
+    def test_primitive_types(self):
+        def fn(a: str, b: int, c: float, d: bool):
+            ...
+        schema = build_schema_from_function(fn)
+        assert schema["properties"]["a"]["type"] == "string"
+        assert schema["properties"]["b"]["type"] == "integer"
+        assert schema["properties"]["c"]["type"] == "number"
+        assert schema["properties"]["d"]["type"] == "boolean"
+        assert set(schema["required"]) == {"a", "b", "c", "d"}
+
+    def test_list_and_dict(self):
+        def fn(items: list, meta: dict):
+            ...
+        schema = build_schema_from_function(fn)
+        assert schema["properties"]["items"]["type"] == "array"
+        assert schema["properties"]["meta"]["type"] == "object"
+
+    def test_optional_excludes_from_required(self):
+        def fn(name: str, nickname: Optional[str] = None):
+            ...
+        schema = build_schema_from_function(fn)
+        assert "nickname" not in schema["required"]
+        assert "name" in schema["required"]
+
+    def test_missing_type_hint_raises(self):
+        def fn(a):
+            ...
+        with pytest.raises(ToolSchemaError):
+            build_schema_from_function(fn)
+
+
+class TestToolsResourceLocal:
+    def test_local_registers_and_lists_specs(self):
+        client = _FakeClient()
+
+        @client.tools.local()
+        def get_weather(city: str) -> dict:
+            """Gets the weather."""
+            return {"city": city, "temp": 72}
+
+        specs = client.tools._local_specs()
+        assert len(specs) == 1
+        assert specs[0]["name"] == "get_weather"
+        assert specs[0]["description"] == "Gets the weather."
+        assert specs[0]["parameters"]["properties"]["city"]["type"] == "string"
+
+    def test_execute_local_happy_path_dict_arguments(self):
+        client = _FakeClient()
+
+        @client.tools.local(name="add")
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        assert client.tools._execute_local("add", {"a": 2, "b": 3}) == 5
+
+    def test_execute_local_defensively_parses_json_string_arguments(self):
+        client = _FakeClient()
+
+        @client.tools.local(name="add")
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        assert client.tools._execute_local("add", json.dumps({"a": 2, "b": 3})) == 5
+
+    def test_execute_local_falls_back_to_empty_dict_for_garbage_input(self):
+        client = _FakeClient()
+
+        @client.tools.local(name="noop")
+        def noop() -> str:
+            return "ok"
+
+        assert client.tools._execute_local("noop", "not json") == "ok"
+        assert client.tools._execute_local("noop", None) == "ok"
+
+    def test_execute_local_raises_for_unregistered_tool(self):
+        client = _FakeClient()
+        with pytest.raises(ZonradToolNotRegisteredError):
+            client.tools._execute_local("nonexistent", {})
+
+
+class TestRunStreamAutoLoop:
+    def _run_with_events(self, lines, client=None):
+        client = client or _FakeClient()
+        resp = _FakeStreamResponse(lines)
+        return Run._from_stream(client, resp), client
+
+    def test_tool_execution_requested_is_handled_transparently(self):
+        client = _FakeClient()
+
+        @client.tools.local(name="get_local_file")
+        def get_local_file(path: str) -> dict:
+            return {"content": f"contents of {path}"}
+
+        first_stream_lines = [
+            _sse_line("agent.status", {"agent_run_id": "run_1", "status": "thinking"}),
+            "",
+            _sse_line("tool.execution_requested", {
+                "agent_run_id": "run_1", "tool": "get_local_file",
+                "tool_call_id": "call_1", "input": {"path": "/tmp/x"}, "batch_size": 1,
+            }),
+            "",
+        ]
+        continuation_lines = [
+            _sse_line("response.completed", {"agent_run_id": "run_1", "content": "Done."}),
+            "",
+        ]
+        client._next_continuation_lines = continuation_lines
+
+        run, _ = self._run_with_events(first_stream_lines, client=client)
+        events = list(run.stream())
+
+        assert [e["event"] for e in events] == ["agent.status", "response.completed"]
+        # Never surfaced tool.execution_requested to the caller.
+        assert not any(e["event"] == "tool.execution_requested" for e in events)
+        # Submitted exactly the local function's real return value.
+        assert client.submitted["json"]["results"] == [
+            {"tool_call_id": "call_1", "output": {"content": "contents of /tmp/x"}, "error": None},
+        ]
+        assert client.submitted["path"].endswith("/runs/run_1/submit-tool-results")
+
+    def test_batch_split_across_buffered_and_live_events_is_unified(self):
+        """Regression: the first draft ran _drain(buffered) then separately
+        _drain(events_iter), which would try to read the dead stream a
+        second time once a batch executed mid-buffer. itertools.chain fixes
+        this — this test exercises a batch_size=2 split across both sources."""
+        client = _FakeClient()
+
+        @client.tools.local(name="tool_a")
+        def tool_a() -> str:
+            return "a"
+
+        @client.tools.local(name="tool_b")
+        def tool_b() -> str:
+            return "b"
+
+        # Only ONE of the two batch events is on the initial (buffered) stream;
+        # Run._from_stream's own buffering (Phase 5) stops once agent_run_id
+        # resolves, so the second call ends up in _events_iter, not buffered.
+        lines = [
+            _sse_line("tool.execution_requested", {
+                "agent_run_id": "run_1", "tool": "tool_a", "tool_call_id": "call_a", "input": {}, "batch_size": 2,
+            }),
+            "",
+            _sse_line("tool.execution_requested", {
+                "agent_run_id": "run_1", "tool": "tool_b", "tool_call_id": "call_b", "input": {}, "batch_size": 2,
+            }),
+            "",
+        ]
+        client._next_continuation_lines = [
+            _sse_line("response.completed", {"agent_run_id": "run_1", "content": "Done."}), "",
+        ]
+
+        run, _ = self._run_with_events(lines, client=client)
+        # Simulate the split: force exactly one event into "buffered" and
+        # leave the rest for the live iterator, matching what _from_stream's
+        # early-break-on-agent_run_id actually produces in practice.
+        assert len(run._buffered_events) == 1
+        events = list(run.stream())
+
+        assert [e["event"] for e in events] == ["response.completed"]
+        submitted_ids = {r["tool_call_id"] for r in client.submitted["json"]["results"]}
+        assert submitted_ids == {"call_a", "call_b"}
+
+    def test_unregistered_client_tool_submits_a_clear_error_instead_of_raising(self):
+        client = _FakeClient()  # no local tools registered at all
+        lines = [
+            _sse_line("tool.execution_requested", {
+                "agent_run_id": "run_1", "tool": "mystery_tool", "tool_call_id": "call_1", "input": {}, "batch_size": 1,
+            }),
+            "",
+        ]
+        client._next_continuation_lines = [
+            _sse_line("response.completed", {"agent_run_id": "run_1", "content": "Done."}), "",
+        ]
+
+        run, _ = self._run_with_events(lines, client=client)
+        events = list(run.stream())  # must not raise
+
+        assert [e["event"] for e in events] == ["response.completed"]
+        result = client.submitted["json"]["results"][0]
+        assert result["output"] is None
+        assert "mystery_tool" in result["error"]
+
+    def test_approval_required_is_not_auto_handled(self):
+        client = _FakeClient()
+        lines = [
+            _sse_line("approval.required", {"agent_run_id": "run_1", "tool": "send_slack", "tool_call_id": "call_1"}),
+            "",
+        ]
+        run, _ = self._run_with_events(lines, client=client)
+        events = list(run.stream())
+        assert [e["event"] for e in events] == ["approval.required"]
+        assert client.submitted is None  # nothing auto-submitted