@builder.io/ai-utils 0.27.0 → 0.27.2

package/package.json

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

package/src/claw.d.ts

@@ -0,0 +1,56 @@
+export interface OrgTreeMemorySummary {
+    id: string;
+    category: string;
+    memory: string;
+    when: string;
+    glob: string | null;
+    updatedAt: number;
+}
+export interface OrgBranchCreator {
+    userId: string;
+    userName?: string;
+    userEmail?: string;
+}
+export interface OrgBranch {
+    name: string;
+    friendlyName?: string;
+    projectId: string;
+    lastUpdatedAt: number;
+    state: string;
+    createdBy?: OrgBranchCreator;
+}
+export interface OrgProject {
+    id: string;
+    name: string;
+    repoFullName?: string;
+    repoUrl?: string;
+    pinned?: boolean;
+    archived?: boolean;
+    branchCount: number;
+    memories?: OrgTreeMemorySummary[];
+}
+export interface OrgTreeResult {
+    branches: OrgBranch[];
+    projects: OrgProject[];
+}
+export interface ClawMessageContext {
+    channelId: string;
+    sender: {
+        userId?: string;
+        displayName?: string;
+    };
+    timestamp: number;
+}
+export interface ParsedChannelId {
+    platform: string;
+    type: string;
+    ids: string[];
+}
+/**
+ * Parses a URI-style channelId into its components.
+ *
+ * Examples:
+ *   "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"] }
+ */
+export declare function parseChannelId(channelId: string): ParsedChannelId;

package/src/claw.js

@@ -0,0 +1,16 @@
+// ── Org Tree types (shared between service endpoint and CLI) ──
+/**
+ * Parses a URI-style channelId into its components.
+ *
+ * Examples:
+ *   "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"] }
+ */
+export function parseChannelId(channelId) {
+    const parts = channelId.split("/");
+    if (parts.length < 2) {
+        throw new Error(`Invalid channelId format: ${channelId}`);
+    }
+    const [platform, type, ...ids] = parts;
+    return { platform, type, ids };
+}

package/src/codegen.d.ts

@@ -4,7 +4,7 @@ import type { Options as PrettierOptions } from "prettier";
 import type { UserContext } from "./mapping";
 import type { ForcedBackup, SetupDependency, GitDiagnostics } from "./projects";
 import type { Feature } from "./features";
