orca/docs/reference/agent-session-search-contract.md

Agent session search contract

AiVaultSearchRequest, AiVaultSearchResponse, AiVaultSearchHit, and AiVaultSearchStatus are defined in src/shared/ai-vault-search-types.ts and validated by src/shared/ai-vault-search-contract.ts.

Search and pagination

• Tool output beyond 3,072 characters per row is not indexed and not searchable; user and assistant text is indexed in full.
• A page cursor outstanding during a retention purge is refused once as stale-cursor; the client re-issues page 1.
• A phrase match across a chunk boundary of a long message is not supported.

aiVault.searchSessions(request) accepts query, optional scope (conversation or all, default all), freshness (indexed or wait-until-current, default indexed), limit, opaque cursor, filters, and debug (default false). Conversation scope searches user and assistant text. Filters accept agents, scopePaths, ISO since, and sort (relevance or newest). Paths refer to the execution host and work for folders without Git. Legacy tier and refresh fields are accepted and discarded; they do not change the defaults. Limits use the engine's resolver: default 20, integers clamped to 1–100, fractional numbers use the default. Long queries reach the engine so it can report truncation rather than fail validation.

Results contain kind: 'results', hits, page: { cursor, hasMore }, generation, truncated: { candidates, snippets, query, freshness }, and durationMs. snippets is a count; the other truncation fields are booleans. durationMs measures the engine search, excluding any reconciliation wait. debug: true adds debug: { route, repairedTerms?, plannerReport }; the report contains route, optional repairedTerms, and scope. Diagnostics never appear at the top level. Status is never attached to search results.

A cursor belongs to one query, one host's index generation, and an opaque persisted index incarnation. Query, scope, filters, and sorting must remain the same; page size may change. Writes that advance the generation can invalidate it, including retention purges. Clearing or rebuilding the database invalidates it even when the new generation counter matches. A refused cursor yields { kind: 'stale-cursor', generation, expectedGeneration? } and the client discards it and issues page 1 without a cursor. Reusing that refused cursor continues to fail; there is no server-side cursor acknowledgement state. Malformed cursors and cursors for a different query yield { kind: 'malformed-cursor' }. Generation checks also reject a first page if the index changes during retrieval. Generation is a fence, not a retained snapshot: a client cannot ask the host to recreate a previous generation.

Pages are per host only. Ordering is local to that host's query. Clients must discard cursors when changing hosts. All-computers search, merged ordering, per-host aggregate outcomes, and merged cursors are deferred to a separate PR. That follow-up must define generation fencing, page-size changes, unavailable hosts, and bounded parallel retrieval before exposing a combined result list.

Execution host routing

Search and status address one execution host: local, ssh:<target>, or runtime:<environmentId>. An omitted host means this desktop's local index. Invalid IDs and all are refused; neither can widen a request to other hosts.

• local searches this machine's index over desktop IPC.
• ssh:<target> asks that relay session and nothing else.
• runtime:<environmentId> asks that paired runtime over its RPC. A paired runtime answers for itself and never forwards through another desktop.

Each hit may carry executionHostId. The desktop stamps remote answers with the host it addressed rather than trusting an ID returned by that host. Local answers and older hosts may omit attribution.

Evidence and exposure

Each hit carries agent, session ID, title, cwd, branch, updated time, message count, score, source, and evidence. Evidence contains snippet, role, and timestamp; it is null for operator-only matches that have no text evidence. Snippet matches use [[ and ]] markers. Source presence is present, unverifiable, or missing; the current engine emits the first two. Loss of contact does not prove a source missing.

redactForTransport(hit, transport) is the exposure policy:

Transport	filePath / codexHome	resumeCommand	Status degradedRoots[].root
Desktop IPC on the same machine	Included when known, under source	Included only for present sources	Included
Runtime RPC on the same machine	Included when known, under source	Included only for present sources	Included
Relay or paired runtime/web/mobile client	Withheld; source keeps presence only	Withheld	Withheld

cwd, titles, snippets, and other hit metadata remain visible to paired clients. Snippets cross the authenticated transport as indexed; this contract does not apply an observability redactor to transcript content. A missing Codex home is omitted. Resume commands reuse the command stored by the transcript reader, constructed by the sidebar's buildAiVaultResumeCommand; this layer does not construct commands or execute them. The runtime uses its authenticated clientKind context to distinguish paired clients from same-machine RPC, never a request-supplied locality flag. The receiving remote client also applies the same exposure function.

