agentcollar 0.0.1 → 0.2.0

package/dist/cli/watch.js

@@ -0,0 +1,44 @@
+// 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 { fit, formatEntry, isToday, termWidth } 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(`agcl watch takes no arguments: ${args.join(" ")}`);
+        return 1;
+    }
+    console.log(`${styleText("bold", "AgentCollar · watch")}   ${styleText("dim", "Ctrl+C to quit")}`);
+    const legend = termWidth() >= 90
+        ? "checks: 1 token · 2 approved · 3 not expired · 4 not revoked · 5 action allowed · 6 limit"
+        : "✓✗· = checks: token, approved, time, revoked, action, limit";
+    console.log(styleText("dim", fit(legend, termWidth())));
+    const tail = createTail(auditLogFile);
+    const past = tail.readNew().slice(-RECENT);
+    if (past.length > 0) {
+        console.log(styleText("dim", "— recent —"));
+        past.forEach(print);
+    }
+    console.log(styleText("dim", "— live —"));
+    // 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: settings are still in broker/.env, run agcl setup to move them to ~/.agentcollar/");
+}

package/dist/gmail-fake.js

@@ -0,0 +1,26 @@
+// A pretend mailbox in memory: the broker uses it until you run `agcl gmail connect`.
+import { randomBytes } from "node:crypto";
+const newId = () => randomBytes(4).toString("hex");
+export function createFakeMailbox() {
+    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 = [];
+    return {
+        kind: "fake",
+        listInbox: async () => inbox,
+        async createDraft(to, subject, body) {
+            const draft = { id: newId(), to, subject, body };
+            drafts.push(draft);
+            return draft;
+        },
+        async sendEmail(to, subject, body) {
+            const email = { id: newId(), to, subject, body };
+            sent.push(email);
+            return email;
+        },
+    };
+}

package/dist/google/connection.js

