@builder.io/ai-utils 0.27.1 → 0.27.4

package/package.json

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

package/src/claw.d.ts

@@ -0,0 +1,44 @@
+import type { NewBranch, Project, MemorySummary } from "./projects";
+export interface OrgTreeUser {
+    userId: string;
+    name?: string;
+    email?: string;
+    role?: string;
+    jobFunctions?: string;
+    githubUsername?: string;
+    gitlabUsername?: string;
+    bitbucketUsername?: string;
+}
+export interface OrgTreeEnvironmentVariable {
+    key: string;
+    value: string;
+    isSecret: boolean;
+}
+export interface OrgTreeResult {
+    projects: Project[];
+    branches: NewBranch[];
+    users: OrgTreeUser[];
+    memories: MemorySummary[];
+    environmentVariables?: OrgTreeEnvironmentVariable[];
+}
+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;
@@ -180,6 +186,8 @@ export interface RevertToolInput {
 }
 export interface TodoReadToolInput {
 }
+export interface RunningAgentsToolInput {
+}
 export interface TodoWriteToolInput {
     mode: "replace" | "patch";
     todos: {
@@ -200,6 +208,9 @@ export interface GetScreenshotToolInput {
     width?: number;
     height?: number;
 }
+export interface NavigatePreviewToolInput {
+    href: string;
+}
 export interface WebFetchToolInput {
     url: string;
     prompt?: string;
@@ -301,11 +312,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 +343,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 +478,27 @@ export interface SetEnvVariableToolInput {
     placeholder?: boolean;
     explanation?: string;
 }
+export interface SendMessageToolInput {
+    channelId: string;
+    markdown: string;
+    status: "starting" | "question" | "done:success" | "done:error";
+}
+export interface SpawnBranchToolInput {
+    projectId: string;
+    message: string;
+    builderUserId?: string;
+    hidden?: boolean;
+}
+export interface SendMessageToBranchToolInput {
+    projectId: string;
+    branchName: string;
+    message: string;
+    builderUserId?: string;
+}
+export interface ReadBranchToolInput {
+    projectId: string;
+    branchName: string;
+}
 /** Comment for PR review - used by both SubmitPRReview and SubmitRecording */
 export interface PRReviewComment {
     file_path: string;
@@ -521,6 +559,7 @@ export interface CodeGenToolMap {
     ReadRule: GetRuleToolInput;
     GetStyleInspiration: GetStyleInspirationToolInput;
     GetScreenshot: GetScreenshotToolInput;
+    NavigatePreview: NavigatePreviewToolInput;
     MultiEdit: MultiSearchReplaceInput;
     FindMedia: FindMediaToolInput;
     Media: MediaToolInput;
@@ -561,11 +600,17 @@ export interface CodeGenToolMap {
     VerifyValidateCommand: VerifyValidateCommandToolInput;
     VerifyRuntimeDependency: VerifyRuntimeDependencyToolInput;
     SetEnvVariable: SetEnvVariableToolInput;
+    SendMessage: SendMessageToolInput;
+    SpawnBranch: SpawnBranchToolInput;
+    SendMessageToBranch: SendMessageToBranchToolInput;
+    ReadBranch: ReadBranchToolInput;
+    RunningAgents: RunningAgentsToolInput;
 }
 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 +1062,7 @@ export interface CustomInstructionDefinition {
     description: string;
     type: "agent-mode" | "always";
     glob?: string;
+    isSkill?: boolean;
 }
 export interface GenerateCompletionStepSession {
     type: "session";
@@ -1387,7 +1433,7 @@ export interface CheckBackupDataResultStale {
 }
 export interface CheckBackupDataResultInvalid {
     state: "invalid";
-    outcome: "no-backup" | "error" | "not-completed" | "no-session-id" | "no-last-commit-hash" | "no-backup-file" | "empty-full-backup" | "no-vcpCodeGenEvent" | "commits-not-in-repo" | "no-after-commit" | "no-signed-url" | "no-git-branch-name" | "repo-url-mismatch" | "branch-uninitialized" | "unexpected-partial-backup" | "unexpected-full-backup";
+    outcome: "no-backup" | "error" | "not-completed" | "no-session-id" | "no-last-commit-hash" | "no-backup-file" | "empty-full-backup" | "no-vcpCodeGenEvent" | "commits-not-in-repo" | "no-after-commit" | "no-signed-url" | "no-git-branch-name" | "repo-url-mismatch" | "branch-uninitialized" | "unexpected-partial-backup" | "unexpected-full-backup" | "no-backup-keys";
     message: string;
     backup: BranchBackup | undefined;
 }
@@ -1395,6 +1441,13 @@ export type CheckBackupDataResult = CheckBackupDataResultValid | CheckBackupData
 export interface BackupMetadata {
     check: CheckBackupDataResultValid | CheckBackupDataResultStale | CheckBackupDataResultForcedBackup;
     downloadUrl: GitBackupDownloadUrlResult | undefined;
+    downloadUrlError?: string;
+}
+export interface AllBackupsCheckResult {
+    /** true only if ALL folders have valid/stale/forced-backup state */
+    allValid: boolean;
+    /** Per-folder check results keyed by backup key ("code", repoHash, etc.) */
+    results: Record<string, CheckBackupDataResult>;
 }
 export interface WorkspaceFolder {
     enableGit?: boolean;
@@ -1424,8 +1477,10 @@ export interface GitRepoContext {
     path: string;
     /** Feature branch name */
     branchName: string;
-    /** Original repo URL */
+    /** Authenticated repo URL (may contain ephemeral token) */
     repoUrl?: string;
+    /** Clean repo URL without auth tokens, for stable storage and refs */
+    originalRepoUrl?: string;
     /** Repo name (e.g., owner/repo) */
     repoName?: string;
     /**
@@ -1468,6 +1523,7 @@ export interface AccessResult {
     message: string;
 }
 export interface RemoteMachineConfig {
+    environment: "cloud" | "cloud-v2" | "containerized" | "container-less" | "unknown";
     cpus: number;
     memory: number;
     region: string;
@@ -1557,7 +1613,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, GenerateCompletionStep } 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;
@@ -300,6 +302,7 @@ export interface BackupGitRepoResultValid {
     empty: boolean;
     lastCommitHash: string;
     backupRef: string | undefined;
+    backupEntry: GitBackupRecordOptions;
 }
 export interface BackupGitRepoResultInvalid {
     success: false;
@@ -335,7 +338,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;
@@ -395,6 +398,8 @@ export interface BranchMetadata {
     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";
@@ -405,7 +410,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" | "default";
 export interface BranchSharedData {
     appName?: string | null;
     prNumber?: number | null;
@@ -542,6 +553,7 @@ export interface Project {
     repoFullName: string | undefined;
     repoProvider: string;
     repoProtocol: string | undefined;
+    description?: string;
     repoDescription?: string;
     repoPrivate: boolean;
     repoUrl: string | undefined;
@@ -672,6 +684,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.
@@ -735,4 +753,174 @@ 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;
+}
+interface BaseCreateBranchMessage {
+}
+export interface ValidatingProjectMessage extends BaseCreateBranchMessage {
+    type: "validating-project";
+    message: string;
+    projectId: string;
+    projectName?: string;
+    branchName: string;
+}
+export interface CreatingBranchMessage extends BaseCreateBranchMessage {
+    type: "creating-branch";
+    message: string;
+    projectId: string;
+    projectName: string;
+    branchName: string;
+    branchFriendlyName: string | undefined;
+}
+export interface SettingUpContainerMessage extends BaseCreateBranchMessage {
+    type: "setting-up-container";
+    message: string;
+    projectId: string;
+    projectName: string;
+    branchName: string;
+    branchFriendlyName: string | undefined;
+}
+export interface ContainerReadyMessage extends BaseCreateBranchMessage {
+    type: "container-ready";
+    message: string;
+    projectId: string;
+    projectName: string;
+    branchName: string;
+    url: string;
+}
+export interface SendingInitialMessageMessage extends BaseCreateBranchMessage {
+    type: "sending-initial-message";
+    message: string;
+    projectId: string;
+    projectName: string;
+    branchName: string;
+}
+export interface BranchCreatedMessage extends BaseCreateBranchMessage {
+    type: "branch-created";
+    message: string;
+    projectId: string;
+    projectName: string;
+    branchName: string;
+    url: string;
+}
+export interface CreateBranchErrorMessage extends BaseCreateBranchMessage {
+    type: "error";
+    message: string;
+    error: string;
+    projectId: string;
+    projectName?: string;
+    branchName?: string;
+}
+export interface EnsureContainerMessage extends BaseCreateBranchMessage {
+    type: "ensure-container";
+    event: ProjectsChunkMessage;
+}
+export interface AiMessage extends BaseCreateBranchMessage {
+    type: "ai";
+    event: GenerateCompletionStep;
+}
+export type CreateBranchChunkMessage = ValidatingProjectMessage | CreatingBranchMessage | SettingUpContainerMessage | SendingInitialMessageMessage | BranchCreatedMessage | CreateBranchErrorMessage | EnsureContainerMessage | ContainerReadyMessage | AiMessage;
+export interface CreateBranchResponse {
+    success: boolean;
+    branchName?: string;
+    projectId: string;
+    projectName?: string;
+    url?: string;
+    error?: string;
+    messageResponse?: string;
+    sentryId?: string;
+    branchId?: string;
+    sessionId?: string;
+}
+export interface SendMessageOptions {
+    projectId: string;
+    branchName: string;
+    userMessage: GenerateUserMessage;
+    devToolsVersion?: string;
+    featureFlags?: Record<string, boolean>;
+    webhook?: WebhookConfig;
+    fireAndForget?: boolean;
+    canHandleTools?: (keyof CodeGenToolMap)[];
+}
+export interface MemoryData {
+    completionId: string;
+    sessionId: string;
+    id: string;
+    scope: "global" | "user" | "project";
+    memory: string;
+    when: string;
+    commit: string | null;
+    category: string;
+    /** Glob pattern for file-based memory retrieval. Should be specific (e.g., "src/components/Button.tsx") rather than broad (e.g., "*.tsx"). */
+    glob: string | null;
+    importance?: number;
+    glob_auto_include?: boolean;
+    ownerId: string;
+    projectId: string | null;
+    branchName: string | null;
+    repoHash: string | null;
+    userId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    modelOverride: string | null;
+    approved: boolean;
+    needsConsolidation: boolean;
+    embedding: any | null;
+    embeddingModel: string | null;
+    position: string;
+    /** Number of memories merged into this one (default: 1). Acts as importance signal (myelin analogy). */
+    mergeCount: number;
+    /** Array of memory IDs that were archived to create this consolidated memory. Used for audit trail and rollback. */
+    mergedMemoryIds: string[];
+    /** Memory ID that archived this memory. Set when this memory gets consolidated into a new one. */
+    archivedBy: string | undefined;
+    archived: boolean;
+    /** Schema version for consolidation process (for future algorithm changes). */
+    consolidationVersion: number | undefined;
+    /** Timestamp of last consolidation processing */
+    lastConsolidatedAt: number | undefined;
+    reads: number;
+    /** Times memory led to positive outcome (default: 0) */
+    successCount: number;
+    /** Times memory was misleading (default: 0) */
+    failureCount: number;
+    /** Times memory was partially helpful (default: 0) */
+    partialCount: number;
+    /** Total times memory was scored (successCount + failureCount + partialCount) */
+    totalUses: number;
+    /** Timestamp of last scoring */
+    lastScoredAt: number | undefined;
+}
+export declare const MEMORY_PICKED_FIELDS: readonly ["id", "updatedAt", "category", "successCount", "partialCount", "failureCount", "totalUses", "when", "glob", "memory"];
+export declare const MEMORY_SUMMARY_FIELDS: readonly ["id", "category", "projectId", "memory", "when", "glob", "updatedAt"];
+export interface MemorySummary extends Pick<MemoryData, (typeof MEMORY_SUMMARY_FIELDS)[number]> {
+}
+export interface GetProjectMemoriesResult {
+    memories: MemorySummary[];
+}
 export {};

package/src/projects.js

@@ -71,3 +71,24 @@ export const isBranchArchived = (branch) => {
 export const isProjectDeleted = (project) => {
     return getProjectState(project) === "deleted";
 };
+export const MEMORY_PICKED_FIELDS = [
+    "id",
+    "updatedAt",
+    "category",
+    "successCount",
+    "partialCount",
+    "failureCount",
+    "totalUses",
+    "when",
+    "glob",
+    "memory",
+];
+export const MEMORY_SUMMARY_FIELDS = [
+    "id",
+    "category",
+    "projectId",
+    "memory",
+    "when",
+    "glob",
+    "updatedAt",
+];