@iinm/plain-agent 1.0.0

package/src/context/loadPrompts.mjs

@@ -0,0 +1,312 @@
+import { execFileSync } from "node:child_process";
+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} Prompt
+ * @property {string} id
+ * @property {string} description
+ * @property {string} content
+ * @property {string} filePath
+ * @property {string} [import]
+ * @property {boolean} [userInvocable]
+ * @property {boolean} [isShortcut]
+ * @property {boolean} [isSkill]
+ */
+
+/**
+ * Load all prompts from the predefined directories.
+ * @param {Array<{name: string, path: string}>} [claudeCodePlugins]
+ * @returns {Promise<Map<string, Prompt>>}
+ */
+export async function loadPrompts(claudeCodePlugins) {
+  const promptDirs = [
+    {
+      dir: path.resolve(AGENT_ROOT, ".config", "prompts.predefined"),
+      idPrefix: "",
+    },
+    { dir: path.resolve(AGENT_USER_CONFIG_DIR, "prompts"), idPrefix: "" },
+    { dir: path.resolve(AGENT_PROJECT_METADATA_DIR, "prompts"), idPrefix: "" },
+    {
+      dir: path.resolve(process.cwd(), ".claude", "commands"),
+      idPrefix: "claude/commands:",
+    },
+    {
+      dir: path.resolve(process.cwd(), ".claude", "skills"),
+      idPrefix: "claude/skills:",
+    },
+  ];
+
+  // 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"),
+        idPrefix: `claude/${plugin.name}/commands:`,
+      });
+
+      // Skills
+      promptDirs.push({
+        dir: path.join(pluginBase, "skills"),
+        idPrefix: `claude/${plugin.name}/skills:`,
+      });
+    }
+  }
+
+  /** @type {Map<string, Prompt>} */
+  const prompts = new Map();
+
+  for (const { dir, idPrefix } of promptDirs) {
+    const files = await getMarkdownFiles(dir).catch((err) => {
+      if (err.code !== "ENOENT") {
+        console.warn(`Failed to list prompts 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 prompt file ${fullPath}:`, err);
+        return null;
+      });
+
+      if (content === null) continue;
+
+      //  Ignore all files in the skills/ directory except for SKILL.md.
+      if (fullPath.match(/\/skills\//) && !file.endsWith("/SKILL.md")) {
+        continue;
+      }
+
+      let prompt = parsePrompt(file, content, fullPath, idPrefix);
+      if (prompt.import) {
+        prompt = await mergeRemotePrompt(prompt, file, fullPath);
+      }
+
+      if (prompt.userInvocable === false) {
+        continue;
+      }
+
+      prompts.set(prompt.id, prompt);
+    }
+  }
+
+  return prompts;
+}
+
+/**
+ * Merges a remote prompt into a local prompt if an import URL is provided.
+ * @param {Prompt} localPrompt
+ * @param {string} relativePath
+ * @param {string} fullPath
+ * @returns {Promise<Prompt>}
+ */
+async function mergeRemotePrompt(localPrompt, relativePath, fullPath) {
+  const importUrl = localPrompt.import;
+  if (!importUrl) {
+    return localPrompt;
+  }
+
+  const fetchedContent = await fetchAndCachePrompt(importUrl).catch((err) => {
+    console.warn(`Failed to fetch prompt from ${importUrl}:`, err);
+    return null;
+  });
+
+  if (!fetchedContent) {
+    return localPrompt;
+  }
+
+  const remotePrompt = parsePrompt(relativePath, fetchedContent, fullPath);
+
+  return {
+    ...remotePrompt,
+    ...localPrompt, // Local overrides
+    content: `${remotePrompt.content}\n\n---\n\n${localPrompt.content}`.trim(),
+    description: localPrompt.description || remotePrompt.description || "",
+  };
+}
+
+/**
+ * Fetch a prompt from a URL and cache it.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+async function fetchAndCachePrompt(url) {
+  const hash = crypto.createHash("sha256").update(url).digest("hex");
+  const cacheDir = path.join(AGENT_CACHE_DIR, "prompts");
+  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 {
+      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 prompt 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 a prompt file content.
+ * @param {string} relativePath
+ * @param {string} fileContent
+ * @param {string} fullPath
+ * @param {string} [idPrefix=""]
+ * @returns {Prompt}
+ */
+function parsePrompt(relativePath, fileContent, fullPath, idPrefix = "") {
+  const rawId = relativePath.replace(/\/SKILL\.md$/, "").replace(/\.md$/, "");
+  const isShortcut = rawId.startsWith("shortcuts/");
+  const id = isShortcut
+    ? idPrefix + rawId.replace(/^shortcuts\//, "")
+    : 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,
+      isShortcut,
+      isSkill: relativePath.endsWith("SKILL.md"),
+    };
+  }
+
+  const content = match[2].trim();
+
+  /** @type {{description?:string; import?:string; "user-invocable"?:boolean}} */
+  let frontmatter;
+  try {
+    frontmatter =
+      /** @type {{description?:string; import?:string; "user-invocable"?:boolean}} */ (
+        yaml.load(match[1])
+      );
+  } catch (_err) {
+    return {
+      id,
+      description: parseFrontmatterField(match[1], "description") ?? "",
+      content,
+      filePath: fullPath,
+      import: parseFrontmatterField(match[1], "import"),
+      userInvocable:
+        parseFrontmatterField(match[1], "user-invocable") === "true" ||
+        undefined,
+      isShortcut,
+      isSkill: relativePath.endsWith("SKILL.md"),
+    };
+  }
+  const userInvocable = frontmatter["user-invocable"];
+
+  return {
+    id,
+    description: frontmatter.description ?? "",
+    content,
+    filePath: fullPath,
+    import: frontmatter.import,
+    userInvocable: userInvocable ?? undefined,
+    isShortcut,
+    isSkill: relativePath.endsWith("SKILL.md"),
+  };
+}
+
+/**
+ * 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;
+}

package/src/context/loadUserMessageContext.mjs

@@ -0,0 +1,147 @@
+/**
+ * @import { MessageContentText, MessageContentImage } from "../model";
+ */
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { styleText } from "node:util";
+import { noThrow } from "../utils/noThrow.mjs";
+import { parseFileRange } from "../utils/parseFileRange.mjs";
+import { readFileRange } from "../utils/readFileRange.mjs";
+
+/** @type {ReadonlyMap<string, string>} */
+const IMAGE_MIME_TYPES = new Map([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"],
+]);
+
+/**
+ * @param {string} message
+ * @returns {Promise<(MessageContentText | MessageContentImage)[]>}
+ */
+export async function loadUserMessageContext(message) {
+  const workingDir = process.cwd();
+
+  /** @type {string[]} */
+  const text = [];
+  /** @type {string[]} */
+  const contexts = [];
+  /** @type {MessageContentImage[]} */
+  const images = [];
+
+  let cursor = 0;
+  for (const match of message.matchAll(
+    /(^|\s)@(?:'([^']+)'|((?:\\ |[^\s])+))/g,
+  )) {
+    if (cursor < match.index) {
+      text.push(message.slice(cursor, match.index));
+    }
+    cursor = match.index + match[0].length;
+    const [entireMatch, leading, quoted, escaped] = match;
+    const reference = quoted ?? escaped.replace(/\\ /g, " ");
+
+    const ext = path.extname(reference).toLowerCase();
+    if (IMAGE_MIME_TYPES.has(ext)) {
+      const imageContent = await loadImageContent(reference);
+      if (imageContent instanceof Error) {
+        warn(`Failed to load image from ${reference}: ${imageContent.message}`);
+        text.push(entireMatch);
+        continue;
+      }
+      images.push(imageContent);
+      text.push(`${leading}[Image #${images.length}:${reference}]`);
+      continue;
+    }
+
+    const contextSnippet = await loadContextSnippet(reference, workingDir);
+    if (contextSnippet) {
+      contexts.push(contextSnippet);
+    }
+    text.push(entireMatch);
+  }
+
+  if (cursor < message.length) {
+    text.push(message.slice(cursor));
+  }
+
+  return [
+    { type: "text", text: [text.join(""), ...contexts].join("\n\n") },
+    ...images,
+  ];
+}
+
+/**
+ * @param {string} reference
+ * @param {string} workingDir
+ * @returns {Promise<string | null>}
+ */
+async function loadContextSnippet(reference, workingDir) {
+  const fileRange = parseFileRange(reference);
+  if (fileRange instanceof Error) {
+    warn(`Failed to parse context reference ${reference}: ${fileRange}`);
+    return null;
+  }
+
+  const absolutePath = path.resolve(fileRange.filePath);
+  const relativePath = path.relative(workingDir, absolutePath);
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    warn(
+      `Refusing to load context from outside working directory: ${absolutePath}`,
+    );
+    return null;
+  }
+
+  const fileContent = await readFileRange(fileRange);
+  if (fileContent instanceof Error) {
+    warn(`Failed to load context from ${reference}: ${fileContent}`);
+    return null;
+  }
+
+  return [`<context location="${reference}">`, fileContent, "</context>"].join(
+    "\n",
+  );
+}
+
+/**
+ * @param {string} imagePath
+ * @returns {Promise<MessageContentImage | Error>}
+ */
+async function loadImageContent(imagePath) {
+  const absolutePath = path.resolve(imagePath);
+
+  return await noThrow(async () => {
+    const data = await readFile(absolutePath);
+    return {
+      type: "image",
+      data: data.toString("base64"),
+      mimeType: inferMimeType(absolutePath),
+    };
+  });
+}
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+function inferMimeType(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  const mimeType = IMAGE_MIME_TYPES.get(extension);
+  if (!mimeType) {
+    throw new Error(
+      `Unsupported image extension: ${extension} (file: ${filePath})`,
+    );
+  }
+
+  return mimeType;
+}
+
+/**
+ * @param {string} message
+ * @returns {void}
+ */
+function warn(message) {
+  console.warn(styleText("yellow", message));
+}

