@pellux/goodvibes-tui 0.24.0 → 0.25.0

package/src/daemon/channels/inbox/poller.ts

@@ -0,0 +1,155 @@
+// ---------------------------------------------------------------------------
+// Inbound provider poller.
+//
+// Runs one setInterval per provider at the provider's own cadence (Slack/
+// Discord 30s, email 60s, others 120s). Each tick:
+//   1. resolves the provider's persisted cursor (nextSince)
+//   2. calls adapter.poll({ since, limit })
+//   3. dedups + persists items into the cursor store (INSERT OR IGNORE / upsert)
+//   4. advances the cursor monotonically to max(receivedAt)
+//   5. records the last per-provider state for channels.inbox.list to report
+//
+// One bad provider can never crash the loop: adapter.poll() resolves with
+// state:'unavailable' instead of rejecting, and any thrown error is caught and
+// downgraded to an 'unavailable' status here.
+// ---------------------------------------------------------------------------
+
+import type { InboundProviderAdapter, ProviderState } from './provider-adapter.ts';
+import type { InboxCursorStore } from './cursor-store.ts';
+import type { OperatorLogger } from '../../operator/index.ts';
+
+export interface ProviderStatus {
+  id: string;
+  state: ProviderState;
+  itemCount: number;
+  error?: string;
+  lastPolledAt?: number;
+}
+
+export interface PollerOptions {
+  adapters: Map<string, InboundProviderAdapter>;
+  store: InboxCursorStore;
+  logger: OperatorLogger;
+  /** Max items fetched per provider per tick. */
+  perProviderLimit?: number;
+  /** Inject a timer factory for tests (defaults to global setInterval). */
+  setIntervalImpl?: typeof setInterval;
+  clearIntervalImpl?: typeof clearInterval;
+}
+
+const DEFAULT_PER_PROVIDER_LIMIT = 50;
+
+export class InboundPoller {
+  private readonly adapters: Map<string, InboundProviderAdapter>;
+  private readonly store: InboxCursorStore;
+  private readonly logger: OperatorLogger;
+  private readonly perProviderLimit: number;
+  private readonly setIntervalImpl: typeof setInterval;
+  private readonly clearIntervalImpl: typeof clearInterval;
+  private readonly timers = new Map<string, ReturnType<typeof setInterval>>();
+  private readonly statuses = new Map<string, ProviderStatus>();
+  private readonly inFlight = new Set<string>();
+  private started = false;
+
+  constructor(options: PollerOptions) {
+    this.adapters = options.adapters;
+    this.store = options.store;
+    this.logger = options.logger;
+    this.perProviderLimit = options.perProviderLimit ?? DEFAULT_PER_PROVIDER_LIMIT;
+    this.setIntervalImpl = options.setIntervalImpl ?? setInterval;
+    this.clearIntervalImpl = options.clearIntervalImpl ?? clearInterval;
+    for (const id of this.adapters.keys()) {
+      this.statuses.set(id, { id, state: 'empty', itemCount: 0 });
+    }
+  }
+
+  /** Begin per-provider interval loops. Idempotent. Does NOT poll immediately. */
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    for (const [id, adapter] of this.adapters) {
+      const handle = this.setIntervalImpl(() => {
+        void this.pollProvider(id, adapter);
+      }, adapter.pollIntervalMs);
+      // Do not keep the event loop alive solely for polling (Bun/Node unref).
+      (handle as unknown as { unref?: () => void }).unref?.();
+      this.timers.set(id, handle);
+    }
+  }
+
+  /** Run a single poll across all providers now (used on register + tests). */
+  async pollOnce(): Promise<void> {
+    await Promise.all(
+      [...this.adapters.entries()].map(([id, adapter]) => this.pollProvider(id, adapter)),
+    );
+  }
+
+  /** Poll a single provider, dedup + persist, update status. Never throws. */
+  async pollProvider(id: string, adapter: InboundProviderAdapter): Promise<void> {
+    if (this.inFlight.has(id)) return; // skip overlapping ticks
+    this.inFlight.add(id);
+    const since = this.store.getCursor(id) || undefined;
+    try {
+      const result = await adapter.poll({ since, limit: this.perProviderLimit });
+      if (result.state === 'unavailable') {
+        this.setStatus(id, {
+          id,
+          state: 'unavailable',
+          itemCount: 0,
+          error: result.error ?? 'provider unavailable',
+          lastPolledAt: Date.now(),
+        });
+        return;
+      }
+      const newCount = this.store.upsertItems(result.items);
+      let maxReceived = since ?? 0;
+      for (const item of result.items) {
+        if (item.receivedAt > maxReceived) maxReceived = item.receivedAt;
+      }
+      if (maxReceived > 0) this.store.advanceCursor(id, maxReceived);
+      await this.store.flush();
+      this.setStatus(id, {
+        id,
+        state: result.items.length > 0 ? 'ready' : 'empty',
+        itemCount: newCount,
+        lastPolledAt: Date.now(),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn('inbound poll failed', { provider: id, error: message });
+      this.setStatus(id, {
+        id,
+        state: 'unavailable',
+        itemCount: 0,
+        error: message,
+        lastPolledAt: Date.now(),
+      });
+    } finally {
+      this.inFlight.delete(id);
+    }
+  }
+
+  /** Snapshot of the last known status for each provider. */
+  snapshotStatuses(providerIds?: readonly string[]): ProviderStatus[] {
+    const ids = providerIds && providerIds.length > 0
+      ? providerIds.filter((id) => this.statuses.has(id))
+      : [...this.statuses.keys()];
+    return ids.map((id) => {
+      const status = this.statuses.get(id)!;
+      return { ...status };
+    });
+  }
+
+  /** Stop all interval loops. Idempotent. */
+  stop(): void {
+    for (const handle of this.timers.values()) {
+      this.clearIntervalImpl(handle);
+    }
+    this.timers.clear();
+    this.started = false;
+  }
+
+  private setStatus(id: string, status: ProviderStatus): void {
+    this.statuses.set(id, status);
+  }
+}

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

@@ -0,0 +1,152 @@
+// ---------------------------------------------------------------------------
+// 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 '../../operator/index.ts';
+import type { OperatorLogger } from '../../operator/index.ts';
+
+/** Wire-shape inbound item as published by `channels.inbox.list`. */
+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 (handoff: 'first-8' bytes / acceptance
+   * checklist: 'first 16 hex chars' — the same value).
+   */
+  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;
+}
+
+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: OperatorLogger;
+  /**
+   * 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 (concurrent work)
+ * injects its `resolveProfile`-backed implementation. 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 ignored by the caller via the
+ * returned map only containing 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/channels/inbox/providers/discord.ts

@@ -0,0 +1,253 @@
+// ---------------------------------------------------------------------------
+// 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 (handoff acceptance checklist: "Daemon polls Discord DMs via
+// Discord Gateway") 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';
+
+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. This 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 unavailable('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 (see provider-adapter.ts InboundChannelItem and
+              // handoff acceptance checklist 'first 16 hex chars'). 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' };
+      } catch (error) {
+        return unavailable(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();
+}
+
+function unavailable(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error };
+}
+
+function errMsg(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}