@iinm/plain-agent 1.0.0

package/src/agent.d.ts

@@ -0,0 +1,48 @@
+import type { EventEmitter } from "node:events";
+import type {
+  CallModel,
+  Message,
+  MessageContentImage,
+  MessageContentText,
+  PartialMessageContent,
+  ProviderTokenUsage,
+} from "./model";
+import type { Tool, ToolUseApprover } from "./tool";
+import type { AgentRole } from "./context/loadAgentRoles.mjs";
+
+export type Agent = {
+  userEventEmitter: UserEventEmitter;
+  agentEventEmitter: AgentEventEmitter;
+  agentCommands: AgentCommands;
+};
+
+export type AgentCommands = {
+  dumpMessages: () => Promise<void>;
+  loadMessages: () => Promise<void>;
+};
+
+type UserEventMap = {
+  userInput: [(MessageContentText | MessageContentImage)[]];
+};
+
+export type UserEventEmitter = EventEmitter<UserEventMap>;
+
+type AgentEventMap = {
+  message: [Message];
+  partialMessageContent: [PartialMessageContent];
+  error: [Error];
+  toolUseRequest: [];
+  turnEnd: [];
+  providerTokenUsage: [ProviderTokenUsage];
+  subagentSwitched: [{ name: string } | null];
+};
+
+export type AgentEventEmitter = EventEmitter<AgentEventMap>;
+
+export type AgentConfig = {
+  callModel: CallModel;
+  prompt: string;
+  tools: Tool[];
+  toolUseApprover: ToolUseApprover;
+  agentRoles: Map<string, AgentRole>;
+};

package/src/agent.mjs

