@kya-os/contracts 1.8.1 → 1.9.0

package/dist/openclaw/types.d.ts

@@ -0,0 +1,714 @@
+/**
+ * OpenClaw Configuration & Gateway Protocol Types
+ *
+ * Single source of truth for:
+ * 1. openclaw.json config shape (Zod schemas + inferred types)
+ * 2. Gateway Protocol v3 WebSocket frame types (plain interfaces)
+ *
+ * Based on openclaw 2026.2.x config schema.
+ *
+ * @package @kya-os/contracts/openclaw
+ */
+import { z } from "zod";
+/**
+ * Gateway controlUi configuration.
+ * Controls WebSocket access, device auth, and origin allowlisting.
+ */
+export declare const OpenClawControlUiSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    allowInsecureAuth: z.ZodOptional<z.ZodBoolean>;
+    dangerouslyDisableDeviceAuth: z.ZodOptional<z.ZodBoolean>;
+    /** Exact origin strings — no wildcard support */
+    allowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    enabled?: boolean | undefined;
+    allowInsecureAuth?: boolean | undefined;
+    dangerouslyDisableDeviceAuth?: boolean | undefined;
+    allowedOrigins?: string[] | undefined;
+}, {
+    enabled?: boolean | undefined;
+    allowInsecureAuth?: boolean | undefined;
+    dangerouslyDisableDeviceAuth?: boolean | undefined;
+    allowedOrigins?: string[] | undefined;
+}>;
+export type OpenClawControlUi = z.infer<typeof OpenClawControlUiSchema>;
+/**
+ * Gateway configuration.
+ * Key differences from older versions:
+ * - bind is an enum ("lan"|"loopback"|"auto"|"custom"|"tailnet"), not an IP
+ */
+export declare const OpenClawGatewaySchema: z.ZodObject<{
+    mode: z.ZodEnum<["local", "remote"]>;
+    port: z.ZodNumber;
+    bind: z.ZodEnum<["lan", "loopback", "auto", "custom", "tailnet"]>;
+    auth: z.ZodObject<{
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+    }, {
+        token: string;
+    }>;
+    remote: z.ZodOptional<z.ZodObject<{
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+    }, {
+        token: string;
+    }>>;
+    trustedProxies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    controlUi: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        allowInsecureAuth: z.ZodOptional<z.ZodBoolean>;
+        dangerouslyDisableDeviceAuth: z.ZodOptional<z.ZodBoolean>;
+        /** Exact origin strings — no wildcard support */
+        allowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        allowInsecureAuth?: boolean | undefined;
+        dangerouslyDisableDeviceAuth?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        allowInsecureAuth?: boolean | undefined;
+        dangerouslyDisableDeviceAuth?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    mode: "local" | "remote";
+    port: number;
+    bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+    auth: {
+        token: string;
+    };
+    remote?: {
+        token: string;
+    } | undefined;
+    trustedProxies?: string[] | undefined;
+    controlUi?: {
+        enabled?: boolean | undefined;
+        allowInsecureAuth?: boolean | undefined;
+        dangerouslyDisableDeviceAuth?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
+    } | undefined;
+}, {
+    mode: "local" | "remote";
+    port: number;
+    bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+    auth: {
+        token: string;
+    };
+    remote?: {
+        token: string;
+    } | undefined;
+    trustedProxies?: string[] | undefined;
+    controlUi?: {
+        enabled?: boolean | undefined;
+        allowInsecureAuth?: boolean | undefined;
+        dangerouslyDisableDeviceAuth?: boolean | undefined;
+        allowedOrigins?: string[] | undefined;
+    } | undefined;
+}>;
+export type OpenClawGateway = z.infer<typeof OpenClawGatewaySchema>;
+/**
+ * Channel configurations.
+ * - Telegram uses "botToken", Discord uses "token" (not "botToken")
+ * - Slack needs both botToken and appToken
+ */
+export declare const OpenClawChannelsSchema: z.ZodObject<{
+    telegram: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        botToken: z.ZodString;
+        dmPolicy: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        botToken: string;
+        dmPolicy?: string | undefined;
+    }, {
+        enabled: boolean;
+        botToken: string;
+        dmPolicy?: string | undefined;
+    }>>;
+    discord: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        token: z.ZodString;
+        dm: z.ZodOptional<z.ZodObject<{
+            policy: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            policy: string;
+        }, {
+            policy: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        token: string;
+        dm?: {
+            policy: string;
+        } | undefined;
+    }, {
+        enabled: boolean;
+        token: string;
+        dm?: {
+            policy: string;
+        } | undefined;
+    }>>;
+    slack: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        botToken: z.ZodString;
+        appToken: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        appToken: string;
+        botToken: string;
+    }, {
+        enabled: boolean;
+        appToken: string;
+        botToken: string;
+    }>>;
+    whatsapp: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    telegram?: {
+        enabled: boolean;
+        botToken: string;
+        dmPolicy?: string | undefined;
+    } | undefined;
+    discord?: {
+        enabled: boolean;
+        token: string;
+        dm?: {
+            policy: string;
+        } | undefined;
+    } | undefined;
+    slack?: {
+        enabled: boolean;
+        appToken: string;
+        botToken: string;
+    } | undefined;
+    whatsapp?: Record<string, unknown> | undefined;
+}, {
+    telegram?: {
+        enabled: boolean;
+        botToken: string;
+        dmPolicy?: string | undefined;
+    } | undefined;
+    discord?: {
+        enabled: boolean;
+        token: string;
+        dm?: {
+            policy: string;
+        } | undefined;
+    } | undefined;
+    slack?: {
+        enabled: boolean;
+        appToken: string;
+        botToken: string;
+    } | undefined;
+    whatsapp?: Record<string, unknown> | undefined;
+}>;
+export type OpenClawChannels = z.infer<typeof OpenClawChannelsSchema>;
+/**
+ * A single model definition within a provider.
+ */
+export declare const OpenClawModelSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    contextWindow: z.ZodNumber;
+    maxTokens: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+}, {
+    name: string;
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+}>;
+export type OpenClawModel = z.infer<typeof OpenClawModelSchema>;
+/**
+ * AI model provider definition.
+ * Tells OpenClaw how to reach an AI provider (e.g. OpenAI, custom endpoint).
+ */
+export declare const OpenClawModelProviderSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
+    api: z.ZodString;
+    models: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        contextWindow: z.ZodNumber;
+        maxTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        contextWindow: number;
+        maxTokens: number;
+    }, {
+        name: string;
+        id: string;
+        contextWindow: number;
+        maxTokens: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    baseUrl: string;
+    api: string;
+    models: {
+        name: string;
+        id: string;
+        contextWindow: number;
+        maxTokens: number;
+    }[];
+    apiKey?: string | undefined;
+}, {
+    baseUrl: string;
+    api: string;
+    models: {
+        name: string;
+        id: string;
+        contextWindow: number;
+        maxTokens: number;
+    }[];
+    apiKey?: string | undefined;
+}>;
+export type OpenClawModelProvider = z.infer<typeof OpenClawModelProviderSchema>;
+/**
+ * Full openclaw.json configuration.
+ *
+ * AI provider keys go in `env` (flat record), not a top-level "ai" key.
+ * The `agents.defaults.model.primary` field sets the default model.
+ */
+export declare const OpenClawConfigSchema: z.ZodObject<{
+    gateway: z.ZodObject<{
+        mode: z.ZodEnum<["local", "remote"]>;
+        port: z.ZodNumber;
+        bind: z.ZodEnum<["lan", "loopback", "auto", "custom", "tailnet"]>;
+        auth: z.ZodObject<{
+            token: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+        }, {
+            token: string;
+        }>;
+        remote: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+        }, {
+            token: string;
+        }>>;
+        trustedProxies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        controlUi: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodBoolean>;
+            allowInsecureAuth: z.ZodOptional<z.ZodBoolean>;
+            dangerouslyDisableDeviceAuth: z.ZodOptional<z.ZodBoolean>;
+            /** Exact origin strings — no wildcard support */
+            allowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "local" | "remote";
+        port: number;
+        bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+        auth: {
+            token: string;
+        };
+        remote?: {
+            token: string;
+        } | undefined;
+        trustedProxies?: string[] | undefined;
+        controlUi?: {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+    }, {
+        mode: "local" | "remote";
+        port: number;
+        bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+        auth: {
+            token: string;
+        };
+        remote?: {
+            token: string;
+        } | undefined;
+        trustedProxies?: string[] | undefined;
+        controlUi?: {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+    }>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    channels: z.ZodOptional<z.ZodObject<{
+        telegram: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            botToken: z.ZodString;
+            dmPolicy: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        }, {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        }>>;
+        discord: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            token: z.ZodString;
+            dm: z.ZodOptional<z.ZodObject<{
+                policy: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                policy: string;
+            }, {
+                policy: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        }, {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        }>>;
+        slack: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            botToken: z.ZodString;
+            appToken: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        }, {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        }>>;
+        whatsapp: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        telegram?: {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        } | undefined;
+        discord?: {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        } | undefined;
+        slack?: {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        } | undefined;
+        whatsapp?: Record<string, unknown> | undefined;
+    }, {
+        telegram?: {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        } | undefined;
+        discord?: {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        } | undefined;
+        slack?: {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        } | undefined;
+        whatsapp?: Record<string, unknown> | undefined;
+    }>>;
+    agents: z.ZodOptional<z.ZodObject<{
+        defaults: z.ZodOptional<z.ZodObject<{
+            model: z.ZodOptional<z.ZodObject<{
+                primary: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                primary: string;
+            }, {
+                primary: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            model?: {
+                primary: string;
+            } | undefined;
+        }, {
+            model?: {
+                primary: string;
+            } | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        defaults?: {
+            model?: {
+                primary: string;
+            } | undefined;
+        } | undefined;
+    }, {
+        defaults?: {
+            model?: {
+                primary: string;
+            } | undefined;
+        } | undefined;
+    }>>;
+    models: z.ZodOptional<z.ZodObject<{
+        providers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            baseUrl: z.ZodString;
+            apiKey: z.ZodOptional<z.ZodString>;
+            api: z.ZodString;
+            models: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                contextWindow: z.ZodNumber;
+                maxTokens: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }, {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        providers?: Record<string, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }> | undefined;
+    }, {
+        providers?: Record<string, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    gateway: {
+        mode: "local" | "remote";
+        port: number;
+        bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+        auth: {
+            token: string;
+        };
+        remote?: {
+            token: string;
+        } | undefined;
+        trustedProxies?: string[] | undefined;
+        controlUi?: {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+    };
+    channels?: {
+        telegram?: {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        } | undefined;
+        discord?: {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        } | undefined;
+        slack?: {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        } | undefined;
+        whatsapp?: Record<string, unknown> | undefined;
+    } | undefined;
+    models?: {
+        providers?: Record<string, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }> | undefined;
+    } | undefined;
+    env?: Record<string, string> | undefined;
+    agents?: {
+        defaults?: {
+            model?: {
+                primary: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    gateway: {
+        mode: "local" | "remote";
+        port: number;
+        bind: "custom" | "lan" | "loopback" | "auto" | "tailnet";
+        auth: {
+            token: string;
+        };
+        remote?: {
+            token: string;
+        } | undefined;
+        trustedProxies?: string[] | undefined;
+        controlUi?: {
+            enabled?: boolean | undefined;
+            allowInsecureAuth?: boolean | undefined;
+            dangerouslyDisableDeviceAuth?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+    };
+    channels?: {
+        telegram?: {
+            enabled: boolean;
+            botToken: string;
+            dmPolicy?: string | undefined;
+        } | undefined;
+        discord?: {
+            enabled: boolean;
+            token: string;
+            dm?: {
+                policy: string;
+            } | undefined;
+        } | undefined;
+        slack?: {
+            enabled: boolean;
+            appToken: string;
+            botToken: string;
+        } | undefined;
+        whatsapp?: Record<string, unknown> | undefined;
+    } | undefined;
+    models?: {
+        providers?: Record<string, {
+            baseUrl: string;
+            api: string;
+            models: {
+                name: string;
+                id: string;
+                contextWindow: number;
+                maxTokens: number;
+            }[];
+            apiKey?: string | undefined;
+        }> | undefined;
+    } | undefined;
+    env?: Record<string, string> | undefined;
+    agents?: {
+        defaults?: {
+            model?: {
+                primary: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+export type OpenClawConfig = z.infer<typeof OpenClawConfigSchema>;
+/**
+ * RPC request frame sent to the OpenClaw gateway.
+ */
+export interface OpenClawRpcRequest {
+    type: "req";
+    id: string;
+    method: string;
+    params?: unknown;
+}
+/**
+ * RPC response frame received from the OpenClaw gateway.
+ */
+export interface OpenClawRpcResponse {
+    type: "res";
+    id: string;
+    ok: boolean;
+    payload?: unknown;
+    error?: unknown;
+}
+/**
+ * Event frame pushed by the OpenClaw gateway.
+ */
+export interface OpenClawEvent {
+    type: "event";
+    event: string;
+    payload?: unknown;
+}
+/**
+ * Discriminated union of all v3 WebSocket frame types.
+ */
+export type OpenClawFrame = OpenClawRpcRequest | OpenClawRpcResponse | OpenClawEvent;
+/**
+ * Payload shape of the `hello-ok` response after a successful
+ * `connect` RPC handshake. Parsed defensively — fields are optional.
+ */
+export interface OpenClawHelloOkPayload {
+    gateway?: {
+        version?: string;
+        mode?: string;
+        features?: string[];
+    };
+    health?: {
+        channels?: Record<string, {
+            connected: boolean;
+            error?: string;
+        }>;
+    };
+    agent?: {
+        id?: string;
+        name?: string;
+    };
+}