Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / ai-vault-sessions

AI Vault sessions

AI Vault gives engineers one view of agent session history across the local desktop, WSL, and runtime hosts. It reads provider-owned history through isolated services, keeps each row tied to its host and source, and lets users search, resume, hand off, or delete a session without turning history access into general file access.

Session history

AI Vault turns different provider record formats into one session view. A row carries the identity and host data needed to display history and to act on the original source.

Session views

The session view keeps the provider session ID, source path, working directory, and execution host together. This stops a session from one machine or WSL distribution from being treated as a local session. List views use bounded previews, while full prompts and transcripts use separate reads.

Conversation text is normalized before it reaches the view. Provider instructions and visual directives do not become titles or previews. User, assistant, and tool content remains available within fixed safety limits. A row can also carry recovery signals for queued prompts or child transcripts when the provider has not saved normal turns.

References: src/…/ai-vault-types.ts• L116-164 src/…/ai-vault-types.ts• L194-221 src/…/session-scanner-text-normalization.ts• L6-21

Provider history

Provider history can be an append-only log, a whole document, a session folder, or a database record. Provider readers map these forms to the same session view. Sidecar data can add a title, working directory, model, usage, or visibility without replacing transcript data.

The scan follows a common path:

  1. Discovery finds a provider candidate.
  2. The provider reader extracts identity and conversation data.
  3. Sidecar data enriches the row when the provider needs it.
  4. The result receives its execution host and resume information.
  5. Independent consumers can use the decoded turns for search.

Shared roots still need provider ownership rules. Pi and OMP can write related records in one root. OMP task transcripts appear as child records only when their artifact shape and parent relationship prove that meaning. Cline manifests do not create an extra row for their messages file.

References: src/…/session-scanner-agent-parser.ts• L45-84 src/…/session-scanner-candidates.ts• L53-129 src/…/session-scanner-sidecar-enrichment.ts• L13-19 src/…/session-scanner-omp-subagent-listing.test.ts• L24-65 src/…/session-scanner-cline-parser.test.ts• L15-75

Provider additions

New provider history joins the common view without changing the meaning of existing rows. Antigravity can expose CLI, IDE, and newer origins as separate sessions when the client opts in. Droid keeps model and own token use in a settings sidecar. Devin uses its session index for title, workspace, model, activity, and hidden-row decisions.

The sidecar remains optional. If a read is refused, AI Vault keeps the transcript row but marks the enrichment unknown so a later scan can retry it. A hidden provider row is not shown after the index proves that it is hidden.

References: src/…/antigravity-ide-history.test.ts• L39-79 src/…/session-scanner-antigravity-history.ts• L83-137 src/…/session-scanner-droid-settings.ts• L9-40 src/…/session-scanner-devin-db.test.ts• L148-199

Hermes history

Hermes stores several conversation surfaces in SQLite state databases. AI Vault presents one usable conversation row instead of exposing hidden, tool-only, archived, reset, or superseded records as separate chats. Compression and reset continuations remain part of the conversation that Hermes can resume.

The reader adapts to supported schema versions. It derives activity from live message rows and session metadata, then reads only the message bodies needed for a preview or full transcript. Rewinds and compaction are reflected in the displayed conversation rather than shown as duplicate turns.

References: src/…/hermes-state-db-activity.ts• L70-124 src/…/hermes-state-db-messages.ts• L53-119 src/…/session-scanner-hermes-sqlite.test.ts• L130-180 src/…/session-scanner-hermes-sqlite.test.ts• L182-224

Session scopes

Session lists can cover the local host, one runtime host, or all active hosts. Workspace and project scopes use recorded working directories to find older sessions that the normal recent-session pass would omit.

Scope paths are bounded and normalized before they cross a host boundary. Workspace history includes active paths and valid prior worktree paths unless another live worktree now owns the same path. Unknown or invalid paths do not widen a scope.

References: src/…/ai-vault-types.ts• L233-262 src/…/ai-vault-scope-paths.ts• L14-89 src/…/runtime-session-scanner.ts• L73-120

Scan coordination

Concurrent requests for the same host and scope share one scan. Each caller can cancel its own wait without cancelling other callers. A forced refresh can replace a long scan, but non-cancelled callers move to the replacement.

Local and runtime results are merged by host. A runtime result is stamped with the host selected by the caller. A failed host becomes a scoped issue so other hosts can still return history.

