onbuzz 4.0.1 → 4.1.0

package/src/tools/memoryTool.js

@@ -19,6 +19,14 @@
 
 import { BaseTool } from './baseTool.js';
 import { getMemoryService } from '../services/memoryService.js';
+import {
+  overview as convOverview,
+  range as convRange,
+  search as convSearch,
+  around as convAround,
+  byTool as convByTool,
+  read as convRead,
+} from '../services/conversationQuery.js';
 
 class MemoryTool extends BaseTool {
   constructor(config = {}, logger = null) {
@@ -141,6 +149,124 @@ Level options:
 }
 \`\`\`
 
+8. REMINISCE - Browse your own pre-compaction conversation archive (READ-ONLY)
+
+This is separate from the other actions. It does NOT read memory entries —
+it reads your full past conversation as stored on disk. Use it when you
+recall a detail from earlier in the session (a user instruction, a tool
+output, an earlier decision) that's no longer in your recent context
+because compaction removed it. The archive is durable: every message you
+and the user exchanged is still there, even if you can't see it now.
+
+The stable pointer is \`messageId\`. You can bookmark one result (e.g. from
+\`search\`) and use it later in \`around\` to pull the surrounding context.
+messageIds never change, even as the conversation grows or compaction runs.
+
+Sub-modes:
+
+  8a. overview — "where have I been"
+  \`\`\`json
+  { "toolId": "memory", "action": "reminisce", "mode": "overview" }
+  \`\`\`
+  Returns: totalMessages, firstAt, lastAt, totalApproxTokens, and a sparse
+  timeline of ~20 evenly-spaced markers { at, role, messageId, snippet }.
+
+  8b. range — slice by index or timestamp
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "range",
+    "offset": 0, "limit": 20,
+    "from": "2026-04-18T00:00:00Z", "to": "2026-04-18T12:00:00Z"
+  }
+  \`\`\`
+  Returns: { messages, total, offset, limit, hasMore }.
+
+  8c. search — substring across content + tool-call arguments
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "search",
+    "query": "database schema", "role": "user", "maxResults": 10
+  }
+  \`\`\`
+  Returns: { matches [{ messageId, role, at, source, snippet, highlightRanges }],
+             total, hasMore, cursor }.
+  Pass \`cursor\` back verbatim to get the next page.
+  Note: search does NOT match tool results/outputs — only content and
+  tool-call arguments.
+
+  8d. around — N MESSAGES before + N MESSAGES after a bookmarked messageId
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "around",
+    "messageId": "msg_abc", "before": 3, "after": 3
+  }
+  \`\`\`
+  \`before\` and \`after\` count MESSAGES (not lines, not characters).
+  Range: 0–20 each side. For a larger window, paginate with a new \`around\`
+  call anchored at the messageId of the last-returned entry.
+  Returns: { messages, center, targetFound }.
+
+  8e. byTool — list your past tool calls (optionally filtered)
+  \`\`\`json
+  {
+    "toolId": "memory", "action": "reminisce", "mode": "byTool",
+    "toolId": "terminal", "limit": 20
+  }
+  \`\`\`
+  Returns: { toolCalls [{ messageId, at, toolId, status, inputSnippet }],
+             total, hasMore, cursor }.
+
+  8f. read — open ONE message at sub-message granularity (lines OR chars)
+  \`\`\`json
+  // Read whole message (byte-capped at ~32 KB)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc" }
+
+  // Read lines 100–150 of a long message (stack trace, paste, etc.)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc", "lineFrom": 100, "lineTo": 150 }
+
+  // Read characters 5000–7000 (half-open range)
+  { "toolId": "memory", "action": "reminisce", "mode": "read",
+    "messageId": "msg_abc", "contentFrom": 5000, "contentTo": 7000 }
+  \`\`\`
+  Use this when \`search\` found a hit inside a huge message and the snippet
+  isn't enough, OR when you want to page through a single long message
+  without pulling the whole thing into context.
+
+  Window selectors are mutually exclusive — if you pass both, LINES win.
+  Omit both selectors to read the whole message. Caps: 500 lines / 16 000
+  chars per call. If the message is larger, the response's
+  \`contentWindow.hasMoreAfter\` is true — call \`read\` again with the next
+  \`lineFrom\` or \`contentFrom\` to continue.
+
+  Returns:
+  \`\`\`
+  {
+    message: {
+      messageId, role, at, tokenCount, hasToolCalls, model,
+      content: "<requested slice>",
+      contentWindow: {
+        kind: "lines" | "chars" | "full",
+        lineFrom?, lineTo?, totalLines?,       // kind="lines"
+        contentFrom?, contentTo?,              // kind="chars"
+        totalContentLength,
+        hasMoreBefore, hasMoreAfter,
+        truncatedAtBytes   // byte cap kicked in mid-window
+      }
+    },
+    targetFound, center
+  }
+  \`\`\`
+
+All reminisce responses are byte-capped (~32 KB) to protect your context.
+When a response is capped it includes \`truncatedByBytes > 0\`; fetch fewer
+or narrower results.
+
+Add \`"detail": "full"\` on range/around to receive full untruncated content
+and the raw toolExecutions / contextReferences — use sparingly; it eats
+tokens fast.
+
 BEST PRACTICES:
 - Use memories for important facts, preferences, or decisions that should persist
 - Keep titles concise and searchable
@@ -148,6 +274,11 @@ BEST PRACTICES:
 - Set expiration dates for time-sensitive information
 - Use LIST with "titles" first, then READ specific memories as needed
 - Avoid storing sensitive data (API keys, passwords) in memories
+- For reminisce: start with \`overview\`, then \`search\` or \`range\` to find
+  the right messageId, then \`around\` for surrounding messages or \`read\`
+  to open a specific message (whole, by line range, or by char range).
+  Bookmark messageIds in memory entries via \`[reminisce:msg_xxx]\`
+  references for a durable pointer that survives compaction.
     `;
   }
 
