@keyueclaw/web-sdk 0.1.84 → 0.1.85

package/dist/src/config/types.base.d.ts

@@ -0,0 +1,216 @@
+import type { ChatType } from "../channels/chat-type.js";
+export type ReplyMode = "text" | "command";
+export type TypingMode = "never" | "instant" | "thinking" | "message";
+export type SessionScope = "per-sender" | "global";
+export type DmScope = "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer";
+export type ReplyToMode = "off" | "first" | "all";
+export type GroupPolicy = "open" | "disabled" | "allowlist";
+export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
+export type OutboundRetryConfig = {
+    /** Max retry attempts for outbound requests (default: 3). */
+    attempts?: number;
+    /** Minimum retry delay in ms (default: 300-500ms depending on provider). */
+    minDelayMs?: number;
+    /** Maximum retry delay cap in ms (default: 30000). */
+    maxDelayMs?: number;
+    /** Jitter factor (0-1) applied to delays (default: 0.1). */
+    jitter?: number;
+};
+export type BlockStreamingCoalesceConfig = {
+    minChars?: number;
+    maxChars?: number;
+    idleMs?: number;
+};
+export type BlockStreamingChunkConfig = {
+    minChars?: number;
+    maxChars?: number;
+    breakPreference?: "paragraph" | "newline" | "sentence";
+};
+export type MarkdownTableMode = "off" | "bullets" | "code";
+export type MarkdownConfig = {
+    /** Table rendering mode (off|bullets|code). */
+    tables?: MarkdownTableMode;
+};
+export type HumanDelayConfig = {
+    /** Delay style for block replies (off|natural|custom). */
+    mode?: "off" | "natural" | "custom";
+    /** Minimum delay in milliseconds (default: 800). */
+    minMs?: number;
+    /** Maximum delay in milliseconds (default: 2500). */
+    maxMs?: number;
+};
+export type SessionSendPolicyAction = "allow" | "deny";
+export type SessionSendPolicyMatch = {
+    channel?: string;
+    chatType?: ChatType;
+    /**
+     * Session key prefix match.
+     * Note: some consumers match against a normalized key (for example, stripping `agent:<id>:`).
+     */
+    keyPrefix?: string;
+    /** Optional raw session-key prefix match for consumers that normalize session keys. */
+    rawKeyPrefix?: string;
+};
+export type SessionSendPolicyRule = {
+    action: SessionSendPolicyAction;
+    match?: SessionSendPolicyMatch;
+};
+export type SessionSendPolicyConfig = {
+    default?: SessionSendPolicyAction;
+    rules?: SessionSendPolicyRule[];
+};
+export type SessionResetMode = "daily" | "idle";
+export type SessionResetConfig = {
+    mode?: SessionResetMode;
+    /** Local hour (0-23) for the daily reset boundary. */
+    atHour?: number;
+    /** Sliding idle window (minutes). When set with daily mode, whichever expires first wins. */
+    idleMinutes?: number;
+};
+export type SessionResetByTypeConfig = {
+    direct?: SessionResetConfig;
+    /** @deprecated Use `direct` instead. Kept for backward compatibility. */
+    dm?: SessionResetConfig;
+    group?: SessionResetConfig;
+    thread?: SessionResetConfig;
+};
+export type SessionThreadBindingsConfig = {
+    /**
+     * Master switch for thread-bound session routing features.
+     * Channel/provider keys can override this default.
+     */
+    enabled?: boolean;
+    /**
+     * Inactivity window for thread-bound sessions (hours).
+     * Session auto-unfocuses after this amount of idle time. Set to 0 to disable. Default: 24.
+     */
+    idleHours?: number;
+    /**
+     * Optional hard max age for thread-bound sessions (hours).
+     * Session auto-unfocuses once this age is reached even if active. Set to 0 to disable. Default: 0.
+     */
+    maxAgeHours?: number;
+};
+export type SessionConfig = {
+    scope?: SessionScope;
+    /** DM session scoping (default: "main"). */
+    dmScope?: DmScope;
+    /** Map platform-prefixed identities (e.g. "telegram:123") to canonical DM peers. */
+    identityLinks?: Record<string, string[]>;
+    resetTriggers?: string[];
+    idleMinutes?: number;
+    reset?: SessionResetConfig;
+    resetByType?: SessionResetByTypeConfig;
+    /** Channel-specific reset overrides (e.g. { discord: { mode: "idle", idleMinutes: 10080 } }). */
+    resetByChannel?: Record<string, SessionResetConfig>;
+    store?: string;
+    typingIntervalSeconds?: number;
+    typingMode?: TypingMode;
+    /**
+     * Max parent transcript token count allowed for thread/session forking.
+     * If parent totalTokens is above this value, OpenClaw skips parent fork and
+     * starts a fresh thread session instead. Set to 0 to disable this guard.
+     */
+    parentForkMaxTokens?: number;
+    mainKey?: string;
+    sendPolicy?: SessionSendPolicyConfig;
+    agentToAgent?: {
+        /** Max ping-pong turns between requester/target (0–5). Default: 5. */
+        maxPingPongTurns?: number;
+    };
+    /** Shared defaults for thread-bound session routing across channels/providers. */
+    threadBindings?: SessionThreadBindingsConfig;
+    /** Automatic session store maintenance (pruning, capping, file rotation). */
+    maintenance?: SessionMaintenanceConfig;
+};
+export type SessionMaintenanceMode = "enforce" | "warn";
+export type SessionMaintenanceConfig = {
+    /** Whether to enforce maintenance or warn only. Default: "warn". */
+    mode?: SessionMaintenanceMode;
+    /** Remove session entries older than this duration (e.g. "30d", "12h"). Default: "30d". */
+    pruneAfter?: string | number;
+    /** Deprecated. Use pruneAfter instead. */
+    pruneDays?: number;
+    /** Maximum number of session entries to keep. Default: 500. */
+    maxEntries?: number;
+    /** Rotate sessions.json when it exceeds this size (e.g. "10mb"). Default: 10mb. */
+    rotateBytes?: number | string;
+    /**
+     * Retention for archived reset transcripts (`*.reset.<timestamp>`).
+     * Set `false` to disable reset-archive cleanup. Default: same as `pruneAfter` (30d).
+     */
+    resetArchiveRetention?: string | number | false;
+    /**
+     * Optional per-agent sessions-directory disk budget (e.g. "500mb").
+     * When exceeded, warn (mode=warn) or enforce oldest-first cleanup (mode=enforce).
+     */
+    maxDiskBytes?: number | string;
+    /**
+     * Target size after disk-budget cleanup (high-water mark), e.g. "400mb".
+     * Default: 80% of maxDiskBytes.
+     */
+    highWaterBytes?: number | string;
+};
+export type LoggingConfig = {
+    level?: "silent" | "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+    file?: string;
+    /** Maximum size of a single log file in bytes before writes are suppressed. Default: 500 MB. */
+    maxFileBytes?: number;
+    consoleLevel?: "silent" | "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+    consoleStyle?: "pretty" | "compact" | "json";
+    /** Redact sensitive tokens in tool summaries. Default: "tools". */
+    redactSensitive?: "off" | "tools";
+    /** Regex patterns used to redact sensitive tokens (defaults apply when unset). */
+    redactPatterns?: string[];
+};
+export type DiagnosticsOtelConfig = {
+    enabled?: boolean;
+    endpoint?: string;
+    protocol?: "http/protobuf" | "grpc";
+    headers?: Record<string, string>;
+    serviceName?: string;
+    traces?: boolean;
+    metrics?: boolean;
+    logs?: boolean;
+    /** Trace sample rate (0.0 - 1.0). */
+    sampleRate?: number;
+    /** Metric export interval (ms). */
+    flushIntervalMs?: number;
+};
+export type DiagnosticsCacheTraceConfig = {
+    enabled?: boolean;
+    filePath?: string;
+    includeMessages?: boolean;
+    includePrompt?: boolean;
+    includeSystem?: boolean;
+};
+export type DiagnosticsConfig = {
+    enabled?: boolean;
+    /** Optional ad-hoc diagnostics flags (e.g. "telegram.http"). */
+    flags?: string[];
+    /** Threshold in ms before a processing session logs "stuck session" diagnostics. */
+    stuckSessionWarnMs?: number;
+    otel?: DiagnosticsOtelConfig;
+    cacheTrace?: DiagnosticsCacheTraceConfig;
+};
+export type WebReconnectConfig = {
+    initialMs?: number;
+    maxMs?: number;
+    factor?: number;
+    jitter?: number;
+    maxAttempts?: number;
+};
+export type WebConfig = {
+    /** If false, do not start the WhatsApp web provider. Default: true. */
+    enabled?: boolean;
+    heartbeatSeconds?: number;
+    reconnect?: WebReconnectConfig;
+};
+export type AgentElevatedAllowFromConfig = Partial<Record<string, Array<string | number>>>;
+export type IdentityConfig = {
+    name?: string;
+    theme?: string;
+    emoji?: string;
+    /** Avatar image: workspace-relative path, http(s) URL, or data URI. */
+    avatar?: string;
+};

