thinknagent 0.1.0

package/bin/thinknagent.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const chalk       = require('chalk');
+const ora         = require('ora');
+const { v4: uuid} = require('uuid');
+const store       = require('../lib/store');
+const Agent       = require('../lib/agent');
+
+const program = new Command();
+
+program
+  .name('thinknagent')
+  .description('ThinkNCollab server agent')
+  .version(require('../package.json').version);
+
+// ── init ─────────────────────────────────────────────────────────────────────
+program
+  .command('init')
+  .description('Register this server with ThinkNCollab')
+  .requiredOption('--server <url>', 'ThinkNCollab server URL (e.g. https://thinkncollab.com)')
+  .requiredOption('--name <name>',  'Display name for this server on the DevOps Wall')
+  .option('--gpu',                  'Enable GPU metrics (requires nvidia-smi)')
+  .option('--logs <paths>',         'Comma-separated log file paths to stream')
+  .action(async (opts) => {
+    const existing = store.get('agentToken');
+    if (existing) {
+      console.log(chalk.yellow('Already registered. Run `thinknagent status` to check.'));
+      console.log(chalk.gray('To re-register: thinknagent revoke && thinknagent init ...'));
+      process.exit(0);
+    }
+
+    const agentId = uuid();
+    const cfg = {
+      agentId,
+      serverUrl: opts.server.replace(/\/$/, ''),
+      name:      opts.name,
+      gpu:       !!opts.gpu,
+      logs:      opts.logs ? opts.logs.split(',').map(s => s.trim()) : [],
+      alerts:    [
+        // sensible defaults — Owner can edit in browser
+        { id: 'cpu-high',  metric: 'cpu.usage',      op: 'gt', value: 85, for: 60, severity: 'warning'  },
+        { id: 'cpu-crit',  metric: 'cpu.usage',      op: 'gt', value: 95, for: 30, severity: 'critical' },
+        { id: 'mem-high',  metric: 'memory.usedPct', op: 'gt', value: 85, for: 60, severity: 'warning'  },
+        { id: 'disk-root', metric: 'disk./',         op: 'gt', value: 90, for: 0,  severity: 'critical' },
+      ],
+    };
+
+    store.write(cfg);
+
+    console.log(chalk.cyan('\n  thinknagent') + chalk.gray(` v${require('../package.json').version}`));
+    console.log(chalk.gray('  ─────────────────────────────────────────'));
+    console.log(`  Server  : ${chalk.white(cfg.serverUrl)}`);
+    console.log(`  Name    : ${chalk.white(cfg.name)}`);
+    console.log(`  Agent ID: ${chalk.white(agentId)}`);
+    console.log(`  GPU     : ${cfg.gpu ? chalk.green('enabled') : chalk.gray('disabled')}`);
+    console.log(`  Logs    : ${cfg.logs.length ? chalk.white(cfg.logs.join(', ')) : chalk.gray('none')}`);
+    console.log(chalk.gray('  ─────────────────────────────────────────'));
+    console.log(chalk.yellow('\n  Next step:'));
+    console.log('  1. Run: ' + chalk.cyan('thinknagent start'));
+    console.log('  2. An Owner of the target room must approve this agent in ThinkNCollab');
+    console.log('  3. Once approved, agent becomes active automatically\n');
+  });
+
+// ── start ─────────────────────────────────────────────────────────────────────
+program
+  .command('start')
+  .description('Start the agent (connect to ThinkNCollab)')
+  .option('--dev', 'Dev mode — verbose logging')
+  .action((opts) => {
+    if (opts.dev) process.env.THINKNAGENT_DEV = '1';
+
+    const cfg = store.read();
+    if (!cfg.serverUrl) {
+      console.error(chalk.red('Not initialized. Run: thinknagent init --server <url> --name <name>'));
+      process.exit(1);
+    }
+
+    console.log(chalk.cyan(`\n  Starting thinknagent — ${cfg.name || cfg.agentId}`));
+    if (!cfg.agentToken) {
+      console.log(chalk.yellow('  Status: PENDING — waiting for Owner approval\n'));
+    }
+
+    const agent = new Agent();
+    agent.start();
+  });
+
+// ── status ────────────────────────────────────────────────────────────────────
+program
+  .command('status')
+  .description('Show current agent config and registration status')
+  .action(() => {
+    const cfg = store.read();
+    if (!cfg.serverUrl) {
+      console.log(chalk.gray('Not initialized.'));
+      return;
+    }
+
+    console.log(chalk.cyan('\n  thinknagent status'));
+    console.log(chalk.gray('  ────────────────────────────────'));
+    console.log(`  Name    : ${chalk.white(cfg.name || '—')}`);
+    console.log(`  Server  : ${chalk.white(cfg.serverUrl || '—')}`);
+    console.log(`  Agent ID: ${chalk.white(cfg.agentId || '—')}`);
+    console.log(`  Role    : ${chalk.white(cfg.role || '—')}`);
+    console.log(`  Room    : ${chalk.white(cfg.roomId || '—')}`);
+    console.log(`  Status  : ${cfg.agentToken ? chalk.green('APPROVED') : chalk.yellow('PENDING')}`);
+    console.log(`  GPU     : ${cfg.gpu ? chalk.green('enabled') : chalk.gray('disabled')}`);
+    console.log(`  Logs    : ${(cfg.logs||[]).length ? cfg.logs.join(', ') : chalk.gray('none')}`);
+    console.log(`  Alerts  : ${(cfg.alerts||[]).length} rule(s)`);
+    console.log(chalk.gray('  ────────────────────────────────\n'));
+  });
+
+// ── revoke ────────────────────────────────────────────────────────────────────
+program
+  .command('revoke')
+  .description('Remove all credentials from this server')
+  .action(() => {
+    store.clear();
+    console.log(chalk.yellow('  Credentials cleared. Run `thinknagent init` to re-register.'));
+  });
+
+program.parse(process.argv);

