@poolzin/pool-bot 2026.2.0 → 2026.2.2

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

@@ -1,9 +1,10 @@
 import { Type } from "@sinclair/typebox";
-import { normalizeCronJobCreate, normalizeCronJobPatch } from "../../cron/normalize.js";
 import { loadConfig } from "../../config/config.js";
-import { truncateUtf16Safe } from "../../utils.js";
-import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
+import { normalizeCronJobCreate, normalizeCronJobPatch } from "../../cron/normalize.js";
+import { parseAgentSessionKey } from "../../sessions/session-key-utils.js";
+import { isRecord, truncateUtf16Safe } from "../../utils.js";
 import { resolveSessionAgentId } from "../agent-scope.js";
+import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
 import { jsonResult, readStringParam } from "./common.js";
 import { callGatewayTool } from "./gateway.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./sessions-helpers.js";
@@ -13,6 +14,7 @@ import { resolveInternalSessionKey, resolveMainSessionAlias } from "./sessions-h
 // accept "any object" here and validate at runtime.
 const CRON_ACTIONS = ["status", "list", "add", "update", "remove", "run", "runs", "wake"];
 const CRON_WAKE_MODES = ["now", "next-heartbeat"];
+const CRON_RUN_MODES = ["due", "force"];
 const REMINDER_CONTEXT_MESSAGES_MAX = 10;
 const REMINDER_CONTEXT_PER_MESSAGE_MAX = 220;
 const REMINDER_CONTEXT_TOTAL_MAX = 700;
@@ -30,17 +32,20 @@ const CronToolSchema = Type.Object({
     patch: Type.Optional(Type.Object({}, { additionalProperties: true })),
     text: Type.Optional(Type.String()),
     mode: optionalStringEnum(CRON_WAKE_MODES),
+    runMode: optionalStringEnum(CRON_RUN_MODES),
     contextMessages: Type.Optional(Type.Number({ minimum: 0, maximum: REMINDER_CONTEXT_MESSAGES_MAX })),
 });
 function stripExistingContext(text) {
     const index = text.indexOf(REMINDER_CONTEXT_MARKER);
-    if (index === -1)
+    if (index === -1) {
         return text;
+    }
     return text.slice(0, index).trim();
 }
 function truncateText(input, maxLen) {
-    if (input.length <= maxLen)
+    if (input.length <= maxLen) {
         return input;
+    }
     const truncated = truncateUtf16Safe(input, Math.max(0, maxLen - 3)).trimEnd();
     return `${truncated}...`;
 }
