@amanm/openpaw 0.1.0

package/config/paths.ts

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_DIR = join(homedir(), ".openpaw");
+const CONFIG_PATH = join(CONFIG_DIR, "config.yaml");
+const WORKSPACE_DIR = join(CONFIG_DIR, "workspace");
+const SESSIONS_DIR = join(WORKSPACE_DIR, "sessions");
+
+/**
+ * Absolute path to the YAML config file, typically `~/.openpaw/config.yaml`.
+ */
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}
+
+/**
+ * Ensures the OpenPaw config directory exists (`~/.openpaw`), creating it if needed.
+ *
+ * @remarks Uses synchronous `mkdirSync` with `recursive: true`.
+ */
+export function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Returns whether the config file exists at {@link getConfigPath}.
+ */
+export function configExists(): boolean {
+  return existsSync(CONFIG_PATH);
+}
+
+/**
+ * Deletes the config file if it exists. No-op when the file is absent.
+ *
+ * @remarks Uses synchronous `unlinkSync`.
+ */
+export function deleteConfig(): void {
+  if (existsSync(CONFIG_PATH)) {
+    unlinkSync(CONFIG_PATH);
+  }
+}
+
+/**
+ * OpenPaw workspace root, typically `~/.openpaw/workspace`.
+ */
+export function getWorkspaceRoot(): string {
+  return WORKSPACE_DIR;
+}
+
+/**
+ * Directory for persisted chat sessions, `~/.openpaw/workspace/sessions`.
+ */
+export function getSessionsDir(): string {
+  return SESSIONS_DIR;
+}
+
+/**
+ * Ensures workspace and `sessions/` exist on disk (directories only).
+ */
+export function ensureWorkspaceDirectories(): void {
+  ensureConfigDir();
+  if (!existsSync(WORKSPACE_DIR)) {
+    mkdirSync(WORKSPACE_DIR, { recursive: true });
+  }
+  if (!existsSync(SESSIONS_DIR)) {
+    mkdirSync(SESSIONS_DIR, { recursive: true });
+  }
+}

package/config/personality-copy.ts

