@builder.io/ai-utils 0.86.0 → 0.87.0

package/package.json

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

package/src/codegen.d.ts

@@ -79,71 +79,6 @@ export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
 export declare const AgentModelOverridesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export type AgentModelOverrides = z.infer<typeof AgentModelOverridesSchema>;
 export type ReviewEffort = "medium" | "high" | "low";
-export interface CustomAgentDefinition {
-    name: string;
-    description?: string;
-    /**
-     * When provided as an array, the first element must be the static prompt and
-     * subsequent elements should be dynamic content (e.g. env var placeholders).
-     * Only the first element is marked as cacheable — placing dynamic content
-     * first would invalidate the prompt cache on every request.
-     */
-    systemPrompt?: string | string[];
-    tools?: string[];
-    model?: string;
-    roundRobinModels?: string[];
-    position?: CodeGenPosition;
-    needDevServer?: boolean;
-    needValidation?: boolean;
-    includeMemories?: boolean;
-    resetAfterRun?: boolean;
-    mcpServers?: boolean;
-    asyncSubAgents?: boolean;
-    /**
-     * Expressive queue behavior for messages sent to this agent. See
-     * {@link QueueBehavior}. When both `queueBehavior` and `queueMode` are
-     * provided, `queueBehavior` wins.
-     */
-    queueBehavior?: QueueBehavior;
-    /**
-     * @deprecated Use {@link CustomAgentDefinition.queueBehavior} instead.
-     * Kept as a string alias for backwards compatibility with existing agent
-     * definitions in the wild.
-     */
-    queueMode?: QueueMode;
-    softContextWindow?: number;
-    filePath?: string;
-    /** Maximum wall time (in milliseconds) before the agent watchdog aborts. */
-    maxTimeoutMs?: number;
-    /**
-     * Default max LLM completion turns when this agent is spawned via the Agent tool.
-     * Overrides generic sub-agent defaults in dev-tools when set.
-     */
-    maxCompletions?: number;
-    /** Default reasoning effort level for this agent type. Overrides the session default. */
-    reasoning?: ReasoningEffort;
-    /**
-     * Default {@link SyncChangesFromRemote} policy applied to messages received
-     * by this agent when the message itself does not specify `syncChanges`.
-     * Only consulted at the session/sub-agent level (i.e. when the session was
-     * spawned with `agentType` equal to this agent's name). Use cases include
-     * always resetting the working branch to its base before each new message
-     * (e.g. the setup-project agent).
-     */
-    defaultSyncChanges?: SyncChangesFromRemote;
-    /**
-     * Where this agent was discovered. Drives precedence on name collision:
-     * `project` > `user` > `plugin`. Set by the discovery loader, not by the
-     * parsed file itself.
-     */
-    scope?: "project" | "user" | "plugin";
-    /**
-     * Name of the plugin that contributed this agent, if any. Set by the
-     * plugin loader (Phase 2); always `undefined` for project-level and
-     * user-level standalone files (Phase 1).
-     */
-    pluginName?: string;
-}
 export declare const CodeGenFrameworkSchema: z.ZodEnum<{
     angular: "angular";
     flutter: "flutter";
@@ -2090,7 +2025,14 @@ export type CodeGenMode = z.infer<typeof CodeGenModeSchema>;
  *   previous review). The in-flight user prompt and any partial
  *   assistant output for it are discarded.
  */
-export type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrupt-clear" | "interrupt-replace";
+export declare const QueueScheduleSchema: z.ZodEnum<{
+    interrupt: "interrupt";
+    "interrupt-clear": "interrupt-clear";
+    "interrupt-replace": "interrupt-replace";
+    "next-turn": "next-turn";
+    "until-idle": "until-idle";
+}>;
+export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
 /**
  * What happens when multiple messages are pending in the queue.
  *
@@ -2102,15 +2044,31 @@ export type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrup
  * - `preserve-order`: never merge; pop one message at a time in FIFO order.
  *   This is the historical behavior for `"until-idle"`.
  */
