codex-configurator 0.2.5 → 0.2.7

package/src/constants.js

@@ -3,7 +3,7 @@ export const CONTROL_HINT =
 export const FILE_SWITCH_HINT =
 	'↑/↓ choose • PgUp/PgDn page • Home/End jump • Enter switch file • Esc/Backspace/← cancel';
 export const EDIT_CONTROL_HINT =
-	'↑/↓ choose • PgUp/PgDn page • Home/End jump • Enter save • Esc/Backspace/← cancel • Del delete char (text input)';
+	'↑/↓ choose • PgUp/PgDn page • Home/End jump • Enter save • Esc/Backspace/← cancel • Del delete char (inline input)';
 export const FILTER_CONTROL_HINT =
 	'Type filter • Enter/Esc: done • Del/Backspace: delete • Ctrl+U: clear';
 export const COMMAND_HINT = 'Type : to see commands';

package/src/reference/config-schema.json

@@ -20,6 +20,13 @@
         "description": {
           "description": "Human-facing role documentation used in spawn tool guidance.",
           "type": "string"
+        },
+        "nickname_candidates": {
+          "description": "Candidate nicknames for agents spawned with this role.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
         }
       },
       "type": "object"
@@ -313,6 +320,9 @@
             "apps_mcp_gateway": {
               "type": "boolean"
             },
+            "artifact": {
+              "type": "boolean"
+            },
             "child_agents_md": {
               "type": "boolean"
             },
@@ -349,6 +359,15 @@
             "experimental_windows_sandbox": {
               "type": "boolean"
             },
+            "fast_mode": {
+              "type": "boolean"
+            },
+            "image_detail_original": {
+              "type": "boolean"
+            },
+            "image_generation": {
+              "type": "boolean"
+            },
             "include_apply_patch_tool": {
               "type": "boolean"
             },
@@ -370,6 +389,9 @@
             "personality": {
               "type": "boolean"
             },
+            "plugins": {
+              "type": "boolean"
+            },
             "powershell_utf8": {
               "type": "boolean"
             },
@@ -502,6 +524,9 @@
         "sandbox_mode": {
           "$ref": "#/definitions/SandboxMode"
         },
+        "service_tier": {
+          "$ref": "#/definitions/ServiceTier"
+        },
         "tools_view_image": {
           "type": "boolean"
         },
@@ -613,7 +638,19 @@
       "additionalProperties": false,
       "description": "Memories settings loaded from config.toml.",
       "properties": {
-        "max_raw_memories_for_global": {
+        "consolidation_model": {
+          "description": "Model used for memory consolidation.",
+          "type": "string"
+        },
+        "extract_model": {
+          "description": "Model used for thread summarisation.",
+          "type": "string"
+        },
+        "generate_memories": {
+          "description": "When `false`, newly created threads are stored with `memory_mode = \"disabled\"` in the state DB.",
+          "type": "boolean"
+        },
+        "max_raw_memories_for_consolidation": {
           "description": "Maximum number of recent raw memories retained for global consolidation.",
           "format": "uint",
           "minimum": 0,
@@ -640,17 +677,25 @@
           "format": "int64",
           "type": "integer"
         },
-        "phase_1_model": {
-          "description": "Model used for thread summarisation.",
-          "type": "string"
+        "no_memories_if_mcp_or_web_search": {
+          "description": "When `true`, web searches and MCP tool calls mark the thread `memory_mode` as `\"polluted\"`.",
+          "type": "boolean"
         },
-        "phase_2_model": {
-          "description": "Model used for memory consolidation.",
-          "type": "string"
+        "use_memories": {
+          "description": "When `false`, skip injecting memory usage instructions into developer prompts.",
+          "type": "boolean"
         }
       },
       "type": "object"
     },
+    "ModelAvailabilityNuxConfig": {
+      "additionalProperties": {
+        "format": "uint32",
+        "minimum": 0,
+        "type": "integer"
+      },
+      "type": "object"
+    },
     "ModelProviderInfo": {
       "additionalProperties": false,
       "description": "Serializable representation of a provider definition.",
@@ -1069,6 +1114,16 @@
       ],
       "type": "string"
     },
+    "PluginConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
     "ProjectConfig": {
       "additionalProperties": false,
       "properties": {
@@ -1146,6 +1201,10 @@
           },
           "type": "object"
         },
+        "oauth_resource": {
+          "default": null,
+          "type": "string"
+        },
         "required": {
           "default": null,
           "type": "boolean"
@@ -1179,6 +1238,18 @@
       },
       "type": "object"
     },
