@mono-agent/agent-runtime 0.18.0 → 0.18.2

package/src/agent/tools/web-search.js

@@ -3,11 +3,49 @@
 import { parseHTML } from "linkedom";
 import { passthroughSandbox } from "../sandbox-seam.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
+import { createCountingSemaphore } from "./shared/semaphore.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const SEARCH_TIMEOUT_MS = 15_000;
 const SEARCH_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 const RRF_K = 60;
+
+// Keyless engines rate-limit by source IP, and one agent can hammer them from
+// many directions at once: a single WebSearch fans out to up to four queries,
+// and every subagent runs its own web controller, so nothing below this module
+// sees the aggregate. Measured against html.duckduckgo.com: ~8 requests in ~4s
+// served normally, ~12 in ~5s tripped an `HTTP 202` anomaly page that persisted
+// for over two minutes. These bounds therefore live at MODULE scope so they
+// apply process-wide (one process is one agent instance), not per run.
+const KEYLESS_DEFAULT_THROTTLE = {
+  // Simultaneous in-flight keyless requests across the whole process.
+  maxConcurrency: 3,
+  // Minimum gap between two requests to the SAME keyless backend, i.e. ~0.67/s
+  // against roughly 2.4/s measured to trip a ban. The asymmetry is deliberate:
+  // being too slow costs a few seconds on a multi-query search, while being too
+  // fast costs a five-minute outage that escalates from a 202 challenge to an
+  // outright 403. Only the fan-out pays it — a single-query search never waits.
+  minSpacingMs: 1_500,
+  // How long a backend stays skipped after it signals rate limiting. Observed
+  // blocks outlasted several minutes, so this is deliberately longer.
+  cooldownMs: 5 * 60_000,
+};
+// Ordered keyless fallback chain. DuckDuckGo first: it yields cleaner titles and
+// snippets, but it is also the one that bans, which is precisely why Startpage
+// behind it has to actually work.
+const KEYLESS_BACKENDS = ["duckduckgo", "startpage"];
+// Markers that identify an interstitial/bot-gate body served with a 2xx status.
+const CHALLENGE_BODY_RE = /anomaly|unusual traffic|captcha|are you a robot|challenge-(?:platform|form)/iu;
+// Statuses these engines use to say "you are sending too much", all of which
+// must put the backend into cooldown rather than be retried next search.
+const RATE_LIMIT_STATUSES = new Set([202, 403, 429]);
+
+let keylessThrottle = { ...KEYLESS_DEFAULT_THROTTLE };
+let keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
+/** @type {Map<string, number>} Backend -> epoch ms until which it is skipped. */
+const backendCooldownUntil = new Map();
+/** @type {Map<string, number>} Backend -> epoch ms its next request may start. */
+const backendNextAvailableAt = new Map();
 const TRACKING_PARAMETERS = new Set([
   "dclid",
   "fbclid",
@@ -96,11 +134,14 @@ export async function performWebSearch(
     );
   };
   const recordResult = (result) => {
+    // Chain failures are reported even when a later backend rescued the query,
+    // so a silent degradation to the fallback is still visible in the outcome.
+    if (result.failures?.length) providerFailures.push(...result.failures);
     if (result.ok) {
       anyProviderSucceeded = true;
       providersUsed.add(result.backend);
       rankedLists.push(filterByDomains(result.results, includeDomains, excludeDomains));
-    } else {
+    } else if (!result.failures?.length) {
       providerFailures.push(result);
     }
   };
@@ -124,16 +165,22 @@ export async function performWebSearch(
   }
 
   if (!anyProviderSucceeded) {
-    const reason = providerFailures.map((entry) => entry.message).filter(Boolean).join("; ")
+    // Four query variants against two backends produce the same handful of
+    // messages over and over; dedupe so the reason stays readable.
+    const reason = [...new Set(providerFailures.map((entry) => entry.message).filter(Boolean))].join("; ")
       || "No search backend was available.";
     const networkDenied = providerFailures.length > 0
       && providerFailures.every((entry) => entry.message === "Network access denied by sandbox policy.");
+    const throttled = providerFailures.some((entry) => entry.rateLimited || entry.cooldown);
     return failure(networkDenied
       ? "Error: Network access denied by sandbox policy."
-      : `Error: WebSearch failed: ${reason}`, networkDenied ? "network_denied" : "backend_unavailable", startedAt, {
+      : `Error: WebSearch failed: ${reason}`,
+    networkDenied ? "network_denied" : (throttled ? "rate_limited" : "backend_unavailable"), startedAt, {
       attempts,
       backend: config.backend,
       retryable: providerFailures.some((entry) => entry.retryable),
+      rateLimited: throttled,
+      cooldownBackends: [...backendCooldownUntil.keys()],
     });
   }
 
@@ -163,48 +210,137 @@ export async function performWebSearch(
       truncated: false,
       resultCount: merged.length,
       providerFailureCount: providerFailures.length,
+      rateLimited: providerFailures.some((entry) => entry.rateLimited || entry.cooldown),
+      cooldownBackends: [...backendCooldownUntil.keys()],
     },
     error: false,
   };
 }
 
