stableclaw 2026.4.19 → 2026.4.20

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

@@ -0,0 +1,266 @@
+import type { Skill } from "@mariozechner/pi-coding-agent";
+import type { ChatType } 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 = ChatType;
+export type SessionOrigin = {
+    label?: string;
+    provider?: string;
+    surface?: string;
+    chatType?: SessionChatType;
+    from?: string;
+    to?: string;
+    accountId?: string;
+    threadId?: string | number;
+};
+export type SessionAcpIdentitySource = "ensure" | "status" | "event";
+export type SessionAcpIdentityState = "pending" | "resolved";
+export type SessionAcpIdentity = {
+    state: SessionAcpIdentityState;
+    acpxRecordId?: string;
+    acpxSessionId?: string;
+    agentSessionId?: string;
+    source: SessionAcpIdentitySource;
+    lastUpdatedAt: number;
+};
+export type SessionAcpMeta = {
+    backend: string;
+    agent: string;
+    runtimeSessionName: string;
+    identity?: SessionAcpIdentity;
+    mode: "persistent" | "oneshot";
+    runtimeOptions?: AcpSessionRuntimeOptions;
+    cwd?: string;
+    state: "idle" | "running" | "error";
+    lastActivityAt: number;
+    lastError?: string;
+};
+export type AcpSessionRuntimeOptions = {
+    /**
+     * ACP runtime mode set via session/set_mode (for example: "plan", "normal", "auto").
+     */
+    runtimeMode?: string;
+    /** ACP runtime config option: model id. */
+    model?: string;
+    /** Working directory override for ACP session turns. */
+    cwd?: string;
+    /** ACP runtime config option: permission profile id. */
+    permissionProfile?: string;
+    /** ACP runtime config option: per-turn timeout in seconds. */
+    timeoutSeconds?: number;
+    /** Backend-specific option bag mapped through session/set_config_option. */
+    backendExtras?: Record<string, string>;
+};
+export type CliSessionBinding = {
+    sessionId: string;
+    authProfileId?: string;
+    extraSystemPromptHash?: string;
+    mcpConfigHash?: string;
+};
+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;
+    /** Workspace inherited by spawned sessions and reused on later turns for the same child session. */
+    spawnedWorkspaceDir?: string;
+    /** Explicit parent session linkage for dashboard-created child sessions. */
+    parentSessionKey?: string;
+    /** True after a thread/topic session has been forked from its parent transcript once. */
+    forkedFromParent?: boolean;
+    /** Subagent spawn depth (0 = main, 1 = sub-agent, 2 = sub-sub-agent). */
+    spawnDepth?: number;
+    /** Explicit role assigned at spawn time for subagent tool policy/control decisions. */
+    subagentRole?: "orchestrator" | "leaf";
+    /** Explicit control scope assigned at spawn time for subagent control decisions. */
+    subagentControlScope?: "children" | "none";
+    systemSent?: boolean;
+    abortedLastRun?: boolean;
+    /** Stable first-run start time for subagent sessions, persisted after completion. */
+    startedAt?: number;
+    /** Latest completed run end time for subagent sessions, persisted after completion. */
+    endedAt?: number;
+    /** Accumulated runtime across subagent follow-up runs, persisted after completion. */
+    runtimeMs?: number;
+    /** Final persisted subagent run status, used after in-memory run archival. */
+    status?: "running" | "done" | "failed" | "killed" | "timeout";
+    /**
+     * Session-level stop cutoff captured when /stop is received.
+     * Messages at/before this boundary are skipped to avoid replaying
+     * queued pre-stop backlog.
+     */
+    abortCutoffMessageSid?: string;
+    /** Epoch ms cutoff paired with abortCutoffMessageSid when available. */
+    abortCutoffTimestamp?: number;
+    chatType?: SessionChatType;
+    thinkingLevel?: string;
+    fastMode?: boolean;
+    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;
+    /**
+     * Whether totalTokens reflects a fresh context snapshot for the latest run.
+     * Undefined means legacy/unknown freshness; false forces consumers to treat
+     * totalTokens as stale/unknown for context-utilization displays.
+     */
+    totalTokensFresh?: boolean;
+    estimatedCostUsd?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    modelProvider?: string;
+    model?: string;
+    /**
+     * Last selected/runtime model pair for which a fallback notice was emitted.
+     * Used to avoid repeating the same fallback notice every turn.
+     */
+    fallbackNoticeSelectedModel?: string;
+    fallbackNoticeActiveModel?: string;
+    fallbackNoticeReason?: string;
+    contextTokens?: number;
+    compactionCount?: number;
+    memoryFlushAt?: number;
+    memoryFlushCompactionCount?: number;
+    memoryFlushContextHash?: string;
+    cliSessionIds?: Record<string, string>;
+    cliSessionBindings?: Record<string, CliSessionBinding>;
+    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;
+    acp?: SessionAcpMeta;
+};
+export declare function normalizeSessionRuntimeModelFields(entry: SessionEntry): SessionEntry;
+export declare function setSessionRuntimeModel(entry: SessionEntry, runtime: {
+    provider: string;
+    model: string;
+}): boolean;
+export type SessionEntryMergePolicy = "touch-activity" | "preserve-activity";
+type MergeSessionEntryOptions = {
+    policy?: SessionEntryMergePolicy;
+    now?: number;
+};
+export declare function mergeSessionEntryWithPolicy(existing: SessionEntry | undefined, patch: Partial<SessionEntry>, options?: MergeSessionEntryOptions): SessionEntry;
+export declare function mergeSessionEntry(existing: SessionEntry | undefined, patch: Partial<SessionEntry>): SessionEntry;
+export declare function mergeSessionEntryPreserveActivity(existing: SessionEntry | undefined, patch: Partial<SessionEntry>): SessionEntry;
+export declare function resolveFreshSessionTotalTokens(entry?: Pick<SessionEntry, "totalTokens" | "totalTokensFresh"> | null): number | undefined;
+export declare function isSessionTotalTokensFresh(entry?: Pick<SessionEntry, "totalTokens" | "totalTokensFresh"> | null): boolean;
+export type GroupKeyResolution = {
+    key: string;
+    channel?: string;
+    id?: string;
+    chatType?: SessionChatType;
+};
+export type SessionSkillSnapshot = {
+    prompt: string;
+    skills: Array<{
+        name: string;
+        primaryEnv?: string;
+        requiredEnv?: string[];
+    }>;
+    /** Normalized agent-level filter used to build this snapshot; undefined means unrestricted. */
+    skillFilter?: 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;
+    bootstrapTotalMaxChars?: number;
+    bootstrapTruncation?: {
+        warningMode?: "off" | "once" | "always";
+        warningShown?: boolean;
+        promptWarningSignature?: string;
+        warningSignaturesSeen?: string[];
+        truncatedFiles?: number;
+        nearLimitFiles?: number;
+        totalNearLimit?: boolean;
+    };
+    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 = 0;
+export {};

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

@@ -0,0 +1,15 @@
+export * from "./sessions/group.js";
+export * from "./sessions/artifacts.js";
+export * from "./sessions/metadata.js";
+export * from "./sessions/main-session.js";
+export * from "./sessions/main-session.runtime.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";
+export * from "./sessions/session-file.js";
+export * from "./sessions/delivery-info.js";
+export * from "./sessions/disk-budget.js";
+export * from "./sessions/targets.js";

package/dist/plugin-sdk/src/config/state-dir-dotenv.d.ts

@@ -0,0 +1,19 @@
+import type { OpenClawConfig } from "./types.js";
+/**
+ * Read and parse `~/.openclaw/.env` (or `$OPENCLAW_STATE_DIR/.env`), returning
+ * a filtered record of key-value pairs suitable for embedding in a service
+ * environment (LaunchAgent plist, systemd unit, Scheduled Task).
+ */
+export declare function readStateDirDotEnvVars(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * Durable service env sources survive beyond the invoking shell and are safe to
+ * persist into gateway install metadata.
+ *
+ * Precedence:
+ * 1. state-dir `.env` file vars
+ * 2. config service env vars
+ */
+export declare function collectDurableServiceEnvVars(params: {
+    env: Record<string, string | undefined>;
+    config?: OpenClawConfig;
+}): Record<string, string>;

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

@@ -0,0 +1,6 @@
+export declare const TALK_SILENCE_TIMEOUT_MS_BY_PLATFORM: {
+    readonly macos: 700;
+    readonly android: 700;
+    readonly ios: 900;
+};
+export declare function describeTalkSilenceTimeoutDefaults(): string;

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

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { ResolvedTalkConfig, TalkConfig, TalkConfigResponse } from "./types.gateway.js";
+import type { OpenClawConfig } from "./types.js";
+type TalkApiKeyDeps = {
+    fs?: typeof fs;
+    os?: typeof os;
+    path?: typeof path;
+};
+export declare const LEGACY_TALK_PROVIDER_ID = "elevenlabs";
+export declare function normalizeTalkSection(value: TalkConfig | undefined): TalkConfig | undefined;
+export declare function normalizeTalkConfig(config: OpenClawConfig): OpenClawConfig;
+export declare function resolveActiveTalkProviderConfig(talk: TalkConfig | undefined): ResolvedTalkConfig | undefined;
+export declare function buildTalkConfigResponse(value: unknown): TalkConfigResponse | undefined;
+export declare function readTalkApiKeyFromProfile(deps?: TalkApiKeyDeps): string | null;
+export declare function resolveTalkApiKey(env?: NodeJS.ProcessEnv, deps?: TalkApiKeyDeps): string | null;
+export {};

package/dist/plugin-sdk/src/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/src/config/types.acp.d.ts

@@ -0,0 +1,44 @@
+import type { AcpSessionUpdateTag } from "../acp/runtime/types.js";
+export type AcpDispatchConfig = {
+    /** Master switch for ACP turn dispatch in the reply pipeline. */
+    enabled?: boolean;
+};
+export type AcpStreamConfig = {
+    /** Coalescer idle flush window in milliseconds for ACP streamed text. */
+    coalesceIdleMs?: number;
+    /** Maximum text size per streamed chunk. */
+    maxChunkChars?: number;
+    /** Suppresses repeated ACP status/tool projection lines within a turn. */
+    repeatSuppression?: boolean;
+    /** Live streams chunks or waits for terminal event before delivery. */
+    deliveryMode?: "live" | "final_only";
+    /** Separator inserted before visible text when hidden tool events occurred. */
+    hiddenBoundarySeparator?: "none" | "space" | "newline" | "paragraph";
+    /** Maximum assistant output characters forwarded per turn. */
+    maxOutputChars?: number;
+    /** Maximum visible characters for projected session/update lines. */
+    maxSessionUpdateChars?: number;
+    /**
+     * Per-sessionUpdate visibility overrides.
+     * Keys not listed here fall back to OpenClaw defaults.
+     */
+    tagVisibility?: Partial<Record<AcpSessionUpdateTag, boolean>>;
+};
+export type AcpRuntimeConfig = {
+    /** Idle runtime TTL in minutes for ACP session workers. */
+    ttlMinutes?: number;
+    /** Optional operator install/setup command shown by `/acp install` and `/acp doctor`. */
+    installCommand?: string;
+};
+export type AcpConfig = {
+    /** Global ACP runtime gate. */
+    enabled?: boolean;
+    dispatch?: AcpDispatchConfig;
+    /** Backend id registered by ACP runtime plugin (for example: acpx). */
+    backend?: string;
+    defaultAgent?: string;
+    allowedAgents?: string[];
+    maxConcurrentSessions?: number;
+    stream?: AcpStreamConfig;
+    runtime?: AcpRuntimeConfig;
+};