@builder.io/ai-utils 0.109.1 → 0.111.0

package/package.json

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

package/src/codegen.d.ts

@@ -61,6 +61,7 @@ export declare const CustomInstructionSchema: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    contentOnClient: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type CustomInstruction = z.infer<typeof CustomInstructionSchema>;
 /** Reasoning effort level for LLM completions. */
@@ -2723,6 +2724,7 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
             name: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        contentOnClient: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     customAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -4099,6 +4101,10 @@ export interface CodegenFeedback {
     id: string;
     feedbackText?: string;
     feedbackSentiment?: string;
+    /** 1–5 star rating. Only the first-generation feedback card sends it. */
+    feedbackRating?: number;
+    /** Set by UIs whose feedback needs handling beyond storage. */
+    feedbackSource?: "first-generation-card";
     framework?: string;
     acceptedLines?: number;
     beforeCommit?: GitSnapshot;
@@ -4424,6 +4430,8 @@ export interface WorkspaceFolder {
      * Optional, so older CLIs/configs that ignore it stay compatible.
      */
     templateRepoUrl?: string;
+    /** Local-cluster testing only: branch or tag of `templateRepoUrl` to clone. Absent means its default branch. */
+    templateRef?: string;
     repoName?: string;
     resetGit?: boolean;
     /**

package/src/codegen.js

@@ -63,6 +63,12 @@ export const CustomInstructionSchema = z
      * built-in skills (e.g. `code-review`).
      */
     ownedAgents: z.array(CustomAgentInfoSchema).optional(),
+    /**
+     * The CLI kept this skill's body locally and sent `content` empty, so the
+     * service forwards `Skill` calls for it to the CLI instead of answering
+     * them. Clients that predate this flag send the full body.
+     */
+    contentOnClient: z.boolean().optional(),
 })
     .meta({ title: "CustomInstruction" });
 /** Reasoning effort level for LLM completions. */
@@ -1257,10 +1263,10 @@ export const VerifySetupCommandToolInputSchema = z
     dependencies: z
         .array(z.object({
         tool: z.string().meta({
-            description: "The tool/binary to verify (e.g., 'node', 'npm', 'git')",
+            description: "The tool to install with mise (e.g., 'node', 'pnpm', 'python')",
         }),
         version: z.string().optional().meta({
-            description: "Optional version requirement (e.g., '>=18.0.0', '20.x')",
+            description: "Optional mise version: an exact version ('22.11.0'), a prefix ('22', '3.11'), 'latest' or 'lts'. Not a semver range: convert package.json engines like '22.x' or '>=20' to '22' / '20'.",
         }),
     }))
         .optional(),

package/src/projects.d.ts

