AgapHost/ai/codex-quota-footer-plugin/index.js

/**
 * Codex Quota Footer (kb #85) — appends a compact usage line to the end of
 * each of Adolf's outgoing replies, via OpenClaw's `reply_payload_sending`
 * hook (docs/plugins/hooks.md: "Mutate or cancel normalized reply payloads
 * before delivery... runs after payload normalization and before channel
 * delivery, including replies routed back to the originating channel").
 *
 * Source of the numbers: the LLM-free `GET /usage` route on adolf-llm, which
 * drives `codex app-server`'s `account/rateLimits/read` JSON-RPC method — the
 * same snapshot the interactive Codex TUI shows. No model call anywhere.
 *
 * Rewritten 2026-08-01 for the Kimi -> Codex migration. The old payload had
 * fixed Kimi buckets (window_5h / weekly / window_7d); Codex instead reports
 * up to two plan-defined windows, `primary` (long, e.g. 30d) and `secondary`
 * (shorter burst window, may be null), each already normalised by adolf-llm
 * to { pct, window_label, resets }. The footer therefore renders whatever
 * windows the plan actually has, labelled from the data, rather than
 * hardcoding bucket names that may not exist on this plan.
 *
 * Never blocks the send path: usage is cached and refreshed in the
 * background, so a reply is at most decorated with a slightly stale
 * (<= cacheTtlMs) snapshot, and any error/timeout simply omits the footer
 * rather than delaying or breaking the message.
 *
 * Streaming caveat (verified against /app/dist in the running container,
 * kb#85): Matrix preview streaming ("draft previews finalize in place",
 * docs/concepts/streaming.md) delivers the finalized text via a direct
 * payload edit (`ctx.edit`/`onEditReceipt`) that never calls
 * deliverOutboundPayloadsInternal, so reply_payload_sending would NOT fire
 * for that path. Adolf's openclaw.json currently leaves
 * channels.matrix.streaming unset (default "off"), so every real reply goes
 * through the normal send path (sendDurableMessageBatch ->
 * deliverOutboundPayloadsInternal) where this hook does fire. If Matrix
 * streaming is ever turned on for Adolf, this footer will silently stop
 * appearing on finalized-in-place replies — re-check this comment first.
 */

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const DEFAULTS = {
  enabled: true,
  usageUrl: "http://adolf-llm:8010/usage",
  cacheTtlMs: 60000, // serve a cached snapshot for up to this long
  fetchTimeoutMs: 2500, // background fetch only; never on the send path
  prefix: "— Codex:",
  showPlan: false, // append the plan name (e.g. "free") when true
};

function normalizeConfig(raw) {
  const c = raw && typeof raw === "object" ? raw : {};
  const int = (v, d) => (Number.isFinite(v) && v > 0 ? Math.floor(v) : d);
  return {
    enabled: c.enabled !== false,
    usageUrl: typeof c.usageUrl === "string" && c.usageUrl ? c.usageUrl : DEFAULTS.usageUrl,
    cacheTtlMs: int(c.cacheTtlMs, DEFAULTS.cacheTtlMs),
    fetchTimeoutMs: int(c.fetchTimeoutMs, DEFAULTS.fetchTimeoutMs),
    prefix: typeof c.prefix === "string" && c.prefix ? c.prefix : DEFAULTS.prefix,
    showPlan: c.showPlan === true,
  };
}

// One window -> "30d 4%". Falls back to a bare percentage when the backend
// didn't report a window duration.
function renderRow(row) {
  if (!row || typeof row.pct !== "number") return null;
  return row.window_label ? `${row.window_label} ${row.pct}%` : `${row.pct}%`;
}

function formatFooter(usage, cfg) {
  if (!usage) return null;
  // Shortest window first — that's the one most likely to bite.
  const rows = [usage.secondary, usage.primary].map(renderRow).filter(Boolean);
  if (rows.length === 0) return null;

  let line = `${cfg.prefix} ${rows.join(" · ")}`;
  if (cfg.showPlan && usage.plan) line += ` (${usage.plan})`;
  // A limit that has actually been hit matters more than the percentages.
  if (usage.limit_reached) line += " ⚠ limit reached";
  // Mark a reading served from a failed refresh so a stale number is never
  // mistaken for a live one.
  if (usage.stale) line += " (stale)";
  return line;
}

export default definePluginEntry({
  id: "codex-quota-footer",
  name: "Codex Quota Footer",
  description: "Appends a compact Codex usage line to the end of each outgoing reply.",
  register(api) {
    const cfg = normalizeConfig(api.pluginConfig);

    // Non-blocking cache: the send path never awaits the network. When the
    // snapshot is stale we kick a background refresh and keep using the last
    // known one; a quota readout tolerates being a minute stale.
    let cache = { usage: null, ts: 0 };
    let refreshing = false;

    async function refresh() {
      if (refreshing) return;
      refreshing = true;
      const controller = new AbortController();
      const timer = setTimeout(() => controller.abort(), cfg.fetchTimeoutMs);
      try {
        const res = await fetch(cfg.usageUrl, { signal: controller.signal });
        if (!res.ok) throw new Error(`/usage HTTP ${res.status}`);
        cache = { usage: await res.json(), ts: Date.now() };
      } catch (e) {
        api.logger?.debug?.(`codex-quota-footer: usage refresh failed (${e?.message || e})`);
      } finally {
        clearTimeout(timer);
        refreshing = false;
      }
    }

    // Warm the cache at startup so the first reply already carries a footer.
    refresh();

    // Resolve the current footer, refreshing usage without blocking the send
    // path (one-shot blocking only on a cold cache).
    async function currentFooter() {
      if (!cache.usage) {
        await refresh();
      } else if (Date.now() - cache.ts > cfg.cacheTtlMs) {
        refresh();
      }
      return formatFooter(cache.usage, cfg);
    }

    api.on("reply_payload_sending", async (event) => {
      try {
        if (!cfg.enabled) return;
        const payload = event?.payload;
        const text = payload?.text;
        if (typeof text !== "string" || text.trim().length === 0) return;
        const footer = await currentFooter();
        if (!footer || text.includes(footer)) return;
        return { payload: { ...payload, text: `${text}\n\n${footer}` } };
      } catch (e) {
        api.logger?.warn?.(`codex-quota-footer: hook failed (${e?.message || e})`);
      }
    });
  },
});