-export type QueueCoalesce = "merge" | "replace-latest" | "preserve-order";
+export declare const QueueCoalesceSchema: z.ZodEnum<{
+    merge: "merge";
+    "preserve-order": "preserve-order";
+    "replace-latest": "replace-latest";
+}>;
+export type QueueCoalesce = z.infer<typeof QueueCoalesceSchema>;
 /**
  * Expressive queue behavior built from two orthogonal axes:
  * `schedule` (when to dispatch) and `coalesce` (how to combine pending).
  */
-export interface QueueBehavior {
-    schedule: QueueSchedule;
-    coalesce: QueueCoalesce;
-}
+export declare const QueueBehaviorSchema: z.ZodObject<{
+    schedule: z.ZodEnum<{
+        interrupt: "interrupt";
+        "interrupt-clear": "interrupt-clear";
+        "interrupt-replace": "interrupt-replace";
+        "next-turn": "next-turn";
+        "until-idle": "until-idle";
+    }>;
+    coalesce: z.ZodEnum<{
+        merge: "merge";
+        "preserve-order": "preserve-order";
+        "replace-latest": "replace-latest";
+    }>;
+}, z.core.$strip>;
+export type QueueBehavior = z.infer<typeof QueueBehaviorSchema>;
 /**
  * Backwards-compatible queue mode. Accepts either a legacy string alias
  * or the full {@link QueueBehavior} object.
@@ -2119,7 +2077,21 @@ export interface QueueBehavior {
  * - `"next-turn"` → `{ schedule: "next-turn", coalesce: "merge" }`
  * - `"until-idle"` → `{ schedule: "until-idle", coalesce: "preserve-order" }`
  */
-export type QueueMode = "next-turn" | "until-idle" | QueueBehavior;
+export declare const QueueModeSchema: z.ZodUnion<readonly [z.ZodLiteral<"next-turn">, z.ZodLiteral<"until-idle">, z.ZodObject<{
+    schedule: z.ZodEnum<{
+        interrupt: "interrupt";
+        "interrupt-clear": "interrupt-clear";
+        "interrupt-replace": "interrupt-replace";
+        "next-turn": "next-turn";
+        "until-idle": "until-idle";
+    }>;
+    coalesce: z.ZodEnum<{
+        merge: "merge";
+        "preserve-order": "preserve-order";
+        "replace-latest": "replace-latest";
+    }>;
+}, z.core.$strip>]>;
+export type QueueMode = z.infer<typeof QueueModeSchema>;
 export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
 /**
  * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
@@ -2911,7 +2883,7 @@ export type CodeGenInputOptions = z.infer<typeof CodeGenInputOptionsSchema> & {
      */
     _mcpClientWrapperFactory?: (realClient: any) => any;
 };
