@pellux/goodvibes-tui 0.25.0 → 0.27.0

package/src/daemon/handlers/inbox/index.ts

@@ -0,0 +1,211 @@
+// ---------------------------------------------------------------------------
+// Inbox surface: attaches the HOST handler to the SDK-registered
+// `channels.inbox.list` gateway descriptor.
+//
+// The SDK already declares the method id, input schema, output schema, scopes
+// (read:channels) and HTTP binding (GET /api/channels/inbox). This module does
+// NOT re-declare any of that — it looks the descriptor up via the catalog and
+// attaches an implementation with `registerCatalogHandler` ({ replace: true }).
+//
+// register(ctx, routing) =>
+//   1. registers built-in provider adapter factories (slack/discord/email)
+//   2. constructs adapters with the daemon credential store + a route resolver
+//      bridged from the routing surface (best-effort, never throws)
+//   3. opens the inbox cursor store and seeds an initial poll
+//   4. starts the per-provider polling loops
+//   5. attaches the read-only `channels.inbox.list` handler (no confirm)
+//   6. returns an Unregister that detaches the handler, stops the poller, and
+//      closes the store.
+//
+// The handler reads the persisted feed (filtered by provider/limit/since) and
+// maps the daemon-internal item shape onto the SDK CHANNEL_INBOX_ITEM_SCHEMA
+// wire shape. The redacted `fromDigest` is the only sender value emitted (as
+// `from`); raw sender ids and unredacted bodies never leave the daemon. The
+// monotonic cursor advances to max(receivedAt) in the returned window.
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../context.ts';
+import type { Unregister } from '../register.ts';
+import { registerCatalogHandler } from '../register.ts';
+import type { RoutingRegistration } from '../index.ts';
+import {
+  buildAdapters,
+  registerAdapterFactory,
+  type AdapterContext,
+  type InboundChannelItem,
+  type RouteResolver,
+} from './provider-adapter.ts';
+import { InboxCursorStore } from './cursor-store.ts';
+import { InboundPoller } 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';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+/** SDK `channels.inbox.list` input (single optional provider per the schema). */
+export interface InboxListInput {
+  provider?: string;
+  limit?: number;
+  since?: number;
+}
+
+/** One item in the SDK CHANNEL_INBOX_ITEM_SCHEMA wire shape. */
+export interface ChannelInboxItem {
+  id: string;
+  provider: string;
+  kind: string;
+  /** Redacted sender token (sha256First, 16 hex). Never the raw id. */
+  from: string;
+  subject?: string;
+  bodyPreview: string;
+  receivedAt: number;
+  unread: boolean;
+  routeId?: string;
+}
+
+/** SDK `channels.inbox.list` output (objectSchema: items/total/truncated/cursor?). */
+export interface InboxListOutput {
+  items: ChannelInboxItem[];
+  total: number;
+  truncated: boolean;
+  cursor?: string;
+}
+
+export interface RegisterInboxOptions {
+  /** Override the cursor-store filename (tests). */
+  storeFileName?: string;
+  /** Skip the initial seed poll (tests that drive polling manually). */
+  skipInitialPoll?: boolean;
+  /** Register the built-in slack/discord/email adapters (default true). */
+  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));
+}
+
+function normalizeInput(body: unknown): { providers?: string[]; limit: number; since?: number } {
+  const input = (body ?? {}) as InboxListInput;
+  const provider = typeof input.provider === 'string' && input.provider.length > 0
+    ? input.provider
+    : 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 {
+    ...(provider ? { providers: [provider] } : {}),
+    limit,
+    ...(since !== undefined ? { since } : {}),
+  };
+}
+
+/** Map a daemon-internal item onto the SDK CHANNEL_INBOX_ITEM_SCHEMA wire shape. */
+function toWireItem(item: InboundChannelItem): ChannelInboxItem {
+  const wire: ChannelInboxItem = {
+    id: item.id,
+    provider: item.provider,
+    kind: item.kind,
+    from: item.fromDigest,
+    bodyPreview: item.bodyPreview,
+    receivedAt: item.receivedAt,
+    unread: item.unread,
+  };
+  if (item.subjectPreview.length > 0) wire.subject = item.subjectPreview;
+  if (item.routeId != null) wire.routeId = item.routeId;
+  return wire;
+}
+
+/**
+ * Bridge the routing surface's profile resolver into the adapter `RouteResolver`
+ * seam. Resolution is by provider surface (best-effort wildcard); a resolved
+ * profile id is surfaced as the item's routeId binding. Never throws.
+ */
+function routeResolverFromRouting(routing: RoutingRegistration): RouteResolver {
+  return ({ provider }) => {
+    try {
+      return routing.resolveProfileId(provider) ?? undefined;
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Register the inbox surface. Attaches the `channels.inbox.list` handler to the
+ * SDK catalog and returns an Unregister that detaches it, stops the poller, and
+ * closes the store.
+ */
+export function registerInboxMethods(
+  ctx: HandlerContext,
+  routing?: RoutingRegistration,
+  options: RegisterInboxOptions = {},
+): Unregister {
+  if (options.registerBuiltins !== false) {
+    registerBuiltinAdapters();
+  }
+
+  const adapterContext: AdapterContext = {
+    credentials: ctx.credentials,
+    logger: ctx.logger,
+    ...(routing ? { resolveRouteId: routeResolverFromRouting(routing) } : {}),
+  };
+  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 handler still serves the
+  // (possibly empty) persisted feed.
+  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: summarizeError(error),
+    });
+  });
+
+  const unregisterMethod = registerCatalogHandler<InboxListInput, InboxListOutput>(
+    ctx.catalog,
+    INBOX_LIST_METHOD_ID,
+    async (invocation) => {
+      await ready;
+      const { providers, limit, since } = normalizeInput(invocation.body);
+      const internalItems = store.listItems({
+        ...(providers ? { providers } : {}),
+        ...(since !== undefined ? { since } : {}),
+        limit,
+      });
+      const items = internalItems.map(toWireItem);
+      const total = store.countItems(providers);
+      const truncated = internalItems.length >= limit && total > internalItems.length;
+      const maxReceived = store.maxReceivedAt(providers);
+      const nextSince = Math.max(since ?? 0, maxReceived);
+      const output: InboxListOutput = { items, total, truncated };
+      if (nextSince > 0) output.cursor = String(nextSince);
+      return output;
+    },
+  );
+
+  return () => {
+    try {
+      unregisterMethod();
+    } finally {
+      poller.stop();
+      void store.close();
+    }
+  };
+}

