agentcollar 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 ank8dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT license above applies to the source code in this repository.
+It does NOT apply to the brand assets in the brand/ folder (logos, marks and
+hand-drawn illustrations): those are © 2026 ank8dev, all rights reserved.

package/README.md

@@ -1,5 +1,83 @@
-# agentcollar
+# AgentCollar
 
-Name reserved for [AgentCollar](https://github.com/ank8dev/agentcollar).
-This version contains no code. Real releases (0.1.0 and later) are built and published by
-GitHub Actions with npm provenance.
+**Let agents work. Keep the keys.** A small broker that runs on your own computer, between your AI
+agents and your accounts. Agents get a short-lived, task-scoped *mandate* that you approve in
+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.
+
+## Install
+
+Requires **Node.js 22+**.
+
+```bash
+npx agentcollar          # try it without installing
+npm install -g agentcollar   # or install: then the short name `agcl` works too
+```
+
+`agcl` and `agentcollar` are the same program: `agcl watch` == `agentcollar watch`.
+
+## First run
+
+```bash
+agcl
+```
+
+The intro plays, then the setup wizard connects **your own** Telegram bot (create one with
+[@BotFather](https://t.me/BotFather); the wizard takes your user id from the Start message, with a
+one-time code), then the broker starts on `127.0.0.1:8787`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agcl` | intro → setup (if not set up yet) → broker |
+| `agcl setup` | connect your Telegram bot |
+| `agcl server` | start the broker |
+| `agcl watch` | live screen: every agent request and which of the 6 checks passed or failed |
+| `agcl mandates` | mandates of the running broker: state, time left, actions left |
+| `agcl logs [--agent <name>] [--denied] [--today]` | the audit log, filtered |
+| `agcl revoke <id>` | kill switch: revoke a mandate instantly |
+| `agcl mcp` | MCP server (stdio) for Claude Code and other agents |
+
+Flags: `--no-intro`, `-h` / `--help`.
+
+## Use it from Claude Code (MCP)
+
+```bash
+claude mcp add agentcollar -- npx -y agentcollar mcp
+```
+
+Tools: `request_mandate`, `mandate_status`, `gmail_read_inbox`, `gmail_create_draft`, `gmail_send`.
+Every call goes through the broker with a mandate token. The token stays inside the MCP server and
+is never shown to the model.
+
+## How a request is checked
+
+Every request runs 6 checks in order; the first failure stops it:
+
+1. the token is known → `401`
+2. a human approved the mandate → `403`
+3. not expired → `403`
+4. not revoked → `403`
+5. this action is in the mandate → `403`
+6. the action limit is not reached → `429`
+
+## Security
+
+- Listens on `127.0.0.1` only; refuses browser requests (`Host` check against DNS rebinding,
+  no `Origin`, JSON only).
+- **Approval is never possible over HTTP or through files**: only in Telegram (only your user id)
+  or in the broker's own terminal. A local agent cannot approve itself.
+- Your data lives in `~/.agentcollar/` (folder `700`, files `600`): `.env`, `audit.log`,
+  `mandates.json` (no tokens in it).
+- Append-only audit log; text from agents is escaped and stripped of terminal control characters.
+- **No runtime dependencies.** Published from GitHub Actions with npm provenance.
+
+## License
+
+Code: MIT. The AgentCollar brand assets (logo, the intro medallion derived from it) are
+© ank8dev, all rights reserved. See [LICENSE](LICENSE).
+
+Source, roadmap and full docs: <https://github.com/ank8dev/agentcollar>

package/dist/approval.js

@@ -0,0 +1,67 @@
+// Phase 3: a human decides about every mandate request.
+// Two channels: Telegram (if configured) or the terminal where the server runs.
+import { createInterface } from "node:readline/promises";
+import { writeAudit } from "./audit.js";
+import { approve, deny, findStalePending, revoke } from "./mandate.js";
+// The single place where a human decision is applied and written to the audit log.
+// Telegram and the terminal both end up here.
+export function decide(id, decision, by) {
+    const mandate = decision === "approve" ? approve(id) : decision === "deny" ? deny(id) : revoke(id);
+    if (mandate !== undefined) {
+        writeAudit(mandate.agent, `mandate.${decision}`, decision === "approve", `${decision} by ${by}, mandate ${id}`);
+    }
+    return mandate;
+}
+// Fail closed: a request nobody answered in time is denied, never left hanging.
+// Returns the mandates it denied, so the server can update their Telegram messages.
+export function denyStalePending(maxAgeMs, now = Date.now()) {
+    const denied = [];
+    for (const mandate of findStalePending(maxAgeMs, now)) {
+        const result = decide(mandate.id, "deny", "timeout");
+        if (result !== undefined)
+            denied.push(result);
+    }
+    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
+// invisible / right-to-left characters. We squash it into one short, plain line.
+export function oneLine(text, max) {
+    const plain = text
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ") // line breaks, control chars
+        .replace(/[\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, "") // invisible, direction tricks
+        .replace(/\s+/g, " ")
+        .trim();
+    return plain.length > max ? plain.slice(0, max) + "…" : plain;
+}
+// Human-readable summary, used in the terminal and in Telegram.
+// The facts the broker enforces come FIRST; the agent's own words come last, in quotes.
+export function describe(mandate) {
+    const lines = [];
+    if (mandate.allowedActions.some((action) => action.endsWith(".send"))) {
+        lines.push("⚠️ Агент просит право ОТПРАВЛЯТЬ от твоего имени");
+    }
+    lines.push(`Действия: ${mandate.allowedActions.join(", ")}`, `Срок: ${mandate.expiresInSeconds} с после одобрения, лимит ${mandate.limit}`, `id: ${mandate.id}`, `Агент: ${oneLine(mandate.agent, 64)}`, `Задача (слова агента): «${oneLine(mandate.task, 200)}»`);
+    return lines.join("\n");
+}
+// Terminal channel. Questions are asked one at a time: if two agents ask at once,
+// the second question waits until the first one is answered.
+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] `);
+        rl.close();
+        console.log(applyTerminalAnswer(mandate, answer));
+    });
+}
+// Applies the human's terminal answer and says what REALLY happened.
+// The question may have waited so long that the mandate already timed out
+// (or was decided in Telegram): then the answer changes nothing, and we say so.
+export function applyTerminalAnswer(mandate, answer) {
+    const decision = answer.trim().toLowerCase() === "y" ? "approve" : "deny";
+    if (decide(mandate.id, decision, "terminal") === undefined) {
+        return "  ⌛ уже решено (время вышло или ответили в Telegram), ответ не применён";
+    }
+    return decision === "approve" ? "  ✅ одобрен" : "  ❌ отклонён";
+}