@@ -1331,6 +1331,7 @@ export declare const ProjectSettingsSchema: z.ZodObject<{
             name: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        contentOnClient: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     customAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -1673,6 +1674,7 @@ export declare const ProjectSettingsExternalSchema: z.ZodObject<{
             name: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        contentOnClient: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     customAgents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -1963,6 +1965,8 @@ export interface Project {
     templateId?: string | null;
     /** @internal Read-only source repo cloned to bootstrap the project. Immutable. Absent for non-template projects. Distinct from `repoUrl`, which is always the real push remote. */
     templateRepoUrl?: string;
+    /** @internal Local-cluster testing only: the branch or tag of `templateRepoUrl` to clone instead of its default branch. Ignored once the real remote is seeded. */
+    templateRef?: string;
     /** Local filesystem path for desktop-app projects. */
     localPath?: string | null;
     /** The state of the project. Use `isProjectDeleted()` helper for backwards-compatible checks. */
@@ -2252,6 +2256,8 @@ export interface CreateProjectOptions {
     useInternalHost?: boolean;
     /** @internal Read-only source repo cloned to bootstrap the project. Carried through to Firestore. */
     templateRepoUrl?: string;
+    /** @internal Local-cluster testing only: branch or tag of `templateRepoUrl` to clone. Carried through to Firestore. */
+    templateRef?: string;
     /** @internal First-class hosting config copied from the template. Carried through to Firestore. */
     hosting?: ProjectHosting;
     /** @internal When true, provision the internalHost repo eagerly at creation. Hardcoded true for v0. */
@@ -2275,6 +2281,11 @@ export declare const GetProjectsQuerySchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 export type GetProjectsQuery = z.infer<typeof GetProjectsQuerySchema>;
+/**
+ * A plain branch or tag name. It becomes an argument to `git clone -b`, so
+ * anything that could be read as an option or a path escape is rejected.
+ */
+export declare const TemplateRefSchema: z.ZodString;
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -2290,6 +2301,7 @@ export declare const CreateProjectRequestSchema: z.ZodObject<{
     name: z.ZodString;
     initialMessage: z.ZodOptional<z.ZodString>;
     designSystems: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    templateRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CreateProjectRequest = z.infer<typeof CreateProjectRequestSchema>;
 export interface BuilderMyContext {
@@ -2902,6 +2914,7 @@ export declare const UpdateProjectOptionsSchema: z.ZodObject<{
                 name: z.ZodString;
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
+            contentOnClient: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
         customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -4064,6 +4077,397 @@ export declare const EnsureFusionConfigParamsSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type EnsureFusionConfigParams = z.infer<typeof EnsureFusionConfigParamsSchema>;
+/** Request body for `POST /projects/pr-message`. */
+export declare const PRMessageRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    prNumber: z.ZodNumber;
+    message: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        user: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodEnum<{
+                azure: "azure";
+                bitbucket: "bitbucket";
+                github: "github";
+                gitlab: "gitlab";
+                jira: "jira";
+                linear: "linear";
+                slack: "slack";
+                teams: "teams";
+                telegram: "telegram";
+                whatsapp: "whatsapp";
+            }>;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+            photoURL: z.ZodOptional<z.ZodString>;
+            builderUserId: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodLiteral<"builder.io">;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+            photoURL: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodLiteral<"agent">;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "source">>;
+        uiContextPrompt: z.ZodOptional<z.ZodString>;
+        ephemeralUserPrompt: z.ZodOptional<z.ZodString>;
+        displayPrompt: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        systemReminders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            tag: z.ZodOptional<z.ZodString>;
+            ephemeral: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        includeBaseFiles: z.ZodOptional<z.ZodBoolean>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"upload">;
+            contentType: z.ZodEnum<{
+                "application/json": "application/json";
+                "application/pdf": "application/pdf";
+                "image/gif": "image/gif";
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+                "image/webp": "image/webp";
+                "text/plain": "text/plain";
+            }>;
+            name: z.ZodString;
+            dataUrl: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            size: z.ZodNumber;
+            id: z.ZodString;
+            originalUrl: z.ZodOptional<z.ZodString>;
+            ephemeral: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"template">;
+            name: z.ZodString;
+            id: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"url">;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"builder">;
+            html: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"figma">;
+            html: z.ZodString;
+        }, z.core.$strip>], "type">>>;
+        logsCheckpoint: z.ZodOptional<z.ZodBoolean>;
+        dropAbortedPrompt: z.ZodOptional<z.ZodBoolean>;
+        runValidateCommand: z.ZodOptional<z.ZodBoolean>;
+        modelOverride: z.ZodOptional<z.ZodString>;
+        agentModelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+        softContextWindow: z.ZodOptional<z.ZodNumber>;
+        maxCompletions: z.ZodOptional<z.ZodNumber>;
+        isManualContinue: z.ZodOptional<z.ZodBoolean>;
+        includeRelevantMemories: z.ZodOptional<z.ZodBoolean>;
+        category: z.ZodOptional<z.ZodUnion<readonly [z.ZodTemplateLiteral<`repair-${string}`>, z.ZodLiteral<"user-normal">, z.ZodLiteral<"user-figma">, z.ZodLiteral<"user-pdf">, z.ZodLiteral<"user-image">, z.ZodLiteral<"setup-agent">, z.ZodTemplateLiteral<`background-${string}`>, z.ZodTemplateLiteral<`indexing-${string}`>]>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        autoPush: z.ZodOptional<z.ZodEnum<{
+            "ff-push": "ff-push";
+            "force-push": "force-push";
+            "merge-push": "merge-push";
+            none: "none";
+            "safe-push": "safe-push";
+        }>>;
+        syncChanges: z.ZodOptional<z.ZodObject<{
+            remoteBranches: z.ZodOptional<z.ZodEnum<{
+                ai: "ai";
+                both: "both";
+                main: "main";
+            }>>;
+            fastForward: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                never: "never";
+                required: "required";
+            }>>;
+            canPush: z.ZodOptional<z.ZodBoolean>;
+            uncommittedChanges: z.ZodOptional<z.ZodEnum<{
+                commit: "commit";
+                fail: "fail";
+                stash: "stash";
+            }>>;
+            requestRefresh: z.ZodOptional<z.ZodBoolean>;
+            allowUnrelatedHistory: z.ZodOptional<z.ZodBoolean>;
+            resetToBase: z.ZodOptional<z.ZodBoolean>;
+            updateLastCommits: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        enabledMCPs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        skippedMCPs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sessionMode: z.ZodOptional<z.ZodEnum<{
+            "auto-planning": "auto-planning";
+            "deep-research": "deep-research";
+            normal: "normal";
+            planning: "planning";
+        }>>;
+        queue: z.ZodOptional<z.ZodBoolean>;
+        enableQAReviewTool: z.ZodOptional<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            none: "none";
+            xhigh: "xhigh";
+        }>>;
+        repair: z.ZodOptional<z.ZodBoolean>;
+        forceCompact: z.ZodOptional<z.ZodBoolean>;
+        userPrompt: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PRMessageRequest = z.infer<typeof PRMessageRequestSchema>;
+/** Max length of `userMessage.userPrompt` on `POST /agents/run`. */
+export declare const AGENTS_RUN_MAX_USER_PROMPT_LENGTH = 300000;
+/** Request body for `POST /agents/run` (public Background Agents API). */
+export declare const AgentsRunRequestSchema: z.ZodObject<{
+    userMessage: z.ZodObject<{
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        user: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodEnum<{
+                azure: "azure";
+                bitbucket: "bitbucket";
+                github: "github";
+                gitlab: "gitlab";
+                jira: "jira";
+                linear: "linear";
+                slack: "slack";
+                teams: "teams";
+                telegram: "telegram";
+                whatsapp: "whatsapp";
+            }>;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+            photoURL: z.ZodOptional<z.ZodString>;
+            builderUserId: z.ZodOptional<z.ZodString>;
+            link: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodLiteral<"builder.io">;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+            photoURL: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            role: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+            }>;
+            principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            jobs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            permissions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                createBranches: "createBranches";
+                editCode: "editCode";
+                modifyMcpServers: "modifyMcpServers";
+                modifyProjectSettings: "modifyProjectSettings";
+                sendPullRequests: "sendPullRequests";
+                view: "view";
+            }>>>;
+            channelId: z.ZodOptional<z.ZodString>;
+            source: z.ZodLiteral<"agent">;
+            userId: z.ZodOptional<z.ZodString>;
+            userName: z.ZodOptional<z.ZodString>;
+            userEmail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "source">>;
+        uiContextPrompt: z.ZodOptional<z.ZodString>;
+        ephemeralUserPrompt: z.ZodOptional<z.ZodString>;
+        displayPrompt: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        systemReminders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            tag: z.ZodOptional<z.ZodString>;
+            ephemeral: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        includeBaseFiles: z.ZodOptional<z.ZodBoolean>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"upload">;
+            contentType: z.ZodEnum<{
+                "application/json": "application/json";
+                "application/pdf": "application/pdf";
+                "image/gif": "image/gif";
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+                "image/webp": "image/webp";
+                "text/plain": "text/plain";
+            }>;
+            name: z.ZodString;
+            dataUrl: z.ZodString;
+            text: z.ZodOptional<z.ZodString>;
+            size: z.ZodNumber;
+            id: z.ZodString;
+            originalUrl: z.ZodOptional<z.ZodString>;
+            ephemeral: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"template">;
+            name: z.ZodString;
+            id: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"url">;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"builder">;
+            html: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"figma">;
+            html: z.ZodString;
+        }, z.core.$strip>], "type">>>;
+        logsCheckpoint: z.ZodOptional<z.ZodBoolean>;
+        dropAbortedPrompt: z.ZodOptional<z.ZodBoolean>;
+        runValidateCommand: z.ZodOptional<z.ZodBoolean>;
+        modelOverride: z.ZodOptional<z.ZodString>;
+        agentModelOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+        softContextWindow: z.ZodOptional<z.ZodNumber>;
+        maxCompletions: z.ZodOptional<z.ZodNumber>;
+        isManualContinue: z.ZodOptional<z.ZodBoolean>;
+        includeRelevantMemories: z.ZodOptional<z.ZodBoolean>;
+        category: z.ZodOptional<z.ZodUnion<readonly [z.ZodTemplateLiteral<`repair-${string}`>, z.ZodLiteral<"user-normal">, z.ZodLiteral<"user-figma">, z.ZodLiteral<"user-pdf">, z.ZodLiteral<"user-image">, z.ZodLiteral<"setup-agent">, z.ZodTemplateLiteral<`background-${string}`>, z.ZodTemplateLiteral<`indexing-${string}`>]>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        autoPush: z.ZodOptional<z.ZodEnum<{
+            "ff-push": "ff-push";
+            "force-push": "force-push";
+            "merge-push": "merge-push";
+            none: "none";
+            "safe-push": "safe-push";
+        }>>;
+        syncChanges: z.ZodOptional<z.ZodObject<{
+            remoteBranches: z.ZodOptional<z.ZodEnum<{
+                ai: "ai";
+                both: "both";
+                main: "main";
+            }>>;
+            fastForward: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                never: "never";
+                required: "required";
+            }>>;
+            canPush: z.ZodOptional<z.ZodBoolean>;
+            uncommittedChanges: z.ZodOptional<z.ZodEnum<{
+                commit: "commit";
+                fail: "fail";
+                stash: "stash";
+            }>>;
+            requestRefresh: z.ZodOptional<z.ZodBoolean>;
+            allowUnrelatedHistory: z.ZodOptional<z.ZodBoolean>;
+            resetToBase: z.ZodOptional<z.ZodBoolean>;
+            updateLastCommits: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        enabledMCPs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        skippedMCPs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sessionMode: z.ZodOptional<z.ZodEnum<{
+            "auto-planning": "auto-planning";
+            "deep-research": "deep-research";
+            normal: "normal";
+            planning: "planning";
+        }>>;
+        queue: z.ZodOptional<z.ZodBoolean>;
+        enableQAReviewTool: z.ZodOptional<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            none: "none";
+            xhigh: "xhigh";
+        }>>;
+        repair: z.ZodOptional<z.ZodBoolean>;
+        forceCompact: z.ZodOptional<z.ZodBoolean>;
+        userPrompt: z.ZodString;
+    }, z.core.$strip>;
+    userId: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>>;
+    userEmail: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>>;
+    branchName: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>>;
+    projectId: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>>;
+    context: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, z.ZodTransform<Record<string, unknown> | undefined, Record<string, unknown> | null | undefined>>>;
+}, z.core.$strip>;
+export type AgentsRunRequest = z.infer<typeof AgentsRunRequestSchema>;
+/** Request body for `PUT /agents/webhook-secret`. */
+export declare const UpdateWebhookSecretRequestSchema: z.ZodObject<{
+    webhookId: z.ZodString;
+    secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateWebhookSecretRequest = z.infer<typeof UpdateWebhookSecretRequestSchema>;
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as
@@ -4248,6 +4652,7 @@ export declare const ProjectTemplateSchema: z.ZodObject<{
                 name: z.ZodString;
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
+            contentOnClient: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
         customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -4678,6 +5083,7 @@ export declare const ProjectTemplateOverridesSchema: z.ZodObject<{
                 name: z.ZodString;
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
+            contentOnClient: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>>;
         customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -5072,6 +5478,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                     name: z.ZodString;
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                contentOnClient: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>>;
             customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -5449,6 +5856,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                     name: z.ZodString;
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                contentOnClient: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>>;
             customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -5795,6 +6203,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                     name: string;
                     description?: string | undefined;
                 }[] | undefined;
+                contentOnClient?: boolean | undefined;
             }[] | undefined;
             customAgents?: {
                 name: string;
@@ -6064,6 +6473,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                     name: string;
                     description?: string | undefined;
                 }[] | undefined;
+                contentOnClient?: boolean | undefined;
             }[] | undefined;
             customAgents?: {
                 name: string;
@@ -6327,6 +6737,7 @@ export declare const CreateProjectTemplateFromProjectOptionsSchema: z.ZodPipe<z.
                     name: string;
                     description?: string | undefined;
                 }[] | undefined;
