@poolzin/pool-bot 2026.1.29 → 2026.1.31

package/dist/gateway/hooks/tool-usage-capture.js

@@ -0,0 +1,253 @@
+/**
+ * Tool Usage Capture Hook
+ *
+ * Captures tool usage automatically via lifecycle hooks.
+ * Safe: never throws, async operations, feature-flagged.
+ *
+ * Integration:
+ * - Registers as onToolUse hook
+ * - Captures all tool calls automatically
+ * - Stores compressed data in SessionEntry
+ */
+import { TOOL_USAGE_ENABLED, TOOL_USAGE_MAX_RECORDS, createToolUsageRecord, updateToolStats, addToHistory, } from "./tool-usage-storage.js";
+// ============================================================================
+// Configuration
+// ============================================================================
+const TOOL_USAGE_BUFFER_FLUSH_INTERVAL = 30000; // 30 seconds
+const TOOL_USAGE_BUFFER_MAX_SIZE = 50; // Flush after 50 tool calls
+const toolUsageBuffer = new Map();
+let bufferFlushScheduled = false;
+// ============================================================================
+// SessionEntry Extension (Type-safe, backward compatible)
+// ============================================================================
+/**
+ * Load tool usage from SessionEntry
+ * Safe: handles missing data, validates structure
+ */
+export async function loadSessionToolUsage(sessionKey) {
+    try {
+        // TODO: Integrate with actual SessionEntry in Phase 4
+        // For now, return in-memory placeholder
+        const existing = toolUsageBuffer.get(sessionKey);
+        if (existing && existing.length > 0) {
+            // Return computed stats from buffer
+            const tools = {};
+            for (const record of existing) {
+                if (!tools[record.toolName]) {
+                    tools[record.toolName] = {
+                        count: 0,
+                        totalMs: 0,
+                        avgMs: 0,
+                        lastUsed: record.timestamp,
+                    };
+                }
+                tools[record.toolName] = updateToolStats(tools[record.toolName], record.executionTimeMs);
+            }
+            return {
+                version: 2,
+                sessionKey,
+                sessionId: sessionKey, // Placeholder
+                tools,
+                history: existing,
+                lastCaptured: Date.now(),
+            };
+        }
+        // Return empty usage
+        return {
+            version: 2,
+            sessionKey,
+            sessionId: sessionKey,
+            tools: {},
+            history: [],
+            lastCaptured: Date.now(),
+        };
+    }
+    catch (err) {
+        console.error("[tool-usage-capture] Failed to load tool usage:", err);
+        // Return empty usage on error
+        return {
+            version: 2,
+            sessionKey,
+            sessionId: sessionKey,
+            tools: {},
+            history: [],
+            lastCaptured: Date.now(),
+        };
+    }
+}
+/**
+ * Save tool usage to SessionEntry
+ * Safe: validates data, handles errors gracefully
+ */
+export async function saveSessionToolUsage(sessionKey, usage) {
+    try {
+        // TODO: Integrate with actual SessionEntry in Phase 4
+        // For now, just update in-memory buffer
+        const existing = toolUsageBuffer.get(sessionKey) || [];
+        const newRecords = usage.history.slice(existing.length);
+        if (newRecords.length > 0) {
+            toolUsageBuffer.set(sessionKey, [...existing, ...newRecords]);
+        }
+        if (TOOL_USAGE_ENABLED) {
+            console.log(`[tool-usage-capture] Saved ${newRecords.length} records for ${sessionKey}`);
+        }
+    }
+    catch (err) {
+        console.error("[tool-usage-capture] Failed to save tool usage:", err);
+        // Never throw - errors are logged only
+    }
+}
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+/**
+ * Main hook: captures tool usage automatically
+ * Safe: validates all inputs, never throws, handles all edge cases
+ */
+export const toolUsageCaptureHook = async (ctx) => {
+    // Feature flag check (safe exit)
+    if (!TOOL_USAGE_ENABLED) {
+        return;
+    }
+    try {
+        // Validate inputs (safe defaults)
+        const toolName = ctx.toolName || "unknown_tool";
+        const executionTimeMs = ctx.executionTimeMs || 0;
+        const success = ctx.success !== undefined ? ctx.success : true;
+        // Create compressed record
+        const record = createToolUsageRecord(toolName, ctx.toolInput, ctx.toolOutput, executionTimeMs, success, ctx.error);
+        // Load existing usage
+        const usage = await loadSessionToolUsage(ctx.sessionKey);
+        // Update stats
+        if (!usage.tools[toolName]) {
+            usage.tools[toolName] = {
+                count: 0,
+                totalMs: 0,
+                avgMs: 0,
+                lastUsed: record.timestamp,
+            };
+        }
+        usage.tools[toolName] = updateToolStats(usage.tools[toolName], executionTimeMs);
+        // Add to history (respects max limit)
+        usage.history = addToHistory(usage.history, record, TOOL_USAGE_MAX_RECORDS);
+        usage.lastCaptured = Date.now();
+        // Save (async, non-blocking)
+        await saveSessionToolUsage(ctx.sessionKey, usage).catch((err) => {
+            // Save errors are logged in saveSessionToolUsage
+            // This catch is just for extra safety
+            console.error("[tool-usage-capture] Unhandled save error:", err);
+        });
+        // Debug logging (can be disabled)
+        if (success && TOOL_USAGE_ENABLED) {
+            console.log(`[tool-usage-capture] ${toolName} (${executionTimeMs}ms) - ${ctx.sessionKey}`);
+        }
+    }
+    catch (err) {
+        // NEVER throw from hook - would break the tool call
+        console.error("[tool-usage-capture] Hook error:", err);
+    }
+};
+// ============================================================================
+// Buffer Management (performance optimization)
+// ============================================================================
+/**
+ * Flush in-memory buffer to storage
+ * Safe: handles errors, never throws
+ */
+export async function flushToolUsageBuffer() {
+    try {
+        if (toolUsageBuffer.size === 0) {
+            return; // Nothing to flush
+        }
+        let flushed = 0;
+        for (const [sessionKey, records] of toolUsageBuffer.entries()) {
+            try {
+                // TODO: Actually persist to SessionEntry in Phase 4
+                // For now, buffer stays in-memory
+                flushed += records.length;
+            }
+            catch (err) {
+                console.error(`[tool-usage-capture] Failed to flush buffer for ${sessionKey}:`, err);
+            }
+        }
+        if (flushed > 0 && TOOL_USAGE_ENABLED) {
+            console.log(`[tool-usage-capture] Flushed ${flushed} records from buffer`);
+        }
+    }
+    catch (err) {
+        console.error("[tool-usage-capture] Buffer flush error:", err);
+    }
+}
+/**
+ * Schedule buffer flush
+ * Safe: debounced, only schedules once
+ */
+function scheduleBufferFlush() {
+    if (bufferFlushScheduled) {
+        return; // Already scheduled
+    }
+    bufferFlushScheduled = true;
+    // Flush after 30 seconds
+    setTimeout(async () => {
+        await flushToolUsageBuffer();
+        bufferFlushScheduled = false;
+    }, TOOL_USAGE_BUFFER_FLUSH_INTERVAL);
+}
+// ============================================================================
+// Query API (for future use)
+// ============================================================================
+/**
+ * Get tool usage statistics for a session
+ * Safe: returns empty object if no data
+ */
+export async function getSessionToolUsage(sessionKey) {
+    try {
+        const usage = await loadSessionToolUsage(sessionKey);
+        return usage;
+    }
+    catch (err) {
+        console.error(`[tool-usage-capture] Failed to get usage for ${sessionKey}:`, err);
+        return undefined;
+    }
+}
+/**
+ * Get recent tool usage (last N records)
+ * Safe: returns empty array if no data
+ */
+export async function getRecentToolUsage(sessionKey, count = 10) {
+    try {
+        const usage = await loadSessionToolUsage(sessionKey);
+        return usage.history.slice(-count);
+    }
+    catch (err) {
+        console.error(`[tool-usage-capture] Failed to get recent usage for ${sessionKey}:`, err);
+        return [];
+    }
+}
+// ============================================================================
+// Cleanup
+// ============================================================================
+/**
+ * Clear tool usage buffer (for testing)
+ * Safe: never throws
+ */
+export function clearToolUsageBuffer() {
+    try {
+        toolUsageBuffer.clear();
+    }
+    catch (err) {
+        console.error("[tool-usage-capture] Buffer clear error:", err);
+    }
+}
+/**
+ * Clear tool usage for a specific session
+ * Safe: never throws
+ */
+export function clearSessionToolUsage(sessionKey) {
+    try {
+        toolUsageBuffer.delete(sessionKey);
+    }
+    catch (err) {
+        console.error(`[tool-usage-capture] Failed to clear usage for ${sessionKey}:`, err);
+    }
+}

