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

package/dist/ai-service/agent/tools2/tools/exit-plan-mode.js

@@ -0,0 +1,802 @@
+import { z } from "zod";
+import { AI_PLAN_STREAMING_END_MARKER, } from "@superblocksteam/library-shared/types";
+import { getErrorMeta, getLogger } from "../../../../util/logger.js";
+import { AttachmentsStore } from "../../../attachments/index.js";
+import { getActiveContext } from "../../../llm/context-v2/utils/index.js";
+import { isPaywallError } from "../../../llm/error.js";
+import { isManagedNativeDbAvailableForClark } from "../../../managed-native-db-availability.js";
+import { sendInteractiveMessageChannel, sendUserMessageChannel, } from "../../../state-machine/helpers/peer.js";
+import { createToolFactory, PermissionLevel, ToolCategory, ToolExecutionError, } from "../types.js";
+const MAX_ATTEMPTS = 5;
+const MAX_PLAN_ATTACHMENTS = 5;
+const TOOL_EXECUTION_TIMEOUT_MS = 3 * 60 * 1000;
+// Reasoning-only empty text (finishReason:stop, no text-delta) does not recover
+// by retrying: the input is identical so every attempt reproduces it. We give
+// the nudged retry exactly one chance to break the loop, then stop instead of
+// burning the remaining MAX_ATTEMPTS. One original empty attempt + one nudged
+// retry = 2.
+export const MAX_EMPTY_TEXT_ATTEMPTS = 2;
+// Enabling extended thinking on Cortex for the plan-generation turn can cause
+// a thinking-only turn: the model emits reasoning, then closes an empty text
+// block, returning no plan content. Plan generation is a single text stream
+// with no interleaved tool calls, so thinking is disabled for this call to
+// prevent the empty output at the source.
+// Note: adaptive-effort models (e.g. claude-opus-4-7) keep adaptive thinking
+// regardless of this flag, by design (they reject the non-adaptive shape). That
+// is not a concern here: the empty-text turn is Cortex-only (claude-opus-4-6),
+// which honors the disable.
+export const PLAN_GEN_THINKING_OPTIONS = {
+    enabled: false,
+    budgetTokens: 0,
+    interleaved: false,
+};
+/**
+ * Transcript-markup shapes models imitate when they pantomime a tool call in
+ * text: <tool_call>/<tool-call>/<tool_response>/<tool-result> tags (open or
+ * close, with or without attributes) and the bare {"name": ...,
+ * "arguments": ...} tool-call JSON. Single source of truth for the
+ * post-generation detector below and the tool-markup eval.
+ */
+export const PLAN_TOOL_MARKUP_PATTERNS = [
+    /<\/?tool[-_](?:call|calls|response|result|use)[\s>]/i,
+    /\{\s*"name"\s*:\s*"[^"]+"\s*,\s*"arguments"\s*:/,
+];
+class NonRetryableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NonRetryableError";
+    }
+}
+/**
+ * Iterates a stream WITHOUT cancelling it on early exit. `ReadableStream`'s
+ * default async iterator calls `reader.cancel()` on `break`/`return`/`throw`;
+ * for a tee'd branch that cancel hangs until the sibling branch is also
+ * cancelled (see the `preventCancel` note at the plan-stream loop). Using
+ * `values({ preventCancel: true })` makes early exit just release the reader
+ * lock. Runtime `ReadableStream` (Node/web) exposes `values`; the TS lib type
+ * doesn't declare it, hence the localized cast.
+ */
+function iterateWithoutCancel(stream) {
+    const maybeReadable = stream;
+    // Real `ReadableStream` (prod, via the orchestrator): use `preventCancel` so
+    // early exit doesn't hang on the tee-branch cancel.
+    if (typeof maybeReadable.values === "function") {
+        return maybeReadable.values({ preventCancel: true });
+    }
+    // Plain async iterables (e.g. test fakes / generators): default iteration is
+    // safe — their `return()` doesn't deadlock the way a tee'd branch does.
+    return stream[Symbol.asyncIterator]();
+}
+/**
+ * Thrown when an attempt produces no plan text (finishReason:stop, empty text
+ * block). Retryable, but the retry MUST vary the prompt
+ * (see PLAN_RETRY_NO_TEXT_NUDGE): an identical retry hits the same cached input
+ * and deterministically reproduces the empty output.
+ */
+class EmptyPlanGenerationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmptyPlanGenerationError";
+    }
+}
+/**
+ * The terminal result returned when a plan-delivery push cannot reach the
+ * editor peer. Frozen and shared so every bail site returns the exact same
+ * shape; the FSM cancels the run on `peerDisconnected`.
+ */
+const PLAN_PEER_DISCONNECTED_RESULT = Object.freeze({
+    success: false,
+    peerDisconnected: true,
+    message: "Plan could not be delivered because the editor peer disconnected. Wait for the user to reconnect before retrying.",
+});
+const PlanComplexityLevels = [
+    "Extra Small",
+    "Small",
+    "Medium",
+    "Large",
+    "Extra Large",
+];
+function formatIntegrationForPlanPrompt(integration) {
+    const { name, displayName, id, type } = integration;
+    const labelForLLM = displayName || name;
+    return `- ${labelForLLM}\n  tag: @${name}[id=${id}]\n  type: ${type}`;
+}
+/**
+ * Exit Plan Mode - prompts the user to exit Plan mode when they have finished planning and are ready to code.
+ */
+export const exitPlanModeToolFactory = createToolFactory("exitPlanMode", ({ clark, services, }) => {
+    const managedNativeDbAvailable = isManagedNativeDbAvailableForClark(services);
+    // Build the base input schema
+    const baseInputSchema = z.object({
+        complexity: z
+            .enum(PlanComplexityLevels)
+            .describe("Your best estimate of the plan complexity"),
+        title: z
+            .string()
+            .min(1, "Plan title is required")
+            .max(160, "Plan title must be 160 characters or fewer")
+            .describe("Title to display for the plan. Should be the name of the feature or fix, eg 'Executive orders dashboard', 'User login page', 'Fix data sync bug'"),
+        integrationIds: z
+            .array(z.string())
+            .describe("List of integration IDs that may be referenced in the plan."),
+        attachmentIds: z
+            .array(z.number())
+            .min(0)
+            .max(MAX_PLAN_ATTACHMENTS)
+            .describe(`List of up to ${MAX_PLAN_ATTACHMENTS} attachment IDs that are relevant to the plan. Call listAttachments first to see available attachments with their IDs, types, and labels.`),
+        entityIds: z
+            .array(z.string())
+            .min(0)
+            .describe(`List of targeted entity IDs (components) from the user's selection that are relevant to implementing this plan. Include entities that the plan will modify or depend on.`),
+    });
+    // Conditionally add includesFreshDatabase field only when managed native DB
+    // is available (flag + ONPREMISE + OPA edit lifecycle registration).
+    const inputSchema = managedNativeDbAvailable
+        ? baseInputSchema.extend({
+            includesFreshDatabase: z
+                .boolean()
+                .optional()
+                .describe("Set to true only when the plan explicitly calls provisionDatabase to create a new dev database. Do not set it for plans that query, migrate, or modify an existing database."),
+        })
+        : baseInputSchema;
+    const description = buildExitPlanModeDescription(managedNativeDbAvailable);
+    return {
+        description,
+        category: ToolCategory.PLAN,
+        defaultPermission: PermissionLevel.ALLOW,
+        readOnly: true,
+        timeoutMs: TOOL_EXECUTION_TIMEOUT_MS,
+        inputSchema,
+        execute: async (input, { abortSignal, messages }) => {
+            const { complexity, title, integrationIds, attachmentIds, entityIds, includesFreshDatabase, } = input;
+            const { chatSessionStore } = services;
+            const sendUserMessage = sendUserMessageChannel(clark, chatSessionStore);
+            const sendInteractiveMessage = sendInteractiveMessageChannel(clark, chatSessionStore);
+            const availableIntegrations = await services.integrationStore.availableIntegrations();
+            const sanitizedTitle = title.trim() || "Plan";
+            const allowedIntegrationIds = new Set(integrationIds ?? []);
+            const filteredIntegrations = availableIntegrations
+                .filter((integration) => allowedIntegrationIds.has(integration.id))
+                .map((integration) => ({
+                id: integration.id,
+                name: integration.name,
+                displayName: integration.displayName,
+                type: integration.type,
+                metadata: {},
+            }));
+            const unavailableRequestedIds = [...allowedIntegrationIds].filter((id) => !availableIntegrations.some((integration) => integration.id === id));
+            if (unavailableRequestedIds.length > 0) {
+                getLogger().warn(`exitPlanMode: Requested integration IDs not available: ${unavailableRequestedIds.join(", ")}`);
+            }
+            // Filter tagged entities for plan execution
+            const taggedEntities = clark.context.taggedEntities ?? [];
+            let filteredEntities = [];
+            if (entityIds && entityIds.length > 0) {
+                const entityIdSet = new Set(entityIds);
+                filteredEntities = taggedEntities.filter((entity) => entityIdSet.has(entity.id));
+                getLogger().info(`Plan entities: ${taggedEntities.length} tagged, ${filteredEntities.length} selected for execution`);
+            }
+            const integrationGuidance = filteredIntegrations.length > 0
+                ? `
+Only reference the integrations listed below when they are necessary. Use the exact tag shown for each integration within relevant plan steps (e.g. "Use @Integration[id=123] to ..."). Do not reference any other integrations.
+
+${filteredIntegrations
+                    .map((integration) => formatIntegrationForPlanPrompt(integration))
+                    .join("\n\n")}`
+                : "";
+            const baseInstructions = PLAN_GENERATION_PROMPT;
+            const planInstructions = [
+                baseInstructions.trim(),
+                `Plan title: ${sanitizedTitle}`,
+                `Use integration.displayName instead of integration.name in titles and natural text`,
+                "NEVER include a different title in your response. Begin directly with the plan content. Start with an Overview heading if applicable.",
+                integrationGuidance.trim(),
+                `The task complexity has been assessed to be '${complexity}'`,
+            ]
+                .filter((section) => section.length > 0)
+                .join("\n\n")
+                .trim();
+            // Append plan generation prompt
+            const planPrompt = {
+                role: "user",
+                content: planInstructions.trim(),
+            };
+            getLogger().info(`Starting plan generation stream. complexity: ${complexity}`);
+            // Rollout gate: when on, the nested plan stream replaces the seeded
+            // agent system prompt with the plan-generation variant the agent
+            // loop stashes on the context before every turn (same
+            // knowledge/context inputs, minus the tool-workflow sections). When
+            // off, legacy behavior: no `system` override, the stream inherits
+            // the seeded agent prompt.
+            const planGenerationSystemPromptEnabled = services.features.planGenerationSystemPromptEnabled === true;
+            const planSystemPrompt = clark.context.planGenerationSystemPrompt;
+            // This tool only runs inside a turn and the stash is unconditional
+            // per turn, so with the flag on the prompt must always be present.
+            // Fail fast if it is not: a missing `system` would not crash the
+            // nested stream, it would silently keep the seeded agent prompt —
+            // the hallucinated textual tool-call bug this replaces — so a
+            // future call path that skips the stash must break loudly (and get
+            // caught in dev/CI) instead of shipping a silent probabilistic
+            // regression. The message must counter the tool description's
+            // "call the tool again" instruction: the missing stash is
+            // deterministic for the whole turn, so a retry can only fail
+            // identically.
+            if (planGenerationSystemPromptEnabled && !planSystemPrompt) {
+                throw new NonRetryableError("Plan generation is misconfigured for this turn (missing plan-generation system prompt). Do not call exitPlanMode again this turn — it will fail the same way. Tell the user plan generation hit an internal error and to resend their prompt.");
+            }
+            let attempt = 0;
+            let emptyTextAttempts = 0;
+            let fullPlanText = "";
+            // Set when the prior attempt produced reasoning-only empty text, so
+            // this attempt appends a corrective nudge and differs from it.
+            let appendNoTextNudge = false;
+            while (attempt < MAX_ATTEMPTS) {
+                const attemptNumber = attempt + 1;
+                let attemptPlanText = "";
+                let hasSentInitialPlanMessageThisAttempt = false;
+                if (clark.context.abortController?.signal?.aborted) {
+                    throw new Error("Plan generation aborted. User canceled, ask how they want to proceed.");
+                }
+                // Declared BEFORE the try so both the bail sites inside it AND the
+                // catch can abort it (fire-and-forget) to tear down the nested stream
+                // once we stop consuming it. Combined with the incoming tool
+                // `abortSignal` (optional, hence the filter) so a parent cancel still
+                // propagates.
+                const innerStreamAbortController = new AbortController();
+                const combinedAbortSignal = AbortSignal.any([abortSignal, innerStreamAbortController.signal].filter((s) => s != null));
+                // Id of the plan card this attempt opened, if any. Used to release
+                // only our own activeInteractiveMessage on incomplete teardown.
+                let planCardMessageId;
+                const releasePlanCardGuard = () => {
+                    const active = clark.context.activeInteractiveMessage;
+                    if (planCardMessageId == null || active?.id !== planCardMessageId) {
+                        return;
+                    }
+                    getLogger().warn("[exitPlanMode] Clearing plan-card activeInteractiveMessage after incomplete attempt", { attempt: attemptNumber, messageId: planCardMessageId });
+                    clark.updateContext({ activeInteractiveMessage: undefined });
+                };
+                // Single bail path for a plan-delivery push that the peer never
+                // acked: warn, tear down the nested stream (fire-and-forget;
+                // idempotent, so it is safe even where the stream already drained),
+                // and return the frozen terminal result. Because the `preventCancel`
+                // loop never cancels the tee branch, this abort is what actually
+                // stops generation — centralizing it here means a new push site
+                // cannot forget it.
+                const bailPeerDisconnected = (reason, logContext) => {
+                    getLogger().warn(`[exitPlanMode] ${reason} because the editor peer disconnected.`, logContext);
+                    innerStreamAbortController.abort();
+                    // Clear the plan-card guard so a model retry is not displaced.
+                    releasePlanCardGuard();
+                    return PLAN_PEER_DISCONNECTED_RESULT;
+                };
+                try {
+                    const attemptPrompt = appendNoTextNudge
+                        ? {
+                            role: "user",
+                            content: `${planPrompt.content}\n\n${PLAN_RETRY_NO_TEXT_NUDGE}`,
+                        }
+                        : planPrompt;
+                    const result = await clark.streamText(services, {
+                        abortSignal: combinedAbortSignal,
+                        user: attemptPrompt,
+                        // Replace the agent system prompt that rides in with the seeded
+                        // messages (an explicit setSystemPrompt on the ephemeral context
+                        // wins over the replayed system message). The agent prompt
+                        // instructs the model to "present plans using the exitPlanMode
+                        // tool", but this call binds no tools — models resolved that
+                        // contradiction by appending a fake textual <tool_call> block to
+                        // the plan, which rendered verbatim on the plan card and
+                        // poisoned the approved plan handed to Build mode.
+                        system: planGenerationSystemPromptEnabled
+                            ? planSystemPrompt
+                            : undefined,
+                        // Plan generation is a bounded one-shot seeded from the parent's
+                        // current in-flight history. Disable Phase-2 so this ephemeral
+                        // context does not run its own (redundant) session summarization
+                        // on top of the parent's. Merge over the live config
+                        // so the prod contextLimit is kept.
+                        context: {
+                            messages,
+                            contextOptionsV2: {
+                                ...clark.context.llmConfig?.contextOptionsV2,
+                                phase2Enabled: false,
+                            },
+                        },
+                        enableFallback: false,
+                        thinking: PLAN_GEN_THINKING_OPTIONS,
+                        // the llm will re-call the tool if it fails, so we don't need to retry here
+                        retry: {
+                            maxAttempts: 0,
+                        },
+                        observers: services.streamObservers,
+                        onError: (error) => {
+                            clark.logger.error("[exitPlanMode] LLM stream generation failed", getErrorMeta(error));
+                        },
+                    });
+                    const chunkTypeCounts = {};
+                    let streamError = null;
+                    let finishReason = null;
+                    let reasoningLength = 0;
+                    // `preventCancel: true` — on an early `return` from this
+                    // loop (e.g. a peer-disconnect bail below), the async iterator must
+                    // NOT call `reader.cancel()`. `fullStream`/`textStream` are two
+                    // branches of one tee'd source; cancelling only this branch stays
+                    // pending forever (WHATWG tee resolves the cancel only once BOTH
+                    // branches are cancelled, and `textStream` is never drained), which
+                    // would hang `execute()` until the 180s tool timeout. Instead we
+                    // skip the cancel and tear the stream down via
+                    // `innerStreamAbortController.abort()` at each bail.
+                    for await (const chunk of iterateWithoutCancel(result.fullStream)) {
+                        chunkTypeCounts[chunk.type] =
+                            (chunkTypeCounts[chunk.type] ?? 0) + 1;
+                        if (chunk.type === "error") {
+                            streamError = chunk.error;
+                            getLogger().error(`[exitPlanMode] Stream error`, getErrorMeta(chunk.error));
+                        }
+                        if (chunk.type === "reasoning-delta") {
+                            reasoningLength += chunk.text.length;
+                        }
+                        if (chunk.type === "finish") {
+                            finishReason = chunk.finishReason;
+                            getLogger().info(`[exitPlanMode] Stream finished with reason: ${chunk.finishReason}`, chunk.totalUsage);
+                        }
+                        if (chunk.type !== "text-delta") {
+                            continue;
+                        }
+                        const text = chunk.text;
+                        if (!hasSentInitialPlanMessageThisAttempt) {
+                            // Skip leading whitespace-only chunks so the initial plan
+                            // message starts on real content. Once the plan has begun,
+                            // whitespace chunks (e.g. "\n\n" between sections) are
+                            // meaningful for markdown formatting and must be forwarded.
+                            if (text.trim().length === 0) {
+                                continue;
+                            }
+                            planCardMessageId = crypto.randomUUID();
+                            const result = await sendInteractiveMessage({
+                                role: "assistant",
+                                type: "plan",
+                                content: text,
+                                group: "clark",
+                                title: sanitizedTitle,
+                                integrations: filteredIntegrations,
+                                entities: filteredEntities.length > 0 ? filteredEntities : undefined,
+                                includesFreshDatabase,
+                                streaming: true,
+                                id: planCardMessageId,
+                            });
+                            if (!result.success) {
+                                // We're abandoning this attempt's plan generation (peer
+                                // disconnected, or displaced by another interactive prompt).
+                                // Tear down the nested stream (fire-and-forget) so it doesn't
+                                // keep generating after we return. Combined with the
+                                // `preventCancel` loop, this settles the early return without
+                                // leaking the stream or hanging on the tee-branch cancel.
+                                innerStreamAbortController.abort();
+                                if (result.peerDisconnected) {
+                                    getLogger().warn("[exitPlanMode] Plan card was not delivered because the editor peer disconnected.", { attempt: attemptNumber });
+                                    return {
+                                        success: false,
+                                        peerDisconnected: true,
+                                        message: "Plan could not be presented because the editor peer disconnected before delivery. Wait for the user to reconnect before retrying.",
+                                    };
+                                }
+                                getLogger().warn("[exitPlanMode] Plan card was displaced by an in-flight interactive prompt; surfacing structured failure to the model.");
+                                return {
+                                    success: false,
+                                    displaced: true,
+                                    message: "Plan could not be presented because another interactive prompt is currently awaiting user input. Wait for the user to respond before retrying.",
+                                };
+                            }
+                            hasSentInitialPlanMessageThisAttempt = true;
+                        }
+                        else {
+                            const deltaResult = await sendUserMessage({
+                                role: "assistant",
+                                type: "plan-delta",
+                                content: text,
+                                group: "clark",
+                            });
+                            if (!deltaResult.success && deltaResult.peerDisconnected) {
+                                return bailPeerDisconnected("Plan delta not delivered", {
+                                    attempt: attemptNumber,
+                                    contentLength: text.length,
+                                });
+                            }
+                        }
+                        attemptPlanText += text;
+                    }
+                    if (!attemptPlanText.trim()) {
+                        getLogger().info(`[exitPlanMode] No text content produced`, {
+                            chunkTypeCounts,
+                            finishReason,
+                            reasoningLength,
+                        });
+                        if (streamError) {
+                            throw streamError;
+                        }
+                        throw new EmptyPlanGenerationError(`Plan generation produced no content. ` +
+                            `chunks: ${JSON.stringify(chunkTypeCounts)}, ` +
+                            `finishReason: ${finishReason}, ` +
+                            `reasoningLength: ${reasoningLength}`);
+                    }
+                    fullPlanText = attemptPlanText;
+                    // Detection only — never alter the plan. A stream sanitizer was
+                    // deliberately deferred until a real recurrence; this warning is
+                    // what makes a recurrence observable during rollout instead of
+                    // waiting for a user to report a broken plan card. Only
+                    // `warnStructured` keeps the attributes as searchable facets —
+                    // plain `warn` flattens them into the message text, and the flag
+                    // attribute is what separates a recurrence on the fixed path from
+                    // one on the legacy path.
+                    const markupPattern = PLAN_TOOL_MARKUP_PATTERNS.find((pattern) => pattern.test(attemptPlanText));
+                    if (markupPattern) {
+                        const markupMessage = "[exitPlanMode] Generated plan contains tool-call transcript markup";
+                        const markupAttributes = {
+                            "plan.markup_pattern": String(markupPattern),
+                            "plan.length": attemptPlanText.length,
+                            "plan.generation_system_prompt_enabled": planGenerationSystemPromptEnabled,
+                        };
+                        if (clark.logger.warnStructured) {
+                            clark.logger.warnStructured(markupMessage, markupAttributes);
+                        }
+                        else {
+                            clark.logger.warn(markupMessage, markupAttributes);
+                        }
+                    }
+                    // Load all attachments from store by ID (images, PDFs, text files - all unified)
+                    let planAttachments = [];
+                    if (attachmentIds && attachmentIds.length > 0) {
+                        const context = getActiveContext(clark, services);
+                        if (!context) {
+                            getLogger().error("[exitPlanMode] Context not loaded");
+                        }
+                        else {
+                            const store = new AttachmentsStore();
+                            const storedAttachments = store.getAttachmentsByIds(context, attachmentIds.slice(0, MAX_PLAN_ATTACHMENTS));
+                            planAttachments =
+                                AttachmentsStore.toAttachments(storedAttachments);
+                            getLogger().info(`Plan attachments: ${attachmentIds.length} requested, ${planAttachments.length} found in store (max ${MAX_PLAN_ATTACHMENTS})`, planAttachments.map((a) => ({
+                                type: a.type,
+                                fileName: a.fileName,
+                            })));
+                        }
+                    }
+                    const endMarkerResult = await sendUserMessage({
+                        role: "assistant",
+                        type: "plan-delta",
+                        content: AI_PLAN_STREAMING_END_MARKER,
+                        streaming: false,
+                        group: "clark",
+                        attachments: planAttachments.length > 0 ? planAttachments : undefined,
+                    });
+                    if (!endMarkerResult.success && endMarkerResult.peerDisconnected) {
+                        return bailPeerDisconnected("Plan streaming-end marker not delivered", { attempt: attemptNumber });
+                    }
+                    // Map complexity to plan_size for billing
+                    const planSizeMap = {
+                        "Extra Small": "small",
+                        Small: "small",
+                        Medium: "medium",
+                        Large: "large",
+                        "Extra Large": "extra large",
+                    };
+                    clark.updateContext((context) => ({
+                        ...context,
+                        planContext: {
+                            enableTesting: context.planContext?.enableTesting ?? false,
+                            plan: attemptPlanText,
+                            integrations: filteredIntegrations,
+                            entities: filteredEntities.length > 0 ? filteredEntities : undefined,
+                            approved: false,
+                            title: sanitizedTitle,
+                            attachments: planAttachments.length > 0 ? planAttachments : undefined,
+                        },
+                        planSize: planSizeMap[complexity],
+                    }));
+                    getLogger().info(`Plan generation completed successfully on attempt ${attemptNumber}. Plan length: ${attemptPlanText.length}`);
+                    return {
+                        plan: fullPlanText,
+                        message: "Plan presented to user. Awaiting mode confirmation.",
+                        title: sanitizedTitle,
+                        complexity,
+                    };
+                }
+                catch (error) {
+                    // Tear down the nested stream on the exception path too.
+                    // `iterateWithoutCancel` releases the reader lock without cancelling,
+                    // so without this an unexpected throw would leave the provider
+                    // stream generating in the background while `attempt++` starts a new
+                    // one — accumulating concurrent streams across retries.
+                    innerStreamAbortController.abort();
+                    if (hasSentInitialPlanMessageThisAttempt) {
+                        // Always release our plan-card guard on this teardown path,
+                        // including when sendUserMessage rethrows a genuine RPC error
+                        // (that throw would otherwise skip a post-await clear and leave
+                        // a later exitPlanMode retry displaced).
+                        try {
+                            const errorEndMarkerResult = await sendUserMessage({
+                                role: "assistant",
+                                type: "plan-delta",
+                                content: AI_PLAN_STREAMING_END_MARKER,
+                                streaming: false,
+                                group: "clark",
+                            });
+                            if (!errorEndMarkerResult.success &&
+                                errorEndMarkerResult.peerDisconnected) {
+                                // A peer disconnect is terminal: return immediately without
+                                // incrementing `attempt`, so a dropped editor does not burn the
+                                // retry budget (the FSM cancels the run on peerDisconnected).
+                                return bailPeerDisconnected("Plan streaming-end marker (error path) not delivered", { attempt: attemptNumber });
+                            }
+                        }
+                        finally {
+                            releasePlanCardGuard();
+                        }
+                    }
+                    attempt++;
+                    const isEmptyPlan = error instanceof EmptyPlanGenerationError;
+                    // Only carry the no-text nudge into the next attempt when this one
+                    // was reasoning-only empty text. Other failures (stream errors,
+                    // etc.) must not inherit the nudge, and they reset the empty-text
+                    // counter so the cap counts the most recent contiguous empty-text
+                    // streak rather than the lifetime total. This keeps the "one
+                    // original empty attempt + one nudged retry" invariant intact even
+                    // when other failures interleave (empty -> stream error -> empty
+                    // still earns its nudged retry).
+                    appendNoTextNudge = isEmptyPlan;
+                    emptyTextAttempts = isEmptyPlan ? emptyTextAttempts + 1 : 0;
+                    const emptyTextCapped = isEmptyPlan && emptyTextAttempts >= MAX_EMPTY_TEXT_ATTEMPTS;
+                    const willRetry = !emptyTextCapped && attempt < MAX_ATTEMPTS;
+                    if (appendNoTextNudge && willRetry) {
+                        getLogger().info(`[exitPlanMode] Applying corrective nudge on attempt ${attempt + 1} after reasoning-only empty output.`);
+                    }
+                    const logger = getLogger();
+                    const logAttempt = willRetry || emptyTextCapped ? logger.warn : logger.error;
+                    logAttempt(`Attempt ${attempt} failed to generate plan: ${error instanceof Error ? error.message : String(error)}. ${willRetry
+                        ? "Retrying..."
+                        : emptyTextCapped
+                            ? "Empty-text retry cap reached"
+                            : "Max attempts reached"}`, getErrorMeta(error));
+                    if (clark.context.abortController?.signal?.aborted) {
+                        throw error;
+                    }
+                    // A quota/paywall error won't resolve by retrying — each attempt
+                    // hits the same server-side gate. Re-throw immediately so it
+                    // reaches the FSM's LLM_ERRORED handler with its paywall context
+                    // intact; otherwise the MAX_ATTEMPTS branch below replaces it with
+                    // a generic message and the "add credits, type continue" flow
+                    // never fires. (APPS-4080 interim-steps hardening.)
+                    if (isPaywallError(error)) {
+                        throw error;
+                    }
+                    if (error instanceof NonRetryableError) {
+                        throw error;
+                    }
+                    // After the nudged retry also comes back empty, stop instead of
+                    // burning the remaining attempts. Re-throw as a warn-severity
+                    // ToolExecutionError so `[tool:exitPlanMode] ✗` is warn (the
+                    // Datadog error-level query for this string is leftover explorer).
+                    // Pass cause only — a message argument plus cause duplicates the
+                    // "produced no content" sentence. Orchestrator still logs
+                    // execute() throws at error.
+                    if (emptyTextCapped) {
+                        throw new ToolExecutionError({
+                            cause: error,
+                            context: {},
+                            input,
+                            severity: "warn",
+                            toolName: "exitPlanMode",
+                        });
+                    }
+                    if (attempt >= MAX_ATTEMPTS) {
+                        throw new Error(`Failed to generate a plan. Please call the tool again.`);
+                    }
+                }
+            }
+        },
+        getSummary: (input, output) => {
+            const title = output?.title ?? input.title ?? "plan";
+            const complexity = output?.complexity ?? input.complexity ?? "unknown";
+            return {
+                input: `title: "${title}", complexity: ${complexity}`,
+                output: "Plan presented to user",
+            };
+        },
+    };
+});
+export const EXIT_PLAN_MODE_PLAN_GENERATION_PROMPT_PREFIX = "Based on our conversation and the information gathered, create a specific, actionable plan.";
+// Appended to the plan prompt on a retry that follows a reasoning-only
+// empty-text attempt. Varying the prompt is what breaks the deterministic
+// empty-output loop: an identical retry reproduces it.
+export const PLAN_RETRY_NO_TEXT_NUDGE = "Your previous response contained only internal reasoning and produced no plan text. " +
+    "Do not repeat your reasoning. Output the plan content directly as text now, " +
+    "beginning immediately with the plan.";
+const PLAN_GENERATION_PROMPT = `
+${EXIT_PLAN_MODE_PLAN_GENERATION_PROMPT_PREFIX}
+
+IMPORTANT: You MUST output a plan. Even for trivial tasks, provide a brief plan describing what will be done.
+
+Always output the plan as visible text. The plan content itself must appear in your response.
+
+The plan title has been generated separately. DO NOT output a title - begin directly with the plan content.
+
+There are five levels of complexity:
+1. Extra Small: For trivial changes like updating a color, text, or single property.
+2. Small: For small tweaks and bug fixes, such as changing a filter or fixing a component bug.
+3. Medium: For moderate features or enhancements, such as adding a new data-driven component to a page.
+4. Large: For significant features or multi-part tasks, such as creating or overhauling a page and associated components and APIs.
+5. Extra Large: For major projects or overhauls, such as building a new application section with multiple pages, components, and backend services.
+
+The character limits for each complexity level are defined below. Shorter is always better.
+
+Use bullets.
+
+Focus on WHAT to build, not HOW to build it. Focus mainly on functional requirements and only very high-level implementation details.
+Assume the user is non-technical and avoid technical jargon. They only care about what the final outcome will be in terms of functionality and design.
+
+Format your response in markdown with clear sections.
+
+Here are some examples of tasks and plans at each complexity level.
+
+Extra Small - (MAX 150 Characters)
+<task>
+Make the header text red
+</task>
+
+<plan>
+Change the header text color to red.
+</plan>
+
+Small - (MAX 500 Characters)
+<task>
+Move the search bar into the header
+</task>
+
+<plan>
+Move the search input into the header beside the filter dropdown to fix misalignment and improve visual consistency.
+
+Requirements
+- Vertically center and maintain balanced padding
+- Stay responsive across screen sizes and window resize
+- Avoid any visual or layout regressions across the app
+</plan>
+
+Medium - (MAX 700 Characters)
+<task>
+Add a filter that gets the dropdown with values from @demoOrders in postgres
+</task>
+
+<plan>
+Add a dynamic Order Status filter that retrieves live values from @demoOrders in Postgres. The filter should let users easily view orders by status, updating results instantly without reloading the page.
+
+Requirements
+- Display unique ORDER_STATUS values from @demoOrders
+- Include a default "All" option showing all orders
+- Selecting a status filters the table results immediately
+- Automatically update if new statuses are added to the dataset
+</plan>
+
+Large - (MAX 900 Characters)
+<task>
+Add a page with data from @demoOrders to display orders in a searchable table.
+</task>
+
+<plan>
+Build an interactive Orders page connected to @demoOrders in Postgres. It should display live order data in a searchable, paginated table where users can type in the search bar to instantly filter results without pressing Enter or reloading the page.
+
+Layout & Data
+- Show a paginated table with columns Order ID, Customer Name, Status, Amount, and Date
+- Load data directly from @demoOrders, defaulting to all orders on initial load
+
+Search Behavior
+- Filter by Order ID, Customer Name, or Status, updating results dynamically on each keystroke with debounce
+- Provide loading feedback while searching and display a clear "No results found" message when no matches exist
+</plan>
+
+Extra Large - (MAX 1100 Characters)
+<task>
+Build a dashboard with data from @demoOrders. Should have a searchable, paginated table with all orders. Clicking an order should bring you to an orders detail page where full order details are displayed.
+</task>
+
+<plan>
+Build a two-page Orders experience backed by @demoOrders in Postgres. The first page lists all orders in a searchable, paginated table. The second displays full order details when a row is clicked, enabling smooth navigation between list and detail views.
+
+Orders List & Search
+- Show a paginated table with columns Order ID, Customer Name, Status, Amount, and Date
+- Add a search bar that filters by Order ID, Customer Name, or Status with instant updates
+- Trigger on keystroke with debounce and show loading feedback
+- Default view shows all orders
+
+Order Detail Page
+- Clicking a row opens a new page showing Order ID, Customer Info, Items, Status, Amounts, and Dates
+- Include a back button that returns to the list while preserving search, pagination, and selection
+
+Navigation & Behavior
+- Use Order ID for navigation (/order/1234)
+- Preserve state and scroll position between pages
+- Match dashboard styling and layout
+</plan>
+`;
+const EXIT_PLAN_MODE_DESCRIPTION_INTRO = `
+Use this tool to delegate to a planning expert who will generate a plan and present it to the user.
+This tool presents a plan with a "Build It" button that allows the user to switch to Build mode.
+NEVER output a plan directly as text - ALWAYS use this tool to present plans properly.
+
+IMPORTANT: Only use this tool AFTER you have gathered enough information to create a specific plan.
+
+ATTACHMENTS:
+- IMPORTANT: If the user has uploaded attachments (images, PDFs, CSV, JSON, etc.) at some point in the conversation, call listAttachments first to see available attachment IDs with their types, labels and insights
+- Pass relevant attachmentIds to include attachments in the plan (max ${MAX_PLAN_ATTACHMENTS})
+- Only include attachments that contain information essential for implementation (UI mockups, data schemas, requirements, etc.)
+
+ENTITIES:
+- If there are focused_entities in the context (components selected by the user), extract the "id" field from each entity
+- Pass these IDs to the entityIds parameter - they will be displayed in the plan and preserved for build mode
+- Include the relevant focused entity IDs unless they are clearly irrelevant to the plan
+`;
+const EXIT_PLAN_MODE_DATABASE_SECTION = `
+DATABASE:
+- Set includesFreshDatabase to true ONLY when the plan explicitly calls the provisionDatabase tool to create a new dev database
+- Do NOT set includesFreshDatabase for plans that merely query, migrate, or modify an existing database
+- This shows a "Fresh Database" indicator on the plan card so the user knows a new database will be created
+`;
+const EXIT_PLAN_MODE_DESCRIPTION_OUTRO = `
+Before presenting a plan:
+- If the user's request is ambiguous or has multiple interpretations, use askMultiChoice to clarify
+- If there are unknowns about requirements, preferences, or approach, use askMultiChoice first
+- If design decisions need to be made, ask the user for their preferences first
+- Gather enough context to create a concrete, specific plan
+- IMPORTANT: Check metadata for relevant integrations to validate feasibility and inform the plan
+- IMPORTANT: Validate that required data is available via integrations using the executeRequestToIntegration tool if needed
+  - eg. if the user wants to display data in a certain way, ensure the integration can support that
+  - eg. if the user wants to join data from two sources, ensure that there is a common key available that has overlap
+  - eg. if metadata is insufficient to validate feasibility, use executeRequestToIntegration to fetch sample data for validation
+  - at minimum, if plan can be validated via metadata alone, just make a test call to confirm availability
+
+When to use this tool:
+- You are in Plan mode
+- You have a clear understanding of the user's requirements
+- You have resolved any ambiguities through askMultiChoice
+- You have asked at least 3 clarifying questions
+- You have checked relevant integration metadata to inform the plan
+- You have validated feasibility via executeRequestToIntegration
+
+When NOT to use:
+- When there are still unknowns or ambiguities - use askMultiChoice instead
+- When you haven't asked at least 3 clarifying questions
+- For research tasks (gathering information, searching files, understanding codebase)
+- When answering questions without a coding plan
+- When you're already in Build mode
+- When you haven't checked relevant integration metadata
+- When you have not validated feasibility via metadata and possibly executeRequestToIntegration
+- When the task is purely a research or informational request with no code changes needed
+
+You must provide an estimate of the plan complexity when calling this tool.
+There are 5 levels of complexity:
+1. Extra Small: For really small tweaks and bug fixes, like changing a component property or fixing a typo.
+2. Small: For small tweaks and bug fixes, such as changing a filter or fixing a component bug.
+3. Medium: For moderate features or enhancements, such as adding a new data-driven component to a page.
+4. Large: For significant features or multi-part tasks, such as creating or overhauling a page and associated components and APIs.
+5. Extra Large: For major projects or overhauls, such as building a new application section with multiple pages, components, and backend services.
+
+After calling this tool, the user will either:
+- Click "Build It" to switch to Build mode and execute the plan
+- Provide feedback to refine the plan further
+
+Remember: Always use this tool to present plans - never output plans directly as text.
+IF THE TOOL CALL FAILS, DO NOT ATTEMPT TO GENERATE THE PLAN YOURSELF. Call the tool again.
+`;
+/**
+ * Build the tool description, conditionally including the DATABASE section
+ * only when managed Native DB is available for Clark.
+ */
+function buildExitPlanModeDescription(managedNativeDbAvailable) {
+    if (managedNativeDbAvailable) {
+        return (EXIT_PLAN_MODE_DESCRIPTION_INTRO +
+            EXIT_PLAN_MODE_DATABASE_SECTION +
+            EXIT_PLAN_MODE_DESCRIPTION_OUTRO);
+    }
+    return EXIT_PLAN_MODE_DESCRIPTION_INTRO + EXIT_PLAN_MODE_DESCRIPTION_OUTRO;
+}
+//# sourceMappingURL=exit-plan-mode.js.map