@songsid/agend 2.3.0-beta.5 → 2.3.0-beta.7

package/dist/ui/shared/effect-registry.js

@@ -1,7 +1,7 @@
 /** #1629 B2: one host-owned Canvas Worker pool. Product adapters are deliberately separate. */
-import { allocateEffectFrames, effectEvent } from "./effect-policy.js";
+import { allocateEffectFrames, effectEvent, effectPlaybackReason } from "./effect-policy.js";
 import { captureEffectBaseline } from "./effect-baseline.js";
-import { createEffectFrame } from "./effect-frame.js";
+import { createOpaqueEffectFrame } from "./effect-frame.js";
 import { createEffectGeometry, hostEffectRect } from "./effect-geometry.js";
 import { effectStockSnapshot, effectStockAllows } from "./effect-stock-snapshot.js";
 import { effectTrialStage, effectTrialStageIdentity, watchEffectTrialStage } from "./effect-trial-stage.js";
@@ -10,7 +10,7 @@ import { EffectBudget } from "./effect-profiler.js";
 const registries = new WeakMap();
 const plain = o => !!o && (Object.getPrototypeOf(o) === Object.prototype || Object.getPrototypeOf(o) === null);
 const finite = v => typeof v === "number" && Number.isFinite(v);
-const FLAGS = ["safe", "publicLink", "reducedMotion", "saveData", "hidden", "enabled", "show", "previewReady", "optIn", "constrained", "modal"];
+const FLAGS = ["safe", "publicLink", "reducedMotion", "saveData", "hidden", "enabled", "show", "transportReady", "constrained", "modal"];
 const TYPES = ["state", "reply", "theme"];
 function unsafeSnapshotDescriptor(d) {
   if (!plain(d) || !plain(d.params ?? {})) return null;
@@ -105,12 +105,7 @@ export function createEffectRegistry({ window: host, origin, boot, load, safety,
     return true;
   };
   // Display only: the closed global gate a row is waiting on, when the host knows it (else the caller's unknown).
-  const gateReason = () => {
-    if (!gatesKnown()) return null;
-    const c = context;
-    return c.safe ? "safe_mode" : c.publicLink ? "public_link" : c.reducedMotion ? "reduced_motion" : c.saveData ? "save_data"
-      : !(c.enabled && c.show) ? "disabled" : !(c.previewReady && c.optIn) ? "preview_unavailable" : null;
-  };
+  const gateReason = () => effectPlaybackReason(context);
   const clearMarker = (s, why) => {
     if (!s.token) return true;
     const token = s.token; s.token = null;
@@ -122,7 +117,9 @@ export function createEffectRegistry({ window: host, origin, boot, load, safety,
     s.live = false;
     if (slots.get(s.d.key) === s) slots.delete(s.d.key);
     if (s.request) { s.request.controller.abort(); if (s.request.timer !== null) host.clearTimeout(s.request.timer); }
-    if (!["disposed", "superseded", "hidden", "human_resume", "calibrating", "geometry_changed"].includes(why)) failures.set(s.d.key, { identity: signature(s.d), reason: why });
+    // A closed/unknown viewer gate revokes paint, not the effect identity. Fresh known gates
+    // may admit it again; resource failures and actual safety pauses retain their latches.
+    if (!["disposed", "superseded", "hidden", "human_resume", "calibrating", "geometry_changed", "gates_unknown"].includes(why)) failures.set(s.d.key, { identity: signature(s.d), reason: why });
     s.stageOff?.(); s.stageOff = null;
     s.frame?.remove(why); s.geometry?.remove();
     if (s.loadOff) s.loadOff();
@@ -145,13 +142,9 @@ export function createEffectRegistry({ window: host, origin, boot, load, safety,
     return true;
   }
   function gatesKnown() { return context && FLAGS.every(k => typeof context[k] === "boolean") && (context.openInstance === null || typeof context.openInstance === "string" && context.openInstance.length >= 1 && context.openInstance.length <= 128); }
-  function consent(d) {
-    const trial = d?.trialStage && effectTrialStageIdentity(d.trialStage);
-    return trial ? context.trialReady === true : context.previewReady === true && context.optIn === true;
-  }
   function eligible(d = null) {
-    return gatesKnown() && !context.safe && !context.publicLink && !context.reducedMotion && !context.saveData && context.enabled && context.show
-      && (d ? consent(d) : context.previewReady && context.optIn || descriptors.some(x => x.trialStage && consent(x)));
+    return gatesKnown() && !context.safe && !context.reducedMotion && !context.saveData && context.enabled && context.show && context.transportReady
+      && (!d || !context.publicLink || d.region === "chat" && !d.trialStage);
   }
   const globalAllowed = (d = null) => eligible(d) && host.document.visibilityState === "visible";
   const signature = d => d.identity;
@@ -329,7 +322,7 @@ export function createEffectRegistry({ window: host, origin, boot, load, safety,
         if (local) fresh = local.rect;
         s.rect = fresh;
         s.budget = new EffectBudget({ device: s.device, baselineFps: baseline, clock: nativeClock, longTasksSupported });
-        const frame = createEffectFrame({ window: host, root: local?.root ?? root, origin, boot, clock: nativeClock,
+        const frame = createOpaqueEffectFrame({ window: host, root: local?.root ?? root, origin, boot, clock: nativeClock,
           render: { code: resource.code, params: resource.params, assets: resource.assets, wants: resource.wants, instance: d.instance, width: fresh.width, height: fresh.height, dpr: dpr(s.device) },
           onReady() { if (!current(s)) return; if (!globalAllowed(d) || context.hidden || !coverage(d)) { retire(s, "hidden"); tell(); return; } const n = time(); if (n === null) { blocked = "clock_unavailable"; stopAll(blocked); tell(); return; } s.ready = true; s.readyAt = n; s.healthySince = n; publishEnv(s); schedule(); tell(); },
           onRemove(why) { if (current(s)) { retire(s, why); tell(); } },
@@ -510,7 +503,7 @@ export function createEffectRegistry({ window: host, origin, boot, load, safety,
       descriptors = ds.map(snapshotDescriptor).filter(Boolean);
       for (const [key, identity] of paused) if (!descriptors.some(d => d.key === key && signature(d) === identity)) paused.delete(key);
       for (const [key, f] of failures) if (!descriptors.some(d => d.key === key && signature(d) === f.identity)) failures.delete(key);
-      context = Object.fromEntries([...FLAGS, "trialReady", "openInstance"].map(k => [k, ctx[k]]));
+      context = Object.fromEntries([...FLAGS, "openInstance"].map(k => [k, ctx[k]]));
       reconcile(); return view();
     },
     snapshot: view,

package/dist/ui/shared/effect-stock-trust.js

@@ -178,9 +178,9 @@ export function stockEffectTrust(host, { frameRoot = null, ownerCss = "unknown"
     if (doc.querySelector(".agend-session-ended")) return fail("session_ended");
     let barrier = [...doc.querySelectorAll(BARRIERS)].some(el => visible(host, el));
     if (host.innerWidth < 900 && [...doc.querySelectorAll(".pv-panel")].some(el => visible(host, el))) barrier = true;
-    const active = doc.activeElement;
     if (doc.fullscreenElement || doc.pictureInPictureElement) barrier = true;
-    if (active && active !== doc.body && active !== doc.documentElement && (active.matches("input,select,textarea,[contenteditable]") || active.isContentEditable)) barrier = true;
+    // Focus alone does not change protected paint bounds. Composer/controls stay clipped; editable focus
+    // separately suppresses pointer delivery in the registry, and keyboard events never enter a Worker.
     return { ok: true, rects, front: !barrier, reason: barrier ? "stock_overlay" : "stock", agentFront: !barrier && ownerCss === "off", agentReason: barrier ? "stock_overlay" : ownerCss === "off" ? "stock" : "owner_css", settingsHref: "/settings/appearance" };
   } catch { return fail("stock_trust_unknown"); }
 }

package/dist/ui/shared/effect-trial-stage.js

@@ -120,21 +120,32 @@ export function createEffectTrialStage({ window: host, panel, stage, binding: ra
   function bind(frame, { layer } = {}, stock) {
     if (frames.size || !["front", "behind"].includes(layer) || frame?.ownerDocument !== host.document || frame.parentElement !== stage || frame.tagName !== "IFRAME") { frame?.remove?.(); return { ok: false }; }
     // The new frame is temporarily known to this owner before the topology check; it remains hidden until sync.
-    const token = `agend-effect-trial-${identity.serial}`; let rule, removed = false;
+    const token = `agend-effect-trial-${identity.serial}`; let rule, removed = false, shown = false;
     const remove = () => {
       if (removed) return; removed = true; frame.remove(); frames.delete(handle);
       try { frame.classList.remove(token); const i = [...sheet.cssRules].indexOf(rule); if (i >= 0) sheet.deleteRule(i); } catch { /* physically removed first */ }
     };
-    const hide = () => { try { rule.style.setProperty("visibility", "hidden", "important"); if (frame.isConnected && host.getComputedStyle(frame).visibility !== "hidden") remove(); } catch { remove(); } };
+    const hide = () => {
+      shown = false;
+      try { rule.style.setProperty("visibility", "hidden", "important"); if (frame.isConnected && host.getComputedStyle(frame).visibility !== "hidden") { remove(); return false; } return !removed; } catch { remove(); return false; }
+    };
     const handle = { ok: true, element: frame, remove, hide,
       sync(proof) {
-        hide(); const r = check(proof); if (!r || removed) { invalidate("stage_unavailable"); return false; }
+        const r = check(proof); if (!r || removed) { invalidate("stage_unavailable"); return false; }
         try {
+          const matches = visibility => {
+            const s = host.getComputedStyle(frame), actual = rect(frame);
+            return !!actual && s.position === "absolute" && s.visibility === visibility && s.pointerEvents === "none" && s.zIndex === "0" && s.opacity === (layer === "front" ? "0.85" : "1") && neutral(s)
+              && ["x", "y", "width", "height"].every(k => Math.abs(actual[k] - r[k]) < 0.02) && actual.x >= r.x && actual.y >= r.y && actual.x + actual.width <= r.x + r.width && actual.y + actual.height <= r.y + r.height
+              && frame.isConnected === true && frame.ownerDocument === host.document && frame.parentElement === stage && !dead && !removed && owners.get(stage) === receipt;
+          };
+          // Reprove the current stage, clipping and actual frame every tick. Hiding/revealing an
+          // unchanged iframe each rAF can starve Firefox's OffscreenCanvas presentation.
+          if (shown && matches("visible")) return true;
+          if (!hide()) throw Error("local hiding lost");
           for (const [k, v] of Object.entries({ left: "0px", top: "0px", width: `${r.width}px`, height: `${r.height}px` })) rule.style.setProperty(k, v, "important");
-          const s = host.getComputedStyle(frame), actual = rect(frame);
-          if (!actual || s.position !== "absolute" || s.visibility !== "hidden" || s.pointerEvents !== "none" || s.zIndex !== "0" || s.opacity !== (layer === "front" ? "0.85" : "1") || !neutral(s)
-            || !["x", "y", "width", "height"].every(k => Math.abs(actual[k] - r[k]) < 0.02) || actual.x < r.x || actual.y < r.y || actual.x + actual.width > r.x + r.width || actual.y + actual.height > r.y + r.height) throw Error("local geometry lost");
-          rule.style.setProperty("visibility", "visible", "important"); return true;
+          if (!matches("hidden")) throw Error("local geometry lost");
+          rule.style.setProperty("visibility", "visible", "important"); shown = true; return true;
         } catch { invalidate("stage_unavailable"); return false; }
       },
     };

package/dist/ui/shared/fx-motion.js

@@ -0,0 +1,58 @@
+// #2117 (the user's direction, hmsg-3c166c26): agents' effects play whatever the system's reduced-motion setting says,
+// unless this device chose "Effects: follow the system's reduced-motion setting". One per-device switch (not synced:
+// it is about this screen), shared by ambient effects and Canvas Worker effects; it also works on the public link.
+export const FX_FOLLOW_REDUCED_MOTION_KEY = "agend_fx_follow_reduced_motion";
+/** The one-time chat note "your system asks for reduced motion; effects are on" was shown on this device. */
+export const FX_MOTION_NOTE_KEY = "agend_fx_motion_note_seen";
+const listeners = new Set();
+
+/** Whether this device asked effects to follow the system's reduced-motion setting (default: no). */
+export function followsReducedMotion() {
+  try { return globalThis.localStorage.getItem(FX_FOLLOW_REDUCED_MOTION_KEY) === "1"; } catch { return false; }
+}
+export function setFollowsReducedMotion(on) {
+  try { if (on) globalThis.localStorage.setItem(FX_FOLLOW_REDUCED_MOTION_KEY, "1"); else globalThis.localStorage.removeItem(FX_FOLLOW_REDUCED_MOTION_KEY); } catch { /* this page only */ }
+  for (const fn of [...listeners]) { try { fn(); } catch { /* a listener's own */ } }
+}
+/** `fn()` when the switch or the system's answer moves (this tab, another tab, the OS). Returns the unsubscribe. */
+export function onMotionChange(fn) {
+  listeners.add(fn);
+  const onStorage = (e) => { if (!e || e.key === FX_FOLLOW_REDUCED_MOTION_KEY || e.key === null) fn(); };
+  let q = null;
+  try { q = typeof globalThis.matchMedia === "function" ? globalThis.matchMedia("(prefers-reduced-motion: reduce)") : null; } catch { q = null; }
+  try { globalThis.addEventListener && globalThis.addEventListener("storage", onStorage); } catch { /* none */ }
+  try { if (q && q.addEventListener) q.addEventListener("change", fn); } catch { /* read again on the next render */ }
+  return () => {
+    listeners.delete(fn);
+    try { globalThis.removeEventListener && globalThis.removeEventListener("storage", onStorage); } catch { /* gone */ }
+    try { if (q && q.removeEventListener) q.removeEventListener("change", fn); } catch { /* gone */ }
+  };
+}
+/** Whether the system asks for reduced motion (false when it can't say: the note is only for a clear yes). */
+export function systemReducesMotion(win = globalThis) {
+  try { return typeof win.matchMedia === "function" && win.matchMedia("(prefers-reduced-motion: reduce)").matches === true; } catch { return false; }
+}
+/**
+ * The one-time note (the user's direction): the system asks for reduced motion, this device does not follow it, and the
+ * note was not shown here before. Showing it marks it shown.
+ */
+export function motionNoteDue(win = globalThis) {
+  if (followsReducedMotion() || !systemReducesMotion(win)) return false;
+  try { return globalThis.localStorage.getItem(FX_MOTION_NOTE_KEY) !== "1"; } catch { return false; }
+}
+export function markMotionNoteShown() {
+  try { globalThis.localStorage.setItem(FX_MOTION_NOTE_KEY, "1"); } catch { /* shown again next time: harmless */ }
+}
+
+/**
+ * True when effects stay still here: this device follows the system's setting and the system asks for reduced motion
+ * (or cannot say — then still, as asked for). With the switch off (the default), never.
+ */
+export function motionBlocked(win = globalThis) {
+  if (!followsReducedMotion()) return false;
+  try {
+    if (typeof win.matchMedia !== "function") return true;
+    const q = win.matchMedia("(prefers-reduced-motion: reduce)");
+    return !q || typeof q.matches !== "boolean" || q.matches;
+  } catch { return true; }
+}

package/dist/ui/shared/web-authorize.js

@@ -0,0 +1,151 @@
+// #1939 S2b (design §0.1): "Authorize this browser". The app shows this browser's state — verified (until when), a
+// Confirm card waiting in the account's Discord or Telegram DM (with its countdown), or why it can't be authorized here —
+// and asks for the card. The card itself is the gate: nothing here can authorize anything.
+import { html, useEffect, useRef, useState } from "./app-html.js";
+import { register, t } from "./app-i18n.js";
+import { guestPage } from "./app-store.js";
+
+register("webauth", {
+  en: {
+    verified: "Verified · speaks as you until {0}",
+    notVerified: "Not verified",
+    authorize: "Authorize this browser",
+    waiting: "Waiting for your Confirm in Discord or Telegram ({0})",
+    sent: "Sent — confirm it in your DM within 5 minutes.",
+    publicLink: "Not on the temporary public link: open the dashboard directly to authorize.",
+    reason_disabled: "Web authority is turned off.",
+    reason_loopback_only: "Only this computer can authorize, and this browser is not on it.",
+    reason_no_account: "This browser was not signed in as an account (agend web): sign in with /web to authorize.",
+    reason_not_admin: "Your account is not a fleet admin here.",
+    reason_not_admin_session: "Guests can't authorize.",
+    reason_token_rotated: "The dashboard's token changed: sign in again.",
+    reason_public_link: "Not on the temporary public link.",
+    reason_not_session: "Sign in to authorize.",
+    reason_other: "This browser can't be authorized here.",
+    refusal_pending: "A request is already waiting in your DM.",
+    refusal_rate_limited: "Three requests this hour — try again in {0} min.",
+    refusal_dm_unavailable: "Couldn't send you a DM. Open your DMs with the bot, then try again.",
+    refusal_other: "That didn't work: {0}",
+    settings: "Settings",
+  },
+  "zh-TW": {
+    verified: "已驗證 · 以你的身分發言到 {0}",
+    notVerified: "未驗證",
+    authorize: "授權這個瀏覽器",
+    waiting: "等你在 Discord 或 Telegram 按下確認（{0}）",
+    sent: "已送出——請在 5 分鐘內到私訊確認。",
+    publicLink: "臨時公開連結上無法授權：請直接開啟儀表板再授權。",
+    reason_disabled: "網頁授權已關閉。",
+    reason_loopback_only: "只有這台電腦可以授權，而這個瀏覽器不在這台電腦上。",
+    reason_no_account: "這個瀏覽器不是用帳號登入的（agend web）：請用 /web 登入後再授權。",
+    reason_not_admin: "你的帳號在這裡不是 fleet 管理者。",
+    reason_not_admin_session: "訪客無法授權。",
+    reason_token_rotated: "儀表板的 token 已變更：請重新登入。",
+    reason_public_link: "臨時公開連結上無法授權。",
+    reason_not_session: "登入後才能授權。",
+    reason_other: "這個瀏覽器在這裡無法授權。",
+    refusal_pending: "已經有一個請求在你的私訊中等待。",
+    refusal_rate_limited: "這一小時已請求三次——請 {0} 分鐘後再試。",
+    refusal_dm_unavailable: "無法私訊給你。請開放與 bot 的私訊後再試一次。",
+    refusal_other: "沒有成功：{0}",
+    settings: "設定",
+  },
+});
+const tn = (k, ...v) => t(`webauth.${k}`, ...v);
+const REASONS = ["disabled", "loopback_only", "no_account", "not_admin", "not_admin_session", "token_rotated", "public_link", "not_session"];
+// Until when: the time, with the day when it isn't today (an authorization lasts up to 48 h).
+const clock = (ms) => {
+  const d = new Date(ms), today = new Date().toDateString() === d.toDateString();
+  return today ? d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })
+    : d.toLocaleString([], { weekday: "short", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+};
+const mmss = (ms) => { const s = Math.max(0, Math.ceil(ms / 1000)); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`; };
+const publicLink = () => globalThis.document?.body?.dataset?.publicLink === "1";
+
+// One read per page load, shared by every line that shows it (the composer's, the session menu's): coming back to a chat
+// reads nothing (#1374). It is read again only after an ask, and while a card is pending.
+// An answer of any kind counts as this page's read (one that isn't a state hides the line); only a network failure lets a
+// later mount try again. Signed out (401: the session ended, e.g. Not me), the line goes.
+let shared = null, answered = false, inflight = null, signedOut = false;
+async function readStatus() {
+  inflight ??= (async () => {
+    try {
+      const r = await fetch("/ui/authorization", { credentials: "same-origin" });
+      answered = true;
+      if (r.status === 401) { signedOut = true; shared = null; }
+      const body = r.ok ? await r.json().catch(() => null) : null;
+      if (body && typeof body.state === "string") shared = body;
+    } catch { /* the line stays as it was; a later mount may try again */ }
+    finally { inflight = null; }
+    return shared;
+  })();
+  return inflight;
+}
+
+/** This browser's authorization, kept fresh while a card is pending (every 3 s, until it is decided or expires). */
+export function useWebAuthorization() {
+  const [st, setSt] = useState(shared), [notice, setNotice] = useState(null);
+  const [deadline, setDeadline] = useState(0), [now, setNow] = useState(() => Date.now());
+  const alive = useRef(true);
+  const load = async () => {
+    if (publicLink() || guestPage()) return;
+    const body = await readStatus();
+    if (!alive.current) return;
+    if (signedOut) { setSt(null); setNotice(null); return; }
+    if (!body) return;
+    setSt(body);
+    if (body.state !== "pending") setNotice((n) => (n === tn("sent") ? null : n));           // "Sent —" was about the card
+    if (body.state === "pending" && typeof body.expiresInMs === "number") setDeadline(Date.now() + body.expiresInMs);
+  };
+  useEffect(() => { alive.current = true; if (!answered) load(); return () => { alive.current = false; }; }, []);
+  useEffect(() => {
+    if (!st || st.state !== "pending") return undefined;
+    const tick = setInterval(() => setNow(Date.now()), 1000), poll = setInterval(load, 3000);
+    return () => { clearInterval(tick); clearInterval(poll); };
+  }, [st && st.state]);
+  // "Verified · until X" is read again at X (a page left open must not keep saying verified after it ends).
+  useEffect(() => {
+    if (!st || st.state !== "verified" || typeof st.until !== "number") return undefined;
+    const at = setTimeout(() => { resetWebAuthorization(); load(); }, Math.max(0, Math.min(st.until - Date.now() + 1000, 2 ** 31 - 1)));
+    return () => clearTimeout(at);
+  }, [st && st.state, st && st.until]);
+  const ask = async () => {
+    setNotice(null);
+    let r = null, body = null;
+    try { r = await fetch("/ui/authorization", { method: "POST", credentials: "same-origin", headers: { "content-type": "application/json" }, body: "{}" }); body = await r.json(); } catch { body = null; }
+    if (r && r.ok && body && body.ok) { setNotice(tn("sent")); setSt(shared = { state: "pending", expiresInMs: body.expiresInMs }); setDeadline(Date.now() + body.expiresInMs); return; }
+    const refusal = body && body.refusal;
+    if (refusal === "rate_limited") setNotice(tn("refusal_rate_limited", Math.max(1, Math.ceil((body.retryAfterMs || 0) / 60_000))));
+    else if (refusal === "pending" || refusal === "dm_unavailable") setNotice(tn(`refusal_${refusal}`));
+    else if (REASONS.includes(refusal)) setNotice(tn(`reason_${refusal}`));
+    else setNotice(tn("refusal_other", String(refusal || (r && r.status) || "?")));
+    load();
+  };
+  return { st, notice, ask, left: deadline - now };
+}
+
+/**
+ * Forget the page's one read, so the next line that mounts reads again: Settings → Web calls it when it shows (a revoke
+ * or a changed switch there changes what the line should say). Tests use it too: each case is its own page load.
+ */
+export function resetWebAuthorization() { shared = null; answered = false; inflight = null; signedOut = false; }
+
+/** The line under the composer: verified, waiting, or "Not verified" with the button (or why not, with the fix). */
+export function AuthorizeChip() {
+  const a = useWebAuthorization();
+  if (guestPage()) return null;
+  if (publicLink()) return html`<p class="webauth-chip note" data-state="public">${tn("publicLink")}</p>`;
+  if (!a.st) return null;
+  return html`<div class="webauth-chip" data-state=${a.st.state}>${body(a)}${a.notice ? html` <span class="note" role="status">${a.notice}</span>` : null}</div>`;
+}
+
+function body(a) {
+  const st = a.st;
+  if (st.state === "verified") return html`<span class="webauth-ok">✓ ${tn("verified", clock(st.until))}</span>`;
+  if (st.state === "pending") return html`<span class="note">${tn("waiting", mmss(a.left))}</span>`;
+  if (st.reason === "not_authorized" || st.reason === "authorization_expired")
+    return html`<span class="note">${tn("notVerified")} ·</span> <button type="button" class="btn btn-sm" onClick=${a.ask}>${tn("authorize")}</button>`;
+  const why = REASONS.includes(st.reason) ? tn(`reason_${st.reason}`) : tn("reason_other");
+  // The fix, where there is one the person can take here: the switch lives in Settings → Web.
+  return html`<span class="note">${tn("notVerified")}: ${why}</span>${st.reason === "disabled" || st.reason === "loopback_only" ? html` <a href="/settings/web">${tn("settings")}</a>` : null}`;
+}

package/dist/usage-report.d.ts

@@ -0,0 +1,147 @@
+/**
+ * #2122: the usage report — tokens, requests, delivered messages and their API-equivalent at list price, per instance
+ * (or by backend, model, credential profile or team), over a range of days. Pure: it reads the ledgers' hours after the
+ * rollup's checkpoint and the rollup's days up to it (usage-rollup.ts), and the delivered-message counts; it never reads
+ * a transcript. docs/design/2122-usage-analysis.md.
+ *
+ * Honest by construction: an amount is "API-equivalent at list price (checked <date>) — not money spent"; an unpriced
+ * model's tokens are shown and its amount is not; Codex's cache writes are "not reported" (every CLI seen records 0),
+ * never priced as uncached; an instance whose backend AgEnD cannot measure is listed with its reason, never as $0.
+ */
+import type { Ledger } from "./cache-ledger.js";
+import { type UsageDays } from "./usage-rollup.js";
+export declare const USAGE_GROUPS: readonly ["instance", "backend", "model", "profile", "team"];
+export type UsageGroup = typeof USAGE_GROUPS[number];
+export declare const USAGE_RANGES: readonly ["today", "7d", "month", "all"];
+export type UsageRange = {
+    kind: typeof USAGE_RANGES[number];
+} | {
+    kind: "custom";
+    from: string;
+    to: string;
+};
+/** What every amount is, in words — the page, the CSV and the agent tool all carry it. */
+export declare const usageBasis: (checked?: string) => string;
+/** Daily rows returned at most (the CSV and the trend); beyond it the report says it is truncated. */
+export declare const USAGE_DAILY_MAX = 20000;
+export interface UsageInstanceInput {
+    name: string;
+    /** Its backend now: what it is collected with from here on (each slice of its history carries its own). */
+    backend: string;
+    /** The team it is in now (fleet.yaml), for the one grouping built from current settings. */
+    team: string | null;
+    /** Whether it is collected now; what it measured before (`ledger`, `days`) is reported either way. */
+    status: "ok" | "no_data" | "credit_billed" | "unsupported" | "shared";
+    with?: string[];
+    /** A snapshot taken together with `days` (cache-service.ts usageData): read-only here. */
+    ledger?: Ledger;
+    days?: UsageDays;
+}
+export interface UsageInput {
+    now: number;
+    zone: string;
+    range: UsageRange;
+    group: UsageGroup;
+    instances: UsageInstanceInput[];
+    messages: Array<{
+        instance: string;
+        hour: number;
+        count: number;
+    }>;
+    scanning: {
+        active: boolean;
+        caughtUp: boolean;
+        pendingBytes: number;
+        pendingFiles: number;
+    };
+}
+export interface UsageTotals {
+    /** Uncached input. */
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite5m: number;
+    cacheWrite1h: number;
+    /** OpenAI's one write column (Codex records 0: see `flags`). */
+    cacheWrite: number;
+    requests: number;
+}
+export interface UsageRow extends UsageTotals {
+    key: string;
+    total: number;
+    /** Delivered messages; null where a message has no such key (by model, by profile). */
+    messages: number | null;
+    /** The API-equivalent at list price of what is priced; null when nothing in it is. */
+    amount: number | null;
+    priced: "all" | "partial" | "none";
+    /**
+     * "cache_write_not_reported" (Codex), "not_priced" (with `unpriced`), "source_unknown" (hours counted before #2122:
+     * which backend and profile read them was not recorded).
+     */
+    flags: string[];
+    unpriced: string[];
+    instances: string[];
+    backends: string[];
+    models: string[];
+    profiles: string[];
+}
+export interface UsageDaily extends UsageTotals {
+    date: string;
+    zone: string;
+    instance: string;
+    backend: string;
+    model: string;
+    tier: "long" | "standard";
+    profile: string;
+    amount: number | null;
+    flags: string[];
+}
+export interface UsageReport {
+    range: {
+        kind: UsageRange["kind"];
+        from: string;
+        to: string;
+    };
+    zone: string;
+    /** Days are made of whole UTC hours (§5.3): in a half-hour zone a day's edge falls on the hour that holds midnight. */
+    granularity: "hour";
+    basis: string;
+    pricesChecked: string;
+    group: UsageGroup;
+    rows: UsageRow[];
+    totals: UsageRow;
+    daily: UsageDaily[];
+    dailyTruncated: boolean;
+    messagesDaily: Array<{
+        date: string;
+        instance: string;
+        count: number;
+    }>;
+    notMeasured: Array<{
+        name: string;
+        backend: string;
+        reason: "credit_billed" | "unsupported" | "no_data";
+    }>;
+    shared: Array<{
+        name: string;
+        backend: string;
+        with: string[];
+    }>;
+    /** Per measured instance: the merged UTC intervals its transcripts were read over (§5.5) — never inferred. */
+    coverage: Array<{
+        name: string;
+        intervals: Array<[number, number]>;
+    }>;
+    scanning: UsageInput["scanning"];
+}
+/** A range as asked (query string or tool argument); anything else is the last 7 days. */
+export declare function usageRange(kind: unknown, from?: unknown, to?: unknown): UsageRange;
+export declare const usageGroup: (g: unknown) => UsageGroup;
+/** A local date (YYYY-MM-DD) moved by `n` calendar days — a date's arithmetic, never 24-hour steps (a DST day is 23 or 25). */
+export declare const shiftDate: (date: string, n: number) => string;
+/** The range's first and last local dates (inclusive) in `zone`: "7d" is today and the 6 calendar days before it. */
+export declare function rangeDates(range: UsageRange, now: number, zone: string): {
+    from: string;
+    to: string;
+};
+export declare function buildUsageReport(input: UsageInput): UsageReport;