# Todo 7 Provider Compatibility Plan

**Status:** done

## Result

Implemented by subagent, then documentation was adjusted in `README.md` so the smoke example uses backend model fallback by default and documents `AGENT_LAB_OPENAI_INCLUDE_USAGE`.

Commands:

```bash
uv run pytest tests/test_websocket_api.py tests/test_ws_smoke.py
uv run pytest
uv run python -c "from agent_lab.main import app; print(app.title)"
uv run python scripts/ws_smoke.py --help
```

Results:

- focused provider/API tests: `10 passed, 1 warning in 0.23s`
- full suite: `14 passed, 1 warning in 0.24s`
- import smoke: `Agent Lab`
- smoke helper help: command prints expected options.

## Goal

Fix code-review findings that can break real OpenAI Chat Completions compatible providers.

## Scope

This todo covers:

- Letting backend settings provide the default model when UI/smoke requests do not specify one.
- Role-aware provider message serialization so `tool` messages do not send unsupported `name` fields.
- Configurable `stream_options.include_usage` for providers that reject stream options.
- Tests that lock provider payload shape after tool calls.

This todo does not cover:

- Live network LLM smoke.
- New UI controls beyond model fallback behavior.
- Changing the EventAgent tool set.

## Files

- Modify: `src/agent_lab/application/contracts.py`
- Modify: `src/agent_lab/infrastructure/chat_client.py`
- Modify: `src/agent_lab/settings.py`
- Modify: `src/agent_lab/presentation/static/index.html`
- Modify: `src/agent_lab/presentation/static/app.js`
- Modify: `scripts/ws_smoke.py`
- Modify: `.env.example`
- Modify tests as needed.
- Do not modify: `docs/plans/todos.md`.

## Design

`AgentParams.model` should be optional. If omitted or blank, `OpenAICompatibleChatClient` uses `Settings.openai_default_model`.

Provider message serialization should be role-aware:

- `system`, `user`, `assistant`: include `role`, `content`, and assistant `tool_calls` when present.
- `tool`: include only `role`, `content`, and `tool_call_id`.

Add `Settings.openai_include_usage: bool = True`. When true, send `stream_options: {"include_usage": True}`; when false, omit `stream_options`.

The static UI and smoke helper should send an empty model by default, allowing backend fallback. Users may still provide a model explicitly.

## Steps

1. Add failing tests for:
   - blank request model uses client default model.
   - tool message serialization excludes `name` while preserving `tool_call_id`.
   - `stream_options` is omitted when configured off.
2. Implement optional/blank model support in contracts and client payload.
3. Add role-aware message serialization in the client.
4. Add `AGENT_LAB_OPENAI_INCLUDE_USAGE` setting and `.env.example` entry.
5. Remove hardcoded default model from the static UI and smoke helper request payload defaults.
6. Run:

```bash
uv run pytest tests/test_websocket_api.py tests/test_ws_smoke.py
uv run pytest
uv run python scripts/ws_smoke.py --help
```

## Verification

Expected result:

- Provider payload tests pass.
- Full suite passes.
- Smoke helper help still works.