@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/dist/infra/abort-pattern.js

@@ -0,0 +1,106 @@
+/**
+ * Abort Pattern Utilities
+ *
+ * Provides memory-leak-free abort signal handling.
+ *
+ * CRITICAL FIX: Uses `.bind()` instead of closures to prevent memory leaks.
+ * Issue #7174: Closure-based abort handlers capture scope and leak memory.
+ *
+ * @example
+ * ```typescript
+ * // BAD: Captures closure scope (leaks memory)
+ * signal.addEventListener('abort', () => controller.abort());
+ *
+ * // GOOD: No closure capture
+ * signal.addEventListener('abort', relayAbort.bind(controller));
+ * ```
+ */
+/**
+ * Relay abort signal without closure capture
+ * Prevents memory leak by using bind instead of arrow function
+ */
+export function relayAbort() {
+    this.abort();
+}
+/**
+ * Create an abort relay that doesn't capture closure scope
+ */
+export function createAbortRelay(controller) {
+    return relayAbort.bind(controller);
+}
+/**
+ * Link an abort signal to a controller without memory leaks
+ */
+export function linkAbortSignal(source, target) {
+    const handler = createAbortRelay(target);
+    source.addEventListener('abort', handler, { once: true });
+    // Return cleanup function
+    return () => {
+        source.removeEventListener('abort', handler);
+    };
+}
+/**
+ * Create a timeout-based abort controller
+ */
+export function createTimeoutAbortController(timeoutMs) {
+    const controller = new AbortController();
+    if (timeoutMs > 0) {
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        return {
+            controller,
+            cleanup: () => clearTimeout(timeout),
+        };
+    }
+    return {
+        controller,
+        cleanup: () => { },
+    };
+}
+/**
+ * Race multiple abort signals
+ */
+export function raceAbortSignals(signals, controller) {
+    const handlers = [];
+    let alreadyAborted = false;
+    for (const signal of signals) {
+        if (signal.aborted && !alreadyAborted) {
+            alreadyAborted = true;
+            controller.abort();
+        }
+        else if (!alreadyAborted) {
+            const handler = createAbortRelay(controller);
+            signal.addEventListener('abort', handler, { once: true });
+            handlers.push(() => signal.removeEventListener('abort', handler));
+        }
+    }
+    return () => {
+        for (const cleanup of handlers) {
+            cleanup();
+        }
+    };
+}
+/**
+ * Fetch with timeout and proper abort handling
+ */
+export async function fetchWithTimeout(url, options = {}) {
+    const { timeoutMs = 30000, ...fetchOptions } = options;
+    const { controller, cleanup } = createTimeoutAbortController(timeoutMs);
+    // Link existing signal if provided
+    let unlink;
+    if (fetchOptions.signal) {
+        unlink = linkAbortSignal(fetchOptions.signal, controller);
+    }
+    try {
+        const response = await fetch(url, {
+            ...fetchOptions,
+            signal: controller.signal,
+        });
+        return response;
+    }
+    finally {
+        unlink?.();
+        cleanup();
+    }
+}

package/dist/infra/retry.js

@@ -85,5 +85,99 @@ export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300
             await sleep(delay);
         }
     }
+    options.onExhausted?.(lastErr, maxAttempts);
     throw lastErr ?? new Error("Retry failed");
 }
