@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/agents/subagent-spawn.js

@@ -1,7 +1,9 @@
 import crypto from "node:crypto";
 import { formatThinkingLevels, normalizeThinkLevel } from "../auto-reply/thinking.js";
+import { DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH } from "../config/agent-limits.js";
 import { loadConfig } from "../config/config.js";
 import { callGateway } from "../gateway/call.js";
+import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
 import { normalizeAgentId, parseAgentSessionKey } from "../routing/session-key.js";
 import { normalizeDeliveryContext } from "../utils/delivery-context.js";
 import { resolveAgentConfig } from "./agent-scope.js";
@@ -12,7 +14,9 @@ import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
 import { countActiveRunsForSession, registerSubagentRun } from "./subagent-registry.js";
 import { readStringParam } from "./tools/common.js";
 import { resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, } from "./tools/sessions-helpers.js";
-export const SUBAGENT_SPAWN_ACCEPTED_NOTE = "auto-announces on completion, do not poll/sleep. The response will be sent back as an agent message.";
+export const SUBAGENT_SPAWN_MODES = ["run", "session"];
+export const SUBAGENT_SPAWN_ACCEPTED_NOTE = "auto-announces on completion, do not poll/sleep. The response will be sent back as an user message.";
+export const SUBAGENT_SPAWN_SESSION_ACCEPTED_NOTE = "thread-bound session stays active after this task; continue in-thread for follow-ups.";
 export function splitModelRef(ref) {
     if (!ref) {
         return { provider: undefined, model: undefined };
@@ -27,23 +31,99 @@ export function splitModelRef(ref) {
     }
     return { provider: undefined, model: trimmed };
 }
+function resolveSpawnMode(params) {
+    if (params.requestedMode === "run" || params.requestedMode === "session") {
+        return params.requestedMode;
+    }
+    // Thread-bound spawns should default to persistent sessions.
+    return params.threadRequested ? "session" : "run";
+}
+function summarizeError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "string") {
+        return err;
+    }
+    return "error";
+}
+async function ensureThreadBindingForSubagentSpawn(params) {
+    const hookRunner = params.hookRunner;
+    if (!hookRunner?.hasHooks("subagent_spawning")) {
+        return {
+            status: "error",
+            error: "thread=true is unavailable because no channel plugin registered subagent_spawning hooks.",
+        };
+    }
+    try {
+        const result = await hookRunner.runSubagentSpawning({
+            childSessionKey: params.childSessionKey,
+            agentId: params.agentId,
+            label: params.label,
+            mode: params.mode,
+            requester: params.requester,
+            threadRequested: true,
+        }, {
+            childSessionKey: params.childSessionKey,
+            requesterSessionKey: params.requesterSessionKey,
+        });
+        if (result?.status === "error") {
+            const error = result.error.trim();
+            return {
+                status: "error",
+                error: error || "Failed to prepare thread binding for this subagent session.",
+            };
+        }
+        if (result?.status !== "ok" || !result.threadBindingReady) {
+            return {
+                status: "error",
+                error: "Unable to create or bind a thread for this subagent session. Session mode is unavailable for this target.",
+            };
+        }
+        return { status: "ok" };
+    }
+    catch (err) {
+        return {
+            status: "error",
+            error: `Thread bind failed: ${summarizeError(err)}`,
+        };
+    }
+}
 export async function spawnSubagentDirect(params, ctx) {
     const task = params.task;
     const label = params.label?.trim() || "";
     const requestedAgentId = params.agentId;
     const modelOverride = params.model;
     const thinkingOverrideRaw = params.thinking;
-    const cleanup = params.cleanup === "keep" || params.cleanup === "delete" ? params.cleanup : "keep";
+    const requestThreadBinding = params.thread === true;
+    const spawnMode = resolveSpawnMode({
+        requestedMode: params.mode,
+        threadRequested: requestThreadBinding,
+    });
+    if (spawnMode === "session" && !requestThreadBinding) {
+        return {
+            status: "error",
+            error: 'mode="session" requires thread=true so the subagent can stay bound to a thread.',
+        };
+    }
+    const cleanup = spawnMode === "session"
+        ? "keep"
+        : params.cleanup === "keep" || params.cleanup === "delete"
+            ? params.cleanup
+            : "keep";
+    const expectsCompletionMessage = params.expectsCompletionMessage !== false;
     const requesterOrigin = normalizeDeliveryContext({
         channel: ctx.agentChannel,
         accountId: ctx.agentAccountId,
         to: ctx.agentTo,
         threadId: ctx.agentThreadId,
     });
+    const hookRunner = getGlobalHookRunner();
     const runTimeoutSeconds = typeof params.runTimeoutSeconds === "number" && Number.isFinite(params.runTimeoutSeconds)
         ? Math.max(0, Math.floor(params.runTimeoutSeconds))
         : 0;
     let modelApplied = false;
+    let threadBindingReady = false;
     const cfg = loadConfig();
     const { mainKey, alias } = resolveMainSessionAlias(cfg);
     const requesterSessionKey = ctx.agentSessionKey;
@@ -60,7 +140,7 @@ export async function spawnSubagentDirect(params, ctx) {
         mainKey,
     });
     const callerDepth = getSubagentDepthFromSessionStore(requesterInternalKey, { cfg });