package/install/setup.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# ThinkNCollab Agent — installer
+# Usage: curl -fsSL https://thinkncollab.com/install-agent.sh | bash -s -- --server https://thinkncollab.com --name my-server
+
+set -euo pipefail
+
+SERVER=""
+NAME=""
+GPU=false
+LOGS=""
+SYSTEMD=false
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --server) SERVER="$2"; shift 2 ;;
+    --name)   NAME="$2";   shift 2 ;;
+    --gpu)    GPU=true;    shift   ;;
+    --logs)   LOGS="$2";   shift 2 ;;
+    --systemd) SYSTEMD=true; shift ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+[[ -z "$SERVER" ]] && echo "Error: --server required" && exit 1
+[[ -z "$NAME"   ]] && echo "Error: --name required"   && exit 1
+
+echo ""
+echo "  ThinkNCollab Agent Installer"
+echo "  ──────────────────────────────"
+
+# Check Node.js >= 18
+NODE_VER=$(node --version 2>/dev/null | cut -d. -f1 | tr -d 'v' || echo "0")
+if [[ "$NODE_VER" -lt 18 ]]; then
+  echo "  Error: Node.js 18+ required (found: $(node --version 2>/dev/null || echo 'not found'))"
+  exit 1
+fi
+echo "  Node.js : $(node --version) ✓"
+
+# Install package
+echo "  Installing thinknagent..."
+npm install -g thinknagent --silent
+
+# Init
+GPU_FLAG=""
+$GPU && GPU_FLAG="--gpu"
+LOGS_FLAG=""
+[[ -n "$LOGS" ]] && LOGS_FLAG="--logs $LOGS"
+
+thinknagent init --server "$SERVER" --name "$NAME" $GPU_FLAG $LOGS_FLAG
+
+# Optional systemd setup
+if $SYSTEMD; then
+  echo ""
+  echo "  Setting up systemd service..."
+
+  # Create system user
+  id thinknagent &>/dev/null || useradd --system --no-create-home thinknagent
+
+  # Copy service file
+  AGENT_SERVICE_SRC="$(npm root -g)/thinknagent/install/thinknagent.service"
+  cp "$AGENT_SERVICE_SRC" /etc/systemd/system/thinknagent.service
+
+  systemctl daemon-reload
+  systemctl enable thinknagent
+  systemctl start  thinknagent
+
+  echo "  systemd service: enabled + started ✓"
+  echo "  Logs: journalctl -u thinknagent -f"
+else
+  echo ""
+  echo "  To start now    : thinknagent start"
+  echo "  To run on boot  : Re-run this script with --systemd flag"
+  echo "  Or with pm2     : pm2 start \$(which thinknagent) -- start && pm2 save"
+fi
+
+echo ""
+echo "  ✓ Done. Open ThinkNCollab and approve this agent in your room's DevOps Wall."
+echo ""

