@promptbook/cli 0.112.0-133 → 0.112.0-135

package/apps/agents-server/src/app/api/openai/v1/audio/transcriptions/route.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import OpenAI from 'openai';
+import { spaceTrim } from 'spacetrim';
 import { getMetadata } from '@/src/database/getMetadata';
+import { guardPaidApiRequest } from '@/src/utils/paidApiRequestGuard';
 
 /**
  * Fallback file name used when the uploaded blob does not carry one.
@@ -12,6 +14,38 @@ const DEFAULT_AUDIO_TRANSCRIPTION_FILE_NAME = 'speech-recording.webm';
  */
 const DEFAULT_AUDIO_TRANSCRIPTION_MODEL_PRIORITY = ['gpt-4o-transcribe', 'gpt-4o-mini-transcribe', 'whisper-1'] as const;
 
+/**
+ * Allowlist of model identifiers accepted from the caller.
+ *
+ * Caller-supplied model names are forwarded to the paid OpenAI API, so we
+ * validate them against a fixed allowlist to prevent attackers from forcing
+ * the server to call expensive or experimental models that are not part of
+ * the supported transcription stack.
+ */
+const ALLOWED_AUDIO_TRANSCRIPTION_MODELS = new Set<string>(DEFAULT_AUDIO_TRANSCRIPTION_MODEL_PRIORITY);
+
+/**
+ * Maximum upload size that will be forwarded to OpenAI transcription.
+ *
+ * OpenAI's own limit is 25 MB; mirroring it here ensures we fail fast with a
+ * clear error before paying for an upload that the provider would reject.
+ */
+const MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Pattern matching ISO-639-1 language codes that OpenAI transcription accepts.
+ */
+const ISO_639_1_LANGUAGE_CODE_PATTERN = /^[a-z]{2}$/u;
+
+/**
+ * Maximum prompt length forwarded as transcription context.
+ *
+ * OpenAI rejects prompts longer than 224 tokens; we keep a conservative
+ * character cap that comfortably stays under that limit while preventing
+ * attackers from inflating request size.
+ */
+const MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH = 800;
+
 /**
  * Proxy endpoint for OpenAI audio transcription
  *
@@ -33,17 +67,55 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
             );
         }
 
+        const guard = await guardPaidApiRequest(request, 'AUDIO_TRANSCRIPTION');
+        if (!guard.ok) {
+            return guard.response;
+        }
+
         const formData = await request.formData();
         const file = formData.get('file') as File;
         const requestedModel = normalizeFormDataStringValue(formData.get('model'));
-        const language = normalizeFormDataStringValue(formData.get('language'));
-        const prompt = normalizeFormDataStringValue(formData.get('prompt'));
+        const language = resolveAudioTranscriptionLanguage(formData.get('language'));
+        const prompt = resolveAudioTranscriptionPrompt(formData.get('prompt'));
         const temperature = resolveAudioTranscriptionTemperature(formData.get('temperature'));
 
         if (!file) {
             return NextResponse.json({ error: { message: 'No file provided' } }, { status: 400 });
         }
 
+        if (file.size > MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Uploaded audio file is too large.
+
+                            **Maximum allowed size:** ${Math.round(
+                                MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES / (1024 * 1024),
+                            )} MB
+                            **Received:** ${(file.size / (1024 * 1024)).toFixed(2)} MB
+                        `),
+                    },
+                },
+                { status: 413 },
+            );
+        }
+
+        if (requestedModel !== undefined && !ALLOWED_AUDIO_TRANSCRIPTION_MODELS.has(requestedModel)) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Requested transcription model is not allowed.
+
+                            **Allowed models:** ${Array.from(ALLOWED_AUDIO_TRANSCRIPTION_MODELS).join(', ')}
+                        `),
+                    },
+                },
+                { status: 400 },
+            );
+        }
+
         const openai = new OpenAI({
             apiKey: openAiApiKey,
         });
@@ -108,6 +180,43 @@ function normalizeFormDataStringValue(value: FormDataEntryValue | null): string
     return normalizedValue;
 }
 
+/**
+ * Validates the caller-supplied language hint against ISO-639-1.
+ *
+ * Forwarding arbitrary `language` strings to OpenAI is harmless cost-wise but
+ * widens the attack surface — invalid values can trigger model retries that
+ * silently inflate the bill. We mirror the documented constraint and drop
+ * anything that does not match.
+ */
+function resolveAudioTranscriptionLanguage(value: FormDataEntryValue | null): string | undefined {
+    const normalizedValue = normalizeFormDataStringValue(value);
+    if (!normalizedValue) {
+        return undefined;
+    }
+
+    if (!ISO_639_1_LANGUAGE_CODE_PATTERN.test(normalizedValue)) {
+        return undefined;
+    }
+
+    return normalizedValue.toLowerCase();
+}
+
+/**
+ * Validates and truncates the optional transcription prompt before sending it to OpenAI.
+ */
+function resolveAudioTranscriptionPrompt(value: FormDataEntryValue | null): string | undefined {
+    const normalizedValue = normalizeFormDataStringValue(value);
+    if (!normalizedValue) {
+        return undefined;
+    }
+
+    if (normalizedValue.length <= MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH) {
+        return normalizedValue;
+    }
+
+    return normalizedValue.slice(0, MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH);
+}
+
 /**
  * Parses optional transcription temperature from multipart form data.
  */

