@mono-agent/agent-runtime 0.20.14 → 0.21.1

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

@@ -0,0 +1,65 @@
+// @ts-check
+
+/** One deadline covers admission, backend startup, I/O, and retries. */
+export async function withWebDeadline(signal, milliseconds, execute) {
+  const controller = new AbortController();
+  const abort = () => controller.abort(signal.reason);
+  if (signal?.aborted) abort();
+  else signal?.addEventListener("abort", abort, { once: true });
+  const timer = setTimeout(() => controller.abort(Object.assign(new Error("Web request deadline exceeded."), { code: "deadline_exceeded" })), milliseconds);
+  try { return await execute(controller.signal); }
+  finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }
+}
+
+export async function coordinatedWebRequest(coordinator, kind, key, signal, execute, classify = classifySearch) {
+  signal?.throwIfAborted();
+  const permit = coordinator ? await coordinator.acquire({ kind, key, signal, deadlineMs: Date.now() + (kind === "fetch" ? 45_000 : 60_000) }) : undefined;
+  const started = Date.now();
+  try {
+    signal?.throwIfAborted();
+    const value = await execute();
+    const completion = await permit?.complete(signal?.aborted ? { status: "cancelled" } : classify(value));
+    const persistedCooldown = value?.rateLimited ? completion : undefined;
+    return {
+      ...value,
+      ...(Number.isFinite(persistedCooldown?.retryAfterMs) ? { retryAfterMs: persistedCooldown.retryAfterMs } : {}),
+      ...(Number.isFinite(persistedCooldown?.retryAtMs) ? { retryAtMs: persistedCooldown.retryAtMs } : {}),
+      coordinationWaitMs: permit?.waitMs ?? 0,
+      backendDurationMs: Date.now() - started,
+    };
+  } catch (error) {
+    // A run-local budget refusal happens after admission but before a provider
+    // request. Release the lease without teaching the shared host coordinator
+    // that the provider failed.
+    await permit?.complete({
+      status: signal?.aborted || error?.code === "search_budget_exhausted"
+        ? "cancelled"
+        : "unavailable",
+    });
+    throw error;
+  }
+}
+
+function classifySearch(result) {
+  return {
+    status: result.rateLimited ? "rate_limited" : result.ok ? "ok" : result.retryable ? "unavailable" : "cancelled",
+    ...(result.retryAfterMs === undefined ? {} : { retryAfterMs: result.retryAfterMs }),
+    ...(result.retryAtMs === undefined ? {} : { retryAtMs: result.retryAtMs }),
+  };
+}
+
+export function webRequestFailure(error, backend, signal) {
+  const code = signal?.aborted ? (signal.reason?.code === "deadline_exceeded" ? "deadline_exceeded" : "aborted") : error?.code;
+  return {
+    ok: false, backend, code: code || "backend_unavailable",
+    message: code === "coordination_unavailable" ? "Web request coordination is unavailable."
+      : code === "rate_limited" ? `${backend} is cooling down.`
+        : code === "search_budget_exhausted" ? "WebSearch request budget exhausted for this run."
+        : code === "deadline_exceeded" ? "Web request deadline exceeded."
+          : code === "aborted" ? "Web request was aborted." : `${backend} request unavailable.`,
+    retryable: !["aborted", "search_budget_exhausted"].includes(code),
+    cooldown: code === "rate_limited", rateLimited: code === "rate_limited",
+    retryAfterMs: error?.retryAfterMs,
+    retryAtMs: error?.retryAtMs,
+  };
+}

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

