@promptbook/cli 0.113.0-0 → 0.113.0-10

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

@@ -0,0 +1,97 @@
+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 prefix used for standalone VPS self-update task rows.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID = 'vps-self-update';
+
+/**
+ * Synthetic queue name used for the standalone VPS self-update task row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_QUEUE_NAME = 'vps-self-update';
+
+/**
+ * Maps a persisted VPS self-update job snapshot to the admin task manager row shape.
+ *
+ * @param job - Latest persisted self-update job snapshot.
+ * @returns Task manager row or `null` when no self-update has ever been triggered on this server.
+ */
+export function mapVpsSelfUpdateJobToAdminChatTask(job: VpsSelfUpdateJobSnapshot): AdminChatTaskRecord | null {
+    const status = toAdminChatTaskStatus(job);
+    if (!status) {
+        return null;
+    }
+
+    const isTerminalStatus = status === 'COMPLETED' || status === 'FAILED';
+    const startedAt = job.startedAt;
+    const finishedAt = isTerminalStatus ? job.finishedAt || startedAt : null;
+    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: taskId,
+        kind: 'VPS_SELF_UPDATE',
+        status,
+        createdAt: startedAt || updatedAt,
+        queuedAt: startedAt || updatedAt,
+        startedAt,
+        updatedAt,
+        finishedAt,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: null,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: errorSummary,
+        lastErrorDetails: currentStepDetails,
+        userId: 0,
+        username: null,
+        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}:${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.
+ *
+ * @param job - Persisted self-update job snapshot.
+ * @returns Equivalent durable chat-job status, or `null` when the job is idle (no run has been triggered yet).
+ */
+function toAdminChatTaskStatus(job: VpsSelfUpdateJobSnapshot): UserChatJobStatus | null {
+    switch (job.status) {
+        case 'running':
+            return 'RUNNING';
+        case 'succeeded':
+            return 'COMPLETED';
+        case 'failed':
+            return 'FAILED';
+        case 'idle':
+            return null;
+    }
+}

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

@@ -1,8 +1,19 @@
 import { ensureUserChatTimeoutWorkerBootstrapped } from '@/src/utils/userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
-import type { AdminChatTaskListResponse } from './chatTasksAdmin';
+import type { AdminChatTaskCounters, AdminChatTaskListResponse, AdminChatTaskRecord } from './chatTasksAdmin';
 import { getAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks';
-import { parseAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
+import { compareAdminChatTasks } from './getAdminChatTasksResponse/getAdminChatTasks/compareAdminChatTasks';
+import { mapVpsSelfUpdateJobToAdminChatTask } from './getAdminChatTasksResponse/mapVpsSelfUpdateJobToAdminChatTask';
+import { parseAdminChatTaskQuery, type ParsedAdminChatTaskQuery } from './getAdminChatTasksResponse/parseAdminChatTaskQuery';
 import { throttledAdminRecovery } from './getAdminChatTasksResponse/throttledAdminRecovery';
+import { listPagePreviewBrowserAdminTasks } from './pagePreviewBrowserSessions';
+import { readVpsSelfUpdateJobTaskSnapshots } from './vpsSelfUpdate';
+
+/**
+ * Milliseconds in one hour.
+ *
+ * @private internal constant of `getAdminChatTasksResponse`
+ */
+const HOUR_IN_MILLISECONDS = 60 * 60 * 1000;
 
 /**
  * Successful task-manager response envelope.
@@ -52,14 +63,27 @@ 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 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,
+        injectedTasks,
+        page: parsedQuery.page,
+        pageSize: parsedQuery.pageSize,
+    });
+    const counters = mergeInjectedAdminChatTaskCounters(adminChatTasks.counters, injectableTasks);
 
     return {
         status: 200,
         response: {
-            items: adminChatTasks.items,
-            counters: adminChatTasks.counters,
-            total: adminChatTasks.total,
+            items,
+            counters,
+            total,
             page: parsedQuery.page,
             pageSize: parsedQuery.pageSize,
             view: parsedQuery.view,
@@ -69,3 +93,231 @@ export async function getAdminChatTasksResponse(
         },
     };
 }
+
+/**
+ * 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 records.
+ */
+async function loadVpsSelfUpdateAdminChatTasks(): Promise<Array<AdminChatTaskRecord>> {
+    try {
+        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 snapshots', error);
+        return [];
+    }
+}
+
+/**
+ * Filters out injected tasks that do not belong to the requested admin task-manager view or search.
+ *
+ * @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(
+    injectableTasks: ReadonlyArray<AdminChatTaskRecord>,
+    query: ParsedAdminChatTaskQuery,
+): ReadonlyArray<AdminChatTaskRecord> {
+    const nowTimestamp = Date.now();
+    return injectableTasks
+        .filter(
+            (task) =>
+                matchesAdminChatTaskView(task, query, nowTimestamp) &&
+                matchesAdminChatTaskSearch(task, query.search),
+        )
+        .sort((leftTask, rightTask) => compareAdminChatTasks(leftTask, rightTask, query.view));
+}
+
+/**
+ * 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;
+    }
+
+    const pageOffset = (query.page - 1) * query.pageSize;
+    const databaseEndOffset = Math.max(0, pageOffset + query.pageSize - injectedTaskCount);
+
+    return {
+        ...query,
+        page: 1,
+        pageSize: Math.max(1, databaseEndOffset),
+    };
+}
+
+/**
+ * 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.
+ */
+function mergeInjectedAdminChatTasks(options: {
+    readonly databaseItems: ReadonlyArray<AdminChatTaskRecord>;
+    readonly databaseTotal: number;
+    readonly injectedTasks: ReadonlyArray<AdminChatTaskRecord>;
+    readonly page: number;
+    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 };
+    }
+
+    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 databaseOffset = Math.max(0, pageOffset - options.injectedTasks.length);
+    const databaseItems = options.databaseItems.slice(databaseOffset, databaseOffset + remainingPageSize);
+    const items = [...injectedItems, ...databaseItems];
+    return { items, total };
+}
+
+/**
+ * Adds injected tasks to the summary counters so the header metrics stay accurate.
+ *
+ * @param databaseCounters - Counters computed from durable database rows.
+ * @param injectedTasks - Synthetic task rows collected from process-local state.
+ * @returns Merged counters including the injected tasks.
+ */
+function mergeInjectedAdminChatTaskCounters(
+    databaseCounters: AdminChatTaskCounters,
+    injectedTasks: ReadonlyArray<AdminChatTaskRecord>,
+): AdminChatTaskCounters {
+    if (injectedTasks.length === 0) {
+        return databaseCounters;
+    }
+
+    const nowTimestamp = Date.now();
+    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 + 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.
+ *
+ * @param task - Injected task.
+ * @param query - Parsed admin task-manager query.
+ * @param nowTimestamp - Current epoch used for time-window filtering.
+ * @returns `true` when the task should be included.
+ */
+function matchesAdminChatTaskView(
+    task: AdminChatTaskRecord,
+    query: ParsedAdminChatTaskQuery,
+    nowTimestamp: number,
+): boolean {
+    switch (query.view) {
+        case 'running':
+            return task.status === 'RUNNING';
+        case 'queued':
+            return task.status === 'QUEUED';
+        case 'failed':
+            return (
+                task.status === 'FAILED' &&
+                isIsoTimestampAtOrAfter(task.finishedAt, nowTimestamp - 24 * HOUR_IN_MILLISECONDS)
+            );
+        case 'all':
+            return isIsoTimestampAtOrAfter(task.updatedAt, nowTimestamp - query.timeWindowHours * HOUR_IN_MILLISECONDS);
+        case 'active':
+        default:
+            return task.status === 'QUEUED' || task.status === 'RUNNING';
+    }
+}
+
+/**
+ * Returns whether the injected task matches the free-text admin search input.
+ *
+ * @param task - Injected task.
+ * @param search - Trimmed search text from the parsed query.
+ * @returns `true` when the task should be included.
+ */
+function matchesAdminChatTaskSearch(task: AdminChatTaskRecord, search: string): boolean {
+    if (!search) {
+        return true;
+    }
+
+    const normalizedSearch = search.toLowerCase();
+    if (task.id.toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    if (task.agentPermanentId.toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    if ((task.agentName || '').toLowerCase().includes(normalizedSearch)) {
+        return true;
+    }
+    return task.chatId.toLowerCase().includes(normalizedSearch);
+}
+
+/**
+ * Returns whether one ISO timestamp is at or after the given cutoff.
+ *
+ * @param timestampIso - Optional ISO timestamp.
+ * @param cutoffTimestamp - Epoch cutoff in milliseconds.
+ * @returns `true` when the timestamp is at or after the cutoff.
+ */
+function isIsoTimestampAtOrAfter(timestampIso: string | null, cutoffTimestamp: number): boolean {
+    if (!timestampIso) {
+        return false;
+    }
+
+    const timestamp = Date.parse(timestampIso);
+    return Number.isFinite(timestamp) && timestamp >= cutoffTimestamp;
+}

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

@@ -1,12 +1,10 @@
-import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
-import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
 import type { string_agent_url } from '../../../../src/types/typeAliases';
 import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
-import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import {
     DEFAULT_FEDERATED_AGENT_IMPORT_CONFIGURATION,
     type FederatedAgentImportConfiguration,
 } from '../constants/federatedAgentImport';
+import { createMissingImportedAgentFallback } from './createMissingImportedAgentFallback';
 import { retryWithBackoff } from './retryWithBackoff';
 import { importAgent, type ImportAgentOptions } from './importAgent';
 
@@ -40,61 +38,6 @@ const cachedFailedImportedAgentFallbackByKey = new Map<string, FailedImportedAge
  */
 const pendingImportedAgentFallbackByKey = new Map<string, Promise<string_book>>();
 
-/**
- * Collapses one thrown error into a single-line message suitable for `NOTE` commitments.
- *
- * @param agentUrl - Canonical imported agent URL.
- * @param error - Unknown error raised while loading the imported agent.
- * @returns Human-readable single-line failure reason.
- *
- * @private internal helper for imported-agent fallback books
- */
-function normalizeImportFailureMessage(agentUrl: string_agent_url, error: unknown): string {
-    const rawMessage = error instanceof Error ? error.message : String(error);
-    const normalizedMessage = rawMessage.replace(/\s+/g, ' ').trim();
-    const prefix = `Failed to import agent from "${agentUrl}"`;
-
-    if (normalizedMessage.startsWith(prefix)) {
-        const suffix = normalizedMessage.slice(prefix.length).trim();
-        if (suffix.length > 0) {
-            return suffix.replace(/^[-:,\s]+/, '').trim() || 'unknown error';
-        }
-    }
-
-    return normalizedMessage || 'unknown error';
-}
-
-/**
- * Creates the ad-hoc fallback source returned when a federated imported agent stays unavailable.
- *
- * @param agentUrl - Canonical imported agent URL.
- * @param attempts - Total number of attempts that were used.
- * @param error - Final error raised by the failed import attempts.
- * @returns Valid fallback book source.
- *
- * @private internal helper for imported-agent fallback books
- */
-function createMissingImportedAgentFallback(
-    agentUrl: string_agent_url,
-    attempts: number,
-    error: unknown,
-): string_book {
-    const failureMessage = normalizeImportFailureMessage(agentUrl, error);
-
-    return padBook(
-        validateBook(
-            spaceTrim(
-                `
-                    Not found agent
-
-                    NOTE This agent was supposed to be imported from ${agentUrl}, but it can not be loaded after ${attempts} attempts because of ${failureMessage}
-                    CLOSED
-                `,
-            ),
-        ),
-    );
-}
-
 /**
  * Builds the stable cache key used for import-with-fallback memoization.
  *

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

@@ -0,0 +1,167 @@
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+
+/**
+ * Parsed local agent route reference.
+ */
+export type LocalAgentRouteReference = {
+    /**
+     * Matched same-instance server origin.
+     */
+    readonly localServerUrl: string;
+
+    /**
+     * Decoded route identifier after `/agents/`.
+     */
+    readonly agentIdentifier: string;
+};
+
+/**
+ * Exact local route alias for one agent URL.
+ */
+export type LocalAgentUrlReference = LocalAgentRouteReference & {
+    /**
+     * Normalized exact local agent URL.
+     */
+    readonly agentUrl: string;
+};
+
+/**
+ * Normalizes same-instance server URLs for route matching.
+ *
+ * @param localServerUrls - Raw server URLs.
+ * @returns Unique normalized origins without trailing slash.
+ */
+export function normalizeLocalServerUrls(localServerUrls: ReadonlyArray<string>): ReadonlyArray<string> {
+    return [
+        ...new Set(
+            localServerUrls
+                .map((localServerUrl) => normalizeServerUrl(localServerUrl))
+                .filter((localServerUrl) => localServerUrl.length > 0),
+        ),
+    ];
+}
+
+/**
+ * Normalizes exact local agent URL aliases for route matching.
+ *
+ * @param localAgentUrls - Raw local agent URLs.
+ * @returns Unique normalized route references.
+ */
+export function normalizeLocalAgentUrlReferences(
+    localAgentUrls: ReadonlyArray<string_agent_url>,
+): ReadonlyArray<LocalAgentUrlReference> {
+    const localAgentUrlReferences: Array<LocalAgentUrlReference> = [];
+    const seenAgentUrls = new Set<string>();
+
+    for (const localAgentUrl of localAgentUrls) {
+        const localAgentRouteReference = parseLocalAgentRouteReference(localAgentUrl);
+
+        if (!localAgentRouteReference) {
+            continue;
+        }
+
+        const normalizedAgentUrl = createLocalAgentUrl(
+            localAgentRouteReference.localServerUrl,
+            localAgentRouteReference.agentIdentifier,
+        );
+
+        if (seenAgentUrls.has(normalizedAgentUrl)) {
+            continue;
+        }
+
+        seenAgentUrls.add(normalizedAgentUrl);
+        localAgentUrlReferences.push({
+            ...localAgentRouteReference,
+            agentUrl: normalizedAgentUrl,
+        });
+    }
+
+    return localAgentUrlReferences;
+}
+
+/**
+ * Extracts a local agent identifier from a same-instance agent URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @param localServerUrls - Normalized same-instance server origins.
+ * @param localAgentUrlReferences - Exact agent URL aliases that should resolve locally.
+ * @returns Route reference or `null` when the URL belongs to another server.
+ */
+export function resolveLocalAgentRouteReference(
+    agentUrl: string_agent_url,
+    localServerUrls: ReadonlyArray<string>,
+    localAgentUrlReferences: ReadonlyArray<LocalAgentUrlReference>,
+): LocalAgentRouteReference | null {
+    const localAgentRouteReference = parseLocalAgentRouteReference(agentUrl);
+
+    if (!localAgentRouteReference) {
+        return null;
+    }
+
+    if (localServerUrls.includes(localAgentRouteReference.localServerUrl)) {
+        return localAgentRouteReference;
+    }
+
+    const normalizedAgentUrl = createLocalAgentUrl(
+        localAgentRouteReference.localServerUrl,
+        localAgentRouteReference.agentIdentifier,
+    );
+    return (
+        localAgentUrlReferences.find((localAgentUrlReference) => localAgentUrlReference.agentUrl === normalizedAgentUrl) ||
+        null
+    );
+}
+
+/**
+ * Builds one local agent profile URL.
+ *
+ * @param localServerUrl - Same-instance server origin.
+ * @param agentIdentifier - Route agent identifier.
+ * @returns Local agent URL.
+ */
+export function createLocalAgentUrl(localServerUrl: string, agentIdentifier: string): string_agent_url {
+    return `${localServerUrl.replace(/\/+$/g, '')}/agents/${encodeURIComponent(agentIdentifier)}` as string_agent_url;
+}
+
+/**
+ * Normalizes one server URL to its origin.
+ *
+ * @param serverUrl - Raw server URL.
+ * @returns Normalized origin or an empty string when invalid.
+ */
+function normalizeServerUrl(serverUrl: string): string {
+    try {
+        return new URL(serverUrl).origin.replace(/\/+$/g, '');
+    } catch {
+        return serverUrl.replace(/\/+$/g, '');
+    }
+}
+
+/**
+ * Extracts a local route reference from an agent profile URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @returns Route reference or `null` when the URL is not an agent profile route.
+ */
+function parseLocalAgentRouteReference(agentUrl: string_agent_url): LocalAgentRouteReference | null {
+    let parsedAgentUrl: URL;
+
+    try {
+        parsedAgentUrl = new URL(agentUrl);
+    } catch {
+        return null;
+    }
+
+    const localServerUrl = normalizeServerUrl(parsedAgentUrl.origin);
+    const pathSegments = parsedAgentUrl.pathname.split('/').filter(Boolean);
+    const agentIdentifier = pathSegments[0] === 'agents' ? pathSegments[1] : null;
+
+    if (!agentIdentifier) {
+        return null;
+    }
+
+    return {
+        localServerUrl,
+        agentIdentifier: decodeURIComponent(agentIdentifier),
+    };
+}

package/apps/agents-server/src/utils/localChatRunner/processLocalUserChatJob.ts

@@ -9,11 +9,11 @@ import { getUserChat } from '../userChat/getUserChat';
 import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
-import { createUserChatRunnerProgressCard } from '../userChat/createUserChatRunnerProgressCard';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
 import { createUserChatRunnerThreadMessages } from '../userChat/userChatMessageLifecycle';
+import { runWithTaskTerminalCapture } from '../taskTerminal/runWithTaskTerminalCapture';
 import {
     createLocalUserChatJobMetadata,
     getLocalUserChatJobMetadata,
@@ -45,6 +45,15 @@ export type ProcessLocalUserChatJobResult = {
  * Processes one UserChatJob through the local message-folder runner contract.
  */
 export async function processLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessLocalUserChatJobResult> {
+    return await runWithTaskTerminalCapture(job.id, () => processLocalUserChatJobWithinTerminalCapture(job));
+}
+
+/**
+ * Processes one local job while its console output is mirrored into the task terminal log.
+ */
+async function processLocalUserChatJobWithinTerminalCapture(
+    job: UserChatJobRecord,
+): Promise<ProcessLocalUserChatJobResult> {
     try {
         if (job.status === 'COMPLETED' || job.status === 'CANCELLED') {
             return { didMutate: false, outcome: 'ignored' };
@@ -120,6 +129,15 @@ export async function processNextLocalUserChatJob(
  * Enqueues one local queued job into the current agent folder.
  */
 async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessLocalUserChatJobResult> {
+    return await runWithTaskTerminalCapture(job.id, () => enqueueLocalUserChatJobWithinTerminalCapture(job));
+}
+
+/**
+ * Enqueues one local job while its console output is mirrored into the task terminal log.
+ */
+async function enqueueLocalUserChatJobWithinTerminalCapture(
+    job: UserChatJobRecord,
+): Promise<ProcessLocalUserChatJobResult> {
     const [chat, agentSourceSnapshot] = await Promise.all([
         getUserChat({
             userId: job.userId,
@@ -144,7 +162,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         throw new Error(`User message "${job.userMessageId}" was not found in chat "${job.chatId}".`);
     }
 
-    const threadMessages = createUserChatRunnerThreadMessages({
+    const threadMessages = await createUserChatRunnerThreadMessages({
         messages: chat.messages,
         userMessageId: job.userMessageId,
         resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,
@@ -176,10 +194,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
             isComplete: false,
             lifecycleState: 'running',
             lifecycleError: undefined,
-            progressCard: createUserChatRunnerProgressCard({
-                runnerKind: 'local',
-                phase: 'queued_for_runner',
-            }),
+            progressCard: undefined,
         }),
     });