@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/state-machine/handlers/agent-planning.js

@@ -1,42 +1,187 @@
-import { getLogger } from "../../../util/logger.js";
-import { LOG_SYSTEM_PROMPT } from "../../const.js";
-import { sdkIntegrationFromPromptContext } from "../../integrations/from-prompt-context.js";
-import { integrationsToSdkPromptContent } from "../../integrations/to-sdk-prompt.js";
-import { getStaticPrompt } from "../../prompts/system.js";
-import { YamlToApiBuilderTransformer } from "../../transform/api-builder/to-sdk-transformer.js";
-import { applyFileTransformations } from "../../transform/shared.js";
-import { NpmInstallError } from "../../types.js";
-import { AGENT_PLANNED, AGENT_NEEDS_USER_INPUT, LLM_ERRORED, LLM_FINISHED_UNEXPECTEDLY, POST_PROCESSING_ERRORED, RUNTIME_REVIEW_ERRORED, USER_SENT_PROMPT, BUILD_SYSTEM_ERRORED, } from "../clark-fsm.js";
+import { AiEntityType, AiGenerationState, } from "@superblocksteam/library-shared/types";
+import { getAiQuotaPaywallReasonFromMessage, isAiQuotaPaywallReason, } from "@superblocksteam/shared";
+import { generateShortId } from "../../../ids.js";
+import { getErrorMeta, getLogger } from "../../../util/logger.js";
+import { getToolCallArguments, getToolErrorCode, getToolOutput, } from "../../agent/tool-message-utils.js";
+import { buildBlockedMessage } from "../../agent/tools/build-install-packages.js";
+import { debugCache, createTypeScriptCheckFunction, } from "../../agent/tools/debug-cache.js";
+import { handleAppKnowledgeApprovalResponse } from "../../app-skills/helpers.js";
+import { isInvalidAttachmentError, isTokenLimitError, } from "../../llm/error.js";
+import { NpmInstallBlocked, NpmInstallError } from "../../types.js";
+import { RpcTimeoutError } from "../../util/rpc-timeout.js";
+import { AGENT_PLANNED, AGENT_NEEDS_USER_INPUT, LLM_ERRORED, LLM_FINISHED_UNEXPECTEDLY, POST_PROCESSING_ERRORED, RUNTIME_REVIEW_ERRORED, USER_SENT_PROMPT, BUILD_SYSTEM_ERRORED, AGENT_CANCELED, } from "../clark-fsm.js";
+import { recordChatMessageInBackground } from "../helpers/background-chat-record.js";
+import { sendChangeInfoHelper } from "../helpers/change-info.js";
+import { fetchWithReconnectRetry } from "../helpers/fetch-with-reconnect-retry.js";
 import { handlerMetadata } from "../helpers/metadata.js";
-import { sendUserCompletionChannel, sendUserMessageChannel, } from "../helpers/peer.js";
+import { flushDeferredInteractiveMessage, sendUserMessageChannel, sendUserGenerationStateChannel, clearPendingToolPermissionRequest, } from "../helpers/peer.js";
+import { paywallStopAdvice } from "../helpers/prompt-failure.js";
+import { promptFailureFromLlmError, promptFailureLlmProviderUnknown, promptFailurePaywall, promptFailurePlatform, isOrganicPromptDuringAwaitingUserHandoff, recordAwaitingUserHandoffDismissed, } from "../helpers/prompt-request-metrics.js";
+import { isPeerUnavailableError } from "../helpers/stable-peer.js";
 import { transitionFrom } from "../helpers/transition.js";
+import { persistPromptAttachments } from "./persist-prompt-attachments.js";
+// Wait briefly for a fast browser reconnect after the initial RPC timeout,
+// unbound/dead route, or transport-close drop, while keeping this foreground
+// planning step from feeling stuck.  Lowered from 15 s to 5 s as part of
+// APPS-4613 to reduce worst-case latency from 75 s → 35 s (15 s fetch + 5 s
+// reconnect + 15 s retry).
+const FETCH_INTEGRATIONS_RECONNECT_BUDGET_MS = 5_000;
+// TODO: make dynamically configurable
 const MAX_DEBUG_ATTEMPTS = 5;