package/src/env.mjs

@@ -0,0 +1,46 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const filename = fileURLToPath(import.meta.url);
+export const AGENT_ROOT = path.dirname(path.dirname(filename));
+
+export const AGENT_USER_CONFIG_DIR = path.join(
+  os.homedir(),
+  ".config",
+  "plain-agent",
+);
+export const AGENT_CACHE_DIR = path.join(os.homedir(), ".cache", "plain-agent");
+
+export const TRUSTED_CONFIG_HASHES_DIR = path.join(
+  AGENT_CACHE_DIR,
+  "trusted-config-hashes",
+);
+
+export const AGENT_PROJECT_METADATA_DIR = ".plain-agent";
+
+export const AGENT_MEMORY_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "memory");
+export const AGENT_TMP_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "tmp");
+
+export const CLAUDE_CODE_PLUGIN_DIR = path.join(
+  AGENT_PROJECT_METADATA_DIR,
+  "claude-code-plugins",
+);
+
+export const MESSAGES_DUMP_FILE_PATH = path.join(
+  AGENT_PROJECT_METADATA_DIR,
+  "messages.json",
+);
+
+export const AGENT_NOTIFY_CMD_DEFAULT = path.join(
+  AGENT_ROOT,
+  "bin",
+  "plain-notify-terminal-bell",
+);
+
+export const AGENT_INTERRUPT_MESSAGE_FILE_PATH = path.join(
+  AGENT_PROJECT_METADATA_DIR,
+  "interrupt-message.txt",
+);
+
+export const USER_NAME = process.env.USER || "unknown";

