@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/capabilities/types.d.ts

@@ -0,0 +1,542 @@
+import type { BrowserDriverContract } from "../capture/browser-contract.js";
+import type { CheckpointFailure, CheckpointWarning, TurnUpdate } from "../sabs/session-peer.js";
+export type CallerKind = "mcp";
+/**
+ * The caller behind a capability invocation.
+ *
+ * Identity is optional because MCP hands over only the credential and lets the
+ * capability resolve it. Whoever resolves it, it is resolved exactly once —
+ * `/users/me` is the most expensive endpoint the Superblocks API exposes.
+ */
+export type Principal = {
+    apiKey: string;
+    email?: string;
+    organizationId?: string;
+    userId?: string;
+};
+/** A principal whose identity the Superblocks API has confirmed. */
+export type ResolvedPrincipal = Principal & {
+    organizationId: string;
+    userId: string;
+};
+export type ProgressEvent = {
+    message: string;
+    type: "progress" | "auth_required" | "completed" | "error";
+};
+export type AuthElicitation = {
+    authUrl: string;
+    browser?: BrowserDriverContract;
+    reason: "idp_step_up";
+    turnId: string;
+};
+/**
+ * A failed capability, and the application it was working on when it failed.
+ *
+ * `start_app` persists an application row before it ever reaches live edit, so
+ * a failure past that point leaves the caller owning a resource it was never
+ * handed. `applicationId` is that handle, and it is a field because the
+ * alternative callers actually resorted to — regex a UUID out of `message`, or
+ * else fall back to "the most recent app" — drives another caller's build in
+ * 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 the host has a concrete way to recover from this failure. */
+    pendingAction?: PendingAppAction;
+};
+export type CapabilityResult<T> = {
+    kind: "ok";
+    value: T;
+} | {
+    kind: "auth_required";
+    elicitation: AuthElicitation;
+} | CapabilityError;
+export type GenerationStatus = "cancelled" | "completed"
+/**
+ * Clark took the prompt but pushes nothing the gateway can see, so its
+ * progress is only visible in the editor. The job itself keeps running.
+ */
+ | "detached"
+/**
+ * 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. 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. */
+ | "no_changes" | "needs_decision" | "timeout";
+/**
+ * How far a `start_app` / `edit_app` call follows the turn it starts.
+ *
+ * - `turn`: block until Clark's job is done (HTTP).
+ * - `ack`: return as soon as Clark accepts the prompt and let the caller follow
+ *   the build through `check_app_progress`. The only way an MCP client that
+ *   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;
+};
+/**
+ * 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" | "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.
+ */
+ | "detached"
+/**
+ * The live-edit session backing the turn died before it finished, or never
+ * opened. Nothing was built, and the caller should retry rather than keep
+ * polling.
+ */
+ | "live_edit_terminated" | "needs_decision"
+/** Clark's job ended having built nothing; there is no app to show. */
+ | "no_changes" | "ready" | "timeout" | "unknown";
+/**
+ * How a finished turn reads as a build status.
+ *
+ * Every member is spelled out and the default is unreachable on purpose. A
+ * `default: return "ready"` would answer "your app is fine" for any status
+ * 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, 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[];
+    question: string;
+} | {
+    kind: "plan";
+    messageId?: string;
+    plan: string;
+    title?: string;
+};
+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;
+    /**
+     * Checkpoint the gateway committed for Clark's work. Absent when Clark left
+     * 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. */
+    decision?: DecisionPayload;
+    editUrl: string;
+    /** Absent while the build is still running (`wait: "ack"`). */
+    generationStatus?: GenerationStatus;
+    liveEditId?: string;
+    /** 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;
+    /** Absent while the build is still running (`wait: "ack"`). */
+    viewStatus?: "ready" | "unknown";
+};
+export type CheckAppProgressInput = {
+    applicationId?: string;
+    branch?: string;
+};
+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;
+    branch?: string;
+    /** See StartAppResult.checkpointCommitId. */
+    checkpointCommitId?: 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;
+    /**
+     * 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[];
+    /**
+     * 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.
+     */
+    remainingTurnBudgetMs?: number;
+    /** Present once the turn has finished. */
+    reply?: string;
+    /** Emitted once per quiet spell, never in place of a terminal answer. */
+    stallHint?: StallHint;
+    status: BuildStatus;
+    /** Whether this turn has produced content the editor can render. */
+    viewStatus?: "ready" | "unknown";
+};
+/**
+ * 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";
+};
+/**
+ * One mid-turn testApi or testIntegration result surfaced to MCP clients.
+ * Output/error strings are truncated so tool results stay readable.
+ */
+export type RecentToolRun = {
+    kind: "test_api" | "test_integration";
+    name: string;
+    success: boolean;
+    summary: string;
+    at: string;
+};
+export type EditAppInput = {
+    applicationId?: string;
+    artifacts?: ArtifactDescriptor[];
+    branch?: string;
+    idempotencyKey: string;
+    /** Defaults to PLAN. Approve forces BUILD with planContext.approved. */
+    mode?: "BUILD" | "PLAN";
+    /**
+     * Approve or refine a pending Clark plan. When omitted and a plan is pending,
+     * a normal prompt is treated as refine feedback. `approve` does not need a
+     * prompt — the pending plan is sent as the build prompt.
+     */
+    planAction?: "approve" | "refine";
+    /** Required unless `planAction` is `approve`. */
+    prompt?: string;
+    wait?: TurnWait;
+};
+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. */
+    decision?: DecisionPayload;
+    editUrl: string;
+    /** Absent while the build is still running (`wait: "ack"`). */
+    generationStatus?: GenerationStatus;
+    /**
+     * Mode this turn actually ran in. Follow-ups stay BUILD once a plan was
+     * 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;
+    /** Absent while the build is still running (`wait: "ack"`). */
+    viewStatus?: "ready" | "unknown";
+};
+export type PreviewAppInput = {
+    applicationId?: string;
+    branch?: string;
+    /**
+     * Capture a deployed-shell screenshot when the preview is ready. `get_app`
+     * sets this false when it will screenshot the live library instead.
+     */
+    includeScreenshot?: boolean;
+    /**
+     * Whether to wait for the build. See {@link GetAppInput.wait}; `false`
+     * starts or observes the build and returns `status: "building"` at once.
+     */
+    wait?: boolean;
+};
+export type PreviewAppResult = {
+    applicationId: string;
+    branch?: string;
+    browser?: BrowserDriverContract;
+    /**
+     * True when preview URLs are returned but Gateway cannot screenshot because
+     * there is no Chromium and no host browser MCP.
+     */
+    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. */
+    name?: string;
+    previewUrl: string;
+    /**
+     * Direct viewer URL used for screenshots (may be http localhost even when
+     * `previewUrl` is an https gateway redirect).
+     */
+    viewerUrl?: string;
+    /**
+     * True when `previewUrl` is https and Claude Desktop can openLink it.
+     */
+    openableViaHttps?: boolean;
+    /**
+     * Base64 JPEG of the running preview when capture succeeds. Absent when
+     * 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.
+     */
+    status: "building" | "ready";
+};
+export type PreviewStatusInput = {
+    applicationId: string;
+    branch?: string;
+    commitId: string;
+    directoryHash: string;
+};
+export type PreviewStatusResult = PreviewStatusInput & {
+    editUrl: string;
+    status: "building" | "failed" | "ready";
+};
+export type GetAppInput = {
+    applicationId?: string;
+    branch?: string;
+    /** Whether to capture a screenshot. Defaults to true. */
+    includeScreenshot?: boolean;
+};
+/**
+ * What has to happen before this app has anything worth previewing. Present
+ * only when the gateway declined to build one, and paired with the status that
+ * 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"
+/** 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"
+/** A turn is in flight; follow it with `check_app_progress`. */
+ | "wait_for_build";
+export type GetAppResult = {
+    applicationId: string;
+    branch?: string;
+    browser?: BrowserDriverContract;
+    checkpointFailure?: CheckpointFailure;
+    /** The question or plan Clark is waiting on, when status is needs_decision. */
+    decision?: DecisionPayload;
+    editUrl: string;
+    /** Display name, so callers can say more than a UUID. Absent when unknown. */
+    name?: string;
+    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" | "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;
+    branch?: string;
+    commitId?: string;
+    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;
+    /** How long the rollout has been running, so a quiet poll still has news. */
+    elapsedSeconds?: number;
+    publishDetailsUrl: string;
+    publishUrl: string;
+    /**
+     * `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, 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_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
+ * afford: every 3 bytes of archive cost 4 characters it has to write out one
+ * token at a time, so even a 42 KB export runs to 57,000 characters and the
+ * tool call never gets sent. Real archives arrive by name — this size only
+ * carries test fixtures.
+ */
+export declare const IMPORT_ZIP_BASE64_MAX_CHARS = 8192;

package/dist/capabilities/types.js

@@ -0,0 +1,86 @@
+/**
+ * How a finished turn reads as a build status.
+ *
+ * Every member is spelled out and the default is unreachable on purpose. A
+ * `default: return "ready"` would answer "your app is fine" for any status
+ * 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, checkpointFailure) {
+    if (checkpointFailure) {
+        return "checkpoint_failed";
+    }
+    switch (generationStatus) {
+        case "cancelled":
+            return "cancelled";
+        case "completed":
+            return "ready";
+        case "detached":
+            return "detached";
+        case "live_edit_terminated":
+            return "live_edit_terminated";
+        case "needs_decision":
+            return "needs_decision";
+        case "no_changes":
+            return "no_changes";
+        case "timeout":
+            return "timeout";
+        default: {
+            const unhandled = generationStatus;
+            return unhandled;
+        }
+    }
+}
+/**
+ * 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_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
+ * afford: every 3 bytes of archive cost 4 characters it has to write out one
+ * token at a time, so even a 42 KB export runs to 57,000 characters and the
+ * tool call never gets sent. Real archives arrive by name — this size only
+ * carries test fixtures.
+ */
+export const IMPORT_ZIP_BASE64_MAX_CHARS = 8_192;
+//# sourceMappingURL=types.js.map

package/dist/capabilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capabilities/types.ts"],"names":[],"mappings":"AA6JA;;;;;;;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;AAqZD;;;;;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"}

package/dist/capture/browser-contract.d.ts

@@ -0,0 +1,46 @@
+import type { CaptureMode } from "./mode.js";
+/** The host drives its own embedded browser; no driver MCP is involved. */
+export declare const HOST_BROWSER_TOOLS_COWORK: "cowork_embedded";
+/**
+ * Nobody looked, rather than nobody found one. The setup-time config scan
+ * behind {@link CaptureMode} can lie, so only a transport that knows which
+ * client is connected may say anything more definite than this.
+ */
+export declare const HOST_BROWSER_TOOLS_UNKNOWN: "unknown";
+export type HostBrowserTools = typeof HOST_BROWSER_TOOLS_COWORK | typeof HOST_BROWSER_TOOLS_UNKNOWN;
+export declare const MUST_NOT_CLOSE_UNTIL = "the Superblocks task is done (status ready, or the user no longer needs the browser session)";
+export declare const NEEDS_BROWSER_DRIVER_CODE = "needs_browser_driver";
+export declare const NEEDS_BROWSER_DRIVER_MESSAGE = "No browser driver is available for live-canvas capture or IdP step-up. Add a host browser MCP (@playwright/mcp) and re-run mcp setup. Gateway Chromium cannot complete IdP. Config on disk can lie if a listed server fails to start.";
+/**
+ * Structured steer for host browser tools. Tokens never belong here.
+ *
+ * The edit URL may stay open while building only in Claude Cowork's built-in
+ * side panel. Other browser drivers can steal the live-edit turn by opening it.
+ */
+export type BrowserDriverContract = {
+    captureMode: CaptureMode;
+    canvas: {
+        editUrl: string;
+        openWhileBuilding: "claude_cowork_side_panel_only";
+    };
+    driver: {
+        isolated?: boolean;
+        mustNotCloseUntil: string;
+    };
+    hostBrowserTools: HostBrowserTools;
+    uiOrigin: {
+        navigate: string;
+    };
+};
+export declare function buildBrowserDriverContract(input: {
+    captureMode: CaptureMode;
+    editUrl: string;
+    hostBrowserTools?: HostBrowserTools;
+    isolated?: boolean;
+    uiOrigin: string;
+}): BrowserDriverContract;
+export declare function needsBrowserDriverError(): {
+    code: typeof NEEDS_BROWSER_DRIVER_CODE;
+    kind: "error";
+    message: string;
+};