clawdbot 2026.1.4-1

package/dist/hooks/gmail-ops.js

@@ -0,0 +1,236 @@
+import { spawn } from "node:child_process";
+import { CONFIG_PATH_CLAWDBOT, loadConfig, readConfigFileSnapshot, resolveGatewayPort, validateConfigObject, writeConfigFile, } from "../config/config.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { defaultRuntime } from "../runtime.js";
+import { buildDefaultHookUrl, buildGogWatchServeArgs, buildGogWatchStartArgs, buildTopicPath, DEFAULT_GMAIL_LABEL, DEFAULT_GMAIL_MAX_BYTES, DEFAULT_GMAIL_RENEW_MINUTES, DEFAULT_GMAIL_SERVE_BIND, DEFAULT_GMAIL_SERVE_PATH, DEFAULT_GMAIL_SERVE_PORT, DEFAULT_GMAIL_SUBSCRIPTION, DEFAULT_GMAIL_TOPIC, generateHookToken, mergeHookPresets, normalizeHooksPath, normalizeServePath, parseTopicPath, resolveGmailHookRuntimeConfig, } from "./gmail.js";
+import { ensureDependency, ensureGcloudAuth, ensureSubscription, ensureTailscaleEndpoint, ensureTopic, resolveProjectIdFromGogCredentials, runGcloud, } from "./gmail-setup-utils.js";
+const DEFAULT_GMAIL_TOPIC_IAM_MEMBER = "serviceAccount:gmail-api-push@system.gserviceaccount.com";
+export async function runGmailSetup(opts) {
+    await ensureDependency("gcloud", ["--cask", "gcloud-cli"]);
+    await ensureDependency("gog", ["gogcli"]);
+    if (opts.tailscale !== "off" && !opts.pushEndpoint) {
+        await ensureDependency("tailscale", ["tailscale"]);
+    }
+    await ensureGcloudAuth();
+    const configSnapshot = await readConfigFileSnapshot();
+    if (!configSnapshot.valid) {
+        throw new Error(`Config invalid: ${CONFIG_PATH_CLAWDBOT}`);
+    }
+    const baseConfig = configSnapshot.config;
+    const hooksPath = normalizeHooksPath(baseConfig.hooks?.path);
+    const hookToken = opts.hookToken ?? baseConfig.hooks?.token ?? generateHookToken();
+    const pushToken = opts.pushToken ?? baseConfig.hooks?.gmail?.pushToken ?? generateHookToken();
+    const topicInput = opts.topic ?? baseConfig.hooks?.gmail?.topic ?? DEFAULT_GMAIL_TOPIC;
+    const parsedTopic = parseTopicPath(topicInput);
+    const topicName = parsedTopic?.topicName ?? topicInput;
+    const projectId = opts.project ??
+        parsedTopic?.projectId ??
+        (await resolveProjectIdFromGogCredentials());
+    // Gmail watch requires the Pub/Sub topic to live in the OAuth client project.
+    if (!projectId) {
+        throw new Error("GCP project id required (use --project or ensure gog credentials are available)");
+    }
+    const topicPath = buildTopicPath(projectId, topicName);
+    const subscription = opts.subscription ?? DEFAULT_GMAIL_SUBSCRIPTION;
+    const label = opts.label ?? DEFAULT_GMAIL_LABEL;
+    const hookUrl = opts.hookUrl ??
+        baseConfig.hooks?.gmail?.hookUrl ??
+        buildDefaultHookUrl(hooksPath, resolveGatewayPort(baseConfig));
+    const serveBind = opts.bind ?? DEFAULT_GMAIL_SERVE_BIND;
+    const servePort = opts.port ?? DEFAULT_GMAIL_SERVE_PORT;
+    const configuredServePath = opts.path ?? baseConfig.hooks?.gmail?.serve?.path;
+    const includeBody = opts.includeBody ?? true;
+    const maxBytes = opts.maxBytes ?? DEFAULT_GMAIL_MAX_BYTES;
+    const renewEveryMinutes = opts.renewEveryMinutes ?? DEFAULT_GMAIL_RENEW_MINUTES;
+    const tailscaleMode = opts.tailscale ?? "funnel";
+    // Tailscale strips the path before proxying; keep a public path while gog
+    // listens on "/" unless the user explicitly configured a serve path.
+    const servePath = normalizeServePath(tailscaleMode !== "off" && !configuredServePath
+        ? "/"
+        : (configuredServePath ?? DEFAULT_GMAIL_SERVE_PATH));
+    const tailscalePath = normalizeServePath(opts.tailscalePath ??
+        baseConfig.hooks?.gmail?.tailscale?.path ??
+        (tailscaleMode !== "off"
+            ? (configuredServePath ?? DEFAULT_GMAIL_SERVE_PATH)
+            : servePath));
+    await runGcloud(["config", "set", "project", projectId, "--quiet"]);
+    await runGcloud([
+        "services",
+        "enable",
+        "gmail.googleapis.com",
+        "pubsub.googleapis.com",
+        "--project",
+        projectId,
+        "--quiet",
+    ]);
+    await ensureTopic(projectId, topicName);
+    await runGcloud([
+        "pubsub",
+        "topics",
+        "add-iam-policy-binding",
+        topicName,
+        "--project",
+        projectId,
+        "--member",
+        DEFAULT_GMAIL_TOPIC_IAM_MEMBER,
+        "--role",
+        "roles/pubsub.publisher",
+        "--quiet",
+    ]);
+    const pushEndpoint = opts.pushEndpoint
+        ? opts.pushEndpoint
+        : await ensureTailscaleEndpoint({
+            mode: tailscaleMode,
+            path: tailscalePath,
+            port: servePort,
+            token: pushToken,
+        });
+    if (!pushEndpoint) {
+        throw new Error("push endpoint required (set --push-endpoint)");
+    }
+    await ensureSubscription(projectId, subscription, topicName, pushEndpoint);
+    await startGmailWatch({
+        account: opts.account,
+        label,
+        topic: topicPath,
+    }, true);
+    const nextConfig = {
+        ...baseConfig,
+        hooks: {
+            ...baseConfig.hooks,
+            enabled: true,
+            path: hooksPath,
+            token: hookToken,
+            presets: mergeHookPresets(baseConfig.hooks?.presets, "gmail"),
+            gmail: {
+                ...baseConfig.hooks?.gmail,
+                account: opts.account,
+                label,
+                topic: topicPath,
+                subscription,
+                pushToken,
+                hookUrl,
+                includeBody,
+                maxBytes,
+                renewEveryMinutes,
+                serve: {
+                    ...baseConfig.hooks?.gmail?.serve,
+                    bind: serveBind,
+                    port: servePort,
+                    path: servePath,
+                },
+                tailscale: {
+                    ...baseConfig.hooks?.gmail?.tailscale,
+                    mode: tailscaleMode,
+                    path: tailscalePath,
+                },
+            },
+        },
+    };
+    const validated = validateConfigObject(nextConfig);
+    if (!validated.ok) {
+        throw new Error(`Config validation failed: ${validated.issues[0]?.message ?? "invalid"}`);
+    }
+    await writeConfigFile(validated.config);
+    const summary = {
+        projectId,
+        topic: topicPath,
+        subscription,
+        pushEndpoint,
+        hookUrl,
+        hookToken,
+        pushToken,
+        serve: {
+            bind: serveBind,
+            port: servePort,
+            path: servePath,
+        },
+    };
+    if (opts.json) {
+        defaultRuntime.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    defaultRuntime.log("Gmail hooks configured:");
+    defaultRuntime.log(`- project: ${projectId}`);
+    defaultRuntime.log(`- topic: ${topicPath}`);
+    defaultRuntime.log(`- subscription: ${subscription}`);
+    defaultRuntime.log(`- push endpoint: ${pushEndpoint}`);
+    defaultRuntime.log(`- hook url: ${hookUrl}`);
+    defaultRuntime.log(`- config: ${CONFIG_PATH_CLAWDBOT}`);
+    defaultRuntime.log("Next: clawdbot hooks gmail run");
+}
+export async function runGmailService(opts) {
+    await ensureDependency("gog", ["gogcli"]);
+    const config = loadConfig();
+    const overrides = {
+        account: opts.account,
+        topic: opts.topic,
+        subscription: opts.subscription,
+        label: opts.label,
+        hookToken: opts.hookToken,
+        pushToken: opts.pushToken,
+        hookUrl: opts.hookUrl,
+        serveBind: opts.bind,
+        servePort: opts.port,
+        servePath: opts.path,
+        includeBody: opts.includeBody,
+        maxBytes: opts.maxBytes,
+        renewEveryMinutes: opts.renewEveryMinutes,
+        tailscaleMode: opts.tailscale,
+        tailscalePath: opts.tailscalePath,
+    };
+    const resolved = resolveGmailHookRuntimeConfig(config, overrides);
+    if (!resolved.ok) {
+        throw new Error(resolved.error);
+    }
+    const runtimeConfig = resolved.value;
+    if (runtimeConfig.tailscale.mode !== "off") {
+        await ensureDependency("tailscale", ["tailscale"]);
+        await ensureTailscaleEndpoint({
+            mode: runtimeConfig.tailscale.mode,
+            path: runtimeConfig.tailscale.path,
+            port: runtimeConfig.serve.port,
+        });
+    }
+    await startGmailWatch(runtimeConfig);
+    let shuttingDown = false;
+    let child = spawnGogServe(runtimeConfig);
+    const renewMs = runtimeConfig.renewEveryMinutes * 60_000;
+    const renewTimer = setInterval(() => {
+        void startGmailWatch(runtimeConfig);
+    }, renewMs);
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        clearInterval(renewTimer);
+        child.kill("SIGTERM");
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    child.on("exit", () => {
+        if (shuttingDown)
+            return;
+        defaultRuntime.log("gog watch serve exited; restarting in 2s");
+        setTimeout(() => {
+            if (shuttingDown)
+                return;
+            child = spawnGogServe(runtimeConfig);
+        }, 2000);
+    });
+}
+function spawnGogServe(cfg) {
+    const args = buildGogWatchServeArgs(cfg);
+    defaultRuntime.log(`Starting gog ${args.join(" ")}`);
+    return spawn("gog", args, { stdio: "inherit" });
+}
+async function startGmailWatch(cfg, fatal = false) {
+    const args = ["gog", ...buildGogWatchStartArgs(cfg)];
+    const result = await runCommandWithTimeout(args, { timeoutMs: 120_000 });
+    if (result.code !== 0) {
+        const message = result.stderr || result.stdout || "gog watch start failed";
+        if (fatal)
+            throw new Error(message);
+        defaultRuntime.error(message);
+    }
+}

package/dist/hooks/gmail-setup-utils.js

@@ -0,0 +1,278 @@
+import fs from "node:fs";
+import path from "node:path";
+import { hasBinary } from "../agents/skills.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { resolveUserPath } from "../utils.js";
+import { normalizeServePath } from "./gmail.js";
+let cachedPythonPath;
+function findExecutablesOnPath(bins) {
+    const pathEnv = process.env.PATH ?? "";
+    const parts = pathEnv.split(path.delimiter).filter(Boolean);
+    const seen = new Set();
+    const matches = [];
+    for (const part of parts) {
+        for (const bin of bins) {
+            const candidate = path.join(part, bin);
+            if (seen.has(candidate))
+                continue;
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                matches.push(candidate);
+                seen.add(candidate);
+            }
+            catch {
+                // keep scanning
+            }
+        }
+    }
+    return matches;
+}
+function ensurePathIncludes(dirPath, position) {
+    const pathEnv = process.env.PATH ?? "";
+    const parts = pathEnv.split(path.delimiter).filter(Boolean);
+    if (parts.includes(dirPath))
+        return;
+    const next = position === "prepend" ? [dirPath, ...parts] : [...parts, dirPath];
+    process.env.PATH = next.join(path.delimiter);
+}
+function ensureGcloudOnPath() {
+    if (hasBinary("gcloud"))
+        return true;
+    const candidates = [
+        "/opt/homebrew/share/google-cloud-sdk/bin/gcloud",
+        "/usr/local/share/google-cloud-sdk/bin/gcloud",
+        "/opt/homebrew/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/bin/gcloud",
+        "/usr/local/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/bin/gcloud",
+    ];
+    for (const candidate of candidates) {
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            ensurePathIncludes(path.dirname(candidate), "append");
+            return true;
+        }
+        catch {
+            // keep scanning
+        }
+    }
+    return false;
+}
+export async function resolvePythonExecutablePath() {
+    if (cachedPythonPath !== undefined) {
+        return cachedPythonPath ?? undefined;
+    }
+    const candidates = findExecutablesOnPath(["python3", "python"]);
+    for (const candidate of candidates) {
+        const res = await runCommandWithTimeout([
+            candidate,
+            "-c",
+            "import os, sys; print(os.path.realpath(sys.executable))",
+        ], { timeoutMs: 2_000 });
+        if (res.code !== 0)
+            continue;
+        const resolved = res.stdout.trim().split(/\s+/)[0];
+        if (!resolved)
+            continue;
+        try {
+            fs.accessSync(resolved, fs.constants.X_OK);
+            cachedPythonPath = resolved;
+            return resolved;
+        }
+        catch {
+            // keep scanning
+        }
+    }
+    cachedPythonPath = null;
+    return undefined;
+}
+async function gcloudEnv() {
+    if (process.env.CLOUDSDK_PYTHON)
+        return undefined;
+    const pythonPath = await resolvePythonExecutablePath();
+    if (!pythonPath)
+        return undefined;
+    return { CLOUDSDK_PYTHON: pythonPath };
+}
+async function runGcloudCommand(args, timeoutMs) {
+    return await runCommandWithTimeout(["gcloud", ...args], {
+        timeoutMs,
+        env: await gcloudEnv(),
+    });
+}
+export async function ensureDependency(bin, brewArgs) {
+    if (bin === "gcloud" && ensureGcloudOnPath())
+        return;
+    if (hasBinary(bin))
+        return;
+    if (process.platform !== "darwin") {
+        throw new Error(`${bin} not installed; install it and retry`);
+    }
+    if (!hasBinary("brew")) {
+        throw new Error("Homebrew not installed (install brew and retry)");
+    }
+    const brewEnv = bin === "gcloud" ? await gcloudEnv() : undefined;
+    const result = await runCommandWithTimeout(["brew", "install", ...brewArgs], {
+        timeoutMs: 600_000,
+        env: brewEnv,
+    });
+    if (result.code !== 0) {
+        throw new Error(`brew install failed for ${bin}: ${result.stderr || result.stdout}`);
+    }
+    if (!hasBinary(bin)) {
+        throw new Error(`${bin} still not available after brew install`);
+    }
+}
+export async function ensureGcloudAuth() {
+    const res = await runGcloudCommand(["auth", "list", "--filter", "status:ACTIVE", "--format", "value(account)"], 30_000);
+    if (res.code === 0 && res.stdout.trim())
+        return;
+    const login = await runGcloudCommand(["auth", "login"], 600_000);
+    if (login.code !== 0) {
+        throw new Error(login.stderr || "gcloud auth login failed");
+    }
+}
+export async function runGcloud(args) {
+    const result = await runGcloudCommand(args, 120_000);
+    if (result.code !== 0) {
+        throw new Error(result.stderr || result.stdout || "gcloud command failed");
+    }
+    return result;
+}
+export async function ensureTopic(projectId, topicName) {
+    const describe = await runGcloudCommand(["pubsub", "topics", "describe", topicName, "--project", projectId], 30_000);
+    if (describe.code === 0)
+        return;
+    await runGcloud([
+        "pubsub",
+        "topics",
+        "create",
+        topicName,
+        "--project",
+        projectId,
+    ]);
+}
+export async function ensureSubscription(projectId, subscription, topicName, pushEndpoint) {
+    const describe = await runGcloudCommand([
+        "pubsub",
+        "subscriptions",
+        "describe",
+        subscription,
+        "--project",
+        projectId,
+    ], 30_000);
+    if (describe.code === 0) {
+        await runGcloud([
+            "pubsub",
+            "subscriptions",
+            "update",
+            subscription,
+            "--project",
+            projectId,
+            "--push-endpoint",
+            pushEndpoint,
+        ]);
+        return;
+    }
+    await runGcloud([
+        "pubsub",
+        "subscriptions",
+        "create",
+        subscription,
+        "--project",
+        projectId,
+        "--topic",
+        topicName,
+        "--push-endpoint",
+        pushEndpoint,
+    ]);
+}
+export async function ensureTailscaleEndpoint(params) {
+    if (params.mode === "off")
+        return "";
+    const status = await runCommandWithTimeout(["tailscale", "status", "--json"], {
+        timeoutMs: 30_000,
+    });
+    if (status.code !== 0) {
+        throw new Error(status.stderr || "tailscale status failed");
+    }
+    const parsed = JSON.parse(status.stdout);
+    const dnsName = parsed.Self?.DNSName?.replace(/\.$/, "");
+    if (!dnsName) {
+        throw new Error("tailscale DNS name missing; run tailscale up");
+    }
+    const target = String(params.port);
+    const pathArg = normalizeServePath(params.path);
+    const funnelArgs = [
+        "tailscale",
+        params.mode,
+        "--bg",
+        "--set-path",
+        pathArg,
+        "--yes",
+        target,
+    ];
+    const funnelResult = await runCommandWithTimeout(funnelArgs, {
+        timeoutMs: 30_000,
+    });
+    if (funnelResult.code !== 0) {
+        throw new Error(funnelResult.stderr || "tailscale funnel failed");
+    }
+    const baseUrl = `https://${dnsName}${pathArg}`;
+    // Funnel/serve strips pathArg before proxying; keep it only in the public URL.
+    return params.token ? `${baseUrl}?token=${params.token}` : baseUrl;
+}
+export async function resolveProjectIdFromGogCredentials() {
+    const candidates = gogCredentialsPaths();
+    for (const candidate of candidates) {
+        if (!fs.existsSync(candidate))
+            continue;
+        try {
+            const raw = fs.readFileSync(candidate, "utf-8");
+            const parsed = JSON.parse(raw);
+            const clientId = extractGogClientId(parsed);
+            const projectNumber = extractProjectNumber(clientId);
+            if (!projectNumber)
+                continue;
+            const res = await runGcloudCommand([
+                "projects",
+                "list",
+                "--filter",
+                `projectNumber=${projectNumber}`,
+                "--format",
+                "value(projectId)",
+            ], 30_000);
+            if (res.code !== 0)
+                continue;
+            const projectId = res.stdout.trim().split(/\s+/)[0];
+            if (projectId)
+                return projectId;
+        }
+        catch {
+            // keep scanning
+        }
+    }
+    return null;
+}
+function gogCredentialsPaths() {
+    const paths = [];
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg) {
+        paths.push(path.join(xdg, "gogcli", "credentials.json"));
+    }
+    paths.push(resolveUserPath("~/.config/gogcli/credentials.json"));
+    if (process.platform === "darwin") {
+        paths.push(resolveUserPath("~/Library/Application Support/gogcli/credentials.json"));
+    }
+    return paths;
+}
+function extractGogClientId(parsed) {
+    const installed = parsed.installed;
+    const web = parsed.web;
+    const candidate = installed?.client_id || web?.client_id || parsed.client_id || "";
+    return typeof candidate === "string" ? candidate : null;
+}
+function extractProjectNumber(clientId) {
+    if (!clientId)
+        return null;
+    const match = clientId.match(/^(\d+)-/);
+    return match?.[1] ?? null;
+}

