@calltelemetry/openclaw-linear 0.7.0 → 0.8.0

package/src/gateway/dispatch-methods.test.ts

@@ -0,0 +1,409 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mock dispatch-state
+// ---------------------------------------------------------------------------
+
+const mockReadDispatchState = vi.fn();
+const mockGetActiveDispatch = vi.fn();
+const mockListActiveDispatches = vi.fn();
+const mockTransitionDispatch = vi.fn();
+const mockRemoveActiveDispatch = vi.fn();
+const mockRegisterDispatch = vi.fn();
+
+vi.mock("../pipeline/dispatch-state.js", () => ({
+  readDispatchState: (...args: any[]) => mockReadDispatchState(...args),
+  getActiveDispatch: (...args: any[]) => mockGetActiveDispatch(...args),
+  listActiveDispatches: (...args: any[]) => mockListActiveDispatches(...args),
+  transitionDispatch: (...args: any[]) => mockTransitionDispatch(...args),
+  removeActiveDispatch: (...args: any[]) => mockRemoveActiveDispatch(...args),
+  registerDispatch: (...args: any[]) => mockRegisterDispatch(...args),
+  TransitionError: class TransitionError extends Error {},
+}));
+
+import { registerDispatchMethods } from "./dispatch-methods.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createApi() {
+  const methods: Record<string, Function> = {};
+  return {
+    api: {
+      logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+      pluginConfig: {},
+      registerGatewayMethod: (name: string, handler: Function) => {
+        methods[name] = handler;
+      },
+    } as any,
+    methods,
+  };
+}
+
+function makeDispatch(overrides?: Record<string, any>) {
+  return {
+    issueIdentifier: "CT-100",
+    issueId: "issue-id",
+    status: "working",
+    tier: "senior",
+    attempt: 0,
+    worktreePath: "/wt/ct-100",
+    model: "opus",
+    startedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+function makeState(active: Record<string, any> = {}, completed: Record<string, any> = {}) {
+  return {
+    dispatches: { active, completed },
+    sessionMap: {},
+    processedEvents: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("registerDispatchMethods", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("registers all 6 methods", () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+    expect(Object.keys(methods)).toEqual(
+      expect.arrayContaining([
+        "dispatch.list",
+        "dispatch.get",
+        "dispatch.retry",
+        "dispatch.escalate",
+        "dispatch.cancel",
+        "dispatch.stats",
+      ]),
+    );
+  });
+});
+
+describe("dispatch.list", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns active and completed dispatches", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch();
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }, { "CT-99": { status: "done" } }));
+    mockListActiveDispatches.mockReturnValue([d]);
+
+    const respond = vi.fn();
+    await methods["dispatch.list"]({ params: {}, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: true,
+      active: [d],
+    }));
+  });
+
+  it("filters by status", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d1 = makeDispatch({ issueIdentifier: "CT-1", status: "working" });
+    const d2 = makeDispatch({ issueIdentifier: "CT-2", status: "stuck" });
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockListActiveDispatches.mockReturnValue([d1, d2]);
+
+    const respond = vi.fn();
+    await methods["dispatch.list"]({ params: { status: "stuck" }, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.ok).toBe(true);
+    expect(result.active).toEqual([d2]);
+  });
+
+  it("filters by tier", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d1 = makeDispatch({ issueIdentifier: "CT-1", tier: "junior" });
+    const d2 = makeDispatch({ issueIdentifier: "CT-2", tier: "senior" });
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockListActiveDispatches.mockReturnValue([d1, d2]);
+
+    const respond = vi.fn();
+    await methods["dispatch.list"]({ params: { tier: "senior" }, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.active).toEqual([d2]);
+  });
+});
+
+describe("dispatch.get", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns active dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch();
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+
+    const respond = vi.fn();
+    await methods["dispatch.get"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: true,
+      dispatch: d,
+      source: "active",
+    }));
+  });
+
+  it("returns completed dispatch when not active", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const completed = { status: "done", tier: "junior" };
+    mockReadDispatchState.mockResolvedValue(makeState({}, { "CT-99": completed }));
+    mockGetActiveDispatch.mockReturnValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.get"]({ params: { identifier: "CT-99" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: true,
+      source: "completed",
+    }));
+  });
+
+  it("fails when identifier missing", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const respond = vi.fn();
+    await methods["dispatch.get"]({ params: {}, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+      error: expect.stringContaining("identifier"),
+    }));
+  });
+
+  it("fails when dispatch not found", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockGetActiveDispatch.mockReturnValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.get"]({ params: { identifier: "NOPE-1" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+      error: expect.stringContaining("NOPE-1"),
+    }));
+  });
+});
+
+describe("dispatch.retry", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("retries stuck dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "stuck", attempt: 1 });
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockRemoveActiveDispatch.mockResolvedValue(undefined);
+    mockRegisterDispatch.mockResolvedValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.retry"]({ params: { identifier: "CT-100" }, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.ok).toBe(true);
+    expect(result.dispatch.status).toBe("dispatched");
+    expect(result.dispatch.attempt).toBe(2);
+    expect(mockRemoveActiveDispatch).toHaveBeenCalledWith("CT-100", undefined);
+    expect(mockRegisterDispatch).toHaveBeenCalled();
+  });
+
+  it("rejects retry for working dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "working" });
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+
+    const respond = vi.fn();
+    await methods["dispatch.retry"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+      error: expect.stringContaining("working"),
+    }));
+  });
+
+  it("rejects retry for missing dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockGetActiveDispatch.mockReturnValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.retry"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+    }));
+  });
+});
+
+describe("dispatch.escalate", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("escalates working dispatch to stuck", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "working" });
+    const updated = { ...d, status: "stuck", stuckReason: "Manual escalation" };
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockTransitionDispatch.mockResolvedValue(updated);
+
+    const respond = vi.fn();
+    await methods["dispatch.escalate"]({ params: { identifier: "CT-100", reason: "Manual escalation" }, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.ok).toBe(true);
+    expect(mockTransitionDispatch).toHaveBeenCalledWith("CT-100", "working", "stuck", expect.objectContaining({ stuckReason: "Manual escalation" }), undefined);
+  });
+
+  it("uses default reason when none provided", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "auditing" });
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockTransitionDispatch.mockResolvedValue(d);
+
+    const respond = vi.fn();
+    await methods["dispatch.escalate"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(mockTransitionDispatch).toHaveBeenCalledWith(
+      "CT-100", "auditing", "stuck",
+      expect.objectContaining({ stuckReason: "Manually escalated via gateway" }),
+      undefined,
+    );
+  });
+
+  it("rejects escalation for stuck dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "stuck" });
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+
+    const respond = vi.fn();
+    await methods["dispatch.escalate"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+      error: expect.stringContaining("stuck"),
+    }));
+  });
+});
+
+describe("dispatch.cancel", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("removes active dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const d = makeDispatch({ status: "working" });
+    mockReadDispatchState.mockResolvedValue(makeState({ "CT-100": d }));
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockRemoveActiveDispatch.mockResolvedValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.cancel"]({ params: { identifier: "CT-100" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: true,
+      cancelled: "CT-100",
+      previousStatus: "working",
+    }));
+    expect(mockRemoveActiveDispatch).toHaveBeenCalledWith("CT-100", undefined);
+  });
+
+  it("fails for missing dispatch", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockGetActiveDispatch.mockReturnValue(undefined);
+
+    const respond = vi.fn();
+    await methods["dispatch.cancel"]({ params: { identifier: "CT-999" }, respond });
+
+    expect(respond).toHaveBeenCalledWith(true, expect.objectContaining({
+      ok: false,
+    }));
+  });
+});
+
+describe("dispatch.stats", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("returns counts by status and tier", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    const active = [
+      makeDispatch({ status: "working", tier: "senior" }),
+      makeDispatch({ status: "working", tier: "junior" }),
+      makeDispatch({ status: "stuck", tier: "senior" }),
+    ];
+    mockReadDispatchState.mockResolvedValue(makeState({}, { "CT-99": {} }));
+    mockListActiveDispatches.mockReturnValue(active);
+
+    const respond = vi.fn();
+    await methods["dispatch.stats"]({ params: {}, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.ok).toBe(true);
+    expect(result.activeCount).toBe(3);
+    expect(result.completedCount).toBe(1);
+    expect(result.byStatus).toEqual({ working: 2, stuck: 1 });
+    expect(result.byTier).toEqual({ senior: 2, junior: 1 });
+  });
+
+  it("returns zeros when no dispatches", async () => {
+    const { api, methods } = createApi();
+    registerDispatchMethods(api);
+
+    mockReadDispatchState.mockResolvedValue(makeState());
+    mockListActiveDispatches.mockReturnValue([]);
+
+    const respond = vi.fn();
+    await methods["dispatch.stats"]({ params: {}, respond });
+
+    const result = respond.mock.calls[0][1];
+    expect(result.activeCount).toBe(0);
+    expect(result.completedCount).toBe(0);
+    expect(result.byStatus).toEqual({});
+    expect(result.byTier).toEqual({});
+  });
+});

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)");
+}