+/**
+ * Gets user-facing error message for terminal LLM errors.
+ *
+ * Terminal errors are errors that cannot be retried (either because they're
+ * inherently non-retryable or because we've exhausted retry attempts).
+ *
+ * @param error - The LLMProviderError with standardized type and context
+ * @returns User-facing error message
+ * @internal Exported for unit testing only; not part of the module's public API.
+ */
+export function getTerminalErrorMessage(error) {
+    const { type, provider, data } = error;
+    // Checked before the switch. An oversized prompt is rejected as a 400, which
+    // `validation_error` covers along with every other bad request, so it used to
+    // produce "There was an issue processing your request. Please try again after
+    // clearing chat history." That tells the user nothing about what went wrong,
+    // implies a bare retry might work when it cannot, and does not name the
+    // action. This is the condition ENG-5282 is about and we detect it
+    // precisely, so it gets its own sentence. "Clear chat history" is the trash
+    // icon's tooltip and confirmation title, the same label the attachment
+    // messages below use.
+    //
+    // Uses the same `isTokenLimitError` that `stream/retry-engine.ts` and
+    // `stream/terminal-reason.ts` gate on, so there is one definition of "the
+    // provider refused this payload for being too long".
+    //
+    // The reassurance is load-bearing and checked: New Chat deletes only
+    // `.superblocks/context` and `.superblocks/events` and archives the chat
+    // session server-side (`handleNewChat` -> `clearAllContexts` ->
+    // `deleteAllContexts` / `deleteAllEvents`). It does not touch app files or
+    // committed state.
+    if (isTokenLimitError(error)) {
+        return ("This conversation has grown too long for the model to continue. " +
+            "Use Clear chat history to start over. Your app and its files are not affected.");
+    }
+    const isClarkError = data?.isClark === true;
+    const effectiveProvider = isClarkError ? "clark" : provider;
+    // Read the DETECTION result, not just the category. `type` is advisory: an
+    // explicit `type` argument wins over classification, and `wrapError`'s
+    // isNoOutputError branch passes `{ type: "no_output", isRetryable: true }` —
+    // which is a plausible wrapper for a provider that 400s on an attachment
+    // before emitting any chunk. Keying the
+    // message off `invalidAttachment` makes the guidance an invariant no caller
+    // argument can erase, without touching the constructor's explicit-argument
+    // precedence (which other callers rely on).
+    const effectiveType = (error.invalidAttachment || isInvalidAttachmentError(error)) &&
+        type !== "aborted"
+        ? "attachment_invalid"
+        : type;
+    switch (effectiveType) {
+        case "ai_quota_exceeded":
+            return data?.message?.trim()
+                ? data.message
+                : "Your organization has reached its AI usage limit. Please contact sales to upgrade your plan.";
+        case "attachment_invalid": {
+            // Retrying can never clear this: the rejected content part is persisted
+            // in the conversation and replayed on every request. Point at the only
+            // action that works instead of inviting a retry loop.
+            const part = error.invalidAttachment;
+            // The remedy names "Clear chat history" because that is the trash icon's
+            // tooltip and confirmation title. Nothing in the editor is labelled
+            // "New Chat".
+            // A tool produced this part, so there is no file the user can re-attach —
+            // telling them to would be flatly wrong advice.
+            if (part?.fromToolResult) {
+                return "A file produced by a tool in this chat can't be read by the AI model, so it will keep failing. Use Clear chat history to start over.";
+            }
+            // Name the kind when the provider identified it: with several files
+            // attached, "one of the attachments" leaves the user re-attaching the bad
+            // one and hitting the identical failure. Some providers name no kind.
+            switch (part?.kind) {
+                case "pdf":
+                    return "A PDF attachment in this chat can't be read by the AI model, so it will keep failing. Use Clear chat history to start over, then re-attach a working copy of the file.";
+                case "image":
+                    // Images are not validated at upload, so a re-attach of the SAME file
+                    // reproduces the failure — tell them to replace it, not re-send it.
+                    return "An image attachment in this chat can't be read by the AI model, so it will keep failing. Use Clear chat history to start over, then re-export or resize the image before attaching it again.";
+                case "document":
+                    return "A document attachment in this chat can't be read by the AI model, so it will keep failing. Use Clear chat history to start over, then re-export the document before attaching it again.";
+                default:
+                    return "One of the attachments in this chat can't be read by the AI model, so it will keep failing. Use Clear chat history to start over, then re-attach a working copy of the file.";
+            }
+        }
+        case "validation_error":
+            return "There was an issue processing your request. Please try again after clearing chat history.";
+        case "auth_error":
+            if (effectiveProvider === "clark") {
+                return "Your session couldn't be authenticated. Please refresh the page and try again.";
+            }
+            return "There was an authentication issue. Please check your API key and permissions, then try again.";
+        case "not_found":
+            return "The requested resource could not be found. Please verify your configuration and try again.";
+        case "rate_limit":
+            return "Rate limit reached. Please wait a few minutes before trying again.";
+        case "api_error":
+            return "The AI model returned an error. Please retry your prompt below. If the problem persists, the model provider may be experiencing issues.";
+        case "timeout":
+            return "The request timed out. Please check your connection and try again.";
+        case "stall":
+            return "The AI model stopped responding mid-generation. Please retry your prompt below. If the problem persists, please open a support ticket.";
+        case "overloaded":
+            return "The model is currently busy. Please retry your prompt below.";
+        case "network":
+            return "A network error occurred. Please check your connection and try again.";
+        case "retries_exhausted":
+            return "The request failed after multiple attempts. Please refresh the page and try again.";
+        case "unknown":
+        default:
+            return "Something went wrong. Please try again, or contact support if the issue persists.";
+    }
+}
 export const doAgentPlanning = (clark, params) => {
     const transitionTo = transitionFrom(clark);
-    const sendUserMessage = sendUserMessageChannel(clark);
-    const sendUserCompletion = sendUserCompletionChannel(clark);
+    const sendUserMessage = sendUserMessageChannel(clark, params.chatSessionStore);
+    const sendUserGenerationState = sendUserGenerationStateChannel(clark);
+    const sendChangeInfo = sendChangeInfoHelper(clark, params.chatSessionStore);
     const { getMeta, updateMeta } = handlerMetadata(clark);
-    const debug = async (debuggingPromptIntro, filePaths = []) => {
-        let { debugCount = 0 } = getMeta() ?? {};
-        if (!filePaths.includes("package.json")) {
-            filePaths.push("package.json");
-        }
-        debugCount++;
-        updateMeta({ debugCount });
-        if (debugCount > MAX_DEBUG_ATTEMPTS) {
-            transitionTo({
-                type: AGENT_NEEDS_USER_INPUT,
-                advice: "I've reached the maximum number of attempts to fix the errors. You may need to reject the changes and try again.",
+    const debug = clark.tracer.wrap({ kind: "task" }, async (debuggingPromptIntro, filePaths = []) => {
+        return params.clarkProfiler
+            .getProfiler()
+            .timeAsync("debug_session", async () => {
+            let { debugCount = 0 } = getMeta() ?? {};
+            if (!filePaths.includes("package.json")) {
+                filePaths.push("package.json");
+            }
+            debugCount++;
+            clark.tracer.annotate({
+                tags: {
+                    "debug.loop": true,
+                    "debug.count": debugCount,
+                },
             });
-            return;
-        }
-        sendUserMessage({
-            text: debugCount === 1
-                ? "I found some problems in the app. Let me address them."
-                : `Still trying to fix the errors… (attempt ${debugCount} of ${MAX_DEBUG_ATTEMPTS})`,
-        });
-        const diff = await params.draftInterface.getDraftDiff(filePaths);
-        const debuggingPrompt = `${debuggingPromptIntro}
+            updateMeta({ debugCount });
+            clark.updateContext({
+                usedDebugging: true,
+            });
+            if (debugCount > MAX_DEBUG_ATTEMPTS) {
+                void transitionTo({
+                    type: AGENT_NEEDS_USER_INPUT,
+                    advice: "I've reached the maximum number of attempts to fix the errors. You may need to reject the changes and try again.",
+                });
+                return;
+            }
+            // sendUserMessage({
+            //   type: "control",
+            //   group: "debugging",
+            //   status: "pending",
+            //   text:
+            //     debugCount === 1
+            //       ? "I found some problems in the app. Let me address them."
+            //       : `Still trying to fix the errors… (attempt ${debugCount} of ${MAX_DEBUG_ATTEMPTS})`,
+            // });
+            const diff = await params.draftInterface.getDraftDiff(filePaths);
+            const debuggingPrompt = `${debuggingPromptIntro}
 
 Below is the diff of the changes made to the relevant files:
 ---
@@ -44,99 +189,879 @@ ${diff}
 ---
 
 Address the errors and return the fixed code.`;
-        const systemPrompt = await createSystemPrompt(getMeta()?.request, params, filePaths);
-        transitionTo({
-            type: AGENT_PLANNED,
-            systemPrompt,
-            userPrompt: debuggingPrompt,
-            debugging: true,
+            getLogger().info(`[ai-service] debugging ${debugCount}: ${debuggingPromptIntro}`);
+            void transitionTo({
+                type: AGENT_PLANNED,
+                userPrompt: debuggingPrompt,
+                debugging: true,
+                isUserPrompt: false, // Debugging prompts are system-generated
+            });
         });
-    };
+    });
     return async ({ event }) => {
         switch (event.type) {
             case USER_SENT_PROMPT: {
-                const { request, peer } = event;
+                // Clear error history for new generation
+                debugCache.getErrorHistoryTracker().clear();
+                const { request, inputSource, internal: isInternalTurn, visibleInChatHistory, } = event;
+                if (isOrganicPromptDuringAwaitingUserHandoff({
+                    awaitingUserHandoffRecorded: clark.context.awaitingUserHandoffRecorded,
+                    internal: isInternalTurn,
+                    responseMetadata: request.responseMetadata,
+                })) {
+                    recordAwaitingUserHandoffDismissed({
+                        awaitingUserHandoffPromptId: clark.context.awaitingUserHandoffPromptId,
+                        awaitingUserHandoffRecorded: clark.context.awaitingUserHandoffRecorded,
+                        promptId: clark.context.promptId,
+                        promptOutcomeDedupeKey: clark.context.promptOutcomeDedupeKey,
+                        reason: "new_prompt",
+                    });
+                }
+                if (clark.context.awaitingUserHandoffRecorded) {
+                    clark.updateContext({
+                        awaitingUserHandoffPromptId: undefined,
+                        awaitingUserHandoffRecorded: undefined,
+                    });
+                }
+                const promptContextWithUploadedAttachments = request.promptContext;
+                const pendingIntegrationActionMessageId = clark.context.pendingIntegrationActionPrompt?.messageId;
+                const previousMode = clark.context.currentMode;
+                // Tier 1 — hard-coded /remember command marks this turn as an explicit
+                // knowledge-capture intent so the model drafts a candidate.
+                const isRememberCommand = /^\s*\/remember\b/i.test(request.prompt);
+                const isKnowledgeApprovalResponse = (request.responseMetadata?.type === "multi_choice_response" ||
+                    request.responseMetadata?.type ===
+                        "remember_knowledge_draft_response" ||
+                    request.responseMetadata?.type === "confirm_response") &&
+                    clark.context.pendingAppKnowledge?.messageId ===
+                        request.responseMetadata.responseToMessageId;
+                const isPendingKnowledgeFreeTextResponse = request.responseMetadata?.type === "multi_choice_response" &&
+                    isKnowledgeApprovalResponse &&
+                    request.prompt.trim().length > 0 &&
+                    (!Array.isArray(request.responseMetadata.selectedChoiceIndices) ||
+                        request.responseMetadata.selectedChoiceIndices.length === 0);
+                const effectiveMode = request.mode ?? clark.context.currentMode;
+                const preserveChatmessageId = request.responseMetadata?.type === "tool_permission_response";
+                clark.updateContext((context) => ({
+                    ...context,
+                    currentMode: effectiveMode,
+                    // Clear testing state when user sends a new prompt
+                    currentTestRunId: undefined,
+                    // Chat recording is non-blocking, so the previous turn's id must
+                    // be dropped now — otherwise this turn's LLM usage would be
+                    // attributed to the previous turn's chat message until the new
+                    // write resolves (see recordChatMessageInBackground). Tool
+                    // permission continuations do not write a new chat message, so they
+                    // keep the original prompt's id for the resumed LLM call.
+                    chatmessageId: preserveChatmessageId
+                        ? context.chatmessageId
+                        : undefined,
+                    // Clear per-turn knowledge intent/candidates on each new user prompt
+                    explicitRememberKnowledgeIntentForTurn: isRememberCommand
+                        ? true
+                        : undefined,
+                    rememberKnowledgeCandidatesForTurn: undefined,
+                    pendingKnowledgeFreeTextTurn: undefined,
+                    // Default clear; if this is a multi_choice_response, the response
+                    // handler below will repopulate it with the question + selected
+                    // choice texts so LLM_ERRORED can promote it on paywall.
+                    lastTurnMultiChoiceContext: undefined,
+                }));
+                if (previousMode !== effectiveMode) {
+                    clark.logger.info("[agent-planning] Mode changed", {
+                        from: previousMode,
+                        to: effectiveMode,
+                        isRememberCommand,
+                    });
+                }
+                let isIntegrationActionResponse = false;
+                // Record user message - use recordUserResponse if this is a response to an interactive message
+                if (request.responseMetadata) {
+                    if (request.responseMetadata.type === "tool_permission_response") {
+                        const pendingToolPermissionRequest = clark.context.pendingToolPermissionRequest;
+                        if (pendingToolPermissionRequest &&
+                            pendingToolPermissionRequest.messageId ===
+                                request.responseMetadata.responseToMessageId) {
+                            if (request.responseMetadata.approved) {
+                                params.entityPermissionStore.approveToolCall(pendingToolPermissionRequest.toolName, pendingToolPermissionRequest.rawInput);
+                                request.responseMetadata.alwaysAllowPermissions?.forEach((permission) => {
+                                    void params.entityPermissionStore.approve(permission.entityType, permission.entityId, permission.permissionType);
+                                });
+                            }
+                            clearPendingToolPermissionRequest(clark, "tool-permission-response-handled");
+                        }
+                        if (clark.context.activeInteractiveMessage) {
+                            clark.updateContext({ activeInteractiveMessage: undefined });
+                        }
+                        if (request.responseMetadata.clarification &&
+                            request.prompt.trim()) {
+                            void clark.context.peer.call
+                                .aiPushMessage({
+                                role: "user",
+                                type: "text",
+                                content: request.prompt,
+                                id: crypto.randomUUID(),
+                                timestamp: Date.now(),
+                            })
+                                .catch((err) => {
+                                getLogger().warn("[agent-planning] Failed to echo tool-permission clarification to UI", err);
+                            });
+                            recordChatMessageInBackground({
+                                clark,
+                                record: () => params.chatSessionStore.recordUser(request.prompt, {
+                                    attachments: request.promptContext?.attachments,
+                                }),
+                            });
+                        }
+                    }
+                    else {
+                        const isTypedOverride = (request.responseMetadata.type === "multi_choice_response" &&
+                            request.responseMetadata.selectedChoiceIndices.length === 0) ||
+                            (request.responseMetadata.type === "plan_response" &&
+                                !request.responseMetadata.approved);
+                        const responseMessage = request.responseMetadata.type === "multi_choice_response" &&
+                            request.responseMetadata.selectedChoiceIndices.length > 0
+                            ? {
+                                content: request.prompt,
+                                id: crypto.randomUUID(),
+                                responseToMessageId: request.responseMetadata.responseToMessageId,
+                                role: "user",
+                                selectedChoiceIndices: request.responseMetadata.selectedChoiceIndices,
+                                selectedScopes: request.responseMetadata.selectedScopes,
+                                timestamp: Date.now(),
+                                type: "multi_choice_response",
+                            }
+                            : isTypedOverride
+                                ? {
+                                    content: request.prompt,
+                                    id: crypto.randomUUID(),
+                                    role: "user",
+                                    timestamp: Date.now(),
+                                    type: "text",
+                                }
+                                : undefined;
+                        if (responseMessage && inputSource?.kind === "editor") {
+                            clark.context.peer.pushMessageToObservers(responseMessage, inputSource, { includeInputPeer: isTypedOverride });
+                        }
+                        else if (responseMessage && isTypedOverride && !inputSource) {
+                            void clark.context.peer.call
+                                .aiPushMessage(responseMessage)
+                                .catch((err) => {
+                                getLogger().warn("[agent-planning] Failed to echo user response to UI", {
+                                    promptId: clark.context.promptId,
+                                    responseType: request.responseMetadata?.type,
+                                }, err);
+                            });
+                        }
+                        // If this is a response to an interactive message, clear it from context
+                        clark.updateContext({
+                            activeInteractiveMessage: undefined,
+                        });
+                        await flushDeferredInteractiveMessage(clark, params.chatSessionStore);
+                        const handledKnowledge = await handleAppKnowledgeApprovalResponse(clark, params, request, request.responseMetadata.type === "multi_choice_response"
+                            ? responseMessage?.id
+                            : undefined);
+                        if (handledKnowledge) {
+                            return;
+                        }
+                        if (request.responseMetadata.type === "multi_choice_response") {
+                            if (pendingIntegrationActionMessageId &&
+                                request.responseMetadata.responseToMessageId ===
+                                    pendingIntegrationActionMessageId) {
+                                isIntegrationActionResponse = true;
+                            }
+                            else {
+                                const messages = await params.chatSessionStore.getMessages();
+                                const parentMessage = messages.find((msg) => msg.type === "multi_choice" &&
+                                    msg.id === request.responseMetadata?.responseToMessageId);
+                                const parentChoices = (parentMessage?.choices ?? []).map((choice) => typeof choice === "string" ? choice : choice.text);
+                                isIntegrationActionResponse =
+                                    parentChoices.length === 2 &&
+                                        parentChoices.includes("Discard integration setup") &&
+                                        parentChoices.includes("Save integration");
+                                // Capture the multi-choice question + the user's selection so
+                                // that if this turn's LLM call fails with a paywall, the next
+                                // turn's resume hint can re-state the user's specific choice
+                                // (option A in APPS-4080 — the generic "proceed as you
+                                // normally would" hint led the model to re-decide open
+                                // questions on its own; surfacing the prior selection
+                                // explicitly pins it). Skip integration save/discard
+                                // actions — those are special-cased UI banners, not
+                                // questions the model needs to acknowledge.
+                                if (!isIntegrationActionResponse && parentMessage) {
+                                    const selected = request.responseMetadata.selectedChoiceIndices ?? [];
+                                    const selectedChoiceTexts = selected
+                                        .filter((i) => typeof i === "number" &&
+                                        i >= 0 &&
+                                        i < parentChoices.length)
+                                        .map((i) => parentChoices[i]);
+                                    const userTypedFreeText = selectedChoiceTexts.length === 0 &&
+                                        request.prompt.trim().length > 0;
+                                    clark.updateContext({
+                                        lastTurnMultiChoiceContext: {
+                                            question: parentMessage.content ?? "",
+                                            selectedChoiceTexts,
+                                            userText: userTypedFreeText ? request.prompt : undefined,
+                                        },
+                                    });
+                                }
+                                // Integration action or missing parent: leave the default
+                                // `undefined` set at the top of USER_SENT_PROMPT in place.
+                            }
+                        }
+                        // Non-multi-choice responses (confirm, plan, dropdown, knowledge)
+                        // leave the default `undefined` in place from the top of
+                        // USER_SENT_PROMPT, so a later paywall in a different turn
+                        // doesn't resurface a stale selection hint.
+                        // If the user sent a chat message in response to a multi-choice fact
+                        // approval (instead of selecting choices), restore the candidates so
+                        // the model can see them and decide which facts to keep based on the
+                        // user's chat response.
+                        if (clark.context.pendingAppKnowledge) {
+                            clark.updateContext((ctx) => ({
+                                ...ctx,
+                                rememberKnowledgeCandidatesForTurn: ctx.pendingAppKnowledge?.knowledgeEntries,
+                                pendingKnowledgeFreeTextTurn: isPendingKnowledgeFreeTextResponse,
+                            }));
+                        }
+                        const metadata = request.responseMetadata.type === "multi_choice_response"
+                            ? {
+                                ...(responseMessage?.id
+                                    ? { messageId: responseMessage.id }
+                                    : {}),
+                                responseToMessageId: request.responseMetadata.responseToMessageId,
+                                selectedChoiceIndices: request.responseMetadata.selectedChoiceIndices,
+                                selectedScopes: request.responseMetadata.selectedScopes,
+                            }
+                            : request.responseMetadata.type ===
+                                "remember_knowledge_draft_response"
+                                ? {
+                                    responseToMessageId: request.responseMetadata.responseToMessageId,
+                                    selectedCandidateIndices: request.responseMetadata.selectedCandidateIndices,
+                                    selectedScopes: request.responseMetadata.selectedScopes,
+                                }
+                                : request.responseMetadata.type === "confirm_response"
+                                    ? {
+                                        responseToMessageId: request.responseMetadata.responseToMessageId,
+                                        approved: request.responseMetadata.approved,
+                                        selectedScopes: request.responseMetadata.selectedScopes,
+                                    }
+                                    : request.responseMetadata.type ===
+                                        "searchable_dropdown_response"
+                                        ? {
+                                            responseToMessageId: request.responseMetadata.responseToMessageId,
+                                            selectedValue: request.responseMetadata.selectedValue,
+                                            selectedLabel: request.responseMetadata.selectedLabel,
+                                        }
+                                        : {
+                                            ...(responseMessage?.id
+                                                ? { messageId: responseMessage.id }
+                                                : {}),
+                                            responseToMessageId: request.responseMetadata.responseToMessageId,
+                                            approved: request.responseMetadata.approved,
+                                            enableTesting: request.responseMetadata.enableTesting,
+                                        };
+                        // Echo the persisted user response to the UI so the optimistic
+                        // overlay is replaced by a server-confirmed entry at the correct
+                        // position in the message list. Only echo when the user typed
+                        // free text instead of selecting a widget option — widget
+                        // interactions (confirm, dropdown, knowledge draft, and
+                        // multi-choice selections) are hidden response types that must
+                        // not appear as visible text bubbles.
+                        const responseMetadataType = request.responseMetadata.type;
+                        recordChatMessageInBackground({
+                            clark,
+                            record: () => params.chatSessionStore.recordUserResponse(request.prompt, responseMetadataType, metadata),
+                        });
+                        if (isIntegrationActionResponse) {
+                            const selectedResponseText = request.prompt.trim().toLowerCase();
+                            const toolName = selectedResponseText.includes("save integration")
+                                ? "saveIntegration"
+                                : selectedResponseText.includes("discard integration setup") ||
+                                    selectedResponseText.includes("close integration setup")
+                                    ? "closeIntegrationSetup"
+                                    : null;
+                            clark.updateContext({
+                                pendingIntegrationActionPrompt: undefined,
+                            });
+                            if (!toolName || toolName === "saveIntegration") {
+                                // For "Save integration" (and free-text), hand off to the LLM.
+                                // Clark will call saveIntegration itself, then follow up based
+                                // on the result (close on success, reopen on failure).
+                                // For free-text, the normal planning flow handles it.
+                                void sendUserGenerationState({
+                                    state: AiGenerationState.GENERATING,
+                                });
+                                void sendUserMessageChannel(clark, params.chatSessionStore)({
+                                    type: "reasoning",
+                                    role: "assistant",
+                                    content: "",
+                                });
+                                void transitionTo({
+                                    type: AGENT_PLANNED,
+                                    userPrompt: request.prompt,
+                                    promptContext: request.promptContext,
+                                    isUserPrompt: false,
+                                });
+                                return;
+                            }
+                            else {
+                                // closeIntegrationSetup — execute directly, no LLM needed.
+                                const toolInput = {};
+                                const toolCallId = crypto.randomUUID();
+                                const sendUserMessage = sendUserMessageChannel(clark, params.chatSessionStore);
+                                const args = await getToolCallArguments(toolName, toolInput, clark);
+                                void sendUserMessage({
+                                    role: "assistant",
+                                    content: "",
+                                    type: "tool",
+                                    tool: toolName,
+                                    toolCallId,
+                                    args,
+                                });
+                                const accessControlContext = clark.getAccessControl(params.features);
+                                const result = await params.toolRegistry.execute(toolName, toolInput, accessControlContext, { toolCallId, messages: [] });
+                                if (result.type === "success") {
+                                    const output = getToolOutput(toolName, result.data);
+                                    void sendUserMessage({
+                                        role: "assistant",
+                                        content: "",
+                                        type: "tool-result",
+                                        toolCallId,
+                                        toolName,
+                                        output,
+                                    });
+                                }
+                                else {
+                                    const errorCode = getToolErrorCode(result.error);
+                                    void sendUserMessage({
+                                        role: "assistant",
+                                        content: "",
+                                        type: "tool-error",
+                                        toolCallId,
+                                        toolName,
+                                        error: result.error.message,
+                                        errorCode,
+                                    });
+                                }
+                                void transitionTo({
+                                    type: AGENT_NEEDS_USER_INPUT,
+                                    countsAsPromptSuccess: true,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                }
+                else {
+                    if (clark.context.activeInteractiveMessage) {
+                        clark.updateContext({ activeInteractiveMessage: undefined });
+                    }
+                    if (clark.context.pendingIntegrationActionPrompt) {
+                        clark.updateContext({ pendingIntegrationActionPrompt: undefined });
+                    }
+                    // If the user continues with a new prompt instead of approving pending
+                    // app knowledge, treat that as an implicit rejection and clear
+                    // pending state so no stale candidates can be saved later.
+                    if (clark.context.pendingAppKnowledge) {
+                        clark.updateContext((ctx) => ({
+                            ...ctx,
+                            pendingAppKnowledge: undefined,
+                            rememberKnowledgeCandidatesForTurn: undefined,
+                            explicitRememberKnowledgeIntentForTurn: undefined,
+                            pendingKnowledgeFreeTextTurn: undefined,
+                        }));
+                    }
+                    const promptForRecording = clark.context.interruptOriginalPrompt ?? request.prompt;
+                    clark.updateContext({ interruptOriginalPrompt: undefined });
+                    const shouldRecordUserPrompt = !isInternalTurn || visibleInChatHistory === true;
+                    let shouldSkipDuplicateInternalPrompt = false;
+                    if (shouldRecordUserPrompt &&
+                        isInternalTurn &&
+                        visibleInChatHistory === true) {
+                        try {
+                            const messages = await params.chatSessionStore.getMessages();
+                            const lastUserTextMessage = [...messages]
+                                .reverse()
+                                .find((message) => message.role === "user" && message.type === "text");
+                            shouldSkipDuplicateInternalPrompt =
+                                lastUserTextMessage?.content.trim() ===
+                                    promptForRecording.trim();
+                        }
+                        catch (error) {
+                            getLogger().warn("[agent-planning] Failed to inspect chat history for duplicate internal prompt", error);
+                        }
+                    }
+                    if (!shouldRecordUserPrompt) {
+                        getLogger().info(`[agent-planning] Internal turn: skipping chat session recording`);
+                    }
+                    else if (shouldSkipDuplicateInternalPrompt) {
+                        getLogger().info(`[agent-planning] Internal turn: skipping duplicate visible prompt`);
+                    }
+                    else {
+                        getLogger().info(`[agent-planning] Recording user message to chat session...`);
+                        const userMessageId = crypto.randomUUID();
+                        const userMessage = {
+                            attachments: promptContextWithUploadedAttachments?.attachments,
+                            content: promptForRecording,
+                            id: userMessageId,
+                            role: "user",
+                            timestamp: Date.now(),
+                            type: "text",
+                        };
+                        if (inputSource?.kind === "editor") {
+                            clark.context.peer.pushMessageToObservers(userMessage, inputSource, { includeInputPeer: true });
+                        }
+                        else {
+                            void clark.context.peer.call
+                                .aiPushMessage(userMessage)
+                                .catch((err) => {
+                                getLogger().warn("[agent-planning] Failed to echo user message to UI", err);
+                            });
+                        }
+                        recordChatMessageInBackground({
+                            clark,
+                            record: () => params.chatSessionStore.recordUser(promptForRecording, {
+                                attachments: promptContextWithUploadedAttachments?.attachments,
+                                messageId: userMessageId,
+                            }),
+                            onRecorded: (chatmessageId) => {
+                                getLogger().info(`[agent-planning] User message recorded: ${chatmessageId}`);
+                            },
+                        });
+                    }
+                }
+                await persistPromptAttachments(clark, request, promptContextWithUploadedAttachments?.attachments, {
+                    applicationId: params.applicationId,
+                    contextManagerV2: params.contextManagerV2,
+                });
+                // Clear stale pending tool permission when the user sends an explicit
+                // new prompt. Internal/system turns (e.g. post-flip migration
+                // translation) and structured interactive responses must not dismiss
+                // an in-flight permission prompt.
+                if (!isInternalTurn && !request.responseMetadata) {
+                    clearPendingToolPermissionRequest(clark, "new-prompt-agent-planning");
+                }
+                if (!request?.jwt) {
+                    getLogger().error(`[agent-planning] Missing or invalid JWT token in AI request (applicationId: ${params.applicationId})`);
+                    void transitionTo({
+                        type: AGENT_NEEDS_USER_INPUT,
+                        advice: "Authentication failed. Please refresh the page and try again. If the problem persists, please contact support.",
+                    });
+                    return;
+                }
+                const initialElementIds = clark.context.initialElementIds ??
+                    Object.keys(params.fileSystemInterface.getElementToFilePathMap() ?? {});
+                const taggedEntities = request.promptContext?.entities;
+                const availableIntegrations = request.promptContext?.integrations;
+                const knowledgePromotionCapabilities = request.promptContext?.knowledgePromotionCapabilities;
+                try {
+                    // Browser-peer RPC on every prompt's critical path; the reconnect
+                    // retry puts its worst case at ~35s, so span it (APPS-4708).
+                    await clark.tracer.trace({ kind: "task", name: "integrations.fetch" }, async (span) => {
+                        const startedAt = performance.now();
+                        const requestedCount = availableIntegrations?.length ?? 0;
+                        try {
+                            await fetchWithReconnectRetry(clark.context.peer, () => params.integrationStore.fetchIntegrations(clark.context.peer, availableIntegrations ?? []), { reconnectBudgetMs: FETCH_INTEGRATIONS_RECONNECT_BUDGET_MS });
+                            clark.tracer.annotate(span, {
+                                metadata: {
+                                    durationMs: Math.round(performance.now() - startedAt),
+                                    requestedCount,
+                                },
+                            });
+                        }
+                        catch (error) {
+                            clark.tracer.annotate(span, {
+                                error,
+                                metadata: {
+                                    durationMs: Math.round(performance.now() - startedAt),
+                                    requestedCount,
+                                },
+                            });
+                            throw error;
+                        }
+                    });
+                }
+                catch (error) {
+                    const isTransient = error instanceof RpcTimeoutError || isPeerUnavailableError(error);
+                    if (isTransient) {
+                        // APPS-4613: Degrade gracefully for transient RPC failures.
+                        // Integration metadata enriches tool context but is not required
+                        // for Clark to produce a useful response.  Prompt-context
+                        // integrations are still available.
+                        getLogger().warn(`[agent-planning] Failed to fetch integrations — proceeding without full integration metadata`, {
+                            ...getErrorMeta(error),
+                            degradedMode: true,
+                            errorType: error instanceof Error
+                                ? error.constructor.name
+                                : typeof error,
+                        });
+                    }
+                    else {
+                        // Unexpected errors (auth failures, code bugs) — cancel so the
+                        // user gets clear feedback instead of a silently degraded response.
+                        getLogger().error(`[agent-planning] Failed to fetch integrations`, getErrorMeta(error));
+                        void transitionTo({
+                            type: AGENT_CANCELED,
+                            advice: "Failed to fetch integrations from the browser. Please refresh the page and try again.",
+                            failure: promptFailurePlatform("integration_fetch"),
+                        });
+                        return;
+                    }
+                }
+                getLogger().info("Agent planning storing llmConfig in context:", request.llmConfig || {});
+                const disabledTools = request.llmConfig?.disabledTools;
+                const customerDataTools = ["queryIntegration"];
+                const allCustomerDataToolsDisabled = customerDataTools.every((tool) => disabledTools?.includes(tool));
+                if (allCustomerDataToolsDisabled) {
+                    getLogger().info(`[agent-planning] Customer data access will be DISABLED (all query tools in disabledTools)`);
+                }
+                else if (disabledTools &&
+                    customerDataTools.some((tool) => disabledTools.includes(tool))) {
+                    const disabled = customerDataTools.filter((tool) => disabledTools.includes(tool));
+                    getLogger().info(`[agent-planning] Partial customer data access: disabled=[${disabled.join(", ")}]`);
+                }
+                else {
+                    getLogger().info(`[agent-planning] Customer data access will be ENABLED`);
+                }
                 clark.updateContext((context) => ({
                     ...context,
                     abortController: context.abortController ?? new AbortController(),
-                    peer,
+                    initialElementIds,
+                    runTimestamp: context.runTimestamp ??
+                        new Date().toISOString().replace(/[:.]/g, "-"),
+                    jwt: request.jwt,
+                    llmConfig: request.llmConfig,
+                    availableIntegrations: availableIntegrations ?? context.availableIntegrations,
+                    knowledgePromotionCapabilities: knowledgePromotionCapabilities ??
+                        context.knowledgePromotionCapabilities,
+                    taggedEntities: taggedEntities ?? context.taggedEntities,
                 }));
-                if (clark.context.hasSuggestions) {
-                    // we're revising a draft
-                    // TODO: also incorporate previous annotations and tagged metadata
-                    const meta = getMeta();
-                    const previousPrompts = meta?.promptsForCurrentDraft ?? [];
-                    const newPrompt = request.prompt;
-                    if (previousPrompts.length > 0) {
-                        const bulletedPreviousPrompts = previousPrompts
-                            .map((prompt) => `- ${prompt}`)
-                            .join("\n");
-                        request.prompt = `You are revising a draft. The user's previous prompt(s):
-
-${bulletedPreviousPrompts}
-
-The user's new prompt is:
-${newPrompt}`;
+                getLogger().info(`[ai-service] Peer set, sending GENERATING state`);
+                void sendUserGenerationState({
+                    state: AiGenerationState.GENERATING,
+                });
+                const generationId = clark.context.promptId ?? generateShortId();
+                params.signals.emit("generationStarted", generationId);
+                // Demo-only: emit the "Preparing development environment" mock card
+                // on the user's first prompt of an empty app, gated by the
+                // `superblocks.byo-db.demo` LaunchDarkly flag. State transitions
+                // (pending → done per task) are driven from the server: we emit
+                // the same message id three times with updated `statuses` and the
+                // UI's awsInfraDemoHandler folds them into a single card. The
+                // awaits below intentionally block agent planning so the demo
+                // finishes before the LLM starts generating.
+                //
+                // Gated by chat history length (rather than a context flag) so it
+                // remains correctly suppressed across reloads — once persisted, the
+                // message stays in the session log and the length check skips
+                // re-emission.
+                if (params.features.byoDbDemo?.enabled &&
+                    !isInternalTurn &&
+                    !request.responseMetadata) {
+                    const priorMessages = await params.chatSessionStore.getMessages();
+                    const isFirstPrompt = !priorMessages.some((m) => m.type === "aws_infra_demo");
+                    if (isFirstPrompt) {
+                        const demoId = generateShortId();
+                        const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+                        const sendDemo = (statuses) => sendUserMessage({
+                            id: demoId,
+                            type: "aws_infra_demo",
+                            role: "assistant",
+                            content: "",
+                            statuses,
+                        });
+                        await sendDemo({ db: "pending", s3: "pending" });
+                        await sleep(2000);
+                        await sendDemo({ db: "done", s3: "pending" });
+                        await sleep(2000);
+                        await sendDemo({ db: "done", s3: "done" });
+                    }
+                }
+                const components = params.appContextStore.componentSemanticsById;
+                const entities = [
+                    ...(request.promptContext?.entities ?? []),
+                ].map((entity) => {
+                    if (entity.type === AiEntityType.COMPONENT) {
+                        return {
+                            ...entity,
+                            metadata: {
+                                name: components[entity.id]?.bindName ??
+                                    components[entity.id]?.tagName,
+                            },
+                        };
                     }
-                    updateMeta({
-                        promptsForCurrentDraft: [...previousPrompts, newPrompt],
+                    return entity;
+                });
+                if (entities.length) {
+                    void sendUserMessage({
+                        type: "context",
+                        role: "assistant",
+                        content: JSON.stringify({ entities }),
+                    });
+                }
+                const isFactsEnabled = clark.context.llmConfig?.flags?.isFactsEnabled ?? false;
+                const knowledgeMessageId = generateShortId();
+                if (isFactsEnabled) {
+                    void sendUserMessage({
+                        id: knowledgeMessageId,
+                        type: "knowledge",
+                        role: "assistant",
+                        content: "",
+                        status: "pending",
+                        facts: {
+                            org: [],
+                            user: [],
+                            integrations: {},
+                        },
                     });
                 }
                 else {
-                    // not revising; just store the initial prompt
-                    updateMeta({
-                        promptsForCurrentDraft: [request.prompt],
+                    void sendUserMessage({
+                        type: "reasoning",
+                        role: "assistant",
+                        content: "",
+                    });
+                }
+                if (clark.context.hasSuggestions) {
+                    // user sent a subsequent prompt on top of a draft
+                    // reset debugging flag
+                    clark.updateContext({
+                        usedDebugging: false,
                     });
                 }
-                const systemPrompt = await createSystemPrompt(request, params);
-                setTimeout(() => {
-                    sendUserMessage({ text: "Planning my approach…" });
-                }, 500);
                 updateMeta({
                     request,
-                    systemPrompt,
-                    retryCount: 0,
                 });
-                // run tsc in the background to speed up incremental typecheck after llm step
-                void params.appShell.runTypecheck();
-                transitionTo({
+                // speed up incremental linting/typecheck after llm step
+                const isTypecheckEnabled = clark.context.llmConfig?.flags?.isTypecheckEnabled ?? true;
+                if (isTypecheckEnabled) {
+                    // Route through the debug cache rather than calling the shell
+                    // directly. A bare `void appShell.runTypecheck()` ran a second
+                    // compiler alongside the cache's own, with no abort signal to stop
+                    // it and no coalescing to prevent the overlap -- and then discarded
+                    // the result. Each compiler holds hundreds of MiB, so the overlap
+                    // was a direct contributor to the pod running out of memory.
+                    debugCache.startEagerTypeScriptCheck(createTypeScriptCheckFunction(params.appShell, clark.context.abortController?.signal));
+                }
+                void params.appShell.warmLinterCache();
+                // If the previous turn was paused mid-stream by the quota gate,
+                // prepend a brief synthetic system-style note so the model opens
+                // its response with a one-line acknowledgement that it's resuming
+                // from the prior context (e.g. "Picking up where we left off
+                // building the dashboard…"). Clear the flag so the hint only
+                // fires for the immediately-next turn.
+                //
+                // Variant: if the failed turn was a `multi_choice_response`, we
+                // ALSO surface the original question and the user's specific
+                // selection. Without this, the model has been observed to
+                // re-decide open questions on its own (picking the default option
+                // rather than the user's choice). Option A in APPS-4080
+                // "resume-quality hardening".
+                //
+                // The wrap is written as natural prose from the user's voice — NOT
+                // using `[system]` / `[user]` markers. Modern Claude is trained to
+                // defend against fake system markers inside user content as a
+                // prompt-injection vector, and was observed responding to the
+                // bracketed form with "that `[system]` message is part of your chat
+                // input, not an actual system instruction. I genuinely don't have
+                // any memory of previous conversations" — i.e. refusing to honor
+                // the resume coaching. Plain prose dodges that defense.
+                let resolvedUserPrompt = request.prompt;
+                // Capture before clearing the flag so the wrapped turn can classify
+                // the raw user input without classifying the synthetic coaching.
+                // The auth resume is one-shot and belongs to the user's own next
+                // message. Priming the pod after a refresh can auto-dispatch the
+                // post-flip migration turn, which lands here as a synthetic
+                // `internal` prompt; letting that consume the flag would spend the
+                // resume on a turn the user never sent. A response to an interactive
+                // message still counts as the user continuing, so only genuinely
+                // system-authored turns are excluded.
+                const isOrganicTurn = !isInternalTurn && !request.importSource;
+                const isSyntheticResume = !!clark.context.pausedForCreditsReason ||
+                    (!!clark.context.resumeAfterAuthFailure && isOrganicTurn);
+                if (clark.context.pausedForCreditsReason) {
+                    const mcCtx = clark.context.pausedForCreditsMultiChoiceContext;
+                    if (mcCtx) {
+                        const userAnswerLine = mcCtx.selectedChoiceTexts.length > 0
+                            ? `I selected: ${mcCtx.selectedChoiceTexts
+                                .map((t) => `"${t}"`)
+                                .join(", ")}.`
+                            : mcCtx.userText
+                                ? `I replied: "${mcCtx.userText}".`
+                                : `My selection was not captured.`;
+                        resolvedUserPrompt =
+                            `(Heads up: my prior turn in this chat got paused mid-task because my team's AI credits ran out. Credits are restored now, so please resume from where you left off.\n\n` +
+                                `Right before the pause, you asked me: "${mcCtx.question}" — ${userAnswerLine} ` +
+                                `Briefly acknowledge that selection and proceed with it as if the pause never happened. Do not re-ask the question, and do not pick a different option.)\n\n` +
+                                `${request.prompt}`;
+                    }
+                    else {
+                        resolvedUserPrompt =
+                            `(Heads up: my prior turn in this chat got paused mid-task because my team's AI credits ran out. Credits are restored now, so please resume from where you left off — briefly acknowledge picking up where the prior run stopped, reference the original task, and proceed as you normally would.)\n\n` +
+                                `${request.prompt}`;
+                    }
+                    clark.updateContext({
+                        pausedForCreditsReason: undefined,
+                        pausedForCreditsMultiChoiceContext: undefined,
+                        // Both can be pending at once, since an internal turn no longer
+                        // consumes the auth flag but can still hit the credits gate. The
+                        // credits wrap already asks the model to pick up where it left
+                        // off, so drop the auth one rather than let it prefix a later,
+                        // unrelated prompt.
+                        resumeAfterAuthFailure: undefined,
+                    });
+                }
+                else if (clark.context.resumeAfterAuthFailure && isOrganicTurn) {
+                    // Short on purpose: unlike the credits case there is no
+                    // multi-choice answer to replay, just the instruction not to start
+                    // over. Same plain-prose framing for the same reason.
+                    resolvedUserPrompt =
+                        `(My previous turn stopped partway because my session expired. It is working again now. Please continue from where you stopped rather than starting over.)\n\n` +
+                            `${request.prompt}`;
+                    clark.updateContext({ resumeAfterAuthFailure: undefined });
+                }
+                void transitionTo({
                     type: AGENT_PLANNED,
-                    systemPrompt,
-                    userPrompt: request.prompt,
+                    userPrompt: resolvedUserPrompt,
+                    promptContext: promptContextWithUploadedAttachments,
+                    // Skip ALL safety features (classifier + secret redaction) when
+                    // this is not an original user prompt: a response to an
+                    // interactive message, a system-initiated internal turn
+                    // (e.g. the post-flip v2→v3 migration translation turn), or a
+                    // third-party import/migration turn. In all these cases the
+                    // message contents are authored or constrained by our code
+                    // (multi-choice option ids, system-generated migration prompt,
+                    // import template text), so there is no user-typed secret to
+                    // redact. Third-party import prompts use
+                    // `withThirdPartyMigrationSkillInstruction` which trips the
+                    // classifier as prompt injection. (APPS-4921)
+                    //
+                    // Resume turns still carry raw user text. They keep both safety
+                    // features on, but classify the raw prompt instead of the wrapper.
+                    isUserPrompt: !request.responseMetadata &&
+                        !isInternalTurn &&
+                        !request.importSource,
+                    safetyClassificationInput: isSyntheticResume
+                        ? request.prompt
+                        : undefined,
+                    knowledgeMessageId,
                 });
                 break;
             }
             case LLM_ERRORED: {
                 const { error } = event;
-                switch (error.type) {
-                    case "overloaded_error":
-                        {
-                            // retry with backoff
-                            const { retryCount = 0, systemPrompt, request } = getMeta() ?? {};
-                            const backoff = Math.min(retryCount * 1000, 10000);
-                            setTimeout(() => {
-                                transitionTo({
-                                    type: AGENT_PLANNED,
-                                    systemPrompt: systemPrompt,
-                                    userPrompt: request.prompt,
-                                });
-                            }, backoff);
-                            updateMeta({
-                                retryCount: retryCount + 1,
-                            });
-                        }
-                        break;
-                    case "invalid_request_error":
-                    case "authentication_error":
-                    case "permission_error":
-                    case "not_found_error":
-                    case "api_error":
-                    case "rate_limit_error":
-                    case "request_too_large":
-                    default:
-                        // TODO: advise user to open a support ticket
-                        break;
+                // Check if this is a paywall error surfaced mid-stream. We try
+                // multiple signals because the error may get rewrapped on the way
+                // from the AI SDK to here, and each wrap can lose some context:
+                //
+                // 1. error.message substring match (carries the specific reason
+                //    token: credit_limit_exceeded, token_limit_exceeded, etc.)
+                // 2. error.type === "ai_quota_exceeded" (mapped from data.type)
+                // 3. error.data.type === "clark_quota_exceeded" (the raw type
+                //    before ERROR_MAPPINGS) — guards against re-wraps that
+                //    overwrite error.type with a generic value
+                // 4. error.cause walked recursively, looking for the same fields
+                //    on any nested cause (the AI SDK sometimes nests its
+                //    APICallError under a RetriesExhaustedError or similar)
+                // Preserve the specific reason from the wire whenever possible.
+                // Earlier versions hardcoded "credit_limit_exceeded" whenever the
+                // structured signals fired, which discarded reasons like
+                // "trial_expired" or "no_seat_assigned" if they ever flowed through
+                // the mid-stream path.
+                const reasonFromData = (err) => {
+                    if (!err || typeof err !== "object")
+                        return undefined;
+                    const e = err;
+                    const data = e.data;
+                    const responseMeta = data?.responseMeta;
+                    const wireReason = responseMeta?.error?.reason;
+                    if (isAiQuotaPaywallReason(wireReason))
+                        return wireReason;
+                    // Raw Clark quota payload often surfaces the reason at top-level
+                    // `data.reason` (e.g. when `error.ts:normalizeProviderErrorData`
+                    // forwards the reason through without re-wrapping inside
+                    // `responseMeta`). `isPaywallError` in `error.ts` already treats
+                    // this shape as a paywall — if we don't extract it here, the
+                    // stream stops retrying via the helper but the FSM ends up
+                    // classifying the failure as a generic cancel with no
+                    // `paywallReason`, so the modal never opens. (APPS-4080)
+                    if (isAiQuotaPaywallReason(data?.reason))
+                        return data.reason;
+                    // `data.type === "clark_quota_exceeded"` means the AI SDK / our
+                    // normalizer already classified this as a quota error but the
+                    // specific reason didn't survive re-wrapping. Last-resort default
+                    // so the user still sees the paywall.
+                    if (data?.type === "clark_quota_exceeded") {
+                        return "credit_limit_exceeded";
+                    }
+                    return undefined;
+                };
+                const walkCause = (err, depth = 0) => {
+                    if (!err || typeof err !== "object" || depth > 5)
+                        return undefined;
+                    const e = err;
+                    return (reasonFromData(err) ??
+                        (typeof e.message === "string"
+                            ? getAiQuotaPaywallReasonFromMessage(e.message)
+                            : undefined) ??
+                        walkCause(e.cause, depth + 1));
+                };
+                const paywallReason = 
+                // Prefer structured data over message text so we keep the specific
+                // reason (`trial_expired`, `no_seat_assigned`, etc.) rather than
+                // collapsing to whatever string the substring matcher hits first.
+                reasonFromData(error) ??
+                    getAiQuotaPaywallReasonFromMessage(error.message) ??
+                    (error.type === "ai_quota_exceeded"
+                        ? "credit_limit_exceeded"
+                        : undefined) ??
+                    walkCause(error.cause);
+                if (paywallReason) {
+                    // Persist that we paused mid-run for credits, so the next user
+                    // prompt gets a synthetic resume hint prepended (see
+                    // USER_SENT_PROMPT). Without this, the model treats "continue"
+                    // as a fresh request and asks clarifying questions instead of
+                    // resuming from prior tool results. (Spec follow-up:
+                    // "Resume-quality hardening" — landed because we observed the
+                    // model fumbling the resume context on EE testing.)
+                    //
+                    // Also promote `lastTurnMultiChoiceContext` (captured at the
+                    // start of the failed USER_SENT_PROMPT) into
+                    // `pausedForCreditsMultiChoiceContext` so the next turn's
+                    // resume hint can re-state the user's specific selection
+                    // verbatim. Clear the captured field so it isn't reused after
+                    // a non-immediately-adjacent paywall. (Option A in APPS-4080.)
+                    const multiChoiceCtx = clark.context.lastTurnMultiChoiceContext;
+                    clark.updateContext({
+                        pausedForCreditsReason: paywallReason,
+                        pausedForCreditsMultiChoiceContext: multiChoiceCtx,
+                        lastTurnMultiChoiceContext: undefined,
+                    });
+                    void transitionTo({
+                        type: AGENT_CANCELED,
+                        advice: paywallStopAdvice(paywallReason),
+                        paywallReason,
+                        failure: promptFailurePaywall(paywallReason),
+                    });
+                    break;
                 }
+                // Clark's own session credential dying mid-stream is recoverable: the
+                // terminal message tells the user to refresh, which mints a fresh
+                // token and re-primes the pod, and their next message picks the run
+                // back up. Record that so USER_SENT_PROMPT can ask the model to carry
+                // on instead of re-planning a task it already half-finished. Gated on
+                // `isClark` so a customer's own provider API key failing — which a
+                // refresh does nothing for — still just stops.
+                if (error.type === "auth_error" && error.data?.isClark === true) {
+                    clark.updateContext({ resumeAfterAuthFailure: true });
+                }
+                const advice = getTerminalErrorMessage(error);
+                void transitionTo({
+                    type: AGENT_CANCELED,
+                    advice,
+                    failure: promptFailureFromLlmError(error),
+                });
                 break;
             }
             case LLM_FINISHED_UNEXPECTEDLY: {
@@ -148,21 +1073,20 @@ ${newPrompt}`;
                 // "tool_use": the model invoked one or more tools
                 switch (finishReason) {
                     case "length":
-                        // TODO: retry with shorter prompt
-                        break;
                     case "content-filter":
                     case "tool-calls":
                     case "error":
                     case "other":
-                    case "unknown":
                     default:
-                        // TODO: advise user to open a support ticket
+                        void transitionTo({
+                            type: AGENT_CANCELED,
+                            advice: `An unexpected error occurred. Please try again.
+
+If the problem persists, please open a support ticket. Finish reason: \`${finishReason}\``,
+                            failure: promptFailureLlmProviderUnknown(),
+                        });
                         break;
                 }
-                void sendUserMessage({
-                    text: `Error: Generation finished with unexpected reason: ${finishReason}`,
-                });
-                await sendUserCompletion({ hasError: true });
                 break;
             }
             case "llmRequestedContext": {
@@ -171,6 +1095,24 @@ ${newPrompt}`;
             }
             case POST_PROCESSING_ERRORED: {
                 const { error } = event;
+                if (error instanceof NpmInstallBlocked) {
+                    // Mirror the agent-tool install path (build-install-packages.ts):
+                    // pick the row-aware advice variant via `buildBlockedMessage` and
+                    // emit the same structured warn so Datadog/Loki can facet on the
+                    // same `messageVariant` regardless of which entry point produced
+                    // the failure (`runNpmInstall` here vs `installSpecificPackages` /
+                    // `runPackageManagerInstall` from the agent tool).
+                    const { message, variant } = buildBlockedMessage(error);
+                    getLogger().warn("Install blocked by registry condition", {
+                        ...error.toJSON(),
+                        messageVariant: variant,
+                    });
+                    await debug(`The following error was encountered while installing dependencies:
+---
+${message}
+---`, ["package.json"]);
+                    break;
+                }
                 if (error instanceof NpmInstallError) {
                     await debug(`The following error was encountered while installing dependencies:
 ---
@@ -185,14 +1127,44 @@ ${error.stack ?? error.message}
                 break;
             }
             case RUNTIME_REVIEW_ERRORED: {
-                const { tsErrorsByPath } = event;
-                const filePaths = Object.keys(tsErrorsByPath);
-                await debug(`The following TypeScript errors were found in the project:
----
+                const { tsErrorsByPath = {}, lintErrorsByPath = {}, integrationErrorsByPath = {}, } = event;
+                const filePaths = new Set(Object.keys(tsErrorsByPath)
+                    .concat(Object.keys(lintErrorsByPath))
+                    .concat(Object.keys(integrationErrorsByPath)));
+                for (const filePath of filePaths) {
+                    void sendChangeInfo({
+                        type: "error",
+                        filePath,
+                    });
+                }
+                let debugPrompt = "";
+                if (Object.keys(tsErrorsByPath).length > 0) {
+                    debugPrompt += `The following TypeScript errors were found in the project:
+----
 ${Object.values(tsErrorsByPath)
-                    .map((errors) => errors.join("\n"))
-                    .join("\n")}
----`, filePaths);
+                        .map((errors) => errors.join("\n"))
+                        .join("\n")}
+----`;
+                }
+                if (Object.keys(lintErrorsByPath).length > 0) {
+                    debugPrompt += `The following linting errors were found in the project:
+----
+${Object.values(lintErrorsByPath)
+                        .map((errors) => errors.join("\n"))
+                        .join("\n")}
+----`;
+                }
+                if (Object.keys(integrationErrorsByPath).length > 0) {
+                    debugPrompt += `The following integration validation errors were found:
+----
+${Object.values(integrationErrorsByPath)
+                        .map((errors) => errors.join("\n"))
+                        .join("\n")}
+----
+
+Please only use the provided integrations and ensure all integration references match exactly.`;
+                }
+                await debug(debugPrompt, Array.from(filePaths));
                 break;
             }
             case BUILD_SYSTEM_ERRORED: {
@@ -208,56 +1180,4 @@ ${error.stack ?? error.message}
         }
     };
 };
-const createSystemPrompt = async (request, params, appFilePatterns = ["**/*.{ts,tsx,yaml}", "package.json"]) => {
-    const { appShell, templateRenderer, artifactProcessor } = params;
-    const appFiles = await params.appShell.readFiles(appFilePatterns);
-    const transformedForPrompt = await applyFileTransformations(appFiles, [
-        new YamlToApiBuilderTransformer({
-            appRootDirPath: appShell.appRootDirPath,
-            entityNames: request?.promptContext?.entityNames ?? [],
-            skipCleanup: true,
-            templateRenderer,
-        }),
-    ]);
-    const artifactContext = artifactProcessor.createArtifactContext(transformedForPrompt);
-    let systemPrompt = getStaticPrompt();
-    systemPrompt = `${systemPrompt}
-
-The current working directory is \`${appShell.appRootDirPath}\`.
-`;
-    const taggedIntegrations = request?.promptContext?.integrations?.map((integration) => sdkIntegrationFromPromptContext(integration));
-    const sdkIntegrationsPromptContent = integrationsToSdkPromptContent(taggedIntegrations ?? []);
-    if (sdkIntegrationsPromptContent.length > 0) {
-        systemPrompt = `${systemPrompt}
-
-Below are the API configurations specific to the request:
----
-${sdkIntegrationsPromptContent.join("\n\n")}
----
-`;
-    }
-    if (artifactContext) {
-        systemPrompt = `${systemPrompt}
-
-Below are the relevant files present in the project:
----
-${artifactContext.paths.join("\n")}
----
-
-Below is the context buffer containing relevant files and code that you should reference when fulfilling the user's request. You may need to modify this code as part of your response.
-CONTEXT BUFFER:
----
-${artifactContext.content}
----
-`;
-    }
-    if (LOG_SYSTEM_PROMPT) {
-        const logger = getLogger();
-        logger.info("[ai-service] " + "=".repeat(80));
-        logger.info("SYSTEM PROMPT:");
-        logger.info(systemPrompt);
-        logger.info("[ai-service] " + "=".repeat(80));
-    }
-    return systemPrompt;
-};
 //# sourceMappingURL=agent-planning.js.map