greprag 5.22.3 → 5.24.0

package/dist/email-send.d.ts

@@ -0,0 +1,64 @@
+/** Outbound email send — the SEND half of `greprag email`, mirror of the
+ *  `email-pull` drain. Thin HTTP client: reads the body (+ optional html),
+ *  base64s any `--attach` files LOCALLY, POSTs the payload to /v1/email/send
+ *  (authed by the API key — no wrangler/R2 creds), prints the result.
+ *
+ *  The CLI NEVER asserts a From identity: the server resolves + guards it from
+ *  the authenticated tenant (a caller can only send as its own @greprag.com
+ *  handle). `--from` is at most a preference among the caller's own handles,
+ *  validated server-side. The pure payload builder is unit-tested without
+ *  network. adr: docs/agent-email.md
+ */
+export interface SendAttachmentInput {
+    filename: string;
+    mime: string | null;
+    /** base64-encoded content (inline — the Worker has no disk to fetch from). */
+    base64: string;
+}
+/** Wire payload for POST /v1/email/send (snake_case mirrors the route). */
+export interface SendPayload {
+    to: string[];
+    subject: string;
+    body?: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string;
+    from?: string;
+    attachments?: SendAttachmentInput[];
+}
+export interface SendOptions {
+    to: string[];
+    subject: string;
+    bodyText?: string | null;
+    htmlText?: string | null;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string | null;
+    from?: string | null;
+    /** Local file paths to attach — read + base64'd by buildSendPayload. */
+    attachPaths?: string[];
+}
+/** Best-effort MIME from a filename extension; octet-stream when unknown. */
+export declare function guessMime(filename: string): string;
+/** Read a body source: a file path, or '-' for stdin. */
+export declare function readBodySource(src: string): string;
+/** base64-encode a local file into an attachment entry. */
+export declare function fileToAttachment(filePath: string): SendAttachmentInput;
+/** Build the wire payload from resolved options. Reads + base64s any
+ *  attachment files (the only I/O); everything else is a pure map. Keeping the
+ *  shape here (not in the arg parser) makes the payload unit-testable. */
+export declare function buildSendPayload(opts: SendOptions): SendPayload;
+export interface SendResult {
+    ok: boolean;
+    from?: string;
+    to?: string[];
+    cc?: string[];
+    subject?: string;
+    message_id?: string | null;
+    attachments?: number;
+    egress_key?: string | null;
+    error?: string;
+}
+/** POST the payload to /v1/email/send. Throws on a non-ok response. */
+export declare function postSend(apiUrl: string, apiKey: string, payload: SendPayload): Promise<SendResult>;

package/dist/email-send.js

