@builder.io/ai-utils 0.86.1 → 0.87.1

package/package.json

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

package/src/codegen.d.ts

@@ -79,71 +79,6 @@ export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
 export declare const AgentModelOverridesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export type AgentModelOverrides = z.infer<typeof AgentModelOverridesSchema>;
 export type ReviewEffort = "medium" | "high" | "low";
-export interface CustomAgentDefinition {
-    name: string;
-    description?: string;
-    /**
-     * When provided as an array, the first element must be the static prompt and
-     * subsequent elements should be dynamic content (e.g. env var placeholders).
-     * Only the first element is marked as cacheable — placing dynamic content
-     * first would invalidate the prompt cache on every request.
-     */
-    systemPrompt?: string | string[];
-    tools?: string[];
-    model?: string;
-    roundRobinModels?: string[];
-    position?: CodeGenPosition;
-    needDevServer?: boolean;
-    needValidation?: boolean;
-    includeMemories?: boolean;
-    resetAfterRun?: boolean;
-    mcpServers?: boolean;
-    asyncSubAgents?: boolean;
-    /**
-     * Expressive queue behavior for messages sent to this agent. See
-     * {@link QueueBehavior}. When both `queueBehavior` and `queueMode` are
-     * provided, `queueBehavior` wins.
-     */
-    queueBehavior?: QueueBehavior;
-    /**
-     * @deprecated Use {@link CustomAgentDefinition.queueBehavior} instead.
-     * Kept as a string alias for backwards compatibility with existing agent
-     * definitions in the wild.
-     */
-    queueMode?: QueueMode;
-    softContextWindow?: number;
-    filePath?: string;
-    /** Maximum wall time (in milliseconds) before the agent watchdog aborts. */
-    maxTimeoutMs?: number;
-    /**
-     * Default max LLM completion turns when this agent is spawned via the Agent tool.
-     * Overrides generic sub-agent defaults in dev-tools when set.
-     */
-    maxCompletions?: number;
-    /** Default reasoning effort level for this agent type. Overrides the session default. */
-    reasoning?: ReasoningEffort;
-    /**
-     * Default {@link SyncChangesFromRemote} policy applied to messages received
-     * by this agent when the message itself does not specify `syncChanges`.
-     * Only consulted at the session/sub-agent level (i.e. when the session was
-     * spawned with `agentType` equal to this agent's name). Use cases include
-     * always resetting the working branch to its base before each new message
-     * (e.g. the setup-project agent).
-     */
-    defaultSyncChanges?: SyncChangesFromRemote;
-    /**
-     * Where this agent was discovered. Drives precedence on name collision:
-     * `project` > `user` > `plugin`. Set by the discovery loader, not by the
-     * parsed file itself.
-     */
-    scope?: "project" | "user" | "plugin";
-    /**
-     * Name of the plugin that contributed this agent, if any. Set by the
-     * plugin loader (Phase 2); always `undefined` for project-level and
-     * user-level standalone files (Phase 1).
-     */
-    pluginName?: string;
-}
 export declare const CodeGenFrameworkSchema: z.ZodEnum<{
     angular: "angular";
     flutter: "flutter";
@@ -2090,7 +2025,14 @@ export type CodeGenMode = z.infer<typeof CodeGenModeSchema>;
  *   previous review). The in-flight user prompt and any partial
  *   assistant output for it are discarded.
  */
-export type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrupt-clear" | "interrupt-replace";
+export declare const QueueScheduleSchema: z.ZodEnum<{
+    interrupt: "interrupt";
+    "interrupt-clear": "interrupt-clear";
+    "interrupt-replace": "interrupt-replace";
+    "next-turn": "next-turn";
+    "until-idle": "until-idle";
+}>;
+export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
 /**
  * What happens when multiple messages are pending in the queue.
  *
@@ -2102,15 +2044,31 @@ export type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrup
  * - `preserve-order`: never merge; pop one message at a time in FIFO order.
  *   This is the historical behavior for `"until-idle"`.
  */