@@ -0,0 +1,159 @@
+/**
+ * @import { Agent, AgentConfig, AgentEventEmitter, UserEventEmitter } from "./agent"
+ * @import { Tool, ToolDefinition } from "./tool"
+ * @import { DelegateToSubagentInput } from "./tools/delegateToSubagent"
+ * @import { ReportAsSubagentInput } from "./tools/reportAsSubagent"
+ */
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs/promises";
+import { createAgentLoop } from "./agentLoop.mjs";
+import { createStateManager } from "./agentState.mjs";
+import { MESSAGES_DUMP_FILE_PATH } from "./env.mjs";
+import { createSubagentManager } from "./subagent.mjs";
+import { createToolExecutor } from "./toolExecutor.mjs";
+import { delegateToSubagentToolName } from "./tools/delegateToSubagent.mjs";
+import { reportAsSubagentToolName } from "./tools/reportAsSubagent.mjs";
+
+/**
+ * @param {AgentConfig} config
+ * @returns {Agent}
+ */
+export function createAgent({
+  callModel,
+  prompt,
+  tools,
+  toolUseApprover,
+  agentRoles,
+}) {
+  /** @type {UserEventEmitter} */
+  const userEventEmitter = new EventEmitter();
+  /** @type {AgentEventEmitter} */
+  const agentEventEmitter = new EventEmitter();
+
+  const stateManager = createStateManager(
+    [
+      {
+        role: "system",
+        content: [{ type: "text", text: prompt }],
+      },
+    ],
+    {
+      onMessagesAppended: (newMessages) => {
+        const lastMessage = newMessages.at(-1);
+        if (!lastMessage) {
+          return;
+        }
+        agentEventEmitter.emit("message", lastMessage);
+      },
+    },
+  );
+
+  const subagentManager = createSubagentManager(agentRoles, {
+    onSubagentSwitched: (subagent) => {
+      agentEventEmitter.emit("subagentSwitched", subagent);
+    },
+  });
+
+  /**
+   * @param {DelegateToSubagentInput} input
+   */
+  const delegateToSubagentImpl = async (input) => {
+    const result = subagentManager.delegateToSubagent(
+      input.name,
+      input.goal,
+      stateManager.getMessages().length - 1,
+    );
+    if (!result.success) {
+      return new Error(result.error);
+    }
+    return result.value;
+  };
+
+  /**
+   * @param {ReportAsSubagentInput} input
+   */
+  const reportAsSubagentImpl = async (input) => {
+    const result = await subagentManager.reportAsSubagent(input.memoryPath);
+    if (!result.success) {
+      return new Error(result.error);
+    }
+    return result.memoryContent;
+  };
+
+  /** @type {Map<string, Tool>} */
+  const toolByName = new Map();
+  for (const tool of tools) {
+    if (tool.def.name === delegateToSubagentToolName && tool.injectImpl) {
+      tool.injectImpl(delegateToSubagentImpl);
+    }
+    if (tool.def.name === reportAsSubagentToolName && tool.injectImpl) {
+      tool.injectImpl(reportAsSubagentImpl);
+    }
+    toolByName.set(tool.def.name, tool);
+  }
+
+  /** @type {ToolDefinition[]} */
+  const toolDefs = tools.map(({ def }) => def);
+
+  const toolExecutor = createToolExecutor(toolByName, {
+    exclusiveToolNames: [delegateToSubagentToolName, reportAsSubagentToolName],
+  });
+
+  async function dumpMessages() {
+    const filePath = MESSAGES_DUMP_FILE_PATH;
+    try {
+      await fs.writeFile(
+        filePath,
+        JSON.stringify(stateManager.getMessages(), null, 2),
+      );
+      console.log(`Messages dumped to ${filePath}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error dumping messages: ${message}`);
+    }
+  }
+
+  async function loadMessages() {
+    const filePath = MESSAGES_DUMP_FILE_PATH;
+    try {
+      const data = await fs.readFile(filePath, "utf-8");
+      const loadedMessages = JSON.parse(data);
+      if (Array.isArray(loadedMessages)) {
+        // Keep the system message (index 0) and replace the rest
+        stateManager.setMessages([
+          stateManager.getMessageAt(0),
+          ...loadedMessages.slice(1),
+        ]);
+        console.log(`Messages loaded from ${filePath}`);
+      } else {
+        console.error("Error loading messages: Invalid format in file.");
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        console.error(`Error loading messages: ${error.message}`);
+      }
+    }
+  }
+
+  const agentLoop = createAgentLoop({
+    callModel,
+    stateManager,
+    toolDefs,
+    toolExecutor,
+    agentEventEmitter,
+    toolUseApprover,
+    subagentManager,
+  });
+
+  userEventEmitter.on("userInput", agentLoop.handleUserInput);
+
+  return {
+    userEventEmitter,
+    agentEventEmitter,
+    agentCommands: {
+      dumpMessages,
+      loadMessages,
+    },
+  };
+}

package/src/agentLoop.mjs