package/install/thinknagent.service

@@ -0,0 +1,38 @@
+[Unit]
+Description=ThinkNCollab Agent
+Documentation=https://thinkncollab.com/docs/agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# Run as a dedicated low-privilege user for security
+# Create with: sudo useradd --system --no-create-home thinknagent
+User=thinknagent
+Group=thinknagent
+
+# Point to wherever thinknagent was installed globally
+ExecStart=/usr/bin/node /usr/local/bin/thinknagent start
+
+# Restart policy
+Restart=on-failure
+RestartSec=10
+StartLimitInterval=60
+StartLimitBurst=3
+
+# Hardening — limit what the process can do
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only        # needed to read ~/.thinknagent/config.json
+ReadWritePaths=/root/.thinknagent /home/%u/.thinknagent
+PrivateTmp=true
+
+# Environment
+Environment=NODE_ENV=production
+
+# Logging — journald will capture stdout/stderr
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=thinknagent
+
+[Install]
+WantedBy=multi-user.target

package/lib/agent.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const Connection    = require('./connect');
+const MetricsPoller = require('./metrics');
+const LogWatcher    = require('./logwatcher');
+const AlertEngine   = require('./alerts');
+const ShellBridge   = require('./shell');
+const store         = require('./store');
+
+class Agent {
+  constructor() {
+    const cfg = store.read();
+
+    this.conn    = new Connection({
+      serverUrl:    cfg.serverUrl,
+      onReady:      ({ role, roomId }) => this._onReady(role, roomId),
+      onDisconnect: ({ reason })       => this._onDisconnect(reason),
+      onRoleUpdate: ({ role })         => this._onRoleUpdate(role),
+    });
+
+    this.metrics = new MetricsPoller({
+      connection: this.conn,
+      gpu:        cfg.gpu || false,
+    });
+
+    this.logs    = new LogWatcher({
+      connection: this.conn,
+      logPaths:   cfg.logs || [],
+    });
+
+    this.alerts  = new AlertEngine({
+      connection: this.conn,
+      rules:      cfg.alerts || [],
+    });
+
+    this.shell   = new ShellBridge({ connection: this.conn });
+
+    this._active = false;
+  }
+
+  start() {
+    const cfg = store.read();
+    if (!cfg.serverUrl) {
+      console.error('[agent] No serverUrl configured. Run: thinknagent init');
+      process.exit(1);
+    }
+
+    console.log(`[agent] Connecting to ${cfg.serverUrl}...`);
+    this.conn.connect();
+
+    // Wire metrics → alert engine
+    this.conn.socket.on('agent:metrics_internal', (m) => this.alerts.evaluate(m));
+
+    // Allow server to push updated alert rules at runtime (Owner changed thresholds)
+    this.conn.socket.on('agent:rules_updated', ({ rules }) => {
+      store.set('alerts', rules);
+      this.alerts.reloadRules(rules);
+    });
+
+    // Allow server to push updated log paths at runtime
+    this.conn.socket.on('agent:logs_updated', ({ logs }) => {
+      store.set('logs', logs);
+      this.logs.stop();
+      this.logs = new LogWatcher({ connection: this.conn, logPaths: logs });
+      this.logs.start();
+    });
+
+    // Graceful shutdown
+    process.on('SIGTERM', () => this._shutdown('SIGTERM'));
+    process.on('SIGINT',  () => this._shutdown('SIGINT'));
+  }
+
+  _onReady(role, roomId) {
+    if (this._active) return; // reconnect — already running
+    this._active = true;
+    console.log(`[agent] Active. Role: ${role} | Room: ${roomId}`);
+
+    this.metrics.start();
+    this.logs.start();
+    this.shell.start();
+
+    // Patch metrics poller to also feed alert engine
+    const origEmit = this.conn.emit.bind(this.conn);
+    this.conn.emit = (event, data) => {
+      if (event === 'agent:metrics') this.alerts.evaluate(data);
+      origEmit(event, data);
+    };
+
+    this.conn.emit('agent:ready', {
+      hostname: require('os').hostname(),
+      platform: process.platform,
+      nodeVersion: process.version,
+    });
+  }
+
+  _onDisconnect(reason) {
+    this.shell.killAll();
+    // metrics + logs keep their intervals; socket.io will reconnect automatically
+  }
+
+  _onRoleUpdate({ role }) {
+    // If role was downgraded to 'monitor', kill open shell sessions
+    if (!this.conn.hasRole('shell')) {
+      this.shell.killAll();
+    }
+  }
+
+  _shutdown(signal) {
+    console.log(`[agent] ${signal} received — shutting down`);
+    this.metrics.stop();
+    this.logs.stop();
+    this.shell.killAll();
+    this.conn.socket?.disconnect();
+    process.exit(0);
+  }
+}
+
+module.exports = Agent;

