@builder.io/ai-utils 0.14.4 → 0.15.0

package/package.json

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

package/src/codegen.d.ts

@@ -467,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";

package/src/projects.d.ts

@@ -265,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;
@@ -279,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;
@@ -310,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;