@calltelemetry/openclaw-linear 0.6.1 → 0.7.1

package/src/infra/notify.ts

@@ -1,24 +1,30 @@
 /**
- * notify.ts — Simple notification function for dispatch lifecycle events.
+ * notify.ts — Unified notification provider for dispatch lifecycle events.
  *
- * One concrete Discord implementation + noop fallback.
- * No abstract class — add provider abstraction only when a second
- * backend (Slack, email) actually exists.
+ * Uses OpenClaw's native runtime channel API for all providers (Discord, Slack,
+ * Telegram, Signal, etc). One formatter, one send function, config-driven
+ * fan-out with per-event-type toggles.
+ *
+ * Modeled on DevClaw's notify.ts pattern — the runtime handles token resolution,
+ * formatting differences (markdown vs mrkdwn), and delivery per channel.
  */
+import type { PluginRuntime } from "openclaw/plugin-sdk";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export type NotifyKind =
-  | "dispatch"       // issue dispatched to worker
-  | "working"        // worker started
-  | "auditing"       // audit triggered
-  | "audit_pass"     // audit passed → done
-  | "audit_fail"     // audit failed → rework
-  | "escalation"     // 2x fail or stale → stuck
-  | "stuck"          // stale detection
-  | "watchdog_kill"; // agent killed by inactivity watchdog
+  | "dispatch"          // issue dispatched to worker
+  | "working"           // worker started
+  | "auditing"          // audit triggered
+  | "audit_pass"        // audit passed → done
+  | "audit_fail"        // audit failed → rework
+  | "escalation"        // 2x fail or stale → stuck
+  | "stuck"             // stale detection
+  | "watchdog_kill"     // agent killed by inactivity watchdog
+  | "project_progress"  // DAG dispatch progress update
+  | "project_complete"; // all project issues dispatched
 
 export interface NotifyPayload {
   identifier: string;
@@ -32,58 +38,231 @@ export interface NotifyPayload {
 export type NotifyFn = (kind: NotifyKind, payload: NotifyPayload) => Promise<void>;
 
 // ---------------------------------------------------------------------------
-// Discord implementation
+// Provider config
+// ---------------------------------------------------------------------------
+
+export interface NotifyTarget {
+  /** OpenClaw channel name: "discord", "slack", "telegram", "signal", etc. */
+  channel: string;
+  /** Channel/group/user ID to send to */
+  target: string;
+  /** Optional account ID for multi-account channel setups */
+  accountId?: string;
+}
+
+export interface NotificationsConfig {
+  targets?: NotifyTarget[];
+  events?: Partial<Record<NotifyKind, boolean>>;
+  /** Opt-in: send rich embeds (Discord) and HTML (Telegram) instead of plain text. */
+  richFormat?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Rich message types (Discord embeds + Telegram HTML)
 // ---------------------------------------------------------------------------
 
-const DISCORD_API = "https://discord.com/api/v10";
+export interface DiscordEmbed {
+  title?: string;
+  description?: string;
+  color?: number;
+  fields?: Array<{ name: string; value: string; inline?: boolean }>;
+  footer?: { text: string };
+}
+
+export interface RichMessage {
+  text: string;
+  discord?: { embeds: DiscordEmbed[] };
+  telegram?: { html: string };
+}
+
+// ---------------------------------------------------------------------------
+// Unified message formatter
+// ---------------------------------------------------------------------------
 
-function formatDiscordMessage(kind: NotifyKind, payload: NotifyPayload): string {
-  const prefix = `**${payload.identifier}**`;
+export function formatMessage(kind: NotifyKind, payload: NotifyPayload): string {
+  const id = payload.identifier;
   switch (kind) {
     case "dispatch":
-      return `${prefix} dispatched — ${payload.title}`;
+      return `${id} dispatched — ${payload.title}`;
     case "working":
-      return `${prefix} worker started (attempt ${payload.attempt ?? 0})`;
+      return `${id} worker started (attempt ${payload.attempt ?? 0})`;
     case "auditing":
-      return `${prefix} audit in progress`;
+      return `${id} audit in progress`;
     case "audit_pass":
-      return `${prefix} passed audit. PR ready.`;
+      return `${id} passed audit. PR ready.`;
     case "audit_fail": {
       const gaps = payload.verdict?.gaps?.join(", ") ?? "unspecified";
-      return `${prefix} failed audit (attempt ${payload.attempt ?? 0}). Gaps: ${gaps}`;
+      return `${id} failed audit (attempt ${payload.attempt ?? 0}). Gaps: ${gaps}`;
     }
     case "escalation":
-      return `🚨 ${prefix} needs human review — ${payload.reason ?? "audit failed 2x"}`;
+      return `🚨 ${id} needs human review — ${payload.reason ?? "audit failed 2x"}`;
     case "stuck":
-      return `⏰ ${prefix} stuck — ${payload.reason ?? "stale 2h"}`;
+      return `⏰ ${id} stuck — ${payload.reason ?? "stale 2h"}`;
     case "watchdog_kill":
-      return `⚡ ${prefix} killed by watchdog (${payload.reason ?? "no I/O for 120s"}). ${
+      return `⚡ ${id} killed by watchdog (${payload.reason ?? "no I/O for 120s"}). ${
         payload.attempt != null ? `Retrying (attempt ${payload.attempt}).` : "Will retry."
       }`;
+    case "project_progress":
+      return `📊 ${payload.title} (${id}): ${payload.status}`;
+    case "project_complete":
+      return `✅ ${payload.title} (${id}): ${payload.status}`;
     default:
-      return `${prefix} — ${kind}: ${payload.status}`;
+      return `${id} — ${kind}: ${payload.status}`;
   }
 }
 
-export function createDiscordNotifier(botToken: string, channelId: string): NotifyFn {
-  return async (kind, payload) => {
-    const message = formatDiscordMessage(kind, payload);
-    try {
-      const res = await fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bot ${botToken}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ content: message }),
-      });
-      if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        console.error(`Discord notify failed (${res.status}): ${body}`);
-      }
-    } catch (err) {
-      console.error("Discord notify error:", err);
+// ---------------------------------------------------------------------------
+// Rich message formatter (Discord embeds + Telegram HTML)
+// ---------------------------------------------------------------------------
+
+const EVENT_COLORS: Record<string, number> = {
+  dispatch: 0x3498db,       // blue
+  working: 0x3498db,        // blue
+  auditing: 0xf39c12,       // yellow
+  audit_pass: 0x2ecc71,     // green
+  audit_fail: 0xe74c3c,     // red
+  escalation: 0xe74c3c,     // red
+  stuck: 0xe67e22,          // orange
+  watchdog_kill: 0x9b59b6,  // purple
+  project_progress: 0x3498db,
+  project_complete: 0x2ecc71,
+};
+
+export function formatRichMessage(kind: NotifyKind, payload: NotifyPayload): RichMessage {
+  const text = formatMessage(kind, payload);
+  const color = EVENT_COLORS[kind] ?? 0x95a5a6;
+
+  // Discord embed
+  const fields: DiscordEmbed["fields"] = [];
+  if (payload.attempt != null) fields.push({ name: "Attempt", value: String(payload.attempt), inline: true });
+  if (payload.status) fields.push({ name: "Status", value: payload.status, inline: true });
+  if (payload.verdict?.gaps?.length) {
+    fields.push({ name: "Gaps", value: payload.verdict.gaps.join("\n").slice(0, 1024) });
+  }
+  if (payload.reason) fields.push({ name: "Reason", value: payload.reason });
+
+  const embed: DiscordEmbed = {
+    title: `${payload.identifier} — ${kind.replace(/_/g, " ")}`,
+    description: payload.title,
+    color,
+    fields: fields.length > 0 ? fields : undefined,
+    footer: { text: `Linear Agent • ${kind}` },
+  };
+
+  // Telegram HTML
+  const htmlParts: string[] = [
+    `<b>${escapeHtml(payload.identifier)}</b> — ${escapeHtml(kind.replace(/_/g, " "))}`,
+    `<i>${escapeHtml(payload.title)}</i>`,
+  ];
+  if (payload.attempt != null) htmlParts.push(`Attempt: <code>${payload.attempt}</code>`);
+  if (payload.status) htmlParts.push(`Status: <code>${escapeHtml(payload.status)}</code>`);
+  if (payload.verdict?.gaps?.length) {
+    htmlParts.push(`Gaps:\n${payload.verdict.gaps.map(g => `• ${escapeHtml(g)}`).join("\n")}`);
+  }
+  if (payload.reason) htmlParts.push(`Reason: ${escapeHtml(payload.reason)}`);
+
+  return {
+    text,
+    discord: { embeds: [embed] },
+    telegram: { html: htmlParts.join("\n") },
+  };
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// ---------------------------------------------------------------------------
+// Unified send — routes to OpenClaw runtime channel API
+// ---------------------------------------------------------------------------
+
+export async function sendToTarget(
+  target: NotifyTarget,
+  message: string | RichMessage,
+  runtime: PluginRuntime,
+): Promise<void> {
+  const ch = target.channel;
+  const to = target.target;
+  const isRich = typeof message !== "string";
+  const plainText = isRich ? message.text : message;
+
+  if (ch === "discord") {
+    if (isRich && message.discord) {
+      await runtime.channel.discord.sendMessageDiscord(to, plainText, { embeds: message.discord.embeds });
+    } else {
+      await runtime.channel.discord.sendMessageDiscord(to, plainText);
     }
+  } else if (ch === "slack") {
+    await runtime.channel.slack.sendMessageSlack(to, plainText, {
+      accountId: target.accountId,
+    });
+  } else if (ch === "telegram") {
+    if (isRich && message.telegram) {
+      await runtime.channel.telegram.sendMessageTelegram(to, message.telegram.html, { silent: true, textMode: "html" });
+    } else {
+      await runtime.channel.telegram.sendMessageTelegram(to, plainText, { silent: true });
+    }
+  } else if (ch === "signal") {
+    await runtime.channel.signal.sendMessageSignal(to, plainText);
+  } else {
+    // Fallback: use CLI for any channel the runtime doesn't expose directly
+    const { execFileSync } = await import("node:child_process");
+    execFileSync("openclaw", ["message", "send", "--channel", ch, "--target", to, "--message", plainText, "--json"], {
+      timeout: 30_000,
+      stdio: "ignore",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config-driven factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse notification config from plugin config.
+ */
+export function parseNotificationsConfig(
+  pluginConfig: Record<string, unknown> | undefined,
+): NotificationsConfig {
+  const raw = pluginConfig?.notifications as NotificationsConfig | undefined;
+  return {
+    targets: raw?.targets ?? [],
+    events: raw?.events ?? {},
+    richFormat: raw?.richFormat ?? false,
+  };
+}
+
+/**
+ * Create a notifier from plugin config. Returns a NotifyFn that:
+ * 1. Checks event toggles (skip suppressed events)
+ * 2. Formats the message
+ * 3. Fans out to all configured targets (failures isolated via Promise.allSettled)
+ */
+export function createNotifierFromConfig(
+  pluginConfig: Record<string, unknown> | undefined,
+  runtime: PluginRuntime,
+): NotifyFn {
+  const config = parseNotificationsConfig(pluginConfig);
+
+  if (!config.targets?.length) return createNoopNotifier();
+
+  const useRich = config.richFormat === true;
+
+  return async (kind, payload) => {
+    // Check event toggle — default is enabled (true)
+    if (config.events?.[kind] === false) return;
+
+    const message = useRich ? formatRichMessage(kind, payload) : formatMessage(kind, payload);
+
+    await Promise.allSettled(
+      config.targets!.map(async (target) => {
+        try {
+          await sendToTarget(target, message, runtime);
+        } catch (err) {
+          console.error(`Notify error (${target.channel}:${target.target}):`, err);
+        }
+      }),
+    );
   };
 }
 

package/src/infra/observability.ts

@@ -0,0 +1,48 @@
+/**
+ * observability.ts — Structured diagnostic event logging.
+ *
+ * Emits structured JSON log lines via api.logger for lifecycle telemetry.
+ * Consumers (log aggregators, monitoring) can parse these for dashboards.
+ *
+ * Pattern: `[linear:diagnostic] {...json...}`
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export type DiagnosticEvent =
+  | "webhook_received"
+  | "dispatch_started"
+  | "phase_transition"
+  | "audit_triggered"
+  | "verdict_processed"
+  | "watchdog_kill"
+  | "notify_sent"
+  | "notify_failed"
+  | "health_check";
+
+export interface DiagnosticPayload {
+  event: DiagnosticEvent;
+  identifier?: string;
+  issueId?: string;
+  phase?: string;
+  from?: string;
+  to?: string;
+  attempt?: number;
+  tier?: string;
+  webhookType?: string;
+  webhookAction?: string;
+  channel?: string;
+  target?: string;
+  error?: string;
+  durationMs?: number;
+  [key: string]: unknown;
+}
+
+const PREFIX = "[linear:diagnostic]";
+
+export function emitDiagnostic(api: OpenClawPluginApi, payload: DiagnosticPayload): void {
+  try {
+    api.logger.info(`${PREFIX} ${JSON.stringify(payload)}`);
+  } catch {
+    // Never throw from telemetry
+  }
+}

package/src/infra/resilience.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  createRetryPolicy,
+  createCircuitBreaker,
+  withResilience,
+  resetDefaultPolicy,
+} from "./resilience.js";
+import { BrokenCircuitError } from "cockatiel";
+
+beforeEach(() => {
+  resetDefaultPolicy();
+});
+
+describe("createRetryPolicy", () => {
+  it("retries on transient failure then succeeds", async () => {
+    let calls = 0;
+    const policy = createRetryPolicy({ attempts: 3, initialDelay: 10, maxDelay: 20 });
+    const result = await policy.execute(async () => {
+      calls++;
+      if (calls < 3) throw new Error("transient");
+      return "ok";
+    });
+    expect(result).toBe("ok");
+    expect(calls).toBe(3);
+  });
+
+  it("throws after exhausting retries", async () => {
+    const policy = createRetryPolicy({ attempts: 2, initialDelay: 10, maxDelay: 20 });
+    await expect(
+      policy.execute(async () => {
+        throw new Error("permanent");
+      }),
+    ).rejects.toThrow("permanent");
+  });
+});
+
+describe("createCircuitBreaker", () => {
+  it("opens after consecutive failures", async () => {
+    const breaker = createCircuitBreaker({ threshold: 3, halfOpenAfter: 60_000 });
+
+    // Fail 3 times to trip the breaker
+    for (let i = 0; i < 3; i++) {
+      try {
+        await breaker.execute(async () => {
+          throw new Error("fail");
+        });
+      } catch {}
+    }
+
+    // Next call should fail fast with BrokenCircuitError
+    await expect(
+      breaker.execute(async () => "should not run"),
+    ).rejects.toThrow(BrokenCircuitError);
+  });
+
+  it("allows calls when under threshold", async () => {
+    const breaker = createCircuitBreaker({ threshold: 5, halfOpenAfter: 60_000 });
+
+    // Fail twice then succeed — should not trip
+    let calls = 0;
+    for (let i = 0; i < 2; i++) {
+      try {
+        await breaker.execute(async () => {
+          throw new Error("fail");
+        });
+      } catch {}
+    }
+
+    const result = await breaker.execute(async () => {
+      calls++;
+      return "ok";
+    });
+    expect(result).toBe("ok");
+    expect(calls).toBe(1);
+  });
+});
+
+describe("withResilience", () => {
+  it("returns result on success", async () => {
+    const result = await withResilience(async () => 42);
+    expect(result).toBe(42);
+  });
+
+  it("retries transient failures", async () => {
+    let calls = 0;
+    const result = await withResilience(async () => {
+      calls++;
+      if (calls < 2) throw new Error("transient");
+      return "recovered";
+    });
+    expect(result).toBe("recovered");
+    expect(calls).toBe(2);
+  });
+});

package/src/infra/resilience.ts

@@ -0,0 +1,101 @@
+/**
+ * resilience.ts — Retry + circuit breaker for external API calls.
+ *
+ * Wraps functions with exponential backoff retry and a circuit breaker
+ * that opens after consecutive failures to prevent cascading overload.
+ */
+import {
+  retry,
+  handleAll,
+  ExponentialBackoff,
+  CircuitBreakerPolicy,
+  circuitBreaker,
+  ConsecutiveBreaker,
+  wrap,
+  type IPolicy,
+} from "cockatiel";
+
+// ---------------------------------------------------------------------------
+// Retry policy
+// ---------------------------------------------------------------------------
+
+const DEFAULT_RETRY_ATTEMPTS = 3;
+const DEFAULT_BACKOFF = { initialDelay: 500, maxDelay: 5_000 };
+
+/**
+ * Create a retry policy with exponential backoff.
+ */
+export function createRetryPolicy(opts?: {
+  attempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+}): IPolicy {
+  const attempts = opts?.attempts ?? DEFAULT_RETRY_ATTEMPTS;
+  const initialDelay = opts?.initialDelay ?? DEFAULT_BACKOFF.initialDelay;
+  const maxDelay = opts?.maxDelay ?? DEFAULT_BACKOFF.maxDelay;
+
+  return retry(handleAll, {
+    maxAttempts: attempts,
+    backoff: new ExponentialBackoff({
+      initialDelay,
+      maxDelay,
+    }),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Circuit breaker
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BREAKER_THRESHOLD = 5;
+const DEFAULT_HALF_OPEN_AFTER = 30_000;
+
+/**
+ * Create a circuit breaker that opens after consecutive failures.
+ */
+export function createCircuitBreaker(opts?: {
+  threshold?: number;
+  halfOpenAfter?: number;
+}): CircuitBreakerPolicy {
+  const threshold = opts?.threshold ?? DEFAULT_BREAKER_THRESHOLD;
+  const halfOpenAfter = opts?.halfOpenAfter ?? DEFAULT_HALF_OPEN_AFTER;
+
+  return circuitBreaker(handleAll, {
+    breaker: new ConsecutiveBreaker(threshold),
+    halfOpenAfter,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Combined policy
+// ---------------------------------------------------------------------------
+
+let _defaultPolicy: IPolicy | null = null;
+
+/**
+ * Get the default combined retry + circuit breaker policy (singleton).
+ * 3 retries with exponential backoff (500ms → 5s) + circuit breaker
+ * (opens after 5 consecutive failures, half-opens after 30s).
+ */
+export function getDefaultPolicy(): IPolicy {
+  if (!_defaultPolicy) {
+    const retryPolicy = createRetryPolicy();
+    const breaker = createCircuitBreaker();
+    _defaultPolicy = wrap(retryPolicy, breaker);
+  }
+  return _defaultPolicy;
+}
+
+/**
+ * Execute a function with the default retry + circuit breaker policy.
+ */
+export async function withResilience<T>(fn: () => Promise<T>): Promise<T> {
+  return getDefaultPolicy().execute(fn);
+}
+
+/**
+ * Reset the default policy singleton (for testing).
+ */
+export function resetDefaultPolicy(): void {
+  _defaultPolicy = null;
+}

package/src/pipeline/artifacts.ts

@@ -229,22 +229,58 @@ export function buildSummaryFromArtifacts(worktreePath: string): string | null {
 // Memory integration
 // ---------------------------------------------------------------------------
 
+export interface DispatchMemoryMetadata {
+  type: "dispatch";
+  issue: string;
+  title: string;
+  tier: string;
+  status: string;
+  project?: string;
+  attempts: number;
+  model: string;
+  date: string;
+}
+
 /**
- * Write dispatch summary to the orchestrator's memory directory.
+ * Write dispatch summary to the orchestrator's memory directory
+ * with YAML frontmatter for searchable metadata.
  * Auto-indexed by OpenClaw's sqlite+embeddings memory system.
  */
 export function writeDispatchMemory(
   issueIdentifier: string,
   summary: string,
   workspaceDir: string,
+  metadata?: Partial<DispatchMemoryMetadata>,
 ): void {
   const memDir = join(workspaceDir, "memory");
   if (!existsSync(memDir)) {
     mkdirSync(memDir, { recursive: true });
   }
+
+  const fm: DispatchMemoryMetadata = {
+    type: "dispatch",
+    issue: issueIdentifier,
+    title: metadata?.title ?? issueIdentifier,
+    tier: metadata?.tier ?? "unknown",
+    status: metadata?.status ?? "unknown",
+    project: metadata?.project,
+    attempts: metadata?.attempts ?? 0,
+    model: metadata?.model ?? "unknown",
+    date: metadata?.date ?? new Date().toISOString().slice(0, 10),
+  };
+
+  const frontmatter = [
+    "---",
+    ...Object.entries(fm)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => `${k}: ${typeof v === "string" ? `"${v}"` : v}`),
+    "---",
+    "",
+  ].join("\n");
+
   writeFileSync(
     join(memDir, `dispatch-${issueIdentifier}.md`),
-    summary,
+    frontmatter + summary,
     "utf-8",
   );
 }