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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/core",
-  "version": "0.26.0",
+  "version": "0.27.0-beta.2",
   "description": "High-performance, schema-agnostic event bus for AI runtime workloads",
   "main": "index.js",
   "types": "index.d.ts",
@@ -46,7 +46,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ai-2070/net"
+    "url": "git+https://github.com/ai-2070/net.git"
   },
   "keywords": [
     "event-bus",
@@ -97,13 +97,13 @@
     "node": ">=20"
   },
   "optionalDependencies": {
-    "@net-mesh/core-win32-x64-msvc": "0.26.0",
-    "@net-mesh/core-win32-arm64-msvc": "0.26.0",
-    "@net-mesh/core-darwin-x64": "0.26.0",
-    "@net-mesh/core-darwin-arm64": "0.26.0",
-    "@net-mesh/core-linux-x64-gnu": "0.26.0",
-    "@net-mesh/core-linux-x64-musl": "0.26.0",
-    "@net-mesh/core-linux-arm64-gnu": "0.26.0",
-    "@net-mesh/core-linux-arm64-musl": "0.26.0"
+    "@net-mesh/core-win32-x64-msvc": "0.27.0-beta.2",
+    "@net-mesh/core-win32-arm64-msvc": "0.27.0-beta.2",
+    "@net-mesh/core-darwin-x64": "0.27.0-beta.2",
+    "@net-mesh/core-darwin-arm64": "0.27.0-beta.2",
+    "@net-mesh/core-linux-x64-gnu": "0.27.0-beta.2",
+    "@net-mesh/core-linux-x64-musl": "0.27.0-beta.2",
+    "@net-mesh/core-linux-arm64-gnu": "0.27.0-beta.2",
+    "@net-mesh/core-linux-arm64-musl": "0.27.0-beta.2"
   }
 }

package/tool.d.ts