@@ -0,0 +1,68 @@
+/**
+ * Fixed prose for each onboarding personality and shared identity copy for the system prompt.
+ */
+
+import type { Personality } from "./types";
+
+/** Core identity (Hermes-style default agent preamble, adapted for OpenPaw). */
+export const OPENPAW_IDENTITY = [
+  "You are OpenPaw, a capable local AI assistant.",
+  "You are helpful, direct, and honest. You assist with questions, code, analysis, and actions via your tools.",
+  "Communicate clearly, admit uncertainty when appropriate, and prioritize being useful over being verbose unless the user or workspace says otherwise.",
+  "Be targeted and efficient in exploration and investigations.",
+  "In conversation, sound like a person who pays attention — not like software narrating where it read data from.",
+].join(" ");
+
+const PERSONALITY_PROSE: Record<Personality, string> = {
+  Assistant:
+    "Tone: casual but professional — warm, conversational, still clear and competent. " +
+      "Answer like someone who remembers the thread and the user: weave in context naturally (\"You said you're in India…\", \"Last time you mentioned…\") instead of quoting files, \"profiles\", or tools. " +
+      "Avoid stiff assistant-speak and avoid meta lines about what you \"loaded\" or \"checked\".",
+  Meowl:
+    "Tone: warm and playful with light cat-themed flair where it fits; stay substantive and never sacrifice clarity for whimsy.",
+  Coder:
+    "Tone: engineer-focused. Prefer concrete steps, code, and commands; minimize filler. When editing code, prefer small diffs and match existing style.",
+};
+
+/**
+ * Returns a short paragraph expanding the selected personality preset for the system prompt.
+ */
+export function getPersonalityProse(personality: Personality): string {
+  return PERSONALITY_PROSE[personality];
+}
+
+/** When to use the memory tool vs files (aligned with Hermes MEMORY guidance intent). */
+export const MEMORY_GUIDANCE = [
+  "You have persistent storage: use the `memory` tool for durable user facts (`user`) and your own notes (`memory`); use the file editor for workspace persona and long-form workspace rules when instructed below.",
+  "Save durable facts: preferences, location/timezone when relevant, environment details, tool quirks, stable conventions.",
+  "Curated memory is shown as a frozen block at session start; after you edit it, updates appear in tool results until a new session.",
+  "Memory tool: `add` only needs `content`. `replace` needs `old_text` + `content`. `remove` needs `old_text` only. Never use `replace` with content alone for a brand-new fact.",
+  "Prioritize what reduces future steering. Do NOT save ephemeral task progress, session logs, or huge dumps.",
+  "Internal only (never say this to the user): persona text may live in one workspace markdown file; rules in another. When saving or recalling, talk like a human: \"You told me…\", \"You're in IST, right?\" — not \"your user.md\", \"soul.md\", \"profile file\", \"MEMORY.md\", or \"I checked the memory tool\".",
+].join("\n");
+
+/**
+ * Explicit rules for user-visible replies — keeps tooling invisible in natural language.
+ */
+export const USER_FACING_VOICE = [
+  "In every message meant for the user, speak naturally.",
+  "Good: \"You mentioned you're in India, so you're on IST (UTC+5:30).\" / \"Want me to remember your timezone for later?\"",
+  "Bad: \"Your user.md says…\", \"According to your profile file…\", \"I read soul.md…\", \"The memory block shows…\", \"I'll add that to MEMORY.md.\"",
+  "If something was never stated and you're inferring, say so briefly instead of pretending it came from a file.",
+].join("\n");
+
+/** Short note about conversation history (session persistence). */
+export const SESSION_NOTE =
+  "Prior messages in this chat are persisted in the session; you can refer to them without saving everything to memory.";
+
+/** Surface-specific hints (Hermes PLATFORM_HINTS style, adapted for OpenPaw). */
+export const PLATFORM_HINTS: Record<"cli" | "telegram", string> = {
+  cli: [
+    "You are running in a terminal UI. Prefer plain, readable text over heavy markdown",
+    "(headings and short lists are fine if they render well in the TUI).",
+  ].join(" "),
+  telegram: [
+    "You are on Telegram. Formatting is limited; avoid relying on complex markdown.",
+    "Keep messages readable as plain text when in doubt.",
+  ].join(" "),
+};

package/config/storage.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { ensureConfigDir, getConfigPath } from "./paths";
+import type { OpenPawConfig, Personality } from "./types";
+
+function toYaml(config: OpenPawConfig): string {
+  const lines: string[] = [];
+
+  lines.push("provider:");
+  lines.push(`  baseUrl: "${config.provider.baseUrl}"`);
+  lines.push(`  apiKey: "${config.provider.apiKey}"`);
+  lines.push(`  model: "${config.provider.model}"`);
+
+  if (config.channels?.telegram) {
+    lines.push("channels:");
+    lines.push("  telegram:");
+    lines.push(`    botToken: "${config.channels.telegram.botToken}"`);
+  }
+
+  lines.push(`personality: "${config.personality}"`);
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Writes the full config to disk, replacing any existing file at {@link getConfigPath}.
+ *
+ * @remarks Ensures the config directory exists before writing via {@link ensureConfigDir}.
+ */
+export async function saveConfig(config: OpenPawConfig): Promise<void> {
+  ensureConfigDir();
+  await Bun.write(getConfigPath(), toYaml(config));
+}
+
+/**
+ * Reads and parses the YAML config file from disk.
+ *
+ * @returns Parsed config, or `null` if the file is missing, unreadable, or required
+ *   fields (`provider.*`, `personality`) cannot be extracted with the current parser.
+ */
+export async function loadConfig(): Promise<OpenPawConfig | null> {
+  const path = getConfigPath();
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    const file = Bun.file(path);
+    const content = await file.text();
+
+    const baseUrlMatch = content.match(/baseUrl:\s*"([^"]+)"/);
+    const apiKeyMatch = content.match(/apiKey:\s*"([^"]+)"/);
+    const modelMatch = content.match(/model:\s*"([^"]+)"/);
+    const botTokenMatch = content.match(/botToken:\s*"([^"]+)"/);
+    const personalityMatch = content.match(/personality:\s*"([^"]+)"/);
+
+    if (!baseUrlMatch?.[1] || !apiKeyMatch?.[1] || !modelMatch?.[1] || !personalityMatch?.[1]) {
+      return null;
+    }
+
+    const config: OpenPawConfig = {
+      provider: {
+        baseUrl: baseUrlMatch[1],
+        apiKey: apiKeyMatch[1],
+        model: modelMatch[1],
+      },
+      personality: personalityMatch[1] as Personality,
+    };
+
+    if (botTokenMatch?.[1]) {
+      config.channels = {
+        telegram: {
+          botToken: botTokenMatch[1],
+        },
+      };
+    }
+
+    return config;
+  } catch {
+    return null;
+  }
+}

