@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/triage/tagger/imap.ts

@@ -0,0 +1,383 @@
+// ---------------------------------------------------------------------------
+// Triage tagger — IMAP provider.
+//
+// Applies a triage label as an IMAP keyword flag (STORE +FLAGS) over a minimal
+// IMAP4rev1-over-TLS client. Credentials are resolved per-apply from the daemon
+// credential store and are NEVER logged or returned. CRLF/control characters in
+// any interpolated command value are rejected (CRLF-injection guard). Transient
+// network failures are retried with bounded exponential backoff; protocol-level
+// NO/BAD rejections are deterministic and never retried.
+// ---------------------------------------------------------------------------
+
+import { connect as tlsConnect } from 'node:tls';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import type { InboundChannelItem } from '../types.ts';
+import type { ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
+import { imapKeywordForTag } from './shared.ts';
+
+export interface ImapStoreArgs {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  mailbox: string;
+  uid: string;
+  flag: string;
+}
+
+export interface ImapRetryOptions {
+  /** Total attempts including the first (default 3). Values < 1 disable retry. */
+  maxAttempts?: number;
+  /** Base backoff in ms for the first retry (default 250). */
+  baseDelayMs?: number;
+  /** Cap on any single backoff delay in ms (default 2000). */
+  maxDelayMs?: number;
+  /** Injectable sleep (tests). Defaults to a real timer. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export type ImapStoreFlag = (args: ImapStoreArgs) => Promise<void>;
+
+/**
+ * The minimal subset of a node:tls TLSSocket that imapStoreFlagOverTls drives.
+ * Declaring it explicitly (rather than depending on the full TLSSocket surface)
+ * gives the data-pump a precise injection seam: tests can supply an in-memory
+ * duplex that exercises the protocol state machine without a real network
+ * socket, while the production path passes the real tlsConnect result.
+ */
+export interface ImapSocketLike {
+  setEncoding(encoding: string): void;
+  setTimeout(ms: number, callback: () => void): void;
+  write(data: string): void;
+  on(event: 'data', listener: (chunk: string) => void): void;
+  on(event: 'error', listener: (err: Error) => void): void;
+  on(event: 'close', listener: () => void): void;
+  destroy(): void;
+}
+
+/** Connector seam: opens an ImapSocketLike for the given host/port. */
+export type ImapConnect = (opts: {
+  host: string;
+  port: number;
+  servername: string;
+}) => ImapSocketLike;
+
+/** Production connector — a real IMAP4rev1-over-TLS socket via node:tls. */
+export const tlsImapConnect: ImapConnect = (opts) =>
+  tlsConnect(opts, () => {
+    /* greeting handled in the data pump */
+  }) as unknown as ImapSocketLike;
+
+export async function applyImap(
+  item: InboundChannelItem,
+  tags: string[],
+  providers: TaggerProviderConfig,
+  credentials: DaemonCredentialStore,
+  storeFlag: ImapStoreFlag,
+  base: ApplyTagsResult,
+): Promise<ApplyTagsResult> {
+  const cfg = providers.imap;
+  if (!cfg) return { ...base, reason: 'imap-not-configured' };
+  const uid = imapUidFromItem(item);
+  if (!uid) return { ...base, reason: 'imap-missing-uid' };
+  if (tags.length === 0) return { ...base, reason: 'no-tags' };
+
+  const password = await credentials.resolveConfigSecret(cfg.passwordConfigKey);
+  if (!password) return { ...base, reason: 'imap-no-credentials' };
+
+  const applied: string[] = [];
+  for (const tag of tags) {
+    await storeFlag({
+      host: cfg.host,
+      port: cfg.port ?? 993,
+      user: cfg.user,
+      password,
+      mailbox: cfg.mailbox ?? 'INBOX',
+      uid,
+      flag: imapKeywordForTag(tag),
+    });
+    applied.push(tag);
+  }
+  return { surface: item.surface, itemId: item.id, appliedTags: applied, skipped: false };
+}
+
+function imapUidFromItem(item: InboundChannelItem): string | null {
+  const meta = item.metadata ?? {};
+  const uid = meta.imapUid ?? meta.uid;
+  if (typeof uid === 'string' && uid.length > 0) return uid;
+  if (typeof uid === 'number' && Number.isFinite(uid)) return String(uid);
+  return null;
+}
+
+/**
+ * Error subclass carrying whether a failure is transient (worth retrying) or a
+ * deterministic protocol rejection (NO/BAD) that must not be retried.
+ */
+export class ImapStoreError extends Error {
+  readonly transient: boolean;
+  constructor(message: string, transient: boolean) {
+    super(message);
+    this.name = 'ImapStoreError';
+    this.transient = transient;
+  }
+}
+
+/**
+ * Reject CR, LF, NUL and any other ASCII control character (0x00-0x1F, 0x7F)
+ * in a value destined for an IMAP command line. CR/LF are the dangerous ones:
+ * an unescaped CRLF would terminate the current command and let an attacker
+ * inject a second IMAP command (CRLF injection). IMAP's quoted-string syntax
+ * has no escape for these control chars — backslash only escapes `\` and `"` —
+ * so the only safe handling is to refuse the value outright.
+ */
+function assertImapSafe(value: string, field: string): void {
+  // eslint-disable-next-line no-control-regex -- intentional control-char guard
+  if (/[\x00-\x1F\x7F]/.test(value)) {
+    throw new ImapStoreError(
+      `IMAP ${field} contains illegal control characters (possible CRLF injection)`,
+      false,
+    );
+  }
+}
+
+/**
+ * Wrap a value as an IMAP quoted string. Backslash and double-quote are escaped
+ * per RFC 3501; control characters are NOT escapable in the quoted-string
+ * grammar, so callers MUST validate with assertImapSafe first. quoteImap
+ * re-asserts as defense-in-depth so no future caller can bypass the guard.
+ */
+function quoteImap(value: string): string {
+  assertImapSafe(value, 'value');
+  return `"${value.replace(/([\\"])/g, '\\$1')}"`;
+}
+
+// A concrete UID sequence-set: one or more comma-separated single UIDs or
+// numeric ranges (`12`, `3:9`, `1,4,7:9`). RFC 3501 also permits `*` (the
+// largest UID in the mailbox) and ranges to `*`, but a wildcard would let a
+// single value like `1:*` apply the flag to the ENTIRE mailbox — never the
+// intent when tagging one triaged item — so `*` is rejected outright.
+const IMAP_UID_SET = /^[0-9]+(:[0-9]+)?(,[0-9]+(:[0-9]+)?)*$/;
+
+// An IMAP flag: an optional leading `\` (system flag, e.g. `\Seen`) followed by
+// atom characters only. The atom grammar excludes SP and the list/quoting
+// specials `(){%*"\` and `]`, so a flag cannot contain a space (which would
+// otherwise inject a second flag atom into the `+FLAGS (...)` list) or close
+// the parenthesised list early.
+// eslint-disable-next-line no-control-regex -- atom grammar excludes controls
+const IMAP_FLAG = /^\\?[^\s(){%*"\\\]\x00-\x1F\x7F]+$/;
+
+/**
+ * Validate an IMAP UID value as a concrete sequence-set before it is
+ * interpolated UNQUOTED into `UID STORE`. assertImapSafe only blocks control
+ * chars; a control-char-free wildcard like `1:*` would still pass that guard
+ * and mutate the whole mailbox. This is the boundary check that prevents it.
+ */
+function assertImapUid(value: string): void {
+  if (!IMAP_UID_SET.test(value)) {
+    throw new ImapStoreError(
+      `IMAP uid is not a valid numeric sequence-set: ${JSON.stringify(value)}`,
+      false,
+    );
+  }
+}
+
+/**
+ * Validate an IMAP flag against the flag/atom grammar before it is interpolated
+ * UNQUOTED into the `+FLAGS (...)` list. assertImapSafe only blocks control
+ * chars; a flag containing a space (e.g. `\Seen Junk`) would still pass that
+ * guard and inject a second flag atom. This is the boundary check that
+ * prevents it — independent of any upstream normalizer.
+ */
+function assertImapFlag(value: string): void {
+  if (!IMAP_FLAG.test(value)) {
+    throw new ImapStoreError(
+      `IMAP flag is not a valid flag-keyword atom: ${JSON.stringify(value)}`,
+      false,
+    );
+  }
+}
+
+/**
+ * Minimal IMAP4rev1 client: connect over TLS, LOGIN, SELECT, UID STORE +FLAGS,
+ * LOGOUT. Uses only node:tls (Bun-compatible).
+ *
+ * Tagged-command sequencing uses an explicit completion flag rather than a line
+ * heuristic: the LOGOUT step is tracked by reference, so its tagged OK (or an
+ * untagged `* BYE`) cleanly completes the operation and tells the `close`
+ * handler the disconnect was expected. Connection/timeout/socket failures are
+ * surfaced as transient ImapStoreError; NO/BAD protocol responses as
+ * non-transient.
+ */
+export function imapStoreFlagOverTls(
+  args: ImapStoreArgs,
+  connect: ImapConnect = tlsImapConnect,
+): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    try {
+      assertImapSafe(args.user, 'user');
+      assertImapSafe(args.password, 'password');
+      assertImapSafe(args.mailbox, 'mailbox');
+      assertImapSafe(args.uid, 'uid');
+      assertImapSafe(args.flag, 'flag');
+      // uid and flag are interpolated UNQUOTED below; the control-char guard
+      // alone is insufficient, so enforce the structural grammar here too.
+      assertImapUid(args.uid);
+      assertImapFlag(args.flag);
+    } catch (err) {
+      reject(
+        err instanceof ImapStoreError
+          ? err
+          : new ImapStoreError(err instanceof Error ? err.message : String(err), false),
+      );
+      return;
+    }
+    type Step = { tag: string; isLogout: boolean; resolve: () => void; reject: (e: Error) => void };
+
+    let done = false;
+    let completed = false; // LOGOUT acknowledged (or BYE seen) — close is expected.
+    let buffer = '';
+    let pending: Step | null = null;
+    let counter = 0;
+    let greeted = false;
+
+    const finish = (err?: Error): void => {
+      if (done) return;
+      done = true;
+      try {
+        socket.destroy();
+      } catch {
+        /* ignore */
+      }
+      if (err) reject(err);
+      else resolve();
+    };
+
+    const socket: ImapSocketLike = connect({
+      host: args.host,
+      port: args.port,
+      servername: args.host,
+    });
+    socket.setEncoding('utf-8');
+    socket.setTimeout(20_000, () =>
+      finish(new ImapStoreError('IMAP connection timed out', true)),
+    );
+
+    const send = (command: string, isLogout = false): Promise<void> =>
+      new Promise<void>((res, rej) => {
+        counter += 1;
+        const tag = `A${counter}`;
+        pending = { tag, isLogout, resolve: res, reject: rej };
+        socket.write(`${tag} ${command}\r\n`);
+      });
+
+    const runSequence = async (): Promise<void> => {
+      await send(`LOGIN ${quoteImap(args.user)} ${quoteImap(args.password)}`);
+      await send(`SELECT ${quoteImap(args.mailbox)}`);
+      await send(`UID STORE ${args.uid} +FLAGS (${args.flag})`);
+      await send('LOGOUT', true);
+    };
+
+    const handleLine = (line: string): void => {
+      if (!greeted) {
+        greeted = true;
+        if (!/^\* (OK|PREAUTH)/i.test(line)) {
+          finish(new ImapStoreError(`IMAP server rejected connection: ${line}`, true));
+          return;
+        }
+        runSequence().catch((err) =>
+          finish(
+            err instanceof ImapStoreError
+              ? err
+              : new ImapStoreError(err instanceof Error ? err.message : String(err), false),
+          ),
+        );
+        return;
+      }
+
+      // An untagged BYE during LOGOUT is the server announcing a clean close.
+      if (/^\* BYE/i.test(line) && pending?.isLogout) {
+        completed = true;
+        return;
+      }
+
+      if (!pending) return;
+      if (!line.startsWith(`${pending.tag} `)) return; // untagged data line
+      const status = line.slice(pending.tag.length + 1);
+      const current = pending;
+      pending = null;
+      if (/^OK/i.test(status)) {
+        current.resolve();
+        if (current.isLogout) {
+          completed = true;
+          finish();
+        }
+      } else {
+        // NO/BAD: deterministic protocol rejection — do not retry.
+        current.reject(new ImapStoreError(`IMAP command failed: ${status}`, false));
+      }
+    };
+
+    socket.on('error', (err) =>
+      finish(new ImapStoreError(err instanceof Error ? err.message : String(err), true)),
+    );
+    socket.on('close', () => {
+      if (completed) finish();
+      else finish(new ImapStoreError('IMAP connection closed unexpectedly', true));
+    });
+    socket.on('data', (chunk: string) => {
+      buffer += chunk;
+      let newlineIdx = buffer.indexOf('\n');
+      while (newlineIdx !== -1) {
+        const line = buffer.slice(0, newlineIdx).replace(/\r$/, '');
+        buffer = buffer.slice(newlineIdx + 1);
+        handleLine(line);
+        newlineIdx = buffer.indexOf('\n');
+      }
+    });
+  });
+}
+
+/** True when an error is worth retrying (network/connection, not protocol). */
+function isTransientImapError(error: unknown): boolean {
+  if (error instanceof ImapStoreError) return error.transient;
+  const code = (error as { code?: unknown })?.code;
+  if (typeof code === 'string') {
+    return ['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'EAI_AGAIN']
+      .includes(code);
+  }
+  return false;
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((res) => setTimeout(res, ms));
+
+/**
+ * Wrap an IMAP store function with bounded exponential-backoff retry on
+ * transient failures only. Protocol-level (NO/BAD) errors are surfaced on the
+ * first attempt without retry.
+ */
+export function makeRetryingImapStoreFlag(
+  inner: ImapStoreFlag,
+  retry: ImapRetryOptions = {},
+): ImapStoreFlag {
+  const maxAttempts = Math.max(1, retry.maxAttempts ?? 3);
+  const baseDelayMs = Math.max(0, retry.baseDelayMs ?? 250);
+  const maxDelayMs = Math.max(baseDelayMs, retry.maxDelayMs ?? 2_000);
+  const sleep = retry.sleep ?? defaultSleep;
+
+  return async (args: ImapStoreArgs): Promise<void> => {
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      try {
+        await inner(args);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt >= maxAttempts || !isTransientImapError(error)) throw error;
+        const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+        await sleep(delay);
+      }
+    }
+    throw lastError;
+  };
+}

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

@@ -0,0 +1,184 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage TAGGER (composition).
+//
+// Applies user-defined triage labels back on the provider side:
+//   - IMAP : STORE a keyword flag on the message (IMAP4rev1 over TLS).
+//   - Slack: reactions.add emoji on the source message.
+//   - Discord: real forum thread tags (PATCH applied_tags, merge) when a
+//     forum-tag mapping is configured, else a unicode reaction analog.
+//
+// Hard rules honored here:
+//   - All provider credentials come ONLY from the daemon credential store.
+//     They are never returned in results and never logged.
+//   - The whole tagger is gated behind a config flag (surfaces.triage.autoTag);
+//     when disabled, applyTags() is a no-op that reports skipped:true.
+//   - Provider-side writes are EFFECTFUL; callers must pass an explicitly
+//     confirmed request (confirm === true && explicitUserRequest === true).
+//     Unconfirmed calls throw HandlerError(REQUIRE_CONFIRM).
+//
+// Contract-fidelity note: the triage surface (`inbox.triage.*`) is daemon-
+// internal and NOT a published operator method, so there is no external
+// request/response schema to certify these tag shapes against. What is
+// guaranteed is the provider-side behavior: no silent data loss (Discord thread
+// tags are merged, never blindly overwritten) and no command injection (IMAP
+// quoting rejects control characters).
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../../context.ts';
+import type { DaemonCredentialStore } from '../../credentials.ts';
+import { HandlerError, REQUIRE_CONFIRM } from '../../errors.ts';
+import { labelToTag } from '../scorer.ts';
+import { applyImap, imapStoreFlagOverTls, makeRetryingImapStoreFlag } from './imap.ts';
+import type { ImapRetryOptions, ImapStoreFlag } from './imap.ts';
+import { applySlack } from './slack.ts';
+import { applyDiscord } from './discord.ts';
+import type { ApplyTagsRequest, ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
+
+export type {
+  ApplyTagsRequest,
+  ApplyTagsResult,
+  TaggerProviderConfig,
+} from './shared.ts';
+export type { ImapRetryOptions, ImapStoreArgs, ImapStoreFlag } from './imap.ts';
+
+export const TRIAGE_AUTOTAG_FLAG = 'surfaces.triage.autoTag';
+
+export interface TriageTaggerOptions {
+  credentials?: DaemonCredentialStore;
+  /** Override the autotag flag lookup (used in tests). */
+  autoTagEnabled?: boolean;
+  /** Per-surface provider config; usually derived from configManager. */
+  providers?: TaggerProviderConfig;
+  /** Injectable fetch (Slack/Discord HTTP). Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Injectable IMAP flag-setter (used in tests to avoid a live socket). */
+  imapStoreFlag?: ImapStoreFlag;
+  /**
+   * Transient-failure retry policy for the default IMAP store implementation.
+   * Ignored when imapStoreFlag is injected and succeeds first-try.
+   */
+  imapRetry?: ImapRetryOptions;
+}
+
+export interface TriageTagger {
+  /** Whether provider-side tagging is currently enabled. */
+  enabled(): boolean;
+  applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult>;
+}
+
+function readBoolFlag(
+  configManager: HandlerContext['configManager'],
+  key: string,
+): boolean {
+  try {
+    const value = configManager.get(key as never) as unknown;
+    return value === true || value === 'true' || value === 1;
+  } catch {
+    return false;
+  }
+}
+
+function safeGet(configManager: HandlerContext['configManager'], key: string): unknown {
+  try {
+    return configManager.get(key as never) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveProvidersFromConfig(
+  configManager: HandlerContext['configManager'],
+): TaggerProviderConfig {
+  const out: TaggerProviderConfig = {};
+  const slackToken = safeGet(configManager, 'surfaces.slack.botToken');
+  if (typeof slackToken === 'string' && slackToken.length > 0) {
+    out.slack = { tokenConfigKey: 'surfaces.slack.botToken' };
+  }
+  const discordToken = safeGet(configManager, 'surfaces.discord.botToken');
+  if (typeof discordToken === 'string' && discordToken.length > 0) {
+    out.discord = { tokenConfigKey: 'surfaces.discord.botToken' };
+  }
+  const imapHost = safeGet(configManager, 'surfaces.email.imap.host');
+  const imapUser = safeGet(configManager, 'surfaces.email.imap.user');
+  if (typeof imapHost === 'string' && imapHost.length > 0 && typeof imapUser === 'string') {
+    const portRaw = safeGet(configManager, 'surfaces.email.imap.port');
+    const mailbox = safeGet(configManager, 'surfaces.email.imap.mailbox');
+    out.imap = {
+      host: imapHost,
+      port: typeof portRaw === 'number' ? portRaw : 993,
+      user: imapUser,
+      passwordConfigKey: 'surfaces.email.imap.password',
+      mailbox: typeof mailbox === 'string' && mailbox.length > 0 ? mailbox : 'INBOX',
+    };
+  }
+  return out;
+}
+
+function resolveTags(request: ApplyTagsRequest): string[] {
+  if (request.tags && request.tags.length > 0) {
+    return [...new Set(request.tags.map((t) => t.trim()).filter((t) => t.length > 0))];
+  }
+  if (request.label) return [labelToTag(request.label)];
+  return [];
+}
+
+/**
+ * Create the triage tagger. Reads the autotag flag and provider config from the
+ * handler context; credentials are resolved lazily, per apply, from the daemon
+ * credential store.
+ */
+export function createTriageTagger(
+  ctx: HandlerContext,
+  options: TriageTaggerOptions = {},
+): TriageTagger {
+  const credentials = options.credentials ?? ctx.credentials;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const providers = options.providers ?? resolveProvidersFromConfig(ctx.configManager);
+  // Retry wraps whichever store impl is in use (default TLS client OR an
+  // injected one), so transient failures are retried uniformly.
+  const imapStoreFlag = makeRetryingImapStoreFlag(
+    options.imapStoreFlag ?? imapStoreFlagOverTls,
+    options.imapRetry,
+  );
+  const enabled = (): boolean =>
+    options.autoTagEnabled ?? readBoolFlag(ctx.configManager, TRIAGE_AUTOTAG_FLAG);
+
+  return {
+    enabled,
+    async applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult> {
+      const { item } = request;
+      const tags = resolveTags(request);
+      const base: ApplyTagsResult = {
+        surface: item.surface,
+        itemId: item.id,
+        appliedTags: [],
+        skipped: true,
+      };
+
+      if (!enabled()) {
+        return { ...base, reason: 'autotag-disabled' };
+      }
+
+      // Provider-side mutation is effectful — require explicit confirmation.
+      if (request.confirm !== true || request.explicitUserRequest !== true) {
+        throw new HandlerError(
+          'Provider-side triage tagging requires explicit user confirmation.',
+          REQUIRE_CONFIRM,
+          403,
+        );
+      }
+
+      switch (item.surface) {
+        case 'email':
+        case 'imap':
+          return applyImap(item, tags, providers, credentials, imapStoreFlag, base);
+        case 'slack':
+          return applySlack(item, tags, providers, credentials, fetchImpl, ctx, base);
+        case 'discord':
+          return applyDiscord(item, tags, providers, credentials, fetchImpl, ctx, base);
+        default:
+          return { ...base, reason: `unsupported-surface:${item.surface}` };
+      }
+    },
+  };
+}

package/src/daemon/handlers/triage/tagger/shared.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Triage tagger — shared types and provider-agnostic helpers.
+//
+// Provider config shapes, the apply request/result contract, and the tag
+// normalization helpers used by the IMAP/Slack/Discord modules. No I/O here.
+// ---------------------------------------------------------------------------
+
+import type { InboundChannelItem, TriageLabel } from '../types.ts';
+
+export interface TaggerProviderConfig {
+  /** IMAP host:port (default port 993, TLS). Credentials resolved separately. */
+  imap?: { host: string; port?: number; user: string; passwordConfigKey: string; mailbox?: string };
+  /** Slack bot token config key (resolved from credential store). */
+  slack?: { tokenConfigKey: string };
+  /**
+   * Discord bot token config key (resolved from credential store), plus an
+   * optional forum-tag mapping. When `forumTagIds` maps a GoodVibes triage tag
+   * (e.g. 'GoodVibes/Spam') to a forum tag SNOWFLAKE id, items that target a
+   * forum/media-channel thread get that REAL thread tag applied (PATCH
+   * applied_tags) — exact fidelity to the contract's "Discord thread tags".
+   * Without a mapping (or for non-thread messages) tagging degrades to a
+   * unicode reaction analog.
+   */
+  discord?: { tokenConfigKey: string; forumTagIds?: Record<string, string> };
+}
+
+export interface ApplyTagsRequest {
+  item: InboundChannelItem;
+  /** Provider-side tags to apply. Defaults to [labelToTag(label)] when omitted. */
+  tags?: readonly string[];
+  label?: TriageLabel;
+  /** Must be true — provider-side mutation requires explicit confirmation. */
+  confirm?: boolean;
+  /** Mirror of the operator invocation context flag. */
+  explicitUserRequest?: boolean;
+}
+
+export interface ApplyTagsResult {
+  surface: string;
+  itemId: string;
+  appliedTags: string[];
+  /** True when the autotag flag is disabled or no provider matched. */
+  skipped: boolean;
+  reason?: string;
+}
+
+/** IMAP keywords cannot contain spaces or '/'; normalize the canonical tag. */
+export function imapKeywordForTag(tag: string): string {
+  return tag.replace(/[^A-Za-z0-9_]+/g, '_');
+}
+
+export function slackEmojiForTag(tag: string): string {
+  const lower = tag.toLowerCase();
+  if (lower.includes('spam')) return 'no_entry_sign';
+  if (lower.includes('priority')) return 'rotating_light';
+  return 'inbox_tray';
+}
+
+export function discordEmojiForTag(tag: string): string {
+  const lower = tag.toLowerCase();
+  if (lower.includes('spam')) return '\u{1F6AB}';
+  if (lower.includes('priority')) return '\u{1F6A8}';
+  return '\u{1F4E5}';
+}
+
+/** Read a non-empty string from the item's opaque metadata bag. */
+export function stringMeta(item: InboundChannelItem, key: string): string | undefined {
+  const value = item.metadata?.[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}