@iinm/plain-agent 1.1.1 → 1.3.0

package/src/tools/askWeb.mjs

@@ -0,0 +1,200 @@
+/**
+ * @import { Tool } from '../tool'
+ */
+
+import { styleText } from "node:util";
+import { getGoogleCloudAccessToken } from "../providers/platform/googleCloud.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/** @typedef {AskWebToolGeminiOptions | AskWebToolGeminiVertexAIOptions} AskWebToolOptions */
+
+/**
+ * @typedef {Object} AskWebToolGeminiOptions
+ * @property {"gemini"} provider
+ * @property {string=} baseURL
+ * @property {string} apiKey
+ * @property {string} model
+ */
+
+/**
+ * @typedef {Object} AskWebToolGeminiVertexAIOptions
+ * @property {"gemini-vertex-ai"} provider
+ * @property {string} baseURL
+ * @property {string=} account
+ * @property {string} model
+ */
+
+/**
+ * @typedef {Object} AskWebInput
+ * @property {string} question
+ */
+
+/**
+ * @param {AskWebToolOptions} config
+ * @returns {Tool}
+ */
+export function createAskWebTool(config) {
+  /**
+   * @param {AskWebInput} input
+   * @param {number} retryCount
+   * @returns {Promise<string | Error>}
+   */
+  async function askWeb(input, retryCount = 0) {
+    const model = config.model ?? "gemini-3-flash-preview";
+    const url =
+      config.provider === "gemini-vertex-ai"
+        ? `${config.baseURL}/publishers/google/models/${config.model}:generateContent`
+        : config.baseURL
+          ? `${config.baseURL}/models/${model}:generateContent`
+          : `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+
+    /** @type {Record<string,string>} */
+    const authHeader =
+      config.provider === "gemini-vertex-ai"
+        ? {
+            Authorization: `Bearer ${await getGoogleCloudAccessToken(config.account)}`,
+          }
+        : {
+            "x-goog-api-key": config.apiKey ?? "",
+          };
+
+    const data = {
+      contents: [
+        {
+          role: "user",
+          parts: [
+            {
+              text: `I need a comprehensive answer to this question. Please note that I don't have access to external URLs, so include all relevant facts, data, or explanations directly in your response. Avoid referencing links I can't open.
+
+Question: ${input.question}`,
+            },
+          ],
+        },
+      ],
+      tools: [
+        {
+          google_search: {},
+        },
+      ],
+    };
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...authHeader,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(data),
+      signal: AbortSignal.timeout(120 * 1000),
+    });
+
+    if (response.status === 429 || response.status >= 500) {
+      const interval = Math.min(2 * 2 ** retryCount, 16);
+      console.error(
+        styleText(
+          "yellow",
+          `Google API returned ${response.status}. Retrying in ${interval} seconds...`,
+        ),
+      );
+      await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+      return askWeb(input, retryCount + 1);
+    }
+
+    if (!response.ok) {
+      return new Error(
+        `Failed to ask Web: status=${response.status}, body=${await response.text()}`,
+      );
+    }
+
+    const body = await response.json();
+
+    const candidate = body.candidates?.[0];
+    const text = candidate?.content?.parts?.[0]?.text;
+    /** @type {{segment?:{startIndex:number,endIndex:number,text:string},groundingChunkIndices?:number[]}[] | undefined} */
+    const supports = candidate?.groundingMetadata?.groundingSupports;
+    /** @type {{web?:{uri:string,title:string}}[] | undefined} */
+    const chunks = candidate?.groundingMetadata?.groundingChunks;
+
+    if (typeof text !== "string") {
+      return new Error(
+        `Unexpected response format from Google: ${JSON.stringify(body)}`,
+      );
+    }
+
+    /**
+     * @param {string} source
+     * @param {number} byteIndex
+     * @param {string} insertText
+     */
+    const insertTextAtUtf8ByteIndex = (source, byteIndex, insertText) => {
+      const sourceBuffer = Buffer.from(source, "utf8");
+      const normalizedByteIndex = Math.max(
+        0,
+        Math.min(byteIndex, sourceBuffer.length),
+      );
+
+      return Buffer.concat([
+        sourceBuffer.subarray(0, normalizedByteIndex),
+        Buffer.from(insertText, "utf8"),
+        sourceBuffer.subarray(normalizedByteIndex),
+      ]).toString("utf8");
+    };
+
+    // Sort by end_index desc because Gemini grounding indexes are byte offsets
+    // into the original UTF-8 text.
+    const sortedSupports = supports?.toSorted(
+      (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
+    );
+
+    // Insert citations using UTF-8 byte offsets.
+    let textWithCitations = text;
+    for (const support of sortedSupports ?? []) {
+      const endIndex = support.segment?.endIndex;
+      if (
+        typeof endIndex !== "number" ||
+        !support.groundingChunkIndices?.length
+      ) {
+        continue;
+      }
+
+      textWithCitations = insertTextAtUtf8ByteIndex(
+        textWithCitations,
+        endIndex,
+        ` [${support.groundingChunkIndices.map((i) => i + 1).join(", ")}] `,
+      );
+    }
+
+    const chunkString = (chunks ?? [])
+      .map(
+        (chunk, index) =>
+          `- [${index + 1} - ${chunk.web?.title}](${chunk.web?.uri})`,
+      )
+      .join("\n");
+
+    return [textWithCitations, chunkString].join("\n\n");
+  }
+
+  return {
+    def: {
+      name: "ask_web",
+      description:
+        "Use the web search to answer questions that need up-to-date information or supporting sources.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description: "The question to ask",
+          },
+        },
+        required: ["question"],
+      },
+    },
+
+    /**
+     * @param {AskWebInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) => await noThrow(async () => askWeb(input, 0)),
+  };
+}

package/src/tools/askGoogle.mjs

@@ -1,135 +0,0 @@
-/**
- * @import { Tool } from '../tool'
- */
-
-import { styleText } from "node:util";
-import { getGoogleCloudAccessToken } from "../providers/platform/googleCloud.mjs";
-import { noThrow } from "../utils/noThrow.mjs";
-
-/**
- * @typedef {Object} AskGoogleToolOptions
- * @property {"vertex-ai"=} platform
- * @property {string=} baseURL
- * @property {string=} apiKey - API key for Google AI Studio
- * @property {string=} account - The Google Cloud account to use for Vertex AI
- * @property {string=} model
- */
-
-/**
- * @typedef {Object} AskGoogleInput
- * @property {string} question
- */
-
-/**
- * @param {AskGoogleToolOptions} config
- * @returns {Tool}
- */
-export function createAskGoogleTool(config) {
-  /**
-   * @param {AskGoogleInput} input
-   * @param {number} retryCount
-   * @returns {Promise<string | Error>}
-   */
-  async function askGoogle(input, retryCount = 0) {
-    const model = config.model ?? "gemini-3-flash-preview";
-    const url =
-      config.platform === "vertex-ai" && config.baseURL
-        ? `${config.baseURL}/publishers/google/models/${model}:generateContent`
-        : config.baseURL
-          ? `${config.baseURL}/models/${model}:generateContent`
-          : `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
-
-    /** @type {Record<string,string>} */
-    const authHeader =
-      config.platform === "vertex-ai"
-        ? {
-            Authorization: `Bearer ${await getGoogleCloudAccessToken(config.account)}`,
-          }
-        : {
-            "x-goog-api-key": config.apiKey ?? "",
-          };
-
-    const data = {
-      contents: [
-        {
-          role: "user",
-          parts: [
-            {
-              text: `I need a comprehensive answer to this question. Please note that I don't have access to external URLs, so include all relevant facts, data, or explanations directly in your response. Avoid referencing links I can't open.
-
-Question: ${input.question}`,
-            },
-          ],
-        },
-      ],
-      tools: [
-        {
-          google_search: {},
-        },
-      ],
-    };
-
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        ...authHeader,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(data),
-      signal: AbortSignal.timeout(120 * 1000),
-    });
-
-    if (response.status === 429 || response.status >= 500) {
-      const interval = Math.min(2 * 2 ** retryCount, 16);
-      console.error(
-        styleText(
-          "yellow",
-          `Google API returned ${response.status}. Retrying in ${interval} seconds...`,
-        ),
-      );
-      await new Promise((resolve) => setTimeout(resolve, interval * 1000));
-      return askGoogle(input, retryCount + 1);
-    }
-
-    if (!response.ok) {
-      return new Error(
-        `Failed to ask Google: status=${response.status}, body=${await response.text()}`,
-      );
-    }
-
-    const body = await response.json();
-
-    const answer = body.candidates?.[0]?.content?.parts?.[0]?.text;
-
-    if (typeof answer !== "string") {
-      return new Error(
-        `Unexpected response format from Google: ${JSON.stringify(body)}`,
-      );
-    }
-
-    return answer;
-  }
-
-  return {
-    def: {
-      name: "ask_google",
-      description: "Ask Google a question using natural language",
-      inputSchema: {
-        type: "object",
-        properties: {
-          question: {
-            type: "string",
-            description: "The question to ask Google",
-          },
-        },
-        required: ["question"],
-      },
-    },
-
-    /**
-     * @param {AskGoogleInput} input
-     * @returns {Promise<string | Error>}
-     */
-    impl: async (input) => await noThrow(async () => askGoogle(input, 0)),
-  };
-}

