@iicp/client 0.7.11 → 0.7.32

package/README.md

@@ -31,6 +31,19 @@ npm install iicp-client
 
 ---
 
+## Architecture — consumer or provider?
+
+This SDK covers **both** sides of the IICP protocol:
+
+| Role | What you do | Class |
+|------|-------------|-------|
+| **Consumer** | Send AI tasks to the mesh; discover and submit | `IicpClient` |
+| **Provider** | Run a node, register with the directory, serve tasks | `IicpNode` |
+
+Consumer and provider can run in the same process. For production provider nodes backed by Ollama/vLLM, see [iicp.network/docs/node-setup](https://iicp.network/docs/node-setup).
+
+---
+
 ## Quickstart
 
 ```typescript

package/dist/cip_policy.d.ts

@@ -16,6 +16,8 @@ export interface CooperativeInferencePolicyOptions {
     /** Bounded to [1, 60000]ms. */
     maxWorkerTimeoutMs?: number;
     maxConcurrentRemote?: number;
+    /** #403 — allow tool-execution-domain intents (default false). */
+    allowToolExecution?: boolean;
 }
 /** Safe-by-default CIP policy with the S.12 §2.2 capacity gate built-in. */
 export declare class CooperativeInferencePolicy {
@@ -25,8 +27,15 @@ export declare class CooperativeInferencePolicy {
     readonly maxReplicas: number;
     readonly maxWorkerTimeoutMs: number;
     readonly maxConcurrentRemote: number;
+    readonly allowToolExecution: boolean;
     private _inFlight;
     constructor(opts?: CooperativeInferencePolicyOptions);
+    /**
+     * #403 — per-task admission: reject tool-execution-domain intents unless the
+     * operator opted in via allowToolExecution. Mirrors the adapter cip_gate.
+     * Intent URN form: urn:iicp:intent:<domain>:... — domain is segment index 3.
+     */
+    permitsIntent(intent: string): boolean;
     /** CIP-W01: returns true if this node may act as a CIP coordinator. */
     checkCoordinator(): boolean;
     /** CIP-W02: returns true if this node may accept CIP worker tasks. */

package/dist/cip_policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cip_policy.d.ts","sourceRoot":"","sources":["../src/cip_policy.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iCAAiC;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,4EAA4E;AAC5E,qBAAa,0BAA0B;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,OAAO,CAAC,SAAS,CAAK;gBAEV,IAAI,GAAE,iCAAsC;IASxD,uEAAuE;IACvE,gBAAgB,IAAI,OAAO;IAI3B,sEAAsE;IACtE,WAAW,IAAI,OAAO;IAItB;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO;IAM5B,uDAAuD;IACvD,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMjD;AAMD,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,0BAA0B,CAEzD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAChC,IAAI,GAAE,iCAAsC,GAC3C,0BAA0B,CAG5B"}
+{"version":3,"file":"cip_policy.d.ts","sourceRoot":"","sources":["../src/cip_policy.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iCAAiC;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,4EAA4E;AAC5E,qBAAa,0BAA0B;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,OAAO,CAAC,SAAS,CAAK;gBAEV,IAAI,GAAE,iCAAsC;IAWxD;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKtC,uEAAuE;IACvE,gBAAgB,IAAI,OAAO;IAI3B,sEAAsE;IACtE,WAAW,IAAI,OAAO;IAItB;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO;IAM5B,uDAAuD;IACvD,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOjD;AAMD,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,0BAA0B,CAEzD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAChC,IAAI,GAAE,iCAAsC,GAC3C,0BAA0B,CAG5B"}

package/dist/cip_policy.js

@@ -22,6 +22,7 @@ class CooperativeInferencePolicy {
     maxReplicas;
     maxWorkerTimeoutMs;
     maxConcurrentRemote;
+    allowToolExecution;
     _inFlight = 0;
     constructor(opts = {}) {
         this.enabled = opts.enabled ?? false;
@@ -30,6 +31,17 @@ class CooperativeInferencePolicy {
         this.maxReplicas = Math.max(1, opts.maxReplicas ?? 3);
         this.maxWorkerTimeoutMs = Math.max(1, Math.min(60_000, opts.maxWorkerTimeoutMs ?? 30_000));
         this.maxConcurrentRemote = Math.max(1, opts.maxConcurrentRemote ?? 2);
+        // #403 — per-task admission: tool-execution intents rejected unless opted in.
+        this.allowToolExecution = opts.allowToolExecution ?? false;
+    }
+    /**
+     * #403 — per-task admission: reject tool-execution-domain intents unless the
+     * operator opted in via allowToolExecution. Mirrors the adapter cip_gate.
+     * Intent URN form: urn:iicp:intent:<domain>:... — domain is segment index 3.
+     */
+    permitsIntent(intent) {
+        const domain = intent.split(":")[3] ?? "";
+        return this.allowToolExecution || domain !== "tool";
     }
     /** CIP-W01: returns true if this node may act as a CIP coordinator. */
     checkCoordinator() {
@@ -66,6 +78,7 @@ class CooperativeInferencePolicy {
             return {};
         return {
             allow_remote_inference: this.allowWorker,
+            allow_tool_execution: this.allowToolExecution,
         };
     }
 }

package/dist/cip_policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"cip_policy.js","sourceRoot":"","sources":["../src/cip_policy.ts"],"names":[],"mappings":";AAAA,sCAAsC;AACtC;;;;;;;;;GASG;;;AA4EH,oCAEC;AAGD,gDAKC;AA1ED,4EAA4E;AAC5E,MAAa,0BAA0B;IAC5B,OAAO,CAAU;IACjB,gBAAgB,CAAU;IAC1B,WAAW,CAAU;IACrB,WAAW,CAAS;IACpB,kBAAkB,CAAS;IAC3B,mBAAmB,CAAS;IAC7B,SAAS,GAAG,CAAC,CAAC;IAEtB,YAAY,OAA0C,EAAE;QACtD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;QACrC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,KAAK,CAAC;QACvD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QACtD,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,IAAI,MAAM,CAAC,CAAC,CAAC;QAC3F,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,uEAAuE;IACvE,gBAAgB;QACd,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,gBAAgB,CAAC;IAC/C,CAAC;IAED,sEAAsE;IACtE,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,iBAAiB;QACf,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,mBAAmB;YAAE,OAAO,KAAK,CAAC;QAC7D,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uDAAuD;IACvD,cAAc;QACZ,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC;YAAE,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,qBAAqB;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAC7B,OAAO;YACL,sBAAsB,EAAE,IAAI,CAAC,WAAW;SACzC,CAAC;IACJ,CAAC;CACF;AAxDD,gEAwDC;AAED,4EAA4E;AAE5E,IAAI,OAAO,GAA+B,IAAI,0BAA0B,EAAE,CAAC;AAE3E,uFAAuF;AACvF,SAAgB,YAAY;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gFAAgF;AAChF,SAAgB,kBAAkB,CAChC,OAA0C,EAAE;IAE5C,OAAO,GAAG,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"cip_policy.js","sourceRoot":"","sources":["../src/cip_policy.ts"],"names":[],"mappings":";AAAA,sCAAsC;AACtC;;;;;;;;;GASG;;;AA4FH,oCAEC;AAGD,gDAKC;AAxFD,4EAA4E;AAC5E,MAAa,0BAA0B;IAC5B,OAAO,CAAU;IACjB,gBAAgB,CAAU;IAC1B,WAAW,CAAU;IACrB,WAAW,CAAS;IACpB,kBAAkB,CAAS;IAC3B,mBAAmB,CAAS;IAC5B,kBAAkB,CAAU;IAC7B,SAAS,GAAG,CAAC,CAAC;IAEtB,YAAY,OAA0C,EAAE;QACtD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;QACrC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,KAAK,CAAC;QACvD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QACtD,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,IAAI,MAAM,CAAC,CAAC,CAAC;QAC3F,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;QACtE,8EAA8E;QAC9E,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,IAAI,KAAK,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,MAAc;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC,kBAAkB,IAAI,MAAM,KAAK,MAAM,CAAC;IACtD,CAAC;IAED,uEAAuE;IACvE,gBAAgB;QACd,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,gBAAgB,CAAC;IAC/C,CAAC;IAED,sEAAsE;IACtE,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,iBAAiB;QACf,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,mBAAmB;YAAE,OAAO,KAAK,CAAC;QAC7D,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uDAAuD;IACvD,cAAc;QACZ,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC;YAAE,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,qBAAqB;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QAC7B,OAAO;YACL,sBAAsB,EAAE,IAAI,CAAC,WAAW;YACxC,oBAAoB,EAAE,IAAI,CAAC,kBAAkB;SAC9C,CAAC;IACJ,CAAC;CACF;AAtED,gEAsEC;AAED,4EAA4E;AAE5E,IAAI,OAAO,GAA+B,IAAI,0BAA0B,EAAE,CAAC;AAE3E,uFAAuF;AACvF,SAAgB,YAAY;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gFAAgF;AAChF,SAAgB,kBAAkB,CAChC,OAA0C,EAAE;IAE5C,OAAO,GAAG,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli.d.ts

@@ -1,3 +1,27 @@
 #!/usr/bin/env node
+import { type NodeIdentity } from "./identity.js";
+export interface ServeOpts {
+    backendUrl: string;
+    backendType: string;
+    /** #5 — Bearer key for an auth-requiring OpenAI-compat backend (LM Studio, hosted). Empty = none. */
+    backendApiKey: string;
+    model: string;
+    publicEndpoint: string;
+    directoryUrl: string;
+    region: string;
+    intent: string;
+    maxConcurrent: number;
+    nodeId: string;
+    port: number;
+    host: string;
+    skipRegistration: boolean;
+    force: boolean;
+    autoDetectNat: boolean;
+    externalIpProbeUrl: string;
+    relayWorkerEndpoint: string;
+    node: string;
+    logDir?: string;
+}
+export declare function applySavedNode(opts: ServeOpts, saved: NodeIdentity): ServeOpts;
 export declare function main(argv?: string[]): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+pBA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFlF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiCA,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8UD,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAiB9E;AAwaD,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CA8FlF"}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySavedNode = applySavedNode;
 exports.main = main;
 // SPDX-License-Identifier: Apache-2.0
 /**
@@ -21,12 +22,17 @@ exports.main = main;
  */
 const node_util_1 = require("node:util");
 const node_crypto_1 = require("node:crypto");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const SDK_VERSION = require("../package.json").version;
 const net = require("node:net");
 const node_child_process_1 = require("node:child_process");
 const readline = require("node:readline/promises");
 const node_process_1 = require("node:process");
 const node_js_1 = require("./node.js");
+const client_js_1 = require("./client.js");
+const node_log_js_1 = require("./node_log.js");
 const cip_policy_js_1 = require("./cip_policy.js");
+const instance_lock_js_1 = require("./instance_lock.js");
 const index_js_1 = require("./backends/index.js");
 const identity_js_1 = require("./identity.js");
 function envOr(name, fallback) {
@@ -51,7 +57,8 @@ function printHelp() {
         `Commands:\n` +
         `  init                       Interactive wizard — set up operator + first node config\n` +
         `  list                       List node configs saved under ~/.iicp/nodes/\n` +
-        `  serve                      Register and serve a node\n\n` +
+        `  serve                      Register and serve a node\n` +
+        `  query <prompt>             Discover mesh nodes and submit a chat task\n\n` +
         `Run an IICP provider node backed by an OpenAI-compatible server.\n\n` +
         `serve required (flag or env):\n` +
         `  --model NAME               IICP_BACKEND_MODEL — model name (e.g. qwen2.5:0.5b)\n` +
@@ -59,6 +66,7 @@ function printHelp() {
         `serve optional:\n` +
         `  --backend-url URL          IICP_BACKEND_URL — Ollama / vLLM / LM Studio (default http://localhost:11434)\n` +
         `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp (default openai_compat)\n` +
+        `  --backend-api-key KEY      IICP_BACKEND_API_KEY — Bearer key for an auth'd backend (LM Studio, hosted)\n` +
         `  --public-endpoint URL      IICP_PUBLIC_ENDPOINT — externally reachable URL of this node\n` +
         `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
         `  --region REGION            IICP_REGION (default eu-central)\n` +
@@ -66,10 +74,16 @@ function printHelp() {
         `  --max-concurrent N         IICP_MAX_CONCURRENT (default 4)\n` +
         `  --node-id ID               IICP_NODE_ID (auto-generated if absent)\n` +
         `  --port N                   IICP_PORT (default 9484)\n` +
-        `  --host HOST                IICP_HOST (default 0.0.0.0)\n` +
+        `  --host HOST                IICP_HOST (default :: — dual-stack IPv4+IPv6)\n` +
         `  --skip-registration        IICP_SKIP_REGISTRATION — register-free dev mode\n` +
         `  --auto-detect-nat          IICP_AUTO_DETECT_NAT — run NAT detection at startup\n` +
-        `  --external-ip-probe-url U  IICP_EXTERNAL_IP_PROBE_URL — fallback IPv4 probe\n`);
+        `  --external-ip-probe-url U  IICP_EXTERNAL_IP_PROBE_URL — fallback IPv4 probe\n\n` +
+        `query optional:\n` +
+        `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
+        `  --intent URN               IICP_INTENT (default urn:iicp:intent:llm:chat:v1)\n` +
+        `  --model NAME               Pin to a specific model on the remote node\n` +
+        `  --max-tokens N             Limit response length\n` +
+        `  --timeout-ms N             Request timeout (default 60000)\n`);
 }
 async function checkDependencies(backendUrl) {
     const out = [];
@@ -101,7 +115,7 @@ async function checkDependencies(backendUrl) {
             out.push({ name: mod, severity: "ok", message: purpose, installable: false, npmExtra: "" });
         }
         catch {
-            out.push({ name: mod, severity: "missing", message: `${purpose} (not installed)`, installable: true, npmExtra: npmName });
+            out.push({ name: mod, severity: "optional", message: `${purpose} (optional — not installed)`, installable: true, npmExtra: npmName });
         }
     }
     // 3) IPv6 routing surface (advisory)
