@gns-foundation/hive-worker 0.1.10 → 0.5.0

package/src/cli.ts

@@ -12,6 +12,7 @@
 
 import { program } from 'commander';
 import { loadOrCreateIdentity, shortPk, identityPath } from './identity.js';
+import { initWorkerMobyDB, shutdownMobyDB } from "./mobydb_hooks.js";
 import { detectHardware, detectGeo } from './hardware.js';
 import { registerNode, heartbeat, deregisterNode, fetchSwarmStats, fetchTokenBalance } from './registry.js';
 import { findRpcBinary, startRpcServer, stopRpcServer, DEFAULT_RPC_PORT, type LlamaRpcHandle } from './llama.js';
@@ -77,6 +78,9 @@ async function cmdJoin(opts: {
   const geo = await detectGeo();
   printSuccess(`Location: ${geo.city}, ${geo.country} · H3 cell ${geo.h3Cell.slice(0, 10)}…`);
 
+  // Phase 4: Embedded MobyDB
+  initWorkerMobyDB(identity.pk, geo.h3Cell);
+
   // 5. llama-cli check (for job execution)
   const llamaCliAvailable = !!findLlamaCli();
   if (!opts.noJobs) {
@@ -317,10 +321,64 @@ async function cmdJoin(opts: {
     }
   } else if (opts.noJobs) {
     addLog('Job execution disabled (--no-jobs flag)');
-  } else {
+  } else if (!rpcHandle) {
     addLog('Observer mode — install llama.cpp + fetch a model to execute jobs');
   }
 
+  // ── Pipeline poller — runs when RPC server is available ──────
+  // This is the primary job handler when rpc-server is running.
+  // It claims jobs and runs them distributed (or solo if no peers).
+  if (!opts.noJobs && rpcHandle && (llamaCliAvailable || cachedModels.length > 0)) {
+    const PIPELINE_INTERVAL = 3000;
+    const pipelineTimer = setInterval(async () => {
+      if (state.status === 'computing') return;
+
+      try {
+        const result = await claimJobPipeline(identity.pk, geo.h3Cell);
+        if (!result) return;
+
+        const { job, peers } = result;
+        state.status = 'computing';
+
+        if (peers.length === 0) {
+          addLog(`Solo job ${job.id.slice(0, 8)} · model=${job.model_id}`);
+        } else {
+          addLog(`Pipeline job ${job.id.slice(0, 8)} · ${peers.length} peer(s) · ${peers.map(p => p.rpc_host).join(', ')}`);
+        }
+
+        try {
+          await markComputing(job.id);
+          const execResult = await executeJob(job, {
+            onLog: addLog,
+            rpcPeers: peers.length > 0 ? peers : undefined,
+          });
+          await postResult(job.id, execResult);
+          jobsCompleted++;
+          const mode = peers.length > 0 ? 'distributed' : 'solo';
+          addLog(`Job ${job.id.slice(0, 8)} done · ${execResult.tokensPerSecond} tok/s (${mode})`);
+          state.tokensEarned += job.gns_reward * SPLIT.WORKER;
+          await creditWorker(identity.pk, job.id, job.gns_reward).catch(() => {});
+        } catch (execErr) {
+          const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
+          await postFailure(job.id, errMsg).catch(() => {});
+          addLog(`Job ${job.id.slice(0, 8)} failed: ${errMsg.slice(0, 60)}`);
+        } finally {
+          state.status = 'idle';
+        }
+      } catch (err) {
+        // Non-fatal poll errors
+      }
+    }, PIPELINE_INTERVAL);
+
+    // Wrap timer in jobPoller for cleanup
+    const prevStop = jobPoller?.stop.bind(jobPoller);
+    jobPoller = {
+      stop: () => { prevStop?.(); clearInterval(pipelineTimer); },
+    } as any;
+
+    addLog('Pipeline poller started — RPC server ready for distributed inference');
+  }
+
   // ─── Dashboard refresh ────────────────────────────────────────
 
   const dashTimer = setInterval(() => {
@@ -337,6 +395,7 @@ async function cmdJoin(opts: {
     clearInterval(statsTimer);
     clearInterval(dashTimer);
     jobPoller?.stop();
+    shutdownMobyDB();
     clearDashboard();
 
     console.log('\n');
@@ -426,7 +485,7 @@ async function cmdModelsList(): Promise<void> {
     }
   }
   console.log('');
-  printInfo('Available models: phi-3-mini, gemma-2-2b, tinyllama');
+  printInfo('Available models: phi-3-mini, gemma-2-2b, tinyllama, lfm2.5-1.2b-instruct, lfm2.5-1.2b-thinking');
   console.log('');
 }
 
@@ -441,7 +500,7 @@ async function cmdModelsFetch(modelId: string): Promise<void> {
 
   const url = resolveModelUrl(job as HiveJob);
   if (!url) {
-    printError(`Unknown model "${modelId}". Available: phi-3-mini, gemma-2-2b, tinyllama`);
+    printError(`Unknown model "${modelId}". Available: phi-3-mini, gemma-2-2b, tinyllama, lfm2.5-1.2b-instruct, lfm2.5-1.2b-thinking`);
     process.exit(1);
   }
 
@@ -504,7 +563,7 @@ models
 
 models
   .command('fetch <model-id>')
-  .description('Download a model (phi-3-mini, gemma-2-2b, tinyllama)')
+  .description('Download a model (phi-3-mini, gemma-2-2b, tinyllama, lfm2.5-1.2b-instruct, lfm2.5-1.2b-thinking)')
   .action(async (modelId: string) => { await cmdModelsFetch(modelId); });
 
 program.parse();

package/src/cli.ts.v0.5.bak.20260515T094956Z

@@ -0,0 +1,569 @@
+#!/usr/bin/env node
+// ============================================================
+// HIVE WORKER CLI
+// Usage:
+//   npx @gns-foundation/hive-worker join [--handle <@name>] [--rpc-port <port>]
+//   npx @gns-foundation/hive-worker status
+//   npx @gns-foundation/hive-worker leave
+//   npx @gns-foundation/hive-worker whoami
+//   npx @gns-foundation/hive-worker models list
+//   npx @gns-foundation/hive-worker models fetch <model-id>
+// ============================================================
+
+import { program } from 'commander';
+import { loadOrCreateIdentity, shortPk, identityPath } from './identity.js';
+import { initWorkerMobyDB, shutdownMobyDB } from "./mobydb_hooks.js";
+import { detectHardware, detectGeo } from './hardware.js';
+import { registerNode, heartbeat, deregisterNode, fetchSwarmStats, fetchTokenBalance } from './registry.js';
+import { findRpcBinary, startRpcServer, stopRpcServer, DEFAULT_RPC_PORT, type LlamaRpcHandle } from './llama.js';
+import {
+  printBanner, printSuccess, printInfo, printWarn, printError,
+  renderDashboard, clearDashboard, hideCursor,
+  type DashboardState,
+} from './dashboard.js';
+import { startJobPoller, claimJobPipeline, markComputing, postResult, postFailure, postChunk, type PollController, type HiveJob, type JobResult } from './jobs.js';
+import { executeJob, downloadModel, listCachedModels, resolveModelUrl, findLlamaCli } from './executor.js';
+import { creditWorker, SPLIT } from './settlement.js';
+
+import os from 'os';
+
+// ─── Get local LAN IP ─────────────────────────────────────────
+function getLocalIp(): string | null {
+  const nets = os.networkInterfaces();
+  for (const name of Object.keys(nets)) {
+    for (const net of nets[name] ?? []) {
+      if (net.family === 'IPv4' && !net.internal) return net.address;
+    }
+  }
+  return null;
+}
+
+const HEARTBEAT_INTERVAL_MS     = 30_000;
+const STATS_REFRESH_INTERVAL_MS = 60_000;
+const DASHBOARD_REFRESH_MS      = 1_000;
+const JOB_POLL_INTERVAL_MS      = 5_000;   // poll for new jobs every 5s
+
+// ─── JOIN command ─────────────────────────────────────────────
+
+async function cmdJoin(opts: {
+  handle?: string;
+  rpcPort?: string;
+  skipRpc?: boolean;
+  noJobs?: boolean;
+}): Promise<void> {
+  printBanner();
+
+  // 1. Identity
+  const { identity, isNew } = loadOrCreateIdentity();
+  if (isNew) {
+    printSuccess(`New identity generated: ${shortPk(identity.pk)}`);
+    printInfo(`Stored at ${identityPath()}`);
+  } else {
+    printSuccess(`Identity loaded: ${shortPk(identity.pk)}`);
+  }
+
+  // 2. Handle
+  const handle = opts.handle?.replace(/^@/, '') ?? null;
+  if (handle) printSuccess(`Handle: @${handle}`);
+  else printInfo('No handle — use --handle @yourname to claim one.');
+
+  // 3. Hardware
+  printInfo('Detecting hardware...');
+  const hw = detectHardware();
+  printSuccess(`${hw.cpuCores}-core ${hw.arch} · ${hw.ramGb} GB RAM · ~${hw.estimatedTflops} TFLOPS`);
+  if (hw.gpuModel) printSuccess(`GPU: ${hw.gpuModel}`);
+
+  // 4. Geo
+  printInfo('Detecting location...');
+  const geo = await detectGeo();
+  printSuccess(`Location: ${geo.city}, ${geo.country} · H3 cell ${geo.h3Cell.slice(0, 10)}…`);
+
+  // Phase 4: Embedded MobyDB
+  initWorkerMobyDB(identity.pk, geo.h3Cell);
+
+  // 5. llama-cli check (for job execution)
+  const llamaCliAvailable = !!findLlamaCli();
+  if (!opts.noJobs) {
+    if (llamaCliAvailable) {
+      printSuccess('llama-cli found — job execution enabled');
+    } else {
+      printWarn('llama-cli not found — joining as observer (no inference jobs).');
+      printWarn('Install llama.cpp to earn GNS: https://github.com/ggerganov/llama.cpp');
+    }
+  }
+
+  // logs declared early so the rpc-server callback can reference it immediately
+  const logs: string[] = [`Joined at ${new Date().toISOString()}`];
+
+  // 6. RPC server (for pipeline/shard mode)
+  let rpcHandle: LlamaRpcHandle | null = null;
+  const rpcBinary = findRpcBinary();
+  const rpcPort = opts.skipRpc ? null : parseInt(opts.rpcPort ?? String(DEFAULT_RPC_PORT), 10);
+
+  if (!opts.skipRpc && rpcBinary) {
+    printInfo(`Starting llama.cpp rpc-server on :${rpcPort}...`);
+    rpcHandle = startRpcServer(rpcPort!, (line) => logs.push(line));
+    if (rpcHandle) printSuccess(`RPC server PID ${rpcHandle.pid} on :${rpcPort}`);
+  } else if (!opts.skipRpc) {
+    printWarn('rpc-server not found — pipeline mode disabled.');
+  }
+
+  // 7. Register
+  printInfo('Registering with GEIANT Hive swarm...');
+  try {
+    const cachedModelIds = listCachedModels().map(m => m.modelId);
+    const localIp = rpcHandle ? getLocalIp() : null;
+    await registerNode(identity, hw, geo, handle, rpcHandle?.port ?? null, cachedModelIds, localIp, !!rpcHandle);
+    printSuccess('Registered in swarm registry');
+  } catch (err) {
+    printError(`Registration failed: ${err instanceof Error ? err.message : String(err)}`);
+    printWarn('Continuing in offline mode — will retry on heartbeat');
+  }
+
+  // 8. Initial stats
+  let swarmStats = await fetchSwarmStats();
+  let tokensEarned = await fetchTokenBalance(identity.pk);
+  printSuccess(`Swarm: ${swarmStats.activeNodes} active nodes · ${swarmStats.totalTflops} TFLOPS`);
+
+  // Cached models
+  const cachedModels = listCachedModels();
+  if (cachedModels.length > 0) {
+    printSuccess(`Models cached: ${cachedModels.map(m => m.modelId).join(', ')}`);
+  } else if (!opts.noJobs && llamaCliAvailable) {
+    printWarn('No models cached. Fetch one: hive-worker models fetch phi-3-mini');
+  }
+
+  console.log('');
+  printInfo('Entering live mode. Press Ctrl+C to disconnect.\n');
+
+  // ─── Live state ───────────────────────────────────────────────
+
+  hideCursor();
+
+  const startTime = Date.now();
+  let heartbeatCount = 0;
+  let lastHeartbeat: Date | null = null;
+  let jobsCompleted = 0;
+
+  const addLog = (msg: string) => {
+    logs.push(`[${new Date().toLocaleTimeString()}] ${msg}`);
+    if (logs.length > 50) logs.splice(0, logs.length - 50);
+  };
+
+  const state: DashboardState = {
+    pk:            identity.pk,
+    handle,
+    status:        'idle',
+    hw,
+    geo,
+    rpcPort:       rpcHandle?.port ?? null,
+    rpcAvailable:  !!rpcBinary,
+    tokensEarned,
+    swarmStats,
+    uptimeSeconds: 0,
+    heartbeatCount: 0,
+    lastHeartbeat: null,
+    logs,
+  };
+
+  // ─── Heartbeat timer ─────────────────────────────────────────
+
+  const heartbeatTimer = setInterval(async () => {
+    try {
+      const freshModels = listCachedModels().map(m => m.modelId);
+      const localIp = rpcHandle ? getLocalIp() : null;
+      await heartbeat(identity.pk, state.status, freshModels, localIp);
+      heartbeatCount++;
+      lastHeartbeat = new Date();
+      state.heartbeatCount = heartbeatCount;
+      state.lastHeartbeat = lastHeartbeat;
+      addLog(`Heartbeat #${heartbeatCount}`);
+    } catch (err) {
+      addLog(`Heartbeat error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }, HEARTBEAT_INTERVAL_MS);
+
+  // ─── Stats refresh timer ─────────────────────────────────────
+
+  const statsTimer = setInterval(async () => {
+    try {
+      swarmStats    = await fetchSwarmStats();
+      tokensEarned  = await fetchTokenBalance(identity.pk);
+      state.swarmStats   = swarmStats;
+      state.tokensEarned = tokensEarned;
+    } catch { /* non-fatal */ }
+  }, STATS_REFRESH_INTERVAL_MS);
+
+  // ─── Job polling loop ─────────────────────────────────────────
+
+  let jobPoller: PollController | null = null;
+
+  // When RPC server is running, pipeline poller handles everything
+  // Standard poller only runs when no RPC server is available
+  const useStandardPoller = !rpcHandle;
+
+  if (!opts.noJobs && useStandardPoller && (llamaCliAvailable || cachedModels.length > 0)) {
+    jobPoller = startJobPoller({
+      workerPk:   identity.pk,
+      h3Cell:     geo.h3Cell,
+      intervalMs: JOB_POLL_INTERVAL_MS,
+
+      onJobClaimed: (job: HiveJob) => {
+        state.status = 'computing';
+        addLog(`Job claimed: ${job.id.slice(0, 8)} · model=${job.model_id} · ${job.max_tokens} tokens`);
+      },
+
+      onJobCompleted: (job: HiveJob, result: JobResult) => {
+        state.status = 'idle';
+        jobsCompleted++;
+        addLog(
+          `Job ${job.id.slice(0, 8)} done · ${result.tokensPerSecond} tok/s · ` +
+          `earned ${(job.gns_reward * SPLIT.WORKER).toFixed(4)} GNS`,
+        );
+        // Optimistic local credit (server-side Stellar TX is async)
+        state.tokensEarned += job.gns_reward * SPLIT.WORKER;
+        // Kick off background settlement
+        creditWorker(identity.pk, job.id, job.gns_reward)
+          .then(rec => {
+            if (rec.stellarTxHash) {
+              addLog(`Settled · TX ${rec.stellarTxHash.slice(0, 12)}…`);
+            }
+          })
+          .catch(err => addLog(`Settlement error: ${err instanceof Error ? err.message : String(err)}`));
+      },
+
+      onJobFailed: (job: HiveJob, error: string) => {
+        state.status = 'idle';
+        addLog(`Job ${job.id.slice(0, 8)} failed: ${error.slice(0, 60)}`);
+      },
+
+      onLog: addLog,
+
+      executor: async (job: HiveJob, onToken?: (t: string) => void) => {
+        return executeJob(job, {
+          onToken,
+          onLog: addLog,
+          // No RPC peers in standard mode — solo execution
+        });
+      },
+    });
+
+    addLog('Job poller started — polling every 5s');
+
+    // ── Pipeline poll loop (only when RPC server is running) ──
+    // Polls for jobs and uses split inference when peers are available.
+    if (rpcHandle) {
+      const PIPELINE_INTERVAL = 3000; // faster than standard poll — pipeline takes priority
+      const pipelineTimer = setInterval(async () => {
+        if (state.status === 'computing') return; // already busy
+
+        try {
+          const result = await claimJobPipeline(
+            identity.pk,
+            geo.h3Cell,
+          );
+          if (!result) return;
+
+          const { job, peers } = result;
+          if (peers.length === 0) {
+            // No peers available — run solo on this worker
+            addLog(`Solo job ${job.id.slice(0, 8)} (no RPC peers available)`);
+            try {
+              await markComputing(job.id);
+              const execResult = await executeJob(job, { onLog: addLog });
+              await postResult(job.id, execResult);
+              jobsCompleted++;
+              addLog(`Solo job ${job.id.slice(0, 8)} done · ${execResult.tokensPerSecond} tok/s`);
+              state.tokensEarned += job.gns_reward * SPLIT.WORKER;
+              await creditWorker(identity.pk, job.id, job.gns_reward).catch(() => {});
+            } catch (execErr) {
+              const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
+              await postFailure(job.id, errMsg).catch(() => {});
+            } finally {
+              state.status = 'idle';
+            }
+            return;
+          }
+
+          state.status = 'computing';
+          addLog(`Pipeline job ${job.id.slice(0, 8)} · ${peers.length} peer(s) · ${peers.map(p => p.rpc_host).join(', ')}`);
+
+          try {
+            await markComputing(job.id);
+            const execResult = await executeJob(job, {
+              onLog: addLog,
+              rpcPeers: peers,
+            });
+            await postResult(job.id, execResult);
+            jobsCompleted++;
+            addLog(`Pipeline job ${job.id.slice(0, 8)} done · ${execResult.tokensPerSecond} tok/s (distributed)`);
+            state.tokensEarned += job.gns_reward * SPLIT.WORKER;
+          } catch (execErr) {
+            const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
+            await postFailure(job.id, errMsg).catch(() => {});
+            addLog(`Pipeline job ${job.id.slice(0, 8)} failed: ${errMsg.slice(0, 60)}`);
+          } finally {
+            state.status = 'idle';
+          }
+        } catch (err) {
+          // Non-fatal — log and continue
+          addLog(`Pipeline poll error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }, PIPELINE_INTERVAL);
+
+      // Store timer for cleanup
+      const origStop = jobPoller!.stop.bind(jobPoller);
+      jobPoller = {
+        ...jobPoller!,
+        stop: () => { origStop(); clearInterval(pipelineTimer); },
+      };
+      addLog('Pipeline poller started — RPC server ready for distributed inference');
+    }
+  } else if (opts.noJobs) {
+    addLog('Job execution disabled (--no-jobs flag)');
+  } else if (!rpcHandle) {
+    addLog('Observer mode — install llama.cpp + fetch a model to execute jobs');
+  }
+
+  // ── Pipeline poller — runs when RPC server is available ──────
+  // This is the primary job handler when rpc-server is running.
+  // It claims jobs and runs them distributed (or solo if no peers).
+  if (!opts.noJobs && rpcHandle && (llamaCliAvailable || cachedModels.length > 0)) {
+    const PIPELINE_INTERVAL = 3000;
+    const pipelineTimer = setInterval(async () => {
+      if (state.status === 'computing') return;
+
+      try {
+        const result = await claimJobPipeline(identity.pk, geo.h3Cell);
+        if (!result) return;
+
+        const { job, peers } = result;
+        state.status = 'computing';
+
+        if (peers.length === 0) {
+          addLog(`Solo job ${job.id.slice(0, 8)} · model=${job.model_id}`);
+        } else {
+          addLog(`Pipeline job ${job.id.slice(0, 8)} · ${peers.length} peer(s) · ${peers.map(p => p.rpc_host).join(', ')}`);
+        }
+
+        try {
+          await markComputing(job.id);
+          const execResult = await executeJob(job, {
+            onLog: addLog,
+            rpcPeers: peers.length > 0 ? peers : undefined,
+          });
+          await postResult(job.id, execResult);
+          jobsCompleted++;
+          const mode = peers.length > 0 ? 'distributed' : 'solo';
+          addLog(`Job ${job.id.slice(0, 8)} done · ${execResult.tokensPerSecond} tok/s (${mode})`);
+          state.tokensEarned += job.gns_reward * SPLIT.WORKER;
+          await creditWorker(identity.pk, job.id, job.gns_reward).catch(() => {});
+        } catch (execErr) {
+          const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
+          await postFailure(job.id, errMsg).catch(() => {});
+          addLog(`Job ${job.id.slice(0, 8)} failed: ${errMsg.slice(0, 60)}`);
+        } finally {
+          state.status = 'idle';
+        }
+      } catch (err) {
+        // Non-fatal poll errors
+      }
+    }, PIPELINE_INTERVAL);
+
+    // Wrap timer in jobPoller for cleanup
+    const prevStop = jobPoller?.stop.bind(jobPoller);
+    jobPoller = {
+      stop: () => { prevStop?.(); clearInterval(pipelineTimer); },
+    } as any;
+
+    addLog('Pipeline poller started — RPC server ready for distributed inference');
+  }
+
+  // ─── Dashboard refresh ────────────────────────────────────────
+
+  const dashTimer = setInterval(() => {
+    state.uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
+    renderDashboard(state);
+  }, DASHBOARD_REFRESH_MS);
+
+  renderDashboard(state);
+
+  // ─── Graceful shutdown ────────────────────────────────────────
+
+  const shutdown = async (signal: string) => {
+    clearInterval(heartbeatTimer);
+    clearInterval(statsTimer);
+    clearInterval(dashTimer);
+    jobPoller?.stop();
+    shutdownMobyDB();
+    clearDashboard();
+
+    console.log('\n');
+    printInfo(`Received ${signal}. Disconnecting gracefully...`);
+
+    try {
+      await deregisterNode(identity.pk);
+      printSuccess('Marked offline in swarm registry');
+    } catch { /* best-effort */ }
+
+    if (rpcHandle) {
+      stopRpcServer(rpcHandle);
+      printSuccess('RPC server stopped');
+    }
+
+    const earned = await fetchTokenBalance(identity.pk).catch(() => state.tokensEarned);
+    printSuccess(`Session complete · ${jobsCompleted} jobs · ${earned.toFixed(4)} GNS earned`);
+    console.log('');
+    process.exit(0);
+  };
+
+  process.on('SIGINT',  () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+// ─── STATUS command ───────────────────────────────────────────
+
+async function cmdStatus(): Promise<void> {
+  printBanner();
+  const { identity } = loadOrCreateIdentity();
+  printInfo(`Identity: ${shortPk(identity.pk)}`);
+
+  const stats  = await fetchSwarmStats();
+  const tokens = await fetchTokenBalance(identity.pk);
+  printInfo(`Swarm: ${stats.activeNodes} active nodes · ${stats.totalTflops} TFLOPS`);
+  printInfo(`GNS earned: ${tokens.toFixed(4)}`);
+
+  const models = listCachedModels();
+  if (models.length > 0) {
+    printInfo(`Cached models: ${models.map(m => `${m.modelId} (${m.sizeMb} MB)`).join(', ')}`);
+  } else {
+    printWarn('No models cached. Run: hive-worker models fetch phi-3-mini');
+  }
+
+  const llamaCli = findLlamaCli();
+  const rpcBin   = findRpcBinary();
+  printInfo(`llama-cli: ${llamaCli ?? 'not found'}`);
+  printInfo(`rpc-server: ${rpcBin ?? 'not found'}`);
+}
+
+// ─── LEAVE command ────────────────────────────────────────────
+
+async function cmdLeave(): Promise<void> {
+  printBanner();
+  const { identity } = loadOrCreateIdentity();
+  printInfo(`Deregistering ${shortPk(identity.pk)} from swarm...`);
+  await deregisterNode(identity.pk);
+  printSuccess('Marked offline. Identity preserved at ' + identityPath());
+  printInfo('Run `hive-worker join` to rejoin.');
+}
+
+// ─── WHOAMI command ───────────────────────────────────────────
+
+async function cmdWhoami(): Promise<void> {
+  const { identity, isNew } = loadOrCreateIdentity();
+  if (isNew) printWarn('No identity found — a new one was just generated.');
+  console.log('');
+  console.log(`  pk:      ${identity.pk}`);
+  console.log(`  short:   ${shortPk(identity.pk)}`);
+  console.log(`  created: ${identity.createdAt}`);
+  console.log(`  file:    ${identityPath()}`);
+  console.log('');
+}
+
+// ─── MODELS LIST command ──────────────────────────────────────
+
+async function cmdModelsList(): Promise<void> {
+  const cached = listCachedModels();
+  console.log('');
+  if (cached.length === 0) {
+    printWarn('No models cached yet.');
+    printInfo('Fetch one: hive-worker models fetch phi-3-mini');
+  } else {
+    printSuccess(`${cached.length} model(s) cached:`);
+    for (const m of cached) {
+      console.log(`    ${m.modelId.padEnd(20)} ${m.sizeMb} MB`);
+    }
+  }
+  console.log('');
+  printInfo('Available models: phi-3-mini, gemma-2-2b, tinyllama');
+  console.log('');
+}
+
+// ─── MODELS FETCH command ─────────────────────────────────────
+
+async function cmdModelsFetch(modelId: string): Promise<void> {
+  printBanner();
+  const job = {
+    model_id:  modelId,
+    model_url: null,
+  } as Pick<HiveJob, 'model_id' | 'model_url'>;
+
+  const url = resolveModelUrl(job as HiveJob);
+  if (!url) {
+    printError(`Unknown model "${modelId}". Available: phi-3-mini, gemma-2-2b, tinyllama`);
+    process.exit(1);
+  }
+
+  printInfo(`Downloading ${modelId}...`);
+  printInfo(`Source: ${url}`);
+  console.log('');
+
+  let lastPct = -1;
+  const dest = await downloadModel(modelId, url, (pct, mbDone, mbTotal) => {
+    if (pct !== lastPct) {
+      process.stdout.write(`\r  Downloading... ${pct}% (${mbDone} / ${mbTotal} MB)   `);
+      lastPct = pct;
+    }
+  });
+
+  console.log('');
+  printSuccess(`Saved to ${dest}`);
+  printInfo('You can now run: hive-worker join');
+}
+
+// ─── CLI definition ───────────────────────────────────────────
+
+program
+  .name('hive-worker')
+  .description('GEIANT Hive compute node — earn GNS tokens for idle compute')
+  .version('0.1.0');
+
+program
+  .command('join')
+  .description('Join the GEIANT Hive swarm and start earning GNS')
+  .option('--handle <n>',      'Your GNS handle (e.g. @alice)')
+  .option('--rpc-port <port>', 'Port for llama.cpp rpc-server', String(DEFAULT_RPC_PORT))
+  .option('--skip-rpc',         'Skip starting rpc-server')
+  .option('--no-jobs',         'Observer only — do not execute inference jobs')
+  .action(async (opts) => { await cmdJoin(opts); });
+
+program
+  .command('status')
+  .description('Show swarm status and your token balance')
+  .action(async () => { await cmdStatus(); });
+
+program
+  .command('leave')
+  .description('Gracefully disconnect from the swarm')
+  .action(async () => { await cmdLeave(); });
+
+program
+  .command('whoami')
+  .description('Show your Hive identity')
+  .action(async () => { await cmdWhoami(); });
+
+const models = program
+  .command('models')
+  .description('Manage locally cached inference models');
+
+models
+  .command('list')
+  .description('List cached models')
+  .action(async () => { await cmdModelsList(); });
+
+models
+  .command('fetch <model-id>')
+  .description('Download a model (phi-3-mini, gemma-2-2b, tinyllama)')
+  .action(async (modelId: string) => { await cmdModelsFetch(modelId); });
+
+program.parse();

package/src/executor.ts

@@ -69,6 +69,10 @@ const KNOWN_MODELS: Record<string, string> = {
     'https://huggingface.co/bartowski/gemma-2-2b-it-GGUF/resolve/main/gemma-2-2b-it-Q4_K_M.gguf',
   'tinyllama':
     'https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf',
+  'lfm2.5-1.2b-instruct':
+    'https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct-GGUF/resolve/main/LFM2.5-1.2B-Instruct-Q4_K_M.gguf',
+  'lfm2.5-1.2b-thinking':
+    'https://huggingface.co/LiquidAI/LFM2.5-1.2B-Thinking-GGUF/resolve/main/LFM2.5-1.2B-Thinking-Q4_K_M.gguf',
 };
 
 export function resolveModelUrl(job: HiveJob): string | null {