clawdbot 2026.1.4-1

package/dist/agents/tools/slack-actions.js

@@ -0,0 +1,129 @@
+import { deleteSlackMessage, editSlackMessage, getSlackMemberInfo, listSlackEmojis, listSlackPins, listSlackReactions, pinSlackMessage, reactSlackMessage, readSlackMessages, sendSlackMessage, unpinSlackMessage, } from "../../slack/actions.js";
+import { jsonResult, readStringParam } from "./common.js";
+const messagingActions = new Set([
+    "sendMessage",
+    "editMessage",
+    "deleteMessage",
+    "readMessages",
+]);
+const reactionsActions = new Set(["react", "reactions"]);
+const pinActions = new Set(["pinMessage", "unpinMessage", "listPins"]);
+export async function handleSlackAction(params, cfg) {
+    const action = readStringParam(params, "action", { required: true });
+    const isActionEnabled = (key, defaultValue = true) => {
+        const value = cfg.slack?.actions?.[key];
+        if (value === undefined)
+            return defaultValue;
+        return value !== false;
+    };
+    if (reactionsActions.has(action)) {
+        if (!isActionEnabled("reactions")) {
+            throw new Error("Slack reactions are disabled.");
+        }
+        const channelId = readStringParam(params, "channelId", { required: true });
+        const messageId = readStringParam(params, "messageId", { required: true });
+        if (action === "react") {
+            const emoji = readStringParam(params, "emoji", { required: true });
+            await reactSlackMessage(channelId, messageId, emoji);
+            return jsonResult({ ok: true });
+        }
+        const reactions = await listSlackReactions(channelId, messageId);
+        return jsonResult({ ok: true, reactions });
+    }
+    if (messagingActions.has(action)) {
+        if (!isActionEnabled("messages")) {
+            throw new Error("Slack messages are disabled.");
+        }
+        switch (action) {
+            case "sendMessage": {
+                const to = readStringParam(params, "to", { required: true });
+                const content = readStringParam(params, "content", { required: true });
+                const mediaUrl = readStringParam(params, "mediaUrl");
+                const result = await sendSlackMessage(to, content, {
+                    mediaUrl: mediaUrl ?? undefined,
+                });
+                return jsonResult({ ok: true, result });
+            }
+            case "editMessage": {
+                const channelId = readStringParam(params, "channelId", {
+                    required: true,
+                });
+                const messageId = readStringParam(params, "messageId", {
+                    required: true,
+                });
+                const content = readStringParam(params, "content", {
+                    required: true,
+                });
+                await editSlackMessage(channelId, messageId, content);
+                return jsonResult({ ok: true });
+            }
+            case "deleteMessage": {
+                const channelId = readStringParam(params, "channelId", {
+                    required: true,
+                });
+                const messageId = readStringParam(params, "messageId", {
+                    required: true,
+                });
+                await deleteSlackMessage(channelId, messageId);
+                return jsonResult({ ok: true });
+            }
+            case "readMessages": {
+                const channelId = readStringParam(params, "channelId", {
+                    required: true,
+                });
+                const limitRaw = params.limit;
+                const limit = typeof limitRaw === "number" && Number.isFinite(limitRaw)
+                    ? limitRaw
+                    : undefined;
+                const before = readStringParam(params, "before");
+                const after = readStringParam(params, "after");
+                const result = await readSlackMessages(channelId, {
+                    limit,
+                    before: before ?? undefined,
+                    after: after ?? undefined,
+                });
+                return jsonResult({ ok: true, ...result });
+            }
+            default:
+                break;
+        }
+    }
+    if (pinActions.has(action)) {
+        if (!isActionEnabled("pins")) {
+            throw new Error("Slack pins are disabled.");
+        }
+        const channelId = readStringParam(params, "channelId", { required: true });
+        if (action === "pinMessage") {
+            const messageId = readStringParam(params, "messageId", {
+                required: true,
+            });
+            await pinSlackMessage(channelId, messageId);
+            return jsonResult({ ok: true });
+        }
+        if (action === "unpinMessage") {
+            const messageId = readStringParam(params, "messageId", {
+                required: true,
+            });
+            await unpinSlackMessage(channelId, messageId);
+            return jsonResult({ ok: true });
+        }
+        const pins = await listSlackPins(channelId);
+        return jsonResult({ ok: true, pins });
+    }
+    if (action === "memberInfo") {
+        if (!isActionEnabled("memberInfo")) {
+            throw new Error("Slack member info is disabled.");
+        }
+        const userId = readStringParam(params, "userId", { required: true });
+        const info = await getSlackMemberInfo(userId);
+        return jsonResult({ ok: true, info });
+    }
+    if (action === "emojiList") {
+        if (!isActionEnabled("emojiList")) {
+            throw new Error("Slack emoji list is disabled.");
+        }
+        const emojis = await listSlackEmojis();
+        return jsonResult({ ok: true, emojis });
+    }
+    throw new Error(`Unknown action: ${action}`);
+}

