@emqo/claudebridge 0.1.0

package/dist/core/agent.js

@@ -0,0 +1,218 @@
+import { spawn } from "child_process";
+import { mkdirSync } from "fs";
+import { join } from "path";
+import { UserLock } from "./lock.js";
+import { AccessControl } from "./permissions.js";
+import { EndpointRotator } from "./keys.js";
+export class AgentEngine {
+    config;
+    store;
+    lock;
+    rotator;
+    access;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+        this.lock = new UserLock(config.redis.enabled ? config.redis.url : undefined);
+        this.access = new AccessControl(config.access.allowed_users, config.access.allowed_groups);
+        this.rotator = new EndpointRotator(config.endpoints);
+    }
+    reloadConfig(config) {
+        this.config = config;
+        this.access.reload(config.access.allowed_users, config.access.allowed_groups);
+        this.rotator.reload(config.endpoints);
+    }
+    getEndpoints() {
+        return this.rotator.list();
+    }
+    getRotator() {
+        return this.rotator;
+    }
+    getIntentConfig() {
+        return this.config.agent.intent;
+    }
+    getEndpointCount() {
+        return this.rotator.count;
+    }
+    getWorkDir(userId) {
+        if (!this.config.workspace.isolation) {
+            return this.config.agent.cwd || process.cwd();
+        }
+        const dir = join(this.config.workspace.base_dir, userId);
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    isLocked(userId) {
+        return this.lock.isLocked(userId);
+    }
+    async runStream(userId, prompt, platform, onChunk) {
+        const release = await this.lock.acquire(userId);
+        try {
+            this.store.addHistory(userId, platform, "user", prompt);
+            const memories = this.config.agent.memory?.enabled ? this.store.getMemories(userId) : [];
+            const memoryPrompt = memories.length ? memories.map(m => `- ${m.content}`).join("\n") : "";
+            const res = await this._executeWithRetry(userId, prompt, platform, onChunk, memoryPrompt);
+            this.store.addHistory(userId, platform, "assistant", res.text);
+            this.store.recordUsage(userId, platform, res.cost || 0);
+            if (this.config.agent.memory?.auto_summary)
+                this._autoSummarize(userId, prompt, res.text);
+            return res;
+        }
+        finally {
+            release();
+        }
+    }
+    async _executeWithRetry(userId, prompt, platform, onChunk, memoryPrompt) {
+        const maxRetries = Math.min(this.rotator.count, 3);
+        let lastErr;
+        for (let i = 0; i < maxRetries; i++) {
+            const ep = this.rotator.next();
+            try {
+                return await this._execute(userId, prompt, platform, ep, onChunk, memoryPrompt);
+            }
+            catch (err) {
+                lastErr = err;
+                const msg = String(err?.message || "");
+                if (msg.includes("429") || msg.includes("401") || msg.includes("529")) {
+                    console.warn(`[agent] endpoint ${ep.name} failed, rotating`);
+                    this.rotator.markFailed(ep);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastErr;
+    }
+    _execute(userId, prompt, platform, ep, onChunk, memoryPrompt) {
+        return new Promise((resolve, reject) => {
+            const sessionId = this.store.getSession(userId) || "";
+            const cwd = this.getWorkDir(userId);
+            const args = ["-p", prompt, "--verbose", "--output-format", "stream-json", "--permission-mode", this.config.agent.permission_mode || "acceptEdits"];
+            if (ep.model)
+                args.push("--model", ep.model);
+            if (sessionId)
+                args.push("-r", sessionId);
+            if (this.config.agent.system_prompt)
+                args.push("--system-prompt", this.config.agent.system_prompt);
+            if (memoryPrompt)
+                args.push("--append-system-prompt", `User memories:\n${memoryPrompt}`);
+            if (this.config.agent.allowed_tools?.length)
+                args.push("--allowed-tools", this.config.agent.allowed_tools.join(","));
+            if (this.config.agent.max_turns)
+                args.push("--max-turns", String(this.config.agent.max_turns));
+            if (this.config.agent.max_budget_usd)
+                args.push("--max-budget-usd", String(this.config.agent.max_budget_usd));
+            const env = { ...process.env };
+            env.ANTHROPIC_API_KEY = ep.api_key;
+            if (ep.base_url)
+                env.ANTHROPIC_BASE_URL = ep.base_url;
+            const child = spawn("claude", args, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+            child.stdin.end();
+            console.log(`[agent] spawned claude pid=${child.pid} cwd=${cwd} args=${args.join(" ")}`);
+            const timeoutMs = (this.config.agent.timeout_seconds || 300) * 1000;
+            const timer = setTimeout(() => { try {
+                child.kill("SIGTERM");
+            }
+            catch { } }, timeoutMs);
+            let fullText = "";
+            let newSessionId = sessionId;
+            let cost = 0;
+            let buffer = "";
+            child.stdout.on("data", (data) => {
+                const chunk = data.toString();
+                console.log(`[agent] stdout chunk: ${chunk.slice(0, 100)}`);
+                buffer += chunk;
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const msg = JSON.parse(line);
+                        if (msg.type === "system" && msg.subtype === "init" && msg.session_id) {
+                            newSessionId = msg.session_id;
+                        }
+                        if (msg.type === "assistant" && msg.message?.content) {
+                            for (const block of msg.message.content) {
+                                if (block.type === "text" && block.text) {
+                                    fullText += block.text + "\n";
+                                    if (onChunk)
+                                        onChunk(block.text, fullText);
+                                }
+                            }
+                        }
+                        if (msg.type === "result") {
+                            if (msg.result)
+                                fullText = msg.result;
+                            if (msg.total_cost_usd)
+                                cost = msg.total_cost_usd;
+                        }
+                    }
+                    catch { }
+                }
+            });
+            let stderr = "";
+            child.stderr.on("data", (data) => {
+                const s = data.toString();
+                stderr += s;
+                console.log(`[agent] stderr: ${s.slice(0, 200)}`);
+            });
+            child.on("close", (code, signal) => {
+                clearTimeout(timer);
+                console.log(`[agent] claude exited code=${code} signal=${signal} fullText=${fullText.length}chars stderr=${stderr.slice(0, 200)}`);
+                if (signal === "SIGTERM") {
+                    if (newSessionId)
+                        this.store.setSession(userId, newSessionId, platform);
+                    resolve({ text: fullText.trim() || "(timed out)", sessionId: newSessionId, cost });
+                    return;
+                }
+                if (newSessionId)
+                    this.store.setSession(userId, newSessionId, platform);
+                if (code === 0 || fullText.trim()) {
+                    resolve({ text: fullText.trim() || "(no response)", sessionId: newSessionId, cost });
+                }
+                else {
+                    reject(new Error(`claude exited ${code}: ${stderr.slice(0, 500)}`));
+                }
+            });
+            child.on("error", reject);
+        });
+    }
+    _autoSummarize(userId, prompt, response) {
+        const ep = this.rotator.next();
+        const env = { ...process.env };
+        env.ANTHROPIC_API_KEY = ep.api_key;
+        if (ep.base_url)
+            env.ANTHROPIC_BASE_URL = ep.base_url;
+        const summaryPrompt = `Extract 1-3 key facts worth remembering about the user from this exchange. Output only bullet points, no preamble. If nothing worth remembering, output "NONE".\n\nUser: ${prompt.slice(0, 500)}\nAssistant: ${response.slice(0, 1000)}`;
+        const args = ["-p", summaryPrompt, "--output-format", "stream-json", "--max-turns", "1", "--max-budget-usd", "0.05"];
+        if (ep.model)
+            args.push("--model", ep.model);
+        const child = spawn("claude", args, { env, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.end();
+        let result = "";
+        let buffer = "";
+        child.stdout.on("data", (data) => {
+            buffer += data.toString();
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === "result" && msg.result)
+                        result = msg.result;
+                }
+                catch { }
+            }
+        });
+        child.on("close", () => {
+            if (result && !result.includes("NONE")) {
+                this.store.addMemory(userId, result.trim(), "auto");
+                this.store.trimMemories(userId, this.config.agent.memory?.max_memories || 50);
+                console.log(`[agent] auto-summary saved for ${userId}`);
+            }
+        });
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,58 @@
+import "dotenv/config";
+import { Endpoint } from "./keys.js";
+export interface MemoryConfig {
+    enabled: boolean;
+    auto_summary: boolean;
+    max_memories: number;
+}
+export interface IntentConfig {
+    enabled: boolean;
+    use_claude_fallback: boolean;
+}
+export interface AgentConfig {
+    allowed_tools: string[];
+    permission_mode: string;
+    max_turns: number;
+    max_budget_usd: number;
+    system_prompt: string;
+    cwd: string;
+    timeout_seconds: number;
+    memory: MemoryConfig;
+    intent: IntentConfig;
+}
+export interface WorkspaceConfig {
+    base_dir: string;
+    isolation: boolean;
+}
+export interface AccessConfig {
+    allowed_users: string[];
+    allowed_groups: string[];
+}
+export interface TelegramConfig {
+    enabled: boolean;
+    token: string;
+    chunk_size: number;
+}
+export interface DiscordConfig {
+    enabled: boolean;
+    token: string;
+    chunk_size: number;
+}
+export interface RedisConfig {
+    enabled: boolean;
+    url: string;
+}
+export interface Config {
+    endpoints: Endpoint[];
+    agent: AgentConfig;
+    workspace: WorkspaceConfig;
+    access: AccessConfig;
+    redis: RedisConfig;
+    locale: string;
+    platforms: {
+        telegram: TelegramConfig;
+        discord: DiscordConfig;
+    };
+}
+export declare function loadConfig(path?: string): Config;
+export declare function reloadConfig(): Config;

package/dist/core/config.js

@@ -0,0 +1,49 @@
+import { readFileSync } from "fs";
+import { parse } from "yaml";
+import "dotenv/config";
+let _configPath = "config.yaml";
+export function loadConfig(path) {
+    if (path)
+        _configPath = path;
+    const raw = parse(readFileSync(_configPath, "utf-8"));
+    const c = {
+        endpoints: raw.endpoints || [],
+        agent: {
+            ...raw.agent,
+            timeout_seconds: raw.agent?.timeout_seconds ?? 300,
+            memory: { enabled: true, auto_summary: true, max_memories: 50, ...raw.agent?.memory },
+            intent: { enabled: true, use_claude_fallback: true, ...raw.agent?.intent },
+        },
+        workspace: raw.workspace,
+        access: raw.access || { allowed_users: [], allowed_groups: [] },
+        redis: raw.redis || { enabled: false, url: "" },
+        locale: raw.locale || "en",
+        platforms: raw.platforms,
+    };
+    // defaults for each endpoint
+    for (const ep of c.endpoints) {
+        ep.name = ep.name || "default";
+        ep.base_url = ep.base_url || "";
+        ep.api_key = ep.api_key || "";
+        ep.model = ep.model || "";
+    }
+    // env fallback: single endpoint from env vars
+    if (!c.endpoints.length && process.env.ANTHROPIC_API_KEY) {
+        c.endpoints.push({
+            name: "env-default",
+            base_url: process.env.ANTHROPIC_BASE_URL || "",
+            api_key: process.env.ANTHROPIC_API_KEY,
+            model: process.env.ANTHROPIC_MODEL || "",
+        });
+    }
+    c.redis.url = c.redis.url || process.env.REDIS_URL || "";
+    c.platforms.telegram.token =
+        c.platforms.telegram.token || process.env.TELEGRAM_BOT_TOKEN || "";
+    c.platforms.discord = c.platforms.discord || { enabled: false, token: "", chunk_size: 1900 };
+    c.platforms.discord.token =
+        c.platforms.discord.token || process.env.DISCORD_BOT_TOKEN || "";
+    return c;
+}
+export function reloadConfig() {
+    return loadConfig();
+}

package/dist/core/i18n.d.ts

@@ -0,0 +1,5 @@
+export declare function t(locale: string, key: string, vars?: Record<string, string | number>): string;
+export declare function getCommandDescriptions(locale: string): {
+    command: string;
+    description: string;
+}[];

package/dist/core/i18n.js

@@ -0,0 +1,102 @@
+const messages = {
+    en: {
+        help: "ClaudeBridge ready.\n\nCommands:\n/new - clear session\n/usage - your stats\n/allusage - all stats\n/history - recent chats\n/model - endpoints info\n/reload - reload config\n/remember <text> - save a memory\n/memories - list memories\n/forget - clear all memories\n/task <desc> - add a task\n/tasks - list pending tasks\n/done <id> - complete a task\n/remind <minutes>m <desc> - set reminder\n/auto <desc> - queue auto task\n/autotasks - list auto tasks\n/cancelauto <id> - cancel auto task\n\nSend text or files to chat. Unknown /commands are forwarded to Claude.",
+        session_cleared: "Session cleared.",
+        no_usage: "No usage data.",
+        no_history: "No history.",
+        config_reloaded: "Config reloaded.",
+        reload_failed: "Reload failed: ",
+        memory_saved: "✅ Memory saved.",
+        no_memories: "No memories.",
+        memories_cleared: "✅ All memories cleared.",
+        task_added: "✅ Task #{id} added.",
+        no_tasks: "No pending tasks.",
+        task_done: "✅ Task #{id} done.",
+        task_not_found: "Task #{id} not found.",
+        reminder_set: "✅ Reminder #{id} set for {mins}m.",
+        auto_queued: "🤖 Auto task #{id} queued. Will execute when idle.",
+        no_auto_tasks: "No auto tasks.",
+        auto_cancelled: "✅ Auto task #{id} cancelled.",
+        auto_starting: "🤖 Auto task #{id} starting:\n{desc}",
+        auto_done: "✅ Auto task #{id} done (cost: ${cost}):",
+        auto_failed: "❌ Auto task #{id} failed: {err}",
+        thinking: "⏳ Thinking...",
+        still_processing: "⏳ Still processing...",
+        upload_failed: "Upload failed: ",
+        reminder_notify: "⏰ Reminder: {desc}",
+        usage_remember: "Usage: /remember <text>",
+        usage_task: "Usage: /task <description>",
+        usage_done: "Usage: /done <task_id>",
+        usage_remind: "Usage: /remind <minutes>m <description>",
+        usage_auto: "Usage: /auto <task description>",
+        usage_cancelauto: "Usage: /cancelauto <task_id>",
+        intent_reminder_set: "✅ Reminder detected: in {mins}m — {desc} (#{id})",
+        intent_task_added: "✅ Task detected #{id}: {desc}",
+        intent_memory_saved: "✅ Remembered: {desc}",
+    },
+    zh: {
+        help: "ClaudeBridge 就绪。\n\n命令：\n/new - 清除会话\n/usage - 你的用量\n/allusage - 所有用量\n/history - 最近对话\n/model - 端点信息\n/reload - 重载配置\n/remember <文本> - 保存记忆\n/memories - 查看记忆\n/forget - 清除所有记忆\n/task <描述> - 添加任务\n/tasks - 查看待办\n/done <id> - 完成任务\n/remind <分钟>m <描述> - 设置提醒\n/auto <描述> - 排队自动任务\n/autotasks - 查看自动任务\n/cancelauto <id> - 取消自动任务\n\n发送文字或文件即可对话。未知 / 命令会转发给 Claude。",
+        session_cleared: "会话已清除。",
+        no_usage: "暂无用量数据。",
+        no_history: "暂无历史记录。",
+        config_reloaded: "配置已重载。",
+        reload_failed: "重载失败：",
+        memory_saved: "✅ 记忆已保存。",
+        no_memories: "暂无记忆。",
+        memories_cleared: "✅ 所有记忆已清除。",
+        task_added: "✅ 任务 #{id} 已添加。",
+        no_tasks: "暂无待办任务。",
+        task_done: "✅ 任务 #{id} 已完成。",
+        task_not_found: "任务 #{id} 未找到。",
+        reminder_set: "✅ 提醒 #{id} 已设置，{mins}分钟后触发。",
+        auto_queued: "🤖 自动任务 #{id} 已排队，空闲时执行。",
+        no_auto_tasks: "暂无自动任务。",
+        auto_cancelled: "✅ 自动任务 #{id} 已取消。",
+        auto_starting: "🤖 自动任务 #{id} 开始执行：\n{desc}",
+        auto_done: "✅ 自动任务 #{id} 完成（花费：${cost}）：",
+        auto_failed: "❌ 自动任务 #{id} 失败：{err}",
+        thinking: "⏳ 思考中...",
+        still_processing: "⏳ 仍在处理...",
+        upload_failed: "上传失败：",
+        reminder_notify: "⏰ 提醒：{desc}",
+        usage_remember: "用法：/remember <文本>",
+        usage_task: "用法：/task <描述>",
+        usage_done: "用法：/done <任务ID>",
+        usage_remind: "用法：/remind <分钟>m <描述>",
+        usage_auto: "用法：/auto <任务描述>",
+        usage_cancelauto: "用法：/cancelauto <任务ID>",
+        intent_reminder_set: "✅ 已识别提醒：{mins}分钟后 — {desc} (#{id})",
+        intent_task_added: "✅ 已识别任务 #{id}：{desc}",
+        intent_memory_saved: "✅ 已识别并记住：{desc}",
+    },
+};
+const commandDescriptions = {
+    en: {
+        new: "Clear session", usage: "Your usage stats", allusage: "All users usage",
+        history: "Recent conversations", model: "Current model/endpoints", reload: "Reload config",
+        remember: "Save a memory", memories: "List your memories", forget: "Clear all memories",
+        task: "Add a task", tasks: "List pending tasks", done: "Complete a task",
+        remind: "Set a timed reminder", auto: "Queue auto task (runs when idle)",
+        autotasks: "List auto tasks", cancelauto: "Cancel an auto task", help: "Show all commands",
+    },
+    zh: {
+        new: "清除会话", usage: "你的用量", allusage: "所有用量",
+        history: "最近对话", model: "端点信息", reload: "重载配置",
+        remember: "保存记忆", memories: "查看记忆", forget: "清除所有记忆",
+        task: "添加任务", tasks: "查看待办", done: "完成任务",
+        remind: "设置提醒", auto: "排队自动任务（空闲执行）",
+        autotasks: "查看自动任务", cancelauto: "取消自动任务", help: "显示所有命令",
+    },
+};
+export function t(locale, key, vars) {
+    const lang = messages[locale] ? locale : "en";
+    let msg = messages[lang][key] ?? messages.en[key] ?? key;
+    if (vars)
+        for (const [k, v] of Object.entries(vars))
+            msg = msg.replaceAll(`{${k}}`, String(v));
+    return msg;
+}
+export function getCommandDescriptions(locale) {
+    const lang = commandDescriptions[locale] ? locale : "en";
+    return Object.entries(commandDescriptions[lang]).map(([command, description]) => ({ command, description }));
+}

package/dist/core/intent.d.ts

@@ -0,0 +1,10 @@
+import { IntentConfig } from "./config.js";
+import { EndpointRotator } from "./keys.js";
+export interface IntentResult {
+    type: "reminder" | "task" | "memory" | "forget" | "clear_session" | "none";
+    description?: string;
+    minutes?: number;
+}
+export declare function regexDetect(text: string): IntentResult;
+export declare function claudeDetect(text: string, rotator: EndpointRotator): Promise<IntentResult>;
+export declare function detectIntent(text: string, rotator: EndpointRotator, config?: IntentConfig): Promise<IntentResult>;

package/dist/core/intent.js

@@ -0,0 +1,84 @@
+import { spawn } from "child_process";
+const patterns = [
+    [/(?:提醒我?|remind\s*me)\s*(\d+)\s*(?:分钟|min(?:ute)?s?|m)\s*(?:后|later)?\s*(.+)/i,
+        m => ({ type: "reminder", minutes: +m[1], description: m[2].trim() })],
+    [/^(?:添加|加个?|创建|add|create)\s*(?:一个)?(?:任务|task)[：:\s]*(.+)/i,
+        m => ({ type: "task", description: m[1].trim() })],
+    [/^(?:记住|记下|remember)\s*(?:that|this)?[：:\s]*(.+)/i,
+        m => ({ type: "memory", description: m[1].trim() })],
+    [/^(?:忘记所有|清除记忆|forget\s*all|clear\s*memo)/i,
+        () => ({ type: "forget" })],
+    [/^(?:新会话|新对话|new\s*session|clear\s*session)/i,
+        () => ({ type: "clear_session" })],
+];
+export function regexDetect(text) {
+    for (const [re, fn] of patterns) {
+        const m = text.match(re);
+        if (m)
+            return fn(m);
+    }
+    return { type: "none" };
+}
+export function claudeDetect(text, rotator) {
+    return new Promise(resolve => {
+        const timeout = setTimeout(() => resolve({ type: "none" }), 15000);
+        const ep = rotator.next();
+        const env = { ...process.env };
+        env.ANTHROPIC_API_KEY = ep.api_key;
+        if (ep.base_url)
+            env.ANTHROPIC_BASE_URL = ep.base_url;
+        const prompt = `Classify the user's intent. Output ONLY one JSON line, no other text:
+{"type":"reminder","minutes":5,"description":"check server"}
+{"type":"task","description":"buy milk"}
+{"type":"memory","description":"I like TypeScript"}
+{"type":"none"}
+
+User: ${text.slice(0, 500)}`;
+        const args = ["-p", prompt, "--output-format", "stream-json", "--max-turns", "1", "--max-budget-usd", "0.005"];
+        if (ep.model)
+            args.push("--model", ep.model);
+        const child = spawn("claude", args, { env, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.end();
+        let result = "";
+        let buffer = "";
+        child.stdout.on("data", (d) => {
+            buffer += d.toString();
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === "result" && msg.result)
+                        result = msg.result;
+                }
+                catch { }
+            }
+        });
+        child.on("close", () => {
+            clearTimeout(timeout);
+            try {
+                const m = result.match(/\{[^}]+\}/);
+                if (m) {
+                    const obj = JSON.parse(m[0]);
+                    if (obj.type && obj.type !== "none") {
+                        resolve(obj);
+                        return;
+                    }
+                }
+            }
+            catch { }
+            resolve({ type: "none" });
+        });
+        child.on("error", () => { clearTimeout(timeout); resolve({ type: "none" }); });
+    });
+}
+export async function detectIntent(text, rotator, config) {
+    const r = regexDetect(text);
+    if (r.type !== "none")
+        return r;
+    if (config?.use_claude_fallback !== false)
+        return claudeDetect(text, rotator);
+    return { type: "none" };
+}

package/dist/core/keys.d.ts

@@ -0,0 +1,22 @@
+export interface Endpoint {
+    name: string;
+    base_url: string;
+    api_key: string;
+    model: string;
+}
+/** Round-robin endpoint rotation with cooldown on failure */
+export declare class EndpointRotator {
+    private endpoints;
+    private index;
+    private cooldowns;
+    private cooldownMs;
+    constructor(endpoints: Endpoint[]);
+    next(): Endpoint;
+    markFailed(ep: Endpoint): void;
+    get count(): number;
+    list(): {
+        name: string;
+        model: string;
+    }[];
+    reload(endpoints: Endpoint[]): void;
+}

package/dist/core/keys.js

@@ -0,0 +1,42 @@
+/** Round-robin endpoint rotation with cooldown on failure */
+export class EndpointRotator {
+    endpoints;
+    index = 0;
+    cooldowns = new Map();
+    cooldownMs = 60_000;
+    constructor(endpoints) {
+        this.endpoints = endpoints.filter(e => e.api_key);
+        if (!this.endpoints.length)
+            throw new Error("No endpoints configured");
+    }
+    next() {
+        const now = Date.now();
+        const len = this.endpoints.length;
+        for (let i = 0; i < len; i++) {
+            const idx = (this.index + i) % len;
+            if ((this.cooldowns.get(idx) || 0) <= now) {
+                this.index = (idx + 1) % len;
+                return this.endpoints[idx];
+            }
+        }
+        const idx = this.index;
+        this.index = (idx + 1) % len;
+        return this.endpoints[idx];
+    }
+    markFailed(ep) {
+        const idx = this.endpoints.indexOf(ep);
+        if (idx >= 0)
+            this.cooldowns.set(idx, Date.now() + this.cooldownMs);
+    }
+    get count() {
+        return this.endpoints.length;
+    }
+    list() {
+        return this.endpoints.map(e => ({ name: e.name, model: e.model }));
+    }
+    reload(endpoints) {
+        this.endpoints = endpoints.filter(e => e.api_key);
+        this.index = 0;
+        this.cooldowns.clear();
+    }
+}

package/dist/core/lock.d.ts

@@ -0,0 +1,12 @@
+/** Per-user lock with Redis backend, memory fallback */
+export declare class UserLock {
+    private memLocks;
+    private redis;
+    private prefix;
+    private ttl;
+    constructor(redisUrl?: string);
+    acquire(userId: string): Promise<() => void>;
+    isLocked(userId: string): boolean;
+    private _acquireMem;
+    private _acquireRedis;
+}

package/dist/core/lock.js

@@ -0,0 +1,57 @@
+import Redis from "ioredis";
+/** Per-user lock with Redis backend, memory fallback */
+export class UserLock {
+    memLocks = new Map();
+    redis = null;
+    prefix = "claudebridge:lock:";
+    ttl = 300; // 5 min max lock
+    constructor(redisUrl) {
+        if (redisUrl) {
+            try {
+                this.redis = new Redis(redisUrl, { maxRetriesPerRequest: 1, lazyConnect: true });
+                this.redis.connect().catch(() => {
+                    console.warn("[lock] Redis unavailable, falling back to memory");
+                    this.redis = null;
+                });
+            }
+            catch {
+                this.redis = null;
+            }
+        }
+    }
+    async acquire(userId) {
+        if (this.redis)
+            return this._acquireRedis(userId);
+        return this._acquireMem(userId);
+    }
+    isLocked(userId) {
+        if (this.redis)
+            return false; // can't sync-check redis, rely on acquire
+        return this.memLocks.has(userId);
+    }
+    async _acquireMem(userId) {
+        while (this.memLocks.has(userId)) {
+            await this.memLocks.get(userId);
+        }
+        let release;
+        const p = new Promise((r) => (release = r));
+        this.memLocks.set(userId, p);
+        return () => {
+            this.memLocks.delete(userId);
+            release();
+        };
+    }
+    async _acquireRedis(userId) {
+        const key = this.prefix + userId;
+        // spin until acquired
+        while (true) {
+            const ok = await this.redis.set(key, "1", "EX", this.ttl, "NX");
+            if (ok)
+                break;
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        return async () => {
+            await this.redis.del(key).catch(() => { });
+        };
+    }
+}

package/dist/core/markdown.d.ts

@@ -0,0 +1,7 @@
+/** Escape text for Telegram MarkdownV2 */
+export declare function escapeMarkdownV2(text: string): string;
+/**
+ * Convert standard markdown to Telegram MarkdownV2.
+ * Handles code blocks (preserve as-is), inline code, bold, italic, links.
+ */
+export declare function toTelegramMarkdown(text: string): string;