-export type CodeGenErrorCodes = "credits-limit-daily" | "credits-limit-monthly" | "credits-limit-user" | "credits-limit-other" | "cli-genetic-error" | "git-update-error" | "prompt-too-long" | "context-too-long" | "abrupt-end" | "unknown" | "failed-recover-state" | "completion-expired" | "ask-to-continue" | "bad-initial-url" | "bad-smart-export-payload" | "invalid-last-message" | "corrupted-session" | "privacy-mode-key-required" | "privacy-mode-key-invalid" | "privacy-mode-key-mismatch" | "cli-network-error" | "invalid-credentials" | "model-restricted-too-large" | "org-no-models-enabled" | "assertion" | "rate-limit" | "unknown-design-system";
+export type CodeGenErrorCodes = "credits-limit-daily" | "credits-limit-monthly" | "credits-limit-user" | "credits-limit-other" | "cli-genetic-error" | "git-update-error" | "prompt-too-long" | "context-too-long" | "abrupt-end" | "unknown" | "failed-recover-state" | "completion-expired" | "ask-to-continue" | "bad-initial-url" | "bad-smart-export-payload" | "invalid-last-message" | "corrupted-session" | "privacy-mode-key-required" | "privacy-mode-key-invalid" | "privacy-mode-key-mismatch" | "privacy-mode-validation-unavailable" | "cli-network-error" | "invalid-credentials" | "model-restricted-too-large" | "org-no-models-enabled" | "assertion" | "rate-limit" | "unknown-design-system";
 export interface CodegenUsage {
     total: number;
     fast: number;
@@ -3498,6 +3470,112 @@ export declare const SyncChangesFromRemoteSchema: z.ZodObject<{
     updateLastCommits: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type SyncChangesFromRemote = z.infer<typeof SyncChangesFromRemoteSchema>;
+export declare const CustomAgentDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model: z.ZodOptional<z.ZodString>;
+    roundRobinModels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    position: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        "browser-testing": "browser-testing";
+        "builder-code": "builder-code";
+        "builder-code-panel": "builder-code-panel";
+        "builder-publish-integration": "builder-publish-integration";
+        cli: "cli";
+        "code-review-orchestrator": "code-review-orchestrator";
+        "create-app-firebase": "create-app-firebase";
+        "create-app-lovable": "create-app-lovable";
+        "design-system-indexer": "design-system-indexer";
+        "dsi-mcp": "dsi-mcp";
+        "editor-ai": "editor-ai";
+        fusion: "fusion";
+        "org-agent": "org-agent";
+        "org-worker": "org-worker";
+        "project-configuration": "project-configuration";
+        "projects-scheduler-memory-extraction": "projects-scheduler-memory-extraction";
+        "repo-indexing": "repo-indexing";
+        "setup-project": "setup-project";
+        unknown: "unknown";
+    }>, z.ZodTemplateLiteral<"browser-testing-agent" | "builder-code-agent" | "builder-code-panel-agent" | "builder-publish-integration-agent" | "cli-agent" | "code-review-orchestrator-agent" | "create-app-firebase-agent" | "create-app-lovable-agent" | "design-system-indexer-agent" | "dsi-mcp-agent" | "editor-ai-agent" | "fusion-agent" | "org-agent-agent" | "org-worker-agent" | "project-configuration-agent" | "projects-scheduler-memory-extraction-agent" | "repo-indexing-agent" | "setup-project-agent" | "unknown-agent">]>>;
+    needDevServer: z.ZodOptional<z.ZodBoolean>;
+    needValidation: z.ZodOptional<z.ZodBoolean>;
+    includeMemories: z.ZodOptional<z.ZodBoolean>;
+    resetAfterRun: z.ZodOptional<z.ZodBoolean>;
+    mcpServers: z.ZodOptional<z.ZodBoolean>;
+    asyncSubAgents: z.ZodOptional<z.ZodBoolean>;
+    queueBehavior: z.ZodOptional<z.ZodObject<{
+        schedule: z.ZodEnum<{
+            interrupt: "interrupt";
+            "interrupt-clear": "interrupt-clear";
+            "interrupt-replace": "interrupt-replace";
+            "next-turn": "next-turn";
+            "until-idle": "until-idle";
+        }>;
+        coalesce: z.ZodEnum<{
+            merge: "merge";
+            "preserve-order": "preserve-order";
+            "replace-latest": "replace-latest";
+        }>;
+    }, z.core.$strip>>;
+    queueMode: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"next-turn">, z.ZodLiteral<"until-idle">, z.ZodObject<{
+        schedule: z.ZodEnum<{
+            interrupt: "interrupt";
+            "interrupt-clear": "interrupt-clear";
+            "interrupt-replace": "interrupt-replace";
+            "next-turn": "next-turn";
+            "until-idle": "until-idle";
+        }>;
+        coalesce: z.ZodEnum<{
+            merge: "merge";
+            "preserve-order": "preserve-order";
+            "replace-latest": "replace-latest";
+        }>;
+    }, z.core.$strip>]>>;
+    softContextWindow: z.ZodOptional<z.ZodNumber>;
+    filePath: z.ZodOptional<z.ZodString>;
+    maxTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxCompletions: z.ZodOptional<z.ZodNumber>;
+    reasoning: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        none: "none";
+        xhigh: "xhigh";
+    }>>;
+    defaultSyncChanges: 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>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
+        project: "project";
+        user: "user";
+    }>>;
+    pluginName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CustomAgentDefinition = z.infer<typeof CustomAgentDefinitionSchema>;
 export declare const GenerateUserMessageSchema: z.ZodObject<{
     idempotencyKey: z.ZodOptional<z.ZodString>;
     user: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -3845,6 +3923,30 @@ export interface GenerateCodeEventError {
     message: string;
     usage?: CodegenUsage;
 }
+/**
+ * Wire schema for the pre-stream error protocol on `/codegen/completion`:
+ * middlewares that reject a request before the stream starts (credit limits,
+ * privacy mode) respond with an error status whose body is a single
+ * {@link GenerateCodeEventError} JSONL line. Loose so servers can attach
+ * extra fields (e.g. `usageInfo`), and `code` stays an open string so newer
+ * server codes pass through older clients.
+ */
+export declare const GenerateCodeEventErrorBodySchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    stopReason: z.ZodEnum<{
+        error: "error";
+        limit: "limit";
+    }>;
+    code: z.ZodString;
+    id: z.ZodString;
+    message: z.ZodString;
+}, z.core.$loose>;
+/**
+ * Decode a non-OK `/codegen/completion` response body as a structured error
+ * event. Returns undefined for anything else (auth failures, proxy errors,
+ * plain-text bodies), letting transport-level status handling take over.
+ */
+export declare function parseGenerateCodeEventErrorBody(body: string): GenerateCodeEventError | undefined;
 export interface GenerateCodeEventPagination {
     type: "pagination";
     pop: number;
@@ -4171,23 +4273,22 @@ export interface PrivacyMode {
     mcpServers?: boolean;
 }
 export type Mode = "init-and-launch" | "backup" | "backup-force-full" | "snapshot-creation";
-export interface FileOverride {
-    /**
-     * Path where the file should be written.
-     * Supports absolute paths ("/app/.env"), tilde ("~/.npmrc"), and relative paths ("./config.json").
-     */
-    path: string;
-    /**
-     * Plain text content to write to the file.
-     * Mutually exclusive with `base64`.
-     */
-    content?: string;
-    /**
-     * Base64-encoded binary content to write to the file.
-     * Mutually exclusive with `content`.
-     */
-    base64?: string;
-}
+/**
+ * A file to write into the container during setup. Exactly one of `content`
+ * (plain text) or `base64` (binary) must be provided: `z.xor` is an exclusive
+ * union that fails if zero or both options match, so the mutual exclusivity is
+ * enforced at runtime and reflected in the inferred type. Each variant omits
+ * the other's field — combined with `z.object`'s key-stripping, that's what
+ * makes the "both provided" case fail (it matches both options).
+ */
+export declare const FileOverrideSchema: z.ZodXor<readonly [z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    base64: z.ZodString;
+}, z.core.$strip>]>;
+export type FileOverride = z.infer<typeof FileOverrideSchema>;
 export interface MCPServerDefinition {
     command: string;
     args?: string[];

package/src/codegen.js

@@ -1626,6 +1626,70 @@ export const CodeGenModeSchema = z
     "quality-v4-agent",
 ])
     .meta({ title: "CodeGenMode" });
