baychat 0.1.0 → 0.3.0

package/README.md

@@ -30,6 +30,7 @@ per session, never one that another integration already uses.
 |---------|-------------|
 | `baychat pair <code> [--base <url>]` | Redeem a pairing code and store credentials |
 | `baychat whoami` | Show the connected agent identity |
+| `baychat qr [<conv>]` | Render this agent's connection QR right in the terminal — scan it with BuzzRelay or any BayChat-aware app |
 | `baychat conversations` | List conversations this agent participates in |
 | `baychat send <conv> <text>` | Send a message |
 | `baychat check <conv>` | Print messages since the last check (cursor-based) |
@@ -69,6 +70,6 @@ watching when the user asks you to leave the chat.
 
 ## Requirements
 
-Node.js ≥ 20. Zero runtime dependencies.
+Node.js ≥ 20. One runtime dependency (`qrcode`, pure JS).
 
 MIT © BayChat

package/dist/api.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
 exports.apiRequest = apiRequest;
+exports.fetchContext = fetchContext;
 exports.pairRequest = pairRequest;
 class ApiError extends Error {
     status;
@@ -36,6 +37,24 @@ async function apiRequest(creds, method, apiPath, body) {
         throw await parseError(res);
     return (await res.json());
 }
+/**
+ * Fetch the Agent Context Contract v2 block for a conversation.
+ * Fail-soft: a v1 server has no `/context` endpoint and 404s — we return null
+ * so the caller keeps behaving like today. Other failures are logged (house
+ * rule: never swallow errors silently) and also downgrade to null rather than
+ * blocking the watch/check loop on a best-effort roster lookup.
+ */
+async function fetchContext(creds, conversationId) {
+    try {
+        return await apiRequest(creds, "GET", `/api/agent-api/conversations/${conversationId}/context`);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null; // old server / not a participant view
+        console.error(`baychat: context lookup failed (${err instanceof Error ? err.message : String(err)}) — using id fallbacks`);
+        return null;
+    }
+}
 async function pairRequest(baseUrl, code) {
     const res = await fetch(`${baseUrl}/api/agent-api/pair`, {
         method: "POST",

package/dist/commands.js

@@ -1,14 +1,22 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requireCredentials = requireCredentials;
 exports.cmdPair = cmdPair;
 exports.cmdWhoami = cmdWhoami;
 exports.cmdConversations = cmdConversations;
 exports.cmdSend = cmdSend;
+exports.resetSessionState = resetSessionState;
 exports.cmdCheck = cmdCheck;
 exports.cmdWatch = cmdWatch;
+exports.cmdQr = cmdQr;
+const qrcode_1 = __importDefault(require("qrcode"));
 const api_1 = require("./api");
+const connection_qr_1 = require("./connection-qr");
 const config_1 = require("./config");
+const context_1 = require("./context");
 const DEFAULT_BASE_URL = "https://api.baychat.io";
 function requireCredentials() {
     const creds = (0, config_1.loadCredentials)();
@@ -54,10 +62,58 @@ async function agentNameMap(creds) {
         return new Map(); // name resolution is best-effort; fall back to ids
     }
 }
-function senderLabel(m, names) {
-    if (m.senderType === "AGENT")
-        return names.get(m.senderId) ?? `agent:${m.senderId.slice(0, 8)}`;
-    return `user:${m.senderId.slice(0, 8)}`;
+/**
+ * Render one message line, v2-aware:
+ *   [HH:MM] Name (member|admin|agent|orchestrator): text  → you should respond
+ * Name resolution order: payload `sender.name` → cached context roster →
+ * best-effort `/agents` map (v1) → `user:`/`agent:<id8>` fallback.
+ */
+function renderMessageLine(m, roster, agentNames, ownId) {
+    const rp = roster.get(m.senderId);
+    const kind = m.sender?.kind ?? rp?.kind ?? (m.senderType === "AGENT" ? "agent" : "user");
+    const fallback = (0, context_1.idFallback)(kind, m.senderId);
+    const name = m.sender?.name ?? rp?.name ?? agentNames.get(m.senderId) ?? fallback;
+    const word = (0, context_1.roleWord)({
+        kind,
+        role: m.sender?.role ?? rp?.role ?? null,
+        isOrchestrator: rp?.isOrchestrator ?? false,
+    });
+    let line = `[${(0, context_1.formatClock)(m.createdAt)}] ${name} (${word}): ${m.content}`;
+    // Routing markers computed by the server for THIS agent (spec §2/§3).
+    if (m.shouldRespond === true)
+        line += "  → you should respond";
+    else if (Array.isArray(m.mentions) && m.mentions.includes(ownId))
+        line += "  → you were mentioned";
+    return line;
+}
+// Whether every fresh message can already be named without a context refresh.
+function allSendersResolvable(messages, roster, agentNames) {
+    return messages.every((m) => Boolean(m.sender?.name) || roster.has(m.senderId) || agentNames.has(m.senderId));
+}
+// ─── Per-process session caches ───────────────────────────────────────────
+// The watch loop calls cmdCheck repeatedly in one process, so cache the v2
+// context and only print the roster header once per conversation.
+const contextCache = new Map();
+const headerPrinted = new Set();
+async function ensureContext(creds, conversationId, force = false) {
+    if (!force && contextCache.has(conversationId))
+        return contextCache.get(conversationId) ?? null;
+    const ctx = await (0, api_1.fetchContext)(creds, conversationId);
+    if (ctx)
+        contextCache.set(conversationId, ctx);
+    return ctx;
+}
+function maybePrintHeader(conversationId, ctx, creds) {
+    if (!ctx || headerPrinted.has(conversationId))
+        return;
+    headerPrinted.add(conversationId);
+    console.log((0, context_1.rosterHeader)(ctx, creds.agent.name));
+}
+/** Reset per-process session state — for tests, and harmless in normal use. */
+function resetSessionState() {
+    contextCache.clear();
+    headerPrinted.clear();
+    resolvedEnvAgentId = null;
 }
 // The BAYCHAT_TOKEN env path can't know the agent id up front, so config.ts
 // returns the sentinel "env". Resolve it to the real id via /me once per process
@@ -75,6 +131,10 @@ async function ownAgentId(creds) {
 async function cmdCheck(conversationId) {
     const creds = requireCredentials();
     const cursor = (0, config_1.loadCursor)(conversationId);
+    // Fetch the v2 context (roster/policy/you) and print the roster header once.
+    // Fail-soft: on a v1 server fetchContext returns null and we behave like today.
+    const startCtx = await ensureContext(creds, conversationId);
+    maybePrintHeader(conversationId, startCtx, creds);
     if (!cursor) {
         // First check: don't dump history. Anchor the cursor at "now"; only
         // messages sent after this moment will be reported.
@@ -83,7 +143,13 @@ async function cmdCheck(conversationId) {
         console.log(`Watching ${conversationId} from ${now}. Run check/watch again for new messages.`);
         return 0;
     }
-    const { messages } = await (0, api_1.apiRequest)(creds, "GET", `/api/agent-api/conversations/${conversationId}/messages?since=${encodeURIComponent(cursor)}`);
+    const res = await (0, api_1.apiRequest)(creds, "GET", `/api/agent-api/conversations/${conversationId}/messages?since=${encodeURIComponent(cursor)}`);
+    const messages = res.messages;
+    // The v2 poll envelope carries a fresh context block — cache it for free. The header was
+    // already printed from the start-of-check context (or stays unprinted on a v1 server).
+    if (res.context) {
+        contextCache.set(conversationId, res.context);
+    }
     const ownId = await ownAgentId(creds);
     const fresh = messages.filter((m) => !m.deletedAt && m.senderId !== ownId);
     if (messages.length > 0) {
@@ -91,9 +157,22 @@ async function cmdCheck(conversationId) {
     }
     if (fresh.length === 0)
         return 0;
-    const names = await agentNameMap(creds);
+    const cachedContext = contextCache.get(conversationId) ?? null;
+    let roster = (0, context_1.rosterFromContext)(cachedContext);
+    // v1 fallback: without a v2 roster, resolve agent names via /agents (humans
+    // stay opaque as they did before). On v2 the roster already has everyone.
+    const agentNames = cachedContext
+        ? new Map()
+        : await agentNameMap(creds);
+    // An unknown sender means the roster is stale (someone just joined) — refresh
+    // the context once and re-index before rendering.
+    if (!allSendersResolvable(fresh, roster, agentNames)) {
+        const refreshed = await ensureContext(creds, conversationId, true);
+        if (refreshed)
+            roster = (0, context_1.rosterFromContext)(refreshed);
+    }
     for (const m of fresh) {
-        console.log(`[${m.createdAt}] ${senderLabel(m, names)}: ${m.content}`);
+        console.log(renderMessageLine(m, roster, agentNames, ownId));
     }
     return fresh.length;
 }
@@ -117,3 +196,17 @@ async function cmdWatch(conversationId, opts = {}) {
     console.log("No new messages before timeout.");
     return false;
 }
+async function cmdQr(conversationId) {
+    const creds = requireCredentials();
+    // The QR carries this agent's API URL + token (baychat.connection v1) — the
+    // same contract the app's "Show QR" renders. Never print the raw token.
+    const payload = (0, connection_qr_1.buildBayChatConnectionQrPayload)({
+        apiBaseUrl: creds.baseUrl,
+        apiToken: creds.token,
+        conversationId: conversationId ?? null,
+    });
+    const ascii = await qrcode_1.default.toString(payload, { type: "terminal", small: true, errorCorrectionLevel: "M" });
+    console.log(ascii);
+    console.log("Scan with a BayChat-aware app (e.g. BuzzRelay settings).");
+    console.log("⚠ This code contains this agent's API token — only show it to scanners you trust.");
+}

package/dist/connection-qr.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBayChatConnectionQrPayload = buildBayChatConnectionQrPayload;
+function normalizePublicHttpsUrl(value) {
+    const parsed = new URL(value.trim());
+    if (parsed.protocol !== "https:") {
+        throw new Error("BayChat connection QR requires a public HTTPS API URL");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/$/, "");
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, "");
+}
+function buildBayChatConnectionQrPayload({ apiBaseUrl, apiToken, conversationId, }) {
+    const token = apiToken.trim();
+    if (!/^bay_[A-Za-z0-9._-]+$/.test(token)) {
+        throw new Error("A valid BayChat Agent API token is required");
+    }
+    const connection = {
+        api_base_url: normalizePublicHttpsUrl(apiBaseUrl),
+        api_token: token,
+    };
+    const normalizedConversationId = conversationId?.trim();
+    if (normalizedConversationId) {
+        connection.conversation_id = normalizedConversationId;
+    }
+    const payload = {
+        type: "baychat.connection",
+        version: 1,
+        connection,
+    };
+    return JSON.stringify(payload);
+}

package/dist/context.js

@@ -0,0 +1,105 @@
+"use strict";
+// Agent Context Contract v2 — client-side types and pure formatting helpers.
+//
+// Every field the server added in v2 is OPTIONAL here: a v1 server (today's
+// deployment) never sends `sender`, `mentions`, `shouldRespond`, or the
+// `context` envelope, and the `/context` endpoint 404s. All rendering must
+// degrade gracefully to the v1 behavior (id-prefix fallbacks) when they are
+// absent. Keep this module free of I/O so it stays trivially testable.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rosterFromContext = rosterFromContext;
+exports.roleWord = roleWord;
+exports.formatClock = formatClock;
+exports.replyModeLabel = replyModeLabel;
+exports.idFallback = idFallback;
+exports.rosterHeader = rosterHeader;
+/** Index a context's participants by id for O(1) sender resolution. */
+function rosterFromContext(ctx) {
+    const map = new Map();
+    for (const p of ctx?.participants ?? [])
+        map.set(p.id, p);
+    return map;
+}
+/**
+ * The single conversation-role word shown after a name — one of
+ * `orchestrator` | `agent` | `admin` | `member`. Orchestrator wins over kind,
+ * kind (agent) wins over role, then admin, else member.
+ */
+function roleWord(entry) {
+    if (entry.isOrchestrator)
+        return "orchestrator";
+    if (entry.kind === "agent")
+        return "agent";
+    if (entry.role === "ADMIN")
+        return "admin";
+    return "member";
+}
+/** `[HH:MM]` local-time clock; falls back to the raw string if unparseable. */
+function formatClock(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    return `${hh}:${mm}`;
+}
+/** Human-friendly reply-mode label from the raw AgentReplyPolicy enum. */
+function replyModeLabel(policy) {
+    switch (policy) {
+        case "ORCHESTRATOR":
+            return "Orchestrator";
+        case "DEDICATED":
+            return "Dedicated";
+        case "MENTIONS":
+            return "Mentions";
+        case "ROUTER":
+            return "Router";
+        default:
+            return policy ?? "Default";
+    }
+}
+/** The `user:`/`agent:<id8>` display fallback when no name is known. Shared so the roster
+ * header and per-message rendering produce the identical string for an unnamed sender. */
+function idFallback(kind, id) {
+    return `${kind === "agent" ? "agent" : "user"}:${id.slice(0, 8)}`;
+}
+function displayName(p) {
+    return p.name ?? idFallback(p.kind, p.id);
+}
+/**
+ * The roster header printed once when a session starts watching/checking a
+ * conversation, e.g.
+ *
+ *   You are "Claude-Terminal" (orchestrator) in "Project X" — members:
+ *   Karmen (admin), Manuel, BuzzRelay (agent). Reply mode: Orchestrator,
+ *   max agent rounds: 2.
+ *
+ * `selfName` is the fallback for the "you are" name when the roster does not
+ * carry the current agent (should not happen, but never block on it).
+ */
+function rosterHeader(ctx, selfName) {
+    const participants = ctx.participants ?? [];
+    const youId = ctx.you?.agentId;
+    const self = youId ? participants.find((p) => p.id === youId) : undefined;
+    const youName = self?.name ?? selfName;
+    const youRole = ctx.you?.isOrchestrator ? "orchestrator" : roleWord(self ?? { kind: "agent" });
+    const title = ctx.conversation?.title ?? "this conversation";
+    const others = participants.filter((p) => p.id !== youId);
+    const memberList = others
+        .map((p) => {
+        const word = roleWord(p);
+        return word === "member" ? displayName(p) : `${displayName(p)} (${word})`;
+    })
+        .join(", ");
+    let header = `You are "${youName}" (${youRole}) in "${title}"`;
+    header += memberList ? ` — members: ${memberList}.` : ".";
+    const policy = ctx.policy;
+    if (policy?.agentReplyPolicy) {
+        header += ` Reply mode: ${replyModeLabel(policy.agentReplyPolicy)}`;
+        if (typeof policy.maxAgentRounds === "number") {
+            header += `, max agent rounds: ${policy.maxAgentRounds}`;
+        }
+        header += ".";
+    }
+    return header;
+}

package/dist/index.js

@@ -10,6 +10,7 @@ Usage:
   baychat conversations                 List conversations this agent is in
   baychat send <conversationId> <text>  Send a message
   baychat check <conversationId>        Print messages since the last check
+  baychat qr [<conversationId>]         Render this agent's connection QR in the terminal
   baychat watch <conversationId> [--interval <sec>] [--timeout <sec>]
                                         Block until new messages arrive (exit 0)
                                         or timeout (exit 2)
@@ -30,6 +31,9 @@ async function main() {
             await (0, commands_1.cmdPair)(args[0], flag(args, "--base"));
             return 0;
         }
+        case "qr":
+            await (0, commands_1.cmdQr)(args[0]);
+            return 0;
         case "whoami":
             await (0, commands_1.cmdWhoami)();
             return 0;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "baychat",
-  "version": "0.1.0",
-  "description": "BayChat connector CLI \u2014 pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
+  "version": "0.3.0",
+  "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
-    "baychat": "./dist/index.js"
+    "baychat": "dist/index.js"
   },
   "main": "dist/index.js",
   "engines": {
@@ -15,6 +15,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "devDependencies": {
+    "@types/qrcode": "^1.5.6",
     "typescript": "^5.7.3",
     "vitest": "^4.1.10"
   },
@@ -34,5 +35,8 @@
     "dist",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  }
+}