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.4 KB
Raw Blame
import { agentArgTerminatorIndex } from './agent-session-option-agent-args'
import { getAgentSessionOptionLaunchCatalog } from './agent-session-option-launch'
import { findOptionOccurrence } from './command-option-occurrence'
import {
  quoteStartupArg,
  tokenizeStartupCommand,
  type AgentStartupShell
} from './tui-agent-startup-shell'
import type { TuiAgent } from './tui-agent'
import { TUI_AGENT_DISPLAY_NAMES } from './tui-agent-display-names'

export const EXTRA_AGENT_ARGS_MAX_BYTES = 4096
export const EXTRA_AGENT_ARGS_HOST_UPDATE_REQUIRED =
  'Update Orca on this host to use extra arguments.'
export const EXTRA_AGENT_ARGS_REQUIRE_FRESH_SESSION =
  'Extra arguments require a fresh session for every run.'

type ExtraAgentArgKind = 'model' | 'effort' | 'repeatable'

type ExtraAgentArgOption = {
  kind: ExtraAgentArgKind
  aliases: readonly string[]
  /** Accepts only values with this prefix, e.g. Codex's `-c model_reasoning_effort=`. */
  valuePrefix?: string
}

const MODEL_OPTION = { kind: 'model', aliases: ['--model'] } as const
const MODEL_OR_M_OPTION = { kind: 'model', aliases: ['-m', '--model'] } as const

// Allowlist paired-client extras so they cannot alter permissions or Orca-owned prompt/resume/cwd/print/config/MCP flags.
const EXTRA_AGENT_ARG_OPTIONS: Partial<Record<TuiAgent, readonly ExtraAgentArgOption[]>> = {
  claude: [
    MODEL_OPTION,
    { kind: 'effort', aliases: ['--effort'] },
    { kind: 'repeatable', aliases: ['--add-dir'] }
  ],
  codex: [
    MODEL_OR_M_OPTION,
    { kind: 'effort', aliases: ['-c', '--config'], valuePrefix: 'model_reasoning_effort=' }
  ],
  codebuddy: [MODEL_OPTION, { kind: 'effort', aliases: ['--effort'] }],
  // Cursor composes effort into the model id, so only the model is a flag.
  cursor: [MODEL_OR_M_OPTION],
  grok: [MODEL_OR_M_OPTION, { kind: 'effort', aliases: ['--effort', '--reasoning-effort'] }],
  omp: [MODEL_OPTION]
}

export function supportsExtraAgentArgs(agent: TuiAgent): boolean {
  return EXTRA_AGENT_ARG_OPTIONS[agent] !== undefined
}

export function getExtraAgentArgsPlaceholder(agent: TuiAgent): string {
  return (EXTRA_AGENT_ARG_OPTIONS[agent] ?? [])
    .map((option) => {
      const value =
        option.kind === 'model'
          ? agent === 'claude'
            ? 'opus'
            : 'model-id'
          : option.kind === 'effort'
            ? 'high'
            : 'docs'
      return `${option.aliases[0]} ${option.valuePrefix ?? ''}${value}`
    })
    .join(' ')
}

// C0, DEL, C1, and the Unicode line/paragraph separators.
function hasControlCharacter(value: string): boolean {
  for (const char of value) {
    const code = char.codePointAt(0) ?? 0
    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029) {
      return true
    }
  }
  return false
}

// One English table: `error` stays English for older readers; the renderer translates by code.
export const EXTRA_AGENT_ARGS_FAILURE_COPY = {
  unsupportedAgent: "Extra arguments aren't supported for this agent yet.",
  tooLarge: 'Extra arguments must be 4 KB or less.',
  controlCharacters: 'Extra arguments cannot contain control characters or line breaks.',
  invalid: 'Extra arguments are invalid: {{detail}}',
  shellSyntax: "{{text}} uses shell syntax that extra arguments don't allow.",
  terminator: '"--" isn\'t allowed in extra arguments.',
  notAnOption:
    '"{{token}}" isn\'t an option. Extra arguments for {{agent}} accept only: {{allowed}}.',
  optionNotAllowed:
    '"{{option}}" isn\'t allowed in extra arguments for {{agent}}. Allowed: {{allowed}}.',
  missingValue: '"{{option}}" needs a value.',
  valueNotAllowed:
    '"{{option}} {{value}}" isn\'t allowed. {{agent}} extra arguments accept only "{{option}} {{prefix}}<level>".',
  modelRepeated: 'Extra arguments set the model more than once.',
  effortRepeated: 'Extra arguments set the effort more than once.'
} as const