package/lib/alerts.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Alert engine — evaluates threshold rules against live metrics.
+ *
+ * Rule format (stored in ~/.thinknagent/config.json under "alerts"):
+ * [
+ *   { id: "cpu-high",  metric: "cpu.usage",         op: "gt", value: 80,  for: 60,  severity: "warning"  },
+ *   { id: "cpu-crit",  metric: "cpu.usage",         op: "gt", value: 95,  for: 30,  severity: "critical" },
+ *   { id: "mem-high",  metric: "memory.usedPct",    op: "gt", value: 85,  for: 60,  severity: "warning"  },
+ *   { id: "disk-root", metric: "disk./",            op: "gt", value: 90,  for: 0,   severity: "critical" },
+ *   { id: "proc-down", metric: "process.nginx",     op: "eq", value: 0,   for: 0,   severity: "critical" },
+ * ]
+ *
+ * "for" = seconds the condition must persist before firing (0 = fire immediately)
+ */
+
+class AlertEngine {
+  constructor({ connection, rules = [] }) {
+    this.conn  = connection;
+    this.rules = rules;
+
+    // per-rule state: { firstTriggeredAt, fired }
+    this._state = {};
+    for (const r of rules) {
+      this._state[r.id] = { firstTriggeredAt: null, fired: false };
+    }
+  }
+
+  // Called by metrics poller on every tick
+  evaluate(metrics) {
+    const now = Date.now();
+
+    for (const rule of this.rules) {
+      const val = this._extract(metrics, rule.metric);
+      if (val === null) continue;
+
+      const breached = this._check(val, rule.op, rule.value);
+      const state    = this._state[rule.id];
+
+      if (breached) {
+        if (!state.firstTriggeredAt) state.firstTriggeredAt = now;
+
+        const elapsed = (now - state.firstTriggeredAt) / 1000; // seconds
+        if (elapsed >= rule.for && !state.fired) {
+          state.fired = true;
+          this._fire(rule, val);
+        }
+      } else {
+        // Condition cleared
+        if (state.fired) {
+          this._resolve(rule);
+        }
+        state.firstTriggeredAt = null;
+        state.fired = false;
+      }
+    }
+  }
+
+  _fire(rule, currentValue) {
+    console.warn(`[alerts] FIRING: ${rule.id} — ${rule.metric} ${rule.op} ${rule.value} (current: ${currentValue})`);
+    this.conn.emit('agent:alert', {
+      id:       rule.id,
+      metric:   rule.metric,
+      op:       rule.op,
+      threshold: rule.value,
+      current:  currentValue,
+      severity: rule.severity || 'warning',
+      status:   'active',
+      firedAt:  Date.now(),
+    });
+  }
+
+  _resolve(rule) {
+    console.log(`[alerts] RESOLVED: ${rule.id}`);
+    this.conn.emit('agent:alert:resolved', {
+      id:         rule.id,
+      resolvedAt: Date.now(),
+    });
+  }
+
+  // Extract a value from the metrics payload by dot-path
+  // Special case: "disk./" = disk entry with mount "/"
+  // Special case: "process.nginx" = check if process named "nginx" is running
+  _extract(metrics, path) {
+    if (path.startsWith('disk.')) {
+      const mount = path.slice(5); // e.g. "/"
+      const entry = (metrics.disk || []).find(d => d.mount === mount);
+      return entry?.usedPct ?? null;
+    }
+    if (path.startsWith('process.')) {
+      const procName = path.slice(8);
+      const found = (metrics.processes?.top || []).some(p => p.name.includes(procName));
+      return found ? 1 : 0;
+    }
+    // Standard dot-path: "cpu.usage", "memory.usedPct"
+    return path.split('.').reduce((obj, k) => obj?.[k] ?? null, metrics);
+  }
+
+  _check(val, op, threshold) {
+    switch (op) {
+      case 'gt': return val > threshold;
+      case 'gte': return val >= threshold;
+      case 'lt': return val < threshold;
+      case 'lte': return val <= threshold;
+      case 'eq': return val === threshold;
+      case 'neq': return val !== threshold;
+      default: return false;
+    }
+  }
+
+  // Reload rules at runtime (Owner updated alert config)
+  reloadRules(rules) {
+    this.rules = rules;
+    this._state = {};
+    for (const r of rules) {
+      this._state[r.id] = { firstTriggeredAt: null, fired: false };
+    }
+    console.log(`[alerts] Rules reloaded: ${rules.length} rule(s)`);
+  }
+}
+
+module.exports = AlertEngine;