+                contentOnClient?: boolean | undefined;
             }[] | undefined;
             customAgents?: {
                 name: string;
@@ -6674,6 +7085,7 @@ export declare const ListProjectTemplatesResponseSchema: z.ZodObject<{
                     name: z.ZodString;
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                contentOnClient: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>>;
             customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -7099,6 +7511,7 @@ export declare const UpdateProjectTemplateOptionsSchema: z.ZodObject<{
                     name: z.ZodString;
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                contentOnClient: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>>;
             customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
@@ -7508,6 +7921,7 @@ export declare const UpdateProjectTemplateResponseSchema: z.ZodObject<{
                     name: z.ZodString;
                     description: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
+                contentOnClient: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>>;
             customAgents: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
                 name: z.ZodString;

package/src/projects.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { EnvironmentVariableSchema, SetupDependencySchema, } from "./common-schemas";
-import { AutoPushModeSchema, CustomInstructionSchema, CustomAgentDefinitionSchema, ExitStateSchema, FileOverrideSchema, } from "./codegen";
+import { AutoPushModeSchema, CustomInstructionSchema, CustomAgentDefinitionSchema, ExitStateSchema, FileOverrideSchema, GenerateUserMessageSchema, } from "./codegen";
 /**
  * Detect git provider from a repository URL (HTTPS or SSH).
  * Used by both error diagnostics and connectivity checks for consistent provider labeling.
@@ -1107,6 +1107,20 @@ export const GetProjectsQuerySchema = z.object({
     /** At most this many projects, counted after access, hidden and DSI filtering. */
     limit: z.coerce.number().int().min(1).max(1000).optional(),
 });
+/**
+ * A plain branch or tag name. It becomes an argument to `git clone -b`, so
+ * anything that could be read as an option or a path escape is rejected.
+ */
+export const TemplateRefSchema = z
+    .string()
+    .max(255)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/)
+    .refine((ref) => !ref.includes(".."), {
+    message: "templateRef must not contain '..'",
+})
+    .meta({
+    description: "Local-cluster testing only: branch or tag of the template repo to clone. Rejected unless the service runs against a local cluster.",
+});
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -1118,6 +1132,8 @@ export const CreateProjectRequestSchema = z.object({
     initialMessage: z.string().optional(),
     /** Design system ids to seed into project settings at creation. */
     designSystems: z.array(z.string()).optional(),
+    /** Local-cluster testing only: branch or tag of the template repo to clone. Template source only. */
+    templateRef: TemplateRefSchema.optional(),
 });
 export function resolveBranchIsPublic(isPublic, defaultBranchType) {
     if (isPublic !== undefined)
@@ -2343,6 +2359,49 @@ export const EnsureFusionConfigParamsSchema = z.object({
         description: "Fusion environment type override. When not provided, the environment is resolved from branch/project settings.",
     }),
 });