export type ExtraAgentArgsFailureCode = keyof typeof EXTRA_AGENT_ARGS_FAILURE_COPY

export type ExtraAgentArgsFailure = {
  ok: false
  error: string
  errorCode: ExtraAgentArgsFailureCode
  errorParams?: Record<string, string>
}

function extraAgentArgsFailure(
  errorCode: ExtraAgentArgsFailureCode,
  params?: Record<string, string>
): ExtraAgentArgsFailure {
  // One pass so a value containing "{{x}}" stays verbatim.
  const error = EXTRA_AGENT_ARGS_FAILURE_COPY[errorCode].replace(
    /\{\{(\w+)\}\}/g,
    (slot, name: string) => params?.[name] ?? slot
  )
  return { ok: false, error, errorCode, ...(params ? { errorParams: params } : {}) }
}

export type ParsedExtraAgentArgs =
  | { ok: true; tokens: string[]; kinds: ReadonlySet<ExtraAgentArgKind> }
  | ExtraAgentArgsFailure

export type MergedAgentArgs = { ok: true; agentArgs: string } | { ok: false; error: string }

/** Saved extras as the launch sees them; whitespace-only text means none. */
export function hasExtraAgentArgs(value: string | null | undefined): value is string {
  return typeof value === 'string' && value.trim().length > 0
}

function allowedOptionList(options: readonly ExtraAgentArgOption[]): string {
  return [
    ...new Set(
      options.map((option) =>
        option.valuePrefix ? `${option.aliases[0]} ${option.valuePrefix}…` : option.aliases.at(-1)
      )
    )
  ].join(', ')
}

function matchOption(
  tokens: readonly string[],
  options: readonly ExtraAgentArgOption[]
): { option: ExtraAgentArgOption; value?: string; consumed: number } | null {
  for (const option of options) {
    const occurrence = findOptionOccurrence(tokens, option.aliases, false)
    if (occurrence?.index === 0) {
      return { option, value: occurrence.value, consumed: occurrence.consumed }
    }
  }
  return null
}

function optionName(token: string): string {
  const equals = token.indexOf('=')
  return equals > 0 ? token.slice(0, equals) : token
}

