@toddzheng024/dscode-bundle 0.2.0 → 0.4.0

package/bin/apply_patch

@@ -1,4 +1,9 @@
 #!/bin/sh
 # Accept a standard unified diff on stdin. Works without a Git repository.
 # git apply checks all hunks before writing; --check performs a dry run.
+prefix=$(git rev-parse --show-prefix 2>/dev/null) || prefix=
+if [ -n "$prefix" ]; then
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 1
+  exec git -C "$root" apply --directory="$prefix" --whitespace=nowarn "$@"
+fi
 exec git apply --whitespace=nowarn "$@"

package/cordis.patch.yml

@@ -95,7 +95,7 @@
     # Adapters resolve references per request; the Models page writes only the
     # managed document, which is never materialized into the process environment.
     - id: credentials
-      name: '@deepseek-ai/dsh-credentials-local'
+      name: '@toddzheng024/dscode-bundle/credentials'
 
     # The pi-ai multi-provider twin, mounted dormant: zero routes (and no extra
     # models in the picker) until a `llm-pi-ai:` settings section supplies provider
@@ -672,21 +672,8 @@
       pointerInputPolicy: targeted
       cursorVisualization: visible
 
-# Official stdio MCP bridge; Chrome starts lazily at the first browser call.
-# Local launcher resolves the pinned, preinstalled entrypoint. A Hub import
-# uses the equally pinned npx fallback and needs npm access on first launch.
-- insert:
-    - id: mcp-chrome
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: chrome
-        transport: stdio
-        command: !!js "process.env.DSH_TUI_CHROME_ENTRY ? process.execPath : 'npx'"
-        args: !!js "[...(process.env.DSH_TUI_CHROME_ENTRY ? [process.env.DSH_TUI_CHROME_ENTRY] : ['--yes', 'chrome-devtools-mcp@1.9.0']), '--isolated', '--no-usage-statistics', '--no-performance-crux']"
-        env:
-          CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: '1'
-        failOnStartupError: true
-        toolCallTimeoutMs: 60000
+# Chrome MCP belongs to the DSCODE agent preset. A fresh, prompt-free TUI
+# launch can render before composing an agent or connecting the browser server.
 
 - id: permission
   config:
@@ -712,51 +699,47 @@
         approval: never
 
 
-- id: llm-deepseek
-  disabled: true
+- id: credentials
+  name: "@toddzheng024/dscode-bundle/credentials"
 - insert:
-    - id: dscode-deepseek
-      name: '@toddzheng024/dscode-bundle/deepseek'
-    - id: dscode-bootstrap
-      name: '@toddzheng024/dscode-bundle/bootstrap'
     - id: dscode-auto-review
-      name: '@toddzheng024/dscode-bundle/auto-review'
+      name: "@toddzheng024/dscode-bundle/auto-review"
       config:
         timeoutMs: 30000
         maxOutputTokens: 768
         maxReviewsPerTurn: 20
     - id: dscode-session-metrics
-      name: '@toddzheng024/dscode-bundle/session-metrics'
-    - id: dscode-memory
-      name: '@toddzheng024/dscode-bundle/memory'
-    - id: dscode-session-bridge
-      name: '@toddzheng024/dscode-bundle/session-bridge'
+      name: "@toddzheng024/dscode-bundle/session-metrics"
     - id: dscode-session-cards
-      name: '@toddzheng024/dscode-bundle/session-cards'
+      name: "@toddzheng024/dscode-bundle/session-cards"
+    - id: dscode-session-bridge
+      name: "@toddzheng024/dscode-bundle/session-bridge"
+    - id: dscode-memory
+      name: "@toddzheng024/dscode-bundle/memory"
     - id: dscode-tui-tools
-      name: '@toddzheng024/dscode-bundle/tui-tools'
+      name: "@toddzheng024/dscode-bundle/tui-tools"
+    - id: dscode-email-tools
+      name: "@toddzheng024/dscode-bundle/email-tools"
     - id: dscode-hooks
