@calltelemetry/openclaw-linear 0.8.2 → 0.8.4

package/src/agent/agent.ts

@@ -68,6 +68,12 @@ export async function runAgent(params: {
   message: string;
   timeoutMs?: number;
   streaming?: AgentStreamCallbacks;
+  /**
+   * Read-only mode: agent keeps read tools (read, glob, grep, web_search,
+   * web_fetch) but all write-capable tools are denied via config policy.
+   * Subprocess fallback is blocked — only the embedded runner is safe.
+   */
+  readOnly?: boolean;
 }): Promise<AgentRunResult> {
   const maxAttempts = 2;
 
@@ -126,8 +132,9 @@ async function runAgentOnce(params: {
   message: string;
   timeoutMs?: number;
   streaming?: AgentStreamCallbacks;
+  readOnly?: boolean;
 }): Promise<AgentRunResult> {
-  const { api, agentId, sessionId, streaming } = params;
+  const { api, agentId, sessionId, streaming, readOnly } = params;
 
   // Inject current timestamp into every LLM request
   const message = `${buildDateContext()}\n\n${params.message}`;
@@ -136,24 +143,60 @@ async function runAgentOnce(params: {
   const wdConfig = resolveWatchdogConfig(agentId, pluginConfig);
   const timeoutMs = params.timeoutMs ?? wdConfig.maxTotalMs;
 
-  api.logger.info(`Dispatching agent ${agentId} for session ${sessionId} (timeout=${Math.round(timeoutMs / 1000)}s, inactivity=${Math.round(wdConfig.inactivityMs / 1000)}s)`);
+  api.logger.info(`Dispatching agent ${agentId} for session ${sessionId} (timeout=${Math.round(timeoutMs / 1000)}s, inactivity=${Math.round(wdConfig.inactivityMs / 1000)}s${readOnly ? ", mode=READ_ONLY" : ""})`);
 
   // Try embedded runner first (has streaming callbacks)
   if (streaming) {
     try {
-      return await runEmbedded(api, agentId, sessionId, message, timeoutMs, streaming, wdConfig.inactivityMs);
+      return await runEmbedded(api, agentId, sessionId, message, timeoutMs, streaming, wdConfig.inactivityMs, readOnly);
     } catch (err) {
+      // Read-only mode MUST NOT fall back to subprocess — subprocess runs a
+      // full agent with no way to enforce the tool deny policy.
+      if (readOnly) {
+        api.logger.error(`Embedded runner failed in read-only mode, refusing subprocess fallback: ${err}`);
+        return { success: false, output: "Read-only agent run failed (embedded runner unavailable)." };
+      }
       api.logger.warn(`Embedded runner failed, falling back to subprocess: ${err}`);
     }
   }
 
   // Fallback: subprocess (no streaming)
+  if (readOnly) {
+    api.logger.error("Cannot run read-only agent via subprocess — no tool policy enforcement");
+    return { success: false, output: "Read-only agent run requires the embedded runner." };
+  }
   return runSubprocess(api, agentId, sessionId, message, timeoutMs);
 }
 
 /**
  * Embedded agent runner with real-time streaming to Linear and inactivity watchdog.
  */
+// Tools denied in read-only mode.  Uses OpenClaw group:* shorthands where
+// possible (see https://docs.openclaw.ai/tools).  Covers every built-in
+// tool that can mutate the filesystem, execute commands, or produce
+// side-effects beyond the Linear API calls the plugin makes after the run.
+//
+// NOT denied (read-only tools the triage agent keeps):
+//   read, glob, grep/search          — codebase inspection
+//   group:web (web_search, web_fetch) — external context
+//   group:memory (memory_search/get)  — knowledge retrieval
+//   sessions_list, sessions_history   — read-only introspection
+const READ_ONLY_DENY: string[] = [
+  // group:fs = read + write + edit + apply_patch — but we need read,
+  // so deny the write-capable members individually.
+  "write", "edit", "apply_patch",
+  // Full groups that are entirely write/side-effect oriented:
+  "group:runtime",                          // exec, bash, process
+  "group:messaging",                        // message
+  "group:ui",                               // browser, canvas
+  "group:automation",                       // cron, gateway
+  "group:nodes",                            // nodes
+  // Individual tools not covered by a group:
+  "sessions_spawn", "sessions_send",        // agent orchestration
+  "tts",                                    // audio file generation
+  "image",                                  // image file generation
+];
+
 async function runEmbedded(
   api: OpenClawPluginApi,
   agentId: string,
@@ -162,12 +205,26 @@ async function runEmbedded(
   timeoutMs: number,
   streaming: AgentStreamCallbacks,
   inactivityMs: number,
+  readOnly?: boolean,
 ): Promise<AgentRunResult> {
   const ext = await getExtensionAPI();
 
   // Load config so we can resolve agent dirs and providers correctly.
-  const config = await api.runtime.config.loadConfig();
-  const configAny = config as Record<string, any>;
+  let config = await api.runtime.config.loadConfig();
+  let configAny = config as Record<string, any>;
+
+  // ── Read-only enforcement ──────────────────────────────────────────
+  // Clone the config and inject a tools.deny policy that strips every
+  // write-capable tool.  The deny list is merged with any existing deny
+  // entries so we don't clobber operator-level restrictions.
+  if (readOnly) {
+    configAny = JSON.parse(JSON.stringify(configAny));
+    config = configAny as typeof config;
+    if (!configAny.tools) configAny.tools = {};
+    const existing: string[] = Array.isArray(configAny.tools.deny) ? configAny.tools.deny : [];
+    configAny.tools.deny = [...new Set([...existing, ...READ_ONLY_DENY])];
+    api.logger.info(`Read-only mode: tools.deny = [${configAny.tools.deny.join(", ")}]`);
+  }
 
   // Resolve workspace and agent dirs from config (ext API ignores agentId).
   const dirs = resolveAgentDirs(agentId, configAny);
@@ -233,6 +290,13 @@ async function runEmbedded(
     abortSignal: controller.signal,
     shouldEmitToolResult: () => true,
     shouldEmitToolOutput: () => true,
+    ...(readOnly ? {
+      extraSystemPrompt: [
+        "READ-ONLY MODE: You may read and search files but you MUST NOT",
+        "write, edit, create, or delete any files. Do not run shell commands.",
+        "Your only output is your text response.",
+      ].join(" "),
+    } : {}),
 
     // Stream reasoning/thinking to Linear
     onReasoningStream: (payload) => {

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

@@ -232,6 +232,43 @@ describe("LinearAgentApi", () => {
       );
     });
 
+    it("returns data when GraphQL errors and data coexist (partial success)", async () => {
+      // Simulates createAsUser returning warnings alongside valid comment data.
+      // This is the root cause of Bug 2 in API-477: gql() used to throw on
+      // any errors, even when the mutation succeeded and data was present.
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({
+            data: {
+              commentCreate: { success: true, comment: { id: "c-partial" } },
+            },
+            errors: [{ message: "createAsUser: user not found, using default" }],
+          }),
+        text: () => Promise.resolve(""),
+        headers: new Headers(),
+      } as unknown as Response);
+
+      const api = new LinearAgentApi(TOKEN);
+      const id = await api.createComment("issue-1", "test body", {
+        createAsUser: "NonexistentUser",
+      });
+
+      expect(id).toBe("c-partial");
+    });
+
+    it("still throws on GraphQL errors when no data is present", async () => {
+      fetchMock.mockResolvedValueOnce(
+        gqlErrorResponse([{ message: "Totally broken" }]),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      await expect(
+        api.createComment("issue-1", "test body"),
+      ).rejects.toThrow(/Linear GraphQL/);
+    });
+
     it("retries on 401 when refresh token is available", async () => {
       // First call (via withResilience): 401
       fetchMock.mockResolvedValueOnce(errorResponse(401, "Unauthorized"));

package/src/api/linear-api.ts

@@ -193,7 +193,7 @@ export class LinearAgentApi {
       }
 
       const payload = await retryRes.json();
-      if (payload.errors?.length) {
+      if (payload.errors?.length && !payload.data) {
         throw new Error(`Linear GraphQL: ${JSON.stringify(payload.errors)}`);
       }
       return payload.data as T;
@@ -205,7 +205,7 @@ export class LinearAgentApi {
     }
 
     const payload = await res.json();
-    if (payload.errors?.length) {
+    if (payload.errors?.length && !payload.data) {
       throw new Error(`Linear GraphQL: ${JSON.stringify(payload.errors)}`);
     }
 
@@ -306,7 +306,7 @@ export class LinearAgentApi {
     title: string;
     description: string | null;
     estimate: number | null;
-    state: { name: string };
+    state: { name: string; type: string };
     assignee: { name: string } | null;
     labels: { nodes: Array<{ id: string; name: string }> };
     team: { id: string; name: string; issueEstimationType: string };
@@ -323,7 +323,7 @@ export class LinearAgentApi {
           title
           description
           estimate
-          state { name }
+          state { name type }
           assignee { name }
           labels { nodes { id name } }
           team { id name issueEstimationType }
@@ -533,7 +533,7 @@ export class LinearAgentApi {
     }>(
       `query TeamStates($id: String!) {
         team(id: $id) {
-          states: workflowStates { nodes { id name type } }
+          states { nodes { id name type } }
         }
       }`,
       { id: teamId },
@@ -591,4 +591,95 @@ export class LinearAgentApi {
     );
     return data.notifications.nodes as any;
   }
+
+  // ---------------------------------------------------------------------------
+  // Webhook management
+  // ---------------------------------------------------------------------------
+
+  async listWebhooks(): Promise<Array<{
+    id: string;
+    label: string | null;
+    url: string;
+    enabled: boolean;
+    resourceTypes: string[];
+    allPublicTeams: boolean;
+    team: { id: string; name: string } | null;
+    createdAt: string;
+  }>> {
+    const data = await this.gql<{
+      webhooks: { nodes: unknown[] };
+    }>(
+      `query Webhooks {
+        webhooks {
+          nodes {
+            id
+            label
+            url
+            enabled
+            resourceTypes
+            allPublicTeams
+            team { id name }
+            createdAt
+          }
+        }
+      }`,
+    );
+    return data.webhooks.nodes as any;
+  }
+
+  async createWebhook(input: {
+    url: string;
+    resourceTypes: string[];
+    label?: string;
+    teamId?: string;
+    allPublicTeams?: boolean;
+    enabled?: boolean;
+    secret?: string;
+  }): Promise<{ id: string; enabled: boolean }> {
+    const data = await this.gql<{
+      webhookCreate: { success: boolean; webhook: { id: string; enabled: boolean } };
+    }>(
+      `mutation WebhookCreate($input: WebhookCreateInput!) {
+        webhookCreate(input: $input) {
+          success
+          webhook { id enabled }
+        }
+      }`,
+      { input },
+    );
+    return data.webhookCreate.webhook;
+  }
+
+  async updateWebhook(webhookId: string, input: {
+    url?: string;
+    resourceTypes?: string[];
+    label?: string;
+    enabled?: boolean;
+  }): Promise<boolean> {
+    const data = await this.gql<{
+      webhookUpdate: { success: boolean };
+    }>(
+      `mutation WebhookUpdate($id: String!, $input: WebhookUpdateInput!) {
+        webhookUpdate(id: $id, input: $input) {
+          success
+        }
+      }`,
+      { id: webhookId, input },
+    );
+    return data.webhookUpdate.success;
+  }
+
+  async deleteWebhook(webhookId: string): Promise<boolean> {
+    const data = await this.gql<{
+      webhookDelete: { success: boolean };
+    }>(
+      `mutation WebhookDelete($id: String!) {
+        webhookDelete(id: $id) {
+          success
+        }
+      }`,
+      { id: webhookId },
+    );
+    return data.webhookDelete.success;
+  }
 }

package/src/infra/cli.ts

@@ -644,6 +644,156 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
         process.exitCode = 1;
       }
     });
+
+  // --- openclaw openclaw-linear webhooks ---
+  const webhooksCmd = linear
+    .command("webhooks")
+    .description("Manage Linear webhook subscriptions");
+
+  webhooksCmd
+    .command("status")
+    .description("Show current webhook configuration in Linear")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found. Run \"openclaw openclaw-linear auth\" first.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      console.log("\nLinear Webhooks");
+      console.log("─".repeat(50));
+
+      const webhooks = await linearApi.listWebhooks();
+      if (webhooks.length === 0) {
+        console.log("\n  No webhooks found.");
+        console.log("  Run \"openclaw openclaw-linear webhooks setup\" to create one.\n");
+        return;
+      }
+
+      for (const wh of webhooks) {
+        const status = wh.enabled ? "enabled" : "DISABLED";
+        const label = wh.label ?? "(no label)";
+        const team = wh.team ? ` (team: ${wh.team.name})` : " (all teams)";
+        console.log(`\n  ${label}${team}`);
+        console.log(`    ID:      ${wh.id}`);
+        console.log(`    URL:     ${wh.url}`);
+        console.log(`    Status:  ${status}`);
+        console.log(`    Events:  ${wh.resourceTypes.join(", ")}`);
+        console.log(`    Created: ${wh.createdAt}`);
+      }
+
+      console.log();
+    });
+
+  webhooksCmd
+    .command("setup")
+    .description("Auto-provision or fix the workspace webhook (create/update as needed)")
+    .option("--url <url>", "Webhook URL (default: from Cloudflare tunnel config)")
+    .option("--team <id>", "Restrict to a specific team ID (default: all public teams)")
+    .option("--dry-run", "Show what would change without making changes")
+    .action(async (opts: { url?: string; team?: string; dryRun?: boolean }) => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const { provisionWebhook, getWebhookStatus, REQUIRED_RESOURCE_TYPES } = await import("./webhook-provision.js");
+
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found. Run \"openclaw openclaw-linear auth\" first.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      const webhookUrl = opts.url
+        ?? (pluginConfig?.webhookUrl as string)
+        ?? "https://linear.calltelemetry.com/linear/webhook";
+
+      console.log("\nWebhook Provisioning");
+      console.log("─".repeat(50));
+      console.log(`  URL:    ${webhookUrl}`);
+      console.log(`  Events: ${[...REQUIRED_RESOURCE_TYPES].join(", ")}`);
+
+      if (opts.dryRun) {
+        const status = await getWebhookStatus(linearApi, webhookUrl);
+        if (!status) {
+          console.log("\n  Would CREATE a new webhook with the above config.");
+        } else if (status.issues.length === 0) {
+          console.log("\n  Webhook already configured correctly. No changes needed.");
+        } else {
+          console.log("\n  Would UPDATE existing webhook:");
+          for (const issue of status.issues) {
+            console.log(`    - Fix: ${issue}`);
+          }
+        }
+        console.log();
+        return;
+      }
+
+      const result = await provisionWebhook(linearApi, webhookUrl, {
+        teamId: opts.team,
+        allPublicTeams: !opts.team,
+      });
+
+      switch (result.action) {
+        case "created":
+          console.log(`\n  Created webhook: ${result.webhookId}`);
+          break;
+        case "updated":
+          console.log(`\n  Updated webhook: ${result.webhookId}`);
+          for (const change of result.changes ?? []) {
+            console.log(`    - ${change}`);
+          }
+          break;
+        case "already_ok":
+          console.log(`\n  Webhook already configured correctly (${result.webhookId}). No changes needed.`);
+          break;
+      }
+
+      console.log();
+    });
+
+  webhooksCmd
+    .command("delete")
+    .description("Delete a webhook by ID")
+    .argument("<webhook-id>", "ID of the webhook to delete")
+    .action(async (webhookId: string) => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      const confirmAnswer = await prompt(`Delete webhook ${webhookId}? [y/N]: `);
+      if (confirmAnswer.toLowerCase() !== "y") {
+        console.log("  Aborted.\n");
+        return;
+      }
+
+      const success = await linearApi.deleteWebhook(webhookId);
+      if (success) {
+        console.log(`\n  Deleted webhook ${webhookId}\n`);
+      } else {
+        console.error(`\n  Failed to delete webhook ${webhookId}\n`);
+        process.exitCode = 1;
+      }
+    });
 }
 
 // ---------------------------------------------------------------------------

package/src/infra/doctor.test.ts

@@ -11,6 +11,9 @@ vi.mock("../api/linear-api.js", () => ({
     expiresAt: Date.now() + 24 * 3_600_000,
     source: "profile" as const,
   })),
+  LinearAgentApi: class MockLinearAgentApi {
+    constructor() {}
+  },
   AUTH_PROFILES_PATH: "/tmp/test-auth-profiles.json",
   LINEAR_GRAPHQL_URL: "https://api.linear.app/graphql",
 }));
