@builder.io/ai-utils 0.22.2 → 0.22.3

package/package.json

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

package/src/codegen.d.ts

@@ -2,7 +2,7 @@ import type { Attachment, ContentMessageItemToolResult } from "./messages";
 import type { BuilderContent } from "./completion";
 import type { Options as PrettierOptions } from "prettier";
 import type { UserContext } from "./mapping";
-import type { ForcedBackup, SetupDependency } from "./projects";
+import type { ForcedBackup, SetupDependency, GitDiagnostics } from "./projects";
 import type { Feature } from "./features";
 import type { CpuKind } from "./projects";
 export type ImportType = "named" | "default";
@@ -192,7 +192,7 @@ export interface BuilderEditToolInput {
     new_str: string;
 }
 export interface GetScreenshotToolInput {
-    href: string;
+    href?: string;
     url?: string;
     selector?: string;
     width?: number;
@@ -1467,6 +1467,11 @@ export interface FusionConfig {
      * Errors matching these patterns will not show the error popup.
      */
     errorIgnorePatterns?: string[];
+    /**
+     * Maximum number of agent completions before pausing to ask the user to continue.
+     * Read from project settings, with fallback to organization/space settings.
+     */
+    maxAgentCompletions?: number;
     /** @deprecated use devCommand */
     command?: string;
 }
@@ -1512,6 +1517,7 @@ export interface InitState {
     success: boolean;
     currentStep: InitStateStep;
     error: string | undefined;
+    gitDiagnostics?: GitDiagnostics;
     repos: {
         repoName: string;
         enabledGit: boolean;

package/src/connectivity/browser.d.ts

@@ -1,6 +1,6 @@
 export type { Source, TestId, Test, RunChecksInput, ProgressEvent, CheckResult, CheckReport, ConnectivityErrorCode, CheckType, Recommendation, LikelyCause, ConnectivityStatus, AnalysisResult, AnalyzeConnectivityInput, } from "./types.js";
 export { runChecks } from "./run-checks.browser.js";
-export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
 export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
 export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 export { httpCheck } from "./checks/http-check.js";

package/src/connectivity/browser.js

@@ -1,5 +1,5 @@
 export { runChecks } from "./run-checks.browser.js";
-export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
 export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
 export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 export { httpCheck } from "./checks/http-check.js";

package/src/connectivity/error-codes.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectivityErrorCode } from "./types.js";
+import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./types.js";
 export declare const SELF_SIGNED_CERT_ERRORS: Set<string>;
 export declare const CERT_EXPIRED_ERRORS: Set<string>;
 export declare const CERT_NOT_YET_VALID_ERRORS: Set<string>;
@@ -19,3 +19,18 @@ export declare function mapFetchErrorToConnectivityCode(error: Error & {
         code?: string;
     };
 }): ConnectivityErrorCode;
+/**
+ * Map a connectivity error code to a likely cause for recommendations.
+ * Shared by the connectivity analyzer and git error diagnostics so both
+ * show consistent likely-cause messaging.
+ */
+export declare function connectivityErrorCodeToLikelyCause(errorCode: ConnectivityErrorCode | undefined): LikelyCause | undefined;
+/**
+ * Map a connectivity error message string (e.g. from a simple DNS/TCP check)
+ * to a connectivity error code and check type. Used when building GitDiagnostics
+ * from checks that don't use the full runChecks/CheckResult pipeline.
+ */
+export declare function mapConnectivityErrorMessage(errorMessage: string): {
+    connectivityErrorCode: ConnectivityErrorCode;
+    checkType: CheckType;
+} | null;

package/src/connectivity/error-codes.js

@@ -165,3 +165,104 @@ export function mapFetchErrorToConnectivityCode(error) {
     }
     return "unknown_error";
 }