package/lib/connect.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { io }   = require('socket.io-client');
+const store    = require('./store');
+
+const NAMESPACE = '/devops';
+const RECONNECT_DELAY = 5000;
+
+/**
+ * Option B auth flow:
+ * 1. Agent has no token yet → sends { agentId, name, hostname } to server
+ * 2. Server creates a PENDING agent entry, notifies Owner in room
+ * 3. Owner approves in browser → server sends back a signed agentToken
+ * 4. Agent stores token in ~/.thinknagent/config.json (mode 600)
+ * 5. All future connections: agent sends { agentId, agentToken } → server verifies → ACTIVE
+ */
+
+class Connection {
+  constructor({ serverUrl, onReady, onDisconnect, onRoleUpdate }) {
+    this.serverUrl   = serverUrl;
+    this.onReady     = onReady;       // called when agent is ACTIVE and authed
+    this.onDisconnect = onDisconnect;
+    this.onRoleUpdate = onRoleUpdate; // called if Owner changes agent permissions
+    this.socket      = null;
+    this.agentId     = store.get('agentId');
+    this.agentToken  = store.get('agentToken');
+    this.role        = store.get('role') || 'monitor'; // monitor | shell | admin
+  }
+
+  connect() {
+    const cfg = store.read();
+
+    this.socket = io(`${this.serverUrl}${NAMESPACE}`, {
+      reconnection:        true,
+      reconnectionDelay:   RECONNECT_DELAY,
+      reconnectionAttempts: Infinity,
+      auth: {
+        agentId:    cfg.agentId,
+        agentToken: cfg.agentToken || null,   // null = first time / pending
+        name:       cfg.name,
+        hostname:   require('os').hostname(),
+        version:    require('../package.json').version,
+      }
+    });
+
+    this._bind();
+    return this.socket;
+  }
+
+  _bind() {
+    const s = this.socket;
+
+    // ── Registration flow (Option B) ─────────────────────────────────────────
+
+    // Server says: "I got your registration, waiting for Owner approval"
+    s.on('agent:pending', ({ agentId }) => {
+      store.set('agentId', agentId);
+      this.agentId = agentId;
+      console.log(`[thinknagent] Registered as ${agentId} — waiting for Owner approval in ThinkNCollab...`);
+    });
+
+    // Server says: "Owner approved, here is your token + assigned role"
+    s.on('agent:approved', ({ agentToken, role, roomId }) => {
+      store.set('agentToken', agentToken);
+      store.set('agentId',    this.agentId);
+      store.set('role',       role);
+      store.set('roomId',     roomId);
+      this.agentToken = agentToken;
+      this.role       = role;
+      console.log(`[thinknagent] Approved! Role: ${role} | Room: ${roomId}`);
+      this.onReady?.({ role, roomId });
+    });
+
+    // Server says: "Owner rejected this agent"
+    s.on('agent:rejected', ({ reason }) => {
+      console.error(`[thinknagent] Registration rejected: ${reason}`);
+      store.clear();
+      process.exit(1);
+    });
+
+    // Already approved on previous run — server confirms active session
+    s.on('agent:active', ({ role, roomId }) => {
+      this.role = role;
+      console.log(`[thinknagent] Reconnected. Role: ${role} | Room: ${roomId}`);
+      this.onReady?.({ role, roomId });
+    });
+
+    // Owner changed this agent's role at runtime
+    s.on('agent:role_updated', ({ role }) => {
+      store.set('role', role);
+      this.role = role;
+      console.log(`[thinknagent] Role updated to: ${role}`);
+      this.onRoleUpdate?.({ role });
+    });
+
+    // Owner revoked this agent
+    s.on('agent:revoked', () => {
+      console.warn('[thinknagent] Agent revoked by Owner. Clearing credentials.');
+      store.clear();
+      process.exit(0);
+    });
+
+    s.on('connect_error', (err) => {
+      console.error(`[thinknagent] Connection error: ${err.message}`);
+    });
+
+    s.on('disconnect', (reason) => {
+      console.warn(`[thinknagent] Disconnected: ${reason}`);
+      this.onDisconnect?.({ reason });
+    });
+  }
+
+  // Emit helper — checks role before sending sensitive data
+  emit(event, data) {
+    if (!this.socket?.connected) return;
+    this.socket.emit(event, data);
+  }
+
+  // Role gate helper — called by shell.js before opening PTY
+  hasRole(required) {
+    const hierarchy = { monitor: 0, shell: 1, admin: 2 };
+    return (hierarchy[this.role] ?? -1) >= (hierarchy[required] ?? 99);
+  }
+
+  get connected() {
+    return this.socket?.connected ?? false;
+  }
+}
+
+module.exports = Connection;

