baychat 0.24.0 → 0.25.0

package/dist/context-report.js

@@ -0,0 +1,307 @@
+"use strict";
+// How full is an attached agent's context — measured on this machine, reported to BayChat.
+//
+// Three sources feed this module, and each is the runtime's OWN number, never a guess:
+//
+//   • Claude Code — the status-line JSON (`context_window.*`) and the PreCompact/PostCompact
+//     hooks, read by `claude-context.ts` in a process of its own.
+//   • Codex — the `token_count` events in the session's rollout JSONL, tailed by the relay
+//     (`relay/codex-context.ts`).
+//   • ACP agents (dsh, Cursor) — the standard `session/update` → `usage_update { used, size }`,
+//     which the relay used to throw away (`relay/acp/client.ts`).
+//
+// All three become ONE body (contract §7) and go out through ONE function. What this module
+// guarantees, and what every caller relies on:
+//
+//   1. IT NEVER THROWS INTO A CALLER. A context report is a nicety riding beside the relay's
+//      real job (waking sessions); a failure here must never cost a delivery. Failures are
+//      LOGGED — never swallowed — and repeated failures are logged once, not once per sample.
+//   2. IT IS CHEAP. "usage" is throttled: at most one every 15 s per session, sooner only when
+//      the fill moved by a whole percentage point. Compaction events are never throttled.
+//   3. IT IS HARMLESS AGAINST A SERVER THAT DOES NOT HAVE THE ROUTE YET. A 404 with no error
+//      `code` is Express's "no such route" — phase 2 not deployed — and the reporter goes quiet
+//      for an hour instead of sending a doomed request every 15 seconds. A 404 WITH a code
+//      (`SESSION_NOT_FOUND`) is a real refusal about one session and backs off only that one.
+//
+// THE CREDENTIAL. The relay holds a DEVICE credential (`bay_u_…`); a session agent has no token
+// of its own (REMOTE_MCP_SESSIONS.md: "An agent with a sessionKey has no apiToken"). So a device
+// posts to the device surface and names the session, exactly as `/approvals` and the relay's
+// command replies do; an agent token (a standing agent) posts to the agent surface as itself.
+// Recorded in the contract's CHANGES, 2026-09-26.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextReporter = exports.SESSION_REFUSED_BACKOFF_MS = exports.NOT_DEPLOYED_BACKOFF_MS = exports.USAGE_MIN_STEP_PERCENT = exports.USAGE_MIN_INTERVAL_MS = void 0;
+exports.usageDue = usageDue;
+exports.claudeUsageFromStatus = claudeUsageFromStatus;
+exports.claudeAutoCompactAt = claudeAutoCompactAt;
+exports.codexUsageFromTokenCount = codexUsageFromTokenCount;
+exports.codexAutoCompactAt = codexAutoCompactAt;
+exports.acpUsageFromUpdate = acpUsageFromUpdate;
+exports.isDeviceCredential = isDeviceCredential;
+exports.postContextEvent = postContextEvent;
+const api_1 = require("./api");
+// ─── Throttle ────────────────────────────────────────────────────────────────
+exports.USAGE_MIN_INTERVAL_MS = 15_000;
+exports.USAGE_MIN_STEP_PERCENT = 1;
+/** How long a server without the route is left alone. */
+exports.NOT_DEPLOYED_BACKOFF_MS = 60 * 60_000;
+/** How long one session the server refused (ended, not live) is left alone. */
+exports.SESSION_REFUSED_BACKOFF_MS = 5 * 60_000;
+/**
+ * Is this usage sample worth a request?
+ *
+ * Yes when nothing was sent yet, when the window itself changed (a model switch), or when the
+ * fill moved by a whole percentage point. Otherwise yes only once 15 s have passed AND the
+ * number actually moved — a session sitting idle at 43 % sends nothing at all.
+ */
+function usageDue(prev, next, now) {
+    if (!prev)
+        return true;
+    if (prev.size !== next.size || prev.autoCompactAt !== next.autoCompactAt)
+        return true;
+    const step = next.size > 0 ? (Math.abs(next.used - prev.used) / next.size) * 100 : 0;
+    if (step >= exports.USAGE_MIN_STEP_PERCENT)
+        return true;
+    return next.used !== prev.used && now - prev.at >= exports.USAGE_MIN_INTERVAL_MS;
+}
+// ─── Normalisers: one per source ─────────────────────────────────────────────
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const count = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.round(v) : undefined;
+/**
+ * Claude Code's status-line JSON → a sample, or null when it carries none yet.
+ *
+ * `current_usage` is the exact per-call count and is preferred; `used` is input + cache writes +
+ * cache reads — the same input-only formula Claude Code's own `used_percentage` uses (docs:
+ * "It does not include output_tokens"). It is null before the first API call and again right
+ * after `/compact`, and then `used_percentage` is the fallback. Neither → null, never a zero:
+ * "no number yet" and "empty" are different claims.
+ */
+function claudeUsageFromStatus(status) {
+    if (!isRecord(status) || !isRecord(status.context_window))
+        return null;
+    const cw = status.context_window;
+    const size = count(cw.context_window_size);
+    if (!size)
+        return null;
+    const cu = cw.current_usage;
+    if (isRecord(cu)) {
+        const parts = [cu.input_tokens, cu.cache_creation_input_tokens, cu.cache_read_input_tokens].map(count);
+        if (parts.every((p) => p !== undefined))
+            return { used: parts.reduce((a, b) => a + b, 0), size };
+    }
+    const pct = typeof cw.used_percentage === "number" && Number.isFinite(cw.used_percentage) ? cw.used_percentage : undefined;
+    if (pct === undefined)
+        return null;
+    return { used: Math.round((Math.max(0, pct) / 100) * size), size };
+}
+/**
+ * Where Claude Code will compact on its own.
+ *
+ * Documented (model-config, "Default auto-compact thresholds"): an explicit window —
+ * `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, else the `autoCompactWindow` setting — capped at the model's
+ * window; otherwise about 967K on a native 1M window and the window itself below that.
+ */
+function claudeAutoCompactAt(size, override) {
+    if (override && override > 0)
+        return Math.min(Math.round(override), size);
+    return size >= 1_000_000 ? 967_000 : size;
+}
+/**
+ * A Codex rollout `event_msg` whose payload is `token_count` → a sample.
+ *
+ * `info.last_token_usage` is the LAST request — what is in the window now. `total_token_usage`
+ * is cumulative across the whole thread (13M on a real rollout against a 258K window) and must
+ * never be used; neither must `codex exec --json`'s totals, which are cumulative too.
+ */
+function codexUsageFromTokenCount(payload) {
+    if (!isRecord(payload) || payload.type !== "token_count" || !isRecord(payload.info))
+        return null;
+    const last = payload.info.last_token_usage;
+    const size = count(payload.info.model_context_window);
+    if (!isRecord(last) || !size)
+        return null;
+    const total = count(last.total_tokens);
+    const used = total ?? (count(last.input_tokens) ?? 0) + (count(last.output_tokens) ?? 0);
+    return { used, size };
+}
+/** Codex compacts on its own at about 90 % of the window (contract §7). */
+function codexAutoCompactAt(size) {
+    return Math.floor(size * 0.9);
+}
+/** ACP `usage_update { used, size }` → a sample. */
+function acpUsageFromUpdate(update) {
+    if (!isRecord(update))
+        return null;
+    const used = count(update.used);
+    const size = count(update.size);
+    return used !== undefined && size ? { used, size } : null;
+}
+/** A device credential names the session; an agent token IS the agent. */
+function isDeviceCredential(auth) {
+    return auth.token.startsWith("bay_u_");
+}
+/**
+ * POST one event. NEVER THROWS — every failure is an outcome.
+ *
+ * `session` is required on the device route (a device owns several sessions and the server must
+ * never pick one for us); on the agent route it is not sent at all.
+ */
+async function postContextEvent(auth, session, event, request = api_1.apiRequest) {
+    try {
+        if (isDeviceCredential(auth)) {
+            if (!session)
+                return { kind: "refused", status: 0, message: "no session named for a device report" };
+            await request(auth, "POST", "/api/device-api/context", { session, ...event });
+        }
+        else {
+            await request(auth, "POST", "/api/agent-api/context", event);
+        }
+        return { kind: "sent" };
+    }
+    catch (err) {
+        if (err instanceof api_1.ApiError) {
+            // Express's own 404 carries no JSON envelope, so no code: the route does not exist here.
+            if (err.status === 404 && !err.code)
+                return { kind: "not-deployed" };
+            if (err.status >= 400 && err.status < 500 && err.status !== 429) {
+                return { kind: "refused", status: err.status, code: err.code, message: err.message };
+            }
+        }
+        return { kind: "failed", message: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Throttles, sends and backs off, per session, in the relay's process.
+ *
+ * `report` returns immediately and never throws; `idle()` resolves when everything queued has
+ * been attempted (tests, and a clean shutdown).
+ */
+class ContextReporter {
+    deps;
+    sessions = new Map();
+    notDeployedUntil = 0;
+    closed = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() {
+        return (this.deps.now ?? Date.now)();
+    }
+    state(session) {
+        let s = this.sessions.get(session);
+        if (!s) {
+            s = { chain: Promise.resolve() };
+            this.sessions.set(session, s);
+        }
+        return s;
+    }
+    report(session, event) {
+        try {
+            if (this.closed)
+                return;
+            const s = this.state(session);
+            if (event.event === "usage") {
+                if (event.used === undefined || event.size === undefined)
+                    return;
+                const sample = { used: event.used, size: event.size, autoCompactAt: event.autoCompactAt };
+                if (!usageDue(s.sent, sample, this.now())) {
+                    this.holdTrailing(session, s, event);
+                    return;
+                }
+                s.timer?.cancel();
+                s.timer = undefined;
+                s.trailing = undefined;
+                // Counted as sent when it is QUEUED, so a burst of samples cannot all pass the throttle
+                // while the first request is still in flight.
+                s.sent = { ...sample, at: this.now() };
+            }
+            else {
+                // A compaction resets the baseline: the next usage is the "after" number and must go.
+                s.sent = undefined;
+                s.trailing = undefined;
+                s.timer?.cancel();
+                s.timer = undefined;
+            }
+            this.enqueue(session, s, event);
+        }
+        catch (err) {
+            this.deps.log(`context: could not queue a report for ${session}: ${errText(err)}`);
+        }
+    }
+    /** Resolves once every queued send has been attempted. */
+    async idle() {
+        await Promise.all([...this.sessions.values()].map((s) => s.chain));
+    }
+    close() {
+        this.closed = true;
+        for (const s of this.sessions.values())
+            s.timer?.cancel();
+    }
+    holdTrailing(session, s, event) {
+        s.trailing = event;
+        if (s.timer || !s.sent)
+            return;
+        const wait = Math.max(0, s.sent.at + exports.USAGE_MIN_INTERVAL_MS - this.now());
+        const setTimer = this.deps.setTimer ??
+            ((fn, ms) => {
+                const t = setTimeout(fn, ms);
+                t.unref?.();
+                return { cancel: () => clearTimeout(t) };
+            });
+        s.timer = setTimer(() => {
+            s.timer = undefined;
+            const held = s.trailing;
+            s.trailing = undefined;
+            // Re-run through `report` so the throttle is the one rule, not a second copy of it.
+            if (held)
+                this.report(session, held);
+        }, wait);
+    }
+    enqueue(session, s, event) {
+        s.chain = s.chain.then(() => this.send(session, s, event)).catch((err) => {
+            this.deps.log(`context: report for ${session} failed unexpectedly: ${errText(err)}`);
+        });
+    }
+    async send(session, s, event) {
+        const now = this.now();
+        if (now < this.notDeployedUntil)
+            return;
+        if (s.refusedUntil && now < s.refusedUntil)
+            return;
+        const auth = this.deps.auth();
+        if (!auth)
+            return;
+        const outcome = await postContextEvent(auth, session, event, this.deps.request ?? api_1.apiRequest);
+        switch (outcome.kind) {
+            case "sent":
+                if (s.lastFailure)
+                    this.deps.log(`context: reports for ${session} are going through again`);
+                s.lastFailure = undefined;
+                return;
+            case "not-deployed":
+                this.notDeployedUntil = this.now() + exports.NOT_DEPLOYED_BACKOFF_MS;
+                this.deps.log("context: this BayChat server does not accept context reports yet — trying again in an hour");
+                return;
+            case "refused": {
+                s.refusedUntil = this.now() + exports.SESSION_REFUSED_BACKOFF_MS;
+                // The sample that was refused was never recorded by the server; the next one must go.
+                s.sent = undefined;
+                this.logOnce(s, `context: BayChat refused a report for ${session} (${outcome.message}${outcome.code ? `, ${outcome.code}` : ""}) — pausing that session's reports for 5 minutes`);
+                return;
+            }
+            case "failed":
+                s.sent = undefined;
+                this.logOnce(s, `context: could not report for ${session} (${outcome.message}) — will retry with the next change`);
+                return;
+        }
+    }
+    logOnce(s, line) {
+        if (s.lastFailure === line)
+            return;
+        s.lastFailure = line;
+        this.deps.log(line);
+    }
+}
+exports.ContextReporter = ContextReporter;
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/help-topics.js

@@ -20,7 +20,7 @@
  * only one of the two places.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HELP_TOPICS = exports.UPDATE_HELP = exports.UPDATE_COMMAND = exports.ROOMS_TOPIC = void 0;
+exports.HELP_TOPICS = exports.ROOMS_TOPIC = void 0;
 exports.findTopic = findTopic;
 exports.topicIndex = topicIndex;
 /**
@@ -52,16 +52,6 @@ Never create on ambiguity, denied access, authentication or network errors.
 Never invent a title or substitute a similar group. If creation returns
 GROUP_TITLE_TAKEN, retry joining that exact title once; if still ambiguous or
 unavailable, report it and stop. Do not loop or create a second name.`;
-/**
- * How to update — the command the owner kept having to look up.
- *
- * Kept here, once, and spliced into the top of `baychat help` and into the `/help` reply a
- * session sends back in chat, so the two can never name different commands.
- * `baychat update` (update-command.ts) already does every step: the package, each
- * connected client's config, and a relay restart onto the new code.
- */
-exports.UPDATE_COMMAND = "baychat update";
-exports.UPDATE_HELP = `Update: ${exports.UPDATE_COMMAND} — then check with baychat --version`;
 const GROUPS = {
     name: "groups",
     summary: "Make a group, or find the ones you are already in",
@@ -176,18 +166,7 @@ cards. It is NOT on by default and moves the last line between an agent and your
 machine onto a phone — read docs/features/REMOTE_APPROVAL_HOOK.md before enabling
 it. It fails CLOSED: every error denies.`,
 };
-const UPDATE = {
-    name: "update",
-    summary: "Update the CLI and restart the relay onto the new version",
-    keywords: ["update", "upgrade", "version", "latest", "new version"],
-    body: `${exports.UPDATE_HELP}
-
-\`${exports.UPDATE_COMMAND}\` upgrades the package (for a global install), refreshes every
-connected client's config, and restarts the relay so it runs the new code.
-Running through npx? Use \`npx baychat@latest update\` — plain npx can run a cached
-older copy.`,
-};
-exports.HELP_TOPICS = [GROUPS, SESSIONS, TOOLS, APPROVALS, UPDATE];
+exports.HELP_TOPICS = [GROUPS, SESSIONS, TOOLS, APPROVALS];
 /** Exact name first, then keyword, then a substring of the body. */
 function findTopic(query) {
     const q = query.trim().toLowerCase();