Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

10.6 KB
Raw Blame

C-5 Transcript rows

Vibey's model context is stored in the existing messages and agent_events tables; there is no other copy (plan §5.1). Row payload shapes: transcript-rows.schema.json.

1. Membership and order

A row belongs to a Session's model context exactly when its context_seq is non-null. context_seq is an integer, unique per Session across both tables (partial unique index on each table, plus the single-writer rule below).

Entry Table type / event_type visibility Payload
user or steer input messages user — content_json.model = ModelInput
harness input messages harness, agent_initiated, annotation — content_json.model = ModelInput
model response messages assistant or result (not final), result or error (final); output (not final, released versions) — content_json.model = ModelResponse
tool result agent_events tool_result context content_json = ToolResult
checkpoint agent_events context_compaction context content_json = Compaction
cleared result agent_events context_edit context content_json = ContextEdit
hook state agent_events agent_state context content_json = AgentState
replay refusal agent_events replay_refusal context content_json = {version, source_identity, payloads}

A final response is error when it failed by itself (no text of its own: an empty answer, or a refusal or safety stop without an explanation), as the other backends' failed terminal rows are. A successful final with nothing to show (a silent reply) is the hidden response type assistant: context, but no transcript row, inbox reply, or unread result, as the other backends persist nothing visible for it; a terminal write at delivery (a run that failed after the commit) types it error. A non-final response is result when it is a reply pending input superseded and has text to show (superseded, loop-control.md): a reply that does not end the Turn (reply-and-turn-end.md); released versions typed it output. Every other non-final response is assistant. Context loading accepts all four.

