@inetafrica/open-claudia 2.15.0 → 3.0.1

package/test-provider-capabilities.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const configDir = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-capabilities-"));
+const workspace = path.join(configDir, "workspace");
+fs.mkdirSync(path.join(workspace, "alpha"), { recursive: true });
+process.env.OPEN_CLAUDIA_CONFIG_DIR = configDir;
+process.env.WORKSPACE = workspace;
+process.env.TELEGRAM_CHAT_ID = "fixture-chat";
+process.env.CHANNELS = "";
+process.env.OPEN_CLAUDIA_TEST = "1";
+process.env.CLAUDE_PATH = process.execPath;
+process.env.CODEX_PATH = process.execPath;
+
+const stateApi = require("./core/state");
+const handlers = require("./core/handlers");
+const commands = require("./core/commands");
+const providers = require("./core/providers");
+const { handleAction } = require("./core/actions");
+const { runInChat } = require("./core/context");
+
+const state = stateApi.currentState();
+state.currentSession = { name: "alpha", dir: path.join(workspace, "alpha") };
+state.settings.backend = "claude";
+
+function callbacks(rows) {
+  return rows.flat().map((button) => button.callback_data).filter(Boolean);
+}
+
+function pickerProbe() {
+  assert.strictEqual(typeof handlers.buildBackendPicker, "function");
+  assert.strictEqual(typeof handlers.buildModelPicker, "function");
+  const backend = handlers.buildBackendPicker({ state, registry: providers });
+  const expectedProviders = providers.listProviders().map((provider) => provider.id);
+  assert.deepStrictEqual(
+    callbacks(backend.rows).map((value) => value.slice("be:".length)),
+    expectedProviders,
+    "backend picker comes from registry order",
+  );
+
+  const model = handlers.buildModelPicker({ state, registry: providers });
+  const modelCallbacks = callbacks(model.rows).filter((value) => value.startsWith("mb:"));
+  for (const provider of providers.listProviders()) {
+    const choices = provider.modelChoices();
+    for (const choice of choices) {
+      assert.ok(modelCallbacks.includes(`mb:${provider.id}:${choice}`), `${provider.id} model choice ${choice}`);
+    }
+    assert.ok(modelCallbacks.includes(`mb:${provider.id}:default`), `${provider.id} default model control`);
+  }
+  assert.ok(!fs.readFileSync(path.join(__dirname, "core", "handlers.js"), "utf8").includes("DEFAULT_CLAUDE_MODEL"));
+}
+
+function mutationProbe() {
+  assert.strictEqual(typeof handlers.applyProviderSetting, "function");
+  const claudeSettings = stateApi.getProviderSettings(state, "claude");
+  const codexSettings = stateApi.getProviderSettings(state, "codex");
+  claudeSettings.effort = "low";
+  claudeSettings.budget = 2;
+  codexSettings.effort = null;
+  codexSettings.budget = null;
+  codexSettings.worktree = false;
+
+  state.settings.backend = "codex";
+  let result = handlers.applyProviderSetting(state, "codex", "effort", "xhigh", { registry: providers });
+  assert.strictEqual(result.ok, true);
+  assert.strictEqual(codexSettings.effort, "xhigh");
+  assert.strictEqual(claudeSettings.effort, "low", "provider setting stays isolated");
+
+  const beforeBudget = structuredClone(state.providerSettings);
+  result = handlers.applyProviderSetting(state, "codex", "budget", 5, { registry: providers });
+  assert.strictEqual(result.ok, false);
+  assert.strictEqual(result.code, "UNSUPPORTED_PROVIDER_CAPABILITY");
+  assert.match(result.message, /no per-run monetary budget/i);
+  assert.deepStrictEqual(state.providerSettings, beforeBudget, "unsupported budget cannot mutate state");
+
+  const beforeWorktree = structuredClone(state.providerSettings);
+  result = handlers.applyProviderSetting(state, "codex", "worktree", true, { registry: providers });
+  assert.strictEqual(result.ok, false);
+  assert.match(result.message, /worktree/i);
+  assert.deepStrictEqual(state.providerSettings, beforeWorktree, "unsupported worktree cannot mutate state");
+
+  const beforeInvalidEffort = structuredClone(state.providerSettings);
+  result = handlers.applyProviderSetting(state, "codex", "effort", "maximum-ish", { registry: providers });
+  assert.strictEqual(result.ok, false);
+  assert.deepStrictEqual(state.providerSettings, beforeInvalidEffort, "invalid effort cannot mutate state");
+
+  state.settings.backend = "claude";
+  result = handlers.applyProviderSetting(state, "claude", "budget", 4, { registry: providers });
+  assert.strictEqual(result.ok, true);
+  assert.strictEqual(claudeSettings.budget, 4);
+
+  const stale = structuredClone(state.providerSettings);
+  result = handlers.applyProviderSetting(state, "codex", "effort", "high", { registry: providers, requireActive: true });
+  assert.strictEqual(result.code, "STALE_PROVIDER_CONTROL");
+  assert.deepStrictEqual(state.providerSettings, stale, "stale provider control cannot mutate inactive settings");
+}
+
+async function inChat(fn, sent) {
+  return runInChat({
+    adapter: {
+      id: "fixture",
+      type: "fixture",
+      send: async (_channelId, text, options) => { sent.push({ text, options }); return true; },
+    },
+    channelId: "fixture-chat",
+    canonicalUserId: "telegram:fixture-chat",
+    userId: "fixture-chat",
+  }, fn);
+}
+
+async function commandProbe() {
+  const names = new Set(commands.list().map((command) => command.name));
+  assert.ok(names.has("ask"), "/ask is registered");
+  const sent = [];
+  const dispatch = (text) => inChat(() => commands.dispatch(text, {
+    adapter: { id: "fixture", type: "fixture" },
+    channelId: "fixture-chat",
+    canonicalUserId: "telegram:fixture-chat",
+    userId: "fixture-chat",
+  }), sent);
+
+  state.settings.backend = "codex";
+  stateApi.getProviderSettings(state, "codex").effort = null;
+  await dispatch("/effort high");
+  assert.strictEqual(stateApi.getProviderSettings(state, "codex").effort, "high", "Codex native effort is accepted");
+
+  const beforeBudget = structuredClone(state.providerSettings);
+  await dispatch("/budget 5");
+  assert.deepStrictEqual(state.providerSettings, beforeBudget);
+  assert.match(sent.at(-1).text, /no per-run monetary budget/i);
+
+  const beforeWorktree = structuredClone(state.providerSettings);
+  await dispatch("/worktree");
+  assert.deepStrictEqual(state.providerSettings, beforeWorktree);
+  assert.match(sent.at(-1).text, /worktree/i);
+
+  await dispatch("/plan");
+  assert.strictEqual(stateApi.getProviderSettings(state, "codex").permissionMode, "plan");
+  await dispatch("/ask");
+  assert.strictEqual(stateApi.getProviderSettings(state, "codex").permissionMode, "ask");
+
+  await dispatch("/status");
+  assert.match(sent.at(-1).text, /Provider: OpenAI Codex/);
+  assert.match(sent.at(-1).text, /Capabilities:/);
+  assert.match(sent.at(-1).text, /budget unsupported/i);
+
+  await dispatch("/backend");
+  assert.deepStrictEqual(
+    callbacks(sent.at(-1).options.keyboard.inline_keyboard).map((value) => value.slice(3)),
+    providers.listProviders().map((provider) => provider.id),
+  );
+
+  await dispatch("/model");
+  const modelControls = callbacks(sent.at(-1).options.keyboard.inline_keyboard);
+  assert.ok(modelControls.includes("mb:codex:gpt-5.6-sol"));
+  assert.ok(modelControls.includes("mb:codex:gpt-5.6-luna"));
+  assert.ok(!modelControls.includes("mb:codex:o4-mini"));
+  assert.ok(modelControls.includes("mb:claude:claude-sonnet-4-6"));
+}
+
+async function callbackProbe() {
+  state.settings.backend = "codex";
+  stateApi.getProviderSettings(state, "codex").budget = null;
+  const before = structuredClone(state.providerSettings);
+  const sent = [];
+  await inChat(() => handleAction({
+    adapter: { id: "fixture", type: "fixture" },
+    channelId: "fixture-chat",
+    canonicalUserId: "telegram:fixture-chat",
+    userId: "fixture-chat",
+    action: { payload: "b:codex:5" },
+  }), sent);
+  assert.deepStrictEqual(state.providerSettings, before, "unsupported callback cannot mutate state");
+  assert.match(sent.at(-1).text, /no per-run monetary budget/i);
+
+  state.settings.backend = "claude";
+  const stale = structuredClone(state.providerSettings);
+  await inChat(() => handleAction({
+    adapter: { id: "fixture", type: "fixture" },
+    channelId: "fixture-chat",
+    canonicalUserId: "telegram:fixture-chat",
+    userId: "fixture-chat",
+    action: { payload: "e:codex:high" },
+  }), sent);
+  assert.deepStrictEqual(state.providerSettings, stale, "stale callback cannot mutate inactive provider");
+  assert.match(sent.at(-1).text, /stale/i);
+}
+
+async function adapterReadOnlyProbe() {
+  const { createClaudeProvider } = require("./core/providers/claude");
+  const { createCodexProvider } = require("./core/providers/codex");
+  const common = {
+    resolveExecutable: () => process.execPath,
+    buildEnv: () => ({}),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    hookTransport: false,
+  };
+  const context = {
+    coreInstructions: "policy",
+    dynamicContext: "context",
+    userPrompt: "question",
+    providerSettings: { permissionMode: "ask" },
+    fresh: true,
+  };
+  const claude = createClaudeProvider(common).buildMainInvocation(context);
+  assert.deepStrictEqual(claude.args.slice(claude.args.indexOf("--permission-mode"), claude.args.indexOf("--permission-mode") + 2), ["--permission-mode", "plan"]);
+  const codex = createCodexProvider({ ...common, defaultModel: "gpt-fixture" }).buildMainInvocation(context);
+  assert.deepStrictEqual(codex.args.slice(codex.args.indexOf("--sandbox"), codex.args.indexOf("--sandbox") + 2), ["--sandbox", "read-only"]);
+  assert.ok(!codex.args.includes("--dangerously-bypass-approvals-and-sandbox"));
+}
+
+async function main() {
+  pickerProbe();
+  mutationProbe();
+  await commandProbe();
+  await callbackProbe();
+  await adapterReadOnlyProbe();
+  console.log("provider capabilities OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(configDir, { recursive: true, force: true });
+});

