alvin-bot 4.10.0 → 4.12.0

package/dist/services/session-persistence.js

@@ -0,0 +1,194 @@
+/**
+ * Session Persistence Service (v4.11.0)
+ *
+ * The sessions Map in src/services/session.ts is in-memory only. When the bot
+ * restarts (launchctl, watchdog brake, npm install, crash), every user's
+ * Claude SDK session_id, conversation history, language preference, and
+ * tracking counters are wiped. Claude SDK then starts a fresh conversation
+ * on the next user message, behaving like a goldfish.
+ *
+ * This service:
+ * 1. Flushes a sanitized snapshot of getAllSessions() to disk (atomic write).
+ * 2. Loads that snapshot at bot startup and rehydrates the Map.
+ * 3. Coalesces rapid mutations via a debounced timer.
+ *
+ * Persisted fields are intentionally a SUBSET of UserSession — runtime-only
+ * fields like abortController, isProcessing, and messageQueue are excluded.
+ *
+ * History is capped at MAX_PERSISTED_HISTORY (50 entries) per session so the
+ * state file stays small even after months of conversation.
+ */
+import fs from "fs";
+import { dirname } from "path";
+import { SESSIONS_STATE_FILE } from "../paths.js";
+import { getAllSessions, getTelegramWorkspacesMap, } from "./session.js";
+/** History entries to keep in the persisted snapshot (per session). */
+const MAX_PERSISTED_HISTORY = 50;
+/** Debounce window for grouped mutations. */
+const DEBOUNCE_MS = 1500;
+let debounceTimer = null;
+/** Strip runtime-only fields and clip history. */
+function snapshot(session) {
+    return {
+        sessionId: session.sessionId,
+        workingDir: session.workingDir,
+        workspaceName: session.workspaceName,
+        language: session.language,
+        effort: session.effort,
+        voiceReply: session.voiceReply,
+        lastActivity: session.lastActivity,
+        startedAt: session.startedAt,
+        totalCost: session.totalCost,
+        messageCount: session.messageCount,
+        toolUseCount: session.toolUseCount,
+        totalInputTokens: session.totalInputTokens,
+        totalOutputTokens: session.totalOutputTokens,
+        lastSdkHistoryIndex: session.lastSdkHistoryIndex,
+        history: session.history.slice(-MAX_PERSISTED_HISTORY),
+    };
+}
+/** Skip sessions that have never accumulated meaningful state. */
+function isWorthPersisting(session) {
+    return !!(session.sessionId ||
+        session.history.length > 0 ||
+        session.messageCount > 0 ||
+        session.totalCost > 0);
+}
+/**
+ * Atomic flush of all worth-persisting sessions to SESSIONS_STATE_FILE.
+ * Cancels any pending debounced flush — this is the immediate path.
+ */
+export async function flushSessions() {
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+    }
+    try {
+        const all = getAllSessions();
+        const out = {};
+        for (const [key, session] of all) {
+            if (isWorthPersisting(session)) {
+                out[key] = snapshot(session);
+            }
+        }
+        // Ensure the state directory exists
+        fs.mkdirSync(dirname(SESSIONS_STATE_FILE), { recursive: true });
+        // v4.12.0 — Persist Telegram active-workspace map alongside sessions.
+        // Wrapped in a versioned envelope so we can add more state later without
+        // breaking loadPersistedSessions' backwards-compat path for older files.
+        const tgWorkspaces = {};
+        for (const [userId, ws] of getTelegramWorkspacesMap()) {
+            tgWorkspaces[userId] = ws;
+        }
+        const envelope = {
+            version: 2,
+            sessions: out,
+            telegramWorkspaces: tgWorkspaces,
+        };
+        // Atomic write: tmp + rename
+        const tmpFile = `${SESSIONS_STATE_FILE}.tmp`;
+        fs.writeFileSync(tmpFile, JSON.stringify(envelope, null, 2), "utf-8");
+        fs.renameSync(tmpFile, SESSIONS_STATE_FILE);
+    }
+    catch (err) {
+        console.warn("⚠️ session-persistence: flush failed —", err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Schedule a debounced flush. Multiple rapid calls collapse into one.
+ * Use this from any session-mutating code path; the immediate flushSessions()
+ * is reserved for graceful shutdown.
+ */
+export function schedulePersist() {
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        void flushSessions();
+    }, DEBOUNCE_MS);
+}
+/**
+ * Load the persisted sessions snapshot from disk and rehydrate the Map.
+ * Called once at bot startup. Returns the number of sessions restored.
+ */
+export function loadPersistedSessions() {
+    let raw;
+    try {
+        raw = fs.readFileSync(SESSIONS_STATE_FILE, "utf-8");
+    }
+    catch {
+        return 0; // no file = nothing to do
+    }
+    let raw_parsed;
+    try {
+        raw_parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn("⚠️ session-persistence: corrupt sessions.json, starting fresh —", err instanceof Error ? err.message : String(err));
+        return 0;
+    }
+    if (!raw_parsed || typeof raw_parsed !== "object")
+        return 0;
+    // v4.12.0 — Detect envelope format vs legacy v4.11.0 flat format
+    let parsed;
+    let tgWorkspaces = {};
+    if (raw_parsed &&
+        typeof raw_parsed === "object" &&
+        "version" in raw_parsed &&
+        "sessions" in raw_parsed) {
+        const env = raw_parsed;
+        parsed = env.sessions ?? {};
+        tgWorkspaces = env.telegramWorkspaces ?? {};
+    }
+    else {
+        // Legacy flat format (v4.11.0)
+        parsed = raw_parsed;
+    }
+    // Rehydrate Telegram workspace map
+    const tgMap = getTelegramWorkspacesMap();
+    for (const [userId, name] of Object.entries(tgWorkspaces)) {
+        if (typeof name === "string")
+            tgMap.set(userId, name);
+    }
+    // Use the same getAllSessions Map that session.ts exports
+    const all = getAllSessions();
+    let count = 0;
+    for (const [key, persisted] of Object.entries(parsed)) {
+        if (!persisted || typeof persisted !== "object")
+            continue;
+        // Build a UserSession from the persisted shape, filling defaults for any
+        // fields added in newer schema versions.
+        const restored = {
+            sessionId: persisted.sessionId ?? null,
+            workingDir: persisted.workingDir ?? process.cwd(),
+            workspaceName: persisted.workspaceName ?? null,
+            isProcessing: false,
+            abortController: null,
+            lastActivity: persisted.lastActivity ?? Date.now(),
+            startedAt: persisted.startedAt ?? Date.now(),
+            totalCost: persisted.totalCost ?? 0,
+            costByProvider: {},
+            queriesByProvider: {},
+            effort: persisted.effort ?? "medium",
+            voiceReply: persisted.voiceReply ?? false,
+            messageCount: persisted.messageCount ?? 0,
+            toolUseCount: persisted.toolUseCount ?? 0,
+            totalInputTokens: persisted.totalInputTokens ?? 0,
+            totalOutputTokens: persisted.totalOutputTokens ?? 0,
+            lastTurnInputTokens: 0,
+            compactionCount: 0,
+            checkpointHintsInjected: 0,
+            sdkSubTaskCount: 0,
+            history: Array.isArray(persisted.history) ? persisted.history : [],
+            language: persisted.language ?? "en",
+            messageQueue: [],
+            lastSdkHistoryIndex: persisted.lastSdkHistoryIndex ?? -1,
+        };
+        all.set(key, restored);
+        count++;
+    }
+    if (count > 0) {
+        console.log(`🧠 session-persistence: restored ${count} session(s) from disk`);
+    }
+    return count;
+}

