agentcollar 0.1.0 → 0.2.0

package/dist/cli/mandates.js

@@ -2,6 +2,7 @@
 import { styleText } from "node:util";
 import { oneLine } from "../approval.js";
 import { readMandatesSnapshot } from "../snapshot.js";
+import { fit, termWidth } from "./format.js";
 function duration(ms) {
     const total = Math.ceil(ms / 1000);
     const h = Math.floor(total / 3600);
@@ -11,18 +12,18 @@ function duration(ms) {
 }
 // The same order as check(): the first thing that ends a mandate decides its name.
 export function mandateRow(m, now = Date.now()) {
-    let state = "активен";
+    let state = "active";
     if (m.status === "pending")
-        state = "ждёт решения";
+        state = "waiting";
     else if (m.status === "denied")
-        state = "отклонён";
+        state = "denied";
     else if (now > m.expiresAt)
-        state = "истёк";
+        state = "expired";
     else if (m.revoked)
-        state = "отозван";
+        state = "revoked";
     else if (m.used >= m.limit)
-        state = "лимит исчерпан";
-    const live = state === "активен";
+        state = "limit used up";
+    const live = state === "active";
     return {
         id: m.id,
         agent: oneLine(m.agent, 24), // agent text: control characters removed before printing
@@ -43,34 +44,58 @@ function isRunning(pid) {
         return error.code === "EPERM"; // exists, but belongs to someone else
     }
 }
-const COLUMNS = ["ID", "АГЕНТ", "ДЕЙСТВИЯ", "СТАТУС", "ОСТАЛОСЬ", "ЛИМИТ"];
+const COLUMNS = ["ID", "AGENT", "ACTIONS", "STATE", "TIME LEFT", "USED"];
+function colorState(row, text) {
+    if (row.live)
+        return styleText("green", text);
+    if (row.state === "waiting")
+        return styleText("yellow", text);
+    return text;
+}
+// A table when it fits the window, otherwise one small "card" (two lines) per mandate.
+export function formatMandates(mandates, now = Date.now(), width = termWidth()) {
+    const rows = [...mandates].sort((a, b) => b.createdAt - a.createdAt).map((m) => mandateRow(m, now));
+    const cells = (r) => [r.id, r.agent, r.actions, r.state, r.timeLeft, r.limit];
+    const widths = COLUMNS.map((title, i) => Math.max(title.length, ...rows.map((r) => cells(r)[i].length)));
+    const tableWidth = widths.reduce((sum, w) => sum + w, 0) + 2 * (widths.length - 1);
+    const dimIfEnded = (row, text) => (row.live || row.state === "waiting" ? text : styleText("dim", text));
+    if (tableWidth <= width) {
+        // pad first, color after: color codes are invisible but would break the padding
+        const lines = [styleText("dim", COLUMNS.map((title, i) => title.padEnd(widths[i])).join("  "))];
+        for (const row of rows) {
+            const line = cells(row).map((c, i) => c.padEnd(widths[i]));
+            line[3] = colorState(row, line[3]);
+            lines.push(dimIfEnded(row, line.join("  ")));
+        }
+        return lines.join("\n");
+    }
+    return rows
+        .map((row) => {
+        const time = row.timeLeft === "—" ? "" : `  ${row.timeLeft} left`;
+        const head = fit(`${row.id}  ${row.state}${time}  ${row.limit} used`, width);
+        const colored = head.replace(row.state, colorState(row, row.state));
+        return dimIfEnded(row, `${colored}\n  ${fit(`${row.agent} · ${row.actions}`, width - 2)}`);
+    })
+        .join("\n");
+}
 export async function runMandates(args) {
     if (args.length > 0) {
-        console.error(`agentcollar mandates не принимает аргументов: ${args.join(" ")}`);
+        console.error(`agcl mandates takes no arguments: ${args.join(" ")}`);
         return 1;
     }
     const snapshot = readMandatesSnapshot();
     if (snapshot === null) {
-        console.log("Брокер ещё не запускался. Запусти: agcl server");
+        console.log("The broker has not been started yet. Run: agcl server");
         return 0;
     }
     if (!isRunning(snapshot.pid)) {
-        console.log("Брокер не запущен. Мандаты живут в его памяти, поэтому после остановки их нет.");
+        console.log("The broker is not running. Mandates live in its memory, so they are gone once it stops.");
         return 0;
     }
     if (snapshot.mandates.length === 0) {
-        console.log("Мандатов пока нет.");
+        console.log("No mandates yet.");
         return 0;
     }
-    const rows = [...snapshot.mandates].sort((a, b) => b.createdAt - a.createdAt).map((m) => mandateRow(m));
-    const cells = (r) => [r.id, r.agent, r.actions, r.state, r.timeLeft, r.limit];
-    const widths = COLUMNS.map((title, i) => Math.max(title.length, ...rows.map((r) => cells(r)[i].length)));
-    // pad first, color after: color codes are invisible but would break the padding
-    console.log(styleText("dim", COLUMNS.map((title, i) => title.padEnd(widths[i])).join("  ")));
-    for (const row of rows) {
-        const line = cells(row).map((cell, i) => cell.padEnd(widths[i]));
-        line[3] = row.live ? styleText("green", line[3]) : row.state === "ждёт решения" ? styleText("yellow", line[3]) : line[3];
-        console.log(row.live || row.state === "ждёт решения" ? line.join("  ") : styleText("dim", line.join("  ")));
-    }
+    console.log(formatMandates(snapshot.mandates));
     return 0;
 }

package/dist/cli/setup.js

@@ -13,7 +13,7 @@ async function ask(question) {
         // If the input ends before an answer (Ctrl+D, closed pipe), fail loudly instead of exiting silently.
         const answer = await new Promise((resolve, reject) => {
             rl.question(question).then(resolve, reject);
-            rl.once("close", () => reject(new Error("ввод закончился, ничего не записано")));
+            rl.once("close", () => reject(new Error("input ended, nothing was written")));
         });
         return answer.trim();
     }
@@ -64,25 +64,25 @@ export async function runSetup() {
     }
 }
 async function setup() {
-    console.log("Настройка AgentCollar broker\n");
+    console.log("AgentCollar setup\n");
     // Older versions kept the data inside the code folder (broker/.env, broker/data/audit.log).
     const oldFiles = [legacyFiles.env, legacyFiles.audit].filter((file) => existsSync(file));
     if (oldFiles.length > 0) {
-        console.log(`Нашёл старые данные:\n${oldFiles.map((f) => `  ${f}`).join("\n")}`);
-        if (yes(await ask(`Перенести в ${homeDir}/ (папка доступна только тебе)? [y/N] `))) {
+        console.log(`Found data from an older version:\n${oldFiles.map((f) => `  ${f}`).join("\n")}`);
+        if (yes(await ask(`Move it to ${homeDir}/ (only you can open that folder)? [y/N] `))) {
             const moved = migrateLegacy();
-            console.log(moved.length > 0 ? `✓ Перенесено: ${moved.join(", ")}\n` : "Там уже есть свои файлы, старые оставил на месте.\n");
+            console.log(moved.length > 0 ? `✓ Moved: ${moved.join(", ")}\n` : "Files already exist there; the old ones stay where they are.\n");
         }
     }
-    if (existsSync(envFile) && !yes(await ask(`${envFile} уже есть. Перезаписать настройки Telegram? [y/N] `))) {
-        console.log("Ничего не меняю.");
+    if (existsSync(envFile) && !yes(await ask(`${envFile} already exists. Replace the Telegram settings? [y/N] `))) {
+        console.log("Nothing changed.");
         return 0;
     }
     // 1. Token
     let token = "";
     let username = "";
     while (username === "") {
-        token = await askHidden("Токен бота (от @BotFather, при вводе не виден): ");
+        token = await askHidden("Bot token (from @BotFather, hidden while you type): ");
         try {
             username = await getBotUsername(token);
         }
@@ -90,12 +90,12 @@ async function setup() {
             console.log(`✗ ${error.message}\n`);
         }
     }
-    console.log(`✓ Бот найден: @${username}\n`);
+    console.log(`✓ Bot found: @${username}\n`);
     // 2. Start with a one-time code
     const code = newStartCode();
     let offset = await skipOldUpdates(token);
-    console.log(`Открой ссылку и нажми Start:  https://t.me/${username}?start=${code}`);
-    console.log("Жду (до 5 минут)...");
+    console.log(`Open this link and press Start:  https://t.me/${username}?start=${code}`);
+    console.log("Waiting (up to 5 minutes)...");
     let user;
     const deadline = Date.now() + WAIT_MS;
     while (user === undefined && Date.now() < deadline) {
@@ -105,20 +105,20 @@ async function setup() {
     }
     await skipOldUpdates(token); // tell Telegram we handled these messages
     if (user === undefined) {
-        console.log("Время вышло. Запусти agcl setup ещё раз.");
+        console.log("Timed out. Run agcl setup again.");
         return 1;
     }
     const who = [user.firstName, user.username ? `@${user.username}` : "", `id ${user.id}`].filter(Boolean).join(", ");
-    if (!yes(await ask(`✓ Это ты? ${who} [y/N] `))) {
-        console.log("Ничего не записал. Запусти agcl setup ещё раз.");
+    if (!yes(await ask(`✓ Is this you? ${who} [y/N] `))) {
+        console.log("Nothing was written. Run agcl setup again.");
         return 1;
     }
     // 3. ~/.agentcollar/.env, readable only by you
     ensureHome();
     const existing = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
     writeEnvFile(envFile, buildEnv(existing, { TELEGRAM_BOT_TOKEN: token, TELEGRAM_USER_ID: String(user.id) }));
-    await sendText(token, user.id, "✅ Брокер настроен. Запросы мандатов будут приходить сюда.").catch(() => { });
-    console.log(`✓ Записано в ${envFile} (права 600: читать может только твой пользователь macOS)`);
-    console.log("Дальше: agcl server (или просто agcl)");
+    await sendText(token, user.id, "✅ AgentCollar is set up. Mandate requests will arrive here.").catch(() => { });
+    console.log(`✓ Saved to ${envFile} (mode 600: only your macOS user can read it)`);
+    console.log("Next: agcl server (or just agcl)");
     return 0;
 }

package/dist/cli/start.js

@@ -15,7 +15,7 @@ export async function runStart(flags) {
     // Ask only a person at a terminal; a script or pipe goes straight to the server.
     const configured = (process.env.TELEGRAM_BOT_TOKEN ?? "") !== "";
     if (!configured && process.stdin.isTTY) {
-        const answer = await ask("Telegram ещё не настроен. Настроить сейчас? [Y/n] (n — одобрять запросы в этом терминале) ");
+        const answer = await ask("Telegram is not set up yet. Set it up now? [Y/n] (n = approve requests in this terminal) ");
         if (answer === "" || answer === "y") {
             const code = await (await import("./setup.js")).runSetup();
             if (code !== 0)

package/dist/cli/watch.js

@@ -4,7 +4,7 @@ import { mkdirSync, watch } from "node:fs";
 import { basename, dirname } from "node:path";
 import { styleText } from "node:util";
 import { auditLogFile } from "../audit.js";
-import { formatEntry, isToday } from "./format.js";
+import { fit, formatEntry, isToday, termWidth } from "./format.js";
 import { createTail } from "./tail.js";
 const RECENT = 10; // how many past events to show first, for context
 function print(entry) {
@@ -12,18 +12,21 @@ function print(entry) {
 }
 export async function runWatch(args) {
     if (args.length > 0) {
-        console.error(`agentcollar watch не принимает аргументов: ${args.join(" ")}`);
+        console.error(`agcl watch takes no arguments: ${args.join(" ")}`);
         return 1;
     }
-    console.log(`${styleText("bold", "AgentCollar · watch")}   ${styleText("dim", "Ctrl+C — выход")}`);
-    console.log(styleText("dim", "проверки: 1 токен · 2 одобрен · 3 срок · 4 не отозван · 5 действие · 6 лимит"));
+    console.log(`${styleText("bold", "AgentCollar · watch")}   ${styleText("dim", "Ctrl+C to quit")}`);
+    const legend = termWidth() >= 90
+        ? "checks: 1 token · 2 approved · 3 not expired · 4 not revoked · 5 action allowed · 6 limit"
+        : "✓✗· = checks: token, approved, time, revoked, action, limit";
+    console.log(styleText("dim", fit(legend, termWidth())));
     const tail = createTail(auditLogFile);
     const past = tail.readNew().slice(-RECENT);
     if (past.length > 0) {
-        console.log(styleText("dim", "— последние события —"));
+        console.log(styleText("dim", "— recent —"));
         past.forEach(print);
     }
-    console.log(styleText("dim", "— дальше в реальном времени —"));
+    console.log(styleText("dim", "— live —"));
     // Watch the FOLDER, not the file: it also works before the log exists, and after it is replaced.
     const folder = dirname(auditLogFile);
     mkdirSync(folder, { recursive: true });

package/dist/env.js

@@ -9,5 +9,5 @@ else if (process.env.AGENTCOLLAR_HOME === undefined && existsSync(legacyFiles.en
     // Older setups kept it in broker/.env. Still works; `agcl setup` offers to move it.
     // (Not when AGENTCOLLAR_HOME is set: an explicit home means "look only there".)
     process.loadEnvFile(legacyFiles.env);
-    console.error("AgentCollar: настройки ещё в broker/.env — запусти agcl setup, чтобы перенести их в ~/.agentcollar/");
+    console.error("AgentCollar: settings are still in broker/.env, run agcl setup to move them to ~/.agentcollar/");
 }

package/dist/gmail-fake.js

@@ -1,27 +1,26 @@
-// A pretend Gmail that lives in memory. Phase 4 replaces it with the real Gmail API.
-// The broker talks to it exactly like it will talk to the real one:
-// only AFTER check() has said yes.
+// A pretend mailbox in memory: the broker uses it until you run `agcl gmail connect`.
 import { randomBytes } from "node:crypto";
-const inbox = [
-    { id: "m1", from: "anna@example.com", subject: "Lunch on Friday?", body: "Are you free at 13:00?" },
-    { id: "m2", from: "bank@example.com", subject: "Your statement", body: "Your October statement is ready." },
-    { id: "m3", from: "boss@example.com", subject: "Report", body: "Please send the report by Monday." },
-];
-const drafts = [];
-const sent = [];
-function newId() {
-    return randomBytes(4).toString("hex");
-}
-export function listInbox() {
-    return inbox;
-}
-export function createDraft(to, subject, body) {
-    const draft = { id: newId(), to, subject, body };
-    drafts.push(draft);
-    return draft;
-}
-export function sendEmail(to, subject, body) {
-    const email = { id: newId(), to, subject, body };
-    sent.push(email);
-    return email;
+const newId = () => randomBytes(4).toString("hex");
+export function createFakeMailbox() {
+    const inbox = [
+        { id: "m1", from: "anna@example.com", subject: "Lunch on Friday?", body: "Are you free at 13:00?" },
+        { id: "m2", from: "bank@example.com", subject: "Your statement", body: "Your October statement is ready." },
+        { id: "m3", from: "boss@example.com", subject: "Report", body: "Please send the report by Monday." },
+    ];
+    const drafts = [];
+    const sent = [];
+    return {
+        kind: "fake",
+        listInbox: async () => inbox,
+        async createDraft(to, subject, body) {
+            const draft = { id: newId(), to, subject, body };
+            drafts.push(draft);
+            return draft;
+        },
+        async sendEmail(to, subject, body) {
+            const email = { id: newId(), to, subject, body };
+            sent.push(email);
+            return email;
+        },
+    };
 }

package/dist/google/connection.js

@@ -0,0 +1,36 @@
+// Which mailbox the broker uses: your real Gmail if `agcl gmail connect` was done, otherwise the fake one.
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createFakeMailbox } from "../gmail-fake.js";
+import { ensureHome, gmailInfoFile, googleClientFile } from "../paths.js";
+import { createGmailMailbox } from "./gmail.js";
+import { keychain } from "./keychain.js";
+import { parseClientJson } from "./oauth.js";
+export const REFRESH_TOKEN_ACCOUNT = "gmail-refresh-token";
+export function readGmailInfo() {
+    if (!existsSync(gmailInfoFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(gmailInfoFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConnection(info, refreshToken, store = keychain) {
+    ensureHome();
+    store.set(REFRESH_TOKEN_ACCOUNT, refreshToken); // the secret goes to the Keychain…
+    writeFileSync(gmailInfoFile, JSON.stringify(info, null, 2), { mode: 0o600 }); // …the file has only the address
+}
+export function forgetConnection(store = keychain) {
+    const token = store.get(REFRESH_TOKEN_ACCOUNT);
+    store.remove(REFRESH_TOKEN_ACCOUNT);
+    if (existsSync(gmailInfoFile))
+        unlinkSync(gmailInfoFile);
+    return token;
+}
+export function loadMailbox(store = keychain) {
+    const refreshToken = store.get(REFRESH_TOKEN_ACCOUNT);
+    if (refreshToken === null || !existsSync(googleClientFile))
+        return createFakeMailbox();
+    return createGmailMailbox(parseClientJson(readFileSync(googleClientFile, "utf8")), refreshToken);
+}

package/dist/google/gmail.js

@@ -0,0 +1,73 @@
+// Your real Gmail, through the Gmail API. Same shape as the fake mailbox, so the broker does not care
+// which one it talks to. The broker calls these ONLY after check() said yes.
+import { isEmailAddress } from "../mailbox.js";
+import { refreshAccessToken } from "./oauth.js";
+const API = "https://gmail.googleapis.com/gmail/v1/users/me";
+// Builds the email in the format Gmail expects ("raw" = base64url of the whole message).
+// The subject comes from an agent, so line breaks are removed: otherwise "Hi\r\nBcc: thief@evil"
+// would add a hidden recipient (header injection).
+export function buildRawEmail(to, subject, body) {
+    if (!isEmailAddress(to))
+        throw new Error(`"to" must be one email address, got: ${JSON.stringify(to)}`);
+    const cleanSubject = subject.replace(/[\r\n]+/g, " ").trim();
+    // non-ASCII subjects are encoded (RFC 2047) so every mail client shows them correctly
+    const encodedSubject = /^[\x20-\x7e]*$/.test(cleanSubject)
+        ? cleanSubject
+        : `=?UTF-8?B?${Buffer.from(cleanSubject, "utf8").toString("base64")}?=`;
+    const message = [
+        `To: ${to}`,
+        `Subject: ${encodedSubject}`,
+        "MIME-Version: 1.0",
+        'Content-Type: text/plain; charset="UTF-8"',
+        "Content-Transfer-Encoding: base64",
+        "",
+        Buffer.from(body, "utf8").toString("base64"),
+    ].join("\r\n");
+    return Buffer.from(message, "utf8").toString("base64url");
+}
+export function createGmailMailbox(client, refreshToken) {
+    // The access token lives only in this process's memory, never on disk.
+    let accessToken = "";
+    let expiresAt = 0;
+    async function token() {
+        if (Date.now() > expiresAt - 60_000) {
+            const fresh = await refreshAccessToken(client, refreshToken);
+            accessToken = fresh.accessToken;
+            expiresAt = fresh.expiresAt;
+        }
+        return accessToken;
+    }
+    async function api(method, path, body) {
+        const response = await fetch(API + path, {
+            method,
+            headers: { authorization: `Bearer ${await token()}`, "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = (await response.json());
+        if (!response.ok)
+            throw new Error(`Gmail API: ${data.error?.message ?? response.status}`);
+        return data;
+    }
+    return {
+        kind: "gmail",
+        async listInbox() {
+            const list = await api("GET", "/messages?labelIds=INBOX&maxResults=10");
+            const ids = (list.messages ?? []).map((m) => m.id);
+            return Promise.all(ids.map(async (id) => {
+                const m = await api("GET", `/messages/${id}?format=metadata&metadataHeaders=From&metadataHeaders=Subject`);
+                const headers = m.payload?.headers ?? [];
+                const header = (name) => headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+                return { id, from: header("From"), subject: header("Subject"), body: String(m.snippet ?? "") };
+            }));
+        },
+        async createDraft(to, subject, body) {
+            const draft = await api("POST", "/drafts", { message: { raw: buildRawEmail(to, subject, body) } });
+            return { id: String(draft.id), to, subject, body };
+        },
+        // AgentCollar asks Google only for read + create drafts, so this connection cannot send.
+        // Even a mandate with gmail.send ends here: the email stays a draft for you to send yourself.
+        async sendEmail() {
+            throw new Error("This Gmail connection cannot send: AgentCollar only has read + create-drafts access. Create a draft instead; the human sends it.");
+        },
+    };
+}

package/dist/google/keychain.js

@@ -0,0 +1,40 @@
+// Secrets in the macOS Keychain (encrypted by macOS, outside the repo and outside ~/.agentcollar/),
+// through the built-in `security` tool. Used for the Gmail refresh token.
+// Honest limit: other programs running as YOUR macOS user can also ask `security` for it.
+// The Keychain protects against leaks through files, backups and git, not against malware you run.
+import { execFileSync } from "node:child_process";
+const SERVICE = "agentcollar";
+export const keychain = {
+    get(account) {
+        try {
+            return execFileSync("security", ["find-generic-password", "-s", SERVICE, "-a", account, "-w"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trimEnd();
+        }
+        catch {
+            return null; // not there (or not macOS)
+        }
+    },
+    set(account, value) {
+        // -U: update if it already exists
+        execFileSync("security", ["add-generic-password", "-U", "-s", SERVICE, "-a", account, "-w", value], { stdio: "ignore" });
+    },
+    remove(account) {
+        try {
+            execFileSync("security", ["delete-generic-password", "-s", SERVICE, "-a", account], { stdio: "ignore" });
+        }
+        catch {
+            // already gone
+        }
+    },
+};
+// For tests: the same interface, kept in memory.
+export function memoryStore() {
+    const values = new Map();
+    return {
+        get: (account) => values.get(account) ?? null,
+        set: (account, value) => void values.set(account, value),
+        remove: (account) => void values.delete(account),
+    };
+}

package/dist/google/oauth.js

@@ -0,0 +1,134 @@
+// Google sign-in for a desktop program (OAuth 2.0 "installed app" flow with PKCE):
+// we open Google's consent page in your browser, Google sends the browser back to a tiny
+// server on 127.0.0.1 with a one-time code, and we swap that code for tokens.
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+// Read + create drafts, nothing more. gmail.drafts.create cannot send: so sending is blocked twice,
+// by the broker (no mandate, no send) AND by Google (this connection has no right to send at all).
+export const SCOPES = ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.drafts.create"];
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+// The JSON file you download from Google Cloud → Clients → Desktop app.
+export function parseClientJson(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error("This is not a Google client_secret JSON file.");
+    }
+    if (data.web !== undefined)
+        throw new Error("This client is a Web app. Create a client of type Desktop app instead.");
+    const installed = data.installed;
+    if (typeof installed?.client_id !== "string" || typeof installed.client_secret !== "string") {
+        throw new Error("This is not a Google client_secret JSON file (no installed.client_id).");
+    }
+    return { clientId: installed.client_id, clientSecret: installed.client_secret };
+}
+// PKCE: we keep a random secret (verifier) and send Google only its hash (challenge).
+// A stolen code is useless without the verifier, which never leaves this process.
+export function newPkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+export function buildAuthUrl(client, redirectUri, challenge, state) {
+    const url = new URL(AUTH_URL);
+    url.search = new URLSearchParams({
+        client_id: client.clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        scope: SCOPES.join(" "),
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state, // a random value: proves the answer belongs to OUR request
+        access_type: "offline", // we want a refresh token
+        prompt: "consent", // always show what is being granted (and always return a refresh token)
+    }).toString();
+    return url.toString();
+}
+async function postToken(params) {
+    const response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+    });
+    const data = (await response.json());
+    if (!response.ok) {
+        if (data.error === "invalid_grant") {
+            throw new Error("Google no longer accepts this sign-in (in Testing mode it expires after 7 days). Run: agcl gmail connect");
+        }
+        throw new Error(`Google sign-in failed: ${String(data.error_description ?? data.error ?? response.status)}`);
+    }
+    return data;
+}
+export async function exchangeCode(client, code, verifier, redirectUri) {
+    const data = await postToken({
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        code,
+        code_verifier: verifier,
+        redirect_uri: redirectUri,
+        grant_type: "authorization_code",
+    });
+    if (typeof data.refresh_token !== "string")
+        throw new Error("Google did not return a refresh token. Run agcl gmail connect again.");
+    return {
+        accessToken: String(data.access_token),
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000,
+    };
+}
+// The access token lives about an hour and only in memory; the refresh token gets a new one.
+export async function refreshAccessToken(client, refreshToken) {
+    const data = await postToken({
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        refresh_token: refreshToken,
+        grant_type: "refresh_token",
+    });
+    return { accessToken: String(data.access_token), expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000 };
+}
+export async function revokeToken(token) {
+    await fetch(`https://oauth2.googleapis.com/revoke?token=${encodeURIComponent(token)}`, { method: "POST" }).catch(() => { });
+}
+// Starts the loopback server, opens the consent page, waits (up to 5 minutes) for Google's redirect.
+export function authorizeInBrowser(client, openUrl, timeoutMs = 5 * 60 * 1000) {
+    const { verifier, challenge } = newPkce();
+    const state = randomBytes(16).toString("hex");
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            if (url.searchParams.get("state") !== state) {
+                res.writeHead(400, { "content-type": "text/plain" }).end("This sign-in answer does not belong to AgentCollar's request.");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (code === null) {
+                res.writeHead(400, { "content-type": "text/plain" }).end(`Google sign-in was cancelled: ${url.searchParams.get("error") ?? "no code"}`);
+                finish(() => reject(new Error("Google sign-in was cancelled.")));
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end("<!doctype html><title>AgentCollar</title><body style=\"font-family:system-ui;padding:3rem\">" +
+                "<h1>AgentCollar is connected to Gmail.</h1><p>You can close this tab and go back to the terminal.</p>");
+            finish(() => resolve({ code, verifier, redirectUri }));
+        });
+        let redirectUri = "";
+        const timer = setTimeout(() => finish(() => reject(new Error("No answer from Google in 5 minutes."))), timeoutMs);
+        function finish(then) {
+            clearTimeout(timer);
+            server.close();
+            then();
+        }
+        // port 0 = any free port; 127.0.0.1 = reachable only from this computer
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            redirectUri = `http://127.0.0.1:${port}/callback`;
+            openUrl(buildAuthUrl(client, redirectUri, challenge, state));
+        });
+    });
+}

package/dist/mailbox.js

@@ -0,0 +1,4 @@
+// One plain address: no commas (several recipients), no spaces or line breaks (header injection).
+export function isEmailAddress(text) {
+    return /^[^\s@<>,;"()]+@[^\s@<>,;"()]+\.[^\s@<>,;"()]+$/.test(text);
+}

package/dist/mcp/protocol.js

@@ -5,7 +5,8 @@
 export const SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 const SERVER_INFO = { name: "agentcollar", version: "0.1.0" };
 const INSTRUCTIONS = "AgentCollar guards the human's accounts. First call request_mandate with only the actions you need; " +
-    "the human approves it in Telegram. Poll mandate_status until it is approved, then pass the mandateId " +
+    "the human approves it in Telegram. Then call mandate_status once with waitSeconds: 90 (it returns as soon " +
+    "as the human decides) and, if approved, pass the mandateId " +
     "to the gmail_* tools. Refusals are final: explain them to the human instead of retrying.";
 function reply(id, result) {
     return JSON.stringify({ jsonrpc: "2.0", id, result });