@promptbook/cli 0.113.0-1 → 0.113.0-10

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

@@ -0,0 +1,246 @@
+import type { Page } from 'playwright';
+import type { AdminChatTaskRecord } from './chatTasksAdmin';
+import type { UserInfo } from './getCurrentUser';
+import { appendTaskTerminalLogLine, markTaskTerminalLogFinished } from './taskTerminal/taskTerminalLog';
+
+/**
+ * Prefix for browser-preview session identifiers created by the citation preview UI.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX = 'page-preview-';
+
+/**
+ * Pattern accepted for client-created page-preview session identifiers.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN = /^page-preview-[a-z0-9-]{16,80}$/;
+
+/**
+ * Queue name used when active browser previews are surfaced in the admin task manager.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME = 'page-preview-browser';
+
+/**
+ * Agent label used by the task manager for browser-preview rows.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME = 'Browser preview';
+
+/**
+ * In-memory record for one live browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserSession = {
+    readonly id: string;
+    readonly url: string;
+    readonly userId: number;
+    readonly username: string | null;
+    readonly createdAt: string;
+    readonly startedAt: string;
+    readonly processId: number | null;
+    page: Page | null;
+    viewport: PagePreviewBrowserViewport | null;
+    updatedAt: string;
+    lastFrameAt: string | null;
+};
+
+/**
+ * Browser viewport used to convert pointer ratios into Playwright coordinates.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewBrowserViewport = {
+    readonly width: number;
+    readonly height: number;
+};
+
+/**
+ * Options used when registering one browser preview stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type RegisterPagePreviewBrowserSessionOptions = {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly user: UserInfo;
+};
+
+/**
+ * Shared in-memory browser-preview registry.
+ *
+ * The route streams are short-lived and tied to the current Node process, so a
+ * durable database row would create stale task-manager entries after restarts.
+ *
+ * @private internal constant of Agents Server page-preview streaming
+ */
+const pagePreviewBrowserSessions = new Map<string, PagePreviewBrowserSession>();
+
+/**
+ * Creates a normalized page-preview browser session id.
+ *
+ * @param requestedSessionId - Optional client-created session id.
+ * @returns Valid session id or `null` when the supplied value is invalid.
+ */
+export function normalizePagePreviewBrowserSessionId(requestedSessionId: string | null): string | null {
+    if (!requestedSessionId) {
+        return null;
+    }
+
+    const normalizedSessionId = requestedSessionId.trim().toLowerCase();
+    return PAGE_PREVIEW_BROWSER_SESSION_ID_PATTERN.test(normalizedSessionId) ? normalizedSessionId : null;
+}
+
+/**
+ * Registers or replaces one active browser preview session.
+ *
+ * @param options - Session metadata.
+ * @returns Registered session snapshot.
+ */
+export function registerPagePreviewBrowserSession(
+    options: RegisterPagePreviewBrowserSessionOptions,
+): PagePreviewBrowserSession {
+    const now = new Date().toISOString();
+    const previousSession = pagePreviewBrowserSessions.get(options.sessionId);
+    if (previousSession?.page) {
+        void previousSession.page.close().catch(() => undefined);
+    }
+
+    const session: PagePreviewBrowserSession = {
+        id: options.sessionId,
+        url: options.url,
+        userId: options.user.id ?? 0,
+        username: options.user.username,
+        createdAt: now,
+        startedAt: now,
+        updatedAt: now,
+        lastFrameAt: null,
+        processId: typeof process.pid === 'number' ? process.pid : null,
+        page: null,
+        viewport: null,
+    };
+
+    pagePreviewBrowserSessions.set(options.sessionId, session);
+    appendTaskTerminalLogLine(
+        options.sessionId,
+        `Started live browser preview of ${options.url} for user #${session.userId} (${session.username || 'unknown'}).`,
+    );
+    return session;
+}
+
+/**
+ * Attaches the Playwright page used by one live browser preview.
+ *
+ * @param sessionId - Active session id.
+ * @param page - Playwright page bound to the stream.
+ * @param viewport - Viewport used by the stream.
+ */
+export function attachPagePreviewBrowserSessionPage(
+    sessionId: string,
+    page: Page,
+    viewport: PagePreviewBrowserViewport,
+): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    session.page = page;
+    session.viewport = viewport;
+    session.updatedAt = new Date().toISOString();
+    appendTaskTerminalLogLine(
+        sessionId,
+        `Browser page attached with a ${viewport.width}x${viewport.height} viewport, streaming frames.`,
+    );
+}
+
+/**
+ * Marks that one stream frame has been delivered.
+ *
+ * @param sessionId - Active session id.
+ */
+export function markPagePreviewBrowserSessionFrame(sessionId: string): void {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return;
+    }
+
+    const now = new Date().toISOString();
+    session.lastFrameAt = now;
+    session.updatedAt = now;
+}
+
+/**
+ * Removes one browser preview session from the active registry.
+ *
+ * @param sessionId - Active session id.
+ */
+export function finishPagePreviewBrowserSession(sessionId: string): void {
+    if (pagePreviewBrowserSessions.delete(sessionId)) {
+        appendTaskTerminalLogLine(sessionId, 'Browser preview session finished.');
+        markTaskTerminalLogFinished(sessionId, { isSuccessful: true });
+    }
+}
+
+/**
+ * Returns the active browser preview session when owned by the current user.
+ *
+ * @param sessionId - Browser preview session id.
+ * @param user - Current authenticated user.
+ * @returns Session or `null` when missing or owned by a different user.
+ */
+export function findUserPagePreviewBrowserSession(
+    sessionId: string,
+    user: UserInfo,
+): PagePreviewBrowserSession | null {
+    const session = pagePreviewBrowserSessions.get(sessionId);
+    if (!session) {
+        return null;
+    }
+
+    if ((user.id ?? 0) !== session.userId || user.username !== session.username) {
+        return null;
+    }
+
+    return session;
+}
+
+/**
+ * Lists active browser preview sessions as admin task-manager rows.
+ *
+ * @returns Task-manager rows for streams currently attached to this process.
+ */
+export function listPagePreviewBrowserAdminTasks(): Array<AdminChatTaskRecord> {
+    return Array.from(pagePreviewBrowserSessions.values()).map((session) => ({
+        id: session.id,
+        kind: 'BROWSER_PREVIEW',
+        status: 'RUNNING',
+        createdAt: session.createdAt,
+        queuedAt: session.createdAt,
+        startedAt: session.startedAt,
+        updatedAt: session.updatedAt,
+        finishedAt: null,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: session.lastFrameAt,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: null,
+        lastErrorDetails: session.url,
+        userId: session.userId,
+        username: session.username,
+        agentPermanentId: PAGE_PREVIEW_BROWSER_SESSION_ID_PREFIX,
+        agentName: PAGE_PREVIEW_BROWSER_TASK_AGENT_NAME,
+        chatId: session.url,
+        workerId: session.processId === null ? null : String(session.processId),
+        queueName: PAGE_PREVIEW_BROWSER_TASK_QUEUE_NAME,
+    }));
+}

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