+const KEYLESS_RUNNERS = {
+  duckduckgo: searchDuckDuckGo,
+  startpage: searchStartpage,
+};
+
 async function searchOneQuery(query, options) {
   const { config } = options;
+  // Every failure along the chain is kept and carried out on the winning result
+  // too. Reporting only the last one is what made a DuckDuckGo ban surface as
+  // "startpage request failed: fetch failed" and sent diagnosis the wrong way.
   const failures = [];
-  if (options.signal?.aborted) return abortedSearch(config.backend);
+  if (options.signal?.aborted) return abortedSearch(config.backend, failures);
   if (config.backend === "searxng" || (config.backend === "auto" && config.endpoint)) {
     const result = await searchSearxng(query, options);
-    if (result.ok || config.backend === "searxng") return result;
+    if (result.ok || config.backend === "searxng") return { ...result, failures };
     failures.push(result);
-    if (options.signal?.aborted) return abortedSearch(result.backend);
+    if (options.signal?.aborted) return abortedSearch(result.backend, failures);
   }
   if (config.backend === "keyless" || config.backend === "auto") {
-    const duck = await searchDuckDuckGo(query, options);
-    if (duck.ok && duck.results.length > 0) return duck;
-    if (!duck.ok) failures.push(duck);
-    if (options.signal?.aborted) return abortedSearch(duck.backend);
-    const startpage = await searchStartpage(query, options);
-    if (startpage.ok) return startpage;
-    failures.push(startpage);
-    if (duck.ok) return duck;
+    // A genuinely empty 200 is a real answer, not a transport failure — but it
+    // is only worth returning once every backend has had its turn.
+    let emptySuccess = null;
+    for (const backend of KEYLESS_BACKENDS) {
+      if (options.signal?.aborted) return abortedSearch(backend, failures);
+      if (backendInCooldown(backend)) {
+        failures.push({
+          ok: false,
+          backend,
+          message: `${backend} skipped: cooling down after rate limiting.`,
+          retryable: true,
+          cooldown: true,
+        });
+        continue;
+      }
+      const result = await KEYLESS_RUNNERS[backend](query, options);
+      if (result.ok) {
+        if (result.results.length > 0) return { ...result, failures };
+        emptySuccess = result;
+        continue;
+      }
+      // The cooldown is already open — rateLimited() sets it at detection.
+      failures.push(result);
+    }
+    if (emptySuccess) return { ...emptySuccess, failures };
   }
-  return failures[failures.length - 1] || {
-    ok: false,
-    backend: config.backend,
-    message: "No configured search backend.",
-    retryable: false,
+  return {
+    ...(failures[failures.length - 1] || {
+      ok: false,
+      backend: config.backend,
+      message: "No configured search backend.",
+      retryable: false,
+    }),
+    failures,
   };
 }
 
-function abortedSearch(backend) {
+function abortedSearch(backend, failures = []) {
   return {
     ok: false,
     backend,
     message: "WebSearch was aborted.",
     retryable: false,
+    failures,
   };
 }
 
+function backendInCooldown(backend) {
+  const until = backendCooldownUntil.get(backend);
+  if (until === undefined) return false;
+  if (Date.now() >= until) {
+    backendCooldownUntil.delete(backend);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Atomically claims this backend's next send slot and reports how long the
+ * caller must wait for it. Synchronous on purpose: concurrent callers each
+ * reserve a distinct slot instead of all reading the same "last sent at".
+ *
+ * @returns {number} Milliseconds to wait before sending.
+ */
+function reserveKeylessSlot(backend) {
+  const now = Date.now();
+  const earliest = Math.max(now, backendNextAvailableAt.get(backend) ?? 0);
+  backendNextAvailableAt.set(backend, earliest + keylessThrottle.minSpacingMs);
+  return earliest - now;
+}
+
+// Deliberately NOT unref'd: this delay is part of an in-flight search the
+// caller is awaiting. An unref'd timer lets the event loop drain while the
+// search is still pending, and a one-shot CLI turn then exits mid-query.
+// Cancellation is the signal's job, not the timer's.
+function sleep(ms, signal) {
+  if (!ms) return Promise.resolve();
+  return new Promise((resolvePromise, rejectPromise) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      // Named so fetchFailure classifies it alongside every other abort.
+      rejectPromise(Object.assign(new Error("WebSearch was aborted."), { name: "AbortError" }));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.("abort", onAbort);
+      resolvePromise();
+    }, ms);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener?.("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Test hook: restores the shipped throttle values and clears cooldown/spacing
+ * state. Module-scoped state would otherwise leak between test cases.
+ *
+ * @param {{maxConcurrency?: number, minSpacingMs?: number, cooldownMs?: number}} [overrides]
+ */
+export function __resetWebSearchThrottleForTests(overrides = {}) {
+  keylessThrottle = { ...KEYLESS_DEFAULT_THROTTLE, ...overrides };
+  keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
+  backendCooldownUntil.clear();
+  backendNextAvailableAt.clear();
+}
+
 async function searchSearxng(query, options) {
   const endpoint = options.config.endpoint;
   if (!endpoint) {
@@ -255,66 +391,143 @@ async function searchSearxng(query, options) {
   }
 }
 
-async function searchDuckDuckGo(query, options) {
-  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
-  if (!options.sandbox.networkAllowsUrl(options.policy, url)) {
-    return { ok: false, backend: "duckduckgo", message: "Network access denied by sandbox policy.", retryable: false };
+/**
+ * Shared transport for the keyless HTML engines. Both are scraped the same way
+ * and both bot-gate the same way, so request shaping, throttling, challenge
+ * detection, and error classification live here exactly once.
+ *
+ * @param {{backend: string, label: string, url: string, init?: RequestInit, parse: (html: string) => any[]}} spec
+ */
+async function keylessHtmlSearch(spec, options) {
+  if (!options.sandbox.networkAllowsUrl(options.policy, spec.url)) {
+    return { ok: false, backend: spec.backend, message: "Network access denied by sandbox policy.", retryable: false };
   }
+  let release;
   try {
-    const response = await options.fetchImpl(url, {
-      headers: {
-        Accept: "text/html,application/xhtml+xml",
-        "Accept-Language": options.language || "en-US,en;q=0.8",
-        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) mono-agent-web/1",
-      },
-      signal: requestSignal(options.signal),
-      redirect: "error",
-    });
-    const html = await readLimitedText(response);
-    if (!response.ok) {
+    release = await keylessSemaphore.acquire(options.signal);
+  } catch {
+    // Queued behind the concurrency bound when the turn was cancelled.
+    return { ok: false, backend: spec.backend, message: "WebSearch was aborted.", retryable: false };
+  }
+  try {
+    const waitMs = reserveKeylessSlot(spec.backend);
+    if (waitMs > 0) await sleep(waitMs, options.signal);
+    // Query variants all clear the cooldown check together and then queue here,
+    // so by the time this one is admitted a sibling may already have been
+    // blocked. Without this second look the very first block still costs a full
+    // round of requests against a backend we know is refusing them.
+    if (backendInCooldown(spec.backend)) {
       return {
         ok: false,
-        backend: "duckduckgo",
-        message: `DuckDuckGo HTTP ${response.status}`,
-        retryable: response.status === 429 || response.status >= 500,
+        backend: spec.backend,
+        message: `${spec.backend} skipped: cooling down after rate limiting.`,
+        retryable: true,
+        cooldown: true,
       };
     }
-    return { ok: true, backend: "duckduckgo", results: parseDuckDuckGoResults(html) };
-  } catch (error) {
-    return fetchFailure("duckduckgo", error);
-  }
-}
-
-async function searchStartpage(query, options) {
-  const url = `https://www.startpage.com/sp/search?query=${encodeURIComponent(query)}`;
-  if (!options.sandbox.networkAllowsUrl(options.policy, url)) {
-    return { ok: false, backend: "startpage", message: "Network access denied by sandbox policy.", retryable: false };
-  }
-  try {
-    const response = await options.fetchImpl(url, {
+    const response = await options.fetchImpl(spec.url, {
+      // "manual", not "error": these engines answer a throttled query with a
+      // redirect to a captcha page, and "error" collapses that into an opaque
+      // `TypeError: fetch failed` with no way to tell it from a real outage.
+      // The redirect is still never followed, so the open-redirect guard holds.
+      redirect: "manual",
+      ...(spec.init || {}),
+      // Headers are merged last on purpose: spreading `spec.init` afterwards
+      // would replace the whole headers object with the backend's few extra
+      // entries, and a Startpage POST without a User-Agent gets bot-gated.
       headers: {
         Accept: "text/html,application/xhtml+xml",
         "Accept-Language": options.language || "en-US,en;q=0.8",
         "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) mono-agent-web/1",
+        ...(spec.init?.headers || {}),
       },
       signal: requestSignal(options.signal),
-      redirect: "error",
     });
     const html = await readLimitedText(response);
+    // Startpage answers a blocked source IP with `303 -> /sp/captcha-block`.
+    // The destination is the block itself, never results, so following it only
+    // costs a round trip and still parses to nothing.
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location") || "";
+      return rateLimited(spec, /captcha|blocked|sorry|challenge/iu.test(location)
+        ? "captcha redirect"
+        : `HTTP ${response.status} redirect`);
+    }
+    // 202 is DuckDuckGo's soft challenge (and is `ok`, so status alone would let
+    // an interstitial through as an empty success); 403 is what it escalates to
+    // once it stops asking politely. No credentials are ever sent to these
+    // endpoints, so a 403 can only mean "blocked", never "unauthorized".
+    if (RATE_LIMIT_STATUSES.has(response.status)) {
+      return rateLimited(spec, `HTTP ${response.status}`);
+    }
     if (!response.ok) {
       return {
         ok: false,
-        backend: "startpage",
-        message: `Startpage HTTP ${response.status}`,
-        retryable: response.status === 429 || response.status >= 500,
+        backend: spec.backend,
+        message: `${spec.label} HTTP ${response.status}`,
+        retryable: response.status >= 500,
       };
     }
-    return { ok: true, backend: "startpage", results: parseStartpageResults(html) };
+    const results = spec.parse(html);
+    // A 200 that parses to nothing is ambiguous: either a genuinely empty
+    // result set or a bot gate. Only the body markers tell them apart, and
+    // conflating them is what made a ban look like "No results."
+    if (results.length === 0 && CHALLENGE_BODY_RE.test(html)) {
+      return rateLimited(spec, "interstitial challenge page");
+    }
+    return { ok: true, backend: spec.backend, results };
   } catch (error) {
-    return fetchFailure("startpage", error);
+    return fetchFailure(spec.backend, error, spec.label);
+  } finally {
+    release();
   }
 }
 
+function searchDuckDuckGo(query, options) {
+  return keylessHtmlSearch({
+    backend: "duckduckgo",
+    label: "DuckDuckGo",
+    url: `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
+    parse: parseDuckDuckGoResults,
+  }, options);
+}
+
+function searchStartpage(query, options) {
+  // Startpage serves its results from a form POST. The old query-string GET was
+  // answered with a 3xx, which `redirect: "error"` turned into a bare
+  // `TypeError: fetch failed` — so this backend never once returned a result,
+  // and its useless error was the only thing the operator ever saw.
+  const body = new URLSearchParams({ query, cat: "web" });
+  const withDate = { day: "d", month: "m", year: "y" }[options.timeRange];
+  if (withDate) body.set("with_date", withDate);
+  return keylessHtmlSearch({
+    backend: "startpage",
+    label: "Startpage",
+    url: "https://www.startpage.com/sp/search",
+    init: {
+      method: "POST",
+      body,
+      headers: { "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8" },
+    },
+    parse: parseStartpageResults,
+  }, options);
+}
+
+// Opens the cooldown at the moment of detection rather than letting the caller
+// do it. The semaphore slot is released before this result reaches the caller,
+// so a queued sibling would otherwise be admitted and re-check the cooldown
+// while it was still closed, and every variant in flight would hit the wire.
+function rateLimited(spec, detail) {
+  backendCooldownUntil.set(spec.backend, Date.now() + keylessThrottle.cooldownMs);
+  return {
+    ok: false,
+    backend: spec.backend,
+    message: `${spec.label} rate-limited (${detail})`,
+    retryable: true,
+    rateLimited: true,
+  };
+}
+
 export function parseDuckDuckGoResults(html) {
   const { document } = parseHTML(String(html || ""));
   const rows = [...document.querySelectorAll(".result")];
@@ -334,6 +547,10 @@ export function parseDuckDuckGoResults(html) {
 
 export function parseStartpageResults(html) {
   const { document } = parseHTML(String(html || ""));
+  // Startpage inlines emotion CSS in <style> tags nested inside the result
+  // anchors, and textContent happily returns the stylesheet as part of the
+  // title (".css-i3irj7{line-height:18px;...}Best time to visit Japan").
+  for (const node of document.querySelectorAll("style, script")) node.remove();
   const selectors = [".w-gl__result", ".result", "article"];
   const rows = selectors.flatMap((selector) => [...document.querySelectorAll(selector)]);
   const seen = new Set();
@@ -541,15 +758,34 @@ async function readLimitedText(response) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-function fetchFailure(backend, error) {
+// undici reports transport problems as a bare `TypeError: fetch failed` and
+// keeps the real reason on `error.cause` — dropping it is what left an
+// "unexpected redirect" looking like an unexplained network fault.
+const RETRYABLE_FETCH_CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "ENOTFOUND",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+
+function fetchFailure(backend, error, label = backend) {
   const name = error?.name;
   const retryable = name === "AbortError"
     || name === "TimeoutError"
-    || ["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EAI_AGAIN"].includes(error?.code ?? error?.cause?.code);
+    || RETRYABLE_FETCH_CODES.has(error?.code ?? error?.cause?.code);
+  const message = error?.message || String(error);
+  const cause = error?.cause?.message;
+  const detail = cause && cause !== message ? `${message} (${cause})` : message;
   return {
     ok: false,
     backend,
-    message: `${backend} request failed: ${error?.message || String(error)}`,
+    message: `${label} request failed: ${detail}`,
     retryable,
   };
 }

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

@@ -8,6 +8,7 @@ import { passthroughSandbox } from "../../agent/sandbox-seam.js";
 import {
   ACP_DEFAULT_MAX_LINE_BYTES,
   AcpTransportError,
+  connectWithSafeAcpSdkDiagnostics,
   createBoundedAcpStdioStream,
   normalizeAcpMaxLineBytes,
 } from "./acp-transport.js";
@@ -20,10 +21,12 @@ import {
   encodeAcpSessionCursor,
   validateAcpProfileId,
   validateAcpProviderSessionId,
+  validateAcpSessionTokenKey,
 } from "./acp-session-tokens.js";
 
 const OWNERS = new Set(["client", "agent"]);
 const RESUME_STRATEGIES = new Set(["auto", "load", "resume"]);
+const TOKEN_FREE_OPERATIONS = new Set(["probe", "authenticate", "logout"]);
 const DEFAULT_PROCESS_POLICY = Object.freeze({
   startupTimeoutMs: 10_000,
   requestTimeoutMs: 60_000,
@@ -135,6 +138,7 @@ const DEFAULT_PROCESS_POLICY = Object.freeze({
  * @property {string} [cwd]
  * @property {AbortSignal} [signal]
  * @property {Record<string, unknown>} [context]
+ * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key required by operations that emit or consume opaque session handles.
  */
 
 export {
@@ -527,6 +531,9 @@ export async function connectAcpProfile(profileId, options) {
   validateAcpProfileId(profileId);
   throwIfAborted(options?.signal);
   const operation = options?.operation || "connect";
+  const sessionTokenKey = TOKEN_FREE_OPERATIONS.has(operation)
+    ? undefined
+    : validateAcpSessionTokenKey(options?.acpSessionTokenKey);
   const descriptor = await resolveProfile(profileId, { ...options, operation });
   throwIfAborted(options?.signal);
   const capabilities = clientCapabilities(descriptor);
@@ -575,7 +582,13 @@ export async function connectAcpProfile(profileId, options) {
   const safeCallbackContext = (context, rawSessionId) => ({
     ...context,
     ...(typeof rawSessionId === "string"
-      ? { providerSessionId: encodeAcpProviderSessionId(profileId, rawSessionId) }
+      ? {
+          providerSessionId: encodeAcpProviderSessionId(
+            profileId,
+            rawSessionId,
+            /** @type {Uint8Array} */ (sessionTokenKey),
+          ),
+        }
       : {}),
     ...(context.requestId === undefined
       ? {}
@@ -696,9 +709,11 @@ export async function connectAcpProfile(profileId, options) {
 
   let connection;
   try {
-    connection = app.connect(createBoundedAcpStdioStream(child, {
-      maxLineBytes: descriptor.process.maxLineBytes,
-    }));
+    connection = connectWithSafeAcpSdkDiagnostics(() => app.connect(
+      createBoundedAcpStdioStream(child, {
+        maxLineBytes: descriptor.process.maxLineBytes,
+      }),
+    ));
   } catch (error) {
     child.kill("SIGTERM");
     const exited = await waitForExit(exitPromise, descriptor.process.killGraceMs);
@@ -1010,15 +1025,15 @@ function validateMcpServers(servers, descriptor, initializeResult) {
   });
 }
 
-/** @param {string} profileId @param {any} request */
-function protocolSessionListRequest(profileId, request) {
+/** @param {string} profileId @param {any} request @param {Uint8Array} key */
+function protocolSessionListRequest(profileId, request, key) {
   if (!request || typeof request !== "object" || Array.isArray(request)) {
     throw new AcpClientError("invalid_request", "ACP session/list request must be an object.");
   }
   const { cursor, _meta: _meta, ...rest } = request;
   return {
     ...rest,
-    ...(cursor == null ? {} : { cursor: decodeAcpSessionCursor(profileId, cursor) }),
+    ...(cursor == null ? {} : { cursor: decodeAcpSessionCursor(profileId, cursor, key) }),
   };
 }
 
@@ -1090,18 +1105,23 @@ export async function logoutAcpProfile(profileId, options) {
  * @returns {Promise<AcpSessionListResult>}
  */
 export async function listAcpSessions(profileId, request = {}, options = /** @type {any} */ ({})) {
-  const protocolRequest = protocolSessionListRequest(profileId, request);
-  const connection = await connectAcpProfile(profileId, { ...options, operation: "list_sessions" });
+  const key = validateAcpSessionTokenKey(options?.acpSessionTokenKey);
+  const protocolRequest = protocolSessionListRequest(profileId, request, key);
+  const connection = await connectAcpProfile(profileId, {
+    ...options,
+    operation: "list_sessions",
+    acpSessionTokenKey: key,
+  });
   try {
     const result = await connection.listSessions(protocolRequest);
     return {
       profileId,
       sessions: (result.sessions || []).map((session) => ({
         ...sanitizeAcpHostValue(session, [session.sessionId, result.nextCursor]),
-        providerSessionId: encodeAcpProviderSessionId(profileId, session.sessionId),
+        providerSessionId: encodeAcpProviderSessionId(profileId, session.sessionId, key),
       })),
       nextCursor: typeof result.nextCursor === "string"
-        ? encodeAcpSessionCursor(profileId, result.nextCursor)
+        ? encodeAcpSessionCursor(profileId, result.nextCursor, key)
         : null,
     };
   } finally {
@@ -1111,8 +1131,13 @@ export async function listAcpSessions(profileId, request = {}, options = /** @ty
 
 /** @param {string} providerSessionId @param {AcpClientHostOptions} options */
 export async function deleteAcpSession(providerSessionId, options) {
-  const { profileId, sessionId } = decodeAcpProviderSessionId(providerSessionId);
-  const connection = await connectAcpProfile(profileId, { ...options, operation: "delete_session" });
+  const key = validateAcpSessionTokenKey(options?.acpSessionTokenKey);
+  const { profileId, sessionId } = decodeAcpProviderSessionId(providerSessionId, key);
+  const connection = await connectAcpProfile(profileId, {
+    ...options,
+    operation: "delete_session",
+    acpSessionTokenKey: key,
+  });
   try {
     await connection.deleteSession(sessionId);
     return { profileId, providerSessionId, deleted: true };