@iinm/plain-agent 1.0.0

package/src/providers/platform/bedrock.mjs

@@ -0,0 +1,74 @@
+import { styleText } from "node:util";
+
+/**
+ * @param {ReadableStreamDefaultReader<Uint8Array>} reader
+ */
+export async function* readBedrockStreamEvents(reader) {
+  let buffer = new Uint8Array();
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+
+    const nextBuffer = new Uint8Array(buffer.length + value.length);
+    nextBuffer.set(buffer);
+    nextBuffer.set(value, buffer.length);
+    buffer = nextBuffer;
+
+    // AWS event stream format
+    // https://github.com/awslabs/aws-c-event-stream/blob/main/docs/images/encoding.png
+    while (buffer.length >= 12) {
+      const view = new DataView(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength,
+      );
+      const totalLength = view.getUint32(0);
+      const headersLength = view.getUint32(4);
+
+      if (buffer.length < totalLength) {
+        break;
+      }
+
+      const payloadOffset = 12 + headersLength;
+      // prelude 12 bytes + CRC 4 bytes = 16
+      const payloadLength = totalLength - headersLength - 16;
+      const payloadRaw = buffer.slice(
+        payloadOffset,
+        payloadOffset + payloadLength,
+      );
+
+      const payloadDecoded = new TextDecoder().decode(payloadRaw);
+      try {
+        const payloadParsed = JSON.parse(payloadDecoded);
+        if (payloadParsed.bytes) {
+          const event = Buffer.from(payloadParsed.bytes, "base64").toString(
+            "utf-8",
+          );
+          const eventParsed = JSON.parse(event);
+          yield eventParsed;
+        } else if (payloadParsed.message) {
+          console.error(
+            styleText(
+              "yellow",
+              `Bedrock message received: ${JSON.stringify(payloadParsed.message)}`,
+            ),
+          );
+        }
+      } catch (err) {
+        if (err instanceof Error) {
+          console.error(
+            styleText(
+              "red",
+              `Error decoding payload: ${err.message}\nPayload: ${payloadDecoded}`,
+            ),
+          );
+        }
+      }
+
+      buffer = buffer.slice(totalLength);
+    }
+  }
+}

package/src/providers/platform/googleCloud.mjs

