@promptbook/cli 0.113.0-1 → 0.113.0-11

package/apps/agents-server/src/utils/getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask.ts

@@ -1,9 +1,10 @@
 import type { AdminChatTaskRecord } from '../chatTasksAdmin';
 import type { UserChatJobStatus } from '../userChat/UserChatJobRecord';
 import type { VpsSelfUpdateJobSnapshot } from '../vpsSelfUpdate';
+import { resolveVpsSelfUpdateJobIdentity } from '../vpsSelfUpdate/vpsSelfUpdateJobIdentity';
 
 /**
- * Stable synthetic task id used for the singleton standalone VPS self-update task row.
+ * Stable synthetic task id prefix used for standalone VPS self-update task rows.
  *
  * @private internal admin utility of Agents Server
  */
@@ -34,9 +35,11 @@ export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot
     const updatedAt = finishedAt || startedAt || new Date().toISOString();
     const errorSummary = job.errorMessage || null;
     const currentStepDetails = job.currentStep || null;
+    const triggerLabel = formatVpsSelfUpdateTrigger(job.trigger);
+    const taskId = `${VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID}:${resolveVpsSelfUpdateJobIdentity(job)}`;
 
     return {
-        id: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
+        id: taskId,
         kind: 'VPS_SELF_UPDATE',
         status,
         createdAt: startedAt || updatedAt,
@@ -56,14 +59,24 @@ export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot
         lastErrorDetails: currentStepDetails,
         userId: 0,
         username: null,
-        agentPermanentId: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
-        agentName: job.targetEnvironment.label,
+        agentPermanentId: taskId,
+        agentName: `${triggerLabel} self-update: ${job.targetEnvironment.label}`,
         chatId: job.targetBranch || job.targetEnvironment.branch || VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID,
         workerId: job.pid !== null ? String(job.pid) : null,
-        queueName: VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME,
+        queueName: `${VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME}:${job.trigger}`,
     };
 }
 
+/**
+ * Formats one self-update trigger for task-manager display.
+ *
+ * @param trigger - Persisted self-update trigger.
+ * @returns Capitalized trigger label.
+ */
+function formatVpsSelfUpdateTrigger(trigger: VpsSelfUpdateJobSnapshot['trigger']): string {
+    return trigger === 'automatic' ? 'Automatic' : 'Manual';
+}
+
 /**
  * Maps the shell-owned self-update status to the durable chat-task status enum used by the admin task manager.
  *

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

@@ -1,10 +1,12 @@
 import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
 import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
 import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
+import { compareAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks/compareAdminChatTasks';
 import { mapVpsSelfUpdateJobToAdminChatTask } from './getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask';
 import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
 import { throttledAdminRecovery } from './getAdminChatTasksResponse/throttledAdminRecovery';
-import { readVpsSelfUpdateJobSnapshot } from './vpsSelfUpdate';
+import { listPagePreviewBrowserAdminTasks } from './pagePreviewBrowserSessions';
+import { readVpsSelfUpdateJobTaskSnapshots } from './vpsSelfUpdate';
 
 /**
  * Milliseconds in one hour.
@@ -61,9 +63,12 @@ export async function getAdminChatTasksResponse(
     // [🧠] Recovery operations are throttled to avoid hammering the DB on every admin poll
     await throttledAdminRecovery();
 
-    const adminChatTasks = await getAdminChatTasks(parsedQuery);
-    const vpsSelfUpdateTask = await loadVpsSelfUpdateAdminChatTask();
-    const injectedTasks = collectAdminChatTasksToInject(vpsSelfUpdateTask, parsedQuery);
+    const vpsSelfUpdateTasks = await loadVpsSelfUpdateAdminChatTasks();
+    const pagePreviewBrowserTasks = listPagePreviewBrowserAdminTasks();
+    const injectableTasks = [...vpsSelfUpdateTasks, ...pagePreviewBrowserTasks];
+    const injectedTasks = collectAdminChatTasksToInject(injectableTasks, parsedQuery);
+    const databaseQuery = createInjectedAwareAdminChatTaskQuery(parsedQuery, injectedTasks.length);
+    const adminChatTasks = await getAdminChatTasks(databaseQuery);
     const { items, total } = mergeInjectedAdminChatTasks({
         databaseItems: adminChatTasks.items,
         databaseTotal: adminChatTasks.total,
@@ -71,7 +76,7 @@ export async function getAdminChatTasksResponse(
         page: parsedQuery.page,
         pageSize: parsedQuery.pageSize,
     });
-    const counters = mergeInjectedAdminChatTaskCounters(adminChatTasks.counters, vpsSelfUpdateTask);
+    const counters = mergeInjectedAdminChatTaskCounters(adminChatTasks.counters, injectableTasks);
 
     return {
         status: 200,
@@ -90,50 +95,72 @@ export async function getAdminChatTasksResponse(
 }
 
 /**
- * Loads the currently persisted standalone VPS self-update task, if any.
+ * Loads persisted standalone VPS self-update tasks, if any.
  *
  * The read is defensive so a corrupt status file cannot block the admin task manager from rendering.
  *
- * @returns Injectable task record or `null` when no self-update has ever been triggered on this server.
+ * @returns Injectable task records.
  */
