@openfinclaw/findoo-alpha-plugin 2026.3.12

package/src/pending-task-tracker.ts

@@ -0,0 +1,254 @@
+/**
+ * PendingTaskTracker — manages background A2A SSE streams for async analysis.
+ *
+ * When fin_analyze submits a long-running query, it opens an SSE stream,
+ * grabs the taskId from the first event, and returns immediately.
+ * The stream keeps running in background; when the final event arrives,
+ * the tracker fires the completion callback to push results via heartbeat.
+ *
+ * Why not poll with tasks/get?
+ * The LangGraph A2A server cleans up tasks once the stream ends.
+ * tasks/get only works while the stream is active, so the stream itself
+ * is the only reliable way to receive the final result.
+ */
+
+import type { A2AClient, A2AStreamEvent } from "./a2a-client.js";
+
+export interface PendingTask {
+  taskId: string;
+  contextId?: string;
+  query: string;
+  threadId?: string;
+  submittedAt: number;
+  status: "submitted" | "working" | "completed" | "failed" | "timeout";
+}
+
+export interface TaskTrackerConfig {
+  a2aClient: A2AClient;
+  onTaskCompleted: (task: PendingTask, result: Record<string, unknown>) => void;
+  onTaskFailed: (task: PendingTask, error: string) => void;
+  timeoutMs?: number;
+  log?: (level: string, msg: string) => void;
+}
+
+export class PendingTaskTracker {
+  private tasks = new Map<string, PendingTask>();
+  private readonly timeoutMs: number;
+  private readonly a2a: A2AClient;
+  private readonly onCompleted: TaskTrackerConfig["onTaskCompleted"];
+  private readonly onFailed: TaskTrackerConfig["onTaskFailed"];
+  private readonly log: (level: string, msg: string) => void;
+
+  constructor(config: TaskTrackerConfig) {
+    this.a2a = config.a2aClient;
+    this.onCompleted = config.onTaskCompleted;
+    this.onFailed = config.onTaskFailed;
+    this.timeoutMs = config.timeoutMs ?? 600_000;
+    this.log = config.log ?? (() => {});
+  }
+
+  /**
+   * Register a task and start consuming its SSE stream in background.
+   * The stream iterator should already be started (first event consumed);
+   * this method takes ownership of the remaining stream.
+   */
+  trackStream(
+    taskId: string,
+    query: string,
+    stream: AsyncGenerator<A2AStreamEvent>,
+    opts?: { threadId?: string; contextId?: string },
+  ): PendingTask {
+    const task: PendingTask = {
+      taskId,
+      contextId: opts?.contextId,
+      query,
+      threadId: opts?.threadId,
+      submittedAt: Date.now(),
+      status: "submitted",
+    };
+    this.tasks.set(taskId, task);
+    this.log(
+      "info",
+      `[findoo-alpha-tracker] tracking stream for ${taskId}: "${query.slice(0, 60)}"`,
+    );
+
+    // Consume stream in background (fire-and-forget)
+    this.consumeStream(task, stream).catch((err) => {
+      this.log("warn", `[findoo-alpha-tracker] stream error for ${taskId}: ${err}`);
+    });
+
+    return task;
+  }
+
+  /**
+   * Submit a task for timeout tracking only (no stream).
+   * Used when stream is consumed elsewhere or for testing.
+   */
+  submit(
+    taskId: string,
+    query: string,
+    opts?: { threadId?: string; contextId?: string },
+  ): PendingTask {
+    const task: PendingTask = {
+      taskId,
+      contextId: opts?.contextId,
+      query,
+      threadId: opts?.threadId,
+      submittedAt: Date.now(),
+      status: "submitted",
+    };
+    this.tasks.set(taskId, task);
+    this.log("info", `[findoo-alpha-tracker] submitted task ${taskId}: "${query.slice(0, 60)}"`);
+    return task;
+  }
+
+  stop(): void {
+    // Mark remaining tasks as timed out
+    for (const [taskId, task] of this.tasks) {
+      task.status = "timeout";
+      this.tasks.delete(taskId);
+    }
+    this.log("info", "[findoo-alpha-tracker] stopped");
+  }
+
+  getPending(): PendingTask[] {
+    return [...this.tasks.values()];
+  }
+
+  private async consumeStream(
+    task: PendingTask,
+    stream: AsyncGenerator<A2AStreamEvent>,
+  ): Promise<void> {
+    const timeoutTimer = setTimeout(() => {
+      task.status = "timeout";
+      this.tasks.delete(task.taskId);
+      this.log("warn", `[findoo-alpha-tracker] task ${task.taskId} timed out`);
+      try {
+        this.onFailed(task, "Analysis timed out after " + Math.round(this.timeoutMs / 1000) + "s");
+      } catch (e) {
+        this.log("warn", `[findoo-alpha-tracker] onFailed callback error: ${e}`);
+      }
+      // Try to close the stream
+      stream.return(undefined as unknown as A2AStreamEvent).catch(() => {});
+    }, this.timeoutMs);
+
+    try {
+      let lastEvent: A2AStreamEvent | undefined;
+      // The final event only has status metadata; the actual result text
+      // accumulates in working events' status.message.parts[].text.
+      // We keep the last message from working events to extract the result.
+      let lastMessage: Record<string, unknown> | undefined;
+
+      for await (const event of stream) {
+        lastEvent = event;
+
+        if (event.kind === "error") {
+          clearTimeout(timeoutTimer);
+          task.status = "failed";
+          this.tasks.delete(task.taskId);
+          const errMsg =
+            (event.raw as Record<string, unknown>)?.error ??
+            event.status?.message ??
+            "Unknown error";
+          this.log("info", `[findoo-alpha-tracker] task ${task.taskId} error`);
+          this.onFailed(task, typeof errMsg === "string" ? errMsg : JSON.stringify(errMsg));
+          return;
+        }
+
+        // Track the latest message content from working events
+        const msg = event.status?.message;
+        if (msg && typeof msg === "object") {
+          lastMessage = msg as Record<string, unknown>;
+        }
+
+        // Update status from stream events
+        const state = event.status?.state;
+        if (state === "working" || state === "in-progress") {
+          task.status = "working";
+        }
+
+        if (event.final) {
+          clearTimeout(timeoutTimer);
+          task.status = "completed";
+          this.tasks.delete(task.taskId);
+          this.log("info", `[findoo-alpha-tracker] task ${task.taskId} completed via stream`);
+          // Use lastMessage (has actual content) over final event raw (only metadata)
+          const resultPayload = lastMessage ? { ...event.raw, message: lastMessage } : event.raw;
+          this.onCompleted(task, resultPayload);
+          return;
+        }
+      }
+
+      // Stream ended without final event — treat as completion if we got events
+      clearTimeout(timeoutTimer);
+      if (lastEvent) {
+        task.status = "completed";
+        this.tasks.delete(task.taskId);
+        this.log("info", `[findoo-alpha-tracker] task ${task.taskId} stream ended (no final flag)`);
+        const resultPayload = lastMessage
+          ? { ...lastEvent.raw, message: lastMessage }
+          : lastEvent.raw;
+        this.onCompleted(task, resultPayload);
+      } else {
+        task.status = "failed";
+        this.tasks.delete(task.taskId);
+        this.log("warn", `[findoo-alpha-tracker] task ${task.taskId} stream empty`);
+        this.onFailed(task, "Stream ended without events");
+      }
+    } catch (err) {
+      clearTimeout(timeoutTimer);
+      task.status = "failed";
+      this.tasks.delete(task.taskId);
+      const msg = err instanceof Error ? err.message : String(err);
+      this.log("warn", `[findoo-alpha-tracker] task ${task.taskId} stream error: ${msg}`);
+      this.onFailed(task, msg);
+    }
+  }
+}
+
+/** Extract a summary from completed task result (max chars) */
+export function extractSummary(result: Record<string, unknown>, maxLen = 2000): string {
+  // Try the message field (added by tracker from last working event)
+  const message = result.message as Record<string, unknown> | undefined;
+  if (message) {
+    const text = extractTextFromParts(message);
+    if (text) return text.length > maxLen ? text.slice(0, maxLen) + "…" : text;
+  }
+
+  // Try common A2A result shapes: artifacts
+  const artifacts = result.artifacts as Array<Record<string, unknown>> | undefined;
+  if (Array.isArray(artifacts) && artifacts.length > 0) {
+    const parts = artifacts[0].parts as Array<Record<string, unknown>> | undefined;
+    if (Array.isArray(parts)) {
+      const text = extractTextFromPartsList(parts);
+      if (text) return text.length > maxLen ? text.slice(0, maxLen) + "…" : text;
+    }
+  }
+
+  // Try status.message (often contains assistant reply)
+  const status = result.status as Record<string, unknown> | undefined;
+  const msg = status?.message as Record<string, unknown> | undefined;
+  if (msg) {
+    const text = extractTextFromParts(msg);
+    if (text) return text.length > maxLen ? text.slice(0, maxLen) + "…" : text;
+  }
+
+  // Fallback: stringify the whole result
+  const raw = JSON.stringify(result);
+  return raw.length > maxLen ? raw.slice(0, maxLen) + "…" : raw;
+}
+
+/** Extract text from a message object with parts array */
+function extractTextFromParts(msg: Record<string, unknown>): string | undefined {
+  const parts = msg.parts as Array<Record<string, unknown>> | undefined;
+  if (!Array.isArray(parts)) return undefined;
+  return extractTextFromPartsList(parts) || undefined;
+}
+
+/** Extract text from a parts array (handles kind=text and kind=data with text) */
+function extractTextFromPartsList(parts: Array<Record<string, unknown>>): string {
+  return parts
+    .filter((p) => typeof p.text === "string" && p.text.length > 0)
+    .map((p) => String(p.text))
+    .join("\n");
+}

