@calltelemetry/openclaw-linear 0.7.0 → 0.8.0

package/src/infra/notify.ts

@@ -8,21 +8,24 @@
  * 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";
+import type { PluginRuntime, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emitDiagnostic } from "./observability.js";
 
 // ---------------------------------------------------------------------------
 // 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;
@@ -51,6 +54,26 @@ export interface NotifyTarget {
 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)
+// ---------------------------------------------------------------------------
+
+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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -59,58 +82,134 @@ export interface NotificationsConfig {
 
 export function formatMessage(kind: NotifyKind, payload: NotifyPayload): string {
   const id = payload.identifier;
+  const attempt = (payload.attempt ?? 0) + 1; // 1-based for humans
   switch (kind) {
     case "dispatch":
-      return `${id} dispatched — ${payload.title}`;
+      return `${id} started — ${payload.title}`;
     case "working":
-      return `${id} worker started (attempt ${payload.attempt ?? 0})`;
+      return `${id} working on it (attempt ${attempt})`;
     case "auditing":
-      return `${id} audit in progress`;
+      return `${id} checking the work...`;
     case "audit_pass":
-      return `${id} passed audit. PR ready.`;
+      return `✅ ${id} done! Ready for review.`;
     case "audit_fail": {
-      const gaps = payload.verdict?.gaps?.join(", ") ?? "unspecified";
-      return `${id} failed audit (attempt ${payload.attempt ?? 0}). Gaps: ${gaps}`;
+      const issues = payload.verdict?.gaps?.join(", ") ?? "unspecified";
+      return `${id} needs more work (attempt ${attempt}). Issues: ${issues}`;
     }
     case "escalation":
-      return `🚨 ${id} needs human review — ${payload.reason ?? "audit failed 2x"}`;
+      return `🚨 ${id} needs your help — couldn't fix it after ${attempt} ${attempt === 1 ? "try" : "tries"}`;
     case "stuck":
-      return `⏰ ${id} stuck — ${payload.reason ?? "stale 2h"}`;
+      return `⏰ ${id} stuck — ${payload.reason ?? "inactive for 2h"}`;
     case "watchdog_kill":
-      return `⚡ ${id} killed by watchdog (${payload.reason ?? "no I/O for 120s"}). ${
-        payload.attempt != null ? `Retrying (attempt ${payload.attempt}).` : "Will retry."
+      return `⚡ ${id} timed out (${payload.reason ?? "no activity for 120s"}). ${
+        payload.attempt != null ? `Retrying (attempt ${attempt}).` : "Will retry."
       }`;
+    case "project_progress":
+      return `📊 ${payload.title} (${id}): ${payload.status}`;
+    case "project_complete":
+      return `✅ ${payload.title} (${id}): ${payload.status}`;
     default:
       return `${id} — ${kind}: ${payload.status}`;
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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 ?? 0) + 1), inline: true });
+  if (payload.status) fields.push({ name: "Status", value: payload.status, inline: true });
+  if (payload.verdict?.gaps?.length) {
+    fields.push({ name: "Issues to fix", 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 ?? 0) + 1}</code>`);
+  if (payload.status) htmlParts.push(`Status: <code>${escapeHtml(payload.status)}</code>`);
+  if (payload.verdict?.gaps?.length) {
+    htmlParts.push(`Issues to fix:\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,
+  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") {
-    await runtime.channel.discord.sendMessageDiscord(to, message);
+    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, message, {
+    await runtime.channel.slack.sendMessageSlack(to, plainText, {
       accountId: target.accountId,
     });
   } else if (ch === "telegram") {
-    await runtime.channel.telegram.sendMessageTelegram(to, message, { silent: true });
+    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, message);
+    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", message, "--json"], {
+    execFileSync("openclaw", ["message", "send", "--channel", ch, "--target", to, "--message", plainText, "--json"], {
       timeout: 30_000,
       stdio: "ignore",
     });
@@ -131,6 +230,7 @@ export function parseNotificationsConfig(
   return {
     targets: raw?.targets ?? [],
     events: raw?.events ?? {},
+    richFormat: raw?.richFormat ?? false,
   };
 }
 
@@ -143,16 +243,19 @@ export function parseNotificationsConfig(
 export function createNotifierFromConfig(
   pluginConfig: Record<string, unknown> | undefined,
   runtime: PluginRuntime,
+  api?: OpenClawPluginApi,
 ): 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 = formatMessage(kind, payload);
+    const message = useRich ? formatRichMessage(kind, payload) : formatMessage(kind, payload);
 
     await Promise.allSettled(
       config.targets!.map(async (target) => {
@@ -160,6 +263,14 @@ export function createNotifierFromConfig(
           await sendToTarget(target, message, runtime);
         } catch (err) {
           console.error(`Notify error (${target.channel}:${target.target}):`, err);
+          if (api) {
+            emitDiagnostic(api, {
+              event: "notify_failed",
+              identifier: payload.identifier,
+              phase: kind,
+              error: String(err),
+            });
+          }
         }
       }),
     );

package/src/infra/observability.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi } from "vitest";
+import { emitDiagnostic, type DiagnosticPayload } from "./observability.ts";
+
+function makeApi(infoFn = vi.fn()) {
+  return { logger: { info: infoFn } } as any;
+}
+
+describe("emitDiagnostic", () => {
+  it("emits JSON with [linear:diagnostic] prefix via api.logger.info", () => {
+    const info = vi.fn();
+    const api = makeApi(info);
+    emitDiagnostic(api, { event: "webhook_received", identifier: "ISS-42" });
+    expect(info).toHaveBeenCalledOnce();
+    const line = info.mock.calls[0][0] as string;
+    expect(line).toMatch(/^\[linear:diagnostic\] \{/);
+    const json = JSON.parse(line.replace("[linear:diagnostic] ", ""));
+    expect(json.event).toBe("webhook_received");
+    expect(json.identifier).toBe("ISS-42");
+  });
+
+  it("includes all payload fields in JSON output", () => {
+    const info = vi.fn();
+    const api = makeApi(info);
+    const payload: DiagnosticPayload = {
+      event: "dispatch_started",
+      identifier: "ISS-99",
+      issueId: "abc-123",
+      phase: "planning",
+      from: "triage",
+      to: "execution",
+      attempt: 2,
+      tier: "gold",
+      webhookType: "Comment",
+      webhookAction: "create",
+      channel: "discord",
+      target: "kaylee",
+      error: "none",
+      durationMs: 1234,
+    };
+    emitDiagnostic(api, payload);
+    const json = JSON.parse((info.mock.calls[0][0] as string).replace("[linear:diagnostic] ", ""));
+    expect(json).toMatchObject(payload);
+  });
+
+  it("works with partial payload (only event + identifier)", () => {
+    const info = vi.fn();
+    const api = makeApi(info);
+    emitDiagnostic(api, { event: "health_check" });
+    const json = JSON.parse((info.mock.calls[0][0] as string).replace("[linear:diagnostic] ", ""));
+    expect(json.event).toBe("health_check");
+    expect(json.identifier).toBeUndefined();
+  });
+
+  it("never throws even if logger throws", () => {
+    const api = makeApi(() => { throw new Error("logger exploded"); });
+    expect(() => {
+      emitDiagnostic(api, { event: "notify_failed", identifier: "ISS-1" });
+    }).not.toThrow();
+  });
+
+  it("includes timestamp-relevant fields — payload is faithfully serialized", () => {
+    const info = vi.fn();
+    const api = makeApi(info);
+    const now = Date.now();
+    emitDiagnostic(api, { event: "phase_transition", identifier: "ISS-7", timestamp: now } as any);
+    const json = JSON.parse((info.mock.calls[0][0] as string).replace("[linear:diagnostic] ", ""));
+    expect(json.timestamp).toBe(now);
+  });
+
+  it("handles payload with special characters", () => {
+    const info = vi.fn();
+    const api = makeApi(info);
+    emitDiagnostic(api, {
+      event: "notify_sent",
+      identifier: 'ISS-"special"',
+      error: "line1\nline2\ttab",
+      channel: "<script>alert('xss')</script>",
+    });
+    expect(info).toHaveBeenCalledOnce();
+    const json = JSON.parse((info.mock.calls[0][0] as string).replace("[linear:diagnostic] ", ""));
+    expect(json.identifier).toBe('ISS-"special"');
+    expect(json.error).toBe("line1\nline2\ttab");
+    expect(json.channel).toBe("<script>alert('xss')</script>");
+  });
+});

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.test.ts

@@ -337,11 +337,13 @@ describe("buildSummaryFromArtifacts", () => {
 // ---------------------------------------------------------------------------
 
 describe("writeDispatchMemory", () => {
-  it("creates memory/ dir and writes file", () => {
+  it("creates memory/ dir and writes file with frontmatter", () => {
     const tmp = makeTmpDir();
     writeDispatchMemory("API-100", "summary content", tmp);
     const content = readFileSync(join(tmp, "memory", "dispatch-API-100.md"), "utf-8");
-    expect(content).toBe("summary content");
+    expect(content).toContain("---\n");
+    expect(content).toContain('issue: "API-100"');
+    expect(content).toContain("summary content");
   });
 
   it("overwrites on second call", () => {
@@ -349,7 +351,28 @@ describe("writeDispatchMemory", () => {
     writeDispatchMemory("API-100", "first", tmp);
     writeDispatchMemory("API-100", "second", tmp);
     const content = readFileSync(join(tmp, "memory", "dispatch-API-100.md"), "utf-8");
-    expect(content).toBe("second");
+    expect(content).toContain("second");
+    expect(content).not.toContain("first");
+  });
+
+  it("includes custom metadata in frontmatter", () => {
+    const tmp = makeTmpDir();
+    writeDispatchMemory("CT-50", "done summary", tmp, {
+      title: "Fix login bug",
+      tier: "senior",
+      status: "done",
+      project: "Auth",
+      attempts: 2,
+      model: "kimi-k2.5",
+    });
+    const content = readFileSync(join(tmp, "memory", "dispatch-CT-50.md"), "utf-8");
+    expect(content).toContain('title: "Fix login bug"');
+    expect(content).toContain('tier: "senior"');
+    expect(content).toContain('status: "done"');
+    expect(content).toContain('project: "Auth"');
+    expect(content).toContain("attempts: 2");
+    expect(content).toContain('model: "kimi-k2.5"');
+    expect(content).toContain("done summary");
   });
 });