npm - onbuzz - Versions diffs - 3.9.8 → 4.0.0 - Mend

onbuzz 3.9.8 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (955) hide show

package/src/index.js CHANGED Viewed

@@ -654,6 +654,10 @@ class LoxiaApplication {
         this.telegramService.setAgentPool(this.agentPool);
         this.telegramService.setWebSocketManager(webServer);
         if (this.flowExecutor) this.telegramService.setFlowExecutor(this.flowExecutor);
+        // Let the scheduler query bridge-state per agent so it can inject
+        // the <external> routing guidance into system prompts only when the
+        // agent is actually addressable from Telegram.
+        this.agentScheduler?.setTelegramService?.(this.telegramService);
         // Auto-connect if token exists in config (non-blocking)
         this.telegramService.autoConnect().catch(e =>
           this.logger.warn('Telegram auto-connect failed', { error: e.message })
@@ -667,6 +671,10 @@ class LoxiaApplication {
         this.discordService.setAgentPool(this.agentPool);
         this.discordService.setWebSocketManager(webServer);
         if (this.flowExecutor) this.discordService.setFlowExecutor(this.flowExecutor);
+        // Same bridge-awareness hook as Telegram above — the scheduler
+        // only appends <external> guidance when `isAgentBridged(agentId)`
+        // returns true for this channel.
+        this.agentScheduler?.setDiscordService?.(this.discordService);
         // Auto-connect if token exists in config (non-blocking)
         this.discordService.autoConnect().catch(e =>
           this.logger.warn('Discord auto-connect failed', { error: e.message })

package/src/interfaces/webServer.js CHANGED Viewed

@@ -45,6 +45,270 @@ import FlowExecutor from '../core/flowExecutor.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+// Self-contained HTML for the /scheduler debug viewer. No external deps;
+// polls /api/scheduler/state every second and re-renders three sections:
+// header strip, per-agent table, and cycle log. See plan:
+// .claude/plans/snazzy-chasing-canyon.md ("Scheduler visualizer").
+const SCHEDULER_VIEWER_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Scheduler visualizer</title>
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; padding: 12px 16px; background: #0f1115; color: #d6d9de; font: 13px/1.35 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  h1 { font-size: 14px; margin: 0 0 8px; font-weight: 600; letter-spacing: .3px; }
+  h2 { font-size: 12px; margin: 20px 0 6px; color: #8b93a1; text-transform: uppercase; letter-spacing: .5px; font-weight: 600; }
+  .hdr { display: flex; gap: 24px; flex-wrap: wrap; padding: 10px 12px; background: #171a21; border: 1px solid #242832; border-radius: 6px; }
+  .hdr .kv { display: flex; flex-direction: column; }
+  .hdr .k { color: #8b93a1; font-size: 10px; text-transform: uppercase; letter-spacing: .4px; }
+  .hdr .v { font-size: 14px; color: #eaecef; }
+  .hdr .v.ok { color: #41d392; }
+  .hdr .v.bad { color: #ff6b6b; }
+  table { border-collapse: collapse; width: 100%; background: #13161c; border: 1px solid #242832; border-radius: 6px; overflow: hidden; }
+  th, td { padding: 6px 8px; text-align: left; border-bottom: 1px solid #1c1f27; vertical-align: top; white-space: nowrap; }
+  th { font-size: 10px; color: #8b93a1; text-transform: uppercase; letter-spacing: .4px; background: #171a21; position: sticky; top: 0; }
+  tr:last-child td { border-bottom: none; }
+  tr.row-wedged { background: rgba(255, 107, 107, 0.08); }
+  tr.row-hung   { background: rgba(255, 184, 0, 0.08); }
+  tr.row-active { background: rgba(65, 211, 146, 0.05); }
+  .chip { display: inline-block; padding: 1px 7px; border-radius: 10px; font-size: 11px; font-weight: 600; }
+  .chip.ok      { background: #133a27; color: #5fe2a6; }
+  .chip.bad     { background: #3a1313; color: #ff8080; }
+  .chip.warn    { background: #3a2e13; color: #ffc658; }
+  .chip.neutral { background: #242832; color: #b4bac5; }
+  .muted { color: #6c7280; }
+  .mono { font-family: inherit; }
+  .count { display: inline-block; min-width: 18px; text-align: right; color: #b4bac5; }
+  .iconbtn { background: none; border: 1px solid #2a2f3a; color: #b4bac5; padding: 2px 8px; border-radius: 4px; font: inherit; cursor: pointer; margin-left: 8px; }
+  .iconbtn:hover { background: #1c1f27; }
+  .tasks-line { color: #8b93a1; font-size: 11px; white-space: normal; max-width: 480px; }
+  .reason { color: #b4bac5; }
+  .error { color: #ff6b6b; padding: 10px; background: #2a1515; border: 1px solid #5a2525; border-radius: 6px; margin-top: 10px; }
+  .cycle-launched { color: #5fe2a6; }
+  .cycle-idle     { color: #6c7280; }
+  .cycle-locked   { color: #ff8080; }
+  .cycle-cap      { color: #ffc658; }
+  .pill-id { display: inline-block; padding: 0 4px; background: #242832; border-radius: 3px; font-size: 11px; color: #b4bac5; margin-right: 3px; }
+  .wrap { max-width: 1600px; margin: 0 auto; }
+  a, a:visited { color: #6ea8fe; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Scheduler visualizer <span id="paused-note" class="muted" style="font-weight:normal;"></span></h1>
+  <div id="err" class="error" style="display:none"></div>
+  <div id="hdr" class="hdr"></div>
+  <h2>Agents (<span id="agent-count">0</span>)</h2>
+  <div style="overflow-x:auto">
+    <table id="agents">
+      <thead><tr>
+        <th>Name</th><th>Mode</th><th>Status</th>
+        <th>Active?</th><th>Reason</th>
+        <th>Lock</th><th>AI call</th><th>Empties</th>
+        <th>Delay</th><th>Paused</th><th>TTL</th><th>Awaiting input</th>
+        <th>Tasks (p/ip/✓)</th><th>Queues (U/I/T)</th>
+        <th>Model</th>
+      </tr></thead>
+      <tbody></tbody>
+    </table>
+  </div>
+  <h2>
+    Cycle log
+    <button class="iconbtn" id="show-all">Show all 200</button>
+    <button class="iconbtn" id="pause">Pause</button>
+  </h2>
+  <div style="overflow-x:auto">
+    <table id="cycles">
+      <thead><tr>
+        <th>#</th><th>Time</th><th>Outcome</th>
+        <th>Total</th><th>Active</th>
+        <th>In-flight</th><th>Locked-skip</th><th>Cap-skip</th>
+        <th>Launched</th>
+      </tr></thead>
+      <tbody></tbody>
+    </table>
+  </div>
+</div>
+<script>
+(() => {
+  const $ = id => document.getElementById(id);
+  let showAll = false;
+  let paused = false;
+  $('show-all').addEventListener('click', () => {
+    showAll = !showAll;
+    $('show-all').textContent = showAll ? 'Show last 30' : 'Show all 200';
+    render(lastState);
+  });
+  $('pause').addEventListener('click', () => {
+    paused = !paused;
+    $('pause').textContent = paused ? 'Resume' : 'Pause';
+    $('paused-note').textContent = paused ? '(paused)' : '';
+  });
+  const fmtMs = ms => {
+    if (ms == null) return '';
+    if (ms < 1000) return ms + 'ms';
+    if (ms < 60000) return (ms / 1000).toFixed(1) + 's';
+    if (ms < 3600000) return Math.floor(ms / 60000) + 'm ' + Math.floor((ms % 60000) / 1000) + 's';
+    return Math.floor(ms / 3600000) + 'h ' + Math.floor((ms % 3600000) / 60000) + 'm';
+  };
+  const fmtTime = iso => iso ? new Date(iso).toLocaleTimeString('en-US', { hour12: false }) : '';
+  const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  function chipActive(a) {
+    if (a.activity?.active) return '<span class="chip ok">yes</span>';
+    return '<span class="chip bad">no</span>';
+  }
+  function chipLock(a) {
+    if (!a.lockHeld) return '<span class="muted">—</span>';
+    const ms = a.lockHeldMs ?? 0;
+    const cls = ms > 60000 ? 'bad' : ms > 5000 ? 'warn' : 'neutral';
+    return '<span class="chip ' + cls + '">held ' + fmtMs(ms) + '</span>';
+  }
+  function chipAI(a) {
+    const r = a.activeAIRequest;
+    if (!r) return '<span class="muted">—</span>';
+    const ms = r.durationMs ?? 0;
+    const cls = ms > 60000 ? 'bad' : ms > 10000 ? 'warn' : 'neutral';
+    return '<span class="chip ' + cls + '">' + esc(r.type || 'req') + ' ' + fmtMs(ms) + '</span>';
+  }
+  function chipEmpty(a) {
+    const e = a.emptyResponse;
+    if (!e || !e.count) return '<span class="muted">—</span>';
+    const elapsedMs = Date.now() - new Date(e.firstAt).getTime();
+    const cls = e.count >= 5 ? 'bad' : e.count >= 3 ? 'warn' : 'neutral';
+    return '<span class="chip ' + cls + '" title="first at ' + esc(new Date(e.firstAt).toISOString()) + '">' + e.count + 'x / ' + fmtMs(elapsedMs) + '</span>';
+  }
+  function chipDelay(a) {
+    if (!a.delayEndTime) return '<span class="muted">—</span>';
+    const end = new Date(a.delayEndTime).getTime();
+    const ms = end - Date.now();
+    if (ms <= 0) return '<span class="muted" title="' + esc(a.delayEndTime) + '">expired</span>';
+    return '<span class="chip warn" title="' + esc(a.delayEndTime) + '">' + fmtMs(ms) + '</span>';
+  }
+  function rowClass(a) {
+    if (a.lockHeld && (a.lockHeldMs ?? 0) > 60000) return 'row-wedged';
+    const aiMs = a.activeAIRequest?.durationMs ?? 0;
+    if (aiMs > 60000) return 'row-hung';
+    if ((a.emptyResponse?.count ?? 0) >= 3) return 'row-hung'; // amber — stall forming
+    if (a.activity?.active && !a.lockHeld) return 'row-active';
+    return '';
+  }
+  function renderAgents(agents) {
+    $('agent-count').textContent = agents.length;
+    const tbody = document.querySelector('#agents tbody');
+    // Sort: locked-wedged first, then active, then everything else. Stable for same class.
+    const score = a => (a.lockHeld && (a.lockHeldMs ?? 0) > 60000) ? 0
+                     : (a.activeAIRequest?.durationMs ?? 0) > 60000 ? 1
+                     : a.activity?.active ? 2
+                     : 3;
+    const sorted = agents.slice().sort((x, y) => score(x) - score(y));
+    tbody.innerHTML = sorted.map(a => {
+      const q = a.queues || {};
+      const t = a.tasks || {};
+      return '<tr class="' + rowClass(a) + '">' +
+        '<td title="' + esc(a.id) + '">' + esc(a.name || a.id) + '</td>' +
+        '<td>' + esc(a.mode || '') + '</td>' +
+        '<td>' + esc(a.status || '') + '</td>' +
+        '<td>' + chipActive(a) + '</td>' +
+        '<td class="reason" title="' + esc(a.activity?.details || '') + '">' + esc(a.activity?.reason || '') + '</td>' +
+        '<td>' + chipLock(a) + '</td>' +
+        '<td>' + chipAI(a) + '</td>' +
+        '<td>' + chipEmpty(a) + '</td>' +
+        '<td>' + chipDelay(a) + '</td>' +
+        '<td>' + (a.pausedUntil ? '<span class="chip warn">paused</span>' : '<span class="muted">—</span>') + '</td>' +
+        '<td>' + (a.ttl != null ? '<span class="chip warn">' + esc(a.ttl) + '</span>' : '<span class="muted">—</span>') + '</td>' +
+        '<td>' + (a.awaitingUserInput ? '<span class="chip warn">' + esc(a.awaitingUserInput.type || 'yes') + '</span>' : '<span class="muted">—</span>') + '</td>' +
+        '<td><span class="count">' + (t.pending||0) + '</span>/<span class="count">' + (t.inProgress||0) + '</span>/<span class="count muted">' + (t.completed||0) + '</span>' +
+          (t.nextPending ? '<div class="tasks-line">next: ' + esc(t.nextPending) + '</div>' : '') + '</td>' +
+        '<td>' + (q.userMessages||0) + '/' + (q.interAgentMessages||0) + '/' + (q.toolResults||0) + '</td>' +
+        '<td class="muted">' + esc(a.currentModel || '—') + '</td>' +
+        '</tr>';
+    }).join('');
+  }
+  function renderCycles(cycles) {
+    const tbody = document.querySelector('#cycles tbody');
+    // Newest first
+    const reversed = cycles.slice().reverse();
+    const limited = showAll ? reversed : reversed.slice(0, 30);
+    tbody.innerHTML = limited.map(c => {
+      const outcomeClass = 'cycle-' + (c.outcome === 'launched' ? 'launched'
+                          : c.outcome === 'idle' ? 'idle'
+                          : c.outcome === 'all-locked' ? 'locked'
+                          : c.outcome === 'concurrency-cap' ? 'cap'
+                          : 'idle');
+      const launched = (c.launched || []).map(id => '<span class="pill-id" title="' + esc(id) + '">' + esc(id.slice(-8)) + '</span>').join('') || '<span class="muted">—</span>';
+      const locked = (c.skippedLocked || []).map(id => '<span class="pill-id" title="' + esc(id) + '">' + esc(id.slice(-8)) + '</span>').join('') || '<span class="muted">—</span>';
+      const cap = (c.skippedConcurrency || []).map(id => '<span class="pill-id" title="' + esc(id) + '">' + esc(id.slice(-8)) + '</span>').join('') || '<span class="muted">—</span>';
+      return '<tr>' +
+        '<td class="muted">' + c.n + '</td>' +
+        '<td>' + fmtTime(c.at) + '</td>' +
+        '<td class="' + outcomeClass + '">' + esc(c.outcome || '') + '</td>' +
+        '<td>' + (c.totalAgents || 0) + '</td>' +
+        '<td>' + (c.activeCount || 0) + '</td>' +
+        '<td>' + (c.inFlightAtStart || 0) + '</td>' +
+        '<td>' + locked + '</td>' +
+        '<td>' + cap + '</td>' +
+        '<td>' + launched + '</td>' +
+        '</tr>';
+    }).join('');
+  }
+  function renderHeader(s) {
+    const hdr = $('hdr');
+    const inflight = s.scheduler.currentlyInFlight;
+    const cap = s.scheduler.maxConcurrent;
+    hdr.innerHTML =
+      '<div class="kv"><div class="k">Server</div><div class="v">' + fmtTime(s.serverTime) + '</div></div>' +
+      '<div class="kv"><div class="k">Scheduler</div><div class="v ' + (s.scheduler.running ? 'ok' : 'bad') + '">' + (s.scheduler.running ? 'running' : 'stopped') + '</div></div>' +
+      '<div class="kv"><div class="k">Tick</div><div class="v">' + s.scheduler.iterationDelayMs + 'ms</div></div>' +
+      '<div class="kv"><div class="k">Cycles</div><div class="v">' + s.scheduler.cycleCount + '</div></div>' +
+      '<div class="kv"><div class="k">In-flight</div><div class="v ' + (inflight >= cap ? 'bad' : '') + '">' + inflight + ' / ' + cap + '</div></div>' +
+      '<div class="kv"><div class="k">Agents</div><div class="v">' + s.agents.length + '</div></div>';
+  }
+  let lastState = null;
+  function render(s) {
+    if (!s) return;
+    lastState = s;
+    renderHeader(s);
+    renderAgents(s.agents);
+    renderCycles(s.cycles);
+  }
+  async function tick() {
+    if (paused) return;
+    try {
+      const res = await fetch('/api/scheduler/state', { cache: 'no-store' });
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+      const data = await res.json();
+      $('err').style.display = 'none';
+      render(data);
+    } catch (err) {
+      $('err').style.display = 'block';
+      $('err').textContent = 'Failed to fetch scheduler state: ' + err.message;
+    }
+  }
+  tick();
+  setInterval(tick, 1000);
+})();
+</script>
+</body>
+</html>`;
 class WebServer {
   constructor(orchestrator, logger, config = {}) {
     this.orchestrator = orchestrator;
@@ -2901,6 +3165,30 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
+    // ============================================
+    // Scheduler Visualizer — JSON state endpoint + HTML viewer
+    // ============================================
+    // JSON snapshot of scheduler + all agents — polled by /scheduler at 1 Hz.
+    this.app.get('/api/scheduler/state', async (req, res) => {
+      try {
+        const sched = this.orchestrator?.agentPool?.scheduler;
+        if (!sched?.getState) {
+          return res.status(503).json({ error: 'scheduler is not attached' });
+        }
+        const state = await sched.getState();
+        res.json(state);
+      } catch (err) {
+        this.logger.error('Failed to build scheduler state', { error: err.message });
+        res.status(500).json({ error: err.message });
+      }
+    });
+    // Self-contained HTML viewer. See SCHEDULER_VIEWER_HTML below.
+    this.app.get('/scheduler', (req, res) => {
+      res.type('html').send(SCHEDULER_VIEWER_HTML);
+    });
     // ============================================
     // Artifacts API Endpoint
     // ============================================

package/src/services/__tests__/channelFilter.test.js ADDED Viewed

@@ -0,0 +1,264 @@
+/**
+ * Unit tests for channelFilter.js
+ *
+ * Exercises the pure-function surface: parsing `<external>` blocks out of
+ * raw agent content, resolving block targets against a set of owned
+ * aliases, and generating the system-prompt guidance paragraph.
+ *
+ * The filter is API-path agnostic (runs on post-bridge content equivalent
+ * for both Responses API and Chat Completions), so nothing here mocks
+ * model providers — we only feed it representative content shapes.
+ */
+import { describe, test, expect } from '@jest/globals';
+import {
+  filterContentForExternalRelay,
+  resolveBlockTargets,
+  getExternalChannelPromptGuidance,
+} from '../channelFilter.js';
+// ───────────────────────── filterContentForExternalRelay ─────────────────────────
+describe('filterContentForExternalRelay()', () => {
+  test('no <external> tags → empty blocks (nothing relayed)', () => {
+    expect(filterContentForExternalRelay('plain text only').blocks).toEqual([]);
+    expect(filterContentForExternalRelay('').blocks).toEqual([]);
+    expect(filterContentForExternalRelay(null).blocks).toEqual([]);
+    expect(filterContentForExternalRelay(undefined).blocks).toEqual([]);
+  });
+  test('single default-routed block (no to=) → to: null', () => {
+    const { blocks } = filterContentForExternalRelay('<external>hello</external>');
+    expect(blocks).toEqual([{ to: null, text: 'hello' }]);
+  });
+  test('block with single alias in to=', () => {
+    const { blocks } = filterContentForExternalRelay(
+      '<external to="discord:#ops">only ops</external>'
+    );
+    expect(blocks).toEqual([{ to: ['discord:#ops'], text: 'only ops' }]);
+  });
+  test('block with multiple aliases (comma-separated, spaces tolerated)', () => {
+    const { blocks } = filterContentForExternalRelay(
+      '<external to="discord:#ops, telegram, discord:#general">multi</external>'
+    );
+    expect(blocks).toEqual([
+      { to: ['discord:#ops', 'telegram', 'discord:#general'], text: 'multi' },
+    ]);
+  });
+  test('to="*" preserved as explicit broadcast marker', () => {
+    const { blocks } = filterContentForExternalRelay('<external to="*">yo</external>');
+    expect(blocks).toEqual([{ to: ['*'], text: 'yo' }]);
+  });
+  test('empty to= is treated as default (null)', () => {
+    expect(filterContentForExternalRelay('<external to="">yo</external>').blocks)
+      .toEqual([{ to: null, text: 'yo' }]);
+    expect(filterContentForExternalRelay('<external to="   ">yo</external>').blocks)
+      .toEqual([{ to: null, text: 'yo' }]);
+  });
+  test('single and double quotes both accepted for to=', () => {
+    expect(filterContentForExternalRelay(`<external to='telegram'>x</external>`).blocks)
+      .toEqual([{ to: ['telegram'], text: 'x' }]);
+    expect(filterContentForExternalRelay(`<external to="telegram">x</external>`).blocks)
+      .toEqual([{ to: ['telegram'], text: 'x' }]);
+  });
+  test('case-insensitive tag matching (both opening and closing)', () => {
+    expect(filterContentForExternalRelay('<EXTERNAL>hi</EXTERNAL>').blocks)
+      .toEqual([{ to: null, text: 'hi' }]);
+    expect(filterContentForExternalRelay('<External To="telegram">hi</External>').blocks)
+      .toEqual([{ to: ['telegram'], text: 'hi' }]);
+  });
+  test('multiple blocks parsed in document order', () => {
+    const { blocks } = filterContentForExternalRelay(
+      '<external>A</external>middle<external to="x">B</external>tail<external>C</external>'
+    );
+    expect(blocks).toEqual([
+      { to: null, text: 'A' },
+      { to: ['x'], text: 'B' },
+      { to: null, text: 'C' },
+    ]);
+  });
+  test('content outside <external> is never captured', () => {
+    const content = 'private planning\n<external>public</external>\nmore private';
+    expect(filterContentForExternalRelay(content).blocks)
+      .toEqual([{ to: null, text: 'public' }]);
+  });
+  test('CONTENT VERBATIM — code blocks preserved inside <external>', () => {
+    const content = '<external>```js\nconst x = 1;\n```</external>';
+    expect(filterContentForExternalRelay(content).blocks).toEqual([
+      { to: null, text: '```js\nconst x = 1;\n```' },
+    ]);
+  });
+  test('CONTENT VERBATIM — tool-call JSON blocks preserved inside <external>', () => {
+    // Critical: the filter must NOT strip tool JSON just because it looks
+    // like internal bookkeeping. If the agent put it inside <external>,
+    // the agent wants it published (e.g., a task summary).
+    const tool = '```json\n{"toolId":"taskmanager","parameters":{}}\n```';
+    const { blocks } = filterContentForExternalRelay(`<external>${tool}</external>`);
+    expect(blocks[0].text).toBe(tool);
+  });
+  test('CONTENT VERBATIM — "Calling X" bridge preamble preserved if wrapped', () => {
+    const txt = '**Calling terminal** — cmd: ls…\n\nsee below';
+    const { blocks } = filterContentForExternalRelay(`<external>${txt}</external>`);
+    expect(blocks[0].text).toBe(txt);
+  });
+  test('empty or whitespace-only block is dropped', () => {
+    expect(filterContentForExternalRelay('<external></external>').blocks).toEqual([]);
+    expect(filterContentForExternalRelay('<external>   \n\n</external>').blocks).toEqual([]);
+  });
+  test('leading/trailing whitespace in block body is trimmed', () => {
+    const { blocks } = filterContentForExternalRelay('<external>\n\n  hi \n\n</external>');
+    expect(blocks).toEqual([{ to: null, text: 'hi' }]);
+  });
+  test('unclosed <external> tag is ignored (no runaway capture)', () => {
+    // Non-greedy regex stops at first </external> it finds; an unclosed
+    // opener produces no blocks rather than swallowing the rest of the turn.
+    expect(filterContentForExternalRelay('<external>open forever').blocks).toEqual([]);
+  });
+  test('mixed API-path content: prose + bridge preamble + tool JSON + <external> reply', () => {
+    // Representative of what `stream_complete` carries on either API path
+    // after the bridge has converted native tool calls to inline blocks.
+    const content =
+      "Thinking through this…\n\n" +
+      "**Calling taskmanager** — type: create, title: foo…\n\n" +
+      "```json\n{\"toolId\":\"taskmanager\",\"parameters\":{\"actions\":[{\"type\":\"create\",\"title\":\"foo\"}]}}\n```\n\n" +
+      "<external to=\"discord:#ops\">\n" +
+      "Created a task for you: **foo**. I'll post back when it's done.\n" +
+      "</external>\n\n" +
+      "<external to=\"telegram\">Done ✅</external>";
+    const { blocks } = filterContentForExternalRelay(content);
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toEqual({
+      to: ['discord:#ops'],
+      text: "Created a task for you: **foo**. I'll post back when it's done.",
+    });
+    expect(blocks[1]).toEqual({ to: ['telegram'], text: 'Done ✅' });
+  });
+});
+// ────────────────────────────── resolveBlockTargets ──────────────────────────────
+describe('resolveBlockTargets()', () => {
+  const owned = ['discord:#ops', 'discord:#general', 'telegram'];
+  test('no owned aliases → always empty', () => {
+    expect(resolveBlockTargets({ to: null }, [])).toEqual([]);
+    expect(resolveBlockTargets({ to: ['*'] }, [])).toEqual([]);
+    expect(resolveBlockTargets({ to: ['telegram'] }, [])).toEqual([]);
+  });
+  test('to=null → broadcast to every owned alias', () => {
+    expect(resolveBlockTargets({ to: null }, owned).sort()).toEqual([...owned].sort());
+  });
+  test('to=["*"] → broadcast to every owned alias (same as null)', () => {
+    expect(resolveBlockTargets({ to: ['*'] }, owned).sort()).toEqual([...owned].sort());
+  });
+  test('exact alias match (case-insensitive)', () => {
+    expect(resolveBlockTargets({ to: ['telegram'] }, owned)).toEqual(['telegram']);
+    expect(resolveBlockTargets({ to: ['TELEGRAM'] }, owned)).toEqual(['telegram']);
+    expect(resolveBlockTargets({ to: ['Discord:#Ops'] }, owned)).toEqual(['discord:#ops']);
+  });
+  test('substring match (short form → canonical alias)', () => {
+    // Agent wrote `#ops` — matches owned `discord:#ops`.
+    expect(resolveBlockTargets({ to: ['#ops'] }, owned)).toEqual(['discord:#ops']);
+    // Agent wrote `ops` — also matches.
+    expect(resolveBlockTargets({ to: ['ops'] }, owned)).toEqual(['discord:#ops']);
+  });
+  test('multiple targets in to= resolve additively', () => {
+    const r = resolveBlockTargets({ to: ['#ops', 'telegram'] }, owned).sort();
+    expect(r).toEqual(['discord:#ops', 'telegram'].sort());
+  });
+  test('unknown alias → empty match (block silently skipped by caller)', () => {
+    expect(resolveBlockTargets({ to: ['slack:#ops'] }, owned)).toEqual([]);
+    expect(resolveBlockTargets({ to: ['nonexistent'] }, owned)).toEqual([]);
+  });
+  test('duplicate matches are deduped', () => {
+    // Substring matching could theoretically match the same owned alias
+    // twice — ensure the return value is a set.
+    expect(resolveBlockTargets({ to: ['ops', '#ops', 'discord:#ops'] }, owned))
+      .toEqual(['discord:#ops']);
+  });
+});
+// ─────────────────────── getExternalChannelPromptGuidance ────────────────────────
+describe('getExternalChannelPromptGuidance()', () => {
+  test('empty channel list → empty string (no prompt pollution)', () => {
+    expect(getExternalChannelPromptGuidance([])).toBe('');
+    expect(getExternalChannelPromptGuidance(null)).toBe('');
+    expect(getExternalChannelPromptGuidance(undefined)).toBe('');
+  });
+  test('single channel → guidance includes alias and label', () => {
+    const out = getExternalChannelPromptGuidance([
+      { alias: 'telegram', label: 'Telegram chat' },
+    ]);
+    expect(out).toContain('OUTPUT ROUTING');
+    expect(out).toContain('`telegram`');
+    expect(out).toContain('Telegram chat');
+    expect(out).toContain('<external>');
+    expect(out).toContain('<external to="alias">');
+  });
+  test('multiple channels listed in given order', () => {
+    const out = getExternalChannelPromptGuidance([
+      { alias: 'discord:#ops', label: 'Discord channel #ops in Acme' },
+      { alias: 'discord:#general', label: 'Discord channel #general in Acme' },
+      { alias: 'telegram', label: 'Telegram chat' },
+    ]);
+    const opsIdx = out.indexOf('`discord:#ops`');
+    const genIdx = out.indexOf('`discord:#general`');
+    const telIdx = out.indexOf('`telegram`');
+    expect(opsIdx).toBeGreaterThan(-1);
+    expect(genIdx).toBeGreaterThan(opsIdx);
+    expect(telIdx).toBeGreaterThan(genIdx);
+  });
+  test('documents the addressing matrix (default / specific / multi / broadcast)', () => {
+    const out = getExternalChannelPromptGuidance([{ alias: 'telegram', label: 't' }]);
+    expect(out).toContain('broadcast to every bridged channel');
+    expect(out).toContain('<external to="alias">');
+    expect(out).toContain('<external to="aliasA,aliasB">');
+    expect(out).toContain('<external to="*">');
+  });
+  test('explicitly states that default (no <external>) means local-only', () => {
+    const out = getExternalChannelPromptGuidance([{ alias: 'telegram', label: 't' }]);
+    expect(out).toMatch(/stays local|never forwarded|NOTHING you write is forwarded/i);
+  });
+  test('channel entry without a label still renders alias', () => {
+    const out = getExternalChannelPromptGuidance([{ alias: 'telegram' }]);
+    expect(out).toContain('`telegram`');
+  });
+  test('ignores entries with missing / empty aliases', () => {
+    const out = getExternalChannelPromptGuidance([
+      { alias: '', label: 'dropped' },
+      { alias: '   ', label: 'dropped' },
+      { alias: 'telegram', label: 'kept' },
+    ]);
+    expect(out).toContain('`telegram`');
+    expect(out).not.toContain('dropped');
+  });
+});