@calltelemetry/openclaw-linear 0.6.1 → 0.7.1

package/src/api/linear-api.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { refreshLinearToken } from "./auth.js";
+import { withResilience } from "../infra/resilience.js";
 
 export const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
 export const AUTH_PROFILES_PATH = join(
@@ -148,38 +149,50 @@ export class LinearAgentApi {
     return this.refreshToken ? `Bearer ${this.accessToken}` : this.accessToken;
   }
 
-  private async gql<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T> {
+  private async gql<T = unknown>(
+    query: string,
+    variables?: Record<string, unknown>,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
     await this.ensureValidToken();
 
-    const res = await fetch(LINEAR_GRAPHQL_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: this.authHeader(),
-      },
-      body: JSON.stringify({ query, variables }),
-    });
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Authorization: this.authHeader(),
+      ...extraHeaders,
+    };
+
+    const res = await withResilience(() =>
+      fetch(LINEAR_GRAPHQL_URL, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query, variables }),
+      }),
+    );
 
-    // If 401, try refreshing token once
+    // If 401, try refreshing token once (outside resilience — own retry semantics)
     if (res.status === 401 && this.refreshToken && this.clientId && this.clientSecret) {
       this.expiresAt = 0; // force refresh
       await this.ensureValidToken();
 
-      const retry = await fetch(LINEAR_GRAPHQL_URL, {
+      const retryHeaders: Record<string, string> = {
+        "Content-Type": "application/json",
+        Authorization: this.authHeader(),
+        ...extraHeaders,
+      };
+
+      const retryRes = await fetch(LINEAR_GRAPHQL_URL, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: this.authHeader(),
-        },
+        headers: retryHeaders,
         body: JSON.stringify({ query, variables }),
       });
 
-      if (!retry.ok) {
-        const text = await retry.text();
-        throw new Error(`Linear API ${retry.status} (after refresh): ${text}`);
+      if (!retryRes.ok) {
+        const text = await retryRes.text();
+        throw new Error(`Linear API ${retryRes.status} (after refresh): ${text}`);
       }
 
-      const payload = await retry.json();
+      const payload = await retryRes.json();
       if (payload.errors?.length) {
         throw new Error(`Linear GraphQL: ${JSON.stringify(payload.errors)}`);
       }
@@ -298,6 +311,9 @@ export class LinearAgentApi {
     labels: { nodes: Array<{ id: string; name: string }> };
     team: { id: string; name: string; issueEstimationType: string };
     comments: { nodes: Array<{ body: string; user: { name: string } | null; createdAt: string }> };
+    project: { id: string; name: string } | null;
+    parent: { id: string; identifier: string } | null;
+    relations: { nodes: Array<{ type: string; relatedIssue: { id: string; identifier: string; title: string } }> };
   }> {
     const data = await this.gql<{ issue: unknown }>(
       `query Issue($id: String!) {
@@ -318,6 +334,9 @@ export class LinearAgentApi {
               createdAt
             }
           }
+          project { id name }
+          parent { id identifier }
+          relations { nodes { type relatedIssue { id identifier title } } }
         }
       }`,
       { id: issueId },
@@ -356,6 +375,161 @@ export class LinearAgentApi {
     return data.team.labels.nodes;
   }
 
+  // ---------------------------------------------------------------------------
+  // Planning methods
+  // ---------------------------------------------------------------------------
+
+  async createIssue(input: {
+    teamId: string;
+    title: string;
+    description?: string;
+    projectId?: string;
+    parentId?: string;
+    priority?: number;
+    estimate?: number;
+    labelIds?: string[];
+    stateId?: string;
+    assigneeId?: string;
+  }): Promise<{ id: string; identifier: string }> {
+    // Sub-issues require the GraphQL-Features header
+    const extra = input.parentId ? { "GraphQL-Features": "sub_issues" } : undefined;
+    const data = await this.gql<{
+      issueCreate: { success: boolean; issue: { id: string; identifier: string } };
+    }>(
+      `mutation IssueCreate($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue { id identifier }
+        }
+      }`,
+      { input },
+      extra,
+    );
+    return data.issueCreate.issue;
+  }
+
+  async createIssueRelation(input: {
+    issueId: string;
+    relatedIssueId: string;
+    type: "blocks" | "blocked_by" | "related" | "duplicate";
+  }): Promise<{ id: string }> {
+    const data = await this.gql<{
+      issueRelationCreate: { success: boolean; issueRelation: { id: string } };
+    }>(
+      `mutation IssueRelationCreate($input: IssueRelationCreateInput!) {
+        issueRelationCreate(input: $input) {
+          success
+          issueRelation { id }
+        }
+      }`,
+      { input },
+    );
+    return data.issueRelationCreate.issueRelation;
+  }
+
+  async getProject(projectId: string): Promise<{
+    id: string;
+    name: string;
+    description: string;
+    state: string;
+    teams: { nodes: Array<{ id: string; name: string }> };
+  }> {
+    const data = await this.gql<{ project: unknown }>(
+      `query Project($id: String!) {
+        project(id: $id) {
+          id
+          name
+          description
+          state
+          teams { nodes { id name } }
+        }
+      }`,
+      { id: projectId },
+    );
+    return data.project as any;
+  }
+
+  async getProjectIssues(projectId: string): Promise<Array<{
+    id: string;
+    identifier: string;
+    title: string;
+    description: string | null;
+    estimate: number | null;
+    priority: number;
+    state: { name: string; type: string };
+    parent: { id: string; identifier: string } | null;
+    labels: { nodes: Array<{ id: string; name: string }> };
+    relations: { nodes: Array<{ type: string; relatedIssue: { id: string; identifier: string; title: string } }> };
+  }>> {
+    const data = await this.gql<{
+      project: { issues: { nodes: unknown[] } };
+    }>(
+      `query ProjectIssues($id: String!) {
+        project(id: $id) {
+          issues {
+            nodes {
+              id
+              identifier
+              title
+              description
+              estimate
+              priority
+              state { name type }
+              parent { id identifier }
+              labels { nodes { id name } }
+              relations { nodes { type relatedIssue { id identifier title } } }
+            }
+          }
+        }
+      }`,
+      { id: projectId },
+    );
+    return data.project.issues.nodes as any;
+  }
+
+  async getTeamStates(teamId: string): Promise<Array<{
+    id: string;
+    name: string;
+    type: string;
+  }>> {
+    const data = await this.gql<{
+      team: { states: { nodes: Array<{ id: string; name: string; type: string }> } };
+    }>(
+      `query TeamStates($id: String!) {
+        team(id: $id) {
+          states: workflowStates { nodes { id name type } }
+        }
+      }`,
+      { id: teamId },
+    );
+    return data.team.states.nodes;
+  }
+
+  async updateIssueExtended(issueId: string, input: {
+    title?: string;
+    description?: string;
+    estimate?: number;
+    labelIds?: string[];
+    stateId?: string;
+    priority?: number;
+    projectId?: string;
+    parentId?: string;
+    assigneeId?: string;
+    dueDate?: string;
+  }): Promise<boolean> {
+    const data = await this.gql<{
+      issueUpdate: { success: boolean };
+    }>(
+      `mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) {
+          success
+        }
+      }`,
+      { id: issueId, input },
+    );
+    return data.issueUpdate.success;
+  }
+
   async getAppNotifications(count: number = 5): Promise<Array<{
     id: string;
     type: string;

package/src/gateway/dispatch-methods.ts

@@ -0,0 +1,243 @@
+/**
+ * dispatch-methods.ts — Gateway RPC methods for dispatch operations.
+ *
+ * Registers methods on the OpenClaw gateway that allow clients (UI, CLI, other
+ * plugins) to inspect and manage the dispatch pipeline via the standard
+ * gateway request/respond protocol.
+ *
+ * Methods:
+ *   dispatch.list      — List active + completed dispatches (filterable)
+ *   dispatch.get       — Full details for a single dispatch
+ *   dispatch.retry     — Re-dispatch a stuck issue
+ *   dispatch.escalate  — Force a working/auditing dispatch into stuck
+ *   dispatch.cancel    — Remove an active dispatch entirely
+ *   dispatch.stats     — Aggregate counts by status and tier
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  readDispatchState,
+  getActiveDispatch,
+  listActiveDispatches,
+  transitionDispatch,
+  removeActiveDispatch,
+  registerDispatch,
+  TransitionError,
+  type ActiveDispatch,
+  type DispatchState,
+  type DispatchStatus,
+  type CompletedDispatch,
+} from "../pipeline/dispatch-state.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ok(data: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ok: true, ...data };
+}
+
+function fail(error: string): Record<string, unknown> {
+  return { ok: false, error };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerDispatchMethods(api: OpenClawPluginApi): void {
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  // ---- dispatch.list -------------------------------------------------------
+  api.registerGatewayMethod("dispatch.list", async ({ params, respond }) => {
+    try {
+      const statusFilter = params.status as DispatchStatus | undefined;
+      const tierFilter = params.tier as string | undefined;
+
+      const state = await readDispatchState(statePath);
+      let active = listActiveDispatches(state);
+
+      if (statusFilter) {
+        active = active.filter((d) => d.status === statusFilter);
+      }
+      if (tierFilter) {
+        active = active.filter((d) => d.tier === tierFilter);
+      }
+
+      const completed = Object.values(state.dispatches.completed);
+
+      respond(true, ok({ active, completed }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.get --------------------------------------------------------
+  api.registerGatewayMethod("dispatch.get", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const active = getActiveDispatch(state, identifier);
+      if (active) {
+        respond(true, ok({ dispatch: active, source: "active" }));
+        return;
+      }
+
+      const completed = state.dispatches.completed[identifier];
+      if (completed) {
+        respond(true, ok({ dispatch: completed, source: "completed" }));
+        return;
+      }
+
+      respond(true, fail(`No dispatch found for identifier: ${identifier}`));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.retry ------------------------------------------------------
+  // Stuck dispatches are terminal in VALID_TRANSITIONS, so we cannot use
+  // transitionDispatch. Instead, remove the active dispatch and re-register
+  // it with status reset to "dispatched" and an incremented attempt counter.
+  api.registerGatewayMethod("dispatch.retry", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      if (dispatch.status !== "stuck") {
+        respond(true, fail(`Cannot retry dispatch in status "${dispatch.status}" — only "stuck" dispatches can be retried`));
+        return;
+      }
+
+      // Capture current state, remove, then re-register with reset status
+      const retryDispatch: ActiveDispatch = {
+        ...dispatch,
+        status: "dispatched",
+        attempt: dispatch.attempt + 1,
+        stuckReason: undefined,
+        workerSessionKey: undefined,
+        auditSessionKey: undefined,
+      };
+
+      await removeActiveDispatch(identifier, statePath);
+      await registerDispatch(identifier, retryDispatch, statePath);
+
+      api.logger.info(`dispatch.retry: ${identifier} re-dispatched (attempt ${retryDispatch.attempt})`);
+      respond(true, ok({ dispatch: retryDispatch }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.escalate ---------------------------------------------------
+  api.registerGatewayMethod("dispatch.escalate", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const reason = (params.reason as string) || "Manually escalated via gateway";
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      if (dispatch.status !== "working" && dispatch.status !== "auditing") {
+        respond(true, fail(`Cannot escalate dispatch in status "${dispatch.status}" — only "working" or "auditing" dispatches can be escalated`));
+        return;
+      }
+
+      const updated = await transitionDispatch(
+        identifier,
+        dispatch.status,
+        "stuck",
+        { stuckReason: reason },
+        statePath,
+      );
+
+      api.logger.info(`dispatch.escalate: ${identifier} escalated to stuck (was ${dispatch.status}, reason: ${reason})`);
+      respond(true, ok({ dispatch: updated }));
+    } catch (err: any) {
+      if (err instanceof TransitionError) {
+        respond(true, fail(`Transition conflict: ${err.message}`));
+        return;
+      }
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.cancel -----------------------------------------------------
+  api.registerGatewayMethod("dispatch.cancel", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      await removeActiveDispatch(identifier, statePath);
+
+      api.logger.info(`dispatch.cancel: ${identifier} removed (was ${dispatch.status})`);
+      respond(true, ok({ cancelled: identifier, previousStatus: dispatch.status }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.stats ------------------------------------------------------
+  api.registerGatewayMethod("dispatch.stats", async ({ params, respond }) => {
+    try {
+      const state = await readDispatchState(statePath);
+      const active = listActiveDispatches(state);
+
+      const byStatus: Record<string, number> = {};
+      const byTier: Record<string, number> = {};
+
+      for (const d of active) {
+        byStatus[d.status] = (byStatus[d.status] ?? 0) + 1;
+        byTier[d.tier] = (byTier[d.tier] ?? 0) + 1;
+      }
+
+      const completedCount = Object.keys(state.dispatches.completed).length;
+
+      respond(true, ok({
+        activeCount: active.length,
+        completedCount,
+        byStatus,
+        byTier,
+      }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  api.logger.info("Dispatch gateway methods registered (dispatch.list, dispatch.get, dispatch.retry, dispatch.escalate, dispatch.cancel, dispatch.stats)");
+}