package/lib/logwatcher.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs      = require('fs');
+const path    = require('path');
+const { EventEmitter } = require('events');
+
+const BUFFER_LINES = 100;   // lines to send on initial connect
+const CHUNK_DELAY  = 50;    // ms debounce before flushing new lines
+
+class LogWatcher extends EventEmitter {
+  constructor({ connection, logPaths = [] }) {
+    super();
+    this.conn     = connection;
+    this.logPaths = logPaths;
+    this._watchers = new Map(); // path → { fd, size, timer }
+  }
+
+  start() {
+    if (!this.logPaths.length) {
+      console.log('[logs] No log paths configured — skipping');
+      return;
+    }
+    for (const p of this.logPaths) {
+      this._watch(p);
+    }
+    console.log(`[logs] Watching ${this.logPaths.length} file(s)`);
+  }
+
+  stop() {
+    for (const [p, w] of this._watchers) {
+      try { fs.unwatchFile(p); } catch {}
+      if (w.timer) clearTimeout(w.timer);
+    }
+    this._watchers.clear();
+  }
+
+  _watch(filePath) {
+    const absPath = path.resolve(filePath);
+
+    if (!fs.existsSync(absPath)) {
+      console.warn(`[logs] File not found: ${absPath} — will retry when it appears`);
+      // retry every 10s in case log file is created later
+      setTimeout(() => this._watch(filePath), 10000);
+      return;
+    }
+
+    const stat = fs.statSync(absPath);
+    const state = {
+      size:  stat.size,
+      timer: null,
+      lines: [],
+    };
+
+    // Send last BUFFER_LINES lines on startup
+    this._sendTail(absPath);
+
+    fs.watchFile(absPath, { interval: 500 }, (curr, prev) => {
+      if (curr.size < prev.size) {
+        // Log rotated — reset position
+        state.size = 0;
+      }
+      if (curr.size === prev.size) return;
+
+      const newBytes = curr.size - state.size;
+      if (newBytes <= 0) return;
+
+      const buf = Buffer.alloc(newBytes);
+      const fd  = fs.openSync(absPath, 'r');
+      fs.readSync(fd, buf, 0, newBytes, state.size);
+      fs.closeSync(fd);
+      state.size = curr.size;
+
+      const newLines = buf.toString('utf8').split('\n').filter(Boolean);
+      state.lines.push(...newLines);
+
+      // debounce — batch lines before emit
+      clearTimeout(state.timer);
+      state.timer = setTimeout(() => {
+        const toSend = state.lines.splice(0);
+        if (toSend.length) {
+          this.conn.emit('agent:logs', {
+            file:  absPath,
+            lines: toSend.map(l => ({ ts: Date.now(), text: l })),
+          });
+        }
+      }, CHUNK_DELAY);
+    });
+
+    this._watchers.set(absPath, state);
+  }
+
+  _sendTail(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines   = content.split('\n').filter(Boolean).slice(-BUFFER_LINES);
+      if (lines.length) {
+        this.conn.emit('agent:logs:tail', {
+          file:  filePath,
+          lines: lines.map(l => ({ ts: null, text: l })), // historical = no ts
+        });
+      }
+    } catch (err) {
+      console.error(`[logs] Failed to read tail for ${filePath}:`, err.message);
+    }
+  }
+}
+
+module.exports = LogWatcher;

