@nodetool-ai/node-sdk 0.7.0-rc.11

package/dist/python-package-scan.js

@@ -0,0 +1,158 @@
+/**
+ * Scan a nodetool Python node package by invoking `nodetool.package_tools`
+ * (shipped inside `nodetool-core`) as a one-shot subprocess.
+ *
+ * Produces a `PackageMetadata` (same shape as what `loadPythonPackageMetadata`
+ * reads back from disk). Does not require a running server.
+ */
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export class PythonScanError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = "PythonScanError";
+    }
+}
+/**
+ * Run `python -m nodetool.package_tools scan` and return the parsed result.
+ *
+ * Requires `nodetool-core` to be installed in the target Python environment.
+ */
+export async function scanPythonPackage(opts) {
+    const python = opts.python ?? resolvePythonBin();
+    const args = [
+        "-m",
+        "nodetool.package_tools",
+        "scan",
+        "--package-dir",
+        opts.packageDir
+    ];
+    if (opts.enrich)
+        args.push("--enrich");
+    if (opts.write)
+        args.push("--write");
+    if (opts.verbose)
+        args.push("--verbose");
+    return await new Promise((resolve, reject) => {
+        const child = spawn(python, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            signal: opts.signal
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stderrBuffer = "";
+        child.stdout.on("data", (chunk) => {
+            stdoutChunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrChunks.push(chunk);
+            if (opts.onProgress) {
+                stderrBuffer += chunk.toString("utf8");
+                let idx;
+                while ((idx = stderrBuffer.indexOf("\n")) !== -1) {
+                    const line = stderrBuffer.slice(0, idx).trimEnd();
+                    stderrBuffer = stderrBuffer.slice(idx + 1);
+                    if (line.startsWith("SCAN"))
+                        opts.onProgress(line);
+                }
+            }
+        });
+        child.once("error", (err) => {
+            reject(new PythonScanError(`Failed to spawn python: ${err.message}`, null, Buffer.concat(stderrChunks).toString("utf8")));
+        });
+        child.once("close", (code) => {
+            const stderr = Buffer.concat(stderrChunks).toString("utf8");
+            if (code !== 0) {
+                reject(new PythonScanError(`nodetool-pkg scan exited with code ${code}`, code, stderr));
+                return;
+            }
+            try {
+                let metadata;
+                if (opts.write) {
+                    // --write: no JSON on stdout; read the file the scanner wrote.
+                    const name = findWrittenMetadataName(stderr);
+                    if (!name) {
+                        throw new Error("scanner did not report a SCAN write path line");
+                    }
+                    const metadataPath = join(opts.packageDir, "src", "nodetool", "package_metadata", `${name}.json`);
+                    metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+                }
+                else {
+                    const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+                    metadata = JSON.parse(stdout);
+                }
+                resolve({ metadata, stderr });
+            }
+            catch (e) {
+                reject(new PythonScanError(`Failed to parse scanner output: ${String(e)}`, code, stderr));
+            }
+        });
+    });
+}
+/**
+ * Parse "SCAN write path=/.../<name>.json" and return "<name>".
+ */
+function findWrittenMetadataName(stderr) {
+    const match = stderr.match(/SCAN write path=(.+\/([^/\\]+)\.json)\s*$/m);
+    return match?.[2] ?? null;
+}
+/**
+ * Resolve a Python executable, matching the convention used by
+ * `PythonStdioBridge` in `@nodetool-ai/runtime`.
+ */
+export function resolvePythonBin() {
+    const explicit = process.env["NODETOOL_PYTHON"];
+    if (explicit)
+        return explicit;
+    const condaPrefix = process.env["CONDA_PREFIX"];
+    if (condaPrefix && looksLikeNodetoolEnv(condaPrefix)) {
+        const bin = process.platform === "win32"
+            ? join(condaPrefix, "python.exe")
+            : join(condaPrefix, "bin", "python");
+        if (existsSync(bin))
+            return bin;
+    }
+    for (const candidate of managedCandidates()) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return "python";
+}
+function looksLikeNodetoolEnv(envPath) {
+    const normalized = envPath.replaceAll("\\", "/").toLowerCase();
+    const name = basename(envPath).toLowerCase();
+    return (name === "nodetool" ||
+        name === "conda_env" ||
+        normalized.includes("/nodetool/conda_env"));
+}
+function managedCandidates() {
+    const home = homedir();
+    if (process.platform === "darwin") {
+        return [
+            join(home, "nodetool_env", "bin", "python"),
+            join(home, "miniconda3", "envs", "nodetool", "bin", "python"),
+            join(home, "anaconda3", "envs", "nodetool", "bin", "python"),
+            join(home, "conda", "envs", "nodetool", "bin", "python")
+        ];
+    }
+    if (process.platform === "linux") {
+        return [
+            join(home, ".local", "share", "nodetool", "conda_env", "bin", "python"),
+            "/opt/nodetool/conda_env/bin/python",
+            join(home, "miniconda3", "envs", "nodetool", "bin", "python"),
+            join(home, "anaconda3", "envs", "nodetool", "bin", "python")
+        ];
+    }
+    return [
+        join(home, "Miniconda3", "envs", "nodetool", "python.exe"),
+        join(home, "miniconda3", "envs", "nodetool", "python.exe"),
+        join(home, "Anaconda3", "envs", "nodetool", "python.exe")
+    ];
+}
+//# sourceMappingURL=python-package-scan.js.map

package/dist/python-package-scan.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,55 @@
+import type { NodeDescriptor } from "@nodetool-ai/protocol";
+import type { NodeExecutor, ResolvedNodeType } from "@nodetool-ai/kernel";
+import type { NodeClass } from "./base-node.js";
+import type { NodeMetadata, PythonMetadataLoadOptions, PythonMetadataLoadResult } from "./metadata.js";
+import type { NodePropertyValidationIssue } from "./validation.js";
+export interface NodeRegistryOptions {
+    metadataByType?: Map<string, NodeMetadata>;
+    strictMetadata?: boolean;
+}
+export interface RegisterNodeOptions {
+    metadata?: NodeMetadata;
+}
+export interface RegistryGraphResolverOptions {
+    loadNamespace?: (namespace: string, registry: NodeRegistry) => Promise<void> | void;
+}
+export declare class NodeRegistry {
+    private _classes;
+    private _loadedMetadataByType;
+    private _registeredMetadataByType;
+    private _strictMetadata;
+    constructor(options?: NodeRegistryOptions);
+    register(nodeClass: NodeClass, options?: RegisterNodeOptions): void;
+    /**
+     * Validate a node descriptor against its registered class's @prop schema.
+     *
+     * Returns an empty array when:
+     *   - the class is not registered (the runner will surface that elsewhere), or
+     *   - all required/model fields are populated.
+     */
+    validateNode(descriptor: NodeDescriptor, connectedHandles?: ReadonlySet<string> | ReadonlyArray<string>): NodePropertyValidationIssue[];
+    /**
+     * Create a validator function compatible with WorkflowRunnerOptions.validateNode.
+     * Bound to this registry, so the runner can call it without holding a
+     * reference to the registry itself.
+     */
+    createNodeValidator(): (descriptor: NodeDescriptor, connectedHandles: ReadonlySet<string>) => NodePropertyValidationIssue[];
+    resolve(descriptor: NodeDescriptor): NodeExecutor;
+    getClass(nodeType: string): NodeClass | undefined;
+    has(nodeType: string): boolean;
+    list(): string[];
+    getMetadata(nodeType: string): NodeMetadata | undefined;
+    resolveMetadata(nodeType: string): NodeMetadata | undefined;
+    listMetadata(): NodeMetadata[];
+    listRegisteredNodeTypesWithoutMetadata(): string[];
+    /** Add or replace metadata for a node type (e.g. from Python bridge). */
+    loadMetadata(nodeType: string, metadata: NodeMetadata): void;
+    loadPythonMetadata(options?: PythonMetadataLoadOptions): PythonMetadataLoadResult;
+    clear(): void;
+    static readonly global: NodeRegistry;
+}
+export declare function register(nodeClass: NodeClass): void;
+export declare function createGraphNodeTypeResolver(registry: NodeRegistry, options?: RegistryGraphResolverOptions): {
+    resolveNodeType: (nodeType: string) => Promise<ResolvedNodeType | null>;
+};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,YAAY,EACZ,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,CACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,YAAY,KACnB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,qBAAqB,CAAmC;IAChE,OAAO,CAAC,yBAAyB,CAAmC;IACpE,OAAO,CAAC,eAAe,CAAU;gBAErB,OAAO,GAAE,mBAAwB;IAS7C,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI;IAqBvE;;;;;;OAMG;IACH,YAAY,CACV,UAAU,EAAE,cAAc,EAC1B,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,GAC7D,2BAA2B,EAAE;IAWhC;;;;OAIG;IACH,mBAAmB,IAAI,CACrB,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,KAClC,2BAA2B,EAAE;IAKlC,OAAO,CAAC,UAAU,EAAE,cAAc,GAAG,YAAY;IAgBjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIjD,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B,IAAI,IAAI,MAAM,EAAE;IAIhB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAOvD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAS3D,YAAY,IAAI,YAAY,EAAE;IAc9B,sCAAsC,IAAI,MAAM,EAAE;IAMlD,yEAAyE;IACzE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAI5D,kBAAkB,CAChB,OAAO,GAAE,yBAA8B,GACtC,wBAAwB;IAQ3B,KAAK,IAAI,IAAI;IAMb,MAAM,CAAC,QAAQ,CAAC,MAAM,eAAsB;CAC7C;AAED,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAEnD;AAoBD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,4BAAiC,GACzC;IAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CAAE,CA2D7E"}

package/dist/registry.js

@@ -0,0 +1,188 @@
+import { loadPythonPackageMetadata } from "./metadata.js";
+import { getNodeMetadata } from "./node-metadata.js";
+export class NodeRegistry {
+    _classes = new Map();
+    _loadedMetadataByType = new Map();
+    _registeredMetadataByType = new Map();
+    _strictMetadata;
+    constructor(options = {}) {
+        this._strictMetadata = options.strictMetadata ?? false;
+        if (options.metadataByType) {
+            for (const [nodeType, metadata] of options.metadataByType.entries()) {
+                this._loadedMetadataByType.set(nodeType, metadata);
+            }
+        }
+    }
+    register(nodeClass, options = {}) {
+        if (!nodeClass.nodeType) {
+            throw new Error(`Cannot register node class without nodeType: ${nodeClass.name}`);
+        }
+        // TS class definitions are the source of truth for TS nodes.
+        // Python metadata is NOT merged — it is only used for Python-only
+        // node packs (huggingface, mlx, etc.) that have no TS class.
+        const metadata = options.metadata ?? getNodeMetadata(nodeClass);
+        if (metadata) {
+            this._registeredMetadataByType.set(nodeClass.nodeType, metadata);
+        }
+        else if (this._strictMetadata) {
+            throw new Error(`Missing resolved metadata for node type: ${nodeClass.nodeType}`);
+        }
+        this._classes.set(nodeClass.nodeType, nodeClass);
+    }
+    /**
+     * Validate a node descriptor against its registered class's @prop schema.
+     *
+     * Returns an empty array when:
+     *   - the class is not registered (the runner will surface that elsewhere), or
+     *   - all required/model fields are populated.
+     */
+    validateNode(descriptor, connectedHandles) {
+        const NodeClass = this._classes.get(descriptor.type);
+        if (!NodeClass)
+            return [];
+        const properties = descriptor.properties ?? {};
+        return NodeClass.validateProperties(properties, {
+            connectedHandles,
+            nodeId: descriptor.id
+        });
+    }
+    /**
+     * Create a validator function compatible with WorkflowRunnerOptions.validateNode.
+     * Bound to this registry, so the runner can call it without holding a
+     * reference to the registry itself.
+     */
+    createNodeValidator() {
+        return (descriptor, connectedHandles) => this.validateNode(descriptor, connectedHandles);
+    }
+    resolve(descriptor) {
+        const NodeClass = this._classes.get(descriptor.type);
+        if (!NodeClass) {
+            throw new Error(`Unknown node type: ${descriptor.type}`);
+        }
+        const instance = new NodeClass(descriptor.properties ?? {});
+        instance.__node_id = descriptor.id;
+        instance.__node_name = descriptor.name ?? descriptor.type;
+        if (descriptor.dynamic_outputs) {
+            instance._dynamic_outputs = descriptor.dynamic_outputs;
+        }
+        return instance.toExecutor();
+    }
+    getClass(nodeType) {
+        return this._classes.get(nodeType);
+    }
+    has(nodeType) {
+        return this._classes.has(nodeType);
+    }
+    list() {
+        return [...this._classes.keys()];
+    }
+    getMetadata(nodeType) {
+        return (this._registeredMetadataByType.get(nodeType) ??
+            this._loadedMetadataByType.get(nodeType));
+    }
+    resolveMetadata(nodeType) {
+        const exact = this.getMetadata(nodeType);
+        if (exact)
+            return exact;
+        if (nodeType.endsWith("Node")) {
+            return this.getMetadata(nodeType.slice(0, -4));
+        }
+        return undefined;
+    }
+    listMetadata() {
+        const merged = new Map();
+        for (const [nodeType, metadata] of this._loadedMetadataByType.entries()) {
+            merged.set(nodeType, metadata);
+        }
+        for (const [nodeType, metadata] of this._registeredMetadataByType.entries()) {
+            merged.set(nodeType, metadata);
+        }
+        return [...merged.values()];
+    }
+    listRegisteredNodeTypesWithoutMetadata() {
+        return this.list().filter((nodeType) => this.getMetadata(nodeType) === undefined);
+    }
+    /** Add or replace metadata for a node type (e.g. from Python bridge). */
+    loadMetadata(nodeType, metadata) {
+        this._loadedMetadataByType.set(nodeType, metadata);
+    }
+    loadPythonMetadata(options = {}) {
+        const loaded = loadPythonPackageMetadata(options);
+        for (const [nodeType, metadata] of loaded.nodesByType.entries()) {
+            this._loadedMetadataByType.set(nodeType, metadata);
+        }
+        return loaded;
+    }
+    clear() {
+        this._classes.clear();
+        this._loadedMetadataByType.clear();
+        this._registeredMetadataByType.clear();
+    }
+    static global = new NodeRegistry();
+}
+export function register(nodeClass) {
+    NodeRegistry.global.register(nodeClass);
+}
+function typeMetadataToString(typeMeta) {
+    const args = (typeMeta.type_args ?? [])
+        .map(typeMetadataToString)
+        .filter(Boolean);
+    return args.length > 0
+        ? `${typeMeta.type}[${args.join(", ")}]`
+        : typeMeta.type;
+}
+function deriveNamespace(nodeType) {
+    const lastDot = nodeType.lastIndexOf(".");
+    return lastDot > 0 ? nodeType.slice(0, lastDot) : "";
+}
+export function createGraphNodeTypeResolver(registry, options = {}) {
+    return {
+        resolveNodeType: async (nodeType) => {
+            let metadata = registry.resolveMetadata(nodeType);
+            if (!metadata) {
+                const namespace = deriveNamespace(nodeType);
+                if (namespace && options.loadNamespace) {
+                    await options.loadNamespace(namespace, registry);
+                    metadata = registry.resolveMetadata(nodeType);
+                }
+            }
+            if (!metadata)
+                return null;
+            const propertyTypes = Object.fromEntries((metadata.properties ?? []).map((prop) => [
+                prop.name,
+                typeMetadataToString(prop.type)
+            ]));
+            const propertyMeta = Object.fromEntries((metadata.properties ?? [])
+                .filter((p) => p.description || p.min != null || p.max != null)
+                .map((p) => [
+                p.name,
+                {
+                    ...(p.description ? { description: p.description } : {}),
+                    ...(p.min != null ? { min: p.min } : {}),
+                    ...(p.max != null ? { max: p.max } : {})
+                }
+            ]));
+            const outputs = Object.fromEntries((metadata.outputs ?? []).map((output) => [
+                output.name,
+                typeMetadataToString(output.type)
+            ]));
+            const NodeClass = registry.getClass(nodeType);
+            const syncMode = NodeClass?.syncMode;
+            return {
+                nodeType: metadata.node_type,
+                propertyTypes,
+                outputs,
+                isDynamic: metadata.is_dynamic ?? false,
+                descriptorDefaults: {
+                    name: metadata.title,
+                    ...(metadata.is_streaming_input && { is_streaming_input: true }),
+                    ...(metadata.is_streaming_output && { is_streaming_output: true }),
+                    ...(metadata.is_controlled && { is_controlled: true }),
+                    ...(syncMode !== undefined && { sync_mode: syncMode }),
+                    ...(Object.keys(propertyMeta).length > 0 && { propertyMeta })
+                }
+            };
+        }
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/search.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Namespace-aware scorer for node metadata search.
+ *
+ * Used by the agent's local search tool to bias results toward
+ * provider-agnostic core nodes (`nodetool.*`) and away from provider-specific
+ * nodes (`openai.*`, `anthropic.*`, `gemini.*`, etc.).
+ *
+ * Pure functions only — no provider or runtime imports — so this module can
+ * live in node-sdk and be consumed by any package that has node metadata.
+ */
+import type { NodeMetadata } from "./metadata.js";
+/**
+ * Root namespace prefixes that identify provider-specific node packages.
+ * Nodes whose namespace starts with one of these (e.g. `openai.tts`,
+ * `anthropic.agents`, `replicate.image`) are treated as provider nodes.
+ *
+ * The agent's search tool hides these by default; users browsing the node
+ * picker UI still see them via the unbiased HTTP endpoint.
+ */
+export declare const PROVIDER_NAMESPACES: readonly string[];
+export type NamespaceClass = "core" | "provider" | "other";
+/**
+ * Classify a node namespace into one of three buckets used for ranking.
+ * - `core`: starts with `nodetool.` (the curated, provider-agnostic surface)
+ * - `provider`: root segment is in `PROVIDER_NAMESPACES`
+ * - `other`: utility libs like `lib.*`, third-party `mcp.*`, etc.
+ */
+export declare function namespaceClass(namespace: string | undefined): NamespaceClass;
+export interface ScoreOptions {
+    /** Include provider-specific nodes in results (default: false). */
+    includeProviderNodes?: boolean;
+    /**
+     * Restrict to nodes whose namespace starts with this prefix.
+     * Applied as a hard filter before scoring.
+     */
+    namespacePrefix?: string;
+}
+/**
+ * Score a node against a list of search terms.
+ * Returns 0 if the node should be hidden (no match, or provider node when
+ * `includeProviderNodes` is false). Higher is more relevant.
+ *
+ * Terms are matched case-insensitively. Each matching field contributes
+ * `FIELD_WEIGHTS[field]` plus an exact-token bonus when the term appears as a
+ * whole token. Core (`nodetool.*`) namespaces get a 1.5× multiplier.
+ */
+export declare function scoreNodeMetadata(meta: NodeMetadata, terms: readonly string[], options?: ScoreOptions): number;
+export interface ScoredNode<T extends NodeMetadata = NodeMetadata> {
+    meta: T;
+    score: number;
+}
+/**
+ * Score and rank a list of node metadata against search terms.
+ * Returns nodes with score > 0, sorted by score descending; ties broken
+ * alphabetically on `node_type` for deterministic output.
+ */
+export declare function rankNodeMetadata<T extends NodeMetadata>(nodes: readonly T[], terms: readonly string[], options?: ScoreOptions): ScoredNode<T>[];
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAgBhD,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAQ5E;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,YAAiB,GACzB,MAAM,CAyBR;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IAC/D,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,YAAY,EACrD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,YAAiB,GACzB,UAAU,CAAC,CAAC,CAAC,EAAE,CAWjB"}

package/dist/search.js

@@ -0,0 +1,127 @@
+/**
+ * Namespace-aware scorer for node metadata search.
+ *
+ * Used by the agent's local search tool to bias results toward
+ * provider-agnostic core nodes (`nodetool.*`) and away from provider-specific
+ * nodes (`openai.*`, `anthropic.*`, `gemini.*`, etc.).
+ *
+ * Pure functions only — no provider or runtime imports — so this module can
+ * live in node-sdk and be consumed by any package that has node metadata.
+ */
+/**
+ * Root namespace prefixes that identify provider-specific node packages.
+ * Nodes whose namespace starts with one of these (e.g. `openai.tts`,
+ * `anthropic.agents`, `replicate.image`) are treated as provider nodes.
+ *
+ * The agent's search tool hides these by default; users browsing the node
+ * picker UI still see them via the unbiased HTTP endpoint.
+ */
+export const PROVIDER_NAMESPACES = [
+    "openai",
+    "anthropic",
+    "gemini",
+    "mistral",
+    "groq",
+    "cohere",
+    "voyage",
+    "huggingface",
+    "fal",
+    "replicate",
+    "kie",
+    "comfyui",
+    "apify",
+    "messaging",
+    "search"
+];
+const PROVIDER_NAMESPACE_SET = new Set(PROVIDER_NAMESPACES);
+/**
+ * Classify a node namespace into one of three buckets used for ranking.
+ * - `core`: starts with `nodetool.` (the curated, provider-agnostic surface)
+ * - `provider`: root segment is in `PROVIDER_NAMESPACES`
+ * - `other`: utility libs like `lib.*`, third-party `mcp.*`, etc.
+ */
+export function namespaceClass(namespace) {
+    if (!namespace)
+        return "other";
+    if (namespace.startsWith("nodetool.") || namespace === "nodetool") {
+        return "core";
+    }
+    const root = namespace.split(".")[0] ?? "";
+    if (PROVIDER_NAMESPACE_SET.has(root))
+        return "provider";
+    return "other";
+}
+const FIELD_WEIGHTS = {
+    title: 6,
+    nodeType: 4,
+    namespace: 2,
+    description: 1
+};
+const EXACT_TOKEN_BONUS = 2;
+const CORE_MULTIPLIER = 1.5;
+function fieldScore(field, term, weight) {
+    if (!field)
+        return 0;
+    const lower = field.toLowerCase();
+    if (!lower.includes(term))
+        return 0;
+    let score = weight;
+    // Exact-token bonus: term appears as a whole word/segment.
+    const tokens = lower.split(/[\s._\-/]+/).filter(Boolean);
+    if (tokens.includes(term))
+        score += weight * EXACT_TOKEN_BONUS;
+    return score;
+}
+/**
+ * Score a node against a list of search terms.
+ * Returns 0 if the node should be hidden (no match, or provider node when
+ * `includeProviderNodes` is false). Higher is more relevant.
+ *
+ * Terms are matched case-insensitively. Each matching field contributes
+ * `FIELD_WEIGHTS[field]` plus an exact-token bonus when the term appears as a
+ * whole token. Core (`nodetool.*`) namespaces get a 1.5× multiplier.
+ */
+export function scoreNodeMetadata(meta, terms, options = {}) {
+    if (terms.length === 0)
+        return 0;
+    if (options.namespacePrefix &&
+        !(meta.namespace ?? "").startsWith(options.namespacePrefix)) {
+        return 0;
+    }
+    const cls = namespaceClass(meta.namespace);
+    if (cls === "provider" && !options.includeProviderNodes)
+        return 0;
+    let raw = 0;
+    for (const rawTerm of terms) {
+        const term = rawTerm.toLowerCase();
+        if (!term)
+            continue;
+        raw += fieldScore(meta.title, term, FIELD_WEIGHTS.title);
+        raw += fieldScore(meta.node_type, term, FIELD_WEIGHTS.nodeType);
+        raw += fieldScore(meta.namespace, term, FIELD_WEIGHTS.namespace);
+        raw += fieldScore(meta.description, term, FIELD_WEIGHTS.description);
+    }
+    if (raw === 0)
+        return 0;
+    return cls === "core" ? raw * CORE_MULTIPLIER : raw;
+}
+/**
+ * Score and rank a list of node metadata against search terms.
+ * Returns nodes with score > 0, sorted by score descending; ties broken
+ * alphabetically on `node_type` for deterministic output.
+ */
+export function rankNodeMetadata(nodes, terms, options = {}) {
+    const scored = [];
+    for (const meta of nodes) {
+        const score = scoreNodeMetadata(meta, terms, options);
+        if (score > 0)
+            scored.push({ meta, score });
+    }
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.meta.node_type.localeCompare(b.meta.node_type);
+    });
+    return scored;
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

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