@calltelemetry/openclaw-linear 0.8.5 → 0.8.7

package/src/pipeline/guidance.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  extractGuidance,
+  extractGuidanceFromPromptContext,
+  cacheGuidanceForTeam,
+  getCachedGuidanceForTeam,
+  formatGuidanceAppendix,
+  isGuidanceEnabled,
+  _resetGuidanceCacheForTesting,
+} from "./guidance.js";
+
+beforeEach(() => {
+  _resetGuidanceCacheForTesting();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// extractGuidance
+// ---------------------------------------------------------------------------
+
+describe("extractGuidance", () => {
+  it("extracts from top-level guidance field", () => {
+    const result = extractGuidance({ guidance: "Always use main branch." });
+    expect(result.guidance).toBe("Always use main branch.");
+    expect(result.source).toBe("webhook");
+  });
+
+  it("falls back to promptContext when guidance is missing", () => {
+    const result = extractGuidance({
+      promptContext: "## Guidance\nUse TypeScript.\n\n## Issue\nENG-123",
+    });
+    expect(result.guidance).toBe("Use TypeScript.");
+    expect(result.source).toBe("promptContext");
+  });
+
+  it("prefers top-level guidance over promptContext", () => {
+    const result = extractGuidance({
+      guidance: "From top-level",
+      promptContext: "## Guidance\nFrom promptContext",
+    });
+    expect(result.guidance).toBe("From top-level");
+    expect(result.source).toBe("webhook");
+  });
+
+  it("returns null when neither field exists", () => {
+    const result = extractGuidance({});
+    expect(result.guidance).toBeNull();
+    expect(result.source).toBeNull();
+  });
+
+  it("ignores empty/whitespace guidance", () => {
+    const result = extractGuidance({ guidance: "   " });
+    expect(result.guidance).toBeNull();
+    expect(result.source).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractGuidanceFromPromptContext
+// ---------------------------------------------------------------------------
+
+describe("extractGuidanceFromPromptContext", () => {
+  it("extracts from XML-style <guidance> tags", () => {
+    const pc = "Some preamble.\n<guidance>Use Go for API work.\nAlways add tests.</guidance>\nMore stuff.";
+    expect(extractGuidanceFromPromptContext(pc)).toBe("Use Go for API work.\nAlways add tests.");
+  });
+
+  it("extracts from markdown ## Guidance heading", () => {
+    const pc = "## Issue\nENG-123\n\n## Guidance\nCommit messages must reference JIRA.\n\n## Comments\nSome comments.";
+    expect(extractGuidanceFromPromptContext(pc)).toBe("Commit messages must reference JIRA.");
+  });
+
+  it("extracts from markdown # Guidance heading", () => {
+    const pc = "# Guidance\nRun make test.\n\n# Issue\nENG-456";
+    expect(extractGuidanceFromPromptContext(pc)).toBe("Run make test.");
+  });
+
+  it("returns null when no guidance section found", () => {
+    const pc = "## Issue\nENG-123\n\n## Description\nSome text.";
+    expect(extractGuidanceFromPromptContext(pc)).toBeNull();
+  });
+
+  it("handles guidance at end of string (no trailing heading)", () => {
+    const pc = "## Guidance\nAlways use TypeScript.";
+    expect(extractGuidanceFromPromptContext(pc)).toBe("Always use TypeScript.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatGuidanceAppendix
+// ---------------------------------------------------------------------------
+
+describe("formatGuidanceAppendix", () => {
+  it("formats guidance as appendix block", () => {
+    const result = formatGuidanceAppendix("Use main branch.");
+    expect(result).toContain("## Additional Guidance");
+    expect(result).toContain("Use main branch.");
+    expect(result).toMatch(/^---\n/);
+    expect(result).toMatch(/\n---$/);
+  });
+
+  it("returns empty string for null", () => {
+    expect(formatGuidanceAppendix(null)).toBe("");
+  });
+
+  it("returns empty string for empty string", () => {
+    expect(formatGuidanceAppendix("")).toBe("");
+  });
+
+  it("returns empty string for whitespace-only", () => {
+    expect(formatGuidanceAppendix("   \n  ")).toBe("");
+  });
+
+  it("truncates at 2000 chars", () => {
+    const long = "x".repeat(3000);
+    const result = formatGuidanceAppendix(long);
+    // 2000 x's + the framing text
+    expect(result).toContain("x".repeat(2000));
+    expect(result).not.toContain("x".repeat(2001));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Cache: cacheGuidanceForTeam / getCachedGuidanceForTeam
+// ---------------------------------------------------------------------------
+
+describe("guidance cache", () => {
+  it("stores and retrieves guidance by team ID", () => {
+    cacheGuidanceForTeam("team-1", "Use TypeScript.");
+    expect(getCachedGuidanceForTeam("team-1")).toBe("Use TypeScript.");
+  });
+
+  it("returns null for unknown team", () => {
+    expect(getCachedGuidanceForTeam("team-unknown")).toBeNull();
+  });
+
+  it("returns null after TTL expiry", () => {
+    const now = Date.now();
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    cacheGuidanceForTeam("team-1", "guidance");
+
+    // Advance 25 hours
+    vi.spyOn(Date, "now").mockReturnValue(now + 25 * 60 * 60 * 1000);
+    expect(getCachedGuidanceForTeam("team-1")).toBeNull();
+  });
+
+  it("evicts oldest entry when at capacity", () => {
+    // Fill cache to 50 entries
+    for (let i = 0; i < 50; i++) {
+      cacheGuidanceForTeam(`team-${i}`, `guidance-${i}`);
+    }
+    expect(getCachedGuidanceForTeam("team-0")).toBe("guidance-0");
+
+    // Adding one more should evict team-0 (oldest)
+    cacheGuidanceForTeam("team-new", "new guidance");
+    expect(getCachedGuidanceForTeam("team-0")).toBeNull();
+    expect(getCachedGuidanceForTeam("team-new")).toBe("new guidance");
+  });
+
+  it("updates existing entry without eviction", () => {
+    cacheGuidanceForTeam("team-1", "old");
+    cacheGuidanceForTeam("team-1", "new");
+    expect(getCachedGuidanceForTeam("team-1")).toBe("new");
+  });
+
+  it("clears on _resetGuidanceCacheForTesting", () => {
+    cacheGuidanceForTeam("team-1", "guidance");
+    _resetGuidanceCacheForTesting();
+    expect(getCachedGuidanceForTeam("team-1")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isGuidanceEnabled
+// ---------------------------------------------------------------------------
+
+describe("isGuidanceEnabled", () => {
+  it("returns true by default (no config)", () => {
+    expect(isGuidanceEnabled(undefined, "team-1")).toBe(true);
+  });
+
+  it("returns true when enableGuidance not set", () => {
+    expect(isGuidanceEnabled({}, "team-1")).toBe(true);
+  });
+
+  it("returns false when enableGuidance is false", () => {
+    expect(isGuidanceEnabled({ enableGuidance: false }, "team-1")).toBe(false);
+  });
+
+  it("returns true when enableGuidance is true", () => {
+    expect(isGuidanceEnabled({ enableGuidance: true }, "team-1")).toBe(true);
+  });
+
+  it("team override true overrides workspace false", () => {
+    const config = {
+      enableGuidance: false,
+      teamGuidanceOverrides: { "team-1": true },
+    };
+    expect(isGuidanceEnabled(config, "team-1")).toBe(true);
+  });
+
+  it("team override false overrides workspace true", () => {
+    const config = {
+      enableGuidance: true,
+      teamGuidanceOverrides: { "team-1": false },
+    };
+    expect(isGuidanceEnabled(config, "team-1")).toBe(false);
+  });
+
+  it("unset team inherits workspace setting", () => {
+    const config = {
+      enableGuidance: false,
+      teamGuidanceOverrides: { "team-other": true },
+    };
+    expect(isGuidanceEnabled(config, "team-1")).toBe(false);
+  });
+
+  it("works with undefined teamId", () => {
+    expect(isGuidanceEnabled({ enableGuidance: false }, undefined)).toBe(false);
+    expect(isGuidanceEnabled({ enableGuidance: true }, undefined)).toBe(true);
+  });
+});

package/src/pipeline/guidance.ts

@@ -0,0 +1,156 @@
+/**
+ * Linear workspace & team guidance extraction, caching, and formatting.
+ *
+ * Guidance is delivered via AgentSessionEvent webhook payloads (both the
+ * top-level `guidance` field and embedded within `promptContext`). This
+ * module extracts it, caches it per-team (so Comment webhook paths can
+ * benefit), and formats it as a prompt appendix.
+ *
+ * @see https://linear.app/docs/agents-in-linear
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GuidanceContext {
+  /** The raw guidance string (workspace + team merged by Linear) */
+  guidance: string | null;
+  /** Where the guidance came from */
+  source: "webhook" | "promptContext" | null;
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract guidance from an AgentSessionEvent webhook payload.
+ * Priority: payload.guidance (string) > parsed from payload.promptContext > null.
+ */
+export function extractGuidance(payload: Record<string, unknown>): GuidanceContext {
+  // 1. Top-level guidance field (clean string from Linear)
+  const guidance = payload.guidance;
+  if (typeof guidance === "string" && guidance.trim()) {
+    return { guidance: guidance.trim(), source: "webhook" };
+  }
+
+  // 2. Try parsing from promptContext
+  const pc = payload.promptContext;
+  if (typeof pc === "string" && pc.trim()) {
+    const extracted = extractGuidanceFromPromptContext(pc);
+    if (extracted) {
+      return { guidance: extracted, source: "promptContext" };
+    }
+  }
+
+  return { guidance: null, source: null };
+}
+
+/**
+ * Best-effort parse guidance from a promptContext string.
+ * Linear's promptContext format may include guidance as XML-style tags
+ * or markdown-headed sections.
+ */
+export function extractGuidanceFromPromptContext(promptContext: string): string | null {
+  // Pattern 1: XML-style tags (e.g. <guidance>...</guidance>)
+  const xmlMatch = promptContext.match(/<guidance>([\s\S]*?)<\/guidance>/i);
+  if (xmlMatch?.[1]?.trim()) return xmlMatch[1].trim();
+
+  // Pattern 2: Markdown heading "## Guidance" or "# Guidance"
+  const mdMatch = promptContext.match(/#{1,3}\s*[Gg]uidance\s*\n([\s\S]*?)(?=\n#{1,3}\s|$)/);
+  if (mdMatch?.[1]?.trim()) return mdMatch[1].trim();
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Cache (per-team, 24h TTL, 50-entry cap)
+// ---------------------------------------------------------------------------
+
+interface CacheEntry {
+  guidance: string;
+  cachedAt: number;
+}
+
+const guidanceCache = new Map<string, CacheEntry>();
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CACHE_MAX_ENTRIES = 50;
+
+/** Cache guidance by team ID. */
+export function cacheGuidanceForTeam(teamId: string, guidance: string): void {
+  // Evict oldest if at capacity
+  if (guidanceCache.size >= CACHE_MAX_ENTRIES && !guidanceCache.has(teamId)) {
+    const oldest = guidanceCache.keys().next().value;
+    if (oldest !== undefined) guidanceCache.delete(oldest);
+  }
+  guidanceCache.set(teamId, { guidance, cachedAt: Date.now() });
+}
+
+/** Look up cached guidance for a team. Returns null on miss or expiry. */
+export function getCachedGuidanceForTeam(teamId: string): string | null {
+  const entry = guidanceCache.get(teamId);
+  if (!entry) return null;
+  if (Date.now() - entry.cachedAt > CACHE_TTL_MS) {
+    guidanceCache.delete(teamId);
+    return null;
+  }
+  return entry.guidance;
+}
+
+/** Test-only: reset the guidance cache. */
+export function _resetGuidanceCacheForTesting(): void {
+  guidanceCache.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+const MAX_GUIDANCE_CHARS = 2000;
+
+/**
+ * Format guidance as a prompt appendix.
+ * Returns empty string if guidance is null/empty.
+ * Truncates at 2000 chars to protect token budget.
+ */
+export function formatGuidanceAppendix(guidance: string | null): string {
+  if (!guidance?.trim()) return "";
+  const trimmed = guidance.trim().slice(0, MAX_GUIDANCE_CHARS);
+  return [
+    `---`,
+    `## Additional Guidance (from Linear workspace/team settings)`,
+    trimmed,
+    `---`,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Config toggle
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve whether guidance is enabled for a given team.
+ * Resolution: teamGuidanceOverrides[teamId] ?? enableGuidance ?? true
+ */
+export function isGuidanceEnabled(
+  pluginConfig: Record<string, unknown> | undefined,
+  teamId: string | undefined,
+): boolean {
+  if (!pluginConfig) return true;
+
+  // Check per-team override first
+  if (teamId) {
+    const overrides = pluginConfig.teamGuidanceOverrides;
+    if (overrides && typeof overrides === "object" && !Array.isArray(overrides)) {
+      const teamOverride = (overrides as Record<string, unknown>)[teamId];
+      if (typeof teamOverride === "boolean") return teamOverride;
+    }
+  }
+
+  // Fall back to workspace-level toggle
+  const enabled = pluginConfig.enableGuidance;
+  if (typeof enabled === "boolean") return enabled;
+
+  return true; // default on
+}

package/src/pipeline/pipeline.ts

@@ -19,6 +19,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { LinearAgentApi, ActivityContent } from "../api/linear-api.js";
 import { runAgent } from "../agent/agent.js";
 import { setActiveSession, clearActiveSession } from "./active-session.js";
+import { getCachedGuidanceForTeam, isGuidanceEnabled } from "./guidance.js";
 import {
   type Tier,
   type DispatchStatus,
@@ -191,7 +192,7 @@ export interface IssueContext {
 export function buildWorkerTask(
   issue: IssueContext,
   worktreePath: string,
-  opts?: { attempt?: number; gaps?: string[]; pluginConfig?: Record<string, unknown> },
+  opts?: { attempt?: number; gaps?: string[]; pluginConfig?: Record<string, unknown>; guidance?: string },
 ): { system: string; task: string } {
   const prompts = loadPrompts(opts?.pluginConfig, worktreePath);
   const vars: Record<string, string> = {
@@ -202,6 +203,9 @@ export function buildWorkerTask(
     tier: "",
     attempt: String(opts?.attempt ?? 0),
     gaps: opts?.gaps?.length ? "- " + opts.gaps.join("\n- ") : "",
+    guidance: opts?.guidance
+      ? `\n---\n## Additional Guidance (from Linear workspace/team settings)\n${opts.guidance.slice(0, 2000)}\n---`
+      : "",
   };
 
   let task = renderTemplate(prompts.worker.task, vars);
@@ -222,6 +226,7 @@ export function buildAuditTask(
   issue: IssueContext,
   worktreePath: string,
   pluginConfig?: Record<string, unknown>,
+  opts?: { guidance?: string },
 ): { system: string; task: string } {
   const prompts = loadPrompts(pluginConfig, worktreePath);
   const vars: Record<string, string> = {
@@ -232,6 +237,9 @@ export function buildAuditTask(
     tier: "",
     attempt: "0",
     gaps: "",
+    guidance: opts?.guidance
+      ? `\n---\n## Additional Guidance (from Linear workspace/team settings)\n${opts.guidance.slice(0, 2000)}\n---`
+      : "",
   };
 
   return {
@@ -350,7 +358,13 @@ export async function triggerAudit(
     ? dispatch.worktrees.map(w => `${w.repoName}: ${w.path}`).join("\n")
     : dispatch.worktreePath;
 
-  const auditPrompt = buildAuditTask(issue, effectiveAuditPath, pluginConfig);
+  // Look up cached guidance for audit
+  const auditTeamId = issueDetails?.team?.id;
+  const auditGuidance = (auditTeamId && isGuidanceEnabled(pluginConfig, auditTeamId))
+    ? getCachedGuidanceForTeam(auditTeamId) ?? undefined
+    : undefined;
+
+  const auditPrompt = buildAuditTask(issue, effectiveAuditPath, pluginConfig, { guidance: auditGuidance });
 
   // Set Linear label
   await linearApi.emitActivity(dispatch.agentSessionId ?? "", {
@@ -744,10 +758,17 @@ export async function spawnWorker(
     ? dispatch.worktrees.map(w => `${w.repoName}: ${w.path}`).join("\n")
     : dispatch.worktreePath;
 
+  // Look up cached guidance for the issue's team
+  const workerTeamId = issueDetails?.team?.id;
+  const workerGuidance = (workerTeamId && isGuidanceEnabled(pluginConfig, workerTeamId))
+    ? getCachedGuidanceForTeam(workerTeamId) ?? undefined
+    : undefined;
+
   const workerPrompt = buildWorkerTask(issue, effectiveWorkerPath, {
     attempt: dispatch.attempt,
     gaps: opts?.gaps,
     pluginConfig,
+    guidance: workerGuidance,
   });
 
   const workerSessionId = `linear-worker-${dispatch.issueIdentifier}-${dispatch.attempt}`;