better-codex 0.1.0

package/apps/web/src/utils/account-refresh.ts

@@ -0,0 +1,168 @@
+import type { Account, AccountStatus, AccountUsage, ModelInfo } from '../types'
+import { hubClient } from '../services/hub-client'
+
+export type AccountReadResult = {
+  account?: {
+    type: string
+    email?: string
+    planType?: string
+  } | null
+  requiresOpenaiAuth?: boolean
+}
+
+type RateLimitWindowRaw = {
+  used_percent?: number
+  usedPercent?: number
+  window_minutes?: number | null
+  windowDurationMins?: number | null
+  resets_at?: number | null
+  resetsAt?: number | null
+}
+
+type CreditsSnapshotRaw = {
+  has_credits?: boolean
+  hasCredits?: boolean
+  unlimited?: boolean
+  balance?: string | null
+}
+
+export type RateLimitResult = {
+  rateLimits?: {
+    primary?: RateLimitWindowRaw | null
+    secondary?: RateLimitWindowRaw | null
+    credits?: CreditsSnapshotRaw | null
+    plan_type?: string | null
+    planType?: string | null
+  } | null
+}
+
+type ModelListResult = {
+  data?: ModelInfo[]
+  nextCursor?: string | null
+}
+
+const readNumber = (...values: Array<number | null | undefined>) => {
+  for (const value of values) {
+    if (typeof value === 'number') {
+      return value
+    }
+  }
+  return 0
+}
+
+const readNumberOrNull = (...values: Array<number | null | undefined>) => {
+  for (const value of values) {
+    if (typeof value === 'number') {
+      return value
+    }
+  }
+  return null
+}
+
+export const parseUsage = (result: RateLimitResult): AccountUsage | undefined => {
+  const limits = result.rateLimits
+  if (!limits) return undefined
+  return {
+    primary: limits.primary ? {
+      usedPercent: readNumber(limits.primary.usedPercent, limits.primary.used_percent),
+      windowMinutes: readNumberOrNull(
+        limits.primary.windowDurationMins,
+        limits.primary.window_minutes
+      ),
+      resetsAt: readNumberOrNull(limits.primary.resetsAt, limits.primary.resets_at),
+    } : null,
+    secondary: limits.secondary ? {
+      usedPercent: readNumber(limits.secondary.usedPercent, limits.secondary.used_percent),
+      windowMinutes: readNumberOrNull(
+        limits.secondary.windowDurationMins,
+        limits.secondary.window_minutes
+      ),
+      resetsAt: readNumberOrNull(limits.secondary.resetsAt, limits.secondary.resets_at),
+    } : null,
+    credits: limits.credits ? {
+      hasCredits: limits.credits.hasCredits ?? limits.credits.has_credits ?? false,
+      unlimited: limits.credits.unlimited ?? false,
+      balance: limits.credits.balance ?? null,
+    } : null,
+    planType: limits.planType ?? limits.plan_type ?? null,
+  }
+}
+
+export const accountStatusFromRead = (result: AccountReadResult): AccountStatus => {
+  if (!result.account) {
+    return result.requiresOpenaiAuth ? 'offline' : 'online'
+  }
+  return 'online'
+}
+
+export const fetchAllModels = async (profileId: string): Promise<ModelInfo[]> => {
+  const models: ModelInfo[] = []
+  let cursor: string | null = null
+  for (let page = 0; page < 10; page += 1) {
+    let result: ModelListResult | null = null
+    try {
+      result = (await hubClient.request(profileId, 'model/list', {
+        limit: 100,
+        cursor,
+      })) as ModelListResult
+    } catch {
+      return models
+    }
+    if (!result?.data?.length) {
+      break
+    }
+    models.push(...result.data)
+    if (!result.nextCursor || result.nextCursor === cursor) {
+      break
+    }
+    cursor = result.nextCursor
+  }
+  return models
+}
+
+export const refreshAccountSnapshot = async (
+  profileId: string,
+  updateAccount: (id: string, updater: (account: Account) => Account) => void,
+  setModelsForAccount: (id: string, models: ModelInfo[]) => void
+): Promise<void> => {
+  let accountResult: AccountReadResult | null = null
+  try {
+    accountResult = (await hubClient.request(profileId, 'account/read', {
+      refreshToken: false,
+    })) as AccountReadResult
+  } catch {
+    accountResult = null
+  }
+  if (accountResult) {
+    updateAccount(profileId, (prev) => ({
+      ...prev,
+      status: accountStatusFromRead(accountResult),
+      email: accountResult.account?.email ?? prev.email,
+      plan: accountResult.account?.planType ?? prev.plan,
+    }))
+  }
+
+  try {
+    const limits = (await hubClient.request(profileId, 'account/rateLimits/read')) as RateLimitResult
+    if (limits) {
+      const usage = parseUsage(limits)
+      const rate = usage?.primary?.usedPercent
+      updateAccount(profileId, (prev) => ({
+        ...prev,
+        rateLimit: typeof rate === 'number' ? Math.round(rate) : prev.rateLimit,
+        usage: usage ?? prev.usage,
+      }))
+    }
+  } catch {
+    // Ignore rate limit errors for unauthenticated accounts.
+  }
+
+  try {
+    const models = await fetchAllModels(profileId)
+    if (models.length) {
+      setModelsForAccount(profileId, models)
+    }
+  } catch {
+    // Ignore model errors for unauthenticated accounts.
+  }
+}