@@ -0,0 +1,369 @@
+/**
+ * @import { AgentEventEmitter } from "./agent"
+ * @import { CallModel, MessageContentText, MessageContentImage, MessageContentToolResult, PartialMessageContent, UserMessage, MessageContentToolUse } from "./model"
+ * @import { ToolDefinition, ToolUseApprover } from "./tool"
+ * @import { SubagentManager } from "./subagent.mjs"
+ * @import { StateManager } from "./agentState.mjs"
+ */
+
+import { styleText } from "node:util";
+import { consumeInterruptMessage } from "./context/consumeInterruptMessage.mjs";
+
+/**
+ * @typedef {Object} AgentLoopConfig
+ * @property {CallModel} callModel - Function to call the language model
+ * @property {StateManager} stateManager - State manager for message handling
+ * @property {ToolDefinition[]} toolDefs - Tool definitions for the model
+ * @property {import("./toolExecutor.mjs").ToolExecutor} toolExecutor - Tool executor instance
+ * @property {AgentEventEmitter} agentEventEmitter - Event emitter for agent events
+ * @property {ToolUseApprover} toolUseApprover - Tool use approval checker
+ * @property {SubagentManager} subagentManager - Subagent manager instance
+ */
+
+/**
+ * @typedef {ReturnType<typeof createAgentLoop>} AgentLoop
+ */
+
+/**
+ * Create an agent loop handler
+ * @param {AgentLoopConfig} config
+ */
+export function createAgentLoop({
+  callModel,
+  stateManager,
+  toolDefs,
+  toolExecutor,
+  agentEventEmitter,
+  toolUseApprover,
+  subagentManager,
+}) {
+  const inputHandler = createInputHandler({
+    stateManager,
+    toolExecutor,
+    subagentManager,
+    toolUseApprover,
+  });
+
+  /**
+   * Handle user input and run the agent turn loop
+   * @param {(MessageContentText | MessageContentImage)[]} input - User input content
+   * @returns {Promise<void>}
+   */
+  async function handleUserInput(input) {
+    toolUseApprover.resetApprovalCount();
+    await inputHandler.handle(input);
+    await runTurnLoop();
+    agentEventEmitter.emit("turnEnd");
+  }
+
+  /**
+   * Run the main agent turn loop
+   * @returns {Promise<void>}
+   */
+  async function runTurnLoop() {
+    let thinkingLoops = 0;
+    const maxThinkingLoops = 5;
+
+    while (true) {
+      const modelOutput = await callModel({
+        messages: stateManager.getMessages(),
+        tools: toolDefs,
+        /**
+         * @param {PartialMessageContent} partialContent
+         */
+        onPartialMessageContent: (partialContent) => {
+          agentEventEmitter.emit("partialMessageContent", partialContent);
+        },
+      });
+
+      if (modelOutput instanceof Error) {
+        agentEventEmitter.emit("error", modelOutput);
+        break;
+      }
+
+      const { message: assistantMessage, providerTokenUsage } = modelOutput;
+      stateManager.appendMessages([assistantMessage]);
+      agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+
+      // Gemini may stop with "thinking" -> continue
+      const lastContent = assistantMessage.content.at(-1);
+      if (lastContent?.type === "thinking") {
+        thinkingLoops += 1;
+        if (thinkingLoops > maxThinkingLoops) {
+          break;
+        }
+
+        stateManager.appendMessages([
+          {
+            role: "user",
+            content: [{ type: "text", text: "System: Continue" }],
+          },
+        ]);
+        console.error(
+          styleText(
+            "yellow",
+            `\nModel is thinking. Sending "System: Continue" (Loop: ${thinkingLoops}/${maxThinkingLoops})`,
+          ),
+        );
+        continue;
+      }
+
+      const toolUseParts = assistantMessage.content.filter(
+        (part) => part.type === "tool_use",
+      );
+
+      // No tool use -> turn end
+      if (toolUseParts.length === 0) {
+        break;
+      }
+
+      const validation = toolExecutor.validateBatch(toolUseParts);
+      if (!validation.isValid) {
+        stateManager.appendMessages([
+          {
+            role: "user",
+            content: validation.toolResults,
+          },
+        ]);
+        if (validation.errorMessage) {
+          console.error(styleText("yellow", validation.errorMessage));
+        }
+        continue;
+      }
+
+      // Approve tool use
+      const decisions = toolUseParts.map(toolUseApprover.isAllowedToolUse);
+
+      const hasDeniedToolUse = decisions.some((d) => d.action === "deny");
+      if (hasDeniedToolUse) {
+        /** @type {MessageContentToolResult[]} */
+        const toolResults = toolUseParts.map((toolUse, index) => {
+          const decision = decisions[index];
+          const rejectionMessage =
+            decision.action === "deny"
+              ? `Tool call rejected. ${decision.reason || ""}`.trim()
+              : "Tool call rejected due to other denied tool calls";
+
+          return {
+            type: "tool_result",
+            toolUseId: toolUse.toolUseId,
+            toolName: toolUse.toolName,
+            content: [{ type: "text", text: rejectionMessage }],
+            isError: true,
+          };
+        });
+        stateManager.appendMessages([{ role: "user", content: toolResults }]);
+        continue;
+      }
+
+      const isAllToolUseApproved = decisions.every((d) => d.action === "allow");
+      if (!isAllToolUseApproved) {
+        agentEventEmitter.emit("toolUseRequest");
+        break;
+      }
+
+      const executionResult = await toolExecutor.executeBatch(toolUseParts);
+
+      if (!executionResult.success) {
+        stateManager.appendMessages([
+          {
+            role: "user",
+            content: executionResult.errors,
+          },
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: executionResult.errorMessage,
+              },
+            ],
+          },
+        ]);
+        console.error(styleText("yellow", executionResult.errorMessage));
+        continue;
+      }
+
+      const toolResults = executionResult.results;
+
+      const result = subagentManager.processToolResults(
+        toolUseParts,
+        toolResults,
+        stateManager.getMessages(),
+      );
+      stateManager.setMessages(result.messages);
+      if (result.newMessage) {
+        stateManager.appendMessages([result.newMessage]);
+      } else {
+        stateManager.appendMessages([{ role: "user", content: toolResults }]);
+      }
+
+      const interruptMessage = await consumeInterruptMessage();
+      if (interruptMessage) {
+        stateManager.appendMessages([
+          {
+            role: "user",
+            content: [{ type: "text", text: interruptMessage }],
+          },
+        ]);
+      }
+    }
+  }
+
+  return {
+    handleUserInput,
+  };
+}
+
+/**
+ * @typedef {Object} InputHandlerContext
+ * @property {StateManager} stateManager
+ * @property {import("./toolExecutor.mjs").ToolExecutor} toolExecutor
+ * @property {import("./subagent.mjs").SubagentManager} subagentManager
+ * @property {import("./tool.d.ts").ToolUseApprover} toolUseApprover
+ */
+
+/**
+ * @typedef {ReturnType<typeof createInputHandler>} InputHandler
+ */
+
+/**
+ * Create an input handler.
+ *
+ * @param {InputHandlerContext} context
+ */
+export function createInputHandler(context) {
+  const { stateManager, toolExecutor, subagentManager, toolUseApprover } =
+    context;
+
+  /**
+   * Determine input type based on current state and input.
+   * @param {UserMessage["content"]} input
+   * @returns {'toolApproval' | 'resume' | 'text'}
+   */
+  function determineInputType(input) {
+    const lastMessage = stateManager.getMessageAt(-1);
+
+    // Check if there's a pending tool call
+    if (lastMessage?.content.some((part) => part.type === "tool_use")) {
+      return "toolApproval";
+    }
+
+    if (
+      input.length === 1 &&
+      input[0].type === "text" &&
+      input[0].text.toLowerCase() === "/resume"
+    ) {
+      return "resume";
+    }
+
+    return "text";
+  }
+
+  /**
+   * Handle tool approval/rejection input.
+   * @param {UserMessage["content"]} input
+   */
+  async function handleToolApproval(input) {
+    const lastMessage = stateManager.getMessageAt(-1);
+    if (!lastMessage) return;
+
+    /** @type {MessageContentToolUse[]} */
+    const toolUseParts = lastMessage.content.filter(
+      (part) => part.type === "tool_use",
+    );
+
+    const isApproval =
+      input.length === 1 &&
+      input[0].type === "text" &&
+      input[0].text.toLocaleLowerCase().match(/^(yes|y|ｙ)$/i);
+
+    if (isApproval) {
+      if (
+        /** @type {MessageContentText} */ (input[0]).text.match(/^(YES|Y)$/)
+      ) {
+        for (const toolUse of toolUseParts) {
+          toolUseApprover.allowToolUse(toolUse);
+        }
+      }
+
+      const executionResult = await toolExecutor.executeBatch(toolUseParts);
+      if (!executionResult.success) {
+        stateManager.appendMessages([
+          { role: "user", content: executionResult.errors },
+        ]);
+        return;
+      }
+
+      const toolResults = executionResult.results;
+      const result = subagentManager.processToolResults(
+        toolUseParts,
+        toolResults,
+        stateManager.getMessages(),
+      );
+      stateManager.setMessages(result.messages);
+
+      if (result.newMessage) {
+        stateManager.appendMessages([result.newMessage]);
+      } else {
+        stateManager.appendMessages([{ role: "user", content: toolResults }]);
+      }
+    } else {
+      // Rejected
+      /** @type {MessageContentToolResult[]} */
+      const toolResults = toolUseParts.map((toolUse) => ({
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [{ type: "text", text: "Tool call rejected" }],
+        isError: true,
+      }));
+
+      stateManager.appendMessages([
+        { role: "user", content: toolResults },
+        {
+          role: "user",
+          content: input,
+        },
+      ]);
+    }
+  }
+
+  async function handleResume() {
+    // Resume the conversation stopped by unexpected error, etc.
+    // No state changes needed
+  }
+
+  /**
+   * @param {UserMessage["content"]} input
+   */
+  async function handleText(input) {
+    stateManager.appendMessages([
+      {
+        role: "user",
+        content: input,
+      },
+    ]);
+  }
+
+  return {
+    /**
+     * @param {UserMessage["content"]} input
+     */
+    async handle(input) {
+      const inputType = determineInputType(input);
+
+      switch (inputType) {
+        case "toolApproval":
+          await handleToolApproval(input);
+          break;
+        case "resume":
+          await handleResume();
+          break;
+        case "text":
+          await handleText(input);
+          break;
+      }
+    },
+  };
+}

