feature/durable turns and heartbeats

[jvjvjv]

• fix: never discard an interrupted turn
• docs: spec, plan and openspec change for heartbeats and durable turns
• feat: emit heartbeats during idle provider reads
• feat: forward stream heartbeats to the browser as comment frames
• feat: add turn run and turn event models
• feat: add TurnRunStore for detached turn events
• feat: run a conversation turn as a queued job
• feat: add resumable turn event reader
• fix: page the turn reader's terminal drain instead of reading once
• feat: add dispatchTurn, resumeTurn and cancelTurn
• feat: add ai:prune-turn-events command
• fix: page the turn-event prune sweep and make run terminality explicit
• fix: dispatch turn jobs after commit and correct the resumeTurn docblock
• docs: document heartbeats and dispatched turns for 0.15.0
• chore: check off completed durable-turns-and-heartbeats tasks
• fix: keep heartbeats out of stored turn events and fail runs on provider errors
• docs: record deferred review findings for the durable-turns change

[Copilot]

🟡 Changes recommended

There are a few confirmed correctness edge cases (notably _seq construction and heartbeat parser detach fallback) that can silently break resumable replay or drop provider output.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR introduces “durable turns” (turn execution detached into a queued job with resumable replay) and “heartbeats” (keep-alive ticks during provider/store silence) to prevent interrupted turns from being discarded, improve abandonment detection, and support browser reconnect/resume semantics.

Changes:

• Add heartbeat emission during idle provider SSE reads and forward heartbeats to browsers as SSE comment frames.
• Add durable turn infrastructure: AiTurnRun/AiTurnEvent models + store/reader + queued job execution + retention pruning.
• Update frontend contract/docs to support resumable SSE id: sequencing and new stop/incomplete semantics.

File summaries