+/**
+ * When a queued message gets picked up by the scheduler.
+ *
+ * - `next-turn`: process queued messages as soon as the current LLM turn
+ *   finishes (i.e. between turns of an in-flight run).
+ * - `until-idle`: hold queued messages until the agent is fully idle
+ *   (current run has ended). Messages never interrupt an in-flight run.
+ * - `interrupt`: abort the in-flight run as soon as a new message arrives
+ *   and start processing it. Reserved for high-priority/reactive cases.
+ * - `interrupt-clear`: like `interrupt`, but also clears the session
+ *   (turn history, queued messages, last user, accumulated credits) before
+ *   processing the new message. Use when the new message should start from
+ *   a clean slate.
+ * - `interrupt-replace`: equivalent to abort + rewind to the previous
+ *   user message + replace it with the new one. Use when a fresh
+ *   request supersedes the in-flight one (e.g. incremental code-review
+ *   requests where a newer review should replace the still-running
+ *   previous review). The in-flight user prompt and any partial
+ *   assistant output for it are discarded.
+ */
+export const QueueScheduleSchema = z
+    .enum([
+    "next-turn",
+    "until-idle",
+    "interrupt",
+    "interrupt-clear",
+    "interrupt-replace",
+])
+    .meta({ title: "QueueSchedule" });
+/**
+ * What happens when multiple messages are pending in the queue.
+ *
+ * - `merge`: combine all pending messages into a single user message before
+ *   the next turn. This is the historical default for `"next-turn"`.
+ * - `replace-latest`: discard older pending messages and keep only the
+ *   most recently queued one (useful when stale inputs are obsolete, e.g.
+ *   a typing user replacing their previous draft).
+ * - `preserve-order`: never merge; pop one message at a time in FIFO order.
+ *   This is the historical behavior for `"until-idle"`.
+ */
+export const QueueCoalesceSchema = z
+    .enum(["merge", "replace-latest", "preserve-order"])
+    .meta({ title: "QueueCoalesce" });
+/**
+ * Expressive queue behavior built from two orthogonal axes:
+ * `schedule` (when to dispatch) and `coalesce` (how to combine pending).
+ */
+export const QueueBehaviorSchema = z
+    .object({
+    schedule: QueueScheduleSchema,
+    coalesce: QueueCoalesceSchema,
+})
+    .meta({ title: "QueueBehavior" });
+/**
+ * Backwards-compatible queue mode. Accepts either a legacy string alias
+ * or the full {@link QueueBehavior} object.
+ *
+ * Legacy aliases:
+ * - `"next-turn"` → `{ schedule: "next-turn", coalesce: "merge" }`
+ * - `"until-idle"` → `{ schedule: "until-idle", coalesce: "preserve-order" }`
+ */
+export const QueueModeSchema = z
+    .union([z.literal("next-turn"), z.literal("until-idle"), QueueBehaviorSchema])
+    .meta({ title: "QueueMode" });
 export const DEFAULT_QUEUE_BEHAVIOR = {
     schedule: "next-turn",
     coalesce: "merge",
@@ -1958,6 +2022,54 @@ export const SyncChangesFromRemoteSchema = z
     }),
 })
     .meta({ title: "SyncChangesFromRemote" });
