Native agent conversations
Native agent conversations provide a durable chat layer for agent workspaces. They let a person choose an agent and model settings, send text or files, answer agent requests, queue more work, and return to the same ordered conversation from desktop or mobile.
This page is a child of Agent workspaces. Related areas include agent integrations and hooks, agent protocol client sessions, workspace and worktree lifecycle, AI Vault sessions, and automation services.
Conversation boundary
The native chat layer connects provider sessions to user-facing chat surfaces. The host owns the durable conversation record, while provider adapters turn agent activity into shared conversation events. Desktop and mobile then project those events into a chat view.
The conversation record and provider execution have separate lifetimes. Opening a conversation restores its saved view without starting an agent. A later send, attachment, command, or recovery action starts or resumes provider work only when the session state permits it.
The layer coordinates these responsibilities:
- discover agents, models, and session options in the right account and workspace scope;
- admit prompts, approvals, questions, commands, and attachments;
- hold accepted messages while the current turn is busy;
- record provider output and delivery results in a session journal;
- combine saved history with live events into one ordered timeline;
- distinguish current work from ended or uncertain work;
- recover unfinished work after a host or client restart; and
- present the same conversation on desktop and mobile.
Model discovery and selection
Model selection gives each conversation a scoped view of available models and their controls. It keeps provider evidence separate from user intent so a missing, stale, or refreshed listing does not silently become a confirmed choice.
Catalog scope
The model catalog uses launch configuration, provider account, execution host, workspace path, and observed program or configuration identity to decide when model data is still valid. A saved-only read can use retained choices without starting a provider probe. An incomplete or failed listing means that availability is unknown. It does not prove that no model exists.
Reads for the same scope share one refresh. A caller can stop waiting within its own time budget without cancelling the refresh. Changes to the executable, provider script, or relevant configuration create a new input stamp and prevent old discovery evidence from being reused.
The catalog can use account-level data to seed a workspace view, but it does not use a session pick to decide where discovery runs. Project settings can invalidate an account default without supplying a replacement. When the host cannot inspect the workspace or its settings, the catalog keeps a conservative view.
References: src/…/agent-model-catalog-input-stamp.ts• L11-45 src/…/agent-model-catalog-input-stamp.ts• L46-71 src/…/agent-model-catalog-service.ts• L83-151
Option provenance
Session options record both what the person selected and what the provider applied. The picker can show a catalog default for context, but a default is not treated as a user choice until the host confirms the relevant session state.
A model change can change which effort, speed, tier, or permission controls are valid. The conversation keeps the source of each value, such as saved, policy, picked, applied, or reported. An unlisted current model remains usable as a session choice, but the client does not infer controls that the provider did not report.
References: src/…/structured-agent-session-options.ts• L47-70 src/…/structured-agent-session-options.ts• L99-149 src/…/structured-agent-session-option-snapshot.ts• L30-79 src/…/structured-agent-session-option-models.ts• L1-80
Provider startup
Provider startup establishes the provider session, restores context when possible, and reports the options that startup actually applied. Startup failure becomes part of the conversation state so the surface can explain it and a later action can make a new decision.
The shared contract hides provider differences. A provider can restore a thread or a bounded transcript, but both forms publish enough evidence for the host to label the session state and make the next send safe. Command resolution also respects explicit user commands, host path rules, and managed copies; an explicit command that is not runnable is refused rather than silently replaced.
Attachments follow the host's execution boundary. The provider receives paths that its execution host can read rather than paths that exist only on the client device.
References: src/…/structured-agent-command-resolution.ts• L88-143 src/…/structured-agent-command-resolution.ts• L179-214 src/…/structured-agent-session-host.ts• L33-67 src/…/antigravity-acp-launch-spec.ts• L35-77
Message admission and delivery
Message delivery separates accepting a user action from proving that the provider received it. The host records the operation and its result, then uses provider evidence or a durable operation identity to avoid sending the same action twice after a reconnect.
Message and attachment admission
The composer creates one user message from text, images, files, and still-relevant skill references. A message can contain attachments without text. A file is not ready for send while its upload is incomplete.
The send body has a stable fingerprint for matching a provider echo. Queue mode and selected options remain separate from the body, so the same user content can be recognized without treating client-only sender details as provider input.
The host claims stored attachments in the same transaction as the message or queue write. A required attachment that is missing or already under sweep rejects the action. This prevents cleanup from deleting a file between admission and provider delivery.
References: src/…/structured-agent-session-send-mutation.ts• L14-73 src/…/structured-agent-session-send-mutation.ts• L101-128 src/…/agent-session-attachment-claims.ts• L89-145 src/…/native-chat-text-attachment-references.ts• L1-80
Prompt and approval delivery
An approval or question is a durable conversation item. It stays pending until a client submits a valid answer or the provider ends the request. The host checks the item identity, revision, and current owner before accepting the answer.
The host records the answer before it asks the provider to apply it. If provider delivery is not proved, the conversation shows an unconfirmed result. A retry can replay the earlier receipt instead of applying the answer twice. Some questions may require the terminal, so desktop and mobile show a handoff instead of a chat answer field.
References: src/…/structured-agent-session-turns-prompt.ts• L91-121 src/…/structured-agent-session-turns-prompt.ts• L128-187 src/…/NativeChatApprovalCard.tsx• L1-120 mobile/…/MobileNativeChatView.tsx• L269-300
Conversation commands
Commands use the same durable admission rules as messages. Stop acts on current work. Clear creates a new context boundary in the same conversation. Compaction asks the provider to reduce its working context and can wait behind active work.
The client receives an acknowledgement before a long-running command finishes. The journal records the final result. Messages accepted during compaction remain ordered behind that command rather than entering the provider too early.
References: src/…/structured-conversation-command.ts• L41-59 src/…/structured-conversation-command.ts• L62-130 src/…/structured-agent-session-delivery-loop.ts• L83-145
Queued message flow
The queue lets a person prepare the next turn while the provider is busy. A queued message is accepted user intent, not provider work, so it stays outside the transcript until safe handover.
Queue cards
Each queued message remains a separate card with its own order, text, attachments, and state. It can be edited, removed, sent, or returned to the composer. An edit uses the version seen by the editor so one client cannot overwrite a newer change.
The queue treats blocked sessions, active work, pending prompts, permission changes, and tool changes as different holds. Returned cards and failed sends need attention. A paused queue does not drain by itself, and a card behind a returned card keeps its place and waits.
References: src/…/structured-agent-session-queued-cards.ts• L33-62 src/…/structured-agent-session-queued-cards.ts• L75-99 src/…/structured-agent-session-queued-messages.ts• L38-131 src/…/journal-queue-failure-policy.ts• L1-80
Queue handover
The delivery loop reads the latest journal and provider state before each handover step. It settles work left by an earlier host, starts a provider only when needed, applies the card's saved options, and consumes no more than the next eligible card.
Handover keeps the send in a held state across the pending journal row, provider call, and late settlement. Stop, close, provider exit, or a changed owner can win between those checks. The loop then holds or settles the card instead of sending it into ended work. A failed admission remains recoverable. After handover, the card becomes a normal submission and a matching provider echo adopts that submission so the optimistic row does not appear twice.
The flow from a composer action to a shared view is:
flowchart LR
A[Composer action] --> B[Host admission]
B --> C{Provider busy or waiting for input?}
C -- Yes --> D[Durable queue card]
C -- No --> E[Durable submission]
D --> F[Safe handover]
E --> F
F --> G[Provider turn]
G --> H[Session journal]
H --> I[Desktop and mobile views]
References: src/…/structured-agent-session-handover.ts• L36-49 src/…/structured-agent-session-handover.ts• L79-106 src/…/structured-agent-session-handing-over.ts• L117-177 src/…/journal-domain-automatic-selection.ts• L6-28
Timeline and session journal
The session journal is the host-owned source of truth for a structured conversation. It stores messages, tool work, diffs, prompts, commands, submissions, queue state, and turn facts so live display, history, and recovery use the same record.
Journal state
Journal rows have stable identities and revisions. A revision updates the state of an existing item without moving it to a new visible position. A tombstone prevents a removed item from returning during replay.
The journal also keeps provider-generation and execution provenance. This links rows to provider children and lets the host settle a turn once. Input eligibility and automatic queue selection derive their barriers from the same saved state, so sends, automatic claims, and publication do not disagree about whether work is safe.
Connector deliveries add a durable outbox for external replies. Admission records each delivery with the journal change that created it. The first outcome fill wins, rewinds and queue withdrawals close requests that will not run, and cloud acceptance removes the sent row. This gives an external reply the same recovery path as the conversation action that caused it.
References: src/…/journal-domain-input-eligibility.ts• L16-55 src/…/journal-domain-automatic-selection.ts• L6-28 src/…/journal-connector-replies-schema.ts• L1-30 src/…/journal-connector-replies.ts• L16-72
Provider timeline assembly
Provider adapters translate provider traffic into semantic events. The timeline assembler uses those events to define turns, stable items, streamed text, prompts, context use, command results, and session end.
The same journal rules handle live writes and replayed rows. Only a turn-open event creates a turn. A turn end settles work in that turn. A session end settles work that the host can no longer observe. Events after session end cannot reopen settled work.
Named provider items keep one identity across streamed deltas and final snapshots. Unnamed streams create a message when they start. Text is coalesced for live display and saved through journal snapshots, while a final text close replaces the stream with its final value. Unknown provider frames become bounded status evidence instead of silently disappearing. Child activity remains visible in the parent conversation while each child keeps its own identity.
References: src/…/provider-timeline-assembler.ts• L37-47 src/…/provider-timeline-assembler.ts• L93-133 src/…/provider-timeline-event.ts• L47-112 src/…/provider-timeline-text-stream.ts• L11-29
History and presentation forms
History reads the reduced timeline in bounded windows. The journal can return a client form for current rows and a detail form for a selected item, while older rows use the stored form. This keeps the wire view stable without forcing every reader to load large output.
Forward catch-up can include late revisions that would be missed by reading only from an old creation position. Invalid or cross-epoch cursors cause a clean snapshot instead of a silent gap. Provider history can also be read by turn facts and adopted into the native journal when the provider session has older work.
References: src/…/journal-domain-item-presentation.ts• L20-36 src/…/journal-domain-item-presentation.ts• L38-87 src/…/journal-domain-acp-history.ts• L34-42 src/…/journal-domain-acp-history.ts• L93-177 src/…/agent-session-bounded-frames.ts• L147-199
Current work and quiet turns
Current work answers whether the conversation is working now, waiting for a person, or idle. It combines ownership evidence, pending prompts, owed sends, command state, and journal provenance. Loss of contact alone does not prove that work ended.
The renderer also distinguishes quiet turns from turns that changed something visible. A clean turn with no person-facing result can be hidden after settlement, while a turn that posted, changed an item, started a worker, or failed remains visible. This keeps the transcript short without hiding work that has an effect outside the chat.
References: src/…/structured-agent-session-current-work.ts• L10-11 src/…/structured-agent-session-current-work.ts• L57-104 src/…/native-chat-quiet-turns.ts• L39-91 src/…/native-chat-acting-turns.ts• L38-63
Session lifetime and recovery
Conversation history can remain available after provider execution stops. The host can close an in-memory handle while keeping the journal and waiting cards, then reopen the record without starting an agent until an operation needs one.
Conversation handles
Opening a handle restores the journal and exposes reads, sends, options, prompts, commands, and attachments. Closing releases active resources but keeps the session record and waiting user intent.
Idle eviction and workspace sleep use the same lifetime boundary. The host holds pending sends before stopping so a closed conversation cannot drain work without a new open or explicit action. The status feed retains saved summaries across idle eviction and renderer reload, but it removes live authority when the host no longer owns the provider.
References: src/…/structured-agent-session-conversation-lifetime.ts• L11-12 src/…/structured-agent-session-conversation-lifetime.ts• L92-115 src/…/structured-agent-session-status-feed.ts• L37-69
Restart recovery
After a host restart, saved execution leases enter reconciliation. The host checks the prior owner before granting a new writer or declaring the old generation ended. Reads can remain available during uncertainty, but sends and commands must settle ownership before they act.
Crash settlement records the cut turn, cancelled prompts, and live work that became unverifiable. A restart offer describes that evidence without claiming that an unproven provider exit occurred. Listing offers reserves nothing. An explicit resume action reserves eligible offers, starts continuation, and settles each result. Merely listing an interrupted conversation does not restart it.
Continuation can rebuild the provider context from journal items. Large stored output is exported as bounded transcript text or a temporary spill file, and the export is rejected if the conversation moved past the expected cursor. Clear creates a durable context boundary inside the same conversation. Rewind keeps the retained prefix and replaces only the selected suffix. Old cursors and old-context restart offers do not cross either boundary.
References: src/…/structured-agent-session-crash-cut-marker.ts• L89-143 src/…/structured-agent-session-restart-resume-host.ts• L116-179 src/…/structured-agent-session-restart-resume-host.ts• L219-320 src/…/structured-agent-session-continuation-context.ts• L28-75
Provider exits and journal failures
Every provider child exit becomes a durable lifecycle event. The host settles the related turn, unfinished tool work, prompts, commands, and submissions. It does not restart the child as part of exit handling. The next send uses the normal delivery path.
If the journal cannot be read or written, the conversation refuses unsafe work instead of rebuilding state by guesswork. The host stops the affected provider child and keeps accepted work in a recoverable state. A saved Stop or command proves that the host accepted the action, not that provider wind-down completed.
References: src/…/structured-agent-session-event-recovery.ts• L102-187 src/…/corrupt-journal-reads.ts• L1-120 src/…/journal-sql-failure.ts• L1-80
Desktop and mobile presentation
Desktop and mobile are clients of the same host-owned conversation model. They keep transcript rows, live work, prompts, queue cards, drafts, and delivery results as separate state while presenting one chat to the person.
Desktop presentation
The desktop surface combines the transcript with turn status, prompts, queue cards, commands, model controls, notices, and the composer. It also supports history movement, file links, message actions, and structured child activity without changing journal order.
Transcript slots decide which rows, turn bars, receipts, diffs, pull requests, work runs, and subagent heads need space. Quiet turns can leave with a short fade when they were visible as working; a turn that was already quiet when the chat opened is not drawn.
References: src/…/NativeChatStructuredSession.tsx• L82-155 src/…/NativeChatStructuredSession.tsx• L285-407 src/…/native-chat-transcript-slots.ts• L121-170 src/…/use-native-chat-quiet-turn-leave.ts• L8-48
Mobile presentation
Mobile reads the same session through a paired subscription. It starts with a small recent window, merges live frames by message identity, and loads older history as the person moves back.
The mobile surface separates transcript rows from prompts, approvals, drafts, attachments, queue cards, and delivery outcomes. It holds Send while an upload or option change is in progress. A reconnect resets state for the new session identity before it interprets an empty transcript, so another chat's history does not appear in the current view. Cached rows remain visible while the new read is unsettled, but they are not treated as confirmed current history.
References: mobile/…/use-mobile-native-chat-session.ts• L77-123 mobile/…/use-mobile-native-chat-session.ts• L172-247 mobile/…/use-mobile-native-chat-session.ts• L258-345 mobile/…/MobileNativeChatView.tsx• L146-173
Publication and capability negotiation
The host publishes history and live changes through ordered subscriber lanes. A lane runs one delivery at a time, coalesces replaceable catch-up and live-text work, and stops when the transport cannot safely retain the stream. Phone frames use bounded content and side batches so history, queue state, and background work fit their transport limits.
Desktop, mobile, and host versions negotiate capabilities before using optional conversation features. A client exposes a feature only when the host can honor its contract. The host withholds data that an older surface cannot render or act on safely.
References: src/…/agent-session-subscriber-delivery-lane.ts• L50-119 src/…/agent-session-subscriber-lane-runners.ts• L1-80 src/…/agent-session-bounded-frames.ts• L48-101 src/…/structured-agent-session-surface-capabilities.ts• L1-79
Change checklist
When these files or sections are changed, remember to consider these:
- When model catalogs or option controls change, keep discovery scope, input stamps, project override checks, shared refresh and wait behavior, default provenance, provider readback, send selection, capability gates, and older-host behavior aligned.
- When provider launch or runtime checks change, keep explicit command refusal, managed and host account boundaries, sign-in behavior, model availability evidence, and accepted protocol capabilities aligned.
- When send or attachment rules change, preserve body fingerprints, execution-host ownership, upload completion, transactional claims, echo adoption, and retry outcomes.
- When prompts or commands change, keep revision ownership, durable receipts, queue ordering, context boundaries, and provider settlement aligned.
- When queue rules change, update card projection, pause reasons, current-work gates, permission and tool acquisition, edit conflict checks, handover, and transcript admission together.
- When journal or timeline rules change, preserve stable item identity, revisions, tombstones, producer provenance, context epochs, write fences, external reply obligations, output bounds, and one-time settlement.
- When connector reply rules change, keep journal admission, first-fill behavior, rewind and withdrawal outcomes, cloud acknowledgement, and cleanup aligned.
- When recovery changes, define how lease uncertainty, crash cuts, clear, rewind, restart offers, explicit resume, continuation context, provider exit, and reconnect appear on every surface.
- When history or transport limits change, preserve cursor invalidation, forward catch-up, bounded frames, coalesced subscriber work, stale-read protection, cached identity checks, and subagent roster continuity.
- When surface features change, update capability negotiation before exposing data or actions that older clients cannot understand.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A model listing reuses an old executable or config stamp | The picker shows availability that no longer matches the provider | Include executable, script, and relevant config identity in the catalog input stamp |
| An explicit agent command is not runnable | The chat starts a different program or fails later with unclear state | Refuse the explicit command instead of falling back to the stock CLI |
| A required attachment is missing or under sweep | The provider receives an unusable attachment or the send fails after admission | Claim required uploads in the message transaction and reject expired references |
| A prompt answer or command is retried after an uncertain write | The provider can receive a duplicate control | Use durable operation identity and replay its receipt |
| A queue card enters the transcript before provider handover | The same message appears twice or acts during stopped work | Keep cards separate until handover and adopt the provider echo |
| A handover is closed while its provider result is still unknown | Accepted input is reported as lost or sent twice | Hold the operation across pending, provider, and late-settlement phases |
| A connector reply is filled twice | An external conversation receives conflicting replies | Make the first outcome fill win and keep a durable unsent outbox |
| A client resumes from an invalid cursor or stale session identity | The visible chat has a silent gap or another chat's rows | Reset the window and tag reads with the current conversation identity |
| A provider disappears without exit evidence | The UI reports success for work that may still be running | Keep the generation uncertain until history or death evidence resolves it |
| A crash cut resumes without its journal cursor or context boundary | Old work crosses into a newer conversation context | Require the recorded cut, expected cursor, and current epoch before continuation |
| A mobile frame exceeds its transport budget | Mobile drops side data or cannot render the update | Bound history and side lists before publication and mark incomplete data |
| An optional feature is used without capability negotiation | An older host or client rejects it or silently misreads it | Gate the feature on the shared capability handshake |
Key files
| File | Why to read it |
|---|---|
| src/…/agent-model-catalog-input-stamp.ts | Model discovery validity and refresh inputs |
| src/…/structured-agent-command-resolution.ts | Agent command selection and safe launch refusal |
| src/…/structured-agent-session-options.ts | Shared model and session option state |
| src/…/structured-agent-session-send-mutation.ts | Message body, attachment, fingerprint, and send contract |
| src/…/structured-agent-session-host.ts | Host composition for lifetime, delivery, publication, and recovery |
| src/…/structured-agent-session-handover.ts | Provider handover and uncertain delivery protection |
| src/…/journal-domain-input-eligibility.ts | Shared barriers for sends, queue claims, and current work |
| src/…/journal-connector-replies.ts | Durable external reply obligations and outcomes |
| src/…/journal-domain-item-presentation.ts | Journal-to-client forms and bounded item detail |
| src/…/journal-domain-acp-history.ts | Provider history adoption and paged turn facts |
| src/…/provider-timeline-assembler.ts | Provider events, turns, streams, and settlement boundaries |
| src/…/agent-session-subscriber-delivery-lane.ts | Ordered subscriber delivery and retention limits |
| src/…/agent-session-bounded-frames.ts | Transport-safe history and side-list publication |
| src/…/structured-agent-session-restart-resume-host.ts | Restart offers, explicit resume, and recovery actions |
| src/…/structured-agent-session-continuation-context.ts | Context reconstruction after an interrupted run |
| src/…/NativeChatStructuredSession.tsx | Desktop composition of transcript, live state, prompts, queue, and composer |
| src/…/native-chat-transcript-slots.ts | Desktop transcript grouping, folding, and row layout |
| mobile/…/use-mobile-native-chat-session.ts | Mobile subscription, identity protection, cached rows, live merge, and paging |
| src/…/structured-agent-session-surface-capabilities.ts | Host capability negotiation for optional conversation features |