codex-configurator 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "codex-configurator",
+  "version": "0.1.0",
+  "description": "TOML-aware Ink TUI for Codex Configurator",
+  "main": "index.js",
+  "type": "module",
+  "keywords": [
+    "tui",
+    "terminal",
+    "cli",
+    "react",
+    "ink",
+    "node",
+    "configurator"
+  ],
+  "author": "Codex Configurator",
+  "license": "MIT",
+  "bin": {
+    "codex-configurator": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node index.js",
+    "lint": "node --check index.js && node --check src/configHelp.js src/configParser.js src/constants.js src/interaction.js src/layout.js src/components/Header.js src/components/ConfigNavigator.js",
+    "build": "node --check index.js && node --check src/configHelp.js src/configParser.js src/constants.js src/interaction.js src/layout.js src/components/Header.js src/components/ConfigNavigator.js",
+    "test": "npm run lint",
+    "prepack": "npm run test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "src"
+  ],
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "ink": "^6.2.1",
+    "react": "^19.0.0",
+    "toml": "^3.0.0"
+  }
+}

package/src/components/ConfigNavigator.js

@@ -0,0 +1,387 @@
+import React from 'react';
+import { Text, Box } from 'ink';
+import {
+  getConfigHelp,
+  getConfigOptions,
+  getConfigOptionExplanation,
+  getConfigDefaultOption,
+} from '../configHelp.js';
+import { computePaneWidths, clamp } from '../layout.js';
+import { getNodeAtPath, buildRows, formatDetails } from '../configParser.js';
+
+const MenuItem = ({ isSelected, isDimmed, isDeprecated, label }) =>
+  React.createElement(
+    Text,
+    {
+      bold: isSelected,
+      color: isSelected ? 'yellow' : isDimmed ? 'gray' : 'white',
+      dimColor: !isSelected && isDimmed,
+    },
+    label,
+    isDeprecated ? React.createElement(Text, { color: 'yellow' }, ' [!]') : null
+  );
+
+const formatArrayItem = (value) => {
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.length} item(s)]`;
+  }
+
+  if (Object.prototype.toString.call(value) === '[object Object]') {
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return '{}';
+    }
+
+    return `{${keys.join(', ')}}`;
+  }
+
+  return String(value);
+};
+
+const formatOptionValue = (value) => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (typeof value === 'boolean' || value === null) {
+    return String(value);
+  }
+
+  return String(value);
+};
+
+const truncate = (text, maxLength) =>
+  text.length <= maxLength ? text : `${text.slice(0, Math.max(0, maxLength - 1))}…`;
+
+const isBooleanOnlyOptions = (options) =>
+  Array.isArray(options) &&
+  options.length === 2 &&
+  options.every((option) => typeof option === 'boolean') &&
+  options.includes(false) &&
+  options.includes(true);
+
+const renderArrayDetails = (rows) => {
+  const items = rows.slice(0, 5).map((item, index) =>
+    React.createElement(Text, { key: `array-item-${index}` }, `  ${index + 1}. ${formatArrayItem(item)}`)
+  );
+  const overflow = rows.length - items.length;
+
+  return React.createElement(
+    React.Fragment,
+    null,
+    ...items,
+    overflow > 0 ? React.createElement(Text, { key: 'array-more' }, `  … and ${overflow} more`) : null
+  );
+};
+
+const renderTextEditor = (draftValue) =>
+  React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(Text, { color: 'white' }, `> ${draftValue}`),
+    React.createElement(Text, { color: 'gray' }, 'Type to edit • Enter: save • Esc: cancel')
+  );
+
+const renderIdEditor = (placeholder, draftValue) =>
+  React.createElement(
+    React.Fragment,
+    null,
+    React.createElement(Text, { color: 'white' }, `${placeholder || 'id'}: ${draftValue}`),
+    React.createElement(Text, { color: 'gray' }, 'Type id • Enter: create • Esc: cancel')
+  );
+
+const renderEditableOptions = (
+  options,
+  selectedOptionIndex,
+  defaultOptionIndex,
+  optionPathSegments,
+  rowKey,
+  savedOptionIndex = null,
+  showCursor = false
+) => {
+  const optionRows = options.map((option, optionIndex) => {
+    const optionValueText = formatOptionValue(option);
+    const prefix = showCursor && optionIndex === selectedOptionIndex ? '▶ ' : '  ';
+    const valueText = `${prefix}${optionValueText}`;
+    const explanation = getConfigOptionExplanation(optionPathSegments, rowKey, option);
+    const isDefault = optionIndex === defaultOptionIndex;
+    const highlightDefault = selectedOptionIndex < 0 && isDefault;
+    return { optionIndex, valueText, explanation, optionValueText, isDefault, highlightDefault };
+  });
+
+  const valueWidth = optionRows.reduce((max, item) => Math.max(max, item.valueText.length), 0);
+
+  return React.createElement(
+    React.Fragment,
+    null,
+    ...optionRows.map(
+      ({ optionIndex, valueText, explanation, optionValueText, isDefault, highlightDefault }) =>
+      React.createElement(
+        Box,
+        {
+          key: `option-${rowKey}-${optionIndex}`,
+          flexDirection: 'column',
+        },
+        React.createElement(
+          Box,
+          {
+            flexDirection: 'row',
+          },
+          React.createElement(
+            Text,
+            {
+              color: optionIndex === selectedOptionIndex
+                ? 'yellow'
+                : highlightDefault
+                  ? 'whiteBright'
+                  : 'white',
+              bold: optionIndex === selectedOptionIndex || highlightDefault,
+            },
+            `${valueText.padEnd(valueWidth, ' ')}`
+          ),
+          explanation
+            ? React.createElement(Text, { color: 'gray' }, `  — ${truncate(explanation, 100)}`)
+            : null,
+          isDefault
+            ? React.createElement(Text, { color: 'cyan' }, '  [default]')
+            : null
+        ),
+        savedOptionIndex === optionIndex
+          ? React.createElement(Text, { color: 'green' }, `  Saved: ${optionValueText}`)
+          : null
+      )
+    )
+  );
+};
+
+const formatConfigHelp = (pathSegments, row) => {
+  if (row?.kind === 'action' && row?.action === 'add-custom-id') {
+    return [
+      {
+        text: `Create a new custom "${row.placeholder || 'id'}" entry in this section.`,
+        color: 'white',
+        bold: false,
+        showWarningIcon: false,
+      },
+      {
+        text: 'Press Enter to type the id, then Enter again to save.',
+        color: 'gray',
+        bold: false,
+        showWarningIcon: false,
+      },
+    ];
+  }
+
+  const info = getConfigHelp(pathSegments, row.key);
+  const defaultCollectionText =
+    row.kind === 'table' || row.kind === 'tableArray'
+      ? 'This section groups related settings.'
+      : row.kind === 'array'
+        ? `This is a list with ${row.value.length} entries.`
+        : 'This setting affects Codex behavior.';
+  const short = info?.short || defaultCollectionText;
+  const usage = info?.usage;
+  const isWarning = Boolean(info?.deprecation);
+  const lines = [{ text: short, color: 'white', bold: false, showWarningIcon: false }];
+
+  if (usage) {
+    lines.push({
+      text: isWarning ? usage.replace(/^\[!\]\s*/, '') : usage,
+      color: 'gray',
+      bold: false,
+      showWarningIcon: isWarning,
+    });
+  }
+
+  if (row?.key === 'approval_policy' && row?.value === 'on-failure') {
+    lines.push({
+      text: 'approval_policy = "on-failure" is deprecated; use "untrusted", "on-request", or "never".',
+      color: 'gray',
+      bold: false,
+      showWarningIcon: true,
+    });
+  }
+
+  if (pathSegments?.[pathSegments.length - 1] === 'features' && row?.isDocumented === false) {
+    lines.push({
+      text: 'This key is configured in your file but is not in the official feature list.',
+      color: 'gray',
+      bold: false,
+      showWarningIcon: true,
+    });
+  }
+
+  if (pathSegments.length === 0 && row?.key === 'model') {
+    lines.push({
+      text: 'Model values shown here are curated presets and not a full upstream model catalog.',
+      color: 'gray',
+      bold: false,
+      showWarningIcon: false,
+    });
+  }
+
+  return lines;
+};
+
+export const ConfigNavigator = ({
+  snapshot,
+  pathSegments,
+  selectedIndex,
+  scrollOffset,
+  terminalWidth,
+  terminalHeight,
+  editMode,
+  editError,
+}) => {
+  if (!snapshot.ok) {
+    return React.createElement(
+      Box,
+      { flexDirection: 'column', marginTop: 1 },
+      React.createElement(Text, { color: 'red', bold: true }, 'Unable to read/parse config'),
+      React.createElement(Text, { color: 'gray' }, snapshot.error),
+      React.createElement(Text, { color: 'gray' }, `Path: ${snapshot.path}`)
+    );
+  }
+
+  const currentNode = getNodeAtPath(snapshot.data, pathSegments);
+  const rows = buildRows(currentNode, pathSegments);
+  const selected = rows.length === 0 ? 0 : Math.min(selectedIndex, rows.length - 1);
+  const { leftWidth, rightWidth } = computePaneWidths(terminalWidth, rows);
+  const terminalListHeight = Math.max(4, (terminalHeight || 24) - 14);
+  const viewportHeight = Math.max(4, Math.min(rows.length, Math.min(20, terminalListHeight)));
+  const viewportStart = clamp(scrollOffset, 0, Math.max(0, rows.length - viewportHeight));
+  const visibleRows = rows.slice(viewportStart, viewportStart + viewportHeight);
+  const canScrollUp = viewportStart > 0;
+  const canScrollDown = viewportStart + viewportHeight < rows.length;
+  const selectedRow = rows[selected] || null;
+  const selectedPath =
+    selectedRow && selectedRow.pathSegment != null
+      ? [...pathSegments, selectedRow.pathSegment]
+      : pathSegments;
+  const readOnlyOptions =
+    selectedRow && selectedRow.kind === 'value'
+      ? getConfigOptions(selectedPath, selectedRow.key, selectedRow.value, selectedRow.kind) || []
+      : [];
+  const readOnlyOptionIndex = readOnlyOptions.findIndex((option) => Object.is(option, selectedRow?.value));
+  const readOnlyDefaultOption = selectedRow
+    ? getConfigDefaultOption(selectedPath, selectedRow.key, selectedRow.kind, readOnlyOptions)
+    : null;
+  const readOnlyDefaultOptionIndex = readOnlyOptions.findIndex((option) =>
+    Object.is(option, readOnlyDefaultOption)
+  );
+  const shouldShowReadOnlyOptions =
+    readOnlyOptions.length > 0 &&
+    !isBooleanOnlyOptions(readOnlyOptions);
+
+  const editRow = rows[selected] || null;
+  const editDefaultOption = editMode && editMode.mode === 'select' && editRow
+    ? getConfigDefaultOption(editMode.path, editRow.key, 'value', editMode.options)
+    : null;
+  const editDefaultOptionIndex = editMode && editMode.mode === 'select'
+    ? editMode.options.findIndex((option) => Object.is(option, editDefaultOption))
+    : -1;
+
+  return React.createElement(
+    Box,
+    { flexDirection: 'row', gap: 2 },
+    React.createElement(
+      Box,
+      { flexDirection: 'column', width: leftWidth },
+      React.createElement(
+        Box,
+        {
+          flexDirection: 'column',
+          borderStyle: 'single',
+          borderColor: 'gray',
+          padding: 1,
+        },
+        rows.length === 0
+          ? React.createElement(Text, { color: 'gray' }, '[no entries in this table]')
+          : visibleRows.map((row, viewIndex) => {
+              const index = viewportStart + viewIndex;
+              const showTopCue = canScrollUp && viewIndex === 0;
+              const showBottomCue = canScrollDown && viewIndex === visibleRows.length - 1;
+              const isSelected = index === selected;
+              const label = `${showTopCue ? '↑ ' : showBottomCue ? '↓ ' : '  '}${isSelected ? '▶' : ' '} ${row.label}`;
+
+              return React.createElement(
+                MenuItem,
+                {
+                  label,
+                  isSelected,
+                  isDimmed: !isSelected && row.isConfigured === false,
+                  isDeprecated: row.isDeprecated,
+                  key: `left-${index}`,
+                }
+              );
+            })
+      )
+    ),
+    React.createElement(
+      Box,
+      { flexDirection: 'column', width: rightWidth, marginTop: 2 },
+      rows.length === 0
+        ? React.createElement(Text, { color: 'gray' }, 'No selection available.')
+        : React.createElement(
+            React.Fragment,
+            null,
+              ...formatConfigHelp(pathSegments, rows[selected]).map((line, lineIndex) =>
+                React.createElement(
+                  Text,
+                  {
+                    key: `help-${selected}-${lineIndex}`,
+                    color: line.color,
+                    bold: line.bold,
+                  },
+                  line.showWarningIcon
+                    ? React.createElement(Text, { color: 'yellow' }, '[!] ')
+                    : null,
+                  line.text
+                )
+              ),
+            editError ? React.createElement(Text, { color: 'red' }, editError) : null,
+            editMode ? React.createElement(Text, { color: 'gray' }, ' ') : null,
+            editMode
+              ? editMode.mode === 'text'
+                ? renderTextEditor(editMode.draftValue)
+                : editMode.mode === 'add-id'
+                  ? renderIdEditor(editMode.placeholder, editMode.draftValue)
+                : renderEditableOptions(
+                    editMode.options,
+                    editMode.selectedOptionIndex,
+                    editDefaultOptionIndex,
+                    editMode.path.slice(0, -1),
+                    rows[selected].key,
+                    editMode.savedOptionIndex,
+                    true
+                  )
+              : shouldShowReadOnlyOptions
+                  ? React.createElement(
+                      React.Fragment,
+                      null,
+                      React.createElement(Text, { color: 'gray' }, ' '),
+                      renderEditableOptions(
+                        readOnlyOptions,
+                        readOnlyOptionIndex,
+                        readOnlyDefaultOptionIndex,
+                        selectedPath,
+                        selectedRow?.key,
+                        null,
+                        false
+                      )
+                    )
+                  : rows[selected].kind === 'array'
+                      ? renderArrayDetails(rows[selected].value)
+                      : null
+          )
+    )
+  );
+};

package/src/components/Header.js

@@ -0,0 +1,33 @@
+import React from 'react';
+import { Text, Box } from 'ink';
+
+const WORDMARK = [
+  ' ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗     ██████╗ ██████╗ ███╗   ██╗███████╗██╗ ██████╗ ██╗   ██╗██████╗  █████╗ ████████╗ ██████╗ ██████╗ ',
+  '██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝    ██╔════╝██╔═══██╗████╗  ██║██╔════╝██║██╔════╝ ██║   ██║██╔══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗',
+  '██║     ██║   ██║██║  ██║█████╗   ╚███╔╝     ██║     ██║   ██║██╔██╗ ██║█████╗  ██║██║  ███╗██║   ██║██████╔╝███████║   ██║   ██║   ██║██████╔╝',
+  '██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗     ██║     ██║   ██║██║╚██╗██║██╔══╝  ██║██║   ██║██║   ██║██╔══██╗██╔══██║   ██║   ██║   ██║██╔══██╗',
+  '╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗    ╚██████╗╚██████╔╝██║ ╚████║██║     ██║╚██████╔╝╚██████╔╝██║  ██║██║  ██║   ██║   ╚██████╔╝██║  ██║',
+  ' ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝     ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝     ╚═╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝',
+];
+
+export const Header = ({ codexVersion, codexVersionStatus }) =>
+  React.createElement(
+    Box,
+    {
+      flexDirection: 'column',
+      paddingX: 1,
+      marginBottom: 1,
+    },
+      React.createElement(
+        Box,
+        { flexDirection: 'column', marginBottom: 1, gap: 0 },
+        ...WORDMARK.map((line) =>
+          React.createElement(Text, { color: 'magentaBright', bold: true, key: `word-${line}` }, line)
+        )
+      ),
+    React.createElement(
+      Text,
+      { color: 'gray' },
+      codexVersionStatus ? `Codex ${codexVersion} (${codexVersionStatus})` : `Codex ${codexVersion}`
+    )
+  );

package/src/configFeatures.js

@@ -0,0 +1,233 @@
+import { getReferenceFeatureKeys } from './configReference.js';
+
+const prettifyFeatureName = (key) =>
+  key
+    .split('_')
+    .map((segment) => `${segment[0]?.toUpperCase() || ''}${segment.slice(1)}`)
+    .join(' ');
+
+const makeFeatureDefinition = (
+  key,
+  short,
+  usage = 'Uses the feature flag value in your config.',
+  options = {}
+) => {
+  const deprecation = options?.deprecation;
+  const defaultValue = typeof options?.defaultValue === 'boolean' ? options.defaultValue : false;
+  const isDocumented = options?.isDocumented === true;
+
+  return {
+    key,
+    short,
+    usage: deprecation ? `[!] ${deprecation}` : usage,
+    deprecation,
+    defaultValue,
+    isDocumented,
+  };
+};
+
+export const CONFIG_FEATURE_DEFINITIONS = [
+  makeFeatureDefinition(
+    'apply_patch_freeform',
+    'Enable freeform apply_patch style for code edits.',
+    'When enabled, patch edits can use larger freeform blocks.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'apps',
+    'Enable built-in app/connector features.',
+    'Toggle access to app integrations used by Codex.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'apps_mcp_gateway',
+    'Use the MCP app gateway.',
+    'Route app calls through the MCP gateway when available.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'child_agents_md',
+    'Allow child-agent markdown workflows.',
+    'Enable loading child-agent instructions from markdown files.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition('codex_git_commit', 'Enable Codex-assisted git commit workflows.', 'Allows additional git-oriented agent workflows.'),
+  makeFeatureDefinition(
+    'collab',
+    'Enable collaboration mode helpers.',
+    'Turn on multi-party collaboration flow features.',
+    { deprecation: 'collab is deprecated; use [features].multi_agent instead.' }
+  ),
+  makeFeatureDefinition(
+    'collaboration_modes',
+    'Enable multiple collaboration modes.',
+    'Allow the assistant to switch between interaction modes.',
+    { defaultValue: true, isDocumented: true }
+  ),
+  makeFeatureDefinition('connectors', 'Enable external connector support.', 'Controls optional third-party connector behavior.'),
+  makeFeatureDefinition(
+    'elevated_windows_sandbox',
+    'Enable elevated Windows sandbox.',
+    'Allows higher-permission sandbox behavior on Windows.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition('enable_experimental_windows_sandbox', 'Enable experimental Windows sandbox.', 'Turns on experimental Windows sandbox behavior.'),
+  makeFeatureDefinition('enable_request_compression', 'Enable request compression.', 'Compress request payloads for matching model endpoints.'),
+  makeFeatureDefinition('experimental_use_freeform_apply_patch', 'Enable experimental freeform apply_patch usage.', 'Allows experimental patching behavior in edit flows.'),
+  makeFeatureDefinition('experimental_use_unified_exec_tool', 'Enable experimental unified exec tool.', 'Use unified execution routing when invoking shell tools.'),
+  makeFeatureDefinition(
+    'experimental_windows_sandbox',
+    'Enable experimental Windows sandbox.',
+    'Turns on a newer Windows sandbox implementation.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition('include_apply_patch_tool', 'Expose the apply_patch tool.', 'Makes apply patch tool calls available to the model.'),
+  makeFeatureDefinition('js_repl', 'Enable JavaScript REPL.', 'Allow JavaScript-based REPL style tooling.'),
+  makeFeatureDefinition('js_repl_tools_only', 'Restrict js_repl to tool-only mode.', 'Limits js_repl usage to explicit tool calls.'),
+  makeFeatureDefinition('memory_tool', 'Enable memory tool support.', 'Allows Codex to use memory-related workflow tools.'),
+  makeFeatureDefinition(
+    'multi_agent',
+    'Enable multi-agent support.',
+    'Allows multiple coordinated agent contexts.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'personality',
+    'Enable personality controls.',
+    'Turns on personality-related routing flags.',
+    { defaultValue: true, isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'powershell_utf8',
+    'Use UTF-8 in PowerShell sessions.',
+    'Keep PowerShell command output in UTF-8 encoding.',
+    { defaultValue: true, isDocumented: true }
+  ),
+  makeFeatureDefinition('prevent_idle_sleep', 'Prevent idle sleep while running.', 'Keeps the system awake during active sessions.'),
+  makeFeatureDefinition(
+    'remote_models',
+    'Enable remote model discovery.',
+    'Allows loading model lists from remote model providers.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'request_rule',
+    'Enable request rule controls.',
+    'Turn on request routing/validation policy behavior.',
+    { defaultValue: true, isDocumented: true }
+  ),
+  makeFeatureDefinition('responses_websockets', 'Enable Responses WebSocket transport.', 'Use websocket transport for Responses API calls.'),
+  makeFeatureDefinition('responses_websockets_v2', 'Enable Responses WebSocket v2 transport.', 'Use the next-generation websocket transport stack.'),
+  makeFeatureDefinition(
+    'runtime_metrics',
+    'Enable runtime metrics collection.',
+    'Record runtime metrics for analysis and telemetry.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'search_tool',
+    'Enable internal search tool.',
+    'Turns on the built-in search execution tool.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'shell_snapshot',
+    'Enable shell snapshots.',
+    'Capture shell environment state before runs.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'shell_tool',
+    'Enable shell tool access.',
+    'Allows Codex to run shell commands through the tool interface.',
+    { defaultValue: true, isDocumented: true }
+  ),
+  makeFeatureDefinition('shell_zsh_fork', 'Enable zsh forked shell tool.', 'Runs shell commands through a forked zsh process.'),
+  makeFeatureDefinition('skill_env_var_dependency_prompt', 'Enable environment variable prompts for skills.', 'Prompts when skills require missing environment variables.'),
+  makeFeatureDefinition('skill_mcp_dependency_install', 'Enable auto install MCP skill dependencies.', 'Installs missing MCP dependencies for skill execution.'),
+  makeFeatureDefinition('sqlite', 'Enable SQLite support features.', 'Turns SQLite-specific feature behavior on or off.'),
+  makeFeatureDefinition('steer', 'Enable steering control mode.', 'Allows steering the tool call strategy for some actions.'),
+  makeFeatureDefinition('undo', 'Enable undo behavior.', 'Expose undo controls for reversible operations.'),
+  makeFeatureDefinition(
+    'unified_exec',
+    'Use unified execution layer.',
+    'Route execution commands through the unified tool layer.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'use_linux_sandbox_bwrap',
+    'Enable Linux bubblewrap sandbox.',
+    'Use bwrap for Linux sandbox isolation.',
+    { isDocumented: true }
+  ),
+  makeFeatureDefinition(
+    'web_search',
+    'Enable web search tool.',
+    'Allows the model to call a web search tool.',
+    {
+      deprecation: '[features].web_search is deprecated; use the top-level web_search setting instead.',
+      isDocumented: true,
+    }
+  ),
+  makeFeatureDefinition(
+    'web_search_cached',
+    'Enable cached web search only.',
+    'Restricts web search calls to cached results.',
+    {
+      deprecation:
+        '[features].web_search_cached is deprecated legacy toggle. `true` maps to `web_search = "cached"`.',
+      isDocumented: true,
+    }
+  ),
+  makeFeatureDefinition(
+    'web_search_request',
+    'Enable web search request flow.',
+    'Turns on request-mode web search behavior.',
+    {
+      deprecation:
+        '[features].web_search_request is deprecated legacy toggle. `true` maps to `web_search = "live"`.',
+      isDocumented: true,
+    }
+  ),
+];
+
+const FEATURE_DEFINITION_MAP = CONFIG_FEATURE_DEFINITIONS.reduce((acc, definition) => {
+  acc[definition.key] = definition;
+
+  return acc;
+}, {});
+
+const DOCUMENTED_REFERENCE_FEATURE_KEYS = getReferenceFeatureKeys();
+
+export const getConfigFeatureKeys = () => {
+  if (DOCUMENTED_REFERENCE_FEATURE_KEYS.length > 0) {
+    return DOCUMENTED_REFERENCE_FEATURE_KEYS;
+  }
+
+  return CONFIG_FEATURE_DEFINITIONS
+    .filter((definition) => definition.isDocumented === true)
+    .map((definition) => definition.key);
+};
+
+export const getConfigFeatureDefinition = (key) => FEATURE_DEFINITION_MAP[key];
+
+export const getConfigFeatureDefinitionOrFallback = (key) => {
+  if (!key) {
+    return {
+      short: `${prettifyFeatureName(String(key))}`,
+      usage: 'Uses a supported feature flag in your Codex config.',
+      defaultValue: false,
+      isDocumented: false,
+    };
+  }
+
+  return (
+    FEATURE_DEFINITION_MAP[key] || {
+      key,
+      short: prettifyFeatureName(String(key)),
+      usage: 'This configured key is not in the official feature list.',
+      defaultValue: false,
+      isDocumented: false,
+    }
+  );
+};