@iinm/plain-agent 1.0.0

package/src/mcp.mjs

@@ -0,0 +1,202 @@
+/**
+ * @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 { AGENT_PROJECT_METADATA_DIR } from "./env.mjs";
+import { writeTmpFile } from "./tmpfile.mjs";
+import { noThrow } from "./utils/noThrow.mjs";
+
+const OUTPUT_MAX_LENGTH = 1024 * 8;
+
+/**
+ * @typedef {Object} SetupMCPServrResult
+ * @property {Tool[]} tools
+ * @property {() => Promise<void>} cleanup
+ */
+
+/**
+ * @param {string} serverName
+ * @param {MCPServerConfig} serverConfig
+ * @returns {Promise<SetupMCPServrResult>}
+ */
+export async function setupMCPServer(serverName, serverConfig) {
+  const { options, ...params } = serverConfig;
+
+  const { client, cleanup } = await startMCPServer({
+    serverName,
+    params,
+  });
+
+  const tools = (await createMCPTools(serverName, client)).filter(
+    (tool) =>
+      !options?.enabledTools ||
+      options.enabledTools.find((enabledToolName) =>
+        tool.def.name.endsWith(`__${enabledToolName}`),
+      ),
+  );
+
+  return {
+    tools,
+    cleanup: async () => {
+      cleanup();
+      await client.close();
+    },
+  };
+}
+
+/**
+ * @typedef {Object} MCPClientOptions
+ * @property {string} serverName - The name of the MCP server.
+ * @property {StdioServerParameters} params - The transport to use for the client.
+ */
+
+/**
+ * @param {MCPClientOptions} options - The options for the client.
+ * @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 client = new mcpClient.Client({
+    name: "undefined",
+    version: "undefined",
+  });
+
+  const { env, ...restParams } = options.params;
+  const defaultEnv = {
+    PWD: process.env.PWD || "",
+    PATH: process.env.PATH || "",
+    HOME: process.env.HOME || "",
+  };
+
+  // Ensure log directory exists and open stderr log file
+  const logDir = path.join(AGENT_PROJECT_METADATA_DIR, "logs");
+  await mkdir(logDir, { recursive: true });
+  const logPath = path.join(logDir, `mcp--${options.serverName}.stderr`);
+  const stderrLogFile = await open(logPath, "a");
+
+  const transport = new mcpClientStdio.StdioClientTransport({
+    ...restParams,
+    env: env ? { ...defaultEnv, ...env } : undefined,
+    stderr: stderrLogFile.fd,
+  });
+  await client.connect(transport);
+
+  return {
+    client,
+    cleanup: () => {
+      stderrLogFile.close();
+    },
+  };
+}
+
+/**
+ * @param {string} serverName
+ * @param {Client} client - The MCP client.
+ * @returns {Promise<Tool[]>} - The list of tools.
+ */
+async function createMCPTools(serverName, client) {
+  const { tools: mcpTools } = await client.listTools();
+  /** @type {Tool[]} */
+  const tools = mcpTools
+    .filter((tool) => {
+      // Remove unsupported tools
+      return ![""].includes(tool.name);
+    })
+    .map((tool) => {
+      return {
+        def: {
+          name: `mcp__${serverName}__${tool.name}`,
+          description: tool.description || `${tool.name} tool`,
+          inputSchema: tool.inputSchema,
+        },
+
+        /** @type {ToolImplementation} */
+        impl: async (input) =>
+          noThrow(async () => {
+            const result = await client.callTool({
+              name: tool.name,
+              arguments: input,
+            });
+
+            const resultStringRaw = JSON.stringify(result, null, 2);
+
+            /** @type {StructuredToolResultContent[]} */
+            const contentParts = [];
+            /** @type {string[]} */
+            const contentStrings = [];
+            let contentContainsImage = false;
+            if (Array.isArray(result.content)) {
+              for (const part of result.content) {
+                if ("text" in part && typeof part.text === "string") {
+                  contentParts.push({
+                    type: "text",
+                    text: part.text,
+                  });
+                  contentStrings.push(part.text);
+                } else if (
+                  part.type === "image" &&
+                  typeof part.mimeType === "string" &&
+                  typeof part.data === "string"
+                ) {
+                  contentParts.push({
+                    type: "image",
+                    data: part.data,
+                    mimeType: part.mimeType,
+                  });
+                  contentContainsImage = true;
+                } else {
+                  console.error(
+                    `Unsupported content part from MCP: ${JSON.stringify(part)}`,
+                  );
+                }
+              }
+            }
+
+            if (contentContainsImage) {
+              return contentParts;
+            }
+
+            const resultString = contentStrings.join("\n\n") || resultStringRaw;
+
+            /** @type {string} */
+            let formmatted = resultString;
+            let fileExtension = "txt";
+
+            try {
+              const parsed = JSON.parse(resultString);
+              formmatted = JSON.stringify(parsed, null, 2);
+              fileExtension = "json";
+            } catch {
+              // not JSON
+            }
+
+            if (formmatted.length <= OUTPUT_MAX_LENGTH) {
+              return formmatted;
+            }
+
+            const filePath = await writeTmpFile(
+              formmatted,
+              tool.name,
+              fileExtension,
+            );
+            const lineCount = formmatted.split("\n").length;
+
+            return [
+              `Content is large (${resultString.length} characters, ${lineCount} lines) and saved to ${filePath}`,
+              "Use exec_command tool to find relevant parts.",
+            ].join("\n");
+          }),
+      };
+    });
+
+  return tools;
+}

