@calltelemetry/openclaw-linear 0.8.4 → 0.8.6

package/src/__test__/webhook-scenarios.test.ts

@@ -628,4 +628,154 @@ describe("webhook scenario tests — full handler flows", () => {
       expect(mockGetIssueDetails).not.toHaveBeenCalled();
     });
   });
+
+  describe("Guidance integration", () => {
+    it("created: appends guidance to agent prompt", async () => {
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated({
+        guidance: "Always use the main branch. Run make test before closing.",
+      });
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const runArgs = mockRunAgent.mock.calls[0][0];
+      expect(runArgs.message).toContain("Additional Guidance");
+      expect(runArgs.message).toContain("Always use the main branch");
+    });
+
+    it("created: guidance is NOT used as user message", async () => {
+      const api = createApi();
+      const payload = makeAgentSessionEventCreated({
+        guidance: "Always use the main branch. Run make test before closing.",
+        previousComments: [
+          { body: "Please fix the routing bug", userId: "user-1", createdAt: new Date().toISOString() },
+        ],
+      });
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+
+      // Guidance text should appear in the appendix section, not as the user's comment
+      const userMsgSection = msg.split("Additional Guidance")[0];
+      expect(userMsgSection).toContain("Please fix the routing bug");
+      // The guidance string itself should not appear before the appendix
+      expect(userMsgSection).not.toContain("Always use the main branch");
+    });
+
+    it("prompted: includes guidance from promptContext", async () => {
+      const api = createApi();
+      const payload = makeAgentSessionEventPrompted({
+        agentActivity: { content: { body: "Can you also fix the tests?" } },
+        promptContext: "## Issue\nENG-123\n\n## Guidance\nUse TypeScript strict mode.\n\n## Comments\nThread.",
+      });
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+      expect(msg).toContain("Can you also fix the tests?");
+      expect(msg).toContain("Additional Guidance");
+      expect(msg).toContain("Use TypeScript strict mode");
+    });
+
+    it("guidance disabled via config: no guidance section in prompt", async () => {
+      const api = createApi();
+      (api as any).pluginConfig = { defaultAgentId: "mal", enableGuidance: false };
+      const payload = makeAgentSessionEventCreated({
+        guidance: "Should not appear in prompt",
+      });
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+      expect(msg).not.toContain("Additional Guidance");
+      expect(msg).not.toContain("Should not appear in prompt");
+    });
+
+    it("team override disables guidance for specific team", async () => {
+      const api = createApi();
+      (api as any).pluginConfig = {
+        defaultAgentId: "mal",
+        enableGuidance: true,
+        teamGuidanceOverrides: { "team-1": false },
+      };
+      const payload = makeAgentSessionEventCreated({
+        guidance: "Should be suppressed for team-1",
+      });
+      await postWebhook(api, payload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+      expect(msg).not.toContain("Additional Guidance");
+      expect(msg).not.toContain("Should be suppressed");
+    });
+
+    it("comment handler uses cached guidance from prior session event", async () => {
+      // Step 1: Trigger a created event to cache guidance
+      const api = createApi();
+      const sessionPayload = makeAgentSessionEventCreated({
+        guidance: "Cached guidance from session event",
+      });
+      await postWebhook(api, sessionPayload);
+      await waitForMock(mockClearActiveSession);
+
+      // Reset mocks for the next webhook
+      vi.clearAllMocks();
+      mockGetViewerId.mockResolvedValue("viewer-bot-1");
+      mockGetIssueDetails.mockResolvedValue(makeIssueDetails());
+      mockCreateComment.mockResolvedValue("comment-new-id");
+      mockEmitActivity.mockResolvedValue(undefined);
+      mockUpdateSession.mockResolvedValue(undefined);
+      mockUpdateIssue.mockResolvedValue(true);
+      mockCreateSessionOnIssue.mockResolvedValue({ sessionId: "session-mock-2" });
+      mockGetTeamLabels.mockResolvedValue([]);
+      mockGetTeamStates.mockResolvedValue([
+        { id: "st-backlog", name: "Backlog", type: "backlog" },
+        { id: "st-started", name: "In Progress", type: "started" },
+        { id: "st-done", name: "Done", type: "completed" },
+      ]);
+      mockRunAgent.mockResolvedValue({ success: true, output: "Agent response text" });
+      mockClassifyIntent.mockResolvedValue({
+        intent: "ask_agent",
+        agentId: "mal",
+        reasoning: "user requesting help",
+        fromFallback: false,
+      });
+
+      // Step 2: Now send a comment — it should pick up cached guidance
+      const commentPayload = makeCommentCreate({
+        data: {
+          id: "comment-guidance-1",
+          body: "Can you investigate further?",
+          user: { id: "user-human", name: "Human" },
+          issue: {
+            id: "issue-1",
+            identifier: "ENG-123",
+            title: "Fix webhook routing",
+            team: { id: "team-1" },
+            project: null,
+          },
+          createdAt: new Date().toISOString(),
+        },
+      });
+      await postWebhook(api, commentPayload);
+
+      await waitForMock(mockClearActiveSession);
+
+      expect(mockRunAgent).toHaveBeenCalledOnce();
+      const msg = mockRunAgent.mock.calls[0][0].message;
+      expect(msg).toContain("Additional Guidance");
+      expect(msg).toContain("Cached guidance from session event");
+    });
+  });
 });