package/test-provider-claude.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+const { validateInvocation, validateProvider } = require("./core/providers/contract");
+const { createClaudeProvider } = require("./core/providers/claude");
+const { getProvider } = require("./core/providers");
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+const safeEnv = {
+  PATH: "/fixture/bin",
+  HOME: "/fixture/home",
+  CLAUDE_CODE_OAUTH_TOKEN: "fixture-present-not-a-real-token",
+};
+let authState = { state: "authenticated", reason: null, method: "fixture" };
+const provider = createClaudeProvider({
+  hookTransport: false,
+  resolveExecutable: () => "/fixture/claude",
+  defaultModel: "claude-default-fixture",
+  buildEnv: () => ({ ...safeEnv }),
+  getAuthStatus: () => authState,
+  runCommand: (_binary, args) => {
+    if (args[0] === "--version") return { ok: true, output: "2.1.150 (Claude Code)", code: 0 };
+    if (args[0] === "--help") return {
+      ok: true,
+      output: "--append-system-prompt --output-format --resume --permission-mode --settings",
+      code: 0,
+    };
+    return { ok: false, output: "unexpected fixture command", code: 1 };
+  },
+});
+
+assert.strictEqual(validateProvider(provider), provider);
+assert.strictEqual(provider.id, "claude");
+assert.strictEqual(getProvider("claude").id, "claude", "built-in registry exposes the adapter without probing it at import");
+assert.strictEqual(provider.label, "Claude Code");
+assert.strictEqual(provider.isAvailable(), true);
+assert.strictEqual(provider.executable(), "/fixture/claude");
+assert.strictEqual(provider.defaultModel(), "claude-default-fixture");
+assert.ok(provider.modelChoices().includes("claude-fable-5"));
+assert.ok(provider.modelChoices().includes("claude-sonnet-4-6"));
+assert.deepStrictEqual(provider.compatibilityStatus(), {
+  state: "compatible",
+  version: "2.1.150",
+  reason: null,
+});
+assert.strictEqual(provider.capabilities.resume.support, "native");
+assert.strictEqual(provider.capabilities.readOnlyMode.support, "native");
+assert.deepStrictEqual(provider.capabilities.effort.values, ["low", "medium", "high", "xhigh", "max"]);
+assert.strictEqual(provider.capabilities.budget.support, "native");
+assert.strictEqual(provider.capabilities.worktree.support, "native");
+assert.strictEqual(provider.capabilities.maxTurns.support, "native");
+assert.strictEqual(provider.capabilities.partialStreaming.support, "native");
+assert.strictEqual(provider.capabilities.persistentUtilityStream.support, "native");
+assert.strictEqual(provider.capabilities.preToolHook.support, "native");
+assert.strictEqual(provider.capabilities.imageFlag.support, "unsupported");
+
+const richContext = deepFreeze({
+  coreInstructions: "STABLE CORE",
+  dynamicContext: "DYNAMIC CONTEXT",
+  userPrompt: "USER SENTINEL",
+  fresh: true,
+  sessionId: "ignored-because-fresh",
+  providerSettings: {
+    model: "claude-sonnet-4-6",
+    effort: "high",
+    budget: 2.5,
+    permissionMode: "plan",
+    worktree: true,
+  },
+  maxTurns: 4,
+  transcriptDirectory: "/fixture/transcripts",
+  voiceStream: true,
+  toolHookSettings: "/fixture/deny-gate.json",
+});
+const before = JSON.stringify(richContext);
+const richInvocation = validateInvocation(provider.buildMainInvocation(richContext));
+assert.strictEqual(JSON.stringify(richContext), before, "frozen run context must not be mutated");
+assert.strictEqual(richInvocation.binary, "/fixture/claude");
+assert.deepStrictEqual(richInvocation.args, [
+  "-p",
+  "--verbose",
+  "--output-format", "stream-json",
+  "--append-system-prompt", "STABLE CORE",
+  "--settings", "/fixture/deny-gate.json",
+  "--add-dir", "/fixture/transcripts",
+  "--model", "claude-sonnet-4-6",
+  "--max-turns", "4",
+  "--effort", "high",
+  "--max-budget-usd", "2.5",
+  "--permission-mode", "plan",
+  "--worktree",
+  "--include-partial-messages",
+  "DYNAMIC CONTEXT\n\nUSER SENTINEL",
+]);
+assert.deepStrictEqual(richInvocation.env, safeEnv);
+assert.strictEqual(richInvocation.stdin, null);
+assert.ok(richInvocation.parserState.seenUsage instanceof Set);
+
+function simpleContext(overrides = {}) {
+  return deepFreeze({
+    coreInstructions: "CORE",
+    dynamicContext: "",
+    userPrompt: "PROMPT",
+    providerSettings: {},
+    ...overrides,
+  });
+}
+
+const fresh = provider.buildMainInvocation(simpleContext({ fresh: true, sessionId: "old" }));
+assert.ok(!fresh.args.includes("--resume"));
+assert.ok(!fresh.args.includes("--continue"));
+assert.ok(fresh.args.includes("--dangerously-skip-permissions"), "direct mode preserves current behavior");
+
+const resumed = provider.buildMainInvocation(simpleContext({ resumeSessionId: "resume-1" }));
+assert.deepStrictEqual(resumed.args.slice(6, 10), ["--resume", "resume-1", "--model", "claude-default-fixture"]);
+
+const implicitResume = provider.buildMainInvocation(simpleContext({ sessionId: "active-1" }));
+assert.ok(implicitResume.args.indexOf("--resume") >= 0);
+assert.strictEqual(implicitResume.args[implicitResume.args.indexOf("--resume") + 1], "active-1");
+
+const continued = provider.buildMainInvocation(simpleContext({ continueSession: true, sessionId: "active-1" }));
+assert.ok(continued.args.includes("--continue"));
+assert.ok(!continued.args.includes("--resume"));
+
+const readOnlyAsk = provider.buildMainInvocation(simpleContext({ providerSettings: { permissionMode: "ask" } }));
+assert.deepStrictEqual(readOnlyAsk.args.slice(readOnlyAsk.args.indexOf("--permission-mode"), -1), ["--permission-mode", "plan"]);
+
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ resumeSessionId: "one", continueSession: true })),
+  (error) => error && error.code === "INVALID_PROVIDER_CONTEXT",
+);
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ providerSettings: { effort: "extreme" } })),
+  (error) => error && error.code === "UNSUPPORTED_PROVIDER_SETTING",
+);
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ providerSettings: { budget: -1 } })),
+  (error) => error && error.code === "INVALID_PROVIDER_CONTEXT",
+);
+assert.throws(
+  () => provider.buildMainInvocation(deepFreeze({ dynamicContext: "only", userPrompt: "raw" })),
+  (error) => error && error.code === "MISSING_CORE_INSTRUCTIONS",
+);
+
+const utility = validateInvocation(provider.buildUtilityInvocation(deepFreeze({
+  coreInstructions: "UTILITY CORE",
+  userPrompt: "UTILITY PROMPT",
+  readOnly: true,
+  allowedTools: ["Read", "Glob"],
+  disallowedTools: ["Write"],
+  outputSchema: { type: "object", required: ["ok"] },
+  tier: "low",
+  maxTurns: 2,
+  toolHookSettings: "/fixture/utility-hook.json",
+})));
+assert.ok(utility.args.includes("--no-session-persistence"));
+assert.deepStrictEqual(utility.args.slice(utility.args.indexOf("--allowedTools"), utility.args.indexOf("--allowedTools") + 2), ["--allowedTools", "Read,Glob"]);
+assert.deepStrictEqual(utility.args.slice(utility.args.indexOf("--permission-mode"), utility.args.indexOf("--permission-mode") + 2), ["--permission-mode", "plan"]);
+assert.strictEqual(utility.args[utility.args.indexOf("--model") + 1], "claude-haiku-4-5-20251001");
+assert.strictEqual(utility.args[utility.args.indexOf("--json-schema") + 1], JSON.stringify({ type: "object", required: ["ok"] }));
+assert.strictEqual(utility.stdin, "UTILITY PROMPT", "utility prompt uses protected stdin transport");
+assert.ok(!utility.args.includes("UTILITY PROMPT"), "utility prompt is absent from argv");
+
+const decoder = provider.createEventDecoder();
+const raw = decoder.push(Buffer.from('{"type":"system","subtype":"init","session_id":"bound-session"}\n'));
+assert.deepStrictEqual(provider.normalizeEvent(raw[0], richInvocation.parserState), [{ type: "session", sessionId: "bound-session" }]);
+
+assert.strictEqual(provider.authStatus().state, "authenticated");
+assert.strictEqual(provider.preflightAuth(), null);
+authState = { state: "unauthenticated", reason: "login required" };
+const authFailure = provider.preflightAuth();
+assert.strictEqual(authFailure.code, "PROVIDER_UNAUTHENTICATED");
+assert.match(authFailure.message, /Claude auth needs attention/);
+assert.match(provider.authHelp(), /setup_token/);
+
+const missing = createClaudeProvider({ hookTransport: false, resolveExecutable: () => null, getAuthStatus: () => ({ state: "not_checked", reason: "missing" }) });
+assert.strictEqual(missing.isAvailable(), false);
+assert.throws(
+  () => missing.buildMainInvocation(simpleContext()),
+  (error) => error && error.code === "NO_AVAILABLE_PROVIDER",
+);
+
+const incompatible = createClaudeProvider({
+  hookTransport: false,
+  resolveExecutable: () => "/fixture/old-claude",
+  buildEnv: () => ({ PATH: "/fixture" }),
+  getAuthStatus: () => ({ state: "unknown", reason: "not checked" }),
+  runCommand: (_binary, args) => args[0] === "--version"
+    ? { ok: true, output: "0.1.0", code: 0 }
+    : { ok: true, output: "--output-format", code: 0 },
+});
+assert.strictEqual(incompatible.compatibilityStatus().state, "incompatible");
+
+const source = fs.readFileSync(path.join(__dirname, "core", "providers", "claude.js"), "utf8");
+assert.ok(!source.includes('require("child_process")'), "provider adapter must return invocation data instead of spawning");
+
+console.log("Claude provider OK");

