@iinm/plain-agent 1.8.4 → 1.8.5

package/src/cliPasteTransform.mjs

@@ -0,0 +1,183 @@
+import { Transform } from "node:stream";
+
+// Bracketed paste mode sequences
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+
+// Time to wait for a continuation paste chunk before flushing the paste buffer.
+// Some terminals split large pastes into multiple bracketed paste sequences
+// (e.g. `\x1b[200~...\x1b[201~\x1b[200~...\x1b[201~`) that arrive back-to-back.
+// Holding the paste briefly lets us merge them into a single placeholder.
+const PASTE_MERGE_WINDOW_MS = 20;
+
+// Paste state machine:
+//   IDLE    - normal passthrough
+//   PASTE   - inside a BRACKETED_PASTE_START ... BRACKETED_PASTE_END sequence
+//   PENDING - just saw an END; waiting to see if the next data continues the
+//             paste (another START immediately follows) or not.
+/** @typedef {"IDLE" | "PASTE" | "PENDING"} PasteState */
+
+/**
+ * Generate a short hash for paste reference.
+ * @param {string} content
+ * @returns {string}
+ */
+function generatePasteHash(content) {
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash).toString(16).padStart(6, "0").slice(0, 6);
+}
+
+/**
+ * @typedef {object} PasteHandler
+ * @property {Transform} transform
+ *   Transform stream to pipe stdin through. Emits placeholders for multi-line
+ *   pastes and raw text for single-line pastes / typed input.
+ * @property {(input: string) => string} resolvePlaceholders
+ *   Given a string containing placeholders produced by `transform`, append a
+ *   `<context id="pasted#HASH">...</context>` block for each referenced paste
+ *   and consume the stored content. Unknown placeholders are left untouched.
+ */
+
+/**
+ * Create a bracketed-paste handler. The handler owns its own content store so
+ * pastes from one handler instance cannot interfere with another (and state
+ * does not leak across tests).
+ *
+ * @returns {PasteHandler}
+ */
+export function createPasteHandler() {
+  /** @type {Map<string, string>} */
+  const pastedContentStore = new Map();
+
+  /** @type {PasteState} */
+  let state = "IDLE";
+  let pasteBuffer = "";
+  /** @type {NodeJS.Timeout | null} */
+  let mergeTimer = null;
+  /** @type {Transform} */
+  let transform;
+
+  const clearMergeTimer = () => {
+    if (mergeTimer) {
+      clearTimeout(mergeTimer);
+      mergeTimer = null;
+    }
+  };
+
+  const flushPasteBuffer = () => {
+    clearMergeTimer();
+    if (pasteBuffer) {
+      // Strip a trailing newline so a paste like "foo\n" is treated as single-line.
+      const trimmed = pasteBuffer.replace(/\n$/, "");
+      if (trimmed.includes("\n")) {
+        // Multi-line: emit a placeholder and stash the content for later.
+        const hash = generatePasteHash(pasteBuffer);
+        pastedContentStore.set(hash, pasteBuffer);
+        const lineCount = pasteBuffer.split("\n").length;
+        transform.push(`[Pasted text #${hash}, ${lineCount} lines]`);
+      } else {
+        transform.push(trimmed);
+      }
+    }
+    pasteBuffer = "";
+    state = "IDLE";
+  };
+
+  transform = new Transform({
+    transform(chunk, _encoding, callback) {
+      /** @type {string} */
+      let data = chunk.toString("utf8");
+
+      while (data.length > 0) {
+        if (state === "PASTE") {
+          const endIdx = data.indexOf(BRACKETED_PASTE_END);
+          if (endIdx === -1) {
+            pasteBuffer += data;
+            data = "";
+          } else {
+            // End of (this chunk of) paste. Hold briefly in case another paste
+            // chunk follows immediately and should be merged.
+            pasteBuffer += data.slice(0, endIdx);
+            data = data.slice(endIdx + BRACKETED_PASTE_END.length);
+            state = "PENDING";
+          }
+        } else if (state === "PENDING") {
+          if (data.startsWith(BRACKETED_PASTE_START)) {
+            // Continuation of the previous paste; keep appending to pasteBuffer.
+            data = data.slice(BRACKETED_PASTE_START.length);
+            clearMergeTimer();
+            state = "PASTE";
+          } else {
+            // Not a continuation; flush, then re-process this data as IDLE.
+            flushPasteBuffer();
+          }
+        } else {
+          // IDLE
+          const startIdx = data.indexOf(BRACKETED_PASTE_START);
+          if (startIdx === -1) {
+            this.push(data);
+            data = "";
+          } else {
+            this.push(data.slice(0, startIdx));
+            data = data.slice(startIdx + BRACKETED_PASTE_START.length);
+            state = "PASTE";
+          }
+        }
+      }
+
+      // If the chunk ended while still waiting for a possible continuation,
+      // schedule a short timer to flush the pending paste if nothing arrives.
+      if (state === "PENDING" && !mergeTimer) {
+        mergeTimer = setTimeout(() => {
+          mergeTimer = null;
+          flushPasteBuffer();
+        }, PASTE_MERGE_WINDOW_MS);
+      }
+
+      callback();
+    },
+
+    flush(callback) {
+      if (state === "PENDING") {
+        flushPasteBuffer();
+      }
+      callback();
+    },
+  });
+
+  /**
+   * @param {string} input
+   * @returns {string}
+   */
+  const resolvePlaceholders = (input) => {
+    /** @type {string[]} */
+    const contexts = [];
+
+    // Collect paste content for context tags while keeping placeholders.
+    const text = input.replace(
+      /\[Pasted text #([a-f0-9]{6}),/g,
+      (match, hash) => {
+        const content = pastedContentStore.get(hash);
+        if (content !== undefined) {
+          pastedContentStore.delete(hash); // Clean up after use
+          contexts.push(
+            `<context id="pasted#${hash}">\n${content}\n</context>`,
+          );
+        }
+        return match; // Keep placeholder in text
+      },
+    );
+
+    if (contexts.length > 0) {
+      return [text, ...contexts].join("\n\n");
+    }
+    return text;
+  };
+
+  return { transform, resolvePlaceholders };
+}

package/src/config.d.ts

@@ -0,0 +1,36 @@
+import { ClaudeCodePluginRepo } from "./claudeCodePlugin.mjs";
+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";
+import { VoiceInputConfig } from "./voiceInput.mjs";
+
+export type AppConfig = {
+  model?: string;
+  models?: ModelDefinition[];
+  platforms?: PlatformConfig[];
+  autoApproval?: {
+    patterns?: ToolUsePattern[];
+    maxApprovals?: number;
+    defaultAction?: "deny" | "ask";
+  };
+  sandbox?: ExecCommandSanboxConfig;
+  tools?: {
+    askWeb?: AskWebToolOptions;
+    askURL?: AskURLToolOptions;
+  };
+  mcpServers?: Record<string, MCPServerConfig>;
+  notifyCmd?: { command: string; args?: string[] };
+  voiceInput?: VoiceInputConfig;
+  claudeCodePlugins?: ClaudeCodePluginRepo[];
+};
+
+export type MCPServerConfig = {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  options?: {
+    enabledTools?: string[];
+  };
+};

package/src/config.mjs

@@ -0,0 +1,197 @@
+/**
+ * @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";
+
+/**
+ * @typedef {Object} LoadAppConfigOptions
+ * @property {boolean} [skipTrustCheck] - Skip trust check for config files
+ * @property {string[]} [configFiles] - Additional config files to load (for batch mode)
+ * @property {boolean} [skipUserConfig] - Skip default user config files (for batch mode)
+ */
+
+/**
+ * @param {LoadAppConfigOptions} [options]
+ * @returns {Promise<{appConfig: AppConfig, loadedConfigPath: string[]}>}
+ */
+export async function loadAppConfig(options = {}) {
+  const {
+    skipTrustCheck = false,
+    configFiles = [],
+    skipUserConfig = false,
+  } = options;
+
+  // Always load predefined config
+  const paths = [`${AGENT_ROOT}/config/config.predefined.json`];
+
+  if (!skipUserConfig) {
+    paths.push(
+      `${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`,
+    );
+  }
+
+  // Add explicitly specified config files
+  paths.push(...configFiles);
+
+  /** @type {string[]} */
+  const loadedConfigPath = [];
+  /** @type {AppConfig} */
+  let merged = {};
+
+  for (const filePath of paths) {
+    const config = await loadConfigFile(path.resolve(filePath), skipTrustCheck);
+    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: {
+        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 ?? {}),
+        ...(config.mcpServers ?? {}),
+      },
+      notifyCmd: config.notifyCmd ?? merged.notifyCmd,
+      claudeCodePlugins: [
+        ...(merged.claudeCodePlugins ?? []),
+        ...(config.claudeCodePlugins ?? []),
+      ],
+      voiceInput: config.voiceInput
+        ? { ...(merged.voiceInput ?? {}), ...config.voiceInput }
+        : merged.voiceInput,
+    };
+  }
+
+  return { appConfig: merged, loadedConfigPath };
+}
+
+/**
+ * @param {string} filePath
+ * @param {boolean} [skipTrustCheck=false]
+ * @returns {Promise<AppConfig>}
+ */
+export async function loadConfigFile(filePath, skipTrustCheck = false) {
+  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 = skipTrustCheck || (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/loadAgentRoles.mjs

@@ -0,0 +1,294 @@
+/** @import { ClaudeCodePlugin } from "../claudeCodePlugin.mjs" */
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import {
+  AGENT_CACHE_DIR,
+  AGENT_PROJECT_METADATA_DIR,
+  AGENT_ROOT,
+  AGENT_USER_CONFIG_DIR,
+} from "../env.mjs";
+
+/**
+ * @typedef {Object} AgentRole
+ * @property {string} id
+ * @property {string} description
+ * @property {string} content
+ * @property {string} filePath
+ * @property {boolean} claudeOriginated
+ * @property {string} [import]
+ */
+
+/**
+ * Load all agent roles from the predefined directories.
+ * @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"),
+      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) {
+      agentDirs.push({
+        dir: path.join(plugin.path, "agents"),
+        idPrefix: `claude/${plugin.name}:`,
+        only: plugin.only,
+      });
+    }
+  }
+
+  const files = (
+    await Promise.all(
+      agentDirs.map(async ({ dir, idPrefix, only }) => {
+        const files = await getMarkdownFiles(dir).catch((err) => {
+          if (err.code !== "ENOENT") {
+            console.warn(`Failed to list agent roles in ${dir}:`, err);
+          }
+          return /** @type {string[]} */ ([]);
+        });
+        return files.map((file) => ({ dir, file, idPrefix, only }));
+      }),
+    )
+  )
+    .flat()
+    // Filter by only pattern if specified
+    .filter(({ file, only }) => !(only && !only.test(file)));
+
+  const roles = /** @type {AgentRole[]} */ (
+    (
+      await Promise.all(
+        files.map(async ({ dir, file, idPrefix }) => {
+          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) return null;
+
+          let role = parseAgentRole(file, content, fullPath, idPrefix);
+          if (role.import) {
+            try {
+              role = await mergeRemoteRole(role, file, fullPath);
+            } catch (err) {
+              console.warn(`Failed to import remote role ${role.id}:`, err);
+              return null;
+            }
+          }
+
+          return role;
+        }),
+      )
+    ).filter((role) => role)
+  );
+
+  return new Map(roles.map((role) => [role.id, role]));
+}
+
+/**
+ * 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;
+  const claudeOriginated = idPrefix.startsWith("claude");
+
+  // 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,
+      claudeOriginated,
+    };
+  }
+
+  /** @type {{description?:string; import?:string}} */
+  let frontmatter;
+  try {
+    frontmatter = /** @type {{description?:string; import?:string}} */ (
+      parseYaml(match[1])
+    );
+  } catch (_err) {
+    return {
+      id,
+      description: parseFrontmatterField(match[1], "description") ?? "",
+      content: fileContent.trim(),
+      filePath: fullPath,
+      claudeOriginated,
+    };
+  }
+  const content = match[2].trim();
+
+  return {
+    id,
+    description: frontmatter.description ?? "",
+    content,
+    filePath: fullPath,
+    claudeOriginated,
+    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;
+}