-      name: '@deepseek-ai/dsh-hooks-codex'
-      inject: [dscodePaths]
+      name: "@deepseek-ai/dsh-hooks-codex"
+      inject: &a1
+        - dscodePaths
       config:
         configPath: !!js ctx.dscodePaths.hooks
         defaultTimeoutMs: 10000
         stderrSummaryMaxChars: 500
 - id: agent-presets
-  inject: [dscodePaths]
+  inject: *a1
   config:
     default: dscode
     roots:
       - path: !!js ctx.dscodePaths.presets
         trust: system
-- id: mcp-chrome
-  inject: [dscodePaths]
-  config:
-    serverName: chrome
-    transport: stdio
-    command: !!js process.execPath
-    args: !!js "[ctx.dscodePaths.chrome, '--isolated', '--no-usage-statistics', '--no-performance-crux']"
-    env:
-      CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: '1'
-    failOnStartupError: true
-    toolCallTimeoutMs: 60000
+
+- id: llm-deepseek
+  disabled: true
+- insert:
+    - id: dscode-deepseek
+      name: '@toddzheng024/dscode-bundle/deepseek'
+    - id: dscode-bootstrap
+      name: '@toddzheng024/dscode-bundle/bootstrap'

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "author": "Todd Zheng",
@@ -25,8 +25,13 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "exports": {
+    "./email-tools": "./plugins/email-tools/index.mjs",
+    "./imap": "./plugins/email/imap.mjs",
+    "./gmail": "./plugins/email/gmail.mjs",
+    "./email": "./plugins/email/inbox.mjs",
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml",
+    "./credentials": "./plugins/credentials/index.mjs",
     "./memory": "./plugins/memory/index.mjs",
     "./session-bridge": "./plugins/session-bridge/index.mjs",
     "./session-cards": "./plugins/session-cards/index.mjs",
@@ -289,6 +294,9 @@
     "dsh-code": "1.0.6",
     "chrome-devtools-mcp": "1.9.0",
     "react": "18.3.1",
+    "imapflow": "2.0.2",
+    "mailparser": "3.9.26",
+    "nodemailer": "10.0.9",
     "commander": "15.0.0",
     "eventsource-parser": "3.1.1"
   },

package/plugins/credentials/index.mjs

@@ -0,0 +1,50 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local';
+import { Context, Service } from '@deepseek-ai/cordis';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+
+const DEEPSEEK = 'DEEPSEEK_API_KEY';
+
+// Use the native locked, watched, owner-only store. Keep this independent of
+// the installed profile so upgrades and different projects share credentials.
+export default class DscodeCredentials extends LocalCredentialProvider {
+  shared;
+  sharedConfig;
+  constructor(ctx, config = {}) {
+    // Retain the old profile store, including other providers and OAuth records.
+    super(ctx, { ...config, path: undefined });
+    this.sharedConfig = { ...config, path: config.path ?? join(homedir(), '.dscode', 'credentials.yaml') };
+  }
+  async *[Service.init]() {
+    const sharedContext = new Context();
+    yield () => sharedContext.fiber.dispose();
+    sharedContext.provide('launchEnvironment', launchEnvironmentOf(this.ctx));
+    sharedContext.on('credentials/reference-updated', ref => this.notifyUpdated(ref));
+    await sharedContext.plugin(LocalCredentialProvider, this.sharedConfig);
+    this.shared = sharedContext.credentials;
+    yield* super[Service.init]();
+  }
+  async resolve(ref) {
+    if (ref === DEEPSEEK) {
+      const stored = await this.shared.resolve(ref);
+      if (stored?.source === 'env' || stored?.source === 'file') return stored;
+    }
+    return super.resolve(ref);
+  }
+  async describe(ref) {
+    if (ref === DEEPSEEK) {
+      const facts = await this.shared.describe(ref);
+      if (facts.source === 'env' || facts.source === 'file') return facts;
+    }
+    return super.describe(ref);
+  }
+  set(ref, value) {
+    return ref === DEEPSEEK ? this.shared.set(ref, value) : super.set(ref, value);
+  }
+  async unset(ref) {
+    // Explicit removal must not uncover a previously configured legacy key.
+    if (ref === DEEPSEEK) await this.shared.unset(ref);
+    await super.unset(ref);
+  }
+}

package/plugins/email/cli.mjs

