openclaw-telegram-manager 1.0.0

package/src/commands/sync.ts

@@ -0,0 +1,46 @@
+import { readRegistry } from '../lib/registry.js';
+import { checkAuthorization } from '../lib/auth.js';
+import { htmlEscape } from '../lib/security.js';
+import { generateInclude } from '../lib/include-generator.js';
+import { triggerRestart } from '../lib/config-restart.js';
+import type { CommandContext, CommandResult } from './help.js';
+
+export async function handleSync(ctx: CommandContext): Promise<CommandResult> {
+  const { workspaceDir, configDir, userId, rpc, logger } = ctx;
+
+  if (!userId) {
+    return { text: 'Missing context: userId not available.' };
+  }
+
+  const registry = readRegistry(workspaceDir);
+
+  // Auth check (admin tier)
+  const auth = checkAuthorization(userId, 'sync', registry);
+  if (!auth.authorized) {
+    return { text: auth.message ?? 'Not authorized.' };
+  }
+
+  try {
+    generateInclude(workspaceDir, registry, configDir);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      text: `Sync failed: ${htmlEscape(msg)}`,
+      parseMode: 'HTML',
+    };
+  }
+
+  const restartResult = await triggerRestart(rpc, logger);
+
+  const topicCount = Object.keys(registry.topics).length;
+  let text = `Include regenerated from ${topicCount} topic(s). Config synced.`;
+
+  if (!restartResult.success && restartResult.fallbackMessage) {
+    text += '\n' + restartResult.fallbackMessage;
+  }
+
+  return {
+    text,
+    parseMode: 'HTML',
+  };
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,64 @@
+import * as path from 'node:path';
+import { readRegistry, withRegistry } from '../lib/registry.js';
+import { checkAuthorization } from '../lib/auth.js';
+import { topicKey, CAPSULE_VERSION } from '../lib/types.js';
+import { htmlEscape } from '../lib/security.js';
+import { upgradeCapsule } from '../lib/capsule.js';
+import type { CommandContext, CommandResult } from './help.js';
+
+export async function handleUpgrade(ctx: CommandContext): Promise<CommandResult> {
+  const { workspaceDir, userId, groupId, threadId } = ctx;
+
+  if (!userId || !groupId || !threadId) {
+    return { text: 'Missing context: userId, groupId, or threadId not available.' };
+  }
+
+  const registry = readRegistry(workspaceDir);
+
+  // Auth check (user tier)
+  const auth = checkAuthorization(userId, 'upgrade', registry);
+  if (!auth.authorized) {
+    return { text: auth.message ?? 'Not authorized.' };
+  }
+
+  const key = topicKey(groupId, threadId);
+  const entry = registry.topics[key];
+
+  if (!entry) {
+    return { text: 'This topic is not registered. Run /topic init first.' };
+  }
+
+  if (entry.capsuleVersion >= CAPSULE_VERSION) {
+    return {
+      text: `Topic <code>${htmlEscape(entry.slug)}</code> is already at capsule version ${CAPSULE_VERSION}. No upgrade needed.`,
+      parseMode: 'HTML',
+    };
+  }
+
+  const projectsBase = path.join(workspaceDir, 'projects');
+  const result = upgradeCapsule(projectsBase, entry.slug, entry.type, entry.capsuleVersion);
+
+  if (!result.upgraded) {
+    return {
+      text: `No upgrade needed for <code>${htmlEscape(entry.slug)}</code>.`,
+      parseMode: 'HTML',
+    };
+  }
+
+  // Update capsule version in registry
+  await withRegistry(workspaceDir, (data) => {
+    const topic = data.topics[key];
+    if (topic) {
+      topic.capsuleVersion = result.newVersion;
+    }
+  });
+
+  const addedList = result.addedFiles.length > 0
+    ? `\nAdded files: ${result.addedFiles.map((f) => htmlEscape(f)).join(', ')}`
+    : '\nNo new files added.';
+
+  return {
+    text: `Topic <code>${htmlEscape(entry.slug)}</code> upgraded from v${entry.capsuleVersion} to v${result.newVersion}.${addedList}`,
+    parseMode: 'HTML',
+  };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { Type } from '@sinclair/typebox';
+import { createTopicManagerTool } from './tool.js';
+
+export default function register(api: {
+  logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+  configDir?: string;
+  workspaceDir?: string;
+  rpc?: { call(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> } | null;
+  pluginConfig?: { configDir?: string; workspaceDir?: string };
+  registerTool(def: {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute(id: string, params: { command: string }, context?: Record<string, unknown>): Promise<unknown>;
+  }): void;
+}): void {
+  const configDir = api.configDir ?? api.pluginConfig?.configDir;
+  const workspaceDir = api.workspaceDir ?? api.pluginConfig?.workspaceDir;
+
+  if (!configDir || !workspaceDir) {
+    api.logger.error(
+      'telegram-manager: configDir or workspaceDir not available. Plugin cannot initialize.',
+    );
+    return;
+  }
+
+  const tool = createTopicManagerTool({
+    logger: api.logger,
+    configDir,
+    workspaceDir,
+    rpc: api.rpc,
+  });
+
+  api.registerTool({
+    name: 'topic_manager',
+    description:
+      'Manage Telegram forum topics as deterministic workcells. Sub-commands: init, doctor, list, status, sync, rename, upgrade, snooze, archive, unarchive, help.',
+    parameters: Type.Object({
+      command: Type.String({
+        description:
+          "Sub-command and arguments (e.g., 'init', 'doctor --all', 'rename new-slug')",
+      }),
+    }),
+    async execute(
+      id: string,
+      params: { command: string },
+      context?: Record<string, unknown>,
+    ) {
+      return tool.execute(id, params, context);
+    },
+  });
+
+  api.logger.info('telegram-manager plugin loaded');
+}

package/src/lib/audit.ts

@@ -0,0 +1,44 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { AuditEntry } from './types.js';
+
+const AUDIT_FILENAME = 'audit.jsonl';
+const FILE_MODE = 0o600;
+
+/**
+ * Append an audit entry to the audit.jsonl file.
+ * Creates the file if it does not exist. Each entry is a single JSON line.
+ * File permissions are set to 0600.
+ */
+export function appendAudit(workspaceDir: string, entry: AuditEntry): void {
+  const auditPath = path.join(workspaceDir, 'projects', AUDIT_FILENAME);
+  const line = JSON.stringify(entry) + '\n';
+
+  const fd = fs.openSync(auditPath, 'a', FILE_MODE);
+  try {
+    fs.writeSync(fd, line);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  // Ensure permissions are correct even if file already existed
+  fs.chmodSync(auditPath, FILE_MODE);
+}
+
+/**
+ * Build an AuditEntry with the current timestamp.
+ */
+export function buildAuditEntry(
+  userId: string,
+  cmd: string,
+  slug: string,
+  detail: string,
+): AuditEntry {
+  return {
+    ts: new Date().toISOString(),
+    userId,
+    cmd,
+    slug,
+    detail,
+  };
+}

package/src/lib/auth.ts

@@ -0,0 +1,96 @@
+import type { Registry } from './types.js';
+
+// ── Authorization tiers ────────────────────────────────────────────────
+
+export const AuthTier = {
+  User: 'User',
+  Admin: 'Admin',
+} as const;
+
+export type AuthTier = (typeof AuthTier)[keyof typeof AuthTier];
+
+// ── Command-to-tier mapping ────────────────────────────────────────────
+
+const ADMIN_COMMANDS = new Set([
+  'doctor --all',
+  'doctor-all',
+  'list',
+  'sync',
+  'rename',
+  'archive',
+  'unarchive',
+]);
+
+const USER_COMMANDS = new Set([
+  'init',
+  'doctor',
+  'status',
+  'help',
+  'upgrade',
+  'snooze',
+]);
+
+/**
+ * Get the authorization tier for a command.
+ * Defaults to Admin for unknown commands.
+ */
+export function getCommandTier(command: string): AuthTier {
+  const normalized = command.toLowerCase().trim();
+  if (USER_COMMANDS.has(normalized)) return AuthTier.User;
+  if (ADMIN_COMMANDS.has(normalized)) return AuthTier.Admin;
+  // Unknown commands default to admin tier (principle of least privilege)
+  return AuthTier.Admin;
+}
+
+// ── Authorization check ────────────────────────────────────────────────
+
+export interface AuthResult {
+  authorized: boolean;
+  message?: string;
+}
+
+/**
+ * Check if a user is authorized to run a command.
+ *
+ * Logic:
+ * - Admin-tier: user must be in topicManagerAdmins
+ * - User-tier: user must be in topicAllowFrom OR topicManagerAdmins
+ * - Special case for init: if topicManagerAdmins is empty (first-time setup),
+ *   allow anyone — the first user to init becomes the default admin.
+ */
+export function checkAuthorization(
+  userId: string,
+  command: string,
+  registry: Registry,
+  topicAllowFrom?: string[],
+): AuthResult {
+  const tier = getCommandTier(command);
+  const admins = registry.topicManagerAdmins;
+
+  // First-user bootstrap: if no admins set yet, allow anyone for init
+  if (command === 'init' && admins.length === 0) {
+    return { authorized: true };
+  }
+
+  const isAdmin = admins.includes(userId);
+
+  if (tier === AuthTier.Admin) {
+    if (isAdmin) return { authorized: true };
+    return {
+      authorized: false,
+      message: 'Not authorized. Ask a telegram-manager admin to run this command.',
+    };
+  }
+
+  // User tier: allowed if admin or in topicAllowFrom
+  if (isAdmin) return { authorized: true };
+
+  if (topicAllowFrom && topicAllowFrom.includes(userId)) {
+    return { authorized: true };
+  }
+
+  return {
+    authorized: false,
+    message: 'Not authorized. Ask a telegram-manager admin to run this command.',
+  };
+}

package/src/lib/capsule.ts

@@ -0,0 +1,206 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { BASE_FILES, OVERLAY_FILES, CAPSULE_VERSION } from './types.js';
+import type { TopicType } from './types.js';
+import { jailCheck, rejectSymlink } from './security.js';
+
+// ── Template content (embedded string constants) ───────────────────────
+// These are the source-of-truth defaults, matching src/templates/.
+
+const BASE_TEMPLATES: Record<string, (slug: string) => string> = {
+  'README.md': (slug) =>
+    `# ${slug}\n\n_Describe what this topic is about._\n`,
+
+  'STATUS.md': (slug) =>
+    `# Status: ${slug}\n\n## Last done (UTC)\n\n${new Date().toISOString()}\n\n_No work recorded yet._\n\n## Next 3 actions\n\n1. [T-1] _Define first task in TODO.md_\n2. [T-2] _Define second task in TODO.md_\n3. [T-3] _Define third task in TODO.md_\n`,
+
+  'TODO.md': (slug) =>
+    `# TODO: ${slug}\n\n## Backlog\n\n- [T-1] _First task placeholder — replace with actual task_\n- [T-2] _Second task placeholder — replace with actual task_\n- [T-3] _Third task placeholder — replace with actual task_\n\n## Completed\n\n_None yet._\n`,
+
+  'COMMANDS.md': (slug) =>
+    `# Commands: ${slug}\n\n_Build, deploy, test, and other commands for this topic. Kept here so they're not lost on reset._\n`,
+
+  'LINKS.md': (slug) =>
+    `# Links: ${slug}\n\n_URLs, paths, and service endpoints for this topic._\n`,
+
+  'CRON.md': (slug) =>
+    `# Cron: ${slug}\n\n_Cron job IDs and schedules for this topic._\n`,
+
+  'NOTES.md': (slug) =>
+    `# Notes: ${slug}\n\n_Anything worth remembering about this topic._\n`,
+};
+
+const OVERLAY_TEMPLATES: Record<string, (slug: string) => string> = {
+  'ARCHITECTURE.md': (slug) =>
+    `# Architecture: ${slug}\n\n_Components, data flow, dependencies, and design decisions._\n`,
+
+  'DEPLOY.md': (slug) =>
+    `# Deployment: ${slug}\n\n_Environments, deployment steps, rollback procedures, and infra details._\n`,
+
+  'SOURCES.md': (slug) =>
+    `# Sources: ${slug}\n\n_Papers, articles, datasets, APIs, and other reference material._\n`,
+
+  'FINDINGS.md': (slug) =>
+    `# Findings: ${slug}\n\n_Conclusions, insights, data summaries, and recommendations._\n`,
+
+  'CAMPAIGNS.md': (slug) =>
+    `# Campaigns: ${slug}\n\n_Active campaigns, target audiences, channels, timelines, and budgets._\n`,
+
+  'METRICS.md': (slug) =>
+    `# Metrics: ${slug}\n\n_KPIs, conversion rates, engagement stats, and performance data._\n`,
+};
+
+// ── File permissions ───────────────────────────────────────────────────
+
+const CAPSULE_FILE_MODE = 0o640;
+
+// ── Scaffold ───────────────────────────────────────────────────────────
+
+/**
+ * Scaffold a new capsule directory with base kit + type overlays.
+ * Uses fs.mkdirSync with exclusive flag as the atomic reservation mechanism.
+ * Throws if the directory already exists (collision).
+ */
+export function scaffoldCapsule(
+  projectsBase: string,
+  slug: string,
+  type: TopicType,
+): void {
+  const capsuleDir = path.join(projectsBase, slug);
+
+  // Path jail check
+  if (!jailCheck(projectsBase, slug)) {
+    throw new Error(`Path escapes projects directory: ${slug}`);
+  }
+
+  // Symlink check on parent
+  if (rejectSymlink(projectsBase)) {
+    throw new Error(`Projects base is a symlink: ${projectsBase}`);
+  }
+
+  // Atomic directory creation (exclusive)
+  fs.mkdirSync(capsuleDir, { recursive: false });
+
+  // Write base files
+  for (const file of BASE_FILES) {
+    const templateFn = BASE_TEMPLATES[file];
+    if (templateFn) {
+      const filePath = path.join(capsuleDir, file);
+      fs.writeFileSync(filePath, templateFn(slug), { mode: CAPSULE_FILE_MODE });
+    }
+  }
+
+  // Write overlay files for the type
+  const overlays = OVERLAY_FILES[type];
+  for (const file of overlays) {
+    const templateFn = OVERLAY_TEMPLATES[file];
+    if (templateFn) {
+      const filePath = path.join(capsuleDir, file);
+      fs.writeFileSync(filePath, templateFn(slug), { mode: CAPSULE_FILE_MODE });
+    }
+  }
+}
+
+// ── Upgrade ────────────────────────────────────────────────────────────
+
+export interface UpgradeResult {
+  upgraded: boolean;
+  newVersion: number;
+  addedFiles: string[];
+}
+
+/**
+ * Upgrade an existing capsule to the latest template version.
+ * Adds missing files without overwriting existing ones.
+ */
+export function upgradeCapsule(
+  projectsBase: string,
+  slug: string,
+  type: TopicType,
+  currentVersion: number,
+): UpgradeResult {
+  if (currentVersion >= CAPSULE_VERSION) {
+    return { upgraded: false, newVersion: currentVersion, addedFiles: [] };
+  }
+
+  const capsuleDir = path.join(projectsBase, slug);
+
+  if (!jailCheck(projectsBase, slug)) {
+    throw new Error(`Path escapes projects directory: ${slug}`);
+  }
+
+  if (rejectSymlink(capsuleDir)) {
+    throw new Error(`Capsule directory is a symlink: ${capsuleDir}`);
+  }
+
+  const addedFiles: string[] = [];
+
+  // Add missing base files
+  for (const file of BASE_FILES) {
+    const filePath = path.join(capsuleDir, file);
+    if (!fs.existsSync(filePath)) {
+      const templateFn = BASE_TEMPLATES[file];
+      if (templateFn) {
+        fs.writeFileSync(filePath, templateFn(slug), { mode: CAPSULE_FILE_MODE });
+        addedFiles.push(file);
+      }
+    }
+  }
+
+  // Add missing overlay files
+  const overlays = OVERLAY_FILES[type];
+  for (const file of overlays) {
+    const filePath = path.join(capsuleDir, file);
+    if (!fs.existsSync(filePath)) {
+      const templateFn = OVERLAY_TEMPLATES[file];
+      if (templateFn) {
+        fs.writeFileSync(filePath, templateFn(slug), { mode: CAPSULE_FILE_MODE });
+        addedFiles.push(file);
+      }
+    }
+  }
+
+  return {
+    upgraded: true,
+    newVersion: CAPSULE_VERSION,
+    addedFiles,
+  };
+}
+
+// ── Validate ───────────────────────────────────────────────────────────
+
+export interface CapsuleValidation {
+  missing: string[];
+  present: string[];
+}
+
+/**
+ * Validate that a capsule has all expected files.
+ * Returns lists of present and missing files.
+ */
+export function validateCapsule(
+  projectsBase: string,
+  slug: string,
+  type: TopicType,
+): CapsuleValidation {
+  const capsuleDir = path.join(projectsBase, slug);
+
+  if (!jailCheck(projectsBase, slug)) {
+    throw new Error(`Path escapes projects directory: ${slug}`);
+  }
+
+  const expectedFiles = [...BASE_FILES, ...OVERLAY_FILES[type]];
+  const missing: string[] = [];
+  const present: string[] = [];
+
+  for (const file of expectedFiles) {
+    const filePath = path.join(capsuleDir, file);
+    if (fs.existsSync(filePath)) {
+      present.push(file);
+    } else {
+      missing.push(file);
+    }
+  }
+
+  return { missing, present };
+}

package/src/lib/config-restart.ts

@@ -0,0 +1,167 @@
+// ── Config restart via config.patch no-op ──────────────────────────────
+//
+// Triggers Gateway restart by patching a no-op value, which causes
+// OpenClaw to reload all $include files.
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+import type { RpcInterface, Logger } from './types.js';
+
+export type { RpcInterface, Logger };
+
+export interface RestartResult {
+  success: boolean;
+  fallbackMessage?: string;
+}
+
+// ── Cooldown tracking (module-level) ───────────────────────────────────
+
+const COOLDOWN_MS = 60_000; // 60 seconds
+let lastRestartTimestamp = 0;
+
+// ── Backoff config ─────────────────────────────────────────────────────
+
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000; // 1s, 2s, 4s exponential backoff
+
+// ── Main function ──────────────────────────────────────────────────────
+
+/**
+ * Trigger a Gateway restart via config.patch no-op.
+ *
+ * - Enforces a 60-second cooldown between calls
+ * - Retries up to 3 times on baseHash mismatch with exponential backoff
+ * - Falls back to a user message if RPC is unavailable
+ */
+export async function triggerRestart(
+  rpc: RpcInterface | null | undefined,
+  logger: Logger,
+): Promise<RestartResult> {
+  // Cooldown check
+  const now = Date.now();
+  if (now - lastRestartTimestamp < COOLDOWN_MS) {
+    const remainingSec = Math.ceil((COOLDOWN_MS - (now - lastRestartTimestamp)) / 1000);
+    logger.info(`Config restart cooldown active. ${remainingSec}s remaining.`);
+    return {
+      success: true, // Not a failure — just throttled
+    };
+  }
+
+  // If RPC is not available, return fallback
+  if (!rpc) {
+    return {
+      success: false,
+      fallbackMessage:
+        'Config updated. Run `openclaw gateway restart` or send SIGUSR1 to apply.',
+    };
+  }
+
+  // Retry loop with exponential backoff
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      // Get current config to capture baseHash
+      const configResult = await rpc.call('config.get', {});
+      const baseHash = configResult['baseHash'] as string | undefined;
+
+      if (!baseHash) {
+        logger.warn('config.get did not return baseHash; attempting patch without it');
+      }
+
+      // Patch with no-op change to trigger restart
+      const patchParams: Record<string, unknown> = {
+        patch: {
+          skills: {
+            entries: {
+              'telegram-manager': {
+                lastSync: new Date().toISOString(),
+              },
+            },
+          },
+        },
+      };
+
+      if (baseHash) {
+        patchParams['baseHash'] = baseHash;
+      }
+
+      await rpc.call('config.patch', patchParams);
+
+      // Success — update cooldown timestamp
+      lastRestartTimestamp = Date.now();
+      logger.info('Gateway restart triggered via config.patch');
+
+      return { success: true };
+    } catch (err: unknown) {
+      const isBaseHashMismatch = isHashMismatchError(err);
+
+      if (isBaseHashMismatch && attempt < MAX_RETRIES) {
+        const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+        logger.warn(
+          `config.patch baseHash mismatch (attempt ${attempt + 1}/${MAX_RETRIES + 1}). Retrying in ${delay}ms...`,
+        );
+        await sleep(delay);
+        continue;
+      }
+
+      // All retries exhausted or non-retryable error
+      const errMsg = err instanceof Error ? err.message : String(err);
+      logger.error(`config.patch failed after ${attempt + 1} attempt(s): ${errMsg}`);
+
+      return {
+        success: false,
+        fallbackMessage:
+          'Config updated. Run `openclaw gateway restart` or send SIGUSR1 to apply.',
+      };
+    }
+  }
+
+  // Should not reach here, but just in case
+  return {
+    success: false,
+    fallbackMessage:
+      'Config updated. Run `openclaw gateway restart` or send SIGUSR1 to apply.',
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+function isHashMismatchError(err: unknown): boolean {
+  if (err && typeof err === 'object') {
+    // Check for common error shape
+    if ('code' in err && (err as { code: string }).code === 'BASE_HASH_MISMATCH') {
+      return true;
+    }
+    if ('message' in err) {
+      const msg = (err as { message: string }).message;
+      return msg.toLowerCase().includes('basehash') || msg.toLowerCase().includes('hash mismatch');
+    }
+  }
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if configWrites is enabled in the plugin config via RPC.
+ */
+export async function getConfigWrites(rpc: RpcInterface | null | undefined): Promise<boolean> {
+  if (!rpc) return false;
+  try {
+    const config = await rpc.call('config.get', {});
+    const skills = config['skills'] as Record<string, unknown> | undefined;
+    const entries = skills?.['entries'] as Record<string, unknown> | undefined;
+    const tmConfig = entries?.['telegram-manager'] as Record<string, unknown> | undefined;
+    return tmConfig?.['configWrites'] === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reset the cooldown timer (for testing purposes).
+ */
+export function resetCooldown(): void {
+  lastRestartTimestamp = 0;
+}