@agent-our/openclaw 2026.2.6-3

package/dist/plugin-sdk/config/sessions/types.d.ts

@@ -0,0 +1,146 @@
+import type { Skill } from "@mariozechner/pi-coding-agent";
+import type { NormalizedChatType } from "../../channels/chat-type.js";
+import type { ChannelId } from "../../channels/plugins/types.js";
+import type { DeliveryContext } from "../../utils/delivery-context.js";
+import type { TtsAutoMode } from "../types.tts.js";
+export type SessionScope = "per-sender" | "global";
+export type SessionChannelId = ChannelId | "webchat";
+export type SessionChatType = NormalizedChatType;
+export type SessionOrigin = {
+    label?: string;
+    provider?: string;
+    surface?: string;
+    chatType?: SessionChatType;
+    from?: string;
+    to?: string;
+    accountId?: string;
+    threadId?: string | number;
+};
+export type SessionEntry = {
+    /**
+     * Last delivered heartbeat payload (used to suppress duplicate heartbeat notifications).
+     * Stored on the main session entry.
+     */
+    lastHeartbeatText?: string;
+    /** Timestamp (ms) when lastHeartbeatText was delivered. */
+    lastHeartbeatSentAt?: number;
+    sessionId: string;
+    updatedAt: number;
+    sessionFile?: string;
+    /** Parent session key that spawned this session (used for sandbox session-tool scoping). */
+    spawnedBy?: string;
+    systemSent?: boolean;
+    abortedLastRun?: boolean;
+    chatType?: SessionChatType;
+    thinkingLevel?: string;
+    verboseLevel?: string;
+    reasoningLevel?: string;
+    elevatedLevel?: string;
+    ttsAuto?: TtsAutoMode;
+    execHost?: string;
+    execSecurity?: string;
+    execAsk?: string;
+    execNode?: string;
+    responseUsage?: "on" | "off" | "tokens" | "full";
+    providerOverride?: string;
+    modelOverride?: string;
+    authProfileOverride?: string;
+    authProfileOverrideSource?: "auto" | "user";
+    authProfileOverrideCompactionCount?: number;
+    groupActivation?: "mention" | "always";
+    groupActivationNeedsSystemIntro?: boolean;
+    sendPolicy?: "allow" | "deny";
+    queueMode?: "steer" | "followup" | "collect" | "steer-backlog" | "steer+backlog" | "queue" | "interrupt";
+    queueDebounceMs?: number;
+    queueCap?: number;
+    queueDrop?: "old" | "new" | "summarize";
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    modelProvider?: string;
+    model?: string;
+    contextTokens?: number;
+    compactionCount?: number;
+    memoryFlushAt?: number;
+    memoryFlushCompactionCount?: number;
+    cliSessionIds?: Record<string, string>;
+    claudeCliSessionId?: string;
+    label?: string;
+    displayName?: string;
+    channel?: string;
+    groupId?: string;
+    subject?: string;
+    groupChannel?: string;
+    space?: string;
+    origin?: SessionOrigin;
+    deliveryContext?: DeliveryContext;
+    lastChannel?: SessionChannelId;
+    lastTo?: string;
+    lastAccountId?: string;
+    lastThreadId?: string | number;
+    skillsSnapshot?: SessionSkillSnapshot;
+    systemPromptReport?: SessionSystemPromptReport;
+};
+export declare function mergeSessionEntry(existing: SessionEntry | undefined, patch: Partial<SessionEntry>): SessionEntry;
+export type GroupKeyResolution = {
+    key: string;
+    channel?: string;
+    id?: string;
+    chatType?: SessionChatType;
+};
+export type SessionSkillSnapshot = {
+    prompt: string;
+    skills: Array<{
+        name: string;
+        primaryEnv?: string;
+    }>;
+    resolvedSkills?: Skill[];
+    version?: number;
+};
+export type SessionSystemPromptReport = {
+    source: "run" | "estimate";
+    generatedAt: number;
+    sessionId?: string;
+    sessionKey?: string;
+    provider?: string;
+    model?: string;
+    workspaceDir?: string;
+    bootstrapMaxChars?: number;
+    sandbox?: {
+        mode?: string;
+        sandboxed?: boolean;
+    };
+    systemPrompt: {
+        chars: number;
+        projectContextChars: number;
+        nonProjectContextChars: number;
+    };
+    injectedWorkspaceFiles: Array<{
+        name: string;
+        path: string;
+        missing: boolean;
+        rawChars: number;
+        injectedChars: number;
+        truncated: boolean;
+    }>;
+    skills: {
+        promptChars: number;
+        entries: Array<{
+            name: string;
+            blockChars: number;
+        }>;
+    };
+    tools: {
+        listChars: number;
+        schemaChars: number;
+        entries: Array<{
+            name: string;
+            summaryChars: number;
+            schemaChars: number;
+            propertiesCount?: number | null;
+        }>;
+    };
+};
+export declare const DEFAULT_RESET_TRIGGER = "/new";
+export declare const DEFAULT_RESET_TRIGGERS: string[];
+export declare const DEFAULT_IDLE_MINUTES = 60;

