@superblocksteam/gateway 2.0.0-SNAPSHOT.2161f9a02a4eb5d8

package/LICENSE.txt

@@ -0,0 +1,87 @@
+Superblocks Community Software License
+
+This Superblocks Community License Agreement (the “Agreement”) sets forth the terms on which DayZero
+Software, Inc. d/b/a Superblocks (“Superblocks”) makes available certain software made available by Superblocks
+under this Agreement (the “Software”). BY INSTALLING, DOWNLOADING, ACCESSING, USING OR
+DISTRIBUTING ANY OF THE SOFTWARE, YOU AGREE TO THE TERMS AND CONDITIONS OF THIS
+AGREEMENT.IF YOU DO NOT AGREE TO SUCH TERMS AND CONDITIONS, YOU MUST NOT USE THE
+SOFTWARE. IF YOU ARE RECEIVING THE SOFTWARE ON BEHALF OF A LEGAL ENTITY, YOU
+REPRESENT AND WARRANT THAT YOU HAVE THE ACTUAL AUTHORITY TO AGREE TO THE
+TERMS AND CONDITIONS OF THIS AGREEMENT ON BEHALF OF SUCH ENTITY. “Licensee” means you,
+an individual, or the entity on whose behalf you are receiving the Software.
+
+1. LICENSE GRANT AND CONDITIONS.
+
+1.1 License. Subject to the terms and conditions of this Agreement, Superblocks hereby grants to Licensee a
+non-exclusive, royalty-free, worldwide, non-transferable, non-sublicenseable license during the term of this
+Agreement to: (a) use the Software; (b) prepare modifications and derivative works of the Software; (c)
+distribute the Software (including without limitation in source code or object code form); and (d) reproduce
+copies of the Software (the “License”). Licensee is not granted the right to, and Licensee shall not, exercise the
+License for an Excluded Purpose. For purposes of this Agreement, “Excluded Purpose” means making
+available any software-as-a-service, platform-as-a-service, infrastructure-as-a-service or other similar online
+service that competes with Superblocks’ products or services.
+
+1.2 Conditions. In consideration of the License, Licensee’s distribution of the Software is subject to the
+following conditions:
+
+  a. Licensee must cause any Software modified by Licensee to carry prominent notices stating that Licensee
+  modified the Software.
+  b. On each Software copy, Licensee shall reproduce and not remove or alter all Superblocks or third party
+  copyright or other proprietary notices contained in the Software, and Licensee must provide the notice
+  below with each copy.
+
+  “This software is made available by DayZero Software, Inc. d/b/a Superblocks, under the terms of the
+  Superblocks Community License Agreement. © 2022 DayZero Software, Inc.”
+
+1.3 Licensee Modifications. Licensee may add its own copyright notices to modifications made by Licensee
+and may provide additional or different license terms and conditions for use, reproduction, or distribution of
+Licensee’s modifications. While redistributing the Software or modifications thereof, Licensee may choose to
+offer, for a fee or free of charge, support, warranty, indemnity, or other obligations. Licensee, and not
+Superblocks, will be responsible for any such obligations.
+
+1.4 No Sublicensing. The License does not include the right to sublicense the Software, however, each recipient
+to which Licensee provides the Software may exercise the Licenses so long as such recipient agrees to the terms
+and conditions of this Agreement.
+
+2. TERM AND TERMINATION. This Agreement will continue unless and until earlier terminated as set forth
+herein. If Licensee breaches any of its conditions or obligations under this Agreement, this Agreement will
+terminate automatically and the License will terminate automatically and permanently.
+
+3. INTELLECTUAL PROPERTY. As between the parties, Superblocks will retain all right, title, and interest in
+the Software, and all intellectual property rights therein. Superblocks hereby reserves all rights not expressly
+granted to Licensee in this Agreement. Superblocks hereby reserves all rights in its trademarks and service
+marks, and no licenses therein are granted in this Agreement.
+
+4. DISCLAIMER. SUPERBLOCKS HEREBY DISCLAIMS ANY AND ALL WARRANTIES AND
+CONDITIONS, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SPECIFICALLY
+DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE, WITH RESPECT TO THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY. SUPERBLOCKS WILL NOT BE LIABLE FOR ANY DAMAGES OF
+ANY KIND, INCLUDING BUT NOT LIMITED TO, LOST PROFITS OR ANY CONSEQUENTIAL,
+SPECIAL, INCIDENTAL, INDIRECT, OR DIRECT DAMAGES, HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, ARISING OUT OF THIS AGREEMENT. THE FOREGOING SHALL APPLY TO
+THE EXTENT PERMITTED BY APPLICABLE LAW.
+
+6. GENERAL.
+
+6.1  Governing Law. This Agreement will be governed by and interpreted in accordance with the laws of the
+state of California, without reference to its conflict of laws principles. If Licensee is located within the United
+States, all disputes arising out of this Agreement are subject to the exclusive jurisdiction of courts located in San
+Mateo County, California. USA. If Licensee is located outside of the United States, any dispute, controversy or
+claim arising out of or relating to this Agreement will be referred to and finally determined by arbitration in
+accordance with the JAMS International Arbitration Rules. The tribunal will consist of one neutral arbitrator.
+The place of arbitration will be Palo Alto, California. The language to be used in the arbitral proceedings will be
+English. Judgment upon the award rendered by the arbitrator may be entered in any court having jurisdiction
+thereof.
+
+6.2.  Assignment. Licensee may not assign its rights under this Agreement to any third party. Superblocks may
+freely assign its rights under this Agreement to any third party.
+
+6.3.  Other.  This Agreement is the entire agreement between the parties regarding the subject matter hereof.
+No amendment or modification of this Agreement will be valid or binding upon the parties unless made in
+writing and signed by the duly authorized representatives of both parties. In the event that any provision,
+including without limitation any condition, of this Agreement is held to be unenforceable, this Agreement and
+all licenses and rights granted hereunder will immediately terminate. Waiver by Superblocks of a breach of any
+provision of this Agreement or the failure by Superblocks to exercise any right hereunder will not be construed
+as a waiver of any subsequent breach of that right or as a waiver of any other right.

