@promptbook/cli 0.112.0-134 → 0.112.0-136

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/serverManagement/createManagedServer/bootstrapManagedServer.ts

@@ -5,7 +5,6 @@ import {
     acquireMigrationExecutionLock,
     releaseMigrationExecutionLock,
 } from '../../../database/acquireMigrationExecutionLock';
-import { scheduleDefaultFederatedAgentsSync } from '../../defaultFederatedAgents/scheduleDefaultFederatedAgentsSync';
 import { createServerPublicUrl, invalidateRegisteredServersCache } from '../../serverRegistry';
 import type { CreateServerResult } from '../createManagedServer';
 import { resolveManagedServerConnectionString } from '../resolveManagedServerConnectionString';
@@ -14,6 +13,7 @@ import { createFailedServerResult } from './createFailedServerResult';
 import { createSqlRecorder } from './createSqlRecorder';
 import { insertManagedServerRegistryRow } from './insertManagedServerRegistryRow';
 import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
+import { seedServerCoreAgents } from './seedServerCoreAgents';
 import { seedServerDefaultAgents } from './seedServerDefaultAgents';
 import { seedServerMetadata } from './seedServerMetadata';
 import { seedServerUsers } from './seedServerUsers';
@@ -50,15 +50,12 @@ export async function bootstrapManagedServer(input: NormalizedCreateServerInput)
         if (input.isDefaultAgentsInstalled) {
             await seedServerDefaultAgents(client, input, sqlRecorder);
         }
+        await seedServerCoreAgents(client, input, sqlRecorder);
 
         await client.query('COMMIT');
         sqlRecorder.addStatement('COMMIT');
 
         invalidateRegisteredServersCache();
