talon-agent 1.0.0

package/src/util/log.ts

@@ -0,0 +1,122 @@
+/**
+ * Structured logging via pino — console + file output.
+ *
+ * Always runs at trace level (maximum verbosity) for debugging.
+ * Logs to both:
+ *   - stdout (pretty-printed for readability)
+ *   - workspace/talon.log (JSON, append-only, for persistence)
+ */
+
+import pino from "pino";
+import { existsSync, readFileSync, mkdirSync, statSync, renameSync, unlinkSync } from "node:fs";
+import { dirs, files } from "./paths.js";
+
+export type LogComponent =
+  | "bot"
+  | "bridge"
+  | "agent"
+  | "pulse"
+  | "userbot"
+  | "users"
+  | "watchdog"
+  | "workspace"
+  | "shutdown"
+  | "file"
+  | "sessions"
+  | "settings"
+  | "commands"
+  | "cron"
+  | "dream"
+  | "dispatcher"
+  | "gateway"
+  | "plugin"
+  | "teams"
+  | "config";
+
+const LOG_FILE = files.log;
+
+// Ensure .talon dir exists for log file
+if (!existsSync(dirs.root)) {
+  try { mkdirSync(dirs.root, { recursive: true }); } catch { /* ignore */ }
+}
+
+// Rotate log file on startup if it exceeds 10MB
+const MAX_LOG_SIZE = 10 * 1024 * 1024;
+try {
+  if (existsSync(LOG_FILE) && statSync(LOG_FILE).size > MAX_LOG_SIZE) {
+    const rotated = `${LOG_FILE}.old`;
+    try { unlinkSync(rotated); } catch { /* ignore */ }
+    renameSync(LOG_FILE, rotated);
+  }
+} catch { /* ignore */ }
+
+// Suppress console output for terminal frontend (stdout belongs to the REPL)
+let quiet = process.env.TALON_QUIET === "1";
+if (!quiet) {
+  try {
+    const cfgPath = files.config;
+    if (existsSync(cfgPath)) {
+      const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+      if (cfg.frontend === "terminal") quiet = true;
+    }
+  } catch { /* ignore */ }
+}
+
+const logger = pino({
+  level: "trace",
+  transport: {
+    targets: [
+      // Console output (disabled in quiet mode)
+      ...(!quiet ? [{
+        target: "pino-pretty",
+        level: "trace" as const,
+        options: {
+          colorize: true,
+          ignore: "pid,hostname",
+          translateTime: "HH:MM:ss",
+        },
+      }] : []),
+      // JSON file output (always active)
+      {
+        target: "pino/file",
+        level: "trace",
+        options: {
+          destination: LOG_FILE,
+          mkdir: true,
+        },
+      },
+    ],
+  },
+});
+
+export function log(component: LogComponent, message: string): void {
+  logger.info({ component }, message);
+}
+
+export function logError(
+  component: LogComponent,
+  message: string,
+  err?: unknown,
+): void {
+  if (err instanceof Error) {
+    logger.error({ component, err: err.message }, message);
+  } else if (err !== undefined) {
+    logger.error({ component, err: String(err) }, message);
+  } else {
+    logger.error({ component }, message);
+  }
+}
+
+export function logWarn(component: LogComponent, message: string): void {
+  logger.warn({ component }, message);
+}
+
+export function logDebug(component: LogComponent, message: string): void {
+  logger.debug({ component }, message);
+}
+
+// Expose logger to plugins running in the same process
+(globalThis as Record<string, unknown>).__talonLog = log;
+(globalThis as Record<string, unknown>).__talonLogError = logError;
+(globalThis as Record<string, unknown>).__talonLogWarn = logWarn;
+

package/src/util/paths.ts

