Skip to content

armgit / orca

Public Imported from GitHub
0

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.

10.7 KB
Raw Blame
// 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]
}