-import type { CpuKind } from "./projects";
+import type { CpuKind, BranchType } from "./projects";
 export type GitSnapshot = unknown;
 export type ImportType = "named" | "default";
 export interface ESMImport {
@@ -31,6 +31,7 @@ export interface CustomInstruction {
     description?: string;
     allowedTools?: string[];
     hideUI?: boolean;
+    isSkill?: boolean;
 }
 export interface CustomAgentInfo {
     name: string;
@@ -42,11 +43,16 @@ export interface CustomAgentDefinition {
     systemPrompt?: string;
     tools?: string[];
     model?: string;
+    mode?: CodeGenMode;
     position?: string;
     needDevServer?: boolean;
     needValidation?: boolean;
     includeMemories?: boolean;
     resetAfterRun?: boolean;
+    mcpServers?: boolean;
+    asyncSubAgents?: boolean;
+    queueMode?: QueueMode;
+    filePath?: string;
 }
 export type CodeGenFramework = "react" | "html" | "mitosis" | "react-native" | "angular" | "vue" | "svelte" | "qwik" | "solid" | "marko" | "swiftui" | "jetpack-compose" | "flutter";
 export type CodeGenStyleLibrary = "tailwind" | "tailwind-precise" | "emotion" | "styled-components" | "styled-jsx" | "react-native" | undefined;
@@ -200,6 +206,9 @@ export interface GetScreenshotToolInput {
     width?: number;
     height?: number;
 }
+export interface NavigatePreviewToolInput {
+    href: string;
+}
 export interface WebFetchToolInput {
     url: string;
     prompt?: string;
@@ -301,11 +310,14 @@ export interface ExitToolInput {
         question: string;
         context: string;
         header?: string;
+        /** Question type: "select" for single-choice, "multi-select" for multiple choices, "text" for free-form input. Defaults to "select" if options are present, "text" if not. */
+        type?: "select" | "multi-select" | "text";
+        /** Placeholder text for text-type questions (e.g., "Enter your API key", "https://localhost:3000") */
+        placeholder?: string;
         options?: Array<{
             label: string;
             description: string;
         }>;
-        multiSelect?: boolean;
     }>;
     isMonorepo?: boolean;
     isMicrofrontend?: boolean;
@@ -329,11 +341,14 @@ export interface ProposedConfig {
         context: string;
         whatYouTried?: string;
         header?: string;
+        /** Question type: "select" for single-choice, "multi-select" for multiple choices, "text" for free-form input */
+        type?: "select" | "multi-select" | "text";
+        /** Placeholder text for text-type questions */
+        placeholder?: string;
         options?: Array<{
             label: string;
             description: string;
         }>;
-        multiSelect?: boolean;
     }>;
     configuration: {
         setupCommand: {
@@ -461,6 +476,24 @@ export interface SetEnvVariableToolInput {
     placeholder?: boolean;
     explanation?: string;
 }
+export interface SendMessageToolInput {
+    channelId: string;
+    markdown: string;
+    status: "starting" | "question" | "done:success" | "done:error";
+}
+export interface ReadChannelToolInput {
+    channelId: string;
+    limit?: number;
+}
+export interface SpawnBranchToolInput {
+    projectId: string;
+    message: string;
+}
+export interface SendMessageToBranchToolInput {
+    projectId: string;
+    branchName: string;
+    message: string;
+}
 /** Comment for PR review - used by both SubmitPRReview and SubmitRecording */
 export interface PRReviewComment {
     file_path: string;
@@ -521,6 +554,7 @@ export interface CodeGenToolMap {
     ReadRule: GetRuleToolInput;
     GetStyleInspiration: GetStyleInspirationToolInput;
     GetScreenshot: GetScreenshotToolInput;
+    NavigatePreview: NavigatePreviewToolInput;
     MultiEdit: MultiSearchReplaceInput;
     FindMedia: FindMediaToolInput;
     Media: MediaToolInput;
@@ -561,11 +595,16 @@ export interface CodeGenToolMap {
     VerifyValidateCommand: VerifyValidateCommandToolInput;
     VerifyRuntimeDependency: VerifyRuntimeDependencyToolInput;
     SetEnvVariable: SetEnvVariableToolInput;
+    SendMessage: SendMessageToolInput;
+    ReadChannel: ReadChannelToolInput;
+    SpawnBranch: SpawnBranchToolInput;
+    SendMessageToBranch: SendMessageToBranchToolInput;
 }
 export type CodeGenTools = keyof CodeGenToolMap;
 export type AllCodeGenTools = CodeGenTools | "web_search";
 export type SessionMode = "planning" | "normal" | "auto-planning" | "deep-research";
 export type CodeGenMode = "quality" | "quality-v3" | "quality-v4" | "quality-v4-agent";
+export type QueueMode = "next-turn" | "until-idle";
 export type BaseCodeGenPosition = "fusion" | "editor-ai" | "repo-indexing" | "cli" | "create-app-firebase" | "create-app-lovable" | "builder-code-panel" | "dsi-mcp";
 export type CodeGenPosition = BaseCodeGenPosition | `${BaseCodeGenPosition}-agent`;
 export interface RepoIndexingConfig {
@@ -1017,6 +1056,7 @@ export interface CustomInstructionDefinition {
     description: string;
     type: "agent-mode" | "always";
     glob?: string;
+    isSkill?: boolean;
 }
 export interface GenerateCompletionStepSession {
     type: "session";
@@ -1557,7 +1597,7 @@ export interface FusionConfig {
     sessionId?: string;
     browserAutomationInstructions?: string;
     /** Whether this branch is for a code review - affects enabled agents and tools */
-    branchType?: "code-review" | "setup-project";
+    branchType?: BranchType;
     featureBranch?: string;
     aiBranch?: string;
     /** Whether this is a fork PR - affects git operations (read-only, can't push) */

package/src/events.d.ts

@@ -519,7 +519,21 @@ export declare const ForceSetupAgentV1: {
     eventName: "fusion.setup.force";
     version: "1";
 };
-export type FusionEvent = AiTaskCompletedEvent | AiTaskFailedEvent | GitPrCreatedEvent | ClientDevtoolsSessionStartedEvent | FusionProjectCreatedV1 | SetupAgentCompletedV1 | ForceSetupAgentV1;
+export type ClawMessageSentV1 = FusionEventVariant<"claw.message.sent", {
+    branchName: string;
+    messageType: "text" | "task-result" | "cron-trigger";
+    content: string;
+    senderType: "user" | "sub-agent" | "system";
+    senderId?: string;
+    correlationId?: string;
+    channelId?: string;
+    senderDisplayName?: string;
+}, {}, 1>;
+export declare const ClawMessageSentV1: {
+    eventName: "claw.message.sent";
+    version: "1";
+};
+export type FusionEvent = AiTaskCompletedEvent | AiTaskFailedEvent | GitPrCreatedEvent | ClientDevtoolsSessionStartedEvent | FusionProjectCreatedV1 | SetupAgentCompletedV1 | ForceSetupAgentV1 | ClawMessageSentV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -26,3 +26,7 @@ export const ForceSetupAgentV1 = {
     eventName: "fusion.setup.force",
     version: "1",
 };
+export const ClawMessageSentV1 = {
+    eventName: "claw.message.sent",
+    version: "1",
+};

package/src/index.d.ts

@@ -9,5 +9,6 @@ export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
+export * from "./claw.js";
 export * from "./connectivity/types.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -9,5 +9,6 @@ export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
+export * from "./claw.js";
 export * from "./connectivity/types.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/projects.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
-import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode } from "./codegen";
+import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode, GenerateUserMessage, CodeGenToolMap } from "./codegen";
 import type { FallbackTokensPrivate } from "./organization";
 /**
  * Temporary type for date fields during migration.
@@ -275,6 +275,8 @@ export interface RecordScreenshotOptions {
 }
 export type GitBackupRecordBody = GitBackupRecordOptions | {
     backups: GitBackupRecordOptions[];
+    elapsedTime: number;
+    error?: string;
 };
 export interface GitBackupRecordResult {
     success: boolean;
@@ -335,7 +337,7 @@ export interface SetupScriptDependency {
     script: string;
 }
 export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
-export type AgentType = "setup-project" | "project-configuration";
+export type AgentType = "setup-project" | "project-configuration" | "org-agent";
 export interface PartialBranchData {
     name?: string;
     createdBy: string;
@@ -393,6 +395,10 @@ export interface BranchMetadata {
     slackChannelId?: string;
     /** Slack thread timestamp - used to construct the Slack thread URL */
     slackThreadTs?: string;
+    /** User-provided description of what reviewers should focus on */
+    description?: string;
+    /** Whether the branch is a cloned branch */
+    isClonedBranch?: boolean;
     [key: string]: unknown;
 }
 export type PRStatus = "open" | "closed" | "merged" | "draft" | "approved";
@@ -403,7 +409,13 @@ export interface BranchReview {
     createdAt: number;
     updatedAt: number;
 }
-export type BranchType = "code-review" | "setup-project";
+export interface OrgAgentConfig {
+    maxSubAgents: number;
+    syncIntervalMinutes: number;
+    enabledTools: string[];
+    longLived: boolean;
+}
+export type BranchType = "code-review" | "setup-project" | "org-agent" | "org-worker";
 export interface BranchSharedData {
     appName?: string | null;
     prNumber?: number | null;
@@ -670,6 +682,12 @@ export interface Project {
     useBranchesCollection?: boolean;
     /** When true, the project is in code-only mode */
     codeOnlyMode?: boolean;
+    /** When true, this project is an org-level Claw agent */
+    isOrgAgent?: boolean;
+    /** Configuration for the org agent */
+    orgAgentConfig?: OrgAgentConfig;
+    /** When true, the project is hidden from normal project listings */
+    hidden?: boolean;
 }
 /**
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
@@ -733,4 +751,41 @@ export interface BuilderMyContext {
     };
     error?: string;
 }
+export interface WebhookConfig {
+    url: string;
+    secret?: string;
+    timeout?: number;
+}
+export interface CreateBranchOptions {
+    projectId: string;
+    userMessage: GenerateUserMessage;
+    devToolsVersion?: string;
+    webhook?: WebhookConfig;
+    branchFriendlyName?: string;
+    agentType?: AgentType;
+    actor: string;
+    hidden?: boolean;
+    featureFlags?: Record<string, boolean>;
+    checkoutBranch?: string | null;
+    canHandleTools?: (keyof CodeGenToolMap)[];
+    useKube?: boolean;
+    fireAndForget?: boolean;
+    /** PR number for QA bot branches */
+    prNumber?: number;
+    /** Whether this branch is for a fork PR - affects git operations */
+    isFork?: boolean;
+    type?: BranchType;
+    /** Optional suffix to append to generated branch names (e.g., model short name for parallel branches) */
+    branchNameSuffix?: string;
+}
+export interface SendMessageOptions {
+    projectId: string;
+    branchName: string;
+    userMessage: GenerateUserMessage;
+    devToolsVersion?: string;
+    featureFlags?: Record<string, boolean>;
+    webhook?: WebhookConfig;
+    fireAndForget?: boolean;
+    canHandleTools?: (keyof CodeGenToolMap)[];
+}
 export {};