@builder.io/ai-utils 0.30.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "description": "Builder.io AI utils",
   "type": "module",
   "main": "src/index.js",

package/src/claw.d.ts

@@ -41,5 +41,47 @@ export interface ParsedChannelId {
  *   "slack/thread/T01234/C56789/1234567890.123456" → { platform: "slack", type: "thread", ids: ["T01234", "C56789", "1234567890.123456"] }
  *   "jira/comment/cloud-id/PROJ-123" → { platform: "jira", type: "comment", ids: ["cloud-id", "PROJ-123"] }
  *   "builder/branch/proj-id/my-branch" → { platform: "builder", type: "branch", ids: ["proj-id", "my-branch"] }
+ *   "inbox/user/builder-user-id" → { platform: "inbox", type: "user", ids: ["builder-user-id"] }
  */
 export declare function parseChannelId(channelId: string): ParsedChannelId;
+export interface WorkerReportOptions {
+    /** The original user's channel that triggered this work. */
+    originChannelId?: string;
+    /** The report content. */
+    content: string;
+    /** Project ID (for branch reports). */
+    projectId?: string;
+    /** Branch name (for branch reports). */
+    branchName?: string;
+    /** Agent/tool ID (for sub-agent reports). */
+    agentId?: string;
+}
+/**
+ * Formats a `<worker_report>` message for the org-agent.
+ *
+ * Used when a spawned branch or sub-agent reports its results back.
+ * The org-agent uses `<origin_channel_id>` to route the response to the
+ * correct user channel.
+ */
+export declare function formatWorkerReport(opts: WorkerReportOptions): string;
+export interface IncomingMessageOptions {
+    /** The source channel (e.g. slack/thread/TEAM/CHANNEL/TS). */
+    channelId: string;
+    /** DM channel ID, if the message was a direct message. */
+    dmId?: string;
+    /** Display name of the sender. */
+    sender?: string;
+    /** Pre-formatted timestamp string. */
+    timestamp: string;
+    /** The message body. */
+    content: string;
+    /** Optional context to prepend (e.g. Slack thread history). */
+    messageContext?: string;
+}
+/**
+ * Formats an `<incoming_message>` for the org-agent.
+ *
+ * Used when a real user message arrives from an integration.
+ * The org-agent uses `<channel_id>` to reply in the same medium.
+ */
+export declare function formatIncomingMessage(opts: IncomingMessageOptions): string;

package/src/claw.js

@@ -6,6 +6,7 @@
  *   "slack/thread/T01234/C56789/1234567890.123456" → { platform: "slack", type: "thread", ids: ["T01234", "C56789", "1234567890.123456"] }
  *   "jira/comment/cloud-id/PROJ-123" → { platform: "jira", type: "comment", ids: ["cloud-id", "PROJ-123"] }
  *   "builder/branch/proj-id/my-branch" → { platform: "builder", type: "branch", ids: ["proj-id", "my-branch"] }
+ *   "inbox/user/builder-user-id" → { platform: "inbox", type: "user", ids: ["builder-user-id"] }
  */
 export function parseChannelId(channelId) {
     const parts = channelId.split("/");
@@ -15,3 +16,63 @@ export function parseChannelId(channelId) {
     const [platform, type, ...ids] = parts;
     return { platform, type, ids };
 }
+// ── Org-agent message formatting ──
+//
+// The org-agent receives two kinds of messages in its conversation:
+//   1. <incoming_message> — from real users (Slack, Jira, GitHub, etc.)
+//   2. <worker_report>    — from spawned agents or branches reporting back
+//
+// These XML tags are consumed by the LLM (not parsed by code), so the
+// format matters for prompt clarity and consistency.
+const WORKER_REPORT_TRAILER = "This is a report from a background worker, NOT a user message. Review the results and take appropriate action (e.g., send findings to the user, update memory).";
+/**
+ * Formats a `<worker_report>` message for the org-agent.
+ *
+ * Used when a spawned branch or sub-agent reports its results back.
+ * The org-agent uses `<origin_channel_id>` to route the response to the
+ * correct user channel.
+ */
+export function formatWorkerReport(opts) {
+    let xml = `<worker_report>\n`;
+    if (opts.originChannelId) {
+        xml += `<origin_channel_id>${opts.originChannelId}</origin_channel_id>\n`;
+    }
+    if (opts.projectId) {
+        xml += `<project_id>${opts.projectId}</project_id>\n`;
+    }
+    if (opts.branchName && opts.projectId) {
+        xml += `<branch_name>${opts.branchName}</branch_name>\n`;
+        xml += `<channel_id>builder/branch/${opts.projectId}/${opts.branchName}</channel_id>\n`;
+    }
+    if (opts.agentId) {
+        xml += `<agent_id>${opts.agentId}</agent_id>\n`;
+    }
+    xml += `<content>${opts.content}</content>\n`;
+    xml += `</worker_report>\n`;
+    xml += WORKER_REPORT_TRAILER;
+    return xml;
+}
+/**
+ * Formats an `<incoming_message>` for the org-agent.
+ *
+ * Used when a real user message arrives from an integration.
+ * The org-agent uses `<channel_id>` to reply in the same medium.
+ */
+export function formatIncomingMessage(opts) {
+    let result = "";
+    if (opts.messageContext) {
+        result += `${opts.messageContext}\n\n`;
+    }
+    result += `<incoming_message>\n`;
+    result += `<channel_id>${opts.channelId}</channel_id>\n`;
+    if (opts.dmId) {
+        result += `<dm_id>${opts.dmId}</dm_id>\n`;
+    }
+    if (opts.sender) {
+        result += `<sender>${opts.sender}</sender>\n`;
+    }
+    result += `<timestamp>${opts.timestamp}</timestamp>\n`;
+    result += `<content>${opts.content}</content>\n`;
+    result += `</incoming_message>\n`;
+    return result;
+}

package/src/codegen.d.ts

@@ -179,6 +179,8 @@ export interface AgentToolInput {
     prompt: string;
     subagent_type?: string;
     resume?: string;
+    origin_channel_id?: string;
+    attachmentUrls?: string[];
 }
 export interface ListDirToolInput {
     path: string;
@@ -205,7 +207,6 @@ export interface BuilderEditToolInput {
 }
 export interface GetScreenshotToolInput {
     href?: string;
-    url?: string;
     selector?: string;
     width?: number;
     height?: number;
@@ -327,6 +328,7 @@ export interface ExitToolInput {
     isMicrofrontend?: boolean;
     setupNeedsCredentials?: boolean;
     devServerNeedsCredentials?: boolean;
+    needsVPN?: boolean;
     /** A human-readable description of what the project is about (not tech specs), used by fusion to route requests to the right project */
     projectDescription?: string;
 }
@@ -419,6 +421,7 @@ export interface ProposedConfig {
     projectDescription?: string;
     cost?: number;
     durationMs?: number;
+    needsVPN?: boolean;
 }
 /**
  * Parameters for proposing a configuration to the backend
@@ -450,6 +453,7 @@ export interface ProposeConfigParams {
     setupNeedsCredentials?: boolean;
     devServerNeedsCredentials?: boolean;
     projectDescription?: string;
+    needsVPN?: boolean;
 }
 export interface VerifySetupCommandToolInput {
     command: string;
@@ -497,6 +501,9 @@ export interface SpawnBranchToolInput {
     hidden?: boolean;
     sourceChannelId?: string;
     sourceDmId?: string;
+    sessionMode?: "normal" | "planning" | "deep-research";
+    model?: "auto" | "opus" | "sonnet" | "haiku";
+    attachmentUrls?: string[];
 }
 export interface ReadBranchToolInput {
     projectId: string;
@@ -1731,6 +1738,8 @@ export interface FusionConfig {
     errorIgnorePatterns?: string[];
     /** When true, sync the git working tree to the latest remote state during init */
     syncBranch?: boolean;
+    /** How the PVC was provisioned. Used by InitStateMachine to decide whether to restore from backup. */
+    pvcCreationSource?: "fresh" | "snapshot" | "existing";
     /**
      * Maximum number of agent completions before pausing to ask the user to continue.
      * Read from project settings, with fallback to organization/space settings.
@@ -1770,7 +1779,7 @@ export interface LoadHistoryResult {
     updatedUnixTime: number;
     turns: CodegenTurn[];
 }
-export type InitStateStep = "initial" | "init" | "validation" | "check-directories" | "create-directories" | "configure-git-repos" | "check-existing-git" | "update-remote-url" | "clone-repo" | "apply-partial-backup" | "configure-git-user" | "stash-changes" | "collect-repo-info" | "init-success" | "init-command" | "init-failed" | "snapshot-git-sync";
+export type InitStateStep = "initial" | "init" | "validation" | "check-directories" | "create-directories" | "configure-git-repos" | "check-existing-git" | "update-remote-url" | "clone-repo" | "apply-partial-backup" | "configure-git-user" | "stash-changes" | "collect-repo-info" | "init-success" | "init-command" | "init-failed" | "snapshot-git-sync" | "snapshot-backup-restore";
 export interface InitStatusLog {
     id: number;
     timestamp: string;
@@ -1822,6 +1831,7 @@ export interface LaunchServerStatus {
     activeOperations: number;
     diskUsage?: number;
     memoryUsage?: number;
+    sessionId?: string;
 }
 /**
  * VS Code Tunnel status information
@@ -1869,6 +1879,8 @@ export interface FusionStatus {
     diskUsage?: number;
     /** Current memory usage as a ratio (0-1, where 1 is fully used) */
     memoryUsage?: number;
+    /** Session ID of the active codegen session */
+    sessionId?: string;
 }
 export interface FusionMetrics {
     counters?: {

package/src/connectivity/checks/http-check.d.ts

@@ -5,5 +5,7 @@ export interface HttpCheckOptions {
     testId: TestId;
     timeout?: number;
     fetchFn?: ConnectivityFetchFn;
+    /** Fetch dispatcher for proxy routing (e.g. undici ProxyAgent). */
+    dispatcher?: object;
 }
 export declare function httpCheck(options: HttpCheckOptions): Promise<CheckResult>;

package/src/connectivity/checks/http-check.js

@@ -3,16 +3,26 @@ import { isBrowser } from "../environment.js";
 const DEFAULT_TIMEOUT_MS = 30000;
 const LATENCY_THRESHOLD_MS = 5000;
 export async function httpCheck(options) {
-    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS, fetchFn = fetch, } = options;
+    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS, fetchFn = fetch, dispatcher, } = options;
     const startTime = Date.now();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     try {
-        const response = await fetchFn(target, {
-            method: "HEAD",
-            signal: controller.signal,
-            redirect: isBrowser() ? "follow" : "manual",
-        });
+        const method = "HEAD";
+        const redirect = isBrowser() ? "follow" : "manual";
+        const signal = controller.signal;
+        /**
+         * The custom fetch fn used in dev tools has proxy handling built-in, so no need
+         * for a custom dispatcher.
+         */
+        const response = dispatcher
+            ? await fetch(target, {
+                method,
+                signal,
+                redirect,
+                dispatcher,
+            })
+            : await fetchFn(target, { method, signal, redirect });
         clearTimeout(timeoutId);
         const durationMs = Date.now() - startTime;
         const errorCode = mapHttpStatusToErrorCode(response.status);

package/src/connectivity/checks/tcp-check.d.ts

@@ -1,3 +1,4 @@
+import net from "net";
 import type { CheckResult, Source, TestId } from "../types.js";
 export interface TcpCheckOptions {
     hostname: string;
@@ -5,5 +6,7 @@ export interface TcpCheckOptions {
     source: Source;
     testId: TestId;
     timeout?: number;
+    /** Provide a pre-connected socket (e.g. tunneled through a proxy via CONNECT). */
+    connectFn?: (hostname: string, port: number) => Promise<net.Socket>;
 }
 export declare function tcpCheck(options: TcpCheckOptions): Promise<CheckResult>;

package/src/connectivity/checks/tcp-check.js

@@ -4,11 +4,29 @@ const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_PORT = 443;
 export async function tcpCheck(options) {
     var _a, _b;
-    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, } = options;
+    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, connectFn, } = options;
     const target = `${hostname}:${port}`;
     const startTime = Date.now();
     try {
         const result = await new Promise((resolve) => {
+            if (connectFn) {
+                const timer = setTimeout(() => {
+                    const error = new Error("Connection timed out");
+                    error.code = "ETIMEDOUT";
+                    resolve({ success: false, error });
+                }, timeout);
+                connectFn(hostname, port)
+                    .then((socket) => {
+                    clearTimeout(timer);
+                    socket.destroy();
+                    resolve({ success: true });
+                })
+                    .catch((err) => {
+                    clearTimeout(timer);
+                    resolve({ success: false, error: err });
+                });
+                return;
+            }
             const socket = new net.Socket();
             socket.setTimeout(timeout);
             socket.on("connect", () => {

package/src/connectivity/checks/tls-check.d.ts

@@ -1,3 +1,4 @@
+import type net from "net";
 import type { CheckResult, Source, TestId } from "../types.js";
 export interface TlsCheckOptions {
     hostname: string;
@@ -5,5 +6,7 @@ export interface TlsCheckOptions {
     source: Source;
     testId: TestId;
     timeout?: number;
+    /** Provide a pre-connected socket (e.g. tunneled through a proxy via CONNECT). TLS upgrade happens on top. */
+    connectFn?: (hostname: string, port: number) => Promise<net.Socket>;
 }
 export declare function tlsCheck(options: TlsCheckOptions): Promise<CheckResult>;

package/src/connectivity/checks/tls-check.js

@@ -4,10 +4,38 @@ const DEFAULT_TIMEOUT_MS = 10000;
 const DEFAULT_PORT = 443;
 export async function tlsCheck(options) {
     var _a, _b;
-    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, } = options;
+    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, connectFn, } = options;
     const target = `${hostname}:${port}`;
     const startTime = Date.now();
     try {
+        let tunnelSocket;
+        if (connectFn) {
+            let timedOut = false;
+            const connectPromise = connectFn(hostname, port);
+            tunnelSocket = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    connectPromise.then((s) => s.destroy()).catch(() => { });
+                    const error = new Error("Proxy CONNECT timed out");
+                    error.code = "ETIMEDOUT";
+                    reject(error);
+                }, timeout);
+                connectPromise
+                    .then((socket) => {
+                    clearTimeout(timer);
+                    if (timedOut) {
+                        socket.destroy();
+                    }
+                    else {
+                        resolve(socket);
+                    }
+                })
+                    .catch((err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+            });
+        }
         const result = await new Promise((resolve) => {
             const socket = tls.connect({
                 host: hostname,
@@ -15,6 +43,7 @@ export async function tlsCheck(options) {
                 servername: hostname, // SNI required for virtual hosts
                 rejectUnauthorized: true,
                 timeout,
+                ...(tunnelSocket ? { socket: tunnelSocket } : {}),
             }, () => {
                 const cert = socket.getPeerCertificate();
                 let certInfo;

package/src/connectivity/run-checks.js

@@ -6,7 +6,7 @@ import { tcpCheck } from "./checks/tcp-check.js";
 import { tlsCheck } from "./checks/tls-check.js";
 import { sshCheck } from "./checks/ssh-check.js";
 export async function runChecks(input) {
-    const { tests, gitHost, onProgress, fetchFn } = input;
+    const { tests, gitHost, onProgress, fetchFn, dispatcher, connectFn } = input;
     const results = [];
     const total = tests.length;
     for (let index = 0; index < tests.length; index++) {
@@ -17,7 +17,7 @@ export async function runChecks(input) {
             index,
             total,
         });
-        const result = await runSingleCheck(test, gitHost, fetchFn);
+        const result = await runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn);
         results.push(result);
         emitProgress(onProgress, {
             type: "test:complete",
@@ -36,7 +36,7 @@ export async function runChecks(input) {
         results,
     };
 }
-async function runSingleCheck(test, gitHost, fetchFn) {
+async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
     const { source, testId } = test;
     const checkType = getCheckTypeForTestId(testId);
     if (!isCheckAvailable(checkType)) {
@@ -80,7 +80,7 @@ async function runSingleCheck(test, gitHost, fetchFn) {
     }
     switch (checkType) {
         case "http":
-            return httpCheck({ target, source, testId, fetchFn });
+            return httpCheck({ target, source, testId, fetchFn, dispatcher });
         case "dns":
             return dnsCheck({
                 hostname: extractHostname(target),
@@ -93,6 +93,7 @@ async function runSingleCheck(test, gitHost, fetchFn) {
                 port: extractPort(target, 443),
                 source,
                 testId,
+                connectFn: connectFn,
             });
         case "tls":
             return tlsCheck({
@@ -100,6 +101,7 @@ async function runSingleCheck(test, gitHost, fetchFn) {
                 port: extractPort(target, 443),
                 source,
                 testId,
+                connectFn: connectFn,
             });
         case "ssh":
             return sshCheck({

package/src/connectivity/types.d.ts

@@ -19,6 +19,18 @@ export interface RunChecksInput {
      * environments.
      */
     fetchFn?: ConnectivityFetchFn;
+    /**
+     * Fetch dispatcher for proxy routing (e.g. undici ProxyAgent).
+     * Passed through to the `dispatcher` option of fetch for HTTP checks.
+     * Typically only needed server-side for static IP routing.
+     */
+    dispatcher?: object;
+    /**
+     * Returns a connected socket tunneled through a proxy (via HTTP CONNECT).
+     * Used by TCP and TLS checks for static IP routing. The returned socket
+     * is already connected to hostname:port through the proxy.
+     */
+    connectFn?: (hostname: string, port: number) => Promise<unknown>;
 }
 export type ProgressEvent = {
     type: "test:start";

package/src/projects.d.ts

@@ -343,6 +343,7 @@ export interface PartialBranchData {
     name?: string;
     createdBy: string;
     friendlyName?: string;
+    description?: string;
     isDefault: boolean;
     isPublic: boolean;
     lockedFusionEnvironment?: FusionExecutionEnvironment;
@@ -357,6 +358,7 @@ export interface PartialBranchData {
     useHomeDir?: boolean;
     agentType?: AgentType;
     checkoutBranch?: string | null;
+    prNumber?: number;
     /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
     isFork?: boolean | null;
     /** Whether this branch is for a code review - affects enabled agents and tools*/
@@ -442,6 +444,7 @@ export interface BranchSharedData {
     isPublic?: boolean;
     isDefault?: boolean;
     friendlyName?: string;
+    description?: string;
     useHomeDir?: boolean;
     useCloudHomeDir?: boolean;
     reviewers?: string[] | null;
@@ -772,6 +775,7 @@ export interface CreateBranchOptions {
     featureFlags?: Record<string, boolean>;
     checkoutBranch?: string | null;
     canHandleTools?: (keyof CodeGenToolMap)[];
+    skipPromptAnalysis?: boolean;
     useKube?: boolean;
     fireAndForget?: boolean;
     /** PR number for QA bot branches */
@@ -786,13 +790,6 @@ export interface CreateBranchOptions {
 }
 interface BaseCreateBranchMessage {
 }
-export interface ValidatingProjectMessage extends BaseCreateBranchMessage {
-    type: "validating-project";
-    message: string;
-    projectId: string;
-    projectName?: string;
-    branchName: string;
-}
 export interface CreatingBranchMessage extends BaseCreateBranchMessage {
     type: "creating-branch";
     message: string;
@@ -808,6 +805,7 @@ export interface SettingUpContainerMessage extends BaseCreateBranchMessage {
     projectName: string;
     branchName: string;
     branchFriendlyName: string | undefined;
+    branchDescription: string | undefined;
 }
 export interface ContainerReadyMessage extends BaseCreateBranchMessage {
     type: "container-ready";
@@ -848,7 +846,7 @@ export interface AiMessage extends BaseCreateBranchMessage {
     type: "ai";
     event: GenerateCompletionStep;
 }
-export type CreateBranchChunkMessage = ValidatingProjectMessage | CreatingBranchMessage | SettingUpContainerMessage | SendingInitialMessageMessage | BranchCreatedMessage | CreateBranchErrorMessage | EnsureContainerMessage | ContainerReadyMessage | AiMessage;
+export type CreateBranchChunkMessage = CreatingBranchMessage | SettingUpContainerMessage | SendingInitialMessageMessage | BranchCreatedMessage | CreateBranchErrorMessage | EnsureContainerMessage | ContainerReadyMessage | AiMessage;
 export interface CreateBranchResponse {
     success: boolean;
     branchName?: string;
@@ -935,12 +933,6 @@ export interface ValidatingBranchMessage extends BaseSendMessageMessage {
     projectId: string;
     branchName: string;
 }
-export interface SettingUpContainerMessage extends BaseSendMessageMessage {
-    type: "setting-up-container";
-    message: string;
-    projectId: string;
-    branchName: string;
-}
 export interface SendingMessageMessage extends BaseSendMessageMessage {
     type: "sending-message";
     message: string;