package/src/model.d.ts

@@ -0,0 +1,109 @@
+import type { ToolDefinition } from "./tool";
+
+export type CallModel = (input: ModelInput) => Promise<ModelOutput | Error>;
+
+export type ModelInput = {
+  messages: Message[];
+  tools?: ToolDefinition[];
+  onPartialMessageContent?: (partialContent: PartialMessageContent) => void;
+};
+
+export type ModelOutput = {
+  message: Message;
+  providerTokenUsage: ProviderTokenUsage;
+};
+
+export type ProviderTokenUsage = Record<
+  string,
+  number | string | Record<string, number>
+>;
+
+export type PartialMessageContent = {
+  type: string;
+  position: "start" | "stop" | "delta";
+  content?: string;
+};
+
+export type Message = SystemMessage | UserMessage | AssistantMessage;
+
+export type SystemMessage = {
+  role: "system";
+  content: MessageContentText[];
+};
+
+export type UserMessage = {
+  role: "user";
+  content: (
+    | MessageContentText
+    | MessageContentImage
+    | MessageContentToolResult
+  )[];
+};
+
+export type AssistantMessage = {
+  role: "assistant";
+  content: (
+    | MessageContentThinking
+    | MessageContentRedactedThinking
+    | MessageContentText
+    | MessageContentToolUse
+  )[];
+  provider?: MessageContentProvider;
+};
+
+export type MessageContentThinking = {
+  type: "thinking";
+  thinking: string;
+  provider?: MessageContentProvider;
+};
+
+export type MessageContentRedactedThinking = {
+  type: "redacted_thinking";
+  provider?: MessageContentProvider;
+};
+
+export type MessageContentText = {
+  type: "text";
+  text: string;
+  provider?: MessageContentProvider;
+};
+
+export type MessageContentImage = {
+  type: "image";
+
+  // base64 encoded image data
+  data: string;
+
+  // e.g., image/jpeg
+  mimeType: string;
+};
+
+export type MessageContentToolUse = {
+  type: "tool_use";
+  toolUseId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+  provider?: MessageContentProvider;
+};
+
+export type MessageContentToolResult = {
+  type: "tool_result";
+  toolUseId: string;
+  toolName: string;
+  content: (MessageContentText | MessageContentImage)[];
+  isError?: boolean;
+};
+
+export type MessageContentProvider = {
+  /**
+   * Raw source data from the provider
+   * (original message, response, output items, etc.)
+   */
+  source?: unknown;
+
+  /**
+   * Provider-specific fields that are directly merged
+   * into the content part sent to the provider API.
+   */
+  fields?: Record<string, unknown>;
+};