+/**
+ * Map a connectivity error code to a likely cause for recommendations.
+ * Shared by the connectivity analyzer and git error diagnostics so both
+ * show consistent likely-cause messaging.
+ */
+export function connectivityErrorCodeToLikelyCause(errorCode) {
+    if (!errorCode)
+        return undefined;
+    const timeoutCodes = [
+        "tcp_connection_timeout",
+        "tcp_host_unreachable",
+        "tcp_network_unreachable",
+    ];
+    if (timeoutCodes.includes(errorCode))
+        return "ip_whitelisting_required";
+    const dnsCodes = [
+        "dns_resolution_failed",
+        "dns_timeout",
+        "dns_wrong_ip",
+    ];
+    if (dnsCodes.includes(errorCode))
+        return "dns_misconfiguration";
+    const tlsCodes = [
+        "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",
+    ];
+    if (tlsCodes.includes(errorCode))
+        return "self_signed_certificate";
+    const firewallCodes = [
+        "tcp_connection_refused",
+        "tcp_connection_reset",
+    ];
+    if (firewallCodes.includes(errorCode))
+        return "firewall_blocking";
+    const proxyCodes = [
+        "proxy_auth_required",
+        "proxy_connection_failed",
+        "proxy_tunnel_failed",
+    ];
+    if (proxyCodes.includes(errorCode))
+        return "corporate_proxy_required";
+    if (errorCode === "http_service_unavailable" ||
+        errorCode === "http_server_error") {
+        return "server_unavailable";
+    }
+    return undefined;
+}
+/**
+ * Map a connectivity error message string (e.g. from a simple DNS/TCP check)
+ * to a connectivity error code and check type. Used when building GitDiagnostics
+ * from checks that don't use the full runChecks/CheckResult pipeline.
+ */
+export function mapConnectivityErrorMessage(errorMessage) {
+    const lower = errorMessage.toLowerCase();
+    if (lower.includes("dns resolution failed") ||
+        lower.includes("dns resolution") ||
+        lower.includes("no addresses found")) {
+        return {
+            connectivityErrorCode: "dns_resolution_failed",
+            checkType: "dns",
+        };
+    }
+    if (lower.includes("connection attempt failed") ||
+        lower.includes("connection timed out") ||
+        lower.includes("connection timeout") ||
+        lower.includes("etimedout") ||
+        lower.includes("timed out")) {
+        return {
+            connectivityErrorCode: "tcp_connection_timeout",
+            checkType: "tcp",
+        };
+    }
+    if (lower.includes("econnrefused") || lower.includes("connection refused")) {
+        return {
+            connectivityErrorCode: "tcp_connection_refused",
+            checkType: "tcp",
+        };
+    }
+    // ENOTFOUND, getaddrinfo, EAI_AGAIN, ENODATA are DNS resolution errors (aligned with DNS_ERRORS and mapNodeErrorToConnectivityCode)
+    if (lower.includes("enotfound") ||
+        lower.includes("getaddrinfo") ||
+        lower.includes("eai_again") ||
+        lower.includes("enodata")) {
+        return {
+            connectivityErrorCode: "dns_resolution_failed",
+            checkType: "dns",
+        };
+    }
+    if (lower.includes("network unreachable")) {
+        return {
+            connectivityErrorCode: "tcp_network_unreachable",
+            checkType: "tcp",
+        };
+    }
+    return null;
+}

package/src/connectivity/node.d.ts

@@ -1,6 +1,6 @@
 export type { Source, TestId, Test, RunChecksInput, ProgressEvent, CheckResult, CheckReport, ConnectivityErrorCode, CheckType, Recommendation, LikelyCause, ConnectivityStatus, AnalysisResult, AnalyzeConnectivityInput, } from "./types.js";
 export { runChecks } from "./run-checks.js";
-export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
 export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
 export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 export { httpCheck } from "./checks/http-check.js";

package/src/connectivity/node.js

@@ -1,5 +1,5 @@
 export { runChecks } from "./run-checks.js";
-export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
 export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
 export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
 export { httpCheck } from "./checks/http-check.js";

package/src/index.d.ts

@@ -10,3 +10,4 @@ export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
 export * from "./connectivity/types.js";
+export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -10,3 +10,4 @@ export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
 export * from "./connectivity/types.js";
+export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/organization.d.ts

