@pellux/goodvibes-tui 0.24.0 → 0.25.0

package/src/daemon/triage/pipeline.ts

@@ -0,0 +1,285 @@
+// ---------------------------------------------------------------------------
+// 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 src/daemon/triage/
+// (per the hard rules), this pipeline persists into a dedicated, co-located
+// OperatorSqliteStore ('inbox-triage.sqlite') keyed by item id. The inbox
+// surface reads these rows by id when assembling its list response. The schema
+// mirrors the agreed columns: triageScore REAL, triageTags TEXT (JSON array).
+// ---------------------------------------------------------------------------
+
+import {
+  OperatorSqliteStore,
+  type InboundChannelItem,
+  type OperatorContext,
+} from '../operator/index.ts';
+import {
+  labelToTag,
+  scoreInboundItem,
+  type TriageLabel,
+  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?: OperatorSqliteStore;
+  /** 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): OperatorSqliteStore {
+  return new OperatorSqliteStore({
+    workingDirectory,
+    fileName: TRIAGE_STORE_FILE,
+    schema: SCHEMA,
+  });
+}
+
+function persistRow(
+  store: OperatorSqliteStore,
+  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: OperatorContext,
+  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 };
+}
+
+/**
+ * Inbound item enriched with the persisted triage metadata that
+ * `channels.inbox.list` advertises (triageScore + triageTags). When no triage
+ * row exists yet for an item the original item is returned unchanged.
+ */
+export interface TriageOverlay {
+  triageScore?: number;
+  triageTags?: string[];
+  triageLabel?: TriageLabel;
+}
+
+/** An inbound item overlaid with optional persisted triage metadata. */
+export type TriageEnrichedItem = InboundChannelItem & TriageOverlay;
+
+/**
+ * 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: OperatorSqliteStore,
+  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,
+    };
+  });
+}
+
+interface TriageRow {
+  id: string;
+  triageScore: number;
+  triageLabel: string;
+  triageTags: string;
+  spamSignal: number;
+  prioritySignal: number;
+}
+
+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 },
+  };
+}
+
+/**
+ * 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: OperatorSqliteStore,
+  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: OperatorSqliteStore,
+  itemId: string,
+): TriageMetadata | null {
+  const row = store.get<{
+    triageScore: number;
+    triageLabel: string;
+    triageTags: string;
+    spamSignal: number;
+    prioritySignal: number;
+  }>(
+    `SELECT triageScore, triageLabel, triageTags, spamSignal, prioritySignal
+       FROM inbox_triage WHERE id = ?`,
+    [itemId],
+  );
+  if (!row) return null;
+  return rowToMetadata(row);
+}

package/src/daemon/triage/register.ts

@@ -0,0 +1,231 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage surface REGISTRATION.
+//
+// Registers the internal methods inbox.triage.list and inbox.triage.tag with
+// transport ['internal'] ONLY — deliberately NOT 'ws'. This keeps them OFF the
+// agent-facing WS method list while remaining invocable by the inbox poller
+// internally. Access is 'operator'.
+//
+// If these are ever promoted to agent-facing methods, their IDs must move to a
+// separate handoff (per the contract); they must not be added to 'ws' here.
+// ---------------------------------------------------------------------------
+
+import {
+  OperatorError,
+  declareOperatorMethods,
+  type InboundChannelItem,
+  type OperatorContext,
+  type SurfaceRegister,
+  type Unregister,
+} from '../operator/index.ts';
+import { runInboxTriage, type RunInboxTriageOptions } from './pipeline.ts';
+import { createTriageTagger, type TriageTaggerOptions } from './tagger.ts';
+import type { TriageLabel } from './scorer.ts';
+
+export const TRIAGE_METHOD_IDS = {
+  // Internal step name per the handoff contract (line 612): the scoring step is
+  // 'inbox.triage.list' (it lists scored items), the mutation step is
+  // 'inbox.triage.tag'. These are non-published, transport ['internal'] only.
+  list: 'inbox.triage.list',
+  tag: 'inbox.triage.tag',
+} as const;
+
+const SCORE_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['items'],
+  additionalProperties: false,
+  properties: {
+    items: {
+      type: 'array',
+      items: { type: 'object' },
+      description: 'InboundChannelItem[] to score.',
+    },
+    persist: {
+      type: 'boolean',
+      description:
+        'Omit or set true to persist triageScore/triageTags to the inbox triage store; set false to dry-run (compute scores only, no write).',
+    },
+  },
+};
+
+const SCORE_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['items', 'scored', 'persisted'],
+  properties: {
+    scored: { type: 'number' },
+    persisted: { type: 'number' },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          triage: {
+            type: 'object',
+            properties: {
+              triageScore: { type: 'number' },
+              triageLabel: { type: 'string', enum: ['spam', 'priority', 'normal'] },
+              triageTags: { type: 'array', items: { type: 'string' } },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+// NOTE: `confirm` is deliberately ABSENT from this advertised schema. Per the
+// operator-confirm-contract-fidelity pattern, confirmed methods must NOT
+// advertise `confirm` in their inputSchema; enforcement is body-level via
+// assertConfirmed (register-helper.ts), which reads body.confirm from the raw
+// untyped invocation body. Keeping it out of the schema makes this an exact
+// match to the handoff Input contract instead of a strict superset.
+const TAG_INPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['item'],
+  additionalProperties: false,
+  properties: {
+    item: { type: 'object', description: 'InboundChannelItem to tag provider-side.' },
+    tags: { type: 'array', items: { type: 'string' } },
+    label: { type: 'string', enum: ['spam', 'priority', 'normal'] },
+  },
+};
+
+const TAG_OUTPUT_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  required: ['surface', 'itemId', 'appliedTags', 'skipped'],
+  properties: {
+    surface: { type: 'string' },
+    itemId: { type: 'string' },
+    appliedTags: { type: 'array', items: { type: 'string' } },
+    skipped: { type: 'boolean' },
+    reason: { type: 'string' },
+  },
+};
+
+interface ScoreBody {
+  items?: unknown;
+  persist?: unknown;
+}
+
+interface TagBody {
+  item?: unknown;
+  tags?: unknown;
+  label?: unknown;
+  confirm?: unknown;
+}
+
+function asInboundItems(value: unknown): InboundChannelItem[] {
+  if (!Array.isArray(value)) {
+    throw new OperatorError('`items` must be an array of inbound items.', 'TRIAGE_INVALID_INPUT', 400);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new OperatorError(`items[${index}] is not an object.`, 'TRIAGE_INVALID_INPUT', 400);
+    }
+    const item = entry as Partial<InboundChannelItem>;
+    if (typeof item.id !== 'string' || typeof item.surface !== 'string') {
+      throw new OperatorError(
+        `items[${index}] requires string id and surface.`,
+        'TRIAGE_INVALID_INPUT',
+        400,
+      );
+    }
+    return item as InboundChannelItem;
+  });
+}
+
+function asInboundItem(value: unknown): InboundChannelItem {
+  const [item] = asInboundItems([value]);
+  return item!;
+}
+
+export interface RegisterTriageOptions {
+  pipeline?: RunInboxTriageOptions;
+  tagger?: TriageTaggerOptions;
+}
+
+/**
+ * SurfaceRegister for the daemon-internal triage surface.
+ *
+ * Wiring contract: the daemon integration layer (services.ts, the single
+ * allowed edit site there) calls `registerTriageMethods(ctx)` once with the
+ * OperatorContext and retains the returned Unregister for teardown. For the
+ * full poll -> score -> persist -> list enrichment loop the contract relies on,
+ * compose it via `registerTriagedInbox` (see ./integration.ts), which is
+ * directly exercised by the integration test.
+ */
+export function createTriageRegister(options: RegisterTriageOptions = {}): SurfaceRegister {
+  return (ctx: OperatorContext): Unregister => {
+    const tagger = createTriageTagger(ctx, options.tagger);
+
+    return declareOperatorMethods(ctx, [
+      {
+        descriptor: {
+          id: TRIAGE_METHOD_IDS.list,
+          title: 'Inbox Triage — List (score)',
+          description:
+            'Daemon-internal: score inbound items for spam/priority and optionally persist triageScore/triageTags.',
+          category: 'inbox',
+          source: 'daemon',
+          access: 'operator',
+          transport: ['internal'],
+          scopes: ['inbox:triage'],
+          effect: 'local-state-mutation',
+          inputSchema: SCORE_INPUT_SCHEMA,
+          outputSchema: SCORE_OUTPUT_SCHEMA,
+        },
+        handler: async (input) => {
+          const body = (input.body ?? {}) as ScoreBody;
+          const items = asInboundItems(body.items);
+          const dryRun = body.persist === false;
+          return runInboxTriage(items, ctx, { ...options.pipeline, dryRun });
+        },
+      },
+      {
+        descriptor: {
+          id: TRIAGE_METHOD_IDS.tag,
+          title: 'Inbox Triage — Tag',
+          description:
+            'Daemon-internal: apply a triage label back on the provider side (IMAP flag / Slack or Discord reaction).',
+          category: 'inbox',
+          source: 'daemon',
+          access: 'operator',
+          transport: ['internal'],
+          scopes: ['inbox:triage', 'inbox:triage:write'],
+          effect: 'confirmed-connected-host-state',
+          confirm: true,
+          inputSchema: TAG_INPUT_SCHEMA,
+          outputSchema: TAG_OUTPUT_SCHEMA,
+        },
+        handler: async (input) => {
+          const body = (input.body ?? {}) as TagBody;
+          const item = asInboundItem(body.item);
+          const tags = Array.isArray(body.tags)
+            ? body.tags.filter((t): t is string => typeof t === 'string')
+            : undefined;
+          const label =
+            typeof body.label === 'string' ? (body.label as TriageLabel) : undefined;
+          return tagger.applyTags({
+            item,
+            tags,
+            label,
+            // confirm:true is enforced by the declareOperatorMethod guard before
+            // we reach here; mirror both flags into the tagger for defense-in-depth.
+            confirm: body.confirm === true,
+            explicitUserRequest: input.context.explicitUserRequest === true,
+          });
+        },
+      },
+    ]);
+  };
+}
+
+/**
+ * Default SurfaceRegister export. Integration may import either this `register`
+ * or `registerTriageMethods` (alias) and call it with the OperatorContext.
+ */
+export const register: SurfaceRegister = createTriageRegister();
+
+/** Named alias matching the integration contract (registerTriageMethods). */
+export const registerTriageMethods: SurfaceRegister = register;