@calltelemetry/openclaw-linear 0.8.7 → 0.9.0

package/src/infra/validation.ts

@@ -0,0 +1,52 @@
+/**
+ * validation.ts — Shared validation utilities for Linear IDs and prompt text.
+ *
+ * Used by linear-issues-tool.ts to validate input before making API calls,
+ * and by pipeline components to sanitize text before embedding in prompts.
+ */
+
+// ---------------------------------------------------------------------------
+// UUID validation
+// ---------------------------------------------------------------------------
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isValidUuid(id: string): boolean {
+  return UUID_REGEX.test(id);
+}
+
+// ---------------------------------------------------------------------------
+// Linear issue ID validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Linear issue IDs are either short identifiers like "ENG-123" or UUIDs.
+ */
+const ISSUE_ID_REGEX = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+
+export function isValidIssueId(id: string): boolean {
+  return ISSUE_ID_REGEX.test(id) || isValidUuid(id);
+}
+
+// ---------------------------------------------------------------------------
+// Team ID validation
+// ---------------------------------------------------------------------------
+
+export function isValidTeamId(id: string): boolean {
+  return isValidUuid(id);
+}
+
+// ---------------------------------------------------------------------------
+// Prompt sanitization
+// ---------------------------------------------------------------------------
+
+/**
+ * Sanitize text before embedding in agent prompts.
+ * Truncates to prevent token budget abuse and escapes template patterns
+ * so user-supplied text cannot inject {{variable}} placeholders.
+ */
+export function sanitizeForPrompt(text: string, maxLength = 4000): string {
+  return text
+    .replace(/\{\{.*?\}\}/g, "{ {escaped} }")
+    .slice(0, maxLength);
+}

package/src/pipeline/active-session.test.ts