-    const maxSpawnDepth = cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;
+    const maxSpawnDepth = cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH;
     if (callerDepth >= maxSpawnDepth) {
         return {
             status: "forbidden",
@@ -170,6 +250,40 @@ export async function spawnSubagentDirect(params, ctx) {
             };
         }
     }
+    if (requestThreadBinding) {
+        const bindResult = await ensureThreadBindingForSubagentSpawn({
+            hookRunner,
+            childSessionKey,
+            agentId: targetAgentId,
+            label: label || undefined,
+            mode: spawnMode,
+            requesterSessionKey: requesterInternalKey,
+            requester: {
+                channel: requesterOrigin?.channel,
+                accountId: requesterOrigin?.accountId,
+                to: requesterOrigin?.to,
+                threadId: requesterOrigin?.threadId,
+            },
+        });
+        if (bindResult.status === "error") {
+            try {
+                await callGateway({
+                    method: "sessions.delete",
+                    params: { key: childSessionKey, emitLifecycleHooks: false },
+                    timeoutMs: 10_000,
+                });
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
+            return {
+                status: "error",
+                error: bindResult.error,
+                childSessionKey,
+            };
+        }
+        threadBindingReady = true;
+    }
     const childSystemPrompt = buildSubagentSystemPrompt({
         requesterSessionKey,
         requesterOrigin,
@@ -181,8 +295,13 @@ export async function spawnSubagentDirect(params, ctx) {
     });
     const childTaskMessage = [
         `[Subagent Context] You are running as a subagent (depth ${childDepth}/${maxSpawnDepth}). Results auto-announce to your requester; do not busy-poll for status.`,
+        spawnMode === "session"
+            ? "[Subagent Context] This subagent session is persistent and remains available for thread follow-up messages."
+            : undefined,
         `[Subagent Task]: ${task}`,
-    ].join("\n\n");
+    ]
+        .filter((line) => Boolean(line))
+        .join("\n\n");
     const childIdem = crypto.randomUUID();
     let childRunId = childIdem;
     try {
@@ -214,7 +333,49 @@ export async function spawnSubagentDirect(params, ctx) {
         }
     }
     catch (err) {
-        const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
+        if (threadBindingReady) {
+            const hasEndedHook = hookRunner?.hasHooks("subagent_ended") === true;
+            let endedHookEmitted = false;
+            if (hasEndedHook) {
+                try {
+                    await hookRunner?.runSubagentEnded({
+                        targetSessionKey: childSessionKey,
+                        targetKind: "subagent",
+                        reason: "spawn-failed",
+                        sendFarewell: true,
+                        accountId: requesterOrigin?.accountId,
+                        runId: childRunId,
+                        outcome: "error",
+                        error: "Session failed to start",
+                    }, {
+                        runId: childRunId,
+                        childSessionKey,
+                        requesterSessionKey: requesterInternalKey,
+                    });
+                    endedHookEmitted = true;
+                }
+                catch {
+                    // Spawn should still return an actionable error even if cleanup hooks fail.
+                }
+            }
+            // Always delete the provisional child session after a failed spawn attempt.
+            // If we already emitted subagent_ended above, suppress a duplicate lifecycle hook.
+            try {
+                await callGateway({
+                    method: "sessions.delete",
+                    params: {
+                        key: childSessionKey,
+                        deleteTranscript: true,
+                        emitLifecycleHooks: !endedHookEmitted,
+                    },
+                    timeoutMs: 10_000,
+                });
+            }
+            catch {
+                // Best-effort only.
+            }
+        }
+        const messageText = summarizeError(err);
         return {
             status: "error",
             error: messageText,
@@ -233,13 +394,40 @@ export async function spawnSubagentDirect(params, ctx) {
         label: label || undefined,
         model: resolvedModel,
         runTimeoutSeconds,
-        expectsCompletionMessage: params.expectsCompletionMessage === true,
+        expectsCompletionMessage,
+        spawnMode,
     });
+    if (hookRunner?.hasHooks("subagent_spawned")) {
+        try {
+            await hookRunner.runSubagentSpawned({
+                runId: childRunId,
+                childSessionKey,
+                agentId: targetAgentId,
+                label: label || undefined,
+                requester: {
+                    channel: requesterOrigin?.channel,
+                    accountId: requesterOrigin?.accountId,
+                    to: requesterOrigin?.to,
+                    threadId: requesterOrigin?.threadId,
+                },
+                threadRequested: requestThreadBinding,
+                mode: spawnMode,
+            }, {
+                runId: childRunId,
+                childSessionKey,
+                requesterSessionKey: requesterInternalKey,
+            });
+        }
+        catch {
+            // Spawn should still return accepted if spawn lifecycle hooks fail.
+        }
+    }
     return {
         status: "accepted",
         childSessionKey,
         runId: childRunId,
-        note: SUBAGENT_SPAWN_ACCEPTED_NOTE,
+        mode: spawnMode,
+        note: spawnMode === "session" ? SUBAGENT_SPAWN_SESSION_ACCEPTED_NOTE : SUBAGENT_SPAWN_ACCEPTED_NOTE,
         modelApplied: resolvedModel ? modelApplied : undefined,
     };
 }

package/dist/agents/system-prompt.js

@@ -1,3 +1,4 @@
+import { createHmac, createHash } from "node:crypto";
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { listDeliverableMessageChannels } from "../utils/message-channel.js";
 import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
@@ -44,7 +45,24 @@ function buildUserIdentitySection(ownerLine, isMinimal) {
     if (!ownerLine || isMinimal) {
         return [];
     }
-    return ["## User Identity", ownerLine, ""];
+    return ["## Authorized Senders", ownerLine, ""];
+}
+function formatOwnerDisplayId(ownerId, ownerDisplaySecret) {
+    const hasSecret = ownerDisplaySecret?.trim();
+    const digest = hasSecret
+        ? createHmac("sha256", hasSecret).update(ownerId).digest("hex")
+        : createHash("sha256").update(ownerId).digest("hex");
+    return digest.slice(0, 12);
+}
+function buildOwnerIdentityLine(ownerNumbers, ownerDisplay, ownerDisplaySecret) {
+    const normalized = ownerNumbers.map((value) => value.trim()).filter(Boolean);
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    const displayOwnerNumbers = ownerDisplay === "hash"
+        ? normalized.map((ownerId) => formatOwnerDisplayId(ownerId, ownerDisplaySecret))
+        : normalized;
+    return `Authorized senders: ${displayOwnerNumbers.join(", ")}. These senders are allowlisted; do not assume they are the owner.`;
 }
 function buildTimeSection(params) {
     if (!params.userTimezone) {
@@ -118,7 +136,7 @@ function buildDocsSection(params) {
     return [
         "## Documentation",
         `Pool Bot docs: ${docsPath}`,
-        "Mirror: https://docs.poolbot.dev",
+        "Mirror: https://docs.molt.bot",
         "Source: https://github.com/poolbot/poolbot",
         "Community: https://discord.com/invite/clawd",
         "Find new skills: https://clawhub.com",
@@ -220,10 +238,8 @@ export function buildAgentSystemPrompt(params) {
     const execToolName = resolveToolName("exec");
     const processToolName = resolveToolName("process");
     const extraSystemPrompt = params.extraSystemPrompt?.trim();
-    const ownerNumbers = (params.ownerNumbers ?? []).map((value) => value.trim()).filter(Boolean);
-    const ownerLine = ownerNumbers.length > 0
-        ? `Owner numbers: ${ownerNumbers.join(", ")}. Treat messages from these numbers as the user.`
-        : undefined;
+    const ownerDisplay = params.ownerDisplay === "hash" ? "hash" : "raw";
+    const ownerLine = buildOwnerIdentityLine(params.ownerNumbers ?? [], ownerDisplay, params.ownerDisplaySecret);
     const reasoningHint = params.reasoningTagHint
         ? [
             "ALL internal reasoning MUST be inside <think>...</think>.",

package/dist/agents/test-helpers/assistant-message-fixtures.js

@@ -0,0 +1,29 @@
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        total: 0,
+    },
+};
+export function makeAssistantMessageFixture(overrides = {}) {
+    const errorText = typeof overrides.errorMessage === "string" ? overrides.errorMessage : "error";
+    return {
+        role: "assistant",
+        api: "openai-responses",
+        provider: "openai",
+        model: "test-model",
+        usage: ZERO_USAGE,
+        timestamp: 0,
+        stopReason: "error",
+        errorMessage: errorText,
+        content: [{ type: "text", text: errorText }],
+        ...overrides,
+    };
+}

package/dist/agents/test-helpers/fast-coding-tools.js

@@ -1,18 +1 @@
-import { vi } from "vitest";
-const stubTool = (name) => ({
-    name,
-    description: `${name} stub`,
-    parameters: { type: "object", properties: {} },
-    execute: vi.fn(),
-});
-vi.mock("../tools/image-tool.js", () => ({
-    createImageTool: () => stubTool("image"),
-}));
-vi.mock("../tools/web-tools.js", () => ({
-    createWebSearchTool: () => null,
-    createWebFetchTool: () => null,
-}));
-vi.mock("../../plugins/tools.js", () => ({
-    resolvePluginTools: () => [],
-    getPluginToolMeta: () => undefined,
-}));
+import "./fast-tool-stubs.js";

package/dist/agents/test-helpers/fast-core-tools.js

@@ -1,24 +1,8 @@
 import { vi } from "vitest";
-const stubTool = (name) => ({
-    name,
-    description: `${name} stub`,
-    parameters: { type: "object", properties: {} },
-    execute: vi.fn(),
-});
+import { stubTool } from "./fast-tool-stubs.js";
 vi.mock("../tools/browser-tool.js", () => ({
     createBrowserTool: () => stubTool("browser"),
 }));
 vi.mock("../tools/canvas-tool.js", () => ({
     createCanvasTool: () => stubTool("canvas"),
 }));
-vi.mock("../tools/image-tool.js", () => ({
-    createImageTool: () => stubTool("image"),
-}));
-vi.mock("../tools/web-tools.js", () => ({
-    createWebSearchTool: () => null,
-    createWebFetchTool: () => null,
-}));
-vi.mock("../../plugins/tools.js", () => ({
-    resolvePluginTools: () => [],
-    getPluginToolMeta: () => undefined,
-}));

package/dist/agents/test-helpers/pi-tools-sandbox-context.js

@@ -0,0 +1,27 @@
+export function createPiToolsSandboxContext(params) {
+    const workspaceDir = params.workspaceDir;
+    return {
+        enabled: true,
+        sessionKey: params.sessionKey ?? "sandbox:test",
+        workspaceDir,
+        agentWorkspaceDir: params.agentWorkspaceDir ?? workspaceDir,
+        workspaceAccess: params.workspaceAccess ?? "rw",
+        containerName: params.containerName ?? "poolbot-sbx-test",
+        containerWorkdir: params.containerWorkdir ?? "/workspace",
+        fsBridge: params.fsBridge,
+        docker: {
+            image: "poolbot-sandbox:bookworm-slim",
+            containerPrefix: "poolbot-sbx-",
+            workdir: "/workspace",
+            readOnlyRoot: true,
+            tmpfs: [],
+            network: "none",
+            user: "1000:1000",
+            capDrop: ["ALL"],
+            env: { LANG: "C.UTF-8" },
+            ...params.dockerOverrides,
+        },
+        tools: params.tools ?? { allow: [], deny: [] },
+        browserAllowHostControl: params.browserAllowHostControl ?? false,
+    };
+}

package/dist/agents/timeout.js

@@ -1,4 +1,5 @@
 const DEFAULT_AGENT_TIMEOUT_SECONDS = 600;
+const MAX_SAFE_TIMEOUT_MS = 2_147_000_000;
 const normalizeNumber = (value) => typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : undefined;
 export function resolveAgentTimeoutSeconds(cfg) {
     const raw = normalizeNumber(cfg?.agents?.defaults?.timeoutSeconds);
@@ -7,18 +8,29 @@ export function resolveAgentTimeoutSeconds(cfg) {
 }
 export function resolveAgentTimeoutMs(opts) {
     const minMs = Math.max(normalizeNumber(opts.minMs) ?? 1, 1);
-    const defaultMs = resolveAgentTimeoutSeconds(opts.cfg) * 1000;
+    const clampTimeoutMs = (valueMs) => Math.min(Math.max(valueMs, minMs), MAX_SAFE_TIMEOUT_MS);
+    const defaultMs = clampTimeoutMs(resolveAgentTimeoutSeconds(opts.cfg) * 1000);
+    // Use the maximum timer-safe timeout to represent "no timeout" when explicitly set to 0.
+    const NO_TIMEOUT_MS = MAX_SAFE_TIMEOUT_MS;
     const overrideMs = normalizeNumber(opts.overrideMs);
     if (overrideMs !== undefined) {
-        if (overrideMs <= 0)
+        if (overrideMs === 0) {
+            return NO_TIMEOUT_MS;
+        }
+        if (overrideMs < 0) {
             return defaultMs;
-        return Math.max(overrideMs, minMs);
+        }
+        return clampTimeoutMs(overrideMs);
     }
     const overrideSeconds = normalizeNumber(opts.overrideSeconds);
     if (overrideSeconds !== undefined) {
-        if (overrideSeconds <= 0)
+        if (overrideSeconds === 0) {
+            return NO_TIMEOUT_MS;
+        }
+        if (overrideSeconds < 0) {
             return defaultMs;
-        return Math.max(overrideSeconds * 1000, minMs);
+        }
+        return clampTimeoutMs(overrideSeconds * 1000);
     }
-    return Math.max(defaultMs, minMs);
+    return defaultMs;
 }

package/dist/agents/tool-call-id.js

@@ -73,7 +73,7 @@ export function isValidCloudCodeAssistToolId(id, mode = "strict") {
     return /^[a-zA-Z0-9]+$/.test(id);
 }
 function shortHash(text, length = 8) {
-    return createHash("sha1").update(text).digest("hex").slice(0, length);
+    return createHash("sha256").update(text).digest("hex").slice(0, length);
 }
 function makeUniqueToolId(params) {
     if (params.mode === "strict9") {