onbuzz 4.0.1 → 4.1.0

package/src/services/__tests__/messageSource.channelFilter.coherence.test.js

@@ -0,0 +1,101 @@
+/**
+ * Cross-module coherence: the aliases emitted by messageSource factories
+ * must compose correctly with channelFilter.resolveBlockTargets.
+ *
+ * This is the single test that catches "we renamed the alias format on one
+ * side of the fence and forgot the other side" — the exact kind of quiet
+ * drift that turns source-awareness back into a ghost feature.
+ *
+ * The agent's contract is:
+ *   1. Read an attribution header like "(Message by alice from Discord > G > #ops)".
+ *   2. Look up the corresponding alias in the bridged-channels list it was given.
+ *   3. Write <external to="<alias>">…</external>.
+ *   4. The relay resolves that back to the concrete channel and sends the reply.
+ *
+ * Step 2 resolves to messageSource's alias output. Step 4 resolves through
+ * channelFilter.resolveBlockTargets. These tests assert the two agree.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  createDiscordSource,
+  createTelegramSource,
+} from '../messageSource.js';
+import { resolveBlockTargets } from '../channelFilter.js';
+
+describe('messageSource ↔ channelFilter alias coherence', () => {
+  test('Discord guild alias resolves when the agent addresses it verbatim', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      guild: { name: 'MyGuild' },
+      channel: { id: 'c1', name: 'ops', isThread: () => false },
+    });
+
+    // The relay advertises bridged aliases in the same shape messageSource
+    // produces (both use `discord:#<name>`). Lock it in.
+    const ownedAliases = [src.alias];
+    const block = { to: [src.alias], text: 'reply' };
+
+    expect(resolveBlockTargets(block, ownedAliases)).toEqual([src.alias]);
+  });
+
+  test('agent can use shorthand (#ops) and it still resolves via substring match', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      guild: { name: 'MyGuild' },
+      channel: { id: 'c1', name: 'ops', isThread: () => false },
+    });
+    // Agent sees "#ops" in the header path, writes a short `to="#ops"`.
+    // channelFilter's substring match should still find the canonical alias.
+    const block = { to: ['#ops'], text: 'reply' };
+    expect(resolveBlockTargets(block, [src.alias])).toEqual([src.alias]);
+  });
+
+  test('guild-prefixed owned alias matches when agent addresses via channel shorthand', () => {
+    // The relay may advertise a guild-qualified alias (`discord:guild-123:#ops`)
+    // while the agent, reading the header path "Discord > MyGuild > #ops",
+    // writes the natural short form `to="#ops"`. channelFilter's endsWith
+    // path is what makes this pair compose — this locks that in.
+    const ownedAliases = ['discord:guild-123:#ops'];
+    const block = { to: ['#ops'], text: 'reply' };
+    expect(resolveBlockTargets(block, ownedAliases)).toEqual(ownedAliases);
+  });
+
+  test('Telegram per-chat alias routes when owned alias set advertises it', () => {
+    const src = createTelegramSource({
+      message_id: 1,
+      chat: { id: 999, type: 'supergroup', title: 'Ops' },
+      from: { username: 'alice' },
+    });
+    const ownedAliases = [src.alias, 'telegram'];
+    const block = { to: [src.alias], text: 'reply' };
+    expect(resolveBlockTargets(block, ownedAliases)).toContain(src.alias);
+  });
+
+  test('Telegram per-chat source alias DOES NOT wildcard-match bare owned "telegram"', () => {
+    // Regression guard on a tempting mistake. channelFilter matches "owned
+    // contains wanted", not the reverse. If the relay owns only 'telegram',
+    // an agent addressing `to="telegram:chat-999"` will NOT be routed there
+    // — by design. The agent is expected to use the alias advertised in its
+    // bridged-channel list (the system-prompt contract), not to invent
+    // narrower aliases from the header. Locking this in prevents accidental
+    // bidirectional-substring loosening of channelFilter later.
+    const src = createTelegramSource({
+      message_id: 1,
+      chat: { id: 999, type: 'supergroup', title: 'Ops' },
+      from: { username: 'alice' },
+    });
+    const ownedAliases = ['telegram'];
+    const block = { to: [src.alias], text: 'reply' };
+    expect(resolveBlockTargets(block, ownedAliases)).toEqual([]);
+  });
+
+  test('default block (no to=) still broadcasts to every owned alias', () => {
+    // Regression guard: adding source-awareness must not change the meaning
+    // of an unaddressed <external> block. It remains "broadcast to every
+    // bridged channel," exactly as before.
+    const block = { to: null, text: 'broadcast' };
+    const owned = ['discord:#ops', 'telegram'];
+    expect(resolveBlockTargets(block, owned).sort()).toEqual(owned.sort());
+  });
+});

package/src/services/__tests__/messageSource.test.js

@@ -0,0 +1,376 @@
+/**
+ * Tests for messageSource — the pure provenance module.
+ *
+ * Scope: exhaustive factory + describeSource coverage. These are the
+ * contract tests for the shape that every other piece of the
+ * source-awareness feature relies on, so the surface is probed widely:
+ * happy paths, every DM / group / thread variant, missing-field
+ * degradation, frozen-object invariants, and idempotency of the header
+ * prepender.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  MESSAGE_SOURCE_KINDS,
+  createDiscordSource,
+  createTelegramSource,
+  createWebSource,
+  createInternalSource,
+  describeSource,
+  formatSourceHeader,
+  prependSourceHeader,
+} from '../messageSource.js';
+
+// ────────────────────────────────────────────────────────────────────────
+// Discord factory
+// ────────────────────────────────────────────────────────────────────────
+
+describe('createDiscordSource', () => {
+  test('guild channel message produces full canonical alias + raw payload', () => {
+    const dm = {
+      id: 'msg-1',
+      author: { id: 'user-1', username: 'alice' },
+      guild: { id: 'g-1', name: 'MyGuild' },
+      channel: {
+        id: 'c-1',
+        name: 'ops',
+        isThread: () => false,
+      },
+    };
+
+    const src = createDiscordSource(dm);
+
+    expect(src.kind).toBe('discord');
+    expect(src.alias).toBe('discord:#ops');
+    expect(src.sessionId).toBe('discord-g-1-c-1');
+    expect(src.raw).toEqual({
+      messageId: 'msg-1',
+      channelId: 'c-1',
+      channelName: 'ops',
+      authorId: 'user-1',
+      authorName: 'alice',
+      guildId: 'g-1',
+      guildName: 'MyGuild',
+      threadId: null,
+      threadName: null,
+      parentChannelId: null,
+      parentChannelName: null,
+    });
+  });
+
+  test('thread message captures thread AND parent channel metadata', () => {
+    const dm = {
+      id: 'msg-2',
+      author: { id: 'user-1', username: 'alice' },
+      guild: { id: 'g-1', name: 'MyGuild' },
+      channel: {
+        id: 't-1',
+        name: 'deploy-thread',
+        parentId: 'c-1',
+        parent: { name: 'ops' },
+        isThread: () => true,
+      },
+    };
+
+    const src = createDiscordSource(dm);
+
+    expect(src.alias).toBe('discord:#deploy-thread');
+    expect(src.raw.threadId).toBe('t-1');
+    expect(src.raw.threadName).toBe('deploy-thread');
+    expect(src.raw.parentChannelId).toBe('c-1');
+    expect(src.raw.parentChannelName).toBe('ops');
+  });
+
+  test('DM (no guild) produces alias from channel id when no name', () => {
+    const dm = {
+      id: 'msg-3',
+      author: { id: 'user-1', username: 'alice' },
+      channel: { id: 'dm-channel-99', isThread: () => false },
+      // no guild
+    };
+
+    const src = createDiscordSource(dm);
+    expect(src.alias).toBe('discord:dm-channel-99');
+    expect(src.raw.guildId).toBeNull();
+    expect(src.raw.guildName).toBeNull();
+    expect(src.sessionId).toBe('discord-dm-dm-channel-99');
+  });
+
+  test('prefers author.username, falls back to globalName', () => {
+    const dm = {
+      id: 'm',
+      author: { id: 'u', globalName: 'AliceDisplay' },
+      channel: { id: 'c', name: 'general', isThread: () => false },
+    };
+    expect(createDiscordSource(dm).raw.authorName).toBe('AliceDisplay');
+  });
+
+  test('missing channel.isThread method is treated as not-a-thread', () => {
+    const dm = {
+      id: 'm',
+      author: { id: 'u', username: 'alice' },
+      channel: { id: 'c', name: 'general' },  // no isThread
+    };
+    const src = createDiscordSource(dm);
+    expect(src.raw.threadId).toBeNull();
+    expect(src.raw.parentChannelId).toBeNull();
+  });
+
+  test('completely empty input produces an alias-of-last-resort, does not throw', () => {
+    const src = createDiscordSource({});
+    expect(src.kind).toBe('discord');
+    expect(src.alias).toBe('discord:unknown');
+    expect(src.raw.messageId).toBeNull();
+    expect(src.raw.authorName).toBeNull();
+  });
+
+  test('null / undefined input does not throw and returns a discord-kind source', () => {
+    expect(() => createDiscordSource(null)).not.toThrow();
+    expect(() => createDiscordSource(undefined)).not.toThrow();
+    expect(createDiscordSource(null).kind).toBe('discord');
+  });
+
+  test('output is deeply frozen', () => {
+    const src = createDiscordSource({
+      id: 'm', author: { username: 'a' },
+      channel: { id: 'c', name: 'n', isThread: () => false },
+      guild: { id: 'g', name: 'G' },
+    });
+    expect(Object.isFrozen(src)).toBe(true);
+    expect(Object.isFrozen(src.raw)).toBe(true);
+    // Attempt to mutate silently fails in non-strict mode, throws in strict.
+    // Either way the value stays put.
+    try { src.raw.channelName = 'hacked'; } catch {}
+    expect(src.raw.channelName).toBe('n');
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Telegram factory
+// ────────────────────────────────────────────────────────────────────────
+
+describe('createTelegramSource', () => {
+  test('group chat captures title + user name, alias is per-chat', () => {
+    const msg = {
+      message_id: 42,
+      chat: { id: -100123, type: 'supergroup', title: 'Ops Chat' },
+      from: { id: 7, username: 'alice' },
+    };
+    const src = createTelegramSource(msg);
+    expect(src.kind).toBe('telegram');
+    expect(src.alias).toBe('telegram:chat--100123');
+    expect(src.raw.chatTitle).toBe('Ops Chat');
+    expect(src.raw.userName).toBe('alice');
+    expect(src.sessionId).toBe('telegram--100123');
+  });
+
+  test('private chat uses from.first_name when no username', () => {
+    const msg = {
+      message_id: 1,
+      chat: { id: 99, type: 'private' },
+      from: { id: 7, first_name: 'Alice' },
+    };
+    const src = createTelegramSource(msg);
+    expect(src.raw.userName).toBe('Alice');
+    expect(src.raw.chatType).toBe('private');
+  });
+
+  test('missing chat id falls back to bare telegram alias', () => {
+    const src = createTelegramSource({ from: { username: 'a' } });
+    expect(src.alias).toBe('telegram');
+  });
+
+  test('output is deeply frozen', () => {
+    const src = createTelegramSource({
+      message_id: 1, chat: { id: 1, type: 'private' }, from: { username: 'u' },
+    });
+    expect(Object.isFrozen(src)).toBe(true);
+    expect(Object.isFrozen(src.raw)).toBe(true);
+  });
+
+  test('null input does not throw', () => {
+    expect(() => createTelegramSource(null)).not.toThrow();
+    expect(createTelegramSource(null).kind).toBe('telegram');
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Web / Internal factories
+// ────────────────────────────────────────────────────────────────────────
+
+describe('createWebSource / createInternalSource', () => {
+  test('web source carries sessionId through', () => {
+    const src = createWebSource({ sessionId: 'web-session-abc', userName: 'op' });
+    expect(src.kind).toBe('web');
+    expect(src.alias).toBe('web:web-session-abc');
+    expect(src.sessionId).toBe('web-session-abc');
+  });
+
+  test('web source tolerates missing info', () => {
+    const src = createWebSource();
+    expect(src.sessionId).toBe('web-unknown');
+  });
+
+  test('internal source is frozen and has a traceable reason', () => {
+    const src = createInternalSource('scheduler-tick');
+    expect(src.kind).toBe('internal');
+    expect(src.raw.reason).toBe('scheduler-tick');
+    expect(Object.isFrozen(src)).toBe(true);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// describeSource
+// ────────────────────────────────────────────────────────────────────────
+
+describe('describeSource', () => {
+  test('Discord guild channel', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      guild: { name: 'MyGuild' },
+      channel: { id: 'c', name: 'ops', isThread: () => false },
+    });
+    expect(describeSource(src)).toBe('Message by alice from Discord > MyGuild > #ops');
+  });
+
+  test('Discord thread shows parent + thread name', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      guild: { name: 'MyGuild' },
+      channel: {
+        id: 't', name: 'deploy-thread',
+        parentId: 'c', parent: { name: 'ops' },
+        isThread: () => true,
+      },
+    });
+    expect(describeSource(src)).toBe(
+      'Message by alice from Discord > MyGuild > #ops > deploy-thread'
+    );
+  });
+
+  test('Discord DM — no guild, no channel name', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      channel: { id: 'dm-99', isThread: () => false },
+    });
+    expect(describeSource(src)).toBe('Message by alice from Discord > DM');
+  });
+
+  test('Discord unknown user falls back gracefully', () => {
+    const src = createDiscordSource({
+      channel: { id: 'c', name: 'general', isThread: () => false },
+    });
+    expect(describeSource(src)).toBe('Message by unknown user from Discord > #general');
+  });
+
+  test('Telegram group chat', () => {
+    const src = createTelegramSource({
+      chat: { id: -100, type: 'supergroup', title: 'Ops Chat' },
+      from: { username: 'alice' },
+    });
+    expect(describeSource(src)).toBe('Message by alice from Telegram > Ops Chat');
+  });
+
+  test('Telegram private chat', () => {
+    const src = createTelegramSource({
+      chat: { id: 1, type: 'private' },
+      from: { username: 'alice' },
+    });
+    expect(describeSource(src)).toBe('Message by alice from Telegram > DM');
+  });
+
+  test('Telegram group with no title falls back to chat id', () => {
+    const src = createTelegramSource({
+      chat: { id: 777, type: 'group' },
+      from: { username: 'alice' },
+    });
+    expect(describeSource(src)).toBe('Message by alice from Telegram > chat 777');
+  });
+
+  test('returns null for web / api / internal kinds', () => {
+    expect(describeSource(createWebSource({ sessionId: 'x' }))).toBeNull();
+    expect(describeSource(createInternalSource('tick'))).toBeNull();
+  });
+
+  test('returns null for null / undefined / non-object', () => {
+    expect(describeSource(null)).toBeNull();
+    expect(describeSource(undefined)).toBeNull();
+    expect(describeSource('not-a-source')).toBeNull();
+    expect(describeSource(42)).toBeNull();
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// formatSourceHeader / prependSourceHeader (idempotency)
+// ────────────────────────────────────────────────────────────────────────
+
+describe('formatSourceHeader', () => {
+  test('wraps describeSource output in parentheses', () => {
+    const src = createDiscordSource({
+      author: { username: 'alice' },
+      guild: { name: 'G' },
+      channel: { id: 'c', name: 'ops', isThread: () => false },
+    });
+    expect(formatSourceHeader(src)).toBe('(Message by alice from Discord > G > #ops)');
+  });
+
+  test('returns empty string for no-header sources', () => {
+    expect(formatSourceHeader(null)).toBe('');
+    expect(formatSourceHeader(createInternalSource())).toBe('');
+    expect(formatSourceHeader(createWebSource({ sessionId: 's' }))).toBe('');
+  });
+});
+
+describe('prependSourceHeader', () => {
+  const discordSrc = createDiscordSource({
+    author: { username: 'alice' },
+    guild: { name: 'G' },
+    channel: { id: 'c', name: 'ops', isThread: () => false },
+  });
+
+  test('prepends header + newline to content', () => {
+    const out = prependSourceHeader('hi is anyone there?', discordSrc);
+    expect(out).toBe('(Message by alice from Discord > G > #ops)\nhi is anyone there?');
+  });
+
+  test('is idempotent — calling twice does not duplicate the header', () => {
+    const once = prependSourceHeader('hello', discordSrc);
+    const twice = prependSourceHeader(once, discordSrc);
+    expect(twice).toBe(once);
+  });
+
+  test('leaves content unchanged when source has no header', () => {
+    expect(prependSourceHeader('hello', null)).toBe('hello');
+    expect(prependSourceHeader('hello', createInternalSource())).toBe('hello');
+    expect(prependSourceHeader('hello', createWebSource())).toBe('hello');
+  });
+
+  test('coerces non-string content to string safely', () => {
+    expect(prependSourceHeader(undefined, null)).toBe('');
+    expect(prependSourceHeader(null, null)).toBe('');
+    expect(prependSourceHeader(42, null)).toBe('42');
+  });
+
+  test('preserves surrounding whitespace in content', () => {
+    const out = prependSourceHeader('\n  indented\n', discordSrc);
+    expect(out.endsWith('\n  indented\n')).toBe(true);
+    expect(out.startsWith('(Message by alice')).toBe(true);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Discriminator surface
+// ────────────────────────────────────────────────────────────────────────
+
+describe('MESSAGE_SOURCE_KINDS', () => {
+  test('is frozen and contains expected keys', () => {
+    expect(Object.isFrozen(MESSAGE_SOURCE_KINDS)).toBe(true);
+    expect(MESSAGE_SOURCE_KINDS).toEqual({
+      DISCORD: 'discord',
+      TELEGRAM: 'telegram',
+      WEB: 'web',
+      API: 'api',
+      INTERNAL: 'internal',
+    });
+  });
+});