-export type QueueCoalesce = "merge" | "replace-latest" | "preserve-order";
+export declare const QueueCoalesceSchema: z.ZodEnum<{
+    merge: "merge";
+    "preserve-order": "preserve-order";
+    "replace-latest": "replace-latest";
+}>;
+export type QueueCoalesce = z.infer<typeof QueueCoalesceSchema>;
 /**
  * Expressive queue behavior built from two orthogonal axes:
  * `schedule` (when to dispatch) and `coalesce` (how to combine pending).
  */
-export interface QueueBehavior {
-    schedule: QueueSchedule;
-    coalesce: QueueCoalesce;
-}
+export declare const QueueBehaviorSchema: z.ZodObject<{
+    schedule: z.ZodEnum<{
+        interrupt: "interrupt";
+        "interrupt-clear": "interrupt-clear";
+        "interrupt-replace": "interrupt-replace";
+        "next-turn": "next-turn";
+        "until-idle": "until-idle";
+    }>;
+    coalesce: z.ZodEnum<{
+        merge: "merge";
+        "preserve-order": "preserve-order";
+        "replace-latest": "replace-latest";
+    }>;
+}, z.core.$strip>;
+export type QueueBehavior = z.infer<typeof QueueBehaviorSchema>;
 /**
  * Backwards-compatible queue mode. Accepts either a legacy string alias
  * or the full {@link QueueBehavior} object.
@@ -2119,7 +2077,21 @@ export interface QueueBehavior {
  * - `"next-turn"` → `{ schedule: "next-turn", coalesce: "merge" }`
  * - `"until-idle"` → `{ schedule: "until-idle", coalesce: "preserve-order" }`
  */