package/dist/agents/tools/slack-schema.js

@@ -0,0 +1,59 @@
+import { Type } from "@sinclair/typebox";
+export const SlackToolSchema = Type.Union([
+    Type.Object({
+        action: Type.Literal("react"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+        emoji: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("reactions"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("sendMessage"),
+        to: Type.String(),
+        content: Type.String(),
+        mediaUrl: Type.Optional(Type.String()),
+    }),
+    Type.Object({
+        action: Type.Literal("editMessage"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+        content: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("deleteMessage"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("readMessages"),
+        channelId: Type.String(),
+        limit: Type.Optional(Type.Number()),
+        before: Type.Optional(Type.String()),
+        after: Type.Optional(Type.String()),
+    }),
+    Type.Object({
+        action: Type.Literal("pinMessage"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("unpinMessage"),
+        channelId: Type.String(),
+        messageId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("listPins"),
+        channelId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("memberInfo"),
+        userId: Type.String(),
+    }),
+    Type.Object({
+        action: Type.Literal("emojiList"),
+    }),
+]);

package/dist/agents/tools/slack-tool.js

@@ -0,0 +1,16 @@
+import { loadConfig } from "../../config/config.js";
+import { handleSlackAction } from "./slack-actions.js";
+import { SlackToolSchema } from "./slack-schema.js";
+export function createSlackTool() {
+    return {
+        label: "Slack",
+        name: "slack",
+        description: "Manage Slack messages, reactions, and pins.",
+        parameters: SlackToolSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const cfg = loadConfig();
+            return await handleSlackAction(params, cfg);
+        },
+    };
+}

package/dist/agents/usage.js

@@ -0,0 +1,39 @@
+const asFiniteNumber = (value) => {
+    if (typeof value !== "number")
+        return undefined;
+    if (!Number.isFinite(value))
+        return undefined;
+    return value;
+};
+export function normalizeUsage(raw) {
+    if (!raw)
+        return undefined;
+    const input = asFiniteNumber(raw.input);
+    const output = asFiniteNumber(raw.output);
+    const cacheRead = asFiniteNumber(raw.cacheRead ?? raw.cache_read);
+    const cacheWrite = asFiniteNumber(raw.cacheWrite ?? raw.cache_write);
+    const total = asFiniteNumber(raw.total ?? raw.totalTokens ?? raw.total_tokens);
+    if (input === undefined &&
+        output === undefined &&
+        cacheRead === undefined &&
+        cacheWrite === undefined &&
+        total === undefined) {
+        return undefined;
+    }
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        total,
+    };
+}
+export function derivePromptTokens(usage) {
+    if (!usage)
+        return undefined;
+    const input = usage.input ?? 0;
+    const cacheRead = usage.cacheRead ?? 0;
+    const cacheWrite = usage.cacheWrite ?? 0;
+    const sum = input + cacheRead + cacheWrite;
+    return sum > 0 ? sum : undefined;
+}

package/dist/agents/workspace.js

@@ -0,0 +1,241 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveUserPath } from "../utils.js";
+export const DEFAULT_AGENT_WORKSPACE_DIR = path.join(os.homedir(), "clawd");
+export const DEFAULT_AGENTS_FILENAME = "AGENTS.md";
+export const DEFAULT_SOUL_FILENAME = "SOUL.md";
+export const DEFAULT_TOOLS_FILENAME = "TOOLS.md";
+export const DEFAULT_IDENTITY_FILENAME = "IDENTITY.md";
+export const DEFAULT_USER_FILENAME = "USER.md";
+export const DEFAULT_BOOTSTRAP_FILENAME = "BOOTSTRAP.md";
+const DEFAULT_AGENTS_TEMPLATE = `# AGENTS.md - Clawdbot Workspace
+
+This folder is the assistant's working directory.
+
+## First run (one-time)
+- If BOOTSTRAP.md exists, follow its ritual and delete it once complete.
+- Your agent identity lives in IDENTITY.md.
+- Your profile lives in USER.md.
+
+## Backup tip (recommended)
+If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
+and notes are backed up.
+
+\`\`\`bash
+git init
+git add AGENTS.md
+git commit -m "Add agent workspace"
+\`\`\`
+
+## Safety defaults
+- Don't exfiltrate secrets or private data.
+- Don't run destructive commands unless explicitly asked.
+- Be concise in chat; write longer output to files in this workspace.
+
+## Daily memory (recommended)
+- Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed).
+- On session start, read today + yesterday if present.
+- Capture durable facts, preferences, and decisions; avoid secrets.
+
+## Customize
+- Add your preferred style, rules, and "memory" here.
+`;
+const DEFAULT_SOUL_TEMPLATE = `# SOUL.md - Persona & Boundaries
+
+Describe who the assistant is, tone, and boundaries.
+
+- Keep replies concise and direct.
+- Ask clarifying questions when needed.
+- Never send streaming/partial replies to external messaging surfaces.
+`;
+const DEFAULT_TOOLS_TEMPLATE = `# TOOLS.md - User Tool Notes (editable)
+
+This file is for *your* notes about external tools and conventions.
+It does not define which tools exist; Clawdbot provides built-in tools internally.
+
+## Examples
+
+### imsg
+- Send an iMessage/SMS: describe who/what, confirm before sending.
+- Prefer short messages; avoid sending secrets.
+
+### sag
+- Text-to-speech: specify voice, target speaker/room, and whether to stream.
+
+Add whatever else you want the assistant to know about your local toolchain.
+`;
+const DEFAULT_BOOTSTRAP_TEMPLATE = `# BOOTSTRAP.md - First Run Ritual (delete after)
+
+Hello. I was just born.
+
+## Your mission
+Start a short, playful conversation and learn:
+- Who am I?
+- What am I?
+- Who are you?
+- How should I call you?
+
+## How to ask (cute + helpful)
+Say:
+"Hello! I was just born. Who am I? What am I? Who are you? How should I call you?"
+
+Then offer suggestions:
+- 3-5 name ideas.
+- 3-5 creature/vibe combos.
+- 5 emoji ideas.
+
+## Write these files
+After the user chooses, update:
+
+1) IDENTITY.md
+- Name
+- Creature
+- Vibe
+- Emoji
+
+2) USER.md
+- Name
+- Preferred address
+- Pronouns (optional)
+- Timezone (optional)
+- Notes
+
+3) ~/.clawdbot/clawdbot.json
+Set identity.name, identity.theme, identity.emoji to match IDENTITY.md.
+
+## Cleanup
+Delete BOOTSTRAP.md once this is complete.
+`;
+const DEFAULT_IDENTITY_TEMPLATE = `# IDENTITY.md - Agent Identity
+
+- Name:
+- Creature:
+- Vibe:
+- Emoji:
+`;
+const DEFAULT_USER_TEMPLATE = `# USER.md - User Profile
+
+- Name:
+- Preferred address:
+- Pronouns (optional):
+- Timezone (optional):
+- Notes:
+`;
+const TEMPLATE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../docs/templates");
+function stripFrontMatter(content) {
+    if (!content.startsWith("---"))
+        return content;
+    const endIndex = content.indexOf("\n---", 3);
+    if (endIndex === -1)
+        return content;
+    const start = endIndex + "\n---".length;
+    let trimmed = content.slice(start);
+    trimmed = trimmed.replace(/^\s+/, "");
+    return trimmed;
+}
+async function loadTemplate(name, fallback) {
+    const templatePath = path.join(TEMPLATE_DIR, name);
+    try {
+        const content = await fs.readFile(templatePath, "utf-8");
+        return stripFrontMatter(content);
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeFileIfMissing(filePath, content) {
+    try {
+        await fs.writeFile(filePath, content, {
+            encoding: "utf-8",
+            flag: "wx",
+        });
+    }
+    catch (err) {
+        const anyErr = err;
+        if (anyErr.code !== "EEXIST")
+            throw err;
+    }
+}
+export async function ensureAgentWorkspace(params) {
+    const rawDir = params?.dir?.trim()
+        ? params.dir.trim()
+        : DEFAULT_AGENT_WORKSPACE_DIR;
+    const dir = resolveUserPath(rawDir);
+    await fs.mkdir(dir, { recursive: true });
+    if (!params?.ensureBootstrapFiles)
+        return { dir };
+    const agentsPath = path.join(dir, DEFAULT_AGENTS_FILENAME);
+    const soulPath = path.join(dir, DEFAULT_SOUL_FILENAME);
+    const toolsPath = path.join(dir, DEFAULT_TOOLS_FILENAME);
+    const identityPath = path.join(dir, DEFAULT_IDENTITY_FILENAME);
+    const userPath = path.join(dir, DEFAULT_USER_FILENAME);
+    const bootstrapPath = path.join(dir, DEFAULT_BOOTSTRAP_FILENAME);
+    const agentsTemplate = await loadTemplate(DEFAULT_AGENTS_FILENAME, DEFAULT_AGENTS_TEMPLATE);
+    const soulTemplate = await loadTemplate(DEFAULT_SOUL_FILENAME, DEFAULT_SOUL_TEMPLATE);
+    const toolsTemplate = await loadTemplate(DEFAULT_TOOLS_FILENAME, DEFAULT_TOOLS_TEMPLATE);
+    const identityTemplate = await loadTemplate(DEFAULT_IDENTITY_FILENAME, DEFAULT_IDENTITY_TEMPLATE);
+    const userTemplate = await loadTemplate(DEFAULT_USER_FILENAME, DEFAULT_USER_TEMPLATE);
+    const bootstrapTemplate = await loadTemplate(DEFAULT_BOOTSTRAP_FILENAME, DEFAULT_BOOTSTRAP_TEMPLATE);
+    await writeFileIfMissing(agentsPath, agentsTemplate);
+    await writeFileIfMissing(soulPath, soulTemplate);
+    await writeFileIfMissing(toolsPath, toolsTemplate);
+    await writeFileIfMissing(identityPath, identityTemplate);
+    await writeFileIfMissing(userPath, userTemplate);
+    await writeFileIfMissing(bootstrapPath, bootstrapTemplate);
+    return {
+        dir,
+        agentsPath,
+        soulPath,
+        toolsPath,
+        identityPath,
+        userPath,
+        bootstrapPath,
+    };
+}
+export async function loadWorkspaceBootstrapFiles(dir) {
+    const resolvedDir = resolveUserPath(dir);
+    const entries = [
+        {
+            name: DEFAULT_AGENTS_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_AGENTS_FILENAME),
+        },
+        {
+            name: DEFAULT_SOUL_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_SOUL_FILENAME),
+        },
+        {
+            name: DEFAULT_TOOLS_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_TOOLS_FILENAME),
+        },
+        {
+            name: DEFAULT_IDENTITY_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_IDENTITY_FILENAME),
+        },
+        {
+            name: DEFAULT_USER_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_USER_FILENAME),
+        },
+        {
+            name: DEFAULT_BOOTSTRAP_FILENAME,
+            filePath: path.join(resolvedDir, DEFAULT_BOOTSTRAP_FILENAME),
+        },
+    ];
+    const result = [];
+    for (const entry of entries) {
+        try {
+            const content = await fs.readFile(entry.filePath, "utf-8");
+            result.push({
+                name: entry.name,
+                path: entry.filePath,
+                content,
+                missing: false,
+            });
+        }
+        catch {
+            result.push({ name: entry.name, path: entry.filePath, missing: true });
+        }
+    }
+    return result;
+}

