@pellux/goodvibes-tui 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -99,7 +99,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.33.38",
+    "@pellux/goodvibes-sdk": "0.34.0",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/daemon/{calendar → handlers/calendar}/caldav-client.ts

@@ -1,8 +1,8 @@
-// CalDAV client for the calendar operator surface.
+// CalDAV client for the calendar handler surface.
 //
 // Authenticates to the user's CalDAV endpoint using credentials resolved from
 // the daemon credential store (config keys under `surfaces.calendar.*`). It
-// implements the CalDAV/WebDAV verbs the operator methods need:
+// implements the CalDAV/WebDAV verbs the gateway methods need:
 //   - REPORT (calendar-query)  -> list / get events
 //   - PUT                      -> create / import events
 //   - REPORT (multiget) / GET  -> export a collection
@@ -16,9 +16,9 @@
 //   * Event hrefs are returned to callers as opaque relative identifiers, never
 //     as fully-qualified authenticated URLs.
 
-import type { OperatorContext } from '../operator/types.ts';
-import { OperatorError } from '../operator/types.ts';
-import { createDaemonCredentialStore } from '../operator/credential-store.ts';
+import { HandlerError } from '../errors.ts';
+import type { HandlerContext } from '../context.ts';
+import type { DaemonCredentialStore } from '../credentials.ts';
 import {
   generateCalendar,
   generateICS,
@@ -112,12 +112,15 @@ export interface CalDavClient {
   exportIcs(opts: { calendarId?: string; from?: string; to?: string }): Promise<ExportResult>;
 }
 
+/** Subset of the handler context the CalDAV config resolver needs. */
+export type CalDavConfigContext = Pick<HandlerContext, 'configManager' | 'credentials'>;
+
 // ---------------------------------------------------------------------------
 // Config resolution
 // ---------------------------------------------------------------------------
 
 function readConfigString(
-  ctx: Pick<OperatorContext, 'configManager'>,
+  ctx: Pick<HandlerContext, 'configManager'>,
   key: string,
 ): string | undefined {
   const value = ctx.configManager.get(key as never);
@@ -147,16 +150,17 @@ function parseCollectionMap(raw: string | undefined): Record<string, string> {
  * Resolve the full CalDAV configuration from config + credential store.
  * The password is resolved from the daemon credential store — either as a
  * goodvibes://secrets/ reference stored in config, or the config-key-derived
- * secret. Throws OperatorError when the surface is not configured.
+ * secret. Throws HandlerError when the surface is not configured. The resolved
+ * password is held only in memory and never returned to callers.
  */
 export async function resolveCalDavConfig(
-  ctx: Pick<OperatorContext, 'configManager' | 'secrets'>,
+  ctx: CalDavConfigContext,
 ): Promise<CalDavConfig> {
-  const credentials = createDaemonCredentialStore(ctx.secrets);
+  const credentials: DaemonCredentialStore = ctx.credentials;
   const baseUrl = readConfigString(ctx, CFG_URL);
   const username = readConfigString(ctx, CFG_USER);
   if (!baseUrl || !username) {
-    throw new OperatorError(
+    throw new HandlerError(
       'CalDAV is not configured. Set surfaces.calendar.caldavUrl and surfaces.calendar.caldavUser.',
       'CALENDAR_NOT_CONFIGURED',
       412,
@@ -174,7 +178,7 @@ export async function resolveCalDavConfig(
     password = await credentials.resolveConfigSecret(CFG_PASSWORD);
   }
   if (!password) {
-    throw new OperatorError(
+    throw new HandlerError(
       'CalDAV password is not available in the credential store.',
       'CALENDAR_CREDENTIALS_MISSING',
       412,
@@ -204,7 +208,7 @@ function joinUrl(base: string, segment: string): string {
 /** Extract the scheme+host origin from an absolute URL (no trailing slash). */
 export function originOf(url: string): string {
   const match = /^(https?:\/\/[^/]+)/i.exec(url.trim());
-  return match ? match[1] : stripTrailingSlash(url);
+  return match ? match[1]! : stripTrailingSlash(url);
 }
 
 /**
@@ -227,7 +231,7 @@ function resolveCollectionUrl(baseUrl: string, path: string): string {
 export function toRelativeHref(href: string): string {
   const trimmed = href.trim();
   const schemeMatch = /^https?:\/\/[^/]+(\/.*)$/i.exec(trimmed);
-  if (schemeMatch) return schemeMatch[1];
+  if (schemeMatch) return schemeMatch[1]!;
   return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
 
@@ -302,7 +306,7 @@ function propfindCalendarsBody(): string {
 function toCalDavStamp(iso: string): string {
   const date = new Date(iso);
   if (Number.isNaN(date.getTime())) {
-    throw new OperatorError(`Invalid date range value: ${iso}`, 'CALENDAR_BAD_RANGE', 400);
+    throw new HandlerError(`Invalid date range value: ${iso}`, 'CALENDAR_BAD_RANGE', 400);
   }
   const pad = (n: number): string => (n < 10 ? `0${n}` : String(n));
   return (
@@ -353,7 +357,7 @@ export function parseMultiStatus(xml: string): MultiStatusEntry[] {
   const responseRe = /<(?:[a-zA-Z0-9]+:)?response(?:\s[^>]*)?>([\s\S]*?)<\/(?:[a-zA-Z0-9]+:)?response>/gi;
   let match: RegExpExecArray | null;
   while ((match = responseRe.exec(xml)) !== null) {
-    const block = match[1];
+    const block = match[1]!;
     const hrefRaw = tagContent(block, 'href');
     if (!hrefRaw) continue;
     const href = decodeXmlEntities(hrefRaw.trim());
@@ -425,18 +429,18 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
       // (e.g. "getaddrinfo ENOTFOUND cal.example.com") leaks the CalDAV
       // hostname/URL into caller-visible output (importIcs errors[]).
       // Never include creds/URL/host or raw fetch detail.
-      throw new OperatorError('CalDAV request failed: network error.', 'CALENDAR_NETWORK_ERROR', 502);
+      throw new HandlerError('CalDAV request failed: network error.', 'CALENDAR_NETWORK_ERROR', 502);
     }
     const text = await response.text();
     if (!response.ok) {
-      // Map auth/permission/not-found to operator errors. Never include creds/URL.
+      // Map auth/permission/not-found to handler errors. Never include creds/URL.
       const status = response.status;
       const code = status === 401 || status === 403
         ? 'CALENDAR_AUTH_FAILED'
         : status === 404
           ? 'CALENDAR_NOT_FOUND'
           : 'CALENDAR_REQUEST_FAILED';
-      throw new OperatorError(
+      throw new HandlerError(
         `CalDAV server returned HTTP ${status}.`,
         code,
         status >= 400 && status < 500 ? status : 502,
@@ -472,7 +476,7 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
         const rel = toRelativeHref(entry.href);
         // Derive a stable logical id from the last path segment.
         const segments = rel.split('/').filter((s) => s.length > 0);
-        const logical = segments.length > 0 ? decodeURIComponent(segments[segments.length - 1]) : config.defaultCalendarId;
+        const logical = segments.length > 0 ? decodeURIComponent(segments[segments.length - 1]!) : config.defaultCalendarId;
         if (seen.has(logical)) continue;
         seen.add(logical);
         calendars.push({ calendarId: logical, displayName: entry.displayName ?? logical });
@@ -509,7 +513,7 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
           single = await request(resourceUrl, 'GET', undefined, { Depth: '0' });
         } catch (error) {
           // A 404 maps to "not found"; any other failure propagates.
-          if (error instanceof OperatorError && error.code === 'CALENDAR_NOT_FOUND') {
+          if (error instanceof HandlerError && error.code === 'CALENDAR_NOT_FOUND') {
             return null;
           }
           throw error;
@@ -517,7 +521,7 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
         const parsed = parseICS(single.text);
         if (parsed.length === 0) return null;
         const relHref = toRelativeHref(eventId);
-        return { ...parsed[0], href: relHref, calendarId: id };
+        return { ...parsed[0]!, href: relHref, calendarId: id };
       }
 
       // Strategy 2 — bare UID: ask the server for ONLY the matching resource via
@@ -566,7 +570,7 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
       const id = calendarId && calendarId.length > 0 ? calendarId : config.defaultCalendarId;
       const parsed = parseICS(icsContent);
       if (parsed.length === 0) {
-        throw new OperatorError('No VEVENT components found in .ics content.', 'CALENDAR_EMPTY_ICS', 400);
+        throw new HandlerError('No VEVENT components found in .ics content.', 'CALENDAR_EMPTY_ICS', 400);
       }
       const collectionUrl = collectionUrlFor(id);
       const eventIds: string[] = [];
@@ -582,7 +586,7 @@ export function createCalDavClient(options: CreateCalDavClientOptions): CalDavCl
           eventIds.push(toRelativeHref(joinUrl(collectionPathOrRoot(collectionUrl, config.baseUrl), resourcePath)));
           imported += 1;
         } catch (error) {
-          const message = error instanceof OperatorError ? error.message : error instanceof Error ? error.message : String(error);
+          const message = error instanceof HandlerError ? error.message : error instanceof Error ? error.message : String(error);
           errors.push(`${uid}: ${message}`);
         }
       }
@@ -646,7 +650,7 @@ function parsedToGenerateInput(event: ParsedICalEvent, uid: string): GenerateICa
     description: event.description,
     location: event.location,
     // Re-emit attendees by their raw value so import preserves the original
-    // addressing; display-name-only redaction applies to operator responses,
+    // addressing; display-name-only redaction applies to handler responses,
     // not to server-side payloads.
     attendees: event.attendees.map((a) => a.rawValue),
     organizer: event.organizerRaw,

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

@@ -0,0 +1,316 @@
+// Handler registration for the CalDAV calendar surface.
+//
+// Attaches host handlers to the five SDK-registered calendar gateway method
+// descriptors BY ID (the SDK auto-registers them with handler:undefined). No
+// method id, descriptor, or schema is authored here — `registerCatalogHandlers`
+// looks up the canonical descriptor via `catalog.get(id)` and re-registers it
+// with the wrapped handler. Method IDs handled (exactly):
+//   calendar.events.list   read:calendar   no confirm
+//   calendar.events.get    read:calendar   no confirm
+//   calendar.events.create write:calendar  confirm:true + explicitUserRequest
+//   calendar.ics.import    write:calendar  confirm:true + explicitUserRequest
+//   calendar.ics.export    read:calendar   no confirm
+//
+// SECURITY: CalDAV credentials and authenticated URLs NEVER appear in any
+// response. `calendarId` is a logical id. Attendees are surfaced as display
+// names only (no raw addresses). Outputs are stripped to exactly the SDK output
+// schema fields (the SDK schemas set additionalProperties:false).
+
+import { HandlerError } from '../errors.ts';
+import type { HandlerContext } from '../context.ts';
+import {
+  registerCatalogHandlers,
+  type CatalogHandlerEntry,
+  type TypedHandler,
+  type Unregister,
+} from '../register.ts';
+import {
+  createCalDavClient,
+  resolveCalDavConfig,
+  type CalDavClient,
+  type CalDavConfigContext,
+  type CalDavEvent,
+} from './caldav-client.ts';
+
+/**
+ * The exact set of method IDs this surface publishes — a single source of truth
+ * for the calendar capability set, consumed by integration wiring and tests.
+ */
+export const CALENDAR_METHOD_IDS = [
+  'calendar.events.list',
+  'calendar.events.get',
+  'calendar.events.create',
+  'calendar.ics.import',
+  'calendar.ics.export',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Client factory injection (real client by default; tests inject a stub).
+// ---------------------------------------------------------------------------
+
+export type CalDavClientFactory = (ctx: CalDavConfigContext) => Promise<CalDavClient>;
+
+const realClientFactory: CalDavClientFactory = async (ctx) => {
+  const config = await resolveCalDavConfig(ctx);
+  return createCalDavClient({ config });
+};
+
+export interface RegisterCalendarOptions {
+  /** Override the CalDAV client factory (for tests). */
+  clientFactory?: CalDavClientFactory;
+}
+
+// ---------------------------------------------------------------------------
+// Input validation helpers
+// ---------------------------------------------------------------------------
+
+function asRecord(body: unknown): Record<string, unknown> {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    throw new HandlerError('Request body must be an object.', 'CALENDAR_BAD_INPUT', 400);
+  }
+  return body as Record<string, unknown>;
+}
+
+function optionalString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw new HandlerError(`Field '${key}' must be a string.`, 'CALENDAR_BAD_INPUT', 400);
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function requiredString(record: Record<string, unknown>, key: string): string {
+  const value = optionalString(record, key);
+  if (value === undefined) {
+    throw new HandlerError(`Field '${key}' is required.`, 'CALENDAR_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+function optionalNumber(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new HandlerError(`Field '${key}' must be a number.`, 'CALENDAR_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+function optionalStringArray(record: Record<string, unknown>, key: string): string[] | undefined {
+  const value = record[key];
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new HandlerError(`Field '${key}' must be an array of strings.`, 'CALENDAR_BAD_INPUT', 400);
+  }
+  return (value as string[]).map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
+function validateIsoDate(value: string, field: string): string {
+  if (Number.isNaN(new Date(value).getTime())) {
+    throw new HandlerError(`Field '${field}' must be a valid ISO-8601 date.`, 'CALENDAR_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Response mapping (credential-free, PII-stripped, schema-exact)
+// ---------------------------------------------------------------------------
+
+/**
+ * Wire shape for `calendar.events.list` items — EXACTLY the SDK
+ * CALENDAR_EVENT_SUMMARY_SCHEMA (additionalProperties:false). Optional fields
+ * are present only when populated. `calendarId`/`allDay`/organizer are NOT in
+ * the SDK schema and are intentionally dropped.
+ */
+export interface CalendarEventSummary {
+  id: string;
+  title: string;
+  start: string;
+  end: string;
+  location?: string;
+  description?: string;
+  attendees?: string[];
+}
+
+function displayAttendees(event: CalDavEvent): string[] {
+  return event.attendees.map((a) => a.displayName).filter((name) => name.length > 0);
+}
+
+function toSummary(event: CalDavEvent): CalendarEventSummary {
+  const attendees = displayAttendees(event);
+  const summary: CalendarEventSummary = {
+    id: event.href || event.uid,
+    title: event.summary,
+    start: event.start,
+    end: event.end,
+  };
+  if (event.location !== undefined) summary.location = event.location;
+  if (event.description !== undefined) summary.description = event.description;
+  if (attendees.length > 0) summary.attendees = attendees;
+  return summary;
+}
+
+/**
+ * Wire shape for `calendar.events.get` — EXACTLY the SDK
+ * CALENDAR_EVENT_DETAIL_SCHEMA (additionalProperties:false), returned directly
+ * (not wrapped). `uid` carries the raw iCalendar UID; attendees are display
+ * names only.
+ */
+export interface CalendarEventDetail {
+  id: string;
+  uid: string;
+  title: string;
+  start: string;
+  end: string;
+  location?: string;
+  description?: string;
+  attendees?: string[];
+  recurrence?: string;
+}
+
+function toDetail(event: CalDavEvent): CalendarEventDetail {
+  const attendees = displayAttendees(event);
+  const detail: CalendarEventDetail = {
+    id: event.href || event.uid,
+    uid: event.uid,
+    title: event.summary,
+    start: event.start,
+    end: event.end,
+  };
+  if (event.location !== undefined) detail.location = event.location;
+  if (event.description !== undefined) detail.description = event.description;
+  if (attendees.length > 0) detail.attendees = attendees;
+  if (event.recurrence !== undefined) detail.recurrence = event.recurrence;
+  return detail;
+}
+
+// ---------------------------------------------------------------------------
+// Handler bodies
+// ---------------------------------------------------------------------------
+
+interface ListBody {
+  calendarId?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+}
+
+interface GetBody {
+  eventId: string;
+  calendarId?: string;
+}
+
+interface ExportBody {
+  calendarId?: string;
+  from?: string;
+  to?: string;
+}
+
+/**
+ * Register all five calendar handlers against the SDK catalog held by `ctx`.
+ * Returns a single Unregister that detaches them in reverse order.
+ */
+export function registerCalendarMethods(
+  ctx: HandlerContext,
+  options: RegisterCalendarOptions = {},
+): Unregister {
+  const clientFactory = options.clientFactory ?? realClientFactory;
+  const getClient = (): Promise<CalDavClient> => clientFactory(ctx);
+
+  const listHandler: TypedHandler<unknown, { events: CalendarEventSummary[] }> = async ({ body }) => {
+    const record = body === undefined || body === null ? {} : asRecord(body);
+    const input: ListBody = {
+      calendarId: optionalString(record, 'calendarId'),
+      from: optionalString(record, 'from'),
+      to: optionalString(record, 'to'),
+      limit: optionalNumber(record, 'limit'),
+    };
+    if (input.from) validateIsoDate(input.from, 'from');
+    if (input.to) validateIsoDate(input.to, 'to');
+    const limit = input.limit !== undefined ? Math.max(1, Math.min(200, Math.floor(input.limit))) : 20;
+    const client = await getClient();
+    const events = await client.listEvents({ ...input, limit });
+    return { events: events.map(toSummary) };
+  };
+
+  const getHandler: TypedHandler<unknown, CalendarEventDetail> = async ({ body }) => {
+    const record = asRecord(body);
+    const input: GetBody = {
+      eventId: requiredString(record, 'eventId'),
+      calendarId: optionalString(record, 'calendarId'),
+    };
+    const client = await getClient();
+    const event = await client.getEvent(input.eventId, input.calendarId);
+    if (!event) {
+      throw new HandlerError(`Event not found: ${input.eventId}`, 'CALENDAR_NOT_FOUND', 404);
+    }
+    return toDetail(event);
+  };
+
+  const createHandler: TypedHandler<unknown, { eventId: string; uid: string; createdAt: string }> = async ({ body }) => {
+    const record = asRecord(body);
+    const title = requiredString(record, 'title');
+    const start = validateIsoDate(requiredString(record, 'start'), 'start');
+    const end = validateIsoDate(requiredString(record, 'end'), 'end');
+    if (new Date(end).getTime() < new Date(start).getTime()) {
+      throw new HandlerError("Field 'end' must not be before 'start'.", 'CALENDAR_BAD_INPUT', 400);
+    }
+    const client = await getClient();
+    const created = await client.createEvent({
+      title,
+      start,
+      end,
+      description: optionalString(record, 'description'),
+      attendees: optionalStringArray(record, 'attendees'),
+      location: optionalString(record, 'location'),
+      calendarId: optionalString(record, 'calendarId'),
+    });
+    return { eventId: created.eventId, uid: created.uid, createdAt: created.createdAt };
+  };
+
+  const importHandler: TypedHandler<unknown, { imported: number; eventIds: string[]; errors: string[] }> = async ({ body }) => {
+    const record = asRecord(body);
+    const icsContent = requiredString(record, 'icsContent');
+    const calendarId = optionalString(record, 'calendarId');
+    const client = await getClient();
+    return client.importIcs(icsContent, calendarId);
+  };
+
+  const exportHandler: TypedHandler<unknown, { icsContent: string; eventCount: number }> = async ({ body }) => {
+    const record = body === undefined || body === null ? {} : asRecord(body);
+    const input: ExportBody = {
+      calendarId: optionalString(record, 'calendarId'),
+      from: optionalString(record, 'from'),
+      to: optionalString(record, 'to'),
+    };
+    if (input.from) validateIsoDate(input.from, 'from');
+    if (input.to) validateIsoDate(input.to, 'to');
+    const client = await getClient();
+    return client.exportIcs(input);
+  };
+
+  const entries: CatalogHandlerEntry[] = [
+    { id: 'calendar.events.list', handler: listHandler as TypedHandler<unknown, unknown> },
+    { id: 'calendar.events.get', handler: getHandler as TypedHandler<unknown, unknown> },
+    {
+      id: 'calendar.events.create',
+      handler: createHandler as TypedHandler<unknown, unknown>,
+      options: { confirm: true },
+    },
+    {
+      id: 'calendar.ics.import',
+      handler: importHandler as TypedHandler<unknown, unknown>,
+      options: { confirm: true },
+    },
+    { id: 'calendar.ics.export', handler: exportHandler as TypedHandler<unknown, unknown> },
+  ];
+
+  return registerCatalogHandlers(ctx.catalog, entries);
+}
+
+/** SurfaceRegister-compatible entry point used by the daemon composition root. */
+export function registerCalendar(ctx: HandlerContext): Unregister {
+  return registerCalendarMethods(ctx);
+}

package/src/daemon/handlers/context.ts

@@ -0,0 +1,29 @@
+/**
+ * Host-facing context passed to every surface register function. Replaces the
+ * former OperatorContext. It carries the SDK gateway catalog (handlers attach
+ * to it), the daemon credential store, a read-only slice of the config manager,
+ * resolved directories, and a logger. No SDK descriptor or schema is declared
+ * here — the catalog type is re-exported through the contracts seam.
+ */
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { GatewayMethodCatalog } from './contracts.ts';
+import type { DaemonCredentialStore } from './credentials.ts';
+import type { Unregister } from './register.ts';
+
+export interface HandlerLogger {
+  info(message: string, meta?: unknown): void;
+  warn(message: string, meta?: unknown): void;
+  error(message: string, meta?: unknown): void;
+}
+
+export interface HandlerContext {
+  readonly catalog: GatewayMethodCatalog;
+  readonly credentials: DaemonCredentialStore;
+  readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+  readonly logger: HandlerLogger;
+}
+
+/** Every surface module exports a register function of this shape. */
+export type SurfaceRegister = (ctx: HandlerContext) => Unregister;

package/src/daemon/handlers/contracts.ts

@@ -0,0 +1,77 @@
+/**
+ * Single SDK-contract import seam for the daemon handler layer.
+ *
+ * Every other module under `src/daemon/handlers/` imports SDK contract
+ * identifiers from HERE and nowhere else. Concentrating the SDK imports in one
+ * concrete-submodule module keeps the rest of the layer free of barrel cycles
+ * and guarantees the host NEVER re-declares an SDK id, descriptor, or schema —
+ * it only attaches handlers to the descriptors the SDK already registered.
+ */
+
+// Catalog + invocation contract types (concrete control-plane subpath, not a project barrel).
+export type {
+  GatewayMethodCatalog,
+  GatewayMethodDescriptor,
+  GatewayMethodInvocation,
+  GatewayMethodInvocationContext,
+  GatewayMethodHandler,
+} from '@pellux/goodvibes-sdk/platform/control-plane';
+
+// Channel domain types reused in handler signatures (read-only SDK interfaces; never re-declared).
+export type {
+  ChannelIdentity,
+  ChannelResolvedTarget,
+  ChannelAccountRecord,
+} from '@pellux/goodvibes-sdk/platform/channels';
+
+/**
+ * Per-peer authentication envelope passed to peer-scoped remote routes.
+ *
+ * The daemon-sdk ships `RemotePeerAuth` only as an UNEXPORTED local alias
+ * inside `@pellux/goodvibes-daemon-sdk/remote-routes` (it is `unknown` there),
+ * so it cannot be re-exported. We mirror that exact shape here for the host
+ * implementation. This is an implementable runtime contract, not a method
+ * descriptor or schema — declaring it does not violate the no-re-declaration
+ * rule for catalog methods.
+ */
+export type RemotePeerAuth = unknown;
+
+/**
+ * Remote distributed-runtime route service the HOST must implement and supply
+ * as `RuntimeServices.distributedRuntime`. The SDK facade injects the instance
+ * into `DaemonRemoteRouteContext.distributedRuntime` so the published
+ * `remote.peers.*` HTTP routes can dispatch to it.
+ *
+ * The daemon-sdk declares this interface locally in
+ * `@pellux/goodvibes-daemon-sdk/remote-routes` but does NOT export it (the
+ * module ends with `export {}`), so it cannot be imported. This declaration
+ * mirrors the SDK's exact structural shape (17 methods, verbatim signatures)
+ * so a host implementation is assignable to the SDK's context field. The SDK
+ * ships no docker/ssh/cloud backend — the host owns the implementation.
+ */
+export interface DistributedRuntimeRouteService {
+  listPairRequests(): unknown;
+  approvePairRequest(requestId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  rejectPairRequest(requestId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  listPeers(): unknown;
+  rotatePeerToken(peerId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  revokePeerToken(peerId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  disconnectPeer(peerId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  listWork(): unknown;
+  invokePeer(input: Record<string, unknown>): Promise<unknown>;
+  cancelWork(workId: string, input: Record<string, unknown>): Promise<unknown | null>;
+  getNodeHostContract(): unknown;
+  requestPairing(input: Record<string, unknown>): Promise<unknown>;
+  verifyPairRequest(
+    requestId: string,
+    challenge: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown | null>;
+  heartbeatPeer(auth: RemotePeerAuth, input: Record<string, unknown>): Promise<unknown>;
+  claimWork(auth: RemotePeerAuth, input: Record<string, unknown>): Promise<unknown>;
+  completeWork(
+    auth: RemotePeerAuth,
+    workId: string,
+    input: Record<string, unknown>,
+  ): Promise<unknown | null>;
+}