Cap prompt variable serialization for context budget

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

currentState.md

@@ -132,6 +132,7 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
 - Normalized CLI per-step failure rendering in `cli/index.ts` so action error messages are sanitized/truncated via `formatCliError` before display.
 - Added Anthropic structured-output regression coverage confirming multi-action calls enforce deterministic `tool_choice: { type: "any", disable_parallel_tool_use: true }`.
 - Hardened CDP frame-filter host/path matching to avoid query-text false positives (e.g. unrelated URLs containing `https://yahoo.com/pixel` in query params) while preserving legitimate host-suffix + path rule matching.
+- Hardened prompt token budgeting for variables by capping serialized variable entries per step-message build and emitting omitted-count context instead of unbounded variable dumps.
 - Expanded top-level package exports for key workflow/config types at `@hyperbrowser/agent`.
 - Removed stale script entry (`build-dom-tree-script`) and improved README usage docs.
 - Added canonical single-action debug writer helper (`writePerformDebug`) while preserving deprecated alias compatibility.

src/agent/messages/builder.test.ts

@@ -710,6 +710,90 @@ describe("buildAgentStepMessages", () => {
     expect(joined).toContain("[variable value unavailable]");
   });
 
+  it("caps variable entries for prompt budget and reports omitted count", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const variables = Array.from({ length: 35 }, (_, index) => ({
+      key: `var_${index}`,
+      value: `value_${index}`,
+      description: `description ${index}`,
+    }));
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      variables
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("<<var_0>>");
+    expect(joined).toContain("<<var_24>>");
+    expect(joined).not.toContain("<<var_25>>");
+    expect(joined).toContain("... 10 more variables omitted for context budget");
+  });
+
+  it("falls back to empty variable section when array length getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedVariables = new Proxy(
+      [
+        {
+          key: "token",
+          value: "abc",
+          description: "desc",
+        },
+      ],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "length") {
+            throw new Error("length trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      trappedVariables as unknown as Parameters<typeof buildAgentStepMessages>[6]
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Variables ===");
+    expect(joined).toContain("No variables set");
+  });
+
   it("truncates oversized DOM state payloads", async () => {
     const page = createFakePage("https://example.com/current", [
       "https://example.com/current",

src/agent/messages/builder.ts

@@ -13,6 +13,7 @@ const MAX_DOM_STATE_CHARS = 50_000;
 const MAX_OPEN_TAB_ENTRIES = 20;
 const MAX_TAB_URL_CHARS = 500;
 const MAX_VARIABLE_KEY_CHARS = 120;
+const MAX_VARIABLE_ITEMS = 25;
 const MAX_OMITTED_STEP_SUMMARY_STEPS = 5;
 const MAX_OMITTED_STEP_SUMMARY_CHARS = 1_500;
 const MAX_OMITTED_STEP_ACTION_CHARS = 120;
@@ -186,6 +187,59 @@ function safeReadRecordField(source: unknown, field: string): unknown {
   }
 }
 
+function safeArrayLength(value: unknown): number {
+  if (!Array.isArray(value)) {
+    return 0;
+  }
+  try {
+    const length = value.length;
+    if (!Number.isFinite(length) || length < 0) {
+      return 0;
+    }
+    return Math.floor(length);
+  } catch {
+    return 0;
+  }
+}
+
+function safeReadArrayItem<T>(value: unknown, index: number): T | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    return value[index] as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function getBoundedVariables(variables: HyperVariable[]): {
+  visibleVariables: HyperVariable[];
+  omittedCount: number;
+} {
+  const total = safeArrayLength(variables);
+  if (total === 0) {
+    return {
+      visibleVariables: [],
+      omittedCount: 0,
+    };
+  }
+
+  const visibleVariables: HyperVariable[] = [];
+  const maxVisible = Math.min(total, MAX_VARIABLE_ITEMS);
+  for (let index = 0; index < maxVisible; index += 1) {
+    const variable = safeReadArrayItem<HyperVariable>(variables, index);
+    if (typeof variable !== "undefined") {
+      visibleVariables.push(variable);
+    }
+  }
+
+  return {
+    visibleVariables,
+    omittedCount: Math.max(0, total - visibleVariables.length),
+  };
+}
+
 function normalizeStepText(value: unknown, fallback: string): string {
   if (typeof value === "string") {
     return truncatePromptText(value);
@@ -197,11 +251,12 @@ function normalizeStepText(value: unknown, fallback: string): string {
 }
 
 function buildVariablesContent(variables: HyperVariable[]): string {
-  if (variables.length === 0) {
+  const { visibleVariables, omittedCount } = getBoundedVariables(variables);
+  if (visibleVariables.length === 0) {
     return "No variables set";
   }
 
-  return variables
+  const variableLines = visibleVariables
     .map((variable, index) => {
       const key = normalizeVariableKey(safeReadVariableField(variable, "key"), index);
       const description = normalizeVariableDescription(
@@ -213,6 +268,12 @@ function buildVariablesContent(variables: HyperVariable[]): string {
       return `<<${key}>> - ${description} | current value: ${currentValue}`;
     })
     .join("\n");
+
+  if (omittedCount <= 0) {
+    return variableLines;
+  }
+  const suffix = omittedCount === 1 ? "" : "s";
+  return `${variableLines}\n... ${omittedCount} more variable${suffix} omitted for context budget`;
 }
 
 function getStepPromptData(step: AgentStep): {