package/src/register-tools.ts

@@ -0,0 +1,145 @@
+/**
+ * Register A2A-bridged tools for the Findoo financial analysis agent.
+ *
+ * Each tool delegates to the remote agent via A2A JSON-RPC 2.0:
+ *   POST /a2a/{assistant_id}  → method: "message/stream" (SSE)
+ *
+ * The agent has 37 skills covering A股/美股/港股/加密/宏观/风控 full spectrum.
+ * We expose a single tool (fin_analyze) that submits the query via SSE stream,
+ * grabs the taskId from the first event (~1-2s), and hands the remaining
+ * stream to PendingTaskTracker for background consumption + heartbeat push.
+ *
+ * Why stream-based instead of poll-based?
+ * The LangGraph A2A server cleans up tasks after the stream ends.
+ * tasks/get only works while the stream is active, so the stream itself
+ * is the only reliable channel to receive the final result.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { A2AClient, A2AStreamEvent } from "./a2a-client.js";
+import type { PluginConfig } from "./config.js";
+import type { PendingTaskTracker } from "./pending-task-tracker.js";
+
+const json = (payload: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+  details: payload,
+});
+
+export function registerTools(
+  api: OpenClawPluginApi,
+  config: PluginConfig,
+  a2a: A2AClient,
+  tracker?: PendingTaskTracker,
+) {
+  // ----------------------------------------------------------------
+  // fin_analyze — Primary analysis tool (A2A bridge to Findoo Agent)
+  // ----------------------------------------------------------------
+  api.registerTool({
+    name: "fin_analyze",
+    description:
+      "Findoo Alpha 专业金融分析 Agent（37 skills）。所有金融问题优先使用此工具，仅简单报价/单数据点查询（'茅台多少钱'/'BTC价格'）才用 fin_stock/fin_crypto 直查。" +
+      "覆盖：分析诊断、估值判断、策略设计、回测验证、筛选推荐、龙虎榜/游资/资金流监控、风险评估、报告生成。" +
+      "市场：A股/美股/港股/加密/宏观/衍生品/ETF。支持多轮对话(thread_id)。" +
+      "深度分析任务异步提交，完成后自动推送结果到对话。",
+
+    parameters: Type.Object({
+      query: Type.String({
+        description: "分析需求（自然语言），Agent 自动选择最佳 skill(s)",
+      }),
+      context: Type.Optional(
+        Type.Object(
+          {},
+          {
+            additionalProperties: true,
+            description: "附加结构化上下文（symbols, risk_profile, portfolio 等）",
+          },
+        ),
+      ),
+      thread_id: Type.Optional(
+        Type.String({ description: "复用之前的对话上下文 threadId，用于多轮分析" }),
+      ),
+    }),
+
+    async execute(_conversationId: string, params: Record<string, unknown>) {
+      const query = String(params.query ?? "");
+      if (!query) return json({ error: "query is required" });
+
+      try {
+        // Open SSE stream — first event arrives in ~1-2s with taskId.
+        // Use taskTimeoutMs (not requestTimeoutMs) since the stream may run
+        // for minutes in background while the tracker consumes it.
+        const stream = a2a.sendMessageStream(query, {
+          data: (params.context as Record<string, unknown>) ?? undefined,
+          threadId: params.thread_id as string | undefined,
+          timeoutMs: config.taskTimeoutMs,
+        });
+
+        // Read first event to get taskId
+        const first = await stream.next();
+        if (first.done) return json({ error: "No response from Findoo Agent" });
+
+        const firstEvent: A2AStreamEvent = first.value;
+
+        if (firstEvent.kind === "error") {
+          const errMsg =
+            (firstEvent.raw as Record<string, unknown>)?.error ??
+            firstEvent.status?.message ??
+            "Unknown stream error";
+          return json({
+            error: typeof errMsg === "string" ? errMsg : JSON.stringify(errMsg),
+          });
+        }
+
+        // If final already (instant response for simple queries), return directly
+        if (firstEvent.final) {
+          const result = firstEvent.status?.message ?? firstEvent.raw;
+          return json(result as Record<string, unknown>);
+        }
+
+        const taskId = extractTaskId(firstEvent.raw);
+        const contextId = (firstEvent.raw as Record<string, unknown>).contextId as
+          | string
+          | undefined;
+
+        // Hand the remaining stream to tracker for background consumption
+        if (taskId && tracker) {
+          tracker.trackStream(taskId, query, stream, {
+            threadId: params.thread_id as string | undefined,
+            contextId,
+          });
+          return json({
+            status: "submitted",
+            taskId,
+            message: `已提交深度分析任务 (${taskId.slice(0, 8)}…)，预计 1-5 分钟完成。你可以继续问其他问题，分析完成后会自动推送结果。`,
+          });
+        }
+
+        // No tracker — consume stream synchronously (fallback to blocking mode)
+        let lastEvent = firstEvent;
+        for await (const event of stream) {
+          lastEvent = event;
+          if (event.final) break;
+        }
+        const result = lastEvent.status?.message ?? lastEvent.raw;
+        return json(result as Record<string, unknown>);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return json({ error: `Findoo Agent request failed: ${msg}` });
+      }
+    },
+  });
+}
+
+/** Extract taskId from various A2A event/response shapes */
+function extractTaskId(raw: Record<string, unknown>): string | undefined {
+  // Direct id field (common in stream task events)
+  if (typeof raw.id === "string" && raw.id.length > 8) return raw.id;
+  // Nested: raw.taskId or raw.task_id
+  if (typeof raw.taskId === "string") return raw.taskId;
+  if (typeof raw.task_id === "string") return raw.task_id;
+  // Nested: raw.task.id
+  const task = raw.task as Record<string, unknown> | undefined;
+  if (typeof task?.id === "string") return task.id;
+  return undefined;
+}