+export const CustomAgentDefinitionSchema = z
+    .object({
+    name: z.string(),
+    description: z.string().optional(),
+    systemPrompt: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .meta({
+        description: "When provided as an array, the first element must be the static prompt and subsequent elements should be dynamic content (e.g. env var placeholders). Only the first element is marked as cacheable — placing dynamic content first would invalidate the prompt cache on every request.",
+    }),
+    tools: z.array(z.string()).optional(),
+    model: z.string().optional(),
+    roundRobinModels: z.array(z.string()).optional(),
+    position: CodeGenPositionSchema.optional(),
+    needDevServer: z.boolean().optional(),
+    needValidation: z.boolean().optional(),
+    includeMemories: z.boolean().optional(),
+    resetAfterRun: z.boolean().optional(),
+    mcpServers: z.boolean().optional(),
+    asyncSubAgents: z.boolean().optional(),
+    queueBehavior: QueueBehaviorSchema.optional().meta({
+        description: "Expressive queue behavior for messages sent to this agent. When both `queueBehavior` and `queueMode` are provided, `queueBehavior` wins.",
+    }),
+    queueMode: QueueModeSchema.optional().meta({
+        description: "@deprecated Use `queueBehavior` instead. Kept as a string alias for backwards compatibility with existing agent definitions in the wild.",
+    }),
+    softContextWindow: z.number().optional(),
+    filePath: z.string().optional(),
+    maxTimeoutMs: z.number().optional().meta({
+        description: "Maximum wall time (in milliseconds) before the agent watchdog aborts.",
+    }),
+    maxCompletions: z.number().optional().meta({
+        description: "Default max LLM completion turns when this agent is spawned via the Agent tool. Overrides generic sub-agent defaults in dev-tools when set.",
+    }),
+    reasoning: ReasoningEffortSchema.optional().meta({
+        description: "Default reasoning effort level for this agent type. Overrides the session default.",
+    }),
+    defaultSyncChanges: SyncChangesFromRemoteSchema.optional().meta({
+        description: "Default sync-changes policy applied to messages received by this agent when the message itself does not specify `syncChanges`. Only consulted at the session/sub-agent level (i.e. when the session was spawned with `agentType` equal to this agent's name). Use cases include always resetting the working branch to its base before each new message (e.g. the setup-project agent).",
+    }),
+    scope: z.enum(["project", "user", "plugin"]).optional().meta({
+        description: "Where this agent was discovered. Drives precedence on name collision: `project` > `user` > `plugin`. Set by the discovery loader, not by the parsed file itself.",
+    }),
+    pluginName: z.string().optional().meta({
+        description: "Name of the plugin that contributed this agent, if any. Set by the plugin loader (Phase 2); always `undefined` for project-level and user-level standalone files (Phase 1).",
+    }),
+})
+    .meta({ title: "CustomAgentDefinition" });
 export const GenerateUserMessageSchema = z
     .object({
     idempotencyKey: z.string().optional(),
@@ -2017,6 +2129,66 @@ export const CodegenSettingsRequestSchema = z
     repoHash: z.string().optional(),
 })
     .meta({ title: "CodegenSettingsRequest" });