package/dist/auto-reply/chunk.js

@@ -0,0 +1,76 @@
+// Utilities for splitting outbound text into platform-sized chunks without
+// unintentionally breaking on newlines. Using [\s\S] keeps newlines inside
+// the chunk so messages are only split when they truly exceed the limit.
+const DEFAULT_CHUNK_LIMIT_BY_SURFACE = {
+    whatsapp: 4000,
+    telegram: 4000,
+    discord: 2000,
+    slack: 4000,
+    signal: 4000,
+    imessage: 4000,
+    webchat: 4000,
+};
+export function resolveTextChunkLimit(cfg, surface) {
+    const surfaceOverride = (() => {
+        if (!surface)
+            return undefined;
+        if (surface === "whatsapp")
+            return cfg?.whatsapp?.textChunkLimit;
+        if (surface === "telegram")
+            return cfg?.telegram?.textChunkLimit;
+        if (surface === "discord")
+            return cfg?.discord?.textChunkLimit;
+        if (surface === "slack")
+            return cfg?.slack?.textChunkLimit;
+        if (surface === "signal")
+            return cfg?.signal?.textChunkLimit;
+        if (surface === "imessage")
+            return cfg?.imessage?.textChunkLimit;
+        return undefined;
+    })();
+    if (typeof surfaceOverride === "number" && surfaceOverride > 0) {
+        return surfaceOverride;
+    }
+    if (surface)
+        return DEFAULT_CHUNK_LIMIT_BY_SURFACE[surface];
+    return 4000;
+}
+export function chunkText(text, limit) {
+    if (!text)
+        return [];
+    if (limit <= 0)
+        return [text];
+    if (text.length <= limit)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > limit) {
+        const window = remaining.slice(0, limit);
+        // 1) Prefer a newline break inside the window.
+        let breakIdx = window.lastIndexOf("\n");
+        // 2) Otherwise prefer the last whitespace (word boundary) inside the window.
+        if (breakIdx <= 0) {
+            for (let i = window.length - 1; i >= 0; i--) {
+                if (/\s/.test(window[i])) {
+                    breakIdx = i;
+                    break;
+                }
+            }
+        }
+        // 3) Fallback: hard break exactly at the limit.
+        if (breakIdx <= 0)
+            breakIdx = limit;
+        const rawChunk = remaining.slice(0, breakIdx);
+        const chunk = rawChunk.trimEnd();
+        if (chunk.length > 0) {
+            chunks.push(chunk);
+        }
+        // If we broke on whitespace/newline, skip that separator; for hard breaks keep it.
+        const brokeOnSeparator = breakIdx < remaining.length && /\s/.test(remaining[breakIdx]);
+        const nextStart = Math.min(remaining.length, breakIdx + (brokeOnSeparator ? 1 : 0));
+        remaining = remaining.slice(nextStart).trimStart();
+    }
+    if (remaining.length)
+        chunks.push(remaining);
+    return chunks;
+}

