onbuzz 4.7.0 → 4.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.7.0",
+  "version": "4.7.2",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/scripts/debug-balance-probe.mjs

@@ -0,0 +1,35 @@
+// Standalone replica of accountRoutes.proxyToBackend, to figure out
+// why the in-process call fails while my curl/node-fetch from the
+// same machine succeed. Run with: node scripts/debug-balance-probe.mjs
+import { readFileSync } from 'fs';
+
+const cfg = JSON.parse(readFileSync('config/default.json', 'utf8'));
+const baseUrl = (cfg.backend?.baseUrl || 'https://autopilot-api.azurewebsites.net').replace(/\/$/, '');
+
+// Pull JWT from the running server (same path /api/auth/status uses).
+const jwt = await (await fetch('http://localhost:8080/api/auth/status')).json().then(d => d.jwt);
+console.log('Using JWT len:', jwt?.length, 'against baseUrl:', baseUrl);
+console.log();
+
+async function proxyLike(path) {
+  const url = `${baseUrl}${path}`;
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${jwt}`,
+        'Content-Type': 'application/json',
+      },
+    });
+    const text = await res.text();
+    let parsed; try { parsed = JSON.parse(text); } catch { parsed = { raw: text.slice(0, 200) }; }
+    console.log(`${path}: status=${res.status} ms=${Date.now() - t0} body=${JSON.stringify(parsed).slice(0, 200)}`);
+  } catch (err) {
+    console.log(`${path}: ERR ${err.message}`);
+  }
+}
+
+for (const p of ['/subscription/status', '/account/profile', '/auth/me', '/auth/apikeys']) {
+  await proxyLike(p);
+}

package/src/__tests__/autoUpdateConfig.test.js

@@ -1,15 +1,25 @@
 /**
- * Tripwire for the auto-update configuration in package.json.
+ * Tripwire: the auto-update feature requires three things in
+ * package.json that are easy to lose in a dep refresh:
  *
- * Catches the class of regression where someone bumps deps or
- * re-formats the build block and accidentally drops:
- *   - the `update-notifier` runtime dep (CLI banner stops working)
- *   - the `electron-updater` optional dep (Electron updates stop)
- *   - the `build.publish` block (electron-builder stops generating
- *     latest.yml + electron-updater has nothing to read)
+ *   1. `update-notifier` in `dependencies` — drives the npm-CLI
+ *      banner. Missing → dynamic import in updateNotifier.js
+ *      silently no-ops (good fail-safe, but the banner disappears
+ *      without any louder signal).
+ *   2. `electron-updater` in `optionalDependencies` — drives the
+ *      Electron in-app update dialog. Missing → autoUpdate.js
+ *      silently no-ops.
+ *   3. `build.publish` config — pointed at the GitHub Releases the
+ *      Electron updater reads `latest.yml` from. Missing → the
+ *      packaged Electron app never sees updates even when
+ *      `electron-updater` is installed.
  *
- * If you intentionally remove any of these, update this test in the
- * SAME commit and explain in the test diff why.
+ * Each is a silent failure on its own. Together they make the
+ * feature look "shipped" but actually inert. This test forces a
+ * loud CI signal when any of the three goes missing.
+ *
+ * If you INTENTIONALLY remove auto-update, change this test in the
+ * same commit and explain why in the diff. Don't just delete it.
  */
 
 import { describe, test, expect } from '@jest/globals';
@@ -33,12 +43,38 @@ describe('package.json — auto-update presence', () => {
 
   test('electron-builder has a publish provider configured', () => {
     expect(pkg.build).toBeDefined();
-    expect(Array.isArray(pkg.build.publish) || typeof pkg.build.publish === 'object').toBe(true);
-    const entries = Array.isArray(pkg.build.publish) ? pkg.build.publish : [pkg.build.publish];
+    const publishField = pkg.build.publish;
+    expect(Array.isArray(publishField) || (publishField && typeof publishField === 'object')).toBe(true);
+    const entries = Array.isArray(publishField) ? publishField : [publishField];
     expect(entries.length).toBeGreaterThan(0);
-    // electron-updater requires a `provider` field on each publish entry.
     for (const entry of entries) {
       expect(entry.provider).toBeTruthy();
     }
   });
+
+  test('GitHub publish target points at a real owner+repo (not the boilerplate `your-org`/`your-repo`)', () => {
+    const entries = Array.isArray(pkg.build.publish) ? pkg.build.publish : [pkg.build.publish];
+    const github = entries.find(e => e.provider === 'github');
+    if (!github) return;        // other providers (S3, etc.) are fine
+    expect(github.owner).toBeTruthy();
+    expect(github.repo).toBeTruthy();
+    // Common copy-paste placeholders.
+    expect(github.owner).not.toMatch(/^(your-org|TODO|placeholder)$/i);
+    expect(github.repo).not.toMatch(/^(your-repo|TODO|placeholder)$/i);
+  });
+
+  test('update-notifier source file exists and is referenced by the CLI entry point', () => {
+    // Tripwire against accidental file deletion. The runtime is
+    // tolerant of missing dependencies (dynamic import), but if the
+    // wrapper FILE goes missing the import line crashes.
+    expect(() => readFileSync(join(REPO_ROOT, 'src/utilities/updateNotifier.js'), 'utf8')).not.toThrow();
+    const cliEntry = readFileSync(join(REPO_ROOT, 'bin/cli.js'), 'utf8');
+    expect(cliEntry).toMatch(/from\s+['"]\.\.\/src\/utilities\/updateNotifier\.js['"]/);
+  });
+
+  test('electron autoUpdate source file exists and is referenced by electron/main.js', () => {
+    expect(() => readFileSync(join(REPO_ROOT, 'electron/autoUpdate.js'), 'utf8')).not.toThrow();
+    const mainEntry = readFileSync(join(REPO_ROOT, 'electron/main.js'), 'utf8');
+    expect(mainEntry).toMatch(/from\s+['"]\.\/autoUpdate\.js['"]/);
+  });
 });

package/src/core/__tests__/messageProcessor.sourceHeader.test.js

@@ -102,7 +102,12 @@ describe('MessageProcessor — source header injection', () => {
     expect(queued.role).toBe('user');
   });
 
-  test('Telegram private message → Telegram > DM attribution', async () => {
+  test('Telegram private message → collapsed "from Telegram" header (no user/DM noise)', async () => {
+    // Telegram private chats have exactly one human; the full
+    // "Message by alice ... > DM" header is bloat that pushes content
+    // out of the agent's context window. We collapse it to a 2-word
+    // prefix instead. Group chats keep the full attribution — see
+    // messageSource.test.js for the group case.
     const source = createTelegramSource({
       message_id: 1,
       chat: { id: 42, type: 'private' },
@@ -115,7 +120,7 @@ describe('MessageProcessor — source header injection', () => {
     });
 
     const [, queued] = agentPool.addUserMessage.mock.calls[0];
-    expect(queued.content).toBe('(Message by alice from Telegram > DM)\nstatus?');
+    expect(queued.content).toBe('(from Telegram)\nstatus?');
     expect(queued.source).toBe(source);
   });
 

package/src/index.js

@@ -705,6 +705,22 @@ class LoxiaApplication {
         this.telegramService.setAgentPool(this.agentPool);
         this.telegramService.setWebSocketManager(webServer);
         if (this.flowExecutor) this.telegramService.setFlowExecutor(this.flowExecutor);
+        // Backend URL + platform API key are needed for the voice-note
+        // → /llm/transcribe path. Without these, voice messages return
+        // a friendly "voice not configured" message and the user is
+        // told to type instead. Both come from the same sources the
+        // rest of the CLI's /api/* proxy code uses.
+        const backendBaseUrl = this.config?.backend?.baseUrl
+          || webServer?.config?.backend?.baseUrl
+          || null;
+        if (backendBaseUrl) this.telegramService.setBackendBaseUrl(backendBaseUrl);
+        // Pass a getter (not a snapshotted value) so the key is
+        // re-resolved on every transcribe call. This lets the user
+        // sign in AFTER boot — voice notes start working immediately
+        // without restarting the server.
+        this.telegramService.setPlatformApiKey(
+          () => this.apiKeyManager?.getKeysForRequest?.(null, { platformProvided: true })?.loxiaApiKey || null
+        );
         // 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.

package/src/interfaces/__tests__/accountRoutes.test.js

@@ -148,7 +148,7 @@ describe('GET /api/account/profile', () => {
 });
 
 describe('GET /api/account/balance', () => {
-  test('proxies to /account/profile and returns the body verbatim', async () => {
+  test('primary path: hits /subscription/status and returns body verbatim', async () => {
     const fetchImpl = jest.fn().mockResolvedValue({
       ok: true, status: 200,
       text: async () => JSON.stringify({ balance: 12.34, plan: 'pro' }),
@@ -159,7 +159,65 @@ describe('GET /api/account/balance', () => {
       const r = await fetch(`${baseUrl}/api/account/balance`);
       const json = await r.json();
       expect(json).toEqual({ balance: 12.34, plan: 'pro' });
-      expect(fetchImpl.mock.calls[0][0]).toBe(`${BACKEND_URL}/account/profile`);
+      expect(fetchImpl.mock.calls[0][0]).toBe(`${BACKEND_URL}/subscription/status`);
+      // Cascade short-circuits on first success — fallback endpoints
+      // are not contacted.
+      expect(fetchImpl).toHaveBeenCalledTimes(1);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('cascade: falls back to /account/profile when /subscription/status fails', async () => {
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce({ ok: false, status: 503, text: async () => JSON.stringify({ error: 'subs down' }) })
+      .mockResolvedValueOnce({ ok: true,  status: 200, text: async () => JSON.stringify({ balance: 7.7, plan: 'free' }) });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/balance`);
+      const json = await r.json();
+      expect(json).toEqual({ balance: 7.7, plan: 'free' });
+      expect(fetchImpl.mock.calls[1][0]).toBe(`${BACKEND_URL}/account/profile`);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('cascade: final fallback uses /auth/me when both fail; returns degraded:true', async () => {
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce({ ok: false, status: 503, text: async () => JSON.stringify({ error: 'subs down' }) })
+      .mockResolvedValueOnce({ ok: false, status: 500, text: async () => JSON.stringify({ error: { message: 'ledger down', code: 'ECONNREFUSED' } }) })
+      .mockResolvedValueOnce({ ok: true,  status: 200, text: async () => JSON.stringify({ user: { creditBalance: 5, accountType: 'free' } }) });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/balance`);
+      const json = await r.json();
+      expect(json.balance).toBe(5);
+      expect(json.plan).toBe('free');
+      expect(json.degraded).toBe(true);
+      // The reason field MUST be a string — not an object — so
+      // FE `title="..."` tooltips don't render "[object Object]".
+      expect(typeof json.reason).toBe('string');
+      expect(json.reason.length).toBeGreaterThan(0);
+    } finally {
+      await stop(server);
+    }
+  });
+
+  test('cascade: every upstream fails → returns degraded with null balance, never 5xx', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue({
+      ok: false, status: 500, text: async () => JSON.stringify({ error: 'everything is broken' }),
+    });
+    const startServer = mountRouter({ fetchImpl });
+    const { server, baseUrl } = await startServer();
+    try {
+      const r = await fetch(`${baseUrl}/api/account/balance`);
+      expect(r.status).toBe(200);  // ← graceful degrade, NOT 500
+      const json = await r.json();
+      expect(json.balance).toBeNull();
+      expect(json.degraded).toBe(true);
     } finally {
       await stop(server);
     }

package/src/interfaces/accountRoutes.js

@@ -106,6 +106,40 @@ export function createAccountRouter({
   const router = express.Router();
   const baseUrl = backendBaseUrl.replace(/\/$/, '');
 
+  // Last-known-good balance cache, per JWT (so a fast user-switch
+  // doesn't show the previous user's balance). Stays in memory only —
+  // a server restart wipes it, by design: stale-on-disk balance would
+  // be more dangerous than no balance.
+  /** @type {Map<string, { balance: number, plan: string|null, savedAt: string }>} */
+  const balanceCache = new Map();
+  function cacheKey(jwt) {
+    if (!jwt) return null;
+    // Hash the JWT to keep memory footprint sane (JWTs are ~240 chars
+    // each). The hash is a fingerprint, not used as auth.
+    let h = 0; for (let i = 0; i < jwt.length; i++) { h = ((h << 5) - h + jwt.charCodeAt(i)) | 0; }
+    return String(h);
+  }
+
+  /**
+   * Coerce whatever the upstream put under `body.error` into a
+   * human-readable string. Different upstream services use different
+   * envelope shapes — string, `{message,code}`, or even nested objects.
+   * Always returns a string so the FE's `title="..."` tooltip never
+   * shows `[object Object]`.
+   */
+  function extractErrorMessage(body) {
+    if (!body) return '';
+    const err = body.error;
+    if (typeof err === 'string') return err;
+    if (err && typeof err === 'object') {
+      if (typeof err.message === 'string') return err.message;
+      if (typeof err.code === 'string')    return err.code;
+      try { return JSON.stringify(err); } catch { return ''; }
+    }
+    if (typeof body.message === 'string') return body.message;
+    return '';
+  }
+
   /**
    * Forward a request to the backend with the user's JWT. Returns a
    * { status, body } tuple the route handlers can hand straight back
@@ -122,11 +156,13 @@ export function createAccountRouter({
     }
     const url = `${baseUrl}${path}`;
     try {
+      const t0 = Date.now();
       const res = await fetchImpl(url, {
         method,
         headers: {
           'Authorization': `Bearer ${jwt}`,
           'Content-Type': 'application/json',
+          'Connection': 'close',
         },
         body: body !== undefined ? JSON.stringify(body) : undefined,
       });
@@ -135,12 +171,26 @@ export function createAccountRouter({
       let parsed;
       try { parsed = text ? JSON.parse(text) : {}; } catch { parsed = { raw: text }; }
 
+      // Per-request debug log so a flaky upstream is diagnosable
+      // without reproducing in a separate process. Worth the noise
+      // because the account proxy currently has an unsolved
+      // discrepancy: standalone Node script gets 200s, the in-process
+      // fetch gets 5xxs against the same URL with the same JWT.
+      logger?.info?.('[accountRoutes] upstream', {
+        url,
+        method,
+        status: res.status,
+        ms: Date.now() - t0,
+        bodyPreview: typeof text === 'string' ? text.slice(0, 200) : null,
+        contentType: res.headers?.get?.('content-type') || null,
+      });
+
       if (!res.ok) {
         return {
           status: res.status,
           body: {
             success: false,
-            error: parsed.error || parsed.message || `Backend returned ${res.status}`,
+            error: extractErrorMessage(parsed) || `Backend returned ${res.status}`,
             code: res.status === 404 ? ERROR_CODES.NOT_FOUND : ERROR_CODES.BACKEND_ERROR,
           },
         };
@@ -159,6 +209,47 @@ export function createAccountRouter({
     }
   }
 
+  // ── Debug ──────────────────────────────────────────────────────────
+  // Temporary diagnostic route. Returns the raw responses from each
+  // upstream call the cascade makes so we can see in the browser why
+  // /balance falls through to degraded when standalone fetch from the
+  // same machine works fine. Remove when the balance issue is closed.
+  router.get('/_debug', async (_req, res) => {
+    const jwt = getJwt();
+    if (!jwt) return res.status(401).json({ error: 'not signed in' });
+    const probe = async (path) => {
+      const url = `${baseUrl}${path}`;
+      const t0 = Date.now();
+      try {
+        const r = await fetchImpl(url, {
+          method: 'GET',
+          headers: {
+            'Authorization': `Bearer ${jwt}`,
+            'Content-Type': 'application/json',
+            'Connection': 'close',
+          },
+        });
+        const text = await r.text();
+        return {
+          path, url, status: r.status, ms: Date.now() - t0,
+          contentType: r.headers?.get?.('content-type') || null,
+          bodyPreview: text.slice(0, 400),
+        };
+      } catch (err) {
+        return { path, url, ms: Date.now() - t0, error: err.message, errCode: err.code, errName: err.name };
+      }
+    };
+    res.json({
+      baseUrl,
+      jwtLen: jwt.length,
+      probes: await Promise.all([
+        probe('/subscription/status'),
+        probe('/account/profile'),
+        probe('/auth/me'),
+      ]),
+    });
+  });
+
   // ── Profile ────────────────────────────────────────────────────────
   router.get('/profile', async (_req, res) => {
     const r = await proxyToBackend('GET', '/auth/me');
@@ -172,13 +263,70 @@ export function createAccountRouter({
   });
 
   // ── Balance ────────────────────────────────────────────────────────
+  // Reads `{ plan, balance, ... }` from the backend.
+  //
+  // Endpoint cascade — first one that returns 2xx wins:
+  //   1. /subscription/status — returns { plan, balance, monthlyAllocation,
+  //      subscriptionStatus, currentPeriodEnd }. Reads from User.creditBalance
+  //      (cached / DB-direct) so it works even when the ledger is down.
+  //      This is the PRIMARY because of that resilience.
+  //   2. /account/profile — bundles plan + balance from the ledger.
+  //      Richer data, but 500s if LEDGER_SERVICE_URL is missing.
+  //   3. /auth/me — no balance, but at least we can return plan + null.
+  //
+  // The FE never sees an error here — degraded data + a `degraded: true`
+  // flag is the right UX, not an error toast.
   router.get('/balance', async (_req, res) => {
-    // The backend exposes a balance read at /account/profile (which
-    // bundles plan + balance) — see autopilot-backend/routes/account.js.
-    // Calling this single endpoint instead of /ledger/balance keeps the
-    // local server free of ledger credentials.
-    const r = await proxyToBackend('GET', '/account/profile');
-    res.status(r.status).json(r.body);
+    // Balance is a per-user query — needs a JWT just like every other
+    // /api/account/* route. Early-exit with the same not_signed_in
+    // envelope so the FE branches the same way.
+    const jwt = getJwt();
+    if (!jwt) {
+      return res.status(401).json({
+        success: false,
+        error: 'Sign in to manage your account',
+        code: ERROR_CODES.NOT_SIGNED_IN,
+      });
+    }
+    const ck = cacheKey(jwt);
+
+    const subscription = await proxyToBackend('GET', '/subscription/status');
+    if (subscription.status >= 200 && subscription.status < 300) {
+      const body = subscription.body || {};
+      if (typeof body.balance === 'number') {
+        balanceCache.set(ck, { balance: body.balance, plan: body.plan || null, savedAt: new Date().toISOString() });
+      }
+      return res.status(subscription.status).json(body);
+    }
+    const profile = await proxyToBackend('GET', '/account/profile');
+    if (profile.status >= 200 && profile.status < 300) {
+      const body = profile.body || {};
+      if (typeof body.balance === 'number') {
+        balanceCache.set(ck, { balance: body.balance, plan: body.plan || body.accountType || null, savedAt: new Date().toISOString() });
+      }
+      return res.status(profile.status).json(body);
+    }
+    // Both balance-bearing endpoints failed. Hand back the last-known
+    // good value (if any) with a `stale: true` flag so the FE shows a
+    // number instead of "— CP". The user still gets a visual cue that
+    // it might not be current.
+    const cached = balanceCache.get(ck);
+    const me = await proxyToBackend('GET', '/auth/me');
+    const u = me.status >= 200 && me.status < 300 ? (me.body?.user || me.body || {}) : {};
+
+    // The internal ECONNREFUSED string is useful for debugging but
+    // not for users — log it once at warn, surface a friendly reason.
+    const technical = extractErrorMessage(subscription.body) || extractErrorMessage(profile.body) || '';
+    if (technical) logger?.warn?.('[accountRoutes] balance degraded', { technical });
+
+    res.json({
+      balance: cached ? cached.balance : (typeof u.creditBalance === 'number' ? u.creditBalance : null),
+      plan:    cached?.plan || u.accountType || null,
+      degraded: true,
+      stale:   !!cached,
+      lastUpdatedAt: cached?.savedAt || null,
+      reason:  'Balance service is temporarily unavailable',
+    });
   });
 
   // ── API keys list ──────────────────────────────────────────────────

package/src/interfaces/webServer.js

@@ -961,7 +961,17 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
     });
 
     // Auth resolve — resolve user account from an existing API key by calling the remote backend
-    // This enables "API key → account auto-link" without requiring a full OAuth login
+    // This enables "API key → account auto-link" without requiring a full OAuth login.
+    //
+    // Preferred path: POST /auth/mint-jwt-from-apikey, which returns
+    // {token, user} in one round-trip. We cache the JWT so subsequent
+    // /api/account/* calls (which require a JWT, not an API key) work
+    // without forcing the user through OAuth.
+    //
+    // Fallback path: GET /auth/me — used when the backend predates
+    // the mint endpoint (older deployment). User is still cached but
+    // no JWT is minted; /api/account/* will be unavailable until the
+    // user does a real OAuth login.
     this.app.get('/api/auth/resolve', async (req, res) => {
       try {
         const loxiaApiKey = this.apiKeyManager?.getKeysForRequest?.(null, { platformProvided: true })?.loxiaApiKey;
@@ -970,6 +980,34 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
         }
 
         const backendBaseUrl = this.config?.backend?.baseUrl || 'https://autopilot-api.azurewebsites.net';
+
+        // Preferred: mint a session JWT alongside the user lookup.
+        try {
+          const mintResp = await fetch(`${backendBaseUrl}/auth/mint-jwt-from-apikey`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${loxiaApiKey}` },
+          });
+          if (mintResp.ok) {
+            const data = await mintResp.json();
+            const user = data.user;
+            const jwt = data.token;
+            if (user && jwt) {
+              await this._setLastAuthResult(recordOAuthResult({
+                user,
+                jwt,
+                hasApiKey: true,
+              }));
+              return res.json({ success: true, user, mintedJwt: true });
+            }
+          }
+          // 404 from older backends → fall through to /auth/me; other
+          // non-2xx → also fall through (the user record is still
+          // worth caching even if we couldn't mint a JWT).
+        } catch (mintErr) {
+          this.logger?.warn('mint-jwt-from-apikey failed; falling back to /auth/me', { error: mintErr.message });
+        }
+
+        // Fallback: just identify the user, no JWT.
         const response = await fetch(`${backendBaseUrl}/auth/me`, {
           headers: { 'Authorization': `Bearer ${loxiaApiKey}` }
         });