@@ -0,0 +1,34 @@
+import { execFile } from "node:child_process";
+
+/**
+ * @param {string=} account
+ * @returns {Promise<string>}
+ */
+export async function getGoogleCloudAccessToken(account) {
+  const accountOption = account?.endsWith("iam.gserviceaccount.com")
+    ? ["--impersonate-service-account", account]
+    : account
+      ? [account]
+      : [];
+
+  /** @type {string} */
+  const stdout = await new Promise((resolve, reject) => {
+    execFile(
+      "gcloud",
+      ["auth", "print-access-token", ...accountOption],
+      {
+        shell: false,
+        timeout: 10 * 1000,
+      },
+      (error, stdout, _stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+  });
+
+  return stdout;
+}

package/src/subagent.mjs

@@ -0,0 +1,247 @@
+/**
+ * @import { Message, MessageContentToolResult, MessageContentToolUse } from "./model"
+ * @import { ReportAsSubagentInput } from "./tools/reportAsSubagent"
+ * @import { AgentRole } from "./context/loadAgentRoles.mjs"
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENT_PROJECT_METADATA_DIR } from "./env.mjs";
+import { reportAsSubagentToolName } from "./tools/reportAsSubagent.mjs";
+
+/** @typedef {ReturnType<typeof createSubagentManager>} SubagentManager */
+
+/**
+ * @typedef {Object} SubagentStateEventHandlers
+ * @property {(subagent: {name:string} | null) => void} onSubagentSwitched
+ */
+
+/**
+ * Creates a manager for subagent lifecycle and state.
+ * @param {Map<string, AgentRole>} agentRoles
+ * @param {SubagentStateEventHandlers} handlers
+ */
+export function createSubagentManager(agentRoles, handlers) {
+  /** @type {{name: string; goal: string; delegationMessageIndex: number}[]} */
+  const subagents = [];
+
+  /**
+   * @typedef {DelegateSuccess | DelegateFailure} DelegateResult
+   */
+
+  /**
+   * @typedef {Object} DelegateSuccess
+   * @property {true} success
+   * @property {string} value
+   */
+
+  /**
+   * @typedef {Object} DelegateFailure
+   * @property {false} success
+   * @property {string} error
+   */
+
+  /**
+   * Delegate a task to a subagent.
+   * @param {string} name
+   * @param {string} goal
+   * @param {number} delegationMessageIndex
+   * @returns {DelegateResult}
+   */
+  function delegateToSubagent(name, goal, delegationMessageIndex) {
+    if (subagents.length > 0) {
+      return {
+        success: false,
+        error:
+          "Cannot call delegate_to_subagent while already acting as a subagent.",
+      };
+    }
+
+    const isCustomRole = name.startsWith("custom:");
+    const actualName = isCustomRole ? name.substring(7) : name;
+
+    let roleContent = "";
+    if (!isCustomRole) {
+      const role = agentRoles.get(name);
+      if (!role) {
+        const availableRoles = Array.from(agentRoles.keys())
+          .sort()
+          .map((id) => `  - ${id}`)
+          .join("\n");
+        return {
+          success: false,
+          error: `Agent role "${name}" not found. Available agent roles:\n${availableRoles}\n\nTo use an ad-hoc role, prefix the name with "custom:" (e.g., "custom:researcher").`,
+        };
+      }
+      roleContent = role.content;
+    }
+
+    subagents.push({
+      name: actualName,
+      goal,
+      delegationMessageIndex,
+    });
+    handlers.onSubagentSwitched({ name: actualName });
+
+    return {
+      success: true,
+      value: [
+        `✓ Delegation successful. You are now the subagent "${actualName}".`,
+        `Your goal: ${goal}`,
+        `Role: ${actualName}\n---\n${roleContent}\n---`,
+        `Memory file path format: ${AGENT_PROJECT_METADATA_DIR}/memory/<session-id>--${actualName}--<kebab-case-title>.md (Replace <kebab-case-title> to match the parent task)`,
+        `Start working on this goal now. When finished, call "report_as_subagent" with the memory file path.`,
+      ].join("\n\n"),
+    };
+  }
+
+  /**
+   * @typedef {ReportSuccess | ReportFailure} ReportResult
+   */
+
+  /**
+   * @typedef {Object} ReportSuccess
+   * @property {true} success
+   * @property {string} memoryContent
+   */
+
+  /**
+   * @typedef {Object} ReportFailure
+   * @property {false} success
+   * @property {string} error
+   */
+
+  /**
+   * Report as a subagent and read the memory file.
+   * @param {string} memoryPath
+   * @returns {Promise<ReportResult>}
+   */
+  async function reportAsSubagent(memoryPath) {
+    if (subagents.length === 0) {
+      return {
+        success: false,
+        error: "Cannot call report_as_subagent from the main agent.",
+      };
+    }
+
+    const absolutePath = path.resolve(memoryPath);
+    const memoryDir = path.resolve(AGENT_PROJECT_METADATA_DIR, "memory");
+    const relativePath = path.relative(memoryDir, absolutePath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+      return {
+        success: false,
+        error: `Access denied: memoryPath must be within ${AGENT_PROJECT_METADATA_DIR}/memory`,
+      };
+    }
+
+    try {
+      const memoryContent = await fs.readFile(absolutePath, {
+        encoding: "utf-8",
+      });
+      return {
+        success: true,
+        memoryContent: memoryContent,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: `Failed to read memory file: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  /**
+   * Process tool results and update state based on special tools.
+   * Returns the truncated message history and a new message to add.
+   * @param {MessageContentToolUse[]} toolUseParts
+   * @param {MessageContentToolResult[]} toolResults
+   * @param {Message[]} messages
+   * @returns {{ messages: Message[], newMessage: Message | null }}
+   *   - messages: The potentially truncated message history (new array)
+   *   - newMessage: The user message to add, or null if tool results should be added directly
+   */
+  function processToolResults(toolUseParts, toolResults, messages) {
+    const reportSubagentToolUse = toolUseParts.find(
+      (toolUse) => toolUse.toolName === reportAsSubagentToolName,
+    );
+
+    if (reportSubagentToolUse) {
+      const reportResult = toolResults.find(
+        (res) => res.toolUseId === reportSubagentToolUse.toolUseId,
+      );
+      if (!reportResult) {
+        return { messages, newMessage: null };
+      }
+      return handleSubagentReport(
+        reportSubagentToolUse,
+        reportResult,
+        messages,
+      );
+    }
+
+    return { messages, newMessage: null };
+  }
+
+  /**
+   * Handle the result of a subagent reporting back.
+   * On success, truncates conversation history back to the delegation point
+   * and converts the report into a standard user message.
+   * @param {MessageContentToolUse} reportToolUse
+   * @param {MessageContentToolResult} reportResult
+   * @param {Message[]} messages
+   * @returns {{ messages: Message[], newMessage: Message | null }}
+   *   - messages: The truncated message history (new array)
+   *   - newMessage: The user message to add, or null if not handled
+   */
+  function handleSubagentReport(reportToolUse, reportResult, messages) {
+    if (reportResult.isError) {
+      return { messages, newMessage: null };
+    }
+
+    const currentSubagent = subagents.pop();
+    if (!currentSubagent) {
+      return { messages, newMessage: null };
+    }
+
+    handlers.onSubagentSwitched(subagents.at(-1) ?? null);
+
+    // Truncate history back to the delegation point
+    const truncatedMessages = messages.slice(
+      0,
+      currentSubagent.delegationMessageIndex,
+    );
+
+    // Convert the tool result into a standard user message
+    const resultText = reportResult.content
+      .map((c) => (c.type === "text" ? c.text : ""))
+      .join("\n\n");
+
+    const reportInput = /** @type {ReportAsSubagentInput} */ (
+      reportToolUse.input
+    );
+
+    /** @type {import('./model').UserMessage} */
+    const newMessage = {
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: [
+            `The subagent "${currentSubagent.name}" has completed the task.`,
+            `Goal: ${currentSubagent.goal}`,
+            `Memory file: ${reportInput.memoryPath}`,
+            `Result:\n${resultText}`,
+          ].join("\n\n"),
+        },
+      ],
+    };
+
+    return { messages: truncatedMessages, newMessage };
+  }
+
+  return {
+    delegateToSubagent,
+    reportAsSubagent,
+    processToolResults,
+  };
+}

package/src/tmpfile.mjs

@@ -0,0 +1,27 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENT_TMP_DIR } from "./env.mjs";
+
+/**
+ * Write content to a temporary file and return the file path
+ * @param {string} content - Content to write
+ * @param {string} name - File name (e.g., "read_web_page")
+ * @param {string} extension - File extension (e.g., "md", "txt")
+ * @returns {Promise<string>} Path to the created temporary file
+ */
+export async function writeTmpFile(content, name, extension = "txt") {
+  const timestamp = new Date()
+    .toISOString()
+    .slice(0, 19)
+    .replace("T", "-")
+    .replace(/:/g, "");
+  const randomSuffix = Math.random().toString(36).substring(2, 8);
+
+  const fileName = `${timestamp}-${randomSuffix}--${name}.${extension}`;
+  const filePath = path.join(AGENT_TMP_DIR, fileName);
+
+  await fs.mkdir(AGENT_TMP_DIR, { recursive: true });
+  await fs.writeFile(filePath, content, "utf8");
+
+  return filePath;
+}

package/src/tool.d.ts

@@ -0,0 +1,74 @@
+import type { MessageContentToolUse } from "./model";
+
+export type Tool = {
+  def: ToolDefinition;
+  impl: ToolImplementation;
+  validateInput?: (input: Record<string, unknown>) => Error | undefined;
+  maskApprovalInput?: (
+    input: Record<string, unknown>,
+  ) => Record<string, unknown>;
+  injectImpl?: (impl: ToolImplementation) => void;
+};
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+export type ToolImplementation = (
+  input: Record,
+) => Promise<string | StructuredToolResultContent[] | Error>;
+
+export type StructuredToolResultContent =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "image";
+      // base64 encoded
+      data: string;
+      // e.g., image/jpeg
+      mimeType: string;
+    };
+
+export type ToolUseApproverConfig = {
+  patterns: ToolUsePattern[];
+  maxApprovals: number;
+  defaultAction: "deny" | "ask";
+
+  /**
+   * Mask the input before auto-approval checks and recording.
+   * Return a redacted object (e.g., keep only necessary fields) that will be used for:
+   * - safety validation via isSafeToolInput
+   * - storing per-session allowed tool-use patterns
+   */
+  maskApprovalInput: (
+    toolName: string,
+    input: Record<string, unknown>,
+  ) => Record<string, unknown>;
+};
+
+export type ToolUseDecision = {
+  action: "allow" | "deny" | "ask";
+  reason?: string;
+};
+
+export type ToolUseApprover = {
+  isAllowedToolUse: (toolUse: MessageContentToolUse) => ToolUseDecision;
+  allowToolUse: (toolUse: MessageContentToolUse) => void;
+  resetApprovalCount: () => void;
+};
+
+export type ToolUsePattern = {
+  toolName: ValuePattern;
+  input?: ObjectPattern;
+  action?: "allow" | "deny" | "ask";
+  reason?: string;
+};
+
+export type ToolUse = {
+  toolName: string;
+  input: Record<string, unknown>;
+};

package/src/toolExecutor.mjs

@@ -0,0 +1,236 @@
+/**
+ * @import { MessageContentToolResult, MessageContentToolUse } from "./model"
+ * @import { Tool } from "./tool"
+ */
+
+/**
+ * @typedef {ReturnType<typeof createToolExecutor>} ToolExecutor
+ */
+
+/**
+ * @typedef {Object} ToolExecutorOptions
+ * @property {string[]} [exclusiveToolNames] - Tool names that must be called exclusively
+ */
+
+/**
+ * Create a tool executor that handles tool validation, execution, and error handling
+ * @param {Map<string, Tool>} toolByName - Map of tool names to tool implementations
+ * @param {ToolExecutorOptions} [options] - Configuration options
+ */
+export function createToolExecutor(toolByName, options = {}) {
+  const { exclusiveToolNames = [] } = options;
+
+  /**
+   * @typedef {ValidationSuccess | ValidationFailure} ValidationResult
+   */
+
+  /**
+   * @typedef {Object} ValidationSuccess
+   * @property {true} isValid
+   */
+
+  /**
+   * @typedef {Object} ValidationFailure
+   * @property {false} isValid
+   * @property {string} errorMessage
+   * @property {MessageContentToolResult[]} toolResults
+   */
+
+  /**
+   * Validate all tool uses (tool existence, input validation, exclusive tool check)
+   * @param {MessageContentToolUse[]} toolUseParts - Tool uses to validate
+   * @returns {ValidationResult}
+   */
+  function validateBatch(toolUseParts) {
+    // Tool existence + Input validation
+    /** @type {{index: number, message: string}[]} */
+    const errors = [];
+
+    for (let i = 0; i < toolUseParts.length; i++) {
+      const toolUse = toolUseParts[i];
+      const tool = toolByName.get(toolUse.toolName);
+      if (!tool) {
+        errors.push({
+          index: i,
+          message: `Tool not found: ${toolUse.toolName}`,
+        });
+        continue;
+      }
+
+      if (tool.validateInput) {
+        const result = tool.validateInput(toolUse.input);
+        if (result instanceof Error) {
+          errors.push({ index: i, message: result.message });
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      return {
+        isValid: false,
+        errorMessage: errors.map((e) => e.message).join("; "),
+        toolResults: toolUseParts.map((toolUse, index) => {
+          const error = errors.find((e) => e.index === index);
+          return {
+            type: "tool_result",
+            toolUseId: toolUse.toolUseId,
+            toolName: toolUse.toolName,
+            content: [
+              {
+                type: "text",
+                text: error
+                  ? error.message
+                  : "Tool call rejected due to other tool validation error",
+              },
+            ],
+            isError: true,
+          };
+        }),
+      };
+    }
+
+    // Exclusive tool validation
+    const exclusiveResult = validateExclusiveTools(toolUseParts);
+    if (!exclusiveResult.isValid) {
+      return {
+        isValid: false,
+        errorMessage: exclusiveResult.errorMessage,
+        toolResults: toolUseParts.map((t) => ({
+          type: "tool_result",
+          toolUseId: t.toolUseId,
+          toolName: t.toolName,
+          content: [{ type: "text", text: exclusiveResult.errorMessage }],
+          isError: true,
+        })),
+      };
+    }
+
+    return { isValid: true };
+  }
+
+  /**
+   * @typedef {ExecuteBatchSuccess | ExecuteBatchFailure} ExecuteBatchResult
+   */
+
+  /**
+   * @typedef {Object} ExecuteBatchSuccess
+   * @property {true} success - Execution succeeded
+   * @property {MessageContentToolResult[]} results - Tool results on success
+   */
+
+  /**
+   * @typedef {Object} ExecuteBatchFailure
+   * @property {false} success - Execution failed
+   * @property {MessageContentToolResult[]} errors - Error tool results on validation failure
+   * @property {string} errorMessage - Error message on validation failure
+   */
+
+  /**
+   * Validate and execute multiple tools
+   * @param {MessageContentToolUse[]} toolUseParts
+   * @returns {Promise<ExecuteBatchResult>}
+   */
+  async function executeBatch(toolUseParts) {
+    const validation = validateBatch(toolUseParts);
+
+    if (!validation.isValid) {
+      return {
+        success: false,
+        errors: /** @type {MessageContentToolResult[]} */ (
+          validation.toolResults
+        ),
+        errorMessage: /** @type {string} */ (validation.errorMessage),
+      };
+    }
+
+    const results = [];
+    for (const toolUse of toolUseParts) {
+      results.push(await execute(toolUse));
+    }
+
+    return {
+      success: true,
+      results,
+    };
+  }
+
+  /**
+   * Validate exclusive tool constraints
+   * @param {MessageContentToolUse[]} toolUseParts
+   * @returns {{isValid: true} | {isValid: false, errorMessage: string}}
+   */
+  function validateExclusiveTools(toolUseParts) {
+    const exclusiveTools = toolUseParts.filter((t) =>
+      exclusiveToolNames.includes(t.toolName),
+    );
+
+    if (exclusiveTools.length > 1) {
+      const toolNames = exclusiveTools.map((t) => t.toolName).join(", ");
+      return {
+        isValid: false,
+        errorMessage: `System: ${toolNames} cannot be called together. Only one of these tools can be called at a time.`,
+      };
+    }
+
+    if (exclusiveTools.length === 1 && toolUseParts.length > 1) {
+      return {
+        isValid: false,
+        errorMessage: `System: ${exclusiveTools[0].toolName} cannot be called with other tools. It must be called alone.`,
+      };
+    }
+
+    return { isValid: true };
+  }
+
+  /**
+   * Execute a tool use and return the result
+   * @param {MessageContentToolUse} toolUse
+   * @returns {Promise<MessageContentToolResult>}
+   */
+  async function execute(toolUse) {
+    const tool = toolByName.get(toolUse.toolName);
+    if (!tool) {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [
+          { type: "text", text: `Tool not found: ${toolUse.toolName}` },
+        ],
+        isError: true,
+      };
+    }
+
+    const result = await tool.impl(toolUse.input);
+    if (result instanceof Error) {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [{ type: "text", text: result.message }],
+        isError: true,
+      };
+    }
+
+    if (typeof result === "string") {
+      return {
+        type: "tool_result",
+        toolUseId: toolUse.toolUseId,
+        toolName: toolUse.toolName,
+        content: [{ type: "text", text: result }],
+      };
+    }
+
+    return {
+      type: "tool_result",
+      toolUseId: toolUse.toolUseId,
+      toolName: toolUse.toolName,
+      content: result,
+    };
+  }
+
+  return {
+    executeBatch,
+    validateBatch,
+  };
+}