@calltelemetry/openclaw-linear 0.4.0 → 0.4.1

package/index.ts

@@ -6,6 +6,7 @@ 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 { createDispatchService } from "./src/dispatch-service.js";
 
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
@@ -56,6 +57,9 @@ export default function register(api: OpenClawPluginApi) {
     },
   });
 
+  // Register dispatch monitor service (stale detection, session hydration, cleanup)
+  api.registerService(createDispatchService(api));
+
   // 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,9 @@
       "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)" }
     }
   }
 }

package/package.json

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

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 === "running") {
+      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/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)), "..");

package/src/codex-worktree.ts

@@ -1,11 +1,16 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync, readdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
+const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
 
 export interface WorktreeInfo {
   path: string;
   branch: string;
+  /** True if the worktree already existed and was resumed, not freshly created. */
+  resumed: boolean;
 }
 
 export interface WorktreeStatus {
@@ -14,6 +19,19 @@ export interface WorktreeStatus {
   lastCommit: string | null;
 }
 
+export interface WorktreeOptions {
+  /** Base git repo to create worktrees from. Default: /home/claw/ai-workspace */
+  baseRepo?: string;
+  /** Directory under which worktrees are created. Default: ~/.openclaw/worktrees */
+  baseDir?: string;
+}
+
+function resolveBaseDir(baseDir?: string): string {
+  if (!baseDir) return DEFAULT_WORKTREE_BASE_DIR;
+  if (baseDir.startsWith("~/")) return baseDir.replace("~", homedir());
+  return baseDir;
+}
+
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
     cwd,
@@ -22,42 +40,89 @@ function git(args: string[], cwd: string): string {
   }).trim();
 }
 