@@ -3,7 +3,7 @@ import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-sour
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
 import { parseAgentSource } from '../../../../src/book-2.0/agent-source/parseAgentSource';
 import { resolveTeamCapabilitiesFromAgentSource } from './agentReferenceResolver/resolveTeamCapabilitiesFromAgentSource';
-import { resolveInheritedAgentSource } from './resolveInheritedAgentSource';
+import { resolveInheritedAgentSource, type AgentSourceImporter } from './resolveInheritedAgentSource';
 
 /**
  * Options for deriving the canonical resolved agent state from an editable source.
@@ -33,6 +33,11 @@ export type ResolveAgentStateFromSourceOptions = {
      * Retry configuration used when loading imported agents from federated servers.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
 /**
@@ -112,6 +117,7 @@ export async function resolveAgentStateFromSource(
         currentAgentAliases: options.currentAgentAliases,
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration: options.federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
     const resolvedAgentProfile = parseAgentSource(resolvedAgentSource);
     const resolvedTeamCapabilities = await resolveTeamCapabilitiesFromAgentSource(

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

@@ -231,8 +231,42 @@ type ResolveInheritedAgentSourceOptions = ImportAgentOptions & {
      * Retry configuration used for federated imported-agent loading.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+    /**
+     * Optional same-instance source importer used before falling back to HTTP import.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
+/**
+ * Context passed to a custom agent source importer.
+ */
+export type AgentSourceImporterContext = {
+    /**
+     * Commitment that requested the imported source.
+     */
+    readonly commitmentType: 'FROM' | 'IMPORT';
+
+    /**
+     * Import options propagated from the current resolution pass.
+     */
+    readonly importAgentOptions: ImportAgentOptions;
+
+    /**
+     * Retry configuration used by the default HTTP importer.
+     */
+    readonly federatedAgentImportConfiguration: FederatedAgentImportConfiguration;
+};
+
+/**
+ * Imports one agent source before the resolver falls back to the default HTTP importer.
+ *
+ * Return `null` when the importer does not own the given URL.
+ */
+export type AgentSourceImporter = (
+    agentUrl: string_agent_url,
+    context: AgentSourceImporterContext,
+) => Promise<string_book | null>;
+
 /**
  * Parent inheritance state derived before rewriting the source body.
  */
@@ -277,6 +311,11 @@ type AgentImportContext = {
      */
     readonly importAgentOptions: ImportAgentOptions;
 
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
+
     /**
      * Original resolution options used for cycle detection.
      */
@@ -364,6 +403,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
             recursionLevel: options?.recursionLevel || 0,
             inheritancePath: createResolutionLineage(options),
         },
+        agentSourceImporter: options?.agentSourceImporter,
         resolutionOptions: options,
     };
 }
@@ -427,11 +467,20 @@ async function importAgentCorpus(
 ): Promise<string> {
     assertNoResolutionCycle(agentUrl, commitmentType, context.resolutionOptions);
 
-    const importedAgentSource = await importAgentWithFallback(
-        agentUrl,
-        context.importAgentOptions,
-        context.federatedAgentImportConfiguration,
-    );
+    const locallyImportedAgentSource = context.agentSourceImporter
+        ? await context.agentSourceImporter(agentUrl, {
+              commitmentType,
+              importAgentOptions: context.importAgentOptions,
+              federatedAgentImportConfiguration: context.federatedAgentImportConfiguration,
+          })
+        : null;
+    const importedAgentSource =
+        locallyImportedAgentSource ??
+        (await importAgentWithFallback(
+            agentUrl,
+            context.importAgentOptions,
+            context.federatedAgentImportConfiguration,
+        ));
 
     return getAgentSourceCorpus(importedAgentSource as string_book);
 }

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

@@ -1,6 +1,7 @@
 import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
 import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
 import { resolveBookScopedAgentContext, type ResolvedBookScopedAgentContext } from './agentReferenceResolver/bookScopedAgentReferences';
+import { createLocalAgentSourceImporter } from './createLocalAgentSourceImporter';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getWellKnownAgentUrl } from './getWellKnownAgentUrl';
 import { resolveAgentStateFromSource, type ResolvedAgentState } from './resolveAgentStateFromSource';
