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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
docs(sessions): plan context rotation for long-lived sessions (#2324)
Maxdc51bcc23c5c
diff --git a/docs/plans/2026-10-01-session-context-rotation.md b/docs/plans/2026-10-01-session-context-rotation.mdnew file mode 100644index 000000000..492c56250--- /dev/null+++ b/docs/plans/2026-10-01-session-context-rotation.md@@ -0,0 +1,438 @@+# Session Context Rotation++Status: proposed (2026-10-01)++## Background++Avibe is moving toward a small set of long-lived built-in agents (main+assistant first; memory and ops roles later) that the user talks to instead of+managing many sessions. A main-agent session is an ordinary `agent_sessions` row+with a type marker; its transcript stays in `messages` like every other session.+The desktop pet will bind to that one session id.++A session that never ends will eventually fill its backend context window.+Backends auto-compact today, but a perpetual session needs more than that:++- compaction is lossy and repeats indefinitely; Avibe cannot see or shape what+ it keeps, and it does not know which runs, watches, or approvals are still+ open for the session;+- the backend transcript behind a resumed native session grows without bound;+- a bound session cannot change backend (`SessionBackendLockedError`), and a+ vanished native session fails the turn loudly. Neither is acceptable for a+ session that is supposed to last for months.++## Decision++Keep one Avibe session and swap the backend-native session underneath it.++The model already separates the two layers this needs:++- `agent_sessions.id` is the conversation the user sees. Messages, deliveries,+ turns, unread state, the queue, SSE events, Harness callbacks+ (`agent_runs.callback_session_id`), run definitions, and the Workbench URL all+ key on it.+- `agent_sessions.native_session_id` is the backend context (Claude session id,+ Codex thread id, OpenCode session id).++Context rotation replaces the second without touching the first, and hands the+new native session a bounded handoff. It is a session-layer mechanism available+to every session; the main agent is its first user. No `conversation` table is+introduced: it would duplicate the session row and split every consumer above+between two owners.++### Concrete example++1. The user has talked to the main agent (session `S`, native Claude session+ `n1`) for weeks. A delegated run `R` is still running with+ `callback_session_id = S`.+2. A turn ends with context occupancy at 62% of the window. Avibe records that+ peak on `S`.+3. The user sends the next message. At turn start the recorded peak is past+ the ratio, so `S` is rotation-due. Before the backend is invoked, Avibe+ archives `n1` as a superseded snapshot row, clears `S.native_session_id`,+ releases the backend's cached runtime for `S`, and prepends a handoff block+ to this turn's input.+4. Claude starts a fresh native session `n2`; the ordinary first-bind path+ records it on `S`.+5. `R` finishes. Its callback targets `S` and lands in `n2` with no special+ handling. The user's transcript, the pet's binding, and the Workbench URL+ never changed.++## Design++### Rotation primitive (storage)++Generalize `SQLiteSessionsService.replace_agent_session_native` into a+"supersede native binding" operation whose replacement may be empty:++- In one write transaction: verify the expected native id, insert the existing+ inert snapshot row (`<anchor>:superseded:<id>`, archived, background), then+ set the active row's `native_session_id` to `""`.+- Record why in the snapshot's `superseded_native_binding` metadata:+ `reason`, `context_tokens`, `context_window`. The snapshot rows are the+ rotation history; no new table or event type is added.+- Set `metadata_json.context_handoff = {"pending": true, "rotated_at", "from_native", "reason"}`+ on the active row.++Clearing to empty instead of pre-creating a replacement lets every backend+reuse its normal first-bind path. This matters for Claude, which only learns a+new session id from the init message of the first query.++### Rotation lifecycle (core)++Rotation has two persisted phases. Both are driven from one turn-start+chokepoint: after the durable turn is `starting` and before the backend target+(`agent_session_target`) is built from the row. Rotation never runs mid-turn,+because steering and interrupts target the live native turn.++1. **Due.** A session is due when the explicit marker+ `metadata_json.context_rotation_due` is set, or when its persisted+ `context_usage` meets the pressure rule and its policy is `auto` (see+ Context pressure trigger). Triggers only write state and never rotate, so a+ request made while a turn is running takes effect on the next turn and+ cannot race it.+ - At the chokepoint, a due session that is not already pending first asks+ the backend whether its native runtime is settled+ (`native_runtime_settled`, below). If the runtime is not settled, rotation+ is deferred: `due` stays set and this turn runs on the current native as+ usual. The check is repeated at every later turn start.+ - Once the runtime is settled, the storage supersede runs. The same+ transaction clears `due` and sets `context_handoff.pending`.+ - A due session with no bound native has nothing to rotate; `due` is simply+ cleared.+2. **Pending** (`metadata_json.context_handoff.pending`). On every turn start+ while pending:+ 1. Release the backend runtime for the session (idempotent; see below).+ If release fails, the turn fails before dispatch and `pending` stays set,+ so the next turn retries the release. A handoff is never sent through the+ old cached runtime.++ The supersede only ran after the runtime was settled. A pending turn+ never dispatches before release succeeds. So no backend work can start on+ the old runtime between the settled check and the release.+ 2. Build the handoff from fresh durable state and prepend it to this turn's+ input. The native id is either empty (the normal case) or already bound+ to a new native that never accepted input. The second case happens when+ Codex `_start_thread` binds the thread and the following `turn/start`+ fails. Either way the new backend context has not seen a handoff, so+ sending one is correct.+ 3. Clear `pending` only on acceptance evidence. That evidence is the native+ start receipt of the turn that carried the handoff; binding a native id+ is not enough.+ - When the handoff is injected, the durable turn records the+ `context_handoff.rotated_at` it carries.+ - `SessionTurns.on_native_start` already writes the receipt+ (`bind_native_start`) inside one SQLite transaction. The pending clear+ joins that same transaction: compare-and-set on the recorded+ `rotated_at`, so a late receipt cannot clear a newer rotation.+ - The receipt and the clear therefore commit together or not at all. A+ native that accepted the handoff never receives it again.++The phases are never skipped. The handoff is resent only when no receipt was+committed. The one case where the native may have accepted it anyway is a+process crash between native acceptance and the receipt transaction. That is+the same window in which ordinary turn delivery can already duplicate a turn,+and it is not widened.++### Backend runtime release (agent abstraction)++Clearing the row is not enough, because backends cache live runtimes:++- Codex checks the in-memory `_threads[base]` before the database;+- Claude reuses a cached SDK client per composite key.++An idle turn boundary also does not mean the runtime is idle. Claude admits a+new human turn while a detached background Activity is still running on the+same SDK client (`docs/plans/claude-result-provenance.md`). Releasing that+client would orphan the Activity and lose its output. The handoff cannot carry+that output either, because it lists only durable Harness items.++Two backend-neutral hooks cover this.++`BaseAgent.native_runtime_settled(session) -> bool` is the rotation+precondition. Its default is `True`:++- Claude: `False` while the backend-neutral `SessionActivityRegistry` has an+ active Activity or completed, unclaimed Activity output for the session's+ runtime key (`has_active`, `has_completed_output`), or the agent still holds+ an Activity output record. This is the same evidence that+ `_activity_output_pending` already reads.+- Codex and OpenCode: `True`. Neither registers detached Activities today, and+ the chokepoint already guarantees no live native turn. A backend that later+ registers Activities must implement the hook.++`BaseAgent.release_native_runtime(session)` drops the cached runtime. Its+default is a no-op:++- Claude: `_cleanup_runtime_session(...)`;+- Codex: `invalidate_thread(...)` plus clearing cached developer instructions;+- OpenCode: no-op, to be verified, since its per-request state is already+ cleared.++The existing `clear_sessions` paths cannot be reused. They delete or archive the+Avibe rows that `/new` retires.++Release must be idempotent and cheap when nothing is cached, because it runs on+every pending turn start. Each backend's release must be complete: it removes+every cache that a resume consults before the database.++### Handoff++Built at the chokepoint while `pending` is set, as one block in the turn input.+It does not go into the system prompt, so system prompt bytes stay stable for+backend caches. Rendered from a `core/prompts/` template.++**One budget covers the whole block.** The budget is a small fraction of the+session's known context window, or a fixed character cap when the window is+unknown. Sections fill it in priority order. Every list is truncated to what+fits and ends with the count of omitted items plus the command that lists them+all, so the size stays bounded however much open work exists.++1. **Continuity notice.** This is a continuing conversation in Avibe session+ `S`; the earlier backend context was rotated.+2. **Open work**, one line per item, read from the durable store at that moment.+ It comes before the transcript because the transcript cannot reconstruct it.+ Each item appears once. The builder deduplicates by identity key rather+ than relying on the sources being disjoint, because the sources are not+ written atomically with each other. For example, `_process_run_callback`+ enqueues a callback and only afterwards moves the parent run's+ `callback_status` from `pending` to `sent`, in a separate operation. A+ handoff built in that gap sees both.+ - The identity key of a delegated run is its run id. A queued callback+ carrying `parent_run_id` takes the same key.+ - When both appear, one line is kept: the run, marked "callback queued".+ - Other items are keyed by their own id.+ - **Delegated runs:** every `agent_runs` row with `callback_session_id = S`+ and `callback_status = 'pending'`, whatever its run status. This includes+ runs that have finished but whose callback has not yet been delivered.+ The handoff owns this query rather than reusing the banner helper, which+ shows only active runs.+ - **Watches and tasks** bound to `S`: the rows of+ `derive_session_harness_activities` whose `item_kind` is `watch` or+ `task`. That helper also returns active delegated runs (`agent_run`), which+ the query above already covers, so they are dropped here.+ - **Queued deliveries** for `S`.+ - **Pending vault requests** for `S`.+3. **Recent transcript.** The tail of `list_session_messages(...,+ types=TRANSCRIPT_TYPES, tail=True)`. It is taken newest first until the+ remaining budget runs out, then restored to chronological order.+4. **History pointer.** Older history is available on demand through+ `vibe data query` over `messages` where `session_id = S`. The memory package+ was removed in #2120, so on-demand query replaces memory retrieval.++v1 summaries are mechanical; there is no LLM summarizer in the runtime today.+An agent-authored handoff note is a follow-up, added only if transcripts show+material loss.++### Context pressure trigger++Context occupancy is in memory only today (`MessageDispatcher._session_token_total`)+and is lost on restart. Persist it as+`metadata_json.context_usage = {"peak_tokens", "window", "compacted", "observed_at"}`,+covering the current native since its last rotation.++**When it is written.** An observation is written whenever a native phase+settles, not only at an Avibe turn end:++- the end of an Avibe turn;+- the terminal `ResultMessage` of a detached Claude Activity phase, which can+ arrive after the originating turn has ended+ (`docs/plans/claude-result-provenance.md`).++Each write merges into the stored value through the locked per-key writer:++- `peak_tokens` takes the maximum of the stored value and the phase's peak+ snapshot, so a drop after a compaction does not hide the peak;+- `compacted` is OR-ed;+- `window` takes the latest known value.++The supersede moves `context_usage` into the snapshot row+(`context_tokens`, `context_window`) and clears it on the active row.++Occupancy, in tokens:++- Claude: per-assistant-message usage (`_extract_context_tokens`).+- Codex: `tokenUsage.last.totalTokens` from `thread/tokenUsage/updated`.+- OpenCode: none yet (follow-up: step-finish token parts).++Window, in priority order:++1. The backend's own report:+ - Claude: `ResultMessage.model_usage[<model>].contextWindow`. The field is+ present at both pinned floors, `claude-agent-sdk` 0.2.158 (Windows,+ `>=0.2.158,<0.2.160`) and 0.2.162 (other platforms). This also covers+ direct, non-Hub launches, whose `ModelHubLaunch` carries no+ `context_window`. A unit test that parses a result message pins the field+ at the Windows floor.+ - Codex: `tokenUsage.modelContextWindow`.+2. The configured Model Hub `context_window`.++Each source is optional at runtime. If a source reports no window, the next+one is used; if none does, the window is unknown and only the compaction+signal applies.++Backend compaction observed in any native phase sets `compacted`:++- Codex: `thread/compacted`; its handler is a no-op today.+- Claude: a `SystemMessage` with subtype `compact_boundary`. The CLI bundled+ at the 0.2.158 floor emits it.+- OpenCode: an assistant message carrying `info.summary`.++The rotation is due when either signal holds:++- **Ratio.** `peak_tokens >= 0.6 * window`, with both values known. The ratio+ sits below backend auto-compaction thresholds and leaves headroom for the+ handoff. It is an internal constant, not a user setting.+- **Compaction.** `compacted` is true. This covers a single turn that jumps+ past the backend threshold before any snapshot is emitted. It is also the+ only automatic signal for OpenCode and for any session whose window is+ unknown.++Both are evaluated at the turn-start chokepoint, from the persisted+`context_usage`. So pressure that a detached phase recorded while the session+was idle is seen by the next human turn. The rotation itself then follows the+lifecycle above.++### Policy++- Automatic rotation is a per-session policy,+ `metadata_json.context_rotation = "auto"`. It is off by default, so existing+ sessions behave exactly as today.+- Main-agent sessions will default to `auto` when the session type lands.+- Explicit rotation works on any session: `vibe session rotate <session-id>+ [--reason <text>]` sets the due marker. It is useful for testing and for an+ agent that wants to rotate itself at a natural break.++## Persisted shape++All additions are optional `metadata_json` keys on `agent_sessions`:+`context_rotation`, `context_rotation_due`, `context_handoff`, and+`context_usage`. The snapshot rows also get extra `superseded_native_binding`+fields. There is no schema migration:++- older releases ignore the keys;+- rows written by older releases have no keys and keep today's behavior.++Safe degradation. All four keys are read through one normalizer, and each key+is validated independently:++- A value that is malformed (wrong type, partial object, unparsable timestamp)+ or of an unknown newer shape is treated as absent for that key alone.+- A malformed value logs one warning per session and process.+- The normalizer never raises on the turn-start, turn-end, or startup paths.+- Writers always write the full canonical shape.++Concurrent writers. The rotation keys share the `metadata_json` column with each+other and with backend runtime markers. Several writers can touch it at the same+time: `vibe session rotate` setting `due` mid-turn, the usage writer,+the turn-start supersede, and the receipt clear.++Every write of a rotation key goes through one storage method. It follows+`set_agent_session_runtime_marker`: inside one transaction it takes+`reserve_write_lock`, re-reads the current metadata, changes only its own key,+and writes the result back. No writer persists a metadata snapshot read+earlier, so a usage write cannot erase a `due` marker set during the turn.++What "treated as absent" means for each key:++| Key | Behaves as |+|---|---|+| `context_rotation` | off |+| `context_rotation_due` | not due |+| `context_usage` | no observation |+| `context_handoff` | not pending |++The last row means that if an interrupted rotation leaves a malformed handoff,+the next turn starts a fresh native without a handoff. That degrades+continuity but does not fail dispatch.++## Invariants and tests++- Rotating preserves everything keyed by the session id. Seed one row of every+ table that references the session, rotate, and assert that every seeded row is+ unchanged and still points at `S`.+- After rotation the active row has an empty native id, and exactly one new+ archived snapshot row holds the previous id.+- The next turn binds a fresh native id through the normal bind path and+ receives the handoff. `context_handoff.pending` is cleared only by that turn's+ native start receipt.+- Any failure before the receipt leaves `pending` set, and the following turn+ delivers the handoff. The failures covered are a release error, a failure+ before bind, and a bind followed by a failed `turn/start`.+- A release failure blocks dispatch. No pending turn reaches the backend's old+ cached runtime.+- The handoff never exceeds its budget, for any number of open items, and every+ truncated list reports its omitted count.+- Every run with `callback_session_id = S` and a pending callback appears in the+ handoff, whatever its run status.+- A run whose callback is already queued while its `callback_status` is still+ `pending` appears once.+- A native phase whose occupancy peaks at or above the ratio, or that observes+ a backend compaction, makes the next turn start rotate, even if its last+ snapshot is lower. This holds for a detached Claude Activity phase that+ settles after its turn ended.+- A crash or failure after the receipt transaction does not resend the+ handoff. Seeding a committed receipt leaves `pending` cleared; with no+ committed receipt, `pending` stays set.+- The window comes from the first source that reports one. With none, ratio+ rotation is skipped and compaction still marks the session due.+- Load fixtures: rows with no rotation keys (every released shape), and rows+ with each key malformed or in an unknown shape. Turn start, turn end, and+ startup all succeed, and each key behaves as absent.+- Interleaving: set `due` between the usage writer's read and its write.+ Both `due` and `context_usage` survive, and the next turn rotates.+- A Claude session with an active detached Activity, or with completed Activity+ output not yet delivered, is not rotated. `due` stays set, the turn runs on+ the old native, and the Activity output is delivered. The next turn start+ after it settles rotates.+- No rotation happens while a turn is live. A request made mid-turn takes effect+ at the next turn start.+- Per backend: after release, a turn does not reuse the cached runtime or thread+ for `S`.+- A session without `context_rotation = "auto"` never rotates automatically,+ whatever its usage.++## Follow-ups (same primitive, separate PRs)++- Self-heal when the native resume target is gone (Claude/Codex currently fail+ the turn) for sessions with rotation enabled.+- Backend switch on a bound session through rotation instead of+ `SessionBackendLockedError`.+- OpenCode context usage.+- Agent-authored handoff note.++## Risks to verify during implementation++- Any turn entry path that does not pass the chokepoint, or that carries a+ cached native id (`_cached_target` in `agent_run_target.py`; non-durable IM+ paths), would resume the old context. Inventory them all and route them+ through the chokepoint.+- Backend runtime markers in `metadata_json` are keyed to the old native. Codex+ re-checks `marker.thread_id`; audit the rest.+- Audit every other kind of process-local, per-session state that release+ drops, such as steering state, pending reactions, and queued requests. Each+ kind must either be settled under `native_runtime_settled` or be safe to+ drop at a turn boundary.+- Snapshot rows must stay invisible to sidebar and archive listings, native+ session listing, and the Claude process reaper, as they are for the existing+ OpenCode repair.++## Todo++- [ ] Storage: supersede-to-empty plus handoff and due markers.+- [ ] Turn-start chokepoint: consume the due marker, rotate, release the+ runtime, inject the handoff.+- [ ] `BaseAgent.native_runtime_settled` (Claude Activity gate) and+ `BaseAgent.release_native_runtime`, implemented for Claude and Codex.+- [ ] Handoff prompt template and builder.+- [ ] Persist peak usage and window on every settled native phase, including+ detached Claude Activity results (Claude, Codex). Observe backend+ compaction on all three backends. Evaluate the ratio and compaction rules+ at turn start.+- [ ] Clear `context_handoff.pending` inside the `on_native_start` receipt+ transaction.+- [ ] Single metadata normalizer with malformed-shape fixtures, and one+ locked per-key merge writer.+- [ ] `vibe session rotate` CLI and per-session `context_rotation` policy.+- [ ] Tests for the invariants above.+- [ ] Update `skills/use-avibe` docs for `vibe session rotate`.