package/apps/agents-server/src/app/api/page-preview/check/route.ts

@@ -1,6 +1,8 @@
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
 import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
 
 /**
@@ -11,14 +13,30 @@ import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanB
  * - `url` — the fully-qualified HTTP(S) URL to check
  *
  * Returns `{ canEmbed: boolean }`.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse.
+ * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
     const url = request.nextUrl.searchParams.get('url');
 
     if (!url) {
         return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
     }
 
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
     try {
         const canEmbed = await checkIfUrlCanBeEmbedded(url);
         return NextResponse.json({ canEmbed });

package/apps/agents-server/src/app/api/page-preview/screenshot/route.ts

@@ -3,6 +3,8 @@ import { serializeError } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
 
 /**
  * Takes a screenshot of the given URL using a headless browser.
@@ -11,23 +13,28 @@ import { assertsError } from '../../../../../../../src/errors/assertsError';
  * - `url` — the fully-qualified HTTP(S) URL to screenshot
  *
  * Returns a PNG image.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse.
+ * The destination URL is validated against private/internal IP ranges before fetching.
  */
 export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
     const url = request.nextUrl.searchParams.get('url');
 
     if (!url) {
         return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
     }
 
-    let parsedUrl: URL;
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
     try {
-        parsedUrl = new URL(url);
-    } catch {
-        return NextResponse.json({ error: 'Invalid URL' }, { status: 400 });
-    }
-
-    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
-        return NextResponse.json({ error: 'Only http and https URLs are supported' }, { status: 400 });
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
     }
 
     try {

package/apps/agents-server/src/app/api/team-agent-profile/route.ts

@@ -8,7 +8,10 @@ import {
     resolvePlaceholderImageUrl,
     resolveProfileImageUrl,
 } from '../../../../../../src/book-components/Chat/utils/loadAgentProfile';
+import { assertsError } from '../../../../../../src/errors/assertsError';
 import { isValidAgentUrl } from '../../../../../../src/utils/validators/url/isValidAgentUrl';
+import { assertSafeUrl } from '../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../utils/getCurrentUser';
 
 /**
  * Response for team agent profile.
@@ -88,8 +91,17 @@ async function fetchAgentProfile(agentUrl: string, localServerUrl: string): Prom
  *
  * The client uses this to render tool call chips without relying on direct cross-origin requests
  * to the teammate agent.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse and exfiltration of the
+ * internal team access token. The destination URL is validated against private/internal
+ * IP ranges before any outbound request is made.
  */
 export async function GET(request: Request) {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
     const requestUrl = new URL(request.url);
     const agentUrl = requestUrl.searchParams.get('url');
 
@@ -97,6 +109,14 @@ export async function GET(request: Request) {
         return NextResponse.json({ error: 'Invalid agent URL' }, { status: 400 });
     }
 
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(agentUrl);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
     const normalizedUrl = agentUrl.replace(/\/$/, '');
     const profile = await fetchAgentProfile(normalizedUrl, requestUrl.origin);
 

package/apps/agents-server/src/app/api/v1/agents/[agentId]/route.ts

@@ -6,6 +6,7 @@ import { $getTableName } from '@/src/database/$getTableName';
 import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
 import { $provideServer } from '@/src/tools/$provideServer';
+import { invalidateCachedActiveOrganizationSnapshots } from '@/src/utils/agentOrganization/loadAgentOrganizationState';
 import { findOwnedAgentByIdentifier, findOwnedFolderById, type OwnedAgentRow } from '@/src/utils/agentOwnership';
 import {
     getNextOwnedAgentSortOrder,
@@ -155,6 +156,8 @@ export async function PATCH(request: NextRequest, { params }: { params: Promise<
             return metadataUpdateResponse;
         }
 
+        invalidateCachedActiveOrganizationSnapshots();
+
         return createUpdatedOwnedAgentResponse(request, identityResult.identity.userId, existingAgent);
     } catch (error) {
         return mapOwnedAgentLookupErrorToResponse(request, error);
@@ -192,6 +195,7 @@ export async function DELETE(request: NextRequest, { params }: { params: Promise
 
         const collection = await $provideAgentCollectionForServer();
         await collection.deleteAgent(existingAgent.permanentId || existingAgent.agentName);
+        invalidateCachedActiveOrganizationSnapshots();
 
         return createManagementApiJsonResponse(request, { success: true });
     } catch (error) {

package/apps/agents-server/src/app/api/v1/agents/route.ts

@@ -4,6 +4,7 @@ import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentColle
 import { $provideServer } from '@/src/tools/$provideServer';
 import { findOwnedFolderById, findOwnedAgentByIdentifier } from '@/src/utils/agentOwnership';
 import { createAgentWithDefaultVisibility } from '@/src/utils/createAgentWithDefaultVisibility';
+import { invalidateCachedActiveOrganizationSnapshots } from '@/src/utils/agentOrganization/loadAgentOrganizationState';
 import {
     searchOwnedAgents,
     getNextOwnedAgentSortOrder,
@@ -141,6 +142,7 @@ export async function POST(request: NextRequest) {
             sortOrder,
             userId: identityResult.identity.userId,
         });
+        invalidateCachedActiveOrganizationSnapshots();
         const persistedRow = await findOwnedAgentByIdentifier(identityResult.identity.userId, createdAgent.permanentId);
 
         if (!persistedRow) {

package/apps/agents-server/src/app/recycle-bin/actions.ts

@@ -4,6 +4,7 @@ import { restoreAgentAndFolders } from '@/src/utils/agentOrganization/restoreAge
 import { revalidatePath } from 'next/cache';
 import { isUserAdmin } from '../../utils/isUserAdmin';
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
+import { invalidateCachedActiveOrganizationSnapshots } from '@/src/utils/agentOrganization/loadAgentOrganizationState';
 
 /**
  * Restores a deleted agent from the recycle bin.
@@ -16,6 +17,7 @@ export async function restoreDeletedAgent(agentName: string) {
     }
 
     await restoreAgentAndFolders(agentName);
+    invalidateCachedActiveOrganizationSnapshots();
 
     revalidatePath('/recycle-bin');
     revalidatePath(`/agents/${agentName}`);
@@ -35,6 +37,7 @@ export async function deleteAgent(agentName: string) {
     const collection = await $provideAgentCollectionForServer();
 
     await collection.deleteAgent(agentName);
+    invalidateCachedActiveOrganizationSnapshots();
 
     revalidatePath('/recycle-bin');
     revalidatePath(`/agents/${agentName}`);

package/apps/agents-server/src/components/AgentContextMenu/useAgentContextMenuItems.ts

@@ -300,6 +300,7 @@ function createManagementMenuItems(
  * @param formatText - Agent-aware text formatter.
  * @param handleRequestVisibilityUpdate - Visibility dialog action.
  * @param integrationLink - Generated integration link metadata.
+ * @param isAdmin - Whether the current user is an administrator (gates admin-only links).
  * @param isAuthenticated - Whether the current user is logged in.
  * @param shouldShowVisibilityAction - Whether visibility editing is available.
  * @param usageAnalyticsHref - Usage analytics URL for the current agent.
@@ -311,6 +312,7 @@ function createAdminMenuItems(
     formatText: FormatAgentContextMenuText,
     handleRequestVisibilityUpdate: () => Promise<void>,
     integrationLink: AgentContextMenuNavigationLink,
+    isAdmin: boolean,
     isAuthenticated: boolean,
     shouldShowVisibilityAction: boolean,
     usageAnalyticsHref: string,
@@ -333,26 +335,31 @@ function createAdminMenuItems(
         );
     }
 
+    if (isAdmin) {
+        menuItems.push(
+            {
+                type: 'link',
+                href: `/admin/chat-history?agentName=${encodeURIComponent(agentName)}`,
+                icon: MessageSquareIcon,
+                label: formatText('Chat History'),
+            },
+            {
+                type: 'link',
+                href: usageAnalyticsHref,
+                icon: BarChart3Icon,
+                label: formatText('Usage Analytics'),
+            },
+            {
+                type: 'link',
+                href: `/admin/chat-feedback?agentName=${encodeURIComponent(agentName)}`,
+                icon: MessageCircleQuestionIcon,
+                label: formatText('Chat Feedback'),
+            },
+            createDividerItem(),
+        );
+    }
+
     menuItems.push(
-        {
-            type: 'link',
-            href: `/admin/chat-history?agentName=${encodeURIComponent(agentName)}`,
-            icon: MessageSquareIcon,
-            label: formatText('Chat History'),
-        },
-        {
-            type: 'link',
-            href: usageAnalyticsHref,
-            icon: BarChart3Icon,
-            label: formatText('Usage Analytics'),
-        },
-        {
-            type: 'link',
-            href: `/admin/chat-feedback?agentName=${encodeURIComponent(agentName)}`,
-            icon: MessageCircleQuestionIcon,
-            label: formatText('Chat Feedback'),
-        },
-        createDividerItem(),
         {
             type: 'link',
             href: integrationLink.href,
@@ -437,6 +444,7 @@ export function useAgentContextMenuItems(props: AgentContextMenuBaseProps): Cont
         formatText,
         handleRequestVisibilityUpdate,
         integrationLink,
+        isAdmin,
         isAuthenticated,
         shouldShowVisibilityAction,
         usageAnalyticsHref,

package/apps/agents-server/src/constants/defaultAgentAvatarVisual.ts

@@ -53,7 +53,7 @@ export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUES = DEFAULT_AGENT_AVATAR_
 export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUE =
     DEFAULT_AGENT_AVATAR_VISUAL_METADATA_OPTIONS.find(
         ({ visualId }) => visualId === SHARED_DEFAULT_AGENT_AVATAR_VISUAL_ID,
-    )?.metadataValue || 'OCTOPUS3D3';
+    )?.metadataValue || 'OCTOPUS3D4';
 
 /**
  * Resolves one raw metadata value to a supported built-in avatar visual id.

package/apps/agents-server/src/database/migrations/2026-06-2600-agent-directory-performance-indexes.sql

@@ -0,0 +1,14 @@
+CREATE INDEX IF NOT EXISTS "prefix_Agent_deletedAt_sortOrder_agentName_idx"
+    ON "prefix_Agent" ("deletedAt", "sortOrder", "agentName");
+
+CREATE INDEX IF NOT EXISTS "prefix_Agent_visibility_deletedAt_sortOrder_agentName_idx"
+    ON "prefix_Agent" ("visibility", "deletedAt", "sortOrder", "agentName");
+
+CREATE INDEX IF NOT EXISTS "prefix_AgentFolder_deletedAt_parentId_sortOrder_name_idx"
+    ON "prefix_AgentFolder" ("deletedAt", "parentId", "sortOrder", "name");
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChat_userId_agentPermanentId_source_createdAt_idx"
+    ON "prefix_UserChat" ("userId", "agentPermanentId", "source", "createdAt" DESC);
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChat_agentPermanentId_source_userId_createdAt_idx"
+    ON "prefix_UserChat" ("agentPermanentId", "source", "userId", "createdAt" DESC);

package/apps/agents-server/src/database/migrations/2026-06-2700-default-agent-avatar-visual-octopus3d4.sql

@@ -0,0 +1,16 @@
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'DEFAULT_AGENT_AVATAR_VISUAL',
+       'OCTOPUS3D4',
+       'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN UPPER(COALESCE("value", '')) = 'OCTOPUS3D3' THEN 'OCTOPUS3D4'
+                  ELSE "value"
+              END,
+    "note" = 'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+    "updatedAt" = NOW()
+WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL';

package/apps/agents-server/src/database/sqlite/$provideLocalSqliteSupabase.ts

@@ -65,6 +65,14 @@ type LocalSqliteUpsertOptions = {
     readonly onConflict?: string;
 };
 
+/**
+ * Read index definition for hot SQLite queries.
+ */
+type LocalSqliteReadIndex = {
+    readonly name: string;
+    readonly columns: ReadonlyArray<string>;
+};
+
 /**
  * Columns whose values are persisted as JSON text in local SQLite.
  */
@@ -141,6 +149,51 @@ const UNIQUE_INDEX_COLUMNS_BY_TABLE = new Map<string, ReadonlyArray<ReadonlyArra
     ['UserPushSubscription', [['endpoint']]],
 ]);
 
+/**
+ * Non-unique indexes for frequent standalone VPS reads.
+ */
+const READ_INDEXES_BY_TABLE = new Map<string, ReadonlyArray<LocalSqliteReadIndex>>([
+    [
+        'Agent',
+        [
+            { name: 'agentName_lookup', columns: ['agentName'] },
+            { name: 'active_directory', columns: ['deletedAt', 'sortOrder', 'agentName'] },
+            { name: 'public_active_directory', columns: ['visibility', 'deletedAt', 'sortOrder', 'agentName'] },
+        ],
+    ],
+    [
+        'AgentFolder',
+        [{ name: 'active_directory', columns: ['deletedAt', 'parentId', 'sortOrder', 'name'] }],
+    ],
+    [
+        'UserChat',
+        [
+            { name: 'user_agent_source_createdAt', columns: ['userId', 'agentPermanentId', 'source', 'createdAt'] },
+            { name: 'agent_source_user_createdAt', columns: ['agentPermanentId', 'source', 'userId', 'createdAt'] },
+        ],
+    ],
+    [
+        'UserChatJob',
+        [
+            { name: 'ready_queue', columns: ['status', 'cancelRequestedAt', 'queuedAt', 'createdAt'] },
+            { name: 'active_chat_scope', columns: ['chatId', 'userId', 'agentPermanentId', 'status', 'createdAt'] },
+            { name: 'agent_chat_status', columns: ['agentPermanentId', 'chatId', 'status'] },
+            { name: 'running_lease', columns: ['status', 'leaseExpiresAt'] },
+        ],
+    ],
+    [
+        'UserChatTimeout',
+        [
+            { name: 'ready_due', columns: ['status', 'cancelRequestedAt', 'pausedAt', 'dueAt', 'createdAt'] },
+            {
+                name: 'active_chat_scope',
+                columns: ['chatId', 'userId', 'agentPermanentId', 'status', 'pausedAt', 'dueAt', 'createdAt'],
+            },
+            { name: 'running_lease', columns: ['status', 'leaseExpiresAt'] },
+        ],
+    ],
+]);
+
 /**
  * Known unique conflict columns used when `.upsert` omits `onConflict`.
  */
@@ -179,6 +232,20 @@ export function $resetLocalSqliteSupabaseForTests(): void {
     localSqliteSupabase = null;
 }
 
+/**
+ * Ensures read indexes for a table that is queried through direct SQLite SQL.
+ *
+ * @param tableName - Actual table name, including any server prefix.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export function ensureLocalSqliteTableReadIndexes(tableName: string): void {
+    const database = $provideAgentsServerSqliteDatabase();
+    const tableBaseName = resolveTableBaseName(tableName);
+
+    ensureTable(database, tableName, resolveReadIndexColumns(tableBaseName));
+}
+
 /**
  * Supabase-shaped client with only the table query surface used by Agents Server.
  */
@@ -836,8 +903,9 @@ function ensureTable(
     const columnsToEnsure = uniqueStrings([...requiredColumns, ...resolveUniqueIndexColumns(tableBaseName)]).filter(
         (column) => column !== '*' && column !== 'id',
     );
+    const columnsToEnsureWithIndexes = uniqueStrings([...columnsToEnsure, ...resolveReadIndexColumns(tableBaseName)]);
 
-    for (const column of columnsToEnsure) {
+    for (const column of columnsToEnsureWithIndexes) {
         if (existingColumns.has(column)) {
             continue;
         }
@@ -852,6 +920,7 @@ function ensureTable(
     }
 
     ensureUniqueIndexes(database, tableName, tableBaseName);
+    ensureReadIndexes(database, tableName, tableBaseName);
 }
 
 /**
@@ -871,6 +940,21 @@ function ensureUniqueIndexes(database: AgentsServerSqliteDatabase, tableName: st
     }
 }
 
+/**
+ * Creates known read indexes after required columns exist.
+ */
+function ensureReadIndexes(database: AgentsServerSqliteDatabase, tableName: string, tableBaseName: string): void {
+    const readIndexes = READ_INDEXES_BY_TABLE.get(tableBaseName) || [];
+
+    for (const readIndex of readIndexes) {
+        const indexName = `index_${sanitizeSqlIdentifier(tableName)}_${sanitizeSqlIdentifier(readIndex.name)}`;
+        const columnSql = readIndex.columns.map(quoteIdentifier).join(', ');
+        database.exec(
+            `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(indexName)} ON ${quoteIdentifier(tableName)} (${columnSql})`,
+        );
+    }
+}
+
 /**
  * Inserts one row into the table.
  */
@@ -1441,6 +1525,13 @@ function resolveUniqueIndexColumns(tableBaseName: string): Array<string> {
     return (UNIQUE_INDEX_COLUMNS_BY_TABLE.get(tableBaseName) || []).flatMap((columns) => [...columns]);
 }
 
+/**
+ * Resolves columns participating in known read indexes.
+ */
+function resolveReadIndexColumns(tableBaseName: string): Array<string> {
+    return (READ_INDEXES_BY_TABLE.get(tableBaseName) || []).flatMap((readIndex) => [...readIndex.columns]);
+}
+
 /**
  * Resolves upsert conflict columns.
  */