@pellux/goodvibes-tui 0.24.0 → 0.25.0

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

@@ -0,0 +1,296 @@
+import {
+  declareOperatorMethods,
+  OperatorError,
+  type OperatorContext,
+  type OperatorHandler,
+  type OperatorMethodDescriptor,
+  type SurfaceRegister,
+  type Unregister,
+} from '../../operator/index.ts';
+import { RouteStore, type RoutingChannelRoute } from './route-store.ts';
+import { createRoutingResolver, type RoutingResolver } from './routing-resolver.ts';
+
+// ---------------------------------------------------------------------------
+// Wire contracts (request/response bodies) for the channels.routing.* methods.
+//
+// These interfaces and the JSON Schemas below mirror the handoff's literal
+// Input/Output blocks exactly. Per the handoff's "Confirmation / Effect
+// Semantics" note, `channels.routing.assign` and `channels.routing.delete` are
+// control-plane mutations that additionally require confirmation. That
+// confirmation is NOT part of the documented Input body shape: it is a
+// framework confirm-guard envelope flag (`confirm: true` on the raw request
+// body, plus `explicitUserRequest` in the call metadata) enforced by
+// `assertConfirmed` inside `declareOperatorMethods` when `descriptor.confirm`
+// is set. We therefore keep `confirm` out of the advertised contract here and
+// rely on the framework guard, so the wire Input stays a faithful match for the
+// handoff rather than a strict superset.
+// ---------------------------------------------------------------------------
+
+export interface RoutingListInput {
+  profileId?: string;
+  surfaceKind?: string;
+}
+export interface RoutingListOutput {
+  routes: RoutingChannelRoute[];
+}
+
+export interface RoutingAssignInput {
+  channelId: string;
+  profileId: string;
+  label?: string;
+}
+export interface RoutingAssignOutput {
+  assignmentId: string;
+  channelId: string;
+  profileId: string;
+  created: boolean;
+}
+
+export interface RoutingDeleteInput {
+  assignmentId: string;
+}
+export interface RoutingDeleteOutput {
+  deleted: boolean;
+}
+
+function asObject(body: unknown): Record<string, unknown> {
+  return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {};
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// JSON Schemas (advertised on the catalog descriptors).
+// ---------------------------------------------------------------------------
+
+const CHANNEL_ROUTE_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['assignmentId', 'channelId', 'surfaceKind', 'profileId', 'createdAt', 'updatedAt'],
+  properties: {
+    assignmentId: { type: 'string' },
+    channelId: { type: 'string' },
+    surfaceKind: { type: 'string' },
+    routeId: { type: 'string' },
+    profileId: { type: 'string' },
+    label: { type: 'string' },
+    createdAt: { type: 'string' },
+    updatedAt: { type: 'string' },
+  },
+};
+
+const LIST_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    profileId: { type: 'string' },
+    surfaceKind: { type: 'string' },
+  },
+};
+
+const LIST_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['routes'],
+  properties: {
+    routes: { type: 'array', items: CHANNEL_ROUTE_SCHEMA },
+  },
+};
+
+const ASSIGN_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['channelId', 'profileId'],
+  properties: {
+    channelId: { type: 'string' },
+    profileId: { type: 'string' },
+    label: { type: 'string' },
+  },
+};
+
+const ASSIGN_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['assignmentId', 'channelId', 'profileId', 'created'],
+  properties: {
+    assignmentId: { type: 'string' },
+    channelId: { type: 'string' },
+    profileId: { type: 'string' },
+    created: { type: 'boolean' },
+  },
+};
+
+const DELETE_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['assignmentId'],
+  properties: {
+    assignmentId: { type: 'string' },
+  },
+};
+
+const DELETE_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['deleted'],
+  properties: {
+    deleted: { type: 'boolean' },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle returned by {@link registerRoutingMethods}: tears down the catalog
+ * methods and closes the underlying SQLite store. Also exposes the resolver so
+ * integration / the inbox surface can reuse routing resolution without going
+ * through the catalog.
+ */
+export interface RoutingRegistration extends Unregister {
+  (): void;
+  readonly store: RouteStore;
+  readonly resolver: RoutingResolver;
+}
+
+/**
+ * Register the channel-to-profile routing control-plane methods against the
+ * operator catalog:
+ *   - channels.routing.list   (read-only)
+ *   - channels.routing.assign (confirmed local-state mutation)
+ *   - channels.routing.delete (confirmed local-state mutation)
+ *
+ * The store is lazily initialized on first method invocation (the SurfaceRegister
+ * contract is synchronous), so registration never blocks on disk I/O.
+ */
+export function registerRoutingMethods(ctx: OperatorContext): RoutingRegistration {
+  const store = new RouteStore({ workingDirectory: ctx.workingDirectory });
+  const resolver = createRoutingResolver(store);
+
+  let initPromise: Promise<void> | null = null;
+  const ensureInit = async (): Promise<void> => {
+    if (!initPromise) {
+      initPromise = store.init().catch((error) => {
+        // Allow a later invocation to retry initialization.
+        initPromise = null;
+        throw error;
+      });
+    }
+    await initPromise;
+  };
+
+  const listHandler: OperatorHandler<RoutingListInput, RoutingListOutput> = async (input) => {
+    await ensureInit();
+    const body = asObject(input.body);
+    const routes = store.list({
+      profileId: optionalString(body.profileId),
+      surfaceKind: optionalString(body.surfaceKind),
+    });
+    return { routes };
+  };
+
+  const assignHandler: OperatorHandler<RoutingAssignInput, RoutingAssignOutput> = async (input) => {
+    await ensureInit();
+    const body = asObject(input.body);
+    const channelId = optionalString(body.channelId);
+    const profileId = optionalString(body.profileId);
+    if (channelId === undefined) {
+      throw new OperatorError('channelId is required', 'ROUTING_INVALID_CHANNEL_ID', 400);
+    }
+    if (profileId === undefined) {
+      throw new OperatorError('profileId is required', 'ROUTING_INVALID_PROFILE_ID', 400);
+    }
+    const { route, created } = await store.upsert({
+      channelId,
+      profileId,
+      label: optionalString(body.label),
+    });
+    ctx.logger.info('channels.routing.assign', {
+      assignmentId: route.assignmentId,
+      channelId: route.channelId,
+      profileId: route.profileId,
+      created,
+      principalId: input.context.principalId,
+    });
+    return {
+      assignmentId: route.assignmentId,
+      channelId: route.channelId,
+      profileId: route.profileId,
+      created,
+    };
+  };
+
+  const deleteHandler: OperatorHandler<RoutingDeleteInput, RoutingDeleteOutput> = async (input) => {
+    await ensureInit();
+    const body = asObject(input.body);
+    const assignmentId = optionalString(body.assignmentId);
+    if (assignmentId === undefined) {
+      throw new OperatorError('assignmentId is required', 'ROUTING_INVALID_ASSIGNMENT_ID', 400);
+    }
+    const deleted = await store.delete(assignmentId);
+    ctx.logger.info('channels.routing.delete', {
+      assignmentId,
+      deleted,
+      principalId: input.context.principalId,
+    });
+    return { deleted };
+  };
+
+  const listDescriptor: OperatorMethodDescriptor = {
+    id: 'channels.routing.list',
+    title: 'List channel routes',
+    description: 'List channel-to-profile routing assignments, optionally filtered by profile or surface.',
+    category: 'channels',
+    source: 'daemon',
+    access: 'authenticated',
+    transport: ['ws', 'internal'],
+    scopes: ['channels:routing:read'],
+    effect: 'read-only',
+    inputSchema: LIST_INPUT_SCHEMA,
+    outputSchema: LIST_OUTPUT_SCHEMA,
+  };
+
+  const assignDescriptor: OperatorMethodDescriptor = {
+    id: 'channels.routing.assign',
+    title: 'Assign channel to profile',
+    description: 'Create or update the profile that handles inbound messages on a channel.',
+    category: 'channels',
+    source: 'daemon',
+    access: 'authenticated',
+    transport: ['ws', 'internal'],
+    scopes: ['channels:routing:write'],
+    effect: 'local-state-mutation',
+    confirm: true,
+    inputSchema: ASSIGN_INPUT_SCHEMA,
+    outputSchema: ASSIGN_OUTPUT_SCHEMA,
+  };
+
+  const deleteDescriptor: OperatorMethodDescriptor = {
+    id: 'channels.routing.delete',
+    title: 'Delete channel route',
+    description: 'Remove a channel-to-profile routing assignment by assignmentId.',
+    category: 'channels',
+    source: 'daemon',
+    access: 'authenticated',
+    transport: ['ws', 'internal'],
+    scopes: ['channels:routing:write'],
+    effect: 'local-state-mutation',
+    confirm: true,
+    inputSchema: DELETE_INPUT_SCHEMA,
+    outputSchema: DELETE_OUTPUT_SCHEMA,
+  };
+
+  const unregister = declareOperatorMethods(ctx, [
+    { descriptor: listDescriptor, handler: listHandler as OperatorHandler<unknown, unknown> },
+    { descriptor: assignDescriptor, handler: assignHandler as OperatorHandler<unknown, unknown> },
+    { descriptor: deleteDescriptor, handler: deleteHandler as OperatorHandler<unknown, unknown> },
+  ]);
+
+  // Build the callable teardown handle, then attach the store/resolver as
+  // read-only properties so callers (integration, the inbox surface) can reuse
+  // routing resolution without going through the catalog.
+  const teardown = (): void => {
+    unregister();
+    store.close();
+  };
+  return Object.assign(teardown, { store, resolver }) as RoutingRegistration;
+}
+
+/** SurfaceRegister contract entry point (integration calls this). */
+export const register: SurfaceRegister = (ctx) => registerRoutingMethods(ctx);

package/src/daemon/channels/routing/route-store.ts

@@ -0,0 +1,278 @@
+import { randomUUID } from 'node:crypto';
+import { OperatorSqliteStore } from '../../operator/sqlite-store.ts';
+import { OperatorError } from '../../operator/types.ts';
+
+/**
+ * A persisted channel-to-profile routing assignment, in the exact shape the
+ * `channels.routing.*` operator methods return (see daemon handoff doc,
+ * Responsibility 2). This is intentionally distinct from the foundation's
+ * generic `ChannelRoute` type — the routing control-plane has its own contract
+ * keyed on (surfaceKind, routeId) composite channel IDs.
+ */
+export interface RoutingChannelRoute {
+  assignmentId: string;
+  /** Composite key: `surfaceKind` or `surfaceKind:routeId`. */
+  channelId: string;
+  surfaceKind: string;
+  routeId?: string;
+  profileId: string;
+  label?: string;
+  createdAt: string; // ISO-8601
+  updatedAt: string; // ISO-8601
+}
+
+/** Parsed components of a composite channelId. */
+export interface ParsedChannelId {
+  surfaceKind: string;
+  routeId?: string;
+}
+
+export interface RouteUpsertInput {
+  channelId: string;
+  profileId: string;
+  label?: string;
+}
+
+export interface RouteUpsertResult {
+  route: RoutingChannelRoute;
+  created: boolean;
+}
+
+export interface RouteListFilter {
+  profileId?: string;
+  surfaceKind?: string;
+}
+
+const SCHEMA: string[] = [
+  `CREATE TABLE IF NOT EXISTS routes (
+    assignmentId TEXT PRIMARY KEY,
+    channelId TEXT NOT NULL,
+    surfaceKind TEXT NOT NULL,
+    routeId TEXT,
+    profileId TEXT NOT NULL,
+    label TEXT,
+    createdAt TEXT NOT NULL,
+    updatedAt TEXT NOT NULL
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_routes_surface_route ON routes (surfaceKind, routeId)`,
+  // Enforce one assignment per channel — the upsert path relies on this.
+  `CREATE UNIQUE INDEX IF NOT EXISTS idx_routes_channel ON routes (channelId)`,
+];
+
+interface RouteRow {
+  assignmentId: string;
+  channelId: string;
+  surfaceKind: string;
+  routeId: string | null;
+  profileId: string;
+  label: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Parse a composite channelId into its `surfaceKind` and optional `routeId`.
+ *
+ * The channelId format is `surfaceKind` (surface-only / wildcard) or
+ * `surfaceKind:routeId`. Everything after the FIRST colon is the routeId, so
+ * route IDs may themselves contain colons (e.g. `slack:C123:thread`).
+ */
+export function parseChannelId(channelId: string): ParsedChannelId {
+  const raw = typeof channelId === 'string' ? channelId.trim() : '';
+  if (raw.length === 0) {
+    throw new OperatorError('channelId is required', 'ROUTING_INVALID_CHANNEL_ID', 400);
+  }
+  const separator = raw.indexOf(':');
+  if (separator === -1) {
+    return { surfaceKind: raw };
+  }
+  const surfaceKind = raw.slice(0, separator).trim();
+  const routeId = raw.slice(separator + 1).trim();
+  if (surfaceKind.length === 0) {
+    throw new OperatorError('channelId is missing a surfaceKind', 'ROUTING_INVALID_CHANNEL_ID', 400);
+  }
+  // A trailing colon with no routeId collapses to a surface-only assignment.
+  return routeId.length === 0 ? { surfaceKind } : { surfaceKind, routeId };
+}
+
+/** Build a canonical composite channelId from its parts. */
+export function buildChannelId(surfaceKind: string, routeId?: string): string {
+  return routeId === undefined || routeId === '' ? surfaceKind : `${surfaceKind}:${routeId}`;
+}
+
+function rowToRoute(row: RouteRow): RoutingChannelRoute {
+  const route: RoutingChannelRoute = {
+    assignmentId: row.assignmentId,
+    channelId: row.channelId,
+    surfaceKind: row.surfaceKind,
+    profileId: row.profileId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+  if (row.routeId !== null && row.routeId !== '') route.routeId = row.routeId;
+  if (row.label !== null && row.label !== '') route.label = row.label;
+  return route;
+}
+
+/**
+ * SQLite-backed store for channel-to-profile routing assignments.
+ *
+ * Wraps {@link OperatorSqliteStore} (file `channel-routes.sqlite`) and persists
+ * after every mutation. The store owns the composite-key parsing so callers only
+ * ever deal with `channelId` strings.
+ */
+export class RouteStore {
+  private readonly store: OperatorSqliteStore;
+  private initialized = false;
+
+  constructor(options: { workingDirectory: string }) {
+    this.store = new OperatorSqliteStore({
+      workingDirectory: options.workingDirectory,
+      fileName: 'channel-routes.sqlite',
+      schema: SCHEMA,
+    });
+  }
+
+  get dbPath(): string {
+    return this.store.dbPath;
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.init();
+    this.initialized = true;
+  }
+
+  close(): void {
+    this.store.close();
+    this.initialized = false;
+  }
+
+  private requireInit(): void {
+    if (!this.initialized) {
+      throw new OperatorError('RouteStore not initialized', 'ROUTING_STORE_UNINITIALIZED', 500);
+    }
+  }
+
+  /** All assignments, ordered most-recently-updated first. */
+  listAll(): RoutingChannelRoute[] {
+    this.requireInit();
+    const rows = this.store.all<RouteRow>(
+      `SELECT assignmentId, channelId, surfaceKind, routeId, profileId, label, createdAt, updatedAt
+       FROM routes ORDER BY updatedAt DESC, assignmentId ASC`,
+    );
+    return rows.map(rowToRoute);
+  }
+
+  /** Assignments filtered by optional profileId and/or surfaceKind. */
+  list(filter: RouteListFilter = {}): RoutingChannelRoute[] {
+    this.requireInit();
+    const clauses: string[] = [];
+    const params: (string | number)[] = [];
+    if (filter.profileId !== undefined && filter.profileId !== '') {
+      clauses.push('profileId = ?');
+      params.push(filter.profileId);
+    }
+    if (filter.surfaceKind !== undefined && filter.surfaceKind !== '') {
+      clauses.push('surfaceKind = ?');
+      params.push(filter.surfaceKind);
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+    const rows = this.store.all<RouteRow>(
+      `SELECT assignmentId, channelId, surfaceKind, routeId, profileId, label, createdAt, updatedAt
+       FROM routes ${where} ORDER BY updatedAt DESC, assignmentId ASC`,
+      params,
+    );
+    return rows.map(rowToRoute);
+  }
+
+  /** Lookup a single assignment by its composite channelId. */
+  findByChannelId(channelId: string): RoutingChannelRoute | null {
+    this.requireInit();
+    const row = this.store.get<RouteRow>(
+      `SELECT assignmentId, channelId, surfaceKind, routeId, profileId, label, createdAt, updatedAt
+       FROM routes WHERE channelId = ?`,
+      [channelId],
+    );
+    return row ? rowToRoute(row) : null;
+  }
+
+  /** Lookup a single assignment by its assignmentId. */
+  findById(assignmentId: string): RoutingChannelRoute | null {
+    this.requireInit();
+    const row = this.store.get<RouteRow>(
+      `SELECT assignmentId, channelId, surfaceKind, routeId, profileId, label, createdAt, updatedAt
+       FROM routes WHERE assignmentId = ?`,
+      [assignmentId],
+    );
+    return row ? rowToRoute(row) : null;
+  }
+
+  /**
+   * Create or update the assignment for a channel.
+   *
+   * `created` is true when no prior assignment existed for the channelId, false
+   * when an existing row was updated. The assignmentId is stable across updates
+   * (it is preserved from the existing row). Persists to disk after the write.
+   */
+  async upsert(input: RouteUpsertInput): Promise<RouteUpsertResult> {
+    this.requireInit();
+    const profileId = typeof input.profileId === 'string' ? input.profileId.trim() : '';
+    if (profileId.length === 0) {
+      throw new OperatorError('profileId is required', 'ROUTING_INVALID_PROFILE_ID', 400);
+    }
+    const { surfaceKind, routeId } = parseChannelId(input.channelId);
+    const channelId = buildChannelId(surfaceKind, routeId);
+    const label = typeof input.label === 'string' && input.label.trim().length > 0
+      ? input.label.trim()
+      : null;
+    const now = new Date().toISOString();
+
+    const existing = this.findByChannelId(channelId);
+    if (existing) {
+      this.store.run(
+        `UPDATE routes
+         SET profileId = ?, label = ?, surfaceKind = ?, routeId = ?, updatedAt = ?
+         WHERE assignmentId = ?`,
+        [profileId, label, surfaceKind, routeId ?? null, now, existing.assignmentId],
+      );
+      await this.store.save();
+      const route = this.findById(existing.assignmentId);
+      if (!route) {
+        throw new OperatorError('Failed to read back updated route', 'ROUTING_WRITE_FAILED', 500);
+      }
+      return { route, created: false };
+    }
+
+    const assignmentId = randomUUID();
+    this.store.run(
+      `INSERT INTO routes
+        (assignmentId, channelId, surfaceKind, routeId, profileId, label, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      [assignmentId, channelId, surfaceKind, routeId ?? null, profileId, label, now, now],
+    );
+    await this.store.save();
+    const route = this.findById(assignmentId);
+    if (!route) {
+      throw new OperatorError('Failed to read back inserted route', 'ROUTING_WRITE_FAILED', 500);
+    }
+    return { route, created: true };
+  }
+
+  /**
+   * Delete an assignment by assignmentId. Returns true when a row was removed,
+   * false when no matching assignment existed. Persists to disk after a delete.
+   */
+  async delete(assignmentId: string): Promise<boolean> {
+    this.requireInit();
+    const id = typeof assignmentId === 'string' ? assignmentId.trim() : '';
+    if (id.length === 0) {
+      throw new OperatorError('assignmentId is required', 'ROUTING_INVALID_ASSIGNMENT_ID', 400);
+    }
+    const existing = this.findById(id);
+    if (!existing) return false;
+    this.store.run('DELETE FROM routes WHERE assignmentId = ?', [id]);
+    await this.store.save();
+    return true;
+  }
+}

package/src/daemon/channels/routing/routing-resolver.ts

@@ -0,0 +1,75 @@
+import type { RoutingChannelRoute } from './route-store.ts';
+import { RouteStore } from './route-store.ts';
+
+/** Wildcard surfaceKind that matches any surface as a last resort. */
+export const WILDCARD_SURFACE = 'any';
+
+/**
+ * Pure resolution of a profileId from a set of routes, applying the EXACT same
+ * order as the agent-side `getProfileForChannel()` so offline and online
+ * routing produce identical results:
+ *
+ *   1. exact match    — surfaceKind AND routeId both match
+ *   2. surface-only   — surfaceKind matches, route has no routeId
+ *   3. wildcard       — a route with surfaceKind === 'any' (no routeId)
+ *
+ * Returns the matching profileId, or `null` when nothing matches.
+ */
+export function resolveProfile(
+  routes: readonly RoutingChannelRoute[],
+  surfaceKind: string,
+  routeId?: string,
+): string | null {
+  const surface = typeof surfaceKind === 'string' ? surfaceKind.trim() : '';
+  if (surface.length === 0) return null;
+  const route = typeof routeId === 'string' && routeId.trim().length > 0 ? routeId.trim() : undefined;
+
+  // 1. Exact match (surfaceKind + routeId). Only attempted when a routeId is
+  //    supplied by the caller.
+  if (route !== undefined) {
+    const exact = routes.find(
+      (entry) => entry.surfaceKind === surface && entry.routeId === route,
+    );
+    if (exact) return exact.profileId;
+  }
+
+  // 2. Surface-only match (surfaceKind, no routeId on the route).
+  const surfaceOnly = routes.find(
+    (entry) => entry.surfaceKind === surface && (entry.routeId === undefined || entry.routeId === ''),
+  );
+  if (surfaceOnly) return surfaceOnly.profileId;
+
+  // 3. Wildcard match (surfaceKind === 'any', no routeId).
+  const wildcard = routes.find(
+    (entry) => entry.surfaceKind === WILDCARD_SURFACE && (entry.routeId === undefined || entry.routeId === ''),
+  );
+  if (wildcard) return wildcard.profileId;
+
+  return null;
+}
+
+/** Resolver bound to a live {@link RouteStore}. */
+export interface RoutingResolver {
+  /**
+   * Resolve the profileId that should handle an inbound message on the given
+   * surface/route, applying the agent resolution order. Returns null when no
+   * assignment matches (caller falls back to the default session).
+   */
+  getProfileForChannel(surfaceKind: string, routeId?: string): string | null;
+  /** Alias of {@link getProfileForChannel}, exported for inbox surface reuse. */
+  resolveProfile(surfaceKind: string, routeId?: string): string | null;
+}
+
+/**
+ * Create a resolver backed by a {@link RouteStore}. The store must already be
+ * initialized; each call reads the current route set so assignments take effect
+ * immediately after a mutation.
+ */
+export function createRoutingResolver(store: RouteStore): RoutingResolver {
+  const resolve = (surfaceKind: string, routeId?: string): string | null =>
+    resolveProfile(store.listAll(), surfaceKind, routeId);
+  return {
+    getProfileForChannel: resolve,
+    resolveProfile: resolve,
+  };
+}