@c4t4/heyamigo 0.10.1 → 0.10.3

package/README.md

@@ -1,12 +1,16 @@
+<p align="center">
+  <img src="assets/heyamigo-premium-clean.jpg" alt="Heyamigo" width="100%">
+</p>
+
 # heyamigo
 
-A WhatsApp-resident assistant. Claude or Codex under the hood, durable SQLite queues, per-sender timezone scheduling, two-track architecture so browser work never blocks the chat.
+A chat-resident assistant for WhatsApp and Telegram. Claude, Codex, or Grok under the hood, durable SQLite queues, per-sender timezone scheduling, two-track architecture so browser work never blocks the chat.
 
 ```
-WhatsApp ─► inbound ─► chat workers ─► outbound ─► WhatsApp
-                          │                ▲
-                          ├──────► async / browser ─┤
-                          └──────► memory_writes ───┘
+WhatsApp / Telegram ─► inbound ─► chat workers ─► outbound ─► WhatsApp / Telegram
+                                     │                ▲
+                                     ├──────► async / browser ─┤
+                                     └──────► memory_writes ───┘
 ```
 
 ## What it does
@@ -14,7 +18,7 @@ WhatsApp ─► inbound ─► chat workers ─► outbound ─► WhatsApp
 - **Long-term memory per person, per chat, per topic.** Files on disk. The agent decides what's worth keeping; background workers consolidate while you're not chatting.
 - **A relevance watchlist.** Open loops the agent tracks on your behalf — questions you'd forget, things you're waiting on — surfaced naturally when the moment matches. Built like external working memory for the user.
 - **Scheduling in the sender's timezone.** Natural language → `[REMIND: 2026-05-26 09:00 — ...]` or `[CRON: 0 9 * * 1 PROMPT — ...]`. Fires at the user's wall-clock 9am, not the server's. Cron variants: deliver text, run AI, kick off async work, or drive a browser.
-- **A real Chrome.** Browser delegation via `[ASYNC-BROWSER: ...]` to a parallel Claude session on a shared logged-in Chrome over CDP. TikTok, Instagram, anywhere the owner is logged in. SSH-tunneled noVNC for setup.
+- **A real Chrome.** Browser delegation via `[ASYNC-BROWSER: ...]` to a parallel provider session on a shared logged-in Chrome over CDP. TikTok, Instagram, anywhere the owner is logged in. SSH-tunneled noVNC for setup.
 - **Per-reply footer with confirmation tags.** Every side effect from the turn is visible: `_9.9s · 465k↑ 169↓ · +remind · +thread-new · +digest_`. No guessing whether a schedule actually got created.
 - **Default-deny proactive messaging.** Groups stay silent unless explicitly opted in. Per-role token quotas, file-size caps, tool restrictions.
 
@@ -31,7 +35,12 @@ npx @c4t4/heyamigo start                # background, auto-restart
 npx @c4t4/heyamigo logs                 # tail
 ```
 
-Codex instead of Claude: install `@openai/codex` and set `ai.provider: "codex"` in `config/config.json`.
+Telegram is optional. Create a bot with BotFather, set `telegram.enabled: true` and `telegram.botToken` in `config/config.json`, then allow users/groups in `config/access.json`. Telegram user keys use `tg_<user_id>`; Telegram group entries use addresses like `tg:group:-1001234567890`.
+
+Other providers:
+
+- Codex: install `@openai/codex` and set `ai.provider: "codex"` in `config/config.json`.
+- Grok Build: install with `curl -fsSL https://x.ai/cli/install.sh | bash`, run `grok login`, and set `ai.provider: "grok"`.
 
 ## In-chat commands
 
@@ -60,7 +69,7 @@ Codex instead of Claude: install `@openai/codex` and set `ai.provider: "codex"`
 
 ## Where to run it
 
