@poolzin/pool-bot 2026.2.11 → 2026.2.18

package/dist/agents/subagent-spawn.js

@@ -0,0 +1,262 @@
+import crypto from "node:crypto";
+import { formatThinkingLevels, normalizeThinkLevel } from "../auto-reply/thinking.js";
+import { loadConfig } from "../config/config.js";
+import { callGateway } from "../gateway/call.js";
+import { normalizeAgentId, parseAgentSessionKey } from "../routing/session-key.js";
+import { normalizeDeliveryContext } from "../utils/delivery-context.js";
+import { resolveAgentConfig } from "./agent-scope.js";
+import { AGENT_LANE_SUBAGENT } from "./lanes.js";
+import { resolveDefaultModelForAgent } from "./model-selection.js";
+import { buildSubagentSystemPrompt } from "./subagent-announce.js";
+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 function splitModelRef(ref) {
+    if (!ref) {
+        return { provider: undefined, model: undefined };
+    }
+    const trimmed = ref.trim();
+    if (!trimmed) {
+        return { provider: undefined, model: undefined };
+    }
+    const [provider, model] = trimmed.split("/", 2);
+    if (model) {
+        return { provider, model };
+    }
+    return { provider: undefined, model: trimmed };
+}
+export function normalizeModelSelection(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const primary = value.primary;
+    if (typeof primary === "string" && primary.trim()) {
+        return primary.trim();
+    }
+    return undefined;
+}
+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 requesterOrigin = normalizeDeliveryContext({
+        channel: ctx.agentChannel,
+        accountId: ctx.agentAccountId,
+        to: ctx.agentTo,
+        threadId: ctx.agentThreadId,
+    });
+    const runTimeoutSeconds = typeof params.runTimeoutSeconds === "number" && Number.isFinite(params.runTimeoutSeconds)
+        ? Math.max(0, Math.floor(params.runTimeoutSeconds))
+        : 0;
+    let modelWarning;
+    let modelApplied = false;
+    const cfg = loadConfig();
+    const { mainKey, alias } = resolveMainSessionAlias(cfg);
+    const requesterSessionKey = ctx.agentSessionKey;
+    const requesterInternalKey = requesterSessionKey
+        ? resolveInternalSessionKey({
+            key: requesterSessionKey,
+            alias,
+            mainKey,
+        })
+        : alias;
+    const requesterDisplayKey = resolveDisplaySessionKey({
+        key: requesterInternalKey,
+        alias,
+        mainKey,
+    });
+    const callerDepth = getSubagentDepthFromSessionStore(requesterInternalKey, { cfg });
+    const maxSpawnDepth = cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;
+    if (callerDepth >= maxSpawnDepth) {
+        return {
+            status: "forbidden",
+            error: `sessions_spawn is not allowed at this depth (current depth: ${callerDepth}, max: ${maxSpawnDepth})`,
+        };
+    }
+    const maxChildren = cfg.agents?.defaults?.subagents?.maxChildrenPerAgent ?? 5;
+    const activeChildren = countActiveRunsForSession(requesterInternalKey);
+    if (activeChildren >= maxChildren) {
+        return {
+            status: "forbidden",
+            error: `sessions_spawn has reached max active children for this session (${activeChildren}/${maxChildren})`,
+        };
+    }
+    const requesterAgentId = normalizeAgentId(ctx.requesterAgentIdOverride ?? parseAgentSessionKey(requesterInternalKey)?.agentId);
+    const targetAgentId = requestedAgentId ? normalizeAgentId(requestedAgentId) : requesterAgentId;
+    if (targetAgentId !== requesterAgentId) {
+        const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];
+        const allowAny = allowAgents.some((value) => value.trim() === "*");
+        const normalizedTargetId = targetAgentId.toLowerCase();
+        const allowSet = new Set(allowAgents
+            .filter((value) => value.trim() && value.trim() !== "*")
+            .map((value) => normalizeAgentId(value).toLowerCase()));
+        if (!allowAny && !allowSet.has(normalizedTargetId)) {
+            const allowedText = allowSet.size > 0 ? Array.from(allowSet).join(", ") : "none";
+            return {
+                status: "forbidden",
+                error: `agentId is not allowed for sessions_spawn (allowed: ${allowedText})`,
+            };
+        }
+    }
+    const childSessionKey = `agent:${targetAgentId}:subagent:${crypto.randomUUID()}`;
+    const childDepth = callerDepth + 1;
+    const spawnedByKey = requesterInternalKey;
+    const targetAgentConfig = resolveAgentConfig(cfg, targetAgentId);
+    const runtimeDefaultModel = resolveDefaultModelForAgent({
+        cfg,
+        agentId: targetAgentId,
+    });
+    const resolvedModel = normalizeModelSelection(modelOverride) ??
+        normalizeModelSelection(targetAgentConfig?.subagents?.model) ??
+        normalizeModelSelection(cfg.agents?.defaults?.subagents?.model) ??
+        normalizeModelSelection(cfg.agents?.defaults?.model?.primary) ??
+        normalizeModelSelection(`${runtimeDefaultModel.provider}/${runtimeDefaultModel.model}`);
+    const resolvedThinkingDefaultRaw = readStringParam(targetAgentConfig?.subagents ?? {}, "thinking") ??
+        readStringParam(cfg.agents?.defaults?.subagents ?? {}, "thinking");
+    let thinkingOverride;
+    const thinkingCandidateRaw = thinkingOverrideRaw || resolvedThinkingDefaultRaw;
+    if (thinkingCandidateRaw) {
+        const normalized = normalizeThinkLevel(thinkingCandidateRaw);
+        if (!normalized) {
+            const { provider, model } = splitModelRef(resolvedModel);
+            const hint = formatThinkingLevels(provider, model);
+            return {
+                status: "error",
+                error: `Invalid thinking level "${thinkingCandidateRaw}". Use one of: ${hint}.`,
+            };
+        }
+        thinkingOverride = normalized;
+    }
+    try {
+        await callGateway({
+            method: "sessions.patch",
+            params: { key: childSessionKey, spawnDepth: childDepth },
+            timeoutMs: 10_000,
+        });
+    }
+    catch (err) {
+        const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
+        return {
+            status: "error",
+            error: messageText,
+            childSessionKey,
+        };
+    }
+    if (resolvedModel) {
+        try {
+            await callGateway({
+                method: "sessions.patch",
+                params: { key: childSessionKey, model: resolvedModel },
+                timeoutMs: 10_000,
+            });
+            modelApplied = true;
+        }
+        catch (err) {
+            const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
+            const recoverable = messageText.includes("invalid model") || messageText.includes("model not allowed");
+            if (!recoverable) {
+                return {
+                    status: "error",
+                    error: messageText,
+                    childSessionKey,
+                };
+            }
+            modelWarning = messageText;
+        }
+    }
+    if (thinkingOverride !== undefined) {
+        try {
+            await callGateway({
+                method: "sessions.patch",
+                params: {
+                    key: childSessionKey,
+                    thinkingLevel: thinkingOverride === "off" ? null : thinkingOverride,
+                },
+                timeoutMs: 10_000,
+            });
+        }
+        catch (err) {
+            const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
+            return {
+                status: "error",
+                error: messageText,
+                childSessionKey,
+            };
+        }
+    }
+    const childSystemPrompt = buildSubagentSystemPrompt({
+        requesterSessionKey,
+        requesterOrigin,
+        childSessionKey,
+        label: label || undefined,
+        task,
+        childDepth,
+        maxSpawnDepth,
+    });
+    const childIdem = crypto.randomUUID();
+    let childRunId = childIdem;
+    try {
+        const response = await callGateway({
+            method: "agent",
+            params: {
+                message: task,
+                sessionKey: childSessionKey,
+                channel: requesterOrigin?.channel,
+                to: requesterOrigin?.to ?? undefined,
+                accountId: requesterOrigin?.accountId ?? undefined,
+                threadId: requesterOrigin?.threadId != null ? String(requesterOrigin.threadId) : undefined,
+                idempotencyKey: childIdem,
+                deliver: false,
+                lane: AGENT_LANE_SUBAGENT,
+                extraSystemPrompt: childSystemPrompt,
+                thinking: thinkingOverride,
+                timeout: runTimeoutSeconds,
+                label: label || undefined,
+                spawnedBy: spawnedByKey,
+                groupId: ctx.agentGroupId ?? undefined,
+                groupChannel: ctx.agentGroupChannel ?? undefined,
+                groupSpace: ctx.agentGroupSpace ?? undefined,
+            },
+            timeoutMs: 10_000,
+        });
+        if (typeof response?.runId === "string" && response.runId) {
+            childRunId = response.runId;
+        }
+    }
+    catch (err) {
+        const messageText = err instanceof Error ? err.message : typeof err === "string" ? err : "error";
+        return {
+            status: "error",
+            error: messageText,
+            childSessionKey,
+            runId: childRunId,
+        };
+    }
+    registerSubagentRun({
+        runId: childRunId,
+        childSessionKey,
+        requesterSessionKey: requesterInternalKey,
+        requesterOrigin,
+        requesterDisplayKey,
+        task,
+        cleanup,
+        label: label || undefined,
+        model: resolvedModel,
+        runTimeoutSeconds,
+    });
+    return {
+        status: "accepted",
+        childSessionKey,
+        runId: childRunId,
+        modelApplied: resolvedModel ? modelApplied : undefined,
+        warning: modelWarning,
+    };
+}