package/dist/audit-log.js

@@ -0,0 +1,37 @@
+// Reads data/audit.log back into objects, for `agentcollar logs` and `agentcollar watch`.
+// Line format (see audit.ts):  time | "agent" | "action" | ALLOWED|DENIED | "reason" [| code]
+import { existsSync, readFileSync } from "node:fs";
+// A JSON string: quote, then any characters except an unescaped quote, then quote.
+// Matching whole strings (not splitting on " | ") keeps a " | " inside the text in one piece.
+const QUOTED = String.raw `"(?:[^"\\]|\\.)*"`;
+const LINE = new RegExp(String.raw `^(\S+) \| (${QUOTED}) \| (${QUOTED}) \| (ALLOWED|DENIED) \| (${QUOTED})(?: \| ([a-z_]+))?$`);
+// The very first lines (before escaping was added in step 4.1) had no quotes at all.
+const OLD_LINE = /^(\S+) \| ([^|"]+) \| ([^|"]+) \| (ALLOWED|DENIED) \| ([^|"]*)$/;
+export function parseAuditLine(line) {
+    const match = LINE.exec(line);
+    if (match !== null) {
+        const [, time, agent, action, verdict, reason, code] = match;
+        return {
+            time: time,
+            agent: JSON.parse(agent),
+            action: JSON.parse(action),
+            allowed: verdict === "ALLOWED",
+            reason: JSON.parse(reason),
+            code: code ?? null,
+        };
+    }
+    const old = OLD_LINE.exec(line);
+    if (old !== null) {
+        const [, time, agent, action, verdict, reason] = old;
+        return { time: time, agent: agent, action: action, allowed: verdict === "ALLOWED", reason: reason, code: null };
+    }
+    return null; // not a log line: skip it rather than guess
+}
+export function readAuditLog(file) {
+    if (!existsSync(file))
+        return [];
+    return readFileSync(file, "utf8")
+        .split("\n")
+        .map(parseAuditLine)
+        .filter((entry) => entry !== null);
+}

package/dist/audit.js

@@ -0,0 +1,23 @@
+import { appendFileSync } from "node:fs";
+import { auditLogFile, ensureHome } from "./paths.js";
+// ~/.agentcollar/audit.log (see paths.ts). Re-exported for the modules that read the log.
+export { auditLogFile };
+// Text that came from outside (agent name, action) could contain a line break
+// and fake a second log line. JSON.stringify wraps it in quotes and turns a line
+// break into a visible \n, so one event is always exactly one line.
+function safe(text) {
+    return JSON.stringify(text);
+}
+// Appends one line per event: every check, and every human decision.
+// We only ever add lines, never change or delete them.
+// The token is NOT written: it is a secret, and the log is not.
+// `code` (only for checks) says which check decided, e.g. "expired": `agentcollar watch` shows it.
+export function writeAudit(agent, action, allowed, reason, code) {
+    ensureHome(); // ~/.agentcollar/ with rights 700
+    const time = new Date().toISOString(); // e.g. 2026-10-04T07:00:00.000Z (UTC)
+    const verdict = allowed ? "ALLOWED" : "DENIED";
+    const fields = [time, safe(agent), safe(action), verdict, safe(reason)];
+    if (code !== undefined)
+        fields.push(code); // our own fixed word: needs no quoting
+    appendFileSync(auditLogFile, fields.join(" | ") + "\n", { mode: 0o600 }); // 600 when the file is created
+}

package/dist/check.js

@@ -0,0 +1,52 @@
+import { writeAudit } from "./audit.js";
+import { mandates, mandatesChanged } from "./mandate.js";
+// The order of the checks. A failure code tells how far a request got: "expired" = check 3.
+export const CHECK_ORDER = ["unknown_token", "not_approved", "expired", "revoked", "action_not_allowed", "limit_reached"];
+// The one function the outside world calls: decide, then write it down.
+// Every answer goes to the audit log, allowed or denied.
+export function check(token, action) {
+    const result = runChecks(token, action);
+    // For an unknown token there is no mandate, so no agent name either.
+    const agent = mandates.get(token)?.agent ?? "unknown";
+    writeAudit(agent, action, result.allowed, result.reason, result.code);
+    return result;
+}
+function deny(code, reason) {
+    return { allowed: false, code, reason };
+}
+// Runs the checks in order. The first failed check stops everything (early return).
+function runChecks(token, action) {
+    // 1. Token is known: we issued it ourselves
+    const mandate = mandates.get(token);
+    if (mandate === undefined) {
+        return deny("unknown_token", "unknown token");
+    }
+    // 2. A human approved it (Phase 3). Must come before "expired":
+    //    a pending mandate has no expiry time yet.
+    if (mandate.status === "pending") {
+        return deny("not_approved", "mandate is waiting for human approval");
+    }
+    if (mandate.status === "denied") {
+        return deny("not_approved", "mandate was denied (by the human, or no answer in time)");
+    }
+    // 3. Not expired
+    if (Date.now() > mandate.expiresAt) {
+        return deny("expired", "mandate expired");
+    }
+    // 4. Not revoked by the human (kill switch)
+    if (mandate.revoked) {
+        return deny("revoked", "mandate revoked");
+    }
+    // 5. This action is on the list
+    if (!mandate.allowedActions.includes(action)) {
+        return deny("action_not_allowed", `action "${action}" is not allowed`);
+    }
+    // 6. Limit not reached
+    if (mandate.used >= mandate.limit) {
+        return deny("limit_reached", `limit of ${mandate.limit} actions reached`);
+    }
+    // All checks passed. Only allowed actions use up the limit.
+    mandate.used += 1;
+    mandatesChanged();
+    return { allowed: true, code: "ok", reason: "ok" };
+}

package/dist/cli/format.js

@@ -0,0 +1,39 @@
+// How one audit entry looks on screen. Shared by `agentcollar logs` and `agentcollar watch`.
+import { styleText } from "node:util";
+import { oneLine } from "../approval.js";
+import { CHECK_ORDER } from "../check.js";
+// ✓ passed, ✗ failed here, · not reached. Empty for human decisions and old lines without a code.
+export function checkMarks(entry) {
+    if (entry.code === null)
+        return "";
+    const failedAt = entry.code === "ok" ? CHECK_ORDER.length : CHECK_ORDER.indexOf(entry.code);
+    return CHECK_ORDER.map((_, i) => (i < failedAt ? "✓" : i === failedAt ? "✗" : "·")).join(" ");
+}
+const pad = (n) => String(n).padStart(2, "0");
+export function isSameLocalDay(a, b) {
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+export function isToday(iso, now = new Date()) {
+    return isSameLocalDay(new Date(iso), now);
+}
+// Local time: "15:42:07", or "2026-10-04 15:42:07" when the date matters.
+export function localTime(iso, showDate) {
+    const d = new Date(iso);
+    const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+    return showDate ? `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}` : time;
+}
+// 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.
+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 verdict = entry.allowed ? styleText("green", "ALLOWED") : styleText("red", "DENIED ");
+    const marks = checkMarks(entry).padEnd(11);
+    return `${time}  ${agent}  ${action.padEnd(18)}  ${verdict}  ${marks}  ${reason}`;
+}

package/dist/cli/intro-frames.js

@@ -0,0 +1,25 @@
+// GENERATED by tools/gen-intro.ts from brand/logo/agentcollar-mark-black.png. Do not edit by hand.
+// Derived from the AgentCollar mark: © 2026 ank8dev, all rights reserved (NOT covered by the MIT license).
+// The medallion, 48×48 dots (24 columns × 12 rows), turned 0°, 30°, … 330° clockwise.
+export const SPIN = [
+    ["", "       ⢀⣤⣤⣴⣶⣶⣶⣦⣄⡀", "     ⣤⣾⣵⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄", "   ⢠⣾⣿⣿⣿⠿⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⡀", "  ⢀⣿⢻⣿⣿⡟ ⡀⠹⣿⣿⡿⠉⢀⡀⠘⣿⣿⣷⡀", "  ⢸⣿⣾⣿⡿ ⣸⣧ ⢻⣿⠁ ⣿⣿⣿⣿⣿⣿⡇", "  ⢸⣿⣿⣿⠃ ⣀⣀⡀⠈⣿ ⠘⣿⣿⡿⣿⣿⣿⡇", "  ⠈⣿⣿⡏ ⣼⣿⣿⣷ ⢸⣧⡀⠉⠉⢀⣼⣿⣿⠇", "   ⠘⣿⣷⣾⣿⣿⣿⣿⣷⣾⣿⣿⣶⣾⣿⡿⣻⠏", "     ⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁", "       ⠉⠛⠳⠶⠿⠿⠿⠟⠛⠁", ""],
+    ["", "       ⣀⣤⣴⣶⣒⣶⣶⣤⣄⣀", "    ⢀⣤⡾⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄", "   ⢠⣾⣯⣾⣿⣿⠿⠋⠉⢹⣿⣿⣿⣿⣿⣿⣷⡀", "  ⢀⣿⣿⣿⡿⠟⠁⣠⡆ ⣾⣿⣿⣿⣿⣿⣿⣿⣷", "  ⢸⣿⡿⠋ ⣀⡀⠉⠁⢀⣿⡿⠋⠉⣀⠉⢻⣿⣿⡆", "  ⢸⣿⣦⣤⣾⣿⣿⡇ ⣸⡏ ⣠⣾⣿⣤⣼⣿⣏⡇", "  ⠘⣿⣿⣿⣿⣿⣿⡇⢀⣿ ⢰⣿⣿⣿⣿⣿⣿⣿⠁", "   ⠘⣿⡿⣿⣿⣿⣿⣿⣿⣄ ⠉⠁⣹⣿⣿⣿⠃", "    ⠈⠻⢮⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠁", "       ⠈⠛⠻⠿⠿⠿⠿⠿⠚⠋⠁", ""],
+    ["", "       ⣀⣤⣤⣶⣶⣶⣶⣦⣤⡀", "    ⢀⣴⣾⣿⣿⣶⣶⣿⣿⣿⣿⣷⣾⣷⣄", "   ⢠⣿⣿⣿⡿⠿⠿⠛⠛⠛⠉⠛⣿⣿⣿⣿⣷⡄", "  ⢠⣿⣿⣀⣀⣀⣀ ⢲⡶⠋⢀⣾⣿⣿⣿⣿⣿⣷⡀", "  ⢸⣿⣿⣿⣿⣿⣿⡦  ⣴⣿⣿⣿⣿⣿⣿⣿⣿⡇", "  ⢸⡿⣿⣿⣿⣿⠋ ⣠⡾⠋⠉⠉⠁⠉⠻⣿⣿⣿⡇", "  ⠈⣷⣻⣿⣿⣿⣶⣿⠃⢀⣴⣾⣿⣿⡃⢠⣿⣿⡿", "   ⠈⢿⣿⣿⣿⣿⣿⡀⠘⠿⢿⣿⣿⣿⣿⣿⡿⠁", "     ⠻⢿⣿⣿⣿⣿⣶⣤⣼⣿⣿⣿⡿⠋", "       ⠉⠛⠿⢭⣿⣿⣿⠿⠛⠉", ""],
+    ["", "       ⣀⣤⣴⣶⣶⣶⣶⣦⣤⣀", "    ⢀⣤⣿⡿⠿⢿⣿⣿⣿⣷⣶⣿⣿⣷⣤", "   ⢠⣿⣿⣿⣷⣤⣀ ⠉⠙⠛⠿⣿⣿⣿⣿⡳⡀", "  ⢀⡿⣿⣿⣿⣿⣿⣿⡇ ⣷⠶⠄ ⢘⣿⣿⣿⣿", "  ⢸⣧⣿⣿⣿⡿⠛⠋⠁⢀⣀⣤⣴⣾⣿⣿⣿⣿⣿⡆", "  ⢸⣿⣿⣿⣿⣷⣶⠶⠛⠛⠛⠻⢿⣿⣿⣿⣿⣿⣿⡇", "  ⠈⣿⣿⣿⣿⡟⠁⢠⣤⣶⣤⣤⡀⠘⣿⣿⣿⣿⡿⠁", "   ⠈⣿⣿⣿⣷⡀⠘⢿⣿⣿⣿⠁⣀⣿⣿⣿⡿⠁", "    ⠈⠻⣝⣿⣿⣶⣿⣿⣿⣿⣿⣿⣿⡿⠋", "      ⠈⠙⠻⠿⠿⠿⠿⠿⠟⠋⠁", ""],
+    ["", "       ⣀⣤⣶⣶⣶⣶⣶⣦⣤⣀", "    ⢀⣴⢿⣿⣿⣿⣿⠁⠙⢿⣿⣿⣿⢷⣦", "   ⢀⣾⣵⣿⣿⣿⣿⣿⣷⡄ ⠹⣿⣿⣷⣹⣷⡄", "  ⢀⣿⣿⣿⣿⣿⠿⠿⠿⠿⠁⢠⣄⠈⢻⣿⣿⣿⣿⡀", "  ⢸⣿⣿⣿⣿⣿⣦⣤⣄⣀⡀⠈⠉⠁ ⢹⣿⣿⡟⡇", "  ⢸⣿⣿⣿⠋ ⣀⡀⠉⠙⢿⣿⣿⣷⣶⣾⣿⣿⣿⡇", "  ⠘⣟⣿⣿ ⠸⣿⣿⣷⣄ ⢹⣿⣿⣿⣿⣿⣿⡿", "   ⠹⣿⣿⣷⣾⣿⣿⣿⠛⠃⢠⣿⣿⣿⣿⣿⡿⠃", "    ⠙⠻⣿⣿⣿⣿⣿⣶⣶⣿⣿⣿⣿⡿⠋", "       ⠉⠛⠻⠯⠽⠿⠟⠛⠋⠁", ""],
+    ["", "       ⢀⣤⡴⢶⣶⣶⣶⣶⣤⣀", "    ⢀⣤⣾⣿⣷⣿⣿⣿⣿⣿⡟⠛⣿⣿⣦⡀", "   ⢠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇ ⢿⣿⣿⣷⡄", "  ⢠⣿⣿⣿⣿⣿⣿⣧ ⠙⢿⠟⠃ ⢸⣿⣿⡟⣿", "  ⣾⣼⣿⡟⠁⣀⡀⠉⢷⣄  ⢶⡇ ⣿⣿⣧⣿⡇", "  ⣿⣿⣿⣀⣸⣿⣿⣆ ⢹⣿⣦⡀⠙ ⢻⣿⣿⣿⡇", "  ⠘⣿⣿⣿⣿⣿⣿⣿ ⠸⣿⣿⣿⣷⣤⣿⣿⡿⣿⠁", "   ⠘⢿⣿⣿⣿⣁⠉⢀⣼⣿⣿⣿⣿⣿⣿⣿⡷⠁", "     ⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠋", "       ⠈⠙⠛⠿⠿⠿⠿⠟⠋⠉", ""],
+    ["", "       ⢀⣤⣴⣶⣶⣶⠶⢦⣤⣀", "    ⢀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦", "   ⣰⣯⣾⣿⡿⠿⣿⣿⡿⢿⣿⣿⣿⣿⡿⢿⣿⡄", "  ⢰⣿⣿⡟⠁⣀⣀⠈⢻⡇ ⢿⣿⣿⡟ ⣸⣿⣿⡀", "  ⢸⣿⣿⣿⣾⣿⣿⡄ ⣿⡀⠈⠉⠉ ⢠⣿⣿⣿⡇", "  ⢸⣿⣿⣿⣿⣿⣿ ⢀⣿⣧ ⢻⡏ ⣾⣿⡿⣿⡇", "  ⠈⢿⣿⣿⡄⠈⠁⣀⣾⣿⣿⣆⠈ ⣼⣿⣿⣧⣿⠁", "   ⠈⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣶⣿⣿⣿⡿⠃", "     ⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢟⡿⠛", "       ⠈⠙⠻⠿⠿⠿⠟⠛⠛⠁", ""],
+    ["", "      ⢀⣠⡤⣶⣶⣶⣶⣶⣦⣤⡀", "    ⢀⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡳⣦⡀", "   ⢠⣿⣿⣿⣏⢀⣀ ⠙⣿⣿⣿⣿⣿⣿⣾⣿⡄", "  ⢀⣿⣿⣿⣿⣿⣿⣿⠇ ⣿⠁⢸⣿⣿⣿⣿⣿⣿⡄", "  ⢸⣹⣿⡟⠛⣿⡿⠋ ⣸⡏ ⢸⣿⣿⡿⠛⠻⣿⡇", "  ⠸⣿⣿⣧⣀⠉⣀⣠⣾⣿⠁⢀⣀⠈⠉ ⣠⣾⣿⡇", "   ⢿⣿⣿⣿⣿⣿⣿⣿⡿ ⠸⠋⢀⣴⣾⣿⣿⣿⠁", "   ⠈⢿⣿⣿⣿⣿⣿⣿⣇⣀⣠⣶⣿⣿⡿⣻⡿⠃", "     ⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⡾⠛⠁", "       ⠉⠙⠛⠿⠿⠭⠿⠟⠛⠉", ""],
+    ["", "       ⣀⣤⣶⣿⣿⣿⣓⣶⣤⣀", "     ⣠⣾⣿⣿⣿⡟⠛⠿⣿⣿⣿⣿⣷⣦", "   ⢀⣾⣿⣿⣿⣿⣿⣷⣶⡄⠈⣿⣿⣿⣿⣿⣷⡀", "   ⣾⣿⣿⠃⢨⣿⣿⡿⠟⠁⢠⣿⠿⣿⣿⣿⣯⢿⡀", "  ⢸⣿⣿⣿⣦⣀⢀⣀⣀⣠⡾⠋ ⣠⣿⣿⣿⣿⣾⡇", "  ⢸⣿⣿⣿⣿⣿⣿⣿⣿⠟  ⠺⣿⣿⣿⣿⣿⣿⡇", "  ⠈⢿⣿⣿⣿⣿⣿⡿⠁⣠⠾⠧ ⠉⠉⠉⠉⣿⣿⠃", "   ⠘⢿⣿⣿⣿⣿⣤⣀⣤⣤⣤⣶⣶⣾⣿⣿⣿⠃", "     ⠙⢿⡿⢿⣿⣿⣿⣿⠿⠿⣿⣿⡿⠟⠁", "       ⠈⠛⠻⠿⠿⠿⠿⠛⠛⠉", ""],
+    ["", "       ⢀⣠⣴⣶⣶⣶⣶⣶⣦⣄⡀", "     ⣠⣾⣿⣿⣿⣿⣿⣿⣿⠿⣿⣿⣝⣦⡀", "   ⢀⣾⣿⣿⣿⠉⢀⣿⣿⣿⣷⡄⠈⢿⣿⣿⣿⡀", "  ⢀⣾⣿⣿⣿⣿⡄⠈⠛⠛⠿⠛⠃⢀⣼⣿⣿⣿⣿⡀", "  ⢸⣿⣿⣿⣿⣿⣿⣷⣦⣤⣤⣤⠶⠿⢿⣿⣿⣿⣿⡇", "  ⠸⣿⣿⣿⣿⣿⡿⠟⠛⠉⠁⢀⣠⣤⣾⣿⣿⣿⢻⡇", "   ⣿⣿⣿⣿⡅ ⠐⠶⢿ ⢸⣿⣿⣿⣿⣿⣿⣾⠁", "   ⠈⢮⣿⣿⣿⣿⣶⣤⣄⣀ ⠉⠛⢿⣿⣿⣿⠃", "     ⠛⢿⣿⣿⠿⢿⣿⣿⣿⣷⣶⣾⣿⠛⠁", "       ⠉⠛⠻⠿⠿⠿⠿⠟⠛⠉", ""],
+    ["", "       ⢀⣠⣤⣴⣶⣖⣲⣦⣤⣀", "     ⣠⣾⣿⣿⣿⣿⠿⠿⣿⣿⣿⣿⣿⣦⣄", "   ⢠⣾⣿⣿⣿⣿⣿⠃⢠⣤⣿⣿⣿⡿⢿⣿⣿⣆", "   ⣾⣿⣿⣿⣿⣿⣿⣇ ⠙⢿⣿⣿⡆ ⣿⣿⣽⡄", "  ⢸⣿⣿⣿⡿⠿⢿⣿⣿⣷⣄⣀⠈⠉ ⣠⣿⣿⣿⡇", "  ⢸⣼⣿⣿⣇ ⢀⣀⡀⠈⠉⠙⠛⠻⣿⣿⣿⣿⣿⡇", "  ⠈⣿⣿⣿⣿⣧⡀⠙⠃⢀⣶⣶⣶⣶⣿⣿⣿⣿⣿⠁", "   ⠘⢿⣏⢿⣿⣿⣆ ⠘⢿⣿⣿⣿⣿⣿⢟⡿⠁", "     ⠻⢷⣿⣿⣿⣷⣄⢀⣿⣿⣿⣿⣷⠟⠁", "       ⠉⠛⠻⠿⠿⠿⠿⠿⠛⠉", ""],
+    ["", "       ⣀⣠⣴⣶⣶⣶⣶⣤⣄⡀", "     ⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄", "   ⢀⢾⣿⣿⣿⣿⣿⣿⣿⡟⠁⣀⢉⣿⣿⣿⣷⡄", "  ⢀⣿⣾⣿⣿⠛⢿⣿⣿⣿⡆ ⣿⣿⣿⣿⣿⣿⣿⡄", "  ⢸⣿⣿⣿⣧ ⣄⠈⠻⣿⣇ ⠹⣿⣿⡏⠉⣿⣿⣿", "  ⢸⣿⢻⣿⣿ ⢸⠷  ⠙⢷⣀⠈⠉⢀⣼⣿⡟⡿", "   ⣿⣼⣿⣿⡇ ⢠⣴⣷⣄ ⢻⣿⣿⣿⣿⣿⣿⠃", "   ⠘⢿⣿⣿⣷ ⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃", "    ⠈⠻⣿⣿⣤⣼⣿⣿⣿⣿⣿⢿⣿⡿⠛⠁", "       ⠉⠛⠿⠿⠿⠿⠷⠞⠛⠁", ""],
+];
+// Upright and smaller (32, 20, 12 dots): the medallion "flies" into the header.
+export const SHRINK = [
+    ["       ⢀⡀", "   ⢀⣴⣾⣿⣿⣿⣿⣷⣦⡀", "  ⣴⣿⣿⡟⠻⣿⣿⡿⠟⢿⣿⣆", " ⢠⣿⣿⡟⢠⡆⢹⡿ ⣶⣶⣿⣿⡄", " ⠘⣿⣿⠁⣠⣤ ⢧ ⠿⠟⣿⣿⡇", "  ⠹⣧⣴⣿⣿⣧⣼⣷⣤⣶⣿⡟", "   ⠙⠿⢿⣿⣿⣿⣿⣿⠟⠋", "       ⠉⠉"],
+    ["   ⣀⣤⣤⣀", " ⢰⣿⡟⢿⣿⠿⢿⡄", " ⣿⡟⢘⡈⡇⣾⢿⣿", " ⠹⣧⣿⣧⣷⣦⣾⠏", "  ⠈⠉⠛⠛⠋"],
+    [" ⣠⣴⣦⣄", "⠰⡟⡊⡳⢾⡆", " ⠙⠻⠟⠋"],
+];
+// 8×8 dots: the small mark in the header.
+export const ICON = ["⢠⡶⢶⡄", "⠘⠶⠾⠃"];

package/dist/cli/intro.js

@@ -0,0 +1,105 @@
+// The intro, after landing/preloader.js: the AC medallion spins, "AgentCollar" types itself
+// 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";
+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 };
+}
+// The whole animation as data: easy to test (duration, sizes) and to play.
+export function introTimeline() {
+    const upright = SPIN[0];
+    const frames = [];
+    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++)
+        frames.push(frame(upright, WORD.slice(0, i), 45)); // types
+    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)
+        frames.push(frame(smaller, "", 60)); // flies into the header
+    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.
+export function shouldShowIntro(c) {
+    if (c.noIntro || !c.stdoutTTY)
+        return false;
+    if (c.env.CI !== undefined || c.env.TERM === "dumb")
+        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;
+}
+// ANSI escape codes used below:
+//   ESC[?25l / ESC[?25h  hide / show the cursor
+//   ESC 7 / ESC 8        save / restore the cursor position
+//   ESC[2K               clear the current line
+//   ESC[J                clear from the cursor to the end of the screen
+//   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();
+    let skipped = false;
+    let ctrlC = false;
+    let wake = () => { };
+    const showCursor = () => out.write(`${ESC}[?25h`);
+    process.once("exit", showCursor); // even if something goes wrong, never leave the cursor hidden
+    const onKey = (key) => {
+        skipped = true;
+        ctrlC = key[0] === 3; // Ctrl+C
+        wake();
+    };
+    if (input.isTTY) {
+        input.setRawMode(true);
+        input.resume();
+        input.on("data", onKey);
+    }
+    // make room for the frames, go back up, and remember where the block starts
+    out.write(`${ESC}[?25l${"\n".repeat(HEIGHT)}${ESC}[${HEIGHT}A${ESC}7`);
+    const draw = (lines) => out.write(`${ESC}8${lines.map((line) => `${ESC}[2K${line}`).join("\n")}`);
+    for (const f of frames.slice(0, -1)) {
+        if (skipped)
+            break;
+        draw(f.lines);
+        await new Promise((resolve) => {
+            wake = resolve;
+            setTimeout(resolve, f.delayMs);
+        });
+    }
+    // the header stays; everything below it is cleared
+    const header = frames[frames.length - 1].lines.filter((line) => line !== "");
+    out.write(`${ESC}8${ESC}[J${header.join("\n")}\n\n`);
+    showCursor();
+    process.off("exit", showCursor);
+    if (input.isTTY) {
+        input.off("data", onKey);
+        input.setRawMode(false);
+        input.pause();
+    }
+    if (ctrlC)
+        process.exit(130);
+}
+// Shows the intro only when it makes sense (see shouldShowIntro).
+export async function maybeIntro(noIntro) {
+    const context = {
+        stdoutTTY: process.stdout.isTTY === true,
+        columns: process.stdout.columns ?? 0,
+        rows: process.stdout.rows ?? 0,
+        env: process.env,
+        noIntro,
+    };
+    if (shouldShowIntro(context))
+        await playIntro();
+}

