agentcollar 0.0.1 → 0.2.0

package/dist/telegram.js

@@ -0,0 +1,124 @@
+// Telegram channel for human approval, using the Bot API directly with fetch.
+// Long polling: we ask Telegram "anything new?" and it holds the request open
+// up to 30 seconds until something happens. No public server or webhook needed.
+import { setTimeout as sleep } from "node:timers/promises";
+import { decide, describe } from "./approval.js";
+// One Bot API call. The bot token is part of the URL, so we never print the URL.
+async function callApi(config, method, params) {
+    const response = await fetch(`https://api.telegram.org/bot${config.botToken}/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(params),
+    });
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Telegram ${method} failed: ${data.description}`);
+    }
+    return data.result;
+}
+function buttons(mandate) {
+    if (mandate.status === "pending") {
+        return [[
+                { text: "✅ Approve", callback_data: `approve:${mandate.id}` },
+                { text: "❌ Deny", callback_data: `deny:${mandate.id}` },
+            ]];
+    }
+    if (mandate.status === "approved" && !mandate.revoked) {
+        return [[{ text: "🛑 Revoke", callback_data: `revoke:${mandate.id}` }]];
+    }
+    return []; // denied or revoked: nothing left to press
+}
+function statusLine(mandate) {
+    if (mandate.revoked)
+        return "🛑 Revoked";
+    if (mandate.status === "approved")
+        return "✅ Approved";
+    if (mandate.status === "denied")
+        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
+// Sent when an agent asks for a mandate. Only the public id goes to Telegram, never the token.
+// Plain text (no parse_mode): the agent wrote the task text, so we do not let it format anything.
+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: `🔐 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 });
+}
+// The mandate ended outside Telegram: the message must not keep showing live buttons.
+async function closeMessage(config, mandate, finalLine) {
+    const sent = sentMessages.get(mandate.id);
+    if (sent === undefined)
+        return; // this mandate was never shown in Telegram
+    sentMessages.delete(mandate.id);
+    await callApi(config, "editMessageText", {
+        chat_id: sent.chatId,
+        message_id: sent.messageId,
+        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, "⌛ 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, "🛑 Revoked");
+}
+// A button was pressed.
+async function handleButton(config, query) {
+    // Anyone can find the bot and press buttons in a forwarded message.
+    // 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: "No access" });
+        return;
+    }
+    const [action, id] = (query.data ?? "").split(":");
+    const decision = action;
+    const mandate = ["approve", "deny", "revoke"].includes(action) && id ? decide(id, decision, "telegram") : undefined;
+    // Telegram shows a spinner on the button until we answer.
+    await callApi(config, "answerCallbackQuery", {
+        callback_query_id: query.id,
+        text: mandate ? statusLine(mandate) : "Already decided, or the mandate is gone",
+    });
+    // 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: `🔐 Mandate request\n\n${describe(mandate)}\n\n${statusLine(mandate)}`,
+            reply_markup: { inline_keyboard: buttons(mandate) },
+        });
+    }
+}
+// Runs forever in the background of the server.
+export async function startTelegramPolling(config) {
+    const me = (await callApi(config, "getMe", {}));
+    console.log(`Telegram: bot @${me.username} is listening, approver user id ${config.approverId}`);
+    let offset = 0; // "give me updates newer than this one"
+    while (true) {
+        try {
+            const updates = (await callApi(config, "getUpdates", {
+                offset,
+                timeout: 30, // long polling: wait up to 30 s for something new
+                allowed_updates: ["callback_query"],
+            }));
+            for (const update of updates) {
+                offset = update.update_id + 1; // mark as handled, even if handling fails
+                if (update.callback_query) {
+                    await handleButton(config, update.callback_query);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Telegram: ${error.message}, retrying in 5 s`);
+            await sleep(5000);
+        }
+    }
+}

package/package.json

@@ -1,10 +1,55 @@
 {
   "name": "agentcollar",
-  "version": "0.0.1",
-  "description": "Reserved for AgentCollar (https://github.com/ank8dev/agentcollar). The first real release is published from GitHub Actions with provenance.",
+  "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",
+    "mcp",
+    "security",
+    "gmail",
+    "telegram",
+    "claude-code",
+    "audit-log",
+    "least-privilege"
+  ],
   "homepage": "https://ank8dev.github.io/agentcollar/",
-  "repository": { "type": "git", "url": "git+https://github.com/ank8dev/agentcollar.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ank8dev/agentcollar.git",
+    "directory": "broker"
+  },
+  "bugs": {
+    "url": "https://github.com/ank8dev/agentcollar/issues"
+  },
   "author": "ank8dev",
-  "license": "MIT",
-  "files": ["README.md"]
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "agentcollar": "dist/cli.js",
+    "agcl": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "demo": "tsx src/demo.ts",
+    "server": "tsx src/server.ts",
+    "agent": "tsx src/agent.ts",
+    "setup": "tsx src/cli.ts setup",
+    "revoke": "tsx src/cli.ts revoke",
+    "test": "AGENTCOLLAR_HOME=${TMPDIR:-/tmp}/agentcollar-test-home tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
 }