-export type QueueMode = "next-turn" | "until-idle" | QueueBehavior;
+export declare const QueueModeSchema: z.ZodUnion<readonly [z.ZodLiteral<"next-turn">, z.ZodLiteral<"until-idle">, z.ZodObject<{
+    schedule: z.ZodEnum<{
+        interrupt: "interrupt";
+        "interrupt-clear": "interrupt-clear";
+        "interrupt-replace": "interrupt-replace";
+        "next-turn": "next-turn";
+        "until-idle": "until-idle";
+    }>;
+    coalesce: z.ZodEnum<{
+        merge: "merge";
+        "preserve-order": "preserve-order";
+        "replace-latest": "replace-latest";
+    }>;
+}, z.core.$strip>]>;
+export type QueueMode = z.infer<typeof QueueModeSchema>;
 export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
 /**
  * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
@@ -3498,6 +3470,112 @@ export declare const SyncChangesFromRemoteSchema: z.ZodObject<{
     updateLastCommits: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type SyncChangesFromRemote = z.infer<typeof SyncChangesFromRemoteSchema>;
+export declare const CustomAgentDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model: z.ZodOptional<z.ZodString>;
+    roundRobinModels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    position: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        "browser-testing": "browser-testing";
+        "builder-code": "builder-code";
+        "builder-code-panel": "builder-code-panel";
+        "builder-publish-integration": "builder-publish-integration";
+        cli: "cli";
+        "code-review-orchestrator": "code-review-orchestrator";
+        "create-app-firebase": "create-app-firebase";
+        "create-app-lovable": "create-app-lovable";
+        "design-system-indexer": "design-system-indexer";
+        "dsi-mcp": "dsi-mcp";
+        "editor-ai": "editor-ai";
+        fusion: "fusion";
+        "org-agent": "org-agent";
+        "org-worker": "org-worker";
+        "project-configuration": "project-configuration";
+        "projects-scheduler-memory-extraction": "projects-scheduler-memory-extraction";
+        "repo-indexing": "repo-indexing";
+        "setup-project": "setup-project";
+        unknown: "unknown";
+    }>, z.ZodTemplateLiteral<"browser-testing-agent" | "builder-code-agent" | "builder-code-panel-agent" | "builder-publish-integration-agent" | "cli-agent" | "code-review-orchestrator-agent" | "create-app-firebase-agent" | "create-app-lovable-agent" | "design-system-indexer-agent" | "dsi-mcp-agent" | "editor-ai-agent" | "fusion-agent" | "org-agent-agent" | "org-worker-agent" | "project-configuration-agent" | "projects-scheduler-memory-extraction-agent" | "repo-indexing-agent" | "setup-project-agent" | "unknown-agent">]>>;
+    needDevServer: z.ZodOptional<z.ZodBoolean>;
+    needValidation: z.ZodOptional<z.ZodBoolean>;
+    includeMemories: z.ZodOptional<z.ZodBoolean>;
+    resetAfterRun: z.ZodOptional<z.ZodBoolean>;
+    mcpServers: z.ZodOptional<z.ZodBoolean>;
+    asyncSubAgents: z.ZodOptional<z.ZodBoolean>;
+    queueBehavior: z.ZodOptional<z.ZodObject<{
+        schedule: z.ZodEnum<{
+            interrupt: "interrupt";
+            "interrupt-clear": "interrupt-clear";
+            "interrupt-replace": "interrupt-replace";
+            "next-turn": "next-turn";
+            "until-idle": "until-idle";
+        }>;
+        coalesce: z.ZodEnum<{
+            merge: "merge";
+            "preserve-order": "preserve-order";
+            "replace-latest": "replace-latest";
+        }>;
+    }, z.core.$strip>>;
+    queueMode: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"next-turn">, z.ZodLiteral<"until-idle">, z.ZodObject<{
+        schedule: z.ZodEnum<{
+            interrupt: "interrupt";
+            "interrupt-clear": "interrupt-clear";
+            "interrupt-replace": "interrupt-replace";
+            "next-turn": "next-turn";
+            "until-idle": "until-idle";
+        }>;
+        coalesce: z.ZodEnum<{
+            merge: "merge";
+            "preserve-order": "preserve-order";
+            "replace-latest": "replace-latest";
+        }>;
+    }, z.core.$strip>]>>;
+    softContextWindow: z.ZodOptional<z.ZodNumber>;
+    filePath: z.ZodOptional<z.ZodString>;
+    maxTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxCompletions: z.ZodOptional<z.ZodNumber>;
+    reasoning: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        none: "none";
+        xhigh: "xhigh";
+    }>>;
+    defaultSyncChanges: z.ZodOptional<z.ZodObject<{
+        remoteBranches: z.ZodOptional<z.ZodEnum<{
+            ai: "ai";
+            both: "both";
+            main: "main";
+        }>>;
+        fastForward: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            never: "never";
+            required: "required";
+        }>>;
+        canPush: z.ZodOptional<z.ZodBoolean>;
+        uncommittedChanges: z.ZodOptional<z.ZodEnum<{
+            commit: "commit";
+            fail: "fail";
+            stash: "stash";
+        }>>;
+        requestRefresh: z.ZodOptional<z.ZodBoolean>;
+        allowUnrelatedHistory: z.ZodOptional<z.ZodBoolean>;
+        resetToBase: z.ZodOptional<z.ZodBoolean>;
+        updateLastCommits: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
+        project: "project";
+        user: "user";
+    }>>;
+    pluginName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CustomAgentDefinition = z.infer<typeof CustomAgentDefinitionSchema>;
 export declare const GenerateUserMessageSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodString>;
     user: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -4044,6 +4122,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";
@@ -4063,15 +4147,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;
 }
@@ -4195,23 +4290,22 @@ export interface PrivacyMode {
     mcpServers?: boolean;
 }
 export type Mode = "init-and-launch" | "backup" | "backup-force-full" | "snapshot-creation";
-export interface FileOverride {
-    /**
-     * Path where the file should be written.
-     * Supports absolute paths ("/app/.env"), tilde ("~/.npmrc"), and relative paths ("./config.json").
-     */
-    path: string;
-    /**
-     * Plain text content to write to the file.
-     * Mutually exclusive with `base64`.
-     */
-    content?: string;
-    /**
-     * Base64-encoded binary content to write to the file.
-     * Mutually exclusive with `content`.
-     */
-    base64?: string;
-}
+/**
+ * A file to write into the container during setup. Exactly one of `content`
+ * (plain text) or `base64` (binary) must be provided: `z.xor` is an exclusive
+ * union that fails if zero or both options match, so the mutual exclusivity is
+ * enforced at runtime and reflected in the inferred type. Each variant omits
+ * the other's field — combined with `z.object`'s key-stripping, that's what
+ * makes the "both provided" case fail (it matches both options).
+ */
+export declare const FileOverrideSchema: z.ZodXor<readonly [z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    base64: z.ZodString;
+}, z.core.$strip>]>;
+export type FileOverride = z.infer<typeof FileOverrideSchema>;
 export interface MCPServerDefinition {
     command: string;
     args?: string[];

package/src/codegen.js

@@ -1626,6 +1626,70 @@ export const CodeGenModeSchema = z
     "quality-v4-agent",
 ])
     .meta({ title: "CodeGenMode" });
