clearhand 0.1.0

package/dist/server/services/executor.js

@@ -0,0 +1,417 @@
+import { audit, now } from '../db/index.js';
+import { effectiveProposal, isValidStripeId } from '../../shared/actions.js';
+/**
+ * The CAS claim — the double-execute guard. Safe because better-sqlite3 is
+ * synchronous single-writer: the conditional UPDATE and its `changes` count
+ * are one atomic step, and no `await` can interleave between claim and check.
+ *
+ * `failed` is claimable on purpose: operator retry of a failed action is
+ * intentional, made safe by the idempotent-error mappings below.
+ * (Deviation from the ancestor: `proposed` is NOT claimable here — execution
+ * strictly requires prior approval through the pipeline.)
+ */
+export function claimActionForExecution(db, actionId) {
+    const res = db
+        .prepare(`UPDATE actions SET status = 'executing'
+        WHERE id = ? AND status IN ('approved','failed')`)
+        .run(actionId);
+    return res.changes === 1;
+}
+function getAction(db, actionId) {
+    return db.prepare(`SELECT * FROM actions WHERE id = ?`).get(actionId);
+}
+function finish(db, action, result) {
+    if (result.success) {
+        db.prepare(`UPDATE actions SET status = 'executed', executed_at = ?, result_json = ?, error_message = NULL
+        WHERE id = ?`).run(now(), JSON.stringify(result.details ?? {}), action.id);
+    }
+    else {
+        db.prepare(`UPDATE actions SET status = 'failed', error_message = ? WHERE id = ?`).run(result.message, action.id);
+    }
+    audit(db, 'system', 'action_execution', {
+        caseId: action.case_id,
+        actionId: action.id,
+        phase: result.success ? 'success' : 'failure',
+        detail: { message: result.message, ...result.details },
+    });
+    return result;
+}
+export async function executeAction(deps, actionId, opts = {}) {
+    const { db } = deps;
+    const pre = getAction(db, actionId);
+    if (!pre)
+        return { success: false, message: `action ${actionId} not found` };
+    if (!claimActionForExecution(db, actionId)) {
+        // Lost the race (or the action is not in a claimable state). Idempotent
+        // no-op — success only if the work is genuinely done.
+        const current = getAction(db, actionId);
+        const status = current?.status ?? 'missing';
+        audit(db, 'system', 'action_execution', {
+            caseId: pre.case_id,
+            actionId,
+            phase: 'start',
+            detail: { skipped: true, reason: `not claimable from status '${status}'` },
+        });
+        return {
+            success: status === 'executed',
+            message: `already '${status}' — not re-executed`,
+            details: { idempotent_noop: true },
+        };
+    }
+    const action = getAction(db, actionId);
+    const proposal = effectiveProposal(action);
+    const ref = `action:${action.id}`;
+    audit(db, 'system', 'action_execution', {
+        caseId: action.case_id,
+        actionId: action.id,
+        phase: 'start',
+        detail: { action_type: action.action_type },
+    });
+    try {
+        let result;
+        switch (action.action_type) {
+            case 'refund':
+                result = await runRefund(deps, action, proposal, ref);
+                break;
+            case 'cancel_subscription':
+                result = await runCancel(deps, action, proposal, ref);
+                break;
+            case 'send_reply':
+                result = await runSendReply(deps, action, proposal, opts.sendMode ?? 'translated', ref);
+                break;
+            case 'create_github_issue':
+                result = await runGithubIssue(deps, action, proposal, ref);
+                break;
+            default:
+                result = {
+                    success: false,
+                    message: `Unsupported action_type "${action.action_type}" — status actions execute inline in the approval pipeline`,
+                };
+        }
+        return finish(db, action, result);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        audit(db, 'system', 'action_execution', {
+            caseId: action.case_id,
+            actionId: action.id,
+            phase: 'error',
+            detail: { message },
+        });
+        return finish(db, action, { success: false, message });
+    }
+}
+// ---------------------------------------------------------------- refund --
+async function runRefund(deps, action, proposal, ref) {
+    const { db } = deps;
+    // Rescue: a sub_… mistakenly placed in charge_id becomes subscription_id.
+    let chargeId = typeof proposal.charge_id === 'string' ? proposal.charge_id : undefined;
+    let subscriptionId = typeof proposal.subscription_id === 'string' ? proposal.subscription_id : undefined;
+    if (chargeId && isValidStripeId(chargeId, 'sub_')) {
+        subscriptionId = chargeId;
+        chargeId = undefined;
+    }
+    const chargeValid = chargeId !== undefined &&
+        (isValidStripeId(chargeId, 'ch_') || isValidStripeId(chargeId, 'py_'));
+    if (!chargeValid)
+        chargeId = undefined;
+    // Tiered resolution: enrichment snapshot first, then live latest-paid-invoice.
+    if (!chargeId) {
+        chargeId = resolveChargeFromContext(db, action.case_id, proposal) ?? undefined;
+    }
+    if (!chargeId && subscriptionId && isValidStripeId(subscriptionId, 'sub_')) {
+        audit(db, 'system', 'action_execution', {
+            caseId: action.case_id, actionId: action.id, phase: 'api_call',
+            detail: { op: 'latestPaidInvoiceCharge', subscriptionId },
+        });
+        chargeId = (await deps.stripe.latestPaidInvoiceCharge(subscriptionId, ref)) ?? undefined;
+    }
+    if (!chargeId) {
+        return {
+            success: false,
+            message: 'no valid charge could be resolved — enrich the case and propose again with a real charge_id',
+        };
+    }
+    // Absolute amount guard: never refund more than the charge. amount_cents is
+    // explicit cents by contract (lint rejects the ambiguous `amount` field).
+    const amountCents = typeof proposal.amount_cents === 'number' ? Math.trunc(proposal.amount_cents) : undefined;
+    const charge = await deps.stripe.retrieveCharge(chargeId, ref);
+    if (charge.refunded) {
+        return {
+            success: true,
+            message: `charge ${chargeId} already fully refunded`,
+            details: { idempotent_noop: true, charge_id: chargeId },
+        };
+    }
+    if (amountCents !== undefined && amountCents > charge.amount) {
+        return {
+            success: false,
+            message: `amount_cents ${amountCents} exceeds charge amount ${charge.amount} — aborting to prevent overcharge`,
+        };
+    }
+    audit(db, 'system', 'action_execution', {
+        caseId: action.case_id, actionId: action.id, phase: 'api_call',
+        detail: { op: 'createRefund', charge_id: chargeId, amount_cents: amountCents ?? 'FULL' },
+    });
+    try {
+        // Single shot — money mutations never auto-retry (an ambiguous timeout
+        // must not double-charge; retry is a human decision made safe by CAS +
+        // the already-refunded mapping).
+        const refund = await deps.stripe.createRefund({ chargeId, ...(amountCents !== undefined ? { amountCents } : {}) }, ref);
+        audit(db, 'system', 'action_execution', {
+            caseId: action.case_id, actionId: action.id, phase: 'api_response',
+            detail: { refund_id: refund.id, status: refund.status, amount: refund.amount },
+        });
+        return {
+            success: true,
+            message: `refunded ${refund.amount} cents on ${chargeId} (refund ${refund.id}, status ${refund.status})`,
+            details: { refund_id: refund.id, amount_cents: refund.amount, charge_id: chargeId },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/charge_already_refunded|already been refunded/i.test(msg)) {
+            return {
+                success: true,
+                message: `charge ${chargeId} was already refunded`,
+                details: { idempotent_noop: true, charge_id: chargeId },
+            };
+        }
+        return { success: false, message: `refund failed: ${msg}` };
+    }
+}
+function resolveChargeFromContext(db, caseId, proposal) {
+    const row = db.prepare(`SELECT prepared_context_json FROM cases WHERE id = ?`).get(caseId);
+    if (!row?.prepared_context_json)
+        return null;
+    try {
+        const ctx = JSON.parse(row.prepared_context_json);
+        const charges = (ctx.stripe?.customers ?? []).flatMap((c) => c.recentCharges ?? []);
+        const succeeded = charges.filter((c) => c.status === 'succeeded' &&
+            typeof c.id === 'string' &&
+            (isValidStripeId(c.id, 'ch_') || isValidStripeId(c.id, 'py_')) &&
+            c.refunded !== true);
+        const wanted = typeof proposal.amount_cents === 'number' ? proposal.amount_cents : undefined;
+        if (wanted !== undefined) {
+            const byAmount = succeeded.find((c) => c.amountCents === wanted);
+            if (byAmount)
+                return byAmount.id;
+        }
+        return succeeded[0]?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------- cancel --
+async function runCancel(deps, action, proposal, ref) {
+    const { db } = deps;
+    const subId = typeof proposal.subscription_id === 'string' ? proposal.subscription_id : '';
+    if (!isValidStripeId(subId, 'sub_')) {
+        return {
+            success: false,
+            message: 'no valid subscription_id — enrich the case and propose again with a real sub_… id',
+        };
+    }
+    const mode = proposal.cancel_mode === 'end_of_period' || proposal.cancel_mode === 'scheduled'
+        ? proposal.cancel_mode
+        : 'immediate';
+    // Pre-flight retrieve.
+    let sub;
+    try {
+        sub = await deps.stripe.retrieveSubscription(subId, ref);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/resource_missing|No such subscription/i.test(msg)) {
+            return {
+                success: true,
+                message: `subscription ${subId} no longer exists — desired end-state already true`,
+                details: { idempotent_noop: true },
+            };
+        }
+        return { success: false, message: `pre-flight retrieve failed: ${msg}` };
+    }
+    if (sub.status === 'canceled') {
+        return {
+            success: true,
+            message: `subscription ${subId} already canceled`,
+            details: { idempotent_noop: true },
+        };
+    }
+    // PRORATION GUARD (Incident A): re-writing cancel state on an already-
+    // scheduled subscription churns the billing period and can generate a
+    // wrongful proration charge. Only an explicit `immediate` may act on an
+    // already-scheduled sub (operator forcing early termination).
+    const alreadyScheduled = sub.cancel_at_period_end === true || sub.cancel_at !== null;
+    if (alreadyScheduled && mode !== 'immediate') {
+        return {
+            success: true,
+            message: `subscription ${subId} already has a scheduled cancellation — not re-applied`,
+            details: { idempotent_noop: true, proration_guard: true },
+        };
+    }
+    audit(db, 'system', 'action_execution', {
+        caseId: action.case_id, actionId: action.id, phase: 'api_call',
+        detail: { op: `cancel:${mode}`, subscription_id: subId, cancel_date: proposal.cancel_date },
+    });
+    try {
+        // Confirm-before-success (Incident C): the API can return 200 with an
+        // unchanged object; verify the mutation actually took.
+        if (mode === 'immediate') {
+            const res = await deps.stripe.cancelNow(subId, ref);
+            if (res.status !== 'canceled') {
+                return {
+                    success: false,
+                    message: `cancellation of ${subId} did not confirm (status=${res.status}) — not marking as done; retry or check the Stripe dashboard`,
+                };
+            }
+            return { success: true, message: `subscription ${subId} canceled immediately`, details: { status: res.status } };
+        }
+        if (mode === 'end_of_period') {
+            const res = await deps.stripe.cancelAtPeriodEnd(subId, ref);
+            if (res.cancel_at_period_end !== true) {
+                return {
+                    success: false,
+                    message: `cancel_at_period_end did not confirm on ${subId} — not marking as done`,
+                };
+            }
+            return {
+                success: true,
+                message: `subscription ${subId} will cancel at period end`,
+                details: { cancel_at_period_end: true },
+            };
+        }
+        // scheduled
+        const date = typeof proposal.cancel_date === 'string' ? proposal.cancel_date : '';
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+            return { success: false, message: 'scheduled cancel requires cancel_date (YYYY-MM-DD)' };
+        }
+        const epoch = Math.floor(Date.parse(`${date}T00:00:00Z`) / 1000);
+        const res = await deps.stripe.cancelAt(subId, epoch, ref);
+        if (res.cancel_at === null) {
+            return { success: false, message: `scheduled cancel did not confirm on ${subId} — not marking as done` };
+        }
+        return {
+            success: true,
+            message: `subscription ${subId} scheduled to cancel on ${date}`,
+            details: { cancel_at: res.cancel_at },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/resource_missing|No such subscription/i.test(msg)) {
+            return {
+                success: true,
+                message: `subscription ${subId} no longer exists — desired end-state already true`,
+                details: { idempotent_noop: true },
+            };
+        }
+        return { success: false, message: `cancel failed: ${msg}` };
+    }
+}
+// ------------------------------------------------------------ send_reply --
+const RETRYABLE = /429|rate.?limit|fetch failed|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|^5\d\d|\b5\d\d\b/i;
+const MAX_SEND_RETRIES = 3;
+async function runSendReply(deps, action, proposal, sendMode, ref) {
+    const { db } = deps;
+    // Content resolution: the current draft row wins over the proposal snapshot
+    // (the operator may have edited after the proposal was created). Fallback
+    // to proposal bodies. NEVER proposal.message — that is the approval-card
+    // summary, not customer content.
+    const draft = db
+        .prepare(`SELECT body_english, body_translated FROM drafts
+        WHERE case_id = ? AND is_current = 1 ORDER BY version DESC LIMIT 1`)
+        .get(action.case_id);
+    let body = null;
+    if (draft) {
+        const english = draft.body_english;
+        const translated = draft.body_translated;
+        if (sendMode === 'both' && translated)
+            body = `${translated}\n\n---\n\n${english}`;
+        else if (sendMode === 'english')
+            body = english;
+        else
+            body = translated ?? english; // 'translated' falls back to english
+    }
+    if (!body) {
+        for (const field of ['body_translated', 'body_english', 'body_text', 'content', 'reply_text']) {
+            const v = proposal[field];
+            if (typeof v === 'string' && v.trim() !== '') {
+                body = v;
+                break;
+            }
+        }
+    }
+    if (!body)
+        return { success: false, message: 'no reply content: no current draft and no usable proposal body' };
+    const caseRow = db
+        .prepare(`SELECT c.id, cu.email AS customer_email FROM cases c
+        LEFT JOIN customers cu ON cu.id = c.customer_id WHERE c.id = ?`)
+        .get(action.case_id);
+    if (!caseRow?.customer_email) {
+        return { success: false, message: 'case has no customer email to reply to' };
+    }
+    // Retry wraps ONLY the customer-facing send; bookkeeping never re-runs.
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const baseDelay = deps.sendRetryBaseDelayMs ?? 30_000;
+    let lastErr = '';
+    for (let attempt = 0; attempt < MAX_SEND_RETRIES; attempt++) {
+        try {
+            audit(db, 'system', 'action_execution', {
+                caseId: action.case_id, actionId: action.id, phase: 'api_call',
+                detail: { op: 'sendReply', to: caseRow.customer_email, attempt },
+            });
+            const sent = await deps.mailer.sendReply({
+                caseId: action.case_id,
+                to: caseRow.customer_email,
+                body,
+                ref,
+            });
+            // Bookkeeping (outside the retry loop by construction — we return).
+            // The outbound row is the dedupe key preventing the next mailbox poll
+            // from re-ingesting our own reply.
+            db.prepare(`INSERT INTO emails (case_id, direction, to_addr, body_text, provider_message_id, received_at, created_at)
+         VALUES (?, 'outbound', ?, ?, ?, ?, ?)`).run(action.case_id, caseRow.customer_email, body, sent.providerMessageId, now(), now());
+            return {
+                success: true,
+                message: `reply sent to ${caseRow.customer_email}`,
+                details: { provider_message_id: sent.providerMessageId, send_mode: sendMode },
+            };
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err.message : String(err);
+            const retryable = RETRYABLE.test(lastErr) && attempt < MAX_SEND_RETRIES - 1;
+            audit(db, 'system', 'action_execution', {
+                caseId: action.case_id, actionId: action.id, phase: 'error',
+                detail: { op: 'sendReply', attempt, error: lastErr, willRetry: retryable },
+            });
+            if (!retryable)
+                break;
+            await sleep(baseDelay * 2 ** attempt);
+        }
+    }
+    return { success: false, message: `send failed after retries: ${lastErr}` };
+}
+// ---------------------------------------------------- create_github_issue --
+async function runGithubIssue(deps, action, proposal, ref) {
+    const title = typeof proposal.title === 'string' ? proposal.title.trim() : '';
+    const body = typeof proposal.body === 'string' ? proposal.body.trim() : '';
+    if (!title || !body) {
+        // Executor guard mirrors the lint rule (the forever rule: both land together).
+        return { success: false, message: 'create_github_issue requires non-empty title and body' };
+    }
+    audit(deps.db, 'system', 'action_execution', {
+        caseId: action.case_id, actionId: action.id, phase: 'api_call',
+        detail: { op: 'createIssue', title },
+    });
+    const issue = await deps.github.createIssue({ title, body, labels: Array.isArray(proposal.labels) ? proposal.labels : undefined }, ref);
+    if (!issue.number || issue.number <= 0) {
+        return { success: false, message: 'GitHub did not confirm issue creation — not marking as done' };
+    }
+    return {
+        success: true,
+        message: `created GitHub issue #${issue.number}`,
+        details: { issue_number: issue.number, url: issue.url },
+    };
+}