@@ -0,0 +1,450 @@
+import type { CallOptions, TypedMeshRpc } from './mesh_rpc';
+import type { CapabilitySetJs } from './index';
+/**
+ * Structural shape of the napi `NetMesh.listTools()` return value
+ * — field-for-field the same as [`ToolDescriptor`]. Declared here
+ * (instead of imported from `./index`) so this file compiles
+ * cleanly before `napi build` regenerates `index.d.ts` with the
+ * new `ToolDescriptorJs` export.
+ */
+interface MeshWithListTools {
+    listTools(): ToolDescriptor[];
+}
+/**
+ * Structural shape of the napi `ToolWatchIter` — an async iterator
+ * over the substrate `watch_tools` stream. `next()` resolves to one
+ * JSON-encoded `ToolListChange`, or `null` when the stream ends /
+ * is closed. Declared here so this file compiles before `napi build`
+ * regenerates `index.d.ts` with the `ToolWatchIter` export.
+ */
+interface NativeToolWatchIter {
+    next(): Promise<string | null>;
+    close(): void;
+}
+/**
+ * Structural shape of the napi `NetMesh.watchTools(intervalMs)`
+ * surface consumed by [`watchTools`].
+ */
+interface MeshWithWatchTools {
+    watchTools(intervalMs?: number | null): Promise<NativeToolWatchIter>;
+}
+/**
+ * Discovery shape for an AI tool, as advertised on the capability
+ * fold. One row per `(tool_id, version)`; `nodeCount` is filled by
+ * the aggregating walk (`list_tools` once it lands).
+ *
+ * Schemas are stored as JSON-encoded strings (matching the Rust
+ * substrate's wire shape). Use `JSON.parse(desc.inputSchema)` to
+ * get the parsed JSON Schema object — most consumers want this
+ * for lowering into a provider tool definition.
+ *
+ * Wire-compatible 1:1 with `net::adapter::net::cortex::tool::ToolDescriptor`.
+ */
+export interface ToolDescriptor {
+    /** nRPC service name. Same string `callTool(...)` takes. */
+    toolId: string;
+    /** Human-readable name. Defaults to `toolId` if unset. */
+    name: string;
+    /** Tool version (semver-ish). Defaults to `"1.0.0"`. */
+    version: string;
+    /** Human-readable description; LLMs read this to decide when to call. */
+    description?: string;
+    /** JSON-encoded JSON Schema (draft 2020-12) for the request body. */
+    inputSchema?: string;
+    /** JSON-encoded JSON Schema (draft 2020-12) for the response body. */
+    outputSchema?: string;
+    /** Required capabilities / dependencies (free-form strings). */
+    requires: string[];
+    /** Soft latency hint (ms); `0` = no estimate. */
+    estimatedTimeMs: number;
+    /** True if the tool is a pure function (no session state). */
+    stateless: boolean;
+    /** True if the tool is server-streaming (uses `serveToolStreaming`). */
+    streaming: boolean;
+    /** Free-form host-attached tags (e.g. `["web", "research"]`). */
+    tags: string[];
+    /** How many nodes currently serve this `(toolId, version)`. */
+    nodeCount: number;
+}
+/**
+ * One envelope on a streaming tool. Discriminated by `type`.
+ *
+ * Wire-compatible 1:1 with `net::adapter::net::cortex::tool::ToolEvent`
+ * (JSON tag form, `{"type": "start", …}` shape).
+ *
+ * Every stream ends with exactly one terminal event
+ * (`type: "result"` or `type: "error"`). Handlers that forget emit
+ * a synthesized `{type: "error", code: "missing_terminal", …}` from
+ * the Rust SDK's streaming wrapper.
+ */
+export type ToolEvent = ToolEventStart | ToolEventProgress | ToolEventDelta | ToolEventResult | ToolEventError;
+export interface ToolEventStart {
+    type: 'start';
+    toolId: string;
+    callId?: number;
+    metadata?: unknown;
+}
+export interface ToolEventProgress {
+    type: 'progress';
+    pct?: number;
+    message?: string;
+}
+export interface ToolEventDelta {
+    type: 'delta';
+    data: unknown;
+}
+export interface ToolEventResult {
+    type: 'result';
+    data: unknown;
+}
+export interface ToolEventError {
+    type: 'error';
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/** True if `event` is a terminal envelope (`result` or `error`). */
+export declare function isTerminalEvent(event: ToolEvent): boolean;
+/**
+ * Options for `tool({...})` and `serveTool(rpc, options, handler)`.
+ * Mirror of the Rust `ToolMetadataBuilder` shape — caller supplies
+ * the fields that don't derive from a type signature in JS (no
+ * compile-time type system to introspect, unlike `schemars` in Rust).
+ *
+ * `inputSchema` / `outputSchema` are JSON-Schema-as-object (caller
+ * uses `zod-to-json-schema`, `pydantic`, or hand-rolls); we serialize
+ * to a string before stashing on the descriptor.
+ */
+export interface ToolOptions {
+    /** nRPC service name + tool identifier. Required. */
+    name: string;
+    /** Human-readable description. Strongly recommended. */
+    description?: string;
+    /** Version. Defaults to `"1.0.0"`. */
+    version?: string;
+    /** JSON Schema object for the request. */
+    inputSchema?: object;
+    /** JSON Schema object for the response. */
+    outputSchema?: object;
+    /** Required capabilities / dependencies. */
+    requires?: string[];
+    /** Soft latency hint (ms). */
+    estimatedTimeMs?: number;
+    /** Pure-function flag. Default `true`. */
+    stateless?: boolean;
+    /** Free-form tags. */
+    tags?: string[];
+}
+/** Construct a [`ToolDescriptor`] from a `ToolOptions` literal. */
+export declare function descriptorFrom(options: ToolOptions): ToolDescriptor;
+/**
+ * Handler signature for `serveTool` — receives a decoded request,
+ * returns a decoded response (or a Promise of one).
+ */
+export type ToolHandler<Req = unknown, Resp = unknown> = (req: Req) => Resp | Promise<Resp>;
+/**
+ * Handle returned by `serveTool`. Calling `.close()` deregisters the
+ * underlying nRPC handler (mirror of the Rust `ToolServeHandle`'s
+ * Drop semantics). Calling `.close()` twice is idempotent; the
+ * second call is a no-op.
+ *
+ * NOTE: v1 does NOT yet integrate with the substrate-side
+ * `tool_registry`, so the `ai-tool:<toolId>` capability tag must be
+ * added to the caller's announce explicitly. See
+ * [`addToolCapabilitiesToAnnounce`] for the convention. Once the
+ * napi surface exposes `tool_registry()` insert/remove (a Wave 3
+ * follow-up), this handle will atomically reverse both the
+ * registry insert and the handler registration on `.close()`.
+ */
+export interface ToolServeHandle {
+    /** The descriptor under which the tool was registered. */
+    readonly descriptor: ToolDescriptor;
+    /** Deregister the handler. Idempotent. */
+    close(): void;
+}
+/**
+ * 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).
+ */
+export declare function serveTool<Req = unknown, Resp = unknown>(rpc: TypedMeshRpc, options: ToolOptions, handler: ToolHandler<Req, Resp>): ToolServeHandle;
+/**
+ * Streaming-handler shape for `serveToolStreaming`. The handler
+ * is an async generator that yields `ToolEvent` envelopes — each
+ * yielded event is JSON-encoded and pushed onto the wire via the
+ * substrate's response sink. The generator returning normally is
+ * the "handler done" signal; if the generator never yields a
+ * terminal `result` / `error` envelope, callers see the
+ * synthesized `missing_terminal` error (the T-2 contract).
+ *
+ * Throwing inside the generator maps to a terminal error frame on
+ * the wire; the caller's `callToolStreaming` sees it as a normal
+ * `ToolEvent` with `type: "error"`.
+ */
+export type StreamingToolHandler<Req = unknown> = (req: Req) => AsyncIterable<ToolEvent>;
+/**
+ * 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.
+ */
+export declare function serveToolStreaming<Req = unknown>(rpc: TypedMeshRpc, options: ToolOptions, handler: StreamingToolHandler<Req>): ToolServeHandle;
+/**
+ * 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.
+ */
+export declare function callTool<Req = unknown, Resp = unknown>(rpc: TypedMeshRpc, toolId: string, req: Req, opts?: CallOptions): Promise<Resp>;
+/**
+ * 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).
+ */
+export declare function callToolStreaming<Req = unknown>(rpc: TypedMeshRpc, toolId: string, req: Req, opts?: CallOptions): AsyncGenerator<ToolEvent, void, void>;
+/**
+ * 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.
+ */
+export declare function addToolCapabilitiesToAnnounce(caps: CapabilitySetJs, descriptors: ToolDescriptor[]): CapabilitySetJs;
+/**
+ * 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.
+ */
+export declare function listTools(mesh: MeshWithListTools): ToolDescriptor[];
+/**
+ * One change in the set of tools visible to the local capability
+ * fold. Discriminated union on `type`; identity for diffing is
+ * `(toolId, version)`.
+ *
+ * Wire-compatible 1:1 with the Rust SDK's `ToolListChange` enum
+ * (JSON tag-form `{ "type": "added", "descriptor": {...} }` /
+ * `"removed"` / `"node_count_changed"`).
+ */
+export type ToolListChange = {
+    type: 'added';
+    descriptor: ToolDescriptor;
+} | {
+    type: 'removed';
+    descriptor: ToolDescriptor;
+} | {
+    type: 'node_count_changed';
+    descriptor: ToolDescriptor;
+    prevNodeCount: number;
+};
+/** Options for [`watchTools`]. */
+export interface WatchToolsOptions {
+    /**
+     * Debounce ceiling in milliseconds — NOT a poll cadence.
+     *
+     * Omitted / `0` is pure event-driven: a change is delivered the
+     * moment the capability fold mutates, and an idle fold does zero
+     * periodic work. A positive value additionally guarantees a
+     * re-diff at least every `intervalMs` as a safety net.
+     */
+    intervalMs?: number;
+    /**
+     * `AbortSignal` to end the watch. Aborting closes the underlying
+     * native iterator, which ends the stream promptly.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * 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.
+ */
+export declare function watchTools(mesh: MeshWithWatchTools, options?: WatchToolsOptions): AsyncIterable<ToolListChange>;
+/** nRPC service name for the on-demand tool-descriptor pull. */
+export declare const TOOL_METADATA_FETCH_SERVICE = "tool.metadata.fetch";
+/** Wire-shape variants of `ToolMetadataResponse` (JSON-tagged on
+ * `type`, snake_case). Pinned by the substrate's
+ * `cortex::tool::ToolMetadataResponse` enum.
+ */
+export type ToolMetadataResponse = {
+    type: 'found';
+    descriptor: ToolDescriptor;
+} | {
+    type: 'not_found';
+    name: string;
+};
+/**
+ * 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.
+ */
+export declare function fetchToolMetadata(rpc: TypedMeshRpc, hostNodeId: bigint, toolId: string, opts?: CallOptions): Promise<ToolMetadataResponse>;
+/** Canonical hand-off between a provider adapter and `callTool`. */
+export interface ToolCallSpec {
+    /** nRPC tool_id to invoke. */
+    name: string;
+    /** JSON-encoded arguments to pass to `callTool` (caller parses). */
+    argumentsJson: string;
+    /** Provider-supplied call id when present (for reply correlation). */
+    providerCallId?: string;
+}
+/** Thrown when a provider's tool-call reply doesn't match its spec. */
+export declare class ToolCallParseError extends Error {
+    constructor(message: string);
+}
+/** OpenAI Chat Completions / Responses API `tools` array. */
+export declare const 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: ToolDescriptor): object;
+    /**
+     * 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: Record<string, unknown>): ToolCallSpec;
+};
+/** Anthropic Messages API `tools` array + `tool_use` content blocks. */
+export declare const 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: ToolDescriptor): object;
+    /**
+     * 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: Record<string, unknown>): ToolCallSpec;
+};
+/** Model Context Protocol `tools/list` + `tools/call`. */
+export declare const mcp: {
+    /** Lower a descriptor to an MCP tool definition. Shape: `{ name, description, inputSchema }` (camelCase). */
+    toMcpTool(desc: ToolDescriptor): object;
+    /**
+     * 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: Record<string, unknown>): ToolCallSpec;
+};
+/** Gemini `generateContent` function-calling shape. */
+export declare const gemini: {
+    /**
+     * Lower a descriptor to one Gemini `FunctionDeclaration`. Shape:
+     * ```
+     * { name, description, parameters }
+     * ```
+     * Caller wraps these into the outer
+     * `tools: [{ function_declarations: [ … ] }]` array.
+     */
+    toGeminiFunctionDeclaration(desc: ToolDescriptor): object;
+    /**
+     * 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: Record<string, unknown>): ToolCallSpec;
+};
+export {};