/** Saved extras use one quoting grammar, independent of the client and execution host. */
export function parseExtraAgentArgs(args: {
  agent: TuiAgent
  extraAgentArgs: string
}): ParsedExtraAgentArgs {
  const options = EXTRA_AGENT_ARG_OPTIONS[args.agent]
  if (!options) {
    return extraAgentArgsFailure('unsupportedAgent')
  }
  if (new TextEncoder().encode(args.extraAgentArgs).length > EXTRA_AGENT_ARGS_MAX_BYTES) {
    return extraAgentArgsFailure('tooLarge')
  }
  if (hasControlCharacter(args.extraAgentArgs)) {
    return extraAgentArgsFailure('controlCharacters')
  }
  const text = args.extraAgentArgs.trim()
  const tokenized = tokenizeStartupCommand(text, 'posix')
  if (!tokenized.ok) {
    return extraAgentArgsFailure('invalid', { detail: tokenized.error })
  }
  // Reject command syntax instead of silently turning it into literal argument text.
  const divergent = tokenized.spans.find((span) => span.divergesFromShell)
  if (divergent) {
    return extraAgentArgsFailure('shellSyntax', {
      text: text.slice(divergent.start, divergent.end)
    })
  }
  const label = TUI_AGENT_DISPLAY_NAMES[args.agent]
  const allowed = allowedOptionList(options)
  const kinds = new Set<ExtraAgentArgKind>()
  const { tokens } = tokenized
  for (let index = 0; index < tokens.length; index += 1) {
    const token = tokens[index]
    if (token === '--') {
      return extraAgentArgsFailure('terminator')
    }
    if (!token.startsWith('-')) {
      return extraAgentArgsFailure('notAnOption', { token, agent: label, allowed })
    }
    const match = matchOption(tokens.slice(index, index + 2), options)
    if (!match) {
      return extraAgentArgsFailure('optionNotAllowed', {
        option: optionName(token),
        agent: label,
        allowed
      })
    }
    const name = optionName(token)
    const { value } = match
    if (!value) {
      return extraAgentArgsFailure('missingValue', { option: name })
    }
    const { kind, valuePrefix } = match.option
    if (valuePrefix && (!value.startsWith(valuePrefix) || value.length === valuePrefix.length)) {
      return extraAgentArgsFailure('valueNotAllowed', {
        option: name,
        value,
        agent: label,
        prefix: valuePrefix
      })
    }
    if (kind !== 'repeatable' && kinds.has(kind)) {
      return extraAgentArgsFailure(kind === 'model' ? 'modelRepeated' : 'effortRepeated')
    }
    kinds.add(kind)
    index += match.consumed - 1
  }
  return { ok: true, tokens, kinds }
}

function removeDefaultsFor(
  agent: TuiAgent,
  kinds: ReadonlySet<ExtraAgentArgKind>,
  tokens: readonly string[]
): string[] {
  const catalog = getAgentSessionOptionLaunchCatalog(agent)
  let result = [...tokens]
  if (!catalog) {
    return result
  }
  if (kinds.has('model')) {
    result = catalog.modelApply.removeAgentArgs?.(result) ?? result
  }
  if (kinds.has('effort')) {
    const effort = [
      ...(catalog.unknownModelOptions ?? []),
      ...catalog.models.flatMap((model) => model.options)
    ].find((option) => option.id === 'effort' && option.apply.removeAgentArgs)
    result = effort?.apply.removeAgentArgs?.(result) ?? result
  }
  return result
}

/** Remove defaults overridden by saved extras before appending them to one launch Arguments string. */
export function mergeExtraAgentArgs(args: {
  agent: TuiAgent
  defaultArgs: string | null | undefined
  extraAgentArgs: string | undefined
  shell: AgentStartupShell
}): MergedAgentArgs {
  const defaultArgs = args.defaultArgs ?? ''
  if (!hasExtraAgentArgs(args.extraAgentArgs)) {
    return { ok: true, agentArgs: defaultArgs }
  }
  const extras = parseExtraAgentArgs({
    agent: args.agent,
    extraAgentArgs: args.extraAgentArgs
  })
  if (!extras.ok) {
    return extras
  }
  const defaults = defaultArgs.trim()
    ? tokenizeStartupCommand(defaultArgs.trim(), args.shell)
    : { ok: true as const, tokens: [] }
  if (!defaults.ok) {
    return { ok: false, error: `Default agent arguments are invalid: ${defaults.error}` }
  }
  const kept = removeDefaultsFor(args.agent, extras.kinds, defaults.tokens)
  const terminator = agentArgTerminatorIndex(args.agent, kept)
  const merged = [...kept.slice(0, terminator), ...extras.tokens, ...kept.slice(terminator)]
  const agentArgs = merged.map((token) => quoteStartupArg(token, args.shell)).join(' ')
  // Why: the launch re-tokenizes this string; refuse rather than launch different argv.
  const reparsed = tokenizeStartupCommand(agentArgs, args.shell)
  if (
    !reparsed.ok ||
    reparsed.tokens.length !== merged.length ||
    reparsed.tokens.some((token, index) => token !== merged[index])
  ) {
    return {
      ok: false,
      error: "This host's default agent arguments can't be combined with extra arguments."
    }
  }
  return { ok: true, agentArgs }
}