package/apps/web/src/utils/approval-policy.ts

@@ -0,0 +1,53 @@
+import type { ApprovalPolicy } from '../types'
+
+const APPROVAL_POLICY_ALIASES: Record<string, ApprovalPolicy> = {
+  untrusted: 'untrusted',
+  unlessTrusted: 'untrusted',
+  'unless-trusted': 'untrusted',
+  'unless_trusted': 'untrusted',
+  'on-request': 'on-request',
+  onRequest: 'on-request',
+  on_request: 'on-request',
+  'on-failure': 'on-failure',
+  onFailure: 'on-failure',
+  on_failure: 'on-failure',
+  never: 'never',
+}
+
+export const normalizeApprovalPolicy = (value?: string | null): ApprovalPolicy | null => {
+  if (!value) {
+    return null
+  }
+  const normalized = APPROVAL_POLICY_ALIASES[value]
+  if (normalized) {
+    return normalized
+  }
+  const lower = value.toLowerCase()
+  return APPROVAL_POLICY_ALIASES[lower] ?? null
+}
+
+export const approvalPolicyLabel = (value: ApprovalPolicy): string => {
+  switch (value) {
+    case 'untrusted':
+      return 'Untrusted'
+    case 'on-failure':
+      return 'On failure'
+    case 'on-request':
+      return 'On request'
+    case 'never':
+      return 'Never'
+  }
+}
+
+export const approvalPolicyDescription = (value: ApprovalPolicy): string => {
+  switch (value) {
+    case 'untrusted':
+      return 'Always ask before running commands or edits.'
+    case 'on-failure':
+      return 'Run in sandbox; ask if it fails.'
+    case 'on-request':
+      return 'Ask before risky commands; auto-run safe reads.'
+    case 'never':
+      return 'Run without approvals.'
+  }
+}

package/apps/web/src/utils/init-prompt.ts

@@ -0,0 +1,41 @@
+export const INIT_PROMPT = `Generate a file named AGENTS.md that serves as a contributor guide for this repository.
+Your goal is to produce a clear, concise, and well-structured document with descriptive headings and actionable explanations for each section.
+Follow the outline below, but adapt as needed -- add sections if relevant, and omit those that do not apply to this project.
+
+Document Requirements
+
+- Title the document "Repository Guidelines".
+- Use Markdown headings (#, ##, etc.) for structure.
+- Keep the document concise. 200-400 words is optimal.
+- Keep explanations short, direct, and specific to this repository.
+- Provide examples where helpful (commands, directory paths, naming patterns).
+- Maintain a professional, instructional tone.
+
+Recommended Sections
+
+Project Structure & Module Organization
+
+- Outline the project structure, including where the source code, tests, and assets are located.
+
+Build, Test, and Development Commands
+
+- List key commands for building, testing, and running locally (e.g., npm test, make build).
+- Briefly explain what each command does.
+
+Coding Style & Naming Conventions
+
+- Specify indentation rules, language-specific style preferences, and naming patterns.
+- Include any formatting or linting tools used.
+
+Testing Guidelines
+
+- Identify testing frameworks and coverage requirements.
+- State test naming conventions and how to run tests.
+
+Commit & Pull Request Guidelines
+
+- Summarize commit message conventions found in the project's Git history.
+- Outline pull request requirements (descriptions, linked issues, screenshots, etc.).
+
+(Optional) Add other sections if relevant, such as Security & Configuration Tips, Architecture Overview, or Agent-Specific Instructions.
+`

package/apps/web/src/utils/item-format.ts

