@iinm/plain-agent 1.8.4 → 1.8.6

package/src/providers/platform/awsSigV4.mjs

@@ -0,0 +1,184 @@
+import { execFile } from "node:child_process";
+import { createHash, createHmac } from "node:crypto";
+
+/**
+ * @typedef {{ accessKeyId: string, secretAccessKey: string, sessionToken?: string }} AwsCredentials
+ */
+
+/** @type {Map<string, { credentials: AwsCredentials, expiration: Date }>} */
+const credentialCache = new Map();
+
+const EXPIRATION_MARGIN_MS = 60 * 1000;
+
+/**
+ * Load AWS credentials for the given profile using the AWS CLI.
+ * Results are cached and reused until the credentials expire.
+ * @param {string} profile
+ * @returns {Promise<AwsCredentials>}
+ */
+export async function loadAwsCredentials(profile) {
+  const cached = credentialCache.get(profile);
+  if (
+    cached &&
+    Date.now() < cached.expiration.getTime() - EXPIRATION_MARGIN_MS
+  ) {
+    return cached.credentials;
+  }
+
+  /** @type {string} */
+  const stdout = await new Promise((resolve, reject) => {
+    execFile(
+      "aws",
+      ["configure", "export-credentials", "--profile", profile],
+      {
+        shell: false,
+        timeout: 30 * 1000,
+      },
+      (error, stdout, _stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+  });
+  const parsed = JSON.parse(stdout);
+  for (const key of ["AccessKeyId", "SecretAccessKey"]) {
+    if (!parsed[key] || typeof parsed[key] !== "string") {
+      throw new Error(
+        `AWS credentials output missing ${key}. Raw output: ${stdout.slice(0, 200)}`,
+      );
+    }
+  }
+  const credentials = {
+    accessKeyId: parsed.AccessKeyId,
+    secretAccessKey: parsed.SecretAccessKey,
+    ...(parsed.SessionToken && { sessionToken: parsed.SessionToken }),
+  };
+
+  if (parsed.Expiration) {
+    const expiration = new Date(parsed.Expiration);
+    if (!Number.isNaN(expiration.getTime())) {
+      credentialCache.set(profile, { credentials, expiration });
+    }
+  }
+
+  return credentials;
+}
+
+/**
+ * Sign an HTTP request with AWS Signature V4.
+ *
+ * Known limitation: if duplicate header names with different casing exist
+ * (e.g. `Content-Type` and `content-type`), only the first match is used.
+ * Per AWS SigV4 spec, values should be combined with commas. Callers should
+ * ensure header names are unique (case-insensitive) before signing.
+ *
+ * @param {{
+ *   method: string,
+ *   hostname: string,
+ *   path: string,
+ *   headers: Record<string, string>,
+ *   body: string,
+ * }} request
+ * @param {{
+ *   region: string,
+ *   service: string,
+ *   credentials: AwsCredentials,
+ * }} options
+ * @returns {{ method: string, headers: Record<string, string>, body: string }}
+ */
+export function signAwsRequest(request, options) {
+  const { method, hostname, path, headers, body } = request;
+  const { region, service, credentials } = options;
+
+  const now = new Date();
+  const amzDate = now
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d{3}/, "");
+  const dateStamp = amzDate.slice(0, 8);
+
+  /** @type {Record<string, string>} */
+  const signedHeaders = { ...headers, host: hostname, "x-amz-date": amzDate };
+  if (credentials.sessionToken) {
+    signedHeaders["x-amz-security-token"] = credentials.sessionToken;
+  }
+
+  // Canonical headers: sorted, lowercased, trimmed
+  const sortedKeys = Object.keys(signedHeaders)
+    .map((k) => k.toLowerCase())
+    .sort();
+  const canonicalHeaders = sortedKeys
+    .map((k) => {
+      const original = Object.keys(signedHeaders).find(
+        (h) => h.toLowerCase() === k,
+      );
+      return `${k}:${signedHeaders[/** @type {string} */ (original)].trim()}`;
+    })
+    .join("\n");
+  const signedHeadersList = sortedKeys.join(";");
+
+  const payloadHash = sha256Hex(body || "");
+
+  // AWS SigV4 Canonical URI requires each path segment to be URI-encoded.
+  // URL.pathname returns a decoded string, so we need to re-encode it.
+  const canonicalUri = path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+
+  const canonicalRequest = [
+    method,
+    canonicalUri,
+    "", // query string (empty for POST)
+    `${canonicalHeaders}\n`,
+    signedHeadersList,
+    payloadHash,
+  ].join("\n");
+
+  // String to sign
+  const scope = `${dateStamp}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    sha256Hex(canonicalRequest),
+  ].join("\n");
+
+  // Signing key
+  const kDate = hmacSha256(`AWS4${credentials.secretAccessKey}`, dateStamp);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  const kSigning = hmacSha256(kService, "aws4_request");
+
+  const signature = createHmac("sha256", kSigning)
+    .update(stringToSign, "utf-8")
+    .digest("hex");
+
+  const authorization = `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeadersList}, Signature=${signature}`;
+
+  return {
+    method,
+    headers: { ...signedHeaders, Authorization: authorization },
+    body,
+  };
+}
+
+/**
+ * @param {string} data
+ * @returns {string}
+ */
+function sha256Hex(data) {
+  return createHash("sha256").update(data, "utf-8").digest("hex");
+}
+
+/**
+ * @param {string | Buffer} key
+ * @param {string} data
+ * @returns {Buffer}
+ */
+function hmacSha256(key, data) {
+  return createHmac("sha256", key).update(data, "utf-8").digest();
+}

package/src/providers/platform/azure.mjs

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+
+/**
+ * @param {{azureConfigDir: string}=} config
+ * @returns {Promise<string>}
+ */
+export async function getAzureAccessToken(config) {
+  /** @type {string} */
+  const stdout = await new Promise((resolve, reject) => {
+    execFile(
+      "az",
+      [
+        "account",
+        "get-access-token",
+        "--resource",
+        "https://cognitiveservices.azure.com",
+        "--query",
+        "accessToken",
+        "--output",
+        "tsv",
+      ],
+      {
+        shell: false,
+        timeout: 10 * 1000,
+        env: config
+          ? {
+              AZURE_CONFIG_DIR: config.azureConfigDir,
+            }
+          : undefined,
+      },
+      (error, stdout, _stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+  });
+
+  return stdout;
+}

package/src/providers/platform/bedrock.mjs

@@ -0,0 +1,78 @@
+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) {
+          // Invoke API format (base64 encoded event)
+          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)}`,
+            ),
+          );
+        } else {
+          // Converse API format (direct event data)
+          yield payloadParsed;
+        }
+      } 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,265 @@
+/**
+ * @import { Message, MessageContentToolResult, MessageContentToolUse } from "./model"
+ * @import { SwitchToMainAgentInput } from "./tools/switchToMainAgent"
+ * @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 { CLAUDE_CODE_COMPATIBILITY_NOTES } from "./prompt.mjs";
+import { switchToMainAgentToolName } from "./tools/switchToMainAgent.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; switchMessageIndex: number}[]} */
+  const subagents = [];
+  let subagentCount = 0;
+
+  /**
+   * @typedef {SwitchToSubagentSuccess | SwitchToSubagentFailure} SwitchToSubagentResult
+   */
+
+  /**
+   * @typedef {Object} SwitchToSubagentSuccess
+   * @property {true} success
+   * @property {string} value
+   */
+
+  /**
+   * @typedef {Object} SwitchToSubagentFailure
+   * @property {false} success
+   * @property {string} error
+   */
+
+  /**
+   * Switch to a subagent role.
+   * @param {string} name
+   * @param {string} goal
+   * @param {number} switchMessageIndex
+   * @returns {SwitchToSubagentResult}
+   */
+  function switchToSubagent(name, goal, switchMessageIndex) {
+    if (subagents.length > 0) {
+      return {
+        success: false,
+        error:
+          "Cannot call switch_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.claudeOriginated
+        ? `${role.content}\n\n---\n\n${CLAUDE_CODE_COMPATIBILITY_NOTES}`
+        : role.content;
+    }
+
+    subagentCount++;
+    const sequenceNumber = String(subagentCount).padStart(2, "0");
+
+    subagents.push({
+      name: actualName,
+      goal,
+      switchMessageIndex,
+    });
+    handlers.onSubagentSwitched({ name: actualName });
+
+    return {
+      success: true,
+      value: [
+        `[SUBAGENT MODE ACTIVATED] You are now operating as the subagent "${actualName}".`,
+        roleContent
+          ? `Role: ${actualName}\n---\n${roleContent}\n---`
+          : `Role: ${actualName}`,
+        `Your goal: ${goal}`,
+        `Memory file path format: ${AGENT_PROJECT_METADATA_DIR}/memory/<session-id>--${sequenceNumber}--${actualName.replace("/", "-")}--<kebab-case-title>.md (Replace <kebab-case-title> with a short title describing your own goal)`,
+        `When finished, call "switch_to_main_agent" with the memory file path. Start executing your goal now.`,
+      ].join("\n\n"),
+    };
+  }
+
+  /**
+   * @typedef {SwitchToMainAgentSuccess | SwitchToMainAgentFailure} SwitchToMainAgentResult
+   */
+
+  /**
+   * @typedef {Object} SwitchToMainAgentSuccess
+   * @property {true} success
+   * @property {string} memoryContent
+   */
+
+  /**
+   * @typedef {Object} SwitchToMainAgentFailure
+   * @property {false} success
+   * @property {string} error
+   */
+
+  /**
+   * Switch back to the main agent role and read the memory file.
+   * @param {string} memoryPath
+   * @returns {Promise<SwitchToMainAgentResult>}
+   */
+  async function switchToMainAgent(memoryPath) {
+    if (subagents.length === 0) {
+      return {
+        success: false,
+        error: "Cannot call switch_to_main_agent 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 === switchToMainAgentToolName,
+    );
+
+    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 switch 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 switch point
+    const truncatedMessages = messages.slice(
+      0,
+      currentSubagent.switchMessageIndex,
+    );
+
+    // 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 {SwitchToMainAgentInput} */ (
+      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 };
+  }
+
+  /**
+   * Whether the main agent is currently running as a subagent.
+   * @returns {boolean}
+   */
+  function isSubagentActive() {
+    return subagents.length > 0;
+  }
+
+  return {
+    switchToSubagent,
+    switchToMainAgent,
+    processToolResults,
+    isSubagentActive,
+  };
+}

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>;
+};