Normalize structured agent output types at runtime

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

Author: cursoragent

currentState.md

@@ -111,8 +111,11 @@ HyperAgent exposes a TypeScript SDK for browser automation with three primary pa
 - Hardened perform-action failure formatting with explicit bounded diagnostics, including trap-prone DOM element lookup failures.
 - Hardened Anthropic provider structured-output warning diagnostics in schema validation fallback branches.
 - Hardened network-settle waiting (`waitForSettledDOM`) with safe listener attach/detach handling, timeout fallback when listener registration fails, and bounded stalled-request diagnostics.
+- Added bounded timeout normalization in `waitForSettledDOM` so invalid/non-finite/non-positive waits no longer resolve immediately and oversized values are capped.
 - Hardened replay-step diagnostics in `runFromActionCache` to strip control characters in cached-step/page getter failure messages.
 - Sanitized control characters in prompt-builder task/step/DOM payload serialization before truncation to keep LLM context inputs clean under malformed runtime values.
+- Tightened agent-loop action/output typing by normalizing parsed structured outputs into explicit `AgentOutput`/`ActionType` shapes before runtime dispatch and cache recording.
+- Removed direct `as any` casts in OpenAI/Anthropic/DeepSeek/Gemini provider request payload assembly in favor of SDK-derived parameter field typing.
 - 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/tools/agent.test.ts

@@ -46,7 +46,12 @@ function createMockPage(): Page {
   } as unknown as Page;
 }
 
-function createCompleteActionDefinition(): AgentActionDefinition {
+function createCompleteActionDefinition(): AgentActionDefinition<
+  z.ZodObject<{
+    success: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+  }>
+> {
   return {
     type: "complete",
     actionParams: z.object({

src/agent/tools/agent.ts

@@ -1,5 +1,6 @@
 import {
   ActionCacheOutput,
+  AgentOutput,
   AgentStep,
   AgentTaskOutput,
 } from "@/types/agent/types";
@@ -227,6 +228,28 @@ function normalizeActionOutput(
   };
 }
 
+function normalizeAgentOutput(value: unknown): AgentOutput {
+  const thoughts = formatDiagnosticText(
+    safeReadRecordField(value, "thoughts"),
+    MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+    ""
+  );
+  const memory = formatDiagnosticText(
+    safeReadRecordField(value, "memory"),
+    MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+    ""
+  );
+  const action = safeReadRecordField(value, "action");
+  return {
+    thoughts,
+    memory,
+    action: {
+      type: normalizeRuntimeActionType(safeReadRecordField(action, "type")),
+      params: safeReadRecordField(action, "params"),
+    },
+  };
+}
+
 function resolveCompleteActionFormatter(
   actions: Array<AgentActionDefinition>
 ):
@@ -855,7 +878,7 @@ export const runAgentTask = async (
       }
 
       // Invoke LLM with structured output
-      const agentOutput = await (async () => {
+      const rawAgentOutput = await (async () => {
         const maxAttempts = 3;
         let currentMsgs = msgs;
 
@@ -1004,6 +1027,7 @@ export const runAgentTask = async (
         }
         throw new Error("Failed to get structured output from LLM");
       })();
+      const agentOutput = normalizeAgentOutput(rawAgentOutput);
 
       params?.debugOnAgentOutput?.(agentOutput);
 

src/types/agent/types.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ActionOutput } from "./actions/types";
+import { ActionOutput, ActionType } from "./actions/types";
 import { Page } from "playwright-core";
 import { ErrorEmitter } from "@/utils";
 import type { HyperAgentLLM } from "@/llm/types";
@@ -24,7 +24,11 @@ export const AgentOutputFn = (
     action: actionsSchema,
   });
 
-export type AgentOutput = z.infer<ReturnType<typeof AgentOutputFn>>;
+export interface AgentOutput {
+  thoughts: string;
+  memory: string;
+  action: ActionType;
+}
 
 export interface AgentStep {
   idx: number;