@@ -0,0 +1,165 @@
+// @ts-check
+
+export const WEB_SEARCH_TITLE_MAX_CHARS = 500;
+export const WEB_SEARCH_SNIPPET_MAX_CHARS = 4_000;
+export const WEB_SEARCH_BODY_MAX_BYTES = 64 * 1024;
+export const WEB_SEARCH_SNIPPET_TRUNCATION_MARKER = "[snippet truncated; use WebFetch for full source]";
+
+const RESULT_OMISSION_MARKER = "[additional search results omitted by WebSearch output bound]";
+
+/** @param {unknown} value */
+function collapseWhitespace(value) {
+  return toWellFormedText(value).replace(/\s+/gu, " ").trim();
+}
+
+/** Replace isolated UTF-16 surrogates while preserving valid astral pairs. @param {unknown} value */
+export function toWellFormedText(value) {
+  let out = "";
+  for (const point of String(value || "")) {
+    const unit = point.charCodeAt(0);
+    out += point.length === 1 && unit >= 0xd800 && unit <= 0xdfff ? "\uFFFD" : point;
+  }
+  return out;
+}
+
+/** @param {unknown} value @param {number} maxChars */
+export function sliceWellFormedCodePoints(value, maxChars) {
+  return [...toWellFormedText(value)].slice(0, Math.max(0, maxChars)).join("");
+}
+
+/** @param {string} value @param {number} maxBytes */
+export function sliceUtf8(value, maxBytes) {
+  const budget = Math.max(0, Math.floor(maxBytes));
+  const text = toWellFormedText(value);
+  if (Buffer.byteLength(text, "utf8") <= budget) return text;
+  let used = 0;
+  let out = "";
+  for (const point of text) {
+    const bytes = Buffer.byteLength(point, "utf8");
+    if (used + bytes > budget) break;
+    out += point;
+    used += bytes;
+  }
+  return out;
+}
+
+/** @param {unknown} value @param {number} [maxChars] */
+export function boundWebSearchSnippet(value, maxChars = WEB_SEARCH_SNIPPET_MAX_CHARS) {
+  const text = collapseWhitespace(value);
+  if ([...text].length <= maxChars) return { text, truncated: false };
+  const markerChars = [...WEB_SEARCH_SNIPPET_TRUNCATION_MARKER].length;
+  const prefixChars = Math.max(0, maxChars - markerChars - 1);
+  const prefix = sliceWellFormedCodePoints(text, prefixChars).trimEnd();
+  return {
+    text: `${prefix}${prefix ? " " : ""}${WEB_SEARCH_SNIPPET_TRUNCATION_MARKER}`,
+    truncated: true,
+  };
+}
+
+/** @param {unknown} value */
+function boundTitle(value) {
+  const text = collapseWhitespace(value);
+  if ([...text].length <= WEB_SEARCH_TITLE_MAX_CHARS) return { text, truncated: false };
+  return {
+    text: `${sliceWellFormedCodePoints(text, WEB_SEARCH_TITLE_MAX_CHARS - 1).trimEnd()}…`,
+    truncated: true,
+  };
+}
+
+/** @param {unknown} value */
+function escapeMarkdownLabel(value) {
+  return collapseWhitespace(value).replace(/[[\]\\]/gu, "\\$&");
+}
+
+/**
+ * @param {string} value
+ * @param {number} maxBytes
+ */
+function truncateSnippetToBytes(value, maxBytes) {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  const markerBytes = Buffer.byteLength(WEB_SEARCH_SNIPPET_TRUNCATION_MARKER, "utf8");
+  if (maxBytes <= markerBytes) return sliceUtf8(WEB_SEARCH_SNIPPET_TRUNCATION_MARKER, maxBytes);
+  const source = value.endsWith(WEB_SEARCH_SNIPPET_TRUNCATION_MARKER)
+    ? value.slice(0, -WEB_SEARCH_SNIPPET_TRUNCATION_MARKER.length).trimEnd()
+    : value;
+  const prefix = sliceUtf8(source, Math.max(0, maxBytes - markerBytes - 1)).trimEnd();
+  return `${prefix}${prefix ? " " : ""}${WEB_SEARCH_SNIPPET_TRUNCATION_MARKER}`;
+}
+
+/**
+ * @param {Array<{title?: unknown, url?: unknown, snippet?: unknown, snippetTruncated?: boolean}>} results
+ * @param {{maxBytes?: number}} [options]
+ */
+export function renderBoundedWebSearchBody(results, { maxBytes = WEB_SEARCH_BODY_MAX_BYTES } = {}) {
+  const normalized = results.map((result, index) => {
+    const url = String(result?.url || "");
+    const title = boundTitle(result?.title || url);
+    const snippet = boundWebSearchSnippet(result?.snippet);
+    const snippetTruncated = result?.snippetTruncated === true || snippet.truncated;
+    const text = snippetTruncated && !snippet.text.endsWith(WEB_SEARCH_SNIPPET_TRUNCATION_MARKER)
+      ? boundWebSearchSnippet(`${snippet.text} ${WEB_SEARCH_SNIPPET_TRUNCATION_MARKER}`).text
+      : snippet.text;
+    return {
+      core: `${index + 1}. [${escapeMarkdownLabel(title.text || url)}](${url})`,
+      snippet: text,
+      truncated: title.truncated || snippetTruncated,
+    };
+  });
+
+  if (normalized.length === 0) {
+    return { body: "No results.", renderedResultCount: 0, truncated: false };
+  }
+
+  let selected = normalized.slice();
+  let omittedResults = 0;
+  const omissionBody = () => omittedResults > 0
+    ? `${RESULT_OMISSION_MARKER} (${omittedResults})`
+    : "";
+  const minimumSnippet = (entry) => entry.snippet
+    ? `\n   ${WEB_SEARCH_SNIPPET_TRUNCATION_MARKER}`
+    : "";
+  const minimumBody = () => [
+    ...selected.map((entry) => `${entry.core}${minimumSnippet(entry)}`),
+    ...(omittedResults > 0 ? [omissionBody()] : []),
+  ].join("\n\n");
+
+  while (selected.length > 0 && Buffer.byteLength(minimumBody(), "utf8") > maxBytes) {
+    selected.pop();
+    omittedResults += 1;
+  }
+  if (selected.length === 0) {
+    return {
+      body: sliceUtf8(omissionBody() || RESULT_OMISSION_MARKER, maxBytes),
+      renderedResultCount: 0,
+      truncated: true,
+    };
+  }
+
+  const minimum = minimumBody();
+  let remaining = Math.max(0, maxBytes - Buffer.byteLength(minimum, "utf8"));
+  let truncated = omittedResults > 0 || selected.some((entry) => entry.truncated);
+  const rendered = [];
+  for (const entry of selected) {
+    if (!entry.snippet) {
+      rendered.push(entry.core);
+      continue;
+    }
+    const prefix = "\n   ";
+    const minimumTextBytes = Buffer.byteLength(WEB_SEARCH_SNIPPET_TRUNCATION_MARKER, "utf8");
+    const desiredBytes = Buffer.byteLength(entry.snippet, "utf8");
+    const extraNeeded = Math.max(0, desiredBytes - minimumTextBytes);
+    const granted = Math.min(remaining, extraNeeded);
+    remaining -= granted;
+    const snippetBudget = minimumTextBytes + granted;
+    const snippet = truncateSnippetToBytes(entry.snippet, snippetBudget);
+    if (snippet !== entry.snippet) truncated = true;
+    rendered.push(`${entry.core}${prefix}${snippet}`);
+  }
+  if (omittedResults > 0) rendered.push(omissionBody());
+  const body = rendered.join("\n\n");
+  return {
+    body,
+    renderedResultCount: selected.length,
+    truncated,
+  };
+}

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

