@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/codexRuntime.js

@@ -0,0 +1,426 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import WebSocket from "ws";
+import { setTimeout as delay } from "node:timers/promises";
+import { normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { CodexAppServerJsonRpcClient, socketPathFromCodexAppServerEndpoint } from "./codexClient.js";
+import { normalizeNullableText } from "./normalize.js";
+import {
+  CODEX_APP_SERVER_DEFAULT_ENVIRONMENT, CODEX_APP_SERVER_ENDPOINT_STATUS, CODEX_APP_SERVER_EXECUTION_MODES,
+  CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS, CODEX_APP_SERVER_METADATA_SCHEMA_VERSION, CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS,
+  CODEX_APP_SERVER_PROCESS_STATE, CODEX_APP_SERVER_PROVIDER_ID, CODEX_APP_SERVER_READY_TIMEOUT_MS,
+  CODEX_APP_SERVER_RUNTIME_STATUS, CODEX_APP_SERVER_TRANSPORT, codexAppServerExecutionMode,
+  codexAppServerHelperWorkspaceDir, codexAppServerIsHelper, codexAppServerLivenessTimeoutMs,
+  codexAppServerTerminalEnvHash, codexHistoryAdapterUrlIsValid, ensureWritablePrivateDirectory, fileExists,
+  normalizeCodexAppServerMetadata, readCodexAppServerMetadata, writeCodexAppServerMetadata
+} from "./codexProcess.js";
+import { createCodexAppServerRuntimeStop } from "./codexRuntimeStop.js";
+import { createCodexAppServerProcessStart } from "./codexRuntimeStart.js";
+import { createConversationProcessIdentity } from "./processIdentity.js";
+
+/**
+ * The host's process facility. Managed hosts add prepare, stopOwned and authoritative to the local one.
+ * @typedef {object} CodexRuntimeExecution
+ * @property {(request: object) => Promise<object>} run
+ * @property {(executionId: string, options: object) => Promise<object>} stop
+ * @property {(owner: object, options: object) => Promise<object>} [stopOwned]
+ * @property {() => Promise<void>} [prepare]
+ * @property {boolean} [authoritative]
+ */
+
+/** @typedef {ReturnType<typeof createConversationProcessIdentity>} CodexProcessIdentity */
+
+/**
+ * The host's account facility for one native runtime.
+ * @typedef {object} CodexRuntimeCredentials
+ * @property {(options: object) => Promise<string>} identity
+ * @property {(options: object) => Promise<string>} generation
+ * @property {(captured: string) => Promise<void>} assertCurrent
+ * @property {(output: string) => void} observeFailure
+ */
+
+/**
+ * What the process start reads from the runtime configuration.
+ * @typedef {object} CodexRuntimeSettings
+ * @property {string | undefined} commandHookCommand
+ * @property {string} errorPrefix
+ * @property {string} modelCatalogEnvironmentName
+ * @property {string} processLabel
+ * @property {string} processPath
+ * @property {string} runtimeTokenEnvironmentName
+ * @property {string} commandHashEnvironmentName
+ * @property {string} socketPathHelp
+ * @property {string | null} umask
+ */
+
+// One preparation at a time per runtime directory, across every runtime in this
+// process: a second start would race the first for the same socket and lock.
+const codexAppServerRuntimePreparations = new Map();
+
+// The process identity a runtime caller's own liveness check reports for the process group.
+function codexAppServerLivenessIdentity(pid, alive) {
+  return {
+    processGroupIds: alive ? [pid] : [],
+    status: alive ? CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.EXACT : CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.ABSENT
+  };
+}
+
+/**
+ * The production shared runtime: one process owner per stable runtime directory.
+ * Execution and credential facilities retain host policy; threads do not own this process.
+ * @param {object} dependencies
+ * @param {CodexRuntimeExecution} dependencies.execution
+ * @param {CodexRuntimeCredentials} dependencies.credentials
+ * @param {object} [dependencies.configuration]
+ */
+export function createCodexAppServerRuntime({ execution, credentials, configuration = {} }) {
+  const {
+    clientInfo = { name: "jskit", title: "JSKIT", version: "0.1.0" },
+    commandHookCommand,
+    errorPrefix = "",
+    modelCatalogEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.modelCatalogSource,
+    processLabel = "jskit-codex-app-server",
+    processPath = fileURLToPath(new URL("./codexProcessLeader.js", import.meta.url)),
+    runtimeTokenEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.runtimeToken,
+    commandHashEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.commandHash,
+    socketPathHelp = "Configure a shorter host runtime directory.",
+    umask = "0007"
+  } = configuration;
+  const codexProcessIdentity = createConversationProcessIdentity({
+    runtimeTokenEnvironmentName, commandHashEnvironmentName,
+    label: "Codex app-server",
+    unavailableCode: `${errorPrefix}codex_app_server_process_identity_unavailable`
+  });
+  const runtimeStop = createCodexAppServerRuntimeStop({ execution, codexProcessIdentity, errorPrefix });
+  const processStart = createCodexAppServerProcessStart({
+    execution,
+    credentials,
+    codexProcessIdentity,
+    runtimeStop,
+    codexAppServerEndpointStatus,
+    waitForCodexAppServer,
+    settings: {
+      commandHookCommand,
+      errorPrefix,
+      modelCatalogEnvironmentName,
+      processLabel,
+      processPath,
+      runtimeTokenEnvironmentName,
+      commandHashEnvironmentName,
+      socketPathHelp,
+      umask
+    }
+  });
+
+  function codexAppServerMetadataIsWellFormed(metadata = {}, options = {}) {
+    const expectedAttachmentHostRoot = options.compatibility.attachmentHostRoot;
+    const expectedAccountIdentitySignature = normalizeNullableText(options.accountIdentitySignature);
+    const expectedExecutionMode = codexAppServerExecutionMode(options);
+    const expectedToolHomeSource = codexAppServerIsHelper(options) ? "" : normalizeNullableText(options.toolHomeSource);
+    const expectedTerminalEnvHash = codexAppServerTerminalEnvHash(codexAppServerIsHelper(options) ? {} : options.terminalEnv);
+    const expectedRuntimesHash = options.compatibility.runtimesHash;
+    const expectedExecutionContextHash = options.compatibility.executionContextHash;
+    const expectedHelperProcessCwd = expectedExecutionMode === CODEX_APP_SERVER_EXECUTION_MODES.HELPER
+      ? codexAppServerHelperWorkspaceDir(metadata.runtimeDir)
+      : "";
+    return Boolean(
+      metadata.schemaVersion === CODEX_APP_SERVER_METADATA_SCHEMA_VERSION &&
+      metadata.accountIdentitySignature === expectedAccountIdentitySignature &&
+      metadata.attachmentHostRoot === expectedAttachmentHostRoot &&
+      metadata.authStateSignature &&
+      metadata.executionId &&
+      metadata.executionContextHash === expectedExecutionContextHash &&
+      metadata.executionMode === expectedExecutionMode &&
+      metadata.processCwd &&
+      runtimeStop.processMetadataIsIdentifiable(metadata) &&
+      metadata.processState === CODEX_APP_SERVER_PROCESS_STATE.RUNNING &&
+      (expectedExecutionMode === CODEX_APP_SERVER_EXECUTION_MODES.HELPER ||
+        codexHistoryAdapterUrlIsValid(metadata.historyAdapterBaseUrl, metadata.processIdentity.runtimeToken)) &&
+      (!expectedHelperProcessCwd || metadata.processCwd === expectedHelperProcessCwd) &&
+      metadata.provider === CODEX_APP_SERVER_PROVIDER_ID &&
+      metadata.runtimesHash === expectedRuntimesHash &&
+      metadata.terminalEnvHash === expectedTerminalEnvHash &&
+      metadata.toolHomeSource === expectedToolHomeSource &&
+      metadata.transport === CODEX_APP_SERVER_TRANSPORT.UNIX &&
+      metadata.endpoint &&
+      metadata.socketPath
+    );
+  }
+
+  async function codexAppServerEndpointStatus(endpoint = "", {
+    timeoutMs = CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS,
+    WebSocketImpl = WebSocket
+  } = {}) {
+    const normalizedEndpoint = normalizeNullableText(endpoint);
+    const socketPath = socketPathFromCodexAppServerEndpoint(normalizedEndpoint);
+    if (!socketPath || !await fileExists(socketPath)) {
+      return {
+        status: CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING
+      };
+    }
+    const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, { fallback: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS });
+    return {
+      status: await probeCodexAppServer(normalizedEndpoint, normalizedTimeoutMs, WebSocketImpl)
+    };
+  }
+
+  // One bounded connect-and-initialize handshake: responsive, timeout or unreachable.
+  async function probeCodexAppServer(endpoint, timeoutMs, WebSocketImpl) {
+    const client = new CodexAppServerJsonRpcClient({
+      endpoint,
+      requestTimeoutMs: timeoutMs,
+      WebSocketImpl
+    });
+    let timeout = null;
+    const probe = (async () => {
+      await client.connect();
+      await client.initialize({ clientInfo });
+      return CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
+    })();
+    probe.catch(() => null);
+    try {
+      return await Promise.race([
+        probe,
+        new Promise((resolve) => {
+          timeout = setTimeout(() => resolve(CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT), timeoutMs);
+          timeout.unref();
+        })
+      ]);
+    } catch {
+      return CODEX_APP_SERVER_ENDPOINT_STATUS.UNREACHABLE;
+    } finally {
+      clearTimeout(timeout);
+      client.close();
+    }
+  }
+
+  async function codexAppServerMetadataIsLive(metadata = {}, options = {}) {
+    return (await codexAppServerRuntimeStatus(metadata, options)).status === CODEX_APP_SERVER_RUNTIME_STATUS.LIVE;
+  }
+
+  async function codexAppServerRuntimeStatus(metadata = {}, options = {}) {
+    const normalized = normalizeCodexAppServerMetadata(metadata);
+    if (
+      runtimeStop.processMetadataIsIdentifiable(normalized) &&
+      normalized.processState === CODEX_APP_SERVER_PROCESS_STATE.STOPPED &&
+      normalized.processExitVerifiedAt
+    ) {
+      return {
+        metadata: normalized,
+        replace: true,
+        reusable: false,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.EXITED
+      };
+    }
+    if (!codexAppServerMetadataIsWellFormed(normalized, options)) {
+      return {
+        metadata: normalized,
+        replace: true,
+        reusable: false,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.INCOMPATIBLE
+      };
+    }
+    const authStateSignature = await credentials.generation(options);
+    if (normalized.authStateSignature !== authStateSignature) {
+      return {
+        metadata: normalized,
+        replace: true,
+        reusable: false,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.INCOMPATIBLE
+      };
+    }
+    // A runtime caller may check its process group's liveness itself; otherwise the process identity is inspected.
+    const processIdentity = options.processGroupIsAlive
+      ? codexAppServerLivenessIdentity(normalized.pid, options.processGroupIsAlive(normalized.pid))
+      : await runtimeStop.inspectProcessIdentity(normalized, options);
+    if (
+      processIdentity.status === CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.ABSENT ||
+      processIdentity.status === CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.MISMATCH
+    ) {
+      return {
+        metadata: normalized,
+        replace: true,
+        reusable: false,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.EXITED
+      };
+    }
+    if (processIdentity.status !== CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS.EXACT) {
+      return {
+        metadata: normalized,
+        replace: false,
+        reusable: true,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.SUSPECT
+      };
+    }
+    const endpoint = await codexAppServerEndpointStatus(normalized.endpoint, {
+      timeoutMs: codexAppServerLivenessTimeoutMs(options),
+      WebSocketImpl: options.WebSocketImpl
+    });
+    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE) {
+      return {
+        metadata: normalized,
+        replace: false,
+        reusable: true,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.LIVE
+      };
+    }
+    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING) {
+      return {
+        metadata: normalized,
+        replace: true,
+        reusable: false,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.MISSING
+      };
+    }
+    if (endpoint.status === CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT) {
+      return {
+        metadata: normalized,
+        replace: false,
+        reusable: true,
+        status: CODEX_APP_SERVER_RUNTIME_STATUS.SUSPECT
+      };
+    }
+    return {
+      metadata: normalized,
+      replace: true,
+      reusable: false,
+      status: CODEX_APP_SERVER_RUNTIME_STATUS.MISSING
+    };
+  }
+
+  async function waitForCodexAppServer(endpoint = "", {
+    timeoutMs = CODEX_APP_SERVER_READY_TIMEOUT_MS,
+    WebSocketImpl = WebSocket
+  } = {}) {
+    const socketPath = socketPathFromCodexAppServerEndpoint(endpoint);
+    if (!socketPath) {
+      return false;
+    }
+    const startedAt = Date.now();
+    while (!await fileExists(socketPath) && Date.now() - startedAt <= timeoutMs) {
+      await delay(100);
+    }
+    const remainingMs = Math.max(1, timeoutMs - (Date.now() - startedAt));
+    if (!await fileExists(socketPath)) {
+      return false;
+    }
+    return await probeCodexAppServer(endpoint, remainingMs, WebSocketImpl) === CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
+  }
+
+  async function ensureCodexAppServerRuntime(options = {}) {
+    const runtimeDir = path.resolve(options.runtimeDir);
+    while (codexAppServerRuntimePreparations.has(runtimeDir)) {
+      await codexAppServerRuntimePreparations.get(runtimeDir);
+    }
+    // Each waiter rechecks its own auth and runtime configuration after startup.
+    const operation = prepareCodexAppServerRuntime({ ...options, runtimeDir });
+    codexAppServerRuntimePreparations.set(runtimeDir, operation);
+    try {
+      return await operation;
+    } finally {
+      codexAppServerRuntimePreparations.delete(runtimeDir);
+    }
+  }
+
+  async function prepareCodexAppServerRuntime(options) {
+    const { runtimeDir } = options;
+    const [accountIdentitySignature, authStateSignature] = await Promise.all([
+      credentials.identity(options),
+      credentials.generation(options)
+    ]);
+    const runtimeOptions = {
+      ...options,
+      accountIdentitySignature,
+      authStateSignature
+    };
+    const { runtimeMetadataWriter = writeCodexAppServerMetadata } = options;
+    await ensureWritablePrivateDirectory(runtimeDir);
+
+    const existing = await readCodexAppServerMetadata(runtimeDir);
+    const existingStatus = existing ? await codexAppServerRuntimeStatus(existing, runtimeOptions) : null;
+    if (existingStatus?.reusable) {
+      return {
+        ...existingStatus.metadata,
+        reused: true,
+        runtimeStatus: existingStatus.status
+      };
+    }
+
+    const releaseLock = await runtimeStop.acquireRuntimeLock(runtimeDir, runtimeOptions);
+    try {
+      let socketOwnerDrained = false;
+      const afterLock = await readCodexAppServerMetadata(runtimeDir);
+      const afterLockStatus = afterLock ? await codexAppServerRuntimeStatus(afterLock, runtimeOptions) : null;
+      if (afterLockStatus?.reusable) {
+        return {
+          ...afterLockStatus.metadata,
+          reused: true,
+          runtimeStatus: afterLockStatus.status
+        };
+      }
+
+      if (afterLock && (!afterLockStatus || afterLockStatus.replace !== false)) {
+        const stopped = await runtimeStop.stopProcess(runtimeDir, runtimeOptions);
+        if (stopped.processExitVerified !== true) {
+          const error = new Error(
+            `${clientInfo.title} found an earlier Codex app-server but could not prove that its owned execution was stopped. It refused to start a replacement because two assistant processes could damage the session or worsen resource pressure.`
+          );
+          error.code = `${errorPrefix}codex_app_server_process_identity_unverified`;
+          error.cleanupRequired = true;
+          error.retryable = false;
+          throw error;
+        }
+        socketOwnerDrained = true;
+      }
+
+      const started = await processStart.start({
+        ...runtimeOptions,
+        runtimeDir,
+        socketOwnerDrained
+      });
+      try {
+        await credentials.assertCurrent(started.authStateSignature, runtimeOptions);
+        await runtimeMetadataWriter(runtimeDir, started);
+        await credentials.assertCurrent(started.authStateSignature, runtimeOptions);
+      } catch (error) {
+        const helper = codexAppServerIsHelper(runtimeOptions);
+        const cleanup = await runtimeStop.cleanupFailedStart(runtimeDir, {
+          helper,
+          executionId: started.executionId,
+          pid: started.pid,
+          processIdentity: started.processIdentity
+        }, runtimeOptions);
+        const failure = new Error(
+          helper
+            ? "Codex isolated helper runtime metadata could not be recorded."
+            : "Codex app-server runtime could not be published safely.",
+          { cause: error }
+        );
+        failure.code = cleanup.cleanupFailed
+          ? (helper
+              ? `${errorPrefix}codex_helper_runtime_cleanup_required`
+              : `${errorPrefix}codex_app_server_cleanup_required`)
+          : (error?.code || (helper
+              ? `${errorPrefix}codex_helper_runtime_metadata_failed`
+              : `${errorPrefix}codex_app_server_metadata_failed`));
+        failure.cleanupRequired = cleanup.cleanupFailed;
+        failure.retryable = false;
+        throw failure;
+      }
+      return {
+        ...started,
+        reused: false
+      };
+    } finally {
+      await releaseLock();
+    }
+  }
+
+  return Object.freeze({
+    ensure: ensureCodexAppServerRuntime,
+    start: processStart.start,
+    stop: runtimeStop.stopRuntime,
+    isLive: codexAppServerMetadataIsLive,
+    cleanupFailedStart: runtimeStop.cleanupFailedStart
+  });
+}