package/dist/services/session.js

@@ -2,6 +2,62 @@ import { config } from "../config.js";
 /** Max history entries to keep (to avoid token overflow) */
 const MAX_HISTORY = 100;
 const sessions = new Map();
+// v4.12.0 P1 #3 — Telegram active-workspace map: userId → workspaceName.
+// Separate from the sessions Map because a user's ACTIVE workspace is an
+// index, not a session itself. Persisted via session-persistence snapshots.
+const telegramWorkspaces = new Map();
+/** Get the user's currently active Telegram workspace. null = default. */
+export function getTelegramWorkspace(userId) {
+    return telegramWorkspaces.get(String(userId)) ?? null;
+}
+/** Set the user's currently active Telegram workspace. */
+export function setTelegramWorkspace(userId, name) {
+    const key = String(userId);
+    if (name === null) {
+        telegramWorkspaces.delete(key);
+    }
+    else {
+        telegramWorkspaces.set(key, name);
+    }
+    // Defer persist() until after it's defined below
+    if (_persistHook) {
+        try {
+            _persistHook();
+        }
+        catch { /* ignore */ }
+    }
+}
+/** For session-persistence.ts — expose the raw map for snapshotting. */
+export function getTelegramWorkspacesMap() {
+    return telegramWorkspaces;
+}
+// ── Persistence Hook (v4.11.0) ─────────────────────────────────────
+//
+// session-persistence.ts is wired in via attachPersistHook() at bot startup.
+// We use a callback indirection rather than a direct import to avoid a
+// circular dependency (session-persistence imports getAllSessions from here).
+let _persistHook = null;
+/** Wire a callback that gets invoked on every session mutation. */
+export function attachPersistHook(fn) {
+    _persistHook = fn;
+}
+/** Internal: invoke the persist hook if attached. Never throws. */
+function persist() {
+    if (!_persistHook)
+        return;
+    try {
+        _persistHook();
+    }
+    catch {
+        // never let persistence break session writes
+    }
+}
+/** Public marker for handlers that mutate session fields directly (sessionId,
+ *  language, effort, voiceReply, workingDir) outside of addToHistory/trackProviderUsage.
+ *  Triggers a debounced persist. Safe to call from any code path. */
+export function markSessionDirty(_key) {
+    persist();
+}
 export function buildSessionKey(platform, channelId, userId) {
     switch (config.sessionMode) {
         case "per-channel":
@@ -20,6 +76,7 @@ export function getSession(key) {
         session = {
             sessionId: null,
             workingDir: config.defaultWorkingDir,
+            workspaceName: null,
             isProcessing: false,
             abortController: null,
             lastActivity: Date.now(),
@@ -71,6 +128,7 @@ export function resetSession(key) {
     // Reset budget warning flags so the user gets fresh warnings in the new session.
     session._budgetWarned80 = false;
     session._budgetWarned100 = false;
+    persist();
 }
 /** Track cost, query count, and tokens for a provider. */
 export function trackProviderUsage(key, providerKey, cost, inputTokens, outputTokens) {
@@ -82,6 +140,7 @@ export function trackProviderUsage(key, providerKey, cost, inputTokens, outputTo
         session.totalInputTokens += inputTokens;
     if (outputTokens)
         session.totalOutputTokens += outputTokens;
+    persist();
     // Soft budget warnings — these NEVER block the bot. They exist purely
     // as log signals so the operator (Ali) can notice unusually expensive
     // sessions. Each threshold fires at most once per session (reset on /new).
@@ -164,11 +223,30 @@ export function addToHistory(key, message) {
             session.lastSdkHistoryIndex = Math.max(-1, session.lastSdkHistoryIndex - dropped);
         }
     }
+    persist();
 }
 /** Get all active sessions (for web UI session browser). */
 export function getAllSessions() {
     return sessions;
 }
+/** v4.12.0 — Aggregate session.totalCost by workspaceName across all
+ *  active sessions. Returns an object keyed by workspace name (null →
+ *  "default") with cumulative cost, session count, message count, and
+ *  tool use count. Used by the Web UI's workspace overview. */
+export function getCostByWorkspace() {
+    const out = {};
+    for (const s of sessions.values()) {
+        const name = s.workspaceName ?? "default";
+        if (!out[name]) {
+            out[name] = { totalCost: 0, sessionCount: 0, messageCount: 0, toolUseCount: 0 };
+        }
+        out[name].totalCost += s.totalCost;
+        out[name].sessionCount += 1;
+        out[name].messageCount += s.messageCount;
+        out[name].toolUseCount += s.toolUseCount;
+    }
+    return out;
+}
 /** Kill a user session completely — abort running query, clear history, remove from map. */
 export function killSession(key) {
     const k = String(key);

package/dist/services/workspaces.js

@@ -0,0 +1,247 @@
+/**
+ * Workspace Registry (v4.12.0)
+ *
+ * A workspace represents an isolated "project context" for Alvin. On Slack
+ * each channel maps to a workspace (1:1 by explicit channel ID or by name
+ * match). On Telegram, the user selects a workspace via /workspace.
+ *
+ * Config format: markdown files under ~/.alvin-bot/workspaces/<name>.md
+ * with YAML frontmatter. The markdown body is the persona/system-prompt
+ * override that gets appended to the base Alvin system prompt for queries
+ * in that workspace.
+ *
+ * Example:
+ *
+ *   ---
+ *   purpose: Alev-B consulting website dev
+ *   cwd: ~/Projects/alev-b-website
+ *   emoji: "🏢"
+ *   color: "#6366f1"
+ *   channels: ["C01ALEVABC"]
+ *   ---
+ *   You are the Alev-B dev assistant. Stack: React + Express + Drizzle + MySQL.
+ *   Prefer concise, directly actionable answers about deployment...
+ *
+ * If no workspaces are configured or no match is found, a built-in "default"
+ * workspace is used — it has an empty persona, inherits the global default
+ * working directory, and is the natural fallback so existing single-session
+ * behavior is preserved for users who don't create any workspace configs.
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { WORKSPACES_DIR } from "../paths.js";
+import { config } from "../config.js";
+const registry = new Map();
+/** Expand ~ at the start of a path to the user's home directory. */
+function expandHome(p) {
+    if (!p)
+        return p;
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.resolve(os.homedir(), p.slice(2));
+    return p;
+}
+/** Parse a very simple YAML subset: key: value pairs + arrays in JSON form.
+ *  We deliberately don't pull in a full YAML library — the frontmatter schema
+ *  is tiny and well-defined. Falls back to an empty object on any parse error. */
+function parseFrontmatter(text) {
+    const out = {};
+    for (const rawLine of text.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const colonIdx = line.indexOf(":");
+        if (colonIdx <= 0)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        let value = line.slice(colonIdx + 1).trim();
+        if (!value)
+            continue;
+        // JSON array
+        if (value.startsWith("[")) {
+            try {
+                out[key] = JSON.parse(value);
+                continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        // Quoted string
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** Split a markdown file into frontmatter (YAML) and body. Returns both as
+ *  strings. If no frontmatter delimiters are found, frontmatter is empty and
+ *  the whole content is the body. */
+function splitFrontmatter(content) {
+    const trimmed = content.replace(/^\uFEFF/, "");
+    const match = trimmed.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { frontmatter: "", body: trimmed };
+    return { frontmatter: match[1], body: match[2] };
+}
+/** Read a single workspace file and return the parsed object, or null on failure. */
+function readWorkspaceFile(filePath, name) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { frontmatter, body } = splitFrontmatter(content);
+        const fm = parseFrontmatter(frontmatter);
+        const purpose = typeof fm.purpose === "string" ? fm.purpose : "";
+        const rawCwd = typeof fm.cwd === "string" ? fm.cwd : config.defaultWorkingDir;
+        const cwd = expandHome(rawCwd);
+        const color = typeof fm.color === "string" ? fm.color : undefined;
+        const emoji = typeof fm.emoji === "string" ? fm.emoji : undefined;
+        const channels = Array.isArray(fm.channels)
+            ? fm.channels.filter((c) => typeof c === "string")
+            : [];
+        return {
+            name,
+            purpose,
+            cwd,
+            color,
+            emoji,
+            channels,
+            systemPromptOverride: body.trim(),
+        };
+    }
+    catch (err) {
+        console.warn(`⚠️ workspaces: failed to load ${filePath} —`, err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}
+/** Load all workspaces from ~/.alvin-bot/workspaces/*.md. Returns the count loaded. */
+export function loadWorkspaces() {
+    registry.clear();
+    if (!fs.existsSync(WORKSPACES_DIR))
+        return 0;
+    let count = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(WORKSPACES_DIR);
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md") || entry.startsWith("."))
+            continue;
+        const name = entry.replace(/\.md$/, "");
+        const filePath = path.resolve(WORKSPACES_DIR, entry);
+        const ws = readWorkspaceFile(filePath, name);
+        if (ws) {
+            registry.set(name, ws);
+            count++;
+        }
+    }
+    return count;
+}
+/** Alias for loadWorkspaces — used by the hot-reload file watcher. */
+export function reloadWorkspaces() {
+    return loadWorkspaces();
+}
+/** Return all registered workspaces. */
+export function listWorkspaces() {
+    return Array.from(registry.values());
+}
+/** Get a workspace by name, or null. */
+export function getWorkspace(name) {
+    return registry.get(name) ?? null;
+}
+/** Built-in fallback workspace. Returned when no user workspaces exist or
+ *  no channel-match can be made. Preserves the pre-v4.12.0 behavior. */
+export function getDefaultWorkspace() {
+    return {
+        name: "default",
+        purpose: "",
+        cwd: config.defaultWorkingDir,
+        channels: [],
+        systemPromptOverride: "",
+    };
+}
+/** Try to resolve a platform + channel to a specific workspace.
+ *
+ * Resolution order:
+ *   1. Explicit channel ID match (workspace frontmatter `channels: ["C01ABC"]`)
+ *   2. Channel name match (workspace filename equals the normalized channel name)
+ *   3. Return null (caller should fall back to the default workspace)
+ *
+ * Normalization: strips leading `#`, lowercases, trims whitespace.
+ */
+export function matchWorkspaceForChannel(_platform, channelId, channelName) {
+    // 1. Channel ID match
+    for (const ws of registry.values()) {
+        if (ws.channels.includes(channelId))
+            return ws;
+    }
+    // 2. Channel name match against workspace filename
+    if (channelName) {
+        const normalized = channelName.replace(/^#/, "").trim().toLowerCase();
+        for (const ws of registry.values()) {
+            if (ws.name.toLowerCase() === normalized)
+                return ws;
+        }
+    }
+    return null;
+}
+/** Resolve a channel to a workspace, falling back to the default when no
+ *  match is found. This is the one-call path handlers should use. */
+export function resolveWorkspaceOrDefault(platform, channelId, channelName) {
+    const match = matchWorkspaceForChannel(platform, channelId, channelName);
+    return match ?? getDefaultWorkspace();
+}
+// ── Hot-reload watcher ──────────────────────────────────────────────────
+let watcher = null;
+let reloadDebounceTimer = null;
+/** Start watching the workspaces directory for file changes. Debounced reload
+ *  at 500 ms so a burst of edits (e.g. git checkout) coalesces into one reload. */
+export function startWorkspaceWatcher() {
+    if (watcher)
+        return;
+    if (!fs.existsSync(WORKSPACES_DIR))
+        return;
+    try {
+        watcher = fs.watch(WORKSPACES_DIR, () => {
+            if (reloadDebounceTimer)
+                clearTimeout(reloadDebounceTimer);
+            reloadDebounceTimer = setTimeout(() => {
+                const count = reloadWorkspaces();
+                console.log(`🧭 workspaces: hot-reloaded (${count} registered)`);
+            }, 500);
+        });
+    }
+    catch {
+        // ignore — hot-reload is a nice-to-have
+    }
+}
+/** Stop the hot-reload watcher (for graceful shutdown). */
+export function stopWorkspaceWatcher() {
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch { /* ignore */ }
+        watcher = null;
+    }
+    if (reloadDebounceTimer) {
+        clearTimeout(reloadDebounceTimer);
+        reloadDebounceTimer = null;
+    }
+}
+/** Initialize: load all workspaces + start hot-reload watcher. Called once at startup. */
+export function initWorkspaces() {
+    const count = loadWorkspaces();
+    startWorkspaceWatcher();
+    if (count > 0) {
+        const names = listWorkspaces().map(w => `${w.emoji ?? "🧭"} ${w.name}`).join(", ");
+        console.log(`🧭 Workspaces: ${count} loaded — ${names}`);
+    }
+    return count;
+}

package/dist/web/server.js

@@ -451,6 +451,31 @@ async function handleAPI(req, res, urlPath, body) {
         res.end(JSON.stringify({ plugins: getLoadedPlugins() }));
         return;
     }
+    // v4.12.0 — Workspace overview: registry + per-workspace cost breakdown
+    if (urlPath === "/api/workspaces") {
+        try {
+            const { listWorkspaces, getDefaultWorkspace } = await import("../services/workspaces.js");
+            const { getCostByWorkspace } = await import("../services/session.js");
+            const costs = getCostByWorkspace();
+            const registered = listWorkspaces();
+            const all = [getDefaultWorkspace(), ...registered];
+            const payload = all.map((ws) => ({
+                name: ws.name,
+                purpose: ws.purpose,
+                emoji: ws.emoji ?? null,
+                color: ws.color ?? null,
+                cwd: ws.cwd,
+                channels: ws.channels,
+                stats: costs[ws.name] ?? { totalCost: 0, sessionCount: 0, messageCount: 0, toolUseCount: 0 },
+            }));
+            res.end(JSON.stringify({ workspaces: payload }));
+        }
+        catch (err) {
+            res.statusCode = 500;
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+        return;
+    }
     // GET /api/users — Enhanced with session data
     if (urlPath === "/api/users" && req.method === "GET") {
         const { getAllSessions } = await import("../services/session.js");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alvin-bot",
-  "version": "4.10.0",
-  "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
+  "version": "4.12.0",
+  "description": "Alvin Bot \u2014 Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {