@calltelemetry/openclaw-linear 0.9.19 → 0.9.21

package/README.md

@@ -41,7 +41,9 @@ Connect Linear to AI agents. Issues get triaged, implemented, and audited — au
 - [x] CI + coverage badges (1170+ tests, Codecov integration)
 - [x] Setup wizard (`openclaw openclaw-linear setup`) + `doctor --fix` auto-repair
 - [x] Project context auto-detection (repo, framework, build/test commands → worker/audit prompts)
-- [x] Per-backend CLI tools (`cli_codex`, `cli_claude`, `cli_gemini`) with Linear session activity streaming
+- [x] Per-backend CLI tools (`cli_codex`, `cli_claude`, `cli_gemini`) with `[Codex]`/`[Claude]`/`[Gemini]`-prefixed Linear session activity streaming
+- [x] Immediate thought emission on comment receipt and tool dispatch (visible before long-running tasks complete)
+- [x] Proactive OAuth token refresh timer (runs on startup, then every 6h)
 - [ ] **Worktree → PR merge** — `createPullRequest()` exists but is not wired into the pipeline. After audit pass, commits sit on a `codex/{identifier}` branch. You create the PR manually.
 - [ ] **Sub-agent worktree sharing** — Sub-agents spawned via `spawn_agent`/`ask_agent` do not inherit the parent worktree. They run in their own session without code access.
 - [ ] **Parallel worktree conflict resolution** — DAG dispatch runs up to 3 issues concurrently in separate worktrees, but there's no merge conflict detection across them.
@@ -118,7 +120,7 @@ The end result: you work in Linear. You create issues, assign them, comment in p
 
 ### Multi-Backend & Multi-Repo
 
-- **Three coding backends** — Codex (OpenAI), Claude (Anthropic), Gemini (Google). Configurable globally or per-agent. Each backend registers as a dedicated tool (`cli_codex`, `cli_claude`, `cli_gemini`) so agents and Linear session UI show exactly which backend is running. Per-agent overrides let you assign different backends to different team members.
+- **Three coding backends** — Codex (OpenAI), Claude (Anthropic), Gemini (Google). Configurable globally or per-agent. Each backend registers as a dedicated tool (`cli_codex`, `cli_claude`, `cli_gemini`) with `[Codex]`/`[Claude]`/`[Gemini]`-prefixed activity streaming — thoughts, actions, progress, and results all show the backend label in Linear's session UI so you always know which runner is active. Per-agent overrides let you assign different backends to different team members.
 - **Multi-repo dispatch** — Tag an issue with `<!-- repos: api, frontend -->` and the worker gets isolated worktrees for each repo. One issue, multiple codebases, one agent session.
 
 ### Operations
@@ -132,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
@@ -1303,7 +1313,7 @@ Every agent session gets these registered tools. They're available as native too
 
 ### `cli_codex` / `cli_claude` / `cli_gemini` — Coding backend tools
 
-Three per-backend tools that send tasks to their respective coding CLIs. Each agent sees only the tool matching its configured backend (e.g., an agent configured for `codex` gets `cli_codex`). The tool name is visible in Linear's agent session UI, so you always know which backend is running. The agent writes the prompt; the plugin handles worktree setup, session activity streaming, and output capture.
+Three per-backend tools that send tasks to their respective coding CLIs. Each agent sees only the tool matching its configured backend (e.g., an agent configured for `codex` gets `cli_codex`). All activity emissions are prefixed with the backend label (`[Codex]`, `[Claude]`, `[Gemini]`) — thoughts, action starts, progress updates, results, and errors — so the Linear session UI always shows which runner is active. When a CLI tool is dispatched, an immediate thought is emitted with the prompt excerpt before the long-running task begins. The agent writes the prompt; the plugin handles worktree setup, session activity streaming, and output capture.
 
 ### `linear_issues` — Native Linear API
 
@@ -1449,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;
 
@@ -95,17 +140,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 +164,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 +180,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 +196,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 +241,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.19",
+  "version": "0.9.21",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/agent/agent.ts

