@builder.io/ai-utils 0.73.0 → 0.74.1

package/package.json

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

package/src/builder-config.d.ts

@@ -18,11 +18,36 @@ export declare const BuilderConfigDatabaseSchema: z.ZodObject<{
     schemaDir: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 export type BuilderConfigDatabase = z.infer<typeof BuilderConfigDatabaseSchema>;
+/** `hosting` block in `builder.config.json` — see First Class Hosting spec. */
+export declare const BuilderConfigHostingEnvironmentSchema: z.ZodObject<{
+    build: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    prod: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type BuilderConfigHostingEnvironment = z.infer<typeof BuilderConfigHostingEnvironmentSchema>;
+export declare const BuilderConfigHostingSchema: z.ZodObject<{
+    buildCommand: z.ZodOptional<z.ZodString>;
+    nodeVersion: z.ZodOptional<z.ZodString>;
+    buildOutputDir: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodObject<{
+        build: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        prod: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuilderConfigHosting = z.infer<typeof BuilderConfigHostingSchema>;
 export declare const BuilderConfigSchema: z.ZodObject<{
     database: z.ZodOptional<z.ZodObject<{
         kind: z.ZodLiteral<"postgres">;
         migrations: z.ZodLiteral<"drizzle">;
         schemaDir: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
+    hosting: z.ZodOptional<z.ZodObject<{
+        buildCommand: z.ZodOptional<z.ZodString>;
+        nodeVersion: z.ZodOptional<z.ZodString>;
+        buildOutputDir: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodObject<{
+            build: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            prod: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type BuilderConfig = z.infer<typeof BuilderConfigSchema>;

package/src/builder-config.js

@@ -17,6 +17,18 @@ export const BuilderConfigDatabaseSchema = z.object({
     migrations: z.literal("drizzle"),
     schemaDir: z.string().default("drizzle"),
 });
+/** `hosting` block in `builder.config.json` — see First Class Hosting spec. */
+export const BuilderConfigHostingEnvironmentSchema = z.object({
+    build: z.record(z.string(), z.string()).optional(),
+    prod: z.record(z.string(), z.string()).optional(),
+});
+export const BuilderConfigHostingSchema = z.object({
+    buildCommand: z.string().optional(),
+    nodeVersion: z.string().optional(),
+    buildOutputDir: z.string().optional(),
+    environment: BuilderConfigHostingEnvironmentSchema.optional(),
+});
 export const BuilderConfigSchema = z.object({
     database: BuilderConfigDatabaseSchema.optional(),
+    hosting: BuilderConfigHostingSchema.optional(),
 });

package/src/codegen.d.ts

@@ -28,6 +28,11 @@ export declare const ProjectFileSchema: z.ZodObject<{
     virtual: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ProjectFile = z.infer<typeof ProjectFileSchema>;
+export declare const CustomAgentInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CustomAgentInfo = z.infer<typeof CustomAgentInfoSchema>;
 export declare const CustomInstructionSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -45,11 +50,16 @@ export declare const CustomInstructionSchema: z.ZodObject<{
     disableModelInvocation: z.ZodOptional<z.ZodBoolean>;
     userInvocable: z.ZodOptional<z.ZodBoolean>;
     scope: z.ZodOptional<z.ZodEnum<{
+        builtin: "builtin";
         plugin: "plugin";
         project: "project";
         user: "user";
     }>>;
     pluginName: z.ZodOptional<z.ZodString>;
+    ownedAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type CustomInstruction = z.infer<typeof CustomInstructionSchema>;
 /** Reasoning effort level for LLM completions. */
@@ -64,11 +74,6 @@ export declare const ReasoningEffortSchema: z.ZodEnum<{
     xhigh: "xhigh";
 }>;
 export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
-export declare const CustomAgentInfoSchema: z.ZodObject<{
-    name: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type CustomAgentInfo = z.infer<typeof CustomAgentInfoSchema>;
 /** Per-agent model overrides. String = fixed model, string[] = round-robin. */
 export declare const AgentModelOverridesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export type AgentModelOverrides = z.infer<typeof AgentModelOverridesSchema>;
@@ -1295,6 +1300,28 @@ export declare const SubmitPRReviewToolInputSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type SubmitPRReviewToolInput = z.infer<typeof SubmitPRReviewToolInputSchema>;
+/**
+ * AddComment - a generic, UI-only tool for attaching a typed comment to the
+ * session. It never posts anywhere external; the service only validates the
+ * call and the dev-tools CLI emits a `comment-added` step from the tool input
+ * so the UI can render it. The `type` discriminates how the UI renders the
+ * comment (e.g. `"code-review"`), and `metadata` carries type-specific fields.
+ *
+ * Example (code-review skill):
+ *   addComment({
+ *     type: "code-review",
+ *     content: "Unawaited async call will fail in serverless",
+ *     metadata: { filePath: "src/x.ts", startLine: 264, endLine: 264, severity: "high" }
+ *   })
+ */
+export declare const AddCommentToolInputSchema: z.ZodObject<{
+    type: z.ZodString;
+    content: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strip>;
+export type AddCommentToolInput = Omit<z.infer<typeof AddCommentToolInputSchema>, "metadata"> & {
+    metadata?: AddedCommentMetadata;
+};
 export declare const ResolveQACommentsToolInputSchema: z.ZodObject<{
     thread_node_ids: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -1639,6 +1666,11 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
             looks_good: "looks_good";
         }>>;
     }, z.core.$strip>;
+    AddComment: z.ZodObject<{
+        type: z.ZodString;
+        content: z.ZodString;
+        metadata: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    }, z.core.$strip>;
     ProposeConfig: z.ZodObject<{
         config: z.ZodObject<{
             projectOverview: z.ZodObject<{
@@ -1930,6 +1962,7 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type CodeGenToolMap = z.infer<typeof CodeGenToolMapSchema>;
 export declare const CodeGenToolsSchema: z.ZodEnum<{
+    AddComment: "AddComment";
     AddMemory: "AddMemory";
     Agent: "Agent";
     ArchiveBranch: "ArchiveBranch";
@@ -2424,11 +2457,16 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         disableModelInvocation: z.ZodOptional<z.ZodBoolean>;
         userInvocable: z.ZodOptional<z.ZodBoolean>;
         scope: z.ZodOptional<z.ZodEnum<{
+            builtin: "builtin";
             plugin: "plugin";
             project: "project";
             user: "user";
         }>>;
         pluginName: z.ZodOptional<z.ZodString>;
+        ownedAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     customAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -2649,6 +2687,7 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     recommendedRoot: z.ZodOptional<z.ZodString>;
     enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        AddComment: "AddComment";
         AddMemory: "AddMemory";
         Agent: "Agent";
         ArchiveBranch: "ArchiveBranch";
@@ -3194,6 +3233,37 @@ export interface GenerateCompletionStepGit {
     pendingValidation: boolean;
     unmergedFiles: string[];
 }
+/**
+ * A typed comment added to the session via the generic `AddComment` tool. The
+ * `commentType` mirrors the tool's `type` field (e.g. `"code-review"`) and
+ * drives how the UI renders it; `metadata` carries type-specific fields (for
+ * code review: `filePath`, `startLine`, optional `endLine`, optional
+ * `severity`).
+ */
+export interface AddedCommentOriginalSnippet {
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    lines: string[];
+}
+export interface AddedCommentMetadata extends Record<string, unknown> {
+    originalSnippet?: AddedCommentOriginalSnippet;
+}
+export interface AddedComment {
+    commentType: string;
+    content: string;
+    metadata?: AddedCommentMetadata;
+}
+/**
+ * Emitted when a comment is added via the `AddComment` tool. The UI renders the
+ * comment based on its `commentType`. No external posting happens for this
+ * event — it is UI-only.
+ */
+export interface GenerateCompletionStepCommentAdded {
+    type: "comment-added";
+    id: string;
+    comment: AddedComment;
+}
 export interface GenerateCompletionStepClose {
     type: "close";
 }
@@ -3216,7 +3286,7 @@ export interface CustomInstructionDefinition {
     glob?: string;
     isSkill?: boolean;
     userInvocable?: boolean;
-    scope?: "project" | "user" | "plugin";
+    scope?: "project" | "user" | "plugin" | "builtin";
     pluginName?: string;
 }
 export interface GenerateCompletionStepSession {
@@ -3313,7 +3383,7 @@ export interface GenerateCompletionStepUpdateSetupValue {
     };
     reason: string;
 }
-export type GenerateCompletionStep = GenerateCompletionStepThinking | GenerateCompletionStepStart | GenerateCompletionStepDelta | GenerateCompletionStepUser | GenerateCompletionStepFile | GenerateCompletionStepDiff | GenerateCompletionStepTool | GenerateCompletionStepError | GenerateCompletionStepContinue | GenerateCompletionStepWaitForInput | GenerateCompletionStepAbort | GenerateCompletionStepDone | GenerateCompletionStepUserInput | GenerateCompletionStepText | GenerateCompletionStepRestore | GenerateCompletionStepState | GenerateCompletionStepStdio | GenerateCompletionStepSession | GenerateCompletionStepServerToolResult | GenerateCompletionStepGit | GenerateCompletionStepBuilderAction | GenerateCompletionStepLocalMCPAuthComplete | GenerateCompletionStepToolResult | GenerateCompletionStepFusionConfigPatch | GenerateCompletionStepToolCallRequest | GenerateCodeEventMCPStatus | GenerateCodeEventMCPAuthRequired | GenerateCompletionStepDevServerState | GenerateCompletionStepAgent | GenerateCompletionStepBatch | GenerateCompletionStepTerminals | GenerateCompletionStepMetadata | GenerateCompletionStepMessageQueue | GenerateCompletionStepProposeConfig | GenerateCompletionStepUpdateSetupValue | GenerateCompletionStepIde;
+export type GenerateCompletionStep = GenerateCompletionStepThinking | GenerateCompletionStepStart | GenerateCompletionStepDelta | GenerateCompletionStepUser | GenerateCompletionStepFile | GenerateCompletionStepDiff | GenerateCompletionStepTool | GenerateCompletionStepError | GenerateCompletionStepContinue | GenerateCompletionStepWaitForInput | GenerateCompletionStepAbort | GenerateCompletionStepDone | GenerateCompletionStepUserInput | GenerateCompletionStepText | GenerateCompletionStepRestore | GenerateCompletionStepState | GenerateCompletionStepStdio | GenerateCompletionStepSession | GenerateCompletionStepServerToolResult | GenerateCompletionStepGit | GenerateCompletionStepBuilderAction | GenerateCompletionStepLocalMCPAuthComplete | GenerateCompletionStepToolResult | GenerateCompletionStepFusionConfigPatch | GenerateCompletionStepToolCallRequest | GenerateCodeEventMCPStatus | GenerateCodeEventMCPAuthRequired | GenerateCompletionStepDevServerState | GenerateCompletionStepAgent | GenerateCompletionStepBatch | GenerateCompletionStepTerminals | GenerateCompletionStepMetadata | GenerateCompletionStepMessageQueue | GenerateCompletionStepProposeConfig | GenerateCompletionStepUpdateSetupValue | GenerateCompletionStepCommentAdded | GenerateCompletionStepIde;
 export interface ApplyActionsResult {
     filePath: string;
     addedLines: number;
@@ -4029,6 +4099,8 @@ export interface FusionConfig {
     checkCommand?: string;
     setupCommand?: string;
     validateCommand?: string;
+    /** Production build command for hosting deploy pods (default: npm run build). */
+    buildCommand?: string;
     fusionServerPort?: number;
     autoPush?: AutoPushMode;
     lockFile?: {
@@ -4514,6 +4586,22 @@ export interface ValidateCommandResultFailure {
     code: number | null;
     output: string;
 }
+export type BuildCommandState = ValidateCommandState;
+export type BuildCommandResult = BuildCommandResultSuccess | BuildCommandResultAborted | BuildCommandResultFailure;
+export interface BuildCommandResultSuccess {
+    status: "success";
+    command: string;
+}
+export interface BuildCommandResultAborted {
+    status: "aborted";
+    command: string | undefined;
+}
+export interface BuildCommandResultFailure {
+    status: "failure";
+    command: string;
+    code?: number;
+    output: string;
+}
 export interface ConfigureDevOrchestratorUpdates {
     devCommand: boolean;
     setupCommand: boolean;

package/src/codegen.js

@@ -22,6 +22,12 @@ export const ProjectFileSchema = z
     virtual: z.boolean().optional(),
 })
     .meta({ title: "ProjectFile" });
+export const CustomAgentInfoSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+})
+    .meta({ title: "CustomAgentInfo" });
 export const CustomInstructionSchema = z
     .object({
     id: z.string(),
@@ -38,28 +44,31 @@ export const CustomInstructionSchema = z
     userInvocable: z.boolean().optional(),
     /**
      * Where this instruction was discovered. Drives precedence on name
-     * collision: `project` > `user` > `plugin`. Set by the discovery loader,
-     * not by the parsed file itself.
+     * collision: `project` > `user` > `plugin` > `builtin`. Set by the
+     * discovery loader, not by the parsed file itself. `builtin` marks
+     * product-level skills shipped with dev-tools.
      */
-    scope: z.enum(["project", "user", "plugin"]).optional(),
+    scope: z.enum(["project", "user", "plugin", "builtin"]).optional(),
     /**
      * Name of the plugin that contributed this instruction, if any. Set by
      * the plugin loader (Phase 2); always `undefined` for project-level and
      * user-level standalone files (Phase 1).
      */
     pluginName: z.string().optional(),
+    /**
+     * Subagents owned by this skill (name + description only). When the skill
+     * is invoked, the service registers these into the available agents so the
+     * model can spawn them within the same request's agent loop. The CLI holds
+     * the full agent definitions; only the metadata travels here. Used by
+     * built-in skills (e.g. `code-review`).
+     */
+    ownedAgents: z.array(CustomAgentInfoSchema).optional(),
 })
     .meta({ title: "CustomInstruction" });
 /** Reasoning effort level for LLM completions. */
 export const ReasoningEffortSchema = z
     .enum(["auto", "none", "minimal", "low", "medium", "high", "xhigh", "max"])
     .meta({ title: "ReasoningEffort" });
-export const CustomAgentInfoSchema = z
-    .object({
-    name: z.string(),
-    description: z.string().optional(),
-})
-    .meta({ title: "CustomAgentInfo" });
 /** Per-agent model overrides. String = fixed model, string[] = round-robin. */
 export const AgentModelOverridesSchema = z
     .record(z.string(), z.union([z.string(), z.array(z.string())]))
@@ -1329,6 +1338,36 @@ export const SubmitPRReviewToolInputSchema = z
     verdict: ReviewVerdictSchema.optional(),
 })
     .meta({ title: "SubmitPRReviewToolInput" });
+/**
+ * AddComment - a generic, UI-only tool for attaching a typed comment to the
+ * session. It never posts anywhere external; the service only validates the
+ * call and the dev-tools CLI emits a `comment-added` step from the tool input
+ * so the UI can render it. The `type` discriminates how the UI renders the
+ * comment (e.g. `"code-review"`), and `metadata` carries type-specific fields.
+ *
+ * Example (code-review skill):
+ *   addComment({
+ *     type: "code-review",
+ *     content: "Unawaited async call will fail in serverless",
+ *     metadata: { filePath: "src/x.ts", startLine: 264, endLine: 264, severity: "high" }
+ *   })
+ */
+export const AddCommentToolInputSchema = z
+    .object({
+    type: z.string().min(1).meta({
+        description: "Comment category that drives how the UI renders it, e.g. 'code-review'",
+    }),
+    content: z.string().min(1).meta({
+        description: "The comment body (plain text or markdown)",
+    }),
+    // `looseObject` (not `z.record`) so the JSON schema emits
+    // `additionalProperties` rather than `propertyNames`, which OpenAI's strict
+    // tool-schema mode rejects.
+    metadata: z.looseObject({}).optional().meta({
+        description: "Type-specific fields. For 'code-review': filePath (string), startLine (number), endLine (number, optional), severity ('high' | 'medium' | 'low'), and originalSnippet when available",
+    }),
+})
+    .meta({ title: "AddCommentToolInput" });
 export const ResolveQACommentsToolInputSchema = z
     .object({
     thread_node_ids: z.array(z.string()).meta({
@@ -1488,6 +1527,7 @@ export const CodeGenToolMapSchema = z.object({
     ReadMcpResource: ReadMcpResourceToolInputSchema,
     RecordFrame: RecordFrameToolInputSchema,
     SubmitPRReview: SubmitPRReviewToolInputSchema,
+    AddComment: AddCommentToolInputSchema,
     ProposeConfig: ProposeConfigToolInputSchema,
     UpdateSetupValue: UpdateSetupValueToolInputSchema,
     Exit: ExitToolInputSchema,

package/src/events.d.ts

@@ -1221,7 +1221,41 @@ export declare const ClientDevtoolsToolResultV1: {
     eventName: "client.devtools.tool.result";
     version: "1";
 };
-export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionGitHubExternalPrV1 | BotMentionGitHubInternalPrV1 | BotMentionGitLabPrV1 | BotMentionBitbucketPrV1 | BotMentionAzurePrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1;
+export type ClientDevtoolsBuildCompletedV1 = FusionEventVariant<"client.devtools.build.completed", {
+    deployId: string;
+    projectId: string;
+}, {
+    projectId: string;
+    deployId: string;
+}, 1>;
+export declare const ClientDevtoolsBuildCompletedV1: {
+    eventName: "client.devtools.build.completed";
+    version: "1";
+};
+export type ClientDevtoolsBuildUploadedV1 = FusionEventVariant<"client.devtools.build.uploaded", {
+    deployId: string;
+    projectId: string;
+}, {
+    projectId: string;
+    deployId: string;
+}, 1>;
+export declare const ClientDevtoolsBuildUploadedV1: {
+    eventName: "client.devtools.build.uploaded";
+    version: "1";
+};
+export type ClientDevtoolsBuildFailedV1 = FusionEventVariant<"client.devtools.build.failed", {
+    deployId: string;
+    projectId: string;
+    error: string;
+}, {
+    projectId: string;
+    deployId: string;
+}, 1>;
+export declare const ClientDevtoolsBuildFailedV1: {
+    eventName: "client.devtools.build.failed";
+    version: "1";
+};
+export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | ClientDevtoolsBuildCompletedV1 | ClientDevtoolsBuildUploadedV1 | ClientDevtoolsBuildFailedV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionGitHubExternalPrV1 | BotMentionGitHubInternalPrV1 | BotMentionGitLabPrV1 | BotMentionBitbucketPrV1 | BotMentionAzurePrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -142,3 +142,15 @@ export const ClientDevtoolsToolResultV1 = {
     eventName: "client.devtools.tool.result",
     version: "1",
 };
+export const ClientDevtoolsBuildCompletedV1 = {
+    eventName: "client.devtools.build.completed",
+    version: "1",
+};
+export const ClientDevtoolsBuildUploadedV1 = {
+    eventName: "client.devtools.build.uploaded",
+    version: "1",
+};
+export const ClientDevtoolsBuildFailedV1 = {
+    eventName: "client.devtools.build.failed",
+    version: "1",
+};

package/src/projects.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { BuilderConfigHosting } from "./builder-config.js";
 import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
 import { type EnvironmentVariable, type SetupDependency } from "./common-schemas";
 import type { FileOverride, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode, GenerateUserMessage, CodeGenToolMap, GenerateCompletionStep, ReviewEffort } from "./codegen";
@@ -1294,8 +1295,11 @@ export declare const DeployStatusSchema: z.ZodEnum<{
     uploading: "uploading";
 }>;
 export type DeployStatus = z.infer<typeof DeployStatusSchema>;
+/** Deploy statuses that are terminal — never transitioned out of. */
+export declare const TERMINAL_DEPLOY_STATUSES: Set<"building" | "canceled" | "deploying" | "failed" | "live" | "queued" | "uploading">;
 export declare const ProjectHostingBuildConfigSchema: z.ZodObject<{
     buildCommand: z.ZodOptional<z.ZodString>;
+    buildOutputDir: z.ZodOptional<z.ZodString>;
     nodeVersion: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProjectHostingBuildConfig = z.infer<typeof ProjectHostingBuildConfigSchema>;
@@ -1310,6 +1314,7 @@ export declare const ProjectHostingSchema: z.ZodObject<{
     url: 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.ZodObject<{
@@ -1353,6 +1358,7 @@ export declare const DeploySchema: z.ZodObject<{
     ownerId: z.ZodString;
     checkoutBranch: z.ZodOptional<z.ZodString>;
     deployBranchId: z.ZodOptional<z.ZodString>;
+    deployBranchName: z.ZodOptional<z.ZodString>;
     devBranchId: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
         building: "building";
@@ -1445,4 +1451,142 @@ export declare const DeployArtifactManifestSchema: z.ZodObject<{
     functions: z.ZodRecord<z.ZodString, z.ZodString>;
 }, z.core.$strip>;
 export type DeployArtifactManifest = z.infer<typeof DeployArtifactManifestSchema>;
+/**
+ * Per-deploy overrides passed from ai-services to the deploy pod's build-and-upload endpoint.
+ */
+export declare const BuildConfigOverridesSchema: z.ZodObject<{
+    buildCommand: z.ZodOptional<z.ZodString>;
+    buildOutputDir: z.ZodOptional<z.ZodString>;
+    nodeVersion: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type BuildConfigOverrides = z.infer<typeof BuildConfigOverridesSchema>;
+/** Map a repo `builder.config.json` hosting block to deploy-pod overrides (build scope only). */
+export declare function builderConfigHostingToBuildOverrides(hosting: BuilderConfigHosting | undefined): BuildConfigOverrides;
+/**
+ * Merge repo file config with Firestore/UI overrides. Firestore wins on key conflicts.
+ */
+export declare function mergeBuildConfigOverrides(fromFile: BuildConfigOverrides, fromFirestore: BuildConfigOverrides | undefined): BuildConfigOverrides;
+/** True when merged hosting build config includes at least one build setting. */
+export declare function hasResolvableHostingBuildConfig(overrides?: BuildConfigOverrides): boolean;
+/**
+ * Request body for `POST /_builder.io/api/build-and-upload` on the deploy pod.
+ */
+export declare const BuildAndUploadRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    deployId: z.ZodString;
+    gcsManifestUploadUrl: z.ZodString;
+    gcsArtifactUploadUrl: z.ZodString;
+    buildConfigOverrides: z.ZodOptional<z.ZodObject<{
+        buildCommand: z.ZodOptional<z.ZodString>;
+        buildOutputDir: z.ZodOptional<z.ZodString>;
+        nodeVersion: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuildAndUploadRequest = z.infer<typeof BuildAndUploadRequestSchema>;
+export declare const ReserveSlugRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    slug: z.ZodString;
+}, z.core.$strip>;
+export type ReserveSlugRequest = z.infer<typeof ReserveSlugRequestSchema>;
+export declare const ReserveSlugResponseSchema: z.ZodObject<{
+    slug: z.ZodString;
+}, z.core.$strip>;
+export type ReserveSlugResponse = z.infer<typeof ReserveSlugResponseSchema>;
+export declare const DeployRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    checkoutBranch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DeployRequest = z.infer<typeof DeployRequestSchema>;
+export declare const DeployResponseSchema: z.ZodObject<{
+    deployId: z.ZodString;
+    status: z.ZodEnum<{
+        building: "building";
+        canceled: "canceled";
+        deploying: "deploying";
+        failed: "failed";
+        live: "live";
+        queued: "queued";
+        uploading: "uploading";
+    }>;
+}, z.core.$strip>;
+export type DeployResponse = z.infer<typeof DeployResponseSchema>;
+export declare const GetDeploysRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    deployId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GetDeploysRequest = z.infer<typeof GetDeploysRequestSchema>;
+export declare const GetDeploysResponseSchema: z.ZodObject<{
+    deploys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            building: "building";
+            canceled: "canceled";
+            deploying: "deploying";
+            failed: "failed";
+            live: "live";
+            queued: "queued";
+            uploading: "uploading";
+        }>;
+        url: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodNumber;
+        completedAt: z.ZodOptional<z.ZodNumber>;
+    }, 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

@@ -200,8 +200,15 @@ export const DeployStatusSchema = z.enum([
     "failed",
     "canceled",
 ]);
+/** Deploy statuses that are terminal — never transitioned out of. */
+export const TERMINAL_DEPLOY_STATUSES = new Set([
+    "live",
+    "failed",
+    "canceled",
+]);
 export const ProjectHostingBuildConfigSchema = z.object({
     buildCommand: z.string().optional(),
+    buildOutputDir: z.string().optional(),
     nodeVersion: z.string().optional(),
 });
 /**
@@ -271,6 +278,9 @@ export const DeploySchema = z.object({
     deployBranchId: z.string().optional().meta({
         description: 'Fusion branch id of the ephemeral hidden deploy branch (`type: "deploy"`) that ran the build.',
     }),
+    deployBranchName: z.string().optional().meta({
+        description: 'Fusion branch name of the ephemeral hidden deploy branch (`type: "deploy"`) that ran the build.',
+    }),
     devBranchId: z.string().optional().meta({
         description: "Fusion dev branch's id (unset if we are deploying project default branch)",
     }),
@@ -357,3 +367,153 @@ export const DeployArtifactManifestSchema = z.object({
         description: "serverless function name → sha256 hash",
     }),
 });
+/**
+ * Per-deploy overrides passed from ai-services to the deploy pod's build-and-upload endpoint.
+ */
+export const BuildConfigOverridesSchema = z.object({
+    buildCommand: z.string().optional(),
+    buildOutputDir: z.string().optional(),
+    nodeVersion: z.string().optional(),
+    /**
+     * Flat key-value map for the deploy pod. Firestore/API layers store
+     * `EnvironmentVariable[]`; convert at the boundary before building overrides.
+     */
+    environment: z.record(z.string(), z.string()).optional(),
+});
+function trimOptionalString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+/** Pick a string override: Firestore wins when the key is present (including ""). */
+function pickBuildConfigString(firestore, file) {
+    if (firestore !== undefined) {
+        return trimOptionalString(firestore);
+    }
+    return trimOptionalString(file);
+}
+/** Map a repo `builder.config.json` hosting block to deploy-pod overrides (build scope only). */
+export function builderConfigHostingToBuildOverrides(hosting) {
+    var _a;
+    if (!hosting) {
+        return {};
+    }
+    const buildEnv = (_a = hosting.environment) === null || _a === void 0 ? void 0 : _a.build;
+    const buildCommand = trimOptionalString(hosting.buildCommand);
+    const buildOutputDir = trimOptionalString(hosting.buildOutputDir);
+    const nodeVersion = trimOptionalString(hosting.nodeVersion);
+    return {
+        ...(buildCommand ? { buildCommand } : {}),
+        ...(buildOutputDir ? { buildOutputDir } : {}),
+        ...(nodeVersion ? { nodeVersion } : {}),
+        ...(buildEnv && Object.keys(buildEnv).length > 0
+            ? { environment: buildEnv }
+            : {}),
+    };
+}
+/**
+ * Merge repo file config with Firestore/UI overrides. Firestore wins on key conflicts.
+ */
+export function mergeBuildConfigOverrides(fromFile, fromFirestore) {
+    const firestore = fromFirestore !== null && fromFirestore !== void 0 ? fromFirestore : {};
+    const merged = {};
+    const buildCommand = pickBuildConfigString(firestore.buildCommand, fromFile.buildCommand);
+    if (buildCommand) {
+        merged.buildCommand = buildCommand;
+    }
+    const buildOutputDir = pickBuildConfigString(firestore.buildOutputDir, fromFile.buildOutputDir);
+    if (buildOutputDir) {
+        merged.buildOutputDir = buildOutputDir;
+    }
+    const nodeVersion = pickBuildConfigString(firestore.nodeVersion, fromFile.nodeVersion);
+    if (nodeVersion) {
+        merged.nodeVersion = nodeVersion;
+    }
+    const fileEnv = fromFile.environment;
+    const firestoreEnv = firestore.environment;
+    if (fileEnv !== undefined || firestoreEnv !== undefined) {
+        const environment = { ...fileEnv, ...firestoreEnv };
+        if (Object.keys(environment).length > 0) {
+            merged.environment = environment;
+        }
+    }
+    return merged;
+}
+/** True when merged hosting build config includes at least one build setting. */
+export function hasResolvableHostingBuildConfig(overrides) {
+    var _a, _b, _c;
+    if (!overrides) {
+        return false;
+    }
+    if ((_a = overrides.buildCommand) === null || _a === void 0 ? void 0 : _a.trim()) {
+        return true;
+    }
+    if ((_b = overrides.buildOutputDir) === null || _b === void 0 ? void 0 : _b.trim()) {
+        return true;
+    }
+    if ((_c = overrides.nodeVersion) === null || _c === void 0 ? void 0 : _c.trim()) {
+        return true;
+    }
+    if (overrides.environment && Object.keys(overrides.environment).length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Request body for `POST /_builder.io/api/build-and-upload` on the deploy pod.
+ */
+export const BuildAndUploadRequestSchema = z.object({
+    projectId: z.string(),
+    deployId: z.string(),
+    gcsManifestUploadUrl: z.string().url(),
+    gcsArtifactUploadUrl: z.string().url(),
+    buildConfigOverrides: BuildConfigOverridesSchema.optional(),
+});
+export const ReserveSlugRequestSchema = z.object({
+    projectId: z.string(),
+    slug: z.string(),
+});
+export const ReserveSlugResponseSchema = z.object({
+    slug: z.string(),
+});
+export const DeployRequestSchema = z.object({
+    projectId: z.string(),
+    checkoutBranch: z.string().optional(),
+});
+export const DeployResponseSchema = z.object({
+    deployId: z.string(),
+    status: DeployStatusSchema,
+});
+export const GetDeploysRequestSchema = z.object({
+    projectId: z.string(),
+    deployId: z.string().optional(),
+});
+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(),
+});