@@ -0,0 +1,80 @@
+/**
+ * Centralized path resolution for all Talon directories and files.
+ *
+ * Location: ~/.talon/ (cross-platform: Linux, macOS, Windows)
+ *
+ * Layout:
+ *   ~/.talon/
+ *     config.json              Main configuration
+ *     data/                    Internal state (sessions, history, settings, cron, media)
+ *       sessions.json
+ *       history.json
+ *       chat-settings.json
+ *       cron.json
+ *       media-index.json
+ *     workspace/               User-facing workspace (memory, uploads, logs)
+ *       memory/
+ *       uploads/
+ *       stickers/
+ *       logs/
+ *     talon.log                Structured log file
+ *     .user-session            Telegram userbot session
+ */
+
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+/** Root of the Talon data directory: ~/.talon/ */
+const TALON_ROOT = resolve(homedir(), ".talon");
+
+// ── Directories ────────────────────────────────────────────────────────────
+
+export const dirs = {
+  /** Root: ~/.talon/ */
+  root: TALON_ROOT,
+  /** Internal data: ~/.talon/data/ */
+  data: resolve(TALON_ROOT, "data"),
+  /** User workspace: ~/.talon/workspace/ */
+  workspace: resolve(TALON_ROOT, "workspace"),
+  /** Upload files: ~/.talon/workspace/uploads/ */
+  uploads: resolve(TALON_ROOT, "workspace", "uploads"),
+  /** Daily logs: ~/.talon/workspace/logs/ */
+  logs: resolve(TALON_ROOT, "workspace", "logs"),
+  /** Memory: ~/.talon/workspace/memory/ */
+  memory: resolve(TALON_ROOT, "workspace", "memory"),
+  /** Sticker packs: ~/.talon/workspace/stickers/ */
+  stickers: resolve(TALON_ROOT, "workspace", "stickers"),
+  /** Prompt files: ~/.talon/prompts/ */
+  prompts: resolve(TALON_ROOT, "prompts"),
+  /** Per-chat message traces: ~/.talon/data/traces/ */
+  traces: resolve(TALON_ROOT, "data", "traces"),
+} as const;
+
+// ── Files ──────────────────────────────────────────────────────────────────
+
+export const files = {
+  /** Main config: ~/.talon/config.json */
+  config: resolve(TALON_ROOT, "config.json"),
+  /** Structured log: ~/.talon/talon.log */
+  log: resolve(TALON_ROOT, "talon.log"),
+  /** Session store: ~/.talon/data/sessions.json */
+  sessions: resolve(TALON_ROOT, "data", "sessions.json"),
+  /** Chat history: ~/.talon/data/history.json */
+  history: resolve(TALON_ROOT, "data", "history.json"),
+  /** Per-chat settings: ~/.talon/data/chat-settings.json */
+  chatSettings: resolve(TALON_ROOT, "data", "chat-settings.json"),
+  /** Cron jobs: ~/.talon/data/cron.json */
+  cron: resolve(TALON_ROOT, "data", "cron.json"),
+  /** Media index: ~/.talon/data/media-index.json */
+  mediaIndex: resolve(TALON_ROOT, "data", "media-index.json"),
+  /** Persistent memory: ~/.talon/workspace/memory/memory.md */
+  memory: resolve(TALON_ROOT, "workspace", "memory", "memory.md"),
+  /** Self-bootstrapping identity: ~/.talon/workspace/identity.md */
+  identity: resolve(TALON_ROOT, "workspace", "identity.md"),
+  /** Telegram userbot session: ~/.talon/.user-session */
+  userSession: resolve(TALON_ROOT, ".user-session"),
+  /** PID file for daemon mode: ~/.talon/talon.pid */
+  pid: resolve(TALON_ROOT, "talon.pid"),
+  /** Dream mode state: ~/.talon/workspace/memory/dream_state.json */
+  dreamState: resolve(TALON_ROOT, "workspace", "memory", "dream_state.json"),
+} as const;

package/src/util/time.ts

