osai-agent 4.0.0

package/src/safety/check.js

@@ -0,0 +1,210 @@
+// =============================================================================
+// OS AI Agent — Safety Check System (v4.0 — Coding Mode aware)
+// =============================================================================
+// Four-tier safety classification: READ, WRITE, DANGEROUS, ASK
+// In CODING mode, WRITE tools auto-approved with --no-confirm.
+// =============================================================================
+
+const TIER = {
+  READ: 'READ',
+  WRITE: 'WRITE',
+  DANGEROUS: 'DANGEROUS',
+  ASK: 'ASK',
+};
+
+const READ_PATTERNS = [
+  /^show\s+/i, /^display\s+/i, /^get\s+/i, /^list\s+/i,
+  /^ls\s/i, /^cat\s/i, /^grep\s/i, /^ping\s/i,
+  /^traceroute\s/i, /^nslookup\s/i, /^dig\s/i, /^whois\s/i,
+  /^ip\s+route\s/i, /^ip\s+addr\s/i, /^ifconfig\s/i,
+  /^netstat\s/i, /^ss\s/i,
+  /^systemctl\s+status\s/i, /^systemctl\s+is-active\s/i, /^systemctl\s+list/i,
+  /^docker\s+ps/i, /^docker\s+inspect/i, /^docker\s+logs/i,
+  /^kubectl\s+get/i, /^kubectl\s+describe/i, /^kubectl\s+logs/i,
+  /^top\s/i, /^htop\s/i, /^ps\s/i, /^df\s/i, /^free\s/i,
+  /^uname\s/i, /^hostname\s/i, /^whoami\s/i, /^date\s/i, /^uptime\s/i,
+  /^version\s/i, /^running-config/i, /^startup-config/i,
+  /^pwd$/i, /^echo\s/i, /^head\s/i, /^tail\s/i, /^wc\s/i,
+  /^file\s/i, /^stat\s/i, /^du\s/i, /^lsof\s/i,
+  /^ipconfig/i, /^systeminfo/i, /^tasklist/i, /^wmic\s/i,
+  /^Get-Process/i, /^Get-Service/i, /^Get-ChildItem/i, /^Get-Content/i,
+  /^Get-NetAdapter/i, /^Get-NetIPAddress/i, /^Get-NetRoute/i,
+  /^Get-EventLog/i, /^Get-WmiObject/i, /^Get-CimInstance/i,
+  /^Get-Disk/i, /^Get-Volume/i, /^Get-ComputerInfo/i,
+  /^Test-Connection/i, /^Test-NetConnection/i, /^Resolve-DnsName/i,
+  /^dir\b/i, /^type\s/i, /^where\s/i, /^findstr\s/i,
+  /^chcp/i, /^ver$/i, /^set$/i, /^driverquery/i, /^qwinsta/i, /^quser/i,
+  /^which\s/i, /^env\b/i, /^printenv/i, /^npm\s+list/i, /^npm\s+ls/i,
+  /^pip\s+list/i, /^pip\s+show/i, /^node\s+-v/i, /^node\s+--version/i,
+  /^python\s+-[Vc]/i, /^python3\s+-[Vc]/i, /^git\s+status/i, /^git\s+log/i,
+  /^git\s+diff/i, /^git\s+branch/i, /^git\s+remote/i, /^git\s+show/i,
+];
+
+const WRITE_PATTERNS = [
+  /^configure\s+terminal/i, /^conf\s+t/i, /^interface\s+/i, /^vlan\s+/i,
+  /^router\s+/i, /^access-list\s+/i, /^nat\s+/i, /^route\s+/i,
+  /^ip\s+route\s+add/i, /^ip\s+route\s+change/i, /^ip\s+route\s+replace/i,
+  /^systemctl\s+start\s/i, /^systemctl\s+stop\s/i, /^systemctl\s+restart\s/i,
+  /^systemctl\s+enable\s/i, /^systemctl\s+disable\s/i,
+  /^service\s+start/i, /^service\s+stop/i, /^service\s+restart/i,
+  /^iptables\s+/i, /^nft\s+/i, /^ufw\s+/i, /^firewall-cmd\s+/i,
+  /^nmcli\s+/i, /^ip\s+link\s+set/i, /^ip\s+addr\s+add/i, /^ip\s+addr\s+del/i,
+  /^echo\s+.*>\s*\//i, /^tee\s+/i, /^sed\s+-i/i, /^awk\s+/i,
+  /^mkdir\s/i, /^touch\s/i, /^chmod\s/i, /^chown\s/i, /^ln\s+-s/i,
+  /^cp\s/i, /^mv\s/i,
+  /^git\s+commit/i, /^git\s+push/i, /^git\s+checkout/i, /^git\s+merge/i,
+  /^git\s+reset/i, /^git\s+rebase/i,
+  /^docker\s+run/i, /^docker\s+exec/i, /^docker\s+build/i,
+  /^docker\s+compose/i, /^docker\s+swarm/i,
+  /^kubectl\s+apply/i, /^kubectl\s+create/i, /^kubectl\s+delete\s+pod/i,
+  /^kubectl\s+delete\s+deployment/i, /^kubectl\s+scale/i, /^kubectl\s+rollout/i,
+  /^write\s+memory/i, /^copy\s+running-config\s+startup-config/i, /^wr\s/i,
+  /^pip\s+install/i, /^npm\s+install/i, /^npm\s+run/i,
+  /^apt(\s+|-get\s+)install/i, /^yum\s+install/i, /^dnf\s+install/i, /^brew\s+install/i,
+  /^New-Item/i, /^Set-Content/i, /^Add-Content/i, /^Out-File/i,
+  /^Set-Service/i, /^Start-Service/i, /^Stop-Service/i, /^Restart-Service/i,
+  /^Enable-NetAdapter/i, /^Disable-NetAdapter/i,
+  /^Set-NetIPAddress/i, /^New-NetIPAddress/i,
+  /^Set-NetFirewallRule/i, /^New-NetFirewallRule/i,
+  /^reg\s+add/i, /^schtasks\s+\/create/i,
+  /^net\s+start/i, /^net\s+stop/i, /^net\s+user/i, /^netsh\s/i,
+  /^sc\s+config/i, /^copy\s/i, /^move\s/i, /^rename\s/i, /^ren\s/i, /^attrib\s/i,
+];
+
+const DANGEROUS_PATTERNS = [
+  /^reload\s/i, /^reboot\s/i, /^shutdown\s/i, /^poweroff\s/i, /^halt\s/i,
+  /^init\s+[06]/i,
+  /^rm\s+-rf\s+\//i, /^rm\s+-rf\s+\/home/i, /^rm\s+-rf\s+\/usr/i,
+  /^rm\s+-rf\s+\/var/i, /^rm\s+-rf\s+\/etc/i, /^rm\s+-rf\s+\/opt/i,
+  /^rm\s+-rf\s+\/srv/i, /^rm\s+-rf\s+\.\//i, /^rm\s+-rf\s+\.\./i,
+  /^dd\s+if=\/dev\/zero/i, /^dd\s+if=\/dev\/urandom/i,
+  />\s*\/dev\/sda/i, />\s*\/dev\/sd[b-z]/i, />\s*\/dev\/nvme/i,
+  />\s*\/dev\/vda/i, />\s*\/dev\/vdb/i,
+  /^mkfs\./i, /^format\s+c:/i, /^del\s+\/[fq]/i, /^erase\s+/i, /^delete\s+/i,
+  /^no\s+ip\s+route/i, /^no\s+interface/i, /^no\s+vlan/i,
+  /^no\s+router/i, /^no\s+access-list/i, /^no\s+nat/i,
+  /^default\s+interface/i, /^default\s+vlan/i,
+  /^clear\s+arp-cache/i, /^clear\s+ip\s+route/i,
+  /^clear\s+mac\s+address-table/i, /^clear\s+spanning-tree/i,
+  /^clear\s+vlan/i, /^clear\s+interface/i,
+  /:\(\)\{\s*:\|:&\s*};:/i,
+  /^kill\s+-9\s+-1/i, /^killall\s+/i, /^pkill\s+-9/i,
+  /^systemctl\s+isolate/i, /^systemctl\s+poweroff/i,
+  /^systemctl\s+reboot/i, /^systemctl\s+halt/i,
+  /^docker\s+rm\s+-f/i, /^docker\s+rmi\s+-f/i, /^docker\s+system\s+prune/i,
+  /^kubectl\s+delete\s+all/i, /^kubectl\s+delete\s+namespace/i,
+  /^kubectl\s+drain/i, /^kubectl\s+cordon/i,
+  /\bnc\s+-[elp]/i, /\/dev\/tcp\//i,
+  /python\s+-c\s+.*import\s+socket/i, /perl\s+-e\s+.*socket/i,
+  /ruby\s+-e\s+.*socket/i,
+  /powershell.*-enc/i, /powershell.*-w\s+hidden/i,
+  /iex\s*\(\s*new-object/i, /invoke-expression/i,
+  /curl\s+.*\|\s*(ba)?sh/i, /wget\s+.*\|\s*(ba)?sh/i,
+  /certutil.*-urlcache.*-f/i, /bitsadmin.*\/transfer/i, /certutil.*-decode/i,
+];
+
+const ASK_PATTERNS = [
+  /\?$/, /^help\s/i, /^man\s/i, /^--help/i, /^-h$/, /^--usage/i,
+  /^what\s+is\s/i, /^how\s+to\s/i, /^explain\s/i, /^describe\s/i,
+  /^why\s/i, /^when\s/i, /^which\s/i, /^where\s/i,
+  /^list\s+all\s/i, /^show\s+all\s/i, /^get\s+all\s/i,
+];
+
+/** Tools that are always READ-safe (no confirmation needed) */
+const FILE_READ_TOOLS = ['READ_FILE', 'LIST_DIR', 'SEARCH_FILE', 'TREE_VIEW', 'FILE_INFO', 'FETCH_URL', 'WEB_SEARCH', 'TODO_LIST', 'BROWSE', 'BROWSE_SEARCH', 'BROWSE_EXTRACT', 'SKILL_LIST', 'LOAD_SKILL'];
+const SKILL_WRITE_TOOLS = ['CREATE_SKILL'];
+
+/** Tools that are safe WRITE operations in coding mode */
+const CODING_SAFE_TOOLS = ['WRITE_FILE', 'EDIT_FILE', 'APPEND_FILE', 'CREATE_DIR', 'MOVE_FILE', 'COPY_FILE', 'RUN_SCRIPT', 'TODO_ADD', 'TODO_COMPLETE', 'TODO_UPDATE', 'TODO_CLEAR', 'GLOB', 'GREP', 'DIAG_POST_EDIT', 'ASK_USER', 'PLAN_MODE', 'CREATE_SKILL', 'TASK'];
+
+export const checkSafety = (command, mode = 'GENERAL') => {
+  const toolName = command.tool || '';
+  const cmdStr = typeof command === 'string' ? command : (typeof command?.cmd === 'string' ? command.cmd : '');
+  const type = command.type;
+
+  // File read/info tools are always safe
+  if (FILE_READ_TOOLS.includes(toolName)) {
+    return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Safe read operation' };
+  }
+
+  if (toolName === 'SKILL_LIST' || toolName === 'LOAD_SKILL') {
+    return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Safe skill operation' };
+  }
+
+  if (SKILL_WRITE_TOOLS.includes(toolName)) {
+    return { tier: TIER.WRITE, requiresConfirmation: mode !== 'CODING', isDangerous: false, message: 'Skill creation' };
+  }
+
+  if (toolName === 'TASK') {
+    return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Subagent exploration (read-only, max 1 concurrent)' };
+  }
+
+  // MCP tools default to ASK (user decides per-call)
+  if (toolName === 'MCP_TOOL') {
+    return { tier: TIER.ASK, requiresConfirmation: false, isDangerous: false, message: 'MCP external tool — user awareness recommended' };
+  }
+
+  // Todo management tools are always safe
+  if (toolName.startsWith('TODO_')) {
+    return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Todo management operation' };
+  }
+
+  // DELETE_FILE is always WRITE
+  if (toolName === 'DELETE_FILE') {
+    return { tier: TIER.WRITE, requiresConfirmation: mode !== 'CODING', isDangerous: false, message: 'File deletion operation' };
+  }
+
+  // GIT tool: classify by operation type
+  if (toolName === 'GIT') {
+    const op = String(command.op || '').toLowerCase().trim();
+    const READ_GIT_OPS = ['status', 'log', 'diff', 'branch', 'remote', 'show', 'ls-files', 'ls-tree', 'describe'];
+    const DANGEROUS_GIT_OPS = ['push --force', 'reset --hard', 'clean -fd', 'push -f', 'checkout --force'];
+    if (READ_GIT_OPS.some(r => op === r || op.startsWith(r + ' '))) {
+      return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Git read operation' };
+    }
+    if (DANGEROUS_GIT_OPS.some(d => op.startsWith(d))) {
+      return { tier: TIER.DANGEROUS, requiresConfirmation: true, isDangerous: true, message: 'DANGEROUS git operation — user confirmation required' };
+    }
+    return { tier: TIER.WRITE, requiresConfirmation: true, isDangerous: false, message: 'Git write operation — confirmation required' };
+  }
+
+  // Coding mode tools auto-approved in CODING mode
+  if (mode === 'CODING' && CODING_SAFE_TOOLS.includes(toolName)) {
+    return { tier: TIER.WRITE, requiresConfirmation: false, isDangerous: false, message: 'Coding mode write operation (auto-approved)' };
+  }
+
+  if (type === TIER.READ) return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Safe read operation' };
+  if (type === TIER.WRITE) return { tier: TIER.WRITE, requiresConfirmation: true, isDangerous: false, message: 'Write operation requires confirmation' };
+  if (type === TIER.DANGEROUS) return { tier: TIER.DANGEROUS, requiresConfirmation: true, isDangerous: true, message: 'DANGEROUS operation' };
+  if (type === TIER.ASK) return { tier: TIER.ASK, requiresConfirmation: false, isDangerous: false, message: 'Information request' };
+
+  const lowerCmd = cmdStr.toLowerCase();
+  for (const pattern of DANGEROUS_PATTERNS) {
+    if (pattern.test(lowerCmd)) return { tier: TIER.DANGEROUS, requiresConfirmation: true, isDangerous: true, message: 'DANGEROUS operation detected' };
+  }
+  for (const pattern of WRITE_PATTERNS) {
+    if (pattern.test(lowerCmd)) {
+      if (mode === 'CODING') return { tier: TIER.WRITE, requiresConfirmation: false, isDangerous: false, message: 'Write operation (coding mode auto-approved)' };
+      return { tier: TIER.WRITE, requiresConfirmation: true, isDangerous: false, message: 'Write operation requires confirmation' };
+    }
+  }
+  for (const pattern of ASK_PATTERNS) {
+    if (pattern.test(lowerCmd)) return { tier: TIER.ASK, requiresConfirmation: false, isDangerous: false, message: 'Information request' };
+  }
+  for (const pattern of READ_PATTERNS) {
+    if (pattern.test(lowerCmd)) return { tier: TIER.READ, requiresConfirmation: false, isDangerous: false, message: 'Safe read operation' };
+  }
+  return { tier: TIER.WRITE, requiresConfirmation: mode !== 'CODING', isDangerous: false, message: 'Unknown operation — requires confirmation' };
+};
+
+export const TIER_LEVELS = TIER;
+
+export const getTierColor = (tier) => {
+  switch (tier) {
+    case TIER.READ: return 'blue';
+    case TIER.WRITE: return 'yellow';
+    case TIER.DANGEROUS: return 'red';
+    case TIER.ASK: return 'green';
+    default: return 'gray';
+  }
+};

package/src/services/crypto.js

@@ -0,0 +1,78 @@
+import crypto from 'crypto';
+import { logger } from '../utils/logger.js';
+
+export const deriveKey = (machineId) => {
+  const secret = process.env.AES_SECRET;
+  if (secret && typeof secret === 'string' && secret.length > 0) {
+    return crypto.createHash('sha256').update(secret).digest();
+  }
+  if (!machineId || typeof machineId !== 'string' || machineId.length === 0) {
+    throw new Error('Cannot derive encryption key: no valid machine ID or AES_SECRET provided');
+  }
+  return crypto.createHash('sha256').update(machineId).digest();
+};
+
+export const encrypt = (text, key) => {
+  if (!text || typeof text !== 'string') {
+    throw new Error('Cannot encrypt: invalid text (expected non-empty string)');
+  }
+  if (!key || !Buffer.isBuffer(key) || key.length !== 32) {
+    throw new Error('Invalid encryption key: must be 32-byte Buffer');
+  }
+
+  try {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    let encrypted = cipher.update(text, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    const authTag = cipher.getAuthTag();
+    return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
+  } catch (err) {
+    logger.error('Encryption failed', { error: err.message });
+    throw new Error(`Encryption failed: ${err.message}`);
+  }
+};
+
+export const decrypt = (str, key) => {
+  if (!str || typeof str !== 'string') {
+    throw new Error('Cannot decrypt: invalid input (expected non-empty string)');
+  }
+  if (!key || !Buffer.isBuffer(key) || key.length !== 32) {
+    throw new Error('Invalid decryption key: must be 32-byte Buffer');
+  }
+
+  const parts = str.split(':');
+  if (parts.length !== 3) {
+    throw new Error('Cannot decrypt: invalid format (expected iv:authTag:encrypted)');
+  }
+
+  const [ivHex, authTagHex, encrypted] = parts;
+
+  if (!ivHex || !authTagHex || !encrypted) {
+    throw new Error('Cannot decrypt: missing required components (iv, authTag, or encrypted data)');
+  }
+
+  try {
+    const iv = Buffer.from(ivHex, 'hex');
+    const authTag = Buffer.from(authTagHex, 'hex');
+
+    if (iv.length !== 12) {
+      throw new Error('Invalid IV length (expected 12 bytes)');
+    }
+    if (authTag.length !== 16) {
+      throw new Error('Invalid auth tag length (expected 16 bytes)');
+    }
+
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+  } catch (err) {
+    logger.error('Decryption failed', { error: err.message });
+    if (err.message.includes('Unsupported state')) {
+      throw new Error('Decryption failed: authentication tag mismatch (possible data corruption or key mismatch)');
+    }
+    throw new Error(`Decryption failed: ${err.message}`);
+  }
+};

package/src/services/executor.js

@@ -0,0 +1,68 @@
+// =============================================================================
+// OS AI Agent — Command Executor
+// =============================================================================
+// Unified command executor that dispatches to local or SSH based on device.
+// Acts as a bridge between the agent loop and the tool system.
+// =============================================================================
+import { exec } from 'child_process';
+import { connectSSH, execSSH, closeSSH } from './ssh.js';
+import { DEFAULTS } from '../utils/constants.js';
+import { logger } from '../utils/logger.js';
+
+const COMMAND_TIMEOUT = DEFAULTS.COMMAND_TIMEOUT;
+
+const withTimeout = (promise, ms) => {
+  let timer;
+  return Promise.race([
+    promise.then(result => { clearTimeout(timer); return result; }),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error('Timeout')), ms);
+    }),
+  ]);
+};
+
+/**
+ * Execute a command either locally or on a remote device via SSH.
+ * Automatically detects whether the target is local or remote.
+ */
+export const executeCommand = async ({ cmd, cmdType, device, authDecrypted }) => {
+  const isLocal = !device?.ip || device.ip === 'localhost' || device.ip === '127.0.0.1' || device?.type === 'Local';
+
+  if (isLocal) {
+    logger.debug('Executing local command', { cmd: cmd.slice(0, 100) });
+    return withTimeout(
+      new Promise((resolve) => {
+        exec(cmd, (error, stdout, stderr) => {
+          if (error) {
+            resolve({ output: stderr || error.message, status: 'error' });
+          } else {
+            resolve({ output: stdout + stderr, status: 'success' });
+          }
+        });
+      }),
+      COMMAND_TIMEOUT
+    );
+  }
+
+  try {
+    logger.debug('Executing SSH command', { host: device.ip, cmd: cmd.slice(0, 100) });
+    let conn = await connectSSH(
+      {
+        host: device.ip,
+        port: device.port || 22,
+        username: authDecrypted.username,
+        password: authDecrypted.password,
+        privateKey: authDecrypted.privateKey || null,
+      },
+      device.type
+    );
+    return await withTimeout(execSSH(conn, cmd), COMMAND_TIMEOUT);
+  } catch (err) {
+    logger.error('SSH command execution failed', { host: device.ip, error: err.message });
+    return { output: err.message, status: 'error' };
+  }
+};
+
+export const closeConnection = (device) => {
+  if (device?.ip) closeSSH(device.ip);
+};

