@calltelemetry/openclaw-linear 0.7.1 → 0.8.0

package/index.ts

@@ -96,7 +96,7 @@ export default function register(api: OpenClawPluginApi) {
   // ---------------------------------------------------------------------------
 
   // Instantiate notifier (Discord, Slack, or both — config-driven)
-  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime);
+  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime, api);
 
   // Register agent_end hook — safety net for sessions_spawn sub-agents.
   // In the current implementation, the worker→audit→verdict flow runs inline

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-linear",
   "name": "Linear Agent",
   "description": "Linear integration with OAuth support, agent pipeline, and webhook-driven AI agent lifecycle",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

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

package/prompts.yaml

@@ -28,10 +28,13 @@ worker:
 
     Instructions:
     1. Read the issue body carefully — it defines what needs to be done
-    2. Plan your approach
-    3. Implement the solution in the worktree
-    4. Run tests to verify your changes
-    5. Return a text summary of what you changed, what tests you ran, and any notes
+    2. If the description is vague or missing, implement a reasonable interpretation and note your assumptions
+    3. Plan your approach
+    4. Implement the solution in the worktree
+    5. Run tests to verify your changes
+    6. If tests fail, diagnose and fix the failures before returning — do not return with failing tests unless you've exhausted your ability to fix them
+    7. Commit your work with a clear commit message
+    8. Return a text summary: what you changed, what tests passed, any assumptions you made, and any open questions
 
     Your text output will be captured automatically. Do NOT use linearis or attempt to post comments.
 
@@ -67,6 +70,9 @@ audit:
     - Post your audit findings as a comment: `linearis comments create {{identifier}} --body "..."`
     - If PASS: update status: `linearis issues update {{identifier}} --status "Done"`
 
+    When posting your audit comment, include a brief assessment: what was done well,
+    what the gaps are (if any), and what the user should look at next.
+
     You MUST return a JSON verdict as the last line of your response:
     {"pass": true/false, "criteria": ["list of criteria found"], "gaps": ["list of unmet criteria"], "testResults": "summary of test output"}
 
@@ -75,7 +81,8 @@ rework:
     PREVIOUS AUDIT FAILED (attempt {{attempt}}). The auditor found these gaps:
     {{gaps}}
 
-    Address these specific issues in your rework. Focus on the gaps listed above.
+    Address these specific issues in your rework. Focus ONLY on the gaps listed above.
+    Do NOT undo or rewrite parts that already work — preserve correct code from prior attempts.
     Remember: you do NOT have linearis access. Just fix the code and return a text summary.
 
 planner:
@@ -97,6 +104,8 @@ planner:
     - After each user response, create or update issues to capture what you learned.
     - Briefly summarize what you added before asking your next question.
     - When the plan feels complete, invite the user to say "finalize plan".
+    - If the user is vague ("make it better", "you decide"), propose concrete options and ask them to pick.
+    - If you've gathered enough info after several turns with no new details, suggest: "This looks ready — say **finalize plan** when you're happy with it."
 
   interview: |
     ## Project: {{projectName}} ({{rootIdentifier}})
@@ -123,4 +132,9 @@ planner:
     features you want to build, then structure everything into Linear issues with proper
     epic hierarchy and dependency chains.
 
+    **How this works:**
+    - I'll ask questions one at a time and create issues as we go
+    - When you're happy with the plan, say **"finalize plan"** — I'll validate it and start dispatching
+    - If you want to stop, say **"abandon planning"**
+
     Let's start — what is this project about, and what are the main feature areas?

package/src/__test__/fixtures/linear-responses.ts

@@ -0,0 +1,75 @@
+/**
+ * Factory functions for Linear GraphQL response shapes.
+ *
+ * Matches the return types of LinearAgentApi methods.
+ */
+
+export function makeIssueDetails(overrides?: Record<string, unknown>) {
+  return {
+    id: "issue-1",
+    identifier: "ENG-123",
+    title: "Fix webhook routing",
+    description: "The webhook handler needs fixing.",
+    estimate: 3,
+    state: { name: "In Progress" },
+    assignee: { name: "Agent" },
+    labels: { nodes: [] as Array<{ id: string; name: string }> },
+    team: { id: "team-1", name: "Engineering", issueEstimationType: "notUsed" },
+    comments: { nodes: [] as Array<{ body: string; user: { name: string } | null; createdAt: string }> },
+    project: null as { id: string; name: string } | null,
+    parent: null as { id: string; identifier: string } | null,
+    relations: { nodes: [] as Array<{ type: string; relatedIssue: { id: string; identifier: string; title: string } }> },
+    ...overrides,
+  };
+}
+
+export function makeProjectIssue(
+  identifier: string,
+  opts?: {
+    title?: string;
+    description?: string;
+    estimate?: number;
+    priority?: number;
+    state?: { name: string; type: string };
+    parentIdentifier?: string;
+    labels?: string[];
+    relations?: Array<{ type: string; relatedIdentifier: string; relatedTitle?: string }>;
+  },
+) {
+  return {
+    id: `id-${identifier}`,
+    identifier,
+    title: opts?.title ?? `Issue ${identifier}`,
+    description: opts?.description ?? null,
+    estimate: opts?.estimate ?? null,
+    priority: opts?.priority ?? 0,
+    state: opts?.state ?? { name: "Backlog", type: "backlog" },
+    parent: opts?.parentIdentifier
+      ? { id: `id-${opts.parentIdentifier}`, identifier: opts.parentIdentifier }
+      : null,
+    labels: {
+      nodes: (opts?.labels ?? []).map((name) => ({ id: `label-${name}`, name })),
+    },
+    relations: {
+      nodes: (opts?.relations ?? []).map((r) => ({
+        type: r.type,
+        relatedIssue: {
+          id: `id-${r.relatedIdentifier}`,
+          identifier: r.relatedIdentifier,
+          title: r.relatedTitle ?? `Issue ${r.relatedIdentifier}`,
+        },
+      })),
+    },
+  };
+}
+
+export function makeProject(overrides?: Record<string, unknown>) {
+  return {
+    id: "proj-1",
+    name: "Test Project",
+    description: "A test project",
+    state: "started",
+    teams: { nodes: [{ id: "team-1", name: "Engineering" }] },
+    ...overrides,
+  };
+}

package/src/__test__/fixtures/webhook-payloads.ts

@@ -0,0 +1,113 @@
+/**
+ * Factory functions for Linear webhook event payloads.
+ *
+ * Matches the shapes received at /linear/webhook from both
+ * workspace webhooks and OAuth app webhooks.
+ */
+
+export function makeAgentSessionCreated(overrides?: Record<string, unknown>) {
+  return {
+    type: "AgentSession",
+    action: "create",
+    data: {
+      id: "sess-1",
+      context: { commentBody: "Please investigate this issue" },
+    },
+    issue: {
+      id: "issue-1",
+      identifier: "ENG-123",
+      title: "Fix webhook routing",
+    },
+    ...overrides,
+  };
+}
+
+export function makeAgentSessionPrompted(overrides?: Record<string, unknown>) {
+  return {
+    type: "AgentSession",
+    action: "prompted",
+    data: {
+      id: "sess-prompted",
+      context: { prompt: "Looks good, approved!" },
+    },
+    issue: {
+      id: "issue-2",
+      identifier: "ENG-124",
+      title: "Approved issue",
+    },
+    ...overrides,
+  };
+}
+
+export function makeCommentCreate(overrides?: Record<string, unknown>) {
+  return {
+    type: "Comment",
+    action: "create",
+    data: {
+      id: "comment-1",
+      body: "This needs work",
+      user: { id: "user-1", name: "Test User" },
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+        team: { id: "team-1" },
+        assignee: { id: "viewer-1" },
+        project: null,
+      },
+      createdAt: new Date().toISOString(),
+    },
+    ...overrides,
+  };
+}
+
+export function makeIssueUpdate(overrides?: Record<string, unknown>) {
+  return {
+    type: "Issue",
+    action: "update",
+    data: {
+      id: "issue-1",
+      identifier: "ENG-123",
+      title: "Fix webhook routing",
+      state: { name: "In Progress", type: "started" },
+      assignee: { id: "viewer-1", name: "Agent" },
+      team: { id: "team-1" },
+      project: null,
+    },
+    ...overrides,
+  };
+}
+
+export function makeIssueCreate(overrides?: Record<string, unknown>) {
+  return {
+    type: "Issue",
+    action: "create",
+    data: {
+      id: "issue-new",
+      identifier: "ENG-200",
+      title: "New issue",
+      state: { name: "Backlog", type: "backlog" },
+      assignee: null,
+      team: { id: "team-1" },
+      project: null,
+    },
+    ...overrides,
+  };
+}
+
+export function makeAppUserNotification(overrides?: Record<string, unknown>) {
+  return {
+    type: "AppUserNotification",
+    action: "create",
+    data: {
+      type: "issueAssigned",
+      issue: {
+        id: "issue-1",
+        identifier: "ENG-123",
+        title: "Fix webhook routing",
+      },
+      user: { id: "user-1", name: "Test User" },
+    },
+    ...overrides,
+  };
+}

package/src/__test__/helpers.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared test helpers for E2E and integration tests.
+ *
+ * Provides reusable mock factories that consolidate patterns scattered across
+ * unit test files. Existing unit tests keep their local factories; new E2E
+ * tests use these from the start.
+ */
+import { vi } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { HookContext } from "../pipeline/pipeline.js";
+import type { NotifyFn } from "../infra/notify.js";
+
+// ---------------------------------------------------------------------------
+// Mock OpenClaw Plugin API
+// ---------------------------------------------------------------------------
+
+export function createMockApi(overrides?: Partial<{
+  logger: Partial<OpenClawPluginApi["logger"]>;
+  pluginConfig: Record<string, unknown>;
+  runtime: Record<string, unknown>;
+}>): OpenClawPluginApi {
+  return {
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+      ...overrides?.logger,
+    },
+    pluginConfig: overrides?.pluginConfig ?? {},
+    runtime: {
+      channel: {
+        discord: { sendMessageDiscord: vi.fn().mockResolvedValue(undefined) },
+        slack: { sendMessageSlack: vi.fn().mockResolvedValue(undefined) },
+        telegram: { sendMessageTelegram: vi.fn().mockResolvedValue(undefined) },
+        signal: { sendMessageSignal: vi.fn().mockResolvedValue(undefined) },
+      },
+      ...overrides?.runtime,
+    },
+  } as unknown as OpenClawPluginApi;
+}
+
+// ---------------------------------------------------------------------------
+// Mock Linear API
+// ---------------------------------------------------------------------------
+
+export interface MockLinearApi {
+  getIssueDetails: ReturnType<typeof vi.fn>;
+  createComment: ReturnType<typeof vi.fn>;
+  emitActivity: ReturnType<typeof vi.fn>;
+  updateSession: ReturnType<typeof vi.fn>;
+  getProject: ReturnType<typeof vi.fn>;
+  getProjectIssues: ReturnType<typeof vi.fn>;
+  getTeamStates: ReturnType<typeof vi.fn>;
+  getTeamLabels: ReturnType<typeof vi.fn>;
+  createIssue: ReturnType<typeof vi.fn>;
+  updateIssue: ReturnType<typeof vi.fn>;
+  updateIssueExtended: ReturnType<typeof vi.fn>;
+  createIssueRelation: ReturnType<typeof vi.fn>;
+  getViewerId: ReturnType<typeof vi.fn>;
+}
+
+export function createMockLinearApi(overrides?: Partial<MockLinearApi>): MockLinearApi {
+  return {
+    getIssueDetails: vi.fn().mockResolvedValue(null),
+    createComment: vi.fn().mockResolvedValue("comment-id"),
+    emitActivity: vi.fn().mockResolvedValue(undefined),
+    updateSession: vi.fn().mockResolvedValue(undefined),
+    getProject: vi.fn().mockResolvedValue({
+      id: "proj-1",
+      name: "Test Project",
+      description: "",
+      state: "started",
+      teams: { nodes: [{ id: "team-1", name: "Team" }] },
+    }),
+    getProjectIssues: vi.fn().mockResolvedValue([]),
+    getTeamStates: vi.fn().mockResolvedValue([
+      { id: "st-1", name: "Backlog", type: "backlog" },
+      { id: "st-2", name: "In Progress", type: "started" },
+      { id: "st-3", name: "Done", type: "completed" },
+    ]),
+    getTeamLabels: vi.fn().mockResolvedValue([]),
+    createIssue: vi.fn().mockResolvedValue({ id: "new-issue-id", identifier: "PROJ-NEW" }),
+    updateIssue: vi.fn().mockResolvedValue(undefined),
+    updateIssueExtended: vi.fn().mockResolvedValue(undefined),
+    createIssueRelation: vi.fn().mockResolvedValue(undefined),
+    getViewerId: vi.fn().mockResolvedValue("viewer-1"),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mock HookContext
+// ---------------------------------------------------------------------------
+
+export function createMockHookCtx(opts: {
+  configPath?: string;
+  planningStatePath?: string;
+  pluginConfig?: Record<string, unknown>;
+  linearApi?: MockLinearApi;
+  notify?: NotifyFn;
+}): HookContext {
+  const configPath = opts.configPath ?? tmpStatePath("claw-hook-");
+  return {
+    api: createMockApi({
+      pluginConfig: {
+        dispatchStatePath: configPath,
+        planningStatePath: opts.planningStatePath ?? configPath,
+        ...opts.pluginConfig,
+      },
+    }),
+    linearApi: (opts.linearApi ?? createMockLinearApi()) as any,
+    notify: opts.notify ?? vi.fn().mockResolvedValue(undefined),
+    pluginConfig: {
+      dispatchStatePath: configPath,
+      planningStatePath: opts.planningStatePath ?? configPath,
+      ...opts.pluginConfig,
+    },
+    configPath,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Temp path helper
+// ---------------------------------------------------------------------------
+
+export function tmpStatePath(prefix = "claw-test-"): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  return join(dir, "state.json");
+}

package/src/agent/agent.test.ts

@@ -61,6 +61,149 @@ function createApi(): OpenClawPluginApi {
   } as unknown as OpenClawPluginApi;
 }
 
+describe("runAgent subprocess", () => {
+  it("extracts text from JSON payloads", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: JSON.stringify({ result: { payloads: [{ text: "hello" }, { text: "world" }] } }),
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test-agent",
+      sessionId: "session-1",
+      message: "do something",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("hello");
+    expect(result.output).toContain("world");
+  });
+
+  it("uses raw stdout when JSON parsing fails", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: "plain text output",
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test-agent",
+      sessionId: "session-1",
+      message: "do something",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toBe("plain text output");
+  });
+
+  it("uses stderr when command fails with no stdout", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 1,
+      stdout: "",
+      stderr: "error from stderr",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test-agent",
+      sessionId: "session-1",
+      message: "do something",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.output).toContain("error from stderr");
+  });
+
+  it("includes agentId in command arguments", async () => {
+    const api = createApi();
+    const runCmd = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: "ok",
+      stderr: "",
+    });
+    (api.runtime.system as any).runCommandWithTimeout = runCmd;
+
+    await runAgent({
+      api,
+      agentId: "my-agent",
+      sessionId: "session-1",
+      message: "test",
+    });
+
+    const args = runCmd.mock.calls[0][0];
+    expect(args).toContain("my-agent");
+    expect(args).toContain("--agent");
+  });
+
+  it("passes timeout in seconds to subprocess", async () => {
+    const api = createApi();
+    const runCmd = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: "ok",
+      stderr: "",
+    });
+    (api.runtime.system as any).runCommandWithTimeout = runCmd;
+
+    await runAgent({
+      api,
+      agentId: "test",
+      sessionId: "session-1",
+      message: "test",
+      timeoutMs: 60_000,
+    });
+
+    const args: string[] = runCmd.mock.calls[0][0];
+    const timeoutIdx = args.indexOf("--timeout");
+    expect(timeoutIdx).toBeGreaterThan(-1);
+    expect(args[timeoutIdx + 1]).toBe("60");
+  });
+
+  it("handles empty payloads array", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: JSON.stringify({ result: { payloads: [] } }),
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test",
+      sessionId: "s1",
+      message: "test",
+    });
+
+    expect(result.success).toBe(true);
+    // Falls back to raw stdout when no payload text
+    expect(result.output).toBeTruthy();
+  });
+
+  it("handles null payloads text", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: JSON.stringify({ result: { payloads: [{ text: null }, { text: "real" }] } }),
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test",
+      sessionId: "s1",
+      message: "test",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toContain("real");
+  });
+});
+
 describe("runAgent retry wrapper", () => {
   it("returns success on first attempt when no watchdog kill", async () => {
     const api = createApi();

package/src/api/linear-api.test.ts

@@ -300,7 +300,7 @@ describe("LinearAgentApi", () => {
       });
 
       await expect(api.updateIssue("i1", { estimate: 1 })).rejects.toThrow(
-        /Linear API 403 \(after refresh\)/,
+        /Linear API authentication failed/,
       );
     });
   });
@@ -464,6 +464,98 @@ describe("LinearAgentApi", () => {
     });
   });
 
+  describe("getTeams", () => {
+    it("returns parsed team list", async () => {
+      fetchMock.mockResolvedValueOnce(
+        okResponse({
+          teams: {
+            nodes: [
+              { id: "t1", name: "Engineering", key: "ENG" },
+              { id: "t2", name: "Design", key: "DES" },
+            ],
+          },
+        }),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      const teams = await api.getTeams();
+      expect(teams).toHaveLength(2);
+      expect(teams[0]).toEqual({ id: "t1", name: "Engineering", key: "ENG" });
+      expect(teams[1]).toEqual({ id: "t2", name: "Design", key: "DES" });
+    });
+
+    it("handles empty teams list", async () => {
+      fetchMock.mockResolvedValueOnce(okResponse({ teams: { nodes: [] } }));
+
+      const api = new LinearAgentApi(TOKEN);
+      const teams = await api.getTeams();
+      expect(teams).toEqual([]);
+    });
+  });
+
+  describe("createLabel", () => {
+    it("sends correct mutation and returns label", async () => {
+      fetchMock.mockResolvedValueOnce(
+        okResponse({
+          issueLabelCreate: {
+            success: true,
+            issueLabel: { id: "label-1", name: "repo:api" },
+          },
+        }),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      const label = await api.createLabel("t1", "repo:api", {
+        color: "#5e6ad2",
+        description: "Multi-repo dispatch: api",
+      });
+
+      expect(label).toEqual({ id: "label-1", name: "repo:api" });
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.query).toContain("issueLabelCreate");
+      expect(body.variables.input).toEqual({
+        teamId: "t1",
+        name: "repo:api",
+        color: "#5e6ad2",
+        description: "Multi-repo dispatch: api",
+      });
+    });
+
+    it("throws on API failure", async () => {
+      fetchMock.mockResolvedValueOnce(
+        okResponse({
+          issueLabelCreate: { success: false, issueLabel: null },
+        }),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      await expect(
+        api.createLabel("t1", "repo:bad"),
+      ).rejects.toThrow(/Failed to create label/);
+    });
+
+    it("omits optional fields when not provided", async () => {
+      fetchMock.mockResolvedValueOnce(
+        okResponse({
+          issueLabelCreate: {
+            success: true,
+            issueLabel: { id: "label-2", name: "repo:frontend" },
+          },
+        }),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      await api.createLabel("t1", "repo:frontend");
+
+      const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+      expect(body.variables.input).toEqual({
+        teamId: "t1",
+        name: "repo:frontend",
+      });
+    });
+  });
+
   describe("createSessionOnIssue", () => {
     it("returns sessionId on success", async () => {
       fetchMock.mockResolvedValueOnce(