agentcollar 0.1.0 → 0.2.0

package/dist/mcp/tools.js

@@ -1,9 +1,18 @@
+const MAX_WAIT_SECONDS = 120;
 function text(value) {
     return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
 }
 function failure(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+function isPending(result) {
+    try {
+        return JSON.parse(result.content[0]?.text ?? "{}").status === "pending";
+    }
+    catch {
+        return false;
+    }
+}
 const BROKER_DOWN = failure("The AgentCollar broker is not running. Ask the human to start it: agcl server");
 const mandateId = { type: "string", description: "The mandateId returned by request_mandate." };
 const emailFields = {
@@ -86,9 +95,35 @@ export function createTools(options) {
         },
         {
             name: "mandate_status",
-            description: "Current state of a mandate: pending / approved / denied, revoked, expiry, actions used.",
-            inputSchema: { type: "object", properties: { mandateId }, required: ["mandateId"] },
-            call: (args) => withMandate(args, "GET", "/mandate"),
+            description: "Current state of a mandate: pending / approved / denied, revoked, expiry, actions used. " +
+                "Right after request_mandate, pass waitSeconds (e.g. 90): the call returns as soon as the human " +
+                "approves or denies in Telegram, so you do not need to call it again and again.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    mandateId,
+                    waitSeconds: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: MAX_WAIT_SECONDS,
+                        description: "Wait up to this many seconds while the mandate is still pending.",
+                    },
+                },
+                required: ["mandateId"],
+            },
+            async call(args) {
+                // Long polling inside THIS process: the model makes one call, we ask the broker every
+                // 2 s until the human decides (or the time is up). The interval is ours, not the model's.
+                const waitSeconds = Math.min(Math.max(Number(args.waitSeconds) || 0, 0), MAX_WAIT_SECONDS);
+                const deadline = Date.now() + waitSeconds * 1000;
+                const every = options.pollEveryMs ?? 2000;
+                let result = await withMandate(args, "GET", "/mandate");
+                while (!result.isError && isPending(result) && Date.now() < deadline) {
+                    await new Promise((resolve) => setTimeout(resolve, Math.min(every, Math.max(deadline - Date.now(), 0))));
+                    result = await withMandate(args, "GET", "/mandate");
+                }
+                return result;
+            },
         },
         {
             name: "gmail_read_inbox",

package/dist/paths.js

@@ -9,6 +9,8 @@ export const homeDir = process.env.AGENTCOLLAR_HOME ?? join(homedir(), ".agentco
 export const envFile = join(homeDir, ".env"); // Telegram bot token + your user id
 export const auditLogFile = join(homeDir, "audit.log"); // every check and every human decision
 export const snapshotFile = join(homeDir, "mandates.json"); // for `agentcollar mandates`
+export const googleClientFile = join(homeDir, "google-client.json"); // your Google Cloud "Desktop app" client
+export const gmailInfoFile = join(homeDir, "gmail.json"); // which Gmail is connected (no secrets)
 // 700: only your macOS user can open the folder at all. chmod also fixes an existing folder.
 export function ensureHome() {
     mkdirSync(homeDir, { recursive: true, mode: 0o700 });

package/dist/revoke.js

@@ -1,18 +1,18 @@
 export async function revokeMandate(id, port) {
     // Mandate ids are 8 hex characters; anything else never reaches the network.
     if (!/^[0-9a-f]{8}$/.test(id)) {
-        return { ok: false, message: "Как использовать: agcl revoke <id>   (id мандата: 8 символов, есть в сообщении Telegram)" };
+        return { ok: false, message: "Usage: agcl revoke <id>   (the mandate id: 8 characters, shown in the Telegram message)" };
     }
     let response;
     try {
         response = await fetch(`http://127.0.0.1:${port}/mandates/${id}/revoke`, { method: "POST" });
     }
     catch {
-        return { ok: false, message: "Брокер не отвечает. Он запущен (agcl server)?" };
+        return { ok: false, message: "The broker is not answering. Is it running (agcl server)?" };
     }
     if (!response.ok) {
         const body = (await response.json());
-        return { ok: false, message: `Не получилось: ${body.error}` };
+        return { ok: false, message: `Could not revoke: ${body.error}` };
     }
-    return { ok: true, message: `🛑 Мандат ${id} отозван` };
+    return { ok: true, message: `🛑 Mandate ${id} revoked` };
 }

package/dist/server.js

@@ -5,7 +5,8 @@ import "./env.js"; // first: loads broker/.env into process.env
 import { createServer } from "node:http";
 import { askInTerminal, decide, denyStalePending, oneLine } from "./approval.js";
 import { check } from "./check.js";
-import { createDraft, listInbox, sendEmail } from "./gmail-fake.js";
+import { loadMailbox, readGmailInfo } from "./google/connection.js";
+import { isEmailAddress } from "./mailbox.js";
 import { mandates, onMandatesChanged, requestMandate } from "./mandate.js";
 import { writeMandatesSnapshot } from "./snapshot.js";
 import { notifyRevoked, notifyTimedOut, sendApprovalRequest, startTelegramPolling } from "./telegram.js";
@@ -27,6 +28,23 @@ const telegram = telegramConfig();
 // data/mandates.json for `agentcollar mandates`: fresh on start (memory is empty), then after every change.
 writeMandatesSnapshot();
 onMandatesChanged(() => writeMandatesSnapshot());
+// Your real Gmail after `agcl gmail connect`, otherwise the fake inbox.
+const mailbox = loadMailbox();
+// Reading/drafting through Gmail can fail (network, Google sign-in expired): tell the agent why, as 502.
+async function viaMailbox(action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        throw new HttpError(502, error.message);
+    }
+}
+function requireEmail(body, field) {
+    const value = requireString(body, field);
+    if (!isEmailAddress(value))
+        throw new HttpError(400, `"${field}" must be one email address`);
+    return value;
+}
 // A pending mandate nobody answered becomes "denied" after 10 minutes (fail closed).
 const PENDING_TIMEOUT_MS = 10 * 60 * 1000;
 // --- small HTTP helpers ---
@@ -185,18 +203,20 @@ async function route(req, res) {
     }
     if (method === "GET" && path === "/inbox") {
         guard(req, "gmail.read");
-        return sendJson(res, 200, { messages: listInbox() });
+        return sendJson(res, 200, { messages: await viaMailbox(() => mailbox.listInbox()) });
     }
     if (method === "POST" && path === "/drafts") {
         guard(req, "gmail.draft");
         const body = await readJson(req);
-        const draft = createDraft(requireString(body, "to"), requireString(body, "subject"), requireString(body, "body"));
+        const [to, subject, text] = [requireEmail(body, "to"), requireString(body, "subject"), requireString(body, "body")];
+        const draft = await viaMailbox(() => mailbox.createDraft(to, subject, text));
         return sendJson(res, 201, { draft }); // 201 = "created"
     }
     if (method === "POST" && path === "/send") {
         guard(req, "gmail.send");
         const body = await readJson(req);
-        const email = sendEmail(requireString(body, "to"), requireString(body, "subject"), requireString(body, "body"));
+        const [to, subject, text] = [requireEmail(body, "to"), requireString(body, "subject"), requireString(body, "body")];
+        const email = await viaMailbox(() => mailbox.sendEmail(to, subject, text));
         return sendJson(res, 200, { sent: email });
     }
     throw new HttpError(404, `no endpoint ${method} ${path}`);
@@ -217,8 +237,19 @@ const server = createServer(async (req, res) => {
         }
     }
 });
