@calltelemetry/openclaw-linear 0.8.2 → 0.8.3

package/README.md

@@ -36,7 +36,7 @@ Go to **Linear Settings > API > Applications** and create an app:
 - Enable events: **Agent Sessions**, **Comments**, **Issues**
 - Save your **Client ID** and **Client Secret**
 
-> You also need a **workspace webhook** (Settings > API > Webhooks) pointing to the same URL with Comment + Issue + User events enabled. Both webhooks are required.
+> You also need a **workspace webhook** — run `openclaw openclaw-linear webhooks setup` to auto-provision it, or manually create one in Settings > API > Webhooks pointing to the same URL with **Comment + Issue** events enabled. Both webhooks are required.
 
 ### 3. Set credentials
 
@@ -310,6 +310,25 @@ User comment → Intent Classifier (small model, ~2s) → Route to handler
 
 > **Tip:** Configure `classifierAgentId` to point to a small/fast model agent (like Haiku) for low-latency, low-cost intent classification. The classifier only needs ~300 tokens per call.
 
+### Deduplication
+
+The webhook handler prevents double-processing through a two-tier guard system:
+
+1. **`activeRuns` (in-memory Set)** — O(1) check if an agent is already running for an issue. Catches feedback loops where our own API calls (e.g., `createComment`, `createSessionOnIssue`) trigger webhooks back to us.
+
+2. **`wasRecentlyProcessed` (TTL Map, 60s)** — Catches exact-duplicate webhook deliveries. Each event type uses a specific dedup key:
+
+| Event | Dedup Key | Guards (in order) |
+|---|---|---|
+| `AgentSessionEvent.created` | `session:<sessionId>` | activeRuns → wasRecentlyProcessed |
+| `AgentSessionEvent.prompted` | `webhook:<webhookId>` | activeRuns → wasRecentlyProcessed |
+| `Comment.create` | `comment:<commentId>` | wasRecentlyProcessed → viewerId → activeRuns |
+| `Issue.update` | `<trigger>:<issueId>:<viewerId>` | activeRuns → no-change → viewerId → wasRecentlyProcessed |
+| `Issue.create` | `issue-create:<issueId>` | wasRecentlyProcessed → activeRuns → planning mode → bot-created |
+| `AppUserNotification` | *(immediate discard)* | — |
+
+**Comment echo prevention:** All comments posted by the handler use `createCommentWithDedup()`, which pre-registers the comment's ID in `wasRecentlyProcessed` immediately after the API returns. When Linear echoes the `Comment.create` webhook back, it's caught before any processing.
+
 ---
 
 ## Planning a Project
@@ -1026,6 +1045,13 @@ openclaw openclaw-linear notify test               # Test all targets
 openclaw openclaw-linear notify test --channel discord  # Test one channel
 openclaw openclaw-linear notify setup              # Interactive setup
 
+# Webhooks
+openclaw openclaw-linear webhooks status             # Show webhook config in Linear
+openclaw openclaw-linear webhooks setup              # Auto-provision workspace webhook
+openclaw openclaw-linear webhooks setup --dry-run    # Preview what would change
+openclaw openclaw-linear webhooks setup --url <url>  # Use custom webhook URL
+openclaw openclaw-linear webhooks delete <id>        # Delete a webhook by ID
+
 # Dispatch
 /dispatch list                                     # Active dispatches
 /dispatch status <identifier>                      # Dispatch details
