aiden-runtime 4.0.2 → 4.1.0

package/dist/core/channels/telegram-commands.js

@@ -0,0 +1,154 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramCommandRouter = void 0;
+const logger_1 = require("../v4/logger");
+class TelegramCommandRouter {
+    constructor(opts) {
+        this.store = opts.store;
+        this.log = opts.logger ?? (0, logger_1.noopLogger)();
+        this.botUsername = opts.botUsername ?? (() => null);
+        this.fetchGroupAdmins = opts.fetchGroupAdmins;
+    }
+    /**
+     * Inspect a Telegram message and decide whether to consume it as a
+     * command or pass it through to the agent. Pure dispatch — never
+     * sends messages itself; the caller renders the reply text and
+     * applies state changes.
+     */
+    async route(msg) {
+        const text = (msg.text ?? '').trim();
+        if (!text.startsWith('/'))
+            return { kind: 'agent' };
+        const { cmd, args } = this.parseCommand(text);
+        if (!cmd)
+            return { kind: 'agent' };
+        const chatId = String(msg.chat.id);
+        const chatType = msg.chat.type;
+        const senderId = msg.from?.id ? String(msg.from.id) : '';
+        switch (cmd) {
+            case '/help':
+            case '/start':
+                return { kind: 'reply', text: this.helpText(chatType) };
+            case '/status':
+                return { kind: 'reply', text: '✓ Online' };
+            case '/clear': {
+                // DMs: anyone may /clear their own chat. Groups: admin only.
+                if (chatType !== 'private' && !(await this.isAdmin(senderId, chatId))) {
+                    this.log.info(`/clear ignored — non-admin in group`, { chatId, senderId });
+                    return { kind: 'handled' };
+                }
+                if (chatType !== 'private')
+                    this.store.recordAdminAction(chatId, 'clear', senderId);
+                return { kind: 'cleared' };
+            }
+            case '/pause': {
+                if (!this.requireGroup(chatType) || !(await this.isAdmin(senderId, chatId))) {
+                    this.log.info(`/pause ignored`, { chatId, senderId, chatType });
+                    return { kind: 'handled' };
+                }
+                this.store.setPaused(chatId, true, senderId);
+                return { kind: 'paused', groupId: chatId };
+            }
+            case '/resume': {
+                if (!this.requireGroup(chatType) || !(await this.isAdmin(senderId, chatId))) {
+                    this.log.info(`/resume ignored`, { chatId, senderId, chatType });
+                    return { kind: 'handled' };
+                }
+                this.store.setPaused(chatId, false, senderId);
+                return { kind: 'resumed', groupId: chatId };
+            }
+            case '/allowusers': {
+                if (!this.requireGroup(chatType) || !(await this.isAdmin(senderId, chatId))) {
+                    this.log.info(`/allowusers ignored`, { chatId, senderId, chatType });
+                    return { kind: 'handled' };
+                }
+                // Comma- or space-separated. `/allowusers reset` clears the list.
+                const raw = args.join(' ').trim();
+                if (raw === '' || raw === 'reset' || raw === 'clear') {
+                    this.store.setAllowedUsers(chatId, [], senderId);
+                    return { kind: 'reply', text: '✓ Cleared user allowlist for this group.' };
+                }
+                const ids = raw.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+                this.store.setAllowedUsers(chatId, ids, senderId);
+                return {
+                    kind: 'reply',
+                    text: `✓ User allowlist updated: ${ids.length} id(s) — only these users may chat with the bot here.`,
+                };
+            }
+            default:
+                // Unknown slash command — fall through to the agent. The
+                // model can decide whether to interpret it as natural input.
+                return { kind: 'agent' };
+        }
+    }
+    // ── Admin checks ────────────────────────────────────────────────
+    /**
+     * True when `senderId` is allowed to issue admin-only commands here.
+     * Owner takes priority; TELEGRAM_ADMIN_USERS escalates additional
+     * ids; TELEGRAM_TRUST_GROUP_ADMINS=true (off by default) accepts
+     * Telegram-side group admins.
+     */
+    async isAdmin(senderId, chatId) {
+        if (!senderId)
+            return false;
+        const ownerId = (process.env.TELEGRAM_OWNER_ID ?? '').trim();
+        if (ownerId && senderId === ownerId)
+            return true;
+        const adminCsv = (process.env.TELEGRAM_ADMIN_USERS ?? '').trim();
+        if (adminCsv) {
+            const admins = adminCsv.split(',').map((s) => s.trim()).filter(Boolean);
+            if (admins.includes(senderId))
+                return true;
+        }
+        const trustGroupAdmins = (process.env.TELEGRAM_TRUST_GROUP_ADMINS ?? '').toLowerCase() === 'true';
+        if (trustGroupAdmins && this.fetchGroupAdmins) {
+            try {
+                const admins = await this.fetchGroupAdmins(chatId);
+                if (admins.includes(senderId))
+                    return true;
+            }
+            catch (err) {
+                this.log.warn(`getChatAdministrators failed: ${err?.message ?? err}`, { chatId });
+            }
+        }
+        return false;
+    }
+    // ── Internals ───────────────────────────────────────────────────
+    /**
+     * Extract `/cmd` and the args list from raw text.
+     * Strips `@bot_username` suffixes Telegram appends in groups so
+     * `/clear@aiden_test_bot` resolves to `/clear`.
+     */
+    parseCommand(raw) {
+        const parts = raw.split(/\s+/);
+        if (!parts[0] || !parts[0].startsWith('/'))
+            return { cmd: null, args: [] };
+        const username = (this.botUsername() ?? '').toLowerCase();
+        let head = parts[0].toLowerCase();
+        if (username && head.endsWith(`@${username}`)) {
+            head = head.slice(0, head.length - username.length - 1);
+        }
+        return { cmd: head, args: parts.slice(1) };
+    }
+    requireGroup(chatType) {
+        return chatType === 'group' || chatType === 'supergroup';
+    }
+    helpText(chatType) {
+        const groupExtras = chatType !== 'private'
+            ? '`/pause`       admin: stop bot in this group\n' +
+                '`/resume`      admin: resume bot\n' +
+                '`/allowusers`  admin: restrict who may chat\n'
+            : '';
+        return ('*Aiden* — your local AI assistant.\n\n' +
+            'Send any message (or @mention me in a group) to start. Built-in commands:\n' +
+            '`/help`        show this message\n' +
+            '`/status`      bot health check\n' +
+            '`/clear`       wipe this chat\'s memory\n' +
+            groupExtras);
+    }
+}
+exports.TelegramCommandRouter = TelegramCommandRouter;