References: src/…/ai-vault.ts• L94-153 src/…/ai-vault.ts• L165-218 src/…/ai-vault-runtime-scan.ts• L31-65 src/…/runtime-session-scanner.ts• L73-137

Transcript access

The list, full transcript, and search index are separate consumers of decoded messages. Each consumer has its own position, so one slow or cancelled consumer cannot make another skip data.

Append-only reads resume after complete records only when the source identity and saved prefix still match. Rewritten or uncertain documents use a replacement read. A partial read does not publish its messages or advance its position.

Whole-document providers can stream only the fields and message arrays needed by their reader. This keeps large documents bounded and rejects malformed input without publishing a partial session. Hermes also keeps large multimodal content and tool output within the same display and search limits.

References: src/…/session-transcript-consumers.test.ts• L99-131 src/…/session-document-consumer-replacement.test.ts• L10-43 src/…/session-document-stream-contract.test.ts• L28-109 src/…/hermes-state-db-messages.ts• L122-179

Process isolation

AI Vault keeps provider discovery, parsing, transcript reads, search indexing, and cache work outside the process that owns terminal control. The boundary limits the effect of large history, bad provider data, and memory pressure. It is a fault and resource boundary, not a complete security sandbox.

Service boundary

The desktop main process and runtime hosts use a scanner service for history work. The parent selects the host, owns transport, validates results, and merges rows. The service owns provider reads, parsing, cache access, title and prompt reads, child-session reads, and search.

Search uses a worker boundary for its local index. Database-backed readers use a further worker boundary. WSL database work stays inside the selected Linux distribution. If a worker or distribution is unavailable, AI Vault reports a source issue instead of moving the work into the main process.

References: src/…/session-scanner-service-spawn.ts• L58-73 src/…/session-scanner-service-protocol.ts• L23-47 src/…/session-search-worker-client.ts• L12-21 src/…/session-scanner-opencode-sqlite-worker-client.ts• L49-87

Service lifecycle

The scanner service starts when history or search work needs it. It waits for a versioned ready signal, serves several requests, and retires after idle time. Search can keep it alive while background indexing continues.

Cache rows are an optimization over provider records. The private parse cache stores reusable session rows and scope facts. It validates cached content, discards incompatible or corrupt databases, and falls back to a cold parse. Rows that are not seen for the provider's retention window are removed instead of being treated as live history.

References: src/…/session-scanner-service-client-state.ts• L301-335 src/…/session-parse-cache-database.ts• L27-49 src/…/session-parse-cache-database.ts• L192-232

Restart policy

A child exit, disconnect, malformed message, timeout, failed start, or failed idle action is a service fault. Active work fails. Safe work that never reached the child can retry with a short increasing delay. Repeated faults open a short circuit so a broken child does not create an endless restart loop.

Search and database workers use the same bounded approach. Handles tied to a dead worker are rejected because they cannot continue safely on a replacement. A scan held during a heap failure can run once on a replacement with a larger bounded heap.

References: src/…/session-scanner-service-restart-policy.ts• L1-61 src/…/session-scanner-service-oom-recovery.ts• L8-76 src/…/session-search-worker-client.ts• L29-69 src/…/session-scanner-opencode-sqlite-worker-client.ts• L24-87

Protocol clients

AI Vault uses private process protocols below desktop IPC and runtime RPC. These clients carry readiness, request identity, results, errors, cancellation, cache invalidation, search state, and shutdown without exposing child-process details to the UI.

Service requests

The scanner service accepts cache work such as session lists and titles, plus interactive work such as prompts, child sessions, search, and search state. Every response keeps its operation and request identity. Unknown or malformed child messages are faults.

The parent validates mixed-version results. Known valid rows remain usable, scoped warnings remain visible, and rows from providers that the current build cannot understand are dropped.

References: src/…/session-scanner-service-protocol.ts• L27-47 src/…/session-scanner-service-protocol.ts• L68-143 src/…/session-list-result-validation.ts• L86-179

Runtime requests

Runtime requests run where the transcript lives. The caller selects the runtime environment and stamps returned rows and issues with that execution host. The caller also records the pairing revision that listed the row, so a later delete cannot silently act on a different pairing.

An unchanged content fingerprint can return without sending session rows again. A bad response becomes a host issue. It cannot choose a new trusted host or widen the requested scope.