@@ -293,6 +293,8 @@ async function runEmbedded(
 
   // Track last emitted tool to avoid duplicates
   let lastToolAction = "";
+  // Derive a friendly label from cli_ tool names: cli_codex→"Codex", cli_claude→"Claude"
+  const cliLabel = (name: string) => name.startsWith("cli_") ? name.slice(4).charAt(0).toUpperCase() + name.slice(5) : name;
 
   watchdog.start();
 
@@ -335,7 +337,8 @@ async function runEmbedded(
       if (text) {
         // Truncate tool results for activity display
         const truncated = text.length > 300 ? text.slice(0, 300) + "..." : text;
-        emit({ type: "action", action: lastToolAction || "Tool result", parameter: truncated });
+        const prefix = lastToolAction.startsWith("cli_") ? `[${cliLabel(lastToolAction)}] ` : "";
+        emit({ type: "action", action: `${prefix}${lastToolAction || "Tool result"}`, parameter: truncated });
       }
     },
 
@@ -364,11 +367,14 @@ async function runEmbedded(
       if (phase === "start") {
         lastToolAction = toolName;
 
-        // cli_codex / cli_claude / cli_gemini: show working dir and prompt excerpt
+        // cli_codex / cli_claude / cli_gemini: emit a thought + action so the
+        // user immediately sees what the agent is dispatching and why.
         if (toolName.startsWith("cli_") && inputObj) {
+          const tag = cliLabel(toolName);
           const prompt = String(inputObj.prompt ?? "").slice(0, 250);
           const workDir = inputObj.workingDir ? ` in ${inputObj.workingDir}` : "";
-          emit({ type: "action", action: `Running ${toolName}${workDir}`, parameter: prompt });
+          emit({ type: "thought", body: `[${tag}] Starting${workDir}: "${prompt}"\n\n${toolName}\nin progress` });
+          emit({ type: "action", action: `[${tag}] Running${workDir}`, parameter: prompt });
         } else {
           const detail = input || meta || toolName;
           emit({ type: "action", action: `Running ${toolName}`, parameter: detail.slice(0, 300) });
@@ -378,18 +384,21 @@ async function runEmbedded(
       // Tool execution update — partial progress (keeps Linear UI alive for long tools)
       if (phase === "update") {
         const detail = meta || input || "in progress";
-        emit({ type: "action", action: `${toolName}`, parameter: detail.slice(0, 300) });
+        const prefix = toolName.startsWith("cli_") ? `[${cliLabel(toolName)}] ` : "";
+        emit({ type: "action", action: `${prefix}${toolName}`, parameter: detail.slice(0, 300) });
       }
 
       // Tool execution completed successfully
       if (phase === "result" && !data.isError) {
         const detail = meta ? meta.slice(0, 300) : "completed";
-        emit({ type: "action", action: `${toolName} done`, parameter: detail });
+        const prefix = toolName.startsWith("cli_") ? `[${cliLabel(toolName)}] ` : "";
+        emit({ type: "action", action: `${prefix}${toolName} done`, parameter: detail });
       }
 
       // Tool execution result with error
       if (phase === "result" && data.isError) {
-        emit({ type: "action", action: `${toolName} failed`, parameter: (meta || "error").slice(0, 300) });
+        const prefix = toolName.startsWith("cli_") ? `[${cliLabel(toolName)}] ` : "";
+        emit({ type: "action", action: `${prefix}${toolName} failed`, parameter: (meta || "error").slice(0, 300) });
       }
     },
 

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;
@@ -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.
  */
@@ -119,6 +145,7 @@ export async function runInTmux(opts: RunInTmuxOptions): Promise<CliResult> {
       let killed = false;
       let killedByWatchdog = false;
       let resolved = false;
+      let completionEventReceived = false;
       const collectedMessages: string[] = [];
 
       const timer = setTimeout(() => {
@@ -175,8 +202,15 @@ export async function runInTmux(opts: RunInTmuxOptions): Promise<CliResult> {
             output: `Agent timed out after ${Math.round(timeoutMs / 1000)}s. Partial output:\n${output}`,
             error: "timeout",
           });
+        } else if (reason === "unexpected_exit") {
+          logger.warn(`tmux session ${sessionName} exited without completion event`);
+          resolve({
+            success: false,
+            output: `Agent session exited unexpectedly (no completion event received). Partial output:\n${output}`,
+            error: "unexpected_exit",
+          });
         } else {
-          // Normal completion
+          // Normal completion — only reached when completionEventReceived is true
           resolve({ success: true, output });
         }
       }
@@ -223,8 +257,9 @@ 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();
         }
@@ -233,7 +268,12 @@ export async function runInTmux(opts: RunInTmuxOptions): Promise<CliResult> {
       // Handle tail process ending (tmux session exited)
       tail.on("close", () => {
         if (!resolved) {
-          cleanup("done");
+          // If we never saw a completion event, the session died unexpectedly
+          if (completionEventReceived) {
+            cleanup("done");
+          } else {
+            cleanup("unexpected_exit");
+          }
         }
         rl.close();
       });

package/src/pipeline/webhook.ts

@@ -1731,11 +1731,12 @@ async function dispatchCommentToAgent(
       });
     }
 
-    // Emit thought
+    // Emit thought — include comment excerpt so the user sees immediate context
     if (agentSessionId) {
+      const excerpt = commentBody.length > 200 ? commentBody.slice(0, 200) + "..." : commentBody;
       await linearApi.emitActivity(agentSessionId, {
         type: "thought",
-        body: `${label} is processing comment on ${issueRef}...`,
+        body: `${label} received comment on ${issueRef}: "${excerpt}" — working on it now...`,
       }).catch(() => {});
     }