package/dist/plugin-sdk/config/sessions.d.ts

@@ -0,0 +1,9 @@
+export * from "./sessions/group.js";
+export * from "./sessions/metadata.js";
+export * from "./sessions/main-session.js";
+export * from "./sessions/paths.js";
+export * from "./sessions/reset.js";
+export * from "./sessions/session-key.js";
+export * from "./sessions/store.js";
+export * from "./sessions/types.js";
+export * from "./sessions/transcript.js";

package/dist/plugin-sdk/config/talk.d.ts

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+type TalkApiKeyDeps = {
+    fs?: typeof fs;
+    os?: typeof os;
+    path?: typeof path;
+};
+export declare function readTalkApiKeyFromProfile(deps?: TalkApiKeyDeps): string | null;
+export declare function resolveTalkApiKey(env?: NodeJS.ProcessEnv, deps?: TalkApiKeyDeps): string | null;
+export {};

package/dist/plugin-sdk/config/telegram-custom-commands.d.ts

@@ -0,0 +1,24 @@
+export declare const TELEGRAM_COMMAND_NAME_PATTERN: RegExp;
+export type TelegramCustomCommandInput = {
+    command?: string | null;
+    description?: string | null;
+};
+export type TelegramCustomCommandIssue = {
+    index: number;
+    field: "command" | "description";
+    message: string;
+};
+export declare function normalizeTelegramCommandName(value: string): string;
+export declare function normalizeTelegramCommandDescription(value: string): string;
+export declare function resolveTelegramCustomCommands(params: {
+    commands?: TelegramCustomCommandInput[] | null;
+    reservedCommands?: Set<string>;
+    checkReserved?: boolean;
+    checkDuplicates?: boolean;
+}): {
+    commands: Array<{
+        command: string;
+        description: string;
+    }>;
+    issues: TelegramCustomCommandIssue[];
+};

package/dist/plugin-sdk/config/types.agent-defaults.d.ts

