clearhand 0.1.0

package/dist/mcp/index.js

@@ -0,0 +1,159 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+/**
+ * clearhand-mcp: a thin, deterministic MCP server exposing the local ClearHand
+ * HTTP API as typed tools. ZERO business logic here — every guard (lint,
+ * freshness, CAS, proration, resolve-guard, redaction) lives server-side, so
+ * a prompt-injected agent gains nothing by calling these creatively.
+ *
+ * Non-2xx responses are surfaced verbatim so the agent can react to a 409
+ * ("pending_financial_actions") by executing the refund first.
+ *
+ * Env: CLEARHAND_BASE_URL (default http://localhost:3117),
+ *      CLEARHAND_EXECUTE_TOKEN (forwarded as bearer ONLY by the execute tool).
+ */
+const BASE = process.env.CLEARHAND_BASE_URL ?? 'http://localhost:3117';
+async function call(method, path, body, token) {
+    try {
+        const res = await fetch(`${BASE}${path}`, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: 'text', text: `HTTP ${res.status}: ${text}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Could not reach the ClearHand server at ${BASE} — is it running? (clearhand start) ${String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+const server = new McpServer({ name: 'clearhand', version: '0.1.0' });
+server.tool('clearhand_status', 'Connection/capability map (metadata only, never secret values), overlay files, and queue counts. Call this first to learn what enrichment is possible. If a connector is missing, send the USER to its connect_url — never ask for credentials in chat.', {}, async () => call('GET', '/api/status'));
+server.tool('clearhand_sync_inbox', 'Fetch new mail from the connected inbox into cases. Returns scanned/ingested/newCases counts.', {}, async () => call('POST', '/api/sync'));
+server.tool('clearhand_list_cases', 'List support cases. status: new|processed|reviewing|pending|resolved|escalated|ignored. search covers subjects, customer emails, summaries AND message bodies. sort: updated (default) | oldest (work a backlog front-to-back) | money_first (cases owing refunds/cancels surface first). date_from/date_to (ISO) and offset page through large backlogs.', {
+    status: z.string().optional(),
+    search: z.string().optional(),
+    sort: z.enum(['updated', 'oldest', 'money_first']).optional(),
+    date_from: z.string().optional(),
+    date_to: z.string().optional(),
+    limit: z.number().int().max(200).optional(),
+    offset: z.number().int().optional(),
+}, async (args) => {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(args))
+        if (v !== undefined)
+            q.set(k, String(v));
+    return call('GET', `/api/cases?${q}`);
+});
+server.tool('clearhand_get_case', 'Full case detail: conversation, current draft, proposed actions, enrichment (prepared_context).', { case_id: z.number().int() }, async (args) => call('GET', `/api/cases/${args.case_id}`));
+server.tool('clearhand_enrich_case', 'Run server-side Stripe enrichment for the case customer (LTV, subscriptions, charges, refund history). The stripe context slice is server-owned and trustworthy.', { case_id: z.number().int() }, async (args) => call('POST', `/api/cases/${args.case_id}/enrich`));
+server.tool('clearhand_update_case', 'Set triage fields on a case: category, priority (low|normal|high|urgent), summary, language.', {
+    case_id: z.number().int(),
+    category: z.string().optional(),
+    priority: z.string().optional(),
+    summary: z.string().optional(),
+    language: z.string().optional(),
+}, async ({ case_id, ...rest }) => call('PATCH', `/api/cases/${case_id}`, rest));
+server.tool('clearhand_patch_context', 'Attach qualitative context slices to a case: customer_history, site_facts, notes, bug_repro. Stripe-shaped data is rejected — the money slice is server-owned.', { case_id: z.number().int(), context: z.record(z.unknown()) }, async (args) => call('PATCH', `/api/cases/${args.case_id}/context`, args.context));
+server.tool('clearhand_update_draft', 'Create/replace the current reply draft for a case. Returns tone-lint warnings from the overlay config.', {
+    case_id: z.number().int(),
+    body_english: z.string(),
+    body_translated: z.string().optional(),
+    target_language: z.string().optional(),
+}, async ({ case_id, ...rest }) => call('POST', `/api/cases/${case_id}/update-draft`, { ...rest, created_by: 'agent' }));
+server.tool('clearhand_propose_action', 'Propose a typed action (Action Proposal v1). Types: refund (amount_cents!), cancel_subscription (cancel_mode: immediate|end_of_period|scheduled), send_reply (body_text = the real body), escalate (reason), set_case_status (target_status: resolved|pending|ignored), create_github_issue (title, body). Proposals are linted and NEVER executed without human approval. Money moves earlier in execution_order by default.', {
+    case_id: z.number().int(),
+    action_type: z.enum([
+        'refund',
+        'cancel_subscription',
+        'send_reply',
+        'escalate',
+        'set_case_status',
+        'create_github_issue',
+    ]),
+    proposal: z.record(z.unknown()),
+    execution_order: z.number().int().optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    policy_matched: z.string().optional(),
+}, async ({ case_id, ...rest }) => call('POST', `/api/cases/${case_id}/actions`, rest));
+server.tool('clearhand_execute_actions', 'THE ONLY MONEY PATH. Approve and execute previously proposed actions, in execution order, through the deterministic executor (CAS claim, confirm-before-success, proration + resolve guards). Requires the human-held CLEARHAND_EXECUTE_TOKEN when configured — by default, direct the user to the dashboard Approve button instead of calling this.', {
+    case_id: z.number().int(),
+    action_ids: z.array(z.number().int()).min(1),
+    send_mode: z.enum(['translated', 'english', 'both']).optional(),
+    allow_pending_financial: z.boolean().optional(),
+}, async ({ case_id, action_ids, send_mode, allow_pending_financial }) => call('POST', `/api/cases/${case_id}/actions/execute`, { actionIds: action_ids, sendMode: send_mode, allow_pending_financial }, process.env.CLEARHAND_EXECUTE_TOKEN));
+server.tool('clearhand_send_reply', 'Send a reply directly (marks pending send_reply proposals executed; never executes financial actions). Returns 409 if a refund/cancel is still un-executed on the case — execute those first.', {
+    case_id: z.number().int(),
+    body: z.string(),
+    allow_pending_financial: z.boolean().optional(),
+}, async ({ case_id, ...rest }) => call('POST', `/api/cases/${case_id}/send-reply`, rest));
+server.tool('clearhand_set_case_status', 'Change case status. Setting "resolved" is blocked with 409 while financial actions are un-executed (the resolve-guard).', {
+    case_id: z.number().int(),
+    status: z.enum(['new', 'processed', 'reviewing', 'pending', 'resolved', 'escalated', 'ignored']),
+    allow_pending_financial: z.boolean().optional(),
+}, async ({ case_id, ...rest }) => call('POST', `/api/cases/${case_id}/status`, rest));
+server.tool('clearhand_extract_sent_samples', 'ONBOARDING: read recent sent mail (locally, transiently) to learn the user’s voice, de-facto policies, and FAQ answers. Synthesize the results into .clearhand/overlay/*.md files.', { limit: z.number().int().max(500).optional(), since_days: z.number().int().max(365).optional() }, async (args) => call('POST', '/api/extract/sent-samples', { limit: args.limit, sinceDays: args.since_days }));
+server.tool('clearhand_extract_stripe_summary', 'ONBOARDING: product/price catalog plus actual refund practice stats from Stripe, for evidence-based policy questions.', {}, async () => call('POST', '/api/extract/stripe-summary'));
+server.tool('clearhand_crawl_site', 'ONBOARDING: fetch the user’s own public pages (pricing, ToS, refund policy, FAQ) as text for overlay synthesis.', { urls: z.array(z.string()).min(1).max(20) }, async (args) => call('POST', '/api/extract/crawl', { urls: args.urls }));
+server.tool('clearhand_save_calibration', 'ONBOARDING: save a shadow-draft calibration pair (your draft vs what the user actually sent) for review on the dashboard Calibration screen.', {
+    customer_message: z.string(),
+    clearhand_draft: z.string(),
+    actual_reply: z.string().optional(),
+    context_note: z.string().optional(),
+}, async (args) => call('POST', '/api/calibrations', args));
+server.tool('clearhand_get_feedback', 'LEARNING LOOP: read recent human corrections — draft edits (original vs modified), action modifications with per-key diffs, rejections, supersessions, calibration verdicts. Review these at session end; a correction pattern that repeats is a rule waiting to be written.', {}, async () => call('GET', '/api/feedback'));
+server.tool('clearhand_get_calibrations', 'LEARNING LOOP: read shadow-draft calibrations including the user’s verdicts (fine | edited | wrong_policy | wrong_facts | wrong_tone) and notes. Fold every wrong_* verdict back into the overlay.', {}, async () => call('GET', '/api/calibrations'));
+server.tool('clearhand_propose_learning_review', 'LEARNING LOOP: propose a rule change distilled from repeated corrections. The user approves or rejects it on the dashboard (Activity page) — the human gate. proposed_rule: the exact rule text; target_file: which overlay file it belongs in (voice.md | policies.md | products.md | escalation.md | tone-lint.json).', {
+    case_id: z.number().int().optional(),
+    category: z.string().optional(),
+    proposed_rule: z.string(),
+    target_file: z.enum(['voice.md', 'policies.md', 'products.md', 'escalation.md', 'tone-lint.json']),
+    target_section: z.string().optional(),
+}, async (args) => call('POST', '/api/learning-reviews', args));
+server.tool('clearhand_get_learning_reviews', 'LEARNING LOOP: list rule-change reviews and their states (proposed → human approves/rejects → you apply). Apply every APPROVED review to its overlay file, then mark it applied.', {}, async () => call('GET', '/api/learning-reviews'));
+server.tool('clearhand_mark_review_applied', 'LEARNING LOOP: mark an APPROVED learning review as applied — call this only AFTER the overlay edit actually landed on disk. Approve/reject themselves are human-only (dashboard).', { review_id: z.number().int() }, async ({ review_id }) => call('POST', `/api/learning-reviews/${review_id}/resolve`, { status: 'applied' }));
+server.tool('clearhand_onboarding_progress', 'ONBOARDING: drive the GUI while you work. Advance a stage (status: active|done|skipped) and/or emit a progress event the user watches live. Event kinds: activity {line} (one-line present tense, replaced in place), finding {track, chip|card...} (evidence with counts — receipts, not theater), conflict {question, options}, artifact {name, bytes}, batch_case {group, title, note}, batch_done {processed, drafts, money, escalated, ignorable}. Emit events as the work actually happens; never simulate.', {
+    stage: z.enum([
+        'arrival',
+        'mailbox',
+        'stripe',
+        'reading_products',
+        'reading_voice',
+        'reading_policies',
+        'style',
+        'calibration',
+        'first_batch',
+        'live',
+    ]),
+    status: z.enum(['active', 'done', 'skipped']).optional(),
+    event: z
+        .object({
+        kind: z.enum(['activity', 'finding', 'conflict', 'artifact', 'batch_case', 'batch_done', 'note']),
+        payload: z.record(z.unknown()),
+    })
+        .optional(),
+}, async ({ stage, status, event }) => {
+    if (status)
+        await call('PATCH', '/api/onboarding/stage', { stage, status });
+    if (event)
+        return call('POST', '/api/onboarding/events', { stage, kind: event.kind, payload: event.payload });
+    return call('GET', '/api/onboarding');
+});
+server.tool('clearhand_get_onboarding', 'ONBOARDING: read the state machine — stage statuses, and the user\'s confirmations from the GUI (chip answers, conflict resolutions, handling_style with the behavior contract). Read these back BEFORE finalizing overlay files.', {}, async () => call('GET', '/api/onboarding'));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/server/connectors/crawl.js

@@ -0,0 +1,52 @@
+import { recordEgress } from '../trust/egress.js';
+function htmlToText(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<br\s*\/?>(?=\s*\S)/gi, '\n')
+        .replace(/<\/(p|div|li|h[1-6]|tr)>/gi, '\n')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#39;|&apos;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n\s*\n\s*\n+/g, '\n\n')
+        .trim();
+}
+export async function crawlPages(db, urls, maxChars = 20_000) {
+    const pages = [];
+    for (const url of urls.slice(0, 20)) {
+        try {
+            const u = new URL(url);
+            if (u.protocol !== 'https:' && u.protocol !== 'http:') {
+                pages.push({ url, ok: false, title: null, text: null, error: 'unsupported protocol' });
+                continue;
+            }
+            recordEgress(db, u.hostname, 'onboarding extraction (site crawl)');
+            const res = await fetch(url, {
+                headers: { 'User-Agent': 'clearhand-onboarding/0.1 (+local extraction of your own site)' },
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!res.ok) {
+                pages.push({ url, ok: false, title: null, text: null, error: `HTTP ${res.status}` });
+                continue;
+            }
+            const html = await res.text();
+            const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1]?.trim() ?? null;
+            pages.push({ url, ok: true, title, text: htmlToText(html).slice(0, maxChars) });
+        }
+        catch (err) {
+            pages.push({
+                url,
+                ok: false,
+                title: null,
+                text: null,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return pages;
+}

package/dist/server/connectors/github.js

@@ -0,0 +1,45 @@
+import { recordEgress } from '../trust/egress.js';
+export const GITHUB_SECRET_NAME = 'github_token';
+const GITHUB_HOST = 'api.github.com';
+export async function verifyGithub(db, secrets, cfg) {
+    try {
+        const token = secrets.use(GITHUB_SECRET_NAME, 'verify github token');
+        recordEgress(db, GITHUB_HOST, 'verify github token');
+        const res = await fetch(`https://${GITHUB_HOST}/repos/${cfg.repo}`, {
+            headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' },
+        });
+        if (!res.ok)
+            return { ok: false, error: `GitHub responded ${res.status} for ${cfg.repo}` };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function makeGithubOps(db, secrets, cfg) {
+    return {
+        async createIssue(params, ref) {
+            const token = secrets.use(GITHUB_SECRET_NAME, `create issue: ${params.title}`, ref);
+            recordEgress(db, GITHUB_HOST, 'create issue');
+            const res = await fetch(`https://${GITHUB_HOST}/repos/${cfg.repo}/issues`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/vnd.github+json',
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    title: params.title,
+                    body: params.body,
+                    ...(params.labels ? { labels: params.labels } : {}),
+                }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`GitHub issue creation failed: ${res.status} ${text.slice(0, 300)}`);
+            }
+            const issue = (await res.json());
+            return { number: issue.number, url: issue.html_url };
+        },
+    };
+}

