@promptbook/cli 0.112.0-99 → 0.113.0-0

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

@@ -1,28 +1,63 @@
 import { resolveUserChatWorkerInternalToken } from './resolveUserChatWorkerInternalToken';
+import { retryWithBackoff } from '../retryWithBackoff';
+
+/**
+ * Number of retries for transient transport failures while waking the durable chat worker.
+ */
+const USER_CHAT_WORKER_TRIGGER_FETCH_RETRIES = 2;
+
+/**
+ * Initial wait before retrying a failed worker wake-up request.
+ */
+const USER_CHAT_WORKER_TRIGGER_FETCH_INITIAL_DELAY_MS = 250;
+
+/**
+ * Maximum wait before retrying a failed worker wake-up request.
+ */
+const USER_CHAT_WORKER_TRIGGER_FETCH_MAX_DELAY_MS = 1_000;
+
+/**
+ * Multiplier used between worker wake-up retry waits.
+ */
+const USER_CHAT_WORKER_TRIGGER_FETCH_BACKOFF_FACTOR = 2;
+
+/**
+ * Randomized extra delay ratio for worker wake-up retry waits.
+ */
+const USER_CHAT_WORKER_TRIGGER_FETCH_JITTER_RATIO = 0.2;
 
 /**
  * Schedules one best-effort internal worker invocation for durable chat jobs.
  */
-export async function triggerUserChatJobWorker(options: {
-    origin: string;
-    preferredJobId?: string;
-}): Promise<void> {
+export async function triggerUserChatJobWorker(options: { origin: string; preferredJobId?: string }): Promise<void> {
     const workerUrl = new URL('/api/internal/user-chat-jobs/run', ensureTrailingSlashlessOrigin(options.origin));
-    const response = await fetch(workerUrl, {
-        method: 'POST',
-        cache: 'no-store',
-        headers: {
-            'Content-Type': 'application/json',
-            'x-user-chat-worker-token': resolveUserChatWorkerInternalToken(),
-        },
-        body: JSON.stringify(
-            options.preferredJobId
-                ? {
-                      preferredJobId: options.preferredJobId,
-                  }
-                : {},
-        ),
-    });
+    const response = (
+        await retryWithBackoff(
+            async () =>
+                await fetch(workerUrl, {
+                    method: 'POST',
+                    cache: 'no-store',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-user-chat-worker-token': resolveUserChatWorkerInternalToken(),
+                    },
+                    body: JSON.stringify(
+                        options.preferredJobId
+                            ? {
+                                  preferredJobId: options.preferredJobId,
+                              }
+                            : {},
+                    ),
+                }),
+            {
+                retries: USER_CHAT_WORKER_TRIGGER_FETCH_RETRIES,
+                initialDelayMs: USER_CHAT_WORKER_TRIGGER_FETCH_INITIAL_DELAY_MS,
+                maxDelayMs: USER_CHAT_WORKER_TRIGGER_FETCH_MAX_DELAY_MS,
+                backoffFactor: USER_CHAT_WORKER_TRIGGER_FETCH_BACKOFF_FACTOR,
+                jitterRatio: USER_CHAT_WORKER_TRIGGER_FETCH_JITTER_RATIO,
+            },
+        )
+    ).value;
 
     if (!response.ok && response.status !== 204) {
         throw new Error(`Failed to trigger user chat worker: ${response.status} ${response.statusText}`);

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

@@ -1,10 +1,16 @@
 import type { ChatMessage } from '../../../../../src/_packages/types.index';
-
 /**
  * Lifecycle states rendered on canonical server-owned chat messages.
  */
 export type UserChatMessageLifecycleState = NonNullable<ChatMessage['lifecycleState']>;
 
+/**
+ * Message shape written into local/external chat-runner `.book` files.
+ */
+export type UserChatRunnerThreadMessage = Pick<ChatMessage, 'content'> & {
+    sender: 'USER' | 'AGENT';
+};
+
 /**
  * Creates one persisted user-authored message for a durable chat turn.
  */
@@ -90,6 +96,36 @@ export function resolvePromptThreadBeforeUserMessage(
     return messages.slice(0, userMessageIndex);
 }
 
+/**
+ * Creates the complete chat thread mirrored to a runner before it writes the next answer.
+ */
+export function createUserChatRunnerThreadMessages(options: {
+    messages: ReadonlyArray<ChatMessage>;
+    userMessageId: string;
+    resolveInitialAgentMessage: () => string | null | undefined;
+}): Array<UserChatRunnerThreadMessage> {
+    const userMessage = options.messages.find((message) => message.id === options.userMessageId);
+    if (!userMessage) {
+        return [];
+    }
+
+    const previousThreadMessages = resolvePromptThreadBeforeUserMessage(options.messages, options.userMessageId);
+
+    return [
+        ...createInitialUserChatRunnerThreadMessages({
+            isFirstUserTurn: previousThreadMessages.length === 0,
+            resolveInitialAgentMessage: options.resolveInitialAgentMessage,
+        }),
+        ...previousThreadMessages,
+        userMessage,
+    ]
+        .filter(isUserChatRunnerThreadMessage)
+        .map((message) => ({
+            sender: message.sender,
+            content: message.content,
+        }));
+}
+
 /**
  * Maps durable job status values to message lifecycle labels rendered by the UI.
  */
@@ -108,3 +144,35 @@ export function resolveMessageLifecycleStateFromJobStatus(status: string): UserC
             return 'completed';
     }
 }
