@spicrawl/mcp 0.0.0-stage → 0.1.0

package/dist/tools/actions.d.ts

@@ -0,0 +1,534 @@
+import { z } from "zod";
+export declare const ActionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+} & {
+    selector: z.ZodString;
+    wait_for_navigation: z.ZodOptional<z.ZodBoolean>;
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"fill">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for">;
+} & {
+    selector: z.ZodOptional<z.ZodString>;
+    ms: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for_navigation">;
+} & {
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+} & {
+    y: z.ZodOptional<z.ZodNumber>;
+    to_bottom: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"evaluate">;
+} & {
+    expression: z.ZodString;
+    return_value: z.ZodOptional<z.ZodBoolean>;
+    await_promise: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+} & {
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["png", "jpeg", "webp"]>>;
+    quality: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}>]>;
+export type Action = z.infer<typeof ActionSchema>;
+export declare const ActionsSchema: z.ZodEffects<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+} & {
+    selector: z.ZodString;
+    wait_for_navigation: z.ZodOptional<z.ZodBoolean>;
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"fill">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for">;
+} & {
+    selector: z.ZodOptional<z.ZodString>;
+    ms: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for_navigation">;
+} & {
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+} & {
+    y: z.ZodOptional<z.ZodNumber>;
+    to_bottom: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"evaluate">;
+} & {
+    expression: z.ZodString;
+    return_value: z.ZodOptional<z.ZodBoolean>;
+    await_promise: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+} & {
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["png", "jpeg", "webp"]>>;
+    quality: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}>]>, "many">, ({
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+} | {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+} | {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+} | {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+} | {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+} | {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+})[], ({
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+} | {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+} | {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+} | {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+} | {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+} | {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+})[]>;
+/** Map typed steps onto the API's keyed shape: {kind: {fields}, timeout_ms?, on_error?, label?}. */
+export declare function toApiActions(steps: Action[]): Record<string, unknown>[];