References: src/…/runtime-session-scanner.ts• L67-137 src/…/runtime-session-scanner.ts• L208-247 src/…/ai-vault-runtime-scan.ts• L47-63

Cancellation

Cancellation stops work that no longer has a caller. A local waiter can leave at once while the remote scan settles later. A sent child request receives cancellation and a short stop deadline. A child that does not stop is unhealthy and is replaced.

The same cancellation meaning crosses desktop IPC, runtime RPC, WSL admission, database readers, search workers, and transcript reads. IPC turns expected cancellation into a marked result instead of an application error.

References: src/…/ai-vault-scan-cancellation.ts• L11-49 src/…/ai-vault.ts• L231-253 src/…/ai-vault-single-host-list-cancellation.test.ts• L16-37

Session search is an optional full-text index over decoded conversation history. It runs in the scanner service and its workers. Search stays off until enabled because it reads approved roots and keeps another local copy of selected text.

Search index

The indexer performs recent passes and periodic full sweeps. It tracks source identity, companion state, read position, and the current index generation. A source is current only when its indexed content still matches the source.

Search writes publish a replacement or append as one coherent generation. A failed write leaves the earlier searchable generation in place. Proven deletion retires source rows only after bounded proof that the source is gone. An unreadable root remains unknown rather than becoming an empty root.

References: src/…/session-search-indexer.ts• L21-40 src/…/session-search-index-consumer.ts• L49-120 src/…/session-search-index-writer.ts• L26-53 src/…/session-search-deleted-sources.ts• L44-101

Search queries

Search accepts free text with repo: and path: qualifiers. Results can use relevance or time order and can narrow to one conversation or all indexed history. Workspace and project scope travel as an identity for the runtime host to resolve in its own catalog.

A stale cursor is rejected when the query shape, index generation, or index incarnation changes. An unknown scope returns no results instead of widening to all history.

References: src/…/session-search-retrieval.ts• L52-196 src/…/session-search-page-cursor.ts• L18-90 src/…/session-search-scope-resolution.ts• L16-45

Structured ownership

Some history rows belong to native structured chats. Ownership projection connects a provider row to its native chat when the client can open that chat. Clients that cannot open the owner do not receive the row, and a terminal resume is removed when the native chat would become a second writer.

The same ownership rule applies to list rows, search hits, resume commands, and native-chat forks. Search remains available without owner metadata when the native chat host cannot install.

References: src/…/history-row-ownership-lookup.ts• L14-43 src/…/structured-session-ownership.ts• L46-119 src/…/structured-session-ownership.ts• L179-204

Session data protection

AI Vault reads sensitive conversation files, so each operation receives only the environment, host, and paths needed for its task. These checks reduce accidental disclosure and prevent session actions from becoming arbitrary file access. Operating-system permissions remain the final control.

Environment boundary

The scanner receives only the runtime values needed to start Node and find approved agent stores. It does not inherit arbitrary shell exports, Node loader settings, or credentials. Agent-root values remain available so relocated stores can be found.

References: src/…/session-scanner-service-env.ts• L1-23 src/…/session-scanner-service-env.ts• L25-101

Path and host boundary

Session files remain on their owning execution host. Resume, search attribution, child-session reads, and deletion checks use that host. Renderer paths are accepted only when they resolve inside a known provider root and match the provider's discoverable session shape.

The same source rules define what discovery can list and what deletion can accept. WSL access gates control WSL transcript paths. A failed discovery probe does not narrow the trusted roots used by deletion or child-session reads.

References: src/…/session-scanner-agent-sources.ts• L73-89 src/…/session-scanner-agent-sources.ts• L224-312 src/…/session-scanner-roots.ts• L38-80

Database and cache boundary

Provider databases are read-only and use bounded waits. WSL databases are read inside the distribution. A database failure becomes a source issue while other providers continue. The parse cache and search index are private and bounded, but they are not encryption and never replace provider records as the source of truth.

The parse cache uses a versioned schema and user-only database files. Invalid rows, old layouts, and repeated corruption cause a miss or disable the cache rather than returning untrusted history.

References: src/…/session-parse-cache-database.ts• L27-49 src/…/session-parse-cache-database.ts• L235-291 src/…/opencode-wsl-runtime-preparation.ts• L79-190

Resume flow

