clawdbot 2026.1.4-1

package/dist/auto-reply/reply/directive-handling.js

@@ -0,0 +1,361 @@
+import { lookupContextTokens } from "../../agents/context.js";
+import { DEFAULT_CONTEXT_TOKENS, DEFAULT_MODEL, DEFAULT_PROVIDER, } from "../../agents/defaults.js";
+import { buildModelAliasIndex, modelKey, resolveConfiguredModelRef, resolveModelRefFromString, } from "../../agents/model-selection.js";
+import { saveSessionStore } from "../../config/sessions.js";
+import { enqueueSystemEvent } from "../../infra/system-events.js";
+import { extractModelDirective } from "../model.js";
+import { extractElevatedDirective, extractThinkDirective, extractVerboseDirective, } from "./directives.js";
+import { stripMentions, stripStructuralPrefixes } from "./mentions.js";
+import { resolveModelDirectiveSelection, } from "./model-selection.js";
+import { extractQueueDirective, } from "./queue.js";
+const SYSTEM_MARK = "⚙️";
+export function parseInlineDirectives(body) {
+    const { cleaned: thinkCleaned, thinkLevel, rawLevel: rawThinkLevel, hasDirective: hasThinkDirective, } = extractThinkDirective(body);
+    const { cleaned: verboseCleaned, verboseLevel, rawLevel: rawVerboseLevel, hasDirective: hasVerboseDirective, } = extractVerboseDirective(thinkCleaned);
+    const { cleaned: elevatedCleaned, elevatedLevel, rawLevel: rawElevatedLevel, hasDirective: hasElevatedDirective, } = extractElevatedDirective(verboseCleaned);
+    const { cleaned: modelCleaned, rawModel, hasDirective: hasModelDirective, } = extractModelDirective(elevatedCleaned);
+    const { cleaned: queueCleaned, queueMode, queueReset, rawMode, debounceMs, cap, dropPolicy, rawDebounce, rawCap, rawDrop, hasDirective: hasQueueDirective, hasOptions: hasQueueOptions, } = extractQueueDirective(modelCleaned);
+    return {
+        cleaned: queueCleaned,
+        hasThinkDirective,
+        thinkLevel,
+        rawThinkLevel,
+        hasVerboseDirective,
+        verboseLevel,
+        rawVerboseLevel,
+        hasElevatedDirective,
+        elevatedLevel,
+        rawElevatedLevel,
+        hasModelDirective,
+        rawModelDirective: rawModel,
+        hasQueueDirective,
+        queueMode,
+        queueReset,
+        rawQueueMode: rawMode,
+        debounceMs,
+        cap,
+        dropPolicy,
+        rawDebounce,
+        rawCap,
+        rawDrop,
+        hasQueueOptions,
+    };
+}
+export function isDirectiveOnly(params) {
+    const { directives, cleanedBody, ctx, cfg, isGroup } = params;
+    if (!directives.hasThinkDirective &&
+        !directives.hasVerboseDirective &&
+        !directives.hasElevatedDirective &&
+        !directives.hasModelDirective &&
+        !directives.hasQueueDirective)
+        return false;
+    const stripped = stripStructuralPrefixes(cleanedBody ?? "");
+    const noMentions = isGroup ? stripMentions(stripped, ctx, cfg) : stripped;
+    return noMentions.length === 0;
+}
+export async function handleDirectiveOnly(params) {
+    const { directives, sessionEntry, sessionStore, sessionKey, storePath, elevatedEnabled, elevatedAllowed, defaultProvider, defaultModel, aliasIndex, allowedModelKeys, allowedModelCatalog, resetModelOverride, initialModelLabel, formatModelSwitchEvent, } = params;
+    if (directives.hasModelDirective) {
+        const isModelListAlias = directives.rawModelDirective?.trim().toLowerCase() === "status";
+        if (!directives.rawModelDirective || isModelListAlias) {
+            if (allowedModelCatalog.length === 0) {
+                return { text: "No models available." };
+            }
+            const current = `${params.provider}/${params.model}`;
+            const defaultLabel = `${defaultProvider}/${defaultModel}`;
+            const header = current === defaultLabel
+                ? `Models (current: ${current}):`
+                : `Models (current: ${current}, default: ${defaultLabel}):`;
+            const lines = [header];
+            if (resetModelOverride) {
+                lines.push(`(previous selection reset to default)`);
+            }
+            for (const entry of allowedModelCatalog) {
+                const label = `${entry.provider}/${entry.id}`;
+                const aliases = aliasIndex.byKey.get(label);
+                const aliasSuffix = aliases && aliases.length > 0
+                    ? ` (alias: ${aliases.join(", ")})`
+                    : "";
+                const suffix = entry.name && entry.name !== entry.id ? ` — ${entry.name}` : "";
+                lines.push(`- ${label}${aliasSuffix}${suffix}`);
+            }
+            return { text: lines.join("\n") };
+        }
+    }
+    if (directives.hasThinkDirective && !directives.thinkLevel) {
+        return {
+            text: `Unrecognized thinking level "${directives.rawThinkLevel ?? ""}". Valid levels: off, minimal, low, medium, high.`,
+        };
+    }
+    if (directives.hasVerboseDirective && !directives.verboseLevel) {
+        return {
+            text: `Unrecognized verbose level "${directives.rawVerboseLevel ?? ""}". Valid levels: off, on.`,
+        };
+    }
+    if (directives.hasElevatedDirective && !directives.elevatedLevel) {
+        return {
+            text: `Unrecognized elevated level "${directives.rawElevatedLevel ?? ""}". Valid levels: off, on.`,
+        };
+    }
+    if (directives.hasElevatedDirective &&
+        (!elevatedEnabled || !elevatedAllowed)) {
+        return { text: "elevated is not available right now." };
+    }
+    const queueModeInvalid = directives.hasQueueDirective &&
+        !directives.queueMode &&
+        !directives.queueReset &&
+        Boolean(directives.rawQueueMode);
+    const queueDebounceInvalid = directives.hasQueueDirective &&
+        directives.rawDebounce !== undefined &&
+        typeof directives.debounceMs !== "number";
+    const queueCapInvalid = directives.hasQueueDirective &&
+        directives.rawCap !== undefined &&
+        typeof directives.cap !== "number";
+    const queueDropInvalid = directives.hasQueueDirective &&
+        directives.rawDrop !== undefined &&
+        !directives.dropPolicy;
+    if (queueModeInvalid ||
+        queueDebounceInvalid ||
+        queueCapInvalid ||
+        queueDropInvalid) {
+        const errors = [];
+        if (queueModeInvalid) {
+            errors.push(`Unrecognized queue mode "${directives.rawQueueMode ?? ""}". Valid modes: steer, followup, collect, steer+backlog, interrupt.`);
+        }
+        if (queueDebounceInvalid) {
+            errors.push(`Invalid debounce "${directives.rawDebounce ?? ""}". Use ms/s/m (e.g. debounce:1500ms, debounce:2s).`);
+        }
+        if (queueCapInvalid) {
+            errors.push(`Invalid cap "${directives.rawCap ?? ""}". Use a positive integer (e.g. cap:10).`);
+        }
+        if (queueDropInvalid) {
+            errors.push(`Invalid drop policy "${directives.rawDrop ?? ""}". Use drop:old, drop:new, or drop:summarize.`);
+        }
+        return { text: errors.join(" ") };
+    }
+    let modelSelection;
+    if (directives.hasModelDirective && directives.rawModelDirective) {
+        const resolved = resolveModelDirectiveSelection({
+            raw: directives.rawModelDirective,
+            defaultProvider,
+            defaultModel,
+            aliasIndex,
+            allowedModelKeys,
+        });
+        if (resolved.error) {
+            return { text: resolved.error };
+        }
+        modelSelection = resolved.selection;
+        if (modelSelection) {
+            const nextLabel = `${modelSelection.provider}/${modelSelection.model}`;
+            if (nextLabel !== initialModelLabel) {
+                enqueueSystemEvent(formatModelSwitchEvent(nextLabel, modelSelection.alias), {
+                    contextKey: `model:${nextLabel}`,
+                });
+            }
+        }
+    }
+    if (sessionEntry && sessionStore && sessionKey) {
+        if (directives.hasThinkDirective && directives.thinkLevel) {
+            if (directives.thinkLevel === "off")
+                delete sessionEntry.thinkingLevel;
+            else
+                sessionEntry.thinkingLevel = directives.thinkLevel;
+        }
+        if (directives.hasVerboseDirective && directives.verboseLevel) {
+            if (directives.verboseLevel === "off")
+                delete sessionEntry.verboseLevel;
+            else
+                sessionEntry.verboseLevel = directives.verboseLevel;
+        }
+        if (directives.hasElevatedDirective && directives.elevatedLevel) {
+            if (directives.elevatedLevel === "off")
+                delete sessionEntry.elevatedLevel;
+            else
+                sessionEntry.elevatedLevel = directives.elevatedLevel;
+        }
+        if (modelSelection) {
+            if (modelSelection.isDefault) {
+                delete sessionEntry.providerOverride;
+                delete sessionEntry.modelOverride;
+            }
+            else {
+                sessionEntry.providerOverride = modelSelection.provider;
+                sessionEntry.modelOverride = modelSelection.model;
+            }
+        }
+        if (directives.hasQueueDirective && directives.queueReset) {
+            delete sessionEntry.queueMode;
+            delete sessionEntry.queueDebounceMs;
+            delete sessionEntry.queueCap;
+            delete sessionEntry.queueDrop;
+        }
+        else if (directives.hasQueueDirective) {
+            if (directives.queueMode)
+                sessionEntry.queueMode = directives.queueMode;
+            if (typeof directives.debounceMs === "number") {
+                sessionEntry.queueDebounceMs = directives.debounceMs;
+            }
+            if (typeof directives.cap === "number") {
+                sessionEntry.queueCap = directives.cap;
+            }
+            if (directives.dropPolicy) {
+                sessionEntry.queueDrop = directives.dropPolicy;
+            }
+        }
+        sessionEntry.updatedAt = Date.now();
+        sessionStore[sessionKey] = sessionEntry;
+        if (storePath) {
+            await saveSessionStore(storePath, sessionStore);
+        }
+    }
+    const parts = [];
+    if (directives.hasThinkDirective && directives.thinkLevel) {
+        parts.push(directives.thinkLevel === "off"
+            ? "Thinking disabled."
+            : `Thinking level set to ${directives.thinkLevel}.`);
+    }
+    if (directives.hasVerboseDirective && directives.verboseLevel) {
+        parts.push(directives.verboseLevel === "off"
+            ? `${SYSTEM_MARK} Verbose logging disabled.`
+            : `${SYSTEM_MARK} Verbose logging enabled.`);
+    }
+    if (directives.hasElevatedDirective && directives.elevatedLevel) {
+        parts.push(directives.elevatedLevel === "off"
+            ? `${SYSTEM_MARK} Elevated mode disabled.`
+            : `${SYSTEM_MARK} Elevated mode enabled.`);
+    }
+    if (modelSelection) {
+        const label = `${modelSelection.provider}/${modelSelection.model}`;
+        const labelWithAlias = modelSelection.alias
+            ? `${modelSelection.alias} (${label})`
+            : label;
+        parts.push(modelSelection.isDefault
+            ? `Model reset to default (${labelWithAlias}).`
+            : `Model set to ${labelWithAlias}.`);
+    }
+    if (directives.hasQueueDirective && directives.queueMode) {
+        parts.push(`${SYSTEM_MARK} Queue mode set to ${directives.queueMode}.`);
+    }
+    else if (directives.hasQueueDirective && directives.queueReset) {
+        parts.push(`${SYSTEM_MARK} Queue mode reset to default.`);
+    }
+    if (directives.hasQueueDirective &&
+        typeof directives.debounceMs === "number") {
+        parts.push(`${SYSTEM_MARK} Queue debounce set to ${directives.debounceMs}ms.`);
+    }
+    if (directives.hasQueueDirective && typeof directives.cap === "number") {
+        parts.push(`${SYSTEM_MARK} Queue cap set to ${directives.cap}.`);
+    }
+    if (directives.hasQueueDirective && directives.dropPolicy) {
+        parts.push(`${SYSTEM_MARK} Queue drop set to ${directives.dropPolicy}.`);
+    }
+    const ack = parts.join(" ").trim();
+    return { text: ack || "OK." };
+}
+export async function persistInlineDirectives(params) {
+    const { directives, sessionEntry, sessionStore, sessionKey, storePath, elevatedEnabled, elevatedAllowed, defaultProvider, defaultModel, aliasIndex, allowedModelKeys, initialModelLabel, formatModelSwitchEvent, agentCfg, } = params;
+    let { provider, model } = params;
+    if (sessionEntry && sessionStore && sessionKey) {
+        let updated = false;
+        if (directives.hasThinkDirective && directives.thinkLevel) {
+            if (directives.thinkLevel === "off") {
+                delete sessionEntry.thinkingLevel;
+            }
+            else {
+                sessionEntry.thinkingLevel = directives.thinkLevel;
+            }
+            updated = true;
+        }
+        if (directives.hasVerboseDirective && directives.verboseLevel) {
+            if (directives.verboseLevel === "off") {
+                delete sessionEntry.verboseLevel;
+            }
+            else {
+                sessionEntry.verboseLevel = directives.verboseLevel;
+            }
+            updated = true;
+        }
+        if (directives.hasElevatedDirective &&
+            directives.elevatedLevel &&
+            elevatedEnabled &&
+            elevatedAllowed) {
+            if (directives.elevatedLevel === "off") {
+                delete sessionEntry.elevatedLevel;
+            }
+            else {
+                sessionEntry.elevatedLevel = directives.elevatedLevel;
+            }
+            updated = true;
+        }
+        const modelDirective = directives.hasModelDirective && params.effectiveModelDirective
+            ? params.effectiveModelDirective
+            : undefined;
+        if (modelDirective) {
+            const resolved = resolveModelRefFromString({
+                raw: modelDirective,
+                defaultProvider,
+                aliasIndex,
+            });
+            if (resolved) {
+                const key = modelKey(resolved.ref.provider, resolved.ref.model);
+                if (allowedModelKeys.size === 0 || allowedModelKeys.has(key)) {
+                    const isDefault = resolved.ref.provider === defaultProvider &&
+                        resolved.ref.model === defaultModel;
+                    if (isDefault) {
+                        delete sessionEntry.providerOverride;
+                        delete sessionEntry.modelOverride;
+                    }
+                    else {
+                        sessionEntry.providerOverride = resolved.ref.provider;
+                        sessionEntry.modelOverride = resolved.ref.model;
+                    }
+                    provider = resolved.ref.provider;
+                    model = resolved.ref.model;
+                    const nextLabel = `${provider}/${model}`;
+                    if (nextLabel !== initialModelLabel) {
+                        enqueueSystemEvent(formatModelSwitchEvent(nextLabel, resolved.alias), {
+                            contextKey: `model:${nextLabel}`,
+                        });
+                    }
+                    updated = true;
+                }
+            }
+        }
+        if (directives.hasQueueDirective && directives.queueReset) {
+            delete sessionEntry.queueMode;
+            delete sessionEntry.queueDebounceMs;
+            delete sessionEntry.queueCap;
+            delete sessionEntry.queueDrop;
+            updated = true;
+        }
+        if (updated) {
+            sessionEntry.updatedAt = Date.now();
+            sessionStore[sessionKey] = sessionEntry;
+            if (storePath) {
+                await saveSessionStore(storePath, sessionStore);
+            }
+        }
+    }
+    return {
+        provider,
+        model,
+        contextTokens: agentCfg?.contextTokens ??
+            lookupContextTokens(model) ??
+            DEFAULT_CONTEXT_TOKENS,
+    };
+}
+export function resolveDefaultModel(params) {
+    const mainModel = resolveConfiguredModelRef({
+        cfg: params.cfg,
+        defaultProvider: DEFAULT_PROVIDER,
+        defaultModel: DEFAULT_MODEL,
+    });
+    const defaultProvider = mainModel.provider;
+    const defaultModel = mainModel.model;
+    const aliasIndex = buildModelAliasIndex({
+        cfg: params.cfg,
+        defaultProvider,
+    });
+    return { defaultProvider, defaultModel, aliasIndex };
+}

