@mono-agent/agent-runtime 0.17.1 → 0.18.0

package/src/ai/providers/acp-privacy.js

@@ -0,0 +1,124 @@
+// @ts-check
+
+const PRIVATE_PROTOCOL_KEYS = new Set(["_meta", "sessionId", "session_id"]);
+const REDACTED = "[redacted]";
+const MAX_HOST_VALUE_DEPTH = 32;
+const MAX_HOST_VALUE_NODES = 4_096;
+// ACP v1's SessionUpdate union is closed. Never carry an arbitrary peer
+// discriminator onto a host-facing event, even when the SDK boundary is
+// bypassed or becomes more permissive.
+const ACP_SESSION_UPDATE_KINDS = new Set([
+  "user_message_chunk",
+  "agent_message_chunk",
+  "agent_thought_chunk",
+  "tool_call",
+  "tool_call_update",
+  "plan",
+  "plan_update",
+  "plan_removed",
+  "available_commands_update",
+  "current_mode_update",
+  "config_option_update",
+  "session_info_update",
+  "usage_update",
+]);
+
+/**
+ * ACP protocol session ids are connection state, not host-facing metadata.
+ * Remove their canonical keys, discard extension metadata, and redact copies
+ * embedded by an agent in otherwise public strings.
+ *
+ * @param {unknown} value
+ * @param {ReadonlyArray<unknown>} [rawSecrets]
+ * @returns {{value: any, truncated: boolean}}
+ */
+export function sanitizeAcpHostValueWithStatus(value, rawSecrets = []) {
+  const secrets = rawSecrets
+    .filter((secret) => typeof secret === "string" && secret.length > 0)
+    .sort((left, right) => /** @type {string} */ (right).length - /** @type {string} */ (left).length);
+
+  /** @param {string} text */
+  const redact = (text) => {
+    let result = text;
+    for (const secret of secrets) {
+      result = result.replaceAll(/** @type {string} */ (secret), REDACTED);
+    }
+    return result;
+  };
+
+  let nodes = 0;
+  let truncated = false;
+
+  /** @param {unknown} item @param {WeakSet<object>} ancestors @param {number} depth @returns {any} */
+  const visit = (item, ancestors, depth) => {
+    nodes += 1;
+    if (nodes > MAX_HOST_VALUE_NODES || depth > MAX_HOST_VALUE_DEPTH) {
+      truncated = true;
+      return null;
+    }
+    if (typeof item === "string") return redact(item);
+    if (Array.isArray(item)) {
+      if (ancestors.has(item)) {
+        truncated = true;
+        return null;
+      }
+      ancestors.add(item);
+      const result = [];
+      for (const entry of item) {
+        if (nodes >= MAX_HOST_VALUE_NODES) {
+          truncated = true;
+          break;
+        }
+        result.push(visit(entry, ancestors, depth + 1));
+      }
+      ancestors.delete(item);
+      return result;
+    }
+    if (!item || typeof item !== "object") return item;
+    if (ancestors.has(item)) {
+      truncated = true;
+      return null;
+    }
+    ancestors.add(item);
+    /** @type {Record<string, unknown>} */
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(item)) {
+      if (nodes >= MAX_HOST_VALUE_NODES) {
+        truncated = true;
+        break;
+      }
+      if (PRIVATE_PROTOCOL_KEYS.has(key)) continue;
+      Object.defineProperty(result, redact(key), {
+        value: visit(entry, ancestors, depth + 1),
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+    }
+    ancestors.delete(item);
+    return result;
+  };
+
+  return { value: visit(value, new WeakSet(), 0), truncated };
+}
+
+/**
+ * Compatibility wrapper for callback/list surfaces that intentionally accept
+ * a bounded representation. Protocol normalization should use the status form
+ * above so it can fail explicitly instead of consuming partial data.
+ *
+ * @param {unknown} value
+ * @param {ReadonlyArray<unknown>} [rawSecrets]
+ * @returns {any}
+ */
+export function sanitizeAcpHostValue(value, rawSecrets = []) {
+  return sanitizeAcpHostValueWithStatus(value, rawSecrets).value;
+}
+
+/** @param {unknown} value @returns {string|null} */
+export function ownAcpSessionUpdateKind(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!Object.hasOwn(value, "sessionUpdate")) return null;
+  const kind = /** @type {{sessionUpdate?: unknown}} */ (value).sessionUpdate;
+  return typeof kind === "string" && ACP_SESSION_UPDATE_KINDS.has(kind) ? kind : null;
+}

