@calltelemetry/openclaw-linear 0.9.20 → 0.9.22

package/README.md

@@ -134,6 +134,14 @@ The end result: you work in Linear. You create issues, assign them, comment in p
 
 ## Quick Start
 
+> **Tip:** Claude Code is very good at setting this up for you. Install the plugin, install the [Cloudflare CLI](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/#1-download-and-install-cloudflared) and authenticate (`cloudflared tunnel login`), then just ask Claude to configure the rest. Or run the guided setup wizard:
+>
+> ```bash
+> openclaw openclaw-linear setup
+> ```
+>
+> It walks through agent profiles, auth, webhook provisioning, and verification in one interactive flow.
+
 ### 1. Install the plugin
 
 ```bash
@@ -1451,9 +1459,11 @@ The `request_work` intent is the only one gated by issue state. When the issue i
 
 ### Hook Lifecycle
 
-The plugin registers four lifecycle hooks via `api.on()` in `index.ts`:
+The plugin registers completion + lifecycle hooks via `api.on()` in `index.ts`.
+For completion events it listens to `agent_end`, `task_completed`, and `task_completion`
+to stay compatible across OpenClaw lifecycle event changes.
 
-**`agent_end`** — Dispatch pipeline state machine. When a sub-agent (worker or auditor) finishes:
+**Completion hooks (`agent_end` / `task_completed` / `task_completion`)** — Dispatch pipeline state machine. When a sub-agent (worker or auditor) finishes:
 - Looks up the session key in dispatch state to find the active dispatch
 - Validates the attempt number matches (rejects stale events from old retries)
 - If the worker finished → triggers the audit phase (`triggerAudit`)

package/index.ts

@@ -20,6 +20,51 @@ import { createDispatchHistoryTool } from "./src/tools/dispatch-history-tool.js"
 import { readDispatchState as readStateForHook, listActiveDispatches as listActiveForHook } from "./src/pipeline/dispatch-state.js";
 import { startTokenRefreshTimer, stopTokenRefreshTimer } from "./src/infra/token-refresh-timer.js";
 
+const COMPLETION_HOOK_NAMES = ["agent_end", "task_completed", "task_completion"] as const;
+const SUCCESS_STATUSES = new Set(["ok", "success", "completed", "complete", "done", "pass", "passed"]);
+const FAILURE_STATUSES = new Set(["error", "failed", "failure", "timeout", "timed_out", "cancelled", "canceled", "aborted", "unknown"]);
+
+function parseCompletionSuccess(event: any): boolean {
+  if (typeof event?.success === "boolean") {
+    return event.success;
+  }
+  const status = typeof event?.status === "string" ? event.status.trim().toLowerCase() : "";
+  if (status) {
+    if (SUCCESS_STATUSES.has(status)) return true;
+    if (FAILURE_STATUSES.has(status)) return false;
+  }
+  if (typeof event?.error === "string" && event.error.trim().length > 0) {
+    return false;
+  }
+  return true;
+}
+
+function extractCompletionOutput(event: any): string {
+  if (typeof event?.output === "string" && event.output.trim().length > 0) {
+    return event.output;
+  }
+  if (typeof event?.result === "string" && event.result.trim().length > 0) {
+    return event.result;
+  }
+
+  const assistantBlocks = (event?.messages ?? [])
+    .filter((m: any) => m?.role === "assistant")
+    .flatMap((m: any) => {
+      if (typeof m?.content === "string") {
+        return [m.content];
+      }
+      if (Array.isArray(m?.content)) {
+        return m.content
+          .filter((b: any) => b?.type === "text" && typeof b?.text === "string")
+          .map((b: any) => b.text);
+      }
+      return [];
+    })
+    .filter((value: string) => value.trim().length > 0);
+
+  return assistantBlocks.join("\n");
+}
+
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
 
@@ -57,6 +102,8 @@ export default function register(api: OpenClawPluginApi) {
   // Register Linear webhook handler on a dedicated route
   api.registerHttpRoute({
     path: "/linear/webhook",
+    auth: "plugin",
+    match: "exact",
     handler: async (req, res) => {
       await handleLinearWebhook(api, req, res);
     },
@@ -65,6 +112,8 @@ export default function register(api: OpenClawPluginApi) {
   // Back-compat route so existing production webhook URLs keep working.
   api.registerHttpRoute({
     path: "/hooks/linear",
+    auth: "plugin",
+    match: "exact",
     handler: async (req, res) => {
       await handleLinearWebhook(api, req, res);
     },
@@ -73,6 +122,8 @@ export default function register(api: OpenClawPluginApi) {
   // Register OAuth callback route
   api.registerHttpRoute({
     path: "/linear/oauth/callback",
+    auth: "plugin",
+    match: "exact",
     handler: async (req, res) => {
       await handleOAuthCallback(api, req, res);
     },
@@ -95,17 +146,19 @@ export default function register(api: OpenClawPluginApi) {
   }).catch((err) => api.logger.warn(`Planning state hydration failed: ${err}`));
 
   // ---------------------------------------------------------------------------
-  // Dispatch pipeline v2: notifier + agent_end lifecycle hook
+  // Dispatch pipeline v2: notifier + completion lifecycle hooks
   // ---------------------------------------------------------------------------
 
   // Instantiate notifier (Discord, Slack, or both — config-driven)
   const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime, api);
 
-  // Register agent_end hook — safety net for sessions_spawn sub-agents.
-  // In the current implementation, the worker→audit→verdict flow runs inline
-  // via spawnWorker() in pipeline.ts. This hook catches sessions_spawn agents
-  // (future upgrade path) and serves as a recovery mechanism.
-  api.on("agent_end", async (event: any, ctx: any) => {
+  // Register completion hooks — safety net for sessions_spawn sub-agents.
+  // In the current implementation, the worker->audit->verdict flow runs inline
+  // via spawnWorker() in pipeline.ts. These hooks catch sessions_spawn agents
+  // (future upgrade path) and serve as a recovery mechanism.
+  const onAnyHook = api.on as unknown as (hookName: string, handler: (event: any, ctx: any) => Promise<void> | void) => void;
+
+  const handleCompletionEvent = async (event: any, ctx: any, hookName: string) => {
     try {
       const sessionKey = ctx?.sessionKey ?? "";
       if (!sessionKey) return;
@@ -117,14 +170,14 @@ export default function register(api: OpenClawPluginApi) {
 
       const dispatch = getActiveDispatch(state, mapping.dispatchId);
       if (!dispatch) {
-        api.logger.info(`agent_end: dispatch ${mapping.dispatchId} no longer active`);
+        api.logger.info(`${hookName}: dispatch ${mapping.dispatchId} no longer active`);
         return;
       }
 
       // Stale event rejection — only process if attempt matches
       if (dispatch.attempt !== mapping.attempt) {
         api.logger.info(
-          `agent_end: stale event for ${mapping.dispatchId} ` +
+          `${hookName}: stale event for ${mapping.dispatchId} ` +
           `(event attempt=${mapping.attempt}, current=${dispatch.attempt})`
         );
         return;
@@ -133,7 +186,7 @@ export default function register(api: OpenClawPluginApi) {
       // Create Linear API for hook context
       const tokenInfo = resolveLinearToken(pluginConfig);
       if (!tokenInfo.accessToken) {
-        api.logger.error("agent_end: no Linear access token — cannot process dispatch event");
+        api.logger.error(`${hookName}: no Linear access token — cannot process dispatch event`);
         return;
       }
       const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
@@ -149,29 +202,24 @@ export default function register(api: OpenClawPluginApi) {
         configPath: statePath,
       };
 
-      // Extract output from event
-      const output = typeof event?.output === "string"
-        ? event.output
-        : (event?.messages ?? [])
-            .filter((m: any) => m?.role === "assistant")
-            .map((m: any) => typeof m?.content === "string" ? m.content : "")
-            .join("\n") || "";
+      const output = extractCompletionOutput(event);
+      const success = parseCompletionSuccess(event);
 
       if (mapping.phase === "worker") {
-        api.logger.info(`agent_end: worker completed for ${mapping.dispatchId} — triggering audit`);
+        api.logger.info(`${hookName}: worker completed for ${mapping.dispatchId} - triggering audit`);
         await triggerAudit(hookCtx, dispatch, {
-          success: event?.success ?? true,
+          success,
           output,
         }, sessionKey);
       } else if (mapping.phase === "audit") {
-        api.logger.info(`agent_end: audit completed for ${mapping.dispatchId} — processing verdict`);
+        api.logger.info(`${hookName}: audit completed for ${mapping.dispatchId} - processing verdict`);
         await processVerdict(hookCtx, dispatch, {
-          success: event?.success ?? true,
+          success,
           output,
         }, sessionKey);
       }
     } catch (err) {
-      api.logger.error(`agent_end hook error: ${err}`);
+      api.logger.error(`${hookName} hook error: ${err}`);
       // Escalate: mark dispatch as stuck so it's visible
       try {
         const statePath = pluginConfig?.dispatchStatePath as string | undefined;
@@ -199,10 +247,15 @@ export default function register(api: OpenClawPluginApi) {
           }
         }
       } catch (escalateErr) {
-        api.logger.error(`agent_end escalation also failed: ${escalateErr}`);
+        api.logger.error(`${hookName} escalation also failed: ${escalateErr}`);
       }
     }
-  });
+  };
+
+  for (const hookName of COMPLETION_HOOK_NAMES) {
+    onAnyHook(hookName, (event: any, ctx: any) => handleCompletionEvent(event, ctx, hookName));
+  }
+  api.logger.info(`Dispatch completion hooks registered: ${COMPLETION_HOOK_NAMES.join(", ")}`);
 
   // Inject recent dispatch history as context for worker/audit agents
   api.on("before_agent_start", async (event: any, ctx: any) => {

package/package.json

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

package/src/infra/tmux-runner.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { isCompletionEvent } from "./tmux-runner.js";
+
+describe("isCompletionEvent", () => {
+  it("detects Claude result events", () => {
+    expect(isCompletionEvent({ type: "result" })).toBe(true);
+  });
+
+  it("detects Codex session completion events", () => {
+    expect(isCompletionEvent({ type: "session.completed" })).toBe(true);
+  });
+
+  it("detects task completion lifecycle variants", () => {
+    expect(isCompletionEvent({ type: "task_completed" })).toBe(true);
+    expect(isCompletionEvent({ type: "task.completed" })).toBe(true);
+    expect(isCompletionEvent({ type: "task_completion" })).toBe(true);
+  });
+
+  it("detects completion when event type is under item.type", () => {
+    expect(isCompletionEvent({ item: { type: "task_completed" } })).toBe(true);
+  });
+
+  it("detects completion from session.completed boolean", () => {
+    expect(isCompletionEvent({ session: { completed: true } })).toBe(true);
+  });
+
+  it("does not treat non-completion events as complete", () => {
+    expect(isCompletionEvent({ type: "assistant" })).toBe(false);
+    expect(isCompletionEvent({ type: "message" })).toBe(false);
+    expect(isCompletionEvent({ item: { type: "agent_message" } })).toBe(false);
+  });
+});

package/src/infra/tmux-runner.ts

@@ -8,6 +8,14 @@ import { formatActivityLogLine, createProgressEmitter } from "../tools/cli-share
 import { InactivityWatchdog } from "../agent/watchdog.js";
 import { shellEscape } from "./tmux.js";
 
+const COMPLETION_EVENT_TYPES = new Set([
+  "result",
+  "session.completed",
+  "task_completed",
+  "task.completed",
+  "task_completion",
+]);
+
 export interface TmuxSession {
   sessionName: string;
   backend: string;
@@ -25,7 +33,7 @@ export interface RunInTmuxOptions {
   timeoutMs: number;
   watchdogMs: number;
   logPath: string;
-  mapEvent: (event: any) => ActivityContent | null;
+  mapEvent: (event: any) => ActivityContent[];
   linearApi?: LinearAgentApi;
   agentSessionId?: string;
   steeringMode: "stdin-pipe" | "one-shot";
@@ -37,6 +45,24 @@ export interface RunInTmuxOptions {
 // Track active tmux sessions by issueId
 const activeSessions = new Map<string, TmuxSession>();
 
+/**
+ * Completion detector for streamed CLI JSONL events.
+ * Supports Claude and Codex event variants across releases.
+ */
+export function isCompletionEvent(event: any): boolean {
+  const type = typeof event?.type === "string" ? event.type.trim().toLowerCase() : "";
+  if (type && COMPLETION_EVENT_TYPES.has(type)) {
+    return true;
+  }
+
+  const itemType = typeof event?.item?.type === "string" ? event.item.type.trim().toLowerCase() : "";
+  if (itemType && COMPLETION_EVENT_TYPES.has(itemType)) {
+    return true;
+  }
+
+  return event?.session?.completed === true;
+}
+
 /**
  * Get the active tmux session for a given issueId, or null if none.
  */
@@ -221,8 +247,8 @@ export async function runInTmux(opts: RunInTmuxOptions): Promise<CliResult> {
         }
 
         // Stream to Linear
-        const activity = mapEvent(event);
-        if (activity) {
+        const activities = mapEvent(event);
+        for (const activity of activities) {
           if (linearApi && agentSessionId) {
             linearApi.emitActivity(agentSessionId, activity).catch((err) => {
               logger.warn(`Failed to emit tmux activity: ${err}`);
@@ -231,8 +257,8 @@ export async function runInTmux(opts: RunInTmuxOptions): Promise<CliResult> {
           progress.push(formatActivityLogLine(activity));
         }
 
-        // Detect completion — Claude uses "result", Codex uses "session.completed"
-        if (event.type === "result" || event.type === "session.completed") {
+        // Detect completion across known CLI event shapes.
+        if (isCompletionEvent(event)) {
           completionEventReceived = true;
           cleanup("done");
           rl.close();

package/src/tools/claude-tool.ts

@@ -26,17 +26,18 @@ const CLAUDE_BIN = "claude";
  * Claude event types:
  *   system(init) → assistant (text|tool_use) → user (tool_result) → result
  */
-function mapClaudeEventToActivity(event: any): ActivityContent | null {
+function mapClaudeEventToActivity(event: any): ActivityContent[] {
   const type = event?.type;
 
-  // Assistant message — text response or tool use
+  // Assistant message — text response and/or tool use (emit all blocks)
   if (type === "assistant") {
     const content = event.message?.content;
-    if (!Array.isArray(content)) return null;
+    if (!Array.isArray(content)) return [];
 
+    const activities: ActivityContent[] = [];
     for (const block of content) {
       if (block.type === "text" && block.text) {
-        return { type: "thought", body: block.text.slice(0, 1000) };
+        activities.push({ type: "thought", body: block.text.slice(0, 1000) });
       }
       if (block.type === "tool_use") {
         const toolName = block.name ?? "tool";
@@ -54,30 +55,31 @@ function mapClaudeEventToActivity(event: any): ActivityContent | null {
         } else {
           paramSummary = JSON.stringify(input).slice(0, 500);
         }
-        return { type: "action", action: `Running ${toolName}`, parameter: paramSummary };
+        activities.push({ type: "action", action: `Running ${toolName}`, parameter: paramSummary });
       }
     }
-    return null;
+    return activities;
   }
 
   // Tool result
   if (type === "user") {
     const content = event.message?.content;
-    if (!Array.isArray(content)) return null;
+    if (!Array.isArray(content)) return [];
 
+    const activities: ActivityContent[] = [];
     for (const block of content) {
       if (block.type === "tool_result") {
         const output = typeof block.content === "string" ? block.content : "";
         const truncated = output.length > 1000 ? output.slice(0, 1000) + "..." : output;
         const isError = block.is_error === true;
-        return {
+        activities.push({
           type: "action",
           action: isError ? "Tool error" : "Tool result",
           parameter: truncated || "(no output)",
-        };
+        });
       }
     }
-    return null;
+    return activities;
   }
 
   // Final result
@@ -92,10 +94,10 @@ function mapClaudeEventToActivity(event: any): ActivityContent | null {
       const output = usage.output_tokens ?? 0;
       parts.push(`${input} in / ${output} out tokens`);
     }
-    return { type: "thought", body: parts.join(" — ") };
+    return [{ type: "thought", body: parts.join(" — ") }];
   }
 
-  return null;
+  return [];
 }
 
 /**
@@ -299,9 +301,9 @@ export async function runClaude(
         // (it duplicates the last assistant text message)
       }
 
-      // Stream activity to Linear + session progress
-      const activity = mapClaudeEventToActivity(event);
-      if (activity) {
+      // Stream activities to Linear + session progress
+      const activities = mapClaudeEventToActivity(event);
+      for (const activity of activities) {
         if (linearApi && agentSessionId) {
           linearApi.emitActivity(agentSessionId, activity).catch((err) => {
             api.logger.warn(`Failed to emit Claude activity: ${err}`);

package/src/tools/codex-tool.ts

@@ -23,13 +23,13 @@ const CODEX_BIN = "codex";
 /**
  * Parse a JSONL line from `codex exec --json` and map it to a Linear activity.
  */
-function mapCodexEventToActivity(event: any): ActivityContent | null {
+function mapCodexEventToActivity(event: any): ActivityContent[] {
   const eventType = event?.type;
   const item = event?.item;
 
   if (item?.type === "reasoning") {
     const text = item.text ?? "";
-    return { type: "thought", body: text ? text.slice(0, 500) : "Reasoning..." };
+    return [{ type: "thought", body: text ? text.slice(0, 500) : "Reasoning..." }];
   }
 
   if (
@@ -37,8 +37,8 @@ function mapCodexEventToActivity(event: any): ActivityContent | null {
     (item?.type === "agent_message" || item?.type === "message")
   ) {
     const text = item.text ?? item.content ?? "";
-    if (text) return { type: "thought", body: text.slice(0, 1000) };
-    return null;
+    if (text) return [{ type: "thought", body: text.slice(0, 1000) }];
+    return [];
   }
 
   if (eventType === "item.started" && item?.type === "command_execution") {
@@ -46,7 +46,7 @@ function mapCodexEventToActivity(event: any): ActivityContent | null {
     const cleaned = typeof cmd === "string"
       ? cmd.replace(/^\/usr\/bin\/\w+ -lc ['"]?/, "").replace(/['"]?$/, "")
       : JSON.stringify(cmd);
-    return { type: "action", action: "Running", parameter: cleaned.slice(0, 200) };
+    return [{ type: "action", action: "Running", parameter: cleaned.slice(0, 200) }];
   }
 
   if (eventType === "item.completed" && item?.type === "command_execution") {
@@ -57,19 +57,19 @@ function mapCodexEventToActivity(event: any): ActivityContent | null {
       ? cmd.replace(/^\/usr\/bin\/\w+ -lc ['"]?/, "").replace(/['"]?$/, "")
       : JSON.stringify(cmd);
     const truncated = output.length > 1000 ? output.slice(0, 1000) + "..." : output;
-    return {
+    return [{
       type: "action",
       action: `${cleaned.slice(0, 150)}`,
       parameter: `exit ${exitCode}`,
       result: truncated || undefined,
-    };
+    }];
   }
 
   if (eventType === "item.completed" && item?.type === "file_changes") {
     const files = item.files ?? [];
     const fileList = Array.isArray(files) ? files.join(", ") : String(files);
     const preview = (item.diff ?? item.content ?? "").slice(0, 500) || undefined;
-    return { type: "action", action: "Modified files", parameter: fileList || "unknown files", result: preview };
+    return [{ type: "action", action: "Modified files", parameter: fileList || "unknown files", result: preview }];
   }
 
   if (eventType === "turn.completed") {
@@ -78,12 +78,12 @@ function mapCodexEventToActivity(event: any): ActivityContent | null {
       const input = usage.input_tokens ?? 0;
       const cached = usage.cached_input_tokens ?? 0;
       const output = usage.output_tokens ?? 0;
-      return { type: "thought", body: `Codex turn complete (${input} in / ${cached} cached / ${output} out tokens)` };
+      return [{ type: "thought", body: `Codex turn complete (${input} in / ${cached} cached / ${output} out tokens)` }];
     }
-    return { type: "thought", body: "Codex turn complete" };
+    return [{ type: "thought", body: "Codex turn complete" }];
   }
 
-  return null;
+  return [];
 }
 
 /**
@@ -248,8 +248,8 @@ export async function runCodex(
         collectedCommands.push(`\`${cleanCmd}\` → exit ${exitCode}${truncOutput ? "\n```\n" + truncOutput + "\n```" : ""}`);
       }
 