@@ -110,7 +110,7 @@ describe("hydrateFromDispatchState", () => {
             issueIdentifier: "API-300",
             worktreePath: "/tmp/wt/API-300",
             branch: "codex/API-300",
-            tier: "junior",
+            tier: "small",
             model: "test",
             status: "working",
             dispatchedAt: "2026-01-01T00:00:00Z",
@@ -121,7 +121,7 @@ describe("hydrateFromDispatchState", () => {
             issueIdentifier: "API-301",
             worktreePath: "/tmp/wt/API-301",
             branch: "codex/API-301",
-            tier: "junior",
+            tier: "small",
             model: "test",
             status: "done",
             dispatchedAt: "2026-01-01T00:00:00Z",

package/src/pipeline/agent-end-hook.test.ts

@@ -0,0 +1,305 @@
+/**
+ * agent-end-hook.test.ts — Tests for the agent_end hook escalation behavior.
+ *
+ * Verifies that when triggerAudit or processVerdict throws, the hook:
+ * 1. Marks the dispatch as "stuck" via transitionDispatch
+ * 2. Sends an escalation notification
+ * 3. Does not crash if escalation itself fails
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Mocks (vi.hoisted to ensure they're available before vi.mock)
+// ---------------------------------------------------------------------------
+
+const { triggerAuditMock, processVerdictMock } = vi.hoisted(() => ({
+  triggerAuditMock: vi.fn(),
+  processVerdictMock: vi.fn(),
+}));
+
+vi.mock("./pipeline.js", () => ({
+  triggerAudit: triggerAuditMock,
+  processVerdict: processVerdictMock,
+}));
+
+vi.mock("../api/linear-api.js", () => ({
+  LinearAgentApi: class {},
+  resolveLinearToken: vi.fn().mockReturnValue({
+    accessToken: "test-token",
+    source: "env",
+    refreshToken: "refresh",
+    expiresAt: Date.now() + 3600_000,
+  }),
+}));
+
+vi.mock("../infra/notify.js", () => ({
+  createNotifierFromConfig: vi.fn(() => vi.fn().mockResolvedValue(undefined)),
+}));
+
+vi.mock("../infra/observability.js", () => ({
+  emitDiagnostic: vi.fn(),
+}));
+
+vi.mock("openclaw/plugin-sdk", () => ({}));
+
+// ---------------------------------------------------------------------------
+// Imports (AFTER mocks)
+// ---------------------------------------------------------------------------
+
+import {
+  registerDispatch,
+  readDispatchState,
+  getActiveDispatch,
+  registerSessionMapping,
+  transitionDispatch,
+  type ActiveDispatch,
+} from "./dispatch-state.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function tmpStatePath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "claw-agent-end-"));
+  return join(dir, "state.json");
+}
+
+function makeDispatch(overrides?: Partial<ActiveDispatch>): ActiveDispatch {
+  return {
+    issueId: "uuid-1",
+    issueIdentifier: "API-100",
+    issueTitle: "Fix the thing",
+    worktreePath: "/tmp/wt/API-100",
+    branch: "codex/API-100",
+    tier: "small",
+    model: "test-model",
+    status: "working",
+    dispatchedAt: new Date().toISOString(),
+    attempt: 0,
+    ...overrides,
+  };
+}
+
+/**
+ * Simulate the agent_end hook's catch-block escalation logic.
+ *
+ * This extracts the escalation path from index.ts so we can test it
+ * in isolation without bootstrapping the entire plugin registration.
+ */
+async function simulateAgentEndEscalation(opts: {
+  statePath: string;
+  sessionKey: string;
+  error: Error;
+  notify: ReturnType<typeof vi.fn>;
+  logger: {
+    info: ReturnType<typeof vi.fn>;
+    warn: ReturnType<typeof vi.fn>;
+    error: ReturnType<typeof vi.fn>;
+  };
+}): Promise<void> {
+  const { statePath, sessionKey, error, notify, logger } = opts;
+
+  // This mirrors the catch block in index.ts agent_end hook
+  logger.error(`agent_end hook error: ${error}`);
+  try {
+    const state = await readDispatchState(statePath);
+    const { lookupSessionMapping } = await import("./dispatch-state.js");
+    const mapping = sessionKey ? lookupSessionMapping(state, sessionKey) : null;
+    if (mapping) {
+      const dispatch = getActiveDispatch(state, mapping.dispatchId);
+      if (dispatch && dispatch.status !== "done" && dispatch.status !== "stuck" && dispatch.status !== "failed") {
+        const stuckReason = `Hook error: ${error instanceof Error ? error.message : String(error)}`.slice(0, 500);
+        await transitionDispatch(
+          mapping.dispatchId,
+          dispatch.status as any,
+          "stuck",
+          { stuckReason },
+          statePath,
+        );
+        await notify("escalation", {
+          identifier: dispatch.issueIdentifier,
+          title: dispatch.issueTitle ?? "Unknown",
+          status: "stuck",
+          reason: `Dispatch failed in ${mapping.phase} phase: ${stuckReason}`,
+        }).catch(() => {});
+      }
+    }
+  } catch (escalateErr) {
+    logger.error(`agent_end escalation also failed: ${escalateErr}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("agent_end hook escalation", () => {
+  let statePath: string;
+  let notifyMock: ReturnType<typeof vi.fn>;
+  let logger: { info: ReturnType<typeof vi.fn>; warn: ReturnType<typeof vi.fn>; error: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    statePath = tmpStatePath();
+    notifyMock = vi.fn().mockResolvedValue(undefined);
+    logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+    vi.clearAllMocks();
+  });
+
+  it("marks dispatch as stuck when audit throws", async () => {
+    // Setup: register a dispatch in "working" status with a session mapping
+    await registerDispatch("API-100", makeDispatch({ status: "working" }), statePath);
+    await registerSessionMapping("sess-worker-1", {
+      dispatchId: "API-100",
+      phase: "worker",
+      attempt: 0,
+    }, statePath);
+
+    // Simulate the hook error
+    await simulateAgentEndEscalation({
+      statePath,
+      sessionKey: "sess-worker-1",
+      error: new Error("triggerAudit exploded"),
+      notify: notifyMock,
+      logger,
+    });
+
+    // Verify: dispatch should now be "stuck"
+    const state = await readDispatchState(statePath);
+    const dispatch = getActiveDispatch(state, "API-100");
+    expect(dispatch).not.toBeNull();
+    expect(dispatch!.status).toBe("stuck");
+    expect(dispatch!.stuckReason).toBe("Hook error: triggerAudit exploded");
+  });
+
+  it("sends escalation notification with correct payload", async () => {
+    await registerDispatch("API-200", makeDispatch({
+      issueIdentifier: "API-200",
+      issueTitle: "Auth regression",
+      status: "auditing",
+    }), statePath);
+    await registerSessionMapping("sess-audit-1", {
+      dispatchId: "API-200",
+      phase: "audit",
+      attempt: 0,
+    }, statePath);
+
+    await simulateAgentEndEscalation({
+      statePath,
+      sessionKey: "sess-audit-1",
+      error: new Error("processVerdict failed"),
+      notify: notifyMock,
+      logger,
+    });
+
+    expect(notifyMock).toHaveBeenCalledWith("escalation", expect.objectContaining({
+      identifier: "API-200",
+      title: "Auth regression",
+      status: "stuck",
+      reason: expect.stringContaining("audit phase"),
+    }));
+  });
+
+  it("does not crash when escalation itself fails", async () => {
+    await registerDispatch("API-300", makeDispatch({
+      issueIdentifier: "API-300",
+      status: "working",
+    }), statePath);
+    await registerSessionMapping("sess-worker-2", {
+      dispatchId: "API-300",
+      phase: "worker",
+      attempt: 0,
+    }, statePath);
+
+    // Make notify throw
+    notifyMock.mockRejectedValueOnce(new Error("Discord is down"));
+
+    // Should not throw even though notify fails — the .catch(() => {}) eats it
+    await expect(
+      simulateAgentEndEscalation({
+        statePath,
+        sessionKey: "sess-worker-2",
+        error: new Error("worker failed"),
+        notify: notifyMock,
+        logger,
+      }),
+    ).resolves.not.toThrow();
+
+    // Dispatch should still be marked stuck
+    const state = await readDispatchState(statePath);
+    expect(getActiveDispatch(state, "API-300")!.status).toBe("stuck");
+  });
+
+  it("skips escalation for already-terminal dispatches", async () => {
+    await registerDispatch("API-400", makeDispatch({
+      issueIdentifier: "API-400",
+      status: "done",
+    }), statePath);
+    await registerSessionMapping("sess-done", {
+      dispatchId: "API-400",
+      phase: "worker",
+      attempt: 0,
+    }, statePath);
+
+    await simulateAgentEndEscalation({
+      statePath,
+      sessionKey: "sess-done",
+      error: new Error("late error"),
+      notify: notifyMock,
+      logger,
+    });
+
+    // Notify should NOT have been called (dispatch is already terminal)
+    expect(notifyMock).not.toHaveBeenCalled();
+
+    // Status should still be "done" (unchanged)
+    const state = await readDispatchState(statePath);
+    expect(getActiveDispatch(state, "API-400")!.status).toBe("done");
+  });
+
+  it("skips escalation when no session mapping found", async () => {
+    await simulateAgentEndEscalation({
+      statePath,
+      sessionKey: "unknown-session-key",
+      error: new Error("some error"),
+      notify: notifyMock,
+      logger,
+    });
+
+    // Only the initial error log, no escalation error
+    expect(notifyMock).not.toHaveBeenCalled();
+    expect(logger.error).toHaveBeenCalledTimes(1); // Just the initial error
+  });
+
+  it("truncates long error messages to 500 chars", async () => {
+    await registerDispatch("API-500", makeDispatch({
+      issueIdentifier: "API-500",
+      status: "working",
+    }), statePath);
+    await registerSessionMapping("sess-long", {
+      dispatchId: "API-500",
+      phase: "worker",
+      attempt: 0,
+    }, statePath);
+
+    const longMessage = "x".repeat(1000);
+    await simulateAgentEndEscalation({
+      statePath,
+      sessionKey: "sess-long",
+      error: new Error(longMessage),
+      notify: notifyMock,
+      logger,
+    });
+
+    const state = await readDispatchState(statePath);
+    const dispatch = getActiveDispatch(state, "API-500")!;
+    expect(dispatch.stuckReason!.length).toBeLessThanOrEqual(500);
+    expect(dispatch.stuckReason).toContain("Hook error:");
+  });
+});

package/src/pipeline/artifacts.test.ts

@@ -33,7 +33,7 @@ function makeManifest(overrides?: Partial<ClawManifest>): ClawManifest {
     issueIdentifier: "API-100",
     issueTitle: "Fix login bug",
     issueId: "id-123",
-    tier: "junior",
+    tier: "small",
     model: "test-model",
     dispatchedAt: "2026-01-01T00:00:00Z",
     worktreePath: "/tmp/test",
@@ -359,7 +359,7 @@ describe("writeDispatchMemory", () => {
     const tmp = makeTmpDir();
     writeDispatchMemory("CT-50", "done summary", tmp, {
       title: "Fix login bug",
-      tier: "senior",
+      tier: "high",
       status: "done",
       project: "Auth",
       attempts: 2,
@@ -367,7 +367,7 @@ describe("writeDispatchMemory", () => {
     });
     const content = readFileSync(join(tmp, "memory", "dispatch-CT-50.md"), "utf-8");
     expect(content).toContain('title: "Fix login bug"');
-    expect(content).toContain('tier: "senior"');
+    expect(content).toContain('tier: "high"');
     expect(content).toContain('status: "done"');
     expect(content).toContain('project: "Auth"');
     expect(content).toContain("attempts: 2");

package/src/pipeline/dispatch-state.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, writeFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
@@ -17,6 +17,7 @@ import {
   removeSessionMapping,
   markEventProcessed,
   pruneCompleted,
+  pruneCompletedDispatches,
   removeActiveDispatch,
   TransitionError,
   type ActiveDispatch,
@@ -33,7 +34,7 @@ function makeDispatch(overrides?: Partial<ActiveDispatch>): ActiveDispatch {
     issueIdentifier: "API-100",
     worktreePath: "/tmp/wt/API-100",
     branch: "codex/API-100",
-    tier: "junior",
+    tier: "small",
     model: "test-model",
     status: "dispatched",
     dispatchedAt: new Date().toISOString(),
@@ -50,11 +51,29 @@ describe("readDispatchState", () => {
   it("returns empty state when file missing", async () => {
     const p = tmpStatePath();
     const state = await readDispatchState(p);
+    expect(state.version).toBe(2);
     expect(state.dispatches.active).toEqual({});
     expect(state.dispatches.completed).toEqual({});
     expect(state.sessionMap).toEqual({});
     expect(state.processedEvents).toEqual([]);
   });
+
+  it("recovers from corrupted state file", async () => {
+    const p = tmpStatePath();
+    // Write invalid JSON
+    writeFileSync(p, "{{{{not valid json!!!!", "utf-8");
+    const state = await readDispatchState(p);
+    expect(state.version).toBe(2);
+    expect(state.dispatches.active).toEqual({});
+    expect(state.dispatches.completed).toEqual({});
+    expect(state.sessionMap).toEqual({});
+    expect(state.processedEvents).toEqual([]);
+    // Corrupted file should have been renamed
+    const dir = join(p, "..");
+    const files = readdirSync(dir);
+    const corrupted = files.filter((f: string) => f.includes(".corrupted."));
+    expect(corrupted.length).toBe(1);
+  });
 });
 
 describe("registerDispatch", () => {
@@ -223,7 +242,7 @@ describe("completeDispatch", () => {
     const p = tmpStatePath();
     await registerDispatch("API-100", makeDispatch(), p);
     await completeDispatch("API-100", {
-      tier: "junior",
+      tier: "small",
       status: "done",
       completedAt: new Date().toISOString(),
     }, p);
@@ -239,7 +258,7 @@ describe("completeDispatch", () => {
     await registerSessionMapping("sess-w", { dispatchId: "API-100", phase: "worker", attempt: 0 }, p);
     await registerSessionMapping("sess-a", { dispatchId: "API-100", phase: "audit", attempt: 0 }, p);
     await completeDispatch("API-100", {
-      tier: "junior",
+      tier: "small",
       status: "done",
       completedAt: new Date().toISOString(),
     }, p);
@@ -311,7 +330,7 @@ describe("pruneCompleted", () => {
     const p = tmpStatePath();
     await registerDispatch("DONE-1", makeDispatch({ issueIdentifier: "DONE-1" }), p);
     await completeDispatch("DONE-1", {
-      tier: "junior",
+      tier: "small",
       status: "done",
       completedAt: new Date(Date.now() - 2 * 24 * 60 * 60_000).toISOString(), // 2 days ago
     }, p);
@@ -323,7 +342,7 @@ describe("pruneCompleted", () => {
     const p = tmpStatePath();
     await registerDispatch("DONE-2", makeDispatch({ issueIdentifier: "DONE-2" }), p);
     await completeDispatch("DONE-2", {
-      tier: "junior",
+      tier: "small",
       status: "done",
       completedAt: new Date().toISOString(),
     }, p);
@@ -337,9 +356,9 @@ describe("pruneCompleted", () => {
 // ---------------------------------------------------------------------------
 
 describe("migration", () => {
-  it("adds missing sessionMap and processedEvents", async () => {
+  it("migrates v1 state to v2 (adds version, sessionMap, processedEvents)", async () => {
     const p = tmpStatePath();
-    // Write v1 state with no v2 fields
+    // Write v1 state with no v2 fields (no version field)
     writeFileSync(p, JSON.stringify({
       dispatches: {
         active: { "X-1": makeDispatch({ issueIdentifier: "X-1" }) },
@@ -347,6 +366,7 @@ describe("migration", () => {
       },
     }), "utf-8");
     const state = await readDispatchState(p);
+    expect(state.version).toBe(2);
     expect(state.sessionMap).toEqual({});
     expect(state.processedEvents).toEqual([]);
   });
@@ -361,8 +381,35 @@ describe("migration", () => {
       processedEvents: [],
     }), "utf-8");
     const state = await readDispatchState(p);
+    expect(state.version).toBe(2);
     expect(getActiveDispatch(state, "X-2")!.status).toBe("working");
   });
+
+  it("rejects unknown version", async () => {
+    const p = tmpStatePath();
+    writeFileSync(p, JSON.stringify({
+      version: 99,
+      dispatches: { active: {}, completed: {} },
+      sessionMap: {},
+      processedEvents: [],
+    }), "utf-8");
+    await expect(readDispatchState(p)).rejects.toThrow("Unknown dispatch state version: 99");
+  });
+
+  it("passes through v2 state unchanged", async () => {
+    const p = tmpStatePath();
+    const d = makeDispatch({ issueIdentifier: "X-3" });
+    writeFileSync(p, JSON.stringify({
+      version: 2,
+      dispatches: { active: { "X-3": d }, completed: {} },
+      sessionMap: {},
+      processedEvents: ["evt-old"],
+    }), "utf-8");
+    const state = await readDispatchState(p);
+    expect(state.version).toBe(2);
+    expect(getActiveDispatch(state, "X-3")).not.toBeNull();
+    expect(state.processedEvents).toEqual(["evt-old"]);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -380,3 +427,59 @@ describe("removeActiveDispatch", () => {
     expect(lookupSessionMapping(state, "sess-rm")).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// pruneCompletedDispatches (convenience wrapper)
+// ---------------------------------------------------------------------------
+
+describe("pruneCompletedDispatches", () => {
+  it("prunes old completed dispatches", async () => {
+    const p = tmpStatePath();
+    // Create and complete a dispatch with a timestamp 10 days ago
+    await registerDispatch("OLD-GC", makeDispatch({ issueIdentifier: "OLD-GC" }), p);
+    await completeDispatch("OLD-GC", {
+      tier: "small",
+      status: "done",
+      completedAt: new Date(Date.now() - 10 * 24 * 60 * 60_000).toISOString(), // 10 days ago
+    }, p);
+    // Also add a recent completed dispatch
+    await registerDispatch("NEW-GC", makeDispatch({ issueIdentifier: "NEW-GC" }), p);
+    await completeDispatch("NEW-GC", {
+      tier: "high",
+      status: "done",
+      completedAt: new Date().toISOString(), // now
+    }, p);
+
+    // Prune with 7-day default
+    const pruned = await pruneCompletedDispatches(7 * 24 * 60 * 60_000, p);
+    expect(pruned).toBe(1);
+
+    // Verify old one gone, recent one survives
+    const state = await readDispatchState(p);
+    expect(state.dispatches.completed["OLD-GC"]).toBeUndefined();
+    expect(state.dispatches.completed["NEW-GC"]).toBeDefined();
+  });
+
+  it("preserves recent completed dispatches", async () => {
+    const p = tmpStatePath();
+    await registerDispatch("FRESH-1", makeDispatch({ issueIdentifier: "FRESH-1" }), p);
+    await completeDispatch("FRESH-1", {
+      tier: "small",
+      status: "done",
+      completedAt: new Date().toISOString(),
+    }, p);
+    await registerDispatch("FRESH-2", makeDispatch({ issueIdentifier: "FRESH-2" }), p);
+    await completeDispatch("FRESH-2", {
+      tier: "medium",
+      status: "failed",
+      completedAt: new Date(Date.now() - 3 * 24 * 60 * 60_000).toISOString(), // 3 days ago
+    }, p);
+
+    const pruned = await pruneCompletedDispatches(7 * 24 * 60 * 60_000, p);
+    expect(pruned).toBe(0);
+
+    const state = await readDispatchState(p);
+    expect(state.dispatches.completed["FRESH-1"]).toBeDefined();
+    expect(state.dispatches.completed["FRESH-2"]).toBeDefined();
+  });
+});