-        scheduleDefaultFederatedAgentsSync({
-            tablePrefix: server.tablePrefix,
-            localServerUrl: createServerPublicUrl(server.domain).href,
-        });
 
         return {
             ok: true,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerCoreAgents.ts

@@ -0,0 +1,162 @@
+import type { Client } from 'pg';
+import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
+import { DEFAULT_AGENT_VISIBILITY } from '../../agentVisibility';
+import { CORE_AGENT_DIRECTORY_NAME, loadCoreAgentBooks } from '../../defaultAgents/loadDefaultAgentBooks';
+import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
+import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
+
+/**
+ * Loads bundled `.core` agent books from the repository and persists them into the newly created server.
+ *
+ * Each `*.book` file in `agents/default/.core` becomes one persisted agent in the `.core` folder with its initial
+ * history snapshot.
+ *
+ * @param client - Connected PostgreSQL client inside the bootstrap transaction.
+ * @param input - Normalized create-server payload.
+ * @param sqlRecorder - Mutable SQL dump recorder.
+ *
+ * @private function of createManagedServer
+ */
+export async function seedServerCoreAgents(
+    client: Client,
+    input: NormalizedCreateServerInput,
+    sqlRecorder: SqlRecorder,
+): Promise<void> {
+    const coreAgentBooks = await loadCoreAgentBooks();
+    if (coreAgentBooks.length === 0) {
+        return;
+    }
+
+    const coreFolderId = await insertCoreFolder(client, input, sqlRecorder);
+    const agentTableIdentifier = quoteIdentifier(`${input.tablePrefix}Agent`);
+    const agentHistoryTableIdentifier = quoteIdentifier(`${input.tablePrefix}AgentHistory`);
+
+    for (const [index, coreAgentBook] of coreAgentBooks.entries()) {
+        const createdAt = new Date().toISOString();
+        const { agentInsertRecord, agentHistoryInsertRecord } = createAgentPersistenceRecords(
+            coreAgentBook,
+            { folderId: coreFolderId, sortOrder: index, visibility: DEFAULT_AGENT_VISIBILITY },
+            createdAt,
+        );
+
+        await client.query(
+            `
+                INSERT INTO ${agentTableIdentifier} (
+                    "agentName",
+                    "createdAt",
+                    "updatedAt",
+                    "permanentId",
+                    "agentHash",
+                    "agentSource",
+                    "agentProfile",
+                    "promptbookEngineVersion",
+                    "usage",
+                    "folderId",
+                    "sortOrder",
+                    "visibility"
+                )
+                VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8, $9::jsonb, $10, $11, $12)
+            `,
+            [
+                agentInsertRecord.agentName,
+                agentInsertRecord.createdAt,
+                agentInsertRecord.updatedAt,
+                agentInsertRecord.permanentId,
+                agentInsertRecord.agentHash,
+                agentInsertRecord.agentSource,
+                JSON.stringify(agentInsertRecord.agentProfile),
+                agentInsertRecord.promptbookEngineVersion,
+                JSON.stringify(agentInsertRecord.usage),
+                coreFolderId,
+                agentInsertRecord.sortOrder ?? index,
+                agentInsertRecord.visibility ?? DEFAULT_AGENT_VISIBILITY,
+            ],
+        );
+        sqlRecorder.addStatement(
+            createInsertStatement(`${input.tablePrefix}Agent`, {
+                ...agentInsertRecord,
+                agentProfile: JSON.stringify(agentInsertRecord.agentProfile),
+                usage: JSON.stringify(agentInsertRecord.usage),
+                folderId: coreFolderId,
+                sortOrder: agentInsertRecord.sortOrder ?? index,
+                visibility: agentInsertRecord.visibility ?? DEFAULT_AGENT_VISIBILITY,
+            }),
+        );
+
+        await client.query(
+            `
+                INSERT INTO ${agentHistoryTableIdentifier} (
+                    "createdAt",
+                    "agentName",
+                    "permanentId",
+                    "agentHash",
+                    "previousAgentHash",
+                    "agentSource",
+                    "promptbookEngineVersion",
+                    "versionName"
+                )
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+            `,
+            [
+                agentHistoryInsertRecord.createdAt,
+                agentHistoryInsertRecord.agentName,
+                agentHistoryInsertRecord.permanentId,
+                agentHistoryInsertRecord.agentHash,
+                agentHistoryInsertRecord.previousAgentHash,
+                agentHistoryInsertRecord.agentSource,
+                agentHistoryInsertRecord.promptbookEngineVersion,
+                agentHistoryInsertRecord.versionName,
+            ],
+        );
+        sqlRecorder.addStatement(createInsertStatement(`${input.tablePrefix}AgentHistory`, agentHistoryInsertRecord));
+    }
+}
+
+/**
+ * Inserts the `.core` folder row for the newly bootstrapped server.
+ *
+ * @param client - Connected PostgreSQL client inside the bootstrap transaction.
+ * @param input - Normalized create-server payload.
+ * @param sqlRecorder - Mutable SQL dump recorder.
+ * @returns Identifier of the inserted `.core` folder.
+ *
+ * @private function of createManagedServer
+ */
+async function insertCoreFolder(
+    client: Client,
+    input: NormalizedCreateServerInput,
+    sqlRecorder: SqlRecorder,
+): Promise<number> {
+    const agentFolderTableIdentifier = quoteIdentifier(`${input.tablePrefix}AgentFolder`);
+    const createdAt = new Date().toISOString();
+    const insertResult = await client.query<{ id: number }>(
+        `
+            INSERT INTO ${agentFolderTableIdentifier} (
+                "name",
+                "parentId",
+                "sortOrder",
+                "icon",
+                "color",
+                "createdAt",
+                "updatedAt"
+            )
+            VALUES ($1, NULL, $2, NULL, NULL, $3, NULL)
+            RETURNING "id"
+        `,
+        [CORE_AGENT_DIRECTORY_NAME, 0, createdAt],
+    );
+
+    sqlRecorder.addStatement(
+        createInsertStatement(`${input.tablePrefix}AgentFolder`, {
+            name: CORE_AGENT_DIRECTORY_NAME,
+            parentId: null,
+            sortOrder: 0,
+            icon: null,
+            color: null,
+            createdAt,
+            updatedAt: null,
+        }),
+    );
+
+    return insertResult.rows[0].id;
+}

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/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;
+}