@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -0,0 +1,170 @@
+import { buildExistingAgentChatHref } from './agentRouting/agentRouteHrefs';
+import type { AdminChatTaskRecord } from './chatTasksAdmin';
+import { createServerPublicUrl } from './serverRegistry';
+
+/**
+ * Browser page route of the super-admin standalone VPS self-update panel.
+ *
+ * @private internal admin utility of Agents Server
+ */
+const VPS_SELF_UPDATE_PAGE_ROUTE = '/superadmin/update';
+
+/**
+ * Synthetic task-id prefix shared by every standalone VPS self-update task row.
+ *
+ * Lives in this browser-safe module so both the server-side task mapper and the super-admin update
+ * page build the exact same task id (DRY), letting the update page link back to its own task.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID_PREFIX = 'vps-self-update';
+
+/**
+ * Synthetic task-id prefix shared by VPS server setup and certificate-maintenance task rows.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const VPS_SERVER_SETUP_ADMIN_CHAT_TASK_ID_PREFIX = 'vps-server-setup';
+
+/**
+ * Link from one admin task to the Agents Server page it operates on (task → page).
+ *
+ * Every durable background task acts on exactly one place in the Agents Server — a chat thread, the
+ * self-update panel, a previewed page,... — and this describes the button that opens it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type AdminChatTaskTargetLink = {
+    /**
+     * Href of the page the task operates on.
+     */
+    href: string;
+
+    /**
+     * Short button label.
+     */
+    label: string;
+
+    /**
+     * Accessible button title.
+     */
+    title: string;
+
+    /**
+     * Whether the href points outside the app and should open in a new browser tab.
+     */
+    isExternal: boolean;
+};
+
+/**
+ * Resolves the page one admin task links to (task → page), or `null` when the task has no target.
+ *
+ * This is the single source of truth for the task-manager "open the thing this task is doing" button,
+ * reused by both the task row and the task detail page so the forward link stays consistent (DRY).
+ *
+ * @param task - Admin task-manager row.
+ * @returns Target link, or `null` when the task kind has no linkable page.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolveAdminChatTaskTargetLink(task: AdminChatTaskRecord): AdminChatTaskTargetLink | null {
+    switch (task.kind) {
+        case 'CHAT_COMPLETION':
+        case 'CHAT_TIMEOUT':
+            if (!task.agentPermanentId || !task.chatId) {
+                return null;
+            }
+            {
+                const chatHref = buildExistingAgentChatHref(task.agentPermanentId, task.chatId);
+                const isForeignServer = Boolean(task.serverDomain);
+
+                return {
+                    href: isForeignServer
+                        ? new URL(chatHref, createServerPublicUrl(task.serverDomain!)).toString()
+                        : chatHref,
+                    label: 'Open chat',
+                    title: 'Open the chat thread this task belongs to',
+                    isExternal: isForeignServer,
+                };
+            }
+        case 'VPS_SELF_UPDATE':
+            return {
+                href: VPS_SELF_UPDATE_PAGE_ROUTE,
+                label: 'Open update',
+                title: 'Open the standalone VPS self-update page',
+                isExternal: false,
+            };
+        case 'VPS_SERVER_SETUP':
+            return {
+                href: '/superadmin/servers',
+                label: 'Open servers',
+                title: 'Open the super admin servers page',
+                isExternal: false,
+            };
+        case 'BROWSER_PREVIEW':
+            if (!isAbsoluteHttpUrl(task.chatId)) {
+                return null;
+            }
+            return {
+                href: task.chatId,
+                label: 'Open page',
+                title: 'Open the previewed page in a new tab',
+                isExternal: true,
+            };
+        default:
+            return null;
+    }
+}
+
+/**
+ * Builds the admin href of the detail page dedicated to one task (page → task, and the task's own page).
+ *
+ * @param taskId - Id of the durable task.
+ * @returns Admin task detail page href.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function buildAdminChatTaskDetailHref(taskId: string, serverDomain?: string | null): string {
+    const href = `/admin/task-manager/${encodeURIComponent(taskId)}`;
+    if (!serverDomain) {
+        return href;
+    }
+
+    return `${href}?serverDomain=${encodeURIComponent(serverDomain)}`;
+}
+
+/**
+ * Builds the synthetic admin task id of one standalone VPS self-update run.
+ *
+ * @param jobIdentity - Stable identity of the self-update run.
+ * @returns Synthetic self-update task id.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function buildVpsSelfUpdateAdminChatTaskId(jobIdentity: string): string {
+    return `${VPS_SELF_UPDATE_ADMIN_CHAT_TASK_ID_PREFIX}:${jobIdentity}`;
+}
+
+/**
+ * Builds the synthetic admin task id of one VPS server setup run.
+ *
+ * @param taskIdentity - Stable identity of the setup run.
+ * @returns Synthetic server-setup task id.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function buildVpsServerSetupAdminChatTaskId(taskIdentity: string): string {
+    return `${VPS_SERVER_SETUP_ADMIN_CHAT_TASK_ID_PREFIX}:${taskIdentity}`;
+}
+
+/**
+ * Detects an absolute http(s) URL, used to guard the browser-preview target link.
+ *
+ * @param value - Candidate URL.
+ * @returns `true` when the value is an absolute http(s) URL.
+ *
+ * @private function of `resolveAdminChatTaskTargetLink`
+ */
+function isAbsoluteHttpUrl(value: string): boolean {
+    return /^https?:\/\//i.test(value);
+}

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