+/**
+ * When a queued message gets picked up by the scheduler.
+ *
+ * - `next-turn`: process queued messages as soon as the current LLM turn
+ *   finishes (i.e. between turns of an in-flight run).
+ * - `until-idle`: hold queued messages until the agent is fully idle
+ *   (current run has ended). Messages never interrupt an in-flight run.
+ * - `interrupt`: abort the in-flight run as soon as a new message arrives
+ *   and start processing it. Reserved for high-priority/reactive cases.
+ * - `interrupt-clear`: like `interrupt`, but also clears the session
+ *   (turn history, queued messages, last user, accumulated credits) before
+ *   processing the new message. Use when the new message should start from
+ *   a clean slate.
+ * - `interrupt-replace`: equivalent to abort + rewind to the previous
+ *   user message + replace it with the new one. Use when a fresh
+ *   request supersedes the in-flight one (e.g. incremental code-review
+ *   requests where a newer review should replace the still-running
+ *   previous review). The in-flight user prompt and any partial
+ *   assistant output for it are discarded.
+ */
+export const QueueScheduleSchema = z
+    .enum([
+    "next-turn",
+    "until-idle",
+    "interrupt",
+    "interrupt-clear",
+    "interrupt-replace",
+])
+    .meta({ title: "QueueSchedule" });
+/**
+ * What happens when multiple messages are pending in the queue.
+ *
+ * - `merge`: combine all pending messages into a single user message before
+ *   the next turn. This is the historical default for `"next-turn"`.
+ * - `replace-latest`: discard older pending messages and keep only the
+ *   most recently queued one (useful when stale inputs are obsolete, e.g.
+ *   a typing user replacing their previous draft).
+ * - `preserve-order`: never merge; pop one message at a time in FIFO order.
+ *   This is the historical behavior for `"until-idle"`.
+ */
+export const QueueCoalesceSchema = z
+    .enum(["merge", "replace-latest", "preserve-order"])
+    .meta({ title: "QueueCoalesce" });
+/**
+ * Expressive queue behavior built from two orthogonal axes:
+ * `schedule` (when to dispatch) and `coalesce` (how to combine pending).
+ */
+export const QueueBehaviorSchema = z
+    .object({
+    schedule: QueueScheduleSchema,
+    coalesce: QueueCoalesceSchema,
+})
+    .meta({ title: "QueueBehavior" });
+/**
+ * Backwards-compatible queue mode. Accepts either a legacy string alias
+ * or the full {@link QueueBehavior} object.
+ *
+ * Legacy aliases:
+ * - `"next-turn"` → `{ schedule: "next-turn", coalesce: "merge" }`
+ * - `"until-idle"` → `{ schedule: "until-idle", coalesce: "preserve-order" }`
+ */
+export const QueueModeSchema = z
+    .union([z.literal("next-turn"), z.literal("until-idle"), QueueBehaviorSchema])
+    .meta({ title: "QueueMode" });
 export const DEFAULT_QUEUE_BEHAVIOR = {
     schedule: "next-turn",
     coalesce: "merge",
@@ -1958,6 +2022,54 @@ export const SyncChangesFromRemoteSchema = z
     }),
 })
     .meta({ title: "SyncChangesFromRemote" });
