@calltelemetry/openclaw-linear 0.4.1 → 0.5.0

package/index.ts

@@ -5,8 +5,11 @@ import { registerCli } from "./src/cli.js";
 import { createLinearTools } from "./src/tools.js";
 import { handleLinearWebhook } from "./src/webhook.js";
 import { handleOAuthCallback } from "./src/oauth-callback.js";
-import { resolveLinearToken } from "./src/linear-api.js";
+import { LinearAgentApi, resolveLinearToken } from "./src/linear-api.js";
 import { createDispatchService } from "./src/dispatch-service.js";
+import { readDispatchState, lookupSessionMapping, getActiveDispatch } from "./src/dispatch-state.js";
+import { triggerAudit, processVerdict, type HookContext } from "./src/pipeline.js";
+import { createDiscordNotifier, createNoopNotifier, type NotifyFn } from "./src/notify.js";
 
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
@@ -60,6 +63,106 @@ export default function register(api: OpenClawPluginApi) {
   // Register dispatch monitor service (stale detection, session hydration, cleanup)
   api.registerService(createDispatchService(api));
 
+  // ---------------------------------------------------------------------------
+  // Dispatch pipeline v2: notifier + agent_end lifecycle hook
+  // ---------------------------------------------------------------------------
+
+  // Instantiate notifier (Discord if configured, otherwise noop)
+  const discordBotToken = (() => {
+    try {
+      const config = JSON.parse(
+        require("node:fs").readFileSync(
+          require("node:path").join(process.env.HOME ?? "/home/claw", ".openclaw", "openclaw.json"),
+          "utf8",
+        ),
+      );
+      return config?.channels?.discord?.token as string | undefined;
+    } catch { return undefined; }
+  })();
+  const flowDiscordChannel = pluginConfig?.flowDiscordChannel as string | undefined;
+
+  const notify: NotifyFn = (discordBotToken && flowDiscordChannel)
+    ? createDiscordNotifier(discordBotToken, flowDiscordChannel)
+    : createNoopNotifier();
+
+  if (flowDiscordChannel && discordBotToken) {
+    api.logger.info(`Linear dispatch: Discord notifications enabled (channel: ${flowDiscordChannel})`);
+  }
+
+  // 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) => {
+    try {
+      const sessionKey = ctx?.sessionKey ?? "";
+      if (!sessionKey) return;
+
+      const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+      const state = await readDispatchState(statePath);
+      const mapping = lookupSessionMapping(state, sessionKey);
+      if (!mapping) return; // Not a dispatch sub-agent
+
+      const dispatch = getActiveDispatch(state, mapping.dispatchId);
+      if (!dispatch) {
+        api.logger.info(`agent_end: 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} ` +
+          `(event attempt=${mapping.attempt}, current=${dispatch.attempt})`
+        );
+        return;
+      }
+
+      // 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");
+        return;
+      }
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      const hookCtx: HookContext = {
+        api,
+        linearApi,
+        notify,
+        pluginConfig,
+        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") || "";
+
+      if (mapping.phase === "worker") {
+        api.logger.info(`agent_end: worker completed for ${mapping.dispatchId} — triggering audit`);
+        await triggerAudit(hookCtx, dispatch, {
+          success: event?.success ?? true,
+          output,
+        }, sessionKey);
+      } else if (mapping.phase === "audit") {
+        api.logger.info(`agent_end: audit completed for ${mapping.dispatchId} — processing verdict`);
+        await processVerdict(hookCtx, dispatch, {
+          success: event?.success ?? true,
+          output,
+        }, sessionKey);
+      }
+    } catch (err) {
+      api.logger.error(`agent_end hook error: ${err}`);
+    }
+  });
+
   // Narration Guard: catch short "Let me explore..." responses that narrate intent
   // without actually calling tools, and append a warning for the user.
   const NARRATION_PATTERNS = [

package/openclaw.plugin.json

@@ -19,7 +19,10 @@
       "codexTimeoutMs": { "type": "number", "description": "Default Codex timeout in milliseconds", "default": 600000 },
       "enableOrchestration": { "type": "boolean", "description": "Allow agents to spawn sub-agents via spawn_agent/ask_agent tools", "default": true },
       "worktreeBaseDir": { "type": "string", "description": "Base directory for persistent git worktrees (default: ~/.openclaw/worktrees)" },
-      "dispatchStatePath": { "type": "string", "description": "Path to dispatch state JSON file (default: ~/.openclaw/linear-dispatch-state.json)" }
+      "dispatchStatePath": { "type": "string", "description": "Path to dispatch state JSON file (default: ~/.openclaw/linear-dispatch-state.json)" },
+      "flowDiscordChannel": { "type": "string", "description": "Discord channel ID for dispatch lifecycle notifications (omit to disable)" },
+      "promptsPath": { "type": "string", "description": "Override path for prompts.yaml (default: ships with plugin)" },
+      "maxReworkAttempts": { "type": "number", "description": "Max audit failures before escalation", "default": 2 }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "index.ts",
     "src/",
     "openclaw.plugin.json",
+    "prompts.yaml",
     "README.md"
   ],
   "publishConfig": {
@@ -35,5 +36,8 @@
     "extensions": [
       "./index.ts"
     ]
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
   }
 }

