mirror of
https://github.com/stablyai/orca.git
synced 2026-11-18 11:54:46 +00:00
* 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.
254 lines
9.9 KiB
TypeScript
254 lines
9.9 KiB
TypeScript
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
|
||
}
|