package/src/main.mjs

@@ -0,0 +1,202 @@
+/**
+ * @import { Tool } from "./tool";
+ */
+
+import { styleText } from "node:util";
+import { createAgent } from "./agent.mjs";
+import { parseCliArgs, printHelp } from "./cliArgs.mjs";
+import { startInteractiveSession } from "./cliInteractive.mjs";
+import { loadAppConfig } from "./config.mjs";
+import { loadAgentRoles } from "./context/loadAgentRoles.mjs";
+import { loadPrompts } from "./context/loadPrompts.mjs";
+import {
+  AGENT_NOTIFY_CMD_DEFAULT,
+  AGENT_PROJECT_METADATA_DIR,
+  USER_NAME,
+} from "./env.mjs";
+import { setupMCPServer } from "./mcp.mjs";
+import { createModelCaller } from "./modelCaller.mjs";
+import { createPrompt } from "./prompt.mjs";
+import { createAskGoogleTool } from "./tools/askGoogle.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) {
+  printHelp();
+}
+
+(async () => {
+  const startTime = new Date();
+  const sessionId = [
+    startTime.toISOString().slice(0, 10),
+    `0${startTime.getHours()}`.slice(-2) +
+      `0${startTime.getMinutes()}`.slice(-2),
+  ].join("-");
+  const tmuxSessionId = `agent-${sessionId}`;
+  const { appConfig, loadedConfigPath } = await loadAppConfig();
+
+  if (loadedConfigPath.length > 0) {
+    console.log(styleText("green", "\n⚡ Loaded configuration files"));
+    console.log(loadedConfigPath.map((p) => `  ⤷ ${p}`).join("\n"));
+  }
+
+  if (appConfig.sandbox) {
+    const sandboxStr = [
+      appConfig.sandbox.command,
+      ...(appConfig.sandbox.args || []),
+    ].join(" ");
+    console.log(styleText("green", "\n📦 Sandbox: on"));
+    console.log(`  ⤷ ${sandboxStr}`);
+  } else {
+    console.log(styleText("yellow", "\n📦 Sandbox: off"));
+  }
+
+  /** @type {(() => Promise<void>)[]} */
+  const mcpCleanups = [];
+
+  /** @type {Tool[]} */
+  const mcpTools = [];
+  if (appConfig.mcpServers) {
+    const mcpServerEntries = Object.entries(appConfig.mcpServers);
+
+    console.log();
+    for (const [serverName] of mcpServerEntries) {
+      console.log(
+        styleText("blue", `🔌 Connecting to MCP server: ${serverName}...`),
+      );
+    }
+
+    const mcpResults = await Promise.all(
+      mcpServerEntries.map(async ([serverName, serverConfig]) => {
+        const result = await setupMCPServer(serverName, serverConfig);
+        return { serverName, ...result };
+      }),
+    );
+
+    for (const { serverName, tools, cleanup } of mcpResults) {
+      mcpTools.push(...tools);
+      mcpCleanups.push(cleanup);
+      console.log(
+        styleText(
+          "green",
+          `✅ Successfully connected to MCP server: ${serverName}`,
+        ),
+      );
+    }
+  }
+
+  const modelNameWithVariant = cliArgs.model || appConfig.model || "";
+  const agentRoles = await loadAgentRoles(appConfig.claudeCodePlugins);
+  const prompts = await loadPrompts(appConfig.claudeCodePlugins);
+
+  const prompt = createPrompt({
+    username: USER_NAME,
+    modelName: modelNameWithVariant,
+    sessionId,
+    tmuxSessionId,
+    workingDir: process.cwd(),
+    projectMetadataDir: AGENT_PROJECT_METADATA_DIR,
+    agentRoles,
+    skills: Array.from(prompts.values()).filter((p) => p.isSkill),
+  });
+
+  const builtinTools = [
+    createExecCommandTool({ sandbox: appConfig.sandbox }),
+    writeFileTool,
+    patchFileTool,
+    createTmuxCommandTool({ sandbox: appConfig.sandbox }),
+    fetchWebPageTool,
+    createDelegateToSubagentTool(),
+    createReportAsSubagentTool(),
+  ];
+
+  if (appConfig.tools?.tavily?.apiKey) {
+    builtinTools.push(createTavilySearchTool(appConfig.tools.tavily));
+  }
+
+  if (appConfig.tools?.askGoogle) {
+    builtinTools.push(
+      createAskGoogleTool({
+        platform: appConfig.tools.askGoogle.platform,
+        baseURL: appConfig.tools.askGoogle.baseURL,
+        apiKey: appConfig.tools.askGoogle.apiKey,
+      }),
+    );
+  }
+
+  const toolUseApprover = createToolUseApprover({
+    maxApprovals: appConfig.autoApproval?.maxApprovals || 50,
+    defaultAction: appConfig.autoApproval?.defaultAction || "ask",
+    patterns: appConfig.autoApproval?.patterns || [],
+    maskApprovalInput: (toolName, input) => {
+      for (const tool of builtinTools) {
+        if (tool.def.name === toolName && tool.maskApprovalInput) {
+          return tool.maskApprovalInput(input);
+        }
+      }
+      return input;
+    },
+  });
+
+  const [modelName, modelVariant] = modelNameWithVariant.split("+");
+  const modelDef = (appConfig.models ?? []).find(
+    (entry) => entry.name === modelName && entry.variant === modelVariant,
+  );
+  if (!modelDef) {
+    throw new Error(
+      `Model "${modelNameWithVariant}" not found in configuration.`,
+    );
+  }
+
+  const platform = (appConfig.platforms ?? []).find(
+    (entry) =>
+      entry.name === modelDef.platform.name &&
+      entry.variant === modelDef.platform.variant,
+  );
+  if (!platform) {
+    throw new Error(
+      `Platform ${modelDef.platform.name} variant=${modelDef.platform.variant} not found in configuration.`,
+    );
+  }
+
+  const { userEventEmitter, agentEventEmitter, agentCommands } = createAgent({
+    callModel: createModelCaller({
+      ...modelDef,
+      platform: {
+        ...modelDef.platform,
+        ...platform,
+      },
+    }),
+    prompt,
+    tools: [...builtinTools, ...mcpTools],
+    toolUseApprover,
+    agentRoles,
+  });
+
+  startInteractiveSession({
+    userEventEmitter,
+    agentEventEmitter,
+    agentCommands,
+    sessionId,
+    modelName: modelNameWithVariant,
+    notifyCmd: appConfig.notifyCmd || AGENT_NOTIFY_CMD_DEFAULT,
+    sandbox: Boolean(appConfig.sandbox),
+    onStop: async () => {
+      for (const cleanup of mcpCleanups) {
+        await cleanup();
+      }
+    },
+    claudeCodePlugins: appConfig.claudeCodePlugins,
+  });
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});