@@ -14,7 +14,7 @@ export const PRIVATE_AGENT_FORBIDDEN_MESSAGE = 'This agent is private. Sign in t
 /**
  * Options for resolving access to one agent.
  */
-type ResolveAgentAccessOptions = {
+export type ResolveAgentAccessOptions = {
     /**
      * Request carrying the optional same-server TEAM access header.
      */

package/apps/agents-server/src/utils/agentBook/createAgentBookDownloadFilename.ts

@@ -0,0 +1,51 @@
+import { sanitizeBackupPathSegment } from '../backup/sanitizeBackupPathSegment';
+
+/**
+ * Extension used for single-agent book downloads.
+ */
+const BOOK_FILE_EXTENSION = '.book';
+
+/**
+ * Fallback book filename base used when an agent name sanitizes to an empty value.
+ */
+const DEFAULT_BOOK_FILENAME_BASE = 'Agent book';
+
+/**
+ * Pattern matching non-ASCII characters that need an ASCII `filename=` fallback.
+ */
+const NON_ASCII_CONTENT_DISPOSITION_FILENAME_PATTERN = /[^\x20-\x7e]/g;
+
+/**
+ * Pattern matching quoted-string characters that can break `Content-Disposition`.
+ */
+const QUOTED_CONTENT_DISPOSITION_FILENAME_PATTERN = /["\\]/g;
+
+/**
+ * Creates a filesystem-safe filename for one downloaded agent book.
+ *
+ * @param agentName - Human-readable agent name used as the filename base.
+ * @returns Safe `.book` download filename.
+ */
+export function createAgentBookDownloadFilename(agentName: string): string {
+    const filenameBase = sanitizeBackupPathSegment(agentName, DEFAULT_BOOK_FILENAME_BASE);
+
+    if (filenameBase.toLowerCase().endsWith(BOOK_FILE_EXTENSION)) {
+        return filenameBase;
+    }
+
+    return `${filenameBase}${BOOK_FILE_EXTENSION}`;
+}
+
+/**
+ * Creates a safe `Content-Disposition` value for one downloaded agent book.
+ *
+ * @param filename - Full download filename, including extension.
+ * @returns Header value with an ASCII fallback and RFC 5987 UTF-8 filename.
+ */
+export function createAgentBookDownloadContentDisposition(filename: string): string {
+    const fallbackFilename = filename
+        .replace(NON_ASCII_CONTENT_DISPOSITION_FILENAME_PATTERN, '_')
+        .replace(QUOTED_CONTENT_DISPOSITION_FILENAME_PATTERN, '_');
+
+    return `attachment; filename="${fallbackFilename}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}

package/apps/agents-server/src/utils/agentBook/downloadAgentBook.ts

@@ -0,0 +1,86 @@
+'use client';
+
+import { PromptbookFetchError } from '@promptbook-local/core';
+import { downloadBlob, parseFilenameFromContentDisposition } from '../download/browserFileDownload';
+import { createAgentBookDownloadFilename } from './createAgentBookDownloadFilename';
+
+/**
+ * Fallback error shown when the book download endpoint does not provide details.
+ */
+const DEFAULT_AGENT_BOOK_DOWNLOAD_ERROR_MESSAGE = 'Failed to download agent book.';
+
+/**
+ * Options for downloading one agent book in the browser.
+ */
+type DownloadAgentBookOptions = {
+    /**
+     * Agent route identifier used by the download endpoint.
+     */
+    readonly agentIdentifier: string;
+    /**
+     * Human-readable name used when the server omits a filename header.
+     */
+    readonly filenameAgentName: string;
+};
+
+/**
+ * Minimal API error payload accepted from the book download endpoint.
+ */
+type AgentBookDownloadErrorPayload = {
+    readonly error?: string;
+    readonly message?: string;
+};
+
+/**
+ * Creates the stored-book download API path for one agent.
+ *
+ * @param agentIdentifier - Agent route identifier.
+ * @returns Relative API path for downloading the stored book.
+ */
+function createAgentBookDownloadApiPath(agentIdentifier: string): string {
+    return `/agents/${encodeURIComponent(agentIdentifier)}/api/book/download`;
+}
+
+/**
+ * Reads a user-facing message from a failed book download response.
+ *
+ * @param response - Failed HTTP response.
+ * @returns Friendly error message suitable for a dialog.
+ */
+async function resolveAgentBookDownloadErrorMessage(response: Response): Promise<string> {
+    try {
+        const payload = (await response.json()) as AgentBookDownloadErrorPayload;
+        const message = payload.message || payload.error;
+
+        if (message && message.trim().length > 0) {
+            return message.trim();
+        }
+    } catch {
+        // Keep the fallback message when the error body is not valid JSON.
+    }
+
+    return DEFAULT_AGENT_BOOK_DOWNLOAD_ERROR_MESSAGE;
+}
+
+/**
+ * Downloads the stored `.book` source for one agent.
+ *
+ * @param options - Agent identifier and fallback filename data.
+ * @returns Promise that resolves after the browser download is triggered.
+ */
+export async function downloadAgentBook({
+    agentIdentifier,
+    filenameAgentName,
+}: DownloadAgentBookOptions): Promise<void> {
+    const response = await fetch(createAgentBookDownloadApiPath(agentIdentifier), { method: 'GET' });
+
+    if (!response.ok) {
+        throw new PromptbookFetchError(await resolveAgentBookDownloadErrorMessage(response));
+    }
+
+    const filename =
+        parseFilenameFromContentDisposition(response.headers.get('Content-Disposition')) ||
+        createAgentBookDownloadFilename(filenameAgentName);
+
+    downloadBlob(await response.blob(), filename);
+}

package/apps/agents-server/src/utils/agentBrowserProfile/$provideAgentBrowserProfile.ts

@@ -0,0 +1,92 @@
+import { mkdir } from 'fs/promises';
+import { createUserWalletRecord } from '../userWallet/createUserWalletRecord';
+import { resolveWalletAgentPermanentId } from '../userWallet/resolveWalletAgentPermanentId';
+import {
+    AGENT_BROWSER_PROFILE_WALLET_KEY,
+    AGENT_BROWSER_PROFILE_WALLET_SERVICE,
+} from './agentBrowserProfileWalletConstants';
+import { findAgentBrowserProfileWalletRecord } from './findAgentBrowserProfileWalletRecord';
+import { resolveDefaultAgentBrowserProfileDirectory } from './resolveAgentBrowserProfileDirectory';
+
+/**
+ * Persistent browser profile of one agent.
+ */
+export type AgentBrowserProfile = {
+    /**
+     * Canonical `Agent.permanentId` owning the profile.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Filesystem directory holding the Playwright user data (cookies, sessions, local storage,...).
+     */
+    readonly directory: string;
+};
+
+/**
+ * Options for `$provideAgentBrowserProfile`.
+ */
+export type ProvideAgentBrowserProfileOptions = {
+    /**
+     * Agent identifier - either `Agent.permanentId` or agent name.
+     */
+    readonly agentIdentifier: string;
+
+    /**
+     * Optional user id used when the wallet record has to be created.
+     *
+     * The wallet table requires an owning user, so without a known user the profile directory is
+     * still provided but the wallet record creation is deferred to the next identified usage.
+     */
+    readonly userId?: number;
+};
+
+/**
+ * Provides the persistent browser profile of one agent.
+ *
+ * - Resolves the profile directory from the agent-scoped `BROWSER_PROFILE` wallet record when it exists.
+ * - Falls back to the deterministic default directory otherwise.
+ * - Ensures the directory exists on the filesystem.
+ * - Registers the wallet record linking the agent to the directory when it is missing and a user is known.
+ *
+ * @param options - Agent identifier and optional owning user.
+ * @returns Agent browser profile or `null` when the agent cannot be resolved.
+ */
+export async function $provideAgentBrowserProfile(
+    options: ProvideAgentBrowserProfileOptions,
+): Promise<AgentBrowserProfile | null> {
+    const agentPermanentId = await resolveWalletAgentPermanentId(options.agentIdentifier);
+    if (!agentPermanentId) {
+        return null;
+    }
+
+    const existingWalletRecord = await findAgentBrowserProfileWalletRecord(agentPermanentId);
+    const directoryFromWallet = existingWalletRecord?.secret?.trim() || null;
+    const directory = directoryFromWallet || resolveDefaultAgentBrowserProfileDirectory(agentPermanentId);
+
+    await mkdir(directory, { recursive: true });
+
+    if (!existingWalletRecord && typeof options.userId === 'number') {
+        try {
+            await createUserWalletRecord({
+                userId: options.userId,
+                agentPermanentId,
+                isUserScoped: false,
+                isGlobal: false,
+                recordType: 'BROWSER_PROFILE',
+                service: AGENT_BROWSER_PROFILE_WALLET_SERVICE,
+                key: AGENT_BROWSER_PROFILE_WALLET_KEY,
+                secret: directory,
+            });
+        } catch (error) {
+            // The profile keeps working from the deterministic directory even when the wallet
+            // registration fails, so browsing must not be interrupted here
+            console.warn('[agent-browser-profile] Failed to register browser profile in wallet', {
+                agentPermanentId,
+                error,
+            });
+        }
+    }
+
+    return { agentPermanentId, directory };
+}

package/apps/agents-server/src/utils/agentBrowserProfile/$provideAgentBrowserProfileForToolArgs.ts

@@ -0,0 +1,36 @@
+import { readToolRuntimeContextFromToolArgs } from '../../../../../src/commitments/_common/toolRuntimeContext';
+import type { TODO_any } from '../../../../../src/utils/organization/TODO_any';
+import type { AgentBrowserProfile } from './$provideAgentBrowserProfile';
+import { $provideAgentBrowserProfile } from './$provideAgentBrowserProfile';
+
+/**
+ * Provides the persistent browser profile of the agent executing one tool call.
+ *
+ * The agent identity is read from the hidden tool runtime context embedded in the tool arguments.
+ * The function never throws - browser tools keep working on the shared default profile when the
+ * agent identity or the profile cannot be resolved.
+ *
+ * @param args - Raw tool arguments including hidden runtime keys.
+ * @returns Agent browser profile or `null` when no agent identity is available.
+ */
+export async function $provideAgentBrowserProfileForToolArgs(
+    args: Record<string, TODO_any>,
+): Promise<AgentBrowserProfile | null> {
+    try {
+        const runtimeContext = readToolRuntimeContextFromToolArgs(args);
+        const agentIdentifier = runtimeContext?.chat?.agentId || runtimeContext?.memory?.agentId;
+        if (!agentIdentifier) {
+            return null;
+        }
+
+        const userId = runtimeContext?.chat?.userId ?? runtimeContext?.memory?.userId;
+
+        return await $provideAgentBrowserProfile({
+            agentIdentifier,
+            userId: typeof userId === 'number' ? userId : undefined,
+        });
+    } catch (error) {
+        console.warn('[agent-browser-profile] Failed to provide agent browser profile for tool call', { error });
+        return null;
+    }
+}

package/apps/agents-server/src/utils/agentBrowserProfile/agentBrowserProfileWalletConstants.ts

@@ -0,0 +1,9 @@
+/**
+ * Wallet service id used for the persistent per-agent browser profile record.
+ */
+export const AGENT_BROWSER_PROFILE_WALLET_SERVICE = 'browser';
+
+/**
+ * Wallet key used for the persistent per-agent browser profile record.
+ */
+export const AGENT_BROWSER_PROFILE_WALLET_KEY = 'agent-browser-profile';

package/apps/agents-server/src/utils/agentBrowserProfile/findAgentBrowserProfileWalletRecord.ts

@@ -0,0 +1,37 @@
+import type { UserWalletRow } from '../userWallet/UserWalletRow';
+import { provideUserWalletTable } from '../userWallet/provideUserWalletTable';
+import {
+    AGENT_BROWSER_PROFILE_WALLET_KEY,
+    AGENT_BROWSER_PROFILE_WALLET_SERVICE,
+} from './agentBrowserProfileWalletConstants';
+
+/**
+ * Finds the wallet record linking one agent to its persistent browser-profile directory.
+ *
+ * The browser profile belongs to the agent (not to one user), so the lookup intentionally ignores
+ * `userId` and `isUserScoped` and returns the newest agent-scoped `BROWSER_PROFILE` record.
+ *
+ * @param agentPermanentId - Canonical `Agent.permanentId`.
+ * @returns Wallet row or `null` when the agent has no browser-profile record yet.
+ */
+export async function findAgentBrowserProfileWalletRecord(agentPermanentId: string): Promise<UserWalletRow | null> {
+    const userWalletTable = await provideUserWalletTable();
+
+    const { data, error } = await userWalletTable
+        .select('*')
+        .eq('isGlobal', false)
+        .eq('agentPermanentId', agentPermanentId)
+        .eq('recordType', 'BROWSER_PROFILE')
+        .eq('service', AGENT_BROWSER_PROFILE_WALLET_SERVICE)
+        .eq('key', AGENT_BROWSER_PROFILE_WALLET_KEY)
+        .is('deletedAt', null)
+        .order('updatedAt', { ascending: false })
+        .limit(1)
+        .maybeSingle();
+
+    if (error) {
+        throw new Error(`Failed to resolve agent browser profile from wallet: ${error.message}`);
+    }
+
+    return (data as UserWalletRow | null) || null;
+}

package/apps/agents-server/src/utils/agentBrowserProfile/resolveAgentBrowserProfileDirectory.ts

@@ -0,0 +1,62 @@
+import { spaceTrim } from 'spacetrim';
+import { UnexpectedError } from '../../../../../src/errors/UnexpectedError';
+import { resolvePromptbookTemporaryPath } from '../../../../../src/utils/filesystem/promptbookTemporaryPath';
+
+/**
+ * Runtime environment variable that overrides the root directory for per-agent browser profiles.
+ */
+const AGENT_BROWSER_PROFILE_STORAGE_DIRECTORY_ENV = 'AGENT_BROWSER_PROFILE_STORAGE_DIRECTORY';
+
+/**
+ * Pattern of characters kept as-is inside one browser-profile directory name.
+ */
+const AGENT_BROWSER_PROFILE_DIRECTORY_NAME_UNSAFE_CHARACTER_PATTERN = /[^a-zA-Z0-9_-]/g;
+
+/**
+ * Resolves the root filesystem directory holding all per-agent browser profiles.
+ *
+ * The profiles are persistent for the whole agent life (they survive browser and server restarts),
+ * they are only co-located with other Promptbook working files by default.
+ */
+export function resolveAgentBrowserProfileStorageDirectory(): string {
+    const configuredStorageDirectory = process.env[AGENT_BROWSER_PROFILE_STORAGE_DIRECTORY_ENV];
+    if (configuredStorageDirectory && configuredStorageDirectory.trim()) {
+        return configuredStorageDirectory.trim();
+    }
+
+    return resolvePromptbookTemporaryPath(process.cwd(), 'agents-server', 'browser', 'profiles');
+}
+
+/**
+ * Resolves the default persistent browser-profile directory of one agent.
+ *
+ * The result is deterministic for one agent so the same profile is reused by every browser session
+ * of that agent, even before any wallet record exists.
+ *
+ * @param agentPermanentId - Canonical `Agent.permanentId`.
+ * @returns Absolute or project-relative directory path of the agent browser profile.
+ */
+export function resolveDefaultAgentBrowserProfileDirectory(agentPermanentId: string): string {
+    const normalizedAgentPermanentId = agentPermanentId.trim();
+    if (!normalizedAgentPermanentId) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                Cannot resolve browser profile directory.
+
+                The \`agentPermanentId\` is required but an empty value was provided.
+            `),
+        );
+    }
+
+    const directoryName = sanitizeAgentBrowserProfileDirectoryName(normalizedAgentPermanentId);
+    return `${resolveAgentBrowserProfileStorageDirectory()}/agent-${directoryName}`;
+}
+
+/**
+ * Converts one agent permanent id into a filesystem-safe directory name.
+ *
+ * @private function of `resolveDefaultAgentBrowserProfileDirectory`
+ */
+function sanitizeAgentBrowserProfileDirectoryName(agentPermanentId: string): string {
+    return agentPermanentId.replace(AGENT_BROWSER_PROFILE_DIRECTORY_NAME_UNSAFE_CHARACTER_PATTERN, '-');
+}

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