package/test-provider-codex.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+const { validateInvocation, validateProvider } = require("./core/providers/contract");
+const { createCodexProvider } = require("./core/providers/codex");
+const { getProvider } = require("./core/providers");
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+const safeEnv = { PATH: "/fixture/bin", HOME: "/fixture/home", OPENAI_API_KEY: "fixture-not-a-real-key" };
+let authState = { state: "authenticated", reason: null, method: "fixture" };
+const provider = createCodexProvider({
+  hookTransport: false,
+  resolveExecutable: () => "/fixture/codex",
+  defaultModel: "gpt-5-codex",
+  buildEnv: () => ({ ...safeEnv }),
+  getAuthStatus: () => authState,
+  runCommand: (_binary, args) => {
+    if (args[0] === "--version") return { ok: true, output: "codex-cli 0.144.0", code: 0 };
+    if (args.join(" ") === "exec --help") return {
+      ok: true,
+      output: "--config --json --sandbox --image --model --skip-git-repo-check",
+      code: 0,
+    };
+    if (args.join(" ") === "exec resume --help") return {
+      ok: true,
+      output: "--config --json --image --model --skip-git-repo-check",
+      code: 0,
+    };
+    return { ok: false, output: "unexpected fixture command", code: 1 };
+  },
+});
+
+assert.strictEqual(validateProvider(provider), provider);
+assert.strictEqual(provider.id, "codex");
+assert.strictEqual(getProvider("codex").id, "codex", "built-in registry exposes Codex lazily");
+assert.strictEqual(provider.label, "OpenAI Codex");
+assert.strictEqual(provider.isAvailable(), true);
+assert.strictEqual(provider.executable(), "/fixture/codex");
+assert.strictEqual(provider.defaultModel(), "gpt-5-codex");
+assert.deepStrictEqual(provider.modelChoices(), ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
+assert.ok(!provider.modelChoices().includes("o4-mini"));
+assert.deepStrictEqual(provider.compatibilityStatus(), {
+  state: "compatible",
+  version: "0.144.0",
+  reason: null,
+});
+
+assert.strictEqual(provider.capabilities.resume.support, "native");
+assert.strictEqual(provider.capabilities.readOnlyMode.support, "native");
+assert.strictEqual(provider.capabilities.effort.support, "native");
+assert.strictEqual(provider.capabilities.imageFlag.support, "native");
+for (const key of ["budget", "worktree", "maxTurns"]) {
+  assert.strictEqual(provider.capabilities[key].support, "unsupported");
+  assert.ok(provider.capabilities[key].reason);
+}
+assert.strictEqual(provider.capabilities.partialStreaming.support, "unsupported");
+assert.strictEqual(provider.capabilities.persistentUtilityStream.support, "unsupported");
+assert.strictEqual(provider.capabilities.preToolHook.support, "native");
+
+const freshContext = deepFreeze({
+  coreInstructions: "STABLE CORE",
+  dynamicContext: "DYNAMIC CONTEXT",
+  userPrompt: "USER SENTINEL",
+  fresh: true,
+  sessionId: "ignored-thread",
+  providerSettings: {
+    model: "gpt-5-codex",
+    effort: "high",
+    permissionMode: "plan",
+    budget: null,
+    worktree: false,
+  },
+  imagePaths: ["/fixture/one.png", "/fixture/two.png"],
+});
+const before = JSON.stringify(freshContext);
+const fresh = validateInvocation(provider.buildMainInvocation(freshContext));
+assert.strictEqual(JSON.stringify(freshContext), before, "frozen run context must not be mutated");
+assert.deepStrictEqual(fresh.args, [
+  "exec",
+  "-c", `developer_instructions=${JSON.stringify("STABLE CORE")}`,
+  "-c", `model_reasoning_effort=${JSON.stringify("high")}`,
+  "--image", "/fixture/one.png", "/fixture/two.png",
+  "--json",
+  "--skip-git-repo-check",
+  "--sandbox", "read-only",
+  "--model", "gpt-5-codex",
+  "DYNAMIC CONTEXT\n\nUSER SENTINEL",
+]);
+assert.deepStrictEqual(fresh.env, safeEnv);
+assert.strictEqual(fresh.stdin, null);
+assert.ok(fresh.parserState.seenUsage instanceof Set);
+assert.ok(!Object.prototype.hasOwnProperty.call(fresh.env, "CLAUDE_CODE_OAUTH_TOKEN"));
+
+function simpleContext(overrides = {}) {
+  return deepFreeze({
+    coreInstructions: "CORE",
+    dynamicContext: "",
+    userPrompt: "PROMPT",
+    providerSettings: { budget: null, worktree: false },
+    ...overrides,
+  });
+}
+
+const resumed = provider.buildMainInvocation(simpleContext({
+  resumeSessionId: "thread-1",
+  providerSettings: { effort: "medium", permissionMode: "plan", budget: null, worktree: false },
+  imagePaths: ["/fixture/resume.png"],
+}));
+assert.deepStrictEqual(resumed.args, [
+  "exec", "resume",
+  "-c", `developer_instructions=${JSON.stringify("CORE")}`,
+  "-c", `model_reasoning_effort=${JSON.stringify("medium")}`,
+  "-c", `sandbox_mode=${JSON.stringify("read-only")}`,
+  "--image", "/fixture/resume.png",
+  "--json",
+  "--skip-git-repo-check",
+  "--model", "gpt-5-codex",
+  "thread-1",
+  "PROMPT",
+]);
+assert.ok(!resumed.args.includes("--sandbox"));
+assert.ok(resumed.args.indexOf("thread-1") > resumed.args.lastIndexOf("--model"));
+
+const directResume = provider.buildMainInvocation(simpleContext({ sessionId: "thread-direct" }));
+assert.ok(directResume.args.includes("--dangerously-bypass-approvals-and-sandbox"));
+assert.ok(directResume.args.indexOf("--dangerously-bypass-approvals-and-sandbox") < directResume.args.indexOf("thread-direct"));
+
+const continued = provider.buildMainInvocation(simpleContext({ continueSession: true, sessionId: "thread-continue" }));
+assert.strictEqual(continued.args[1], "resume");
+assert.ok(continued.args.includes("thread-continue"));
+
+const freshIgnoringSession = provider.buildMainInvocation(simpleContext({ fresh: true, sessionId: "old-thread" }));
+assert.strictEqual(freshIgnoringSession.args[1], "-c");
+assert.ok(!freshIgnoringSession.args.includes("old-thread"));
+
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ continueSession: true })),
+  (error) => error && error.code === "INVALID_PROVIDER_CONTEXT",
+);
+for (const providerSettings of [
+  { budget: 1, worktree: false },
+  { budget: null, worktree: true },
+]) {
+  assert.throws(
+    () => provider.buildMainInvocation(simpleContext({ providerSettings })),
+    (error) => error && error.code === "UNSUPPORTED_PROVIDER_SETTING",
+  );
+}
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ maxTurns: 2 })),
+  (error) => error && error.code === "UNSUPPORTED_PROVIDER_SETTING",
+);
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ voiceStream: true })),
+  (error) => error && error.code === "UNSUPPORTED_PROVIDER_CAPABILITY",
+);
+assert.throws(
+  () => provider.buildMainInvocation(simpleContext({ providerSettings: { effort: "max", budget: null, worktree: false } })),
+  (error) => error && error.code === "UNSUPPORTED_PROVIDER_SETTING",
+);
+assert.throws(
+  () => provider.buildMainInvocation(deepFreeze({ dynamicContext: "only", userPrompt: "raw" })),
+  (error) => error && error.code === "MISSING_CORE_INSTRUCTIONS",
+);
+
+const utility = validateInvocation(provider.buildUtilityInvocation(deepFreeze({
+  coreInstructions: "UTILITY CORE",
+  userPrompt: "UTILITY PROMPT",
+  readOnly: true,
+  tier: "low",
+  outputSchemaPath: "/fixture/schema.json",
+})));
+assert.ok(utility.args.includes("--ephemeral"));
+assert.strictEqual(utility.args[utility.args.indexOf("--model") + 1], "gpt-5.6-luna");
+assert.strictEqual(utility.args[utility.args.indexOf("--output-schema") + 1], "/fixture/schema.json");
+assert.deepStrictEqual(
+  utility.args.slice(utility.args.indexOf("--sandbox"), utility.args.indexOf("--sandbox") + 2),
+  ["--sandbox", "read-only"],
+);
+assert.strictEqual(utility.args.at(-1), "-", "Codex utility invocation reads its protected prompt from stdin");
+assert.strictEqual(utility.stdin, "UTILITY PROMPT");
+assert.ok(!utility.args.includes("UTILITY PROMPT"));
+
+const decoder = provider.createEventDecoder();
+const raw = decoder.push(Buffer.from('{"type":"thread.started","thread_id":"bound-thread"}\n'));
+assert.deepStrictEqual(provider.normalizeEvent(raw[0], fresh.parserState), [{ type: "session", sessionId: "bound-thread" }]);
+
+assert.strictEqual(provider.authStatus().state, "authenticated");
+assert.strictEqual(provider.preflightAuth(), null);
+authState = { state: "unauthenticated", reason: "login required" };
+const authFailure = provider.preflightAuth();
+assert.strictEqual(authFailure.code, "PROVIDER_UNAUTHENTICATED");
+assert.match(authFailure.message, /Codex authentication/i);
+assert.match(provider.authHelp(), /codex_login/);
+
+const missing = createCodexProvider({ hookTransport: false, resolveExecutable: () => null, getAuthStatus: () => ({ state: "not_checked", reason: "missing" }) });
+assert.strictEqual(missing.isAvailable(), false);
+assert.throws(
+  () => missing.buildMainInvocation(simpleContext()),
+  (error) => error && error.code === "NO_AVAILABLE_PROVIDER",
+);
+
+const incompatible = createCodexProvider({
+  hookTransport: false,
+  resolveExecutable: () => "/fixture/old-codex",
+  buildEnv: () => ({ PATH: "/fixture" }),
+  getAuthStatus: () => ({ state: "unknown", reason: "not checked" }),
+  runCommand: (_binary, args) => {
+    if (args[0] === "--version") return { ok: true, output: "codex-cli 0.1.0", code: 0 };
+    if (args.join(" ") === "exec --help") return { ok: true, output: "--json", code: 0 };
+    return { ok: true, output: "--json", code: 0 };
+  },
+});
+assert.strictEqual(incompatible.compatibilityStatus().state, "incompatible");
+
+const source = fs.readFileSync(path.join(__dirname, "core", "providers", "codex.js"), "utf8");
+assert.ok(!source.includes('require("child_process")'), "provider adapter must return invocation data instead of spawning");
+
+console.log("Codex provider OK");