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

package/dist/ai-service/state-machine/handlers/llm-generating.js

@@ -1,158 +1,1247 @@
-import { streamText, smoothStream } from "ai";
-import { getLogger } from "../../../util/logger.js";
-import { BoltResultBuffer, BoltResultType } from "../../result-buffer/bolt.js";
-import { AGENT_PLANNED, APP_RUNTIME_UPDATED_WITHOUT_EDITS, LLM_ERRORED, LLM_FINISHED, LLM_FINISHED_UNEXPECTEDLY, } from "../clark-fsm.js";
-import { sendUserCompletionChannel, sendUserMessageChannel, } from "../helpers/peer.js";
+import path from "node:path";
+import { AiEntityType, AiMode, resolveAttachmentFileName, } from "@superblocksteam/library-shared/types";
+import { classifyAttachmentDelivery, } from "@superblocksteam/shared";
+import { safeJsonStringify } from "../../../util/log-sanitizer.js";
+import { getErrorMeta, getLogger } from "../../../util/logger.js";
+import { buildBaseSystemPrompt, gitConnectedFromRuntime, } from "../../agent/prompts/build-base-system-prompt.js";
+import { buildTools } from "../../agent/tools.js";
+import { processStreamChunk } from "../../agent/utils.js";
+import { AppSkillsManager } from "../../app-skills/manager.js";
+import { parseDataUrl } from "../../attachments/parse-data-url.js";
+import { TextUploadArtifactMaterializer, getUploadedAttachmentArtifactKey, isUploadedTextAttachment, normalizeMimeTypes, } from "../../attachments/text-upload-artifacts.js";
+import { escapeAttachmentReferenceValue, getCanonicalAttachmentUrl, isUploadedAttachment, toInlineAttachmentReferenceTextPart, toUploadedAttachmentContentPart, toUploadedAttachmentReferenceTextPart, } from "../../attachments/uploaded-content-part.js";
+import { normalizeTextAttachmentForModel } from "../../chat/utils.js";
+import { isV2ToV3MigrationInProgress, readPersistedChecklist, } from "../../checklist/persisted-checklist-store.js";
+import { recordKnowledgeTurnLoadMetrics } from "../../knowledge/knowledge-metrics-emitters.js";
+import { getActiveContext } from "../../llm/context-v2/utils/index.js";
+import { isNoOutputError, LLMProviderError } from "../../llm/error.js";
+import { wrapError } from "../../llm/stream/errors.js";
+import { GRAPHQL_SKILL_INTEGRATION_TYPES, REST_SKILL_INTEGRATION_TYPES, SQL_SKILL_INTEGRATION_TYPES, SYSTEM_SKILL_REFERENCES, } from "../../skills/types.js";
+import { buildModeMessage } from "../../util/mode-message.js";
+import { parseJwt } from "../../util/parse-jwt.js";
+import { getScopedToken } from "../../util/scoped-token-utils.js";
+import { hasToolSuccess, isAwaitingUser, needsPermissionToExecute, } from "../../util/stop-condition.js";
+import { AGENT_CANCELED, AGENT_NEEDS_USER_INPUT, AGENT_PLANNED, LLM_ERRORED, USER_CANCELED, V3_AGENT_FINISHED, } from "../clark-fsm.js";
+import { getContextId } from "../helpers/context-id.js";
+import { sendInteractiveMessageChannel, sendUserMessageChannel, } from "../helpers/peer.js";
+import { startPreSessionWatch } from "../helpers/pre-session-metrics.js";
+import { promptFailureFromLlmError, promptFailureFromStreamAbort, promptFailurePlatform, resolvePromptOutcomeDedupeKey, } from "../helpers/prompt-request-metrics.js";
+import { catchBackgroundPeerDisconnect } from "../helpers/stable-peer.js";
 import { transitionFrom } from "../helpers/transition.js";