Resume turns stored provider history into a new agent launch on a compatible workspace and execution host. It preserves provider identity and source path, then adds the target workspace, account context, shell form, and launch surface required by that host.

Resume targets

The UI checks that the target workspace exists and uses the same execution host as the session. Runtime sessions return to their runtime host. WSL sessions need a shell that can reach the WSL source. A mismatch blocks the launch before a command is queued.

Rows without real conversation turns are not offered as normal resumes. Rows with queued prompts or child transcripts can show recovery information instead of appearing as an ordinary empty chat.

References: src/…/ai-vault-session-launch-actions.ts• L113-160 src/…/ai-vault-types.ts• L194-221 src/…/ai-vault-resume-startup.ts• L107-211

Provider preparation

Before launch, provider-specific preparation can attach a local Codex session to the selected account or prepare a host-local handoff for a database-backed conversation. Runtime sessions keep their recorded host and account context because the owning host performs remote work.

Native structured chats keep ownership of their conversation. A terminal action therefore creates a new provider session from saved content instead of opening the owned session as a second writer. The source is checked again when slow preparation completes.

References: src/…/ai-vault-resume-startup.ts• L214-258 src/…/structured-session-ownership.ts• L179-204 src/…/history-row-ownership-lookup.ts• L33-57

The following diagram shows how stored history becomes a host-bound terminal or native-chat launch.

flowchart LR
  A[Stored session row] --> B[Check workspace and execution host]
  B -->|valid target| C[Prepare provider account or session copy]
  C --> D[Build provider launch plan]
  D --> E[Launch terminal or native chat]
  B -->|invalid target| F[Show workspace or host error]

Resume surfaces

The session surface can be a terminal, a new native chat, an existing chat, or a hand-off to another agent. A native chat can replace an existing chat only after the new view opens. Busy chats require confirmation before replacement, and an already open owner is revealed instead of duplicated.

References: src/…/ai-vault-session-resume-here.ts• L47-135 src/…/ai-vault-session-launch-actions.ts• L144-221 src/…/AiVaultResumeInNewChatButton.tsx• L6-31

Deletion flow

Deletion is a host-owned destructive action. Local sessions use the desktop deletion path. Runtime sessions route deletion to the owning runtime and require the row's host pairing to remain valid. The action removes only provider-owned session units that discovery could have found.

Deletion eligibility

The validator accepts supported providers, known roots, discoverable session files, and complete session units. Some providers remove one file. Directory-shaped providers remove the session directory and its owned companions. Shared registries, aliases, database identities, child-only files, and unrelated sidecars remain protected.

The system creates a path-only removal plan, then checks the file type and resolved location again just before acting. The UI confirms the action before it sends the session identity and execution host to the owner.

References: src/…/session-delete-target.ts• L21-120 src/…/ai-vault-session-deletion.ts• L20-59 src/…/ai-vault-session-delete-action.ts• L82-128

Removal refresh

Provider companions are removed before the main transcript, or as one directory unit when the provider owns a directory. Missing paths count as success so a partial removal can be retried. WSL paths are checked and removed inside the distribution.

After confirmed removal, list, host, parse, service, and search caches invalidate. A late scan cannot restore the deleted row or its searchable text. An unreadable root does not count as proof of deletion.

References: src/…/session-delete.ts• L15-109 src/…/host-session-delete.ts• L21-76 src/…/session-search-deleted-sources.ts• L44-101 src/…/ai-vault-session-delete-action.ts• L119-151

AI Vault resume depends on the workspace and terminal systems that select an execution host and launch the agent. Continue with Agent workspaces, agent integrations and hooks, agent protocol client sessions, workspace and worktree lifecycle, native agent conversations, and automation services.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep provider discovery, parser output, sidecar enrichment, transcript consumers, search freshness, resume preparation, and deletion eligibility aligned. A provider shape change can otherwise list a session that cannot be searched, resumed, or removed.
  • Preserve execution-host stamping and pairing revisions at every runtime transport boundary. A returned host or pairing must not choose its own ownership.
  • Keep shared-root ownership rules aligned across candidate deduplication, parser labels, child counts, scope recovery, and deletion. A Pi/OMP overlap must not create duplicate rows or remove the wrong unit.
  • Keep cached session rows tied to source identity, sidecar state, schema version, and visibility. A refused sidecar read must remain retryable.
  • Keep the transcript reader position separate from parse-cache and search positions. A declined or partial read must not skip data for another consumer.
  • Keep committed and speculative search facts aligned with file identity, prefixes, generations, and cursors. A changed source must not reuse a stale position.
  • Keep service lanes, cancellation, child restart demand, heap recovery, worker limits, and shutdown flush behavior aligned when a private operation changes.
  • Keep scope path caps, path normalization, prior worktree ownership, and runtime host identity aligned. A scope must not widen when its path cannot be keyed.
  • Keep structured ownership checks aligned across list projection, search projection, resume, command validation, and native-chat fork creation.
  • Keep Hermes schema probing, lineage folding, activity recency, and display projection aligned. A schema or compaction change must not expose hidden continuation rows as separate chats.

