@poolzin/pool-bot 2026.2.17 → 2026.2.18

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

@@ -310,7 +310,7 @@ export function createImageTool(options) {
             const modelOverride = typeof record.model === "string" && record.model.trim() ? record.model.trim() : undefined;
             const maxBytesMb = typeof record.maxBytesMb === "number" ? record.maxBytesMb : undefined;
             const maxBytes = pickMaxBytes(options?.config, maxBytesMb);
-            const sandboxRoot = options?.sandboxRoot?.trim();
+            const sandboxRoot = options?.sandbox?.root?.trim() ?? options?.sandboxRoot?.trim();
             const isUrl = isHttpUrl;
             if (sandboxRoot && isUrl) {
                 throw new Error("Sandboxed image tool does not allow remote URLs.");

package/dist/agents/tools/sessions-access.js

@@ -0,0 +1,178 @@
+import { isSubagentSessionKey, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+import { listSpawnedSessionKeys, resolveInternalSessionKey, resolveMainSessionAlias, } from "./sessions-resolution.js";
+export function resolveSessionToolsVisibility(cfg) {
+    const raw = cfg.tools?.sessions
+        ?.visibility;
+    const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+    if (value === "self" || value === "tree" || value === "agent" || value === "all") {
+        return value;
+    }
+    return "tree";
+}
+export function resolveEffectiveSessionToolsVisibility(params) {
+    const visibility = resolveSessionToolsVisibility(params.cfg);
+    if (!params.sandboxed) {
+        return visibility;
+    }
+    const sandboxClamp = params.cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
+    if (sandboxClamp === "spawned" && visibility !== "tree") {
+        return "tree";
+    }
+    return visibility;
+}
+export function resolveSandboxSessionToolsVisibility(cfg) {
+    return cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
+}
+export function resolveSandboxedSessionToolContext(params) {
+    const { mainKey, alias } = resolveMainSessionAlias(params.cfg);
+    const visibility = resolveSandboxSessionToolsVisibility(params.cfg);
+    const requesterInternalKey = typeof params.agentSessionKey === "string" && params.agentSessionKey.trim()
+        ? resolveInternalSessionKey({
+            key: params.agentSessionKey,
+            alias,
+            mainKey,
+        })
+        : undefined;
+    const effectiveRequesterKey = requesterInternalKey ?? alias;
+    const restrictToSpawned = params.sandboxed === true &&
+        visibility === "spawned" &&
+        !!requesterInternalKey &&
+        !isSubagentSessionKey(requesterInternalKey);
+    return {
+        mainKey,
+        alias,
+        visibility,
+        requesterInternalKey,
+        effectiveRequesterKey,
+        restrictToSpawned,
+    };
+}
+export function createAgentToAgentPolicy(cfg) {
+    const routingA2A = cfg.tools?.agentToAgent;
+    const enabled = routingA2A?.enabled === true;
+    const allowPatterns = Array.isArray(routingA2A?.allow) ? routingA2A.allow : [];
+    const matchesAllow = (agentId) => {
+        if (allowPatterns.length === 0) {
+            return true;
+        }
+        return allowPatterns.some((pattern) => {
+            const raw = String(pattern ?? "").trim();
+            if (!raw) {
+                return false;
+            }
+            if (raw === "*") {
+                return true;
+            }
+            if (!raw.includes("*")) {
+                return raw === agentId;
+            }
+            const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const re = new RegExp(`^${escaped.replaceAll("\\*", ".*")}$`, "i");
+            return re.test(agentId);
+        });
+    };
+    const isAllowed = (requesterAgentId, targetAgentId) => {
+        if (requesterAgentId === targetAgentId) {
+            return true;
+        }
+        if (!enabled) {
+            return false;
+        }
+        return matchesAllow(requesterAgentId) && matchesAllow(targetAgentId);
+    };
+    return { enabled, matchesAllow, isAllowed };
+}
+function actionPrefix(action) {
+    if (action === "history") {
+        return "Session history";
+    }
+    if (action === "send") {
+        return "Session send";
+    }
+    return "Session list";
+}
+function a2aDisabledMessage(action) {
+    if (action === "history") {
+        return "Agent-to-agent history is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent access.";
+    }
+    if (action === "send") {
+        return "Agent-to-agent messaging is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent sends.";
+    }
+    return "Agent-to-agent listing is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent visibility.";
+}
+function a2aDeniedMessage(action) {
+    if (action === "history") {
+        return "Agent-to-agent history denied by tools.agentToAgent.allow.";
+    }
+    if (action === "send") {
+        return "Agent-to-agent messaging denied by tools.agentToAgent.allow.";
+    }
+    return "Agent-to-agent listing denied by tools.agentToAgent.allow.";
+}
+function crossVisibilityMessage(action) {
+    if (action === "history") {
+        return "Session history visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+    }
+    if (action === "send") {
+        return "Session send visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+    }
+    return "Session list visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+}
+function selfVisibilityMessage(action) {
+    return `${actionPrefix(action)} visibility is restricted to the current session (tools.sessions.visibility=self).`;
+}
+function treeVisibilityMessage(action) {
+    return `${actionPrefix(action)} visibility is restricted to the current session tree (tools.sessions.visibility=tree).`;
+}
+export async function createSessionVisibilityGuard(params) {
+    const requesterAgentId = resolveAgentIdFromSessionKey(params.requesterSessionKey);
+    const spawnedKeys = params.visibility === "tree"
+        ? await listSpawnedSessionKeys({ requesterSessionKey: params.requesterSessionKey })
+        : null;
+    const check = (targetSessionKey) => {
+        const targetAgentId = resolveAgentIdFromSessionKey(targetSessionKey);
+        const isCrossAgent = targetAgentId !== requesterAgentId;
+        if (isCrossAgent) {
+            if (params.visibility !== "all") {
+                return {
+                    allowed: false,
+                    status: "forbidden",
+                    error: crossVisibilityMessage(params.action),
+                };
+            }
+            if (!params.a2aPolicy.enabled) {
+                return {
+                    allowed: false,
+                    status: "forbidden",
+                    error: a2aDisabledMessage(params.action),
+                };
+            }
+            if (!params.a2aPolicy.isAllowed(requesterAgentId, targetAgentId)) {
+                return {
+                    allowed: false,
+                    status: "forbidden",
+                    error: a2aDeniedMessage(params.action),
+                };
+            }
+            return { allowed: true };
+        }
+        if (params.visibility === "self" && targetSessionKey !== params.requesterSessionKey) {
+            return {
+                allowed: false,
+                status: "forbidden",
+                error: selfVisibilityMessage(params.action),
+            };
+        }
+        if (params.visibility === "tree" &&
+            targetSessionKey !== params.requesterSessionKey &&
+            !spawnedKeys?.has(targetSessionKey)) {
+            return {
+                allowed: false,
+                status: "forbidden",
+                error: treeVisibilityMessage(params.action),
+            };
+        }
+        return { allowed: true };
+    };
+    return { check };
+}

package/dist/agents/tools/sessions-resolution.js

@@ -0,0 +1,206 @@
+import { callGateway } from "../../gateway/call.js";
+import { isAcpSessionKey, normalizeMainKey } from "../../routing/session-key.js";
+function normalizeKey(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function resolveMainSessionAlias(cfg) {
+    const mainKey = normalizeMainKey(cfg.session?.mainKey);
+    const scope = cfg.session?.scope ?? "per-sender";
+    const alias = scope === "global" ? "global" : mainKey;
+    return { mainKey, alias, scope };
+}
+export function resolveDisplaySessionKey(params) {
+    if (params.key === params.alias) {
+        return "main";
+    }
+    if (params.key === params.mainKey) {
+        return "main";
+    }
+    return params.key;
+}
+export function resolveInternalSessionKey(params) {
+    if (params.key === "main") {
+        return params.alias;
+    }
+    return params.key;
+}
+export async function listSpawnedSessionKeys(params) {
+    const limit = typeof params.limit === "number" && Number.isFinite(params.limit)
+        ? Math.max(1, Math.floor(params.limit))
+        : 500;
+    try {
+        const list = await callGateway({
+            method: "sessions.list",
+            params: {
+                includeGlobal: false,
+                includeUnknown: false,
+                limit,
+                spawnedBy: params.requesterSessionKey,
+            },
+        });
+        const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+        const keys = sessions
+            .map((entry) => (typeof entry?.key === "string" ? entry.key : ""))
+            .map((value) => value.trim())
+            .filter(Boolean);
+        return new Set(keys);
+    }
+    catch {
+        return new Set();
+    }
+}
+export async function isRequesterSpawnedSessionVisible(params) {
+    if (params.requesterSessionKey === params.targetSessionKey) {
+        return true;
+    }
+    const keys = await listSpawnedSessionKeys({
+        requesterSessionKey: params.requesterSessionKey,
+        limit: params.limit,
+    });
+    return keys.has(params.targetSessionKey);
+}
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function looksLikeSessionId(value) {
+    return SESSION_ID_RE.test(value.trim());
+}
+export function looksLikeSessionKey(value) {
+    const raw = value.trim();
+    if (!raw) {
+        return false;
+    }
+    // These are canonical key shapes that should never be treated as sessionIds.
+    if (raw === "main" || raw === "global" || raw === "unknown") {
+        return true;
+    }
+    if (isAcpSessionKey(raw)) {
+        return true;
+    }
+    if (raw.startsWith("agent:")) {
+        return true;
+    }
+    if (raw.startsWith("cron:") || raw.startsWith("hook:")) {
+        return true;
+    }
+    if (raw.startsWith("node-") || raw.startsWith("node:")) {
+        return true;
+    }
+    if (raw.includes(":group:") || raw.includes(":channel:")) {
+        return true;
+    }
+    return false;
+}
+export function shouldResolveSessionIdInput(value) {
+    // Treat anything that doesn't look like a well-formed key as a sessionId candidate.
+    return looksLikeSessionId(value) || !looksLikeSessionKey(value);
+}
+async function resolveSessionKeyFromSessionId(params) {
+    try {
+        // Resolve via gateway so we respect store routing and visibility rules.
+        const result = await callGateway({
+            method: "sessions.resolve",
+            params: {
+                sessionId: params.sessionId,
+                spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
+                includeGlobal: !params.restrictToSpawned,
+                includeUnknown: !params.restrictToSpawned,
+            },
+        });
+        const key = typeof result?.key === "string" ? result.key.trim() : "";
+        if (!key) {
+            throw new Error(`Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`);
+        }
+        return {
+            ok: true,
+            key,
+            displayKey: resolveDisplaySessionKey({
+                key,
+                alias: params.alias,
+                mainKey: params.mainKey,
+            }),
+            resolvedViaSessionId: true,
+        };
+    }
+    catch (err) {
+        if (params.restrictToSpawned) {
+            return {
+                ok: false,
+                status: "forbidden",
+                error: `Session not visible from this sandboxed agent session: ${params.sessionId}`,
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            status: "error",
+            error: message ||
+                `Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`,
+        };
+    }
+}
+async function resolveSessionKeyFromKey(params) {
+    try {
+        // Try key-based resolution first so non-standard keys keep working.
+        const result = await callGateway({
+            method: "sessions.resolve",
+            params: {
+                key: params.key,
+                spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
+            },
+        });
+        const key = typeof result?.key === "string" ? result.key.trim() : "";
+        if (!key) {
+            return null;
+        }
+        return {
+            ok: true,
+            key,
+            displayKey: resolveDisplaySessionKey({
+                key,
+                alias: params.alias,
+                mainKey: params.mainKey,
+            }),
+            resolvedViaSessionId: false,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveSessionReference(params) {
+    const raw = params.sessionKey.trim();
+    if (shouldResolveSessionIdInput(raw)) {
+        // Prefer key resolution to avoid misclassifying custom keys as sessionIds.
+        const resolvedByKey = await resolveSessionKeyFromKey({
+            key: raw,
+            alias: params.alias,
+            mainKey: params.mainKey,
+            requesterInternalKey: params.requesterInternalKey,
+            restrictToSpawned: params.restrictToSpawned,
+        });
+        if (resolvedByKey) {
+            return resolvedByKey;
+        }
+        return await resolveSessionKeyFromSessionId({
+            sessionId: raw,
+            alias: params.alias,
+            mainKey: params.mainKey,
+            requesterInternalKey: params.requesterInternalKey,
+            restrictToSpawned: params.restrictToSpawned,
+        });
+    }
+    const resolvedKey = resolveInternalSessionKey({
+        key: raw,
+        alias: params.alias,
+        mainKey: params.mainKey,
+    });
+    const displayKey = resolveDisplaySessionKey({
+        key: resolvedKey,
+        alias: params.alias,
+        mainKey: params.mainKey,
+    });
+    return { ok: true, key: resolvedKey, displayKey, resolvedViaSessionId: false };
+}
+export function normalizeOptionalKey(value) {
+    return normalizeKey(value);
+}