lightnode-sdk 0.4.0 → 0.4.2

package/dist/add.d.ts

@@ -36,6 +36,12 @@ export declare function addAnalyticsDashboard(opts?: AddOpts): {
     template: Template;
     network: Network;
 };
+export declare function addAgent(opts?: AddOpts): {
+    written: WrittenFile[];
+    install: string;
+    template: Template;
+    network: Network;
+};
 export declare function addChat(opts?: AddOpts): {
     written: WrittenFile[];
     install: string;

package/dist/add.js

@@ -897,6 +897,175 @@ while (true) {
   }
 }
 `;
+// ---------------------------------------------------------------------------
+// `lightnode add agent` - drop in a scheduled/loop inference scaffold. Good
+// for daily summarizers, monitoring agents, cron jobs that run inference on a
+// fixed cadence. For Next.js: a /api/agent route that Vercel Cron (or any
+// cron-style trigger) can hit on schedule. For Node: a standalone script that
+// runs inference on an interval until you kill it.
+// ---------------------------------------------------------------------------
+const NEXTJS_AGENT_ROUTE = `// app/api/agent/route.ts
+// Generated by 'lightnode add agent'.
+//
+// Set up Vercel Cron in vercel.json:
+//   { "crons": [{ "path": "/api/agent", "schedule": "0 9 * * *" }] }
+// That hits this route every day at 09:00 UTC.
+//
+// Auth your cron call: Vercel Cron sends a Bearer token in the Authorization
+// header that you can verify here against CRON_SECRET. See:
+// https://vercel.com/docs/cron-jobs/manage-cron-jobs#securing-cron-jobs
+import { NextResponse } from "next/server";
+import WS from "ws";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { LightNode, GatewayClient, runInference, consumerGatewayUrl, type NetworkId } from "lightnode-sdk";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+export const maxDuration = 120;
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as NetworkId;
+const MODEL = process.env.MODEL ?? "llama3-8b";
+const TASK_PROMPT = process.env.AGENT_TASK ?? "Summarize today's news in 3 bullet points.";
+
+export async function GET(req: Request) {
+  // Verify Vercel Cron sent this. Set CRON_SECRET in your Vercel env vars; the
+  // platform automatically injects it as the Bearer token on cron-fired requests.
+  const auth = req.headers.get("authorization");
+  if (process.env.CRON_SECRET && auth !== \`Bearer \${process.env.CRON_SECRET}\`) {
+    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+  }
+  if (!process.env.PRIVATE_KEY?.startsWith("0x")) {
+    return NextResponse.json({ error: "PRIVATE_KEY not configured" }, { status: 500 });
+  }
+
+  const ln = new LightNode(NETWORK);
+  const acct = privateKeyToAccount(process.env.PRIVATE_KEY as \`0x\${string}\`);
+  const chain = { id: ln.network.chainId, name: ln.network.label, nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 }, rpcUrls: { default: { http: [ln.network.rpc] } } };
+  const publicClient = createPublicClient({ transport: http(ln.network.rpc), chain });
+  const wallet = createWalletClient({ account: acct, transport: http(ln.network.rpc), chain });
+
+  // SIWE -> JWT (one handshake per agent run).
+  const ch = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/challenge?address=\${acct.address}\`)).json() as { message?: string };
+  if (!ch.message) return NextResponse.json({ error: "auth challenge failed" }, { status: 502 });
+  const sig = await wallet.signMessage({ message: ch.message });
+  const verify = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/verify\`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message: ch.message, signature: sig }) })).json() as { token?: string };
+  if (!verify.token) return NextResponse.json({ error: "auth verify failed" }, { status: 502 });
+  const gateway = new GatewayClient({ network: NETWORK, bearer: verify.token });
+
+  // ---- your agent's logic ------------------------------------------------
+  // Replace this block with whatever your scheduled task should do. By default
+  // it just runs a single inference call with the AGENT_TASK prompt and stores
+  // the result; you might fetch upstream data first, run multiple turns, post
+  // results to Slack/Discord/a DB, etc.
+  try {
+    const result = await runInference({
+      prompt: TASK_PROMPT,
+      gateway, wallet, publicClient, network: ln.network,
+      model: MODEL, WebSocket: WS, maxRetries: 2,
+    });
+    // TODO: persist result.answer somewhere durable (DB, S3, send to Slack, etc.).
+    return NextResponse.json({
+      ok: true,
+      answer: result.answer,
+      txs: result.txs,
+      jobId: result.jobId.toString(),
+      ranAt: new Date().toISOString(),
+    });
+  } catch (e) {
+    return NextResponse.json({ ok: false, error: (e as Error).message }, { status: 500 });
+  }
+}
+`;
+const NEXTJS_AGENT_VERCEL_JSON = `{
+  "crons": [
+    {
+      "path": "/api/agent",
+      "schedule": "0 9 * * *"
+    }
+  ]
+}
+`;
+const NODE_AGENT_SCRIPT = `// agent.ts
+// Generated by 'lightnode add agent'. A long-running script that runs inference
+// on a fixed cadence. Use it under pm2, systemd, a Docker container - anywhere
+// you'd run a daemon.
+//   npm install lightnode-sdk viem ws
+//   AGENT_INTERVAL_MS=3600000 tsx agent.ts
+import WS from "ws";
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { LightNode, GatewayClient, runInference, consumerGatewayUrl, isStalledWorker, type NetworkId } from "lightnode-sdk";
+
+const NETWORK = (process.env.NETWORK ?? "testnet") as NetworkId;
+const MODEL = process.env.MODEL ?? "llama3-8b";
+const TASK_PROMPT = process.env.AGENT_TASK ?? "Summarize today's news in 3 bullet points.";
+const INTERVAL_MS = Number(process.env.AGENT_INTERVAL_MS ?? 24 * 60 * 60 * 1000); // default daily
+const PRIVATE_KEY = process.env.PRIVATE_KEY as \`0x\${string}\` | undefined;
+if (!PRIVATE_KEY?.startsWith("0x") || PRIVATE_KEY.length !== 66) { console.error("set PRIVATE_KEY in .env"); process.exit(1); }
+
+const ln = new LightNode(NETWORK);
+const acct = privateKeyToAccount(PRIVATE_KEY);
+const chain = { id: ln.network.chainId, name: ln.network.label, nativeCurrency: { name: "LCAI", symbol: "LCAI", decimals: 18 }, rpcUrls: { default: { http: [ln.network.rpc] } } };
+const publicClient = createPublicClient({ transport: http(ln.network.rpc), chain });
+const wallet = createWalletClient({ account: acct, transport: http(ln.network.rpc), chain });
+
+// One SIWE handshake per process; refreshed lazily when the JWT expires.
+async function freshGateway() {
+  const ch = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/challenge?address=\${acct.address}\`)).json() as { message?: string };
+  if (!ch.message) throw new Error("auth challenge failed");
+  const sig = await wallet.signMessage({ message: ch.message });
+  const verify = await (await fetch(\`\${consumerGatewayUrl(NETWORK)}/api/auth/verify\`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message: ch.message, signature: sig }) })).json() as { token?: string };
+  if (!verify.token) throw new Error("auth verify failed");
+  return new GatewayClient({ network: NETWORK, bearer: verify.token });
+}
+
+let gateway = await freshGateway();
+console.log(\`▶ agent ready on \${NETWORK}, interval=\${(INTERVAL_MS / 1000 / 60).toFixed(1)} min, task=\${TASK_PROMPT.slice(0, 60)}…\\n\`);
+
+async function tick() {
+  console.log(\`[\${new Date().toISOString()}] tick\`);
+  try {
+    const result = await runInference({
+      prompt: TASK_PROMPT,
+      gateway, wallet, publicClient, network: ln.network,
+      model: MODEL, WebSocket: WS, maxRetries: 2,
+    });
+    // ---- your agent's output sink: write to a DB, post to Slack, etc. ----
+    console.log(\`[\${new Date().toISOString()}] answer:\\n\${result.answer}\\n  (createSession=\${result.txs.createSession.slice(0, 14)}…, jobCompleted=\${result.txs.jobCompleted.slice(0, 14)}…)\\n\`);
+  } catch (e) {
+    if (isStalledWorker(e)) console.error(\`[\${new Date().toISOString()}] all workers stalled this round; protocol refunds, skipping\`);
+    else if ((e as Error).message.includes("auth")) { console.warn("JWT expired; re-authing"); gateway = await freshGateway(); }
+    else console.error(\`[\${new Date().toISOString()}] tick failed:\`, (e as Error).message);
+  }
+}
+
+await tick(); // run once immediately
+setInterval(tick, INTERVAL_MS);
+
+// Keep alive forever.
+process.on("SIGINT", () => { console.log("\\n▶ agent stopped"); process.exit(0); });
+`;
+export function addAgent(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const network = opts.network ?? "testnet";
+    const template = opts.template && opts.template !== "auto" ? opts.template : detectTemplate(cwd);
+    const force = !!opts.force;
+    const written = [];
+    if (template === "nextjs-api") {
+        written.push(writeFile(path.join(cwd, "app/api/agent/route.ts"), NEXTJS_AGENT_ROUTE, force));
+        // Only add vercel.json if there isn't one; merging is too fragile to do
+        // blindly here (we'd risk clobbering the user's existing config).
+        if (!fs.existsSync(path.join(cwd, "vercel.json"))) {
+            written.push(writeFile(path.join(cwd, "vercel.json"), NEXTJS_AGENT_VERCEL_JSON, force));
+        }
+    }
+    else {
+        written.push(writeFile(path.join(cwd, "agent.ts"), NODE_AGENT_SCRIPT, force));
+    }
+    written.push(writeFile(path.join(cwd, ".env.example"), ENV_EXAMPLE(network), force));
+    return { written, install: `npm install ${depsNeeded(template).join(" ")}`, template, network };
+}
 export function addChat(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const network = opts.network ?? "testnet";

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { LightNode, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./index.js";
-import { addInference, addAnalyticsDashboard, addNftMint, addChat } from "./add.js";
+import { addInference, addAnalyticsDashboard, addNftMint, addChat, addAgent } from "./add.js";
 function flag(name) {
     const i = process.argv.indexOf(name);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -28,6 +28,7 @@ const HELP = `lightnode <command> [--net mainnet|testnet]
 
   add inference                   end-to-end encrypted inference route/script
   add chat                        chat-style UI with conversation history
+  add agent                       scheduled/loop inference (cron-style)
   add analytics-dashboard         read-only network + worker analytics page
   add nft-mint-with-inference     AI-generated NFT metadata (provenance on-chain)
                                   (all add commands: [--template auto|nextjs-api|hono|node] [--force])
@@ -103,7 +104,7 @@ async function main() {
             const template = flag("--template") ?? "auto";
             const force = process.argv.includes("--force");
             const network = (net === "mainnet" ? "mainnet" : "testnet");
-            const known = ["inference", "chat", "analytics-dashboard", "nft-mint-with-inference"];
+            const known = ["inference", "chat", "agent", "analytics-dashboard", "nft-mint-with-inference"];
             if (!known.includes(sub ?? "")) {
                 die(`usage: lightnode add <${known.join("|")}> [--template auto|nextjs-api|hono|node] [--net testnet|mainnet] [--force]`);
             }
@@ -113,7 +114,9 @@ async function main() {
                     ? addNftMint({ template, network, force })
                     : sub === "chat"
                         ? addChat({ template, network, force })
-                        : addInference({ template, network, force });
+                        : sub === "agent"
+                            ? addAgent({ template, network, force })
+                            : addInference({ template, network, force });
             console.log(`▶ add ${sub} (${result.template} template, default network ${result.network})`);
             for (const f of result.written) {
                 if (f.skipped)
@@ -128,9 +131,16 @@ async function main() {
             else {
                 console.log(`\nNext steps:`);
                 console.log(`  1. ${result.install}`);
-                if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat") {
+                if (sub === "nft-mint-with-inference" || sub === "inference" || sub === "chat" || sub === "agent") {
                     console.log(`  2. cp .env.example .env  (and put a funded ${result.network} PRIVATE_KEY in it)`);
-                    if (sub === "chat" && result.template === "nextjs-api") {
+                    if (sub === "agent" && result.template === "nextjs-api") {
+                        console.log(`  3. Set CRON_SECRET in your Vercel env vars + edit AGENT_TASK in .env`);
+                        console.log(`  4. Deploy. Vercel Cron fires /api/agent on the schedule in vercel.json`);
+                    }
+                    else if (sub === "agent") {
+                        console.log(`  3. AGENT_INTERVAL_MS=3600000 tsx agent.ts   # or run under pm2/systemd`);
+                    }
+                    else if (sub === "chat" && result.template === "nextjs-api") {
                         console.log(`  3. Make sure /api/inference is mounted too (run: npx lightnode add inference)`);
                         console.log(`  4. npm run dev, open /chat`);
                     }

package/dist/inference.d.ts

@@ -159,7 +159,7 @@ export interface RunInferenceArgs {
     onChunk?: (chunk: string, totalSoFar: string) => void;
     /** Retry count if a worker stalls. Default 2 (so up to 3 paid attempts). */
     maxRetries?: number;
-    /** How long to wait for JobCompleted before declaring the worker stalled. Default 90s. */
+    /** How long to wait for JobCompleted before declaring the worker stalled. Default 120s. */
     jobCompletedTimeoutMs?: number;
     /**
      * WebSocket constructor. In a browser, omit and `globalThis.WebSocket` is
@@ -179,7 +179,12 @@ export interface RunInferenceResult {
     txs: {
         createSession: `0x${string}`;
         submitJob: `0x${string}`;
-        jobCompleted: `0x${string}`;
+        /**
+         * Worker's commit-result tx. Null if the on-chain event hasn't landed by the
+         * deadline but the WS-delivered, session-key-decrypted answer DID arrive -
+         * in that case the answer is still authentic; this is just the explorer link.
+         */
+        jobCompleted: `0x${string}` | null;
     };
     /** The dispatcher-assigned worker that produced this response. */
     worker: `0x${string}`;

package/dist/inference.js

@@ -190,7 +190,7 @@ function topicAsUint(hex) {
     return BigInt(hex);
 }
 async function runOneAttempt(args, attempt) {
-    const { prompt, gateway, wallet, publicClient, network, model = "llama3-8b", onChunk, jobCompletedTimeoutMs = 90000, } = args;
+    const { prompt, gateway, wallet, publicClient, network, model = "llama3-8b", onChunk, jobCompletedTimeoutMs = 120000, } = args;
     const WS = pickWebSocket(args.WebSocket);
     const relayUrl = args.relayUrl ?? `wss://relay.${network.id}.lightchain.ai/ws`;
     // 1. prepareSession
@@ -326,6 +326,11 @@ async function runOneAttempt(args, attempt) {
         throw new Error("JobSubmitted log missing in submitJob receipt");
     const jobId = topicAsUint(jobLog.topics[1]);
     // 6. wait for JobCompleted
+    // KEY INVARIANT: the real result is the WS-delivered, session-key-decrypted
+    // ciphertext. JobCompleted is an explorer pointer (the worker's commit-result
+    // tx). If the WS already produced an answer (chunks.length > 0) we MUST
+    // accept it even if the on-chain event hasn't landed - throwing stalled here
+    // wipes a delivered answer on retry, which reads as "the call returned nothing".
     const deadline = Date.now() + jobCompletedTimeoutMs;
     const jobIdTopic = (`0x${jobId.toString(16).padStart(64, "0")}`);
     let completed = null;
@@ -338,8 +343,14 @@ async function runOneAttempt(args, attempt) {
         });
         completed =
             logs.find((l) => l.topics[0] === JOB_COMPLETED_TOPIC && l.topics[1] === jobIdTopic) ?? null;
+        if (completed)
+            break;
+        // If the WS already delivered the answer, stop polling - no point burning
+        // more time on a confirmation that only serves as an explorer link.
+        if (chunks.length > 0)
+            break;
     }
-    if (!completed) {
+    if (!completed && chunks.length === 0) {
         try {
             ws.close();
         }
@@ -363,7 +374,11 @@ async function runOneAttempt(args, attempt) {
     }
     return {
         answer: chunks.join(""),
-        txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed.transactionHash },
+        // completed may be null when the answer arrived via the WS but JobCompleted
+        // hasn't landed on-chain yet. The decrypted answer is still authentic
+        // (session-key bound); callers can poll for the event later if they want
+        // the explorer-link form of the proof.
+        txs: { createSession: createTx, submitJob: submitTx, jobCompleted: completed?.transactionHash ?? null },
         worker: prepared.createSessionArgs.worker,
         sessionId,
         jobId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",