+function gitLong(args: string[], cwd: string, timeout = 120_000): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout,
+  }).trim();
+}
+
 /**
- * Create a git worktree for isolated Codex work.
+ * Create a git worktree for isolated work on a Linear issue.
+ *
+ * Path: {baseDir}/{issueIdentifier}/ — deterministic, persistent.
  * Branch: codex/{issueIdentifier}
- * Path: /tmp/codex-{issueIdentifier}-{timestamp}
+ *
+ * Idempotent: if the worktree already exists, returns it without recreating.
+ * If the branch exists but the worktree is gone, recreates the worktree from
+ * the existing branch (resume scenario).
  */
 export function createWorktree(
   issueIdentifier: string,
-  baseRepo?: string,
+  opts?: WorktreeOptions,
 ): WorktreeInfo {
-  const repo = baseRepo ?? DEFAULT_BASE_REPO;
+  const repo = opts?.baseRepo ?? DEFAULT_BASE_REPO;
+  const baseDir = resolveBaseDir(opts?.baseDir);
+
   if (!existsSync(repo)) {
     throw new Error(`Base repo not found: ${repo}`);
   }
 
+  // Ensure base directory exists
+  if (!existsSync(baseDir)) {
+    mkdirSync(baseDir, { recursive: true });
+  }
+
   const branch = `codex/${issueIdentifier}`;
-  const ts = Date.now();
-  const worktreePath = `/tmp/codex-${issueIdentifier}-${ts}`;
+  const worktreePath = path.join(baseDir, issueIdentifier);
 
-  // Ensure we're on a clean base — fetch latest
+  // Fetch latest from origin (best effort) — do this early so both
+  // resume and fresh paths have up-to-date refs.
   try {
     git(["fetch", "origin"], repo);
   } catch {
     // Offline or no remote — continue with local state
   }
 
-  // Delete stale branch if it exists (from a previous run)
-  try {
-    git(["branch", "-D", branch], repo);
-  } catch {
-    // Branch doesn't exist — fine
+  // Idempotent: if worktree already exists, return it
+  if (existsSync(worktreePath)) {
+    try {
+      // Verify it's a valid git worktree
+      git(["rev-parse", "--git-dir"], worktreePath);
+      return { path: worktreePath, branch, resumed: true };
+    } catch {
+      // Directory exists but isn't a valid worktree — remove and recreate
+      try {
+        git(["worktree", "remove", "--force", worktreePath], repo);
+      } catch { /* best effort */ }
+    }
   }
 
-  // Create worktree with new branch off HEAD
+  // Check if branch already exists (resume scenario)
+  const branchExists = branchExistsInRepo(branch, repo);
+
+  if (branchExists) {
+    // Recreate worktree from existing branch — preserves previous work
+    git(["worktree", "add", worktreePath, branch], repo);
+    return { path: worktreePath, branch, resumed: true };
+  }
+
+  // Fresh start: new branch off HEAD
   git(["worktree", "add", "-b", branch, worktreePath], repo);
+  return { path: worktreePath, branch, resumed: false };
+}
 
-  return { path: worktreePath, branch };
+/**
+ * Check if a branch exists in the repo.
+ */
+function branchExistsInRepo(branch: string, repo: string): boolean {
+  try {
+    const result = git(["branch", "--list", branch], repo);
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -117,19 +182,13 @@ export function removeWorktree(
   }
 
   if (opts?.deleteBranch) {
-    // Extract branch name from the worktree path convention
+    // Extract issue identifier from worktree path to find matching branch
+    const dirName = path.basename(worktreePath);
+    const branch = `codex/${dirName}`;
     try {
-      const branches = git(["branch", "--list", "codex/*"], repo);
-      // Only delete if it looks like a codex branch
-      for (const b of branches.split("\n")) {
-        const name = b.trim().replace(/^\* /, "");
-        if (name && worktreePath.includes(name.replace("codex/", ""))) {
-          git(["branch", "-D", name], repo);
-          break;
-        }
-      }
+      git(["branch", "-D", branch], repo);
     } catch {
-      // Best effort
+      // Branch doesn't exist or already deleted
     }
   }
 }
@@ -175,23 +234,23 @@ export function createPullRequest(
 export interface WorktreeEntry {
   path: string;
   branch: string;
+  issueIdentifier: string;
   ageMs: number;
   hasChanges: boolean;
 }
 
 /**
- * List all codex worktrees under /tmp.
+ * List all worktrees in the configured base directory.
  */
-export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
-  const repo = baseRepo ?? DEFAULT_BASE_REPO;
+export function listWorktrees(opts?: WorktreeOptions): WorktreeEntry[] {
+  const baseDir = resolveBaseDir(opts?.baseDir);
   const entries: WorktreeEntry[] = [];
 
-  // Find /tmp/codex-* directories
+  if (!existsSync(baseDir)) return [];
+
   let dirs: string[];
   try {
-    dirs = readdirSync("/tmp")
-      .filter((d) => d.startsWith("codex-"))
-      .map((d) => `/tmp/${d}`);
+    dirs = readdirSync(baseDir).map((d) => path.join(baseDir, d));
   } catch {
     return [];
   }
@@ -202,6 +261,13 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
       const stat = statSync(dir);
       if (!stat.isDirectory()) continue;
 
+      // Verify it's a git worktree
+      try {
+        git(["rev-parse", "--git-dir"], dir);
+      } catch {
+        continue; // Not a git worktree
+      }
+
       let branch = "unknown";
       try {
         branch = git(["rev-parse", "--abbrev-ref", "HEAD"], dir);
@@ -216,6 +282,7 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
       entries.push({
         path: dir,
         branch,
+        issueIdentifier: path.basename(dir),
         ageMs: Date.now() - stat.mtimeMs,
         hasChanges,
       });
@@ -227,16 +294,75 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
   return entries.sort((a, b) => b.ageMs - a.ageMs);
 }
 
+export interface PrepareResult {
+  pulled: boolean;
+  pullOutput?: string;
+  submodulesInitialized: boolean;
+  submoduleOutput?: string;
+  errors: string[];
+}
+
+/**
+ * Prepare a worktree for a code run:
+ *   1. Pull latest from origin for the issue branch (fast-forward only)
+ *   2. Initialize and update all git submodules recursively
+ *
+ * Safe to call on every run — idempotent. Failures are non-fatal;
+ * the code run proceeds even if pull or submodule init fails.
+ */
+export function prepareWorkspace(worktreePath: string, branch: string): PrepareResult {
+  const errors: string[] = [];
+  let pulled = false;
+  let pullOutput: string | undefined;
+  let submodulesInitialized = false;
+  let submoduleOutput: string | undefined;
+
+  // 1. Pull latest from origin (ff-only to avoid merge conflicts)
+  try {
+    // Check if remote branch exists before pulling
+    const remoteBranch = `origin/${branch}`;
+    try {
+      git(["rev-parse", "--verify", remoteBranch], worktreePath);
+      // Remote branch exists — pull latest
+      pullOutput = git(["pull", "--ff-only", "origin", branch], worktreePath);
+      pulled = true;
+    } catch {
+      // Remote branch doesn't exist yet (fresh issue branch) — nothing to pull
+      pullOutput = "remote branch not found, skipping pull";
+    }
+  } catch (err) {
+    const msg = `pull failed: ${err}`;
+    errors.push(msg);
+    pullOutput = msg;
+  }
+
+  // 2. Initialize and update all submodules recursively
+  try {
+    submoduleOutput = gitLong(
+      ["submodule", "update", "--init", "--recursive"],
+      worktreePath,
+      120_000, // submodule clone can take a while
+    );
+    submodulesInitialized = true;
+  } catch (err) {
+    const msg = `submodule init failed: ${err}`;
+    errors.push(msg);
+    submoduleOutput = msg;
+  }
+
+  return { pulled, pullOutput, submodulesInitialized, submoduleOutput, errors };
+}
+
 /**
- * Remove codex worktrees older than maxAgeMs.
+ * Remove worktrees older than maxAgeMs.
  * Returns list of removed paths.
  */
 export function pruneStaleWorktrees(
   maxAgeMs: number = 24 * 60 * 60_000,
-  opts?: { baseRepo?: string; dryRun?: boolean },
+  opts?: WorktreeOptions & { dryRun?: boolean },
 ): { removed: string[]; skipped: string[]; errors: string[] } {
+  const worktrees = listWorktrees(opts);
   const repo = opts?.baseRepo ?? DEFAULT_BASE_REPO;
-  const worktrees = listWorktrees(repo);
   const removed: string[] = [];
   const skipped: string[] = [];
   const errors: string[] = [];

package/src/dispatch-service.ts

@@ -0,0 +1,113 @@
+/**
+ * dispatch-service.ts — Background service for dispatch health monitoring.
+ *
+ * Registered via api.registerService(). Runs on a 5-minute interval.
+ * Zero LLM tokens — all logic is deterministic code.
+ *
+ * Responsibilities:
+ * - Hydrate active sessions from dispatch-state.json on startup
+ * - Detect stale dispatches (active >2h with no progress)
+ * - Verify worktree health for active dispatches
+ * - Prune completed dispatches older than 7 days
+ */
+import { existsSync } from "node:fs";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { hydrateFromDispatchState } from "./active-session.js";
+import {
+  readDispatchState,
+  listStaleDispatches,
+  removeActiveDispatch,
+  pruneCompleted,
+} from "./dispatch-state.js";
+import { getWorktreeStatus } from "./codex-worktree.js";
+
+const INTERVAL_MS = 5 * 60_000; // 5 minutes
+const STALE_THRESHOLD_MS = 2 * 60 * 60_000; // 2 hours
+const COMPLETED_MAX_AGE_MS = 7 * 24 * 60 * 60_000; // 7 days
+
+type ServiceContext = {
+  logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+};
+
+export function createDispatchService(api: OpenClawPluginApi) {
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  return {
+    id: "linear-dispatch-monitor",
+
+    start: async (ctx: ServiceContext) => {
+      // Hydrate active sessions on startup
+      try {
+        const restored = await hydrateFromDispatchState(statePath);
+        if (restored > 0) {
+          ctx.logger.info(`linear-dispatch: hydrated ${restored} active session(s) from dispatch state`);
+        }
+      } catch (err) {
+        ctx.logger.warn(`linear-dispatch: hydration failed: ${err}`);
+      }
+
+      ctx.logger.info(`linear-dispatch: service started (interval: ${INTERVAL_MS / 1000}s)`);
+
+      intervalId = setInterval(() => runTick(ctx), INTERVAL_MS);
+    },
+
+    stop: async (ctx: ServiceContext) => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+        ctx.logger.info("linear-dispatch: service stopped");
+      }
+    },
+  };
+
+  async function runTick(ctx: ServiceContext): Promise<void> {
+    try {
+      const state = await readDispatchState(statePath);
+      const activeCount = Object.keys(state.dispatches.active).length;
+
+      // Skip tick if nothing to do
+      if (activeCount === 0 && Object.keys(state.dispatches.completed).length === 0) return;
+
+      // 1. Stale dispatch detection
+      const stale = listStaleDispatches(state, STALE_THRESHOLD_MS);
+      for (const dispatch of stale) {
+        // Check if worktree still exists and has progress
+        if (existsSync(dispatch.worktreePath)) {
+          const status = getWorktreeStatus(dispatch.worktreePath);
+          if (status.hasUncommitted || status.lastCommit) {
+            // Worktree has activity — not truly stale, just slow
+            continue;
+          }
+        }
+        ctx.logger.warn(
+          `linear-dispatch: stale dispatch ${dispatch.issueIdentifier} ` +
+          `(dispatched ${dispatch.dispatchedAt}, status: ${dispatch.status})`
+        );
+      }
+
+      // 2. Worktree health — verify active dispatches have valid worktrees
+      for (const [id, dispatch] of Object.entries(state.dispatches.active)) {
+        if (!existsSync(dispatch.worktreePath)) {
+          ctx.logger.warn(
+            `linear-dispatch: worktree missing for ${id} at ${dispatch.worktreePath}`
+          );
+        }
+      }
+
+      // 3. Prune old completed entries
+      const pruned = await pruneCompleted(COMPLETED_MAX_AGE_MS, statePath);
+      if (pruned > 0) {
+        ctx.logger.info(`linear-dispatch: pruned ${pruned} old completed dispatch(es)`);
+      }
+
+      if (activeCount > 0) {
+        ctx.logger.info(`linear-dispatch: tick — ${activeCount} active, ${stale.length} stale`);
+      }
+    } catch (err) {
+      ctx.logger.error(`linear-dispatch: tick failed: ${err}`);
+    }
+  }
+}