@wardby/cli 0.5.3 → 0.7.0

package/dist/sandbox/run-in-sandbox.js

@@ -7,12 +7,13 @@
  * exhaustion, or non-serializable return all fail *that call* cleanly
  * instead of crashing the run or the host process.
  */
-import { installHostFunctions } from "./host-functions.js";
+import { createPrivilegedHost, installSandboxApi } from "./host-functions.js";
 import { SANDBOX_PRELUDE } from "./prelude.js";
 import { evalToJson, NON_SERIALIZABLE_MARKER } from "./eval-core.js";
 import { boundedJson, boundedString } from "./bounded-json.js";
 import { BRIDGE_INPUT_BYTES } from "./limits.js";
-export async function runInSandbox(invocation) {
+/** Evaluates one tool body in a fresh QuickJS context against the given privileged host. */
+export async function runToolCode(invocation) {
     let params;
     try {
         boundedString(invocation.code, BRIDGE_INPUT_BYTES);
@@ -39,15 +40,32 @@ export async function runInSandbox(invocation) {
   }
 })()`;
     return evalToJson(code, invocation.limits, (context, runtime, signal) => {
-        installHostFunctions(context, runtime, {
-            agentId: invocation.agentId,
-            datastore: invocation.datastore,
-            sharedDatastore: invocation.sharedDatastore,
-            logTag: invocation.toolName,
-            secrets: invocation.secrets,
-            logger: invocation.logger,
-            allowedFetchHosts: invocation.allowedFetchHosts,
+        installSandboxApi(context, runtime, {
+            privileged: invocation.privileged(signal),
             signal,
+            parserPool: invocation.parserPool,
         });
     });
 }
+/** The in-process privileged host for a sandbox invocation. */
+export function privilegedHostFor(invocation, signal) {
+    return createPrivilegedHost({
+        agentId: invocation.agentId,
+        datastore: invocation.datastore,
+        sharedDatastore: invocation.sharedDatastore,
+        logTag: invocation.toolName,
+        secrets: invocation.secrets,
+        logger: invocation.logger,
+        allowedFetchHosts: invocation.allowedFetchHosts,
+        fetchImpl: invocation.fetchImpl,
+        signal,
+    });
+}
+export async function runInSandbox(invocation) {
+    return runToolCode({
+        code: invocation.code,
+        params: invocation.params,
+        limits: invocation.limits,
+        privileged: (signal) => privilegedHostFor(invocation, signal),
+    });
+}

package/dist/sandbox/safe-fetch.d.ts

@@ -12,6 +12,8 @@ export declare function requestPinned(destination: Destination, init: SafeFetchI
 export interface SafeFetchOptions extends FetchPolicyOptions {
     signal?: AbortSignal;
     connect?: typeof requestPinned;
+    /** False: a 3xx is returned to the caller as-is (brokered requests re-check every hop themselves). */
+    followRedirects?: boolean;
 }
 export declare function safeFetch(input: string, init?: SafeFetchInit, options?: SafeFetchOptions): Promise<{
     ok: boolean;

package/dist/sandbox/safe-fetch.js

@@ -60,7 +60,9 @@ export async function safeFetch(input, init = {}, options = {}) {
             signal.throwIfAborted();
             response = await (options.connect ?? requestPinned)(destination, { method, headers, body }, signal);
             const status = response.statusCode ?? 0;
-            if ([301, 302, 303, 307, 308].includes(status) && response.headers.location) {
+            if (options.followRedirects !== false &&
+                [301, 302, 303, 307, 308].includes(status) &&
+                response.headers.location) {
                 response.destroy();
                 if (hop >= MAX_REDIRECTS)
                     throw new Error("fetch_redirect_limit");

package/dist/sandbox/secret-broker-sigv4.d.ts

@@ -0,0 +1,2 @@
+import type { BrokeredSecret, BrokerRequest } from "./secret-broker.js";
+export declare function signSigV4(request: BrokerRequest, secret: BrokeredSecret, now?: Date): Promise<BrokerRequest>;

package/dist/sandbox/secret-broker-sigv4.js

@@ -0,0 +1,49 @@
+/** AWS SigV4 for a brokered secret, using AWS's own signer. The tool never sees the keys. */
+import { SignatureV4 } from "@smithy/signature-v4";
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { parseSigV4Value } from "../core/secret-broker-config.js";
+const SIGNER_HEADERS = ["authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"];
+/** Group query params by key so repeated keys survive (Object.fromEntries would drop them). */
+function queryOf(url) {
+    const query = {};
+    for (const key of new Set(url.searchParams.keys())) {
+        const all = url.searchParams.getAll(key);
+        query[key] = all.length === 1 ? all[0] : all;
+    }
+    return query;
+}
+export async function signSigV4(request, secret, now = new Date()) {
+    if (secret.broker.placement.kind !== "aws-sigv4") {
+        throw new Error("signSigV4 needs an aws-sigv4 secret");
+    }
+    const headers = Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k.toLowerCase(), v]));
+    for (const h of SIGNER_HEADERS) {
+        if (h in headers) {
+            throw new Error(`secret_broker_conflict: header "${h}" is set by the SigV4 signer for "${secret.name}"`);
+        }
+    }
+    // safeFetch replaces accept-encoding after signing; a signed one would no longer match.
+    delete headers["accept-encoding"];
+    const { region, service } = secret.broker.placement;
+    const signer = new SignatureV4({
+        credentials: parseSigV4Value(secret.value),
+        region,
+        service,
+        sha256: Sha256,
+        applyChecksum: service === "s3",
+        uriEscapePath: service !== "s3",
+    });
+    const url = new URL(request.url);
+    const signed = await signer.sign({
+        method: request.method,
+        protocol: url.protocol,
+        hostname: url.hostname,
+        path: url.pathname,
+        query: queryOf(url),
+        headers: { ...headers, host: url.host },
+        body: request.body,
+    }, { signingDate: now });
+    const out = Object.fromEntries(Object.entries(signed.headers).map(([k, v]) => [k.toLowerCase(), String(v)]));
+    delete out.host; // safeFetch forbids setting Host; Node sets the same value from the URL.
+    return { ...request, headers: out };
+}

package/dist/sandbox/secret-broker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Brokered secrets at request time: check the destination, place each value where its
+ * owner said, and scrub values from the response. Pure — the privileged host
+ * (host-functions.ts) does the I/O. SigV4 signing is in secret-broker-sigv4.ts.
+ */
+import { type SecretBrokerConfig } from "../core/secret-broker-config.js";
+export interface BrokeredSecret {
+    name: string;
+    value: string;
+    broker: SecretBrokerConfig;
+}
+export interface BrokerRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export declare function checkBrokerDestination(url: string, secrets: readonly BrokeredSecret[]): void;
+export declare function applyBrokerPlacements(request: BrokerRequest, secrets: readonly BrokeredSecret[]): BrokerRequest;
+export declare function brokerScrubValues(secrets: readonly BrokeredSecret[]): string[];
+/**
+ * The strings console output must not show for one secret the tool may use: its value and, for a
+ * brokered SigV4 secret, the secret key and session token alone. A value that won't parse adds nothing.
+ */
+export declare function consoleRedactionValues(entry: {
+    value: string;
+    broker: SecretBrokerConfig | null;
+}): string[];
+export declare function scrubBrokeredResponse<T extends {
+    headers: Record<string, string>;
+    bodyBase64: string;
+    url: string;
+    statusText?: string;
+}>(response: T, values: readonly string[]): T;

package/dist/sandbox/secret-broker.js

@@ -0,0 +1,161 @@
+/**
+ * Brokered secrets at request time: check the destination, place each value where its
+ * owner said, and scrub values from the response. Pure — the privileged host
+ * (host-functions.ts) does the I/O. SigV4 signing is in secret-broker-sigv4.ts.
+ */
+import { parseSigV4Value } from "../core/secret-broker-config.js";
+import { redactExactSecretValues } from "../core/secret-spans.js";
+const REDACTED = "[REDACTED]";
+function deny(reason) {
+    throw new Error(`secret_broker_destination_denied: ${reason}`);
+}
+function conflict(reason) {
+    throw new Error(`secret_broker_conflict: ${reason}`);
+}
+export function checkBrokerDestination(url, secrets) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        deny("invalid URL");
+    }
+    if (parsed.protocol !== "https:")
+        deny("brokered secrets are only sent over https");
+    if (parsed.port !== "")
+        deny("brokered secrets are only sent to the default https port");
+    const host = parsed.hostname.toLowerCase();
+    for (const s of secrets) {
+        if (!s.broker.hosts.includes(host))
+            deny(`"${s.name}" may not be sent to ${host}`);
+        const prefixes = s.broker.pathPrefixes ?? [];
+        if (prefixes.length && !prefixes.some((p) => parsed.pathname.startsWith(p))) {
+            deny(`"${s.name}" may not be sent to path ${parsed.pathname}`);
+        }
+        // An encoded slash or backslash may be decoded upstream into a separator, escaping the prefix.
+        if (prefixes.length && /%2f|%5c/i.test(parsed.pathname)) {
+            deny(`"${s.name}" may not be sent to a path with an encoded separator`);
+        }
+    }
+}
+function contentType(headers) {
+    return (headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+}
+export function applyBrokerPlacements(request, secrets) {
+    const headers = Object.fromEntries(Object.entries(request.headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const url = new URL(request.url);
+    let body = request.body;
+    const placed = new Set();
+    for (const s of secrets) {
+        const p = s.broker.placement;
+        if (p.kind === "header") {
+            const key = p.name.toLowerCase();
+            if (key in headers || placed.has(`h:${key}`))
+                conflict(`header "${p.name}" is set by the broker for "${s.name}"`);
+            // A replacer function, not a string: "$$", "$&", "$'" in a value are literal, not patterns.
+            headers[key] = p.format.replace("{value}", () => s.value);
+            placed.add(`h:${key}`);
+        }
+        else if (p.kind === "query") {
+            if (url.searchParams.has(p.name) || placed.has(`q:${p.name}`))
+                conflict(`query parameter "${p.name}" is set by the broker for "${s.name}"`);
+            url.searchParams.append(p.name, s.value);
+            placed.add(`q:${p.name}`);
+        }
+        else if (p.kind === "body") {
+            if (placed.has(`b:${p.field}`))
+                conflict(`body field "${p.field}" is set by the broker for "${s.name}"`);
+            body = placeBodyField(headers, body, p.field, s);
+            placed.add(`b:${p.field}`);
+        }
+    }
+    return { ...request, url: url.href, headers, body };
+}
+function placeBodyField(headers, body, field, s) {
+    const type = contentType(headers);
+    if (body === undefined)
+        throw new Error(`secret_broker_body_invalid: "${s.name}" is placed in the body, but the request has none`);
+    if (type === "application/json" || type.endsWith("+json")) {
+        let json;
+        try {
+            json = JSON.parse(body);
+        }
+        catch {
+            throw new Error("secret_broker_body_invalid: the body is not valid JSON");
+        }
+        if (json === null || typeof json !== "object" || Array.isArray(json)) {
+            throw new Error("secret_broker_body_invalid: a brokered JSON body must be an object");
+        }
+        if (Object.hasOwn(json, field))
+            conflict(`body field "${field}" is set by the broker for "${s.name}"`);
+        return JSON.stringify({ ...json, [field]: s.value });
+    }
+    if (type === "application/x-www-form-urlencoded") {
+        const form = new URLSearchParams(body);
+        if (form.has(field))
+            conflict(`body field "${field}" is set by the broker for "${s.name}"`);
+        form.append(field, s.value);
+        return form.toString();
+    }
+    throw new Error("secret_broker_body_invalid: body placement needs a JSON-object or form-encoded body");
+}
+export function brokerScrubValues(secrets) {
+    return secrets.flatMap((s) => {
+        if (s.broker.placement.kind !== "aws-sigv4")
+            return [s.value];
+        const creds = parseSigV4Value(s.value);
+        return [creds.secretAccessKey, ...(creds.sessionToken ? [creds.sessionToken] : [])];
+    });
+}
+/**
+ * The strings console output must not show for one secret the tool may use: its value and, for a
+ * brokered SigV4 secret, the secret key and session token alone. A value that won't parse adds nothing.
+ */
+export function consoleRedactionValues(entry) {
+    if (!entry.broker)
+        return [entry.value];
+    try {
+        return [entry.value, ...brokerScrubValues([{ name: "", value: entry.value, broker: entry.broker }])].filter((v, i, all) => all.indexOf(v) === i);
+    }
+    catch {
+        return [entry.value];
+    }
+}
+function encodedForms(value) {
+    const buf = Buffer.from(value, "utf8");
+    // Query placement goes through URLSearchParams, which encodes ~ ! ' ( ) differently and space as "+",
+    // so both percent-encodings are scrubbed, each also in lowercase-hex form (a response may echo either).
+    const percent = [encodeURIComponent(value), new URLSearchParams({ k: value }).toString().slice("k=".length)];
+    const lowerHex = percent.map((f) => f.replace(/%[0-9A-F]{2}/g, (m) => m.toLowerCase()));
+    return [
+        ...new Set([
+            value,
+            buf.toString("base64"),
+            buf.toString("base64").replace(/=+$/, ""),
+            buf.toString("base64url"),
+            ...percent,
+            ...lowerHex,
+        ]),
+    ]
+        .filter((form) => form.length >= 6)
+        .sort((a, b) => b.length - a.length);
+}
+/** The shared span-union redactor, with this site's marker (every form is already six or more characters). */
+function scrubText(text, forms) {
+    return redactExactSecretValues(text, forms, { marker: REDACTED });
+}
+export function scrubBrokeredResponse(response, values) {
+    // Longest first across every value: a value that prefixes another must not split the longer one.
+    const forms = [...new Set(values.flatMap(encodedForms))].sort((a, b) => b.length - a.length);
+    const body = Buffer.from(response.bodyBase64, "base64").toString("latin1");
+    // latin1 is byte-preserving, so scrubbing never corrupts non-UTF-8 bodies; every encoded form is ASCII,
+    // and a UTF-8 plaintext's bytes appear verbatim in latin1 as the latin1 decode of its UTF-8 bytes.
+    const latinForms = forms.map((f) => Buffer.from(f, "utf8").toString("latin1"));
+    return {
+        ...response,
+        url: scrubText(response.url, forms),
+        ...(response.statusText === undefined ? {} : { statusText: scrubText(response.statusText, forms) }),
+        headers: Object.fromEntries(Object.entries(response.headers).map(([k, v]) => [k, scrubText(v, forms)])),
+        bodyBase64: Buffer.from(scrubText(body, latinForms), "latin1").toString("base64"),
+    };
+}

package/dist/sandbox/tool-capabilities.d.ts

@@ -15,38 +15,18 @@ export declare const MAX_ALLOWED_SHARED_DATASTORES = 16;
 export declare const FETCH_WILDCARD = "*";
 /** Full capability set — used when creating a brand-new attachment (unset fields default to deny-all). */
 export declare const ToolCapabilitiesSchema: z.ZodObject<{
-    allowedSecrets: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
-    allowedDatastorePrefixes: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
-    allowedHosts: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">, string[], string[]>>;
-    allowedSharedDatastorePrefixes: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>, Record<string, string[]>, Record<string, string[]>>>;
-}, "strict", z.ZodTypeAny, {
-    allowedSecrets: string[];
-    allowedDatastorePrefixes: string[];
-    allowedHosts: string[];
-    allowedSharedDatastorePrefixes: Record<string, string[]>;
-}, {
-    allowedSecrets?: string[] | undefined;
-    allowedDatastorePrefixes?: string[] | undefined;
-    allowedHosts?: string[] | undefined;
-    allowedSharedDatastorePrefixes?: Record<string, string[]> | undefined;
-}>;
+    allowedSecrets: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    allowedDatastorePrefixes: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    allowedHosts: z.ZodDefault<z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>, z.ZodTransform<string[], string[]>>>;
+    allowedSharedDatastorePrefixes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
 /** Partial capability set — used when re-declaring capabilities on an attachment that already exists; an omitted field leaves that field untouched. */
 export declare const ToolCapabilitiesPatchSchema: z.ZodObject<{
-    allowedSecrets: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
-    allowedDatastorePrefixes: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>>;
-    allowedHosts: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, "many">, string[], string[]>>;
-    allowedSharedDatastorePrefixes: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>, Record<string, string[]>, Record<string, string[]>>>;
-}, "strict", z.ZodTypeAny, {
-    allowedSecrets?: string[] | undefined;
-    allowedDatastorePrefixes?: string[] | undefined;
-    allowedHosts?: string[] | undefined;
-    allowedSharedDatastorePrefixes?: Record<string, string[]> | undefined;
-}, {
-    allowedSecrets?: string[] | undefined;
-    allowedDatastorePrefixes?: string[] | undefined;
-    allowedHosts?: string[] | undefined;
-    allowedSharedDatastorePrefixes?: Record<string, string[]> | undefined;
-}>;
+    allowedSecrets: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    allowedDatastorePrefixes: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    allowedHosts: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>, z.ZodTransform<string[], string[]>>>;
+    allowedSharedDatastorePrefixes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
 export type ToolCapabilities = z.infer<typeof ToolCapabilitiesSchema>;
 export type ToolCapabilitiesPatch = z.infer<typeof ToolCapabilitiesPatchSchema>;
 /**

package/dist/sandbox/user-tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One user-tool call, end to end: parse the model's arguments, validate them
+ * against the tool's Zod schema (in its own sandbox), run the body, and format
+ * the result string fed back to the model. Never throws — every failure is a
+ * JSON error result. Worker-safe: it touches no database or provider, only the
+ * privileged host it is given, so the native sandbox worker runs it as is.
+ */
+import type { PrivilegedHost } from "./host-functions.js";
+import type { SandboxLimits } from "./eval-core.js";
+export interface UserToolDefinition {
+    code: string;
+    paramsZod: string;
+}
+export declare function runUserToolCall(tool: UserToolDefinition, argsJson: string, privileged: (signal: AbortSignal) => PrivilegedHost, limits?: Partial<SandboxLimits>): Promise<string>;

package/dist/sandbox/user-tool.js

@@ -0,0 +1,32 @@
+/**
+ * One user-tool call, end to end: parse the model's arguments, validate them
+ * against the tool's Zod schema (in its own sandbox), run the body, and format
+ * the result string fed back to the model. Never throws — every failure is a
+ * JSON error result. Worker-safe: it touches no database or provider, only the
+ * privileged host it is given, so the native sandbox worker runs it as is.
+ */
+import { runToolCode } from "./run-in-sandbox.js";
+import { validateParams } from "./zod-params.js";
+export async function runUserToolCall(tool, argsJson, privileged, limits) {
+    let parsedArgs;
+    try {
+        // Some providers stream no JSON delta at all for a zero-parameter
+        // tool call, yielding an empty argsJson rather than "{}".
+        parsedArgs = JSON.parse(argsJson || "{}");
+    }
+    catch (err) {
+        return JSON.stringify({
+            error: "invalid_arguments_json",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const validation = await validateParams(tool.paramsZod, parsedArgs);
+    if (!validation.ok) {
+        return JSON.stringify({ error: "validation_failed", message: validation.errorMessage });
+    }
+    const result = await runToolCode({ code: tool.code, params: validation.value, limits, privileged });
+    if (!result.ok) {
+        return JSON.stringify({ error: result.errorKind, message: result.errorMessage });
+    }
+    return JSON.stringify(result.value);
+}

package/dist/sandbox/zod-params.d.ts

@@ -5,18 +5,50 @@
  * eval (pure computation, no host I/O — `installExtras` is a no-op):
  *
  *  - `deriveJsonSchema`: registration-time. Compiles the schema and derives
- *    its JSON Schema (via the vendored `zod-to-json-schema`) — what's sent
- *    to the model as the tool's `parameters`. A malformed schema fails here,
- *    not at call time.
+ *    its JSON Schema — what's sent to the model as the tool's `parameters`.
+ *    A malformed schema fails here, not at call time.
  *  - `validateParams`: call-time. Compiles the same schema (again, inside
  *    the sandbox) and parses the model-supplied arguments against it.
  *    Zod's own validation error (a real thrown `ZodError`, whose `.message`
  *    is already a readable issue list) becomes the sandbox failure the
  *    engine feeds back to the model as a tool-result error — not a run
  *    failure.
+ *
+ * Zod 3 compatibility window (this release only): wardby itself runs Zod 4,
+ * but a custom tool's paramsZod is still compiled with Zod 4's built-in Zod 3
+ * API (`zod/v3`) first, so a schema written for Zod 3 keeps working exactly as
+ * before, and its JSON Schema comes from zod-to-json-schema (the converter it
+ * was derived with before). Source Zod 3 can't compile (a schema written for
+ * Zod 4, such as one using `z.email()`) falls back to Zod 4, whose JSON Schema
+ * is `z.toJSONSchema` rewritten in zod-to-json-schema's spelling
+ * (core/zod-json-schema.ts). `zod4Compatibility` finds the schemas the next
+ * release, which compiles with Zod 4 only, would break; zod3-window.ts warns
+ * about them. To close the window: set PARAMS_ZOD_APIS to ["v4"], and drop the
+ * Zod 3 bundle (scripts/build-sandbox-vendor.mjs) and the window's warnings.
  */
 import { type SandboxResult } from "./eval-core.js";
+/** A Zod API a tool's paramsZod can compile against. */
+export type ZodApi = "v3" | "v4";
+/** The APIs a tool's paramsZod is compiled with, in order: the first that compiles it is used. */
+export declare const PARAMS_ZOD_APIS: readonly ZodApi[];
 /** Registration-time: compiles the schema source and derives its JSON Schema. */
-export declare function deriveJsonSchema(paramsZodSource: string): Promise<SandboxResult>;
+export declare function deriveJsonSchema(paramsZodSource: string, apis?: readonly ZodApi[]): Promise<SandboxResult>;
 /** Call-time: compiles the schema source and validates the model-supplied args against it. */
-export declare function validateParams(paramsZodSource: string, rawArgs: unknown): Promise<SandboxResult>;
+export declare function validateParams(paramsZodSource: string, rawArgs: unknown, apis?: readonly ZodApi[]): Promise<SandboxResult>;
+export type Zod4Compatibility = {
+    compatible: true;
+}
+/** `removed` lists the removed Zod 3 API it uses (fixed labels); empty when it fails some other way. */
+ | {
+    compatible: false;
+    removed: string[];
+}
+/** The probe hit a sandbox limit, or the source compiles under neither API: nothing to report. */
+ | {
+    compatible: "unknown";
+};
+/**
+ * Whether the source compiles with Zod 4 alone, as it must from the next
+ * release on. Only meaningful for source the current release accepts.
+ */
+export declare function zod4Compatibility(paramsZodSource: string): Promise<Zod4Compatibility>;