lightnode-sdk 0.5.0 → 0.6.0

package/dist/agent.js

@@ -0,0 +1,176 @@
+import { runInferenceWithKey } from "./inference.js";
+/**
+ * ReAct-style agent on top of `runInferenceWithKey`. Each iteration:
+ *   1. The SDK sends a system prompt that lists tools + the JSON tool-call
+ *      format to the model, plus the running transcript.
+ *   2. The model emits either a tool call (`<tool>name {"k":"v"}</tool>`)
+ *      or a final answer (`<answer>...</answer>`).
+ *   3. The SDK parses, runs the tool, threads the result back, repeats.
+ *
+ * Designed for smaller open models (llama3-8b). The protocol is simple
+ * string markers, not native function calling, so it works on any model
+ * the LightChain network exposes.
+ *
+ * @example
+ * ```ts
+ * import { Agent } from "lightnode-sdk";
+ *
+ * const agent = new Agent({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   system: "You are a careful research assistant.",
+ *   tools: [
+ *     {
+ *       name: "add",
+ *       description: "Add two integers and return the sum.",
+ *       args: { a: "first integer", b: "second integer" },
+ *       handler: ({ a, b }) => Number(a) + Number(b),
+ *     },
+ *   ],
+ *   maxIterations: 3,
+ * });
+ *
+ * const { answer, steps } = await agent.run("What is 17 + 25?");
+ * console.log(answer); // "42"
+ * ```
+ */
+export class Agent {
+    constructor(opts) {
+        if (!opts.tools || opts.tools.length === 0) {
+            throw new Error("Agent: at least one tool is required (use runInferenceWithKey for plain inference)");
+        }
+        // Tool names must be unique - the SDK matches model-emitted names by
+        // string and a dup would silently route to the wrong handler.
+        const seen = new Set();
+        for (const t of opts.tools) {
+            if (seen.has(t.name))
+                throw new Error(`Agent: duplicate tool name "${t.name}"`);
+            seen.add(t.name);
+        }
+        this.opts = opts;
+    }
+    async run(userMessage) {
+        const maxIter = Math.max(1, this.opts.maxIterations ?? 5);
+        const steps = [];
+        const transcript = [`User: ${userMessage}`];
+        const system = this.buildSystemPrompt();
+        let iterations = 0;
+        // Strip Agent-only fields before passing through to runInferenceWithKey.
+        const passthrough = { ...this.opts };
+        delete passthrough.tools;
+        delete passthrough.maxIterations;
+        delete passthrough.onStep;
+        delete passthrough.system;
+        while (iterations < maxIter) {
+            iterations++;
+            const prompt = `${system}\n\n${transcript.join("\n\n")}\n\nAssistant:`;
+            const { answer: raw } = await runInferenceWithKey({
+                ...passthrough,
+                prompt,
+            });
+            const parsed = parseAgentOutput(raw);
+            if (parsed.kind === "answer") {
+                const step = { kind: "answer", text: parsed.text };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                return { answer: parsed.text, steps, iterations, hitLimit: false };
+            }
+            if (parsed.kind === "thought") {
+                const step = { kind: "thought", text: parsed.text };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <think>${parsed.text}</think>`);
+                continue;
+            }
+            // tool_call: look up + execute
+            const tool = this.opts.tools.find((t) => t.name === parsed.name);
+            if (!tool) {
+                const step = {
+                    kind: "tool_error",
+                    name: parsed.name,
+                    args: parsed.args,
+                    error: `unknown tool "${parsed.name}"`,
+                };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: error: unknown tool "${parsed.name}"`);
+                continue;
+            }
+            try {
+                const result = await tool.handler(parsed.args);
+                const step = { kind: "tool_call", name: parsed.name, args: parsed.args, result };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: ${JSON.stringify(result)}`);
+            }
+            catch (err) {
+                const msg = err.message ?? String(err);
+                const step = {
+                    kind: "tool_error",
+                    name: parsed.name,
+                    args: parsed.args,
+                    error: msg,
+                };
+                steps.push(step);
+                this.opts.onStep?.(step);
+                transcript.push(`Assistant: <tool>${parsed.name} ${JSON.stringify(parsed.args)}</tool>`);
+                transcript.push(`Observation: error: ${msg}`);
+            }
+        }
+        return { answer: "", steps, iterations, hitLimit: true };
+    }
+    buildSystemPrompt() {
+        const base = this.opts.system?.trim() ?? "You are a helpful assistant.";
+        const toolDocs = this.opts.tools
+            .map((t) => {
+            const argList = Object.entries(t.args)
+                .map(([k, v]) => `    "${k}": <${v}>`)
+                .join(",\n");
+            return `- ${t.name}: ${t.description}\n  Call as: <tool>${t.name} {\n${argList}\n  }</tool>`;
+        })
+            .join("\n");
+        return `${base}
+
+You have access to these tools:
+${toolDocs}
+
+To call a tool, write EXACTLY one line:
+<tool>tool_name {"arg":"value"}</tool>
+
+After the tool runs, the user will reply with: Observation: <json>
+
+When you are done, respond with EXACTLY:
+<answer>your final reply to the user</answer>
+
+Use one tool at a time. Do not invent tools. Keep observations short.`;
+    }
+}
+/**
+ * Parse the model's raw output into either a tool call, a final answer, or
+ * a thought (everything else). Tolerant of whitespace and the model
+ * forgetting to close a tag. Visible for testing.
+ */
+export function parseAgentOutput(raw) {
+    const answer = raw.match(/<answer>([\s\S]*?)(?:<\/answer>|$)/i);
+    if (answer)
+        return { kind: "answer", text: answer[1].trim() };
+    const tool = raw.match(/<tool>\s*([a-zA-Z_][\w-]*)\s*(\{[\s\S]*?\})\s*(?:<\/tool>|$)/i);
+    if (tool) {
+        const name = tool[1];
+        let args = {};
+        try {
+            const parsed = JSON.parse(tool[2]);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                args = parsed;
+            }
+        }
+        catch {
+            // best-effort: leave args empty so the handler sees missing fields
+        }
+        return { kind: "tool_call", name, args };
+    }
+    return { kind: "thought", text: raw.trim() };
+}

package/dist/batch.d.ts

@@ -0,0 +1,88 @@
+import { type RunInferenceWithKeyArgs, type RunInferenceResult } from "./inference.js";
+/**
+ * One slot in a batch run. `prompt` is the only required field; everything
+ * else inherits from the shared base args passed to `runInferenceBatch`.
+ * A per-prompt `model` / `system` overrides the base when set.
+ */
+export interface BatchPrompt {
+    prompt: string;
+    model?: string;
+    system?: string;
+    /** Opaque per-slot tag returned on the result so the caller can correlate. */
+    tag?: string;
+}
+/** One slot's outcome. `error` is set on failure; `result` on success. Always exactly one. */
+export type BatchResult = {
+    index: number;
+    tag?: string;
+    prompt: string;
+    result: RunInferenceResult;
+    error: null;
+} | {
+    index: number;
+    tag?: string;
+    prompt: string;
+    result: null;
+    error: {
+        name: string;
+        message: string;
+        jobId?: string;
+    };
+};
+export interface RunInferenceBatchArgs extends Omit<RunInferenceWithKeyArgs, "prompt"> {
+    /** Prompts to run. Each slot becomes one independent encrypted inference. */
+    prompts: ReadonlyArray<string | BatchPrompt>;
+    /**
+     * Shared system prompt prepended to every slot. A per-slot `system`
+     * overrides this. Implemented by prefixing the prompt at submit time
+     * (the underlying inference call has no native system role).
+     */
+    system?: string;
+    /**
+     * Max parallel inferences in flight (default 4). Each slot is one
+     * createSession + submitJob pair, so this caps the concurrent wallet
+     * nonce pressure as well as the gateway socket fan-out.
+     */
+    concurrency?: number;
+    /**
+     * Called when ANY slot resolves (success or failure), useful for live
+     * progress UI. Fires in order of completion, not submission.
+     */
+    onSlotComplete?: (result: BatchResult) => void;
+    /**
+     * When set, abort all in-flight + queued slots if this signal fires.
+     * Slots already submitted on chain still settle on chain; the SDK just
+     * stops awaiting their answer.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Run many prompts as parallel encrypted inferences against the same
+ * worker pool. Returns a stable array indexed by submission order.
+ *
+ * Slots fail independently - a stalled worker on one prompt does not
+ * cancel the others. The caller decides what to retry from the per-slot
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceBatch } from "lightnode-sdk";
+ *
+ * const results = await runInferenceBatch({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   prompts: ["one", "two", "three"],
+ *   concurrency: 3,
+ *   onSlotComplete: ({ index, result, error }) => {
+ *     console.log(`#${index}:`, error?.message ?? result?.answer);
+ *   },
+ * });
+ *
+ * for (const r of results) {
+ *   if (r.error) console.warn(`slot ${r.index} failed:`, r.error.message);
+ *   else console.log(r.result.answer);
+ * }
+ * ```
+ */
+export declare function runInferenceBatch(args: RunInferenceBatchArgs): Promise<BatchResult[]>;

package/dist/batch.js

@@ -0,0 +1,102 @@
+import { runInferenceWithKey } from "./inference.js";
+import { StalledWorkerError } from "./errors.js";
+/**
+ * Run many prompts as parallel encrypted inferences against the same
+ * worker pool. Returns a stable array indexed by submission order.
+ *
+ * Slots fail independently - a stalled worker on one prompt does not
+ * cancel the others. The caller decides what to retry from the per-slot
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { runInferenceBatch } from "lightnode-sdk";
+ *
+ * const results = await runInferenceBatch({
+ *   network: "testnet",
+ *   privateKey: process.env.PRIVATE_KEY!,
+ *   model: "llama3-8b",
+ *   prompts: ["one", "two", "three"],
+ *   concurrency: 3,
+ *   onSlotComplete: ({ index, result, error }) => {
+ *     console.log(`#${index}:`, error?.message ?? result?.answer);
+ *   },
+ * });
+ *
+ * for (const r of results) {
+ *   if (r.error) console.warn(`slot ${r.index} failed:`, r.error.message);
+ *   else console.log(r.result.answer);
+ * }
+ * ```
+ */
+export async function runInferenceBatch(args) {
+    const concurrency = Math.max(1, args.concurrency ?? 4);
+    const slots = args.prompts.map((p) => (typeof p === "string" ? { prompt: p } : p));
+    const out = new Array(slots.length);
+    let nextIndex = 0;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    if (args.signal) {
+        if (args.signal.aborted)
+            aborted = true;
+        else
+            args.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const runOne = async (index) => {
+        if (aborted) {
+            out[index] = {
+                index,
+                tag: slots[index].tag,
+                prompt: slots[index].prompt,
+                result: null,
+                error: { name: "AbortError", message: "batch aborted before this slot ran" },
+            };
+            return;
+        }
+        const slot = slots[index];
+        try {
+            const system = slot.system ?? args.system;
+            const finalPrompt = system ? `${system.trim()}\n\n${slot.prompt}` : slot.prompt;
+            // Strip batch-only fields before passing through to runInferenceWithKey.
+            const passthrough = { ...args };
+            delete passthrough.prompts;
+            delete passthrough.system;
+            delete passthrough.concurrency;
+            delete passthrough.onSlotComplete;
+            const result = await runInferenceWithKey({
+                ...passthrough,
+                prompt: finalPrompt,
+                model: slot.model ?? args.model,
+            });
+            out[index] = { index, tag: slot.tag, prompt: slot.prompt, result, error: null };
+        }
+        catch (err) {
+            const e = err;
+            const jobId = e instanceof StalledWorkerError ? e.jobId.toString() : undefined;
+            out[index] = {
+                index,
+                tag: slot.tag,
+                prompt: slot.prompt,
+                result: null,
+                error: { name: e.name ?? "Error", message: e.message, jobId },
+            };
+        }
+        args.onSlotComplete?.(out[index]);
+    };
+    // N parallel workers pulling off the queue. Order of completion is
+    // non-deterministic, order of OUTPUT is stable via `index`.
+    const workers = new Array(Math.min(concurrency, slots.length)).fill(0).map(async () => {
+        while (true) {
+            const i = nextIndex++;
+            if (i >= slots.length)
+                return;
+            await runOne(i);
+        }
+    });
+    await Promise.all(workers);
+    if (args.signal)
+        args.signal.removeEventListener("abort", onAbort);
+    return out;
+}

package/dist/bridge.js

@@ -36,7 +36,7 @@ export const BRIDGE_ROUTE = {
         underlying: "0x9cA8530CA349c966Fe9ef903Df17a75B8A778927", // LCAI ERC-20
         mailbox: "0x287cf56E5b1435Ae59BF9Ce6443F055A0321a063",
         explorer: "https://etherscan.io",
-        rpc: "https://eth.llamarpc.com",
+        rpc: "https://ethereum-rpc.publicnode.com",
         label: "Ethereum",
     },
     "lightchain-mainnet": {

package/dist/cli.js

@@ -279,14 +279,28 @@ async function main() {
                 // Live read against Ethereum mainnet. We use viem's HTTP transport
                 // via a minimal inline client (no ethers dep). This is the only
                 // ecosystem read that needs a live RPC, so we wire it lazily.
+                // Default to publicnode (reliable, no key required). Caller can
+                // override with --rpc <url> if they have a higher-quality endpoint.
                 const { createPublicClient, http } = await import("viem");
-                const ethRpc = flag("--rpc") ?? "https://eth.llamarpc.com";
+                const ethRpc = flag("--rpc") ?? "https://ethereum-rpc.publicnode.com";
                 const pub = createPublicClient({ transport: http(ethRpc) });
                 // The DAO ctor accepts a structurally-typed MinimalPublicClient; viem's
                 // PublicClient satisfies it. The unknown cast is the standard SDK pattern
                 // for keeping the public API free of viem generic noise.
                 const dao = new DAO(pub, "ethereum");
-                const cfg = await dao.config();
+                let cfg;
+                try {
+                    cfg = await dao.config();
+                }
+                catch (e) {
+                    const msg = e.message ?? String(e);
+                    // Short-circuit the viem stack trace: a friendly one-liner is what
+                    // the operator wants when the public RPC is having a bad day.
+                    die(`dao config: RPC call failed against ${ethRpc}.\n` +
+                        `   Hint: try a different Ethereum RPC with --rpc <url>.\n` +
+                        `   Public options: https://ethereum-rpc.publicnode.com, https://rpc.ankr.com/eth, https://eth.merkle.io\n` +
+                        `   Underlying: ${msg.split("\n")[0]}`);
+                }
                 console.log(JSON.stringify({
                     votingDelayBlocks: cfg.votingDelayBlocks.toString(),
                     votingPeriodBlocks: cfg.votingPeriodBlocks.toString(),

package/dist/dao.d.ts

@@ -17,22 +17,47 @@
  * This module covers the OZ Governor v5 surface: state machine, propose,
  * castVote, queue, execute. Plus convenience reads of the constants.
  */
-export type DaoChain = "ethereum";
+/**
+ * Both deployed DAOs we know about:
+ *
+ *   - `ethereum`         LCAIGovernor on Ethereum mainnet. Token holders
+ *                        wrap LCAI ERC-20 into LCAI-Ballots (IVotes) at
+ *                        https://ballots.lightchain.ai, then vote /
+ *                        propose / queue / execute through the Governor.
+ *                        Proposal threshold: 140,000 LCAI wrapped.
+ *
+ *   - `lightchain`       LightChainGovernor on LightChain mainnet (chain
+ *                        9200). Uses the NativeVotes precompile at
+ *                        0x...0001001 - native LCAI itself acts as the
+ *                        voting token, no wrapping needed. Governor is
+ *                        an upgradeable proxy controlled by the
+ *                        TimelockController.
+ *
+ * Addresses sourced from LightChain's official "Mainnet Contract Addresses"
+ * page.
+ */
+export type DaoChain = "ethereum" | "lightchain";
 export interface DaoAddresses {
     chainId: number;
-    /** OZ Governor contract. */
+    label: string;
+    /** OZ Governor contract (proxy when behind an upgradeable pattern). */
     governor: `0x${string}`;
     /** Timelock controller. queue/execute dispatch through this. */
     timelock: `0x${string}`;
-    /** ERC-20 wrapped as IVotes; this is what users delegate / hold to vote. */
-    ballots: `0x${string}`;
-    /** LCAI ERC-20 (the underlying governance token). */
-    token: `0x${string}`;
+    /** ERC-20 wrapped as IVotes (null when the chain uses a NativeVotes precompile). */
+    ballots: `0x${string}` | null;
+    /** Underlying governance token (LCAI ERC-20 on Ethereum, native LCAI on LightChain). */
+    token: `0x${string}` | null;
     /** Treasury contract holding DAO funds. */
     treasury: `0x${string}`;
+    /** Optional UI link (where regular users wrap / view proposals). */
+    wrapperUi?: string;
     explorer: string;
 }
-/** Confirmed Ethereum mainnet addresses (chain 1). */
+/**
+ * Confirmed deployment addresses. Each entry is what an SDK user passes to
+ * `new DAO(client, chainKey, walletClient?)`.
+ */
 export declare const DAO_ADDRESSES: Record<DaoChain, DaoAddresses>;
 /**
  * The 8-state OZ Governor v5 enum. The string label is what most builders

package/dist/dao.js

@@ -18,17 +18,33 @@
  * castVote, queue, execute. Plus convenience reads of the constants.
  */
 import { parseAbi } from "viem";
-/** Confirmed Ethereum mainnet addresses (chain 1). */
+/**
+ * Confirmed deployment addresses. Each entry is what an SDK user passes to
+ * `new DAO(client, chainKey, walletClient?)`.
+ */
 export const DAO_ADDRESSES = {
     ethereum: {
         chainId: 1,
+        label: "Ethereum mainnet",
         governor: "0x6dfa413B5900a1a7947BC75E68AbBA093cB2492d",
         timelock: "0xbE1c37F8C4DA77dD06F4A8AC5098Ec70273093d7",
         ballots: "0x75F3D01c4D960FE986A598B7954A3b786B29cE49",
         token: "0x9cA8530CA349c966Fe9ef903Df17a75B8A778927",
         treasury: "0x07A716a551E5f4CA7D6C71Da9dF1cb1429Dba826",
+        wrapperUi: "https://ballots.lightchain.ai",
         explorer: "https://etherscan.io",
     },
+    lightchain: {
+        chainId: 9200,
+        label: "LightChain mainnet",
+        governor: "0x262E9f9232933E8565253918db703baD58DE93aB",
+        timelock: "0x79e571420c5473Ca9b0FCd599B1b0062D7793c97",
+        // Native voting via the genesis predeploy precompile; no separate wrapping token.
+        ballots: "0x0000000000000000000000000000000000001001",
+        token: null,
+        treasury: "0x786eDe8C42Ca54E54c9dCECa9b30052CF4743389",
+        explorer: "https://mainnet.lightscan.app",
+    },
 };
 /**
  * The 8-state OZ Governor v5 enum. The string label is what most builders

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
+import { runInferenceBatch } from "./batch.js";
+import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI } from "./dao.js";
@@ -88,11 +90,13 @@ export declare class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export declare const SDK_VERSION = "0.5.0";
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, Conversation, chat, 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, };
+export declare const SDK_VERSION = "0.6.0";
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, runInferenceStream, 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, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs, RunInferenceStreamResult } 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";
 export type { WorkerPreflightArgs, WorkerPreflightResult, WorkerWatchOptions, WorkerEventKind, WorkerEvent, WorkerWatchHandle } from "./worker.js";
 export type { BridgeChain, BridgeEndpoints, BridgeTransferArgs } from "./bridge.js";
 export type { DaoChain, DaoAddresses, ProposalSummary, DaoConfig } from "./dao.js";

package/dist/index.js

@@ -4,6 +4,8 @@ import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
 import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, runInferenceStream, } from "./inference.js";
 import { Conversation, chat } from "./chat.js";
+import { runInferenceBatch } from "./batch.js";
+import { Agent, parseAgentOutput } from "./agent.js";
 import { preflight as workerPreflight, watch as workerWatch } from "./worker.js";
 import { Bridge, BRIDGE_ROUTE, HYPERLANE_ROUTER_ABI, ERC20_ABI, addressToBytes32, quoteBridgeFee, bridgeableBalance, bridgeAllowance, approveBridge, bridgeTransfer, } from "./bridge.js";
 import { DAO, DAO_ADDRESSES, ProposalState, PROPOSAL_STATE_LABEL, VoteSupport, GOVERNOR_ABI, VOTES_ABI, } from "./dao.js";
@@ -143,7 +145,7 @@ export class LightNode {
  * (especially in registry-proxy environments like StackBlitz where lockfiles
  * may pin an older minor than the local install command suggests).
  */
-export const SDK_VERSION = "0.5.0";
+export const SDK_VERSION = "0.6.0";
 export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
@@ -155,6 +157,10 @@ runInferenceWithKey,
 runInferenceStream, 
 // v0.5.0 multi-turn conversation helper (history client-side; one inference per turn).
 Conversation, chat, 
+// v0.6.0 batch runner: many prompts, capped parallelism, stable result order.
+runInferenceBatch, 
+// v0.6.0 ReAct-style agent: tool calling on any LightChain-hosted model.
+Agent, parseAgentOutput, 
 // v0.5.0 worker preflight + watch (one real test inference + status polling).
 workerPreflight, workerWatch, 
 // v0.5.0 Bridge SDK (Hyperlane Warp Route wrapper for LCAI <-> Ethereum).

package/dist/inference.d.ts

@@ -171,6 +171,11 @@ export interface RunInferenceArgs {
      * Useful for tests / mirrors.
      */
     relayUrl?: string;
+    /**
+     * Cancellation signal. Aborts pending awaits inside the run; in-flight
+     * submitJob transactions still settle on chain (the SDK stops listening).
+     */
+    signal?: AbortSignal;
 }
 export interface RunInferenceResult {
     /** The decrypted, fully-assembled model answer. */
@@ -264,6 +269,13 @@ export interface RunInferenceWithKeyArgs {
      * Useful for tests / mirrors / proxying through your own backend.
      */
     gatewayUrl?: string;
+    /**
+     * Cancellation signal. Aborts the SIWE handshake and stops awaiting the
+     * relay; in-flight submitJob transactions still settle on chain (the SDK
+     * just stops listening). Throws `Error("aborted")` synchronously if the
+     * signal is already fired when the call starts.
+     */
+    signal?: AbortSignal;
 }
 /**
  * One call, key-in / answer-out encrypted inference. Builds viem clients,

package/dist/inference.js

@@ -428,12 +428,14 @@ export async function runInference(args) {
     const maxRetries = args.maxRetries ?? 2;
     const stalled = [];
     for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        if (args.signal?.aborted)
+            throw new Error("runInference: aborted");
         try {
             const result = await runOneAttempt(args, attempt);
             return { ...result, stalled };
         }
         catch (err) {
-            if (err instanceof StalledWorkerError && attempt <= maxRetries) {
+            if (err instanceof StalledWorkerError && attempt <= maxRetries && !args.signal?.aborted) {
                 stalled.push({ jobId: err.jobId, worker: err.worker, submitTx: err.submitTx });
                 continue;
             }
@@ -482,6 +484,9 @@ export async function runInferenceWithKey(args) {
     if (!key || !key.startsWith("0x") || key.length !== 66) {
         throw new Error("runInferenceWithKey: privateKey must be a 0x-prefixed 32-byte hex string");
     }
+    if (args.signal?.aborted) {
+        throw new Error("runInferenceWithKey: aborted before start");
+    }
     const account = viemPrivateKeyToAccount(key);
     const chain = {
         id: network.chainId,
@@ -504,7 +509,7 @@ export async function runInferenceWithKey(args) {
     // looks like a CORS or undici-level reachability error.
     const fetchOrFail = async (url, init, label) => {
         try {
-            return await fetch(url, init);
+            return await fetch(url, { ...init, signal: args.signal });
         }
         catch (err) {
             const cause = err.cause;
@@ -574,6 +579,7 @@ export async function runInferenceWithKey(args) {
         jobCompletedTimeoutMs: args.jobCompletedTimeoutMs,
         WebSocket: wsCtor,
         relayUrl: args.relayUrl,
+        signal: args.signal,
     });
 }
 /**

package/dist/networks.js

@@ -17,6 +17,12 @@ export const NETWORKS = {
         aiConfig: "0x24D11533C354092ed6E18b964257819cE78Ce77D",
         jobRegistry: "0xfB15F90298e4CcD7106E76fFB5e520315cC42B0b",
         minStakeLcai: 50000,
+        // Sourced from LightChain's official "Mainnet Contract Addresses" page.
+        feePool: "0x0000000000000000000000000000000000001004",
+        nativeVotes: "0x0000000000000000000000000000000000001001",
+        governor: "0x262E9f9232933E8565253918db703baD58DE93aB",
+        timelock: "0x79e571420c5473Ca9b0FCd599B1b0062D7793c97",
+        treasury: "0x786eDe8C42Ca54E54c9dCECa9b30052CF4743389",
     },
     testnet: {
         id: "testnet",
@@ -30,6 +36,9 @@ export const NETWORKS = {
         aiConfig: "0xeCF4Ca5Ba6D97ae586993e170764a1E92231b67e",
         jobRegistry: "0x531b3a87c5d785441b9cf55b98169f20fd9056a7",
         minStakeLcai: 5000,
+        // Same genesis predeploys as mainnet (chain bytecode is identical).
+        feePool: "0x0000000000000000000000000000000000001004",
+        nativeVotes: "0x0000000000000000000000000000000000001001",
     },
 };
 /** WorkerRegistry genesis predeploy (same address on both networks). */

package/dist/types.d.ts

@@ -12,6 +12,16 @@ export interface NetworkConfig {
     aiConfig: string;
     jobRegistry: string;
     minStakeLcai: number;
+    /** FeePool genesis predeploy. Where per-job fees accumulate before payout. */
+    feePool?: string;
+    /** NativeVotes precompile (mainnet only - backs LightChainGovernor). */
+    nativeVotes?: string;
+    /** On-chain DAO governor (mainnet only today). */
+    governor?: string;
+    /** Governor timelock controller (mainnet only). */
+    timelock?: string;
+    /** DAO-controlled treasury (mainnet only). */
+    treasury?: string;
 }
 export interface Worker {
     id: string;