package/prompts.yaml

@@ -0,0 +1,61 @@
+# prompts.yaml — Externalized phase prompts for the Linear dispatch pipeline.
+#
+# Template variables: {{identifier}}, {{title}}, {{description}},
+#   {{worktreePath}}, {{gaps}}, {{tier}}, {{attempt}}
+#
+# Edit these to customize worker/audit behavior without rebuilding the plugin.
+# Override path via `promptsPath` in plugin config.
+
+worker:
+  system: |
+    You are implementing a Linear issue. Your job is to plan and code the solution.
+    Post an implementation summary as a Linear comment when done.
+    DO NOT mark the issue as Done — that is handled by the audit system.
+    DO NOT attempt to change the issue status or labels.
+  task: |
+    Implement issue {{identifier}}: {{title}}
+
+    Issue body:
+    {{description}}
+
+    Worktree: {{worktreePath}}
+
+    Instructions:
+    1. Read the issue body carefully — it defines what needs to be done
+    2. Plan your approach
+    3. Implement the solution in the worktree
+    4. Run tests to verify your changes
+    5. Post an implementation summary as a comment on the Linear issue
+    6. Include what was changed, what tests were run, and any notes
+
+audit:
+  system: |
+    You are an independent auditor. Your job is to verify that work was completed correctly.
+    The Linear issue body is the SOURCE OF TRUTH for what "done" means.
+    Worker comments are secondary evidence of what was attempted.
+    You must be thorough and objective. Do not rubber-stamp.
+  task: |
+    Audit issue {{identifier}}: {{title}}
+
+    Issue body (source of truth):
+    {{description}}
+
+    Worktree: {{worktreePath}}
+
+    Checklist:
+    1. Identify ALL acceptance criteria from the issue body
+    2. Read worker comments on the issue (use linearis)
+    3. Verify each acceptance criterion is addressed in the code
+    4. Run tests in the worktree — verify they pass
+    5. Check test coverage if expectations are stated in the issue
+    6. Review the code diff for quality and correctness
+
+    You MUST return a JSON verdict as the last line of your response:
+    {"pass": true/false, "criteria": ["list of criteria found"], "gaps": ["list of unmet criteria"], "testResults": "summary of test output"}
+
+rework:
+  addendum: |
+    PREVIOUS AUDIT FAILED (attempt {{attempt}}). The auditor found these gaps:
+    {{gaps}}
+
+    Address these specific issues in your rework. Focus on the gaps listed above.

package/src/active-session.ts

