@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/inbox/providers/imap-client.ts

@@ -0,0 +1,300 @@
+// ---------------------------------------------------------------------------
+// Minimal, dependency-free IMAPS client (RFC 3501 subset) over node:tls.
+//
+// Implements exactly what the inbound poller needs:
+//   LOGIN, SELECT, UID SEARCH (SINCE / ALL), UID FETCH (ENVELOPE + body peek),
+//   LOGOUT. No external npm dependency — uses node:tls (Bun-compatible).
+//
+// This is intentionally conservative: line-buffered tagged-command protocol,
+// per-command timeout, and a hard cap on response size to avoid unbounded
+// memory growth from a hostile/large mailbox.
+// ---------------------------------------------------------------------------
+
+import { connect as tlsConnect } from 'node:tls';
+import type { TLSSocket } from 'node:tls';
+
+export interface ImapConfig {
+  host: string;
+  port: number; // 993 for IMAPS
+  user: string;
+  password: string;
+  /** Per-command timeout in ms. */
+  timeoutMs?: number;
+  /** Hard cap on bytes buffered per command (defense against huge fetches). */
+  maxResponseBytes?: number;
+}
+
+export interface ImapEnvelope {
+  uid: number;
+  from: string; // raw From header value (digested by the adapter)
+  subject: string;
+  date: number; // Unix ms (0 when unparseable)
+  seen: boolean;
+  bodyPreview: string; // first text fragment, raw (sanitized by the adapter)
+}
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+export class ImapClient {
+  private socket: TLSSocket | null = null;
+  private tagCounter = 0;
+  private buffer = '';
+  private readonly cfg: Required<ImapConfig>;
+
+  constructor(cfg: ImapConfig) {
+    this.cfg = {
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      maxResponseBytes: DEFAULT_MAX_RESPONSE_BYTES,
+      ...cfg,
+    };
+  }
+
+  async connect(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const socket = tlsConnect(
+        { host: this.cfg.host, port: this.cfg.port, servername: this.cfg.host },
+        () => {
+          resolve();
+        },
+      );
+      socket.setEncoding('utf-8');
+      socket.once('error', reject);
+      this.socket = socket;
+    });
+    // Consume the server greeting (untagged * OK ...).
+    await this.readUntil((chunk) => /\r?\n/.test(chunk), 'greeting');
+  }
+
+  async login(): Promise<void> {
+    const user = quote(this.cfg.user);
+    const pass = quote(this.cfg.password);
+    await this.command(`LOGIN ${user} ${pass}`);
+  }
+
+  /** SELECT a mailbox (default INBOX). */
+  async select(mailbox = 'INBOX'): Promise<void> {
+    await this.command(`SELECT ${quote(mailbox)}`);
+  }
+
+  /** UID SEARCH; returns matching UIDs. `since` filters by internal date. */
+  async searchUids(since?: number): Promise<number[]> {
+    const criteria = since ? `SINCE ${imapDate(since)}` : 'ALL';
+    const lines = await this.command(`UID SEARCH ${criteria}`);
+    const uids: number[] = [];
+    for (const line of lines) {
+      const match = /^\* SEARCH(.*)$/i.exec(line.trim());
+      if (match) {
+        for (const tok of match[1]!.trim().split(/\s+/)) {
+          const n = Number.parseInt(tok, 10);
+          if (Number.isFinite(n)) uids.push(n);
+        }
+      }
+    }
+    return uids;
+  }
+
+  /**
+   * UID FETCH envelope + flags + a small text body peek for the given uids.
+   * Returns one ImapEnvelope per uid that parsed successfully.
+   */
+  async fetchEnvelopes(uids: readonly number[]): Promise<ImapEnvelope[]> {
+    if (uids.length === 0) return [];
+    const set = uids.join(',');
+    // BODY.PEEK[HEADER.FIELDS (...)] avoids setting \Seen; TEXT peek for preview.
+    const lines = await this.command(
+      `UID FETCH ${set} (UID FLAGS INTERNALDATE `
+        + `BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)] `
+        + `BODY.PEEK[TEXT]<0.600>)`,
+    );
+    return parseFetchResponse(lines.join('\r\n'));
+  }
+
+  async logout(): Promise<void> {
+    if (!this.socket) return;
+    try {
+      await this.command('LOGOUT');
+    } catch {
+      // ignore logout failures
+    }
+  }
+
+  close(): void {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Protocol plumbing
+  // -------------------------------------------------------------------------
+
+  private nextTag(): string {
+    this.tagCounter += 1;
+    return `A${this.tagCounter.toString().padStart(4, '0')}`;
+  }
+
+  private requireSocket(): TLSSocket {
+    if (!this.socket) throw new Error('IMAP socket not connected');
+    return this.socket;
+  }
+
+  /** Send a tagged command and collect all response lines up to the tagged OK. */
+  private async command(text: string): Promise<string[]> {
+    const tag = this.nextTag();
+    const socket = this.requireSocket();
+    socket.write(`${tag} ${text}\r\n`);
+    const taggedOk = new RegExp(`^${tag} (OK|NO|BAD)\\b`, 'm');
+    const raw = await this.readUntil((buf) => taggedOk.test(buf), text);
+    const lines = raw.split(/\r?\n/);
+    const statusLine = lines.find((l) => new RegExp(`^${tag} `).test(l)) ?? '';
+    const status = /^A\d+ (OK|NO|BAD)/.exec(statusLine)?.[1];
+    if (status !== 'OK') {
+      throw new Error(`IMAP command failed: ${redactCommand(text)} -> ${statusLine.trim()}`);
+    }
+    return lines.filter((l) => l.startsWith('*'));
+  }
+
+  /** Read from the socket until `predicate(buffer)` is true or timeout. */
+  private readUntil(predicate: (buf: string) => boolean, label: string): Promise<string> {
+    const socket = this.requireSocket();
+    return new Promise<string>((resolve, reject) => {
+      const onData = (chunk: string): void => {
+        this.buffer += chunk;
+        if (this.buffer.length > this.cfg.maxResponseBytes) {
+          cleanup();
+          reject(new Error(`IMAP response exceeded ${this.cfg.maxResponseBytes} bytes (${label})`));
+          return;
+        }
+        if (predicate(this.buffer)) {
+          const out = this.buffer;
+          this.buffer = '';
+          cleanup();
+          resolve(out);
+        }
+      };
+      const onError = (err: Error): void => {
+        cleanup();
+        reject(err);
+      };
+      const onClose = (): void => {
+        cleanup();
+        reject(new Error(`IMAP connection closed during ${label}`));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`IMAP timeout after ${this.cfg.timeoutMs}ms (${label})`));
+      }, this.cfg.timeoutMs);
+      const cleanup = (): void => {
+        clearTimeout(timer);
+        socket.off('data', onData);
+        socket.off('error', onError);
+        socket.off('close', onClose);
+      };
+      socket.on('data', onData);
+      socket.on('error', onError);
+      socket.on('close', onClose);
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure parsers (exported for unit testing)
+// ---------------------------------------------------------------------------
+
+/** Quote an IMAP astring, escaping backslashes and double quotes. */
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** Never echo a LOGIN password in an error message. */
+function redactCommand(text: string): string {
+  return /^LOGIN\b/i.test(text) ? 'LOGIN <redacted>' : text;
+}
+
+/** Format a Unix-ms timestamp as an IMAP date (dd-Mon-yyyy). */
+export function imapDate(ms: number): string {
+  const d = new Date(ms);
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${day}-${months[d.getUTCMonth()]}-${d.getUTCFullYear()}`;
+}
+
+const HEADER_FROM_RE = /^From:\s*(.*)$/im;
+const HEADER_SUBJECT_RE = /^Subject:\s*(.*)$/im;
+const HEADER_DATE_RE = /^Date:\s*(.*)$/im;
+
+/**
+ * Parse a UID FETCH response block into envelopes. Robust to interleaving and
+ * partial fields; entries that lack a UID are skipped.
+ */
+export function parseFetchResponse(raw: string): ImapEnvelope[] {
+  const envelopes: ImapEnvelope[] = [];
+  // Split on each "* <n> FETCH (" boundary.
+  const blocks = raw.split(/\* \d+ FETCH \(/i).slice(1);
+  for (const block of blocks) {
+    const uidMatch = /UID (\d+)/i.exec(block);
+    if (!uidMatch) continue;
+    const uid = Number.parseInt(uidMatch[1]!, 10);
+    const seen = /FLAGS \([^)]*\\Seen/i.test(block);
+
+    // Header literal: BODY[HEADER.FIELDS (...)] {n}\r\n<header bytes>
+    const headerText = extractLiteral(block, /BODY\[HEADER\.FIELDS[^\]]*\]/i);
+    const bodyText = extractLiteral(block, /BODY\[TEXT\](?:<\d+(?:\.\d+)?>)?/i);
+
+    const from = HEADER_FROM_RE.exec(headerText)?.[1]?.trim() ?? '';
+    const subject = decodeHeader(HEADER_SUBJECT_RE.exec(headerText)?.[1]?.trim() ?? '');
+    const dateRaw = HEADER_DATE_RE.exec(headerText)?.[1]?.trim() ?? '';
+    const parsedDate = dateRaw ? Date.parse(dateRaw) : NaN;
+
+    envelopes.push({
+      uid,
+      from,
+      subject,
+      date: Number.isFinite(parsedDate) ? parsedDate : 0,
+      seen,
+      bodyPreview: bodyText,
+    });
+  }
+  return envelopes;
+}
+
+/**
+ * Extract a literal `{n}\r\n<bytes>` that follows a section header matched by
+ * `sectionRe`. Returns the literal content (n bytes) or ''.
+ */
+function extractLiteral(block: string, sectionRe: RegExp): string {
+  const sectionMatch = sectionRe.exec(block);
+  if (!sectionMatch) return '';
+  const after = block.slice(sectionMatch.index + sectionMatch[0].length);
+  const litMatch = /^\s*\{(\d+)\}\r?\n/.exec(after);
+  if (!litMatch) {
+    // Quoted-string form: BODY[...] "value"
+    const q = /^\s*"((?:[^"\\]|\\.)*)"/.exec(after);
+    return q ? q[1]!.replace(/\\"/g, '"') : '';
+  }
+  const n = Number.parseInt(litMatch[1]!, 10);
+  const start = litMatch.index + litMatch[0].length;
+  return after.slice(start, start + n);
+}
+
+/** Decode RFC 2047 encoded-word subjects (UTF-8 B/Q) best-effort. */
+export function decodeHeader(value: string): string {
+  return value.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g, (_m, _charset, enc, text) => {
+    try {
+      if (enc.toUpperCase() === 'B') {
+        return Buffer.from(text, 'base64').toString('utf-8');
+      }
+      // Q-encoding: _ -> space, =XX -> byte
+      const replaced = String(text)
+        .replace(/_/g, ' ')
+        .replace(/=([0-9A-Fa-f]{2})/g, (_s: string, hex: string) =>
+          String.fromCharCode(Number.parseInt(hex, 16)),
+        );
+      return replaced;
+    } catch {
+      return text;
+    }
+  });
+}

package/src/daemon/handlers/inbox/providers/route-util.ts

@@ -0,0 +1,23 @@
+// Shared best-effort route resolution wrapper used by all adapters.
+// Swallows resolver failures (routing is an optional, concurrently-wired
+// surface) so a route lookup can never crash a provider poll.
+
+import type { AdapterContext, InboundChannelItem } from '../provider-adapter.ts';
+
+export async function resolveRouteId(
+  ctx: AdapterContext,
+  provider: string,
+  fromDigest: string,
+  kind: InboundChannelItem['kind'],
+): Promise<string | undefined> {
+  if (!ctx.resolveRouteId) return undefined;
+  try {
+    return (await ctx.resolveRouteId({ provider, fromDigest, kind })) ?? undefined;
+  } catch (error) {
+    ctx.logger.warn('route resolution failed', {
+      provider,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+}

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

@@ -0,0 +1,262 @@
+// ---------------------------------------------------------------------------
+// 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. 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. 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 outranks mention which outranks thread/dm (most-specific first).
+ */
+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. 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/handlers/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Composition root for the daemon handler layer — the only module that
+ * `src/runtime/services.ts` imports. It assembles every surface (routing,
+ * inbox+triage, drafts, calendar, email, remote) onto the SDK gateway catalog
+ * and returns a single teardown plus the cross-surface handles the runtime
+ * needs (routing resolver, the remote `DistributedRuntimeRouteService` the SDK
+ * facade injects, and the `remote.peers.invoke` dispatch adapter).
+ *
+ * Surfaces are provided by the caller as `SurfaceRegister` functions so this
+ * foundation module stays free of import cycles and does not author any SDK
+ * descriptor or schema. Registration order is fixed; teardown runs in reverse.
+ */
+import type { DistributedRuntimeRouteService } from './contracts.ts';
+import type { HandlerContext, SurfaceRegister } from './context.ts';
+import type { Unregister } from './register.ts';
+
+/** Routing surface handle: teardown plus the resolver other surfaces consume. */
+export interface RoutingRegistration {
+  readonly unregister: Unregister;
+  /** Resolve an inbound channel target to a profile id (exact → wildcard → null). */
+  readonly resolveProfileId: (surfaceKind: string, routeId?: string) => string | null;
+}
+
+/** Adapter the runtime wires into the published `remote.peers.invoke` route. */
+export interface RemoteInvokeAdapter {
+  invoke(input: Record<string, unknown>): Promise<unknown>;
+}
+
+/** Remote surface handle: the host service the SDK facade injects + its teardown. */
+export interface RemoteSurfaceRegistration {
+  readonly unregister: Unregister;
+  readonly service: DistributedRuntimeRouteService;
+  readonly dispatch: RemoteInvokeAdapter;
+}
+
+/** Aggregate result returned to the runtime for teardown and cross-surface wiring. */
+export interface DaemonHandlerSurfaces {
+  readonly unregister: Unregister;
+  readonly routing: RoutingRegistration;
+  readonly remoteSurface: { readonly service: DistributedRuntimeRouteService };
+  readonly remoteDispatch: RemoteInvokeAdapter;
+}
+
+/**
+ * The surface implementations the runtime supplies. Each builds its stores and
+ * attaches handlers to the SDK catalog via `registerCatalogHandler(s)`.
+ *
+ * Order of composition (and reverse teardown) is enforced by
+ * `registerDaemonHandlers`: routing → inbox(+triage) → drafts → calendar →
+ * email → remote.
+ */
+export interface DaemonHandlerSurfaceProviders {
+  /** channels.routing.* — returns the resolver consumed by the inbox surface. */
+  readonly registerRouting: (ctx: HandlerContext) => RoutingRegistration;
+  /** channels.inbox.list (triage-decorated) + inbox.triage.* (daemon-internal). */
+  readonly registerInbox: (ctx: HandlerContext, routing: RoutingRegistration) => Unregister;
+  /** channels.drafts.* */
+  readonly registerDrafts: SurfaceRegister;
+  /** calendar.* */
+  readonly registerCalendar: SurfaceRegister;
+  /** email.* */
+  readonly registerEmail: SurfaceRegister;
+  /** remote.peers.* — supplies the host DistributedRuntimeRouteService + dispatch adapter. */
+  readonly registerRemote: (ctx: HandlerContext) => RemoteSurfaceRegistration;
+}
+
+/**
+ * Compose all daemon handler surfaces onto the gateway catalog held by `ctx`.
+ * Returns a single teardown (reverse order, best-effort) and the handles the
+ * runtime must expose: the routing registration, the remote service the SDK
+ * facade injects into `DaemonRemoteRouteContext.distributedRuntime`, and the
+ * remote invoke dispatch adapter.
+ */
+export function registerDaemonHandlers(
+  ctx: HandlerContext,
+  providers: DaemonHandlerSurfaceProviders,
+): DaemonHandlerSurfaces {
+  const teardowns: Unregister[] = [];
+
+  const routing = providers.registerRouting(ctx);
+  teardowns.push(routing.unregister);
+
+  teardowns.push(providers.registerInbox(ctx, routing));
+  teardowns.push(providers.registerDrafts(ctx));
+  teardowns.push(providers.registerCalendar(ctx));
+  teardowns.push(providers.registerEmail(ctx));
+
+  const remote = providers.registerRemote(ctx);
+  teardowns.push(remote.unregister);
+
+  const unregister: Unregister = () => {
+    for (let i = teardowns.length - 1; i >= 0; i -= 1) {
+      try {
+        teardowns[i]!();
+      } catch (error) {
+        ctx.logger.warn('daemon handler surface teardown failed', { error });
+      }
+    }
+  };
+
+  return {
+    unregister,
+    routing,
+    remoteSurface: { service: remote.service },
+    remoteDispatch: remote.dispatch,
+  };
+}