package/src/ai/providers/acp-public.js

@@ -0,0 +1,21 @@
+// Public high-level ACP surface. The owned stdio connection and raw protocol
+// session state stay in acp-client.js and are intentionally not package exports.
+
+/** @typedef {import("./acp-client.js").AcpProfileDescriptor} AcpProfileDescriptor */
+/** @typedef {import("./acp-client.js").AcpCallbackContext} AcpCallbackContext */
+/** @typedef {import("./acp-client.js").AcpInteractionRequest} AcpInteractionRequest */
+/** @typedef {import("./acp-client.js").AcpClientHostOptions} AcpClientHostOptions */
+/** @typedef {import("./acp-client.js").AcpListedSession} AcpListedSession */
+/** @typedef {import("./acp-client.js").AcpSessionListResult} AcpSessionListResult */
+
+export {
+  ACP_PROTOCOL_VERSION,
+  AcpClientError,
+  authenticateAcpProfile,
+  deleteAcpSession,
+  listAcpSessions,
+  logoutAcpProfile,
+  probeAcpProfile,
+  validateAcpProfileId,
+  validateAcpProviderSessionId,
+} from "./acp-client.js";

package/src/ai/providers/acp-session-tokens.js

@@ -0,0 +1,129 @@
+// @ts-check
+
+const PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const MAX_PROFILE_ID_LENGTH = 128;
+const MAX_RAW_TOKEN_BYTES = 4_096;
+const MAX_ENCODED_TOKEN_LENGTH = Math.ceil(MAX_RAW_TOKEN_BYTES * 4 / 3);
+const PROVIDER_SESSION_PREFIX = "acp:v1:";
+const SESSION_CURSOR_PREFIX = "acp-cursor:v1:";
+const MAX_PROVIDER_SESSION_ID_LENGTH = PROVIDER_SESSION_PREFIX.length
+  + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
+const MAX_SESSION_CURSOR_LENGTH = SESSION_CURSOR_PREFIX.length
+  + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
+
+export class AcpClientError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "AcpClientError";
+    this.code = code;
+    this.details = { ...details, code };
+  }
+}
+
+/** @param {string} profileId @returns {string} */
+export function validateAcpProfileId(profileId) {
+  if (typeof profileId !== "string" || !PROFILE_ID_RE.test(profileId)) {
+    throw new AcpClientError(
+      "invalid_profile_id",
+      "ACP profile id must use 1-128 ASCII letters, digits, dots, underscores, or hyphens and start alphanumeric.",
+    );
+  }
+  return profileId;
+}
+
+/** @param {unknown} value @param {string} code @param {string} label */
+function requiredTokenString(value, code, label) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.includes("\0")) {
+    throw new AcpClientError(code, `${label} must be a non-empty trimmed string without NUL bytes.`);
+  }
+  return value;
+}
+
+/** @param {string} encoded @param {string} code @param {string} label */
+function decodeToken(encoded, code, label) {
+  if (!BASE64URL_RE.test(encoded)) throw new AcpClientError(code, `Invalid ${label} encoding.`);
+  const bytes = Buffer.from(encoded, "base64url");
+  if (bytes.length === 0 || bytes.toString("base64url") !== encoded) {
+    throw new AcpClientError(code, `Non-canonical ${label} encoding.`);
+  }
+  if (bytes.length > MAX_RAW_TOKEN_BYTES) {
+    throw new AcpClientError(code, `${label} exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  }
+  try {
+    return requiredTokenString(new TextDecoder("utf-8", { fatal: true }).decode(bytes), code, label);
+  } catch (error) {
+    if (error instanceof AcpClientError) throw error;
+    throw new AcpClientError(code, `${label} is not valid UTF-8.`);
+  }
+}
+
+/** @param {string} profileId @param {string} sessionId */
+export function encodeAcpProviderSessionId(profileId, sessionId) {
+  validateAcpProfileId(profileId);
+  requiredTokenString(sessionId, "invalid_session_id", "ACP session id");
+  if (Buffer.byteLength(sessionId, "utf8") > MAX_RAW_TOKEN_BYTES) {
+    throw new AcpClientError("invalid_session_id", `ACP session id exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  }
+  return `${PROVIDER_SESSION_PREFIX}${profileId}:${Buffer.from(sessionId, "utf8").toString("base64url")}`;
+}
+
+/** Internal protocol-state decoder. This module is not a package export. @param {string} providerSessionId */
+export function decodeAcpProviderSessionId(providerSessionId) {
+  if (typeof providerSessionId !== "string") {
+    throw new AcpClientError("invalid_session_id", "ACP provider session id must be a string.");
+  }
+  if (providerSessionId.length > MAX_PROVIDER_SESSION_ID_LENGTH) {
+    throw new AcpClientError("invalid_session_id", "ACP provider session id exceeds the supported length.");
+  }
+  const match = /^acp:v1:([^:]+):([^:]+)$/.exec(providerSessionId);
+  if (!match) throw new AcpClientError("invalid_session_id", "Invalid ACP provider session id.");
+  const profileId = validateAcpProfileId(match[1]);
+  const sessionId = decodeToken(match[2], "invalid_session_id", "ACP session id");
+  return { profileId, sessionId };
+}
+
+/**
+ * Validate an opaque provider-session handle and its profile binding without
+ * exposing the remote agent's protocol session id.
+ *
+ * @param {string} providerSessionId
+ * @param {string} expectedProfileId
+ * @returns {string}
+ */
+export function validateAcpProviderSessionId(providerSessionId, expectedProfileId) {
+  const profileId = validateAcpProfileId(expectedProfileId);
+  const decoded = decodeAcpProviderSessionId(providerSessionId);
+  if (decoded.profileId !== profileId) {
+    throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
+  }
+  return providerSessionId;
+}
+
+/** @param {string} profileId @param {string} cursor */
+export function encodeAcpSessionCursor(profileId, cursor) {
+  validateAcpProfileId(profileId);
+  requiredTokenString(cursor, "invalid_cursor", "ACP session cursor");
+  if (Buffer.byteLength(cursor, "utf8") > MAX_RAW_TOKEN_BYTES) {
+    throw new AcpClientError("invalid_cursor", `ACP session cursor exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  }
+  return `${SESSION_CURSOR_PREFIX}${profileId}:${Buffer.from(cursor, "utf8").toString("base64url")}`;
+}
+
+/** @param {string} profileId @param {unknown} cursor */
+export function decodeAcpSessionCursor(profileId, cursor) {
+  validateAcpProfileId(profileId);
+  if (typeof cursor !== "string" || cursor.length > MAX_SESSION_CURSOR_LENGTH) {
+    throw new AcpClientError("invalid_cursor", "ACP session cursor must be an opaque cursor returned by listAcpSessions.");
+  }
+  const match = /^acp-cursor:v1:([^:]+):([^:]+)$/.exec(cursor);
+  if (!match || match[1] !== profileId) {
+    throw new AcpClientError("invalid_cursor", "ACP session cursor is invalid for this profile.");
+  }
+  return decodeToken(match[2], "invalid_cursor", "ACP session cursor");
+}

package/src/ai/providers/acp-transport.js

@@ -0,0 +1,259 @@
+// @ts-check
+
+// Strict, bounded ACP v1 newline transport for an owned stdio child process.
+// The SDK's stock ndJsonStream intentionally tolerates malformed input and its
+// line buffer is unbounded, which is a poor fit for a long-lived host boundary.
+
+const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
+const MAX_MAX_LINE_BYTES = 16 * 1024 * 1024;
+
+export class AcpTransportError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "AcpTransportError";
+    this.code = code;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function normalizeAcpMaxLineBytes(value, fallback = DEFAULT_MAX_LINE_BYTES) {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || Number(value) < 1024 || Number(value) > MAX_MAX_LINE_BYTES) {
+    throw new AcpTransportError(
+      "invalid_transport_policy",
+      `ACP maxLineBytes must be an integer between 1024 and ${MAX_MAX_LINE_BYTES}.`,
+    );
+  }
+  return Number(value);
+}
+
+/**
+ * The transport only accepts individual JSON-RPC 2.0 objects. Batches are not
+ * part of ACP v1 and are rejected before the SDK sees them.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isIndividualJsonRpcMessage(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.jsonrpc !== "2.0") return false;
+
+  const hasId = Object.hasOwn(record, "id");
+  const hasMethod = Object.hasOwn(record, "method");
+  const hasParams = Object.hasOwn(record, "params");
+  const hasResult = Object.hasOwn(record, "result");
+  const hasError = Object.hasOwn(record, "error");
+
+  const validId = !hasId
+    || record.id === null
+    || typeof record.id === "string"
+    || (typeof record.id === "number" && Number.isFinite(record.id));
+  if (!validId) return false;
+
+  if (hasMethod) {
+    if (typeof record.method !== "string" || record.method.length === 0) return false;
+    if (hasParams) {
+      const params = record.params;
+      if (!params || typeof params !== "object") return false;
+    }
+    return !hasResult && !hasError;
+  }
+
+  if (!hasId || hasParams || hasResult === hasError) return false;
+  if (!hasError) return true;
+  if (!record.error || typeof record.error !== "object" || Array.isArray(record.error)) return false;
+  const error = /** @type {Record<string, unknown>} */ (record.error);
+  return Number.isInteger(error.code) && typeof error.message === "string";
+}
+
+/**
+ * @param {Buffer} line
+ * @returns {Record<string, unknown>}
+ */
+function decodeLine(line) {
+  if (line.length === 0) {
+    throw new AcpTransportError("invalid_jsonrpc", "ACP peer emitted an empty NDJSON line.");
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(line);
+  } catch {
+    throw new AcpTransportError("invalid_utf8", "ACP peer emitted invalid UTF-8.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new AcpTransportError("invalid_jsonrpc", "ACP peer emitted malformed JSON.");
+  }
+  if (!isIndividualJsonRpcMessage(parsed)) {
+    throw new AcpTransportError("invalid_jsonrpc", "ACP peer emitted a non-ACP JSON-RPC message.");
+  }
+  return parsed;
+}
+
+/**
+ * Build the Stream shape consumed by @agentclientprotocol/sdk from a child
+ * process's stdin/stdout. Both inbound and outbound payloads are capped.
+ *
+ * @param {{stdin: import('node:stream').Writable|null, stdout: import('node:stream').Readable|null}} child
+ * @param {{maxLineBytes?: number}} [options]
+ * @returns {{readable: ReadableStream<any>, writable: WritableStream<any>}}
+ */
+export function createBoundedAcpStdioStream(child, options = {}) {
+  const maxLineBytes = normalizeAcpMaxLineBytes(options.maxLineBytes);
+  if (!child.stdin || !child.stdout) {
+    throw new AcpTransportError("stdio_unavailable", "ACP child stdio is unavailable.");
+  }
+  const input = child.stdout;
+  const output = child.stdin;
+
+  let pending = Buffer.alloc(0);
+  let settled = false;
+  let inputEnded = false;
+  /** @type {ReadableStreamDefaultController<any>|null} */
+  let readableController = null;
+
+  const cleanupReadable = () => {
+    input.off("data", onData);
+    input.off("end", onEnd);
+    input.off("error", onError);
+  };
+  const failReadable = (error) => {
+    if (settled) return;
+    settled = true;
+    input.pause();
+    cleanupReadable();
+    readableController?.error(error instanceof Error
+      ? error
+      : new AcpTransportError("transport_failed", "ACP stdout failed."));
+  };
+  const firstPendingLineIsTooLarge = () => {
+    const newline = pending.indexOf(0x0a);
+    if (newline !== -1) {
+      const contentBytes = newline > 0 && pending[newline - 1] === 0x0d ? newline - 1 : newline;
+      return contentBytes > maxLineBytes;
+    }
+    if (pending.length <= maxLineBytes) return false;
+    return pending.length > maxLineBytes + 1 || pending[pending.length - 1] !== 0x0d;
+  };
+  const finishReadableIfEnded = () => {
+    if (!inputEnded || settled || !readableController) return false;
+    if (pending.length === 0) {
+      settled = true;
+      cleanupReadable();
+      readableController.close();
+      return true;
+    }
+    if (pending.indexOf(0x0a) === -1) {
+      failReadable(new AcpTransportError(
+        "unterminated_line",
+        "ACP peer closed stdout with an unterminated JSON-RPC line.",
+      ));
+      return true;
+    }
+    return false;
+  };
+  const drainPending = () => {
+    if (settled || !readableController) return;
+    while (readableController.desiredSize !== null && readableController.desiredSize > 0) {
+      const newline = pending.indexOf(0x0a);
+      if (newline === -1) break;
+      let line = pending.subarray(0, newline);
+      pending = pending.subarray(newline + 1);
+      if (line.length > 0 && line[line.length - 1] === 0x0d) line = line.subarray(0, line.length - 1);
+      if (line.length > maxLineBytes) {
+        failReadable(new AcpTransportError("line_too_large", "ACP peer exceeded the inbound line limit."));
+        return;
+      }
+      try {
+        readableController.enqueue(decodeLine(line));
+      } catch (error) {
+        failReadable(error);
+        return;
+      }
+    }
+    if (firstPendingLineIsTooLarge()) {
+      failReadable(new AcpTransportError("line_too_large", "ACP peer exceeded the inbound line limit."));
+      return;
+    }
+    if (finishReadableIfEnded()) return;
+    if (readableController.desiredSize !== null
+      && readableController.desiredSize > 0
+      && pending.indexOf(0x0a) === -1) {
+      input.resume();
+    }
+  };
+  const onData = (chunk) => {
+    if (settled) return;
+    input.pause();
+    const next = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    pending = pending.length === 0 ? next : Buffer.concat([pending, next]);
+    drainPending();
+  };
+  const onEnd = () => {
+    if (settled) return;
+    inputEnded = true;
+    drainPending();
+  };
+  const onError = () => failReadable(new AcpTransportError("transport_failed", "ACP stdout failed."));
+
+  const readable = new ReadableStream({
+    start(controller) {
+      readableController = controller;
+      input.pause();
+      input.on("data", onData);
+      input.once("end", onEnd);
+      input.once("error", onError);
+      drainPending();
+    },
+    pull() {
+      drainPending();
+    },
+    cancel() {
+      if (!settled) {
+        settled = true;
+        cleanupReadable();
+      }
+      input.destroy();
+    },
+  }, { highWaterMark: 1 });
+
+  const writable = new WritableStream({
+    async write(message) {
+      let json;
+      try {
+        json = JSON.stringify(message);
+      } catch {
+        throw new AcpTransportError("invalid_outbound_json", "ACP outbound message is not JSON serializable.");
+      }
+      if (typeof json !== "string" || Buffer.byteLength(json, "utf8") > maxLineBytes) {
+        throw new AcpTransportError("line_too_large", "ACP outbound message exceeded the line limit.");
+      }
+      if (output.destroyed || output.writableEnded) {
+        throw new AcpTransportError("transport_closed", "ACP stdin is closed.");
+      }
+      await new Promise((resolve, reject) => {
+        output.write(`${json}\n`, (error) => error ? reject(error) : resolve(undefined));
+      });
+    },
+    close() {
+      if (!output.destroyed && !output.writableEnded) output.end();
+    },
+    abort() {
+      output.destroy();
+    },
+  });
+
+  return { readable, writable };
+}
+
+export const ACP_DEFAULT_MAX_LINE_BYTES = DEFAULT_MAX_LINE_BYTES;