-A VPS (Hetzner, DO) at ~$5/mo is the path of least resistance. Home server or Raspberry Pi also fine. Needs Node 18+, a persistent filesystem, and one outbound WebSocket to WhatsApp. Not serverless-compatible.
+A VPS (Hetzner, DO) at ~$5/mo is the path of least resistance. Home server or Raspberry Pi also fine. Needs Node 18+, a persistent filesystem, and outbound access to the enabled chat channels. Not serverless-compatible.
 
 ## Tracking memory with git
 

package/config/access.example.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Access rules. Copy this to access.json and customize. Groups auto-discover with mode=off when the bot sees them.",
+  "_readme": "Access rules. Copy this to access.json and customize. Groups auto-discover with mode=off when the bot sees them. WhatsApp users are phone numbers; Telegram users are tg_<user_id>.",
 
   "_limits_readme": "maxFileBytes caps the size of media/documents sent to Claude (null = unlimited). dailyTokenLimit caps Claude tokens (input+output) per user per day in the owner's timezone (null = unlimited). The bot owner is always unlimited regardless of role.",
 
@@ -45,6 +45,7 @@
   "users": {
     "17861234567": { "role": "admin", "name": "Alice" },
     "14155559999": { "role": "admin", "name": "Bob" },
+    "tg_123456789": { "role": "admin", "name": "Alice on Telegram" },
     "491701234567": { "role": "user", "name": "Carlos" },
     "5511987654321": { "role": "user", "name": "Davi" }
   },
@@ -71,6 +72,14 @@
       "allowedSenders": ["17861234567", "491701234567"],
       "proactive": true
     },
+    {
+      "_note": "Telegram group. Chat id is the address external id; senders use tg_<user_id>.",
+      "jid": "tg:group:-1001234567890",
+      "name": "Telegram Team",
+      "mode": "active",
+      "allowedSenders": ["tg_123456789"],
+      "proactive": false
+    },
     {
       "_note": "Silent group: stores messages but never responds",
       "jid": "120363zzzzz@g.us",
@@ -88,10 +97,11 @@
   ],
 
   "dms": {
-    "_readme": "Matched by chat partner number, not sender. Owner messages in DMs are always silent.",
+    "_readme": "Matched by chat partner number/key, not sender. Telegram DMs use tg_<user_id>. Owner messages in WhatsApp DMs are always silent.",
     "defaultMode": "off",
     "allowed": [
       { "_note": "friend can DM the bot, and bot can proactively message them", "number": "491701234567", "mode": "active", "proactive": true },
+      { "_note": "Telegram friend can DM the bot", "number": "tg_123456789", "mode": "active", "proactive": true },
       { "_note": "colleague, store messages but don't respond", "number": "5511987654321", "mode": "silent", "proactive": false }
     ]
   }

package/config/config.example.json