@@ -57,6 +60,16 @@ vi.mock("../tools/code-tool.js", () => ({
   })),
 }));
 
+vi.mock("./webhook-provision.js", () => ({
+  getWebhookStatus: vi.fn(async () => null),
+  provisionWebhook: vi.fn(async () => ({
+    action: "created",
+    webhookId: "wh-test-1",
+    changes: ["created new webhook"],
+  })),
+  REQUIRED_RESOURCE_TYPES: ["Comment", "Issue"],
+}));
+
 import {
   checkAuth,
   checkAgentConfig,
@@ -64,6 +77,7 @@ import {
   checkFilesAndDirs,
   checkConnectivity,
   checkDispatchHealth,
+  checkWebhooks,
   runDoctor,
   formatReport,
   formatReportJson,
@@ -330,7 +344,7 @@ describe("checkDispatchHealth", () => {
 // ---------------------------------------------------------------------------
 
 describe("runDoctor", () => {
-  it("returns all 6 sections", async () => {
+  it("returns all 7 sections", async () => {
     vi.stubGlobal("fetch", vi.fn(async (url: string) => {
       if (url.includes("linear.app")) {
         return {
@@ -342,7 +356,7 @@ describe("runDoctor", () => {
     }));
 
     const report = await runDoctor({ fix: false, json: false });
-    expect(report.sections).toHaveLength(6);
+    expect(report.sections).toHaveLength(7);
     expect(report.sections.map((s) => s.name)).toEqual([
       "Authentication & Tokens",
       "Agent Configuration",
@@ -350,6 +364,7 @@ describe("runDoctor", () => {
       "Files & Directories",
       "Connectivity",
       "Dispatch Health",
+      "Webhook Configuration",
     ]);
     expect(report.summary.passed + report.summary.warnings + report.summary.errors).toBeGreaterThan(0);
   });

package/src/infra/doctor.ts

@@ -8,11 +8,12 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 
-import { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
+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 { getWebhookStatus, provisionWebhook, REQUIRED_RESOURCE_TYPES } from "./webhook-provision.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -650,6 +651,68 @@ export async function checkDispatchHealth(pluginConfig?: Record<string, unknown>
   return checks;
 }
 
+// ---------------------------------------------------------------------------
+// Section 7: Webhook Configuration
+// ---------------------------------------------------------------------------
+
+export async function checkWebhooks(pluginConfig?: Record<string, unknown>, fix = false): Promise<CheckResult[]> {
+  const checks: CheckResult[] = [];
+
+  const tokenInfo = resolveLinearToken(pluginConfig);
+  if (!tokenInfo.accessToken) {
+    checks.push(warn("Webhook check skipped (no Linear token)"));
+    return checks;
+  }
+
+  const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+    refreshToken: tokenInfo.refreshToken,
+    expiresAt: tokenInfo.expiresAt,
+  });
+
+  const webhookUrl = (pluginConfig?.webhookUrl as string)
+    ?? "https://linear.calltelemetry.com/linear/webhook";
+
+  try {
+    const status = await getWebhookStatus(linearApi, webhookUrl);
+
+    if (!status) {
+      if (fix) {
+        const result = await provisionWebhook(linearApi, webhookUrl, { allPublicTeams: true });
+        checks.push(pass(`Workspace webhook created (${result.webhookId}) (--fix)`));
+      } else {
+        checks.push(fail(
+          `No workspace webhook found for ${webhookUrl}`,
+          undefined,
+          'Run: openclaw openclaw-linear webhooks setup',
+        ));
+      }
+      return checks;
+    }
+
+    if (status.issues.length === 0) {
+      checks.push(pass(`Workspace webhook OK (${[...REQUIRED_RESOURCE_TYPES].join(", ")})`));
+    } else {
+      if (fix) {
+        const result = await provisionWebhook(linearApi, webhookUrl);
+        const changes = result.changes?.join(", ") ?? "fixed";
+        checks.push(pass(`Workspace webhook fixed: ${changes} (--fix)`));
+      } else {
+        for (const issue of status.issues) {
+          checks.push(warn(
+            `Webhook issue: ${issue}`,
+            undefined,
+            { fixable: true, fix: 'Run: openclaw openclaw-linear webhooks setup' },
+          ));
+        }
+      }
+    }
+  } catch (err) {
+    checks.push(warn(`Webhook check failed: ${err instanceof Error ? err.message : String(err)}`));
+  }
+
+  return checks;
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -685,6 +748,12 @@ export async function runDoctor(opts: DoctorOptions): Promise<DoctorReport> {
     checks: await checkDispatchHealth(opts.pluginConfig, opts.fix),
   });
 
+  // 7. Webhook configuration (auto-fix if --fix)
+  sections.push({
+    name: "Webhook Configuration",
+    checks: await checkWebhooks(opts.pluginConfig, opts.fix),
+  });
+
   // Fix: chmod auth-profiles.json if needed
   if (opts.fix) {
     const permCheck = auth.checks.find((c) => c.fixable && c.label.includes("permissions"));