@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/utils/getPagePreviewBrowserSessionState.ts

@@ -0,0 +1,41 @@
+import type { PagePreviewSessionState } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewSessionState';
+import type { PagePreviewBrowserSession } from './pagePreviewBrowserSessions';
+
+/**
+ * Reads the current navigation state of one live browser preview session.
+ *
+ * `canGoBack` / `canGoForward` are resolved from the CDP navigation history when the stream
+ * runs on a CDP screencast; otherwise they stay `null` and the preview toolbar keeps its
+ * history buttons enabled.
+ *
+ * @param session - Active browser preview session.
+ * @returns Session navigation state, or `null` when the session has no usable page.
+ *
+ * @private internal utility of Agents Server page-preview streaming
+ */
+export async function getPagePreviewBrowserSessionState(
+    session: PagePreviewBrowserSession,
+): Promise<PagePreviewSessionState | null> {
+    const page = session.page;
+    if (!page || page.isClosed()) {
+        return null;
+    }
+
+    const url = page.url();
+    const title = await page.title().catch(() => null);
+
+    let canGoBack: boolean | null = null;
+    let canGoForward: boolean | null = null;
+
+    if (session.cdpSession) {
+        try {
+            const navigationHistory = await session.cdpSession.send('Page.getNavigationHistory');
+            canGoBack = navigationHistory.currentIndex > 0;
+            canGoForward = navigationHistory.currentIndex < navigationHistory.entries.length - 1;
+        } catch {
+            // The CDP session may already be detached — the toolbar keeps its buttons enabled
+        }
+    }
+
+    return { url, title, canGoBack, canGoForward };
+}

package/apps/agents-server/src/utils/getVpsAdminChatTasksResponse.ts