package/dist/auto-reply/envelope.js

@@ -0,0 +1,38 @@
+function formatTimestamp(ts) {
+    if (!ts)
+        return undefined;
+    const date = ts instanceof Date ? ts : new Date(ts);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    const yyyy = String(date.getFullYear()).padStart(4, "0");
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    const hh = String(date.getHours()).padStart(2, "0");
+    const min = String(date.getMinutes()).padStart(2, "0");
+    // getTimezoneOffset() is minutes *behind* UTC. Flip sign to get ISO offset.
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absOffsetMinutes = Math.abs(offsetMinutes);
+    const offsetH = String(Math.floor(absOffsetMinutes / 60)).padStart(2, "0");
+    const offsetM = String(absOffsetMinutes % 60).padStart(2, "0");
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const tzSuffix = tz ? `{${tz}}` : "";
+    // Compact ISO-like *local* timestamp with minutes precision.
+    // Example: 2025-01-02T03:04-08:00{America/Los_Angeles}
+    return `${yyyy}-${mm}-${dd}T${hh}:${min}${sign}${offsetH}:${offsetM}${tzSuffix}`;
+}
+export function formatAgentEnvelope(params) {
+    const surface = params.surface?.trim() || "Surface";
+    const parts = [surface];
+    if (params.from?.trim())
+        parts.push(params.from.trim());
+    if (params.host?.trim())
+        parts.push(params.host.trim());
+    if (params.ip?.trim())
+        parts.push(params.ip.trim());
+    const ts = formatTimestamp(params.timestamp);
+    if (ts)
+        parts.push(ts);
+    const header = `[${parts.join(" ")}]`;
+    return `${header} ${params.body}`;
+}