+    "RealtimeAudioToml": {
+      "additionalProperties": false,
+      "properties": {
+        "microphone": {
+          "type": "string"
+        },
+        "speaker": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
     "ReasoningEffort": {
       "description": "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
       "enum": [
@@ -1266,6 +1337,13 @@
       },
       "type": "object"
     },
+    "ServiceTier": {
+      "enum": [
+        "fast",
+        "flex"
+      ],
+      "type": "string"
+    },
     "ShellEnvironmentPolicyInherit": {
       "oneOf": [
         {
@@ -1396,6 +1474,15 @@
           "description": "Enable animations (welcome screen, shimmer effects, spinners). Defaults to `true`.",
           "type": "boolean"
         },
+        "model_availability_nux": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/ModelAvailabilityNuxConfig"
+            }
+          ],
+          "default": {},
+          "description": "Startup tooltip availability NUX state persisted by the TUI."
+        },
         "notification_method": {
           "allOf": [
             {
@@ -1540,6 +1627,15 @@
       "default": null,
       "description": "Settings for app-specific controls."
     },
+    "audio": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/RealtimeAudioToml"
+        }
+      ],
+      "default": null,
+      "description": "Machine-local realtime audio device preferences used by realtime voice."
+    },
     "background_terminal_max_timeout": {
       "description": "Maximum poll window for background terminal output (`write_stdin`), in milliseconds. Default: `300000` (5 minutes).",
       "format": "uint64",
@@ -1584,11 +1680,15 @@
       "$ref": "#/definitions/AbsolutePathBuf"
     },
     "experimental_realtime_ws_backend_prompt": {
-      "description": "Experimental / do not use. Overrides only the realtime conversation websocket transport backend prompt (the `Op::RealtimeConversation` `/ws` session.create backend_prompt) without changing normal prompts.",
+      "description": "Experimental / do not use. Overrides only the realtime conversation websocket transport instructions (the `Op::RealtimeConversation` `/ws` session.update instructions) without changing normal prompts.",
       "type": "string"
     },
     "experimental_realtime_ws_base_url": {
-      "description": "Experimental / do not use. Overrides only the realtime conversation websocket transport base URL (the `Op::RealtimeConversation` `/ws` connection) without changing normal provider HTTP requests.",
+      "description": "Experimental / do not use. Overrides only the realtime conversation websocket transport base URL (the `Op::RealtimeConversation` `/v1/realtime` connection) without changing normal provider HTTP requests.",
+      "type": "string"
+    },
+    "experimental_realtime_ws_model": {
+      "description": "Experimental / do not use. Selects the realtime websocket model/snapshot used for the `Op::RealtimeConversation` connection.",
       "type": "string"
     },
     "experimental_use_freeform_apply_patch": {
@@ -1611,6 +1711,9 @@
         "apps_mcp_gateway": {
           "type": "boolean"
         },
+        "artifact": {
+          "type": "boolean"
+        },
         "child_agents_md": {
           "type": "boolean"
         },
@@ -1647,6 +1750,15 @@
         "experimental_windows_sandbox": {
           "type": "boolean"
         },
+        "fast_mode": {
+          "type": "boolean"
+        },
+        "image_detail_original": {
+          "type": "boolean"
+        },
+        "image_generation": {
+          "type": "boolean"
+        },
         "include_apply_patch_tool": {
           "type": "boolean"
         },
@@ -1668,6 +1780,9 @@
         "personality": {
           "type": "boolean"
         },
+        "plugins": {
+          "type": "boolean"
+        },
         "powershell_utf8": {
           "type": "boolean"
         },
@@ -1965,6 +2080,14 @@
     "plan_mode_reasoning_effort": {
       "$ref": "#/definitions/ReasoningEffort"
     },
+    "plugins": {
+      "additionalProperties": {
+        "$ref": "#/definitions/PluginConfig"
+      },
+      "default": {},
+      "description": "User-level plugin config entries keyed by plugin name.",
+      "type": "object"
+    },
     "profile": {
       "description": "Profile to use from the `profiles` map.",
       "type": "string"
@@ -2024,6 +2147,14 @@
       ],
       "description": "Sandbox configuration to apply if `sandbox` is `WorkspaceWrite`."
     },