@@ -0,0 +1,254 @@
+import type { ChannelId } from "../channels/plugins/types.js";
+import type { BlockStreamingChunkConfig, BlockStreamingCoalesceConfig, HumanDelayConfig, TypingMode } from "./types.base.js";
+import type { SandboxBrowserSettings, SandboxDockerSettings, SandboxPruneSettings } from "./types.sandbox.js";
+import type { MemorySearchConfig } from "./types.tools.js";
+export type AgentModelEntryConfig = {
+    alias?: string;
+    /** Provider-specific API parameters (e.g., GLM-4.7 thinking mode). */
+    params?: Record<string, unknown>;
+    /** Enable streaming for this model (default: true, false for Ollama to avoid SDK issue #1205). */
+    streaming?: boolean;
+};
+export type AgentModelListConfig = {
+    primary?: string;
+    fallbacks?: string[];
+};
+export type AgentContextPruningConfig = {
+    mode?: "off" | "cache-ttl";
+    /** TTL to consider cache expired (duration string, default unit: minutes). */
+    ttl?: string;
+    keepLastAssistants?: number;
+    softTrimRatio?: number;
+    hardClearRatio?: number;
+    minPrunableToolChars?: number;
+    tools?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    softTrim?: {
+        maxChars?: number;
+        headChars?: number;
+        tailChars?: number;
+    };
+    hardClear?: {
+        enabled?: boolean;
+        placeholder?: string;
+    };
+};
+export type CliBackendConfig = {
+    /** CLI command to execute (absolute path or on PATH). */
+    command: string;
+    /** Base args applied to every invocation. */
+    args?: string[];
+    /** Output parsing mode (default: json). */
+    output?: "json" | "text" | "jsonl";
+    /** Output parsing mode when resuming a CLI session. */
+    resumeOutput?: "json" | "text" | "jsonl";
+    /** Prompt input mode (default: arg). */
+    input?: "arg" | "stdin";
+    /** Max prompt length for arg mode (if exceeded, stdin is used). */
+    maxPromptArgChars?: number;
+    /** Extra env vars injected for this CLI. */
+    env?: Record<string, string>;
+    /** Env vars to remove before launching this CLI. */
+    clearEnv?: string[];
+    /** Flag used to pass model id (e.g. --model). */
+    modelArg?: string;
+    /** Model aliases mapping (config model id → CLI model id). */
+    modelAliases?: Record<string, string>;
+    /** Flag used to pass session id (e.g. --session-id). */
+    sessionArg?: string;
+    /** Extra args used when resuming a session (use {sessionId} placeholder). */
+    sessionArgs?: string[];
+    /** Alternate args to use when resuming a session (use {sessionId} placeholder). */
+    resumeArgs?: string[];
+    /** When to pass session ids. */
+    sessionMode?: "always" | "existing" | "none";
+    /** JSON fields to read session id from (in order). */
+    sessionIdFields?: string[];
+    /** Flag used to pass system prompt. */
+    systemPromptArg?: string;
+    /** System prompt behavior (append vs replace). */
+    systemPromptMode?: "append" | "replace";
+    /** When to send system prompt. */
+    systemPromptWhen?: "first" | "always" | "never";
+    /** Flag used to pass image paths. */
+    imageArg?: string;
+    /** How to pass multiple images. */
+    imageMode?: "repeat" | "list";
+    /** Serialize runs for this CLI. */
+    serialize?: boolean;
+};
+export type AgentDefaultsConfig = {
+    /** Primary model and fallbacks (provider/model). */
+    model?: AgentModelListConfig;
+    /** Optional image-capable model and fallbacks (provider/model). */
+    imageModel?: AgentModelListConfig;
+    /** Model catalog with optional aliases (full provider/model keys). */
+    models?: Record<string, AgentModelEntryConfig>;
+    /** Agent working directory (preferred). Used as the default cwd for agent runs. */
+    workspace?: string;
+    /** Optional repository root for system prompt runtime line (overrides auto-detect). */
+    repoRoot?: string;
+    /** Skip bootstrap (BOOTSTRAP.md creation, etc.) for pre-configured deployments. */
+    skipBootstrap?: boolean;
+    /** Max chars for injected bootstrap files before truncation (default: 20000). */
+    bootstrapMaxChars?: number;
+    /** Optional IANA timezone for the user (used in system prompt; defaults to host timezone). */
+    userTimezone?: string;
+    /** Time format in system prompt: auto (OS preference), 12-hour, or 24-hour. */
+    timeFormat?: "auto" | "12" | "24";
+    /**
+     * Envelope timestamp timezone: "utc" (default), "local", "user", or an IANA timezone string.
+     */
+    envelopeTimezone?: string;
+    /**
+     * Include absolute timestamps in message envelopes ("on" | "off", default: "on").
+     */
+    envelopeTimestamp?: "on" | "off";
+    /**
+     * Include elapsed time in message envelopes ("on" | "off", default: "on").
+     */
+    envelopeElapsed?: "on" | "off";
+    /** Optional context window cap (used for runtime estimates + status %). */
+    contextTokens?: number;
+    /** Optional CLI backends for text-only fallback (claude-cli, etc.). */
+    cliBackends?: Record<string, CliBackendConfig>;
+    /** Opt-in: prune old tool results from the LLM context to reduce token usage. */
+    contextPruning?: AgentContextPruningConfig;
+    /** Compaction tuning and pre-compaction memory flush behavior. */
+    compaction?: AgentCompactionConfig;
+    /** Vector memory search configuration (per-agent overrides supported). */
+    memorySearch?: MemorySearchConfig;
+    /** Default thinking level when no /think directive is present. */
+    thinkingDefault?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    /** Default verbose level when no /verbose directive is present. */
+    verboseDefault?: "off" | "on" | "full";
+    /** Default elevated level when no /elevated directive is present. */
+    elevatedDefault?: "off" | "on" | "ask" | "full";
+    /** Default block streaming level when no override is present. */
+    blockStreamingDefault?: "off" | "on";
+    /**
+     * Block streaming boundary:
+     * - "text_end": end of each assistant text content block (before tool calls)
+     * - "message_end": end of the whole assistant message (may include tool blocks)
+     */
+    blockStreamingBreak?: "text_end" | "message_end";
+    /** Soft block chunking for streamed replies (min/max chars, prefer paragraph/newline). */
+    blockStreamingChunk?: BlockStreamingChunkConfig;
+    /**
+     * Block reply coalescing (merge streamed chunks before send).
+     * idleMs: wait time before flushing when idle.
+     */
+    blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+    /** Human-like delay between block replies. */
+    humanDelay?: HumanDelayConfig;
+    timeoutSeconds?: number;
+    /** Max inbound media size in MB for agent-visible attachments (text note or future image attach). */
+    mediaMaxMb?: number;
+    typingIntervalSeconds?: number;
+    /** Typing indicator start mode (never|instant|thinking|message). */
+    typingMode?: TypingMode;
+    /** Periodic background heartbeat runs. */
+    heartbeat?: {
+        /** Heartbeat interval (duration string, default unit: minutes; default: 30m). */
+        every?: string;
+        /** Optional active-hours window (local time); heartbeats run only inside this window. */
+        activeHours?: {
+            /** Start time (24h, HH:MM). Inclusive. */
+            start?: string;
+            /** End time (24h, HH:MM). Exclusive. Use "24:00" for end-of-day. */
+            end?: string;
+            /** Timezone for the window ("user", "local", or IANA TZ id). Default: "user". */
+            timezone?: string;
+        };
+        /** Heartbeat model override (provider/model). */
+        model?: string;
+        /** Session key for heartbeat runs ("main" or explicit session key). */
+        session?: string;
+        /** Delivery target ("last", "none", or a channel id). */
+        target?: "last" | "none" | ChannelId;
+        /** Optional delivery override (E.164 for WhatsApp, chat id for Telegram). */
+        to?: string;
+        /** Optional account id for multi-account channels. */
+        accountId?: string;
+        /** Override the heartbeat prompt body (default: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK."). */
+        prompt?: string;
+        /** Max chars allowed after HEARTBEAT_OK before delivery (default: 30). */
+        ackMaxChars?: number;
+        /**
+         * When enabled, deliver the model's reasoning payload for heartbeat runs (when available)
+         * as a separate message prefixed with `Reasoning:` (same as `/reasoning on`).
+         *
+         * Default: false (only the final heartbeat payload is delivered).
+         */
+        includeReasoning?: boolean;
+    };
+    /** Max concurrent agent runs across all conversations. Default: 1 (sequential). */
+    maxConcurrent?: number;
+    /** Sub-agent defaults (spawned via sessions_spawn). */
+    subagents?: {
+        /** Max concurrent sub-agent runs (global lane: "subagent"). Default: 1. */
+        maxConcurrent?: number;
+        /** Auto-archive sub-agent sessions after N minutes (default: 60). */
+        archiveAfterMinutes?: number;
+        /** Default model selection for spawned sub-agents (string or {primary,fallbacks}). */
+        model?: string | {
+            primary?: string;
+            fallbacks?: string[];
+        };
+        /** Default thinking level for spawned sub-agents (e.g. "off", "low", "medium", "high"). */
+        thinking?: string;
+    };
+    /** Optional sandbox settings for non-main sessions. */
+    sandbox?: {
+        /** Enable sandboxing for sessions. */
+        mode?: "off" | "non-main" | "all";
+        /**
+         * Agent workspace access inside the sandbox.
+         * - "none": do not mount the agent workspace into the container; use a sandbox workspace under workspaceRoot
+         * - "ro": mount the agent workspace read-only; disables write/edit tools
+         * - "rw": mount the agent workspace read/write; enables write/edit tools
+         */
+        workspaceAccess?: "none" | "ro" | "rw";
+        /**
+         * Session tools visibility for sandboxed sessions.
+         * - "spawned": only allow session tools to target sessions spawned from this session (default)
+         * - "all": allow session tools to target any session
+         */
+        sessionToolsVisibility?: "spawned" | "all";
+        /** Container/workspace scope for sandbox isolation. */
+        scope?: "session" | "agent" | "shared";
+        /** Legacy alias for scope ("session" when true, "shared" when false). */
+        perSession?: boolean;
+        /** Root directory for sandbox workspaces. */
+        workspaceRoot?: string;
+        /** Docker-specific sandbox settings. */
+        docker?: SandboxDockerSettings;
+        /** Optional sandboxed browser settings. */
+        browser?: SandboxBrowserSettings;
+        /** Auto-prune sandbox containers. */
+        prune?: SandboxPruneSettings;
+    };
+};
+export type AgentCompactionMode = "default" | "safeguard";
+export type AgentCompactionConfig = {
+    /** Compaction summarization mode. */
+    mode?: AgentCompactionMode;
+    /** Minimum reserve tokens enforced for Pi compaction (0 disables the floor). */
+    reserveTokensFloor?: number;
+    /** Max share of context window for history during safeguard pruning (0.1–0.9, default 0.5). */
+    maxHistoryShare?: number;
+    /** Pre-compaction memory flush (agentic turn). Default: enabled. */
+    memoryFlush?: AgentCompactionMemoryFlushConfig;
+};
+export type AgentCompactionMemoryFlushConfig = {
+    /** Enable the pre-compaction memory flush (default: true). */
+    enabled?: boolean;
+    /** Run the memory flush when context is within this many tokens of the compaction threshold. */
+    softThresholdTokens?: number;
+    /** User prompt used for the memory flush turn (NO_REPLY is enforced if missing). */
+    prompt?: string;
+    /** System prompt appended for the memory flush turn. */
+    systemPrompt?: string;
+};

