@superblocksteam/vite-plugin-file-sync 2.0.123 → 2.0.124-next.1

package/dist/ai-service/index.js

@@ -1,30 +1,35 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { generateObject, hasToolCall, } from "ai";
+import { generateObject, hasToolCall, stepCountIs, streamText as aiStreamText, } from "ai";
 import { z } from "zod";
 import { AiMode, resolveAttachmentFileName, } from "@superblocksteam/library-shared/types";
 import { addTracingToMethods, classifyAttachmentDelivery, FactAccessType, FactCreatedSource, FactEntityScope, TracedEventEmitter, } from "@superblocksteam/shared";
 import { buildTranslationPrompt } from "../migration/translation-prompt.js";
 import { getErrorMeta, getLogger, setDefaultLogger } from "../util/logger.js";
+import { composeSecurityAgentPrompt, } from "./agent/prompts/build-security-scan-prompt.js";
 import { getToolCallArguments, getToolErrorCode, getToolOutput, } from "./agent/tool-message-utils.js";
+import { buildSecurityScanTools, } from "./agent/tools.js";
 import { hasPendingEscalations, flushPendingEscalations, } from "./agent/tools/apis/api-validation-orchestrator.js";
 import { safeSampleJson } from "./agent/tools/apis/sample-json.js";
 import { resolveSdkApiEntryPoint } from "./agent/tools/apis/sdk-registry.js";
 import { readFile } from "./agent/tools/build-read-file.js";
 import { debugCache } from "./agent/tools/debug-cache.js";
 import { buildReadFileToolFactory } from "./agent/tools/index.js";
+import { securityScanResultSchema, } from "./agent/tools/report-security-findings.js";
 import { SessionEntityPermissionStore, } from "./agent/tools2/entity-permissions.js";
 import { ToolRegistry } from "./agent/tools2/registry.js";
 import { explainCodeFinalizeToolFactory } from "./agent/tools2/tools/explain-code-finalize.js";
 import { FileSystemInterface } from "./app-interface/file-system-interface.js";
 import { createDefaultVirtualFileSystem, createPathValidator, } from "./app-interface/filesystem/index.js";
+import { NpmPackageLookup } from "./app-interface/npm-package-lookup.js";
+import { NpmRegistryClient, createDiskRegistryPolicyStore, } from "./app-interface/npm-registry.js";
 import { AppShell } from "./app-interface/shell.js";
 import { AppSkillsManager } from "./app-skills/manager.js";
 import { isUploadedAttachment, toUploadedAttachmentContentPart, } from "./attachments/uploaded-content-part.js";
 import { ChatSessionStore } from "./chat/chat-session-store.js";
 import { normalizeTextAttachmentForModel } from "./chat/utils.js";
-import { API_MIGRATION_ORIGINS, readPersistedChecklist, } from "./checklist/persisted-checklist-store.js";
+import { API_MIGRATION_ORIGINS, readPersistedChecklist, updateChecklistItem, } from "./checklist/persisted-checklist-store.js";
 import { downloadContextFromBucketeer, restoreContextFromCheckpoint, } from "./context-download.js";
 import { uploadContextToBucketeer } from "./context-upload.js";
 import { AppContextStore } from "./context/app-context.js";
@@ -35,7 +40,9 @@ import { CsvJudgeStorage } from "./judge/storage/csv-storage.js";
 import { KnowledgeManager } from "./knowledge/knowledge-manager.js";
 import { createChaosFetch } from "./llm/chaos-fetch.js";
 import { LLMClient } from "./llm/client.js";
+import { selectContextManagementStrategy, } from "./llm/context-v2/context-management.js";
 import { ContextManagerV2 } from "./llm/context-v2/manager.js";
+import { JsonlEventStore } from "./llm/context-v2/storage/jsonl-event-store.js";
 import { LocalContextStorageV2 } from "./llm/context-v2/storage/local.js";
 import { createLLMProvider } from "./llm/provider.js";
 import { traceLLM } from "./llmobs/helpers.js";
@@ -62,12 +69,145 @@ import { transitionFrom } from "./state-machine/helpers/transition.js";
 import { TemplateRenderer } from "./template-renderer.js";
 import { createJsonStreamParser } from "./util/json-stream-parser.js";
 import { processLLMConfig } from "./util/llm-config-utils.js";
+import { buildModeMessage } from "./util/mode-message.js";
 import { parseJwt } from "./util/parse-jwt.js";
 import { getToolCallSignature } from "./util/tool-signature.js";
 export { AiServiceFeatureFlags } from "./features.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 function buildLastKnownPolicyStore(opts) {