package/dist/gateway/hooks/tool-usage-storage.js

@@ -0,0 +1,144 @@
+/**
+ * Tool Usage Capture - Storage Layer
+ *
+ * Safe, efficient storage for tool usage data.
+ * Phase 2a: Type definitions and interfaces (NO breaking changes)
+ *
+ * Safety measures:
+ * - All fields optional (backward compatible)
+ * - Version field for future migrations
+ * - No modifications to existing SessionEntry fields
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+export const TOOL_USAGE_MAX_RECORDS = 100; // Keep only last 100 records
+export const TOOL_USAGE_MAX_SUMMARY_LEN = 100; // Max 100 chars per summary
+export const TOOL_USAGE_ENABLED = true; // Feature flag (master switch)
+// ============================================================================
+// Compression Functions (safe, no side effects)
+// ============================================================================
+/**
+ * Compress a tool input/output value to a short summary
+ * Safe: never throws, handles all types gracefully
+ */
+export function compressToolValue(value, maxLen = TOOL_USAGE_MAX_SUMMARY_LEN) {
+    try {
+        // Handle primitives
+        if (value === null)
+            return "null";
+        if (value === undefined)
+            return "undefined";
+        if (typeof value === "string") {
+            return value.length > maxLen ? value.slice(0, maxLen) + "..." : value;
+        }
+        if (typeof value === "number")
+            return String(value);
+        if (typeof value === "boolean")
+            return String(value);
+        // Handle objects and arrays
+        if (typeof value === "object") {
+            const json = JSON.stringify(value);
+            return json.length > maxLen ? json.slice(0, maxLen) + "..." : json;
+        }
+        // Fallback
+        return String(value);
+    }
+    catch (err) {
+        // If compression fails, return safe fallback
+        return "[compression_error]";
+    }
+}
+/**
+ * Create a tool usage record from hook context
+ * Safe: validates all inputs, never throws
+ */
+export function createToolUsageRecord(toolName, toolInput, toolOutput, executionTimeMs, success, error) {
+    // Validate inputs (safe defaults)
+    const safeToolName = typeof toolName === "string" && toolName.length > 0 ? toolName : "unknown_tool";
+    const safeInput = typeof toolInput === "object" && toolInput !== null ? toolInput : {};
+    const safeTime = typeof executionTimeMs === "number" && executionTimeMs >= 0 ? executionTimeMs : 0;
+    const safeSuccess = Boolean(success);
+    return {
+        toolName: safeToolName,
+        timestamp: Date.now(),
+        executionTimeMs: safeTime,
+        success: safeSuccess,
+        inputSummary: compressToolValue(safeInput),
+        outputSummary: compressToolValue(toolOutput),
+        error: error ? String(error).slice(0, 200) : undefined,
+    };
+}
+// ============================================================================
+// Statistics Update (pure function, no side effects)
+// ============================================================================
+/**
+ * Update tool statistics with a new record
+ * Safe: never mutates input, returns new object
+ */
+export function updateToolStats(existingStats, executionTimeMs) {
+    const count = (existingStats?.count ?? 0) + 1;
+    const totalMs = (existingStats?.totalMs ?? 0) + executionTimeMs;
+    const avgMs = count > 0 ? Math.round((totalMs / count) * 100) / 100 : 0;
+    return {
+        count,
+        totalMs,
+        avgMs,
+        lastUsed: Date.now(),
+    };
+}
+// ============================================================================
+// History Management (pure functions)
+// ============================================================================
+/**
+ * Add record to history, respecting max limit
+ * Safe: never exceeds max records, returns new array
+ */
+export function addToHistory(history, record, maxRecords = TOOL_USAGE_MAX_RECORDS) {
+    const newHistory = [...history, record];
+    // Keep only last N records
+    if (newHistory.length > maxRecords) {
+        return newHistory.slice(-maxRecords);
+    }
+    return newHistory;
+}
+/**
+ * Get recent tool usage (last N records)
+ * Safe: never mutates input, returns slice
+ */
+export function getRecentToolUsage(history, count = 10) {
+    return history.slice(-count);
+}
+// ============================================================================
+// Query Functions (for future use)
+// ============================================================================
+/**
+ * Get statistics for a specific tool
+ * Safe: returns undefined if tool not found
+ */
+export function getToolStats(usage, toolName) {
+    return usage?.tools[toolName];
+}
+/**
+ * Get all tool names sorted by usage frequency
+ * Safe: returns empty array if no data
+ */
+export function getToolsByFrequency(usage) {
+    if (!usage?.tools)
+        return [];
+    return Object.entries(usage.tools)
+        .map(([toolName, stats]) => ({ toolName, count: stats.count }))
+        .sort((a, b) => b.count - a.count);
+}
+/**
+ * Get slowest tools (by average execution time)
+ * Safe: returns empty array if no data
+ */
+export function getSlowestTools(usage, limit = 5) {
+    if (!usage?.tools)
+        return [];
+    return Object.entries(usage.tools)
+        .map(([toolName, stats]) => ({ toolName, avgMs: stats.avgMs }))
+        .sort((a, b) => b.avgMs - a.avgMs)
+        .slice(0, limit);
+}

