grok-telegram-bot 2.6.0 → 2.7.0

package/src/bot/plan-exit-service.ts

@@ -0,0 +1,169 @@
+/**
+ * Interactive plan-mode approval. Grok's exit_plan_mode reverse request
+ * becomes Approve / Request changes / Abandon buttons (same idea as
+ * PermissionService). Auto-approve is used when configured, or when the
+ * session has no owning chat (scheduled / orphan).
+ */
+import type { Api } from "grammy";
+import { InlineKeyboard } from "grammy";
+import type { PlanExitDecision, PlanExitOutcome } from "../grok/plan-approval.js";
+import { outboundThreadExtra } from "../forum/thread.js";
+import { createLogger } from "../logger.js";
+import type { RuntimeRegistry } from "./registry.js";
+
+const log = createLogger("plan-exit");
+const TIMEOUT_MS = 30 * 60 * 1000;
+const PREVIEW = 900;
+
+interface Pending {
+  resolve: (d: PlanExitDecision) => void;
+  chatId: number;
+  messageId?: number;
+  timer: NodeJS.Timeout;
+  pinned: boolean;
+  waitingFeedback: boolean;
+}
+
+export class PlanExitService {
+  private readonly pending = new Map<string, Pending>();
+  /** chatId → reqId while we wait for revision notes after "Request changes". */
+  private readonly feedbackFor = new Map<number, string>();
+  private seq = 0;
+
+  constructor(
+    private readonly api: Api,
+    private readonly registry: RuntimeRegistry,
+    public autoApprove = false,
+    private readonly onUnpinned?: (chatId: number) => void | Promise<void>,
+  ) {}
+
+  async handle(params: Record<string, unknown>): Promise<PlanExitDecision> {
+    const sessionId = str(params.sessionId) || str(params.session_id) || "";
+    const planText = extractPlanText(params);
+    if (this.autoApprove) {
+      log.info(`auto-approved plan exit for ${sessionId.slice(0, 8) || "?"}`);
+      return { outcome: "approved", feedback: "" };
+    }
+
+    const desc = sessionId ? this.registry.describeSession(sessionId) : { chatId: undefined };
+    const chatId = desc.chatId;
+    if (chatId === undefined) return { outcome: "approved", feedback: "" };
+    const threadExtra = outboundThreadExtra(desc.threadId);
+
+    const reqId = String(++this.seq);
+    const preview = planText.replace(/\s+/g, " ").trim().slice(0, PREVIEW);
+    const body = [
+      "\u{1F4CB} Plan ready \u2014 review before Grok implements.",
+      preview ? `\n${preview}${planText.length > PREVIEW ? "\u2026" : ""}` : "\n(No plan text in the request.)",
+      "\nApprove to build, request changes (then send notes), or abandon.",
+    ].join("\n");
+
+    const kb = new InlineKeyboard()
+      .text("\u2705 Approve", `planx:${reqId}:ok`)
+      .text("\u270F\uFE0F Changes", `planx:${reqId}:chg`)
+      .row()
+      .text("\u26D4 Abandon", `planx:${reqId}:no`);
+
+    let messageId: number | undefined;
+    let pinned = false;
+    try {
+      const msg = await this.api.sendMessage(chatId, body, {
+        reply_markup: kb,
+        disable_notification: false,
+        ...threadExtra,
+      });
+      messageId = msg.message_id;
+      try {
+        await this.api.pinChatMessage(chatId, messageId, { disable_notification: true });
+        pinned = true;
+      } catch (e) {
+        log.warn("pin plan prompt failed:", (e as Error).message);
+      }
+    } catch (e) {
+      log.warn("send plan prompt failed:", (e as Error).message);
+      return { outcome: "approved", feedback: "" };
+    }
+
+    return new Promise<PlanExitDecision>((resolve) => {
+      const timer = setTimeout(() => {
+        const p = this.pending.get(reqId);
+        if (!p) return;
+        this.pending.delete(reqId);
+        this.feedbackFor.delete(p.chatId);
+        void this.finish(p, "\u231B Plan approval timed out \u2014 abandoned.");
+        resolve({ outcome: "abandoned", feedback: "timed out waiting for review" });
+      }, TIMEOUT_MS);
+      this.pending.set(reqId, { resolve, chatId, messageId, timer, pinned, waitingFeedback: false });
+    });
+  }
+
+  /** Button tap. Returns a short toast; "chg" waits for the next text message. */
+  resolveChoice(reqId: string, action: string): string | undefined {
+    const p = this.pending.get(reqId);
+    if (!p) return undefined;
+    if (action === "chg") {
+      p.waitingFeedback = true;
+      this.feedbackFor.set(p.chatId, reqId);
+      void this.api
+        .editMessageText(p.chatId, p.messageId ?? 0, "\u270F\uFE0F Send revision notes as your next message.", {
+          reply_markup: { inline_keyboard: [] },
+        })
+        .catch(() => {});
+      return "Send change notes";
+    }
+    clearTimeout(p.timer);
+    this.pending.delete(reqId);
+    this.feedbackFor.delete(p.chatId);
+    const outcome: PlanExitOutcome = action === "ok" ? "approved" : "abandoned";
+    const label = outcome === "approved" ? "\u2705 Plan approved \u2014 implementing." : "\u26D4 Plan abandoned.";
+    void this.finish(p, label);
+    p.resolve({ outcome, feedback: "" });
+    return outcome === "approved" ? "Approved" : "Abandoned";
+  }
+
+  /** If this chat is waiting for revision notes, consume the text. */
+  takeFeedback(chatId: number, text: string): boolean {
+    const reqId = this.feedbackFor.get(chatId);
+    if (!reqId) return false;
+    const p = this.pending.get(reqId);
+    this.feedbackFor.delete(chatId);
+    if (!p) return false;
+    clearTimeout(p.timer);
+    this.pending.delete(reqId);
+    const notes = text.trim().slice(0, 4000);
+    void this.finish(p, `\u270F\uFE0F Requested changes:\n${notes.slice(0, 400)}`);
+    p.resolve({ outcome: "request_changes", feedback: notes || "Please revise the plan." });
+    return true;
+  }
+
+  private async finish(p: Pending, text: string): Promise<void> {
+    if (p.messageId !== undefined) {
+      await this.api
+        .editMessageText(p.chatId, p.messageId, text, { reply_markup: { inline_keyboard: [] } })
+        .catch(() => {});
+    }
+    if (p.pinned && p.messageId !== undefined) {
+      p.pinned = false;
+      await this.api.unpinChatMessage(p.chatId, p.messageId).catch(() => {});
+    }
+    if (this.onUnpinned) {
+      try {
+        await this.onUnpinned(p.chatId);
+      } catch {
+        /* non-fatal */
+      }
+    }
+  }
+}
+
+export function extractPlanText(params: Record<string, unknown>): string {
+  for (const k of ["plan_content", "planContent", "content", "plan", "text"]) {
+    const v = params[k];
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return "";
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}

package/src/bot/registry.ts

@@ -24,6 +24,8 @@ import type { SessionRuntime } from "./session-runtime.js";
 export interface SessionDescription {
   /** Chat that owns the session (controlled session or subagent parent). */
   chatId?: number;
+  /** Forum topic thread id when the session lives in a project topic. */
+  threadId?: number;
   /** True when this is a session the chat directly controls. */
   controlled: boolean;
   /** True when this is a subagent of a controlled turn. */
@@ -202,10 +204,17 @@ export class RuntimeRegistry {
   describeSession(sessionId: string): SessionDescription {
     const controlledChat = this.findChatBySession(sessionId);
     if (controlledChat !== undefined) {
-      const project = this.controller(controlledChat)
+      const forum = this.forumControllerForSession(sessionId);
+      const project = (forum ?? this.controller(controlledChat))
         .list()
         .find((s) => s.sessionId === sessionId)?.projectName;
-      return { chatId: controlledChat, controlled: true, subagent: false, projectName: project };
+      return {
+        chatId: controlledChat,
+        threadId: forum?.messageThreadId,
+        controlled: true,
+        subagent: false,
+        projectName: project,
+      };
     }
     const parent = this.subagentParents.get(sessionId);
     const info = this.acp.subagentById(sessionId);

package/src/bot/session-runtime.ts

@@ -846,6 +846,7 @@ export class SessionRuntime {
     // Never wrap meta follow-ups even if somehow first.
     if (
       input.skipSelfRecheck ||
+      input.rawSlashCommand ||
       isSelfRecheckPrompt(input.text) ||
       isTelegramBridgeResultsPrompt(input.text) ||
       isManagerWorkReportPrompt(input.text)
@@ -870,6 +871,7 @@ export class SessionRuntime {
   private applyManagerContext(input: PromptInput): PromptInput {
     if (!this.managerMode) return input;
     if (
+      input.rawSlashCommand ||
       isTelegramBridgeResultsPrompt(input.text) ||
       isManagerWorkReportPrompt(input.text) ||
       isSelfRecheckPrompt(input.text)

package/src/cli.ts

@@ -10,16 +10,17 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { listKnownInstances, stripInstanceFlags } from "./app/instance.js";
 import { ENV_PATH, INSTANCE_DIR, PROJECT_ROOT } from "./config.js";
 import { buildLaunchSpec, getController } from "./service/index.js";
 
 const HELP = `Grok Telegram Bot — CLI
 
-Usage: grok-tg <command>
+Usage: grok-tg [--name <slug>] [--instance <dir>] <command>
 
   run                 Run in the foreground
-  setup [--path]      Create/update .env (default ~/.grok/tg/.env, loaded from
-                      any folder); --path just prints the resolved .env location
+  setup [--path]      Create/update .env (default ~/.grok/tg/.env);
+                      --name <slug> writes ~/.grok/tg/instances/<slug>/.env
   install             Install + start a background service (autostart on boot)
   uninstall           Stop + remove the background service
   start               Start the service
@@ -27,12 +28,20 @@ Usage: grok-tg <command>
   restart             Restart the service
   status              Show install + running status
   logs [n]            Show the last n log lines (default 100)
+  instances           List named bot instances on this host
   help                Show this help
+
+Several Telegram bots on one host (one chat per project):
+
+  grok-tg --name work setup <BOT_TOKEN> <YOUR_USER_ID>
+  grok-tg --name work install
+  grok-tg --name work status
 `;
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
-  const [cmd, arg] = args;
+  const rest = stripInstanceFlags(args);
+  const [cmd, arg] = rest;
 
   switch (cmd) {
     case "run":
@@ -45,9 +54,9 @@ async function main(): Promise<void> {
       // Run the plain-node setup script, targeting this folder (.env lives in
       // the instance dir). Pass through optional <token> [userId] args.
       const script = join(PROJECT_ROOT, "scripts", "setup.mjs");
-      const r = spawnSync(process.execPath, [script, ...args.slice(1)], {
+      const r = spawnSync(process.execPath, [script, "--instance", INSTANCE_DIR, ...rest.slice(1)], {
         stdio: "inherit",
-        env: { ...process.env, GROK_TG_CWD: INSTANCE_DIR },
+        env: { ...process.env, GROK_TG_DIR: INSTANCE_DIR, GROK_TG_CWD: INSTANCE_DIR },
       });
       process.exit(r.status ?? 0);
       break;
@@ -57,7 +66,11 @@ async function main(): Promise<void> {
       preflight();
       const r = await getController().install(buildLaunchSpec());
       console.log(r.ok ? `✓ ${r.message}` : `✗ ${r.message}`);
-      if (r.ok) console.log("\nManage it with: grok-tg status | stop | restart | logs");
+      if (r.ok) {
+        const spec = buildLaunchSpec();
+        const flag = spec.slug ? `--name ${spec.slug} ` : "";
+        console.log(`\nManage it with: grok-tg ${flag}status | stop | restart | logs`);
+      }
       process.exit(r.ok ? 0 : 1);
       break;
     }
@@ -86,6 +99,11 @@ async function main(): Promise<void> {
       process.exit(0);
       break;
 
+    case "instances":
+      printInstances();
+      process.exit(0);
+      break;
+
     case "help":
     case "--help":
     case "-h":
@@ -112,6 +130,24 @@ function preflight(): void {
   }
 }
 
+function printInstances(): void {
+  const items = listKnownInstances();
+  if (items.length === 0) {
+    console.log("No instances found.");
+    console.log("  grok-tg setup                         # default bot (~/.grok/tg)");
+    console.log("  grok-tg --name work setup <token> <userId>   # second bot");
+    return;
+  }
+  console.log("Instances:\n");
+  for (const it of items) {
+    const manage = it.slug ? `grok-tg --name ${it.slug}` : "grok-tg";
+    console.log(`  ${it.name}`);
+    console.log(`    dir:     ${it.dir}`);
+    console.log(`    service: ${it.identity.id}`);
+    console.log(`    manage:  ${manage} status | restart | logs\n`);
+  }
+}
+
 function printLogs(n: number): void {
   const file = buildLaunchSpec().logFile;
   if (!existsSync(file)) {

package/src/config.ts

@@ -10,51 +10,42 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  CANONICAL_DIR,
+  expandHome,
+  resolveInstanceDir as resolveNamedInstanceDir,
+} from "./app/instance.js";
+
+export { CANONICAL_DIR, expandHome };
 
 /** Absolute path to the installed bot code (one level above src/). For a global
  *  npm install this lives inside node_modules — code lives here, never user data. */
 export const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
-/** Canonical, path-independent home for this bot's `.env`, `logs/`, `data/` and
- *  the single-instance locks: `~/.grok/tg`. Used whenever the bot is started
- *  without an explicit instance dir and there's no `.env` in the current folder,
- *  so the SAME configuration is found no matter which directory you launch from. */
-export const CANONICAL_DIR = join(homedir(), ".grok", "tg");
-
 /**
  * Directory holding THIS instance's `.env`, `logs/` and `data/`. Resolution
  * (first match wins):
  *   1. `--instance <dir>` argv — set by the installed background service,
- *   2. `GROK_TG_DIR` env — an explicit override,
- *   3. `GROK_TG_CWD` env — the legacy launcher variable,
- *   4. the current folder, IF it already contains a `.env`,
+ *   2. `--name` / `GROK_TG_NAME` — named instance under `~/.grok/tg/instances/`,
+ *   3. `GROK_TG_DIR` env — an explicit override,
+ *   4. `GROK_TG_CWD` or cwd IF that folder already contains a `.env`,
  *   5. the canonical `~/.grok/tg` home — the path-independent default.
  */
-export const INSTANCE_DIR = resolveInstanceDir();
+export const INSTANCE_DIR = resolveNamedInstanceDir({
+  argv: process.argv,
+  envDir: process.env.GROK_TG_DIR,
+  nameEnv: process.env.GROK_TG_NAME,
+  cwdHint: process.env.GROK_TG_CWD,
+});
 
 /** Absolute path to the `.env` this instance loads (and that `setup` writes). */
 export const ENV_PATH = join(INSTANCE_DIR, ".env");
 
-function resolveInstanceDir(): string {
-  const flag = process.argv.indexOf("--instance");
-  if (flag !== -1 && process.argv[flag + 1]) return resolve(process.argv[flag + 1]!);
-  const envDir = process.env.GROK_TG_DIR?.trim() || process.env.GROK_TG_CWD?.trim();
-  if (envDir) return resolve(expandHome(envDir));
-  if (existsSync(join(process.cwd(), ".env"))) return process.cwd();
-  return CANONICAL_DIR;
-}
-
 // Load .env from the resolved instance directory. Keep the parsed values as
 // well: a machine-wide TELEGRAM_BOT_TOKEN may belong to a sibling bot (Codex,
 // Kiro, etc.) and must never override this Grok instance's identity.
 const instanceEnv = loadDotenv({ path: ENV_PATH }).parsed ?? {};
 
-function expandHome(p: string): string {
-  if (p === "~") return homedir();
-  if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
-  return p;
-}
-
 function bool(v: string | undefined, def: boolean): boolean {
   if (v === undefined || v === "") return def;
   return ["1", "true", "yes", "on"].includes(v.toLowerCase());
@@ -142,6 +133,20 @@ export interface AppConfig {
    * Approve/Deny buttons.
    */
   autoApprovePermissions: boolean;
+  /**
+   * Auto-approve Grok plan-mode exit (no Approve/Changes/Abandon buttons).
+   * Default true so unattended/24/7 bots never wait on a TUI. Set false for
+   * interactive review in Telegram.
+   */
+  autoApprovePlan: boolean;
+  /** GROK_SANDBOX profile (workspace-safe, strict, off, …). */
+  sandboxProfile?: string;
+  /** GROK_MEMORY setting forwarded to the agent process. */
+  grokMemory?: string;
+  /** `--agent-profile` for `grok agent`. */
+  agentProfile?: string;
+  /** `--plugin-dir` for `grok agent`. */
+  pluginDir?: string;
   projectRoots: string[];
   streamThrottleMs: number;
   messageBatchMs: number;
@@ -301,6 +306,11 @@ export function loadConfig(): AppConfig {
     trustAllTools: bool(process.env.GROK_TRUST_ALL_TOOLS, true),
     // Default true: auto-approve with session-scope when the agent still asks.
     autoApprovePermissions: bool(process.env.AUTO_APPROVE_PERMISSIONS, true),
+    autoApprovePlan: bool(process.env.AUTO_APPROVE_PLAN, true),
+    sandboxProfile: process.env.GROK_SANDBOX?.trim() || undefined,
+    grokMemory: process.env.GROK_MEMORY?.trim() || undefined,
+    agentProfile: process.env.GROK_AGENT_PROFILE?.trim() || undefined,
+    pluginDir: process.env.GROK_PLUGIN_DIR?.trim() || undefined,
     projectRoots: [...new Set(roots)],
     streamThrottleMs: num(process.env.STREAM_THROTTLE_MS, 1500),
     messageBatchMs: nonNegNum(process.env.MESSAGE_BATCH_MS, 800),

package/src/grok/client.ts

@@ -218,6 +218,10 @@ export interface GrokClientOptions {
   autoRestart?: boolean;
   promptIdleTimeoutMs?: number;
   promptMaxMs?: number;
+  sandboxProfile?: string;
+  grokMemory?: string;
+  agentProfile?: string;
+  pluginDir?: string;
 }
 
 interface Pending {
@@ -288,6 +292,10 @@ export class GrokClient extends EventEmitter {
    * outcomes). Must never kill the agent process.
    */
   onSessionCancel?: (sessionId: string) => void;
+  /** Interactive (or auto) plan-mode exit. Default: auto-approve. */
+  planExitHandler?: (params: Record<string, unknown>) => Promise<unknown>;
+  /** Interactive (or skip) ask_user_question. Default: SkipInterview. */
+  askUserHandler?: (params: Record<string, unknown>) => Promise<unknown>;
 
   constructor(private readonly opts: GrokClientOptions) {
     super();
@@ -313,11 +321,15 @@ export class GrokClient extends EventEmitter {
     // the new token. `--no-auto-update` was removed in grok 0.2.x (exit 2).
     const args = ["agent", "--no-leader"];
     if (this.opts.trustAllTools) args.push("--always-approve");
+    if (this.opts.agentProfile) args.push("--agent-profile", this.opts.agentProfile);
+    if (this.opts.pluginDir) args.push("--plugin-dir", this.opts.pluginDir);
     args.push("stdio");
 
     log.info(`spawning: ${this.opts.grokCliPath} ${args.join(" ")}`);
     const env = { ...process.env };
     if (this.opts.apiKey) env.XAI_API_KEY = this.opts.apiKey;
+    if (this.opts.sandboxProfile) env.GROK_SANDBOX = this.opts.sandboxProfile;
+    if (this.opts.grokMemory) env.GROK_MEMORY = this.opts.grokMemory;
     const proc = spawn(this.opts.grokCliPath, args, {
       stdio: ["pipe", "pipe", "pipe"],
       cwd: this.opts.workspace,
@@ -419,7 +431,11 @@ export class GrokClient extends EventEmitter {
   }
 
   async newSession(cwd: string): Promise<string> {
-    const res = (await this.request("session/new", { cwd, mcpServers: [] })) as { sessionId: string };
+    const res = (await this.request("session/new", {
+      cwd,
+      mcpServers: [],
+      ...(this.opts.trustAllTools ? { _meta: { yoloMode: true } } : {}),
+    })) as { sessionId: string };
     this.parseSessionExtras(res);
     this.cwd.set(res.sessionId, cwd);
     this.slog.create(res.sessionId, cwd);
@@ -622,6 +638,12 @@ export class GrokClient extends EventEmitter {
     return this.request("_grok.dev/commands/execute", { sessionId, command });
   }
 
+  /** Update spawn-time agent env (applied on the next `grok agent` restart). */
+  setAgentOptions(opts: { sandboxProfile?: string; grokMemory?: string }): void {
+    if (opts.sandboxProfile !== undefined) this.opts.sandboxProfile = opts.sandboxProfile;
+    if (opts.grokMemory !== undefined) this.opts.grokMemory = opts.grokMemory;
+  }
+
   stop(): void {
     this.stopped = true;
     if (this.restartTimer) {
@@ -780,11 +802,13 @@ export class GrokClient extends EventEmitter {
             (planSnippet ? ` plan=${planSnippet.replace(/\s+/g, " ").slice(0, 80)}` : "") +
             (keys ? ` keys=[${keys}]` : ""),
         );
-        result = autoApproveExitPlanMode(params);
+        result = this.planExitHandler
+          ? await this.planExitHandler(params)
+          : autoApproveExitPlanMode(params);
       } else if (isAskUserQuestionMethod(method)) {
-        // No TUI question form: skip so the agent continues (prefer later Telegram UI).
-        log.info(`auto-skipping ${method} (no interactive question UI in Telegram bridge)`);
-        result = autoSkipAskUserQuestion(params);
+        result = this.askUserHandler
+          ? await this.askUserHandler(params)
+          : autoSkipAskUserQuestion(params);
       } else {
         // We advertise no fs/terminal capabilities, so the agent shouldn't ask.
         // Log at warn — unknown reverse methods used to silently break plan exit

package/src/grok/plan-approval.ts

@@ -24,6 +24,14 @@ export const EXT_EXIT_PLAN_MODE_ALT = "x.ai/exit_plan_mode";
 export const EXT_ASK_USER_QUESTION = "_x.ai/ask_user_question";
 export const EXT_ASK_USER_QUESTION_ALT = "x.ai/ask_user_question";
 
+/** Plan approval outcomes accepted by Grok Build's ExitPlanModeExtResponse. */
+export type PlanExitOutcome = "approved" | "abandoned" | "request_changes";
+
+export interface PlanExitDecision {
+  outcome: PlanExitOutcome;
+  feedback?: string;
+}
+
 /**
  * Auto-approve leaving plan mode so the agent can implement.
  *

package/src/index.ts

@@ -146,6 +146,10 @@ async function main(): Promise<void> {
     model: cfg.grokModel,
     autoRestart: cfg.grokAutoRestart,
     promptIdleTimeoutMs: cfg.promptIdleMs,
+    sandboxProfile: cfg.sandboxProfile,
+    grokMemory: cfg.grokMemory,
+    agentProfile: cfg.agentProfile,
+    pluginDir: cfg.pluginDir,
   });
 
   // Retry ACP connect — agent crash at boot should not kill the Telegram bot.

package/src/service/linux.ts

@@ -11,8 +11,12 @@ import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
 
 const UNIT = "grok-telegram-bot.service";
 
-function unitPath(): string {
-  return join(homedir(), ".config", "systemd", "user", UNIT);
+function unitName(spec?: { id?: string }): string {
+  return spec?.id ? `${spec.id}.service` : UNIT;
+}
+
+function unitPath(spec?: { id?: string }): string {
+  return join(homedir(), ".config", "systemd", "user", unitName(spec));
 }
 
 export const linuxController: ServiceController = {
@@ -21,35 +25,37 @@ export const linuxController: ServiceController = {
   async install(spec) {
     mkdirSync(join(homedir(), ".config", "systemd", "user"), { recursive: true });
     mkdirSync(spec.logsDir, { recursive: true });
-    writeFileSync(unitPath(), unitFile(spec), "utf-8");
+    const unit = unitName(spec);
+    writeFileSync(unitPath(spec), unitFile(spec), "utf-8");
 
     runSafe("systemctl", ["--user", "daemon-reload"]);
-    const en = runSafe("systemctl", ["--user", "enable", "--now", UNIT]);
+    const en = runSafe("systemctl", ["--user", "enable", "--now", unit]);
     if (!en.ok) return fail(`systemctl enable failed: ${en.out}`);
     const linger = runSafe("loginctl", ["enable-linger", userInfo().username]);
     const note = linger.ok ? " Boot-without-login enabled (linger)." : " (run `loginctl enable-linger` for boot-without-login)";
-    return ok(`Installed and started systemd user service "${UNIT}".${note}`);
+    return ok(`Installed and started systemd user service "${unit}".${note}`);
   },
 
-  async uninstall() {
-    runSafe("systemctl", ["--user", "disable", "--now", UNIT]);
-    rmSync(unitPath(), { force: true });
+  async uninstall(spec) {
+    const unit = unitName(spec);
+    runSafe("systemctl", ["--user", "disable", "--now", unit]);
+    rmSync(unitPath(spec), { force: true });
     runSafe("systemctl", ["--user", "daemon-reload"]);
-    return ok(`Removed systemd user service "${UNIT}".`);
+    return ok(`Removed systemd user service "${unit}".`);
   },
 
-  async start() {
-    const r = runSafe("systemctl", ["--user", "start", UNIT]);
+  async start(spec) {
+    const r = runSafe("systemctl", ["--user", "start", unitName(spec)]);
     return r.ok ? ok("Started.") : fail(r.out);
   },
 
-  async stop() {
-    const r = runSafe("systemctl", ["--user", "stop", UNIT]);
+  async stop(spec) {
+    const r = runSafe("systemctl", ["--user", "stop", unitName(spec)]);
     return r.ok ? ok("Stopped.") : fail(r.out);
   },
 
-  async status() {
-    const r = runSafe("systemctl", ["--user", "status", UNIT, "--no-pager"]);
+  async status(spec) {
+    const r = runSafe("systemctl", ["--user", "status", unitName(spec), "--no-pager"]);
     return ok(r.out.trim() || "No status.");
   },
 };

package/src/service/macos.ts

@@ -10,8 +10,12 @@ import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
 
 const LABEL = "com.grok.telegrambot";
 
-function plistPath(): string {
-  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+function labelOf(spec?: { macosLabel?: string }): string {
+  return spec?.macosLabel || LABEL;
+}
+
+function plistPath(spec?: { macosLabel?: string }): string {
+  return join(homedir(), "Library", "LaunchAgents", `${labelOf(spec)}.plist`);
 }
 
 export const macosController: ServiceController = {
@@ -20,32 +24,33 @@ export const macosController: ServiceController = {
   async install(spec) {
     mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
     mkdirSync(spec.logsDir, { recursive: true });
-    const path = plistPath();
+    const path = plistPath(spec);
     runSafe("launchctl", ["unload", "-w", path]); // ignore if not loaded
     writeFileSync(path, plist(spec), "utf-8");
     const r = runSafe("launchctl", ["load", "-w", path]);
-    return r.ok ? ok(`Installed and loaded LaunchAgent "${LABEL}".`) : fail(r.out);
+    return r.ok ? ok(`Installed and loaded LaunchAgent "${labelOf(spec)}".`) : fail(r.out);
   },
 
-  async uninstall() {
-    runSafe("launchctl", ["unload", "-w", plistPath()]);
-    rmSync(plistPath(), { force: true });
-    return ok(`Removed LaunchAgent "${LABEL}".`);
+  async uninstall(spec) {
+    runSafe("launchctl", ["unload", "-w", plistPath(spec)]);
+    rmSync(plistPath(spec), { force: true });
+    return ok(`Removed LaunchAgent "${labelOf(spec)}".`);
   },
 
-  async start() {
-    const r = runSafe("launchctl", ["start", LABEL]);
+  async start(spec) {
+    const r = runSafe("launchctl", ["start", labelOf(spec)]);
     return r.ok ? ok("Started.") : fail(r.out);
   },
 
-  async stop() {
-    const r = runSafe("launchctl", ["stop", LABEL]);
+  async stop(spec) {
+    const r = runSafe("launchctl", ["stop", labelOf(spec)]);
     return r.ok ? ok("Stopped.") : fail(r.out);
   },
 
-  async status() {
+  async status(spec) {
+    const lab = labelOf(spec);
     const r = runSafe("launchctl", ["list"]);
-    const line = r.out.split("\n").find((l) => l.includes(LABEL));
+    const line = r.out.split("\n").find((l) => l.includes(lab));
     return ok(line ? `Loaded: ${line.trim()}` : "Not loaded.");
   },
 };
@@ -67,7 +72,7 @@ function plist(spec: LaunchSpec): string {
     '<plist version="1.0">',
     "<dict>",
     "  <key>Label</key>",
-    `  <string>${LABEL}</string>`,
+    `  <string>${labelOf(spec)}</string>`,
     "  <key>ProgramArguments</key>",
     "  <array>",
     args,