@builder.io/ai-utils 0.53.1 → 0.55.0

package/package.json

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

package/src/codegen.d.ts

@@ -38,10 +38,14 @@ export interface CustomInstruction {
 }
 /** Reasoning effort level for LLM completions. */
 export declare const ReasoningEffortSchema: z.ZodEnum<{
+    none: "none";
     low: "low";
     medium: "medium";
     high: "high";
+    auto: "auto";
     minimal: "minimal";
+    xhigh: "xhigh";
+    max: "max";
 }>;
 export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
 export interface CustomAgentInfo {
@@ -64,7 +68,6 @@ export interface CustomAgentDefinition {
     tools?: string[];
     model?: string;
     roundRobinModels?: string[];
-    mode?: CodeGenMode;
     position?: CodeGenPosition;
     needDevServer?: boolean;
     needValidation?: boolean;
@@ -72,6 +75,17 @@ export interface CustomAgentDefinition {
     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;
@@ -737,19 +751,6 @@ export interface ReportIssueToolInput {
     body: string;
 }
 export interface CodeGenToolMap {
-    view_path: ReadToolInput;
-    glob_search: GlobSearchToolInput;
-    grep_search: GrepSearchToolInput;
-    get_rule: GetRuleToolInput;
-    get_style_inspiration: GetStyleInspirationToolInput;
-    get_screenshot: GetScreenshotToolInput;
-    dev_server_control: DevServerControlInput;
-    bash: BashToolInput;
-    powershell: PowerShellToolInput;
-    web_search: WebSearchToolInput;
-    write_file: WriteFileInput;
-    search_replace_file: SearchReplaceInput;
-    find_media: FindMediaToolInput;
     Read: ReadToolInput;
     Write: WriteFileInput;
     Edit: SearchReplaceInput;
@@ -812,6 +813,7 @@ export interface CodeGenToolMap {
     IDEDiagnostics: IDEDiagnosticsToolInput;
     EscalateToPlanner: EscalateToPlanner;
     PullPrototype: PullPrototypeToolInput;
+    ConnectMCP: ConnectMCPToolInput;
 }
 export interface EscalateToPlanner {
     /** What's blocking execution */
@@ -825,11 +827,80 @@ export interface EscalateToPlanner {
 }
 export interface GetLastBrowserTestToolInput {
 }
+export interface ConnectMCPToolInput {
+    /** Human-readable name of the MCP service, e.g. "Jira", "Linear", "Sentry" */
+    name: string;
+    /** Remote MCP endpoint URL. When omitted, discovery is performed for the named service. */
+    url?: string;
+}
 export type CodeGenTools = keyof CodeGenToolMap;
 export type AllCodeGenTools = CodeGenTools | "web_search";
 export type SessionMode = "planning" | "normal" | "auto-planning" | "deep-research";
-export type CodeGenMode = "quality" | "quality-v3" | "quality-v4" | "quality-v4-agent";
-export type QueueMode = "next-turn" | "until-idle";
+export type CodeGenMode = "quality" | "quality-v4"
+/**
+ * @deprecated Use `quality-v4` instead. Kept for backwards compatibility
+ * with older dev-tools clients in the wild that may still request this mode
+ * for sub-agents. New code should not produce this value.
+ */
+ | "quality-v4-agent";
+/**
+ * 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 type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrupt-clear" | "interrupt-replace";
+/**
+ * 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 type QueueCoalesce = "merge" | "replace-latest" | "preserve-order";
+/**
+ * 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;
+}
+/**
+ * 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 type QueueMode = "next-turn" | "until-idle" | QueueBehavior;
+export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
+/**
+ * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
+ * `undefined` resolves to {@link DEFAULT_QUEUE_BEHAVIOR}.
+ */
+/** True for any schedule that aborts the in-flight run on enqueue. */
+export declare function isInterruptSchedule(schedule: QueueSchedule): boolean;
+export declare function normalizeQueueMode(mode: QueueMode | undefined): QueueBehavior;
 export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp"];
 export type BaseCodeGenPosition = (typeof BASE_CODEGEN_POSITIONS)[number];
 export type CodeGenPosition = BaseCodeGenPosition | `${BaseCodeGenPosition}-agent`;
@@ -1102,7 +1173,7 @@ export interface ContextWindow {
      * the proportion (0-1) of total tokens used by that category.
      *
      * Common keys include:
-     * - `tool:<name>` - Tokens from tool calls and results (e.g., `tool:read_file`, `tool:bash`)
+     * - `tool:<name>` - Tokens from tool calls and results (e.g., `tool:Read`, `tool:Bash`)
      * - `tools:builtin` - Tokens from built-in tool definitions/schemas
      * - `tools:mcp:<server>` - Tokens from MCP server tool definitions (e.g., `tools:mcp:browser`)
      * - `images` - Tokens from image content (estimated at ~1200 tokens per image)
@@ -2230,6 +2301,23 @@ export interface SyncChangesFromRemote {
     uncommittedChanges?: "stash" | "commit" | "fail";
     requestRefresh?: boolean;
     allowUnrelatedHistory?: boolean;
+    /**
+     * When true, reset the AI branch hard to the remote feature/base branch instead
+     * of merging. This gives a clean slate that exactly matches the checked-out
+     * feature branch on remote, avoiding any merge-style conflicts or divergence.
+     * Fails clearly if the feature/base branch cannot be determined or is absent
+     * from the remote.
+     */
+    resetToBase?: boolean;
+    /**
+     * Whether to update the internal "last AI commits" baseline after the sync
+     * completes. Defaults to `true` for backwards compatibility.
+     *
+     * Set to `false` when the caller wants `getChangesReport()` to keep diffing
+     * from the pre-sync baseline (e.g. so a downstream prompt can see exactly
+     * what changed since the last reset/sync).
+     */
+    updateLastCommits?: boolean;
 }
 export type PushChangesArgs = PushChangesOptions | boolean;
 export type CodegenApiResult = CodegenApiSuccess | CodegenApiFailure;

package/src/codegen.js

@@ -1,8 +1,31 @@
 import { z } from "zod";
 /** Reasoning effort level for LLM completions. */
 export const ReasoningEffortSchema = z
-    .enum(["low", "medium", "high", "minimal"])
+    .enum(["auto", "none", "minimal", "low", "medium", "high", "xhigh", "max"])
     .meta({ title: "ReasoningEffort" });
+export const DEFAULT_QUEUE_BEHAVIOR = {
+    schedule: "next-turn",
+    coalesce: "merge",
+};
+/**
+ * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
+ * `undefined` resolves to {@link DEFAULT_QUEUE_BEHAVIOR}.
+ */
+/** True for any schedule that aborts the in-flight run on enqueue. */
+export function isInterruptSchedule(schedule) {
+    return (schedule === "interrupt" ||
+        schedule === "interrupt-clear" ||
+        schedule === "interrupt-replace");
+}
+export function normalizeQueueMode(mode) {
+    if (mode === undefined)
+        return { ...DEFAULT_QUEUE_BEHAVIOR };
+    if (mode === "next-turn")
+        return { schedule: "next-turn", coalesce: "merge" };
+    if (mode === "until-idle")
+        return { schedule: "until-idle", coalesce: "preserve-order" };
+    return { schedule: mode.schedule, coalesce: mode.coalesce };
+}
 export const BASE_CODEGEN_POSITIONS = [
     "fusion",
     "editor-ai",

package/src/codegen.spec.d.ts

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

package/src/codegen.spec.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { DEFAULT_QUEUE_BEHAVIOR, isInterruptSchedule, normalizeQueueMode, } from "./codegen";
+describe("normalizeQueueMode", () => {
+    it("returns the default behavior when input is undefined", () => {
+        expect(normalizeQueueMode(undefined)).toEqual(DEFAULT_QUEUE_BEHAVIOR);
+    });
+    it("maps the legacy 'next-turn' alias to merge between turns", () => {
+        expect(normalizeQueueMode("next-turn")).toEqual({
+            schedule: "next-turn",
+            coalesce: "merge",
+        });
+    });
+    it("maps the legacy 'until-idle' alias to FIFO at idle", () => {
+        expect(normalizeQueueMode("until-idle")).toEqual({
+            schedule: "until-idle",
+            coalesce: "preserve-order",
+        });
+    });
+    it("returns an object input as a normalized copy", () => {
+        const input = {
+            schedule: "interrupt",
+            coalesce: "replace-latest",
+        };
+        const out = normalizeQueueMode(input);
+        expect(out).toEqual(input);
+        expect(out).not.toBe(input);
+    });
+    it("supports next-turn + preserve-order (FIFO between turns)", () => {
+        expect(normalizeQueueMode({ schedule: "next-turn", coalesce: "preserve-order" })).toEqual({ schedule: "next-turn", coalesce: "preserve-order" });
+    });
+    it("supports until-idle + replace-latest (debounce on idle)", () => {
+        expect(normalizeQueueMode({
+            schedule: "until-idle",
+            coalesce: "replace-latest",
+        })).toEqual({ schedule: "until-idle", coalesce: "replace-latest" });
+    });
+    it("supports interrupt-clear and interrupt-replace schedules", () => {
+        expect(normalizeQueueMode({
+            schedule: "interrupt-clear",
+            coalesce: "merge",
+        })).toEqual({ schedule: "interrupt-clear", coalesce: "merge" });
+        expect(normalizeQueueMode({
+            schedule: "interrupt-replace",
+            coalesce: "merge",
+        })).toEqual({ schedule: "interrupt-replace", coalesce: "merge" });
+    });
+});
+describe("isInterruptSchedule", () => {
+    it("returns true for every interrupt-* schedule", () => {
+        expect(isInterruptSchedule("interrupt")).toBe(true);
+        expect(isInterruptSchedule("interrupt-clear")).toBe(true);
+        expect(isInterruptSchedule("interrupt-replace")).toBe(true);
+    });
+    it("returns false for non-interrupt schedules", () => {
+        expect(isInterruptSchedule("next-turn")).toBe(false);
+        expect(isInterruptSchedule("until-idle")).toBe(false);
+    });
+});

package/src/organization.d.ts

@@ -461,5 +461,11 @@ export interface Organization {
     fusionReferrals?: string;
     githubInstallationIds?: number[];
     disableFigmaImageUpload?: boolean;
+    blocked?: boolean;
+    archived?: boolean;
+    gatewaySuspended?: boolean;
+    gatewaySuspendedAt?: number;
+    gatewaySuspendedBy?: string;
+    gatewaySuspendedReason?: string;
 }
 export {};