package/dist/auto-reply/reply/directives.js

@@ -0,0 +1,47 @@
+import { normalizeElevatedLevel, normalizeThinkLevel, normalizeVerboseLevel, } from "../thinking.js";
+export function extractThinkDirective(body) {
+    if (!body)
+        return { cleaned: "", hasDirective: false };
+    // Match the longest keyword first to avoid partial captures (e.g. "/think:high")
+    const match = body.match(/(?:^|\s)\/(?:thinking|think|t)\s*:?\s*([a-zA-Z-]+)\b/i);
+    const thinkLevel = normalizeThinkLevel(match?.[1]);
+    const cleaned = match
+        ? body.replace(match[0], "").replace(/\s+/g, " ").trim()
+        : body.trim();
+    return {
+        cleaned,
+        thinkLevel,
+        rawLevel: match?.[1],
+        hasDirective: !!match,
+    };
+}
+export function extractVerboseDirective(body) {
+    if (!body)
+        return { cleaned: "", hasDirective: false };
+    const match = body.match(/(?:^|\s)\/(?:verbose|v)(?=$|\s|:)\s*:?\s*([a-zA-Z-]+)\b/i);
+    const verboseLevel = normalizeVerboseLevel(match?.[1]);
+    const cleaned = match
+        ? body.replace(match[0], "").replace(/\s+/g, " ").trim()
+        : body.trim();
+    return {
+        cleaned,
+        verboseLevel,
+        rawLevel: match?.[1],
+        hasDirective: !!match,
+    };
+}
+export function extractElevatedDirective(body) {
+    if (!body)
+        return { cleaned: "", hasDirective: false };
+    const match = body.match(/(?:^|\s)\/(?:elevated|elev)(?=$|\s|:)\s*:?\s*([a-zA-Z-]+)\b/i);
+    const elevatedLevel = normalizeElevatedLevel(match?.[1]);
+    const cleaned = match
+        ? body.replace(match[0], "").replace(/\s+/g, " ").trim()
+        : body.trim();
+    return {
+        cleaned,
+        elevatedLevel,
+        rawLevel: match?.[1],
+        hasDirective: !!match,
+    };
+}