package/src/daemon/{channels → handlers}/inbox/mapping.ts

@@ -3,23 +3,25 @@
 //
 // Rules (from the handoff contract):
 //   - fromDigest  = sha256First(senderExternalId, 16)   (never the raw id)
-//                   (16 hex chars == the first 8 bytes of the SHA-256 digest;
-//                    handoff acceptance checklist: 'first 16 hex chars')
 //   - bodyPreview = plain-text, PII-stripped, truncated to 500 chars
 //   - subjectPreview <= 200 chars
 // These are pure and deterministic so they are unit-testable in isolation.
 // ---------------------------------------------------------------------------
 
-import { sha256First } from '../../operator/index.ts';
+import { createHash } from 'node:crypto';
 
 export const SUBJECT_PREVIEW_MAX = 200;
 export const BODY_PREVIEW_MAX = 500;
 
+/** First `hexChars` hex chars of the SHA-256 digest of `input` (utf-8). */
+export function sha256First(input: string, hexChars: number): string {
+  const digest = createHash('sha256').update(input, 'utf-8').digest('hex');
+  return digest.slice(0, Math.max(0, hexChars));
+}
+
 /**
  * Digest a sender's external id to a stable 16-hex-char token (the first 8
- * bytes of the SHA-256 digest). The handoff wire-shape note's 'SHA-256 first-8'
- * refers to those 8 bytes; the acceptance checklist states it as 'first 16 hex
- * chars'. Both describe the same value emitted here.
+ * bytes of the SHA-256 digest). The raw id is never emitted.
  */
 export function digestSender(senderExternalId: string): string {
   return sha256First(senderExternalId, 16);

package/src/daemon/{channels → handlers}/inbox/poller.ts

@@ -5,7 +5,7 @@
 // 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)
+//   3. dedups + persists items into the cursor store (upsert)
 //   4. advances the cursor monotonically to max(receivedAt)
 //   5. records the last per-provider state for channels.inbox.list to report
 //
@@ -16,7 +16,8 @@
 
 import type { InboundProviderAdapter, ProviderState } from './provider-adapter.ts';
 import type { InboxCursorStore } from './cursor-store.ts';
-import type { OperatorLogger } from '../../operator/index.ts';
+import type { HandlerLogger } from '../context.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 export interface ProviderStatus {
   id: string;
@@ -29,7 +30,7 @@ export interface ProviderStatus {
 export interface PollerOptions {
   adapters: Map<string, InboundProviderAdapter>;
   store: InboxCursorStore;
-  logger: OperatorLogger;
+  logger: HandlerLogger;
   /** Max items fetched per provider per tick. */
   perProviderLimit?: number;
   /** Inject a timer factory for tests (defaults to global setInterval). */
@@ -42,7 +43,7 @@ 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 logger: HandlerLogger;
   private readonly perProviderLimit: number;
   private readonly setIntervalImpl: typeof setInterval;
   private readonly clearIntervalImpl: typeof clearInterval;
@@ -115,7 +116,7 @@ export class InboundPoller {
         lastPolledAt: Date.now(),
       });
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = summarizeError(error);
       this.logger.warn('inbound poll failed', { provider: id, error: message });
       this.setStatus(id, {
         id,

package/src/daemon/{channels → handlers}/inbox/provider-adapter.ts

@@ -12,10 +12,15 @@
 // 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';
+import type { DaemonCredentialStore } from '../credentials.ts';
+import type { HandlerLogger } from '../context.ts';
 
-/** Wire-shape inbound item as published by `channels.inbox.list`. */
+/**
+ * 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;
@@ -23,8 +28,7 @@ export interface InboundChannelItem {
   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).
+   * first 8 bytes of the SHA-256 digest.
    */
   fromDigest: string;
   /** <= 200 chars, safe for display. */
@@ -60,7 +64,7 @@ export interface ProviderPollOptions {
 /** Context handed to every adapter at construction time. */
 export interface AdapterContext {
   readonly credentials: DaemonCredentialStore;
-  readonly logger: OperatorLogger;
+  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 /
@@ -70,8 +74,8 @@ export interface AdapterContext {
 }
 
 /**
- * Best-effort route resolution seam. The routing surface (concurrent work)
- * injects its `resolveProfile`-backed implementation. Until then it is
+ * 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: {
@@ -127,8 +131,8 @@ export function registeredProviderIds(): string[] {
 
 /**
  * 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.
+ * `requested` is undefined/empty). Unknown ids are dropped: the returned map
+ * only contains known providers.
  */
 export function buildAdapters(
   ctx: AdapterContext,

package/src/daemon/{channels → handlers}/inbox/providers/discord.ts

@@ -7,8 +7,7 @@
 // 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
+// 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
@@ -32,6 +31,7 @@ import type {
 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.
@@ -67,10 +67,10 @@ interface DiscordMessage {
 /**
  * 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.
+ *               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
@@ -201,10 +201,9 @@ export function createDiscordAdapter(ctx: AdapterContext): InboundProviderAdapte
               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.
+              // 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 = {
@@ -249,5 +248,5 @@ function unavailable(error: string): ProviderPollResult {
 }
 
 function errMsg(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return summarizeError(error);
 }

package/src/daemon/{channels → handlers}/inbox/providers/email.ts

@@ -25,6 +25,7 @@ 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';
@@ -147,5 +148,5 @@ function unavailable(error: string): ProviderPollResult {
 }
 
 function errMsg(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return summarizeError(error);
 }

package/src/daemon/{channels → handlers}/inbox/providers/imap-client.ts

@@ -72,7 +72,7 @@ export class ImapClient {
     await this.command(`LOGIN ${user} ${pass}`);
   }
 
-  /** SELECT a mailbox (default INBOX). Returns the reported message count. */
+  /** SELECT a mailbox (default INBOX). */
   async select(mailbox = 'INBOX'): Promise<void> {
     await this.command(`SELECT ${quote(mailbox)}`);
   }

package/src/daemon/{channels → handlers}/inbox/providers/route-util.ts

@@ -1,8 +1,9 @@
 // Shared best-effort route resolution wrapper used by all adapters.
-// Swallows resolver failures (routing is an optional, concurrent surface) so a
-// route lookup can never crash a provider poll.
+// 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';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 export async function resolveRouteId(
   ctx: AdapterContext,
@@ -16,7 +17,7 @@ export async function resolveRouteId(
   } catch (error) {
     ctx.logger.warn('route resolution failed', {
       provider,
-      error: error instanceof Error ? error.message : String(error),
+      error: summarizeError(error),
     });
     return undefined;
   }

package/src/daemon/{channels → handlers}/inbox/providers/slack.ts

@@ -16,7 +16,7 @@
 //   auth.test                      -> our own user id (for @-mention class.);
 //                                     id is digested, never emitted raw.
 //
-// Credential: surfaces.slack.botToken (xoxb-...). Missing => 'unavailable'.
+// Credential: surfaces.slack.botToken. Missing => 'unavailable'.
 // Cadence: 30s (realtime tier).
 // ---------------------------------------------------------------------------
 
@@ -30,6 +30,7 @@ import type {
 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 SLACK_API = 'https://slack.com/api';
 export const SLACK_PROVIDER_ID = 'slack';
@@ -76,15 +77,14 @@ interface SlackHistoryResponse {
 /**
  * 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.
+ *               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 takes precedence over mention/thread because a reaction is the most
- * specific inbound signal; mention outranks thread/dm.
+ * Reaction outranks mention which outranks thread/dm (most-specific first).
  */
 function classifySlackKind(
   msg: SlackMessage,
@@ -219,10 +219,9 @@ export function createSlackAdapter(ctx: AdapterContext): InboundProviderAdapter
               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.
+              // 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 = {
@@ -260,5 +259,5 @@ function unavailable(error: string): ProviderPollResult {
 }
 
 function errMsg(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return summarizeError(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,
+  };
+}