@superblocksteam/gateway 2.0.161 → 2.0.162-next.1

package/dist/capabilities/source-files-archive.js

@@ -0,0 +1,54 @@
+import { strToU8, zipSync } from "fflate";
+import { IMPORT_SOURCE_FILES_MAX_BYTES } from "./types.js";
+/** Paths come from the model, so anything that would not extract as a relative path is rejected. */
+function normalizeSourcePath(sourcePath) {
+    const portablePath = sourcePath.replaceAll("\\", "/");
+    if (portablePath.startsWith("/") ||
+        /^[a-zA-Z]:/.test(portablePath) ||
+        portablePath.includes("\0")) {
+        return undefined;
+    }
+    const segments = portablePath
+        .split("/")
+        .filter((segment) => segment !== "" && segment !== ".");
+    if (segments.length === 0 || segments.includes("..")) {
+        return undefined;
+    }
+    return segments.join("/");
+}
+export function archiveSourceFiles(files) {
+    // Null prototype so a path like "__proto__" or "toString" is stored, not swallowed.
+    const entries = Object.create(null);
+    let sourceBytes = 0;
+    for (const file of files) {
+        const normalized = normalizeSourcePath(file.path);
+        if (!normalized) {
+            return {
+                kind: "error",
+                message: `Source file path must be a safe relative path: "${file.path}".`,
+            };
+        }
+        if (Object.hasOwn(entries, normalized)) {
+            return {
+                kind: "error",
+                message: `Source file path is duplicated: "${normalized}".`,
+            };
+        }
+        if (Buffer.byteLength(normalized) > 0xffff) {
+            return {
+                kind: "error",
+                message: `Source file path is too long: "${normalized}".`,
+            };
+        }
+        sourceBytes += Buffer.byteLength(file.content);
+        if (sourceBytes > IMPORT_SOURCE_FILES_MAX_BYTES) {
+            return {
+                kind: "error",
+                message: `Source files are ${sourceBytes} bytes before compression; the gateway inline source limit is ${IMPORT_SOURCE_FILES_MAX_BYTES} bytes (1 MB).`,
+            };
+        }
+        entries[normalized] = strToU8(file.content);
+    }
+    return { bytes: zipSync(entries), kind: "ok" };
+}
+//# sourceMappingURL=source-files-archive.js.map

package/dist/capabilities/source-files-archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-files-archive.js","sourceRoot":"","sources":["../../src/capabilities/source-files-archive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAM3D,oGAAoG;AACpG,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,MAAM,YAAY,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,IACE,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC;QAC5B,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC;QAC/B,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC3B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY;SAC1B,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAA+C;IAE/C,oFAAoF;IACpF,MAAM,OAAO,GAA+B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChE,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,mDAAmD,IAAI,CAAC,IAAI,IAAI;aAC1E,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;YACvC,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,oCAAoC,UAAU,IAAI;aAC5D,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,MAAM,EAAE,CAAC;YAC3C,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,kCAAkC,UAAU,IAAI;aAC1D,CAAC;QACJ,CAAC;QACD,WAAW,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,WAAW,GAAG,6BAA6B,EAAE,CAAC;YAChD,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,oBAAoB,WAAW,iEAAiE,6BAA6B,gBAAgB;aACvJ,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjD,CAAC"}

package/dist/capabilities/types.d.ts

@@ -1,7 +1,5 @@
 import type { BrowserDriverContract } from "../capture/browser-contract.js";