package/src/services/history.js

@@ -0,0 +1,58 @@
+import { DEFAULTS } from '../utils/constants.js';
+
+export class CommandHistory {
+  constructor(maxSize = DEFAULTS.MAX_COMMAND_HISTORY) {
+    this.maxSize = maxSize;
+    this.commands = [];
+    this.currentIndex = -1;
+    this.partialInput = '';
+  }
+
+  add(command) {
+    if (!command || !command.trim()) return;
+    const trimmed = command.trim();
+    // Skip duplicates of the most recent command
+    if (this.commands.length > 0 && this.commands[this.commands.length - 1] === trimmed) return;
+    this.commands.push(trimmed);
+    if (this.commands.length > this.maxSize) this.commands.shift();
+    this.currentIndex = -1;
+    this.partialInput = '';
+  }
+
+  getPrevious(partialInput) {
+    if (this.currentIndex === -1) {
+      this.partialInput = partialInput || '';
+      this.currentIndex = this.commands.length;
+    }
+    if (this.currentIndex > 0) {
+      this.currentIndex--;
+      return this.commands[this.currentIndex];
+    }
+    return this.commands[0] || null;
+  }
+
+  getNext() {
+    if (this.currentIndex === -1) return this.partialInput;
+    if (this.currentIndex < this.commands.length - 1) {
+      this.currentIndex++;
+      return this.commands[this.currentIndex];
+    }
+    this.currentIndex = -1;
+    return this.partialInput;
+  }
+
+  search(prefix) {
+    if (!prefix) return [];
+    const lower = prefix.toLowerCase();
+    return this.commands.filter(cmd => cmd.toLowerCase().includes(lower));
+  }
+
+  clear() {
+    this.commands = [];
+    this.currentIndex = -1;
+    this.partialInput = '';
+  }
+
+  getAll() { return [...this.commands]; }
+  getRecent(count = 10) { return this.commands.slice(-count); }
+}

