@builder.io/ai-utils 0.75.3 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.75.3",
+  "version": "0.76.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/claw.d.ts

@@ -1,4 +1,16 @@
 import type { NewBranch, Project, MemorySummary } from "./projects";
+import type { UserSource } from "./codegen";
+/**
+ * Derives a human-readable sender name from a resolved UserSource.
+ * Prefers "Name <email>", falling back to name, email, then the platform user id.
+ */
+export declare function formatUserSourceDisplayName(userSource: UserSource): string | undefined;
+/**
+ * Extracts the Builder user id from any UserSource variant. For builder.io
+ * sources the `userId` already is the Builder user id; integration sources
+ * carry it as `builderUserId` (resolved by matching the external user).
+ */
+export declare function getBuilderUserId(userSource: UserSource): string | undefined;
 export interface OrgTreeUser {
     userId: string;
     name?: string;
@@ -21,7 +33,10 @@ export interface OrgTreeMessage {
     channelId?: string;
     direction?: "incoming" | "outgoing";
     senderDisplayName?: string;
-    senderId?: string;
+    /** Platform-native sender id (e.g. Slack/Telegram user id), not the Builder user. */
+    platformSenderId?: string;
+    /** Builder user id of the sender, when known. */
+    userId?: string;
     source?: string;
     channelType?: string;
 }
@@ -54,8 +69,44 @@ export interface ParsedChannelId {
  *   "jira/comment/cloud-id/PROJ-123" → { platform: "jira", type: "comment", ids: ["cloud-id", "PROJ-123"] }
  *   "builder/branch/proj-id/my-branch" → { platform: "builder", type: "branch", ids: ["proj-id", "my-branch"] }
  *   "inbox/user/builder-user-id" → { platform: "inbox", type: "user", ids: ["builder-user-id"] }
+ *   "inbox/user/builder-user-id/thread-id" → { platform: "inbox", type: "user", ids: ["builder-user-id", "thread-id"] }
+ *   "inbox/channel/general" → { platform: "inbox", type: "channel", ids: ["general"] }
+ *   "inbox/channel/general/thread-id" → { platform: "inbox", type: "channel", ids: ["general", "thread-id"] }
  */
 export declare function parseChannelId(channelId: string): ParsedChannelId;
+/**
+ * Platforms the org-agent can send messages to. The `platform` segment of a
+ * channelId (e.g. `slack/thread/...`). This is the single source of truth —
+ * the typed dispatch and message logging derive their unions from here.
+ */
+export declare const KNOWN_PLATFORMS: readonly ["slack", "jira", "telegram", "whatsapp", "builder", "inbox", "internal"];
+export type KnownPlatform = (typeof KNOWN_PLATFORMS)[number];
+export declare function isKnownPlatform(p: string): p is KnownPlatform;
+/**
+ * Valid channel sub-types per platform — the `type` segment of a channelId
+ * (e.g. `slack/thread/...`). Declared `satisfies Record<KnownPlatform, ...>`
+ * so every platform must enumerate its types; the literal values drive the
+ * `ChannelType<P>` unions used by the dispatch handlers.
+ */
+export declare const CHANNEL_TYPES: {
+    readonly slack: readonly ["thread", "channel", "dm"];
+    readonly jira: readonly ["comment"];
+    readonly telegram: readonly ["chat"];
+    readonly whatsapp: readonly ["chat"];
+    readonly builder: readonly ["branch"];
+    readonly inbox: readonly ["user", "channel"];
+    readonly internal: readonly ["support", "feedback"];
+};
+export type ChannelType<P extends KnownPlatform> = (typeof CHANNEL_TYPES)[P][number];
+/** Union of every channel sub-type across all platforms. */
+export type AnyChannelType = ChannelType<KnownPlatform>;
+export declare function isChannelType<P extends KnownPlatform>(platform: P, type: string): type is ChannelType<P>;
+/** Platform recorded on a logged message; "unknown" when the channelId fails to parse. */
+export type ChannelSource = KnownPlatform | "unknown";
+/** Channel sub-type recorded on a logged message; "unknown" when parsing fails. */
+export type LoggedChannelType = AnyChannelType | "unknown";
+/** Delivery status reported alongside an outbound org-agent message. */
+export type SendMessageStatus = "starting" | "question" | "will-follow-up" | "done:success" | "done:error";
 /**
  * Converts a Builder channel_id URI to a clickable URL for the
  * corresponding platform (Slack, Jira, etc.).
@@ -111,8 +162,6 @@ export interface WorkerMessageOptions {
 export declare function formatWorkerReport(opts: WorkerReportOptions): string;
 export declare function formatWorkerMessage(opts: WorkerMessageOptions): string;
 export interface SystemMessageOptions {
-    /** Identifier of the system sender (e.g. "cron:daily_check"). */
-    senderId?: string;
     /** Human-readable display name (e.g. "Cron Job Trigger: daily_check"). */
     senderDisplayName?: string;
     /** Pre-formatted timestamp string. */
@@ -138,6 +187,8 @@ export interface IncomingMessageOptions {
     dmId?: string;
     /** Display name of the sender. */
     sender?: string;
+    /** Resolved Builder user id of the sender, when known. */
+    builderUserId?: string;
     /** Pre-formatted timestamp string. */
     timestamp: string;
     /** The message body. */

package/src/claw.js

@@ -1,4 +1,31 @@
 // ── Org Tree types (shared between service endpoint and CLI) ──
+/**
+ * Derives a human-readable sender name from a resolved UserSource.
+ * Prefers "Name <email>", falling back to name, email, then the platform user id.
+ */
+export function formatUserSourceDisplayName(userSource) {
+    var _a, _b;
+    const name = (_a = userSource.userName) === null || _a === void 0 ? void 0 : _a.trim();
+    const email = "userEmail" in userSource ? (_b = userSource.userEmail) === null || _b === void 0 ? void 0 : _b.trim() : undefined;
+    if (name && email) {
+        return `${name} <${email}>`;
+    }
+    return name || email || userSource.userId || undefined;
+}
+/**
+ * Extracts the Builder user id from any UserSource variant. For builder.io
+ * sources the `userId` already is the Builder user id; integration sources
+ * carry it as `builderUserId` (resolved by matching the external user).
+ */
+export function getBuilderUserId(userSource) {
+    if (userSource.source === "agent") {
+        return undefined;
+    }
+    if (userSource.source === "builder.io") {
+        return userSource.userId;
+    }
+    return userSource.builderUserId;
+}
 /**
  * Parses a URI-style channelId into its components.
  *
@@ -7,6 +34,9 @@
  *   "jira/comment/cloud-id/PROJ-123" → { platform: "jira", type: "comment", ids: ["cloud-id", "PROJ-123"] }
  *   "builder/branch/proj-id/my-branch" → { platform: "builder", type: "branch", ids: ["proj-id", "my-branch"] }
  *   "inbox/user/builder-user-id" → { platform: "inbox", type: "user", ids: ["builder-user-id"] }
+ *   "inbox/user/builder-user-id/thread-id" → { platform: "inbox", type: "user", ids: ["builder-user-id", "thread-id"] }
+ *   "inbox/channel/general" → { platform: "inbox", type: "channel", ids: ["general"] }
+ *   "inbox/channel/general/thread-id" → { platform: "inbox", type: "channel", ids: ["general", "thread-id"] }
  */
 export function parseChannelId(channelId) {
     const parts = channelId.split("/");
@@ -16,6 +46,41 @@ export function parseChannelId(channelId) {
     const [platform, type, ...ids] = parts;
     return { platform, type, ids };
 }
+/**
+ * Platforms the org-agent can send messages to. The `platform` segment of a
+ * channelId (e.g. `slack/thread/...`). This is the single source of truth —
+ * the typed dispatch and message logging derive their unions from here.
+ */
+export const KNOWN_PLATFORMS = [
+    "slack",
+    "jira",
+    "telegram",
+    "whatsapp",
+    "builder",
+    "inbox",
+    "internal",
+];
+export function isKnownPlatform(p) {
+    return KNOWN_PLATFORMS.includes(p);
+}
+/**
+ * Valid channel sub-types per platform — the `type` segment of a channelId
+ * (e.g. `slack/thread/...`). Declared `satisfies Record<KnownPlatform, ...>`
+ * so every platform must enumerate its types; the literal values drive the
+ * `ChannelType<P>` unions used by the dispatch handlers.
+ */
+export const CHANNEL_TYPES = {
+    slack: ["thread", "channel", "dm"],
+    jira: ["comment"],
+    telegram: ["chat"],
+    whatsapp: ["chat"],
+    builder: ["branch"],
+    inbox: ["user", "channel"],
+    internal: ["support", "feedback"],
+};
+export function isChannelType(platform, type) {
+    return CHANNEL_TYPES[platform].includes(type);
+}
 /**
  * Converts a Builder channel_id URI to a clickable URL for the
  * corresponding platform (Slack, Jira, etc.).
@@ -142,9 +207,6 @@ export function formatWorkerMessage(opts) {
  */
 export function formatSystemMessage(opts) {
     let xml = `<system_message>\n`;
-    if (opts.senderId) {
-        xml += `<sender_id>${opts.senderId}</sender_id>\n`;
-    }
     if (opts.senderDisplayName) {
         xml += `<sender>${opts.senderDisplayName}</sender>\n`;
     }
@@ -181,6 +243,9 @@ export function formatIncomingMessage(opts) {
     if (opts.sender) {
         result += `<sender>${opts.sender}</sender>\n`;
     }
+    if (opts.builderUserId) {
+        result += `<builder_user_id>${opts.builderUserId}</builder_user_id>\n`;
+    }
     result += `<timestamp>${opts.timestamp}</timestamp>\n`;
     result += `<content>\n${opts.content.trim()}\n</content>\n`;
     result += `</incoming_message>\n`;

package/src/codegen.d.ts

@@ -3060,6 +3060,8 @@ export interface GenerateCompletionStepDone {
     planPath: string | undefined;
     stopReason: CompletionStopReason;
     hasChanges: boolean;
+    /** True when this turn was a compaction pass run on an internal model. */
+    compact: boolean;
 }
 export interface GenerateCompletionStepFusionConfigPatch {
     type: "fusion-config-patch";
@@ -3738,6 +3740,8 @@ export interface GenerateCodeEventDone {
     autoContinue: boolean;
     model: string;
     promptVersion: string | undefined;
+    /** True when this turn was a compaction pass run on an internal model. */
+    compact: boolean;
 }
 export interface GenerateCodeEventError {
     type: "error";
@@ -4329,7 +4333,6 @@ export interface LaunchServerStatus {
     projectId?: string;
     detectedServerUrl?: string;
     httpClients: number;
-    _attemptDryRunBackupOutcome?: string;
     workingDirectory?: string;
     fusionConfig?: FusionConfig;
     fusionEnvironment: "cloud" | "cloud-v2" | "unknown";
@@ -4374,7 +4377,6 @@ export interface FusionStatus {
     machine: MachineConfig | undefined;
     projectId: string | undefined;
     detectedServerUrl: string | undefined;
-    _attemptDryRunBackupOutcome: string | undefined;
     workingDirectory: string | undefined;
     fusionEnvironment: "cloud" | "cloud-v2" | "unknown";
     containerState: "idle" | "busy";

package/src/codegen.js

@@ -662,7 +662,7 @@ export const RecordFrameToolInputSchema = z
         description: "Optional longer description providing context about what this frame shows.",
     }),
     pr_highlight: z.boolean().optional().meta({
-        description: "Set true to mark this as a 'verified screenshot' worth showing in the PR description — i.e. visual proof of how the fix/feature behaves. Use sparingly (1–3 per session) for the key moments that demonstrate the feature working. The title is used as the caption.",
+        description: "Set true to mark this as a 'verified screenshot' worth showing in the PR description — visual proof of how the fix/feature behaves. The title is the caption; `description` supports bullet points / multiple lines. Only flag a frame when it shows a GENUINELY DISTINCT UI state — never flag multiple shots of the same screen. For a single-screen change: flag exactly ONE frame and list ALL the changes as bullet points in `description`. For a multi-step flow: flag one frame per unique screen (e.g. step 1, 2, 3 — each a different UI). The first flagged frame is shown full-width as the hero, so make it the most representative.",
     }),
 })
     .meta({ title: "RecordFrameToolInput" });

package/src/events.d.ts

@@ -758,7 +758,6 @@ export type ClawMessageSentV1 = FusionEventVariant<"claw.message.sent", {
     branchName: string;
     content: string;
     senderType: "user" | "sub-agent" | "system";
-    senderId?: string;
     correlationId?: string;
     channelId?: string;
     /** Optional clickable URL for channelId. */
@@ -1022,7 +1021,6 @@ export interface SendMessageToOrgAgentInput {
     channelName?: string;
     senderDisplayName?: string;
     messageContext?: string;
-    senderId?: string;
     dmId?: string;
     userSource?: UserSource;
     attachments?: FileUpload[];

package/src/messages.d.ts

@@ -92,6 +92,7 @@ export interface MCPServerURLDefinition {
     create_date?: number | null;
     serverId: string;
     disabled: boolean;
+    clientName?: string;
 }
 export interface MCPServerToolConfiguration {
     allowed_tools?: Array<string> | null;
@@ -116,6 +117,7 @@ export interface MCPServerDoc<TCreateDate = unknown, TLegacyTokenExpiresAt = nev
     createDate: TCreateDate;
     provider?: string;
     disabled?: boolean;
+    clientName: string | undefined;
     tool_configuration?: MCPServerToolConfiguration | null;
     oauthMetadata?: MCPServerOAuthMetadata | null;
     authorizationToken?: string;
@@ -170,6 +172,7 @@ export interface ContentMessageItemToolSearchToolResult {
     };
     cache?: boolean;
 }
+export type ContentMessageItemFromTool = ContentMessageItemText | ContentMessageItemImage | ContentMessageItemResource;
 export type ContentMessageItem = ContentMessageItemText | ContentMessageItemImage | ContentMessageItemResource | ContentMessageItemDocument | ContentMessageItemVideo | ContentMessageItemThinking | ContentMessageItemRedactedThinking | ContentMessageItemToolUse | ContentMessageItemToolResult | ContentMessageItemWebSearchToolResult | ContentMessageItemServerToolUse | ContentMessageItemMCPToolUse | ContentMessageItemMCPToolResult | ContentMessageItemContainerUpload | ContentMessageItemCodeExecutionToolResult | ContentMessageItemToolSearchToolResult;
 export type ContentMessage = ContentMessageItem[];
 export interface SystemMessageParam {

package/src/projects.d.ts

@@ -1605,57 +1605,4 @@ export declare const GetDeploysResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GetDeploysResponse = z.infer<typeof GetDeploysResponseSchema>;
-export declare const UpdateHostingRequestSchema: z.ZodObject<{
-    projectId: z.ZodString;
-    customDomain: z.ZodOptional<z.ZodString>;
-    buildCommand: z.ZodOptional<z.ZodString>;
-    autoDeploy: z.ZodOptional<z.ZodBoolean>;
-    environment: z.ZodOptional<z.ZodObject<{
-        build: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            value: z.ZodString;
-            isSecret: z.ZodBoolean;
-            placeholder: z.ZodOptional<z.ZodBoolean>;
-            explanation: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        prod: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            value: z.ZodString;
-            isSecret: z.ZodBoolean;
-            placeholder: z.ZodOptional<z.ZodBoolean>;
-            explanation: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
-    deleteEnvironmentVariableKeys: z.ZodOptional<z.ZodObject<{
-        build: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        prod: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type UpdateHostingRequest = z.infer<typeof UpdateHostingRequestSchema>;
-export declare const UpdateHostingResponseSchema: z.ZodObject<{
-    slug: z.ZodOptional<z.ZodString>;
-    customDomain: z.ZodOptional<z.ZodString>;
-    buildConfig: z.ZodOptional<z.ZodObject<{
-        buildCommand: z.ZodOptional<z.ZodString>;
-        buildOutputDir: z.ZodOptional<z.ZodString>;
-        nodeVersion: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    environment: z.ZodOptional<z.ZodOptional<z.ZodObject<{
-        build: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            value: z.ZodString;
-            isSecret: z.ZodBoolean;
-            placeholder: z.ZodOptional<z.ZodBoolean>;
-            explanation: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        prod: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            value: z.ZodString;
-            isSecret: z.ZodBoolean;
-            placeholder: z.ZodOptional<z.ZodBoolean>;
-            explanation: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export type UpdateHostingResponse = z.infer<typeof UpdateHostingResponseSchema>;
 export {};

package/src/projects.js

@@ -507,27 +507,3 @@ export const GetDeploysRequestSchema = z.object({
 export const GetDeploysResponseSchema = z.object({
     deploys: z.array(DeployListItemSchema),
 });
-export const UpdateHostingRequestSchema = z.object({
-    projectId: z.string(),
-    customDomain: z.string().optional(),
-    buildCommand: z.string().optional(),
-    autoDeploy: z.boolean().optional(),
-    environment: z
-        .object({
-        build: z.array(EnvironmentVariableSchema).optional(),
-        prod: z.array(EnvironmentVariableSchema).optional(),
-    })
-        .optional(),
-    deleteEnvironmentVariableKeys: z
-        .object({
-        build: z.array(z.string()).optional(),
-        prod: z.array(z.string()).optional(),
-    })
-        .optional(),
-});
-export const UpdateHostingResponseSchema = z.object({
-    slug: z.string().optional(),
-    customDomain: z.string().optional(),
-    buildConfig: ProjectHostingBuildConfigSchema.optional(),
-    environment: ProjectHostingSchema.shape.environment.optional(),
-});