package/dist/server/connectors/mailbox.js

@@ -0,0 +1,257 @@
+import { ImapFlow } from 'imapflow';
+import { simpleParser } from 'mailparser';
+import nodemailer from 'nodemailer';
+import { audit, newestCaseForConversation, now } from '../db/index.js';
+import { recordEgress } from '../trust/egress.js';
+export const MAILBOX_SECRET_NAME = 'mailbox_password';
+export function gmailDefaults(address) {
+    return {
+        address,
+        imapHost: 'imap.gmail.com',
+        imapPort: 993,
+        smtpHost: 'smtp.gmail.com',
+        smtpPort: 465,
+    };
+}
+function imapClient(db, secrets, cfg, purpose) {
+    const pass = secrets.use(MAILBOX_SECRET_NAME, purpose);
+    recordEgress(db, cfg.imapHost, purpose);
+    return new ImapFlow({
+        host: cfg.imapHost,
+        port: cfg.imapPort,
+        secure: true,
+        auth: { user: cfg.address, pass },
+        logger: false,
+    });
+}
+export async function verifyMailbox(db, secrets, cfg) {
+    try {
+        const client = imapClient(db, secrets, cfg, 'verify mailbox login');
+        await client.connect();
+        await client.logout();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function upsertCustomer(db, email, name) {
+    db.prepare(`INSERT INTO customers (email, name, created_at, updated_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(email) DO UPDATE SET name = COALESCE(customers.name, excluded.name), updated_at = excluded.updated_at`).run(email, name, now(), now());
+    return db.prepare(`SELECT id FROM customers WHERE email = ?`).get(email).id;
+}
+function conversationKeyOf(parsed) {
+    const refs = parsed.references;
+    const root = Array.isArray(refs) ? refs[0] : refs;
+    return (root ?? parsed.inReplyTo ?? parsed.messageId ?? `no-id-${Date.now()}`).trim();
+}
+function normalizedSubject(subject) {
+    return subject
+        .replace(/^\s*((re|fwd?|fw)\s*:\s*)+/i, '')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 50);
+}
+/**
+ * Ingest recent inbox mail into cases.
+ *
+ * Threading rules ported from the ancestor system:
+ * - new activity attaches to the NEWEST case of a conversation, never the
+ *   original;
+ * - a message on a resolved/ignored thread opens a FRESH case linked via
+ *   parent_case_id (never reopen a case whose actions already executed);
+ * - dedupe is by provider Message-ID (unique index), plus a conservative
+ *   same-sender + normalized-subject match for clients that strip headers.
+ */
+export async function syncInbox(db, secrets, cfg, opts = {}) {
+    const client = imapClient(db, secrets, cfg, 'sync inbox');
+    const result = { scanned: 0, ingested: 0, newCases: 0, followUpCases: 0 };
+    await client.connect();
+    try {
+        const lock = await client.getMailboxLock('INBOX');
+        try {
+            const since = new Date(Date.now() - (opts.sinceDays ?? 7) * 86_400_000);
+            for await (const msg of client.fetch({ since }, { source: true })) {
+                result.scanned++;
+                const parsed = await simpleParser(msg.source);
+                const fromAddr = parsed.from?.value?.[0]?.address?.toLowerCase();
+                if (!fromAddr || fromAddr === cfg.address.toLowerCase())
+                    continue;
+                const messageId = parsed.messageId ?? null;
+                if (messageId &&
+                    db.prepare(`SELECT 1 FROM emails WHERE provider_message_id = ?`).get(messageId)) {
+                    continue;
+                }
+                const subject = parsed.subject ?? '(no subject)';
+                const convKey = conversationKeyOf(parsed);
+                let target = newestCaseForConversation(db, 'imap', convKey);
+                if (!target && !parsed.inReplyTo) {
+                    // Fallback threading for header-stripping clients: same sender,
+                    // same normalized subject, open case, within 7 days.
+                    target = db
+                        .prepare(`SELECT c.id, c.status FROM cases c
+                JOIN customers cu ON cu.id = c.customer_id
+               WHERE cu.email = ? AND c.status NOT IN ('resolved','ignored')
+                 AND c.created_at > ?
+               ORDER BY c.id DESC LIMIT 1`)
+                        .get(fromAddr, new Date(Date.now() - 7 * 86_400_000).toISOString());
+                    if (target) {
+                        const existing = db
+                            .prepare(`SELECT subject FROM cases WHERE id = ?`)
+                            .get(target.id);
+                        if (normalizedSubject(existing.subject ?? '') !== normalizedSubject(subject)) {
+                            target = undefined;
+                        }
+                    }
+                }
+                const customerId = upsertCustomer(db, fromAddr, parsed.from?.value?.[0]?.name ?? null);
+                let caseId;
+                if (!target) {
+                    caseId = createCase(db, customerId, convKey, subject, null);
+                    result.newCases++;
+                }
+                else if (['resolved', 'ignored'].includes(target.status)) {
+                    // Follow-up on a closed thread: fresh linked case.
+                    caseId = createCase(db, customerId, convKey, subject, target.id);
+                    result.followUpCases++;
+                }
+                else {
+                    caseId = target.id;
+                    db.prepare(`UPDATE cases SET updated_at = ? WHERE id = ?`).run(now(), caseId);
+                }
+                db.prepare(`INSERT OR IGNORE INTO emails
+             (case_id, direction, from_addr, to_addr, subject, body_text, body_html,
+              provider_message_id, in_reply_to, received_at, created_at)
+           VALUES (?, 'inbound', ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(caseId, fromAddr, parsed.to && !Array.isArray(parsed.to) ? (parsed.to.value?.[0]?.address ?? null) : null, subject, parsed.text ?? null, typeof parsed.html === 'string' ? parsed.html : null, messageId, parsed.inReplyTo ?? null, (parsed.date ?? new Date()).toISOString(), now());
+                result.ingested++;
+            }
+        }
+        finally {
+            lock.release();
+        }
+    }
+    finally {
+        await client.logout().catch(() => { });
+    }
+    audit(db, 'system', 'inbox_synced', { detail: result });
+    return result;
+}
+function createCase(db, customerId, convKey, subject, parentCaseId) {
+    const res = db
+        .prepare(`INSERT INTO cases (customer_id, source, conversation_key, subject, status, parent_case_id, created_at, updated_at)
+       VALUES (?, 'imap', ?, ?, 'new', ?, ?, ?)`)
+        .run(customerId, convKey, subject, parentCaseId, now(), now());
+    return Number(res.lastInsertRowid);
+}
+/**
+ * Cheap counts for the connect micro-payoff ("Found 1,284 conversations ·
+ * 312 sent replies") — STATUS calls only, no message bodies read.
+ */
+export async function mailboxInventory(db, secrets, cfg) {
+    const client = imapClient(db, secrets, cfg, 'connect inventory (message counts)');
+    await client.connect();
+    try {
+        const boxes = await client.list();
+        const sentFolder = boxes.find((b) => b.specialUse === '\\Sent')?.path ??
+            boxes.find((b) => /sent/i.test(b.path))?.path ??
+            'Sent';
+        const inbox = await client.status('INBOX', { messages: true });
+        let sentCount = 0;
+        try {
+            sentCount = (await client.status(sentFolder, { messages: true })).messages ?? 0;
+        }
+        catch {
+            // no sent folder is survivable — voice learning degrades, connect doesn't
+        }
+        return {
+            inboxMessages: inbox.messages ?? 0,
+            sentMessages: sentCount,
+            sentFolder,
+        };
+    }
+    finally {
+        await client.logout().catch(() => { });
+    }
+}
+/**
+ * Onboarding extraction: the user's sent mail is the richest context source
+ * (voice, de-facto policy, FAQ answers). Read locally, returned transiently
+ * for the agent to synthesize overlay files — never persisted by ClearHand.
+ */
+export async function fetchSentSamples(db, secrets, cfg, opts = {}) {
+    const client = imapClient(db, secrets, cfg, 'onboarding extraction (sent mail)');
+    const samples = [];
+    await client.connect();
+    try {
+        const boxes = await client.list();
+        const sentBox = boxes.find((b) => b.specialUse === '\\Sent')?.path ??
+            boxes.find((b) => /sent/i.test(b.path))?.path ??
+            'Sent';
+        const lock = await client.getMailboxLock(sentBox);
+        try {
+            const since = new Date(Date.now() - (opts.sinceDays ?? 90) * 86_400_000);
+            const limit = opts.limit ?? 200;
+            for await (const msg of client.fetch({ since }, { source: true })) {
+                const parsed = await simpleParser(msg.source);
+                samples.push({
+                    to: parsed.to && !Array.isArray(parsed.to) ? (parsed.to.value?.[0]?.address ?? null) : null,
+                    subject: parsed.subject ?? null,
+                    text: parsed.text?.slice(0, 4000) ?? null,
+                    date: parsed.date?.toISOString() ?? null,
+                    inReplyTo: parsed.inReplyTo ?? null,
+                });
+                if (samples.length >= limit)
+                    break;
+            }
+        }
+        finally {
+            lock.release();
+        }
+    }
+    finally {
+        await client.logout().catch(() => { });
+    }
+    return samples;
+}
+/**
+ * The executor's mailer. Replies thread onto the customer's original message
+ * (In-Reply-To/References) and go out through the provider's SMTP.
+ */
+export function makeMailer(db, secrets, cfg) {
+    return {
+        async sendReply(params) {
+            const lastInbound = db
+                .prepare(`SELECT provider_message_id, subject FROM emails
+            WHERE case_id = ? AND direction = 'inbound'
+            ORDER BY id DESC LIMIT 1`)
+                .get(params.caseId);
+            const pass = secrets.use(MAILBOX_SECRET_NAME, `send reply for case ${params.caseId}`, params.ref);
+            recordEgress(db, cfg.smtpHost, 'send customer reply');
+            const transport = nodemailer.createTransport({
+                host: cfg.smtpHost,
+                port: cfg.smtpPort,
+                secure: cfg.smtpPort === 465,
+                auth: { user: cfg.address, pass },
+            });
+            const subject = lastInbound?.subject
+                ? /^re:/i.test(lastInbound.subject)
+                    ? lastInbound.subject
+                    : `Re: ${lastInbound.subject}`
+                : 'Re: your message';
+            const info = await transport.sendMail({
+                from: cfg.displayName ? `"${cfg.displayName}" <${cfg.address}>` : cfg.address,
+                to: params.to,
+                subject,
+                text: params.body,
+                ...(lastInbound?.provider_message_id
+                    ? {
+                        inReplyTo: lastInbound.provider_message_id,
+                        references: lastInbound.provider_message_id,
+                    }
+                    : {}),
+            });
+            return { providerMessageId: info.messageId ?? null };
+        },
+    };
+}