Important failure modes

TriggerConsequenceGuard
The scanner child exits, times out, or sends malformed outputThe current history request failsFail active work, retry only safe unsent work, and open the fault circuit after repeated faults
The scanner child exhausts its heapA large scan could fail on every refreshRerun the held scan once on a replacement with a larger bounded heap
A transcript read is partial or malformedA list or index could contain only part of a conversationPublish only complete reads and keep the source due for a later replacement
A source file or sidecar changes during an append readSearch or previews can skip new data or keep stale metadataRequire source identity and prefix agreement, then replace or re-enrich
A configured root cannot be listedValid history can look deletedKeep the root unverifiable until a bounded listing proves absence
A runtime response supplies a different host or pairingA session can be resumed or removed on the wrong hostStamp the caller-selected host and fence mutations to the listed pairing
Antigravity origins share an ID or metadata names conflicting workspacesSeparate sessions can merge or a session can get the wrong workspaceKeep origins separate and accept only unique bounded metadata matches
A Droid settings sidecar is unavailableThe transcript row loses model or usage dataKeep the row and retry enrichment on a later scan
A Hermes schema or lineage is unknownHistory can be hidden or split into false chatsCheck the supported schema and report a scoped source issue
A native chat owns a provider rowA terminal launch can create a second writerProject ownership into list and search results and require a new unowned session for CLI forks
A delete path is outside a known root or changes type before removalThe action could remove an unrelated fileRecheck containment and target type immediately before removal
A forced refresh replaces a shared scan without transferring waitersCallers can see cancellation although a replacement is availableRegister the replacement before aborting the old scan

Key files

FileWhy to read it
src/…/ai-vault-types.tsDefines the session view, host identity, scope limits, recovery signals, and resumable-content rules
src/…/ai-vault.tsShows how IPC selects hosts, coalesces scans, handles cancellation, and projects native ownership
src/…/session-scanner-agent-sources.tsDefines provider roots, discoverable shapes, companion files, and shared-root rules
src/…/session-scanner-agent-parser.tsShows how provider candidates enter the common session view
src/…/session-parse-cache-database.tsShows the private cache contract, validation, schema recovery, and retention
src/…/session-scanner-service-client.tsShows request lanes, cancellation, child retirement, and restart handling
src/…/session-scanner-service-protocol.tsDefines the scanner service readiness and request messages
src/…/runtime-session-scanner.tsShows runtime validation, host stamping, pairing fencing, resume preparation, and deletion routing
src/…/session-transcript-reader.tsShows full and resumable transcript reads
src/…/session-transcript-consumers.tsShows independent consumers and incomplete-read handling
src/…/session-scanner-hermes-sqlite.tsShows Hermes conversation selection and transcript capture
src/…/session-scanner-antigravity-history.tsShows bounded workspace enrichment across Antigravity history origins
src/…/session-scanner-droid-settings.tsShows transcript and settings-sidecar enrichment
src/…/structured-session-ownership.tsConnects native-chat ownership to list, search, and legacy resume safety
src/…/session-search-indexer.tsShows search reconciliation, root refresh, and source health
src/…/session-search-retrieval.tsShows search scope, ranking, paging, and result hydration
src/…/session-delete-target.tsDefines safe deletion eligibility and removal plans
src/…/session-delete.tsPerforms final target checks and ordered host-local removal
src/…/ai-vault-session-launch-actions.tsShows terminal, native-chat, fork, and hand-off launch choices
src/…/ai-vault-session-delete-action.tsShows host capability checks, confirmation, deletion transport, and refresh feedback