package/dist/tools/actions.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Browser actions for spicrawl_scrape, as an explicit discriminated union.
+//
+// The API's step shape is an object keyed by its kind — {"click": {...}} — which
+// a JSON schema can only describe as "any object". Agents given that schema
+// guessed field names (`scroll.pixels`, `evaluate.script`) and got 400s. Here
+// each step is `{type, ...fields}` with its fields spelt exactly as the Go
+// router (api/internal/router/actions.go) reads them; toApiActions maps it back
+// onto the keyed shape. Only kinds the API supports are offered: there is no
+// hover or press step to map to.
+// ---------------------------------------------------------------------------
+const until = z
+    .enum(["load", "domcontentloaded", "networkidle"])
+    .describe("Load state the new document must reach. Default load.");
+/** Keys every step accepts; they sit beside the kind key in the API shape. */
+const meta = {
+    timeout_ms: z.number().int().min(1).optional().describe("Budget for this step in ms. The step fails (or is skipped) when it runs out."),
+    on_error: z.enum(["fail", "skip"]).optional().describe("fail (default) aborts the workflow; skip records the failure and continues."),
+    label: z.string().optional().describe("Name echoed in the response's `actions` and `screenshots`."),
+};
+const META_KEYS = Object.keys(meta);
+const step = (type, fields, description) => z.object({ type: z.literal(type), ...fields, ...meta }).strict().describe(description);
+export const ActionSchema = z.discriminatedUnion("type", [
+    step("click", {
+        selector: z.string().min(1).describe("CSS selector of the element to click."),
+        wait_for_navigation: z.boolean().optional().describe("The click navigates: finish the step only once the new page has loaded."),
+        until: until.optional(),
+    }, "Click an element. On a checkbox or radio this toggles it (there is no 'set checked'); read its state with evaluate if it matters."),
+    step("fill", {
+        selector: z.string().min(1),
+        value: z.string(),
+        secret: z.boolean().optional().describe("A credential: redacted from logs and the request log."),
+    }, "Type a value into an input."),
+    step("wait_for", {
+        selector: z.string().min(1).optional().describe("CSS selector to wait for."),
+        ms: z.number().int().min(1).optional().describe("Or: sleep this many ms."),
+    }, "Wait for a selector to appear, or sleep `ms`."),
+    step("wait_for_navigation", { until: until.optional() }, "Wait for a navigation started by the previous step (a click, a form submit, a redirect) to load."),
+    step("scroll", {
+        y: z.number().int().optional().describe("Pixels to scroll down (negative scrolls up)."),
+        to_bottom: z.boolean().optional().describe("Scroll to the bottom repeatedly until the page stops growing (infinite scroll)."),
+        selector: z.string().min(1).optional().describe("Scroll this element into view."),
+    }, "Scroll the page: give exactly one of y, to_bottom or selector."),
+    step("select", {
+        selector: z.string().min(1).describe("CSS selector of the <select>."),
+        value: z.string().optional(),
+        values: z.array(z.string()).optional().describe("Several options, for a multi-select."),
+    }, "Choose option(s) in a <select> by value."),
+    step("evaluate", {
+        expression: z.string().min(1).describe("JavaScript expression evaluated in the page."),
+        return_value: z.boolean().optional().describe("Return the value under `actions` in the response (forces format json)."),
+        await_promise: z.boolean().optional(),
+    }, "Run JavaScript in the page."),
+    step("screenshot", {
+        full_page: z.boolean().optional(),
+        selector: z.string().min(1).optional().describe("Capture only this element."),
+        format: z.enum(["png", "jpeg", "webp"]).optional(),
+        quality: z.number().int().min(1).max(100).optional(),
+    }, "Capture the page at this point. The image is returned as an image block; the response becomes the JSON envelope whatever `format` says."),
+]);
+export const ActionsSchema = z
+    .array(ActionSchema)
+    .superRefine((steps, ctx) => {
+    steps.forEach((s, i) => {
+        if (s.type === "scroll" && [s.y !== undefined, s.to_bottom === true, s.selector !== undefined].filter(Boolean).length !== 1) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [i], message: "scroll needs exactly one of y, to_bottom or selector" });
+        }
+        if (s.type === "wait_for" && s.selector === undefined && s.ms === undefined) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [i], message: "wait_for needs selector or ms" });
+        }
+        if (s.type === "select" && s.value === undefined && !s.values?.length) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [i], message: "select needs value or values" });
+        }
+        if (s.type === "click" && s.until !== undefined && s.wait_for_navigation !== true) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [i], message: "click.until only applies with wait_for_navigation: true" });
+        }
+    });
+})
+    .describe("Browser steps run in order before capture (render only). Each step is {type, ...fields}. Examples: " +
+    '[{"type":"click","selector":"#load-more"},{"type":"wait_for","selector":".item:nth-child(20)","timeout_ms":5000}] · ' +
+    'infinite scroll: [{"type":"scroll","to_bottom":true},{"type":"wait_for","ms":1000}] · ' +
+    'login: [{"type":"fill","selector":"#user","value":"me"},{"type":"fill","selector":"#pass","value":"…","secret":true},' +
+    '{"type":"click","selector":"button[type=submit]","wait_for_navigation":true}]. ' +
+    "A screenshot step switches the response to the JSON envelope (a FORMAT_COERCED warning says so).");
+/** Map typed steps onto the API's keyed shape: {kind: {fields}, timeout_ms?, on_error?, label?}. */
+export function toApiActions(steps) {
+    return steps.map((s) => {
+        const { type, ...rest } = s;
+        const body = {};
+        const out = {};
+        for (const [k, v] of Object.entries(rest)) {
+            if (v === undefined)
+                continue;
+            if (META_KEYS.includes(k))
+                out[k] = v;
+            else
+                body[k] = v;
+        }
+        return { [type]: body, ...out };
+    });
+}
+//# sourceMappingURL=actions.js.map

package/dist/tools/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/tools/actions.ts"],"names":[],"mappings":"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"}

package/dist/tools/batch.d.ts

@@ -0,0 +1,2 @@
+import { type RegisterTools } from "./common.js";
+export declare const registerBatchTools: RegisterTools;