@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -1,11 +1,14 @@
 import type { Page } from 'playwright';
+import type { PagePreviewViewport } from '../../../../src/book-components/Chat/Chat/pagePreview/PagePreviewViewport';
 import { $provideBrowserForServer } from '../tools/$provideBrowserForServer';
-import type { PagePreviewBrowserViewport } from './pagePreviewBrowserSessions';
+import { createPagePreviewFramePump } from './createPagePreviewFramePump';
 import {
     attachPagePreviewBrowserSessionPage,
     finishPagePreviewBrowserSession,
     markPagePreviewBrowserSessionFrame,
+    updatePagePreviewBrowserSessionViewport,
 } from './pagePreviewBrowserSessions';
+import { startPagePreviewScreencast } from './startPagePreviewScreencast';
 
 /**
  * Boundary used for MJPEG page-preview streams.
@@ -15,25 +18,25 @@ import {
 const PAGE_PREVIEW_STREAM_BOUNDARY = 'pagepreviewboundary';
 
 /**
- * Width of the live browser preview viewport.
+ * Milliseconds between streamed browser frames when falling back to screenshot polling.
  *
  * @private internal constant of Agents Server page-preview streaming
  */
-const PAGE_PREVIEW_VIEWPORT_WIDTH = 1280;
+const PAGE_PREVIEW_FRAME_INTERVAL_MS = 350;
 
 /**
- * Height of the live browser preview viewport.
+ * Minimum milliseconds between two screencast frames (caps the stream at ~15 fps).
  *
  * @private internal constant of Agents Server page-preview streaming
  */
-const PAGE_PREVIEW_VIEWPORT_HEIGHT = 800;
+const PAGE_PREVIEW_MINIMUM_FRAME_INTERVAL_MS = 66;
 
 /**
- * Milliseconds between streamed browser frames.
+ * Milliseconds of inactivity after which the latest frame is re-sent to keep the stream alive.
  *
  * @private internal constant of Agents Server page-preview streaming
  */
-const PAGE_PREVIEW_FRAME_INTERVAL_MS = 350;
+const PAGE_PREVIEW_HEARTBEAT_INTERVAL_MS = 2000;
 
 /**
  * JPEG quality used by the live browser preview stream.
@@ -65,25 +68,39 @@ export type CreatePagePreviewBrowserStreamOptions = {
     readonly request: Request;
     readonly sessionId: string;
     readonly url: string;
+
+    /**
+     * Initial viewport of the streamed page, usually measured from the client preview area.
+     */
+    readonly viewport: PagePreviewViewport;
+
+    /**
+     * Persistent per-agent browser-profile directory, `null` for the shared default profile.
+     *
+     * When the stream runs on an agent profile, everything the user does in the live browser
+     * (like logging into a website) is saved into the agent's persistent browser profile.
+     */
+    readonly browserProfileDirectory?: string | null;
 };
 
 /**
  * Creates a Playwright-backed MJPEG stream for one page-preview browser session.
  *
+ * Frames are sourced from a CDP screencast (pushed on every repaint, smooth for video and
+ * scrolling) with a screenshot-polling fallback when CDP is unavailable. The stream keeps
+ * running until the client disconnects or the page is closed.
+ *
  * @param options - Stream options.
  * @returns Readable multipart stream.
  */
 export function createPagePreviewBrowserStream(options: CreatePagePreviewBrowserStreamOptions): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
