grok-telegram-bot 2.0.0

package/src/grok/session-log.ts

@@ -0,0 +1,148 @@
+/**
+ * Bot-owned session log. Grok CLI keeps its own sessions in an internal SQLite
+ * store, but this bridge is the source of truth for the sessions IT drives: for
+ * each one it writes the SAME on-disk layout the original ACP bridge used, under
+ * the bot's data dir, so the session store, history parser and live-tail watcher
+ * all keep working without change:
+ *
+ *   <sessionsDir>/<id>.json    metadata (session_id, cwd, title, timestamps, …)
+ *   <sessionsDir>/<id>.jsonl   event log (Prompt / AssistantMessage / ToolUse)
+ *   <sessionsDir>/<id>.lock    { pid } while a turn is running (drives "active")
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("grok:session-log");
+
+interface SessionFile {
+  session_id: string;
+  cwd: string;
+  title: string;
+  created_at: string;
+  updated_at: string;
+  session_created_reason?: string;
+  /** The id the underlying `grok --session` uses (may differ from ours). */
+  grok_session_id?: string;
+  /** Model last used for this session (applied via `grok --model`). */
+  model?: string;
+}
+
+export class SessionLog {
+  constructor(private readonly dir: string) {}
+
+  private path(id: string, ext: string): string {
+    return join(this.dir, `${id}.${ext}`);
+  }
+
+  private ensureDir(): void {
+    try {
+      mkdirSync(this.dir, { recursive: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  /** Create the metadata file for a new session if it doesn't exist yet. */
+  create(id: string, cwd: string, reason = "user"): void {
+    this.ensureDir();
+    if (existsSync(this.path(id, "json"))) return;
+    const now = new Date().toISOString();
+    const meta: SessionFile = {
+      session_id: id,
+      cwd,
+      title: "(untitled)",
+      created_at: now,
+      updated_at: now,
+      session_created_reason: reason,
+    };
+    this.writeMeta(id, meta);
+  }
+
+  read(id: string): SessionFile | undefined {
+    try {
+      return JSON.parse(readFileSync(this.path(id, "json"), "utf-8")) as SessionFile;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private writeMeta(id: string, meta: SessionFile): void {
+    try {
+      this.ensureDir();
+      writeFileSync(this.path(id, "json"), JSON.stringify(meta, null, 2), "utf-8");
+    } catch (e) {
+      log.debug("writeMeta failed:", (e as Error).message);
+    }
+  }
+
+  /** Merge a partial update into the metadata file (touches updated_at). */
+  update(id: string, patch: Partial<SessionFile>): void {
+    const cur = this.read(id) ?? {
+      session_id: id,
+      cwd: patch.cwd ?? "",
+      title: "(untitled)",
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+    const next: SessionFile = { ...cur, ...patch, session_id: id, updated_at: new Date().toISOString() };
+    this.writeMeta(id, next);
+  }
+
+  grokIdFor(id: string): string | undefined {
+    return this.read(id)?.grok_session_id;
+  }
+
+  modelFor(id: string): string | undefined {
+    return this.read(id)?.model;
+  }
+
+  cwdFor(id: string): string | undefined {
+    return this.read(id)?.cwd;
+  }
+
+  // ── event log (history-compatible jsonl) ──────────────────────────────────
+
+  private append(id: string, kind: string, data: Record<string, unknown>): void {
+    try {
+      this.ensureDir();
+      const line = JSON.stringify({ kind, data: { ...data, meta: { timestamp: Date.now() } } });
+      appendFileSync(this.path(id, "jsonl"), line + "\n", "utf-8");
+    } catch (e) {
+      log.debug("append failed:", (e as Error).message);
+    }
+  }
+
+  logUser(id: string, text: string): void {
+    if (!text.trim()) return;
+    this.append(id, "Prompt", { content: [{ kind: "text", data: text }] });
+  }
+
+  logAssistant(id: string, text: string): void {
+    if (!text.trim()) return;
+    this.append(id, "AssistantMessage", { content: [{ kind: "text", data: text }] });
+  }
+
+  logTool(id: string, name: string, summary: string): void {
+    this.append(id, "ToolUse", { tool_name: name, content: [{ kind: "text", data: summary }] });
+  }
+
+  // ── lock (active detection) ───────────────────────────────────────────────
+
+  lock(id: string, pid: number): void {
+    try {
+      this.ensureDir();
+      writeFileSync(this.path(id, "lock"), JSON.stringify({ pid, started_at: new Date().toISOString() }), "utf-8");
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  unlock(id: string): void {
+    try {
+      rmSync(this.path(id, "lock"), { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}

package/src/grok/transport.ts

@@ -0,0 +1,51 @@
+/**
+ * Newline-delimited JSON-RPC framing over the ACP agent's stdio.
+ * Parses incoming lines and emits typed messages; writes outgoing messages.
+ * Used by the persistent `grok agent stdio` process.
+ */
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { EventEmitter } from "node:events";
+import type { JsonRpcMessage } from "./types.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("grok:transport");
+
+export class JsonRpcTransport extends EventEmitter {
+  private buffer = "";
+
+  constructor(private readonly proc: ChildProcessWithoutNullStreams) {
+    super();
+    proc.stdout.setEncoding("utf-8");
+    proc.stdout.on("data", (chunk: string) => this.onData(chunk));
+    proc.stderr.setEncoding("utf-8");
+    proc.stderr.on("data", (chunk: string) => {
+      const msg = chunk.trim();
+      if (msg) log.debug("[grok stderr]", msg.slice(0, 500));
+    });
+  }
+
+  private onData(chunk: string): void {
+    this.buffer += chunk;
+    let idx: number;
+    while ((idx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      let parsed: JsonRpcMessage;
+      try {
+        parsed = JSON.parse(line) as JsonRpcMessage;
+      } catch {
+        log.debug("non-JSON line ignored:", line.slice(0, 200));
+        continue;
+      }
+      this.emit("message", parsed);
+    }
+  }
+
+  send(msg: object): void {
+    if (!this.proc.stdin.writable) {
+      throw new Error("ACP process stdin is not writable");
+    }
+    this.proc.stdin.write(JSON.stringify(msg) + "\n");
+  }
+}

package/src/grok/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent Client Protocol (ACP) type definitions for the Grok Build CLI agent
+ * (`grok agent stdio`). Wire format: newline-delimited JSON-RPC 2.0 over stdio.
+ * @see https://agentclientprotocol.com  @see https://docs.x.ai/build/cli/headless-scripting
+ */
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+export type JsonRpcMessage = JsonRpcResponse & JsonRpcNotification & { method?: string };
+
+/** A content block in a prompt or message. */
+export interface ContentBlock {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  [k: string]: unknown;
+}
+
+/** One authentication method advertised by the agent in `initialize`. */
+export interface AuthMethod {
+  id: string; // e.g. "cached_token" | "xai.api_key"
+  name?: string;
+  description?: string;
+}
+
+export interface InitializeResult {
+  protocolVersion: number;
+  authMethods?: AuthMethod[];
+  agentCapabilities?: {
+    loadSession?: boolean;
+    promptCapabilities?: { image?: boolean };
+  };
+  agentInfo?: { name?: string; version?: string };
+}
+
+export interface NewSessionResult {
+  sessionId: string;
+}
+
+export interface PromptResult {
+  stopReason?: string; // e.g. "end_turn", "cancelled", "max_tokens"
+}
+
+/** session/update notification payload. */
+export interface SessionUpdate {
+  sessionUpdate:
+    | "agent_message_chunk"
+    | "agent_thought_chunk"
+    | "tool_call"
+    | "tool_call_update"
+    | "plan"
+    | "user_message_chunk"
+    | string;
+  content?: ContentBlock;
+  toolCallId?: string;
+  title?: string;
+  kind?: string; // "read" | "edit" | "execute" | "search" | ...
+  status?: "pending" | "in_progress" | "completed" | "failed" | string;
+  rawInput?: Record<string, unknown>;
+  content_blocks?: ToolCallContent[];
+  [k: string]: unknown;
+}
+
+/** A piece of tool-call content (text, diff, etc.). */
+export interface ToolCallContent {
+  type: "content" | "diff" | string;
+  path?: string;
+  oldText?: string | null;
+  newText?: string;
+  content?: ContentBlock;
+  [k: string]: unknown;
+}
+
+export interface SessionNotificationParams {
+  sessionId: string;
+  update: SessionUpdate;
+}
+
+/** Permission request from the agent (server -> client) — ACP "ask" mode. */
+export interface RequestPermissionParams {
+  sessionId: string;
+  toolCall?: { toolCallId?: string; title?: string; kind?: string; rawInput?: Record<string, unknown> };
+  options: Array<{ optionId: string; name: string; kind?: string }>;
+}
+
+export type PermissionOutcome =
+  | { outcome: { outcome: "selected"; optionId: string } }
+  | { outcome: { outcome: "cancelled" } };
+
+/** One subagent ("crew" member) as reported by the agent, if it emits them. */
+export interface SubagentInfo {
+  sessionId: string;
+  sessionName?: string;
+  agentName?: string;
+  role?: string;
+  initialQuery?: string;
+  status?: { type?: string; message?: string };
+  group?: string;
+  dependsOn?: string[];
+  hasLoop?: boolean;
+  loopIteration?: number;
+  loopMaxIterations?: number;
+  createdAtMs?: number;
+}
+
+export interface PendingStage {
+  name?: string;
+  role?: string;
+  agentName?: string;
+  dependsOn?: string[];
+  [k: string]: unknown;
+}
+
+export interface SubagentListUpdate {
+  subagents?: SubagentInfo[];
+  pendingStages?: PendingStage[];
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Grok Telegram Bot — entry point.
+ * Starts the Grok ACP bridge (`grok agent stdio`), the Telegram bot, and wires
+ * graceful shutdown between them.
+ */
+import { GrokClient } from "./grok/client.js";
+import { createBot } from "./bot/bot.js";
+import { CANONICAL_DIR, loadConfig } from "./config.js";
+import { InstanceLock } from "./app/instance-lock.js";
+import { join } from "node:path";
+import { createLogger, enableFileLogging, setLogLevel } from "./logger.js";
+
+async function main(): Promise<void> {
+  process.stdout.write("\u{1F916} Grok Telegram Bot — starting…\n");
+
+  const cfg = loadConfig();
+  setLogLevel(cfg.logLevel);
+  enableFileLogging(cfg.logFile);
+  const log = createLogger("main");
+
+  // Single-instance guard: kill any ghost/duplicate already polling this token.
+  const lock = new InstanceLock(cfg.token, join(CANONICAL_DIR, "locks"), process.env.GROK_TG_SUPERVISED === "1");
+  if (cfg.singleInstance && !(await lock.acquire())) {
+    process.stdout.write(
+      "\u26D4 Another Grok Telegram Bot is already running for this token (a background service). Use `grok-tg restart`, or `grok-tg stop` first.\n",
+    );
+    process.exit(0);
+  }
+
+  log.info("starting Grok Telegram Bot");
+  log.info(`workspace: ${cfg.workspace}`);
+  log.info(`grok:      ${cfg.grokCliPath}`);
+  log.info(`sessions:  ${cfg.sessionsDir}`);
+  log.info(`log file:  ${cfg.logFile}`);
+
+  const grok = new GrokClient({
+    grokCliPath: cfg.grokCliPath,
+    workspace: cfg.workspace,
+    sessionsDir: cfg.sessionsDir,
+    trustAllTools: cfg.trustAllTools,
+    apiKey: cfg.grokApiKey,
+    model: cfg.grokModel,
+    autoRestart: cfg.grokAutoRestart,
+    promptIdleTimeoutMs: cfg.promptIdleMs,
+  });
+
+  await grok.start();
+  const { bot, registry, scheduler, updater } = await createBot(cfg, grok);
+  scheduler.start();
+  await updater.start();
+
+  let shuttingDown = false;
+  const shutdown = (code: number): void => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log.info("shutting down…");
+    scheduler.stop();
+    updater.stop();
+    registry.disposeAll();
+    void bot.stop().catch(() => {});
+    grok.stop();
+    lock.release();
+    setTimeout(() => process.exit(code), 500);
+  };
+
+  grok.on("restarted", () => log.info("Grok bridge re-bound; sessions continue on next message."));
+
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+  process.on("uncaughtException", (err) => log.error("uncaughtException:", err));
+  process.on("unhandledRejection", (err) => log.error("unhandledRejection:", err));
+
+  await bot.start({
+    onStart: (info) => {
+      log.info(`bot online as @${info.username}`);
+      process.stdout.write(`\u2705 Online as @${info.username}. Send it a message on Telegram.\n`);
+    },
+  });
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/logger.ts

@@ -0,0 +1,78 @@
+/**
+ * Tiny leveled logger with timestamps and optional file output (for daemon
+ * mode, where stdout may not be captured).
+ */
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 } as const;
+export type LogLevel = keyof typeof LEVELS;
+
+let threshold: number = LEVELS.info;
+let filePath: string | undefined;
+
+const MAX_LOG_BYTES = 5 * 1024 * 1024; // rotate when the log file exceeds 5 MB
+
+export function setLogLevel(level: string | undefined): void {
+  const lvl = (level || "info").toLowerCase() as LogLevel;
+  threshold = LEVELS[lvl] ?? LEVELS.info;
+}
+
+/** Mirror all log output to a file (rotated once at startup if too large). */
+export function enableFileLogging(path: string): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+      if (statSync(path).size > MAX_LOG_BYTES) renameSync(path, `${path}.old`);
+    } catch {
+      /* no existing file */
+    }
+    filePath = path;
+  } catch {
+    filePath = undefined;
+  }
+}
+
+function ts(): string {
+  return new Date().toISOString().replace("T", " ").replace("Z", "");
+}
+
+function emit(level: LogLevel, scope: string, args: unknown[]): void {
+  if (LEVELS[level] < threshold) return;
+  const tag = `${ts()} ${level.toUpperCase().padEnd(5)} [${scope}]`;
+  const fn = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+  fn(tag, ...args);
+  if (filePath) {
+    try {
+      appendFileSync(filePath, `${tag} ${args.map(stringify).join(" ")}\n`);
+    } catch {
+      /* non-fatal */
+    }
+  }
+}
+
+function stringify(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (v instanceof Error) return v.stack || v.message;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+export interface Logger {
+  debug: (...a: unknown[]) => void;
+  info: (...a: unknown[]) => void;
+  warn: (...a: unknown[]) => void;
+  error: (...a: unknown[]) => void;
+}
+
+export function createLogger(scope: string): Logger {
+  return {
+    debug: (...a) => emit("debug", scope, a),
+    info: (...a) => emit("info", scope, a),
+    warn: (...a) => emit("warn", scope, a),
+    error: (...a) => emit("error", scope, a),
+  };
+}

package/src/mcp/config.ts

@@ -0,0 +1,120 @@
+/**
+ * MCP config store — reads and edits Grok CLI's MCP server definitions.
+ *
+ * Grok keeps them in two places:
+ *   • global    → `~/.grok/user-settings.json` under `mcp.servers` (array), and
+ *   • workspace → `<cwd>/.grok/settings.json` under `mcpServers` (object map).
+ *
+ * We normalize both shapes into a flat list. Edits are surgical: parse, flip a
+ * single `disabled` flag on one entry, write back with 2-space indentation.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createLogger } from "../logger.js";
+import { detailOf, type McpScope, type McpServer, type McpServerConfig, transportOf } from "./types.js";
+
+const log = createLogger("mcp:config");
+
+/** Absolute path of the global settings file (Grok user settings). */
+export function globalMcpPath(): string {
+  return join(homedir(), ".grok", "user-settings.json");
+}
+
+/** Absolute path of a workspace settings file for a given project directory. */
+export function workspaceMcpPath(cwd: string): string {
+  return join(cwd, ".grok", "settings.json");
+}
+
+interface RawFile {
+  mcpServers?: Record<string, McpServerConfig>;
+  mcp?: { servers?: Array<McpServerConfig & { name?: string }> };
+  servers?: Array<McpServerConfig & { name?: string }>;
+  [k: string]: unknown;
+}
+
+function readJson(path: string): RawFile | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as RawFile;
+  } catch (e) {
+    log.warn(`cannot parse ${path}: ${(e as Error).message}`);
+    return undefined;
+  }
+}
+
+/** Extract normalized servers from a file (supports object-map and array). */
+function serversFrom(path: string, scope: McpScope): McpServer[] {
+  const file = readJson(path);
+  if (!file) return [];
+  const out: McpServer[] = [];
+  const push = (name: string, config: McpServerConfig): void => {
+    out.push({
+      name,
+      scope,
+      configPath: path,
+      disabled: config?.disabled === true,
+      transport: transportOf(config ?? {}),
+      detail: detailOf(config ?? {}),
+      config: config ?? {},
+    });
+  };
+  if (file.mcpServers && typeof file.mcpServers === "object") {
+    for (const [name, config] of Object.entries(file.mcpServers)) push(name, config);
+  }
+  const arr = file.mcp?.servers ?? file.servers;
+  if (Array.isArray(arr)) {
+    for (const entry of arr) if (entry?.name) push(entry.name, entry);
+  }
+  return out;
+}
+
+/** List all configured MCP servers (workspace entries shadow global). */
+export function listMcpServers(cwd?: string): McpServer[] {
+  const byName = new Map<string, McpServer>();
+  for (const s of serversFrom(globalMcpPath(), "global")) byName.set(s.name, s);
+  if (cwd) {
+    for (const s of serversFrom(workspaceMcpPath(cwd), "workspace")) byName.set(s.name, s);
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+}
+
+export function findMcpServer(name: string, cwd?: string): McpServer | undefined {
+  return listMcpServers(cwd).find((s) => s.name === name);
+}
+
+export interface ToggleResult {
+  ok: boolean;
+  disabled?: boolean;
+  error?: string;
+}
+
+/** Set the `disabled` flag for a server in its own config file. */
+export function setMcpDisabled(server: McpServer, disabled: boolean): ToggleResult {
+  const file = readJson(server.configPath);
+  if (!file) return { ok: false, error: `cannot read ${server.configPath}` };
+
+  const applyMap = (map?: Record<string, McpServerConfig>): boolean => {
+    if (!map || !map[server.name]) return false;
+    const entry = map[server.name]!;
+    if (disabled) entry.disabled = true;
+    else delete entry.disabled;
+    return true;
+  };
+  const applyArr = (arr?: Array<McpServerConfig & { name?: string }>): boolean => {
+    const entry = arr?.find((e) => e.name === server.name);
+    if (!entry) return false;
+    if (disabled) entry.disabled = true;
+    else delete entry.disabled;
+    return true;
+  };
+
+  const changed = applyMap(file.mcpServers) || applyArr(file.mcp?.servers) || applyArr(file.servers);
+  if (!changed) return { ok: false, error: `server "${server.name}" not found in ${server.configPath}` };
+  try {
+    writeFileSync(server.configPath, JSON.stringify(file, null, 2) + "\n", "utf-8");
+    return { ok: true, disabled };
+  } catch (e) {
+    return { ok: false, error: (e as Error).message };
+  }
+}