@@ -1,3 +1,5 @@
+import { buildAgentNameOrPermanentIdFilter } from '../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/buildAgentNameOrPermanentIdFilter';
+
 /**
  * Minimal agent shape needed to build canonical route identifiers.
  */
@@ -26,13 +28,34 @@ export function resolveAgentRouteIdentifier(agent: AgentRouteIdentifierSource):
 /**
  * Builds a Supabase `.or()` filter that matches an agent by name or permanent identifier.
  *
- * Supabase/PostgREST filters expect values to be URL-encoded so that characters like
- * spaces or punctuation do not break the query syntax (e.g. `agentName.eq.AI Team`).
+ * The permanent identifier is matched case-insensitively so that `/agents/:agentId` routes
+ * resolve to the same agent regardless of the letter casing used in the URL. This delegates to
+ * the shared core builder to keep a single source of truth for the filter syntax.
  *
  * @param identifier - Agent name or permanent identifier to match.
  * @returns `.or()` filter string safe to pass to Supabase.
  */
 export function buildAgentNameOrIdFilter(identifier: string): string {
-    const encodedIdentifier = encodeURIComponent(identifier);
-    return `agentName.eq.${encodedIdentifier},permanentId.eq.${encodedIdentifier}`;
+    return buildAgentNameOrPermanentIdFilter(identifier);
+}
+
+/**
+ * Compares two agent permanent identifiers case-insensitively.
+ *
+ * Permanent ids are treated as case-insensitive, so `doQMRg82izNfJa` and `DOQMRG82IZNFJA`
+ * refer to the same agent. Empty, `null` or `undefined` ids never match.
+ *
+ * @param firstPermanentId - First permanent id to compare.
+ * @param secondPermanentId - Second permanent id to compare.
+ * @returns `true` when both ids are present and equal ignoring case.
+ */
+export function isSameAgentPermanentId(
+    firstPermanentId: string | null | undefined,
+    secondPermanentId: string | null | undefined,
+): boolean {
+    if (!firstPermanentId || !secondPermanentId) {
+        return false;
+    }
+
+    return firstPermanentId.toLowerCase() === secondPermanentId.toLowerCase();
 }

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

@@ -1,7 +1,7 @@
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
 import type { AgentsServerDatabase } from '../database/schema';
-import { buildAgentNameOrIdFilter } from './agentIdentifier';
+import { buildAgentNameOrIdFilter, isSameAgentPermanentId } from './agentIdentifier';
 
 /**
  * Agent row shape used by owner-aware helpers.
@@ -116,7 +116,7 @@ const OWNED_AGENT_ROW_COLUMNS =
  * 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.
+ * 1. Case-insensitive `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.
  *
@@ -134,7 +134,7 @@ function pickAgentRowByIdentifier(
         return null;
     }
 
-    const permanentIdMatch = rows.find((row) => row.permanentId === identifier);
+    const permanentIdMatch = rows.find((row) => isSameAgentPermanentId(row.permanentId, identifier));
     if (permanentIdMatch) {
         return permanentIdMatch;
     }