@nodetool-ai/websocket 0.7.0-rc.22 → 0.8.1

package/dist/e2e-server.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * E2E harness backend — runs the real NodeTool HTTP+WebSocket backend with an
+ * in-memory SQLite database, tailored for the web E2E test runner
+ * (`web/e2e-runner.html`). It is fully hermetic: every external provider is
+ * faked so the shipped templates run in CI with no API keys and no network.
+ *
+ * Faking strategy:
+ *   - LLM/agent providers: every registered provider id is re-registered with a
+ *     FakeProvider (a ScriptedProvider with no required credentials), so
+ *     `getProvider`/`isProviderConfigured` and the runner's resolveProvider all
+ *     return a configured fake regardless of how a node resolves its provider.
+ *   - External / media-generating nodes (fal, replicate, search, http, image /
+ *     video / audio generation, …): resolved to a fake executor that returns
+ *     type-correct placeholder outputs derived from the node's output metadata,
+ *     so downstream nodes and output nodes still receive well-formed values.
+ *   - Pure-compute nodes (text, control, data, math, …) run for real.
+ *   - Unknown node types (e.g. the `test.Input` placeholder) pass through.
+ *
+ * Usage (via the Playwright globalSetup — not normally invoked directly):
+ *   tsx packages/websocket/src/e2e-server.ts
+ *
+ * Environment:
+ *   PORT / HOST                bind config (default 127.0.0.1:7777)
+ *   SECRETS_MASTER_KEY         base64 master key (a test default is used if unset)
+ *   NODETOOL_E2E_EXAMPLES_DIR  examples dir served at /api/examples (optional)
+ *   NODETOOL_TRACE_FILE        JSONL trace output path (optional)
+ */
+import { initTestDb } from "@nodetool-ai/models";
+import { initMasterKey } from "@nodetool-ai/security";
+import { createFakeExecutorResolver, fakeAllProviders, resolveFakeProvider } from "./fake-runtime.js";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { createTestUiServer } from "./test-ui-server.js";
+import { refreshSandboxCatalog } from "./sandbox-catalog.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.PORT ?? 7777);
+const HOST = process.env.HOST ?? "127.0.0.1";
+// Base64-encoded 32-byte placeholder key used only for E2E tests.
+const E2E_TEST_MASTER_KEY_B64 = "RTJFX1RFU1RfS0VZX0RPX05PVF9VU0VfSU5fUFJPRCE=";
+async function main() {
+    if (process.env.NODE_ENV === "production" &&
+        !process.env.SECRETS_MASTER_KEY) {
+        throw new Error("[e2e-server] SECRETS_MASTER_KEY must be set when NODE_ENV=production");
+    }
+    process.env.SECRETS_MASTER_KEY =
+        process.env.SECRETS_MASTER_KEY ?? E2E_TEST_MASTER_KEY_B64;
+    const traceFile = process.env.NODETOOL_TRACE_FILE;
+    if (traceFile || process.env.NODETOOL_TRACE_STDOUT) {
+        const { initTelemetry } = await import("@nodetool-ai/runtime");
+        const telemetryOptions = {
+            serviceName: "nodetool-e2e",
+            silent: true
+        };
+        if (traceFile) {
+            telemetryOptions.traceFile = traceFile;
+        }
+        await initTelemetry(telemetryOptions);
+    }
+    initTestDb();
+    await initMasterKey();
+    fakeAllProviders();
+    // The shipped sandbox packs, so a Code node in an example workflow can
+    // import one. `createTestUiServer` registers built-in nodes without loading
+    // packs, which leaves no catalog on the process — and a Code node that
+    // imports one then fails with "Sandbox packages are not available in this
+    // process" rather than running the way it does on the real server.
+    await refreshSandboxCatalog();
+    let registry = null;
+    const examplesDir = resolveExamplesDir();
+    const serverOptions = {
+        port: PORT,
+        host: HOST,
+        passthroughUnknownNodes: true,
+        configureRegistry: (r) => {
+            registry = r;
+            // Providers self-register on import; re-fake after registry setup in case
+            // any provider registration happened during node registration.
+            fakeAllProviders();
+        },
+        resolveExecutor: createFakeExecutorResolver(() => registry),
+        resolveProvider: resolveFakeProvider
+    };
+    if (examplesDir) {
+        serverOptions.examplesDir = examplesDir;
+    }
+    const srv = createTestUiServer(serverOptions);
+    await srv.listen();
+    console.log(`[e2e-server] Ready on http://${HOST}:${PORT} (${srv.info.metadataCount} nodes registered)` +
+        (examplesDir ? ` examples=${examplesDir}` : ""));
+    // Human-readable readiness marker; the Playwright globalSetup gates on the
+    // backend accepting TCP connections (waitForPort), not on this line.
+    process.stdout.write("[e2e-server] READY\n");
+}
+function resolveExamplesDir() {
+    const fromEnv = process.env.NODETOOL_E2E_EXAMPLES_DIR;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    const repoRoot = resolve(__dirname, "..", "..", "..");
+    const candidates = [
+        resolve(repoRoot, "packages", "base-nodes", "nodetool", "examples", "nodetool-base"),
+        resolve(repoRoot, "examples", "workflows")
+    ];
+    return candidates.find((dir) => existsSync(dir));
+}
+main().catch((error) => {
+    console.error("[e2e-server] Failed to start:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=e2e-server.js.map

package/dist/e2e-server.js.map

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

package/dist/example-workflows.d.ts

@@ -0,0 +1,20 @@
+interface ExampleWorkflowLoadOptions {
+    examplesDir?: string;
+    /** Fallback thumbnail directory when the sibling of examplesDir has no JPGs. */
+    examplesAssetsFallbackDir?: string;
+    metadataRoots?: string[];
+    metadataMaxDepth?: number;
+}
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export declare function deriveExampleAssetsDir(examplesDir: string, fallbackAssetsDir?: string | null): string;
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export declare function resolveExampleJsonPath(examplesDir: string, exampleRef: string): string | null;
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export declare function loadExampleGraph(packageName: string, exampleRef: string, options?: ExampleWorkflowLoadOptions): Record<string, unknown> | null;
+export declare function defaultExamplePackageName(options: ExampleWorkflowLoadOptions): string | null;
+export {};
+//# sourceMappingURL=example-workflows.d.ts.map

package/dist/example-workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-workflows.d.ts","sourceRoot":"","sources":["../src/example-workflows.ts"],"names":[],"mappings":"AAKA,UAAU,0BAA0B;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAaD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,CAiBR;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAkDf;AAyCD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAahC;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,MAAM,GAAG,IAAI,CAKf"}

package/dist/example-workflows.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import nodePath from "node:path";
+import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
+import { isString } from "./lib/wire-values.js";
+function directoryHasGalleryThumbnails(dir) {
+    if (!existsSync(dir)) {
+        return false;
+    }
+    try {
+        return readdirSync(dir).some((file) => /\.(jpg|jpeg|png)$/i.test(file));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export function deriveExampleAssetsDir(examplesDir, fallbackAssetsDir) {
+    const derived = nodePath.join(nodePath.dirname(nodePath.dirname(examplesDir)), "assets", nodePath.basename(examplesDir));
+    if (directoryHasGalleryThumbnails(derived)) {
+        return derived;
+    }
+    if (fallbackAssetsDir &&
+        existsSync(fallbackAssetsDir) &&
+        directoryHasGalleryThumbnails(fallbackAssetsDir)) {
+        return fallbackAssetsDir;
+    }
+    return derived;
+}
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export function resolveExampleJsonPath(examplesDir, exampleRef) {
+    const ref = exampleRef.trim();
+    if (!ref) {
+        return null;
+    }
+    const directCandidates = ref.toLowerCase().endsWith(".json")
+        ? [nodePath.join(examplesDir, nodePath.basename(ref))]
+        : [
+            nodePath.join(examplesDir, `${ref}.json`),
+            nodePath.join(examplesDir, ref)
+        ];
+    for (const candidate of directCandidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    let files;
+    try {
+        files = readdirSync(examplesDir).filter((file) => file.toLowerCase().endsWith(".json"));
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (file === ref || file === `${ref}.json`) {
+            return nodePath.join(examplesDir, file);
+        }
+    }
+    for (const file of files) {
+        try {
+            const raw = readFileSync(nodePath.join(examplesDir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            if (isString(parsed.name) && parsed.name === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+            if (isString(parsed.id) && parsed.id === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+        }
+        catch {
+            // skip invalid example files
+        }
+    }
+    return null;
+}
+function loadExampleGraphFromDir(examplesDir, exampleRef) {
+    const examplePath = resolveExampleJsonPath(examplesDir, exampleRef);
+    if (!examplePath) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(examplePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function loadExampleGraphFromPythonPackage(packageName, exampleRef, options) {
+    const loaded = loadPythonPackageMetadata({
+        roots: options.metadataRoots,
+        maxDepth: options.metadataMaxDepth
+    });
+    const pkg = loaded.packages.find((p) => p.name === packageName);
+    if (!pkg?.sourceFolder) {
+        return null;
+    }
+    const examplesDir = nodePath.join(pkg.sourceFolder, "nodetool", "examples", packageName);
+    return loadExampleGraphFromDir(examplesDir, exampleRef);
+}
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export function loadExampleGraph(packageName, exampleRef, options = {}) {
+    if (options.examplesDir && existsSync(options.examplesDir)) {
+        const fromDir = loadExampleGraphFromDir(options.examplesDir, exampleRef);
+        if (fromDir) {
+            return fromDir;
+        }
+    }
+    if (packageName) {
+        return loadExampleGraphFromPythonPackage(packageName, exampleRef, options);
+    }
+    return null;
+}
+export function defaultExamplePackageName(options) {
+    if (options.examplesDir && existsSync(options.examplesDir)) {
+        return nodePath.basename(options.examplesDir);
+    }
+    return null;
+}
+//# sourceMappingURL=example-workflows.js.map

package/dist/example-workflows.js.map

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

package/dist/extension-cdp-bridge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * In-process broker for the `/ws/extension` side channel.
+ *
+ * Topology (see the extension-CDP-proxy design spec):
+ *
+ *   Chrome extension  <--JSON text frames-->  /ws/extension route
+ *                                                     |
+ *                                          registerSocket / clear
+ *                                                     |
+ *                                            ExtensionBridge (singleton)
+ *                                                     |
+ *                                              getChannel()
+ *                                                     |
+ *                            in-process ExtensionChannel { send, onMessage, close }
+ *                                                     |
+ *                                  host-process ExtensionCdpClient (Track A)
+ *
+ * The bridge is intentionally dumb: it forwards every frame transparently and
+ * never interprets CDP semantics. CDP command/response/event routing lives in
+ * the `ExtensionCdpClient`; debugger attach/detach lives in the extension.
+ *
+ * v1 supports a single extension connection. A second extension socket replaces
+ * the first (the first is closed and any open channel observers are notified of
+ * disconnect).
+ */
+import { type ExtensionFrame } from "@nodetool-ai/browser";
+/**
+ * The minimal `ws`-style socket surface the bridge needs. Satisfied by the
+ * `@fastify/websocket` socket without importing its type here (keeps this module
+ * free of a hard `ws` dependency and trivially fakeable in tests).
+ */
+export interface ExtensionSocket {
+    send(data: string): void;
+    close(): void;
+    on(event: "message", cb: (raw: Buffer | ArrayBuffer | Buffer[]) => void): void;
+    on(event: "close", cb: () => void): void;
+    on(event: "error", cb: (err: Error) => void): void;
+}
+/**
+ * The in-process channel an {@link ExtensionCdpClient} rides. Track A's client
+ * is constructed with exactly this shape (or a WS URL). Frames are typed
+ * {@link ExtensionFrame} objects in-process; the bridge serializes them to/from
+ * JSON text on the wire to the extension.
+ */
+export interface ExtensionChannel {
+    /** Send a frame host→ext. No-op (logged) if no extension is connected. */
+    send(frame: ExtensionFrame): void;
+    /**
+     * Register a handler for inbound ext→host frames. Returns an unsubscribe fn.
+     * The handler is also invoked with a synthetic `error` frame when the
+     * extension socket disconnects, so the client can reject pending commands.
+     */
+    onMessage(cb: (frame: ExtensionFrame) => void): () => void;
+    /** Close the channel: detaches this observer and closes the extension socket. */
+    close(): void;
+    /** Whether an extension socket is currently registered. */
+    readonly connected: boolean;
+}
+/**
+ * Module-level singleton that holds the current extension socket and fans
+ * inbound frames out to in-process channel observers.
+ */
+export declare class ExtensionBridge {
+    private socket;
+    private observers;
+    /**
+     * Register a freshly-connected extension socket. Replaces any existing one
+     * (v1 is single-connection): the previous socket is closed first.
+     */
+    registerSocket(socket: ExtensionSocket): void;
+    /** Forget the given socket if it is still the active one. */
+    clear(socket: ExtensionSocket): void;
+    /** True when an extension socket is currently registered. */
+    get connected(): boolean;
+    /**
+     * Hand a host-process consumer an {@link ExtensionChannel} bridging to the
+     * current (and any future) extension socket. The channel survives extension
+     * reconnects; it observes the bridge, not a specific socket.
+     */
+    getChannel(): ExtensionChannel;
+    private handleSocketGone;
+}
+/** The process-wide extension bridge singleton. */
+export declare const extensionBridge: ExtensionBridge;
+//# sourceMappingURL=extension-cdp-bridge.d.ts.map

package/dist/extension-cdp-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-cdp-bridge.d.ts","sourceRoot":"","sources":["../src/extension-cdp-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAK9B;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/E,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CACpD;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,iFAAiF;IACjF,KAAK,IAAI,IAAI,CAAC;IACd,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,SAAS,CAA8C;IAE/D;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAyC5C;IAED,6DAA6D;IAC7D,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAInC;IAED,6DAA6D;IAC7D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;OAIG;IACH,UAAU,IAAI,gBAAgB,CA2C7B;IAED,OAAO,CAAC,gBAAgB;CAmBzB;AASD,mDAAmD;AACnD,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/extension-cdp-bridge.js

@@ -0,0 +1,163 @@
+/**
+ * In-process broker for the `/ws/extension` side channel.
+ *
+ * Topology (see the extension-CDP-proxy design spec):
+ *
+ *   Chrome extension  <--JSON text frames-->  /ws/extension route
+ *                                                     |
+ *                                          registerSocket / clear
+ *                                                     |
+ *                                            ExtensionBridge (singleton)
+ *                                                     |
+ *                                              getChannel()
+ *                                                     |
+ *                            in-process ExtensionChannel { send, onMessage, close }
+ *                                                     |
+ *                                  host-process ExtensionCdpClient (Track A)
+ *
+ * The bridge is intentionally dumb: it forwards every frame transparently and
+ * never interprets CDP semantics. CDP command/response/event routing lives in
+ * the `ExtensionCdpClient`; debugger attach/detach lives in the extension.
+ *
+ * v1 supports a single extension connection. A second extension socket replaces
+ * the first (the first is closed and any open channel observers are notified of
+ * disconnect).
+ */
+import { createLogger } from "@nodetool-ai/config";
+import { parseExtensionFrame } from "@nodetool-ai/browser";
+import { isString } from "./lib/wire-values.js";
+const log = createLogger("nodetool.websocket.extension-bridge");
+/**
+ * Module-level singleton that holds the current extension socket and fans
+ * inbound frames out to in-process channel observers.
+ */
+export class ExtensionBridge {
+    socket = null;
+    observers = new Set();
+    /**
+     * Register a freshly-connected extension socket. Replaces any existing one
+     * (v1 is single-connection): the previous socket is closed first.
+     */
+    registerSocket(socket) {
+        if (this.socket && this.socket !== socket) {
+            log.warn("Extension already connected; replacing previous socket (v1 is single-connection)");
+            const prev = this.socket;
+            this.socket = null;
+            try {
+                prev.close();
+            }
+            catch {
+                /* previous socket already gone */
+            }
+        }
+        this.socket = socket;
+        log.info("Extension socket registered");
+        socket.on("message", (raw) => {
+            const text = bufferToString(raw);
+            const frame = parseExtensionFrame(text);
+            if (!frame) {
+                log.warn("Dropping unparseable extension frame");
+                return;
+            }
+            for (const observer of this.observers) {
+                try {
+                    observer(frame);
+                }
+                catch (err) {
+                    log.error("Extension channel observer threw", err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+        });
+        socket.on("close", () => this.handleSocketGone(socket, "closed"));
+        socket.on("error", (err) => {
+            log.error("Extension socket error", err);
+            this.handleSocketGone(socket, "error");
+        });
+    }
+    /** Forget the given socket if it is still the active one. */
+    clear(socket) {
+        if (this.socket === socket) {
+            this.handleSocketGone(socket, "cleared");
+        }
+    }
+    /** True when an extension socket is currently registered. */
+    get connected() {
+        return this.socket !== null;
+    }
+    /**
+     * Hand a host-process consumer an {@link ExtensionChannel} bridging to the
+     * current (and any future) extension socket. The channel survives extension
+     * reconnects; it observes the bridge, not a specific socket.
+     */
+    getChannel() {
+        // Arrow functions capture the bridge's `this` lexically (no `const self =
+        // this` alias); the getter delegates to one so it reads live state too.
+        const isConnected = () => this.socket !== null;
+        return {
+            send: (frame) => {
+                const socket = this.socket;
+                if (!socket) {
+                    log.warn(`No extension connected; dropping ${frame.kind} frame host→ext`);
+                    return;
+                }
+                try {
+                    socket.send(JSON.stringify(frame));
+                }
+                catch (err) {
+                    log.error("Failed to send frame to extension", err instanceof Error ? err : new Error(String(err)));
+                }
+            },
+            onMessage: (cb) => {
+                this.observers.add(cb);
+                return () => {
+                    this.observers.delete(cb);
+                };
+            },
+            close: () => {
+                const socket = this.socket;
+                if (socket) {
+                    this.socket = null;
+                    try {
+                        socket.close();
+                    }
+                    catch {
+                        /* socket already gone */
+                    }
+                }
+            },
+            get connected() {
+                return isConnected();
+            }
+        };
+    }
+    handleSocketGone(socket, reason) {
+        if (this.socket !== socket)
+            return;
+        this.socket = null;
+        log.info(`Extension socket gone (${reason}); notifying observers`);
+        const errorFrame = {
+            kind: "error",
+            message: `Extension connection ${reason}`
+        };
+        for (const observer of this.observers) {
+            try {
+                observer(errorFrame);
+            }
+            catch (err) {
+                log.error("Extension channel observer threw on disconnect", err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+    }
+}
+function bufferToString(raw) {
+    if (isString(raw))
+        return raw;
+    if (Array.isArray(raw))
+        return Buffer.concat(raw).toString("utf8");
+    if (raw instanceof ArrayBuffer)
+        return Buffer.from(raw).toString("utf8");
+    return raw.toString("utf8");
+}
+/** The process-wide extension bridge singleton. */
+export const extensionBridge = new ExtensionBridge();
+//# sourceMappingURL=extension-cdp-bridge.js.map

package/dist/extension-cdp-bridge.js.map

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

package/dist/external-mcp.d.ts

@@ -0,0 +1,58 @@
+/**
+ * User-configured external MCP servers: persistence and the per-user client
+ * pool that serves their tools to a chat turn.
+ *
+ * The server list is one JSON row in the plaintext `Setting` table, and it
+ * holds no credential: on save, every literal header or env value that is
+ * not already a `${SECRET_NAME}` reference is moved into an encrypted
+ * `Secret` row named `MCP_<SERVER>_<KEY>` and the reference stored in its
+ * place. References resolve at connect time from the user's own secrets and
+ * nowhere else — never from the process environment, which holds the
+ * server's infrastructure keys.
+ *
+ * Connections are process-global per user: the belt of every turn shares
+ * them, `sync` reconciles them after a save, and a server that stops
+ * answering is dropped and retried on the next turn.
+ */
+import { type McpRemoteTool, type Tool } from "@nodetool-ai/agents";
+import { type McpServerConfig } from "@nodetool-ai/protocol";
+/** The `Setting` key the server list lives under. */
+export declare const EXTERNAL_MCP_SETTING_KEY = "EXTERNAL_MCP_SERVERS";
+/**
+ * Whether this deployment spawns stdio servers and reaches private hosts. A
+ * stdio server is a command run on the machine the server owns, so it is
+ * offered only where that machine belongs to its user — the desktop app, a
+ * local server, a self-hosted install. The cloud profile keeps HTTP servers
+ * only, and only public https ones.
+ */
+export declare function isLocalMcpProfile(): boolean;
+export declare const STDIO_MCP_DISABLED_ERROR: string;
+/** The user's configured servers, invalid rows dropped. */
+export declare function loadExternalMcpServers(userId: string): Promise<McpServerConfig[]>;
+/** Create or replace one server. */
+export declare function saveExternalMcpServer(userId: string, config: McpServerConfig): Promise<McpServerConfig[]>;
+/** Remove one server and the secrets it owns. Returns false if absent. */
+export declare function deleteExternalMcpServer(userId: string, id: string): Promise<boolean>;
+/** What one server answered when asked for its tools. */
+export interface ExternalMcpServerProbe {
+    id: string;
+    ok: boolean;
+    tools: McpRemoteTool[];
+    error: string | null;
+}
+/**
+ * Connect to one server (fresh, outside the shared pool) and list its tools.
+ * The settings UI calls this after a save so the user sees what the server
+ * offers, or why it could not be reached. A literal credential in the probe
+ * is used for the probe only; nothing is stored.
+ */
+export declare function probeExternalMcpServer(userId: string, config: McpServerConfig): Promise<ExternalMcpServerProbe>;
+/**
+ * The belt contribution of the user's enabled servers. Syncs the pool with
+ * the stored list first, so a server saved from the settings UI is live on
+ * the next turn without a restart.
+ */
+export declare function externalMcpToolsFor(userId: string): Promise<Tool[]>;
+/** Close every user's connections (server shutdown, tests). */
+export declare function closeExternalMcpPools(): Promise<void>;
+//# sourceMappingURL=external-mcp.d.ts.map

package/dist/external-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-mcp.d.ts","sourceRoot":"","sources":["../src/external-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,IAAI,EACV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAI/B,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAiB/D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAK3C;AAED,eAAO,MAAM,wBAAwB,QAEwB,CAAC;AAyE9D,2DAA2D;AAC3D,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB5B;AAuFD,oCAAoC;AACpC,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,sBAAsB,CAAC,CAyBjC;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAYzE;AAED,+DAA+D;AAC/D,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3D"}