@superblocksteam/gateway 2.0.161 → 2.0.162-next.0

package/README.md

@@ -3,13 +3,14 @@
 Standalone Superblocks entry point for a **single MCP connector** (Admin + Builder)
 over **stdio**, running as the already-logged-in Superblocks CLI user.
 
-Builder tools (`start_app`, `import_app`, `edit_app`, `check_app_progress`,
-`get_app`, `get_integration_metadata`, `preview_app`, `publish_app`) plus
-customer Admin tools from `@superblocksteam/mcp-server` share this process.
-
-The MCP host owns process lifecycle: it spawns `superblocks gateway serve`.
-There is no foreground HTTP `/mcp`, no OAuth resource server, and no linked-grant
-exchange. Personal API keys here are the CLI session
+Builder tools (`upload_artifact`, `start_app`, `edit_app`,
+`check_app_progress`, `ask_user`, `get_app`, `build_app`,
+`get_preview_status`, `get_integration_metadata`, `publish_app`) plus customer
+Admin tools from `@superblocksteam/mcp-server` share this process.
+
+The MCP host owns process lifecycle: it spawns `superblocks mcp serve`. The
+unified Gateway has no foreground HTTP `/mcp`, no OAuth resource server, and no
+linked-grant exchange. Personal API keys here are the CLI session
 (`~/.superblocks/auth.json` / `SUPERBLOCKS_AUTH_FILE` / `just worktree auth`).
 
 Scope notes:
@@ -22,6 +23,56 @@ Scope notes:
 - No Slack wrapper (ENG-5596).
 - Orchestrator URL is discovered from Server agent inventory, not configured here.
 
