@osovv/vv-opencode 1.4.5 → 1.6.0

package/dist/plugins/web-tools/schemas.d.ts

@@ -0,0 +1,469 @@
+import type { z, ZodRawShape } from "zod";
+import { type ContractIssue, type OwnedToolContract } from "../../lib/agent-tool-contract.js";
+/** Registered tool id for provider-neutral web search. */
+export declare const WEB_SEARCH_TOOL_ID = "web_search";
+/** Registered tool id for provider-neutral web fetch. */
+export declare const WEB_FETCH_TOOL_ID = "web_fetch";
+/** Canonical search provider vocabulary. */
+export declare const WEB_SEARCH_PROVIDERS: readonly ["exa", "brave", "zai"];
+/** Canonical fetch provider vocabulary. */
+export declare const WEB_FETCH_PROVIDERS: readonly ["native", "spider", "zai"];
+/** Credential provenance vocabulary reported in result metadata. */
+export declare const WEB_CREDENTIAL_SOURCES: readonly ["env", "config"];
+/** Canonical Z.AI region vocabulary (matches the canonical vvoc web region enum). */
+export declare const WEB_REGIONS: readonly ["international", "china"];
+/** Union of supported Z.AI region identifiers. */
+export type WebRegion = (typeof WEB_REGIONS)[number];
+/** Canonical freshness window vocabulary. */
+export declare const SEARCH_FRESHNESS_WINDOWS: readonly ["day", "week", "month", "year"];
+/** Union of supported freshness window identifiers. */
+export type WebSearchFreshness = (typeof SEARCH_FRESHNESS_WINDOWS)[number];
+/** Canonical textual output format vocabulary. */
+export declare const FETCH_FORMATS: readonly ["markdown", "text", "html"];
+/** Union of supported textual output format identifiers. */
+export type WebFetchFormat = (typeof FETCH_FORMATS)[number];
+/** Default result count. */
+export declare const WEB_SEARCH_DEFAULT_COUNT = 8;
+/** Minimum result count. */
+export declare const WEB_SEARCH_MIN_COUNT = 1;
+/** Maximum result count. */
+export declare const WEB_SEARCH_MAX_COUNT = 20;
+/** Default per-call timeout in seconds. */
+export declare const WEB_FETCH_DEFAULT_TIMEOUT_SECONDS = 30;
+/** Maximum model-configurable timeout in seconds. */
+export declare const WEB_FETCH_MAX_TIMEOUT_SECONDS = 120;
+/**
+ * Registered raw argument map for web_search (single source of the tool surface).
+ * Provider-neutral: no credential, provider, or region arguments are accepted.
+ * count carries a representable 1..20 integer bound and the documented default;
+ * the execute boundary re-applies the default because the host forwards raw args.
+ */
+export declare const webSearchArgs: {
+    query: z.ZodString;
+    count: z.ZodDefault<z.ZodNumber>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>>;
+};
+declare const webSearchArgsObject: z.ZodObject<{
+    query: z.ZodString;
+    count: z.ZodDefault<z.ZodNumber>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>>;
+}, z.core.$strip>;
+/** web_search argument shape with defaults applied, single-sourced from the registered schema. */
+export type WebSearchToolArgs = z.infer<typeof webSearchArgsObject>;
+/**
+ * Registered raw argument map for web_fetch (single source of the tool surface).
+ * Provider-neutral: no credential or provider arguments are accepted.
+ * format and timeout carry the documented defaults; the execute boundary re-applies
+ * them because the host forwards raw args. A provider may drop the numeric bound
+ * during schema lowering, so the positive/maximum rule stays runtime-enforced.
+ */
+export declare const webFetchArgs: {
+    url: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+};
+declare const webFetchArgsObject: z.ZodObject<{
+    url: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** web_fetch argument shape with defaults applied, single-sourced from the registered schema. */
+export type WebFetchToolArgs = z.infer<typeof webFetchArgsObject>;
+/** Owned contract for web_search. */
+export declare const webSearchContract: OwnedToolContract<{
+    query: z.ZodString;
+    count: z.ZodDefault<z.ZodNumber>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>>;
+}>;
+/** Owned contract for web_fetch. */
+export declare const webFetchContract: OwnedToolContract<{
+    url: z.ZodString;
+    format: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>>;
+    timeout: z.ZodDefault<z.ZodNumber>;
+}>;
+/** Owned contracts for both web tools (input to the owned definition/pre-execute adapters). */
+export declare const webToolContracts: readonly OwnedToolContract<ZodRawShape>[];
+/** Successful parsed search args or bounded structural issues. */
+export type WebSearchValidation = {
+    ok: true;
+    data: WebSearchToolArgs;
+} | {
+    ok: false;
+    issues: readonly ContractIssue[];
+};
+/** Successful parsed fetch args or bounded structural/URL issues. */
+export type WebFetchValidation = {
+    ok: true;
+    data: WebFetchToolArgs;
+} | {
+    ok: false;
+    issues: readonly ContractIssue[];
+};
+/**
+ * Strict structural validation for web_search.
+ * Unknown root keys, malformed provided values, unsupported freshness windows, and
+ * out-of-bounds counts reject; the documented count default is applied for execute.
+ * The query text is preserved verbatim.
+ */
+export declare function validateWebSearchToolInput(raw: unknown): WebSearchValidation;
+/**
+ * Strict structural plus URL scheme/shape validation for web_fetch.
+ * Structural failures reject first; then the URL must parse as an absolute HTTP or
+ * HTTPS URL. Diagnostics identify the offending `url` field with a bounded message
+ * that never echoes the raw URL (which may carry credentials) or an error payload.
+ * The format and timeout defaults are applied for execute.
+ */
+export declare function validateWebFetchToolInput(raw: unknown): WebFetchValidation;
+/**
+ * Closed search metadata schemas for the actual delivery variants.
+ * `region` is present only for the direct Z.AI provider; unknown fields and
+ * missing known fields reject.
+ */
+export declare const webSearchMetadataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodLiteral<"exa">;
+    resultCount: z.ZodNumber;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"brave">;
+    resultCount: z.ZodNumber;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"zai">;
+    region: z.ZodEnum<{
+        international: "international";
+        china: "china";
+    }>;
+    resultCount: z.ZodNumber;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+}, z.core.$strip>]>;
+/**
+ * Closed result envelope for web_search producer/test checks.
+ * `output` is the rendered Markdown document and stays a declared opaque string.
+ * This is never applied as a throw-after-side-effect execute wrapper.
+ */
+export declare const webSearchResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    output: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"exa">;
+        resultCount: z.ZodNumber;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"brave">;
+        resultCount: z.ZodNumber;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"zai">;
+        region: z.ZodEnum<{
+            international: "international";
+            china: "china";
+        }>;
+        resultCount: z.ZodNumber;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+/**
+ * Closed fetch metadata schemas for the actual provider/delivery variants.
+ * Native reports its status; Spider may add status/duration; Z.AI reader text
+ * carries its regional request metadata while direct Z.AI media reports only the
+ * region/format/credential provenance. Region is required for every Z.AI variant.
+ */
+export declare const webFetchMetadataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodLiteral<"native">;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>;
+    status: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"spider">;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+    status: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"zai">;
+    region: z.ZodEnum<{
+        international: "international";
+        china: "china";
+    }>;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+    status: z.ZodNumber;
+    requestId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    provider: z.ZodLiteral<"zai">;
+    region: z.ZodEnum<{
+        international: "international";
+        china: "china";
+    }>;
+    format: z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>;
+    credentialSource: z.ZodEnum<{
+        config: "config";
+        env: "env";
+    }>;
+}, z.core.$strip>]>;
+/** Closed textual fetch result envelope producer schema (no attachments region). */
+export declare const webFetchTextResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    output: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"native">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        status: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"spider">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"zai">;
+        region: z.ZodEnum<{
+            international: "international";
+            china: "china";
+        }>;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodNumber;
+        requestId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        created: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+/** Closed media fetch result envelope producer schema requiring a real attachment. */
+export declare const webFetchMediaResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    output: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"native">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        status: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"spider">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"zai">;
+        region: z.ZodEnum<{
+            international: "international";
+            china: "china";
+        }>;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+    }, z.core.$strip>]>;
+    attachments: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        mime: z.ZodString;
+        url: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Closed fetch result envelope union for producer/test checks. */
+export declare const webFetchResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    title: z.ZodString;
+    output: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"native">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        status: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"spider">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"zai">;
+        region: z.ZodEnum<{
+            international: "international";
+            china: "china";
+        }>;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodNumber;
+        requestId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        created: z.ZodOptional<z.ZodNumber>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+}, z.core.$strip>, z.ZodObject<{
+    title: z.ZodString;
+    output: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodLiteral<"native">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        status: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"spider">;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+        status: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        provider: z.ZodLiteral<"zai">;
+        region: z.ZodEnum<{
+            international: "international";
+            china: "china";
+        }>;
+        format: z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>;
+        credentialSource: z.ZodEnum<{
+            config: "config";
+            env: "env";
+        }>;
+    }, z.core.$strip>]>;
+    attachments: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        mime: z.ZodString;
+        url: z.ZodString;
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+/** Schema-derived search result envelope. */
+export type WebSearchResultEnvelope = z.infer<typeof webSearchResultSchema>;
+/** Schema-derived fetch result envelope. */
+export type WebFetchResultEnvelope = z.infer<typeof webFetchResultSchema>;
+/** Schema-derived search metadata union. */
+export type WebSearchMetadata = z.infer<typeof webSearchMetadataSchema>;
+/** Schema-derived fetch metadata union. */
+export type WebFetchMetadata = z.infer<typeof webFetchMetadataSchema>;
+export {};