@pellux/goodvibes-tui 0.24.1 → 0.25.0

package/src/daemon/channels/inbox/providers/slack.ts

@@ -0,0 +1,264 @@
+// ---------------------------------------------------------------------------
+// Slack inbound adapter.
+//
+// Transport note (contract fidelity): the daemon-handoff checklist names the
+// Slack Events API / RTM for DM polling. Those are push transports (HTTP event
+// callbacks / a persistent websocket) 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 websocket/event-callback
+// would require an inbound HTTP endpoint or a long-lived socket the poller
+// neither owns nor supervises. We therefore satisfy the DM-polling goal over
+// the supported request/response surface (the Slack Web API), which the Events
+// API itself documents as the canonical pull-based equivalent for reading DM
+// history on an interval:
+//   conversations.list (types=im)  -> open DM channels (cursor-paginated)
+//   conversations.history          -> recent messages per DM
+//   auth.test                      -> our own user id (for @-mention class.);
+//                                     id is digested, never emitted raw.
+//
+// Credential: surfaces.slack.botToken (xoxb-...). 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 SLACK_API = 'https://slack.com/api';
+export const SLACK_PROVIDER_ID = 'slack';
+export const SLACK_CREDENTIAL_KEY = 'surfaces.slack.botToken';
+
+interface SlackConversationsListResponse {
+  ok: boolean;
+  error?: string;
+  channels?: Array<{ id: string; user?: string }>;
+  response_metadata?: { next_cursor?: string };
+}
+
+interface SlackAuthTestResponse {
+  ok: boolean;
+  error?: string;
+  user_id?: string;
+}
+
+interface SlackReaction {
+  name?: string;
+  count?: number;
+  users?: string[];
+}
+
+interface SlackMessage {
+  type?: string;
+  subtype?: string;
+  user?: string;
+  bot_id?: string;
+  text?: string;
+  ts?: string; // "1700000000.000200"
+  thread_ts?: string;
+  reactions?: SlackReaction[];
+}
+
+interface SlackHistoryResponse {
+  ok: boolean;
+  error?: string;
+  messages?: SlackMessage[];
+  has_more?: boolean;
+  response_metadata?: { next_cursor?: string };
+}
+
+/**
+ * Classify a Slack 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
+ *               user id is selfUserId) 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 (text contains `<@SELF>`)
+ *   - thread:   a threaded reply (thread_ts present and not the root ts)
+ *   - dm:       a plain direct message
+ * Reaction takes precedence over mention/thread because a reaction is the most
+ * specific inbound signal; mention outranks thread/dm.
+ */
+function classifySlackKind(
+  msg: SlackMessage,
+  selfUserId: string | undefined,
+): InboundChannelItem['kind'] {
+  if (
+    selfUserId &&
+    msg.user === selfUserId &&
+    Array.isArray(msg.reactions) &&
+    msg.reactions.length > 0
+  ) {
+    return 'reaction';
+  }
+  if (selfUserId && typeof msg.text === 'string' && msg.text.includes(`<@${selfUserId}>`)) {
+    return 'mention';
+  }
+  if (msg.thread_ts && msg.thread_ts !== msg.ts) return 'thread';
+  return 'dm';
+}
+
+/** Slack ts ("1700000000.000200") -> Unix ms. */
+function tsToMs(ts: string | undefined): number {
+  if (!ts) return 0;
+  const seconds = Number.parseFloat(ts);
+  return Number.isFinite(seconds) ? Math.round(seconds * 1000) : 0;
+}
+
+async function slackGet<T>(
+  token: string,
+  method: string,
+  params: Record<string, string>,
+): Promise<T> {
+  const url = new URL(`${SLACK_API}/${method}`);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Slack ${method} HTTP ${res.status}`);
+  }
+  return (await res.json()) as T;
+}
+
+export function createSlackAdapter(ctx: AdapterContext): InboundProviderAdapter {
+  return {
+    id: SLACK_PROVIDER_ID,
+    pollIntervalMs: POLL_CADENCE_MS.realtime,
+    async poll(opts: ProviderPollOptions): Promise<ProviderPollResult> {
+      let token: string | null;
+      try {
+        token = await ctx.credentials.resolveConfigSecret(SLACK_CREDENTIAL_KEY);
+      } catch (error) {
+        return unavailable(`credential lookup failed: ${errMsg(error)}`);
+      }
+      if (!token || token.trim().length === 0) {
+        return unavailable('missing surfaces.slack.botToken');
+      }
+      if (!token.startsWith('xoxb-') && !token.startsWith('xoxp-')) {
+        return unavailable('surfaces.slack.botToken is not a valid Slack bot/user token');
+      }
+
+      // Resolve our own user id so we can distinguish @-mentions of us from
+      // plain DMs. Best-effort: a failure here only means mentions are not
+      // separately classified, it never fails the provider.
+      let selfUserId: string | undefined;
+      try {
+        const auth = await slackGet<SlackAuthTestResponse>(token, 'auth.test', {});
+        if (auth.ok && auth.user_id) selfUserId = auth.user_id;
+      } catch (error) {
+        ctx.logger.warn('slack auth.test failed; mentions will not be classified', {
+          error: errMsg(error),
+        });
+      }
+
+      try {
+        // Page through ALL open DM channels. conversations.list returns at most
+        // `limit` channels per page and a response_metadata.next_cursor when more
+        // remain; without following the cursor, accounts with >100 open DMs would
+        // silently lose every channel past the first page. MAX_LIST_PAGES bounds
+        // the loop so a misbehaving cursor can never spin forever.
+        const MAX_LIST_PAGES = 50;
+        const channels: Array<{ id: string; user?: string }> = [];
+        let cursor: string | undefined;
+        for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
+          const list = await slackGet<SlackConversationsListResponse>(token, 'conversations.list', {
+            types: 'im',
+            limit: '100',
+            ...(cursor ? { cursor } : {}),
+          });
+          if (!list.ok) {
+            return unavailable(`conversations.list: ${list.error ?? 'unknown_error'}`);
+          }
+          if (list.channels) channels.push(...list.channels);
+          const next = list.response_metadata?.next_cursor;
+          if (!next || next.length === 0) break;
+          cursor = next;
+        }
+        const oldest = opts.since ? (opts.since / 1000).toFixed(6) : undefined;
+        // Page through conversations.history per channel: a single call returns at
+        // most `limit` (<=50) messages and sets has_more + a next_cursor when a DM
+        // accrued more new messages than fit in one page. Without following the
+        // cursor a busy DM would silently drop everything past the first page.
+        // MAX_HISTORY_PAGES bounds the loop so a misbehaving cursor cannot spin.
+        const MAX_HISTORY_PAGES = 20;
+        const items: InboundChannelItem[] = [];
+        channelLoop: for (const channel of channels) {
+          if (items.length >= opts.limit) break;
+          let historyCursor: string | undefined;
+          for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
+            const history = await slackGet<SlackHistoryResponse>(token, 'conversations.history', {
+              channel: channel.id,
+              limit: String(Math.min(opts.limit, 50)),
+              ...(oldest ? { oldest } : {}),
+              ...(historyCursor ? { cursor: historyCursor } : {}),
+            });
+            if (!history.ok) {
+              // Skip this DM but keep going; do not fail the whole provider.
+              ctx.logger.warn('slack conversations.history failed', {
+                channel: channel.id,
+                error: history.error,
+              });
+              continue channelLoop;
+            }
+            for (const msg of history.messages ?? []) {
+              if (items.length >= opts.limit) break;
+              if (msg.subtype === 'bot_message' || msg.bot_id) continue;
+              const senderId = msg.user ?? channel.user ?? channel.id;
+              const receivedAt = tsToMs(msg.ts);
+              if (opts.since && receivedAt <= opts.since) continue;
+              // 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'). Slack user ids
+              // (U...) are unique within a workspace, and the item.id / provider
+              // fields already namespace by provider.
+              const fromDigest = digestSender(senderId);
+              const kind = classifySlackKind(msg, selfUserId);
+              const item: InboundChannelItem = {
+                id: `slack:${channel.id}:${msg.ts ?? String(receivedAt)}`,
+                provider: SLACK_PROVIDER_ID,
+                kind,
+                fromDigest,
+                subjectPreview: toSubjectPreview(`Direct message`),
+                bodyPreview: toBodyPreview(msg.text),
+                receivedAt,
+                unread: true,
+              };
+              const routeId = await resolveRouteId(ctx, SLACK_PROVIDER_ID, fromDigest, kind);
+              if (routeId) item.routeId = routeId;
+              items.push(item);
+            }
+            // Advance to the next history page only while the channel reported
+            // more messages AND we still have item budget left.
+            const nextHistory = history.response_metadata?.next_cursor;
+            if (!history.has_more || !nextHistory || nextHistory.length === 0) break;
+            if (items.length >= opts.limit) break;
+            historyCursor = nextHistory;
+          }
+        }
+        return { items, state: items.length > 0 ? 'ready' : 'empty' };
+      } catch (error) {
+        return unavailable(errMsg(error));
+      }
+    },
+  };
+}
+
+function unavailable(error: string): ProviderPollResult {
+  return { items: [], state: 'unavailable', error };
+}
+
+function errMsg(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,247 @@
+// ---------------------------------------------------------------------------
+// Surface register: `channels.inbox.list`.
+//
+// register(ctx) =>
+//   1. registers built-in provider adapter factories (slack/discord/email)
+//   2. constructs adapters with a daemon credential store
+//   3. opens the inbox cursor store and seeds an initial poll
+//   4. starts the per-provider polling loops
+//   5. publishes the read-only `channels.inbox.list` operator method
+//   6. returns an Unregister that stops the poller, closes the store, and
+//      removes the method.
+//
+// `channels.inbox.list` is READ-ONLY (no confirm). It reads the persisted feed
+// (filtered by providers/limit/since) and reports per-provider state from the
+// live poller status. nextSince advances monotonically (max receivedAt in the
+// returned window, never below the requested `since`).
+// ---------------------------------------------------------------------------
+
+import {
+  createDaemonCredentialStore,
+  declareOperatorMethod,
+} from '../../operator/index.ts';
+import type {
+  OperatorContext,
+  OperatorInvocation,
+  SurfaceRegister,
+  Unregister,
+} from '../../operator/index.ts';
+import {
+  buildAdapters,
+  registerAdapterFactory,
+  type AdapterContext,
+  type InboundChannelItem,
+  type RouteResolver,
+} from './provider-adapter.ts';
+import { InboxCursorStore } from './cursor-store.ts';
+import { InboundPoller, type ProviderStatus } from './poller.ts';
+import { createSlackAdapter, SLACK_PROVIDER_ID } from './providers/slack.ts';
+import { createDiscordAdapter, DISCORD_PROVIDER_ID } from './providers/discord.ts';
+import { createEmailAdapter, EMAIL_PROVIDER_ID } from './providers/email.ts';
+
+export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';
+export const INBOX_LIST_SCOPES = ['channels:inbox:read'];
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+export interface InboxListInput {
+  providers?: string[];
+  limit?: number;
+  since?: number;
+}
+
+export interface InboxProviderReport {
+  id: string;
+  state: ProviderStatus['state'];
+  itemCount: number;
+  error?: string;
+}
+
+export interface InboxListOutput {
+  items: InboundChannelItem[];
+  nextSince: number;
+  providers: InboxProviderReport[];
+}
+
+export interface RegisterInboxOptions {
+  /** Route resolver injected by the routing surface (optional, best-effort). */
+  resolveRouteId?: RouteResolver;
+  /** Override the cursor-store filename (tests). */
+  storeFileName?: string;
+  /** Skip the initial seed poll (tests that drive polling manually). */
+  skipInitialPoll?: boolean;
+  /** Replace the default built-in adapter set (tests). */
+  registerBuiltins?: boolean;
+}
+
+function registerBuiltinAdapters(): void {
+  registerAdapterFactory(SLACK_PROVIDER_ID, (ctx) => createSlackAdapter(ctx));
+  registerAdapterFactory(DISCORD_PROVIDER_ID, (ctx) => createDiscordAdapter(ctx));
+  registerAdapterFactory(EMAIL_PROVIDER_ID, (ctx) => createEmailAdapter(ctx));
+}
+
+const INBOX_LIST_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['items', 'nextSince', 'providers'],
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: [
+          'id', 'provider', 'kind', 'fromDigest',
+          'subjectPreview', 'bodyPreview', 'receivedAt', 'unread',
+        ],
+        properties: {
+          id: { type: 'string' },
+          provider: { type: 'string' },
+          kind: { type: 'string', enum: ['dm', 'thread', 'mention', 'reaction'] },
+          fromDigest: { type: 'string' },
+          subjectPreview: { type: 'string', maxLength: 200 },
+          bodyPreview: { type: 'string', maxLength: 500 },
+          routeId: { type: 'string' },
+          receivedAt: { type: 'number' },
+          unread: { type: 'boolean' },
+          triageScore: { type: 'number' },
+          triageTags: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+    nextSince: { type: 'number' },
+    providers: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['id', 'state', 'itemCount'],
+        properties: {
+          id: { type: 'string' },
+          state: { type: 'string', enum: ['ready', 'unavailable', 'empty'] },
+          itemCount: { type: 'number' },
+          error: { type: 'string' },
+        },
+      },
+    },
+  },
+};
+
+const INBOX_LIST_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    providers: { type: 'array', items: { type: 'string' } },
+    limit: { type: 'number', minimum: 1, maximum: MAX_LIMIT },
+    since: { type: 'number', minimum: 0 },
+  },
+};
+
+function normalizeInput(body: unknown): { providers?: string[]; limit: number; since?: number } {
+  const input = (body ?? {}) as InboxListInput;
+  const providers = Array.isArray(input.providers)
+    ? input.providers.filter((p): p is string => typeof p === 'string' && p.length > 0)
+    : undefined;
+  let limit = typeof input.limit === 'number' && Number.isFinite(input.limit)
+    ? Math.floor(input.limit)
+    : DEFAULT_LIMIT;
+  limit = Math.min(Math.max(1, limit), MAX_LIMIT);
+  const since = typeof input.since === 'number' && Number.isFinite(input.since) && input.since >= 0
+    ? Math.floor(input.since)
+    : undefined;
+  return {
+    ...(providers && providers.length > 0 ? { providers } : {}),
+    limit,
+    ...(since !== undefined ? { since } : {}),
+  };
+}
+
+/**
+ * Register the inbox surface. Returns an Unregister that tears down the poller,
+ * closes the store, and removes the operator method.
+ */
+export function registerInboxMethods(
+  ctx: OperatorContext,
+  options: RegisterInboxOptions = {},
+): Unregister {
+  if (options.registerBuiltins !== false) {
+    registerBuiltinAdapters();
+  }
+
+  const credentials = createDaemonCredentialStore(ctx.secrets);
+  const adapterContext: AdapterContext = {
+    credentials,
+    logger: ctx.logger,
+    ...(options.resolveRouteId ? { resolveRouteId: options.resolveRouteId } : {}),
+  };
+  const adapters = buildAdapters(adapterContext);
+  const store = new InboxCursorStore(ctx.workingDirectory, options.storeFileName);
+  const poller = new InboundPoller({ adapters, store, logger: ctx.logger });
+
+  // Async bootstrap: init store, seed one poll, start loops. Failures are
+  // logged but never thrown out of register() — the method still serves the
+  // (possibly empty) persisted feed and reports provider states.
+  const ready: Promise<void> = (async () => {
+    await store.init();
+    if (!options.skipInitialPoll) {
+      await poller.pollOnce();
+    }
+    poller.start();
+  })().catch((error: unknown) => {
+    ctx.logger.error('inbox surface bootstrap failed', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  });
+
+  const handler = async (
+    invocation: OperatorInvocation<InboxListInput>,
+  ): Promise<InboxListOutput> => {
+    await ready;
+    const { providers, limit, since } = normalizeInput(invocation.body);
+    const items = store.listItems({ ...(providers ? { providers } : {}), ...(since !== undefined ? { since } : {}), limit });
+    const maxReceived = store.maxReceivedAt(providers);
+    const nextSince = Math.max(since ?? 0, maxReceived);
+    const statuses = poller.snapshotStatuses(providers);
+    const reports: InboxProviderReport[] = statuses.map((status) => ({
+      id: status.id,
+      state: status.state,
+      itemCount: status.itemCount,
+      ...(status.error ? { error: status.error } : {}),
+    }));
+    return { items, nextSince, providers: reports };
+  };
+
+  const unregisterMethod = declareOperatorMethod<InboxListInput, InboxListOutput>(
+    ctx,
+    {
+      id: INBOX_LIST_METHOD_ID,
+      title: 'List inbound channel items',
+      description:
+        'Aggregated, deduplicated inbound feed (DMs/threads/mentions) across '
+        + 'configured providers. Read-only; advances a monotonic nextSince cursor.',
+      category: 'channels',
+      source: 'daemon',
+      access: 'operator',
+      transport: ['ws', 'internal'],
+      scopes: INBOX_LIST_SCOPES,
+      effect: 'read-only',
+      confirm: false,
+      inputSchema: INBOX_LIST_INPUT_SCHEMA,
+      outputSchema: INBOX_LIST_OUTPUT_SCHEMA,
+    },
+    handler,
+  );
+
+  return () => {
+    try {
+      unregisterMethod();
+    } finally {
+      poller.stop();
+      void store.close();
+    }
+  };
+}
+
+/**
+ * SurfaceRegister contract entry point. Integration wires the inbox surface by
+ * calling this from its surface bootstrap (the same mechanism every other
+ * daemon surface uses, e.g. routing/triage), retaining the returned Unregister
+ * for teardown. This is the production caller of `registerInboxMethods`.
+ */
+export const register: SurfaceRegister = (ctx) => registerInboxMethods(ctx);

package/src/daemon/channels/routing/inbox-bridge.ts

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// Inbox <-> Routing resolver bridge.
+//
+// The inbox provider adapters expose a best-effort `RouteResolver` seam
+// (provider-adapter.ts): given an inbound item's `{ provider, fromDigest, kind }`
+// they ask "which daemon route binding handles this item?" and stamp the answer
+// onto `item.routeId` when one resolves. The routing control plane owns the
+// channel<->profile bindings and exposes a `RoutingResolver` whose
+// `getProfileForChannel(surfaceKind, routeId?)` applies the canonical resolution
+// order:
+//
+//   1. exact     — surfaceKind AND routeId both match
+//   2. surface   — surfaceKind matches, route has no routeId
+//   3. wildcard  — a route with surfaceKind === 'any' (no routeId)
+//
+// This module bridges the two shapes. The bridge maps an inbound item's
+// `provider` to the routing `surfaceKind` and forwards an optional `routeId`
+// refinement; `fromDigest`/`kind` are NOT used as routing keys (the routing
+// store is keyed by surfaceKind + optional routeId only, never by sender digest
+// or message kind — see RoutingChannelRoute). When no binding matches the
+// resolver returns null and the bridge yields `undefined`, so the adapter falls
+// back to leaving the item unrouted (offline/default behaviour intact). The
+// bridge NEVER throws: route-util.ts already swallows resolver errors, and the
+// underlying resolver is a pure in-memory lookup.
+// ---------------------------------------------------------------------------
+
+import type { RouteResolver } from '../inbox/provider-adapter.ts';
+import type { RoutingResolver } from './routing-resolver.ts';
+
+/**
+ * Optional input fields the bridge consults for routeId refinement. The
+ * published {@link RouteResolver} input does not currently carry a routeId, so
+ * surface-only / wildcard resolution is the effective path today; should the
+ * inbox seam grow a routeId (e.g. a Slack channel id or email mailbox tag) the
+ * bridge will pass it through to enable exact (surfaceKind+routeId) matches
+ * without any further change here.
+ */
+type RouteResolverInput = Parameters<RouteResolver>[0] & { routeId?: unknown };
+
+/**
+ * Build a {@link RouteResolver} backed by the routing surface's
+ * {@link RoutingResolver}. Maps `provider -> surfaceKind` and forwards an
+ * optional `routeId` refinement, then applies the canonical
+ * exact > surface-only > wildcard resolution order via
+ * `getProfileForChannel`. Returns the resolved profileId (the daemon route
+ * binding) or `undefined` when nothing matches.
+ */
+export function createInboxRouteResolver(resolver: RoutingResolver): RouteResolver {
+  return (input: RouteResolverInput): string | undefined => {
+    const surfaceKind = typeof input.provider === 'string' ? input.provider : '';
+    if (surfaceKind.length === 0) return undefined;
+    const routeId = typeof input.routeId === 'string' && input.routeId.length > 0 ? input.routeId : undefined;
+    // getProfileForChannel applies exact (surfaceKind+routeId) > surface-only >
+    // wildcard ('any') and returns null when no assignment matches.
+    const profileId = resolver.getProfileForChannel(surfaceKind, routeId);
+    return profileId ?? undefined;
+  };
+}

package/src/daemon/channels/routing/index.ts

@@ -0,0 +1,39 @@
+// Channel-to-Profile Routing Control Plane — surface barrel.
+//
+// Integration wires this surface by calling `register(ctx)` (or
+// `registerRoutingMethods(ctx)` when it needs the returned store/resolver).
+// The inbox surface reuses `resolveProfile` / `createRoutingResolver` for
+// identical online/offline routing resolution.
+
+export { register, registerRoutingMethods } from './register.ts';
+export type {
+  RoutingRegistration,
+  RoutingListInput,
+  RoutingListOutput,
+  RoutingAssignInput,
+  RoutingAssignOutput,
+  RoutingDeleteInput,
+  RoutingDeleteOutput,
+} from './register.ts';
+
+export {
+  RouteStore,
+  parseChannelId,
+  buildChannelId,
+} from './route-store.ts';
+export type {
+  RoutingChannelRoute,
+  ParsedChannelId,
+  RouteUpsertInput,
+  RouteUpsertResult,
+  RouteListFilter,
+} from './route-store.ts';
+
+export {
+  resolveProfile,
+  createRoutingResolver,
+  WILDCARD_SURFACE,
+} from './routing-resolver.ts';
+export type { RoutingResolver } from './routing-resolver.ts';
+
+export { createInboxRouteResolver } from './inbox-bridge.ts';