@@ -49,21 +54,25 @@ function normalizeContextText(raw) {
 }
 function extractMessageText(message) {
     const role = typeof message.role === "string" ? message.role : "";
-    if (role !== "user" && role !== "assistant")
+    if (role !== "user" && role !== "assistant") {
         return null;
+    }
     const content = message.content;
     if (typeof content === "string") {
         const normalized = normalizeContextText(content);
         return normalized ? { role, text: normalized } : null;
     }
-    if (!Array.isArray(content))
+    if (!Array.isArray(content)) {
         return null;
+    }
     const chunks = [];
     for (const block of content) {
-        if (!block || typeof block !== "object")
+        if (!block || typeof block !== "object") {
             continue;
-        if (block.type !== "text")
+        }
+        if (block.type !== "text") {
             continue;
+        }
         const text = block.text;
         if (typeof text === "string" && text.trim()) {
             chunks.push(text);
@@ -74,26 +83,29 @@ function extractMessageText(message) {
 }
 async function buildReminderContextLines(params) {
     const maxMessages = Math.min(REMINDER_CONTEXT_MESSAGES_MAX, Math.max(0, Math.floor(params.contextMessages)));
-    if (maxMessages <= 0)
+    if (maxMessages <= 0) {
         return [];
+    }
     const sessionKey = params.agentSessionKey?.trim();
-    if (!sessionKey)
+    if (!sessionKey) {
         return [];
+    }
     const cfg = loadConfig();
     const { mainKey, alias } = resolveMainSessionAlias(cfg);
     const resolvedKey = resolveInternalSessionKey({ key: sessionKey, alias, mainKey });
     try {
-        const res = (await callGatewayTool("chat.history", params.gatewayOpts, {
+        const res = await callGatewayTool("chat.history", params.gatewayOpts, {
             sessionKey: resolvedKey,
             limit: maxMessages,
-        }));
+        });
         const messages = Array.isArray(res?.messages) ? res.messages : [];
         const parsed = messages
             .map((msg) => extractMessageText(msg))
             .filter((msg) => Boolean(msg));
         const recent = parsed.slice(-maxMessages);
-        if (recent.length === 0)
+        if (recent.length === 0) {
             return [];
+        }
         const lines = [];
         let total = 0;
         for (const entry of recent) {
@@ -101,8 +113,9 @@ async function buildReminderContextLines(params) {
             const text = truncateText(entry.text, REMINDER_CONTEXT_PER_MESSAGE_MAX);
             const line = `- ${label}: ${text}`;
             total += line.length;
-            if (total > REMINDER_CONTEXT_TOTAL_MAX)
+            if (total > REMINDER_CONTEXT_TOTAL_MAX) {
                 break;
+            }
             lines.push(line);
         }
         return lines;
@@ -111,6 +124,62 @@ async function buildReminderContextLines(params) {
         return [];
     }
 }
+function stripThreadSuffixFromSessionKey(sessionKey) {
+    const normalized = sessionKey.toLowerCase();
+    const idx = normalized.lastIndexOf(":thread:");
+    if (idx <= 0) {
+        return sessionKey;
+    }
+    const parent = sessionKey.slice(0, idx).trim();
+    return parent ? parent : sessionKey;
+}
+function inferDeliveryFromSessionKey(agentSessionKey) {
+    const rawSessionKey = agentSessionKey?.trim();
+    if (!rawSessionKey) {
+        return null;
+    }
+    const parsed = parseAgentSessionKey(stripThreadSuffixFromSessionKey(rawSessionKey));
+    if (!parsed || !parsed.rest) {
+        return null;
+    }
+    const parts = parsed.rest.split(":").filter(Boolean);
+    if (parts.length === 0) {
+        return null;
+    }
+    const head = parts[0]?.trim().toLowerCase();
+    if (!head || head === "main" || head === "subagent" || head === "acp") {
+        return null;
+    }
+    // buildAgentPeerSessionKey encodes peers as:
+    // - direct:<peerId>
+    // - <channel>:direct:<peerId>
+    // - <channel>:<accountId>:direct:<peerId>
+    // - <channel>:group:<peerId>
+    // - <channel>:channel:<peerId>
+    // Note: legacy keys may use "dm" instead of "direct".
+    // Threaded sessions append :thread:<id>, which we strip so delivery targets the parent peer.
+    // NOTE: Telegram forum topics encode as <chatId>:topic:<topicId> and should be preserved.
+    const markerIndex = parts.findIndex((part) => part === "direct" || part === "dm" || part === "group" || part === "channel");
+    if (markerIndex === -1) {
+        return null;
+    }
+    const peerId = parts
+        .slice(markerIndex + 1)
+        .join(":")
+        .trim();
+    if (!peerId) {
+        return null;
+    }
+    let channel;
+    if (markerIndex >= 1) {
+        channel = parts[0]?.trim().toLowerCase();
+    }
+    const delivery = { mode: "announce", to: peerId };
+    if (channel) {
+        delivery.channel = channel;
+    }
+    return delivery;
+}
 export function createCronTool(opts) {
     return {
         label: "Cron",
@@ -132,27 +201,36 @@ JOB SCHEMA (for add action):
   "name": "string (optional)",
   "schedule": { ... },      // Required: when to run
   "payload": { ... },       // Required: what to execute
+  "delivery": { ... },      // Optional: announce summary (isolated only)
   "sessionTarget": "main" | "isolated",  // Required
   "enabled": true | false   // Optional, default true
 }
 
 SCHEDULE TYPES (schedule.kind):
 - "at": One-shot at absolute time
-  { "kind": "at", "atMs": <unix-ms-timestamp> }
+  { "kind": "at", "at": "<ISO-8601 timestamp>" }
 - "every": Recurring interval
   { "kind": "every", "everyMs": <interval-ms>, "anchorMs": <optional-start-ms> }
 - "cron": Cron expression
   { "kind": "cron", "expr": "<cron-expression>", "tz": "<optional-timezone>" }
 
+ISO timestamps without an explicit timezone are treated as UTC.
+
 PAYLOAD TYPES (payload.kind):
 - "systemEvent": Injects text as system event into session
   { "kind": "systemEvent", "text": "<message>" }
 - "agentTurn": Runs agent with message (isolated sessions only)
-  { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional>, "deliver": <optional-bool>, "channel": "<optional>", "to": "<optional>", "bestEffortDeliver": <optional-bool> }
+  { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional> }
+
+DELIVERY (isolated-only, top-level):
+  { "mode": "none|announce", "channel": "<optional>", "to": "<optional>", "bestEffort": <optional-bool> }
+  - Default for isolated agentTurn jobs (when delivery omitted): "announce"
+  - If the task needs to send to a specific chat/recipient, set delivery.channel/to here; do not call messaging tools inside the run.
 
 CRITICAL CONSTRAINTS:
 - sessionTarget="main" REQUIRES payload.kind="systemEvent"
 - sessionTarget="isolated" REQUIRES payload.kind="agentTurn"
+Default: prefer isolated agentTurn jobs unless the user explicitly wants a main-session system event.
 
 WAKE MODES (for wake action):
 - "next-heartbeat" (default): Wake on next heartbeat
@@ -166,7 +244,7 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
             const gatewayOpts = {
                 gatewayUrl: readStringParam(params, "gatewayUrl", { trim: false }),
                 gatewayToken: readStringParam(params, "gatewayToken", { trim: false }),
-                timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : undefined,
+                timeoutMs: typeof params.timeoutMs === "number" ? params.timeoutMs : 60_000,
             };
             switch (action) {
                 case "status":
@@ -176,6 +254,52 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                         includeDisabled: Boolean(params.includeDisabled),
                     }));
                 case "add": {
+                    // Flat-params recovery: non-frontier models (e.g. Grok) sometimes flatten
+                    // job properties to the top level alongside `action` instead of nesting
+                    // them inside `job`. When `params.job` is missing or empty, reconstruct
+                    // a synthetic job object from any recognised top-level job fields.
+                    // See: https://github.com/openclaw/openclaw/issues/11310
+                    if (!params.job ||
+                        (typeof params.job === "object" &&
+                            params.job !== null &&
+                            Object.keys(params.job).length === 0)) {
+                        const JOB_KEYS = new Set([
+                            "name",
+                            "schedule",
+                            "sessionTarget",
+                            "wakeMode",
+                            "payload",
+                            "delivery",
+                            "enabled",
+                            "description",
+                            "deleteAfterRun",
+                            "agentId",
+                            "message",
+                            "text",
+                            "model",
+                            "thinking",
+                            "timeoutSeconds",
+                            "allowUnsafeExternalContent",
+                        ]);
+                        const synthetic = {};
+                        let found = false;
+                        for (const key of Object.keys(params)) {
+                            if (JOB_KEYS.has(key) && params[key] !== undefined) {
+                                synthetic[key] = params[key];
+                                found = true;
+                            }
+                        }
+                        // Only use the synthetic job if at least one meaningful field is present
+                        // (schedule, payload, message, or text are the minimum signals that the
+                        // LLM intended to create a job).
+                        if (found &&
+                            (synthetic.schedule !== undefined ||
+                                synthetic.payload !== undefined ||
+                                synthetic.message !== undefined ||
+                                synthetic.text !== undefined)) {
+                            params.job = synthetic;
+                        }
+                    }
                     if (!params.job || typeof params.job !== "object") {
                         throw new Error("job required");
                     }
@@ -189,6 +313,28 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                             job.agentId = agentId;
                         }
                     }
+                    if (opts?.agentSessionKey &&
+                        job &&
+                        typeof job === "object" &&
+                        "payload" in job &&
+                        job.payload?.kind === "agentTurn") {
+                        const deliveryValue = job.delivery;
+                        const delivery = isRecord(deliveryValue) ? deliveryValue : undefined;
+                        const modeRaw = typeof delivery?.mode === "string" ? delivery.mode : "";
+                        const mode = modeRaw.trim().toLowerCase();
+                        const hasTarget = (typeof delivery?.channel === "string" && delivery.channel.trim()) ||
+                            (typeof delivery?.to === "string" && delivery.to.trim());
+                        const shouldInfer = (deliveryValue == null || delivery) && mode !== "none" && !hasTarget;
+                        if (shouldInfer) {
+                            const inferred = inferDeliveryFromSessionKey(opts.agentSessionKey);
+                            if (inferred) {
+                                job.delivery = {
+                                    ...delivery,
+                                    ...inferred,
+                                };
+                            }
+                        }
+                    }
                     const contextMessages = typeof params.contextMessages === "number" && Number.isFinite(params.contextMessages)
                         ? params.contextMessages
                         : 0;
@@ -237,7 +383,8 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
                     if (!id) {
                         throw new Error("jobId required (id accepted for backward compatibility)");
                     }
-                    return jsonResult(await callGatewayTool("cron.run", gatewayOpts, { id }));
+                    const runMode = params.runMode === "due" || params.runMode === "force" ? params.runMode : "force";
+                    return jsonResult(await callGatewayTool("cron.run", gatewayOpts, { id, mode: runMode }));
                 }
                 case "runs": {
                     const id = readStringParam(params, "jobId") ?? readStringParam(params, "id");

package/dist/agents/tools/discord-actions-presence.js

@@ -0,0 +1,78 @@
+import { getGateway } from "../../discord/monitor/gateway-registry.js";
+import { jsonResult, readStringParam } from "./common.js";
+const ACTIVITY_TYPE_MAP = {
+    playing: 0,
+    streaming: 1,
+    listening: 2,
+    watching: 3,
+    custom: 4,
+    competing: 5,
+};
+const VALID_STATUSES = new Set(["online", "dnd", "idle", "invisible"]);
+export async function handleDiscordPresenceAction(action, params, isActionEnabled) {
+    if (action !== "setPresence") {
+        throw new Error(`Unknown presence action: ${action}`);
+    }
+    if (!isActionEnabled("presence", false)) {
+        throw new Error("Discord presence changes are disabled.");
+    }
+    const accountId = readStringParam(params, "accountId");
+    const gateway = getGateway(accountId);
+    if (!gateway) {
+        throw new Error(`Discord gateway not available${accountId ? ` for account "${accountId}"` : ""}. The bot may not be connected.`);
+    }
+    if (!gateway.isConnected) {
+        throw new Error(`Discord gateway is not connected${accountId ? ` for account "${accountId}"` : ""}.`);
+    }
+    const statusRaw = readStringParam(params, "status") ?? "online";
+    if (!VALID_STATUSES.has(statusRaw)) {
+        throw new Error(`Invalid status "${statusRaw}". Must be one of: ${[...VALID_STATUSES].join(", ")}`);
+    }
+    const status = statusRaw;
+    const activityTypeRaw = readStringParam(params, "activityType");
+    const activityName = readStringParam(params, "activityName");
+    const activities = [];
+    if (activityTypeRaw || activityName) {
+        if (!activityTypeRaw) {
+            throw new Error("activityType is required when activityName is provided. " +
+                `Valid types: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`);
+        }
+        const typeNum = ACTIVITY_TYPE_MAP[activityTypeRaw.toLowerCase()];
+        if (typeNum === undefined) {
+            throw new Error(`Invalid activityType "${activityTypeRaw}". Must be one of: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`);
+        }
+        const activity = {
+            name: activityName ?? "",
+            type: typeNum,
+        };
+        // Streaming URL (Twitch/YouTube). May not render for bots but is the correct payload shape.
+        if (typeNum === 1) {
+            const url = readStringParam(params, "activityUrl");
+            if (url) {
+                activity.url = url;
+            }
+        }
+        const state = readStringParam(params, "activityState");
+        if (state) {
+            activity.state = state;
+        }
+        activities.push(activity);
+    }
+    const presenceData = {
+        since: null,
+        activities,
+        status,
+        afk: false,
+    };
+    gateway.updatePresence(presenceData);
+    return jsonResult({
+        ok: true,
+        status,
+        activities: activities.map((a) => ({
+            type: a.type,
+            name: a.name,
+            ...(a.url ? { url: a.url } : {}),
+            ...(a.state ? { state: a.state } : {}),
+        })),
+    });
+}

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

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { complete, } from "@mariozechner/pi-ai";
-import { discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
+import { discoverAuthStorage, discoverModels } from "../pi-model-discovery.js";
 import { Type } from "@sinclair/typebox";
 import { resolveUserPath } from "../../utils.js";
 import { loadWebMedia } from "../../web/media.js";

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

@@ -11,8 +11,20 @@ import { normalizeAccountId } from "../../routing/session-key.js";
 import { channelTargetSchema, channelTargetsSchema, stringEnum } from "../schema/typebox.js";
 import { listChannelSupportedActions } from "../channel-tools.js";
 import { normalizeMessageChannel } from "../../utils/message-channel.js";
+import { stripReasoningTagsFromText } from "../../shared/text/reasoning-tags.js";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
 const AllMessageActions = CHANNEL_MESSAGE_ACTION_NAMES;
+const EXPLICIT_TARGET_ACTIONS = new Set([
+    "send",
+    "sendWithEffect",
+    "sendAttachment",
+    "reply",
+    "thread-reply",
+    "broadcast",
+]);
+function actionNeedsExplicitTarget(action) {
+    return EXPLICIT_TARGET_ACTIONS.has(action);
+}
 function buildRoutingSchema() {
     return {
         channel: Type.Optional(Type.String()),
@@ -29,7 +41,9 @@ function buildSendSchema(options) {
             description: "Message effect name/id for sendWithEffect (e.g., invisible ink).",
         })),
         effect: Type.Optional(Type.String({ description: "Alias for effectId (e.g., invisible-ink, balloons)." })),
-        media: Type.Optional(Type.String()),
+        media: Type.Optional(Type.String({
+            description: "Media URL or local path. data: URLs are not supported here, use buffer.",
+        })),
         filename: Type.Optional(Type.String()),
         buffer: Type.Optional(Type.String({
             description: "Base64 payload for attachments (optionally a data: URL).",
@@ -45,6 +59,7 @@ function buildSendSchema(options) {
         silent: Type.Optional(Type.Boolean()),
         bestEffort: Type.Optional(Type.Boolean()),
         gifPlayback: Type.Optional(Type.Boolean()),
+        quoteText: Type.Optional(Type.String({ description: "Quote text for Telegram reply_parameters" })),
         buttons: Type.Optional(Type.Array(Type.Array(Type.Object({
             text: Type.String(),
             callback_data: Type.String(),
@@ -159,6 +174,23 @@ function buildChannelManagementSchema() {
         })),
     };
 }
+function buildPresenceSchema() {
+    return {
+        activityType: Type.Optional(Type.String({
+            description: "Activity type: playing, streaming, listening, watching, competing, custom.",
+        })),
+        activityName: Type.Optional(Type.String({
+            description: "Activity name shown in sidebar (e.g. 'with fire'). Ignored for custom type.",
+        })),
+        activityUrl: Type.Optional(Type.String({
+            description: "Streaming URL (Twitch or YouTube). Only used with streaming type; may not render for bots.",
+        })),
+        activityState: Type.Optional(Type.String({
+            description: "State text. For custom type this is the status text; for others it shows in the flyout.",
+        })),
+        status: Type.Optional(Type.String({ description: "Bot status: online, dnd, idle, invisible." })),
+    };
+}
 function buildMessageToolSchemaProps(options) {
     return {
         ...buildRoutingSchema(),
@@ -173,6 +205,7 @@ function buildMessageToolSchemaProps(options) {
         ...buildModerationSchema(),
         ...buildGatewaySchema(),
         ...buildChannelManagementSchema(),
+        ...buildPresenceSchema(),
     };
 }
 function buildMessageToolSchemaFromActions(actions, options) {
@@ -266,11 +299,31 @@ export function createMessageTool(options) {
                 err.name = "AbortError";
                 throw err;
             }
-            const params = args;
+            // Shallow-copy so we don't mutate the original event args (used for logging/dedup).
+            const params = { ...args };
+            // Strip reasoning tags from text fields — models may include <think>…</think>
+            // in tool arguments, and the messaging tool send path has no other tag filtering.
+            for (const field of ["text", "content", "message", "caption"]) {
+                if (typeof params[field] === "string") {
+                    params[field] = stripReasoningTagsFromText(params[field]);
+                }
+            }
             const cfg = options?.config ?? loadConfig();
             const action = readStringParam(params, "action", {
                 required: true,
             });
+            // Enforce explicit target when required (e.g. cron/hook-initiated runs).
+            const requireExplicitTarget = options?.requireExplicitTarget === true;
+            if (requireExplicitTarget && actionNeedsExplicitTarget(action)) {
+                const explicitTarget = (typeof params.target === "string" && params.target.trim().length > 0) ||
+                    (typeof params.to === "string" && params.to.trim().length > 0) ||
+                    (typeof params.channelId === "string" && params.channelId.trim().length > 0) ||
+                    (Array.isArray(params.targets) &&
+                        params.targets.some((value) => typeof value === "string" && value.trim().length > 0));
+                if (!explicitTarget) {
+                    throw new Error("Explicit message target required for this run. Provide target/targets (and channel when needed).");
+                }
+            }
             const accountId = readStringParam(params, "accountId") ?? agentAccountId;
             if (accountId) {
                 params.accountId = accountId;
@@ -309,6 +362,7 @@ export function createMessageTool(options) {
                 agentId: options?.agentSessionKey
                     ? resolveSessionAgentId({ sessionKey: options.agentSessionKey, config: cfg })
                     : undefined,
+                sandboxRoot: options?.sandboxRoot,
                 abortSignal: signal,
             });
             const toolResult = getToolResult(result);

package/dist/agents/tools/sessions-history-tool.js

@@ -1,7 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import { loadConfig } from "../../config/config.js";
 import { callGateway } from "../../gateway/call.js";
+import { capArrayByJsonBytes } from "../../gateway/session-utils.fs.js";
 import { isSubagentSessionKey, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+import { truncateUtf16Safe } from "../../utils.js";
 import { jsonResult, readStringParam } from "./common.js";
 import { createAgentToAgentPolicy, resolveSessionReference, resolveMainSessionAlias, resolveInternalSessionKey, stripToolMessages, } from "./sessions-helpers.js";
 const SessionsHistoryToolSchema = Type.Object({
@@ -9,6 +11,63 @@ const SessionsHistoryToolSchema = Type.Object({
     limit: Type.Optional(Type.Number({ minimum: 1 })),
     includeTools: Type.Optional(Type.Boolean()),
 });
+/** Hard cap on the serialized JSON size of the returned messages array. */
+const SESSIONS_HISTORY_MAX_BYTES = 512 * 1024;
+/** Per-block text truncation limit (in UTF-16 chars). */
+const SESSIONS_HISTORY_TEXT_MAX_CHARS = 32_000;
+function truncateHistoryText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${truncateUtf16Safe(text, maxChars)}…(truncated)`;
+}
+function sanitizeHistoryContentBlock(block) {
+    if (!block || typeof block !== "object")
+        return block;
+    const rec = block;
+    if (typeof rec.text === "string") {
+        return { ...rec, text: truncateHistoryText(rec.text, SESSIONS_HISTORY_TEXT_MAX_CHARS) };
+    }
+    return block;
+}
+function sanitizeHistoryMessage(msg) {
+    if (!msg || typeof msg !== "object")
+        return msg;
+    const rec = msg;
+    if (typeof rec.content === "string") {
+        return { ...rec, content: truncateHistoryText(rec.content, SESSIONS_HISTORY_TEXT_MAX_CHARS) };
+    }
+    if (Array.isArray(rec.content)) {
+        return { ...rec, content: rec.content.map(sanitizeHistoryContentBlock) };
+    }
+    return msg;
+}
+function jsonUtf8Bytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf8");
+    }
+    catch {
+        return Buffer.byteLength(String(value), "utf8");
+    }
+}
+function enforceSessionsHistoryHardCap(messages) {
+    const sanitized = messages.map(sanitizeHistoryMessage);
+    const { items, bytes } = capArrayByJsonBytes(sanitized, SESSIONS_HISTORY_MAX_BYTES);
+    const droppedMessages = sanitized.length - items.length;
+    // Count how many messages had content truncated by comparing original vs sanitized text.
+    let contentTruncated = 0;
+    for (let i = 0; i < messages.length; i++) {
+        if (jsonUtf8Bytes(messages[i]) !== jsonUtf8Bytes(sanitized[i])) {
+            contentTruncated++;
+        }
+    }
+    return {
+        messages: items,
+        truncated: droppedMessages > 0 || contentTruncated > 0,
+        droppedMessages,
+        contentTruncated,
+        bytes,
+    };
+}
 function resolveSandboxSessionToolsVisibility(cfg) {
     return cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
 }
@@ -109,9 +168,18 @@ export function createSessionsHistoryTool(opts) {
             }));
             const rawMessages = Array.isArray(result?.messages) ? result.messages : [];
             const messages = includeTools ? rawMessages : stripToolMessages(rawMessages);
+            const capped = enforceSessionsHistoryHardCap(messages);
             return jsonResult({
                 sessionKey: displayKey,
-                messages,
+                messages: capped.messages,
+                ...(capped.truncated
+                    ? {
+                        truncated: true,
+                        droppedMessages: capped.droppedMessages,
+                        contentTruncated: capped.contentTruncated,
+                        bytes: capped.bytes,
+                    }
+                    : {}),
             });
         },
     };