@@ -0,0 +1,86 @@
+/**
+ * Timezone-aware time formatting utilities.
+ *
+ * All functions accept a timezone string (IANA, e.g. "Europe/Warsaw").
+ * If none is set, falls back to the system default.
+ */
+
+let configuredTz: string | undefined;
+
+/** Set the global timezone used by all formatting helpers. */
+export function setTimezone(tz: string | undefined): void {
+  configuredTz = tz;
+}
+
+/** Get the active timezone (configured or system default). */
+export function getTimezone(): string {
+  return configuredTz ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+// ── Formatting helpers ──────────────────────────────────────────────────────
+
+/** Format a Date in the configured timezone as HH:MM. */
+function toHHMM(date: Date): string {
+  return date.toLocaleTimeString("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZone: getTimezone(),
+  });
+}
+
+/** Format a Date in the configured timezone as YYYY-MM-DD. */
+function toYMD(date: Date): string {
+  return date.toLocaleDateString("en-CA", { timeZone: getTimezone() }); // en-CA gives YYYY-MM-DD
+}
+
+/** Get "today" and "yesterday" date strings in the configured timezone. */
+function todayAndYesterday(): { today: string; yesterday: string } {
+  const now = new Date();
+  const today = toYMD(now);
+  const yd = new Date(now.getTime() - 86_400_000);
+  const yesterday = toYMD(yd);
+  return { today, yesterday };
+}
+
+/**
+ * Smart timestamp for message display.
+ *
+ * - Today:     "14:32"
+ * - Yesterday: "Yesterday 14:32"
+ * - This year: "Mar 19 14:32"
+ * - Older:     "2025-12-19 14:32"
+ */
+export function formatSmartTimestamp(ts: number): string {
+  const date = new Date(ts);
+  const time = toHHMM(date);
+  const dateStr = toYMD(date);
+  const { today, yesterday } = todayAndYesterday();
+
+  if (dateStr === today) return time;
+  if (dateStr === yesterday) return `Yesterday ${time}`;
+
+  const now = new Date();
+  const thisYear = now.toLocaleDateString("en-CA", { timeZone: getTimezone() }).slice(0, 4);
+  const msgYear = dateStr.slice(0, 4);
+
+  if (msgYear === thisYear) {
+    const month = date.toLocaleString("en-US", { month: "short", timeZone: getTimezone() });
+    const day = date.toLocaleString("en-US", { day: "numeric", timeZone: getTimezone() });
+    return `${month} ${day} ${time}`;
+  }
+
+  return `${dateStr} ${time}`;
+}
+
+/**
+ * Full datetime for system prompt injection.
+ * Example: "2026-03-21 14:32 (Europe/Warsaw, Fri)"
+ */
+export function formatFullDatetime(): string {
+  const now = new Date();
+  const tz = getTimezone();
+  const dateStr = toYMD(now);
+  const time = toHHMM(now);
+  const weekday = now.toLocaleString("en-US", { weekday: "short", timeZone: tz });
+  return `${dateStr} ${time} ${weekday} (${tz})`;
+}

package/src/util/trace.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-chat message trace — dumps full in/out messages to ~/.talon/data/traces/<chatId>.jsonl
+ * for debugging. One JSON object per line, append-only.
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { dirs } from "./paths.js";
+
+function ensureDir(): void {
+  if (!existsSync(dirs.traces)) mkdirSync(dirs.traces, { recursive: true });
+}
+
+export function traceMessage(
+  chatId: string,
+  direction: "in" | "out",
+  text: string,
+  meta?: Record<string, unknown>,
+): void {
+  try {
+    ensureDir();
+    const entry = {
+      ts: new Date().toISOString(),
+      dir: direction,
+      text,
+      ...meta,
+    };
+    appendFileSync(
+      resolve(dirs.traces, `${chatId}.jsonl`),
+      JSON.stringify(entry) + "\n",
+    );
+  } catch {
+    // Non-fatal — never break the bot for debug tracing
+  }
+}

package/src/util/watchdog.ts

@@ -0,0 +1,108 @@
+/**
+ * Watchdog -- tracks bot health and recent errors.
+ * Monitors message processing activity and bridge HTTP server responsiveness.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { logWarn } from "./log.js";
+
+// ── Message processing tracking ──────────────────────────────────────────────
+
+let lastProcessedAt = Date.now();
+let totalMessagesProcessed = 0;
+const startTime = Date.now();
+
+/** Record that a message was successfully processed. */
+export function recordMessageProcessed(): void {
+  lastProcessedAt = Date.now();
+  totalMessagesProcessed++;
+}
+
+/** Get total messages processed since startup. */
+export function getTotalMessagesProcessed(): number {
+  return totalMessagesProcessed;
+}
+
+/** Get bot uptime in milliseconds. */
+export function getUptimeMs(): number {
+  return Date.now() - startTime;
+}
+
+// ── Error tracking ───────────────────────────────────────────────────────────
+
+type ErrorRecord = {
+  message: string;
+  timestamp: number;
+};
+
+const recentErrors: ErrorRecord[] = [];
+const MAX_ERRORS = 20;
+
+/** Record an error for admin visibility. */
+export function recordError(message: string): void {
+  recentErrors.push({ message, timestamp: Date.now() });
+  if (recentErrors.length > MAX_ERRORS) {
+    recentErrors.splice(0, recentErrors.length - MAX_ERRORS);
+  }
+}
+
+/** Get the last N errors. */
+export function getRecentErrors(limit = 5): ErrorRecord[] {
+  return recentErrors.slice(-limit);
+}
+
+// ── Inactivity monitoring ────────────────────────────────────────────────────
+
+const INACTIVITY_WARN_MS = 10 * 60 * 1000; // 10 minutes
+let watchdogTimer: ReturnType<typeof setInterval> | null = null;
+
+export function startWatchdog(workspaceDir?: string): void {
+  if (watchdogTimer) return;
+
+  watchdogTimer = setInterval(() => {
+    const elapsed = Date.now() - lastProcessedAt;
+    if (totalMessagesProcessed > 0 && elapsed > INACTIVITY_WARN_MS) {
+      const mins = Math.round(elapsed / 60000);
+      logWarn("watchdog", `No messages processed for ${mins} minutes`);
+    }
+
+    // Ensure workspace still exists (might have been deleted externally)
+    if (workspaceDir && !existsSync(workspaceDir)) {
+      logWarn("watchdog", "Workspace directory missing — recreating");
+      try { mkdirSync(workspaceDir, { recursive: true }); } catch { /* ignore */ }
+    }
+  }, 60_000); // Check every minute
+}
+
+export function stopWatchdog(): void {
+  if (watchdogTimer) {
+    clearInterval(watchdogTimer);
+    watchdogTimer = null;
+  }
+}
+
+// ── Health check ─────────────────────────────────────────────────────────────
+
+export type HealthStatus = {
+  healthy: boolean;
+  uptimeMs: number;
+  totalMessagesProcessed: number;
+  lastProcessedAt: number;
+  msSinceLastMessage: number;
+  recentErrorCount: number;
+};
+
+/** Get current health status (exportable for external monitoring). */
+export function getHealthStatus(): HealthStatus {
+  const now = Date.now();
+  const msSinceLastMessage = now - lastProcessedAt;
+  return {
+    // Unhealthy if no messages processed for 30+ minutes when we've seen at least one
+    healthy: totalMessagesProcessed === 0 || msSinceLastMessage < 30 * 60_000,
+    uptimeMs: now - startTime,
+    totalMessagesProcessed,
+    lastProcessedAt,
+    msSinceLastMessage,
+    recentErrorCount: recentErrors.length,
+  };
+}

