Harden prompt builder against trap-prone step arrays

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

Author: cursoragent

currentState.md

@@ -134,6 +134,7 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
 - 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 trap-safe per-call override regression coverage for sync task execution and replay params to ensure `cdpActions` / `filterAdTrackingFrames` reliably fall back to agent defaults when option getters throw.
+- Hardened prompt-step history materialization with trap-safe step-array reads so malformed/trap-prone `steps` payloads degrade gracefully instead of crashing message assembly.
 - 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

@@ -214,6 +214,82 @@ describe("buildAgentStepMessages", () => {
     expect(joined).toContain("Action output unavailable");
   });
 
+  it("falls back to no previous-actions section when step array length getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedSteps = new Proxy([createStep(0)], {
+      get: (target, prop, receiver) => {
+        if (prop === "length") {
+          throw new Error("steps length trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      trappedSteps as unknown as AgentStep[],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).not.toContain("=== Previous Actions ===");
+    expect(joined).toContain("=== Final Goal ===");
+  });
+
+  it("ignores unreadable step array entries when index getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedSteps = new Proxy([createStep(0)], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("steps item trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      trappedSteps as unknown as AgentStep[],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).not.toContain("=== Previous Actions ===");
+    expect(joined).not.toContain("thought-0");
+  });
+
   it("falls back to zeroed page state when scroll info lookup fails", async () => {
     retry.mockRejectedValue({ reason: "scroll failed" });
     const page = createFakePage("https://example.com/current", [

src/agent/messages/builder.ts

@@ -240,6 +240,22 @@ function getBoundedVariables(variables: HyperVariable[]): {
   };
 }
 
+function materializeSafeSteps(steps: AgentStep[]): AgentStep[] {
+  const total = safeArrayLength(steps);
+  if (total === 0) {
+    return [];
+  }
+
+  const normalizedSteps: AgentStep[] = [];
+  for (let index = 0; index < total; index += 1) {
+    const step = safeReadArrayItem<AgentStep>(steps, index);
+    if (typeof step !== "undefined") {
+      normalizedSteps.push(step);
+    }
+  }
+  return normalizedSteps;
+}
+
 function normalizeStepText(value: unknown, fallback: string): string {
   if (typeof value === "string") {
     return truncatePromptText(value);
@@ -405,6 +421,7 @@ export const buildAgentStepMessages = async (
   variables: HyperVariable[]
 ): Promise<HyperAgentMessage[]> => {
   const messages = [...baseMessages];
+  const normalizedSteps = materializeSafeSteps(steps);
 
   // Add the final goal section
   messages.push({
@@ -432,20 +449,20 @@ export const buildAgentStepMessages = async (
   });
 
   // Add previous actions section if there are steps
-  if (steps.length > 0) {
+  if (normalizedSteps.length > 0) {
     const relevantSteps =
-      steps.length > MAX_HISTORY_STEPS
-        ? steps.slice(-MAX_HISTORY_STEPS)
-        : steps;
-    const hiddenStepCount = steps.length - relevantSteps.length;
+      normalizedSteps.length > MAX_HISTORY_STEPS
+        ? normalizedSteps.slice(-MAX_HISTORY_STEPS)
+        : normalizedSteps;
+    const hiddenStepCount = normalizedSteps.length - relevantSteps.length;
     const omittedSteps =
-      hiddenStepCount > 0 ? steps.slice(0, hiddenStepCount) : [];
+      hiddenStepCount > 0 ? normalizedSteps.slice(0, hiddenStepCount) : [];
 
     messages.push({
       role: "user",
       content:
         hiddenStepCount > 0
-          ? `=== Previous Actions ===\n(Showing latest ${relevantSteps.length} of ${steps.length} steps; ${hiddenStepCount} older steps omitted for context budget.)\n`
+          ? `=== Previous Actions ===\n(Showing latest ${relevantSteps.length} of ${normalizedSteps.length} steps; ${hiddenStepCount} older steps omitted for context budget.)\n`
           : "=== Previous Actions ===\n",
     });
     if (hiddenStepCount > 0) {