@@ -0,0 +1,32 @@
+import { createEmailContacts } from './contacts.mjs';
+import { createGmailConnector } from './gmail.mjs';
+import { createImapConnector } from './imap.mjs';
+
+export async function runEmailClient(args, { connector = createGmailConnector(), imap = createImapConnector(), contacts = createEmailContacts(), output = console.log } = {}) {
+  const [command = 'status', ...rest] = args;
+  if (command === 'alias') {
+    const [action = 'list', name, address] = rest;
+    let result;
+    if (action === 'list' && rest.length <= 1) result = contacts.list();
+    else if (action === 'set' && rest.length === 3) result = await contacts.set(name, address);
+    else if (action === 'remove' && rest.length === 2) result = await contacts.remove(name);
+    else throw Error('Usage: dscode email alias list | set NAME ADDRESS | remove NAME');
+    if (result.busy === true) throw Error('Contacts are busy in another session. Retry shortly.');
+    output(JSON.stringify(result, null, 2)); return;
+  }
+  if (!['configure', 'connect', 'sync', 'status', 'imap-status', 'imap-sync'].includes(command) || (command === 'configure' ? rest.length !== 1 : rest.length !== 0)) throw Error('Usage: dscode email configure CLIENT_JSON | connect | sync | status | imap-status | imap-sync (IMAP setup: /email then i)');
+  if (command.startsWith('imap-')) connector = imap;
+  if (command === 'imap-status') { output(JSON.stringify(connector.status(), null, 2)); return; }
+  if (command === 'status') { output(JSON.stringify(connector.status(), null, 2)); return; }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once('SIGINT', abort); process.once('SIGTERM', abort);
+  try {
+    if (command === 'connect') output('Complete Gmail authorization in your browser. Ctrl+C cancels.');
+    const result = command === 'configure' ? await connector.configure(rest[0])
+      : command === 'connect' ? await connector.connect({ signal: controller.signal })
+      : await connector.sync({ signal: controller.signal, force: true });
+    if (result.busy) throw Error('Gmail is busy in another session. Retry shortly.');
+    output(command === 'configure' ? 'Google Desktop OAuth client saved privately. Open /email and press g to connect.' : JSON.stringify(result, null, 2));
+  } finally { process.off('SIGINT', abort); process.off('SIGTERM', abort); }
+}

package/plugins/email/contacts.mjs

@@ -0,0 +1,36 @@
+import { join } from 'node:path';
+import { createEmailInbox } from './inbox.mjs';
+import { emailStore } from './store.mjs';
+
+export const emailAddress = value => typeof value === 'string' && value.length <= 254 && /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\.[A-Za-z]{2,}$/.test(value);
+const aliasKey = value => {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value)) throw Error('Alias must be 1..64 letters, digits, underscores or hyphens.');
+  return value.toLowerCase();
+};
+export function createEmailContacts({ directory = createEmailInbox().directory } = {}) {
+  const store = emailStore(join(directory, 'contacts'));
+  const list = () => store.read('aliases.json') ?? {};
+  return {
+    list,
+    resolve(value) {
+      if (emailAddress(value)) return { to: value };
+      const alias = aliasKey(value), entries = list();
+      const to = Object.hasOwn(entries, alias) ? entries[alias] : null;
+      if (!emailAddress(to)) throw Error('Unknown email alias: ' + alias + '. Add it with dscode email alias set NAME ADDRESS.');
+      return { alias, to };
+    },
+    async set(name, address) {
+      const alias = aliasKey(name);
+      if (!emailAddress(address)) throw Error('Specify one plain email address.');
+      return store.locked(async () => {
+        const entries = list();
+        Object.defineProperty(entries, alias, { value: address, enumerable: true, configurable: true, writable: true });
+        store.write('aliases.json', entries); return { alias, to: address };
+      });
+    },
+    async remove(name) {
+      const alias = aliasKey(name);
+      return store.locked(async () => { const entries = list(); delete entries[alias]; store.write('aliases.json', entries); return { removed: alias }; });
+    },
+  };
+}

package/plugins/email/gmail-oauth.mjs