package/test/a2a-client.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { A2AClient } from "../src/a2a-client.js";
+
+describe("A2AClient", () => {
+  let client: A2AClient;
+
+  beforeEach(() => {
+    client = new A2AClient("http://localhost:5085", "test-assistant-id");
+  });
+
+  it("constructs correct A2A message/send request", async () => {
+    const mockResponse = {
+      jsonrpc: "2.0",
+      id: "req-1",
+      result: { taskId: "task-123", status: "completed" },
+    };
+
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify(mockResponse), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+
+    const resp = await client.sendMessage("分析茅台");
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, opts] = fetchSpy.mock.calls[0];
+    expect(url).toBe("http://localhost:5085/a2a/test-assistant-id");
+    expect(opts?.method).toBe("POST");
+
+    const body = JSON.parse(opts?.body as string);
+    expect(body.jsonrpc).toBe("2.0");
+    expect(body.method).toBe("message/send");
+    expect(body.params.message.role).toBe("user");
+    expect(body.params.message.parts).toEqual([{ kind: "text", text: "分析茅台" }]);
+
+    expect(resp.result).toEqual({ taskId: "task-123", status: "completed" });
+
+    fetchSpy.mockRestore();
+  });
+
+  it("includes data part when context provided", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ jsonrpc: "2.0", id: "1", result: {} }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+
+    await client.sendMessage("分析个股", {
+      data: { symbol: "600519.SS", market: "cn" },
+    });
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body.params.message.parts).toHaveLength(2);
+    expect(body.params.message.parts[1]).toEqual({
+      kind: "data",
+      data: { symbol: "600519.SS", market: "cn" },
+    });
+
+    fetchSpy.mockRestore();
+  });
+
+  it("includes threadId when provided", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ jsonrpc: "2.0", id: "1", result: {} }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+
+    await client.sendMessage("继续分析", { threadId: "thread-abc" });
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body.params.thread).toEqual({ threadId: "thread-abc" });
+
+    fetchSpy.mockRestore();
+  });
+
+  it("throws on non-200 response", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response("Not Found", { status: 404, statusText: "Not Found" }),
+    );
+
+    await expect(client.sendMessage("test")).rejects.toThrow("A2A request failed: 404");
+
+    vi.restoreAllMocks();
+  });
+
+  it("sends tasks/get request", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: "1",
+          result: { taskId: "t-1", status: "completed", artifacts: [] },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+
+    const resp = await client.getTask("t-1");
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
+    expect(body.method).toBe("tasks/get");
+    expect(body.params.taskId).toBe("t-1");
+    expect(resp.result?.status).toBe("completed");
+
+    fetchSpy.mockRestore();
+  });
+});