+    "service_tier": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/ServiceTier"
+        }
+      ],
+      "description": "Optional explicit service tier preference for new turns (`fast` or `flex`)."
+    },
     "shell_environment_policy": {
       "allOf": [
         {

package/src/scalarEditing.js

@@ -0,0 +1,117 @@
+import { getReferenceOptionForPath } from './configReference.js';
+
+const STRING_REFERENCE_TYPE_PATTERN = /^string(?:\s|$)/;
+const DIGIT_GROUP_PATTERN = '\\d(?:_?\\d)*';
+const INTEGER_DRAFT_PATTERN = new RegExp(
+	`^[+-]?${DIGIT_GROUP_PATTERN}$`,
+);
+const NUMBER_DRAFT_PATTERN = new RegExp(
+	`^[+-]?(?:(?:${DIGIT_GROUP_PATTERN}(?:\\.(?:${DIGIT_GROUP_PATTERN})?)?)|(?:\\.${DIGIT_GROUP_PATTERN}))(?:[eE][+-]?${DIGIT_GROUP_PATTERN})?$`,
+);
+
+export const getReferenceScalarType = (pathSegments) => {
+	const referenceType = String(
+		getReferenceOptionForPath(pathSegments)?.type || '',
+	).trim();
+
+	if (STRING_REFERENCE_TYPE_PATTERN.test(referenceType)) {
+		return 'string';
+	}
+
+	if (referenceType === 'integer') {
+		return 'integer';
+	}
+
+	if (referenceType === 'number') {
+		return 'number';
+	}
+
+	return null;
+};
+
+export const getScalarEditType = (pathSegments, value) => {
+	const referenceScalarType = getReferenceScalarType(pathSegments);
+	if (referenceScalarType) {
+		return referenceScalarType;
+	}
+
+	if (typeof value === 'string') {
+		return 'string';
+	}
+
+	if (typeof value === 'number') {
+		return Number.isInteger(value) ? 'integer' : 'number';
+	}
+	return null;
+};
+
+export const parseScalarDraftValue = (draftValue, scalarType) => {
+	const nextDraftValue =
+		typeof draftValue === 'string'
+			? draftValue
+			: String(draftValue ?? '');
+
+	if (scalarType === 'string') {
+		return {
+			ok: true,
+			value: nextDraftValue,
+		};
+	}
+
+	const normalized = nextDraftValue.trim();
+	if (!normalized) {
+		return {
+			ok: false,
+			error: 'Value cannot be empty. Use Del to unset it.',
+		};
+	}
+
+	if (scalarType === 'integer') {
+		if (!INTEGER_DRAFT_PATTERN.test(normalized)) {
+			return {
+				ok: false,
+				error: 'Value must be a whole number.',
+			};
+		}
+
+		const parsed = Number(normalized.replaceAll('_', ''));
+		if (!Number.isSafeInteger(parsed)) {
+			return {
+				ok: false,
+				error: 'Value must be a safe integer.',
+			};
+		}
+
+		return {
+			ok: true,
+			value: parsed,
+		};
+	}
+
+	if (scalarType === 'number') {
+		if (!NUMBER_DRAFT_PATTERN.test(normalized)) {
+			return {
+				ok: false,
+				error: 'Value must be a finite decimal number.',
+			};
+		}
+
+		const parsed = Number(normalized.replaceAll('_', ''));
+		if (!Number.isFinite(parsed)) {
+			return {
+				ok: false,
+				error: 'Value must be a finite decimal number.',
+			};
+		}
+
+		return {
+			ok: true,
+			value: parsed,
+		};
+	}
+
+	return {
+		ok: false,
+		error: 'Unsupported scalar type.',
+	};
+};

package/src/schemaRuntimeSync.js

@@ -0,0 +1,282 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  getReferenceSchemaRevision,
+  setReferenceSchema,
+} from './configReference.js';
+import { logConfiguratorError } from './errorLogger.js';
+
+const CONFIG_SCHEMA_URL = 'https://developers.openai.com/codex/config-schema.json';
+const SCHEMA_CACHE_DIRECTORY_NAME = 'codex-configurator-cache';
+const SCHEMA_CACHE_FILE_NAME = 'config-schema.json';
+const SCHEMA_METADATA_FILE_NAME = 'config-schema.meta.json';
+const FETCH_TIMEOUT_MS = 10000;
+const MAX_SCHEMA_BYTES = 512 * 1024;
+
+const isObject = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const normalizeText = (value) => String(value || '').trim();
+
+const resolveCodexDirectory = ({ mainConfigPath = '', homeDir = os.homedir() } = {}) => {
+  const normalizedPath = normalizeText(mainConfigPath);
+  if (!normalizedPath) {
+    return path.join(homeDir, '.codex');
+  }
+
+  return path.dirname(path.resolve(normalizedPath));
+};
+
+export const resolveSchemaCachePaths = ({ mainConfigPath = '', homeDir = os.homedir() } = {}) => {
+  const codexDirectory = resolveCodexDirectory({ mainConfigPath, homeDir });
+  const cacheDirectory = path.join(codexDirectory, SCHEMA_CACHE_DIRECTORY_NAME);
+  return {
+    codexDirectory,
+    cacheDirectory,
+    schemaPath: path.join(cacheDirectory, SCHEMA_CACHE_FILE_NAME),
+    metadataPath: path.join(cacheDirectory, SCHEMA_METADATA_FILE_NAME),
+  };
+};
+
+const readJsonFile = (targetPath) => {
+  try {
+    const payload = fs.readFileSync(targetPath, 'utf8');
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+};
+
+const writeJsonFileAtomic = (targetPath, payload) => {
+  const directoryPath = path.dirname(targetPath);
+  const fileName = path.basename(targetPath);
+  const tempPath = path.join(
+    directoryPath,
+    `.${fileName}.${process.pid}.${Date.now()}.tmp`
+  );
+
+  if (!fs.existsSync(directoryPath)) {
+    fs.mkdirSync(directoryPath, { recursive: true, mode: 0o700 });
+  }
+
+  let fileDescriptor = null;
+
+  try {
+    fileDescriptor = fs.openSync(tempPath, 'wx', 0o600);
+    fs.writeFileSync(fileDescriptor, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(fileDescriptor);
+    fs.closeSync(fileDescriptor);
+    fileDescriptor = null;
+    fs.renameSync(tempPath, targetPath);
+  } finally {
+    if (fileDescriptor !== null) {
+      try {
+        fs.closeSync(fileDescriptor);
+      } catch {}
+    }
+
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {}
+    }
+  }
+};
+
+const applySchema = (schema) => {
+  const previousRevision = getReferenceSchemaRevision();
+  const ok = setReferenceSchema(schema);
+  if (!ok) {
+    return {
+      ok: false,
+      changed: false,
+    };
+  }
+
+  return {
+    ok: true,
+    changed: previousRevision !== getReferenceSchemaRevision(),
+  };
+};
+
+const buildConditionalHeaders = (metadata = {}) => {
+  const headers = {
+    accept: 'application/json',
+  };
+  const etag = normalizeText(metadata.etag);
+  const lastModified = normalizeText(metadata.lastModified);
+
+  if (etag) {
+    headers['if-none-match'] = etag;
+  }
+
+  if (lastModified) {
+    headers['if-modified-since'] = lastModified;
+  }
+
+  return headers;
+};
+
+const fetchRemoteSchema = async ({
+  fetchImpl = fetch,
+  metadata = {},
+}) => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetchImpl(CONFIG_SCHEMA_URL, {
+      headers: buildConditionalHeaders(metadata),
+      signal: controller.signal,
+    });
+
+    if (response.status === 304) {
+      return {
+        status: 'not-modified',
+      };
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `Schema request failed (${response.status} ${response.statusText})`
+      );
+    }
+
+    const contentType = normalizeText(response.headers.get('content-type')).toLowerCase();
+    if (!contentType.includes('application/json')) {
+      throw new Error('Schema response content-type is not application/json.');
+    }
+
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAX_SCHEMA_BYTES) {
+      throw new Error(
+        `Schema response exceeded max size (${bytes.length} bytes > ${MAX_SCHEMA_BYTES} bytes).`
+      );
+    }
+
+    let parsedSchema = null;
+    try {
+      parsedSchema = JSON.parse(bytes.toString('utf8'));
+    } catch (error) {
+      throw new Error(
+        `Schema response was not valid JSON (${String(error?.message || 'parse failed')}).`
+      );
+    }
+
+    return {
+      status: 'updated',
+      schema: parsedSchema,
+      metadata: {
+        etag: normalizeText(response.headers.get('etag')) || null,
+        lastModified: normalizeText(response.headers.get('last-modified')) || null,
+      },
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export const syncReferenceSchemaAtStartup = async ({
+  mainConfigPath = '',
+  fetchImpl = fetch,
+  onSchemaChange,
+  onStatus,
+} = {}) => {
+  const cachePaths = resolveSchemaCachePaths({ mainConfigPath });
+  const notifySchemaChange = (source) => {
+    if (typeof onSchemaChange === 'function') {
+      onSchemaChange({ source });
+    }
+  };
+  const updateStatus = (value) => {
+    if (typeof onStatus === 'function') {
+      onStatus(String(value || '').trim());
+    }
+  };
+
+  let source = 'bundled';
+  let canReuseCachedValidators = false;
+
+  try {
+    updateStatus('Schema: Loading cache...');
+
+    const cachedSchema = readJsonFile(cachePaths.schemaPath);
+    const metadataPayload = readJsonFile(cachePaths.metadataPath);
+    const cachedMetadata = isObject(metadataPayload) ? metadataPayload : {};
+
+    if (cachedSchema !== null) {
+      const cacheApplyResult = applySchema(cachedSchema);
+      if (cacheApplyResult.ok) {
+        source = 'cache';
+        canReuseCachedValidators = true;
+        if (cacheApplyResult.changed) {
+          notifySchemaChange('cache');
+        }
+      } else {
+        logConfiguratorError('schema.cache.invalid', {
+          schemaPath: cachePaths.schemaPath,
+        });
+      }
+    }
+
+    updateStatus('Schema: Checking upstream...');
+
+    const fetchResult = await fetchRemoteSchema({
+      fetchImpl,
+      metadata: canReuseCachedValidators ? cachedMetadata : {},
+    });
+
+    if (fetchResult.status === 'not-modified') {
+      return {
+        ok: true,
+        updated: false,
+        source,
+      };
+    }
+
+    const remoteApplyResult = applySchema(fetchResult.schema);
+    if (!remoteApplyResult.ok) {
+      throw new Error('Downloaded schema did not pass local validation.');
+    }
+    if (remoteApplyResult.changed) {
+      notifySchemaChange('remote');
+    }
+
+    updateStatus('Schema: Saving cache...');
+
+    const mergedMetadata = {
+      etag: fetchResult.metadata.etag || normalizeText(cachedMetadata.etag) || null,
+      lastModified:
+        fetchResult.metadata.lastModified ||
+        normalizeText(cachedMetadata.lastModified) ||
+        null,
+      updatedAt: new Date().toISOString(),
+      sourceUrl: CONFIG_SCHEMA_URL,
+    };
+
+    writeJsonFileAtomic(cachePaths.schemaPath, fetchResult.schema);
+    writeJsonFileAtomic(cachePaths.metadataPath, mergedMetadata);
+
+    return {
+      ok: true,
+      updated: true,
+      source: 'remote',
+    };
+  } catch (error) {
+    const message = String(error?.message || 'Unknown schema sync error.');
+    logConfiguratorError('schema.sync.failed', {
+      error: message,
+      source,
+      schemaPath: cachePaths.schemaPath,
+      metadataPath: cachePaths.metadataPath,
+    });
+
+    return {
+      ok: false,
+      updated: false,
+      source,
+      error: message,
+    };
+  }
+};