@@ -0,0 +1,124 @@
+"use strict";
+/** Outbound email send — the SEND half of `greprag email`, mirror of the
+ *  `email-pull` drain. Thin HTTP client: reads the body (+ optional html),
+ *  base64s any `--attach` files LOCALLY, POSTs the payload to /v1/email/send
+ *  (authed by the API key — no wrangler/R2 creds), prints the result.
+ *
+ *  The CLI NEVER asserts a From identity: the server resolves + guards it from
+ *  the authenticated tenant (a caller can only send as its own @greprag.com
+ *  handle). `--from` is at most a preference among the caller's own handles,
+ *  validated server-side. The pure payload builder is unit-tested without
+ *  network. adr: docs/agent-email.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guessMime = guessMime;
+exports.readBodySource = readBodySource;
+exports.fileToAttachment = fileToAttachment;
+exports.buildSendPayload = buildSendPayload;
+exports.postSend = postSend;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const MIME_BY_EXT = {
+    pdf: 'application/pdf', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+    gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+    txt: 'text/plain', md: 'text/markdown', csv: 'text/csv', html: 'text/html',
+    json: 'application/json', xml: 'application/xml',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    zip: 'application/zip',
+};
+/** Best-effort MIME from a filename extension; octet-stream when unknown. */
+function guessMime(filename) {
+    const m = (filename || '').toLowerCase().match(/\.([a-z0-9]+)$/);
+    return (m && MIME_BY_EXT[m[1]]) || 'application/octet-stream';
+}
+/** Read a body source: a file path, or '-' for stdin. */
+function readBodySource(src) {
+    if (src === '-')
+        return fs.readFileSync(0, 'utf-8');
+    return fs.readFileSync(src, 'utf-8');
+}
+/** base64-encode a local file into an attachment entry. */
+function fileToAttachment(filePath) {
+    const buf = fs.readFileSync(filePath);
+    return {
+        filename: path.basename(filePath),
+        mime: guessMime(filePath),
+        base64: buf.toString('base64'),
+    };
+}
+/** Build the wire payload from resolved options. Reads + base64s any
+ *  attachment files (the only I/O); everything else is a pure map. Keeping the
+ *  shape here (not in the arg parser) makes the payload unit-testable. */
+function buildSendPayload(opts) {
+    const payload = { to: opts.to, subject: opts.subject };
+    if (opts.bodyText)
+        payload.body = opts.bodyText;
+    if (opts.htmlText)
+        payload.html = opts.htmlText;
+    if (opts.cc && opts.cc.length)
+        payload.cc = opts.cc;
+    if (opts.bcc && opts.bcc.length)
+        payload.bcc = opts.bcc;
+    if (opts.replyTo)
+        payload.reply_to = opts.replyTo;
+    if (opts.from)
+        payload.from = opts.from;
+    const atts = (opts.attachPaths || []).map(fileToAttachment);
+    if (atts.length)
+        payload.attachments = atts;
+    return payload;
+}
+/** POST the payload to /v1/email/send. Throws on a non-ok response. */
+async function postSend(apiUrl, apiKey, payload) {
+    const url = `${apiUrl.replace(/\/+$/, '')}/v1/email/send`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+    let data = { ok: false };
+    try {
+        data = await res.json();
+    }
+    catch { /* non-JSON error body */ }
+    if (!res.ok || !data.ok) {
+        throw new Error(data.error || `API ${res.status}`);
+    }
+    return data;
+}
+//# sourceMappingURL=email-send.js.map

package/dist/email-send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-send.js","sourceRoot":"","sources":["../src/email-send.ts"],"names":[],"mappings":"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"}

package/dist/front-desk-mail.d.ts

@@ -0,0 +1,50 @@
+/** "You've got mail" — the front-desk turn notification (Chip B).
+ *
+ *  A turn-based announcement, NOT a live watcher interrupt: each turn the hook
+ *  asks the server for ENVELOPE-ONLY pending front-desk mail and, for any
+ *  arrival it hasn't announced yet this machine, injects a one-line "you've got
+ *  mail from X" notice. It feeds the human sign-off gate — it announces that a
+ *  record arrived; it NEVER ingests body content (front-desk store contract
+ *  invariant 2/3). The envelope type carries no `body` field, so body-leakage is
+ *  impossible by construction here, and the server's `/v1/email/pending`
+ *  projection withholds body too — defense at both ends.
+ *
+ *  De-dupe: each record id is announced once (stamped in ~/.greprag/state.json),
+ *  so a still-unread message doesn't re-nag every single turn — only genuinely
+ *  new arrivals fire. The agent makes it stop by acting on the mail
+ *  (`greprag email`), which marks it read and drops it from `pending`.
+ */
+/** Envelope of a pending front-desk record. NO `body` — by design. */
+export interface FrontDeskEnvelope {
+    id: string;
+    nodeId: string;
+    from: string | null;
+    subject: string | null;
+    trustVerdict: 'verified' | 'unverified' | 'failed' | null;
+    attachmentCount: number;
+    createdAt: string;
+}
+/** Strip control chars / newlines and truncate untrusted envelope text before
+ *  it enters the agent's context. The subject + from are attacker-controllable;
+ *  rendering them on one clean line (no embedded newlines / escape sequences)
+ *  blunts the obvious injection shapes without pretending the text is trusted.
+ *
+ *  Done as a codepoint scan rather than a control-char regex on purpose — it is
+ *  unambiguous in source (no literal control bytes in the file) and replaces
+ *  every C0 control char + DEL with a space. */
+export declare function sanitizeEnvelopeText(text: string | null, max: number): string;
+/** Render the envelope-only notice. Pure: takes envelopes, returns a string (or
+ *  null when there's nothing to announce). Provably body-free — `FrontDeskEnvelope`
+ *  has no body field to render. */
+export declare function renderFrontDeskNotice(envelopes: FrontDeskEnvelope[]): string | null;
+/** Fetch envelope-only pending front-desk mail. Returns [] on any error so the
+ *  hook never blocks a turn. */
+export declare function fetchPendingMail(apiUrl: string, apiKey: string): Promise<FrontDeskEnvelope[]>;
+/** Filter envelopes to those NOT yet announced. Pure given `stamps`. */
+export declare function filterUnannounced(envelopes: FrontDeskEnvelope[], stamps: Record<string, string>): FrontDeskEnvelope[];
+/** Mark a batch of ids announced and persist (pruning stale stamps). Best-effort. */
+export declare function stampAnnounced(ids: string[]): void;
+/** End-to-end: fetch pending mail, drop already-announced ids, render the
+ *  envelope-only notice, stamp the freshly-announced ids. Returns null when
+ *  there's nothing new. The data path is body-free throughout. */
+export declare function buildFrontDeskNotice(apiUrl: string, apiKey: string): Promise<string | null>;