-import type { EventCursor } from "../events/cursor.js";
-import type { LostEventRange } from "../events/types.js";
-export type { CallerChannel, CallerRef } from "../resume/types.js";
+import type { CheckpointFailure, CheckpointWarning, TurnUpdate } from "../sabs/session-peer.js";
 export type CallerKind = "mcp";
 /**
  * The caller behind a capability invocation.
@@ -42,12 +40,14 @@ export type AuthElicitation = {
  * any session with more than one of them.
  */
 export type CapabilityError = {
+    /** Absent only when the call failed before it had an application at all. */
+    agentInstructions?: string;
     /** Absent only when the call failed before it had an application at all. */
     applicationId?: string;
     code: string;
     kind: "error";
     message: string;
-    /** Set when resending the prompt is what recovers this application. */
+    /** Set when the host has a concrete way to recover from this failure. */
     pendingAction?: PendingAppAction;
 };
 export type CapabilityResult<T> = {
@@ -67,7 +67,9 @@ export type GenerationStatus = "cancelled" | "completed"
  * The turn never ran to an outcome because the live-edit session did not: it
  * went away mid-flight, or it never opened at all. Distinct from `timeout`:
  * the turn did not run out of time, the thing that was to run it was not
- * there, and retrying is the right response.
+ * there. Mid-turn deaths are retryable. Failed opens are not when reconnecting
+ * would reach the same wedged session; only a just-created app is safe to
+ * recreate.
  */
  | "live_edit_terminated"
 /** The job ended without writing a file or leaving a draft. */
@@ -81,13 +83,40 @@ export type GenerationStatus = "cancelled" | "completed"
  *   sends no `progressToken` — Claude Desktop — can show anything mid-build.
  */
 export type TurnWait = "ack" | "turn";
+/**
+ * Durable org-scoped file returned by `upload_artifact`.
+ *
+ * `mediaType` is any type Superblocks attachments accept, not only the two
+ * archive types: an image or a log uploads as itself rather than being wrapped
+ * in a zip it would have to be decoded back out of.
+ */
+export type ArtifactDescriptor = {
+    fileName: string;
+    id: string;
+    mediaType: string;
+    storageKey: string;
+};
+export type UploadArtifactInput = {
+    files?: Array<{
+        content: string;
+        path: string;
+    }>;
+    /** Path or file name on the gateway host. */
+    filePath?: string;
+    /** Test-fixture transport only; real archives should use filePath. */
+    zipBase64?: string;
+};
+export type UploadArtifactResult = {
+    artifact: ArtifactDescriptor;
+    summary: string;
+};
 /**
  * Where a build stands.
  *
  * `unknown` means the gateway is not following a turn for this app: it finished
  * and was already reported, or nothing was ever started here.
  */
-export type BuildStatus = "building" | "cancelled"
+export type BuildStatus = "building" | "cancelled" | "checkpoint_failed"
 /**
  * Clark is working but out of the gateway's sight — polling cannot report it,
  * and only the editor can. Ends the poll loop instead of running it out.
@@ -109,17 +138,37 @@ export type BuildStatus = "building" | "cancelled"
  * added later, which is how a dead live edit came to be reported as `ready`
  * in the first place; this way the compiler stops the next one.
  */
-export declare function buildStatusOf(generationStatus: GenerationStatus): BuildStatus;
+export declare function buildStatusOf(generationStatus: GenerationStatus, checkpointFailure?: CheckpointFailure): BuildStatus;
+/**
+ * How a `check_app_progress` poll reads as a build status.
+ *
+ * Running and unknown map directly. A finished poll uses {@link buildStatusOf},
+ * except a successful checkpoint that paused for missing integrations: that is
+ * a decision, even when generationStatus is still `completed`.
+ */
+export declare function progressStatusOf(update: TurnUpdate): BuildStatus;
 export type StartAppInput = {
+    artifacts?: ArtifactDescriptor[];
     branch?: string;
     idempotencyKey: string;
     /** Defaults to PLAN (editor parity). Pass BUILD to skip planning. */
     mode?: "BUILD" | "PLAN";
     name?: string;
     prompt: string;
+    /** The failed app this one replaces; permits only this one fresh attempt. */
+    replacesApplicationId?: string;
     wait?: TurnWait;
 };
 export type DecisionPayload = {
+    integrations: Array<{
+        configuration: Record<string, unknown>;
+        /** The plugin's configuration form, so the host needs no lookup. */
+        configurationSchema?: Record<string, unknown>;
+        name?: string;
+        pluginId: string;
+    }>;
+    kind: "missing_integrations";
+} | {
     kind: "multi_choice";
     messageId?: string;
     options: string[];
@@ -134,6 +183,7 @@ export type StartAppResult = {
     /** Clark's chat lines since the previous report, oldest first. */
     activity?: string[];
     applicationId: string;
+    branch?: string;
     /** Host-driver steer. Tokens never belong here. */
     browser?: BrowserDriverContract;
     /**
@@ -141,6 +191,8 @@ export type StartAppResult = {
      * nothing to commit or the checkpoint did not land.
      */
     checkpointCommitId?: string;
+    checkpointFailure?: CheckpointFailure;
+    checkpointWarning?: CheckpointWarning;
     /** Absent while the build is still running (`wait: "ack"`). */
     reply?: string;
     /** Present when status is needs_decision. */
@@ -152,6 +204,7 @@ export type StartAppResult = {
     /** Mode this turn ran in, so the caller can say whether Clark is planning. */
     mode?: "BUILD" | "PLAN";
     name: string;
+    pendingAction?: PendingAppAction;
     /** Mid-turn testApi / testIntegration outcomes when the turn finished. */
     recentRuns?: RecentToolRun[];
     status: BuildStatus;
@@ -160,83 +213,55 @@ export type StartAppResult = {
 };
 export type CheckAppProgressInput = {
     applicationId?: string;
-    /**
-     * Resume from an explicit position instead of the one stored for this
-     * caller. Only needed when a caller keeps its own place — an omitted cursor
-     * reads from wherever the gateway last left this caller.
-     */
-    cursor?: EventCursor;
-};
-/**
- * Machine-readable pacing, so a caller polls on the gateway's terms rather
- * than on a number the model invented.
- *
- * Every long-running result carries a poll interval whether or not the host
- * supports progress notifications: a host that ignores progress still has to be
- * told when to come back.
- */
-export type PollPacing = {
-    /** Cursor to resume from. Stable JSON; hand it back verbatim. */
-    cursor?: EventCursor;
-    /** How long to wait before asking again. Zero once nothing is in flight. */
-    nextPollAfterMs: number;
-    /**
-     * What is left of the turn budget before the gateway gives up on it.
-     *
-     * Present only while this gateway is following the turn itself and can see
-     * its clock, which is the only case where the number means anything. It used
-     * to be sent unconditionally, so a poll of an app with no turn at all
-     * answered with the full budget next to a zero elapsed - a fresh,
-     * fully-funded turn, asserted about nothing (ENG-5808).
-     *
-     * Absent does not mean "nothing is running": a build read out of the
-     * persisted stream reports `building` without a budget, because the turn is
-     * running somewhere this process cannot time it.
-     * {@link PollPacing.nextPollAfterMs} and the status are what say whether to
-     * keep polling.
-     */
-    remainingTurnBudgetMs?: number;
-    /**
-     * Producers whose retained history had already passed the resumed cursor.
-     * Present only when something was actually lost.
-     */
-    staleStreams?: LostEventRange[];
-};
-/**
- * A nonterminal warning that a build has gone quiet, raised well before the
- * turn budget runs out so a caller can say something rather than sit on a
- * silent poll loop until it times out.
- */
-export type StallHint = {
-    /** How long the build has been running without saying anything new. */
-    quietMs: number;
-    reason: "long_quiet";
+    branch?: string;
 };
-export type CheckAppProgressResult = PollPacing & {
+export type CheckAppProgressResult = {
     /** Clark's chat lines since the previous poll, oldest first. */
     activity: string[];
+    /**
+     * Next step for the calling agent, when present. Produced by a host-specific
+     * decision instruction (status needs_decision) or a relay reminder on a
+     * building poll that carried new Superblocks lines.
+     */
+    agentInstructions?: string;
     applicationId: string;
-    /** How long Clark has been on this turn, so a quiet poll still has news. */
-    elapsedSeconds: number;
+    branch?: string;
     /** See StartAppResult.checkpointCommitId. */
     checkpointCommitId?: string;
-    /** Present once the turn has finished. */
-    reply?: string;
+    checkpointFailure?: CheckpointFailure;
+    checkpointWarning?: CheckpointWarning;
     /** Present when status is needs_decision. */
     decision?: DecisionPayload;
     editUrl: string;
+    /** How long Clark has been on this turn, so a quiet poll still has news. */
+    elapsedSeconds: number;
     /** Present once the turn has finished. */
     generationStatus?: GenerationStatus;
-    /** How to retry when the finished turn wrote nothing. */
-    pendingAction?: "retry_build" | "retry_import";
+    /**
+     * Who owes the next move, once the turn is waiting on one. Present on the
+     * polling path as well as on `get_app`, because a host without form
+     * elicitation answers a decision from this loop and nowhere else.
+     */
+    pendingAction?: PendingAppAction;
     /** Recent mid-turn testApi / testIntegration outcomes, oldest first. */
     recentRuns?: RecentToolRun[];
+    /** Present once the turn has finished. */
+    reply?: string;
     /** Emitted once per quiet spell, never in place of a terminal answer. */
     stallHint?: StallHint;
     status: BuildStatus;
-    /** Present once the turn has finished. */
+    /** Whether this turn has produced content the editor can render. */
     viewStatus?: "ready" | "unknown";
 };
+/**
+ * A nonterminal warning that a build has gone quiet so a caller can report
+ * the silence while continuing to poll.
+ */
+export type StallHint = {
+    /** How long the build has been running without saying anything new. */
+    quietMs: number;
+    reason: "long_quiet";
+};
 /**
  * One mid-turn testApi or testIntegration result surfaced to MCP clients.
  * Output/error strings are truncated so tool results stay readable.
@@ -250,6 +275,7 @@ export type RecentToolRun = {
 };
 export type EditAppInput = {
     applicationId?: string;
+    artifacts?: ArtifactDescriptor[];
     branch?: string;
     idempotencyKey: string;
     /** Defaults to PLAN. Approve forces BUILD with planContext.approved. */
@@ -268,10 +294,13 @@ export type EditAppResult = {
     /** Clark's chat lines since the previous report, oldest first. */
     activity?: string[];
     applicationId: string;
+    branch?: string;
     /** Host-driver steer. Tokens never belong here. */
     browser?: BrowserDriverContract;
     /** See StartAppResult.checkpointCommitId. */
     checkpointCommitId?: string;
+    checkpointFailure?: CheckpointFailure;
+    checkpointWarning?: CheckpointWarning;
     /** Absent while the build is still running (`wait: "ack"`). */
     reply?: string;
     /** Present when status is needs_decision. */
@@ -284,6 +313,7 @@ export type EditAppResult = {
      * approved, so the caller can see it does not need to re-send mode.
      */
     mode?: "BUILD" | "PLAN";
+    pendingAction?: PendingAppAction;
     /** Mid-turn testApi / testIntegration outcomes when the turn finished. */
     recentRuns?: RecentToolRun[];
     status: BuildStatus;
@@ -306,6 +336,7 @@ export type PreviewAppInput = {
 };
 export type PreviewAppResult = {
     applicationId: string;
+    branch?: string;
     browser?: BrowserDriverContract;
     /**
      * True when preview URLs are returned but Gateway cannot screenshot because
@@ -314,6 +345,7 @@ export type PreviewAppResult = {
     needsBrowserDriver?: boolean;
     /** Commit that was built and is being previewed. */
     commitId: string;
+    directoryHash: string;
     /** Editor URL for the same app (MCP App Open editor button). */
     editUrl: string;
     /** Display name, so callers can say more than a UUID. Absent when unknown. */
@@ -333,32 +365,30 @@ export type PreviewAppResult = {
      * capture was skipped (still building) or soft-failed.
      */
     screenshotBase64?: string;
+    /** Why a ready preview could not be screenshotted. */
+    screenshotUnavailableReason?: string;
     /**
-     * `building` means the URL is right but SABS has not finished building it
-     * yet; previewing again resumes watching the same build.
+     * `building` means SABS has not finished building this commit yet.
+     * Poll get_preview_status with this commit and directory hash.
      */
     status: "building" | "ready";
 };
+export type PreviewStatusInput = {
+    applicationId: string;
+    branch?: string;
+    commitId: string;
+    directoryHash: string;
+    wait?: boolean;
+};
+export type PreviewStatusResult = PreviewStatusInput & {
+    editUrl: string;
+    status: "building" | "failed" | "ready";
+};
 export type GetAppInput = {
     applicationId?: string;
     branch?: string;
-    /** When true, ensure a preview build exists and return preview URLs. */
-    ensurePreview?: boolean;
-    /**
-     * Whether to wait for the preview build.
-     *
-     * A boolean, and deliberately not the {@link TurnWait} the prompt
-     * capabilities take: this decides how long *this call* blocks on a build,
-     * while `wait: "ack"` decides how far a prompt follows the turn it starts.
-     * Conflating them would make `wait: "ack"` mean something here, where there
-     * is no turn to acknowledge.
-     *
-     * `false` starts or observes the build and returns straight away with
-     * `status: "building"` and pacing to poll on. `true` (the default) waits,
-     * but never past the host's tool-call ceiling — it returns `building` with
-     * the same pacing rather than holding the call open.
-     */
-    wait?: boolean;
+    /** Whether to capture a screenshot. Defaults to true. */
+    includeScreenshot?: boolean;
 };
 /**
  * What has to happen before this app has anything worth previewing. Present
@@ -366,20 +396,37 @@ export type GetAppInput = {
  * says why.
  */
 export type PendingAppAction = 
+/** Superblocks requested a datasource the MCP host must create. */
+"create_integration"
 /** Clark asked a multi_choice question; answer it with `edit_app`. */
-"answer_question"
+ | "answer_question"
 /** Clark proposed a plan; `edit_app` with `planAction: "approve"` builds it. */
  | "approve_plan"
+/**
+ * Clark is waiting on the user, and the gateway cannot say what it is
+ * asking: the turn ended on a decision it streamed as ordinary chat text,
+ * so nothing structured was captured and no plan was remembered either.
+ *
+ * A distinct value because the alternative was reporting `answer_question`
+ * with no question attached, which told the caller to put a decision to the
+ * user that it had no way to see - and re-reading only returned the same
+ * thing (ENG-5910). The honest answer is that this one has to be finished in
+ * the editor.
+ */
+ | "decide_in_editor"
+/** The build finished, but its checkpoint failed; inspect it in the editor. */
+ | "open_editor"
+/** A newly created app is wedged; recreate it with `start_app`. */
+ | "start_new_app"
 /** The last turn ended without writing anything; `edit_app` starts it over. */
  | "retry_build"
-/** The import failed before writing anything; `import_app` retries it. */
- | "retry_import"
 /** A turn is in flight; follow it with `check_app_progress`. */
  | "wait_for_build";
-export type GetAppResult = Partial<PollPacing> & {
+export type GetAppResult = {
     applicationId: string;
+    branch?: string;
     browser?: BrowserDriverContract;
-    commitId?: string;
+    checkpointFailure?: CheckpointFailure;
     /** The question or plan Clark is waiting on, when status is needs_decision. */
     decision?: DecisionPayload;
     editUrl: string;
@@ -388,16 +435,41 @@ export type GetAppResult = Partial<PollPacing> & {
     openableViaHttps?: boolean;
     /** Set whenever no preview was built; says what unblocks one. */
     pendingAction?: PendingAppAction;
+    /** Why the last turn left nothing to preview, when that reason is known. */
+    reply?: string;
     needsBrowserDriver?: boolean;
+    /** Live editor preview opened in fullscreen mode. */
     previewUrl?: string;
     publishUrl?: string;
     screenshotBase64?: string;
+    screenshotUnavailableReason?: string;
     /**
      * `cancelled`, `live_edit_terminated`, `no_changes` and `timeout` mean the
      * last turn left nothing to show, so no preview was built for it.
      */
-    status: "building" | "cancelled" | "live_edit_terminated" | "needs_decision" | "no_changes" | "ready" | "timeout" | "unknown";
-    viewerUrl?: string;
+    status: "building" | "cancelled" | "checkpoint_failed" | "detached" | "live_edit_terminated" | "needs_decision" | "no_changes" | "ready" | "timeout";
+};
+export type AskUserInput = {
+    applicationId?: string;
+    branch?: string;
+};
+/**
+ * What the decision card renders. The card cannot read AppState, so the plan
+ * or question travels here in full — a form built from a summary would ask the
+ * user to approve something other than what Superblocks proposed.
+ */
+export type AskUserResult = {
+    applicationId: string;
+    branch?: string;
+    /** Absent when nothing is waiting on the user; `status` says what is. */
+    decision?: DecisionPayload;
+    editUrl: string;
+    /** Display name, so the card says more than a UUID. */
+    name?: string;
+    pendingAction?: PendingAppAction;
+    /** Superblocks' own words on the turn that stopped. */
+    reply?: string;
+    status: BuildStatus;
 };
 export type PublishAppInput = {
     applicationId?: string;
@@ -406,21 +478,46 @@ export type PublishAppInput = {
     idempotencyKey: string;
     prompt: string;
 };
+export type CheckPublishProgressInput = {
+    applicationId?: string;
+    /**
+     * Which commit's deploy to follow. Defaults to the one `publish_app` queued
+     * for this application, so a caller that did not carry the id back can still
+     * follow its own publish.
+     */
+    commitId?: string;
+};
 export type PublishAppResult = {
     applicationId: string;
     commitId: string;
-    /** Present when the deploy response carried an id. */
-    deploymentId?: string;
+    /** How long the rollout has been running, so a quiet poll still has news. */
+    elapsedSeconds?: number;
+    publishDetailsUrl: string;
     publishUrl: string;
-    status: "deployed";
+    /**
+     * `deployed` once the app is live. `publishing` means the deploy was
+     * accepted and is still running: the publish itself succeeded, and only the
+     * rollout is outstanding. It used to be reported as a `publish_timeout`
+     * error, because the call blocked on the rollout until it outlived the
+     * host's tool-call ceiling (ENG-6172).
+     */
+    status: "deployed" | "publishing";
 };
 /**
- * Gateway MCP/HTTP import rejects archives above this size. Larger ZIPs almost
- * certainly include `node_modules` (or similar); those belong outside the
- * export — deps are installed on or after import. Stricter than the browser
- * migration UI (50 MB) on purpose.
+ * Gateway MCP/HTTP import rejects archives above this size, matching the
+ * Superblocks archive attachment upload cap. Larger ZIPs often include
+ * `node_modules` (or similar); those belong outside the export — deps are
+ * installed on or after import.
+ */
+export declare const IMPORT_ZIP_MAX_BYTES: number;
+/**
+ * Ceiling on inline `files` payloads, which the model writes out itself rather
+ * than naming a file the gateway reads. It stays well below
+ * {@link IMPORT_ZIP_MAX_BYTES} for the same reason `zipBase64` does: an archive
+ * cap sized for bytes on disk is meaningless for content a model has to emit
+ * one token at a time.
  */
-export declare const IMPORT_ZIP_MAX_BYTES = 1048576;
+export declare const IMPORT_SOURCE_FILES_MAX_BYTES = 1048576;
 /**
  * Ceiling on an inline `zipBase64` payload, far below
  * {@link IMPORT_ZIP_MAX_BYTES} because base64 is not a transport a model can
@@ -430,22 +527,3 @@ export declare const IMPORT_ZIP_MAX_BYTES = 1048576;
  * carries test fixtures.
  */
 export declare const IMPORT_ZIP_BASE64_MAX_CHARS = 8192;
-/** Third-party import source ids Clark uses for migration prompts and billing. */
-export type ImportAppSource = "chatgpt" | "claude" | "claude-design" | "lovable" | "replit" | "streamlit" | "v0" | "zip";
-export type ImportAppInput = {
-    applicationId?: string;
-    branch?: string;
-    idempotencyKey: string;
-    /** Defaults to PLAN. */
-    mode?: "BUILD" | "PLAN";
-    name?: string;
-    /** Extra intent appended after the migration template (e.g. harden security). */
-    prompt?: string;
-    source?: ImportAppSource | string;
-    wait?: TurnWait;
-    /** Absolute path on the gateway host; mutually exclusive with zipBase64. */
-    zipBase64?: string;
-    zipPath?: string;
-};
-/** Same shape as {@link StartAppResult}: import creates an app then starts Clark. */
-export type ImportAppResult = StartAppResult;

package/dist/capabilities/types.js

@@ -6,7 +6,10 @@
  * added later, which is how a dead live edit came to be reported as `ready`
  * in the first place; this way the compiler stops the next one.
  */
-export function buildStatusOf(generationStatus) {
+export function buildStatusOf(generationStatus, checkpointFailure) {
+    if (checkpointFailure) {
+        return "checkpoint_failed";
+    }
     switch (generationStatus) {
         case "cancelled":
             return "cancelled";
@@ -29,12 +32,48 @@ export function buildStatusOf(generationStatus) {
     }
 }
 /**
- * Gateway MCP/HTTP import rejects archives above this size. Larger ZIPs almost
- * certainly include `node_modules` (or similar); those belong outside the
- * export — deps are installed on or after import. Stricter than the browser
- * migration UI (50 MB) on purpose.
+ * How a `check_app_progress` poll reads as a build status.
+ *
+ * Running and unknown map directly. A finished poll uses {@link buildStatusOf},
+ * except a successful checkpoint that paused for missing integrations: that is
+ * a decision, even when generationStatus is still `completed`.
+ */
+export function progressStatusOf(update) {
+    switch (update.status) {
+        case "running":
+            return "building";
+        case "unknown":
+            return "unknown";
+        case "finished":
+            return finishedProgressStatus(update);
+        default: {
+            const unhandled = update;
+            return unhandled;
+        }
+    }
+}
+function finishedProgressStatus(update) {
+    if (!update.checkpointFailure &&
+        update.decision?.kind === "missing_integrations") {
+        return "needs_decision";
+    }
+    return buildStatusOf(update.generationStatus, update.checkpointFailure);
+}
+/**
+ * Gateway MCP/HTTP import rejects archives above this size, matching the
+ * Superblocks archive attachment upload cap. Larger ZIPs often include
+ * `node_modules` (or similar); those belong outside the export — deps are
+ * installed on or after import.
+ */
+export const IMPORT_ZIP_MAX_BYTES = 50 * 1024 * 1024;
+/**
+ * Ceiling on inline `files` payloads, which the model writes out itself rather
+ * than naming a file the gateway reads. It stays well below
+ * {@link IMPORT_ZIP_MAX_BYTES} for the same reason `zipBase64` does: an archive
+ * cap sized for bytes on disk is meaningless for content a model has to emit
+ * one token at a time.
  */
-export const IMPORT_ZIP_MAX_BYTES = 1_048_576;
+export const IMPORT_SOURCE_FILES_MAX_BYTES = 1_048_576;
 /**
  * Ceiling on an inline `zipBase64` payload, far below
  * {@link IMPORT_ZIP_MAX_BYTES} because base64 is not a transport a model can

package/dist/capabilities/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capabilities/types.ts"],"names":[],"mappings":"AA0HA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,gBAAkC;IAC9D,QAAQ,gBAAgB,EAAE,CAAC;QACzB,KAAK,WAAW;YACd,OAAO,WAAW,CAAC;QACrB,KAAK,WAAW;YACd,OAAO,OAAO,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,sBAAsB;YACzB,OAAO,sBAAsB,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,gBAAgB,CAAC;QAC1B,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,SAAS,GAAU,gBAAgB,CAAC;YAC1C,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AA6UD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capabilities/types.ts"],"names":[],"mappings":"AA8JA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,gBAAkC,EAClC,iBAAqC;IAErC,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IACD,QAAQ,gBAAgB,EAAE,CAAC;QACzB,KAAK,WAAW;YACd,OAAO,WAAW,CAAC;QACrB,KAAK,WAAW;YACd,OAAO,OAAO,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,sBAAsB;YACzB,OAAO,sBAAsB,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,gBAAgB,CAAC;QAC1B,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,SAAS,GAAU,gBAAgB,CAAC;YAC1C,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,UAAU,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,SAAS,GAAU,MAAM,CAAC;YAChC,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAC7B,MAAmD;IAEnD,IACE,CAAC,MAAM,CAAC,iBAAiB;QACzB,MAAM,CAAC,QAAQ,EAAE,IAAI,KAAK,sBAAsB,EAChD,CAAC;QACD,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,aAAa,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1E,CAAC;AAuYD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC"}