Files
orca/src/shared/runtime-worktree-contracts.ts
T
Brennan Benson 912a723f6c Give terminal agents a lasting Agent ID with Copy Agent ID (#41286)
* Give terminal agents a lasting Orca Agent ID

Terminal agents now get an Orca ID (orca_session_id:<agent>_<uuid>) derived
from their own conversation id on the host that runs them, so it stays the
same across worktree sleep/wake, app restart and a hand-run resume in any
pane. The terminal pane menu gets Copy Agent ID beside Copy Session ID, and
worktree ps --json agent rows carry orcaSessionId. Messaging a terminal
agent by that ID is refused with a message naming its pane until terminal
delivery lands.

* Name terminal agents at row admission and fix review round 1

- Perf: a row's Agent ID is resolved once, when its provider key changes at
  admission (legacy rows via the status adapter's prepareRow hook, tmux rows at
  canonical commit) and carried on the row as runtime-only agentIdentity.
  Snapshots, publications and internal notifications only copy it; no key
  serialization, cache lookup or database access per walk. Drops the pane FIFO
  cache.
- Refusal: the identity service keeps a reverse index id -> rows, kept exact by
  the adapter's rowChanged hook; a terminal refusal reads only matching panes
  and names only confirmed running ones (no resume seeds, exited or
  unconfirmed restored rows).
- Retry: a read-only identity file is lookup-only and never mints; any store
  failure backs off all SQLite work for 30 s; a Copy click retries once.
- Menu: Copy Agent ID shows for a live pane only when its host stamped an ID,
  and for a sleeping pane only when this app owns it on macOS/Linux.
- SSH: a sleeping record keeps its connection; a foreign (non-WSL) one resolves
  no ID.
- Renderer keeps an existing ID only for the same agent, owner and provider key
  including the Pi transcript locator.
- tmux-selected terminal rows carry their ID at every snapshot seam and in Copy
  resolution; structured chat rows stay excluded.

* Keep Agent ID work out of notifications and reach Copy wherever a host can answer

- Internal status/provider notifications walk rows without Agent ID work:
  canonical (tmux-selected) rows are decorated only for outputs that carry
  the id (snapshots, live emit, ps, Copy). The tmux publish body is now
  publishTmuxSelectedStatus so tests drive the production path.
- A row this host can name but has not yet (failed or pending link) is
  published with orcaSessionId: null; older hosts omit the field. The
  renderer offers Copy Agent ID on a live row whenever the field is present,
  and the click retries through terminal.agentId.
- Hosts advertise terminal.agent-id.v1. A sleeping pane offers Copy Agent ID
  when its owner is this app on macOS/Linux, or a remote owner that advertises
  the capability on a known non-Windows platform, and its record names no
  foreign connection.
- "Running in pane" places require that this runtime observed the row; a
  saved status, Done included, is history.

* Guard the pane menu subscription and stop offering Copy where it can never succeed

- A settled read-only miss (no link in a newer build's identity file) no
  longer publishes orcaSessionId; only a resolved id or a pending failed link
  does, so Copy Agent ID is offered only where a click can succeed.
- Render contract for the per-pane menu selection: another pane's or host's
  status change re-renders no unaffected pane; a pane's own stamp flips its
  availability.

* Move terminal agent identity SQL into a worker thread

Main's blocking-SQLite ratchet forbids the synchronous identity store, so
(per the decider ruling) agent-identities.db is now owned by one lazy
worker-thread entry per hook-server owner, desktop and orcad alike.

- The schema, open/version handling, mint/link transaction and read-only
  behaviour move unchanged into agent-identity-worker-entry.ts; main keeps
  only the key type, path and an async client over WorkerThreadRequestQueue.
- Admission stays synchronous: a new key is published pending (null), one
  request per exact key is shared by every row and click, and the committed
  answer re-stamps the current rows still pending on that key (legacy and
  tmux-selected) as identity-only replays. Replies are fenced by store
  generation, key and current subscription; failures back off 30 s and a
  Copy click retries once.
- terminal.agentId and the terminal-ID refusal are async: Copy waits for the
  pending lookup and revalidates the pane; send/task routing resolves the
  terminal recipient (awaiting the store's has() on an index miss) before
  any synchronous routing or effects.
- The renderer treats the host's row naming a conversation as authoritative
  for its id, so a settled miss clears a pending null, while ID-less local
  updates keep it.
- Packaged for desktop and orcad; registered as a worker entry, no baseline
  growth.

* Own identity demand per key, publish settled ids as projections, recheck authority

Implements the second decider ruling for the identity worker:

- One owner-level demand table replaces the per-key promise backlog and the
  settled-row scan: each exact key a current row or caller needs has one
  record (identity, places, waiters); the pump sends the worker one operation
  at a time, only for keys still needed, so a healthy burst completes and
  detached keys are never sent. Operation deadlines start at dispatch; a
  caller's wait expiring never drops a row's demand.
- One failure gate for lookups and membership: after a failure nothing is
  sent for 30 s except one coalesced Copy attempt; a single owner wake
  retries while rows still wait, and cancels with the last demand or close.
- The retirement barrier outlives a client: a replaced worker must exit
  before another starts; a different store path is a different authority.
- Settlement re-stamps the stored row and publishes a projection only: window
  readers get the row without its hook event (no agent-state record) and
  session.tabs is woken by a row touch; no enriched subscriber, plugin event
  or freshness heartbeat runs again.
- Copy and terminal membership check the owner generation after their waits.
  A known chat is decided by the chat store alone; send, peer mail, reply and
  assignee admission resolve the terminal recipient before reading the facts
  they act on, recheck the sender after the wait, and group send reselects
  its audience and mailboxes after each wait before writing.

* Scope identity answers to their store authority, expire Copy grants with callers, index provider aliases

- One synchronized authority token before Copy/reverse fast paths, compared after their awaits;
  answers carry their authority and an ended store turns rows, tmux subjects and the reverse
  index pending together. Status path changes sync the authority outside admission.
- A failed operation reschedules the pump so a queued click gets its attempt; grants belong to
  live waiters and a click joining a running attempt earns none.
- Provider-native ids resolve through a commit-maintained alias index at the record store.
- Group fan-out no longer classifies authoritative candidates; @idle rereads statuses with
  current candidates before the final synchronous selection.
- Hook-server unit fixtures use an in-memory identity client; a real worker load/stop failure
  check covers the worker boundary.

* Pick a shared provider alias's owner among its owners only

The alias index keeps the store's listing order (readable, then unreadable) as derived ranks, updated from the draft's appended keys on commit, so a duplicate alias no longer walks the history per lookup.

* Ask a remote pane's host for its Agent ID by the host's own pane key

Copy Agent ID on a web-terminal surface sent the client's mirrored pane key, which the execution host does not know, so it answered null.

* Keep focus where the user moved, recover a missed identity re-stamp, ack peer-mail replays first

Copy Agent ID refocuses its pane only when focus is unclaimed or still in the pane; a carried pending row takes its key's settled answer; an already-delivered peer-mail retry is acknowledged before recipient preparation.
2026-11-12 16:18:16 -08:00

254 lines
9.9 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type { DictationTerm } from './dictation-dictionary'
import type { SmartTier } from './sidebar-list/sort-stamps'
import type {
AgentStatusState,
AgentType,
AgentWorkingMode
} from './agent-status/contracts/agent-status-types'
import type { AgentMainAgentStatus } from './agent-status/lifecycle/main-agent-status'
import type { ProgramStatusFacet } from './program-status/facet'
import type { AgentListVerdict } from './agent-status/presentation/agent-list-status'
import type { CheckStatus, ProviderCheckSummary } from './github/pull-requests/pull-request-types'
import type { AgentChildWorkView } from './agent-status/child-work/agent-status-child-work-view'
import type { AgentSubagentSnapshot } from './agent-status/contracts/agent-status-subagent-snapshot'
import type { RuntimeTerminalInteractiveWait } from './runtime-terminal-contracts'
import type { BaseRefSearchResult, Repo } from './repo-types'
import type { CreateWorktreeResult, RemoveWorktreeResult } from './worktree/create-types'
import type {
CrossStoreWorkspaceLineage,
WorkspaceLineageEdge,
WorkspaceLineage,
WorktreeLineage,
WorktreeLineageWarning
} from './worktree/lineage-types'
import type { RuntimeListingHostScope } from './runtime-listing-host-scope'
import type { GitWorktreeInfo, Worktree } from './worktree/types'
import type { WorkspaceStatusWarning } from './workspace-status-warning'
import type { WorktreeStatus } from './worktree-status-rollup'
export type RuntimeWorktreeSetResult = {
worktree: RuntimeWorktreeRecord
/** Older hosts omit warnings; metadata writes still succeed. */
warnings?: WorkspaceStatusWarning[]
}
export type RuntimeWorktreeAgentRow = {
paneKey: string
/** The host's Orca id for this terminal agent's conversation; old hosts omit it. */
orcaSessionId?: string
parentPaneKey: string | null
state: AgentStatusState
workingMode?: AgentWorkingMode
agentType: AgentType | null
prompt: string
taskTitle: string | null
displayName: string | null
/** The name desktop's compact row leads with (rename, chat or live title). Old hosts omit it. */
conversationName?: string
lastAssistantMessage: string | null
toolName: string | null
toolInput: string | null
interrupted: boolean
/** Main-agent state/verdict/clock even while subagents keep the row working; old hosts omit it, falling back to interrupted. */
mainAgent?: AgentMainAgentStatus
/** Same as `terminal show`, only when requested: null is "looked, no wait"; absent is not evaluated (structured workers, old hosts). */
agentWait?: RuntimeTerminalInteractiveWait | null
stateStartedAt: number
updatedAt: number
/** Native canonical views win over the CLI roster, including an explicit empty list. */
children?: AgentChildWorkView[]
subagents?: AgentSubagentSnapshot[]
/** The host's freshness verdict; child clocks cannot be compared with the phone's clock. */
subagentObservation?: 'live' | 'unverifiable'
restoredUnconfirmed?: boolean
/** A structured host still owns the provider child, so age alone cannot stale it. Old hosts omit this. */
structuredHostOwned?: true
/** A connected PTY backs the row, so a stale row reads "No update in …" rather than idle. Old hosts omit this. */
hasLivePty?: true
/** The program's own OSC 7501 report; never decides `state`. Optional: old hosts never send it. */
programStatus?: ProgramStatusFacet
/** How the desktop Agents list shows this agent. Omitted with no desktop window, by old hosts, and for a turn newer than the window's last verdicts. */
activity?: AgentListVerdict
}
export type RuntimeWorktreePsSummary = {
workspaceKind?: 'git' | 'folder-workspace'
worktreeId: string
repoId: string
hostId?: Worktree['hostId']
/** Host-qualified identity; tells same-id rows on different hosts apart. Absent from older hosts. */
identity?: Worktree['identity']
terminalPlatform?: NodeJS.Platform
repo: string
path: string
priorWorktreeIds?: string[]
branch: string
isArchived: boolean
isMainWorktree: boolean
hasHostSidebarActivity: boolean
worktreeInstanceId?: string
lineageWorktreeInstanceId?: string
parentWorktreeInstanceId?: string
parentWorktreeId: string | null
childWorktreeIds: string[]
/** This row's parent in another Orca store; lineage fields above stay null for it, so older readers show it standalone. */
crossStoreParent?: CrossStoreWorkspaceLineage
/** Its folder workspace parent; null for none, absent from older hosts. Lineage fields above stay null for it. */
workspaceLineage?: WorkspaceLineageEdge | null
displayName: string
workspaceStatus: string
sortOrder: number
manualOrder?: number
lastActivityAt?: number
/** The owning host's Smart stamps (sidebar-list/sort-stamps.ts); absent tier is Rest. */
smartTier?: SmartTier
smartAt?: number
/** Set by a host that writes sort stamps: clients sort Recent and Smart by them alone. */
sortedByStamps?: true
createdAt?: number
creatorProvenance?: Worktree['creatorProvenance']
linkedIssue: number | null
/** The cached PR the desktop's PR lanes read, else a linked number with state UNCACHED_LINKED_PR_STATE. Old hosts omit title/url/checks. */
linkedPR: {
number: number
state: string
title?: string
url?: string
checksStatus?: CheckStatus
checksSummary?: ProviderCheckSummary
} | null
linkedLinearIssue: string | null
linkedGitLabMR: number | null
linkedGitLabIssue: number | null
linkedItems?: Worktree['linkedItems']
comment: string
isPinned: boolean
isActive: boolean
unread: boolean
liveTerminalCount: number
hasAttachedPty: boolean
/** Lost-contact terminals are neither liveTerminalCount nor exited; current hosts send even zero, old hosts omit. */
unverifiableTerminalCount?: number
lastOutputAt: number | null
preview: string
status: RuntimeWorktreeStatus
/** Optional discriminator for a working workspace; older clients fall back to ordinary working. */
workingMode?: AgentWorkingMode
/** The desktop sidebar dot, including failed/interrupted/unconfirmed; older hosts omit it. */
sidebarStatus?: WorktreeStatus
agents: RuntimeWorktreeAgentRow[]
/** See `Worktree.removing`; sent only to clients that advertise background removal. */
removing?: true
/** The owning host committed removal intent before publishing this row. */
removalRecorded?: true
/** See `GitWorktreeInfo.removalError`. */
removalError?: string
/** Host-derived workspace kinds. Missing defaultBranch retains reader guesses; other missing flags show the row.
* Older hosts omit these facts. */
defaultBranch?: boolean
automationCreated?: true
/** The automation's name when it made the row; older hosts send only `automationCreated`. */
automationName?: string
cliCreated?: true
detachedHead?: true
/** Other-client classification for this host’s own phone, which shares its filter setting. */
desktopOtherClient?: true
/** Set by a relaying desktop that created this workspace's environment from a recipe. */
recipeEnvironment?: { name: string; destroys?: boolean }
}
export type RuntimeGitLocalBranches = {
current: string | null
branches: string[]
committedAt?: Record<string, number>
worktreePaths?: Record<string, string>
}
export type RuntimeSpeechModelSummary = {
id: string
label: string
provider: 'local' | 'openai'
sizeBytes: number | null
recommended: boolean
status: 'ready' | 'not-downloaded' | 'downloading' | 'extracting' | 'error'
progress: number | null
}
export type RuntimeSpeechSetupState = {
enabled: boolean
selectedModelId: string
dictationMode: 'toggle' | 'hold'
/** Toggle plus hold-to-record is Auto. */
dictationHoldToRecord: boolean
/** Phones that recognize speech themselves clean their own text by this switch. */
removeFillerWords: boolean
/** Seconds of silence that end a tap-started dictation; null never. Absent from older hosts (60). */
stopAfterSilenceSeconds?: number | null
/** ...and spell these terms, repo terms first; absent from older hosts. */
dictationTerms?: DictationTerm[]
models: RuntimeSpeechModelSummary[]
}
export type RuntimeGitSwitchResult = { ok: true; branch: string; head?: string; warning?: string }
export type RuntimeGitCheckoutResult = {
ok: true
branch: string
}
/** A linked PR the host has no cached state for: it shows a badge but, like desktop, sits in the In progress lane. */
export const UNCACHED_LINKED_PR_STATE = 'unknown'
export type RuntimeWorktreeStatus = 'active' | 'working' | 'permission' | 'done' | 'inactive'
export type RuntimeWorktreeRecord = Worktree & {
parentWorktreeId: string | null
childWorktreeIds: string[]
lineage: WorktreeLineage | null
workspaceLineage?: WorkspaceLineage | null
/** A parent in another Orca store (worktree.show); older hosts omit it. */
crossStoreLineage?: CrossStoreWorkspaceLineage | null
git: GitWorktreeInfo
}
export type RuntimeWorktreeCreateResult = {
worktree: RuntimeWorktreeRecord
lineage: WorktreeLineage | null
workspaceLineage?: WorkspaceLineage | null
crossStoreLineage?: CrossStoreWorkspaceLineage | null
warnings: WorktreeLineageWarning[]
warning?: string
startupTerminal?: CreateWorktreeResult['startupTerminal']
agentTerminalHandle?: string
}
export type RuntimeWorktreeRemoveResult = RemoveWorktreeResult & {
removed: boolean
warning?: string
}
export type RuntimeWorktreePsResult = {
worktrees: RuntimeWorktreePsSummary[]
totalCount: number
truncated: boolean
/** Absent from hosts that predate the field; treat that scope as unverifiable. */
hostScope?: RuntimeListingHostScope
}
export type RuntimeRepoList = { repos: Repo[] }
export type RuntimeRepoSearchRefs = {
namespace?: 'remote'
refs: string[]
refDetails?: BaseRefSearchResult[]
truncated: boolean
}
export type RuntimeWorktreeListResult = {
worktrees: RuntimeWorktreeRecord[]
totalCount: number
truncated: boolean
/** Absent from hosts that predate the field; treat that scope as unverifiable. */
hostScope?: RuntimeListingHostScope
}