@@ -0,0 +1,170 @@
+import type { Message, MessageKind } from '../types'
+
+type ThreadItem = {
+  type: string
+  id: string
+  [key: string]: unknown
+}
+
+type CommandAction =
+  | { type: 'read'; command: string; name: string; path: string }
+  | { type: 'listFiles'; command: string; path?: string | null }
+  | { type: 'search'; command: string; query?: string | null; path?: string | null }
+  | { type: 'unknown'; command: string }
+
+const clampText = (value: string, max = 1400) => {
+  if (value.length <= max) {
+    return value
+  }
+  return `${value.slice(0, max)}\n…`
+}
+
+const safeStringify = (value: unknown) => {
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+const formatFileChanges = (changes: Array<{ path?: unknown; kind?: unknown; diff?: string; movePath?: unknown }>) => {
+  const summary = changes
+    .map((change) => {
+      const path =
+        typeof change.path === 'string'
+          ? change.path
+          : change.path
+            ? safeStringify(change.path)
+            : 'unknown'
+      const kind = typeof change.kind === 'string' ? change.kind : 'update'
+      const movePath =
+        typeof change.movePath === 'string'
+          ? ` -> ${change.movePath}`
+          : change.movePath
+            ? ` -> ${safeStringify(change.movePath)}`
+            : ''
+      return `${kind}: ${path}${movePath}`
+    })
+    .join('\n')
+
+  const diffPreview = changes
+    .map((change) => change.diff ?? '')
+    .filter(Boolean)
+    .join('\n\n')
+
+  const content = [summary, diffPreview].filter(Boolean).join('\n\n')
+  return clampText(content)
+}
+
+const formatCommandActions = (actions: CommandAction[], commandFallback: string) => {
+  if (!actions.length) {
+    return {
+      kind: 'command' as MessageKind,
+      title: 'Command',
+      content: commandFallback,
+    }
+  }
+
+  const primary = actions.find((action) => action.type !== 'unknown') ?? actions[0]
+  switch (primary.type) {
+    case 'read': {
+      const detail = primary.path ? `${primary.name} · ${primary.path}` : primary.name
+      return {
+        kind: 'tool' as MessageKind,
+        title: 'Read',
+        content: detail || commandFallback,
+      }
+    }
+    case 'search': {
+      const detail = [primary.query, primary.path].filter(Boolean).join(' · ')
+      return {
+        kind: 'tool' as MessageKind,
+        title: 'Search',
+        content: detail || commandFallback,
+      }
+    }
+    case 'listFiles': {
+      return {
+        kind: 'tool' as MessageKind,
+        title: 'List',
+        content: primary.path || commandFallback,
+      }
+    }
+    default:
+      return {
+        kind: 'command' as MessageKind,
+        title: 'Command',
+        content: commandFallback,
+      }
+  }
+}
+
+export const formatThreadItem = (item: ThreadItem): { kind: MessageKind; content: string; title?: string } | null => {
+  switch (item.type) {
+    case 'reasoning': {
+      const summary = Array.isArray(item.summary) ? item.summary.join('\n') : ''
+      const content = summary
+      return { kind: 'reasoning', content: clampText(content), title: 'Reasoning' }
+    }
+    case 'commandExecution': {
+      const command = typeof item.command === 'string' ? item.command : 'Command'
+      const output = typeof item.aggregatedOutput === 'string' ? item.aggregatedOutput : ''
+      const status = typeof item.status === 'string' ? item.status : 'inProgress'
+      const actions = Array.isArray(item.commandActions) ? (item.commandActions as CommandAction[]) : []
+      const actionSummary = formatCommandActions(actions, command)
+      const content = output ? `${actionSummary.content}\n\n${output}` : actionSummary.content
+      return { kind: actionSummary.kind, content: clampText(content), title: `${actionSummary.title} · ${status}` }
+    }
+    case 'fileChange': {
+      const changes = Array.isArray(item.changes) ? item.changes : []
+      const content = formatFileChanges(changes as Array<{ path?: string; kind?: string; diff?: string; movePath?: string }>)
+      const status = typeof item.status === 'string' ? item.status : 'inProgress'
+      return { kind: 'file', content, title: `Files · ${status}` }
+    }
+    case 'mcpToolCall': {
+      const server = typeof item.server === 'string' ? item.server : 'mcp'
+      const tool = typeof item.tool === 'string' ? item.tool : 'tool'
+      const args = item.arguments ? safeStringify(item.arguments) : ''
+      const result = item.result ? safeStringify(item.result) : ''
+      const error = item.error ? safeStringify(item.error) : ''
+      const content = [args, result, error].filter(Boolean).join('\n\n')
+      return { kind: 'tool', content: clampText(content || `${server}.${tool}`), title: `${server}.${tool}` }
+    }
+    case 'webSearch': {
+      const query = typeof item.query === 'string' ? item.query : 'Search'
+      return { kind: 'tool', content: clampText(query), title: 'Web Search' }
+    }
+    case 'imageView': {
+      const path = typeof item.path === 'string' ? item.path : 'Image'
+      return { kind: 'tool', content: clampText(path), title: 'Image View' }
+    }
+    case 'enteredReviewMode': {
+      const review = typeof item.review === 'string' ? item.review : 'Review'
+      return { kind: 'tool', content: clampText(review), title: 'Review Started' }
+    }
+    case 'exitedReviewMode': {
+      const review = typeof item.review === 'string' ? item.review : 'Review'
+      return { kind: 'tool', content: clampText(review, 2400), title: 'Review' }
+    }
+    case 'compacted': {
+      return { kind: 'tool', content: 'Conversation compacted to save context.', title: 'Compaction' }
+    }
+    default:
+      return null
+  }
+}
+
+export const buildSystemMessage = (item: ThreadItem): Message | null => {
+  const formatted = formatThreadItem(item)
+  if (!formatted) {
+    return null
+  }
+  return {
+    id: item.id,
+    role: 'assistant',
+    kind: formatted.kind,
+    title: formatted.title,
+    content: formatted.content,
+    timestamp: '',
+  }
+}

package/apps/web/src/utils/prompt-expander.ts

@@ -0,0 +1,62 @@
+type ParsedArgs = {
+  positional: string[]
+  named: Record<string, string>
+}
+
+const tokenizeArgs = (input: string): string[] => {
+  if (!input.trim()) {
+    return []
+  }
+  const tokens: string[] = []
+  const regex = /"([^"]*)"|'([^']*)'|([^\s]+)/g
+  let match: RegExpExecArray | null
+  while ((match = regex.exec(input)) !== null) {
+    tokens.push(match[1] ?? match[2] ?? match[3] ?? '')
+  }
+  return tokens
+}
+
+const parseArgs = (input: string): ParsedArgs => {
+  const tokens = tokenizeArgs(input)
+  const positional: string[] = []
+  const named: Record<string, string> = {}
+
+  tokens.forEach((token) => {
+    const eqIndex = token.indexOf('=')
+    if (eqIndex > 0) {
+      const key = token.slice(0, eqIndex)
+      const value = token.slice(eqIndex + 1)
+      named[key] = value
+    } else {
+      positional.push(token)
+    }
+  })
+
+  return { positional, named }
+}
+
+export const stripPromptFrontmatter = (input: string): string => {
+  const trimmed = input.trimStart()
+  if (!trimmed.startsWith('---')) {
+    return input
+  }
+  const end = trimmed.indexOf('\n---', 3)
+  if (end === -1) {
+    return input
+  }
+  const after = trimmed.slice(end + 4)
+  return after.startsWith('\n') ? after.slice(1) : after
+}
+
+export const expandPromptTemplate = (template: string, args: string): string => {
+  const { positional, named } = parseArgs(args)
+  const placeholder = '__CODEX_DOLLAR__'
+  let output = template.replace(/\$\$/g, placeholder)
+
+  output = output.replace(/\$ARGUMENTS/g, positional.join(' '))
+  output = output.replace(/\$(\d)/g, (_, digit) => positional[Number(digit) - 1] ?? '')
+  output = output.replace(/\$([A-Z][A-Z0-9_]*)/g, (_, key) => named[key] ?? '')
+
+  output = output.replace(new RegExp(placeholder, 'g'), '$')
+  return output
+}