package/src/util/workspace.ts

@@ -0,0 +1,208 @@
+/**
+ * Workspace — Claude's home directory.
+ * Talon only ensures the root exists. Claude organizes it however it wants.
+ * Includes periodic cleanup of old uploads to prevent disk exhaustion.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmdirSync, renameSync, statSync, unlinkSync, copyFileSync, cpSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { log } from "./log.js";
+import { dirs, files as pathFiles } from "./paths.js";
+
+const IDENTITY_SEED = `# Identity
+
+<!-- This file defines who you are. It's empty because you're new here. -->
+<!-- On your first conversation, ask the user to help you fill this in: -->
+<!--   - What should I be called? -->
+<!--   - Who are you? Who created me? -->
+<!--   - What will I be used for? -->
+<!-- Then write your identity here using the Write tool. Keep it concise. -->
+`;
+
+// ── Layout migration ────────────────────────────────────────────────────────
+
+/**
+ * Migrate from the old workspace/ layout to the new .talon/ layout.
+ * Only runs if workspace/ exists and .talon/ does not.
+ * Uses renameSync (same filesystem, atomic).
+ */
+export function migrateLayout(): void {
+  const oldRoot = resolve(process.cwd(), "workspace");
+  if (!existsSync(oldRoot) || existsSync(dirs.root)) return;
+
+  log("workspace", "Migrating workspace/ → .talon/ layout");
+
+  // Create target directories
+  mkdirSync(dirs.data, { recursive: true });
+  mkdirSync(dirs.workspace, { recursive: true });
+
+  // File moves: old → new
+  const fileMoves: Array<[string, string]> = [
+    [join(oldRoot, "talon.json"), dirs.root + "/config.json"],
+    [join(oldRoot, "sessions.json"), join(dirs.data, "sessions.json")],
+    [join(oldRoot, "history.json"), join(dirs.data, "history.json")],
+    [join(oldRoot, "chat-settings.json"), join(dirs.data, "chat-settings.json")],
+    [join(oldRoot, "cron.json"), join(dirs.data, "cron.json")],
+    [join(oldRoot, "media-index.json"), join(dirs.data, "media-index.json")],
+    [join(oldRoot, "talon.log"), join(dirs.root, "talon.log")],
+    [join(oldRoot, ".user-session"), join(dirs.root, ".user-session")],
+  ];
+
+  // Move helper — try rename first (fast, same filesystem), fall back to copy+delete
+  const moveFile = (src: string, dst: string) => {
+    try {
+      renameSync(src, dst);
+    } catch {
+      // Cross-filesystem: copy then delete
+      copyFileSync(src, dst);
+      unlinkSync(src);
+    }
+    log("workspace", `Moved ${src} → ${dst}`);
+  };
+
+  for (const [src, dst] of fileMoves) {
+    if (existsSync(src)) moveFile(src, dst);
+  }
+
+  // Directory moves: old → new
+  const dirMoves: Array<[string, string]> = [
+    [join(oldRoot, "memory"), join(dirs.workspace, "memory")],
+    [join(oldRoot, "uploads"), join(dirs.workspace, "uploads")],
+    [join(oldRoot, "logs"), join(dirs.workspace, "logs")],
+    [join(oldRoot, "stickers"), join(dirs.workspace, "stickers")],
+  ];
+
+  for (const [src, dst] of dirMoves) {
+    if (existsSync(src)) {
+      try {
+        renameSync(src, dst);
+      } catch {
+        // Cross-filesystem: use cpSync (Node 16+) then rmSync
+        cpSync(src, dst, { recursive: true });
+        rmSync(src, { recursive: true, force: true });
+      }
+      log("workspace", `Moved ${src} → ${dst}`);
+    }
+  }
+
+  // Remove old workspace/ if empty
+  try {
+    const remaining = readdirSync(oldRoot);
+    if (remaining.length === 0) {
+      rmdirSync(oldRoot);
+      log("workspace", "Removed empty workspace/ directory");
+    } else {
+      log("workspace", `Old workspace/ still has ${remaining.length} item(s) — not removed`);
+    }
+  } catch { /* ignore */ }
+
+  log("workspace", "Migration complete");
+}
+
+// ── Workspace init ───────────────────────────────────────────────────────────
+
+/** Ensure workspace directories exist. */
+export function initWorkspace(root: string): void {
+  migrateLayout();
+  // Ensure .talon/ tree exists
+  for (const dir of [dirs.root, dirs.data, dirs.workspace]) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+  // Ensure the caller-supplied root exists too (may differ in tests)
+  if (!existsSync(root)) mkdirSync(root, { recursive: true });
+
+  // Ensure subdirectories exist
+  for (const sub of [dirs.memory, dirs.uploads, dirs.logs, dirs.stickers, dirs.prompts, dirs.traces]) {
+    if (!existsSync(sub)) mkdirSync(sub, { recursive: true });
+  }
+
+  // Seed identity.md for new workspaces
+  if (!existsSync(pathFiles.identity)) {
+    writeFileSync(pathFiles.identity, IDENTITY_SEED);
+  }
+
+  // Seed prompt files from the package into ~/.talon/prompts/
+  // Only copies files that don't already exist — user edits are preserved.
+  const packagePrompts = resolve(process.cwd(), "prompts");
+  if (existsSync(packagePrompts)) {
+    for (const file of readdirSync(packagePrompts)) {
+      if (!file.endsWith(".md")) continue;
+      const dst = join(dirs.prompts, file);
+      if (!existsSync(dst)) {
+        copyFileSync(join(packagePrompts, file), dst);
+        log("workspace", `Seeded prompt: ${file}`);
+      }
+    }
+  }
+}
+
+/** Calculate total disk usage of the workspace in bytes. */
+export function getWorkspaceDiskUsage(root: string): number {
+  let total = 0;
+  function walk(dir: string): void {
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.isFile()) {
+          try { total += statSync(full).size; } catch { /* skip */ }
+        }
+      }
+    } catch { /* skip */ }
+  }
+  walk(root);
+  return total;
+}
+
+// ── Upload cleanup ──────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // check every hour
+let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Delete files in uploads/ older than maxAgeMs.
+ * Returns number of files deleted.
+ */
+export function cleanupUploads(root: string, maxAgeMs = DEFAULT_MAX_AGE_MS): number {
+  const uploadsDir = join(root, "uploads");
+  if (!existsSync(uploadsDir)) return 0;
+
+  const now = Date.now();
+  let deleted = 0;
+
+  try {
+    for (const entry of readdirSync(uploadsDir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const filePath = join(uploadsDir, entry.name);
+      try {
+        const stat = statSync(filePath);
+        if (now - stat.mtimeMs >= maxAgeMs) {
+          unlinkSync(filePath);
+          deleted++;
+        }
+      } catch { /* skip individual file errors */ }
+    }
+  } catch { /* skip if directory unreadable */ }
+
+  if (deleted > 0) {
+    log("workspace", `Cleaned up ${deleted} old upload(s)`);
+  }
+  return deleted;
+}
+
+/** Start periodic upload cleanup. Call once at startup. */
+export function startUploadCleanup(root: string): void {
+  if (cleanupTimer) return;
+  // Run once immediately, then every hour
+  cleanupUploads(root);
+  cleanupTimer = setInterval(() => cleanupUploads(root), CLEANUP_INTERVAL_MS);
+}
+
+/** Stop the cleanup timer. */
+export function stopUploadCleanup(): void {
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}