lightnode-sdk 0.9.2 → 0.10.1

package/dist/gateway.d.ts

@@ -92,8 +92,19 @@ export declare class GatewayClient {
             name: string;
         }[];
     }>;
-    /** Protected: dispatcher picks a worker for a session and returns its pubkey. */
-    selectSession(modelId: `0x${string}`): Promise<SelectSessionResult>;
+    /** Protected: dispatcher picks a worker for a session and returns its pubkey.
+     *  Pass requiredCapabilities (e.g. ["search"]) to bind only to a worker that
+     *  advertises them. */
+    selectSession(modelId: `0x${string}`, opts?: {
+        requiredCapabilities?: string[];
+    }): Promise<SelectSessionResult>;
+    /** Public: union of capabilities advertised by active workers for a model
+     *  (e.g. ["search"]). Used to gate UI before a session binds. Note: this
+     *  endpoint may 404 on networks where consumer-api hasn't deployed it yet. */
+    getModelCapabilities(modelIdHex: `0x${string}`): Promise<{
+        modelId: string;
+        capabilities: string[];
+    }>;
     /**
      * Protected: hand the dispatcher the encrypted session key it can give the
      * worker, get back the EIP-712 signature authorising on-chain createSession.
@@ -116,8 +127,11 @@ export declare class GatewayClient {
         selectionId?: string;
         requiredCapabilities?: string[];
     }): Promise<PrepareSessionResult>;
-    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash. */
-    uploadBlob(base64Data: string): Promise<UploadBlobResult>;
+    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash.
+     *  Pass { searchEnabled: true } to opt this job into worker-side web search. */
+    uploadBlob(base64Data: string, opts?: {
+        searchEnabled?: boolean;
+    }): Promise<UploadBlobResult>;
     /** Protected: fetch the relay JWT for an active session (202 = pending). */
     getSessionToken(sessionId: number): Promise<SessionTokenResult>;
     private req;

package/dist/gateway.js

