@iinm/plain-agent 1.0.0

package/src/config.d.ts

@@ -0,0 +1,48 @@
+import { ModelDefinition, PlatformConfig } from "./modelDefinition";
+import { ToolUsePattern } from "./tool";
+import { ExecCommandSanboxConfig } from "./tools/execCommand";
+
+export type ClaudeCodePluginConfig = {
+  name: string;
+  path: string;
+};
+
+export type AppConfig = {
+  model?: string;
+  models?: ModelDefinition[];
+  platforms?: PlatformConfig[];
+  autoApproval?: {
+    patterns?: ToolUsePattern[];
+    maxApprovals?: number;
+    defaultAction?: "deny" | "ask";
+  };
+  sandbox?: ExecCommandSanboxConfig;
+  tools?: {
+    tavily?: {
+      apiKey?: string;
+    };
+    /**
+     * - Vertex AI: requires baseURL and account
+     * - AI Studio: requires apiKey
+     */
+    askGoogle?: {
+      platform?: "vertex-ai";
+      baseURL?: string;
+      account?: string;
+      apiKey?: string;
+      model?: string;
+    };
+  };
+  mcpServers?: Record<string, MCPServerConfig>;
+  notifyCmd?: string;
+  claudeCodePlugins?: ClaudeCodePluginConfig[];
+};
+
+export type MCPServerConfig = {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  options?: {
+    enabledTools?: string[];
+  };
+};

package/src/config.mjs

