@promptbook/cli 0.112.0-99 → 0.112.0

package/apps/agents-server/src/tools/$provideAgentCollectionForServer.ts

@@ -36,7 +36,7 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
     */
 
     const supabase = $provideSupabaseForServer();
-    const { publicUrl, tablePrefix } = await $provideServer();
+    const { tablePrefix } = await $provideServer();
     const cachedAgentCollection = agentCollectionsByTablePrefix.get(tablePrefix);
 
     if (cachedAgentCollection) {
@@ -50,16 +50,9 @@ export async function $provideAgentCollectionForServer(): Promise<AgentCollectio
 
     agentCollectionsByTablePrefix.set(tablePrefix, providedCollection);
 
-    const [{ attachAgentPreparationScheduling }, { scheduleDefaultFederatedAgentsSync }] = await Promise.all([
-        import('../utils/attachAgentPreparationScheduling'),
-        import('../utils/defaultFederatedAgents/scheduleDefaultFederatedAgentsSync'),
-    ]);
+    const { attachAgentPreparationScheduling } = await import('../utils/attachAgentPreparationScheduling');
 
     attachAgentPreparationScheduling(providedCollection, { tablePrefix });
-    scheduleDefaultFederatedAgentsSync({
-        tablePrefix,
-        localServerUrl: publicUrl.href,
-    });
 
     return providedCollection;
 }

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -1,43 +1,215 @@
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import { DigitalOceanSpaces } from '../utils/cdn/classes/DigitalOceanSpaces';
 import { TrackedFilesStorage } from '../utils/cdn/classes/TrackedFilesStorage';
 import { VercelBlobStorage } from '../utils/cdn/classes/VercelBlobStorage';
 import { IIFilesStorageWithCdn } from '../utils/cdn/interfaces/IFilesStorage';
 
 /**
- * Cache of CDN instance
+ * Options controlling CDN storage construction for the current server request.
+ */
+export type ProvideCdnForServerOptions = {
+    /**
+     * Public URL used when generating file links.
+     */
+    readonly cdnPublicUrl?: URL;
+};
+
+/**
+ * Region expected by the bundled VersityGW S3-compatible storage.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const SELF_CONTAINED_S3_DEFAULT_REGION = 'us-east-1';
+
+/**
+ * Legacy fallback used by Cloudflare R2-style external S3 configuration.
+ *
+ * @private internal default for `$provideCdnForServer`
+ */
+const EXTERNAL_S3_DEFAULT_REGION = 'auto';
+
+/**
+ * Cache of CDN instances by public URL.
  *
  * @private internal cache for `$provideCdnForServer`
  */
-let cdn: IIFilesStorageWithCdn | null = null;
+const cdnByPublicUrl = new Map<string, IIFilesStorageWithCdn>();
 
 /**
  * Provides a CDN storage interface for server-side file operations, with caching to reuse instances.
+ *
+ * @param options - Optional request-aware CDN public URL override.
+ * @returns CDN storage interface.
  */
