talon-agent 1.0.0

package/src/core/errors.ts

@@ -0,0 +1,206 @@
+/**
+ * Typed error classification.
+ *
+ * One place to classify errors. Every module reads `err.reason` instead
+ * of regex-matching error messages. Inspired by OpenClaw's FailoverError.
+ */
+
+// ── Error reasons ───────────────────────────────────────────────────────────
+
+type ErrorReason =
+  | "rate_limit"
+  | "overloaded"
+  | "network"
+  | "auth"
+  | "context_length"
+  | "session_expired"
+  | "bad_request"
+  | "forbidden"
+  | "telegram_api"
+  | "unknown";
+
+// ── TalonError class ────────────────────────────────────────────────────────
+
+export class TalonError extends Error {
+  readonly reason: ErrorReason;
+  readonly retryable: boolean;
+  readonly status?: number;
+  readonly retryAfterMs?: number;
+
+  constructor(
+    message: string,
+    params: {
+      reason: ErrorReason;
+      retryable?: boolean;
+      status?: number;
+      retryAfterMs?: number;
+      cause?: unknown;
+    },
+  ) {
+    super(message, { cause: params.cause });
+    this.name = "TalonError";
+    this.reason = params.reason;
+    this.retryable = params.retryable ?? false;
+    this.status = params.status;
+    this.retryAfterMs = params.retryAfterMs;
+  }
+}
+
+// ── Classify any error ──────────────────────────────────────────────────────
+
+/**
+ * Wrap or classify any thrown value into a TalonError.
+ * Call this at module boundaries (backend catch, bridge catch) to convert
+ * raw errors into typed ones that callers can switch on.
+ */
+export function classify(err: unknown): TalonError {
+  if (err instanceof TalonError) return err;
+
+  let msg: string;
+  if (err instanceof Error) msg = err.message;
+  else if (typeof err === "string") msg = err;
+  else { try { msg = String(err); } catch { msg = "[non-stringifiable error]"; } }
+  const cause = err instanceof Error ? err : undefined;
+
+  // Extract HTTP status if present
+  const statusMatch = msg.match(/\b([2-5]\d{2})\b/);
+  const status = statusMatch ? parseInt(statusMatch[1], 10) : undefined;
+
+  // Rate limit
+  if (/rate.?limit|429|too many requests/i.test(msg)) {
+    const retryMatch = msg.match(/retry.?after[:\s]*(\d+)/i);
+    const retryAfterMs = retryMatch
+      ? Math.min(parseInt(retryMatch[1], 10) * 1000, 300_000)
+      : 60_000;
+    return new TalonError(msg, {
+      reason: "rate_limit",
+      retryable: true,
+      status: status ?? 429,
+      retryAfterMs,
+      cause,
+    });
+  }
+
+  // Overloaded / capacity
+  if (/overloaded|503|capacity/i.test(msg)) {
+    return new TalonError(msg, {
+      reason: "overloaded",
+      retryable: true,
+      status: status ?? 503,
+      retryAfterMs: 5_000,
+      cause,
+    });
+  }
+
+  // Network errors
+  if (/network|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|fetch failed/i.test(msg)) {
+    return new TalonError(msg, {
+      reason: "network",
+      retryable: true,
+      retryAfterMs: 2_000,
+      cause,
+    });
+  }
+
+  // Session expired
+  if (/session|expired|invalid.*resume/i.test(msg)) {
+    return new TalonError(msg, {
+      reason: "session_expired",
+      retryable: false,
+      cause,
+    });
+  }
+
+  // Context length / overflow
+  if (/context.*length|too.*long|token.*limit|overflow/i.test(msg)) {
+    return new TalonError(msg, {
+      reason: "context_length",
+      retryable: false,
+      cause,
+    });
+  }
+
+  // Auth
+  if (/authentication|unauthorized|401|api.?key/i.test(msg)) {
+    return new TalonError(msg, {
+      reason: "auth",
+      retryable: false,
+      status: status ?? 401,
+      cause,
+    });
+  }
+
+  // Bad request (don't retry)
+  if (status === 400) {
+    return new TalonError(msg, {
+      reason: "bad_request",
+      retryable: false,
+      status: 400,
+      cause,
+    });
+  }
+
+  // Forbidden (don't retry)
+  if (status === 403) {
+    return new TalonError(msg, {
+      reason: "forbidden",
+      retryable: false,
+      status: 403,
+      cause,
+    });
+  }
+
+  // Server errors (5xx) are generally retryable
+  if (status && status >= 500) {
+    return new TalonError(msg, {
+      reason: "overloaded",
+      retryable: true,
+      status,
+      retryAfterMs: 2_000,
+      cause,
+    });
+  }
+
+  // Unknown
+  return new TalonError(msg, {
+    reason: "unknown",
+    retryable: false,
+    status,
+    cause,
+  });
+}
+
+// ── User-friendly messages ──────────────────────────────────────────────────
+
+const FRIENDLY_MESSAGES: Record<ErrorReason, string> = {
+  rate_limit: "Rate limited. Try again in a moment.",
+  overloaded: "Claude is busy right now. Retrying with a faster model...",
+  network: "Connection issue. Retrying shortly.",
+  auth: "API key error. Bot operator: check your Claude credentials.",
+  context_length:
+    "Conversation too long for the context window. Use /reset to start fresh.",
+  session_expired: "Session expired. Retrying automatically...",
+  bad_request: "Something went wrong. Try /reset if this keeps happening.",
+  forbidden: "Permission denied for this action.",
+  telegram_api: "Telegram API error. Try again.",
+  unknown: "Something went wrong. Try again or /reset.",
+};
+
+/**
+ * Get a user-friendly error message. For rate limits, includes retry timing.
+ */
+export function friendlyMessage(err: unknown): string {
+  const classified = err instanceof TalonError ? err : classify(err);
+
+  if (classified.reason === "rate_limit" && classified.retryAfterMs) {
+    const seconds = Math.ceil(classified.retryAfterMs / 1000);
+    return `Rate limited. Try again in ${seconds} seconds.`;
+  }
+
+  // Session expired messages are already user-friendly from the backend
+  if (classified.reason === "session_expired") {
+    return classified.message;
+  }
+
+  return FRIENDLY_MESSAGES[classified.reason];
+}

