@iinm/plain-agent 1.8.4 → 1.8.5

package/src/tools/askURL.mjs

@@ -0,0 +1,209 @@
+/**
+ * @import { Tool } from '../tool'
+ */
+
+import { styleText } from "node:util";
+import { getGoogleCloudAccessToken } from "../providers/platform/googleCloud.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+/** @typedef {AskURLToolGeminiOptions | AskURLToolGeminiVertexAIOptions} AskURLToolOptions */
+
+/**
+ * @typedef {Object} AskURLToolGeminiOptions
+ * @property {"gemini"} provider
+ * @property {string=} baseURL
+ * @property {string} apiKey
+ * @property {string} model
+ */
+
+/**
+ * @typedef {Object} AskURLToolGeminiVertexAIOptions
+ * @property {"gemini-vertex-ai"} provider
+ * @property {string} baseURL
+ * @property {string=} account
+ * @property {string} model
+ */
+
+/**
+ * @typedef {Object} AskURLInput
+ * @property {string} question
+ */
+
+/**
+ * @param {AskURLToolOptions} config
+ * @returns {Tool}
+ */
+export function createAskURLTool(config) {
+  /**
+   * @param {AskURLInput} input
+   * @param {number} retryCount
+   * @returns {Promise<string | Error>}
+   */
+  async function askURL(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: [
+        {
+          url_context: {},
+        },
+      ],
+    };
+
+    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 askURL(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_url",
+      description:
+        "Use one or more provided URLs to answer a question. Include the URLs in your question.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          question: {
+            type: "string",
+            description:
+              "The question to ask, including one or more URLs to use as context.",
+          },
+        },
+        required: ["question"],
+      },
+    },
+
+    /**
+     * @param {AskURLInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) => await noThrow(async () => askURL(input, 0)),
+
+    /**
+     * @param {Record<string, unknown>} _input
+     * @returns {Record<string, unknown>}
+     */
+    maskApprovalInput: (_input) => {
+      return {};
+    },
+  };
+}

package/src/tools/askWeb.mjs

@@ -0,0 +1,208 @@
+/**
+ * @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)),
+
+    /**
+     * @param {Record<string, unknown>} _input
+     * @returns {Record<string, unknown>}
+     */
+    maskApprovalInput: (_input) => {
+      return {};
+    },
+  };
+}

package/src/tools/compactContext.d.ts

@@ -0,0 +1,4 @@
+export type CompactContextInput = {
+  memoryPath: string;
+  reason: string;
+};

package/src/tools/compactContext.mjs

@@ -0,0 +1,87 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ * @import { CompactContextInput } from './compactContext'
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENT_MEMORY_DIR } from "../env.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+export const compactContextToolName = "compact_context";
+
+/** @returns {Tool} */
+export function createCompactContextTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: compactContextToolName,
+      description:
+        "Discard prior messages and reload task state from a memory file.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          memoryPath: {
+            type: "string",
+            description: `Path to the memory file under ${AGENT_MEMORY_DIR}/.`,
+          },
+          reason: {
+            type: "string",
+            description: "The reason for compacting the context.",
+          },
+        },
+        required: ["memoryPath", "reason"],
+      },
+    },
+
+    // Implementation is injected by the agent so it can access subagent
+    // state (compact_context is not allowed during subagent execution).
+    get impl() {
+      return impl;
+    },
+
+    injectImpl(fn) {
+      impl = fn;
+    },
+  };
+
+  return tool;
+}
+
+/**
+ * Read a memory file and return the compact_context tool result string.
+ * Validates that the memoryPath is within the project memory directory.
+ * @param {CompactContextInput} input
+ * @returns {Promise<string | Error>}
+ */
+export async function readMemoryForCompaction(input) {
+  return await noThrow(async () => {
+    const absolutePath = path.resolve(input.memoryPath);
+    const memoryDir = path.resolve(AGENT_MEMORY_DIR);
+    const relativePath = path.relative(memoryDir, absolutePath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+      return new Error(
+        `Access denied: memoryPath must be within ${AGENT_MEMORY_DIR}`,
+      );
+    }
+
+    const memoryContent = await fs.readFile(absolutePath, {
+      encoding: "utf-8",
+    });
+
+    return [
+      "Context compacted. Prior conversation has been discarded.",
+      `Reason: ${input.reason}`,
+      `Memory file: ${input.memoryPath}`,
+      "",
+      "Resume the task using the memory file contents below.",
+      "",
+      memoryContent,
+    ].join("\n");
+  });
+}

package/src/tools/execCommand.d.ts

@@ -0,0 +1,22 @@
+export type ExecCommandInput = {
+  command: string;
+  args?: string[];
+};
+
+export type ExecCommandConfig = {
+  sandbox?: ExecCommandSanboxConfig;
+};
+
+export type ExecCommandSanboxConfig = {
+  command: string;
+  args?: string[];
+  separator?: string;
+  rules?: {
+    pattern: {
+      command: string;
+      args?: string[];
+    };
+    mode: "sandbox" | "unsandboxed";
+    additionalArgs?: string[];
+  }[];
+};