@@ -982,15 +1020,13 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
         const user = data.user || data;
 
         // Cache the resolved user for subsequent /api/auth/status calls.
-        // Preserves any JWT from a prior OAuth login (this path mints
-        // no JWT of its own — it just links a user from an existing
-        // API key). See utilities/authCache.js for the invariant.
+        // Preserves any JWT from a prior OAuth login.
         await this._setLastAuthResult(recordResolvedUser({
           user,
           prevCache: this.lastAuthResult,
         }));
 
-        res.json({ success: true, user });
+        res.json({ success: true, user, mintedJwt: false });
       } catch (error) {
         this.logger?.warn('Failed to resolve user from API key', { error: error.message });
         res.json({ success: true, user: null, reason: 'fetch_error', error: error.message });

package/src/services/__tests__/channelRelay.integration.test.js

@@ -312,18 +312,42 @@ function makeTelegramHarness({ agentId = 'agent-y', chatId = 42 } = {}) {
   const logger = createMockLogger();
   const service = new TelegramService(logger);
   service.status = TELEGRAM_STATUS.CONNECTED;
-  service.chatId = chatId;
-  service.activeAgentIds.add(agentId);
+  // Multi-chat shape (no more global scalar `chatId`). Each chat carries
+  // its own activeAgentIds set + a thinking-message map. The relay
+  // pipeline iterates `service.chats` and only sends when the agent is
+  // active in that chat — same contract the production code obeys.
+  service.chats.set(String(chatId), {
+    type: 'private',
+    title: null,
+    addedAt: new Date().toISOString(),
+    watchEnabled: false,
+    lastAgentId: agentId,
+    activeAgentIds: new Set([agentId]),
+    thinkingByAgentId: new Map(),
+  });
   // The event handler short-circuits on `!this.bot`; populate a stub so the
-  // relay pipeline runs. Our `_send` override is the real interception point.
-  service.bot = { sendMessage: jest.fn() };
+  // relay pipeline runs. Our `_send` / sendPhoto / sendDocument overrides
+  // are the interception points.
+  service.bot = {
+    sendMessage:   jest.fn().mockResolvedValue({ message_id: 1 }),
+    editMessageText: jest.fn().mockResolvedValue({ ok: true }),
+    deleteMessage: jest.fn().mockResolvedValue(undefined),
+    sendPhoto:    jest.fn().mockResolvedValue({}),
+    sendDocument: jest.fn().mockResolvedValue({}),
+    sendChatAction: jest.fn().mockResolvedValue({}),
+  };
   service.setAgentPool({
     getAgent: jest.fn().mockResolvedValue({ id: agentId, name: 'Agent Y' }),
   });
 
-  // Intercept the real underlying `_send` to avoid hitting node-telegram-bot-api.
+  // Intercept the real underlying `_sendRaw` (and its wrapper `_send`)
+  // to avoid hitting node-telegram-bot-api. Capturing at `_sendRaw`
+  // catches edit-placeholder and fresh-send paths uniformly.
   const sends = [];
-  service._send = jest.fn(async (chatIdArg, text) => {
+  service._sendRaw = jest.fn(async (chatIdArg, text /* , opts */) => {
+    sends.push({ chatId: chatIdArg, text });
+  });
+  service._send = jest.fn(async (chatIdArg, text /* , opts */) => {
     sends.push({ chatId: chatIdArg, text });
   });
 
@@ -354,7 +378,10 @@ describe('Telegram relay — end-to-end via _handleBroadcastEvent', () => {
       },
     });
     expect(harness.sends).toHaveLength(1);
-    expect(harness.sends[0].chatId).toBe(harness.chatId);
+    // The service normalises chat IDs to strings (Map keys); the
+    // harness factory builds with a numeric `chatId` so we coerce
+    // before comparing.
+    expect(String(harness.sends[0].chatId)).toBe(String(harness.chatId));
     expect(harness.sends[0].text).toContain('hi from agent');
   });
 
@@ -393,8 +420,13 @@ describe('Telegram relay — end-to-end via _handleBroadcastEvent', () => {
     expect(harness.sends.map(s => s.text).join('|')).toMatch(/A.*B.*C/s);
   });
 
-  test('agent not in activeAgentIds → nothing sent', async () => {
-    harness.service.activeAgentIds.clear();
+  test('agent not in any chat\'s activeAgentIds → nothing sent', async () => {
+    // Multi-chat refactor: activeAgentIds is now per-chat state. Drop
+    // the agent from every chat to simulate "user has stopped
+    // following this agent everywhere".
+    for (const state of harness.service.chats.values()) {
+      state.activeAgentIds.clear();
+    }
     await harness.service._handleBroadcastEvent({
       type: 'stream_complete',
       data: {
@@ -434,9 +466,14 @@ describe('Telegram relay — end-to-end via _handleBroadcastEvent', () => {
     expect(harness.sends[0].text).not.toContain('memory');
   });
 
-  test('getBridgedChannels returns the telegram alias when bridged, empty otherwise', () => {
-    expect(harness.service.getBridgedChannels(harness.agentId))
-      .toEqual([{ alias: 'telegram', label: 'Telegram chat' }]);
+  test('getBridgedChannels returns per-chat aliases plus the bare "telegram" alias', () => {
+    // Multi-chat: one alias per chat the agent is active in, plus a
+    // bare `telegram` alias for agents that don't know per-chat
+    // addressing. With one chat registered (chatId=42), we expect:
+    //   - `telegram:chat-42` — chat-scoped alias
+    //   - `telegram`         — broadcast-friendly fallback alias
+    const aliases = harness.service.getBridgedChannels(harness.agentId).map(c => c.alias);
+    expect(aliases).toEqual(expect.arrayContaining(['telegram:chat-42', 'telegram']));
     expect(harness.service.getBridgedChannels('other-agent')).toEqual([]);
   });
 });

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

@@ -271,12 +271,16 @@ describe('describeSource', () => {
     expect(describeSource(src)).toBe('Message by alice from Telegram > Ops Chat');
   });
 
-  test('Telegram private chat', () => {
+  test('Telegram private chat — collapsed to "from Telegram" (no user/DM noise)', () => {
+    // In a private DM the chat has exactly one human; spelling out
+    // the username + a redundant "> DM" was just header bloat that
+    // pushed real content out of context. The agent still knows the
+    // channel is Telegram. Group chats keep the full attribution.
     const src = createTelegramSource({
       chat: { id: 1, type: 'private' },
       from: { username: 'alice' },
     });
-    expect(describeSource(src)).toBe('Message by alice from Telegram > DM');
+    expect(describeSource(src)).toBe('from Telegram');
   });
 
   test('Telegram group with no title falls back to chat id', () => {