Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
// Require wording and next steps for every new refusal reason at compile time.
import type { AgentSessionFailureKind } from './agent-session-failure'
import type { AgentSessionRefusalReason } from './agent-session-refusal-details'
import type { AgentSessionWriteNoticeSentence } from './agent-session-write-notice-copy'
import type { AgentSessionWireRefusalCode } from './agent-session-wire-refusals'
import type { AgentSessionWriteKind, AgentSessionWriteRefusal } from './agent-session-write-failure'
/** What the person can do about a refusal with this reason. */
export type AgentSessionRefusalAction =
/** Use the control that sent the write again. */
| 'retry'
/** Wait for what the notice names; its step says what. */
| 'wait'
/** Take the step the notice names first. */
| 'actFirst'
/** Continue somewhere else: the current conversation, or a new chat. */
| 'goElsewhere'
| 'checkChat'
| 'updateOrca'
/** What the write was for is over: the question it answered moved on. */
| 'nothingLeft'
/** Orca's own state or fault; nothing the person does gets past it. */
| 'hostFinding'
export type AgentSessionRefusalReasonWords =
/** The code's own words are the honest ones for this reason. */
| { words: 'code'; action: AgentSessionRefusalAction }
/** What stopped the write, and the step past it where the person has one to take. */
| {
cause: AgentSessionWriteNoticeSentence
step?: AgentSessionWriteNoticeSentence
action: AgentSessionRefusalAction
/** Its words when what failed is reading the chat's history. */
history?: { cause: AgentSessionWriteNoticeSentence; step: AgentSessionWriteNoticeSentence }
}
/** A start that failed: the sentence that failure has everywhere, whose next step is a send. */
| { fact: AgentSessionFailureKind; action: AgentSessionRefusalAction }
/** A failure's sentence, naming the agent, then `step`: the whole notice for `writes`. */
| {
fact: AgentSessionFailureKind
action: AgentSessionRefusalAction
step: AgentSessionWriteNoticeSentence
writes: readonly AgentSessionWriteKind[]
}
function codeWords(action: AgentSessionRefusalAction): AgentSessionRefusalReasonWords {
return { words: 'code', action }
}
function causeWords(
cause: AgentSessionWriteNoticeSentence,
action: AgentSessionRefusalAction,
step?: AgentSessionWriteNoticeSentence
): AgentSessionRefusalReasonWords {
return step ? { cause, step, action } : { cause, action }
}
const AGENT_STARTING = causeWords('agentStarting', 'wait', 'waitForStart')
const OWNER_UNPROVEN = causeWords('ownerUnproven', 'actFirst', 'reopenChat')
// Only a terminal agent an older build recorded holds a claim; quitting it frees the chat.
const TERMINAL_CLAIM = causeWords('terminalAgentHoldsChat', 'actFirst', 'quitTerminalAgent')
// Require all code/reason pairs; create/attach/hold/import-only reasons retain code wording because they never reach chat writes.
const REASON_WORDS = {
agent_session_operation_invalid: {
requestMalformed: codeWords('hostFinding'),
operationIdInvalid: codeWords('hostFinding'),
messageIdReused: codeWords('hostFinding'),
// Settled under that id, so the control's retry goes out under a new one.
operationRefusedEarlier: codeWords('retry'),
journalWriteFailed: causeWords('recordFailed', 'retry'),
// Any other write reads the code's words, as a client before this reason does.
stopFailed: { fact: 'stopFailed', action: 'retry', step: 'tryAgain', writes: ['stop'] },
// The card's Cancel button stays; its notice names the step.
cancelNotSaved: causeWords('cancelNotSaved', 'retry', 'tryAgain'),
attachmentExpired: causeWords('attachmentExpired', 'actFirst', 'reattachFile'),
conversationCleared: causeWords(
'conversationCleared',
'goElsewhere',
'openCurrentConversation'
),
// Only an older host sends this, and it keeps refusing the chat, so only a new chat continues.
clearUnconfirmed: causeWords('clearUnfinished', 'goElsewhere', 'startNewChat'),
// Only an older host sends this, for a /clear it never settled; only that host resolves it.
conversationCommandUnconfirmed: codeWords('hostFinding'),
conversationCommandInFlight: causeWords('commandRunning', 'wait', 'waitForCommand'),
// The chat's agent process is being replaced, which a start or restart does.
handoffInFlight: AGENT_STARTING,
continuationSuperseded: causeWords('continuationSuperseded', 'nothingLeft'),
turnActive: causeWords('turnActive', 'wait', 'waitForTurn'),
promptPending: causeWords('promptPending', 'actFirst', 'answerFirst'),
backgroundTasksRunning: causeWords('backgroundTasksRunning', 'wait', 'waitForBackgroundTasks'),
messagesUnsettled: causeWords('messagesUnsettled', 'actFirst', 'settleEarlierMessage'),
queueTooLarge: causeWords('queueTooLarge', 'actFirst', 'shrinkQueue'),
// The rewind control words its own refusals; anywhere else says only that it did not happen.
rewindRefused: codeWords('hostFinding'),
rewindUnconfirmed: codeWords('hostFinding'),
promptGone: causeWords('questionChanged', 'nothingLeft'),
// Name the agent that ended before an answer, with sending a message as the next step.
promptOwnerEnded: { fact: 'providerExited', action: 'nothingLeft' },
optionRejected: causeWords('optionRejected', 'retry'),
providerStarting: AGENT_STARTING,
goalsUnsupported: causeWords('goalsUnsupported', 'hostFinding'),
providerRejected: causeWords('agentRefused', 'retry'),
providerStartFailed: { fact: 'providerStartFailed', action: 'retry' },
notSignedIn: { fact: 'notSignedIn', action: 'actFirst' },
cliMissing: { fact: 'cliMissing', action: 'actFirst' },
historyTooLarge: { fact: 'historyTooLarge', action: 'goElsewhere' },
managedAccountEnvOverride: { fact: 'managedAccountEnvOverride', action: 'actFirst' },
accountSwitchInProgress: { fact: 'accountSwitchInProgress', action: 'wait' },
managedAccountUnsupported: { fact: 'managedAccountUnsupported', action: 'actFirst' },
launchFolderMissing: { fact: 'launchFolderMissing', action: 'actFirst' },
historyInOtherAccount: { fact: 'historyInOtherAccount', action: 'actFirst' },
claudeAccountFolderMissing: { fact: 'claudeAccountFolderMissing', action: 'actFirst' },
claudeAccountSetupFailed: { fact: 'claudeAccountSetupFailed', action: 'retry' },
agentCommandNotRunnable: { fact: 'agentCommandNotRunnable', action: 'actFirst' },
runtimeNotInstalled: { fact: 'runtimeNotInstalled', action: 'actFirst' },
fullAccessAsRoot: { fact: 'fullAccessAsRoot', action: 'actFirst' },
launchPreparationFailed: { fact: 'launchPreparationFailed', action: 'retry' },
conversationOpenInTerminal: { fact: 'conversationOpenInTerminal', action: 'actFirst' },
conversationOpenElsewhere: { fact: 'conversationOpenElsewhere', action: 'actFirst' },
attachFailed: codeWords('retry')
},
agent_session_ownership_unknown: {
sessionNotAttached: codeWords('retry'),
noLiveOwner: codeWords('retry'),
ownerUnproven: OWNER_UNPROVEN,
claimConflicted: TERMINAL_CLAIM,
recordMissing: codeWords('retry'),
replaySuperseded: codeWords('retry'),
leaseMoved: codeWords('retry'),
spawnIdentityMismatch: codeWords('hostFinding'),
notResumable: codeWords('retry'),
noProviderChild: codeWords('retry'),
conversationHeldElsewhere: codeWords('retry'),
// Trying again retries the stop that could not prove the exit.
previousExitUnverifiable: causeWords('ownerUnproven', 'retry')
},
agent_session_conflict: {
chatStarting: AGENT_STARTING,
ownerUnproven: OWNER_UNPROVEN,
claimConflicted: TERMINAL_CLAIM,
ownerAlive: codeWords('retry'),
identityMismatch: codeWords('hostFinding'),
sessionExists: codeWords('retry'),
conversationHeldElsewhere: codeWords('retry'),
tabIdTaken: codeWords('retry')
},
execution_owner_reconciling: {
hostReconciling: causeWords('hostReconciling', 'wait', 'waitMoment'),
recordUnreadable: causeWords('recordUnreadable', 'hostFinding')
},
agent_session_checkpoint_stale: {
fenceStale: codeWords('retry'),
leaseMoved: codeWords('retry'),
recordMissing: codeWords('retry')
},
agent_session_identity_required: {
recordMissing: causeWords('chatNotFound', 'goElsewhere', 'startNewChat'),
transcriptNotFound: codeWords('retry'),
transcriptUnreadable: causeWords('historyUnavailable', 'retry', 'tryAgain')
},
agent_session_operation_conflict: {
fingerprintMismatch: codeWords('hostFinding'),
operationIdReused: codeWords('hostFinding'),
handoffInFlight: codeWords('retry')
},
agent_session_operation_expired: { operationExpired: codeWords('retry') },
agent_session_operation_capacity: { operationCapacity: codeWords('updateOrca') },
agent_session_operation_unknown: {
outcomeUnknown: codeWords('checkChat'),
resultLost: codeWords('checkChat'),
rewindUnconfirmed: codeWords('checkChat'),
tabUnconfirmed: codeWords('checkChat')
},
agent_session_item_revision_stale: { promptMoved: codeWords('nothingLeft') },
agent_session_already_resolved: { promptAlreadyResolved: codeWords('nothingLeft') },
agent_session_journal_unreadable: {
// No retry reads past damage, and the words name no step: it only can't load.
journalCorrupt: causeWords('historyUnusable', 'hostFinding'),
// Says its step despite 'retry' unless a Retry stands beside it: the phone often has none.
journalUnavailable: causeWords('historyUnavailable', 'retry', 'tryAgain'),
// Writes meet newer/read-only databases; reads meet this chat, opened only by an update.
journalWrittenByNewerOrca: {
...causeWords('savedByNewerOrca', 'updateOrca', 'updateOrcaToKeepUsing'),
history: { cause: 'chatSavedByNewerOrca', step: 'updateOrcaToOpenChat' }
}
},
// Unknown methods justify the code's update advice; unsupported agents/locations or absent chat hosts do not. Only hostUnsupported names the unsupported cause; missing client capabilities retain older copy.
structured_agent_session_unsupported: {
clientCapabilityMissing: causeWords('notAvailable', 'hostFinding'),
hostDisabled: causeWords('notAvailable', 'hostFinding'),
hostUnsupported: causeWords('cannotRunHere', 'hostFinding')
},
agent_session_owner_restart_failed: {}
} satisfies {
[C in AgentSessionWireRefusalCode]: Record<
AgentSessionRefusalReason<C>,
AgentSessionRefusalReasonWords
>
}
/** The words and next step a reason gets; undefined when the refusal names none. */
export function agentSessionRefusalReasonWords(
failure: AgentSessionWriteRefusal
): AgentSessionRefusalReasonWords | undefined {
const reason = failure.details?.reason
const byReason: Partial<Record<string, AgentSessionRefusalReasonWords>> | undefined =
REASON_WORDS[failure.code]
return reason === undefined ? undefined : byReason?.[reason]
}