@@ -0,0 +1,150 @@
+import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
+import { mapRegisteredServerContexts } from '../tools/mapRegisteredServerContexts';
+import type { ServerRecord } from './serverRegistry';
+import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
+import type { GetAdminChatTasksResponseResult } from './getAdminChatTasksResponse';
+import {
+    addAdminChatTaskCounters,
+    collectAdminChatTasksToInject,
+    expandAdminChatTaskQueryToPageSpan,
+    loadInjectableAdminChatTasks,
+    mergeInjectedAdminChatTaskCounters,
+} from './getAdminChatTasksResponse/adminChatTaskInjection';
+import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
+import { compareAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks/compareAdminChatTasks';
+import type { GetAdminChatTasksData } from './getAdminChatTasksResponse/getAdminChatTasks';
+import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
+
+/**
+ * Empty durable-task counters used as the accumulator when summing servers.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+const EMPTY_ADMIN_CHAT_TASK_COUNTERS: AdminChatTaskCounters = {
+    runningCount: 0,
+    queuedCount: 0,
+    failedLast24hCount: 0,
+    oldestQueuedAgeMs: null,
+};
+
+/**
+ * Builds the paginated task-manager payload aggregated across **every** server on the VPS.
+ *
+ * This is the superadmin VPS-wide view. It loads each registered server's durable tasks inside that
+ * server's routing context (so per-server isolation is preserved), tags every row with its server,
+ * and merges them with the process-local VPS tasks (self-updates, browser previews) that are injected
+ * exactly once because they belong to the VPS rather than to any single server.
+ *
+ * @param searchParams - Task-manager query string shared with the per-server endpoint.
+ * @returns Aggregated, paginated VPS-wide task-manager payload.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function getVpsAdminChatTasksResponse(
+    searchParams: URLSearchParams,
+): Promise<GetAdminChatTasksResponseResult> {
+    const parsedQuery = parseAdminChatTaskQuery(searchParams);
+    if (!parsedQuery) {
+        return {
+            status: 400,
+            error: 'Invalid admin task query.',
+        };
+    }
+
+    ensureUserChatTimeoutWorkerBootstrapped();
+
+    const injectableTasks = await loadInjectableAdminChatTasks();
+    const injectedTasks = collectAdminChatTasksToInject(injectableTasks, parsedQuery);
+
+    // Note: Every server must return all rows up to the requested page, because the final global order
+    //       is only known once all servers and the injected VPS tasks are merged together.
+    const perServerQuery = expandAdminChatTaskQueryToPageSpan(parsedQuery);
+    const serverRuns = await mapRegisteredServerContexts((server) => loadServerAdminChatTasks(server, perServerQuery));
+
+    const databaseItems: Array<AdminChatTaskRecord> = [];
+    let databaseTotal = 0;
+    let databaseCounters = EMPTY_ADMIN_CHAT_TASK_COUNTERS;
+    for (const serverRun of serverRuns) {
+        databaseItems.push(...serverRun.value.items);
+        databaseTotal += serverRun.value.total;
+        databaseCounters = addAdminChatTaskCounters(databaseCounters, serverRun.value.counters);
+    }
+
+    const { items, total } = mergeVpsAdminChatTaskPage({
+        databaseItems,
+        databaseTotal,
+        injectedTasks,
+        query: parsedQuery,
+    });
+    const counters = mergeInjectedAdminChatTaskCounters(databaseCounters, injectableTasks);
+
+    return {
+        status: 200,
+        response: {
+            items,
+            counters,
+            total,
+            page: parsedQuery.page,
+            pageSize: parsedQuery.pageSize,
+            view: parsedQuery.view,
+            search: parsedQuery.search,
+            sortBy: parsedQuery.sortBy,
+            sortOrder: parsedQuery.sortOrder,
+            timeWindowHours: parsedQuery.timeWindowHours,
+            generatedAt: new Date().toISOString(),
+        } satisfies AdminChatTaskListResponse,
+    };
+}
+
+/**
+ * Loads one server's durable tasks and tags each row with that server.
+ *
+ * Runs inside the server's routing context established by `mapRegisteredServerContexts`.
+ *
+ * @param server - Registered server the tasks belong to, or `null` for the ambient context.
+ * @param query - Page-spanning query used for every server.
+ * @returns Server-tagged durable task data.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+async function loadServerAdminChatTasks(
+    server: ServerRecord | null,
+    query: ParsedAdminChatTaskQuery,
+): Promise<GetAdminChatTasksData> {
+    const data = await getAdminChatTasks(query);
+
+    return {
+        ...data,
+        items: data.items.map((task) => ({
+            ...task,
+            serverName: server?.name ?? null,
+            serverDomain: server?.domain ?? null,
+        })),
+    };
+}
+
+/**
+ * Merges the injected VPS tasks with the server-tagged database rows and slices the requested page.
+ *
+ * Unlike the per-server merge, this always sorts and slices because the concatenated per-server rows
+ * have no meaningful order until merged.
+ *
+ * @param options - Merge inputs.
+ * @returns Merged items for the current page and the combined total row count.
+ *
+ * @private function of `getVpsAdminChatTasksResponse`
+ */
+function mergeVpsAdminChatTaskPage(options: {
+    readonly databaseItems: ReadonlyArray<AdminChatTaskRecord>;
+    readonly databaseTotal: number;
+    readonly injectedTasks: ReadonlyArray<AdminChatTaskRecord>;
+    readonly query: ParsedAdminChatTaskQuery;
+}): { items: Array<AdminChatTaskRecord>; total: number } {
+    const total = options.databaseTotal + options.injectedTasks.length;
+    const pageOffset = (options.query.page - 1) * options.query.pageSize;
+    const items = [...options.injectedTasks, ...options.databaseItems]
+        .sort((leftTask, rightTask) => compareAdminChatTasks(leftTask, rightTask, options.query))
+        .slice(pageOffset, pageOffset + options.query.pageSize);
+
+    return { items, total };
+}

package/apps/agents-server/src/utils/{codeRunnerAuthentication.ts → harnessAuthentication.ts}

@@ -11,21 +11,23 @@ import {
 } from './interactiveTerminalSession';
 
 /**
- * Serializable snapshot of one interactive code-runner authentication session.
+ * Serializable snapshot of one interactive harness authentication session.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export type CodeRunnerAuthenticationSessionSnapshot = {
+export type HarnessAuthenticationSessionSnapshot = {
     /**
      * Session identifier used by the browser UI.
      */
     readonly id: string;
 
     /**
-     * Runner being authenticated.
+     * Harness being authenticated.
      */
-    readonly agent: string;
+    readonly harness: string;
 
     /**
-     * Whether the interactive runner process is still active.
+     * Whether the interactive harness process is still active.
      */
     readonly isRunning: boolean;
 
@@ -57,8 +59,10 @@ export type CodeRunnerAuthenticationSessionSnapshot = {
 
 /**
  * Browser stream callbacks used by one subscribed UI client.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export type CodeRunnerAuthenticationSessionSubscriber = {
+export type HarnessAuthenticationSessionSubscriber = {
     /**
      * Called whenever new terminal output arrives.
      */
@@ -67,27 +71,29 @@ export type CodeRunnerAuthenticationSessionSubscriber = {
     /**
      * Called once the session exits.
      */
-    readonly onExit: (event: { readonly type: 'exit'; readonly snapshot: CodeRunnerAuthenticationSessionSnapshot }) => void;
+    readonly onExit: (event: { readonly type: 'exit'; readonly snapshot: HarnessAuthenticationSessionSnapshot }) => void;
 };
 
 /**
- * Starts a streamed authentication session for the currently configured standalone runner.
+ * Starts a streamed authentication session for the currently configured standalone harness.
  *
- * @param agent - Runner identifier stored in `.env`.
- * @returns Existing running session for the same runner or a new one.
+ * @param harness - Harness identifier stored in `.env`.
+ * @returns Existing running session for the same harness or a new one.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export async function startCodeRunnerAuthenticationSession(
-    agent: string,
-): Promise<CodeRunnerAuthenticationSessionSnapshot> {
+export async function startHarnessAuthenticationSession(
+    harness: string,
+): Promise<HarnessAuthenticationSessionSnapshot> {
     const scriptPath = await resolveVpsInstallerScriptPath();
     if (!scriptPath) {
         throw new Error('The VPS installer script could not be found on this server.');
     }
 
-    return toRequiredCodeRunnerAuthenticationSessionSnapshot(
+    return toRequiredHarnessAuthenticationSessionSnapshot(
         startInteractiveTerminalSession({
-            sessionKey: buildCodeRunnerAuthenticationSessionKey(agent),
-            title: `${agent} authentication`,
+            sessionKey: buildHarnessAuthenticationSessionKey(harness),
+            title: `${harness} authentication`,
             command: 'bash',
             arguments: [scriptPath, 'authenticate-runner'],
             env: createVpsInstallerCommandEnvironment({
@@ -95,26 +101,28 @@ export async function startCodeRunnerAuthenticationSession(
                 isProcessRestartEnabled: false,
             }),
             metadata: {
-                agent,
+                harness,
             },
-            unavailableErrorMessage: 'Interactive code-runner authentication is available only on the Linux VPS runtime.',
+            unavailableErrorMessage: 'Interactive harness authentication is available only on the Linux VPS runtime.',
         }),
-        agent,
+        harness,
     );
 }
 
 /**
- * Returns the latest known authentication session for a runner.
+ * Returns the latest known authentication session for a harness.
  *
- * @param agent - Runner identifier.
+ * @param harness - Harness identifier.
  * @returns Serializable session snapshot or `null`.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export function getLatestCodeRunnerAuthenticationSession(
-    agent: string,
-): CodeRunnerAuthenticationSessionSnapshot | null {
-    return toCodeRunnerAuthenticationSessionSnapshot(
-        getLatestInteractiveTerminalSession(buildCodeRunnerAuthenticationSessionKey(agent)),
-        agent,
+export function getLatestHarnessAuthenticationSession(
+    harness: string,
+): HarnessAuthenticationSessionSnapshot | null {
+    return toHarnessAuthenticationSessionSnapshot(
+        getLatestInteractiveTerminalSession(buildHarnessAuthenticationSessionKey(harness)),
+        harness,
     );
 }
 
@@ -123,11 +131,13 @@ export function getLatestCodeRunnerAuthenticationSession(
  *
  * @param sessionId - Session identifier.
  * @returns Serializable session snapshot or `null`.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export function getCodeRunnerAuthenticationSession(
+export function getHarnessAuthenticationSession(
     sessionId: string,
-): CodeRunnerAuthenticationSessionSnapshot | null {
-    return toCodeRunnerAuthenticationSessionSnapshot(getInteractiveTerminalSession(sessionId));
+): HarnessAuthenticationSessionSnapshot | null {
+    return toHarnessAuthenticationSessionSnapshot(getInteractiveTerminalSession(sessionId));
 }
 
 /**
@@ -136,17 +146,19 @@ export function getCodeRunnerAuthenticationSession(
  * @param sessionId - Session identifier.
  * @param subscriber - Stream callbacks.
  * @returns Cleanup callback.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export function subscribeToCodeRunnerAuthenticationSession(
+export function subscribeToHarnessAuthenticationSession(
     sessionId: string,
-    subscriber: CodeRunnerAuthenticationSessionSubscriber,
+    subscriber: HarnessAuthenticationSessionSubscriber,
 ): (() => void) | null {
     return subscribeToInteractiveTerminalSession(sessionId, {
         onOutput: subscriber.onOutput,
         onExit: ({ snapshot }) =>
             subscriber.onExit({
                 type: 'exit',
-                snapshot: toRequiredCodeRunnerAuthenticationSessionSnapshot(snapshot),
+                snapshot: toRequiredHarnessAuthenticationSessionSnapshot(snapshot),
             }),
     });
 }
@@ -157,12 +169,14 @@ export function subscribeToCodeRunnerAuthenticationSession(
  * @param sessionId - Session identifier.
  * @param input - Raw text to write to stdin.
  * @returns Updated session snapshot.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export function writeCodeRunnerAuthenticationSessionInput(
+export function writeHarnessAuthenticationSessionInput(
     sessionId: string,
     input: string,
-): CodeRunnerAuthenticationSessionSnapshot {
-    return toRequiredCodeRunnerAuthenticationSessionSnapshot(writeInteractiveTerminalSessionInput(sessionId, input));
+): HarnessAuthenticationSessionSnapshot {
+    return toRequiredHarnessAuthenticationSessionSnapshot(writeInteractiveTerminalSessionInput(sessionId, input));
 }
 
 /**
@@ -170,41 +184,43 @@ export function writeCodeRunnerAuthenticationSessionInput(
  *
  * @param sessionId - Session identifier.
  * @returns Updated session snapshot.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export function stopCodeRunnerAuthenticationSession(
+export function stopHarnessAuthenticationSession(
     sessionId: string,
-): CodeRunnerAuthenticationSessionSnapshot {
-    return toRequiredCodeRunnerAuthenticationSessionSnapshot(stopInteractiveTerminalSession(sessionId));
+): HarnessAuthenticationSessionSnapshot {
+    return toRequiredHarnessAuthenticationSessionSnapshot(stopInteractiveTerminalSession(sessionId));
 }
 
 /**
- * Builds the stable logical session key for one runner authentication terminal.
+ * Builds the stable logical session key for one harness authentication terminal.
  *
- * @param agent - Runner identifier.
+ * @param harness - Harness identifier.
  * @returns Stable session key.
  */
-function buildCodeRunnerAuthenticationSessionKey(agent: string): string {
-    return `code-runner-authentication:${agent}`;
+function buildHarnessAuthenticationSessionKey(harness: string): string {
+    return `harness-authentication:${harness}`;
 }
 
 /**
- * Converts one generic terminal snapshot into the runner-specific browser shape.
+ * Converts one generic terminal snapshot into the harness-specific browser shape.
  *
  * @param session - Generic terminal snapshot.
- * @param fallbackAgent - Agent name used when older sessions miss metadata.
- * @returns Runner-specific snapshot or `null`.
+ * @param fallbackHarness - Harness name used when older sessions miss metadata.
+ * @returns Harness-specific snapshot or `null`.
  */
-function toCodeRunnerAuthenticationSessionSnapshot(
+function toHarnessAuthenticationSessionSnapshot(
     session: InteractiveTerminalSessionSnapshot | null,
-    fallbackAgent = '',
-): CodeRunnerAuthenticationSessionSnapshot | null {
+    fallbackHarness = '',
+): HarnessAuthenticationSessionSnapshot | null {
     if (!session) {
         return null;
     }
 
     return {
         id: session.id,
-        agent: session.metadata.agent || fallbackAgent,
+        harness: session.metadata.harness || session.metadata.agent || fallbackHarness,
         isRunning: session.isRunning,
         output: session.output,
         startedAt: session.startedAt,
@@ -215,16 +231,16 @@ function toCodeRunnerAuthenticationSessionSnapshot(
 }
 
 /**
- * Converts one generic terminal snapshot into a required runner-specific snapshot.
+ * Converts one generic terminal snapshot into a required harness-specific snapshot.
  *
  * @param session - Generic terminal snapshot.
- * @returns Runner-specific snapshot.
+ * @returns Harness-specific snapshot.
  */
-function toRequiredCodeRunnerAuthenticationSessionSnapshot(
+function toRequiredHarnessAuthenticationSessionSnapshot(
     session: InteractiveTerminalSessionSnapshot | null,
-    fallbackAgent = '',
-): CodeRunnerAuthenticationSessionSnapshot {
-    const mappedSession = toCodeRunnerAuthenticationSessionSnapshot(session, fallbackAgent);
+    fallbackHarness = '',
+): HarnessAuthenticationSessionSnapshot {
+    const mappedSession = toHarnessAuthenticationSessionSnapshot(session, fallbackHarness);
 
     if (!mappedSession) {
         throw new Error('Authentication session was not found.');

package/apps/agents-server/src/utils/harnessConfiguration.ts

@@ -0,0 +1,232 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { spaceTrim } from 'spacetrim';
+import { CODEX_CHATGPT_LOGIN_STATUS_NEEDLE, type CodexLoginMethod } from '../../../../src/book-3.0/codexLoginMethod';
+import { listVpsEnvironmentVariables } from './vpsConfiguration';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Harness identifier of the OpenAI Codex CLI.
+ *
+ * @private internal constant of Agents Server Harness Auth
+ */
+const OPENAI_CODEX_HARNESS_ID = 'openai-codex';
+
+/**
+ * OpenAI API-key environment variables that make the Codex CLI bill per token and hide an active
+ * ChatGPT subscription login from `codex login status`.
+ *
+ * @private internal constant of Agents Server Harness Auth
+ */
+const OPENAI_CODEX_API_KEY_ENVIRONMENT_KEYS = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'CODEX_API_KEY'] as const;
+
+/**
+ * Saved standalone VPS harness configuration exposed to the admin UI.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+export type ConfiguredHarness = {
+    /**
+     * Harness identifier persisted in `.env`.
+     */
+    readonly harness: string;
+
+    /**
+     * Model identifier persisted in `.env`.
+     */
+    readonly model: string;
+
+    /**
+     * Thinking level persisted in `.env`.
+     */
+    readonly thinkingLevel: string;
+};
+
+/**
+ * Reads the currently configured standalone VPS harness from managed environment variables.
+ *
+ * @returns Saved harness settings with fallback defaults.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+export async function readConfiguredHarness(): Promise<ConfiguredHarness> {
+    const snapshot = await listVpsEnvironmentVariables();
+    const environmentByKey = Object.fromEntries(snapshot.variables.map((variable) => [variable.key, variable.value])) as Record<
+        string,
+        string
+    >;
+
+    return {
+        harness: environmentByKey.PTBK_HARNESS || process.env.PTBK_HARNESS || process.env.PTBK_AGENT || 'github-copilot',
+        model: environmentByKey.PTBK_MODEL || process.env.PTBK_MODEL || 'gpt-5.4',
+        thinkingLevel: environmentByKey.PTBK_THINKING_LEVEL || process.env.PTBK_THINKING_LEVEL || 'xhigh',
+    };
+}
+
+/**
+ * Resolves a short authentication status for the configured harness.
+ *
+ * @param harness - Harness id.
+ * @returns Human-readable status.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+export async function resolveHarnessStatus(harness: string): Promise<string> {
+    if (harness !== 'github-copilot') {
+        return 'Status check is currently available for GitHub Copilot CLI only.';
+    }
+
+    try {
+        const { stdout, stderr } = await execFileAsync('copilot', ['auth', 'status'], {
+            timeout: 10_000,
+            maxBuffer: 128 * 1024,
+        });
+
+        return [stdout, stderr].filter(Boolean).join('\n').trim() || 'GitHub Copilot CLI returned no status output.';
+    } catch (error) {
+        return error instanceof Error ? error.message : 'GitHub Copilot CLI status check failed.';
+    }
+}
+
+/**
+ * Resolved harness authentication status shown by the Harness Auth admin page.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+export type HarnessAuthenticationStatus = {
+    /**
+     * Human-readable status line for the configured harness.
+     */
+    readonly status: string;
+
+    /**
+     * Which login method the OpenAI Codex harness currently uses, or `null` for other harnesses.
+     */
+    readonly codexLoginMethod: CodexLoginMethod | null;
+};
+
+/**
+ * Resolves the authentication status shown by the Harness Auth admin page for the configured harness.
+ *
+ * @param harness - Harness id.
+ * @returns Status line plus the resolved OpenAI Codex login method when the harness is OpenAI Codex.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+export async function resolveHarnessAuthenticationStatus(harness: string): Promise<HarnessAuthenticationStatus> {
+    if (harness === OPENAI_CODEX_HARNESS_ID) {
+        return resolveOpenAiCodexAuthenticationStatus();
+    }
+
+    return {
+        status: await resolveHarnessStatus(harness),
+        codexLoginMethod: null,
+    };
+}
+
+/**
+ * Resolves whether OpenAI Codex currently authenticates with the ChatGPT subscription or the
+ * `OPENAI_API_KEY`, mirroring the runtime decision made by the Codex runner script.
+ *
+ * @returns Status line and the resolved Codex login method.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+async function resolveOpenAiCodexAuthenticationStatus(): Promise<HarnessAuthenticationStatus> {
+    if (await isOpenAiCodexChatgptLoginActive()) {
+        return {
+            status: spaceTrim(`
+                Signed in with a ChatGPT subscription.
+                OpenAI Codex uses the ChatGPT account and ignores any OPENAI_API_KEY.
+            `),
+            codexLoginMethod: 'chatgpt',
+        };
+    }
+
+    if (await isOpenAiApiKeyConfigured()) {
+        return {
+            status: spaceTrim(`
+                Using the OpenAI API key (OPENAI_API_KEY).
+                OpenAI Codex is billed per token through the OpenAI API. Sign in below to switch to a ChatGPT subscription.
+            `),
+            codexLoginMethod: 'api',
+        };
+    }
+
+    return {
+        status: spaceTrim(`
+            Not signed in.
+            There is no ChatGPT subscription login and no OPENAI_API_KEY configured, so OpenAI Codex cannot answer chats yet.
+            Start the authentication wizard below to sign in with "codex login --device-auth".
+        `),
+        codexLoginMethod: 'unknown',
+    };
+}
+
+/**
+ * Checks whether the OpenAI Codex CLI reports an active ChatGPT subscription login.
+ *
+ * @returns `true` when Codex is logged in with a ChatGPT account.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+async function isOpenAiCodexChatgptLoginActive(): Promise<boolean> {
+    return (await runOpenAiCodexLoginStatus()).includes(CODEX_CHATGPT_LOGIN_STATUS_NEEDLE);
+}
+
+/**
+ * Runs `codex login status` with the API-key environment variables removed and returns the combined
+ * output, because the API-key variables make Codex report API-key authentication and hide an active
+ * ChatGPT login, and Codex prints the ChatGPT status line to stderr.
+ *
+ * @returns Combined stdout and stderr, or an empty string when the CLI is unavailable.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+async function runOpenAiCodexLoginStatus(): Promise<string> {
+    try {
+        const { stdout, stderr } = await execFileAsync('codex', ['login', 'status'], {
+            timeout: 10_000,
+            maxBuffer: 128 * 1024,
+            env: buildOpenAiCodexEnvironmentWithoutApiKey(),
+        });
+
+        return [stdout, stderr].join('\n');
+    } catch (error) {
+        // `codex login status` exits non-zero when signed out; still inspect any captured output.
+        const execError = error as { readonly stdout?: string; readonly stderr?: string };
+        return [execError.stdout ?? '', execError.stderr ?? ''].join('\n');
+    }
+}
+
+/**
+ * Builds a child-process environment for the Codex CLI with the OpenAI API-key variables removed.
+ *
+ * @returns Process environment without the OpenAI API-key variables.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+function buildOpenAiCodexEnvironmentWithoutApiKey(): NodeJS.ProcessEnv {
+    const environment: NodeJS.ProcessEnv = { ...process.env };
+
+    for (const environmentKey of OPENAI_CODEX_API_KEY_ENVIRONMENT_KEYS) {
+        delete environment[environmentKey];
+    }
+
+    return environment;
+}
+
+/**
+ * Checks whether an OpenAI API key is configured in the managed VPS environment or the process env.
+ *
+ * @returns `true` when `OPENAI_API_KEY` is defined.
+ *
+ * @private internal utility of Agents Server Harness Auth
+ */
+async function isOpenAiApiKeyConfigured(): Promise<boolean> {
+    const snapshot = await listVpsEnvironmentVariables();
+    const openAiApiKeyRecord = snapshot.variables.find((variable) => variable.key === 'OPENAI_API_KEY');
+
+    return Boolean(openAiApiKeyRecord?.isDefined);
+}