@tspappsen/elamax 1.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ELA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# Max
+
+AI orchestrator powered by [Copilot SDK](https://github.com/github/copilot-sdk) — control multiple Copilot CLI sessions from Telegram or a local terminal.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/burkeholland/max/main/install.sh | bash
+```
+
+Or install directly with npm:
+
+```bash
+npm install -g elamax
+```
+
+## Quick Start
+
+### 1. Run setup
+
+```bash
+max setup
+```
+
+This creates `~/.max/` and walks you through configuration (Telegram bot token, etc.). Telegram is optional — you can use Max with just the terminal UI.
+
+If you're running Max from a local clone instead of a global install, use:
+
+```bash
+npm run build
+node dist/cli.js setup
+```
+
+You can also run setup directly from source without building first:
+
+```bash
+npx tsx src/setup.ts
+```
+
+### 2. Make sure Copilot CLI is authenticated
+
+```bash
+copilot login
+```
+
+### 3. Start Max
+
+```bash
+max start
+```
+
+From a local clone, use:
+
+```bash
+node dist/cli.js start
+```
+
+### 4. Connect via terminal
+
+In a separate terminal:
+
+```bash
+max tui
+```
+
+From a local clone, use:
+
+```bash
+npm run tui
+```
+
+### 5. Talk to Max
+
+From Telegram or the TUI, just send natural language:
+
+- "Start working on the auth bug in ~/dev/myapp"
+- "What sessions are running?"
+- "Check on the api-tests session"
+- "Kill the auth-fix session"
+- "Restart yourself"
+- "What's the capital of France?"
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `max start` | Start the Max daemon |
+| `max tui` | Connect to the daemon via terminal |
+| `max setup` | Interactive first-run configuration |
+| `max update` | Check for and install updates |
+| `max help` | Show available commands |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--profile <name>` | Run as a named profile (e.g. `--profile watchdog`) |
+| `--self-edit` | Allow Max to modify his own source code (use with `max start`) |
+
+### TUI commands
+
+| Command | Description |
+|---------|-------------|
+| `/model [name]` | Show or switch the current model |
+| `/memory` | Show stored memories |
+| `/skills` | List installed skills |
+| `/workers` | List active worker sessions |
+| `/copy` | Copy last response to clipboard |
+| `/status` | Daemon health check |
+| `/restart` | Restart the daemon (under pm2, exit and let pm2 restart it) |
+| `/cancel` | Cancel the current in-flight message |
+| `/clear` | Clear the screen |
+| `/help` | Show help |
+| `/quit` | Exit the TUI |
+| `Escape` | Cancel a running response |
+
+### Restarting Max
+
+You can restart Max in any of these ways:
+
+- **TUI**: run `/restart`
+- **Telegram**: send `/restart`
+- **Discord**: use `/restart`
+- **Natural language**: ask Max something like "restart yourself" or "restart and come back online"
+
+If Max is running under [pm2](https://pm2.keymetrics.io/), a restart request does **not** spawn a replacement process directly.
+Instead, Max detects pm2 by checking `PM2_HOME` or `pm_id`, logs a message, and exits cleanly.
+pm2 then starts the daemon again.
+
+So the behavior is:
+
+- **pm2-managed** → exit only, let pm2 restart
+- **non-pm2** → spawn a detached replacement process, then exit
+
+## How it Works
+
+Max runs a persistent **orchestrator Copilot session** — an always-on AI brain that receives your messages and decides how to handle them. For coding tasks, it spawns **worker Copilot sessions** in specific directories. For simple questions, it answers directly.
+
+You can talk to Max from:
+- **Telegram** — remote access from your phone (authenticated by user ID)
+- **TUI** — local terminal client (no auth needed)
+
+## Architecture
+
+```
+Telegram ──→ Max Daemon ←── TUI
+                │
+          Orchestrator Session (Copilot SDK)
+                │
+      ┌─────────┼─────────┐
+   Worker 1  Worker 2  Worker N
+```
+
+- **Daemon** (`max start`) — persistent service running Copilot SDK + Telegram bot + HTTP API
+- **TUI** (`max tui`) — lightweight terminal client connecting to the daemon
+- **Orchestrator** — long-running Copilot session with custom tools for session management
+- **Workers** — child Copilot sessions for specific coding tasks
+
+## Development
+
+When developing locally, `npm run dev` starts the daemon in watch mode, but it does **not** register the `max` command on your system. Use the built CLI directly:
+
+```bash
+# One-time install
+git clone https://github.com/burkeholland/max.git
+cd max
+npm install
+
+# Run setup locally
+npm run build
+node dist/cli.js setup
+
+# Start the daemon in watch mode
+npm run dev
+
+# In a second terminal, connect the TUI
+npm run tui
+```
+
+If you want the `max` command while developing locally, link the package after building:
+
+```bash
+npm run build
+npm link
+max setup
+max start
+max tui
+```
+
+On Windows, prefer `node dist/cli.js setup` for local development rather than the shell installer.
+
+### Running as a background service with pm2
+
+To keep Max running even after you close the terminal, use [pm2](https://pm2.keymetrics.io/):
+
+When Max restarts under pm2, it no longer spawns a second process itself.
+It checks for `PM2_HOME` or `pm_id`, exits cleanly, and lets pm2 bring it back.
+This avoids duplicate daemon instances during restart.
+
+```bash
+# Install pm2 globally
+npm install -g pm2
+
+# Start Max with pm2
+pm2 start "npm run dev" --name max
+
+# Check status
+pm2 list
+
+# Stop it
+pm2 stop max
+
+# Restart it manually
+pm2 restart max
+
+# Auto-start on login (macOS uses launchd)
+pm2 startup   # follow the printed instructions
+pm2 save
+```
+
+pm2 works on macOS, Linux, and Windows.
+
+## Watchdog
+
+Max-Watchdog is a second, ops-only Max instance that monitors and repairs the main Max daemon. When main Max goes down, you message the watchdog over Telegram (or Discord) to diagnose, read logs, and restart — no SSH required.
+
+### How it works
+
+```
+┌────────────────────────┐     ┌─────────────────────────┐
+│  Main Max (~/.max)     │     │  Watchdog Max           │
+│  Port 7777             │     │  (~/.max-watchdog)      │
+│  @MaxBot on Telegram   │     │  Port 7778              │
+│  General-purpose AI    │     │  @WatchdogBot           │
+│  Skills, workers, etc. │     │  Ops-only: health,      │
+└────────────────────────┘     │  restart, logs, shell   │
+                               └─────────────────────────┘
+```
+
+Two fully isolated instances: separate home directories, separate SQLite databases, separate bot tokens, separate ports, separate pm2 processes. Zero shared state.
+
+### Watchdog setup
+
+1. Create a **second Telegram bot** via [@BotFather](https://t.me/BotFather) (e.g. "Max Watchdog 🔧").
+
+2. Run the watchdog setup wizard:
+
+```bash
+max setup --profile watchdog
+```
+
+This creates `~/.max-watchdog/` and prompts for the watchdog bot token, your user ID, API port (default 7778), and the main Max pm2 process name.
+
+3. Start the watchdog:
+
+```bash
+max start --profile watchdog
+```
+
+### Watchdog tools
+
+The watchdog has its own Copilot-powered AI session with these ops tools:
+
+| Tool | Description |
+|------|-------------|
+| `check_main_max` | Check if main Max is running (pm2 status + HTTP health) |
+| `restart_main_max` | Restart the main Max pm2 process |
+| `read_main_logs` | Read the last N lines of main Max's daemon log |
+| `server_health` | Report hostname, uptime, memory, disk, load average |
+| `run_shell` | Run a shell command (30s timeout, output capped) |
+| `update_main_max` | Stop main Max, update via npm, restart |
+
+The watchdog does **not** have workers, skills, or long-term memory — it's purpose-built for ops.
+
+### Dual-instance pm2 deployment
+
+```bash
+# Main Max
+pm2 start "max start" --name max
+
+# Watchdog
+pm2 start "max start --profile watchdog" --name max-watchdog
+
+pm2 save
+```
+
+### Recovery example
+
+```
+You → Watchdog: "is Max alive?"
+Watchdog: "Main Max is down. Last log: [ERROR] Copilot SDK auth expired."
+
+You → Watchdog: "show me the last 50 log lines"
+Watchdog: (tails ~/.max/daemon.log)
+
+You → Watchdog: "restart main Max"
+Watchdog: "Main Max is back online (pid 4521)."
+```
+
+### Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MAX_PROFILE` | _(unset)_ | Profile name; `watchdog` for the ops instance |
+| `MAX_HOME` | `~/.max` or `~/.max-<profile>` | Override the home directory |
+| `MAIN_MAX_PM2_NAME` | `max` | pm2 process name of the main Max instance |
+| `MAIN_MAX_HOME` | `~/.max` | Home directory of the main Max instance |
+| `MAIN_MAX_API_PORT` | `7777` | HTTP API port of the main Max instance |

package/dist/api/server.js

@@ -0,0 +1,297 @@
+import express from "express";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { randomBytes } from "crypto";
+import { sendToOrchestrator, getWorkers, cancelCurrentMessage, getLastRouteResult, invalidateSession } from "../copilot/orchestrator.js";
+import { sendPhoto, sendProactiveMessage } from "../telegram/bot.js";
+import { sendDiscordProactiveMessage, startDiscordThread } from "../discord/bot.js";
+import { config, persistModel } from "../config.js";
+import { getRouterConfig, updateRouterConfig } from "../copilot/router.js";
+import { searchMemories } from "../store/db.js";
+import { listSkills, removeSkill } from "../copilot/skills.js";
+import { restartDaemon } from "../daemon.js";
+import { API_TOKEN_PATH, ensureMaxHome } from "../paths.js";
+// Ensure token file exists (generate on first run)
+let apiToken = null;
+try {
+    if (existsSync(API_TOKEN_PATH)) {
+        apiToken = readFileSync(API_TOKEN_PATH, "utf-8").trim();
+    }
+    else {
+        ensureMaxHome();
+        apiToken = randomBytes(32).toString("hex");
+        writeFileSync(API_TOKEN_PATH, apiToken, { mode: 0o600 });
+    }
+}
+catch (err) {
+    console.error(`[auth] Failed to load/generate API token: ${err}`);
+    process.exit(1);
+}
+const app = express();
+app.use(express.json());
+// Handle malformed JSON bodies
+app.use((err, _req, res, next) => {
+    if (err.type === "entity.parse.failed") {
+        console.error("[max] API received malformed JSON body");
+        res.status(400).json({ error: "Invalid JSON" });
+        return;
+    }
+    next(err);
+});
+// Bearer token authentication middleware (skip /status health check)
+app.use((req, res, next) => {
+    if (!apiToken || req.path === "/status" || req.path === "/send-photo")
+        return next();
+    const auth = req.headers.authorization;
+    if (!auth || auth !== `Bearer ${apiToken}`) {
+        res.status(401).json({ error: "Unauthorized" });
+        return;
+    }
+    next();
+});
+// Active SSE connections
+const sseClients = new Map();
+let connectionCounter = 0;
+// Health check
+app.get("/status", (_req, res) => {
+    res.json({
+        status: "ok",
+        workers: Array.from(getWorkers().values()).map((w) => ({
+            name: w.name,
+            workingDir: w.workingDir,
+            status: w.status,
+        })),
+    });
+});
+// List worker sessions
+app.get("/sessions", (_req, res) => {
+    const workers = Array.from(getWorkers().values()).map((w) => ({
+        name: w.name,
+        workingDir: w.workingDir,
+        status: w.status,
+        lastOutput: w.lastOutput?.slice(0, 500),
+    }));
+    res.json(workers);
+});
+// SSE stream for real-time responses
+app.get("/stream", (req, res) => {
+    const connectionId = `tui-${++connectionCounter}`;
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    res.write(`data: ${JSON.stringify({ type: "connected", connectionId })}\n\n`);
+    sseClients.set(connectionId, res);
+    // Heartbeat to keep connection alive
+    const heartbeat = setInterval(() => {
+        res.write(`:ping\n\n`);
+    }, 20_000);
+    req.on("close", () => {
+        clearInterval(heartbeat);
+        sseClients.delete(connectionId);
+    });
+});
+// Send a message to the orchestrator
+app.post("/message", (req, res) => {
+    const { prompt, connectionId } = req.body;
+    if (!prompt || typeof prompt !== "string") {
+        res.status(400).json({ error: "Missing 'prompt' in request body" });
+        return;
+    }
+    if (!connectionId || !sseClients.has(connectionId)) {
+        res.status(400).json({ error: "Missing or invalid 'connectionId'. Connect to /stream first." });
+        return;
+    }
+    sendToOrchestrator(prompt, { type: "tui", connectionId }, (text, done) => {
+        const sseRes = sseClients.get(connectionId);
+        if (sseRes) {
+            const event = {
+                type: done ? "message" : "delta",
+                content: text,
+            };
+            if (done) {
+                const routeResult = getLastRouteResult();
+                if (routeResult) {
+                    event.route = {
+                        model: routeResult.model,
+                        routerMode: routeResult.routerMode,
+                        tier: routeResult.tier,
+                        ...(routeResult.overrideName ? { overrideName: routeResult.overrideName } : {}),
+                    };
+                }
+            }
+            sseRes.write(`data: ${JSON.stringify(event)}\n\n`);
+        }
+    });
+    res.json({ status: "queued" });
+});
+// Cancel the current in-flight message
+app.post("/cancel", async (_req, res) => {
+    const cancelled = await cancelCurrentMessage();
+    // Notify all SSE clients that the message was cancelled
+    for (const [, sseRes] of sseClients) {
+        sseRes.write(`data: ${JSON.stringify({ type: "cancelled" })}\n\n`);
+    }
+    res.json({ status: "ok", cancelled });
+});
+// Get or switch model
+app.get("/model", (_req, res) => {
+    res.json({ model: config.copilotModel });
+});
+app.post("/model", async (req, res) => {
+    const { model } = req.body;
+    if (!model || typeof model !== "string") {
+        res.status(400).json({ error: "Missing 'model' in request body" });
+        return;
+    }
+    // Validate against available models before persisting
+    try {
+        const { getClient } = await import("../copilot/client.js");
+        const client = await getClient();
+        const models = await client.listModels();
+        const match = models.find((m) => m.id === model);
+        if (!match) {
+            const suggestions = models
+                .filter((m) => m.id.includes(model) || m.id.toLowerCase().includes(model.toLowerCase()))
+                .map((m) => m.id);
+            const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+            res.status(400).json({ error: `Model '${model}' not found.${hint}` });
+            return;
+        }
+    }
+    catch {
+        // If we can't validate (client not ready), allow the switch — it'll fail on next message if wrong
+    }
+    const previous = config.copilotModel;
+    config.copilotModel = model;
+    persistModel(model);
+    invalidateSession();
+    res.json({ previous, current: model });
+});
+// Get auto-routing config
+app.get("/auto", (_req, res) => {
+    const routerConfig = getRouterConfig();
+    const lastRoute = getLastRouteResult();
+    res.json({
+        ...routerConfig,
+        currentModel: config.copilotModel,
+        lastRoute: lastRoute || null,
+    });
+});
+// Update auto-routing config
+app.post("/auto", (req, res) => {
+    const body = req.body;
+    const updated = updateRouterConfig(body);
+    console.log(`[max] Auto-routing ${updated.enabled ? "enabled" : "disabled"}`);
+    res.json(updated);
+});
+// List memories
+app.get("/memory", (_req, res) => {
+    const memories = searchMemories(undefined, undefined, 100);
+    res.json(memories);
+});
+// List skills
+app.get("/skills", (_req, res) => {
+    const skills = listSkills();
+    res.json(skills);
+});
+// Remove a local skill
+app.delete("/skills/:slug", (req, res) => {
+    const slug = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
+    const result = removeSkill(slug);
+    if (!result.ok) {
+        res.status(400).json({ error: result.message });
+    }
+    else {
+        res.json({ ok: true, message: result.message });
+    }
+});
+// Restart daemon
+app.post("/restart", (_req, res) => {
+    res.json({ status: "restarting" });
+    setTimeout(() => {
+        restartDaemon().catch((err) => {
+            console.error("[max] Restart failed:", err);
+        });
+    }, 500);
+});
+// Send a photo to Telegram (protected by bearer token auth middleware)
+app.post("/send-photo", async (req, res) => {
+    const { photo, caption } = req.body;
+    if (!photo || typeof photo !== "string") {
+        res.status(400).json({ error: "Missing 'photo' (file path or URL) in request body" });
+        return;
+    }
+    try {
+        await sendPhoto(photo, caption);
+        res.json({ status: "sent" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(500).json({ error: msg });
+    }
+});
+// Send a message to a channel (telegram or discord)
+app.post("/send-message", async (req, res) => {
+    const { channel, target, message } = req.body;
+    if (!message || typeof message !== "string") {
+        res.status(400).json({ error: "Missing 'message' in request body" });
+        return;
+    }
+    try {
+        if (channel === "discord") {
+            await sendDiscordProactiveMessage(message, target);
+        }
+        else {
+            await sendProactiveMessage(message);
+        }
+        res.json({ status: "sent" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(500).json({ error: msg });
+    }
+});
+// Start a Discord thread on a specific message
+app.post("/discord/start-thread", async (req, res) => {
+    const { channelId, messageId, name } = req.body;
+    if (!channelId || typeof channelId !== "string") {
+        res.status(400).json({ error: "Missing 'channelId' in request body" });
+        return;
+    }
+    if (!messageId || typeof messageId !== "string") {
+        res.status(400).json({ error: "Missing 'messageId' in request body" });
+        return;
+    }
+    try {
+        const threadId = await startDiscordThread(channelId, messageId, name);
+        res.json({ threadId });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(500).json({ error: msg });
+    }
+});
+export function startApiServer() {
+    return new Promise((resolve, reject) => {
+        const server = app.listen(config.apiPort, "127.0.0.1", () => {
+            console.log(`[max] HTTP API listening on http://127.0.0.1:${config.apiPort}`);
+            resolve();
+        });
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`Port ${config.apiPort} is already in use. Is another Max instance running?`));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}
+/** Broadcast a proactive message to all connected SSE clients (for background task completions). */
+export function broadcastToSSE(text) {
+    for (const [, res] of sseClients) {
+        res.write(`data: ${JSON.stringify({ type: "message", content: text })}\n\n`);
+    }
+}
+//# sourceMappingURL=server.js.map