package/lib/metrics.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const si = require('systeminformation');
+
+const POLL_INTERVAL = 5000; // ms
+
+class MetricsPoller {
+  constructor({ connection, gpu = false }) {
+    this.conn     = connection;
+    this.gpu      = gpu;
+    this._timer   = null;
+    this._history = []; // last 60 data points (5 min rolling)
+  }
+
+  start() {
+    this._poll(); // immediate first poll
+    this._timer = setInterval(() => this._poll(), POLL_INTERVAL);
+    console.log('[metrics] Poller started');
+  }
+
+  stop() {
+    if (this._timer) clearInterval(this._timer);
+    console.log('[metrics] Poller stopped');
+  }
+
+  async _poll() {
+    try {
+      const [cpu, mem, disk, net, load, procs] = await Promise.all([
+        si.currentLoad(),
+        si.mem(),
+        si.fsSize(),
+        si.networkStats(),
+        si.currentLoad(),       // for load average
+        si.processes(),
+      ]);
+
+      const payload = {
+        ts: Date.now(),
+        cpu: {
+          usage:    parseFloat(cpu.currentLoad.toFixed(1)),
+          cores:    cpu.cpus?.length ?? 0,
+          loadAvg:  load.avgLoad ?? 0,
+        },
+        memory: {
+          total:    mem.total,
+          used:     mem.used,
+          free:     mem.free,
+          usedPct:  parseFloat(((mem.used / mem.total) * 100).toFixed(1)),
+        },
+        disk: disk.map(d => ({
+          fs:       d.fs,
+          mount:    d.mount,
+          size:     d.size,
+          used:     d.used,
+          usedPct:  parseFloat(d.use?.toFixed(1) ?? 0),
+        })),
+        network: net.map(n => ({
+          iface:    n.iface,
+          rxSec:    n.rx_sec ?? 0,
+          txSec:    n.tx_sec ?? 0,
+        })),
+        processes: {
+          total:  procs.all,
+          running: procs.running,
+          // top 5 by CPU
+          top: (procs.list || [])
+            .sort((a, b) => b.pcpu - a.pcpu)
+            .slice(0, 5)
+            .map(p => ({ pid: p.pid, name: p.name, cpu: p.pcpu, mem: p.pmem })),
+        },
+      };
+
+      // optional GPU
+      if (this.gpu) {
+        try {
+          const gpuData = await si.graphics();
+          payload.gpu = gpuData.controllers?.map(g => ({
+            model:      g.model,
+            utilizationGpu: g.utilizationGpu ?? null,
+            memUsed:    g.memoryUsed ?? null,
+            memTotal:   g.memoryTotal ?? null,
+            tempC:      g.temperatureGpu ?? null,
+          }));
+        } catch {
+          // nvidia-smi not available — silently skip
+        }
+      }
+
+      // rolling history (keep last 60 points)
+      this._history.push({ ts: payload.ts, cpu: payload.cpu.usage, mem: payload.memory.usedPct });
+      if (this._history.length > 60) this._history.shift();
+
+      payload.history = this._history;
+
+      this.conn.emit('agent:metrics', payload);
+    } catch (err) {
+      console.error('[metrics] Poll error:', err.message);
+    }
+  }
+}
+
+module.exports = MetricsPoller;

package/lib/shell.js

