@calltelemetry/openclaw-linear 0.5.2 → 0.6.1

package/src/agent/watchdog.ts

@@ -0,0 +1,176 @@
+/**
+ * watchdog.ts — I/O inactivity watchdog for agent sessions.
+ *
+ * Resets a countdown timer on every tick(). If no tick arrives within
+ * the inactivity threshold, fires onKill(). Also provides a config
+ * resolver that reads per-agent timeouts from agent-profiles.json.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Defaults (seconds — matches config units)
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_INACTIVITY_SEC = 120;     // 2 min
+export const DEFAULT_MAX_TOTAL_SEC = 7200;     // 2 hrs
+export const DEFAULT_TOOL_TIMEOUT_SEC = 600;   // 10 min
+
+// ---------------------------------------------------------------------------
+// Watchdog
+// ---------------------------------------------------------------------------
+
+export type WatchdogKillReason = "inactivity";
+
+export interface WatchdogOptions {
+  /** Inactivity threshold in ms. */
+  inactivityMs: number;
+  /** Label for logging (e.g. "embedded:zoe:session-123"). */
+  label: string;
+  /** Logger interface. */
+  logger: { info(msg: string): void; warn(msg: string): void };
+  /** Called when inactivity timeout fires. Must kill the process/abort. */
+  onKill: (reason: WatchdogKillReason) => void | Promise<void>;
+}
+
+export class InactivityWatchdog {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly inactivityMs: number;
+  private readonly label: string;
+  private readonly logger: WatchdogOptions["logger"];
+  private readonly onKill: WatchdogOptions["onKill"];
+  private lastActivityAt: number = Date.now();
+  private killed = false;
+  private started = false;
+
+  constructor(opts: WatchdogOptions) {
+    this.inactivityMs = opts.inactivityMs;
+    this.label = opts.label;
+    this.logger = opts.logger;
+    this.onKill = opts.onKill;
+  }
+
+  /** Start the watchdog. Call after the process/run is launched. */
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.lastActivityAt = Date.now();
+    this.scheduleCheck();
+    this.logger.info(`Watchdog started: ${this.label} (inactivity=${this.inactivityMs}ms)`);
+  }
+
+  /** Record an I/O activity tick. Resets the inactivity countdown. */
+  tick(): void {
+    this.lastActivityAt = Date.now();
+  }
+
+  /** Stop the watchdog (normal completion). */
+  stop(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.started = false;
+  }
+
+  /** Whether the watchdog triggered a kill. */
+  get wasKilled(): boolean {
+    return this.killed;
+  }
+
+  /** Milliseconds since last activity. */
+  get silenceMs(): number {
+    return Date.now() - this.lastActivityAt;
+  }
+
+  private scheduleCheck(): void {
+    const remaining = Math.max(1000, this.inactivityMs - (Date.now() - this.lastActivityAt));
+    this.timer = setTimeout(() => {
+      if (this.killed || !this.started) return;
+
+      const silence = Date.now() - this.lastActivityAt;
+      if (silence >= this.inactivityMs) {
+        this.killed = true;
+        this.logger.warn(
+          `Watchdog KILL: ${this.label} — no I/O for ${Math.round(silence / 1000)}s ` +
+          `(threshold: ${this.inactivityMs / 1000}s)`,
+        );
+        try {
+          const result = this.onKill("inactivity");
+          if (result && typeof (result as Promise<void>).catch === "function") {
+            (result as Promise<void>).catch((err) => {
+              this.logger.warn(`Watchdog onKill error: ${err}`);
+            });
+          }
+        } catch (err) {
+          this.logger.warn(`Watchdog onKill error: ${err}`);
+        }
+      } else {
+        // Activity happened during the wait — reschedule for remaining time
+        this.scheduleCheck();
+      }
+    }, remaining);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+
+export interface WatchdogConfig {
+  inactivityMs: number;
+  maxTotalMs: number;
+  toolTimeoutMs: number;
+}
+
+interface AgentProfileWatchdog {
+  inactivitySec?: number;
+  maxTotalSec?: number;
+  toolTimeoutSec?: number;
+}
+
+const PROFILES_PATH = join(process.env.HOME ?? "/home/claw", ".openclaw", "agent-profiles.json");
+
+function loadProfileWatchdog(agentId: string): AgentProfileWatchdog | null {
+  try {
+    const raw = readFileSync(PROFILES_PATH, "utf8");
+    const profiles = JSON.parse(raw).agents ?? {};
+    return profiles[agentId]?.watchdog ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve watchdog config for an agent.
+ *
+ * Priority: agent-profiles.json → plugin config → hardcoded defaults.
+ * All config values are in seconds; output is in ms.
+ */
+export function resolveWatchdogConfig(
+  agentId: string,
+  pluginConfig?: Record<string, unknown>,
+): WatchdogConfig {
+  const profile = loadProfileWatchdog(agentId);
+
+  const inactivitySec =
+    profile?.inactivitySec ??
+    (pluginConfig?.inactivitySec as number | undefined) ??
+    DEFAULT_INACTIVITY_SEC;
+
+  const maxTotalSec =
+    profile?.maxTotalSec ??
+    (pluginConfig?.maxTotalSec as number | undefined) ??
+    DEFAULT_MAX_TOTAL_SEC;
+
+  const toolTimeoutSec =
+    profile?.toolTimeoutSec ??
+    (pluginConfig?.toolTimeoutSec as number | undefined) ??
+    DEFAULT_TOOL_TIMEOUT_SEC;
+
+  return {
+    inactivityMs: inactivitySec * 1000,
+    maxTotalMs: maxTotalSec * 1000,
+    toolTimeoutMs: toolTimeoutSec * 1000,
+  };
+}

package/src/{cli.ts → infra/cli.ts}

@@ -9,10 +9,10 @@ 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 { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
+import { LINEAR_OAUTH_AUTH_URL, LINEAR_OAUTH_TOKEN_URL, LINEAR_AGENT_SCOPES } from "../api/auth.js";
 import { listWorktrees } from "./codex-worktree.js";
-import { loadPrompts, clearPromptCache } from "./pipeline.js";
+import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
 
 function prompt(question: string): Promise<string> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -262,7 +262,7 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
           ? customPath.replace("~", process.env.HOME ?? "")
           : customPath;
       } else {
-        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
         resolvedPath = join(pluginRoot, "prompts.yaml");
       }
 
@@ -293,7 +293,7 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
           ? customPath.replace("~", process.env.HOME ?? "")
           : customPath;
       } else {
-        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
         resolvedPath = join(pluginRoot, "prompts.yaml");
       }
 
@@ -342,4 +342,31 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
         process.exitCode = 1;
       }
     });