File	Description
tests/Feature/TurnRunStoreTest.php	Coverage for sequencing, cancellation/abandonment, throttled stop checks, and finish recording.
tests/Feature/TurnEventStreamTest.php	Coverage for replay/resume behavior, terminal drain, SSE id framing, and polling touch behavior.
tests/Feature/StreamTranslatorTest.php	Ensures stop_reason becomes incomplete when a stream never cleanly ended.
tests/Feature/RunConversationTurnJobTest.php	Verifies job-driven turn execution records events and sets run terminal state correctly.
tests/Feature/ReasoningOpenAiCompatibleGatewayTest.php	Exercises idle-gap heartbeat behavior and parser correctness across split frames.
tests/Feature/PruneTurnEventsCommandTest.php	Validates retention pruning deletes terminal runs/events while preserving live runs and supports “disabled” retention.
tests/Feature/ConversationUsageServiceTest.php	Ensures aborted turns still count toward token usage totals.
tests/Feature/ChatTurnLibraryTest.php	Verifies heartbeat is encoded as an SSE comment frame and stream still terminates normally.
tests/Feature/AiTurnRunModelTest.php	Covers run public id generation, status terminality, and event uniqueness/payload casting.
tests/Feature/AiPersonaConversationServiceTest.php	Adds tests for dispatch/resume/cancel APIs, heartbeat handling, and interrupted-turn persistence semantics.
src/Services/RawExchange/TeeingStream.php	Adds record() to capture bytes read directly from detached resources.
src/Services/LaravelAi/StreamTranslator.php	Tracks open-stream state to return stop_reason: incomplete when appropriate.
src/Services/LaravelAi/Streaming/Heartbeat.php	New stream-event type used to surface heartbeat ticks through laravel/ai streaming.
src/Services/LaravelAi/ReasoningOpenAiCompatibleGateway.php	Uses idle-read heartbeat parsing and forwards Heartbeat events through processing.
src/Services/LaravelAi/Concerns/HeartbeatsIdleSseReads.php	Implements timeout-bounded SSE reading with a partial-line buffer and heartbeat yields.
src/Services/ConversationUsageService.php	Counts both success and aborted interaction logs when summarizing usage.
src/Services/Conversation/TurnRunStore.php	Implements single-writer event sequencing, cancellation/abandonment logic, and throttled stop checks.
src/Services/Conversation/TurnEventStream.php	Streams stored events with replay/resume cursoring, terminal drain, heartbeat synthesis, and read ceiling.
src/Services/ChatBot/SseFrameEncoder.php	Encodes heartbeats as SSE comments and _seq as SSE id: while stripping from payload.
src/Services/ChatBot/Conversation/TurnRecorder.php	Persists interrupted turns (even empty), adds incomplete metadata, and logs aborted status appropriately.
src/Services/ChatBot/Conversation/ConversationTurnRunner.php	Forwards heartbeat events without logging/storing them and ensures guards can evaluate during silence.
src/Services/ChatBot/ChatBotPresenter.php	Surfaces incomplete on transcript rows based on stored message metadata.
src/Services/AiPersonaConversationService.php	Adds dispatchTurn(), resumeTurn(), and cancelTurn() durable-turn APIs.
src/Models/AiTurnRun.php	New model for durable turn runs with status/timestamp casts and ordered events relation.
src/Models/AiTurnEvent.php	New model for durable turn events with payload casting and created-at defaulting.
src/Jobs/RunConversationTurnJob.php	Queued execution of turns that records events, skips heartbeat storage, and finalizes run state.
src/Enums/AiTurnRunStatus.php	New status enum with isTerminal() used by reader/job/store semantics.
src/Enums/AiInteractionStatus.php	Adds Aborted status to represent caller-hung-up turns.
src/Console/Commands/PruneTurnEventsCommand.php	Adds ai:prune-turn-events retention command with paging.
src/CodeTalkerServiceProvider.php	Registers and schedules turn-event pruning alongside existing scheduled jobs.
resources/js/types/code-talker.d.ts	Updates client contract: incomplete transcript field, StopReason includes incomplete, documents heartbeat omission from wire union.
resources/js/code-talker-stream.ts	Adds onSequence callback by parsing SSE id: for resume support.
README.md	Documents detached turns, heartbeat behavior/encoding, and interrupted turn semantics.
openspec/changes/durable-turns-and-heartbeats/tasks.md	Implementation task checklist for the change set.
openspec/changes/durable-turns-and-heartbeats/specs/chat-turn-library/spec.md	Spec updates for heartbeat + resumable SSE id framing + durable turns lifecycle.
openspec/changes/durable-turns-and-heartbeats/proposal.md	Proposal describing motivation, constraints, and scope.
openspec/changes/durable-turns-and-heartbeats/design.md	Design summary referencing deeper design/plan docs.
openspec/changes/durable-turns-and-heartbeats/deferred-findings.md	Deferred review findings tracked for later follow-up.
docs/superpowers/specs/2026-08-31-durable-turns-and-heartbeats-design.md	Detailed design document for heartbeats + durable turns.
docs/superpowers/plans/2026-08-31-durable-turns-and-heartbeats.md	Detailed implementation plan and constraints checklist.
database/migrations/2026_08_31_000002_create_ai_turn_events_table.php	Adds ai_turn_events schema with unique (run, sequence).
database/migrations/2026_08_31_000001_create_ai_turn_runs_table.php	Adds ai_turn_runs schema for durable turn lifecycle.
config/code-talker.php	Adds conversations.heartbeat_seconds and new turns.* config block.
CHANGELOG.md	Documents 0.15.0 breaking changes, new features, and bug fixes for durable turns/heartbeats.

Review details

Suppressed comments (1)

src/Services/Conversation/TurnEventStream.php:67

• Same _seq override issue as above: using array union with $event->payload on the left allows an _seq key in the stored payload to mask the actual sequence, breaking resumable replay cursors.

                        /** @var AiTurnEvent $event */
                        $after = $event->sequence;

                        yield $event->payload + ['_seq' => $event->sequence];
                    }

• Files reviewed: 43/44 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.