package/dist/core/channels/telegram-groups.js

@@ -0,0 +1,198 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramGroupStore = void 0;
+// core/channels/telegram-groups.ts — Phase v4.1-2.
+//
+// Persistent per-group state for the Telegram channel:
+//   - paused              — admin /pause stops the bot from replying
+//   - allowedUsers        — opt-in restriction set by /allowusers
+//   - title               — group display name (cached for /channel
+//                           telegram groups list — Telegram's getChat
+//                           costs an HTTP call per query)
+//   - lastMessageAt       — wall-clock of the last seen inbound msg
+//   - lastAdminAction     — when an admin last touched the state
+//   - firstSeenAt         — when the bot first observed this group
+//
+// State lives at `<aidenRoot>/state/telegram-groups.json`. Atomic
+// writes (tmp → rename) keep the file consistent across process
+// crashes. Loaded once at adapter start; mutations debounce flushes
+// at 1 s so a burst of admin commands doesn't hammer the disk.
+//
+// All diagnostics route through the v4.1-1.3a Logger contract.
+// No console.* anywhere in this module.
+const node_fs_1 = require("node:fs");
+const node_fs_2 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../v4/logger");
+/**
+ * In-memory + disk-backed store of per-group state. Read paths are
+ * always synchronous reads of the in-memory map; mutations schedule
+ * a debounced flush so a burst of admin commands collapses to one
+ * write.
+ */
+class TelegramGroupStore {
+    constructor(opts) {
+        this.groups = new Map();
+        this.flushTimer = null;
+        this.loaded = false;
+        this.stateDir = node_path_1.default.join(opts.paths.root, 'state');
+        this.statePath = node_path_1.default.join(this.stateDir, 'telegram-groups.json');
+        this.log = opts.logger ?? (0, logger_1.noopLogger)();
+        this.flushDebounceMs = opts.flushDebounceMs ?? 1000;
+    }
+    /**
+     * Synchronously load on first call. Subsequent calls are no-ops.
+     * Failure to read is treated as "fresh state" — better than crashing
+     * the adapter on a malformed file.
+     */
+    async load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        if (!(0, node_fs_2.existsSync)(this.statePath))
+            return;
+        try {
+            const raw = await node_fs_1.promises.readFile(this.statePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed?.version !== 1 || !parsed.groups)
+                return;
+            for (const [id, g] of Object.entries(parsed.groups)) {
+                if (g && typeof g === 'object' && 'groupId' in g) {
+                    this.groups.set(id, normalizeOnLoad(g));
+                }
+            }
+            this.log.info(`loaded ${this.groups.size} group(s)`);
+        }
+        catch (err) {
+            this.log.warn(`could not load state: ${err?.message ?? err}`);
+        }
+    }
+    /** True when this group is allowed to interact with the bot. */
+    isPaused(groupId) {
+        return this.groups.get(groupId)?.paused === true;
+    }
+    /**
+     * When an allowed-users list is set on a group, only those users may
+     * converse. Empty list (the default) → everyone in the group is OK.
+     * Returns true when the user is allowed.
+     */
+    userIsAllowed(groupId, userId) {
+        const g = this.groups.get(groupId);
+        if (!g || g.allowedUsers.length === 0)
+            return true;
+        return g.allowedUsers.includes(userId);
+    }
+    /** Public accessor for /channel telegram groups list. */
+    list() {
+        return Array.from(this.groups.values()).sort((a, b) => (b.lastMessageAt ?? 0) - (a.lastMessageAt ?? 0));
+    }
+    get(groupId) {
+        return this.groups.get(groupId);
+    }
+    /** Record an inbound observation — bumps lastMessageAt + caches title. */
+    observeMessage(groupId, opts) {
+        const existing = this.groups.get(groupId);
+        const now = Date.now();
+        if (existing) {
+            existing.lastMessageAt = now;
+            if (opts.title && existing.title !== opts.title)
+                existing.title = opts.title;
+        }
+        else {
+            this.groups.set(groupId, {
+                groupId,
+                title: opts.title,
+                paused: false,
+                allowedUsers: [],
+                firstSeenAt: now,
+                lastMessageAt: now,
+            });
+        }
+        this.scheduleFlush();
+    }
+    setPaused(groupId, paused, actor) {
+        const g = this.ensureGroup(groupId);
+        g.paused = paused;
+        g.lastAdminAction = { actor, cmd: paused ? 'pause' : 'resume', at: Date.now() };
+        this.scheduleFlush();
+    }
+    setAllowedUsers(groupId, userIds, actor) {
+        const g = this.ensureGroup(groupId);
+        g.allowedUsers = [...new Set(userIds.map(s => s.trim()).filter(Boolean))];
+        g.lastAdminAction = { actor, cmd: 'allowusers', at: Date.now() };
+        this.scheduleFlush();
+    }
+    recordAdminAction(groupId, cmd, actor) {
+        const g = this.ensureGroup(groupId);
+        g.lastAdminAction = { actor, cmd, at: Date.now() };
+        this.scheduleFlush();
+    }
+    /** Force-flush + clear debounce timer (called on adapter teardown). */
+    async flushNow() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.writeFile();
+    }
+    // ── Internals ─────────────────────────────────────────────────
+    ensureGroup(groupId) {
+        let g = this.groups.get(groupId);
+        if (!g) {
+            g = {
+                groupId,
+                paused: false,
+                allowedUsers: [],
+                firstSeenAt: Date.now(),
+            };
+            this.groups.set(groupId, g);
+        }
+        return g;
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.writeFile().catch((err) => this.log.warn(`flush failed: ${err?.message ?? err}`));
+        }, this.flushDebounceMs);
+        if (typeof this.flushTimer.unref === 'function')
+            this.flushTimer.unref();
+    }
+    async writeFile() {
+        const payload = {
+            version: 1,
+            groups: Object.fromEntries(this.groups),
+        };
+        await node_fs_1.promises.mkdir(this.stateDir, { recursive: true });
+        const tmp = `${this.statePath}.${process.pid}.tmp`;
+        await node_fs_1.promises.writeFile(tmp, JSON.stringify(payload, null, 2), 'utf8');
+        await node_fs_1.promises.rename(tmp, this.statePath);
+    }
+}
+exports.TelegramGroupStore = TelegramGroupStore;
+/**
+ * Defensive load-time normaliser — older state files may be missing
+ * fields we've since added; fall back to safe defaults instead of
+ * propagating undefined into the rest of the adapter.
+ */
+function normalizeOnLoad(raw) {
+    return {
+        groupId: String(raw.groupId),
+        title: typeof raw.title === 'string' ? raw.title : undefined,
+        paused: raw.paused === true,
+        allowedUsers: Array.isArray(raw.allowedUsers) ? raw.allowedUsers.map(String) : [],
+        firstSeenAt: typeof raw.firstSeenAt === 'number' ? raw.firstSeenAt : Date.now(),
+        lastMessageAt: typeof raw.lastMessageAt === 'number' ? raw.lastMessageAt : undefined,
+        lastAdminAction: raw.lastAdminAction && typeof raw.lastAdminAction === 'object'
+            ? raw.lastAdminAction
+            : undefined,
+    };
+}