-    const viewport: PagePreviewBrowserViewport = {
-        width: PAGE_PREVIEW_VIEWPORT_WIDTH,
-        height: PAGE_PREVIEW_VIEWPORT_HEIGHT,
-    };
 
     return new ReadableStream<Uint8Array>({
         async start(controller) {
             let isStreamOpen = true;
             let page: Page | null = null;
+            let stopFrameSource: (() => void) | null = null;
 
             const closeStream = async (): Promise<void> => {
                 if (!isStreamOpen) {
@@ -91,6 +108,7 @@ export function createPagePreviewBrowserStream(options: CreatePagePreviewBrowser
                 }
 
                 isStreamOpen = false;
+                stopFrameSource?.();
                 finishPagePreviewBrowserSession(options.sessionId);
                 await page?.close().catch(() => undefined);
 
@@ -109,28 +127,84 @@ export function createPagePreviewBrowserStream(options: CreatePagePreviewBrowser
                 { once: true },
             );
 
+            const writeFrame = (frame: Buffer): void => {
+                if (!isStreamOpen) {
+                    return;
+                }
+
+                try {
+                    controller.enqueue(encoder.encode(createPagePreviewFrameHeader(frame.byteLength)));
+                    controller.enqueue(frame);
+                    markPagePreviewBrowserSessionFrame(options.sessionId);
+                } catch {
+                    // The controller may already be closed when the client disconnects mid-frame.
+                }
+            };
+
             try {
-                const browserContext = await $provideBrowserForServer({ sessionId: options.sessionId });
+                const browserContext = await $provideBrowserForServer({
+                    sessionId: options.sessionId,
+                    browserProfileDirectory: options.browserProfileDirectory,
+                });
                 page = await browserContext.newPage();
-                attachPagePreviewBrowserSessionPage(options.sessionId, page, viewport);
+                await page.setViewportSize(options.viewport);
+
+                const framePump = createPagePreviewFramePump({
+                    minimumFrameIntervalMs: PAGE_PREVIEW_MINIMUM_FRAME_INTERVAL_MS,
+                    heartbeatIntervalMs: PAGE_PREVIEW_HEARTBEAT_INTERVAL_MS,
+                    writeFrame,
+                });
 
-                await page.setViewportSize(viewport);
+                const screencast = await startPagePreviewScreencast({
+                    page,
+                    viewport: options.viewport,
+                    jpegQuality: PAGE_PREVIEW_JPEG_QUALITY,
+                    onFrame: framePump.pushFrame,
+                });
+
+                stopFrameSource = () => {
+                    framePump.stop();
+                    void screencast?.stop();
+                };
+
+                const streamedPage = page;
+                attachPagePreviewBrowserSessionPage(options.sessionId, {
+                    page,
+                    viewport: options.viewport,
+                    cdpSession: screencast?.cdpSession ?? null,
+                    applyViewport: async (viewport: PagePreviewViewport) => {
+                        await streamedPage.setViewportSize(viewport);
+                        await screencast?.applyViewport(viewport);
+                        updatePagePreviewBrowserSessionViewport(options.sessionId, viewport);
+                    },
+                });
+
+                // Navigation happens after the screencast starts so the user watches the page load live
                 await page.goto(options.url, {
                     waitUntil: 'domcontentloaded',
                     timeout: PAGE_PREVIEW_NAVIGATION_TIMEOUT_MS,
                 });
 
-                while (isStreamOpen && !options.request.signal.aborted) {
-                    const buffer = await page.screenshot({
+                if (screencast) {
+                    // Prime the stream in case the screencast delivered its first frame before the client attached
+                    const initialFrame = await page.screenshot({
                         type: 'jpeg',
                         quality: PAGE_PREVIEW_JPEG_QUALITY,
                     });
-                    const header = createPagePreviewFrameHeader(buffer.byteLength);
+                    framePump.pushFrame(initialFrame);
 
-                    controller.enqueue(encoder.encode(header));
-                    controller.enqueue(buffer);
-                    markPagePreviewBrowserSessionFrame(options.sessionId);
-                    await waitForNextPagePreviewFrame(options.request.signal);
+                    await waitForPagePreviewStreamEnd(options.request.signal, page);
+                } else {
+                    framePump.stop();
+
+                    while (isStreamOpen && !options.request.signal.aborted && !page.isClosed()) {
+                        const frame = await page.screenshot({
+                            type: 'jpeg',
+                            quality: PAGE_PREVIEW_JPEG_QUALITY,
+                        });
+                        writeFrame(frame);
+                        await waitForNextPagePreviewFrame(options.request.signal);
+                    }
                 }
             } catch (error) {
                 if (!options.request.signal.aborted) {
@@ -154,6 +228,23 @@ function createPagePreviewFrameHeader(byteLength: number): string {
     return `\r\n--${PAGE_PREVIEW_STREAM_BOUNDARY}\r\nContent-Type: image/jpeg\r\nContent-Length: ${byteLength}\r\n\r\n`;
 }
 
+/**
+ * Waits until the stream request aborts or the streamed page closes.
+ *
+ * @param signal - Request abort signal.
+ * @param page - Streamed Playwright page.
+ */
+function waitForPagePreviewStreamEnd(signal: AbortSignal, page: Page): Promise<void> {
+    if (signal.aborted || page.isClosed()) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+        signal.addEventListener('abort', () => resolve(), { once: true });
+        page.once('close', () => resolve());
+    });
+}
+
 /**
  * Waits before sending the next stream frame, resolving early on abort.
  *
@@ -165,15 +256,16 @@ function waitForNextPagePreviewFrame(signal: AbortSignal): Promise<void> {
     }
 
     return new Promise((resolve) => {
-        const timeout = setTimeout(resolve, PAGE_PREVIEW_FRAME_INTERVAL_MS);
-
-        signal.addEventListener(
-            'abort',
-            () => {
-                clearTimeout(timeout);
-                resolve();
-            },
-            { once: true },
-        );
+        const handleAbort = () => {
+            clearTimeout(timeout);
+            resolve();
+        };
+        const timeout = setTimeout(() => {
+            // The listener must not accumulate on the signal across the many frames of one stream
+            signal.removeEventListener('abort', handleAbort);
+            resolve();
+        }, PAGE_PREVIEW_FRAME_INTERVAL_MS);
+
+        signal.addEventListener('abort', handleAbort, { once: true });
     });
 }

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

@@ -0,0 +1,117 @@
+/**
+ * Options of one page-preview frame pump.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewFramePumpOptions = {
+    /**
+     * Minimum milliseconds between two written frames (caps the stream frame rate).
+     */
+    readonly minimumFrameIntervalMs: number;
+
+    /**
+     * Milliseconds of inactivity after which the latest frame is re-sent to keep the
+     * multipart connection alive across proxies.
+     */
+    readonly heartbeatIntervalMs: number;
+
+    /**
+     * Writes one JPEG frame into the multipart stream.
+     */
+    readonly writeFrame: (frame: Buffer) => void;
+};
+
+/**
+ * Pacing gate between a push-based frame source (CDP screencast) and the multipart stream.
+ *
+ * @private internal type of Agents Server page-preview streaming
+ */
+export type PagePreviewFramePump = {
+    /**
+     * Offers one fresh frame; it is written immediately, or replaces the pending frame
+     * when the stream is already at its frame-rate cap.
+     */
+    readonly pushFrame: (frame: Buffer) => void;
+
+    /**
+     * Stops the pump, its scheduled writes, and its heartbeat.
+     */
+    readonly stop: () => void;
+};
+
+/**
+ * Creates a pacing gate that caps the stream frame rate and keeps idle streams alive.
+ *
+ * A push-based source (CDP screencast) can deliver frames faster than the preview needs;
+ * excess frames are dropped in favor of the latest one. When the source goes quiet
+ * (static page), the latest frame is re-sent as a heartbeat.
+ *
+ * @param options - Pump options.
+ * @returns Running frame pump.
+ *
+ * @private internal utility of Agents Server page-preview streaming
+ */
+export function createPagePreviewFramePump(options: PagePreviewFramePumpOptions): PagePreviewFramePump {
+    let latestWrittenFrame: Buffer | null = null;
+    let pendingFrame: Buffer | null = null;
+    let lastWriteAtMs = 0;
+    let scheduledWriteTimeout: NodeJS.Timeout | null = null;
+    let isStopped = false;
+
+    const writeFrameNow = (frame: Buffer): void => {
+        latestWrittenFrame = frame;
+        lastWriteAtMs = Date.now();
+        options.writeFrame(frame);
+    };
+
+    const pushFrame = (frame: Buffer): void => {
+        if (isStopped) {
+            return;
+        }
+
+        const elapsedMs = Date.now() - lastWriteAtMs;
+        if (elapsedMs >= options.minimumFrameIntervalMs) {
+            writeFrameNow(frame);
+            return;
+        }
+
+        pendingFrame = frame;
+        if (scheduledWriteTimeout === null) {
+            scheduledWriteTimeout = setTimeout(() => {
+                scheduledWriteTimeout = null;
+                if (isStopped || pendingFrame === null) {
+                    return;
+                }
+
+                const frameToWrite = pendingFrame;
+                pendingFrame = null;
+                writeFrameNow(frameToWrite);
+            }, Math.max(1, options.minimumFrameIntervalMs - elapsedMs));
+        }
+    };
+
+    const heartbeatInterval = setInterval(() => {
+        if (isStopped || latestWrittenFrame === null) {
+            return;
+        }
+
+        if (Date.now() - lastWriteAtMs >= options.heartbeatIntervalMs) {
+            writeFrameNow(latestWrittenFrame);
+        }
+    }, options.heartbeatIntervalMs);
+    heartbeatInterval.unref?.();
+
+    const stop = (): void => {
+        isStopped = true;
+        if (scheduledWriteTimeout !== null) {
+            clearTimeout(scheduledWriteTimeout);
+            scheduledWriteTimeout = null;
+        }
+
+        clearInterval(heartbeatInterval);
+        latestWrittenFrame = null;
+        pendingFrame = null;
+    };
+
+    return { pushFrame, stop };
+}

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

@@ -13,6 +13,7 @@ import { ParseError } from '../../../../src/errors/ParseError';
 import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { normalizeDomainForMatching } from '../../../../src/utils/validators/url/normalizeDomainForMatching';
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
+import { isSameAgentPermanentId } from './agentIdentifier';
 import { createServerAgentReferenceResolver } from './agentReferenceResolver/createServerAgentReferenceResolver';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getFederatedServers } from './getFederatedServers';
@@ -143,7 +144,8 @@ function createResolverAgentCollection(agents: ReadonlyArray<CustomDomainAgentRo
     const resolveAgent = (agentNameOrPermanentId: string): CustomDomainAgentRow => {
         const agent = agents.find(
             (candidate) =>
-                candidate.agentName === agentNameOrPermanentId || candidate.permanentId === agentNameOrPermanentId,
+                candidate.agentName === agentNameOrPermanentId ||
+                isSameAgentPermanentId(candidate.permanentId, agentNameOrPermanentId),
         );
 
         if (!agent) {

package/apps/agents-server/src/utils/defaultAgents/coreAgentExplanations.ts

@@ -0,0 +1,53 @@
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Curated explanation of why each bundled core agent exists.
+ *
+ * The authoritative set of core agents is defined by the `*.book` files in `agents/default/.core`; this map only adds a
+ * human-readable rationale keyed by the normalized agent name so the Core Agents admin page can explain the purpose of
+ * each one. Core agents that are not listed here fall back to `GENERIC_CORE_AGENT_EXPLANATION`.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export const CORE_AGENT_EXPLANATION_BY_AGENT_NAME: Readonly<Record<string, string>> = {
+    adam: spaceTrim(`
+        **Adam** is the root ancestor agent. Every agent that does not use an explicit \`FROM\` commitment inherits from
+        Adam, so its persona, rules, and base capabilities form the shared foundation of all agents on this server.
+        Removing Adam breaks the default inheritance chain for new and existing agents.
+    `),
+    expert: spaceTrim(`
+        **Expert** is the Book-language specialist that other core agents build on. It carries the knowledge about the
+        Book language used whenever an agent needs to reason about or generate Book sources, and it is the ancestor of
+        the Creator agent.
+    `),
+    creator: spaceTrim(`
+        **Creator** turns any input into a Book-language agent. It powers the "create an agent from a description"
+        flows and inherits from Expert, so it depends on the other core agents being present.
+    `),
+    teacher: spaceTrim(`
+        **Teacher** explains and consults on the Book language and guides users while they write or modify agents. It is
+        used by the self-learning features and inherits from Adam.
+    `),
+};
+
+/**
+ * Fallback explanation shown for a core agent that has no curated rationale.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export const GENERIC_CORE_AGENT_EXPLANATION = spaceTrim(`
+    This is a core agent bundled in the \`.core\` folder. Core agents are used as a shared base building block for the
+    other agents on this server.
+`);
+
+/**
+ * Resolves the human-readable explanation of why one core agent exists.
+ *
+ * @param agentName - Normalized agent name (for example \`adam\`).
+ * @returns Curated explanation, or a generic fallback for unknown core agents.
+ *
+ * @private utility of Agents Server core-agent tracking
+ */
+export function resolveCoreAgentExplanation(agentName: string): string {
+    return CORE_AGENT_EXPLANATION_BY_AGENT_NAME[agentName.toLowerCase()] ?? GENERIC_CORE_AGENT_EXPLANATION;
+}

package/apps/agents-server/src/utils/defaultAgents/resolveDefaultAgentsStatus.ts

@@ -0,0 +1,249 @@
+import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { prepareAgentSourceForPersistence } from '../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/prepareAgentSourceForPersistence';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
+import { resolveCoreAgentExplanation } from './coreAgentExplanations';
+import { loadCoreAgentBooks, loadDefaultAgentBooks, type LoadDefaultAgentBooksOptions } from './loadDefaultAgentBooks';
+
+/**
+ * Identity of one bundled agent book used to match it against a persisted agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type BundledAgentIdentity = {
+    /**
+     * Normalized agent name that matches the persisted `agentName` column.
+     */
+    readonly agentName: string;
+
+    /**
+     * Human-readable title taken from the first line of the book.
+     */
+    readonly title: string;
+
+    /**
+     * Hash the persisted agent would have right after seeding from the repository book.
+     */
+    readonly expectedAgentHash: string;
+};
+
+/**
+ * Presence and repository-difference report for one bundled core agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type CoreAgentReport = BundledAgentIdentity & {
+    /**
+     * Explanation of why this core agent exists.
+     */
+    readonly explanation: string;
+
+    /**
+     * Whether the core agent currently exists on this server.
+     */
+    readonly isPresent: boolean;
+
+    /**
+     * Whether the present core agent differs from the bundled repository book.
+     *
+     * This is informational only — an edited core agent is perfectly fine and must not be treated as a warning.
+     */
+    readonly isDifferentFromRepository: boolean;
+
+    /**
+     * Permanent id of the present agent, used to link to its editable book.
+     */
+    readonly permanentId: string | null;
+};
+
+/**
+ * Presence report for one bundled normal default agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type DefaultAgentReport = BundledAgentIdentity & {
+    /**
+     * Whether the default agent currently exists on this server.
+     */
+    readonly isPresent: boolean;
+
+    /**
+     * Permanent id of the present agent, used to link to its editable book.
+     */
+    readonly permanentId: string | null;
+};
+
+/**
+ * Combined status of the bundled normal default agents and core default agents on the current server.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export type DefaultAgentsStatus = {
+    readonly coreAgents: ReadonlyArray<CoreAgentReport>;
+    readonly defaultAgents: ReadonlyArray<DefaultAgentReport>;
+    readonly isAnyCoreAgentMissing: boolean;
+    readonly isAnyDefaultAgentMissing: boolean;
+};
+
+/**
+ * In-memory cache of parsed bundled identities keyed by the resolved default-agent directory.
+ *
+ * The bundled books never change while the process runs, so parsing them once avoids repeated disk reads on every
+ * admin page render.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+const cachedIdentitiesByDirectoryKey = new Map<
+    string,
+    {
+        readonly defaultAgents: ReadonlyArray<BundledAgentIdentity>;
+        readonly coreAgents: ReadonlyArray<BundledAgentIdentity>;
+    }
+>();
+
+/**
+ * Loads the parsed identities of the bundled default and core agent books.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Parsed identities for the normal default agents and the core agents.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export async function loadBundledAgentIdentities(options: LoadDefaultAgentBooksOptions = {}): Promise<{
+    readonly defaultAgents: ReadonlyArray<BundledAgentIdentity>;
+    readonly coreAgents: ReadonlyArray<BundledAgentIdentity>;
+}> {
+    const directoryKey = options.defaultAgentDirectory ?? '<default>';
+    const cachedIdentities = cachedIdentitiesByDirectoryKey.get(directoryKey);
+    if (cachedIdentities) {
+        return cachedIdentities;
+    }
+
+    const [defaultAgentBooks, coreAgentBooks] = await Promise.all([
+        loadDefaultAgentBooks(options),
+        loadCoreAgentBooks(options),
+    ]);
+    const identities = {
+        defaultAgents: defaultAgentBooks.map(createBundledAgentIdentity),
+        coreAgents: coreAgentBooks.map(createBundledAgentIdentity),
+    };
+    cachedIdentitiesByDirectoryKey.set(directoryKey, identities);
+    return identities;
+}
+
+/**
+ * Resolves the presence and repository-difference status of the bundled default and core agents.
+ *
+ * @param options - Optional explicit default-agent directory.
+ * @returns Combined status used by the home page notices and the Core Agents admin page.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export async function resolveDefaultAgentsStatus(
+    options: LoadDefaultAgentBooksOptions = {},
+): Promise<DefaultAgentsStatus> {
+    const [{ defaultAgents: defaultIdentities, coreAgents: coreIdentities }, presentAgentByName] = await Promise.all([
+        loadBundledAgentIdentities(options),
+        loadPresentAgentsByName(),
+    ]);
+
+    const coreAgents = coreIdentities.map((identity) => {
+        const presentAgent = presentAgentByName.get(identity.agentName);
+        return {
+            ...identity,
+            explanation: resolveCoreAgentExplanation(identity.agentName),
+            isPresent: presentAgent !== undefined,
+            isDifferentFromRepository:
+                presentAgent !== undefined && presentAgent.agentHash !== identity.expectedAgentHash,
+            permanentId: presentAgent?.permanentId ?? null,
+        };
+    });
+    const defaultAgents = defaultIdentities.map((identity) => {
+        const presentAgent = presentAgentByName.get(identity.agentName);
+        return {
+            ...identity,
+            isPresent: presentAgent !== undefined,
+            permanentId: presentAgent?.permanentId ?? null,
+        };
+    });
+
+    return {
+        coreAgents,
+        defaultAgents,
+        isAnyCoreAgentMissing: coreAgents.some((coreAgent) => !coreAgent.isPresent),
+        isAnyDefaultAgentMissing: defaultAgents.some((defaultAgent) => !defaultAgent.isPresent),
+    };
+}
+
+/**
+ * Returns the normalized names of core agents that are missing from a set of present agent names.
+ *
+ * This lightweight check reuses an already-loaded agent list (for example the header organization state) so the admin
+ * menu can flag missing core agents without an extra database query.
+ *
+ * @param coreIdentities - Parsed identities of the bundled core agents.
+ * @param presentAgentNames - Names of the agents already present on the server.
+ * @returns Normalized names of the core agents that are not present.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+export function resolveMissingCoreAgentNames(
+    coreIdentities: ReadonlyArray<BundledAgentIdentity>,
+    presentAgentNames: Iterable<string>,
+): ReadonlyArray<string> {
+    const presentAgentNameSet = new Set(presentAgentNames);
+    return coreIdentities
+        .filter((identity) => !presentAgentNameSet.has(identity.agentName))
+        .map((identity) => identity.agentName);
+}
+
+/**
+ * Builds one bundled agent identity from a raw book source.
+ *
+ * The expected hash is computed exactly the way the seeding flow persists the agent, so a freshly seeded agent is never
+ * reported as differing from the repository.
+ *
+ * @param agentBook - Raw bundled agent book source.
+ * @returns Parsed identity for the bundled agent.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+function createBundledAgentIdentity(agentBook: string_book): BundledAgentIdentity {
+    const { agentProfile } = prepareAgentSourceForPersistence(agentBook);
+    return {
+        agentName: agentProfile.agentName,
+        title: resolveBundledAgentTitle(agentBook) ?? agentProfile.agentName,
+        expectedAgentHash: agentProfile.agentHash,
+    };
+}
+
+/**
+ * Extracts the human-readable title (first non-empty line) from a book source.
+ *
+ * @param agentBook - Raw bundled agent book source.
+ * @returns Title line, or `null` when the book has no visible title.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+function resolveBundledAgentTitle(agentBook: string_book): string | null {
+    for (const line of agentBook.split(/\r?\n/)) {
+        const trimmedLine = line.trim();
+        if (trimmedLine !== '') {
+            return trimmedLine;
+        }
+    }
+    return null;
+}
+
+/**
+ * Loads all active agents on the current server indexed by their normalized name.
+ *
+ * @returns Map from normalized agent name to its basic information.
+ *
+ * @private utility of Agents Server default-agent tracking
+ */
+async function loadPresentAgentsByName(): Promise<ReadonlyMap<string, AgentBasicInformation>> {
+    const collection = await $provideAgentCollectionForServer();
+    const presentAgents = await collection.listAgents();
+    return new Map(presentAgents.map((presentAgent) => [presentAgent.agentName, presentAgent]));
+}