-async function loadVpsSelfUpdateAdminChatTask(): Promise<AdminChatTaskRecord | null> {
+async function loadVpsSelfUpdateAdminChatTasks(): Promise<Array<AdminChatTaskRecord>> {
     try {
-        const jobSnapshot = await readVpsSelfUpdateJobSnapshot();
-        return mapVpsSelfUpdateJobToAdminChatTask(jobSnapshot);
+        const jobSnapshots = await readVpsSelfUpdateJobTaskSnapshots();
+        return jobSnapshots
+            .map(mapVpsSelfUpdateJobToAdminChatTask)
+            .filter((task): task is AdminChatTaskRecord => task !== null);
     } catch (error) {
-        console.error('[admin-chat-task] failed to load VPS self-update task snapshot', error);
-        return null;
+        console.error('[admin-chat-task] failed to load VPS self-update task snapshots', error);
+        return [];
     }
 }
 
 /**
  * Filters out injected tasks that do not belong to the requested admin task-manager view or search.
  *
- * @param vpsSelfUpdateTask - Currently persisted self-update task or `null`.
+ * @param injectableTasks - Synthetic task rows collected from process-local state.
  * @param query - Parsed admin task-manager query.
  * @returns Tasks to inject on top of the database-backed items.
  */
 function collectAdminChatTasksToInject(
-    vpsSelfUpdateTask: AdminChatTaskRecord | null,
+    injectableTasks: ReadonlyArray<AdminChatTaskRecord>,
     query: ParsedAdminChatTaskQuery,
 ): ReadonlyArray<AdminChatTaskRecord> {
-    if (!vpsSelfUpdateTask) {
-        return [];
-    }
+    const nowTimestamp = Date.now();
+    return injectableTasks
+        .filter(
+            (task) =>
+                matchesAdminChatTaskView(task, query, nowTimestamp) &&
+                matchesAdminChatTaskSearch(task, query.search),
+        )
+        .sort((leftTask, rightTask) => compareAdminChatTasks(leftTask, rightTask, query.view));
+}
 
-    if (!matchesAdminChatTaskView(vpsSelfUpdateTask, query, Date.now())) {
-        return [];
+/**
+ * Builds the database query needed to merge injected task rows into the requested page.
+ *
+ * @param query - Parsed admin task-manager query.
+ * @param injectedTaskCount - Number of injected rows that appear before database-backed rows.
+ * @returns Query used for loading enough database-backed rows to fill the final page.
+ */
+function createInjectedAwareAdminChatTaskQuery(
+    query: ParsedAdminChatTaskQuery,
+    injectedTaskCount: number,
+): ParsedAdminChatTaskQuery {
+    if (injectedTaskCount === 0) {
+        return query;
     }
 
-    if (!matchesAdminChatTaskSearch(vpsSelfUpdateTask, query.search)) {
-        return [];
-    }
+    const pageOffset = (query.page - 1) * query.pageSize;
+    const databaseEndOffset = Math.max(0, pageOffset + query.pageSize - injectedTaskCount);
 
-    return [vpsSelfUpdateTask];
+    return {
+        ...query,
+        page: 1,
+        pageSize: Math.max(1, databaseEndOffset),
+    };
 }
 
 /**
- * Prepends the injected task rows to the paginated database items so the self-update stays visible on page 1.
+ * Prepends injected task rows to the database-backed items and returns the requested combined page.
  *
  * @param options - Merge inputs.
  * @returns Merged items for the current page and the updated total row count.
@@ -146,48 +173,83 @@ function mergeInjectedAdminChatTasks(options: {
     readonly pageSize: number;
 }): { items: Array<AdminChatTaskRecord>; total: number } {
     const total = options.databaseTotal + options.injectedTasks.length;
-
     if (options.injectedTasks.length === 0) {
         return { items: [...options.databaseItems], total };
     }
 
-    if (options.page !== 1) {
-        return { items: [...options.databaseItems], total };
+    const pageOffset = (options.page - 1) * options.pageSize;
+    const injectedItems = options.injectedTasks.slice(pageOffset, pageOffset + options.pageSize);
+    const remainingPageSize = options.pageSize - injectedItems.length;
+
+    if (remainingPageSize <= 0) {
+        return { items: [...injectedItems], total };
     }
 
-    const items = [...options.injectedTasks, ...options.databaseItems].slice(0, options.pageSize);
+    const databaseOffset = Math.max(0, pageOffset - options.injectedTasks.length);
+    const databaseItems = options.databaseItems.slice(databaseOffset, databaseOffset + remainingPageSize);
+    const items = [...injectedItems, ...databaseItems];
     return { items, total };
 }
 
 /**
- * Adds the injected self-update task to the summary counters so the header metrics stay accurate.
+ * Adds injected tasks to the summary counters so the header metrics stay accurate.
  *
  * @param databaseCounters - Counters computed from durable database rows.
- * @param vpsSelfUpdateTask - Currently persisted self-update task or `null`.
- * @returns Merged counters including the injected task.
+ * @param injectedTasks - Synthetic task rows collected from process-local state.
+ * @returns Merged counters including the injected tasks.
  */
 function mergeInjectedAdminChatTaskCounters(
     databaseCounters: AdminChatTaskCounters,
-    vpsSelfUpdateTask: AdminChatTaskRecord | null,
+    injectedTasks: ReadonlyArray<AdminChatTaskRecord>,
 ): AdminChatTaskCounters {
-    if (!vpsSelfUpdateTask) {
+    if (injectedTasks.length === 0) {
         return databaseCounters;
     }
 
     const nowTimestamp = Date.now();
-    const isRunning = vpsSelfUpdateTask.status === 'RUNNING';
-    const isFailedInWindow =
-        vpsSelfUpdateTask.status === 'FAILED' &&
-        isIsoTimestampAtOrAfter(vpsSelfUpdateTask.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS);
+    const injectedQueuedTimestamps = injectedTasks
+        .filter((task) => task.status === 'QUEUED')
+        .map((task) => Date.parse(task.queuedAt))
+        .filter((timestamp) => Number.isFinite(timestamp));
+    const oldestInjectedQueuedAgeMs =
+        injectedQueuedTimestamps.length === 0 ? null : nowTimestamp - Math.min(...injectedQueuedTimestamps);
 
     return {
-        runningCount: databaseCounters.runningCount + (isRunning ? 1 : 0),
-        queuedCount: databaseCounters.queuedCount,
-        failedLast24hCount: databaseCounters.failedLast24hCount + (isFailedInWindow ? 1 : 0),
-        oldestQueuedAgeMs: databaseCounters.oldestQueuedAgeMs,
+        runningCount: databaseCounters.runningCount + injectedTasks.filter((task) => task.status === 'RUNNING').length,
+        queuedCount: databaseCounters.queuedCount + injectedTasks.filter((task) => task.status === 'QUEUED').length,
+        failedLast24hCount:
+            databaseCounters.failedLast24hCount +
+            injectedTasks.filter(
+                (task) =>
+                    task.status === 'FAILED' &&
+                    isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS),
+            ).length,
+        oldestQueuedAgeMs: mergeOldestQueuedAge(databaseCounters.oldestQueuedAgeMs, oldestInjectedQueuedAgeMs),
     };
 }
 
+/**
+ * Merges durable and injected queued-task ages.
+ *
+ * @param databaseOldestQueuedAgeMs - Oldest durable queued-task age.
+ * @param injectedOldestQueuedAgeMs - Oldest injected queued-task age.
+ * @returns Oldest queued age across both sources.
+ */
+function mergeOldestQueuedAge(
+    databaseOldestQueuedAgeMs: number | null,
+    injectedOldestQueuedAgeMs: number | null,
+): number | null {
+    if (databaseOldestQueuedAgeMs === null) {
+        return injectedOldestQueuedAgeMs;
+    }
+
+    if (injectedOldestQueuedAgeMs === null) {
+        return databaseOldestQueuedAgeMs;
+    }
+
+    return Math.max(databaseOldestQueuedAgeMs, injectedOldestQueuedAgeMs);
+}
+
 /**
  * Returns whether the injected task belongs in the requested admin task-manager view.
  *

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/{codeRunnerConfiguration.ts → harnessConfiguration.ts}

@@ -5,13 +5,15 @@ import { listVpsEnvironmentVariables } from './vpsConfiguration';
 const execFileAsync = promisify(execFile);
 
 /**
- * Saved standalone VPS code-runner configuration exposed to the admin UI.
+ * Saved standalone VPS harness configuration exposed to the admin UI.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export type ConfiguredCodeRunner = {
+export type ConfiguredHarness = {
     /**
-     * Runner identifier persisted in `.env`.
+     * Harness identifier persisted in `.env`.
      */
-    readonly agent: string;
+    readonly harness: string;
 
     /**
      * Model identifier persisted in `.env`.
@@ -25,11 +27,13 @@ export type ConfiguredCodeRunner = {
 };
 
 /**
- * Reads the currently configured standalone VPS code runner from managed environment variables.
+ * Reads the currently configured standalone VPS harness from managed environment variables.
+ *
+ * @returns Saved harness settings with fallback defaults.
  *
- * @returns Saved code-runner settings with fallback defaults.
+ * @private internal utility of Agents Server Harness Auth
  */
-export async function readConfiguredCodeRunner(): Promise<ConfiguredCodeRunner> {
+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,
@@ -37,20 +41,22 @@ export async function readConfiguredCodeRunner(): Promise<ConfiguredCodeRunner>
     >;
 
     return {
-        agent: environmentByKey.PTBK_HARNESS || process.env.PTBK_HARNESS || process.env.PTBK_AGENT || 'github-copilot',
+        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 runner-authentication status for the configured runner.
+ * Resolves a short authentication status for the configured harness.
  *
- * @param agent - Runner id.
+ * @param harness - Harness id.
  * @returns Human-readable status.
+ *
+ * @private internal utility of Agents Server Harness Auth
  */
-export async function resolveCodeRunnerStatus(agent: string): Promise<string> {
-    if (agent !== 'github-copilot') {
+export async function resolveHarnessStatus(harness: string): Promise<string> {
+    if (harness !== 'github-copilot') {
         return 'Status check is currently available for GitHub Copilot CLI only.';
     }