Define shared operator turn/task state protocol for TUI and webchat

[njfio]

Problem statement

Tau does not have a first-class shared operator turn/task state model. The runtime emits low-level provider and tool activity, while the TUI and webchat each reconstruct their own view from logs, ad hoc events, and endpoint-specific payloads. This causes missing assistant output, weak progress feedback, divergent behavior between TUI and webchat, and poor recoverability when turns fail or time out.

Acceptance criteria

1. Shared state contract defined

• Define a typed operator state/event contract for: turn, task, tool, approval, artifact, memory, cortex, job, and error.
• The contract must support both live streaming updates and snapshot/state-sync reads.

2. Runtime semantics defined

• Define how provider start/progress/partial-output/tool-execution/approval/timeout/cancel/failure states map into the shared contract.
• Failures must preserve actionable phase context instead of collapsing into opaque timeout text.

3. Client consumption rules defined

• Specify how TUI and webchat consume the same contract for transcript, progress, tools, tasks, memory, and artifacts.
• Eliminate log-parsing as the primary UI integration path for operator-visible state.

4. Backwards-compatibility boundaries defined

• Identify what legacy stderr/stdout markers and gateway endpoints remain temporarily supported during migration.
• Define cutover rules so old and new paths do not silently diverge.

5. Test plan defined

• Add acceptance criteria for runtime integration tests, TUI parser/render tests, and web/browser tests that prove both clients render the same turn/task outcomes.

Non-goals

• Full visual redesign in this issue.
• Provider-specific prompt redesign by itself.
• Swarm orchestration design beyond the state primitives it depends on.

Notes

• This issue is the dependency for the TUI and webchat redesign tracks.
• Existing related issues on TUI resilience, memory parity, and tool reliability should build on this contract rather than invent separate UI-specific state paths.

[njfio]

Draft spec created locally at specs/3581-shared-operator-turn-task-state-protocol.md. This issue is the dependency slice for shared runtime/TUI/webchat operator state and should land before client redesign work proceeds.

[njfio]

Spec branch pushed: 3581-shared-operator-turn-task-state-protocol at c8a191e7. Spec link: https://github.com/njfio/Tau/blob/3581-shared-operator-turn-task-state-protocol/specs/3581-shared-operator-turn-task-state-protocol.md

[njfio]

Phase 3 red tests are now committed on 3581-shared-operator-turn-task-state-protocol at a30f1061.

Red failures currently proving the missing shared contract:

• cargo test -p tau-runtime red_spec_3581_event_to_json_emits_operator_state
• cargo test -p tau-gateway functional_openresponses_endpoint_streams_sse_for_stream_true
• cargo test -p tau-gateway tier_pr_a2_agent_session_flow_matrix

Current failure reason: runtime event JSON and gateway SSE payloads do not yet emit operator_state structure for shared turn/task/tool state.

[njfio]

Initial operator_state slice is now implemented on the 3581 branch and remains intentionally scoped to runtime+gateway emission.

New commits:

• 3fd086ad feat(3581): add initial operator state envelope
• 136968eb refactor(3581): centralize operator state payload builders
• f9ec80ac integrate(3581): cover streaming operator state failure path

What landed:

• tau-runtime event JSON now emits initial operator_state envelopes for turn/tool lifecycle events.
• OpenResponses SSE now emits operator_state on response.created, response.output_text.delta, response.output_text.done, response.completed, and response.failed.
• Added real gateway integration coverage for streaming failure-path operator state.

Passing tests on branch 3581-shared-operator-turn-task-state-protocol:

• cargo test -p tau-runtime red_spec_3581_event_to_json_emits_operator_state_for_turn_and_tool_events
• cargo test -p tau-runtime
• cargo test -p tau-gateway functional_openresponses_endpoint_streams_sse_for_stream_true
• cargo test -p tau-gateway integration_spec_3581_openresponses_stream_failure_emits_operator_state
• cargo test -p tau-gateway tier_pr_a2_agent_session_flow_matrix

Issue stays open because AC-4 through AC-7 still require TUI/webchat consumption, migration enforcement, and cross-surface parity.

[njfio]

Added the first webchat consumer slice for the shared operator-state contract on branch 3581-shared-operator-turn-task-state-protocol.

New commits:

• baa76657 test(3581): red tests for webchat operator state contract
• a04a6bfb feat(3581): add webchat response operator state panel
• fa2e9194 refactor(3581): isolate webchat response stream handling
• bc858132 integrate(3581): wire webchat operator state shell coverage

What landed:

• Conversation view now includes a dedicated responseState panel.
• Webchat now explicitly consumes payload.operator_state for /v1/responses SSE lifecycle events.
• Webchat now handles response.created, response.output_text.delta, response.output_text.done, response.completed, and response.failed as first-class stream events instead of only appending deltas/errors.
• /webchat endpoint coverage now asserts the live shell includes the response-state panel and operator-state consumer hook.

Passing tests for this slice:

• cargo test -p tau-gateway red_spec_3581_webchat_page_consumes_operator_state_response_stream_contract
• cargo test -p tau-gateway unit_render_gateway_webchat_page_includes_expected_endpoints
• cargo test -p tau-gateway functional_webchat_endpoint_returns_html_shell
• cargo test -p tau-gateway functional_openresponses_endpoint_streams_sse_for_stream_true
• cargo test -p tau-gateway integration_spec_3581_openresponses_stream_failure_emits_operator_state

Issue remains open: TUI still does not consume the shared contract, and cross-surface parity/migration enforcement are still outstanding.

[njfio]

Completed the TUI consumption and parity slice for #3581 on 3581-shared-operator-turn-task-state-protocol at 06bb3097.

What landed:

• TUI now has a real gateway worker that POSTs to /v1/responses, streams SSE incrementally, and applies shared operator_state events into chat/status/tool state.
• agent mode no longer relies on inherited child stdio for the live path; it launches the interactive TUI with gateway-backed config while preserving the existing dry-run contract.
• tau-unified.sh tui now exports bind/auth/session context for the TUI gateway client.
• Added an integration test that spins a local TCP SSE server and proves streamed operator-state events update the TUI incrementally and end in Idle.

Validation:

• cargo test -p tau-tui
• ./scripts/run/test-tau-unified.sh

This closes the main TUI side of AC-4 and adds parity/integration coverage toward AC-7. Remaining work on #3581 is broader cross-surface parity and any final cleanup around the legacy main entrypoint structure.