+    return createDiskRegistryPolicyStore(opts);
+}
+const MAX_POLICY_GATE_STREAM_ERRORS = 5;
+const MAX_POLICY_GATE_STREAM_ERROR_ARRAY_LENGTH = 10;
+const MAX_POLICY_GATE_STREAM_ERROR_FIELD_LENGTH = 500;
+const MAX_POLICY_GATE_STREAM_ERROR_OBJECT_DEPTH = 3;
+const MAX_POLICY_GATE_STREAM_ERROR_OBJECT_KEYS = 20;
+const POLICY_GATE_STREAM_ERROR_REDACTED_VALUE = "[redacted]";
+const POLICY_GATE_STREAM_ERROR_SECRET_KEY_PATTERN = /(access[-_]?key|api[-_]?key|authorization|connection[-_]?string|credential|dsn|password|private[-_]?key|secret|token)/i;
+const POLICY_GATE_STREAM_ERROR_SECRET_VALUE_PATTERN_SOURCES = [
+    String.raw `\bbearer\s+[a-z0-9._~+/=-]+`,
+    String.raw `\bhttps?:\/\/[^@\s/:]+:[^@\s]+@\S+`,
+    String.raw `\b(?:mongodb(?:\+srv)?|mysql|postgres(?:ql)?|snowflake):\/\/\S+`,
+    String.raw `\bA[SK]IA[0-9A-Z]{16}\b`,
+    String.raw `\bgh[pousr]_[a-z0-9_]{20,}\b`,
+    String.raw `\bsk-[a-z0-9_-]{8,}\b`,
+    String.raw `\bxox[baprs]-[a-z0-9-]{10,}\b`,
+];
+function truncatePolicyGateStreamErrorField(value) {
+    if (value.length <= MAX_POLICY_GATE_STREAM_ERROR_FIELD_LENGTH) {
+        return value;
+    }
+    return `${value.slice(0, MAX_POLICY_GATE_STREAM_ERROR_FIELD_LENGTH)}...`;
+}
+function sanitizePolicyGateStreamErrorString(value) {
+    const redacted = POLICY_GATE_STREAM_ERROR_SECRET_VALUE_PATTERN_SOURCES.reduce((current, patternSource) => current.replace(new RegExp(patternSource, "gi"), POLICY_GATE_STREAM_ERROR_REDACTED_VALUE), value);
+    return truncatePolicyGateStreamErrorField(redacted);
+}
+function isUnhelpfulPolicyGateStreamError(serialized) {
+    return (Object.keys(serialized).length === 1 &&
+        serialized.message === "[object Object]");
+}
+function serializePolicyGateStreamError(error, streamPart) {
+    const attachStreamPartIfUseful = (serialized) => {
+        if (isUnhelpfulPolicyGateStreamError(serialized) &&
+            streamPart &&
+            typeof streamPart === "object") {
+            return {
+                ...serialized,
+                streamPart: serializePolicyGateStreamErrorRecord(streamPart, 0),
+            };
+        }
+        return serialized;
+    };
+    if (error instanceof Error) {
+        const serialized = {
+            message: sanitizePolicyGateStreamErrorString(error.message),
+            name: error.name,
+        };
+        const extraFields = serializePolicyGateStreamErrorRecord(error, 0);
+        return attachStreamPartIfUseful({
+            ...extraFields,
+            ...serialized,
+        });
+    }
+    if (error && typeof error === "object") {
+        const serialized = serializePolicyGateStreamErrorRecord(error, 0);
+        if (Object.keys(serialized).length > 0) {
+            return attachStreamPartIfUseful(serialized);
+        }
+    }
+    return attachStreamPartIfUseful({
+        message: truncatePolicyGateStreamErrorField(String(error)),
+    });
+}
+function serializePolicyGateStreamErrorValue(value, depth) {
+    if (typeof value === "string") {
+        return sanitizePolicyGateStreamErrorString(value);
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null) {
+        return value;
+    }
+    if (value instanceof Error) {
+        return {
+            ...serializePolicyGateStreamErrorRecord(value, depth + 1),
+            message: sanitizePolicyGateStreamErrorString(value.message),
+            name: value.name,
+        };
+    }
+    if (Array.isArray(value)) {
+        if (depth >= MAX_POLICY_GATE_STREAM_ERROR_OBJECT_DEPTH) {
+            return `[array:${value.length}]`;
+        }
+        return value
+            .slice(0, MAX_POLICY_GATE_STREAM_ERROR_ARRAY_LENGTH)
+            .map((item) => serializePolicyGateStreamErrorValue(item, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        if (depth >= MAX_POLICY_GATE_STREAM_ERROR_OBJECT_DEPTH) {
+            return "[object]";
+        }
+        return serializePolicyGateStreamErrorRecord(value, depth + 1);
+    }
+    if (value === undefined) {
+        return undefined;
+    }
+    return sanitizePolicyGateStreamErrorString(String(value));
+}
+function serializePolicyGateStreamErrorRecord(value, depth) {
+    const output = {};
+    for (const key of Object.keys(value).slice(0, MAX_POLICY_GATE_STREAM_ERROR_OBJECT_KEYS)) {
+        if (POLICY_GATE_STREAM_ERROR_SECRET_KEY_PATTERN.test(key)) {
+            output[key] = POLICY_GATE_STREAM_ERROR_REDACTED_VALUE;
+            continue;
+        }
+        const fieldValue = value[key];
+        const serializedValue = serializePolicyGateStreamErrorValue(fieldValue, depth);
+        if (serializedValue !== undefined) {
+            output[key] = serializedValue;
+        }
+    }
+    return output;
+}
 // Helper functions for console log and runtime error buffer management
 export function pruneByTTL(items, ttlMs) {
     const now = Date.now();
@@ -89,6 +229,29 @@ export function estimateSize(obj) {
         return 0;
     }
 }
+/**
+ * How long the npm-registry client's `getJwt` will block waiting for the
+ * first `tokenUpdated` event when no JWT is yet primed. Kept conservative —
+ * a cold prefetch that misses the window degrades to last-known-good or
+ * not-configured rather than crashing the install path.
+ */
+const NPM_REGISTRY_JWT_WAIT_MS = 5_000;
+/**
+ * How long the npm-registry client will wait for a fresh `tokenUpdated`
+ * event between an HTTP 401 and its retry.
+ *
+ * Two failure modes for the refresh:
+ *   - `waitForTokenUpdate` times out (push-refresh channel hung): the
+ *     adapter throws, the client treats it as a refresh-channel failure
+ *     and routes through `serveStaleOrUnconfigured` rather than retrying
+ *     with the stale JWT — the install path gets last-known-good (or
+ *     `not-configured`).
+ *   - No `tokenManager` is wired (SaaS without push refresh, some test
+ *     fixtures): the adapter resolves immediately on the next microtask;
+ *     the retry runs with the existing JWT, and a second 401 hard-throws
+ *     via the second-401 branch in `NpmRegistryClient.fetchWithRefresh`.
+ */
+const NPM_REGISTRY_REFRESH_WAIT_MS = 5_000;
 export function truncateString(str, maxBytes) {
     // Rough approximation: assume 2 bytes per character
     const maxChars = Math.floor(maxBytes / 2);
@@ -148,6 +311,39 @@ export class AiService extends TracedEventEmitter {
     entityPermissionStore = new SessionEntityPermissionStore();
     _onGenerationCompleteCallback;
     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.
+     */
+    handleTokenUpdated(event) {
+        try {
+            this.tokenManagerJwt = event.token;
+            this.getLogger().info(`[ai-service] token updated via tokenManager`);
+        }
+        catch (err) {
+            console.error("[ai-service] tokenUpdated listener threw", err);
+        }
+    }
+    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`.
+     */
+    npmPackageLookup;
     viteServer;
     mcpServerManager;
     recordingManager;
@@ -163,6 +359,21 @@ export class AiService extends TracedEventEmitter {
     get clarkState() {
         return this.clark.state;
     }
+    /**
+     * 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() {
+        return this.npmRegistryClient;
+    }
     /**
      * Injects git and sync services for the git tool (called by the plugin when native git is available).
      */
@@ -292,6 +503,71 @@ export class AiService extends TracedEventEmitter {
             // Keep this opt-out alongside the injected model factory.
             useSuperblocksAuthorizationHeader: config.providerSettings?.useSuperblocksAuthorizationHeader,
         };
+        // Seed `tokenManagerJwt` synchronously from the manager's current
+        // value before any consumer that calls `getJwt()` is constructed. The
+        // `tokenUpdated` listener below covers FUTURE refreshes; this read
+        // covers the cold-start case where the CLI (or any earlier code) has
+        // already called `tokenManager.updateToken(...)` before this AiService
+        // was constructed. Without it, the prior emission is lost — Node
+        // `EventEmitter` has no replay — and `NpmRegistryClient.getJwt()`
+        // would time out via `waitForJwt(...)`, downgrading `syncHomeNpmrc`
+        // to `unreachable` and leaving `~/.npmrc` unwritten on cold boot.
+        this.tokenManagerJwt = this.config.tokenManager?.getCurrentToken();
+        // Resolve the npm registry client once and reuse across TemplateRenderer
+        // and AppShell so both install paths share the same in-memory cache and
+        // 401-refresh state. Explicit injection wins (tests); otherwise we
+        // construct a default that reads the LD flag from `config.features` and
+        // routes JWT through the AiService's own `getJwt()` (which prefers the
+        // tokenManager token and falls back to clark.context.jwt). Empty
+        // tokens are refused upstream of `attempt()` so the server doesn't
+        // see `Bearer ` and reply 400 (which the client would now treat as a
+        // hard fail rather than a transient outage).
+        //
+        // APPS-4370. Wire the disk-backed `LastKnownRegistryPolicyStore` here
+        // so the production client carries `everConfigured` end-to-end. Without
+        // this the unreachable short-circuit in AppShell is inert: the marker
+        // writer is fire-and-forget and `hasEverBeenConfigured()` always
+        // resolves false when no store is wired. `rootDir` is `os.homedir()`
+        // for the same reason the home-npmrc writer roots at
+        // `~/.superblocks/...`: the marker lives next to the existing
+        // CLI-managed state and survives application-directory recycles.
+        const npmRegistryClient = config.npmRegistryClient ??
+            new NpmRegistryClient({
+                isFlagEnabled: () => config.features.npmRegistryEnabled === true,
+                // The prefetch can fire before tokenManager has primed
+                // `tokenManagerJwt`. Block (with a short timeout) on the next
+                // `tokenUpdated` event rather than throwing immediately, so the
+                // first install in the shared template dir actually gets a
+                // `.npmrc` instead of silently downgrading to "not configured".
+                getJwt: () => this.waitForJwt(NPM_REGISTRY_JWT_WAIT_MS),
+                // Push-based refresh hook: on 401, wait briefly for the next
+                // `tokenUpdated` event before re-reading the JWT. Without this,
+                // a 401 retry fires immediately with the same expired token and
+                // throws `re-authenticated and still received HTTP 401` for any
+                // user whose JWT expired mid-install.
+                refreshJwt: () => this.waitForTokenUpdate(NPM_REGISTRY_REFRESH_WAIT_MS),
+                organizationId: config.organizationId,
+                baseUrl: config.superblocksBaseUrl,
+                lastKnownPolicyStore: buildLastKnownPolicyStore({
+                    organizationId: config.organizationId,
+                    rootDir: config.policyStoreRootDir ?? os.homedir(),
+                }),
+            });
+        this.npmRegistryClient = npmRegistryClient;
+        // One process-lifetime `NpmPackageLookup` shared across every
+        // `buildTools()` call. The `build_lookupNpmPackage` tool factory used
+        // to construct a fresh instance per LLM turn; each construction
+        // registered an `ObservableGauge` callback for
+        // `superblocks.npm.lookup.cache_size` that the OTel API keeps strongly
+        // referenced for the lifetime of the meter. `ToolRegistry.clear()`
+        // does not dispose tool resources, so every cleared instance's callback
+        // (and the cache it closed over) stuck around for the process lifetime
+        // and emitted multiple same-instrument/same-attribute observations per
+        // collection cycle. Owning the lookup here — same pattern as
+        // `npmRegistryClient` / `templateRenderer` / `appShell` — means the
+        // gauge wires up exactly once and the 60s TTL cache stays warm across
+        // turns instead of being thrown away.
+        this.npmPackageLookup = new NpmPackageLookup({ client: npmRegistryClient });
         this.templateRenderer =
             config.templateRenderer ??
                 new TemplateRenderer({
@@ -301,6 +577,7 @@ export class AiService extends TracedEventEmitter {
                     // process.cwd() — process.cwd() is fragile in CI matrix shards and
                     // monorepo sub-invocations. See PR #19282 (F3).
                     detectionCwd: config.appRootDirPath,
+                    npmRegistryClient,
                 });
         // Create KnowledgeManager before AppShell so it can be passed to VirtualFileSystem
         this.knowledgeManager = new KnowledgeManager();
@@ -309,6 +586,7 @@ export class AiService extends TracedEventEmitter {
             fsOperationQueue: config.fsOperationQueue,
             draftInterface: config.draftInterface,
             templateRenderer: this.templateRenderer,
+            npmRegistryClient,
             virtualFileSystem: createDefaultVirtualFileSystem({
                 useSystemSkills: config.features.useSystemSkills,
                 knowledgeManager: this.knowledgeManager,
@@ -344,15 +622,13 @@ export class AiService extends TracedEventEmitter {
             logger: config.logger,
         });
         if (this.config.tokenManager) {
-            this.config.tokenManager.on("tokenUpdated", (event) => {
-                this.tokenManagerJwt = event.token;
-                this.getLogger().info(`[ai-service] token updated via tokenManager`);
-            });
+            this.config.tokenManager.on("tokenUpdated", this.handleTokenUpdated.bind(this));
         }
         this.clarkProfiler = new ClarkProfiler(this.sessionId);
         this.clarkProfiler.initialize(this.appShell);
         this.contextManagerV2 = new ContextManagerV2({
             storage: new LocalContextStorageV2(config.appRootDirPath),
+            eventStore: new JsonlEventStore(config.appRootDirPath),
             rootDir: config.appRootDirPath,
             getModeState: () => {
                 const mode = this.clark?.context?.currentMode;
@@ -363,7 +639,7 @@ export class AiService extends TracedEventEmitter {
                     planApproved: this.clark?.context?.planContext?.approved,
                 };
             },
-            remoteRestoreFallback: async () => {
+            remoteRestoreFallback: async (id) => {
                 const jwt = this.getJwt();
                 // Prefer the live sync service commitId (set after uploads), but on
                 // fresh pods downloadDirectory doesn't set it.  Fall back to the
@@ -382,6 +658,8 @@ export class AiService extends TracedEventEmitter {
                     superblocksBaseUrl: config.superblocksBaseUrl,
                     logger: this.getLogger(),
                     jwt,
+                    contextId: id,
+                    appRootDirPath: config.appRootDirPath,
                 });
             },
         });
@@ -489,6 +767,18 @@ export class AiService extends TracedEventEmitter {
         if (!checklist) {
             return;
         }
+        // Reset stale in_progress items to pending. After a dev-server restart,
+        // items left in_progress are not truly running — resetting them allows
+        // the UI polling trigger and backend handler to re-dispatch Clark.
+        const staleInProgressItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) && item.status === "in_progress");
+        for (const item of staleInProgressItems) {
+            await updateChecklistItem({
+                appRootDirPath: this.appRootDirPath,
+                itemId: item.id,
+                status: "pending",
+            });
+            this.getLogger().info(`[ai-service] Reset stale in_progress item "${item.id}" to pending after restart`);
+        }
         const hasPendingSeedApi = checklist.items.some((item) => API_MIGRATION_ORIGINS.has(item.origin) &&
             (item.status === "pending" || item.status === "in_progress"));
         if (hasPendingSeedApi) {
@@ -553,6 +843,20 @@ export class AiService extends TracedEventEmitter {
                     logger: this.getLogger(),
                     templateRenderer: this.templateRenderer,
                     appShell: this.appShell,
+                    // AiServiceConfig.npmRegistryClient is optional (injectable test
+                    // seam); the SDK's `dev()` never passes it in production, so
+                    // spreading `...this.config` above leaves it `undefined` and any
+                    // state-handler / tool that reads `services.npmRegistryClient`
+                    // sees nothing. The `build_lookupNpmPackage` tool's `!this.client`
+                    // branch silently downgraded to public npm because of this gap.
+                    // Carry the AiService's resolved instance through explicitly,
+                    // same pattern as `appShell` / `templateRenderer` above.
+                    npmRegistryClient: this.npmRegistryClient,
+                    // Pass the AiService's long-lived lookup so `build_lookupNpmPackage`
+                    // reuses one instance across LLM turns (gauge registered once,
+                    // cache warm). See the `npmPackageLookup` field comment for why
+                    // per-turn instantiation in the tool factory leaked OTel callbacks.
+                    npmPackageLookup: this.npmPackageLookup,
                     signals: this,
                     fileSystemInterface: this.fileSystemInterface,
                     integrationStore: this.integrationStore,
@@ -627,6 +931,79 @@ export class AiService extends TracedEventEmitter {
         // fallback to clark context if no token manager is provided
         return this.clark?.context?.jwt;
     }
+    buildContextManagementForCurrentClark(llmConfig) {
+        const modeInstructions = this.clark.context.currentMode
+            ? `Preserve the following mode context in your summary: ${buildModeMessage(this.clark.context.currentMode, this.clark.context.planContext?.approved)}`
+            : undefined;
+        return selectContextManagementStrategy({
+            serverContextManagementEnabled: llmConfig?.serverContextManagement?.enabled,
+            modeInstructions,
+            thresholds: llmConfig?.serverContextManagement,
+            summarizationModel: () => createLLMProvider(this.getLLMProviderSettings(llmConfig), () => this.getJwt(), llmConfig, () => ({
+                prompt_id: this.clark.context.promptId,
+                chatmessage_id: this.clark.context.chatmessageId,
+                application_id: this.config.applicationId,
+                session_id: this.sessionId,
+                mode: this.clark.context.currentMode === AiMode.PLAN ? "plan" : "build",
+                plan_size: this.clark.context.planSize,
+            })).modelForTask("summarizeMessages"),
+        });
+    }
+    /**
+     * 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
+     * `getJwt()` 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.
+     */
+    async waitForJwt(timeoutMs) {
+        const immediate = this.getJwt();
+        if (immediate) {
+            return immediate;
+        }
+        if (!this.config.tokenManager) {
+            throw new Error("[npm-registry] no JWT available and no tokenManager wired to wait for one");
+        }
+        await this.waitForTokenUpdate(timeoutMs);
+        const after = this.getJwt();
+        if (!after) {
+            throw new Error("[npm-registry] no JWT available after waiting for tokenManager update");
+        }
+        return after;
+    }
+    /**
+     * 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 (`waitForJwt`, 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.
+     */
+    waitForTokenUpdate(timeoutMs) {
+        const tokenManager = this.config.tokenManager;
+        if (!tokenManager) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const onUpdate = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                tokenManager.off("tokenUpdated", onUpdate);
+                reject(new Error(`[npm-registry] timed out after ${timeoutMs}ms waiting for tokenManager update`));
+            }, timeoutMs);
+            tokenManager.once("tokenUpdated", onUpdate);
+        });
+    }
     createClarkTagProviderFactory() {
         return (fsm) => {
             const clark = fsm;
@@ -652,11 +1029,19 @@ export class AiService extends TracedEventEmitter {
         }
         return (await response.json());
     }
-    async ensureAiQuotaAvailable(jwt) {
+    /**
+     * 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.
+     */
+    async checkAiQuota(jwt) {
         const token = jwt ?? this.getJwt();
         if (!token) {
             this.getLogger().warn("[ai-service] No JWT available for quota check, skipping");
-            return;
+            return { allowed: true };
         }
         try {
             const quota = await this.callServer({
@@ -670,14 +1055,19 @@ export class AiService extends TracedEventEmitter {
                     : reason === "no_seat_assigned"
                         ? "You don't have an AI Builder license assigned. Ask your admin to assign a license."
                         : "Your organization has reached its AI usage limit.";
-                throw new Error(`${message} [reason:${reason}]`);
+                return { allowed: false, reason, message };
             }
+            return { allowed: true };
         }
         catch (error) {
-            if (error instanceof Error && error.message.includes("[reason:")) {
-                throw error;
-            }
             this.getLogger().warn("[ai-service] Quota check failed, allowing request", getErrorMeta(error));
+            return { allowed: true };
+        }
+    }
+    async ensureAiQuotaAvailable(jwt) {
+        const quota = await this.checkAiQuota(jwt);
+        if (!quota.allowed) {
+            throw new Error(`${quota.message} [reason:${quota.reason}]`);
         }
     }
     /**
@@ -712,16 +1102,35 @@ export class AiService extends TracedEventEmitter {
         if (this.clark.context.pendingToolPermissionRequest) {
             return { dispatched: false, reason: "pending-tool-permission" };
         }
+        if (this.clark.state === ClarkStateNames.AwaitingUser) {
+            if (this.clark.context.activeInteractiveMessage ||
+                this.clark.context.deferredInteractiveMessage) {
+                return { dispatched: false, reason: "awaiting-interactive-response" };
+            }
+        }
         const checklist = await readPersistedChecklist(this.appRootDirPath);
         if (!checklist) {
             this.getLogger().warn("[ai-service] Migration checklist not found or unreadable; skipping translation turn");
             return { dispatched: false, reason: "checklist-unavailable" };
         }
-        const pendingSeedApiItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) && item.status === "pending");
+        const pendingSeedApiItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin) &&
+            (item.status === "pending" || item.status === "in_progress"));
         const pendingSeedApiCount = pendingSeedApiItems.length;
         if (pendingSeedApiCount === 0) {
             return { dispatched: false, reason: "no-pending-items" };
         }
+        // Pre-flight quota gate. The migration turn drives LLM inference (which
+        // doesn't enforce quota) followed by tool calls that hit quota-protected
+        // endpoints (e.g. attachment uploads via /api/v1/files). Without this gate
+        // an over-limit org burns more credits on the migration turn, then fails
+        // mid-turn with a generic "inference error" when a downstream tool call
+        // 429s. Fail fast with a clear reason before consuming any credits, the
+        // same pre-flight check handleAiGenerate already runs.
+        const quota = await this.checkAiQuota(request.jwt);
+        if (!quota.allowed) {
+            this.getLogger().warn("[ai-service] Skipping v2→v3 migration turn — AI quota exceeded", { reason: quota.reason });
+            return { dispatched: false, reason: "quota-exceeded" };
+        }
         this.migrationTurnTriggered = true;
         this.appShell.setApiHandlerEnabled(false);
         this.getLogger().info(`[ai-service] Dispatching internal v2→v3 migration turn for ${pendingSeedApiCount} API(s) (API VFS projection disabled, retryMode=${request.retryMode ?? "none"})`);
@@ -764,7 +1173,7 @@ export class AiService extends TracedEventEmitter {
     getMigrationSafeLlmConfig(llmConfig) {
         const result = filterDisabledToolsForMigration(llmConfig);
         if (result.removedTools.length > 0) {
-            this.getLogger().warn("[ai-service] Migration turn overrides operator-disabled tools required for migration: install/checklist/askMultiChoice", { removedTools: result.removedTools });
+            this.getLogger().warn("[ai-service] Migration turn overrides operator-disabled tools required for migration: install/checklist/askMultiChoice/build_navigatePreview/build_captureScreenshot", { removedTools: result.removedTools });
         }
         return result.config;
     }
@@ -814,6 +1223,7 @@ export class AiService extends TracedEventEmitter {
                 },
                 llmConfig: request.llmConfig,
                 partialResponse: undefined,
+                userPreferences: request.userPreferences,
             };
         });
         const transitionTo = transitionFrom(this.clark);
@@ -1688,12 +2098,13 @@ export class AiService extends TracedEventEmitter {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                // create a tool-error message with the error
+                // Provider-facing context expects tool failures to be encoded as
+                // errored tool results so they still satisfy the preceding tool call.
                 toolResultMessage = {
                     role: "tool",
                     content: [
                         {
-                            type: "tool-error",
+                            type: "tool-result",
                             toolCallId,
                             toolName,
                             output: {
@@ -1712,9 +2123,7 @@ export class AiService extends TracedEventEmitter {
                     type: "tool-error",
                     toolCallId,
                     toolName,
-                    error: typeof errorMessage === "string"
-                        ? errorMessage
-                        : JSON.stringify(errorMessage),
+                    error: errorMessage,
                     errorCode,
                 });
             }
@@ -1749,10 +2158,8 @@ export class AiService extends TracedEventEmitter {
             };
             logger.info(`[ai-service] Tool ${toolName} permission denied, error injected into context`);
         }
-        const llmProviderSettings = this.getLLMProviderSettings(llmConfig);
-        const llmProvider = createLLMProvider(llmProviderSettings, () => this.clark.context.jwt || "", llmConfig, undefined);
-        const summarizationModel = llmProvider.modelForTask("summarizeMessages");
-        const context = await this.contextManagerV2.getOrCreateContext(contextId, summarizationModel, llmConfig?.contextOptionsV2);
+        const contextManagement = this.buildContextManagementForCurrentClark(llmConfig);
+        const context = await this.contextManagerV2.getOrCreateContext(contextId, llmConfig?.contextOptionsV2, undefined, contextManagement);
         const placeholderUsage = {
             inputTokens: 0,
             outputTokens: 0,
@@ -2185,6 +2592,184 @@ export class AiService extends TracedEventEmitter {
             this.tokenManagerJwt = previousJwt;
         }
     }
+    async handlePolicyGateExecution(request) {
+        const logger = this.getLogger();
+        logger.info(`[ai-service] Policy gate execution requested for app=${request.applicationId}`);
+        const requestLlmConfig = request.llmConfig;
+        const contextLlmConfig = this.clark.context.llmConfig;
+        const llmConfig = requestLlmConfig ?? contextLlmConfig;
+        const llmProvider = createLLMProvider(this.getLLMProviderSettings(llmConfig), () => this.getJwt(), llmConfig, () => ({
+            ai_agent_run_id: request.aiAgentRunId,
+            application_id: request.applicationId,
+            session_id: this.sessionId,
+            trigger_type: "policy_gate",
+        }));
+        const model = llmProvider.modelForTask("generateBroadEdit");
+        const availableIntegrations = await this.integrationStore.availableIntegrations();
+        const integrations = availableIntegrations.map((i) => ({
+            name: i.name,
+            pluginType: i.plugin?.id ?? "unknown",
+        }));
+        const appContext = { integrations };
+        const systemPrompt = composeSecurityAgentPrompt(appContext, request.adminPrompt);
+        const startedAt = Date.now();
+        const toolCallCounts = {};
+        const filePathsRead = new Set();
+        const filePathsListed = new Set();
+        const finishReasons = [];
+        const grepPatterns = [];
+        const grepMatchCounts = [];
+        const grepPatternByToolCallId = new Map();
+        const streamErrors = [];
+        const streamPartTypeCounts = {};
+        let textDeltaChars = 0;
+        const promptHash = createHash("sha256").update(systemPrompt).digest("hex");
+        const modelName = typeof model === "string" ? model : model.modelId;
+        const scanRoot = typeof this.appShell.appRootDirPath === "string"
+            ? this.appShell.appRootDirPath
+            : undefined;
+        let scanResult;
+        const buildRuntimeMetadata = (finalFailureReason) => ({
+            diagnosticsVersion: 2,
+            durationMs: Date.now() - startedAt,
+            filePathsListed: Array.from(filePathsListed).slice(0, 100),
+            filePathsRead: Array.from(filePathsRead).slice(0, 100),
+            finalFailureReason,
+            finishReasons,
+            grepMatchCounts,
+            grepPatterns,
+            model: modelName,
+            promptHash,
+            reportToolCalled: Boolean(scanResult),
+            scanComplete: scanResult?.scanComplete === true,
+            scanRoot,
+            streamErrors,
+            streamPartTypeCounts,
+            textDeltaChars,
+            toolCallCounts,
+        });
+        const failPolicyGateExecution = (message) => {
+            const error = new Error(message);
+            error.runtimeMetadataJson = buildRuntimeMetadata(message);
+            throw error;
+        };
+        const scanToolsDeps = {
+            appShell: this.appShell,
+            features: this.config.features ?? {},
+            integrationStore: this.integrationStore,
+            llmProvider: llmProvider,
+        };
+        const tools = await buildSecurityScanTools(this.clark, scanToolsDeps);
+        const result = aiStreamText({
+            messages: [
+                { content: systemPrompt, role: "system" },
+                {
+                    content: "Begin your security review of this application now.",
+                    role: "user",
+                },
+            ],
+            model,
+            tools,
+            stopWhen: stepCountIs(30),
+        });
+        for await (const part of result.fullStream) {
+            const partType = typeof part.type === "string"
+                ? part.type
+                : "unknown";
+            streamPartTypeCounts[partType] =
+                (streamPartTypeCounts[partType] ?? 0) + 1;
+            if (partType === "error") {
+                const streamError = serializePolicyGateStreamError(part.error, part);
+                if (streamErrors.length < MAX_POLICY_GATE_STREAM_ERRORS) {
+                    streamErrors.push(streamError);
+                }
+                logger.warn("[ai-service] Policy gate stream error", { streamError });
+            }
+            const textDelta = part.textDelta ??
+                part.text ??
+                part.delta;
+            if (typeof textDelta === "string") {
+                textDeltaChars += textDelta.length;
+            }
+            const finishReason = part.finishReason;
+            if (typeof finishReason === "string") {
+                finishReasons.push(finishReason);
+            }
+            if (part.type === "tool-call") {
+                toolCallCounts[part.toolName] =
+                    (toolCallCounts[part.toolName] ?? 0) + 1;
+                const input = part.input ??
+                    part.args;
+                if (input && typeof input === "object") {
+                    const record = input;
+                    if (part.toolName === "build_readFile" &&
+                        typeof record.filePath === "string") {
+                        filePathsRead.add(record.filePath);
+                    }
+                    if (part.toolName === "grep" && typeof record.pattern === "string") {
+                        grepPatterns.push(record.pattern);
+                        const toolCallId = typeof part.toolCallId === "string"
+                            ? part.toolCallId
+                            : `grep-${grepPatterns.length}`;
+                        grepPatternByToolCallId.set(toolCallId, record.pattern);
+                    }
+                }
+            }
+            if (part.type === "tool-result") {
+                const output = part.output ??
+                    part.result;
+                if (output && typeof output === "object") {
+                    const record = output;
+                    if (part.toolName === "build_listFiles" &&
+                        Array.isArray(record.files)) {
+                        for (const file of record.files) {
+                            if (typeof file === "string") {
+                                filePathsListed.add(file);
+                            }
+                        }
+                    }
+                    if (part.toolName === "grep" && typeof record.matches === "number") {
+                        const toolCallId = typeof part.toolCallId === "string"
+                            ? part.toolCallId
+                            : `grep-${grepMatchCounts.length + 1}`;
+                        grepMatchCounts.push({
+                            matches: record.matches,
+                            pattern: grepPatternByToolCallId.get(toolCallId) ??
+                                grepPatterns[grepPatterns.length - 1] ??
+                                "",
+                        });
+                    }
+                }
+            }
+            if (part.type === "tool-call" && part.toolName === "reportReviewRun") {
+                const input = part.input ??
+                    part.args;
+                const parsedInput = securityScanResultSchema.safeParse(input);
+                if (!parsedInput.success) {
+                    logger.error("[ai-service] Invalid policy gate reportReviewRun input", getErrorMeta(parsedInput.error));
+                    failPolicyGateExecution("Invalid policy gate reportReviewRun input");
+                }
+                scanResult = parsedInput.data;
+            }
+        }
+        if (!scanResult) {
+            logger.warn("[ai-service] Policy gate agent did not call reportReviewRun");
+            failPolicyGateExecution("Policy gate agent did not complete a report");
+        }
+        const completedScanResult = scanResult;
+        if (!completedScanResult.scanComplete) {
+            logger.warn("[ai-service] Policy gate agent reported an incomplete scan", {
+                findingCount: completedScanResult.findings.length,
+                scannedFiles: completedScanResult.scannedFiles,
+            });
+            failPolicyGateExecution("Policy gate agent did not complete a report");
+        }
+        logger.info(`[ai-service] Policy gate execution complete: ${completedScanResult.findings.length} findings`);
+        return {
+            ...completedScanResult,
+            runtimeMetadataJson: buildRuntimeMetadata(),
+        };
+    }
     handleUserChange(change) {
         this.getLogger().info(`[ai-service] User changed: ${change.type}`, change);
         this.clark.updateContext((context) => ({