macroclaw 0.45.0 → 0.47.0

package/src/authorized-chats.ts

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod/v4";
+import { createLogger } from "./logger";
+
+const log = createLogger("authorized-chats");
+
+export const ADMIN_CHAT_NAME = "admin";
+const NAME_PATTERN = /^[a-z0-9-]+$/;
+
+const chatSchema = z.object({
+  chatId: z.string().regex(/^-?\d+$/, "Must be a numeric Telegram chat ID"),
+  name: z.string().regex(NAME_PATTERN, "Name must be lowercase alphanumeric or dashes"),
+  addedAt: z.string(),
+});
+
+const fileSchema = z.object({
+  chats: z.array(chatSchema).default([]),
+});
+
+export type AuthorizedChat = z.infer<typeof chatSchema>;
+export type AuthorizedChatsFile = z.infer<typeof fileSchema>;
+
+const defaultDir = resolve(process.env.HOME || "~", ".macroclaw");
+
+export class DuplicateChatError extends Error {
+  constructor(public readonly kind: "name" | "chatId", public readonly value: string) {
+    super(`Chat with ${kind} "${value}" is already authorized`);
+  }
+}
+
+export class InvalidChatNameError extends Error {
+  constructor(public readonly chatName: string, reason: string) {
+    super(`Invalid chat name "${chatName}": ${reason}`);
+  }
+}
+
+export class UnknownChatError extends Error {
+  constructor(public readonly chatName: string) {
+    super(`No authorized chat named "${chatName}"`);
+  }
+}
+
+export class AuthorizedChats {
+  readonly #dir: string;
+  #chats: AuthorizedChat[] = [];
+
+  constructor(dir: string = defaultDir) {
+    this.#dir = dir;
+    this.#chats = this.#loadFromDisk();
+  }
+
+  list(): readonly AuthorizedChat[] {
+    return this.#chats;
+  }
+
+  byName(name: string): AuthorizedChat | undefined {
+    return this.#chats.find((c) => c.name === name);
+  }
+
+  byChatId(chatId: string): AuthorizedChat | undefined {
+    return this.#chats.find((c) => c.chatId === chatId);
+  }
+
+  add(chatId: string, name: string, now: Date = new Date()): AuthorizedChat {
+    AuthorizedChats.validateName(name);
+
+    if (this.byName(name)) throw new DuplicateChatError("name", name);
+    if (this.byChatId(chatId)) throw new DuplicateChatError("chatId", chatId);
+
+    const chat = chatSchema.parse({ chatId, name, addedAt: now.toISOString() });
+    this.#chats.push(chat);
+    this.#persist();
+    return chat;
+  }
+
+  remove(name: string): AuthorizedChat {
+    const existing = this.byName(name);
+    if (!existing) throw new UnknownChatError(name);
+    this.#chats = this.#chats.filter((c) => c.name !== name);
+    this.#persist();
+    return existing;
+  }
+
+  static validateName(name: string): void {
+    if (name === ADMIN_CHAT_NAME) {
+      throw new InvalidChatNameError(name, `"${ADMIN_CHAT_NAME}" is reserved`);
+    }
+    if (!NAME_PATTERN.test(name)) {
+      throw new InvalidChatNameError(name, "must be lowercase alphanumeric or dashes");
+    }
+  }
+
+  #loadFromDisk(): AuthorizedChat[] {
+    const path = this.#path();
+    if (!existsSync(path)) return [];
+    try {
+      const raw = JSON.parse(readFileSync(path, "utf-8"));
+      const result = fileSchema.safeParse(raw);
+      if (!result.success) {
+        log.warn(
+          { issues: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) },
+          "authorized-chats.json validation failed; starting with empty list",
+        );
+        return [];
+      }
+      return result.data.chats;
+    } catch (err) {
+      log.warn({ err }, "Failed to load authorized-chats.json; starting with empty list");
+      return [];
+    }
+  }
+
+  #persist(): void {
+    mkdirSync(this.#dir, { recursive: true });
+    writeFileSync(this.#path(), `${JSON.stringify({ chats: this.#chats }, null, 2)}\n`);
+  }
+
+  #path(): string {
+    return join(this.#dir, "authorized-chats.json");
+  }
+}

