@gns-foundation/hive-worker 0.1.0

package/src/cli.ts

@@ -0,0 +1,418 @@
+#!/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 { 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, type PollController, type HiveJob, type JobResult } from './jobs.js';
+import { executeJob, downloadModel, listCachedModels, resolveModelUrl, findLlamaCli } from './executor.js';
+import { creditWorker, SPLIT } from './settlement.js';
+
+const HEARTBEAT_INTERVAL_MS     = 30_000;
+const STATS_REFRESH_INTERVAL_MS = 60_000;
+const DASHBOARD_REFRESH_MS      = 3_000;
+const JOB_POLL_INTERVAL_MS      = 5_000;   // poll for new jobs every 5s
+
+// ─── JOIN command ─────────────────────────────────────────────
+
+async function cmdJoin(opts: {
+  handle?: string;
+  rpcPort?: string;
+  noRpc?: 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)}…`);
+
+  // 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.noRpc ? null : parseInt(opts.rpcPort ?? String(DEFAULT_RPC_PORT), 10);
+
+  if (opts.noRpc !== true && 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.noRpc !== true) {
+    printWarn('rpc-server not found — pipeline mode disabled.');
+  }
+
+  // 7. Register
+  printInfo('Registering with GEIANT Hive swarm...');
+  try {
+    await registerNode(identity, hw, geo, handle, rpcHandle?.port ?? null);
+    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 {
+      await heartbeat(identity.pk, state.status);
+      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;
+
+  if (!opts.noJobs && (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) => {
+        return executeJob(job, {
+          onToken: (_tok) => { /* streaming tokens — could update dashboard */ },
+          onLog:   addLog,
+        });
+      },
+    });
+
+    addLog('Job poller started — polling every 5s');
+  } else if (opts.noJobs) {
+    addLog('Job execution disabled (--no-jobs flag)');
+  } else {
+    addLog('Observer mode — install llama.cpp + fetch a model to execute jobs');
+  }
+
+  // ─── 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();
+    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('--no-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/dashboard.ts

@@ -0,0 +1,129 @@
+// ============================================================
+// HIVE WORKER — TERMINAL DASHBOARD (simple logger mode)
+// No ANSI cursor movement — just clean line-by-line output.
+// Eliminates the flickering caused by cursor-up + clear redraws.
+// ============================================================
+
+import type { HardwareProfile, GeoProfile } from './hardware.js';
+import type { RegistryStats, WorkerStatus } from './registry.js';
+
+const A = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  green:   '\x1b[32m',
+  cyan:    '\x1b[36m',
+  yellow:  '\x1b[33m',
+  magenta: '\x1b[35m',
+  gray:    '\x1b[90m',
+  white:   '\x1b[37m',
+};
+const col = (c: string, s: string) => `${c}${s}${A.reset}`;
+
+export interface DashboardState {
+  pk: string;
+  handle: string | null;
+  status: WorkerStatus;
+  hw: HardwareProfile;
+  geo: GeoProfile;
+  rpcPort: number | null;
+  rpcAvailable: boolean;
+  tokensEarned: number;
+  swarmStats: RegistryStats;
+  uptimeSeconds: number;
+  heartbeatCount: number;
+  lastHeartbeat: Date | null;
+  logs: string[];
+}
+
+// Track what we last printed so we only reprint on change
+let lastStatus: WorkerStatus | null = null;
+let lastHeartbeat = 0;
+let lastTokens = -1;
+let lastSwarmNodes = -1;
+let lastLogCount = 0;
+let headerPrinted = false;
+
+export function renderDashboard(state: DashboardState): void {
+  // Print header once
+  if (!headerPrinted) {
+    console.log('');
+    console.log(col(A.cyan + A.bold, '  ◆ GEIANT HIVE WORKER v0.1.0'));
+    console.log(col(A.gray, `  ${state.hw.cpuCores}c ${state.hw.arch} · ${state.hw.ramGb} GB · ~${state.hw.estimatedTflops} TFLOPS · ${state.geo.city}`));
+    console.log(col(A.gray, `  Identity: ${col(A.cyan, state.pk.slice(0, 8))}${state.handle ? ' · @' + state.handle : ''}`));
+    console.log(col(A.gray, '  ─────────────────────────────────────'));
+    headerPrinted = true;
+  }
+
+  // Print status line only when status changes
+  if (state.status !== lastStatus) {
+    const icon = state.status === 'idle'      ? col(A.green,  '●')
+               : state.status === 'computing' ? col(A.yellow, '◉')
+               :                                col(A.gray,   '○');
+    console.log(`  ${icon} ${col(A.white, state.status.toUpperCase())}  ${col(A.gray, new Date().toLocaleTimeString())}`);
+    lastStatus = state.status;
+  }
+
+  // Print heartbeat line only on new heartbeat
+  if (state.heartbeatCount > lastHeartbeat) {
+    console.log(col(A.gray, `  ♥ Heartbeat #${state.heartbeatCount} · uptime ${humanUptime(state.uptimeSeconds)}`));
+    lastHeartbeat = state.heartbeatCount;
+  }
+
+  // Print swarm update when node count changes
+  if (state.swarmStats.activeNodes !== lastSwarmNodes) {
+    console.log(col(A.gray, `  ⬡ Swarm: ${col(A.white, String(state.swarmStats.activeNodes))} nodes · ${col(A.yellow, state.swarmStats.totalTflops + ' TFLOPS')}`));
+    lastSwarmNodes = state.swarmStats.activeNodes;
+  }
+
+  // Print earnings update when tokens change
+  if (state.tokensEarned !== lastTokens) {
+    console.log(col(A.green, `  ✦ Earned: ${state.tokensEarned.toFixed(4)} GNS`));
+    lastTokens = state.tokensEarned;
+  }
+
+  // Print only new log lines
+  if (state.logs.length > lastLogCount) {
+    const newLines = state.logs.slice(lastLogCount);
+    for (const line of newLines) {
+      console.log(col(A.gray, '  › ') + col(A.white, line.slice(0, 72)));
+    }
+    lastLogCount = state.logs.length;
+  }
+}
+
+export function clearDashboard(): void {
+  // Nothing to clear in logger mode
+}
+
+export function hideCursor(): void {
+  // No cursor hiding in logger mode — not needed
+}
+
+function humanUptime(s: number): string {
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+
+export function printBanner(): void {
+  console.log('');
+  console.log(col(A.cyan + A.bold, '  ◆ GEIANT HIVE WORKER'));
+  console.log(col(A.gray, '  geiant.com/hive  ·  Powered by GNS Protocol'));
+  console.log('');
+}
+
+export function printSuccess(msg: string): void {
+  console.log(`  ${col(A.green, '✓')} ${msg}`);
+}
+
+export function printInfo(msg: string): void {
+  console.log(`  ${col(A.cyan, '›')} ${msg}`);
+}
+
+export function printWarn(msg: string): void {
+  console.log(`  ${col(A.yellow, '!')} ${msg}`);
+}
+
+export function printError(msg: string): void {
+  console.log(`  ${col(A.magenta, '✗')} ${msg}`);
+}