package/src/core/gateway-actions.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared gateway actions — platform-agnostic handlers that work with any frontend.
+ *
+ * Handles: cron CRUD, fetch_url, in-memory history queries.
+ * Returns null if the action isn't recognized (so the gateway delegates to the frontend).
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import * as cheerio from "cheerio";
+import { dirs } from "../util/paths.js";
+import {
+  getRecentFormatted,
+  searchHistory,
+  getMessagesByUser,
+  getKnownUsers,
+} from "../storage/history.js";
+import { formatMediaIndex } from "../storage/media-index.js";
+import {
+  addCronJob,
+  getCronJob,
+  getCronJobsForChat,
+  updateCronJob,
+  deleteCronJob,
+  validateCronExpression,
+  generateCronId,
+  type CronJobType,
+} from "../storage/cron-store.js";
+import { log } from "../util/log.js";
+import type { ActionResult } from "./types.js";
+
+/** Extract readable text from HTML using cheerio (proper DOM parser). */
+function extractText(html: string, maxLength = 8000): string {
+  const $ = cheerio.load(html);
+  // Remove non-content elements
+  $("script, style, noscript, iframe, svg, nav, footer, header").remove();
+  // Get text content, normalize whitespace
+  const text = $("body").text().replace(/\s+/g, " ").trim();
+  return text.slice(0, maxLength);
+}
+
+export async function handleSharedAction(
+  body: Record<string, unknown>,
+  chatId: number,
+): Promise<ActionResult | null> {
+  const action = body.action as string;
+
+  switch (action) {
+    // ── History (in-memory fallback) ──────────────────────────────────────
+    // These are only used when userbot is not available.
+    // Frontends can override these with richer implementations.
+
+    case "read_history": {
+      const limit = Math.min(100, Number(body.limit ?? 30));
+      return { ok: true, text: getRecentFormatted(String(chatId), limit) };
+    }
+
+    case "search_history": {
+      const limit = Math.min(100, Number(body.limit ?? 20));
+      return { ok: true, text: searchHistory(String(chatId), String(body.query ?? ""), limit) };
+    }
+
+    case "get_user_messages": {
+      const limit = Math.min(50, Number(body.limit ?? 20));
+      return { ok: true, text: getMessagesByUser(String(chatId), String(body.user_name ?? ""), limit) };
+    }
+
+    case "list_known_users":
+      return { ok: true, text: getKnownUsers(String(chatId)) };
+
+    case "list_media":
+      return { ok: true, text: formatMediaIndex(String(chatId), Math.min(20, Number(body.limit ?? 10))) };
+
+    // ── Web search (SearXNG) ────────────────────────────────────────────
+
+    case "web_search": {
+      const query = String(body.query ?? "");
+      if (!query) return { ok: false, error: "Missing query" };
+      const limit = Math.min(10, Number(body.limit ?? 5));
+
+      // Try Brave first (if API key configured), fall back to SearXNG
+      const braveKey = process.env.TALON_BRAVE_API_KEY;
+      const searxUrl = process.env.TALON_SEARXNG_URL || "http://localhost:8080";
+
+      type SearchResult = { title: string; url: string; snippet: string };
+      let results: SearchResult[] = [];
+      let provider = "";
+
+      // Brave Search API
+      if (braveKey) {
+        try {
+          const resp = await fetch(
+            `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${limit}`,
+            { signal: AbortSignal.timeout(8_000), headers: { "X-Subscription-Token": braveKey, Accept: "application/json" } },
+          );
+          if (resp.ok) {
+            const data = await resp.json() as { web?: { results?: Array<{ title: string; url: string; description: string }> } };
+            results = (data.web?.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.description ?? "" }));
+            provider = "Brave";
+          }
+        } catch { /* fall through to SearXNG */ }
+      }
+
+      // SearXNG fallback
+      if (results.length === 0) {
+        try {
+          const resp = await fetch(
+            `${searxUrl}/search?q=${encodeURIComponent(query)}&format=json`,
+            { signal: AbortSignal.timeout(10_000) },
+          );
+          if (resp.ok) {
+            const data = await resp.json() as { results?: Array<{ title: string; url: string; content: string }> };
+            results = (data.results ?? []).slice(0, limit).map((r) => ({ title: r.title, url: r.url, snippet: r.content ?? "" }));
+            provider = "SearXNG";
+          }
+        } catch { /* both failed */ }
+      }
+
+      if (results.length === 0) return { ok: true, text: `No results for "${query}".` };
+      const formatted = results.map((r, i) =>
+        `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet.slice(0, 200)}`
+      ).join("\n\n");
+      return { ok: true, text: `Search results for "${query}" (via ${provider}):\n\n${formatted}` };
+    }
+
+    // ── Web fetch ────────────────────────────────────────────────────────
+
+    case "fetch_url": {
+      const url = String(body.url ?? "");
+      if (!url) return { ok: false, error: "Missing URL" };
+      try {
+        const parsed = new URL(url);
+        if (!["http:", "https:"].includes(parsed.protocol)) {
+          return { ok: false, error: "URL must use http or https protocol" };
+        }
+      } catch {
+        return { ok: false, error: "Invalid URL" };
+      }
+      try {
+        const resp = await fetch(url, {
+          signal: AbortSignal.timeout(15_000),
+          headers: { "User-Agent": "Talon/1.0" },
+          redirect: "follow",
+        });
+        if (!resp.ok) return { ok: false, error: `HTTP ${resp.status}` };
+        const ct = resp.headers.get("content-type") ?? "";
+
+        // Binary content: download and save to workspace
+        const mimeType = ct.split(";")[0].trim().toLowerCase();
+        const isText = mimeType.startsWith("text/") || mimeType === "application/json";
+        if (!isText) {
+          const buffer = Buffer.from(await resp.arrayBuffer());
+          if (buffer.length > 20 * 1024 * 1024) return { ok: false, error: "File too large (max 20MB)" };
+          if (buffer.length === 0) return { ok: false, error: "Empty response (0 bytes)" };
+
+          // Validate magic bytes — prevent saving HTML error pages as images
+          // (servers can return error pages with image content-type headers)
+          const magic = buffer.subarray(0, 16);
+          const isRealImage =
+            (magic[0] === 0xFF && magic[1] === 0xD8) || // JPEG
+            (magic[0] === 0x89 && magic[1] === 0x50 && magic[2] === 0x4E && magic[3] === 0x47) || // PNG
+            (magic[0] === 0x47 && magic[1] === 0x49 && magic[2] === 0x46) || // GIF
+            (magic[0] === 0x52 && magic[1] === 0x49 && magic[2] === 0x46 && magic[3] === 0x46 &&
+             magic[8] === 0x57 && magic[9] === 0x45 && magic[10] === 0x42 && magic[11] === 0x50); // WebP
+
+          // If content-type says image but bytes say otherwise, treat as text
+          if (ct.startsWith("image/") && !isRealImage) {
+            const text = extractText(buffer.toString("utf-8"), 500);
+            return { ok: false, error: `Server returned an error page instead of an image. Content: ${text}` };
+          }
+
+          const ext = isRealImage
+            ? ((magic[0] === 0xFF) ? "jpg" : (magic[0] === 0x89) ? "png" : (magic[0] === 0x47) ? "gif" : "webp")
+            : ct.includes("pdf") ? "pdf" : ct.includes("zip") ? "zip" : "bin";
+          const uploadsDir = dirs.uploads;
+          if (!existsSync(uploadsDir)) mkdirSync(uploadsDir, { recursive: true });
+          const filePath = resolve(uploadsDir, `${Date.now()}-fetched.${ext}`);
+          writeFileSync(filePath, buffer);
+          const typeLabel = isRealImage ? "image" : ct.split("/")[1]?.split(";")[0] ?? "file";
+          return { ok: true, text: `Downloaded ${typeLabel} (${(buffer.length / 1024).toFixed(0)}KB) to: ${filePath}\nRead it with the Read tool or send it with send(type="file", file_path="${filePath}").` };
+        }
+        const raw = await resp.text();
+        const text = extractText(raw);
+        if (text.length < 20) return { ok: true, text: "(Page has no readable content)" };
+        return { ok: true, text };
+      } catch (err) {
+        return { ok: false, error: `Fetch failed: ${err instanceof Error ? err.message : err}` };
+      }
+    }
+
+    // ── Cron CRUD ────────────────────────────────────────────────────────
+
+    case "create_cron_job": {
+      const name = String(body.name ?? "Unnamed job");
+      const schedule = String(body.schedule ?? "");
+      const jobType = (body.type as CronJobType) ?? "message";
+      const content = String(body.content ?? "");
+      const timezone = body.timezone ? String(body.timezone) : undefined;
+
+      if (!schedule) return { ok: false, error: "Missing schedule expression" };
+      if (!content) return { ok: false, error: "Missing content" };
+      if (content.length > 10_000) return { ok: false, error: "Content too long (max 10,000 chars)" };
+
+      const validation = validateCronExpression(schedule, timezone);
+      if (!validation.valid) return { ok: false, error: `Invalid cron expression: ${validation.error}` };
+
+      const id = generateCronId();
+      addCronJob({ id, chatId: String(chatId), schedule, type: jobType, content, name, enabled: true, createdAt: Date.now(), runCount: 0, timezone });
+      log("gateway", `create_cron_job: "${name}" [${schedule}]`);
+      return { ok: true, text: `Created cron job "${name}" (id: ${id})\nSchedule: ${schedule}\nType: ${jobType}\nNext run: ${validation.next ?? "unknown"}` };
+    }
+
+    case "list_cron_jobs": {
+      const jobs = getCronJobsForChat(String(chatId));
+      if (jobs.length === 0) return { ok: true, text: "No cron jobs in this chat." };
+      const lines = jobs.map((j) => {
+        const status = j.enabled ? "enabled" : "disabled";
+        const lastRun = j.lastRunAt ? new Date(j.lastRunAt).toISOString().slice(0, 16).replace("T", " ") : "never";
+        const v = validateCronExpression(j.schedule, j.timezone);
+        const nextRun = v.next ? new Date(v.next).toISOString().slice(0, 16).replace("T", " ") : "unknown";
+        return [
+          `- ${j.name} (${status})`, `  ID: ${j.id}`,
+          `  Schedule: ${j.schedule}${j.timezone ? ` (${j.timezone})` : ""}`,
+          `  Type: ${j.type}`, `  Content: ${j.content.slice(0, 100)}${j.content.length > 100 ? "..." : ""}`,
+          `  Runs: ${j.runCount} | Last: ${lastRun} | Next: ${nextRun}`,
+        ].join("\n");
+      });
+      return { ok: true, text: `Cron jobs (${jobs.length}):\n\n${lines.join("\n\n")}` };
+    }
+
+    case "edit_cron_job": {
+      const jobId = String(body.job_id ?? "");
+      if (!jobId) return { ok: false, error: "Missing job_id" };
+      const job = getCronJob(jobId);
+      if (!job) return { ok: false, error: `Job ${jobId} not found` };
+      if (job.chatId !== String(chatId)) return { ok: false, error: "Job belongs to a different chat" };
+
+      const updates: Record<string, unknown> = {};
+      if (body.name !== undefined) updates.name = String(body.name);
+      if (body.content !== undefined) updates.content = String(body.content);
+      if (body.enabled !== undefined) updates.enabled = Boolean(body.enabled);
+      if (body.type !== undefined) updates.type = String(body.type);
+      if (body.timezone !== undefined) updates.timezone = body.timezone ? String(body.timezone) : undefined;
+      if (body.schedule !== undefined) {
+        const v = validateCronExpression(String(body.schedule), (updates.timezone as string | undefined) ?? job.timezone);
+        if (!v.valid) return { ok: false, error: `Invalid cron expression: ${v.error}` };
+        updates.schedule = String(body.schedule);
+      }
+
+      const updated = updateCronJob(jobId, updates);
+      return { ok: true, text: `Updated job "${updated?.name ?? jobId}". Fields changed: ${Object.keys(updates).join(", ")}` };
+    }
+
+    case "delete_cron_job": {
+      const jobId = String(body.job_id ?? "");
+      if (!jobId) return { ok: false, error: "Missing job_id" };
+      const job = getCronJob(jobId);
+      if (!job) return { ok: false, error: `Job ${jobId} not found` };
+      if (job.chatId !== String(chatId)) return { ok: false, error: "Job belongs to a different chat" };
+      deleteCronJob(jobId);
+      return { ok: true, text: `Deleted cron job "${job.name}" (${jobId})` };
+    }
+
+    default:
+      return null; // not a shared action — delegate to frontend
+  }
+}