package/dist/src/config/types.browser.d.ts

@@ -0,0 +1,71 @@
+export type BrowserProfileConfig = {
+    /** CDP port for this profile. Allocated once at creation, persisted permanently. */
+    cdpPort?: number;
+    /** CDP URL for this profile (use for remote Chrome). */
+    cdpUrl?: string;
+    /** Explicit user data directory for existing-session Chrome MCP attachment. */
+    userDataDir?: string;
+    /** Profile driver (default: openclaw). */
+    driver?: "openclaw" | "clawd" | "existing-session";
+    /** If true, never launch a browser for this profile; only attach. Falls back to browser.attachOnly. */
+    attachOnly?: boolean;
+    /** Profile color (hex). Auto-assigned at creation. */
+    color: string;
+};
+export type BrowserSnapshotDefaults = {
+    /** Default snapshot mode (applies when mode is not provided). */
+    mode?: "efficient";
+};
+export type BrowserSsrFPolicyConfig = {
+    /** Legacy alias for private-network access. Prefer dangerouslyAllowPrivateNetwork. */
+    allowPrivateNetwork?: boolean;
+    /** If true, permit browser navigation to private/internal networks. Default: true */
+    dangerouslyAllowPrivateNetwork?: boolean;
+    /**
+     * Explicitly allowed hostnames (exact-match), including blocked names like localhost.
+     * Example: ["localhost", "metadata.internal"]
+     */
+    allowedHostnames?: string[];
+    /**
+     * Hostname allowlist patterns for browser navigation.
+     * Supports exact hosts and "*.example.com" wildcard subdomains.
+     */
+    hostnameAllowlist?: string[];
+};
+export type BrowserConfig = {
+    enabled?: boolean;
+    /** If false, disable browser act:evaluate (arbitrary JS). Default: true */
+    evaluateEnabled?: boolean;
+    /** Base URL of the CDP endpoint (for remote browsers). Default: loopback CDP on the derived port. */
+    cdpUrl?: string;
+    /** Remote CDP HTTP timeout (ms). Default: 1500. */
+    remoteCdpTimeoutMs?: number;
+    /** Remote CDP WebSocket handshake timeout (ms). Default: max(remoteCdpTimeoutMs * 2, 2000). */
+    remoteCdpHandshakeTimeoutMs?: number;
+    /** Accent color for the openclaw browser profile (hex). Default: #FF4500 */
+    color?: string;
+    /** Override the browser executable path (all platforms). */
+    executablePath?: string;
+    /** Start Chrome headless (best-effort). Default: false */
+    headless?: boolean;
+    /** Pass --no-sandbox to Chrome (Linux containers). Default: false */
+    noSandbox?: boolean;
+    /** If true: never launch; only attach to an existing browser. Default: false */
+    attachOnly?: boolean;
+    /** Starting local CDP port for auto-assigned browser profiles. Default derives from gateway port. */
+    cdpPortRangeStart?: number;
+    /** Default profile to use when profile param is omitted. Default: "chrome" */
+    defaultProfile?: string;
+    /** Named browser profiles with explicit CDP ports or URLs. */
+    profiles?: Record<string, BrowserProfileConfig>;
+    /** Default snapshot options (applied by the browser tool/CLI when unset). */
+    snapshotDefaults?: BrowserSnapshotDefaults;
+    /** SSRF policy for browser navigation/open-tab operations. */
+    ssrfPolicy?: BrowserSsrFPolicyConfig;
+    /**
+     * Additional Chrome launch arguments.
+     * Useful for stealth flags, window size overrides, or custom user-agent strings.
+     * Example: ["--window-size=1920,1080", "--disable-infobars"]
+     */
+    extraArgs?: string[];
+};