@@ -0,0 +1,69 @@
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+export const GMAIL_SCOPES = ['gmail.readonly', 'gmail.labels', 'gmail.settings.basic'].map(scope => 'https://www.googleapis.com/auth/' + scope);
+export function readGoogleClient(path) {
+  let value;
+  try { value = JSON.parse(readFileSync(path, 'utf8')).installed; } catch { /* Report no content or secrets. */ }
+  if (!value || typeof value.client_id !== 'string' || !value.client_id.endsWith('.apps.googleusercontent.com')) throw Error('Set DSCODE_GMAIL_CLIENT_FILE to a Google Desktop OAuth client JSON file.');
+  return { client_id: value.client_id, ...(typeof value.client_secret === 'string' ? { client_secret: value.client_secret } : {}) };
+}
+
+export async function tokenRequest(params, { fetchImpl = fetch, signal } = {}) {
+  const response = await fetchImpl('https://oauth2.googleapis.com/token', {
+    method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(params).toString(), redirect: 'error',
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(20000)]) : AbortSignal.timeout(20000),
+  });
+  if (!response.ok) throw Error(response.status === 400 ? 'Google authorization expired or was rejected. Reconnect Gmail.' : 'Google token request failed. Retry later.');
+  const token = await response.json();
+  if (typeof token.access_token !== 'string' || !token.access_token || !Number.isFinite(token.expires_in) || token.expires_in <= 0) throw Error('Google returned an invalid access token.');
+  if (token.scope && !GMAIL_SCOPES.every(scope => token.scope.split(' ').includes(scope))) throw Error('Grant all three Gmail permissions, then reconnect.');
+  return { access_token: token.access_token, expiresAt: Date.now() + token.expires_in * 1000,
+    ...(typeof token.refresh_token === 'string' ? { refresh_token: token.refresh_token } : {}) };
+}
+
+export const openGoogleBrowser = url => new Promise((resolve, reject) => {
+  execFile(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { timeout: 10000 }, error => error ? reject(Error('Could not open the browser for Google login.')) : resolve());
+});
+
+export async function authorizeGoogle(client, { fetchImpl = fetch, openBrowser = openGoogleBrowser, signal, timeoutMs = 180000 } = {}) {
+  const verifier = randomBytes(32).toString('base64url'), state = randomBytes(32).toString('base64url');
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, timeoutMs);
+  let resolveCode, rejectCode;
+  const codeResult = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+  codeResult.catch(() => {});
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    res.setHeader('Cache-Control', 'no-store'); res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    if (req.method !== 'GET' || url.pathname !== '/oauth/callback' || url.searchParams.get('state') !== state) { res.writeHead(400).end('Invalid callback.'); return; }
+    if (url.searchParams.has('error')) { res.end('Google authorization was declined. Return to DSCODE.'); rejectCode(Error('Google authorization was declined.')); return; }
+    const code = url.searchParams.get('code');
+    if (!code) { res.writeHead(400).end('Missing code.'); return; }
+    res.end('Authorization received. Return to DSCODE to see connection status.');
+    resolveCode(code);
+  });
+  controller.signal.addEventListener('abort', () => rejectCode(Error('Google login cancelled or timed out.')), { once: true });
+  try {
+    if (signal?.aborted) throw Error('Google login cancelled.');
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+    const redirect = 'http://127.0.0.1:' + server.address().port + '/oauth/callback';
+    const url = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+    url.search = new URLSearchParams({ client_id: client.client_id, redirect_uri: redirect,
+      response_type: 'code', scope: GMAIL_SCOPES.join(' '), access_type: 'offline', prompt: 'consent select_account',
+      state, code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256' }).toString();
+    await openBrowser(url.href);
+    const code = await codeResult;
+    const token = await tokenRequest({ ...client, code, redirect_uri: redirect, code_verifier: verifier, grant_type: 'authorization_code' }, { fetchImpl, signal: controller.signal });
+    if (!token.refresh_token) throw Error('Google did not grant offline access. Reconnect Gmail.');
+    return token;
+  } finally {
+    clearTimeout(timer); signal?.removeEventListener('abort', abort);
+    server.close(); server.closeAllConnections();
+  }
+}

package/plugins/email/gmail-store.mjs

@@ -0,0 +1,2 @@
+import { emailStore } from './store.mjs';
+export const gmailStore = directory => emailStore(directory, 'Gmail');

package/plugins/email/gmail.mjs

@@ -0,0 +1,194 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { createEmailInbox, normalizeEmail } from './inbox.mjs';
+import { gmailStore } from './gmail-store.mjs';
+import { readGoogleClient, authorizeGoogle, tokenRequest } from './gmail-oauth.mjs';
+
+const LABEL = 'ToAgent';
+const FILTER = { subject: '[ToAgent]' };
+const isId = value => typeof value === 'string' && /^[a-zA-Z0-9_-]+$/.test(value);
+const historyId = value => { if (typeof value !== 'string' || !/^\d+$/.test(value)) throw Error('Invalid Gmail sync cursor.'); return value; };
+const header = (part, name) => (part?.headers || []).find(h => h.name?.toLowerCase() === name.toLowerCase())?.value || '';
+const decode = (data, charset = 'utf-8') => {
+  if (typeof data !== 'string' || data.length > 400000 || !/^[A-Za-z0-9_-]*={0,2}$/.test(data)) throw Error('Invalid or oversized plain-text body.');
+  try { return new TextDecoder(charset, { fatal: true }).decode(Buffer.from(data, 'base64url')); }
+  catch { throw Error('Invalid plain-text encoding.'); }
+};
+export function decodeHeader(value) {
+  return value.replace(/(\?=)\s+(=\?)/g, '$1$2').replace(/=\?([^?]+)\?([bq])\?([^?]*)\?=/gi, (_, charset, type, data) => {
+    const bytes = type.toLowerCase() === 'b' ? Buffer.from(data, 'base64') : Buffer.from(data.replace(/_/g, ' ').replace(/=([a-f0-9]{2})/gi, (_, n) => String.fromCharCode(parseInt(n, 16))), 'latin1');
+    try { return new TextDecoder(charset, { fatal: true }).decode(bytes); }
+    catch { throw Error('Invalid header encoding.'); }
+  });
+}
+export function matchesGmailMessage(message, state) {
+  const date = Number(message.internalDate);
+  return Array.isArray(message.labelIds) && message.labelIds.includes(state.labelId)
+    && !message.labelIds.some(id => ['SPAM', 'TRASH', 'DRAFT', 'SENT'].includes(id))
+    && Number.isFinite(date) && date >= state.connectedAt
+    && /^\[ToAgent\](?:\s|$)/.test(decodeHeader(header(message.payload, 'subject')));
+}
+export async function gmailEnvelope(message, state, getAttachment) {
+  if (!matchesGmailMessage(message, state)) return null;
+  const findPlain = (part, depth = 0) => {
+    if (!part || depth > 20 || part.filename || /^attachment\b/i.test(header(part, 'content-disposition'))) return null;
+    if (part.mimeType === 'text/plain') return part;
+    if (!part.mimeType?.startsWith('multipart/')) return null;
+    for (const child of part.parts || []) { const found = findPlain(child, depth + 1); if (found) return found; }
+    return null;
+  };
+  const part = findPlain(message.payload);
+  if (!part || part.body?.size > 262144) return null;
+  const body = part.body?.data ?? (part.body?.attachmentId ? (await getAttachment(part.body.attachmentId)).data : '');
+  const charset = header(part, 'content-type').match(/charset\s*=\s*"?([^;"\s]+)/i)?.[1] || 'utf-8';
+  return normalizeEmail({ format: 'dscode.email.v1', connector: 'gmail', account: state.account,
+    id: message.id, from: decodeHeader(header(message.payload, 'from')), subject: decodeHeader(header(message.payload, 'subject')),
+    body: decode(body, charset), receivedAt: new Date(Number(message.internalDate)).toISOString(),
+    updatedAt: new Date(Number(message.internalDate)).toISOString() });
+}
+
+export function createGmailConnector({ inbox = createEmailInbox(), directory = join(inbox.directory, 'gmail'), fetchImpl = fetch, authorize = authorizeGoogle, openBrowser, now = Date.now } = {}) {
+  const store = gmailStore(directory);
+  const clientPath = () => process.env.DSCODE_GMAIL_CLIENT_FILE || join(directory, 'client.json');
+  let working = false;
+  const exclusive = async action => {
+    if (working) return { busy: true };
+    working = true;
+    try { return await store.locked(action); } finally { working = false; }
+  };
+  async function api(token, path, { method = 'GET', body, signal } = {}) {
+    const response = await fetchImpl('https://gmail.googleapis.com/gmail/v1/users/me/' + path, {
+      method, headers: { Authorization: 'Bearer ' + token.access_token, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'error',
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(20000)]) : AbortSignal.timeout(20000),
+    });
+    if (!response.ok) {
+      const error = Error(response.status === 401 ? 'Gmail authorization expired. Press g to reconnect.' : response.status === 403 ? 'Gmail access denied. Check API enablement and granted permissions, then reconnect.' : 'Gmail request failed (' + response.status + '). Retry sync.');
+      error.status = response.status; throw error;
+    }
+    return response.status === 204 ? {} : response.json();
+  }
+  async function access(signal, force = false) {
+    const token = store.read('tokens.json');
+    if (!token?.refresh_token) throw Error('Gmail is not connected. Press g to connect.');
+    if (!force && token.expiresAt > now() + 60000) return token;
+    const next = { ...token, ...await tokenRequest({ ...readGoogleClient(clientPath()), grant_type: 'refresh_token', refresh_token: token.refresh_token }, { fetchImpl, signal }) };
+    store.write('tokens.json', next); return next;
+  }
+  async function provision(token, signal) {
+    const labels = await api(token, 'labels', { signal });
+    let label = labels.labels?.find(label => label.name === LABEL);
+    if (!label) label = await api(token, 'labels', { method: 'POST', body: { name: LABEL, labelListVisibility: 'labelShow', messageListVisibility: 'show' }, signal });
+    if (!isId(label.id)) throw Error('Invalid Gmail ToAgent label.');
+    const filters = await api(token, 'settings/filters', { signal });
+    const found = filters.filter?.some(filter => JSON.stringify(filter.criteria) === JSON.stringify(FILTER)
+      && filter.action?.addLabelIds?.includes(label.id) && !filter.action?.removeLabelIds?.length && !filter.action?.forward);
+    if (!found) await api(token, 'settings/filters', { method: 'POST', body: { criteria: FILTER, action: { addLabelIds: [label.id] } }, signal });
+    return label.id;
+  }
+  async function collect(token, state, signal) {
+    const ids = new Set();
+    let cursor, pageToken;
+    try {
+      do {
+        const query = new URLSearchParams({ startHistoryId: state.historyId, labelId: state.labelId, maxResults: '100', ...(pageToken ? { pageToken } : {}) });
+        const page = await api(token, 'history?' + query, { signal });
+        for (const event of page.history || []) for (const change of [...(event.messagesAdded || []), ...(event.labelsAdded || [])]) {
+          if (isId(change.message?.id)) ids.add(change.message.id);
+        }
+        cursor = historyId(page.historyId); pageToken = page.nextPageToken;
+      } while (pageToken);
+    } catch (error) {
+      if (error.status !== 404) throw error;
+      // Expired history: capture a new boundary BEFORE listing so changes that
+      // race this recovery are replayed on the next incremental pass.
+      cursor = historyId((await api(token, 'profile', { signal })).historyId);
+      pageToken = undefined;
+      do {
+        const query = new URLSearchParams({ labelIds: state.labelId, q: 'after:' + (Math.floor(state.connectedAt / 1000) - 1), maxResults: '100', ...(pageToken ? { pageToken } : {}) });
+        const page = await api(token, 'messages?' + query, { signal });
+        for (const message of page.messages || []) if (isId(message.id)) ids.add(message.id);
+        pageToken = page.nextPageToken;
+      } while (pageToken);
+    }
+    let accepted = 0, skipped = 0;
+    for (const id of ids) {
+      let metadata;
+      try { metadata = await api(token, 'messages/' + id + '?format=metadata&metadataHeaders=Subject', { signal }); }
+      catch (error) { if (error.status === 404) { skipped++; continue; } throw error; }
+      let matches;
+      try { matches = matchesGmailMessage(metadata, state); } catch { matches = false; }
+      if (!matches) { skipped++; continue; }
+      let message;
+      try { message = await api(token, 'messages/' + id + '?format=full', { signal }); }
+      catch (error) { if (error.status === 404) { skipped++; continue; } throw error; }
+      let envelope;
+      try { envelope = await gmailEnvelope(message, state, attachmentId => {
+        if (!isId(attachmentId)) throw Error('Invalid body attachment.');
+        return api(token, 'messages/' + id + '/attachments/' + attachmentId, { signal });
+      }); } catch (error) {
+        // Network/body fetch failures must retain the cursor for retry.
+        if (error.status || signal?.aborted || error.name === 'TypeError' || error.name === 'TimeoutError') throw error;
+        skipped++; continue;
+      }
+      if (envelope) { inbox.receive(envelope); accepted++; } else skipped++;
+    }
+    return { ...state, historyId: cursor, lastSyncAt: now(), accepted, skipped, error: null };
+  }
+  return {
+    directory,
+    configure(path) {
+      return exclusive(async () => {
+        if (process.env.DSCODE_GMAIL_CLIENT_FILE) throw Error('DSCODE_GMAIL_CLIENT_FILE is set. Unset it before importing a client.');
+        const client = readGoogleClient(path);
+        if (store.exists('tokens.json') && readGoogleClient(clientPath()).client_id !== client.client_id) throw Error('Gmail already uses a different OAuth client. Keep the connected client.');
+        store.write('client.json', { installed: client });
+        return { configured: true };
+      });
+    },
+    status() {
+      try {
+        const state = store.read('state.json');
+        return { configured: existsSync(clientPath()), connected: !!state?.account && store.exists('tokens.json'), account: state?.account,
+          lastSyncAt: state?.lastSyncAt, accepted: state?.accepted || 0, skipped: state?.skipped || 0, error: state?.error || null };
+      } catch { return { connected: false, error: 'Cannot read local Gmail state.' }; }
+    },
+    connect({ signal } = {}) {
+      return exclusive(async () => {
+        const client = readGoogleClient(clientPath());
+        const token = await authorize(client, { fetchImpl, openBrowser, signal });
+        const profile = await api(token, 'profile', { signal });
+        if (typeof profile.emailAddress !== 'string' || !profile.emailAddress.includes('@')) throw Error('Google returned an invalid account.');
+        const old = store.read('state.json');
+        if (old?.account && old.account !== profile.emailAddress) throw Error('One Gmail account is supported. Reconnect the original account.');
+        const labelId = await provision(token, signal);
+        const boundary = historyId((await api(token, 'profile', { signal })).historyId);
+        const state = { account: profile.emailAddress, labelId, connectedAt: old?.connectedAt ?? now(),
+          historyId: old?.historyId ?? boundary, lastSyncAt: old?.lastSyncAt ?? null, error: null };
+        signal?.throwIfAborted();
+        store.write('tokens.json', token);
+        store.write('state.json', state);
+        return { connected: true, account: state.account };
+      });
+    },
+    async sync({ signal, force = false } = {}) {
+      if (!store.exists('state.json')) return { connected: false };
+      return exclusive(async () => {
+        const state = store.read('state.json');
+        if (!state?.account) return { connected: false };
+        if (!force && now() - (state.lastAttemptAt || 0) < 30000) return { throttled: true };
+        state.lastAttemptAt = now(); store.write('state.json', state);
+        try {
+          let next;
+          try { next = await collect(await access(signal), state, signal); }
+          catch (error) { if (error.status !== 401) throw error; next = await collect(await access(signal, true), state, signal); }
+          signal?.throwIfAborted();
+          store.write('state.json', next); return { accepted: next.accepted, skipped: next.skipped };
+        } catch (error) {
+          const safe = error.status ? error.message : /^(Google|Gmail|Grant|Set DSCODE_|Cannot read|Invalid Gmail)/.test(error.message) ? error.message : 'Gmail sync interrupted. Retry sync.';
+          store.write('state.json', { ...state, error: safe }); throw Error(safe);
+        }
+      });
+    },
+  };
+}