package/src/claude.test.ts

@@ -479,7 +479,7 @@ describe("Claude factory", () => {
       claude.newSession(textResult);
       const args = spawnArgs();
       expect(args).toContain("--disallowedTools");
-      expect(args).toContain("CronList,CronDelete,CronCreate,AskUserQuestion");
+      expect(args).toContain("CronList,CronDelete,CronCreate,AskUserQuestion,RemoteTrigger");
     });
 
     it("spawns with stdin: pipe, stdout: pipe, stderr: pipe", () => {

package/src/claude.ts

@@ -257,7 +257,7 @@ export class Claude {
       "--input-format", "stream-json",
       "--output-format", "stream-json",
       "--verbose",
-      "--disallowedTools", "CronList,CronDelete,CronCreate,AskUserQuestion",
+      "--disallowedTools", "CronList,CronDelete,CronCreate,AskUserQuestion,RemoteTrigger",
     ];
 
     if (mode.kind === "resume") {

package/src/cli.test.ts

@@ -20,7 +20,7 @@ const { main } = await import("./cli");
 
 function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<string, unknown>) => Promise<unknown>; installService?: () => Promise<void>; forceInstallService?: () => Promise<void> }) {
 	return {
-		collectSettings: overrides?.collectSettings ?? mock(async () => ({ botToken: "tok", chatId: "123" })),
+		collectSettings: overrides?.collectSettings ?? mock(async () => ({ botToken: "tok", adminChatId: "123" })),
 		installService: overrides?.installService ?? mock(async () => {}),
 		forceInstallService: overrides?.forceInstallService ?? mock(async () => {}),
 	} as unknown as SetupWizard;
@@ -28,7 +28,7 @@ function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<str
 
 function createMockSettings(overrides?: Partial<SettingsManager>) {
 	return {
-		load: mock(() => ({ botToken: "tok", chatId: "123", model: "sonnet", workspace: "/tmp" })),
+		load: mock(() => ({ botToken: "tok", adminChatId: "123", model: "sonnet", workspace: "/tmp" })),
 		loadRaw: mock(() => null),
 		save: mock(() => {}),
 		applyEnvOverrides: mock((s: unknown) => ({ settings: s, overrides: new Set() })),
@@ -72,14 +72,14 @@ describe("Cli.setup", () => {
 		const settings = createMockSettings();
 		const cli = new Cli({ wizard, settings });
 		await cli.setup();
-		expect((settings.save as ReturnType<typeof mock>)).toHaveBeenCalledWith({ botToken: "tok", chatId: "123" });
+		expect((settings.save as ReturnType<typeof mock>)).toHaveBeenCalledWith({ botToken: "tok", adminChatId: "123" });
 	});
 
 	it("passes existing settings as defaults to wizard", async () => {
-		const existing = { botToken: "old-tok", chatId: "999" };
+		const existing = { botToken: "old-tok", adminChatId: "999" };
 		let receivedDefaults: unknown = null;
 		const wizard = createMockWizard({
-			collectSettings: async (defaults) => { receivedDefaults = defaults; return { botToken: "tok", chatId: "123" }; },
+			collectSettings: async (defaults) => { receivedDefaults = defaults; return { botToken: "tok", adminChatId: "123" }; },
 		});
 		const settings = createMockSettings({ loadRaw: () => existing } as unknown as Partial<SettingsManager>);
 		const cli = new Cli({ wizard, settings });
@@ -236,7 +236,7 @@ describe("Cli.claude", () => {
 		const fs = await import("node:fs");
 		const dir = `/tmp/macroclaw-test-claude-${Date.now()}`;
 		fs.mkdirSync(dir, { recursive: true });
-		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", chatId: "123", model: "opus", workspace: "/tmp" }));
+		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", adminChatId: "123", model: "opus", workspace: "/tmp" }));
 		fs.writeFileSync(`${dir}/sessions.json`, JSON.stringify({ mainSessionId: "sess-123" }));
 
 		mockExecSync.mockClear();
@@ -257,7 +257,7 @@ describe("Cli.claude", () => {
 		const fs = await import("node:fs");
 		const dir = `/tmp/macroclaw-test-claude-${Date.now()}`;
 		fs.mkdirSync(dir, { recursive: true });
-		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", chatId: "123", model: "sonnet", workspace: "/tmp" }));
+		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", adminChatId: "123", model: "sonnet", workspace: "/tmp" }));
 		fs.writeFileSync(`${dir}/sessions.json`, JSON.stringify({}));
 
 		mockExecSync.mockClear();

package/src/cli.ts

@@ -2,7 +2,7 @@ import {execSync} from "node:child_process";
 import {createInterface} from "node:readline";
 import {defineCommand} from "citty";
 import pkg from "../package.json" with {type: "json"};
-import {loadSessions} from "./sessions";
+import {getMainSession} from "./sessions";
 import {SettingsManager} from "./settings";
 import {type SetupIo, SetupWizard} from "./setup";
 import {SystemServiceManager} from "./system-service";
@@ -32,9 +32,9 @@ export class Cli {
 
 	claude(): void {
 		const settings = this.#settingsManager.load();
-		const sessions = loadSessions(this.#settingsManager.dir);
+		const adminSession = getMainSession("admin", this.#settingsManager.dir);
 		const args = ["claude"];
-		if (sessions.mainSessionId) args.push("--resume", sessions.mainSessionId);
+		if (adminSession) args.push("--resume", adminSession);
 		args.push("--model", settings.model);
 		execSync(args.join(" "), { cwd: settings.workspace, stdio: "inherit", env: { ...process.env, CLAUDECODE: "" } });
 	}

package/src/index.ts

@@ -37,7 +37,7 @@ export async function start(): Promise<void> {
 
   const config: AppConfig = {
     botToken: resolved.botToken,
-    authorizedChatId: resolved.chatId,
+    adminChatId: resolved.adminChatId,
     workspace,
     model: resolved.model,
     timeZone: resolved.timeZone,

package/src/orchestrator.test.ts

@@ -263,7 +263,7 @@ describe("Orchestrator", () => {
     });
 
     it("reports error when resume fails", async () => {
-      saveSessions({ mainSessionId: "old-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "old-session" } }, tmpSettingsDir);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const proc = autoProcess(null, "old-session");
         (proc as any).send = mock(async () => { throw new QueryProcessError(1, "session not found"); });
@@ -282,7 +282,7 @@ describe("Orchestrator", () => {
 
   describe("session management", () => {
     it("uses resumeSession for existing session", async () => {
-      saveSessions({ mainSessionId: "existing-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "existing-session" } }, tmpSettingsDir);
       const claude = mockClaude({ action: "send", message: "ok", actionReason: "ok" });
       const { orch } = makeOrchestrator(claude);
 
@@ -320,7 +320,7 @@ describe("Orchestrator", () => {
     });
 
     it("background-agent forks from main session", async () => {
-      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "main-session" } }, tmpSettingsDir);
       const claude = mockClaude({ action: "send", message: "ok", actionReason: "ok" });
       const { orch } = makeOrchestrator(claude);
 
@@ -449,7 +449,7 @@ describe("Orchestrator", () => {
     });
 
     it("delivers result with error when session not in runningSessions", async () => {
-      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "main-session" } }, tmpSettingsDir);
       const { process: mainProc, resolve } = pendingProcess("main-session");
       const claude = mockClaude(() => mainProc);
       const { orch, responses } = makeOrchestrator(claude);
@@ -539,7 +539,7 @@ describe("Orchestrator", () => {
 
   describe("cron routing", () => {
     it("cron always forks as background, never goes through queue", async () => {
-      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "main-session" } }, tmpSettingsDir);
       const claude = mockClaude({ action: "send", message: "ok", actionReason: "ok" });
       const { orch } = makeOrchestrator(claude);
 
@@ -553,7 +553,7 @@ describe("Orchestrator", () => {
     });
 
     it("cron uses config model when none specified", async () => {
-      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "main-session" } }, tmpSettingsDir);
       const claude = mockClaude({ action: "send", message: "ok", actionReason: "ok" });
       const { orch } = makeOrchestrator(claude, { model: "sonnet" });
 
@@ -564,7 +564,7 @@ describe("Orchestrator", () => {
     });
 
     it("cron result feeds back into main session", async () => {
-      saveSessions({ mainSessionId: "main-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "main-session" } }, tmpSettingsDir);
       let callCount = 0;
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         callCount++;
@@ -591,7 +591,7 @@ describe("Orchestrator", () => {
     });
 
     it("includes detail buttons and dismiss when sessions are running", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const { process } = pendingProcess(`bg-${Date.now()}`);
         return process;
@@ -644,7 +644,7 @@ describe("Orchestrator", () => {
     });
 
     it("peeks at running agent and returns status", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       let callCount = 0;
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         callCount++;
@@ -674,7 +674,7 @@ describe("Orchestrator", () => {
     });
 
     it("handles Claude error during peek gracefully", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       let callCount = 0;
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         callCount++;
@@ -717,7 +717,7 @@ describe("Orchestrator", () => {
     });
 
     it("shows session details with peek/kill/dismiss buttons", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const { process } = pendingProcess("bg-sid");
         return process;
@@ -748,7 +748,7 @@ describe("Orchestrator", () => {
     });
 
     it("truncates prompt at 300 chars", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const longPrompt = "a".repeat(500);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const { process } = pendingProcess("bg-sid");
@@ -775,7 +775,7 @@ describe("Orchestrator", () => {
     });
 
     it("shows model when specified", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const { process } = pendingProcess("bg-sid");
         return process;
@@ -834,7 +834,7 @@ describe("Orchestrator", () => {
     });
 
     it("kills running session and sends confirmation", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
       const claude = mockClaude((): ClaudeProcess<unknown> => bgProc);
       const { orch, responses } = makeOrchestrator(claude);
@@ -862,7 +862,7 @@ describe("Orchestrator", () => {
     });
 
     it("does not feed error back to queue after kill", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc, reject: rejectBg } = pendingProcess("bg-sid");
       const claude = mockClaude((): ClaudeProcess<unknown> => bgProc);
       const { orch, responses } = makeOrchestrator(claude);
@@ -890,7 +890,7 @@ describe("Orchestrator", () => {
 
   describe("handleBackgroundCommand", () => {
     it("spawns background agent and sends started message", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const claude = mockClaude((): ClaudeProcess<unknown> => {
         const { process } = pendingProcess("bg-sid");
         return process;
@@ -907,7 +907,7 @@ describe("Orchestrator", () => {
 
   describe("background management", () => {
     it("spawns background agent and feeds result back to queue", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc, resolve: resolveBg } = pendingProcess("bg-sid");
 
       let callCount = 0;
@@ -931,7 +931,7 @@ describe("Orchestrator", () => {
     });
 
     it("passes action and actionReason through result XML for silent background agent", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc, resolve: resolveBg } = pendingProcess("bg-sid");
 
       let callCount = 0;
@@ -957,7 +957,7 @@ describe("Orchestrator", () => {
     });
 
     it("feeds error back to queue on spawn failure", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc, reject: rejectBg } = pendingProcess("bg-sid");
 
       let callCount = 0;
@@ -981,7 +981,7 @@ describe("Orchestrator", () => {
 
   describe("health checks", () => {
     it("runs health check after interval and reports finished agent", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
 
       let callCount = 0;
@@ -1013,7 +1013,7 @@ describe("Orchestrator", () => {
     });
 
     it("reports progress and schedules next check when not finished", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
 
       let hcCount = 0;
@@ -1045,7 +1045,7 @@ describe("Orchestrator", () => {
     });
 
     it("kills unresponsive agent on health check timeout", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
 
       const claude = mockClaude((info: CallInfo): ClaudeProcess<unknown> => {
@@ -1070,7 +1070,7 @@ describe("Orchestrator", () => {
     });
 
     it("does not run health checks when interval is 0", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
 
       const claude = mockClaude((): ClaudeProcess<unknown> => bgProc);
@@ -1084,7 +1084,7 @@ describe("Orchestrator", () => {
     });
 
     it("clears health check timer when session is killed", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc } = pendingProcess("bg-sid");
 
       let hcCount = 0;
@@ -1106,7 +1106,7 @@ describe("Orchestrator", () => {
     });
 
     it("stops health check if session completes organically before timer", async () => {
-      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      saveSessions({ mainSessions: { admin: "test-session" } }, tmpSettingsDir);
       const { process: bgProc, resolve: resolveBg } = pendingProcess("bg-sid");
 
       let hcCount = 0;

package/src/orchestrator.ts

@@ -12,7 +12,7 @@ import { createLogger } from "./logger";
 import { generateName } from "./naming";
 import { PromptBuilder } from "./prompt-builder";
 import { Queue } from "./queue";
-import { loadSessions, saveSessions } from "./sessions";
+import { clearMainSession, getMainSession, setMainSession } from "./sessions";
 
 type ButtonSpec = string | { text: string; data: string };
 
@@ -90,6 +90,8 @@ interface SessionInfo {
 }
 
 export interface OrchestratorConfig {
+  /** Name of the chat this orchestrator serves. Used to scope the sessions.json slot. Defaults to "admin". */
+  chatName?: string;
   model: string;
   workspace: string;
   timeZone: string;
@@ -106,6 +108,7 @@ export interface OrchestratorConfig {
 
 export class Orchestrator {
   #config: Omit<OrchestratorConfig , 'claude'>;
+  #chatName: string;
   #claude: Claude;
   #prompts: PromptBuilder;
   #waitThreshold: number;
@@ -119,7 +122,8 @@ export class Orchestrator {
 
   constructor(config: OrchestratorConfig) {
     this.#config = config;
-    this.#prompts = new PromptBuilder(config.timeZone);
+    this.#chatName = config.chatName ?? "admin";
+    this.#prompts = new PromptBuilder(config.timeZone, this.#chatName);
     const envVars: Record<string, string> = { TZ: config.timeZone };
     this.#claude = config.claude ?? new Claude({ workspace: config.workspace, systemPrompt: this.#prompts.systemPrompt, envVars });
     this.#waitThreshold = config.waitThreshold ?? WAIT_THRESHOLD;
@@ -128,7 +132,7 @@ export class Orchestrator {
     this.#queue = new Queue<OrchestratorRequest>();
     this.#queue.setHandler((request) => this.#handleRequest(request));
 
-    this.#mainSessionId = loadSessions(config.settingsDir).mainSessionId;
+    this.#mainSessionId = getMainSession(this.#chatName, config.settingsDir);
   }
 
   // --- Public handle methods ---
@@ -264,7 +268,7 @@ export class Orchestrator {
       this.#mainProcess = null;
     }
     this.#mainSessionId = undefined;
-    saveSessions({}, this.#config.settingsDir);
+    clearMainSession(this.#chatName, this.#config.settingsDir);
     log.info("Session cleared");
     this.#callOnResponse({ message: "Session cleared." });
   }
@@ -294,7 +298,7 @@ export class Orchestrator {
 
     if (this.#mainProcess.sessionId !== this.#mainSessionId) {
       this.#mainSessionId = this.#mainProcess.sessionId;
-      saveSessions({ mainSessionId: this.#mainSessionId }, this.#config.settingsDir);
+      setMainSession(this.#chatName, this.#mainSessionId, this.#config.settingsDir);
     }
 
     log.info({ sessionId: this.#mainSessionId }, "Main process created");
@@ -340,7 +344,7 @@ export class Orchestrator {
         { model: this.#config.model },
       );
       this.#mainSessionId = this.#mainProcess.sessionId;
-      saveSessions({ mainSessionId: this.#mainSessionId }, this.#config.settingsDir);
+      setMainSession(this.#chatName, this.#mainSessionId, this.#config.settingsDir);
     }
 
     await writeHistoryPrompt(request);

package/src/prompt-builder.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { PromptBuilder } from "./prompt-builder";
 
-const p = new PromptBuilder("UTC");
+const p = new PromptBuilder("UTC", "admin");
 
 describe("systemPrompt", () => {
   it("contains key sections", () => {
@@ -52,17 +52,22 @@ describe("systemPrompt", () => {
   });
 
   it("includes time zone but not a fixed date", () => {
-    const prague = new PromptBuilder("Europe/Prague");
+    const prague = new PromptBuilder("Europe/Prague", "admin");
     expect(prague.systemPrompt).not.toContain("Current date:");
     expect(prague.systemPrompt).toContain("Timezone: Europe/Prague");
     expect(prague.systemPrompt).toContain("TZ env var is set");
   });
+
+  it("documents the chat attribute on events", () => {
+    expect(p.systemPrompt).toContain("Multi-chat");
+    expect(p.systemPrompt).toContain("chat — name of the Telegram chat");
+  });
 });
 
 describe("userMessage", () => {
   it("builds user message event with time attribute", () => {
     const result = p.userMessage("check-logs", "hello");
-    expect(result).toMatch(/^<event time="\d{4}-\d{2}-\d{2}T\d{2}:\d{2}" name="check-logs" type="user-message" session="main">/);
+    expect(result).toMatch(/^<event time="\d{4}-\d{2}-\d{2}T\d{2}:\d{2}" name="check-logs" chat="admin" type="user-message" session="main">/);
     expect(result).toContain("<text>hello</text>");
     expect(result).toEndWith("</event>");
   });
@@ -241,3 +246,23 @@ describe("healthCheck", () => {
     expect(result).toContain("<instructions>Report status.</instructions>");
   });
 });
+
+describe("chat attribute", () => {
+  it("includes chat attribute on every event type", () => {
+    const pb = new PromptBuilder("UTC", "family");
+    expect(pb.userMessage("t", "hello")).toContain('chat="family"');
+    expect(pb.buttonClick("t", "Yes")).toContain('chat="family"');
+    expect(pb.scheduleTrigger("t", { name: "daily" }, "go")).toContain('chat="family"');
+    expect(pb.backgroundAgentStart("t", "task")).toContain('chat="family"');
+    expect(pb.backgroundAgentResult("t", "orig", { action: "send", actionReason: "done" })).toContain('chat="family"');
+    expect(pb.backgroundAgentProgress("t", "orig", "50%", "keep going")).toContain('chat="family"');
+    expect(pb.peek("t", "orig", "status?")).toContain('chat="family"');
+    expect(pb.healthCheck("t", "orig", "status?")).toContain('chat="family"');
+  });
+
+  it("escapes XML in chat name", () => {
+    const pb = new PromptBuilder("UTC", 'a<b>"');
+    const result = pb.userMessage("test", "hello");
+    expect(result).toContain('chat="a&lt;b&gt;&quot;"');
+  });
+});

package/src/prompt-builder.ts

@@ -17,9 +17,16 @@ Use raw <b>, <i>, <code>, <pre> tags. Escape &, <, > in text content as &amp;, &
 Architecture: message bridge connecting chat interface and scheduled tasks. \
 Persistent session — conversation history carries across messages. Workspace persists across sessions.
 
+Multi-chat: the bridge serves multiple Telegram chats (e.g. "admin", "family", "work"). Each chat has its own \
+isolated conversation thread with you. The chat attribute on every <event> identifies which chat the event \
+originates from. Tailor your response to that chat — different people/contexts may expect different tone, \
+access, and information. When responding to a scheduled task with chat="*", the same prompt is being \
+broadcast to every authorized chat.
+
 Event format: every incoming message is wrapped in an <event> XML block. Attributes:
 - time — local time when the event was created (ISO 8601, minute precision).
 - name — short identifier for this event (e.g. "check-logs", "cron-daily").
+- chat — name of the Telegram chat this event belongs to (e.g. "admin", "family").
 - type — what triggered this event. One of:
   - user-message — direct user message. Content in <text>, optional <files>.
   - button-click — user tapped an inline button. Label in <button>.
@@ -83,9 +90,11 @@ interface BuildXmlFields {
 
 export class PromptBuilder {
   readonly #timeZone: string;
+  readonly #chatName: string;
 
-  constructor(timeZone: string) {
+  constructor(timeZone: string, chatName: string) {
     this.#timeZone = timeZone;
+    this.#chatName = chatName;
   }
 
   get systemPrompt(): string {
@@ -100,10 +109,10 @@ export class PromptBuilder {
     return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   }
 
-  static #buildXml(name: string, type: string, session: string, time: string, fields: BuildXmlFields): string {
+  #buildXml(name: string, type: string, session: string, time: string, fields: BuildXmlFields): string {
     const esc = PromptBuilder.#escapeXml;
     const lines: string[] = [
-      `<event time="${time}" name="${esc(name)}" type="${type}" session="${session}">`,
+      `<event time="${time}" name="${esc(name)}" chat="${esc(this.#chatName)}" type="${type}" session="${session}">`,
     ];
 
     if (fields.backgroundedEvent) {
@@ -174,34 +183,34 @@ export class PromptBuilder {
   }
 
   userMessage(name: string, text: string, opts?: { files?: string[]; backgroundedEvent?: string }): string {
-    return PromptBuilder.#buildXml(name, "user-message", "main", this.#localTime(), { text, files: opts?.files, backgroundedEvent: opts?.backgroundedEvent });
+    return this.#buildXml(name, "user-message", "main", this.#localTime(), { text, files: opts?.files, backgroundedEvent: opts?.backgroundedEvent });
   }
 
   buttonClick(name: string, button: string, opts?: { backgroundedEvent?: string }): string {
-    return PromptBuilder.#buildXml(name, "button-click", "main", this.#localTime(), { button, backgroundedEvent: opts?.backgroundedEvent });
+    return this.#buildXml(name, "button-click", "main", this.#localTime(), { button, backgroundedEvent: opts?.backgroundedEvent });
   }
 
   scheduleTrigger(name: string, schedule: { name: string; missedBy?: string; scheduledAt?: string }, text: string): string {
-    return PromptBuilder.#buildXml(name, "schedule-trigger", "background", this.#localTime(), { schedule, text });
+    return this.#buildXml(name, "schedule-trigger", "background", this.#localTime(), { schedule, text });
   }
 
   backgroundAgentStart(name: string, text: string): string {
-    return PromptBuilder.#buildXml(name, "background-agent-start", "background", this.#localTime(), { text });
+    return this.#buildXml(name, "background-agent-start", "background", this.#localTime(), { text });
   }
 
   backgroundAgentResult(name: string, originalEvent: string, result: { action: string; actionReason: string; text?: string; files?: string[] }, opts?: { backgroundedEvent?: string }): string {
-    return PromptBuilder.#buildXml(name, "background-agent-result", "main", this.#localTime(), { originalEvent, result, backgroundedEvent: opts?.backgroundedEvent });
+    return this.#buildXml(name, "background-agent-result", "main", this.#localTime(), { originalEvent, result, backgroundedEvent: opts?.backgroundedEvent });
   }
 
   backgroundAgentProgress(name: string, originalEvent: string, progress: string, instructions: string, opts?: { backgroundedEvent?: string }): string {
-    return PromptBuilder.#buildXml(name, "background-agent-progress", "main", this.#localTime(), { originalEvent, progress, instructions, backgroundedEvent: opts?.backgroundedEvent });
+    return this.#buildXml(name, "background-agent-progress", "main", this.#localTime(), { originalEvent, progress, instructions, backgroundedEvent: opts?.backgroundedEvent });
   }
 
   peek(name: string, targetEvent: string, instructions: string): string {
-    return PromptBuilder.#buildXml(name, "peek", "background", this.#localTime(), { targetEvent, instructions });
+    return this.#buildXml(name, "peek", "background", this.#localTime(), { targetEvent, instructions });
   }
 
   healthCheck(name: string, targetEvent: string, instructions: string): string {
-    return PromptBuilder.#buildXml(name, "health-check", "background", this.#localTime(), { targetEvent, instructions });
+    return this.#buildXml(name, "health-check", "background", this.#localTime(), { targetEvent, instructions });
   }
 }