@builder.io/ai-utils 0.107.0 → 0.109.0

package/package.json

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

package/src/codegen.d.ts

@@ -140,6 +140,7 @@ export declare const GlobSearchToolInputSchema: z.ZodObject<{
 export type GlobSearchToolInput = z.infer<typeof GlobSearchToolInputSchema>;
 export declare const GrepSearchToolInputSchema: z.ZodObject<{
     query: z.ZodString;
+    node_modules_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     include_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     exclude_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     case_sensitive: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -510,6 +511,56 @@ export declare const RecordFrameToolInputSchema: z.ZodObject<{
     pr_highlight: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RecordFrameToolInput = z.infer<typeof RecordFrameToolInputSchema>;
+export declare const StartRecordingToolInputSchema: z.ZodObject<{
+    label: z.ZodString;
+}, z.core.$strip>;
+export type StartRecordingToolInput = z.infer<typeof StartRecordingToolInputSchema>;
+export declare const StopRecordingToolInputSchema: z.ZodObject<{}, z.core.$strip>;
+export type StopRecordingToolInput = z.infer<typeof StopRecordingToolInputSchema>;
+export declare const PublishEvidenceToolInputSchema: z.ZodObject<{
+    issues: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        verdict: z.ZodEnum<{
+            fixed: "fixed";
+            "needs-input": "needs-input";
+            "no-ui-change": "no-ui-change";
+            "not-reproduced": "not-reproduced";
+        }>;
+        summary: z.ZodString;
+        screenshots: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            caption: z.ZodString;
+        }, z.core.$strip>>;
+        recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            recording_id: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PublishEvidenceToolInput = z.infer<typeof PublishEvidenceToolInputSchema>;
+export declare const MAX_EVIDENCE_UPLOAD_BYTES: number;
+export declare const EvidenceUploadUrlOptionsSchema: z.ZodObject<{
+    contentType: z.ZodEnum<{
+        "image/webp": "image/webp";
+        "video/mp4": "video/mp4";
+    }>;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+export type EvidenceUploadUrlOptions = z.infer<typeof EvidenceUploadUrlOptionsSchema>;
+/** What publishing evidence did to the branch's open pull request. */
+export type OpenPRRefresh = {
+    status: "no-open-pr";
+} | {
+    status: "updated";
+    prNumber: number;
+} | {
+    status: "failed";
+    reason: string;
+};
+export interface EvidenceUploadUrlResult {
+    upload_url: string;
+    public_url: string;
+    required_headers: Record<string, string>;
+}
 export declare const ReportTestOutcomeToolInputSchema: z.ZodObject<{
     outcome: z.ZodEnum<{
         couldnt_verify: "couldnt_verify";
@@ -568,12 +619,29 @@ export interface TimelineFrameMetadata {
     fileName?: string;
     image_url?: string;
     prHighlight?: boolean;
+    /** Index into `TimelineRecording.phases` for a frame that belongs to a recording tab. */
+    phaseIndex?: number;
     description?: string;
     cursorX?: number | null;
     cursorY?: number | null;
     viewportWidth?: number;
     viewportHeight?: number;
 }
+/** One agent's slice of a merged browser-testing run. */
+export interface TimelineAgentPhase {
+    label: string;
+    sessionId: string;
+    startEventId: number;
+    endEventId: number;
+    testCaseIds?: string[];
+    replayId?: string;
+}
+/** One screen recording published as evidence; the timeline shows a tab for each. */
+export interface TimelineVideoPhase {
+    label: string;
+    videoUrl: string;
+    testCaseIds: string[];
+}
 export interface TimelineRecording {
     version: 1;
     sessionId: string;
@@ -590,14 +658,7 @@ export interface TimelineRecording {
         description: string;
         debugInfo?: string;
     }>;
-    phases?: Array<{
-        label: string;
-        sessionId: string;
-        startEventId: number;
-        endEventId: number;
-        testCaseIds?: string[];
-        replayId?: string;
-    }>;
+    phases?: Array<TimelineAgentPhase | TimelineVideoPhase>;
 }
 export interface TimelineSubmissionMetadata {
     prNumber?: number;
@@ -1515,6 +1576,7 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
     }, z.core.$strip>;
     Grep: z.ZodObject<{
         query: z.ZodString;
+        node_modules_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         include_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         exclude_glob: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         case_sensitive: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
@@ -1629,6 +1691,29 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         pr_highlight: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
+    StartRecording: z.ZodObject<{
+        label: z.ZodString;
+    }, z.core.$strip>;
+    StopRecording: z.ZodObject<{}, z.core.$strip>;
+    PublishEvidence: z.ZodObject<{
+        issues: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            verdict: z.ZodEnum<{
+                fixed: "fixed";
+                "needs-input": "needs-input";
+                "no-ui-change": "no-ui-change";
+                "not-reproduced": "not-reproduced";
+            }>;
+            summary: z.ZodString;
+            screenshots: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                caption: z.ZodString;
+            }, z.core.$strip>>;
+            recordings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                recording_id: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
     SubmitPRReview: z.ZodObject<{
         summary: z.ZodString;
         comments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1999,6 +2084,7 @@ export declare const CodeGenToolsSchema: z.ZodEnum<{
     PowerShell: "PowerShell";
     ProposeConfig: "ProposeConfig";
     ProposeEnvVariable: "ProposeEnvVariable";
+    PublishEvidence: "PublishEvidence";
     PullPrototype: "PullPrototype";
     Read: "Read";
     ReadBranch: "ReadBranch";
@@ -2018,6 +2104,8 @@ export declare const CodeGenToolsSchema: z.ZodEnum<{
     SetFileOverride: "SetFileOverride";
     Skill: "Skill";
     SpawnBranch: "SpawnBranch";
+    StartRecording: "StartRecording";
+    StopRecording: "StopRecording";
     SubmitPRReview: "SubmitPRReview";
     TaskCreate: "TaskCreate";
     TaskList: "TaskList";
@@ -2891,6 +2979,7 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         PowerShell: "PowerShell";
         ProposeConfig: "ProposeConfig";
         ProposeEnvVariable: "ProposeEnvVariable";
+        PublishEvidence: "PublishEvidence";
         PullPrototype: "PullPrototype";
         Read: "Read";
         ReadBranch: "ReadBranch";
@@ -2910,6 +2999,8 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         SetFileOverride: "SetFileOverride";
         Skill: "Skill";
         SpawnBranch: "SpawnBranch";
+        StartRecording: "StartRecording";
+        StopRecording: "StopRecording";
         SubmitPRReview: "SubmitPRReview";
         TaskCreate: "TaskCreate";
         TaskList: "TaskList";

package/src/codegen.js

@@ -143,7 +143,9 @@ export function readToolImageMediaType(filePath) {
 }
 export const GlobSearchToolInputSchema = z
     .object({
-    pattern: z.string().meta({ description: "The pattern to search for" }),
+    pattern: z.string().meta({
+        description: "The pattern to search for. node_modules and dist folders are skipped unless the pattern starts with a path inside node_modules (e.g. 'node_modules/@tabler/icons-react/**/*.d.ts').",
+    }),
 })
     .meta({ title: "GlobSearchToolInput" });
 export const GrepSearchToolInputSchema = z
@@ -151,6 +153,9 @@ export const GrepSearchToolInputSchema = z
     query: z.string().meta({
         description: 'A string literal or a JavaScript-flavored regex to search for in all project files. Only escape special characters such as {} and () in string literals to avoid confusion with regex patterns (e.g. "import \\{ foo \\}"). Avoid over-escaping as that will cause errors. Do NOT use inline regex flags like (?i) or (?s) — they are not supported. The search is case-insensitive by default; use the case_sensitive parameter to control this.',
     }),
+    node_modules_path: z.string().nullish().meta({
+        description: "Searches an installed package instead of the project. node_modules and dist folders are skipped by default; set this to a directory or file inside node_modules (e.g. 'node_modules/@tabler/icons-react') to search that package, including its dist folder and .d.ts files.",
+    }),
     include_glob: z.string().nullish().meta({
         description: "An optional single glob pattern to include only specific files (e.g. '**/*.(ts|tsx)' for all TypeScript files)",
     }),
@@ -746,6 +751,62 @@ export const RecordFrameToolInputSchema = z
     }),
 })
     .meta({ title: "RecordFrameToolInput" });
+export const StartRecordingToolInputSchema = z
+    .object({
+    label: z.string().meta({
+        description: "Timeline tab label for this recording, e.g. 'Production before', 'Figma', 'Local after'.",
+    }),
+})
+    .meta({ title: "StartRecordingToolInput" });
+export const StopRecordingToolInputSchema = z
+    .object({})
+    .meta({ title: "StopRecordingToolInput" });
+export const PublishEvidenceToolInputSchema = z
+    .object({
+    issues: z
+        .array(z.object({
+        title: z.string().meta({
+            description: "The issue as the user would name it.",
+        }),
+        verdict: z
+            .enum(["fixed", "not-reproduced", "needs-input", "no-ui-change"])
+            .meta({
+            description: "Only 'fixed' issues reach the PR's Verified section; the others stay on the timeline. 'no-ui-change' is for a change with nothing to show in a browser.",
+        }),
+        summary: z.string().meta({
+            description: "One or two sentences: what changed, or why it was not fixed.",
+        }),
+        screenshots: z
+            .array(z.object({
+            path: z.string().meta({
+                description: "A .png, .jpg or .webp file in the workspace or under ~/.builder.",
+            }),
+            caption: z.string(),
+        }))
+            .meta({
+            description: "Stills that support the fix; the PR shows them under the recording.",
+        }),
+        recordings: z
+            .array(z.object({
+            recording_id: z.string().meta({
+                description: "The recording_id StopRecording returned.",
+            }),
+        }))
+            .optional()
+            .meta({
+            description: "Required for a 'fixed' issue: its verification, recorded on your current code. Older recordings stay on the timeline as comparisons. One timeline tab each.",
+        }),
+    }))
+        .min(1),
+})
+    .meta({ title: "PublishEvidenceToolInput" });
+export const MAX_EVIDENCE_UPLOAD_BYTES = 100 * 1024 * 1024;
+export const EvidenceUploadUrlOptionsSchema = z
+    .object({
+    contentType: z.enum(["video/mp4", "image/webp"]),
+    size: z.number().int().positive().max(MAX_EVIDENCE_UPLOAD_BYTES),
+})
+    .meta({ title: "EvidenceUploadUrlOptions" });
 export const ReportTestOutcomeToolInputSchema = z
     .object({
     outcome: TestOutcomeSchema.meta({
@@ -1638,6 +1699,9 @@ export const CodeGenToolMapSchema = z.object({
     ExitPlanMode: ExitPlanModeToolInputSchema,
     ReadMcpResource: ReadMcpResourceToolInputSchema,
     RecordFrame: RecordFrameToolInputSchema,
+    StartRecording: StartRecordingToolInputSchema,
+    StopRecording: StopRecordingToolInputSchema,
+    PublishEvidence: PublishEvidenceToolInputSchema,
     SubmitPRReview: SubmitPRReviewToolInputSchema,
     AddComment: AddCommentToolInputSchema,
     ProposeConfig: ProposeConfigToolInputSchema,

package/src/projects.d.ts

@@ -472,7 +472,13 @@ export declare const ProjectSkillSchema: z.ZodUnion<readonly [z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>]>;
 export type ProjectSkill = z.infer<typeof ProjectSkillSchema>;
-export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
+export declare const FusionExecutionEnvironmentSchema: z.ZodEnum<{
+    cloud: "cloud";
+    "cloud-v2": "cloud-v2";
+    "container-less": "container-less";
+    containerized: "containerized";
+}>;
+export type FusionExecutionEnvironment = z.infer<typeof FusionExecutionEnvironmentSchema>;
 export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "repo-indexer" | "builder-publish-integration";
 export interface PartialBranchData {
     name?: string;
@@ -725,6 +731,19 @@ export interface NewBranch extends BranchSharedData, RequiredBranchSharedData {
  */
 export type Branch = NewBranch | LegacyBranch;
 export declare const checkIsNewBranch: (branch: Branch) => branch is NewBranch;
+/** Identifies a single branch by its project and branch name. */
+export declare const BranchIdentifierSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+}, z.core.$strip>;
+export type BranchIdentifier = z.infer<typeof BranchIdentifierSchema>;
+/** Query params for `DELETE /projects/branches`. */
+export declare const DeleteBranchOptionsSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+    hard: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
+}, z.core.$strip>;
+export type DeleteBranchOptions = z.input<typeof DeleteBranchOptionsSchema>;
 /**
  * Request options for `GET /projects/branches/list`. Owner/org scope comes from
  * the authenticated request context; `ownerId` here is a superuser-only override.
@@ -829,6 +848,11 @@ export declare const ShapeOptionSchema: z.ZodObject<{
             designSystemName: z.ZodString;
         }, z.core.$strip>], "kind">>>;
     }, z.core.$strip>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        delegate: "delegate";
+        "figma-link": "figma-link";
+        upload: "upload";
+    }>>;
 }, z.core.$strip>;
 export type ShapeOption = z.infer<typeof ShapeOptionSchema>;
 export declare const ShapeQuestionSchema: z.ZodObject<{
@@ -853,14 +877,32 @@ export declare const ShapeQuestionSchema: z.ZodObject<{
                 designSystemName: z.ZodString;
             }, z.core.$strip>], "kind">>>;
         }, z.core.$strip>>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            delegate: "delegate";
+            "figma-link": "figma-link";
+            upload: "upload";
+        }>>;
     }, z.core.$strip>>;
     guessOptionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ShapeQuestion = z.infer<typeof ShapeQuestionSchema>;
+/**
+ * The link in canonical form, or undefined when it is not an https link to a
+ * file on figma.com. Deliberately strict: the result is written into the
+ * user's repo and handed to the agent as a requirement.
+ */
+export declare function parseFigmaFileUrl(value: string): string | undefined;
+/**
+ * The first Figma file link in `text`, canonicalized by `parseFigmaFileUrl`.
+ * Bare and `http:` mentions count as https; trailing punctuation is dropped.
+ */
+export declare function findFigmaFileUrl(text: string): string | undefined;
+export declare function mentionsFigmaFileUrl(text: string): boolean;
 export declare const ShapeAnswerSchema: z.ZodObject<{
     questionId: z.ZodString;
     optionId: z.ZodOptional<z.ZodString>;
     designSystemId: z.ZodOptional<z.ZodString>;
+    figmaUrl: z.ZodOptional<z.ZodString>;
     designSystemName: z.ZodOptional<z.ZodString>;
     skipped: z.ZodBoolean;
     delegated: z.ZodBoolean;
@@ -878,6 +920,7 @@ export declare const ShapeAnswerInputSchema: z.ZodObject<{
     questionId: z.ZodString;
     optionId: z.ZodOptional<z.ZodString>;
     designSystemId: z.ZodOptional<z.ZodString>;
+    figmaUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ShapeAnswerInput = z.infer<typeof ShapeAnswerInputSchema>;
 export declare const GetShapeQuestionnaireOptionsSchema: z.ZodObject<{
@@ -893,6 +936,7 @@ export declare const SubmitShapeAnswersOptionsSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SubmitShapeAnswersOptions = z.infer<typeof SubmitShapeAnswersOptionsSchema>;
@@ -968,6 +1012,11 @@ export declare const ShapeSessionSchema: z.ZodObject<{
                     designSystemName: z.ZodString;
                 }, z.core.$strip>], "kind">>>;
             }, z.core.$strip>>;
+            kind: z.ZodOptional<z.ZodEnum<{
+                delegate: "delegate";
+                "figma-link": "figma-link";
+                upload: "upload";
+            }>>;
         }, z.core.$strip>>;
         guessOptionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
@@ -976,6 +1025,7 @@ export declare const ShapeSessionSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
         designSystemName: z.ZodOptional<z.ZodString>;
         skipped: z.ZodBoolean;
         delegated: z.ZodBoolean;
@@ -1041,6 +1091,11 @@ export declare const ShapeSessionDocSchema: z.ZodObject<{
                     designSystemName: z.ZodString;
                 }, z.core.$strip>], "kind">>>;
             }, z.core.$strip>>;
+            kind: z.ZodOptional<z.ZodEnum<{
+                delegate: "delegate";
+                "figma-link": "figma-link";
+                upload: "upload";
+            }>>;
         }, z.core.$strip>>;
         guessOptionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
@@ -1049,6 +1104,7 @@ export declare const ShapeSessionDocSchema: z.ZodObject<{
         questionId: z.ZodString;
         optionId: z.ZodOptional<z.ZodString>;
         designSystemId: z.ZodOptional<z.ZodString>;
+        figmaUrl: z.ZodOptional<z.ZodString>;
         designSystemName: z.ZodOptional<z.ZodString>;
         skipped: z.ZodBoolean;
         delegated: z.ZodBoolean;
@@ -1868,7 +1924,14 @@ export interface Project {
     projectType?: "app" | "repo-indexing";
     /** Custom domains associated with this project. */
     domains?: string[];
-    /** Whether the project is publicly accessible. */
+    /**
+     * Which members of the owning space can access the project. `"public"` (shown
+     * as "Team" in the UI, and the behavior when absent) admits every space
+     * member, subject to any project limits on their org role; `"private"` admits
+     * only the roles and users in {@link Project.projectAccess}. Org admins and
+     * the project's creator always have access. Grants nothing outside the
+     * space — see {@link Project.isPublic}.
+     */
     accessMode?: "public" | "private";
     /** Fine-grained access control configuration for the project. */
     projectAccess?: ProjectAccessControl;
@@ -1878,7 +1941,12 @@ export interface Project {
     screenshot: string | null;
     /** When true, this project is a built-in example shown to new users. */
     isExample?: boolean;
-    /** When true, the project is publicly accessible without authentication. */
+    /**
+     * When true, signed-in users outside the owning space can view and clone the
+     * project. Only example projects and connected fusion-starter projects can be
+     * made public. Independent of {@link Project.accessMode}, which governs members
+     * of the owning space.
+     */
     isPublic?: boolean;
     /** Volume snapshot metadata for restoring container state. */
     snapshotVolume?: {
@@ -2202,6 +2270,11 @@ export declare const ProjectSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     templateId: z.ZodString;
 }, z.core.$strip>], "kind">;
 export type ProjectSource = z.infer<typeof ProjectSourceSchema>;
+/** Query string of `GET /projects`. Only `limit` is validated here so far. */
+export declare const GetProjectsQuerySchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type GetProjectsQuery = z.infer<typeof GetProjectsQuerySchema>;
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -3169,6 +3242,12 @@ export declare const DeployFailureReportSchema: z.ZodObject<{
     excerpt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type DeployFailureReport = z.infer<typeof DeployFailureReportSchema>;
+export declare const DeployFixNotRequestedReasonSchema: z.ZodEnum<{
+    error: "error";
+    "no-branch": "no-branch";
+    "send-failed": "send-failed";
+}>;
+export type DeployFixNotRequestedReason = z.infer<typeof DeployFixNotRequestedReasonSchema>;
 export declare const DeployFailureSchema: z.ZodObject<{
     stage: z.ZodOptional<z.ZodEnum<{
         build: "build";
@@ -3188,6 +3267,11 @@ export declare const DeployFailureSchema: z.ZodObject<{
     exitCode: z.ZodOptional<z.ZodNumber>;
     signal: z.ZodOptional<z.ZodString>;
     fixRequested: z.ZodOptional<z.ZodBoolean>;
+    fixNotRequestedReason: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        "no-branch": "no-branch";
+        "send-failed": "send-failed";
+    }>>;
 }, z.core.$strip>;
 export type DeployFailure = z.infer<typeof DeployFailureSchema>;
 export declare const DeploySchema: z.ZodObject<{
@@ -3239,6 +3323,11 @@ export declare const DeploySchema: z.ZodObject<{
         exitCode: z.ZodOptional<z.ZodNumber>;
         signal: z.ZodOptional<z.ZodString>;
         fixRequested: z.ZodOptional<z.ZodBoolean>;
+        fixNotRequestedReason: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            "no-branch": "no-branch";
+            "send-failed": "send-failed";
+        }>>;
     }, z.core.$strip>>;
     createdAt: z.ZodNumber;
     completedAt: z.ZodOptional<z.ZodNumber>;
@@ -3365,6 +3454,11 @@ export declare const DeployListItemSchema: z.ZodObject<{
         exitCode: z.ZodOptional<z.ZodNumber>;
         signal: z.ZodOptional<z.ZodString>;
         fixRequested: z.ZodOptional<z.ZodBoolean>;
+        fixNotRequestedReason: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            "no-branch": "no-branch";
+            "send-failed": "send-failed";
+        }>>;
     }, z.core.$strip>>;
     createdAt: z.ZodNumber;
     completedAt: z.ZodOptional<z.ZodNumber>;
@@ -3625,6 +3719,11 @@ export declare const GetDeploysResponseSchema: z.ZodObject<{
             exitCode: z.ZodOptional<z.ZodNumber>;
             signal: z.ZodOptional<z.ZodString>;
             fixRequested: z.ZodOptional<z.ZodBoolean>;
+            fixNotRequestedReason: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                "no-branch": "no-branch";
+                "send-failed": "send-failed";
+            }>>;
         }, z.core.$strip>>;
         createdAt: z.ZodNumber;
         completedAt: z.ZodOptional<z.ZodNumber>;
@@ -3936,6 +4035,24 @@ export declare const EnsureMainBranchExistsOptionsSchema: z.ZodObject<{
     branchName: z.ZodString;
 }, z.core.$strip>;
 export type EnsureMainBranchExistsOptions = z.infer<typeof EnsureMainBranchExistsOptionsSchema>;
+/** Request body for `POST /projects/ensure-fusion-config`. */
+export declare const EnsureFusionConfigParamsSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    branchName: z.ZodString;
+    includeBackupMetadata: z.ZodOptional<z.ZodBoolean>;
+    volumeMountPath: z.ZodOptional<z.ZodString>;
+    isLocal: z.ZodOptional<z.ZodBoolean>;
+    nativeApp: z.ZodOptional<z.ZodBoolean>;
+    miseLocationPath: z.ZodOptional<z.ZodString>;
+    _useNI: z.ZodOptional<z.ZodBoolean>;
+    fusionEnvironment: z.ZodOptional<z.ZodEnum<{
+        cloud: "cloud";
+        "cloud-v2": "cloud-v2";
+        "container-less": "container-less";
+        containerized: "containerized";
+    }>>;
+}, z.core.$strip>;
+export type EnsureFusionConfigParams = z.infer<typeof EnsureFusionConfigParamsSchema>;
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as

package/src/projects.js

@@ -200,9 +200,27 @@ export const ProjectSkillSchema = z
     ProjectSkillUrlSchema,
 ])
     .meta({ title: "ProjectSkill" });
+export const FusionExecutionEnvironmentSchema = z.enum([
+    "containerized",
+    "container-less",
+    "cloud",
+    "cloud-v2",
+]);
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };
+/** Identifies a single branch by its project and branch name. */
+export const BranchIdentifierSchema = z.object({
+    projectId: z.string().min(1),
+    branchName: z.string().min(1),
+});
+/** Query params for `DELETE /projects/branches`. */
+export const DeleteBranchOptionsSchema = z.object({
+    ...BranchIdentifierSchema.shape,
+    hard: z.stringbool().default(false).meta({
+        description: 'Permanently delete the branch instead of soft-deleting it ("true" / "false").',
+    }),
+});
 /**
  * Request options for `GET /projects/branches/list`. Owner/org scope comes from
  * the authenticated request context; `ownerId` here is a superuser-only override.
@@ -310,6 +328,11 @@ export const ShapeOptionSchema = z.object({
     id: z.string(),
     label: z.string(),
     effect: ShapeOptionEffectSchema.optional(),
+    /**
+     * How the client renders an option that is not a plain choice. Absent means
+     * a choice when `effect` is set, delegation otherwise.
+     */
+    kind: z.enum(["upload", "delegate", "figma-link"]).optional(),
 });
 export const ShapeQuestionSchema = z.object({
     id: z.string(),
@@ -318,10 +341,57 @@ export const ShapeQuestionSchema = z.object({
     options: z.array(ShapeOptionSchema),
     guessOptionId: z.string().optional(),
 });
+/** Figma paths that name a file, which is what the Builder Design tools read. */
+const FIGMA_FILE_PATH = /^\/(?:design|file|proto|board|slides|make)\/[A-Za-z0-9]+/;
+/**
+ * The link in canonical form, or undefined when it is not an https link to a
+ * file on figma.com. Deliberately strict: the result is written into the
+ * user's repo and handed to the agent as a requirement.
+ */
+export function parseFigmaFileUrl(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch (_a) {
+        return undefined;
+    }
+    const isFigmaHost = url.hostname === "figma.com" || url.hostname === "www.figma.com";
+    if (url.protocol !== "https:" ||
+        !isFigmaHost ||
+        url.port ||
+        url.username ||
+        url.password ||
+        !FIGMA_FILE_PATH.test(url.pathname)) {
+        return undefined;
+    }
+    return url.href;
+}
+/**
+ * Lenient on purpose: users paste bare links, so any mention counts. Not one
+ * inside another URL's path or after an `@`, which would name a different host.
+ */
+const FIGMA_FILE_MENTION = /(?:^|[^a-z0-9.\/@-])(?:https?:\/\/)?((?:www\.)?figma\.com\/(?:design|file|proto|board|slides|make)\/[a-z0-9]+[^\s<>()[\]{}"'`]*)/i;
+/**
+ * The first Figma file link in `text`, canonicalized by `parseFigmaFileUrl`.
+ * Bare and `http:` mentions count as https; trailing punctuation is dropped.
+ */
+export function findFigmaFileUrl(text) {
+    var _a;
+    const mention = (_a = FIGMA_FILE_MENTION.exec(text)) === null || _a === void 0 ? void 0 : _a[1];
+    if (!mention)
+        return undefined;
+    return parseFigmaFileUrl(`https://${mention.replace(/[.,;:!?]+$/, "")}`);
+}
+export function mentionsFigmaFileUrl(text) {
+    return findFigmaFileUrl(text) !== undefined;
+}
 export const ShapeAnswerSchema = z.object({
     questionId: z.string(),
     optionId: z.string().optional(),
     designSystemId: z.string().optional(),
+    /** Set only for the Figma link option, canonicalized by `parseFigmaFileUrl`. */
+    figmaUrl: z.string().optional(),
     /**
      * Server-resolved from `designSystemId` against the caller's accessible
      * design systems. `settings.designSystems` is matched by name downstream, so
@@ -338,6 +408,7 @@ const ShapeAnswerInputBaseSchema = ShapeAnswerSchema.pick({
     questionId: true,
     optionId: true,
     designSystemId: true,
+    figmaUrl: true,
     skipped: true,
     delegated: true,
 });
@@ -354,6 +425,14 @@ export const ShapeAnswerInputSchema = z.object({
         .trim()
         .min(1)
         .optional(),
+    figmaUrl: ShapeAnswerInputBaseSchema.shape.figmaUrl
+        .unwrap()
+        .trim()
+        .max(2048)
+        .refine((value) => parseFigmaFileUrl(value) !== undefined, {
+        message: "Must be a link to a Figma file",
+    })
+        .optional(),
 });
 export const GetShapeQuestionnaireOptionsSchema = z.object({
     projectId: z.string().trim().min(1),
@@ -1023,6 +1102,11 @@ export const ProjectSourceSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("repo"), repoUrl: z.string().url() }),
     z.object({ kind: z.literal("template"), templateId: z.string() }),
 ]);
+/** Query string of `GET /projects`. Only `limit` is validated here so far. */
+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(),
+});
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -1416,6 +1500,11 @@ export const DeployFailureReportSchema = z.object({
         description: "Head-and-tail excerpt of the failing output, cut on line boundaries. Event only, never persisted.",
     }),
 });
+export const DeployFixNotRequestedReasonSchema = z.enum([
+    "no-branch",
+    "send-failed",
+    "error",
+]);
 export const DeployFailureSchema = z.object({
     stage: DeployFailureStageSchema.optional(),
     owner: DeployFailureOwnerSchema,
@@ -1430,6 +1519,9 @@ export const DeployFailureSchema = z.object({
     fixRequested: z.boolean().optional().meta({
         description: "Whether a Fusion agent fix was dispatched for this failure.",
     }),
+    fixNotRequestedReason: DeployFixNotRequestedReasonSchema.optional().meta({
+        description: "Why a fix this failure qualified for was not dispatched. Absent when the failure never qualified.",
+    }),
 });
 export const DeploySchema = z.object({
     id: z.string(),
@@ -2214,6 +2306,32 @@ export const EnsureMainBranchExistsOptionsSchema = z.object({
         description: "Branch whose head ref seeds the main branch when it doesn't exist yet. No-op for non-internalHost projects.",
     }),
 });
+/** Request body for `POST /projects/ensure-fusion-config`. */
+export const EnsureFusionConfigParamsSchema = z.object({
+    projectId: z.string().min(1),
+    branchName: z.string().min(1),
+    includeBackupMetadata: z.boolean().optional().meta({
+        description: "Whether to include backup metadata in the fusion config. This involves checking backup data and generating download URLs. Defaults to false.",
+    }),
+    volumeMountPath: z.string().optional().meta({
+        description: 'Volume mount path for the container. Defaults to "/app" if not specified.',
+    }),
+    isLocal: z.boolean().optional().meta({
+        description: "Flag for local execution mode. When true, adjusts paths for local execution (e.g., ./workspace instead of /app/workspace).",
+    }),
+    nativeApp: z.boolean().optional().meta({
+        description: "Flag for native app projects. When true, adds nativeApp: true to fusion config.",
+    }),
+    miseLocationPath: z.string().optional().meta({
+        description: "Path to mise installation. Provided by client from desktop app system info.",
+    }),
+    _useNI: z.boolean().optional().meta({
+        description: "Flag to use NI for package management. When true, uses NI for package management. Defaults to true.",
+    }),
+    fusionEnvironment: FusionExecutionEnvironmentSchema.optional().meta({
+        description: "Fusion environment type override. When not provided, the environment is resolved from branch/project settings.",
+    }),
+});
 /**
  * `settings.environmentVariables` is stored with **plaintext** secret values;
  * secrets are masked before this shape leaves ai-services, same as

package/src/projects.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/projects.spec.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { DeleteBranchOptionsSchema, EnsureFusionConfigParamsSchema, } from "./projects.js";
+describe("DeleteBranchOptionsSchema", () => {
+    const ids = { projectId: "p1", branchName: "main" };
+    it("defaults hard to false", () => {
+        expect(DeleteBranchOptionsSchema.parse(ids)).toEqual({
+            ...ids,
+            hard: false,
+        });
+    });
+    it("parses hard from its query-string form", () => {
+        expect(DeleteBranchOptionsSchema.parse({ ...ids, hard: "true" }).hard).toBe(true);
+        expect(DeleteBranchOptionsSchema.parse({ ...ids, hard: "false" }).hard).toBe(false);
+    });
+    it("rejects a hard value that isn't a boolean string", () => {
+        expect(DeleteBranchOptionsSchema.safeParse({ ...ids, hard: "maybe" }).success).toBe(false);
+    });
+    it("requires a non-empty projectId and branchName", () => {
+        expect(DeleteBranchOptionsSchema.safeParse({}).success).toBe(false);
+        expect(DeleteBranchOptionsSchema.safeParse({ projectId: "", branchName: "main" })
+            .success).toBe(false);
+    });
+});
+describe("EnsureFusionConfigParamsSchema", () => {
+    const ids = { projectId: "p1", branchName: "main" };
+    it("accepts just the identifiers", () => {
+        expect(EnsureFusionConfigParamsSchema.parse(ids)).toEqual(ids);
+    });
+    it("requires a non-empty projectId and branchName", () => {
+        expect(EnsureFusionConfigParamsSchema.safeParse({ ...ids, projectId: "" })
+            .success).toBe(false);
+        expect(EnsureFusionConfigParamsSchema.safeParse({ projectId: "p1" }).success).toBe(false);
+    });
+    it("rejects an unknown fusionEnvironment", () => {
+        expect(EnsureFusionConfigParamsSchema.safeParse({
+            ...ids,
+            fusionEnvironment: "mainframe",
+        }).success).toBe(false);
+    });
+});

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, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
+import { AGENT_NATIVE_STARTER_REPO, 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" });
@@ -112,6 +112,92 @@ describe("guided onboarding project settings", () => {
             answers: [],
         })).toThrow();
     });
+    it("accepts a Figma file link on an answer and rejects anything else", () => {
+        var _a, _b;
+        const submit = (figmaUrl) => SubmitShapeAnswersOptionsSchema.safeParse({
+            projectId: "project-1",
+            questionnaireId: "questionnaire-1",
+            answers: [
+                {
+                    questionId: "visual-style",
+                    optionId: "figma-link",
+                    figmaUrl,
+                    skipped: false,
+                    delegated: false,
+                },
+            ],
+        });
+        expect((_b = (_a = submit(" https://www.figma.com/design/AbC123/App ").data) === null || _a === void 0 ? void 0 : _a.answers[0]) === null || _b === void 0 ? void 0 : _b.figmaUrl).toBe("https://www.figma.com/design/AbC123/App");
+        expect(submit("https://example.com/design/AbC123").success).toBe(false);
+        expect(submit("").success).toBe(false);
+    });
+});
+describe("parseFigmaFileUrl", () => {
+    it.each([
+        "https://www.figma.com/design/AbC123/My-App?node-id=1-2",
+        "https://figma.com/file/AbC123/Old-Style",
+        "  https://www.figma.com/proto/AbC123/Flow  ",
+    ])("accepts %s", (value) => {
+        expect(parseFigmaFileUrl(value)).toBe(new URL(value.trim()).href);
+    });
+    it.each([
+        "",
+        "not a url",
+        "http://www.figma.com/design/AbC123/My-App",
+        "https://evil.com/figma.com/design/AbC123",
+        "https://www.figma.com.evil.com/design/AbC123",
+        "https://www.figma.com/community/file/123",
+        "https://www.figma.com/design/",
+        "https://user:pass@www.figma.com/design/AbC123",
+        "https://www.figma.com:8443/design/AbC123",
+        "javascript:alert(1)",
+    ])("rejects %j", (value) => {
+        expect(parseFigmaFileUrl(value)).toBeUndefined();
+    });
+});
+describe("mentionsFigmaFileUrl", () => {
+    it.each([
+        "Build this https://www.figma.com/design/AbC123/My-App please",
+        "from figma.com/file/AbC123",
+        "(https://figma.com/proto/AbC123)",
+    ])("finds a link in %j", (text) => {
+        expect(mentionsFigmaFileUrl(text)).toBe(true);
+    });
+    it.each([
+        "Make it look like our Figma mockups",
+        "https://notfigma.com/design/AbC123",
+        "https://www.figma.com/community",
+        "https://evil.com/figma.com/design/AbC123",
+        "https://evil.com/?next=//figma.com/design/AbC123",
+        "user@figma.com/design/AbC123",
+    ])("finds nothing in %j", (text) => {
+        expect(mentionsFigmaFileUrl(text)).toBe(false);
+    });
+});
+describe("findFigmaFileUrl", () => {
+    it.each([
+        [
+            "Build this https://www.figma.com/design/AbC123/App?node-id=1-2.",
+            "https://www.figma.com/design/AbC123/App?node-id=1-2",
+        ],
+        [
+            "from figma.com/file/AbC123/Old, thanks",
+            "https://figma.com/file/AbC123/Old",
+        ],
+        [
+            "(http://www.figma.com/proto/AbC123/Flow)",
+            "https://www.figma.com/proto/AbC123/Flow",
+        ],
+        [
+            "first https://www.figma.com/design/One/A then https://www.figma.com/design/Two/B",
+            "https://www.figma.com/design/One/A",
+        ],
+    ])("reads the link out of %j", (text, expected) => {
+        expect(findFigmaFileUrl(text)).toBe(expected);
+    });
+    it("finds nothing without a file link", () => {
+        expect(findFigmaFileUrl("Make it like our Figma mockups")).toBeUndefined();
+    });
 });
 describe("matchesAgentNativeStarter", () => {
     it("matches when repoName is the starter", () => {