@builder.io/ai-utils 0.72.0 → 0.74.0

package/package.json

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

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;
@@ -3560,12 +3630,10 @@ export interface UserInput {
     /** @deprecated */
     repair?: boolean;
 }
-export interface CodegenTurn {
-    state: "running" | "done" | "error";
+interface CodegenTurnBase {
     unixTime: number;
     completionId: string;
     title: string;
-    nextUrl: string | undefined;
     user: UserSource;
     creditsUsed: number;
     actions: ActionItem[];
@@ -3577,7 +3645,34 @@ export interface CodegenTurn {
     lastCommit: GitSnapshot | undefined;
     cachedToolResults?: ContentMessageItemToolResult[];
     autoContinue: boolean;
+    /**
+     * Only set on synthetic per-user-message checkpoints (the non-linear
+     * `getSessionTurns` result). `completionId` always stays the checkpoint's
+     * own identity — for these synthetic turns, the user message's id — which is
+     * exactly what restoring "before this point" needs (the factual commit at
+     * that moment). `finalCompletionId` separately carries the last agent turn in
+     * the message's range that holds the post-message commit (`afterCommit`), for
+     * callers that want to restore to the "after" state. Undefined for ordinary
+     * (linear) turns.
+     */
+    finalCompletionId?: string;
+}
+/**
+ * A completed turn. Invariant: a `done` turn ALWAYS has a `nextUrl` (the
+ * continuation pointer the server emits on the `done` event / persists as the
+ * session's last completion). Encoded in the type so `state === "done"` narrows
+ * `nextUrl` to `string` — restore/anchor logic can rely on it.
+ */
+export interface CodegenTurnDone extends CodegenTurnBase {
+    state: "done";
+    nextUrl: string;
+}
+/** A turn that is still running, or errored before completing. */
+export interface CodegenTurnPending extends CodegenTurnBase {
+    state: "running" | "error";
+    nextUrl: string | undefined;
 }
+export type CodegenTurn = CodegenTurnDone | CodegenTurnPending;
 export interface GetSessionTurnsResult {
     turns: CodegenTurn[];
     allIds: string[];
@@ -4656,3 +4751,4 @@ export interface SessionData {
     numNormalUserMessages: number;
     metadata?: Record<string, any>;
 }
+export {};

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/design-systems.d.ts

@@ -35,10 +35,6 @@ export interface GenerateDesignSystemFormFields {
  */
 export declare const GITHUB_REPO_URL_REGEX: RegExp;
 export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
-    /**
-     * Mixed list of uploaded files in any order. Sent as repeated
-     * `attachments` fields in the multipart body.
-     */
     attachments: File[];
 }
 export interface GenerateDesignSystemResponse {
@@ -58,18 +54,75 @@ export interface GenerateDesignSystemErrorResponse {
 export declare const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES: number;
 export declare const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export declare const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
+export declare const generateDesignSystemBodySchema: z.ZodObject<{
+    projectName: z.ZodOptional<z.ZodString>;
+    devToolsVersion: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    githubRepoUrl: z.ZodOptional<z.ZodString>;
+    connectedProjectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;
 /**
- * Validation for non-file fields posted alongside the multipart upload.
- * Files are parsed out of the body by multer before this schema runs.
+ * Signed-URL upload flow.
  *
- * The inferred type matches `GenerateDesignSystemFormFields` so the wire
- * contract stays in lockstep with the shared type.
+ * Clients no longer post `.fig` bytes through the service (Cloud Run caps
+ * request bodies at 32 MiB). Instead they call `upload/start` to get a
+ * temporary signed resumable-upload URL per attachment, stream the bytes
+ * directly to GCS, then call `/generate` with the returned upload tokens.
+ * See `tech-specs/signed-url-figma-upload`.
  */
-export declare const generateDesignSystemBodySchema: z.ZodObject<{
+/** A single attachment the client declares when starting an upload. */
+export declare const uploadStartAttachmentSchema: z.ZodObject<{
+    name: z.ZodString;
+    mimetype: z.ZodString;
+    declaredSize: z.ZodNumber;
+}, z.core.$strip>;
+export type UploadStartAttachment = z.infer<typeof uploadStartAttachmentSchema>;
+/** Request body for `POST /design-systems/v1/upload/start`. */
+export declare const uploadStartBodySchema: z.ZodObject<{
+    attachments: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mimetype: z.ZodString;
+        declaredSize: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UploadStartBody = z.infer<typeof uploadStartBodySchema>;
+/**
+ * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
+ * `upload/start` and verified at `/generate`, so a client cannot point the
+ * decode worker at an object it did not upload.
+ */
+export declare const uploadTokenPayloadSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    gcsObject: z.ZodString;
+    ownerId: z.ZodString;
+    mimetype: z.ZodString;
+    originalName: z.ZodString;
+    idx: z.ZodNumber;
+}, z.core.$strip>;
+export type UploadTokenPayload = z.infer<typeof uploadTokenPayloadSchema>;
+export interface UploadStartResponseItem {
+    idx: number;
+    /** Signed URL the client POSTs to (with `x-goog-resumable: start`) to begin the resumable upload. */
+    uploadUrl: string;
+    /** Opaque signed token the client passes back to `/generate`. */
+    uploadToken: string;
+}
+export interface UploadStartResponse {
+    jobId: string;
+    uploads: UploadStartResponseItem[];
+}
+/**
+ * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
+ * Same non-file fields as the legacy multipart form, plus the `uploads`
+ * tokens returned by `upload/start` (one per attachment).
+ */
+export declare const generateDesignSystemRequestSchema: z.ZodObject<{
     projectName: z.ZodOptional<z.ZodString>;
     devToolsVersion: z.ZodOptional<z.ZodString>;
     selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
     githubRepoUrl: z.ZodOptional<z.ZodString>;
     connectedProjectId: z.ZodOptional<z.ZodString>;
+    uploads: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
-export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;
+export type GenerateDesignSystemRequestBody = z.infer<typeof generateDesignSystemRequestSchema>;

package/src/design-systems.js

@@ -8,13 +8,6 @@ export const GITHUB_REPO_URL_REGEX = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[
 export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 2 * 1024 * 1024 * 1024;
 export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
-/**
- * Validation for non-file fields posted alongside the multipart upload.
- * Files are parsed out of the body by multer before this schema runs.
- *
- * The inferred type matches `GenerateDesignSystemFormFields` so the wire
- * contract stays in lockstep with the shared type.
- */
 export const generateDesignSystemBodySchema = z.object({
     projectName: z.string().trim().min(1).max(200).optional(),
     devToolsVersion: z.string().trim().min(1).max(64).optional(),
@@ -40,3 +33,54 @@ export const generateDesignSystemBodySchema = z.object({
         .optional(),
     connectedProjectId: z.string().trim().min(1).max(128).optional(),
 });
+/**
+ * Signed-URL upload flow.
+ *
+ * Clients no longer post `.fig` bytes through the service (Cloud Run caps
+ * request bodies at 32 MiB). Instead they call `upload/start` to get a
+ * temporary signed resumable-upload URL per attachment, stream the bytes
+ * directly to GCS, then call `/generate` with the returned upload tokens.
+ * See `tech-specs/signed-url-figma-upload`.
+ */
+/** A single attachment the client declares when starting an upload. */
+export const uploadStartAttachmentSchema = z.object({
+    name: z.string().trim().min(1).max(512),
+    mimetype: z.string().trim().min(1).max(255),
+    declaredSize: z
+        .number()
+        .int()
+        .positive()
+        .max(GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES),
+});
+/** Request body for `POST /design-systems/v1/upload/start`. */
+export const uploadStartBodySchema = z.object({
+    attachments: z
+        .array(uploadStartAttachmentSchema)
+        .min(GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS)
+        .max(GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS),
+});
+/**
+ * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
+ * `upload/start` and verified at `/generate`, so a client cannot point the
+ * decode worker at an object it did not upload.
+ */
+export const uploadTokenPayloadSchema = z.object({
+    jobId: z.string().min(1),
+    gcsObject: z.string().min(1),
+    ownerId: z.string().min(1),
+    mimetype: z.string().min(1),
+    originalName: z.string().min(1),
+    idx: z.number().int().nonnegative(),
+});
+/**
+ * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
+ * Same non-file fields as the legacy multipart form, plus the `uploads`
+ * tokens returned by `upload/start` (one per attachment).
+ */
+export const generateDesignSystemRequestSchema = z.object({
+    ...generateDesignSystemBodySchema.shape,
+    uploads: z
+        .array(z.string().min(1))
+        .min(GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS)
+        .max(GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS),
+});

package/src/events.d.ts

@@ -1039,6 +1039,8 @@ export type FigmaDecodeJobV1 = FusionEventVariant<"figma.decode.job", {
     projectId: string;
     projectName: string;
     figmaName: string;
+    /** Design-system record this job feeds; updated with the branch once created. */
+    designSystemId?: string;
     /**
      * GCS object paths (relative to the configured bucket) of every attachment
      * uploaded for this job. The worker streams these back down, runs