package/dist/src/config/types.channel-messaging-common.d.ts

@@ -0,0 +1,46 @@
+import type { BlockStreamingCoalesceConfig, DmPolicy, GroupPolicy, MarkdownConfig } from "./types.base.js";
+import type { ChannelHealthMonitorConfig, ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
+import type { DmConfig } from "./types.messages.js";
+export type CommonChannelMessagingConfig = {
+    /** Optional display name for this account (used in CLI/UI lists). */
+    name?: string;
+    /** Optional provider capability tags used for agent/runtime guidance. */
+    capabilities?: string[];
+    /** Markdown formatting overrides (tables). */
+    markdown?: MarkdownConfig;
+    /** Allow channel-initiated config writes (default: true). */
+    configWrites?: boolean;
+    /** If false, do not start this account. Default: true. */
+    enabled?: boolean;
+    /** Direct message access policy (default: pairing). */
+    dmPolicy?: DmPolicy;
+    /** Optional allowlist for inbound DM senders. */
+    allowFrom?: Array<string | number>;
+    /** Default delivery target for CLI --deliver when no explicit --reply-to is provided. */
+    defaultTo?: string;
+    /** Optional allowlist for group/channel senders. */
+    groupAllowFrom?: Array<string | number>;
+    /** Group/channel message handling policy. */
+    groupPolicy?: GroupPolicy;
+    /** Max group/channel messages to keep as history context (0 disables). */
+    historyLimit?: number;
+    /** Max DM turns to keep as history context. */
+    dmHistoryLimit?: number;
+    /** Per-DM config overrides keyed by sender ID. */
+    dms?: Record<string, DmConfig>;
+    /** Outbound text chunk size (chars). */
+    textChunkLimit?: number;
+    /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
+    chunkMode?: "length" | "newline";
+    blockStreaming?: boolean;
+    /** Merge streamed block replies before sending. */
+    blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+    /** Heartbeat visibility settings for this channel. */
+    heartbeat?: ChannelHeartbeatVisibilityConfig;
+    /** Channel health monitor overrides for this channel/account. */
+    healthMonitor?: ChannelHealthMonitorConfig;
+    /** Outbound response prefix override for this channel/account. */
+    responsePrefix?: string;
+    /** Max outbound media size in MB. */
+    mediaMaxMb?: number;
+};

package/dist/src/config/types.channels.d.ts

@@ -0,0 +1,63 @@
+import type { GroupPolicy } from "./types.base.js";
+import type { DiscordConfig } from "./types.discord.js";
+import type { GoogleChatConfig } from "./types.googlechat.js";
+import type { IMessageConfig } from "./types.imessage.js";
+import type { IrcConfig } from "./types.irc.js";
+import type { MSTeamsConfig } from "./types.msteams.js";
+import type { SignalConfig } from "./types.signal.js";
+import type { SlackConfig } from "./types.slack.js";
+import type { TelegramConfig } from "./types.telegram.js";
+import type { WhatsAppConfig } from "./types.whatsapp.js";
+export type ChannelHeartbeatVisibilityConfig = {
+    /** Show HEARTBEAT_OK acknowledgments in chat (default: false). */
+    showOk?: boolean;
+    /** Show heartbeat alerts with actual content (default: true). */
+    showAlerts?: boolean;
+    /** Emit indicator events for UI status display (default: true). */
+    useIndicator?: boolean;
+};
+export type ChannelHealthMonitorConfig = {
+    /**
+     * Enable channel-health-monitor restarts for this channel or account.
+     * Inherits the global gateway setting when omitted.
+     */
+    enabled?: boolean;
+};
+export type ChannelDefaultsConfig = {
+    groupPolicy?: GroupPolicy;
+    /** Default heartbeat visibility for all channels. */
+    heartbeat?: ChannelHeartbeatVisibilityConfig;
+};
+export type ChannelModelByChannelConfig = Record<string, Record<string, string>>;
+/**
+ * Base type for extension channel config sections.
+ * Extensions can use this as a starting point for their channel config.
+ */
+export type ExtensionChannelConfig = {
+    enabled?: boolean;
+    allowFrom?: string | string[];
+    /** Default delivery target for CLI --deliver when no explicit --reply-to is provided. */
+    defaultTo?: string;
+    /** Optional default account id when multiple accounts are configured. */
+    defaultAccount?: string;
+    dmPolicy?: string;
+    groupPolicy?: GroupPolicy;
+    healthMonitor?: ChannelHealthMonitorConfig;
+    accounts?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export type ChannelsConfig = {
+    defaults?: ChannelDefaultsConfig;
+    /** Map provider -> channel id -> model override. */
+    modelByChannel?: ChannelModelByChannelConfig;
+    whatsapp?: WhatsAppConfig;
+    telegram?: TelegramConfig;
+    discord?: DiscordConfig;
+    irc?: IrcConfig;
+    googlechat?: GoogleChatConfig;
+    slack?: SlackConfig;
+    signal?: SignalConfig;
+    imessage?: IMessageConfig;
+    msteams?: MSTeamsConfig;
+    [key: string]: any;
+};

package/dist/src/config/types.cli.d.ts

@@ -0,0 +1,12 @@
+export type CliBannerTaglineMode = "random" | "default" | "off";
+export type CliConfig = {
+    banner?: {
+        /**
+         * Controls CLI banner tagline behavior.
+         * - "random": pick from tagline pool (default)
+         * - "default": always use DEFAULT_TAGLINE
+         * - "off": hide tagline text
+         */
+        taglineMode?: CliBannerTaglineMode;
+    };
+};

package/dist/src/config/types.cron.d.ts

@@ -0,0 +1,55 @@
+import type { SecretInput } from "./types.secrets.js";
+/** Error types that can trigger retries for one-shot jobs. */
+export type CronRetryOn = "rate_limit" | "overloaded" | "network" | "timeout" | "server_error";
+export type CronRetryConfig = {
+    /** Max retries for transient errors before permanent disable (default: 3). */
+    maxAttempts?: number;
+    /** Backoff delays in ms for each retry attempt (default: [30000, 60000, 300000]). */
+    backoffMs?: number[];
+    /** Error types to retry; omit to retry all transient types. */
+    retryOn?: CronRetryOn[];
+};
+export type CronFailureAlertConfig = {
+    enabled?: boolean;
+    after?: number;
+    cooldownMs?: number;
+    mode?: "announce" | "webhook";
+    accountId?: string;
+};
+export type CronFailureDestinationConfig = {
+    channel?: string;
+    to?: string;
+    accountId?: string;
+    mode?: "announce" | "webhook";
+};
+export type CronConfig = {
+    enabled?: boolean;
+    store?: string;
+    maxConcurrentRuns?: number;
+    /** Override default retry policy for one-shot jobs on transient errors. */
+    retry?: CronRetryConfig;
+    /**
+     * Deprecated legacy fallback webhook URL used only for stored jobs with notify=true.
+     * Prefer per-job delivery.mode="webhook" with delivery.to.
+     */
+    webhook?: string;
+    /** Bearer token for cron webhook POST delivery. */
+    webhookToken?: SecretInput;
+    /**
+     * How long to retain completed cron run sessions before automatic pruning.
+     * Accepts a duration string (e.g. "24h", "7d", "1h30m") or `false` to disable pruning.
+     * Default: "24h".
+     */
+    sessionRetention?: string | false;
+    /**
+     * Run-log pruning controls for `cron/runs/<jobId>.jsonl`.
+     * Defaults: `maxBytes=2_000_000`, `keepLines=2000`.
+     */
+    runLog?: {
+        maxBytes?: number | string;
+        keepLines?: number;
+    };
+    failureAlert?: CronFailureAlertConfig;
+    /** Default destination for failure notifications across all cron jobs. */
+    failureDestination?: CronFailureDestinationConfig;
+};

package/dist/src/config/types.d.ts

@@ -0,0 +1,35 @@
+export * from "./types.agent-defaults.js";
+export * from "./types.agent-task-models.js";
+export * from "./types.agents.js";
+export * from "./types.acp.js";
+export * from "./types.approvals.js";
+export * from "./types.auth.js";
+export * from "./types.base.js";
+export * from "./types.browser.js";
+export * from "./types.channels.js";
+export * from "./types.cli.js";
+export * from "./types.openclaw.js";
+export * from "./types.cron.js";
+export * from "./types.discord.js";
+export * from "./types.googlechat.js";
+export * from "./types.gateway.js";
+export * from "./types.hooks.js";
+export * from "./types.imessage.js";
+export * from "./types.irc.js";
+export * from "./types.messages.js";
+export * from "./types.models.js";
+export * from "./types.node-host.js";
+export * from "./types.msteams.js";
+export * from "./types.plugins.js";
+export * from "./types.queue.js";
+export * from "./types.sandbox.js";
+export * from "./types.secrets.js";
+export * from "./types.signal.js";
+export * from "./types.skills.js";
+export * from "./types.slack.js";
+export * from "./types.telegram.js";
+export * from "./types.tts.js";
+export * from "./types.tools.js";
+export * from "./types.whatsapp.js";
+export * from "./types.memory.js";
+export * from "./types.mcp.js";