Files
archived-orca/src/shared/agent-session-record.ts
T
Brennan Benson ae9bc8d120 A slept native-chat workspace reads asleep and hides (#28457)
* fix(sidebar): a slept chat workspace reads asleep and hides

* fix(sidebar): a wake during Sleep's teardown keeps the workspace awake

* test(sidebar): give the activation-race mock store the chat tab map Sleep reads

* feat(native-chat): the host marks the chats an explicit Sleep stopped

The fact "the user's Sleep put this chat to rest" now lives on the host
that runs the chat, on its session record, instead of in the window.

- New runtime capability agent-session.workspace-sleep-mark.v1 and an
  optional markAsleep on agentSession.sleepWorkspace (strict params, so
  only hosts advertising the capability are sent it).
- The Sleep close decides each chat's receipt inside the same per-session
  step that stopped it; with markAsleep it writes sleptAt in that step's
  record write, so a chat is marked exactly when it is in the receipt.
- The next send the host hands over clears sleptAt, whichever client sent
  it; the idle sweep and plain stops never mark.
- sleptAt rides the status summary (optional field), its equality, and
  the retained summary of a closed chat, so it survives restart through
  the persisted tab index.

* refactor(sidebar): read a slept chat from its host's mark, not a window record

The window no longer keeps its own saved record of which chats Sleep
stopped (explicitlySleptChatsByWorkspace). That record had to mirror every
host event that should end it (sends, replaced conversations, renames,
profile and WSL moves, removal, wakes during teardown), and each missed
mirror was a bug. The host now owns the fact (previous commit).

- Delete the record, its schema, store slice, workspace-session field
  registrations, moves, renames, purges, migrations and hydration, and the
  renderer clearing hooks. Those files are back to main.
- Opening a workspace no longer wakes its slept chats (product ruling):
  drop the chat Sleep-attempt tokens and their set-active-worktree hook. A
  slept chat wakes only when a send reaches its host, from any client.
- The status bridge mirrors each chat tab's published sleptAt into a
  store map keyed by the chat's pane key, dropped when its projection
  unmounts and never saved; a chat whose host runs it again is not slept.
- The asleep derivation, hide filter, palette, board and context menu read
  that map. Explicit Sleep sends markAsleep only to the local host and to
  hosts last probed with the new capability; a project move never does.

* fix(native-chat): preserve host-owned Sleep across fallback and legacy tabs

* fix(native-chat): clear Sleep when a new send is admitted

* chore: restore incoming documentation after merge hook formatting

* fix(native-chat): let admitted sends supersede pending Sleep receipts

* fix(sidebar): wait for host Sleep state before showing restored chats

* fix(sidebar): retain host Sleep answers when chat projections remount

* fix(native-chat): clear Sleep when queued drafts become sends

* test(sidebar): cover unknown and known chat Sleep state on the board

* test(vault): expect both host status capability checks

* test(native-chat): consolidate Sleep behavior coverage

* fix(native-chat): commit Sleep wake with send admission

* test: pin visibility while chat host is unidentified

* test: consolidate workspace sleep regression flows

* test: keep status feed regression within renderer boundary
2026-10-20 22:42:56 -07:00

386 lines
16 KiB
TypeScript

import { isAgentSessionRewindRecord, type AgentSessionRewindRecord } from './agent-session-rewind'
import { isAgentSessionLaunchArgs } from './agent-session-launch-args'
import { isAgentSessionConversationName } from './agent-session-conversation-name'
import {
isPersistedAgentSessionHandoffStage,
isPersistedAgentSessionRuntimeKind,
type PersistedAgentSessionLease,
type PersistedAgentSessionRecord
} from './agent-session-legacy-handoff-lease'
/**
* Durable agent-session record and its single-writer lease.
*
* The record is the session's identity — where it runs, which provider it talks to, which account
* home is pinned to it — and is independent of any terminal tab. The lease is the separate
* question of which process is currently allowed to write to it.
*/
import type { ExecutionHostId } from './execution-host'
import {
isAgentSessionConversationCommandRecord,
type AgentSessionConversationCommandRecord
} from './agent-session-conversation-command'
import {
decodePersistedAgentSessionProviderHandleChain,
type AgentSessionProviderHandleLink
} from './agent-session-provider-handle'
import {
isAgentSessionProviderContextBoundary,
type AgentSessionProviderContextBoundary
} from './agent-session-provider-context'
import { isStructuredAgentId } from './agent-session-provider-handle-encoding'
import {
isAgentSessionAccountHome,
MAX_PATH_LENGTH,
type AgentSessionAccountHome
} from './agent-session-account-home'
export type { AgentSessionAccountHome } from './agent-session-account-home'
export const AGENT_SESSION_RECORD_SCHEMA_VERSION = 2 as const
export type AgentSessionWorkspaceKind = 'git-worktree' | 'folder'
/**
* Where the provider process actually runs. WSL is called out separately from the execution host
* id because a WSL workspace is served by the local host but is a distinct filesystem, account
* root, and process namespace — two sessions there must never collide with their native twins.
*/
export type AgentSessionExecutionLocation = {
executionHostId: ExecutionHostId
/** Distro name when the provider runs inside WSL; null for native and remote hosts. */
wslDistro: string | null
workspaceId: string
workspaceKind: AgentSessionWorkspaceKind
}
/** Provider launch environment captured by the host when the session is created. */
export type AgentSessionLaunchEnv = Record<string, string>
/** Provider CLI arguments captured by the host when the session is created. */
export type AgentSessionLaunchArgs = string[]
/** Still persisted because older builds read it. The removed terminal handoff's `tui` is mapped
* away at decode (agent-session-legacy-handoff-lease). */
export type AgentSessionOwnerRuntimeKind = 'native'
/** The acquisition stage. Stages only older builds wrote are mapped away at decode. */
export type AgentSessionHandoffStage = 'new-owner-proving' | 'recovering'
/**
* PID-reuse-safe process identity. `spawnToken` is the only element available on every platform:
* process start time costs a CIM query on Windows and is absent in some containers.
*/
export type AgentSessionProcessIdentity = {
hostId: string
pid: number
processStartTimeMs: number | null
spawnToken: string
/** The Orca runtime that started this process and holds its transport, stamped when the owner is
* recorded; absent on owners older builds recorded. */
runtime?: string
}
/**
* `released` means no owner: a durable record that outlives its owner needs a name for that.
* `conflicted` is how a terminal owner an older build recorded loads: recovery waits it out and
* never stops it, because it is the user's own agent.
*/
export type AgentSessionClaimStatus = 'reserved' | 'live' | 'conflicted' | 'released'
export type AgentSessionDeathEvidence = {
kind: 'exit-observed' | 'pid-absent' | 'identity-mismatch'
detail: string
observedAt: number
/** Fence of the owner (or reservation) this death is about; a fence names exactly one. Absent on
* evidence older builds wrote, which then speaks for no turn. */
ownerFence?: number
/** The death interval's lower bound: the last time the runtime holding the owner's transport
* proved it alive. Only a probe's proof records it: absent on a surface-release exit, a failed
* start, and evidence older builds wrote. */
lastProvenAliveAt?: number
/** How the Orca runtime that held the owner ended, when the owner died with it: the quit or
* update it had begun, else 'crash'. Absent when a provider died on its own while Orca ran, and
* whenever that cannot be told. A string, since a newer build may write a cause this one does
* not know; read it with `isAgentSessionOrcaStopCause`. */
runtimeEnd?: string
}
export type AgentSessionLease = {
sessionId: string
runtimeKind: AgentSessionOwnerRuntimeKind
/** Durable monotonic integer; only acquisition CAS and proven eviction move it. */
runtimeFence: number
handoffStage: AgentSessionHandoffStage | null
/** Link id of the provider handle this owner proved; the full chain lives on the record. */
provenHandleLinkId: string | null
/** Null between the durable reservation and the observed spawn. */
ownerProcess: AgentSessionProcessIdentity | null
/** Reserved before any process exists, then matched against the child's environment. */
reservedSpawnToken: string | null
leaseDeadlineAt: number
/** While `ownerProcess` is set, the last time its transport holder proved it alive; parking in
* `recovering` proves nothing, so it leaves this alone. */
lastRenewedAt: number
handoffOperationId: string | null
/** Key id that minted the HMAC claim this lease was granted under. */
claimKeyId: string
claimStatus: AgentSessionClaimStatus
/** True from load until the host adjudicates it; no writer is granted while set. */
unreconciled: boolean
/**
* Lowest fence a future grant may use. Set only by an earlier build's import of its records file,
* when the copy came from its backup or sat beside a set-aside copy of the same chat: either may
* hide a fence already granted. The CURRENT fence is deliberately left alone: `live` means a
* handle proven at exactly that number, so rewriting it would invalidate the record it is trying
* to save.
*/
minimumNextFence?: number
/** Null on a released lease when nothing proved its owner gone. */
deathEvidence: AgentSessionDeathEvidence | null
}
export type AgentSessionRecord = {
schemaVersion: typeof AGENT_SESSION_RECORD_SCHEMA_VERSION
sessionId: string
location: AgentSessionExecutionLocation
/** The agent this session names, whether this build can run it or not. */
provider: string
providerHandleChain: AgentSessionProviderHandleLink[]
providerContextBoundary?: AgentSessionProviderContextBoundary
accountHome: AgentSessionAccountHome
/** The directory the provider first launched in, in the execution host's path syntax. Floating
* sessions resume here; worktree and folder ids still resolve by id to their durable place. */
launchDirectory?: string
/** Provider options the user chose, replayed whenever a new owner starts the session. */
options?: Record<string, string>
/** The permission mode the user chose; Orca's, so a provider's options answer never replaces it. */
permissionMode?: string
rewind?: AgentSessionRewindRecord
conversationCommand?: AgentSessionConversationCommandRecord
/** The name Orca gave this conversation, so a later acquisition need not name it again. */
conversationName?: string
/** When the user's Sleep stopped this chat; the next admitted send clears it. */
sleptAt?: number
launchArgs?: AgentSessionLaunchArgs
lease: AgentSessionLease
createdAt: number
updatedAt: number
}
/** Replaces the provider options or sets the permission mode, never both, so neither write
* touches the other. */
export type AgentSessionOptionsReplacement = {
sessionId: string
fence: number
now: number
} & ({ options: Readonly<Record<string, string>> } | { permissionMode: string })
const MAX_ID_LENGTH = 512
/** A death evidence's `detail` past this fails a load, so whoever writes one cuts it here. */
export const MAX_AGENT_SESSION_DEATH_DETAIL_CHARS = MAX_ID_LENGTH
const MAX_LAUNCH_ENV_ENTRIES = 256
const MAX_LAUNCH_ENV_VALUE_LENGTH = 65_536
const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/
function isBoundedString(value: unknown, max: number): value is string {
return typeof value === 'string' && value.length > 0 && value.length <= max
}
export function isAgentSessionId(value: unknown): value is string {
return typeof value === 'string' && SESSION_ID_PATTERN.test(value)
}
/** NUL cannot occur in a host id, distro name, or workspace id, so no component can forge a join. */
const SCOPE_KEY_SEPARATOR = '\u0000'
/**
* Scope key for host-and-workspace isolation. Native, WSL, and SSH copies of one workspace id are
* different sessions; collapsing them would let one host adjudicate another host's lease.
*/
export function agentSessionScopeKey(location: AgentSessionExecutionLocation): string {
return [location.executionHostId, location.wslDistro ?? '', location.workspaceId].join(
SCOPE_KEY_SEPARATOR
)
}
export function agentSessionExecutionLocationsEqual(
left: AgentSessionExecutionLocation,
right: AgentSessionExecutionLocation
): boolean {
return (
agentSessionScopeKey(left) === agentSessionScopeKey(right) &&
left.workspaceKind === right.workspaceKind
)
}
export function isAgentSessionExecutionLocation(
value: unknown
): value is AgentSessionExecutionLocation {
if (typeof value !== 'object' || value === null) {
return false
}
const location = value as Partial<AgentSessionExecutionLocation>
return (
isBoundedString(location.executionHostId, MAX_ID_LENGTH) &&
(location.wslDistro === null || isBoundedString(location.wslDistro, MAX_ID_LENGTH)) &&
isBoundedString(location.workspaceId, MAX_ID_LENGTH) &&
(location.workspaceKind === 'git-worktree' || location.workspaceKind === 'folder')
)
}
export function isAgentSessionProcessIdentity(
value: unknown
): value is AgentSessionProcessIdentity {
if (typeof value !== 'object' || value === null) {
return false
}
const identity = value as Partial<AgentSessionProcessIdentity>
return (
isBoundedString(identity.hostId, MAX_ID_LENGTH) &&
Number.isSafeInteger(identity.pid) &&
(identity.pid as number) > 0 &&
(identity.processStartTimeMs === null ||
(Number.isSafeInteger(identity.processStartTimeMs) &&
(identity.processStartTimeMs as number) >= 0)) &&
isBoundedString(identity.spawnToken, MAX_ID_LENGTH) &&
(identity.runtime === undefined || isBoundedString(identity.runtime, MAX_ID_LENGTH))
)
}
export function isAgentSessionOptions(value: unknown): value is Record<string, string> {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false
}
const entries = Object.entries(value)
return (
entries.length <= 32 &&
entries.every(
([key, option]) =>
isBoundedString(key, MAX_ID_LENGTH) && isBoundedString(option, MAX_ID_LENGTH)
)
)
}
export function isAgentSessionLaunchEnv(value: unknown): value is AgentSessionLaunchEnv {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false
}
const entries = Object.entries(value)
return (
entries.length <= MAX_LAUNCH_ENV_ENTRIES &&
entries.every(
([key, entry]) =>
isBoundedString(key, MAX_ID_LENGTH) &&
typeof entry === 'string' &&
entry.length <= MAX_LAUNCH_ENV_VALUE_LENGTH
)
)
}
function isAgentSessionDeathEvidence(value: unknown): value is AgentSessionDeathEvidence {
if (typeof value !== 'object' || value === null) {
return false
}
const evidence = value as Partial<AgentSessionDeathEvidence>
const { observedAt, lastProvenAliveAt, ownerFence, runtimeEnd } = evidence
return (
(evidence.kind === 'exit-observed' ||
evidence.kind === 'pid-absent' ||
evidence.kind === 'identity-mismatch') &&
isBoundedString(evidence.detail, MAX_AGENT_SESSION_DEATH_DETAIL_CHARS) &&
typeof observedAt === 'number' &&
Number.isSafeInteger(observedAt) &&
observedAt >= 0 &&
(ownerFence === undefined || (Number.isSafeInteger(ownerFence) && ownerFence >= 0)) &&
(lastProvenAliveAt === undefined ||
(Number.isSafeInteger(lastProvenAliveAt) &&
lastProvenAliveAt >= 0 &&
lastProvenAliveAt <= observedAt)) &&
(runtimeEnd === undefined || isBoundedString(runtimeEnd, MAX_ID_LENGTH))
)
}
function isPersistedAgentSessionLease(value: unknown): value is PersistedAgentSessionLease {
if (typeof value !== 'object' || value === null) {
return false
}
const lease = value as Partial<AgentSessionLease>
return (
isAgentSessionId(lease.sessionId) &&
isPersistedAgentSessionRuntimeKind(lease.runtimeKind) &&
Number.isSafeInteger(lease.runtimeFence) &&
(lease.runtimeFence as number) >= 0 &&
(lease.handoffStage === null || isPersistedAgentSessionHandoffStage(lease.handoffStage)) &&
(lease.provenHandleLinkId === null || isBoundedString(lease.provenHandleLinkId, 128)) &&
(lease.ownerProcess === null || isAgentSessionProcessIdentity(lease.ownerProcess)) &&
(lease.reservedSpawnToken === null ||
isBoundedString(lease.reservedSpawnToken, MAX_ID_LENGTH)) &&
Number.isSafeInteger(lease.leaseDeadlineAt) &&
Number.isSafeInteger(lease.lastRenewedAt) &&
(lease.handoffOperationId === null ||
isBoundedString(lease.handoffOperationId, MAX_ID_LENGTH)) &&
isBoundedString(lease.claimKeyId, MAX_ID_LENGTH) &&
(lease.claimStatus === 'reserved' ||
lease.claimStatus === 'live' ||
lease.claimStatus === 'conflicted' ||
lease.claimStatus === 'released') &&
typeof lease.unreconciled === 'boolean' &&
(lease.deathEvidence === null || isAgentSessionDeathEvidence(lease.deathEvidence))
)
}
/** Stored identity is independent of registrations; availability is checked only at start. */
export function isPersistedAgentSessionRecord(
value: unknown
): value is PersistedAgentSessionRecord {
if (typeof value !== 'object' || value === null) {
return false
}
const record = value as Partial<AgentSessionRecord>
const fieldsValid =
record.schemaVersion === AGENT_SESSION_RECORD_SCHEMA_VERSION &&
isAgentSessionId(record.sessionId) &&
isAgentSessionExecutionLocation(record.location) &&
isStructuredAgentId(record.provider) &&
isAgentSessionAccountHome(record.accountHome) &&
(record.launchDirectory === undefined ||
isBoundedString(record.launchDirectory, MAX_PATH_LENGTH)) &&
(record.options === undefined || isAgentSessionOptions(record.options)) &&
(record.permissionMode === undefined ||
isBoundedString(record.permissionMode, MAX_ID_LENGTH)) &&
(record.rewind === undefined || isAgentSessionRewindRecord(record.rewind)) &&
(record.providerContextBoundary === undefined ||
isAgentSessionProviderContextBoundary(record.providerContextBoundary)) &&
(record.conversationCommand === undefined ||
isAgentSessionConversationCommandRecord(record.conversationCommand)) &&
(record.conversationName === undefined ||
isAgentSessionConversationName(record.conversationName)) &&
(record.launchArgs === undefined || isAgentSessionLaunchArgs(record.launchArgs)) &&
!Object.hasOwn(record, 'launchEnv') &&
isPersistedAgentSessionLease(record.lease) &&
record.lease.sessionId === record.sessionId &&
Number.isSafeInteger(record.createdAt) &&
Number.isSafeInteger(record.updatedAt)
if (!fieldsValid) {
return false
}
const validated = record as AgentSessionRecord
// The row holds stored handles; validate the chain they decode to.
const chain = decodePersistedAgentSessionProviderHandleChain(validated.providerHandleChain)
const head = chain?.at(-1)
return (
chain !== null &&
// Chain validation already enforces one namespace.
(!head || head.handle.agent === validated.provider) &&
(validated.providerContextBoundary === undefined ||
validated.providerContextBoundary.afterFence <= validated.lease.runtimeFence) &&
(validated.lease.claimStatus !== 'live' ||
(validated.lease.ownerProcess !== null &&
// Null: the owner's process is live and its provider has not answered with a handle yet.
(validated.lease.provenHandleLinkId === null ||
(head?.linkId === validated.lease.provenHandleLinkId &&
head.mintedAtFence === validated.lease.runtimeFence))))
)
}