@inceptionstack/roundhouse 0.2.2 → 0.3.1

package/src/commands.ts

@@ -0,0 +1,23 @@
+/**
+ * commands.ts — Shared Telegram bot command definitions
+ *
+ * Single source of truth for bot commands registered with Telegram.
+ * Used by both setup (at install time) and gateway (on startup).
+ */
+
+export interface BotCommand {
+  command: string;
+  description: string;
+}
+
+export const BOT_COMMANDS: BotCommand[] = [
+  { command: "new", description: "Start a fresh conversation" },
+  { command: "compact", description: "Compact context window" },
+  { command: "verbose", description: "Toggle verbose tool output" },
+  { command: "stop", description: "Stop the current agent run" },
+  { command: "restart", description: "Restart agent process" },
+  { command: "status", description: "Show system status" },
+  { command: "doctor", description: "Run diagnostics" },
+  { command: "crons", description: "List scheduled cron jobs" },
+  { command: "jobs", description: "Show running jobs" },
+];

package/src/config.ts

@@ -0,0 +1,188 @@
+/**
+ * config.ts — Shared configuration for roundhouse
+ *
+ * Canonical config directory: ~/.roundhouse/
+ * Legacy fallback: ~/.config/roundhouse/ (deprecated, will warn)
+ */
+
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { readFile, access } from "node:fs/promises";
+import type { GatewayConfig } from "./types";
+
+// ── Path constants ───────────────────────────────────
+
+/** New canonical config root */
+export const ROUNDHOUSE_DIR = resolve(homedir(), ".roundhouse");
+
+/** Legacy config root (deprecated) */
+export const LEGACY_CONFIG_DIR = resolve(homedir(), ".config", "roundhouse");
+
+/** Active config directory — use ROUNDHOUSE_DIR */
+export const CONFIG_DIR = ROUNDHOUSE_DIR;
+export const CONFIG_PATH = resolve(ROUNDHOUSE_DIR, "gateway.config.json");
+export const ENV_FILE_PATH = resolve(ROUNDHOUSE_DIR, "env");
+
+/** Cron directories */
+export const CRON_JOBS_DIR = resolve(ROUNDHOUSE_DIR, "crons");
+export const CRON_STATE_DIR = resolve(ROUNDHOUSE_DIR, "cron-state");
+export const CRON_RUNS_DIR = resolve(ROUNDHOUSE_DIR, "cron-runs");
+
+export const SERVICE_NAME = "roundhouse";
+
+/**
+ * Default config written to disk by `roundhouse install`.
+ */
+export const DEFAULT_CONFIG: GatewayConfig = {
+  agent: {
+    type: "pi",
+    cwd: homedir(),
+  },
+  chat: {
+    botUsername: "roundhouse_bot",
+    allowedUsers: [],
+    adapters: {
+      telegram: { mode: "polling" },
+    },
+  },
+};
+
+/**
+ * Build a runtime config by overlaying environment variables onto a base config.
+ */
+export function applyEnvOverrides(config: GatewayConfig): GatewayConfig {
+  return {
+    ...config,
+    agent: {
+      ...config.agent,
+      cwd: (typeof config.agent.cwd === "string" && config.agent.cwd) ? config.agent.cwd : process.cwd(),
+    },
+    chat: {
+      ...config.chat,
+      botUsername: process.env.BOT_USERNAME ?? config.chat.botUsername,
+      allowedUsers: process.env.ALLOWED_USERS
+        ? process.env.ALLOWED_USERS.split(",").map((u) => u.trim())
+        : config.chat.allowedUsers,
+      notifyChatIds: process.env.NOTIFY_CHAT_IDS
+        ? process.env.NOTIFY_CHAT_IDS.split(",").map((id) => Number(id.trim())).filter((n) => !isNaN(n))
+        : config.chat.notifyChatIds,
+    },
+  };
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve config path with legacy fallback.
+ * Returns the path that actually has a config file, or the new canonical path.
+ */
+let configPathWarned = false;
+
+export async function resolveConfigPath(): Promise<{ path: string; legacy: boolean }> {
+  // New path takes priority
+  if (await fileExists(CONFIG_PATH)) {
+    return { path: CONFIG_PATH, legacy: false };
+  }
+  // Legacy fallback
+  const legacyPath = resolve(LEGACY_CONFIG_DIR, "gateway.config.json");
+  if (await fileExists(legacyPath)) {
+    if (!configPathWarned) {
+      configPathWarned = true;
+      console.warn(`[roundhouse] ⚠️  Config found at legacy path: ${legacyPath}`);
+      console.warn(`[roundhouse]    Move it to ${CONFIG_PATH} — legacy path will be removed in a future version.`);
+    }
+    return { path: legacyPath, legacy: true };
+  }
+  return { path: CONFIG_PATH, legacy: false };
+}
+
+/**
+ * Resolve env file path with legacy fallback.
+ */
+let envFileWarned = false;
+
+export async function resolveEnvFilePath(): Promise<string> {
+  if (await fileExists(ENV_FILE_PATH)) return ENV_FILE_PATH;
+  const legacyEnv = resolve(LEGACY_CONFIG_DIR, "env");
+  if (await fileExists(legacyEnv)) {
+    if (!envFileWarned) {
+      envFileWarned = true;
+      console.warn(`[roundhouse] \u26a0\ufe0f  Env file found at legacy path: ${legacyEnv}`);
+      console.warn(`[roundhouse]    Move it to ${ENV_FILE_PATH} \u2014 legacy path will be removed in a future version.`);
+    }
+    return legacyEnv;
+  }
+  return ENV_FILE_PATH;
+}
+
+export async function loadConfig(): Promise<GatewayConfig> {
+  let config: GatewayConfig | undefined;
+
+  // Check for ROUNDHOUSE_CONFIG env var (set by CLI/daemon — must be valid)
+  const envConfig = process.env.ROUNDHOUSE_CONFIG;
+  if (envConfig) {
+    try {
+      const raw = await readFile(resolve(envConfig), "utf8");
+      console.log(`[roundhouse] loaded config from ${envConfig}`);
+      config = JSON.parse(raw) as GatewayConfig;
+    } catch (err: any) {
+      console.error(`[roundhouse] failed to load config from ROUNDHOUSE_CONFIG=${envConfig}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Check for --config flag
+  if (!config) {
+    const configIdx = process.argv.indexOf("--config");
+    if (configIdx !== -1 && process.argv[configIdx + 1]) {
+      const configPath = resolve(process.argv[configIdx + 1]);
+      try {
+        const raw = await readFile(configPath, "utf8");
+        console.log(`[roundhouse] loaded config from ${configPath}`);
+        config = JSON.parse(raw) as GatewayConfig;
+      } catch (err: any) {
+        console.error(`[roundhouse] failed to load config from ${configPath}: ${err.message}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  // Try canonical path, then legacy, then cwd
+  if (!config) {
+    const resolved = await resolveConfigPath();
+    try {
+      const raw = await readFile(resolved.path, "utf8");
+      console.log(`[roundhouse] loaded config from ${resolved.path}`);
+      config = JSON.parse(raw) as GatewayConfig;
+    } catch (err: any) {
+      // File not found → try cwd. Parse error on existing file → fail fast.
+      if (err.code !== "ENOENT") {
+        console.error(`[roundhouse] failed to parse config at ${resolved.path}: ${err.message}`);
+        process.exit(1);
+      }
+      // Try cwd
+      try {
+        const cwdPath = resolve(process.cwd(), "gateway.config.json");
+        const raw = await readFile(cwdPath, "utf8");
+        console.log("[roundhouse] loaded gateway.config.json from cwd");
+        config = JSON.parse(raw) as GatewayConfig;
+      } catch (cwdErr: any) {
+        if (cwdErr.code !== "ENOENT") {
+          console.error(`[roundhouse] failed to parse config at ./gateway.config.json: ${cwdErr.message}`);
+          process.exit(1);
+        }
+        console.log("[roundhouse] using default config + env vars");
+        config = DEFAULT_CONFIG;
+      }
+    }
+  }
+
+  return applyEnvOverrides(config);
+}

package/src/cron/constants.ts

@@ -0,0 +1,54 @@
+/**
+ * cron/constants.ts — Shared constants for cron system
+ */
+
+/** Default job timeout: 30 minutes */
+export const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+/** Default timezone when none specified */
+export const DEFAULT_TIMEZONE = "UTC";
+
+/** Scheduler tick interval: 60 seconds */
+export const TICK_MS = 60_000;
+
+/** Shutdown grace period: 30 seconds */
+export const SHUTDOWN_TIMEOUT_MS = 30_000;
+
+/** Max catch-up iterations to prevent blocking on high-frequency schedules */
+export const MAX_CATCHUP_ITERATIONS = 10_000;
+
+/** Default number of recent runs to show */
+export const DEFAULT_RUNS_LIMIT = 10;
+
+/** Telegram notification: max response text chars */
+export const NOTIFY_MAX_RESPONSE_CHARS = 3500;
+
+/** Telegram notification: max error text chars */
+export const NOTIFY_MAX_ERROR_CHARS = 500;
+
+
+/** Valid notify-on values */
+export const VALID_NOTIFY_ON = ["always", "success", "failure"] as const;
+export type NotifyOn = (typeof VALID_NOTIFY_ON)[number];
+
+/** Heartbeat interval: 30 minutes */
+export const HEARTBEAT_INTERVAL_MS = 30 * 60 * 1000;
+
+/** Default HEARTBEAT.md content — if file matches this exactly, heartbeat is skipped */
+export const HEARTBEAT_DEFAULT_CONTENT = `# Heartbeat Instructions
+
+# Add your recurring tasks below. The agent will check these every 30 minutes.
+# If this file is empty or contains only this default text, no action is taken.
+#
+# Example:
+# ## Every heartbeat:
+# - Check disk usage and warn if above 80%
+# - Check if roundhouse gateway is healthy
+#
+# ## Every morning:
+# - Summarize overnight system events`;
+
+/** Suffix appended to every cron prompt to constrain agent output */
+export const CRON_PROMPT_SUFFIX = `
+
+IMPORTANT: You are running as an automated cron job. Your entire text output will be sent as a notification message. Output ONLY the requested content — no preamble, no explanation of what you are, no offers to help with other things. Do not repeat the request. Be concise and direct.`;

package/src/cron/durations.ts

@@ -0,0 +1,33 @@
+/**
+ * cron/durations.ts — Parse human-friendly duration strings
+ */
+
+const UNITS: Record<string, number> = {
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** Parse "30s", "5m", "6h", "2d" → milliseconds. Throws on invalid input. */
+export function parseDuration(input: string): number {
+  const match = input.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
+  if (!match) throw new Error(`Invalid duration: "${input}". Use format like 30s, 5m, 6h, 2d`);
+  const value = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  if (value <= 0) throw new Error(`Duration must be positive: "${input}"`);
+  return Math.round(value * UNITS[unit]);
+}
+
+/** Format milliseconds as human-friendly string */
+export function formatDuration(ms: number): string {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 86_400_000) return `${(ms / 3_600_000).toFixed(1)}h`;
+  return `${(ms / 86_400_000).toFixed(1)}d`;
+}
+
+/** Check if a string looks like a duration */
+export function isDuration(input: string): boolean {
+  return /^\d+(?:\.\d+)?\s*[smhd]$/i.test(input.trim());
+}

package/src/cron/format.ts

@@ -0,0 +1,139 @@
+/**
+ * cron/format.ts — Shared cron formatting utilities
+ *
+ * Used by CLI, gateway /crons, and notifications.
+ */
+
+import type { CronSchedule, CronJobConfig, CronJobState, CronRunRecord, CronRunStatus } from "./types";
+import { DEFAULT_TIMEOUT_MS } from "./constants";
+import { formatDuration } from "./durations";
+
+/** Format a schedule for human-readable display */
+export function formatSchedule(schedule: CronSchedule): string {
+  switch (schedule.type) {
+    case "cron": return `${cronToHuman(schedule.cron)} (${schedule.tz})`;
+    case "interval": return `every ${schedule.every}`;
+    case "once": return `once at ${schedule.at}${schedule.tz ? ` (${schedule.tz})` : ""}`;
+    default: return "unknown";
+  }
+}
+
+/** Convert a 5-field cron expression to human-readable text */
+function cronToHuman(expr: string): string {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return expr;
+  const [min, hour, dom, month, dow] = parts;
+
+  const time = formatCronTime(hour, min);
+  if (!time) return expr; // complex expression — show raw
+  const isRepeating = time.startsWith("every");
+  const dayPart = formatCronDays(dom, month, dow);
+
+  if (isRepeating && (!dayPart || dayPart === "daily")) return time;
+  if (isRepeating && dayPart) return `${dayPart}, ${time}`;
+  if (dayPart) return `${dayPart} at ${time}`;
+  return expr; // complex — show raw
+}
+
+function formatCronTime(hour: string, min: string): string | null {
+  if (hour === "*" && min === "*") return "every minute";
+  if (hour.startsWith("*/")) {
+    if (min !== "0" && min !== "*") return null; // complex: specific min + repeating hour
+    const n = hour.slice(2); return n === "1" ? "every hour" : `every ${n} hours`;
+  }
+  if (min.startsWith("*/") && hour === "*") { const n = min.slice(2); return n === "1" ? "every minute" : `every ${n} minutes`; }
+  if (min.startsWith("*/")) return null; // complex: min repeat + specific hour
+  if (hour === "*" && /^\d+$/.test(min)) return `every hour at :${min.padStart(2, "0")}`;
+  if (hour === "*") return null; // complex min field
+
+  // Only parse simple numeric values — reject ranges/lists
+  if (!/^\d+$/.test(hour) || !/^\d+$/.test(min)) return null;
+  const h = parseInt(hour, 10);
+  const m = parseInt(min, 10);
+  if (h < 0 || h > 23 || m < 0 || m > 59) return null;
+  const ampm = h >= 12 ? "pm" : "am";
+  const h12 = h === 0 ? 12 : h > 12 ? h - 12 : h;
+  return m === 0 ? `${h12}${ampm}` : `${h12}:${String(m).padStart(2, "0")}${ampm}`;
+}
+
+function formatCronDays(dom: string, month: string, dow: string): string {
+  const DOW_NAMES: Record<string, string> = { "0": "Sun", "1": "Mon", "2": "Tue", "3": "Wed", "4": "Thu", "5": "Fri", "6": "Sat", "7": "Sun" };
+  const DOW_RANGE: Record<string, string> = { "1-5": "weekdays", "0,6": "weekends", "6,0": "weekends" };
+
+  // Non-* month makes it complex — return empty to trigger raw fallback
+  if (month !== "*") return "";
+
+  if (dom === "*" && dow === "*") return "daily";
+
+  if (dom === "*" && dow !== "*") {
+    if (DOW_RANGE[dow]) return DOW_RANGE[dow];
+    // Handle ranges like 1-3 and lists like 1,3,5
+    const days = dow.split(",").map((d) => {
+      if (d.includes("-")) {
+        const [s, e] = d.split("-");
+        return `${DOW_NAMES[s] ?? s}-${DOW_NAMES[e] ?? e}`;
+      }
+      return DOW_NAMES[d] ?? d;
+    }).join(", ");
+    return `every ${days}`;
+  }
+
+  if (dom !== "*" && dow === "*") {
+    return `on day ${dom} of each month`;
+  }
+
+  return ""; // complex — both dom + dow set
+}
+
+/** Icon for job enabled/paused state */
+export function jobEnabledIcon(enabled: boolean): string {
+  return enabled ? "✅" : "⏸️";
+}
+
+/** Icon for run status */
+export function runStatusIcon(status: CronRunStatus): string {
+  return status === "completed" ? "✅" : "❌";
+}
+
+/** Format run count summary */
+export function formatRunCounts(state: CronJobState): string {
+  return `${state.totalRuns} runs (${state.totalSuccesses}✓ ${state.totalFailures}✗)`;
+}
+
+/** Format a single run line */
+export function formatRunLine(run: CronRunRecord): string {
+  return `${runStatusIcon(run.status)} ${run.id} ${run.status} ${run.durationMs}ms`;
+}
+
+/** Format a job summary line */
+export function formatJobSummary(job: CronJobConfig, state: CronJobState): string {
+  return `${jobEnabledIcon(job.enabled)} ${job.id}: ${formatSchedule(job.schedule)} — ${formatRunCounts(state)}`;
+}
+
+/** Format job detail (for show command) */
+export function formatJobDetail(job: CronJobConfig, state: CronJobState, runs: CronRunRecord[]): string {
+  const lines: string[] = [];
+  lines.push(`Job: ${job.id}`);
+  lines.push(`Enabled: ${job.enabled}`);
+  lines.push(`Schedule: ${formatSchedule(job.schedule)}`);
+  if (job.description) lines.push(`Description: ${job.description}`);
+  lines.push(`Prompt: ${job.prompt.slice(0, 200)}`);
+  lines.push(`Timeout: ${formatDuration(job.timeoutMs ?? DEFAULT_TIMEOUT_MS)}`);
+  lines.push(``);
+  lines.push(`Runs: ${formatRunCounts(state)}`);
+  if (state.lastRunId) lines.push(`Last run: ${state.lastRunId} at ${state.lastFinishedAt}`);
+  if (state.lastError) lines.push(`Last error: ${state.lastError}`);
+  if (runs.length) {
+    lines.push(``);
+    lines.push(`Recent runs:`);
+    for (const r of runs) {
+      lines.push(`  ${formatRunLine(r)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Default empty state for a job */
+export function emptyState(id: string): CronJobState {
+  return { id, totalRuns: 0, totalSuccesses: 0, totalFailures: 0 };
+}

package/src/cron/helpers.ts

@@ -0,0 +1,30 @@
+/**
+ * cron/helpers.ts — Shared cron helpers to eliminate cross-module duplication
+ */
+
+/** Built-in job ID prefix */
+export const BUILTIN_JOB_PREFIX = "builtin-";
+
+/** Built-in heartbeat job ID */
+export const BUILTIN_HEARTBEAT_JOB_ID = `${BUILTIN_JOB_PREFIX}heartbeat`;
+
+/** Heartbeat file name */
+export const HEARTBEAT_FILE_NAME = "HEARTBEAT.md";
+
+/** Check if a job ID is a built-in job */
+export function isBuiltinJob(id: string): boolean {
+  return id.startsWith(BUILTIN_JOB_PREFIX);
+}
+
+/** Build a cron thread ID */
+export function buildCronThreadId(jobId: string, runId: string): string {
+  return `cron:${jobId}:${runId}`;
+}
+
+/** Check if a notify policy should send for a given status */
+export function shouldNotify(policy: string | undefined, status: string): boolean {
+  if (!policy || policy === "always") return true;
+  if (policy === "success" && status === "completed") return true;
+  if (policy === "failure" && status !== "completed") return true;
+  return false;
+}

package/src/cron/runner.ts

@@ -0,0 +1,148 @@
+/**
+ * cron/runner.ts — Execute a single cron job
+ *
+ * Creates a fresh agent per run, renders prompt, runs with timeout,
+ * saves results, notifies.
+ */
+
+import { getAgentFactory } from "../agents/registry";
+import { sendTelegramToMany } from "../notify/telegram";
+import { CronStore, generateRunId } from "./store";
+import { buildTemplateContext, renderTemplate } from "./template";
+import type { CronJobConfig, CronRunRecord } from "./types";
+import { isBuiltinJob, buildCronThreadId, shouldNotify } from "./helpers";
+import { DEFAULT_TIMEOUT_MS, NOTIFY_MAX_RESPONSE_CHARS, NOTIFY_MAX_ERROR_CHARS, CRON_PROMPT_SUFFIX } from "./constants";
+import { runStatusIcon } from "./format";
+import type { GatewayConfig } from "../types";
+
+export class CronRunner {
+  constructor(
+    private store: CronStore,
+    private agentConfig?: GatewayConfig["agent"],
+  ) {}
+
+  async runJob(
+    job: CronJobConfig,
+    scheduledAt: Date,
+    kind: "scheduled" | "manual" = "scheduled",
+  ): Promise<CronRunRecord> {
+    const runId = generateRunId();
+    const startedAt = new Date();
+    const threadId = buildCronThreadId(job.id, runId);
+    const timeoutMs = job.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+    // Render prompt
+    const tz = job.schedule.type === "cron" ? job.schedule.tz : job.schedule.type === "once" ? job.schedule.tz : undefined;
+    const ctx = buildTemplateContext(job.id, job.description, runId, scheduledAt, startedAt, tz, process.cwd(), job.vars ?? {});
+    const prompt = renderTemplate(job.prompt, ctx) + CRON_PROMPT_SUFFIX;
+
+    console.log(`[cron] starting ${job.id} [${runId}] kind=${kind}`);
+
+    // Create fresh agent — use provided config or load dynamically for CLI trigger
+    let agentCfg = this.agentConfig;
+    if (!agentCfg) {
+      const { loadConfig } = await import("../config");
+      agentCfg = (await loadConfig()).agent;
+    }
+    const { type, ...rest } = agentCfg;
+    const factory = getAgentFactory(type);
+    const agent = factory({ ...rest, sessionDir: undefined });
+
+    let responseText = "";
+    let error: string | undefined;
+    let status: CronRunRecord["status"] = "completed";
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      // Race agent.prompt against timeout
+      const result = await Promise.race([
+        agent.prompt(threadId, { text: prompt }),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(async () => {
+            timedOut = true;
+            try { await agent.abort?.(threadId); } catch {}
+            reject(new Error(`Cron job timed out after ${timeoutMs}ms`));
+          }, timeoutMs);
+        }),
+      ]);
+      clearTimeout(timer);
+      responseText = result.text;
+    } catch (err) {
+      clearTimeout(timer);
+      error = (err as Error).message;
+      status = timedOut ? "timeout" : "failed";
+      console.error(`[cron] ${job.id} [${runId}] ${status}:`, error);
+    } finally {
+      try { await agent.dispose(); } catch {}
+    }
+
+    const finishedAt = new Date();
+    const record: CronRunRecord = {
+      id: runId, jobId: job.id, kind, status,
+      scheduledAt: scheduledAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      threadId, prompt,
+      responseText: responseText || undefined,
+      error,
+    };
+
+    // Save run + update state (skip entirely for built-in jobs)
+    const isBuiltin = isBuiltinJob(job.id);
+
+    if (!isBuiltin) {
+      try {
+        await this.store.appendRun(record);
+        const state = await this.store.getState(job.id);
+        state.lastRunId = runId;
+        state.lastStartedAt = startedAt.toISOString();
+        state.lastFinishedAt = finishedAt.toISOString();
+        state.totalRuns++;
+        if (status === "completed") {
+          state.lastSuccessAt = finishedAt.toISOString();
+          state.totalSuccesses++;
+          state.lastError = undefined;
+        } else {
+          state.lastFailureAt = finishedAt.toISOString();
+          state.totalFailures++;
+          state.lastError = error ?? status;
+        }
+        await this.store.writeState(state);
+      } catch (err) {
+        console.error(`[cron] ${job.id} [${runId}] failed to persist run:`, (err as Error).message);
+      }
+    }
+
+    // Notify (catch errors)
+    try { await this.notify(job, record); } catch (err) {
+      console.error(`[cron] ${job.id} [${runId}] notification failed:`, (err as Error).message);
+    }
+
+    console.log(`[cron] finished ${job.id} [${runId}] status=${status} duration=${record.durationMs}ms`);
+    return record;
+  }
+
+  private async notify(job: CronJobConfig, record: CronRunRecord): Promise<void> {
+    const tg = job.notify?.telegram;
+    if (!tg?.chatIds?.length) return;
+
+    if (!shouldNotify(tg.onlyOn, record.status)) return;
+
+    const icon = runStatusIcon(record.status);
+    const dur = `${(record.durationMs / 1000).toFixed(1)}s`;
+    const header = `${icon} Cron: ${job.id}\nStatus: ${record.status} (${dur})`;
+
+    let body = header;
+    if (record.responseText) {
+      const trimmed = record.responseText.slice(0, NOTIFY_MAX_RESPONSE_CHARS);
+      body = `${header}\n\n${trimmed}`;
+      if (record.responseText.length > NOTIFY_MAX_RESPONSE_CHARS) body += "\n\n(truncated)";
+    } else if (record.error) {
+      body = `${header}\nError: ${record.error.slice(0, NOTIFY_MAX_ERROR_CHARS)}`;
+    }
+
+    await sendTelegramToMany(tg.chatIds, body);
+  }
+}