package/dist/hooks/gmail-watcher.js

@@ -0,0 +1,175 @@
+/**
+ * Gmail Watcher Service
+ *
+ * Automatically starts `gog gmail watch serve` when the gateway starts,
+ * if hooks.gmail is configured with an account.
+ */
+import { spawn } from "node:child_process";
+import { hasBinary } from "../agents/skills.js";
+import { createSubsystemLogger } from "../logging.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { buildGogWatchServeArgs, buildGogWatchStartArgs, resolveGmailHookRuntimeConfig, } from "./gmail.js";
+import { ensureTailscaleEndpoint } from "./gmail-setup-utils.js";
+const log = createSubsystemLogger("gmail-watcher");
+let watcherProcess = null;
+let renewInterval = null;
+let shuttingDown = false;
+let currentConfig = null;
+/**
+ * Check if gog binary is available
+ */
+function isGogAvailable() {
+    return hasBinary("gog");
+}
+/**
+ * Start the Gmail watch (registers with Gmail API)
+ */
+async function startGmailWatch(cfg) {
+    const args = ["gog", ...buildGogWatchStartArgs(cfg)];
+    try {
+        const result = await runCommandWithTimeout(args, { timeoutMs: 120_000 });
+        if (result.code !== 0) {
+            const message = result.stderr || result.stdout || "gog watch start failed";
+            log.error(`watch start failed: ${message}`);
+            return false;
+        }
+        log.info(`watch started for ${cfg.account}`);
+        return true;
+    }
+    catch (err) {
+        log.error(`watch start error: ${String(err)}`);
+        return false;
+    }
+}
+/**
+ * Spawn the gog gmail watch serve process
+ */
+function spawnGogServe(cfg) {
+    const args = buildGogWatchServeArgs(cfg);
+    log.info(`starting gog ${args.join(" ")}`);
+    const child = spawn("gog", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: false,
+    });
+    child.stdout?.on("data", (data) => {
+        const line = data.toString().trim();
+        if (line)
+            log.info(`[gog] ${line}`);
+    });
+    child.stderr?.on("data", (data) => {
+        const line = data.toString().trim();
+        if (line)
+            log.warn(`[gog] ${line}`);
+    });
+    child.on("error", (err) => {
+        log.error(`gog process error: ${String(err)}`);
+    });
+    child.on("exit", (code, signal) => {
+        if (shuttingDown)
+            return;
+        log.warn(`gog exited (code=${code}, signal=${signal}); restarting in 5s`);
+        watcherProcess = null;
+        setTimeout(() => {
+            if (shuttingDown || !currentConfig)
+                return;
+            watcherProcess = spawnGogServe(currentConfig);
+        }, 5000);
+    });
+    return child;
+}
+/**
+ * Start the Gmail watcher service.
+ * Called automatically by the gateway if hooks.gmail is configured.
+ */
+export async function startGmailWatcher(cfg) {
+    // Check if gmail hooks are configured
+    if (!cfg.hooks?.enabled) {
+        return { started: false, reason: "hooks not enabled" };
+    }
+    if (!cfg.hooks?.gmail?.account) {
+        return { started: false, reason: "no gmail account configured" };
+    }
+    // Check if gog is available
+    const gogAvailable = isGogAvailable();
+    if (!gogAvailable) {
+        return { started: false, reason: "gog binary not found" };
+    }
+    // Resolve the full runtime config
+    const resolved = resolveGmailHookRuntimeConfig(cfg, {});
+    if (!resolved.ok) {
+        return { started: false, reason: resolved.error };
+    }
+    const runtimeConfig = resolved.value;
+    currentConfig = runtimeConfig;
+    // Set up Tailscale endpoint if needed
+    if (runtimeConfig.tailscale.mode !== "off") {
+        try {
+            await ensureTailscaleEndpoint({
+                mode: runtimeConfig.tailscale.mode,
+                path: runtimeConfig.tailscale.path,
+                port: runtimeConfig.serve.port,
+            });
+            log.info(`tailscale ${runtimeConfig.tailscale.mode} configured for port ${runtimeConfig.serve.port}`);
+        }
+        catch (err) {
+            log.error(`tailscale setup failed: ${String(err)}`);
+            return {
+                started: false,
+                reason: `tailscale setup failed: ${String(err)}`,
+            };
+        }
+    }
+    // Start the Gmail watch (register with Gmail API)
+    const watchStarted = await startGmailWatch(runtimeConfig);
+    if (!watchStarted) {
+        log.warn("gmail watch start failed, but continuing with serve");
+    }
+    // Spawn the gog serve process
+    shuttingDown = false;
+    watcherProcess = spawnGogServe(runtimeConfig);
+    // Set up renewal interval
+    const renewMs = runtimeConfig.renewEveryMinutes * 60_000;
+    renewInterval = setInterval(() => {
+        if (shuttingDown)
+            return;
+        void startGmailWatch(runtimeConfig);
+    }, renewMs);
+    log.info(`gmail watcher started for ${runtimeConfig.account} (renew every ${runtimeConfig.renewEveryMinutes}m)`);
+    return { started: true };
+}
+/**
+ * Stop the Gmail watcher service.
+ */
+export async function stopGmailWatcher() {
+    shuttingDown = true;
+    if (renewInterval) {
+        clearInterval(renewInterval);
+        renewInterval = null;
+    }
+    if (watcherProcess) {
+        log.info("stopping gmail watcher");
+        watcherProcess.kill("SIGTERM");
+        // Wait a bit for graceful shutdown
+        await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                if (watcherProcess) {
+                    watcherProcess.kill("SIGKILL");
+                }
+                resolve();
+            }, 3000);
+            watcherProcess?.on("exit", () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+        });
+        watcherProcess = null;
+    }
+    currentConfig = null;
+    log.info("gmail watcher stopped");
+}
+/**
+ * Check if the Gmail watcher is running.
+ */
+export function isGmailWatcherRunning() {
+    return watcherProcess !== null && !shuttingDown;
+}