refactor(plugin-sdk): share tool payload extraction

src/plugin-sdk/tool-payload.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { extractToolPayload } from "./tool-payload.js";
+
+describe("extractToolPayload", () => {
+  it("returns undefined for missing results", () => {
+    expect(extractToolPayload(undefined)).toBeUndefined();
+    expect(extractToolPayload(null)).toBeUndefined();
+  });
+
+  it("prefers explicit details payloads", () => {
+    expect(
+      extractToolPayload({
+        details: { ok: true },
+        content: [{ type: "text", text: '{"ignored":true}' }],
+      }),
+    ).toEqual({ ok: true });
+  });
+
+  it("parses JSON text blocks and falls back to raw text, content, or the whole result", () => {
+    expect(
+      extractToolPayload({
+        content: [
+          { type: "image", url: "https://example.com/a.png" },
+          { type: "text", text: '{"ok":true,"count":2}' },
+        ],
+      }),
+    ).toEqual({ ok: true, count: 2 });
+
+    expect(
+      extractToolPayload({
+        content: [{ type: "text", text: "not json" }],
+      }),
+    ).toBe("not json");
+
+    const content = [{ type: "image", url: "https://example.com/a.png" }];
+    expect(
+      extractToolPayload({
+        content,
+      }),
+    ).toBe(content);
+
+    const result = { status: "ok" };
+    expect(extractToolPayload(result)).toBe(result);
+  });
+});

src/plugin-sdk/tool-payload.ts

@@ -0,0 +1,43 @@
+type ToolPayloadTextBlock = {
+  type: "text";
+  text: string;
+};
+
+export type ToolPayloadCarrier = {
+  details?: unknown;
+  content?: unknown;
+};
+
+function isToolPayloadTextBlock(block: unknown): block is ToolPayloadTextBlock {
+  return (
+    !!block &&
+    typeof block === "object" &&
+    (block as { type?: unknown }).type === "text" &&
+    typeof (block as { text?: unknown }).text === "string"
+  );
+}
+
+/**
+ * Extract the most useful payload from tool result-like objects shared across
+ * outbound core flows and bundled plugin helpers.
+ */
+export function extractToolPayload(result: ToolPayloadCarrier | null | undefined): unknown {
+  if (!result) {
+    return undefined;
+  }
+  if (result.details !== undefined) {
+    return result.details;
+  }
+  const textBlock = Array.isArray(result.content)
+    ? result.content.find(isToolPayloadTextBlock)
+    : undefined;
+  const text = textBlock?.text;
+  if (!text) {
+    return result.content ?? result;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}