package/dist/auto-reply/reply/followup-runner.js

@@ -0,0 +1,149 @@
+import crypto from "node:crypto";
+import { lookupContextTokens } from "../../agents/context.js";
+import { DEFAULT_CONTEXT_TOKENS } from "../../agents/defaults.js";
+import { runWithModelFallback } from "../../agents/model-fallback.js";
+import { runEmbeddedPiAgent } from "../../agents/pi-embedded.js";
+import { saveSessionStore } from "../../config/sessions.js";
+import { logVerbose } from "../../globals.js";
+import { registerAgentRunContext } from "../../infra/agent-events.js";
+import { defaultRuntime } from "../../runtime.js";
+import { stripHeartbeatToken } from "../heartbeat.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import { extractReplyToTag } from "./reply-tags.js";
+export function createFollowupRunner(params) {
+    const { opts, typing, sessionEntry, sessionStore, sessionKey, storePath, defaultModel, agentCfgContextTokens, } = params;
+    const sendFollowupPayloads = async (payloads) => {
+        if (!opts?.onBlockReply) {
+            logVerbose("followup queue: no onBlockReply handler; dropping payloads");
+            return;
+        }
+        for (const payload of payloads) {
+            if (!payload?.text && !payload?.mediaUrl && !payload?.mediaUrls?.length) {
+                continue;
+            }
+            if (payload.text?.trim() === SILENT_REPLY_TOKEN &&
+                !payload.mediaUrl &&
+                !payload.mediaUrls?.length) {
+                continue;
+            }
+            await typing.startTypingOnText(payload.text);
+            await opts.onBlockReply(payload);
+        }
+    };
+    return async (queued) => {
+        const runId = crypto.randomUUID();
+        if (queued.run.sessionKey) {
+            registerAgentRunContext(runId, { sessionKey: queued.run.sessionKey });
+        }
+        let runResult;
+        let fallbackProvider = queued.run.provider;
+        let fallbackModel = queued.run.model;
+        try {
+            const fallbackResult = await runWithModelFallback({
+                cfg: queued.run.config,
+                provider: queued.run.provider,
+                model: queued.run.model,
+                run: (provider, model) => runEmbeddedPiAgent({
+                    sessionId: queued.run.sessionId,
+                    sessionKey: queued.run.sessionKey,
+                    surface: queued.run.surface,
+                    sessionFile: queued.run.sessionFile,
+                    workspaceDir: queued.run.workspaceDir,
+                    config: queued.run.config,
+                    skillsSnapshot: queued.run.skillsSnapshot,
+                    prompt: queued.prompt,
+                    extraSystemPrompt: queued.run.extraSystemPrompt,
+                    ownerNumbers: queued.run.ownerNumbers,
+                    enforceFinalTag: queued.run.enforceFinalTag,
+                    provider,
+                    model,
+                    thinkLevel: queued.run.thinkLevel,
+                    verboseLevel: queued.run.verboseLevel,
+                    bashElevated: queued.run.bashElevated,
+                    timeoutMs: queued.run.timeoutMs,
+                    runId,
+                    blockReplyBreak: queued.run.blockReplyBreak,
+                }),
+            });
+            runResult = fallbackResult.result;
+            fallbackProvider = fallbackResult.provider;
+            fallbackModel = fallbackResult.model;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            defaultRuntime.error?.(`Followup agent failed before reply: ${message}`);
+            return;
+        }
+        const payloadArray = runResult.payloads ?? [];
+        if (payloadArray.length === 0)
+            return;
+        const sanitizedPayloads = payloadArray.flatMap((payload) => {
+            const text = payload.text;
+            if (!text || !text.includes("HEARTBEAT_OK"))
+                return [payload];
+            const stripped = stripHeartbeatToken(text, { mode: "message" });
+            const hasMedia = Boolean(payload.mediaUrl) || (payload.mediaUrls?.length ?? 0) > 0;
+            if (stripped.shouldSkip && !hasMedia)
+                return [];
+            return [{ ...payload, text: stripped.text }];
+        });
+        const replyTaggedPayloads = sanitizedPayloads
+            .map((payload) => {
+            const { cleaned, replyToId } = extractReplyToTag(payload.text);
+            return {
+                ...payload,
+                text: cleaned ? cleaned : undefined,
+                replyToId: replyToId ?? payload.replyToId,
+            };
+        })
+            .filter((payload) => payload.text ||
+            payload.mediaUrl ||
+            (payload.mediaUrls && payload.mediaUrls.length > 0));
+        if (replyTaggedPayloads.length === 0)
+            return;
+        if (sessionStore && sessionKey) {
+            const usage = runResult.meta.agentMeta?.usage;
+            const modelUsed = runResult.meta.agentMeta?.model ?? fallbackModel ?? defaultModel;
+            const contextTokensUsed = agentCfgContextTokens ??
+                lookupContextTokens(modelUsed) ??
+                sessionEntry?.contextTokens ??
+                DEFAULT_CONTEXT_TOKENS;
+            if (usage) {
+                const entry = sessionStore[sessionKey];
+                if (entry) {
+                    const input = usage.input ?? 0;
+                    const output = usage.output ?? 0;
+                    const promptTokens = input + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+                    sessionStore[sessionKey] = {
+                        ...entry,
+                        inputTokens: input,
+                        outputTokens: output,
+                        totalTokens: promptTokens > 0 ? promptTokens : (usage.total ?? input),
+                        modelProvider: fallbackProvider ?? entry.modelProvider,
+                        model: modelUsed,
+                        contextTokens: contextTokensUsed ?? entry.contextTokens,
+                        updatedAt: Date.now(),
+                    };
+                    if (storePath) {
+                        await saveSessionStore(storePath, sessionStore);
+                    }
+                }
+            }
+            else if (modelUsed || contextTokensUsed) {
+                const entry = sessionStore[sessionKey];
+                if (entry) {
+                    sessionStore[sessionKey] = {
+                        ...entry,
+                        modelProvider: fallbackProvider ?? entry.modelProvider,
+                        model: modelUsed ?? entry.model,
+                        contextTokens: contextTokensUsed ?? entry.contextTokens,
+                    };
+                    if (storePath) {
+                        await saveSessionStore(storePath, sessionStore);
+                    }
+                }
+            }
+        }
+        await sendFollowupPayloads(replyTaggedPayloads);
+    };
+}