@@ -124,14 +138,14 @@ async function checkDependencies(backendUrl) {
     return out;
 }
 function printDepStatus(issues) {
-    const glyph = { ok: "  ✓", warn: "  !", missing: "  ✗" };
+    const glyph = { ok: "  ✓", optional: "  ○", warn: "  !", missing: "  ✗" };
     for (const i of issues) {
         process.stdout.write(`${glyph[i.severity] ?? "  ?"} ${i.name.padEnd(18)}  ${i.message}\n`);
     }
 }
 function installMissing(issues) {
     const extras = Array.from(new Set(issues
-        .filter((i) => i.severity === "missing" && i.installable && i.npmExtra)
+        .filter((i) => (i.severity === "optional" || i.severity === "missing") && i.installable && i.npmExtra)
         .map((i) => i.npmExtra))).sort();
     if (extras.length === 0)
         return;
@@ -212,14 +226,14 @@ async function runInit() {
         process.stdout.write(`Checking dependencies …\n`);
         const issues = await checkDependencies(backend);
         printDepStatus(issues);
-        const missingCount = issues.filter((i) => i.severity === "missing" && i.installable).length;
-        if (missingCount > 0) {
-            const yn = (await ask(rl, `\nInstall ${missingCount} missing optional package(s)? [Y/n]`, "y")).toLowerCase();
+        const optionalCount = issues.filter((i) => (i.severity === "optional" || i.severity === "missing") && i.installable).length;
+        if (optionalCount > 0) {
+            const yn = (await ask(rl, `\nEnable ${optionalCount} optional package(s)? (your node runs without them) [Y/n]`, "y")).toLowerCase();
             if (yn === "" || yn === "y" || yn === "yes") {
                 installMissing(issues);
             }
             else {
-                process.stdout.write(`  ! skipping — install later with: npm install <pkg>\n`);
+                process.stdout.write(`  ○ skipping — enable later with: npm install <pkg>\n`);
             }
         }
         process.stdout.write(`\nDocumentation:\n`);
@@ -384,6 +398,20 @@ async function runServe(opts) {
         return 2;
     }
     const nodeId = (opts.nodeId || (0, node_crypto_1.randomUUID)()).slice(0, 36);
+    const logDir = opts.logDir;
+    // #405 — single-instance lock: refuse a second LIVE process for this node_id
+    // (the token-rotation war). Distinct node_ids are unaffected. Fails open.
+    let instanceLock;
+    try {
+        instanceLock = instance_lock_js_1.InstanceLock.acquire(nodeId, opts.force);
+    }
+    catch (exc) {
+        if (exc instanceof instance_lock_js_1.NodeAlreadyServingError) {
+            console.error(`[iicp-node] ${exc.message}`);
+            process.exit(2);
+        }
+        throw exc;
+    }
     // Resolve the actual listen port before NAT detection: start at the
     // requested port (default 9484, the official IICP port) and auto-increment
     // to the next free port. Keeps one port per node (multiple models share it)
@@ -513,44 +541,105 @@ async function runServe(opts) {
     const handler = (0, index_js_1.getBackendHandler)(opts.backendType, {
         baseUrl: _baseUrl,
         model: opts.model,
+        // #5 — Bearer key for auth'd backends (LM Studio, hosted). Empty/undefined = no header.
+        apiKey: opts.backendApiKey || undefined,
     });
     // GAP-6: probe backend for all available models so the registration advertises
     // the full list — not just the single configured model. Best-effort; fall back
     // to the single configured model on any error.
     try {
-        const tagsUrl = opts.backendUrl.replace(/\/$/, "") + "/api/tags";
-        const tagsResp = await fetch(tagsUrl, { signal: AbortSignal.timeout(3000) });
-        if (tagsResp.ok) {
-            const tagsData = await tagsResp.json();
-            const extra = (tagsData.models ?? [])
-                .map((m) => m.name)
-                .filter((m) => m !== opts.model);
-            if (extra.length > 0) {
-                node["_cfg"].capabilities = extra;
-                // eslint-disable-next-line no-console
-                console.log(`[iicp-node] GAP-6: advertising ${extra.length} additional model(s): ${extra.slice(0, 6).join(", ")}`);
+        // #409 — strip a trailing /v1 to a root so probe URLs are well-formed for
+        // both Ollama (`http://host:11434`) and LM Studio/OpenAI-compat
+        // (`http://host:1234/v1`); attach the Bearer key (LM Studio /v1/models 401s
+        // without it). Without this, /v1 backends got `…/v1/v1/models` (404) and no
+        // models were discovered, so multi-intent never fired.
+        const base = opts.backendUrl.replace(/\/$/, "");
+        const root = base.endsWith("/v1") ? base.slice(0, -3) : base;
+        const headers = opts.backendApiKey
+            ? { Authorization: `Bearer ${opts.backendApiKey}` }
+            : {};
+        const allModels = await (async () => {
+            // Ollama /api/tags ({models:[{name}]})
+            try {
+                const r = await fetch(`${root}/api/tags`, { headers, signal: AbortSignal.timeout(3000) });
+                if (r.ok) {
+                    const d = await r.json();
+                    const names = (d.models ?? []).map((m) => m.name);
+                    if (names.length > 0)
+                        return names;
+                }
+            }
+            catch { /* try OpenAI next */ }
+            // OpenAI-compat /v1/models ({data:[{id}]})
+            try {
+                const r = await fetch(`${root}/v1/models`, { headers, signal: AbortSignal.timeout(3000) });
+                if (r.ok) {
+                    const d = await r.json();
+                    return (d.data ?? []).map((m) => m.id).filter(Boolean);
+                }
             }
+            catch { /* best-effort */ }
+            return [];
+        })();
+        const extra = allModels.filter((m) => m !== opts.model);
+        if (extra.length > 0) {
+            node["_cfg"].capabilities = extra;
+            // eslint-disable-next-line no-console
+            console.log(`[iicp-node] GAP-6: advertising ${extra.length} additional model(s): ${extra.slice(0, 6).join(", ")}`);
         }
     }
     catch {
         // best-effort; no-op on error
     }
+    // NAT-4 guard: if endpoint is non-routable and no relay configured, skip
+    // registration to avoid a confusing 422 from the directory's RoutableEndpoint check.
+    const epLocal = publicEndpoint.startsWith("http://localhost") ||
+        publicEndpoint.startsWith("http://127.") ||
+        publicEndpoint.startsWith("http://0.0.0.0") ||
+        publicEndpoint.startsWith("http://192.168.") ||
+        publicEndpoint.startsWith("http://10.");
+    if (epLocal && !opts.relayWorkerEndpoint && !opts.skipRegistration) {
+        // eslint-disable-next-line no-console
+        console.warn("[iicp-node] no routable endpoint detected and no relay configured — " +
+            "skipping directory registration. Node will accept direct connections " +
+            "but will not appear in discover results. " +
+            "Set IICP_PUBLIC_ENDPOINT=<url> or IICP_RELAY_WORKER_ENDPOINT=<host>:<port> to register.");
+        opts.skipRegistration = true;
+    }
+    // #404 — register with bounded backoff retry. On persistent failure, pass an
+    // empty token (NOT undefined) so the heartbeat loop still starts and re-registers
+    // on the first 401 (#399 path) once the directory is reachable — the self-healing
+    // watchdog. undefined is reserved for --skip-registration (no heartbeat by design).
     let token;
     if (!opts.skipRegistration) {
-        try {
-            token = await node.register();
-            // eslint-disable-next-line no-console
-            console.log(`[iicp-node] registered as ${nodeId} (token=${(token ?? "").slice(0, 8)}…)`);
-        }
-        catch (exc) {
-            const msg = exc instanceof Error ? exc.message : String(exc);
-            // eslint-disable-next-line no-console
-            console.warn(`[iicp-node] registration failed: ${msg} — continuing without heartbeat`);
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                token = await node.register();
+                // eslint-disable-next-line no-console
+                console.log(`[iicp-node] registered as ${nodeId} (token=${(token ?? "").slice(0, 8)}…)`);
+                (0, node_log_js_1.writeNodeEvent)(nodeId, "register_ok", `endpoint=${opts.publicEndpoint || `http://localhost:${opts.port}`}`, logDir);
+                break;
+            }
+            catch (exc) {
+                const msg = exc instanceof Error ? exc.message : String(exc);
+                if (attempt >= 3) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[iicp-node] registration failed after ${attempt} attempts: ${msg} — starting heartbeat loop anyway; it will re-register on the first 401`);
+                    (0, node_log_js_1.writeNodeEvent)(nodeId, "register_fail", `error=${msg} attempts=${attempt}`, logDir);
+                    token = ""; // empty (not undefined) → heartbeat loop starts and self-heals
+                    break;
+                }
+                const backoff = 2 ** attempt;
+                // eslint-disable-next-line no-console
+                console.warn(`[iicp-node] registration attempt ${attempt} failed: ${msg} — retrying in ${backoff}s`);
+                await new Promise((r) => setTimeout(r, backoff * 1000));
+            }
         }
     }
     // eslint-disable-next-line no-console
     console.log(`[iicp-node] serving ${opts.intent} on ${opts.host}:${opts.port} — ` +
         `backend ${opts.backendUrl} (model=${opts.model}, max_concurrent=${opts.maxConcurrent})`);
+    (0, node_log_js_1.writeNodeEvent)(nodeId, "serve_start", `port=${opts.port} model=${opts.model} intent=${opts.intent}`, logDir);
     // serve() returns a stop() handle but never resolves on its own; we wait for
     // SIGINT/SIGTERM to terminate.
     const stop = node.serve(handler, { host: opts.host, port: opts.port, nodeToken: token });
@@ -568,13 +657,17 @@ async function runServe(opts) {
             try {
                 if (token) {
                     await node.deregister(token);
+                    (0, node_log_js_1.writeNodeEvent)(nodeId, "deregister_ok", "", logDir);
                 }
             }
             catch (exc) {
+                const deregMsg = exc instanceof Error ? exc.message : String(exc);
                 // eslint-disable-next-line no-console
-                console.warn(`[iicp-node] deregister failed: ${exc instanceof Error ? exc.message : exc}`);
+                console.warn(`[iicp-node] deregister failed: ${deregMsg}`);
+                (0, node_log_js_1.writeNodeEvent)(nodeId, "deregister_fail", `error=${deregMsg}`, logDir);
             }
             stop();
+            instanceLock.release(); // #405 — free the pidfile on shutdown
             resolve();
         };
         process.once("SIGINT", () => void shutdown("SIGINT"));
@@ -584,16 +677,84 @@ async function runServe(opts) {
     void node_crypto_1.randomUUID;
     return 0;
 }
+async function runQuery(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: argv,
+        options: {
+            "directory-url": { type: "string" },
+            intent: { type: "string" },
+            model: { type: "string" },
+            "max-tokens": { type: "string" },
+            "timeout-ms": { type: "string" },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    const prompt = positionals.join(" ").trim();
+    if (!prompt) {
+        process.stderr.write("Usage: iicp-node query <prompt> [flags]\n");
+        return 1;
+    }
+    const directoryUrl = values["directory-url"] ??
+        process.env["IICP_DIRECTORY_URL"] ??
+        "https://iicp.network/api";
+    const intent = values["intent"] ??
+        process.env["IICP_INTENT"] ??
+        "urn:iicp:intent:llm:chat:v1";
+    const timeoutMs = parseInt(values["timeout-ms"] ?? "60000", 10);
+    const payload = {
+        messages: [{ role: "user", content: prompt }],
+    };
+    if (values["model"])
+        payload["model"] = values["model"];
+    if (values["max-tokens"])
+        payload["max_tokens"] = parseInt(values["max-tokens"], 10);
+    const client = new client_js_1.IicpClient({ directory_url: directoryUrl, timeout_ms: timeoutMs, tls_verify: true });
+    process.stderr.write(`[iicp-node] Discovering nodes for ${intent}...\n`);
+    try {
+        const resp = await client.submit({
+            task_id: (0, node_crypto_1.randomUUID)(),
+            intent,
+            payload,
+        });
+        if (resp.status === "completed" && resp.result) {
+            const res = resp.result;
+            const content = typeof res["content"] === "string"
+                ? res["content"]
+                : JSON.stringify(resp.result, null, 2);
+            process.stdout.write(content + "\n");
+            if (resp.metrics?.node_id) {
+                process.stderr.write(`[iicp-node] routed to node ${resp.metrics.node_id.slice(0, 8)}\n`);
+            }
+            if (resp.metrics?.latency_ms != null) {
+                process.stderr.write(`[iicp-node] latency ${resp.metrics.latency_ms.toFixed(0)}ms\n`);
+            }
+            return 0;
+        }
+        process.stderr.write(`[iicp-node] task status: ${resp.status}\n`);
+        return 1;
+    }
+    catch (e) {
+        process.stderr.write(`ERROR: ${e}\n`);
+        return 1;
+    }
+}
 async function main(argv = process.argv.slice(2)) {
     if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
         printHelp();
         return argv.length === 0 ? 2 : 0;
     }
+    if (argv[0] === "--version" || argv[0] === "-V") {
+        process.stdout.write(`iicp-node ${SDK_VERSION}\n`);
+        return 0;
+    }
     const cmd = argv[0];
     if (cmd === "init")
         return runInit();
     if (cmd === "list")
         return runList();
+    if (cmd === "query")
+        return runQuery(argv.slice(1));
     if (cmd !== "serve") {
         process.stderr.write(`unknown command: ${cmd}\n`);
         printHelp();
@@ -605,6 +766,7 @@ async function main(argv = process.argv.slice(2)) {
             node: { type: "string" },
             "backend-url": { type: "string" },
             "backend-type": { type: "string" },
+            "backend-api-key": { type: "string" },
             model: { type: "string" },
             "public-endpoint": { type: "string" },
             "directory-url": { type: "string" },
@@ -615,9 +777,11 @@ async function main(argv = process.argv.slice(2)) {
             port: { type: "string" },
             host: { type: "string" },
             "skip-registration": { type: "boolean" },
+            force: { type: "boolean" },
             "auto-detect-nat": { type: "boolean" },
             "external-ip-probe-url": { type: "string" },
             "relay-worker-endpoint": { type: "string" },
+            "log-dir": { type: "string" },
             help: { type: "boolean", short: "h" },
         },
         allowPositionals: false,
@@ -631,6 +795,7 @@ async function main(argv = process.argv.slice(2)) {
         backendUrl: values["backend-url"] ?? envOr("IICP_BACKEND_URL") ?? "",
         backendType: values["backend-type"] ??
             envOr("IICP_BACKEND_TYPE", "openai_compat"),
+        backendApiKey: values["backend-api-key"] ?? envOr("IICP_BACKEND_API_KEY") ?? "",
         model: values.model ?? envOr("IICP_BACKEND_MODEL") ?? "",
         publicEndpoint: values["public-endpoint"] ?? envOr("IICP_PUBLIC_ENDPOINT") ?? "",
         directoryUrl: values["directory-url"] ??
@@ -644,8 +809,9 @@ async function main(argv = process.argv.slice(2)) {
         port: values.port !== undefined
             ? parseInt(values.port, 10)
             : envInt("IICP_PORT", 9484),
-        host: values.host ?? envOr("IICP_HOST", "0.0.0.0"),
+        host: values.host ?? envOr("IICP_HOST", "::"),
         skipRegistration: Boolean(values["skip-registration"]) || envBool("IICP_SKIP_REGISTRATION"),
+        force: Boolean(values["force"]) || envBool("IICP_FORCE"),
         // Default ON — matches Python CLI behaviour; operator must set IICP_AUTO_DETECT_NAT=false to opt out.
         autoDetectNat: values["auto-detect-nat"] !== undefined
             ? Boolean(values["auto-detect-nat"])
@@ -655,6 +821,7 @@ async function main(argv = process.argv.slice(2)) {
             ?? envOr("IICP_EXTERNAL_IP_PROBE_URL")
             ?? "https://api.ipify.org",
         relayWorkerEndpoint: values["relay-worker-endpoint"] ?? envOr("IICP_RELAY_WORKER_ENDPOINT") ?? "",
+        logDir: values["log-dir"] ?? envOr("IICP_LOG_DIR"),
     };
     return runServe(opts);
 }