-export function $provideCdnForServer(): IIFilesStorageWithCdn {
-    if (!cdn) {
-        const inner = new VercelBlobStorage({
-            token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
-            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
-        });
+export function $provideCdnForServer(options: ProvideCdnForServerOptions = {}): IIFilesStorageWithCdn {
+    const cdnPublicUrl = options.cdnPublicUrl || resolveConfiguredCdnPublicUrl();
+    const cdnCacheKey = cdnPublicUrl.href;
+    let cdn = cdnByPublicUrl.get(cdnCacheKey);
 
+    if (!cdn) {
+        const inner = createCdnStorageForServer(cdnPublicUrl);
         const supabase = $provideSupabaseForServer();
         cdn = new TrackedFilesStorage(inner, supabase);
+        cdnByPublicUrl.set(cdnCacheKey, cdn);
+    }
 
-        /*
-        cdn = new DigitalOceanSpaces({
+    return cdn;
+}
+
+/**
+ * Creates the configured CDN storage implementation for server-side file operations.
+ *
+ * @param cdnPublicUrl - Public URL used to build deterministic file links.
+ * @private helper of `$provideCdnForServer`
+ */
+function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
+    if (isS3CompatibleStorageSelected()) {
+        return new DigitalOceanSpaces({
             bucket: process.env.CDN_BUCKET!,
-            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX!,
+            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
             endpoint: process.env.CDN_ENDPOINT!,
             accessKeyId: process.env.CDN_ACCESS_KEY_ID!,
             secretAccessKey: process.env.CDN_SECRET_ACCESS_KEY!,
-            cdnPublicUrl: new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!),
+            cdnPublicUrl,
             gzip: true,
+            forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
+            region: resolveS3CompatibleStorageRegion(),
+            // [✨🏣] For self-contained S3: hash-based CDN keys get a public URL that
+            // omits the internal bucket and pathPrefix so users can't infer the storage
+            // structure. The `/s3/` segment is preserved so nginx routes those requests
+            // to the Next.js hash-file route instead of directly to VersityGW.
+            publicCdnBaseUrl: isSelfContainedS3StorageSelected()
+                ? resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl)
+                : undefined,
         });
-        */
     }
 
-    return cdn;
+    return new VercelBlobStorage({
+        token: process.env.VERCEL_BLOB_READ_WRITE_TOKEN!,
+        pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX || '',
+        cdnPublicUrl,
+    });
+}
+
+/**
+ * Derives the public base URL used for hash-based file URLs on self-contained S3.
+ *
+ * Strips the bucket segment from the configured CDN URL so that the public URL
+ * exposes only the `/s3/` prefix — the internal bucket name and path prefix
+ * remain hidden from users.
+ *
+ * Example: `https://s24.ptbk.io/s3/promptbook-files/` → `https://s24.ptbk.io/s3/`
+ *
+ * [✨🏣] Companion to `isHashBasedCdnKey` in `DigitalOceanSpaces`.
+ *
+ * @private helper of `createCdnStorageForServer`
+ */
+function resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl: URL): URL {
+    return new URL('/s3/', cdnPublicUrl);
+}
+
+/**
+ * Resolves the CDN public URL from environment configuration.
+ *
+ * @returns Configured CDN public URL.
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveConfiguredCdnPublicUrl(): URL {
+    return new URL(process.env.NEXT_PUBLIC_CDN_PUBLIC_URL!);
+}
+
+/**
+ * Resolves the public URL that should be used for CDN links for one server request.
+ *
+ * Self-contained S3 is proxied through the current server domain. The configured
+ * CDN public URL still owns the `/s3/<bucket>` path, but the origin must follow
+ * the active server so uploads are not published under the VPS raw IP address.
+ *
+ * @param serverPublicUrl - Public URL of the active server.
+ * @returns Request-aware CDN public URL.
+ */
+export function resolveCdnPublicUrlForServer(serverPublicUrl: URL): URL {
+    const configuredCdnPublicUrl = resolveConfiguredCdnPublicUrl();
+
+    if (!isSelfContainedS3StorageSelected()) {
+        return configuredCdnPublicUrl;
+    }
+
+    const cdnPublicUrl = new URL(configuredCdnPublicUrl.href);
+    cdnPublicUrl.protocol = serverPublicUrl.protocol;
+    cdnPublicUrl.host = serverPublicUrl.host;
+    cdnPublicUrl.username = '';
+    cdnPublicUrl.password = '';
+
+    return cdnPublicUrl;
+}
+
+/**
+ * Checks whether the current environment should use the S3-compatible storage implementation.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function isS3CompatibleStorageSelected(): boolean {
+    const storageMode = getS3CompatibleStorageMode();
+    const isS3StorageMode =
+        storageMode === 's3' || storageMode === 'external-s3' || storageMode === 'self-contained-s3';
+
+    if (isS3StorageMode) {
+        return hasS3CompatibleStorageConfiguration();
+    }
+
+    return !process.env.VERCEL_BLOB_READ_WRITE_TOKEN && hasS3CompatibleStorageConfiguration();
+}
+
+/**
+ * Resolves the configured S3-compatible storage mode.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function getS3CompatibleStorageMode(): string {
+    return (process.env.PTBK_FILE_STORAGE_MODE || process.env.CDN_PROVIDER || '').toLowerCase();
+}
+
+/**
+ * Checks whether the bundled self-contained S3 storage mode is selected.
+ *
+ * @returns `true` when self-contained S3 is selected.
+ */
+export function isSelfContainedS3StorageSelected(): boolean {
+    return getS3CompatibleStorageMode() === 'self-contained-s3';
+}
+
+/**
+ * Resolves the S3 signing region used by AWS SDK requests.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function resolveS3CompatibleStorageRegion(): string {
+    const configuredRegion = process.env.CDN_REGION?.trim();
+    if (configuredRegion) {
+        return configuredRegion;
+    }
+
+    if (isSelfContainedS3StorageSelected()) {
+        return SELF_CONTAINED_S3_DEFAULT_REGION;
+    }
+
+    return EXTERNAL_S3_DEFAULT_REGION;
+}
+
+/**
+ * Checks whether all S3-compatible storage environment variables are present.
+ *
+ * @private helper of `$provideCdnForServer`
+ */
+function hasS3CompatibleStorageConfiguration(): boolean {
+    return Boolean(
+        process.env.CDN_BUCKET &&
+            process.env.CDN_ENDPOINT &&
+            process.env.CDN_ACCESS_KEY_ID &&
+            process.env.CDN_SECRET_ACCESS_KEY &&
+            process.env.NEXT_PUBLIC_CDN_PUBLIC_URL,
+    );
 }
 
 // TODO: [🏓] Unite `xxxForServer` and `xxxForNode` naming

