agent-lab/docs/plans/todo-43-typed-provider-tool-calls.md

Todo 43 Typed Provider Tool Calls Plan

Status: done

Result

• Added distinct text_event and provider_tool_call stream kinds.
• Preserved provider IDs plus parsed/raw arguments and ordered multiple calls.
• Added exactly-once flush behavior for providers that omit finish_reason.
• Follow-up todos 43.1 and 43.2 repaired legacy consumers and removed production acceptance of the compatibility event kind.
• Verified with focused regressions and the full suite (82 passed, one existing Starlette deprecation warning).

Goal

Preserve native provider tool calls as a distinct stream item so direct ChatAgent tools can retain provider-generated IDs and arguments without changing the existing hidden text-event protocol.

Scope

• Keep text protocol output as name-only events for dual-agent mode.
• Represent provider-native tool calls with a separate stream kind.
• Preserve id, name, parsed arguments, and raw arguments from the provider.
• Flush buffered provider tool calls when a compatible provider ends with [DONE] but omits the expected tool-call finish reason.
• Do not change Runtime tool routing or provider transcript serialization in this todo.

Files

• Modify: src/agent_lab/domain/messages.py
• Modify: src/agent_lab/infrastructure/openai_compatible.py
• Modify: tests/test_openai_stream_parser.py
• Modify: tests/test_debug_runtime.py
• Modify: docs/plans/todos.md

Plan

Plan

1. Add failing parser tests for distinct event sources.
2. Verify the tests fail because provider calls and text events currently share kind="event".
3. Add explicit StreamItem.text_event(...) and StreamItem.provider_tool_call(...) constructors while keeping the event payload as ToolCallEvent.
4. Update the text-event parser to emit text_event and the provider tool-call accumulator to emit provider_tool_call.
5. Make parser flush drain buffered provider calls exactly once when no finish reason was received.
6. Update existing Runtime regression fixtures to accept only text_event in the current dual-agent path; direct routing remains out of scope.

Act

Follow TDD in this order:

• Add test_parser_distinguishes_text_events_from_provider_tool_calls asserting:
  • visible text remains message_delta;
  • <agent_events>mock_search</agent_events> produces kind="text_event";
  • provider delta.tool_calls produces kind="provider_tool_call" with intact arguments.
• Add test_parser_flushes_provider_tool_calls_without_finish_reason using fragmented name/argument chunks followed by flush() and asserting one call is emitted.
• Add test_parser_does_not_emit_provider_tool_call_twice_after_finish_and_flush to protect normal providers.
• Run uv run pytest tests/test_openai_stream_parser.py -q and confirm the new tests fail for the missing typed kinds/flush behavior.
• Implement the minimum domain/parser changes.
• Run the focused parser tests until green.
• Run uv run pytest tests/test_debug_runtime.py tests/test_event_agent.py tests/test_openai_stream_parser.py -q to verify the existing dual-agent path still passes.

Observe

Confirm from test output and inspection that:

• text events remain name-only;
• provider calls retain raw and parsed arguments;
• multiple provider calls preserve provider order/index;
• flush emits only buffered calls that were not already drained;
• no Runtime direct-tools behavior was added early.

Update

• Mark only todo 43 as done after focused and regression tests pass.
• If review finds a defect after the commit, add a new 43.1 row directly below todo 43 instead of modifying any completed historical todo row.
• Commit with a message explaining that the previous shared event kind discarded the distinction required for direct tools; mention compatibility risk if any provider-specific flush behavior remains.

Verification

• uv run pytest tests/test_openai_stream_parser.py -q
• uv run pytest tests/test_debug_runtime.py tests/test_event_agent.py tests/test_openai_stream_parser.py -q
• git diff --check