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

package/dist/ai-service/index.d.ts

@@ -1,21 +1,702 @@
-import EventEmitter from "node:events";
-import type { AiServiceConfig, AiServiceEvents } from "./types.ts";
-import type { AiGenerateRequest, EditorClientMethods } from "@superblocksteam/library-shared/types";
-import type { ISocketClient } from "@superblocksteam/shared";
-export declare class AiService extends EventEmitter<AiServiceEvents> {
+import type { ViteDevServer } from "vite";
+import { type AiAppFact, type AiMoveAppKnowledgeRequest, type AiMoveAppKnowledgeResult, type AiGenerateRequest, type AiSummarizeApiUsageRequest, type AiSummarizeErrorRequest, type AiLabelAttachmentRequest, type AiLabelAttachmentResponse, type AiToolPermission, type ClarkUsageSurface, type LLMProviderConfig, type PromptContext, type RuntimeErrorData, type ConsoleLogEntry, type ApiRunRecord } from "@superblocksteam/library-shared/types";
+import { TracedEventEmitter, type ScanScopeJson } from "@superblocksteam/shared";
+import type { FileSystemManager } from "../file-system-manager.js";
+import type { GitOperationLock } from "../git-operation-lock.js";
+import type { GitService } from "../git-service/index.js";
+import type { SourceTracker } from "../source-tracker.js";
+import { type ReportReviewRunInput } from "./agent/tools/report-security-findings.js";
+import type { GitPullSyncService } from "./agent/tools2/tools/git.js";
+import { NpmRegistryClient, type LastKnownRegistryPolicyStore } from "./app-interface/npm-registry.js";
+import { ChatSessionStore } from "./chat/chat-session-store.js";
+import { AppContextStore } from "./context/app-context.js";
+import type { JudgeEvaluationOptions, JudgeEvaluationResult } from "./judge/judge-service.js";
+import type { ContextId } from "./llm/context-v2/types.js";
+import { RecordingManager } from "./recording/index.js";
+import type { BuildErrorPhase, BuildSystemError } from "./state-machine/clark-fsm.js";
+import { CLARK_USAGE_ORIGIN } from "./state-machine/helpers/prompt-request-metrics.js";
+import { StablePeer } from "./state-machine/helpers/stable-peer.js";
+import type { AiServiceConfig, AiServiceEvents, AiInputSource, EditorClient, UserChange, ApiUpdate } from "./types.ts";
+import type { PeerConnectionLiveness } from "./util/peer-liveness.js";
+export { AiServiceFeatureFlags } from "./features.js";
+export { getManagedNativeDbGateDenialReason, hasEditLifecycleCapability, isManagedNativeDbAvailableForClark, } from "./managed-native-db-availability.js";
+export { stripResolvedFromLockfile } from "./app-interface/npm-registry.js";
+export { SnapshotManager } from "./recording/index.js";
+export { isSdkApiTemplate } from "./sdk-api-templates.js";
+/**
+ * APPS-4370. Build the disk-backed `LastKnownRegistryPolicyStore` the
+ * production `AiService` wires into its default `NpmRegistryClient`.
+ *
+ * Exported so unit tests can exercise the exact wiring path the
+ * constructor uses without standing up a full AiService — the
+ * constructor calls this function inline. Tests pass a tmp directory as
+ * `rootDir`; production callers leave the field undefined on
+ * `AiServiceConfig` and we fall back to `os.homedir()` at the call
+ * site.
+ *
+ * Kept as a thin pass-through (rather than inlining
+ * `createDiskRegistryPolicyStore`) so the production wiring shape is
+ * named and reviewable: a single function, a single call site, one
+ * place to assert about in coverage.
+ */
+export declare function buildLastKnownPolicyStore(opts: {
+    organizationId: string;
+    rootDir: string;
+}): LastKnownRegistryPolicyStore;
+export declare function pruneByTTL<T extends {
+    timestamp?: number;
+    generationTimestamp?: string;
+}>(items: T[], ttlMs: number): T[];
+export declare function estimateSize(obj: unknown): number;
+export declare function truncateString(str: string, maxBytes: number): string;
+export declare function pruneBySize<T extends {
+    _size?: number;
+}>(items: T[], maxBytes: number): T[];
+interface MigrationUsageMetadata extends Record<string, unknown> {
+    applicationId: string;
+    branchName: string | undefined;
+    migrationSource: "superblocks_2_0";
+    origin: typeof CLARK_USAGE_ORIGIN.app_migration;
+    pendingSeedApiCount: number;
+    retryMode: "focused-debug" | "none";
+    surface: ClarkUsageSurface;
+    triggeredBy: "auto-dispatch" | "focused-debug" | "ui-rpc";
+}
+interface ToolPermissionResponseRequest {
+    messageId: string;
+    approved: boolean;
+    alwaysAllowPermissions?: AiToolPermission[];
+    denyMessage?: string;
+    requestId?: string;
+}
+export declare class AiService extends TracedEventEmitter<AiServiceEvents> {
     private readonly config;
-    private artifactProcessor;
-    private anthropicProvider;
     private templateRenderer;
     private appShell;
-    private clark;
+    private fileSystemInterface;
+    private integrationStore;
+    private knowledgeManager;
+    private _appContext;
+    private llmProviderSettings;
+    private _logger;
+    private readonly clark;
+    private clarkProfiler;
+    readonly chatSessionStore: ChatSessionStore;
+    private readonly contextManagerV2;
+    private readonly llmClient;
+    private readonly stablePeer;
+    private readonly toolRegistry;
+    private readonly requestDeduplicator;
+    private readonly entityPermissionStore;
+    private readonly generationCompleteWaiters;
+    private activeGenerationTrace;
+    /** JWT-derived userId of the currently-authenticated peer, set by
+     * `notifyAuthenticatedRpc` and cleared on disconnect / peer swap.
+     * Only trusted while `authenticatedPeerId` still matches the bound
+     * `stablePeer.peerId` (see `getAuthenticatedPeerUserId`). Used by
+     * `wireTaskStatusPushToPeer` to owner-filter live status pushes. */
+    private authenticatedPeerUserId?;
+    /** The `peerId` that `authenticatedPeerUserId` was authenticated for.
+     * `handleUserConnected` can bind a replacement peer before the
+     * previous peer's disconnect is processed; keying the identity to its
+     * peerId means a live push in that window is gated against `undefined`
+     * (suppressed) instead of the previous user, closing the cross-user
+     * leak from PR #19718 Comment 59. */
+    private authenticatedPeerId?;
+    private tokenManagerJwt?;
+    /**
+     * Listener body for `tokenManager.on("tokenUpdated", ...)`. Defined as a
+     * prototype method (not a class field arrow) so tests can exercise the
+     * real implementation via `AiService.prototype.handleTokenUpdated`; the
+     * constructor binds `this` explicitly when registering with the emitter.
+     * Wrapped in try/catch because EventEmitter re-throws synchronous
+     * listener exceptions — a logger transport disconnect during JWT
+     * rotation would otherwise crash the process. `console.error` is the
+     * fallback because it cannot itself trigger the emitter chain.
+     */
+    private handleTokenUpdated;
+    private readonly npmRegistryClient;
+    /**
+     * Long-lived `NpmPackageLookup` reused across every `buildTools()` call.
+     * Constructed once in the AiService constructor and passed into the
+     * per-turn tool factory via `ClarkStateHandlerParams`. The factory used
+     * to `new NpmPackageLookup(...)` on every LLM generation turn, which
+     * leaked the `superblocks.npm.lookup.cache_size` `ObservableGauge`
+     * callback (the OTel API keeps a strong reference to every registered
+     * callback) and produced multiple same-instrument/same-attribute
+     * observations per collection cycle. Sharing one instance lifecycle-
+     * bound to the AiService ties the gauge to the process lifetime — same
+     * pattern as `npmRegistryClient` / `templateRenderer` / `appShell`.
+     */
+    private readonly npmPackageLookup;
+    private viteServer?;
+    private readonly mcpServerManager;
+    private readonly recordingManager;
+    private readonly sessionId;
+    private _runtimeGitService?;
+    private _runtimeSyncService?;
+    private _runtimeGitOperationLock?;
+    private _onGitOperationComplete?;
+    private _syncContextProvider?;
+    private readonly taskStore?;
+    get appContext(): AppContextStore;
+    get clarkState(): string;
+    /**
+     * Exposes the shared `NpmRegistryClient` so external SDK dev-server startup
+     * paths in `cli-replacement/dev.mts` — the home `~/.npmrc` writer
+     * (APPS-4231) and the startup `installPackages` call that honors the
+     * per-org `allow_install_scripts` policy (APPS-4251) — can share the
+     * in-memory cache, 401-refresh, and last-known-policy state already used
+     * by AppShell and TemplateRenderer. A separate client would fragment that
+     * state and double the network roundtrips against the registry-config
+     * endpoint. The client is always constructed (LD flag and empty-list
+     * cases short-circuit internally) so callers can treat this as
+     * non-optional once the AiService has been initialized.
+     */
+    getNpmRegistryClient(): NpmRegistryClient;
+    /**
+     * Opens the relay that lets a Gateway-driven turn see what Clark is doing.
+     *
+     * The sandbox holds a socket to the editor, but a Gateway turn has no editor
+     * on the far end, so its caller would otherwise learn nothing until the turn
+     * ended. Where the deployment does not run this channel the environment is
+     * simply absent, and this leaves the relay closed rather than failing to
+     * start.
+     */
+    private startLiveEditEventForwarding;
+    remediateDeclaredDependencies(): Promise<void>;
+    /**
+     * Injects git and sync services for the git tool (called by the plugin when native git is available).
+     */
+    setRuntimeGitServices(gitService?: GitService, syncService?: GitPullSyncService, gitOperationLock?: GitOperationLock): void;
+    setSyncContextProvider(provider: {
+        getBranchName: () => string;
+        getLastCommitId: () => string | undefined;
+    }): void;
+    setAuthenticatedEditorPeersProvider(provider: Parameters<StablePeer["setAuthenticatedEditorPeersProvider"]>[0]): void;
+    setAuthenticatedGatewayPeersProvider(provider: Parameters<StablePeer["setAuthenticatedGatewayPeersProvider"]>[0]): void;
+    setOnGitOperationComplete(callback: () => void): void;
+    get appRootDirPath(): string;
+    get organizationId(): string;
+    get superblocksBaseUrl(): string;
+    /**
+     * Gets the contextId for the current conversation context.
+     * Returns null if JWT is missing or has no userId.
+     */
+    getContextId(): ContextId | null;
+    /**
+     * Gets the JWT from Clark context
+     */
+    getClarkJwt(): string | undefined;
+    /**
+     * Updates the JWT in Clark context.
+     *
+     * A token that expires before the one already installed is ignored, because
+     * primes can arrive out of order.
+     *
+     * @returns whether the pod ended up holding a usable token. A rejected token
+     *   used to look exactly like one that landed, and like one that was never
+     *   sent at all, which is why a run could die holding a credential nobody
+     *   knew was stale.
+     */
+    updateClarkJwt(jwt: string): boolean;
+    /**
+     * Check if recording is currently enabled.
+     */
+    isRecording(): boolean;
+    /**
+     * Get the current recording session ID.
+     */
+    getRecordingSessionId(): string | null;
+    /**
+     * Clear all recordings.
+     *
+     * @param sessionId - Optional session ID to clear only that session
+     */
+    clearRecordings(sessionId?: string): Promise<void>;
+    /**
+     * Get the RecordingManager instance for advanced usage.
+     * This allows external code to add custom recording middleware.
+     */
+    getRecordingManager(): RecordingManager;
+    /**
+     * Returns the set of integration IDs available in the current environment.
+     */
+    getAvailableIntegrationIds(): Promise<Set<string>>;
+    get isSessionManagementEnabled(): boolean;
+    get isAiFileUploadEnabled(): boolean;
+    /**
+     * Checks if there is a live editor socket behind the StablePeer proxy.
+     * `clark.context.peer` is always present (it's the proxy); inner liveness
+     * is tracked on the proxy itself via `peerId`.
+     */
+    hasConnectedPeer(): boolean;
     constructor(config: AiServiceConfig);
+    /**
+     * Initialize the AI service. Must be called after construction.
+     * Sets up storage, cleanup tasks, and starts recording.
+     */
+    initialize(): Promise<void>;
+    private hydrateChecklistFromDisk;
+    private migrationAppArtifactsReady;
+    private migrationAutoDispatchPending;
+    private migrationAutoDispatchInFlight;
+    private lastMigrationTurnCredentials?;
+    private hasInitialPendingMigrationWork;
+    private resolveMigrationTurnCredentials;
+    private storeMigrationTurnCredentials;
+    private isRetriableMigrationAutoDispatchFailure;
+    /**
+     * Called by dev startup once DBFS download (or upload-first local tree)
+     * has finished so migration scratch/checklist files are on disk.
+     */
+    notifyMigrationAppArtifactsReady(): void;
+    private tryAutoDispatchMigrationTurnIfReady;
+    /**
+     * Attempts to start the initial post-flip migration turn without UI
+     * involvement. Skips user-initiated focused-debug retries (items with
+     * `lastFailureReason`) and defers when JWT is unavailable.
+     */
+    private maybeAutoDispatchMigrationTurn;
+    /**
+     * Remove the integration metadata cache for this session.
+     * Cleans up the session cache directory.
+     */
+    removeIntegrationCache(): Promise<void>;
+    private getLogger;
+    private startGenerationTrace;
     private createClarkTransitionHandler;
-    handleAiGenerate(request: AiGenerateRequest, peer: ISocketClient<EditorClientMethods>): Promise<void>;
-    handleUserAcceptedDraft(peer: ISocketClient<EditorClientMethods>): Promise<void>;
-    handleUserRejectedDraft(peer: ISocketClient<EditorClientMethods>): Promise<void>;
+    private getInferenceJwt;
+    private getProviderInferenceAuthToken;
+    private requireInferenceJwt;
+    private requireProviderInferenceAuthToken;
+    /**
+     * Resolves the conversation context for a contextId that is not present
+     * locally, by downloading it from Bucketeer. Wired into ContextManagerV2 as
+     * its `remoteRestoreFallback`, so it runs on a cold/recycled pod where the
+     * editor reconnects and no local context exists.
+     *
+     * Primary path: ask Bucketeer for the latest context for (app, branch). This
+     * needs no commitId, so a wrong or read-replica-lagged commitId can no longer
+     * resolve to an empty conversation.
+     *
+     * Fallback path: if the latest endpoint returns nothing (a Bucketeer that
+     * predates it returns 404, or there is no archive yet), resolve a commitId the
+     * old way — preferring `syncService.lastCommitId` (seeded by
+     * `downloadDirectory()` from the server's latest non-draft commit, the key the
+     * post-generation upload uses) and otherwise the most recent chat-history
+     * commitId — and GET by commit. The resolution is logged either way.
+     */
+    private remoteRestoreFallback;
+    private requireProvidedInferenceJwt;
+    private getNpmRegistryJwt;
+    private buildContextManagementForCurrentClark;
+    /**
+     * The checkpoint the app is currently based on: the last non-draft commit
+     * seeded by sync (preferred — same key the post-generation upload uses) or
+     * the most recent chat-history commit. Captured once at prompt start
+     * because the checkpoint an eventual accept will create does not exist yet
+     * while the LLM calls run. Never throws: a billing annotation must not be
+     * able to break generation.
+     */
+    private resolveBaseCommitId;
+    /**
+     * Races the chat-store fallback against `timeoutMs` so a hung store
+     * degrades exactly like a failure instead of delaying prompt start. The
+     * timeout rejects (never resolves) so the caller's catch block handles
+     * both outcomes uniformly; `onTimeout` lets the caller distinguish which
+     * branch fired for metrics/logging without a second code path.
+     * `.unref()` keeps the fallback timer from holding the process open.
+     */
+    private raceChatStoreLatestCommitId;
+    private recordAndWarnBaseCommitResolutionFailure;
+    private getLlmAiAttributes;
+    /**
+     * Resolve a JWT for the npm-registry fetch, blocking briefly on the
+     * first `tokenUpdated` event when no JWT is yet primed. The
+     * `TemplateRenderer` prefetch fires during AiService construction —
+     * before the `tokenManager` subscription has emitted — so a synchronous
+     * `getNpmRegistryJwt()` would observe `undefined` and silently downgrade the
+     * private-registry install to public npm. Blocking here is the
+     * narrowest fix: callers that already have a primed JWT take the fast
+     * path and never await.
+     */
+    private waitForNpmRegistryJwt;
+    /**
+     * Resolve when the next `tokenUpdated` event lands on `tokenManager`,
+     * or reject when `timeoutMs` elapses without one. When no
+     * `tokenManager` is wired (test fixtures, SaaS paths without push
+     * refresh), resolves immediately on the next microtask.
+     *
+     * Resolution only signals "a wait completed" — never that a JWT actually
+     * changed. The constructor's `tokenUpdated` listener (above) is the only
+     * code that mutates `tokenManagerJwt`. Callers (`waitForNpmRegistryJwt`, the
+     * npm-registry `refreshJwt` adapter) must re-read the JWT after this
+     * resolves and treat an unchanged value the same as a refresh that
+     * never happened.
+     */
+    private waitForTokenUpdate;
+    private createClarkTagProviderFactory;
+    /**
+     * Non-throwing AI quota check. Returns `{ allowed: true }` when the org is
+     * within its limit, and also when the check itself can't run (no JWT, or the
+     * quota endpoint errors) — callers fail open so a flaky quota service never
+     * blocks legitimate work. When the org is over limit, returns the reason and
+     * a user-facing message instead of throwing, so callers that don't surface
+     * exceptions (e.g. the background migration turn) can react.
+     * Logic lives in `quota-client.ts` (with the `quota.check` span).
+     */
+    private checkAiQuota;
+    private ensureAiQuotaAvailable;
+    /**
+     * Fires the internal, UI-invisible migration turn if the app is post-flip
+     * and still has `seed_api` checklist items pending. Safe to call multiple
+     * times — the `migrationTurnTriggered` guard ensures one-shot semantics
+     * per ai-service lifetime. The disk checklist is the recovery source of
+     * truth across process restarts.
+     *
+     * Primary auto-trigger: readiness gate (`notifyMigrationAppArtifactsReady`,
+     * `handleUserConnected`, `updateClarkJwt`) →
+     * `tryAutoDispatchMigrationTurnIfReady` → `maybeAutoDispatchMigrationTurn`.
+     * Backup caller: the UI RPC (see v1.ai.triggerMigrationTurn) once it
+     * observes the post-flip state via /sb-migration-status.
+     * User retry after unresolved failures: UI RPC with
+     * `retryMode: "focused-debug"` after /sb-migration-retry-unresolved.
+     */
+    handleAiTriggerMigrationTurn(request: {
+        jwt: string;
+        llmConfig: LLMProviderConfig;
+        retryMode?: "focused-debug";
+        triggeredBy?: MigrationUsageMetadata["triggeredBy"];
+    }): Promise<{
+        dispatched: boolean;
+        reason?: string;
+    }>;
+    private getMigrationSafeLlmConfig;
+    private migrationTurnTriggered;
+    /**
+     * Rejects prompt submission while a policy gate run is executing against the
+     * current application so concurrent Clark activity cannot mutate the app
+     * mid-run (APPS-4466). Enforced here at the dev server, not only in the UI.
+     */
+    private assertNoActivePolicyGateRun;
+    /**
+     * Run the pre-call quota check for an incoming user request. If quota is
+     * denied with a recognized paywall reason, persist the prompt + advice
+     * and open the modal via `handlePreCallPaywall`, and return `true` so
+     * the caller can short-circuit. Returns `false` if quota is fine.
+     * Non-paywall errors from the quota check are re-thrown unchanged.
+     *
+     * Shared between `handleAiGenerate` (the normal entry point) and
+     * `interruptAndContinue` (the interrupt-mid-generation entry point) so
+     * both surfaces produce the same user-visible behavior on quota denial —
+     * chat record + modal — instead of the interrupt path silently rejecting
+     * with no UI state. (APPS-4080)
+     */
+    private tryHandlePaywallForRequest;
+    private publishUserInput;
+    /**
+     * Persist the user's prompt + the "credits ran out" advice and open the
+     * paywall modal when the pre-call quota check denies the request. Mirrors
+     * what `idle.ts:AGENT_CANCELED` does for the mid-stream paywall path so
+     * both paths leave an identical chat record. Used only when
+     * `ensureAiQuotaAvailable` throws a paywall error in `handleAiGenerate`.
+     *
+     * - For organic user prompts (no `responseMetadata`), persists via
+     *   `recordUser`.
+     * - For widget responses (`multi_choice_response`, `plan_response`,
+     *   `confirm_response`, `searchable_dropdown_response`,
+     *   `remember_knowledge_draft_response`), persists via
+     *   `recordUserResponse` with the full metadata — without this, the
+     *   user's exact choice is silently dropped (they lose their selection
+     *   from chat history AND the resume turn's LLM has no record of what
+     *   they picked). Mirrors `agent-planning.ts:USER_SENT_PROMPT`.
+     * - `tool_permission_response` is intentionally NOT persisted — those
+     *   responses don't have a chat representation; the approval is just
+     *   side-effect state. On resume the user will see the permission
+     *   prompt again, which is acceptable UX.
+     * - Uses fire-and-forget peer pushes after each `await` on the store so
+     *   the chat is durable across refresh even if the live peer push drops.
+     */
+    private handlePreCallPaywall;
+    handleAiGenerate(request: AiGenerateRequest, inputSource?: AiInputSource): Promise<void>;
+    handleAiSummarizeApiUsage(request: AiSummarizeApiUsageRequest): Promise<void>;
+    handleAiSummarizeError(request: AiSummarizeErrorRequest): Promise<void>;
+    handleAiLabelAttachment(request: AiLabelAttachmentRequest): Promise<AiLabelAttachmentResponse>;
+    /**
+     * Converts an attachment to the appropriate LLM content part.
+     */
+    private attachmentToContentPart;
+    private submitAcceptanceEvaluation;
+    handleUserAcceptedDraft(silently?: boolean): Promise<void>;
+    handleUserRejectedDraft(silently?: boolean): Promise<void>;
+    /**
+     * Called when the user closes the integration setup form via the X button.
+     * Clears backend state so Clark knows the form is no longer open.
+     */
+    handleIntegrationSetupClosed(): Promise<void>;
     handleUserCanceled(): Promise<void>;
-    handleBuildSystemError(error: Error): void;
+    /**
+     * UI-initiated cancellation of a background task. Delegates to
+     * `TaskStore.cancel`, which aborts the local poll loop and best-effort
+     * invokes the task type's `cancel` hook on the external system. The
+     * status listener wired in the constructor pushes the resulting
+     * `cancelled` summary to the UI; this method just returns whether a
+     * transition actually happened so the thunk can short-circuit retries.
+     *
+     * `callerUserId` is the JWT-derived identity of the RPC caller (the
+     * socket handler extracts it from `peerAuthorization`). When the
+     * target task has a recorded `ownerUserId` that does not match, we
+     * return the same `{ cancelled: false }` no-op as the unknown /
+     * already-terminal cases. This is intentional: surfacing a distinct
+     * "not your task" error would let a malicious caller probe the
+     * existence of other users' task IDs. See PR #19718 review feedback.
+     *
+     * Returns `{ cancelled: false }` when:
+     *   - the background-tasks framework is disabled
+     *   - the task is unknown or already terminal
+     *   - the caller is not the task's owner
+     */
+    cancelBackgroundTask(taskId: string, callerUserId?: string): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Submit a prompt with interrupt behavior.
+     * If not busy, starts immediately. Otherwise interrupts and continues.
+     */
+    handleAiGenerateWithQueue(request: AiGenerateRequest, mode: "queue" | "interrupt", inputSource?: AiInputSource): Promise<{
+        generationId?: string;
+        status: "started" | "interrupted";
+    }>;
+    /**
+     * Interrupt current generation and continue with new prompt.
+     * The partial response is preserved in chat history for context.
+     */
+    private interruptAndContinue;
+    /**
+     * Wait for the FSM to transition out of busy state after abort.
+     *
+     * Resolves when idle, rejects after 20s. The caller must NOT replace
+     * the AbortController before this settles — the running generation
+     * re-reads the signal on each streamText / tool call and would
+     * "un-abort" itself if given a fresh controller.
+     */
+    private waitForAbortComplete;
+    handleSkipTestCase(testRunId: string, testCaseId: string): Promise<void>;
+    private scheduleToolPermissionReplayWindow;
+    private scheduleToolPermissionExpiry;
+    /**
+     * `userSentPrompt` is only valid from Idle or AwaitingUser. A parked
+     * permission can expire while a sibling tool is still generating; wait
+     * until the continuation can actually run, or abort if the request is gone.
+     */
+    private waitUntilToolPermissionContinuationAllowed;
+    private scheduleToolPermissionReplay;
+    handleAiRespondToToolPermission(request: ToolPermissionResponseRequest): Promise<void>;
+    private handleToolPermissionOutcome;
+    /**
+     * Builds a continuation prompt when a tool permission is denied.
+     * For testApi, provides specific guidance to continue testing other APIs.
+     */
+    private buildDenialContinuationPrompt;
+    resolveGenerationStateForUi(): import("@superblocksteam/library-shared/types").AiGenerationStateSnapshot | undefined;
+    /**
+     * A gateway peer asked for a turn. Clark's pushes and tool callbacks for it
+     * are routed to that peer for as long as it is attached, without giving it
+     * the editor binding: a browser tab opening or closing mid-turn changes
+     * nothing about where the turn reports.
+     *
+     * `turnId` is the correlator the caller sent with the prompt, and is what
+     * lets that same caller reacquire this turn on a replacement socket.
+     * Returned so the caller can be told which turn it now owns; a turn started
+     * without one is reachable by this socket alone.
+     */
+    beginHeadlessTurn(peer: EditorClient, peerId: string, turnId?: string, liveness?: PeerConnectionLiveness): string | undefined;
+    /**
+     * A gateway peer offered the correlator of a turn in flight, which is what a
+     * reattach looks like: the peer that started the turn lost its socket, so the
+     * turn moves onto the replacement.
+     *
+     * Runs on every authorized gateway RPC, so the two uninteresting outcomes —
+     * the caller already owns the turn, or is talking about a turn that is not
+     * this one — are silent. Only an actual handover is worth a line.
+     */
+    claimHeadlessTurn(peer: EditorClient, peerId: string, turnId?: string, liveness?: PeerConnectionLiveness): void;
+    /**
+     * The prompt a turn was bound for never started, so there is no generation
+     * coming that could settle it. Scoped to the exact turn: a reattach or a
+     * later turn may already own routing.
+     */
+    abandonHeadlessTurn(peerId: string, turnId?: string): void;
+    /**
+     * The gateway peer went away. Only the peer still holding the turn can end
+     * it, so a socket that a reattach already replaced cannot strip routing from
+     * its successor.
+     */
+    endHeadlessTurn(peerId: string, turnIdOrLiveness?: string | PeerConnectionLiveness): void;
+    handleUserConnected(peer: EditorClient, peerId: string, liveness?: PeerConnectionLiveness): void;
+    /**
+     * Per-session set of peer IDs that connected since their last task
+     * resync drained. Populated by `handleUserConnected`, drained inside
+     * `notifyAuthenticatedRpc` exactly once per (connect, first auth
+     * success) pair — so a fresh tab gets the active task list as soon
+     * as auth is proven, but never before.
+     */
+    private readonly pendingTaskResyncPeerIds;
+    /**
+     * The authenticated peer's identity, but only while that same peer is
+     * still the bound `stablePeer`. `handleUserConnected` can swap in a
+     * replacement peer before the previous peer's disconnect is processed;
+     * keying the identity to its peerId means a live status push in that
+     * window is gated against `undefined` (suppressed) rather than the
+     * previous user — closing the cross-user leak in PR #19718 Comment 59.
+     * Returns `undefined` until the currently-bound peer proves auth via
+     * `notifyAuthenticatedRpc`, so owned-task pushes fail closed.
+     */
+    private getAuthenticatedPeerUserId;
+    /**
+     * Hook for the socket-manager auth middleware to call after every
+     * successful authorization check. The first call per peer drains any
+     * deferred state pushes registered by `handleUserConnected` (today:
+     * the active background-task summary resync). Subsequent calls for
+     * the same connection are no-ops; the set is repopulated on the
+     * next connect/reconnect.
+     *
+     * `callerUserId` is the JWT-derived identity of the just-authenticated
+     * RPC caller. The resync filters by `isTaskAccessibleTo(task, callerUserId)`
+     * so user B reconnecting to an AiService that's running user A's task
+     * does not receive A's `taskId` / label / message. Tasks with no
+     * recorded `ownerUserId` (legacy/local-dev) remain visible to anyone,
+     * matching the LLM-facing `listTasks` semantics.
+     *
+     * NOTE: The legacy `aiSetGenerationState` / tool-permission pushes
+     * in `handleUserConnected` have the same pre-auth exposure but are
+     * out of scope for this gate — they were not introduced by the
+     * background-task framework. Move them here when tightening that
+     * threat surface (see PR #19718 review feedback).
+     */
+    notifyAuthenticatedRpc(peerId: string, callerUserId?: string): void;
+    /**
+     * @param replacement An editor socket that is still attached. Clark's RPCs
+     * are bound to one peer at a time, so when the departing peer was the bound
+     * one, handing the binding to a survivor keeps API execution working for
+     * whoever is still watching. Without it those calls queue for a peer that
+     * will never answer — the case a headless build leaves behind when its
+     * gateway socket closes over an open editor tab.
+     */
+    handleUserDisconnected(peerId: string, replacement?: {
+        liveness?: PeerConnectionLiveness;
+        peer: EditorClient;
+        peerId: string;
+    }, liveness?: PeerConnectionLiveness): void;
+    private clearPeerConnection;
+    handleBuildSystemError(error: Error, phase?: BuildErrorPhase): void;
+    handleRuntimeError(errorData: RuntimeErrorData): void;
+    handleClearRuntimeError(id: string): void;
+    handleConsoleLog(logEntry: ConsoleLogEntry): void;
+    handleApiRunRecord(apiId: string, runRecord: ApiRunRecord): void;
+    handleClearRuntimeErrors(before?: number): void;
+    handleClearBuildSystemErrors(source?: BuildSystemError["source"]): void;
+    handlePromptInterpretation(request: {
+        prompt: string;
+        jwt: string;
+        promptContext?: PromptContext;
+    }): Promise<void>;
+    /**
+     * Handles judge evaluation requests.
+     *
+     * Evaluates an application against a prompt using the judge system.
+     * The evaluation is automatically stored to CSV for later analysis.
+     *
+     * @param request - Judge evaluation request
+     * @returns Evaluation result with scores and feedback
+     */
+    handleJudgeEvaluation(request: {
+        promptId: string;
+        prompt: string;
+        appId: string;
+        appUrl: string;
+        jwt: string;
+        llmConfig?: LLMProviderConfig;
+        options?: Partial<JudgeEvaluationOptions>;
+        storageStateData?: any;
+    }): Promise<JudgeEvaluationResult>;
+    handlePolicyGateExecution(request: {
+        adminPrompt?: string;
+        aiAgentRunId: string;
+        applicationId: string;
+        jwt?: string;
+        llmConfig?: LLMProviderConfig;
+        reviewPolicyId: string;
+        scanScopeJson?: ScanScopeJson;
+    }): Promise<ReportReviewRunInput & {
+        runtimeMetadataJson?: Record<string, unknown>;
+    }>;
+    handleUserChange(change: UserChange): void;
+    handleNewChat(): Promise<void>;
+    /** Clears local LLM context so migration-era memory does not survive abort. */
+    clearMigrationAbortLocalContext(): Promise<void>;
+    /**
+     * Upload the (now-empty) context to Bucketeer.
+     * commitId is captured before newChat() clears the session.
+     * Failures are logged but do not fail clear chat.
+     */
+    private uploadEmptyContextToBucketeer;
+    /**
+     * Returns all saved app skill facts for the current application.
+     */
+    getAppFacts(): Promise<AiAppFact[]>;
+    /**
+     * Deletes an app skill fact by its virtual path.
+     */
+    deleteAppFact(virtualPath: string): Promise<void>;
+    /**
+     * Toggles the isEnabled field of an app skill fact and returns the updated fact.
+     */
+    toggleAppFact(virtualPath: string, isEnabled: boolean): Promise<AiAppFact>;
+    /**
+     * Move an app skill fact to org/user/integration scope.
+     */
+    moveAppFact(payload: AiMoveAppKnowledgeRequest): Promise<AiMoveAppKnowledgeResult>;
+    handleRestoreToCommit(sinceTimestamp: number, commitId: string, applicationId: string, branchName: string): Promise<void>;
+    handleApiUpdate(update: ApiUpdate): Promise<void>;
     isBusy(): boolean;
+    isAwaitingUser(): boolean;
+    /**
+     * True when finalize (or similar) must wait for the user to resolve an
+     * interactive prompt or tool-permission widget. Unlike {@link isAwaitingUser},
+     * Clark's resting `AwaitingUser` FSM state after a completed turn does not
+     * count — only outstanding interactive/deferred messages or pending tool
+     * permissions block.
+     *
+     * Advice-only `AGENT_NEEDS_USER_INPUT` handoffs (plain assistant text,
+     * no widget) intentionally do not block: the migration UI gate
+     * (`hasActiveInteractivePrompt`) uses the same narrow signal.
+     */
+    isAwaitingInteractiveResponse(): boolean;
+    /**
+     * Check if Clark is currently generating code.
+     * Used by lock-service to determine if lock should be held during generation.
+     * @returns true if Clark is in a generating state (AgentPlanning, LLMGenerating, PostProcessing, RuntimeReviewing)
+     */
+    isGenerating(): boolean;
+    /**
+     * Wait for Clark generation to complete.
+     * Generation means that Clark is either in Plan Mode or Build Mode
+     * If Clark is not currently generating, resolves immediately.
+     * Used by lock-service to wait for generation before releasing lock.
+     * @returns Promise that resolves when generation completes (or immediately if not generating)
+     */
+    waitUntilGenerationComplete(): Promise<void>;
+    /**
+     * Resolve generation waiters when Clark reaches a terminal state.
+     */
+    private triggerGenerationComplete;
+    isGeneratingFullAppOrBroadUpdate(): Promise<boolean>;
+    setSourceTracker(sourceTracker: SourceTracker | undefined): void;
+    setFileSystemManager(fileSystemManager: FileSystemManager): void;
+    setViteServer(server: ViteDevServer): void;
+    getViteServer(): ViteDevServer | undefined;
+    private getLLMProviderSettings;
 }
 //# sourceMappingURL=index.d.ts.map