@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.84af65cd215b6ca1

package/dist/ai-service/state-machine/clark-fsm.d.ts

@@ -1,13 +1,40 @@
-import type { AiServiceConfig, AiServiceEvents, AnthropicError, ArtifactProcessor, FileArtifact } from "../types.js";
-import type { FSM, FSMOnTransitionParams } from "./fsm.js";
+import type { LanguageModelV3 } from "@ai-sdk/provider";
+import type { FinishReason } from "ai";
+import type { ViteDevServer } from "vite";
+import type { AiGenerateRequest, LLMProviderConfig, PromptContextIntegration, PromptContext, PromptContextEntity, KnowledgePromotionCapabilities, RememberKnowledgeCandidate, RuntimeErrorData, AiMode, PlanContext, AiChatMessage, AiGenerationStateSnapshot, AiToolPermission, ClarkUserPreferences, BrowserContext, ConsoleLogEntry, ApiRunRecord, KnowledgeSaveOutcome } from "@superblocksteam/library-shared/types";
+import type { AiPromptCostUsageEntry, AiQuotaPaywallReason, TracedEventEmitter } from "@superblocksteam/shared";
+import type { GitService } from "../../git-service/index.js";
 import type { OperationQueue } from "../../util/operation-queue.js";
+import type { EntityPermissionStore } from "../agent/tools2/entity-permissions.js";
+import type { ToolRegistry } from "../agent/tools2/registry.js";
+import type { AccessControlContext, Tool } from "../agent/tools2/types.js";
+import type { FileSystemInterface } from "../app-interface/file-system-interface.js";
+import type { NpmPackageLookup } from "../app-interface/npm-package-lookup.js";
 import type { AppShell } from "../app-interface/shell.js";