package/dist/core/channels/telegram-rate-limit.js

@@ -0,0 +1,124 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramRateLimiter = void 0;
+// core/channels/telegram-rate-limit.ts — Phase v4.1-2.
+//
+// Sliding-window per-user rate limiter for the Telegram channel.
+//
+// Design:
+//   - In-memory only — resets on aiden restart. The threat model is
+//     "stop a single chatter from burning the bot owner's quota in
+//     one sitting"; a restart-bypass that costs the abuser an entire
+//     restart-window's worth of messages is acceptable.
+//   - Single user-id keyspace across all chats — a spammer can't dodge
+//     by hopping between groups.
+//   - 1-minute sliding window, default 5 messages. Both knobs are
+//     configurable via env (`TELEGRAM_USER_RATE_LIMIT`,
+//     `TELEGRAM_USER_RATE_WINDOW_MS`) so an op who hosts the bot for a
+//     bigger community can bump them without code changes.
+//   - `shouldThrottle(userId)` is the only consumer-facing method —
+//     records the access *and* reports whether the caller should drop
+//     the message. One lookup, one mutation, one decision.
+//   - A coalescing sweeper trims stale buckets every 5 minutes so an
+//     adversary can't blow the heap by hammering with fresh user ids.
+//
+// `TelegramRateLimiter` accepts an injected logger from the unified
+// `Logger` contract (Phase v4.1-1.3a) — diagnostics file-only, REPL
+// stays sacred. No console.* anywhere in this module.
+const logger_1 = require("../v4/logger");
+const DEFAULT_LIMIT = 5;
+const DEFAULT_WINDOW_MS = 60000;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // prune buckets idle > sweep+window
+class TelegramRateLimiter {
+    constructor(opts = {}) {
+        this.buckets = new Map();
+        this.sweepTimer = null;
+        this.limit = readPositiveInt(process.env.TELEGRAM_USER_RATE_LIMIT, opts.limit ?? DEFAULT_LIMIT);
+        this.windowMs = readPositiveInt(process.env.TELEGRAM_USER_RATE_WINDOW_MS, opts.windowMs ?? DEFAULT_WINDOW_MS);
+        this.now = opts.now ?? Date.now;
+        this.log = opts.logger ?? (0, logger_1.noopLogger)();
+    }
+    /**
+     * Record an attempted message + return true when the caller should
+     * drop it. The bucket is updated on every call (even ones that get
+     * throttled), so a sustained over-limit user stays throttled until
+     * the oldest message in their window ages out.
+     */
+    shouldThrottle(userId) {
+        if (!userId)
+            return false;
+        const cutoff = this.now() - this.windowMs;
+        const bucket = this.buckets.get(userId) ?? [];
+        // Drop expired entries from the front (oldest-first list).
+        while (bucket.length > 0 && bucket[0] <= cutoff)
+            bucket.shift();
+        if (bucket.length >= this.limit) {
+            // Don't append on throttle so the window can age out cleanly —
+            // appending here would reset the user's clock every time they
+            // try to spam, locking them in indefinitely.
+            this.buckets.set(userId, bucket);
+            this.log.warn(`rate-limited`, { userId, count: bucket.length, limit: this.limit });
+            return true;
+        }
+        bucket.push(this.now());
+        this.buckets.set(userId, bucket);
+        this.scheduleSweep();
+        return false;
+    }
+    /** Test / diagnostic accessor — current bucket size for a user. */
+    getCount(userId) {
+        const bucket = this.buckets.get(userId);
+        if (!bucket)
+            return 0;
+        const cutoff = this.now() - this.windowMs;
+        return bucket.filter((t) => t > cutoff).length;
+    }
+    /** Stop the sweep timer (called on adapter teardown). */
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    // ── Internal: prune fully-expired buckets so memory doesn't drift. ──
+    scheduleSweep() {
+        if (this.sweepTimer)
+            return;
+        this.sweepTimer = setInterval(() => this.sweep(), SWEEP_INTERVAL_MS);
+        // Don't keep the process alive just for the sweeper.
+        if (typeof this.sweepTimer.unref === 'function')
+            this.sweepTimer.unref();
+    }
+    sweep() {
+        const cutoff = this.now() - this.windowMs;
+        let pruned = 0;
+        for (const [userId, bucket] of this.buckets) {
+            const filtered = bucket.filter((t) => t > cutoff);
+            if (filtered.length === 0) {
+                this.buckets.delete(userId);
+                pruned += 1;
+            }
+            else {
+                this.buckets.set(userId, filtered);
+            }
+        }
+        if (pruned > 0)
+            this.log.debug(`swept ${pruned} stale buckets`);
+    }
+}
+exports.TelegramRateLimiter = TelegramRateLimiter;
+/**
+ * Parse a positive integer env var with a fallback. Negative / NaN /
+ * empty values fall back to the default — better than crashing the
+ * adapter because someone fat-fingered an env var.
+ */
+function readPositiveInt(envValue, fallback) {
+    if (typeof envValue !== 'string' || envValue.trim() === '')
+        return fallback;
+    const n = Number.parseInt(envValue, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}