package/README.md

@@ -0,0 +1,284 @@
+# Gateway v0
+
+Standalone Superblocks entry point for a **single MCP connector** (Admin + Builder)
+over **stdio**, running as the already-logged-in Superblocks CLI user.
+
+Builder tools (`upload_artifact`, `start_app`, `edit_app`,
+`check_app_progress`, `ask_user`, `get_app`, `get_integration_metadata`,
+`query_integration`, `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
+(`~/.superblocks/auth.json` / `SUPERBLOCKS_AUTH_FILE` / `just worktree auth`).
+
+Scope notes:
+
+- In-memory stores only; no Redis (ENG-5594).
+- CLI identity only. Linked MCP grants, static `GATEWAY_DEV_SUPERBLOCKS_API_KEY`,
+  and on-behalf-of exchange are not supported.
+- Missing Playwright Chromium does not block start (ENG-5796). Screenshots fail
+  closed when Chromium is absent.
+- 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
+# Log in if needed (same CLI session the Gateway will use)
+superblocks login
+
+# Write a stdio MCP entry into the client config
+superblocks gateway setup --client claude
+# or: --client cursor / --client claude-desktop / --client generic
+
+# Restart the MCP host. It spawns Gateway; do not run gateway 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` 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.
+
+`gateway setup` downloads Playwright Chromium for preview captures when it is
+missing.
+
+## Local run
+
+The MCP host spawns Gateway. Do not run `gateway serve` in a TTY.
+
+Against a remote Superblocks domain (EE / SaaS IR):
+
+```bash
+cd packages/cli/packages/cli
+./bin/dev.js config set domain <host>
+./bin/dev.js login
+./bin/dev.js gateway setup --client claude
+```
+
+Against a local control plane, start the stack first (`just up <worktree>`),
+then login and `gateway setup` the same way.
+
+`superblocks mcp serve` (stdio Admin-only) is deprecated; prefer `gateway setup`.
+
+## Worktree MCP (Cursor / Claude)
+
+Until published packages are on PATH, point the MCP host at this checkout.
+Log in and run setup from the worktree CLI (not a globally installed `superblocks`):
+
+```bash
+cd packages/cli/packages/cli
+./bin/dev.js config set domain <host>
+./bin/dev.js login
+./bin/dev.js gateway setup --client cursor
+# or: --client claude
+```
+
+`setup` writes an absolute stdio spawn into the host config (`~/.cursor/mcp.json`
+for Cursor, `~/.claude.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "superblocks": {
+      "command": "/absolute/path/to/tsx/cli.mjs",
+      "args": [
+        "/absolute/path/to/packages/cli/packages/cli/bin/dev.js",
+        "gateway",
+        "serve"
+      ],
+      "env": {
+        "SUPERBLOCKS_AUTH_FILE": "/absolute/path/to/worktree/.superblocks/auth.json"
+      }
+    }
+  }
+}
+```
+
+`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 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.
+
+Restart the MCP host after `setup` and after every rebuild below.
+
+### Rebuild after source changes
+
+Cursor MCP still goes through oclif `dist/index.js`. CLI esbuild inlines
+`@superblocksteam/gateway`, so a Gateway `tsc` alone does not update the
+process the host spawns.
+
+| You changed                                                     | Rebuild                                        |
+| --------------------------------------------------------------- | ---------------------------------------------- |
+| `packages/shared` (types Gateway imports, e.g. SocketHeartbeat) | `pnpm --filter @superblocksteam/shared build`  |
+| `packages/gateway/src`                                          | `pnpm --filter @superblocksteam/gateway build` |
+| Gateway, CLI serve wiring, or anything oclif esbuild inlines    | `pnpm --filter @superblocksteam/cli build`     |
+
+A typical Gateway capture change is shared (if types moved), then Gateway,
+then CLI. Then restart Cursor.
+
+Proof the new bundle is live: Gateway stderr logs
+`gateway live canvas capture uses libraryBrowserContext (testingEnabled does not gate it)`
+at boot. A crash that `@superblocksteam/shared` does not export
+`SocketHeartbeat` means shared `dist/` is stale.
+
+## Authentication
+
+Gateway tools call the Superblocks control plane with the personal API key from
+the CLI session. Log in first (`superblocks login`). There is no issuer env, no
+consent page, and no second PAT.
+
+## Cloud-Prem laptop agent
+
+Set `GATEWAY_LOCAL_AGENT=true` for a single-user corp laptop process. Stores are
+always in-memory; suspended turns and progress cursors do not survive a restart.
+`SUPERBLOCKS_SERVER_URL` (or `GATEWAY_SERVER_URL`) points at the in-VPC control
+plane. The CLI session supplies identity.
+
+Set `GATEWAY_ADMIN_TOOLS_ONLY=true` alongside `GATEWAY_LOCAL_AGENT=true` to
+package only the customer Admin surface. Builder tools are not registered.
+
+## MCP tools
+
+After `gateway setup`, restart Claude Code or Cursor and call `upload_artifact`,
+`start_app`, `edit_app`, `check_app_progress`, `ask_user`, `get_app`,
+`get_integration_metadata`, `query_integration`, `preview_app`, 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_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.
+It resolves the integration through the RBAC-annotated superset list rather than
+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.
+
+`query_integration` answers one-off data questions directly without creating an
+application or persistent API. It accepts one parser-constrained PostgreSQL
+`SELECT`, read-only CTE, `SHOW`, or `EXPLAIN` statement and returns a sanitized,
+bounded result. PostgreSQL functions are limited to `count`, `sum`, `avg`,
+`min`, and `max`; explicit casts, all other functions, and all mutation, schema,
+session, and row-locking statements are rejected before execution. The
+operation uses the same integration-level build permission and scoped token as
+metadata reads and has a 30-second execution ceiling within the host-call
+deadline.
+
+## 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.                    |
+| `GATEWAY_IMPORT_SEARCH_DIRS` | Directories `upload_artifact.filePath` may read.           |
+| `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
+restart the MCP host. Re-run setup without `--debug` to turn them off.
+
+## Remote traceability
+
+Gateway exports one OpenTelemetry trace per MCP process through the authenticated
+Server `/api/v1/traces` proxy. Each tool call is a child span with the MCP client
+name and version, tool name, duration, outcome, organization ID, and application
+ID when available.
+
+Prompts, answers, result payloads, credentials, and raw error messages are never
+added to these spans. Use the application ID to correlate a trace with the
+existing server-side app and build records.
+
+Cloud-Prem uses `SUPERBLOCKS_DEPLOYMENT_TYPE=cloud-prem` (or `GATEWAY_LOCAL_AGENT`)
+so the stricter telemetry policy is selected. Laptop agents still drop client,
+organization, and application attributes until the Tier 2 traces contract lists
+them; tool name, duration, and outcome still export.

package/dist/agents/resolve-orchestrator-url.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Picks an orchestrator (agent) base URL the way the browser does: from the
+ * Server's agent inventory for the org, filtered by org agent type, Active
+ * status, and profile tags. Operators never set this URL.
+ */
+export type OrchestratorAgentCandidate = {
+    status: string;
+    tags: Record<string, string[]>;
+    type: number;
+    url: string;
+};
+export type PickOrchestratorBaseUrlInput = {
+    agentType: number;
+    agents: OrchestratorAgentCandidate[];
+    profileKey: string;
+};
+/**
+ * Returns a single orchestrator base URL from Server-reported agents.
+ * Throws when none are eligible — same failure mode as the browser's
+ * "No active agent found".
+ */
+export declare function pickOrchestratorBaseUrl(input: PickOrchestratorBaseUrlInput): string;

package/dist/agents/resolve-orchestrator-url.js

@@ -0,0 +1,38 @@
+/**
+ * Picks an orchestrator (agent) base URL the way the browser does: from the
+ * Server's agent inventory for the org, filtered by org agent type, Active
+ * status, and profile tags. Operators never set this URL.
+ */
+const ACTIVE_STATUS = "Active";
+function matchesProfile(tags, profileKey) {
+    const profiles = tags.profile;
+    if (!profiles || profiles.length === 0) {
+        // Cloud sentinel and untagged agents are eligible for any profile.
+        return true;
+    }
+    return profiles.includes("*") || profiles.includes(profileKey);
+}
+function withTrailingSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+ * Returns a single orchestrator base URL from Server-reported agents.
+ * Throws when none are eligible — same failure mode as the browser's
+ * "No active agent found".
+ */
+export function pickOrchestratorBaseUrl(input) {
+    const eligible = input.agents.filter((candidate) => candidate.type === input.agentType &&
+        candidate.status === ACTIVE_STATUS &&
+        Boolean(candidate.url) &&
+        matchesProfile(candidate.tags ?? {}, input.profileKey));
+    if (eligible.length === 0) {
+        throw new Error(`No active agent found for agentType=${input.agentType} profile=${input.profileKey}`);
+    }
+    // Browser picks randomly among matches; stable first is fine for gateway.
+    const chosen = eligible[0];
+    if (!chosen) {
+        throw new Error(`No active agent found for agentType=${input.agentType} profile=${input.profileKey}`);
+    }
+    return withTrailingSlash(chosen.url);
+}
+//# sourceMappingURL=resolve-orchestrator-url.js.map

package/dist/agents/resolve-orchestrator-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-orchestrator-url.js","sourceRoot":"","sources":["../../src/agents/resolve-orchestrator-url.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,MAAM,aAAa,GAAG,QAAQ,CAAC;AAE/B,SAAS,cAAc,CACrB,IAA8B,EAC9B,UAAkB;IAElB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,mEAAmE;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmC;IAEnC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAClC,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,IAAI,KAAK,KAAK,CAAC,SAAS;QAClC,SAAS,CAAC,MAAM,KAAK,aAAa;QAClC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC;QACtB,cAAc,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CACzD,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,uCAAuC,KAAK,CAAC,SAAS,YAAY,KAAK,CAAC,UAAU,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,uCAAuC,KAAK,CAAC,SAAS,YAAY,KAAK,CAAC,UAAU,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC"}

package/dist/capabilities/integration-metadata.d.ts

@@ -0,0 +1,28 @@
+import { type CapabilityContext } from "./lifecycle.js";
+import type { CapabilityResult } from "./types.js";
+export type GetIntegrationMetadataInput = {
+    applicationId?: string;
+    integrationId: string;
+    limit?: number;
+    offset?: number;
+    search?: string;
+};
+type MetadataEntry = {
+    path: string;
+    value: boolean | null | number | string;
+};
+export type GetIntegrationMetadataResult = {
+    /** Absent when the metadata was read through an integration-scoped token. */
+    applicationId?: string;
+    entries: MetadataEntry[];
+    hasMore: boolean;
+    integrationId: string;
+    integrationName: string;
+    nextOffset: number | null;
+    offset: number;
+    pluginId: string;
+    returnedCount: number;
+    totalCount: number;
+};
+export declare function getIntegrationMetadata(context: CapabilityContext, input: GetIntegrationMetadataInput): Promise<CapabilityResult<GetIntegrationMetadataResult>>;
+export {};

package/dist/capabilities/integration-metadata.js

@@ -0,0 +1,174 @@
+import { pickOrchestratorBaseUrl } from "../agents/resolve-orchestrator-url.js";
+import { integrationIsToolSupported } from "../integrations/filters.js";
+import { hasBuildPermission } from "../integrations/map.js";
+import { pickEditorProfileKey } from "../integrations/profile-key.js";
+import { HttpOrchestratorClient } from "../orchestrator/client.js";
+import { sanitizeAgentFacingText, sanitizeAgentFacingValue, } from "../sabs/agent-facing-text.js";
+import { ensurePrincipal, resolveApplicationId, } from "./lifecycle.js";
+const DEFAULT_LIMIT = 100;
+function labelPart(value) {
+    return typeof value === "string"
+        ? value.trim().replaceAll(/[.[\]]/g, "_")
+        : "";
+}
+/**
+ * A table name alone is ambiguous: `public.users` and `analytics.users` are
+ * different tables, so qualify with the schema whenever the row carries one.
+ */
+function arrayEntryLabel(value, index) {
+    if (value && typeof value === "object") {
+        const row = value;
+        const name = labelPart(row.name);
+        if (name) {
+            const schema = labelPart(row.schema);
+            return schema ? `${schema}.${name}` : name;
+        }
+    }
+    return String(index);
+}
+function metadataEntries(value, path = "", entries = []) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        entries.push({ path, value });
+        return entries;
+    }
+    if (Array.isArray(value)) {
+        const seen = new Set();
+        value.forEach((entry, index) => {
+            const label = arrayEntryLabel(entry, index);
+            // Two rows that still label identically would be indistinguishable, so
+            // fall back to the index for the later one.
+            const unique = seen.has(label) ? `${label}#${index}` : label;
+            seen.add(unique);
+            metadataEntries(entry, `${path}[${unique}]`, entries);
+        });
+        return entries;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            metadataEntries(entry, path ? `${path}.${key}` : key, entries);
+        }
+    }
+    return entries;
+}
+export async function getIntegrationMetadata(context, input) {
+    const principal = await ensurePrincipal(context);
+    if (principal.kind !== "ok") {
+        return principal;
+    }
+    let applicationId;
+    // Named for the agent before the integration resolves, so a failure on the
+    // way to the metadata still reports which integration it was reaching for.
+    let label = sanitizeAgentFacingText(input.integrationId);
+    try {
+        // An app is preferred but not required. App-owned integrations (Native DB
+        // among them) are only visible through an app-scoped token, so use one
+        // whenever an app is in play and fall back to the integration-scoped token
+        // rather than making the caller invent an application.
+        const resolved = await resolveApplicationId(context, principal.value, input.applicationId);
+        applicationId = resolved.kind === "ok" ? resolved.value : undefined;
+        // The RBAC-annotated list, not the org-wide lookup by id: only this one
+        // carries the permissions that say whether the caller may build with the
+        // integration at all.
+        const rows = await context.server.getSupersetIntegrations({
+            apiKey: principal.value.apiKey,
+            ...(applicationId && { applicationId }),
+            organizationId: principal.value.organizationId,
+        });
+        const integration = rows.find((row) => row.id === input.integrationId);
+        if (!integration) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_accessible",
+                message: `Integration ${label} was not found or is not accessible.`,
+            };
+        }
+        const integrationName = sanitizeAgentFacingText(integration.name);
+        const pluginId = sanitizeAgentFacingText(integration.pluginId);
+        label = integrationName;
+        if (!hasBuildPermission(integration)) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_permitted",
+                message: `You do not have build permission on ${integrationName}.`,
+            };
+        }
+        if (!integrationIsToolSupported(integration.pluginId)) {
+            return {
+                ...(applicationId && { applicationId }),
+                kind: "error",
+                code: "integration_not_supported",
+                message: `${integrationName} is a ${pluginId} integration, which this tool cannot inspect.`,
+            };
+        }
+        const profiles = await context.server.getOrganizationProfiles({
+            apiKey: principal.value.apiKey,
+            organizationId: principal.value.organizationId,
+        });
+        const profileKey = pickEditorProfileKey(context.config.profileKey, profiles);
+        const inventory = await context.server.getAgentInventory({
+            apiKey: principal.value.apiKey,
+            organizationId: principal.value.organizationId,
+        });
+        const orchestratorUrl = pickOrchestratorBaseUrl({
+            agentType: inventory.agentType,
+            agents: inventory.agents,
+            profileKey,
+        });
+        const scopedToken = await context.server.issueScopedToken(applicationId
+            ? {
+                apiKey: principal.value.apiKey,
+                applicationId,
+                scope: "apps:update",
+            }
+            : {
+                apiKey: principal.value.apiKey,
+                integrationId: input.integrationId,
+                scope: "integrations:build",
+            });
+        const metadata = await new HttpOrchestratorClient(orchestratorUrl).getMetadata({
+            apiKey: principal.value.apiKey,
+            integrationId: input.integrationId,
+            profileKey,
+            scopedToken,
+        });
+        const sanitized = sanitizeAgentFacingValue(metadata);
+        const search = input.search?.trim().toLowerCase();
+        const matched = metadataEntries(sanitized).filter((entry) => !search ||
+            entry.path.toLowerCase().includes(search) ||
+            String(entry.value).toLowerCase().includes(search));
+        const limit = input.limit ?? DEFAULT_LIMIT;
+        const offset = input.offset ?? 0;
+        const entries = matched.slice(offset, offset + limit);
+        const nextOffset = offset + entries.length < matched.length ? offset + entries.length : null;
+        return {
+            kind: "ok",
+            value: {
+                ...(applicationId && { applicationId }),
+                entries,
+                hasMore: nextOffset !== null,
+                integrationId: integration.id,
+                integrationName,
+                nextOffset,
+                offset,
+                pluginId,
+                returnedCount: entries.length,
+                totalCount: matched.length,
+            },
+        };
+    }
+    catch (error) {
+        const detail = sanitizeAgentFacingText(error instanceof Error ? error.message : "Unknown metadata error").replaceAll("\u2014", "-");
+        return {
+            ...(applicationId && { applicationId }),
+            kind: "error",
+            code: "integration_metadata_unavailable",
+            message: `Could not load metadata for ${label}: ${detail}`,
+        };
+    }
+}
+//# sourceMappingURL=integration-metadata.js.map

package/dist/capabilities/integration-metadata.js.map

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