@@ -0,0 +1,168 @@
+/**
+ * @import { AppConfig } from "./config";
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { styleText } from "node:util";
+import {
+  AGENT_PROJECT_METADATA_DIR,
+  AGENT_ROOT,
+  AGENT_USER_CONFIG_DIR,
+  TRUSTED_CONFIG_HASHES_DIR,
+} from "./env.mjs";
+import { evalJSONConfig } from "./utils/evalJSONConfig.mjs";
+
+/**
+ * @returns {Promise<{appConfig: AppConfig, loadedConfigPath: string[]}>}
+ */
+export async function loadAppConfig() {
+  const paths = [
+    `${AGENT_ROOT}/.config/config.predefined.json`,
+    `${AGENT_USER_CONFIG_DIR}/config.json`,
+    `${AGENT_USER_CONFIG_DIR}/config.local.json`,
+    `${AGENT_PROJECT_METADATA_DIR}/config.json`,
+    `${AGENT_PROJECT_METADATA_DIR}/config.local.json`,
+  ];
+
+  /** @type {string[]} */
+  const loadedConfigPath = [];
+  /** @type {AppConfig} */
+  let merged = {};
+
+  for (const filePath of paths) {
+    const config = await loadConfigFile(path.resolve(filePath));
+    if (Object.keys(config).length) {
+      loadedConfigPath.push(filePath);
+    }
+    merged = {
+      model: config.model || merged.model,
+      models: [...(config.models ?? []), ...(merged.models ?? [])],
+      platforms: [...(config.platforms ?? []), ...(merged.platforms ?? [])],
+      autoApproval: {
+        defaultAction:
+          config.autoApproval?.defaultAction ??
+          merged.autoApproval?.defaultAction,
+        patterns: [
+          ...(config.autoApproval?.patterns ?? []),
+          ...(merged.autoApproval?.patterns ?? []),
+        ],
+        maxApprovals:
+          config.autoApproval?.maxApprovals ??
+          merged.autoApproval?.maxApprovals,
+      },
+      sandbox: config.sandbox ?? merged.sandbox,
+      tools: {
+        tavily: {
+          ...(merged.tools?.tavily ?? {}),
+          ...(config.tools?.tavily ?? {}),
+        },
+        askGoogle: {
+          ...(merged.tools?.askGoogle ?? {}),
+          ...(config.tools?.askGoogle ?? {}),
+        },
+      },
+      mcpServers: {
+        ...(merged.mcpServers ?? {}),
+        ...(config.mcpServers ?? {}),
+      },
+      notifyCmd: config.notifyCmd || merged.notifyCmd,
+      claudeCodePlugins: [
+        ...(merged.claudeCodePlugins ?? []),
+        ...(config.claudeCodePlugins ?? []),
+      ],
+    };
+  }
+
+  return { appConfig: merged, loadedConfigPath };
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<AppConfig>}
+ */
+export async function loadConfigFile(filePath) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+
+  const hash = crypto.createHash("sha256").update(content).digest("hex");
+  const isTrusted = await isConfigHashTrusted(hash);
+
+  if (!isTrusted) {
+    if (!process.stdout.isTTY) {
+      console.warn(
+        styleText(
+          "yellow",
+          `WARNING: Config file found at '${filePath}' but cannot ask for approval without a TTY. Skipping.`,
+        ),
+      );
+      return {};
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const answer = await new Promise((resolve) => {
+      console.log(styleText("blue", `\nFound a config file at ${filePath}`));
+      rl.question(
+        styleText("yellow", "Do you want to load this file? (y/N) "),
+        (ans) => {
+          rl.close();
+          resolve(ans);
+        },
+      );
+    });
+
+    if (answer.toLowerCase() !== "y") {
+      console.log(styleText("yellow", "Skipping local config file."));
+      return {};
+    }
+
+    await trustConfigHash(hash);
+  }
+
+  try {
+    const commentRemovedContent = content.replace(/^ *\/\/.+$/gm, "");
+    const parsed = JSON.parse(commentRemovedContent);
+    return /** @type {AppConfig} */ (evalJSONConfig(parsed));
+  } catch (err) {
+    throw new Error(`Failed to parse JSON config at ${filePath}`, {
+      cause: err,
+    });
+  }
+}
+
+/**
+ * @param {string} hash
+ * @returns {Promise<boolean>}
+ */
+async function isConfigHashTrusted(hash) {
+  try {
+    await fs.access(path.join(TRUSTED_CONFIG_HASHES_DIR, hash));
+    return true;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string} hash
+ */
+async function trustConfigHash(hash) {
+  await fs.mkdir(TRUSTED_CONFIG_HASHES_DIR, { recursive: true });
+  await fs.writeFile(path.join(TRUSTED_CONFIG_HASHES_DIR, hash), "");
+}

package/src/context/consumeInterruptMessage.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import { AGENT_INTERRUPT_MESSAGE_FILE_PATH } from "../env.mjs";
+
+/**
+ * @returns {Promise<string | undefined>}
+ */
+export async function consumeInterruptMessage() {
+  try {
+    const content = await fs.readFile(
+      AGENT_INTERRUPT_MESSAGE_FILE_PATH,
+      "utf8",
+    );
+    await fs.truncate(AGENT_INTERRUPT_MESSAGE_FILE_PATH, 0);
+
+    if (content.trim() === "") {
+      return undefined;
+    }
+    return content;
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      "code" in err &&
+      typeof err.code === "string" &&
+      err.code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    throw err;
+  }
+}

package/src/context/loadAgentRoles.mjs

@@ -0,0 +1,272 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import {
+  AGENT_CACHE_DIR,
+  AGENT_PROJECT_METADATA_DIR,
+  AGENT_ROOT,
+  AGENT_USER_CONFIG_DIR,
+  CLAUDE_CODE_PLUGIN_DIR,
+} from "../env.mjs";
+
+/**
+ * @typedef {Object} AgentRole
+ * @property {string} id
+ * @property {string} description
+ * @property {string} content
+ * @property {string} filePath
+ * @property {string} [import]
+ */
+
+/**
+ * Load all agent roles from the predefined directories.
+ * @param {Array<{name: string, path: string}>} [claudeCodePlugins]
+ * @returns {Promise<Map<string, AgentRole>>}
+ */
+export async function loadAgentRoles(claudeCodePlugins) {
+  const agentDirs = [
+    {
+      dir: path.resolve(AGENT_ROOT, ".config", "agents.predefined"),
+      idPrefix: "",
+    },
+    { dir: path.resolve(AGENT_USER_CONFIG_DIR, "agents"), idPrefix: "" },
+    { dir: path.resolve(AGENT_PROJECT_METADATA_DIR, "agents"), idPrefix: "" },
+    {
+      dir: path.resolve(process.cwd(), ".claude", "agents"),
+      idPrefix: "claude:",
+    },
+  ];
+
+  // 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"),
+        idPrefix: `claude/${plugin.name}:`,
+      });
+    }
+  }
+
+  /** @type {Map<string, AgentRole>} */
+  const roles = new Map();
+
+  for (const { dir, idPrefix } of agentDirs) {
+    const files = await getMarkdownFiles(dir).catch((err) => {
+      if (err.code !== "ENOENT") {
+        console.warn(`Failed to list agent roles in ${dir}:`, err);
+      }
+      return [];
+    });
+
+    for (const file of files) {
+      const fullPath = path.join(dir, file);
+      const content = await fs.readFile(fullPath, "utf-8").catch((err) => {
+        console.warn(`Failed to read agent role file ${fullPath}:`, err);
+        return null;
+      });
+
+      if (content === null) continue;
+
+      let role = parseAgentRole(file, content, fullPath, idPrefix);
+      if (role.import) {
+        role = await mergeRemoteRole(role, file, fullPath);
+      }
+
+      roles.set(role.id, role);
+    }
+  }
+
+  return roles;
+}
+
+/**
+ * Merges a remote role into a local role.
+ * @param {AgentRole} localRole
+ * @param {string} relativePath
+ * @param {string} fullPath
+ * @returns {Promise<AgentRole>}
+ */
+async function mergeRemoteRole(localRole, relativePath, fullPath) {
+  const importUrl = localRole.import;
+  if (!importUrl) {
+    return localRole;
+  }
+
+  const fetchedContent = await fetchAndCacheRole(importUrl).catch((err) => {
+    console.warn(`Failed to fetch agent role from ${importUrl}:`, err);
+    return null;
+  });
+
+  if (!fetchedContent) {
+    return localRole;
+  }
+
+  const remoteRole = parseAgentRole(relativePath, fetchedContent, fullPath);
+
+  return {
+    ...remoteRole,
+    ...localRole, // Local overrides
+    content: `${remoteRole.content}\n\n---\n\n${localRole.content}`.trim(),
+    description: localRole.description || remoteRole.description || "",
+  };
+}
+
+/**
+ * Fetch an agent role from a URL and cache it.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchAndCacheRole(url) {
+  const hash = crypto.createHash("sha256").update(url).digest("hex");
+  const cacheDir = path.join(AGENT_CACHE_DIR, "agents");
+  const cachePath = path.join(cacheDir, hash);
+
+  const cachedContent = await fs.readFile(cachePath, "utf-8").catch(() => null);
+  if (cachedContent !== null) {
+    return cachedContent;
+  }
+
+  const fetchedContent = await fetchContent(url);
+
+  // Attempt to cache, but don't block or fail on errors
+  fs.mkdir(cacheDir, { recursive: true })
+    .then(() => fs.writeFile(cachePath, fetchedContent, "utf-8"))
+    .catch((err) => {
+      console.warn(`Failed to write cache for ${url}:`, err);
+    });
+
+  return fetchedContent;
+}
+
+/**
+ * Fetch content from a URL.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchContent(url) {
+  const githubMatch = url.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/,
+  );
+
+  if (githubMatch) {
+    const [, owner, repo, ref, path] = githubMatch;
+    const apiUrl = `repos/${owner}/${repo}/contents/${path}?ref=${ref}`;
+    try {
+      const { execFileSync } = await import("node:child_process");
+      return execFileSync(
+        "gh",
+        ["api", "-H", "Accept: application/vnd.github.v3.raw", apiUrl],
+        { encoding: "utf-8" },
+      );
+    } catch (err) {
+      throw new Error(`Failed to fetch from GitHub via gh CLI: ${err}`);
+    }
+  }
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch agent role from ${url}: ${response.status} ${response.statusText}`,
+    );
+  }
+  return response.text();
+}
+
+/**
+ * Recursively get all markdown files in a directory.
+ * @param {string} dir
+ * @param {string} [baseDir]
+ * @returns {Promise<string[]>}
+ */
+async function getMarkdownFiles(dir, baseDir = dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    let isDirectory = entry.isDirectory();
+    let isFile = entry.isFile();
+
+    if (entry.isSymbolicLink()) {
+      const stat = await fs.stat(fullPath).catch(() => null);
+      if (!stat) continue;
+      isDirectory = stat.isDirectory();
+      isFile = stat.isFile();
+    }
+
+    if (isDirectory) {
+      files.push(...(await getMarkdownFiles(fullPath, baseDir)));
+    } else if (isFile && entry.name.endsWith(".md")) {
+      files.push(path.relative(baseDir, fullPath));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Parse an agent role file content.
+ * @param {string} relativePath
+ * @param {string} fileContent
+ * @param {string} fullPath
+ * @param {string} [idPrefix=""]
+ * @returns {AgentRole}
+ */
+function parseAgentRole(relativePath, fileContent, fullPath, idPrefix = "") {
+  const rawId = relativePath.replace(/\.md$/, "");
+  const id = idPrefix + rawId;
+
+  // Match YAML frontmatter
+  const match = fileContent.match(
+    /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/,
+  );
+
+  if (!match) {
+    return {
+      id,
+      description: "",
+      content: fileContent.trim(),
+      filePath: fullPath,
+    };
+  }
+
+  /** @type {{description?:string; import?:string}} */
+  let frontmatter;
+  try {
+    frontmatter = /** @type {{description?:string; import?:string}} */ (
+      yaml.load(match[1])
+    );
+  } catch (_err) {
+    return {
+      id,
+      description: parseFrontmatterField(match[1], "description") ?? "",
+      content: fileContent.trim(),
+      filePath: fullPath,
+    };
+  }
+  const content = match[2].trim();
+
+  return {
+    id,
+    description: frontmatter.description ?? "",
+    content,
+    filePath: fullPath,
+    import: frontmatter.import,
+  };
+}
+
+/**
+ * Parse a field from YAML frontmatter.
+ * @param {string} frontmatter
+ * @param {string} field
+ * @returns {string | undefined}
+ */
+
+function parseFrontmatterField(frontmatter, field) {
+  const regex = new RegExp(`^${field}:\\s*(.*)$`, "m");
+  const match = frontmatter.match(regex);
+  return match ? match[1].trim() : undefined;
+}