+## Claude Code plugin
+
+Add the Superblocks marketplace and install the plugin from inside Claude Code:
+
+```text
+/plugin marketplace add https://unpkg.com/@superblocksteam/cli@beta/.claude-plugin/marketplace.json
+/plugin install superblocks@superblocks
+```
+
+The plugin includes Gateway and the `superblocks-import` skill. When prompted,
+enter a Superblocks personal API key and your Superblocks instance URL. Claude
+stores the API key in secure storage. The npm-backed plugin requires Node.js 24
+or newer and npm 10 or newer.
+
+## Claude Cowork plugin
+
+For a local desktop Cowork session:
+
+1. Install Node.js 24 or newer and npm 10 or newer.
+2. Download [the Cowork plugin](https://unpkg.com/@superblocksteam/cli@beta/dist/superblocks.plugin).
+3. Open `Customize > Plugins`, choose upload, and select the plugin file.
+4. Enter a Superblocks personal API key and your Superblocks instance URL.
+
+The plugin starts Gateway on the desktop. It is unavailable in cloud Cowork
+sessions, which cannot run local MCP servers.
+
+### Organization-managed rollout
+
+Owners and Primary Owners on Team and Enterprise plans can distribute the
+plugin from `Organization settings > Plugins`:
+
+1. Enable Cowork and Skills for the organization.
+2. Save a copy of `superblocks.plugin` with a `.zip` suffix. Organization
+   uploads require a valid `.zip` smaller than 50 MB.
+3. Choose `Add plugins > Upload a file`, then create a marketplace or add the
+   archive to an existing one.
+4. Set the plugin to `Installed by default` or `Required` and confirm its
+   version in the marketplace.
+
+Upload a new archive with the same plugin name to replace the current version.
+Members receive it on their next session or plugin refresh. To deprecate it, set
+it to `Not available`; to remove it, delete it from the marketplace. Rollback
+behavior is not documented by Anthropic; validate re-uploading a retained older
+archive in a test marketplace before relying on it.
+
+Superblocks supplies the archive and Gateway runtime. Claude organization Owners
+control marketplace distribution and installation policy. Each member supplies
+their Superblocks credentials; each desktop still needs Node.js, npm, and
+permission to run local MCP servers. See [Anthropic's organization plugin guide](https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization).
+
 ## Internal review
 
 ```bash
@@ -29,26 +80,38 @@ Scope notes:
 superblocks login
 
 # Write a stdio MCP entry into the client config
-superblocks gateway setup --client claude
+superblocks mcp setup --client claude
 # or: --client cursor / --client claude-desktop / --client generic
 
-# Restart the MCP host. It spawns Gateway; do not run gateway serve yourself.
+# Restart the MCP host. It spawns Gateway; do not run mcp serve yourself.
 ```
 
+`--client claude` also copies `skills/superblocks-import/SKILL.md` to
+`~/.claude/skills/superblocks-import/`. `--client cursor` copies it to
+`~/.cursor/skills/superblocks-import/`. Claude Desktop and generic clients
+have no Agent Skills dir; they rely on the short MCP migration fallback.
+Restart the host after setup so skills reload.
+
 `setup` writes an absolute spawn so the host does not depend on cwd.
 Published `bin/run.js` is the MCP `command` (its `node` shebang applies).
 Worktree `bin/dev.js` is launched with `tsx` and without `--watch`: the
 dev shebang is a file-watcher, which would kill stdio on source edits and
-corrupt JSON-RPC on stdout. When `SUPERBLOCKS_AUTH_FILE` or
-`SUPERBLOCKS_BASE_URL` is set (worktree auth), those are copied into the MCP
-`env` block.
+corrupt JSON-RPC on stdout. When `SUPERBLOCKS_AUTH_FILE` is set (worktree
+auth), it is copied into the MCP `env` block. Gateway derives both control
+plane and remote UI URLs from `superblocksBaseUrl` in that auth file.
 
-Optional: `--with-screenshots` downloads Playwright Chromium for preview
-captures. Omit it; start still succeeds.
+Optional: `mcp setup --with-screenshots` downloads Playwright Chromium for
+preview captures. Omit it; MCP setup still succeeds.
 
 ## Local run
 
-The MCP host spawns Gateway. Do not run `gateway serve` in a TTY.
+The MCP host spawns Gateway's default stdio transport. Do not run `mcp serve`
+without `--transport http` in a TTY. The legacy Admin-only HTTP transport
+remains available for compatibility:
+
+```bash
+SUPERBLOCKS_MCP_HTTP_TOKEN=<token> superblocks mcp serve --transport http --port 8484
+```
 
 Against a remote Superblocks domain (EE / SaaS IR):
 
@@ -56,13 +119,14 @@ Against a remote Superblocks domain (EE / SaaS IR):
 cd packages/cli/packages/cli
 ./bin/dev.js config set domain <host>
 ./bin/dev.js login
-./bin/dev.js gateway setup --client claude
+./bin/dev.js mcp setup --client claude
 ```
 
 Against a local control plane, start the stack first (`just up <worktree>`),
-then login and `gateway setup` the same way.
+then login and `mcp setup` the same way.
 
-`superblocks mcp serve` (stdio Admin-only) is deprecated; prefer `gateway setup`.
+The standalone `superblocks-mcp` Admin-only server is deprecated; prefer
+`superblocks mcp setup`.
 
 ## Worktree MCP (Cursor / Claude)
 
@@ -73,7 +137,7 @@ Log in and run setup from the worktree CLI (not a globally installed `superblock
 cd packages/cli/packages/cli
 ./bin/dev.js config set domain <host>
 ./bin/dev.js login
-./bin/dev.js gateway setup --client cursor
+./bin/dev.js mcp setup --client cursor
 # or: --client claude
 ```
 
@@ -87,12 +151,11 @@ for Cursor, `~/.claude.json` for Claude Code):
       "command": "/absolute/path/to/tsx/cli.mjs",
       "args": [
         "/absolute/path/to/packages/cli/packages/cli/bin/dev.js",
-        "gateway",
+        "mcp",
         "serve"
       ],
       "env": {
-        "SUPERBLOCKS_AUTH_FILE": "/absolute/path/to/worktree/.superblocks/auth.json",
-        "SUPERBLOCKS_BASE_URL": "https://your-control-plane"
+        "SUPERBLOCKS_AUTH_FILE": "/absolute/path/to/worktree/.superblocks/auth.json"
       }
     }
   }
@@ -101,8 +164,9 @@ for Cursor, `~/.claude.json` for Claude Code):
 
 `command` is `tsx` without `--watch`: the `bin/dev.js` shebang is a file
 watcher, which would kill stdio on source edits and corrupt JSON-RPC on
-stdout. `env` only copies the CLI session (`SUPERBLOCKS_AUTH_FILE`,
-`SUPERBLOCKS_BASE_URL`). Do not add `SUPERBLOCKS_GATEWAY_FROM_SOURCE`.
+stdout. `env` only copies the worktree CLI session path
+(`SUPERBLOCKS_AUTH_FILE`). Gateway reads `superblocksBaseUrl` from that file.
+Do not add `SUPERBLOCKS_GATEWAY_FROM_SOURCE`.
 Optional stderr tees (`2>> ~/.cursor/superblocks-gateway.err`) are host
 specific; `setup` does not write them.
 
@@ -146,11 +210,43 @@ package only the customer Admin surface. Builder tools are not registered.
 
 ## MCP tools
 
-After `gateway setup`, restart Claude Code or Cursor and call `start_app`,
-`edit_app`, `check_app_progress`, `get_app`, `get_integration_metadata`,
-`preview_app`, and `publish_app`. `get_integration_metadata` reads tables,
-columns, and types from a connected integration; use `search`, `limit`, and
-`offset` for large results. It needs no application: without one it mints an
+After `mcp setup`, restart Claude Code or Cursor and call `upload_artifact`,
+`start_app`, `edit_app`, `check_app_progress`, `ask_user`, `get_app`,
+`build_app`, `get_preview_status`, `get_integration_metadata`, and
+`publish_app`.
+
+`upload_artifact` accepts any file the gateway can read through `filePath` -
+an archive, an image, a PDF, or a log - or source the MCP client is writing out
+itself through `files: [{ path, content }]`. `files` is archived as text, so
+binary belongs on the `filePath` route, where the bytes never pass through the
+model. Pass its returned artifact to `start_app` or `edit_app`; retries reuse
+the same artifact and application IDs.
+
+`ask_user` is what a turn ending on a plan or a question goes through. Hosts
+with form elicitation never need it - `check_app_progress` puts the decision as
+a native picker and answers Superblocks itself. Hosts without one (Claude
+Desktop) get an MCP App: the plan with Build it / Change something beside it, or
+the question with a button per option. The answer is posted back as the user's
+own message (`ui/message`), so the host's agent loop continues as if they had
+typed it. The decision is in the tool result as data either way, and the server
+instructions require the host to write it out in chat as well - a host that
+renders the card shows it instead of the tool text, and one that renders nothing
+shows only the text.
+
+`get_app` returns the current live development view without creating a commit or
+starting a build. `build_app` is the explicit versioned-preview operation: use
+it only when the user asks to build a commit preview, never automatically after
+`start_app`, `edit_app`, or `get_app`. It creates a commit and starts or reuses
+the build for that content, but does not publish the app or change its
+permissions. If it returns `building`, carry its `applicationId`, `commitId`,
+`directoryHash`, and optional `branch` into `get_preview_status`; do not call
+`build_app` again to poll. The original `previewUrl` is the URL to use once the
+status becomes `ready`. Call `publish_app` only when the user explicitly asks
+to deploy the app.
+
+`get_integration_metadata` reads tables, columns, and types from a connected
+integration; use `search`, `limit`, and `offset` for large results. It needs no
+application: without one it mints an
 `integrations:build` token scoped to that single integration. Pass
 `applicationId` only for an integration owned by one application, such as a
 Native DB, which is invisible without app context.
@@ -159,25 +255,25 @@ the org-wide lookup by id, so it answers `integration_not_permitted` without
 build permission on that integration and `integration_not_supported` for a
 plugin Clark cannot use as a tool.
 `get_integration_config_schema` is the create-integration form, not live data.
-See `.env.example` for optional configuration.
 
 ## Env
 
 See `.env.example`. Stores are in-memory only. Identity comes from the CLI
 session, not from these variables.
 
-| Variable                   | Purpose                                                    |
-| -------------------------- | ---------------------------------------------------------- |
-| `SUPERBLOCKS_SERVER_URL`   | Control plane URL (default from `auth.json` or localhost). |
-| `GATEWAY_PROFILE_KEY`      | Integration profile key (default `default`).               |
-| `GATEWAY_LOCAL_AGENT`      | Cloud-Prem laptop agent mode.                              |
-| `GATEWAY_ADMIN_TOOLS_ONLY` | Admin tools only; skip Builder surface.                    |
-| `SUPERBLOCKS_AUTH_FILE`    | Worktree-local CLI session (from `just worktree auth`).    |
-| `NODE_DEBUG=gateway`       | Tool call stacks and conditional-flow logs on stderr.      |
+| Variable                     | Purpose                                                    |
+| ---------------------------- | ---------------------------------------------------------- |
+| `SUPERBLOCKS_SERVER_URL`     | Control plane URL (default from `auth.json` or localhost). |
+| `GATEWAY_PROFILE_KEY`        | Integration profile key (default `default`).               |
+| `GATEWAY_LOCAL_AGENT`        | Cloud-Prem laptop agent mode.                              |
+| `GATEWAY_ADMIN_TOOLS_ONLY`   | Admin tools only; skip Builder surface.                    |
+| `GATEWAY_IMPORT_SEARCH_DIRS` | Fallback folders for bare or sandbox attachment paths.     |
+| `SUPERBLOCKS_AUTH_FILE`      | Worktree-local CLI session (from `just worktree auth`).    |
+| `NODE_DEBUG=gateway`         | Tool call stacks and conditional-flow logs on stderr.      |
 
 Gateway debug logs include tool names, result states, decision branches, and
 entry-point stacks. They intentionally omit credentials, prompts, answers, and
-result payloads. Run `superblocks gateway setup --client <client> --debug`, then
+result payloads. Run `superblocks mcp setup --client <client> --debug`, then
 restart the MCP host. Re-run setup without `--debug` to turn them off.
 
 ## Remote traceability

package/dist/capabilities/lifecycle.d.ts

@@ -1,32 +1,24 @@
+import { type HostBrowserTools } from "../capture/browser-contract.js";
 import type { CaptureLibraryScreenshot } from "../capture/capture-library.js";
 import type { GatewayConfig } from "../config.js";
-import type { EventStore } from "../events/types.js";
-import type { CapturePreviewScreenshot } from "../preview/capture-screenshot.js";
-import type { CallerRef, ProgressStore, RecentAppStore, TurnStore } from "../resume/types.js";
-import type { SessionPeer } from "../sabs/session-peer.js";
+import { type CapturePreviewScreenshot } from "../preview/capture-screenshot.js";
+import type { AppState } from "../sabs/app-state.js";
+import { type SessionPeer } from "../sabs/session-peer.js";
 import type { SuperblocksServerClient } from "../server/client.js";
-import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, EditAppInput, EditAppResult, GetAppInput, GetAppResult, ImportAppInput, ImportAppResult, PreviewAppInput, PreviewAppResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, ResolvedPrincipal, StartAppInput, StartAppResult } from "./types.js";
+import type { ProgressStore, RecentAppStore, StepUpTurnStore } from "../stores/types.js";
+import type { CapabilityResult, CheckAppProgressInput, CheckAppProgressResult, CheckPublishProgressInput, EditAppInput, EditAppResult, AskUserInput, AskUserResult, GetAppInput, GetAppResult, PreviewAppInput, PreviewAppResult, PreviewStatusInput, PreviewStatusResult, Principal, ProgressEvent, PublishAppInput, PublishAppResult, ResolvedPrincipal, StartAppInput, StartAppResult, UploadArtifactInput, UploadArtifactResult } from "./types.js";
 export { IMPORT_ZIP_MAX_BYTES } from "./types.js";
 export type CapabilityContext = {
-    /**
-     * Who is polling, for resume. Absent on one-shot capability calls that do
-     * not poll, in which case no cursor is kept.
-     */
-    caller?: CallerRef;
     config: GatewayConfig;
-    /**
-     * Durable history of the live-edit session. This is what a caller reads
-     * when there is no local turn to ask — after a restart, on another replica,
-     * or from a channel that never started the build.
-     */
-    events?: EventStore;
-    /** Injected so pacing and stall thresholds are testable without real time. */
+    /** Injected so turn and stall thresholds are testable without real time. */
     now?: () => number;
     onProgress?: (event: ProgressEvent) => void;
     onPrincipalResolved?: (principal: ResolvedPrincipal) => void;
     principal: Principal;
-    /** Where each caller's place in the event stream is kept between calls. */
-    progressCursors?: ProgressStore;
+    /** Per-application facts that outlive any one turn. */
+    appState: AppState;
+    /** When each build last spoke, and whether its silence was reported. */
+    progress?: ProgressStore;
     recentApps: RecentAppStore;
     /**
      * Optional headless capture of the live library iframe (pitcherURL). Injected
@@ -39,11 +31,16 @@ export type CapabilityContext = {
      * Injected in tests; defaults to Playwright in the MCP transport.
      */
     capturePreviewScreenshot?: CapturePreviewScreenshot;
+    /**
+     * What the connected host can drive a browser with. Only a transport knows
+     * which client it is talking to; absent, the contract says "unknown".
+     */
+    hostBrowserTools?: HostBrowserTools;
     server: SuperblocksServerClient;
     sessionPeer: SessionPeer;
     /** The caller gave up on this call (an MCP cancellation, a closed request). */
     signal?: AbortSignal;
-    turns: TurnStore;
+    stepUpTurns: StepUpTurnStore;
 };
 /**
  * Resolves the Superblocks user behind the CLI session this Gateway was
@@ -54,16 +51,19 @@ export type CapabilityContext = {
  * so it surfaces as an error rather than an interactive-auth elicitation.
  */
 export declare function ensurePrincipal(ctx: CapabilityContext): Promise<CapabilityResult<ResolvedPrincipal>>;
-export declare function resolveApplicationId(ctx: CapabilityContext, principal: ResolvedPrincipal, applicationId: string | undefined): Promise<CapabilityResult<string>>;
-export declare function startApp(ctx: CapabilityContext, input: StartAppInput): Promise<CapabilityResult<StartAppResult>>;
+export declare function resolveApplicationId(ctx: CapabilityContext, principal: ResolvedPrincipal, applicationId: string | undefined, 
 /**
- * Creates a fullstack app, uploads the caller's archive as an app attachment,
- * and hands Clark a migration prompt — the same path as the browser import
- * wizard, without the sessionStorage hop.
+ * `unambiguous` declines to guess while a second application is also in
+ * play. Reserved for calls that write: acting on the wrong application is
+ * cheap to undo for a status poll and not cheap at all for an edit.
  */
-export declare function importApp(ctx: CapabilityContext, input: ImportAppInput): Promise<CapabilityResult<ImportAppResult>>;
+options?: {
+    unambiguous?: boolean;
+}): Promise<CapabilityResult<string>>;
+export declare function startApp(ctx: CapabilityContext, input: StartAppInput): Promise<CapabilityResult<StartAppResult>>;
+export declare function uploadArtifact(ctx: CapabilityContext, input: UploadArtifactInput): Promise<CapabilityResult<UploadArtifactResult>>;
 export declare function checkAppProgress(ctx: CapabilityContext, input: CheckAppProgressInput): Promise<CapabilityResult<CheckAppProgressResult>>;
-export declare function editApp(ctx: CapabilityContext, input: EditAppInput): Promise<CapabilityResult<EditAppResult>>;
+export declare function editApp(ctx: CapabilityContext, input: EditAppInput, approvedPlan?: object): Promise<CapabilityResult<EditAppResult>>;
 /**
  * Shows the app's current work on a real URL without deploying it - the
  * editor's Preview button, driven from here.
@@ -76,9 +76,26 @@ export declare function editApp(ctx: CapabilityContext, input: EditAppInput): Pr
  * second one.
  */
 export declare function previewApp(ctx: CapabilityContext, input: PreviewAppInput): Promise<CapabilityResult<PreviewAppResult>>;
+/** Read the build backing an existing commit preview without creating work. */
+export declare function getPreviewStatus(ctx: CapabilityContext, input: PreviewStatusInput): Promise<CapabilityResult<PreviewStatusResult>>;
+/**
+ * Opens the decision card: what Superblocks asked, for the user to answer as a
+ * form rather than by typing an approval the host has to interpret.
+ *
+ * Its own tool because an MCP App is bound to one, and `check_app_progress`
+ * must stay text-only - a card tool reopens its card on every poll, so putting
+ * this on the poll loop would flash a blank form through a whole build.
+ */
+export declare function askUser(ctx: CapabilityContext, input: AskUserInput): Promise<CapabilityResult<AskUserResult>>;
 /**
- * Lovable-style lookup: editor URL always, preview URLs when a build can be
- * ensured (default). Captures a screenshot whenever the preview is ready.
+ * Read the app's current live editor view without committing or building it.
  */
 export declare function getApp(ctx: CapabilityContext, input: GetAppInput): Promise<CapabilityResult<GetAppResult>>;
 export declare function publishApp(ctx: CapabilityContext, input: PublishAppInput): Promise<CapabilityResult<PublishAppResult>>;
+/**
+ * Where a publish handed back as `publishing` has got to.
+ *
+ * Each call watches for a bounded slice of the rollout, then hands back a
+ * changing clock so repeated calls remain useful without outliving the host.
+ */
+export declare function checkPublishProgress(ctx: CapabilityContext, input: CheckPublishProgressInput): Promise<CapabilityResult<PublishAppResult>>;