Skip to content

The agent that grows with you

fix(api): session chat stream emits tool lifecycle events under the session authority

David Dudok de Witf284d84301f7
diff --git a/gateway/run_turn_progress.py b/gateway/run_turn_progress.py
index 0b246ea4b8f..32779095d93 100644
--- a/gateway/run_turn_progress.py
+++ b/gateway/run_turn_progress.py
@@ -87,8 +87,17 @@ def publish_worker_tool_event(authority, session_id, generation, frame) -> bool:
verbose = getattr(authority.sessions[session_id], "tool_progress_mode", None) == "verbose"
payload = _tool_complete_payload(call_id, name, args, result, is_error=frame["is_error"], verbose=verbose)
authority.publish_execution(session_id, generation, kind, payload)
- from gateway.session_api_turn import publish_api_tool_event
+ from gateway.session_api_turn import publish_api_tool_event, publish_api_tool_progress
publish_api_tool_event(authority, session_id, generation, kind, call_id, name, args, result)
+ # A worker sends no progress events: progress-only observers get the executor's preview of its
+ # args and the frame's own verdict, taken before the result was bounded.
+ if kind == "tool.start":
+ from agent.display import build_tool_preview
+ publish_api_tool_progress(authority, session_id, generation, "tool.started", name,
+ build_tool_preview(name, args), args)
+ else:
+ publish_api_tool_progress(authority, session_id, generation, "tool.completed", name, None, None,
+ is_error=frame["is_error"], result=result)
return True
diff --git a/gateway/session_api_turn.py b/gateway/session_api_turn.py
index c0bc81d480c..3ac39727032 100644
--- a/gateway/session_api_turn.py
+++ b/gateway/session_api_turn.py
@@ -18,6 +18,7 @@ _SETTINGS_PREFIX = 'gateway.api.settings.v1.'
# Request-owned sinks an API observer may register for its admission's execution.
_OBSERVER_KEYS = ('stream_delta_callback', 'tool_start_callback', 'tool_complete_callback',
'reasoning_callback', 'status_callback', 'interim_assistant_callback')
+_TOOL_SINKS = {'tool_start_callback', 'tool_complete_callback'}
_SETTING_KEYS = ('ephemeral_system_prompt', 'requested_model', 'requested_provider',
'model_options', 'route', 'session_model', 'confirmed_runtime_lock',
'requested_runtime', 'route_source', 'room_dispatch', 'room_execution_policy',
@@ -392,6 +393,10 @@ async def observe_api_turn(admitted, **kwargs):
if observers is None:
observers = authority.api_observers = {}
observer = {key: kwargs[key] for key in _OBSERVER_KEYS if kwargs.get(key) is not None}
+ if kwargs.get('tool_progress_callback') is not None and not observer.keys() & _TOOL_SINKS:
+ # Progress-only (the session chat stream): the producer's own tool.started / tool.completed
+ # events with its preview and failure verdict. Structured observers keep only theirs.
+ observer['tool_progress_callback'] = kwargs['tool_progress_callback']
registered = observers.setdefault(row['admission_id'], [])
registered.append(observer)
try:
@@ -504,8 +509,8 @@ def _notify_observers(authority, session_id, key, *args, **kwargs):
def wire_api_observers(agent, owner, want_interim):
"""Hand this admission's API observers (Chat/Responses SSE, runs) the agent's reasoning,
- status and commentary callbacks, the ones the direct API path gave the agent itself. Each
- event is fenced to the exact running claim, so a settled worker's late callback is inert;
+ status, commentary and tool progress callbacks, the ones the direct API path gave the agent
+ itself. Each event is fenced to the exact running claim, so a settled worker's late callback is inert;
the turn's own status/commentary sinks keep running after the observers."""
authority, session_id, generation = owner
@@ -528,8 +533,16 @@ def wire_api_observers(agent, owner, want_interim):
publish('interim_assistant_callback', text, already_streamed=already_streamed)
if interim is not None:
interim(text, already_streamed=already_streamed)
+ progress = agent.tool_progress_callback
+
+ def tool_progress_callback(event_type, *args, **kwargs):
+ if event_type in ('tool.started', 'tool.completed'):
+ publish_api_tool_progress(authority, session_id, generation, event_type, *args, **kwargs)
+ if progress is not None:
+ return progress(event_type, *args, **kwargs)
agent.reasoning_callback = lambda text: publish('reasoning_callback', text)
agent.status_callback = status_callback
+ agent.tool_progress_callback = tool_progress_callback
if want_interim:
agent.interim_assistant_callback = interim_assistant_callback
@@ -540,6 +553,17 @@ def publish_api_event(authority, session_id, event_type, payload):
return False
+def publish_api_tool_progress(authority, session_id, generation, *args, **kwargs):
+ """A ``tool_progress_callback`` tool event as its producer emitted it, for the admission's
+ progress-only observers; never inferred again from formatted or bounded result text."""
+ with authority.sessions[session_id].event_stream.lock:
+ try:
+ authority.check_approval_generation(session_id, generation)
+ except RuntimeStoreError:
+ return
+ _notify_observers(authority, session_id, 'tool_progress_callback', *args, **kwargs)
+
+
def publish_api_tool_event(authority, session_id, generation, event_type, call_id, tool_name, args, result=None):
"""Real tool arguments/results for the admission's API observers (Responses streaming,
runs SSE); never part of the shared viewer event stream."""
diff --git a/tests/gateway/test_api_canonical_projection.py b/tests/gateway/test_api_canonical_projection.py
index 1e5ea197c3b..73fc67d7551 100644
--- a/tests/gateway/test_api_canonical_projection.py
+++ b/tests/gateway/test_api_canonical_projection.py
@@ -127,6 +127,16 @@ def _wrap(api, run_id, loop, sink):
return callback
+def _wired_agent(turn):
+ """The agent's tool sinks as TurnRunner wires them for an API admission."""
+ from gateway.session_api_turn import wire_api_observers
+ agent = SimpleNamespace(tool_progress_callback=None, status_callback=None, interim_assistant_callback=None,
+ tool_start_callback=turn.combined_tool_start_callback,
+ tool_complete_callback=turn.combined_tool_complete_callback)
+ wire_api_observers(agent, turn._approval_owner, False)
+ return agent
+
+
@pytest.mark.asyncio
async def test_responses_streaming_projects_real_tool_arguments_and_results(api, owner):
from gateway.session_api_turn import observe_api_turn
@@ -137,12 +147,77 @@ async def test_responses_streaming_projects_real_tool_arguments_and_results(api,
async def handle(event):
from gateway.session_results import execution_result
turn = _turn_runner(owner, ref)
+ progress_cb = _wired_agent(turn).tool_progress_callback
+ if progress_cb: # the executor fires it only when wired
+ progress_cb('tool.completed', 'read_file', None, None, is_error=False)
turn.combined_tool_complete_callback('call-9', 'read_file', {'path': 'a.txt'}, 'file body')
execution_result.get()['result'] = {'final_response': 'ok'}
return 'ok'
owner.runner._handle_message = handle
- await observe_api_turn(admitted, tool_complete_callback=lambda *a: seen.append(a))
- assert seen == [('call-9', 'read_file', {'path': 'a.txt'}, 'file body')]
+ progress = [] # Responses also passes a progress sink; it must not get the tools a second time
+ await observe_api_turn(admitted, tool_complete_callback=lambda *a: seen.append(a),
+ tool_progress_callback=lambda *a, **kw: progress.append(a))
+ assert seen == [('call-9', 'read_file', {'path': 'a.txt'}, 'file body')] and progress == []
+
+
+async def _session_stream_tool_frames(api, owner, produce):
+ """POST /api/sessions/{id}/chat/stream under the authority -> its tool.* (event, data) frames."""
+ import json
+
+ async def handle(event):
+ from gateway.session_results import execution_result
+ produce(_turn_runner(owner, SimpleNamespace(session_id=event.source.chat_id)))
+ execution_result.get()['result'] = {'final_response': 'done', 'messages': []}
+ return 'done'
+ owner.runner._handle_message = handle
+ api._api_key = 'request-scope-key-long-enough'
+ owner.db.create_session('stream-tools', source='api_server')
+ app = web.Application()
+ app.router.add_post('/api/sessions/{session_id}/chat/stream', api._handle_session_chat_stream)
+ async with TestClient(TestServer(app)) as client:
+ response = await client.post('/api/sessions/stream-tools/chat/stream', json={'message': 'run tools'},
+ headers={'Authorization': 'Bearer ' + api._api_key})
+ text = await response.text()
+ assert 'event: run.completed' in text, text
+ frames = [dict(line.split(': ', 1) for line in block.splitlines() if ': ' in line) for block in text.split('\n\n')]
+ return [(f['event'], json.loads(f['data'])) for f in frames if f.get('event', '').startswith('tool.')]
+
+
+async def test_session_chat_stream_carries_the_producers_tool_verdict_and_preview(api, owner):
+ """A Codex command that exits 1 with no output is tool.failed (its result text is only "[exit 1]"),
+ and the start frame keeps Codex's own 120-character preview, as the direct progress path does."""
+ from agent.codex_runtime import make_codex_app_server_event_bridge
+
+ def produce(turn):
+ bridge = make_codex_app_server_event_bridge(_wired_agent(turn))
+ for item in ({'type': 'commandExecution', 'id': 'x1', 'command': 'echo ' + 'x' * 500, 'exitCode': 1,
+ 'aggregatedOutput': ''},
+ {'type': 'commandExecution', 'id': 'x2', 'command': 'true', 'exitCode': 0, 'aggregatedOutput': 'ok'}):
+ bridge({'method': 'item/started', 'params': {'item': item}})
+ bridge({'method': 'item/completed', 'params': {'item': item}})
+ frames = await _session_stream_tool_frames(api, owner, produce)
+ names, preview = [name for name, _ in frames], frames[0][1]['preview'] if frames else ''
+ assert (names, len(preview)) == (['tool.started', 'tool.failed', 'tool.started', 'tool.completed'], 120)
+
+
+async def test_session_chat_stream_keeps_a_bounded_worker_failure(api, owner):
+ """A managed worker bounds a large failing terminal result into an envelope with no exit_code;
+ the stream reports the frame's own verdict, tool.failed."""
+ import json
+ from agent.managed_worker import tool_frame
+ from gateway.run_turn_progress import publish_worker_tool_event
+
+ def produce(turn):
+ authority, session_id, generation = turn._approval_owner
+ args, result = {'command': 'make'}, json.dumps({'output': 'x' * 70000, 'exit_code': 1})
+ publish_worker_tool_event(authority, session_id, generation, {'type': 'tool.start', **tool_frame('w1', 'terminal', args)})
+ publish_worker_tool_event(authority, session_id, generation,
+ {'type': 'tool.complete', **tool_frame('w1', 'terminal', args, result)})
+ frames = await _session_stream_tool_frames(api, owner, produce)
+ assert [name for name, _ in frames] == ['tool.started', 'tool.failed'], frames
+ assert frames[0][1]['preview'] == 'make', frames
@pytest.mark.asyncio