+// `agentType` swaps the agent config (tools, model, system prompt) for a
+// message. HTTP callers have no need to pick an agent, so strip it.
+const HttpUserMessageSchema = GenerateUserMessageSchema.omit({
+    agentType: true,
+});
+/** Request body for `POST /projects/pr-message`. */
+export const PRMessageRequestSchema = z.object({
+    projectId: z.string().min(1).meta({ description: "Builder project ID" }),
+    prNumber: z.number().int().positive().meta({ description: "PR number" }),
+    message: HttpUserMessageSchema.extend({ userPrompt: z.string().min(1) })
+        .nullish()
+        .meta({
+        description: "The user message to send to the agent (prompt, attachments, etc.). If omitted or null, the request resolves the PR branch and returns without starting a container or notifying the agent.",
+    }),
+});
+/** Max length of `userMessage.userPrompt` on `POST /agents/run`. */
+export const AGENTS_RUN_MAX_USER_PROMPT_LENGTH = 300000;
+// Public API clients often send `null` for unset fields, which /agents/run has
+// always treated as absent. Accept it and normalize to `undefined`.
+const nullishToUndefined = (schema) => schema
+    .nullish()
+    .transform((v) => v !== null && v !== void 0 ? v : undefined)
+    .optional();
+/** Request body for `POST /agents/run` (public Background Agents API). */
+export const AgentsRunRequestSchema = z.object({
+    userMessage: HttpUserMessageSchema.extend({
+        userPrompt: z.string().min(1).max(AGENTS_RUN_MAX_USER_PROMPT_LENGTH),
+    }),
+    userId: nullishToUndefined(z.string()),
+    userEmail: nullishToUndefined(z.string()),
+    branchName: nullishToUndefined(z.string()),
+    projectId: nullishToUndefined(z.string()),
+    context: nullishToUndefined(z.record(z.string(), z.unknown())).meta({
+        description: "Arbitrary key-value context passed to webhook payloads.",
+    }),
+});
+/** Request body for `PUT /agents/webhook-secret`. */
+export const UpdateWebhookSecretRequestSchema = z.object({
+    webhookId: z.string().min(1),
+    secret: z.string().optional().meta({
+        description: "An empty or omitted secret removes it.",
+    }),
+});
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as

