Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Agent Message Priority Contract
Status
Implemented program contract. P0, P1, and P3 share one durable Delivery owner across interactive input, Harness input, queue promotion, and restart recovery. P2 and P4 remain reserved for a separate Mailbox design.
Priority Semantics
- P0 Stop is an explicit content-free action. It stops the exact active Turn; no message-producing surface may use P0 to replace that Turn.
- P1 steer delivers content into the expected currently active Turn without stopping it. A content-free P1 request atomically promotes the current P3 queue head. A definitive steering failure may transfer the same Delivery to P3; an acknowledgement-ambiguous result must be reconciled durably first.
- P3 queue starts immediately when the Session is idle and otherwise remains FIFO until the active Turn ends. Queueing is not a hold mechanism.
Priority controls delivery timing only. A request has no correction/addition
intent, and no layer may wrap, prefix, summarize, or otherwise rewrite the
natural-language content.
Native Steering Contract
The shared backend request has these fields:
SteerRequest
target_session_id: str
expected_logical_turn_id: str
expected_native_turn_id: str
text: str
attempt_id: str = ""
input_metadata: AgentInputMetadata | None = None
files: tuple[FileAttachment, ...] = ()
target_session_idis the target Avibe Agent Session identity.expected_logical_turn_idis the active Avibe Turn identity observed by the caller. It prevents a stale request from steering a later logical Turn.expected_native_turn_idis the backend-specific active-Turn identity or generation observed by the caller: the Codex turn id, the Claude live client/receiver generation, or the OpenCode native session/runner generation.textis the original, unmodified input. Adapters must pass it to the native backend byte-for-byte as text, including non-ASCII and Markdown/code content.filescontains session-bound attachments resolved from the durable Delivery tokens immediately before native dispatch. Never accept arbitrary caller paths. If any reference is revoked, foreign, missing, or no longer local, refuse before writing any part of the batch and keep the original Delivery queued.attempt_idis the durable attempt identity;input_metadatarenders only at the native boundary. Neither changes the original text or attachment snapshot.
The typed result has one outcome with exactly four possible values. Optional
reason and details fields are subordinate diagnostics and do not create
additional outcomes.
SteerResult.outcome = accepted | not_active | refused | unknown
accepted: the backend acknowledged insertion into the expected currently active Turn.not_active: no active Turn matches both expected identities.refused: the backend definitively rejected the request or definitively cannot support it. Runtime-unavailable and unsupported states are reasons under this outcome when they are known before delivery.unknown: the transport may have accepted the input, but no trustworthy acknowledgement was obtained. Callers must not retry or queue-fallback from this outcome without durable reconciliation.
The adapter call is insertion-only. It must not invoke normal new-Turn dispatch, acquire another Avibe Turn gate, append a primary pending request, replace the terminal Result owner, create an Agent Run or callback, or install another receiver.
Backend Acknowledgements
- Codex: call the installed app-server
turn/steermethod withthreadId,expectedTurnId, and the same text /localImageinput builder asturn/start. Include the durable steer attempt id asclientUserMessageId; Codex persists it on the resultinguserMessageitem. A response is accepted only when itsturnIdequals the expected native turn. If the acknowledgement is ambiguous, recovery reads the exact thread turn and accepts only a matchingclientId; absence of that evidence remainsunknownand fenced. Never fall back toturn/start. - Claude: call
query()on the existing live client using the existing runtime session id while retaining the same receiver generation. Successful completion of the SDK transport write is the acknowledgement. A timeout, disconnect, or failed write with an ambiguous partial-write boundary isunknown; a pre-write unavailable state isrefused. Use the same attachment-path context as normal turns; receipt tracking includes the complete rendered prompt, including image/file paths. - OpenCode: call
prompt_asyncon the existing native session and runner. HTTP 200/204 is the acknowledgement. A definitive HTTP rejection isrefused(ornot_activewhen the native session is absent); a timeout or disconnect after request dispatch isunknown. The adapter never calls abort or stop. Use the normal-turn attachment-path context and track that full prompt for reconciliation.
These acknowledgement strengths are intentionally different because the native protocols expose different boundaries. The common result preserves that truth instead of claiming equivalent durability.
Source Policy
| Source | Default | Behavior |
|---|---|---|
| Web composer | P3 | Starts when idle; otherwise joins the FIFO backlog. |
| Ordinary IM message | P1 | Steers the active Turn or starts when idle; a definitive refusal falls back to P3. |
| Existing-Session Agent Run | P1 | Same as ordinary IM. --queue selects P3. The new message never promotes older queued work. |
| Watch, Hook, Webhook | P1 | Continues the target Session without interrupting it. |
| Show annotation | P1 | Delivers the annotation to the current Turn when possible. |
| Session callback | P1 | Delivers each completed child Run independently. |
| Scheduled Task | P3 | Never interrupts or steers the work a user is already doing. |
| Stop | Empty P0 | Stops the exact live Turn. Definitive terminal settlement immediately starts the oldest claimable P3 segment. |
| Send Now existing head | Empty P1 | Promotes only the exact observed FIFO head. |
Attachments remain part of the same Delivery and follow the same P1 admission as text. Send Now can steer pure-image and mixed text/file messages into the active Turn without stopping it. Definitive refusal preserves the queue; an ambiguous acknowledgement retains the existing reconciliation fence. The send-now response exposes queued refusal reasons so the UI never implies that the attachment was sent when it was not.
The queue and bootstrap read projections retain unaccepted pending_steer,
steering, and reconciling_steer rows in FIFO order with their original content.
These rows remain inspectable after reload but cannot be recalled, deleted, or
sent again; a fenced head blocks Send Now without blocking removal of queued
followers. The strict queued-only storage default and native ordering fences
remain unchanged. Receipt settlement publishes a queue refresh after commit:
acceptance transfers the input to the transcript, while definitive refusal
restores the editable queued row (or retires it for an inactive Session).
Attachment steering acceptance scenarios:
QUEUE-IMAGE-001: pure image and Chinese text/image queue heads reach the exact active native turn, preserving token, filename and transcript identity.QUEUE-IMAGE-002: Codex useslocalImage; Claude/OpenCode use their normal attachment context; all retain their current receiver/runner and never Stop.QUEUE-IMAGE-003: foreign/revoked/missing media refuses the whole input before writing text; unknown acknowledgements never retry or duplicate the input.QUEUE-IMAGE-004: queued thumbnails and send feedback survive refresh and reload while steering is unconfirmed; pending rows are read-only, and receipt settlement restores queued actions or moves the input to the transcript. Text-only rows use the same delivery-state projection.
Ownership Closure
message_deliveriesowns every unaccepted input, queue position, attempt, and receipt. No unaccepted input is a transcript Message.session_turnsowns execution and its immutable terminal snapshot.messagescontains accepted communication records only.- Accepted Agent Runs attached to one Turn are independent terminal subscribers. The existing Run rows and their Delivery-to-Turn links are sufficient; no callback table or second terminal writer is introduced.
- One terminal snapshot settles every accepted Run once, after which each Run's existing callback state produces at most one P1 callback Delivery.
Deferred Work
- P2/P4 Mailbox cursor, unread, acknowledgement, merge, and retrieval semantics
- generic exact-id promotion or demotion
- authentication, authorization, ACL, and unrelated issue dependencies