@iinm/plain-agent 1.1.1 → 1.3.0

package/src/config.d.ts

@@ -1,11 +1,9 @@
 import { ModelDefinition, PlatformConfig } from "./modelDefinition";
 import { ToolUsePattern } from "./tool";
+import { AskURLToolOptions } from "./tools/askURL.mjs";
+import { AskWebToolOptions } from "./tools/askWeb.mjs";
 import { ExecCommandSanboxConfig } from "./tools/execCommand";
-
-export type ClaudeCodePluginConfig = {
-  name: string;
-  path: string;
-};
+import { ClaudeCodePluginRepo } from "./claudeCodePlugin.mjs";
 
 export type AppConfig = {
   model?: string;
@@ -18,24 +16,12 @@ export type AppConfig = {
   };
   sandbox?: ExecCommandSanboxConfig;
   tools?: {
-    /**
-     * - Vertex AI: requires baseURL and account
-     * - AI Studio: requires apiKey
-     */
-    askGoogle?: {
-      platform?: "vertex-ai";
-      baseURL?: string;
-      account?: string;
-      apiKey?: string;
-      model?: string;
-    };
-    searchWeb?: {
-      tavilyApiKey?: string;
-    };
+    askWeb?: AskWebToolOptions;
+    askURL?: AskURLToolOptions;
   };
   mcpServers?: Record<string, MCPServerConfig>;
   notifyCmd?: string;
-  claudeCodePlugins?: ClaudeCodePluginConfig[];
+  claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 
 export type MCPServerConfig = {

package/src/config.mjs

@@ -76,14 +76,18 @@ export async function loadAppConfig(options = {}) {
       },
       sandbox: config.sandbox ?? merged.sandbox,
       tools: {
-        searchWeb: {
-          ...(merged.tools?.searchWeb ?? {}),
-          ...(config.tools?.searchWeb ?? {}),
-        },
-        askGoogle: {
-          ...(merged.tools?.askGoogle ?? {}),
-          ...(config.tools?.askGoogle ?? {}),
-        },
+        askWeb: config.tools?.askWeb
+          ? {
+              ...(merged.tools?.askWeb ?? {}),
+              ...config.tools.askWeb,
+            }
+          : merged.tools?.askWeb,
+        askURL: config.tools?.askURL
+          ? {
+              ...(merged.tools?.askURL ?? {}),
+              ...config.tools.askURL,
+            }
+          : merged.tools?.askWeb,
       },
       mcpServers: {
         ...(merged.mcpServers ?? {}),

package/src/context/loadAgentRoles.mjs

@@ -1,3 +1,5 @@
+/** @import { ClaudeCodePlugin } from "../claudeCodePlugin.mjs" */
+
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -7,7 +9,6 @@ import {
   AGENT_PROJECT_METADATA_DIR,
   AGENT_ROOT,
   AGENT_USER_CONFIG_DIR,
-  CLAUDE_CODE_PLUGIN_DIR,
 } from "../env.mjs";
 
 /**
@@ -21,10 +22,11 @@ import {
 
 /**
  * Load all agent roles from the predefined directories.
- * @param {Array<{name: string, path: string}>} [claudeCodePlugins]
+ * @param {ClaudeCodePlugin[]} [claudeCodePlugins]
  * @returns {Promise<Map<string, AgentRole>>}
  */
 export async function loadAgentRoles(claudeCodePlugins) {
+  /** @type {Array<{dir: string, idPrefix: string, only?: RegExp}>} */
   const agentDirs = [
     {
       dir: path.resolve(AGENT_ROOT, ".config", "agents.predefined"),
@@ -41,11 +43,10 @@ export async function loadAgentRoles(claudeCodePlugins) {
   // Add plugin directories if provided
   if (claudeCodePlugins) {
     for (const plugin of claudeCodePlugins) {
-      const pluginBase = path.join(CLAUDE_CODE_PLUGIN_DIR, plugin.path);
-
       agentDirs.push({
-        dir: path.join(pluginBase, "agents"),
+        dir: path.join(plugin.path, "agents"),
         idPrefix: `claude/${plugin.name}:`,
+        only: plugin.only,
       });
     }
   }
@@ -53,7 +54,7 @@ export async function loadAgentRoles(claudeCodePlugins) {
   /** @type {Map<string, AgentRole>} */
   const roles = new Map();
 
-  for (const { dir, idPrefix } of agentDirs) {
+  for (const { dir, idPrefix, only } of agentDirs) {
     const files = await getMarkdownFiles(dir).catch((err) => {
       if (err.code !== "ENOENT") {
         console.warn(`Failed to list agent roles in ${dir}:`, err);
@@ -70,6 +71,11 @@ export async function loadAgentRoles(claudeCodePlugins) {
 
       if (content === null) continue;
 
+      // Filter by only pattern if specified
+      if (only && !only.test(file)) {
+        continue;
+      }
+
       let role = parseAgentRole(file, content, fullPath, idPrefix);
       if (role.import) {
         role = await mergeRemoteRole(role, file, fullPath);

package/src/context/loadPrompts.mjs

@@ -1,3 +1,5 @@
+/** @import { ClaudeCodePlugin } from "../claudeCodePlugin.mjs" */
+
 import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
@@ -8,7 +10,6 @@ import {
   AGENT_PROJECT_METADATA_DIR,
   AGENT_ROOT,
   AGENT_USER_CONFIG_DIR,
-  CLAUDE_CODE_PLUGIN_DIR,
 } from "../env.mjs";
 
 /**
@@ -25,10 +26,11 @@ import {
 
 /**
  * Load all prompts from the predefined directories.
- * @param {Array<{name: string, path: string}>} [claudeCodePlugins]
+ * @param {ClaudeCodePlugin[]} [claudeCodePlugins]
  * @returns {Promise<Map<string, Prompt>>}
  */
 export async function loadPrompts(claudeCodePlugins) {
+  /** @type {Array<{dir: string, idPrefix: string, only?: RegExp}>} */
   const promptDirs = [
     {
       dir: path.resolve(AGENT_ROOT, ".config", "prompts.predefined"),
@@ -49,18 +51,18 @@ export async function loadPrompts(claudeCodePlugins) {
   // Add plugin directories if provided
   if (claudeCodePlugins) {
     for (const plugin of claudeCodePlugins) {
-      const pluginBase = path.join(CLAUDE_CODE_PLUGIN_DIR, plugin.path);
-
       // Commands
       promptDirs.push({
-        dir: path.join(pluginBase, "commands"),
+        dir: path.join(plugin.path, "commands"),
         idPrefix: `claude/${plugin.name}/commands:`,
+        only: plugin.only,
       });
 
       // Skills
       promptDirs.push({
-        dir: path.join(pluginBase, "skills"),
+        dir: path.join(plugin.path, "skills"),
         idPrefix: `claude/${plugin.name}/skills:`,
+        only: plugin.only,
       });
     }
   }
@@ -68,7 +70,7 @@ export async function loadPrompts(claudeCodePlugins) {
   /** @type {Map<string, Prompt>} */
   const prompts = new Map();
 
-  for (const { dir, idPrefix } of promptDirs) {
+  for (const { dir, idPrefix, only } of promptDirs) {
     const files = await getMarkdownFiles(dir).catch((err) => {
       if (err.code !== "ENOENT") {
         console.warn(`Failed to list prompts in ${dir}:`, err);
@@ -85,6 +87,11 @@ export async function loadPrompts(claudeCodePlugins) {
 
       if (content === null) continue;
 
+      // Filter by only pattern if specified
+      if (only && !only.test(file)) {
+        continue;
+      }
+
       //  Ignore all files in the skills/ directory except for SKILL.md.
       if (fullPath.match(/\/skills\//) && !file.endsWith("/SKILL.md")) {
         continue;
@@ -240,6 +247,7 @@ async function getMarkdownFiles(dir, baseDir = dir) {
  */
 function parsePrompt(relativePath, fileContent, fullPath, idPrefix = "") {
   const rawId = relativePath.replace(/\/SKILL\.md$/, "").replace(/\.md$/, "");
+  const isSkill = relativePath.endsWith("SKILL.md");
   const isShortcut = rawId.startsWith("shortcuts/");
   const id = isShortcut
     ? idPrefix + rawId.replace(/^shortcuts\//, "")
@@ -257,7 +265,7 @@ function parsePrompt(relativePath, fileContent, fullPath, idPrefix = "") {
       content: fileContent.trim(),
       filePath: fullPath,
       isShortcut,
-      isSkill: relativePath.endsWith("SKILL.md"),
+      isSkill,
     };
   }
 
@@ -281,7 +289,7 @@ function parsePrompt(relativePath, fileContent, fullPath, idPrefix = "") {
         parseFrontmatterField(match[1], "user-invocable") === "true" ||
         undefined,
       isShortcut,
-      isSkill: relativePath.endsWith("SKILL.md"),
+      isSkill,
     };
   }
   const userInvocable = frontmatter["user-invocable"];
@@ -304,7 +312,6 @@ function parsePrompt(relativePath, fileContent, fullPath, idPrefix = "") {
  * @param {string} field
  * @returns {string | undefined}
  */
-
 function parseFrontmatterField(frontmatter, field) {
   const regex = new RegExp(`^${field}:\\s*(.*)$`, "m");
   const match = frontmatter.match(regex);

package/src/main.mjs

@@ -4,6 +4,10 @@
 
 import { styleText } from "node:util";
 import { createAgent } from "./agent.mjs";
+import {
+  installClaudeCodePlugins,
+  resolvePluginPaths,
+} from "./claudeCodePlugin.mjs";
 import { parseCliArgs, printHelp } from "./cliArgs.mjs";
 import { startBatchSession } from "./cliBatch.mjs";
 import { startInteractiveSession } from "./cliInteractive.mjs";
@@ -18,23 +22,22 @@ import {
 import { setupMCPServer } from "./mcp.mjs";
 import { createModelCaller } from "./modelCaller.mjs";
 import { createPrompt } from "./prompt.mjs";
-import { createAskGoogleTool } from "./tools/askGoogle.mjs";
+import { createAskURLTool } from "./tools/askURL.mjs";
+import { createAskWebTool } from "./tools/askWeb.mjs";
 import { createDelegateToSubagentTool } from "./tools/delegateToSubagent.mjs";
 import { createExecCommandTool } from "./tools/execCommand.mjs";
-import { fetchWebPageTool } from "./tools/fetchWebPage.mjs";
 import { patchFileTool } from "./tools/patchFile.mjs";
 import { createReportAsSubagentTool } from "./tools/reportAsSubagent.mjs";
-import { createTavilySearchTool } from "./tools/tavilySearch.mjs";
 import { createTmuxCommandTool } from "./tools/tmuxCommand.mjs";
 import { writeFileTool } from "./tools/writeFile.mjs";
 import { createToolUseApprover } from "./toolUseApprover.mjs";
 
 const cliArgs = parseCliArgs(process.argv);
-if (cliArgs.showHelp) {
+if (cliArgs.subcommand.type === "help") {
   printHelp();
 }
 
-if (cliArgs.listModels) {
+if (cliArgs.subcommand.type === "list-models") {
   const { appConfig } = await loadAppConfig({ skipTrustCheck: true });
   if (!appConfig.models || appConfig.models.length === 0) {
     console.error("No models found in configuration.");
@@ -49,6 +52,11 @@ if (cliArgs.listModels) {
   process.exit(0);
 }
 
+if (cliArgs.subcommand.type === "install-claude-code-plugins") {
+  await installClaudeCodePlugins();
+  process.exit(0);
+}
+
 (async () => {
   const startTime = new Date();
   const sessionId = [
@@ -57,12 +65,18 @@ if (cliArgs.listModels) {
       `0${startTime.getMinutes()}`.slice(-2),
   ].join("-");
   const tmuxSessionId = `agent-${sessionId}`;
-  const isBatchMode = Boolean(cliArgs.batch);
+
+  const isBatchMode = cliArgs.subcommand.type === "batch";
+  const configFiles =
+    cliArgs.subcommand.type === "batch" ||
+    cliArgs.subcommand.type === "interactive"
+      ? cliArgs.subcommand.config
+      : [];
 
   const { appConfig, loadedConfigPath } = await loadAppConfig({
     skipUserConfig: isBatchMode,
     skipTrustCheck: isBatchMode,
-    configFiles: cliArgs.config,
+    configFiles,
   });
 
   // In batch mode, skip human-readable output
@@ -122,9 +136,17 @@ if (cliArgs.listModels) {
     }
   }
 
-  const modelNameWithVariant = cliArgs.model || appConfig.model || "";
-  const agentRoles = await loadAgentRoles(appConfig.claudeCodePlugins);
-  const prompts = await loadPrompts(appConfig.claudeCodePlugins);
+  const modelFromConfig = appConfig.model || "";
+  const modelFromArgs =
+    cliArgs.subcommand.type === "batch" ||
+    cliArgs.subcommand.type === "interactive"
+      ? cliArgs.subcommand.model
+      : null;
+  const modelNameWithVariant = modelFromArgs || modelFromConfig;
+
+  const pluginPaths = resolvePluginPaths(appConfig.claudeCodePlugins ?? []);
+  const agentRoles = await loadAgentRoles(pluginPaths);
+  const prompts = await loadPrompts(pluginPaths);
 
   const prompt = createPrompt({
     username: USER_NAME,
@@ -142,23 +164,16 @@ if (cliArgs.listModels) {
     writeFileTool,
     patchFileTool,
     createTmuxCommandTool({ sandbox: appConfig.sandbox }),
-    fetchWebPageTool,
     createDelegateToSubagentTool(),
     createReportAsSubagentTool(),
   ];
 
-  if (appConfig.tools?.searchWeb?.tavilyApiKey) {
-    builtinTools.push(createTavilySearchTool(appConfig.tools.searchWeb));
+  if (appConfig.tools?.askWeb) {
+    builtinTools.push(createAskWebTool(appConfig.tools.askWeb));
   }
 
-  if (appConfig.tools?.askGoogle) {
-    builtinTools.push(
-      createAskGoogleTool({
-        platform: appConfig.tools.askGoogle.platform,
-        baseURL: appConfig.tools.askGoogle.baseURL,
-        apiKey: appConfig.tools.askGoogle.apiKey,
-      }),
-    );
+  if (appConfig.tools?.askURL) {
+    builtinTools.push(createAskURLTool(appConfig.tools.askURL));
   }
 
   const toolUseApprover = createToolUseApprover({
@@ -224,19 +239,20 @@ if (cliArgs.listModels) {
     },
   };
 
-  if (isBatchMode) {
-    if (!cliArgs.batch) {
+  if (cliArgs.subcommand.type === "batch") {
+    const task = cliArgs.subcommand.task;
+    if (!task) {
       throw new Error("Batch task is required in batch mode");
     }
     await startBatchSession({
       ...sessionOptions,
-      task: cliArgs.batch,
+      task,
     });
   } else {
     startInteractiveSession({
       ...sessionOptions,
       notifyCmd: appConfig.notifyCmd || AGENT_NOTIFY_CMD_DEFAULT,
-      claudeCodePlugins: appConfig.claudeCodePlugins,
+      claudeCodePlugins: resolvePluginPaths(appConfig.claudeCodePlugins ?? []),
     });
   }
 })().catch((err) => {

package/src/mcp.mjs

@@ -1,12 +1,11 @@
 /**
- * @import { Client } from "@modelcontextprotocol/sdk/client/index.js";
- * @import { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
  * @import { StructuredToolResultContent, Tool, ToolImplementation } from "./tool";
  * @import { MCPServerConfig } from "./config";
  */
 
 import { mkdir, open } from "node:fs/promises";
 import path from "node:path";
+import { Client } from "@modelcontextprotocol/client";
 import { AGENT_PROJECT_METADATA_DIR } from "./env.mjs";
 import { writeTmpFile } from "./tmpfile.mjs";
 import { noThrow } from "./utils/noThrow.mjs";
@@ -52,7 +51,7 @@ export async function setupMCPServer(serverName, serverConfig) {
 /**
  * @typedef {Object} MCPClientOptions
  * @property {string} serverName - The name of the MCP server.
- * @property {StdioServerParameters} params - The transport to use for the client.
+ * @property {import("@modelcontextprotocol/client").StdioServerParameters} params - The transport to use for the client.
  */
 
 /**
@@ -60,10 +59,7 @@ export async function setupMCPServer(serverName, serverConfig) {
  * @returns {Promise<{client: Client; cleanup: () => void}>} - The MCP client and cleanup function.
  */
 async function startMCPServer(options) {
-  const mcpClient = await import("@modelcontextprotocol/sdk/client/index.js");
-  const mcpClientStdio = await import(
-    "@modelcontextprotocol/sdk/client/stdio.js"
-  );
+  const mcpClient = await import("@modelcontextprotocol/client");
 
   const client = new mcpClient.Client({
     name: "undefined",
@@ -83,7 +79,7 @@ async function startMCPServer(options) {
   const logPath = path.join(logDir, `mcp--${options.serverName}.stderr`);
   const stderrLogFile = await open(logPath, "a");
 
-  const transport = new mcpClientStdio.StdioClientTransport({
+  const transport = new mcpClient.StdioClientTransport({
     ...restParams,
     env: env ? { ...defaultEnv, ...env } : undefined,
     stderr: stderrLogFile.fd,

package/src/tools/askURL.mjs

@@ -0,0 +1,201 @@
+/**
+ * @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} AskWebInput
+ * @property {string} question
+ */
+
+/**
+ * @param {AskURLToolOptions} config
+ * @returns {Tool}
+ */
+export function createAskURLTool(config) {
+  /**
+   * @param {AskWebInput} 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 {AskWebInput} input
+     * @returns {Promise<string | Error>}
+     */
+    impl: async (input) => await noThrow(async () => askURL(input, 0)),
+  };
+}