package/apps/agents-server/src/tools/BrowserConnectionProvider.ts

@@ -1,8 +1,8 @@
 import { mkdir } from 'fs/promises';
 import { BrowserContext, chromium } from 'playwright';
-import { locateChrome } from '../../../../src/executables/browsers/locateChrome';
 import { resolvePromptbookTemporaryPath } from '../../../../src/utils/filesystem/promptbookTemporaryPath';
 import { REMOTE_BROWSER_URL } from '../../config';
+import { createServerChromiumLaunchOptions } from './createServerChromiumLaunchOptions';
 import { retryWithBackoff } from '../utils/retryWithBackoff';
 import {
     extractNetworkErrorCode,
@@ -409,24 +409,7 @@ export class BrowserConnectionProvider {
         const userDataDir = `${DEFAULT_BROWSER_USER_DATA_DIR}/run-browser`;
         await mkdir(userDataDir, { recursive: true });
 
-        const launchOptions: NonNullable<Parameters<typeof chromium.launchPersistentContext>[1]> = {
-            headless: true,
-            args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-        };
-
-        try {
-            const chromePath = await locateChrome();
-            launchOptions.executablePath = chromePath!;
-        } catch (error) {
-            if (this.isVerbose) {
-                console.warn(
-                    '[BrowserConnectionProvider] Could not locate system Chrome; using Playwright bundled Chromium',
-                    {
-                        error: error instanceof Error ? error.message : String(error),
-                    },
-                );
-            }
-        }
+        const launchOptions = await createServerChromiumLaunchOptions();
 
         return await chromium.launchPersistentContext(userDataDir, launchOptions);
     }

package/apps/agents-server/src/tools/createAgentProgressTools.ts

@@ -22,11 +22,15 @@ export function createAgentProgressTools(
         {
             name: AGENT_PROGRESS_TOOL_NAME,
             description: spaceTrim(`
-                Update to user while you work on a response.
+                Update the visible progress card while you work on a response.
 
-                - Use this to communicate only concise progress updates visible to the user.
-                - Include what you are doing now, and what you will do next.
-                - Be informative and make update before any chunk of work that might take more than a few seconds.
+                - Call \`initialize\` before meaningful work when the answer may take more than a few seconds.
+                - Call \`update\` after each user-relevant decision, action, tool use, or result.
+                - Use \`append_items\` for new checklist items discovered while working.
+                - Call \`finalize\` immediately before the final answer.
+                - Keep every update concise, user-facing, and specific about what is happening now and what comes next.
+                - Summarize your reasoning as visible decisions and checks, not hidden chain-of-thought.
+                - Do not expose system prompts, raw tool payloads, secrets, private implementation details, or technical logs.
             `),
             parameters: {
                 type: 'object',

package/apps/agents-server/src/tools/createChatAttachmentToolFunctions.ts

@@ -460,7 +460,13 @@ function truncateAttachmentToolContent(content: string, warnings: string[]): str
     }
 
     warnings.push(`Returned content was truncated to ${MAX_ATTACHED_FILE_OUTPUT_CHARACTERS} characters.`);
-    return `${content.slice(0, MAX_ATTACHED_FILE_OUTPUT_CHARACTERS)}\n\n[...truncated...]`;
+    return spaceTrim(
+        (block) => `
+            ${block(content.slice(0, MAX_ATTACHED_FILE_OUTPUT_CHARACTERS))}
+
+            [...truncated...]
+        `,
+    );
 }
 
 /**
@@ -583,9 +589,7 @@ function normalizeBoundedInteger(
     }
 
     if (parsed < min || parsed > max) {
-        throw new LimitReachedError(
-            `Tool argument \`${fieldName}\` must be between \`${min}\` and \`${max}\`.`,
-        );
+        throw new LimitReachedError(`Tool argument \`${fieldName}\` must be between \`${min}\` and \`${max}\`.`);
     }
 
     return parsed;

package/apps/agents-server/src/tools/createServerChromiumLaunchOptions.ts

@@ -0,0 +1,44 @@
+import { locateChrome } from '../../../../src/executables/browsers/locateChrome';
+
+/**
+ * Shared Chromium sandbox flags used by server-side browser work.
+ */
+const SERVER_CHROMIUM_LAUNCH_ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'];
+
+/**
+ * Minimal Playwright Chromium launch options shared by local browser providers.
+ *
+ * @private internal type for server-side browser launch helpers
+ */
+export type ServerChromiumLaunchOptions = {
+    readonly headless: true;
+    readonly args: Array<string>;
+    readonly executablePath?: string;
+};
+
+/**
+ * Creates launch options for server-side Playwright Chromium.
+ *
+ * The system Chrome executable is preferred when it is available. When Chrome is not installed,
+ * the `executablePath` field is intentionally omitted so Playwright can use its installed Chromium.
+ */
+export async function createServerChromiumLaunchOptions(): Promise<ServerChromiumLaunchOptions> {
+    const chromeExecutablePath = await resolveSystemChromeExecutablePath();
+
+    return {
+        headless: true,
+        args: [...SERVER_CHROMIUM_LAUNCH_ARGS],
+        ...(chromeExecutablePath ? { executablePath: chromeExecutablePath } : {}),
+    };
+}
+
+/**
+ * Resolves the optional system Chrome path without preventing Playwright's bundled fallback.
+ */
+async function resolveSystemChromeExecutablePath(): Promise<string | undefined> {
+    try {
+        return (await locateChrome()) || undefined;
+    } catch {
+        return undefined;
+    }
+}

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

@@ -69,9 +69,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     const tableName = await $getTableName('Agent');
     const { data, error } = await supabase
         .from(tableName)
-        .select(
-            'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId',
-        )
+        .select(OWNED_AGENT_ROW_COLUMNS)
         .eq('userId', userId as never)
         .or(buildAgentNameOrIdFilter(identifier))
         .limit(10);
@@ -80,7 +78,58 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
         throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
     }
 
-    const rows = (data || []) as unknown as OwnedAgentRow[];
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'for this owner');
+}
+
+/**
+ * Loads one agent by permanent id or agent name without an owner restriction.
+ *
+ * Owner-aware callers should use {@link findOwnedAgentByIdentifier}; this helper is reserved for administrative
+ * overrides where the caller has been independently authorized to read or mutate any agent.
+ *
+ * @param identifier - Permanent id or agent name.
+ * @returns Matching agent row or `null` when nothing matches.
+ */
+export async function findAgentByIdentifier(identifier: string): Promise<OwnedAgentRow | null> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(OWNED_AGENT_ROW_COLUMNS)
+        .or(buildAgentNameOrIdFilter(identifier))
+        .limit(10);
+
+    if (error) {
+        throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
+    }
+
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'across agents');
+}
+
+/**
+ * Database columns selected for every agent row exposed by ownership-aware helpers.
+ */
+const OWNED_AGENT_ROW_COLUMNS =
+    'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId';
+
+/**
+ * Disambiguates a list of agent rows that all matched the same identifier.
+ *
+ * Resolution order:
+ * 1. Exact `permanentId` match — always preferred because permanent ids are unique.
+ * 2. Single `agentName` match — preserves the legacy lookup by human-readable name.
+ * 3. Single remaining row — accepts the only candidate found.
+ *
+ * @param rows - Candidate agent rows returned by Supabase.
+ * @param identifier - Identifier that was searched.
+ * @param ambiguityScope - Human-readable scope used in the ambiguity error message.
+ * @returns Best-matching row or `null` when no candidate matches.
+ */
+function pickAgentRowByIdentifier(
+    rows: OwnedAgentRow[],
+    identifier: string,
+    ambiguityScope: string,
+): OwnedAgentRow | null {
     if (rows.length === 0) {
         return null;
     }
@@ -100,7 +149,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     }
 
     throw new Error(
-        `Agent identifier "${identifier}" is ambiguous for this owner. Use the stable \`permanentId\` returned by the API.`,
+        `Agent identifier "${identifier}" is ambiguous ${ambiguityScope}. Use the stable \`permanentId\` returned by the API.`,
     );
 }
 

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -56,15 +56,21 @@ type PseudoAgentRouteTarget = {
 export type AgentRouteTarget = LocalAgentRouteTarget | RemoteAgentRouteTarget | PseudoAgentRouteTarget;
 
 /**
- * Resolves any incoming `/agents/:agentId` token into a canonical target URL.
+ * Resolves any incoming `/agents/:agentId` token into a canonical target URL without memoization.
  *
  * Supported inputs include plain IDs/names, `@name`, `{name}`, `{id}`, and absolute `/agents/...` URLs.
  * Pseudo-agent tokens such as `{User}`, `{Void}`, or `{Null}` resolve to dedicated documentation pages.
  *
  * @param rawReference - Raw decoded route parameter value.
+ * @param options - Optional cache-bypass controls used by create-agent flows.
  * @returns Canonical local/remote route target or `null` when the reference cannot be resolved.
  */
-const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<AgentRouteTarget | null> => {
+async function resolveAgentRouteTargetUncached(
+    rawReference: string,
+    options?: {
+        readonly forceRefresh?: boolean;
+    },
+): Promise<AgentRouteTarget | null> {
     const parsedBookScopedAgentIdentifier = parseBookScopedAgentIdentifier(rawReference);
     if (parsedBookScopedAgentIdentifier) {
         const { publicUrl } = await $provideServer();
@@ -96,7 +102,14 @@ const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<Ag
         };
     }
 
-    const resolver = await $provideAgentReferenceResolver();
+    if (!options?.forceRefresh) {
+        const fastLocalRouteTarget = await resolveFastLocalAgentRouteTarget(normalizedReference, localServerUrl);
+        if (fastLocalRouteTarget) {
+            return fastLocalRouteTarget;
+        }
+    }
+
+    const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
     try {
@@ -137,15 +150,63 @@ const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<Ag
         canonicalAgentId,
         canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
     };
+}
+
+/**
+ * Resolves the common local-agent case without constructing the heavier shared reference resolver.
+ *
+ * Normal page and chat routes almost always target one local agent by its stored name or permanent id.
+ * Handling that case up front keeps route resolution cheap while still falling back to the full TEAM/federation
+ * resolver for aliases, remote agents, and fuzzy matches.
+ *
+ * @param reference - Normalized route/reference text.
+ * @param localServerUrl - Normalized URL of the current Agents Server instance.
+ * @returns Local route target or `null` when a direct lookup does not match.
+ */
+async function resolveFastLocalAgentRouteTarget(
+    reference: string,
+    localServerUrl: string,
+): Promise<AgentRouteTarget | null> {
+    const collection = await $provideAgentCollectionForServer();
+    const directMatch = await collection.findAgentBasicInformation(reference);
+
+    if (!directMatch) {
+        return null;
+    }
+
+    const canonicalAgentId = directMatch.permanentId || directMatch.agentName;
+
+    return {
+        kind: 'local',
+        canonicalAgentId,
+        canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
+    };
+}
+
+/**
+ * Memoized route-target resolver used for normal page rendering.
+ */
+const getCachedAgentRouteTarget = cache(async (rawReference: string): Promise<AgentRouteTarget | null> => {
+    return resolveAgentRouteTargetUncached(rawReference);
 });
 
 /**
  * Resolves any incoming `/agents/:agentId` token into a canonical target URL.
  *
  * @param rawReference - Raw decoded route parameter value.
+ * @param options - Optional cache-bypass controls used by create-agent flows.
  * @returns Canonical local/remote route target or `null` when the reference cannot be resolved.
  */
-export async function resolveAgentRouteTarget(rawReference: string): Promise<AgentRouteTarget | null> {
+export async function resolveAgentRouteTarget(
+    rawReference: string,
+    options?: {
+        readonly forceRefresh?: boolean;
+    },
+): Promise<AgentRouteTarget | null> {
+    if (options?.forceRefresh) {
+        return resolveAgentRouteTargetUncached(rawReference, options);
+    }
+
     return getCachedAgentRouteTarget(rawReference);
 }
 
@@ -248,21 +309,7 @@ async function resolveLocalAgentRouteTarget(
     localServerUrl: string,
 ): Promise<AgentRouteTarget | null> {
     const collection = await $provideAgentCollectionForServer();
-    const agents = await collection.listAgents();
-    const normalizedReference = normalizeAgentName(reference);
-
-    const agentMatch = agents.find((agent: { agentName: string; permanentId?: string }) => {
-        if (agent.agentName === reference || agent.permanentId === reference) {
-            return true;
-        }
-
-        const normalizedAgentName = normalizeAgentName(agent.agentName);
-        if (normalizedAgentName === normalizedReference) {
-            return true;
-        }
-
-        return false;
-    });
+    const agentMatch = await findLocalAgentRouteMatch(collection, reference);
 
     if (!agentMatch) {
         return null;
@@ -276,3 +323,38 @@ async function resolveLocalAgentRouteTarget(
         canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
     };
 }
+
+/**
+ * Finds a local agent route match without loading the whole collection when possible.
+ *
+ * @param collection - Agents collection backing local routes.
+ * @param reference - Normalized route/reference text.
+ * @returns Matching local agent profile or `null`.
+ */
+async function findLocalAgentRouteMatch(
+    collection: Awaited<ReturnType<typeof $provideAgentCollectionForServer>>,
+    reference: string,
+): Promise<{ agentName: string; permanentId?: string | null } | null> {
+    const directMatch = await collection.findAgentBasicInformation(reference);
+    if (directMatch) {
+        return directMatch;
+    }
+
+    const agents = await collection.listAgents();
+    const normalizedReference = normalizeAgentName(reference);
+
+    return (
+        agents.find((agent: { agentName: string; permanentId?: string | null }) => {
+            if (agent.agentName === reference || agent.permanentId === reference) {
+                return true;
+            }
+
+            const normalizedAgentName = normalizeAgentName(agent.agentName);
+            if (normalizedAgentName === normalizedReference) {
+                return true;
+            }
+
+            return false;
+        }) || null
+    );
+}