package/config/types.ts

@@ -0,0 +1,37 @@
+/**
+ * LLM provider settings used for API calls.
+ */
+export interface ProviderConfig {
+  /** Base URL of the provider API (e.g. OpenAI-compatible endpoint). */
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+
+/**
+ * Optional integrations for outbound channels (e.g. Telegram bot).
+ */
+export interface ChannelsConfig {
+  /** When set, enables Telegram with this bot token. */
+  telegram?: {
+    botToken: string;
+  };
+}
+
+/**
+ * Ordered list of personality labels shown in onboarding and persisted to `config.yaml`.
+ * Each value is written as the `personality` string field.
+ */
+export const PERSONALITIES = ["Assistant", "Meowl", "Coder"] as const;
+
+/** One of the allowed `personality` values stored in config. */
+export type Personality = (typeof PERSONALITIES)[number];
+
+/**
+ * Full OpenPaw user configuration as represented on disk and in the onboarding flow.
+ */
+export interface OpenPawConfig {
+  provider: ProviderConfig;
+  channels?: ChannelsConfig;
+  personality: Personality;
+}

package/gateway/bootstrap.ts

@@ -0,0 +1,25 @@
+import { createAgentRuntime, type AgentRuntime } from "../agent/agent";
+import { ensureWorkspaceLayout } from "../agent/workspace-bootstrap";
+import { getWorkspaceRoot } from "../config/paths";
+import type { OpenPawConfig } from "../config/types";
+import { loadConfig } from "../config/storage";
+
+export type OpenPawGatewayContext = {
+  config: OpenPawConfig;
+  workspacePath: string;
+  runtime: AgentRuntime;
+};
+
+/**
+ * Load config, ensure workspace layout, and create the shared agent runtime used by all channels.
+ */
+export async function createGatewayContext(): Promise<OpenPawGatewayContext> {
+  const config = await loadConfig();
+  if (!config) {
+    throw new Error("Config not found. Run `openpaw onboard` first.");
+  }
+  ensureWorkspaceLayout();
+  const workspacePath = getWorkspaceRoot();
+  const runtime = await createAgentRuntime(config, workspacePath);
+  return { config, workspacePath, runtime };
+}

package/gateway/channel-adapter.ts

@@ -0,0 +1,8 @@
+/**
+ * A messaging channel (Telegram, future webhooks, etc.) that runs until stopped.
+ */
+export type ChannelAdapter = {
+  readonly id: string;
+  /** Runs until the channel stops (e.g. long polling ends). Normally does not resolve. */
+  run: () => Promise<void>;
+};

package/gateway/daemon-manager.ts

@@ -0,0 +1,191 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** Filesystem paths used by the gateway daemon lifecycle. */
+export type GatewayDaemonPaths = {
+  stateDir: string;
+  pidFile: string;
+  logFile: string;
+  errFile: string;
+};
+
+/** Current observed process state for the background gateway daemon. */
+export type GatewayDaemonState = "running" | "stopped" | "stale";
+
+/** Structured status payload returned by {@link getGatewayDaemonStatus}. */
+export type GatewayDaemonStatus = {
+  state: GatewayDaemonState;
+  pid: number | null;
+  paths: GatewayDaemonPaths;
+};
+
+/** Result payload from {@link startGatewayDaemon}. */
+export type StartGatewayDaemonResult = {
+  status: "started" | "already_running";
+  pid: number;
+  paths: GatewayDaemonPaths;
+};
+
+/** Result payload from {@link stopGatewayDaemon}. */
+export type StopGatewayDaemonResult = {
+  status: "stopped" | "already_stopped";
+  pid: number | null;
+  paths: GatewayDaemonPaths;
+};
+
+/** CLI entrypoint path for spawning `openpaw gateway dev` in a detached process. */
+const OPENPAW_CLI_ENTRY = fileURLToPath(new URL("../cli/openpaw.tsx", import.meta.url));
+
+/**
+ * Canonical daemon state file locations under `~/.openpaw/gateway`.
+ */
+export function getGatewayDaemonPaths(): GatewayDaemonPaths {
+  const stateDir = join(homedir(), ".openpaw", "gateway");
+  return {
+    stateDir,
+    pidFile: join(stateDir, "gateway.pid"),
+    logFile: join(stateDir, "gateway.log"),
+    errFile: join(stateDir, "gateway.err.log"),
+  };
+}
+
+/**
+ * Ensures daemon state directory exists before reading/writing status files.
+ */
+function ensureDaemonStateDir(paths: GatewayDaemonPaths): void {
+  if (!existsSync(paths.stateDir)) {
+    mkdirSync(paths.stateDir, { recursive: true });
+  }
+}
+
+/**
+ * Parses daemon pid from disk. Returns `null` when missing, invalid, or unreadable.
+ */
+function readPid(paths: GatewayDaemonPaths): number | null {
+  if (!existsSync(paths.pidFile)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(paths.pidFile, "utf8").trim();
+    if (!/^\d+$/.test(raw)) {
+      return null;
+    }
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort liveness check using `kill(pid, 0)` semantics.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Deletes stale pid file when process is no longer alive.
+ */
+function cleanupStalePid(paths: GatewayDaemonPaths): void {
+  if (existsSync(paths.pidFile)) {
+    rmSync(paths.pidFile, { force: true });
+  }
+}
+
+/**
+ * Resolves current daemon status and auto-cleans stale pid state.
+ */
+export function getGatewayDaemonStatus(): GatewayDaemonStatus {
+  const paths = getGatewayDaemonPaths();
+  const pid = readPid(paths);
+  if (pid === null) {
+    return { state: "stopped", pid: null, paths };
+  }
+
+  if (isProcessAlive(pid)) {
+    return { state: "running", pid, paths };
+  }
+
+  cleanupStalePid(paths);
+  return { state: "stale", pid, paths };
+}
+
+/**
+ * Starts gateway in detached mode (`openpaw gateway dev`) if not already running.
+ */
+export function startGatewayDaemon(): StartGatewayDaemonResult {
+  const pre = getGatewayDaemonStatus();
+  if (pre.state === "running" && pre.pid !== null) {
+    return { status: "already_running", pid: pre.pid, paths: pre.paths };
+  }
+
+  const paths = pre.paths;
+  ensureDaemonStateDir(paths);
+
+  const outFd = openSync(paths.logFile, "a");
+  const errFd = openSync(paths.errFile, "a");
+  const child = spawn(process.execPath, [OPENPAW_CLI_ENTRY, "gateway", "dev"], {
+    detached: true,
+    stdio: ["ignore", outFd, errFd],
+    env: process.env,
+  });
+
+  child.unref();
+  closeSync(outFd);
+  closeSync(errFd);
+
+  if (child.pid === undefined) {
+    throw new Error("Failed to start gateway daemon: child process pid was unavailable.");
+  }
+
+  writeFileSync(paths.pidFile, `${child.pid}\n`, "utf8");
+  return { status: "started", pid: child.pid, paths };
+}
+
+/**
+ * Stops detached gateway daemon process if currently running.
+ */
+export function stopGatewayDaemon(): StopGatewayDaemonResult {
+  const status = getGatewayDaemonStatus();
+  const { paths } = status;
+
+  if (status.state !== "running" || status.pid === null) {
+    cleanupStalePid(paths);
+    return { status: "already_stopped", pid: status.pid, paths };
+  }
+
+  try {
+    process.kill(status.pid, "SIGTERM");
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to stop gateway daemon (pid ${status.pid}): ${message}`);
+  }
+
+  cleanupStalePid(paths);
+  return { status: "stopped", pid: status.pid, paths };
+}
+
+/**
+ * Returns the last `lineCount` lines from the selected daemon log file.
+ */
+export function readGatewayDaemonLog(lineCount = 80, stream: "stdout" | "stderr" = "stdout"): string {
+  const paths = getGatewayDaemonPaths();
+  const logPath = stream === "stdout" ? paths.logFile : paths.errFile;
+  if (!existsSync(logPath)) {
+    return "";
+  }
+
+  const raw = readFileSync(logPath, "utf8");
+  const lines = raw.split(/\r?\n/);
+  const tail = lines.slice(Math.max(lines.length - lineCount, 0));
+  return tail.join("\n").trim();
+}

package/gateway/index.ts

@@ -0,0 +1,18 @@
+export { createGatewayContext, type OpenPawGatewayContext } from "./bootstrap";
+export type { ChannelAdapter } from "./channel-adapter";
+export {
+  getGatewayDaemonPaths,
+  getGatewayDaemonStatus,
+  readGatewayDaemonLog,
+  startGatewayDaemon,
+  stopGatewayDaemon,
+} from "./daemon-manager";
+export { cliSessionKey, tuiSessionKey } from "./session-key";
+export { createMessagingChannelAdapters, runGatewayMessagingChannels, startGateway } from "./start-messaging";
+export {
+  createTelegramChannelAdapter,
+  deliverStreamingReply,
+  runTelegramGateway,
+  telegramSessionKey,
+} from "./telegram";
+export type { TelegramSessionListEntry } from "./telegram";

package/gateway/session-key.ts

@@ -0,0 +1,13 @@
+/**
+ * Session id for CLI / non-Telegram entrypoints.
+ */
+export function cliSessionKey(id = "main"): string {
+  return `cli:${id}`;
+}
+
+/**
+ * Session id for the local OpenTUI chat (separate from Telegram and other channels).
+ */
+export function tuiSessionKey(id = "main"): string {
+  return `tui:${id}`;
+}

package/gateway/slash-command-tokens.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared parsing for OpenPaw slash commands across channels (Telegram, TUI).
+ */
+
+/** Registered bot commands and reserved slash tokens, in menu order. */
+export const OPENPAW_SLASH_COMMAND_NAMES = [
+  "new",
+  "sessions",
+  "resume",
+  "reasoning",
+  "tool_calls",
+  "sandbox",
+] as const;
+
+export const RESERVED_SLASH_COMMANDS = new Set(
+  OPENPAW_SLASH_COMMAND_NAMES.map((name) => `/${name}`),
+);
+
+/**
+ * Comma-separated list of supported slash commands for user-facing error text.
+ */
+export function formatAvailableOpenPawSlashCommandsForUser(): string {
+  return OPENPAW_SLASH_COMMAND_NAMES.map((n) => `/${n}`).join(", ");
+}
+
+/**
+ * First whitespace-separated token of the message, lowercased; strips optional `@botname` suffix.
+ */
+export function firstCommandToken(text: string): string | undefined {
+  return text.trim().split(/\s/)[0]?.split("@")[0]?.toLowerCase();
+}
+
+/**
+ * Text after the first whitespace-separated token (command + args).
+ */
+export function restAfterCommand(text: string): string {
+  const tokens = text.trim().split(/\s+/).filter(Boolean);
+  return tokens.slice(1).join(" ").trim();
+}

package/gateway/start-messaging.ts

@@ -0,0 +1,40 @@
+import { createGatewayContext, type OpenPawGatewayContext } from "./bootstrap";
+import type { ChannelAdapter } from "./channel-adapter";
+import { createTelegramChannelAdapter } from "./telegram/adapter";
+
+/**
+ * Build all messaging adapters that are activated by the current config.
+ */
+export function createMessagingChannelAdapters(ctx: OpenPawGatewayContext): ChannelAdapter[] {
+  const adapters: ChannelAdapter[] = [];
+
+  const telegramToken = ctx.config.channels?.telegram?.botToken;
+  if (telegramToken) {
+    adapters.push(createTelegramChannelAdapter(ctx));
+  }
+
+  return adapters;
+}
+
+/**
+ * Start every configured messaging adapter in parallel (shared `AgentRuntime`).
+ */
+export async function runGatewayMessagingChannels(ctx: OpenPawGatewayContext): Promise<void> {
+  const adapters = createMessagingChannelAdapters(ctx);
+  if (adapters.length === 0) {
+    throw new Error(
+      "No messaging channels configured. Add e.g. channels.telegram.botToken to ~/.openpaw/config.yaml",
+    );
+  }
+
+  console.log(`OpenPaw gateway starting: ${adapters.map((a) => a.id).join(", ")}`);
+  await Promise.all(adapters.map((a) => a.run()));
+}
+
+/**
+ * Bootstrap and run all messaging channels.
+ */
+export async function startGateway(): Promise<void> {
+  const ctx = await createGatewayContext();
+  await runGatewayMessagingChannels(ctx);
+}

package/gateway/telegram/active-thread-store.ts

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getSessionsDir } from "../../config/paths";
+import { TELEGRAM_ACTIVE_THREADS_FILENAME } from "./constants";
+
+type ActiveThreadsState = Record<string, string>;
+
+function activeThreadsPath(): string {
+  return join(getSessionsDir(), TELEGRAM_ACTIVE_THREADS_FILENAME);
+}
+
+async function readActiveThreads(): Promise<ActiveThreadsState> {
+  const path = activeThreadsPath();
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const raw = await Bun.file(path).text();
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+    const out: ActiveThreadsState = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (typeof v === "string" && v.length > 0) {
+        out[k] = v;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+async function writeActiveThreads(state: ActiveThreadsState): Promise<void> {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  await Bun.write(activeThreadsPath(), JSON.stringify(state, null, 2));
+}
+
+/**
+ * OpenPaw persistence session id for this Telegram chat (legacy or threaded).
+ */
+export async function getTelegramPersistenceSessionId(chatId: number): Promise<string> {
+  const state = await readActiveThreads();
+  const uuid = state[String(chatId)];
+  if (uuid) {
+    return `telegram:${chatId}:${uuid}`;
+  }
+  return `telegram:${chatId}`;
+}
+
+/**
+ * Starts a new thread: new uuid in the active map. Returns the new persistence session id.
+ */
+export async function startNewTelegramThread(chatId: number): Promise<string> {
+  const uuid = crypto.randomUUID();
+  const state = await readActiveThreads();
+  state[String(chatId)] = uuid;
+  await writeActiveThreads(state);
+  return `telegram:${chatId}:${uuid}`;
+}
+
+/**
+ * Points the chat at an existing persistence session (legacy or thread file).
+ */
+export async function setActiveTelegramSession(
+  chatId: number,
+  persistenceSessionId: string,
+): Promise<void> {
+  const legacy = `telegram:${chatId}`;
+  const state = await readActiveThreads();
+  if (persistenceSessionId === legacy) {
+    delete state[String(chatId)];
+  } else {
+    const prefix = `${legacy}:`;
+    if (!persistenceSessionId.startsWith(prefix)) {
+      throw new Error("Session does not belong to this chat");
+    }
+    const uuid = persistenceSessionId.slice(prefix.length);
+    if (!uuid) {
+      throw new Error("Invalid thread id");
+    }
+    state[String(chatId)] = uuid;
+  }
+  await writeActiveThreads(state);
+}