package/apps/web/src/utils/reasoning-summary.ts

@@ -0,0 +1,48 @@
+import type { ReasoningSummary } from '../types'
+
+const SUMMARY_ALIASES: Record<string, ReasoningSummary> = {
+  auto: 'auto',
+  concise: 'concise',
+  detailed: 'detailed',
+  none: 'none',
+  off: 'none',
+  disable: 'none',
+}
+
+export const normalizeReasoningSummary = (value?: string | null): ReasoningSummary | null => {
+  if (!value) {
+    return null
+  }
+  const normalized = SUMMARY_ALIASES[value]
+  if (normalized) {
+    return normalized
+  }
+  const lower = value.toLowerCase()
+  return SUMMARY_ALIASES[lower] ?? null
+}
+
+export const reasoningSummaryLabel = (value: ReasoningSummary): string => {
+  switch (value) {
+    case 'auto':
+      return 'Auto'
+    case 'concise':
+      return 'Concise'
+    case 'detailed':
+      return 'Detailed'
+    case 'none':
+      return 'None'
+  }
+}
+
+export const reasoningSummaryDescription = (value: ReasoningSummary): string => {
+  switch (value) {
+    case 'auto':
+      return 'Let the model choose the best summary length.'
+    case 'concise':
+      return 'Short, readable reasoning summaries.'
+    case 'detailed':
+      return 'Longer reasoning summaries with extra detail.'
+    case 'none':
+      return 'Disable reasoning summaries.'
+  }
+}

