agentcollar 0.0.1 → 0.1.0

package/dist/cli/mandates.js

@@ -0,0 +1,76 @@
+// agentcollar mandates — the mandates of the running broker: who, what, state, time and actions left.
+import { styleText } from "node:util";
+import { oneLine } from "../approval.js";
+import { readMandatesSnapshot } from "../snapshot.js";
+function duration(ms) {
+    const total = Math.ceil(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = String(total % 60).padStart(2, "0");
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${s}` : `${m}:${s}`;
+}
+// The same order as check(): the first thing that ends a mandate decides its name.
+export function mandateRow(m, now = Date.now()) {
+    let state = "активен";
+    if (m.status === "pending")
+        state = "ждёт решения";
+    else if (m.status === "denied")
+        state = "отклонён";
+    else if (now > m.expiresAt)
+        state = "истёк";
+    else if (m.revoked)
+        state = "отозван";
+    else if (m.used >= m.limit)
+        state = "лимит исчерпан";
+    const live = state === "активен";
+    return {
+        id: m.id,
+        agent: oneLine(m.agent, 24), // agent text: control characters removed before printing
+        actions: m.allowedActions.join(", "),
+        state,
+        timeLeft: live ? duration(m.expiresAt - now) : "—",
+        limit: `${m.used}/${m.limit}`,
+        live,
+    };
+}
+// Is the server process still running? Signal 0 checks without touching it.
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM"; // exists, but belongs to someone else
+    }
+}
+const COLUMNS = ["ID", "АГЕНТ", "ДЕЙСТВИЯ", "СТАТУС", "ОСТАЛОСЬ", "ЛИМИТ"];
+export async function runMandates(args) {
+    if (args.length > 0) {
+        console.error(`agentcollar mandates не принимает аргументов: ${args.join(" ")}`);
+        return 1;
+    }
+    const snapshot = readMandatesSnapshot();
+    if (snapshot === null) {
+        console.log("Брокер ещё не запускался. Запусти: agcl server");
+        return 0;
+    }
+    if (!isRunning(snapshot.pid)) {
+        console.log("Брокер не запущен. Мандаты живут в его памяти, поэтому после остановки их нет.");
+        return 0;
+    }
+    if (snapshot.mandates.length === 0) {
+        console.log("Мандатов пока нет.");
+        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("  ")));
+    }
+    return 0;
+}

package/dist/cli/revoke.js

@@ -0,0 +1,8 @@
+// agentcollar revoke <id> — the local kill switch from the terminal.
+import "../env.js";
+import { revokeMandate } from "../revoke.js";
+export async function runRevoke(args) {
+    const result = await revokeMandate(args[0] ?? "", Number(process.env.BROKER_PORT ?? 8787));
+    console.log(result.message);
+    return result.ok ? 0 : 1;
+}

package/dist/cli/setup.js

@@ -0,0 +1,124 @@
+// agcl setup (= agentcollar setup, npm run setup) — connects the broker to YOUR Telegram bot, without editing files by hand.
+// 1) asks for the bot token and checks it with Telegram,
+// 2) you press Start in the bot: we take your user id from that message,
+// 3) writes ~/.agentcollar/.env readable only by you (600).
+import { existsSync, readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { ensureHome, envFile, homeDir, legacyFiles, migrateLegacy } from "../paths.js";
+import { buildEnv, getBotUsername, newStartCode, pollForStart, sendText, skipOldUpdates, writeEnvFile, } from "../setup.js";
+const WAIT_MS = 5 * 60 * 1000;
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // 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("ввод закончился, ничего не записано")));
+        });
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+const yes = (answer) => answer.toLowerCase() === "y";
+// Reads a line without showing it (for the token). Node has no ready-made "password input",
+// so we switch the terminal to raw mode and read key by key, printing nothing.
+function askHidden(question) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY)
+        return ask(question); // input is piped, not typed: nothing to hide
+    return new Promise((resolve) => {
+        process.stdout.write(question);
+        stdin.setRawMode(true);
+        stdin.setEncoding("utf8");
+        stdin.resume();
+        let value = "";
+        const onData = (chunk) => {
+            for (const char of chunk) {
+                if (char === "\r" || char === "\n") {
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    stdin.off("data", onData);
+                    process.stdout.write("\n");
+                    return resolve(value.trim());
+                }
+                if (char === "\u0003")
+                    process.exit(130); // Ctrl+C
+                if (char === "\u007f")
+                    value = value.slice(0, -1); // Backspace
+                else
+                    value += char;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+export async function runSetup() {
+    try {
+        return await setup();
+    }
+    catch (error) {
+        console.error(`\n✗ ${error.message}`);
+        return 1;
+    }
+}
+async function setup() {
+    console.log("Настройка AgentCollar broker\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] `))) {
+            const moved = migrateLegacy();
+            console.log(moved.length > 0 ? `✓ Перенесено: ${moved.join(", ")}\n` : "Там уже есть свои файлы, старые оставил на месте.\n");
+        }
+    }
+    if (existsSync(envFile) && !yes(await ask(`${envFile} уже есть. Перезаписать настройки Telegram? [y/N] `))) {
+        console.log("Ничего не меняю.");
+        return 0;
+    }
+    // 1. Token
+    let token = "";
+    let username = "";
+    while (username === "") {
+        token = await askHidden("Токен бота (от @BotFather, при вводе не виден): ");
+        try {
+            username = await getBotUsername(token);
+        }
+        catch (error) {
+            console.log(`✗ ${error.message}\n`);
+        }
+    }
+    console.log(`✓ Бот найден: @${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 минут)...");
+    let user;
+    const deadline = Date.now() + WAIT_MS;
+    while (user === undefined && Date.now() < deadline) {
+        const round = await pollForStart(token, code, offset);
+        user = round.user;
+        offset = round.offset;
+    }
+    await skipOldUpdates(token); // tell Telegram we handled these messages
+    if (user === undefined) {
+        console.log("Время вышло. Запусти agcl setup ещё раз.");
+        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 ещё раз.");
+        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)");
+    return 0;
+}

package/dist/cli/start.js

@@ -0,0 +1,29 @@
+// `agcl` with no command: the intro, then the setup wizard if Telegram is not set up yet,
+// then the broker itself. One word from install to a running broker.
+import "../env.js";
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { envFile } 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();
+}
+export async function runStart(flags) {
+    await (await import("./intro.js")).maybeIntro(flags.noIntro);
+    // 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 — одобрять запросы в этом терминале) ");
+        if (answer === "" || answer === "y") {
+            const code = await (await import("./setup.js")).runSetup();
+            if (code !== 0)
+                return code;
+            if (existsSync(envFile))
+                process.loadEnvFile(envFile); // the server reads the new settings
+        }
+    }
+    await import("../server.js");
+    return new Promise(() => { }); // the server runs until Ctrl+C
+}

package/dist/cli/tail.js

@@ -0,0 +1,46 @@
+// Like `tail -f`: each readNew() returns only the entries appended since the previous call.
+import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { parseAuditLine } from "../audit-log.js";
+const NEWLINE = 0x0a; // the byte of "\n"
+export function createTail(file) {
+    let offset = 0; // how many bytes we have already read
+    let rest = Buffer.alloc(0); // bytes after the last "\n": a line the server is still writing
+    return {
+        readNew() {
+            if (!existsSync(file))
+                return [];
+            const size = statSync(file).size;
+            if (size < offset) {
+                // the file got shorter: it was cut or replaced, so start over
+                offset = 0;
+                rest = Buffer.alloc(0);
+            }
+            if (size === offset)
+                return [];
+            const chunk = Buffer.alloc(size - offset);
+            const fd = openSync(file, "r");
+            try {
+                readSync(fd, chunk, 0, chunk.length, offset);
+            }
+            finally {
+                closeSync(fd);
+            }
+            offset = size;
+            // Work with BYTES up to the last "\n". Turning a half line into text could cut a
+            // Cyrillic letter (2 bytes) in the middle and break it; the rest waits for the next call.
+            const bytes = Buffer.concat([rest, chunk]);
+            const end = bytes.lastIndexOf(NEWLINE);
+            if (end === -1) {
+                rest = bytes;
+                return [];
+            }
+            rest = bytes.subarray(end + 1);
+            return bytes
+                .subarray(0, end)
+                .toString("utf8")
+                .split("\n")
+                .map(parseAuditLine)
+                .filter((entry) => entry !== null);
+        },
+    };
+}

package/dist/cli/watch.js

@@ -0,0 +1,41 @@
+// agentcollar watch — the audit log live: every agent request as it happens, with the 6 checks.
+// Read-only: it only watches data/audit.log, no HTTP and no way to change anything.
+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 { createTail } from "./tail.js";
+const RECENT = 10; // how many past events to show first, for context
+function print(entry) {
+    console.log(formatEntry(entry, { showDate: !isToday(entry.time) }));
+}
+export async function runWatch(args) {
+    if (args.length > 0) {
+        console.error(`agentcollar watch не принимает аргументов: ${args.join(" ")}`);
+        return 1;
+    }
+    console.log(`${styleText("bold", "AgentCollar · watch")}   ${styleText("dim", "Ctrl+C — выход")}`);
+    console.log(styleText("dim", "проверки: 1 токен · 2 одобрен · 3 срок · 4 не отозван · 5 действие · 6 лимит"));
+    const tail = createTail(auditLogFile);
+    const past = tail.readNew().slice(-RECENT);
+    if (past.length > 0) {
+        console.log(styleText("dim", "— последние события —"));
+        past.forEach(print);
+    }
+    console.log(styleText("dim", "— дальше в реальном времени —"));
+    // 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 });
+    const watcher = watch(folder, (_event, name) => {
+        if (name === null || name === basename(auditLogFile))
+            tail.readNew().forEach(print);
+    });
+    return new Promise((resolve) => {
+        process.once("SIGINT", () => {
+            watcher.close();
+            process.stdout.write("\n");
+            resolve(0);
+        });
+    });
+}

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The `agcl` / `agentcollar` command: the words typed after it go to the CLI.
+import { runCli } from "./cli/main.js";
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/env.js

@@ -0,0 +1,13 @@
+// Loads ~/.agentcollar/.env into process.env (secrets live there, never in the code).
+// Imported first by the server and by the CLI commands.
+import { existsSync } from "node:fs";
+import { envFile, legacyFiles } from "./paths.js";
+if (existsSync(envFile)) {
+    process.loadEnvFile(envFile); // built into Node: puts the lines of .env into process.env
+}
+else if (process.env.AGENTCOLLAR_HOME === undefined && existsSync(legacyFiles.env)) {
+    // 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/");
+}

package/dist/gmail-fake.js

@@ -0,0 +1,27 @@
+// 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.
+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;
+}

package/dist/mandate.js

@@ -0,0 +1,82 @@
+import { randomBytes } from "node:crypto";
+// In-memory store: token -> mandate.
+// It disappears when the program stops. That is fine for now.
+export const mandates = new Map();
+// Called after every change. The server uses it to write data/mandates.json for `agentcollar mandates`.
+let changeListener = () => { };
+export function onMandatesChanged(listener) {
+    changeListener = listener;
+}
+export function mandatesChanged() {
+    changeListener();
+}
+// An agent asks for a mandate. It stays "pending" until a human decides.
+export function requestMandate(agent, task, allowedActions, expiresInSeconds, limit) {
+    const mandate = {
+        id: randomBytes(4).toString("hex"), // 8 characters, easy to read; not a secret
+        // 32 random bytes = 256 bits: impossible to guess. As hex text it is 64 characters.
+        token: randomBytes(32).toString("hex"),
+        agent,
+        task,
+        allowedActions,
+        status: "pending",
+        expiresInSeconds,
+        expiresAt: 0,
+        limit,
+        used: 0,
+        revoked: false,
+        createdAt: Date.now(),
+    };
+    mandates.set(mandate.token, mandate);
+    mandatesChanged();
+    return mandate;
+}
+// Shortcut used by the Phase 1 demo: request + approve at once, returns the token.
+export function issueMandate(agent, task, allowedActions, expiresInSeconds, limit) {
+    const mandate = requestMandate(agent, task, allowedActions, expiresInSeconds, limit);
+    approve(mandate.id);
+    return mandate.token;
+}
+// The human side only knows the public id, never the token.
+export function findById(id) {
+    for (const mandate of mandates.values()) {
+        if (mandate.id === id)
+            return mandate;
+    }
+    return undefined;
+}
+// Pending mandates nobody answered for longer than maxAgeMs (the server uses 10 minutes).
+export function findStalePending(maxAgeMs, now = Date.now()) {
+    return [...mandates.values()].filter((mandate) => mandate.status === "pending" && now - mandate.createdAt > maxAgeMs);
+}
+// Human says yes. Only a pending mandate can be decided, and only once.
+export function approve(id) {
+    const mandate = findById(id);
+    if (mandate === undefined || mandate.status !== "pending")
+        return undefined;
+    mandate.status = "approved";
+    mandate.expiresAt = Date.now() + mandate.expiresInSeconds * 1000;
+    mandatesChanged();
+    return mandate;
+}
+// Human says no.
+export function deny(id) {
+    const mandate = findById(id);
+    if (mandate === undefined || mandate.status !== "pending")
+        return undefined;
+    mandate.status = "denied";
+    mandatesChanged();
+    return mandate;
+}
+// Kill switch: the human stops a mandate immediately.
+// We mark it instead of deleting it, so check() can still say "revoked" (not "unknown")
+// and the audit log still knows which agent it belonged to.
+// Phase 1 passed the token; now the human side uses the public id.
+export function revoke(id) {
+    const mandate = findById(id);
+    if (mandate === undefined)
+        return undefined;
+    mandate.revoked = true;
+    mandatesChanged();
+    return mandate;
+}

package/dist/mcp/protocol.js

@@ -0,0 +1,72 @@
+// The small part of MCP (Model Context Protocol) we need: tools over JSON-RPC 2.0.
+// One message = one line of JSON. A request has an "id" and gets a reply with the same id;
+// a notification has no "id" and gets no reply. This file knows nothing about the broker.
+// Newest first. If the client asks for one of these, we answer with it; otherwise with the newest.
+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 " +
+    "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 });
+}
+function error(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+// Handles one incoming line. Returns the reply line, or null when no reply is due.
+export async function handleMessage(line, context) {
+    if (line.trim() === "")
+        return null;
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return error(null, -32700, "Parse error");
+    }
+    if (typeof message !== "object" || message === null || Array.isArray(message)) {
+        return error(null, -32600, "Invalid Request");
+    }
+    const m = message;
+    const id = typeof m.id === "string" || typeof m.id === "number" ? m.id : null;
+    if (m.jsonrpc !== "2.0" || typeof m.method !== "string")
+        return error(id, -32600, "Invalid Request");
+    if (m.id === undefined)
+        return null; // a notification, e.g. "notifications/initialized"
+    const params = (typeof m.params === "object" && m.params !== null ? m.params : {});
+    switch (m.method) {
+        case "initialize": {
+            const requested = params.protocolVersion;
+            const version = typeof requested === "string" && SUPPORTED_VERSIONS.includes(requested) ? requested : SUPPORTED_VERSIONS[0];
+            const clientInfo = params.clientInfo;
+            if (typeof clientInfo?.name === "string")
+                context.onInitialize?.(clientInfo.name);
+            return reply(id, { protocolVersion: version, capabilities: { tools: {} }, serverInfo: SERVER_INFO, instructions: INSTRUCTIONS });
+        }
+        case "ping":
+            return reply(id, {});
+        case "tools/list":
+            return reply(id, {
+                tools: context.tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+            });
+        case "tools/call": {
+            const tool = context.tools.find((t) => t.name === params.name);
+            if (tool === undefined)
+                return error(id, -32602, `Unknown tool: ${String(params.name)}`);
+            const args = params.arguments ?? {};
+            if (typeof args !== "object" || args === null || Array.isArray(args)) {
+                return error(id, -32602, "arguments must be an object");
+            }
+            try {
+                return reply(id, await tool.call(args));
+            }
+            catch (e) {
+                // Details go to stderr for the human; the model only learns that it failed.
+                console.error(`agentcollar mcp: tool ${tool.name} failed: ${e.message}`);
+                return reply(id, { content: [{ type: "text", text: `Tool ${tool.name} failed inside AgentCollar.` }], isError: true });
+            }
+        }
+        default:
+            return error(id, -32601, `Method not found: ${m.method}`);
+    }
+}

package/dist/mcp/server.js

@@ -0,0 +1,22 @@
+// AgentCollar MCP server over stdio. Claude Code (or another agent) starts this file and
+// talks to it through stdin/stdout, one JSON message per line.
+// Register: claude mcp add agentcollar -- npx tsx <path>/broker/src/mcp/server.ts
+// IMPORTANT: stdout belongs to the protocol. Anything else printed there breaks the connection,
+// so every log line goes to stderr (console.error).
+import "../env.js";
+import { createInterface } from "node:readline";
+import { handleMessage } from "./protocol.js";
+import { createTools } from "./tools.js";
+const port = Number(process.env.BROKER_PORT ?? 8787);
+let clientName = "mcp-agent"; // replaced by the client's name from "initialize"
+const tools = createTools({ brokerUrl: `http://127.0.0.1:${port}`, agentName: () => clientName });
+const lines = createInterface({ input: process.stdin });
+lines.on("line", (line) => {
+    handleMessage(line, { tools, onInitialize: (name) => (clientName = name) })
+        .then((reply) => {
+        if (reply !== null)
+            process.stdout.write(reply + "\n");
+    })
+        .catch((error) => console.error(`agentcollar mcp: ${error.message}`));
+});
+console.error(`agentcollar MCP server ready (stdio), broker at 127.0.0.1:${port}`);