@promptbook/cli 0.112.0-133 → 0.112.0-135

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/findAgentForCallerWriteAccess.ts

@@ -0,0 +1,36 @@
+import { findAgentByIdentifier, findOwnedAgentByIdentifier, type OwnedAgentRow } from './agentOwnership';
+import { getCurrentUser } from './getCurrentUser';
+import { isUserAdmin } from './isUserAdmin';
+
+/**
+ * Loads one agent for the current caller, enforcing ownership-or-admin write access.
+ *
+ * Resolution order:
+ * 1. Anonymous callers receive `null` so routes can return `403`.
+ * 2. Owners are matched via {@link findOwnedAgentByIdentifier} using the authenticated user id.
+ * 3. Administrators (resolved via {@link isUserAdmin}) fall through to {@link findAgentByIdentifier} so they can manage any agent — including legacy `ADMIN_PASSWORD` admins that have no database user id.
+ *
+ * @param identifier - Permanent id or agent name supplied by the route.
+ * @returns Matching agent row when the caller owns it or is an administrator, otherwise `null`.
+ *
+ * @private internal helper of Agents Server route handlers
+ */
+export async function findAgentForCallerWriteAccess(identifier: string): Promise<OwnedAgentRow | null> {
+    const [currentUser, isAdmin] = await Promise.all([getCurrentUser(), isUserAdmin()]);
+    if (!currentUser) {
+        return null;
+    }
+
+    if (typeof currentUser.id === 'number') {
+        const ownedAgent = await findOwnedAgentByIdentifier(currentUser.id, identifier);
+        if (ownedAgent) {
+            return ownedAgent;
+        }
+    }
+
+    if (!isAdmin) {
+        return null;
+    }
+
+    return findAgentByIdentifier(identifier);
+}

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