-export const doLLMGenerating = (clark, { anthropicProvider, artifactProcessor }) => {
+import { flushPendingChatPushesBeforeTransition } from "./flush-pending-chat-pushes.js";
+export async function refreshHasSuggestionsFromLocalDraft(clark, services, isStaleRun, logContext = {}) {
+    clark.logger.info("[llm-generating] Checking local draft changes", {
+        currentHasSuggestions: clark.context.hasSuggestions,
+    });
+    let hasLocalDraft;
+    try {
+        hasLocalDraft = await services.draftInterface.hasLocalDraftChanges();
+    }
+    catch (error) {
+        if (isStaleRun()) {
+            clark.logger.info("[llm-generating] Ignoring local-draft error from stale run", {
+                runPromptId: logContext.runPromptId,
+                currentPromptId: clark.context.promptId,
+            });
+            return { status: "stale" };
+        }
+        clark.logger.error("[llm-generating] Failed to refresh local draft state", {
+            ...getErrorMeta(error),
+            reason: `runPromptId=${logContext.runPromptId ?? "unknown"} currentPromptId=${clark.context.promptId}`,
+        });
+        return {
+            status: "error",
+            hasLocalDraft: Boolean(clark.context.hasSuggestions),
+            error,
+        };
+    }
+    if (isStaleRun()) {
+        clark.logger.info("[llm-generating] Ignoring local-draft result from stale run", {
+            runPromptId: logContext.runPromptId,
+            currentPromptId: clark.context.promptId,
+        });
+        return { status: "stale" };
+    }
+    clark.logger.info("[llm-generating] hasLocalDraft check completed", {
+        hasLocalDraft,
+        currentHasSuggestions: clark.context.hasSuggestions,
+    });
+    clark.updateContext({ hasSuggestions: hasLocalDraft });
+    return { status: "ok", hasLocalDraft };
+}
+/**
+ * Get the skill reference files that should be read based on the tagged integrations.
+ * Returns an array of skill file paths.
+ */
+function getRequiredSkillReferences(integrations) {
+    const refs = new Set();
+    for (const integration of integrations) {
+        const pluginType = integration.type?.toLowerCase() ?? "";
+        if (SQL_SKILL_INTEGRATION_TYPES.has(pluginType)) {
+            refs.add(SYSTEM_SKILL_REFERENCES.SQL_DATABASES);
+        }
+        if (REST_SKILL_INTEGRATION_TYPES.has(pluginType)) {
+            refs.add(SYSTEM_SKILL_REFERENCES.REST_APIS);
+        }
+        if (GRAPHQL_SKILL_INTEGRATION_TYPES.has(pluginType)) {
+            refs.add(SYSTEM_SKILL_REFERENCES.GRAPHQL);
+        }
+    }
+    // If any integration-specific reference is needed, also require the main API skill
+    if (refs.size > 0) {
+        refs.add(SYSTEM_SKILL_REFERENCES.API_MAIN);
+    }
+    return Array.from(refs);
+}
+const toBase64Data = (value) => Buffer.from(value, "utf8").toString("base64");
+const getToolResultOutputObject = (output) => {
+    if (!output || typeof output !== "object") {
+        return null;
+    }
+    if ("value" in output && output.value && typeof output.value === "object") {
+        return output.value;
+    }
+    return output;
+};
+/**
+ * Maps attachments to LLM content parts.
+ * Uploaded inline-native attachments include both the model-visible content
+ * part and a reference block so Clark can materialize bytes when needed.
+ */
+export const mapAttachmentsToContentParts = (attachments, options) => {
+    const textUploadContextByReferenceMimeTypes = normalizeMimeTypes(options.textUploadContextByReferenceMimeTypes ?? []);
+    return attachments.flatMap((attachment) => {
+        if (attachment.type === "image") {
+            const parsed = parseDataUrl(attachment.image);
+            const mediaType = parsed?.mediaType ?? "image/*";
+            const fileName = resolveAttachmentFileName({
+                fileName: attachment.fileName,
+                mediaType,
+                type: attachment.type,
+            });
+            return [
+                {
+                    type: attachment.type,
+                    image: attachment.image,
+                },
+                toInlineAttachmentReferenceTextPart({ fileName, mediaType }),
+            ];
+        }
+        else if (attachment.type === "archive") {
+            // Archives are reference-only: upstream providers reject
+            // application/zip, application/gzip, etc. as inline FileParts.
+            // The normal flow force-uploads archives in
+            // `maybeUploadPromptContextAttachments` so they arrive here as
+            // `type: "uploaded"`; this branch is a defensive fallback for the
+            // narrow case where that upload was skipped (e.g. missing jwt or
+            // applicationId) so the generation degrades to a reference rather
+            // than blowing up the whole LLM request.
+            const parsed = parseDataUrl(attachment.data);
+            const mediaType = parsed?.mediaType ?? "application/octet-stream";
+            const fileName = resolveAttachmentFileName({
+                fileName: attachment.fileName,
+                mediaType,
+                type: attachment.type,
+            });
+            return [
+                {
+                    type: "text",
+                    text: `<attachment_reference>
+fileName: ${escapeAttachmentReferenceValue(fileName)}
+mediaType: ${escapeAttachmentReferenceValue(mediaType)}
+note: This archive was not uploaded to persistent storage, so it cannot be materialized from server-backed storage. Ask the user to retry; do not attempt to infer its contents.
+</attachment_reference>`,
+                },
+            ];
+        }
+        else if (attachment.type === "pdf") {
+            const parsed = parseDataUrl(attachment.data);
+            const mediaType = parsed?.mediaType ?? "application/pdf";
+            const fileName = resolveAttachmentFileName({
+                fileName: attachment.fileName,
+                mediaType,
+                type: attachment.type,
+            });
+            return [
+                {
+                    type: "file",
+                    data: parsed?.data ?? attachment.data,
+                    mediaType,
+                    filename: fileName,
+                },
+                toInlineAttachmentReferenceTextPart({ fileName, mediaType }),
+            ];
+        }
+        else if (isUploadedAttachment(attachment)) {
+            const textArtifact = options.textUploadArtifacts?.get(getUploadedAttachmentArtifactKey(attachment));
+            if (textArtifact && options.attachmentDownloadEnabled) {
+                return [
+                    {
+                        type: "text",
+                        text: `<attachment_reference>
+fileName: ${escapeAttachmentReferenceValue(textArtifact.fileName)}
+mediaType: ${escapeAttachmentReferenceValue(textArtifact.mediaType)}
+workspacePath: ${escapeAttachmentReferenceValue(textArtifact.workspacePath)}
+sizeBytes: ${textArtifact.sizeBytes}
+lineCount: ${textArtifact.lineCount} (all non-empty lines, including headers in CSV files)
+note: This text file is cached in the workspace and is not delivered inline to the model. Inspect it with normal file tools such as build_readFile or grep when you need its contents.
+</attachment_reference>`,
+                    },
+                ];
+            }
+            if (textUploadContextByReferenceMimeTypes.length > 0 &&
+                isUploadedTextAttachment(attachment, textUploadContextByReferenceMimeTypes)) {
+                const fileName = resolveAttachmentFileName(attachment);
+                return [
+                    {
+                        type: "text",
+                        text: `<attachment_reference>
+fileName: ${escapeAttachmentReferenceValue(fileName)}
+mediaType: ${escapeAttachmentReferenceValue(attachment.mediaType)}
+url: ${escapeAttachmentReferenceValue(getCanonicalAttachmentUrl(attachment.url))}
+storageKey: ${escapeAttachmentReferenceValue(attachment.storageKey ?? "unknown")}
+note: ${escapeAttachmentReferenceValue(getTextUploadFallbackNote(options.attachmentDownloadEnabled))}
+</attachment_reference>`,
+                    },
+                ];
+            }
+            const delivery = classifyAttachmentDelivery({
+                fileName: attachment.fileName,
+                mimeType: attachment.mediaType,
+            });
+            const referencePart = toUploadedAttachmentReferenceTextPart(attachment, {
+                downloadEnabled: options.attachmentDownloadEnabled,
+            });
+            if (delivery === "reference_only") {
+                return [referencePart];
+            }
+            return [toUploadedAttachmentContentPart(attachment), referencePart];
+        }
+        const normalizedTextAttachment = normalizeTextAttachmentForModel(attachment);
+        if (normalizedTextAttachment) {
+            const filePart = {
+                type: "file",
+                data: toBase64Data(normalizedTextAttachment.content),
+                filename: normalizedTextAttachment.fileName,
+                mediaType: "text/plain",
+            };
+            return [
+                filePart,
+                toInlineAttachmentReferenceTextPart({
+                    fileName: normalizedTextAttachment.fileName,
+                    mediaType: "text/plain",
+                }),
+            ];
+        }
+        throw new Error("Unsupported attachment type");
+    });
+};
+function getTextUploadFallbackNote(attachmentDownloadEnabled) {
+    if (!attachmentDownloadEnabled) {
+        return "This text file is not delivered inline to the model. The workspace artifact was unavailable. Attachment downloads are disabled in this workspace; treat this as a pointer only and do not attempt to fetch it.";
+    }
+    return "This text file is not delivered inline to the model. The workspace artifact was unavailable; call downloadAttachments with this storageKey to materialize the bytes on disk before inspecting or copying it.";
+}
+export const materializeTextUploadArtifacts = async ({ clark, services, promptContext, planContext, }) => {
+    const rawTextUploadMimeTypes = clark.context.llmConfig?.flags?.textUploadContextByReferenceMimeTypes;
+    if (rawTextUploadMimeTypes != null &&
+        !Array.isArray(rawTextUploadMimeTypes)) {
+        services.logger.warn("[llm-generating] textUploadContextByReferenceMimeTypes is not an array; text upload by-reference disabled", { rawValue: rawTextUploadMimeTypes });
+    }
+    const textUploadContextByReferenceMimeTypes = Array.isArray(rawTextUploadMimeTypes)
+        ? normalizeMimeTypes(rawTextUploadMimeTypes)
+        : [];
+    if (textUploadContextByReferenceMimeTypes.length === 0) {
+        return undefined;
+    }
+    if (services.features?.clarkAttachmentDownloadEnabled !== true) {
+        return undefined;
+    }
+    const attachments = [
+        ...(promptContext?.attachments ?? []),
+        ...(planContext?.approved === true ? (planContext.attachments ?? []) : []),
+    ];
+    if (attachments.length === 0) {
+        return undefined;
+    }
+    try {
+        const materializer = new TextUploadArtifactMaterializer({
+            appRootDirPath: services.appShell.appRootDirPath,
+            materializedMimeTypes: textUploadContextByReferenceMimeTypes,
+            resolveSignedUrls: async (textAttachments) => {
+                const appScopeAttachments = textAttachments.filter((attachment) => attachment.scopeType !== "org");
+                let scopedToken = "";
+                if (appScopeAttachments.length > 0) {
+                    if (!clark.context.jwt) {
+                        throw new Error("Cannot resolve app-scoped text uploads without a user JWT");
+                    }
+                    scopedToken = await getScopedToken({
+                        applicationId: services.applicationId,
+                        jwt: clark.context.jwt,
+                        superblocksBaseUrl: services.superblocksBaseUrl,
+                    });
+                }
+                const urlByKey = new Map();
+                const leaseReferences = textAttachments.map((attachment) => {
+                    const scopeType = attachment.scopeType === "org" ? "org" : "app";
+                    const url = getCanonicalAttachmentUrl(attachment.url);
+                    urlByKey.set(getUploadedAttachmentArtifactKey(attachment), url);
+                    return {
+                        applicationId: scopeType === "app"
+                            ? (attachment.applicationId ?? services.applicationId)
+                            : undefined,
+                        fileName: resolveAttachmentFileName(attachment),
+                        mediaType: attachment.mediaType,
+                        scopeType,
+                        storageKey: attachment.storageKey,
+                        url,
+                    };
+                });
+                const leaseResponse = await services.rpcClient.call(async (client) => {
+                    return await client.call.v1.ai.resolveAttachmentLeases({
+                        attachments: leaseReferences,
+                        scopedToken,
+                        superblocksBaseUrl: services.superblocksBaseUrl,
+                    });
+                });
+                const signedUrlByUrl = new Map();
+                for (const attachment of leaseResponse?.data?.attachments ?? []) {
+                    if (typeof attachment?.url !== "string" ||
+                        typeof attachment?.signedUrl !== "string") {
+                        continue;
+                    }
+                    signedUrlByUrl.set(getCanonicalAttachmentUrl(attachment.url), attachment.signedUrl);
+                }
+                const signedUrls = new Map();
+                for (const [key, url] of urlByKey) {
+                    const signedUrl = signedUrlByUrl.get(url);
+                    if (signedUrl) {
+                        signedUrls.set(key, signedUrl);
+                    }
+                }
+                return signedUrls;
+            },
+            logger: services.logger,
+        });
+        const artifacts = await materializer.materialize(attachments);
+        if (artifacts.size > 0) {
+            services.logger.info("[llm-generating] Text upload artifacts materialized", {
+                applicationId: services.applicationId,
+                artifactCount: artifacts.size,
+            });
+        }
+        return artifacts.size > 0 ? artifacts : undefined;
+    }
+    catch (error) {
+        services.logger.warn("[llm-generating] Failed to materialize text upload artifacts; falling back to text reference-only handling", getErrorMeta(error));
+        return undefined;
+    }
+};
+const escapeTagDelimiters = (json) => json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+export function buildEnvironmentCompatibilityContext(compatibility) {
+    if (!compatibility) {
+        return "";
+    }
+    const projection = {
+        appDataTags: compatibility.appDataTags.map((tag) => ({
+            availableModes: tag.availableModes,
+            profileId: tag.profileId,
+            profileKey: tag.profileKey,
+        })),
+        organizationDataTags: compatibility.organizationDataTags.map((tag) => ({
+            displayName: tag.displayName,
+            profileId: tag.profileId,
+            profileKey: tag.profileKey,
+        })),
+        appDatabase: {
+            overallState: compatibility.appDatabase.overallState,
+            needsAttention: compatibility.appDatabase.needsAttention,
+            tags: compatibility.appDatabase.tags.map((tag) => ({
+                profileKey: tag.profileKey,
+                availableModes: tag.availableModes,
+                supportState: tag.supportState,
+                requiredOperations: tag.requiredOperations,
+                missingOperations: tag.missingOperations,
+            })),
+        },
+        integrations: compatibility.integrations.map((integration) => ({
+            integrationId: integration.integrationId,
+            integrationName: integration.integrationName,
+            pluginId: integration.pluginId,
+            supportedProfileKeys: integration.supportedProfileKeys,
+            mismatchedAppProfileKeys: integration.mismatchedAppProfileKeys,
+            tags: integration.tags.map((tag) => ({
+                profileId: tag.profileId,
+                profileKey: tag.profileKey,
+                availableModes: tag.availableModes,
+                state: tag.state,
+                remediationActions: tag.remediationActions,
+            })),
+        })),
+        integrationReadState: compatibility.integrationReadState,
+        canManageEnvironments: compatibility.canManageEnvironments,
+        overallState: compatibility.overallState,
+        isBlocking: compatibility.isBlocking,
+        needsAttention: compatibility.needsAttention,
+        remediationActions: compatibility.remediationActions,
+    };
+    return `<environment_compatibility>\n${escapeTagDelimiters(safeJsonStringify(projection, 2))}\n</environment_compatibility>\n\n`;
+}
+const buildUserMessage = ({ preferredAppInferenceIntegration, userPrompt, promptContext, planContext, mode, services, userChanges, userFactsSection, pendingKnowledgeFreeTextTurn, pendingKnowledgeEntries, skillsNeedReload, useSystemSkills, textUploadArtifacts, textUploadContextByReferenceMimeTypes, }) => {
+    const content = [];
+    // If context was recently summarized, remind Clark to re-read skills
+    if (skillsNeedReload && useSystemSkills) {
+        const sdkApiEnabled = services.features?.sdkApiEnabled ?? false;
+        const apiSkillReminder = sdkApiEnabled
+            ? ""
+            : "\n- For API work: `skills/system/superblocks-api/SKILL.md` and the appropriate reference file for your integration type";
+        content.push({
+            type: "text",
+            text: `<skill_reload_reminder>
+**IMPORTANT:** The conversation context was recently summarized. Any skill files you previously read may no longer be in context.
+
+If you are working on tasks that require skill guidance, you MUST re-read the relevant skill files using \`build_readFile\` before continuing:${apiSkillReminder}
+- For frontend work: \`skills/system/superblocks-frontend/SKILL.md\`
+
+Do not rely on prior knowledge from skills that may have been summarized away.
+</skill_reload_reminder>\n\n`,
+        });
+    }
+    // Get entities from promptContext, but also include planContext entities for approved plans
+    const promptEntities = promptContext?.entities ?? [];
+    const planEntities = planContext?.entities ?? [];
+    const planApproved = planContext?.approved === true;
+    // Merge entities: use promptContext entities, but if plan is approved include plan entities too
+    const focusedEntities = planApproved && planEntities.length > 0
+        ? [
+            ...promptEntities,
+            ...planEntities.filter((pe) => !promptEntities.some((e) => e.id === pe.id)),
+        ]
+        : promptEntities.length > 0
+            ? promptEntities
+            : undefined;
+    const focusedEntitiesWithSemanticInfo = focusedEntities?.map((entity) => {
+        if (entity.type === AiEntityType.COMPONENT) {
+            // add semantic information to components so clark can use it to understand which
+            // element is targeted
+            const component = services.appContextStore.getComponent(entity.id) ?? {};
+            return {
+                ...entity,
+                ...component,
+            };
+        }
+        return entity;
+    });
+    const selectedIntegrations = promptContext?.integrations;
+    const planSummary = planContext?.plan;
+    // Add user changes if present
+    if (userChanges && userChanges.length > 0) {
+        const appRootDirPath = services.appShell.appRootDirPath;
+        const changeDescriptions = userChanges.map((change) => {
+            switch (change.type) {
+                case "addPage":
+                    return `- Created a new page at ${path.relative(appRootDirPath, change.path)}`;
+                case "deletePage":
+                    return `- Deleted page at ${path.relative(appRootDirPath, change.path)}`;
+                case "apiUpdate":
+                    return `- Modified API "${change.apiName}"`;
+                case "apiDelete":
+                    return `- Deleted API "${change.apiName}"`;
+                case "fileChanged":
+                    return `- Edited code in ${path.relative(appRootDirPath, change.filePath)}`;
+            }
+        });
+        content.push({
+            type: "text",
+            text: `<recent_user_changes>\nSince your last interaction, the user has made the following changes:\n${changeDescriptions.join("\n")}\n\nThe current state of the application reflects all of these changes.\n</recent_user_changes>\n\n`,
+        });
+    }
+    // Add integration setup state
+    if (promptContext?.integrationSetup) {
+        const { pluginId, mode, integrationName } = promptContext.integrationSetup;
+        const nameLabel = integrationName ? ` ("${integrationName}")` : "";
+        content.push({
+            type: "text",
+            text: `<integration_setup_state>\nThe integration setup form is already open for ${pluginId}${nameLabel} in ${mode} mode. Do not call openIntegrationSetup or openExistingIntegration — the user can already see the form.\n</integration_setup_state>\n\n`,
+        });
+    }
+    if (promptContext?.gitSetup) {
+        const { isConnected, remoteUrl } = promptContext.gitSetup;
+        const urlLabel = remoteUrl ? ` (${remoteUrl})` : "";
+        content.push({
+            type: "text",
+            text: `<git_setup_state>\nThe git settings tab is open. The repository is ${isConnected ? `connected${urlLabel}` : "not yet connected"}.\nYou can only provide read-only guidance — answer the user's questions about connecting to git, required token permissions, provider setup, CI/CD pipeline files, and branch workflows. Do NOT attempt to fill form fields, run git commands, or modify the configuration directly.\n</git_setup_state>\n\n`,
+        });
+    }
+    if (promptContext?.currentView) {
+        const viewDescriptions = {
+            "code-viewer": "the Code view. The Code view is a read-only file viewer — the user cannot edit files directly in this view. Do not suggest editing files through the Code view UI. To make code changes, use your own tools instead.",
+            "git-setup": "the Git Setup view, where the user connects their application to a git repository. You provide read-only guidance — do not attempt to modify the form.",
+            "integration-setup": "the Integration Setup view, where the user configures an integration (e.g. database credentials, API keys, or connection settings).",
+            publish: "the Publish view, where the user reviews policy gate scan results, database provisioning progress, and remediation guidance during publish.",
+            preview: "the Preview, where the user sees a live preview of their application as it would appear in a browser.",
+        };
+        const desc = viewDescriptions[promptContext.currentView];
+        content.push({
+            type: "text",
+            text: `<current_view>\nThe user is currently in ${desc}\n</current_view>\n\n`,
+        });
+    }
+    // Add preview device context (only relevant in Preview)
+    if (promptContext &&
+        (!promptContext.currentView || promptContext.currentView === "preview")) {
+        content.push({
+            type: "text",
+            text: `<preview_device>\nThe user is currently viewing the app in ${promptContext.previewDevice === "mobile" ? "mobile preview mode (viewport width: 375px)" : "desktop preview mode (full width)"}.\n</preview_device>\n\n`,
+        });
+    }
+    // Add current page context
+    if (promptContext?.currentPageName) {
+        content.push({
+            type: "text",
+            text: `<current_page>\nThe user is currently viewing the page named "${promptContext.currentPageName}".\n</current_page>\n\n`,
+        });
+    }
+    // Add current route context
+    if (promptContext) {
+        const routeLines = [];
+        if (promptContext.currentPathname) {
+            routeLines.push(`pathname: "${promptContext.currentPathname}"`);
+        }
+        if (promptContext.currentRoutePattern) {
+            routeLines.push(`routePattern: "${promptContext.currentRoutePattern}"`);
+        }
+        if (promptContext.currentRouteParams &&
+            Object.keys(promptContext.currentRouteParams).length > 0) {
+            routeLines.push(`routeParams: ${safeJsonStringify(promptContext.currentRouteParams)}`);
+        }
+        if (routeLines.length > 0) {
+            content.push({
+                type: "text",
+                text: `<current_route>\n${routeLines.join("\n")}\n</current_route>\n\n`,
+            });
+        }
+    }
+    // Add current API context
+    if (promptContext?.currentApiName) {
+        content.push({
+            type: "text",
+            text: `<current_api>\nThe user is currently viewing the API named "${promptContext.currentApiName}" in the bottom panel.\n</current_api>\n\n`,
+        });
+    }
+    const environmentCompatibilityContext = buildEnvironmentCompatibilityContext(promptContext?.environmentCompatibility);
+    if (environmentCompatibilityContext) {
+        content.push({
+            type: "text",
+            text: environmentCompatibilityContext,
+        });
+    }
+    // Add available data tags context
+    if (promptContext?.dataTags) {
+        const { available, selected, default: defaultDataTag, } = promptContext.dataTags;
+        const dataTagLines = [];
+        dataTagLines.push(`Available data tags (${available.length}):`);
+        available.forEach((dataTag) => {
+            const isSelected = selected?.id === dataTag.id;
+            const isDefault = defaultDataTag.id === dataTag.id;
+            let line = `- ${dataTag.displayName} (key: "${dataTag.key}")`;
+            if (isSelected)
+                line += " [CURRENTLY SELECTED]";
+            if (isDefault)
+                line += " [DEFAULT]";
+            if (dataTag.description)
+                line += ` - ${dataTag.description}`;
+            dataTagLines.push(line);
+        });
+        content.push({
+            type: "text",
+            text: `<available_data_tags>\n${dataTagLines.join("\n")}\n</available_data_tags>\n\n`,
+        });
+    }
+    // Add current user context
+    if (promptContext?.user) {
+        const user = promptContext.user;
+        content.push({
+            type: "text",
+            text: `<current_user>\nName: ${user.name}\nEmail: ${user.email}\nUsername: ${user.username}\n</current_user>\n\n`,
+        });
+    }
+    // Add organization groups context
+    if (promptContext?.groups && promptContext.groups.length > 0) {
+        const allGroups = promptContext.groups
+            .map((g) => `- ${g.name} (${g.size} members)`)
+            .join("\n");
+        content.push({
+            type: "text",
+            text: `<organization_groups>\nAll groups in the organization (${promptContext.groups.length}):\n${allGroups}\n</organization_groups>\n\n`,
+        });
+    }
+    if (promptContext?.conflictedFiles?.length) {
+        const fileList = promptContext.conflictedFiles
+            .map((f) => `- ${f}`)
+            .join("\n");
+        content.push({
+            type: "text",
+            text: `<conflicted_files>\nThe following files have unresolved git merge conflicts:\n${fileList}\nRead each file, resolve the conflict markers, and stage them.\nAfter resolving all conflicts, run \`build_debug\` to verify the app still builds and runs. Only run \`build_captureScreenshot\` if the merge changed the UI and you need to confirm it looks right. If any issues are found, fix them before finishing.\n</conflicted_files>\n\n`,
+        });
+    }
+    // Add focused entities if present
+    if (focusedEntities?.length) {
+        content.push({
+            type: "text",
+            text: `<focused_entities>\nThe user has focused the editor on the following entities corresponding to the current app state. Attempt to constrain your actions to affect only these entities.\n${safeJsonStringify(focusedEntitiesWithSemanticInfo)}\n\n`,
+        });
+    }
+    // Add selected integrations if present.
+    //
+    // Integration `displayName` / `name` are user-controlled (org admins set them), so
+    // anything we interpolate into a tag-delimited prompt block must be escaped or a
+    // crafted name (e.g. `</selected_integrations>...`) could close the block and inject
+    // attacker-controlled instructions into the system prompt. We do that by escaping
+    // `<` and `>` in the JSON payload before interpolation.
+    if (selectedIntegrations?.length) {
+        // Omit metadata to reduce token usage - only include essential identifying information
+        // Send displayName as "name" so message shows original name
+        const integrationsWithoutMetadata = selectedIntegrations.map(({ id, name, displayName, mismatchedAppProfileKeys, supportedProfileKeys, type, }) => ({
+            id,
+            mismatchedAppProfileKeys: mismatchedAppProfileKeys ?? [],
+            name: displayName || name,
+            supportedProfileKeys: supportedProfileKeys ?? [],
+            tagName: name,
+            type,
+        }));
+        content.push({
+            type: "text",
+            text: `<selected_integrations>\nThe user has explicitly selected the following integration configurations to use. You MUST use these specific integrations when creating or modifying APIs.\n${escapeTagDelimiters(safeJsonStringify(integrationsWithoutMetadata))}\n</selected_integrations>\n\n`,
+        });
+        // Add required skill reads based on integration types (YAML APIs only)
+        const requiredSkillRefs = getRequiredSkillReferences(selectedIntegrations);
+        const sdkApiEnabledForSkills = services.features?.sdkApiEnabled ?? false;
+        if (requiredSkillRefs.length > 0 &&
+            useSystemSkills &&
+            !sdkApiEnabledForSkills) {
+            content.push({
+                type: "text",
+                text: `<required_skill_reads>\n**MANDATORY:** Before creating or modifying APIs with the tagged integrations, you MUST read the following skill files using \`build_readFile\`:\n${requiredSkillRefs.map((f) => `- ${f}`).join("\n")}\n\nDo NOT proceed with API work until you have read these files. They contain integration-specific patterns and syntax that differ from general knowledge.\n</required_skill_reads>\n\n`,
+            });
+        }
+    }
+    if (preferredAppInferenceIntegration) {
+        const defaultPayload = {
+            id: preferredAppInferenceIntegration.id,
+            name: preferredAppInferenceIntegration.displayName ||
+                preferredAppInferenceIntegration.name,
+            tagName: preferredAppInferenceIntegration.name,
+            type: preferredAppInferenceIntegration.type,
+        };
+        content.push({
+            type: "text",
+            text: `<default_ai_integration>\nThe organization has configured the following integration as the default for AI inference in customer-built apps:\n${escapeTagDelimiters(safeJsonStringify(defaultPayload))}\nWhen the user asks for AI-powered functionality (chatbots, summarization, classification, content generation, semantic search, etc.), DIRECTLY use this integration for AI inference. Do NOT use askMultiChoice or searchIntegrations to ask which AI provider to use — this integration is already the organization's chosen default. Include its ID in integrationIds when calling exitPlanMode for plans that involve AI-powered features. Only pick a different AI integration if the user explicitly names another provider.\n</default_ai_integration>\n\n`,
+        });
+    }
+    // Add integration-specific knowledge facts
+    if (userFactsSection) {
+        content.push({
+            type: "text",
+            text: `${userFactsSection}\n\n`,
+        });
+    }
+    if (pendingKnowledgeFreeTextTurn &&
+        pendingKnowledgeEntries &&
+        pendingKnowledgeEntries.length > 0) {
+        const candidateSummary = pendingKnowledgeEntries
+            .map((entry, idx) => `${idx + 1}. ${entry.name}${entry.description ? ` — ${entry.description}` : ""}`)
+            .join("\n");
+        content.push({
+            type: "text",
+            text: `<pending_knowledge_approval_context>
+The user is replying in free text while there is a pending app knowledge approval draft.
+
+Prioritize resolving this pending knowledge approval interaction:
+- Interpret the user's message as feedback on the pending knowledge candidates first.
+- Refine or consolidate candidates as needed, then call \`rememberKnowledge\` with updated candidate(s).
+- Ask one focused clarifying question only if the feedback is genuinely ambiguous.
+- Do not pivot into unrelated implementation work until this pending knowledge interaction is resolved.
+
+Pending candidates:
+${candidateSummary}
+</pending_knowledge_approval_context>\n\n`,
+        });
+    }
+    if (promptContext?.attachments?.length) {
+        // Log attachments with their label/insight metadata for debugging
+        getLogger().info("[llm-generating] Received attachments:", promptContext.attachments.map((a) => ({
+            type: a.type,
+            fileName: a.fileName,
+            label: a.label,
+            insight: a.insight,
+            imageLength: a.type === "image" ? a.image?.length : undefined,
+        })));
+        content.push(...mapAttachmentsToContentParts(promptContext.attachments, {
+            attachmentDownloadEnabled: services.features?.clarkAttachmentDownloadEnabled === true,
+            textUploadArtifacts,
+            textUploadContextByReferenceMimeTypes,
+        }));
+    }
+    if (mode !== undefined) {
+        content.push({
+            type: "text",
+            text: `${buildModeMessage(mode, planApproved)}\n\n`,
+        });
+    }
+    // Only include <approved_plan> when the plan is actually approved.
+    if (planApproved && planSummary) {
+        content.push({
+            type: "text",
+            text: `<approved_plan>Reference this previously approved plan when executing. Do not deviate without user confirmation.\n${planSummary}\n</approved_plan>\n\n`,
+        });
+    }
+    else if (mode === AiMode.PLAN && planSummary) {
+        // Keep refining the plan until it is approved.
+        content.push({
+            type: "text",
+            text: `<proposed_plan>This is the current proposed plan. It is NOT approved yet. Revise it as needed based on the user's feedback, and present an updated plan via exitPlanMode.\n${planSummary}\n</proposed_plan>\n\n`,
+        });
+    }
+    // Add testing instructions if enableTesting is set on the plan context
+    const shouldTest = planContext?.enableTesting === true;
+    if (shouldTest && mode === AiMode.BUILD) {
+        content.push({
+            type: "text",
+            text: `<testing_required>
+IMPORTANT: Testing is enabled for this plan. After building the features, you MUST call the \`startTestRun\` tool to invoke the Testing Agent.
+The Testing Agent will verify your implementation works correctly before you can finalize.
+Do NOT call \`build_finalize\` until testing is complete.
+</testing_required>\n\n`,
+        });
+    }
+    // Include attachments from approved plan for execution.
+    // Duplicate filenames are handled downstream by uniquifyFilePartFilenames()
+    // in getMessages(), which appends stable suffixes (_2, _3, …) to collisions
+    // rather than dropping any attachments.
+    if (planApproved && planContext?.attachments?.length) {
+        content.push(...mapAttachmentsToContentParts(planContext.attachments, {
+            attachmentDownloadEnabled: services.features?.clarkAttachmentDownloadEnabled === true,
+            textUploadArtifacts,
+            textUploadContextByReferenceMimeTypes,
+        }));
+    }
+    content.push({
+        type: "text",
+        text: userPrompt,
+    });
+    return {
+        role: "user",
+        content,
+    };
+};
+export const doLLMGenerating = (clark, services) => {
     const transitionTo = transitionFrom(clark);
-    const sendUserMessage = sendUserMessageChannel(clark);
-    const sendUserCompletion = sendUserCompletionChannel(clark);
-    const logger = getLogger();
     return async ({ event }) => {
         switch (event.type) {
             case AGENT_PLANNED: {
-                const { systemPrompt, userPrompt, debugging } = event;
-                const { abortController } = clark.context;
-                const { fullStream } = streamText({
-                    model: anthropicProvider("claude-4-sonnet-20250514"),
-                    system: systemPrompt,
-                    prompt: userPrompt,
-                    experimental_transform: smoothStream(),
-                    maxTokens: 32000,
-                    abortSignal: abortController?.signal,
+                const { userPrompt, promptContext, isUserPrompt = true, safetyClassificationInput, knowledgeMessageId, } = event;
+                const runPromptId = clark.context.promptId;
+                const isStaleRun = () => clark.context.promptId !== runPromptId;
+                const provider = services.llmProvider.name;
+                const isKnowledgeEnabled = clark.context.llmConfig?.flags?.isFactsEnabled ?? false;
+                const mode = clark.context.currentMode;
+                const planContext = clark.context.planContext;
+                const planApproved = planContext?.approved;
+                const pendingKnowledgeFreeTextTurn = clark.context.pendingKnowledgeFreeTextTurn === true;
+                const pendingKnowledgeEntries = clark.context.pendingAppKnowledge?.knowledgeEntries?.map((entry) => ({
+                    name: entry.name,
+                    description: entry.description,
+                }));
+                const context = getActiveContext(clark, services);
+                const skillsNeedReload = context?.checkAndClearSkillsNeedReload?.() ?? false;
+                const userId = parseJwt(clark.context.jwt)?.userId ?? "";
+                let netNewKnowledge = {
+                    org: [],
+                    user: [],
+                    integrations: {},
+                };
+                let knowledgeSections = {
+                    systemPromptSection: "",
+                    userMessageSection: "",
+                    onDemandSkillIndex: "",
+                    facts: netNewKnowledge,
+                };
+                if (isKnowledgeEnabled) {
+                    knowledgeSections =
+                        await services.knowledgeManager.loadFactsPromptSections({
+                            rpcClient: services.rpcClient,
+                            organizationId: services.organizationId,
+                            userId,
+                            logger: services.logger,
+                            promptIntegrations: promptContext?.integrations ?? [],
+                            planIntegrations: planContext?.integrations,
+                            tracer: clark.tracer,
+                        });
+                    // Get net-new facts (this marks ALL facts as sent, including on-demand)
+                    const allNetNewKnowledge = services.knowledgeManager.getNetNewFacts(knowledgeSections.facts);
+                    // Only show always-inject facts in the initial knowledge UI message
+                    // On-demand facts will be shown when they are read via build_readFile
+                    netNewKnowledge =
+                        services.knowledgeManager.filterAlwaysInjectFacts(allNetNewKnowledge);
+                }
+                // Load app knowledge entries from disk (user's persistent app preferences)
+                let appKnowledgeSection = "";
+                let appMetrics;
+                try {
+                    const appSkillsManager = new AppSkillsManager(services.appRootDirPath);
+                    const appKnowledgeBundle = await appSkillsManager.loadFactsForPromptBundle();
+                    appKnowledgeSection = appKnowledgeBundle.section;
+                    appMetrics = {
+                        alwaysInjectDedupeKeys: appKnowledgeBundle.alwaysInjectDedupeKeys,
+                        onDemandIndexCount: appKnowledgeBundle.onDemandIndexCount,
+                    };
+                }
+                catch (err) {
+                    clark.logger.warn("[llm-generating] Failed to load app skills facts (non-blocking)", { err });
+                }
+                recordKnowledgeTurnLoadMetrics({
+                    appMetrics,
+                    rpcFacts: isKnowledgeEnabled
+                        ? knowledgeSections.facts
+                        : { integrations: {}, org: [], user: [] },
                 });
-                let pendingArtifacts = false;
-                let artifactChunk = null;
-                const flushedAfterArtifacts = [];
-                // the buffer collects the text and artifact chunks and
-                // yields side effects on flush or when a new chunk type is detected
-                const resultBuffer = new BoltResultBuffer({
-                    onPending: async (type) => {
-                        switch (type) {
-                            case BoltResultType.Artifact:
-                                if (!debugging) {
-                                    void sendUserMessage({ text: "Starting to build…" });
-                                }
-                                pendingArtifacts = true;
-                                break;
-                        }
+                let registryPolicy;
+                try {
+                    const result = await services.npmRegistryClient?.getConfig();
+                    if (result) {
+                        // Narrow `result.source` to the subset the paragraph builder
+                        // distinguishes. `stale` is functionally a successful read
+                        // (cache hit), so collapse it into `configured` — what matters
+                        // to the prompt is "we have a real, recent view of the policy"
+                        // versus the degraded `unreachable` case.
+                        const source = result.source === "unreachable"
+                            ? "unreachable"
+                            : result.source === "not-configured"
+                                ? "not-configured"
+                                : "configured";
+                        registryPolicy = {
+                            hasAnyRegistryConfigured: result.config.configured,
+                            source,
+                        };
+                    }
+                }
+                catch (err) {
+                    clark.logger.warn("[llm-generating] Failed to resolve registry policy (non-blocking)", getErrorMeta(err));
+                }
+                const migrationChecklist = await readPersistedChecklist(services.appRootDirPath);
+                const v2ToV3MigrationInProgress = isV2ToV3MigrationInProgress(migrationChecklist);
+                const coreModel = clark.context.llmConfig?.coreModel;
+                const gitConnected = gitConnectedFromRuntime(services.gitService);
+                // Which publish/Git guidance the turn received is otherwise only
+                // recoverable by reading the raw system prompt, and reports of wrong
+                // guidance arrive as "Clark told me to connect GitHub".
+                clark.logger.debug("[llm-generating] Resolved Git publish guidance", {
+                    gitConnected,
+                    nativeGitEnabled: services.features.nativeGitEnabled,
+                    mode,
+                });
+                const system = buildBaseSystemPrompt(services, mode, knowledgeSections.systemPromptSection, appKnowledgeSection, knowledgeSections.onDemandSkillIndex, registryPolicy, v2ToV3MigrationInProgress, coreModel, true, { gitConnected });
+                // Same inputs, minus the tool-workflow sections. Stashed for the
+                // nested exitPlanMode plan stream, which binds no tools: seeding it
+                // with the agent prompt made models imitate a tool call in text and
+                // the markup rendered verbatim on the plan card. The stash is
+                // unconditional; consumption is gated by the
+                // clark.plan-generation-system-prompt.enabled rollout flag inside
+                // exitPlanMode, so the flag is read in exactly one place.
+                const planGenerationSystemPrompt = buildBaseSystemPrompt(services, mode, knowledgeSections.systemPromptSection, appKnowledgeSection, knowledgeSections.onDemandSkillIndex, registryPolicy, v2ToV3MigrationInProgress, 
+                // No app-builder model guidance for the plan stream: the block is
+                // unvalidated operator text from LaunchDarkly, so it can carry the
+                // tool imperatives this variant exists to remove.
+                undefined, false, {
+                    gitConnected,
+                    variant: "plan-generation",
+                });
+                // Unlike the agent `system` (passed run-scoped into this run's own
+                // streamText call), the stash is a shared-context write. The awaits
+                // above (knowledge/config loading) can park this handler while a
+                // cancel lands and a NEW prompt starts and stashes its own variant;
+                // a late write from this run would replace it with a stale knowledge
+                // snapshot that the active run's exitPlanMode then consumes. The
+                // check-then-write below is synchronous, so it cannot interleave.
+                if (isStaleRun()) {
+                    clark.logger.info("[llm-generating] Skipping plan-generation prompt stash from a stale run", {
+                        runPromptId,
+                        currentPromptId: clark.context.promptId,
+                    });
+                }
+                else {
+                    clark.updateContext((context) => ({
+                        ...context,
+                        planGenerationSystemPrompt,
+                    }));
+                }
+                void services.logger.info("[llm-generating] System prompt:", {
+                    systemPromptLength: system.length,
+                    planGenerationSystemPromptLength: planGenerationSystemPrompt.length,
+                    coreModel,
+                    appBuilderModelGuidanceApplied: system.includes("<app_builder_model_guidance>"),
+                });
+                const preferredAppInferenceIntegrationId = promptContext?.aiConfiguration?.preferredAppInferenceIntegrationId;
+                const preferredAppInferenceIntegration = preferredAppInferenceIntegrationId
+                    ? await services.integrationStore.availableIntegration(preferredAppInferenceIntegrationId)
+                    : undefined;
+                const textUploadArtifacts = await materializeTextUploadArtifacts({
+                    clark,
+                    services,
+                    promptContext,
+                    planContext,
+                });
+                const textUploadMimeTypes = clark.context.llmConfig?.flags?.textUploadContextByReferenceMimeTypes;
+                const user = buildUserMessage({
+                    preferredAppInferenceIntegration,
+                    userPrompt,
+                    promptContext,
+                    planContext,
+                    mode,
+                    services,
+                    userChanges: clark.context.userChanges,
+                    userFactsSection: knowledgeSections.userMessageSection,
+                    pendingKnowledgeFreeTextTurn,
+                    pendingKnowledgeEntries,
+                    skillsNeedReload,
+                    useSystemSkills: services.features?.useSystemSkills ?? false,
+                    textUploadArtifacts,
+                    textUploadContextByReferenceMimeTypes: Array.isArray(textUploadMimeTypes)
+                        ? textUploadMimeTypes.filter((mimeType) => typeof mimeType === "string")
+                        : undefined,
+                });
+                void services.logger.info("[llm-generating] User message:", {
+                    userMessagePartCount: Array.isArray(user.content)
+                        ? user.content.length
+                        : 1,
+                    userMessageTotalLength: Array.isArray(user.content)
+                        ? user.content.reduce((acc, part) => acc + (part.type === "text" ? part.text.length : 0), 0)
+                        : user.content.length,
+                });
+                const sendUserMessage = sendUserMessageChannel(clark, services.chatSessionStore);
+                if (isKnowledgeEnabled) {
+                    // Persist validated knowledge message to chatSessionStore so it survives message reloads
+                    const knowledgePayload = {
+                        id: knowledgeMessageId,
+                        type: "knowledge",
+                        role: "assistant",
+                        content: "",
+                        status: "validated",
+                        facts: netNewKnowledge,
+                    };
+                    // Fail-open: half-open peer must not delay streamText.
+                    // `immediate: true` keeps these off peerChannelQueue.
+                    // Catch background rejections — sendUserMessageChannel rethrows
+                    // genuine RPC failures; bare `void` would be an unhandled rejection.
+                    catchBackgroundPeerDisconnect(sendUserMessage(knowledgePayload, 0, true), "knowledge push");
+                    catchBackgroundPeerDisconnect(sendUserMessage({
+                        type: "reasoning",
+                        role: "assistant",
+                        content: "",
+                    }, 0, true), "reasoning push");
+                }
+                const preSessionWatch = startPreSessionWatch({
+                    applicationId: services.applicationId,
+                    degradationKey: resolvePromptOutcomeDedupeKey(clark.context),
+                    logger: clark.logger,
+                    organizationId: services.organizationId,
+                });
+                let tools;
+                try {
+                    tools = await buildTools(clark, services, promptContext?.environmentCompatibility?.canManageEnvironments);
+                }
+                catch (error) {
+                    preSessionWatch.complete("canceled");
+                    throw error;
+                }
+                preSessionWatch.complete("ok");
+                const result = await clark.streamText(services, {
+                    user,
+                    system,
+                    tools,
+                    observers: services.streamObservers,
+                    context: {
+                        contextId: getContextId(clark, services),
+                    },
+                    stopWhen: [
+                        hasToolSuccess("build_finalize"),
+                        hasToolSuccess("exitPlanMode"),
+                        hasToolSuccess("askMultiChoice"),
+                        hasToolSuccess("askSearchableDropdown"),
+                        hasToolSuccess("openExistingIntegration"),
+                        hasToolSuccess("openIntegrationSetup"),
+                        needsPermissionToExecute(clark),
+                        isAwaitingUser(clark),
+                    ],
+                    onError: (error) => {
+                        clark.logger.error("LLM stream processing failed", getErrorMeta(error));
                     },
-                    onFlush: async (type, text) => {
-                        switch (type) {
-                            case BoltResultType.Text:
-                                if (artifactChunk) {
-                                    flushedAfterArtifacts.push([type, text]);
+                    safety: isUserPrompt
+                        ? {
+                            scope: "last",
+                            classification: {
+                                enabled: services.features.safetyClassificationEnabled ?? false,
+                                input: safetyClassificationInput,
+                                model: services.features.safetyClassificationEnabled
+                                    ? services.llmProvider.modelForTask("fast").model
+                                    : undefined,
+                                failOpen: true,
+                            },
+                            secretRedaction: {
+                                level: services.features.secretRedactionLevel ?? "full",
+                            },
+                        }
+                        : undefined,
+                });
+                let shouldTransitionToAwaitingUser;
+                let blockedAwaitingUserTransitionReason;
+                const markVisiblePromptAwaitingUser = () => {
+                    blockedAwaitingUserTransitionReason = undefined;
+                    shouldTransitionToAwaitingUser = true;
+                };
+                clark.logger.info("[llm-generating] Starting to process stream chunks");
+                try {
+                    for await (const chunk of result.fullStream) {
+                        if (isStaleRun()) {
+                            clark.logger.warn("[llm-generating] Ignoring stale stream chunk from prior run", {
+                                runPromptId,
+                                currentPromptId: clark.context.promptId,
+                                chunkType: chunk.type,
+                            });
+                            return;
+                        }
+                        if (chunk.type === "tool-result") {
+                            const isOpenIntegrationTool = chunk.toolName === "openExistingIntegration" ||
+                                chunk.toolName === "openIntegrationSetup";
+                            const isUpdateIntegrationTool = chunk.toolName === "updateIntegrationFields";
+                            const output = getToolResultOutputObject(chunk.output);
+                            const peerDisconnected = output?.peerDisconnected === true;
+                            if (chunk.toolName === "askMultiChoice" ||
+                                chunk.toolName === "askSearchableDropdown") {
+                                if (peerDisconnected) {
+                                    blockedAwaitingUserTransitionReason =
+                                        "interactive prompt peer disconnected";
                                 }
                                 else {
-                                    void sendUserMessage({ text, type: "text" });
+                                    const hasVisiblePrompt = output?.success === true || output?.displaced === true;
+                                    if (hasVisiblePrompt) {
+                                        markVisiblePromptAwaitingUser();
+                                    }
                                 }
-                                break;
-                            case BoltResultType.Think:
-                                if (artifactChunk) {
-                                    flushedAfterArtifacts.push([type, text]);
+                            }
+                            if (chunk.toolName === "exitPlanMode") {
+                                if (peerDisconnected) {
+                                    blockedAwaitingUserTransitionReason =
+                                        "plan prompt peer disconnected";
                                 }
                                 else {
-                                    void sendUserMessage({ text, type: "reasoning" });
-                                }
-                                break;
-                            case BoltResultType.Artifact: {
-                                artifactChunk = text;
-                                break;
-                            }
-                        }
-                    },
-                });
-                // process stream. in general this should be agnostic to the bolt-oriented prompt
-                for await (const chunk of fullStream) {
-                    switch (chunk.type) {
-                        case "text-delta":
-                            resultBuffer.add(chunk.textDelta);
-                            resultBuffer.maybeFlush();
-                            break;
-                        case "reasoning":
-                            // note: unused; the system prompt encourages <think> tags
-                            break;
-                        case "file":
-                            // note: unused; the system prompt encourages <boltArtifact> tags
-                            break;
-                        case "step-start":
-                            logger.debug("[ai-service] Step started:", chunk.messageId);
-                            break;
-                        case "step-finish":
-                            resultBuffer.maybeFlush(true);
-                            logger.debug("[ai-service] Step finished:", chunk.messageId);
-                            break;
-                        case "error":
-                            {
-                                logger.error("[ai-service] LLM error chunk:", chunk);
-                                let error = {
-                                    type: "unknown",
-                                };
-                                if (typeof chunk.error === "object" &&
-                                    chunk.error !== null &&
-                                    "type" in chunk.error &&
-                                    typeof chunk.error.type === "string") {
-                                    error = chunk.error;
+                                    const hasVisiblePrompt = output?.success === true || output?.displaced === true;
+                                    if (hasVisiblePrompt) {
+                                        markVisiblePromptAwaitingUser();
+                                    }
                                 }
-                                transitionTo({
-                                    type: LLM_ERRORED,
-                                    error: error,
-                                });
-                            }
-                            break;
-                        case "finish":
-                            if (chunk.finishReason !== "stop") {
-                                transitionTo({
-                                    type: LLM_FINISHED_UNEXPECTEDLY,
-                                    finishReason: chunk.finishReason,
-                                });
                             }
-                            else if (!pendingArtifacts || !artifactChunk) {
-                                transitionTo({
-                                    type: APP_RUNTIME_UPDATED_WITHOUT_EDITS,
-                                });
-                                // TODO: do this in the state handler
-                                void sendUserCompletion({
-                                    hasSuggestions: false,
-                                });
-                            }
-                            else {
-                                const generated = artifactProcessor.extractFileArtifacts(artifactChunk);
-                                const summaryMessages = flushedAfterArtifacts
-                                    .filter(([type]) => type === BoltResultType.Text)
-                                    .map(([_, text]) => text);
-                                if (debugging) {
-                                    // inform of debugging progress
-                                    for (const message of summaryMessages) {
-                                        void sendUserMessage({ text: message });
+                            if (isOpenIntegrationTool || isUpdateIntegrationTool) {
+                                const success = output?.success === true;
+                                if (success) {
+                                    const sendInteractiveMessage = sendInteractiveMessageChannel(clark, services.chatSessionStore);
+                                    const payload = {
+                                        type: "multi_choice",
+                                        role: "assistant",
+                                        content: "Integration drafted",
+                                        group: "clark",
+                                        choices: ["Discard integration setup", "Save integration"],
+                                        selectionType: "single",
+                                    };
+                                    const result = await sendInteractiveMessage(payload);
+                                    if (!result.success && result.peerDisconnected) {
+                                        blockedAwaitingUserTransitionReason =
+                                            "integration action prompt peer disconnected";
+                                    }
+                                    else {
+                                        const hasVisiblePrompt = result.success ||
+                                            (!result.success && result.displaced === true);
+                                        if (hasVisiblePrompt) {
+                                            markVisiblePromptAwaitingUser();
+                                        }
+                                    }
+                                    if (result.success &&
+                                        clark.context.activeInteractiveMessage?.id) {
+                                        clark.updateContext({
+                                            pendingIntegrationActionPrompt: {
+                                                messageId: clark.context.activeInteractiveMessage.id,
+                                            },
+                                        });
                                     }
                                 }
-                                else {
-                                    // store the summary messages so we can display them after everything is validated
-                                    clark.updateContext({
-                                        summaryMessages,
-                                    });
-                                }
-                                transitionTo({
-                                    type: LLM_FINISHED,
-                                    files: generated,
-                                });
                             }
-                            break;
-                        case "tool-call":
-                        case "tool-call-streaming-start":
-                        case "tool-call-delta":
-                        case "reasoning-signature":
-                        case "redacted-reasoning":
-                        case "source":
-                            break;
-                        default:
-                            logger.error("[ai-service] Unhandled chunk type:", chunk.type);
-                            break;
+                        }
+                        await processStreamChunk(chunk, clark, services);
+                    }
+                    clark.logger.info("[llm-generating] Stream processing completed successfully");
+                    // APPS-4729: block-end chat commits are queued, not awaited, inside
+                    // the stream loop. Make history durable before transitioning, but
+                    // bound the wait so a dead RPC socket cannot wedge the FSM here.
+                    await flushPendingChatPushesBeforeTransition(services);
+                }
+                catch (err) {
+                    // Error/abort exits need the same durability boundary as the
+                    // success path: commits queued before the failure must flush
+                    // (bounded) before any transition is dispatched, or they race the
+                    // next state's reads of chat history.
+                    await flushPendingChatPushesBeforeTransition(services);
+                    let error;
+                    if (LLMProviderError.isInstance(err)) {
+                        error = err;
+                    }
+                    else {
+                        error = wrapError(err, provider);
+                    }
+                    if (error.type === "aborted") {
+                        const failure = promptFailureFromStreamAbort(clark.context);
+                        clark.logger.info("LLM generation aborted", {
+                            userInitiated: failure.origin === "user",
+                        });
+                        if (isStaleRun()) {
+                            clark.logger.info("[llm-generating] Ignoring aborted transition from stale run", {
+                                runPromptId,
+                                currentPromptId: clark.context.promptId,
+                            });
+                            return;
+                        }
+                        void transitionTo({
+                            type: USER_CANCELED,
+                            failure,
+                        });
+                        return;
+                    }
+                    if (error.type === "validation_error" && error.isRetryable) {
+                        clark.logger.warn("Validation error (possibly invalid tool input)", getErrorMeta(error));
+                        return;
+                    }
+                    // Handle AI_NoOutputGeneratedError - transition to idle since no output was generated
+                    // The retry logic will have already tried fallback providers/models if enabled
+                    if (isNoOutputError(err)) {
+                        getLogger().warn("AI stream completed without output (retries exhausted or not retryable)");
+                        if (isStaleRun()) {
+                            clark.logger.info("[llm-generating] Ignoring no-output transition from stale run", {
+                                runPromptId,
+                                currentPromptId: clark.context.promptId,
+                            });
+                            return;
+                        }
+                        void transitionTo({
+                            type: AGENT_CANCELED,
+                            advice: "Clark completed without output. Try again.",
+                            failure: promptFailureFromLlmError(error),
+                        });
+                        return;
+                    }
+                    clark.logger.error("LLM stream processing failed", getErrorMeta(error));
+                    if (isStaleRun()) {
+                        clark.logger.info("[llm-generating] Ignoring errored transition from stale run", {
+                            runPromptId,
+                            currentPromptId: clark.context.promptId,
+                        });
+                        return;
                     }
+                    void clark.send({
+                        type: LLM_ERRORED,
+                        error,
+                    });
+                    return;
+                }
+                if (blockedAwaitingUserTransitionReason) {
+                    if (isStaleRun()) {
+                        clark.logger.info("[llm-generating] Ignoring peer-disconnect transition from stale run", {
+                            runPromptId,
+                            currentPromptId: clark.context.promptId,
+                        });
+                        return;
+                    }
+                    clark.logger.warn("[llm-generating] Interactive prompt was not delivered; returning to idle instead of awaiting invisible user input", {
+                        reason: blockedAwaitingUserTransitionReason,
+                    });
+                    void transitionTo({
+                        type: AGENT_CANCELED,
+                        advice: "The editor disconnected before Clark could show the prompt. Reconnect and retry.",
+                        failure: promptFailurePlatform("peer_disconnect"),
+                    });
+                    return;
+                }
+                // In PLAN mode, only proceed to draft state if the user has approved the plan
+                if (mode === AiMode.PLAN && !planApproved) {
+                    if (isStaleRun()) {
+                        clark.logger.info("[llm-generating] Ignoring plan-awaiting transition from stale run", {
+                            runPromptId,
+                            currentPromptId: clark.context.promptId,
+                        });
+                        return;
+                    }
+                    clark.logger.info("[llm-generating] Early return: PLAN mode without approval - transitioning to AGENT_NEEDS_USER_INPUT", {
+                        hasSuggestions: clark.context.hasSuggestions,
+                        mode,
+                        planApproved,
+                    });
+                    void transitionTo({
+                        type: AGENT_NEEDS_USER_INPUT,
+                        countsAsPromptSuccess: true,
+                    });
+                    return;
+                }
+                if (shouldTransitionToAwaitingUser ||
+                    clark.context.pendingToolPermissionRequest) {
+                    if (isStaleRun()) {
+                        clark.logger.info("[llm-generating] Ignoring awaiting-user transition from stale run", {
+                            runPromptId,
+                            currentPromptId: clark.context.promptId,
+                        });
+                        return;
+                    }
+                    const draftRefreshResult = await refreshHasSuggestionsFromLocalDraft(clark, services, isStaleRun, { runPromptId });
+                    // The boolean updates hasSuggestions as a side effect; stale runs must
+                    // not transition, but read failures should still show the approval UI.
+                    if (draftRefreshResult.status === "stale") {
+                        return;
+                    }
+                    clark.logger.info("[llm-generating] Early return: transitioning to AGENT_NEEDS_USER_INPUT", {
+                        hasSuggestions: clark.context.hasSuggestions,
+                        shouldTransitionToAwaitingUser,
+                        pendingToolPermissionRequest: !!clark.context.pendingToolPermissionRequest,
+                    });
+                    void transitionTo({
+                        type: AGENT_NEEDS_USER_INPUT,
+                        countsAsPromptSuccess: true,
+                    });
+                    return;
+                }
+                const draftRefreshResult = await refreshHasSuggestionsFromLocalDraft(clark, services, isStaleRun, { runPromptId });
+                if (draftRefreshResult.status === "stale") {
+                    return;
+                }
+                if (draftRefreshResult.status === "error") {
+                    void clark.send({
+                        type: LLM_ERRORED,
+                        error: wrapError(new Error("Failed to refresh local draft state", {
+                            cause: draftRefreshResult.error,
+                        }), provider),
+                    });
+                    return;
+                }
+                const { hasLocalDraft } = draftRefreshResult;
+                if (hasLocalDraft) {
+                    clark.logger.info("[llm-generating] Transitioning to V3_AGENT_FINISHED with hasSuggestions=true");
+                    void transitionTo({
+                        type: V3_AGENT_FINISHED,
+                    });
+                }
+                else {
+                    clark.logger.info("[llm-generating] No local drafts found, completing agent run with hasSuggestions=false");
+                    void transitionTo({
+                        type: V3_AGENT_FINISHED,
+                    });
                 }
-                resultBuffer.maybeFlush(true);
             }
         }
     };