@@ -75,9 +75,21 @@ export class GatewayClient {
     getModels() {
         return this.req("GET", "/api/models");
     }
-    /** Protected: dispatcher picks a worker for a session and returns its pubkey. */
-    selectSession(modelId) {
-        return this.req("POST", "/api/sessions/select", { modelId });
+    /** Protected: dispatcher picks a worker for a session and returns its pubkey.
+     *  Pass requiredCapabilities (e.g. ["search"]) to bind only to a worker that
+     *  advertises them. */
+    selectSession(modelId, opts) {
+        const body = { modelId };
+        if (opts?.requiredCapabilities && opts.requiredCapabilities.length > 0) {
+            body.requiredCapabilities = opts.requiredCapabilities;
+        }
+        return this.req("POST", "/api/sessions/select", body);
+    }
+    /** Public: union of capabilities advertised by active workers for a model
+     *  (e.g. ["search"]). Used to gate UI before a session binds. Note: this
+     *  endpoint may 404 on networks where consumer-api hasn't deployed it yet. */
+    getModelCapabilities(modelIdHex) {
+        return this.req("GET", `/api/models/${modelIdHex}/capabilities`);
     }
     /**
      * Protected: hand the dispatcher the encrypted session key it can give the
@@ -92,9 +104,13 @@ export class GatewayClient {
     prepareSession(input) {
         return this.req("POST", "/api/sessions/prepare", input);
     }
-    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash. */
-    uploadBlob(base64Data) {
-        return this.req("POST", "/api/blobs", { data: base64Data });
+    /** Protected: upload an encrypted prompt blob; returns the EIP-4844 blob hash.
+     *  Pass { searchEnabled: true } to opt this job into worker-side web search. */
+    uploadBlob(base64Data, opts) {
+        const body = { data: base64Data };
+        if (opts?.searchEnabled === true)
+            body.searchEnabled = true;
+        return this.req("POST", "/api/blobs", body);
     }
     /** Protected: fetch the relay JWT for an active session (202 = pending). */
     getSessionToken(sessionId) {

package/dist/index.d.ts

@@ -137,7 +137,7 @@ export declare class LightNode {
 export declare const SDK_VERSION = "0.7.20";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, resolveJobTransactions, siweSignIn, siweChallenge, siweVerify, fetchWorkerModels, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, openSession, runJobOnSession, LightChatSession, Conversation, chat, runInferenceBatch, Agent, parseAgentOutput, workerPreflight, workerWatch, Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, OnchainModelRegistry, AIVM_MODEL_REGISTRY_ABI, BENCHMARK_REGISTRY_ABI, ModelStatus, MODEL_STATUS_LABEL, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, WorkerOperator, WORKER_REGISTRY_ABI, JOB_REGISTRY_OPERATOR_ABI, AI_CONFIG_ABI, JOB_STATE, decodeWorkerError, WorkerOpError, isWorkerOpError, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
-export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } from "./inference.js";
+export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult, OpenSession, OpenSessionArgs, RunJobOpts, WebSearchSource } from "./inference.js";
 export type { ChatRole, ChatMessage, ConversationOptions, ConversationSendResult } from "./chat.js";
 export type { BatchPrompt, BatchResult, RunInferenceBatchArgs } from "./batch.js";
 export type { AgentTool, AgentStep, AgentOptions, AgentRunResult } from "./agent.js";

package/dist/inference.d.ts

@@ -73,6 +73,8 @@ export interface SessionPreparation {
         expiry: bigint;
     };
     nonce: number;
+    /** Capabilities the bound worker advertises (e.g. ["search"]). */
+    workerCapabilities?: string[];
 }
 /**
  * Step 1 + 2 of the protocol: ask the gateway which worker to use, generate a
@@ -82,12 +84,16 @@ export interface SessionPreparation {
  * After this returns, the caller submits the on-chain `createSession` tx with
  * `createSessionArgs` and remembers `sessionKey` for the rest of the session.
  */
-export declare function prepareSession(gateway: GatewayClient, modelTag: string): Promise<SessionPreparation>;
+export declare function prepareSession(gateway: GatewayClient, modelTag: string, opts?: {
+    requiredCapabilities?: string[];
+}): Promise<SessionPreparation>;
 /**
  * Encrypt a UTF-8 prompt with the session key, upload as a blob, and return
  * the EIP-4844 blob hash to pass to `submitJob(sessionId, blobHash)`.
  */
-export declare function submitPrompt(gateway: GatewayClient, sessionKey: Uint8Array, prompt: string): Promise<`0x${string}`>;
+export declare function submitPrompt(gateway: GatewayClient, sessionKey: Uint8Array, prompt: string, opts?: {
+    searchEnabled?: boolean;
+}): Promise<`0x${string}`>;
 /** Decrypt a worker response (raw bytes or base64 from the relay) with the session key. */
 export declare function decryptResponse(sessionKey: Uint8Array, ciphertext: Uint8Array | string): Promise<string>;
 /** Re-export so callers don't have to import from a second module just for the URL helper. */
@@ -152,6 +158,8 @@ export interface RunInferenceArgs {
     network: NetworkConfig;
     /** Inference model tag. Default: `"llama3-8b"`. */
     model?: string;
+    /** Opt into worker-side web search (needs a search-capable worker). */
+    searchEnabled?: boolean;
     /**
      * Streaming callback invoked once per decrypted relay chunk. Use for live
      * stdout / UI updates. Optional - the final `answer` is returned either way.
@@ -203,6 +211,8 @@ export interface RunInferenceResult {
         worker: `0x${string}`;
         submitTx: `0x${string}`;
     }>;
+    /** Web-search citations, when searchEnabled and the worker returned them. */
+    sources?: WebSearchSource[];
 }
 /** A live, on-chain session. Open once, then run many jobs through it - each
  *  follow-up turn skips SIWE + createSession, leaving just the submitJob tx. */
@@ -219,6 +229,8 @@ export interface OpenSession {
     readonly createTx: `0x${string}`;
     /** Unix seconds when the on-chain session window closes. */
     readonly expirySec: number;
+    /** Capabilities the bound worker advertises (e.g. ["search"]). */
+    readonly capabilities: string[];
 }
 export interface OpenSessionArgs {
     gateway: GatewayClient;
@@ -226,6 +238,8 @@ export interface OpenSessionArgs {
     publicClient: MinimalPublicClient;
     network: NetworkConfig;
     model?: string;
+    /** Bind only to a worker advertising these (e.g. ["search"]). */
+    requiredCapabilities?: string[];
 }
 /**
  * prepareSession + the on-chain createSession tx. Do this once, then run many
@@ -233,8 +247,18 @@ export interface OpenSessionArgs {
  * passes or the chosen worker stops serving.
  */
 export declare function openSession(args: OpenSessionArgs): Promise<OpenSession>;
+/** A web-search citation returned alongside an answer (from the worker's
+ *  "metadata" relay frame when searchEnabled was set). */
+export interface WebSearchSource {
+    position: number;
+    title: string;
+    url: string;
+    description: string;
+}
 export interface RunJobOpts {
     onChunk?: (chunk: string, totalSoFar: string) => void;
+    /** Opt this job into worker-side web search (requires a search-capable worker). */
+    searchEnabled?: boolean;
     /** Human-readable progress, e.g. "Uploading prompt to chain..." then "Thinking...". */
     onStage?: (stage: string) => void;
     jobCompletedTimeoutMs?: number;
@@ -268,6 +292,8 @@ export declare class LightChatSession {
     get sessionId(): bigint;
     get worker(): `0x${string}`;
     get model(): string;
+    /** Capabilities the bound worker advertises (e.g. ["search"]). */
+    get capabilities(): string[];
     /** true once the on-chain session window has closed; re-open before sending. */
     get expired(): boolean;
     send(prompt: string, opts?: RunJobOpts): Promise<RunInferenceResult>;
@@ -315,6 +341,8 @@ export interface RunInferenceWithKeyArgs {
     prompt: string;
     /** Inference model tag. Default: `"llama3-8b"`. */
     model?: string;
+    /** Opt into worker-side web search (needs a search-capable worker). */
+    searchEnabled?: boolean;
     /**
      * Streaming callback invoked once per decrypted relay chunk. Use for live
      * stdout / UI updates. Optional - the final `answer` is returned either way.

package/dist/inference.js

@@ -73,8 +73,9 @@ export const JOB_REGISTRY_CONSUMER_ABI = [
  * After this returns, the caller submits the on-chain `createSession` tx with
  * `createSessionArgs` and remembers `sessionKey` for the rest of the session.
  */
-export async function prepareSession(gateway, modelTag) {
+export async function prepareSession(gateway, modelTag, opts) {
     const id = modelId(modelTag);
+    const requiredCapabilities = opts?.requiredCapabilities;
     // The gateway returns 409 selection_mismatch when a NEWER selectSession()
     // for the same wallet supersedes ours between the select and the prepare.
     // The error message is literally "re-run POST /api/sessions/select", so we
@@ -98,7 +99,7 @@ export async function prepareSession(gateway, modelTag) {
             // call has already superseded ours by the time the gateway processes
             // it. prepareSession 409s when the same happens between select and
             // prepare. The whole select -> prepare flow is one atomic unit.
-            const selected = await gateway.selectSession(id);
+            const selected = await gateway.selectSession(id, requiredCapabilities ? { requiredCapabilities } : undefined);
             const sessionKey = await generateSessionKey();
             // Workers' pubkeys arrive as base64; disputer's as hex - decodePublicKey
             // accepts either.
@@ -119,10 +120,12 @@ export async function prepareSession(gateway, modelTag) {
                 encWorkerKey: bytesToBase64(encWorker),
                 encDisputerKey: bytesToBase64(encDisputer),
                 ...(selected.selectionId ? { selectionId: selected.selectionId } : {}),
+                ...(requiredCapabilities ? { requiredCapabilities } : {}),
             });
             return {
                 sessionKey,
                 nonce: prepared.nonce,
+                workerCapabilities: selected.workerCapabilities ?? [],
                 createSessionArgs: {
                     paramsHash: id,
                     worker: prepared.worker,
@@ -148,9 +151,9 @@ export async function prepareSession(gateway, modelTag) {
  * Encrypt a UTF-8 prompt with the session key, upload as a blob, and return
  * the EIP-4844 blob hash to pass to `submitJob(sessionId, blobHash)`.
  */
-export async function submitPrompt(gateway, sessionKey, prompt) {
+export async function submitPrompt(gateway, sessionKey, prompt, opts) {
     const ct = await encrypt(sessionKey, utf8ToBytes(prompt));
-    const res = await gateway.uploadBlob(bytesToBase64(ct));
+    const res = await gateway.uploadBlob(bytesToBase64(ct), opts?.searchEnabled ? { searchEnabled: true } : undefined);
     const first = res.blobHashes?.[0];
     if (!first)
         throw new Error("gateway returned no blob hashes");
@@ -228,6 +231,37 @@ function pickWebSocket(provided) {
 function topicAsUint(hex) {
     return BigInt(hex);
 }
+/** Parse a decrypted "metadata" relay frame into web-search citations. Mirrors
+ *  lcai-chat-v2's parseWebSearchSources: requires type === "webSearchSources"
+ *  and an array of { position:number, url:string, title?, snippet? }. */
+function parseWebSearchSources(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const obj = parsed;
+    if (obj.type !== "webSearchSources" || !Array.isArray(obj.sources))
+        return [];
+    const out = [];
+    for (const s of obj.sources) {
+        if (!s || typeof s !== "object")
+            continue;
+        const src = s;
+        const position = typeof src.position === "number" ? src.position : undefined;
+        const url = typeof src.url === "string" ? src.url : "";
+        const title = typeof src.title === "string" ? src.title : "";
+        const snippet = typeof src.snippet === "string" ? src.snippet : "";
+        if (!position || !url)
+            continue;
+        out.push({ position, title: title || url, url, description: snippet });
+    }
+    return out;
+}
 /**
  * prepareSession + the on-chain createSession tx. Do this once, then run many
  * jobs through the handle with `runJobOnSession`. Re-open when `expirySec`
@@ -235,7 +269,7 @@ function topicAsUint(hex) {
  */
 export async function openSession(args) {
     const { gateway, wallet, publicClient, network, model = "llama3-8b" } = args;
-    const prepared = await prepareSession(gateway, model);
+    const prepared = await prepareSession(gateway, model, args.requiredCapabilities ? { requiredCapabilities: args.requiredCapabilities } : undefined);
     const fee = await estimateJobFee(network, model);
     const createTx = await wallet.writeContract({
         address: network.jobRegistry,
@@ -269,6 +303,7 @@ export async function openSession(args) {
         worker: prepared.createSessionArgs.worker,
         createTx,
         expirySec: Number(prepared.createSessionArgs.expiry),
+        capabilities: prepared.workerCapabilities ?? [],
     };
 }
 /**
@@ -277,7 +312,7 @@ export async function openSession(args) {
  */
 export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
     const { gateway, wallet, publicClient, network, sessionId, sessionKey, worker, fee, createTx } = session;
-    const { onChunk, onStage, jobCompletedTimeoutMs = 120000 } = opts;
+    const { onChunk, onStage, searchEnabled, jobCompletedTimeoutMs = 120000 } = opts;
     const WS = pickWebSocket(opts.WebSocket);
     const relayUrl = opts.relayUrl ?? `wss://relay.${network.id}.lightchain.ai/ws`;
     // Shim so the job body below can keep referencing prepared.* unchanged.
@@ -327,6 +362,7 @@ export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
         setTimeout(() => reject(new Error("relay WebSocket open timeout")), 20000);
     });
     const chunks = [];
+    const sources = [];
     let streamDone = false;
     let streamDoneAt = null;
     const handleMessage = async (rawData) => {
@@ -344,6 +380,18 @@ export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
         catch {
             return;
         }
+        // "metadata" carries web-search citations (sent before the answer stream).
+        if (frame.type === "metadata" && frame.payload) {
+            try {
+                const decoded = await decryptResponse(prepared.sessionKey, frame.payload);
+                for (const s of parseWebSearchSources(decoded))
+                    sources.push(s);
+            }
+            catch {
+                /* ignore malformed metadata */
+            }
+            return;
+        }
         // "complete" marks end-of-stream (it may or may not carry a payload).
         // Record it so the JobCompleted wait can stop promptly instead of polling
         // the full grace window after the answer is already in hand.
@@ -382,8 +430,8 @@ export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
         ws.addEventListener("message", (ev) => handleMessage(ev.data));
     }
     // 4. encrypt + upload prompt
-    onStage?.("Uploading prompt to chain...");
-    const promptHash = await submitPrompt(gateway, prepared.sessionKey, prompt);
+    onStage?.(searchEnabled ? "Searching the web + uploading prompt..." : "Uploading prompt to chain...");
+    const promptHash = await submitPrompt(gateway, prepared.sessionKey, prompt, searchEnabled ? { searchEnabled: true } : undefined);
     // 5. submitJob on-chain
     const submitTx = await wallet.writeContract({
         address: network.jobRegistry,
@@ -485,6 +533,7 @@ export async function runJobOnSession(session, prompt, opts = {}, attempt = 1) {
         jobId,
         attempts: attempt,
         stalled: [],
+        ...(sources.length > 0 ? { sources } : {}),
     };
 }
 /** One attempt = open a fresh session, then run one job through it. */
@@ -495,9 +544,11 @@ async function runOneAttempt(args, attempt) {
         publicClient: args.publicClient,
         network: args.network,
         model: args.model,
+        ...(args.searchEnabled ? { requiredCapabilities: ["search"] } : {}),
     });
     return runJobOnSession(session, args.prompt, {
         onChunk: args.onChunk,
+        searchEnabled: args.searchEnabled,
         jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,
         WebSocket: args.WebSocket,
         relayUrl: args.relayUrl,
@@ -528,6 +579,8 @@ export class LightChatSession {
     get sessionId() { return this.session.sessionId; }
     get worker() { return this.session.worker; }
     get model() { return this.session.model; }
+    /** Capabilities the bound worker advertises (e.g. ["search"]). */
+    get capabilities() { return this.session.capabilities; }
     /** true once the on-chain session window has closed; re-open before sending. */
     get expired() { return Date.now() / 1000 >= this.session.expirySec; }
     send(prompt, opts = {}) {
@@ -711,6 +764,7 @@ export async function runInferenceWithKey(args) {
         publicClient: publicClient,
         network,
         model: args.model,
+        searchEnabled: args.searchEnabled,
         onChunk: args.onChunk,
         maxRetries: args.maxRetries,
         jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",