agentcollar 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 ank8dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT license above applies to the source code in this repository.
+It does NOT apply to the brand assets in the brand/ folder (logos, marks and
+hand-drawn illustrations): those are © 2026 ank8dev, all rights reserved.

package/README.md

@@ -1,5 +1,84 @@
-# agentcollar
+# AgentCollar
 
-Name reserved for [AgentCollar](https://github.com/ank8dev/agentcollar).
-This version contains no code. Real releases (0.1.0 and later) are built and published by
-GitHub Actions with npm provenance.
+**Let agents work. Keep the keys.** A small broker that runs on your own computer, between your AI
+agents and your accounts. Agents get a short-lived, task-scoped *mandate* that you approve in
+Telegram — never your password or tokens.
+
+> **Hobby project. Use at your own risk. Do not connect accounts you can't afford to lose.**
+> **Status: paused.** It works end to end (Claude Code → Telegram approval → real Gmail drafts), but
+> development is paused and may never resume. The code stays open (MIT): fork it if you need it.
+
+## Install
+
+Requires **Node.js 22+**.
+
+```bash
+npx agentcollar          # try it without installing
+npm install -g agentcollar   # or install: then the short name `agcl` works too
+```
+
+`agcl` and `agentcollar` are the same program: `agcl watch` == `agentcollar watch`.
+
+## First run
+
+```bash
+agcl
+```
+
+The intro plays, then the setup wizard connects **your own** Telegram bot (create one with
+[@BotFather](https://t.me/BotFather); the wizard takes your user id from the Start message, with a
+one-time code), then the broker starts on `127.0.0.1:8787`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agcl` | intro → setup (if not set up yet) → broker |
+| `agcl setup` | connect your Telegram bot |
+| `agcl server` | start the broker |
+| `agcl watch` | live screen: every agent request and which of the 6 checks passed or failed |
+| `agcl mandates` | mandates of the running broker: state, time left, actions left |
+| `agcl logs [--agent <name>] [--denied] [--today]` | the audit log, filtered |
+| `agcl revoke <id>` | kill switch: revoke a mandate instantly |
+| `agcl mcp` | MCP server (stdio) for Claude Code and other agents |
+
+Flags: `--no-intro`, `-h` / `--help`.
+
+## Use it from Claude Code (MCP)
+
+```bash
+claude mcp add agentcollar -- npx -y agentcollar mcp
+```
+
+Tools: `request_mandate`, `mandate_status`, `gmail_read_inbox`, `gmail_create_draft`, `gmail_send`.
+Every call goes through the broker with a mandate token. The token stays inside the MCP server and
+is never shown to the model.
+
+## How a request is checked
+
+Every request runs 6 checks in order; the first failure stops it:
+
+1. the token is known → `401`
+2. a human approved the mandate → `403`
+3. not expired → `403`
+4. not revoked → `403`
+5. this action is in the mandate → `403`
+6. the action limit is not reached → `429`
+
+## Security
+
+- Listens on `127.0.0.1` only; refuses browser requests (`Host` check against DNS rebinding,
+  no `Origin`, JSON only).
+- **Approval is never possible over HTTP or through files**: only in Telegram (only your user id)
+  or in the broker's own terminal. A local agent cannot approve itself.
+- Your data lives in `~/.agentcollar/` (folder `700`, files `600`): `.env`, `audit.log`,
+  `mandates.json` (no tokens in it).
+- Append-only audit log; text from agents is escaped and stripped of terminal control characters.
+- **No runtime dependencies.** Published from GitHub Actions with npm provenance.
+
+## License
+
+Code: MIT. The AgentCollar brand assets (logo, the intro medallion derived from it) are
+© ank8dev, all rights reserved. See [LICENSE](LICENSE).
+
+Source, roadmap and full docs: <https://github.com/ank8dev/agentcollar>

package/dist/approval.js

@@ -0,0 +1,67 @@
+// Phase 3: a human decides about every mandate request.
+// Two channels: Telegram (if configured) or the terminal where the server runs.
+import { createInterface } from "node:readline/promises";
+import { writeAudit } from "./audit.js";
+import { approve, deny, findStalePending, revoke } from "./mandate.js";
+// The single place where a human decision is applied and written to the audit log.
+// Telegram and the terminal both end up here.
+export function decide(id, decision, by) {
+    const mandate = decision === "approve" ? approve(id) : decision === "deny" ? deny(id) : revoke(id);
+    if (mandate !== undefined) {
+        writeAudit(mandate.agent, `mandate.${decision}`, decision === "approve", `${decision} by ${by}, mandate ${id}`);
+    }
+    return mandate;
+}
+// Fail closed: a request nobody answered in time is denied, never left hanging.
+// Returns the mandates it denied, so the server can update their Telegram messages.
+export function denyStalePending(maxAgeMs, now = Date.now()) {
+    const denied = [];
+    for (const mandate of findStalePending(maxAgeMs, now)) {
+        const result = decide(mandate.id, "deny", "timeout");
+        if (result !== undefined)
+            denied.push(result);
+    }
+    return denied;
+}
+// Text written by the agent (its name, the task) is shown to the human, so a bad agent
+// could try to fake lines like "Actions: gmail.read" with line breaks, or hide text with
+// invisible / right-to-left characters. We squash it into one short, plain line.
+export function oneLine(text, max) {
+    const plain = text
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ") // line breaks, control chars
+        .replace(/[\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, "") // invisible, direction tricks
+        .replace(/\s+/g, " ")
+        .trim();
+    return plain.length > max ? plain.slice(0, max) + "…" : plain;
+}
+// Human-readable summary, used in the terminal and in Telegram.
+// The facts the broker enforces come FIRST; the agent's own words come last, in quotes.
+export function describe(mandate) {
+    const lines = [];
+    if (mandate.allowedActions.some((action) => action.endsWith(".send"))) {
+        lines.push("⚠️ The agent asks for the right to SEND in your name");
+    }
+    lines.push(`Actions: ${mandate.allowedActions.join(", ")}`, `Lifetime: ${mandate.expiresInSeconds} s after approval, limit ${mandate.limit} actions`, `id: ${mandate.id}`, `Agent: ${oneLine(mandate.agent, 64)}`, `Task (agent's own words): “${oneLine(mandate.task, 200)}”`);
+    return lines.join("\n");
+}
+// Terminal channel. Questions are asked one at a time: if two agents ask at once,
+// the second question waits until the first one is answered.
+let queue = Promise.resolve();
+export function askInTerminal(mandate) {
+    queue = queue.then(async () => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(`\nNew mandate request:\n${describe(mandate)}\nApprove? [y/N] `);
+        rl.close();
+        console.log(applyTerminalAnswer(mandate, answer));
+    });
+}
+// Applies the human's terminal answer and says what REALLY happened.
+// The question may have waited so long that the mandate already timed out
+// (or was decided in Telegram): then the answer changes nothing, and we say so.
+export function applyTerminalAnswer(mandate, answer) {
+    const decision = answer.trim().toLowerCase() === "y" ? "approve" : "deny";
+    if (decide(mandate.id, decision, "terminal") === undefined) {
+        return "  ⌛ already decided (timed out or answered in Telegram), your answer was not applied";
+    }
+    return decision === "approve" ? "  ✅ approved" : "  ❌ denied";
+}

package/dist/audit-log.js

@@ -0,0 +1,37 @@
+// Reads data/audit.log back into objects, for `agentcollar logs` and `agentcollar watch`.
+// Line format (see audit.ts):  time | "agent" | "action" | ALLOWED|DENIED | "reason" [| code]
+import { existsSync, readFileSync } from "node:fs";
+// A JSON string: quote, then any characters except an unescaped quote, then quote.
+// Matching whole strings (not splitting on " | ") keeps a " | " inside the text in one piece.
+const QUOTED = String.raw `"(?:[^"\\]|\\.)*"`;
+const LINE = new RegExp(String.raw `^(\S+) \| (${QUOTED}) \| (${QUOTED}) \| (ALLOWED|DENIED) \| (${QUOTED})(?: \| ([a-z_]+))?$`);
+// The very first lines (before escaping was added in step 4.1) had no quotes at all.
+const OLD_LINE = /^(\S+) \| ([^|"]+) \| ([^|"]+) \| (ALLOWED|DENIED) \| ([^|"]*)$/;
+export function parseAuditLine(line) {
+    const match = LINE.exec(line);
+    if (match !== null) {
+        const [, time, agent, action, verdict, reason, code] = match;
+        return {
+            time: time,
+            agent: JSON.parse(agent),
+            action: JSON.parse(action),
+            allowed: verdict === "ALLOWED",
+            reason: JSON.parse(reason),
+            code: code ?? null,
+        };
+    }
+    const old = OLD_LINE.exec(line);
+    if (old !== null) {
+        const [, time, agent, action, verdict, reason] = old;
+        return { time: time, agent: agent, action: action, allowed: verdict === "ALLOWED", reason: reason, code: null };
+    }
+    return null; // not a log line: skip it rather than guess
+}
+export function readAuditLog(file) {
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .map(parseAuditLine)
+        .filter((entry) => entry !== null);
+}

package/dist/audit.js

@@ -0,0 +1,23 @@
+import { appendFileSync } from "node:fs";
+import { auditLogFile, ensureHome } from "./paths.js";
+// ~/.agentcollar/audit.log (see paths.ts). Re-exported for the modules that read the log.
+export { auditLogFile };
+// Text that came from outside (agent name, action) could contain a line break
+// and fake a second log line. JSON.stringify wraps it in quotes and turns a line
+// break into a visible \n, so one event is always exactly one line.
+function safe(text) {
+    return JSON.stringify(text);
+}
+// Appends one line per event: every check, and every human decision.
+// We only ever add lines, never change or delete them.
+// The token is NOT written: it is a secret, and the log is not.
+// `code` (only for checks) says which check decided, e.g. "expired": `agentcollar watch` shows it.
+export function writeAudit(agent, action, allowed, reason, code) {
+    ensureHome(); // ~/.agentcollar/ with rights 700
+    const time = new Date().toISOString(); // e.g. 2026-10-04T07:00:00.000Z (UTC)
+    const verdict = allowed ? "ALLOWED" : "DENIED";
+    const fields = [time, safe(agent), safe(action), verdict, safe(reason)];
+    if (code !== undefined)
+        fields.push(code); // our own fixed word: needs no quoting
+    appendFileSync(auditLogFile, fields.join(" | ") + "\n", { mode: 0o600 }); // 600 when the file is created
+}

package/dist/check.js

@@ -0,0 +1,52 @@
+import { writeAudit } from "./audit.js";
+import { mandates, mandatesChanged } from "./mandate.js";
+// The order of the checks. A failure code tells how far a request got: "expired" = check 3.
+export const CHECK_ORDER = ["unknown_token", "not_approved", "expired", "revoked", "action_not_allowed", "limit_reached"];
+// The one function the outside world calls: decide, then write it down.
+// Every answer goes to the audit log, allowed or denied.
+export function check(token, action) {
+    const result = runChecks(token, action);
+    // For an unknown token there is no mandate, so no agent name either.
+    const agent = mandates.get(token)?.agent ?? "unknown";
+    writeAudit(agent, action, result.allowed, result.reason, result.code);
+    return result;
+}
+function deny(code, reason) {
+    return { allowed: false, code, reason };
+}
+// Runs the checks in order. The first failed check stops everything (early return).
+function runChecks(token, action) {
+    // 1. Token is known: we issued it ourselves
+    const mandate = mandates.get(token);
+    if (mandate === undefined) {
+        return deny("unknown_token", "unknown token");
+    }
+    // 2. A human approved it (Phase 3). Must come before "expired":
+    //    a pending mandate has no expiry time yet.
+    if (mandate.status === "pending") {
+        return deny("not_approved", "mandate is waiting for human approval");
+    }
+    if (mandate.status === "denied") {
+        return deny("not_approved", "mandate was denied (by the human, or no answer in time)");
+    }
+    // 3. Not expired
+    if (Date.now() > mandate.expiresAt) {
+        return deny("expired", "mandate expired");
+    }
+    // 4. Not revoked by the human (kill switch)
+    if (mandate.revoked) {
+        return deny("revoked", "mandate revoked");
+    }
+    // 5. This action is on the list
+    if (!mandate.allowedActions.includes(action)) {
+        return deny("action_not_allowed", `action "${action}" is not allowed`);
+    }
+    // 6. Limit not reached
+    if (mandate.used >= mandate.limit) {
+        return deny("limit_reached", `limit of ${mandate.limit} actions reached`);
+    }
+    // All checks passed. Only allowed actions use up the limit.
+    mandate.used += 1;
+    mandatesChanged();
+    return { allowed: true, code: "ok", reason: "ok" };
+}

package/dist/cli/format.js

@@ -0,0 +1,86 @@
+// How one audit entry looks on screen. Shared by `agentcollar logs` and `agentcollar watch`.
+import { styleText } from "node:util";
+import { oneLine } from "../approval.js";
+import { CHECK_ORDER } from "../check.js";
+// ✓ passed, ✗ failed here, · not reached. Empty for human decisions and old lines without a code.
+export function checkMarks(entry) {
+    if (entry.code === null)
+        return "";
+    const failedAt = entry.code === "ok" ? CHECK_ORDER.length : CHECK_ORDER.indexOf(entry.code);
+    return CHECK_ORDER.map((_, i) => (i < failedAt ? "✓" : i === failedAt ? "✗" : "·")).join(" ");
+}
+const pad = (n) => String(n).padStart(2, "0");
+export function isSameLocalDay(a, b) {
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+export function isToday(iso, now = new Date()) {
+    return isSameLocalDay(new Date(iso), now);
+}
+// Local time: "15:42:07", or "2026-10-04 15:42:07" when the date matters.
+export function localTime(iso, showDate) {
+    const d = new Date(iso);
+    const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+    return showDate ? `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}` : time;
+}
+// The terminal width right now (it changes when you resize the window). COLUMNS: for pipes and tests.
+export function termWidth() {
+    return process.stdout.columns || Number(process.env.COLUMNS) || 100;
+}
+// Cuts text to `max` visible characters, ending with "…" when something was cut.
+export function fit(text, max) {
+    const chars = [...text];
+    if (max <= 0)
+        return "";
+    return chars.length <= max ? text : chars.slice(0, max - 1).join("") + "…";
+}
+const cell = (text, width) => fit(text, width).padEnd(width);
+// Breaks text into lines of at most `width` characters, at spaces.
+export function wrap(text, width) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line !== "" && [...line].length + 1 + [...word].length > width) {
+            lines.push(line);
+            line = "";
+        }
+        line = line === "" ? fit(word, width) : `${line} ${word}`;
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines;
+}
+// Agent names, actions and reasons come from agents. Printed raw, a text like "\u001b[2J" would
+// be a COMMAND to the terminal (clear screen, change title...). oneLine() strips control characters.
+// Layout follows the window width: wide = one roomy line, medium = one tight line, narrow = two lines.
+export function formatEntry(entry, options) {
+    const width = options.width ?? termWidth();
+    const iso = localTime(entry.time, options.showDate);
+    const time = options.showDate && width < 100 ? iso.slice(5, 16) : iso; // "10-04 15:42" when tight
+    const agent = oneLine(entry.agent, 64);
+    const action = oneLine(entry.action, 64);
+    const reason = oneLine(entry.reason, 300);
+    const human = entry.action.startsWith("mandate."); // approve / deny / revoke by a person
+    const verdict = entry.allowed ? styleText("green", "ALLOWED") : styleText("red", "DENIED ");
+    const dimTime = styleText("dim", time);
+    if (width >= 70) {
+        const wide = width >= 100;
+        const [agentW, actionW] = wide ? [16, 18] : [12, 14];
+        const marks = wide ? checkMarks(entry) : checkMarks(entry).replaceAll(" ", "");
+        const marksW = wide ? 11 : 6;
+        if (human) {
+            const humanActionW = Math.max(actionW, 16); // "mandate.approve" fits
+            const rest = width - time.length - agentW - humanActionW - 6;
+            return `${dimTime}  ${styleText("yellow", `${cell(agent, agentW)}  ${cell(action, humanActionW)}  ${fit(reason, rest)}`)}`;
+        }
+        const rest = width - time.length - agentW - actionW - 7 - marksW - 10;
+        return `${dimTime}  ${cell(agent, agentW)}  ${cell(action, actionW)}  ${verdict}  ${marks.padEnd(marksW)}  ${styleText("dim", fit(reason, rest))}`;
+    }
+    // narrow window: two short lines
+    if (human) {
+        return `${dimTime}  ${styleText("yellow", fit(action, width - time.length - 2))}\n  ${styleText("yellow", fit(`${agent} · ${reason}`, width - 2))}`;
+    }
+    const first = `${dimTime}  ${verdict}  ${fit(action, width - time.length - 11)}`;
+    const marks = checkMarks(entry).replaceAll(" ", "");
+    const second = `  ${marks}  ${styleText("dim", fit(`${agent} · ${reason}`, width - marks.length - 4))}`;
+    return `${first}\n${second}`;
+}

package/dist/cli/gmail-guide.js

@@ -0,0 +1,87 @@
+// A guided walk through Google Cloud for `agcl gmail connect`, for people who have no OAuth client yet.
+// Each step opens the right console page in the browser and says in one line what to click.
+// (Google moves its menus around now and then, so every step also names the page.)
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { styleText } from "node:util";
+import { SCOPES } from "../google/oauth.js";
+export const GUIDE_STEPS = [
+    {
+        title: "Create a project",
+        url: "https://console.cloud.google.com/projectcreate",
+        todo: 'Project name: AgentCollar → Create. Then make sure "AgentCollar" is selected in the top bar.',
+    },
+    {
+        title: "Turn on the Gmail API",
+        url: "https://console.cloud.google.com/apis/library/gmail.googleapis.com",
+        todo: "Click Enable.",
+    },
+    {
+        title: "Consent screen (Google Auth Platform → Overview)",
+        url: "https://console.cloud.google.com/auth/overview",
+        todo: "Get started → App name: AgentCollar (local), your email → Audience: External → contact email → Create.",
+    },
+    {
+        title: "Add yourself as a test user (Audience)",
+        url: "https://console.cloud.google.com/auth/audience",
+        todo: "Test users → Add users → your Gmail address → Save. The app stays in Testing: no Google review needed.",
+    },
+    {
+        title: "Permissions (Data Access)",
+        url: "https://console.cloud.google.com/auth/scopes",
+        todo: "Add or remove scopes → paste these two into “Manually add scopes” → Add to table → Update → Save:",
+        copy: SCOPES,
+    },
+    {
+        title: "Create the client (Clients)",
+        url: "https://console.cloud.google.com/auth/clients/create",
+        todo: "Application type: Desktop app → Name: agcl → Create → Download JSON.",
+    },
+];
+// Waits for a client_secret*.json that appears in `folder` after `since` (an older one is ignored).
+export async function waitForClientFile(folder, since, timeoutMs, pollMs = 1000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(folder)) {
+            const fresh = readdirSync(folder)
+                .filter((name) => name.startsWith("client_secret") && name.endsWith(".json"))
+                .map((name) => join(folder, name))
+                .filter((file) => statSync(file).mtimeMs >= since - 1000);
+            if (fresh[0] !== undefined)
+                return fresh[0];
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return null;
+}
+// Runs the guide in the terminal. Returns the downloaded client file, or null if the user stopped.
+export async function runGuide(downloads) {
+    const started = Date.now();
+    console.log(styleText("bold", "\nGoogle Cloud setup — 6 steps, about 3 minutes."));
+    console.log("Each step opens a page in your browser. Do what it says, then press Enter here.\n");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (const [i, step] of GUIDE_STEPS.entries()) {
+            console.log(`${styleText("cyan", `[${i + 1}/${GUIDE_STEPS.length}]`)} ${styleText("bold", step.title)}`);
+            console.log(`      ${step.todo}`);
+            for (const line of step.copy ?? [])
+                console.log(`        ${styleText("yellow", line)}`);
+            console.log(styleText("dim", `      ${step.url}`));
+            execFile("open", [step.url], () => { });
+            const answer = await rl.question(styleText("dim", "      Enter = done · q = stop "));
+            if (answer.trim().toLowerCase() === "q")
+                return null;
+            console.log("");
+        }
+    }
+    finally {
+        rl.close();
+    }
+    console.log("Waiting for client_secret_….json in your Downloads folder…");
+    const file = await waitForClientFile(downloads, started, 10 * 60 * 1000);
+    if (file === null)
+        console.log("No file in 10 minutes. Run agcl gmail connect again when you have it.");
+    return file;
+}

package/dist/cli/gmail.js

@@ -0,0 +1,125 @@
+// agcl gmail connect | status | disconnect — connect YOUR Gmail (read + drafts).
+// The refresh token goes to the macOS Keychain; the access token only ever lives in memory.
+import { execFile } from "node:child_process";
+import { copyFileSync, chmodSync, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { styleText } from "node:util";
+import { forgetConnection, readGmailInfo, REFRESH_TOKEN_ACCOUNT, saveConnection } from "../google/connection.js";
+import { keychain } from "../google/keychain.js";
+import { authorizeInBrowser, exchangeCode, parseClientJson, refreshAccessToken, revokeToken } from "../google/oauth.js";
+import { ensureHome, googleClientFile } from "../paths.js";
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(question);
+    rl.close();
+    return answer.trim().toLowerCase();
+}
+// The newest client_secret_*.json in ~/Downloads, where Google Cloud puts it.
+function findDownloadedClient() {
+    const downloads = join(homedir(), "Downloads");
+    if (!existsSync(downloads))
+        return null;
+    const files = readdirSync(downloads)
+        .filter((name) => name.startsWith("client_secret") && name.endsWith(".json"))
+        .map((name) => join(downloads, name))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return files[0] ?? null;
+}
+function loadClient() {
+    if (!existsSync(googleClientFile))
+        throw new Error("No Google client yet. Run: agcl gmail connect");
+    return parseClientJson(readFileSync(googleClientFile, "utf8"));
+}
+async function connect(args) {
+    // 1. The Desktop-app client file from Google Cloud
+    let file = args[0] ?? null;
+    if (file === null) {
+        const found = findDownloadedClient();
+        if (found !== null && (await ask(`Use ${found}? [Y/n] `)) !== "n")
+            file = found;
+    }
+    if (file === null && existsSync(googleClientFile))
+        file = googleClientFile;
+    if (file === null) {
+        // No OAuth client yet: walk the person through Google Cloud, page by page.
+        if (!process.stdin.isTTY) {
+            console.error("No Google client yet. Run agcl gmail connect in a terminal for the guided setup,");
+            console.error("or pass the file: agcl gmail connect ~/Downloads/client_secret_….json");
+            return 1;
+        }
+        if ((await ask("No Google client found. Set one up now, step by step? [Y/n] ")) === "n")
+            return 1;
+        file = await (await import("./gmail-guide.js")).runGuide(join(homedir(), "Downloads"));
+        if (file === null)
+            return 1;
+        console.log(`${styleText("green", "✓")} Found ${file}\n`);
+    }
+    const client = parseClientJson(readFileSync(file, "utf8")); // fails early if it is the wrong file
+    ensureHome();
+    if (file !== googleClientFile) {
+        copyFileSync(file, googleClientFile);
+        chmodSync(googleClientFile, 0o600);
+    }
+    // 2. Sign in with Google in the browser
+    console.log("Opening Google in your browser. Allow: read your email + create drafts.");
+    const { code, verifier, redirectUri } = await authorizeInBrowser(client, (url) => {
+        console.log(styleText("dim", `If the browser did not open: ${url}`));
+        execFile("open", [url], () => { });
+    });
+    const tokens = await exchangeCode(client, code, verifier, redirectUri);
+    // 3. Which Gmail is this?
+    const profile = (await (await fetch("https://gmail.googleapis.com/gmail/v1/users/me/profile", { headers: { authorization: `Bearer ${tokens.accessToken}` } })).json());
+    const email = profile.emailAddress ?? "unknown";
+    saveConnection({ email, connectedAt: new Date().toISOString() }, tokens.refreshToken);
+    console.log(`\n${styleText("green", "✓")} Gmail connected: ${styleText("bold", email)}`);
+    console.log("  Read + create drafts. This connection cannot send at all: Google itself blocks it.");
+    console.log("  Refresh token: macOS Keychain. Access token: memory only.");
+    console.log(styleText("yellow", "  Testing mode: Google ends this sign-in after 7 days. Then run agcl gmail connect again."));
+    if (file !== googleClientFile)
+        console.log(styleText("dim", `  You can delete ${file} now (a copy is in ${googleClientFile}).`));
+    console.log("  Restart the broker to use it: agcl server");
+    return 0;
+}
+async function status() {
+    const info = readGmailInfo();
+    const refreshToken = keychain.get(REFRESH_TOKEN_ACCOUNT);
+    if (info === null || refreshToken === null) {
+        console.log("Gmail: not connected (the broker uses a fake inbox). Connect: agcl gmail connect");
+        return 0;
+    }
+    try {
+        await refreshAccessToken(loadClient(), refreshToken);
+        console.log(`${styleText("green", "✓")} Gmail: ${info.email}, connected ${info.connectedAt.slice(0, 10)}, access works.`);
+        return 0;
+    }
+    catch (error) {
+        console.log(`${styleText("red", "✗")} Gmail: ${info.email}: ${error.message}`);
+        return 1;
+    }
+}
+async function disconnect() {
+    const token = forgetConnection();
+    if (token !== null)
+        await revokeToken(token); // also tell Google to cancel the access
+    console.log("Gmail disconnected: the Keychain entry is deleted and Google access is revoked.");
+    return 0;
+}
+export async function runGmail(args) {
+    const [sub, ...rest] = args;
+    try {
+        if (sub === "connect")
+            return await connect(rest);
+        if (sub === "status")
+            return await status();
+        if (sub === "disconnect")
+            return await disconnect();
+    }
+    catch (error) {
+        console.error(`${styleText("red", "✗")} ${error.message}`);
+        return 1;
+    }
+    console.error("Usage: agcl gmail connect [client_secret.json] | agcl gmail status | agcl gmail disconnect");
+    return 1;
+}