@@ -79,6 +79,7 @@ interface OrganizationSettings {
     fusionPrLabel?: string;
     fusionPrQuietMode?: boolean;
     runInPty?: boolean;
+    maxAgentCompletions?: number;
     privacyMode?: Pick<PrivacyMode, "mcpServers" | "redactUserMessages" | "redactLLMMessages"> & {
         enabled?: boolean;
     };

package/src/projects.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
 import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition } from "./codegen";
 import type { FallbackTokensPrivate } from "./organization";
 /**
@@ -148,6 +149,54 @@ export interface ReadyMessage extends BaseMessage {
 export type MachineState = "unknown" | "created" | "starting" | "started" | "stopping" | "stopped" | "suspending" | "suspended" | "replacing" | "destroying" | "destroyed" | "not-found" | "running" | "failed";
 export type FlyVolumeState = "unknown" | "creating" | "created" | "extending" | "restoring" | "enabling_remote_export" | "hydrating" | "recovering" | "scheduling_destroy" | "pending_destroy" | "failed";
 export type GitAuthErrorCode = "git-auth-failed" | "git-auth-failed-root-repo" | "git-auth-failed-folder-added-by" | "git-auth-failed-folder-created-by" | "git-auth-failed-repo-not-found" | "git-auth-failed-repo-renamed" | "git-auth-failed-folder-server-token" | "git-auth-failed-root-repo-server-token" | "git-auth-failed-ghes-unreachable";
+/**
+ * Git provider types for diagnostics.
+ */
+export type GitDiagnosticsProvider = "github" | "bitbucket" | "gitlab" | "azure" | "unknown";
+/**
+ * Detect git provider from a repository URL (HTTPS or SSH).
+ * Used by both error diagnostics and connectivity checks for consistent provider labeling.
+ */
+export declare function getGitProviderFromUrl(url: string): GitDiagnosticsProvider;
+/**
+ * Issue classification for git-related errors.
+ * - access: Repository access issues (404, repo doesn't exist, insufficient permissions)
+ * - auth: Authentication issues (token expired, invalid credentials)
+ * - network: Network issues (timeouts, connection failures, unreachable hosts)
+ * - unknown: Should be avoided - not helpful for debugging
+ */
+export type GitDiagnosticsIssue = "access" | "auth" | "network" | "unknown";
+/**
+ * Diagnostic information for git-related errors.
+ * Helps frontend display actionable error messages.
+ * Optional connectivity fields align with the connectivity check feature so that
+ * when a git error is due to network/connectivity, we can pass through granular
+ * error codes and likely causes for better UX and recommendations.
+ */
+export interface GitDiagnostics {
+    provider: GitDiagnosticsProvider;
+    hostname: string;
+    /**
+     * Source IP for debugging network issues: when using an HTTP proxy for outbound
+     * git requests, use the proxy host/IP; otherwise the egress IP of the running machine if known.
+     */
+    sourceIp: string;
+    repoName: string;
+    issue: GitDiagnosticsIssue;
+    /**
+     * When issue is "network" (or from a connectivity check), the specific
+     * connectivity error code from the check result, if available.
+     */
+    connectivityErrorCode?: ConnectivityErrorCode;
+    /**
+     * Which kind of check failed (dns, tcp, tls, http, ssh). Omitted when not from a connectivity check.
+     */
+    checkType?: CheckType;
+    /**
+     * Suggested likely cause for the failure; can drive recommendations (e.g. whitelist IP, fix DNS).
+     */
+    likelyCause?: LikelyCause;
+}
 export type EnsureContainerErrorCode = "FAILED_TO_START_MACHINE_ERROR" | "FLY_APP_CHECK_ERROR" | "FLY_CAPACITY_ERROR" | "FLY_PERMISSIONS_TOKEN_ERROR" | "FLY_VOLUME_CREATE_ERROR" | "FLY_VOLUME_FORK_ERROR" | "FLY_VOLUME_DELETE_RECENTLY_FORKED_ERROR" | "FLY_MACHINE_CREATE_ERROR" | "FLY_VOLUME_CHECK_ERROR" | "FLY_NON_MOUNTABLE_VOLUME_ERROR" | "FLY_DEPRECATED_REGION_ERROR" | "FLY_VOLUME_NOT_FOUND" | "FLY_MACHINE_LIMIT_ERROR" | "KUBE_CAPACITY_ERROR" | "KUBE_PERMISSIONS_ERROR" | "KUBE_POD_LIMIT_ERROR" | "KUBE_RESOURCE_QUOTA_ERROR" | "KUBE_NAMESPACE_CHECK_ERROR" | "KUBE_PVC_CREATE_ERROR" | "KUBE_PVC_CHECK_ERROR" | "KUBE_POD_CREATE_ERROR" | "KUBE_SERVICE_CREATE_ERROR" | "KUBE_INGRESS_CREATE_ERROR" | "KUBE_POD_FAILED_TO_START_ERROR" | "ensure-checking-existing-machines" | "found-multiple-failed-machine" | "maximun-retries-machine-creation" | GitAuthErrorCode | "unknown" | "project-bad-state" | "project-not-found" | "project-deleted" | "project-branch-not-found" | "project-branch-deleted" | "project-branch-no-session-id" | "project-repo-full-name-not-found" | "project-org-not-found" | "invalid-project-repo-url-already-in-use" | "no-available-regions" | "invalid-backup-without-volume-id" | "missing-app-with-machine-or-volume" | "update-branch-info-in-firebase" | "update-branch-app-name-in-firebase" | `machine-status-polling-${MachineState}` | `machine-image-exited-immediately` | `volume-not-found-${FlyVolumeState}` | "trying-to-remove-used-volume" | "missing-container-url" | "timeout" | "fatal:zod-validation-error" | `fatal:${string}`;
 export interface ErrorStateMessage extends BaseMessage {
     state: "error";
@@ -210,6 +259,13 @@ export interface GitBackupRecordOptions {
     forced: ForcedBackup;
     metadata?: Record<string, string | string[] | undefined>;
 }
+export interface RecordScreenshotOptions {
+    projectId: string;
+    branchName: string;
+    completionId?: string;
+    screenshotUrl: string;
+    meta?: Record<string, any>;
+}
 export interface GitBackupRecordResult {
     success: boolean;
 }
@@ -391,6 +447,7 @@ interface BranchSharedData {
     lastActivityAt?: number;
     /** Whether the branch has unpushed changes (ahead > 0 or dirty working directory) */
     hasUnpushedChanges?: boolean;
+    screenshot?: string | null;
 }
 /**
  * fields that are required in the new branch format, but optional in the legacy branch format.
@@ -500,7 +557,7 @@ export interface Project {
         autoStop?: MachineAutoStop;
         mainBranchName?: string;
         minMachinesRunning?: number;
-        volumeSize?: 5 | 10 | 12 | 15 | 20;
+        volumeSize?: 5 | 10 | 12 | 15 | 20 | 25 | 30 | 50;
         includePath?: string;
         includePatterns?: string[];
         environmentVariables?: EnvironmentVariable[];
@@ -541,6 +598,7 @@ export interface Project {
         };
         postMergeMemories?: boolean;
         commitInstructions?: string;
+        maxAgentCompletions?: number;
         httpsServerKeyPath?: string;
         httpsServerCertPath?: string;
         httpsServerCaPath?: string;

package/src/projects.js

@@ -1,3 +1,25 @@
+/**
+ * Detect git provider from a repository URL (HTTPS or SSH).
+ * Used by both error diagnostics and connectivity checks for consistent provider labeling.
+ */
+export function getGitProviderFromUrl(url) {
+    try {
+        const lower = url.toLowerCase();
+        // Prefer canonical hostnames to avoid false positives (e.g. custom host with "github" in name)
+        if (lower.includes("github.com"))
+            return "github";
+        if (lower.includes("gitlab.com"))
+            return "gitlab";
+        if (lower.includes("bitbucket.org"))
+            return "bitbucket";
+        if (lower.includes("dev.azure.com"))
+            return "azure";
+        return "unknown";
+    }
+    catch (_a) {
+        return "unknown";
+    }
+}
 export const EXAMPLE_REPOS = [
     "steve8708/mui-vite",
     "steve8708/carbon-vite",