package/dist/gateway/server-methods/nodes.js

@@ -5,6 +5,8 @@ import { respondInvalidParams, respondUnavailableOnThrow, safeParseJson, uniqueS
 import { loadConfig } from "../../config/config.js";
 import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
 function isNodeEntry(entry) {
+    if (entry.clientMode === "node")
+        return true;
     if (entry.role === "node")
         return true;
     if (Array.isArray(entry.roles) && entry.roles.includes("node"))

package/dist/gateway/server.impl.js

@@ -27,6 +27,7 @@ import { createExecApprovalHandlers } from "./server-methods/exec-approval.js";
 import { createExecApprovalForwarder } from "../infra/exec-approval-forwarder.js";
 import { createChannelManager } from "./server-channels.js";
 import { createAgentEventHandler } from "./server-chat.js";
+import { startLifecycleHooksIntegration } from "./hooks/lifecycle-hooks-integration.js";
 import { createGatewayCloseHandler } from "./server-close.js";
 import { buildGatewayCronService } from "./server-cron.js";
 import { applyGatewayLaneConcurrency } from "./server-lanes.js";
@@ -263,6 +264,9 @@ export async function startGatewayServer(port = 18789, opts = {}) {
         resolveSessionKeyForRun,
         clearAgentRunContext,
     }));