+// Port taken: most likely a broker is already running. Say so instead of a stack trace.
+server.on("error", (error) => {
+    if (error.code === "EADDRINUSE") {
+        console.error(`Port ${PORT} is already in use: is another AgentCollar broker running? (check: agcl mandates)`);
+        console.error(`Stop it, or start this one on another port: BROKER_PORT=8788 agcl server`);
+        process.exit(1);
+    }
+    throw error;
+});
 server.listen(PORT, HOST, () => {
     console.log(`Broker listening on http://${HOST}:${PORT}`);
+    const gmail = readGmailInfo();
+    console.log(mailbox.kind === "gmail" ? `Mailbox: Gmail (${gmail?.email ?? "connected"})` : "Mailbox: fake inbox (connect your Gmail: agcl gmail connect)");
     console.log(telegram ? "Approvals: Telegram" : "Approvals: this terminal (no TELEGRAM_BOT_TOKEN in .env)");
 });
 // Every 30 seconds: deny requests nobody answered, and fix their Telegram messages.

package/dist/setup.js

@@ -70,15 +70,15 @@ async function call(token, method, params) {
     if (data.ok)
         return data.result;
     if (data.error_code === 401)
-        throw new Error("Telegram не узнал этот токен. Скопируй его заново у @BotFather (/mybots → бот → API Token).");
+        throw new Error("Telegram does not know this token. Copy it again from @BotFather (/mybots → your bot → API Token).");
     if (data.error_code === 409)
-        throw new Error("Этого бота уже слушает другая программа. Останови agcl server и запусти agcl setup снова.");
+        throw new Error("Another program is already listening to this bot. Stop agcl server, then run agcl setup again.");
     throw new Error(`Telegram ${method}: ${data.description}`);
 }
 // Checks the token for real (getMe) and returns the bot's @username.
 export async function getBotUsername(token) {
     if (!isTokenFormat(token))
-        throw new Error("Это не похоже на токен бота (должно быть вида 123456789:AAH...).");
+        throw new Error("This does not look like a bot token (it looks like 123456789:AAH...).");
     const me = (await call(token, "getMe", {}));
     return me.username;
 }