@@ -0,0 +1,104 @@
+'use strict';
+
+let pty;
+try {
+  pty = require('node-pty');
+} catch {
+  pty = null; // node-pty is optional — shell feature disabled if not installed
+}
+
+/**
+ * Shell bridge — opens a PTY session on this server and relays I/O
+ * bidirectionally over Socket.IO to the DevOps Wall xterm.js terminal.
+ *
+ * Role gate: connection.hasRole('shell') must be true.
+ * If the agent role is 'monitor' only, all shell:open events are rejected.
+ */
+
+class ShellBridge {
+  constructor({ connection }) {
+    this.conn     = connection;
+    this._sessions = new Map(); // sessionId → ptyProcess
+  }
+
+  start() {
+    if (!pty) {
+      console.warn('[shell] node-pty not installed — shell feature disabled');
+      return;
+    }
+
+    const s = this.conn.socket;
+
+    // Browser requests a new shell session
+    s.on('shell:open', ({ sessionId, cols = 80, rows = 24 }) => {
+      if (!this.conn.hasRole('shell')) {
+        s.emit('shell:error', { sessionId, reason: 'Insufficient role — shell access not granted for this agent' });
+        return;
+      }
+      if (this._sessions.has(sessionId)) return; // already open
+
+      const proc = pty.spawn(process.env.SHELL || '/bin/bash', [], {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd:  process.env.HOME || '/',
+        env:  {
+          ...process.env,
+          TERM: 'xterm-256color',
+          THINKNCOLLAB_AGENT: '1',       // agent can inject this env so shell scripts know
+        },
+      });
+
+      proc.onData(data => {
+        s.emit('shell:data', { sessionId, data });
+      });
+
+      proc.onExit(({ exitCode }) => {
+        s.emit('shell:exit', { sessionId, exitCode });
+        this._sessions.delete(sessionId);
+        console.log(`[shell] Session ${sessionId} exited (code ${exitCode})`);
+      });
+
+      this._sessions.set(sessionId, proc);
+      s.emit('shell:opened', { sessionId });
+      console.log(`[shell] Session ${sessionId} opened (${cols}x${rows})`);
+    });
+
+    // Browser → server → agent: user typed something
+    s.on('shell:input', ({ sessionId, data }) => {
+      const proc = this._sessions.get(sessionId);
+      if (!proc) return;
+      proc.write(data);
+    });
+
+    // Browser resized terminal
+    s.on('shell:resize', ({ sessionId, cols, rows }) => {
+      const proc = this._sessions.get(sessionId);
+      if (!proc) return;
+      proc.resize(cols, rows);
+    });
+
+    // Browser closed terminal tab
+    s.on('shell:close', ({ sessionId }) => {
+      this._killSession(sessionId);
+    });
+
+    console.log('[shell] Bridge ready');
+  }
+
+  _killSession(sessionId) {
+    const proc = this._sessions.get(sessionId);
+    if (proc) {
+      try { proc.kill(); } catch {}
+      this._sessions.delete(sessionId);
+      console.log(`[shell] Session ${sessionId} killed`);
+    }
+  }
+
+  // Kill all sessions on disconnect
+  killAll() {
+    for (const [id] of this._sessions) this._killSession(id);
+  }
+}
+
+module.exports = ShellBridge;

package/lib/store.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const CONFIG_DIR  = path.join(os.homedir(), '.thinknagent');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const LOG_FILE    = path.join(CONFIG_DIR, 'agent.log');
+
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 }); // owner-only
+  }
+}
+
+function read() {
+  ensureDir();
+  if (!fs.existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function write(data) {
+  ensureDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), { mode: 0o600 }); // owner read/write only
+}
+
+function get(key) {
+  return read()[key];
+}
+
+function set(key, value) {
+  const cfg = read();
+  cfg[key] = value;
+  write(cfg);
+}
+
+function clear() {
+  if (fs.existsSync(CONFIG_FILE)) fs.unlinkSync(CONFIG_FILE);
+}
+
+module.exports = { CONFIG_DIR, CONFIG_FILE, LOG_FILE, read, write, get, set, clear };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "thinknagent",
+  "version": "0.1.0",
+  "description": "ThinkNCollab server agent — metrics, logs, alerts, shell bridge",
+  "main": "lib/agent.js",
+  "bin": {
+    "thinknagent": "./bin/thinknagent.js"
+  },
+  "scripts": {
+    "start": "node bin/thinknagent.js start",
+    "dev": "node bin/thinknagent.js start --dev"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.7.5",
+    "node-pty": "^1.0.0",
+    "systeminformation": "^5.22.7",
+    "chokidar": "^3.6.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "conf": "^10.2.0",
+    "ora": "^5.4.1",
+    "uuid": "^10.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["thinkncollab", "devops", "monitoring", "agent"],
+  "license": "MIT"
+}