package/src/api/linear-api.ts

@@ -307,6 +307,7 @@ export class LinearAgentApi {
     description: string | null;
     estimate: number | null;
     state: { name: string; type: string };
+    creator: { name: string; email: string | null } | null;
     assignee: { name: string } | null;
     labels: { nodes: Array<{ id: string; name: string }> };
     team: { id: string; name: string; issueEstimationType: string };
@@ -324,6 +325,7 @@ export class LinearAgentApi {
           description
           estimate
           state { name type }
+          creator { name email }
           assignee { name }
           labels { nodes { id name } }
           team { id name issueEstimationType }

package/src/infra/cli.ts

@@ -645,6 +645,33 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
       }
     });
 
+  // --- openclaw openclaw-linear code-run ---
+  const codeRunCmd = linear
+    .command("code-run")
+    .description("Manage and diagnose coding tool backends");
+
+  codeRunCmd
+    .command("doctor")
+    .description("Deep health check: verify each coding backend (Claude, Codex, Gemini) is callable")
+    .option("--json", "Output results as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      const { checkCodeRunDeep, buildSummary, formatReport, formatReportJson } = await import("./doctor.js");
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+
+      const sections = await checkCodeRunDeep(pluginConfig);
+      const report = { sections, summary: buildSummary(sections) };
+
+      if (opts.json) {
+        console.log(formatReportJson(report));
+      } else {
+        console.log(formatReport(report));
+      }
+
+      if (report.summary.errors > 0) {
+        process.exitCode = 1;
+      }
+    });
+
   // --- openclaw openclaw-linear webhooks ---
   const webhooksCmd = linear
     .command("webhooks")

package/src/infra/doctor.test.ts

