@jskit-ai/assistant-core 0.2.7 → 0.2.9

package/src/server/conversation/codexProvider.js

@@ -1,406 +1,20 @@
-import { createHash, randomUUID } from "node:crypto";
-import { lstat, realpath } from "node:fs/promises";
-import path from "node:path";
+import { CODEX_APP_SERVER_EXECUTION_MODES, CODEX_APP_SERVER_PROCESS_STATE, CODEX_APP_SERVER_PROVIDER_ID, CODEX_APP_SERVER_TRANSPORT, codexAppServerExecutionMode, codexAppServerHelperWorkspaceDir, codexAppServerIsHelper, codexAppServerRuntimeIdentity, codexAppServerTerminalEnvHash, ensureWritablePrivateDirectory, tailTextFile } from "./codexProcess.js";
 import { CodexAppServerJsonRpcClient } from "./codexClient.js";
-import { releaseSupersededCodexRuntime } from "./codexProviderOwner.js";
-import {
-  createCodexAccountReader, codexAuthOutputRequiresReconnect, codexAppServerProjectHookTrustConfig,
-  codexAppServerTextHasControlCharacters, CODEX_APP_SERVER_ACCOUNT_ID_MAX_LENGTH
-} from "./codexConfiguration.js";
-import {
-  CODEX_APP_SERVER_PROCESS_STATE, CODEX_APP_SERVER_TRANSPORT,
-  codexAppServerExecutionMode, codexAppServerHelperWorkspaceDir, codexAppServerIsHelper,
-  codexAppServerRuntimeIdentity, codexAppServerTerminalEnvHash,
-  ensureWritablePrivateDirectory, normalizeCodexAppServerTerminalEnv, tailTextFile
-} from "./codexProcess.js";
-import { assertCodexAuthPreflightReady } from "./codexAuthPreflight.js";
+import { codexAppServerTextHasControlCharacters } from "./codexConfiguration.js";
+import { codexAuthOutputRequiresReconnect, createCodexAccountReader } from "./codexAccountReader.js";
 import { codexAppServerModelCatalogError } from "./codexModelCatalog.js";
-import { prepareCodexHistory } from "./codexHistoryAdapter.js";
 import { createCodexConversationAdapter } from "./providers/codex.js";