package/src/projects.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { DeleteBranchOptionsSchema, EnsureFusionConfigParamsSchema, } from "./projects.js";
+import { AGENTS_RUN_MAX_USER_PROMPT_LENGTH, AgentsRunRequestSchema, DeleteBranchOptionsSchema, EnsureFusionConfigParamsSchema, PRMessageRequestSchema, UpdateWebhookSecretRequestSchema, } from "./projects.js";
 describe("DeleteBranchOptionsSchema", () => {
     const ids = { projectId: "p1", branchName: "main" };
     it("defaults hard to false", () => {
@@ -38,3 +38,92 @@ describe("EnsureFusionConfigParamsSchema", () => {
         }).success).toBe(false);
     });
 });
+describe("PRMessageRequestSchema", () => {
+    const ids = { projectId: "p1", prNumber: 42 };
+    it("accepts an omitted or null message", () => {
+        expect(PRMessageRequestSchema.safeParse(ids).success).toBe(true);
+        expect(PRMessageRequestSchema.safeParse({ ...ids, message: null }).success).toBe(true);
+    });
+    it("requires a non-empty userPrompt when a message is given", () => {
+        expect(PRMessageRequestSchema.safeParse({ ...ids, message: { userPrompt: "" } })
+            .success).toBe(false);
+        expect(PRMessageRequestSchema.safeParse({ ...ids, message: {} }).success).toBe(false);
+    });
+    it("requires a positive integer prNumber", () => {
+        for (const prNumber of [0, -1, 1.5, "42"]) {
+            expect(PRMessageRequestSchema.safeParse({ ...ids, prNumber }).success).toBe(false);
+        }
+    });
+    it("strips message keys GenerateUserMessage doesn't declare", () => {
+        const parsed = PRMessageRequestSchema.parse({
+            ...ids,
+            message: { userPrompt: "fix it", vcpImportId: "v1" },
+        });
+        expect(parsed.message).toEqual({ userPrompt: "fix it" });
+    });
+    it("strips agentType from the message", () => {
+        const parsed = PRMessageRequestSchema.parse({
+            ...ids,
+            message: { userPrompt: "fix it", agentType: "project-configuration" },
+        });
+        expect(parsed.message).toEqual({ userPrompt: "fix it" });
+    });
+});
+describe("AgentsRunRequestSchema", () => {
+    it("requires a non-empty userPrompt", () => {
+        expect(AgentsRunRequestSchema.safeParse({}).success).toBe(false);
+        expect(AgentsRunRequestSchema.safeParse({ userMessage: { userPrompt: "" } })
+            .success).toBe(false);
+    });
+    it("caps userPrompt length", () => {
+        const at = "a".repeat(AGENTS_RUN_MAX_USER_PROMPT_LENGTH);
+        expect(AgentsRunRequestSchema.safeParse({ userMessage: { userPrompt: at } })
+            .success).toBe(true);
+        expect(AgentsRunRequestSchema.safeParse({
+            userMessage: { userPrompt: at + "a" },
+        }).success).toBe(false);
+    });
+    it("strips agentType from userMessage", () => {
+        const parsed = AgentsRunRequestSchema.parse({
+            userMessage: { userPrompt: "x", agentType: "project-configuration" },
+        });
+        expect(parsed.userMessage).toEqual({ userPrompt: "x" });
+    });
+    it("treats null optional fields as absent", () => {
+        const parsed = AgentsRunRequestSchema.parse({
+            userMessage: { userPrompt: "x" },
+            userId: null,
+            userEmail: "a@b.c",
+            branchName: null,
+            projectId: null,
+            context: null,
+        });
+        expect(parsed).toEqual({
+            userMessage: { userPrompt: "x" },
+            userId: undefined,
+            userEmail: "a@b.c",
+            branchName: undefined,
+            projectId: undefined,
+            context: undefined,
+        });
+    });
+});
+describe("AgentsRunRequest type", () => {
+    it("keeps optional fields optional on the parsed type", () => {
+        // Compile-time check: fails to type-check if the null normalization makes
+        // optional keys required on the output type.
+        const minimal = { userMessage: { userPrompt: "x" } };
+        expect(AgentsRunRequestSchema.parse(minimal)).toEqual(minimal);
+    });
+});
+describe("UpdateWebhookSecretRequestSchema", () => {
+    it("requires a non-empty webhookId", () => {
+        expect(UpdateWebhookSecretRequestSchema.safeParse({}).success).toBe(false);
+        expect(UpdateWebhookSecretRequestSchema.safeParse({ webhookId: "" }).success).toBe(false);
+    });
+    it("accepts an empty or omitted secret (removal)", () => {
+        expect(UpdateWebhookSecretRequestSchema.safeParse({ webhookId: "w", secret: "" })
+            .success).toBe(true);
+        expect(UpdateWebhookSecretRequestSchema.safeParse({ webhookId: "w" }).success).toBe(true);
+    });
+});