package/src/modelCaller.mjs

@@ -0,0 +1,29 @@
+import { callAnthropicModel } from "./providers/anthropic.mjs";
+import { createCacheEnabledGeminiModelCaller } from "./providers/gemini.mjs";
+import { callOpenAIModel } from "./providers/openai.mjs";
+import { callOpenAICompatibleModel } from "./providers/openaiCompatible.mjs";
+
+/**
+ * @param {import("./modelDefinition").ModelDefinition} modelDef
+ * @returns {import("./model").CallModel}
+ */
+export function createModelCaller(modelDef) {
+  const { platform, model } = modelDef;
+
+  switch (model.format) {
+    case "anthropic":
+      return (input) => callAnthropicModel(platform, model.config, input);
+    case "gemini": {
+      const modelCaller = createCacheEnabledGeminiModelCaller(
+        platform,
+        model.config,
+      );
+      return (input) => modelCaller(model.config, input);
+    }
+    case "openai-responses":
+      return (input) => callOpenAIModel(platform, model.config, input);
+    case "openai-messages":
+      return (input) =>
+        callOpenAICompatibleModel(platform, model.config, input);
+  }
+}

package/src/modelDefinition.d.ts

@@ -0,0 +1,73 @@
+import { AnthropicModelConfig } from "./providers/anthropic";
+import { GeminiModelConfig } from "./providers/gemini";
+import { OpenAIModelConfig } from "./providers/openai";
+import { OpenAICompatibleModelConfig } from "./providers/openaiCompatible";
+
+export type ModelDefinition = {
+  name: string;
+  variant: string;
+  platform: PlatformConfig;
+  model: ModelConfig;
+};
+
+export type PlatformConfig =
+  | {
+      name: "anthropic";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      apiKey: string;
+    }
+  | {
+      name: "gemini";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      apiKey: string;
+    }
+  | {
+      name: "openai";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      apiKey: string;
+    }
+  | {
+      name: "azure";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      azureConfigDir?: string;
+    }
+  | {
+      name: "bedrock";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      awsProfile: string;
+    }
+  | {
+      name: "vertex-ai";
+      variant: string;
+      baseURL: string;
+      customHeaders?: Record<string, string>;
+      account?: string;
+    };
+
+export type ModelConfig =
+  | {
+      format: "anthropic";
+      config: AnthropicModelConfig;
+    }
+  | {
+      format: "gemini";
+      config: GeminiModelConfig;
+    }
+  | {
+      format: "openai-responses";
+      config: OpenAIModelConfig;
+    }
+  | {
+      format: "openai-messages";
+      config: OpenAICompatibleModelConfig;
+    };

package/src/prompt.mjs