package/dist/plugin-sdk/config/types.agents.d.ts

@@ -0,0 +1,77 @@
+import type { AgentDefaultsConfig } from "./types.agent-defaults.js";
+import type { HumanDelayConfig, IdentityConfig } from "./types.base.js";
+import type { GroupChatConfig } from "./types.messages.js";
+import type { SandboxBrowserSettings, SandboxDockerSettings, SandboxPruneSettings } from "./types.sandbox.js";
+import type { AgentToolsConfig, MemorySearchConfig } from "./types.tools.js";
+export type AgentModelConfig = string | {
+    /** Primary model (provider/model). */
+    primary?: string;
+    /** Per-agent model fallbacks (provider/model). */
+    fallbacks?: string[];
+};
+export type AgentConfig = {
+    id: string;
+    default?: boolean;
+    name?: string;
+    workspace?: string;
+    agentDir?: string;
+    model?: AgentModelConfig;
+    /** Optional allowlist of skills for this agent (omit = all skills; empty = none). */
+    skills?: string[];
+    memorySearch?: MemorySearchConfig;
+    /** Human-like delay between block replies for this agent. */
+    humanDelay?: HumanDelayConfig;
+    /** Optional per-agent heartbeat overrides. */
+    heartbeat?: AgentDefaultsConfig["heartbeat"];
+    identity?: IdentityConfig;
+    groupChat?: GroupChatConfig;
+    subagents?: {
+        /** Allow spawning sub-agents under other agent ids. Use "*" to allow any. */
+        allowAgents?: string[];
+        /** Per-agent default model for spawned sub-agents (string or {primary,fallbacks}). */
+        model?: string | {
+            primary?: string;
+            fallbacks?: string[];
+        };
+    };
+    sandbox?: {
+        mode?: "off" | "non-main" | "all";
+        /** Agent workspace access inside the sandbox. */
+        workspaceAccess?: "none" | "ro" | "rw";
+        /**
+         * Session tools visibility for sandboxed sessions.
+         * - "spawned": only allow session tools to target sessions spawned from this session (default)
+         * - "all": allow session tools to target any session
+         */
+        sessionToolsVisibility?: "spawned" | "all";
+        /** Container/workspace scope for sandbox isolation. */
+        scope?: "session" | "agent" | "shared";
+        /** Legacy alias for scope ("session" when true, "shared" when false). */
+        perSession?: boolean;
+        workspaceRoot?: string;
+        /** Docker-specific sandbox overrides for this agent. */
+        docker?: SandboxDockerSettings;
+        /** Optional sandboxed browser overrides for this agent. */
+        browser?: SandboxBrowserSettings;
+        /** Auto-prune overrides for this agent. */
+        prune?: SandboxPruneSettings;
+    };
+    tools?: AgentToolsConfig;
+};
+export type AgentsConfig = {
+    defaults?: AgentDefaultsConfig;
+    list?: AgentConfig[];
+};
+export type AgentBinding = {
+    agentId: string;
+    match: {
+        channel: string;
+        accountId?: string;
+        peer?: {
+            kind: "dm" | "group" | "channel";
+            id: string;
+        };
+        guildId?: string;
+        teamId?: string;
+    };
+};