-import type { TemplateRenderer } from "../eval/template-renderer.js";
-import type { AnthropicProvider } from "@ai-sdk/anthropic";
-import type { AiGenerateRequest, EditorClientMethods } from "@superblocksteam/library-shared/types";
-import type { ISocketClient } from "@superblocksteam/shared";
-import type { FinishReason } from "ai";
-import type { EventEmitter } from "node:events";
+import type { ChatSessionStore } from "../chat/chat-session-store.js";
+import type { AppContextStore } from "../context/app-context.js";
+import type { AiServiceFeatureFlags } from "../features.js";
+import type { IntegrationStore } from "../integrations/store.js";
+import type { KnowledgeManager } from "../knowledge/knowledge-manager.js";
+import type { ChaosOptions } from "../llm/chaos-fetch.js";
+import type { LLMClient, LLMClientStreamTextOptions } from "../llm/client.js";
+import type { ContextManagerV2 } from "../llm/context-v2/manager.js";
+import type { LLMProviderError } from "../llm/error.js";
+import type { StreamTextResult } from "../llm/interaction/provider.js";
+import type { LLMProvider } from "../llm/types.js";
+import type { LLMObsNamedSpanOptions } from "../llmobs/index.js";
+import type { PlaywrightMcpServerManager } from "../mcp/playwright-server.js";
+import type { ClarkProfiler } from "../profiler/clark-profiler.js";
+import type { PromptInterpretTask } from "../prompt-builder-service/classifiers/prompt-interpret-task.js";
+import type { RecordingManager } from "../recording/index.js";
+import type { TaskStore } from "../tasks/task-store.js";
+import type { TemplateRenderer } from "../template-renderer.js";
+import type { AiServiceConfig, AiServiceEvents, AiInputSource, ChangeInfo, EditorClient, FileArtifact, UserChange } from "../types.js";
+import type { CallablePeer } from "../util/call-peer.js";
+import type { FSMOnTransitionParams, FSMTransitionHandlerFactory } from "./fsm.js";
+import type { PromptFailure } from "./helpers/prompt-failure.js";
+import type { ReconnectablePeer } from "./helpers/stable-peer.js";
+import { TracedFSM, type Tags, type TracedFSMStateSpanOptions, type TracedFSMTagProviderFactory } from "./traced-fsm.js";
 declare const $: {
     readonly Idle: "Idle";
     readonly AgentPlanning: "AgentPlanning";
@@ -35,6 +62,7 @@ export declare const AGENT_PLANNED = "agentPlanned";
 export declare const AGENT_REPORTED_ERROR_TO_USER = "agentReportedErrorToUser";
 export declare const AGENT_NEEDS_USER_INPUT = "agentNeedsUserInput";
 export declare const AGENT_GAVE_UP = "agentGaveUp";
+export declare const AGENT_CANCELED = "agentCanceled";
 export declare const LLM_REQUESTED_CONTEXT = "llmRequestedContext";
 export declare const LLM_FINISHED_UNEXPECTEDLY = "llmFinishedUnexpectedly";
 export declare const LLM_ERRORED = "llmErrored";
@@ -46,29 +74,69 @@ export declare const APP_RUNTIME_UPDATED_WITHOUT_EDITS = "appRuntimeUpdatedWitho
 export declare const RUNTIME_REVIEW_ERRORED = "runtimeReviewErrored";
 export declare const BUILD_SYSTEM_ERRORED = "buildSystemErrored";
 export declare const SERVICE_STARTED_WITH_DRAFT = "serviceStartedWithDraft";
+export declare const V3_AGENT_FINISHED = "v3AgentFinished";
 export type ClarkEvent = {
     type: typeof USER_SENT_PROMPT;
     request: AiGenerateRequest;
-    peer: ISocketClient<EditorClientMethods>;
+    inputSource?: AiInputSource;
+    /**
+     * When true, the turn runs through the FSM normally but does NOT
+     * persist the user prompt to the chat session store or surface it
+     * in the UI chat pane. Used for system-initiated turns (e.g. the
+     * post-flip v2→v3 migration turn) where the "user" is the
+     * ai-service itself.
+     */
+    internal?: boolean;
+    /**
+     * When true, persist and surface the prompt in chat history even when
+     * the turn is internal. This is used by system-initiated prompts that we
+     * still want users to see (for example, migration bootstrap prompts).
+     */
+    visibleInChatHistory?: boolean;
 } | {
     type: typeof USER_ACCEPTED_DRAFT;
+    silently?: boolean;
 } | {
     type: typeof USER_REJECTED_DRAFT;
+    silently?: boolean;
 } | {
     type: typeof USER_CANCELED;
+    failure?: PromptFailure;
 } | {
     type: typeof AGENT_PLANNED;
-    systemPrompt: string;
     userPrompt: string;
+    promptContext?: PromptContext;
     debugging?: boolean;
+    /** True if this is an original user prompt (not a response to interactive message). Defaults to true. */
+    isUserPrompt?: boolean;
+    /**
+     * Classify this text instead of the model-visible prompt. Resume turns
+     * use the raw user input here so synthetic coaching does not look like
+     * prompt injection. Secret redaction still covers both values.
+     */
+    safetyClassificationInput?: string;
+    knowledgeMessageId?: string;
 } | {
     type: typeof AGENT_REPORTED_ERROR_TO_USER;
     error: Error;
 } | {
     type: typeof AGENT_NEEDS_USER_INPUT;
-    advice: string;
+    advice?: string;
+    /** True when Clark is genuinely paused waiting for the user (plan approval, permissions, etc.). */
+    countsAsPromptSuccess?: boolean;
+    /**
+     * True when this handoff *ends* the turn (knowledge approval). Mid-turn
+     * pauses omit it so a real failure streak survives until a later
+     * streak-eligible success (ENG-5477).
+     */
+    clearsFailureStreak?: boolean;
 } | {
     type: typeof AGENT_GAVE_UP;
+} | {
+    type: typeof AGENT_CANCELED;
+    advice?: string;
+    failure: PromptFailure;
+    paywallReason?: AiQuotaPaywallReason;
 } | {
     type: typeof LLM_REQUESTED_CONTEXT;
     prompt: string;
@@ -77,9 +145,7 @@ export type ClarkEvent = {
     finishReason: FinishReason;
 } | {
     type: typeof LLM_ERRORED;
-    error: AnthropicError | {
-        type: "unknown";
-    };
+    error: LLMProviderError;
 } | {
     type: typeof LLM_FINISHED;
     files: FileArtifact[];
@@ -96,21 +162,28 @@ export type ClarkEvent = {
 } | {
     type: typeof RUNTIME_REVIEW_ERRORED;
     tsErrorsByPath: Record<string, string[]>;
+    lintErrorsByPath: Record<string, string[]>;
+    integrationErrorsByPath: Record<string, string[]>;
 } | {
     type: typeof BUILD_SYSTEM_ERRORED;
     error: Error;
 } | {
     type: typeof SERVICE_STARTED_WITH_DRAFT;
+} | {
+    type: typeof V3_AGENT_FINISHED;
 };
 export declare const transitions: {
     readonly Idle: {
         readonly userSentPrompt: "AgentPlanning";
         readonly serviceStartedWithDraft: "AwaitingUser";
+        readonly appRuntimeUpdatedWithoutEdits: "Idle";
     };
     readonly AgentPlanning: {
         readonly agentPlanned: "LLMGenerating";
         readonly agentNeedsUserInput: "AwaitingUser";
+        readonly v3AgentFinished: "AwaitingUser";
         readonly agentGaveUp: "Dead";
+        readonly agentCanceled: "Idle";
         readonly userCanceled: "Idle";
     };
     readonly LLMGenerating: {
@@ -120,11 +193,17 @@ export declare const transitions: {
         readonly llmRequestedContext: "AgentPlanning";
         readonly appRuntimeUpdatedWithoutEdits: "Idle";
         readonly userCanceled: "Idle";
+        readonly agentCanceled: "Idle";
+        readonly postProcessingErrored: "AgentPlanning";
+        readonly v3AgentFinished: "AwaitingUser";
+        readonly agentNeedsUserInput: "AwaitingUser";
     };
     readonly PostProcessing: {
         readonly postProcessingFinished: "RuntimeReviewing";
         readonly postProcessingErrored: "AgentPlanning";
         readonly userCanceled: "Idle";
+        readonly agentCanceled: "Idle";
+        readonly appRuntimeUpdatedWithoutEdits: "Idle";
     };
     readonly RuntimeReviewing: {
         readonly runtimeReviewErrored: "AgentPlanning";
@@ -132,12 +211,14 @@ export declare const transitions: {
         readonly runtimeReviewFinished: "AwaitingUser";
         readonly appRuntimeUpdatedWithoutEdits: "Idle";
         readonly userCanceled: "Idle";
+        readonly agentCanceled: "Idle";
     };
     readonly AwaitingUser: {
         readonly userAcceptedDraft: "Idle";
         readonly userRejectedDraft: "RuntimeReviewing";
         readonly userSentPrompt: "AgentPlanning";
         readonly userCanceled: "Idle";
+        readonly agentCanceled: "Idle";
     };
     readonly Dead: {};
 };
@@ -147,8 +228,75 @@ export type $LLMGenerating = typeof $.LLMGenerating;
 export type $AwaitingUser = typeof $.AwaitingUser;
 export type $PostProcessing = typeof $.PostProcessing;
 export type $RuntimeReviewing = typeof $.RuntimeReviewing;
-export type $Dead = typeof $.Dead;
-export type Clark = FSM<ClarkState, ClarkEvent, ClarkContext>;
+export type ClarkTransitionHandlerFactory = FSMTransitionHandlerFactory<ClarkState, ClarkEvent>;
+export type ClarkTagProviderFactory = TracedFSMTagProviderFactory<ClarkState, ClarkEvent, ClarkContext>;
+export declare class Clark extends TracedFSM<ClarkState, ClarkEvent, ClarkContext> {
+    constructor(config: {
+        initialContext: ClarkContext;
+        createTransitionHandler: ClarkTransitionHandlerFactory;
+        sessionId?: string;
+        createTagProvider?: ClarkTagProviderFactory;
+    });
+    getAccessControl(flags: AiServiceFeatureFlags): AccessControlContext;
+    resetContext(): void;
+    protected getRootSpanOptions(_initialEvent: ClarkEvent): LLMObsNamedSpanOptions;
+    protected getStateSpanOptions(state: ClarkState): TracedFSMStateSpanOptions;
+    protected sanitizeEvent(event: ClarkEvent): Partial<ClarkEvent>;
+    protected getRootSpanFinishTags(params: FSMOnTransitionParams<ClarkState, ClarkEvent>): Tags;
+    /**
+     * High-level streamText interface with middleware support.
+     *
+     * Automatically composes:
+     * - Context management (acquires lock, manages conversation history)
+     * - Logging middleware (logs full conversation to artifact)
+     * - LLMObs middleware (tracing and observability)
+     *
+     * Only `user` message is required - all other options have smart defaults.
+     *
+     * @param services - Service dependencies (contextManager, profiler, etc.)
+     * @param options - Stream options including model, user message, tools, etc.
+     * @returns Promise resolving to stream result
+     *
+     * @example
+     * ```typescript
+     * // Minimal usage - only user message required
+     * const result = await clark.streamText(services, {
+     *   user: { role: "user", content: "Hello!" }
+     * });
+     *
+     * // With overrides
+     * const result = await clark.streamText(services, {
+     *   user: { role: "user", content: userPrompt },
+     *   model: myCustomModel,
+     *   system: systemPrompt,
+     *   tools: actualTools,
+     *   context: { contextOptions: { maxTokens: 150000 } },
+     *   logging: { conversationId: "custom-id" }
+     * });
+     * ```
+     */
+    streamText<TOOLS extends Record<string, Tool>>(services: ClarkStateHandlerParams, options: ClarkStreamTextOptions<TOOLS>): Promise<StreamTextResult<TOOLS>>;
+    private static readonly PLACEHOLDER_USAGE;
+    /**
+     * Record a system message into the conversation. Writes to:
+     * - ChatSessionStore (server persistence + live UI socket push)
+     * - ContextV2 (LLM conversation history)
+     *
+     * The message is formatted as `[label] content` so system messages are
+     * recognizable in traces and context dumps. It uses the
+     * `system_notification` type, which the UI hides by default.
+     *
+     * Use this when something happens outside of streaming that the LLM
+     * needs to know about on the next turn (e.g., knowledge approval
+     * outcomes, tool permission results, plan decisions).
+     *
+     * @param services - Active Clark session services (chat store, context manager)
+     * @param label - Short category tag, e.g. "Knowledge update"
+     * @param content - Human-readable description of what happened
+     */
+    recordSystemMessage(services: Pick<ClarkStateHandlerParams, "chatSessionStore" | "contextManagerV2" | "applicationId">, label: string, content: string): Promise<void>;
+    private pushContextUsed;
+}
 export type ClarkTransition = FSMOnTransitionParams<ClarkState, ClarkEvent>;
 export type ClarkStateHandlerFactory = (clark: Clark, params: ClarkStateHandlerParams) => (transition: ClarkTransition) => Promise<void>;
 export type ClarkStateHandlerFactories = {
@@ -159,19 +307,417 @@ export type ValidEventsForState<S extends ClarkState> = keyof (typeof transition
         type: K;
     }>;
 }[keyof (typeof transitions)[S]];
+/**
+ * Consolidated state for API testing lifecycle.
+ *
+ * An API moves between sets as events occur:
+ *   buildApi succeeds  → untested
+ *   testApi succeeds   → passed  (removed from untested/failed)
+ *   testApi fails      → failed  (removed from untested/passed)
+ *   buildApi rebuilds  → untested (removed from failed/passed)
+ *   deleteFile         → removed from all sets
+ */
+export interface ApiTestingState {
+    /** APIs built in this session that have never had testApi called */
+    untested: Set<string>;
+    /** APIs where testApi ran and returned errors */
+    failed: Set<string>;
+    /** APIs where testApi ran successfully */
+    passed: Set<string>;
+    /** APIs where the user denied the testApi permission prompt.
+     *  Prevents markSdkApiAsUntestedIfNeeded from re-adding these APIs
+     *  to `untested` when files are rewritten after a denial (APPS-2717).
+     *
+     *  Note: if `onCall` fires but the session aborts before the permission
+     *  prompt resolves (e.g. user cancels the Clark session), the API stays
+     *  in `denied` for the remainder of the session. This is a conservative
+     *  failure — the API simply won't be re-tested — and is acceptable
+     *  because a new session starts with a fresh `apiTestingState`. */
+    denied: Set<string>;
+}
+/**
+ * Which part of the build produced a build system error, for the producers that
+ * know what they were doing when it failed. This is a causal claim, not just a
+ * label: `transform` and `resolve` are failures in our own source, while
+ * `import` is the browser failing to load a module, which is usually downstream
+ * of one of the others. Errors that reach us through Vite's shared logger carry
+ * no phase, because that path is a catch-all we cannot attribute.
+ */
+export type BuildErrorPhase = "transform" | "resolve" | "import";
+/** A build system error augmented with capture metadata. */
+export type BuildSystemError = Error & {
+    timestamp?: number;
+    phase?: BuildErrorPhase;
+};
 export type ClarkContext = {
-    peer?: ISocketClient<EditorClientMethods>;
+    /**
+     * The editor peer RPC client. This is a permanent `StablePeer` proxy
+     * installed at Clark construction time; its inner WebSocket client is
+     * swapped on reconnect via `StablePeer.setInner(...)`. The reference on
+     * the context itself NEVER changes — do not reassign it via
+     * `updateContext({ peer })`. Callers can cache this reference freely and
+     * trust that `peer.call.*` routes to the currently-live socket (or queues
+     * transparently during the reconnect window).
+     *
+     * The peer's identity token (`peerId`) lives on the proxy itself; read it
+     * via `stablePeer.peerId` rather than tracking a separate context field.
+     *
+     * Typed as `ReconnectablePeer` too because the proxy always exposes the
+     * reconnect controls (`connectionGeneration`/`whenConnectedAfter`/
+     * `invalidateConnection`) that operation-level retry helpers depend on.
+     */
+    peer: CallablePeer & EditorClient & ReconnectablePeer & {
+        pushMessageToObservers(message: AiChatMessage, inputSource: AiInputSource | undefined, options?: {
+            includeInputPeer?: boolean;
+        }): void;
+    };
     hasSuggestions?: boolean;
-    summaryMessages?: string[];
+    /**
+     * Set when the previous run terminated via the mid-prompt quota gate
+     * (`AGENT_CANCELED` with a `paywallReason`). The next `USER_SENT_PROMPT`
+     * reads this and prepends a synthetic resume hint to the user's prompt
+     * so the model picks up from the prior tool results instead of asking
+     * clarifying questions, then clears the flag. See APPS-4080
+     * "resume-quality hardening" follow-up.
+     */
+    pausedForCreditsReason?: AiQuotaPaywallReason;
+    /**
+     * Set alongside `pausedForCreditsReason` when the failed turn was a
+     * response to a multi-choice question. The resume hint in `USER_SENT_PROMPT`
+     * uses these fields to re-state the original question and the user's
+     * specific selection so the model honors it instead of drifting to a
+     * different default. Without this, the model has been observed to
+     * re-decide the open question on its own (e.g. picking "Use sample data"
+     * after the user clicked "Connect a database"). See APPS-4080
+     * "resume-quality hardening — multi-choice variant".
+     */
+    pausedForCreditsMultiChoiceContext?: {
+        /** The original question from the multi_choice message. */
+        question: string;
+        /** Texts the user actually selected (empty if they typed free text). */
+        selectedChoiceTexts: string[];
+        /** Free-text response, if the user typed instead of selecting. */
+        userText?: string;
+    };
+    /**
+     * Set when the previous run was cut short because Clark's own session
+     * credential stopped working mid-stream. The next `USER_SENT_PROMPT` asks
+     * the model to carry on from where it stopped rather than re-planning the
+     * whole task, then clears the flag. The user recovers the credential by
+     * refreshing the page, which is what the terminal message already tells
+     * them to do.
+     */
+    resumeAfterAuthFailure?: boolean;
+    /**
+     * Captures the most recent `multi_choice_response` request in flight, so
+     * that if the LLM call fails with a paywall, `LLM_ERRORED` can promote
+     * this into `pausedForCreditsMultiChoiceContext` for the next turn's
+     * resume hint. Overwritten at the start of every `USER_SENT_PROMPT`
+     * (set to `undefined` for non-multi-choice prompts).
+     */
+    lastTurnMultiChoiceContext?: {
+        question: string;
+        selectedChoiceTexts: string[];
+        userText?: string;
+    };
+    summaryMessages?: {
+        role: "user" | "assistant";
+        isDebugging: boolean;
+        content: string;
+    }[];
     abortController?: AbortController;
+    initialElementIds?: string[];
+    initialFilePaths?: {
+        apis: string[];
+        components: string[];
+    };
+    generatedChangeInfo?: Record<string, ChangeInfo>;
+    peerChannelQueue?: OperationQueue;
+    usedDebugging?: boolean;
+    runTimestamp?: string;
+    jwt?: string;
+    promptId?: string;
+    /** Aligns pre-FSM and FSM outcome dedupe with requestId when present. */
+    promptOutcomeDedupeKey?: string;
+    /**
+     * Set when a genuine user-wait handoff records prompt success. Used to
+     * attribute post-handoff cancel/dismiss telemetry without overwriting the
+     * handoff outcome.
+     */
+    awaitingUserHandoffRecorded?: boolean;
+    /** promptId at handoff time; survives handleAiGenerate assigning a new id. */
+    awaitingUserHandoffPromptId?: string;
+    usageMetadata?: Record<string, unknown>;
+    chatmessageId?: string;
+    /**
+     * The non-draft commit (checkpoint) the app was based on -- i.e. already
+     * on -- when the current prompt started, NOT the checkpoint the work
+     * produces. Stamped into LLM usage metadata so the read side can attribute
+     * the spend of the interval that starts here forward to whatever
+     * checkpoint the next accept creates. Set alongside promptId so their
+     * lifetimes match.
+     */
+    baseCommitId?: string;
+    availableIntegrations?: PromptContextIntegration[];
+    knowledgePromotionCapabilities?: KnowledgePromotionCapabilities;
+    promptInterpretTask?: PromptInterpretTask;
+    debugToolCalled?: boolean;
+    lastDebugTimestamp?: number;
+    lastDebugHadTypeErrors?: boolean;
+    lastFileModificationTime?: number;
+    debugAttemptCount?: number;
+    useMockGeneration?: boolean;
+    buildSystemErrors?: BuildSystemError[];
+    runtimeErrors?: RuntimeErrorData[];
+    consoleLogs?: ConsoleLogEntry[];
+    apiRunRecords?: Array<ApiRunRecord & {
+        apiId: string;
+        _size?: number;
+    }>;
+    requiredFileReads?: Set<string>;
+    checklist?: {
+        items: {
+            id: string;
+            content: string;
+            status: "pending" | "in_progress" | "completed" | "cancelled" | "failed";
+            createdAt: string;
+            updatedAt?: string;
+            /** Populated only when status === "failed". */
+            failureReason?: string;
+        }[];
+        lastUpdated: string;
+    };
+    llmConfig?: LLMProviderConfig;
+    traceHeaders?: {
+        traceparent?: string;
+        tracestate?: string;
+    };
+    usedCacheBreakpoints?: Record<string, number>;
+    currentMode?: AiMode;
+    planContext?: PlanContext;
+    /**
+     * Plan-generation variant of the turn's system prompt (same builder inputs
+     * as the agent prompt, minus the tool-workflow sections). Rebuilt by the
+     * agent loop each turn; exitPlanMode passes it as `system` on the nested
+     * tool-less plan stream so the seeded agent prompt — which instructs the
+     * model to present plans via a tool — never reaches that stream.
+     */
+    planGenerationSystemPrompt?: string;
+    taggedEntities?: PromptContextEntity[];
+    chaosOptions?: ChaosOptions;
+    retryCount?: number;
+    workflowFailed?: boolean;
+    workflowMetrics?: {
+        toolCallCount: number;
+        stepCount: number;
+        linesAdded: number;
+        linesEdited: number;
+        linesRemoved: number;
+        llmUsage: AiPromptCostUsageEntry[];
+        llmCallCount: number;
+        workflowStartedAt?: string;
+        hadProviderFallback?: boolean;
+        peakContextUsed?: number;
+        minHeadroomTokens?: number;
+    };
+    planSize?: "small" | "medium" | "large" | "extra large";
+    /**
+     * The last state pushed, replayed on reconnect by `handleUserConnected`.
+     *
+     * Held as the wire type itself so the replay cannot drift from what a live
+     * push carries. It used to be a hand-kept copy, and every field the wire
+     * gained had to be remembered here too — APPS-4080 was `hasError` and
+     * `paywallReason` going missing from the replay, which lost a credit
+     * paywall across a reconnect.
+     */
+    lastGenerationState?: AiGenerationStateSnapshot;
+    activeInteractiveMessage?: {
+        id: string;
+        payload: AiChatMessage;
+        /**
+         * Set by `sendInteractiveMessageChannel` after a successful peer
+         * push. Distinguishes prompts that are genuinely in flight (waiting
+         * on the user) from stale guards left behind by a lifecycle path
+         * that did not clear `activeInteractiveMessage`. The channel uses
+         * this to auto-recover from stale state instead of silently
+         * dropping the next interactive tool call.
+         */
+        deliveredViaChannel?: boolean;
+    };
+    /**
+     * User-controlled Clark preferences for the current prompt cycle. Populated
+     * from {@link AiGenerateRequest.userPreferences} in `handleAiGenerate`; read
+     * with `resolveUserPreferences(context.userPreferences)` so callers always
+     * see a fully-populated object with defaults applied.
+     */
+    userPreferences?: Partial<ClarkUserPreferences>;
+    deferredInteractiveMessage?: {
+        payload: AiChatMessage;
+    };
+    lastMigrationUnresolvedSnapshotKey?: string;
+    /** Tracks integration action prompt sent after opening setup so responses can be handled deterministically */
+    pendingIntegrationActionPrompt?: {
+        messageId: string;
+    };
+    /**
+     * Packages that CVE-blocked while named in the builder's own message. Only
+     * these may proceed past the block via `build_installPackages`'
+     * `proceedWithReason`. Survives `resetContext` because the builder answers
+     * the "do you still want it?" question on a later turn, and that reply
+     * (e.g. "yes, we need it for the demo") does not repeat the package name.
+     * Cleared once an override install is attempted.
+     */
+    pendingCveProceedPackages?: string[];
+    pendingToolPermissionRequest?: {
+        messageId: string;
+        toolName: string;
+        delivery: {
+            status: "awaiting_ack";
+            generation: number;
+        } | {
+            status: "parked";
+            expiresAtMs: number;
+            generation: number;
+            failure: {
+                kind: "timeout";
+            } | {
+                kind: "peer_unavailable";
+                message: string;
+            } | {
+                kind: "rpc_error";
+                message: string;
+            };
+        } | {
+            status: "acked";
+            generation: number;
+        };
+        actionName?: {
+            future: string;
+            present: string;
+            past: string;
+        };
+        formattedInput?: {
+            targets: string[];
+            details?: string;
+            summary?: string;
+        };
+        rawInput: any;
+        permissions?: AiToolPermission[];
+        toolCallId?: string;
+        signature?: string;
+        /** Timestamp of the assistant message containing the tool call - used to truncate stale error on approval */
+        toolCallTimestamp?: number;
+    };
+    skippedToolPermissionRequests?: Set<string>;
+    userChanges?: UserChange[];
+    /** Consolidated API testing state tracking */
+    apiTestingState?: ApiTestingState;
+    /** Cached SDK API registry: API name → entry point path (parsed from server/apis/index.ts) */
+    sdkApiRegistryEntryPoints?: Map<string, string>;
+    /** Cached SDK API registry: API name → source export name (named imports only; parsed from server/apis/index.ts) */
+    sdkApiRegistryExportNames?: Map<string, string>;
+    /** APIs that failed to build - must be fixed and rebuilt before finalizing */
+    failedApiBuilds?: Set<string>;
+    /** Browser context for Playwright automation - contains iframe URL and init/bootstrap data */
+    browserContext?: BrowserContext;
+    /** Current test run ID */
+    currentTestRunId?: string;
+    /** Current test cases for the active test run */
+    currentTestCases?: Array<{
+        id: string;
+        name: string;
+        description?: string;
+    }>;
+    /** Tracked statuses of test cases (source of truth for reconciliation) */
+    testCaseStatuses?: Map<string, "not_started" | "running" | "passed" | "failed" | "skipped">;
+    /** Test case ID that should be skipped (set by user skip request) */
+    skipRequestedForTestCase?: string;
+    partialResponse?: {
+        text: string;
+        lastUpdatedAt: number;
+    };
+    interruptedPreviousGeneration?: boolean;
+    interruptOriginalPrompt?: string;
+    isInterruptAbort?: boolean;
+    /** Set before aborting the stream for explicit user cancel/interrupt. */
+    userInitiatedPromptAbort?: boolean;
+    /** Set to true when Clark calls the rememberKnowledge tool in the current turn */
+    explicitRememberKnowledgeIntentForTurn?: boolean;
+    /** Candidate knowledge entries staged by rememberKnowledge, awaiting user approval */
+    rememberKnowledgeCandidatesForTurn?: RememberKnowledgeCandidate[];
+    /** True only for turns where the user free-types while a knowledge approval is pending */
+    pendingKnowledgeFreeTextTurn?: boolean;
+    /** The active pending approval for app knowledge — contains the interactive message ID */
+    pendingAppKnowledge?: {
+        messageId: string;
+        knowledgeEntries: RememberKnowledgeCandidate[];
+    };
+    /** Recent outcomes from knowledge save actions to help avoid immediate duplicate suggestions */
+    recentKnowledgeSaveOutcomes?: KnowledgeSaveOutcome[];
 };
 export type ClarkStateHandlerParams = AiServiceConfig & {
-    fsOperationQueue: OperationQueue;
     templateRenderer: TemplateRenderer;
-    artifactProcessor: ArtifactProcessor;
-    anthropicProvider: AnthropicProvider;
     appShell: AppShell;
-    signals: EventEmitter<AiServiceEvents>;
+    /**
+     * Present only when this application is connected to a Git repository.
+     * Native Git feature availability alone does not imply a connection.
+     */
+    gitService?: GitService;
+    /**
+     * Process-lifetime `NpmPackageLookup` owned by the AiService. Reused across
+     * every `buildTools()` call so the `superblocks.npm.lookup.cache_size`
+     * `ObservableGauge` registers exactly once and the 60s TTL cache stays
+     * warm across LLM turns — see AiService's `npmPackageLookup` field for
+     * the OTel callback-leak rationale this replaces.
+     */
+    npmPackageLookup: NpmPackageLookup;
+    signals: TracedEventEmitter<AiServiceEvents>;
+    fileSystemInterface: FileSystemInterface;
+    integrationStore: IntegrationStore;
+    knowledgeManager: KnowledgeManager;
+    appContextStore: AppContextStore;
+    llmProvider: LLMProvider;
+    chatSessionStore: ChatSessionStore;
+    clarkProfiler: ClarkProfiler;
+    contextManagerV2: ContextManagerV2;
+    toolRegistry: ToolRegistry;
+    entityPermissionStore: EntityPermissionStore;
+    llmClient: LLMClient;
+    mcpServerManager: PlaywrightMcpServerManager;
+    onToolPermissionParked: (messageId: string) => void;
+    viteServer?: ViteDevServer;
+    recordingManager?: RecordingManager;
+    /**
+     * Per-session owner of background tasks (dev-DB provisioning today; Devin,
+     * CI, etc. future). Present only when `features.managedNativeDbEnabled`
+     * (the dev-DB feature rollout, since dev-DB provisioning is the only
+     * producer today) is on; stays `undefined` otherwise so the framework is
+     * invisible.
+     */
+    taskStore?: TaskStore;
+    /**
+     * Returns the current "owner" identity for any tool calls in this turn,
+     * used to stamp `ownerUserId` on background tasks at kickoff and to filter
+     * `listTasks` / gate `checkTask` / `waitForTask` / `cancelTask` to that
+     * caller. Returns `undefined` when no JWT-derived identity is available
+     * (anonymous reconnect, local dev), in which case stamped tasks remain
+     * accessible to anyone in the session — see `tasks/access.ts`.
+     *
+     * Only consumed by the four task tools today; wired through to
+     * `defineBackgroundTaskFactory` for kickoff stamping.
+     */
+    getCurrentOwnerId?: () => string | undefined;
 };
+/**
+ * Options for Clark.streamText().
+ *
+ * Extends StreamTextOptions with Clark-specific middleware configuration.
+ * Only `user` message is required - all other options have smart defaults.
+ * providerConfig and enableFallback are populated from Clark's context.llmConfig.
+ */
+interface ClarkStreamTextOptions<TOOLS extends Record<string, Tool>> extends Omit<LLMClientStreamTextOptions<TOOLS>, "model" | "providerConfig"> {
+    /** Language model to use. Defaults to services.llmProvider.modelForTask("generateBroadEdit"). */
+    model?: LanguageModelV3;
+}
 export {};
 //# sourceMappingURL=clark-fsm.d.ts.map