@@ -0,0 +1,128 @@
+/**
+ * @typedef {object} PromptConfig
+ * @property {string} username
+ * @property {string} modelName
+ * @property {string} sessionId
+ * @property {string} tmuxSessionId
+ * @property {string} workingDir - The current working directory.
+ * @property {string} projectMetadataDir - The directory where memory files are stored.
+ * @property {Map<string, import('./context/loadAgentRoles.mjs').AgentRole>} agentRoles - Available agent roles.
+ * @property {{filePath: string, description: string}[]} skills
+ */
+
+/**
+ * @param {PromptConfig} config
+ * @returns {string}
+ */
+export function createPrompt({
+  username,
+  modelName,
+  sessionId,
+  tmuxSessionId,
+  workingDir,
+  projectMetadataDir,
+  agentRoles,
+  skills,
+}) {
+  const agentRoleDescriptions = Array.from(agentRoles.entries())
+    .map(([id, role]) => {
+      const desc =
+        role.description.length > 100
+          ? `${role.description.substring(0, 100)}...`
+          : role.description;
+      return `- ${id}: ${desc}`;
+    })
+    .join("\n");
+
+  const skillDescriptions = skills
+    .map((skill) => {
+      const desc =
+        skill.description.length > 100
+          ? `${skill.description.substring(0, 100)}...`
+          : skill.description;
+      return `- ${skill.filePath}\n  ${desc}`;
+    })
+    .join("\n");
+
+  return `
+# Communication Style
+
+- Respond in the user's language.
+- Address the user by their name, rather than "user".
+- Use emojis sparingly to highlight key points.
+
+# Memory Files
+
+- Create/Update memory files after creating/updating a plan, completing milestones, encountering issues, or making decisions.
+- Update existing task memory when continuing the same task.
+- Write the memory content in the user's language.
+- Ensure self-containment: The file must be standalone. A reader should fully understand the task context, logic and progress without any other references.
+
+Memory files should include:
+- Task overview: What the task is, why it's being done, requirements and constraints
+- Context: Relevant documentation, source files, commands, and resources referenced
+- Progress tracking: Completed milestones with evidence, current status, and next steps
+- Decision records: Important decisions made, alternatives considered, and rationale
+- Findings and learnings: Key discoveries, challenges encountered, and solutions applied
+- Future considerations: Known limitations, potential improvements, and follow-up items
+
+# Tools
+
+Call multiple tools at once when they don't depend on each other's results.
+
+## exec_command
+
+- Use relative paths.
+- Avoid bash -c unless pipes (|) or redirection (>, <) are required.
+
+Examples:
+- List directories or find files: fd [".", "./", "--max-depth", "3", "--type", "d", "--hidden"]
+- Search for strings: rg ["--heading", "--line-number", "pattern", "./"]
+- Read specific line ranges (max 200 lines): sed ["-n", "1,200p", "file.txt"]
+- Manage GitHub issues and PRs:
+  Get PR details: gh ["pr", "view", "123", "--json", "title,body,url"]
+  Get PR comment: gh ["api", "--method", "GET", "repos/<owner>/<repo>/pulls/comments/<id>", "--jq", "{user: .user.login, path: .path, line: .line, body: .body}"]
+
+## tmux_command
+
+- Only use when the user explicitly requests it.
+- Create a new session with the given tmux session id.
+- Use relative paths.
+
+Examples:
+- Start session: new-session ["-d", "-s", "<tmux-session-id>"]
+- Detect window number to send keys: list-windows ["-t", "<tmux-session-id>"]
+- Get output of window before sending keys: capture-pane ["-p", "-t", "<tmux-session-id>:<window>"]
+- Send key to session: send-keys ["-t", "<tmux-session-id>:<window>", "echo hello", "Enter"]
+- Delete line: send-keys ["-t", "<tmux-session-id>:<window>", "C-a", "C-k"]
+
+# Project Rules and Skills
+ 
+Discover and apply project-specific rules and reusable skills.
+
+## AGENTS.md (falling back to CLAUDE.md if not found): Project-specific rules, conventions, and commands.
+
+Find: fd ["^(AGENTS|CLAUDE)\\.md$", "./", "--hidden", "--max-depth", "5"]
+Read from root to target: ./AGENTS.md → dir/AGENTS.md → dir/subdir/AGENTS.md
+Apply rules when working in that directory
+
+## SKILL.md: Reusable workflows with specialized knowledge
+
+If skill matches task: read full file and apply the workflow
+
+${skillDescriptions}
+
+# Environment
+
+- User name: ${username}
+- Your model name: ${modelName}
+- Current working directory: ${workingDir}
+- Session id: ${sessionId}
+- Tmux session id: ${tmuxSessionId}
+- Memory file path: ${projectMetadataDir}/memory/${sessionId}--<kebab-case-title>.md
+
+Available subagents:
+${agentRoleDescriptions}
+- custom:<role-name>: Use this for ad-hoc roles not listed above (e.g., custom:explore, custom:plan).
+`.trim();
+}