@poolzin/pool-bot 2026.3.6 → 2026.3.7

package/dist/hooks/internal-hooks.js

@@ -5,8 +5,18 @@
  * like command processing, session lifecycle, etc.
  */
 import { createSubsystemLogger } from "../logging/subsystem.js";
-/** Registry of hook handlers by event key */
-const handlers = new Map();
+/**
+ * Registry of hook handlers by event key.
+ *
+ * Uses a globalThis singleton so that registerInternalHook and
+ * triggerInternalHook always share the same Map even when the bundler
+ * emits multiple copies of this module into separate chunks (bundle
+ * splitting). Without the singleton, handlers registered in one chunk
+ * are invisible to triggerInternalHook in another chunk, causing hooks
+ * to silently fire with zero handlers.
+ */
+const _g = globalThis;
+const handlers = (_g.__poolbot_internal_hook_handlers__ ??= new Map());
 const log = createSubsystemLogger("internal-hooks");
 /**
  * Register a hook handler for a specific event type or event:action combination
@@ -112,45 +122,80 @@ export function createInternalHookEvent(type, action, sessionKey, context = {})
         messages: [],
     };
 }
+function isHookEventTypeAndAction(event, type, action) {
+    return event.type === type && event.action === action;
+}
+function getHookContext(event) {
+    const context = event.context;
+    if (!context || typeof context !== "object") {
+        return null;
+    }
+    return context;
+}
+function hasStringContextField(context, key) {
+    return typeof context[key] === "string";
+}
+function hasBooleanContextField(context, key) {
+    return typeof context[key] === "boolean";
+}
 export function isAgentBootstrapEvent(event) {
-    if (event.type !== "agent" || event.action !== "bootstrap") {
+    if (!isHookEventTypeAndAction(event, "agent", "bootstrap")) {
         return false;
     }
-    const context = event.context;
-    if (!context || typeof context !== "object") {
+    const context = getHookContext(event);
+    if (!context) {
         return false;
     }
-    if (typeof context.workspaceDir !== "string") {
+    if (!hasStringContextField(context, "workspaceDir")) {
         return false;
     }
     return Array.isArray(context.bootstrapFiles);
 }
 export function isGatewayStartupEvent(event) {
-    if (event.type !== "gateway" || event.action !== "startup") {
+    if (!isHookEventTypeAndAction(event, "gateway", "startup")) {
         return false;
     }
-    const context = event.context;
-    return Boolean(context && typeof context === "object");
+    return Boolean(getHookContext(event));
 }
 export function isMessageReceivedEvent(event) {
-    if (event.type !== "message" || event.action !== "received") {
+    if (!isHookEventTypeAndAction(event, "message", "received")) {
         return false;
     }
-    const context = event.context;
-    if (!context || typeof context !== "object") {
+    const context = getHookContext(event);
+    if (!context) {
         return false;
     }
-    return typeof context.from === "string" && typeof context.channelId === "string";
+    return hasStringContextField(context, "from") && hasStringContextField(context, "channelId");
 }
 export function isMessageSentEvent(event) {
-    if (event.type !== "message" || event.action !== "sent") {
+    if (!isHookEventTypeAndAction(event, "message", "sent")) {
         return false;
     }
-    const context = event.context;
-    if (!context || typeof context !== "object") {
+    const context = getHookContext(event);
+    if (!context) {
+        return false;
+    }
+    return (hasStringContextField(context, "to") &&
+        hasStringContextField(context, "channelId") &&
+        hasBooleanContextField(context, "success"));
+}
+export function isMessageTranscribedEvent(event) {
+    if (!isHookEventTypeAndAction(event, "message", "transcribed")) {
+        return false;
+    }
+    const context = getHookContext(event);
+    if (!context) {
+        return false;
+    }
+    return (hasStringContextField(context, "transcript") && hasStringContextField(context, "channelId"));
+}
+export function isMessagePreprocessedEvent(event) {
+    if (!isHookEventTypeAndAction(event, "message", "preprocessed")) {
+        return false;
+    }
+    const context = getHookContext(event);
+    if (!context) {
         return false;
     }
-    return (typeof context.to === "string" &&
-        typeof context.channelId === "string" &&
-        typeof context.success === "boolean");
+    return hasStringContextField(context, "channelId");
 }

package/dist/hooks/message-hook-mappers.js

@@ -0,0 +1,179 @@
+export function deriveInboundMessageHookContext(ctx, overrides) {
+    const content = overrides?.content ??
+        (typeof ctx.BodyForCommands === "string"
+            ? ctx.BodyForCommands
+            : typeof ctx.RawBody === "string"
+                ? ctx.RawBody
+                : typeof ctx.Body === "string"
+                    ? ctx.Body
+                    : "");
+    const channelId = (ctx.OriginatingChannel ?? ctx.Surface ?? ctx.Provider ?? "").toLowerCase();
+    const conversationId = ctx.OriginatingTo ?? ctx.To ?? ctx.From ?? undefined;
+    const isGroup = Boolean(ctx.GroupSubject || ctx.GroupChannel);
+    return {
+        from: ctx.From ?? "",
+        to: ctx.To,
+        content,
+        body: ctx.Body,
+        bodyForAgent: ctx.BodyForAgent,
+        transcript: ctx.Transcript,
+        timestamp: typeof ctx.Timestamp === "number" && Number.isFinite(ctx.Timestamp)
+            ? ctx.Timestamp
+            : undefined,
+        channelId,
+        accountId: ctx.AccountId,
+        conversationId,
+        messageId: overrides?.messageId ??
+            ctx.MessageSidFull ??
+            ctx.MessageSid ??
+            ctx.MessageSidFirst ??
+            ctx.MessageSidLast,
+        senderId: ctx.SenderId,
+        senderName: ctx.SenderName,
+        senderUsername: ctx.SenderUsername,
+        senderE164: ctx.SenderE164,
+        provider: ctx.Provider,
+        surface: ctx.Surface,
+        threadId: ctx.MessageThreadId,
+        mediaPath: ctx.MediaPath,
+        mediaType: ctx.MediaType,
+        originatingChannel: ctx.OriginatingChannel,
+        originatingTo: ctx.OriginatingTo,
+        guildId: ctx.GroupSpace,
+        channelName: ctx.GroupChannel,
+        isGroup,
+        groupId: isGroup ? conversationId : undefined,
+    };
+}
+export function buildCanonicalSentMessageHookContext(params) {
+    return {
+        to: params.to,
+        content: params.content,
+        success: params.success,
+        error: params.error,
+        channelId: params.channelId,
+        accountId: params.accountId,
+        conversationId: params.conversationId ?? params.to,
+        messageId: params.messageId,
+        isGroup: params.isGroup,
+        groupId: params.groupId,
+    };
+}
+export function toPluginMessageContext(canonical) {
+    return {
+        channelId: canonical.channelId,
+        accountId: canonical.accountId,
+        conversationId: canonical.conversationId,
+    };
+}
+export function toPluginMessageReceivedEvent(canonical) {
+    return {
+        from: canonical.from,
+        content: canonical.content,
+        timestamp: canonical.timestamp,
+        metadata: {
+            to: canonical.to,
+            provider: canonical.provider,
+            surface: canonical.surface,
+            threadId: canonical.threadId,
+            originatingChannel: canonical.originatingChannel,
+            originatingTo: canonical.originatingTo,
+            messageId: canonical.messageId,
+            senderId: canonical.senderId,
+            senderName: canonical.senderName,
+            senderUsername: canonical.senderUsername,
+            senderE164: canonical.senderE164,
+            guildId: canonical.guildId,
+            channelName: canonical.channelName,
+        },
+    };
+}
+export function toPluginMessageSentEvent(canonical) {
+    return {
+        to: canonical.to,
+        content: canonical.content,
+        success: canonical.success,
+        ...(canonical.error ? { error: canonical.error } : {}),
+    };
+}
+export function toInternalMessageReceivedContext(canonical) {
+    return {
+        from: canonical.from,
+        content: canonical.content,
+        timestamp: canonical.timestamp,
+        channelId: canonical.channelId,
+        accountId: canonical.accountId,
+        conversationId: canonical.conversationId,
+        messageId: canonical.messageId,
+        metadata: {
+            to: canonical.to,
+            provider: canonical.provider,
+            surface: canonical.surface,
+            threadId: canonical.threadId,
+            senderId: canonical.senderId,
+            senderName: canonical.senderName,
+            senderUsername: canonical.senderUsername,
+            senderE164: canonical.senderE164,
+            guildId: canonical.guildId,
+            channelName: canonical.channelName,
+        },
+    };
+}
+export function toInternalMessageTranscribedContext(canonical, cfg) {
+    return {
+        from: canonical.from,
+        to: canonical.to,
+        body: canonical.body,
+        bodyForAgent: canonical.bodyForAgent,
+        transcript: canonical.transcript ?? "",
+        timestamp: canonical.timestamp,
+        channelId: canonical.channelId,
+        conversationId: canonical.conversationId,
+        messageId: canonical.messageId,
+        senderId: canonical.senderId,
+        senderName: canonical.senderName,
+        senderUsername: canonical.senderUsername,
+        provider: canonical.provider,
+        surface: canonical.surface,
+        mediaPath: canonical.mediaPath,
+        mediaType: canonical.mediaType,
+        cfg,
+    };
+}
+export function toInternalMessagePreprocessedContext(canonical, cfg) {
+    return {
+        from: canonical.from,
+        to: canonical.to,
+        body: canonical.body,
+        bodyForAgent: canonical.bodyForAgent,
+        transcript: canonical.transcript,
+        timestamp: canonical.timestamp,
+        channelId: canonical.channelId,
+        conversationId: canonical.conversationId,
+        messageId: canonical.messageId,
+        senderId: canonical.senderId,
+        senderName: canonical.senderName,
+        senderUsername: canonical.senderUsername,
+        provider: canonical.provider,
+        surface: canonical.surface,
+        mediaPath: canonical.mediaPath,
+        mediaType: canonical.mediaType,
+        isGroup: canonical.isGroup,
+        groupId: canonical.groupId,
+        cfg,
+    };
+}
+export function toInternalMessageSentContext(canonical) {
+    return {
+        to: canonical.to,
+        content: canonical.content,
+        success: canonical.success,
+        ...(canonical.error ? { error: canonical.error } : {}),
+        channelId: canonical.channelId,
+        accountId: canonical.accountId,
+        conversationId: canonical.conversationId,
+        messageId: canonical.messageId,
+        ...(canonical.isGroup != null ? { isGroup: canonical.isGroup } : {}),
+        ...(canonical.groupId ? { groupId: canonical.groupId } : {}),
+    };
+}

package/dist/security/capability-guards.js

@@ -0,0 +1,89 @@
+import { getCapabilityManager } from "./capability-manager.js";
+/** Error thrown when a capability check fails. */
+export class CapabilityError extends Error {
+    agentId;
+    required;
+    constructor(message, agentId, required) {
+        super(message);
+        this.agentId = agentId;
+        this.required = required;
+        this.name = "CapabilityError";
+    }
+}
+/** Guard function that throws if capability is denied. */
+export function requireCapability(agentId, required) {
+    const manager = getCapabilityManager();
+    const check = manager.check(agentId, required);
+    if (!check.granted) {
+        throw new CapabilityError(check.reason, agentId, required);
+    }
+}
+/** Async guard that returns a promise rejection if denied. */
+export async function withCapability(agentId, required, fn) {
+    requireCapability(agentId, required);
+    return await fn();
+}
+/** Helper to check file read capability. */
+export function checkFileRead(agentId, path) {
+    return getCapabilityManager().check(agentId, {
+        type: "file:read",
+        pattern: path,
+    });
+}
+/** Helper to check file write capability. */
+export function checkFileWrite(agentId, path) {
+    return getCapabilityManager().check(agentId, {
+        type: "file:write",
+        pattern: path,
+    });
+}
+/** Helper to check tool invocation capability. */
+export function checkToolInvoke(agentId, toolId) {
+    return getCapabilityManager().check(agentId, {
+        type: "tool:invoke",
+        toolId,
+    });
+}
+/** Helper to check network connection capability. */
+export function checkNetConnect(agentId, host) {
+    return getCapabilityManager().check(agentId, {
+        type: "net:connect",
+        pattern: host,
+    });
+}
+/** Helper to check shell execution capability. */
+export function checkShellExec(agentId, command) {
+    return getCapabilityManager().check(agentId, {
+        type: "shell:exec",
+        pattern: command,
+    });
+}
+/** Helper to check LLM query capability. */
+export function checkLlmQuery(agentId, model) {
+    return getCapabilityManager().check(agentId, {
+        type: "llm:query",
+        pattern: model,
+    });
+}
+/** Helper to check agent spawn capability. */
+export function checkAgentSpawn(agentId) {
+    return getCapabilityManager().check(agentId, { type: "agent:spawn" });
+}
+/** Helper to check memory read capability. */
+export function checkMemoryRead(agentId, scope) {
+    return getCapabilityManager().check(agentId, {
+        type: "memory:read",
+        scope,
+    });
+}
+/** Helper to check memory write capability. */
+export function checkMemoryWrite(agentId, scope) {
+    return getCapabilityManager().check(agentId, {
+        type: "memory:write",
+        scope,
+    });
+}
+/** Helper to check gateway admin capability. */
+export function checkGatewayAdmin(agentId) {
+    return getCapabilityManager().check(agentId, { type: "gateway:admin" });
+}

