mirror of
https://github.com/getpaseo/paseo.git
synced 2026-07-29 12:01:31 +00:00
fa1198c2be
* fix(app): stop completed turns from appearing stuck Turn activity was inferred from a user-message row flag, so a stale duplicate row could keep the working footer active after the turn ended. Track submission lifecycle separately and route every send path through the shared submission flow. * fix(app): guard pending message identity * test(app): measure submission layout independent of scroll * fix(app): keep submitted messages consistent through reconnects Track each in-flight send until its own RPC establishes acceptance, and keep canonical timeline placement authoritative. Restore legacy cached rewind IDs during cache deserialization. * fix(app): close canonical submission races * test(app): cover canonical submission races in browser * fix(app): keep replacement submissions authoritative Keep current pending rows out of legacy cache migration and leave ambiguous terminal lifecycle events to the daemon snapshot. This prevents fabricated rewind identities and stale completion events from marking replacement turns idle. * fix(app): keep submitted messages stable across sync Give submission transport and canonical timeline ingestion separate authority. Preserve every unresolved local send across replacement, reconcile provider identity once, and bridge RPC acceptance to authoritative running state without deriving lifecycle from timeline rows. * fix(app): settle submissions in either acknowledgement order Complete submission transactions when RPC and provider acknowledgement arrive in either order. Cache only transaction-owned local rows as transient data, preserve canonical ID-less prompts, and invalidate ambiguous legacy display caches instead of inventing provider identity. * fix(app): keep agent visible during history handoff Running and terminal updates could clear create continuity before the initial authoritative timeline arrived, leaving a streaming agent behind the loading screen. End the handoff only when authoritative history is applied. * fix(app): settle attachment-only submissions Canonical providers can acknowledge image-only prompts with empty text. Reconcile those events by client identity without rendering a blank canonical row. * fix(agent): settle out-of-band message submissions Accepted commands that do not allocate a foreground turn previously had no canonical user acknowledgement. Record the command before its handler runs so submission state and reconnect history converge through the normal timeline producer. * fix(app): settle out-of-band submissions compatibly * fix(app): preserve canonical prompt order * test(app): keep workspace status check timing-independent The workspace-status scenario asserted footer settlement before initial agent creation had necessarily completed. The dedicated draft-handoff coverage owns that lifecycle contract.
134 lines
8.6 KiB
Markdown
134 lines
8.6 KiB
Markdown
# Timeline sync
|
|
|
|
Agent chat delivery has two paths:
|
|
|
|
1. **Live stream** — `agent_stream` WebSocket messages for immediacy. These may be delta-shaped lifecycle updates.
|
|
2. **Authoritative history** — `fetch_agent_timeline_request` for correctness. This always returns full projected timeline items, never lifecycle deltas.
|
|
|
|
The invariant is:
|
|
|
|
> If the daemon has committed timeline rows for an agent, any connected client that opens or resumes that agent eventually displays every row through the daemon's current tail.
|
|
|
|
Tool output is bounded before it enters either delivery path. Canonical shell tool output is sliced
|
|
to 64 KiB, and the same bounded item is used for durable timeline rows and live stream events.
|
|
Provider history hydration applies the same rule so reopening an agent cannot restore an oversized
|
|
tool payload.
|
|
|
|
## Presence is not delivery
|
|
|
|
Client heartbeat reports presence:
|
|
|
|
- device type
|
|
- app visibility
|
|
- focused agent
|
|
- last activity time
|
|
|
|
Heartbeat is used for notification routing. It must not be used as a correctness gate for `agent_stream` delivery. A stale mobile focus heartbeat may affect whether the user gets notified; it must not make timeline rows disappear from the live stream.
|
|
|
|
## Catch-up is paged but complete
|
|
|
|
Large unbounded timeline responses can exceed relay frame limits, so catch-up uses bounded pages. Bounded does not mean partial.
|
|
|
|
Page limits are projected-item targets. A tool call lifecycle is one projected item even if it spans many source sequence numbers, and assistant/reasoning chunks are merged before counting. The response carries `seqStart`, `seqEnd`, `sourceSeqRanges`, and `collapsed` so clients can advance sequence cursors without rendering delta rows.
|
|
|
|
When the app fetches `direction: "after"` and the daemon responds with `hasNewer: true`, the app must immediately fetch the next page from `endCursor`. The catch-up is complete only when `hasNewer: false`.
|
|
|
|
Initialization timeouts guard lack of catch-up progress, not the full multi-page sync. A successful page that queues the next `after` page refreshes the watchdog.
|
|
|
|
The first load of an agent without a local cursor is different: it fetches a bounded latest tail page. Older history remains user-driven by scrolling upward.
|
|
|
|
## Durable item anchors
|
|
|
|
Provider message IDs are not guaranteed for every displayed item. Paseo-generated system errors are one example. Rendered item indices are not durable either because pagination and projection can merge source rows.
|
|
|
|
Actions that address a point in chat history, such as Fork, use the daemon timeline `epoch` plus the projected item's `seqEnd`. The app carries that position on the rendered assistant item for both live and fetched history. When adjacent projected chunks merge, the merged item retains the newer chunk's position.
|
|
|
|
The daemon validates that the epoch is current and the exact source sequence still exists before slicing rows. It slices before projection so later lifecycle updates cannot leak into the selected context.
|
|
|
|
## Resume behavior
|
|
|
|
When a client resumes with a known cursor, it catches up after that cursor to completion. It does not replace the view with a latest tail page, because tail pagination can skip the middle of a long background run.
|
|
|
|
When a client resumes without a cursor, it fetches the latest tail page.
|
|
|
|
## Client replica lifetime
|
|
|
|
The host runtime owns each session replica for as long as the host remains registered. React
|
|
providers attach message handlers and UI integrations to that replica, but mounting or unmounting a
|
|
provider must not create or clear it. A provider can remount during Fast Refresh or ordinary UI
|
|
recomposition while the runtime still owns the same directory snapshot and timeline cursors.
|
|
|
|
Removing the host from the registry is the destructive boundary: it stops the runtime and clears the
|
|
session and host-scoped setup state together.
|
|
|
|
## Selective and legacy delivery
|
|
|
|
The app chooses one delivery policy from `server_info.features.selectiveAgentTimeline`:
|
|
|
|
- Selective daemons receive the union of agents visible in every pane. Additions subscribe and
|
|
catch up immediately. Every visibility-driven removal, including app backgrounding, stays
|
|
subscribed for a 30-second grace period so brief tab, pane, route, and app switches do not repeatedly
|
|
unsubscribe and catch up. Losing window keyboard focus does not make a selected pane invisible.
|
|
Disconnecting and disposal clear pending grace because the subscription itself no longer exists.
|
|
After grace has expired, revisiting a retained timeline displays its cached state immediately and
|
|
authoritative catch-up advances it to the current tail.
|
|
- Legacy daemons keep globally streaming agent timelines. Visibility still triggers the existing
|
|
authoritative catch-up, but the app does not issue selective-subscription RPCs.
|
|
|
|
This policy is owned by `viewed-timeline-sync.ts`; downstream reducers do not branch on daemon
|
|
version.
|
|
|
|
## Projected pages reconcile with live presentation
|
|
|
|
A projected page is canonical state, not a sequence of live deltas. One projected item can overlap
|
|
rows already received live—for example, a tool call retained at its original display position while
|
|
its completion advances `seqEnd`, followed by a merged assistant message. The app uses
|
|
`sourceSeqRanges` to replace overlapping assistant and reasoning projections before applying the
|
|
remaining page through the existing stream reducer. It must not append full projected text to a
|
|
live prefix.
|
|
|
|
Every path that sends a message to an agent — composer send, dictation accept-and-send, queued
|
|
send-now, and the automatic queue drain in `HostRuntime` — goes through
|
|
`dispatchComposerAgentMessage` with a submission writer. There is no second transport for the same
|
|
product action: calling `client.sendAgentMessage` directly skips the submitted row and the pending
|
|
footer, and permanently drops attachments because the daemon does not echo them back.
|
|
|
|
A submitted prompt is one `UserMessageItem` row. That row is the authoritative local presentation:
|
|
its stable identity, text, timestamp, images, and attachments do not change when the provider
|
|
acknowledges it. Submission lifecycle is a separate record keyed by agent, not another row shape or
|
|
a property inferred from message identity. The transaction registry holds every unresolved send and
|
|
records RPC acceptance and provider acknowledgement independently. Provider acknowledgement exists
|
|
solely so a later transport error cannot roll back a prompt already observed canonically.
|
|
|
|
The daemon's accepted response already waits for the correlated run start, but its response and the
|
|
directory update reach client state separately. An accepted transaction remains active until the
|
|
directory observes that run or canonical ingestion acknowledges the prompt, bridging those ordered
|
|
authorities without inspecting timeline snapshots. Either signal clears only an RPC-accepted
|
|
transaction, regardless of which arrived first; it cannot settle a fresh send.
|
|
Overlapping sends settle independently rather than collapsing to one newest pending message.
|
|
|
|
Canonical submitted user rows carry the provider's `messageId` and Paseo's optional
|
|
`clientMessageId`. The user-message producer reconciles them by `clientMessageId`, adds provider
|
|
identity to the existing row, and keeps the local presentation in its original timeline slot.
|
|
Content matching is limited to the dated compatibility path for daemon timelines created before
|
|
that field existed. Canonical ingestion may match only an explicit unreconciled local candidate;
|
|
the draft-create handoff is the one boundary that also permits the legacy canonical twin to have
|
|
arrived first. Generic reducers and consumers do not reimplement message identity matching.
|
|
|
|
Ordinary bootstrap, same-epoch reset, and catch-up replacement preserve unmatched locally submitted
|
|
rows because a provider may never echo them. A known epoch change or rewind replaces history and
|
|
drops acknowledged local rows omitted by the new canonical epoch; every transaction not yet
|
|
acknowledged by the provider, and no other local row, crosses that destructive boundary.
|
|
|
|
Canonical replacement owns both timeline lanes. A matching local row keeps its presentation ID and
|
|
payload while taking the canonical row's ordered position. If a live assistant head is the
|
|
canonical assistant prefix, it stays in the head lane. No row may be returned in both lanes.
|
|
|
|
## Relevant code
|
|
|
|
- Server live stream forwarding: `packages/server/src/server/session.ts`
|
|
- App sync planning: `packages/app/src/timeline/timeline-sync-plan.ts`
|
|
- App viewed-agent synchronization: `packages/app/src/timeline/viewed-timeline-sync.ts`
|
|
- App stream/timeline reducer: `packages/app/src/timeline/session-stream-reducers.ts`
|
|
- Session wiring: `packages/app/src/contexts/session-context.tsx`
|