@poolzin/pool-bot 2026.3.22 → 2026.3.23

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## v2026.3.23 (2026-03-16)
+
+### 🎯 OpenClaw Integration - Melhorias Importadas
+
+#### Sistema de Polls/Enquetes
+- **polls.ts:** Criação e normalização de enquetes multi-canal
+- **poll-params.ts:** Definições de parâmetros para polls
+- **param-key.ts:** Utilitários para leitura de parâmetros
+- **Suporte:** Telegram, Discord e outros canais
+- **Testes:** 15 testes unitários passando
+
+#### Error Handling Avançado
+- Validação de que Pool Bot já possui sistema superior ao OpenClaw
+- 840 linhas de error handling vs 330 do OpenClaw
+- Classificação detalhada de erros
+- Redaction de dados sensíveis
+
+### 📊 Melhorias de Core (v2026.3.22)
+
+#### Event Deduplication Layer
+- Previne processamento duplicado de eventos
+- LRU-style tracking com TTL configurável
+- ~100KB overhead para 10k eventos
+- 14 testes unitários
+
+#### Run Tracker com AbortController
+- Cancelamento limpo de operações longas
+- TransformStream buffering para streaming real-time
+- Estatísticas de runs ativas e duração média
+- 18 testes unitários
+
+#### Command Analyzer & Security
+- 40+ padrões perigosos detectados
+- Shell wrapper detection (10 patterns)
+- PATH traversal prevention
+- Command injection detection
+- 36 testes unitários
+
+#### Browser Profile Manager
+- Múltiplos perfis Chrome isolados
+- Cookies e storage isolados por perfil
+- Suporte a proxy por perfil
+- Integrado com chrome-mcp.ts
+
+### 📝 Documentation
+- **IMPLEMENTATIONS_COMPLETE.md:** Resumo completo das implementações
+- **OPENCLAW_GAP_ANALYSIS.md:** Análise de gaps vs OpenClaw
+- **docs/improvements/USAGE-GUIDE.md:** Guia de uso de cada componente
+
+### 🧪 Test Coverage
+- 68 testes para componentes core
+- 15 testes para sistema de polls
+- 90%+ coverage nos novos componentes
+
 ## v2026.3.22 (2026-03-13)
 
 ### ✅ Testes Críticos Implementados

package/dist/acp/bindings-store.js