Display-only rows keep context_seq null: interim, notify, an error that reports a run failure, vault, an output that is not a committed response, queued or removed inputs, and the tool_call trace row written at tool start (its metadata_json carries tool_call_id and job_id so the activity panel can pair it with the result). Audit rows are never context either: agent_events with visibility = 'audit' and no context_seq, written by append_audit, as fork_turn (ForkTurn, C-10 fork.md §7: one side turn, such as a C-9 checkpoint, with its own attempts' partials and usage) or model_attempt (ModelAttempt: the usage and/or optional cache diagnostics of a conversation attempt that did not become a response row, C-9 context.md §10, invariant 4). The activity panel does not read them.

2. Writing

Cache diagnostics are optional version-1 objects, outside canonical Usage: ModelResponse.cache, ModelAttempt.cache/cache_state, and ForkTurn.cache_attempts/cache_state. Old readers ignore them. Only usage-bearing records restore the request-start clock; two indexed latest-audit lookups recover the per-route state without scanning history. Each persisted prefix holds at most 32 sampled 128-bit hash boundaries (including tools, system, and the exact final boundary), not copied prompt content. Partial-prefix counts are estimates/lower bounds; a fully retained request uses its reported input count.

  • Every store implements the whole TranscriptStore protocol (harness/store.py) with the same behavior: an append returns exactly the entry load reads back, created_at (epoch seconds) included; a response keeps C-9's request facts in content_json.model.request; a payload row needs a payload kind and version 1, and append_payloads commits all of its rows or none; consuming the same input again returns its entry, and a different message for it is refused; a call is settled once (a second result returns the first); audit rows never load. One contract suite, tests/test_transcript_store_contract.py, runs the same tests on the SQLite store, the adapter's store over it, and the in-memory store the engine tests use.
  • The loop is the only writer of a Session's context_seq, under a per-Session lock held across the transaction: next = max(context_seq of the Session in both tables, fork_source_context_seq if the Session is a fork) + 1, so a fork's first entry follows its inherited prefix.
  • Inputs already exist as rows when they are submitted. The loop sets context_seq and content_json.model on that row when it consumes the input. Each entry is its own transaction; an input accepted by steer but not yet consumed when a crash happens is admitted into the context by the adapter at resume (recovery.md T3).
  • The adapter binds live writes to the durable Turn ID independently of input consumption. A transcript-only retry therefore writes tool results, context edits, state, and audits against its new retry Turn, not the last consumed input's Turn. Response metadata records that Turn ID at commit time; T2 recovery and job handover use the response's identity after restart. Legacy responses without it retain the input-order fallback.
  • A response row is inserted at message_end with both content_json.model and its commit-time display content_text.
  • A deferred hosted use produces no activity card on Web or IM. Its completion fragment uses the ordinary hosted-card path at the completion response's own position. A deferred use that never completes has no card; old trace cards for that exact shape are hidden at read time. Other pending blocks retain interrupted rendering. There is no cross-response Web merge or extra delivery guarantee.
  • An Anthropic server call deferred behind client tools finishes in a later response (C-1 cross-provider.md, 2026-10-22). Both existing v1 hosted-block fragments are appended in the provider's real response order; neither response row changes. C-1 request conversion joins the logical call for portable replay, while display joins append-only trace cards by owning durable Turn and call id. Usage remains on the reporting response.
  • A tool result row is inserted at tool_finished. The tool_call trace row is inserted at tool start without a context_seq.
  • Each commit is one SQLite transaction. The adapter delivers a row to surfaces only after it commits, through the same emit path as the other backends, naming the row (MessageOutput.persisted_row_id). Every dispatcher persist site then writes that row's display columns instead of inserting a second row: content_text, the display keys of content_json (text, kind, quick_replies, result_footer, citations), the delivery target's platform and scope_id, metadata_json (including the delivery_suppressed marker and its promotion), the output's native_message_id unless another row holds it, and a final's result / error type. Nothing is replayed: a delivery a crash or send failure interrupts is lost, as for the other backends (recovery.md §Delivery).

3. Projection

project(session_id, fork_point=None) -> list[Message], a pure function of the rows:

  1. Collect the context rows: the Session's own, plus its fork ancestry (§4).
  2. Order by context_seq.
  3. If a context_compaction row exists, take the latest; the context becomes its checkpoint message (its summary, then each state text as its own block) followed by the rows with context_seq >= first_kept_seq, excluding every context_compaction row (including the selected one), agent_state and replay_refusal rows. A tool result whose call was summarized leaves with it. Every replay_refusal row of the ancestry holds, whatever a checkpoint cut: the (Source identity, payload kind) pairs it names are never sent again in this Session (provider.md).
  4. Apply context_edit rows: the latest edit per target replaces that tool result's content with its placeholder; the context_edit rows themselves are then removed, so the result is only messages.
  5. Answer any tool call that still has no committed result with the synthetic interrupted result from cross-provider.md. Projection never consults a live job; resume settles open calls durably first (recovery.md).
  6. Prepend the rebuilt system prompt and hook-rehydrated messages; these are not rows. State rendered for a checkpoint is in its row, so projection stays a pure function of the rows (C-9 context.md §7).

4. Fork

The child Session's metadata already records its parent as top-level keys fork_source_session_id and fork_source_message_id (written by reserve_forked_session, read by fork_metadata_from_session_metadata in core/services/session_fork.py); C-5 reads those keys and adds no new fork shape.

  • anchor_seq is the fork point's as_of (C-10 fork.md §2): resolved once, in the reservation's transaction, from context_seq, row shape, and the source's Turn rows, never from a clock, and persisted as the top-level metadata key fork_source_context_seq. A user's fork cuts before the first input of the earliest unfinished Turn, as C-10 §2 defines it (live, holding a call awaiting T2, or with an accepted input awaiting T3); a self-fork takes the largest settled point; a system mechanism may name any settled point. 0 is the empty prefix. Rows that receive a context_seq later can never move into or out of the prefix. A released fork without that key (forked from a non-vibey Session) has no Vibey context to inherit and starts empty.
  • The child's context = the source's context rows with context_seq <= anchor_seq (recursively through the source's own fork), then the child's rows.
  • The child's context_seq continues from anchor_seq + 1, so the combined order stays total.
  • Nothing is copied. A checkpoint in the source after anchor_seq is invisible to the child.

5. Retention and deletion

  • Trace retention never selects visibility = 'context'; a contract test pins this.
  • The context content of a row never changes after commit: context_seq and content_json.model are written once (on an input row, when it is consumed). A response row's display columns (§2) may be written again when it is delivered; they are never context. Context rows are never deleted while a Session or a fork descendant references them (C-10 F8).