@@ -50,14 +50,18 @@ vi.mock("./codex-worktree.js", () => ({
 
 vi.mock("../tools/code-tool.js", () => ({
   loadCodingConfig: vi.fn(() => ({
-    codingTool: "claude",
-    agentCodingTools: {},
+    codingTool: "codex",
+    agentCodingTools: { inara: "claude" },
     backends: {
       claude: { aliases: ["claude", "anthropic"] },
       codex: { aliases: ["codex", "openai"] },
       gemini: { aliases: ["gemini", "google"] },
     },
   })),
+  resolveCodingBackend: vi.fn((config: any, agentId?: string) => {
+    if (agentId && config?.agentCodingTools?.[agentId]) return config.agentCodingTools[agentId];
+    return config?.codingTool ?? "codex";
+  }),
 }));
 
 vi.mock("./webhook-provision.js", () => ({
@@ -78,6 +82,8 @@ import {
   checkConnectivity,
   checkDispatchHealth,
   checkWebhooks,
+  checkCodeRunDeep,
+  buildSummary,
   runDoctor,
   formatReport,
   formatReportJson,
@@ -199,7 +205,7 @@ describe("checkCodingTools", () => {
     const checks = checkCodingTools();
     const configCheck = checks.find((c) => c.label.includes("coding-tools.json"));
     expect(configCheck?.severity).toBe("pass");
-    expect(configCheck?.label).toContain("claude");
+    expect(configCheck?.label).toContain("codex");
   });
 
   it("reports warn for missing CLIs", () => {
@@ -431,3 +437,124 @@ describe("formatReportJson", () => {
     expect(parsed.summary.passed).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildSummary
+// ---------------------------------------------------------------------------
+
+describe("buildSummary", () => {
+  it("counts pass/warn/fail across sections", () => {
+    const sections = [
+      { name: "A", checks: [{ label: "ok", severity: "pass" as const }, { label: "meh", severity: "warn" as const }] },
+      { name: "B", checks: [{ label: "bad", severity: "fail" as const }] },
+    ];
+    const summary = buildSummary(sections);
+    expect(summary).toEqual({ passed: 1, warnings: 1, errors: 1 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkCodeRunDeep
+// ---------------------------------------------------------------------------
+
+describe("checkCodeRunDeep", () => {
+  // Run a single invocation and share results across assertions to avoid
+  // repeated 30s live CLI calls (the live test spawns all 3 backends).
+  let sections: Awaited<ReturnType<typeof checkCodeRunDeep>>;
+
+  beforeEach(async () => {
+    if (!sections) {
+      sections = await checkCodeRunDeep();
+    }
+  }, 120_000);
+
+  it("returns 4 sections (3 backends + routing)", () => {
+    expect(sections).toHaveLength(4);
+    expect(sections.map((s) => s.name)).toEqual([
+      "Code Run: Claude Code (Anthropic)",
+      "Code Run: Codex (OpenAI)",
+      "Code Run: Gemini CLI (Google)",
+      "Code Run: Routing",
+    ]);
+  });
+
+  it("each backend section has binary, API key, and live test checks", () => {
+    for (const section of sections.slice(0, 3)) {
+      const labels = section.checks.map((c) => c.label);
+      expect(labels.some((l) => l.includes("Binary:"))).toBe(true);
+      expect(labels.some((l) => l.includes("API key:"))).toBe(true);
+      expect(labels.some((l) => l.includes("Live test:"))).toBe(true);
+    }
+  });
+
+  it("all check results have valid severity", () => {
+    for (const section of sections) {
+      for (const check of section.checks) {
+        expect(check).toHaveProperty("label");
+        expect(check).toHaveProperty("severity");
+        expect(["pass", "warn", "fail"]).toContain(check.severity);
+      }
+    }
+  });
+
+  it("shows routing with default backend and callable count", () => {
+    const routing = sections.find((s) => s.name === "Code Run: Routing")!;
+    expect(routing).toBeDefined();
+
+    const defaultCheck = routing.checks.find((c) => c.label.includes("Default backend:"));
+    expect(defaultCheck?.severity).toBe("pass");
+    expect(defaultCheck?.label).toContain("codex");
+
+    const callableCheck = routing.checks.find((c) => c.label.includes("Callable backends:"));
+    expect(callableCheck?.severity).toBe("pass");
+    expect(callableCheck?.label).toMatch(/Callable backends: \d+\/3/);
+  });
+
+  it("shows agent override routing for inara", () => {
+    const routing = sections.find((s) => s.name === "Code Run: Routing")!;
+    const inaraCheck = routing.checks.find((c) => c.label.toLowerCase().includes("inara"));
+    if (inaraCheck) {
+      expect(inaraCheck.label).toContain("claude");
+      expect(inaraCheck.label).toContain("override");
+    }
+  });
+
+  // API key tests — still call checkCodeRunDeep which runs live CLI checks
+  it("detects API key from plugin config", async () => {
+    const origKey = process.env.ANTHROPIC_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
+
+    try {
+      const result = await checkCodeRunDeep({ claudeApiKey: "sk-from-config" });
+      const claudeKey = result[0].checks.find((c) => c.label.includes("API key:"));
+      expect(claudeKey?.severity).toBe("pass");
+      expect(claudeKey?.label).toContain("claudeApiKey");
+    } finally {
+      if (origKey) process.env.ANTHROPIC_API_KEY = origKey;
+      else delete process.env.ANTHROPIC_API_KEY;
+    }
+  }, 120_000);
+
+  it("warns when API key missing", async () => {
+    const origKeys = {
+      GEMINI_API_KEY: process.env.GEMINI_API_KEY,
+      GOOGLE_API_KEY: process.env.GOOGLE_API_KEY,
+      GOOGLE_GENAI_API_KEY: process.env.GOOGLE_GENAI_API_KEY,
+    };
+    delete process.env.GEMINI_API_KEY;
+    delete process.env.GOOGLE_API_KEY;
+    delete process.env.GOOGLE_GENAI_API_KEY;
+
+    try {
+      const result = await checkCodeRunDeep();
+      const geminiKey = result[2].checks.find((c) => c.label.includes("API key:"));
+      expect(geminiKey?.severity).toBe("warn");
+      expect(geminiKey?.label).toContain("not found");
+    } finally {
+      for (const [k, v] of Object.entries(origKeys)) {
+        if (v) process.env[k] = v;
+        else delete process.env[k];
+      }
+    }
+  }, 120_000);
+});

package/src/infra/doctor.ts

@@ -6,13 +6,13 @@
 import { existsSync, readFileSync, statSync, accessSync, unlinkSync, chmodSync, constants } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 
 import { resolveLinearToken, LinearAgentApi, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
 import { readDispatchState, listActiveDispatches, listStaleDispatches, pruneCompleted, type DispatchState } from "../pipeline/dispatch-state.js";
 import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
 import { listWorktrees } from "./codex-worktree.js";
-import { loadCodingConfig, type CodingBackend } from "../tools/code-tool.js";
+import { loadCodingConfig, resolveCodingBackend, type CodingBackend } from "../tools/code-tool.js";
 import { getWebhookStatus, provisionWebhook, REQUIRED_RESOURCE_TYPES } from "./webhook-provision.js";
 
 // ---------------------------------------------------------------------------
@@ -767,19 +767,209 @@ export async function runDoctor(opts: DoctorOptions): Promise<DoctorReport> {
     }
   }
 
-  // Build summary
-  let passed = 0, warnings = 0, errors = 0;
-  for (const section of sections) {
-    for (const check of section.checks) {
-      switch (check.severity) {
-        case "pass": passed++; break;
-        case "warn": warnings++; break;
-        case "fail": errors++; break;
+  return { sections, summary: buildSummary(sections) };
+}
+
+// ---------------------------------------------------------------------------
+// Code Run Deep Checks
+// ---------------------------------------------------------------------------
+
+interface BackendSpec {
+  id: CodingBackend;
+  label: string;
+  bin: string;
+  /** CLI args for a minimal live invocation test */
+  testArgs: string[];
+  /** Environment variable names that provide an API key */
+  envKeys: string[];
+  /** Plugin config key for API key (if any) */
+  configKey?: string;
+  /** Env vars to unset before spawning (e.g. CLAUDECODE) */
+  unsetEnv?: string[];
+}
+
+const BACKEND_SPECS: BackendSpec[] = [
+  {
+    id: "claude",
+    label: "Claude Code (Anthropic)",
+    bin: "/home/claw/.npm-global/bin/claude",
+    testArgs: ["--print", "-p", "Respond with the single word hello", "--output-format", "stream-json", "--max-turns", "1", "--dangerously-skip-permissions"],
+    envKeys: ["ANTHROPIC_API_KEY"],
+    configKey: "claudeApiKey",
+    unsetEnv: ["CLAUDECODE"],
+  },
+  {
+    id: "codex",
+    label: "Codex (OpenAI)",
+    bin: "/home/claw/.npm-global/bin/codex",
+    testArgs: ["exec", "--json", "--ephemeral", "--full-auto", "echo hello"],
+    envKeys: ["OPENAI_API_KEY"],
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI (Google)",
+    bin: "/home/claw/.npm-global/bin/gemini",
+    testArgs: ["-p", "Respond with the single word hello", "-o", "stream-json", "--yolo"],
+    envKeys: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENAI_API_KEY"],
+  },
+];
+
+function checkBackendBinary(spec: BackendSpec): { installed: boolean; checks: CheckResult[] } {
+  const checks: CheckResult[] = [];
+
+  // Binary existence
+  try {
+    accessSync(spec.bin, constants.X_OK);
+  } catch {
+    checks.push(fail(
+      `Binary: not found at ${spec.bin}`,
+      undefined,
+      `Install ${spec.id}: npm install -g <package>`,
+    ));
+    return { installed: false, checks };
+  }
+
+  // Version check
+  try {
+    const env = { ...process.env } as Record<string, string | undefined>;
+    for (const key of spec.unsetEnv ?? []) delete env[key];
+    const raw = execFileSync(spec.bin, ["--version"], {
+      encoding: "utf8",
+      timeout: 15_000,
+      env: env as NodeJS.ProcessEnv,
+    }).trim();
+    checks.push(pass(`Binary: ${raw || "installed"} (${spec.bin})`));
+  } catch {
+    checks.push(pass(`Binary: installed (${spec.bin})`));
+  }
+
+  return { installed: true, checks };
+}
+
+function checkBackendApiKey(spec: BackendSpec, pluginConfig?: Record<string, unknown>): CheckResult {
+  // Check plugin config first
+  if (spec.configKey) {
+    const configVal = pluginConfig?.[spec.configKey];
+    if (typeof configVal === "string" && configVal) {
+      return pass(`API key: configured (${spec.configKey} in plugin config)`);
+    }
+  }
+
+  // Check env vars
+  for (const envKey of spec.envKeys) {
+    if (process.env[envKey]) {
+      return pass(`API key: configured (${envKey})`);
+    }
+  }
+
+  return warn(
+    `API key: not found`,
+    `Checked: ${spec.envKeys.join(", ")}${spec.configKey ? `, pluginConfig.${spec.configKey}` : ""}`,
+    { fix: `Set ${spec.envKeys[0]} environment variable or configure in plugin config` },
+  );
+}
+
+function checkBackendLive(spec: BackendSpec, pluginConfig?: Record<string, unknown>): CheckResult {
+  const env = { ...process.env } as Record<string, string | undefined>;
+  for (const key of spec.unsetEnv ?? []) delete env[key];
+
+  // Pass API key from plugin config if available (Claude-specific)
+  if (spec.configKey) {
+    const configVal = pluginConfig?.[spec.configKey] as string | undefined;
+    if (configVal && spec.envKeys[0]) {
+      env[spec.envKeys[0]] = configVal;
+    }
+  }
+
+  const start = Date.now();
+  try {
+    const result = spawnSync(spec.bin, spec.testArgs, {
+      encoding: "utf8",
+      timeout: 30_000,
+      env: env as NodeJS.ProcessEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+
+    if (result.error) {
+      const msg = result.error.message ?? String(result.error);
+      if (msg.includes("ETIMEDOUT") || msg.includes("timed out")) {
+        return warn(`Live test: timed out after 30s`);
       }
+      return warn(`Live test: spawn error — ${msg.slice(0, 200)}`);
     }
+
+    if (result.status === 0) {
+      return pass(`Live test: responded in ${elapsed}s`);
+    }
+
+    // Non-zero exit
+    const stderr = (result.stderr ?? "").trim().slice(0, 200);
+    const stdout = (result.stdout ?? "").trim().slice(0, 200);
+    const detail = stderr || stdout || "(no output)";
+    return warn(`Live test: exit code ${result.status} (${elapsed}s) — ${detail}`);
+  } catch (err) {
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    return warn(`Live test: error (${elapsed}s) — ${err instanceof Error ? err.message.slice(0, 200) : String(err)}`);
   }
+}
+
+/**
+ * Deep health checks for coding tool backends.
+ *
+ * Verifies binary installation, API key configuration, and live callability
+ * for each backend (Claude, Codex, Gemini). Also shows agent routing.
+ *
+ * Usage: openclaw openclaw-linear code-run doctor [--json]
+ */
+export async function checkCodeRunDeep(
+  pluginConfig?: Record<string, unknown>,
+): Promise<CheckSection[]> {
+  const sections: CheckSection[] = [];
+  const config = loadCodingConfig();
+  let callableCount = 0;
+
+  for (const spec of BACKEND_SPECS) {
+    const checks: CheckResult[] = [];
+
+    // 1. Binary check
+    const { installed, checks: binChecks } = checkBackendBinary(spec);
+    checks.push(...binChecks);
+
+    if (installed) {
+      // 2. API key check
+      checks.push(checkBackendApiKey(spec, pluginConfig));
+
+      // 3. Live invocation test
+      const liveResult = checkBackendLive(spec, pluginConfig);
+      checks.push(liveResult);
 
-  return { sections, summary: { passed, warnings, errors } };
+      if (liveResult.severity === "pass") callableCount++;
+    }
+
+    sections.push({ name: `Code Run: ${spec.label}`, checks });
+  }
+
+  // Routing summary section
+  const routingChecks: CheckResult[] = [];
+  const defaultBackend = resolveCodingBackend(config);
+  routingChecks.push(pass(`Default backend: ${defaultBackend}`));
+
+  const profiles = loadAgentProfiles();
+  for (const [agentId, profile] of Object.entries(profiles)) {
+    const resolved = resolveCodingBackend(config, agentId);
+    const isOverride = config.agentCodingTools?.[agentId] != null;
+    const label = profile.label ?? agentId;
+    routingChecks.push(pass(
+      `${label} → ${resolved}${isOverride ? " (override)" : " (default)"}`,
+    ));
+  }
+
+  routingChecks.push(pass(`Callable backends: ${callableCount}/${BACKEND_SPECS.length}`));
+  sections.push({ name: "Code Run: Routing", checks: routingChecks });
+
+  return sections;
 }
 
 // ---------------------------------------------------------------------------
@@ -831,3 +1021,18 @@ export function formatReport(report: DoctorReport): string {
 export function formatReportJson(report: DoctorReport): string {
   return JSON.stringify(report, null, 2);
 }
+
+/** Build a summary by counting pass/warn/fail across sections. */
+export function buildSummary(sections: CheckSection[]): { passed: number; warnings: number; errors: number } {
+  let passed = 0, warnings = 0, errors = 0;
+  for (const section of sections) {
+    for (const check of section.checks) {
+      switch (check.severity) {
+        case "pass": passed++; break;
+        case "warn": warnings++; break;
+        case "fail": errors++; break;
+      }
+    }
+  }
+  return { passed, warnings, errors };
+}