@@ -84,7 +84,7 @@ export async function hydrateFromDispatchState(configPath?: string): Promise<num
   let restored = 0;
 
   for (const [, dispatch] of Object.entries(active)) {
-    if (dispatch.status === "dispatched" || dispatch.status === "running") {
+    if (dispatch.status === "dispatched" || dispatch.status === "working") {
       sessions.set(dispatch.issueId, {
         agentSessionId: dispatch.agentSessionId ?? "",
         issueIdentifier: dispatch.issueIdentifier,

package/src/cli.ts

@@ -6,9 +6,13 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { createInterface } from "node:readline";
 import { exec } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync as readFileSyncFs, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "./linear-api.js";
 import { LINEAR_OAUTH_AUTH_URL, LINEAR_OAUTH_TOKEN_URL, LINEAR_AGENT_SCOPES } from "./auth.js";
 import { listWorktrees } from "./codex-worktree.js";
+import { loadPrompts, clearPromptCache } from "./pipeline.js";
 
 function prompt(question: string): Promise<string> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -239,4 +243,103 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
 
       console.log(`\nTo remove one: openclaw openclaw-linear worktrees --prune <path>\n`);
     });
+
+  // --- openclaw openclaw-linear prompts ---
+  const prompts = linear
+    .command("prompts")
+    .description("Manage pipeline prompt templates (prompts.yaml)");
+
+  prompts
+    .command("show")
+    .description("Print current prompts.yaml content")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const customPath = pluginConfig?.promptsPath as string | undefined;
+
+      let resolvedPath: string;
+      if (customPath) {
+        resolvedPath = customPath.startsWith("~")
+          ? customPath.replace("~", process.env.HOME ?? "")
+          : customPath;
+      } else {
+        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+        resolvedPath = join(pluginRoot, "prompts.yaml");
+      }
+
+      console.log(`\nPrompts file: ${resolvedPath}\n`);
+
+      try {
+        const content = readFileSyncFs(resolvedPath, "utf-8");
+        console.log(content);
+      } catch {
+        console.log("(file not found — using built-in defaults)\n");
+        // Show the loaded defaults
+        clearPromptCache();
+        const loaded = loadPrompts(pluginConfig);
+        console.log(JSON.stringify(loaded, null, 2));
+      }
+    });
+
+  prompts
+    .command("path")
+    .description("Print the resolved prompts.yaml file path")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const customPath = pluginConfig?.promptsPath as string | undefined;
+
+      let resolvedPath: string;
+      if (customPath) {
+        resolvedPath = customPath.startsWith("~")
+          ? customPath.replace("~", process.env.HOME ?? "")
+          : customPath;
+      } else {
+        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+        resolvedPath = join(pluginRoot, "prompts.yaml");
+      }
+
+      const exists = existsSync(resolvedPath);
+      console.log(`${resolvedPath} ${exists ? "(exists)" : "(not found — using defaults)"}`);
+    });
+
+  prompts
+    .command("validate")
+    .description("Validate prompts.yaml structure")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      clearPromptCache();
+
+      try {
+        const loaded = loadPrompts(pluginConfig);
+        const errors: string[] = [];
+
+        if (!loaded.worker?.system) errors.push("Missing worker.system");
+        if (!loaded.worker?.task) errors.push("Missing worker.task");
+        if (!loaded.audit?.system) errors.push("Missing audit.system");
+        if (!loaded.audit?.task) errors.push("Missing audit.task");
+        if (!loaded.rework?.addendum) errors.push("Missing rework.addendum");
+
+        // Check for template variables
+        const requiredVars = ["{{identifier}}", "{{title}}", "{{description}}", "{{worktreePath}}"];
+        for (const v of requiredVars) {
+          if (!loaded.worker.task.includes(v)) {
+            errors.push(`worker.task missing template variable: ${v}`);
+          }
+          if (!loaded.audit.task.includes(v)) {
+            errors.push(`audit.task missing template variable: ${v}`);
+          }
+        }
+
+        if (errors.length > 0) {
+          console.log("\nValidation FAILED:\n");
+          for (const e of errors) console.log(`  - ${e}`);
+          console.log();
+          process.exitCode = 1;
+        } else {
+          console.log("\nValidation PASSED — all sections and template variables present.\n");
+        }
+      } catch (err) {
+        console.error(`\nFailed to load prompts: ${err}\n`);
+        process.exitCode = 1;
+      }
+    });
 }