package/src/server/conversation/codexRuntimeInventory.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import {
+  CODEX_APP_SERVER_PROCESS_STATE,
+  readCodexAppServerMetadata,
+  removeCodexAppServerRuntimeDir
+} from "./codexProcess.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+// Every provider owner in this process shares one inventory: one native
+// runtime may serve several owners, so recovery and sharing always inspect the
+// complete inventory by native runtime identity. Caller-local provider keys are
+// grouped by owner without duplicating it.
+export const codexAppServerProviders = new Map();
+export const codexAppServerOwnedRuntimes = new Map();
+const codexAppServerRuntimeLifecycles = new Map();
+// Runtimes an account change left running a turn, by native runtime identity.
+export const codexAppServerStaleRuntimes = new Map();
+
+export function codexAppServerOwnedRuntimeKey(providerKey = "", providerOptions) {
+  const runtimeDir = normalizeText(providerOptions?.runtimeDir);
+  return runtimeDir
+    ? `runtime:${path.resolve(runtimeDir)}`
+    : `provider:${normalizeText(providerKey)}`;
+}
+
+export function withRuntimeLifecycle(runtimeKey, operation) {
+  const previous = codexAppServerRuntimeLifecycles.get(runtimeKey) || Promise.resolve();
+  const run = previous.catch(() => null).then(operation);
+  const tail = run.catch(() => null).finally(() => {
+    if (codexAppServerRuntimeLifecycles.get(runtimeKey) === tail) {
+      codexAppServerRuntimeLifecycles.delete(runtimeKey);
+    }
+  });
+  codexAppServerRuntimeLifecycles.set(runtimeKey, tail);
+  return run;
+}
+
+// A session recorded a new runtime directory (a new sign-in gets its own), so
+// its previous one is no longer used. It goes once its runtime has verifiably
+// stopped; a stale runtime still finishing its turn drops it when it stops.
+// Helper cleanup treats an absent directory as retired, which is also what it
+// does with a previous sign-in's runtime it finds stopped.
+export function releaseSupersededCodexRuntime(runtimeDir = "") {
+  const runtimeKey = codexAppServerOwnedRuntimeKey("", { runtimeDir });
+  return withRuntimeLifecycle(runtimeKey, async () => {
+    const stale = codexAppServerStaleRuntimes.get(runtimeKey);
+    if (stale) {
+      stale.superseded = true;
+      return { deferred: true, removed: false };
+    }
+    if (codexAppServerOwnedRuntimes.has(runtimeKey) || runtimePeers(runtimeKey).length) {
+      return { removed: false };
+    }
+    const metadata = await readCodexAppServerMetadata(runtimeDir);
+    if (metadata?.processState !== CODEX_APP_SERVER_PROCESS_STATE.STOPPED || !metadata.processExitVerifiedAt) {
+      return { removed: false };
+    }
+    return { removed: await removeCodexAppServerRuntimeDir(runtimeDir) };
+  });
+}
+
+export function codexAppServerRuntimeStopWasVerified(result) {
+  return result?.stopped === true ||
+    result?.processExitVerified === true ||
+    result?.runtimeDirRemoved === true;
+}
+
+export async function directoryExists(filePath = "") {
+  try {
+    return (await stat(filePath)).isDirectory();
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export function* providerRecords() {
+  for (const records of codexAppServerProviders.values()) yield* records.values();
+}
+
+// Every owner's provider records on one native runtime.
+export function runtimePeers(runtimeKey) {
+  return [...providerRecords()].filter(record =>
+    codexAppServerOwnedRuntimeKey(record.providerKey, record.providerOptions) === runtimeKey);
+}
+
+export function nativeRequest(client, method, params) {
+  return client.request(method, params, { signal: AbortSignal.timeout(5_000) });
+}
+
+// The loaded threads of one native runtime that have a running turn, read from
+// the runtime itself so Temporary, Main and native terminal turns all count.
+export async function runningNativeThreads(peers) {
+  const client = peers.find(record => record.provider.client?.isOpen())?.provider.client;
+  if (!client) return [];
+  const running = [];
+  const seen = new Set();
+  let cursor;
+  do {
+    const page = await nativeRequest(client, "thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+    for (const threadId of Array.isArray(page?.data) ? page.data : []) {
+      const { thread } = await nativeRequest(client, "thread/read", { threadId, includeTurns: false });
+      if ((typeof thread?.status === "string" ? thread.status : thread?.status?.type) === "active") running.push(threadId);
+    }
+    cursor = page?.nextCursor;
+    if (cursor && seen.has(cursor)) throw new Error("Codex's loaded-thread inventory did not finish.");
+    if (cursor) seen.add(cursor);
+  } while (cursor);
+  return running;
+}

package/src/server/conversation/codexRuntimeLifecycle.js

@@ -1,9 +1,29 @@
-import { normalizeCodexRunText as normalizeText } from "./codexTurnState.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
-// Shutdown, wellbeing timers and managed-session records for shared Codex
-// runtimes. It works on the run/provider owners' collections; it owns no servers.
-// `pendingWork` names the run owner's in-flight task collections that shutdown
-// drains; `observer` owns the event subscriptions a released provider ends.
+/** @typedef {ReturnType<typeof import("./codexHelperThreads.js").createCodexHelperThreadLifecycle>} CodexHelperThreadLifecycle */
+/** @typedef {ReturnType<typeof import("./codexNotificationObserver.js").createCodexNotificationObserver>} CodexNotificationObserver */
+/** @typedef {ReturnType<typeof createCodexRuntimeLifecycle>} CodexRuntimeLifecycle */
+/** @typedef {ReturnType<typeof import("./codexTurn.js").createCodexAppServerRunOwner>} CodexRunOwner */
+/** @typedef {(event: string, details: object) => void} CodexDebugLog */
+
+/**
+ * Shutdown, wellbeing timers and managed-session records for shared Codex
+ * runtimes. It works on the run/provider owners' collections; it owns no servers.
+ * `pendingWork` names the run owner's in-flight task collections that shutdown
+ * drains; `observer` owns the event subscriptions a released provider ends.
+ * @param {object} dependencies
+ * @param {Record<string, Map<unknown, Promise<unknown>> | Set<Promise<unknown>>>} dependencies.pendingWork
+ * @param {CodexNotificationObserver} dependencies.observer
+ * @param {(providerKey: string, managed: object) => Promise<unknown>} dependencies.checkManagedConnection
+ * @param {import("./codexProviderOwner.js").CodexProviderSessions} dependencies.providerSessions
+ * @param {CodexHelperThreadLifecycle | null} dependencies.helperLifecycle
+ * @param {() => unknown} dependencies.captureContext
+ * @param {<T>(context: unknown, operation: () => T) => T} dependencies.runInContext
+ * @param {((sessionId: string, options: { threadId: string }) => Promise<unknown>) | null} [dependencies.continueGoalAfterAccountChange]
+ * @param {CodexDebugLog} dependencies.debugLog
+ * @param {(error: unknown) => unknown} dependencies.debugError
+ * @param {{ message: string, code: string, retryable: boolean } | null} [dependencies.closingError]
+ */
 export function createCodexRuntimeLifecycle({
   pendingWork,
   observer,
@@ -12,7 +32,7 @@ export function createCodexRuntimeLifecycle({
   helperLifecycle,
   captureContext,
   runInContext,
-  continueGoalAfterAccountChange = null,
+  continueGoalAfterAccountChange,
   debugLog,
   debugError,
   closingError = null
@@ -268,7 +288,7 @@ export function createCodexRuntimeLifecycle({
           }
         });
     }, providerSessions.wellbeingMs);
-    timer.unref?.();
+    timer.unref();
     codexAppServerWellbeingTimers.set(normalizedProviderKey, timer);
   }
 
@@ -296,7 +316,7 @@ export function createCodexRuntimeLifecycle({
   }
 
   function invalidateRuntimes(input = {}, preparation) {
-    const serverShutdown = normalizeText(input?.reason) === "server-shutdown";
+    const serverShutdown = normalizeText(input.reason) === "server-shutdown";
     if (serverShutdown) {
       beginCodexAppServerShutdown();
     }
@@ -328,18 +348,24 @@ export function createCodexRuntimeLifecycle({
     })();
   }
 
-  return {
+  function nextReconcileGeneration() { return ++codexAppServerThreadReconcileGeneration; }
+
+  const managedSession = providerKey => providerSessions.managed.get(providerKey);
+
+  const managedThreadId = providerKey => providerSessions.managed.get(providerKey)?.threadId;
+
+  return Object.freeze({
     get closing() { return codexAppServerServerClosing; },
     assertOpen,
     get reconcileGeneration() { return codexAppServerThreadReconcileGeneration; },
-    nextReconcileGeneration() { return ++codexAppServerThreadReconcileGeneration; },
+    nextReconcileGeneration,
     reconcileTasks: codexAppServerReconcileTasks,
     sessionClosures: codexAppServerSessionClosures,
     invalidateRuntimes,
     resources: codexAppServerProviderResources,
     retireProvider: retireAndCloseCodexAppServerProvider,
     rememberManagedSession: rememberCodexAppServerManagedSession,
-    managedSession: providerKey => providerSessions.managed.get(providerKey),
-    managedThreadId: providerKey => providerSessions.managed.get(providerKey)?.threadId
-  };
+    managedSession,
+    managedThreadId
+  });
 }