+    // Lifecycle Hooks Integration (POC Day 1.5)
+    const lifecycleHooksUnsub = startLifecycleHooksIntegration();
+    logHooks.info("Lifecycle hooks integration started");
     const heartbeatUnsub = onHeartbeatEvent((evt) => {
         broadcast("heartbeat", evt, { dropIfSlow: true });
     });

package/dist/imessage/monitor/monitor-provider.js

@@ -108,9 +108,18 @@ export async function monitorIMessageProvider(opts = {}) {
     const inboundDebouncer = createInboundDebouncer({
         debounceMs: inboundDebounceMs,
         buildKey: (entry) => {
+            // Use message-specific key to preserve attachments
+            // This prevents different messages from being merged incorrectly
             const sender = entry.message.sender?.trim();
             if (!sender)
                 return null;
+            // Prefer message id for unique identification (prevents cross-message contamination)
+            // If id is not available, fall back to conversation-based key
+            const messageId = entry.message.id;
+            if (messageId != null) {
+                return `imessage:${accountInfo.accountId}:msg:${messageId}`;
+            }
+            // Fallback to conversation-based key only when id is unavailable
             const conversationId = entry.message.chat_id != null
                 ? `chat:${entry.message.chat_id}`
                 : (entry.message.chat_guid ?? entry.message.chat_identifier ?? "unknown");
@@ -120,6 +129,8 @@ export async function monitorIMessageProvider(opts = {}) {
             const text = entry.message.text?.trim() ?? "";
             if (!text)
                 return false;
+            // Messages with attachments should not be debounced across message boundaries
+            // to preserve attachment context
             if (entry.message.attachments && entry.message.attachments.length > 0)
                 return false;
             return !hasControlCommand(text, cfg);
@@ -139,7 +150,9 @@ export async function monitorIMessageProvider(opts = {}) {
             const syntheticMessage = {
                 ...last.message,
                 text: combinedText,
-                attachments: null,
+                // Preserve attachments from the last message in the batch
+                // (should always be null here due to shouldDebounce guard, but keep for safety)
+                attachments: last.message.attachments ?? null,
             };
             await handleMessageNow(syntheticMessage);
         },

package/dist/media/store.js

@@ -12,6 +12,40 @@ const resolveMediaDir = () => path.join(resolveConfigDir(), "media");
 export const MEDIA_MAX_BYTES = 5 * 1024 * 1024; // 5MB default
 const MAX_BYTES = MEDIA_MAX_BYTES;
 const DEFAULT_TTL_MS = 2 * 60 * 1000; // 2 minutes
+/**
+ * SECURITY: Safe paths for local file extraction
+ *
+ * Prevents LFI (Local File Inclusion) attacks by restricting
+ * local file extraction to known-safe directories.
+ *
+ * Backported from: openclaw/openclaw@2026.1.30 (PR #4880)
+ * Security: CRITICAL
+ */
+const SAFE_PATHS = [
+    "/tmp",
+    "/var/tmp",
+    process.cwd(), // Current working directory
+    resolveConfigDir(), // PoolBot config directory
+];
+/**
+ * Validate that a local path is safe for file extraction.
+ *
+ * Resolves the path and checks if it's within one of the SAFE_PATHS.
+ * Throws an error if the path is outside safe directories.
+ *
+ * @param filePath - The path to validate
+ * @throws Error if path is outside safe directories
+ */
+function validateLocalPath(filePath) {
+    const resolved = path.resolve(filePath);
+    for (const safePath of SAFE_PATHS) {
+        if (resolved.startsWith(safePath)) {
+            return; // Path is safe
+        }
+    }
+    throw new Error(`Unsafe local path: ${filePath} (resolved: ${resolved}). ` +
+        `Path must be within one of: ${SAFE_PATHS.join(", ")}`);
+}
 /**
  * Sanitize a filename for cross-platform safety.
  * Removes chars unsafe on Windows/SharePoint/all platforms.
@@ -158,6 +192,8 @@ export async function saveMediaSource(source, headers, subdir = "") {
         return { id, path: finalDest, size, contentType: mime };
     }
     // local path
+    // SECURITY: Validate local path before reading
+    validateLocalPath(source); // LFI prevention
     const stat = await fs.stat(source);
     if (!stat.isFile()) {
         throw new Error("Media path is not a file");
@@ -175,7 +211,7 @@ export async function saveMediaSource(source, headers, subdir = "") {
 }
 export async function saveMediaBuffer(buffer, contentType, subdir = "inbound", maxBytes = MAX_BYTES, originalFilename) {
     if (buffer.byteLength > maxBytes) {
-        throw new Error(`Media exceeds ${(maxBytes / (1024 * 1024)).toFixed(0)}MB limit`);
+        throw new Error(`Media exceeds ${(maxBytes / 1024 / 1024).toFixed(0)}MB limit`);
     }
     const dir = path.join(resolveMediaDir(), subdir);
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });

package/dist/memory/index.js

@@ -1 +1,6 @@
+/**
+ * Memory Search - Public Exports
+ * Legacy system only (PME removed 2026-02-03)
+ */
+// Legacy memory search system
 export { getMemorySearchManager } from "./search-manager.js";

package/dist/memory/manager.js

@@ -157,6 +157,7 @@ export class MemoryIndexManager {
             this.sessionWarm.add(key);
     }
     async search(query, opts) {
+        const searchStart = Date.now();
         void this.warmSession(opts?.sessionKey);
         if (this.settings.sync.onSearch && (this.dirty || this.sessionsDirty)) {
             void this.sync({ reason: "search" }).catch((err) => {
@@ -179,7 +180,17 @@ export class MemoryIndexManager {
             ? await this.searchVector(queryVec, candidates).catch(() => [])
             : [];
         if (!hybrid.enabled) {
-            return vectorResults.filter((entry) => entry.score >= minScore).slice(0, maxResults);
+            const results = vectorResults.filter((entry) => entry.score >= minScore).slice(0, maxResults);
+            const searchDuration = Date.now() - searchStart;
+            log.debug("memory search performance", {
+                query: cleaned.substring(0, 50),
+                durationMs: searchDuration,
+                resultCount: results.length,
+                provider: this.provider.id,
+                model: this.provider.model,
+                hybrid: false,
+            });
+            return results;
         }
         const merged = this.mergeHybridResults({
             vector: vectorResults,
@@ -187,7 +198,19 @@ export class MemoryIndexManager {
             vectorWeight: hybrid.vectorWeight,
             textWeight: hybrid.textWeight,
         });
-        return merged.filter((entry) => entry.score >= minScore).slice(0, maxResults);
+        const results = merged.filter((entry) => entry.score >= minScore).slice(0, maxResults);
+        const searchDuration = Date.now() - searchStart;
+        log.debug("memory search performance", {
+            query: cleaned.substring(0, 50),
+            durationMs: searchDuration,
+            resultCount: results.length,
+            provider: this.provider.id,
+            model: this.provider.model,
+            hybrid: true,
+            keywordResults: keywordResults.length,
+            vectorResults: vectorResults.length,
+        });
+        return results;
     }
     async searchVector(queryVec, limit) {
         const results = await searchVector({