@@ -1057,7 +1083,7 @@ journalctl --user -u openclaw-gateway -f         # Watch live logs
 | Agent goes silent | Watchdog auto-kills after `inactivitySec` and retries. Check logs for `Watchdog KILL`. |
 | Dispatch stuck after watchdog | Both retries failed. Check `.claw/log.jsonl`. Re-assign issue to restart. |
 | `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. |
-| Webhook events not arriving | Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
+| Webhook events not arriving | Run `openclaw openclaw-linear webhooks setup` to auto-provision. Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
 | OAuth token expired | Auto-refreshes. If stuck, re-run `openclaw openclaw-linear auth` and restart. |
 | Audit always fails | Run `openclaw openclaw-linear prompts validate` to check prompt syntax. |
 | Multi-repo not detected | Markers must be `<!-- repos: name1, name2 -->`. Names must match `repos` config keys. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/__test__/fixtures/webhook-payloads.ts

@@ -95,6 +95,99 @@ export function makeIssueCreate(overrides?: Record<string, unknown>) {
   };
 }
 
+/**
+ * AgentSessionEvent.created — the actual type from OAuth app webhooks.
+ * (makeAgentSessionCreated uses the legacy "AgentSession"/"create" variant.)
+ */
+export function makeAgentSessionEventCreated(overrides?: Record<string, unknown>) {
+  return {
+    type: "AgentSessionEvent",
+    action: "created",
+    agentSession: {
+      id: "sess-event-1",
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+      },
+    },
+    previousComments: [],
+    guidance: "Please investigate this issue",
+    ...overrides,
+  };
+}
+
+/**
+ * AgentSessionEvent.prompted — follow-up user message in existing session.
+ */
+export function makeAgentSessionEventPrompted(overrides?: Record<string, unknown>) {
+  return {
+    type: "AgentSessionEvent",
+    action: "prompted",
+    agentSession: {
+      id: "sess-event-1",
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+      },
+    },
+    agentActivity: { content: { body: "Follow-up question here" } },
+    webhookId: "webhook-prompted-1",
+    ...overrides,
+  };
+}
+
+/**
+ * Comment.create from the bot's own user (should be skipped by viewerId check).
+ */
+export function makeCommentCreateFromBot(viewerId: string, overrides?: Record<string, unknown>) {
+  return {
+    type: "Comment",
+    action: "create",
+    data: {
+      id: `comment-bot-${Date.now()}`,
+      body: "**[Mal]** Bot response text",
+      user: { id: viewerId, name: "CT Claw" },
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+        team: { id: "team-1" },
+        assignee: { id: viewerId },
+        project: null,
+      },
+      createdAt: new Date().toISOString(),
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Issue.update with assignment/delegation fields for dedup testing.
+ */
+export function makeIssueUpdateWithAssignment(overrides?: Record<string, unknown>) {
+  return {
+    type: "Issue",
+    action: "update",
+    data: {
+      id: "issue-1",
+      identifier: "ENG-123",
+      title: "Fix webhook routing",
+      state: { name: "In Progress", type: "started" },
+      assignee: { id: "viewer-1", name: "Agent" },
+      assigneeId: "viewer-1",
+      delegateId: null,
+      team: { id: "team-1" },
+      project: null,
+    },
+    updatedFrom: {
+      assigneeId: null,
+    },
+    ...overrides,
+  };
+}
+
 export function makeAppUserNotification(overrides?: Record<string, unknown>) {
   return {
     type: "AppUserNotification",

package/src/__test__/smoke-linear-api.test.ts

@@ -0,0 +1,352 @@
+/**
+ * smoke-linear-api.test.ts — Live integration tests against the real Linear API.
+ *
+ * These tests verify API connectivity, comment lifecycle, and dedup behavior
+ * using real API calls. Run separately from unit tests:
+ *
+ *   npx vitest run --config vitest.smoke.config.ts
+ *
+ * Requires: ~/.openclaw/auth-profiles.json with a valid linear:api-key profile.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { LinearAgentApi } from "../api/linear-api.js";
+
+// ── Setup ──────────────────────────────────────────────────────────
+
+const AUTH_PROFILES_PATH = join(
+  process.env.HOME ?? "/home/claw",
+  ".openclaw",
+  "auth-profiles.json",
+);
+
+const TEAM_ID = "08cba264-d774-4afd-bc93-ee8213d12ef8";
+
+function loadApiKey(): string {
+  const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+  const store = JSON.parse(raw);
+  const profile = store?.profiles?.["linear:api-key"];
+  const token = profile?.accessToken ?? profile?.access;
+  if (!token) throw new Error("No linear:api-key profile found in auth-profiles.json");
+  return token;
+}
+
+let api: LinearAgentApi;
+let smokeIssueId: string | null = null;
+const createdCommentIds: string[] = [];
+
+beforeAll(() => {
+  const token = loadApiKey();
+  api = new LinearAgentApi(token);
+});
+
+afterAll(async () => {
+  // Cleanup: we can't delete comments via API, but they're prefixed
+  // with [SMOKE TEST] for easy identification.
+  if (createdCommentIds.length > 0) {
+    console.log(
+      `Smoke test created ${createdCommentIds.length} comment(s) prefixed with [SMOKE TEST]. ` +
+      `Clean up manually if needed.`,
+    );
+  }
+});
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe("Linear API smoke tests", () => {
+  describe("connectivity", () => {
+    it("resolves viewer ID", async () => {
+      const viewerId = await api.getViewerId();
+      expect(viewerId).toBeTruthy();
+      expect(typeof viewerId).toBe("string");
+    });
+  });
+
+  describe("team discovery", () => {
+    it("lists teams", async () => {
+      const teams = await api.getTeams();
+      expect(teams.length).toBeGreaterThan(0);
+      expect(teams[0]).toHaveProperty("id");
+      expect(teams[0]).toHaveProperty("name");
+      expect(teams[0]).toHaveProperty("key");
+    });
+
+    it("finds our configured team", async () => {
+      const teams = await api.getTeams();
+      const ourTeam = teams.find((t) => t.id === TEAM_ID);
+      expect(ourTeam).toBeTruthy();
+    });
+
+    it("lists team labels", async () => {
+      const labels = await api.getTeamLabels(TEAM_ID);
+      expect(Array.isArray(labels)).toBe(true);
+      // Labels may or may not exist, but the call should succeed
+    });
+
+    it("lists team workflow states", async () => {
+      const states = await api.getTeamStates(TEAM_ID);
+      expect(states.length).toBeGreaterThan(0);
+      expect(states[0]).toHaveProperty("id");
+      expect(states[0]).toHaveProperty("name");
+      expect(states[0]).toHaveProperty("type");
+      // Should have at least backlog, started, completed types
+      const types = states.map((s) => s.type);
+      expect(types).toContain("backlog");
+    });
+  });
+
+  describe("issue operations", () => {
+    it("creates a smoke test issue", async () => {
+      const states = await api.getTeamStates(TEAM_ID);
+      const backlogState = states.find((s) => s.type === "backlog");
+      expect(backlogState).toBeTruthy();
+
+      const result = await api.createIssue({
+        teamId: TEAM_ID,
+        title: "[SMOKE TEST] Linear Plugin Integration Test",
+        description:
+          "Auto-generated by smoke tests. Safe to delete.\n\n" +
+          `Created: ${new Date().toISOString()}`,
+        stateId: backlogState!.id,
+        priority: 4, // Low
+      });
+
+      expect(result.id).toBeTruthy();
+      expect(result.identifier).toBeTruthy();
+      smokeIssueId = result.id;
+    });
+
+    it("reads issue details", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const issue = await api.getIssueDetails(smokeIssueId!);
+
+      expect(issue.id).toBe(smokeIssueId);
+      expect(issue.identifier).toBeTruthy();
+      expect(issue.title).toContain("[SMOKE TEST]");
+      expect(issue.state).toHaveProperty("name");
+      expect(issue.team).toHaveProperty("id");
+      expect(issue.team).toHaveProperty("name");
+      expect(issue.labels).toHaveProperty("nodes");
+      expect(issue.comments).toHaveProperty("nodes");
+    });
+
+    it("updates issue fields", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const success = await api.updateIssue(smokeIssueId!, {
+        estimate: 1,
+        priority: 4,
+      });
+      expect(success).toBe(true);
+
+      // Verify the update
+      const issue = await api.getIssueDetails(smokeIssueId!);
+      expect(issue.estimate).toBe(1);
+    });
+  });
+
+  describe("comment lifecycle", () => {
+    it("creates a comment", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const commentId = await api.createComment(
+        smokeIssueId!,
+        "[SMOKE TEST] Comment created by integration test.\n\n" +
+        `Timestamp: ${new Date().toISOString()}`,
+      );
+      expect(commentId).toBeTruthy();
+      expect(typeof commentId).toBe("string");
+      createdCommentIds.push(commentId);
+    });
+
+    it("comment appears in issue details", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      expect(createdCommentIds.length).toBeGreaterThan(0);
+
+      const issue = await api.getIssueDetails(smokeIssueId!);
+      const comments = issue.comments.nodes;
+      const found = comments.some((c) =>
+        c.body.includes("[SMOKE TEST] Comment created by integration test"),
+      );
+      expect(found).toBe(true);
+    });
+
+    it("creates an agent identity comment (requires OAuth — skipped with API key)", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      // createAsUser posts as a named OpenClaw agent (e.g. "Mal", "Kaylee")
+      // with their avatar. Requires OAuth actor=app mode — personal API keys
+      // can't use it, so comments fall back to a **[AgentName]** prefix.
+      try {
+        const commentId = await api.createComment(
+          smokeIssueId!,
+          "[SMOKE TEST] Agent identity comment test.",
+          {
+            createAsUser: "Smoke Test Bot",
+            displayIconUrl: "https://avatars.githubusercontent.com/u/1?v=4",
+          },
+        );
+        expect(commentId).toBeTruthy();
+        createdCommentIds.push(commentId);
+      } catch (err) {
+        const msg = String(err);
+        if (msg.includes("createAsUser") || msg.includes("actor=app")) {
+          // Expected with API key — agent identity comments require OAuth
+          expect(true).toBe(true);
+        } else {
+          throw err; // Unexpected error
+        }
+      }
+    });
+  });
+
+  describe("issue state transitions", () => {
+    let teamStates: Array<{ id: string; name: string; type: string }>;
+
+    it("fetches team workflow states for transition tests", async () => {
+      teamStates = await api.getTeamStates(TEAM_ID);
+      expect(teamStates.length).toBeGreaterThan(0);
+    });
+
+    it("transitions issue from backlog to started", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const startedState = teamStates.find((s) => s.type === "started");
+      expect(startedState).toBeTruthy();
+
+      const success = await api.updateIssue(smokeIssueId!, { stateId: startedState!.id });
+      expect(success).toBe(true);
+
+      const issue = await api.getIssueDetails(smokeIssueId!);
+      expect(issue.state.type).toBe("started");
+    });
+
+    it("transitions issue from started to completed", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const completedState = teamStates.find((s) => s.type === "completed");
+      expect(completedState).toBeTruthy();
+
+      const success = await api.updateIssue(smokeIssueId!, { stateId: completedState!.id });
+      expect(success).toBe(true);
+
+      const issue = await api.getIssueDetails(smokeIssueId!);
+      expect(issue.state.type).toBe("completed");
+    });
+
+    it("transitions issue from completed to canceled", async () => {
+      expect(smokeIssueId).toBeTruthy();
+      const canceledState = teamStates.find(
+        (s) => s.type === "canceled" || s.name.toLowerCase().includes("cancel"),
+      );
+      expect(canceledState).toBeTruthy();
+
+      const success = await api.updateIssue(smokeIssueId!, { stateId: canceledState!.id });
+      expect(success).toBe(true);
+
+      const issue = await api.getIssueDetails(smokeIssueId!);
+      expect(issue.state.type).toBe("canceled");
+    });
+  });
+
+  describe("@mention pattern matching", () => {
+    it("buildMentionPattern matches configured aliases", async () => {
+      // Test the pattern logic without needing agent-profiles.json.
+      // Note: use match() not test() — test() with `g` flag is stateful.
+      const aliases = ["mal", "kaylee", "inara", "zoe"];
+      const escaped = aliases.map((a) =>
+        a.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+      );
+      const pattern = new RegExp(`@(${escaped.join("|")})`, "gi");
+
+      expect("@mal please fix this".match(pattern)).toBeTruthy();
+      expect("Hey @kaylee can you look at this?".match(pattern)).toBeTruthy();
+      expect("@Inara write a blog post".match(pattern)).toBeTruthy();
+      expect("No mention here".match(pattern)).toBeNull();
+      expect("email@mal.com".match(pattern)).toBeTruthy(); // Known edge case
+    });
+  });
+
+  describe("dedup dry run", () => {
+    it("wasRecentlyProcessed returns false first, true second", async () => {
+      // Import the dedup function
+      const { _resetForTesting } = await import(
+        "../pipeline/webhook.js"
+      );
+      _resetForTesting();
+
+      // The wasRecentlyProcessed function is not exported directly,
+      // but we can test it indirectly through the webhook handler.
+      // For a pure unit test of the dedup function, see webhook-dedup.test.ts.
+      // Here we just verify the reset works.
+      expect(typeof _resetForTesting).toBe("function");
+    });
+  });
+
+  describe("webhook management", () => {
+    it("lists webhooks", async () => {
+      const webhooks = await api.listWebhooks();
+      expect(Array.isArray(webhooks)).toBe(true);
+      // Should have at least the shape we expect
+      if (webhooks.length > 0) {
+        expect(webhooks[0]).toHaveProperty("id");
+        expect(webhooks[0]).toHaveProperty("url");
+        expect(webhooks[0]).toHaveProperty("enabled");
+        expect(webhooks[0]).toHaveProperty("resourceTypes");
+      }
+    });
+
+    it("getWebhookStatus reports issues on misconfigured webhook", async () => {
+      const { getWebhookStatus } = await import("../../src/infra/webhook-provision.js");
+      // Use a URL that won't match any real webhook — should return null
+      const status = await getWebhookStatus(api, "https://nonexistent.example.com/webhook");
+      expect(status).toBeNull();
+    });
+
+    it("getWebhookStatus finds our webhook if configured", async () => {
+      const { getWebhookStatus } = await import("../../src/infra/webhook-provision.js");
+      const status = await getWebhookStatus(
+        api,
+        "https://linear.calltelemetry.com/linear/webhook",
+      );
+      // May or may not exist — just check the function works
+      if (status) {
+        expect(status.id).toBeTruthy();
+        expect(status.url).toBe("https://linear.calltelemetry.com/linear/webhook");
+        expect(Array.isArray(status.issues)).toBe(true);
+      }
+    });
+
+    it("provisionWebhook returns already_ok when correctly configured", async () => {
+      const { provisionWebhook, getWebhookStatus } = await import("../../src/infra/webhook-provision.js");
+      const status = await getWebhookStatus(
+        api,
+        "https://linear.calltelemetry.com/linear/webhook",
+      );
+      // Only run if our webhook exists and is correctly configured
+      if (status && status.issues.length === 0) {
+        const result = await provisionWebhook(
+          api,
+          "https://linear.calltelemetry.com/linear/webhook",
+        );
+        expect(result.action).toBe("already_ok");
+        expect(result.webhookId).toBe(status.id);
+      }
+    });
+  });
+
+  describe("cleanup", () => {
+    it("cancels the smoke test issue", async () => {
+      if (!smokeIssueId) return;
+
+      // Move to cancelled state if available, otherwise just leave it
+      try {
+        const states = await api.getTeamStates(TEAM_ID);
+        const cancelledState = states.find(
+          (s) => s.type === "cancelled" || s.name.toLowerCase().includes("cancel"),
+        );
+        if (cancelledState) {
+          await api.updateIssue(smokeIssueId, { stateId: cancelledState.id });
+        }
+      } catch {
+        // Best effort cleanup
+      }
+    });
+  });
+});