@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/sqlite-store.ts

@@ -0,0 +1,124 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import initSqlJs from 'sql.js';
+
+type SqlJsStatic = Awaited<ReturnType<typeof initSqlJs>>;
+type SqlDatabase = InstanceType<SqlJsStatic['Database']>;
+
+export interface SqliteStoreOptions {
+  workingDirectory: string;
+  /** e.g. 'channel-routes.sqlite', 'drafts.sqlite', 'inbox-cursors.sqlite' */
+  fileName: string;
+  /** CREATE TABLE / INDEX statements run once on init (idempotent: IF NOT EXISTS). */
+  schema: string[];
+}
+
+let sqlJsStaticPromise: Promise<SqlJsStatic> | null = null;
+
+async function loadSqlJs(): Promise<SqlJsStatic> {
+  if (!sqlJsStaticPromise) {
+    sqlJsStaticPromise = initSqlJs();
+  }
+  return sqlJsStaticPromise;
+}
+
+/**
+ * Daemon sqlite helper following the project MemoryStore lifecycle
+ * (sql.js WASM: init → run/exec → save → close). One file per concern under
+ * {workingDirectory}/.goodvibes/tui/operator/{fileName}.
+ */
+export class HandlerSqliteStore {
+  private readonly options: SqliteStoreOptions;
+  private readonly resolvedPath: string;
+  private db: SqlDatabase | null = null;
+
+  constructor(options: SqliteStoreOptions) {
+    this.options = options;
+    this.resolvedPath = join(
+      options.workingDirectory,
+      '.goodvibes',
+      'tui',
+      'operator',
+      options.fileName,
+    );
+  }
+
+  get dbPath(): string {
+    return this.resolvedPath;
+  }
+
+  private requireDb(): SqlDatabase {
+    if (!this.db) {
+      throw new Error(`HandlerSqliteStore not initialized: ${this.resolvedPath}`);
+    }
+    return this.db;
+  }
+
+  async init(): Promise<void> {
+    if (this.db) return;
+    await mkdir(dirname(this.resolvedPath), { recursive: true });
+    const SQL = await loadSqlJs();
+    const existing = existsSync(this.resolvedPath) ? readFileSync(this.resolvedPath) : undefined;
+    this.db = existing ? new SQL.Database(existing) : new SQL.Database();
+    for (const statement of this.options.schema) {
+      this.db.run(statement);
+    }
+  }
+
+  /** Execute a write (INSERT/UPDATE/DELETE/CREATE). */
+  run(sql: string, params?: (string | number | Uint8Array | null)[]): void {
+    this.requireDb().run(sql, params);
+  }
+
+  /** SELECT → array of row objects (columns mapped to values). */
+  all<T = Record<string, unknown>>(sql: string, params?: (string | number)[]): T[] {
+    const result = this.requireDb().exec(sql, params);
+    if (result.length === 0) return [];
+    const { columns, values } = result[0]!;
+    return values.map((row) => {
+      const obj: Record<string, unknown> = {};
+      for (let i = 0; i < columns.length; i += 1) {
+        obj[columns[i]!] = row[i];
+      }
+      return obj as T;
+    });
+  }
+
+  /** First row or null. */
+  get<T = Record<string, unknown>>(sql: string, params?: (string | number)[]): T | null {
+    const rows = this.all<T>(sql, params);
+    return rows.length > 0 ? rows[0]! : null;
+  }
+
+  /** Serialize and atomically persist to dbPath (tmp + rename). */
+  async save(): Promise<void> {
+    const db = this.requireDb();
+    await mkdir(dirname(this.resolvedPath), { recursive: true });
+    const data = db.export();
+    const tmpPath = `${this.resolvedPath}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmpPath, data);
+    await rename(tmpPath, this.resolvedPath);
+  }
+
+  close(): void {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+
+  /** BEGIN/COMMIT around fn; ROLLBACK on throw (synchronous sql.js). */
+  transaction(fn: () => void): void {
+    const db = this.requireDb();
+    db.run('BEGIN');
+    try {
+      fn();
+      db.run('COMMIT');
+    } catch (error) {
+      db.run('ROLLBACK');
+      throw error;
+    }
+  }
+}

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

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Public surface for the daemon-internal Email Auto-Tag / Spam Triage handler.
+//
+// `registerTriagedInbox` (from ./integration.ts) is the single entry the
+// runtime composition root calls. It DECORATES the inbox surface's
+// `channels.inbox.list` handler (overlaying persisted triage metadata) and
+// returns the poller-facing pipeline + tagger. inbox.triage.* are NOT published
+// catalog methods — this surface registers no triage method id.
+// ---------------------------------------------------------------------------
+
+export {
+  scoreInboundItem,
+  labelToTag,
+  type TriageScore,
+  type TriageScorerOptions,
+} from './scorer.ts';
+
+export type {
+  InboundChannelItem,
+  TriageLabel,
+  ConversationKind,
+} from './types.ts';
+
+export {
+  runInboxTriage,
+  createTriageStore,
+  readTriageMetadata,
+  readTriageMetadataBatch,
+  enrichItemsWithTriage,
+  TRIAGE_STORE_FILE,
+  type TriageMetadata,
+  type TriagedItem,
+  type TriageOverlay,
+  type TriageEnrichedItem,
+  type RunInboxTriageOptions,
+  type RunInboxTriageResult,
+} from './pipeline.ts';
+
+export {
+  createTriageTagger,
+  TRIAGE_AUTOTAG_FLAG,
+  type TriageTagger,
+  type TriageTaggerOptions,
+  type TaggerProviderConfig,
+  type ApplyTagsRequest,
+  type ApplyTagsResult,
+  type ImapStoreArgs,
+  type ImapRetryOptions,
+} from './tagger/index.ts';
+
+export {
+  registerTriagedInbox,
+  INBOX_LIST_METHOD_ID,
+  type RegisterInbox,
+  type RegisterTriagedInboxOptions,
+  type TriagedInboxRegistration,
+} from './integration.ts';

package/src/daemon/handlers/triage/integration.ts

@@ -0,0 +1,212 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage INTEGRATION (the single entry the runtime calls).
+//
+// `registerTriagedInbox(ctx, registerInbox, options)` closes the contract loop:
+//
+//   1. It DECORATES the inbox surface's `channels.inbox.list` handler. The
+//      inbox surface (a separate handler module) attaches its handler to the
+//      SDK-auto-registered descriptor via `ctx.catalog.register(descriptor,
+//      handler, { replace: true })`. We pass the inbox `registerInbox` a
+//      catalog PROXY whose `register` intercepts exactly the
+//      `channels.inbox.list` id and wraps the handler so every returned item is
+//      overlaid with the persisted triageScore/triageTags via
+//      enrichItemsWithTriage(). Every other registration passes straight
+//      through to the real catalog. The inbox descriptor/schema/id is never
+//      re-authored — only its handler is wrapped.
+//   2. It exposes the triage pipeline + tagger (`runInboxTriage`, `tagger`) for
+//      the daemon-internal poller, which scores items and persists them to the
+//      co-located inbox-triage.sqlite store the decorator reads from.
+//   3. inbox.triage.* are intentionally NOT registered on the catalog (they are
+//      a daemon-internal pipeline, not published methods) — so this module
+//      makes ZERO catalog.register call for any triage id.
+//
+// Reads in the decorator are best-effort and degrade to the raw item when no
+// triage row exists yet, so the read-only inbox feed never breaks.
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../context.ts';
+import type {
+  GatewayMethodCatalog,
+  GatewayMethodDescriptor,
+  GatewayMethodHandler,
+} from '../contracts.ts';
+import type { Unregister } from '../register.ts';
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import {
+  createTriageStore,
+  enrichItemsWithTriage,
+  runInboxTriage,
+  type RunInboxTriageOptions,
+  type RunInboxTriageResult,
+} from './pipeline.ts';
+import type { InboundChannelItem } from './types.ts';
+import {
+  createTriageTagger,
+  type ApplyTagsRequest,
+  type ApplyTagsResult,
+  type TriageTagger,
+  type TriageTaggerOptions,
+} from './tagger/index.ts';
+
+/**
+ * Canonical id of the inbox list method whose handler we decorate. This is the
+ * SDK's published id — referenced as a plain string for matching during
+ * registration; no descriptor or schema is authored here.
+ */
+export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';
+
+/** Minimal shape of the inbox.list result the decorator overlays triage onto. */
+interface InboxListResult {
+  items?: unknown;
+  [key: string]: unknown;
+}
+
+export interface RegisterTriagedInboxOptions {
+  pipeline?: RunInboxTriageOptions;
+  tagger?: TriageTaggerOptions;
+}
+
+/**
+ * The inbox surface provider. The runtime supplies the inbox module's register
+ * function; we hand it a decorating catalog proxy so its `channels.inbox.list`
+ * handler is wrapped with triage enrichment.
+ */
+export type RegisterInbox = (ctx: HandlerContext) => Unregister;
+
+/** Handle returned to the runtime: teardown + the poller-facing pipeline/tagger. */
+export interface TriagedInboxRegistration {
+  readonly unregister: Unregister;
+  /** Score (+persist) a batch of polled items. Used by the inbox poller. */
+  runInboxTriage(
+    items: readonly InboundChannelItem[],
+    options?: RunInboxTriageOptions,
+  ): Promise<RunInboxTriageResult>;
+  /** Provider-side tagger (IMAP flag / Slack or Discord reaction/tag). */
+  readonly tagger: TriageTagger;
+}
+
+type StoredHandler = GatewayMethodHandler;
+
+interface EnrichmentProxy {
+  readonly ctx: HandlerContext;
+  /** Close the shared triage store handle (if one was ever opened). */
+  dispose(): void;
+}
+
+/**
+ * Build a HandlerContext whose catalog decorates `channels.inbox.list`
+ * registration. The triage store is opened lazily ONCE on the first list
+ * invocation and reused for every subsequent call (hot read path); the caller
+ * disposes the handle on teardown.
+ */
+function withInboxEnrichment(ctx: HandlerContext): EnrichmentProxy {
+  const original = ctx.catalog;
+
+  let store: HandlerSqliteStore | null = null;
+  let initPromise: Promise<HandlerSqliteStore> | null = null;
+  const getStore = async (): Promise<HandlerSqliteStore> => {
+    if (store) return store;
+    if (!initPromise) {
+      const pending = createTriageStore(ctx.workingDirectory);
+      initPromise = pending
+        .init()
+        .then(() => {
+          store = pending;
+          return pending;
+        })
+        .catch((error) => {
+          initPromise = null; // allow a later call to retry opening the store
+          throw error;
+        });
+    }
+    return initPromise;
+  };
+  const dispose = (): void => {
+    if (store) {
+      store.close();
+      store = null;
+    }
+    initPromise = null;
+  };
+
+  const decoratedRegister: GatewayMethodCatalog['register'] = (
+    descriptor: GatewayMethodDescriptor,
+    handler?: StoredHandler,
+    options?: { replace?: boolean },
+  ): Unregister => {
+    if (descriptor.id !== INBOX_LIST_METHOD_ID || !handler) {
+      return original.register(descriptor, handler, options);
+    }
+    const innerHandler = handler;
+    const wrapped: StoredHandler = async (invocation) => {
+      const result = (await innerHandler(invocation)) as InboxListResult;
+      if (!result || !Array.isArray(result.items) || result.items.length === 0) {
+        return result;
+      }
+      const items = result.items as Array<{ id: string }>;
+      try {
+        const handle = await getStore();
+        return { ...result, items: enrichItemsWithTriage(handle, items) };
+      } catch (error) {
+        // Triage is best-effort: a missing/locked store must never break the
+        // read-only inbox feed. Log and return the un-enriched result.
+        ctx.logger.warn('triage: inbox enrichment skipped', {
+          message: error instanceof Error ? error.message : String(error),
+        });
+        return result;
+      }
+    };
+    return original.register(descriptor, wrapped, options);
+  };
+
+  // Clone the context with only `catalog.register` swapped. Every other catalog
+  // method (invoke/list/get/...) keeps pointing at the original instance.
+  const proxiedCatalog = new Proxy(original, {
+    get(target, prop, receiver) {
+      if (prop === 'register') return decoratedRegister;
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as GatewayMethodCatalog;
+
+  return { ctx: { ...ctx, catalog: proxiedCatalog }, dispose };
+}
+
+/**
+ * Compose the triage pipeline with the inbox surface so channels.inbox.list
+ * returns pre-scored items. Returns the teardown plus the poller-facing
+ * pipeline/tagger handle. The inbox surface's registration is wrapped; inbox
+ * teardown runs first, then the shared store handle is disposed.
+ */
+export function registerTriagedInbox(
+  ctx: HandlerContext,
+  registerInbox: RegisterInbox,
+  options: RegisterTriagedInboxOptions = {},
+): TriagedInboxRegistration {
+  const tagger = createTriageTagger(ctx, options.tagger);
+  const enriched = withInboxEnrichment(ctx);
+
+  let unregisterInbox: Unregister;
+  try {
+    unregisterInbox = registerInbox(enriched.ctx);
+  } catch (error) {
+    enriched.dispose();
+    throw error;
+  }
+
+  const unregister: Unregister = () => {
+    try {
+      unregisterInbox();
+    } finally {
+      enriched.dispose();
+    }
+  };
+
+  return {
+    unregister,
+    runInboxTriage: (items, runOptions) =>
+      runInboxTriage(items, ctx, { ...options.pipeline, ...runOptions }),
+    tagger,
+  };
+}
+
+export type { ApplyTagsRequest, ApplyTagsResult };

package/src/daemon/handlers/triage/pipeline.ts

@@ -0,0 +1,273 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage PIPELINE.
+//
+// runInboxTriage(items): scores each inbound item (scorer.ts) and writes the
+// resulting triageScore/triageTags back into the inbox triage store so that a
+// later channels.inbox.list response can surface pre-scored items.
+//
+// The inbox surface owns the authoritative cursor-store and exposes
+// triageScore/triageTags columns. To stay strictly within the triage handler
+// surface, this pipeline persists into a dedicated, co-located
+// HandlerSqliteStore ('inbox-triage.sqlite') keyed by item id. The inbox
+// surface reads these rows by id when assembling its list response (the
+// integration decorator does exactly that). The schema mirrors the agreed
+// columns: triageScore REAL, triageTags TEXT (JSON array).
+// ---------------------------------------------------------------------------
+
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import type { HandlerContext } from '../context.ts';
+import type { InboundChannelItem, TriageLabel } from './types.ts';
+import {
+  labelToTag,
+  scoreInboundItem,
+  type TriageScore,
+  type TriageScorerOptions,
+} from './scorer.ts';
+
+export const TRIAGE_STORE_FILE = 'inbox-triage.sqlite';
+
+const SCHEMA: string[] = [
+  `CREATE TABLE IF NOT EXISTS inbox_triage (
+     id TEXT PRIMARY KEY,
+     surface TEXT NOT NULL,
+     triageScore REAL NOT NULL,
+     triageLabel TEXT NOT NULL,
+     triageTags TEXT NOT NULL,
+     spamSignal REAL NOT NULL,
+     prioritySignal REAL NOT NULL,
+     updatedAt TEXT NOT NULL
+   )`,
+  `CREATE INDEX IF NOT EXISTS idx_inbox_triage_label ON inbox_triage (triageLabel)`,
+  `CREATE INDEX IF NOT EXISTS idx_inbox_triage_surface ON inbox_triage (surface)`,
+];
+
+export interface TriageMetadata {
+  triageScore: number;
+  triageLabel: TriageLabel;
+  triageTags: string[];
+  signals: TriageScore['signals'];
+}
+
+export interface TriagedItem extends InboundChannelItem {
+  triage: TriageMetadata;
+}
+
+export interface RunInboxTriageOptions {
+  scorer?: TriageScorerOptions;
+  /** Inject a store (tests). When omitted, a triage store is opened/closed. */
+  store?: HandlerSqliteStore;
+  /** When true, do not persist — only compute (used by inbox.triage.list). */
+  dryRun?: boolean;
+  /** Clock injection for deterministic updatedAt in tests. */
+  now?: () => Date;
+}
+
+export interface RunInboxTriageResult {
+  items: TriagedItem[];
+  scored: number;
+  persisted: number;
+}
+
+function toMetadata(score: TriageScore): TriageMetadata {
+  return {
+    triageScore: score.score,
+    triageLabel: score.label,
+    triageTags: [labelToTag(score.label)],
+    signals: score.signals,
+  };
+}
+
+/**
+ * Open the triage store for this working directory. Caller owns close()/save()
+ * when they pass their own store; otherwise runInboxTriage manages lifecycle.
+ */
+export function createTriageStore(workingDirectory: string): HandlerSqliteStore {
+  return new HandlerSqliteStore({
+    workingDirectory,
+    fileName: TRIAGE_STORE_FILE,
+    schema: SCHEMA,
+  });
+}
+
+function persistRow(
+  store: HandlerSqliteStore,
+  item: InboundChannelItem,
+  meta: TriageMetadata,
+  updatedAt: string,
+): void {
+  store.run(
+    `INSERT INTO inbox_triage
+       (id, surface, triageScore, triageLabel, triageTags, spamSignal, prioritySignal, updatedAt)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       surface = excluded.surface,
+       triageScore = excluded.triageScore,
+       triageLabel = excluded.triageLabel,
+       triageTags = excluded.triageTags,
+       spamSignal = excluded.spamSignal,
+       prioritySignal = excluded.prioritySignal,
+       updatedAt = excluded.updatedAt`,
+    [
+      item.id,
+      item.surface,
+      meta.triageScore,
+      meta.triageLabel,
+      JSON.stringify(meta.triageTags),
+      meta.signals.spam,
+      meta.signals.priority,
+      updatedAt,
+    ],
+  );
+}
+
+/**
+ * Score every item and (unless dryRun) persist triageScore/triageTags back into
+ * the inbox triage store. Returns each item enriched with triage metadata so
+ * the caller can surface it without a second read.
+ *
+ * Called by the inbox poller (Responsibility 1) after each poll.
+ */
+export async function runInboxTriage(
+  items: readonly InboundChannelItem[],
+  ctx: HandlerContext,
+  options: RunInboxTriageOptions = {},
+): Promise<RunInboxTriageResult> {
+  const now = options.now ?? (() => new Date());
+  const updatedAt = now().toISOString();
+
+  const enriched: TriagedItem[] = items.map((item) => {
+    const score = scoreInboundItem(item, options.scorer);
+    return { ...item, triage: toMetadata(score) };
+  });
+
+  if (options.dryRun || enriched.length === 0) {
+    return { items: enriched, scored: enriched.length, persisted: 0 };
+  }
+
+  const ownsStore = !options.store;
+  const store = options.store ?? createTriageStore(ctx.workingDirectory);
+  let persisted = 0;
+  try {
+    if (ownsStore) await store.init();
+    store.transaction(() => {
+      for (const item of enriched) {
+        persistRow(store, item, item.triage, updatedAt);
+        persisted += 1;
+      }
+    });
+    if (ownsStore) await store.save();
+  } catch (error) {
+    ctx.logger.error('triage: failed to persist scores', {
+      message: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  } finally {
+    if (ownsStore) store.close();
+  }
+
+  return { items: enriched, scored: enriched.length, persisted };
+}
+
+/** Optional persisted triage metadata overlaid onto an inbound item. */
+export interface TriageOverlay {
+  triageScore?: number;
+  triageTags?: string[];
+  triageLabel?: TriageLabel;
+}
+
+/** An inbound item overlaid with optional persisted triage metadata. */
+export type TriageEnrichedItem = InboundChannelItem & TriageOverlay;
+
+function rowToMetadata(row: Omit<TriageRow, 'id'>): TriageMetadata {
+  let tags: string[] = [];
+  try {
+    const parsed = JSON.parse(row.triageTags) as unknown;
+    if (Array.isArray(parsed)) tags = parsed.filter((t): t is string => typeof t === 'string');
+  } catch {
+    tags = [];
+  }
+  return {
+    triageScore: row.triageScore,
+    triageLabel: row.triageLabel as TriageLabel,
+    triageTags: tags,
+    signals: { spam: row.spamSignal, priority: row.prioritySignal },
+  };
+}
+
+interface TriageRow {
+  id: string;
+  triageScore: number;
+  triageLabel: string;
+  triageTags: string;
+  spamSignal: number;
+  prioritySignal: number;
+}
+
+/**
+ * Read persisted triage rows for many item ids in a single `WHERE id IN (...)`
+ * query. Returns a Map keyed by item id; ids without a stored row are absent.
+ * De-duplicates ids so the placeholder list stays minimal.
+ */
+export function readTriageMetadataBatch(
+  store: HandlerSqliteStore,
+  itemIds: readonly string[],
+): Map<string, TriageMetadata> {
+  const out = new Map<string, TriageMetadata>();
+  const uniqueIds = [...new Set(itemIds)];
+  if (uniqueIds.length === 0) return out;
+  const placeholders = uniqueIds.map(() => '?').join(', ');
+  const rows = store.all<TriageRow>(
+    `SELECT id, triageScore, triageLabel, triageTags, spamSignal, prioritySignal
+       FROM inbox_triage WHERE id IN (${placeholders})`,
+    uniqueIds,
+  );
+  for (const row of rows) {
+    out.set(row.id, rowToMetadata(row));
+  }
+  return out;
+}
+
+/** Read a single persisted triage row by item id (used by the inbox surface). */
+export function readTriageMetadata(
+  store: HandlerSqliteStore,
+  itemId: string,
+): TriageMetadata | null {
+  const row = store.get<Omit<TriageRow, 'id'>>(
+    `SELECT triageScore, triageLabel, triageTags, spamSignal, prioritySignal
+       FROM inbox_triage WHERE id = ?`,
+    [itemId],
+  );
+  if (!row) return null;
+  return rowToMetadata(row);
+}
+
+/**
+ * Merge persisted triage metadata onto a batch of inbound items by id. This is
+ * the exact glue `channels.inbox.list` invokes to surface pre-scored items: the
+ * inbox surface lists from its cursor store, then calls this to overlay the
+ * triageScore/triageTags columns the contract promises. Items without a stored
+ * triage row pass through untouched, so an un-scored feed degrades gracefully.
+ */
+export function enrichItemsWithTriage<T extends { id: string }>(
+  store: HandlerSqliteStore,
+  items: readonly T[],
+): Array<T & TriageOverlay> {
+  if (items.length === 0) return [];
+  // Single batched read (`WHERE id IN (...)`) instead of one SELECT per item —
+  // this is a hot read path (every channels.inbox.list call), so the N+1 is
+  // collapsed to one query keyed by id.
+  const byId = readTriageMetadataBatch(
+    store,
+    items.map((item) => item.id),
+  );
+  return items.map((item) => {
+    const meta = byId.get(item.id);
+    if (!meta) return { ...item };
+    return {
+      ...item,
+      triageScore: meta.triageScore,
+      triageLabel: meta.triageLabel,
+      triageTags: meta.triageTags,
+    };
+  });
+}