agentcollar 0.1.0 → 0.2.0

package/README.md

@@ -5,7 +5,8 @@ agents and your accounts. Agents get a short-lived, task-scoped *mandate* that y
 Telegram — never your password or tokens.
 
 > **Hobby project. Use at your own risk. Do not connect accounts you can't afford to lose.**
-> Status: early. Gmail is still **fake** (an in-memory inbox); real Gmail is next.
+> **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
 

package/dist/approval.js

@@ -24,7 +24,7 @@ export function denyStalePending(maxAgeMs, now = Date.now()) {
     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 "Действия: gmail.read" with line breaks, or hide text with
+// 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
@@ -39,9 +39,9 @@ export function oneLine(text, max) {
 export function describe(mandate) {
     const lines = [];
     if (mandate.allowedActions.some((action) => action.endsWith(".send"))) {
-        lines.push("⚠️ Агент просит право ОТПРАВЛЯТЬ от твоего имени");
+        lines.push("⚠️ The agent asks for the right to SEND in your name");
     }
-    lines.push(`Действия: ${mandate.allowedActions.join(", ")}`, `Срок: ${mandate.expiresInSeconds} с после одобрения, лимит ${mandate.limit}`, `id: ${mandate.id}`, `Агент: ${oneLine(mandate.agent, 64)}`, `Задача (слова агента): «${oneLine(mandate.task, 200)}»`);
+    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,
@@ -50,7 +50,7 @@ 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(`\nНовый запрос мандата:\n${describe(mandate)}\nОдобрить? [y/N] `);
+        const answer = await rl.question(`\nNew mandate request:\n${describe(mandate)}\nApprove? [y/N] `);
         rl.close();
         console.log(applyTerminalAnswer(mandate, answer));
     });
@@ -61,7 +61,7 @@ export function askInTerminal(mandate) {
 export function applyTerminalAnswer(mandate, answer) {
     const decision = answer.trim().toLowerCase() === "y" ? "approve" : "deny";
     if (decide(mandate.id, decision, "terminal") === undefined) {
-        return "  ⌛ уже решено (время вышло или ответили в Telegram), ответ не применён";
+        return "  ⌛ already decided (timed out or answered in Telegram), your answer was not applied";
     }
-    return decision === "approve" ? "  ✅ одобрен" : "  ❌ отклонён";
+    return decision === "approve" ? "  ✅ approved" : "  ❌ denied";
 }

package/dist/cli/format.js

@@ -22,18 +22,65 @@ export function localTime(iso, showDate) {
     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 time = styleText("dim", localTime(entry.time, options.showDate));
-    const agent = oneLine(entry.agent, 24).padEnd(16);
-    const action = oneLine(entry.action, 32);
-    const reason = styleText("dim", oneLine(entry.reason, 120));
-    if (entry.action.startsWith("mandate.")) {
-        // a human decision (approve / deny / revoke) or the relay fallback: one yellow line
-        return `${time}  ${styleText("yellow", `${agent}  ${action.padEnd(18)}  ${oneLine(entry.reason, 120)}`)}`;
-    }
+    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 marks = checkMarks(entry).padEnd(11);
-    return `${time}  ${agent}  ${action.padEnd(18)}  ${verdict}  ${marks}  ${reason}`;
+    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;
+}

package/dist/cli/intro-frames.js

@@ -15,6 +15,21 @@ export const SPIN = [
     ["", "       ⢀⣠⣤⣴⣶⣖⣲⣦⣤⣀", "     ⣠⣾⣿⣿⣿⣿⠿⠿⣿⣿⣿⣿⣿⣦⣄", "   ⢠⣾⣿⣿⣿⣿⣿⠃⢠⣤⣿⣿⣿⡿⢿⣿⣿⣆", "   ⣾⣿⣿⣿⣿⣿⣿⣇ ⠙⢿⣿⣿⡆ ⣿⣿⣽⡄", "  ⢸⣿⣿⣿⡿⠿⢿⣿⣿⣷⣄⣀⠈⠉ ⣠⣿⣿⣿⡇", "  ⢸⣼⣿⣿⣇ ⢀⣀⡀⠈⠉⠙⠛⠻⣿⣿⣿⣿⣿⡇", "  ⠈⣿⣿⣿⣿⣧⡀⠙⠃⢀⣶⣶⣶⣶⣿⣿⣿⣿⣿⠁", "   ⠘⢿⣏⢿⣿⣿⣆ ⠘⢿⣿⣿⣿⣿⣿⢟⡿⠁", "     ⠻⢷⣿⣿⣿⣷⣄⢀⣿⣿⣿⣿⣷⠟⠁", "       ⠉⠛⠻⠿⠿⠿⠿⠿⠛⠉", ""],
     ["", "       ⣀⣠⣴⣶⣶⣶⣶⣤⣄⡀", "     ⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄", "   ⢀⢾⣿⣿⣿⣿⣿⣿⣿⡟⠁⣀⢉⣿⣿⣿⣷⡄", "  ⢀⣿⣾⣿⣿⠛⢿⣿⣿⣿⡆ ⣿⣿⣿⣿⣿⣿⣿⡄", "  ⢸⣿⣿⣿⣧ ⣄⠈⠻⣿⣇ ⠹⣿⣿⡏⠉⣿⣿⣿", "  ⢸⣿⢻⣿⣿ ⢸⠷  ⠙⢷⣀⠈⠉⢀⣼⣿⡟⡿", "   ⣿⣼⣿⣿⡇ ⢠⣴⣷⣄ ⢻⣿⣿⣿⣿⣿⣿⠃", "   ⠘⢿⣿⣿⣷ ⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃", "    ⠈⠻⣿⣿⣤⣼⣿⣿⣿⣿⣿⢿⣿⡿⠛⠁", "       ⠉⠛⠿⠿⠿⠿⠷⠞⠛⠁", ""],
 ];
+// The same, 32×32 dots (16 columns × 8 rows), for narrow terminal windows.
+export const SPIN_SMALL = [
+    ["       ⢀⡀", "   ⢀⣴⣾⣿⣿⣿⣿⣷⣦⡀", "  ⣴⣿⣿⡟⠻⣿⣿⡿⠟⢿⣿⣆", " ⢠⣿⣿⡟⢠⡆⢹⡿ ⣶⣶⣿⣿⡄", " ⠘⣿⣿⠁⣠⣤ ⢧ ⠿⠟⣿⣿⡇", "  ⠹⣧⣴⣿⣿⣧⣼⣷⣤⣶⣿⡟", "   ⠙⠿⢿⣿⣿⣿⣿⣿⠟⠋", "       ⠉⠉"],
+    ["       ⣀⣀", "   ⢀⡴⣾⣿⣷⣿⣿⣷⣦⡀", "  ⣰⣿⣿⡿⠋⠉⣿⣿⣿⣿⣿⣆", " ⢰⣿⠟⠉⡀⠛ ⣿⠟⠛⠛⢿⣿⡀", " ⠸⣿⣶⣾⣿⠇⢸⠃⣰⣿⣷⣾⣿⠅", "  ⠻⣿⣿⣿⣶⣿⡀⠙⢛⣿⣿⡏", "   ⠉⠻⢿⣿⣿⣿⣿⣿⠿⠋", "       ⠉⠉⠁"],
+    ["       ⣀⣀", "   ⣀⣴⣿⣿⣽⣿⣿⣷⣦⡀", "  ⣴⡿⠟⠛⠛⣉⡉⢙⣿⣿⣿⣆", " ⢰⣿⣷⣶⣷⡄⠉⣰⣿⣿⣿⣿⣿⡀", " ⠸⣿⣿⣿⡋⣠⠞⢉⣀⣈⠙⣿⣿⠁", "  ⠹⣿⣿⣿⣇⠐⠿⣿⣷⣾⣿⠏", "   ⠈⠻⣿⣿⣷⣶⣿⣿⠟⠉", "      ⠈⠉⠉⠉"],
+    ["       ⣀⣀", "   ⣠⣴⠾⣿⣿⣿⣿⣿⣦⡀", "  ⣸⣿⣿⣦⣄⠈⣉⠛⠿⣿⣿⣆", " ⢠⣿⣿⣿⠿⠛ ⣉⣡⣴⣿⣿⣿⡀", " ⠘⣿⣿⣿⡶⠚⠉⠙⠛⢿⣿⣿⣿⠁", "  ⠻⣿⣿⡄⠸⣿⣿⡇⣨⣿⣿⠏", "   ⠙⠿⣿⣿⣿⣿⣿⡿⠟⠁", "      ⠉⠉⠉"],
+    ["      ⢀⣀⣀⡀", "   ⢠⣴⣿⣿⡟⠻⣿⣷⣦⡀", "  ⣰⣿⣿⣿⣿⣷⠄⠘⢿⣿⣽⣆", " ⢠⣿⣿⣿⣧⣈⣉ ⠛ ⢹⣿⡿⡄", " ⠸⣿⣿⠁⣠⣄⡉⠻⣿⣿⣿⣿⣿⠃", "  ⢻⣿⣦⣿⣿⡿ ⣿⣿⣿⣿⠏", "   ⠙⠿⢿⣿⣷⣾⣿⡿⠟⠁", "      ⠈⠈⠁"],
+    ["      ⢀⣀⣀⡀", "   ⢀⣴⣾⣿⣿⣿⡿⢿⣦⡄", "  ⣴⣿⣿⣿⠟⢿⣿⡧⠈⣿⣿⣦", " ⢰⣿⡿⠋⡉⠳⣄⠉⢠⡄⢻⣿⣻⡄", " ⢸⣿⣧⣼⣿⡆⠘⣷⣦⡁⣸⣿⣿⠃", "  ⠻⣿⣿⣏⠃⣰⣿⣿⣿⣿⣿⠏", "   ⠘⠻⢿⣿⣿⣿⣿⡿⠟⠁", "       ⠈⠁"],
+    ["       ⣀⣀", "   ⣠⣴⣿⣿⣿⣿⣿⣷⣶⣄", "  ⣼⣿⠿⠛⢿⡟⢻⣿⣿⠟⢻⣆", " ⢸⣿⣿⣴⣶ ⢳ ⠛⠋⢀⣿⣿⡄", " ⠘⣿⣿⠿⠿ ⣾⣇⠸⠃⣼⣿⣿⠃", "  ⠹⣿⣷⣴⣾⣿⣿⣦⣼⣿⣿⠟", "   ⠈⠻⢿⣿⣿⣿⣿⡿⠟⠁", "       ⠈⠁"],
+    ["      ⢀⣀⣀", "   ⣠⣶⣿⣿⣿⣿⣿⣷⣦⣀", "  ⣸⣿⣿⣥⣄⠈⣿⠿⣿⣿⣿⣦", " ⢐⣿⡿⢿⣿⠏⢠⡇⢰⣿⡿⠿⣿⡆", " ⠈⣿⣷⣤⣤⣴⣿ ⣤⠈⣀⣴⣿⠇", "  ⠹⣿⣿⣿⣿⣿⣀⣠⣾⣿⣿⠏", "   ⠈⠻⢿⣿⣿⢿⣿⡿⠞⠁", "       ⠉⠉"],
+    ["      ⣀⣀⣀⡀", "   ⣀⣴⣿⣿⠿⢿⣿⣿⣦⡀", "  ⣰⣿⡿⢿⣿⣶⠄⢹⣿⣿⣿⣆", " ⢀⣿⣿⣄⡉⠉⣁⡴⠋⣨⣿⣿⣿⡆", " ⠈⣿⣿⣿⣿⣿⠏⣀⠘⢿⠿⢿⣿⠇", "  ⠹⣿⣿⣿⣅⣈⣉⣤⣤⣴⣾⠟", "   ⠈⠻⢿⣿⣿⣟⣿⣿⠟⠉", "       ⠉⠉"],
+    ["       ⣀⣀⣀", "   ⢀⣴⣾⣿⣿⣿⣿⣿⣶⣄", "  ⣰⣿⣿⡋⢸⣿⣿⡆⠘⣿⣿⣦", " ⢀⣿⣿⣿⣷⣤⣄⣀⡤⠾⣿⣿⣿⡄", " ⠈⣿⣿⣿⠟⢋⣉ ⣤⣶⣿⣿⣿⠃", "  ⠹⣿⣿⣶⣤⣉⡀⠙⠻⣿⣿⡏", "   ⠈⠻⣿⣿⣿⣿⣿⡶⠟⠋", "       ⠉⠉"],
+    ["       ⢀⡀⡀", "   ⢀⣴⣾⣿⡿⢿⣿⣷⣶⣄", "  ⣰⣿⣿⣿⣿ ⣾⣿⣿⠻⣿⣧", " ⢠⣿⣿⣿⣿⣿⣦⣈⠙⠋⢀⣿⣿⡆", " ⠘⣾⣿⣇ ⣤ ⣉⡉⢻⣿⣿⣿⠃", "  ⠹⣟⣿⣷⡄⠐⢿⣿⣿⣿⣿⠏", "   ⠈⠻⢿⣿⣦⣼⣿⣿⠟⠃", "      ⠈⠉⠉⠁"],
+    ["       ⢀⡀", "   ⢀⣴⣾⣿⣿⣿⣿⣷⣦⡄", "  ⣰⣿⣿⣿⣿⣿⠏⢠⣹⣿⣿⣦", " ⢠⣿⣿⡏⢈⠻⢿⡄⠸⣿⡟⢻⣿⡇", " ⠘⣯⣿⣧⠘⠃⣀⠙⢦⣈⣠⣾⣿⠇", "  ⠻⣿⣿⡀⢺⣿⣷⣴⣿⣿⣿⠟", "   ⠘⠻⣷⣾⣿⣿⣿⡿⠟⠁", "      ⠈⠉⠉⠁"],
+];
 // Upright and smaller (32, 20, 12 dots): the medallion "flies" into the header.
 export const SHRINK = [
     ["       ⢀⡀", "   ⢀⣴⣾⣿⣿⣿⣿⣷⣦⡀", "  ⣴⣿⣿⡟⠻⣿⣿⡿⠟⢿⣿⣆", " ⢠⣿⣿⡟⢠⡆⢹⡿ ⣶⣶⣿⣿⡄", " ⠘⣿⣿⠁⣠⣤ ⢧ ⠿⠟⣿⣿⡇", "  ⠹⣧⣴⣿⣿⣧⣼⣷⣤⣶⣿⡟", "   ⠙⠿⢿⣿⣿⣿⣿⣿⠟⠋", "       ⠉⠉"],

package/dist/cli/intro.js

@@ -2,24 +2,34 @@
 // and un-types, then the medallion shrinks into the header. About 1.7 s; any key skips it.
 // The frames are plain text made once from the logo (see tools/gen-intro.ts).
 import { styleText } from "node:util";
-import { ICON, SHRINK, SPIN } from "./intro-frames.js";
+import { ICON, SHRINK, SPIN, SPIN_SMALL } from "./intro-frames.js";
 const WORD = "AgentCollar";
 const WELCOME = "Welcome. Let agents work. Keep the keys.";
-const HEIGHT = SPIN[0].length; // every frame has this many lines, so each one overwrites the last
-const WORD_ROW = Math.floor(HEIGHT / 2) - 1;
-const WORD_COLUMN = 28;
-function frame(medallion, word = "", delayMs = 0) {
-    const lines = Array.from({ length: HEIGHT }, (_, row) => {
-        const left = medallion[row] ?? "";
-        return row === WORD_ROW && word !== "" ? left.padEnd(WORD_COLUMN) + word : left;
-    });
-    return { lines, delayMs };
+const WELCOME_SHORT = "Let agents work. Keep the keys.";
+// The big medallion needs 60×16, the small one 44×12; a smaller window gets no intro at all.
+export function introSize(columns, rows) {
+    if (columns >= 60 && rows >= SPIN[0].length + 4)
+        return "big";
+    if (columns >= 44 && rows >= SPIN_SMALL[0].length + 4)
+        return "small";
+    return "none";
 }
 // The whole animation as data: easy to test (duration, sizes) and to play.
-export function introTimeline() {
-    const upright = SPIN[0];
+export function introTimeline(size = "big", width = 100) {
+    const spin = size === "big" ? SPIN : SPIN_SMALL;
+    const height = spin[0].length; // every frame has this many lines, so each one overwrites the last
+    const wordRow = Math.floor(height / 2) - 1;
+    const wordColumn = Math.max(...spin[0].map((line) => [...line].length)) + 3;
+    const frame = (medallion, word = "", delayMs = 0) => ({
+        lines: Array.from({ length: height }, (_, row) => {
+            const left = medallion[row] ?? "";
+            return row === wordRow && word !== "" ? left.padEnd(wordColumn) + word : left;
+        }),
+        delayMs,
+    });
+    const upright = spin[0];
     const frames = [];
-    for (const turned of SPIN)
+    for (const turned of spin)
         frames.push(frame(turned, "", 40)); // one full turn
     frames.push(frame(upright, "", 40)); // settles upright
     for (let i = 1; i <= WORD.length; i++)
@@ -27,9 +37,11 @@ export function introTimeline() {
     frames[frames.length - 1].delayMs = 250; // holds the full name
     for (let i = WORD.length - 1; i >= 0; i--)
         frames.push(frame(upright, WORD.slice(0, i), 22)); // un-types
-    for (const smaller of SHRINK)
+    const shrink = size === "big" ? SHRINK : SHRINK.slice(1); // the small intro starts at 32 dots already
+    for (const smaller of shrink)
         frames.push(frame(smaller, "", 60)); // flies into the header
-    frames.push(frame([`${ICON[0]}  ${styleText("bold", WORD)}`, `${ICON[1]}  ${WELCOME}`]));
+    const welcome = width >= WELCOME.length + 6 ? WELCOME : WELCOME_SHORT;
+    frames.push(frame([`${ICON[0]}  ${styleText("bold", WORD)}`, `${ICON[1]}  ${welcome}`]));
     return frames;
 }
 // Only for a person looking at a real terminal: never in pipes, logs, CI, or when asked not to.
@@ -40,7 +52,7 @@ export function shouldShowIntro(c) {
         return false;
     if (c.env.NO_COLOR !== undefined && c.env.NO_COLOR !== "")
         return false; // no-color.org rule
-    return c.columns >= 72 && c.rows >= HEIGHT + 4;
+    return introSize(c.columns, c.rows) !== "none";
 }
 // ANSI escape codes used below:
 //   ESC[?25l / ESC[?25h  hide / show the cursor
@@ -50,7 +62,11 @@ export function shouldShowIntro(c) {
 //   ESC[<n>A             move the cursor n lines up
 const ESC = "\u001b";
 export async function playIntro(out = process.stdout, input = process.stdin) {
-    const frames = introTimeline();
+    const size = introSize(out.columns ?? 100, out.rows ?? 40);
+    if (size === "none")
+        return;
+    const frames = introTimeline(size, out.columns ?? 100);
+    const HEIGHT = frames[0].lines.length;
     let skipped = false;
     let ctrlC = false;
     let wake = () => { };

package/dist/cli/logs.js

@@ -13,11 +13,11 @@ export function parseLogsArgs(args) {
         else if (arg === "--agent") {
             const name = args[++i];
             if (name === undefined || name.startsWith("--"))
-                throw new Error("После --agent нужно имя: --agent <имя>");
+                throw new Error("--agent needs a name: --agent <name>");
             filter.agent = name;
         }
         else
-            throw new Error(`Неизвестный флаг: ${arg}. Есть: --agent <имя>, --denied, --today`);
+            throw new Error(`Unknown flag: ${arg}. Available: --agent <name>, --denied, --today`);
     }
     return filter;
 }
@@ -37,7 +37,7 @@ export async function runLogs(args) {
     }
     const entries = filterEntries(readAuditLog(auditLogFile), filter);
     if (entries.length === 0) {
-        console.log("Записей нет.");
+        console.log("No entries.");
         return 0;
     }
     for (const entry of entries)

package/dist/cli/main.js

@@ -2,17 +2,23 @@
 // both names point to one file, so `agcl watch` == `agentcollar watch`.
 // Each command lives in its own file and is loaded only when it is used.
 import { styleText } from "node:util";
+import { fit, termWidth, wrap } from "./format.js";
 // Runs forever (until Ctrl+C): the server and the MCP server keep the process alive themselves.
 const forever = () => new Promise(() => { });
 const COMMANDS = {
     setup: {
         usage: "agcl setup",
-        summary: "подключить своего Telegram-бота (мастер настройки)",
+        summary: "connect your own Telegram bot (setup wizard)",
         run: async () => (await import("./setup.js")).runSetup(),
     },
+    gmail: {
+        usage: "agcl gmail connect|status|disconnect",
+        summary: "connect your real Gmail (read + create drafts; cannot send)",
+        run: async (args) => (await import("./gmail.js")).runGmail(args),
+    },
     server: {
         usage: "agcl server",
-        summary: "запустить брокер на 127.0.0.1",
+        summary: "start the broker on 127.0.0.1",
         run: async () => {
             await import("../server.js");
             return forever();
@@ -20,7 +26,7 @@ const COMMANDS = {
     },
     watch: {
         usage: "agcl watch",
-        summary: "живой экран: запросы агентов в реальном времени и 6 проверок",
+        summary: "live screen: agent requests as they happen, with the 6 checks",
         run: async (args, flags) => {
             await (await import("./intro.js")).maybeIntro(flags.noIntro);
             return (await import("./watch.js")).runWatch(args);
@@ -28,22 +34,22 @@ const COMMANDS = {
     },
     mandates: {
         usage: "agcl mandates",
-        summary: "мандаты запущенного брокера: статус, сколько осталось времени и действий",
+        summary: "mandates of the running broker: state, time and actions left",
         run: async (args) => (await import("./mandates.js")).runMandates(args),
     },
     logs: {
-        usage: "agcl logs [--agent <имя>] [--denied] [--today]",
-        summary: "аудит-лог: кто, что, когда, разрешено или нет",
+        usage: "agcl logs [--agent <name>] [--denied] [--today]",
+        summary: "the audit log: who, what, when, allowed or not",
         run: async (args) => (await import("./logs.js")).runLogs(args),
     },
     revoke: {
         usage: "agcl revoke <id>",
-        summary: "мгновенно отозвать мандат (kill switch)",
+        summary: "revoke a mandate instantly (kill switch)",
         run: async (args) => (await import("./revoke.js")).runRevoke(args),
     },
     mcp: {
         usage: "agcl mcp",
-        summary: "MCP-сервер для Claude Code и других агентов (stdio)",
+        summary: "MCP server for Claude Code and other agents (stdio)",
         run: async () => {
             await import("../mcp/server.js");
             return forever();
@@ -62,19 +68,23 @@ export function parseCommand(argv) {
     return { kind: "run", name, args, flags };
 }
 function helpText() {
+    const screen = termWidth();
     const width = Math.max(...Object.values(COMMANDS).map((c) => c.usage.length)) + 3;
-    const row = (left, right) => `  ${styleText("cyan", left.padEnd(width))}${right}`;
+    // wide window: "usage   summary" on one line; narrow: the summary goes under the usage
+    const row = (left, right) => screen >= width + 40
+        ? `  ${styleText("cyan", left.padEnd(width))}${fit(right, screen - width - 2)}`
+        : `  ${styleText("cyan", fit(left, screen - 2))}\n${wrap(right, screen - 6).map((line) => `      ${line}`).join("\n")}`;
     return [
-        `${styleText("bold", "AgentCollar")} — let agents work, keep the keys.`,
+        fit(`${styleText("bold", "AgentCollar")} — let agents work, keep the keys.`, screen + 20),
         "",
-        row("agcl", "заставка → мастер настройки (если ещё не настроен) → брокер"),
+        row("agcl", "intro → setup wizard (first time only) → broker"),
         ...Object.values(COMMANDS).map((c) => row(c.usage, c.summary)),
         "",
-        row("--no-intro", "без заставки"),
-        row("-h, --help", "эта справка"),
+        row("--no-intro", "skip the intro"),
+        row("-h, --help", "this help"),
         "",
-        styleText("dim", "agcl — короткое имя agentcollar: agcl watch == agentcollar watch"),
-        styleText("dim", "Данные: ~/.agentcollar/ (папка доступна только тебе)"),
+        styleText("dim", fit("agcl is the short name of agentcollar: agcl watch == agentcollar watch", screen)),
+        styleText("dim", fit("Your data: ~/.agentcollar/ (only you can open it)", screen)),
     ].join("\n");
 }
 export async function runCli(argv) {
@@ -86,7 +96,7 @@ export async function runCli(argv) {
             console.log(helpText());
             return 0;
         case "unknown":
-            console.error(`${styleText("red", `Неизвестная команда: ${parsed.name}`)}\n\n${helpText()}`);
+            console.error(`${styleText("red", `Unknown command: ${parsed.name}`)}\n\n${helpText()}`);
             return 1;
         case "run":
             return COMMANDS[parsed.name].run(parsed.args, parsed.flags);