onbuzz 4.0.0 → 4.0.2

package/src/services/messageSource.js

@@ -0,0 +1,318 @@
+/**
+ * Message source — provenance metadata for inbound user messages.
+ *
+ * Attached at the inbound-service boundary (Discord / Telegram inbound),
+ * preserved verbatim through the orchestrator -> messageProcessor ->
+ * agentPool pipeline, and rendered as a single attribution line prepended
+ * to the message content so the agent can see where the message arrived
+ * from and decide for itself how to respond.
+ *
+ * Design notes
+ * ------------
+ *  - Pure module. No discord.js / node-telegram-bot-api imports. Tests run
+ *    without network, DB, or platform-SDK setup.
+ *  - Factories are defensive: they accept the full platform message object
+ *    and tolerate missing fields rather than throwing. A partial source is
+ *    better than no source for the agent to reason about.
+ *  - Output is deeply frozen so downstream code can't silently mutate
+ *    provenance. Surprising mutation of a source once it's on a queued
+ *    message would be a correctness nightmare to debug.
+ *  - `alias` is chosen to match the strings advertised by
+ *    discordService.getBridgedChannels / telegramService.getBridgedChannels,
+ *    so <external to="…"> routing composes with channelFilter's substring
+ *    matching without any translation layer.
+ *  - `describeSource(src)` returns a human-readable attribution for the
+ *    header; `prependSourceHeader(content, src)` is idempotent so replaying
+ *    a message through the pipeline never double-prefixes.
+ */
+
+/**
+ * Exhaustive discriminator for the source kind. Adding a new kind is a
+ * deliberate act — downstream consumers (the scheduler's prompt injector,
+ * the relay services) switch on this value.
+ */
+export const MESSAGE_SOURCE_KINDS = Object.freeze({
+  DISCORD: 'discord',
+  TELEGRAM: 'telegram',
+  WEB: 'web',
+  API: 'api',
+  INTERNAL: 'internal',
+});
+
+/**
+ * @typedef {Object} MessageSource
+ * @property {'discord'|'telegram'|'web'|'api'|'internal'} kind
+ * @property {string} alias
+ * @property {string} sessionId
+ * @property {Object} raw  Kind-specific identifiers (channel ids, user ids, …)
+ */
+
+/**
+ * Deep-freeze a plain object tree. Keeps the source literal-immutable so
+ * any code that treats it as a value-object is safe.
+ * @param {any} value
+ * @returns {any}
+ */
+function freezeDeep(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Object.isFrozen(value)) return value;
+  for (const key of Object.keys(value)) {
+    freezeDeep(value[key]);
+  }
+  return Object.freeze(value);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Discord
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a MessageSource from a discord.js Message object.
+ *
+ * Tolerant of missing fields: DMs have no guild, non-threaded channels
+ * have no parent, bot-posted messages have no author — each just produces
+ * a `null` in the raw payload and is gracefully handled by describeSource.
+ *
+ * @param {Object} discordMessage  discord.js Message
+ * @returns {MessageSource}
+ */
+export function createDiscordSource(discordMessage) {
+  const msg = discordMessage || {};
+  const channel = msg.channel || {};
+  const guild = msg.guild || null;
+  const author = msg.author || {};
+
+  const isThread = typeof channel.isThread === 'function'
+    ? !!channel.isThread()
+    : false;
+
+  const raw = {
+    messageId: msg.id ?? null,
+    channelId: channel.id ?? null,
+    channelName: channel.name ?? null,
+    authorId: author.id ?? null,
+    authorName: author.username ?? author.globalName ?? null,
+    guildId: guild?.id ?? null,
+    guildName: guild?.name ?? null,
+    // Thread metadata: threadId/threadName are set only when the message
+    // arrived inside a thread. parentChannel* records the channel the
+    // thread lives under, so describeSource can render the full path.
+    threadId: isThread ? (channel.id ?? null) : null,
+    threadName: isThread ? (channel.name ?? null) : null,
+    parentChannelId: isThread ? (channel.parentId ?? null) : null,
+    parentChannelName: isThread ? (channel.parent?.name ?? null) : null,
+  };
+
+  const alias = _computeDiscordAlias(raw);
+  const sessionId = `discord-${raw.guildId || 'dm'}-${raw.channelId || 'unknown'}`;
+
+  return freezeDeep({
+    kind: MESSAGE_SOURCE_KINDS.DISCORD,
+    alias,
+    sessionId,
+    raw,
+  });
+}
+
+/**
+ * Canonical Discord alias. Format matches discordService.getBridgedChannels
+ * output so the agent can round-trip an alias from the bridged-channel list
+ * back through `<external to="…">` with no translation.
+ *
+ * For threads we still alias by the thread's own channel id / name because
+ * that's what the relay dispatches to. The parent channel is only used for
+ * the human-readable label.
+ * @private
+ */
+function _computeDiscordAlias(raw) {
+  if (raw.channelName) return `discord:#${raw.channelName}`;
+  if (raw.channelId) return `discord:${raw.channelId}`;
+  return 'discord:unknown';
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Telegram
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a MessageSource from a node-telegram-bot-api Message object.
+ *
+ * @param {Object} telegramMessage  node-telegram-bot-api Message
+ * @returns {MessageSource}
+ */
+export function createTelegramSource(telegramMessage) {
+  const msg = telegramMessage || {};
+  const chat = msg.chat || {};
+  const from = msg.from || {};
+
+  const raw = {
+    messageId: msg.message_id ?? null,
+    chatId: chat.id ?? null,
+    chatType: chat.type ?? null,      // 'private' | 'group' | 'supergroup' | 'channel'
+    chatTitle: chat.title ?? null,
+    userId: from.id ?? null,
+    userName: from.username ?? from.first_name ?? null,
+  };
+
+  // Telegram's relay service today is single-chat-per-instance and
+  // advertises the bare alias `telegram`. For per-chat addressability we
+  // emit `telegram:chat-<id>` which matches exactly one owned alias when
+  // the service's bridge list grows richer, and still substring-matches
+  // `telegram` (the current owned alias) when it doesn't.
+  const alias = raw.chatId != null ? `telegram:chat-${raw.chatId}` : 'telegram';
+  const sessionId = `telegram-${raw.chatId ?? 'unknown'}`;
+
+  return freezeDeep({
+    kind: MESSAGE_SOURCE_KINDS.TELEGRAM,
+    alias,
+    sessionId,
+    raw,
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Web / API / Internal  (null-object-ish; produces no header)
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ sessionId?: string, userName?: string }} [info]
+ * @returns {MessageSource}
+ */
+export function createWebSource(info = {}) {
+  const sessionId = info.sessionId || 'web-unknown';
+  return freezeDeep({
+    kind: MESSAGE_SOURCE_KINDS.WEB,
+    alias: `web:${sessionId}`,
+    sessionId,
+    raw: { sessionId, userName: info.userName ?? null },
+  });
+}
+
+/**
+ * For scheduler / flow-injected messages where no human channel is behind
+ * the send. `describeSource` returns null for internal sources so no
+ * header is prepended — the agent sees the raw content as before.
+ * @param {string} [reason]
+ * @returns {MessageSource}
+ */
+export function createInternalSource(reason = 'internal') {
+  return freezeDeep({
+    kind: MESSAGE_SOURCE_KINDS.INTERNAL,
+    alias: `internal:${reason}`,
+    sessionId: `internal-${reason}`,
+    raw: { reason },
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Rendering
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Produce the human-readable attribution sentence for a source, or null
+ * when the source is absent / of a kind that doesn't warrant a header
+ * (web, api, internal — those interactions don't need to teach the agent
+ * where the message came from).
+ *
+ * Output shape (examples):
+ *   Discord guild channel    → "Message by alice from Discord > MyGuild > #ops"
+ *   Discord thread           → "Message by alice from Discord > MyGuild > #ops > Deploy thread"
+ *   Discord DM               → "Message by alice from Discord > DM"
+ *   Telegram group           → "Message by alice from Telegram > Ops Chat"
+ *   Telegram private         → "Message by alice from Telegram > DM"
+ *
+ * @param {MessageSource|null|undefined} source
+ * @returns {string|null}
+ */
+export function describeSource(source) {
+  if (!source || typeof source !== 'object') return null;
+  const raw = source.raw || {};
+
+  switch (source.kind) {
+    case MESSAGE_SOURCE_KINDS.DISCORD: {
+      const user = raw.authorName || 'unknown user';
+      const parts = ['Discord'];
+      // Thread path: Discord > Guild > #parent > ThreadName
+      // Flat path:   Discord > Guild > #channel
+      // DM path:     Discord > DM
+      if (raw.guildName) parts.push(raw.guildName);
+
+      if (raw.parentChannelName || raw.threadName) {
+        if (raw.parentChannelName) parts.push(`#${raw.parentChannelName}`);
+        if (raw.threadName) parts.push(raw.threadName);
+      } else if (raw.channelName) {
+        parts.push(`#${raw.channelName}`);
+      }
+
+      // No guild and no channel name usually means a DM (or a stripped-down
+      // test fixture). Label it as DM rather than leaving a bare "Discord".
+      if (parts.length === 1) parts.push('DM');
+
+      return `Message by ${user} from ${parts.join(' > ')}`;
+    }
+
+    case MESSAGE_SOURCE_KINDS.TELEGRAM: {
+      const user = raw.userName || 'unknown user';
+      const parts = ['Telegram'];
+      if (raw.chatType === 'private') {
+        parts.push('DM');
+      } else if (raw.chatTitle) {
+        parts.push(raw.chatTitle);
+      } else if (raw.chatId != null) {
+        parts.push(`chat ${raw.chatId}`);
+      } else {
+        parts.push('DM');
+      }
+      return `Message by ${user} from ${parts.join(' > ')}`;
+    }
+
+    case MESSAGE_SOURCE_KINDS.WEB:
+    case MESSAGE_SOURCE_KINDS.API:
+    case MESSAGE_SOURCE_KINDS.INTERNAL:
+    default:
+      return null;
+  }
+}
+
+/**
+ * Format the header line — a parenthesized describeSource() output — or
+ * empty string when the source has no describable shape.
+ * @param {MessageSource|null|undefined} source
+ * @returns {string}
+ */
+export function formatSourceHeader(source) {
+  const desc = describeSource(source);
+  return desc ? `(${desc})` : '';
+}
+
+/**
+ * Prepend the source attribution header to a user message's content.
+ *
+ * Idempotent: if the content already begins with the exact header line,
+ * nothing is added. This keeps the pipeline safe against re-serialization
+ * (state restore, compaction, retry) without baking a "did-we-prefix" flag
+ * into the message shape.
+ *
+ * @param {string} content
+ * @param {MessageSource|null|undefined} source
+ * @returns {string}
+ */
+export function prependSourceHeader(content, source) {
+  const header = formatSourceHeader(source);
+  if (!header) return typeof content === 'string' ? content : String(content ?? '');
+
+  const text = typeof content === 'string' ? content : String(content ?? '');
+  if (text.startsWith(header)) return text;
+  return `${header}\n${text}`;
+}
+
+export default {
+  MESSAGE_SOURCE_KINDS,
+  createDiscordSource,
+  createTelegramSource,
+  createWebSource,
+  createInternalSource,
+  describeSource,
+  formatSourceHeader,
+  prependSourceHeader,
+};

package/src/services/telegramService.js

@@ -19,6 +19,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { getUserDataPaths, ensureUserDataDirs } from '../utilities/userDataDir.js';
 import { filterContentForExternalRelay, resolveBlockTargets } from './channelFilter.js';
+import { createTelegramSource } from './messageSource.js';
 
 const TELEGRAM_STATUS = {
   DISCONNECTED: 'disconnected',
@@ -521,6 +522,10 @@ class TelegramService {
 
       if (this.orchestrator) {
         const sessionId = `telegram-${this.chatId}`;
+        // Capture source at ingress — see services/messageSource.js. The
+        // source rides the payload into the orchestrator and becomes the
+        // `(Message by alice from Telegram > …)` line the agent sees.
+        const source = createTelegramSource(msg);
         await this.orchestrator.processRequest({
           interface: 'telegram',
           sessionId,
@@ -528,7 +533,8 @@ class TelegramService {
           payload: {
             agentId: targetAgent.id,
             message: messageText,
-            streamingEnabled: false
+            streamingEnabled: false,
+            source,
           },
           projectDir: this.orchestrator.config?.project?.directory || process.cwd()
         });

package/src/services/visualEditorServer.js

@@ -859,22 +859,50 @@ class VisualEditorServer {
 
     // Add a <base> tag to make relative URLs resolve to the original site
     // This prevents assets (scripts, styles, images) from being requested through our server
+    //
+    // IMPORTANT: The base href must include the *directory* of the target URL, not just
+    // the origin. If the target is http://host/sub/page.html and we set <base href="http://host/">,
+    // then a relative <link href="styles.css"> resolves to http://host/styles.css (wrong) instead
+    // of http://host/sub/styles.css (correct). We compute the directory portion of the pathname
+    // and use that as the base href.
     let baseTag = '';
     try {
       const parsed = new URL(targetUrl);
-      baseTag = `<base href="${parsed.origin}/">`;
+      // Derive directory: for /sub/page.html -> /sub/, for /sub/ -> /sub/, for / -> /
+      let dir = parsed.pathname;
+      if (!dir.endsWith('/')) {
+        const lastSlash = dir.lastIndexOf('/');
+        dir = lastSlash >= 0 ? dir.substring(0, lastSlash + 1) : '/';
+      }
+      baseTag = `<base href="${parsed.origin}${dir}">`;
     } catch (e) {
       // Invalid URL, skip base tag
     }
 
     let modifiedHtml = html;
 
-    // Inject base tag after <head> (if not already present)
-    if (baseTag && !html.toLowerCase().includes('<base ')) {
-      if (html.includes('<head>')) {
-        modifiedHtml = modifiedHtml.replace('<head>', `<head>${baseTag}`);
-      } else if (html.includes('<HEAD>')) {
-        modifiedHtml = modifiedHtml.replace('<HEAD>', `<HEAD>${baseTag}`);
+    // Inject base tag right after the opening <head ...> tag (case-insensitive, allows attributes).
+    // If there is no <head> at all, synthesize one after <html ...> so we still get a base.
+    // If a <base> already exists in the document, rewrite its href — the original would point
+    // at the original site path and we want it pointed at our resolved directory instead.
+    if (baseTag) {
+      const hasBase = /<base\b[^>]*>/i.test(html);
+      if (hasBase) {
+        // Replace the first <base ...> with our computed one
+        modifiedHtml = modifiedHtml.replace(/<base\b[^>]*>/i, baseTag);
+      } else {
+        const headOpenRe = /<head\b[^>]*>/i;
+        if (headOpenRe.test(modifiedHtml)) {
+          modifiedHtml = modifiedHtml.replace(headOpenRe, (match) => `${match}${baseTag}`);
+        } else {
+          const htmlOpenRe = /<html\b[^>]*>/i;
+          if (htmlOpenRe.test(modifiedHtml)) {
+            modifiedHtml = modifiedHtml.replace(htmlOpenRe, (match) => `${match}<head>${baseTag}</head>`);
+          } else {
+            // No <html> either — prepend a head block
+            modifiedHtml = `<head>${baseTag}</head>${modifiedHtml}`;
+          }
+        }
       }
     }
 

package/src/tools/__tests__/visualEditorTool.broadcast.test.js

@@ -64,6 +64,16 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     }
   });
 
+  // ── Session targeting: always null so the webServer fan-out path runs ──
+  //
+  // The visual-editor open-editor / set-app-url broadcast is a UI-wide
+  // notification — we want every attached browser to hear it. `context.sessionId`
+  // here is the agent's scheduler session (e.g. 'scheduler-session'), which
+  // doesn't match any UI WebSocket connection. Passing `null` explicitly
+  // makes broadcastToSession take its "no session match, deliver to all
+  // connections" path — cleaner than accidentally landing there via a
+  // mismatched session string.
+
   // ── Path 1: through agentPool ────────────────────────────────────
   test('uses agentPool.messageProcessor.orchestrator.webServer when available', () => {
     const tool = makeTool();
@@ -82,7 +92,7 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     tool._broadcastOpenEditor(context, sampleData);
 
     expect(broadcastToSession).toHaveBeenCalledTimes(1);
-    expect(broadcastToSession).toHaveBeenCalledWith('session-A', {
+    expect(broadcastToSession).toHaveBeenCalledWith(null, {
       type: 'visual_editor_open',
       data: {
         agentId: 'agent-1',
@@ -92,10 +102,15 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     });
   });
 
-  test('falls back to "web-session" when sessionId is missing on agentPool path', () => {
+  test('ignores context.sessionId — always broadcasts to all connections', () => {
+    // Regression guard: previously `sessionId || 'web-session'` was passed
+    // as the target. Either path effectively fell through to "all clients"
+    // via the webServer's fallback, but the intent wasn't explicit. Now
+    // we pass `null` no matter what.
     const tool = makeTool();
     const broadcastToSession = jest.fn();
     const context = {
+      sessionId: 'scheduler-session',  // the scheduler's own session
       agentPool: {
         messageProcessor: {
           orchestrator: { webServer: { broadcastToSession } }
@@ -104,7 +119,8 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     };
 
     tool._broadcastOpenEditor(context, sampleData);
-    expect(broadcastToSession).toHaveBeenCalledWith('web-session', expect.any(Object));
+    const [targetSessionId] = broadcastToSession.mock.calls[0];
+    expect(targetSessionId).toBeNull();
   });
 
   // ── Path 2: direct orchestrator ──────────────────────────────────
@@ -117,7 +133,7 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     };
 
     tool._broadcastOpenEditor(context, sampleData);
-    expect(broadcastToSession).toHaveBeenCalledWith('session-B', expect.objectContaining({
+    expect(broadcastToSession).toHaveBeenCalledWith(null, expect.objectContaining({
       type: 'visual_editor_open'
     }));
   });
@@ -150,19 +166,19 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     const context = { sessionId: 'session-D' };
     tool._broadcastOpenEditor(context, sampleData);
 
-    expect(broadcastToSession).toHaveBeenCalledWith('session-D', expect.objectContaining({
+    expect(broadcastToSession).toHaveBeenCalledWith(null, expect.objectContaining({
       type: 'visual_editor_open',
       data: expect.objectContaining({ agentId: 'agent-1' })
     }));
   });
 
-  test('global fallback also defaults sessionId to "web-session"', () => {
+  test('global fallback also uses null sessionId (UI-wide broadcast)', () => {
     const tool = makeTool();
     const broadcastToSession = jest.fn();
     global.loxiaWebServer = { broadcastToSession };
 
     tool._broadcastOpenEditor({}, sampleData);
-    expect(broadcastToSession).toHaveBeenCalledWith('web-session', expect.any(Object));
+    expect(broadcastToSession).toHaveBeenCalledWith(null, expect.any(Object));
   });
 
   // ── No webServer at all → warn but don't throw ───────────────────
@@ -170,10 +186,24 @@ describe('VisualEditorTool._broadcastOpenEditor', () => {
     const tool = makeTool();
     const context = {}; // Nothing at all
 
-    expect(() => tool._broadcastOpenEditor(context, sampleData)).not.toThrow();
-    expect(tool.logger.warn).toHaveBeenCalledWith(
-      expect.stringContaining('Could not broadcast open-editor')
-    );
+    // Warn is emitted via console.warn (not this.logger) so the message
+    // surfaces even when the tool was constructed without a logger
+    // (historic registry behavior).
+    const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      expect(() => tool._broadcastOpenEditor(context, sampleData)).not.toThrow();
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Could not broadcast open-editor'),
+        expect.objectContaining({
+          hasContext: true,
+          hasAgentPool: false,
+          hasOrchestrator: false,
+          hasGlobal: false,
+        })
+      );
+    } finally {
+      consoleWarnSpy.mockRestore();
+    }
   });
 
   test('handles partial agentPool object gracefully (no messageProcessor)', () => {

package/src/tools/__tests__/visualEditorTool.context.test.js

@@ -0,0 +1,141 @@
+/**
+ * Tests for VisualEditorTool's project-root context resolution.
+ *
+ * Why this exists:
+ *   The tool's action handlers (detect-project, serve-static, detect-dev-port,
+ *   open-editor) need the agent's working directory. Historically the code
+ *   read only `context.projectRoot || context.workingDirectory`, but the
+ *   canonical key messageProcessor (src/core/messageProcessor.js:455) passes
+ *   is `context.projectDir`. That mismatch meant every agent-initiated call
+ *   silently fell through with "No project directory available" — the editor
+ *   only worked when invoked through a legacy path or with the URL typed
+ *   manually.
+ *
+ *   These tests lock in the three-name fallback so a future refactor can't
+ *   silently regress the resolution order.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+// Mock heavy dependencies the tool imports at load time
+jest.unstable_mockModule('../../services/visualEditorBridge.js', () => ({
+  getVisualEditorBridge: jest.fn(),
+  InstanceStatus: { CONNECTED: 'connected', DISCONNECTED: 'disconnected' }
+}));
+jest.unstable_mockModule('../../services/visualEditorServer.js', () => ({
+  getVisualEditorServer: jest.fn(),
+  getVisualEditorPort: jest.fn(() => 4000),
+  getVisualEditorBaseUrl: jest.fn(() => 'http://localhost:4000')
+}));
+jest.unstable_mockModule('../../services/portTracker.js', () => ({
+  getPortTracker: jest.fn()
+}));
+
+// Project detector is the key mock — we control what it returns so the
+// handler's resolution logic is the only thing under test.
+const detectMock = jest.fn();
+const getSuggestedServerCommand = jest.fn(() => ({ command: 'npm start', port: 3000 }));
+jest.unstable_mockModule('../../services/projectDetector.js', () => ({
+  getProjectDetector: jest.fn(() => ({
+    detect: detectMock,
+    getSuggestedServerCommand
+  })),
+  PROJECT_TYPES: {}
+}));
+
+const { VisualEditorTool } = await import('../visualEditorTool.js');
+
+function makeTool() {
+  return new VisualEditorTool({}, createMockLogger());
+}
+
+const happyDetection = {
+  projectType: 'react-vite',
+  framework: 'react',
+  isStatic: false,
+  entryPoints: ['src/main.jsx'],
+  availableScripts: ['dev', 'build'],
+  confidence: 'high'
+};
+
+describe('VisualEditorTool._handleDetectProject — context-key resolution', () => {
+  beforeEach(() => {
+    detectMock.mockReset();
+    getSuggestedServerCommand.mockClear();
+  });
+
+  test('resolves project root via context.projectRoot (legacy path)', async () => {
+    const tool = makeTool();
+    detectMock.mockResolvedValueOnce(happyDetection);
+
+    const result = await tool._handleDetectProject({ projectRoot: '/legacy/path' });
+
+    expect(detectMock).toHaveBeenCalledWith('/legacy/path');
+    expect(result.success).toBe(true);
+    expect(result.projectDir).toBe('/legacy/path');
+  });
+
+  test('resolves project root via context.workingDirectory (alt path)', async () => {
+    const tool = makeTool();
+    detectMock.mockResolvedValueOnce(happyDetection);
+
+    const result = await tool._handleDetectProject({ workingDirectory: '/wd/path' });
+
+    expect(detectMock).toHaveBeenCalledWith('/wd/path');
+    expect(result.success).toBe(true);
+  });
+
+  test('resolves project root via context.projectDir (messageProcessor path)', async () => {
+    // THE REGRESSION GUARD: messageProcessor passes `projectDir`. Before the
+    // fix this returned {success:false, error:"No project directory available"}.
+    const tool = makeTool();
+    detectMock.mockResolvedValueOnce(happyDetection);
+
+    const result = await tool._handleDetectProject({ projectDir: '/mp/path' });
+
+    expect(detectMock).toHaveBeenCalledWith('/mp/path');
+    expect(result.success).toBe(true);
+  });
+
+  test('precedence: projectRoot > workingDirectory > projectDir', async () => {
+    const tool = makeTool();
+    detectMock.mockResolvedValue(happyDetection);
+
+    await tool._handleDetectProject({
+      projectRoot: '/a',
+      workingDirectory: '/b',
+      projectDir: '/c'
+    });
+    expect(detectMock).toHaveBeenLastCalledWith('/a');
+
+    detectMock.mockClear();
+    await tool._handleDetectProject({
+      workingDirectory: '/b',
+      projectDir: '/c'
+    });
+    expect(detectMock).toHaveBeenLastCalledWith('/b');
+
+    detectMock.mockClear();
+    await tool._handleDetectProject({ projectDir: '/c' });
+    expect(detectMock).toHaveBeenLastCalledWith('/c');
+  });
+
+  test('returns error when none of the three context keys is present', async () => {
+    const tool = makeTool();
+    const result = await tool._handleDetectProject({});
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/No project directory available/i);
+    expect(detectMock).not.toHaveBeenCalled();
+  });
+
+  test('surfaces detector errors as returned errors (not thrown)', async () => {
+    const tool = makeTool();
+    detectMock.mockResolvedValueOnce({ error: 'unreadable project' });
+
+    const result = await tool._handleDetectProject({ projectDir: '/x' });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('unreadable project');
+  });
+});

package/src/tools/baseTool.js

@@ -508,7 +508,20 @@ class ToolsRegistry {
   async registerTool(toolClass) {
     try {
       const tool = new toolClass();
-      
+
+      // Propagate the registry's logger to the tool so the tool's own
+      // diagnostic output (`this.logger?.info(...)`, `this.logger?.warn(...)`,
+      // etc.) actually reaches the operator's console. Tools extending
+      // BaseTool default `this.logger = null` unless the class explicitly
+      // passes one to `super()` — and registration never supplied one,
+      // which silently swallowed every `this.logger?.…` call in every tool.
+      // This made debugging things like "why doesn't the visual-editor
+      // tool ever log [VisualEditorTool] lines?" impossible because the
+      // logs literally weren't being emitted.
+      if (this.logger && !tool.logger) {
+        tool.logger = this.logger;
+      }
+
       if (!(tool instanceof BaseTool)) {
         throw new Error(`Tool ${toolClass.name} must extend BaseTool`);
       }