@@ -1,9 +1,16 @@
 {
   "whatsapp": {
+    "enabled": true,
     "authDir": "./storage/auth",
     "browserName": "WhatsApp Bot"
   },
 
+  "telegram": {
+    "enabled": false,
+    "botToken": "",
+    "pollIntervalMs": 1000
+  },
+
   "owner": {
     "number": "",
     "treatAsAllowedEverywhere": true,
@@ -11,7 +18,7 @@
   },
 
   "triggers": {
-    "aliases": ["heyamigo", "amigo", "claude", "clawd"],
+    "aliases": ["heyamigo", "amigo", "claude", "clawd", "grok", "codex", "xai"],
     "groupMode": "mention",
     "dmMode": "mention",
     "replyToBotCounts": true
@@ -37,11 +44,20 @@
   },
 
   "codex": {
+    "contextWindow": 200000,
     "yolo": true,
     "skipGitRepoCheck": true,
     "extraArgs": []
   },
 
+  "grok": {
+    "bin": "grok",
+    "contextWindow": 1000000,
+    "alwaysApprove": true,
+    "memory": false,
+    "extraArgs": []
+  },
+
   "bootstrap": {
     "historyDepth": 50,
     "includeHistory": true,

package/config/memory-instructions.md

@@ -205,7 +205,7 @@ Cost tracked per cron — `/crons` shows fire count + tokens. Omitting variant d
 
 ### Cross-chat: `[SEND-TEXT: address=wa:dm:<n>@s.whatsapp.net body="..."]`
 
-Rare; usually owner-only.
+Rare; usually owner-only. Telegram targets use the same address grammar, e.g. `tg:dm:123456789` or `tg:group:-1001234567890`.
 
 ### Rules
 

package/config/personalities/casual.md

@@ -1,6 +1,6 @@
 # Personality: Casual
 
-You answer WhatsApp messages for the account owner. Act like a smart friend chatting over coffee.
+You answer chat messages for the account owner. Act like a smart friend chatting over coffee.
 
 ## Voice
 

package/config/personalities/professional.md

@@ -1,6 +1,6 @@
 # Personality: Professional
 
-You answer WhatsApp messages for the account owner in business and professional contexts.
+You answer chat messages for the account owner in business and professional contexts.
 
 ## Voice
 

package/config/personalities/sharp.md

@@ -1,6 +1,6 @@
 # Personality: Sharp (default)
 
-You answer WhatsApp messages for the account owner. Not customer service, not marketing copy. A conversational peer: sharp, direct, useful.
+You answer chat messages for the account owner. Not customer service, not marketing copy. A conversational peer: sharp, direct, useful.
 
 ## Voice
 
@@ -32,6 +32,6 @@ See the layers. Most questions have a surface answer and a real answer — give
 
 The default chatbot failure mode. Skip validation openers ("great question", "good point", "absolutely", "that makes sense") — just answer. Disagree directly when you disagree; softening bad ideas wastes their time. Don't reflexively offer more help. Don't apologize for nothing. Don't flatter — engage with substance instead of complimenting it.
 
-## WhatsApp
+## Chat
 
 Short replies, plain text. No markdown headers, bold, or bullet lists (renders poorly). Don't dominate groups. Never break frame with "As an AI assistant..." or similar.

package/dist/ai/claude.js

@@ -202,6 +202,7 @@ export async function runClaudeTask(params) {
 }
 export const claudeProvider = {
     name: 'claude',
+    contextWindow: config.claude.contextWindow,
     // Claude CLI's `result` event reports per-turn usage (just the
     // tokens consumed by this single resume invocation).
     usageReportingMode: 'per-turn',

package/dist/ai/codex.js

@@ -267,6 +267,7 @@ async function askCodex(params) {
 }
 export const codexProvider = {
     name: 'codex',
+    contextWindow: config.codex.contextWindow,
     // Codex CLI's `turn.completed.usage` reports cumulative totals for
     // the entire resume thread, not just this one turn. Worker uses
     // this flag to delta-math each turn before display so the context

package/dist/ai/grok.js

@@ -0,0 +1,310 @@
+// Grok Build CLI provider. Maps the neutral AiProvider contract onto
+// `grok` headless mode (`--prompt-file` + `--output-format json`).
+//
+// Grok Build is a local coding-agent CLI, not a plain API model. It already
+// knows how to inspect repo config, use MCP, run shell tools, and resume
+// sessions. This adapter keeps the same heyamigo contract Claude/Codex use:
+// one prompt in, one reply out, opaque provider-native session ids.
+import { mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from 'fs';
+import { tmpdir } from 'os';
+import { join, resolve } from 'path';
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import { logPrompt } from '../promptlog.js';
+import { runClaude, TIMEOUT_MS } from './spawn.js';
+let cachedSystemPrompt = null;
+function systemPrompt() {
+    if (cachedSystemPrompt !== null)
+        return cachedSystemPrompt;
+    const personality = readFileSync(resolve(process.cwd(), config.claude.personalityFile), 'utf-8');
+    let memoryInstructions = '';
+    try {
+        memoryInstructions = readFileSync(resolve(process.cwd(), config.memory.instructionsFile), 'utf-8');
+    }
+    catch {
+        // memory instructions optional
+    }
+    cachedSystemPrompt = memoryInstructions
+        ? `${personality}\n\n---\n\n${memoryInstructions}`
+        : personality;
+    return cachedSystemPrompt;
+}
+function reloadSystemPrompt() {
+    cachedSystemPrompt = null;
+}
+function permissionModeFor(mode) {
+    switch (mode) {
+        case 'read-only':
+            return 'plan';
+        case 'auto':
+            return 'acceptEdits';
+        case 'full':
+            return 'bypassPermissions';
+    }
+}
+function laneTimeoutMs(lane) {
+    return TIMEOUT_MS[lane];
+}
+function hasWebTool(tools) {
+    return tools.some((tool) => /web(fetch|search)?/i.test(tool));
+}
+function buildArgs(params) {
+    const cfg = config.grok;
+    let prompt = params.prompt;
+    const args = [
+        '--cwd',
+        process.cwd(),
+        '--output-format',
+        'json',
+        '--permission-mode',
+        permissionModeFor(params.mode),
+        '--verbatim',
+    ];
+    if (cfg.model)
+        args.push('-m', cfg.model);
+    if (params.mode === 'read-only') {
+        args.push('--sandbox', 'read-only');
+    }
+    else if (cfg.alwaysApprove) {
+        args.push('--always-approve');
+    }
+    if (cfg.memory) {
+        args.push('--experimental-memory');
+    }
+    else {
+        args.push('--no-memory');
+    }
+    if (params.allowedTools && params.allowedTools !== 'all') {
+        if (params.allowedTools.length > 0) {
+            args.push('--allow', params.allowedTools.join(','));
+        }
+        if (!hasWebTool(params.allowedTools)) {
+            args.push('--disable-web-search');
+        }
+    }
+    for (const extra of cfg.extraArgs)
+        args.push(extra);
+    if (params.sessionId) {
+        args.push('--resume', params.sessionId);
+    }
+    else if (params.includeSystemPrompt) {
+        // Keep this in the prompt file instead of argv so large personalities and
+        // memory instructions don't hit ARG_MAX.
+        prompt = `${systemPrompt()}\n\n---\n\n${prompt}`;
+    }
+    args.push('--prompt-file', params.promptFile);
+    return { args, prompt };
+}
+function usageFrom(raw) {
+    const usage = raw.usage;
+    return {
+        inputTokens: usage?.inputTokens ?? usage?.input_tokens ?? usage?.prompt_tokens ?? 0,
+        cacheReadTokens: usage?.cacheReadTokens ?? usage?.cached_input_tokens ?? 0,
+        cacheCreationTokens: usage?.cacheCreationTokens ?? 0,
+        outputTokens: usage?.outputTokens ?? usage?.output_tokens ?? usage?.completion_tokens ?? 0,
+        numTurns: 0,
+    };
+}
+function textFrom(raw) {
+    for (const value of [
+        raw.text,
+        raw.output_text,
+        raw.result,
+        raw.reply,
+        raw.message,
+    ]) {
+        if (typeof value === 'string')
+            return value;
+    }
+    return null;
+}
+function parseJsonObject(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // Grok may emit log lines before/after JSON on some failures. Try the
+        // broadest JSON-looking slice before giving up.
+        const first = trimmed.indexOf('{');
+        const last = trimmed.lastIndexOf('}');
+        if (first >= 0 && last > first) {
+            try {
+                return JSON.parse(trimmed.slice(first, last + 1));
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+function parseStreamingJson(stdout) {
+    let reply = '';
+    let sessionId;
+    let error = null;
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (ev.type === 'text' && typeof ev.data === 'string') {
+            reply += ev.data;
+        }
+        else if (ev.type === 'end') {
+            const id = ev.sessionId ?? ev.session_id;
+            if (typeof id === 'string')
+                sessionId = id;
+        }
+        else if (ev.type === 'error') {
+            error = textFrom(ev) ?? (typeof ev.data === 'string' ? ev.data : null);
+        }
+    }
+    if (error)
+        throw new Error(`grok returned error: ${error}`);
+    if (!reply)
+        return null;
+    return {
+        reply: reply.trim(),
+        sessionId,
+        usage: {
+            inputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            outputTokens: 0,
+            numTurns: 0,
+        },
+    };
+}
+function parseGrokOutput(stdout) {
+    const raw = parseJsonObject(stdout);
+    if (raw) {
+        if (raw.type === 'error') {
+            throw new Error(`grok returned error: ${textFrom(raw) ?? stdout.slice(0, 500)}`);
+        }
+        const reply = textFrom(raw);
+        if (reply !== null) {
+            const id = raw.sessionId ?? raw.session_id;
+            return {
+                reply: reply.trim(),
+                sessionId: typeof id === 'string' ? id : undefined,
+                usage: usageFrom(raw),
+            };
+        }
+    }
+    return parseStreamingJson(stdout);
+}
+function createPromptFile(prompt) {
+    const dir = mkdtempSync(join(tmpdir(), 'heyamigo-grok-'));
+    const path = join(dir, 'prompt.txt');
+    writeFileSync(path, prompt, 'utf-8');
+    return { dir, path };
+}
+function removePromptFile(tmp) {
+    try {
+        unlinkSync(tmp.path);
+    }
+    catch { }
+    try {
+        rmSync(tmp.dir, { recursive: true, force: true });
+    }
+    catch { }
+}
+async function runGrokTask(params) {
+    const tmp = createPromptFile(params.input);
+    let args = [];
+    let promptForFile = params.input;
+    try {
+        const built = buildArgs({
+            mode: params.mode,
+            sessionId: params.sessionId,
+            includeSystemPrompt: params.includeSystemPrompt,
+            prompt: params.input,
+            allowedTools: params.allowedTools,
+            promptFile: tmp.path,
+        });
+        args = built.args;
+        promptForFile = built.prompt;
+        writeFileSync(tmp.path, promptForFile, 'utf-8');
+        logger.info({
+            caller: params.caller,
+            resume: !!params.sessionId,
+            argv: args,
+            promptChars: promptForFile.length,
+        }, 'spawning grok');
+        const { stdout, stderr, durationMs } = await runClaude({
+            args,
+            input: '',
+            timeoutMs: laneTimeoutMs(params.lane),
+            caller: params.caller,
+            bin: config.grok.bin,
+        });
+        const startedAt = Date.now() - durationMs;
+        const parsed = parseGrokOutput(stdout);
+        if (!parsed) {
+            throw new Error(`grok produced no parseable result; stdout: ${stdout.slice(0, 500)}`);
+        }
+        void logPrompt({
+            ts: Math.floor(startedAt / 1000),
+            caller: params.caller,
+            args,
+            input: params.input,
+            output: parsed.reply,
+            sessionId: parsed.sessionId,
+            usage: parsed.usage,
+            durationMs,
+            stderr,
+        });
+        return parsed;
+    }
+    finally {
+        removePromptFile(tmp);
+    }
+}
+async function askGrok(params) {
+    const result = await runGrokTask({
+        input: params.input,
+        caller: 'worker',
+        mode: 'auto',
+        lane: 'main',
+        sessionId: params.sessionId,
+        includeSystemPrompt: true,
+        allowedTools: params.allowedTools,
+        addDirs: [
+            config.memory.dir,
+            config.storage.mediaDir,
+        ],
+    });
+    if (!result.sessionId) {
+        throw new Error('grok ask: response missing session id');
+    }
+    return {
+        reply: result.reply,
+        sessionId: result.sessionId,
+        usage: result.usage ?? {
+            inputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+            outputTokens: 0,
+            numTurns: 0,
+        },
+    };
+}
+export const grokProvider = {
+    name: 'grok',
+    contextWindow: config.grok.contextWindow,
+    // The current Grok Build headless JSON output does not expose reliable
+    // per-turn token usage, so treat any reported counts as this invocation only.
+    usageReportingMode: 'per-turn',
+    ask: askGrok,
+    runTask: runGrokTask,
+    reloadSystemPrompt,
+};

package/dist/ai/provider.js

@@ -1,9 +1,9 @@
 // Provider abstraction for the user-facing chat ask path. Lets the worker
-// route conversation turns to either Claude or Codex (or any future CLI)
+// route conversation turns to Claude, Codex, Grok, or any future CLI
 // without knowing the wire details.
 //
-// Scope: covers the interactive worker call (one turn in, one turn out, with
-// resumable session ids and per-role tool gating). Memory digests, async
-// tasks, and the journal observers stay on `runClaude` directly — they're
-// Claude-specific batch pipelines and not in this interface.
+// Scope: covers the interactive worker call and general provider-backed agent
+// tasks (memory digests, async/background work, browser tasks). A few legacy
+// utilities may still call a specific CLI directly, but runtime work should
+// flow through this interface.
 export {};

package/dist/ai/providers.js

@@ -1,9 +1,11 @@
 import { config } from '../config.js';
 import { claudeProvider } from './claude.js';
 import { codexProvider } from './codex.js';
+import { grokProvider } from './grok.js';
 const REGISTRY = {
     claude: claudeProvider,
     codex: codexProvider,
+    grok: grokProvider,
 };
 // Resolve the active provider. Defaults to claude if no override is set in
 // config; pass an explicit name to force one (useful for per-role routing

package/dist/ai/sessions.js

@@ -34,7 +34,11 @@ function load() {
                     ('codex' in obj &&
                         typeof obj.codex === 'object' &&
                         obj.codex !== null &&
-                        'sessionId' in obj.codex);
+                        'sessionId' in obj.codex) ||
+                    ('grok' in obj &&
+                        typeof obj.grok === 'object' &&
+                        obj.grok !== null &&
+                        'sessionId' in obj.grok);
                 if (isNamespaced) {
                     out[jid] = obj;
                 }

package/dist/boot.js

@@ -3,9 +3,12 @@
 // startup order — there used to be two parallel main() functions that
 // drifted; this prevents that.
 import { setBaileysSocket } from './channels/index.js';
+import { telegramRuntime } from './channels/telegram.js';
+import { config } from './config.js';
 import { closeDb, initDb } from './db/index.js';
 import { syncIdentitiesFromAccess } from './db/identity-sync.js';
 import { attachIncoming } from './gateway/incoming.js';
+import { processIncomingMessage } from './gateway/ingest.js';
 import { logger } from './logger.js';
 import { startScheduler } from './memory/scheduler.js';
 import { startBrowserWorkers, stopBrowserWorkers } from './queue/browser-worker.js';
@@ -35,6 +38,7 @@ export async function bootBot() {
             stopBrowserWorkers();
             stopSenderWorker();
             stopMemoryWorker();
+            void telegramRuntime.stop();
             stopOrchestrator();
             closeDb();
         },
@@ -47,12 +51,17 @@ export async function bootBot() {
     startBrowserWorkers();
     startChatWorkers();
     startScheduler();
-    await startSocket((sock) => {
-        attachIncoming(sock);
-        // Point the Baileys adapter at the live socket. Called on each
-        // reconnect with a fresh sock; the adapter just keeps the latest.
-        setBaileysSocket(sock);
-    });
+    if (config.telegram.enabled) {
+        await telegramRuntime.start(processIncomingMessage);
+    }
+    if (config.whatsapp.enabled !== false) {
+        await startSocket((sock) => {
+            attachIncoming(sock);
+            // Point the Baileys adapter at the live socket. Called on each
+            // reconnect with a fresh sock; the adapter just keeps the latest.
+            setBaileysSocket(sock);
+        });
+    }
 }
 // Install once. Both signals trigger the same graceful drain:
 // orchestrator picks up the shutdown control row, waits for busy

package/dist/channels/index.js

@@ -1,9 +1,10 @@
 // Channel adapter registry. Sender worker calls getChannelAdapter(name)
 // keyed off the parsed address.channel.
 import { baileysAdapter } from './baileys.js';
+import { telegramAdapter } from './telegram.js';
 const REGISTRY = {
     wa: baileysAdapter,
-    // tg: telegramAdapter, // Phase 8
+    tg: telegramAdapter,
 };
 export function getChannelAdapter(channel) {
     const adapter = REGISTRY[channel];

package/dist/channels/runtime.js

@@ -0,0 +1 @@
+export {};