Files
orca/src/cli/cli-error.ts
T
Neil c10881fa8c refactor(shared): organize execution and automation defining owners (#39776)
* refactor: import journal queue state from defining owners

* refactor(shared): organize execution and automation owners

* fix: retain type imports used by surviving test cases

* refactor: finish work item owners and refresh validation metadata

* test: infer reconnect status fixture type

* test(claude): resolve source files beside same-named directories

* test(runtime): group repository creation mock registrations
2026-11-08 06:46:09 -08:00

334 lines
11 KiB
TypeScript

import { computerUseErrorRecoveryData } from '../shared/computer-use-error-recovery'
import {
matchAutomationOwnerConflict,
stripAutomationOwnerConflictCode
} from '../shared/automations/ownership/automation-owner-conflict'
import { automationOwnerConflictRecovery } from './automation-owner-conflict-recovery'
import { worktreeSelectorRecovery } from './worktree-selector-recovery'
import { ambiguousWorkspaceChoices, selectorAmbiguityRecovery } from './selector-ambiguity-recovery'
import type { RuntimeRpcFailure } from './runtime-client'
import { RuntimeClientError, RuntimeRpcFailureError } from './runtime/types'
import { readableWslDistroCliRefusal } from './wsl-distro-cli-refusal'
export type CliErrorContext = {
commandPath?: readonly string[]
/** The `--worktree` value this invocation sent; the runtime's error never echoes it. */
worktreeSelector?: string
/** The runtime error omits the original --repo selector. */
repoSelector?: string
/** True when --environment, --pairing-code, --host runtime:, or their env vars chose a server. */
remoteServerSelected?: boolean
/** Concise orchestration failures: compact JSON plus one `error: <code>: <message>` stderr line. */
conciseOrchestration?: boolean
}
type ContextRecovery = { nextSteps: readonly string[] } & Record<string, unknown>
const STALE_HANDLE_SERVER_HINT =
'Terminal handles belong to the Orca server that issued them. If this handle came from a paired server (for example `orca terminal list --environment <server>`), pass the same --environment <server> to this command.'
function contextRecovery(error: unknown, context: CliErrorContext): ContextRecovery | undefined {
const code = cliErrorCode(error)
if (code === 'selector_not_found' && context.worktreeSelector) {
return worktreeSelectorRecovery(context.worktreeSelector)
}
// No selector can name one of two folders sharing an id; only the error's repair step applies.
if (code === 'selector_ambiguous' && !isDuplicateFolderIdData(errorData(error))) {
return selectorAmbiguityRecovery({
repo: context.repoSelector,
worktree: context.worktreeSelector,
remoteServerSelected: context.remoteServerSelected
})
}
// A remote handle sent locally looks stale rather than missing a flag.
if (
code === 'terminal_handle_stale' &&
context.commandPath?.[0] === 'terminal' &&
context.remoteServerSelected === false
) {
return { nextSteps: [STALE_HANDLE_SERVER_HINT] }
}
return undefined
}
function isDuplicateFolderIdData(data: unknown): boolean {
return data !== null && typeof data === 'object' && 'duplicateFolderId' in data
}
function errorData(error: unknown): unknown {
if (error instanceof RuntimeRpcFailureError) {
return error.response.error.data
}
return error instanceof RuntimeClientError ? error.data : undefined
}
export function cliErrorCode(error: unknown): string | undefined {
if (error instanceof RuntimeRpcFailureError) {
return error.response.error.code
}
return error instanceof RuntimeClientError ? error.code : undefined
}
export function formatCliError(error: unknown, context: CliErrorContext = {}): string {
const message = readableWslDistroCliRefusal(
error instanceof Error ? error.message : String(error)
)
const selector = contextRecovery(error, context)
const workspaceChoices =
error instanceof RuntimeClientError &&
!(error instanceof RuntimeRpcFailureError) &&
error.code === 'selector_ambiguous'
? ambiguousWorkspaceChoices(error.data)
: undefined
if (workspaceChoices) {
return formatMessageWithNextSteps(
`${message}\nWorkspace choices (JSON data):\n${JSON.stringify(workspaceChoices, null, 2)}`,
nextStepsFromData(errorData(error))
)
}
if (selector) {
return formatMessageWithNextSteps(
message,
nextStepsFromData(mergeContextRecovery(errorData(error), selector))
)
}
if (error instanceof RuntimeClientError && error.code === 'runtime_unavailable') {
if (hasOrchestrationRequestId(error.data)) {
return message
}
return formatRuntimeUnavailableError(message, error.data)
}
// Match before generic recovery; flattened errors may retain only the conflict token.
const conflict = automationOwnerConflictRecovery(matchAutomationOwnerConflict(error))
if (conflict) {
return formatMessageWithNextSteps(stripAutomationOwnerConflictCode(message), conflict.nextSteps)
}
const sidecarExit = computerSidecarExitRecovery(error, context)
if (sidecarExit) {
return formatMessageWithNextSteps(message, sidecarExit.nextSteps)
}
if (error instanceof RuntimeClientError) {
const nextSteps = nextStepsFromData(error.data)
if (nextSteps.length > 0) {
return formatMessageWithNextSteps(message, nextSteps)
}
if (error.code === 'invalid_argument' && context.commandPath?.[0] === 'computer') {
return formatMessageWithNextSteps(
message,
computerUseErrorRecoveryData('invalid_argument')?.nextSteps ?? []
)
}
}
if (
error instanceof RuntimeRpcFailureError &&
error.response.error.code === 'runtime_unavailable'
) {
return formatRuntimeUnavailableError(message, error.response.error.data)
}
if (error instanceof RuntimeRpcFailureError) {
return formatMessageWithNextSteps(message, nextStepsFromData(error.response.error.data))
}
return message
}
function hasOrchestrationRequestId(data: unknown): boolean {
return (
data !== null &&
typeof data === 'object' &&
typeof (data as { orchestrationRequestId?: unknown }).orchestrationRequestId === 'string'
)
}
function formatRuntimeUnavailableError(message: string, data: unknown): string {
const nextSteps = nextStepsFromData(data)
if (nextSteps.length > 0) {
return formatMessageWithNextSteps(message, nextSteps)
}
return `${message}\nOrca is not running. Run 'orca open' first.`
}
// Streaming commands print one JSON object per line with --json, so their failure is one line too.
const JSON_LINES_COMMANDS = new Set(['plugin dev watch'])
export function reportCliError(error: unknown, json: boolean, context: CliErrorContext = {}): void {
const selector = contextRecovery(error, context)
const concise = context.conciseOrchestration
if (json) {
const response = cliErrorJsonResponse(error, context, selector)
console.log(
concise
? JSON.stringify({ ok: false, error: response.error })
: JSON_LINES_COMMANDS.has(context.commandPath?.join(' ') ?? '')
? JSON.stringify(response)
: JSON.stringify(response, null, 2)
)
if (concise) {
console.error(formatOrchestrationErrorLine(response.error.code, response.error.message))
}
} else if (concise) {
// Recovery detail goes to stdout so stderr stays the one-line failure.
const [first = '', ...detail] = formatCliError(error, context).split('\n')
if (detail.length > 0) {
console.log(detail.join('\n'))
}
console.error(formatOrchestrationErrorLine(cliErrorCode(error) ?? 'runtime_error', first))
} else {
console.error(formatCliError(error, context))
}
}
// Agents that read only stderr, or pipe stdout through tail, must still see the failure.
export function formatOrchestrationErrorLine(
code: string,
message: string,
level: 'error' | 'warning' = 'error'
): string {
return `${level}: ${code}: ${message.split('\n')[0]}`
}
function cliErrorJsonResponse(
error: unknown,
context: CliErrorContext,
selector: ContextRecovery | undefined
): RuntimeRpcFailure {
if (error instanceof RuntimeRpcFailureError) {
const sidecarExit = computerSidecarExitRecovery(error, context)
const response = sidecarExit
? { ...error.response, error: { ...error.response.error, data: sidecarExit } }
: withAutomationOwnerConflictRecovery(error.response)
return selector
? {
...response,
error: {
...response.error,
data: mergeContextRecovery(response.error.data, selector)
}
}
: response
}
return {
id: 'local',
ok: false,
error: {
code:
matchAutomationOwnerConflict(error) ??
(error instanceof RuntimeClientError ? error.code : 'runtime_error'),
message: stripAutomationOwnerConflictCode(
error instanceof Error ? error.message : String(error)
),
data: localCliErrorData(error, context)
},
_meta: {
runtimeId: null
}
}
}
function withAutomationOwnerConflictRecovery(response: RuntimeRpcFailure): RuntimeRpcFailure {
const code = matchAutomationOwnerConflict(response)
const conflict = automationOwnerConflictRecovery(code)
if (!conflict || !code) {
return response
}
return {
...response,
error: {
...response.error,
// Restore conflict classification lost during transport flattening.
code,
message: stripAutomationOwnerConflictCode(response.error.message),
data: response.error.data ?? conflict
}
}
}
function formatMessageWithNextSteps(message: string, nextSteps: readonly string[]): string {
if (nextSteps.length === 0) {
return message
}
return `${message}\n${nextSteps.map((step) => `Next step: ${step}`).join('\n')}`
}
// Preserve both mutation request IDs and selector recovery hints.
function mergeContextRecovery(
data: unknown,
selector: ReturnType<typeof contextRecovery>
): unknown {
if (!selector) {
return data
}
if (
data &&
typeof data === 'object' &&
'validSelectorForms' in data &&
'nextSteps' in data &&
Array.isArray(data.validSelectorForms) &&
data.validSelectorForms.every((form: unknown) => typeof form === 'string') &&
Array.isArray(data.nextSteps) &&
data.nextSteps.every((step: unknown) => typeof step === 'string')
) {
return data
}
if (data === null || typeof data !== 'object') {
return selector
}
return {
...selector,
...data,
nextSteps: [...selector.nextSteps, ...nextStepsFromData(data)]
}
}
function nextStepsFromData(data: unknown): string[] {
if (
data &&
typeof data === 'object' &&
Array.isArray((data as { nextSteps?: unknown }).nextSteps)
) {
return (data as { nextSteps: unknown[] }).nextSteps.filter(
(step): step is string => typeof step === 'string'
)
}
return []
}
// Older servers do not include this recovery hint in error data.
function computerSidecarExitRecovery(error: unknown, context: CliErrorContext) {
if (
context.commandPath?.[0] !== 'computer' ||
cliErrorCode(error) !== 'accessibility_error' ||
!(error instanceof Error) ||
!error.message.startsWith('computer sidecar exited with code')
) {
return undefined
}
return computerUseErrorRecoveryData('accessibility_error', error.message)
}
function localCliErrorData(error: unknown, context: CliErrorContext): unknown {
const sidecarExit = computerSidecarExitRecovery(error, context)
if (sidecarExit) {
return sidecarExit
}
const selector = contextRecovery(error, context)
// Error-specific recovery takes precedence over the generic fallback.
if (error instanceof RuntimeClientError && error.data !== undefined) {
return mergeContextRecovery(error.data, selector)
}
if (selector) {
return selector
}
const conflict = automationOwnerConflictRecovery(matchAutomationOwnerConflict(error))
if (conflict) {
return conflict
}
if (
error instanceof RuntimeClientError &&
error.code === 'invalid_argument' &&
context.commandPath?.[0] === 'computer'
) {
return computerUseErrorRecoveryData('invalid_argument')
}
return undefined
}