@builder.io/ai-utils 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "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

@@ -92,6 +92,8 @@ export interface DevServerControlInput {
 }
 export interface DevServerLogsInput {
 }
+export interface DevServerRestartInput {
+}
 export interface BashToolInput {
     command?: string | null;
     timeout?: number | null;
@@ -179,6 +181,8 @@ export interface AgentToolInput {
     prompt: string;
     subagent_type?: string;
     resume?: string;
+    origin_channel_id?: string;
+    attachmentUrls?: string[];
 }
 export interface ListDirToolInput {
     path: string;
@@ -450,8 +454,8 @@ export interface ProposeConfigParams {
     isMicrofrontend?: boolean;
     setupNeedsCredentials?: boolean;
     devServerNeedsCredentials?: boolean;
-    projectDescription?: string;
     needsVPN?: boolean;
+    projectDescription?: string;
 }
 export interface VerifySetupCommandToolInput {
     command: string;
@@ -479,6 +483,11 @@ export interface VerifyRuntimeDependencyToolInput {
     version: string;
     source?: string;
 }
+export interface ProposeEnvVariableToolInput {
+    key: string;
+    value: string;
+    secret?: boolean;
+}
 export interface SetEnvVariableToolInput {
     key: string;
     value: string;
@@ -499,6 +508,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;
@@ -580,6 +592,7 @@ export interface CodeGenToolMap {
     Glob: GlobSearchToolInput;
     DevServerControl: DevServerControlInput;
     DevServerLogs: DevServerLogsInput;
+    DevServerRestart: DevServerRestartInput;
     Revert: RevertToolInput;
     TodoRead: TodoReadToolInput;
     TodoWrite: TodoWriteToolInput;
@@ -604,6 +617,7 @@ export interface CodeGenToolMap {
     VerifyDevServer: VerifyDevServerToolInput;
     VerifyValidateCommand: VerifyValidateCommandToolInput;
     VerifyRuntimeDependency: VerifyRuntimeDependencyToolInput;
+    ProposeEnvVariable: ProposeEnvVariableToolInput;
     SetEnvVariable: SetEnvVariableToolInput;
     SendMessage: SendMessageToolInput;
     SpawnBranch: SpawnBranchToolInput;
@@ -1733,6 +1747,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.
@@ -1772,7 +1788,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;

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, dispatcher } = 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, dispatcher);
+        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, dispatcher) {
+async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
     const { source, testId } = test;
     const checkType = getCheckTypeForTestId(testId);
     if (!isCheckAvailable(checkType)) {
@@ -93,6 +93,7 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher) {
                 port: extractPort(target, 443),
                 source,
                 testId,
+                connectFn: connectFn,
             });
         case "tls":
             return tlsCheck({
@@ -100,6 +101,7 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher) {
                 port: extractPort(target, 443),
                 source,
                 testId,
+                connectFn: connectFn,
             });
         case "ssh":
             return sshCheck({

package/src/connectivity/types.d.ts

@@ -25,6 +25,12 @@ export interface RunChecksInput {
      * 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/events.d.ts

@@ -493,6 +493,14 @@ export declare const ClientDevtoolsSessionStartedEvent: {
     eventName: "client.devtools.session.started";
     version: "1";
 };
+export type ClientDevtoolsSessionIdleEventV1 = FusionEventVariant<"client.devtools.session.idle", {
+    sessionId?: string;
+    lastMessage?: string;
+}, {}, 1>;
+export declare const ClientDevtoolsSessionIdleEventV1: {
+    eventName: "client.devtools.session.idle";
+    version: "1";
+};
 export type FusionProjectCreatedV1 = FusionEventVariant<"fusion.project.created", {
     projectId: string;
     branchName?: string;
@@ -546,7 +554,7 @@ export interface SendMessageToOrgAgentInput {
     senderDisplayName?: string;
     messageContext?: string;
 }
-export type FusionEvent = AiTaskCompletedEvent | AiTaskFailedEvent | GitPrCreatedEvent | ClientDevtoolsSessionStartedEvent | FusionProjectCreatedV1 | SetupAgentCompletedV1 | ForceSetupAgentV1 | ClawMessageSentV1;
+export type FusionEvent = AiTaskCompletedEvent | AiTaskFailedEvent | GitPrCreatedEvent | ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | ForceSetupAgentV1 | ClawMessageSentV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -14,6 +14,10 @@ export const ClientDevtoolsSessionStartedEvent = {
     eventName: "client.devtools.session.started",
     version: "1",
 };
+export const ClientDevtoolsSessionIdleEventV1 = {
+    eventName: "client.devtools.session.idle",
+    version: "1",
+};
 export const FusionProjectCreatedV1 = {
     eventName: "fusion.project.created",
     version: "1",

package/src/projects.d.ts

@@ -775,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 */
@@ -789,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;
@@ -811,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";
@@ -851,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;
@@ -938,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;