update the extract tool in v2 agent

[tkattkat]

why

update extract handling

what changed

test plan

---

Summary by cubic

Switch the v2 agent extract tool to accept JSON Schema and convert it to Zod internally. This removes unsafe schema string evaluation and adds format support (url, email, uuid) for clearer, safer extraction.

• Refactors

  • Replaced Function-based Zod string evaluation with JSON Schema → Zod conversion.
  • Added format handling for url, email, and uuid; supports enum and arrays via items.
  • Wrapped non-object schemas into an object as { result: ... } for consistent output.
  • Removed logger dependency from createExtractTool and its registration.

• Migration

  • Pass schema as a JSON object (JSON Schema), not a Zod string.
  • Use format: "url" for links; use enum for string lists; use items for arrays.
  • If you call createExtractTool directly, remove the logger parameter.

^{Written for commit c1d8cf1. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: c1d8cf1

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

2 issues found across 2 files

Confidence score: 3/5

• There is some user-impacting risk: jsonSchemaToZod in lib/agent/tools/extract.ts can crash at runtime when nested property values are null/undefined.
• z.enum() is called even when schema.enum is an empty array, which will throw at runtime; add a length check to avoid invalid enums.
• Because these are concrete runtime errors in schema conversion, the merge risk is moderate rather than minimal.
• Pay close attention to lib/agent/tools/extract.ts - runtime guards for null property values and empty enums.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="lib/agent/tools/extract.ts">

<violation number="1" location="lib/agent/tools/extract.ts:13">
P1: Missing null/undefined guard in `jsonSchemaToZod` will cause runtime crash when nested property values are null. The parameter schema allows `z.unknown()` for property values, but the function immediately accesses `schema.type` without checking if schema exists.</violation>

<violation number="2" location="lib/agent/tools/extract.ts:31">
P1: `z.enum()` requires at least one enum value, but this check will pass when `schema.enum` is an empty array `[]` (empty arrays are truthy). This will cause a runtime error. Add a length check: `if (schema.enum && schema.enum.length > 0)`</violation>
</file>

Architecture diagram

sequenceDiagram
    participant AI as AI Agent
    participant Tool as Extract Tool
    participant Logic as jsonSchemaToZod
    participant Core as Stagehand Core

    Note over AI, Tool: NEW: Schema passed as structured JSON object\n(formerly a string containing JS code)

    AI->>Tool: execute({ instruction, schema: JsonSchema })
    
    Tool->>Core: log(instruction, schema)

    Note over Tool, Logic: NEW: Safe conversion strategy replacing\nunsafe "new Function()" evaluation

    Tool->>Logic: Convert JSON Schema to Zod
    
    loop Recursively parse schema properties
        alt type is "object"
            Logic->>Logic: Create z.object(properties)
        else type is "array"
            Logic->>Logic: Create z.array(items)
        else type is "string"
            opt format defined
                Logic->>Logic: Apply .url(), .email(), or .uuid()
            end
            opt enum defined
                Logic->>Logic: Create z.enum(values)
            end
        else primitives
            Logic->>Logic: Create z.number(), z.boolean(), etc.
        end
    end

    Logic->>Tool: ZodSchema Instance

    alt Schema is not ZodObject
        Tool->>Tool: Wrap as z.object({ result: schema })
    end

    Tool->>Core: page.extract({ instruction, schema: zodObject })
    
    Core->>Tool: Extracted Data (JSON)
    Tool->>AI: Return Result

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}