+/**
+ * Execute a function with retry logic and return detailed result
+ */
+export async function retryWithResult(fn, options = {}) {
+    const resolved = resolveRetryConfig(DEFAULT_RETRY_CONFIG, options);
+    const maxAttempts = resolved.attempts;
+    const minDelayMs = resolved.minDelayMs;
+    const maxDelayMs = Number.isFinite(resolved.maxDelayMs) ? resolved.maxDelayMs : Number.POSITIVE_INFINITY;
+    const jitter = resolved.jitter;
+    const shouldRetry = options.shouldRetry ?? (() => true);
+    let lastErr;
+    let totalDelayMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return { result, attempts: attempt, totalDelayMs };
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+                break;
+            }
+            const retryAfterMs = options.retryAfterMs?.(err);
+            const hasRetryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs);
+            const baseDelay = hasRetryAfter
+                ? Math.max(retryAfterMs, minDelayMs)
+                : minDelayMs * 2 ** (attempt - 1);
+            let delay = Math.min(baseDelay, maxDelayMs);
+            delay = applyJitter(delay, jitter);
+            delay = Math.min(Math.max(delay, minDelayMs), maxDelayMs);
+            totalDelayMs += delay;
+            options.onRetry?.({
+                attempt,
+                maxAttempts,
+                delayMs: delay,
+                err,
+                label: options.label,
+            });
+            await sleep(delay);
+        }
+    }
+    options.onExhausted?.(lastErr, maxAttempts);
+    throw lastErr ?? new Error("Retry failed");
+}
+/**
+ * Check if error is retryable (network errors, rate limits, etc.)
+ */
+export function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Network errors
+        if (message.includes("econnreset"))
+            return true;
+        if (message.includes("etimedout"))
+            return true;
+        if (message.includes("econnrefused"))
+            return true;
+        if (message.includes("enotfound"))
+            return true;
+        if (message.includes("network"))
+            return true;
+        if (message.includes("timeout"))
+            return true;
+        // HTTP status codes that are retryable
+        const statusMatch = error.message.match(/status\s+(\d+)/i);
+        if (statusMatch) {
+            const status = parseInt(statusMatch[1], 10);
+            // 429 = Too Many Requests, 502/503/504 = Gateway errors
+            if (status === 429 || status === 502 || status === 503 || status === 504) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Default retry configuration for API calls
+ */
+export const API_RETRY_CONFIG = {
+    attempts: 3,
+    minDelayMs: 1000,
+    maxDelayMs: 10000,
+    jitter: 0.1,
+};
+/**
+ * Default retry configuration for network calls
+ */
+export const NETWORK_RETRY_CONFIG = {
+    attempts: 5,
+    minDelayMs: 500,
+    maxDelayMs: 30000,
+    jitter: 0.1,
+};

package/dist/secrets/index.js

@@ -0,0 +1,28 @@
+/**
+ * Secrets Management System
+ *
+ * Secure secret resolution with support for:
+ * - Environment variables (env:default:KEY)
+ * - JSON files (file:/path/to/secrets.json:key)
+ * - Direct values (backward compatible)
+ *
+ * @example
+ * ```typescript
+ * import { SecretsRuntime, resolveValue } from './secrets/index.js';
+ *
+ * // Create runtime
+ * const runtime = new SecretsRuntime({
+ *   allowDirectValues: true,
+ *   warnOnDirectValues: true
+ * });
+ *
+ * // Resolve API key
+ * runtime.resolve('openaiApiKey', 'env:default:OPENAI_API_KEY');
+ *
+ * // Get resolved value
+ * const apiKey = runtime.get('openaiApiKey');
+ * ```
+ */
+export * from "./types.js";
+export * from "./resolver.js";
+export * from "./runtime.js";

package/dist/secrets/resolver.js

@@ -0,0 +1,185 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+/**
+ * Parse a secret reference string
+ * Formats:
+ * - env:default:KEY - Environment variable
+ * - env:production:KEY - Environment variable from specific source
+ * - file:/path/to/secrets.json:KEY - JSON file
+ * - file:/path/to/secrets.json - Entire JSON file as secret
+ * - raw value - Direct value (backward compatibility)
+ */
+export function parseSecretRef(value) {
+    // Check if it's a reference
+    const envMatch = value.match(/^env:([^:]+):(.+)$/);
+    if (envMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "env",
+                source: envMatch[1],
+                key: envMatch[2],
+            },
+        };
+    }
+    const fileMatch = value.match(/^file:([^:]+):(.+)$/);
+    if (fileMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "file",
+                source: fileMatch[1],
+                key: fileMatch[2],
+            },
+        };
+    }
+    const fileOnlyMatch = value.match(/^file:(.+)$/);
+    if (fileOnlyMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "file",
+                source: fileOnlyMatch[1],
+                key: "", // Entire file
+            },
+        };
+    }
+    // Not a reference - treat as direct value
+    return {
+        isRef: false,
+        rawValue: value,
+    };
+}
+/**
+ * Resolve a secret reference to its value
+ */
+export function resolveSecret(ref, options = {}) {
+    const warnings = [];
+    switch (ref.provider) {
+        case "env":
+            return resolveEnvSecret(ref, options, warnings);
+        case "file":
+            return resolveFileSecret(ref, options, warnings);
+        case "exec":
+            return resolveExecSecret(ref, options, warnings);
+        default:
+            return {
+                value: undefined,
+                resolved: false,
+                warnings: [`Unknown provider: ${String(ref.provider)}`],
+            };
+    }
+}
+function resolveEnvSecret(ref, options, warnings) {
+    const value = process.env[ref.key];
+    if (value === undefined) {
+        if (!options.allowMissing) {
+            warnings.push(`Environment variable ${ref.key} is not set`);
+        }
+        return {
+            value: undefined,
+            resolved: false,
+            source: `env:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+    return {
+        value,
+        resolved: true,
+        source: `env:${ref.source}:${ref.key}`,
+        warnings,
+    };
+}
+function resolveFileSecret(ref, options, warnings) {
+    try {
+        const filePath = resolvePath(ref.source);
+        // Path traversal protection
+        if (options.basePath && !filePath.startsWith(resolvePath(options.basePath))) {
+            warnings.push(`Secret file path outside allowed directory: ${ref.source}`);
+            return {
+                value: undefined,
+                resolved: false,
+                source: `file:${ref.source}`,
+                warnings,
+            };
+        }
+        const content = readFileSync(filePath, "utf-8");
+        // If key is empty, return entire file content
+        if (!ref.key) {
+            return {
+                value: content.trim(),
+                resolved: true,
+                source: `file:${ref.source}`,
+                warnings,
+            };
+        }
+        // Try to parse as JSON
+        try {
+            const json = JSON.parse(content);
+            if (typeof json === "object" && json !== null) {
+                if (ref.key in json) {
+                    const value = String(json[ref.key]);
+                    return {
+                        value,
+                        resolved: true,
+                        source: `file:${ref.source}:${ref.key}`,
+                        warnings,
+                    };
+                }
+                warnings.push(`Key "${ref.key}" not found in JSON file ${ref.source}`);
+            }
+        }
+        catch {
+            // Not valid JSON, treat as plain text
+            warnings.push(`File ${ref.source} is not valid JSON`);
+        }
+        if (!options.allowMissing) {
+            warnings.push(`Could not resolve secret from file: ${ref.source}:${ref.key}`);
+        }
+        return {
+            value: undefined,
+            resolved: false,
+            source: `file:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`Failed to read file ${ref.source}: ${message}`);
+        return {
+            value: undefined,
+            resolved: false,
+            source: `file:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+}
+function resolveExecSecret(ref, _options, warnings) {
+    // Exec provider not yet implemented
+    warnings.push("Exec provider is not yet implemented");
+    return {
+        value: undefined,
+        resolved: false,
+        source: `exec:${ref.source}:${ref.key}`,
+        warnings,
+    };
+}
+/**
+ * Resolve a value that may be a secret reference or direct value
+ */
+export function resolveValue(value, options = {}) {
+    const parsed = parseSecretRef(value);
+    if (parsed.isRef && parsed.ref) {
+        return resolveSecret(parsed.ref, options);
+    }
+    // Direct value
+    const warnings = [];
+    if (options.warnOnDirectValues && parsed.rawValue !== undefined) {
+        warnings.push("Using direct secret value. Consider using env:default:KEY or file:/path:key format for better security");
+    }
+    return {
+        value: parsed.rawValue,
+        resolved: parsed.rawValue !== undefined,
+        warnings,
+    };
+}

package/dist/secrets/runtime.js

@@ -0,0 +1,142 @@
+import { resolveValue } from "./resolver.js";
+/**
+ * Runtime snapshot for resolved secrets
+ *
+ * This class manages a snapshot of resolved secrets that is created
+ * at startup and remains immutable during runtime for security.
+ */
+export class SecretsRuntime {
+    snapshot;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            allowDirectValues: true,
+            warnOnDirectValues: true,
+            failOnUnresolved: false,
+            ...config,
+        };
+        this.snapshot = {
+            secrets: new Map(),
+            unresolved: [],
+            warnings: [],
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Resolve a single secret and add to snapshot
+     */
+    resolve(key, value) {
+        const result = resolveValue(value, {
+            allowDirectValues: this.config.allowDirectValues,
+            warnOnDirectValues: this.config.warnOnDirectValues,
+            allowMissing: !this.config.failOnUnresolved,
+        });
+        if (result.resolved && result.value !== undefined) {
+            this.snapshot.secrets.set(key, {
+                value: result.value,
+                source: result.source || "direct",
+                warnings: result.warnings,
+            });
+        }
+        else {
+            this.snapshot.unresolved.push(key);
+        }
+        if (result.warnings.length > 0) {
+            this.snapshot.warnings.push(...result.warnings);
+        }
+        return result;
+    }
+    /**
+     * Resolve multiple secrets from an object
+     */
+    resolveObject(obj) {
+        const resolved = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const result = this.resolve(key, value);
+            if (result.value !== undefined) {
+                resolved[key] = result.value;
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Get a resolved secret value
+     */
+    get(key) {
+        return this.snapshot.secrets.get(key)?.value;
+    }
+    /**
+     * Check if a secret is resolved
+     */
+    has(key) {
+        return this.snapshot.secrets.has(key);
+    }
+    /**
+     * Get full snapshot info for a secret
+     */
+    getInfo(key) {
+        return this.snapshot.secrets.get(key);
+    }
+    /**
+     * Get all unresolved keys
+     */
+    getUnresolved() {
+        return [...this.snapshot.unresolved];
+    }
+    /**
+     * Get all warnings
+     */
+    getWarnings() {
+        return [...this.snapshot.warnings];
+    }
+    /**
+     * Get snapshot timestamp
+     */
+    getTimestamp() {
+        return this.snapshot.timestamp;
+    }
+    /**
+     * Create an immutable snapshot copy
+     */
+    createSnapshot() {
+        return {
+            secrets: new Map(this.snapshot.secrets),
+            unresolved: [...this.snapshot.unresolved],
+            warnings: [...this.snapshot.warnings],
+            timestamp: new Date(this.snapshot.timestamp),
+        };
+    }
+    /**
+     * Check if there are any unresolved required secrets
+     */
+    hasUnresolved() {
+        return this.snapshot.unresolved.length > 0;
+    }
+    /**
+     * Get summary of the runtime state
+     */
+    getSummary() {
+        return {
+            resolved: this.snapshot.secrets.size,
+            unresolved: this.snapshot.unresolved.length,
+            warnings: this.snapshot.warnings.length,
+            timestamp: this.snapshot.timestamp,
+        };
+    }
+}
+/**
+ * Global runtime instance (lazy initialized)
+ */
+let globalRuntime = null;
+export function getGlobalRuntime() {
+    if (!globalRuntime) {
+        globalRuntime = new SecretsRuntime();
+    }
+    return globalRuntime;
+}
+export function setGlobalRuntime(runtime) {
+    globalRuntime = runtime;
+}
+export function resetGlobalRuntime() {
+    globalRuntime = null;
+}

package/dist/secrets/types.js

@@ -0,0 +1,11 @@
+/**
+ * Secrets Management System for PoolBot
+ *
+ * Provides secure secret resolution with support for:
+ * - Environment variables (env:default:KEY)
+ * - JSON files (file:/path/to/secrets.json)
+ * - Direct values (for backward compatibility)
+ *
+ * Based on OpenClaw patterns but adapted for PoolBot architecture.
+ */
+export {};

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" });
+}