Carlos Florêncio
79 lines
3.1 KiB
Markdown
79 lines
3.1 KiB
Markdown
---
|
|
id: "02-persist-model-warning"
|
|
title: "Persist model-selection warnings"
|
|
status: done
|
|
wave: 2
|
|
depends_on: ["01-executor-model-decision"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/agents/requirements/no-silent-model-fallback.md"
|
|
---
|
|
|
|
# Task 02: Persist model-selection warnings
|
|
|
|
## Acceptance
|
|
|
|
- Every default or explicit fallback emits structured requested, effective, agent, executor, and reason data.
|
|
- The orchestrator persists one warning status message for each session-start decision, and reload hydration returns it.
|
|
- Event replay or message failure does not create duplicates or stop the task launch.
|
|
|
|
## TDD scenarios
|
|
|
|
1. RED: Add lifecycle event tests for explicit fallback, provider default, unknown effective model, and unsupported selection.
|
|
2. RED: Add orchestrator tests for status metadata, idempotency, replay, and persistence errors.
|
|
3. RED: Add gateway tests for the provider-neutral live event and old-event compatibility.
|
|
4. GREEN: Generalize the lifecycle event and persist the semantic warning message.
|
|
5. REFACTOR: Keep the event payload, stored metadata, and WebSocket payload on one shared shape.
|
|
|
|
## Verification
|
|
|
|
- `cd apps/backend && go test -tags fts5 -run 'Test.*ModelSelectionWarning|Test.*ModelFallback' ./internal/agent/runtime/lifecycle ./internal/orchestrator ./internal/gateway/websocket`
|
|
- `cd apps/backend && go test -tags fts5 ./internal/orchestrator ./internal/gateway/websocket`
|
|
- `git diff --check`
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/internal/agentctl/types/streams/agent.go`
|
|
- `apps/backend/internal/agent/runtime/lifecycle/event_types.go`
|
|
- `apps/backend/internal/agent/runtime/lifecycle/events.go`
|
|
- `apps/backend/internal/agent/runtime/lifecycle/session.go`
|
|
- `apps/backend/internal/events/types.go`
|
|
- `apps/backend/internal/orchestrator/event_handlers_streaming.go`
|
|
- `apps/backend/internal/orchestrator/event_handlers_streaming_test.go`
|
|
- `apps/backend/internal/orchestrator/service.go`
|
|
- `apps/backend/internal/gateway/websocket/session_notifications.go`
|
|
- `apps/backend/internal/gateway/websocket/session_notifications_test.go`
|
|
- `apps/backend/pkg/websocket/actions.go`
|
|
|
|
## Dependencies
|
|
|
|
- Task 01 supplies the typed model decision.
|
|
|
|
## Parallelism
|
|
|
|
Sequential after Task 01.
|
|
This task defines the persisted and live warning contracts.
|
|
|
|
## Inputs
|
|
|
|
- The typed decision from Task 01.
|
|
- The current `session_model_fallback` event.
|
|
- The existing `CreateSessionMessage` warning path.
|
|
- The existing task message repository and hydration flow.
|
|
|
|
## Output contract
|
|
|
|
Report the event shape, message metadata, idempotency method, RED evidence, GREEN evidence, and test results.
|
|
|
|
## Risks
|
|
|
|
- The lifecycle event can arrive before the session identity is linked.
|
|
- A blank turn ID must use the existing session-status message convention.
|
|
- Compatibility consumers can still depend on `session.model_fallback`.
|
|
|
|
## Results
|
|
|
|
Implemented structured warning events, idempotent best-effort persistence,
|
|
provider-neutral WebSocket notification, and durable metadata hydration. The
|
|
orchestrator and gateway suites passed with 2,270 tests; the combined backend
|
|
targeted suite passed with 7,299 tests.
|