Status, freshness, and availability

aiVault.searchStatus() returns enabled, phase (idle, indexing, current, degraded, or closed), filesIndexed, filesDue, filesFailed, degradedRoots (root and reason), lastReconcileAt, lastSweepCompletedAt, and generation. Times are milliseconds since epoch or null. These are the indexer's observations; an indexed row is not a new filesystem verification. A degraded root's root and raw reason can both contain host filesystem paths. Desktop IPC and same-machine runtime RPC receive the full diagnostic; relay and paired clients receive only the fixed reason "Source root could not be verified." for each degraded root. The array length retains the count.

wait-until-current calls service.reconcile() before searching. The adapter uses indexer.reconcile({ full: false }). After five seconds the endpoint searches anyway and sets truncated.freshness: true on results. It does not cancel the host's reconciliation. Completion before the deadline leaves the flag false; a reconciliation error before the deadline propagates. The indexer's bounded recent pass is not a promise that the entire historical corpus was swept.

Search unavailability is a value: { kind: 'unavailable', reason: 'disabled' | 'not-ready' | 'no-service' }. No registered service returns no-service. Status without a service has enabled: false, phase: 'idle', zero counts and generation, empty degraded roots, and null timestamps. This is a sentinel for an absent service, not a claim of an empty, current index. A registered service may report disabled or not-ready.

Boundaries and compatibility

• Desktop: aiVault:searchSessions and aiVault:searchStatus, via preload.
• Runtime and relay: aiVault.searchSessions and aiVault.searchStatus.
• CLI: orca search calls both over the runtime RPC, against the host that --environment / --pairing-code selects and no other. It reuses createSessionSearchClient, so an old host's refusal reaches the caller as unavailable/no-service rather than an error, and needs no new capability. In an Orca SSH terminal, the forwarded CLI defaults to the controlling Orca runtime's index. --path filters that index; it does not select the SSH host. --environment / --pairing-code can explicitly select a paired runtime.
• Desktop preload optionally accepts an execution host scope as a separate routing argument. It addresses exactly that host; missing connections never fall back to the local index. The web preload addresses its own paired runtime, answers all and any other host with unavailable/no-service rather than an error.

Requests and responses are parsed where received from another process. Existing relay JSON-RPC request/response framing needs no new stream opcode. Following the existing relay method probe pattern, an old host's explicit -32601 refusal (or runtime method_not_found) maps to unavailable/no-service on the client; status uses the absent-service sentinel above. Transport failures, authentication errors, and invalid payloads remain errors. Unknown request fields are stripped for wire compatibility.

The process-local setSessionSearchService(service | null) registry connects these endpoints to the production service installed by PR 3b. Desktop indexing runs in the scanner child; orcad and the SSH relay register their own in-process services. Registration alone does not grant consent.

Desktop index controls (PR8)

Settings → Agent Session History controls this desktop's persisted aiVaultSearch { enabled, historyDays } policy. It stays local even when another execution host is selected. Paired clients cannot grant consent or clear an index through this surface; SSH relay registration remains disabled without a separate host consent mechanism.

aiVault.clearSearchIndex() is a no-argument desktop-only preload operation over aiVault:clearSearchIndex. It addresses the local scanner child, not the selected remote host. The child's existing interactive request lane executes searchClear through SessionSearchInstance.clear(): close the indexer and database handles, remove the SQLite database and sidecars, then reconstruct only if consent remains enabled. Errors propagate to the settings pane. This operation never deletes original transcripts. There is no new runtime or relay method. Opaque cursors also carry a persistent database identity: clearing creates a new identity, so a pre-clear or legacy cursor returns stale-cursor even if the rebuilt numeric generation happens to match. Reopening the same database preserves its identity.

Disabling closes the indexer and keeps the index copy; clearing deletes the copy. Changing retention reuses the existing close-and-construct policy application. The settings pane reads status only while enabled and visible, polls only an observed indexing phase, and stops on completion or error. Opening the pane, changing policy, or pressing Refresh obtains a new observation. The indexer's own schedule does not depend on the pane.