package/dist/security/capability-manager.js

@@ -0,0 +1,76 @@
+import { capabilityMatches, CapabilityResult } from "./capability.js";
+/**
+ * Manages capability grants for all agents.
+ * Uses a Map for O(1) lookups. Thread-safe for single-threaded Node.js.
+ */
+export class CapabilityManager {
+    grants = new Map();
+    /** Grant capabilities to an agent. Replaces any existing grants. */
+    grant(agentId, capabilities) {
+        this.grants.set(agentId, capabilities);
+    }
+    /** Add capabilities to an agent's existing grants. */
+    add(agentId, capabilities) {
+        const existing = this.grants.get(agentId) ?? [];
+        this.grants.set(agentId, [...existing, ...capabilities]);
+    }
+    /** Check whether an agent has a specific capability. */
+    check(agentId, required) {
+        const grants = this.grants.get(agentId);
+        if (!grants) {
+            return CapabilityResult.denied(`No capabilities registered for agent ${agentId}`);
+        }
+        for (const granted of grants) {
+            if (capabilityMatches(granted, required)) {
+                return CapabilityResult.granted();
+            }
+        }
+        return CapabilityResult.denied(`Agent ${agentId} does not have capability: ${JSON.stringify(required)}`);
+    }
+    /** Check multiple capabilities at once. Returns first denial or grants all. */
+    checkAll(agentId, required) {
+        for (const req of required) {
+            const result = this.check(agentId, req);
+            if (!result.granted)
+                return result;
+        }
+        return CapabilityResult.granted();
+    }
+    /** List all capabilities for an agent. */
+    list(agentId) {
+        return this.grants.get(agentId) ?? [];
+    }
+    /** Remove all capabilities for an agent. */
+    revokeAll(agentId) {
+        this.grants.delete(agentId);
+    }
+    /** Check if an agent has any capabilities registered. */
+    has(agentId) {
+        return this.grants.has(agentId);
+    }
+    /** Get all registered agent IDs. */
+    agents() {
+        return Array.from(this.grants.keys());
+    }
+    /** Clear all grants. */
+    clear() {
+        this.grants.clear();
+    }
+}
+/** Global singleton instance. */
+let globalManager;
+/** Get or create the global capability manager. */
+export function getCapabilityManager() {
+    if (!globalManager) {
+        globalManager = new CapabilityManager();
+    }
+    return globalManager;
+}
+/** Reset the global manager (useful for testing). */
+export function resetCapabilityManager() {
+    globalManager = undefined;
+}
+/** Set a custom global manager (useful for testing). */
+export function setCapabilityManager(manager) {
+    globalManager = manager;
+}