+
+  // --- openclaw openclaw-linear doctor ---
+  linear
+    .command("doctor")
+    .description("Run comprehensive health checks on the Linear plugin")
+    .option("--fix", "Auto-fix safe issues (chmod, stale locks, prune old dispatches)")
+    .option("--json", "Output results as JSON")
+    .action(async (opts: { fix?: boolean; json?: boolean }) => {
+      const { runDoctor, formatReport, formatReportJson } = await import("./doctor.js");
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+
+      const report = await runDoctor({
+        fix: opts.fix ?? false,
+        json: opts.json ?? false,
+        pluginConfig,
+      });
+
+      if (opts.json) {
+        console.log(formatReportJson(report));
+      } else {
+        console.log(formatReport(report));
+      }
+
+      if (report.summary.errors > 0) {
+        process.exitCode = 1;
+      }
+    });
 }

package/src/{codex-worktree.ts → infra/codex-worktree.ts}

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { ensureGitignore } from "./artifacts.js";
+import { ensureGitignore } from "../pipeline/artifacts.js";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
 const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");

package/src/infra/doctor.test.ts

@@ -0,0 +1,399 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// Mock heavy cross-module imports to isolate doctor checks
+vi.mock("../api/linear-api.js", () => ({
+  resolveLinearToken: vi.fn(() => ({
+    accessToken: "lin_test_token_123",
+    refreshToken: "refresh_token",
+    expiresAt: Date.now() + 24 * 3_600_000,
+    source: "profile" as const,
+  })),
+  AUTH_PROFILES_PATH: "/tmp/test-auth-profiles.json",
+  LINEAR_GRAPHQL_URL: "https://api.linear.app/graphql",
+}));
+
+vi.mock("../pipeline/dispatch-state.js", () => ({
+  readDispatchState: vi.fn(async () => ({
+    dispatches: { active: {}, completed: {} },
+    sessionMap: {},
+    processedEvents: [],
+  })),
+  listActiveDispatches: vi.fn(() => []),
+  listStaleDispatches: vi.fn(() => []),
+  pruneCompleted: vi.fn(async () => 0),
+}));
+
+vi.mock("../pipeline/pipeline.js", () => ({
+  loadPrompts: vi.fn(() => ({
+    worker: {
+      system: "You are a worker",
+      task: "Fix {{identifier}} {{title}} {{description}} in {{worktreePath}}",
+    },
+    audit: {
+      system: "You are an auditor",
+      task: "Audit {{identifier}} {{title}} {{description}} in {{worktreePath}}",
+    },
+    rework: { addendum: "Fix these gaps: {{gaps}}" },
+  })),
+  clearPromptCache: vi.fn(),
+}));
+
+vi.mock("./codex-worktree.js", () => ({
+  listWorktrees: vi.fn(() => []),
+}));
+
+vi.mock("../tools/code-tool.js", () => ({
+  loadCodingConfig: vi.fn(() => ({
+    codingTool: "claude",
+    agentCodingTools: {},
+    backends: {
+      claude: { aliases: ["claude", "anthropic"] },
+      codex: { aliases: ["codex", "openai"] },
+      gemini: { aliases: ["gemini", "google"] },
+    },
+  })),
+}));
+
+import {
+  checkAuth,
+  checkAgentConfig,
+  checkCodingTools,
+  checkFilesAndDirs,
+  checkConnectivity,
+  checkDispatchHealth,
+  runDoctor,
+  formatReport,
+  formatReportJson,
+} from "./doctor.js";
+
+import { resolveLinearToken } from "../api/linear-api.js";
+import { readDispatchState, listStaleDispatches, pruneCompleted } from "../pipeline/dispatch-state.js";
+import { loadPrompts } from "../pipeline/pipeline.js";
+import { listWorktrees } from "./codex-worktree.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// checkAuth
+// ---------------------------------------------------------------------------
+
+describe("checkAuth", () => {
+  it("reports pass when token is found", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ data: { viewer: { id: "1", name: "Test" }, organization: { name: "TestOrg", urlKey: "test" } } }),
+    })));
+
+    const { checks, ctx } = await checkAuth();
+    const tokenCheck = checks.find((c) => c.label.includes("Access token"));
+    expect(tokenCheck?.severity).toBe("pass");
+    expect(tokenCheck?.label).toContain("profile");
+    expect(ctx.viewer?.name).toBe("Test");
+  });
+
+  it("reports fail when no token found", async () => {
+    vi.mocked(resolveLinearToken).mockReturnValueOnce({
+      accessToken: null,
+      source: "none",
+    });
+
+    const { checks } = await checkAuth();
+    const tokenCheck = checks.find((c) => c.label.includes("access token"));
+    expect(tokenCheck?.severity).toBe("fail");
+  });
+
+  it("reports warn when token is expired", async () => {
+    vi.mocked(resolveLinearToken).mockReturnValueOnce({
+      accessToken: "tok",
+      expiresAt: Date.now() - 1000,
+      source: "profile",
+    });
+    vi.stubGlobal("fetch", vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ data: { viewer: { id: "1", name: "T" }, organization: { name: "O", urlKey: "o" } } }),
+    })));
+
+    const { checks } = await checkAuth();
+    const expiryCheck = checks.find((c) => c.label.includes("expired") || c.label.includes("Token"));
+    expect(expiryCheck?.severity).toBe("warn");
+  });
+
+  it("reports pass with time remaining", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ data: { viewer: { id: "1", name: "T" }, organization: { name: "O", urlKey: "o" } } }),
+    })));
+
+    const { checks } = await checkAuth();
+    const expiryCheck = checks.find((c) => c.label.includes("not expired"));
+    expect(expiryCheck?.severity).toBe("pass");
+    expect(expiryCheck?.label).toContain("h");
+  });
+
+  it("reports fail on API error", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => { throw new Error("network down"); }));
+
+    const { checks } = await checkAuth();
+    const apiCheck = checks.find((c) => c.label.includes("unreachable") || c.label.includes("API"));
+    expect(apiCheck?.severity).toBe("fail");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkAgentConfig
+// ---------------------------------------------------------------------------
+
+describe("checkAgentConfig", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "doctor-agent-"));
+  });
+
+  it("reports pass for valid agent profiles", () => {
+    // Mock the AGENT_PROFILES_PATH by writing to the expected location
+    // Since the path is hardcoded, we test the function's logic indirectly
+    const checks = checkAgentConfig();
+    // This tests against the real ~/.openclaw/agent-profiles.json on the system
+    // The checks should either pass (if file exists) or fail (if not)
+    expect(checks.length).toBeGreaterThan(0);
+  });
+
+  it("detects duplicate mention aliases", () => {
+    // Since we can't easily mock the file path, we test the overall behavior
+    const checks = checkAgentConfig();
+    // Verify the function returns structured results
+    for (const check of checks) {
+      expect(check).toHaveProperty("label");
+      expect(check).toHaveProperty("severity");
+      expect(["pass", "warn", "fail"]).toContain(check.severity);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkCodingTools
+// ---------------------------------------------------------------------------
+
+describe("checkCodingTools", () => {
+  it("reports loaded config with default backend", () => {
+    const checks = checkCodingTools();
+    const configCheck = checks.find((c) => c.label.includes("coding-tools.json"));
+    expect(configCheck?.severity).toBe("pass");
+    expect(configCheck?.label).toContain("claude");
+  });
+
+  it("reports warn for missing CLIs", () => {
+    const checks = checkCodingTools();
+    // Each CLI check should be present
+    const cliChecks = checks.filter((c) =>
+      c.label.startsWith("codex:") ||
+      c.label.startsWith("claude:") ||
+      c.label.startsWith("gemini:") ||
+      c.label.includes("not found"),
+    );
+    expect(cliChecks.length).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkFilesAndDirs
+// ---------------------------------------------------------------------------
+
+describe("checkFilesAndDirs", () => {
+  it("reports dispatch state counts", async () => {
+    vi.mocked(readDispatchState).mockResolvedValueOnce({
+      dispatches: {
+        active: { "API-1": { status: "working" } as any },
+        completed: { "API-2": { status: "done" } as any, "API-3": { status: "done" } as any },
+      },
+      sessionMap: {},
+      processedEvents: [],
+    });
+
+    const checks = await checkFilesAndDirs();
+    const stateCheck = checks.find((c) => c.label.includes("Dispatch state"));
+    expect(stateCheck?.severity).toBe("pass");
+    expect(stateCheck?.label).toContain("1 active");
+    expect(stateCheck?.label).toContain("2 completed");
+  });
+
+  it("reports valid prompts", async () => {
+    const checks = await checkFilesAndDirs();
+    const promptCheck = checks.find((c) => c.label.includes("Prompts"));
+    expect(promptCheck?.severity).toBe("pass");
+    expect(promptCheck?.label).toContain("5/5");
+    expect(promptCheck?.label).toContain("4/4");
+  });
+
+  it("reports prompt failures when sections missing", async () => {
+    vi.mocked(loadPrompts).mockReturnValueOnce({
+      worker: { system: "ok", task: "no vars here" },
+      audit: { system: "ok", task: "no vars here" },
+      rework: { addendum: "" },
+    } as any);
+
+    const checks = await checkFilesAndDirs();
+    const promptCheck = checks.find((c) => c.label.includes("Prompt") || c.label.includes("prompt"));
+    expect(promptCheck?.severity).toBe("fail");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkConnectivity
+// ---------------------------------------------------------------------------
+
+describe("checkConnectivity", () => {
+  it("skips Linear API re-check when authCtx provided", async () => {
+    const checks = await checkConnectivity(undefined, {
+      viewer: { name: "Test" },
+      organization: { name: "Org", urlKey: "org" },
+    });
+    const apiCheck = checks.find((c) => c.label.includes("Linear API"));
+    expect(apiCheck?.severity).toBe("pass");
+  });
+
+  it("reports Discord not configured as pass", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => { throw new Error("should not be called"); }));
+    const checks = await checkConnectivity({});
+    const discordCheck = checks.find((c) => c.label.includes("Discord"));
+    expect(discordCheck?.severity).toBe("pass");
+    expect(discordCheck?.label).toContain("not configured");
+  });
+
+  it("reports webhook skip when gateway not running", async () => {
+    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+      if (url.includes("localhost")) throw new Error("ECONNREFUSED");
+      throw new Error("unexpected");
+    }));
+
+    const checks = await checkConnectivity({}, {
+      viewer: { name: "T" },
+      organization: { name: "O", urlKey: "o" },
+    });
+    const webhookCheck = checks.find((c) => c.label.includes("Webhook"));
+    expect(webhookCheck?.severity).toBe("warn");
+    expect(webhookCheck?.label).toContain("gateway not detected");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkDispatchHealth
+// ---------------------------------------------------------------------------
+
+describe("checkDispatchHealth", () => {
+  it("reports no active dispatches", async () => {
+    const checks = await checkDispatchHealth();
+    const activeCheck = checks.find((c) => c.label.includes("active"));
+    expect(activeCheck?.severity).toBe("pass");
+  });
+
+  it("reports stale dispatches", async () => {
+    vi.mocked(listStaleDispatches).mockReturnValueOnce([
+      { issueIdentifier: "API-1", status: "working", dispatchedAt: new Date(Date.now() - 3 * 3_600_000).toISOString() } as any,
+    ]);
+
+    const checks = await checkDispatchHealth();
+    const staleCheck = checks.find((c) => c.label.includes("stale"));
+    expect(staleCheck?.severity).toBe("warn");
+    expect(staleCheck?.label).toContain("API-1");
+  });
+
+  it("prunes old completed with --fix", async () => {
+    vi.mocked(readDispatchState).mockResolvedValueOnce({
+      dispatches: {
+        active: {},
+        completed: {
+          "API-OLD": { completedAt: new Date(Date.now() - 10 * 24 * 3_600_000).toISOString(), status: "done" } as any,
+        },
+      },
+      sessionMap: {},
+      processedEvents: [],
+    });
+    vi.mocked(pruneCompleted).mockResolvedValueOnce(1);
+
+    const checks = await checkDispatchHealth(undefined, true);
+    const pruneCheck = checks.find((c) => c.label.includes("Pruned") || c.label.includes("prune"));
+    expect(pruneCheck).toBeDefined();
+    // With fix=true, it should have called pruneCompleted
+    expect(pruneCompleted).toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runDoctor (integration)
+// ---------------------------------------------------------------------------
+
+describe("runDoctor", () => {
+  it("returns all 6 sections", async () => {
+    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
+      if (url.includes("linear.app")) {
+        return {
+          ok: true,
+          json: async () => ({ data: { viewer: { id: "1", name: "T" }, organization: { name: "O", urlKey: "o" } } }),
+        };
+      }
+      throw new Error("not mocked");
+    }));
+
+    const report = await runDoctor({ fix: false, json: false });
+    expect(report.sections).toHaveLength(6);
+    expect(report.sections.map((s) => s.name)).toEqual([
+      "Authentication & Tokens",
+      "Agent Configuration",
+      "Coding Tools",
+      "Files & Directories",
+      "Connectivity",
+      "Dispatch Health",
+    ]);
+    expect(report.summary.passed + report.summary.warnings + report.summary.errors).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+
+describe("formatReport", () => {
+  it("produces readable output with section headers", () => {
+    const report = {
+      sections: [
+        {
+          name: "Test Section",
+          checks: [
+            { label: "Check passed", severity: "pass" as const },
+            { label: "Check warned", severity: "warn" as const },
+          ],
+        },
+      ],
+      summary: { passed: 1, warnings: 1, errors: 0 },
+    };
+
+    const output = formatReport(report);
+    expect(output).toContain("Linear Plugin Doctor");
+    expect(output).toContain("Test Section");
+    expect(output).toContain("Check passed");
+    expect(output).toContain("Check warned");
+    expect(output).toContain("1 passed");
+    expect(output).toContain("1 warning");
+  });
+});
+
+describe("formatReportJson", () => {
+  it("produces valid JSON", () => {
+    const report = {
+      sections: [{ name: "Test", checks: [{ label: "ok", severity: "pass" as const }] }],
+      summary: { passed: 1, warnings: 0, errors: 0 },
+    };
+
+    const json = formatReportJson(report);
+    const parsed = JSON.parse(json);
+    expect(parsed.sections).toHaveLength(1);
+    expect(parsed.summary.passed).toBe(1);
+  });
+});