package/dist/front-desk-mail.js

@@ -0,0 +1,206 @@
+"use strict";
+/** "You've got mail" — the front-desk turn notification (Chip B).
+ *
+ *  A turn-based announcement, NOT a live watcher interrupt: each turn the hook
+ *  asks the server for ENVELOPE-ONLY pending front-desk mail and, for any
+ *  arrival it hasn't announced yet this machine, injects a one-line "you've got
+ *  mail from X" notice. It feeds the human sign-off gate — it announces that a
+ *  record arrived; it NEVER ingests body content (front-desk store contract
+ *  invariant 2/3). The envelope type carries no `body` field, so body-leakage is
+ *  impossible by construction here, and the server's `/v1/email/pending`
+ *  projection withholds body too — defense at both ends.
+ *
+ *  De-dupe: each record id is announced once (stamped in ~/.greprag/state.json),
+ *  so a still-unread message doesn't re-nag every single turn — only genuinely
+ *  new arrivals fire. The agent makes it stop by acting on the mail
+ *  (`greprag email`), which marks it read and drops it from `pending`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeEnvelopeText = sanitizeEnvelopeText;
+exports.renderFrontDeskNotice = renderFrontDeskNotice;
+exports.fetchPendingMail = fetchPendingMail;
+exports.filterUnannounced = filterUnannounced;
+exports.stampAnnounced = stampAnnounced;
+exports.buildFrontDeskNotice = buildFrontDeskNotice;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const SUBJECT_MAX = 80;
+const FROM_MAX = 60;
+/** Strip control chars / newlines and truncate untrusted envelope text before
+ *  it enters the agent's context. The subject + from are attacker-controllable;
+ *  rendering them on one clean line (no embedded newlines / escape sequences)
+ *  blunts the obvious injection shapes without pretending the text is trusted.
+ *
+ *  Done as a codepoint scan rather than a control-char regex on purpose — it is
+ *  unambiguous in source (no literal control bytes in the file) and replaces
+ *  every C0 control char + DEL with a space. */
+function sanitizeEnvelopeText(text, max) {
+    if (!text)
+        return '';
+    let out = '';
+    for (const ch of text) {
+        const code = ch.codePointAt(0) ?? 0;
+        out += (code < 0x20 || code === 0x7f) ? ' ' : ch;
+    }
+    const oneLine = out.replace(/\s+/g, ' ').trim();
+    return oneLine.length > max ? oneLine.slice(0, max - 1) + '…' : oneLine;
+}
+function verdictTag(v) {
+    switch (v) {
+        case 'verified': return 'verified';
+        case 'failed': return '⚠ FAILED-AUTH';
+        case 'unverified': return 'unverified';
+        default: return 'unverified';
+    }
+}
+/** Render the envelope-only notice. Pure: takes envelopes, returns a string (or
+ *  null when there's nothing to announce). Provably body-free — `FrontDeskEnvelope`
+ *  has no body field to render. */
+function renderFrontDeskNotice(envelopes) {
+    if (!envelopes || envelopes.length === 0)
+        return null;
+    const n = envelopes.length;
+    const lines = [];
+    lines.push(`📬 You've got mail — ${n} new front-desk message${n === 1 ? '' : 's'} (envelope only; body stays sealed until you sign off):`);
+    for (const e of envelopes) {
+        const from = sanitizeEnvelopeText(e.from, FROM_MAX) || '(unknown sender)';
+        const subject = sanitizeEnvelopeText(e.subject, SUBJECT_MAX) || '(no subject)';
+        const att = e.attachmentCount > 0
+            ? ` (${e.attachmentCount} attachment${e.attachmentCount === 1 ? '' : 's'})`
+            : '';
+        lines.push(`  · [${verdictTag(e.trustVerdict)}] from ${from} — "${subject}"${att}`);
+    }
+    lines.push(`Act on it: \`greprag email\` reads the body deliberately. unverified/failed mail never auto-acts — you sign off first.`);
+    return lines.join('\n');
+}
+/** Fetch envelope-only pending front-desk mail. Returns [] on any error so the
+ *  hook never blocks a turn. */
+async function fetchPendingMail(apiUrl, apiKey) {
+    try {
+        const url = `${apiUrl.replace(/\/+$/, '')}/v1/email/pending`;
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+        if (!res.ok)
+            return [];
+        const data = await res.json();
+        return (data.pending || []).map(r => ({
+            id: r.id,
+            nodeId: r.node_id,
+            from: r.from,
+            subject: r.subject,
+            trustVerdict: r.trust_verdict,
+            attachmentCount: r.attachment_count ?? 0,
+            createdAt: r.created_at,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ---- Once-per-arrival de-dupe (state.json) ---------------------------------
+const ANNOUNCE_TTL_MS = 30 * 86_400_000; // prune stamps older than 30 days
+function statePath() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    if (!home)
+        return null;
+    return path.join(home, '.greprag', 'state.json');
+}
+function readState() {
+    const file = statePath();
+    if (!file)
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readAnnouncedStamps(state) {
+    const stamps = state.frontDeskAnnounced;
+    return stamps && typeof stamps === 'object' && !Array.isArray(stamps)
+        ? stamps
+        : {};
+}
+/** Filter envelopes to those NOT yet announced. Pure given `stamps`. */
+function filterUnannounced(envelopes, stamps) {
+    return envelopes.filter(e => !stamps[e.id]);
+}
+/** Mark a batch of ids announced and persist (pruning stale stamps). Best-effort. */
+function stampAnnounced(ids) {
+    const file = statePath();
+    if (!file || ids.length === 0)
+        return;
+    try {
+        const state = readState();
+        const stamps = readAnnouncedStamps(state);
+        const nowIso = new Date().toISOString();
+        const nowMs = Date.now();
+        for (const id of ids)
+            stamps[id] = nowIso;
+        // Prune stale stamps so the map can't grow without bound.
+        for (const [id, iso] of Object.entries(stamps)) {
+            const ms = Date.parse(iso);
+            if (Number.isFinite(ms) && nowMs - ms > ANNOUNCE_TTL_MS)
+                delete stamps[id];
+        }
+        state.frontDeskAnnounced = stamps;
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+    }
+    catch {
+        /* best-effort — a missed stamp just means a possible re-announce */
+    }
+}
+/** End-to-end: fetch pending mail, drop already-announced ids, render the
+ *  envelope-only notice, stamp the freshly-announced ids. Returns null when
+ *  there's nothing new. The data path is body-free throughout. */
+async function buildFrontDeskNotice(apiUrl, apiKey) {
+    const envelopes = await fetchPendingMail(apiUrl, apiKey);
+    if (envelopes.length === 0)
+        return null;
+    const stamps = readAnnouncedStamps(readState());
+    const fresh = filterUnannounced(envelopes, stamps);
+    if (fresh.length === 0)
+        return null;
+    const notice = renderFrontDeskNotice(fresh);
+    if (notice)
+        stampAnnounced(fresh.map(e => e.id));
+    return notice;
+}
+//# sourceMappingURL=front-desk-mail.js.map

package/dist/front-desk-mail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"front-desk-mail.js","sourceRoot":"","sources":["../src/front-desk-mail.ts"],"names":[],"mappings":"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"}

package/dist/hook.js

@@ -51,6 +51,8 @@ const session_id_1 = require("./session-id");
 // elide it so it never lands as a searchable turn node.
 const turn_provenance_1 = require("./turn-provenance");
 const codex_steering_1 = require("./codex-steering");
+const front_desk_mail_1 = require("./front-desk-mail");
+const email_pull_1 = require("./email-pull");
 const API_URL_DEFAULT = 'https://api.greprag.com';
 const MAX_FIELD_CHARS = 500_000; // safety cap per text field
 // ---------- Env + config ---------------------------------------------------
@@ -977,13 +979,23 @@ function shouldEmitDriftWarning(storedId, derivedId) {
         return true;
     return (Date.now() - lastMs) >= DRIFT_WARNING_TTL_MS;
 }
+function writeRecapOutput(text, mode) {
+    if (!text)
+        return;
+    if (mode === 'additionalContext') {
+        writeAdditionalContext('SessionStart', text);
+        return;
+    }
+    process.stdout.write(text);
+}
 /** SessionStart — fetch recent episodic activity for this project and print
- *  to stdout. Claude Code injects the printed text as session context. Fires
+ *  to stdout. Claude Code injects the printed text as session context. Codex
+ *  uses the same content via `hookSpecificOutput.additionalContext`. Fires
  *  once per session. No LLM call.
  *
  *  Storage and display are both UTC. The agent can compute local time itself
  *  if needed — a server-side UTC display avoids straddle-day confusion. */
-async function recap(input) {
+async function recap(input, mode = 'plain') {
     const cwd = input.cwd || process.cwd();
     const cfg = getConfig(cwd);
     if (!cfg.enabled || !cfg.apiKey)
@@ -1044,8 +1056,7 @@ async function recap(input) {
     // hook globally. Setup warning + inbox header still fire above.
     if (!anchor.sessionStartRecap) {
         const out = preamble();
-        if (out)
-            process.stdout.write(out);
+        writeRecapOutput(out, mode);
         return;
     }
     const now = new Date();
@@ -1088,8 +1099,7 @@ async function recap(input) {
     // surface via preamble if they're pending.
     if (recentHourlies.length === 0) {
         const out = preamble();
-        if (out)
-            process.stdout.write(out);
+        writeRecapOutput(out, mode);
         return;
     }
     const parts = [];
@@ -1112,7 +1122,7 @@ async function recap(input) {
         parts.push(`${recency}:`);
         parts.push(stripRecapNoise(h.content.trim(), 'hourly'));
     }
-    process.stdout.write(parts.join('\n') + '\n');
+    writeRecapOutput(parts.join('\n') + '\n', mode);
 }
 /** Self-scoped arm-state check: does THIS session have a live inbox watcher?
  *  Asks the server's watcher registry (GET /v1/inbox/watchers — the same live-
@@ -1194,6 +1204,60 @@ async function notify(input, source = 'claude-code') {
         return; // armed OR couldn't tell → silent
     writeAdditionalContext('UserPromptSubmit', (0, session_id_1.buildArmDirective)(short, (0, session_id_1.readIdentityAlias)()));
 }
+/** "You've got mail" turn hook (Chip B) — wire as a UserPromptSubmit hook.
+ *  Each turn, ask the server for ENVELOPE-ONLY pending front-desk mail and
+ *  inject a one-line "you've got mail from X" notice for any arrival not yet
+ *  announced on this machine. It feeds the human sign-off gate — it NEVER
+ *  ingests body (front-desk store contract invariant 2/3); the data path is
+ *  body-free end to end (envelope type has no body field, server projection
+ *  withholds it). Self-silences once each record is announced; the agent stops
+ *  the loop by acting on the mail (`greprag email` marks it read).
+ *
+ *  Unconfigured / no API key → silent. Tenant-scoped by the API key, so a
+ *  session only ever sees its own tenant's front desk.
+ *
+ *  Auto-save (Chip E): when a project opts in (`email_autosave=true` in
+ *  .greprag/project.json, or env GREPRAG_EMAIL_AUTOSAVE), the hook also drains
+ *  new attachments to the configured dir each turn and appends a one-line saved
+ *  summary. Default OFF — no opt-in, no pull. Best-effort: a drain failure never
+ *  blocks the turn or suppresses the envelope notice. */
+async function mail(input) {
+    const cwd = input.cwd || process.cwd();
+    const cfg = getConfig(cwd);
+    if (!cfg.enabled || !cfg.apiKey)
+        return; // unconfigured → silent
+    const parts = [];
+    const notice = await (0, front_desk_mail_1.buildFrontDeskNotice)(cfg.apiUrl, cfg.apiKey);
+    if (notice)
+        parts.push(notice);
+    try {
+        const auto = await maybeAutoSaveAttachments(cwd, cfg.apiUrl, cfg.apiKey);
+        if (auto)
+            parts.push(auto);
+    }
+    catch { /* drain is best-effort — never block a turn */ }
+    if (parts.length) {
+        writeAdditionalContext(input.hook_event_name || 'UserPromptSubmit', parts.join('\n\n'));
+    }
+}
+/** Per-turn attachment auto-save. Returns a one-line summary of freshly-saved
+ *  files, or null when auto-save is off or nothing new landed. Gated on an
+ *  explicit per-project opt-in so it never surprises a project that didn't
+ *  ask for local writes. */
+async function maybeAutoSaveAttachments(cwd, apiUrl, apiKey) {
+    const anchor = (0, project_anchor_1.readAnchor)(cwd);
+    const envOptIn = /^(1|true|yes|on)$/i.test(process.env.GREPRAG_EMAIL_AUTOSAVE || '');
+    if (anchor.emailAutosave !== true && !envOptIn)
+        return null;
+    const dir = (0, email_pull_1.resolveEmailDir)({
+        explicit: null,
+        env: process.env.GREPRAG_EMAIL_DIR,
+        anchorDir: anchor.emailDir,
+        projectName: anchor.projectName,
+    });
+    const { saved } = await (0, email_pull_1.pullAllPending)(apiUrl, apiKey, dir);
+    return (0, email_pull_1.buildAutoSaveSummary)(saved, dir);
+}
 /** UserPromptSubmit PROBE / manual diagnostic — prints a per-turn readout of
  *  whether THIS session has a live watcher (the same isSessionArmed signal
  *  `notify` gates on). Kept as a separate subcommand for visibility/debugging:
@@ -1270,11 +1334,11 @@ function handlePreSpawnCheck(input) {
 async function main() {
     const subcommand = process.argv[2];
     const validSubs = new Set([
-        'store', 'recap', 'notify', 'session-id', 'pre-spawn-check', 'armcheck',
-        'codex-store', 'codex-notify', 'codex-inbox',
+        'store', 'recap', 'notify', 'mail', 'session-id', 'pre-spawn-check', 'armcheck',
+        'codex-store', 'codex-notify', 'codex-inbox', 'codex-recap',
     ]);
     if (!validSubs.has(subcommand)) {
-        process.stderr.write(`Usage: greprag-hook <store|recap|notify|session-id|pre-spawn-check|armcheck|codex-store|codex-notify|codex-inbox>\n`);
+        process.stderr.write(`Usage: greprag-hook <store|recap|notify|mail|session-id|pre-spawn-check|armcheck|codex-store|codex-notify|codex-inbox|codex-recap>\n`);
         process.exit(1);
     }
     let input = {};
@@ -1293,9 +1357,15 @@ async function main() {
     if (subcommand === 'recap') {
         await recap(input);
     }
+    else if (subcommand === 'codex-recap') {
+        await recap(input, 'additionalContext');
+    }
     else if (subcommand === 'notify') {
         await notify(input);
     }
+    else if (subcommand === 'mail') {
+        await mail(input);
+    }
     else if (subcommand === 'codex-notify') {
         await notify(input, 'codex');
     }