+
+/**
+ * Recreates the synthetic first agent message that the UI shows for empty durable chats.
+ */
+function createInitialUserChatRunnerThreadMessages(options: {
+    isFirstUserTurn: boolean;
+    resolveInitialAgentMessage: () => string | null | undefined;
+}): Array<UserChatRunnerThreadMessage> {
+    if (!options.isFirstUserTurn) {
+        return [];
+    }
+
+    const initialAgentMessage = options.resolveInitialAgentMessage();
+    if (!initialAgentMessage || initialAgentMessage.trim().length === 0) {
+        return [];
+    }
+
+    return [
+        {
+            sender: 'AGENT',
+            content: initialAgentMessage,
+        },
+    ];
+}
+
+/**
+ * Returns true when one persisted message should be visible to out-of-process runners.
+ */
+function isUserChatRunnerThreadMessage(message: ChatMessage): message is ChatMessage & UserChatRunnerThreadMessage {
+    const isRunnerSender = message.sender === 'USER' || message.sender === 'AGENT';
+    return message.isComplete !== false && isRunnerSender;
+}

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

@@ -0,0 +1,360 @@
+import type { ChatMessage } from '@promptbook-local/types';
+import { spaceTrim } from '../../../../../src/_packages/utils.index';
+
+/**
+ * User-facing phases shown while one durable chat answer is being prepared.
+ */
+export type UserChatProgressPhase =
+    | 'queued'
+    | 'reading_context'
+    | 'preparing_agent'
+    | 'checking_capabilities'
+    | 'starting_response';
+
+/**
+ * Real runtime details surfaced into the user-facing progress card text.
+ *
+ * Only signals that are already known at the corresponding phase are filled in,
+ * so the produced markdown reflects what the worker is actually doing right now
+ * instead of a generic scripted summary.
+ */
+export type UserChatProgressContext = {
+    /**
+     * Resolved human-readable agent name, when already loaded for this turn.
+     */
+    readonly agentName?: string;
+
+    /**
+     * Stable agent identifier shown when the human-readable name is not yet known.
+     */
+    readonly agentPermanentId?: string;
+
+    /**
+     * Resolved LLM provider title (e.g. `OpenAI`, `Anthropic`), when already known.
+     */
+    readonly provider?: string;
+
+    /**
+     * Number of attachments the user submitted with the current turn.
+     */
+    readonly attachmentCount?: number;
+
+    /**
+     * Number of agent-defined tools available to the model for this turn.
+     */
+    readonly toolCount?: number;
+
+    /**
+     * Concise user-facing tool labels (e.g. `web browser`, `calendar`) for the progress text.
+     */
+    readonly toolHighlights?: ReadonlyArray<string>;
+
+    /**
+     * Number of knowledge sources the agent will reference during the turn.
+     */
+    readonly knowledgeSourceCount?: number;
+
+    /**
+     * Whether the calendar integration is wired up for this turn.
+     */
+    readonly hasCalendarAccess?: boolean;
+
+    /**
+     * Whether the email-sending integration is wired up for this turn.
+     */
+    readonly hasEmailAccess?: boolean;
+
+    /**
+     * Whether one or more project repositories are linked to this turn.
+     */
+    readonly hasProjectAccess?: boolean;
+
+    /**
+     * Whether the AgentKit runtime for this agent came from the in-process cache.
+     */
+    readonly isAgentKitCached?: boolean;
+};
+
+/**
+ * Ordered progress item identifiers shared across all durable chat phases.
+ */
+const USER_CHAT_PROGRESS_ITEM_IDS = {
+    RECEIVE_MESSAGE: 'receive-message',
+    PREPARE_AGENT: 'prepare-agent',
+    CHECK_CAPABILITIES: 'check-capabilities',
+    CREATE_RESPONSE: 'create-response',
+} as const;
+
+/**
+ * Static checklist mapping for one durable chat phase.
+ */
+type UserChatProgressPhaseChecklist = {
+    readonly completedItemIds: ReadonlySet<string>;
+};
+
+/**
+ * Static checklist progression shared across all durable chat phases.
+ */
+const USER_CHAT_PROGRESS_PHASE_CHECKLISTS: Record<UserChatProgressPhase, UserChatProgressPhaseChecklist> = {
+    queued: { completedItemIds: new Set([]) },
+    reading_context: { completedItemIds: new Set([USER_CHAT_PROGRESS_ITEM_IDS.RECEIVE_MESSAGE]) },
+    preparing_agent: {
+        completedItemIds: new Set([
+            USER_CHAT_PROGRESS_ITEM_IDS.RECEIVE_MESSAGE,
+            USER_CHAT_PROGRESS_ITEM_IDS.PREPARE_AGENT,
+        ]),
+    },
+    checking_capabilities: {
+        completedItemIds: new Set([
+            USER_CHAT_PROGRESS_ITEM_IDS.RECEIVE_MESSAGE,
+            USER_CHAT_PROGRESS_ITEM_IDS.PREPARE_AGENT,
+            USER_CHAT_PROGRESS_ITEM_IDS.CHECK_CAPABILITIES,
+        ]),
+    },
+    starting_response: {
+        completedItemIds: new Set([
+            USER_CHAT_PROGRESS_ITEM_IDS.RECEIVE_MESSAGE,
+            USER_CHAT_PROGRESS_ITEM_IDS.PREPARE_AGENT,
+            USER_CHAT_PROGRESS_ITEM_IDS.CHECK_CAPABILITIES,
+        ]),
+    },
+};
+
+/**
+ * Base progress items shown for durable chat jobs before model-specific progress arrives.
+ */
+const USER_CHAT_PROGRESS_ITEMS: ReadonlyArray<{
+    readonly id: string;
+    readonly text: string;
+}> = [
+    {
+        id: USER_CHAT_PROGRESS_ITEM_IDS.RECEIVE_MESSAGE,
+        text: 'Read the user request',
+    },
+    {
+        id: USER_CHAT_PROGRESS_ITEM_IDS.PREPARE_AGENT,
+        text: 'Prepare the agent context',
+    },
+    {
+        id: USER_CHAT_PROGRESS_ITEM_IDS.CHECK_CAPABILITIES,
+        text: 'Check available tools and inputs',
+    },
+    {
+        id: USER_CHAT_PROGRESS_ITEM_IDS.CREATE_RESPONSE,
+        text: 'Create the response',
+    },
+];
+
+/**
+ * Creates one user-facing durable chat progress card for the current job phase.
+ *
+ * The optional `context` carries already-resolved runtime details (agent name, provider,
+ * tool count, attachment count, integrations) so the rendered `now`/`next` text reflects
+ * what the worker is actually doing on this turn instead of a generic scripted summary.
+ */
+export function createUserChatProgressCard(
+    phase: UserChatProgressPhase,
+    context?: UserChatProgressContext,
+): NonNullable<ChatMessage['progressCard']> {
+    const checklist = USER_CHAT_PROGRESS_PHASE_CHECKLISTS[phase];
+    const { now, next } = composeUserChatProgressPhaseText(phase, context);
+
+    return {
+        now,
+        next,
+        items: USER_CHAT_PROGRESS_ITEMS.map((item) => ({
+            ...item,
+            status: checklist.completedItemIds.has(item.id) ? 'completed' : 'pending',
+        })),
+        updatedAt: new Date().toISOString() as NonNullable<ChatMessage['progressCard']>['updatedAt'],
+        isVisible: true,
+    };
+}
+
+/**
+ * Composes the dynamic `now`/`next` markdown shown for one durable chat phase.
+ *
+ * @private internal helper of `createUserChatProgressCard`
+ */
+function composeUserChatProgressPhaseText(
+    phase: UserChatProgressPhase,
+    context: UserChatProgressContext | undefined,
+): { now: string; next: string } {
+    const agentLabel = describeAgent(context);
+
+    switch (phase) {
+        case 'queued':
+            return {
+                now: spaceTrim(`
+                    Your message is waiting in the queue for the next available worker to pick it up.
+                `),
+                next: spaceTrim(`
+                    Read the conversation and load ${agentLabel}.
+                `),
+            };
+        case 'reading_context': {
+            const attachmentHint = describeAttachmentHint(context);
+            return {
+                now: spaceTrim(`
+                    Reading your latest message${attachmentHint} together with the earlier conversation thread.
+                `),
+                next: spaceTrim(`
+                    Resolve ${agentLabel} and load its instructions, persona, and rules.
+                `),
+            };
+        }
+        case 'preparing_agent': {
+            const knowledgeHint = describeKnowledgeHint(context);
+            return {
+                now: spaceTrim(`
+                    Loading the instructions and configured commitments for ${agentLabel}${knowledgeHint}.
+                `),
+                next: spaceTrim(`
+                    Check which tools, integrations, and attachments are usable for this turn.
+                `),
+            };
+        }
+        case 'checking_capabilities': {
+            const capabilitiesText = describeCapabilities(context);
+            return {
+                now: spaceTrim(`
+                    Verifying that ${agentLabel} can use ${capabilitiesText} for this answer.
+                `),
+                next: spaceTrim(`
+                    Connect to the language model and start streaming the response.
+                `),
+            };
+        }
+        case 'starting_response': {
+            const providerHint = describeProviderHint(context);
+            const cacheHint = context?.isAgentKitCached === false
+                ? ' Fresh runtime is being prepared because no cached agent was available.'
+                : '';
+            return {
+                now: spaceTrim(`
+                    Calling the language model${providerHint} and waiting for the first tokens.${cacheHint}
+                `),
+                next: spaceTrim(`
+                    Stream the response and update this panel with each user-relevant decision, action, or result.
+                `),
+            };
+        }
+    }
+}
+
+/**
+ * Returns the user-facing label for the active agent based on available context.
+ *
+ * @private internal helper of `composeUserChatProgressPhaseText`
+ */
+function describeAgent(context: UserChatProgressContext | undefined): string {
+    if (context?.agentName) {
+        return `agent **${context.agentName}**`;
+    }
+
+    if (context?.agentPermanentId) {
+        return `agent \`${context.agentPermanentId}\``;
+    }
+
+    return 'the agent';
+}
+
+/**
+ * Returns a fragment describing attachment count when one or more attachments are present.
+ *
+ * @private internal helper of `composeUserChatProgressPhaseText`
+ */
+function describeAttachmentHint(context: UserChatProgressContext | undefined): string {
+    const count = context?.attachmentCount ?? 0;
+    if (count <= 0) {
+        return '';
+    }
+
+    return count === 1 ? ' and 1 attachment' : ` and ${count} attachments`;
+}
+
+/**
+ * Returns a fragment describing knowledge sources when one or more are configured.
+ *
+ * @private internal helper of `composeUserChatProgressPhaseText`
+ */
+function describeKnowledgeHint(context: UserChatProgressContext | undefined): string {
+    const count = context?.knowledgeSourceCount ?? 0;
+    if (count <= 0) {
+        return '';
+    }
+
+    return count === 1 ? ' (1 knowledge source)' : ` (${count} knowledge sources)`;
+}
+
+/**
+ * Returns a fragment describing the LLM provider when already known.
+ *
+ * @private internal helper of `composeUserChatProgressPhaseText`
+ */
+function describeProviderHint(context: UserChatProgressContext | undefined): string {
+    if (!context?.provider) {
+        return '';
+    }
+
+    return ` via ${context.provider}`;
+}
+
+/**
+ * Builds the markdown fragment describing tools, knowledge, attachments, and integrations.
+ *
+ * @private internal helper of `composeUserChatProgressPhaseText`
+ */
+function describeCapabilities(context: UserChatProgressContext | undefined): string {
+    if (!context) {
+        return 'its configured tools and inputs';
+    }
+
+    const fragments: Array<string> = [];
+
+    const toolCount = context.toolCount ?? 0;
+    if (toolCount > 0) {
+        const highlights = (context.toolHighlights ?? []).filter((entry) => entry.trim().length > 0);
+        if (highlights.length > 0) {
+            fragments.push(`${toolCount === 1 ? '1 tool' : `${toolCount} tools`} (${highlights.join(', ')})`);
+        } else {
+            fragments.push(toolCount === 1 ? '1 tool' : `${toolCount} tools`);
+        }
+    }
+
+    const knowledgeCount = context.knowledgeSourceCount ?? 0;
+    if (knowledgeCount > 0) {
+        fragments.push(knowledgeCount === 1 ? '1 knowledge source' : `${knowledgeCount} knowledge sources`);
+    }
+
+    const attachmentCount = context.attachmentCount ?? 0;
+    if (attachmentCount > 0) {
+        fragments.push(attachmentCount === 1 ? '1 attachment' : `${attachmentCount} attachments`);
+    }
+
+    const integrations: Array<string> = [];
+    if (context.hasCalendarAccess) {
+        integrations.push('calendar');
+    }
+    if (context.hasEmailAccess) {
+        integrations.push('email');
+    }
+    if (context.hasProjectAccess) {
+        integrations.push('project repository');
+    }
+    if (integrations.length > 0) {
+        fragments.push(`${integrations.join(' / ')} access`);
+    }
+
+    if (fragments.length === 0) {
+        return 'its configured instructions and inputs';
+    }
+
+    if (fragments.length === 1) {
+        return fragments[0]!;
+    }
+
+    const head = fragments.slice(0, -1).join(', ');
+    const tail = fragments[fragments.length - 1]!;
+    return `${head}, and ${tail}`;
+}

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