package/dist/telegram.js

@@ -19,23 +19,23 @@ async function callApi(config, method, params) {
 function buttons(mandate) {
     if (mandate.status === "pending") {
         return [[
-                { text: "✅ Одобрить", callback_data: `approve:${mandate.id}` },
-                { text: "❌ Отклонить", callback_data: `deny:${mandate.id}` },
+                { text: "✅ Approve", callback_data: `approve:${mandate.id}` },
+                { text: "❌ Deny", callback_data: `deny:${mandate.id}` },
             ]];
     }
     if (mandate.status === "approved" && !mandate.revoked) {
-        return [[{ text: "🛑 Отозвать", callback_data: `revoke:${mandate.id}` }]];
+        return [[{ text: "🛑 Revoke", callback_data: `revoke:${mandate.id}` }]];
     }
     return []; // denied or revoked: nothing left to press
 }
 function statusLine(mandate) {
     if (mandate.revoked)
-        return "🛑 Отозван";
+        return "🛑 Revoked";
     if (mandate.status === "approved")
-        return "✅ Одобрен";
+        return "✅ Approved";
     if (mandate.status === "denied")
-        return "❌ Отклонён";
-    return "⏳ Ждёт решения";
+        return "❌ Denied";
+    return "⏳ Waiting for your decision";
 }
 // Which Telegram message shows which mandate, so it can be edited later (e.g. on timeout).
 const sentMessages = new Map(); // mandate id -> message
@@ -44,7 +44,7 @@ const sentMessages = new Map(); // mandate id -> message
 export async function sendApprovalRequest(config, mandate) {
     const message = (await callApi(config, "sendMessage", {
         chat_id: config.approverId, // in a private chat, chat id = user id
-        text: `🔐 Запрос мандата\n\n${describe(mandate)}\n\n${statusLine(mandate)}`,
+        text: `🔐 Mandate request\n\n${describe(mandate)}\n\n${statusLine(mandate)}`,
         reply_markup: { inline_keyboard: buttons(mandate) },
     }));
     sentMessages.set(mandate.id, { chatId: config.approverId, messageId: message.message_id });
@@ -58,17 +58,17 @@ async function closeMessage(config, mandate, finalLine) {
     await callApi(config, "editMessageText", {
         chat_id: sent.chatId,
         message_id: sent.messageId,
-        text: `🔐 Запрос мандата\n\n${describe(mandate)}\n\n${finalLine}`,
+        text: `🔐 Mandate request\n\n${describe(mandate)}\n\n${finalLine}`,
         reply_markup: { inline_keyboard: [] },
     });
 }
 // Nobody answered in time.
 export async function notifyTimedOut(config, mandate) {
-    await closeMessage(config, mandate, "⌛ Время вышло");
+    await closeMessage(config, mandate, "⌛ Timed out: no answer in 10 minutes");
 }
 // Revoked from the terminal (npm run revoke) or over HTTP.
 export async function notifyRevoked(config, mandate) {
-    await closeMessage(config, mandate, "🛑 Отозван");
+    await closeMessage(config, mandate, "🛑 Revoked");
 }
 // A button was pressed.
 async function handleButton(config, query) {
@@ -76,7 +76,7 @@ async function handleButton(config, query) {
     // Only the approver's presses count.
     if (query.from.id !== config.approverId) {
         console.log(`Telegram: ignored a button press from user ${query.from.id} (not the approver)`);
-        await callApi(config, "answerCallbackQuery", { callback_query_id: query.id, text: "Нет доступа" });
+        await callApi(config, "answerCallbackQuery", { callback_query_id: query.id, text: "No access" });
         return;
     }
     const [action, id] = (query.data ?? "").split(":");
@@ -85,14 +85,14 @@ async function handleButton(config, query) {
     // Telegram shows a spinner on the button until we answer.
     await callApi(config, "answerCallbackQuery", {
         callback_query_id: query.id,
-        text: mandate ? statusLine(mandate) : "Уже решено или мандат не найден",
+        text: mandate ? statusLine(mandate) : "Already decided, or the mandate is gone",
     });
-    // Update the message: new status line, new buttons (e.g. "Отозвать" after approval).
+    // Update the message: new status line, new buttons (e.g. "Revoke" after approval).
     if (mandate && query.message) {
         await callApi(config, "editMessageText", {
             chat_id: query.message.chat.id,
             message_id: query.message.message_id,
-            text: `🔐 Запрос мандата\n\n${describe(mandate)}\n\n${statusLine(mandate)}`,
+            text: `🔐 Mandate request\n\n${describe(mandate)}\n\n${statusLine(mandate)}`,
             reply_markup: { inline_keyboard: buttons(mandate) },
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcollar",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A small local broker between your AI agents and your accounts: short-lived, task-scoped mandates that you approve in Telegram, instead of passwords.",
   "keywords": [
     "ai-agents",