+/**
+ * Wire schema for the pre-stream error protocol on `/codegen/completion`:
+ * middlewares that reject a request before the stream starts (credit limits,
+ * privacy mode) respond with an error status whose body is a single
+ * {@link GenerateCodeEventError} JSONL line. Loose so servers can attach
+ * extra fields (e.g. `usageInfo`), and `code` stays an open string so newer
+ * server codes pass through older clients.
+ */
+export const GenerateCodeEventErrorBodySchema = z.looseObject({
+    type: z.literal("error"),
+    stopReason: z.enum(["error", "limit"]),
+    code: z.string(),
+    id: z.string(),
+    message: z.string(),
+});
+/**
+ * Decode a non-OK `/codegen/completion` response body as a structured error
+ * event. Returns undefined for anything else (auth failures, proxy errors,
+ * plain-text bodies), letting transport-level status handling take over.
+ */
+export function parseGenerateCodeEventErrorBody(body) {
+    try {
+        const parsed = GenerateCodeEventErrorBodySchema.safeParse(JSON.parse(body.trim().split("\n")[0]));
+        return parsed.success
+            ? parsed.data
+            : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+const FileOverrideBaseShape = {
+    path: z.string().meta({
+        description: 'Path where the file should be written. Supports absolute paths ("/app/.env"), tilde ("~/.npmrc"), and relative paths ("./config.json").',
+    }),
+};
+/**
+ * A file to write into the container during setup. Exactly one of `content`
+ * (plain text) or `base64` (binary) must be provided: `z.xor` is an exclusive
+ * union that fails if zero or both options match, so the mutual exclusivity is
+ * enforced at runtime and reflected in the inferred type. Each variant omits
+ * the other's field — combined with `z.object`'s key-stripping, that's what
+ * makes the "both provided" case fail (it matches both options).
+ */
+export const FileOverrideSchema = z
+    .xor([
+    z.object({
+        ...FileOverrideBaseShape,
+        content: z.string().meta({
+            description: "Plain text content to write to the file.",
+        }),
+    }),
+    z.object({
+        ...FileOverrideBaseShape,
+        base64: z.string().meta({
+            description: "Base64-encoded binary content to write to the file.",
+        }),
+    }),
+])
+    .meta({ title: "FileOverride" });
 /**
  * Request for generating a commit message via LLM
  */

package/src/codegen.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { DEFAULT_QUEUE_BEHAVIOR, isInterruptSchedule, normalizeQueueMode, } from "./codegen";
+import { DEFAULT_QUEUE_BEHAVIOR, isInterruptSchedule, normalizeQueueMode, parseGenerateCodeEventErrorBody, } from "./codegen";
 describe("normalizeQueueMode", () => {
     it("returns the default behavior when input is undefined", () => {
         expect(normalizeQueueMode(undefined)).toEqual(DEFAULT_QUEUE_BEHAVIOR);
@@ -56,3 +56,38 @@ describe("isInterruptSchedule", () => {
         expect(isInterruptSchedule("until-idle")).toBe(false);
     });
 });
+describe("parseGenerateCodeEventErrorBody", () => {
+    it("decodes a structured error-event body", () => {
+        const body = JSON.stringify({
+            type: "error",
+            stopReason: "error",
+            code: "privacy-mode-key-required",
+            id: "abc",
+            message: "no key",
+        }) + "\n";
+        expect(parseGenerateCodeEventErrorBody(body)).toMatchObject({
+            code: "privacy-mode-key-required",
+            message: "no key",
+        });
+    });
+    it("preserves extra fields like usageInfo and decodes only the first line", () => {
+        const body = JSON.stringify({
+            type: "error",
+            stopReason: "limit",
+            code: "credits-limit-monthly",
+            id: "abc",
+            message: "limit reached",
+            usageInfo: { plan: "free" },
+        }) + "\nnot-json-second-line";
+        expect(parseGenerateCodeEventErrorBody(body)).toMatchObject({
+            code: "credits-limit-monthly",
+            usageInfo: { plan: "free" },
+        });
+    });
+    it("returns undefined for non-event bodies", () => {
+        expect(parseGenerateCodeEventErrorBody("Forbidden")).toBeUndefined();
+        expect(parseGenerateCodeEventErrorBody('{"error":"invalid token"}')).toBeUndefined();
+        expect(parseGenerateCodeEventErrorBody(JSON.stringify({ type: "error", code: 42, message: "bad shape" }))).toBeUndefined();
+        expect(parseGenerateCodeEventErrorBody("")).toBeUndefined();
+    });
+});

package/src/design-systems.d.ts

@@ -11,6 +11,22 @@ export interface FigmaHydrationResponse {
     manifest: import("./events.js").FigmaFrameManifest | null;
     files: FigmaHydrationFile[];
 }
+export declare const figmaDecodeJobStatusParamsSchema: z.ZodObject<{
+    jobId: z.ZodString;
+}, z.core.$strip>;
+export type FigmaDecodeJobStatusParams = z.infer<typeof figmaDecodeJobStatusParamsSchema>;
+export interface FigmaDecodeJobStatusResponse {
+    jobId: string;
+    status: "pending" | "processing" | "complete" | "error";
+    framesProcessed: number;
+    totalFrames: number;
+    branchName: string | null;
+    branchUrl: string | null;
+    error: string | null;
+    partialFailure?: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
 /**
  * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
  * `.git` or path segments). Used to gate public-repo inputs before cloning.

package/src/design-systems.js

@@ -1,4 +1,7 @@
 import { z } from "zod";
+export const figmaDecodeJobStatusParamsSchema = z.object({
+    jobId: z.string().min(1),
+});
 /**
  * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
  * `.git` or path segments). Used to gate public-repo inputs before cloning.