-import { exportCodexNativeHistory } from "./codexNativeHistoryExport.js";
-import { retireNativeConversation, readStoppedNativeDatabase } from "./nativeHistoryExport.js";
-import { isRecord, normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { codexAppServerHelperRequestError, createCodexProviderAuth } from "./codexProviderAuth.js";
+import { codexAppServerThreadRequestParams, createCodexProviderThreads, keepCodexThreadParams, resumeCodexThreadAsIs } from "./codexProviderThreads.js";
+import { createCodexProviderInventories } from "./codexProviderInventories.js";
+import { createCodexProviderTurns } from "./codexProviderTurns.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeNullableText as normalizeAgentText } from "./normalize.js";
-import {
-  codexAppServerProviderThreadTurns,
-  codexAppServerProviderTurnItems,
-  codexAppServerProviderTurnClientIds,
-  codexAppServerThreadRawValue,
-  codexAppServerErrorText
-} from "./codexEvents.js";
-
-const CODEX_APP_SERVER_PROVIDER_ID = "codex_app_server";
-const CODEX_APP_SERVER_EXECUTION_MODES = Object.freeze({ HELPER: "helper", INTERACTIVE: "interactive" });
-const codexAppServerHelperAuthError = createCodexAccountReader().error;
+import path from "node:path";
 
-const CODEX_APP_SERVER_INVALID_REQUEST_CODE = -32600;
-const CODEX_APP_SERVER_MODEL_CATALOG_PAGE_LIMIT = 100;
-const CODEX_APP_SERVER_MODEL_CATALOG_MAX_PAGES = 100;
-const CODEX_APP_SERVER_MODEL_CATALOG_MAX_ENTRIES = 1000;
-const CODEX_APP_SERVER_MODEL_CATALOG_MAX_ENTRY_BYTES = 32 * 1024;
-const CODEX_APP_SERVER_MODEL_CATALOG_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
-const CODEX_APP_SERVER_MODEL_CATALOG_MAX_CURSOR_LENGTH = 512;
-const CODEX_APP_SERVER_THREAD_INVENTORY_PAGE_LIMIT = 100;
-const CODEX_APP_SERVER_THREAD_INVENTORY_MAX_PAGES = 100;
-export const CODEX_APP_SERVER_THREAD_INVENTORY_MAX_COUNT = 1000;
-export const CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH = 512;
 const CODEX_APP_SERVER_HELPER_MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
-const CODEX_APP_SERVER_SERVER_INFO_USER_AGENT_MAX_LENGTH = 512;
-const CODEX_APP_SERVER_CHATGPT_REFRESH_METHOD = "account/chatgptAuthTokens/refresh";
-const CODEX_NATIVE_STORAGE_SOURCE_KINDS = ["cli", "vscode", "exec", "appServer", "subAgent", "subAgentReview",
-  "subAgentCompact", "subAgentThreadSpawn", "subAgentOther", "unknown"];
-
-function codexAppServerRequestIsInvalid(error = null, method = "") {
-  const expectedMethod = normalizeAgentText(method);
-  const actualMethod = normalizeAgentText(error?.method);
-  return Number(error?.code) === CODEX_APP_SERVER_INVALID_REQUEST_CODE &&
-    (!expectedMethod || !actualMethod || actualMethod === expectedMethod);
-}
-
-function codexAppServerThreadIsMissing(error = null, threadId = "") {
-  const normalizedThreadId = normalizeAgentText(threadId || "").toLowerCase();
-  if (
-    !normalizedThreadId ||
-    !codexAppServerRequestIsInvalid(error, "thread/read")
-  ) {
-    return false;
-  }
-  // Codex also uses -32600 for unrelated invalid requests, so recovery must
-  // match both the missing-thread wording and the exact durable thread id.
-  const message = normalizeAgentText(error?.message || "").toLowerCase();
-  return [
-    `thread not loaded: ${normalizedThreadId}`,
-    `thread ${normalizedThreadId} not found`,
-    `no rollout found for thread id ${normalizedThreadId}`
-  ].includes(message);
-}
-
-async function retireCodexConversationHistory(provider, binding, {
-  toolHomeSource, beforeDelete, signal, errorPrefix = ""
-} = {}) {
-  const inspect = async () => {
-    const ids = [...new Set([binding.conversationId, ...await provider.listThreadDescendants(binding.conversationId)])].sort();
-    const records = [];
-    for (const conversationId of ids) {
-      let thread;
-      try { thread = codexAppServerThreadRawValue(await provider.readThreadStatus(conversationId)); }
-      catch (error) {
-        // Native thread/read also says "not loaded" after deletion. Only
-        // an exhaustive native inventory can distinguish absence from an
-        // existing unloaded thread, including one moved to another cwd.
-        if (codexAppServerThreadIsMissing(error, conversationId) &&
-            !await provider.nativeThreadExists(conversationId, { signal })) continue;
-        throw error;
-      }
-      if (thread.id !== conversationId || thread.cwd !== binding.workdir ||
-          !["idle", "notLoaded"].includes(thread.status?.type)) {
-        throw new Error("Codex retirement requires an idle native family in the exact saved directory.");
-      }
-      if (thread.historyMode !== "paginated") {
-        throw Object.assign(new Error("Codex native retirement requires paginated history. This unsupported conversation needs operator cleanup."),
-          { code: `${errorPrefix}codex_paginated_history_required` });
-      }
-      const relative = path.isAbsolute(thread.path || "") && toolHomeSource
-        ? path.relative(path.join(toolHomeSource, ".codex"), thread.path) : "";
-      if (thread.path && (!/^(?:sessions|archived_sessions)\//u.test(relative) || !/\.jsonl(?:\.zst)?$/u.test(thread.path))) {
-        throw new Error("Codex returned an unsafe or unknown rollout path.");
-      }
-      const files = [];
-      const plainPath = thread.path?.replace(/\.zst$/u, "");
-      for (const file of plainPath ? [plainPath, `${plainPath}.zst`] : []) {
-        try {
-          const info = await lstat(file);
-          if (!info.isFile() || info.isSymbolicLink() || await realpath(file) !== path.resolve(file)) {
-            throw new Error("Codex rollout is not a regular file at its exact native path.");
-          }
-          files.push({ path: file, inode: info.ino, size: info.size, modified: info.mtimeMs });
-        } catch (error) { if (error.code !== "ENOENT") throw error; }
-      }
-      records.push({ conversationId, workdir: thread.cwd, historyMode: thread.historyMode, ...(files[0] || {}), files,
-        nativePath: thread.path ?? null, status: thread.status.type,
-        ...(Number.isFinite(thread.createdAt) ? { createdAt: new Date(thread.createdAt * 1000).toISOString() } : {}),
-        ...(Number.isFinite(thread.updatedAt) ? { updatedAt: new Date(thread.updatedAt * 1000).toISOString() } : {}) });
-    }
-    return records;
-  };
-  return retireNativeConversation({ binding, inspect, beforeDelete,
-    exportConversation: (id, onRecord) => provider.exportThreadHistory(id, onRecord, { signal }),
-    remove: () => provider.deleteThread(binding.conversationId) });
-}
-
-// Native Codex0.159.1 keeps goals in its separate goals_1.sqlite store.
-// Return its original SQL fields; the host owns stopped conversion eligibility,
-// including rejecting active/blocked/limited goals and resolving SQLite home.
-async function readCodexNativeGoal(databasePath, { threadId, signal } = {}) {
-  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(threadId || "") ||
-      path.basename(databasePath || "") !== "goals_1.sqlite") {
-    throw new TypeError("Codex goal inspection requires its exact thread ID and supported goals_1.sqlite path.");
-  }
-  return readStoppedNativeDatabase(databasePath, database => {
-    const columns = database.prepare("PRAGMA table_info(thread_goals)").all();
-    const text = ["thread_id", "goal_id", "objective", "status"];
-    const integers = ["token_budget", "tokens_used", "time_used_seconds", "created_at_ms", "updated_at_ms"];
-    if (!columns.some(column => column.name === "thread_id" && column.pk === 1) ||
-        text.some(name => !columns.some(column => column.name === name && column.type === "TEXT")) ||
-        integers.some(name => !columns.some(column => column.name === name && column.type === "INTEGER"))) {
-      throw new Error("Codex's saved native goal schema is unsupported; no history was changed.");
-    }
-    const rows = database.prepare(`SELECT thread_id, goal_id, objective, status, token_budget,
-      tokens_used, time_used_seconds, created_at_ms, updated_at_ms
-      FROM thread_goals WHERE thread_id = ? LIMIT 2`).all(threadId);
-    if (!rows.length) return null;
-    const row = rows[0];
-    if (rows.length !== 1 || row.thread_id !== threadId ||
-        !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(row.goal_id || "") ||
-        typeof row.objective !== "string" ||
-        !["active", "paused", "blocked", "usage_limited", "budget_limited", "complete"].includes(row.status) ||
-        row.token_budget !== null && (!Number.isSafeInteger(row.token_budget) || row.token_budget < 0) ||
-        ["tokens_used", "time_used_seconds", "created_at_ms", "updated_at_ms"].some(key =>
-          !Number.isSafeInteger(row[key]) || row[key] < 0)) {
-      throw new Error("Codex's saved native goal is unsupported or ambiguous; no history was changed.");
-    }
-    return row;
-  }, { signal });
-}
-
-async function codexAppServerThreadHasReadableHistory(provider = null, threadId = "") {
-  const normalizedThreadId = normalizeAgentText(threadId);
-  if (!normalizedThreadId || typeof provider?.readThread !== "function") {
-    return false;
-  }
-  try {
-    await provider.readThread(normalizedThreadId);
-    return true;
-  } catch (error) {
-    if (codexAppServerRequestIsInvalid(error, "thread/read")) {
-      return false;
-    }
-    throw error;
-  }
-}
-
-// The caller has already checked the requested thread against its current
-// conversation. History can confirm this exact authored input, never infer it
-// from an assistant item or from a failed read.
-async function inspectCodexAppServerMessageAdmission({ provider, threadId, messageId } = {}) {
-  try {
-    const thread = await provider.readThread(threadId);
-    const accepted = codexAppServerProviderThreadTurns(thread).find((turn) =>
-      codexAppServerProviderTurnItems(turn).some((item) => item.type === "userMessage" &&
-        codexAppServerProviderTurnClientIds({ items: [item] }).includes(messageId)));
-    return { ok: true, admission: accepted ? "accepted" : "unknown", messageId, threadId,
-      turnId: normalizeAgentText(accepted?.id) };
-  } catch {
-    return { ok: true, admission: "unknown", messageId, threadId };
-  }
-}
 
-// Native result validation only. The caller owns any interruption, absence
-// proof and durable cleanup receipt.
-async function deleteCodexAppServerThread({ provider, threadId } = {}) {
-  const result = await provider.deleteThread(threadId);
-  if (!isRecord(result)) {
-    const error = new Error("Codex app-server returned an invalid thread deletion result.");
-    error.code = "codex_helper_thread_delete_unconfirmed";
-    throw error;
-  }
-  return result;
-}
-
-// The caller persists cleanup ownership before this operation and removes that
-// receipt only after success. Native failure details remain local to that owner.
-async function deleteCodexAppServerHelperThread({ provider, threadId, turnId = "" } = {}) {
-  let interruptError = null;
-  if (turnId) {
-    if (typeof provider?.interruptTurn === "function") {
-      try {
-        await provider.interruptTurn(threadId, turnId);
-      } catch (error) {
-        interruptError = error;
-      }
-    } else {
-      interruptError = new Error("Codex provider cannot interrupt an active helper turn.");
-    }
-  }
-  if (typeof provider?.deleteThread !== "function") {
-    return { ok: false, error: new Error("Codex provider cannot delete a helper thread."), interruptError };
-  }
-  try {
-    const result = await deleteCodexAppServerThread({ provider, threadId });
-    return {
-      deleted: true,
-      interrupted: Boolean(turnId) && !interruptError,
-      ok: true,
-      result,
-      status: "deleted",
-      threadId,
-      turnId,
-      interruptError
-    };
-  } catch (error) {
-    let absent = false;
-    if (codexAppServerRequestIsInvalid(error, "thread/delete")) {
-      try {
-        absent = !await codexAppServerThreadHasReadableHistory(provider, threadId);
-      } catch {
-        absent = false;
-      }
-    }
-    if (absent) {
-      return {
-        deleted: false,
-        interrupted: Boolean(turnId) && !interruptError,
-        ok: true,
-        status: "notFound",
-        threadId,
-        turnId,
-        interruptError
-      };
-    }
-    return { ok: false, error, interruptError };
-  }
-}
-
-function codexApplicationToolConfiguration(tools) {
-  const dynamicTools = (tools?.schemas || []).map(({ function: tool }) => ({
-    type: "function", name: tool.name, description: tool.description, inputSchema: tool.parameters
-  }));
-  return { dynamicTools, toolSchemaIdentity: createHash("sha256").update(JSON.stringify(dynamicTools)).digest("hex") };
-}
-
-function assertCodexApplicationToolSchemaIdentity(threadId, savedIdentity, toolSchemaIdentity) {
-  if (threadId && (savedIdentity || codexApplicationToolConfiguration().toolSchemaIdentity) !== toolSchemaIdentity) {
-    throw new Error("This Codex conversation was created with different application tool entry points. Start a new conversation to enable or remove application tools.");
-  }
-}
-
-/** Retained thread selection keeps observation ahead of a resume that can start work. */
-async function ensureCodexAppServerThread({
-  observeThread,
-  provider,
-  settings,
-  projectHooks = false,
-  identity,
-  applicationTools,
-  providerReady,
-  workdir = "",
-  onStage = () => {}
-} = {}) {
-  if (typeof observeThread !== "function") {
-    throw new TypeError("Main Codex threads require an observer before they can resume.");
-  }
-  const normalizedWorkdir = normalizeAgentText(workdir);
-  let stageStartedAt = Date.now();
-  const availability = typeof provider.ensureAvailable === "function"
-    ? await provider.ensureAvailable()
-    : null;
-  const appServerRuntime = availability?.runtime || await provider.ensureRuntime();
-  onStage({ durationMs: Date.now() - stageStartedAt, stage: "runtime" });
-  const existingThreadId = identity.read(normalizedWorkdir);
-  const toolConfiguration = applicationTools ? codexApplicationToolConfiguration(applicationTools) : null;
-  if (toolConfiguration) {
-    if (typeof identity.readToolSchemaIdentity !== "function") throw new TypeError("Bound Codex application tools require the original schema identity reader and writer.");
-    assertCodexApplicationToolSchemaIdentity(existingThreadId, await identity.readToolSchemaIdentity(normalizedWorkdir), toolConfiguration.toolSchemaIdentity);
-  }
-  let config = null;
-  if (projectHooks) {
-    stageStartedAt = Date.now();
-    config = await codexAppServerProjectHookTrustConfig(provider, normalizedWorkdir);
-    onStage({ durationMs: Date.now() - stageStartedAt, stage: "hook-config" });
-  }
-  let { threadSettings, threadStartSettings } = await settings(normalizedWorkdir, config);
-  if (toolConfiguration) {
-    threadSettings = { ...threadSettings, dynamicTools: toolConfiguration.dynamicTools };
-    threadStartSettings = { ...threadStartSettings, dynamicTools: toolConfiguration.dynamicTools };
-  }
-  if (providerReady) await providerReady({ provider, threadId: existingThreadId });
-  let thread = null;
-  stageStartedAt = Date.now();
-  if (existingThreadId) {
-    if (identity.pauseGoal) {
-      const { goal } = await provider.readGoal(existingThreadId);
-      if (goal?.status === "active") await provider.setGoalStatus(existingThreadId, "paused");
-    }
-    // Resuming can immediately start an active goal before the RPC returns.
-    await observeThread(existingThreadId);
-    thread = await provider.resumeThread(existingThreadId, threadSettings);
-    if (identity.pauseGoal) {
-      await identity.clearPause();
-    }
-  } else {
-    thread = await provider.startThread(threadStartSettings);
-  }
-  onStage({ durationMs: Date.now() - stageStartedAt, stage: existingThreadId ? "resume" : "start" });
-  const threadId = normalizeAgentText(thread.id || existingThreadId);
-  if (!threadId) {
-    throw new Error("Codex app-server did not return a thread id.");
-  }
-  stageStartedAt = Date.now();
-  const recorded = await identity.write({ appServerRuntime, threadId, workdir: normalizedWorkdir,
-    ...(toolConfiguration ? { toolSchemaIdentity: toolConfiguration.toolSchemaIdentity } : {}) });
-  // The session no longer uses the runtime directory it recorded before (an
-  // earlier sign-in's). Releasing it is cleanup: a failure keeps the directory.
-  const superseded = normalizeAgentText(recorded?.supersededRuntimeDir);
-  if (superseded) await releaseSupersededCodexRuntime(superseded).catch(() => null);
-  if (providerReady) await providerReady({ provider, threadId });
-  onStage({ durationMs: Date.now() - stageStartedAt, stage: "identity-metadata" });
-  return {
-    appServerRuntime,
-    thread,
-    threadId
-  };
-}
-
-function codexAppServerHelperLoginParams(auth = {}, errorPrefix = "") {
-  if (auth.authMode === "chatgpt") {
-    return {
-      accessToken: auth.accessToken,
-      chatgptAccountId: auth.accountId,
-      chatgptPlanType: auth.planType || null,
-      type: "chatgptAuthTokens"
-    };
-  }
-  if (auth.authMode === "apiKey") {
-    return {
-      apiKey: auth.apiKey,
-      type: "apiKey"
-    };
-  }
-  throw codexAppServerHelperAuthError(
-    `${errorPrefix}codex_helper_auth_invalid`,
-    "The selected Codex authentication mode is unsupported. Reconnect Codex and retry."
-  );
-}
-
-function codexAppServerHelperLoginResponseType(auth = {}) {
-  return auth.authMode === "chatgpt" ? "chatgptAuthTokens" : "apiKey";
-}
-
-function codexAppServerHelperAccountType(auth = {}) {
-  return auth.authMode === "chatgpt" ? "chatgpt" : "apiKey";
-}
-
-function codexAppServerHelperRequestError(error = null, reason = "", errorPrefix = "") {
-  if (
-    error?.name === "AbortError" ||
-    error?.code === "ABORT_ERR" ||
-    (typeof error?.code === "string" && error.code.startsWith(`${errorPrefix}codex_helper_`)) ||
-    error?.code === `${errorPrefix}codex_model_catalog_invalid`
-  ) {
-    return error;
-  }
-  const failure = new Error("Codex isolated helper execution failed. Retry the task.");
-  failure.code = `${errorPrefix}codex_helper_provider_request_failed`;
-  const providerCode = Number(error?.code);
-  if (Number.isSafeInteger(providerCode)) {
-    failure.providerCode = providerCode;
-  }
-  const normalizedReason = normalizeAgentText(reason);
-  if (normalizedReason && normalizedReason.length <= 128) {
-    failure.operation = normalizedReason;
-  }
-  return failure;
-}
+const CODEX_APP_SERVER_SERVER_INFO_USER_AGENT_MAX_LENGTH = 512;
 
 function normalizeCodexAppServerInfo(initializeResult = null) {
   if (!isRecord(initializeResult)) {
@@ -420,305 +34,39 @@ function normalizeCodexAppServerInfo(initializeResult = null) {
   });
 }
 
-function codexAppServerEndpointForTarget(endpoint = "") {
-  const normalizedEndpoint = normalizeAgentText(endpoint);
-  if (!normalizedEndpoint) {
-    return "";
-  }
-  return normalizedEndpoint;
-}
-
-function codexAppServerThreadRequestParams(params = {}, threadEnv = {}) {
-  const source = isRecord(params) ? params : {};
-  const config = isRecord(source.config) ? source.config : {};
-  if (Object.hasOwn(config, "shell_environment_policy")) {
-    return source;
-  }
-  return {
-    ...source,
-    config: {
-      ...config,
-      shell_environment_policy: {
-        inherit: "none",
-        set: normalizeCodexAppServerTerminalEnv(threadEnv)
-      }
-    }
-  };
-}
-
-function codexTextInput(text = "") {
-  return {
-    text: String(text ?? ""),
-    text_elements: [],
-    type: "text"
-  };
-}
-
-function codexLocalImageInput(attachments = []) {
-  return attachments
-    .filter((attachment) => attachment.contentType?.startsWith("image/"))
-    .map((attachment) => ({ type: "localImage", path: attachment.path }));
-}
-
-async function sendCodexAppServerPrompt({
-  attachments = [],
-  clientUserMessageId = "",
-  outputSchema = null,
-  provider,
-  prompt = "",
-  threadId = "",
-  readOnly = false
-} = {}, authorized = {}) {
-  const authoredInput = String(prompt ?? "");
-  const preparedInput = authorized.preparedInput;
-  if (preparedInput === undefined && !authoredInput.trim()) {
-    throw new Error("Codex app-server prompt is empty.");
-  }
-  const input = preparedInput === undefined ? [authoredInput, ...codexLocalImageInput(attachments)] : preparedInput;
-  const turnSettings = {
-    ...authorized.turnSettings,
-    ...(readOnly
-      ? {
-          sandboxPolicy: {
-            networkAccess: false,
-            type: "readOnly"
-          }
-        }
-      : {}),
-    ...(normalizeAgentText(clientUserMessageId)
-      ? { clientUserMessageId: normalizeAgentText(clientUserMessageId) }
-      : {})
-  };
-  if (outputSchema && typeof outputSchema === "object" && !Array.isArray(outputSchema)) {
-    turnSettings.outputSchema = outputSchema;
-  }
-  const turn = await provider.sendTurn(threadId, input, turnSettings);
-  return {
-    input,
-    turn
-  };
-}
-
-function codexTurnInput(input = []) {
-  const values = Array.isArray(input) ? input : [input];
-  return values.map((item) => {
-    if (isRecord(item) && item.type === "localImage" && typeof item.path === "string") {
-      return { type: "localImage", path: item.path };
-    }
-    if (isRecord(item) && item.type === "image" && typeof item.url === "string") {
-      return { type: "image", url: item.url };
-    }
-    if (isRecord(item) && item.type === "text") {
-      return codexTextInput(item.text);
-    }
-    return codexTextInput(item);
-  });
-}
-
-function shellQuote(value = "") {
-  const text = String(value ?? "");
-  if (/^[A-Za-z0-9_./:=@+-]+$/u.test(text)) {
-    return text;
-  }
-  return `'${text.replaceAll("'", "'\"'\"'")}'`;
-}
-
-function codexControlProbeCommand(keys, marker) {
-  const source = [
-    "const {createHash}=require('node:crypto');",
-    `const keys=${JSON.stringify(keys)};`,
-    `process.stdout.write(${JSON.stringify(marker)}+createHash('sha256').update(JSON.stringify(keys.map(key=>[key,process.env[key]]))).digest('hex'))`
-  ].join("");
-  return `${shellQuote(process.execPath)} -e ${shellQuote(source)}`;
-}
+const CODEX_APP_SERVER_CHATGPT_REFRESH_METHOD = "account/chatgptAuthTokens/refresh";
 
-function codexCliResumeCommand({
-  codexCommand = "",
-  endpoint = "",
-  threadId = ""
-} = {}) {
-  const normalizedEndpoint = codexAppServerEndpointForTarget(endpoint);
-  const resolvedCodexCommand = normalizeAgentText(codexCommand) || "codex";
-  const normalizedThreadId = normalizeAgentText(threadId);
-  if (!normalizedEndpoint) {
-    throw new Error("Codex app-server endpoint is required for the native CLI command.");
-  }
-  if (!normalizedThreadId) {
-    throw new Error("Codex thread id is required for the native CLI command.");
-  }
-  const argv = [
-    resolvedCodexCommand,
-    "-c",
-    "check_for_update_on_startup=false",
-    "--remote",
-    normalizedEndpoint,
-    "resume",
-    normalizedThreadId
-  ];
-  return {
-    argv,
-    command: argv.map(shellQuote).join(" ")
-  };
-}
+// Option callbacks an application leaves out.
+function readNoInstructions() {}
 
-function codexAppServerThreadInventoryError(errorCode, label, detail) {
-  const error = new Error(`Codex ${label} thread inventory ${detail}.`);
-  error.code = errorCode;
-  return error;
+function keepThreadEnvironment(environment) {
+  return environment;
 }
 
-// Why a listed inventory entry is refused, or "" for a valid thread.
-function codexAppServerThreadInventoryRefusal(entry, threadId, { cwd, verifyCwd }) {
-  if (!isRecord(entry)) return "listed an entry that is not a thread";
-  if (!threadId) return "listed a thread without an id";
-  if (threadId.length > CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH) {
-    return `listed a thread id longer than ${CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH} characters`;
-  }
-  if (codexAppServerTextHasControlCharacters(threadId)) return "listed a thread id with control characters";
-  if (verifyCwd && normalizeAgentText(entry.cwd) !== cwd) return `listed thread ${threadId} outside the requested directory`;
-  return "";
-}
+function prepareNoThreadResume() {}
 
-async function listBoundedCodexAppServerThreadIds({
-  ancestorThreadId = "",
-  archived = false,
-  client,
-  cwd = "",
-  errorCode = "",
-  findThreadId = "",
-  label = "",
-  requestLabel = "",
-  runRequest,
-  signal = null,
-  sourceKinds = ["appServer"],
-  state,
-  verifyCwd = false
-} = {}) {
-  const seenCursors = new Set();
-  let cursor = "";
-  for (let page = 0; page < CODEX_APP_SERVER_THREAD_INVENTORY_MAX_PAGES; page += 1) {
-    if (cursor && seenCursors.has(cursor)) {
-      throw codexAppServerThreadInventoryError(
-        errorCode,
-        label,
-        "repeated a pagination cursor"
-      );
-    }
-    if (cursor) {
-      seenCursors.add(cursor);
-    }
-    const response = await runRequest(
-      () => client.request("thread/list", {
-        archived,
-        ...(cursor ? { cursor } : {}),
-        ...(ancestorThreadId ? { ancestorThreadId } : cwd ? { cwd } : {}),
-        limit: CODEX_APP_SERVER_THREAD_INVENTORY_PAGE_LIMIT,
-        modelProviders: [],
-        sourceKinds,
-        useStateDbOnly: false
-      }, { signal }),
-      requestLabel
-    );
-    if (!Array.isArray(response?.data) || response.data.length > CODEX_APP_SERVER_THREAD_INVENTORY_PAGE_LIMIT) {
-      throw codexAppServerThreadInventoryError(errorCode, label, "returned a malformed page");
-    }
-    // Only thread ids are retained, so only they are bounded. A search for one
-    // thread retains none and is bounded by the page limit alone.
-    if (!findThreadId && state.entryCount + response.data.length > CODEX_APP_SERVER_THREAD_INVENTORY_MAX_COUNT) {
-      throw codexAppServerThreadInventoryError(errorCode, label,
-        `exceeded its ${CODEX_APP_SERVER_THREAD_INVENTORY_MAX_COUNT}-thread limit`);
-    }
-    for (const entry of response.data) {
-      const threadId = isRecord(entry) ? normalizeAgentText(entry.id) : "";
-      const refusal = codexAppServerThreadInventoryRefusal(entry, threadId, { cwd, verifyCwd });
-      if (refusal) {
-        throw codexAppServerThreadInventoryError(errorCode, label, refusal);
-      }
-      if (findThreadId) {
-        if (threadId === findThreadId) {
-          state.found = true;
-          return state;
-        }
-        continue;
-      }
-      state.entryCount += 1;
-      state.threadIds.add(threadId);
-    }
-    const nextCursor = response.nextCursor === undefined || response.nextCursor === null || response.nextCursor === ""
-      ? ""
-      : typeof response.nextCursor === "string"
-        ? response.nextCursor.trim()
-        : null;
-    if (
-      nextCursor === null ||
-      nextCursor.length > CODEX_APP_SERVER_MODEL_CATALOG_MAX_CURSOR_LENGTH ||
-      (nextCursor && seenCursors.has(nextCursor))
-    ) {
-      throw codexAppServerThreadInventoryError(
-        errorCode,
-        label,
-        "returned an invalid pagination cursor"
-      );
-    }
-    if (!nextCursor) {
-      return state;
-    }
-    cursor = nextCursor;
-  }
-  throw codexAppServerThreadInventoryError(
-    errorCode,
-    label,
-    "exceeded its page limit"
-  );
-}
-
-function codexPlanUsage(limits = {}) {
-  if (limits?.limitId && limits.limitId !== "codex") return { status: "unavailable", windows: [], checkedAt: Date.now() };
-  const windows = ["primary", "secondary"].flatMap((id) => {
-    const value = limits?.[id];
-    if (typeof value?.usedPercent !== "number" || !Number.isFinite(value.usedPercent) || value.usedPercent < 0) return [];
-    return [{
-      id,
-      remainingPercent: Math.max(0, 100 - Math.min(100, value.usedPercent)),
-      windowDurationMins: Number.isInteger(value.windowDurationMins) && value.windowDurationMins > 0 ? value.windowDurationMins : null,
-      resetsAt: Number.isSafeInteger(value.resetsAt) && value.resetsAt > 0 ? value.resetsAt : null
-    }];
-  });
-  return { status: windows.length ? "available" : "unavailable", windows, checkedAt: Date.now() };
-}
+function logNothing() {}
 
-function normalizeAgentThread(value = {}) {
-  const thread = value && typeof value === "object" && !Array.isArray(value) ? value : {};
-  return {
-    id: normalizeAgentText(thread.id || thread.threadId),
-    provider: normalizeAgentText(thread.provider),
-    raw: thread.raw || thread
-  };
-}
+function reportNoObservationLoss() {}
 
-function normalizeAgentTurn(value = {}) {
-  const turn = value && typeof value === "object" && !Array.isArray(value) ? value : {};
-  return {
-    id: normalizeAgentText(turn.id || turn.turnId),
-    provider: normalizeAgentText(turn.provider),
-    raw: turn.raw || turn,
-    status: normalizeAgentText(turn.status || turn.raw?.status)
-  };
-}
+function closeNothing() {}
 
-// The one reading of a sendTurn delivery. Its turn is already normalized; the
-// provider's own error stays on the raw native turn.
-function codexAppServerDeliveredTurn(delivery = {}) {
-  const turn = delivery?.turn || {};
-  return {
-    turnId: normalizeAgentText(turn.id),
-    status: normalizeAgentText(turn.status || turn.raw?.status),
-    error: codexAppServerErrorText(turn.raw?.error || turn.response?.turn?.error || turn.error)
-  };
+function runDirectly(operation) {
+  return operation();
 }
 
+/**
+ * One account's connection to its native Codex app-server: the runtime it ensures, the client it opens, the
+ * notifications it publishes and the server requests it routes. Its auth, turns, threads and inventories are
+ * composed from their own modules; their operations are this provider's members.
+ */
 export class CodexAppServerAgentProvider {
-  constructor(options = {}, host = {}) {
+  /**
+   * @param {object} options The provider options: execution mode, account selection and the application's
+   *   thread callbacks.
+   * @param {object} host The native host: credentials, runtime, launch parameters, execution and configuration.
+   */
+  constructor(options, host) {
     this.host = host;
     this.credentials = host.credentials;
     this.configuration = {
@@ -732,9 +80,6 @@ export class CodexAppServerAgentProvider {
     this.errorPrefix = this.configuration.errorPrefix;
     this.accountReader = createCodexAccountReader({ errorPrefix: this.errorPrefix, ...this.configuration.accountReader });
     this.modelCatalogError = (message) => codexAppServerModelCatalogError(message, this.errorPrefix);
-    this.planUsage = null;
-    this.planUsagePending = null;
-    this.planUsageAuthGeneration = 0;
     this.availabilityPromise = null;
     this.stale = false;
     this.options = options;
@@ -743,48 +88,93 @@ export class CodexAppServerAgentProvider {
     this.connectionGeneration = 0;
     this.notificationSubscribers = new Set();
     this.settingsWaiters = new Set();
-    this.helperAuth = null;
-    this.helperAuthBlocked = false;
     this.initializeResult = null;
     this.runtime = null;
     this.runtimeStopOwner = null;
     this.runtimePromise = null;
     this.serverRequestHandler = null;
     this.threadRequestHandlers = new Map();
+
+    const auth = createCodexProviderAuth({ provider: this });
+    const turns = createCodexProviderTurns({ provider: this });
+    const threads = createCodexProviderThreads({ provider: this });
+    const inventories = createCodexProviderInventories({ provider: this });
+    this.auth = auth;
+    this.turns = turns;
+
+    const {
+      readInstructions = readNoInstructions,
+      prepareThreadEnvironment = keepThreadEnvironment,
+      prepareThreadParams = keepCodexThreadParams,
+      prepareThreadResumeParams = prepareNoThreadResume,
+      beforeResumeThread = resumeCodexThreadAsIs
+    } = options;
+    const { log = logNothing } = host;
     this.conversationRuntime = createCodexConversationAdapter({
-      readInstructions: (params, threadId) => this.options.readInstructions?.(params, threadId),
+      readInstructions: (params, threadId) => readInstructions(params, threadId),
       client: () => this.activeClient(),
       runtime: () => this.runtime,
       runRequest: (run, reason) => this.runRequest(run, reason),
       timeoutMs: options.threadControlTimeoutMs,
       environment: options.threadEnv,
-      prepareEnvironment: (environment) => this.options.prepareThreadEnvironment?.(environment) || environment,
-      prepareParameters: (params) => this.options.prepareThreadParams?.(params),
-      prepareResume: (id, params, context) => this.options.prepareThreadResumeParams?.(id, params, context),
-      beforeResume: (id) => this.options.beforeResumeThread?.(id),
+      prepareEnvironment: (environment) => prepareThreadEnvironment(environment) || environment,
+      prepareParameters: (params) => prepareThreadParams(params),
+      prepareResume: (id, params, context) => prepareThreadResumeParams(id, params, context),
+      beforeResume: (id) => beforeResumeThread(id),
       prepareHistory: (params, client, context) => this.withHistoryAdapter(params, client, context),
       threadParameters: codexAppServerThreadRequestParams,
-      verifyEnvironment: (...args) => this.#verifyThreadEnvironment(...args),
-      recordInterruption: (threadId, turnId) => {
-        const key = JSON.stringify([threadId, turnId]);
-        this.interruptedTurns.set(key, this.interruptedTurns.get(key) || "control_reconfiguration");
-      },
-      onRecoveryFailure: (id) => {
-        const probe = this.threadControlProbes.get(id);
-        if (probe && !probe.verified) {
-          this.threadControlProbes.delete(id);
-          for (const pending of probe.pending) this.publishNotification(pending);
-        }
-      },
+      verifyEnvironment: turns.verifyThreadEnvironment,
+      recordInterruption: turns.recordInterruption,
+      onRecoveryFailure: turns.abandonControlProbe,
       publishGoal: (threadId, goal) => this.publishNotification({ method: "thread/goal/updated", params: { threadId, goal } }),
-      log: (event, fields, context) => host.log?.(event, fields, {
-        ...context, connectionGeneration: this.connectionGeneration
-      })
+      log: (event, fields, context) => log(event, fields, { ...context, connectionGeneration: this.connectionGeneration })
     });
-    this.threadControlProbes = new Map();
-    this.commandExecutions = new Map();
-    this.interruptedTurns = new Map();
-    this.commandStopFailure = null;
+
+    this.selectedHelperAuth = auth.selectedHelperAuth;
+    this.assertHelperAccountIdentityCurrent = auth.assertHelperAccountIdentityCurrent;
+    this.authenticateHelperClient = auth.authenticateHelperClient;
+    this.refreshHelperChatgptAuth = auth.refreshHelperChatgptAuth;
+    this.preflightAuth = auth.preflightAuth;
+    this.assertRuntimeAuthReady = auth.assertRuntimeAuthReady;
+    this.markReconnectRequired = auth.markReconnectRequired;
+    this.readPlanUsage = auth.readPlanUsage;
+
+    this.sendTurn = turns.sendTurn;
+    this.steerTurn = turns.steerTurn;
+    this.interruptionOutcome = turns.interruptionOutcome;
+    this.interruptTurn = turns.interruptTurn;
+    this.nativeCliResumeCommand = turns.nativeCliResumeCommand;
+    this.isControlProbeTurn = turns.isControlProbeTurn;
+    this.stopThreadForObservationLoss = turns.stopThreadForObservationLoss;
+
+    this.startThread = threads.startThread;
+    this.resumeThread = threads.resumeThread;
+    this.withHistoryAdapter = threads.withHistoryAdapter;
+    this.withThreadEnvironment = threads.withThreadEnvironment;
+    this.ensureThreadControls = threads.ensureThreadControls;
+    this.readGoal = threads.readGoal;
+    this.updateThreadSettings = threads.updateThreadSettings;
+    this.setGoal = threads.setGoal;
+    this.setGoalStatus = threads.setGoalStatus;
+    this.clearGoal = threads.clearGoal;
+    this.readThread = threads.readThread;
+    this.readThreadStatus = threads.readThreadStatus;
+    this.listThreadTurns = threads.listThreadTurns;
+    this.exportThreadHistory = threads.exportThreadHistory;
+    this.unsubscribeThread = threads.unsubscribeThread;
+    this.deleteThread = threads.deleteThread;
+
+    this.listLoadedThreads = inventories.listLoadedThreads;
+    this.listAppServerThreadsForCwd = inventories.listAppServerThreadsForCwd;
+    this.listThreadDescendants = inventories.listThreadDescendants;
+    this.listNativeThreadsForCwd = inventories.listNativeThreadsForCwd;
+    this.nativeThreadExists = inventories.nativeThreadExists;
+    this.listHelperThreads = inventories.listHelperThreads;
+    this.listModels = inventories.listModels;
+    this.readConfig = inventories.readConfig;
+    this.trustProject = inventories.trustProject;
+    this.listHooks = inventories.listHooks;
+    this.writeHookTrustState = inventories.writeHookTrustState;
   }
 
   get threadEnvironments() { return this.conversationRuntime.threadEnvironments; }
@@ -795,123 +185,25 @@ export class CodexAppServerAgentProvider {
     return codexAppServerIsHelper(this.options);
   }
 
-  async selectedHelperAuth() {
-    if (!this.isHelperProvider()) {
-      return null;
-    }
-    if (this.host.parameters.providerHome) {
-      return { identitySignature: await this.credentials.identity(this.host.parameters) };
-    }
-    return this.accountReader.readSelected(this.options);
+  currentConnectionGeneration() {
+    return this.connectionGeneration;
   }
 
-  async assertHelperAccountIdentityCurrent() {
-    if (!this.isHelperProvider() || !this.helperAuth) {
-      return;
-    }
-    if (this.helperAuthBlocked) {
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
-      );
-    }
-    const current = await this.selectedHelperAuth();
-    if (current.identitySignature !== this.helperAuth.identitySignature) {
-      this.helperAuthBlocked = true;
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
-      );
-    }
+  currentServerInfo() {
+    return this.initializeResult;
   }
 
-  async authenticateHelperClient(client, runtime = {}) {
-    if (!this.isHelperProvider()) {
-      return null;
-    }
-    const auth = await this.selectedHelperAuth();
-    if (
-      !runtime.accountIdentitySignature ||
-      auth.identitySignature !== runtime.accountIdentitySignature
-    ) {
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed while helper execution was starting. Retry the task."
-      );
-    }
-    this.helperAuth = auth;
-    this.helperAuthBlocked = false;
-    if (this.host.parameters.providerHome) return auth;
-    try {
-      const login = await client.request(
-        "account/login/start",
-        codexAppServerHelperLoginParams(auth, this.errorPrefix)
-      );
-      if (normalizeAgentText(login?.type) !== codexAppServerHelperLoginResponseType(auth)) {
-        throw new Error("invalid login response");
-      }
-      const account = await client.request("account/read", {
-        refreshToken: false
-      });
-      if (
-        account?.requiresOpenaiAuth !== true ||
-        normalizeAgentText(account?.account?.type) !== codexAppServerHelperAccountType(auth)
-      ) {
-        throw new Error("invalid account response");
-      }
-      return auth;
-    } catch {
-      this.helperAuth = null;
-      this.helperAuthBlocked = true;
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_unavailable`,
-        "Codex could not activate the selected account for isolated helper work. Reconnect Codex and retry."
-      );
-    }
+  isAvailable() {
+    return Boolean(this.client?.isOpen() && this.runtime);
   }
 
-  async refreshHelperChatgptAuth(params = {}) {
-    const currentAuth = this.helperAuth;
-    const previousAccountId = params.previousAccountId;
-    if (
-      !this.isHelperProvider() ||
-      currentAuth?.authMode !== "chatgpt" ||
-      params.reason !== "unauthorized" ||
-      typeof previousAccountId !== "string" ||
-      previousAccountId.length === 0 ||
-      previousAccountId.length > CODEX_APP_SERVER_ACCOUNT_ID_MAX_LENGTH ||
-      previousAccountId !== currentAuth.accountId
-    ) {
-      this.helperAuthBlocked = true;
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_refresh_rejected`,
-        "Codex helper authentication refresh was rejected. Reconnect Codex and retry."
-      );
-    }
-    const refreshed = await this.selectedHelperAuth();
-    if (
-      refreshed.authMode !== "chatgpt" ||
-      refreshed.identitySignature !== currentAuth.identitySignature
-    ) {
-      this.helperAuthBlocked = true;
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_changed`,
-        "The selected Codex account changed during helper work. Retry the task with the current account."
-      );
-    }
-    if (refreshed.secretSignature === currentAuth.secretSignature) {
-      this.helperAuthBlocked = true;
-      throw this.accountReader.error(
-        `${this.errorPrefix}codex_helper_auth_refresh_pending`,
-        "The selected Codex account has not produced a newer access token yet. Reconnect Codex and retry."
-      );
+  subscribe(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Codex app-server observer must be a function.");
     }
-    this.helperAuth = refreshed;
-    return {
-      accessToken: refreshed.accessToken,
-      chatgptAccountId: refreshed.accountId,
-      chatgptPlanType: refreshed.planType || null
-    };
+    // Observation belongs to this provider, not one replaceable socket.
+    this.notificationSubscribers.add(callback);
+    return () => this.notificationSubscribers.delete(callback);
   }
 
   async handleServerRequest(request = {}, sourceClient = this.client) {
@@ -935,7 +227,7 @@ export class CodexAppServerAgentProvider {
       }
       return threadHandler.handler(request);
     }
-    if (typeof this.serverRequestHandler === "function") {
+    if (this.serverRequestHandler) {
       return this.serverRequestHandler(request);
     }
     const error = new Error("Codex app-server request is not supported by this client.");
@@ -958,10 +250,12 @@ export class CodexAppServerAgentProvider {
     }
   }
 
-  // An account change leaves a runtime that is still working on the
-  // credentials it started with. Codex reads them once, so this provider
-  // finishes its running turn on them and then stops; it never re-checks,
-  // replaces or restarts its runtime, and never marks the new account invalid.
+  /**
+   * An account change leaves a runtime that is still working on the
+   * credentials it started with. Codex reads them once, so this provider
+   * finishes its running turn on them and then stops; it never re-checks,
+   * replaces or restarts its runtime, and never marks the new account invalid.
+   */
   markStale() {
     this.stale = true;
   }
@@ -992,63 +286,6 @@ export class CodexAppServerAgentProvider {
     return this.runtime;
   }
 
-  async preflightAuth(reason = "codex-auth-preflight", modelProviderId = "") {
-    if (await this.options.prepareAuth?.(modelProviderId) === "external") {
-      await this.assertRuntimeAuthReady(reason);
-      return;
-    }
-    if (this.options.modelProviderId && this.options.modelProviderId !== "openai") {
-      await this.credentials.assertCurrent("");
-      return;
-    }
-    await this.assertRuntimeAuthReady(reason);
-    try {
-      return await assertCodexAuthPreflightReady({ ...this.options, codexCommand: this.host.parameters.codexCommand }, {
-        execution: this.host.execution, credentials: this.credentials, reason
-      });
-    } catch (error) {
-      if (error?.code === this.credentials.reconnectRequiredCode && this.runtime?.runtimeDir) {
-        await this.stopRuntimeAndRequireDrain(reason);
-      }
-      throw error;
-    }
-  }
-
-  async assertRuntimeAuthReady(reason = "codex-app-server") {
-    if (this.isHelperProvider() || this.stale) {
-      return;
-    }
-    const runtime = this.runtime || {};
-    let generationError = null;
-    try {
-      await this.credentials.assertCurrent(runtime.authStateSignature);
-    } catch (error) {
-      generationError = error;
-    }
-    const logTail = await tailTextFile(runtime.logPath || "");
-    const reconnectRequired = codexAuthOutputRequiresReconnect(logTail);
-    if (!generationError && !reconnectRequired) {
-      return;
-    }
-    await this.stopRuntimeAndRequireDrain(reason);
-    if (reconnectRequired) {
-      await this.markReconnectRequired({
-        toolHomeSource: runtime.toolHomeSource || this.options.toolHomeSource,
-        observed: logTail,
-        reason
-      });
-      throw this.credentials.reconnectError({
-        observed: logTail
-      });
-    }
-    throw generationError;
-  }
-
-  async markReconnectRequired({ reason = "codex-app-server", observed = "", toolHomeSource } = {}) {
-    await this.credentials.markInvalid({ reason, toolHomeSource });
-    throw this.credentials.reconnectError({ modelProviderId: this.options.modelProviderId, observed });
-  }
-
   async runRequest(operation, reason = "codex-app-server-request") {
     try {
       await this.assertHelperAccountIdentityCurrent();
@@ -1103,7 +340,7 @@ export class CodexAppServerAgentProvider {
 
   async connect() {
     if (this.observationFailure) throw this.observationFailure;
-    if (this.client?.isOpen?.() && this.runtime) {
+    if (this.client?.isOpen() && this.runtime) {
       return {
         initializeResult: null,
         reusedClient: true,
@@ -1125,7 +362,7 @@ export class CodexAppServerAgentProvider {
   }
 
   async openConnection() {
-    if (this.client?.isOpen?.() && this.runtime) {
+    if (this.client?.isOpen() && this.runtime) {
       return {
         initializeResult: null,
         reusedClient: true,
@@ -1133,14 +370,14 @@ export class CodexAppServerAgentProvider {
       };
     }
     const runtime = await this.ensureRuntime();
-    if (this.client?.isOpen?.()) {
+    if (this.client?.isOpen()) {
       return {
         initializeResult: null,
         reusedClient: true,
         runtime
       };
     }
-    this.client?.close?.();
+    this.client?.close();
     this.client = null;
     this.initializeResult = null;
     const client = new CodexAppServerJsonRpcClient({
@@ -1186,10 +423,7 @@ export class CodexAppServerAgentProvider {
         }
         : runtime;
       this.runtime = null;
-      if (helper) {
-        this.helperAuth = null;
-        this.helperAuthBlocked = true;
-      }
+      if (helper) this.auth.blockHelper();
       if (cleanup.cleanupFailed) {
         const failure = new Error(
           helper
@@ -1207,18 +441,10 @@ export class CodexAppServerAgentProvider {
       throw error;
     }
     this.client = client;
-    this.planUsage = null;
-    this.planUsagePending = null;
+    this.auth.resetPlanUsage();
     client.subscribe((notification = {}) => {
       if (this.client !== client || this.observationFailure) return;
-      if (notification.method === "account/updated") {
-        this.planUsage = null;
-        this.planUsageAuthGeneration += 1;
-      }
-      if (notification.method === "account/rateLimits/updated") {
-        const limits = notification.params?.rateLimits;
-        if (!limits?.limitId || limits.limitId === "codex") this.planUsage = codexPlanUsage(limits);
-      }
+      this.auth.observeAccountNotification(notification);
       this.publishNotification(notification);
     });
     this.initializeResult = normalizeCodexAppServerInfo(initializeResult);
@@ -1229,68 +455,12 @@ export class CodexAppServerAgentProvider {
     };
   }
 
-  currentConnectionGeneration() {
-    return this.connectionGeneration;
-  }
-
   publishNotification(notification) {
-    const threadId = notification.params?.threadId;
     if (notification.method === "thread/goal/updated") {
       notification = { ...notification, params: { ...notification.params,
-        goal: this.conversationRuntime.projectGoal(threadId, notification.params.goal) } };
-    }
-    const turnId = notification.params?.turnId;
-    const item = notification.params?.item;
-    if (item?.type === "commandExecution" && item.processId && item.source === "unifiedExecStartup") {
-      const key = JSON.stringify([threadId, turnId, item.id]);
-      if (notification.method === "item/completed") {
-        const command = this.commandExecutions.get(key);
-        if (command) command.completed = true;
-        this.commandExecutions.delete(key);
-      } else if (notification.method === "item/started") {
-        const command = this.commandExecutions.get(key) || {
-          threadId, turnId, itemId: item.id, processId: item.processId, client: this.client
-        };
-        this.commandExecutions.set(key, command);
-        // Native startup may finish after turn/interrupt has already returned.
-        if (this.interruptedTurns.has(JSON.stringify([threadId, turnId]))) {
-          void this.#stopCommand(command).catch(() => null);
-        }
-      }
-    }
-    const probe = this.threadControlProbes.get(threadId);
-    const method = notification.method;
-    if (probe && (/^(turn|item)\//u.test(method) || method === "thread/status/changed")) {
-      const turnId = notification.params?.turnId || notification.params?.turn?.id;
-      if (method === "turn/started" && probe.turnId && probe.turnId !== turnId) {
-        this.threadControlProbes.delete(threadId);
-      } else if (probe.verified) {
-        if (turnId === probe.turnId) {
-          if (method === "item/completed" && notification.params.item?.id === probe.itemId) {
-            probe.result = notification.params.item;
-          }
-          if (method === "turn/completed") probe.completed = true;
-        }
-        return;
-      } else {
-        if (method === "turn/started") probe.turnId = turnId;
-        probe.pending.push(notification);
-        if (method === "item/started" || probe.pending.length >= 32) {
-          const item = notification.params?.item;
-          if (item?.type === "commandExecution" && item.command?.includes(probe.marker)) {
-            probe.verified = true;
-            probe.itemId = item.id;
-            probe.pending = [];
-          } else {
-            // A concurrent native user turn must retain every event. Only a
-            // positively identified control probe may be hidden from chat.
-            this.threadControlProbes.delete(threadId);
-            for (const pending of probe.pending) this.publishNotification(pending);
-          }
-        }
-        return;
-      }
+        goal: this.conversationRuntime.projectGoal(notification.params?.threadId, notification.params.goal) } };
     }
+    if (!this.turns.observeNotification(notification)) return;
     for (const subscriber of this.notificationSubscribers) {
       try {
         subscriber(notification);
@@ -1300,15 +470,6 @@ export class CodexAppServerAgentProvider {
     }
   }
 
-  currentServerInfo() {
-    return this.initializeResult;
-  }
-
-  isControlProbeTurn(threadId, turnId) {
-    const probe = this.threadControlProbes.get(threadId);
-    return Boolean(turnId && probe?.verified && probe.turnId === turnId);
-  }
-
   async currentRuntimeInfo() {
     const runtime = this.runtime || {};
     const executionMode = codexAppServerExecutionMode(this.options);
@@ -1358,13 +519,9 @@ export class CodexAppServerAgentProvider {
     });
   }
 
-  isAvailable() {
-    return Boolean(this.client?.isOpen?.() && this.runtime);
-  }
-
   async activeClient() {
     if (this.observationFailure) throw this.observationFailure;
-    if (this.client?.isOpen?.()) {
+    if (this.client?.isOpen()) {
       return this.client;
     }
     await this.connect();
@@ -1406,45 +563,6 @@ export class CodexAppServerAgentProvider {
     }
   }
 
-  async readPlanUsage() {
-    const client = this.client;
-    if (!client?.isOpen?.()) return { status: "unavailable", windows: [] };
-    if (this.planUsage && Date.now() - this.planUsage.checkedAt < 60_000) return this.planUsage;
-    if (this.planUsagePending) return this.planUsagePending;
-    const previous = this.planUsage;
-    const authGeneration = this.planUsageAuthGeneration;
-    const signal = AbortSignal.timeout(10_000);
-    const operation = (async () => {
-      try {
-        const account = await client.request("account/read", { refreshToken: false }, { signal });
-        if (this.client !== client || this.planUsageAuthGeneration !== authGeneration) return { status: "unavailable", windows: [] };
-        if (account?.account?.type !== "chatgpt") {
-          this.planUsage = { status: "unsupported", windows: [], checkedAt: Date.now() };
-        } else {
-          const result = await client.request("account/rateLimits/read", {}, { signal });
-          if (this.client !== client || this.planUsageAuthGeneration !== authGeneration) return { status: "unavailable", windows: [] };
-          // A live event received during the read is newer than this request.
-          if (this.planUsage === previous) this.planUsage = codexPlanUsage(result.rateLimitsByLimitId?.codex || result.rateLimits);
-        }
-        return this.planUsage;
-      } catch {
-        return { status: "unavailable", windows: [] };
-      }
-    })();
-    this.planUsagePending = operation;
-    try { return await operation; }
-    finally { if (this.planUsagePending === operation) this.planUsagePending = null; }
-  }
-
-  subscribe(callback) {
-    if (typeof callback !== "function") {
-      throw new TypeError("Codex app-server observer must be a function.");
-    }
-    // Observation belongs to this provider, not one replaceable socket.
-    this.notificationSubscribers.add(callback);
-    return () => this.notificationSubscribers.delete(callback);
-  }
-
   failObservation(cause) {
     const message = cause?.code === `${this.errorPrefix}agent_control_recovery_failed`
       ? cause.message
@@ -1453,51 +571,20 @@ export class CodexAppServerAgentProvider {
       new Error(message, { cause }),
       { code: `${this.errorPrefix}codex_observation_lost` }
     );
-    return this.options.onObservationLost?.(this.observationFailure);
-  }
-
-  async stopThreadForObservationLoss(threadId, turnId) {
-    // Control uses only this existing socket. It must not spawn or resume work
-    // to find out whether the work we lost sight of has stopped.
-    const client = this.client;
-    if (!client?.isOpen()) throw new Error("Codex control connection is unavailable.");
-    if (this.commandStopFailure) throw this.commandStopFailure;
-    const signal = AbortSignal.timeout(5_000);
-    const request = (method, params) => client.request(method, params, { signal });
-    let { goal } = await request("thread/goal/get", { threadId });
-    if (goal?.status === "active") {
-      const result = await request("thread/goal/set", { threadId, status: "paused" });
-      if (result.goal?.status !== "paused" || result.goal?.createdAt !== goal.createdAt || result.goal?.objective !== goal.objective) {
-        throw new Error("Codex did not confirm that the same goal was paused.");
-      }
-      goal = result.goal;
-    }
-    const readStatus = async () => {
-      const { thread } = await request("thread/read", { threadId, includeTurns: false });
-      return typeof thread?.status === "string" ? thread.status : thread?.status?.type;
-    };
-    if (!["idle", "notLoaded"].includes(await readStatus())) {
-      if (!turnId) {
-        const page = await request("thread/turns/list", { threadId, limit: 1, sortDirection: "desc", itemsView: "summary" });
-        turnId = page.data?.[0]?.id;
-      }
-      if (!turnId) throw new Error("Codex's running turn could not be identified.");
-      await this.#interruptTurn(client, threadId, turnId, signal);
-      if (await readStatus() !== "idle") throw new Error("Codex did not confirm that its turn stopped.");
-    }
-    return { goal };
+    const { onObservationLost = reportNoObservationLoss } = this.options;
+    return onObservationLost(this.observationFailure);
   }
 
   setServerRequestHandler(callback) {
     const handler = typeof callback === "function" ? callback : null;
     this.serverRequestHandler = handler;
     const client = this.client;
-    client?.setRequestHandler?.((request) => this.handleServerRequest(request, client));
+    client?.setRequestHandler((request) => this.handleServerRequest(request, client));
     return () => {
       if (this.serverRequestHandler === handler) {
         this.serverRequestHandler = null;
         const client = this.client;
-        client?.setRequestHandler?.((request) => this.handleServerRequest(request, client));
+        client?.setRequestHandler((request) => this.handleServerRequest(request, client));
       }
     };
   }
@@ -1507,12 +594,11 @@ export class CodexAppServerAgentProvider {
       throw new TypeError("Codex tool dispatch requires its exact thread and handler.");
     }
     if (this.threadRequestHandlers.has(threadId)) throw new Error("This Codex thread already has an application tool owner.");
-    const runInContext = this.options.runInContext;
-    const registration = { handler: typeof runInContext === "function"
-      ? request => runInContext(() => handler(request)) : handler };
+    const { runInContext = runDirectly } = this.options;
+    const registration = { handler: request => runInContext(() => handler(request)) };
     this.threadRequestHandlers.set(threadId, registration);
     const client = this.client;
-    client?.setRequestHandler?.(request => this.handleServerRequest(request, client));
+    client?.setRequestHandler(request => this.handleServerRequest(request, client));
     return Object.freeze({
       isCurrent: () => this.threadRequestHandlers.get(threadId) === registration,
       release: () => {
@@ -1521,756 +607,26 @@ export class CodexAppServerAgentProvider {
     });
   }
 
-  async startThread({ hostContext, ...params } = {}) {
-    params = await this.conversationRuntime.prepareInstructions({ ...params, hostContext });
-    delete params.hostContext;
-    params = await this.options.prepareThreadParams?.(params) || params;
-    const client = await this.activeClient();
-    params = await this.withHistoryAdapter(params, client);
-    const environment = this.options.prepareThreadEnvironment
-      ? await this.options.prepareThreadEnvironment(this.options.threadEnv || {})
-      : this.options.threadEnv;
-    const requestParams = this.conversationRuntime.threadParameters(params, environment);
-    if (params.ephemeral !== true) requestParams.historyMode = "paginated";
-    const response = await this.runRequest(
-      () => client.request("thread/start", requestParams),
-      "codex-app-server-thread-start"
-    );
-    if (hostContext) {
-      await this.options.bindThreadContext(response?.thread?.id, hostContext, params);
-    }
-    // Native ephemeral helpers have no stored history and report "legacy".
-    // Paginated history is required only for persistent conversations.
-    if (params.ephemeral !== true && response?.thread?.historyMode === "legacy") {
-      throw Object.assign(new Error("Codex did not create the required paginated conversation history. Update Codex before starting a conversation."), {
-        code: `${this.errorPrefix}codex_history_unsupported`
-      });
-    }
-    if (response?.thread?.historyMode === "paginated" && response.thread.ephemeral !== true) {
-      const threadId = normalizeAgentText(response.thread.id);
-      // A new paginated thread needs its metadata and empty rollout persisted
-      // before it can be resumed. This initializes only the just-created,
-      // empty thread; it never hydrates an existing conversation.
-      await this.runRequest(async () => {
-        await client.request("thread/name/set", { threadId, name: threadId });
-        await client.request("thread/read", { threadId, includeTurns: true });
-      }, "codex-app-server-thread-initialize-history");
-    }
-    if (this.options.prepareThreadEnvironment && response?.thread?.id) {
-      this.conversationRuntime.registerThread(response.thread.id, {
-        client, executionId: normalizeAgentText(this.runtime?.executionId),
-        params: requestParams, managed: !Object.hasOwn(params.config || {}, "shell_environment_policy")
-      });
-    }
-    return {
-      ...normalizeAgentThread({
-        id: response?.thread?.id,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.thread
-      }),
-      response
-    };
-  }
-
-  async resumeThread(threadId = "", { hostContext, ...params } = {}) {
-    if (hostContext) await this.options.bindThreadContext(threadId, hostContext, params);
-    params = await this.conversationRuntime.prepareInstructions({ ...params, hostContext }, threadId);
-    delete params.hostContext;
-    params = await this.options.prepareThreadParams?.(params) || params;
-    await this.options.beforeResumeThread?.(threadId);
-    const client = await this.activeClient();
-    let response;
-    if (this.options.prepareThreadEnvironment) {
-      response = await this.withThreadEnvironment(threadId, params, (requestParams, resumed) =>
-        resumed || client.request("thread/resume", { excludeTurns: true, ...requestParams, threadId }));
-    } else {
-      params = await this.withHistoryAdapter(params, client, { threadId });
-      const requestParams = codexAppServerThreadRequestParams(params, this.options.threadEnv);
-      response = await this.runRequest(
-        () => client.request("thread/resume", {
-          excludeTurns: true,
-          ...requestParams,
-          threadId: normalizeAgentText(threadId || requestParams.threadId)
-        }),
-        "codex-app-server-thread-resume"
-      );
-    }
-    return {
-      ...normalizeAgentThread({
-        id: response?.thread?.id,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.thread
-      }),
-      response
-    };
-  }
-
-  async withHistoryAdapter(params, client, options = {}) {
-    return prepareCodexHistory(params, client, { ...options,
-      baseUrl: this.runtime?.historyAdapterBaseUrl, modelProviderId: this.options.modelProviderId });
-  }
-
-  async withThreadEnvironment(threadId, params, operation) {
-    try {
-      return await this.conversationRuntime.withThreadContext(threadId, params, operation);
-    } catch (error) {
-      if (typeof error.code === "string" && error.code.startsWith("assistant_")) error.code = `${this.errorPrefix}${error.code.slice(10)}`;
-      throw error;
-    }
-  }
-
-  async #verifyThreadEnvironment(threadId, environment, request, signal, { requiredKeys = [] } = {}) {
-    const keys = Object.keys(environment).filter((key) => key.startsWith(this.configuration.controlEnvironmentPrefix) || requiredKeys.includes(key)).sort();
-    if (!keys.length) return;
-
-    const marker = `${this.configuration.controlProbePrefix}${randomUUID()}:`;
-    const probe = { marker, pending: [], verified: false, turnId: "" };
-    this.threadControlProbes.set(threadId, probe);
-    const expected = createHash("sha256").update(JSON.stringify(keys.map((key) => [key, environment[key]]))).digest("hex");
-    // This bounded native shell check uses no model and prints only a digest,
-    // never credentials or environment values.
-    await request("thread/shellCommand", {
-      threadId, command: codexControlProbeCommand(keys, marker), timeoutMs: 2000
-    });
-    while (true) {
-      signal.throwIfAborted();
-      // The native completion event owns this result; saved history is not a
-      // second acknowledgement of this live control operation.
-      if (probe.completed && probe.result) {
-        if (probe.result.type !== "commandExecution" || probe.result.exitCode !== 0 ||
-            probe.result.aggregatedOutput?.trim() !== `${marker}${expected}`) {
-          throw Object.assign(new Error("Another native subscriber retained the previous assistant settings. Close the native assistant terminal and retry Resume."), {
-            code: "assistant_agent_control_binding_retained"
-          });
-        }
-        return;
-      }
-      await new Promise((resolve) => setTimeout(resolve, 25));
-    }
-  }
-
-  async ensureThreadControls(threadId) {
-    if (!this.options.prepareThreadEnvironment) return;
-    return this.withThreadEnvironment(threadId, {}, async (_params, resumed) => ({ ok: true, recovered: Boolean(resumed) }));
-  }
-
-  async readGoal(threadId = "", { signal } = {}) {
-    const client = await this.activeClient();
-    const result = await this.runRequest(
-      () => client.request("thread/goal/get", { threadId: normalizeAgentText(threadId) }, { signal }),
-      "codex-app-server-goal-read"
-    );
-    return { ...result, goal: this.conversationRuntime.projectGoal(threadId, result.goal) };
-  }
-
-  async updateThreadSettings(threadId, { model, effort } = {}, { signal } = {}) {
-    if (!normalizeAgentText(threadId) || !normalizeAgentText(model)) {
-      throw new TypeError("Codex settings require an existing thread and a model.");
-    }
-    const client = await this.activeClient();
-    threadId = normalizeAgentText(threadId);
-    const requested = { model, effort, ...(effort ? { config: { model_reasoning_effort: effort } } : {}) };
-    const params = await this.options.prepareThreadParams?.(requested) || requested;
-    const update = async selected => {
-      const current = await this.activeClient();
-      const applied = Promise.withResolvers();
-      // A successful RPC only queues the update. Observe its applied snapshot
-      // before resuming a goal or accepting a dependent settings operation.
-      const deadline = AbortSignal.any([AbortSignal.timeout(this.options.requestTimeoutMs || 10_000), ...(signal ? [signal] : [])]);
-      const abort = () => applied.reject(deadline.reason);
-      const unsubscribe = current.subscribe(notification => {
-        const settings = notification.params?.threadSettings;
-        if (notification.method === "thread/settings/updated" && notification.params?.threadId === threadId &&
-            settings?.model === selected.model && (!selected.effort || settings.effort === selected.effort)) applied.resolve();
-      });
-      this.settingsWaiters.add(applied.reject);
-      deadline.addEventListener("abort", abort, { once: true });
-      void applied.promise.catch(() => {});
-      try {
-        deadline.throwIfAborted();
-        const { thread } = await this.runRequest(() => current.request("thread/read", {
-          threadId, includeTurns: false
-        }, { signal: deadline }), "codex-app-server-settings-read");
-        // Native no-op updates may emit no settings event. A current snapshot
-        // also confirms values already applied by the provider reload.
-        if (thread?.model === selected.model && (!selected.effort || thread.reasoningEffort === selected.effort) &&
-            (!selected.modelProvider || thread.modelProvider === selected.modelProvider)) return {};
-        const result = await this.runRequest(() => current.request("thread/settings/update", {
-          threadId, model: selected.model, ...(selected.effort ? { effort: selected.effort } : {})
-        }, { signal: deadline }), "codex-app-server-settings-update");
-        await applied.promise;
-        return result;
-      } finally {
-        unsubscribe();
-        deadline.removeEventListener("abort", abort);
-        this.settingsWaiters.delete(applied.reject);
-      }
-    };
-    if (params.modelProvider || this.conversationRuntime.hasPendingSettings(threadId)) {
-      const { thread } = await client.request("thread/read", { threadId, includeTurns: false }, { signal });
-      if (params.modelProvider !== thread?.modelProvider || this.conversationRuntime.hasPendingSettings(threadId)) {
-        return this.conversationRuntime.scheduleSettings(threadId, params, update);
-      }
-    }
-    return update(params);
-  }
-
-  async setGoal(threadId, { objective, tokenBudget } = {}, { signal } = {}) {
-    if (typeof objective !== "string" || !objective.trim() ||
-        (tokenBudget !== undefined && (!Number.isSafeInteger(tokenBudget) || tokenBudget <= 0))) {
-      throw new TypeError("A Codex goal requires an objective and an optional positive token budget.");
-    }
-    this.conversationRuntime.goalChanged(threadId);
-    const operation = async () => {
-      const client = await this.activeClient();
-      return client.request("thread/goal/set", {
-        threadId: normalizeAgentText(threadId), objective: objective.trim(), status: "active",
-        ...(tokenBudget === undefined ? {} : { tokenBudget })
-      }, { signal });
-    };
-    return this.options.prepareThreadEnvironment
-      ? this.withThreadEnvironment(threadId, {}, operation)
-      : this.runRequest(operation, "codex-app-server-goal-set");
-  }
-
-  async setGoalStatus(threadId = "", status = "", { signal } = {}) {
-    if (!["active", "paused"].includes(status)) {
-      throw new TypeError("Invalid Codex goal status.");
-    }
-    this.conversationRuntime.goalChanged(threadId);
-    const operation = async () => {
-      const client = await this.activeClient();
-      return client.request("thread/goal/set", { threadId: normalizeAgentText(threadId), status }, { signal });
-    };
-    return status === "active" && this.options.prepareThreadEnvironment
-      ? this.withThreadEnvironment(threadId, {}, operation)
-      : this.runRequest(operation, "codex-app-server-goal-status");
-  }
-
-  async clearGoal(threadId = "", { signal } = {}) {
-    this.conversationRuntime.goalChanged(threadId);
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("thread/goal/clear", { threadId: normalizeAgentText(threadId) }, { signal }),
-      "codex-app-server-goal-clear"
-    );
-  }
-
-  async readThread(threadId = "") {
-    const client = await this.activeClient();
-    const response = await this.runRequest(
-      () => client.request("thread/read", {
-        includeTurns: true,
-        threadId: normalizeAgentText(threadId)
-      }),
-      "codex-app-server-thread-read"
-    );
-    return {
-      ...normalizeAgentThread({
-        id: response?.thread?.id || threadId,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.thread || response
-      }),
-      response
-    };
-  }
-
-  async readThreadStatus(threadId = "") {
-    const client = await this.activeClient();
-    const response = await this.runRequest(
-      () => client.request("thread/read", {
-        includeTurns: false,
-        threadId: normalizeAgentText(threadId)
-      }),
-      "codex-app-server-thread-status"
-    );
-    return {
-      ...normalizeAgentThread({
-        id: response?.thread?.id || threadId,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.thread || response
-      }),
-      response
-    };
-  }
-
-  async listThreadTurns(threadId = "", params = {}) {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("thread/turns/list", {
-        ...params,
-        threadId: normalizeAgentText(threadId || params.threadId)
-      }),
-      "codex-app-server-thread-turns-list"
-    );
-  }
-
-  async exportThreadHistory(threadId, onRecord, { signal } = {}) {
-    const active = await this.activeClient();
-    // Oversized native items must fail preservation without disconnecting the
-    // shared conversation observer. Reuse JSKIT's transport on a separate socket.
-    const client = new CodexAppServerJsonRpcClient({
-      endpoint: active.endpoint,
-      maxMessageBytes: 64 * 1024 ** 2,
-      requestTimeoutMs: 30_000,
-      WebSocketImpl: this.options.WebSocketImpl
-    });
-    const deadline = AbortSignal.timeout(300_000);
-    const boundedSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
-    boundedSignal.throwIfAborted();
-    const abort = () => client.close();
-    boundedSignal.addEventListener("abort", abort, { once: true });
-    try {
-      await client.connect();
-      boundedSignal.throwIfAborted();
-      await client.initialize({ clientInfo: this.configuration.historyClientInfo });
-      boundedSignal.throwIfAborted();
-      return await exportCodexNativeHistory(client, normalizeAgentText(threadId), onRecord, { signal: boundedSignal, errorPrefix: this.errorPrefix });
-    } finally {
-      boundedSignal.removeEventListener("abort", abort);
-      client.close();
-    }
-  }
-
-  async listLoadedThreads(params = {}) {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("thread/loaded/list", params),
-      "codex-app-server-thread-loaded-list"
-    );
-  }
-
-  async listAppServerThreadsForCwd({
-    cwd = "",
-    signal = null
-  } = {}) {
-    const normalizedCwd = normalizeAgentText(cwd);
-    if (!normalizedCwd || codexAppServerTextHasControlCharacters(normalizedCwd)) {
-      const error = new Error("Codex session thread inventory requires an exact cwd.");
-      error.code = `${this.errorPrefix}codex_session_thread_inventory_invalid`;
-      throw error;
-    }
-    const client = await this.activeClient();
-    const state = await listBoundedCodexAppServerThreadIds({
-      archived: false,
-      client,
-      cwd: normalizedCwd,
-      errorCode: `${this.errorPrefix}codex_session_thread_inventory_invalid`,
-      label: "session",
-      requestLabel: "codex-app-server-session-thread-list",
-      runRequest: this.runRequest.bind(this),
-      signal,
-      state: {
-        entryCount: 0,
-        threadIds: new Set()
-      },
-      verifyCwd: true
-    });
-    return Object.freeze({
-      cwd: normalizedCwd,
-      threadIds: Object.freeze([...state.threadIds].sort())
-    });
-  }
-
-  // Native thread/delete cascades through all spawned descendants, including
-  // archived and non-app-server threads. Never infer its scope from cwd alone.
-  async listThreadDescendants(threadId) {
-    const ancestorThreadId = normalizeAgentText(threadId);
-    if (!ancestorThreadId || ancestorThreadId.length > CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH ||
-        codexAppServerTextHasControlCharacters(ancestorThreadId)) {
-      throw new TypeError("Codex descendant inventory requires an exact thread id.");
-    }
-    const client = await this.activeClient();
-    const state = { entryCount: 0, threadIds: new Set() };
-    for (const archived of [false, true]) {
-      await listBoundedCodexAppServerThreadIds({
-        ancestorThreadId, archived, client, state,
-        sourceKinds: CODEX_NATIVE_STORAGE_SOURCE_KINDS,
-        errorCode: `${this.errorPrefix}codex_retirement_inventory_invalid`, label: "retirement",
-        requestLabel: "codex-app-server-descendant-list", runRequest: this.runRequest.bind(this)
-      });
-    }
-    return [...state.threadIds].sort();
-  }
-
-  async listNativeThreadsForCwd(cwd) {
-    if (!path.isAbsolute(cwd || "") || codexAppServerTextHasControlCharacters(cwd)) throw new TypeError("Native inventory requires an exact absolute directory.");
-    const client = await this.activeClient();
-    const state = { entryCount: 0, threadIds: new Set() };
-    for (const archived of [false, true]) {
-      await listBoundedCodexAppServerThreadIds({ archived, client, cwd, state, verifyCwd: true,
-        sourceKinds: CODEX_NATIVE_STORAGE_SOURCE_KINDS,
-        errorCode: `${this.errorPrefix}codex_retirement_inventory_invalid`, label: "native storage",
-        requestLabel: "codex-app-server-native-storage-list", runRequest: this.runRequest.bind(this) });
-    }
-    return [...state.threadIds].sort();
-  }
-
-  async nativeThreadExists(threadId, { signal } = {}) {
-    const id = normalizeAgentText(threadId);
-    if (!id || id.length > CODEX_APP_SERVER_THREAD_INVENTORY_ID_MAX_LENGTH || codexAppServerTextHasControlCharacters(id)) {
-      throw new TypeError("Native existence checks require an exact thread id.");
-    }
-    const client = await this.activeClient();
-    const state = { entryCount: 0, found: false, threadIds: new Set() };
-    for (const archived of [false, true]) {
-      await listBoundedCodexAppServerThreadIds({ archived, client, findThreadId: id, state, signal,
-        sourceKinds: CODEX_NATIVE_STORAGE_SOURCE_KINDS,
-        errorCode: `${this.errorPrefix}codex_retirement_inventory_invalid`, label: "native storage",
-        requestLabel: "codex-app-server-native-existence", runRequest: this.runRequest.bind(this) });
-      if (state.found) return true;
-    }
-    return false;
-  }
-
-  async listHelperThreads({
-    signal = null
-  } = {}) {
-    const client = await this.activeClient();
-    const execution = await this.currentHelperExecutionContext();
-    const state = {
-      entryCount: 0,
-      threadIds: new Set()
-    };
-    for (const archived of [false, true]) {
-      await listBoundedCodexAppServerThreadIds({
-        archived,
-        client,
-        cwd: execution.cwd,
-        errorCode: `${this.errorPrefix}codex_helper_thread_inventory_invalid`,
-        label: "helper",
-        requestLabel: "codex-app-server-helper-thread-list",
-        runRequest: this.runRequest.bind(this),
-        signal,
-        state
-      });
-    }
-    return Object.freeze({
-      threadIds: Object.freeze([...state.threadIds].sort())
-    });
-  }
-
-  async listModels(params = {}, {
-    signal = null
-  } = {}) {
-    const client = await this.activeClient();
-    const data = [];
-    const seenCursors = new Set();
-    const includeHidden = params.includeHidden === true;
-    const limit = normalizePositiveInteger(
-      params.limit,
-      { fallback: CODEX_APP_SERVER_MODEL_CATALOG_PAGE_LIMIT }
-    );
-    const boundedLimit = Math.min(limit, CODEX_APP_SERVER_MODEL_CATALOG_PAGE_LIMIT);
-    let totalBytes = 0;
-    let cursor = params.cursor === undefined || params.cursor === null || params.cursor === ""
-      ? ""
-      : typeof params.cursor === "string"
-        ? params.cursor.trim()
-        : null;
-    if (cursor === null || cursor.length > CODEX_APP_SERVER_MODEL_CATALOG_MAX_CURSOR_LENGTH) {
-      throw this.modelCatalogError("Codex model catalog cursor is invalid.");
-    }
-    for (let page = 0; page < CODEX_APP_SERVER_MODEL_CATALOG_MAX_PAGES; page += 1) {
-      if (cursor && seenCursors.has(cursor)) {
-        throw this.modelCatalogError("Codex model catalog repeated a pagination cursor.");
-      }
-      if (cursor) {
-        seenCursors.add(cursor);
-      }
-      const response = await this.runRequest(
-        () => client.request("model/list", {
-          ...(cursor ? { cursor } : {}),
-          includeHidden,
-          limit: boundedLimit
-        }, { signal }),
-        "codex-app-server-model-list"
-      );
-      if (!Array.isArray(response?.data)) {
-        throw this.modelCatalogError(
-          "Codex model catalog response did not contain a data array."
-        );
-      }
-      if (
-        response.data.length > boundedLimit ||
-        data.length + response.data.length > CODEX_APP_SERVER_MODEL_CATALOG_MAX_ENTRIES
-      ) {
-        throw this.modelCatalogError("Codex model catalog exceeded its entry limit.");
-      }
-      for (const entry of response.data) {
-        if (!isRecord(entry)) {
-          throw this.modelCatalogError("Codex model catalog contained an invalid entry.");
-        }
-        let entryBytes = 0;
-        try {
-          entryBytes = Buffer.byteLength(JSON.stringify(entry), "utf8");
-        } catch {
-          throw this.modelCatalogError("Codex model catalog contained an invalid entry.");
-        }
-        if (
-          entryBytes > CODEX_APP_SERVER_MODEL_CATALOG_MAX_ENTRY_BYTES ||
-          totalBytes + entryBytes > CODEX_APP_SERVER_MODEL_CATALOG_MAX_TOTAL_BYTES
-        ) {
-          throw this.modelCatalogError("Codex model catalog exceeded its response limit.");
-        }
-        totalBytes += entryBytes;
-        data.push(entry);
-      }
-      const nextCursor = response.nextCursor === undefined || response.nextCursor === null || response.nextCursor === ""
-        ? ""
-        : typeof response.nextCursor === "string"
-          ? response.nextCursor.trim()
-          : null;
-      if (nextCursor === null || nextCursor.length > CODEX_APP_SERVER_MODEL_CATALOG_MAX_CURSOR_LENGTH) {
-        throw this.modelCatalogError("Codex model catalog cursor is invalid.");
-      }
-      if (!nextCursor) {
-        return {
-          data,
-          nextCursor: null
-        };
-      }
-      if (seenCursors.has(nextCursor)) {
-        throw this.modelCatalogError("Codex model catalog repeated a pagination cursor.");
-      }
-      cursor = nextCursor;
-    }
-    throw this.modelCatalogError(
-      `Codex model catalog exceeded ${CODEX_APP_SERVER_MODEL_CATALOG_MAX_PAGES} pages.`
-    );
-  }
-
-  async readConfig(params = {}) {
-    const client = await this.activeClient();
-    const cwd = normalizeAgentText(params.cwd);
-    return this.runRequest(
-      () => client.request("config/read", {
-        ...(cwd ? { cwd } : {}),
-        includeLayers: params.includeLayers === true
-      }),
-      "codex-app-server-config-read"
-    );
-  }
-
-  async trustProject(cwd = "") {
-    if (!path.isAbsolute(cwd)) throw new TypeError("Codex project trust requires an absolute worktree path.");
-    const projectRoot = path.resolve(cwd);
-    const client = await this.activeClient();
-    return this.runRequest(async () => {
-      const { config } = await client.request("config/read", { cwd: projectRoot, includeLayers: false });
-      if (config?.projects?.[projectRoot]?.trust_level === "trusted") return;
-      // Codex discovers project hooks before applying thread config overrides.
-      // Trust only this managed worktree through its native configuration API.
-      await client.request("config/batchWrite", {
-        edits: [{
-          keyPath: `projects.${JSON.stringify(projectRoot)}.trust_level`,
-          value: "trusted",
-          mergeStrategy: "upsert"
-        }],
-        expectedVersion: null,
-        filePath: null,
-        reloadUserConfig: true
-      });
-    }, "codex-app-server-project-trust");
-  }
-
-  async listHooks(cwds = []) {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("hooks/list", {
-        cwds: (Array.isArray(cwds) ? cwds : [cwds])
-          .map(normalizeAgentText)
-          .filter(Boolean)
-      }),
-      "codex-app-server-hooks-list"
-    );
-  }
-
-  async writeHookTrustState(state = {}) {
-    if (!isRecord(state) || Object.keys(state).length === 0) {
-      return null;
-    }
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("config/batchWrite", {
-        edits: [{
-          keyPath: "hooks.state",
-          mergeStrategy: "upsert",
-          value: state
-        }],
-        expectedVersion: null,
-        filePath: null,
-        reloadUserConfig: true
-      }),
-      "codex-app-server-hook-trust-write"
-    );
-  }
-
-  async unsubscribeThread(threadId = "") {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("thread/unsubscribe", {
-        threadId: normalizeAgentText(threadId)
-      }),
-      "codex-app-server-thread-unsubscribe"
-    );
-  }
-
-  async deleteThread(threadId = "") {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => client.request("thread/delete", {
-        threadId: normalizeAgentText(threadId)
-      }),
-      "codex-app-server-thread-delete"
-    );
-  }
-
-  async sendTurn(threadId = "", input = [], params = {}, { signal } = {}) {
-    const operation = async () => {
-      const client = await this.activeClient();
-      return client.request("turn/start", {
-        ...params,
-        input: codexTurnInput(input),
-        threadId: normalizeAgentText(threadId || params.threadId)
-      }, { signal });
-    };
-    const response = this.options.prepareThreadEnvironment
-      ? await this.withThreadEnvironment(threadId || params.threadId, {}, operation)
-      : await this.runRequest(operation, "codex-app-server-turn-start");
-    return {
-      ...normalizeAgentTurn({
-        id: response?.turn?.id || response?.turnId,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.turn || response
-      }),
-      response
-    };
-  }
-
-  async steerTurn(threadId = "", turnId = "", input = [], params = {}, { signal } = {}) {
-    const client = await this.activeClient();
-    const response = await this.runRequest(
-      () => client.request("turn/steer", {
-        ...params,
-        expectedTurnId: normalizeAgentText(turnId || params.expectedTurnId),
-        input: codexTurnInput(input),
-        threadId: normalizeAgentText(threadId || params.threadId)
-      }, { signal }),
-      "codex-app-server-turn-steer"
-    );
-    return {
-      ...normalizeAgentTurn({
-        id: response?.turn?.id || response?.turnId || turnId,
-        provider: CODEX_APP_SERVER_PROVIDER_ID,
-        raw: response?.turn || response
-      }),
-      response
-    };
-  }
-
-  interruptionOutcome(threadId = "", turnId = "") {
-    const key = JSON.stringify([normalizeAgentText(threadId), normalizeAgentText(turnId)]);
-    return this.interruptedTurns.get(key) || "";
-  }
-
-  async interruptTurn(threadId = "", turnId = "", { outcome = "" } = {}) {
-    const client = await this.activeClient();
-    return this.runRequest(
-      () => this.#interruptTurn(client, normalizeAgentText(threadId), normalizeAgentText(turnId), undefined, outcome),
-      "codex-app-server-turn-interrupt"
-    );
-  }
-
-  async #interruptTurn(client, threadId, turnId, signal, outcome = "") {
-    const key = JSON.stringify([threadId, turnId]);
-    this.interruptedTurns.set(key, outcome || this.interruptedTurns.get(key) || "");
-    const result = await client.request("turn/interrupt", { threadId, turnId }, { signal });
-    await Promise.all([...this.commandExecutions.values()]
-      .filter((command) => command.threadId === threadId && command.turnId === turnId)
-      .map((command) => this.#stopCommand(command)));
-    return result;
-  }
-
-  #stopCommand(command) {
-    if (command.stopTask) return command.stopTask;
-    command.stopTask = (async () => {
-      const signal = AbortSignal.timeout(5000);
-      const request = (method, params) => command.client.request(method, params, { signal });
-      while (!command.completed) {
-        signal.throwIfAborted();
-        let cursor;
-        let terminal;
-        const cursors = new Set();
-        do {
-          const page = await request("thread/backgroundTerminals/list", {
-            threadId: command.threadId, limit: 100, ...(cursor ? { cursor } : {})
-          });
-          if (!Array.isArray(page.data)) throw new Error("Codex returned no command inventory.");
-          terminal = page.data.find((entry) => entry.processId === command.processId);
-          cursor = page.nextCursor;
-          if (cursor && cursors.has(cursor)) throw new Error("Codex repeated its command inventory cursor.");
-          cursors.add(cursor);
-        } while (!terminal && cursor);
-        if (command.completed) return;
-        if (terminal) {
-          // A recycled process ID must never target a different command.
-          if (terminal.itemId !== command.itemId) throw new Error("The native command identity changed during Stop.");
-          const stopped = await request("thread/backgroundTerminals/terminate", {
-            threadId: command.threadId, processId: command.processId
-          });
-          if (stopped.terminated === true) return;
-        }
-        // Codex emits command-start before adding it to the process inventory.
-        // Absence during that interval is not proof that the command exited.
-        await new Promise((resolve) => setTimeout(resolve, 25));
-      }
-    })().catch((cause) => {
-      const error = Object.assign(new Error("Codex could not confirm that the stopped turn's command exited.", { cause }), {
-        code: `${this.errorPrefix}codex_command_stop_unconfirmed`
-      });
-      this.commandStopFailure = error;
-      // Reuse the existing verified-runtime-stop owner when native control fails.
-      // That owner may already be awaiting this command while stopping a lost
-      // observation. Do not make command cleanup wait on its own caller.
-      void Promise.resolve(this.failObservation(error)).catch(() => null);
-      throw error;
-    });
-    return command.stopTask;
-  }
-
-  nativeCliResumeCommand(threadId = "") {
-    const runtime = this.runtime || {};
-    return codexCliResumeCommand({
-      codexCommand: this.options.codexCommand || "codex",
-      endpoint: runtime.endpoint,
-      threadId
-    });
-  }
-
   close() {
-    this.options.onClose?.();
+    const { onClose = closeNothing } = this.options;
+    onClose();
     for (const reject of this.settingsWaiters) reject(new Error("The assistant connection closed before confirming its settings."));
     this.settingsWaiters.clear();
     this.conversationRuntime.close();
-    this.threadControlProbes.clear();
-    this.commandExecutions.clear();
-    this.interruptedTurns.clear();
-    this.planUsage = null;
-    this.planUsagePending = null;
+    this.turns.clear();
+    this.auth.resetPlanUsage();
     this.notificationSubscribers.clear();
     this.threadRequestHandlers.clear();
     this.client?.close();
     this.client = null;
     this.initializeResult = null;
-    this.helperAuth = null;
-    this.helperAuthBlocked = false;
+    this.auth.forgetHelper();
   }
 
   async stopRuntime({
-    expectedAccountIdentitySignature = "",
-    preserveProcessExitProof = false
-  } = {}) {
+      expectedAccountIdentitySignature = "",
+      preserveProcessExitProof = false
+    } = {}) {
     this.close();
     this.runtimeStopOwner = this.runtime || this.runtimeStopOwner;
     const runtime = this.runtimeStopOwner || {};
@@ -2294,19 +650,3 @@ export class CodexAppServerAgentProvider {
     return result;
   }
 }
-
-export {
-  CODEX_APP_SERVER_INVALID_REQUEST_CODE,
-  ensureCodexAppServerThread, codexApplicationToolConfiguration, assertCodexApplicationToolSchemaIdentity, sendCodexAppServerPrompt,
-  codexAppServerDeliveredTurn,
-  codexAppServerEndpointForTarget, codexAppServerRequestIsInvalid, codexAppServerThreadIsMissing,
-  codexAppServerThreadHasReadableHistory, deleteCodexAppServerThread, deleteCodexAppServerHelperThread,
-  inspectCodexAppServerMessageAdmission,
-  codexCliResumeCommand, codexLocalImageInput, codexTextInput, codexTurnInput, shellQuote,
-  exportCodexNativeHistory, retireCodexConversationHistory, readCodexNativeGoal
-};
-export {
-  createCodexAppServerProviderOwner,
-  codexAppServerOwnedRuntimeKey,
-  codexAppServerRuntimeStopWasVerified
-} from "./codexProviderOwner.js";