@pellux/goodvibes-daemon 1.28.0

package/src/daemon/handlers/inbox/provider-adapter.ts

@@ -0,0 +1,171 @@
+// ---------------------------------------------------------------------------
+// Inbound provider adapter contract + registry.
+//
+// Each adapter owns ONE provider (slack, discord, email, ...). The poller calls
+// adapter.poll() on a cadence, dedups by item.id, and persists into the cursor
+// store. Adapters resolve credentials ONLY through the daemon credential store
+// and NEVER return raw sender ids or unredacted bodies — mapping/redaction is
+// the adapter's responsibility (see mapping helpers in `./mapping.ts`).
+//
+// CRITICAL: when a credential is missing/misconfigured an adapter returns
+// state 'unavailable' WITH an error string. It is NEVER silently omitted — the
+// caller must be able to distinguish "configured-but-empty" from "not wired".
+// ---------------------------------------------------------------------------
+
+import type { DaemonCredentialStore } from '../credentials.ts';
+import type { HandlerLogger } from '../context.ts';
+
+/**
+ * Daemon-internal inbound item. This is NOT the SDK wire shape — the inbox
+ * surface maps it onto the SDK `CHANNEL_INBOX_ITEM_SCHEMA` shape
+ * (`from`/`subject`/`bodyPreview`/...) before returning. `fromDigest` is the
+ * redacted sender (the only sender value that ever leaves the daemon).
+ */
+export interface InboundChannelItem {
+  /** Stable, provider-scoped dedup key. Idempotent across polls. */
+  id: string;
+  provider: string;
+  kind: 'dm' | 'thread' | 'mention' | 'reaction';
+  /**
+   * sha256First(senderExternalId, 16) — NEVER the raw id. 16 hex chars == the
+   * first 8 bytes of the SHA-256 digest.
+   */
+  fromDigest: string;
+  /** <= 200 chars, safe for display. */
+  subjectPreview: string;
+  /** <= 500 chars, plain text, PII-stripped. */
+  bodyPreview: string;
+  /** Daemon route binding id, when resolvable. */
+  routeId?: string;
+  /** Unix ms. */
+  receivedAt: number;
+  unread: boolean;
+  /** Optional triage metadata written by the triage surface (read-only here). */
+  triageScore?: number;
+  triageTags?: string[];
+}
+
+export type ProviderState = 'ready' | 'unavailable' | 'empty';
+
+export interface ProviderPollResult {
+  items: InboundChannelItem[];
+  state: ProviderState;
+  /** Present only when state === 'unavailable'. */
+  error?: string;
+  /**
+   * Whether this provider's credentials resolved.
+   *
+   * 'unavailable' alone conflates two things a reader has to tell apart: a
+   * provider nobody has wired up yet, and a wired-up provider whose API just
+   * refused us. The first is a normal state of a fresh install and the second
+   * is an outage hiding items that exist, and `channels.inbox.list` reports
+   * them as different states because a caller acts on them differently.
+   *
+   * `false` — no credential (or an unusable one), so nothing was even asked.
+   * `true`  — credentials resolved; whatever happened next happened WITH them.
+   * absent  — the adapter could not find out (the credential store itself
+   *           failed), which is neither claim and is reported as neither.
+   */
+  configured?: boolean;
+}
+
+export interface ProviderPollOptions {
+  /** Only return items newer than this Unix-ms timestamp, when supported. */
+  since?: number;
+  /** Max items to return this poll. */
+  limit: number;
+}
+
+/** Context handed to every adapter at construction time. */
+export interface AdapterContext {
+  readonly credentials: DaemonCredentialStore;
+  readonly logger: HandlerLogger;
+  /**
+   * Optional route resolver supplied by the routing surface. Returns the route
+   * binding id for a given inbound item, or undefined when no route matches /
+   * the routing surface is not wired yet. Adapters/poller call this best-effort.
+   */
+  readonly resolveRouteId?: RouteResolver;
+}
+
+/**
+ * Best-effort route resolution seam. The routing surface injects its
+ * profile-backed implementation via the inbox bridge. Until then it is
+ * undefined and items carry no routeId.
+ */
+export type RouteResolver = (input: {
+  provider: string;
+  fromDigest: string;
+  kind: InboundChannelItem['kind'];
+}) => Promise<string | undefined> | string | undefined;
+
+export interface InboundProviderAdapter {
+  /** Provider id, e.g. 'slack'. Must be unique within the registry. */
+  readonly id: string;
+  /**
+   * Poll cadence in ms. Slack/Discord 30s, email 60s, everything else 120s.
+   * The poller reads this to schedule its per-provider interval.
+   */
+  readonly pollIntervalMs: number;
+  /**
+   * Pull recent DMs/threads/mentions. MUST resolve (never reject) — failures
+   * are reported via state:'unavailable' + error so one bad provider cannot
+   * crash the aggregate feed.
+   */
+  poll(opts: ProviderPollOptions): Promise<ProviderPollResult>;
+}
+
+/** Factory signature: adapters are constructed lazily with shared context. */
+export type AdapterFactory = (ctx: AdapterContext) => InboundProviderAdapter;
+
+// ---------------------------------------------------------------------------
+// Cadence constants (single source of truth, referenced by adapters + tests).
+// ---------------------------------------------------------------------------
+
+export const POLL_CADENCE_MS = {
+  realtime: 30_000, // slack, discord
+  email: 60_000,
+  default: 120_000,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const FACTORIES = new Map<string, AdapterFactory>();
+
+/** Register a provider factory. Last registration for an id wins (idempotent). */
+export function registerAdapterFactory(id: string, factory: AdapterFactory): void {
+  FACTORIES.set(id, factory);
+}
+
+/** All registered provider ids, in insertion order. */
+export function registeredProviderIds(): string[] {
+  return [...FACTORIES.keys()];
+}
+
+/**
+ * Construct adapters for the requested provider ids (or all registered ids when
+ * `requested` is undefined/empty). Unknown ids are dropped: the returned map
+ * only contains known providers.
+ */
+export function buildAdapters(
+  ctx: AdapterContext,
+  requested?: readonly string[],
+): Map<string, InboundProviderAdapter> {
+  const ids = requested && requested.length > 0
+    ? requested.filter((id) => FACTORIES.has(id))
+    : registeredProviderIds();
+  const out = new Map<string, InboundProviderAdapter>();
+  for (const id of ids) {
+    const factory = FACTORIES.get(id);
+    if (!factory) continue;
+    out.set(id, factory(ctx));
+  }
+  return out;
+}
+
+/** Test/seam hook: clear the registry. */
+export function clearAdapterRegistry(): void {
+  FACTORIES.clear();
+}

package/src/daemon/handlers/inbox/providers/discord.ts

@@ -0,0 +1,276 @@
+// ---------------------------------------------------------------------------
+// Discord inbound adapter.
+//
+// Transport note (contract fidelity): the daemon-handoff checklist names the
+// Discord Gateway for DM polling. The Gateway is a persistent websocket push
+// transport and cannot be driven by the inbound poller, whose contract is a
+// stateless, cadence-driven adapter.poll() that MUST resolve each call (see
+// provider-adapter.ts) — a long-lived socket the poller neither owns nor
+// supervises is out of scope for that contract. We therefore satisfy the
+// DM-polling goal over Discord's supported request/response surface, the REST
+// API — the same DM data the Gateway streams, fetched on the poll cadence and
+// paged so a busy DM is never truncated:
+//   GET /users/@me/channels        -> list DM channels the bot participates in
+//   GET /channels/{id}/messages    -> recent messages per DM channel (paged via
+//                                   the `before` snowflake cursor)
+//
+// Discord snowflake ids encode their creation timestamp, so receivedAt is
+// derived from the message id (snowflake) when no explicit timestamp is present.
+//
+// Credential: surfaces.discord.botToken. Missing => 'unavailable'.
+// Cadence: 30s (realtime tier).
+// ---------------------------------------------------------------------------
+
+import type {
+  AdapterContext,
+  InboundChannelItem,
+  InboundProviderAdapter,
+  ProviderPollOptions,
+  ProviderPollResult,
+} from '../provider-adapter.ts';
+import { POLL_CADENCE_MS } from '../provider-adapter.ts';
+import { digestSender, toBodyPreview, toSubjectPreview } from '../mapping.ts';
+import { resolveRouteId } from './route-util.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+const DISCORD_API = 'https://discord.com/api/v10';
+// Discord epoch (2015-01-01T00:00:00Z) in ms, used to decode snowflakes.
+const DISCORD_EPOCH_MS = 1_420_070_400_000;
+export const DISCORD_PROVIDER_ID = 'discord';
+export const DISCORD_CREDENTIAL_KEY = 'surfaces.discord.botToken';
+
+interface DiscordChannel {
+  id: string;
+  type: number; // 1 = DM, 3 = group DM
+}
+
+interface DiscordSelf {
+  id: string;
+}
+
+interface DiscordReaction {
+  count?: number;
+  emoji?: { id?: string | null; name?: string | null };
+}
+
+interface DiscordMessage {
+  id: string;
+  channel_id?: string;
+  content?: string;
+  timestamp?: string; // ISO-8601
+  author?: { id: string; bot?: boolean };
+  referenced_message?: unknown;
+  mentions?: Array<{ id: string }>;
+  reactions?: DiscordReaction[];
+}
+
+/**
+ * Classify a Discord message into the InboundChannelItem `kind`.
+ *   - reaction: someone reacted to OUR OWN message — a genuine inbound reaction
+ *               event. Requires the message to be authored by us (its author id
+ *               is selfId) AND to carry a non-empty reactions[]. A message
+ *               authored by someone else that merely carries reactions[] is a
+ *               normal DM, not a reaction event.
+ *   - mention:  the message mentions us (our id is in mentions[])
+ *   - thread:   the message is a reply (referenced_message present)
+ *   - dm:       a plain direct message
+ * Reaction outranks mention which outranks thread/dm (most-specific first).
+ */
+function classifyDiscordKind(
+  msg: DiscordMessage,
+  selfId: string | undefined,
+): InboundChannelItem['kind'] {
+  if (
+    selfId &&
+    msg.author?.id === selfId &&
+    Array.isArray(msg.reactions) &&
+    msg.reactions.length > 0
+  ) {
+    return 'reaction';
+  }
+  if (selfId && Array.isArray(msg.mentions) && msg.mentions.some((m) => m.id === selfId)) {
+    return 'mention';
+  }
+  if (msg.referenced_message) return 'thread';
+  return 'dm';
+}
+
+/** Decode a Discord snowflake id to its creation Unix-ms timestamp. */
+function snowflakeToMs(id: string): number {
+  try {
+    const asBig = BigInt(id);
+    return Number((asBig >> 22n)) + DISCORD_EPOCH_MS;
+  } catch {
+    return 0;
+  }
+}
+
+async function discordGet<T>(token: string, path: string): Promise<T> {
+  const res = await fetch(`${DISCORD_API}${path}`, {
+    method: 'GET',
+    headers: {
+      Authorization: `Bot ${token}`,
+      Accept: 'application/json',
+    },
+  });
+  if (res.status === 401) throw new Error('Discord authentication failed (401)');
+  if (!res.ok) throw new Error(`Discord GET ${path} HTTP ${res.status}`);
+  return (await res.json()) as T;
+}
+
+export function createDiscordAdapter(ctx: AdapterContext): InboundProviderAdapter {
+  return {
+    id: DISCORD_PROVIDER_ID,
+    pollIntervalMs: POLL_CADENCE_MS.realtime,
+    async poll(opts: ProviderPollOptions): Promise<ProviderPollResult> {
+      let token: string | null;
+      try {
+        token = await ctx.credentials.resolveConfigSecret(DISCORD_CREDENTIAL_KEY);
+      } catch (error) {
+        return unavailable(`credential lookup failed: ${errMsg(error)}`);
+      }
+      if (!token || token.trim().length === 0) {
+        return notConfigured('missing surfaces.discord.botToken');
+      }
+
+      // Resolve our own user id so we can classify @-mentions of us. Best-effort:
+      // a failure only disables mention classification, never the provider.
+      let selfId: string | undefined;
+      try {
+        const self = await discordGet<DiscordSelf>(token, '/users/@me');
+        if (self.id) selfId = self.id;
+      } catch (error) {
+        ctx.logger.warn('discord /users/@me failed; mentions will not be classified', {
+          error: errMsg(error),
+        });
+      }
+
+      try {
+        const channels = await discordGet<DiscordChannel[]>(token, '/users/@me/channels');
+        const dmChannels = channels.filter((c) => c.type === 1 || c.type === 3);
+        const items: InboundChannelItem[] = [];
+        // /channels/{id}/messages returns at most `perChannel` (<=50) messages
+        // newest-first. A DM that accrued more than one page of new messages in
+        // the `since` window would silently drop the oldest beyond the first page
+        // unless we page backwards via the `before` cursor (the id of the oldest
+        // message seen so far). MAX_HISTORY_PAGES bounds the walk.
+        const MAX_HISTORY_PAGES = 20;
+        const perChannel = Math.min(opts.limit, 50);
+        channelLoop: for (const channel of dmChannels) {
+          if (items.length >= opts.limit) break;
+          let before: string | undefined;
+          for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
+            const params = new URLSearchParams({ limit: String(perChannel) });
+            // Discord treats after/before/around as mutually exclusive: sending
+            // both silently drops older in-window messages. Use `after` only on
+            // the first page (to bound the window at `since`); once paging
+            // backwards via `before`, drop `after` and rely on the
+            // oldestMs<=since stop condition below to terminate the walk.
+            if (before) params.set('before', before);
+            else if (opts.since) params.set('after', msToSnowflake(opts.since));
+            let messages: DiscordMessage[];
+            try {
+              messages = await discordGet<DiscordMessage[]>(
+                token,
+                `/channels/${channel.id}/messages?${params.toString()}`,
+              );
+            } catch (error) {
+              ctx.logger.warn('discord channel messages failed', {
+                channel: channel.id,
+                error: errMsg(error),
+              });
+              continue channelLoop;
+            }
+            if (messages.length === 0) break;
+            // Track the oldest id on this page for the next `before` cursor before
+            // we filter/skip, so pagination is driven by the raw page, not by what
+            // survived classification.
+            let oldestId: string | undefined;
+            let oldestMs = Number.POSITIVE_INFINITY;
+            for (const msg of messages) {
+              const msgMs = msg.timestamp
+                ? Date.parse(msg.timestamp) || snowflakeToMs(msg.id)
+                : snowflakeToMs(msg.id);
+              if (msgMs < oldestMs) {
+                oldestMs = msgMs;
+                oldestId = msg.id;
+              }
+              if (items.length >= opts.limit) break;
+              if (msg.author?.bot) continue;
+              const receivedAt = msgMs;
+              if (opts.since && receivedAt <= opts.since) continue;
+              const senderId = msg.author?.id ?? channel.id;
+              // Contract: fromDigest is SHA-256 (first 16 hex == 8 bytes) of the
+              // provider user id. Discord user ids (snowflakes) are globally
+              // unique, and the item.id / provider fields already namespace by
+              // provider.
+              const fromDigest = digestSender(senderId);
+              const kind = classifyDiscordKind(msg, selfId);
+              const item: InboundChannelItem = {
+                id: `discord:${channel.id}:${msg.id}`,
+                provider: DISCORD_PROVIDER_ID,
+                kind,
+                fromDigest,
+                subjectPreview: toSubjectPreview('Direct message'),
+                bodyPreview: toBodyPreview(msg.content),
+                receivedAt,
+                unread: true,
+              };
+              const routeId = await resolveRouteId(ctx, DISCORD_PROVIDER_ID, fromDigest, kind);
+              if (routeId) item.routeId = routeId;
+              items.push(item);
+            }
+            // Stop paging this channel when the page was not full (no older
+            // messages exist), the item budget is spent, or the oldest message on
+            // this page is already at/older than the `since` floor.
+            if (messages.length < perChannel || items.length >= opts.limit) break;
+            if (opts.since && oldestMs <= opts.since) break;
+            if (!oldestId) break;
+            before = oldestId;
+          }
+        }
+        return { items, state: items.length > 0 ? 'ready' : 'empty', configured: true };
+      } catch (error) {
+        return failed(errMsg(error));
+      }
+    },
+  };
+}
+
+/** Build a synthetic snowflake from a Unix-ms timestamp for the `after` cursor. */
+function msToSnowflake(ms: number): string {
+  const delta = Math.max(0, Math.floor(ms) - DISCORD_EPOCH_MS);
+  return (BigInt(delta) << 22n).toString();
+}
+
+/**
+ * The provider is wired up but this attempt failed — an outage, a refusal, a
+ * bad response. Items that exist are missing from the feed, which is what
+ * `configured: true` here tells the aggregator to report as a partial answer
+ * rather than as an empty one.
+ */
+function failed(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error, configured: true };
+}
+
+/**
+ * Nothing to poll with: no credential, or an unusable one. Normal on a fresh
+ * install, and deliberately NOT a partial answer — nothing is missing from a
+ * provider nobody asked us to read.
+ */
+function notConfigured(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error, configured: false };
+}
+
+/**
+ * The credential store itself failed, so we do not know whether this provider
+ * is configured. Neither claim is made — reporting a guess here is how a
+ * transient store fault would get read as "you never set this up".
+ */
+function unavailable(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error };
+}
+
+function errMsg(error: unknown): string {
+  return summarizeError(error);
+}