package/dist/plugin-sdk/config/types.approvals.d.ts

@@ -0,0 +1,26 @@
+export type ExecApprovalForwardingMode = "session" | "targets" | "both";
+export type ExecApprovalForwardTarget = {
+    /** Channel id (e.g. "discord", "slack", or plugin channel id). */
+    channel: string;
+    /** Destination id (channel id, user id, etc. depending on channel). */
+    to: string;
+    /** Optional account id for multi-account channels. */
+    accountId?: string;
+    /** Optional thread id to reply inside a thread. */
+    threadId?: string | number;
+};
+export type ExecApprovalForwardingConfig = {
+    /** Enable forwarding exec approvals to chat channels. Default: false. */
+    enabled?: boolean;
+    /** Delivery mode (session=origin chat, targets=config targets, both=both). Default: session. */
+    mode?: ExecApprovalForwardingMode;
+    /** Only forward approvals for these agent IDs. Omit = all agents. */
+    agentFilter?: string[];
+    /** Only forward approvals matching these session key patterns (substring or regex). */
+    sessionFilter?: string[];
+    /** Explicit delivery targets (used when mode includes targets). */
+    targets?: ExecApprovalForwardTarget[];
+};
+export type ApprovalsConfig = {
+    exec?: ExecApprovalForwardingConfig;
+};

package/dist/plugin-sdk/config/types.auth.d.ts

@@ -0,0 +1,28 @@
+export type AuthProfileConfig = {
+    provider: string;
+    /**
+     * Credential type expected in auth-profiles.json for this profile id.
+     * - api_key: static provider API key
+     * - oauth: refreshable OAuth credentials (access+refresh+expires)
+     * - token: static bearer-style token (optionally expiring; no refresh)
+     */
+    mode: "api_key" | "oauth" | "token";
+    email?: string;
+};
+export type AuthConfig = {
+    profiles?: Record<string, AuthProfileConfig>;
+    order?: Record<string, string[]>;
+    cooldowns?: {
+        /** Default billing backoff (hours). Default: 5. */
+        billingBackoffHours?: number;
+        /** Optional per-provider billing backoff (hours). */
+        billingBackoffHoursByProvider?: Record<string, number>;
+        /** Billing backoff cap (hours). Default: 24. */
+        billingMaxHours?: number;
+        /**
+         * Failure window for backoff counters (hours). If no failures occur within
+         * this window, counters reset. Default: 24.
+         */
+        failureWindowHours?: number;
+    };
+};