@llblab/pi-telegram 0.19.2 → 0.20.0

package/lib/config.ts

@@ -6,27 +6,19 @@
 
 import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { resolveAgentDir, resolveTelegramConfigPath } from "./paths.ts";
 
 import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 
 const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
 
-function getAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
-}
-
 function getConfigPath(): string {
-  return join(getAgentDir(), "telegram.json");
+  return resolveTelegramConfigPath();
 }
 
 export type TelegramOutboundCommandTemplateConfig =
-  | string
-  | CommandTemplateObjectConfig;
+  string | CommandTemplateObjectConfig;
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
   type?: string;
   match?: string | string[];
@@ -75,12 +67,88 @@ export interface TelegramConfig {
     sendTranscript?: boolean;
   };
   time?: TelegramTimeConfig;
+  /** Named bot/session profiles (e.g. "work", "omp"). */
+  profiles?: Record<string, TelegramBotProfile>;
+}
+
+/**
+ * Per-profile bot/session identity fields.
+ * Stored under `profiles.<name>` in telegram.json.
+ * Shared bridge settings (inboundHandlers, outboundHandlers, voice, time,
+ * assistant, proactivePush) stay at the top level.
+ */
+export interface TelegramBotProfile {
+  botToken: string;
+  botUsername?: string;
+  botId?: number;
+  allowedUserId?: number;
+  lastUpdateId?: number;
+}
+
+/** Profile names must be lowercase letters, digits, hyphens, underscores; max 32 chars. */
+const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+const TELEGRAM_RESERVED_PROFILE_NAMES: ReadonlySet<string> = new Set([
+  "default",
+  "main",
+  "active",
+]);
+
+export function isValidTelegramProfileName(name: string): boolean {
+  return (
+    TELEGRAM_PROFILE_NAME_PATTERN.test(name) &&
+    !TELEGRAM_RESERVED_PROFILE_NAMES.has(name)
+  );
+}
+
+/**
+ * Resolve the effective config for a named (or default) profile.
+ * Returns bot/session fields from the named profile, falling back to
+ * top-level fields for the default profile. Shared bridge settings
+ * always come from the top level.
+ */
+export function resolveTelegramActiveProfile(
+  config: TelegramConfig,
+  profileName?: string,
+): {
+  botToken?: string;
+  botUsername?: string;
+  botId?: number;
+  allowedUserId?: number;
+  lastUpdateId?: number;
+} {
+  if (!profileName || !config.profiles?.[profileName]) {
+    return {
+      botToken: config.botToken,
+      botUsername: config.botUsername,
+      botId: config.botId,
+      allowedUserId: config.allowedUserId,
+      lastUpdateId: config.lastUpdateId,
+    };
+  }
+  const profile = config.profiles[profileName];
+  return {
+    botToken: profile.botToken,
+    botUsername: profile.botUsername,
+    botId: profile.botId,
+    allowedUserId: profile.allowedUserId,
+    lastUpdateId: profile.lastUpdateId,
+  };
+}
+
+/** List defined profile names. */
+export function getTelegramProfileNames(
+  config: TelegramConfig,
+): string[] {
+  return Object.keys(config.profiles ?? {}).sort();
 }
 
 export interface TelegramConfigStore {
   get: () => TelegramConfig;
+  getStoredConfig: () => TelegramConfig;
   set: (config: TelegramConfig) => void;
   update: (mutate: (config: TelegramConfig) => void) => void;
+  activateProfile: (profileName: string | undefined) => boolean;
+  getActiveProfileName: () => string | undefined;
   getBotToken: () => string | undefined;
   hasBotToken: () => boolean;
   getAllowedUserId: () => number | undefined;
@@ -211,23 +279,85 @@ export async function writeTelegramConfig(
   await chmod(configPath, 0o600);
 }
 
+function getTelegramProfileFields(config: TelegramConfig): TelegramBotProfile | undefined {
+  const token = config.botToken?.trim();
+  if (!token) return undefined;
+  return {
+    botToken: token,
+    botUsername: config.botUsername,
+    botId: config.botId,
+    allowedUserId: config.allowedUserId,
+    lastUpdateId: config.lastUpdateId,
+  };
+}
+
+function applyTelegramProfile(
+  config: TelegramConfig,
+  profileName: string | undefined,
+): TelegramConfig {
+  if (!profileName) return config;
+  const profile = config.profiles?.[profileName];
+  if (!profile) return config;
+  return {
+    ...config,
+    botToken: profile.botToken,
+    botUsername: profile.botUsername,
+    botId: profile.botId,
+    allowedUserId: profile.allowedUserId,
+    lastUpdateId: profile.lastUpdateId,
+  };
+}
+
+function storeTelegramEffectiveConfig(
+  baseConfig: TelegramConfig,
+  nextConfig: TelegramConfig,
+  profileName: string | undefined,
+): TelegramConfig {
+  if (!profileName) return nextConfig;
+  const profile = getTelegramProfileFields(nextConfig);
+  const profiles = { ...(baseConfig.profiles ?? {}) };
+  if (profile) profiles[profileName] = profile;
+  else delete profiles[profileName];
+  return {
+    ...nextConfig,
+    botToken: baseConfig.botToken,
+    botUsername: baseConfig.botUsername,
+    botId: baseConfig.botId,
+    allowedUserId: baseConfig.allowedUserId,
+    lastUpdateId: baseConfig.lastUpdateId,
+    profiles: Object.keys(profiles).length > 0 ? profiles : undefined,
+  };
+}
+
 export function createTelegramConfigStore(
   options: TelegramConfigStoreOptions = {},
 ): TelegramConfigStore {
   let config: TelegramConfig = options.initialConfig ?? {};
-  const agentDir = options.agentDir ?? getAgentDir();
+  let activeProfileName: string | undefined;
+  const agentDir = options.agentDir ?? resolveAgentDir();
   const configPath = options.configPath ?? getConfigPath();
+  const getEffectiveConfig = () => applyTelegramProfile(config, activeProfileName);
+  const setEffectiveConfig = (nextConfig: TelegramConfig) => {
+    config = storeTelegramEffectiveConfig(config, nextConfig, activeProfileName);
+  };
   return {
-    get: () => config,
-    set: (nextConfig) => {
-      config = nextConfig;
-    },
+    get: getEffectiveConfig,
+    getStoredConfig: () => config,
+    set: setEffectiveConfig,
     update: (mutate) => {
-      mutate(config);
+      const nextConfig = getEffectiveConfig();
+      mutate(nextConfig);
+      setEffectiveConfig(nextConfig);
+    },
+    activateProfile: (profileName) => {
+      if (profileName && !config.profiles?.[profileName]) return false;
+      activeProfileName = profileName;
+      return true;
     },
-    getBotToken: () => config.botToken,
-    hasBotToken: () => !!config.botToken,
-    getAllowedUserId: () => config.allowedUserId,
+    getActiveProfileName: () => activeProfileName,
+    getBotToken: () => getEffectiveConfig().botToken,
+    hasBotToken: () => !!getEffectiveConfig().botToken,
+    getAllowedUserId: () => getEffectiveConfig().allowedUserId,
     getInboundHandlers: () => [
       ...(config.inboundHandlers ?? []),
       ...(config.attachmentHandlers ?? []),
@@ -235,7 +365,9 @@ export function createTelegramConfigStore(
     getAttachmentHandlers: () => config.attachmentHandlers,
     getOutboundHandlers: () => config.outboundHandlers,
     setAllowedUserId: (userId) => {
-      config.allowedUserId = userId;
+      const nextConfig = getEffectiveConfig();
+      nextConfig.allowedUserId = userId;
+      setEffectiveConfig(nextConfig);
     },
     load: async () => {
       config = await readTelegramConfig(configPath, {
@@ -247,9 +379,18 @@ export function createTelegramConfigStore(
           });
         },
       });
+      if (activeProfileName && !config.profiles?.[activeProfileName]) {
+        activeProfileName = undefined;
+      }
     },
-    persist: async (nextConfig = config) => {
-      await writeTelegramConfig(agentDir, configPath, nextConfig);
+    persist: async (nextConfig = getEffectiveConfig()) => {
+      const storedConfig = storeTelegramEffectiveConfig(
+        config,
+        nextConfig,
+        activeProfileName,
+      );
+      config = storedConfig;
+      await writeTelegramConfig(agentDir, configPath, storedConfig);
     },
   };
 }
@@ -481,9 +622,7 @@ export function createTelegramConfigControls(
 }
 
 export type TelegramAuthorizationState =
-  | { kind: "pair"; userId: number }
-  | { kind: "allow" }
-  | { kind: "deny" };
+  { kind: "pair"; userId: number } | { kind: "allow" } | { kind: "deny" };
 
 export interface TelegramUserPairingDeps<TContext> {
   allowedUserId?: number;

package/lib/locks.ts

@@ -12,20 +12,38 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname } from "node:path";
+import { resolveTelegramLocksPath } from "./paths.ts";
 
 export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 5_000;
+const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
+const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
 
-function getAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
+function getLocksPath(): string {
+  return resolveTelegramLocksPath();
 }
 
-function getLocksPath(): string {
-  return join(getAgentDir(), "locks.json");
+/**
+ * Resolve the scoped lock key for the active Telegram profile.
+ * Default profile → @llblab/pi-telegram
+ * Named profile → @llblab/pi-telegram:<name>
+ */
+export function resolveTelegramLockKey(activeProfile?: string): string {
+  if (activeProfile) return `${TELEGRAM_LOCK_KEY}:${activeProfile}`;
+  return TELEGRAM_LOCK_KEY;
+}
+
+export interface TelegramActiveProfileGetter {
+  getActiveProfileName: () => string | undefined;
+}
+
+export function createTelegramLockKeyResolver(
+  activeProfile: TelegramActiveProfileGetter,
+): () => string {
+  return function getTelegramLockKey() {
+    return resolveTelegramLockKey(activeProfile.getActiveProfileName());
+  };
 }
 
 export interface TelegramLockEntry {
@@ -81,7 +99,7 @@ export interface TelegramLockContextStore<
 }
 
 export interface TelegramLockRuntimeOptions {
-  key?: string;
+  key?: string | (() => string | undefined);
   locksPath?: string;
   pid?: number;
   isProcessAlive?: (pid: number) => boolean;
@@ -104,23 +122,46 @@ export function readLocks(path = getLocksPath()): Record<string, unknown> {
   }
 }
 
+function isRetryableLockWriteError(error: unknown): boolean {
+  const code = (error as { code?: unknown })?.code;
+  return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+
+function sleepSync(ms: number): void {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
 export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
-  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    renameSync(tempPath, path);
-  } catch (error) {
+  const payload = `${JSON.stringify(locks, null, 2)}\n`;
+  let lastError: unknown;
+  for (let attempt = 0; attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+    const tempPath = `${path}.${process.pid}.${Date.now()}.${attempt}.tmp`;
     try {
-      unlinkSync(tempPath);
-    } catch {
-      /* best effort */
+      writeFileSync(tempPath, payload, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+      renameSync(tempPath, path);
+      return;
+    } catch (error) {
+      lastError = error;
+      try {
+        unlinkSync(tempPath);
+      } catch {
+        /* best effort */
+      }
+      if (
+        !isRetryableLockWriteError(error) ||
+        attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
+      ) {
+        throw error;
+      }
+      sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
     }
-    throw error;
   }
+  throw lastError;
 }
 
 export function parseTelegramLockEntry(
@@ -238,10 +279,18 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     nowMs: getNowMs(),
     staleHeartbeatMs: options.staleHeartbeatMs,
   });
-  const readLock = () => parseTelegramLockEntry(readLocks(locksPath)[key]);
+  const resolveEffectiveKey = (): string => {
+    if (typeof key === "function") return key() || TELEGRAM_LOCK_KEY;
+    return key;
+  };
+  const readLock = () => {
+    const effectiveKey = resolveEffectiveKey();
+    return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+  };
   const writeLock = (lock: TelegramLockEntry) => {
+    const effectiveKey = resolveEffectiveKey();
     const locks = readLocks(locksPath);
-    locks[key] = lock;
+    locks[effectiveKey] = lock;
     writeLocks(locksPath, locks);
   };
   return {
@@ -262,7 +311,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
       const state = getLockState(readLock(), pid, isAlive, stateOptions());
       if (state.kind === "active-here" || state.kind === "stale") {
         const locks = readLocks(locksPath);
-        delete locks[key];
+        delete locks[resolveEffectiveKey()];
         writeLocks(locksPath, locks);
       }
       return state;
@@ -411,7 +460,11 @@ export function createTelegramLockedPollingRuntime<
     const owner = snapshotLockContext(ctx);
     stopOwnershipWatcher();
     ownershipInterval = setInterval(() => {
-      if (deps.lock.refresh(owner)) return;
+      try {
+        if (deps.lock.refresh(owner)) return;
+      } catch (error) {
+        deps.recordRuntimeEvent?.("lock", error, { phase: "refresh" });
+      }
       stopAfterOwnershipLoss();
     }, ownershipCheckMs);
     ownershipInterval.unref?.();

package/lib/{runtime-log.ts → logs.ts}

@@ -1,7 +1,7 @@
 /**
- * Telegram runtime JSONL diagnostics log
+ * Telegram diagnostics logs
  * Zones: telegram diagnostics, filesystem, session observability
- * Owns session-local append-only runtime evidence for debugging without becoming routing state
+ * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
  */
 
 import {
@@ -12,8 +12,13 @@ import {
   writeFileSync,
   appendFile,
 } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname } from "node:path";
+import {
+  resolveAgentDir,
+  resolveTelegramProfileTempFilePath,
+} from "./paths.ts";
+
+export type TelegramLogPathInput = string | (() => string);
 
 export interface TelegramRuntimeJsonlEvent {
   at: number;
@@ -23,14 +28,14 @@ export interface TelegramRuntimeJsonlEvent {
 }
 
 export interface TelegramRuntimeJsonlLogOptions {
-  path?: string;
-  previousPath?: string;
+  path?: TelegramLogPathInput;
+  previousPath?: TelegramLogPathInput;
   maxBytes?: number;
   getNowMs?: () => number;
 }
 
 export interface TelegramRuntimeJsonlLog {
-  path: string;
+  getPath: () => string;
   reset: (reason: string, scope?: Record<string, unknown>) => void;
   resetIfScopeChanged: (
     scopeKey: string,
@@ -42,21 +47,36 @@ export interface TelegramRuntimeJsonlLog {
 
 const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
 
-function getAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
+export function getTelegramRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "logs",
+    "jsonl",
+    agentDir,
+    profileName,
+  );
 }
 
-export function getTelegramRuntimeLogPath(agentDir = getAgentDir()): string {
-  return join(agentDir, "tmp", "telegram", "logs.jsonl");
+export function getTelegramPreviousRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "logs",
+    "previous.jsonl",
+    agentDir,
+    profileName,
+  );
 }
 
 function safeJsonLine(value: unknown): string {
   return JSON.stringify(value, (_key, item) => {
     if (item instanceof Error) return item.message;
     if (typeof item === "bigint") return item.toString();
-    if (typeof item === "function" || typeof item === "symbol") return undefined;
+    if (typeof item === "function" || typeof item === "symbol")
+      return undefined;
     return item;
   });
 }
@@ -64,27 +84,35 @@ function safeJsonLine(value: unknown): string {
 export function createTelegramRuntimeJsonlLog(
   options: TelegramRuntimeJsonlLogOptions = {},
 ): TelegramRuntimeJsonlLog {
-  const path = options.path ?? getTelegramRuntimeLogPath();
-  const previousPath =
-    options.previousPath ?? path.replace(/\.jsonl$/u, ".previous.jsonl");
+  const resolvePath = () =>
+    typeof options.path === "function"
+      ? options.path()
+      : (options.path ?? getTelegramRuntimeLogPath());
+  const resolvePreviousPath = () => {
+    if (typeof options.previousPath === "function") return options.previousPath();
+    if (options.previousPath) return options.previousPath;
+    return resolvePath().replace(/\.jsonl$/u, ".previous.jsonl");
+  };
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
   const getNowMs = options.getNowMs ?? Date.now;
-  let scopeKey: string | undefined;
+  const scopeKeys = new Map<string, string | undefined>();
   let pending: Promise<void> = Promise.resolve();
 
-  const ensureParent = () => {
+  const ensureParent = (path: string) => {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   };
 
-  const preserveCurrentLog = () => {
+  const preserveCurrentLog = (path: string, previousPath: string) => {
     if (!existsSync(path)) return;
     mkdirSync(dirname(previousPath), { recursive: true, mode: 0o700 });
     copyFileSync(path, previousPath);
   };
 
   const writeReset = (reason: string, scope?: Record<string, unknown>) => {
-    ensureParent();
-    preserveCurrentLog();
+    const path = resolvePath();
+    const previousPath = resolvePreviousPath();
+    ensureParent(path);
+    preserveCurrentLog(path, previousPath);
     writeFileSync(
       path,
       safeJsonLine({
@@ -102,7 +130,8 @@ export function createTelegramRuntimeJsonlLog(
     pending = pending
       .catch(() => undefined)
       .then(async () => {
-        ensureParent();
+        const path = resolvePath();
+        ensureParent(path);
         if (existsSync(path) && statSync(path).size > maxBytes) {
           writeReset("max-bytes", { maxBytes });
         }
@@ -116,9 +145,10 @@ export function createTelegramRuntimeJsonlLog(
   };
 
   return {
-    path,
+    getPath: resolvePath,
     reset(reason, scope) {
-      scopeKey = scope ? safeJsonLine(scope) : undefined;
+      const path = resolvePath();
+      scopeKeys.set(path, scope ? safeJsonLine(scope) : undefined);
       try {
         writeReset(reason, scope);
       } catch {
@@ -126,8 +156,9 @@ export function createTelegramRuntimeJsonlLog(
       }
     },
     resetIfScopeChanged(nextScopeKey, reason, scope) {
-      if (scopeKey === nextScopeKey) return;
-      scopeKey = nextScopeKey;
+      const path = resolvePath();
+      if (scopeKeys.get(path) === nextScopeKey) return;
+      scopeKeys.set(path, nextScopeKey);
       try {
         writeReset(reason, scope);
       } catch {