package/dist/auto-reply/reply/groups.js

@@ -0,0 +1,91 @@
+import { normalizeGroupActivation } from "../group-activation.js";
+export function resolveGroupRequireMention(params) {
+    const { cfg, ctx, groupResolution } = params;
+    const surface = groupResolution?.surface ?? ctx.Surface?.trim().toLowerCase();
+    const groupId = groupResolution?.id ?? ctx.From?.replace(/^group:/, "");
+    if (surface === "telegram") {
+        if (groupId) {
+            const groupConfig = cfg.telegram?.groups?.[groupId];
+            if (typeof groupConfig?.requireMention === "boolean") {
+                return groupConfig.requireMention;
+            }
+        }
+        const groupDefault = cfg.telegram?.groups?.["*"]?.requireMention;
+        if (typeof groupDefault === "boolean")
+            return groupDefault;
+        return true;
+    }
+    if (surface === "whatsapp") {
+        if (groupId) {
+            const groupConfig = cfg.whatsapp?.groups?.[groupId];
+            if (typeof groupConfig?.requireMention === "boolean") {
+                return groupConfig.requireMention;
+            }
+        }
+        const groupDefault = cfg.whatsapp?.groups?.["*"]?.requireMention;
+        if (typeof groupDefault === "boolean")
+            return groupDefault;
+        return true;
+    }
+    if (surface === "imessage") {
+        if (groupId) {
+            const groupConfig = cfg.imessage?.groups?.[groupId];
+            if (typeof groupConfig?.requireMention === "boolean") {
+                return groupConfig.requireMention;
+            }
+        }
+        const groupDefault = cfg.imessage?.groups?.["*"]?.requireMention;
+        if (typeof groupDefault === "boolean")
+            return groupDefault;
+        return true;
+    }
+    return true;
+}
+export function defaultGroupActivation(requireMention) {
+    return requireMention === false ? "always" : "mention";
+}
+export function buildGroupIntro(params) {
+    const activation = normalizeGroupActivation(params.sessionEntry?.groupActivation) ??
+        params.defaultActivation;
+    const subject = params.sessionCtx.GroupSubject?.trim();
+    const members = params.sessionCtx.GroupMembers?.trim();
+    const surface = params.sessionCtx.Surface?.trim().toLowerCase();
+    const surfaceLabel = (() => {
+        if (!surface)
+            return "chat";
+        if (surface === "whatsapp")
+            return "WhatsApp";
+        if (surface === "telegram")
+            return "Telegram";
+        if (surface === "discord")
+            return "Discord";
+        if (surface === "webchat")
+            return "WebChat";
+        return `${surface.at(0)?.toUpperCase() ?? ""}${surface.slice(1)}`;
+    })();
+    const subjectLine = subject
+        ? `You are replying inside the ${surfaceLabel} group "${subject}".`
+        : `You are replying inside a ${surfaceLabel} group chat.`;
+    const membersLine = members ? `Group members: ${members}.` : undefined;
+    const activationLine = activation === "always"
+        ? "Activation: always-on (you receive every group message)."
+        : "Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included).";
+    const silenceLine = activation === "always"
+        ? `If no response is needed, reply with exactly "${params.silentToken}" (no other text) so Clawdbot stays silent.`
+        : undefined;
+    const cautionLine = activation === "always"
+        ? "Be extremely selective: reply only when you are directly addressed, asked a question, or can add clear value. Otherwise stay silent."
+        : undefined;
+    const lurkLine = "Be a good group participant: lurk and follow the conversation, but only chime in when you have something genuinely helpful or relevant to add. Don't feel obligated to respond to every message — quality over quantity. Even when lurking silently, you can use emoji reactions to acknowledge messages, show support, or react to humor — reactions are always appreciated and don't clutter the chat.";
+    return [
+        subjectLine,
+        membersLine,
+        activationLine,
+        silenceLine,
+        cautionLine,
+        lurkLine,
+    ]
+        .filter(Boolean)
+        .join(" ")
+        .concat(" Address the specific sender noted in the message context.");
+}