@calltelemetry/openclaw-linear 0.4.0 → 0.5.0

package/index.ts

@@ -5,7 +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;
@@ -56,6 +60,109 @@ 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

@@ -17,7 +17,12 @@
       "codexBaseRepo": { "type": "string", "description": "Path to git repo for Codex worktrees", "default": "/home/claw/ai-workspace" },
       "codexModel": { "type": "string", "description": "Default Codex model (optional — uses Codex default if omitted)" },
       "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 }
+      "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)" },
+      "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.0",
+  "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

@@ -7,8 +7,14 @@
  *
  * This runs in the gateway process. Tool execution also happens in the gateway,
  * so tools can read from this registry directly.
+ *
+ * The in-memory Map is the fast-path for tool lookups. On startup, the
+ * dispatch service calls hydrateFromDispatchState() to rebuild it from
+ * the persistent dispatch-state.json file.
  */
 
+import { readDispatchState } from "./dispatch-state.js";
+
 export interface ActiveSession {
   agentSessionId: string;
   issueIdentifier: string;
@@ -64,3 +70,37 @@ export function getCurrentSession(): ActiveSession | null {
   }
   return null;
 }
+
+/**
+ * Hydrate the in-memory session Map from dispatch-state.json.
+ * Called on startup by the dispatch service to restore sessions
+ * that were active before a gateway restart.
+ *
+ * Returns the number of sessions restored.
+ */
+export async function hydrateFromDispatchState(configPath?: string): Promise<number> {
+  const state = await readDispatchState(configPath);
+  const active = state.dispatches.active;
+  let restored = 0;
+
+  for (const [, dispatch] of Object.entries(active)) {
+    if (dispatch.status === "dispatched" || dispatch.status === "working") {
+      sessions.set(dispatch.issueId, {
+        agentSessionId: dispatch.agentSessionId ?? "",
+        issueIdentifier: dispatch.issueIdentifier,
+        issueId: dispatch.issueId,
+        startedAt: new Date(dispatch.dispatchedAt).getTime(),
+      });
+      restored++;
+    }
+  }
+
+  return restored;
+}
+
+/**
+ * Get the count of currently tracked sessions.
+ */
+export function getSessionCount(): number {
+  return sessions.size;
+}

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/code-tool.ts

@@ -30,7 +30,7 @@ interface BackendConfig {
   aliases?: string[];
 }
 
-interface CodingToolsConfig {
+export interface CodingToolsConfig {
   codingTool?: string;
   agentCodingTools?: Record<string, string>;
   backends?: Record<string, BackendConfig>;
@@ -40,7 +40,7 @@ interface CodingToolsConfig {
  * Load coding tool config from the plugin's coding-tools.json file.
  * Falls back to empty config if the file doesn't exist or is invalid.
  */
-function loadCodingConfig(): CodingToolsConfig {
+export function loadCodingConfig(): CodingToolsConfig {
   try {
     // Resolve relative to the plugin root (one level up from src/)
     const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");