package/src/projects.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { AGENT_NATIVE_STARTER_REPO, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, findFigmaFileUrl, mentionsFigmaFileUrl, parseFigmaFileUrl, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
+import { AGENT_NATIVE_STARTER_REPO, CreateProjectRequestSchema, TemplateRefSchema, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, findFigmaFileUrl, mentionsFigmaFileUrl, parseFigmaFileUrl, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
 describe("project hosting schemas", () => {
     it("accepts the canonical published branch route", () => {
         expect(ProjectHostingSchema.parse({ publishedBranchId: "branch-live" })).toEqual({ publishedBranchId: "branch-live" });
@@ -294,3 +294,37 @@ describe("getProjectState", () => {
         expect(isProjectDeleted(project({ deleted: false }))).toBe(false);
     });
 });
+describe("TemplateRefSchema", () => {
+    it.each(["main", "eval/kyle/faster-start", "v1.2.3", "release_2026.10"])("accepts the branch or tag name %s", (ref) => {
+        expect(TemplateRefSchema.safeParse(ref).success).toBe(true);
+    });
+    it.each([
+        "",
+        "-b",
+        "--upload-pack=evil",
+        "../escape",
+        "a/../b",
+        "has space",
+        "semi;colon",
+        "a".repeat(256),
+    ])("rejects %j", (ref) => {
+        expect(TemplateRefSchema.safeParse(ref).success).toBe(false);
+    });
+});
+describe("CreateProjectRequestSchema templateRef", () => {
+    const base = {
+        source: { kind: "template", templateId: "agent-native-starter" },
+        name: "p",
+    };
+    it("is optional", () => {
+        expect(CreateProjectRequestSchema.parse(base).templateRef).toBeUndefined();
+    });
+    it("carries a valid ref through", () => {
+        expect(CreateProjectRequestSchema.parse({ ...base, templateRef: "eval/x" })
+            .templateRef).toBe("eval/x");
+    });
+    it("rejects an invalid ref", () => {
+        expect(CreateProjectRequestSchema.safeParse({ ...base, templateRef: "--x" })
+            .success).toBe(false);
+    });
+});