clawmatrix 0.4.2 → 0.5.0

package/src/automation.ts

@@ -0,0 +1,625 @@
+/**
+ * AutomationManager — rule-based automation triggers.
+ *
+ * Rules are stored in `.clawmatrix/automations.json` and can be synced
+ * across devices via CRDT knowledge sync. When an ingested event matches
+ * a rule's trigger, an action is automatically dispatched.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { watch, type FSWatcher } from "node:fs";
+import { nanoid } from "nanoid";
+import type { HandoffManager } from "./handoff.ts";
+import type { PeerManager } from "./peer-manager.ts";
+import type { IngestedEvent } from "./types.ts";
+import { debug } from "./debug.ts";
+import type { Store } from "./store.ts";
+
+const MAX_EXECUTIONS = 100;
+const DEFAULT_COOLDOWN_MS = 30_000;
+const DEFAULT_RETRY_DELAY_MS = 5_000;
+const MAX_CONCURRENT = 3;
+const FILE_WATCH_DEBOUNCE_MS = 1_000;
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface AutomationTrigger {
+  type: "event" | "schedule";
+  source?: string;
+  eventType?: string;
+  intervalMs?: number;
+}
+
+export interface AutomationCondition {
+  path: string;
+  operator: "exists" | "not_exists" | "eq" | "ne" | "contains" | "gt" | "gte" | "lt" | "lte";
+  value?: string | number | boolean;
+}
+
+export interface AutomationHandoffAction {
+  type?: "handoff";
+  agent: string;
+  task: string;
+}
+
+export interface AutomationToolAction {
+  type: "tool";
+  node: string;
+  tool: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+}
+
+export interface AutomationNotifyAction {
+  type: "notify";
+  title: string;
+  detail?: string;
+  progress?: number;
+  success?: boolean;
+}
+
+export type AutomationAction =
+  | AutomationHandoffAction
+  | AutomationToolAction
+  | AutomationNotifyAction;
+
+export interface AutomationRetryPolicy {
+  maxAttempts?: number;
+  delayMs?: number;
+}
+
+export interface AutomationRule {
+  id: string;
+  name: string;
+  enabled: boolean;
+  trigger: AutomationTrigger;
+  conditions?: AutomationCondition[];
+  action: AutomationAction;
+  notify?: boolean;
+  cooldownMs?: number;
+  retry?: AutomationRetryPolicy;
+}
+
+export interface AutomationExecution {
+  id: string;
+  ruleId: string;
+  ruleName: string;
+  status: "running" | "success" | "error";
+  startedAt: number;
+  finishedAt?: number;
+  result?: string;
+  error?: string;
+  attempt: number;
+  maxAttempts: number;
+  triggerSource?: string;
+  triggerType?: string;
+  triggerPayload?: string;
+  actionType: "handoff" | "tool" | "notify";
+}
+
+interface AutomationsFile {
+  rules: AutomationRule[];
+}
+
+interface ToolInvoker {
+  invoke(node: string, tool: string, params: Record<string, unknown>, timeout?: number): Promise<Record<string, unknown>>;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function resolvePath(data: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".");
+  let current: unknown = data;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function interpolateTemplate(template: string, data: Record<string, unknown>): string {
+  return template.replace(/\$\{([^}]+)\}/g, (_match, expression: string) => {
+    const trimmed = expression.trim();
+    const path = trimmed.startsWith("data.") || trimmed.startsWith("event.")
+      ? trimmed
+      : `data.${trimmed}`;
+    const value = resolvePath(data, path);
+    return value != null ? String(value) : "";
+  });
+}
+
+function interpolateUnknown(value: unknown, context: Record<string, unknown>): unknown {
+  if (typeof value === "string") return interpolateTemplate(value, context);
+  if (Array.isArray(value)) return value.map((item) => interpolateUnknown(item, context));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, inner]) => [key, interpolateUnknown(inner, context)]),
+    );
+  }
+  return value;
+}
+
+function coerceComparable(value: unknown): { number: number | null; text: string } {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return { number: value, text: String(value) };
+  }
+  if (typeof value === "boolean") {
+    return { number: Number(value), text: String(value) };
+  }
+  if (typeof value === "string") {
+    const number = Number(value);
+    return {
+      number: Number.isFinite(number) && value.trim() !== "" ? number : null,
+      text: value,
+    };
+  }
+  return { number: null, text: value == null ? "" : String(value) };
+}
+
+function matchesCondition(condition: AutomationCondition, data: Record<string, unknown>): boolean {
+  const actual = resolvePath(data, condition.path);
+  const expected = condition.value;
+  const actualCmp = coerceComparable(actual);
+  const expectedCmp = coerceComparable(expected);
+
+  switch (condition.operator) {
+    case "exists":
+      return actual !== undefined;
+    case "not_exists":
+      return actual === undefined;
+    case "eq":
+      return actualCmp.number != null && expectedCmp.number != null
+        ? actualCmp.number === expectedCmp.number
+        : actualCmp.text === expectedCmp.text;
+    case "ne":
+      return actualCmp.number != null && expectedCmp.number != null
+        ? actualCmp.number !== expectedCmp.number
+        : actualCmp.text !== expectedCmp.text;
+    case "contains":
+      if (Array.isArray(actual)) return actual.includes(expected);
+      return actualCmp.text.includes(expectedCmp.text);
+    case "gt":
+      return actualCmp.number != null && expectedCmp.number != null && actualCmp.number > expectedCmp.number;
+    case "gte":
+      return actualCmp.number != null && expectedCmp.number != null && actualCmp.number >= expectedCmp.number;
+    case "lt":
+      return actualCmp.number != null && expectedCmp.number != null && actualCmp.number < expectedCmp.number;
+    case "lte":
+      return actualCmp.number != null && expectedCmp.number != null && actualCmp.number <= expectedCmp.number;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function clampInteger(value: number | undefined, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+function normalizeAction(action: AutomationAction): AutomationAction {
+  if (!("type" in action) || action.type == null) {
+    return { ...action, type: "handoff" } as AutomationHandoffAction;
+  }
+  return action;
+}
+
+function buildTemplateContext(event?: IngestedEvent, data: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    data,
+    event: event
+      ? {
+          id: event.id,
+          source: event.source,
+          type: event.type,
+          ts: event.ts,
+          data: event.data,
+        }
+      : undefined,
+  };
+}
+
+function serializeTriggerPayload(event?: IngestedEvent, data: Record<string, unknown> = {}): string | undefined {
+  if (!event && Object.keys(data).length === 0) return undefined;
+  return JSON.stringify({
+    event: event ?? null,
+    data,
+  });
+}
+
+// ── AutomationManager ────────────────────────────────────────────────
+
+export class AutomationManager {
+  private rules: AutomationRule[] = [];
+  private executions: AutomationExecution[] = [];
+  private scheduleTimers = new Map<string, ReturnType<typeof setInterval>>();
+  private lastFired = new Map<string, number>();
+  private running = 0;
+  private filePath: string;
+  private watcher: FSWatcher | null = null;
+  private watchDebounce: ReturnType<typeof setTimeout> | null = null;
+  private handoffManager: HandoffManager;
+  private peerManager: PeerManager;
+  private nodeId: string;
+  private store: Store | null = null;
+  private toolInvoker: ToolInvoker | null = null;
+
+  constructor(filePath: string, handoffManager: HandoffManager, peerManager: PeerManager, nodeId: string) {
+    this.filePath = filePath;
+    this.handoffManager = handoffManager;
+    this.peerManager = peerManager;
+    this.nodeId = nodeId;
+  }
+
+  async start(): Promise<void> {
+    await this.loadRules();
+    this.startScheduleTimers();
+    this.startFileWatch();
+    debug("automation", `started with ${this.rules.length} rule(s)`);
+  }
+
+  stop(): void {
+    this.stopScheduleTimers();
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+    if (this.watchDebounce) {
+      clearTimeout(this.watchDebounce);
+      this.watchDebounce = null;
+    }
+  }
+
+  setStore(store: Store) {
+    this.store = store;
+    this.executions = store.queryAutomationExecutions(MAX_EXECUTIONS)
+      .reverse()
+      .map((row) => ({
+        id: row.id,
+        ruleId: row.rule_id,
+        ruleName: row.rule_name,
+        status: row.status as AutomationExecution["status"],
+        startedAt: row.started_at,
+        finishedAt: row.finished_at ?? undefined,
+        result: row.result ?? undefined,
+        error: row.error ?? undefined,
+        attempt: row.attempt,
+        maxAttempts: row.max_attempts,
+        triggerSource: row.trigger_source ?? undefined,
+        triggerType: row.trigger_type ?? undefined,
+        triggerPayload: row.trigger_payload ?? undefined,
+        actionType: this.resolveActionType(row.rule_id),
+      }));
+  }
+
+  setToolInvoker(toolInvoker: ToolInvoker) {
+    this.toolInvoker = toolInvoker;
+  }
+
+  onEventIngested(event: IngestedEvent): void {
+    for (const rule of this.rules) {
+      if (!rule.enabled) continue;
+      if (rule.trigger.type !== "event") continue;
+      if (!this.matchesEvent(rule, event)) continue;
+      if (this.isOnCooldown(rule)) continue;
+
+      void this.executeRule(rule, event, event.data);
+    }
+  }
+
+  getRules(): AutomationRule[] {
+    return this.rules;
+  }
+
+  getExecutions(limit = 50): AutomationExecution[] {
+    return this.executions.slice(-limit).reverse();
+  }
+
+  async saveRules(rules: AutomationRule[]): Promise<void> {
+    const normalized = rules.map((rule) => ({ ...rule, action: normalizeAction(rule.action) }));
+    const content: AutomationsFile = { rules: normalized };
+    await writeFile(this.filePath, JSON.stringify(content, null, 2), "utf-8");
+    this.stopScheduleTimers();
+    this.rules = normalized;
+    this.startScheduleTimers();
+    debug("automation", `saved ${normalized.length} rule(s)`);
+  }
+
+  async runRuleById(ruleId: string, event?: IngestedEvent): Promise<AutomationExecution> {
+    const rule = this.rules.find((candidate) => candidate.id === ruleId);
+    if (!rule) throw new Error(`Automation rule "${ruleId}" not found`);
+    const execution = await this.executeRule(rule, event, event?.data ?? {});
+    return execution;
+  }
+
+  async replayExecution(executionId: string): Promise<AutomationExecution> {
+    const execution = this.executions.find((item) => item.id === executionId);
+    const persisted = this.store?.getAutomationExecution(executionId) ?? null;
+    const target = execution ?? (persisted ? {
+      id: persisted.id,
+      ruleId: persisted.rule_id,
+      ruleName: persisted.rule_name,
+      status: persisted.status as AutomationExecution["status"],
+      startedAt: persisted.started_at,
+      finishedAt: persisted.finished_at ?? undefined,
+      result: persisted.result ?? undefined,
+      error: persisted.error ?? undefined,
+      attempt: persisted.attempt,
+      maxAttempts: persisted.max_attempts,
+      triggerSource: persisted.trigger_source ?? undefined,
+      triggerType: persisted.trigger_type ?? undefined,
+      triggerPayload: persisted.trigger_payload ?? undefined,
+      actionType: this.resolveActionType(persisted.rule_id),
+    } : null);
+    if (!target) throw new Error(`Automation execution "${executionId}" not found`);
+
+    const rule = this.rules.find((candidate) => candidate.id === target.ruleId);
+    if (!rule) throw new Error(`Automation rule "${target.ruleId}" not found`);
+
+    let replayEvent: IngestedEvent | undefined;
+    let replayData: Record<string, unknown> = {};
+    if (target.triggerPayload) {
+      try {
+        const parsed = JSON.parse(target.triggerPayload) as { event?: IngestedEvent | null; data?: Record<string, unknown> };
+        replayEvent = parsed.event ?? undefined;
+        replayData = parsed.data ?? replayEvent?.data ?? {};
+      } catch {
+        replayData = {};
+      }
+    }
+
+    return this.executeRule(rule, replayEvent, replayData);
+  }
+
+  // ── Private ──────────────────────────────────────────────────────
+
+  private matchesEvent(rule: AutomationRule, event: IngestedEvent): boolean {
+    if (rule.trigger.source && rule.trigger.source !== event.source) return false;
+    if (rule.trigger.eventType && rule.trigger.eventType !== event.type) return false;
+    if (rule.conditions && rule.conditions.length > 0) {
+      return rule.conditions.every((condition) => matchesCondition(condition, event.data));
+    }
+    return true;
+  }
+
+  private isOnCooldown(rule: AutomationRule): boolean {
+    const last = this.lastFired.get(rule.id);
+    if (!last) return false;
+    const cooldown = rule.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    return Date.now() - last < cooldown;
+  }
+
+  private resolveActionType(ruleId: string): AutomationExecution["actionType"] {
+    const rule = this.rules.find((candidate) => candidate.id === ruleId);
+    const type = rule ? normalizeAction(rule.action).type ?? "handoff" : "handoff";
+    return type;
+  }
+
+  private async executeRule(rule: AutomationRule, event?: IngestedEvent, data: Record<string, unknown> = {}): Promise<AutomationExecution> {
+    if (this.running >= MAX_CONCURRENT) {
+      throw new Error(`Automation busy: max concurrent (${MAX_CONCURRENT}) reached`);
+    }
+
+    this.lastFired.set(rule.id, Date.now());
+    this.running++;
+
+    const maxAttempts = clampInteger(rule.retry?.maxAttempts, 1, 1, 5);
+    const retryDelayMs = clampInteger(rule.retry?.delayMs, DEFAULT_RETRY_DELAY_MS, 0, 300_000);
+    const normalizedAction = normalizeAction(rule.action);
+
+    const execution: AutomationExecution = {
+      id: nanoid(),
+      ruleId: rule.id,
+      ruleName: rule.name,
+      status: "running",
+      startedAt: Date.now(),
+      attempt: 1,
+      maxAttempts,
+      triggerSource: event?.source,
+      triggerType: event?.type,
+      triggerPayload: serializeTriggerPayload(event, data),
+      actionType: normalizedAction.type ?? "handoff",
+    };
+    this.pushExecution(execution);
+    this.persistExecution(execution);
+
+    const templateContext = buildTemplateContext(event, data);
+
+    try {
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        execution.attempt = attempt;
+        execution.error = undefined;
+        execution.result = undefined;
+        this.persistExecution(execution);
+
+        try {
+          execution.result = await this.performAction(normalizedAction, templateContext, rule.name, execution);
+          execution.status = "success";
+          execution.finishedAt = Date.now();
+          this.persistExecution(execution);
+          if (rule.notify) this.sendCompletionNotification(rule, execution);
+          return execution;
+        } catch (err) {
+          execution.error = err instanceof Error ? err.message : String(err);
+        }
+
+        if (attempt < maxAttempts && retryDelayMs > 0) {
+          this.persistExecution(execution);
+          await sleep(retryDelayMs);
+        }
+      }
+
+      execution.status = "error";
+      execution.finishedAt = Date.now();
+      if (!execution.error) execution.error = "Automation failed after retries";
+      this.persistExecution(execution);
+      if (rule.notify) this.sendCompletionNotification(rule, execution);
+      return execution;
+    } finally {
+      this.running--;
+    }
+  }
+
+  private async performAction(
+    action: AutomationAction,
+    templateContext: Record<string, unknown>,
+    ruleName: string,
+    execution: AutomationExecution,
+  ): Promise<string> {
+    if (action.type === "tool") {
+      if (!this.toolInvoker) {
+        throw new Error("Tool invoker not available");
+      }
+      const params = (interpolateUnknown(action.params ?? {}, templateContext) as Record<string, unknown>) ?? {};
+      const result = await this.toolInvoker.invoke(
+        interpolateTemplate(action.node, templateContext),
+        interpolateTemplate(action.tool, templateContext),
+        params,
+        action.timeoutMs,
+      );
+      return JSON.stringify(result);
+    }
+
+    if (action.type === "notify") {
+      const title = interpolateTemplate(action.title, templateContext);
+      const detail = action.detail ? interpolateTemplate(action.detail, templateContext) : undefined;
+      this.broadcastNotify(title, detail, action.progress, action.success ?? true, execution.id);
+      return detail ? `${title}: ${detail}` : title;
+    }
+
+    const task = interpolateTemplate(action.task, templateContext);
+    debug("automation", `executing rule "${ruleName}" (attempt ${execution.attempt}/${execution.maxAttempts}) → agent "${action.agent}": ${task.slice(0, 100)}`);
+    const result = await this.handoffManager.handoff(action.agent, task);
+    if (!result.success) {
+      throw new Error(result.error ?? "Automation handoff failed");
+    }
+    return result.result ?? "";
+  }
+
+  private sendCompletionNotification(rule: AutomationRule, execution: AutomationExecution): void {
+    const title = execution.status === "success"
+      ? `✅ ${rule.name} 完成`
+      : `❌ ${rule.name} 失败`;
+    const baseDetail = execution.status === "success"
+      ? (execution.result?.slice(0, 200) ?? "")
+      : (execution.error?.slice(0, 200) ?? "");
+    const detail = execution.maxAttempts > 1
+      ? `[尝试 ${execution.attempt}/${execution.maxAttempts}] ${baseDetail}`.trim()
+      : baseDetail;
+    this.broadcastNotify(title, detail, execution.status === "success" ? 1 : undefined, execution.status === "success", execution.id);
+  }
+
+  private broadcastNotify(title: string, detail?: string, progress?: number, success = true, executionId?: string): void {
+    try {
+      this.peerManager.router.broadcast({
+        type: "task_activity",
+        id: nanoid(),
+        from: this.nodeId,
+        timestamp: Date.now(),
+        payload: {
+          action: "update",
+          taskId: `automation:${executionId ?? nanoid()}`,
+          title,
+          detail,
+          progress,
+          status: success ? "completed" : "error",
+        },
+      });
+    } catch {
+      // Non-critical
+    }
+  }
+
+  private pushExecution(execution: AutomationExecution): void {
+    this.executions.push(execution);
+    if (this.executions.length > MAX_EXECUTIONS) {
+      this.executions.splice(0, this.executions.length - MAX_EXECUTIONS);
+    }
+  }
+
+  private persistExecution(execution: AutomationExecution): void {
+    if (!this.store) return;
+    try {
+      this.store.upsertAutomationExecution({
+        id: execution.id,
+        ruleId: execution.ruleId,
+        ruleName: execution.ruleName,
+        status: execution.status,
+        startedAt: execution.startedAt,
+        finishedAt: execution.finishedAt,
+        result: execution.result,
+        error: execution.error,
+        attempt: execution.attempt,
+        maxAttempts: execution.maxAttempts,
+        triggerSource: execution.triggerSource,
+        triggerType: execution.triggerType,
+        triggerPayload: execution.triggerPayload,
+      });
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  private async loadRules(): Promise<void> {
+    try {
+      const content = await readFile(this.filePath, "utf-8");
+      const parsed = JSON.parse(content) as AutomationsFile;
+      if (Array.isArray(parsed.rules)) {
+        this.rules = parsed.rules.map((rule) => ({ ...rule, action: normalizeAction(rule.action) }));
+      }
+    } catch {
+      this.rules = [];
+    }
+  }
+
+  private startScheduleTimers(): void {
+    for (const rule of this.rules) {
+      if (!rule.enabled) continue;
+      if (rule.trigger.type !== "schedule") continue;
+      if (!rule.trigger.intervalMs || rule.trigger.intervalMs < 10_000) continue;
+
+      const timer = setInterval(() => {
+        if (!this.isOnCooldown(rule)) {
+          void this.executeRule(rule);
+        }
+      }, rule.trigger.intervalMs);
+
+      this.scheduleTimers.set(rule.id, timer);
+    }
+  }
+
+  private stopScheduleTimers(): void {
+    for (const timer of this.scheduleTimers.values()) {
+      clearInterval(timer);
+    }
+    this.scheduleTimers.clear();
+  }
+
+  private startFileWatch(): void {
+    try {
+      this.watcher = watch(this.filePath, () => {
+        if (this.watchDebounce) clearTimeout(this.watchDebounce);
+        this.watchDebounce = setTimeout(() => {
+          this.watchDebounce = null;
+          void this.reloadFromFile();
+        }, FILE_WATCH_DEBOUNCE_MS);
+      });
+    } catch {
+      // File may not exist yet
+    }
+  }
+
+  private async reloadFromFile(): Promise<void> {
+    const oldRuleIds = new Set(this.rules.map((r) => r.id));
+    await this.loadRules();
+    const newRuleIds = new Set(this.rules.map((r) => r.id));
+
+    if (oldRuleIds.size !== newRuleIds.size || [...oldRuleIds].some((id) => !newRuleIds.has(id))) {
+      this.stopScheduleTimers();
+      this.startScheduleTimers();
+    }
+
+    debug("automation", `reloaded ${this.rules.length} rule(s) from file`);
+  }
+}