package/src/daemon/handlers/inbox/providers/email.ts

@@ -0,0 +1,176 @@
+// ---------------------------------------------------------------------------
+// Email (IMAP) inbound adapter.
+//
+// Uses the dependency-free ImapClient (node:tls) to pull recent INBOX messages.
+// Connection params resolve through the daemon credential store (env/secrets
+// backend) so nothing sensitive is read from plaintext config:
+//   surfaces.email.imapHost      (e.g. imap.fastmail.com)
+//   surfaces.email.imapPort      (default 993)
+//   surfaces.email.imapUser
+//   surfaces.email.imapPassword  (app password / token)
+//
+// Any missing required field => state 'unavailable' WITH an explanatory error.
+// Cadence: 60s (email tier).
+// ---------------------------------------------------------------------------
+
+import type {
+  AdapterContext,
+  InboundChannelItem,
+  InboundProviderAdapter,
+  ProviderPollOptions,
+  ProviderPollResult,
+} from '../provider-adapter.ts';
+import { POLL_CADENCE_MS } from '../provider-adapter.ts';
+import { digestSender, toBodyPreview, toSubjectPreview } from '../mapping.ts';
+import { resolveRouteId } from './route-util.ts';
+import { ImapClient } from './imap-client.ts';
+import type { ImapConfig, ImapEnvelope } from './imap-client.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+export const EMAIL_PROVIDER_ID = 'email';
+export const EMAIL_HOST_KEY = 'surfaces.email.imapHost';
+export const EMAIL_PORT_KEY = 'surfaces.email.imapPort';
+export const EMAIL_USER_KEY = 'surfaces.email.imapUser';
+export const EMAIL_PASSWORD_KEY = 'surfaces.email.imapPassword';
+
+/**
+ * Injectable client factory so tests can substitute a fake IMAP client without
+ * opening a TLS socket. Production default constructs the real ImapClient.
+ */
+export interface ImapLike {
+  connect(): Promise<void>;
+  login(): Promise<void>;
+  select(mailbox?: string): Promise<void>;
+  searchUids(since?: number): Promise<number[]>;
+  fetchEnvelopes(uids: readonly number[]): Promise<ImapEnvelope[]>;
+  logout(): Promise<void>;
+  close(): void;
+}
+
+export type ImapClientFactory = (cfg: ImapConfig) => ImapLike;
+
+const defaultFactory: ImapClientFactory = (cfg) => new ImapClient(cfg);
+
+export function createEmailAdapter(
+  ctx: AdapterContext,
+  factory: ImapClientFactory = defaultFactory,
+): InboundProviderAdapter {
+  return {
+    id: EMAIL_PROVIDER_ID,
+    pollIntervalMs: POLL_CADENCE_MS.email,
+    async poll(opts: ProviderPollOptions): Promise<ProviderPollResult> {
+      let host: string | null;
+      let user: string | null;
+      let password: string | null;
+      let portRaw: string | null;
+      try {
+        [host, portRaw, user, password] = await Promise.all([
+          ctx.credentials.resolveConfigSecret(EMAIL_HOST_KEY),
+          ctx.credentials.resolveConfigSecret(EMAIL_PORT_KEY),
+          ctx.credentials.resolveConfigSecret(EMAIL_USER_KEY),
+          ctx.credentials.resolveConfigSecret(EMAIL_PASSWORD_KEY),
+        ]);
+      } catch (error) {
+        return unavailable(`credential lookup failed: ${errMsg(error)}`);
+      }
+
+      const missing: string[] = [];
+      if (!host) missing.push('imapHost');
+      if (!user) missing.push('imapUser');
+      if (!password) missing.push('imapPassword');
+      if (missing.length > 0) {
+        return notConfigured(`missing email IMAP credentials: ${missing.join(', ')}`);
+      }
+      const port = portRaw ? Number.parseInt(portRaw, 10) : 993;
+      if (!Number.isFinite(port) || port <= 0) {
+        return notConfigured(`invalid surfaces.email.imapPort: ${portRaw}`);
+      }
+
+      const client = factory({
+        host: host!,
+        port,
+        user: user!,
+        password: password!,
+      });
+
+      try {
+        await client.connect();
+        await client.login();
+        await client.select('INBOX');
+        const uids = await client.searchUids(opts.since);
+        // Newest UIDs first, capped at limit.
+        const selected = uids.sort((a, b) => b - a).slice(0, opts.limit);
+        const envelopes = await client.fetchEnvelopes(selected);
+        const items: InboundChannelItem[] = [];
+        for (const env of envelopes) {
+          const receivedAt = env.date > 0 ? env.date : Date.now();
+          if (opts.since && receivedAt <= opts.since) continue;
+          const fromDigest = digestSender(`email:${normalizeAddress(env.from)}`);
+          const kind = 'dm';
+          const item: InboundChannelItem = {
+            id: `email:${user}:${env.uid}`,
+            provider: EMAIL_PROVIDER_ID,
+            kind,
+            fromDigest,
+            subjectPreview: toSubjectPreview(env.subject),
+            bodyPreview: toBodyPreview(env.bodyPreview),
+            receivedAt,
+            unread: !env.seen,
+          };
+          const routeId = await resolveRouteId(ctx, EMAIL_PROVIDER_ID, fromDigest, kind);
+          if (routeId) item.routeId = routeId;
+          items.push(item);
+        }
+        return { items, state: items.length > 0 ? 'ready' : 'empty', configured: true };
+      } catch (error) {
+        return failed(errMsg(error));
+      } finally {
+        try {
+          await client.logout();
+        } catch {
+          // ignore
+        }
+        client.close();
+      }
+    },
+  };
+}
+
+/** Extract a bare address from a `Name <addr@host>` From header for digesting. */
+function normalizeAddress(from: string): string {
+  const angle = /<([^>]+)>/.exec(from);
+  const addr = (angle ? angle[1]! : from).trim().toLowerCase();
+  return addr.length > 0 ? addr : from.trim().toLowerCase();
+}
+
+/**
+ * The provider is wired up but this attempt failed — an outage, a refusal, a
+ * bad response. Items that exist are missing from the feed, which is what
+ * `configured: true` here tells the aggregator to report as a partial answer
+ * rather than as an empty one.
+ */
+function failed(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error, configured: true };
+}
+
+/**
+ * Nothing to poll with: no credential, or an unusable one. Normal on a fresh
+ * install, and deliberately NOT a partial answer — nothing is missing from a
+ * provider nobody asked us to read.
+ */
+function notConfigured(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error, configured: false };
+}
+
+/**
+ * The credential store itself failed, so we do not know whether this provider
+ * is configured. Neither claim is made — reporting a guess here is how a
+ * transient store fault would get read as "you never set this up".
+ */
+function unavailable(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error };
+}
+
+function errMsg(error: unknown): string {
+  return summarizeError(error);
+}