+export const CustomAgentDefinitionSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+    systemPrompt: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .meta({
+        description: "When provided as an array, the first element must be the static prompt and subsequent elements should be dynamic content (e.g. env var placeholders). Only the first element is marked as cacheable — placing dynamic content first would invalidate the prompt cache on every request.",
+    }),
+    tools: z.array(z.string()).optional(),
+    model: z.string().optional(),
+    roundRobinModels: z.array(z.string()).optional(),
+    position: CodeGenPositionSchema.optional(),
+    needDevServer: z.boolean().optional(),
+    needValidation: z.boolean().optional(),
+    includeMemories: z.boolean().optional(),
+    resetAfterRun: z.boolean().optional(),
+    mcpServers: z.boolean().optional(),
+    asyncSubAgents: z.boolean().optional(),
+    queueBehavior: QueueBehaviorSchema.optional().meta({
+        description: "Expressive queue behavior for messages sent to this agent. When both `queueBehavior` and `queueMode` are provided, `queueBehavior` wins.",
+    }),
+    queueMode: QueueModeSchema.optional().meta({
+        description: "@deprecated Use `queueBehavior` instead. Kept as a string alias for backwards compatibility with existing agent definitions in the wild.",
+    }),
+    softContextWindow: z.number().optional(),
+    filePath: z.string().optional(),
+    maxTimeoutMs: z.number().optional().meta({
+        description: "Maximum wall time (in milliseconds) before the agent watchdog aborts.",
+    }),
+    maxCompletions: z.number().optional().meta({
+        description: "Default max LLM completion turns when this agent is spawned via the Agent tool. Overrides generic sub-agent defaults in dev-tools when set.",
+    }),
+    reasoning: ReasoningEffortSchema.optional().meta({
+        description: "Default reasoning effort level for this agent type. Overrides the session default.",
+    }),
+    defaultSyncChanges: SyncChangesFromRemoteSchema.optional().meta({
+        description: "Default sync-changes policy applied to messages received by this agent when the message itself does not specify `syncChanges`. Only consulted at the session/sub-agent level (i.e. when the session was spawned with `agentType` equal to this agent's name). Use cases include always resetting the working branch to its base before each new message (e.g. the setup-project agent).",
+    }),
+    scope: z.enum(["project", "user", "plugin"]).optional().meta({
+        description: "Where this agent was discovered. Drives precedence on name collision: `project` > `user` > `plugin`. Set by the discovery loader, not by the parsed file itself.",
+    }),
+    pluginName: z.string().optional().meta({
+        description: "Name of the plugin that contributed this agent, if any. Set by the plugin loader (Phase 2); always `undefined` for project-level and user-level standalone files (Phase 1).",
+    }),
+})
+    .meta({ title: "CustomAgentDefinition" });
 export const GenerateUserMessageSchema = z
     .object({
     idempotencyKey: z.string().optional(),
@@ -2048,6 +2160,35 @@ export function parseGenerateCodeEventErrorBody(body) {
         return undefined;
     }
 }
+const FileOverrideBaseShape = {
+    path: z.string().meta({
+        description: 'Path where the file should be written. Supports absolute paths ("/app/.env"), tilde ("~/.npmrc"), and relative paths ("./config.json").',
+    }),
+};
+/**
+ * A file to write into the container during setup. Exactly one of `content`
+ * (plain text) or `base64` (binary) must be provided: `z.xor` is an exclusive
+ * union that fails if zero or both options match, so the mutual exclusivity is
+ * enforced at runtime and reflected in the inferred type. Each variant omits
+ * the other's field — combined with `z.object`'s key-stripping, that's what
+ * makes the "both provided" case fail (it matches both options).
+ */
+export const FileOverrideSchema = z
+    .xor([
+    z.object({
+        ...FileOverrideBaseShape,
+        content: z.string().meta({
+            description: "Plain text content to write to the file.",
+        }),
+    }),
+    z.object({
+        ...FileOverrideBaseShape,
+        base64: z.string().meta({
+            description: "Base64-encoded binary content to write to the file.",
+        }),
+    }),
+])
+    .meta({ title: "FileOverride" });
 /**
  * Request for generating a commit message via LLM
  */

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";