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

package/dist/external-mcp.js

@@ -0,0 +1,288 @@
+/**
+ * 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 { createLogger } from "@nodetool-ai/config";
+import { Secret, Setting, clearSecretCache } from "@nodetool-ai/models";
+import { McpClientPool, getExternalMcpTools } from "@nodetool-ai/agents";
+import { assertSafePublicHttpsUrl, safeFetch } from "@nodetool-ai/runtime";
+import { CLOUD_PROFILE_ENV, NODE_ENV_VAR, McpServerConfigListSchema, isCloudProfileActive, isPureSecretReferences, mcpCredentialSecretName, secretReferencesIn } from "@nodetool-ai/protocol";
+const log = createLogger("nodetool.websocket.external-mcp");
+/** The `Setting` key the server list lives under. */
+export const EXTERNAL_MCP_SETTING_KEY = "EXTERNAL_MCP_SERVERS";
+const pools = new Map();
+/** Per-user write serialization: save and delete are read-modify-write. */
+const writeQueues = new Map();
+function serializedFor(userId, fn) {
+    const prior = writeQueues.get(userId) ?? Promise.resolve();
+    const next = prior.then(fn, fn);
+    writeQueues.set(userId, next.catch(() => undefined));
+    return next;
+}
+/**
+ * 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 function isLocalMcpProfile() {
+    return !isCloudProfileActive(process.env[CLOUD_PROFILE_ENV], process.env[NODE_ENV_VAR]);
+}
+export const STDIO_MCP_DISABLED_ERROR = "Stdio MCP servers run a command on the server machine, so they are not " +
+    "available on this deployment. Use an HTTP server instead.";
+/** A resolver over the user's encrypted secrets only. */
+function userSecretResolver(userId) {
+    return async (name) => {
+        const row = await Secret.find(userId, name);
+        if (!row)
+            return null;
+        try {
+            return await row.getDecryptedValue();
+        }
+        catch {
+            // An undecryptable secret reads as unset; the server sees an empty
+            // header, which is what the user has to fix by re-entering it.
+            return null;
+        }
+    };
+}
+/** `safeFetch` in the shape the MCP transports take. */
+const guardedFetch = (input, init) => {
+    const url = input instanceof Request ? input.url : String(input);
+    return safeFetch(url, init);
+};
+/**
+ * A probe has someone watching it, so it waits less than a chat turn does for
+ * a server that accepts the socket and then says nothing.
+ */
+const PROBE_CONNECT_TIMEOUT_MS = 15_000;
+function newPool(userId, extra = {}) {
+    const options = {
+        ...extra,
+        getSecret: userSecretResolver(userId)
+    };
+    // The cloud profile fetches through the SSRF guard, which re-checks every
+    // redirect hop. A local install may reach its own loopback servers.
+    if (!isLocalMcpProfile())
+        options.fetch = guardedFetch;
+    return new McpClientPool(options);
+}
+function poolFor(userId) {
+    let pool = pools.get(userId);
+    if (pool === undefined) {
+        pool = newPool(userId);
+        pools.set(userId, pool);
+    }
+    return pool;
+}
+/** Refuse what this deployment cannot connect to. */
+function assertConnectable(config) {
+    if (isLocalMcpProfile())
+        return;
+    if (config.transport.type === "stdio") {
+        throw new Error(STDIO_MCP_DISABLED_ERROR);
+    }
+    assertSafePublicHttpsUrl(config.transport.url);
+}
+/** The servers this deployment can actually connect to. */
+function connectable(servers) {
+    return servers.filter((s) => {
+        try {
+            assertConnectable(s);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The user's configured servers, invalid rows dropped. */
+export async function loadExternalMcpServers(userId) {
+    const setting = await Setting.find(userId, EXTERNAL_MCP_SETTING_KEY);
+    if (!setting)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(setting.getValue());
+    }
+    catch {
+        return [];
+    }
+    const parsed = McpServerConfigListSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    log.warn("Ignoring malformed external MCP server list", {
+        userId,
+        issues: parsed.error.issues.length
+    });
+    return [];
+}
+async function writeServers(userId, servers) {
+    await Setting.upsert({
+        userId,
+        key: EXTERNAL_MCP_SETTING_KEY,
+        value: JSON.stringify(servers),
+        description: "External MCP servers whose tools join the agent toolbelt"
+    });
+    await poolFor(userId).sync(connectable(servers));
+}
+/**
+ * Move every literal header/env value into an encrypted secret and store the
+ * reference. A value already made of references is kept as written. The
+ * secrets for keys the new config no longer carries are removed.
+ */
+async function externalizeCredentials(userId, config, previous) {
+    const t = config.transport;
+    const values = t.type === "stdio" ? t.env : t.headers;
+    const stored = {};
+    for (const [key, value] of Object.entries(values)) {
+        // Only a value made purely of references stays as written; anything
+        // carrying a literal — even beside a reference — is a credential.
+        if (value === "" || isPureSecretReferences(value)) {
+            stored[key] = value;
+            continue;
+        }
+        const name = mcpCredentialSecretName(config.id, key);
+        await Secret.upsert({
+            userId,
+            key: name,
+            value,
+            description: `${key} for the MCP server ${config.name}`
+        });
+        clearSecretCache(userId, name);
+        stored[key] = `\${${name}}`;
+    }
+    if (previous !== undefined) {
+        await removeOwnedSecrets(userId, previous, ownedReferences(config.id, stored));
+    }
+    return t.type === "stdio"
+        ? { ...config, transport: { ...t, env: stored } }
+        : { ...config, transport: { ...t, headers: stored } };
+}
+/** The secret names a config's values own: those it references by its own name. */
+function ownedReferences(serverId, values) {
+    const owned = new Set();
+    // A secret is owned by this server when any value references it, not only
+    // the value at its own key: `${MCP_HF_58}${OTHER}` still uses it.
+    const names = new Set(Object.keys(values).map((key) => mcpCredentialSecretName(serverId, key)));
+    for (const value of Object.values(values)) {
+        for (const ref of secretReferencesIn(value)) {
+            if (names.has(ref))
+                owned.add(ref);
+        }
+    }
+    return owned;
+}
+/** Delete the secrets a config owns, except the names in `keep`. */
+async function removeOwnedSecrets(userId, config, keep = new Set()) {
+    const t = config.transport;
+    const values = t.type === "stdio" ? t.env : t.headers;
+    for (const name of ownedReferences(config.id, values)) {
+        if (keep.has(name))
+            continue;
+        await Secret.deleteSecret(userId, name);
+        clearSecretCache(userId, name);
+    }
+}
+/** Create or replace one server. */
+export async function saveExternalMcpServer(userId, config) {
+    assertConnectable(config);
+    return serializedFor(userId, async () => {
+        const current = await loadExternalMcpServers(userId);
+        const previous = current.find((s) => s.id === config.id);
+        const stored = await externalizeCredentials(userId, config, previous);
+        const next = current.filter((s) => s.id !== config.id);
+        next.push(stored);
+        // A rotated literal keeps the same reference, so the fingerprint alone
+        // would keep the old connection. Drop this server first; the sync
+        // below reopens it with the values now stored.
+        await poolFor(userId).sync(connectable(current.filter((s) => s.id !== config.id)));
+        await writeServers(userId, next);
+        return next;
+    });
+}
+/** Remove one server and the secrets it owns. Returns false if absent. */
+export function deleteExternalMcpServer(userId, id) {
+    return serializedFor(userId, async () => {
+        const current = await loadExternalMcpServers(userId);
+        const target = current.find((s) => s.id === id);
+        if (target === undefined)
+            return false;
+        await removeOwnedSecrets(userId, target);
+        await writeServers(userId, current.filter((s) => s.id !== id));
+        return true;
+    });
+}
+/**
+ * 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 async function probeExternalMcpServer(userId, config) {
+    try {
+        assertConnectable(config);
+    }
+    catch (err) {
+        return {
+            id: config.id,
+            ok: false,
+            tools: [],
+            error: err instanceof Error ? err.message : String(err)
+        };
+    }
+    const pool = newPool(userId, {
+        connectTimeoutMs: PROBE_CONNECT_TIMEOUT_MS
+    });
+    try {
+        await pool.sync([{ ...config, enabled: true }]);
+        let error = null;
+        const discovered = await pool.discover((_id, err) => {
+            error = err.message.split("\n")[0].slice(0, 300);
+        });
+        const tools = discovered.get(config.id) ?? [];
+        return { id: config.id, ok: error === null, tools, error };
+    }
+    finally {
+        await pool.close();
+    }
+}
+/**
+ * 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 async function externalMcpToolsFor(userId) {
+    const servers = await loadExternalMcpServers(userId);
+    const pool = poolFor(userId);
+    await pool.sync(connectable(servers));
+    if (pool.serverIds().length === 0)
+        return [];
+    return getExternalMcpTools(pool, (serverId, error) => {
+        log.warn("External MCP server skipped for this turn", {
+            userId,
+            server: serverId,
+            error: error.message.split("\n")[0].slice(0, 300)
+        });
+    });
+}
+/** Close every user's connections (server shutdown, tests). */
+export async function closeExternalMcpPools() {
+    const all = [...pools.values()];
+    pools.clear();
+    await Promise.all(all.map((p) => p.close()));
+}
+//# sourceMappingURL=external-mcp.js.map

package/dist/external-mcp.js.map

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

package/dist/fake-runtime.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Hermetic execution fakes shared by the test backends.
+ *
+ * Both test servers need workflows and chat to run with no API keys and no
+ * network, while pure-compute nodes still run for real so the assertions mean
+ * something:
+ *   - `e2e-server.ts` runs the shipped templates for the web E2E runner.
+ *   - `screenshot-server.ts` (with `NODETOOL_FAKE_PROVIDERS=1`) serves the
+ *     seeded fixtures to the user-journey suite.
+ *
+ * Faking strategy:
+ *   - LLM/agent providers: every registered provider id is re-registered with
+ *     `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, …) resolve to an executor returning
+ *     type-correct placeholder outputs derived from the node's output metadata,
+ *     so downstream and output nodes still receive well-formed values.
+ *   - Structural nodes (input/output/control) and pure-compute nodes (text,
+ *     data, math, …) run for real.
+ *
+ * Set `NODETOOL_FAKE_DEBUG=1` for per-node REAL/FAKE resolution logging.
+ */
+import { ScriptedProvider, type BaseProvider, type ProviderStreamItem } from "@nodetool-ai/runtime";
+import type { NodeRegistry } from "@nodetool-ai/node-sdk";
+import type { NodeExecutor } from "@nodetool-ai/kernel";
+import { type NodeDescriptor } from "@nodetool-ai/protocol";
+/** Valid 1x1 transparent PNG — bytes for faked image/media outputs, so
+ *  downstream nodes that decode them don't choke. */
+export declare const TINY_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4////fwAJ+wP9KobjigAAAABJRU5ErkJggg==";
+/** The text every faked LLM call returns. Assert on this in tests. */
+export declare const FAKE_LLM_TEXT = "deterministic e2e response";
+/** The value every faked non-media output slot returns. */
+export declare const FAKE_OUTPUT_TEXT = "deterministic e2e output";
+/**
+ * Validate a `Chunk` a fake provider is about to yield against the B1
+ * protocol schema (`packages/protocol/src/messages.ts`) and throw a
+ * descriptive error on mismatch. Called unconditionally — this module only
+ * ever runs in tests, so there is no production cost to always-on validation.
+ * See RELIABILITY_ARCHITECTURE.md §8 point 5 ("Fakes derive from contracts").
+ */
+export declare function assertValidFakeChunk(chunk: unknown): void;
+/** A provider that returns deterministic scripted responses; ignores kwargs. */
+export declare class FakeProvider extends ScriptedProvider {
+    constructor(_kwargs?: Record<string, unknown>);
+    /**
+     * Validate every yielded `Chunk` (the only `ProcessingMessage`-shaped
+     * payload a fake provider emits — tool calls and session updates carry no
+     * `type: "chunk"` discriminator) against the B1 schema before it reaches
+     * downstream consumers.
+     */
+    generateMessages(args: Parameters<ScriptedProvider["generateMessages"]>[0]): AsyncGenerator<ProviderStreamItem>;
+}
+/**
+ * Replace every registered provider (openai, anthropic, gemini, …) with the
+ * FakeProvider, registered with no required credentials. This makes
+ * `isProviderConfigured` return true and `getProvider` return a fake on every
+ * resolution path — so agent/LLM nodes never demand a real API key.
+ *
+ * Call again after node registration: providers self-register on import, so a
+ * package loaded during registry setup can add a real provider afterwards.
+ */
+export declare function fakeAllProviders(): void;
+/** A `resolveProvider` implementation that always hands back a fake. */
+export declare const resolveFakeProvider: () => Promise<BaseProvider>;
+interface FakeMeta {
+    node_type?: string;
+    required_settings?: string[] | null;
+    required_runtimes?: string[] | null;
+    outputs?: Array<{
+        name: string;
+        type?: {
+            type?: string;
+        };
+    }> | null;
+    properties?: Array<{
+        name: string;
+        type?: {
+            type?: string;
+        };
+    }> | null;
+}
+/** A placeholder value standing in for one output slot. */
+export type FakeSlotValue = string | number | boolean | null | never[] | Record<string, never> | {
+    type: string;
+    uri: string;
+    data: string;
+    mimeType: string;
+};
+/** Build a type-correct placeholder for a single output slot. */
+export declare function fakeValueForType(type: string): FakeSlotValue;
+/** An executor that emits placeholder outputs for a node's declared slots. */
+export declare function fakeExecutor(meta: FakeMeta | undefined, nodeType?: string, staticProperties?: Record<string, unknown>): NodeExecutor;
+/** True when a node type should be faked rather than executed for real. */
+export declare function shouldFakeNode(nodeType: string, meta: FakeMeta | undefined): boolean;
+/**
+ * Build a `resolveExecutor` that fakes external/provider-backed nodes and runs
+ * everything else for real.
+ *
+ * `getRegistry` is a callback rather than a value because the registry only
+ * exists once `createTestUiServer` calls `configureRegistry`, which happens
+ * after the options object is constructed.
+ *
+ * @param getRegistry     returns the live registry, or null before setup
+ * @param passthrough     when true, unknown node types echo their inputs
+ *                        through instead of throwing (e.g. `test.Input`)
+ */
+export declare function createFakeExecutorResolver(getRegistry: () => NodeRegistry | null, { passthrough }?: {
+    passthrough?: boolean;
+}): (node: NodeDescriptor) => NodeExecutor;
+export {};
+//# sourceMappingURL=fake-runtime.d.ts.map

package/dist/fake-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-runtime.d.ts","sourceRoot":"","sources":["../src/fake-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,gBAAgB,EAKhB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEzE;qDACqD;AACrD,eAAO,MAAM,eAAe,qGACwE,CAAC;AAErG,sEAAsE;AACtE,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAE1D,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AA2B3D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAQzD;AAED,gFAAgF;AAChF,qBAAa,YAAa,SAAQ,gBAAgB;IAChD,YAAY,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAoB5C;IAED;;;;;OAKG;IACa,gBAAgB,CAC9B,IAAI,EAAE,UAAU,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,GACxD,cAAc,CAAC,kBAAkB,CAAC,CAOpC;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,QAAa,OAAO,CAAC,YAAY,CAC7C,CAAC;AAsCrB,UAAU,QAAQ;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACpC,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACnE,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;CACvE;AA6BD,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,KAAK,EAAE,GACP,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAiC5D;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAC7C,YAAY,CAgCd;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,GAAG,SAAS,GACzB,OAAO,CAUT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,YAAY,GAAG,IAAI,EACtC,EAAE,WAAkB,EAAE,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACrD,CAAC,IAAI,EAAE,cAAc,KAAK,YAAY,CAsBxC"}