@@ -0,0 +1,75 @@
+// @ts-check
+
+export const DEFAULT_WEB_SEARCH_MAX_REQUESTS_PER_RUN = 4;
+export const MAX_WEB_SEARCH_REQUESTS_PER_RUN = 20;
+
+/**
+ * Private mutable state shared by every WebSearch controller created for one
+ * logical runtime run. Router retries receive the same object, while child and
+ * later runs receive a fresh one.
+ *
+ * @param {any} searchConfig
+ * @param {any} [existing]
+ */
+export function createWebSearchRunState(searchConfig, existing) {
+  if (isWebSearchRunState(existing)) return existing;
+  const configured = searchConfig?.maxRequestsPerRun;
+  const maxRequests = Number.isSafeInteger(configured)
+    && configured >= 1
+    && configured <= MAX_WEB_SEARCH_REQUESTS_PER_RUN
+    ? configured
+    : DEFAULT_WEB_SEARCH_MAX_REQUESTS_PER_RUN;
+  return {
+    schema: "mono-agent.web-search-run.v1",
+    maxRequests,
+    requestsUsed: 0,
+    deferredProviders: new Map(),
+  };
+}
+
+/** Claim one actual provider dispatch synchronously. */
+export function claimWebSearchRequest(state, backend, callClaims) {
+  if (!isWebSearchRunState(state)) throw new Error("Invalid WebSearch run state.");
+  if (state.requestsUsed >= state.maxRequests) {
+    throw Object.assign(new Error("WebSearch request budget exhausted for this run."), {
+      code: "search_budget_exhausted",
+      backend,
+    });
+  }
+  state.requestsUsed += 1;
+  if (callClaims && Number.isSafeInteger(callClaims.requests)) callClaims.requests += 1;
+}
+
+export function webSearchBudgetSnapshot(state, requestsThisCall = 0) {
+  const resolved = createWebSearchRunState(undefined, state);
+  return {
+    requestsThisCall,
+    maxRequestsPerRun: resolved.maxRequests,
+    requestsUsed: resolved.requestsUsed,
+    requestsRemaining: Math.max(0, resolved.maxRequests - resolved.requestsUsed),
+  };
+}
+
+export function deferWebSearchProvider(state, backend, retryAtMs) {
+  if (!isWebSearchRunState(state)) return;
+  const current = state.deferredProviders.get(backend);
+  const next = Number.isFinite(retryAtMs) ? retryAtMs : undefined;
+  if (current === undefined || (next !== undefined && (current.retryAtMs === undefined || next > current.retryAtMs))) {
+    state.deferredProviders.set(backend, { retryAtMs: next });
+  }
+}
+
+export function deferredWebSearchProvider(state, backend) {
+  return isWebSearchRunState(state) ? state.deferredProviders.get(backend) : undefined;
+}
+
+function isWebSearchRunState(value) {
+  return value?.schema === "mono-agent.web-search-run.v1"
+    && Number.isSafeInteger(value.maxRequests)
+    && value.maxRequests >= 1
+    && value.maxRequests <= MAX_WEB_SEARCH_REQUESTS_PER_RUN
+    && Number.isSafeInteger(value.requestsUsed)
+    && value.requestsUsed >= 0
+    && value.requestsUsed <= value.maxRequests
+    && value.deferredProviders instanceof Map;
+}