@superblocksteam/library-shared 1.99.99-next.3 → 2.0.0-SNAPSHOT.04704c19f32b3902

package/dist/types/ai.d.ts

@@ -0,0 +1,1721 @@
+import type { AiQuotaPaywallReason, AppEnvironmentCompatibility, FactDto, PluginType, Profile } from "@superblocksteam/shared";
+import type { InteractionMode, SbElement } from "./common.js";
+export type PreviewDevice = "desktop" | "mobile";
+export type EditorView = "code-viewer" | "git-setup" | "integration-setup" | "publish" | "preview";
+export type DataTag = Profile;
+export declare enum AiPermissionType {
+    READ = "read",
+    WRITE = "write",
+    DELETE = "delete"
+}
+export interface AiToolPermission {
+    entityType: AiEntityType;
+    entityId: string | undefined;
+    permissionType: AiPermissionType;
+}
+export declare enum AiEntityType {
+    COMPONENT = "component",
+    API = "api",
+    TIMER = "timer",
+    STATE_VARIABLE = "stateVariable",
+    INTEGRATION = "integration",
+    EVENT = "event",
+    THEME = "theme",
+    PAGE = "page",
+    PROFILE = "profile",
+    GROUP = "group",
+    USER = "user",
+    BLOCK = "block"
+}
+/**
+ * Serialized context entity for homepage prompt handoff (sessionStorage).
+ * Code-mode maps these to ContextEntity when building initialContextEntities.
+ */
+export type HomepageContextEntity = {
+    id: string;
+    type: AiEntityType;
+    name: string;
+    pluginId?: string;
+};
+interface AiChatMessageBase {
+    role: "user" | "assistant" | "system";
+    content: string;
+    type?: "text" | "reasoning" | "changeInfo" | "appGenerationDone" | "appGenerationCanceled" | "draftAccepted" | "draftRejected" | "draftCommitted" | "commitRestored" | "commitRestoring" | "sessionTerminated" | "control" | "clark" | "context" | "tool" | "tool-result" | "tool-error" | "text-delta" | "plan" | "plan-delta" | "confirm" | "confirm_response" | "multi_choice" | "multi_choice_response" | "searchable_dropdown" | "searchable_dropdown_response" | "remember_knowledge_draft" | "remember_knowledge_draft_response" | "plan_response" | "tool_permission_request" | "test_run_start" | "test_step" | "test_run_end" | "test_case_update" | "git_setup_required" | "knowledge" | "app_knowledge_saved" | "retry_notification" | "system_notification" | "error" | "next_steps" | "aws_infra_demo";
+    id?: string;
+    timestamp?: number;
+    group?: string;
+    action?: "create" | "edit" | "delete" | "transient";
+    status?: "pending" | "ready" | "error" | "validated" | "cancelled";
+    agentHeader?: string;
+    name?: string;
+    attachments?: Array<Attachment>;
+    mode?: AiMode;
+    authorEmail?: string | null;
+    authorName?: string | null;
+    title?: string;
+}
+type BaseToolCallChatMessage = AiChatMessageBase & {
+    type: "tool";
+    streaming?: boolean;
+    toolCallId?: string;
+    error?: string;
+    errorCode?: AiToolExecutionErrorCode;
+    errorSummary?: string;
+    output?: any;
+    signature?: string;
+    requiresUserPermission?: boolean;
+};
+type BuildCaptureScreenshotToolCallChatMessage = {
+    tool: "build_captureScreenshot";
+    args: undefined;
+    output?: {
+        screenshotFileName?: string;
+    };
+};
+type BuildNavigatePreviewToolCallChatMessage = {
+    tool: "build_navigatePreview";
+    args: {
+        hash?: string;
+        path: string;
+        queryParams?: Record<string, string>;
+        routeParams?: Record<string, string>;
+    };
+    output?: {
+        message?: string;
+        path?: string;
+        success?: boolean;
+    };
+};
+type BuildCopyToolOutput = {
+    copied?: string[];
+    copiedCount: number;
+    rejected?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    rejectedCount: number;
+    skipped?: Array<{
+        path: string;
+        reason: "destination_exists" | "default_excluded";
+    }>;
+    skippedCount: number;
+};
+type BuildCopyDirectoryToolCallChatMessage = {
+    tool: "build_copyDirectory";
+    args: {
+        conflictStrategy?: "fail" | "skip" | "replace";
+        destinationDir: string;
+        sourceDir: string;
+        verbose?: boolean;
+    };
+    output?: BuildCopyToolOutput;
+};
+type BuildCopyFileToolCallChatMessage = {
+    tool: "build_copyFile";
+    args: {
+        conflictStrategy?: "fail" | "skip" | "replace";
+        destinationPath: string;
+        sourcePath: string;
+        verbose?: boolean;
+    };
+    output?: BuildCopyToolOutput;
+};
+type BuildWriteFileToolCallChatMessage = {
+    tool: "build_writeFile";
+    args: {
+        filePath: string;
+        content: string;
+    };
+};
+type BuildEditFileToolCallChatMessage = {
+    tool: "build_editFile";
+    args: {
+        filePath: string;
+        oldString: string;
+        newString: string;
+        replaceAll?: boolean;
+    };
+};
+type BuildMultiEditFileToolCallChatMessage = {
+    tool: "build_multiEditFile";
+    args: {
+        filePath: string;
+        edits: Array<{
+            oldString: string;
+            newString: string;
+            replaceAll?: boolean;
+        }>;
+    };
+};
+type BuildDeleteFileToolCallChatMessage = {
+    tool: "build_deleteFile";
+    args: {
+        filePath: string;
+        reason?: string;
+    };
+};
+type BuildRenameFileToolCallChatMessage = {
+    tool: "build_renameFile";
+    args: {
+        oldPath: string;
+        newPath: string;
+    };
+};
+type BuildReadFilesToolCallChatMessage = {
+    tool: "build_readFiles";
+    args: {
+        filePaths: string[];
+    };
+};
+type BuildReadFileToolCallChatMessage = {
+    tool: "build_readFile";
+    args: {
+        filePath: string;
+        ranges?: Array<{
+            start: number;
+            end: number;
+        }>;
+    };
+};
+type BuildGenerateApiSourceToolCallChatMessage = {
+    tool: "build_generateApiSource";
+    args: {
+        apiName: string;
+        action: "create" | "edit";
+    };
+};
+type ReadIntegrationMetadataToolCallChatMessage = {
+    tool: "readIntegrationMetadata";
+    args: {
+        integrationName: string;
+    };
+};
+type FetchIntegrationToolCallChatMessage = {
+    tool: "fetchIntegration";
+    args: {
+        integrationName: string;
+    };
+};
+type WriteApiToolCallChatMessage = {
+    tool: "writeApi";
+    args: {
+        apiName: string;
+        apiSource: string;
+    };
+};
+type BuildApiToolCallChatMessage = {
+    tool: "buildApi";
+    args: {
+        apiName: string;
+    };
+};
+type TestApiToolCallChatMessage = {
+    tool: "testApi";
+    args: {
+        apiName: string;
+        inputs: Record<string, any>;
+    };
+};
+type SearchIntegrationsToolCallChatMessage = {
+    tool: "searchIntegrations";
+    args: {
+        type?: PluginType;
+        name?: string;
+    };
+};
+type ReadIntegrationMetadataForPromptToolCallChatMessage = {
+    tool: "readIntegrationMetadataForPrompt";
+    args: {
+        integrationNames: string[];
+    };
+};
+type GrepMetadataToolCallChatMessage = {
+    tool: "grepMetadata";
+    args: {
+        integrationId: string;
+        grepPattern: string;
+        limit?: number;
+        includeDetails?: boolean;
+        startIndex?: number;
+    };
+};
+type ExecuteRequestToIntegrationToolCallChatMessage = {
+    tool: "executeRequestToIntegration";
+    args: {
+        integrationId: string;
+        integrationName: string;
+        description?: {
+            request: string;
+            present: string;
+            past: string;
+        };
+        params?: {
+            type: "sql" | "graphql" | "rest" | "other" | "salesforce";
+            query?: string;
+            graphQLQuery?: {
+                query: string;
+                variables?: Record<string, unknown>;
+                headers?: Record<string, string>;
+            };
+            httpRequest?: {
+                path: string;
+                headers?: Record<string, string>;
+                queryParams?: Record<string, string>;
+            };
+            body?: string;
+        };
+    };
+};
+type RunCodeToolCallChatMessage = {
+    tool: "runCode";
+    args: {
+        integrationId: string;
+        integrationName: string;
+        script?: string;
+    };
+};
+type BuildInstallPackagesToolCallChatMessage = {
+    tool: "build_installPackages";
+    args?: {
+        packages?: Array<{
+            name: string;
+            version?: string;
+            dev?: boolean;
+        }>;
+        remove?: string[];
+    };
+};
+type BuildLookupNpmPackageToolCallChatMessage = {
+    tool: "build_lookupNpmPackage";
+    args?: {
+        name?: string;
+    };
+    output?: {
+        available?: boolean;
+        mode?: "private" | "public-npm" | "fail-closed";
+        reason?: "not_in_registry" | "registry_auth_failed" | "registry_unreachable";
+        registry_host?: string;
+        latest_version?: string;
+        recent_versions?: string[];
+    };
+};
+type SimpleToolCallChatMessage = {
+    tool: "build_manageChecklist" | "build_listFiles" | "build_debug" | "build_finalize" | "downloadAttachments" | "glob" | "grep" | "ls" | "getApiDocs" | "getIntegrationTypes" | "get_runtime_errors" | "get_console_logs" | "get_logs" | "clear_error_cache" | "listAttachments" | "exitPlanMode" | "closeIntegrationSetup" | "listAvailableIntegrationTypes" | "listTasks";
+    args: undefined;
+};
+type ProvisionDatabaseToolCallChatMessage = {
+    tool: "provisionDatabase";
+    args: {
+        requirement: {
+            logicalName: string;
+            migrationDirectory?: string;
+        };
+    };
+    output?: {
+        taskId: string;
+        label?: string;
+        state?: string;
+    };
+};
+type StartApplyDevDatabaseMigrationsToolCallChatMessage = {
+    tool: "startApplyDevDatabaseMigrations";
+    args: {
+        bindingKey?: string;
+    };
+    output?: {
+        taskId: string;
+        label?: string;
+        state?: string;
+    };
+};
+type CheckTaskToolCallChatMessage = {
+    tool: "checkTask";
+    args: {
+        taskId: string;
+    };
+    output?: {
+        taskId: string;
+        state?: string;
+        message?: string;
+        label?: string;
+    };
+};
+type WaitForTaskToolCallChatMessage = {
+    tool: "waitForTask";
+    args: {
+        taskId: string;
+        timeoutMs?: number;
+    };
+    output?: {
+        taskId: string;
+        state?: string;
+        message?: string;
+        label?: string;
+        timedOut?: boolean;
+    };
+};
+type CancelTaskToolCallChatMessage = {
+    tool: "cancelTask";
+    args: {
+        taskId: string;
+    };
+    output?: {
+        taskId: string;
+        state?: string;
+        label?: string;
+    };
+};
+type SpawnCodingSubagentsToolCallChatMessage = {
+    tool: "spawnCodingSubagents";
+    /**
+     * Compact wire shape forwarded by `getToolCallArguments` — `instructions`
+     * is intentionally stripped before persistence so we don't balloon chat
+     * messages with sub-agent prompts. Only fields the chat UI needs survive.
+     */
+    args: {
+        subagents: Array<{
+            id: string;
+            apiNames?: string[];
+        }>;
+        maxStepsPerSubagent?: number;
+    };
+    output?: {
+        success?: boolean;
+        completed?: number;
+        errored?: number;
+        maxSteps?: number;
+    };
+};
+type GetSdkApiDocsToolCallChatMessage = {
+    tool: "getSdkApiDocs";
+    args: {
+        integrationIds?: string[];
+        pluginIds?: string[];
+    };
+    output?: {
+        pluginIds: string[];
+    };
+};
+type BuildReloadFileToolCallChatMessage = {
+    tool: "build_reloadFile";
+    args: {
+        filePath: string;
+    };
+};
+export type BrowserPlaywrightToolCallChatMessage = {
+    tool: "browser_playwright_action";
+    args: {
+        action: "navigate" | "click" | "fill" | "screenshot" | "getText" | "getUrl" | "evaluate" | "waitForSelector" | "reload" | "getConsoleLogs" | "getEmbedEvents" | "triggerEmbedEvent" | "setEmbedProperties";
+        url?: string;
+        selector?: string;
+        value?: string;
+        fullPage?: boolean;
+        script?: string;
+        clear?: boolean;
+        eventName?: string;
+        payload?: Record<string, unknown>;
+        properties?: Record<string, unknown>;
+    };
+};
+type WebSearchToolCallChatMessage = {
+    tool: "web_search";
+    args: {
+        query: string;
+        allowed_domains?: string[];
+        blocked_domains?: string[];
+    };
+};
+type WebFetchToolCallChatMessage = {
+    tool: "web_fetch";
+    args: {
+        url: string;
+        prompt: string;
+    };
+};
+type GitToolCallChatMessage = {
+    tool: "git";
+    args: Record<string, any>;
+};
+type GitRawToolCallChatMessage = {
+    tool: "git_raw";
+    args: Record<string, any>;
+};
+type OpenIntegrationSetupToolCallChatMessage = {
+    tool: "openIntegrationSetup";
+    args: {
+        pluginId: string;
+        fields?: Record<string, unknown>;
+        label?: string;
+    };
+    output?: {
+        success: boolean;
+        tabId?: string;
+        formState?: unknown;
+    };
+};
+type OpenExistingIntegrationToolCallChatMessage = {
+    tool: "openExistingIntegration";
+    args: {
+        integrationId: string;
+    };
+    output?: {
+        success: boolean;
+        tabId?: string;
+        pluginId?: string;
+        integrationName?: string;
+        formState?: unknown;
+    };
+};
+type UpdateIntegrationFieldsToolCallChatMessage = {
+    tool: "updateIntegrationFields";
+    args: {
+        fields: Record<string, unknown>;
+        configId?: string;
+    };
+    output?: {
+        success: boolean;
+        formState?: unknown;
+        error?: string;
+    };
+};
+type UpdateAppEnvironmentToolCallChatMessage = {
+    tool: "updateAppEnvironment";
+    args: {
+        changes: Array<{
+            addProfileIds?: string[];
+            defaultProfileId?: string;
+            mode: "deployed" | "editor" | "preview";
+            removeProfileIds?: string[];
+        }>;
+    };
+};
+type TestIntegrationConnectionToolCallChatMessage = {
+    tool: "testIntegrationConnection";
+    args: {
+        configId?: string;
+    };
+    output?: {
+        success: boolean;
+        configId?: string;
+        error?: {
+            message: string;
+            details: string;
+        };
+        formState?: unknown;
+    };
+};
+type SaveIntegrationToolCallChatMessage = {
+    tool: "saveIntegration";
+    args: {
+        force?: boolean;
+    };
+    output?: {
+        success: boolean;
+        integrationId?: string;
+        testFailed?: boolean;
+        failedConfigIds?: string[];
+        validationErrors?: Record<string, string>;
+        error?: string;
+    };
+};
+type AskSearchableDropdownToolCallChatMessage = {
+    tool: "askSearchableDropdown";
+    args: {
+        question: string;
+        options: {
+            label: string;
+            value: string;
+        }[];
+    };
+};
+type DeleteIntegrationToolCallChatMessage = {
+    tool: "deleteIntegration";
+    args: {
+        integrationId: string;
+    };
+    output?: {
+        success: boolean;
+        integrationId?: string;
+        integrationName?: string;
+        alreadyDeleted?: boolean;
+        error?: string;
+    };
+};
+type GetIntegrationFormSchemaToolCallChatMessage = {
+    tool: "getIntegrationFormSchema";
+    args: {
+        pluginId: string;
+    };
+};
+export type ToolName = AiToolCallChatMessage["tool"];
+type RunMigrationVerificationToolCallChatMessage = {
+    tool: "runMigrationVerification";
+    args: {
+        apiName: string;
+        attemptCount?: number;
+    };
+};
+type ToolWithArgs = SimpleToolCallChatMessage | RunMigrationVerificationToolCallChatMessage | BuildInstallPackagesToolCallChatMessage | BuildLookupNpmPackageToolCallChatMessage | BuildCopyDirectoryToolCallChatMessage | BuildCopyFileToolCallChatMessage | BuildWriteFileToolCallChatMessage | BuildEditFileToolCallChatMessage | BuildMultiEditFileToolCallChatMessage | BuildDeleteFileToolCallChatMessage | BuildRenameFileToolCallChatMessage | BuildReadFilesToolCallChatMessage | BuildGenerateApiSourceToolCallChatMessage | ReadIntegrationMetadataToolCallChatMessage | FetchIntegrationToolCallChatMessage | SearchIntegrationsToolCallChatMessage | ReadIntegrationMetadataForPromptToolCallChatMessage | GrepMetadataToolCallChatMessage | ExecuteRequestToIntegrationToolCallChatMessage | RunCodeToolCallChatMessage | WriteApiToolCallChatMessage | BuildApiToolCallChatMessage | TestApiToolCallChatMessage | BuildReloadFileToolCallChatMessage | BuildReadFileToolCallChatMessage | BrowserPlaywrightToolCallChatMessage | BuildCaptureScreenshotToolCallChatMessage | BuildNavigatePreviewToolCallChatMessage | WebSearchToolCallChatMessage | WebFetchToolCallChatMessage | RememberKnowledgeToolCallChatMessage | GitToolCallChatMessage | GitRawToolCallChatMessage | OpenIntegrationSetupToolCallChatMessage | OpenExistingIntegrationToolCallChatMessage | UpdateAppEnvironmentToolCallChatMessage | UpdateIntegrationFieldsToolCallChatMessage | TestIntegrationConnectionToolCallChatMessage | AskSearchableDropdownToolCallChatMessage | DeleteIntegrationToolCallChatMessage | GetIntegrationFormSchemaToolCallChatMessage | SaveIntegrationToolCallChatMessage | GetSdkApiDocsToolCallChatMessage | SpawnCodingSubagentsToolCallChatMessage | ProvisionDatabaseToolCallChatMessage | StartApplyDevDatabaseMigrationsToolCallChatMessage | CheckTaskToolCallChatMessage | WaitForTaskToolCallChatMessage | CancelTaskToolCallChatMessage;
+export type AiToolCallChatMessage = BaseToolCallChatMessage & ToolWithArgs;
+export interface AiChecklistChatMessage extends AiChatMessageBase {
+    type: "tool";
+    group: "checklist";
+    checklistData: {
+        type: "checklist_item_added" | "checklist_item_updated" | "checklist_cleared";
+        payload: {
+            item?: {
+                id: string;
+                content: string;
+                status: "pending" | "in_progress" | "completed" | "cancelled" | "failed";
+                createdAt: string;
+                updatedAt?: string;
+                failureReason?: string;
+            };
+            totalItems?: number;
+            completedItems?: number;
+        };
+    };
+}
+type Choice = string | {
+    text: string;
+    subText?: string;
+    action?: "approve" | "deny";
+};
+export interface AiMultiChoiceMessage extends AiChatMessageBase {
+    type: "multi_choice";
+    subtitle?: string;
+    details?: string;
+    choices: Array<Choice>;
+    selectionType?: "single" | "multiple";
+    questionType?: "api_integration_error";
+    userResponse?: AiMultiChoiceResponseMessage;
+    /**
+     * Knowledge candidates embedded in approval prompts so they can be
+     * recovered from chat history after a page reload (when clark.context is gone).
+     */
+    knowledgeCandidates?: RememberKnowledgeCandidate[];
+}
+export interface AiSearchableDropdownMessage extends AiChatMessageBase {
+    type: "searchable_dropdown";
+    options: AiSearchableDropdownOption[];
+    placeholder?: string;
+    userResponse?: AiSearchableDropdownResponseMessage;
+}
+export interface AiSearchableDropdownResponseMessage extends AiChatMessageBase {
+    type: "searchable_dropdown_response";
+    responseToMessageId: string;
+    selectedValue: string;
+    selectedLabel: string;
+}
+export interface AiRememberKnowledgeDraftMessage extends AiChatMessageBase {
+    type: "remember_knowledge_draft";
+    candidates: RememberKnowledgeCandidate[];
+    userResponse?: AiRememberKnowledgeDraftResponseMessage;
+}
+export interface AiConfirmMessage extends AiChatMessageBase {
+    type: "confirm";
+    knowledgeEntry?: AiAppFactInput;
+    userResponse?: AiConfirmResponseMessage;
+}
+export interface AiPlanMessage extends AiChatMessageBase {
+    type: "plan";
+    userResponse?: AiPlanResponseMessage;
+    streaming?: boolean;
+    integrations?: PromptContextIntegration[];
+    entities?: PromptContextEntity[];
+    title?: string;
+    includesFreshDatabase?: boolean;
+}
+export interface AiPlanDeltaMessage extends AiChatMessageBase {
+    type: "plan-delta";
+    streaming?: boolean;
+}
+export interface AiMultiChoiceResponseMessage extends AiChatMessageBase {
+    type: "multi_choice_response";
+    responseToMessageId: string;
+    selectedChoiceIndices: number[];
+    selectedScopes?: KnowledgePromotionSelection[];
+    savedFacts?: SavedKnowledgeFact[];
+}
+export interface AiConfirmResponseMessage extends AiChatMessageBase {
+    type: "confirm_response";
+    responseToMessageId: string;
+    approved: boolean;
+    selectedScopes?: KnowledgePromotionSelection[];
+    savedFacts?: SavedKnowledgeFact[];
+}
+export interface AiPlanResponseMessage extends AiChatMessageBase {
+    type: "plan_response";
+    responseToMessageId: string;
+    enableTesting?: boolean;
+    approved?: boolean;
+}
+export interface AiRememberKnowledgeDraftResponseMessage extends AiChatMessageBase {
+    type: "remember_knowledge_draft_response";
+    responseToMessageId: string;
+    selectedCandidateIndices: number[];
+    selectedScopes?: KnowledgePromotionSelection[];
+    savedFacts?: SavedKnowledgeFact[];
+}
+export type KnowledgePromotionScope = "app" | "org" | "user" | "integration";
+export type KnowledgePromotionSelection = {
+    candidateIndex: number;
+    entityScope: KnowledgePromotionScope;
+    entityId?: string;
+};
+export type SavedKnowledgeFact = {
+    candidateIndex: number;
+    scope: KnowledgePromotionScope;
+    factName: string;
+    factId?: string;
+};
+export interface AiCommitRestoringMessage extends AiChatMessageBase {
+    type: "commitRestoring";
+    commitId: string;
+}
+export interface AiCommitRestoredMessage extends AiChatMessageBase {
+    type: "commitRestored";
+    commitId?: string;
+}
+export interface AiDraftCommittedMessage extends AiChatMessageBase {
+    type: "draftCommitted";
+    commitId?: string;
+}
+export type TestCasePlan = {
+    id: string;
+    name: string;
+    description?: string;
+    status: "not_started" | "running" | "passed" | "failed" | "skipped";
+};
+export interface AiTestRunStartMessage extends AiChatMessageBase {
+    type: "test_run_start";
+    testRunId: string;
+    header: string;
+    testCases?: TestCasePlan[];
+}
+export interface AiTestRunEndMessage extends AiChatMessageBase {
+    type: "test_run_end";
+    testRunId: string;
+    testStatus: "completed" | "failed";
+    summary?: string;
+}
+export interface AiTestCaseUpdateMessage extends AiChatMessageBase {
+    type: "test_case_update";
+    testRunId: string;
+    testCaseId: string;
+    testCaseStatus: "running" | "passed" | "failed" | "skipped";
+}
+export interface AiToolPermissionDetails {
+    targets: string[];
+    details?: string;
+    summary?: string;
+    /** Type of entity being deleted (for build_deleteFile) */
+    entityType?: "api" | "page" | "file";
+    /** Name of the entity being deleted (for build_deleteFile) */
+    entityName?: string;
+}
+export interface AiToolPermissionRequestMessage extends AiChatMessageBase {
+    type: "tool_permission_request";
+    toolName: string;
+    actionName?: {
+        future: string;
+        present: string;
+        past: string;
+    };
+    formattedInput?: AiToolPermissionDetails;
+    rawInput?: any;
+    permissions?: AiToolPermission[];
+    decision?: "approved" | "denied";
+    decisionTimestamp?: number;
+    signature?: string;
+    alwaysAllowPermissions?: AiToolPermission[];
+    output?: any;
+    error?: string;
+    errorCode?: AiToolExecutionErrorCode;
+    errorSummary?: string;
+}
+export interface AiToolResultMessage extends AiChatMessageBase {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: any;
+}
+export interface AiToolErrorMessage extends AiChatMessageBase {
+    type: "tool-error";
+    toolCallId: string;
+    toolName: string;
+    error: string;
+    errorCode?: AiToolExecutionErrorCode;
+    errorSummary?: string;
+}
+export interface AiGitSetupRequiredMessage extends AiChatMessageBase {
+    type: "git_setup_required";
+    applicationId?: string;
+    reason?: "git_not_connected";
+}
+export interface AiKnowledgeMessage extends AiChatMessageBase {
+    type: "knowledge";
+    facts: {
+        org: FactDto[];
+        user: FactDto[];
+        integrations: {
+            [integrationId: string]: FactDto[];
+        };
+    };
+}
+export interface AiAppKnowledgeSavedMessage extends AiChatMessageBase {
+    type: "app_knowledge_saved";
+    knowledgeCount: number;
+    responseToMessageId?: string;
+    savedFacts?: SavedKnowledgeFact[];
+    saveOutcomes?: KnowledgeSaveOutcome[];
+}
+export interface AiNextStepsChatMessage extends AiChatMessageBase {
+    type: "next_steps";
+    nextSteps: AiNextStep[];
+}
+export interface AiRetryNotificationChatMessage extends AiChatMessageBase {
+    type: "retry_notification";
+    retryType: "same_provider" | "fallback_provider";
+    attempt?: number;
+    delaySeconds?: number;
+    fromProvider?: string;
+    toProvider?: string;
+    reason?: string;
+    /** Number of consecutive retries (used by UI to consolidate messages) */
+    retryCount?: number;
+    success?: boolean;
+}
+export interface AiCompactionControlMessage extends AiChatMessageBase {
+    type: "control";
+    group: `context-compaction-${"phase1" | "phase2"}`;
+    status: "pending" | "validated" | "cancelled";
+    summary?: string;
+}
+export type AwsInfraDemoTaskKey = "db" | "s3";
+export type AwsInfraDemoTaskStatus = "pending" | "done";
+/**
+ * Demo-only: state snapshot for the "Preparing development environment" mock
+ * card in the Clark sidebar. The AI service emits this message multiple
+ * times during a single demo run — always with the SAME `id` — to drive
+ * the card's UI through its state transitions (e.g. pending/pending →
+ * done/pending → done/done). The UI's awsInfraDemoHandler folds repeated
+ * sends with the same id into a single message that always reflects the
+ * latest server snapshot, so no client-side timers are involved.
+ *
+ * Emitted only when the `superblocks.byo-db.demo` feature flag returns
+ * `{ enabled: true }` and the user submits the first prompt of an empty
+ * app. The UI also re-checks the flag before rendering.
+ */
+export interface AiAwsInfraDemoMessage extends AiChatMessageBase {
+    type: "aws_infra_demo";
+    statuses: Record<AwsInfraDemoTaskKey, AwsInfraDemoTaskStatus>;
+}
+export type AiChatMessage = AiChatMessageBase | AiToolCallChatMessage | AiChecklistChatMessage | AiCompactionControlMessage | AiConfirmMessage | AiConfirmResponseMessage | AiMultiChoiceMessage | AiMultiChoiceResponseMessage | AiSearchableDropdownMessage | AiSearchableDropdownResponseMessage | AiRememberKnowledgeDraftMessage | AiRememberKnowledgeDraftResponseMessage | AiPlanMessage | AiPlanDeltaMessage | AiPlanResponseMessage | AiToolPermissionRequestMessage | AiToolResultMessage | AiToolErrorMessage | AiGitSetupRequiredMessage | AiCommitRestoringMessage | AiCommitRestoredMessage | AiDraftCommittedMessage | AiTestRunStartMessage | AiTestRunEndMessage | AiTestCaseUpdateMessage | AiKnowledgeMessage | AiAppKnowledgeSavedMessage | AiRetryNotificationChatMessage | AiNextStepsChatMessage | AiAwsInfraDemoMessage;
+export interface AiChatSummary {
+    summary: string;
+    relevantFilePaths: string[];
+    goals: string[];
+    decisions: string[];
+    adviceToAgents: string;
+    timestamp: number;
+}
+/**
+ * Context V2 options for the two-phase compaction system.
+ * Phase 1: Tool output redaction (removes verbose outputs)
+ * Phase 2: Session summarization (LLM-generated summary)
+ *
+ * Use Partial<ContextOptionsV2> for overrides; merge with defaults via spread.
+ */
+export interface ContextOptionsV2 {
+    /** Maximum tokens allowed in the context window. Default: 170,000 */
+    contextLimit: number;
+    /** Tokens reserved for context buffer/jitter. Default: 4,000 */
+    contextBufferTokens: number;
+    /** Tokens reserved for model output. Default: 64,000 */
+    maxOutputTokens: number;
+    /** Whether Phase 1 (tool output redaction) is enabled. Default: true */
+    phase1Enabled: boolean;
+    /** Minimum pruneable tokens required to run Phase 1. Default: 10,000 */
+    phase1MinPruneable: number;
+    /** Recent tool call tokens protected from Phase 1 redaction. Default: 5,000 */
+    phase1ProtectedTokens: number;
+    /** Recent tool use/result pairs protected from Phase 1 redaction. Default: 3 */
+    phase1ProtectedToolUseCount: number;
+    /**
+     * Whether Phase 2 (LLM session summarization) is enabled. Default: true.
+     * Set false for bounded one-shot nested generations (e.g. exitPlanMode)
+     * that should inherit the conversation rather than re-summarize it.
+     */
+    phase2Enabled: boolean;
+    /** Target context ratio (0-1). After Phase 1, Phase 2 runs if usage exceeds this. Default: 0.4 */
+    phase2TargetRatio: number;
+    /**
+     * Within one turn, after a compaction whose measured post-compaction floor
+     * F is still over the compaction threshold, a second compaction is blocked
+     * until input exceeds F + reArmDeltaTokens. Guards same-instance per-step
+     * re-fire; the first compaction of a turn is unguarded, and a floor at or
+     * below threshold never arms the guard. Default: 40,000. Tunable via the
+     * ai.context-v2.options flag.
+     */
+    reArmDeltaTokens: number;
+    /**
+     * Whether to size the request before sending it and compact when it is
+     * already over the model's input limit. Default: true.
+     *
+     * The kill switch for ENG-5282. This is the one compaction trigger that runs
+     * on a size estimate rather than on provider-reported usage, so a bad
+     * estimate spends money and discards history on a conversation that would
+     * have been fine. Setting this false through the `ai.context-v2.options`
+     * flag restores the previous behavior: the provider rejects the oversized
+     * request and the session stays wedged, which is visible and recoverable,
+     * where a wrong estimate is neither.
+     */
+    preflightCompactionEnabled: boolean;
+}
+/**
+ * Server-side context management thresholds sent to the Anthropic API.
+ *
+ * These control when Claude's server-side edits fire:
+ * - `clear_tool_uses_20250919`: removes old tool use/result pairs
+ * - `compact_20260112`: summarizes conversation to reduce context size
+ *
+ * All fields are optional; omitted fields use the hardcoded defaults
+ * in `context-management.ts`.
+ */
+export interface ServerContextManagementOptions {
+    /**
+     * Master switch for server-side context management. Defaults to
+     * client-side compaction (phase 1 tool summarization + phase 2 LLM
+     * session summarization); set `true` to opt into Anthropic's
+     * `compact_20260112` / `clear_tool_uses_20250919` edits. `false`,
+     * `undefined`, and missing flag payloads all resolve to client-side.
+     * The polarity is "opt-in for server-side" rather than "opt-out for
+     * client-side" so a regression in the server-side path can't
+     * silently catch users whose flag wasn't migrated.
+     */
+    enabled?: boolean;
+    /** Input token threshold for clearing old tool uses. Default: 100,000 */
+    clearToolUsesTriggerTokens?: number;
+    /** Input token threshold for server-side compaction. Default: 150,000 */
+    compactTriggerTokens?: number;
+    /** Number of recent tool use/result pairs to keep. Default: 6 */
+    keepRecentToolUses?: number;
+    /** Minimum tokens to reclaim per clear operation. Default: 10,000 */
+    clearAtLeastTokens?: number;
+}
+/**
+ * Model capabilities for Claude models.
+ * maxOutputTokens is the absolute maximum including thinking budget.
+ */
+export declare const MODEL_CAPABILITIES: {
+    readonly "claude-haiku-4-5": {
+        readonly maxOutputTokens: 64000;
+    };
+    readonly "claude-opus-4-5": {
+        readonly maxOutputTokens: 64000;
+    };
+    readonly "claude-opus-4-6": {
+        readonly maxOutputTokens: 128000;
+    };
+    readonly "claude-opus-4-7": {
+        readonly maxOutputTokens: 128000;
+    };
+    readonly "claude-opus-4-8": {
+        readonly maxOutputTokens: 128000;
+    };
+    readonly "claude-opus-5": {
+        readonly maxOutputTokens: 128000;
+    };
+    readonly "claude-sonnet-4-5": {
+        readonly maxOutputTokens: 64000;
+    };
+    readonly "claude-sonnet-4-6": {
+        readonly maxOutputTokens: 128000;
+    };
+};
+/**
+ * Maximum tokens reserved for model output (non-thinking).
+ * Set to 48K to leave headroom for thinking budget (default 5K-16K).
+ * The total (maxOutputTokens + thinkingBudget) must not exceed
+ * MODEL_CAPABILITIES[model].maxOutputTokens (64K).
+ */
+export declare const MAX_OUTPUT_TOKENS = 48000;
+/**
+ * Default values for ContextOptionsV2.
+ */
+export declare const DEFAULT_CONTEXT_OPTIONS_V2: ContextOptionsV2;
+export interface ChaosOptions {
+    errorRate?: number;
+}
+export type ApiLLMProviderType = "bedrock" | "anthropic" | "vertex" | "snowflake";
+/**
+ * Known core models, as a runtime list so callers can validate untrusted input
+ * against it — a bare type union erases at compile time and leaves request
+ * bodies unchecked.
+ */
+export declare const CORE_MODEL_NAMES: readonly ["claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-5", "claude-sonnet-4-5", "claude-sonnet-4-6"];
+export type CoreModelName = (typeof CORE_MODEL_NAMES)[number];
+export declare function isCoreModelName(value: unknown): value is CoreModelName;
+/** Metric-label value for anything outside {@link CORE_MODEL_NAMES}. */
+export declare const UNKNOWN_CORE_MODEL_LABEL = "unknown";
+/**
+ * Bound a core model to the known set before it becomes a metric label.
+ *
+ * `coreModel` reaches telemetry from caller-controlled input on both the server
+ * (request body) and the dev server (the UI's `llmConfig`), and is only typed,
+ * never validated on arrival. Unrecognized values collapse onto a single label
+ * so a caller cannot mint an unbounded series by varying the field.
+ */
+export declare function coreModelLabel(value: unknown): string;
+/**
+ * Clark LLM usage surfaces for golden cost/reliability metrics. Values align
+ * with billing metadata `surface` on proxy requests.
+ */
+export declare const CLARK_USAGE_SURFACES: readonly ["app", "dashboard", "policy_gate"];
+export type ClarkUsageSurface = (typeof CLARK_USAGE_SURFACES)[number];
+export declare function isClarkUsageSurface(value: unknown): value is ClarkUsageSurface;
+/** Metric-label value for anything outside {@link CLARK_USAGE_SURFACES}. */
+export declare const UNKNOWN_USAGE_SURFACE_LABEL = "unknown";
+export declare function usageSurfaceLabel(value: unknown): string;
+/**
+ * Compaction implementations, as a runtime list so the proxy can check the
+ * client-supplied billing attribute before it egresses to Snowflake.
+ */
+export declare const CONTEXT_MANAGEMENT_MODES: readonly ["client", "server"];
+export type ContextManagementMode = (typeof CONTEXT_MANAGEMENT_MODES)[number];
+export declare function isContextManagementMode(value: unknown): value is ContextManagementMode;
+/** Thinking configurations a request can send, as a runtime list. */
+export declare const THINKING_MODES: readonly ["adaptive", "budgeted", "off"];
+export type ThinkingMode = (typeof THINKING_MODES)[number];
+export declare function isThinkingMode(value: unknown): value is ThinkingMode;
+/**
+ * Bucket boundaries for the `superblocks.clark.prompt.credits` histogram.
+ * Shared because the dev-server and the server both emit that one metric name:
+ * two local bucket definitions would silently produce incomparable percentiles.
+ */
+export declare const CLARK_PROMPT_CREDITS_BUCKETS: readonly [0.5, 1, 2, 5, 7.5, 10, 15, 25, 50, 100, 250];
+/** AI SDK usage shape, as reported per step and in aggregate. */
+export interface LlmUsageTokens {
+    cachedInputTokens?: number;
+    inputTokenDetails?: {
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        noCacheTokens?: number;
+    };
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface PromptCostTokens {
+    cachedReadTokens: number;
+    cachedWriteTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Normalizes AI SDK token usage into the four counts credit pricing bills on.
+ *
+ * `inputTokens` from the SDK is the total including cache traffic, so the
+ * uncached remainder is derived rather than read directly, and clamped because
+ * providers occasionally report cache counts that exceed the total.
+ */
+export declare function promptCostTokensFrom(usage: LlmUsageTokens): PromptCostTokens;
+export declare const FALLBACK_STRATEGIES: readonly ["model-then-provider", "provider-then-model", "model-then-provider-no-retry", "provider-then-model-no-retry", "only-model", "only-provider", "disabled"];
+/**
+ * Fallback strategy for model failover.
+ *
+ * The initial provider comes from ui.clark-ai.llm-provider feature flag.
+ * The initial model comes from superblocks.ai.core-model.name feature flag.
+ * This strategy controls what happens when the initial provider/model fails.
+ *
+ * With retry (4 entries):
+ * - "model-then-provider": initial → initial+model2 → provider2+initial → provider2+model2
+ * - "provider-then-model": initial → provider2+initial → initial+model2 → provider2+model2
+ *
+ * Without retry (3 entries):
+ * - "model-then-provider-no-retry": initial → initial+model2 → provider2+model2
+ * - "provider-then-model-no-retry": initial → provider2+initial → provider2+model2
+ *
+ * Limited (2 entries):
+ * - "only-model": initial → initial+model2
+ * - "only-provider": initial → provider2+initial
+ *
+ * No fallback:
+ * - "disabled": initial only, fail immediately on error
+ */
+export type FallbackStrategy = (typeof FALLBACK_STRATEGIES)[number];
+export interface LLMProviderConfig {
+    provider: ApiLLMProviderType;
+    thinkingEnabled: boolean;
+    thinkingBudgetTokens: string;
+    interleavedThinking: boolean;
+    disabledTools?: string[];
+    contextOptionsV2?: Partial<ContextOptionsV2>;
+    serverContextManagement?: Partial<ServerContextManagementOptions>;
+    chaosOptions?: ChaosOptions;
+    flags?: {
+        isChecklistEnabled?: boolean;
+        isNavigationToolEnabled?: boolean;
+        isScreenshotToolEnabled?: boolean;
+        isTestingEnabled?: boolean;
+        isFactsEnabled?: boolean;
+        isAppKnowledgeEnabled?: boolean;
+        isTypecheckEnabled?: boolean;
+        textUploadContextByReferenceMimeTypes?: unknown;
+    };
+    coreModel: CoreModelName;
+    unifiedProviderEnabled: boolean;
+    fallbackStrategy?: FallbackStrategy;
+    /** @deprecated Hardcoded to true for one release cycle so old dev servers don't block data access. Remove after next release. */
+    customerDataAccessEnabled?: boolean;
+}
+export type PlanContext = {
+    plan?: string;
+    approved?: boolean;
+    integrations?: PromptContextIntegration[];
+    entities?: PromptContextEntity[];
+    title?: string;
+    attachments?: Array<Attachment>;
+    enableTesting?: boolean;
+};
+/**
+ * Init data from sb-init message - required for socket connection setup.
+ */
+export interface InitData {
+    peerId: string;
+    userId?: string;
+    appId: string;
+    sessionRecordingKey?: string;
+    interactionMode?: InteractionMode;
+    /** The value of the authorization header on requests to the dev server. */
+    devServerAuthorization: string | undefined;
+    /** Timestamp when the parent connection started (for end-to-end metrics) */
+    connectionStartTime?: number;
+    /** W3C Trace Context headers for linking app websocket span to parent trace */
+    traceContext?: Record<string, string>;
+    /** Connection type: initial or reconnect */
+    connectionType?: "initial" | "reconnect";
+    /** Connection target: local, sabs, or default */
+    connectionTarget?: string;
+    /** Window origin URL for initializing tracer provider */
+    windowOriginUrl?: string;
+    aiState?: {
+        generationState: AiGenerationState;
+        editingComponents: SbElement[];
+    };
+}
+/**
+ * Bootstrap data required for the vite dev server app to initialize.
+ * This simulates the data normally sent from the parent window via postMessage.
+ */
+export interface BootstrapData {
+    appId: string;
+    userId: string;
+    token: string;
+    accessToken: string;
+    /** Explicit authorization for the code-mode dev server. */
+    devServerAuthorization: string | null;
+    agentUrls?: string[];
+    /**
+     * On-prem agent metadata. Cloud / Gateway capture must send `[]` rather
+     * than omitting the key: the library assigns `payload.agents` onto
+     * `_agents` and then reads `_agents.length`.
+     */
+    agents?: unknown[];
+    orgId?: string;
+    orgName?: string;
+    userEmail?: string;
+    windowOriginUrl?: string;
+    /** Profile data for API execution - includes selected profile with id/key */
+    profiles?: {
+        available: Profile[];
+        selected?: Profile;
+        default: Profile;
+    };
+    /**
+     * Editor parent sends LaunchDarkly flags here. `clark.sdk-api.enabled`
+     * must be true or the canvas runs YAML `runApiByPath` instead of v3/execute.
+     */
+    featureFlags?: Record<string, unknown>;
+}
+/**
+ * Data needed for Playwright browser automation to interact with the app.
+ * Contains the iframe URL and initialization data that the app expects.
+ */
+export type BrowserContext = {
+    /** The base URL of the iframe (e.g., sandbox URL from socket connection) */
+    iframeBaseUrl: string;
+    /** Data from sb-init message - required for socket connection setup */
+    initData: InitData;
+    /** Data from sb-bootstrap-response - required for API manager initialization */
+    bootstrapData: BootstrapData;
+};
+export type AiResponseMetadata = {
+    responseToMessageId: string;
+} & ({
+    type: "multi_choice_response";
+    selectedChoiceIndices: number[];
+    selectedScopes?: KnowledgePromotionSelection[];
+} | {
+    type: "remember_knowledge_draft_response";
+    selectedCandidateIndices: number[];
+    selectedScopes?: KnowledgePromotionSelection[];
+} | {
+    type: "confirm_response";
+    approved: boolean;
+    selectedScopes?: KnowledgePromotionSelection[];
+} | {
+    type: "plan_response";
+    approved?: boolean;
+    enableTesting?: boolean;
+} | {
+    type: "searchable_dropdown_response";
+    selectedValue: string;
+    selectedLabel: string;
+} | {
+    type: "tool_permission_response";
+    responseToMessageId: string;
+    approved?: boolean;
+    /** Distinguishes an editor-delivery failure from an actual user decision. */
+    outcome?: "delivery_expired" | "user_response";
+    alwaysAllowPermissions?: AiToolPermission[];
+    /** When true, the user's typed message is clarification rather than a denial. Only meaningful when `approved` is false. */
+    clarification?: boolean;
+});
+export type AiGenerateRequest = {
+    prompt: string;
+    promptContext?: PromptContext;
+    planContext?: PlanContext;
+    mockGeneration?: boolean;
+    jwt: string;
+    /** Required - contains provider and coreModel from feature flags */
+    llmConfig: LLMProviderConfig;
+    mode?: AiMode;
+    responseMetadata?: AiResponseMetadata;
+    browserContext?: BrowserContext;
+    userPreferences?: ClarkUserPreferences;
+    requestId?: string;
+    /** Third-party import source id (e.g. "lovable") for billing attribution of the turn. */
+    importSource?: string;
+};
+export type ClarkUserPreferences = {
+    suggestNextSteps: boolean;
+};
+export declare const CLARK_USER_PREFERENCES_DEFAULTS: ClarkUserPreferences;
+export type AiLabelAttachmentRequest = {
+    attachment: Attachment;
+    jwt: string;
+    llmConfig?: LLMProviderConfig;
+};
+export type AiLabelAttachmentResponse = {
+    label: string;
+    insight: string;
+};
+export declare enum AiMode {
+    BUILD = "BUILD",
+    PLAN = "PLAN"
+}
+/**
+ * A saved app-level fact that Clark can reference when building/editing this application.
+ * Stored as a markdown file with YAML frontmatter in skills/app/*.md.
+ */
+export type AiAppFact = {
+    /** Virtual path used as a stable identifier, e.g. ".superblocks/skills/app/no-emojis.md" */
+    path: string;
+    name: string;
+    description: string;
+    content: string;
+    /** Currently only "always" — on_demand is reserved for a future phase */
+    accessType: "always" | "on_demand";
+    isEnabled: boolean;
+    createdAt?: string;
+};
+export type AiMoveAppKnowledgeTargetScope = Exclude<KnowledgePromotionScope, "app">;
+export type AiMoveAppKnowledgeRequest = {
+    path: string;
+    targetScope: AiMoveAppKnowledgeTargetScope;
+    entityId?: string;
+};
+export type AiMoveAppKnowledgeResult = {
+    sourcePath: string;
+    createdFact: {
+        id?: string;
+        name: string;
+        scope: AiMoveAppKnowledgeTargetScope;
+        entityId?: string;
+    };
+};
+export type KnowledgeSaveOutcome = {
+    candidateIndex: number;
+    scope: KnowledgePromotionScope;
+    factName: string;
+    status: "created" | "updated" | "deleted" | "created_remote" | "skipped_existing" | "skipped_not_found" | "failed";
+    factId?: string;
+    reason?: string;
+};
+export type AiAppFactInput = {
+    name: string;
+    description: string;
+    content: string;
+    currentContent?: string;
+    proposedContent?: string;
+    evidence?: string;
+    confidence?: number;
+    reasonCode?: "explicit_user_instruction" | "drift_detected" | "invalidation";
+    factKind?: "durable_guardrail" | "mutable_state";
+    status?: "active" | "stale";
+    reason?: string;
+    accessType?: "always" | "on_demand";
+    isEnabled?: boolean;
+    createdAt?: string;
+    action?: "create" | "update" | "delete";
+    targetFactName?: string;
+};
+/**
+ * A candidate knowledge entry to create, update, or delete.
+ * Passed in by the rememberKnowledge tool when the user asks Clark to remember something.
+ */
+export type RememberKnowledgeCandidate = {
+    name: string;
+    description: string;
+    content: string;
+    currentContent?: string;
+    proposedContent?: string;
+    evidence?: string;
+    confidence?: number;
+    reasonCode?: "explicit_user_instruction" | "drift_detected" | "invalidation";
+    action?: "create" | "update" | "delete";
+    targetFactName?: string;
+    reason?: string;
+};
+export type RememberKnowledgeToolCallChatMessage = {
+    tool: "rememberKnowledge";
+    args: {
+        candidates?: RememberKnowledgeCandidate[];
+    };
+};
+export type AiChangeInfoPush = {
+    type: "component" | "api" | "page" | "dependency" | "theme";
+    name: string;
+    action: AiChatMessage["action"];
+    status: AiChatMessage["status"];
+};
+/**
+ * Message types that are excluded from being stored by the server.
+ * These messages are ephemeral and should not be persisted to the database.
+ */
+export declare const EXCLUDED_MESSAGE_TYPES: readonly AiChatMessage["type"][];
+/** Maps legacy persisted roles ("server", "ai") onto "assistant". */
+export declare function normalizeLegacyChatRole(role: string): string;
+/**
+ * Types the live-edit pod never evicts. Shared so editor pod-reconcile can
+ * exclude them when inferring the eviction frontier from a payload.
+ *
+ * Distinct from EXCLUDED_MESSAGE_TYPES (what the server never persists).
+ */
+export declare const EVICTION_PROTECTED_MESSAGE_TYPES: readonly AiChatMessage["type"][];
+export type AiSearchableDropdownOption = {
+    label: string;
+    value: string;
+    description?: string;
+};
+/**
+ * Curated list of Lucide icon names (kebab-case) available for next steps.
+ * This is the single source of truth — both the backend prompt and the frontend icon map
+ * must stay in sync with this list.
+ */
+export declare const NEXT_STEPS_ICON_NAMES: readonly ["alert-triangle", "arrow-right-left", "arrow-up-down", "bar-chart-3", "bell", "bookmark", "calendar", "check", "check-circle", "circle-user", "clipboard", "clock", "cloud", "code", "copy", "database", "download", "external-link", "eye", "file-down", "file-plus", "file-text", "filter", "folder", "git-branch", "globe", "grip-vertical", "hard-drive", "heart", "home", "image", "info", "key", "layers", "layout-grid", "line-chart", "link", "list", "lock", "log-out", "mail", "map", "message-square", "monitor", "moon", "package", "palette", "pencil", "pie-chart", "plus", "printer", "puzzle", "refresh-cw", "repeat", "rocket", "save", "search", "server", "settings", "share-2", "shield", "sliders", "smartphone", "sparkles", "star", "table", "tag", "thumbs-up", "toggle-left", "trash-2", "upload", "user-plus", "users", "wand-2", "zap"];
+export type NextStepsIconName = (typeof NEXT_STEPS_ICON_NAMES)[number];
+export type AiNextStep = {
+    label: string;
+    prompt: string;
+    /** Lucide icon name (kebab-case) chosen by the LLM to represent this next step */
+    icon?: NextStepsIconName;
+};
+export type PromptContextEntity = {
+    id: string;
+    type: AiEntityType;
+    metadata?: Record<string, any>;
+};
+export type ElementDomMetadata = {
+    openingTagHtml?: string;
+    boundingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+};
+export type TaggedElementDomMetadata = {
+    sourceId: string;
+    totalCount: number;
+    elements: ElementDomMetadata[];
+};
+export type AiPromptInterpretationPush = {
+    prompt: string;
+    classification: PromptClassification;
+    entities: PromptContextEntity[];
+};
+export type AiGenerationStateSnapshot = {
+    state: AiGenerationState;
+    /**
+     * The generation this state is about, as the dev server named it when the
+     * prompt started (`aiGenerateWithQueue` returns the same id).
+     *
+     * Without it a terminal state is unattributable: the ai-service starts
+     * generations of its own — a migration turn, an interrupt-and-continue —
+     * and their COMPLETED is indistinguishable on the wire from the one a
+     * caller is waiting for. A consumer must ignore terminal states naming a
+     * generation other than the one it started.
+     *
+     * Absent from dev servers that predate this field; treat that as today's
+     * behavior rather than as a mismatch. (APPS-5161)
+     */
+    generationId?: string;
+    hasError?: boolean;
+    hasSuggestions?: boolean;
+    paywallReason?: AiQuotaPaywallReason;
+};
+export type AiChatGetMessagesResponse = {
+    messages: AiChatMessage[];
+};
+export type PromptContextIntegration = {
+    id: string;
+    name: string;
+    displayName?: string;
+    type: string;
+    metadata: Record<string, any>;
+    openApiSpecRef?: string;
+    /** True when this integration can fall back to a default configuration for any app data tag. */
+    hasDefaultConfiguration?: boolean;
+    /** App data tags that do not have an integration configuration and require user confirmation. */
+    mismatchedAppProfileKeys?: string[];
+    /** Data tags that have an explicit configuration or can use the default configuration. */
+    supportedProfileKeys?: string[];
+    /** Set to `database_lifecycle` for app-scoped managed Native DB integrations. */
+    managedBy?: string | null;
+};
+/** Base fields for all attachment types */
+export type BaseAttachment = {
+    /** Original filename; may be missing or blank when attachments come from partial/legacy payloads */
+    fileName?: string;
+    /** Brief 2-3 word description of the attachment (populated async by LLM) */
+    label?: string;
+    /** Key observation about what the attachment shows (populated async by LLM) */
+    insight?: string;
+};
+/** Display and model-input-safe filename when `fileName` is missing or whitespace-only */
+export declare const DEFAULT_ATTACHMENT_FILE_NAME = "Attachment";
+/**
+ * Returns a non-empty filename for UI, LLM file parts, and lease metadata.
+ * Prefer `fileName` when present; otherwise infer from `mediaType` / `type` when possible.
+ */
+export declare function resolveAttachmentFileName(attachment: {
+    fileName?: string;
+    /** Uploaded attachments use `mediaType`; text file attachments use `mimeType` */
+    mediaType?: string;
+    mimeType?: string;
+    type?: string;
+}): string;
+export type ImageAttachment = BaseAttachment & {
+    type: "image";
+    image: string;
+};
+export type PdfAttachment = BaseAttachment & {
+    type: "pdf";
+    data: string;
+    size?: number;
+};
+export type ArchiveAttachment = BaseAttachment & {
+    type: "archive";
+    data: string;
+    size?: number;
+};
+/**
+ * Uploaded attachment reference.
+ *
+ * Uses a stable URL and carries upload metadata so downstream services can
+ * refresh leases or authorize access as needed.
+ */
+export type UploadedAttachment = BaseAttachment & {
+    type: "uploaded";
+    url: string;
+    signedUrl?: string;
+    mediaType: string;
+    storageKey?: string;
+    signedUrlExpiresAt?: string;
+    scopeType?: "org" | "app";
+    applicationId?: string;
+};
+/** Text-based attachment types that share the same structure */
+export declare const TEXT_ATTACHMENT_TYPES: readonly ["csv", "json", "yaml", "css", "txt"];
+export type TextAttachmentType = (typeof TEXT_ATTACHMENT_TYPES)[number];
+/** Unified type for text-based file attachments (CSV, JSON, YAML, CSS, TXT) */
+export type TextAttachment = BaseAttachment & {
+    type: TextAttachmentType;
+    content: string;
+    mimeType: string;
+    size?: number;
+};
+/** Default MIME types for text attachments */
+export declare const TEXT_ATTACHMENT_MIME_TYPES: Record<TextAttachmentType, string>;
+/** Accepted file types configuration for file inputs and dropzones */
+export declare const ACCEPTED_ATTACHMENT_TYPES: Record<string, string[]>;
+/** Image-only file types configuration */
+export declare const ACCEPTED_IMAGE_TYPES: Record<string, string[]>;
+/** Returns accepted attachment types based on whether file attachments are enabled */
+export declare const getAcceptedAttachmentTypes: (fileAttachmentsEnabled: boolean) => Record<string, string[]>;
+/** Accepted file types as a string for HTML input accept attribute */
+export declare const ACCEPTED_ATTACHMENT_TYPES_STRING: string;
+/** Image-only file types as a string for HTML input accept attribute */
+export declare const ACCEPTED_IMAGE_TYPES_STRING: string;
+/** Helper to check if an attachment is a text-based attachment */
+export declare const isTextAttachment: (attachment: Attachment) => attachment is TextAttachment;
+export type FileAttachment = ArchiveAttachment | PdfAttachment | TextAttachment;
+export type Attachment = ImageAttachment | FileAttachment | UploadedAttachment;
+/**
+ * Simplified user type for PromptContext
+ */
+export type PromptContextUser = {
+    id: string;
+    name: string;
+    email: string;
+    username: string;
+};
+export type KnowledgePromotionIntegrationCapability = {
+    entityId: string;
+    name: string;
+    canCreate: boolean;
+    reason?: string;
+};
+export type KnowledgePromotionCapabilities = {
+    app: {
+        canCreate: true;
+    };
+    org: {
+        canCreate: boolean;
+        entityId?: string;
+    };
+    user: {
+        canCreate: boolean;
+        entityId?: string;
+    };
+    integrations: KnowledgePromotionIntegrationCapability[];
+};
+export type PromptContext = {
+    entities: PromptContextEntity[];
+    integrations: PromptContextIntegration[];
+    knowledgePromotionCapabilities?: KnowledgePromotionCapabilities;
+    unresolvedIntegrations?: string[];
+    fromEmptyState?: boolean;
+    currentPageName?: string;
+    currentApiName?: string;
+    currentRoutePattern?: string;
+    currentPathname?: string;
+    currentRouteParams?: Record<string, string | undefined>;
+    previewDevice?: PreviewDevice;
+    currentView?: EditorView;
+    attachments?: Array<Attachment>;
+    dataTags?: {
+        available: Array<DataTag>;
+        selected?: DataTag;
+        default: DataTag;
+    };
+    environmentCompatibility?: AppEnvironmentCompatibility;
+    user?: PromptContextUser;
+    groups?: Array<{
+        id: string;
+        name: string;
+        size: number;
+    }>;
+    conflictedFiles?: string[];
+    gitSetup?: {
+        isConnected: boolean;
+        provider?: string;
+        remoteUrl?: string;
+    };
+    integrationSetup?: {
+        pluginId: string;
+        mode: "create" | "edit";
+        integrationName?: string;
+    };
+    /**
+     * Org-level `app_ai` setting. Mirrors the server-side jsonb and is intentionally
+     * extensible (per-purpose defaults, model preference, etc. land here as new fields).
+     * When `preferredAppInferenceIntegrationId` is set, Clark treats it as the preferred
+     * provider for AI inference in customer-built apps.
+     */
+    aiConfiguration?: {
+        preferredAppInferenceIntegrationId?: string;
+    };
+};
+export type AiInterpretPromptRequest = {
+    prompt: string;
+    promptContext?: PromptContext;
+    jwt: string;
+};
+export declare const PromptClassificationAndComplexity: {
+    readonly full_app_gen: 1;
+    readonly broad_edit: 2;
+    readonly specific_edit: 3;
+    readonly question: 4;
+    readonly unknown: 5;
+};
+export type PromptClassification = keyof typeof PromptClassificationAndComplexity;
+export declare enum AiContextMode {
+    HIGHLIGHT = "highlight",
+    AUTO_SELECT = "auto-select",
+    SILENT = "silent"
+}
+export declare enum AiGenerationState {
+    IDLE = "idle",
+    GENERATING = "generating",
+    DEBUGGING = "debugging",
+    SUMMARIZING = "summarizing",
+    COMPLETED = "completed",
+    CANCELLED = "cancelled",
+    AWAITING_USER_INPUT = "awaiting_user_input"
+}
+/**
+ * Internal marker used to signal the end of plan streaming.
+ * This value is intentionally unique to avoid conflicts with plan content.
+ */
+export declare const AI_PLAN_STREAMING_END_MARKER = "[__SUPERBLOCKS_PLAN_DONE__]";
+export interface TokenRequestData {
+    requestId: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedInputTokens?: number;
+    model: string;
+    startTime: string;
+    endTime: string;
+}
+export type TokenUsage = Omit<TokenRequestData, "requestId">;
+export interface TokenSessionSummary {
+    startTime: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    totalCachedTokens: number;
+    requestCount: number;
+    primaryModel: string;
+    endTime: string;
+}
+export declare enum AiToolExecutionErrorCode {
+    NOT_FOUND = "tool_not_found",
+    NOT_ALLOWED = "tool_not_allowed",
+    REQUIRES_USER_CONFIRMATION = "tool_requires_user_confirmation",
+    INVALID_INPUT = "tool_invalid_input",
+    INTERNAL_ERROR = "tool_internal_error"
+}
+/**
+ * AI Attributes
+ *
+ * Attributes passed from ai-service (dev-server) to control plane (server) for AI usage tracking.
+ * This data is included in the LLM request body and extracted by the control plane to log
+ * usage events to Snowflake.
+ *
+ * This interface is designed to be extensible - additional fields can be added in future PRs
+ * for plan mode, timestamps, LOC tracking, etc.
+ */
+export interface AiAttributes {
+    /** Unique ID for this user interaction (UUID) */
+    prompt_id?: string;
+    /** Chat message ID for linking to chat history (UUID) */
+    chatmessage_id?: string;
+    /** Application ID associated with this request */
+    application_id?: string;
+    /** Attribution details for internal reporting, such as migration or import identifiers. */
+    metadata?: Record<string, unknown>;
+    /** LLMObs session ID for correlation with Datadog LLM Observability */
+    session_id?: string;
+    /** AI agent run ID supplied by the caller; the server validates org ownership before attribution. */
+    ai_agent_run_id?: string;
+    /** Underlying model ID (e.g. claude-3-5-sonnet-20241022) */
+    model?: string;
+    /** Clark model abstraction (e.g. clark-fast) */
+    clark_model?: string;
+    /** Provider (bedrock, vertex, etc.) */
+    provider?: string;
+    /** Authenticated Superblocks platform user email for AI billing attribution. */
+    user_email?: string | null;
+    /** Organization display name, denormalized so analytics can resolve an org id to a name without a DB join. */
+    organization_name?: string | null;
+    /** True when organization_name was derived from an email-shaped name (the self-serve default) rather than chosen. */
+    organization_name_is_derived?: boolean | null;
+    /** AI credits consumed for this request (computed from token costs × multiplier) */
+    credits_used?: number;
+    /** Input tokens from LLM response */
+    input_tokens?: number;
+    /** Output tokens from LLM response */
+    output_tokens?: number;
+    /** Total tokens (input + output) */
+    total_tokens?: number;
+    /** Cache read tokens (90% discount) */
+    cached_read_tokens?: number;
+    /** Cache write tokens (25% of regular price) */
+    cached_write_tokens?: number;
+    /** Reasoning tokens (o1/o3 models) */
+    reasoning_tokens?: number;
+    /** ISO 8601 UTC timestamp when LLM call begins */
+    started_at?: string;
+    /** ISO 8601 UTC timestamp when LLM call finishes */
+    completed_at?: string;
+    /** Lines added from Write tool calls */
+    lines_added?: number;
+    /** Lines edited from Edit tool calls (min of added/removed) */
+    lines_edited?: number;
+    /** Lines removed from Edit tool calls */
+    lines_removed?: number;
+    /** Number of reasoning steps */
+    step_count?: number;
+    /** Total tool invocations */
+    tool_call_count?: number;
+    /** Number of retry attempts for this request */
+    retry_count?: number;
+    /** Whether workflow failed after all retries */
+    workflow_failed?: boolean;
+    /** Mode: "plan" (when exitPlanMode called) or "build" (default) */
+    mode?: "plan" | "build";
+    /** Plan complexity: "small" | "medium" | "large" | "extra large" (only when mode="plan") */
+    plan_size?: "small" | "medium" | "large" | "extra large";
+    /** Type of system operation that triggered this AI call (e.g. commit_message, attachment_label) */
+    trigger_type?: string;
+    /** Context window (tokens) available to the request. */
+    context_limit?: number;
+    /** Tokens reserved for model output. */
+    max_output_tokens?: number;
+    /** Safety margin (tokens) held back on top of the output reservation. */
+    context_buffer_tokens?: number;
+    /**
+     * Which compaction implementation ran. "client" is our two-phase local
+     * compaction, whose phase 2 bills a separate summarization call; "server"
+     * delegates to Anthropic's managed context edits, which fold into the
+     * request. The two have different cost shapes, so comparing GAU per prompt
+     * across a rollout is only meaningful when split by this.
+     *
+     * Client-side compaction fires once input exceeds
+     * `context_limit - max_output_tokens - context_buffer_tokens`.
+     */
+    context_management?: ContextManagementMode;
+    /**
+     * Thinking configuration sent upstream. Adaptive models (opus 4.7 and later)
+     * take an effort level and ignore the token budget entirely, so they report
+     * "adaptive" and carry no `thinking_budget_tokens`.
+     */
+    thinking_mode?: ThinkingMode;
+    /**
+     * Requested thinking budget (tokens), set only when `thinking_mode` is
+     * "budgeted". This is what the config asked for: the request path can still
+     * shrink it at call time if output reservation plus budget would exceed the
+     * model's ceiling.
+     */
+    thinking_budget_tokens?: number;
+}
+export type { AiAttachmentLeaseReference, AiResolveAttachmentLeasesRequest, AiResolveAttachmentLeasesResponse, AiResolvedAttachment, } from "@superblocksteam/shared";
+//# sourceMappingURL=ai.d.ts.map