package/dist/agents/system-prompt.js

@@ -1,5 +1,6 @@
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { listDeliverableMessageChannels } from "../utils/message-channel.js";
+import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
 function buildSkillsSection(params) {
     if (params.isMinimal)
         return [];
@@ -66,6 +67,9 @@ function buildMessagingSection(params) {
         "## Messaging",
         "- Reply in current session → automatically routes to the source channel (Signal, Telegram, etc.)",
         "- Cross-session messaging → use sessions_send(sessionKey, message)",
+        "- Sub-agent orchestration → use subagents(action=list|steer|kill)",
+        "- `[System Message] ...` blocks are internal context and are not user-visible by default.",
+        `- If a \`[System Message]\` reports completed cron/subagent work and asks for a user update, rewrite it in your normal assistant voice and send that update (do not forward raw system text or default to ${SILENT_REPLY_TOKEN}).`,
         "- Never use exec/curl for provider messaging; Pool Bot handles all routing internally.",
         params.availableTools.has("message")
             ? [
@@ -76,7 +80,7 @@ function buildMessagingSection(params) {
                 `- If multiple channels are configured, pass \`channel\` (${params.messageChannelOptions}).`,
                 `- If you use \`message\` (\`action=send\`) to deliver your user-visible reply, respond with ONLY: ${SILENT_REPLY_TOKEN} (avoid duplicate replies).`,
                 params.inlineButtonsEnabled
-                    ? "- Inline buttons supported. Use `action=send` with `buttons=[[{text,callback_data}]]` (callback_data routes back as a user message)."
+                    ? "- Inline buttons supported. Use `action=send` with `buttons=[[{text,callback_data,style?}]]`; `style` can be `primary`, `success`, or `danger`."
                     : params.runtimeChannel
                         ? `- Inline buttons not enabled for ${params.runtimeChannel}. If you need them, ask to set ${params.runtimeChannel}.capabilities.inlineButtons ("dm"|"group"|"all"|"allowlist").`
                         : "",
@@ -96,6 +100,22 @@ function buildVoiceSection(params) {
         return [];
     return ["## Voice (TTS)", hint, ""];
 }
+function buildLlmsTxtSection(params) {
+    if (params.isMinimal) {
+        return [];
+    }
+    if (!params.availableTools.has("web_fetch")) {
+        return [];
+    }
+    return [
+        "## llms.txt Discovery",
+        "When exploring a new domain or website (via web_fetch or browser), check for an llms.txt file that describes how AI agents should interact with the site:",
+        "- Try `/llms.txt` or `/.well-known/llms.txt` at the domain root",
+        "- If found, follow its guidance for interacting with that site's content and APIs",
+        "- llms.txt is an emerging standard (like robots.txt for AI) — not all sites have one, so don't warn if missing",
+        "",
+    ];
+}
 function buildDocsSection(params) {
     const docsPath = params.docsPath?.trim();
     if (!docsPath || params.isMinimal)
@@ -137,6 +157,7 @@ export function buildAgentSystemPrompt(params) {
         sessions_history: "Fetch history for another session/sub-agent",
         sessions_send: "Send a message to another session/sub-agent",
         sessions_spawn: "Spawn a sub-agent session",
+        subagents: "List, steer, or kill sub-agent runs for this requester session",
         session_status: "Show a /status-equivalent status card (usage + time + Reasoning/Verbose/Elevated); use for model-use questions (📊 session_status); optional per-session model override",
         image: "Analyze an image with the configured image model",
     };
@@ -162,6 +183,8 @@ export function buildAgentSystemPrompt(params) {
         "sessions_list",
         "sessions_history",
         "sessions_send",
+        "sessions_spawn",
+        "subagents",
         "session_status",
         "image",
     ];
@@ -235,6 +258,17 @@ export function buildAgentSystemPrompt(params) {
     const messageChannelOptions = listDeliverableMessageChannels().join("|");
     const promptMode = params.promptMode ?? "full";
     const isMinimal = promptMode === "minimal" || promptMode === "none";
+    const sandboxContainerWorkspace = params.sandboxInfo?.containerWorkspaceDir?.trim();
+    const sanitizedWorkspaceDir = sanitizeForPromptLiteral(params.workspaceDir);
+    const sanitizedSandboxContainerWorkspace = sandboxContainerWorkspace
+        ? sanitizeForPromptLiteral(sandboxContainerWorkspace)
+        : "";
+    const displayWorkspaceDir = params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+        ? sanitizedSandboxContainerWorkspace
+        : sanitizedWorkspaceDir;
+    const workspaceGuidance = params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+        ? `For read/write/edit/apply_patch, file paths resolve against host workspace: ${sanitizedWorkspaceDir}. For bash/exec commands, use sandbox container paths under ${sanitizedSandboxContainerWorkspace} (or relative paths from that workdir), not host paths. Prefer relative paths so both sandboxed exec and file tools work consistently.`
+        : "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.";
     const safetySection = [
         "## Safety",
         "You have no independent goals: do not pursue self-preservation, replication, resource acquisition, or power-seeking; avoid long-term plans beyond the user's request.",
@@ -285,10 +319,13 @@ export function buildAgentSystemPrompt(params) {
                 "- sessions_list: list sessions",
                 "- sessions_history: fetch session history",
                 "- sessions_send: send to another session",
+                "- subagents: list/steer/kill sub-agent runs",
                 '- session_status: show usage/time/model state and answer "what model are we using?"',
             ].join("\n"),
         "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
-        "If a task is more complex or takes longer, spawn a sub-agent. It will do the work for you and ping you when it's done. You can always check up on it.",
+        `For long waits, avoid rapid poll loops: use ${execToolName} with enough yieldMs or ${processToolName}(action=poll, timeout=<ms>).`,
+        "If a task is more complex or takes longer, spawn a sub-agent. Completion is push-based: it will auto-announce when done.",
+        "Do not poll `subagents list` / `sessions_list` in a loop; only check status on-demand (for intervention, debugging, or when explicitly asked).",
         "",
         "## Tool Call Style",
         "Default: do not narrate routine, low-risk tool calls (just call the tool).",
@@ -335,8 +372,8 @@ export function buildAgentSystemPrompt(params) {
             ? "If you need the current date, time, or day of week, run session_status (📊 session_status)."
             : "",
         "## Workspace",
-        `Your working directory is: ${params.workspaceDir}`,
-        "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.",
+        `Your working directory is: ${displayWorkspaceDir}`,
+        workspaceGuidance,
         ...workspaceNotes,
         "",
         ...docsSection,
@@ -346,17 +383,20 @@ export function buildAgentSystemPrompt(params) {
                 "You are running in a sandboxed runtime (tools execute in Docker).",
                 "Some tools may be unavailable due to sandbox policy.",
                 "Sub-agents stay sandboxed (no elevated/host access). Need outside-sandbox read/write? Don't spawn; ask first.",
+                params.sandboxInfo.containerWorkspaceDir
+                    ? `Sandbox container workdir: ${sanitizeForPromptLiteral(params.sandboxInfo.containerWorkspaceDir)}`
+                    : "",
                 params.sandboxInfo.workspaceDir
-                    ? `Sandbox workspace: ${params.sandboxInfo.workspaceDir}`
+                    ? `Sandbox host mount source (file tools bridge only; not valid inside sandbox exec): ${sanitizeForPromptLiteral(params.sandboxInfo.workspaceDir)}`
                     : "",
                 params.sandboxInfo.workspaceAccess
                     ? `Agent workspace access: ${params.sandboxInfo.workspaceAccess}${params.sandboxInfo.agentWorkspaceMount
-                        ? ` (mounted at ${params.sandboxInfo.agentWorkspaceMount})`
+                        ? ` (mounted at ${sanitizeForPromptLiteral(params.sandboxInfo.agentWorkspaceMount)})`
                         : ""}`
                     : "",
                 params.sandboxInfo.browserBridgeUrl ? "Sandbox browser: enabled." : "",
                 params.sandboxInfo.browserNoVncUrl
-                    ? `Sandbox browser observer (noVNC): ${params.sandboxInfo.browserNoVncUrl}`
+                    ? `Sandbox browser observer (noVNC): ${sanitizeForPromptLiteral(params.sandboxInfo.browserNoVncUrl)}`
                     : "",
                 params.sandboxInfo.hostBrowserAllowed === true
                     ? "Host browser control: allowed."
@@ -397,6 +437,7 @@ export function buildAgentSystemPrompt(params) {
             messageToolHints: params.messageToolHints,
         }),
         ...buildVoiceSection({ isMinimal, ttsHint: params.ttsHint }),
+        ...buildLlmsTxtSection({ isMinimal, availableTools }),
     ];
     if (extraSystemPrompt) {
         // Use "Subagent Context" header for minimal mode (subagents), otherwise "Group Chat Context"
@@ -429,8 +470,9 @@ export function buildAgentSystemPrompt(params) {
         lines.push("## Reasoning Format", reasoningHint, "");
     }
     const contextFiles = params.contextFiles ?? [];
-    if (contextFiles.length > 0) {
-        const hasSoulFile = contextFiles.some((file) => {
+    const validContextFiles = contextFiles.filter((file) => typeof file.path === "string" && file.path.trim().length > 0);
+    if (validContextFiles.length > 0) {
+        const hasSoulFile = validContextFiles.some((file) => {
             const normalizedPath = file.path.trim().replace(/\\/g, "/");
             const baseName = normalizedPath.split("/").pop() ?? normalizedPath;
             return baseName.toLowerCase() === "soul.md";
@@ -440,7 +482,7 @@ export function buildAgentSystemPrompt(params) {
             lines.push("If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.");
         }
         lines.push("");
-        for (const file of contextFiles) {
+        for (const file of validContextFiles) {
             lines.push(`## ${file.path}`, "", file.content, "");
         }
     }

package/dist/agents/test-helpers/fast-tool-stubs.js

@@ -0,0 +1,18 @@
+import { vi } from "vitest";
+export 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,
+}));

package/dist/agents/test-helpers/host-sandbox-fs-bridge.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveSandboxPath } from "../sandbox-paths.js";
+export function createSandboxFsBridgeFromResolver(resolvePath) {
+    return {
+        resolvePath: ({ filePath, cwd }) => resolvePath(filePath, cwd),
+        readFile: async ({ filePath, cwd }) => {
+            const target = resolvePath(filePath, cwd);
+            return fs.readFile(target.hostPath);
+        },
+        writeFile: async ({ filePath, cwd, data, mkdir = true }) => {
+            const target = resolvePath(filePath, cwd);
+            if (mkdir) {
+                await fs.mkdir(path.dirname(target.hostPath), { recursive: true });
+            }
+            const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            await fs.writeFile(target.hostPath, buffer);
+        },
+        mkdirp: async ({ filePath, cwd }) => {
+            const target = resolvePath(filePath, cwd);
+            await fs.mkdir(target.hostPath, { recursive: true });
+        },
+        remove: async ({ filePath, cwd, recursive, force }) => {
+            const target = resolvePath(filePath, cwd);
+            await fs.rm(target.hostPath, {
+                recursive: recursive ?? false,
+                force: force ?? false,
+            });
+        },
+        rename: async ({ from, to, cwd }) => {
+            const source = resolvePath(from, cwd);
+            const target = resolvePath(to, cwd);
+            await fs.mkdir(path.dirname(target.hostPath), { recursive: true });
+            await fs.rename(source.hostPath, target.hostPath);
+        },
+        stat: async ({ filePath, cwd }) => {
+            try {
+                const target = resolvePath(filePath, cwd);
+                const stats = await fs.stat(target.hostPath);
+                return {
+                    type: stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other",
+                    size: stats.size,
+                    mtimeMs: stats.mtimeMs,
+                };
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    return null;
+                }
+                throw error;
+            }
+        },
+    };
+}
+export function createHostSandboxFsBridge(rootDir) {
+    const root = path.resolve(rootDir);
+    const resolvePath = (filePath, cwd) => {
+        const resolved = resolveSandboxPath({
+            filePath,
+            cwd: cwd ?? root,
+            root,
+        });
+        const relativePath = resolved.relative
+            ? resolved.relative.split(path.sep).filter(Boolean).join(path.posix.sep)
+            : "";
+        const containerPath = relativePath ? path.posix.join("/workspace", relativePath) : "/workspace";
+        return {
+            hostPath: resolved.resolved,
+            relativePath,
+            containerPath,
+        };
+    };
+    return createSandboxFsBridgeFromResolver(resolvePath);
+}