@@ -218,7 +349,7 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
 
     if (!params.action) {
       errors.push('action is required');
@@ -297,6 +428,8 @@ BEST PRACTICES:
           return await this._executeSearch(memoryService, agentId, params);
         case 'stats':
           return await this._executeStats(memoryService, agentId);
+        case 'reminisce':
+          return await this._executeReminisce(agentId, params, context);
         default:
           throw new Error(`Unknown action: ${action}`);
       }
@@ -468,12 +601,106 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute REMINISCE action — read-only query over the agent's
+   * pre-compaction conversation archive (conversations.full.messages).
+   *
+   * Unlike the other memory actions, reminisce does NOT touch memoryService.
+   * It's a lens over a different dataset: the conversation history that
+   * stateManager preserves durably on disk regardless of compaction. The
+   * agent uses it to pull specific spans of past context back into the
+   * current turn when they've fallen out of the active context window.
+   *
+   * Pointer contract: `messageId` values returned here are stable across
+   * session growth and compaction — an agent can bookmark one now and
+   * resolve it in a much later turn (see services/conversationQuery.js).
+   *
+   * @param {string} agentId
+   * @param {Object} params
+   * @param {'overview'|'range'|'search'|'around'|'byTool'} params.mode
+   * @param {Object} context  Must carry `agentPool` to fetch the agent's
+   *                          conversation. If missing, returns a clean
+   *                          failure (not a crash).
+   */
+  async _executeReminisce(agentId, params, context) {
+    const mode = typeof params.mode === 'string' ? params.mode : '';
+    const validModes = ['overview', 'range', 'search', 'around', 'byTool', 'read'];
+    if (!validModes.includes(mode)) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: `mode must be one of: ${validModes.join(', ')}`,
+      };
+    }
+
+    const agentPool = context?.agentPool;
+    if (!agentPool?.getAgent) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: 'agentPool is not available on the tool context; cannot read conversation archive',
+      };
+    }
+
+    const agent = await agentPool.getAgent(agentId);
+    if (!agent) {
+      return {
+        success: false,
+        action: 'reminisce',
+        error: `Agent not found: ${agentId}`,
+      };
+    }
+
+    // Always read from conversations.full — the durable archive that
+    // survives every compaction pass. Never from per-model views.
+    const messages = agent?.conversations?.full?.messages;
+    if (!Array.isArray(messages)) {
+      return {
+        success: true,
+        action: 'reminisce',
+        mode,
+        result: { empty: true, message: 'No conversation archive found for this agent.' },
+      };
+    }
+
+    // Pass only the params relevant to each mode — conversationQuery's
+    // per-mode validators clamp/default the rest.
+    const modeParams = {
+      from: params.from, to: params.to,
+      offset: params.offset, limit: params.limit,
+      query: params.query, role: params.role,
+      maxResults: params.maxResults, cursor: params.cursor,
+      messageId: params.messageId, before: params.before, after: params.after,
+      toolId: params.toolId, detail: params.detail,
+      // read-only window selectors (sub-message granularity)
+      lineFrom: params.lineFrom, lineTo: params.lineTo,
+      contentFrom: params.contentFrom, contentTo: params.contentTo,
+    };
+
+    let result;
+    switch (mode) {
+      case 'overview': result = convOverview(messages); break;
+      case 'range':    result = convRange(messages, modeParams); break;
+      case 'search':   result = convSearch(messages, modeParams); break;
+      case 'around':   result = convAround(messages, modeParams); break;
+      case 'byTool':   result = convByTool(messages, modeParams); break;
+      case 'read':     result = convRead(messages, modeParams); break;
+    }
+
+    return {
+      success: true,
+      action: 'reminisce',
+      mode,
+      result,
+    };
+  }
+
   /**
    * Get supported actions
    * @returns {Array<string>}
    */
   getSupportedActions() {
-    return ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'];
+    return ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
   }
 
   /**
@@ -486,7 +713,7 @@ BEST PRACTICES:
       properties: {
         action: {
           type: 'string',
-          enum: ['add', 'update', 'delete', 'list', 'read', 'search', 'stats'],
+          enum: ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'],
           description: 'Action to perform'
         },
         id: {
@@ -522,7 +749,42 @@ BEST PRACTICES:
         },
         query: {
           type: 'string',
-          description: 'Search query (required for search)'
+          description: 'Search query (required for memory search AND reminisce search)'
+        },
+
+        // ── reminisce-specific parameters ────────────────────────────────
+        // Required when action="reminisce"; ignored otherwise.
+        mode: {
+          type: 'string',
+          enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'],
+          description: 'Reminisce sub-mode (required for action="reminisce")'
+        },
+        messageId: {
+          type: 'string',
+          description: 'Stable conversation-archive pointer. Required for reminisce around/read.'
+        },
+        from: { type: 'string', description: 'ISO timestamp lower bound (reminisce range)' },
+        to:   { type: 'string', description: 'ISO timestamp upper bound (reminisce range)' },
+        offset:     { type: 'integer', description: 'Pagination offset (reminisce range)' },
+        limit:      { type: 'integer', description: 'Max entries (reminisce range/byTool), 1–100' },
+        maxResults: { type: 'integer', description: 'Max search matches (reminisce search), 1–50' },
+        role: {
+          type: 'string',
+          enum: ['user', 'assistant', 'system'],
+          description: 'Role filter for reminisce search'
+        },
+        cursor: { type: 'string', description: 'Opaque pagination cursor (reminisce search/byTool) — pass verbatim from a previous response' },
+        toolId: { type: 'string', description: 'Filter by toolId (reminisce byTool)' },
+        before: { type: 'integer', description: 'Messages BEFORE the target (reminisce around), 0–20' },
+        after:  { type: 'integer', description: 'Messages AFTER the target (reminisce around), 0–20' },
+        lineFrom:    { type: 'integer', description: 'First line (reminisce read), 1-indexed inclusive' },
+        lineTo:      { type: 'integer', description: 'Last line (reminisce read), 1-indexed inclusive; window ≤ 500 lines' },
+        contentFrom: { type: 'integer', description: 'Char offset start (reminisce read), 0-indexed inclusive. Ignored if lineFrom is set.' },
+        contentTo:   { type: 'integer', description: 'Char offset end (reminisce read), 0-indexed exclusive; window ≤ 16000 chars' },
+        detail: {
+          type: 'string',
+          enum: ['default', 'full'],
+          description: 'Reminisce return shape: "default" (truncated/slim) or "full" (everything)'
         }
       },
       required: ['action']

package/src/tools/openaiFunctionSchemas.js

@@ -222,27 +222,82 @@ export const OPENAI_FUNCTION_SCHEMAS = [
     },
   },
   // Memory — flat params (no actions array). Field names mirror the tool's
-  // validate/execute sites in src/tools/memoryTool.js (params.action/id/title/
-  // content/description/query/level).
+  // validate/execute sites in src/tools/memoryTool.js.
+  //
+  // Memory-entry actions (user-authored notes):
   //   add:             {action, title, content, description?}
   //   update:          {action, id, title?, content?, description?}
   //   delete|read:     {action, id}
   //   list:            {action, level?}
   //   search:          {action, query, level?}
+  //   stats:           {action}
+  //
+  // Conversation-archive action (read-only browse of the agent's own past
+  // conversation — survives compaction; see src/services/conversationQuery.js):
+  //   reminisce:       {action, mode, ...mode-specific params}
+  //     overview       — {mode}
+  //     range          — {mode, from?, to?, offset?, limit?, detail?}
+  //     search         — {mode, query, role?, maxResults?, cursor?, detail?}
+  //     around         — {mode, messageId, before?, after?, detail?}
+  //     byTool         — {mode, toolId?, limit?, cursor?}
+  //     read           — {mode, messageId, lineFrom?/lineTo? OR contentFrom?/contentTo?, detail?}
   {
     type: 'function',
     name: 'memory',
-    description: 'Store and retrieve persistent memories across sessions.',
+    description: 'Store and retrieve persistent memories across sessions, and browse your own pre-compaction conversation archive via the `reminisce` action.',
     parameters: {
       type: 'object',
       properties: {
-        action:      { type: 'string', enum: ['add', 'update', 'delete', 'read', 'list', 'search'] },
-        id:          { type: 'string', description: 'Memory id. Required for: update, delete, read.' },
+        action:      { type: 'string', enum: ['add', 'update', 'delete', 'read', 'list', 'search', 'stats', 'reminisce'] },
+        id:          { type: 'string', description: 'Memory id. Required for: update, delete, read (of memory entries).' },
         title:       { type: 'string', description: 'Short title. Required for: add. Optional for: update.' },
         content:     { type: 'string', description: 'Full memory content. Required for: add. Optional for: update.' },
         description: { type: 'string', description: 'Short summary. Optional for: add, update.' },
-        query:       { type: 'string', description: 'Search query. Required for: search.' },
-        level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for list/search output.' },
+        query:       { type: 'string', description: 'Search query. Required for memory search AND reminisce search.' },
+        level:       { type: 'string', enum: ['titles', 'descriptions', 'full'], description: 'Detail level for memory list/search output.' },
+
+        // ── reminisce-specific params ─────────────────────────────────────
+        mode: {
+          type: 'string',
+          enum: ['overview', 'range', 'search', 'around', 'byTool', 'read'],
+          description: 'Reminisce sub-mode. Required when action="reminisce".',
+        },
+        messageId: {
+          type: 'string',
+          description: 'Stable pointer into the conversation archive. Required for reminisce around/read. Get messageIds from overview/search/range/byTool results.',
+        },
+        // range / search / byTool paging
+        from:        { type: 'string', description: 'ISO timestamp lower bound (reminisce range).' },
+        to:          { type: 'string', description: 'ISO timestamp upper bound (reminisce range).' },
+        offset:      { type: 'integer', description: 'Pagination offset (reminisce range).' },
+        limit:       { type: 'integer', description: 'Max entries returned (reminisce range/byTool). 1–100.' },
+        maxResults:  { type: 'integer', description: 'Max search matches returned (reminisce search). 1–50.' },
+        role: {
+          type: 'string',
+          enum: ['user', 'assistant', 'system'],
+          description: 'Filter by message role (reminisce search).',
+        },
+        cursor:      { type: 'string', description: 'Opaque pagination cursor from a previous reminisce search/byTool response. Pass verbatim to continue.' },
+        toolId:      { type: 'string', description: 'Filter by toolId (reminisce byTool).' },
+        // around — MESSAGES on each side of the target
+        before: {
+          type: 'integer',
+          description: 'Number of MESSAGES before the target to include (reminisce around). 0–20.',
+        },
+        after: {
+          type: 'integer',
+          description: 'Number of MESSAGES after the target to include (reminisce around). 0–20.',
+        },
+        // read — sub-message window, mutually exclusive (lines win if both)
+        lineFrom:    { type: 'integer', description: 'First line to read, 1-indexed inclusive (reminisce read).' },
+        lineTo:      { type: 'integer', description: 'Last line to read, 1-indexed inclusive (reminisce read). Window capped at 500 lines.' },
+        contentFrom: { type: 'integer', description: 'First character offset (reminisce read, 0-indexed inclusive). Ignored if lineFrom is set.' },
+        contentTo:   { type: 'integer', description: 'Last character offset (reminisce read, 0-indexed exclusive). Window capped at 16000 chars.' },
+        detail: {
+          type: 'string',
+          enum: ['default', 'full'],
+          description: 'Return shape: "default" truncates content and omits toolExecutions; "full" returns everything (eats tokens fast).',
+        },
       },
       required: ['action'],
     },

package/src/tools/taskManagerTool.js

@@ -257,10 +257,27 @@ Complete a task:
 {"toolId": "taskmanager", "actions": [{"type": "complete", "taskId": "task-123"}]}
 \`\`\`
 
-WORKFLOW:
-1. List tasks to see current state
-2. Work on tasks
-3. Mark tasks complete when done
+RECOMMENDED WORKFLOW (read this before your first call)
+
+Phase 1 — Plan (ONE call, at the start):
+  \`sync\` with the full list of planned tasks. All start "pending".
+  Don't issue \`create\` one-by-one — that's many calls where one would do.
+
+Phase 2 — Execute (per step, repeating):
+  a. \`update\` { taskId, status: "in_progress" }   — pick up the next task
+  b. do the actual work using other tools
+  c. \`update\` { taskId, status: "completed" }     — finish it, move to the next
+  (the scheduler enforces at most one task in_progress at a time)
+
+Phase 3 — Refine (as you discover new work):
+  - \`create\` a single new task, OR
+  - \`sync\` again with the restated full list when the plan materially changes.
+  \`sync\` is safe to call repeatedly — it matches by title and preserves
+  existing status on unchanged tasks. Don't \`sync\` every turn, though —
+  prefer targeted \`update\`/\`create\` unless the plan itself shifted.
+
+Phase 4 — Finish:
+  When every task is "completed", call the \`jobdone\` tool.
 
 **MANDATORY**: Complete tasks when finished or you'll loop forever!
 

package/src/tools/visualEditorTool.js

@@ -319,6 +319,22 @@ Code:
    * @returns {Promise<Object>} Execution result
    */
   async execute(params, context = {}) {
+    // FIRST THING: an unconditional console.log so we can always see that
+    // the tool was invoked — before any early-return (parse failure,
+    // bridge disabled, validation fail) or thrown error could swallow it.
+    // Earlier the log lived past a `bridge.isEnabled()` gate and was
+    // silently skipped whenever that gate tripped, making it look like
+    // the tool wasn't being called at all.
+    console.log('[VisualEditorTool] execute() called', {
+      paramsType: typeof params,
+      paramsAction: params?.action,
+      paramsUrl: params?.url,
+      agentId: context?.agentId,
+      hasGlobalWebServer: !!global.loxiaWebServer,
+      hasOrchestratorWebServer: !!context?.orchestrator?.webServer,
+      hasAgentPool: !!context?.agentPool,
+    });
+
     try {
       const { agentId } = context;
 
@@ -334,6 +350,7 @@ Code:
 
       // Check if bridge is enabled
       if (!bridge.isEnabled()) {
+        console.warn('[VisualEditorTool] Early exit: bridge.isEnabled() === false');
         return {
           success: false,
           error: 'Visual editor is disabled. Enable it in configuration.'
@@ -343,12 +360,19 @@ Code:
       // Validate
       const validation = this.customValidateParameters(params);
       if (!validation.valid) {
+        console.warn('[VisualEditorTool] Early exit: validation failed', { action: params?.action, error: validation.error });
         return {
           success: false,
           error: validation.error
         };
       }
 
+      // Confirmation that we reached action dispatch
+      console.log(`[VisualEditorTool] Action=${params.action} — about to dispatch`, {
+        agentId,
+        url: params.url,
+      });
+
       // Route to action handler
       switch (params.action) {
         case ACTIONS.GET_CONTEXT:
@@ -401,7 +425,16 @@ Code:
       }
 
     } catch (error) {
-      this.logger?.error('Visual editor tool error:', error);
+      // Log full stack + action context so failures that happen BEFORE
+      // the broadcast fires (e.g., bridge.getInstance throws) are
+      // visible in the Node console. Previously the tool returned a
+      // clean error string to the agent and the human operator saw
+      // nothing — making "the editor never opens" undebuggable.
+      console.error(`[VisualEditorTool] Action=${params?.action} FAILED: ${error.message}`, {
+        agentId,
+        action: params?.action,
+        stack: error.stack,
+      });
       return {
         success: false,
         error: error.message
@@ -904,7 +937,19 @@ Or for static HTML, use 'serve-static' action instead (auto-opens the editor).
   }
 
   /**
-   * Broadcast open-editor command to web-ui
+   * Broadcast open-editor command to web-ui.
+   *
+   * Fan-out semantics: we deliberately pass `null` as sessionId so the
+   * webServer's broadcastToSession falls through to its "broadcast to all
+   * connections" path. Previously this used `context.sessionId ||
+   * 'web-session'`, but `context.sessionId` is usually the agent's
+   * scheduler session (`scheduler-session`) which doesn't match any UI
+   * WebSocket connection, and the literal `'web-session'` fallback only
+   * matches if a client happens to have that exact id. In both cases the
+   * underlying broadcastToSession also falls back to "all clients", but
+   * the path is log-noisy ("⚠ No connections for session") and semantically
+   * misleading. The visual editor auto-open is inherently a UI-scoped
+   * notification — we want every attached browser to hear it.
    * @private
    */
   _broadcastOpenEditor(context, data) {
@@ -917,34 +962,54 @@ Or for static HTML, use 'serve-static' action instead (auto-opens the editor).
       }
     };
 
-    // Method 1: Through agentPool messageProcessor
-    if (context.agentPool?.messageProcessor?.orchestrator?.webServer) {
-      context.agentPool.messageProcessor.orchestrator.webServer.broadcastToSession(
-        context.sessionId || 'web-session',
-        message
-      );
+    // Use plain console.log so the success path always prints even when
+    // the tool was constructed without a logger (pre-logger-propagation
+    // registries, test harnesses, future refactors).
+    const log = (path) =>
+      console.log(`[VisualEditorTool] Broadcast visual_editor_open via ${path}`, {
+        agentId: data.agentId,
+        appUrl: data.appUrl,
+      });
+
+    // Prefer the global webServer reference. Rationale:
+    //   - It's set exactly once, at boot (`global.loxiaWebServer = webServer`
+    //     in src/index.js after the server's own `initialize()` resolves).
+    //   - It bypasses any context-wiring subtlety. The tool's context can
+    //     be shaped differently depending on how the tool was invoked
+    //     (scheduler vs. direct orchestrator vs. flow executor), and
+    //     past outages have been "the context path USED to be populated,
+    //     then someone refactored the orchestrator setter order and the
+    //     inner path silently became undefined". The global dodges that.
+    //   - Verified live: the `/api/visual-editor/debug-broadcast` endpoint
+    //     uses the same webServer.broadcastToSession(null, ...) call and
+    //     delivers successfully every time.
+    // The context-based paths are kept as belt-and-braces fallbacks for
+    // any unusual execution environment (tests, possible future
+    // embedded use) where `global` wasn't initialized.
+    if (global.loxiaWebServer?.broadcastToSession) {
+      global.loxiaWebServer.broadcastToSession(null, message);
+      log('global.loxiaWebServer');
       return;
     }
 
-    // Method 2: Direct orchestrator access
-    if (context.orchestrator?.webServer) {
-      context.orchestrator.webServer.broadcastToSession(
-        context.sessionId || 'web-session',
-        message
-      );
+    if (context.agentPool?.messageProcessor?.orchestrator?.webServer?.broadcastToSession) {
+      context.agentPool.messageProcessor.orchestrator.webServer.broadcastToSession(null, message);
+      log('agentPool.messageProcessor.orchestrator.webServer');
       return;
     }
 
-    // Method 3: Global reference fallback
-    if (global.loxiaWebServer) {
-      global.loxiaWebServer.broadcastToSession(
-        context.sessionId || 'web-session',
-        message
-      );
+    if (context.orchestrator?.webServer?.broadcastToSession) {
+      context.orchestrator.webServer.broadcastToSession(null, message);
+      log('context.orchestrator.webServer');
       return;
     }
 
-    this.logger?.warn('[VisualEditorTool] Could not broadcast open-editor command - no webServer access');
+    console.warn('[VisualEditorTool] Could not broadcast open-editor command - no webServer access', {
+      hasContext: !!context,
+      hasAgentPool: !!context?.agentPool,
+      hasOrchestrator: !!context?.orchestrator,
+      hasGlobal: !!global.loxiaWebServer,
+    });
   }
 
   // === Phase 5 Action Handlers ===