@calltelemetry/openclaw-linear 0.9.6 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "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/recorded-sub-issue-flow.ts

@@ -2,7 +2,7 @@
  * Recorded API responses from sub-issue decomposition smoke test.
  * Auto-generated — do not edit manually.
  * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts
- * Last recorded: 2026-02-22T01:35:48.289Z
+ * Last recorded: 2026-02-22T02:01:43.760Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-    "identifier": "UAT-235"
+    "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+    "identifier": "UAT-265"
   },
   "createSubIssue1": {
-    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
-    "identifier": "UAT-236"
+    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
+    "identifier": "UAT-266"
   },
   "createSubIssue2": {
-    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
-    "identifier": "UAT-237"
+    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
+    "identifier": "UAT-267"
   },
   "subIssue1Details": {
-    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
-    "identifier": "UAT-236",
+    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
+    "identifier": "UAT-266",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -83,16 +83,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-      "identifier": "UAT-235"
+      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+      "identifier": "UAT-265"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
-    "identifier": "UAT-237",
+    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
+    "identifier": "UAT-267",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -118,18 +118,18 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-      "identifier": "UAT-235"
+      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+      "identifier": "UAT-265"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-    "identifier": "UAT-235",
+    "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+    "identifier": "UAT-265",
     "title": "[SMOKE TEST] Sub-Issue Parent: Search Feature",
-    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T01:35:46.183Z",
+    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T02:01:42.469Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -149,13 +149,7 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T01:35:47.210Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": null,
@@ -164,11 +158,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "f2b33a57-b79a-4dcc-b973-a5453676a78f"
+    "id": "4c97b0aa-563e-4aad-84aa-826078f012fd"
   },
   "subIssue1WithRelation": {
-    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
-    "identifier": "UAT-236",
+    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
+    "identifier": "UAT-266",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -190,26 +184,20 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T01:35:47.302Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": {
-      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-      "identifier": "UAT-235"
+      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+      "identifier": "UAT-265"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
-            "identifier": "UAT-237",
+            "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
+            "identifier": "UAT-267",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -217,8 +205,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
-    "identifier": "UAT-237",
+    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
+    "identifier": "UAT-267",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -240,12 +228,18 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T02:01:43.418Z"
+        }
+      ]
     },
     "project": null,
     "parent": {
-      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
-      "identifier": "UAT-235"
+      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
+      "identifier": "UAT-265"
     },
     "relations": {
       "nodes": []

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

@@ -441,7 +441,7 @@ describe("Linear API smoke tests", () => {
       }
 
       expect(issue.id).toBe(sessionIssueId);
-    });
+    }, 20_000);
 
     it("Path B: createSessionOnIssue via OAuth (programmatic)", async () => {
       expect(sessionIssueId).toBeTruthy();

package/src/__test__/webhook-scenarios.test.ts

@@ -152,6 +152,11 @@ vi.mock("../pipeline/dag-dispatch.js", () => ({
   startProjectDispatch: vi.fn().mockResolvedValue(undefined),
 }));
 
+vi.mock("../infra/shared-profiles.js", async (importOriginal) => {
+  const actual = await importOriginal() as Record<string, unknown>;
+  return { ...actual, validateProfiles: vi.fn().mockReturnValue(null) };
+});
+
 // ── Imports (after mocks) ────────────────────────────────────────
 
 import { handleLinearWebhook, _resetForTesting } from "../pipeline/webhook.js";

package/src/infra/shared-profiles.ts

@@ -5,7 +5,7 @@
  * resolveAgentFromAlias() implementations that were previously in
  * webhook.ts, intent-classify.ts, and tier-assess.ts.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
@@ -107,6 +107,64 @@ export function resolveDefaultAgent(api: { pluginConfig?: Record<string, unknown
   return "default";
 }
 
+// ---------------------------------------------------------------------------
+// Profile validation — returns a user-facing error string or null if OK.
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that agent-profiles.json exists, is parseable, and has at least
+ * one agent.  Returns a human-readable error string suitable for posting
+ * back to Linear, or null when everything looks good.
+ */
+export function validateProfiles(): string | null {
+  if (!existsSync(PROFILES_PATH)) {
+    return (
+      `**Critical setup error:** \`agent-profiles.json\` not found.\n\n` +
+      `The Linear plugin requires this file to route messages to your agent.\n\n` +
+      `**Create it now:**\n` +
+      "```\n" +
+      `cat > ${PROFILES_PATH} << 'EOF'\n` +
+      `{\n` +
+      `  "agents": {\n` +
+      `    "my-agent": {\n` +
+      `      "label": "My Agent",\n` +
+      `      "mission": "AI assistant",\n` +
+      `      "isDefault": true,\n` +
+      `      "mentionAliases": ["my-agent"]\n` +
+      `    }\n` +
+      `  }\n` +
+      `}\n` +
+      `EOF\n` +
+      "```\n\n" +
+      `Then restart the gateway: \`systemctl --user restart openclaw-gateway\`\n\n` +
+      `Run \`openclaw openclaw-linear doctor\` to verify your setup.`
+    );
+  }
+
+  let profiles: Record<string, unknown>;
+  try {
+    const raw = readFileSync(PROFILES_PATH, "utf8");
+    profiles = JSON.parse(raw).agents ?? {};
+  } catch (err) {
+    return (
+      `**Critical setup error:** \`agent-profiles.json\` exists but could not be parsed.\n\n` +
+      `Error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+      `Fix the JSON syntax in \`${PROFILES_PATH}\` and restart the gateway.\n` +
+      `Run \`openclaw openclaw-linear doctor\` to verify.`
+    );
+  }
+
+  if (Object.keys(profiles).length === 0) {
+    return (
+      `**Critical setup error:** \`agent-profiles.json\` has no agents configured.\n\n` +
+      `Add at least one agent entry to the \`"agents"\` object in \`${PROFILES_PATH}\`.\n` +
+      `Run \`openclaw openclaw-linear doctor\` for a guided setup check.`
+    );
+  }
+
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Test-only: reset cache
 // ---------------------------------------------------------------------------

package/src/pipeline/webhook.test.ts

@@ -14,6 +14,7 @@ const {
   loadAgentProfilesMock,
   buildMentionPatternMock,
   resolveAgentFromAliasMock,
+  validateProfilesMock,
   resetProfilesCacheMock,
   classifyIntentMock,
   extractGuidanceMock,
@@ -86,6 +87,7 @@ const {
   }),
   buildMentionPatternMock: vi.fn().mockReturnValue(/@(mal|mason|kaylee|eureka)/i),
   resolveAgentFromAliasMock: vi.fn().mockReturnValue(null),
+  validateProfilesMock: vi.fn().mockReturnValue(null),
   resetProfilesCacheMock: vi.fn(),
   classifyIntentMock: vi.fn().mockResolvedValue({
     intent: "general",
@@ -154,6 +156,7 @@ vi.mock("../infra/shared-profiles.js", () => ({
   loadAgentProfiles: loadAgentProfilesMock,
   buildMentionPattern: buildMentionPatternMock,
   resolveAgentFromAlias: resolveAgentFromAliasMock,
+  validateProfiles: validateProfilesMock,
   _resetProfilesCacheForTesting: resetProfilesCacheMock,
 }));
 
@@ -352,6 +355,7 @@ afterEach(() => {
   });
   buildMentionPatternMock.mockReset().mockReturnValue(/@(mal|mason|kaylee|eureka)/i);
   resolveAgentFromAliasMock.mockReset().mockReturnValue(null);
+  validateProfilesMock.mockReset().mockReturnValue(null);
   classifyIntentMock.mockReset().mockResolvedValue({
     intent: "general",
     reasoning: "Not actionable",

package/src/pipeline/webhook.ts

@@ -17,7 +17,7 @@ import { startProjectDispatch } from "./dag-dispatch.js";
 import { emitDiagnostic } from "../infra/observability.js";
 import { classifyIntent } from "./intent-classify.js";
 import { extractGuidance, formatGuidanceAppendix, cacheGuidanceForTeam, getCachedGuidanceForTeam, isGuidanceEnabled, _resetGuidanceCacheForTesting } from "./guidance.js";
-import { loadAgentProfiles, buildMentionPattern, resolveAgentFromAlias, _resetProfilesCacheForTesting, type AgentProfile } from "../infra/shared-profiles.js";
+import { loadAgentProfiles, buildMentionPattern, resolveAgentFromAlias, validateProfiles, _resetProfilesCacheForTesting, type AgentProfile } from "../infra/shared-profiles.js";
 
 // ── Prompt input sanitization ─────────────────────────────────────
 
@@ -322,6 +322,21 @@ export async function handleLinearWebhook(
       return true;
     }
 
+    // Validate agent profiles before doing any work
+    const profilesError = validateProfiles();
+    if (profilesError) {
+      api.logger.error("Agent profiles validation failed — posting setup error to Linear");
+      await linearApi.emitActivity(session.id, {
+        type: "error",
+        body: profilesError,
+      }).catch(() => {});
+      // Also try posting as a comment in case emitActivity doesn't render markdown
+      try {
+        await createCommentWithDedup(linearApi, issue.id, profilesError);
+      } catch {}
+      return true;
+    }
+
     const previousComments = payload.previousComments ?? [];
     const guidanceCtx = extractGuidance(payload);
 
@@ -331,21 +346,54 @@ export async function handleLinearWebhook(
       : null;
     const userMessage = lastComment?.body ?? "";
 
+    // Also extract the session prompt from promptContext — on initial session
+    // creation, previousComments is empty but the user's message lives here.
+    const promptContext = typeof payload.promptContext === "string" ? payload.promptContext : "";
+
     // Route to the mentioned agent if the user's message contains an @mention.
     // AgentSessionEvent doesn't carry mention routing — we must check manually.
+    // Check the last comment body, promptContext, AND agentSession prompt for @mentions.
     const profiles = loadAgentProfiles();
     const mentionPattern = buildMentionPattern(profiles);
     let agentId = resolveAgentId(api);
     let mentionOverride = false;
-    if (mentionPattern && userMessage) {
-      const mentionMatch = userMessage.match(mentionPattern);
-      if (mentionMatch) {
-        const alias = mentionMatch[1];
-        const resolved = resolveAgentFromAlias(alias, profiles);
-        if (resolved) {
-          api.logger.info(`AgentSession routed to ${resolved.agentId} via @${alias} mention`);
-          agentId = resolved.agentId;
-          mentionOverride = true;
+    const sessionPrompt = typeof (payload.agentSession as any)?.prompt === "string"
+      ? (payload.agentSession as any).prompt : "";
+    const textsToScan = [userMessage, sessionPrompt, promptContext].filter(Boolean);
+    for (const text of textsToScan) {
+      if (mentionOverride) break;
+      if (mentionPattern) {
+        mentionPattern.lastIndex = 0;
+        const mentionMatch = text.match(mentionPattern);
+        if (mentionMatch) {
+          const alias = mentionMatch[1];
+          const resolved = resolveAgentFromAlias(alias, profiles);
+          if (resolved) {
+            api.logger.info(`AgentSession routed to ${resolved.agentId} via @${alias} mention in ${text === userMessage ? "comment" : text === sessionPrompt ? "session prompt" : "promptContext"}`);
+            agentId = resolved.agentId;
+            mentionOverride = true;
+          }
+        }
+      }
+    }
+    // Also try bare-name matching (e.g. "hey mal" without @) in the user's text
+    if (!mentionOverride) {
+      for (const text of textsToScan) {
+        if (mentionOverride) break;
+        const lowerText = text.toLowerCase();
+        for (const [id, profile] of Object.entries(profiles)) {
+          const allNames = [...profile.mentionAliases, ...(profile.appAliases ?? [])];
+          for (const name of allNames) {
+            // Match bare name at word boundary (e.g. "hey mal" but not "malware")
+            const nameRe = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+            if (nameRe.test(lowerText)) {
+              api.logger.info(`AgentSession routed to ${id} via bare name "${name}" in ${text === userMessage ? "comment" : text === sessionPrompt ? "session prompt" : "promptContext"}`);
+              agentId = id;
+              mentionOverride = true;
+              break;
+            }
+          }
+          if (mentionOverride) break;
         }
       }
     }
@@ -553,6 +601,17 @@ export async function handleLinearWebhook(
       return true;
     }
 
+    // Validate agent profiles before doing any work
+    const profilesError = validateProfiles();
+    if (profilesError) {
+      api.logger.error("Agent profiles validation failed — posting setup error to Linear");
+      await linearApi.emitActivity(session.id, {
+        type: "error",
+        body: profilesError,
+      }).catch(() => {});
+      return true;
+    }
+
     // Route to mentioned agent if user's message contains an @mention (one-time detour)
     const promptedProfiles = loadAgentProfiles();
     const promptedMentionPattern = buildMentionPattern(promptedProfiles);
@@ -764,6 +823,16 @@ export async function handleLinearWebhook(
       return true;
     }
 
+    // Validate agent profiles before doing any work
+    const profilesError = validateProfiles();
+    if (profilesError) {
+      api.logger.error("Agent profiles validation failed — posting setup error to Linear");
+      try {
+        await createCommentWithDedup(linearApi, issue.id, profilesError);
+      } catch {}
+      return true;
+    }
+
     // Load agent profiles
     const profiles = loadAgentProfiles();
     const agentNames = Object.keys(profiles);
@@ -1050,6 +1119,16 @@ export async function handleLinearWebhook(
       return true;
     }
 
+    // Validate agent profiles
+    const profilesError = validateProfiles();
+    if (profilesError) {
+      api.logger.error("Agent profiles validation failed — cannot triage new issue");
+      try {
+        await createCommentWithDedup(linearApi, issue.id, profilesError);
+      } catch {}
+      return true;
+    }
+
     const agentId = resolveAgentId(api);
 
     // Guard: prevent duplicate runs on same issue (also blocks AgentSessionEvent