@builder.io/ai-utils 0.27.2 → 0.28.0

package/package.json

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

package/src/claw.d.ts

@@ -1,37 +1,25 @@
-export interface OrgTreeMemorySummary {
-    id: string;
-    category: string;
-    memory: string;
-    when: string;
-    glob: string | null;
-    updatedAt: number;
-}
-export interface OrgBranchCreator {
+import type { NewBranch, Project, MemorySummary } from "./projects";
+export interface OrgTreeUser {
     userId: string;
-    userName?: string;
-    userEmail?: string;
-}
-export interface OrgBranch {
-    name: string;
-    friendlyName?: string;
-    projectId: string;
-    lastUpdatedAt: number;
-    state: string;
-    createdBy?: OrgBranchCreator;
+    name?: string;
+    email?: string;
+    role?: string;
+    jobFunctions?: string;
+    githubUsername?: string;
+    gitlabUsername?: string;
+    bitbucketUsername?: string;
 }
-export interface OrgProject {
-    id: string;
-    name: string;
-    repoFullName?: string;
-    repoUrl?: string;
-    pinned?: boolean;
-    archived?: boolean;
-    branchCount: number;
-    memories?: OrgTreeMemorySummary[];
+export interface OrgTreeEnvironmentVariable {
+    key: string;
+    value: string;
+    isSecret: boolean;
 }
 export interface OrgTreeResult {
-    branches: OrgBranch[];
-    projects: OrgProject[];
+    projects: Project[];
+    branches: NewBranch[];
+    users: OrgTreeUser[];
+    memories: MemorySummary[];
+    environmentVariables?: OrgTreeEnvironmentVariable[];
 }
 export interface ClawMessageContext {
     channelId: string;

package/src/codegen.d.ts

@@ -186,6 +186,8 @@ export interface RevertToolInput {
 }
 export interface TodoReadToolInput {
 }
+export interface RunningAgentsToolInput {
+}
 export interface TodoWriteToolInput {
     mode: "replace" | "patch";
     todos: {
@@ -481,18 +483,21 @@ export interface SendMessageToolInput {
     markdown: string;
     status: "starting" | "question" | "done:success" | "done:error";
 }
-export interface ReadChannelToolInput {
-    channelId: string;
-    limit?: number;
-}
 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 {
@@ -596,9 +601,10 @@ export interface CodeGenToolMap {
     VerifyRuntimeDependency: VerifyRuntimeDependencyToolInput;
     SetEnvVariable: SetEnvVariableToolInput;
     SendMessage: SendMessageToolInput;
-    ReadChannel: ReadChannelToolInput;
     SpawnBranch: SpawnBranchToolInput;
     SendMessageToBranch: SendMessageToBranchToolInput;
+    ReadBranch: ReadBranchToolInput;
+    RunningAgents: RunningAgentsToolInput;
 }
 export type CodeGenTools = keyof CodeGenToolMap;
 export type AllCodeGenTools = CodeGenTools | "web_search";
@@ -1427,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;
 }
@@ -1435,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;
@@ -1464,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;
     /**
@@ -1508,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;
@@ -1560,15 +1576,20 @@ export interface EnvironmentVariable {
 }
 export interface FileOverride {
     /**
-     * Absolute path where the file should be written in the container.
-     * Example: "/app/.env", "/etc/config/app.conf"
+     * Path where the file should be written.
+     * Supports absolute paths ("/app/.env"), tilde ("~/.npmrc"), and relative paths ("./config.json").
      */
     path: string;
     /**
-     * Content to write to the file.
-     * Can be plain text or binary content (base64 encoded if needed).
+     * Plain text content to write to the file.
+     * Mutually exclusive with `base64`.
      */
-    content: string;
+    content?: string;
+    /**
+     * Base64-encoded binary content to write to the file.
+     * Mutually exclusive with `content`.
+     */
+    base64?: string;
 }
 export interface MCPServerDefinition {
     command: string;
@@ -2050,6 +2071,7 @@ export interface ConfigureDevOrchestratorUpdates {
     validateCommand: boolean;
     hosts: boolean;
     env: boolean;
+    fileOverrides: boolean;
     setupResult: SetupCommandResult | undefined;
     devResult: DevCommandResult | undefined;
     validateResult: ValidateCommandResult | undefined;
@@ -2067,6 +2089,7 @@ export interface ConfigureDevOrchestratorOpts {
     forceDevCommand?: boolean;
     autoDetectDevServer?: boolean;
     autoDetectDevServerPatterns?: string[];
+    fileOverrides?: FileOverride[];
 }
 export interface LanguageInfo {
     color: string;

package/src/events.d.ts

@@ -528,6 +528,8 @@ export type ClawMessageSentV1 = FusionEventVariant<"claw.message.sent", {
     correlationId?: string;
     channelId?: string;
     senderDisplayName?: string;
+    /** Optional context to include alongside the message (e.g. Slack thread history). */
+    messageContext?: string;
 }, {}, 1>;
 export declare const ClawMessageSentV1: {
     eventName: "claw.message.sent";

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, GenerateUserMessage, CodeGenToolMap } 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.
@@ -302,6 +302,7 @@ export interface BackupGitRepoResultValid {
     empty: boolean;
     lastCommitHash: string;
     backupRef: string | undefined;
+    backupEntry: GitBackupRecordOptions;
 }
 export interface BackupGitRepoResultInvalid {
     success: false;
@@ -415,7 +416,7 @@ export interface OrgAgentConfig {
     enabledTools: string[];
     longLived: boolean;
 }
-export type BranchType = "code-review" | "setup-project" | "org-agent" | "org-worker";
+export type BranchType = "code-review" | "setup-project" | "org-agent" | "default";
 export interface BranchSharedData {
     appName?: string | null;
     prNumber?: number | null;
@@ -552,6 +553,7 @@ export interface Project {
     repoFullName: string | undefined;
     repoProvider: string;
     repoProtocol: string | undefined;
+    description?: string;
     repoDescription?: string;
     repoPrivate: boolean;
     repoUrl: string | undefined;
@@ -778,6 +780,83 @@ export interface CreateBranchOptions {
     /** 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;
@@ -788,4 +867,60 @@ export interface SendMessageOptions {
     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",
+];