@net-mesh/core 0.26.0 → 0.27.0-beta.2

package/tool.js

@@ -0,0 +1,554 @@
+"use strict";
+// TypeScript layer for AI tool calling on net.
+//
+// Wraps the existing `TypedMeshRpc` napi surface with the `tool()` /
+// `callTool()` ergonomic helpers + format translators that lower
+// `ToolDescriptor`s to OpenAI / Anthropic / MCP / Gemini tool shapes
+// and parse provider tool-call replies back into nRPC dispatches.
+//
+// This is the Wave 3 / B-1 + B-4 starting point. v1 covers unary
+// register + invoke + format conversion. Streaming (B-2) and
+// discovery (B-3 list_tools / watch_tools) follow once the
+// underlying napi surface exposes them; today the only available
+// streaming primitive is direct-addressed (`callStreaming(nodeId,
+// ...)`), so capability-routed streaming has to wait on a
+// `callServiceStreaming` TS wrapper or a `findServiceNodes` +
+// direct-call composition (TODO).
+//
+// Plan: see
+// `crates/net/docs/plans/NRPC_AI_TOOL_CALLING_AND_AGENT_DX.md`,
+// slices B-1 / B-2 / B-4. Mirror of the Rust SDK's
+// `net_sdk::tool` + `net_sdk::tool::formats` modules — cross-
+// language tests (T-1) will pin byte equality across both.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gemini = exports.mcp = exports.anthropic = exports.openai = exports.ToolCallParseError = exports.TOOL_METADATA_FETCH_SERVICE = void 0;
+exports.isTerminalEvent = isTerminalEvent;
+exports.descriptorFrom = descriptorFrom;
+exports.serveTool = serveTool;
+exports.serveToolStreaming = serveToolStreaming;
+exports.callTool = callTool;
+exports.callToolStreaming = callToolStreaming;
+exports.addToolCapabilitiesToAnnounce = addToolCapabilitiesToAnnounce;
+exports.listTools = listTools;
+exports.watchTools = watchTools;
+exports.fetchToolMetadata = fetchToolMetadata;
+/** True if `event` is a terminal envelope (`result` or `error`). */
+function isTerminalEvent(event) {
+    return event.type === 'result' || event.type === 'error';
+}
+/** Construct a [`ToolDescriptor`] from a `ToolOptions` literal. */
+function descriptorFrom(options) {
+    return {
+        toolId: options.name,
+        name: options.name,
+        version: options.version ?? '1.0.0',
+        description: options.description,
+        inputSchema: options.inputSchema ? JSON.stringify(options.inputSchema) : undefined,
+        outputSchema: options.outputSchema ? JSON.stringify(options.outputSchema) : undefined,
+        requires: options.requires ?? [],
+        estimatedTimeMs: options.estimatedTimeMs ?? 0,
+        stateless: options.stateless ?? true,
+        streaming: false,
+        tags: options.tags ?? [],
+        nodeCount: 0,
+    };
+}
+const _toolRegistries = new WeakMap();
+function _ensureFetchInstalled(rpc) {
+    let entry = _toolRegistries.get(rpc);
+    if (entry)
+        return entry;
+    entry = { registry: new Map(), fetchHandle: null };
+    _toolRegistries.set(rpc, entry);
+    // Register the fetch handler. The handler queries `entry.registry`
+    // for the name; falls back to NotFound. Mirrors the Rust SDK's
+    // `tool.metadata.fetch` handler shape.
+    try {
+        entry.fetchHandle = rpc.serve(exports.TOOL_METADATA_FETCH_SERVICE, (req) => {
+            const d = entry.registry.get(req.name);
+            return d
+                ? { type: 'found', descriptor: d }
+                : { type: 'not_found', name: req.name };
+        });
+    }
+    catch {
+        // If install fails (e.g. another caller already registered the
+        // service manually), leave fetchHandle null. Subsequent serveTool
+        // calls retry. Silent because the failure is recoverable +
+        // observable via `fetchToolMetadata` returning NoRoute / NotFound
+        // on the agent side.
+    }
+    return entry;
+}
+/**
+ * Register an AI tool against `rpc`. The handler is registered as
+ * an nRPC service at `descriptor.toolId` with JSON codec (same as
+ * the Rust SDK's `Mesh::serve_tool`).
+ *
+ * Atomically:
+ * 1. Inserts the descriptor into a per-rpc local registry keyed on
+ *    `toolId`. The next [`fetchToolMetadata`] call against this
+ *    host can resolve the descriptor by name.
+ * 2. Registers the typed handler at `toolId` with JSON codec.
+ * 3. On the FIRST `serveTool` call against this rpc, lazy-
+ *    installs the `tool.metadata.fetch` nRPC service handler so
+ *    remote agents can pull the full descriptor for any
+ *    registered tool. Subsequent `serveTool` calls reuse the
+ *    same fetch handler. Mirrors the Rust SDK's
+ *    `ensure_tool_metadata_fetch_installed` pattern.
+ *
+ * The caller is still responsible for announcing the tool to
+ * peers — use [`addToolCapabilitiesToAnnounce`] on the
+ * `CapabilitySetJs` you pass to `mesh.announceCapabilities(...)`.
+ *
+ * On `handle.close()`: removes the descriptor from the per-rpc
+ * registry and unregisters the handler. The lazy `tool.metadata.fetch`
+ * service stays installed for the lifetime of the rpc — harmless
+ * when empty (returns NotFound for every request).
+ */
+function serveTool(rpc, options, handler) {
+    const descriptor = descriptorFrom(options);
+    const entry = _ensureFetchInstalled(rpc);
+    entry.registry.set(descriptor.toolId, descriptor);
+    const inner = rpc.serve(descriptor.toolId, handler);
+    let closed = false;
+    return {
+        descriptor,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            entry.registry.delete(descriptor.toolId);
+            inner.close();
+        },
+    };
+}
+/**
+ * Register a streaming tool handler. The handler is an async
+ * generator that yields ToolEvents — each yielded event is
+ * forwarded to the caller via `callToolStreaming` (or any other
+ * client that drains a `tool.metadata.fetch`-discoverable
+ * streaming service).
+ *
+ * Atomic register + lazy auto-install of `tool.metadata.fetch` —
+ * same pattern as `serveTool` for unary handlers. Stamps
+ * `streaming: true` on the descriptor so peers can discover the
+ * streaming variant explicitly.
+ */
+function serveToolStreaming(rpc, options, handler) {
+    const baseDescriptor = descriptorFrom(options);
+    const descriptor = { ...baseDescriptor, streaming: true };
+    const entry = _ensureFetchInstalled(rpc);
+    entry.registry.set(descriptor.toolId, descriptor);
+    const inner = rpc.serveStreaming(descriptor.toolId, async (req, sink) => {
+        let sawTerminal = false;
+        try {
+            for await (const event of handler(req)) {
+                sink.send(event);
+                if (isTerminalEvent(event))
+                    sawTerminal = true;
+            }
+            if (!sawTerminal) {
+                sink.send({
+                    type: 'error',
+                    code: 'missing_terminal',
+                    message: 'tool stream ended without a terminal result or error envelope',
+                });
+            }
+        }
+        catch (err) {
+            // Convert handler exceptions into a terminal error envelope
+            // so the caller sees a typed error rather than relying on
+            // the client-side missing_terminal fallback.
+            const message = err instanceof Error ? err.message : String(err);
+            const errEvent = {
+                type: 'error',
+                code: 'handler_error',
+                message,
+            };
+            sink.send(errEvent);
+        }
+    });
+    let closed = false;
+    return {
+        descriptor,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            entry.registry.delete(descriptor.toolId);
+            inner.close();
+        },
+    };
+}
+/**
+ * Capability-routed unary tool invocation. Encodes `req` as JSON
+ * (the codec every AI provider consumes for tool input/output),
+ * dispatches via `rpc.callService(toolId, req, opts)`.
+ *
+ * Throws `NoRouteError` if no host advertises `nrpc:<toolId>` in
+ * the local capability fold; bubbles handler errors as
+ * `RpcServerError` with the typed-handler status code.
+ */
+async function callTool(rpc, toolId, req, opts) {
+    return rpc.callService(toolId, req, opts);
+}
+/**
+ * Capability-routed streaming tool invocation. Returns an
+ * `AsyncIterable<ToolEvent>` — drain via `for await (...)` until
+ * the stream terminates. The substrate routes the call via the
+ * cap-auth gate just like `callService`; the iterator yields each
+ * JSON-decoded `ToolEvent` envelope.
+ *
+ * Synthesizes a terminal `error` event with code
+ * `missing_terminal` if the stream ends without a `result` /
+ * `error` envelope — matches the Rust SDK's `serve_tool_streaming`
+ * contract and the T-2 cross-language fixture.
+ *
+ * Cancel mid-stream by aborting `opts.signal` (wired through the
+ * substrate's cancel-registry on the underlying RpcStream).
+ */
+async function* callToolStreaming(rpc, toolId, req, opts) {
+    const stream = await rpc.callServiceStreaming(toolId, req, opts);
+    let sawTerminal = false;
+    try {
+        for await (const event of stream) {
+            yield event;
+            if (isTerminalEvent(event)) {
+                sawTerminal = true;
+            }
+        }
+    }
+    finally {
+        await stream.close().catch(() => { });
+    }
+    if (!sawTerminal) {
+        const synthesized = {
+            type: 'error',
+            code: 'missing_terminal',
+            message: 'tool stream ended without a terminal result or error envelope',
+        };
+        yield synthesized;
+    }
+}
+/**
+ * Merge tool descriptors into a `CapabilitySetJs` so the next
+ * `mesh.announceCapabilities(caps)` carries:
+ *
+ * - `ai-tool:<toolId>` tag — peer fold's tag-prefix lookup hits.
+ * - A `ToolJs` entry — peer's `list_tools` walk sees the
+ *   tool's tag-encoded fields.
+ *
+ * Caller still owns the `caps` object — pass it through
+ * `mesh.announceCapabilities(caps)` to publish. Returns the same
+ * object for chaining.
+ *
+ * This is a v1 convenience; once the napi surface exposes
+ * `tool_registry()`, the announce-time merge happens
+ * automatically and this helper becomes optional.
+ */
+function addToolCapabilitiesToAnnounce(caps, descriptors) {
+    if (descriptors.length === 0)
+        return caps;
+    const tags = new Set(caps.tags ?? []);
+    const tools = [...(caps.tools ?? [])];
+    for (const desc of descriptors) {
+        tags.add(`ai-tool:${desc.toolId}`);
+        tools.push({
+            toolId: desc.toolId,
+            name: desc.name,
+            version: desc.version,
+            inputSchema: desc.inputSchema,
+            outputSchema: desc.outputSchema,
+            requires: desc.requires,
+            estimatedTimeMs: desc.estimatedTimeMs,
+            stateless: desc.stateless,
+        });
+    }
+    caps.tags = Array.from(tags);
+    caps.tools = tools;
+    return caps;
+}
+/**
+ * Walk the local capability fold for every published AI tool.
+ * Returns one [`ToolDescriptor`] per `(toolId, version)` slot,
+ * with `nodeCount` filled in by the aggregating walk.
+ *
+ * Pure delegation to the napi binding's `NetMesh.listTools()` (B-3
+ * of the plan). Requires the napi binding's `tool` Cargo feature
+ * (default-on); throws if the underlying mesh wasn't built with it.
+ *
+ * Schemas come back as JSON-encoded strings on
+ * `descriptor.inputSchema` / `descriptor.outputSchema` — call
+ * `JSON.parse(...)` for the parsed shape that adapter packages
+ * consume when lowering into provider-specific tool definitions.
+ */
+function listTools(mesh) {
+    return mesh.listTools();
+}
+/**
+ * Subscribe to a stream of [`ToolListChange`] events for every
+ * dynamic addition / removal / publisher-count change in the
+ * local capability fold's tool view.
+ *
+ * Event-driven: consumes the substrate's `MeshNode::watch_tools`
+ * stream via the napi `ToolWatchIter` — a change is delivered the
+ * moment the fold mutates (latency is bounded by fold-apply, not a
+ * timer), and an idle fold does zero periodic work. The diff happens
+ * substrate-side; this just `JSON.parse`s each emitted change. No
+ * client-side `setTimeout` / `listTools` re-diff loop.
+ *
+ * The native subscription is kicked off eagerly — when `watchTools`
+ * is *called*, not on the first iteration — so a change published
+ * between the call and the first `for await` is not lost (the prior
+ * version subscribed lazily and could drop that first event). Because
+ * the subscription is started at call time, the returned iterable
+ * holds a live substrate watch: consume it (or abort via `signal`) so
+ * it is closed. Call `listTools(mesh)` once for the starting shape.
+ *
+ * Mirror of the Rust SDK's `Mesh::watch_tools(matcher, interval)`
+ * and the Python `watch_tools` — all three are event-driven off the
+ * same substrate change signal, and all three subscribe eagerly.
+ *
+ * Returns an `AsyncIterable<ToolListChange>` suitable for
+ * `for await (const change of watchTools(mesh)) { ... }`. The
+ * iterator ends when `options.signal` aborts, when the stream is
+ * closed, or on an unrecoverable error.
+ */
+function watchTools(mesh, options = {}) {
+    const intervalMs = options.intervalMs;
+    const signal = options.signal;
+    // Subscribe eagerly — at call time, not on the first iteration — so a
+    // change published before iteration begins is still observed. The
+    // generator below awaits this same promise; the extra no-op `.catch`
+    // keeps an unhandled-rejection warning from firing if the returned
+    // iterable is created but never consumed (the generator's own `await`
+    // still surfaces the real rejection to a consumer that does iterate).
+    const nativePromise = mesh.watchTools(intervalMs ?? null);
+    void nativePromise.catch(() => { });
+    async function* iterator() {
+        const native = await nativePromise;
+        const onAbort = () => native.close();
+        if (signal) {
+            if (signal.aborted) {
+                native.close();
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        try {
+            while (true) {
+                const raw = await native.next();
+                if (raw == null) {
+                    return;
+                }
+                yield JSON.parse(raw);
+            }
+        }
+        finally {
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            native.close();
+        }
+    }
+    return { [Symbol.asyncIterator]: iterator };
+}
+/** nRPC service name for the on-demand tool-descriptor pull. */
+exports.TOOL_METADATA_FETCH_SERVICE = 'tool.metadata.fetch';
+/**
+ * Pull a tool's full descriptor from a specific host by calling
+ * the auto-installed `tool.metadata.fetch` nRPC service. Useful
+ * when the local fold's capability-fold entry dropped the schema
+ * (size-budget-exceeded) and the agent needs the full
+ * input/output schemas for strict-mode provider lowering.
+ *
+ * Mirror of calling `mesh.call_typed(host, TOOL_METADATA_FETCH_SERVICE,
+ * { name: tool_id })` in the Rust SDK. The
+ * `tool.metadata.fetch` server-side handler is auto-installed on
+ * the host's first `serveTool` call.
+ */
+async function fetchToolMetadata(rpc, hostNodeId, toolId, opts) {
+    return rpc.call(hostNodeId, exports.TOOL_METADATA_FETCH_SERVICE, { name: toolId }, opts);
+}
+/** Thrown when a provider's tool-call reply doesn't match its spec. */
+class ToolCallParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolCallParseError';
+    }
+}
+exports.ToolCallParseError = ToolCallParseError;
+function inputSchemaValue(desc) {
+    if (!desc.inputSchema)
+        return { type: 'object', properties: {} };
+    try {
+        return JSON.parse(desc.inputSchema);
+    }
+    catch {
+        // Schema string was malformed (shouldn't happen for descriptors
+        // built via `descriptorFrom`). Empty-object fallback keeps
+        // provider validators happy.
+        return { type: 'object', properties: {} };
+    }
+}
+/** OpenAI Chat Completions / Responses API `tools` array. */
+exports.openai = {
+    /**
+     * Lower a descriptor to an OpenAI tool definition. Shape:
+     * ```
+     * { type: "function", function: { name, description, parameters, strict } }
+     * ```
+     * `strict` is true when the descriptor carried an `inputSchema`.
+     */
+    toOpenaiTool(desc) {
+        return {
+            type: 'function',
+            function: {
+                name: desc.toolId,
+                description: desc.description ?? '',
+                parameters: inputSchemaValue(desc),
+                strict: desc.inputSchema !== undefined,
+            },
+        };
+    },
+    /**
+     * Parse one OpenAI `tool_calls[]` entry into a `ToolCallSpec`.
+     * OpenAI's `function.arguments` is a JSON-encoded STRING; this
+     * helper validates it parses up front so malformed payloads fail
+     * fast instead of riding through `callTool`.
+     */
+    lowerOpenaiToolCall(call) {
+        const fn = call['function'];
+        if (!fn)
+            throw new ToolCallParseError('tool-call reply missing field `function`');
+        const name = fn['name'];
+        if (typeof name !== 'string') {
+            throw new ToolCallParseError('tool-call reply field `function.name` must be a string');
+        }
+        const argumentsField = fn['arguments'];
+        if (typeof argumentsField !== 'string') {
+            throw new ToolCallParseError('tool-call reply field `function.arguments` must be a JSON-encoded string');
+        }
+        try {
+            JSON.parse(argumentsField);
+        }
+        catch (e) {
+            throw new ToolCallParseError(`tool-call arguments were not valid JSON: ${e.message}`);
+        }
+        const id = call['id'];
+        return {
+            name,
+            argumentsJson: argumentsField,
+            providerCallId: typeof id === 'string' ? id : undefined,
+        };
+    },
+};
+/** Anthropic Messages API `tools` array + `tool_use` content blocks. */
+exports.anthropic = {
+    /**
+     * Lower a descriptor to an Anthropic tool definition. Shape:
+     * ```
+     * { name, description, input_schema }
+     * ```
+     * No tool-level `strict` flag — Anthropic relies on schema-
+     * validated tool input as the default.
+     */
+    toAnthropicTool(desc) {
+        return {
+            name: desc.toolId,
+            description: desc.description ?? '',
+            input_schema: inputSchemaValue(desc),
+        };
+    },
+    /**
+     * Parse one Anthropic `tool_use` content block into a
+     * `ToolCallSpec`. `input` is already a parsed object (not a
+     * string like OpenAI); re-serializes once to preserve the
+     * `argumentsJson: string` invariant.
+     */
+    lowerAnthropicToolUse(block) {
+        const name = block['name'];
+        if (typeof name !== 'string') {
+            throw new ToolCallParseError('tool_use block field `name` must be a string');
+        }
+        if (!('input' in block)) {
+            throw new ToolCallParseError('tool_use block missing field `input`');
+        }
+        const argumentsJson = JSON.stringify(block['input']);
+        const id = block['id'];
+        return {
+            name,
+            argumentsJson,
+            providerCallId: typeof id === 'string' ? id : undefined,
+        };
+    },
+};
+/** Model Context Protocol `tools/list` + `tools/call`. */
+exports.mcp = {
+    /** Lower a descriptor to an MCP tool definition. Shape: `{ name, description, inputSchema }` (camelCase). */
+    toMcpTool(desc) {
+        return {
+            name: desc.toolId,
+            description: desc.description ?? '',
+            inputSchema: inputSchemaValue(desc),
+        };
+    },
+    /**
+     * Parse an MCP `tools/call` request's `params` into a
+     * `ToolCallSpec`. `providerCallId` is left `undefined` — MCP's
+     * JSON-RPC `id` lives one envelope layer up, threaded
+     * independently.
+     */
+    lowerMcpToolsCall(params) {
+        const name = params['name'];
+        if (typeof name !== 'string') {
+            throw new ToolCallParseError('tools/call params field `name` must be a string');
+        }
+        if (!('arguments' in params)) {
+            throw new ToolCallParseError('tools/call params missing field `arguments`');
+        }
+        return {
+            name,
+            argumentsJson: JSON.stringify(params['arguments']),
+            providerCallId: undefined,
+        };
+    },
+};
+/** Gemini `generateContent` function-calling shape. */
+exports.gemini = {
+    /**
+     * Lower a descriptor to one Gemini `FunctionDeclaration`. Shape:
+     * ```
+     * { name, description, parameters }
+     * ```
+     * Caller wraps these into the outer
+     * `tools: [{ function_declarations: [ … ] }]` array.
+     */
+    toGeminiFunctionDeclaration(desc) {
+        return {
+            name: desc.toolId,
+            description: desc.description ?? '',
+            parameters: inputSchemaValue(desc),
+        };
+    },
+    /**
+     * Parse one Gemini `functionCall` part into a `ToolCallSpec`.
+     * Gemini has no per-call id; the spec leaves `providerCallId`
+     * `undefined` (multi-call sequences are positional).
+     */
+    lowerGeminiFunctionCall(call) {
+        const name = call['name'];
+        if (typeof name !== 'string') {
+            throw new ToolCallParseError('functionCall field `name` must be a string');
+        }
+        if (!('args' in call)) {
+            throw new ToolCallParseError('functionCall missing field `args`');
+        }
+        return {
+            name,
+            argumentsJson: JSON.stringify(call['args']),
+            providerCallId: undefined,
+        };
+    },
+};