@@ -0,0 +1,241 @@
+import { createHash } from 'crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
+import { getRequestIp } from '../middleware/createMiddlewareRequestContext/getRequestIp';
+import { getSession } from './session';
+import { validateApiKey } from './validateApiKey';
+
+/**
+ * Categorizes the kind of paid third-party AI call a route performs.
+ *
+ * Each tier maps to its own per-identity sliding-window budget because the
+ * marginal cost (and therefore acceptable rate) differs significantly between
+ * speech-to-text, text-to-speech, and image generation.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestTier = 'AUDIO_TRANSCRIPTION' | 'TEXT_TO_SPEECH' | 'IMAGE_GENERATION';
+
+/**
+ * Per-tier rate limit definition.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+type PaidApiRateLimitDefinition = {
+    /**
+     * Maximum number of paid calls permitted per identity in a single window.
+     */
+    readonly maxRequestsPerWindow: number;
+    /**
+     * Length of the sliding window in milliseconds.
+     */
+    readonly windowMs: number;
+};
+
+/**
+ * Per-identity, per-tier sliding-window budgets for paid third-party calls.
+ *
+ * Numbers are intentionally generous for normal interactive UI use while still
+ * blocking sustained abuse — e.g. an attacker who has obtained a valid API key
+ * or signed-in account cannot loop millions of image generations.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_RATE_LIMITS: Readonly<Record<PaidApiRequestTier, PaidApiRateLimitDefinition>> = {
+    AUDIO_TRANSCRIPTION: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    TEXT_TO_SPEECH: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    IMAGE_GENERATION: { maxRequestsPerWindow: 20, windowMs: 60_000 },
+};
+
+/**
+ * In-memory map of request timestamps keyed by `tier|identity`.
+ *
+ * In-memory state is intentional: the sliding window is a defense in depth on
+ * top of authentication, and we do not want to add a Redis dependency just for
+ * this guard. Operators who run multiple replicas should still configure a
+ * front-door rate limiter; this layer prevents single-process abuse.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_REQUEST_TIMESTAMPS: Map<string, Array<number>> = new Map();
+
+/**
+ * Successful guard outcome describing the authenticated identity.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardSuccess = {
+    readonly ok: true;
+    /**
+     * Stable identity key used for rate limiting and audit logs.
+     *
+     * Derived from (in order): the signed session username, the bearer API key
+     * hash, and finally the request IP for anonymous fallbacks (which should
+     * not happen because `authenticatedOnly` rejects them).
+     */
+    readonly identityKey: string;
+};
+
+/**
+ * Failure outcome containing the response that should be returned verbatim.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardFailure = {
+    readonly ok: false;
+    readonly response: NextResponse;
+};
+
+/**
+ * Guard outcome returned by `guardPaidApiRequest`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardResult = PaidApiRequestGuardSuccess | PaidApiRequestGuardFailure;
+
+/**
+ * Combined authentication and per-identity rate-limit check for routes that
+ * proxy directly to paid third-party AI providers (OpenAI, ElevenLabs, ...).
+ *
+ * The guard enforces two invariants in a single place so that every paid
+ * endpoint stays consistent (DRY) and no new endpoint accidentally forgets
+ * authentication or rate limiting:
+ *
+ * 1. The caller must be authenticated via a signed session cookie or a valid
+ *    `Authorization: Bearer ptbk_...` API key.
+ * 2. The caller must stay within the per-tier sliding-window budget defined
+ *    in `PAID_API_RATE_LIMITS`.
+ *
+ * @param request - Incoming HTTP request.
+ * @param tier - Paid call category determining the applicable budget.
+ * @returns Either `{ ok: true, identityKey }` or `{ ok: false, response }`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export async function guardPaidApiRequest(
+    request: NextRequest,
+    tier: PaidApiRequestTier,
+): Promise<PaidApiRequestGuardResult> {
+    const apiKeyValidation = await validateApiKey(request);
+    if (!apiKeyValidation.isValid) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: apiKeyValidation.error || 'Authentication required',
+                        type: 'authentication_error',
+                    },
+                },
+                { status: 401 },
+            ),
+        };
+    }
+
+    const identityKey = await resolvePaidApiIdentityKey(request, apiKeyValidation.token);
+
+    const rateLimitCheck = checkPaidApiRateLimit(tier, identityKey);
+    if (!rateLimitCheck.isAllowed) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Rate limit exceeded for paid AI proxy.
+
+                            **Tier:** \`${tier}\`
+                            **Limit:** ${rateLimitCheck.maxRequestsPerWindow} requests per ${Math.round(
+                            rateLimitCheck.windowMs / 1000,
+                        )} seconds.
+
+                            Try again in **${rateLimitCheck.retryAfterSeconds}** seconds.
+                        `),
+                        type: 'rate_limit_exceeded',
+                    },
+                },
+                {
+                    status: 429,
+                    headers: {
+                        'Retry-After': String(rateLimitCheck.retryAfterSeconds),
+                    },
+                },
+            ),
+        };
+    }
+
+    return { ok: true, identityKey };
+}
+
+/**
+ * Resolves a stable per-identity key used to bucket rate-limit counts.
+ *
+ * @param request - Incoming HTTP request.
+ * @param apiKeyToken - Optional bearer token recovered by `validateApiKey`.
+ * @returns Identity key prefixed with the source kind (`user:`, `apikey:`, or `ip:`).
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+async function resolvePaidApiIdentityKey(request: NextRequest, apiKeyToken: string | undefined): Promise<string> {
+    const session = await getSession();
+    if (session?.username) {
+        return `user:${session.username}`;
+    }
+
+    if (apiKeyToken) {
+        return `apikey:${createHash('sha256').update(apiKeyToken).digest('hex')}`;
+    }
+
+    return `ip:${getRequestIp(request)}`;
+}
+
+/**
+ * Sliding-window rate-limit check shared by all paid AI proxy tiers.
+ *
+ * @param tier - Paid call category determining the applicable budget.
+ * @param identityKey - Stable per-identity key from `resolvePaidApiIdentityKey`.
+ * @returns Decision describing whether the request is allowed and, if not, how long to wait.
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+function checkPaidApiRateLimit(
+    tier: PaidApiRequestTier,
+    identityKey: string,
+): {
+    readonly isAllowed: boolean;
+    readonly maxRequestsPerWindow: number;
+    readonly windowMs: number;
+    readonly retryAfterSeconds: number;
+} {
+    const { maxRequestsPerWindow, windowMs } = PAID_API_RATE_LIMITS[tier];
+    const bucketKey = `${tier}|${identityKey}`;
+    const now = Date.now();
+    const windowStart = now - windowMs;
+
+    const existingTimestamps = PAID_API_REQUEST_TIMESTAMPS.get(bucketKey) || [];
+    const recentTimestamps = existingTimestamps.filter((timestamp) => timestamp > windowStart);
+
+    if (recentTimestamps.length >= maxRequestsPerWindow) {
+        const oldestRelevantTimestamp = recentTimestamps[0]!;
+        const retryAfterMs = Math.max(1_000, oldestRelevantTimestamp + windowMs - now);
+        PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+        return {
+            isAllowed: false,
+            maxRequestsPerWindow,
+            windowMs,
+            retryAfterSeconds: Math.ceil(retryAfterMs / 1_000),
+        };
+    }
+
+    recentTimestamps.push(now);
+    PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+
+    return {
+        isAllowed: true,
+        maxRequestsPerWindow,
+        windowMs,
+        retryAfterSeconds: 0,
+    };
+}
+
+// Note: [🟢] Code for the Agents Server paid AI request guard should never be published into packages that could be imported into browser environment

package/apps/agents-server/src/utils/userChat/createRunUserChatJobExecutionContext.ts

@@ -27,7 +27,8 @@ import type { ChatMessage, ChatPrompt, LlmToolDefinition, ToolCall } from '@prom
 import { resolveTeamInternalAgentAccessToken } from '../../../../../src/commitments/_common/teamInternalAgentAccess';
 import type { ChatPromptResult } from '../../../../../src/execution/PromptResult';
 import { createUserChatMessagePrompt } from './createUserChatMessagePrompt';
-import type { UserChatProgressPhase } from './userChatProgressCard';
+import { resolveUserChatProgressToolHighlights } from './resolveUserChatProgressToolHighlights';
+import type { UserChatProgressContext, UserChatProgressPhase } from './userChatProgressCard';
 import type { UserChatJobRecord } from './UserChatJobRecord';
 
 /**
@@ -55,9 +56,13 @@ type RunUserChatJobPromptSnapshotFactory = (
 ) => NonNullable<ChatMessage['prompt']>;
 
 /**
- * Reports one user-facing durable chat progress phase.
+ * Reports one user-facing durable chat progress phase together with the real runtime
+ * details already known at that point in the worker lifecycle.
  */
