@base44-preview/sdk 0.8.52-pr.286.2dbb896 → 0.8.52-pr.286.58a3186

package/dist/platform/client/errors.types.d.ts

@@ -1,2 +1,2 @@
 /** Server refusals and client transport/processing failures. */
-export type PlatformSocketErrorCode = "connection_denied" | "connection_failed" | "session_unavailable" | "session_replaced" | "access_denied" | "access_revoked" | "snapshot_unavailable" | "subscription_limit" | "delivery_overflow" | "protocol_error" | "handler_failed" | "client_closed";
+export type PlatformSocketErrorCode = "connection_denied" | "connection_failed" | "session_unavailable" | "session_revoked" | "session_replaced" | "access_denied" | "access_revoked" | "snapshot_unavailable" | "subscription_limit" | "delivery_overflow" | "protocol_error" | "handler_failed" | "client_closed";

package/dist/platform/client/index.d.ts

@@ -4,4 +4,4 @@ export { PlatformSocketError } from "./errors.js";
 export type { PlatformSocketErrorCode } from "./errors.types.js";
 export type { PlatformClientOptions } from "./client.types.js";
 export type { BuilderModule, BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./modules/builder.types.js";
-export type { AppUpdate, AppStatus, ChatMessage, MessageParams, ToolCall, ToolDisplayProjection, ToolQuestionOption, ToolQuestion, ToolQuestionArguments, ToolSecretField, ToolSecretArguments, ToolPackageOperation, ToolPackageArguments, ToolPlanUpdate, ToolPlanArguments, ToolPrdArguments, ToolMediaArguments, ToolMediaResult, ToolQuestionAnswer, ToolQuestionInput, ToolOutcome, ToolGuardApproval, ToolResult, QueueItem, QueueUpdate, TaskUpdate, ImageReady, Directive, PlatformEventMap, PlatformEvent, Snapshot } from "./modules/builder.events.types.js";
+export type { AppStatus, AppStatusChanged, BranchScoped, ChatMessage, ImageResolved, MessageParams, MessageRemoved, MessageUpdated, PlatformEvent, PlatformEventMap, PreviewNavigationRequested, QueueItem, QueueUpdated, Snapshot, SnapshotQueue, TaskProgressed, ToolArguments, ToolCall, ToolDisplay, ToolEntityMutationArguments, ToolGuardApproval, ToolMediaArguments, ToolMediaResult, ToolPackageArguments, ToolPackageOperation, ToolPlanArguments, ToolPlanUpdate, ToolPrdArguments, ToolQuestion, ToolQuestionAnswer, ToolQuestionArguments, ToolQuestionInput, ToolQuestionOption, ToolSecretArguments, ToolSecretField, } from "./modules/builder.events.types.js";

package/dist/platform/client/modules/builder-protocol.d.ts

@@ -1,11 +1,15 @@
 import type { PlatformEvent, PlatformEventMap, Snapshot } from "./builder.events.types.js";
-export declare const eventNames: readonly ["update_model", "directive", "queue_update", "task_update", "image_ready"];
-/** Error frames that name an app room. */
-export declare const roomErrorCodes: readonly ["access_denied", "access_revoked", "snapshot_unavailable"];
+export declare const eventNames: readonly ["message.updated", "message.removed", "app.status_changed", "preview.reload_requested", "preview.navigation_requested", "queue.updated", "task.progressed", "image.resolved", "conversation.changed", "files.changed", "branch.deleted", "repository.changed", "pull_request.changed"];
+/** Notices that name an app room, by the error code each one reports. */
+export declare const roomNotices: {
+    readonly "room.access_denied": "access_denied";
+    readonly "room.access_revoked": "access_revoked";
+    readonly "room.snapshot_unavailable": "snapshot_unavailable";
+};
 export declare const appPattern: RegExp;
 export declare const roomFor: (appId: string) => string;
 export declare function object(value: unknown): Record<string, unknown>;
-export declare function string(value: unknown): string;
 export declare function appFromRoom(value: unknown): string | undefined;
+/** Every event is `{room, data}`; payload schemas are the service's, so only the envelope is validated. */
 export declare function decode(type: keyof PlatformEventMap, appId: string, raw: unknown): PlatformEvent;
 export declare function decodeSnapshot(raw: unknown): Snapshot;

package/dist/platform/client/modules/builder-protocol.js

@@ -1,6 +1,14 @@
-export const eventNames = ["update_model", "directive", "queue_update", "task_update", "image_ready"];
-/** Error frames that name an app room. */
-export const roomErrorCodes = ["access_denied", "access_revoked", "snapshot_unavailable"];
+export const eventNames = [
+    "message.updated", "message.removed", "app.status_changed", "preview.reload_requested",
+    "preview.navigation_requested", "queue.updated", "task.progressed", "image.resolved",
+    "conversation.changed", "files.changed", "branch.deleted", "repository.changed", "pull_request.changed",
+];
+/** Notices that name an app room, by the error code each one reports. */
+export const roomNotices = {
+    "room.access_denied": "access_denied",
+    "room.access_revoked": "access_revoked",
+    "room.snapshot_unavailable": "snapshot_unavailable",
+};
 export const appPattern = /^[a-f0-9]{24}$/;
 export const roomFor = (appId) => `/apps/${appId}`;
 export function object(value) {
@@ -8,25 +16,19 @@ export function object(value) {
         throw new Error("Invalid frame");
     return value;
 }
-export function string(value) {
-    if (typeof value !== "string" || !value)
-        throw new Error("Invalid string");
-    return value;
-}
 export function appFromRoom(value) {
     return typeof value === "string" && /^\/apps\/[a-f0-9]{24}$/.test(value) ? value.slice(6) : undefined;
 }
+/** Every event is `{room, data}`; payload schemas are the service's, so only the envelope is validated. */
 export function decode(type, appId, raw) {
-    const frame = object(raw);
-    const wrapped = type === "update_model" || type === "task_update" || type === "image_ready";
-    const data = wrapped ? object(JSON.parse(string(frame.data))) : frame;
-    // Payload schemas are owned by the service; only decode/validate the transport envelope here.
-    return { type, appId, data };
+    return { type, appId, data: object(object(raw).data) };
 }
 export function decodeSnapshot(raw) {
     const frame = object(raw);
-    if (!appFromRoom(frame.room) || !Array.isArray(frame.messages) || (frame.status !== null && typeof frame.status !== "object")) {
+    const data = object(frame.data);
+    if (!appFromRoom(frame.room) || !Array.isArray(data.messages) || (data.status !== null && typeof data.status !== "object")) {
         throw new Error("Invalid snapshot");
     }
-    return frame;
+    const queue = data.queue !== null && typeof data.queue === "object" ? { queue: data.queue } : {};
+    return { room: frame.room, status: data.status, messages: data.messages, ...queue };
 }

package/dist/platform/client/modules/builder-socket.d.ts

@@ -36,6 +36,7 @@ export declare class BuilderSocket implements BuilderSession {
     private retryDenied;
     private clearConnecting;
     private connectionError;
-    private serverError;
+    private sessionEnded;
+    private roomNotice;
     private protocolError;
 }

package/dist/platform/client/modules/builder-socket.js

@@ -1,6 +1,6 @@
 import { io } from "socket.io-client";
 import { PlatformSocketError } from "../errors.js";
-import { appFromRoom, appPattern, decode, decodeSnapshot, eventNames, object, roomErrorCodes, roomFor } from "./builder-protocol.js";
+import { appFromRoom, appPattern, decode, decodeSnapshot, eventNames, object, roomFor, roomNotices } from "./builder-protocol.js";
 import { notify, Subscription } from "./builder-subscription.js";
 const MAX_DENIAL_RETRIES = 5;
 /** @internal */
@@ -36,11 +36,11 @@ export class BuilderSocket {
             if (ending === "session_expired")
                 this.socket.connect(); // Renew through getSessionToken.
             else
-                this.connectionError(new PlatformSocketError(ending === "session_replaced" ? "session_replaced" : "connection_failed"));
+                this.connectionError(new PlatformSocketError(ending !== null && ending !== void 0 ? ending : "connection_failed"));
         });
         this.socket.on("connect_error", (error) => this.refused(error));
         this.socket.io.on("reconnect_failed", () => this.connectionError(new PlatformSocketError("connection_failed")));
-        this.socket.on("joined", (raw) => {
+        this.socket.on("app.snapshot", (raw) => {
             var _a;
             try {
                 const snapshot = decodeSnapshot(raw);
@@ -50,17 +50,23 @@ export class BuilderSocket {
                 this.protocolError(raw);
             }
         });
-        this.socket.on("error", (raw) => this.serverError(raw));
+        this.socket.on("session.ended", (raw) => this.sessionEnded(raw));
+        for (const [name, code] of Object.entries(roomNotices))
+            this.socket.on(name, (raw) => this.roomNotice(code, raw));
         for (const type of eventNames)
             this.socket.on(type, (raw) => {
-                var _a;
                 try {
                     const appId = appFromRoom(object(raw).room);
                     if (!appId)
                         throw new Error("Invalid app");
-                    (_a = this.subscriptions.get(appId)) === null || _a === void 0 ? void 0 : _a.event(decode(type, appId, raw));
+                    const event = decode(type, appId, raw);
+                    const subscription = this.subscriptions.get(appId);
+                    subscription === null || subscription === void 0 ? void 0 : subscription.event(event);
+                    // The server does not resend a snapshot after a rewrite of main: rejoining asks for one.
+                    if (subscription && event.type === "conversation.changed" && event.data.branch_id == null)
+                        this.join(subscription);
                 }
-                catch (_b) {
+                catch (_a) {
                     this.protocolError(raw);
                 }
             });
@@ -199,19 +205,27 @@ export class BuilderSocket {
         if (!this.closed)
             notify(this.options.onError, error);
     }
-    serverError(raw) {
+    sessionEnded(raw) {
         try {
-            const frame = object(raw);
-            if (frame.room === null && (frame.code === "session_expired" || frame.code === "session_replaced")) {
-                // The server disconnects next; the disconnect handler renews or stops.
-                this.token = undefined;
-                this.ending = frame.code;
-                return;
-            }
-            const appId = appFromRoom(frame.room);
-            const code = roomErrorCodes.find((code) => code === frame.code);
-            if (!appId || !code)
-                throw new Error("Unknown error");
+            const reason = object(object(raw).data).reason;
+            const ending = reason === "expired" ? "session_expired"
+                : reason === "revoked" ? "session_revoked"
+                    : reason === "replaced" ? "session_replaced" : undefined;
+            if (!ending)
+                throw new Error("Unknown reason");
+            // The server disconnects next; the disconnect handler renews or stops.
+            this.token = undefined;
+            this.ending = ending;
+        }
+        catch (_a) {
+            this.protocolError(raw);
+        }
+    }
+    roomNotice(code, raw) {
+        try {
+            const appId = appFromRoom(object(raw).room);
+            if (!appId)
+                throw new Error("Invalid app");
             const subscription = this.subscriptions.get(appId);
             if (code === "snapshot_unavailable")
                 subscription === null || subscription === void 0 ? void 0 : subscription.warn(code);

package/dist/platform/client/modules/builder.events.types.d.ts

@@ -1,5 +1,5 @@
-/** A reviewed file, execution, or entity activity summary. */
-export interface ToolDisplayProjection {
+/** Activity a file, execution or entity tool declared public. */
+export interface ToolDisplay {
     /** Changed file paths for a file operation. Source bodies and diffs are never included. */
     file_paths?: string[];
     /** Whether a file write intentionally used empty content. */
@@ -13,75 +13,74 @@ export interface ToolDisplayProjection {
     /** Number of records affected when supplied by the producer. */
     record_count?: number;
 }
-/** A reviewed selectable answer to a builder question. */
+/** A selectable answer to a builder question. */
 export interface ToolQuestionOption {
     /** Visible option label. */
-    label: string;
+    label?: string;
 }
-/** A reviewed builder question. Image/HTML source and private design context are excluded. */
+/** A builder question. Image/HTML source and private design context are excluded. */
 export interface ToolQuestion {
     /** Visible question text. */
     question?: string;
-    /** Existing question category. */
+    /** Question category. */
     type?: string;
     /** Optional visible supporting text. */
     description?: string;
     /** Whether more than one answer may be selected. */
     multi_select?: boolean;
-    /** Optional existing plan section identifier. */
+    /** Plan section the question covers. */
     covers?: string;
-    /** Reviewed selectable options. */
-    options?: ToolQuestionOption[];
+    /** Selectable options; a bare string option is its label. */
+    options?: (ToolQuestionOption | string)[];
 }
-/** Reviewed question arguments, serialized in `ToolCall.arguments_string`. */
+/** `ask_clarifying_questions` and `ask_plan_questions` arguments. */
 export interface ToolQuestionArguments {
-    /** Questions presented by a clarifying-question tool. */
-    questions: ToolQuestion[];
+    /** Questions presented to the user. */
+    questions?: ToolQuestion[];
 }
 /** A requested secret field. The secret value is never sent over the socket. */
 export interface ToolSecretField {
     /** Requested secret name. */
-    secretName: string;
+    secretName?: string;
     /** Optional explanation of where to obtain it. */
     description?: string;
 }
-/** Reviewed secret-form arguments, serialized in `ToolCall.arguments_string`. */
+/** `set_secrets` arguments. */
 export interface ToolSecretArguments {
     /** Requested secret fields. */
-    secrets_schema: ToolSecretField[];
+    secrets_schema?: ToolSecretField[];
 }
-/** A reviewed package operation. Versions and package-manager output are excluded. */
+/** A package operation. Versions and package-manager output are excluded. */
 export interface ToolPackageOperation {
     /** Package name. */
-    name: string;
+    name?: string;
     /** Requested package operation. */
     action?: string;
 }
-/** Reviewed package arguments, serialized in `ToolCall.arguments_string`. */
+/** `install_npm_package` arguments. */
 export interface ToolPackageArguments {
     /** Requested package operations. */
-    packages: ToolPackageOperation[];
+    packages?: ToolPackageOperation[];
 }
-/** A reviewed add-only builder plan update. */
+/** An add-only builder plan update. */
 export interface ToolPlanUpdate {
-    /** Existing update action. */
+    /** Update action. */
     action?: string;
     /** Plan section key. */
     section?: string;
     /** Optional user-facing section label. */
     section_label?: string;
-    /** Reviewed plan point. */
+    /** Plan point. */
     text?: string;
 }
-/** Reviewed plan arguments, serialized in `ToolCall.arguments_string`. */
+/** `update_plan` arguments. */
 export interface ToolPlanArguments {
     /** Plan updates in their emitted order. */
     updates?: ToolPlanUpdate[];
     /** Base plan sections the builder considers sufficiently specified. */
     sections_with_enough?: string[];
 }
-/** A reviewed plan, serialized in `generate_prd`'s `ToolCall.arguments_string`. The plan is the
- * user's own spec; in plan mode the message `content` beside it can be empty. */
+/** `generate_prd` arguments: the user's own plan. In plan mode the message `content` beside it can be empty. */
 export interface ToolPrdArguments {
     /** App or feature name. */
     app_name?: string;
@@ -102,45 +101,52 @@ export interface ToolPrdArguments {
     /** Engine settled in planning, for game plans. */
     game_engine?: string;
 }
-/** Reviewed generated-media arguments, serialized in `ToolCall.arguments_string`. */
+/** Image, game-image and video generation arguments. */
 export interface ToolMediaArguments {
     /** Visible media label. */
     label?: string;
     /** Requested image or video aspect ratio. */
     aspect_ratio?: string;
 }
-/** Reviewed state of generated media. Raw generation prompts and IDs are never included. */
+/** `update_entities` and `delete_entities` arguments; the entity is in `display.entity_name`. */
+export interface ToolEntityMutationArguments {
+    /** The agent's summary of the change. Queries and record values are never included. */
+    summary?: string;
+}
+/** The public arguments of a tool that declares them; narrow by the tool call's `name`. */
+export type ToolArguments = ToolQuestionArguments | ToolSecretArguments | ToolPackageArguments | ToolPlanArguments | ToolPrdArguments | ToolMediaArguments | ToolEntityMutationArguments;
+/** Generated-media state. Raw generation prompts and IDs are never included. */
 export interface ToolMediaResult {
-    /** Existing placeholder URL, used to associate an `image_ready` event with this tool. */
-    placeholder_url: string;
+    /** Placeholder URL, used to associate an `image.resolved` event with this tool. */
+    placeholder_url?: string;
     /** Current media-generation status. */
-    status: "pending" | "completed" | "failed";
-    /** Approved generated asset URL, once available. */
-    image_url: string | null;
+    status?: "pending" | "completed" | "failed";
+    /** Generated asset URL, once available. */
+    image_url?: string | null;
 }
-/** A reviewed answer to a clarifying question. Secret-form input is never included. */
+/** An answer to a clarifying question. Secret-form input is never included. */
 export interface ToolQuestionAnswer {
     /** Zero-based question index. */
     question_index?: number;
-    /** Labels selected by the user. */
+    /** Label selected for a single-select question. */
+    selected_label?: string;
+    /** Labels selected for a multi-select question. */
     selected_labels?: string[];
     /** User-provided free-text answer. Structural filtering does not redact prose. */
     custom_text?: string;
 }
-/** Reviewed clarifying-question input. */
+/** Clarifying-question answers. */
 export interface ToolQuestionInput {
     /** Answers supplied to the question card. */
-    answers: ToolQuestionAnswer[];
+    answers?: ToolQuestionAnswer[];
 }
-/** Fixed reviewed completion text. Raw tool results and errors are never included. */
-export type ToolOutcome = "Secret configuration completed." | "Package installation completed." | "Plan updated.";
 /** Why a safety guard parked a call for approval. Only present while the call waits. */
 export interface ToolGuardApproval {
     /** Guard identifier, e.g. `exec_tool_send_email` or `bash_approval`. */
     guard: string;
-    /** Human-readable reason. Omitted for shell commands, whose reason can quote the command. */
+    /** Human-readable reason, for guards whose reason never quotes input (not shell commands). */
     reason?: string;
-    /** Reviewed details for the guard; commands and record data are never included. */
+    /** The details the guard declares public; commands and record data are never included. */
     details?: {
         /** Entity method the code calls, e.g. `delete`. */
         method?: string;
@@ -158,61 +164,38 @@ export interface ToolGuardApproval {
         inspection_failed?: boolean;
     };
 }
-/** A fixed reviewed outcome, reviewed generated-media state, or a guard's approval reason. */
-export type ToolResult = ToolOutcome | ToolMediaResult | ToolGuardApproval;
-/** Public progress of an existing builder tool. */
+/** Public progress of a builder tool call. Only what the tool and its guard declare public is present. */
 export interface ToolCall {
-    /** Stable tool call identifier, when included in the update. */
+    /** Stable tool call identifier. */
     id?: string;
-    /** Tool name displayed by the builder. */
+    /** Tool name. */
     name?: string;
     /** Current execution state. */
     status?: "running" | "success" | "error" | "stopped" | "waiting_for_user_input";
     /** Whether the tool needs a user response through the partner backend. */
     requires_user_input?: boolean;
-    /** Whether the builder auto-approved the reviewed operation. */
-    auto_approved?: boolean | null;
-    /** Whether the reviewed mutation was applied. */
+    /** Whether the builder auto-approved the operation. */
+    auto_approved?: boolean;
+    /** Whether the mutation was applied. */
     mutation_applied?: boolean | null;
-    /** Existing serialized interaction category; no raw interaction payload. */
+    /** Kind of response a parked call waits for. */
     waiting_on?: {
         /** Kind of response expected. */
-        kind?: "approval" | "choice" | "input" | null;
-    } | null;
-    /**
-     * JSON containing one reviewed argument shape: ToolQuestionArguments, ToolSecretArguments,
-     * ToolPackageArguments, ToolPlanArguments, ToolPrdArguments, or ToolMediaArguments.
-     * It is omitted for all other tools and malformed/partial streaming arguments.
-     */
-    arguments_string?: string;
-    /** Reviewed activity metadata for file, execution, or entity tools. */
-    display_projection?: ToolDisplayProjection;
-    /** Reviewed clarifying-question answers only. */
+        kind?: "approval" | "choice" | "input";
+    };
+    /** The tool's public arguments; absent for tools that declare none and for partial streaming arguments. */
+    arguments?: ToolArguments;
+    /** What a file, execution or entity tool touched. */
+    display?: ToolDisplay;
+    /** Clarifying-question answers. */
     user_input?: ToolQuestionInput;
-    /** Fixed reviewed success outcome, generated-media state, or a parked call's guard reason. */
-    results?: ToolResult;
+    /** Generated media, once the call is not waiting on a guard: the image tool's state, or a URL alone
+     * (a game asset's placeholder, which `image.resolved` replaces, or a finished video). */
+    results?: ToolMediaResult | string;
+    /** A parked call's guard, and its reason and details where the guard declares them. */
+    approval?: ToolGuardApproval;
 }
-/** Public message replacement. Omitted properties are not synthesized by the SDK. */
-export interface ChatMessage {
-    /** Existing message identifier; replace a message with the same identifier. */
-    id?: string;
-    /** Public message author category. System messages are never delivered. */
-    role?: "user" | "assistant";
-    /** Generated or user-authored text. Structural filtering is not prose redaction. */
-    content?: string | null;
-    /** Public tool progress with optional reviewed interaction details. */
-    tool_calls?: ToolCall[] | null;
-    /** Message timestamp, without author identity. */
-    metadata?: {
-        /** Existing timestamp string. */
-        created_date?: string | null;
-    } | null;
-    /** Existing checkpoint reference; mutations remain on the partner backend. */
-    checkpoint_id?: string | null;
-    /** Reviewed scalar message parameters. */
-    additional_message_params?: MessageParams;
-}
-/** Reviewed scalar parameters a chat UI needs while a turn runs. */
+/** Scalar parameters a chat UI needs while a turn runs. */
 export interface MessageParams {
     /** Identifier the sending client attached, to match its optimistic message. */
     client_creation_id?: string;
@@ -225,67 +208,95 @@ export interface MessageParams {
     /** System message category. */
     system_message_type?: string;
 }
+/** A public chat message. Replace the message with the same `id` as a whole. */
+export interface ChatMessage {
+    /** Message identifier. */
+    id?: string;
+    /** Author category. System and hidden messages are never delivered. */
+    role?: "user" | "assistant";
+    /** Message text; structured content is withheld. Structural filtering is not prose redaction. */
+    content?: string | null;
+    /** Public tool progress. */
+    tool_calls?: ToolCall[] | null;
+    /** Message timestamp, without author identity. */
+    metadata?: {
+        /** ISO timestamp string. */
+        created_date?: string;
+    };
+    /** Checkpoint reference; mutations remain on the partner backend. */
+    checkpoint_id?: string | null;
+    /** Scalar message parameters. */
+    additional_message_params?: MessageParams;
+}
 /** Public builder state, without error diagnostics or billing context. */
 export interface AppStatus {
     /** Current builder state. */
     state?: "ready" | "processing" | "error";
-    /** Existing state timestamp. */
+    /** State timestamp. */
     last_updated_date?: string | null;
+    /** The user message that started the turn, when a turn set this state. Quote it to Base44 support. */
+    turn_id?: string | null;
+}
+/** Branch scope carried by app events. Null or absent is the main branch. */
+export interface BranchScoped {
+    /** Branch the change belongs to; null is main. */
+    branch_id?: string | null;
+}
+/** `message.updated`: a chat message was added or replaced. */
+export interface MessageUpdated extends BranchScoped {
+    /** The whole message; replace the one with the same `id`. */
+    message: ChatMessage;
+    /** Conversation containing the message. */
+    conversation_id?: string | null;
+}
+/** `message.removed`: a message was removed or hidden. An `id` the viewer never saw is a no-op. */
+export interface MessageRemoved extends BranchScoped {
+    /** Identifier of the message to remove. */
+    message_id: string;
+    /** Conversation that contained the message. */
+    conversation_id?: string | null;
+}
+/** `app.status_changed`: a turn started, finished or failed. */
+export interface AppStatusChanged extends BranchScoped {
+    /** The new state; null clears it. */
+    status: AppStatus | null;
+}
+/** `preview.navigation_requested`: show this page of the app in the preview. */
+export interface PreviewNavigationRequested extends BranchScoped {
+    /** App path to show. */
+    path: string;
+    /** Navigate even when the user has moved away from the page. */
+    force: boolean;
 }
-/** Partial app update. Omitted keys mean unchanged; explicit null means clear. */
-export interface AppUpdate {
-    /** Public builder state. */
-    status?: AppStatus | null;
-    /** Whole-message replacement by identifier, not a recursive message patch. */
-    _last_msg?: ChatMessage | null;
-    /** Conversation containing the replacement message. */
-    _last_msg_conversation_id?: string | null;
-    /** Existing branch scope, if supplied by the producer. */
-    _scope_branch_id?: string | null;
-    /** Whether to reload the app preview. */
-    sandbox_should_reload?: boolean | null;
-    /** Existing preview navigation target. */
-    navigate_preview_to?: string | null;
-    /** Existing forced preview navigation target. */
-    navigate_preview_force_to?: string | null;
-}
-/** Public queued builder request. */
+/** A queued builder request. */
 export interface QueueItem {
-    /** Stable queue item identifier. */
-    id: string;
+    /** Queue item identifier. */
+    id?: string;
     /** User-authored request text. */
-    content: string;
-    /** Existing creation timestamp. */
-    created_at: string;
-    /** Existing branch scope. */
+    content?: string;
+    /** Creation timestamp. */
+    created_at?: string;
+    /** Branch the request belongs to. */
     branch_id?: string | null;
 }
-/** Full public queue snapshot, replacing the previous queue. */
-export interface QueueUpdate {
-    /** Canonical app room. */
-    room: string;
-    /** App owning this queue. */
-    app_id: string;
-    /** Existing branch scope. */
-    branch_id?: string | null;
-    /** Current pending items. */
-    items: QueueItem[];
+/** `queue.updated`: the whole prompt queue, replacing the previous one. */
+export interface QueueUpdated extends BranchScoped {
+    /** Pending items. */
+    items?: QueueItem[];
     /** Whether queue processing is paused. */
-    is_paused: boolean;
+    is_paused?: boolean;
     /** Identifier of the item just processed, when supplied. */
     processed_item_id?: string | null;
 }
-/** Public tool task progress. */
-export interface TaskUpdate {
-    /** Existing task lifecycle event. */
-    event_type: "task_started" | "task_progress" | "task_completed" | "task_failed" | "task_cancelled";
+/** `task.progressed`: progress of a long-running tool. */
+export interface TaskProgressed extends BranchScoped {
     /** Associated tool call. */
     tool_call_id?: string | null;
     /** Associated chat message. */
     message_id?: string | null;
-    /** Existing branch scope. */
-    branch_id?: string | null;
-    /** Numeric progress only; diagnostic/free-text messages are withheld. */
+    /** Task lifecycle event, e.g. `task_progress`. */
+    event_type?: string | null;
+    /** Numeric progress only; diagnostic text is withheld. */
     progress?: {
         /** Completed work units. */
         current?: number | null;
@@ -295,49 +306,49 @@ export interface TaskUpdate {
         percentage?: number | null;
     } | null;
 }
-/** Placeholder resolution or image-generation completion. */
-export interface ImageReady {
-    /** Placeholder being resolved. */
-    placeholder_url: string;
-    /** Existing generation state. */
-    status: "pending" | "completed" | "failed";
-    /** Resolved image URL, or null when unavailable. */
-    image_url?: string | null;
-}
-/** Invalidation notice. A main-conversation `conversation_changed` is followed by a snapshot. */
-export interface Directive {
-    /** Canonical app room. */
-    room: string;
-    /** Public invalidation category. */
-    type: "conversation_changed" | "app_files_changed" | "branch_deleted" | "imported_git_changed" | "imported_pull_request_changed";
-    /** Existing branch scope. */
-    branch_id?: string | null;
-}
-/** Mapping of wire event names to decoded public payloads. */
+/** `image.resolved`: a generated image finished or failed. Replace its `placeholder_url` wherever it appears. */
+export type ImageResolved = ToolMediaResult;
+/** Mapping of public event names to their payloads. */
 export interface PlatformEventMap {
-    /** Partial builder/app update. */
-    update_model: AppUpdate;
-    /** Conversation or file invalidation. */
-    directive: Directive;
-    /** Full queue snapshot. */
-    queue_update: QueueUpdate;
-    /** Numeric tool progress. */
-    task_update: TaskUpdate;
-    /** Image placeholder resolution. */
-    image_ready: ImageReady;
-}
-/** Ordered delivery with decoded data and the original event name. */
+    /** A chat message was added or replaced. */
+    "message.updated": MessageUpdated;
+    /** A chat message was removed or hidden. */
+    "message.removed": MessageRemoved;
+    /** The builder started, finished or failed a turn. */
+    "app.status_changed": AppStatusChanged;
+    /** Reload the app preview. */
+    "preview.reload_requested": BranchScoped;
+    /** Show a page of the app in the preview. */
+    "preview.navigation_requested": PreviewNavigationRequested;
+    /** The whole prompt queue. */
+    "queue.updated": QueueUpdated;
+    /** Progress of a long-running tool. */
+    "task.progressed": TaskProgressed;
+    /** A generated image finished or failed. */
+    "image.resolved": ImageResolved;
+    /** The conversation was rewritten (undo, restore, sync). On main, the SDK rejoins for a fresh snapshot. */
+    "conversation.changed": BranchScoped;
+    /** The app's files changed outside a chat turn. Re-read them. */
+    "files.changed": BranchScoped;
+    /** A branch was deleted. */
+    "branch.deleted": BranchScoped;
+    /** The imported app's repository changed. */
+    "repository.changed": BranchScoped;
+    /** The imported app's pull request changed. */
+    "pull_request.changed": BranchScoped;
+}
+/** Ordered delivery of one public event. */
 export type PlatformEvent = {
     [K in keyof PlatformEventMap]: {
-        /** Original socket event name; narrows the payload type. */
+        /** Public event name; narrows the payload type. */
         type: K;
         /** Authorized app receiving this event. */
         appId: string;
-        /** Decoded payload; existing field names and omission/null semantics are retained. */
+        /** Event payload. Omitted keys mean unchanged; explicit null clears. */
         data: PlatformEventMap[K];
     };
 }[keyof PlatformEventMap];
-/** An app's current state: sent after each join and rejoin, and after a main-conversation rewrite. */
+/** An app's current state: sent after every join and rejoin, and after a main-conversation rewrite. */
 export interface Snapshot {
     /** Canonical app room. */
     room: string;
@@ -345,4 +356,13 @@ export interface Snapshot {
     status: AppStatus | null;
     /** The last 50 public messages, oldest first. */
     messages: ChatMessage[];
+    /** The main branch's prompt queue. Replace it, as with `queue.updated`. Absent from older servers. */
+    queue?: SnapshotQueue;
+}
+/** The prompt queue in a snapshot. */
+export interface SnapshotQueue {
+    /** Pending items. */
+    items: QueueItem[];
+    /** Whether queue processing is paused. */
+    is_paused: boolean;
 }

package/dist/platform/client/modules/builder.types.d.ts

@@ -28,7 +28,7 @@ export interface BuilderSession {
 /** One app subscription; at most eight may be active per builder session. */
 export interface SubscriptionOptions {
     /** Replace this app's state. Arrives after every join and rejoin, and after a main-conversation
-     * rewrite (undo, restore, sync). Live events may precede it; merge its messages by `id`.
+     * rewrite (undo, restore, sync). Live events follow it; it holds only the last 50 messages.
      */
     onSnapshot: (snapshot: Snapshot) => void | Promise<void>;
     /** Apply each live event. Delivery is serial per app; a rejection ends this subscription. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.52-pr.286.2dbb896",
+  "version": "0.8.52-pr.286.58a3186",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",