package/dist/security/capability.js

@@ -0,0 +1,147 @@
+/**
+ * Capability-based security system for Pool Bot.
+ *
+ * Inspired by OpenFang's capability system, adapted for TypeScript.
+ * Agents can only perform actions they've been explicitly granted permission for.
+ * Capabilities are immutable after agent creation and enforced at runtime.
+ */
+/** All available capability types for CLI and validation. */
+export const CAPABILITY_TYPES = [
+    // File system
+    "file:read",
+    "file:write",
+    // Network
+    "net:connect",
+    "net:listen",
+    // Tools
+    "tool:invoke",
+    "tool:all",
+    // LLM
+    "llm:query",
+    "llm:maxTokens",
+    // Agent interaction
+    "agent:spawn",
+    "agent:message",
+    "agent:kill",
+    // Memory
+    "memory:read",
+    "memory:write",
+    // Shell
+    "shell:exec",
+    "env:read",
+    // Gateway
+    "gateway:admin",
+    "gateway:channels:read",
+    "gateway:channels:write",
+    // Economic
+    "econ:spend",
+    "econ:earn",
+    "econ:transfer",
+];
+/** Helper to create capability check results. */
+export const CapabilityResult = {
+    granted() {
+        return { granted: true };
+    },
+    denied(reason) {
+        return { granted: false, reason };
+    },
+};
+/** Simple glob pattern matching supporting '*' as wildcard. */
+export function globMatches(pattern, value) {
+    if (pattern === "*")
+        return true;
+    if (pattern === value)
+        return true;
+    // Prefix wildcard: "*.example.com"
+    if (pattern.startsWith("*")) {
+        const suffix = pattern.slice(1);
+        return value.endsWith(suffix);
+    }
+    // Suffix wildcard: "api.*"
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        return value.startsWith(prefix);
+    }
+    // Middle wildcard: "api.*.com"
+    const starPos = pattern.indexOf("*");
+    if (starPos !== -1) {
+        const prefix = pattern.slice(0, starPos);
+        const suffix = pattern.slice(starPos + 1);
+        return (value.startsWith(prefix) &&
+            value.endsWith(suffix) &&
+            value.length >= prefix.length + suffix.length);
+    }
+    return false;
+}
+/**
+ * Check whether a required capability matches any granted capability.
+ */
+export function capabilityMatches(granted, required) {
+    // Tool:all grants any specific tool
+    if (granted.type === "tool:all" && required.type === "tool:invoke") {
+        return true;
+    }
+    // Same variant type matching
+    if (granted.type !== required.type)
+        return false;
+    switch (granted.type) {
+        case "file:read":
+        case "file:write":
+            return globMatches(granted.pattern, required.pattern);
+        case "net:connect":
+            return globMatches(granted.pattern, required.pattern);
+        case "net:listen":
+            return granted.port === required.port;
+        case "tool:invoke":
+            return granted.toolId === required.toolId || granted.toolId === "*";
+        case "llm:query":
+            return globMatches(granted.pattern, required.pattern);
+        case "llm:maxTokens":
+            return granted.limit >= required.limit;
+        case "agent:spawn":
+            return true;
+        case "agent:message":
+        case "agent:kill":
+            return globMatches(granted.pattern, required.pattern);
+        case "memory:read":
+        case "memory:write":
+            return globMatches(granted.scope, required.scope);
+        case "shell:exec":
+            return globMatches(granted.pattern, required.pattern);
+        case "env:read":
+            return globMatches(granted.pattern, required.pattern);
+        case "gateway:admin":
+        case "gateway:channels:read":
+            return true;
+        case "gateway:channels:write":
+            return globMatches(granted.pattern, required.pattern);
+        case "econ:spend":
+            return granted.limit >= required.limit;
+        case "econ:earn":
+            return true;
+        case "econ:transfer":
+            return globMatches(granted.pattern, required.pattern);
+        case "tool:all":
+            // tool:all only matches tool:all (already handled above for tool:invoke)
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Validate that child capabilities are a subset of parent capabilities.
+ * Prevents privilege escalation.
+ */
+export function validateCapabilityInheritance(parentCaps, childCaps) {
+    for (const childCap of childCaps) {
+        const isCovered = parentCaps.some((parentCap) => capabilityMatches(parentCap, childCap));
+        if (!isCovered) {
+            return {
+                valid: false,
+                reason: `Privilege escalation denied: child requests ${JSON.stringify(childCap)} but parent does not have a matching grant`,
+            };
+        }
+    }
+    return { valid: true };
+}

package/dist/security/index.js

@@ -0,0 +1,7 @@
+/**
+ * Security module index exports.
+ */
+export * from "./capability.js";
+export * from "./capability-manager.js";
+export * from "./capability-guards.js";
+export * from "./middleware.js";