@builder.io/ai-utils 0.87.0 → 0.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/builder-config.d.ts

@@ -34,6 +34,22 @@ export declare const BuilderConfigHostingSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type BuilderConfigHosting = z.infer<typeof BuilderConfigHostingSchema>;
+/**
+ * `realtime` block in `builder.config.json` — selects the change-notification
+ * delivery transport. `"local"` (default) keeps sync on the app's own
+ * `/_agent-native/poll` + `/_agent-native/events`; `"hosted"` routes clients to
+ * the Builder Realtime Gateway. Read by the backend provisioning path only —
+ * it is never shipped to the browser (the client learns transport via the
+ * impersonal `window.__AGENT_NATIVE_CONFIG__` script). See the Agent-Native
+ * Realtime Sync spec.
+ */
+export declare const BuilderConfigRealtimeSchema: z.ZodObject<{
+    transport: z.ZodEnum<{
+        hosted: "hosted";
+        local: "local";
+    }>;
+}, z.core.$strip>;
+export type BuilderConfigRealtime = z.infer<typeof BuilderConfigRealtimeSchema>;
 export declare const BuilderConfigSchema: z.ZodObject<{
     database: z.ZodOptional<z.ZodObject<{
         kind: z.ZodLiteral<"postgres">;
@@ -49,5 +65,11 @@ export declare const BuilderConfigSchema: z.ZodObject<{
             prod: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>>>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    realtime: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        transport: z.ZodEnum<{
+            hosted: "hosted";
+            local: "local";
+        }>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type BuilderConfig = z.infer<typeof BuilderConfigSchema>;

package/src/builder-config.js

@@ -57,7 +57,23 @@ export const BuilderConfigHostingSchema = z.object({
     buildOutputDir: z.string().optional().catch(undefined),
     environment: BuilderConfigHostingEnvironmentSchema.optional().catch(undefined),
 });
+/**
+ * `realtime` block in `builder.config.json` — selects the change-notification
+ * delivery transport. `"local"` (default) keeps sync on the app's own
+ * `/_agent-native/poll` + `/_agent-native/events`; `"hosted"` routes clients to
+ * the Builder Realtime Gateway. Read by the backend provisioning path only —
+ * it is never shipped to the browser (the client learns transport via the
+ * impersonal `window.__AGENT_NATIVE_CONFIG__` script). See the Agent-Native
+ * Realtime Sync spec.
+ */
+export const BuilderConfigRealtimeSchema = z.object({
+    transport: z.enum(["local", "hosted"]),
+});
 export const BuilderConfigSchema = z.object({
     database: BuilderConfigDatabaseSchema.optional(),
     hosting: BuilderConfigHostingSchema.optional(),
+    // `.catch(undefined)` (like the `hosting` fields): a malformed `realtime`
+    // block degrades to "no realtime" rather than failing the whole parse and
+    // discarding a valid `database` block.
+    realtime: BuilderConfigRealtimeSchema.optional().catch(undefined),
 });

package/src/codegen.d.ts

@@ -2433,8 +2433,6 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         planning: "planning";
     }>>;
     url: z.ZodOptional<z.ZodString>;
-    diffActions: z.ZodOptional<z.ZodBoolean>;
-    planningPrompt: z.ZodOptional<z.ZodBoolean>;
     customInstructions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
@@ -2485,7 +2483,6 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         wasIncluded: z.ZodOptional<z.ZodBoolean>;
         virtual: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
-    rerankFiles: z.ZodOptional<z.ZodNumber>;
     toolResults: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"tool_result">;
         tool_use_id: z.ZodString;
@@ -2767,18 +2764,13 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
     maxAgentLoops: z.ZodOptional<z.ZodNumber>;
     maxAgentTiming: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
-    maxPages: z.ZodOptional<z.ZodNumber>;
-    autoContinue: z.ZodOptional<z.ZodNumber>;
     isManualContinue: z.ZodOptional<z.ZodBoolean>;
-    llmSuggestions: z.ZodOptional<z.ZodBoolean>;
-    conclusionText: z.ZodOptional<z.ZodBoolean>;
     mcpServers: z.ZodOptional<z.ZodBoolean>;
     pingEvents: z.ZodOptional<z.ZodBoolean>;
     forceCompact: z.ZodOptional<z.ZodBoolean>;
     hadPagination: z.ZodOptional<z.ZodBoolean>;
     category: z.ZodOptional<z.ZodUnion<readonly [z.ZodTemplateLiteral<`repair-${string}`>, z.ZodLiteral<"user-normal">, z.ZodLiteral<"user-figma">, z.ZodLiteral<"user-pdf">, z.ZodLiteral<"user-image">, z.ZodLiteral<"setup-agent">, z.ZodTemplateLiteral<`background-${string}`>, z.ZodTemplateLiteral<`indexing-${string}`>]>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-    searchResponse: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
     prettierConfig: z.ZodOptional<z.ZodCustom<PrettierOptions, PrettierOptions>>;
     role: z.ZodOptional<z.ZodEnum<{
         agent: "agent";
@@ -2874,6 +2866,8 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
 export type CodeGenInputOptions = z.infer<typeof CodeGenInputOptionsSchema> & {
     /** @internal Derived from BuilderEditorState.components for editor AI. */
     _allowedComponentNames?: string[];
+    /** @internal Derived from BuilderEditorState.components for editor AI. */
+    _fieldShapeChecks?: FieldShapeCheck[];
     /**
      * Optional factory function to wrap the MCP client with custom behavior
      * Used by Editor AI to add permission checks for model operations
@@ -2883,6 +2877,11 @@ export type CodeGenInputOptions = z.infer<typeof CodeGenInputOptionsSchema> & {
      */
     _mcpClientWrapperFactory?: (realClient: any) => any;
 };
+export interface FieldShapeCheck {
+    component: string;
+    input: string;
+    subField: string;
+}
 export type CodeGenErrorCodes = "credits-limit-daily" | "credits-limit-monthly" | "credits-limit-user" | "credits-limit-other" | "cli-genetic-error" | "git-update-error" | "prompt-too-long" | "context-too-long" | "abrupt-end" | "unknown" | "failed-recover-state" | "completion-expired" | "ask-to-continue" | "bad-initial-url" | "bad-smart-export-payload" | "invalid-last-message" | "corrupted-session" | "privacy-mode-key-required" | "privacy-mode-key-invalid" | "privacy-mode-key-mismatch" | "privacy-mode-validation-unavailable" | "cli-network-error" | "invalid-credentials" | "model-restricted-too-large" | "org-no-models-enabled" | "assertion" | "rate-limit" | "unknown-design-system";
 export interface CodegenUsage {
     total: number;
@@ -2915,38 +2914,6 @@ export interface ActionItem {
     suggestions?: PromptSuggestion[];
     errors?: string[];
 }
-export interface RepoInfo {
-    remoteUrl: string;
-    defaultBranch: string;
-    currentBranch: string;
-    commit: string;
-}
-export interface CodebaseSearchOptions {
-    repoInfo?: RepoInfo;
-    query: string;
-    selectedFiles?: string[];
-    sessionId: string;
-    files?: string[];
-    packageJson?: string;
-    limit?: number;
-    includeContent?: boolean;
-}
-export interface CodebaseSearchResponse {
-    id: string;
-    relevantPaths: string[];
-    grepQueries: string[];
-    streamMeta: any;
-    ranked: RankedResult[];
-}
-export interface RankedResult {
-    index: number;
-    filePath: string;
-    startIndex: number;
-    endIndex: number;
-    score: number;
-    id: string;
-    content?: string;
-}
 export interface GenerateCompletionStepThinking {
     type: "thinking";
     content: string;
@@ -3768,9 +3735,6 @@ export interface UserInput {
     systemReminders: SystemReminder[];
     attachments: Attachment[];
     files: ProjectFile[];
-    searchResponse: CodebaseSearchResponse | null;
-    rerankFiles?: number;
-    mostRelevantFile: string | null;
     toolResults: ContentMessageItemToolResult[];
     user: UserSource;
     patchFusionConfig?: Partial<FusionConfig> | undefined;
@@ -4122,6 +4086,12 @@ export interface BranchBackup {
     forced: ForcedBackup;
     commitInRepoVerified?: "verified" | "not-found" | "unverified";
     metadata?: Record<string, any>;
+    /**
+     * Paths of submodules / embedded git repos whose state the bundle cannot
+     * reproduce. When non-empty the backup is restorable for the outer repo
+     * but must not be treated as deletion-safe.
+     */
+    changedSubmodules?: string[];
 }
 export interface CheckBackupDataResultValid {
     state: "valid";
@@ -4141,15 +4111,26 @@ export interface CheckBackupDataResultStale {
     message: string;
     backup: BranchBackup;
 }
+/**
+ * The backup is otherwise valid but includes submodule changes the bundle
+ * cannot reproduce (see BranchBackup.changedSubmodules). It can still be
+ * restored, but the volume must be retained.
+ */
+export interface CheckBackupDataResultSubmoduleChanges {
+    state: "submodule-changes";
+    outcome: "submodule-changes";
+    message: string;
+    backup: BranchBackup;
+}
 export interface CheckBackupDataResultInvalid {
     state: "invalid";
     outcome: "no-backup" | "error" | "not-completed" | "no-session-id" | "no-last-commit-hash" | "no-backup-file" | "empty-full-backup" | "no-vcpCodeGenEvent" | "commits-not-in-repo" | "no-after-commit" | "no-signed-url" | "no-git-branch-name" | "repo-url-mismatch" | "branch-uninitialized" | "unexpected-partial-backup" | "unexpected-full-backup" | "no-backup-keys";
     message: string;
     backup: BranchBackup | undefined;
 }
-export type CheckBackupDataResult = CheckBackupDataResultValid | CheckBackupDataResultForcedBackup | CheckBackupDataResultStale | CheckBackupDataResultInvalid;
+export type CheckBackupDataResult = CheckBackupDataResultValid | CheckBackupDataResultForcedBackup | CheckBackupDataResultStale | CheckBackupDataResultSubmoduleChanges | CheckBackupDataResultInvalid;
 export interface BackupMetadata {
-    check: CheckBackupDataResultValid | CheckBackupDataResultStale | CheckBackupDataResultForcedBackup;
+    check: CheckBackupDataResultValid | CheckBackupDataResultStale | CheckBackupDataResultForcedBackup | CheckBackupDataResultSubmoduleChanges;
     downloadUrl: GitBackupDownloadUrlResult | undefined;
     downloadUrlError?: string;
 }

package/src/codegen.js

@@ -1616,6 +1616,11 @@ export const SessionModeSchema = z
     .meta({ title: "SessionMode" });
 export const CodeGenModeSchema = z
     .enum([
+    /**
+     * @deprecated The legacy quality-v2 pipeline has been removed. Old
+     * dev-tools clients that still request this mode are served `quality-v4`.
+     * New code should not produce this value.
+     */
     "quality",
     "quality-v4",
     /**
@@ -1909,8 +1914,6 @@ export const CodeGenInputOptionsSchema = z
     codeGenMode: CodeGenModeSchema.optional(),
     sessionMode: SessionModeSchema.optional(),
     url: z.string().optional(),
-    diffActions: z.boolean().optional(),
-    planningPrompt: z.boolean().optional(),
     customInstructions: z.array(CustomInstructionSchema).optional(),
     customAgents: z.array(CustomAgentInfoSchema).optional(),
     systemPromptOverride: z.union([z.string(), z.array(z.string())]).optional(),
@@ -1920,7 +1923,6 @@ export const CodeGenInputOptionsSchema = z
     uiContextPrompt: z.string().optional(),
     displayUserPrompt: z.string().optional(),
     files: z.array(ProjectFileSchema).optional(),
-    rerankFiles: z.number().optional(),
     toolResults: z.array(ContentMessageItemToolResultSchema).optional(),
     attachments: z.array(AttachmentSchema).optional(),
     beforeCommit: GitSnapshotSchema.optional(),
@@ -1965,18 +1967,13 @@ export const CodeGenInputOptionsSchema = z
     maxTokens: z.number().optional().meta({
         description: "Maximum output tokens allowed in the LLM response. This will set the maximum token output for the LLM.",
     }),
-    maxPages: z.number().optional(),
-    autoContinue: z.number().optional(),
     isManualContinue: z.boolean().optional(),
-    llmSuggestions: z.boolean().optional(),
-    conclusionText: z.boolean().optional(),
     mcpServers: z.boolean().optional(),
     pingEvents: z.boolean().optional(),
     forceCompact: z.boolean().optional(),
     hadPagination: z.boolean().optional(),
     category: CodeGenCategorySchema.optional(),
     metadata: z.record(z.string(), z.any()).optional(),
-    searchResponse: z.any().nullish(),
     prettierConfig: z.custom().optional(),
     // Role
     role: z.enum(["user", "agent"]).optional(),

package/src/events.d.ts

@@ -3,6 +3,7 @@ import type { AssistantMessage, AssistantMessageAction } from "./messages.js";
 import type { AssistantSettings } from "./settings.js";
 import type { ExitState, UserSource, CodeGenPosition, ReviewSeverity, ReviewVerdict } from "./codegen.js";
 import type { FileUpload } from "./messages.js";
+import type { BuilderConfigRealtime } from "./builder-config.js";
 export type BuilderAssistantEventHandler = (ev: BuilderAssistantEvent) => void;
 export type BuilderAssistantEvent = AssistantCompletionResultEvent | AssistantErrorEvent | AssistantStreamErrorEvent | AppCloseEvent | AppMessagesClickEvent | AppMessagesGenerationEvent | AppMessageEditCustomInstructionsEvent | AppPromptAbortEvent | AppPromptFocusEvent | AppPromptSubmitEvent | AppReadyEvent | AppSettingsSetEvent | AppThreadNewEvent | AssistantStatsEvent | AssistantThemeEvent | BuilderEditorAuthEvent | BuilderEditorStateEvent | ContentUpdateEvent | ContentApplySnapshotEvent | ModelUndoEvent | ModelRedoEvent | ResultEvent | ThreadCreatedEvent | ThreadMessageCompletedEvent | ThreadMessageCreatedEvent | ThreadMessageDeltaEvent | ThreadMessageFeedbackEvent | ThreadRunStepCreatedEvent | ThreadRunStepDeltaEvent | AppAcceptChangeEvent | AppAcceptRejectEvent | AssistantTrackEvent | AssistantEditorAuthMessage | AppAttachmentTemplateEvent | AppPasteSmartExportEvent | ThreadMessageRetryEvent | AppFigmaImportEvent | AppWebImportEvent | AppMcpServersEvent | AssistantContentInitialEvent | ThreadMessageSummaryEvent | ThreadMessageSummaryCodegenDeltaEvent | ThreadMessageThinkingDeltaEvent | AssistantHeartbeatEvent | ShowUpgradeDialogEvent | AssistantFusionSuggestionEvent | AppNavigateToFusionEvent | ModelPermissionRequiredEvent | ModelPermissionResponseEvent;
 export interface AssistantCompletionResultEvent {
@@ -1271,6 +1272,15 @@ export type ClientDevtoolsBuildUploadedV1 = FusionEventVariant<"client.devtools.
      * directly in the handler and is not sent through the event.
      */
     prodEnvFromBuilderConfig?: Record<string, string>;
+    /**
+     * `realtime.transport` from the same `builder.config.json` read. Sent from
+     * the pod because the tree it built is the authoritative revision — the
+     * service would otherwise have to re-resolve the deployed commit through
+     * the git provider, which for template-backed projects can resolve against
+     * a different repo. Absent from pods predating this field; the handler
+     * falls back to reading the repo at the deployed commit.
+     */
+    realtimeTransport?: BuilderConfigRealtime["transport"];
 }, {
     projectId: string;
     deployId: string;

package/src/fusion-environment.d.ts

@@ -0,0 +1,5 @@
+import type { Branch, FusionExecutionEnvironment } from "./projects.js";
+/** Upgrade legacy `cloud` to `cloud-v2` when kube is enabled. */
+export declare function upgradeCloudForKube(environment: FusionExecutionEnvironment, useKube: boolean): FusionExecutionEnvironment;
+/** Work branch whose fusion environment a new sibling branch should inherit. */
+export declare function pickReferenceWorkBranch(branches: Branch[]): Branch | undefined;

package/src/fusion-environment.js

@@ -0,0 +1,16 @@
+import { getBranchState } from "./projects.js";
+/** Upgrade legacy `cloud` to `cloud-v2` when kube is enabled. */
+export function upgradeCloudForKube(environment, useKube) {
+    return environment === "cloud" && useKube ? "cloud-v2" : environment;
+}
+/** Work branch whose fusion environment a new sibling branch should inherit. */
+export function pickReferenceWorkBranch(branches) {
+    var _a, _b;
+    const activeWorkBranches = branches.filter((branch) => {
+        if (branch.type === "deploy" || branch.hidden) {
+            return false;
+        }
+        return getBranchState(branch) === "active";
+    });
+    return ((_b = (_a = activeWorkBranches.find((branch) => branch.name === "development")) !== null && _a !== void 0 ? _a : activeWorkBranches.find((branch) => branch.isDefault)) !== null && _b !== void 0 ? _b : activeWorkBranches[0]);
+}

package/src/fusion-environment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/fusion-environment.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { pickReferenceWorkBranch, upgradeCloudForKube, } from "./fusion-environment.js";
+function branch(overrides) {
+    return {
+        id: `br-${overrides.name}`,
+        projectId: "project-1",
+        ownerId: "org-1",
+        isPublic: true,
+        ...overrides,
+    };
+}
+describe("upgradeCloudForKube", () => {
+    it("upgrades cloud when useKube is true", () => {
+        expect(upgradeCloudForKube("cloud", true)).toBe("cloud-v2");
+    });
+    it("leaves cloud-v2 unchanged", () => {
+        expect(upgradeCloudForKube("cloud-v2", false)).toBe("cloud-v2");
+    });
+});
+describe("pickReferenceWorkBranch", () => {
+    it("prefers development over other work branches", () => {
+        var _a;
+        expect((_a = pickReferenceWorkBranch([
+            branch({ name: "feature-a", lockedFusionEnvironment: "cloud" }),
+            branch({ name: "development", lockedFusionEnvironment: "cloud-v2" }),
+        ])) === null || _a === void 0 ? void 0 : _a.name).toBe("development");
+    });
+    it("ignores deploy and hidden branches", () => {
+        var _a;
+        expect((_a = pickReferenceWorkBranch([
+            branch({
+                name: "deploy-pod",
+                type: "deploy",
+                hidden: true,
+                lockedFusionEnvironment: "cloud",
+            }),
+            branch({ name: "development", lockedFusionEnvironment: "cloud-v2" }),
+        ])) === null || _a === void 0 ? void 0 : _a.name).toBe("development");
+    });
+});

package/src/index.d.ts

@@ -9,6 +9,7 @@ export * from "./codegen.js";
 export * from "./codegen/investigation-context.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";
+export * from "./fusion-environment.js";
 export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";

package/src/index.js

@@ -9,6 +9,7 @@ export * from "./codegen.js";
 export * from "./codegen/investigation-context.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";
+export * from "./fusion-environment.js";
 export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";

package/src/organization.d.ts

@@ -1,4 +1,4 @@
-import type { PrivacyMode, ReviewEffort } from "./codegen";
+import type { PrivacyMode, ReasoningEffort, ReviewEffort } from "./codegen";
 import type { EnvironmentVariable } from "./common-schemas";
 export interface GitlabEnterpriseSetupValue {
     host: string;
@@ -103,6 +103,8 @@ interface OrganizationSettings {
     fusionPrQuietMode?: boolean;
     runInPty?: boolean;
     maxAgentCompletions?: number;
+    defaultBackgroundAgentModel?: string;
+    defaultBackgroundAgentEffort?: ReasoningEffort;
     privacyMode?: Pick<PrivacyMode, "mcpServers" | "redactUserMessages" | "redactLLMMessages"> & {
         enabled?: boolean;
     };
@@ -328,6 +330,7 @@ export interface FeatureMap {
     agentCreditsRollover?: boolean;
     selfHostedGitProviders?: boolean;
     reviewAgent?: boolean;
+    hosting?: boolean;
 }
 export interface SubscriptionInfo {
     price?: number;
@@ -420,6 +423,7 @@ export interface SubscriptionInfoMap {
     "vcp:v1:level1": SubscriptionInfo;
     "vcp:v1:level2": SubscriptionInfo;
     "vcp:v1:enterprise": SubscriptionInfo;
+    "vcp:v2:enterprise": SubscriptionInfo;
     "vcp:v2:level1": SubscriptionInfo;
     "vcp:v2:level2": SubscriptionInfo;
     "vcp:v3:level1": SubscriptionInfo;

package/src/projects.d.ts

@@ -283,6 +283,14 @@ export interface GitBackupRecordOptions {
     forced: ForcedBackup;
     metadata?: Record<string, string | string[] | undefined>;
     folderName?: string;
+    /**
+     * Paths of submodules / embedded git repos whose state the bundle cannot
+     * reproduce: gitlinks changed within the backed-up range, or inner repos
+     * with commits/changes that exist only on the volume. When non-empty the
+     * backup is restorable for the outer repo but must not be treated as
+     * deletion-safe.
+     */
+    changedSubmodules?: string[];
 }
 export interface RecordScreenshotOptions {
     projectId: string;
@@ -1602,6 +1610,15 @@ export interface ProjectDatabase {
     role: string;
     /** @internal Plaintext credential — Firestore IAM enforces access. Never serialize to client responses. */
     password: string;
+    /**
+     * @internal Per-project HMAC secret for signing/verifying Realtime Gateway
+     * subscribe tokens. Plaintext like `password`; Firestore IAM enforces access.
+     * Never serialize to client responses. Absent on projects provisioned before
+     * the Realtime Sync Gateway shipped — there is no backfill by design; such a
+     * project gets its secret on its next deploy. See the Agent-Native Realtime
+     * Sync spec.
+     */
+    realtimeHmacSecret?: string;
     /** Database name (white-labeled to "main"); needed to build connection URIs. */
     database: string;
     region: string;