package/src/dispatch-service.ts

@@ -16,6 +16,9 @@ import { hydrateFromDispatchState } from "./active-session.js";
 import {
   readDispatchState,
   listStaleDispatches,
+  listRecoverableDispatches,
+  transitionDispatch,
+  TransitionError,
   removeActiveDispatch,
   pruneCompleted,
 } from "./dispatch-state.js";
@@ -49,6 +52,27 @@ export function createDispatchService(api: OpenClawPluginApi) {
         ctx.logger.warn(`linear-dispatch: hydration failed: ${err}`);
       }
 
+      // Recovery scan: find dispatches stuck in "working" with a workerSessionKey
+      // but no auditSessionKey (worker completed but audit wasn't triggered before crash)
+      try {
+        const state = await readDispatchState(statePath);
+        const recoverable = listRecoverableDispatches(state);
+        for (const d of recoverable) {
+          ctx.logger.warn(
+            `linear-dispatch: recoverable dispatch ${d.issueIdentifier} ` +
+            `(status: ${d.status}, attempt: ${d.attempt}, workerKey: ${d.workerSessionKey}, auditKey: ${d.auditSessionKey ?? "none"})`,
+          );
+          // Mark as stuck for manual review — automated recovery requires
+          // re-triggering audit which needs the full HookContext (Linear API, notifier).
+          // The dispatch monitor logs a warning; operator can re-dispatch.
+        }
+        if (recoverable.length > 0) {
+          ctx.logger.warn(`linear-dispatch: ${recoverable.length} dispatch(es) need recovery — consider re-dispatching`);
+        }
+      } catch (err) {
+        ctx.logger.warn(`linear-dispatch: recovery scan failed: ${err}`);
+      }
+
       ctx.logger.info(`linear-dispatch: service started (interval: ${INTERVAL_MS / 1000}s)`);
 
       intervalId = setInterval(() => runTick(ctx), INTERVAL_MS);
@@ -71,9 +95,14 @@ export function createDispatchService(api: OpenClawPluginApi) {
       // Skip tick if nothing to do
       if (activeCount === 0 && Object.keys(state.dispatches.completed).length === 0) return;
 
-      // 1. Stale dispatch detection
+      // 1. Stale dispatch detection — transition truly stale dispatches to "stuck"
       const stale = listStaleDispatches(state, STALE_THRESHOLD_MS);
       for (const dispatch of stale) {
+        // Skip terminal states
+        if (dispatch.status === "done" || dispatch.status === "failed" || dispatch.status === "stuck") {
+          continue;
+        }
+
         // Check if worktree still exists and has progress
         if (existsSync(dispatch.worktreePath)) {
           const status = getWorktreeStatus(dispatch.worktreePath);
@@ -82,10 +111,29 @@ export function createDispatchService(api: OpenClawPluginApi) {
             continue;
           }
         }
+
         ctx.logger.warn(
           `linear-dispatch: stale dispatch ${dispatch.issueIdentifier} ` +
-          `(dispatched ${dispatch.dispatchedAt}, status: ${dispatch.status})`
+          `(dispatched ${dispatch.dispatchedAt}, status: ${dispatch.status}) — transitioning to stuck`,
         );
+
+        // Try to transition to stuck
+        try {
+          await transitionDispatch(
+            dispatch.issueIdentifier,
+            dispatch.status,
+            "stuck",
+            { stuckReason: `stale_${Math.round((Date.now() - new Date(dispatch.dispatchedAt).getTime()) / 3_600_000)}h` },
+            statePath,
+          );
+          ctx.logger.info(`linear-dispatch: ${dispatch.issueIdentifier} marked as stuck`);
+        } catch (err) {
+          if (err instanceof TransitionError) {
+            ctx.logger.info(`linear-dispatch: CAS failed for stale transition: ${(err as TransitionError).message}`);
+          } else {
+            ctx.logger.error(`linear-dispatch: stale transition error: ${err}`);
+          }
+        }
       }
 
       // 2. Worktree health — verify active dispatches have valid worktrees