package/apps/web/src/utils/slash-commands.ts

@@ -0,0 +1,98 @@
+export type SlashCommandId =
+  | 'model'
+  | 'summary'
+  | 'cwd'
+  | 'approvals'
+  | 'skills'
+  | 'review'
+  | 'new'
+  | 'resume'
+  | 'init'
+  | 'compact'
+  | 'diff'
+  | 'mention'
+  | 'status'
+  | 'mcp'
+  | 'experimental'
+  | 'logout'
+  | 'quit'
+  | 'exit'
+  | 'feedback'
+  | `prompts:${string}`
+
+export type SlashCommandDefinition = {
+  id: SlashCommandId
+  description: string
+  availableDuringTask: boolean
+}
+
+export const SLASH_COMMANDS: SlashCommandDefinition[] = [
+  { id: 'model', description: 'choose what model and reasoning effort to use', availableDuringTask: false },
+  { id: 'summary', description: 'set reasoning summary length', availableDuringTask: false },
+  { id: 'cwd', description: 'set working directory for the thread', availableDuringTask: false },
+  { id: 'approvals', description: 'choose what Codex can do without approval', availableDuringTask: false },
+  { id: 'skills', description: 'browse and insert skills', availableDuringTask: true },
+  { id: 'review', description: 'review my current changes and find issues', availableDuringTask: false },
+  { id: 'new', description: 'start a new chat during a conversation', availableDuringTask: false },
+  { id: 'resume', description: 'resume a saved chat', availableDuringTask: false },
+  { id: 'init', description: 'create an AGENTS.md file with instructions for Codex', availableDuringTask: false },
+  { id: 'compact', description: 'summarize conversation to prevent hitting the context limit', availableDuringTask: false },
+  { id: 'diff', description: 'show git diff (including untracked files)', availableDuringTask: true },
+  { id: 'mention', description: 'mention a file', availableDuringTask: true },
+  { id: 'status', description: 'show current session configuration and token usage', availableDuringTask: true },
+  { id: 'mcp', description: 'list configured MCP tools', availableDuringTask: true },
+  { id: 'experimental', description: 'open experimental menu', availableDuringTask: true },
+  { id: 'logout', description: 'log out of Codex', availableDuringTask: false },
+  { id: 'quit', description: 'exit Codex', availableDuringTask: true },
+  { id: 'exit', description: 'exit Codex', availableDuringTask: true },
+  { id: 'feedback', description: 'send logs to maintainers', availableDuringTask: true },
+]
+
+export const filterSlashCommands = (query: string, extra: SlashCommandDefinition[] = []) => {
+  const allCommands = [...SLASH_COMMANDS, ...extra]
+  if (!query) {
+    return allCommands
+  }
+  const lowered = query.toLowerCase()
+  return allCommands.filter((command) => command.id.startsWith(lowered))
+}
+
+export const findSlashCommand = (name: string, extra: SlashCommandDefinition[] = []) =>
+  [...SLASH_COMMANDS, ...extra].find((command) => command.id === name)
+
+export const getSlashQuery = (text: string): string | null => {
+  const firstLine = text.split('\n')[0] ?? ''
+  if (!firstLine.startsWith('/')) {
+    return null
+  }
+  if (firstLine.startsWith('/ ') || firstLine.startsWith('/\t')) {
+    return null
+  }
+  const raw = firstLine.slice(1)
+  const token = raw.split(/\s/)[0]
+  return token
+}
+
+export const parseSlashInput = (text: string): { name: string; rest: string } | null => {
+  const firstLine = text.split('\n')[0] ?? ''
+  if (!firstLine.startsWith('/')) {
+    return null
+  }
+  if (firstLine.startsWith('/ ') || firstLine.startsWith('/\t')) {
+    return null
+  }
+  const raw = firstLine.slice(1)
+  if (!raw) {
+    return { name: '', rest: '' }
+  }
+  const match = raw.match(/^([^\s]+)\s*(.*)$/)
+  if (!match) {
+    return null
+  }
+  const name = match[1]
+  const rest = match[2] ?? ''
+  if (!name || name.includes('/')) {
+    return null
+  }
+  return { name, rest: rest.trim() }
+}

package/apps/web/tsconfig.app.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/apps/web/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}