@opengeni/runtime 3.3.0 → 3.4.0

package/src/browser-current-tab.ts

@@ -0,0 +1,139 @@
+// The browser tab an agent is working in.
+//
+// Browser tools may omit browserSessionId and targetId to keep working in the
+// tab the agent used last, the way a person keeps using the tab in front of
+// them. A step then costs a few output tokens instead of two identifiers, and
+// output tokens dominate a browser step's model latency. The remembered tab
+// lives for one turn attempt; a call that omits identifiers before any browser
+// call in that attempt resolves this session's most recently used live
+// browser and its selected tab.
+
+export class BrowserTargetResolutionError extends Error {
+  constructor(
+    readonly code: "browser_session_required" | "browser_target_required",
+    message: string,
+  ) {
+    super(message);
+    this.name = "BrowserTargetResolutionError";
+  }
+}
+
+export type CurrentBrowserTabDeps = {
+  /** This agent session's live BrowserSessions. */
+  listLiveSessions: () => Promise<ReadonlyArray<{ id: string; lastUsedAt: string }>>;
+  /** The tabs of one BrowserSession. */
+  listTargets: (
+    browserSessionId: string,
+  ) => Promise<ReadonlyArray<{ id: string; kind: string; selected: boolean }>>;
+};
+
+export type ResolvedBrowserSession = {
+  browserSessionId: string;
+  /** True when the identifier came from memory or lookup, not the caller. */
+  implicit: boolean;
+};
+
+export type ResolvedBrowserTarget = ResolvedBrowserSession & {
+  targetId: string;
+  implicitTarget: boolean;
+};
+
+export class CurrentBrowserTab {
+  private current: { browserSessionId: string; targetId: string | null } | null = null;
+
+  constructor(private readonly deps: CurrentBrowserTabDeps) {}
+
+  /** Record the session and, when known, the tab a successful call used. */
+  use(browserSessionId: string, targetId?: string | null): void {
+    if (targetId === undefined) {
+      if (this.current?.browserSessionId !== browserSessionId) {
+        this.current = { browserSessionId, targetId: null };
+      }
+      return;
+    }
+    this.current = { browserSessionId, targetId };
+  }
+
+  forgetTarget(browserSessionId: string, targetId: string): void {
+    if (this.current?.browserSessionId === browserSessionId && this.current.targetId === targetId) {
+      this.current = { browserSessionId, targetId: null };
+    }
+  }
+
+  forgetSession(browserSessionId: string): void {
+    if (this.current?.browserSessionId === browserSessionId) this.current = null;
+  }
+
+  /** A call that relied on remembered identifiers failed: resolve afresh next time. */
+  failed(resolved: ResolvedBrowserSession & { implicitTarget?: boolean }): void {
+    if (resolved.implicit) this.forgetSession(resolved.browserSessionId);
+    else if (
+      resolved.implicitTarget &&
+      this.current?.browserSessionId === resolved.browserSessionId
+    ) {
+      this.current = { browserSessionId: resolved.browserSessionId, targetId: null };
+    }
+  }
+
+  async session(browserSessionId: string | undefined): Promise<ResolvedBrowserSession> {
+    if (browserSessionId !== undefined) return { browserSessionId, implicit: false };
+    if (this.current) return { browserSessionId: this.current.browserSessionId, implicit: true };
+    const sessions = [...(await this.deps.listLiveSessions())].sort((left, right) =>
+      right.lastUsedAt.localeCompare(left.lastUsedAt),
+    );
+    const latest = sessions[0];
+    if (!latest) {
+      throw new BrowserTargetResolutionError(
+        "browser_session_required",
+        "This session has no open browser. Call browser_open first, or pass browserSessionId.",
+      );
+    }
+    return { browserSessionId: latest.id, implicit: true };
+  }
+
+  async target(value: {
+    browserSessionId?: string | undefined;
+    targetId?: string | undefined;
+  }): Promise<ResolvedBrowserTarget> {
+    const session = await this.session(value.browserSessionId);
+    if (value.targetId !== undefined) {
+      return { ...session, targetId: value.targetId, implicitTarget: false };
+    }
+    if (this.current?.browserSessionId === session.browserSessionId && this.current.targetId) {
+      return { ...session, targetId: this.current.targetId, implicitTarget: true };
+    }
+    const pages = (await this.deps.listTargets(session.browserSessionId)).filter(
+      (target) => target.kind === "page" || target.kind === "popup",
+    );
+    const chosen =
+      pages.find((target) => target.selected) ?? (pages.length === 1 ? pages[0] : null);
+    if (!chosen) {
+      throw new BrowserTargetResolutionError(
+        "browser_target_required",
+        pages.length === 0
+          ? "This browser has no open tab. Open one with browser_tabs operation=open."
+          : `This browser has ${pages.length} tabs and none is selected. Pass targetId from browser_tabs operation=list.`,
+      );
+    }
+    return { ...session, targetId: chosen.id, implicitTarget: true };
+  }
+}
+
+/** An element ref passed where a locator is expected, as a bare string. */
+export function expandRefShorthand(action: unknown): unknown {
+  if (!action || typeof action !== "object" || Array.isArray(action)) return action;
+  const record = action as Record<string, unknown>;
+  let expanded: Record<string, unknown> | null = null;
+  for (const field of ["locator", "from", "to"] as const) {
+    const value = record[field];
+    if (typeof value === "string") {
+      expanded ??= { ...record };
+      expanded[field] = { kind: "ref", ref: value };
+    }
+  }
+  if (Array.isArray(record.actions)) {
+    expanded ??= { ...record };
+    expanded.actions = record.actions.map(expandRefShorthand);
+  }
+  return expanded ?? action;
+}