-type RunUserChatJobProgressReporter = (phase: UserChatProgressPhase) => Promise<void>;
+type RunUserChatJobProgressReporter = (
+    phase: UserChatProgressPhase,
+    context?: UserChatProgressContext,
+) => Promise<void>;
 
 /**
  * Prepares the full agent/runtime context required to execute one durable user chat job.
@@ -75,7 +80,12 @@ export async function createRunUserChatJobExecutionContext(options: {
     promptContent: ChatPrompt['content'];
     reportProgress?: RunUserChatJobProgressReporter;
 }) {
-    await options.reportProgress?.('reading_context');
+    const initialProgressContext: UserChatProgressContext = {
+        agentPermanentId: options.job.agentPermanentId,
+        attachmentCount: options.userMessageAttachments?.length ?? 0,
+    };
+
+    await options.reportProgress?.('reading_context', initialProgressContext);
 
     const [localServerUrl, collection, baseAgentReferenceResolver] = await Promise.all([
         resolveCurrentOrInternalServerOrigin(),
@@ -83,7 +93,7 @@ export async function createRunUserChatJobExecutionContext(options: {
         $provideAgentReferenceResolver(),
     ]);
 
-    await options.reportProgress?.('preparing_agent');
+    await options.reportProgress?.('preparing_agent', initialProgressContext);
 
     const resolvedAgentContext = await resolveCachedServerAgentContext({
         collection,
@@ -103,8 +113,22 @@ export async function createRunUserChatJobExecutionContext(options: {
     const projectRepositories = extractProjectRepositoriesFromAgentSource(agentSource);
     const calendarConnections = extractUseCalendarConnectionsFromAgentSource(agentSource);
     const useEmailConfiguration = extractUseEmailConfigurationFromAgentSource(agentSource);
+    const agentToolDefinitions = preparedAgentModelRequirements.modelRequirements.tools ?? [];
+    const agentKnowledgeSources = preparedAgentModelRequirements.modelRequirements.knowledgeSources ?? [];
 
-    await options.reportProgress?.('checking_capabilities');
+    const checkingCapabilitiesProgressContext: UserChatProgressContext = {
+        ...initialProgressContext,
+        agentName: resolvedAgentName,
+        agentPermanentId,
+        knowledgeSourceCount: agentKnowledgeSources.length,
+        toolCount: agentToolDefinitions.length,
+        toolHighlights: resolveUserChatProgressToolHighlights(agentToolDefinitions),
+        hasCalendarAccess: calendarConnections.length > 0,
+        hasEmailAccess: useEmailConfiguration.isEnabled,
+        hasProjectAccess: projectRepositories.length > 0,
+    };
+
+    await options.reportProgress?.('checking_capabilities', checkingCapabilitiesProgressContext);
 
     const { projectGithubToken, calendarGoogleAccessToken, emailSmtpCredential } =
         await resolveRunUserChatJobCredentials({
@@ -179,8 +203,6 @@ export async function createRunUserChatJobExecutionContext(options: {
         });
     }
 
-    await options.reportProgress?.('starting_response');
-
     const agentKitResult = await agentKitCacheManager.getOrCreateAgentKitAgent(
         agentSource,
         resolvedAgentName,
@@ -203,6 +225,12 @@ export async function createRunUserChatJobExecutionContext(options: {
         teacherAgent: await getTeacherRemoteAgent(),
     });
 
+    await options.reportProgress?.('starting_response', {
+        ...checkingCapabilitiesProgressContext,
+        provider: provider ?? undefined,
+        isAgentKitCached: agentKitResult.fromCache,
+    });
+
     return {
         collection,
         agent,

package/apps/agents-server/src/utils/userChat/listUserChats.ts

@@ -2,6 +2,7 @@ import { $getTableName } from '@/src/database/$getTableName';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
 import { $provideAgentsServerSqliteDatabase } from '@/src/database/sqlite/$provideAgentsServerSqliteDatabase';
+import { ensureLocalSqliteTableReadIndexes } from '@/src/database/sqlite/$provideLocalSqliteSupabase';
 import type { ListUserChatsOptions, UserChatRecord } from './UserChatRecord';
 import type { UserChatSource } from './UserChatSource';
 import type { UserChatRow } from './UserChatRow';
@@ -168,7 +169,10 @@ export async function listUserChatSummarySeeds(options: ListUserChatsOptions): P
  * @private function of `userChat`
  */
 async function listUserChatSummarySeedsViaSqlite(options: ListUserChatsOptions): Promise<Array<UserChatSummarySeed>> {
-    const userChatTableName = quoteIdentifier(await $getTableName('UserChat'));
+    const rawUserChatTableName = await $getTableName('UserChat');
+    ensureLocalSqliteTableReadIndexes(rawUserChatTableName);
+
+    const userChatTableName = quoteIdentifier(rawUserChatTableName);
     const shouldLoadExternalChats = options.viewerIsAdmin && options.includeExternalChats;
     const whereClause = shouldLoadExternalChats
         ? `

package/apps/agents-server/src/utils/userChat/persistUserChatJobProgressCard.ts

@@ -1,8 +1,16 @@
-import { createUserChatProgressCard, type UserChatProgressPhase } from './userChatProgressCard';
+import {
+    createUserChatProgressCard,
+    type UserChatProgressContext,
+    type UserChatProgressPhase,
+} from './userChatProgressCard';
 import { updateUserChatAssistantMessage } from './updateUserChatAssistantMessage';
 
 /**
  * Persists one durable chat progress phase onto the active assistant placeholder.
+ *
+ * The optional `context` carries real runtime details (agent name, provider, tool count,
+ * attachments, integrations) so the persisted progress card reflects what the worker is
+ * actually doing on this turn instead of a fixed scripted summary.
  */
 export async function persistUserChatJobProgressCard(options: {
     readonly userId: number;
@@ -10,6 +18,7 @@ export async function persistUserChatJobProgressCard(options: {
     readonly chatId: string;
     readonly assistantMessageId: string;
     readonly phase: UserChatProgressPhase;
+    readonly context?: UserChatProgressContext;
 }): Promise<void> {
     await updateUserChatAssistantMessage({
         userId: options.userId,
@@ -24,7 +33,7 @@ export async function persistUserChatJobProgressCard(options: {
                 lifecycleState,
                 lifecycleError: undefined,
                 isComplete: false,
-                progressCard: createUserChatProgressCard(options.phase),
+                progressCard: createUserChatProgressCard(options.phase, options.context),
             };
         },
     });

package/apps/agents-server/src/utils/userChat/resolveUserChatProgressToolHighlights.ts

@@ -0,0 +1,100 @@
+import type { LlmToolDefinition } from '@promptbook-local/types';
+
+/**
+ * Maximum number of tool highlight labels surfaced in the progress card text.
+ *
+ * Keeps the rendered sentence readable when an agent exposes many tools.
+ */
+const MAX_TOOL_HIGHLIGHTS = 4;
+
+/**
+ * Maps technical tool identifiers to short user-facing labels shown in the
+ * durable chat progress card while capabilities are being checked.
+ */
+const USER_CHAT_PROGRESS_TOOL_LABEL_BY_NAME: Record<string, string> = {
+    web_search: 'web search',
+    deep_search: 'deep research',
+    useSearchEngine: 'web search',
+    search: 'web search',
+    useBrowser: 'web browser',
+    browse: 'web browser',
+    fetch_url_content: 'web browser',
+    run_browser: 'web browser',
+    get_current_time: 'time awareness',
+    useTime: 'time awareness',
+    set_timeout: 'timers',
+    cancel_timeout: 'timers',
+    list_timeouts: 'timers',
+    update_timeout: 'timers',
+    get_user_location: 'user location',
+    send_email: 'email sending',
+    useEmail: 'email sending',
+    spawn_agent: 'teammate agents',
+    retrieve_user_memory: 'long-term memory',
+    store_user_memory: 'long-term memory',
+    project_list_files: 'project files',
+    project_read_file: 'project files',
+    project_upsert_file: 'project files',
+    project_delete_file: 'project files',
+    project_create_branch: 'project repository',
+    project_create_pull_request: 'project repository',
+};
+
+/**
+ * Tool identifiers that should never appear as user-facing capability highlights.
+ *
+ * `agent_progress` is an internal runtime tool used by the worker to update this
+ * very progress card, and `assistant_preparation` is the engine-level chip shown
+ * while the model is being prepared. Neither describes a user-relevant capability.
+ */
+const HIDDEN_PROGRESS_TOOL_NAMES: ReadonlySet<string> = new Set(['agent_progress', 'assistant_preparation']);
+
+/**
+ * Derives a short, deduplicated list of user-facing tool labels for one durable chat turn.
+ *
+ * @public exported for `createRunUserChatJobExecutionContext`
+ */
+export function resolveUserChatProgressToolHighlights(
+    tools: ReadonlyArray<LlmToolDefinition>,
+): ReadonlyArray<string> {
+    const highlights: Array<string> = [];
+    const seenLabels = new Set<string>();
+
+    for (const tool of tools) {
+        if (!tool || typeof tool.name !== 'string') {
+            continue;
+        }
+
+        if (HIDDEN_PROGRESS_TOOL_NAMES.has(tool.name)) {
+            continue;
+        }
+
+        const label = USER_CHAT_PROGRESS_TOOL_LABEL_BY_NAME[tool.name] ?? humanizeToolName(tool.name);
+        if (!label || seenLabels.has(label)) {
+            continue;
+        }
+
+        seenLabels.add(label);
+        highlights.push(label);
+
+        if (highlights.length >= MAX_TOOL_HIGHLIGHTS) {
+            break;
+        }
+    }
+
+    return highlights;
+}
+
+/**
+ * Converts a technical tool identifier into a short readable label as a fallback.
+ *
+ * @private internal helper of `resolveUserChatProgressToolHighlights`
+ */
+function humanizeToolName(name: string): string {
+    const normalized = name.replace(/[_-]+/g, ' ').trim().toLowerCase();
+    if (!normalized) {
+        return '';
+    }
+
+    return normalized;
+}

package/apps/agents-server/src/utils/userChat/runUserChatJob.ts

@@ -22,7 +22,7 @@ import { heartbeatUserChatJob } from './heartbeatUserChatJob';
 import { persistUserChatJobTerminalState } from './persistUserChatJobTerminalState';
 import { persistUserChatJobProgressCard } from './persistUserChatJobProgressCard';
 import type { UserChatJobRecord } from './UserChatJobRecord';
-import type { UserChatProgressPhase } from './userChatProgressCard';
+import type { UserChatProgressContext, UserChatProgressPhase } from './userChatProgressCard';
 import { createReplyAwareUserChatPromptContent, createReplyAwareUserChatPromptMessage } from './userChatReplies';
 import { resolvePromptThreadBeforeUserMessage } from './userChatMessageLifecycle';
 import { isUserChatNotFoundScopeError } from './UserChatScopeError';
@@ -132,14 +132,15 @@ export async function runUserChatJob(job: UserChatJobRecord): Promise<RunUserCha
  */
 function createRunUserChatJobProgressReporter(
     job: Pick<UserChatJobRecord, 'userId' | 'agentPermanentId' | 'chatId' | 'assistantMessageId' | 'id'>,
-): (phase: UserChatProgressPhase) => Promise<void> {
-    return async (phase) => {
+): (phase: UserChatProgressPhase, context?: UserChatProgressContext) => Promise<void> {
+    return async (phase, context) => {
         await persistUserChatJobProgressCard({
             userId: job.userId,
             agentPermanentId: job.agentPermanentId,
             chatId: job.chatId,
             assistantMessageId: job.assistantMessageId,
             phase,
+            context,
         }).catch((error) => {
             console.warn('[user-chat-job] progress_update_failed', {
                 chatId: job.chatId,