@@ -0,0 +1,209 @@
+/**
+ * ACP Persistent Bindings Store
+ * Persists tool bindings across sessions with validation
+ */
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Persistent store for ACP tool bindings
+ */
+export class BindingsStore {
+    dataDir;
+    bindingsFile;
+    cache = new Map();
+    validateOnLoad;
+    constructor(options) {
+        this.dataDir = options.dataDir;
+        this.bindingsFile = path.join(this.dataDir, "bindings.json");
+        this.validateOnLoad = options.validateOnLoad ?? true;
+        // Ensure data directory exists
+        if (!fs.existsSync(this.dataDir)) {
+            fs.mkdirSync(this.dataDir, { recursive: true });
+        }
+    }
+    /**
+     * Load bindings from disk
+     */
+    async load() {
+        const errors = [];
+        const warnings = [];
+        if (!fs.existsSync(this.bindingsFile)) {
+            return { valid: true, errors, warnings };
+        }
+        try {
+            const content = fs.readFileSync(this.bindingsFile, "utf-8");
+            const data = JSON.parse(content);
+            // Clear cache
+            this.cache.clear();
+            // Load and validate each binding
+            for (const binding of data) {
+                if (this.validateOnLoad) {
+                    const validation = this.validateBinding(binding);
+                    errors.push(...validation.errors.map((e) => `Binding ${binding.id}: ${e}`));
+                    warnings.push(...validation.warnings.map((w) => `Binding ${binding.id}: ${w}`));
+                    if (!validation.valid) {
+                        continue; // Skip invalid bindings
+                    }
+                }
+                // Check expiration
+                if (binding.expiresAt && binding.expiresAt < Date.now()) {
+                    warnings.push(`Binding ${binding.id}: expired`);
+                    continue; // Skip expired bindings
+                }
+                this.cache.set(binding.id, binding);
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+            };
+        }
+        catch (e) {
+            errors.push(`Failed to load bindings: ${e.message}`);
+            return { valid: false, errors, warnings };
+        }
+    }
+    /**
+     * Save bindings to disk
+     */
+    async save() {
+        const bindings = Array.from(this.cache.values());
+        const content = JSON.stringify(bindings, null, 2);
+        fs.writeFileSync(this.bindingsFile, content, "utf-8");
+    }
+    /**
+     * Add a new binding
+     */
+    addBinding(binding) {
+        this.cache.set(binding.id, binding);
+    }
+    /**
+     * Get a binding by ID
+     */
+    getBinding(id) {
+        return this.cache.get(id);
+    }
+    /**
+     * Remove a binding by ID
+     */
+    removeBinding(id) {
+        return this.cache.delete(id);
+    }
+    /**
+     * Get all bindings for a session
+     */
+    getSessionBindings(sessionId) {
+        return Array.from(this.cache.values()).filter((b) => b.scope === "session" && b.sessionId === sessionId);
+    }
+    /**
+     * Get all bindings for an agent
+     */
+    getAgentBindings(agentId) {
+        return Array.from(this.cache.values()).filter((b) => b.scope === "agent" && b.agentId === agentId);
+    }
+    /**
+     * Get all global bindings
+     */
+    getGlobalBindings() {
+        return Array.from(this.cache.values()).filter((b) => b.scope === "global");
+    }
+    /**
+     * Get all bindings (optionally filtered by scope)
+     */
+    getAllBindings(scope) {
+        const all = Array.from(this.cache.values());
+        if (scope) {
+            return all.filter((b) => b.scope === scope);
+        }
+        return all;
+    }
+    /**
+     * Clear expired bindings
+     */
+    clearExpired() {
+        const now = Date.now();
+        let cleared = 0;
+        for (const [id, binding] of this.cache.entries()) {
+            if (binding.expiresAt && binding.expiresAt < now) {
+                this.cache.delete(id);
+                cleared++;
+            }
+        }
+        return cleared;
+    }
+    /**
+     * Clear all bindings
+     */
+    clearAll() {
+        this.cache.clear();
+    }
+    /**
+     * Validate a single binding
+     */
+    validateBinding(binding) {
+        const errors = [];
+        const warnings = [];
+        // Required fields
+        if (!binding.id) {
+            errors.push("Missing required field: id");
+        }
+        if (!binding.name) {
+            errors.push("Missing required field: name");
+        }
+        if (!binding.scope) {
+            errors.push("Missing required field: scope");
+        }
+        else if (!["session", "global", "agent"].includes(binding.scope)) {
+            errors.push(`Invalid scope: ${binding.scope}`);
+        }
+        // Scope-specific validation
+        if (binding.scope === "session" && !binding.sessionId) {
+            errors.push("Session scope requires sessionId");
+        }
+        if (binding.scope === "agent" && !binding.agentId) {
+            errors.push("Agent scope requires agentId");
+        }
+        // Timestamp validation
+        if (!binding.createdAt) {
+            errors.push("Missing required field: createdAt");
+        }
+        if (binding.expiresAt && binding.expiresAt <= binding.createdAt) {
+            errors.push("expiresAt must be after createdAt");
+        }
+        // Warnings
+        if (binding.expiresAt && binding.expiresAt - binding.createdAt > 86400000 * 30) {
+            warnings.push("Binding expires in more than 30 days");
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Get store statistics
+     */
+    getStats() {
+        const all = Array.from(this.cache.values());
+        const now = Date.now();
+        return {
+            total: all.length,
+            byScope: {
+                session: all.filter((b) => b.scope === "session").length,
+                global: all.filter((b) => b.scope === "global").length,
+                agent: all.filter((b) => b.scope === "agent").length,
+            },
+            expired: all.filter((b) => b.expiresAt && b.expiresAt < now).length,
+        };
+    }
+}
+/**
+ * Create a default bindings store
+ */
+export function createBindingsStore(dataDir) {
+    const dir = dataDir || path.join(process.cwd(), ".poolbot", "bindings");
+    return new BindingsStore({
+        dataDir: dir,
+        validateOnLoad: true,
+    });
+}

package/dist/acp/control-plane/runtime-cache.js

@@ -0,0 +1,54 @@
+export class RuntimeCache {
+    cache = new Map();
+    size() {
+        return this.cache.size;
+    }
+    has(actorKey) {
+        return this.cache.has(actorKey);
+    }
+    get(actorKey, params = {}) {
+        const entry = this.cache.get(actorKey);
+        if (!entry) {
+            return null;
+        }
+        if (params.touch !== false) {
+            entry.lastTouchedAt = params.now ?? Date.now();
+        }
+        return entry.state;
+    }
+    peek(actorKey) {
+        return this.get(actorKey, { touch: false });
+    }
+    getLastTouchedAt(actorKey) {
+        return this.cache.get(actorKey)?.lastTouchedAt ?? null;
+    }
+    set(actorKey, state, params = {}) {
+        this.cache.set(actorKey, {
+            state,
+            lastTouchedAt: params.now ?? Date.now(),
+        });
+    }
+    clear(actorKey) {
+        this.cache.delete(actorKey);
+    }
+    snapshot(params = {}) {
+        const now = params.now ?? Date.now();
+        const entries = [];
+        for (const [actorKey, entry] of this.cache.entries()) {
+            entries.push({
+                actorKey,
+                state: entry.state,
+                lastTouchedAt: entry.lastTouchedAt,
+                idleMs: Math.max(0, now - entry.lastTouchedAt),
+            });
+        }
+        return entries;
+    }
+    collectIdleCandidates(params) {
+        if (!Number.isFinite(params.maxIdleMs) || params.maxIdleMs <= 0) {
+            return [];
+        }
+        const now = params.now ?? Date.now();
+        return this.snapshot({ now }).filter((entry) => entry.idleMs >= params.maxIdleMs);
+    }
+}

package/dist/acp/control-plane/runtime-options.js

@@ -0,0 +1,215 @@
+import { isAbsolute } from "node:path";
+import { AcpRuntimeError } from "../runtime/errors.js";
+const MAX_RUNTIME_MODE_LENGTH = 64;
+const MAX_MODEL_LENGTH = 200;
+const MAX_PERMISSION_PROFILE_LENGTH = 80;
+const MAX_CWD_LENGTH = 4096;
+const MIN_TIMEOUT_SECONDS = 1;
+const MAX_TIMEOUT_SECONDS = 24 * 60 * 60;
+const MAX_BACKEND_OPTION_KEY_LENGTH = 64;
+const MAX_BACKEND_OPTION_VALUE_LENGTH = 512;
+const MAX_BACKEND_EXTRAS = 32;
+const SAFE_OPTION_KEY_RE = /^[a-z0-9][a-z0-9._:-]*$/i;
+function failInvalidOption(message) {
+    throw new AcpRuntimeError("ACP_INVALID_RUNTIME_OPTION", message);
+}
+function validateNoControlChars(value, field) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code < 32 || code === 127) {
+            failInvalidOption(`${field} must not include control characters.`);
+        }
+    }
+    return value;
+}
+function validateBoundedText(params) {
+    const normalized = normalizeText(params.value);
+    if (!normalized) {
+        failInvalidOption(`${params.field} must not be empty.`);
+    }
+    if (normalized.length > params.maxLength) {
+        failInvalidOption(`${params.field} must be at most ${params.maxLength} characters.`);
+    }
+    return validateNoControlChars(normalized, params.field);
+}
+function validateBackendOptionKey(rawKey) {
+    const key = validateBoundedText({
+        value: rawKey,
+        field: "ACP config key",
+        maxLength: MAX_BACKEND_OPTION_KEY_LENGTH,
+    });
+    if (!SAFE_OPTION_KEY_RE.test(key)) {
+        failInvalidOption("ACP config key must use letters, numbers, dots, colons, underscores, or dashes.");
+    }
+    return key;
+}
+function validateBackendOptionValue(rawValue) {
+    return validateBoundedText({
+        value: rawValue,
+        field: "ACP config value",
+        maxLength: MAX_BACKEND_OPTION_VALUE_LENGTH,
+    });
+}
+export function validateRuntimeModeInput(rawMode) {
+    return validateBoundedText({
+        value: rawMode,
+        field: "Runtime mode",
+        maxLength: MAX_RUNTIME_MODE_LENGTH,
+    });
+}
+export function validateRuntimeModelInput(rawModel) {
+    return validateBoundedText({
+        value: rawModel,
+        field: "Model id",
+        maxLength: MAX_MODEL_LENGTH,
+    });
+}
+export function validateRuntimePermissionProfileInput(rawProfile) {
+    return validateBoundedText({
+        value: rawProfile,
+        field: "Permission profile",
+        maxLength: MAX_PERMISSION_PROFILE_LENGTH,
+    });
+}
+export function validateRuntimeCwdInput(rawCwd) {
+    const cwd = validateBoundedText({
+        value: rawCwd,
+        field: "Working directory",
+        maxLength: MAX_CWD_LENGTH,
+    });
+    if (!isAbsolute(cwd)) {
+        failInvalidOption(`Working directory must be an absolute path. Received "${cwd}".`);
+    }
+    return cwd;
+}
+export function validateRuntimeTimeoutSecondsInput(rawTimeout) {
+    if (typeof rawTimeout !== "number" || !Number.isFinite(rawTimeout)) {
+        failInvalidOption("Timeout must be a positive integer in seconds.");
+    }
+    const timeout = Math.round(rawTimeout);
+    if (timeout < MIN_TIMEOUT_SECONDS || timeout > MAX_TIMEOUT_SECONDS) {
+        failInvalidOption(`Timeout must be between ${MIN_TIMEOUT_SECONDS} and ${MAX_TIMEOUT_SECONDS} seconds.`);
+    }
+    return timeout;
+}
+export function validateRuntimeConfigOptionInput(rawKey, rawValue) {
+    return {
+        key: validateBackendOptionKey(rawKey),
+        value: validateBackendOptionValue(rawValue),
+    };
+}
+export function validateRuntimeOptionPatch(patch) {
+    if (!patch) {
+        return {};
+    }
+    const rawPatch = patch;
+    const allowedKeys = new Set([
+        "runtimeMode",
+        "model",
+        "cwd",
+        "permissionProfile",
+        "timeoutSeconds",
+        "backendExtras",
+    ]);
+    for (const key of Object.keys(rawPatch)) {
+        if (!allowedKeys.has(key)) {
+            failInvalidOption(`Unknown runtime option "${key}".`);
+        }
+    }
+    const next = {};
+    if (Object.hasOwn(rawPatch, "runtimeMode")) {
+        next.runtimeMode =
+            rawPatch.runtimeMode === undefined
+                ? undefined
+                : validateRuntimeModeInput(rawPatch.runtimeMode);
+    }
+    if (Object.hasOwn(rawPatch, "model")) {
+        next.model =
+            rawPatch.model === undefined ? undefined : validateRuntimeModelInput(rawPatch.model);
+    }
+    if (Object.hasOwn(rawPatch, "cwd")) {
+        next.cwd = rawPatch.cwd === undefined ? undefined : validateRuntimeCwdInput(rawPatch.cwd);
+    }
+    if (Object.hasOwn(rawPatch, "permissionProfile")) {
+        next.permissionProfile =
+            rawPatch.permissionProfile === undefined
+                ? undefined
+                : validateRuntimePermissionProfileInput(rawPatch.permissionProfile);
+    }
+    if (Object.hasOwn(rawPatch, "timeoutSeconds")) {
+        next.timeoutSeconds =
+            rawPatch.timeoutSeconds === undefined
+                ? undefined
+                : validateRuntimeTimeoutSecondsInput(rawPatch.timeoutSeconds);
+    }
+    if (Object.hasOwn(rawPatch, "backendExtras")) {
+        const rawExtras = rawPatch.backendExtras;
+        if (rawExtras === undefined) {
+            next.backendExtras = undefined;
+        }
+        else if (!rawExtras || typeof rawExtras !== "object" || Array.isArray(rawExtras)) {
+            failInvalidOption("Backend extras must be a key/value object.");
+        }
+        else {
+            const entries = Object.entries(rawExtras);
+            if (entries.length > MAX_BACKEND_EXTRAS) {
+                failInvalidOption(`Backend extras must include at most ${MAX_BACKEND_EXTRAS} entries.`);
+            }
+            const extras = {};
+            for (const [entryKey, entryValue] of entries) {
+                const { key, value } = validateRuntimeConfigOptionInput(entryKey, entryValue);
+                extras[key] = value;
+            }
+            next.backendExtras = Object.keys(extras).length > 0 ? extras : undefined;
+        }
+    }
+    return next;
+}
+export function normalizeText(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+export function normalizeRuntimeOptions(options) {
+    const runtimeMode = normalizeText(options?.runtimeMode);
+    const model = normalizeText(options?.model);
+    const cwd = normalizeText(options?.cwd);
+    const permissionProfile = normalizeText(options?.permissionProfile);
+    let timeoutSeconds;
+    if (typeof options?.timeoutSeconds === "number" && Number.isFinite(options.timeoutSeconds)) {
+        const rounded = Math.round(options.timeoutSeconds);
+        if (rounded > 0) {
+            timeoutSeconds = rounded;
+        }
+    }
+    const backendExtrasEntries = Object.entries(options?.backendExtras ?? {})
+        .map(([key, value]) => [normalizeText(key), normalizeText(value)])
+        .filter(([key, value]) => Boolean(key && value));
+    const backendExtras = backendExtrasEntries.length > 0 ? Object.fromEntries(backendExtrasEntries) : undefined;
+    return {
+        ...(runtimeMode ? { runtimeMode } : {}),
+        ...(model ? { model } : {}),
+        ...(cwd ? { cwd } : {}),
+        ...(permissionProfile ? { permissionProfile } : {}),
+        ...(typeof timeoutSeconds === "number" ? { timeoutSeconds } : {}),
+        ...(backendExtras ? { backendExtras } : {}),
+    };
+}
+export function mergeRuntimeOptions(params) {
+    const current = normalizeRuntimeOptions(params.current);
+    const patch = normalizeRuntimeOptions(validateRuntimeOptionPatch(params.patch));
+    const mergedExtras = {
+        ...current.backendExtras,
+        ...patch.backendExtras,
+    };
+    return normalizeRuntimeOptions({
+        ...current,
+        ...patch,
+        ...(Object.keys(mergedExtras).length > 0 ? { backendExtras: mergedExtras } : {}),
+    });
+}
+export function runtimeOptionsEqual(a, b) {
+    return JSON.stringify(normalizeRuntimeOptions(a)) === JSON.stringify(normalizeRuntimeOptions(b));
+}

package/dist/acp/control-plane/session-actor-queue.js

@@ -0,0 +1,36 @@
+import { KeyedAsyncQueue } from "../../plugin-sdk/keyed-async-queue.js";
+export class SessionActorQueue {
+    queue = new KeyedAsyncQueue();
+    pendingBySession = new Map();
+    tailMap = new Map();
+    getTailMapForTesting() {
+        return this.tailMap;
+    }
+    getTotalPendingCount() {
+        let total = 0;
+        for (const count of this.pendingBySession.values()) {
+            total += count;
+        }
+        return total;
+    }
+    getPendingCountForSession(actorKey) {
+        return this.pendingBySession.get(actorKey) ?? 0;
+    }
+    async run(actorKey, op) {
+        this.pendingBySession.set(actorKey, (this.pendingBySession.get(actorKey) ?? 0) + 1);
+        await this.queue.acquire(actorKey);
+        try {
+            return await op();
+        }
+        finally {
+            this.queue.release(actorKey);
+            const pending = (this.pendingBySession.get(actorKey) ?? 1) - 1;
+            if (pending <= 0) {
+                this.pendingBySession.delete(actorKey);
+            }
+            else {
+                this.pendingBySession.set(actorKey, pending);
+            }
+        }
+    }
+}

package/dist/acp/runtime/errors.js

@@ -0,0 +1,47 @@
+export const ACP_ERROR_CODES = [
+    "ACP_BACKEND_MISSING",
+    "ACP_BACKEND_UNAVAILABLE",
+    "ACP_BACKEND_UNSUPPORTED_CONTROL",
+    "ACP_DISPATCH_DISABLED",
+    "ACP_INVALID_RUNTIME_OPTION",
+    "ACP_SESSION_INIT_FAILED",
+    "ACP_TURN_FAILED",
+];
+export class AcpRuntimeError extends Error {
+    code;
+    cause;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "AcpRuntimeError";
+        this.code = code;
+        this.cause = options?.cause;
+    }
+}
+export function isAcpRuntimeError(value) {
+    return value instanceof AcpRuntimeError;
+}
+export function toAcpRuntimeError(params) {
+    if (params.error instanceof AcpRuntimeError) {
+        return params.error;
+    }
+    if (params.error instanceof Error) {
+        return new AcpRuntimeError(params.fallbackCode, params.error.message, {
+            cause: params.error,
+        });
+    }
+    return new AcpRuntimeError(params.fallbackCode, params.fallbackMessage, {
+        cause: params.error,
+    });
+}
+export async function withAcpRuntimeErrorBoundary(params) {
+    try {
+        return await params.run();
+    }
+    catch (error) {
+        throw toAcpRuntimeError({
+            error,
+            fallbackCode: params.fallbackCode,
+            fallbackMessage: params.fallbackMessage,
+        });
+    }
+}