package/src/tools/fetchWebPage.mjs

@@ -1,96 +0,0 @@
-/**
- * @import { Tool } from '../tool'
- */
-
-import { writeTmpFile } from "../tmpfile.mjs";
-import { noThrow } from "../utils/noThrow.mjs";
-
-const MAX_CONTENT_LENGTH = 1024 * 8;
-
-/** @type {Tool} */
-export const fetchWebPageTool = {
-  def: {
-    name: "fetch_web_page",
-    description:
-      "Fetch and extract web page content from a given URL, returning it as Markdown.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        url: {
-          type: "string",
-        },
-      },
-      required: ["url"],
-    },
-  },
-
-  /**
-   * @param {Record<string, unknown>} input
-   * @returns {Record<string, unknown>}
-   */
-  maskApprovalInput: (input) => {
-    try {
-      const url = new URL(String(input.url));
-      return { url: url.hostname };
-    } catch {
-      return input;
-    }
-  },
-
-  /**
-   * @param {{url: string}} input
-   * @returns {Promise<string | Error>}
-   */
-  impl: async (input) =>
-    await noThrow(async () => {
-      const { Readability } = await import("@mozilla/readability");
-      const { JSDOM } = await import("jsdom");
-      const TurndownService = (await import("turndown")).default;
-
-      const response = await fetch(input.url, {
-        signal: AbortSignal.timeout(30 * 1000),
-      });
-      const html = await response.text();
-      const dom = new JSDOM(html, { url: input.url });
-      const reader = new Readability(dom.window.document);
-      const article = reader.parse();
-
-      if (!article?.content) {
-        return "";
-      }
-
-      const turndownService = new TurndownService({
-        headingStyle: "atx",
-        bulletListMarker: "-",
-        codeBlockStyle: "fenced",
-      });
-
-      const markdown = turndownService.turndown(article.content);
-      const trimmedMarkdown = markdown.trim();
-
-      if (trimmedMarkdown.length <= MAX_CONTENT_LENGTH) {
-        return trimmedMarkdown;
-      }
-
-      const filePath = await writeTmpFile(
-        trimmedMarkdown,
-        "read_web_page",
-        "md",
-      );
-
-      const lineCount = trimmedMarkdown.split("\n").length;
-
-      return [
-        `Content is large (${trimmedMarkdown.length} characters, ${lineCount} lines) and saved to ${filePath}`,
-        "- Use rg / awk to read specific parts",
-      ].join("\n");
-    }),
-};
-
-// Playground
-// (async () => {
-//   const input = {
-//     url: "https://devin.ai/agents101",
-//   };
-//   console.log(await fetchWebPageTool.impl(input));
-// })();