@@ -46,12 +47,22 @@ export async function resolveServerAgentContext(
 ): Promise<ResolvedServerAgentContext> {
     const bookScopedAgentContext = await resolveBookScopedAgentContext(options);
     const federatedAgentImportConfiguration = await loadFederatedAgentImportConfiguration();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: options.collection,
+        localServerUrls: [options.localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: options.fallbackResolver,
+        federatedAgentImportConfiguration,
+    });
     const resolvedAgentState = await resolveAgentStateFromSource(bookScopedAgentContext.unresolvedAgentSource, {
-        adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+        adamAgentUrl,
         canonicalAgentUrl: bookScopedAgentContext.canonicalAgentUrl,
         currentAgentAliases: bookScopedAgentContext.currentAgentAliases,
         agentReferenceResolver: bookScopedAgentContext.scopedAgentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter,
     });
 
     return {

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

@@ -30,7 +30,7 @@ export type ResolvedStoredAgentState<TAgent extends StoredAgentSourceRecord> = T
  */
 export type ResolveStoredAgentStateOptions = Pick<
     ResolveAgentStateFromSourceOptions,
-    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration'
+    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration' | 'agentSourceImporter'
 > & {
     /**
      * Public/current server origin used to build canonical local agent URLs.
@@ -91,6 +91,7 @@ export async function resolveStoredAgentState<TAgent extends StoredAgentSourceRe
         currentAgentAliases: createCanonicalLocalAgentAliases(agent, options.localServerUrl),
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
 
     return {

package/apps/agents-server/src/utils/resourceMonitor/formatResourceMonitorValue.ts

@@ -0,0 +1,50 @@
+/**
+ * Byte units used for compact resource values.
+ */
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const;
+
+/**
+ * Converts a nullable byte count into a compact display value.
+ *
+ * @param bytes - Byte count.
+ * @returns Human-readable byte value.
+ */
+export function formatResourceBytes(bytes: number | null | undefined): string {
+    if (bytes === null || bytes === undefined || !Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+
+    const exponent = Math.min(BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / Math.pow(1024, exponent);
+    const precision = value >= 10 || exponent === 0 ? 0 : 1;
+
+    return `${value.toFixed(precision)} ${BYTE_UNITS[exponent]}`;
+}
+
+/**
+ * Converts a nullable ratio into a display percentage.
+ *
+ * @param ratio - Ratio from `0` to `1`.
+ * @returns Human-readable percentage or fallback.
+ */
+export function formatResourcePercentage(ratio: number | null | undefined): string {
+    if (ratio === null || ratio === undefined || !Number.isFinite(ratio)) {
+        return 'Not available';
+    }
+
+    return `${(ratio * 100).toFixed(0)}%`;
+}
+
+/**
+ * Converts a nullable byte-per-second count into a compact display value.
+ *
+ * @param bytesPerSecond - Byte count per second.
+ * @returns Human-readable rate or fallback.
+ */
+export function formatResourceRate(bytesPerSecond: number | null | undefined): string {
+    if (bytesPerSecond === null || bytesPerSecond === undefined || !Number.isFinite(bytesPerSecond)) {
+        return 'Not available';
+    }
+
+    return `${formatResourceBytes(bytesPerSecond)}/s`;
+}

package/apps/agents-server/src/utils/resourceMonitor/readCpuResourceUsage.ts

@@ -0,0 +1,75 @@
+import os from 'node:os';
+
+import { DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS } from './resourceMonitorConstants';
+import { waitForResourceMonitorSample } from './waitForResourceMonitorSample';
+import type { CpuResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Options for reading CPU usage.
+ */
+type ReadCpuResourceUsageOptions = {
+    /**
+     * Whether the current Node.js process CPU usage should be sampled.
+     */
+    readonly isProcessUsageSampled: boolean;
+
+    /**
+     * Optional process CPU sampling duration.
+     */
+    readonly sampleDurationMs?: number;
+};
+
+/**
+ * Reads platform load average and optionally samples current process CPU usage.
+ *
+ * @param options - CPU reader options.
+ * @returns CPU usage snapshot.
+ */
+export async function readCpuResourceUsage({
+    isProcessUsageSampled,
+    sampleDurationMs = DEFAULT_PROCESS_CPU_SAMPLE_DURATION_MS,
+}: ReadCpuResourceUsageOptions): Promise<CpuResourceUsage> {
+    const coreCount = Math.max(os.cpus().length, 1);
+    const isLoadAverageAvailable = process.platform !== 'win32';
+    const [averageLoadOneMinute, averageLoadFiveMinutes, averageLoadFifteenMinutes] = isLoadAverageAvailable
+        ? os.loadavg()
+        : [null, null, null];
+    const loadRatio = averageLoadOneMinute === null ? null : averageLoadOneMinute / coreCount;
+    const processUsageRatio = isProcessUsageSampled
+        ? await sampleProcessCpuUsageRatio(coreCount, sampleDurationMs)
+        : null;
+
+    return {
+        coreCount,
+        averageLoadOneMinute,
+        averageLoadFiveMinutes,
+        averageLoadFifteenMinutes,
+        loadRatio,
+        processUsageRatio,
+    };
+}
+
+/**
+ * Samples current Node.js process CPU usage over a short interval.
+ *
+ * @param coreCount - Logical CPU core count.
+ * @param sampleDurationMs - Sampling duration in milliseconds.
+ * @returns Process CPU ratio across all logical cores.
+ */
+async function sampleProcessCpuUsageRatio(coreCount: number, sampleDurationMs: number): Promise<number | null> {
+    const startedUsage = process.cpuUsage();
+    const startedAtNanoseconds = process.hrtime.bigint();
+
+    await waitForResourceMonitorSample(sampleDurationMs);
+
+    const elapsedMicroseconds = Number(process.hrtime.bigint() - startedAtNanoseconds) / 1000;
+    if (!Number.isFinite(elapsedMicroseconds) || elapsedMicroseconds <= 0) {
+        return null;
+    }
+
+    const usage = process.cpuUsage(startedUsage);
+    const usedMicroseconds = usage.user + usage.system;
+    const processUsageRatio = usedMicroseconds / elapsedMicroseconds / Math.max(coreCount, 1);
+
+    return Number.isFinite(processUsageRatio) ? Math.max(processUsageRatio, 0) : null;
+}

package/apps/agents-server/src/utils/resourceMonitor/readDiskResourceUsage.ts

@@ -0,0 +1,42 @@
+import { statfs } from 'node:fs/promises';
+
+import type { DiskResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads disk usage for the filesystem that hosts the server process.
+ *
+ * @param inspectedPath - Filesystem path to inspect.
+ * @returns Disk usage snapshot.
+ */
+export async function readDiskResourceUsage(inspectedPath: string = process.cwd()): Promise<DiskResourceUsage> {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSize = fileSystemStats.bsize;
+        const totalBytes = fileSystemStats.blocks * blockSize;
+        const freeBytes = fileSystemStats.bfree * blockSize;
+        const availableBytes = fileSystemStats.bavail * blockSize;
+        const usedBytes = Math.max(totalBytes - freeBytes, 0);
+
+        return {
+            inspectedPath,
+            totalBytes,
+            freeBytes,
+            availableBytes,
+            usedBytes,
+            usedRatio: totalBytes > 0 ? usedBytes / totalBytes : null,
+            availableRatio: totalBytes > 0 ? availableBytes / totalBytes : null,
+            errorMessage: null,
+        };
+    } catch (error) {
+        return {
+            inspectedPath,
+            totalBytes: null,
+            freeBytes: null,
+            availableBytes: null,
+            usedBytes: null,
+            usedRatio: null,
+            availableRatio: null,
+            errorMessage: error instanceof Error ? error.message : 'Disk usage is not available.',
+        };
+    }
+}

package/apps/agents-server/src/utils/resourceMonitor/readMemoryResourceUsage.ts

@@ -0,0 +1,28 @@
+import os from 'node:os';
+
+import type { MemoryResourceUsage } from './resourceMonitorTypes';
+
+/**
+ * Reads current host and process memory usage.
+ *
+ * @returns Memory usage snapshot.
+ */
+export function readMemoryResourceUsage(): MemoryResourceUsage {
+    const totalBytes = os.totalmem();
+    const freeBytes = os.freemem();
+    const usedBytes = Math.max(totalBytes - freeBytes, 0);
+    const memoryUsage = process.memoryUsage();
+
+    return {
+        totalBytes,
+        freeBytes,
+        usedBytes,
+        usedRatio: totalBytes > 0 ? usedBytes / totalBytes : 0,
+        availableRatio: totalBytes > 0 ? freeBytes / totalBytes : 0,
+        processRssBytes: memoryUsage.rss,
+        processHeapUsedBytes: memoryUsage.heapUsed,
+        processHeapTotalBytes: memoryUsage.heapTotal,
+        processExternalBytes: memoryUsage.external,
+        processArrayBuffersBytes: memoryUsage.arrayBuffers ?? 0,
+    };
+}