package/src/agentState.mjs

@@ -0,0 +1,41 @@
+/**
+ * @import { Message } from "./model"
+ */
+
+/**
+ * @typedef {ReturnType<typeof createStateManager>} StateManager
+ */
+
+/**
+ * @typedef {Object} StateEventHandlers
+ * @property {(messages: Message[]) => void} onMessagesAppended
+ */
+
+/**
+ * Creates a state manager for message handling.
+ * @param {Message[]} initialMessages
+ * @param {StateEventHandlers} handlers
+ */
+export function createStateManager(initialMessages, handlers) {
+  /** @type {Message[]} */
+  let messages = [...initialMessages];
+
+  return {
+    /** Get all messages (immutable copy) */
+    getMessages: () => [...messages],
+
+    /** Get message at specific index (supports -1 for last) */
+    getMessageAt: /** @param {number} index */ (index) => messages.at(index),
+
+    /** Append messages */
+    appendMessages: /** @param {Message[]} newMessages */ (newMessages) => {
+      messages = [...messages, ...newMessages];
+      handlers.onMessagesAppended(newMessages);
+    },
+
+    /** Replace all messages */
+    setMessages: /** @param {Message[]} newMessages */ (newMessages) => {
+      messages = [...newMessages];
+    },
+  };
+}

package/src/cliArgs.mjs

@@ -0,0 +1,45 @@
+/**
+ * @typedef {Object} CliArgs
+ * @property {string|null} model - Model name with variant
+ * @property {boolean} showHelp - Whether to show help message
+ */
+
+/**
+ * Parse command-line arguments.
+ * @param {string[]} argv - process.argv or similar
+ * @returns {CliArgs}
+ */
+export function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  /** @type {CliArgs} */
+  const result = { model: null, showHelp: false };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "-m" && args[i + 1]) {
+      result.model = args[++i];
+    } else if (args[i] === "-h" || args[i] === "--help") {
+      result.showHelp = true;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Print help message and exit.
+ * @param {number} [exitCode] - Exit code (default: 0)
+ */
+export function printHelp(exitCode = 0) {
+  console.log(`
+Usage: agent [options]
+
+Options:
+  -m <model+variant>  Model to use
+  -h, --help          Show this help message
+
+Examples:
+  agent -m claude-sonnet-4-6+thinking-16k
+  agent -m gpt-5.4+thinking-medium
+`);
+  process.exit(exitCode);
+}