@leo000001/opencode-quota-sidebar 2.0.20 → 2.0.23

package/README.md

@@ -65,8 +65,11 @@ Want to add support for another provider (Google Antigravity, Zhipu AI, Firmware
   - short windows (`5h`, `1d`, `Daily`) still show same-day resets as `HH:MM` and cross-day resets as `MM-DD HH:MM`; longer windows continue to show `MM-DD`
   - long quota content wraps across extra compact lines instead of dropping fields from the sidebar, and continuation lines align to the quota content column
 - Desktop automatically switches to a compact monitoring-style single-line title. It keeps recently used providers from the last `50` requests or last `60` minutes, expands all windows/balance for those selected providers in short form such as `OAI 5h80 R16:20 W70 R04-03` or `RC D88.9/60 B260`, and keeps only summary usage signals such as `Cd66%` and `Est$0.12`
-- TUI is always rendered as compact multiline; Desktop is always rendered as compact monitoring-style single-line. This behavior no longer depends on `sidebar.multilineTitle`
-- Web UI currently cannot be reliably detected by the plugin, so it follows the non-desktop multiline path
+- Auto mode now prefers compact single-line titles everywhere except the actively selected TUI session. That means Desktop stays compact, Web UI / `serve` clients also use compact single-line titles, and the current TUI session keeps the compact multiline layout.
+- `sidebar.titleMode` can force `auto`, `multiline`, or `compact` if the heuristic does not match your workflow.
+- Auto-mode signals are intentionally minimal: Desktop is detected only from `OPENCODE_CLIENT=desktop`; TUI ownership comes from `tui.session.select`; `tui.command.execute` and `tui.prompt.append` only keep that last selected TUI session fresh.
+- Auto-mode freshness lasts `15` minutes. If no new TUI activity arrives in that window, the tracked TUI session is refreshed back to compact; the next TUI activity re-enables multiline for the last selected TUI session.
+- Multi-client caveat: the plugin tracks one global TUI-selected session and writes one shared `session.title`. In mixed TUI/Web or multi-TUI setups, the latest TUI selection wins for that session title. Use `sidebar.titleMode="compact"` or `"multiline"` if you need a stable forced policy.
 - Session-scoped usage/quota can include descendant subagent sessions (enabled by default via `sidebar.includeChildren=true`). Traversal is bounded by `childrenMaxDepth` (default 6), `childrenMaxSessions` (default 128), and `childrenConcurrency` (default 5); truncation is logged when `OPENCODE_QUOTA_DEBUG=1`. Day/week/month ranges never merge children — only session scope does.
 - Toast message can include four sections: `Token Usage`, `Cost as API` (per provider), `Provider Cache` (when provider-level cached ratios are available), and `Quota`
 - Expiry reminders are shown in a separate `Expiry Soon` toast section only for providers with real subscription expiry timestamps, and each session shows that auto-reminder at most once
@@ -249,7 +252,8 @@ Sidebar defaults:
 
 - `sidebar.enabled`: `true`
 - `sidebar.width`: `36` (clamped to `20`-`60`)
-- `sidebar.multilineTitle`: `true` (legacy compatibility field; TUI/Desktop display mode is now chosen automatically)
+- `sidebar.titleMode`: `auto` (`auto`/`multiline`/`compact`)
+- `sidebar.multilineTitle`: `true` (legacy compatibility field; title style is now chosen automatically)
 - `sidebar.showCost`: `true`
 - `sidebar.showQuota`: `true`
 - `sidebar.wrapQuotaLines`: `true`
@@ -257,8 +261,8 @@ Sidebar defaults:
 - `sidebar.childrenMaxDepth`: `6` (clamped to `1`-`32`)
 - `sidebar.childrenMaxSessions`: `128` (clamped to `0`-`2000`)
 - `sidebar.childrenConcurrency`: `5` (clamped to `1`-`10`)
-- `sidebar.desktopCompact.recentRequests`: `50` (desktop compact only)
-- `sidebar.desktopCompact.recentMinutes`: `60` (desktop compact only)
+- `sidebar.desktopCompact.recentRequests`: `50` (compact single-line titles)
+- `sidebar.desktopCompact.recentMinutes`: `60` (compact single-line titles)
 
 Quota defaults:
 
@@ -282,6 +286,7 @@ Other defaults:
   "sidebar": {
     "enabled": true,
     "width": 36,
+    "titleMode": "auto",
     "multilineTitle": true,
     "showCost": true,
     "showQuota": true,
@@ -323,13 +328,18 @@ Other defaults:
 - `sidebar.showCost` controls API-cost visibility in sidebar title, `quota_summary` markdown report, and toast message.
 - `quota_summary` follows the same reset compaction rules for short windows in its subscription section (`5h` / `1d` / `Daily` show time, long windows show date, RightCode `Exp` stays date-only).
 - `sidebar.width` is measured in terminal cells. CJK/emoji truncation is best-effort to avoid sidebar overflow.
-- `sidebar.multilineTitle` is kept for backward compatibility, but current rendering is fixed by client type: TUI uses multiline titles and Desktop uses compact monitoring-style single-line titles.
+- `sidebar.titleMode` defaults to `auto`: Desktop is compact, the actively selected TUI session stays multiline, and everything else (including Web UI / `serve` clients) uses the compact single-line layout. Use `multiline` or `compact` to force one style.
+- `auto` relies on positive TUI signals: `tui.session.select` chooses the tracked TUI session, and recent `tui.command.execute` / `tui.prompt.append` activity only refreshes that tracked session. If no `tui.session.select` has been seen, command/prompt activity alone will not promote a session to multiline.
+- The TUI freshness window is `15` minutes. After that timeout, the tracked TUI session is refreshed back to compact; the next TUI activity re-promotes only the last selected TUI session.
+- The plugin tracks one global `tuiSessionID` and one shared session title per plugin process, not one title per window/tab/client. In multi-client or shared-server setups, different TUI/Web viewers can influence each other. If you need predictable rendering, force `sidebar.titleMode`.
+- `sidebar.multilineTitle` is kept for backward compatibility, but `sidebar.titleMode` now controls the active policy.
 - `sidebar.wrapQuotaLines` controls quota line wrapping and continuation indentation (default: `true`).
 - `sidebar.includeChildren` controls whether session-scoped usage/quota includes descendant subagent sessions (default: `true`).
 - `sidebar.childrenMaxDepth` limits how many levels of nested subagents are traversed (default: `6`, clamped 1–32).
 - `sidebar.childrenMaxSessions` caps the total number of descendant sessions aggregated (default: `128`, clamped 0–2000).
 - `sidebar.childrenConcurrency` controls parallel fetches for descendant session messages (default: `5`, clamped 1–10).
-- `sidebar.desktopCompact.recentRequests` and `sidebar.desktopCompact.recentMinutes` control which recently used providers remain visible in desktop compact titles.
+- `sidebar.desktopCompact.recentRequests` and `sidebar.desktopCompact.recentMinutes` control which recently used providers remain visible in compact single-line titles.
+- `sidebar.desktopCompact.recentRequests` and `sidebar.desktopCompact.recentMinutes` only control provider filtering inside compact titles; they do not change TUI detection or the 15-minute freshness timeout.
 - `output` includes reasoning tokens (`output = tokens.output + tokens.reasoning`). Reasoning is not rendered as a separate line.
 - API cost bills reasoning tokens at the output rate (same as completion tokens).
 - API cost is computed from OpenCode model pricing metadata, not from `message.cost`. This keeps subscription-backed providers such as OpenAI OAuth usable for API-equivalent cost estimation even when OpenCode's measured cost is `0`.
@@ -368,7 +378,27 @@ These examples show the quota block portion of the sidebar title.
 
 ### TUI layout
 
-This section describes the TUI layout. Desktop uses its own compact monitoring-style single-line format and Web UI currently follows the multiline path.
+This section describes the multiline TUI layout. Desktop and Web UI / `serve` clients use the compact single-line format unless you force `sidebar.titleMode = "multiline"`.
+
+### Force modes
+
+If you prefer a stable policy instead of the auto heuristic:
+
+```json
+{
+  "sidebar": {
+    "titleMode": "compact"
+  }
+}
+```
+
+```json
+{
+  "sidebar": {
+    "titleMode": "multiline"
+  }
+}
+```
 
 0 providers (no quota data):
 

package/dist/events.d.ts

@@ -3,6 +3,8 @@ export declare function createEventDispatcher(handlers: {
     onSessionCreated: (session: Session) => Promise<void>;
     onSessionUpdated: (session: Session) => Promise<void>;
     onSessionDeleted: (session: Session) => Promise<void>;
+    onTuiActivity: () => Promise<void>;
+    onTuiSessionSelect: (sessionID: string) => Promise<void>;
     onMessageRemoved: (info: {
         sessionID: string;
         messageID?: string;

package/dist/events.js

@@ -3,6 +3,7 @@ function isAssistantMessage(message) {
 }
 export function createEventDispatcher(handlers) {
     return async (event) => {
+        const tui = event;
         if (event.type === 'session.created') {
             await handlers.onSessionCreated(event.properties.info);
             return;
@@ -15,6 +16,17 @@ export function createEventDispatcher(handlers) {
             await handlers.onSessionDeleted(event.properties.info);
             return;
         }
+        if (tui.type === 'tui.prompt.append' || tui.type === 'tui.command.execute') {
+            await handlers.onTuiActivity();
+            return;
+        }
+        if (tui.type === 'tui.session.select') {
+            if (typeof tui.properties?.sessionID !== 'string')
+                return;
+            await handlers.onTuiSessionSelect(tui.properties.sessionID);
+            await handlers.onTuiActivity();
+            return;
+        }
         if (event.type === 'message.removed') {
             const props = event.properties;
             await handlers.onMessageRemoved({

package/dist/format.d.ts

@@ -1,6 +1,15 @@
 import type { QuotaSidebarConfig, QuotaSnapshot } from './types.js';
 import { type UsageSummary } from './usage.js';
+export type TitleView = 'multiline' | 'compact';
+export declare const TUI_ACTIVE_MS: number;
 export declare function isDesktopClient(): boolean;
+export declare function resolveTitleView(opts: {
+    config: QuotaSidebarConfig;
+    sessionID?: string;
+    tuiSessionID?: string;
+    tuiActiveAt?: number;
+    now?: number;
+}): TitleView;
 export declare function selectDesktopCompactProviderIDs(usage: UsageSummary, config: QuotaSidebarConfig, now?: number): string[];
 /**
  * Render sidebar title with multi-line token breakdown.
@@ -13,7 +22,7 @@ export declare function selectDesktopCompactProviderIDs(usage: UsageSummary, con
  *   $3.81 as API cost         (only if showCost=true)
  *   OpenAI Remaining 78%      (only if quota available)
  */
-export declare function renderSidebarTitle(baseTitle: string, usage: UsageSummary, quotas: QuotaSnapshot[], config: QuotaSidebarConfig): string;
+export declare function renderSidebarTitle(baseTitle: string, usage: UsageSummary, quotas: QuotaSnapshot[], config: QuotaSidebarConfig, view?: TitleView): string;
 export declare function renderMarkdownReport(period: string, usage: UsageSummary, quotas: QuotaSnapshot[], options?: {
     showCost?: boolean;
 }): string;

package/dist/format.js

@@ -1,6 +1,7 @@
 import { getCacheCoverageMetrics, getProviderCacheCoverageMetrics, } from './usage.js';
 import { canonicalProviderID, collapseQuotaSnapshots, displayShortLabel, quotaDisplayLabel, } from './quota_render.js';
 import { stripAnsi } from './title.js';
+export const TUI_ACTIVE_MS = 15 * 60_000;
 /** M6 fix: handle negative, NaN, Infinity gracefully. */
 function shortNumber(value, decimals = 1) {
     if (!Number.isFinite(value) || value < 0)
@@ -163,6 +164,20 @@ function formatRequestsLabel(value, short = false) {
 export function isDesktopClient() {
     return process.env.OPENCODE_CLIENT === 'desktop';
 }
+export function resolveTitleView(opts) {
+    if (opts.config.sidebar.titleMode === 'compact')
+        return 'compact';
+    if (opts.config.sidebar.titleMode === 'multiline')
+        return 'multiline';
+    if (isDesktopClient())
+        return 'compact';
+    if (opts.sessionID &&
+        opts.sessionID === opts.tuiSessionID &&
+        (opts.now ?? Date.now()) - (opts.tuiActiveAt ?? 0) <= TUI_ACTIVE_MS) {
+        return 'multiline';
+    }
+    return 'compact';
+}
 function desktopCompactSettings(config) {
     return {
         recentRequests: Math.max(1, config.sidebar.desktopCompact?.recentRequests ?? 50),
@@ -462,10 +477,11 @@ function renderSingleLineTitle(baseTitle, usage, quotas, config, width) {
  *   $3.81 as API cost         (only if showCost=true)
  *   OpenAI Remaining 78%      (only if quota available)
  */
-export function renderSidebarTitle(baseTitle, usage, quotas, config) {
+export function renderSidebarTitle(baseTitle, usage, quotas, config, view) {
     const width = Math.max(8, Math.floor(config.sidebar.width || 36));
     const safeBaseTitle = stripAnsi(baseTitle || 'Session') || 'Session';
-    if (isDesktopClient()) {
+    const mode = view || resolveTitleView({ config });
+    if (mode === 'compact') {
         const singleLineBase = safeBaseTitle.split(/\r?\n/, 1)[0] || 'Session';
         return renderDesktopCompactTitle(singleLineBase, usage, quotas, config, width);
     }

package/dist/index.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { renderMarkdownReport, renderSidebarTitle, renderToastMessage, } from './format.js';
+import { renderMarkdownReport, resolveTitleView, renderSidebarTitle, renderToastMessage, TUI_ACTIVE_MS, } from './format.js';
 import { createQuotaRuntime } from './quota.js';
 import { authFilePath, dateKeyFromTimestamp, deleteSessionFromDayChunk, evictOldSessions, loadConfig, loadState, normalizeTimestampMs, resolveOpencodeConfigDir, resolveOpencodeDataDir, saveState, stateFilePath, } from './storage.js';
 import { debug, swallow } from './helpers.js';
@@ -126,6 +126,23 @@ export async function QuotaSidebarPlugin(input) {
     });
     const summarizeSessionUsageForDisplay = usageService.summarizeSessionUsageForDisplay;
     const summarizeForTool = usageService.summarizeForTool;
+    let tuiSessionID;
+    let tuiActiveAt = 0;
+    let tuiTimer;
+    const armTuiTimer = () => {
+        if (tuiTimer)
+            clearTimeout(tuiTimer);
+        if (!tuiSessionID)
+            return;
+        tuiTimer = setTimeout(() => {
+            const id = tuiSessionID;
+            tuiActiveAt = 0;
+            tuiTimer = undefined;
+            if (id)
+                scheduleTitleRefresh(id, 0);
+        }, TUI_ACTIVE_MS);
+        tuiTimer.unref?.();
+    };
     // title apply / refresh lifecycle
     let scheduleTitleRefresh = (sessionID, delay = 250) => {
         void sessionID;
@@ -161,6 +178,7 @@ export async function QuotaSidebarPlugin(input) {
         markDirty,
         scheduleSave,
         renderSidebarTitle,
+        getTitleView: (sessionID) => resolveTitleView({ config, sessionID, tuiSessionID, tuiActiveAt }),
         getQuotaSnapshots,
         summarizeSessionUsageForDisplay,
         scheduleParentRefreshIfSafe,
@@ -200,6 +218,8 @@ export async function QuotaSidebarPlugin(input) {
             .catch(swallow('startup:refreshAllTouchedTitles'));
     }
     const shutdown = async () => {
+        if (tuiTimer)
+            clearTimeout(tuiTimer);
         await Promise.race([
             startupTitleWork,
             new Promise((resolve) => setTimeout(resolve, 5_000)),
@@ -327,6 +347,14 @@ export async function QuotaSidebarPlugin(input) {
         },
         onSessionDeleted: async (session) => {
             await flushSave().catch(swallow('onSessionDeleted:flushSave'));
+            if (tuiSessionID === session.id) {
+                tuiSessionID = undefined;
+                tuiActiveAt = 0;
+                if (tuiTimer) {
+                    clearTimeout(tuiTimer);
+                    tuiTimer = undefined;
+                }
+            }
             descendantsResolver.invalidateForAncestors(session.parentID);
             descendantsResolver.invalidateForAncestors(session.id);
             usageService.forgetSession(session.id);
@@ -348,6 +376,23 @@ export async function QuotaSidebarPlugin(input) {
                 titleRefresh.schedule(session.parentID, 0);
             }
         },
+        onTuiActivity: async () => {
+            const stale = Boolean(tuiSessionID) && Date.now() - tuiActiveAt > TUI_ACTIVE_MS;
+            tuiActiveAt = Date.now();
+            armTuiTimer();
+            if (stale && tuiSessionID) {
+                titleRefresh.schedule(tuiSessionID, 0);
+            }
+        },
+        onTuiSessionSelect: async (sessionID) => {
+            const prev = tuiSessionID;
+            tuiSessionID = sessionID;
+            armTuiTimer();
+            if (prev && prev !== sessionID) {
+                titleRefresh.schedule(prev, 0);
+            }
+            titleRefresh.schedule(sessionID, 0);
+        },
         onMessageRemoved: async (info) => {
             usageService.markForceRescan(info.sessionID);
             titleRefresh.schedule(info.sessionID, 0);

package/dist/storage.js

@@ -11,6 +11,7 @@ export const defaultConfig = {
     sidebar: {
         enabled: true,
         width: 36,
+        titleMode: 'auto',
         multilineTitle: true,
         showCost: true,
         showQuota: true,
@@ -88,6 +89,11 @@ export async function loadConfig(paths) {
             sidebar: {
                 enabled: asBoolean(sidebar.enabled, base.sidebar.enabled),
                 width: Math.max(20, Math.min(60, asNumber(sidebar.width, base.sidebar.width))),
+                titleMode: sidebar.titleMode === 'compact' ||
+                    sidebar.titleMode === 'multiline' ||
+                    sidebar.titleMode === 'auto'
+                    ? sidebar.titleMode
+                    : (base.sidebar.titleMode ?? 'auto'),
                 multilineTitle: asBoolean(sidebar.multilineTitle, base.sidebar.multilineTitle ?? true),
                 showCost: asBoolean(sidebar.showCost, base.sidebar.showCost),
                 showQuota: asBoolean(sidebar.showQuota, base.sidebar.showQuota),

package/dist/title_apply.d.ts

@@ -1,6 +1,7 @@
 import type { PluginInput } from '@opencode-ai/plugin';
 import type { QuotaSidebarConfig, QuotaSidebarState, QuotaSnapshot, SessionState } from './types.js';
 import type { UsageSummary } from './usage.js';
+import { type TitleView } from './format.js';
 export declare function createTitleApplicator(deps: {
     state: QuotaSidebarState;
     config: QuotaSidebarConfig;
@@ -9,7 +10,8 @@ export declare function createTitleApplicator(deps: {
     ensureSessionState: (sessionID: string, title: string, createdAt: number, parentID?: string | null) => SessionState;
     markDirty: (dateKey: string | undefined) => void;
     scheduleSave: () => void;
-    renderSidebarTitle: (baseTitle: string, usage: UsageSummary, quotas: QuotaSnapshot[], config: QuotaSidebarConfig) => string;
+    renderSidebarTitle: (baseTitle: string, usage: UsageSummary, quotas: QuotaSnapshot[], config: QuotaSidebarConfig, view?: TitleView) => string;
+    getTitleView?: (sessionID: string) => TitleView;
     getQuotaSnapshots: (providerIDs: string[], options?: {
         allowDefault?: boolean;
     }) => Promise<QuotaSnapshot[]>;

package/dist/title_apply.js

@@ -1,6 +1,6 @@
 import { canonicalizeTitle, canonicalizeTitleForCompare, looksDecorated, normalizeBaseTitle, } from './title.js';
 import { swallow, debug, mapConcurrent } from './helpers.js';
-import { isDesktopClient, selectDesktopCompactProviderIDs } from './format.js';
+import { resolveTitleView, selectDesktopCompactProviderIDs, } from './format.js';
 export function createTitleApplicator(deps) {
     const pendingAppliedTitle = new Map();
     const recentRestore = new Map();
@@ -73,13 +73,15 @@ export function createTitleApplicator(deps) {
             }
         }
         const usage = await deps.summarizeSessionUsageForDisplay(sessionID, deps.config.sidebar.includeChildren);
-        const quotaProviders = Array.from(new Set(isDesktopClient()
+        const view = deps.getTitleView?.(sessionID) ??
+            resolveTitleView({ config: deps.config, sessionID });
+        const quotaProviders = Array.from(new Set(view === 'compact'
             ? selectDesktopCompactProviderIDs(usage, deps.config)
             : Object.keys(usage.providers)));
         const quotas = deps.config.sidebar.showQuota && quotaProviders.length > 0
             ? await deps.getQuotaSnapshots(quotaProviders)
             : [];
-        const nextTitle = deps.renderSidebarTitle(sessionState.baseTitle, usage, quotas, deps.config);
+        const nextTitle = deps.renderSidebarTitle(sessionState.baseTitle, usage, quotas, deps.config, view);
         if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
             return false;
         if (canonicalizeTitleForCompare(nextTitle) ===

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 export type QuotaStatus = 'ok' | 'unavailable' | 'unsupported' | 'error';
+export type SidebarTitleMode = 'auto' | 'multiline' | 'compact';
 export type QuotaWindow = {
     label: string;
     /** Set false when this window line should not render a trailing percentage. */
@@ -148,6 +149,11 @@ export type QuotaSidebarConfig = {
     sidebar: {
         enabled: boolean;
         width: number;
+        /**
+         * `auto`: compact by default, but keep the actively selected TUI session
+         * multiline when the plugin can positively identify it.
+         */
+        titleMode?: SidebarTitleMode;
         /**
          * Legacy switch retained for compatibility.
          * TUI keeps a compact multiline sidebar layout; Desktop keeps a compact
@@ -166,7 +172,7 @@ export type QuotaSidebarConfig = {
         childrenMaxSessions: number;
         /** Concurrency for fetching descendant session messages (bounded). */
         childrenConcurrency: number;
-        /** Desktop-only compact title selection window by request count/time. */
+        /** Compact single-line title selection window by request count/time. */
         desktopCompact?: {
             recentRequests?: number;
             recentMinutes?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leo000001/opencode-quota-sidebar",
-  "version": "2.0.20",
+  "version": "2.0.23",
   "description": "OpenCode plugin that shows quota and token usage in session titles",
   "type": "module",
   "main": "dist/index.js",

package/quota-sidebar.config.example.json

@@ -2,6 +2,7 @@
   "sidebar": {
     "enabled": true,
     "width": 36,
+    "titleMode": "auto",
     "multilineTitle": true,
     "showCost": true,
     "showQuota": true,