package/src/browser-model-text.ts

@@ -0,0 +1,378 @@
+/**
+ * The model's text view of browser tool results.
+ *
+ * A browser tool result keeps its complete typed value in `structuredContent`
+ * for Code Mode, the API and the UI. What the model reads is this text: an
+ * outline with one line per page element, in the role/name vocabulary that
+ * locators use. It repeats no envelope keys, quoting or bookkeeping ids the
+ * model never sends back, which makes a page view about half the tokens of
+ * the same value as JSON.
+ */
+
+export type BrowserTextNode = {
+  ref: string;
+  role: string;
+  depth: number;
+  name?: string | undefined;
+  description?: string | undefined;
+  value?: string | { redacted: true; reason: string } | undefined;
+  states?: readonly string[] | undefined;
+  actions?: readonly string[] | undefined;
+};
+
+export type BrowserTextTarget = {
+  id: string;
+  kind: string;
+  title: string;
+  url: string;
+  selected?: boolean | undefined;
+};
+
+export type BrowserTextObservation = {
+  target: BrowserTextTarget;
+  viewport?:
+    | {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number | undefined;
+        maxTouchPoints?: number | undefined;
+      }
+    | null
+    | undefined;
+  focusedRef?: string | null | undefined;
+  changedRegions?: readonly unknown[] | undefined;
+  diagnostics?:
+    | {
+        consoleErrorCount: number;
+        failedRequestCount: number;
+        downloadCount: number;
+        pageErrorCount: number;
+      }
+    | null
+    | undefined;
+  dialog?: { type: string; message: string; defaultPrompt?: string | undefined } | null | undefined;
+  screenshot?: unknown;
+  agentView: {
+    sourceKind: string;
+    nodes: readonly BrowserTextNode[];
+    omittedNodeCount?: number | undefined;
+    removedRefCount?: number | undefined;
+    clippedFieldCount?: number | undefined;
+  };
+};
+
+/** Text, structure and table-layout roles. Locate these by text or role and
+ * name; listing their refs would cost every page view several tokens per line
+ * for nodes that are almost never acted on. A complete view, a focused read,
+ * and any node that reports actions still show every ref. */
+const REFLESS_ROLES: ReadonlySet<string> = new Set([
+  "article",
+  "banner",
+  "blockquote",
+  "caption",
+  "cell",
+  "code",
+  "columnheader",
+  "complementary",
+  "contentinfo",
+  "definition",
+  "deletion",
+  "document",
+  "emphasis",
+  "figure",
+  "form",
+  "generic",
+  "group",
+  "heading",
+  "insertion",
+  "LabelText",
+  "LineBreak",
+  "list",
+  "listitem",
+  "log",
+  "main",
+  "mark",
+  "navigation",
+  "none",
+  "note",
+  "paragraph",
+  "presentation",
+  "region",
+  "row",
+  "rowgroup",
+  "rowheader",
+  "Section",
+  "separator",
+  "status",
+  "strong",
+  "subscript",
+  "superscript",
+  "table",
+  "term",
+  "text",
+  "time",
+]);
+
+/** States every page repeats that tell the model nothing it can act on. */
+function shownState(role: string, state: string): boolean {
+  if (state === "focusable" || state === "settable" || state === "editable") return false;
+  if (state.startsWith("editable=") || state.startsWith("url=")) return false;
+  if (state.endsWith("=")) return false;
+  if (role === "document" && state === "focused") return false;
+  return true;
+}
+
+function quoted(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function browserNodeLine(node: BrowserTextNode, allRefs: boolean, baseDepth = 0): string {
+  const parts = [`${"  ".repeat(Math.max(0, node.depth - baseDepth))}- ${node.role}`];
+  if (node.name) parts.push(quoted(node.name));
+  if (allRefs || (node.actions?.length ?? 0) > 0 || !REFLESS_ROLES.has(node.role)) {
+    parts.push(`[${node.ref}]`);
+  }
+  if (node.value !== undefined && node.value !== "") {
+    parts.push(typeof node.value === "string" ? `value=${quoted(node.value)}` : "value=<redacted>");
+  }
+  if (node.description) parts.push(`description=${quoted(node.description)}`);
+  for (const state of node.states ?? []) if (shownState(node.role, state)) parts.push(state);
+  return parts.join(" ");
+}
+
+export function browserTargetLine(target: BrowserTextTarget): string {
+  const kind = target.kind === "page" ? "" : ` (${target.kind})`;
+  const selected = target.selected ? " selected" : "";
+  return `Tab ${target.id}${kind}${selected}: ${quoted(target.title)} ${target.url}`;
+}
+
+/** Indent relative to the shallowest listed node, so a view of a deeply
+ * nested part of the page does not spend tokens on leading spaces. */
+function shallowestDepth(nodes: readonly BrowserTextNode[]): number {
+  let base = Number.POSITIVE_INFINITY;
+  for (const node of nodes) base = Math.min(base, node.depth);
+  return Number.isFinite(base) ? base : 0;
+}
+
+function plural(count: number, noun: string): string {
+  if (count === 1) return `${count} ${noun}`;
+  return `${count} ${noun}${/(?:s|x|ch|sh)$/.test(noun) ? "es" : "s"}`;
+}
+
+export function browserObservationText(
+  observation: BrowserTextObservation,
+  options: { allRefs?: boolean } = {},
+): string {
+  const allRefs = options.allRefs === true;
+  const lines = [browserTargetLine({ ...observation.target, selected: false })];
+  const viewport = observation.viewport;
+  if (viewport) {
+    const extras = [
+      viewport.deviceScaleFactor && viewport.deviceScaleFactor !== 1
+        ? `scale ${viewport.deviceScaleFactor}`
+        : null,
+      viewport.maxTouchPoints ? `${viewport.maxTouchPoints} touch points` : null,
+    ].filter((entry): entry is string => entry !== null);
+    lines.push(
+      `Viewport ${viewport.width}x${viewport.height}${extras.length ? ` (${extras.join(", ")})` : ""}`,
+    );
+  }
+  const dialog = observation.dialog;
+  if (dialog) {
+    const prompt =
+      dialog.type === "prompt" && dialog.defaultPrompt
+        ? ` default ${quoted(dialog.defaultPrompt)}`
+        : "";
+    lines.push(`Open ${dialog.type} dialog: ${quoted(dialog.message)}${prompt}`);
+  }
+  const diagnostics = observation.diagnostics;
+  if (diagnostics) {
+    const reported = [
+      diagnostics.consoleErrorCount ? plural(diagnostics.consoleErrorCount, "console error") : null,
+      diagnostics.pageErrorCount ? plural(diagnostics.pageErrorCount, "page error") : null,
+      diagnostics.failedRequestCount
+        ? plural(diagnostics.failedRequestCount, "failed request")
+        : null,
+      diagnostics.downloadCount ? plural(diagnostics.downloadCount, "download") : null,
+    ].filter((entry): entry is string => entry !== null);
+    if (reported.length) lines.push(`Page reported ${reported.join(", ")}`);
+  }
+  if (observation.changedRegions && observation.changedRegions.length > 0) {
+    lines.push(`Changed regions: ${JSON.stringify(observation.changedRegions)}`);
+  }
+  if (observation.screenshot) lines.push(`Screenshot: ${JSON.stringify(observation.screenshot)}`);
+  const view = observation.agentView;
+  const nodes = view.nodes;
+  if (
+    observation.focusedRef &&
+    !nodes.some(
+      (node) => node.ref === observation.focusedRef && (node.states ?? []).includes("focused"),
+    )
+  ) {
+    lines.push(`Focused element: ${observation.focusedRef}`);
+  }
+  if (view.sourceKind === "none") {
+    lines.push("No accessibility view is available for this tab.");
+  } else {
+    if (view.sourceKind === "diff") lines.push("Changed elements:");
+    const base = shallowestDepth(nodes);
+    for (const node of nodes) lines.push(browserNodeLine(node, allRefs, base));
+  }
+  const notes = [
+    view.omittedNodeCount ? `${plural(view.omittedNodeCount, "element")} not shown` : null,
+    view.removedRefCount ? `${plural(view.removedRefCount, "earlier element")} removed` : null,
+    view.clippedFieldCount ? `${plural(view.clippedFieldCount, "long field")} clipped` : null,
+  ].filter((entry): entry is string => entry !== null);
+  if (notes.length) lines.push(`(${notes.join("; ")})`);
+  return lines.join("\n");
+}
+
+export type BrowserTextResolvedTarget = {
+  actionIndex: number;
+  ref: string | null;
+  role: string;
+  name: string | null;
+  container: { role: string; name: string | null } | null;
+};
+
+function resolvedTargetText(target: BrowserTextResolvedTarget): string {
+  const parts = [`#${target.actionIndex} ${target.role}`];
+  if (target.name) parts.push(quoted(target.name));
+  if (target.ref) parts.push(`[${target.ref}]`);
+  if (target.container) {
+    parts.push(
+      `in ${target.container.role}${target.container.name ? ` ${quoted(target.container.name)}` : ""}`,
+    );
+  }
+  return parts.join(" ");
+}
+
+export function browserActionText(receipt: {
+  targetId: string;
+  state: string;
+  error?:
+    | ({ code: string; message: string; retryable: boolean } & Record<string, unknown>)
+    | null
+    | undefined;
+  targets?: readonly BrowserTextResolvedTarget[] | undefined;
+  observation?: BrowserTextObservation | null | undefined;
+  allRefs?: boolean | undefined;
+}): string {
+  const lines = [`Action ${receipt.state} on tab ${receipt.targetId}.`];
+  if (receipt.error) {
+    const { code, message, retryable, ...details } = receipt.error;
+    lines.push(
+      `Error ${code}${retryable ? " (retryable)" : ""}: ${message}${
+        Object.keys(details).length ? ` ${JSON.stringify(details)}` : ""
+      }`,
+    );
+  }
+  if (receipt.targets && receipt.targets.length > 0) {
+    lines.push(`Acted on: ${receipt.targets.map(resolvedTargetText).join("; ")}`);
+  }
+  if (receipt.observation) {
+    lines.push(browserObservationText(receipt.observation, { allRefs: receipt.allRefs === true }));
+  }
+  return lines.join("\n");
+}
+
+const PLACEMENT_LABELS: Record<string, string> = {
+  sandbox_group: "the managed sandbox",
+  connected_machine: "a Connected Machine",
+  external_provider: "a remote browser provider",
+  attached_device: "the user's own Chrome",
+};
+
+export function browserSessionLine(session: {
+  id: string;
+  lifecycle: string;
+  placement: { kind: string };
+  engine?: string | null | undefined;
+  headless?: boolean | null | undefined;
+  identityId?: string | null | undefined;
+  failureCode?: string | null | undefined;
+}): string {
+  const engine = session.engine ?? "browser";
+  const mode =
+    session.placement.kind === "attached_device" ? "" : session.headless ? " headless" : " headed";
+  const placement = PLACEMENT_LABELS[session.placement.kind] ?? session.placement.kind;
+  const extras = [
+    session.identityId ? `identity ${session.identityId}` : null,
+    session.failureCode ? `failure ${session.failureCode}` : null,
+  ].filter((entry): entry is string => entry !== null);
+  return `BrowserSession ${session.id} (${session.lifecycle}): ${engine}${mode} on ${placement}${
+    extras.length ? `, ${extras.join(", ")}` : ""
+  }`;
+}
+
+type AttachedProfileText = { id: string; name: string; profileLabel?: string | undefined };
+
+function attachedProfileText(profile: AttachedProfileText): string {
+  return `${quoted(profile.name)}${profile.profileLabel ? ` (${profile.profileLabel})` : ""} deviceId ${profile.id}`;
+}
+
+export function browserOpenText(output: {
+  session: Parameters<typeof browserSessionLine>[0];
+  targets: readonly BrowserTextTarget[];
+  otherTabCount?: number | undefined;
+  observation?: BrowserTextObservation | undefined;
+  attachedProfile?: AttachedProfileText | undefined;
+  otherAttachedProfiles?: readonly AttachedProfileText[] | undefined;
+}): string {
+  const lines = [browserSessionLine(output.session)];
+  if (output.attachedProfile) {
+    lines.push(`Attached Chrome profile: ${attachedProfileText(output.attachedProfile)}`);
+  }
+  if (output.otherAttachedProfiles && output.otherAttachedProfiles.length > 0) {
+    lines.push(
+      `Other attached profiles: ${output.otherAttachedProfiles.map(attachedProfileText).join("; ")}`,
+    );
+  }
+  const observedId = output.observation?.target.id;
+  for (const target of output.targets) {
+    if (target.id !== observedId) lines.push(browserTargetLine(target));
+  }
+  if (output.otherTabCount) {
+    lines.push(`${plural(output.otherTabCount, "other tab")} (browser_tabs list shows them)`);
+  }
+  if (output.observation) lines.push(browserObservationText(output.observation));
+  else if (output.targets.length === 0) lines.push("No tabs are open.");
+  return lines.join("\n");
+}
+
+export function browserTabsText(output: {
+  browserSessionId: string;
+  targets: readonly BrowserTextTarget[];
+  mutationObservation?: BrowserTextObservation | undefined;
+}): string {
+  const lines = [
+    `BrowserSession ${output.browserSessionId} has ${plural(output.targets.length, "tab")}:`,
+  ];
+  for (const target of output.targets) lines.push(browserTargetLine(target));
+  if (output.mutationObservation) lines.push(browserObservationText(output.mutationObservation));
+  return lines.join("\n");
+}
+
+export function browserReadText(output: {
+  targetId: string;
+  mode: string;
+  scopeFound: boolean;
+  nodes: readonly BrowserTextNode[];
+  totalMatches: number;
+  omittedMatches: number;
+  clippedFieldCount: number;
+}): string {
+  const lines = [
+    `Tab ${output.targetId}: ${plural(output.totalMatches, "match")} (${output.mode})${
+      output.scopeFound ? "" : "; the scope element was not found"
+    }`,
+  ];
+  const base = shallowestDepth(output.nodes);
+  for (const node of output.nodes) lines.push(browserNodeLine(node, true, base));
+  const notes = [
+    output.omittedMatches ? `${plural(output.omittedMatches, "match")} not shown` : null,
+    output.clippedFieldCount ? `${plural(output.clippedFieldCount, "long field")} clipped` : null,
+  ].filter((entry): entry is string => entry !== null);
+  if (notes.length) lines.push(`(${notes.join("; ")})`);
+  return lines.join("\n");
+}

package/src/codex-tool-search.ts

@@ -135,6 +135,59 @@ function familyCompanions<T extends Tool & { name: string }>(disclosed: T[], poo
   return companions;
 }
 
+/**
+ * The tool that starts each interaction family. It stays in the first request,
+ * so a browser or computer task begins with its first real call instead of a
+ * search round trip, and opening discloses the rest of the family right after
+ * the open result (see the lazy-tool transport). Only a tool the attempt
+ * actually prepared can be visible: a first-party interaction tool, or one the
+ * `interaction` server listed, never a same-named tool from another server.
+ */
+const INTERACTION_ENTRY_TOOLS: ReadonlySet<string> = new Set(["browser_open", "computer_open"]);
+
+/** True when a prepared function tool is an interaction family's entry tool. */
+export function isInteractionEntryFunctionTool(
+  tool: unknown,
+  mcpServerIds: ReadonlySet<string> = NO_MCP_SERVER_IDS,
+  modelServerIds?: ReadonlyMap<string, string>,
+): boolean {
+  if (!tool || typeof tool !== "object" || (tool as { type?: unknown }).type !== "function") {
+    return false;
+  }
+  const name = (tool as { name?: unknown }).name;
+  if (typeof name !== "string" || !isInteractionEntryToolName(name)) return false;
+  const serverId = mcpServerIdForTool(tool, mcpServerIds, modelServerIds);
+  return serverId === null || serverId === INTERACTION_MCP_SERVER_ID;
+}
+
+/** True when a model tool name is an interaction family's entry tool. */
+export function isInteractionEntryToolName(name: string): boolean {
+  const short = interactionToolName(name);
+  return short !== null && INTERACTION_ENTRY_TOOLS.has(short);
+}
+
+/**
+ * The companions an entry tool discloses once it is called: the rest of its
+ * family that is still searchable, within the same byte budgets as a search.
+ */
+export function interactionEntryCompanions(entryName: string, searchable: Tool[]): Tool[] {
+  if (!isInteractionEntryToolName(entryName)) return [];
+  const pool = searchable.filter(
+    (tool): tool is Tool & { name: string } =>
+      tool.type === "function" && typeof (tool as { name?: unknown }).name === "string",
+  );
+  const disclosed: Tool[] = [];
+  let disclosedBytes = 0;
+  for (const tool of familyCompanions([{ name: entryName } as Tool & { name: string }], pool)) {
+    const toolBytes = mcpSerializedSizeBytes(tool);
+    if (toolBytes > MCP_MAX_TOOL_DEFINITION_BYTES) continue;
+    if (disclosedBytes + toolBytes > MCP_MAX_TOOL_SEARCH_DISCLOSURE_BYTES) continue;
+    disclosedBytes += toolBytes;
+    disclosed.push(tool);
+  }
+  return disclosed;
+}
+
 /**
  * True when a prepared MCP function tool is one of the harness control tools
  * served by the authorized first-party `opengeni` server. These stay in the

package/src/index.ts

@@ -117,6 +117,7 @@ import { createSecretArgumentResolver } from "./secret-argument-resolution";
 import {
   approvalIdentifier,
   INTERACTION_REQUEST_HUMAN_MODEL_TOOL_NAME,
+  RequestHumanInteractionToolInput,
   CAPABILITY_DESCRIPTORS,
   DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   DEFAULT_FIRST_PARTY_MCP_TOOLS,
@@ -303,6 +304,7 @@ import {
   applyDiff,
   RunContext,
   ToolGuardrailFunctionOutputFactory,
+  defineToolInputGuardrail,
   type AgentInputItem,
   type CallModelInputFilter,
   type MCPServer,
@@ -3881,6 +3883,23 @@ function activeModelToolInvocation(modelName: string): ModelToolInvocation | nul
   return invocation?.modelName === modelName ? invocation : null;
 }
 
+/** Why interaction_request_human arguments cannot be recorded as an
+ * intervention, in words the model can act on, or null when they can. */
+export function interactionRequestArgumentsProblem(serialized: string): string | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(serialized);
+  } catch {
+    return "Invalid interaction_request_human arguments: they are not valid JSON. Nothing was requested; call it again with a JSON object matching its schema.";
+  }
+  const parsed = RequestHumanInteractionToolInput.safeParse(value);
+  if (parsed.success) return null;
+  const issues = parsed.error.issues
+    .slice(0, 5)
+    .map((issue) => `${issue.path.join(".") || "arguments"}: ${issue.message}`);
+  return `Invalid interaction_request_human arguments: ${issues.join("; ")}. Nothing was requested; call it again with corrected arguments.`;
+}
+
 /**
  * Turn the canonical interaction-request tool into a typed SDK interruption.
  * Its MCP/Codemode catalog entry and execution stay unchanged; this projection
@@ -3903,6 +3922,22 @@ function installInteractionInterventionPolicy(
       const originalInvoke = tool.invoke.bind(tool);
       return {
         ...tool,
+        // Runs before the approval pause, so invalid arguments come back to
+        // the model as a correctable tool result. Without it the call would
+        // pause first, the intervention could never be recorded, and the
+        // turn would fail.
+        inputGuardrails: [
+          ...(tool.inputGuardrails ?? []),
+          defineToolInputGuardrail({
+            name: "validate_interaction_request_human",
+            run: async ({ toolCall }) => {
+              const problem = interactionRequestArgumentsProblem(toolCall.arguments);
+              return problem
+                ? ToolGuardrailFunctionOutputFactory.rejectContent(problem)
+                : ToolGuardrailFunctionOutputFactory.allow();
+            },
+          }),
+        ],
         needsApproval: async (
           _runContext: Parameters<typeof originalNeedsApproval>[0],
           _parsedInput: Parameters<typeof originalNeedsApproval>[1],
@@ -8469,7 +8504,10 @@ export class PrefixedMcpServer implements MCPServer {
           return {
             ...tool,
             name,
-            ...(this.accountLabel
+            // Name the account only when the turn has several accounts of this
+            // connector to tell apart. With one account the line adds nothing
+            // the model can act on, and it would repeat on every tool.
+            ...(this.accountLabel?.account
               ? {
                   description:
                     `Account: ${this.accountLabel.model}. Use only this account; if the intended account for a write is unclear, ask before calling.\n${tool.description ?? ""}`.trimEnd(),