package/dist/cli/logs.js

@@ -0,0 +1,46 @@
+// agentcollar logs [--agent <name>] [--denied] [--today] — the audit log, readable and filtered.
+import { readAuditLog } from "../audit-log.js";
+import { auditLogFile } from "../audit.js";
+import { formatEntry, isSameLocalDay } from "./format.js";
+export function parseLogsArgs(args) {
+    const filter = { agent: null, denied: false, today: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--denied")
+            filter.denied = true;
+        else if (arg === "--today")
+            filter.today = true;
+        else if (arg === "--agent") {
+            const name = args[++i];
+            if (name === undefined || name.startsWith("--"))
+                throw new Error("После --agent нужно имя: --agent <имя>");
+            filter.agent = name;
+        }
+        else
+            throw new Error(`Неизвестный флаг: ${arg}. Есть: --agent <имя>, --denied, --today`);
+    }
+    return filter;
+}
+export function filterEntries(entries, filter, now = new Date()) {
+    return entries.filter((entry) => (filter.agent === null || entry.agent === filter.agent) &&
+        (!filter.denied || !entry.allowed) &&
+        (!filter.today || isSameLocalDay(new Date(entry.time), now)));
+}
+export async function runLogs(args) {
+    let filter;
+    try {
+        filter = parseLogsArgs(args);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const entries = filterEntries(readAuditLog(auditLogFile), filter);
+    if (entries.length === 0) {
+        console.log("Записей нет.");
+        return 0;
+    }
+    for (const entry of entries)
+        console.log(formatEntry(entry, { showDate: !filter.today }));
+    return 0;
+}

package/dist/cli/main.js

@@ -0,0 +1,94 @@
+// agcl <command> [arguments] — one entry point for the broker. `agentcollar` is the same program:
+// 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";
+// 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-бота (мастер настройки)",
+        run: async () => (await import("./setup.js")).runSetup(),
+    },
+    server: {
+        usage: "agcl server",
+        summary: "запустить брокер на 127.0.0.1",
+        run: async () => {
+            await import("../server.js");
+            return forever();
+        },
+    },
+    watch: {
+        usage: "agcl watch",
+        summary: "живой экран: запросы агентов в реальном времени и 6 проверок",
+        run: async (args, flags) => {
+            await (await import("./intro.js")).maybeIntro(flags.noIntro);
+            return (await import("./watch.js")).runWatch(args);
+        },
+    },
+    mandates: {
+        usage: "agcl mandates",
+        summary: "мандаты запущенного брокера: статус, сколько осталось времени и действий",
+        run: async (args) => (await import("./mandates.js")).runMandates(args),
+    },
+    logs: {
+        usage: "agcl logs [--agent <имя>] [--denied] [--today]",
+        summary: "аудит-лог: кто, что, когда, разрешено или нет",
+        run: async (args) => (await import("./logs.js")).runLogs(args),
+    },
+    revoke: {
+        usage: "agcl revoke <id>",
+        summary: "мгновенно отозвать мандат (kill switch)",
+        run: async (args) => (await import("./revoke.js")).runRevoke(args),
+    },
+    mcp: {
+        usage: "agcl mcp",
+        summary: "MCP-сервер для Claude Code и других агентов (stdio)",
+        run: async () => {
+            await import("../mcp/server.js");
+            return forever();
+        },
+    },
+};
+export function parseCommand(argv) {
+    const flags = { noIntro: argv.includes("--no-intro") };
+    const [name, ...args] = argv.filter((word) => word !== "--no-intro");
+    if (name === undefined)
+        return { kind: "default", flags };
+    if (name === "help" || name === "--help" || name === "-h")
+        return { kind: "help" };
+    if (!Object.hasOwn(COMMANDS, name))
+        return { kind: "unknown", name };
+    return { kind: "run", name, args, flags };
+}
+function helpText() {
+    const width = Math.max(...Object.values(COMMANDS).map((c) => c.usage.length)) + 3;
+    const row = (left, right) => `  ${styleText("cyan", left.padEnd(width))}${right}`;
+    return [
+        `${styleText("bold", "AgentCollar")} — let agents work, keep the keys.`,
+        "",
+        row("agcl", "заставка → мастер настройки (если ещё не настроен) → брокер"),
+        ...Object.values(COMMANDS).map((c) => row(c.usage, c.summary)),
+        "",
+        row("--no-intro", "без заставки"),
+        row("-h, --help", "эта справка"),
+        "",
+        styleText("dim", "agcl — короткое имя agentcollar: agcl watch == agentcollar watch"),
+        styleText("dim", "Данные: ~/.agentcollar/ (папка доступна только тебе)"),
+    ].join("\n");
+}
+export async function runCli(argv) {
+    const parsed = parseCommand(argv);
+    switch (parsed.kind) {
+        case "default":
+            return (await import("./start.js")).runStart(parsed.flags);
+        case "help":
+            console.log(helpText());
+            return 0;
+        case "unknown":
+            console.error(`${styleText("red", `Неизвестная команда: ${parsed.name}`)}\n\n${helpText()}`);
+            return 1;
+        case "run":
+            return COMMANDS[parsed.name].run(parsed.args, parsed.flags);
+    }
+}