@builder.io/ai-utils 0.14.3 → 0.15.0

package/package.json

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

package/src/codegen.d.ts

@@ -175,7 +175,8 @@ export interface BuilderEditToolInput {
     new_str: string;
 }
 export interface GetScreenshotToolInput {
-    url: string;
+    href: string;
+    url?: string;
     selector?: string;
     width?: number;
     height?: number;
@@ -466,12 +467,46 @@ export interface GenerateCompletionStepText {
     type: "text";
     content: string;
 }
+/**
+ * Represents the current state and composition of the AI model's context window.
+ * Used to track token usage and provide a breakdown of what content is consuming the context.
+ */
 export interface ContextWindow {
+    /** Percentage of context window currently in use (0-1 range) */
     usage: number;
+    /** Total number of tokens currently used in the context */
     usedTokens: number;
+    /** Number of tokens that are cached (reduces cost on subsequent requests) */
     cachedTokens: number;
+    /** Maximum tokens available in the model's context window */
     totalTokens: number;
-    details: Record<string, any>;
+    /** Reserved token buffer to allow for compaction before hitting the limit */
+    compactBufferTokens: number;
+    /**
+     * Breakdown of context window usage by category, with each value representing
+     * 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`)
+     * - `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)
+     * - `system` - Tokens from system prompt content
+     * - `rules` - Tokens from custom instructions/rules
+     * - `memory` - Tokens from memory/context persistence
+     * - `reminder` - Tokens from generic system reminders
+     * - `reminder:plan` - Tokens from plan mode prompts
+     * - `reminder:framework` - Tokens from framework-specific prompts
+     * - `reminder:design-system` - Tokens from design system context
+     * - `reminder:ui-context` - Tokens from UI context information
+     * - `reminder:health` - Tokens from dev server health status
+     * - `reminder:url` - Tokens from dev server URL information
+     * - `reminder:environment-variables` - Tokens from environment variable context
+     * - `reminder:git-status` - Tokens from git status information
+     * - `reminder:modified-files-context` - Tokens from modified files diff context
+     * - `rest` - Tokens from other text content without a specific tag
+     */
+    details: Record<string, number>;
 }
 export interface GenerateCompletionStepDone {
     type: "done";
@@ -484,7 +519,7 @@ export interface GenerateCompletionStepDone {
     model: string;
     usage: CodegenUsage | undefined;
     url?: string;
-    promptVersion: string;
+    promptVersion: string | undefined;
     stopReason: CompletionStopReason;
     hasChanges: boolean;
 }
@@ -872,7 +907,7 @@ export interface GenerateCodeEventDone {
     nextUrl: string;
     autoContinue: boolean;
     model: string;
-    promptVersion: string;
+    promptVersion: string | undefined;
 }
 export interface GenerateCodeEventError {
     type: "error";
@@ -1028,13 +1063,13 @@ export interface AccessResult {
     allowed: boolean;
     message: string;
 }
-export type RemoteMachineConfig = {
+export interface RemoteMachineConfig {
     cpus: number;
     memory: number;
     region: string;
     cpuKind?: CpuKind;
     volumeSize: number;
-};
+}
 export type MachineConfig = (RemoteMachineConfig & {
     environment: "cloud" | "cloud-v2" | "unknown";
 }) | {

package/src/messages.d.ts

@@ -57,6 +57,7 @@ export interface ContentMessageItemToolResult {
     is_error?: boolean;
     cache?: boolean;
     ephemeral?: boolean;
+    structured_result?: Record<string, any>;
 }
 export interface ImageBase64Source {
     type: "base64";

package/src/organization.d.ts

@@ -19,11 +19,47 @@ export interface GitlabEnterprisePATValue {
     botUsername: string;
     secondaryHost?: string;
 }
+/**
+ * Public metadata for GitLab fallback token (stored in organizations collection).
+ */
 export interface GitlabCloudFallbackToken {
-    token: string;
+    configured: boolean;
+    createdBy: string;
+    createdAt: number;
+}
+/**
+ * Public metadata for Azure fallback token (stored in organizations collection).
+ */
+export interface AzureCloudFallbackToken {
+    configured: boolean;
+    organization: string;
     createdBy: string;
     createdAt: number;
 }
+/**
+ * Public metadata for Bitbucket fallback token (stored in organizations collection).
+ */
+export interface BitbucketCloudFallbackToken {
+    configured: boolean;
+    username: string;
+    email: string;
+    createdBy: string;
+    createdAt: number;
+}
+/**
+ * Private fallback tokens stored in organizations_private collection.
+ */
+export interface FallbackTokensPrivate {
+    gitlab?: {
+        token: string;
+    };
+    azure?: {
+        token: string;
+    };
+    bitbucket?: {
+        token: string;
+    };
+}
 interface OrganizationSettings {
     attribution?: string[];
     visualEditorAiStyleInspirationURL?: string;
@@ -39,6 +75,8 @@ interface OrganizationSettings {
     githubEnterpriseSetupValue?: GithubEnterpriseSetupValue;
     gitlabEnterprisePAT?: GitlabEnterprisePATValue;
     gitlabCloudFallbackToken?: GitlabCloudFallbackToken;
+    azureCloudFallbackToken?: AzureCloudFallbackToken;
+    bitbucketCloudFallbackToken?: BitbucketCloudFallbackToken;
     bitbucketEnterprisePAT?: BitbucketEnterprisePAT;
     useProxy?: boolean;
     fusionShareableUrlSuffix?: string;

package/src/projects.d.ts

@@ -1,4 +1,5 @@
 import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode } from "./codegen";
+import type { FallbackTokensPrivate } from "./organization";
 export interface ConfigStatus {
     isReady: boolean;
     lastUpdated: string;
@@ -152,10 +153,11 @@ export interface CleanupCompletedMessage extends BaseMessage {
  * Messages sent by the container orchestrator.
  */
 export type ProjectsChunkMessage = InitializingMessage | FetchingGithubTokenMessage | FetchingFusionKeyMessage | CheckingAppMessage | CleaningUpAppMessage | CreatingAppMessage | CheckingIPMessage | AllocatingIPMessage | CheckingMachineMessage | CheckingVolumeMessage | ForkingVolumeMessage | RetryingWithNewRegionMessage | WaitingBeforePollingMessage | PollingMachineStatusMessage | WarningStateMessage | PingMessage | DebugMessage | ErrorMessage | InfoMessage | WarningMessage | MachineStatusMessage | LogsMessage | ConfigStatusMessage | AppCreatedMessage | MachineCreatedMessage | IpAllocatedMessage | VolumeForkedMessage | ReadyMessage | ErrorStateMessage | CleanupCompletedMessage;
-export type GitConfig = {
+export interface GitConfig {
     url: string;
     provider: "github" | "bitbucket" | "gitlab" | "azure" | "unknown";
-};
+    token: string | undefined;
+}
 export type GitConfigs = Record<string, GitConfig>;
 export declare const EXAMPLE_REPOS: string[];
 export declare const STARTER_REPO = "BuilderIO/fusion-starter";
@@ -263,7 +265,7 @@ export interface PartialBranchData {
     isDefault: boolean;
     isPublic: boolean;
     lockedFusionEnvironment?: FusionExecutionEnvironment;
-    metadata?: Record<string, unknown>;
+    metadata?: BranchMetadata;
     backup?: BranchBackup;
     gitAiBranch?: string | null;
     lastCommitHash?: string | null;
@@ -277,6 +279,29 @@ export interface PartialBranchData {
     };
 }
 export type EntityState = "active" | "deleted";
+/**
+ * Metadata stored in branches for integration tracking and PR description generation.
+ * This type documents the integration context that can be attached to a branch.
+ */
+export interface BranchMetadata {
+    /** How the branch was created (e.g., "slack", "jira", "api", "cli") */
+    createdVia?: string;
+    /** JIRA issue key (e.g., "PROJ-123") - used to link back to the JIRA ticket in PR descriptions */
+    jiraIssueKey?: string;
+    /** JIRA cloud ID - UUID identifier for the Atlassian cloud instance */
+    jiraCloudId?: string;
+    /** JIRA site name - the subdomain used in the JIRA URL (e.g., "mycompany" for mycompany.atlassian.net) */
+    jiraSiteName?: string;
+    /** JIRA issue ID - internal JIRA identifier */
+    jiraIssueId?: string;
+    /** Slack team/workspace ID - used to ensure deep links open in the correct workspace for multi-workspace users */
+    slackTeamId?: string;
+    /** Slack channel ID - used to link back to the Slack thread in PR descriptions */
+    slackChannelId?: string;
+    /** Slack thread timestamp - used to construct the Slack thread URL */
+    slackThreadTs?: string;
+    [key: string]: unknown;
+}
 interface BranchSharedData {
     appName?: string | null;
     prNumber?: number | null;
@@ -308,7 +333,7 @@ interface BranchSharedData {
         allocated: boolean | null;
     } | null;
     backup?: BranchBackup;
-    metadata?: Record<string, unknown>;
+    metadata?: BranchMetadata;
     needsCleanup?: boolean;
     /** @deprecated Use `state` field instead. Kept for backwards compatibility. */
     deleted?: boolean;
@@ -521,6 +546,7 @@ export interface OrganizationPrivate {
         ids: number[];
         host: string;
     }[];
+    fallbackTokens?: FallbackTokensPrivate;
     createdAt: number;
     updatedAt: number;
 }