package/dist/auto-reply/group-activation.js

@@ -0,0 +1,20 @@
+export function normalizeGroupActivation(raw) {
+    const value = raw?.trim().toLowerCase();
+    if (value === "mention")
+        return "mention";
+    if (value === "always")
+        return "always";
+    return undefined;
+}
+export function parseActivationCommand(raw) {
+    if (!raw)
+        return { hasCommand: false };
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { hasCommand: false };
+    const match = trimmed.match(/^\/?activation\b(?:\s+([a-zA-Z]+))?/i);
+    if (!match)
+        return { hasCommand: false };
+    const mode = normalizeGroupActivation(match[1]);
+    return { hasCommand: true, mode };
+}

package/dist/auto-reply/heartbeat.js

@@ -0,0 +1,57 @@
+import { HEARTBEAT_TOKEN } from "./tokens.js";
+export const HEARTBEAT_PROMPT = "HEARTBEAT";
+function stripTokenAtEdges(raw) {
+    let text = raw.trim();
+    if (!text)
+        return { text: "", didStrip: false };
+    const token = HEARTBEAT_TOKEN;
+    if (!text.includes(token))
+        return { text, didStrip: false };
+    let didStrip = false;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const next = text.trim();
+        if (next.startsWith(token)) {
+            const after = next.slice(token.length).trimStart();
+            text = after;
+            didStrip = true;
+            changed = true;
+            continue;
+        }
+        if (next.endsWith(token)) {
+            const before = next.slice(0, Math.max(0, next.length - token.length));
+            text = before.trimEnd();
+            didStrip = true;
+            changed = true;
+        }
+    }
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return { text: collapsed, didStrip };
+}
+export function stripHeartbeatToken(raw, opts = {}) {
+    if (!raw)
+        return { shouldSkip: true, text: "", didStrip: false };
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { shouldSkip: true, text: "", didStrip: false };
+    const mode = opts.mode ?? "message";
+    const maxAckChars = Math.max(0, opts.maxAckChars ?? 30);
+    if (!trimmed.includes(HEARTBEAT_TOKEN)) {
+        return { shouldSkip: false, text: trimmed, didStrip: false };
+    }
+    const stripped = stripTokenAtEdges(trimmed);
+    if (!stripped.didStrip) {
+        return { shouldSkip: false, text: trimmed, didStrip: false };
+    }
+    if (!stripped.text) {
+        return { shouldSkip: true, text: "", didStrip: true };
+    }
+    if (mode === "heartbeat") {
+        const rest = stripped.text.trim();
+        if (rest.length <= maxAckChars) {
+            return { shouldSkip: true, text: "", didStrip: true };
+        }
+    }
+    return { shouldSkip: false, text: stripped.text, didStrip: true };
+}