-      const activity = mapCodexEventToActivity(event);
-      if (activity) {
+      const activities = mapCodexEventToActivity(event);
+      for (const activity of activities) {
         if (linearApi && agentSessionId) {
           linearApi.emitActivity(agentSessionId, activity).catch((err) => {
             api.logger.warn(`Failed to emit Codex activity: ${err}`);

package/src/tools/gemini-tool.ts

@@ -26,14 +26,14 @@ const GEMINI_BIN = "gemini";
  * Gemini event types:
  *   init → message(user) → message(assistant) → tool_use → tool_result → result
  */
-function mapGeminiEventToActivity(event: any): ActivityContent | null {
+function mapGeminiEventToActivity(event: any): ActivityContent[] {
   const type = event?.type;
 
   // Assistant message (delta text)
   if (type === "message" && event.role === "assistant") {
     const text = event.content;
-    if (text) return { type: "thought", body: text.slice(0, 1000) };
-    return null;
+    if (text) return [{ type: "thought", body: text.slice(0, 1000) }];
+    return [];
   }
 
   // Tool use — running a command or tool
@@ -50,7 +50,7 @@ function mapGeminiEventToActivity(event: any): ActivityContent | null {
     } else {
       paramSummary = JSON.stringify(params).slice(0, 500);
     }
-    return { type: "action", action: `Running ${toolName}`, parameter: paramSummary };
+    return [{ type: "action", action: `Running ${toolName}`, parameter: paramSummary }];
   }
 
   // Tool result
@@ -58,11 +58,11 @@ function mapGeminiEventToActivity(event: any): ActivityContent | null {
     const status = event.status ?? "unknown";
     const output = event.output ?? "";
     const truncated = output.length > 1000 ? output.slice(0, 1000) + "..." : output;
-    return {
+    return [{
       type: "action",
       action: `Tool ${status}`,
       parameter: truncated || "(no output)",
-    };
+    }];
   }
 
   // Final result
@@ -74,10 +74,10 @@ function mapGeminiEventToActivity(event: any): ActivityContent | null {
       if (stats.total_tokens) parts.push(`${stats.total_tokens} tokens`);
       if (stats.tool_calls) parts.push(`${stats.tool_calls} tool calls`);
     }
-    return { type: "thought", body: parts.join(" — ") };
+    return [{ type: "thought", body: parts.join(" — ") }];
   }
 
-  return null;
+  return [];
 }
 
 /**
@@ -244,9 +244,9 @@ export async function runGemini(
         }
       }
 
-      // Stream activity to Linear + session progress
-      const activity = mapGeminiEventToActivity(event);
-      if (activity) {
+      // Stream activities to Linear + session progress
+      const activities = mapGeminiEventToActivity(event);
+      for (const activity of activities) {
         if (linearApi && agentSessionId) {
           linearApi.emitActivity(agentSessionId, activity).catch((err) => {
             api.logger.warn(`Failed to emit Gemini activity: ${err}`);