package/src/tools/tavilySearch.d.ts

@@ -1,6 +0,0 @@
-/**
- * @doc https://docs.tavily.com/documentation/api-reference/endpoint/search
- */
-export type TavilySearchInput = {
-  query: string;
-};

package/src/tools/tavilySearch.mjs

@@ -1,57 +0,0 @@
-/**
- * @import { Tool } from '../tool'
- * @import { TavilySearchInput } from './tavilySearch'
- */
-
-import { noThrow } from "../utils/noThrow.mjs";
-
-/**
- * @param {{tavilyApiKey?: string}} config
- * @returns {Tool}
- */
-export function createTavilySearchTool(config) {
-  return {
-    def: {
-      name: "search_web",
-      description: "Search the web for information",
-      inputSchema: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-          },
-        },
-        required: ["query"],
-      },
-    },
-
-    /**
-     * @param {TavilySearchInput} input
-     * @returns {Promise<string | Error>}
-     */
-    impl: async (input) =>
-      await noThrow(async () => {
-        const response = await fetch("https://api.tavily.com/search", {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${config.tavilyApiKey}`,
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({
-            ...input,
-            max_results: 5,
-          }),
-          signal: AbortSignal.timeout(120 * 1000),
-        });
-
-        if (!response.ok) {
-          return new Error(
-            `Failed to search: status=${response.status}, body=${await response.text()}`,
-          );
-        }
-
-        const body = await response.json();
-        return JSON.stringify(body);
-      }),
-  };
-}