@calltelemetry/openclaw-linear 0.7.0 → 0.7.1

package/src/tools/dispatch-history-tool.ts

@@ -0,0 +1,201 @@
+/**
+ * dispatch-history-tool.ts — Agent tool for searching dispatch history.
+ *
+ * Searches dispatch state + memory files to provide context about
+ * past dispatches. Useful for agents to understand what work has
+ * been done on related issues.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { readDispatchState, listActiveDispatches, type ActiveDispatch, type CompletedDispatch } from "../pipeline/dispatch-state.js";
+import { resolveOrchestratorWorkspace } from "../pipeline/artifacts.js";
+
+export function createDispatchHistoryTool(
+  api: OpenClawPluginApi,
+  pluginConfig?: Record<string, unknown>,
+): AnyAgentTool {
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  return {
+    name: "dispatch_history",
+    label: "Dispatch History",
+    description:
+      "Search dispatch history for past and active Linear issue dispatches. " +
+      "Returns issue identifier, tier, status, attempts, and summary excerpts.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Issue identifier (e.g. 'CT-123') or keyword to search in summaries.",
+        },
+        tier: {
+          type: "string",
+          enum: ["junior", "medior", "senior"],
+          description: "Filter by tier.",
+        },
+        status: {
+          type: "string",
+          enum: ["dispatched", "working", "auditing", "done", "failed", "stuck"],
+          description: "Filter by status.",
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default: 10).",
+        },
+      },
+    },
+    execute: async (_toolCallId: string, params: {
+      query?: string;
+      tier?: string;
+      status?: string;
+      limit?: number;
+    }) => {
+      const maxResults = params.limit ?? 10;
+      const results: Array<{
+        identifier: string;
+        tier: string;
+        status: string;
+        attempts: number;
+        summary?: string;
+        active: boolean;
+      }> = [];
+
+      // Search active dispatches
+      const state = await readDispatchState(statePath);
+      const active = listActiveDispatches(state);
+      for (const d of active) {
+        if (matchesFilters(d.issueIdentifier, d.tier, d.status, params)) {
+          results.push({
+            identifier: d.issueIdentifier,
+            tier: d.tier,
+            status: d.status,
+            attempts: d.attempt,
+            active: true,
+          });
+        }
+      }
+
+      // Search completed dispatches
+      for (const [id, d] of Object.entries(state.dispatches.completed)) {
+        if (matchesFilters(id, d.tier, d.status, params)) {
+          results.push({
+            identifier: id,
+            tier: d.tier,
+            status: d.status,
+            attempts: d.totalAttempts ?? 0,
+            active: false,
+          });
+        }
+      }
+
+      // Search memory files for richer context
+      try {
+        const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+        const memDir = join(wsDir, "memory");
+        const files = readdirSync(memDir).filter(f => f.startsWith("dispatch-") && f.endsWith(".md"));
+
+        for (const file of files) {
+          const id = file.replace("dispatch-", "").replace(".md", "");
+          // Skip if already in results
+          if (results.some(r => r.identifier === id)) {
+            // Enrich with summary
+            const existing = results.find(r => r.identifier === id);
+            if (existing && !existing.summary) {
+              try {
+                const content = readFileSync(join(memDir, file), "utf-8");
+                existing.summary = extractSummaryExcerpt(content, params.query);
+              } catch {}
+            }
+            continue;
+          }
+
+          // Check if memory file matches query
+          if (params.query) {
+            try {
+              const content = readFileSync(join(memDir, file), "utf-8");
+              if (
+                id.toLowerCase().includes(params.query.toLowerCase()) ||
+                content.toLowerCase().includes(params.query.toLowerCase())
+              ) {
+                const meta = parseFrontmatter(content);
+                if (matchesFilters(id, meta.tier, meta.status, params)) {
+                  results.push({
+                    identifier: id,
+                    tier: meta.tier ?? "unknown",
+                    status: meta.status ?? "completed",
+                    attempts: meta.attempts ?? 0,
+                    summary: extractSummaryExcerpt(content, params.query),
+                    active: false,
+                  });
+                }
+              }
+            } catch {}
+          }
+        }
+      } catch {}
+
+      const limited = results.slice(0, maxResults);
+
+      if (limited.length === 0) {
+        return jsonResult({ message: "No dispatch history found matching the criteria.", results: [] });
+      }
+
+      const formatted = limited.map(r => {
+        const parts = [`**${r.identifier}** — ${r.status} (${r.tier}, ${r.attempts} attempts)${r.active ? " [ACTIVE]" : ""}`];
+        if (r.summary) parts.push(`  ${r.summary}`);
+        return parts.join("\n");
+      }).join("\n\n");
+
+      return jsonResult({
+        message: `Found ${limited.length} dispatch(es):\n\n${formatted}`,
+        results: limited,
+      });
+    },
+  } as unknown as AnyAgentTool;
+}
+
+function matchesFilters(
+  identifier: string,
+  tier: string,
+  status: string,
+  params: { query?: string; tier?: string; status?: string },
+): boolean {
+  if (params.tier && tier !== params.tier) return false;
+  if (params.status && status !== params.status) return false;
+  if (params.query && !identifier.toLowerCase().includes(params.query.toLowerCase())) return false;
+  return true;
+}
+
+function parseFrontmatter(content: string): Record<string, any> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const result: Record<string, any> = {};
+  for (const line of match[1].split("\n")) {
+    const [key, ...rest] = line.split(": ");
+    if (key && rest.length > 0) {
+      let value: any = rest.join(": ").trim();
+      if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+      else if (!isNaN(Number(value))) value = Number(value);
+      result[key.trim()] = value;
+    }
+  }
+  return result;
+}
+
+function extractSummaryExcerpt(content: string, query?: string): string {
+  // Remove frontmatter
+  const body = content.replace(/^---[\s\S]*?---\n?/, "").trim();
+  if (!query) return body.slice(0, 200);
+
+  // Find the query in the body and return surrounding context
+  const lower = body.toLowerCase();
+  const idx = lower.indexOf(query.toLowerCase());
+  if (idx === -1) return body.slice(0, 200);
+
+  const start = Math.max(0, idx - 50);
+  const end = Math.min(body.length, idx + query.length + 150);
+  return (start > 0 ? "..." : "") + body.slice(start, end) + (end < body.length ? "..." : "");
+}

package/src/tools/orchestration-tools.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createOrchestrationTools } from "./orchestration-tools.js";
+
+// ---------------------------------------------------------------------------
+// Mock runAgent
+// ---------------------------------------------------------------------------
+
+const mockRunAgent = vi.fn();
+
+vi.mock("../agent/agent.js", () => ({
+  runAgent: (...args: unknown[]) => mockRunAgent(...args),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock jsonResult (from openclaw/plugin-sdk)
+// ---------------------------------------------------------------------------
+
+vi.mock("openclaw/plugin-sdk", () => ({
+  jsonResult: (obj: unknown) => ({ type: "json", data: obj }),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeApi() {
+  return {
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+  } as any;
+}
+
+function makeCtx(): Record<string, unknown> {
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createOrchestrationTools", () => {
+  beforeEach(() => {
+    mockRunAgent.mockReset();
+  });
+
+  it("returns 2 tools", () => {
+    const tools = createOrchestrationTools(makeApi(), makeCtx());
+
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe("spawn_agent");
+    expect(tools[1].name).toBe("ask_agent");
+  });
+
+  it("spawn_agent tool has correct name and parameters schema", () => {
+    const tools = createOrchestrationTools(makeApi(), makeCtx());
+    const spawn = tools[0];
+
+    expect(spawn.name).toBe("spawn_agent");
+    expect(spawn.parameters).toBeDefined();
+    expect(spawn.parameters.type).toBe("object");
+    expect(spawn.parameters.properties.agentId).toBeDefined();
+    expect(spawn.parameters.properties.task).toBeDefined();
+    expect(spawn.parameters.properties.timeoutSeconds).toBeDefined();
+    expect(spawn.parameters.required).toEqual(["agentId", "task"]);
+  });
+
+  it("spawn_agent dispatches to runAgent and returns immediately", async () => {
+    // runAgent returns a promise that never resolves (to prove fire-and-forget)
+    let resolveAgent!: (value: unknown) => void;
+    const agentPromise = new Promise((resolve) => { resolveAgent = resolve; });
+    mockRunAgent.mockReturnValue(agentPromise);
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const spawn = tools[0];
+
+    const result = await spawn.execute("call-1", {
+      agentId: "kaylee",
+      task: "Investigate database performance",
+    });
+
+    // Should return immediately with a sessionId, even though runAgent hasn't resolved
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.sessionId).toMatch(/^spawn-kaylee-/);
+    expect(result.data.message).toContain("Dispatched task");
+    expect(mockRunAgent).toHaveBeenCalledOnce();
+
+    // Clean up: resolve the hanging promise to avoid unhandled rejection
+    resolveAgent({ success: true, output: "done" });
+  });
+
+  it("ask_agent returns response on success", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: "No, the schema change is backward-compatible and won't break tests.",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    const result = await askAgent.execute("call-2", {
+      agentId: "kaylee",
+      message: "Would this schema change break existing tests?",
+    });
+
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.response).toBe(
+      "No, the schema change is backward-compatible and won't break tests.",
+    );
+    expect(result.data.message).toContain("Response from agent");
+  });
+
+  it("ask_agent returns error message on failure", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: false,
+      output: "Agent timed out after 120s",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    const result = await askAgent.execute("call-3", {
+      agentId: "kaylee",
+      message: "Check if the migration works",
+    });
+
+    expect(result.data.agentId).toBe("kaylee");
+    expect(result.data.error).toBe("Agent timed out after 120s");
+    expect(result.data.message).toContain("failed to respond");
+    expect(result.data.response).toBeUndefined();
+  });
+
+  it("ask_agent uses custom timeout when provided", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: "Result from agent",
+    });
+
+    const api = makeApi();
+    const tools = createOrchestrationTools(api, makeCtx());
+    const askAgent = tools[1];
+
+    await askAgent.execute("call-4", {
+      agentId: "mal",
+      message: "Run a long analysis",
+      timeoutSeconds: 600,
+    });
+
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    // 600 seconds = 600_000 ms
+    expect(callArgs.timeoutMs).toBe(600_000);
+  });
+});