package/dist/server/services/lint.js

@@ -0,0 +1,129 @@
+import { PROPOSAL_SCHEMAS, ACTION_TYPES, } from '../../shared/actions.js';
+import { loadToneLintConfig } from './overlay.js';
+export function lintDraft(text, cfg = loadToneLintConfig()) {
+    const warnings = [];
+    for (const pattern of cfg.bannedGreetings) {
+        if (new RegExp(pattern, 'm').test(text)) {
+            warnings.push(`banned greeting form (/${pattern}/) — prefer "${cfg.suggestions.greeting}"`);
+        }
+    }
+    for (const phrase of cfg.bannedOpeners) {
+        if (text.toLowerCase().includes(phrase.toLowerCase())) {
+            warnings.push(`banned opener "${phrase}" — prefer "${cfg.suggestions.opener}"`);
+        }
+    }
+    for (const pattern of cfg.bannedSignoffs) {
+        if (new RegExp(pattern, 'im').test(text)) {
+            warnings.push(`banned sign-off form (/${pattern}/) — prefer "${cfg.suggestions.signoff}"`);
+        }
+    }
+    return warnings;
+}
+export function lintAndNormalizeAction(actionType, rawProposal, toneCfg) {
+    const errors = [];
+    const warnings = [];
+    const proposal = { ...rawProposal };
+    if (!ACTION_TYPES.includes(actionType)) {
+        return { proposal, errors: [`unknown action_type "${actionType}"`], warnings };
+    }
+    const type = actionType;
+    // Retired mode from a bundled-downgrade over-refund incident. Checked
+    // BEFORE schema validation so the brain gets the instructive replacement
+    // recipe instead of a generic enum error.
+    if (type === 'cancel_subscription' && proposal.cancel_mode === 'downgrade_to_monthly') {
+        errors.push('cancel_mode "downgrade_to_monthly" is retired: propose a `refund` (execution_order 0) ' +
+            'for total_paid minus the verified monthly price, plus a `cancel_subscription` with ' +
+            'cancel_mode "scheduled" (execution_order 5).');
+        return { proposal, errors, warnings };
+    }
+    const schema = PROPOSAL_SCHEMAS[type];
+    const parsed = schema.safeParse(proposal);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            errors.push(`${issue.path.join('.') || '(root)'}: ${issue.message}`);
+        }
+        return { proposal, errors, warnings };
+    }
+    switch (type) {
+        case 'cancel_subscription': {
+            // Operators stripped time components on every single proposal.
+            if (typeof proposal.cancel_date === 'string' && /T|\s\d{2}:/.test(proposal.cancel_date)) {
+                proposal.cancel_date = proposal.cancel_date.slice(0, 10);
+                warnings.push('cancel_date had a time component — truncated to YYYY-MM-DD (auto-fixed)');
+            }
+            if (typeof proposal.cancel_date === 'string' &&
+                proposal.cancel_date !== '' &&
+                !/^\d{4}-\d{2}-\d{2}$/.test(proposal.cancel_date)) {
+                errors.push(`cancel_date "${proposal.cancel_date}" is not YYYY-MM-DD`);
+            }
+            if (proposal.cancel_mode === 'scheduled' && !proposal.cancel_date) {
+                proposal.cancel_mode = 'end_of_period';
+                warnings.push('cancel_mode "scheduled" without cancel_date — downgraded to end_of_period (auto-fixed)');
+            }
+            // The brain must never control this flag; always derived from intent.
+            const derived = proposal.cancel_mode === 'end_of_period';
+            if (proposal.cancel_at_period_end !== undefined && proposal.cancel_at_period_end !== derived) {
+                warnings.push(`cancel_at_period_end coerced to ${derived} to match cancel_mode (never trusted from the brain)`);
+            }
+            proposal.cancel_at_period_end = derived;
+            if (!proposal.customer_id) {
+                warnings.push('customer_id missing — expected explicitly for duplicate-subscription disambiguation');
+            }
+            break;
+        }
+        case 'refund': {
+            // The ancestor system's ambiguous `amount` (dollars? cents?) carried a
+            // heuristic that could 100x a small partial refund. ClearHand accepts
+            // only an explicit amount_cents.
+            if (proposal.amount !== undefined) {
+                errors.push('`amount` is ambiguous (dollars vs cents) and not accepted: use `amount_cents` ' +
+                    '(integer cents), or omit it entirely for a full refund of the charge.');
+            }
+            if (proposal.refund_amount !== undefined) {
+                warnings.push('`refund_amount` is retired — use `amount_cents` (integer cents)');
+            }
+            if (!proposal.currency) {
+                proposal.currency = 'usd';
+                warnings.push('currency defaulted to "usd" (auto-fixed)');
+            }
+            break;
+        }
+        case 'send_reply': {
+            const body = typeof proposal.body_text === 'string' ? proposal.body_text.trim() : '';
+            const placeholder = /^see draft\.?$/i.test(body);
+            if (!body || placeholder) {
+                errors.push('send_reply.body_text must carry the real reply body at creation time ' +
+                    '(empty or "see draft" placeholders are rejected)');
+                break;
+            }
+            for (const w of lintDraft(body, toneCfg))
+                warnings.push(`send_reply body: ${w}`);
+            break;
+        }
+        case 'escalate': {
+            if (typeof proposal.reason !== 'string' || proposal.reason.trim() === '') {
+                errors.push('escalate.reason is required — the operator needs to know why');
+            }
+            break;
+        }
+        case 'set_case_status': {
+            // zod already restricts target_status to resolved|pending|ignored;
+            // 'processed' is the "AI finished a pass" marker, never a closing state.
+            break;
+        }
+        case 'create_github_issue': {
+            // New action type in ClearHand — lint rule + executor guard land in the
+            // same change (the forever rule).
+            const title = typeof proposal.title === 'string' ? proposal.title.trim() : '';
+            const body = typeof proposal.body === 'string' ? proposal.body.trim() : '';
+            if (!title)
+                errors.push('create_github_issue.title is required');
+            if (!body)
+                errors.push('create_github_issue.body is required (include repro + case link)');
+            if (title.length > 200)
+                warnings.push('title longer than 200 chars — consider shortening');
+            break;
+        }
+    }
+    return { proposal, errors, warnings };
+}