@builder.io/ai-utils 0.48.1 → 0.50.0

package/package.json

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

package/src/codegen.d.ts

@@ -68,6 +68,13 @@ export interface CustomAgentDefinition {
     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;
 }
@@ -332,6 +339,7 @@ export interface TimelineRecording {
         startEventId: number;
         endEventId: number;
         testCaseIds?: string[];
+        replayId?: string;
     }>;
 }
 export interface TimelineSubmissionMetadata {

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

@@ -0,0 +1,21 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface WebSocketCheckOptions {
+    target: string;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+/**
+ * Tests WebSocket connectivity by attempting to open a WSS connection.
+ *
+ * Protocol notes:
+ * - Uses wss:// (WebSocket Secure) — ws:// is blocked by browsers on HTTPS pages
+ *   due to mixed-content restrictions, and wss:// uses port 443 which is typically
+ *   allowed by firewalls that permit HTTPS traffic.
+ * - Considers the check passed as soon as the WebSocket `open` event fires,
+ *   meaning the TCP+TLS+HTTP-upgrade handshake completed successfully.
+ * - A firewall or proxy that blocks WebSocket upgrades (even on the same host/port
+ *   that allows normal HTTPS) will cause the `error` event instead, and the check fails.
+ * - The timeout guards against silent connection drops that never emit an event.
+ */
+export declare function websocketCheck(options: WebSocketCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,90 @@
+const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Tests WebSocket connectivity by attempting to open a WSS connection.
+ *
+ * Protocol notes:
+ * - Uses wss:// (WebSocket Secure) — ws:// is blocked by browsers on HTTPS pages
+ *   due to mixed-content restrictions, and wss:// uses port 443 which is typically
+ *   allowed by firewalls that permit HTTPS traffic.
+ * - Considers the check passed as soon as the WebSocket `open` event fires,
+ *   meaning the TCP+TLS+HTTP-upgrade handshake completed successfully.
+ * - A firewall or proxy that blocks WebSocket upgrades (even on the same host/port
+ *   that allows normal HTTPS) will cause the `error` event instead, and the check fails.
+ * - The timeout guards against silent connection drops that never emit an event.
+ */
+export async function websocketCheck(options) {
+    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS } = options;
+    const startTime = Date.now();
+    return new Promise((resolve) => {
+        let settled = false;
+        let ws = null;
+        const timeoutId = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            ws === null || ws === void 0 ? void 0 : ws.close();
+            resolve({
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "tcp_connection_timeout",
+                durationMs: Date.now() - startTime,
+                metadata: {
+                    error: "WebSocket connection timed out",
+                    timeoutMs: timeout,
+                },
+            });
+        }, timeout);
+        try {
+            ws = new WebSocket(target);
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            settled = true;
+            resolve({
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "unknown_error",
+                durationMs: Date.now() - startTime,
+                metadata: {
+                    error: err instanceof Error ? err.message : "Failed to create WebSocket",
+                },
+            });
+            return;
+        }
+        ws.onopen = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutId);
+            const durationMs = Date.now() - startTime;
+            ws === null || ws === void 0 ? void 0 : ws.close(1000);
+            resolve({
+                source,
+                testId,
+                target,
+                passed: true,
+                durationMs,
+                metadata: { protocol: (ws === null || ws === void 0 ? void 0 : ws.protocol) || undefined },
+            });
+        };
+        ws.onerror = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutId);
+            resolve({
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "tcp_connection_refused",
+                durationMs: Date.now() - startTime,
+                metadata: { error: "WebSocket connection failed" },
+            });
+        };
+    });
+}

package/src/connectivity/environment.js