@@ -0,0 +1,36 @@
+// Which mailbox the broker uses: your real Gmail if `agcl gmail connect` was done, otherwise the fake one.
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createFakeMailbox } from "../gmail-fake.js";
+import { ensureHome, gmailInfoFile, googleClientFile } from "../paths.js";
+import { createGmailMailbox } from "./gmail.js";
+import { keychain } from "./keychain.js";
+import { parseClientJson } from "./oauth.js";
+export const REFRESH_TOKEN_ACCOUNT = "gmail-refresh-token";
+export function readGmailInfo() {
+    if (!existsSync(gmailInfoFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(gmailInfoFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConnection(info, refreshToken, store = keychain) {
+    ensureHome();
+    store.set(REFRESH_TOKEN_ACCOUNT, refreshToken); // the secret goes to the Keychain…
+    writeFileSync(gmailInfoFile, JSON.stringify(info, null, 2), { mode: 0o600 }); // …the file has only the address
+}
+export function forgetConnection(store = keychain) {
+    const token = store.get(REFRESH_TOKEN_ACCOUNT);
+    store.remove(REFRESH_TOKEN_ACCOUNT);
+    if (existsSync(gmailInfoFile))
+        unlinkSync(gmailInfoFile);
+    return token;
+}
+export function loadMailbox(store = keychain) {
+    const refreshToken = store.get(REFRESH_TOKEN_ACCOUNT);
+    if (refreshToken === null || !existsSync(googleClientFile))
+        return createFakeMailbox();
+    return createGmailMailbox(parseClientJson(readFileSync(googleClientFile, "utf8")), refreshToken);
+}

package/dist/google/gmail.js

@@ -0,0 +1,73 @@
+// Your real Gmail, through the Gmail API. Same shape as the fake mailbox, so the broker does not care
+// which one it talks to. The broker calls these ONLY after check() said yes.
+import { isEmailAddress } from "../mailbox.js";
+import { refreshAccessToken } from "./oauth.js";
+const API = "https://gmail.googleapis.com/gmail/v1/users/me";
+// Builds the email in the format Gmail expects ("raw" = base64url of the whole message).
+// The subject comes from an agent, so line breaks are removed: otherwise "Hi\r\nBcc: thief@evil"
+// would add a hidden recipient (header injection).
+export function buildRawEmail(to, subject, body) {
+    if (!isEmailAddress(to))
+        throw new Error(`"to" must be one email address, got: ${JSON.stringify(to)}`);
+    const cleanSubject = subject.replace(/[\r\n]+/g, " ").trim();
+    // non-ASCII subjects are encoded (RFC 2047) so every mail client shows them correctly
+    const encodedSubject = /^[\x20-\x7e]*$/.test(cleanSubject)
+        ? cleanSubject
+        : `=?UTF-8?B?${Buffer.from(cleanSubject, "utf8").toString("base64")}?=`;
+    const message = [
+        `To: ${to}`,
+        `Subject: ${encodedSubject}`,
+        "MIME-Version: 1.0",
+        'Content-Type: text/plain; charset="UTF-8"',
+        "Content-Transfer-Encoding: base64",
+        "",
+        Buffer.from(body, "utf8").toString("base64"),
+    ].join("\r\n");
+    return Buffer.from(message, "utf8").toString("base64url");
+}
+export function createGmailMailbox(client, refreshToken) {
+    // The access token lives only in this process's memory, never on disk.
+    let accessToken = "";
+    let expiresAt = 0;
+    async function token() {
+        if (Date.now() > expiresAt - 60_000) {
+            const fresh = await refreshAccessToken(client, refreshToken);
+            accessToken = fresh.accessToken;
+            expiresAt = fresh.expiresAt;
+        }
+        return accessToken;
+    }
+    async function api(method, path, body) {
+        const response = await fetch(API + path, {
+            method,
+            headers: { authorization: `Bearer ${await token()}`, "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = (await response.json());
+        if (!response.ok)
+            throw new Error(`Gmail API: ${data.error?.message ?? response.status}`);
+        return data;
+    }
+    return {
+        kind: "gmail",
+        async listInbox() {
+            const list = await api("GET", "/messages?labelIds=INBOX&maxResults=10");
+            const ids = (list.messages ?? []).map((m) => m.id);
+            return Promise.all(ids.map(async (id) => {
+                const m = await api("GET", `/messages/${id}?format=metadata&metadataHeaders=From&metadataHeaders=Subject`);
+                const headers = m.payload?.headers ?? [];
+                const header = (name) => headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+                return { id, from: header("From"), subject: header("Subject"), body: String(m.snippet ?? "") };
+            }));
+        },
+        async createDraft(to, subject, body) {
+            const draft = await api("POST", "/drafts", { message: { raw: buildRawEmail(to, subject, body) } });
+            return { id: String(draft.id), to, subject, body };
+        },
+        // AgentCollar asks Google only for read + create drafts, so this connection cannot send.
+        // Even a mandate with gmail.send ends here: the email stays a draft for you to send yourself.
+        async sendEmail() {
+            throw new Error("This Gmail connection cannot send: AgentCollar only has read + create-drafts access. Create a draft instead; the human sends it.");
+        },
+    };
+}

package/dist/google/keychain.js

@@ -0,0 +1,40 @@
+// Secrets in the macOS Keychain (encrypted by macOS, outside the repo and outside ~/.agentcollar/),
+// through the built-in `security` tool. Used for the Gmail refresh token.
+// Honest limit: other programs running as YOUR macOS user can also ask `security` for it.
+// The Keychain protects against leaks through files, backups and git, not against malware you run.
+import { execFileSync } from "node:child_process";
+const SERVICE = "agentcollar";
+export const keychain = {
+    get(account) {
+        try {
+            return execFileSync("security", ["find-generic-password", "-s", SERVICE, "-a", account, "-w"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trimEnd();
+        }
+        catch {
+            return null; // not there (or not macOS)
+        }
+    },
+    set(account, value) {
+        // -U: update if it already exists
+        execFileSync("security", ["add-generic-password", "-U", "-s", SERVICE, "-a", account, "-w", value], { stdio: "ignore" });
+    },
+    remove(account) {
+        try {
+            execFileSync("security", ["delete-generic-password", "-s", SERVICE, "-a", account], { stdio: "ignore" });
+        }
+        catch {
+            // already gone
+        }
+    },
+};
+// For tests: the same interface, kept in memory.
+export function memoryStore() {
+    const values = new Map();
+    return {
+        get: (account) => values.get(account) ?? null,
+        set: (account, value) => void values.set(account, value),
+        remove: (account) => void values.delete(account),
+    };
+}

package/dist/google/oauth.js

@@ -0,0 +1,134 @@
+// Google sign-in for a desktop program (OAuth 2.0 "installed app" flow with PKCE):
+// we open Google's consent page in your browser, Google sends the browser back to a tiny
+// server on 127.0.0.1 with a one-time code, and we swap that code for tokens.
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+// Read + create drafts, nothing more. gmail.drafts.create cannot send: so sending is blocked twice,
+// by the broker (no mandate, no send) AND by Google (this connection has no right to send at all).
+export const SCOPES = ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.drafts.create"];
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+// The JSON file you download from Google Cloud → Clients → Desktop app.
+export function parseClientJson(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error("This is not a Google client_secret JSON file.");
+    }
+    if (data.web !== undefined)
+        throw new Error("This client is a Web app. Create a client of type Desktop app instead.");
+    const installed = data.installed;
+    if (typeof installed?.client_id !== "string" || typeof installed.client_secret !== "string") {
+        throw new Error("This is not a Google client_secret JSON file (no installed.client_id).");
+    }
+    return { clientId: installed.client_id, clientSecret: installed.client_secret };
+}
+// PKCE: we keep a random secret (verifier) and send Google only its hash (challenge).
+// A stolen code is useless without the verifier, which never leaves this process.
+export function newPkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+export function buildAuthUrl(client, redirectUri, challenge, state) {
+    const url = new URL(AUTH_URL);
+    url.search = new URLSearchParams({
+        client_id: client.clientId,
+        redirect_uri: redirectUri,
+        response_type: "code",
+        scope: SCOPES.join(" "),
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        state, // a random value: proves the answer belongs to OUR request
+        access_type: "offline", // we want a refresh token
+        prompt: "consent", // always show what is being granted (and always return a refresh token)
+    }).toString();
+    return url.toString();
+}
+async function postToken(params) {
+    const response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+    });
+    const data = (await response.json());
+    if (!response.ok) {
+        if (data.error === "invalid_grant") {
+            throw new Error("Google no longer accepts this sign-in (in Testing mode it expires after 7 days). Run: agcl gmail connect");
+        }
+        throw new Error(`Google sign-in failed: ${String(data.error_description ?? data.error ?? response.status)}`);
+    }
+    return data;
+}
+export async function exchangeCode(client, code, verifier, redirectUri) {
+    const data = await postToken({
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        code,
+        code_verifier: verifier,
+        redirect_uri: redirectUri,
+        grant_type: "authorization_code",
+    });
+    if (typeof data.refresh_token !== "string")
+        throw new Error("Google did not return a refresh token. Run agcl gmail connect again.");
+    return {
+        accessToken: String(data.access_token),
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000,
+    };
+}
+// The access token lives about an hour and only in memory; the refresh token gets a new one.
+export async function refreshAccessToken(client, refreshToken) {
+    const data = await postToken({
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        refresh_token: refreshToken,
+        grant_type: "refresh_token",
+    });
+    return { accessToken: String(data.access_token), expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000 };
+}
+export async function revokeToken(token) {
+    await fetch(`https://oauth2.googleapis.com/revoke?token=${encodeURIComponent(token)}`, { method: "POST" }).catch(() => { });
+}
+// Starts the loopback server, opens the consent page, waits (up to 5 minutes) for Google's redirect.
+export function authorizeInBrowser(client, openUrl, timeoutMs = 5 * 60 * 1000) {
+    const { verifier, challenge } = newPkce();
+    const state = randomBytes(16).toString("hex");
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            if (url.searchParams.get("state") !== state) {
+                res.writeHead(400, { "content-type": "text/plain" }).end("This sign-in answer does not belong to AgentCollar's request.");
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (code === null) {
+                res.writeHead(400, { "content-type": "text/plain" }).end(`Google sign-in was cancelled: ${url.searchParams.get("error") ?? "no code"}`);
+                finish(() => reject(new Error("Google sign-in was cancelled.")));
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end("<!doctype html><title>AgentCollar</title><body style=\"font-family:system-ui;padding:3rem\">" +
+                "<h1>AgentCollar is connected to Gmail.</h1><p>You can close this tab and go back to the terminal.</p>");
+            finish(() => resolve({ code, verifier, redirectUri }));
+        });
+        let redirectUri = "";
+        const timer = setTimeout(() => finish(() => reject(new Error("No answer from Google in 5 minutes."))), timeoutMs);
+        function finish(then) {
+            clearTimeout(timer);
+            server.close();
+            then();
+        }
+        // port 0 = any free port; 127.0.0.1 = reachable only from this computer
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            redirectUri = `http://127.0.0.1:${port}/callback`;
+            openUrl(buildAuthUrl(client, redirectUri, challenge, state));
+        });
+    });
+}

package/dist/mailbox.js

@@ -0,0 +1,4 @@
+// One plain address: no commas (several recipients), no spaces or line breaks (header injection).
+export function isEmailAddress(text) {
+    return /^[^\s@<>,;"()]+@[^\s@<>,;"()]+\.[^\s@<>,;"()]+$/.test(text);
+}

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,73 @@
+// 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. Then call mandate_status once with waitSeconds: 90 (it returns as soon " +
+    "as the human decides) and, if approved, 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}`);