package/src/services/server-url.js

@@ -0,0 +1,11 @@
+export const DEFAULT_SERVER_URL = 'ws://localhost:3001';
+
+export const toHttpUrl = (serverUrl) => {
+  if (!serverUrl) return null;
+  return serverUrl.replace(/^wss:\/\//, 'https://').replace(/^ws:\/\//, 'http://');
+};
+
+export const toWsUrl = (serverUrl) => {
+  if (!serverUrl) return null;
+  return serverUrl.replace(/^https:\/\//, 'wss://').replace(/^http:\/\//, 'ws://');
+};

package/src/services/session.js

@@ -0,0 +1,194 @@
+// =============================================================================
+// OS AI Agent — Session Manager
+// Supports both LOCAL (JSON file) and CLOUD (MongoDB via server API) storage.
+// =============================================================================
+import fs   from 'fs/promises';
+import { mkdirSync, writeFileSync } from 'fs';
+import path from 'path';
+import os   from 'os';
+import { logger } from '../utils/logger.js';
+
+const SESSIONS_DIR = path.join(os.homedir(), '.osai-agent', 'sessions');
+
+const ensureDir = async () => { await fs.mkdir(SESSIONS_DIR, { recursive: true }); };
+
+const makeId = () => {
+  const now = new Date();
+  const d = `${now.getFullYear()}${String(now.getMonth()+1).padStart(2,'0')}${String(now.getDate()).padStart(2,'0')}`;
+  const t = `${String(now.getHours()).padStart(2,'0')}${String(now.getMinutes()).padStart(2,'0')}`;
+  return `${d}-${t}-${Math.random().toString(36).slice(2,6)}`;
+};
+
+const apiFetch = async (server, token, endpoint, opts = {}) => {
+  const res = await fetch(`${server}${endpoint}`, {
+    ...opts,
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...(opts.headers||{}) },
+    signal: AbortSignal.timeout(8000),
+  });
+  if (!res.ok) throw new Error(`Cloud ${res.status}: ${await res.text()}`);
+  return res.json();
+};
+
+export class SessionManager {
+  constructor({ server = null, token = null } = {}) {
+    this.sessionsDir = SESSIONS_DIR;
+    this.server = server;
+    this.token  = token;
+  }
+
+  generateSessionId() { return makeId(); }
+
+  // ── LOCAL ────────────────────────────────────────────────────────────────
+
+  async saveLocal(sessionId, data) {
+    await ensureDir();
+    const fp = path.join(this.sessionsDir, `${sessionId}.json`);
+    await fs.writeFile(fp, JSON.stringify({ id: sessionId, savedAt: new Date().toISOString(), storage: 'local', ...data }, null, 2), 'utf-8');
+    logger.debug('Session saved locally', { id: sessionId });
+    return fp;
+  }
+
+  saveLocalSync(sessionId, data) {
+    mkdirSync(this.sessionsDir, { recursive: true });
+    const fp = path.join(this.sessionsDir, `${sessionId}.json`);
+    writeFileSync(fp, JSON.stringify({ id: sessionId, savedAt: new Date().toISOString(), storage: 'local', ...data }, null, 2), 'utf-8');
+    logger.debug('Session saved locally (sync)', { id: sessionId });
+    return fp;
+  }
+
+  async loadLocal(sessionId) {
+    try { return JSON.parse(await fs.readFile(path.join(this.sessionsDir, `${sessionId}.json`), 'utf-8')); }
+    catch { return null; }
+  }
+
+  async listLocal() {
+    try {
+      await ensureDir();
+      const files = await fs.readdir(this.sessionsDir);
+      const sessions = [];
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        try {
+          const data = JSON.parse(await fs.readFile(path.join(this.sessionsDir, file), 'utf-8'));
+          sessions.push({
+            id:           data.id,
+            title:        data.title || data.conversationHistory?.find(m => m.role === 'user')?.content?.slice(0, 60) || 'Untitled',
+            savedAt:      data.savedAt,
+            storage:      'local',
+            messageCount: data.conversationHistory?.length || 0,
+            mode:         data.mode || 'LOCAL',
+            os:           data.os   || 'unknown',
+          });
+        } catch { /* skip corrupt */ }
+      }
+      return sessions.sort((a, b) => new Date(b.savedAt) - new Date(a.savedAt));
+    } catch { return []; }
+  }
+
+  async deleteLocal(sessionId) {
+    try { await fs.unlink(path.join(this.sessionsDir, `${sessionId}.json`)); return true; }
+    catch { return false; }
+  }
+
+  // ── CLOUD ────────────────────────────────────────────────────────────────
+
+  async saveCloud(sessionId, data) {
+    if (!this.server || !this.token) throw new Error('Not connected to server');
+    const result = await apiFetch(this.server, this.token, '/conversations', {
+      method: 'POST',
+      body: JSON.stringify({
+        session_id: sessionId,
+        title:      data.title || null,
+        os:         data.os   || 'unknown',
+        mode:       data.mode || 'LOCAL',
+        messages:   data.conversationHistory || [],
+        stats:      data.stats || {},
+      }),
+    });
+    logger.debug('Session saved to cloud', { id: sessionId });
+    return result;
+  }
+
+  async loadCloud(sessionId) {
+    if (!this.server || !this.token) throw new Error('Not connected to server');
+    const conv = await apiFetch(this.server, this.token, `/conversations/${sessionId}`);
+    return {
+      id:                  conv.session_id,
+      savedAt:             conv.updated_at,
+      storage:             'cloud',
+      os:                  conv.os,
+      mode:                conv.mode,
+      conversationHistory: (conv.messages || []).map(m => ({ role: m.role, content: m.content })),
+      stats:               conv.stats || {},
+    };
+  }
+
+  async listCloud(page = 1) {
+    if (!this.server || !this.token) throw new Error('Not connected to server');
+    const data = await apiFetch(this.server, this.token, `/conversations?page=${page}&limit=20`);
+    return (data.conversations || []).map(c => ({
+      id:           c.session_id,
+      title:        c.title || 'Untitled',
+      savedAt:      c.updated_at,
+      storage:      'cloud',
+      messageCount: (c.messages || []).length,
+      mode:         c.mode || 'LOCAL',
+      os:           c.os   || 'unknown',
+    }));
+  }
+
+  async deleteCloud(sessionId) {
+    if (!this.server || !this.token) throw new Error('Not connected to server');
+    return apiFetch(this.server, this.token, `/conversations/${sessionId}`, { method: 'DELETE' });
+  }
+
+  // ── UNIFIED ──────────────────────────────────────────────────────────────
+
+  async listAll() {
+    const [local, cloud] = await Promise.allSettled([
+      this.listLocal(),
+      (this.server && this.token) ? this.listCloud() : Promise.resolve([]),
+    ]);
+    const localList = local.status === 'fulfilled' ? local.value : [];
+    const cloudList = cloud.status === 'fulfilled' ? cloud.value : [];
+    const seen = new Set();
+    const merged = [];
+    for (const s of [...cloudList, ...localList]) {
+      if (!seen.has(s.id)) { seen.add(s.id); merged.push(s); }
+    }
+    return merged.sort((a, b) => new Date(b.savedAt) - new Date(a.savedAt));
+  }
+
+  async load(sessionId) {
+    if (this.server && this.token) {
+      try { return await this.loadCloud(sessionId); } catch {}
+    }
+    return this.loadLocal(sessionId);
+  }
+
+  // Legacy alias
+  async saveSession(sessionId, data, storage = 'local') {
+    if (storage === 'cloud') return this.saveCloud(sessionId, data);
+    return this.saveLocal(sessionId, data);
+  }
+
+  async exportSession(sessionId, format = 'markdown') {
+    const session = await this.load(sessionId);
+    if (!session) return null;
+    if (format === 'json') return JSON.stringify(session, null, 2);
+    const lines = [`# Session ${session.id}`, `Mode: ${session.mode} | OS: ${session.os} | Saved: ${new Date(session.savedAt).toLocaleString()}`, ''];
+    for (const msg of (session.conversationHistory || [])) {
+      lines.push(`**${msg.role}:** ${msg.content}`);
+    }
+    return lines.join('\n');
+  }
+
+  async deleteSession(sessionId) {
+    let deleted = false;
+    if (this.server && this.token) {
+      try { await this.deleteCloud(sessionId); deleted = true; } catch {}
+    }
+    if (!deleted) deleted = await this.deleteLocal(sessionId);
+    return deleted;
+  }
+}