@@ -7,13 +7,17 @@ export function isNode() {
         process.versions.node != null);
 }
 export function getCheckTypeForTestId(testId) {
+    if (testId === "health.builderio.xyz:ws" ||
+        testId === "health.builderio.dev:ws") {
+        return "websocket";
+    }
     if (testId.startsWith("git-host:")) {
         return testId.replace("git-host:", "");
     }
     return "http";
 }
 export function isCheckAvailable(checkType) {
-    if (checkType === "http") {
+    if (checkType === "http" || checkType === "websocket") {
         return true;
     }
     // DNS, TCP, TLS, and SSH checks require Node.js modules
@@ -21,7 +25,7 @@ export function isCheckAvailable(checkType) {
 }
 export function getUnavailabilityReason(checkType) {
     if (isBrowser()) {
-        return `${checkType.toUpperCase()} checks are not available in browser environments. Only HTTP checks can be performed from the browser.`;
+        return `${checkType.toUpperCase()} checks are not available in browser environments. Only HTTP and WebSocket checks can be performed from the browser.`;
     }
     return `${checkType.toUpperCase()} checks are not available in this environment.`;
 }

package/src/connectivity/run-checks.browser.js

@@ -1,6 +1,7 @@
 import { resolveTarget } from "./targets.js";
 import { getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 import { httpCheck } from "./checks/http-check.js";
+import { websocketCheck } from "./checks/websocket-check.js";
 export async function runChecks(input) {
     const { tests, gitHost, onProgress } = input;
     const results = [];
@@ -77,6 +78,8 @@ async function runSingleCheck(test, gitHost) {
     switch (checkType) {
         case "http":
             return httpCheck({ target, source, testId });
+        case "websocket":
+            return websocketCheck({ target, source, testId });
         default:
             return {
                 source,

package/src/connectivity/run-checks.js

@@ -1,6 +1,7 @@
 import { resolveTarget, extractHostname, extractPort, extractExplicitPort, } from "./targets.js";
 import { getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 import { httpCheck } from "./checks/http-check.js";
+import { websocketCheck } from "./checks/websocket-check.js";
 import { dnsCheck } from "./checks/dns-check.js";
 import { tcpCheck } from "./checks/tcp-check.js";
 import { tlsCheck } from "./checks/tls-check.js";
@@ -81,6 +82,8 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
     switch (checkType) {
         case "http":
             return httpCheck({ target, source, testId, fetchFn, dispatcher });
+        case "websocket":
+            return websocketCheck({ target, source, testId });
         case "dns":
             return dnsCheck({
                 hostname: extractHostname(target),

package/src/connectivity/targets.js

@@ -3,8 +3,10 @@ export const BUILDER_TARGETS = {
     "builder.codes": "https://test.projects.builder.codes/proxy-health",
     "api.builder.io": "https://api.builder.io/codegen/health",
     "cdn.builder.io": "https://cdn.builder.io/api/v1/image/assets/TEMP/75a212ab82b6175c9862b125e0e23db8d369a58a?width=100",
-    "builderio.xyz": "https://builderio.xyz/health",
     "health.builderio.xyz": "https://health.builderio.xyz/health",
+    "health.builderio.xyz:ws": "wss://health.builderio.xyz/ws",
+    "health.builderio.dev": "https://health.builderio.dev/health",
+    "health.builderio.dev:ws": "wss://health.builderio.dev/ws",
     "fly.dev": "https://fly.dev",
 };
 export const DEFAULT_PORTS = {

package/src/connectivity/types.d.ts

@@ -1,5 +1,5 @@
 export type Source = "local" | "cloud" | "static-ip";
-export type TestId = "builder.io" | "builder.codes" | "api.builder.io" | "cdn.builder.io" | "builderio.xyz" | "health.builderio.xyz" | "fly.dev" | "git-host:http" | "git-host:dns" | "git-host:tcp" | "git-host:tls" | "git-host:ssh";
+export type TestId = "builder.io" | "builder.codes" | "api.builder.io" | "cdn.builder.io" | "health.builderio.xyz" | "health.builderio.xyz:ws" | "health.builderio.dev" | "health.builderio.dev:ws" | "fly.dev" | "git-host:http" | "git-host:dns" | "git-host:tcp" | "git-host:tls" | "git-host:ssh";
 export interface Test {
     source: Source;
     testId: TestId;
@@ -61,7 +61,7 @@ export interface CheckReport {
     results: CheckResult[];
 }
 export type ConnectivityErrorCode = "dns_resolution_failed" | "dns_timeout" | "dns_wrong_ip" | "tcp_connection_refused" | "tcp_connection_timeout" | "tcp_connection_reset" | "tcp_host_unreachable" | "tcp_network_unreachable" | "tls_self_signed_cert" | "tls_cert_expired" | "tls_cert_not_yet_valid" | "tls_cert_invalid" | "tls_cert_hostname_mismatch" | "tls_handshake_failed" | "tls_protocol_error" | "proxy_auth_required" | "proxy_connection_failed" | "proxy_tunnel_failed" | "http_unauthorized" | "http_forbidden" | "http_not_found" | "http_server_error" | "http_service_unavailable" | "latency_high" | "check_unavailable" | "unknown_error";
-export type CheckType = "http" | "dns" | "tcp" | "tls" | "ssh";
+export type CheckType = "http" | "websocket" | "dns" | "tcp" | "tls" | "ssh";
 export type Recommendation = "ready_for_cloud_dev" | "enable_static_ip_proxy" | "whitelist_static_ip" | "fix_local_dns" | "fix_local_tls_certs" | "fix_local_firewall" | "use_local_development";
 export type LikelyCause = "ip_whitelisting_required" | "vpn_blocking" | "corporate_proxy_required" | "self_signed_certificate" | "dns_misconfiguration" | "firewall_blocking" | "server_unavailable";
 export type ConnectivityStatus = "pass" | "fail" | "unknown";

package/src/projects.d.ts

@@ -144,6 +144,8 @@ export interface ReadyMessage extends BaseMessage {
     state: "ready";
     message: string;
     url: string;
+    /** Public kube hostnames (no scheme), e.g. `*.builderio.xyz` and `*.builderio.dev` when both are routed. */
+    hostnames?: string[];
     status?: LaunchServerStatus;
 }
 export type MachineState = "unknown" | "created" | "starting" | "started" | "stopping" | "stopped" | "suspending" | "suspended" | "replacing" | "destroying" | "destroyed" | "not-found" | "running" | "failed";
@@ -480,6 +482,8 @@ export interface BranchSharedData {
     kubeNamespace?: string | null;
     kubePvcName?: string | null;
     kubeHostname?: string | null;
+    /** Public kube hostnames for this branch (no scheme), when more than one domain is available. */
+    kubeHostnames?: string[] | null;
     checkoutBranch?: string | null;
     /** Whether this branch is for a fork PR - affects git operations (read-only, can't push) */
     isFork?: boolean | null;
@@ -563,6 +567,10 @@ export interface ProjectAccessControl {
     roles: Record<string, ProjectRolePermissions | null>;
     users: Record<string, ProjectRolePermissions>;
 }
+export interface PreviewPasswordProtection {
+    enabled: boolean;
+    password?: string;
+}
 export interface Project {
     id: string;
     name: string;
@@ -686,6 +694,7 @@ export interface Project {
         /** VPC peering ID for this project. Overrides the space-level defaultVpcPeering.
          *  References a document in the vpcPeerings collection. */
         vpcPeering?: string;
+        previewPasswordProtection?: PreviewPasswordProtection;
     };
     screenshot: string | null;
     isExample?: boolean;
@@ -823,6 +832,18 @@ export interface CreateBranchOptions {
     gitAiBranch?: string | null;
     /** Contextual information (e.g., a git diff) used by the backend to generate a friendly branch name via LLM */
     branchContext?: string;
+    /**
+     * Lifecycle hook awaited by createBranch after the container is ready and
+     * before the initial message is dispatched to devtools/codegen. Use this to
+     * register webhook hooks so they're guaranteed to be in place before the
+     * first events stream out. Errors are caught + reported and do not block
+     * message dispatch.
+     */
+    onContainerReady?: (info: {
+        projectId: string;
+        branchName: string;
+        url: string;
+    }) => Promise<void> | void;
 }
 interface BaseCreateBranchMessage {
 }