@@ -1,6 +1,7 @@
 import { NextRequest } from 'next/server';
 import { $getTableName } from '../database/$getTableName';
 import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import { parseSessionToken, SESSION_COOKIE_NAME } from './session';
 
 /**
  * Result of Api key validation.
@@ -21,10 +22,13 @@ export type ApiKeyValidationResult = {
 export async function validateApiKey(request: NextRequest): Promise<ApiKeyValidationResult> {
     const authHeader = request.headers.get('authorization');
 
-    // If no auth header, check if user has a session cookie (logged in via web)
+    // If no auth header, check if user has a valid signed session cookie (logged in via web).
+    // The cookie value must pass HMAC-signature verification — merely sending a `sessionToken`
+    // cookie with arbitrary content must NOT authenticate the request.
     if (!authHeader) {
-        const hasSession = request.cookies.has('sessionToken');
-        if (hasSession) {
+        const sessionToken = request.cookies.get(SESSION_COOKIE_NAME)?.value;
+        const session = parseSessionToken(sessionToken);
+        if (session !== null) {
             return { isValid: true };
         }
         return {

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

@@ -22,8 +22,14 @@ export const VPS_ENVIRONMENT_VARIABLE_KEYS = [
     'SERVERS',
     'NEXT_PUBLIC_SITE_URL',
     'ADMIN_PASSWORD',
+    'SESSION_SECRET',
+    'PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN',
+    'PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN',
+    'SENDGRID_INBOUND_PARSE_PUBLIC_KEY',
+    'SENDGRID_INBOUND_PARSE_WEBHOOK_SECRET',
+    'SENDGRID_INBOUND_PARSE_HOSTS',
     'OPENAI_API_KEY',
-    'PTBK_AGENT',
+    'PTBK_HARNESS',
     'PTBK_MODEL',
     'PTBK_THINKING_LEVEL',
     'PORT',
@@ -38,6 +44,7 @@ export const VPS_ENVIRONMENT_VARIABLE_KEYS = [
     'SUPABASE_AUTO_MIGRATE',
     'COPILOT_GITHUB_TOKEN',
     'GH_TOKEN',
+    'ANTHROPIC_API_KEY',
     'ANTHROPIC_CLAUDE_API_KEY',
     'GOOGLE_GENERATIVE_AI_API_KEY',
     'AZUREOPENAI_API_KEY',