@leo000001/opencode-quota-sidebar 1.0.2 → 1.2.0

package/dist/storage_chunks.js

@@ -5,6 +5,39 @@ import { debug, isRecord, swallow } from './helpers.js';
 import { isDateKey } from './storage_dates.js';
 import { parseSessionState } from './storage_parse.js';
 import { chunkFilePath } from './storage_paths.js';
+async function mkdirpNoSymlink(rootPath, dirPath) {
+    const rel = path.relative(rootPath, dirPath);
+    if (!rel || rel === '.')
+        return;
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`refusing to mkdir outside root: ${dirPath}`);
+    }
+    let current = rootPath;
+    const parts = rel.split(path.sep).filter(Boolean);
+    for (const part of parts) {
+        current = path.join(current, part);
+        const stat = await fs.lstat(current).catch(() => undefined);
+        if (stat) {
+            if (stat.isSymbolicLink()) {
+                throw new Error(`refusing to write through symlink dir: ${current}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new Error(`expected directory at ${current}`);
+            }
+            continue;
+        }
+        await fs.mkdir(current).catch((error) => {
+            const code = error.code;
+            if (code === 'EEXIST')
+                return;
+            throw error;
+        });
+        const created = await fs.lstat(current).catch(() => undefined);
+        if (!created || created.isSymbolicLink() || !created.isDirectory()) {
+            throw new Error(`unsafe directory created at ${current}`);
+        }
+    }
+}
 /** P2: Simple LRU cache for loaded chunks. */
 class ChunkCache {
     cache = new Map();
@@ -41,10 +74,17 @@ class ChunkCache {
 }
 const chunkCache = new ChunkCache();
 export async function readDayChunk(rootPath, dateKey) {
+    if (!isDateKey(dateKey))
+        return {};
     const cached = chunkCache.get(dateKey);
     if (cached)
         return cached;
     const filePath = chunkFilePath(rootPath, dateKey);
+    const stat = await fs.lstat(filePath).catch(() => undefined);
+    if (stat?.isSymbolicLink()) {
+        debug(`refusing to read symlink chunk: ${filePath}`);
+        return {};
+    }
     const parsed = await fs
         .readFile(filePath, 'utf8')
         .then((value) => JSON.parse(value))
@@ -76,6 +116,12 @@ export async function safeWriteFile(filePath, content) {
         debug(message);
         throw new Error(message);
     }
+    const dirStat = await fs.lstat(path.dirname(filePath)).catch(() => undefined);
+    if (dirStat?.isSymbolicLink()) {
+        const message = `refusing to write through symlink dir: ${path.dirname(filePath)}`;
+        debug(message);
+        throw new Error(message);
+    }
     // M4: atomic write via temp + rename
     const dir = path.dirname(filePath);
     const name = path.basename(filePath);
@@ -109,8 +155,25 @@ export async function safeWriteFile(filePath, content) {
         : new Error(`safeWriteFile failed for ${filePath}`);
 }
 export async function writeDayChunk(rootPath, dateKey, sessions) {
+    if (!isDateKey(dateKey)) {
+        throw new Error(`invalid dateKey: ${dateKey}`);
+    }
     const filePath = chunkFilePath(rootPath, dateKey);
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const rootStat = await fs.lstat(rootPath).catch(() => undefined);
+    if (rootStat?.isSymbolicLink()) {
+        throw new Error(`refusing to write through symlink dir: ${rootPath}`);
+    }
+    if (rootStat && !rootStat.isDirectory()) {
+        throw new Error(`expected directory at ${rootPath}`);
+    }
+    await fs.mkdir(rootPath, { recursive: true });
+    const createdRoot = await fs.lstat(rootPath).catch(() => undefined);
+    if (!createdRoot ||
+        createdRoot.isSymbolicLink() ||
+        !createdRoot.isDirectory()) {
+        throw new Error(`unsafe chunk root at ${rootPath}`);
+    }
+    await mkdirpNoSymlink(rootPath, path.dirname(filePath));
     const chunk = {
         version: 1,
         dateKey,
@@ -126,11 +189,21 @@ export async function discoverChunks(rootPath) {
         if (!/^\d{4}$/.test(year))
             continue;
         const yearPath = path.join(rootPath, year);
+        const yearStat = await fs.lstat(yearPath).catch(() => undefined);
+        if (!yearStat || yearStat.isSymbolicLink() || !yearStat.isDirectory()) {
+            continue;
+        }
         const months = await fs.readdir(yearPath).catch(() => []);
         for (const month of months) {
             if (!/^\d{2}$/.test(month))
                 continue;
             const monthPath = path.join(yearPath, month);
+            const monthStat = await fs.lstat(monthPath).catch(() => undefined);
+            if (!monthStat ||
+                monthStat.isSymbolicLink() ||
+                !monthStat.isDirectory()) {
+                continue;
+            }
             const days = await fs.readdir(monthPath).catch(() => []);
             for (const dayFile of days) {
                 const match = dayFile.match(/^(\d{2})\.json$/);

package/dist/storage_parse.js

@@ -55,9 +55,16 @@ function parseCachedUsage(value) {
 function parseCursor(value) {
     if (!isRecord(value))
         return undefined;
+    const idsRaw = value.lastMessageIdsAtTime;
+    const lastMessageIdsAtTime = Array.isArray(idsRaw)
+        ? idsRaw.filter((item) => typeof item === 'string' && !!item)
+        : undefined;
     return {
         lastMessageId: typeof value.lastMessageId === 'string' ? value.lastMessageId : undefined,
         lastMessageTime: asNumber(value.lastMessageTime),
+        lastMessageIdsAtTime: lastMessageIdsAtTime && lastMessageIdsAtTime.length
+            ? Array.from(new Set(lastMessageIdsAtTime)).sort()
+            : undefined,
     };
 }
 export function parseSessionState(value) {
@@ -72,6 +79,7 @@ export function parseSessionState(value) {
     return {
         ...title,
         createdAt,
+        parentID: typeof value.parentID === 'string' ? value.parentID : undefined,
         usage: parseCachedUsage(value.usage),
         cursor: parseCursor(value.cursor),
     };

package/dist/storage_paths.d.ts

@@ -6,6 +6,7 @@
  * This applies on all platforms including Windows and macOS.
  *
  * S4 fix: renamed env var from OPENCODE_TEST_HOME to OPENCODE_QUOTA_DATA_HOME.
+ * OPENCODE_QUOTA_DATA_HOME overrides the full data directory path.
  */
 export declare function resolveOpencodeDataDir(): string;
 export declare function stateFilePath(dataDir: string): string;

package/dist/storage_paths.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import { isDateKey } from './storage_dates.js';
 /**
  * Resolve the OpenCode data directory.
  *
@@ -8,13 +9,16 @@ import path from 'node:path';
  * This applies on all platforms including Windows and macOS.
  *
  * S4 fix: renamed env var from OPENCODE_TEST_HOME to OPENCODE_QUOTA_DATA_HOME.
+ * OPENCODE_QUOTA_DATA_HOME overrides the full data directory path.
  */
 export function resolveOpencodeDataDir() {
-    const home = process.env.OPENCODE_QUOTA_DATA_HOME || os.homedir();
-    const xdg = process.env.XDG_DATA_HOME;
+    const override = process.env.OPENCODE_QUOTA_DATA_HOME?.trim();
+    if (override)
+        return path.resolve(override);
+    const xdg = process.env.XDG_DATA_HOME?.trim();
     if (xdg)
-        return path.join(xdg, 'opencode');
-    return path.join(home, '.local', 'share', 'opencode');
+        return path.join(path.resolve(xdg), 'opencode');
+    return path.join(os.homedir(), '.local', 'share', 'opencode');
 }
 export function stateFilePath(dataDir) {
     return path.join(dataDir, 'quota-sidebar.state.json');
@@ -26,6 +30,10 @@ export function chunkRootPathFromStateFile(statePath) {
     return path.join(path.dirname(statePath), 'quota-sidebar-sessions');
 }
 export function chunkFilePath(rootPath, dateKey) {
+    // Defense-in-depth: ensure we never build paths from untrusted inputs.
+    if (!isDateKey(dateKey)) {
+        throw new Error(`invalid dateKey: ${dateKey}`);
+    }
     const [year, month, day] = dateKey.split('-');
     return path.join(rootPath, year, month, `${day}.json`);
 }

package/dist/title.d.ts

@@ -1,6 +1,11 @@
 export declare function normalizeBaseTitle(title: string): string;
 export declare function stripAnsi(value: string): string;
 export declare function canonicalizeTitle(value: string): string;
+/**
+ * Comparison canonicalizer for decorated titles.
+ * OpenCode may normalize runs of spaces; treat those as equivalent.
+ */
+export declare function canonicalizeTitleForCompare(value: string): string;
 /**
  * Detect whether a title already contains our decoration.
  * Current layout has token/quota lines after base title line.

package/dist/title.js

@@ -1,8 +1,19 @@
 export function normalizeBaseTitle(title) {
-    return stripAnsi(title).split(/\r?\n/, 1)[0] || 'Session';
+    const firstLine = stripAnsi(title).split(/\r?\n/, 1)[0] || 'Session';
+    return firstLine.replace(/[\x00-\x1F\x7F-\x9F]/g, ' ').trimEnd() || 'Session';
 }
 export function stripAnsi(value) {
-    return value.replace(/\u001b\[[0-9;]*m/g, '');
+    // Remove terminal escape sequences. Sidebar titles must be plain text.
+    // We intentionally strip more than SGR to avoid resize/render corruption.
+    return (value
+        // OSC: ESC ] ... BEL or ST (ESC \)
+        .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+        // CSI: ESC [ ... final byte
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+        // 2-byte escapes and other single-ESC controls
+        .replace(/\u001b[@-Z\\-_]/g, '')
+        // Any leftover ESC
+        .replace(/\u001b/g, ''));
 }
 export function canonicalizeTitle(value) {
     return stripAnsi(value)
@@ -10,6 +21,19 @@ export function canonicalizeTitle(value) {
         .map((line) => line.trimEnd())
         .join('\n');
 }
+/**
+ * Comparison canonicalizer for decorated titles.
+ * OpenCode may normalize runs of spaces; treat those as equivalent.
+ */
+export function canonicalizeTitleForCompare(value) {
+    const lines = stripAnsi(value).split(/\r?\n/);
+    return lines
+        .map((line, index) => {
+        const safe = line.replace(/[\x00-\x1F\x7F-\x9F]/g, ' ').trimEnd();
+        return safe.trim().replace(/[ \t]+/g, ' ');
+    })
+        .join('\n');
+}
 /**
  * Detect whether a title already contains our decoration.
  * Current layout has token/quota lines after base title line.

package/dist/title_apply.d.ts

@@ -0,0 +1,33 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { QuotaSidebarConfig, QuotaSidebarState, QuotaSnapshot, SessionState } from './types.js';
+import type { UsageSummary } from './usage.js';
+export declare function createTitleApplicator(deps: {
+    state: QuotaSidebarState;
+    config: QuotaSidebarConfig;
+    client: PluginInput['client'];
+    directory: string;
+    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;
+    quotaRuntime: {
+        normalizeProviderID: (providerID: string) => string;
+    };
+    getQuotaSnapshots: (providerIDs: string[], options?: {
+        allowDefault?: boolean;
+    }) => Promise<QuotaSnapshot[]>;
+    summarizeSessionUsageForDisplay: (sessionID: string, includeChildren: boolean) => Promise<UsageSummary>;
+    scheduleParentRefreshIfSafe: (sessionID: string, parentID?: string) => void;
+    restoreConcurrency: number;
+}): {
+    applyTitle: (sessionID: string) => Promise<void>;
+    handleSessionUpdatedTitle: (args: {
+        sessionID: string;
+        incomingTitle: string;
+        sessionState: SessionState;
+        scheduleRefresh: (sessionID: string, delay?: number) => void;
+    }) => Promise<void>;
+    restoreSessionTitle: (sessionID: string) => Promise<void>;
+    restoreAllVisibleTitles: () => Promise<void>;
+    forgetSession: (sessionID: string) => void;
+};

package/dist/title_apply.js

@@ -0,0 +1,189 @@
+import { canonicalizeTitle, canonicalizeTitleForCompare, looksDecorated, normalizeBaseTitle, } from './title.js';
+import { swallow, debug, mapConcurrent } from './helpers.js';
+export function createTitleApplicator(deps) {
+    const pendingAppliedTitle = new Map();
+    const forgetSession = (sessionID) => {
+        pendingAppliedTitle.delete(sessionID);
+    };
+    const applyTitle = async (sessionID) => {
+        if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
+            return;
+        let stateMutated = false;
+        const session = await deps.client.session
+            .get({
+            path: { id: sessionID },
+            query: { directory: deps.directory },
+            throwOnError: true,
+        })
+            .catch(swallow('applyTitle:getSession'));
+        if (!session)
+            return;
+        const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
+        // Detect whether the current title is our own decorated form.
+        const currentTitle = session.data.title;
+        if (canonicalizeTitle(currentTitle) !==
+            canonicalizeTitle(sessionState.lastAppliedTitle || '')) {
+            if (looksDecorated(currentTitle)) {
+                // Ignore decorated echoes as base-title source.
+                // If we previously applied a decorated title, treat this as an
+                // equivalent echo (OpenCode may normalize whitespace) and keep
+                // lastAppliedTitle in sync so restoreAllVisibleTitles still works.
+                if (sessionState.lastAppliedTitle &&
+                    looksDecorated(sessionState.lastAppliedTitle)) {
+                    if (sessionState.lastAppliedTitle !== currentTitle) {
+                        sessionState.lastAppliedTitle = currentTitle;
+                        stateMutated = true;
+                    }
+                }
+                else {
+                    debug(`ignoring decorated current title for session ${sessionID}`);
+                    if (sessionState.lastAppliedTitle !== undefined) {
+                        sessionState.lastAppliedTitle = undefined;
+                        stateMutated = true;
+                    }
+                }
+            }
+            else {
+                const nextBase = normalizeBaseTitle(currentTitle);
+                if (sessionState.baseTitle !== nextBase) {
+                    sessionState.baseTitle = nextBase;
+                    stateMutated = true;
+                }
+                if (sessionState.lastAppliedTitle !== undefined) {
+                    sessionState.lastAppliedTitle = undefined;
+                    stateMutated = true;
+                }
+            }
+        }
+        const usage = await deps.summarizeSessionUsageForDisplay(sessionID, deps.config.sidebar.includeChildren);
+        const quotaProviders = Array.from(new Set(Object.keys(usage.providers).map((id) => deps.quotaRuntime.normalizeProviderID(id))));
+        const quotas = deps.config.sidebar.showQuota && quotaProviders.length > 0
+            ? await deps.getQuotaSnapshots(quotaProviders)
+            : [];
+        const nextTitle = deps.renderSidebarTitle(sessionState.baseTitle, usage, quotas, deps.config);
+        if (canonicalizeTitleForCompare(nextTitle) ===
+            canonicalizeTitleForCompare(session.data.title)) {
+            if (looksDecorated(session.data.title)) {
+                if (sessionState.lastAppliedTitle !== session.data.title) {
+                    sessionState.lastAppliedTitle = session.data.title;
+                    stateMutated = true;
+                }
+            }
+            if (stateMutated) {
+                deps.markDirty(deps.state.sessionDateMap[sessionID]);
+            }
+            deps.scheduleSave();
+            deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
+            return;
+        }
+        // Mark pending title to ignore the immediate echo `session.updated` event.
+        // H3 fix: use longer TTL (15s) and add decoration detection as backup.
+        pendingAppliedTitle.set(sessionID, {
+            title: nextTitle,
+            expiresAt: Date.now() + 15_000,
+        });
+        const previousApplied = sessionState.lastAppliedTitle;
+        sessionState.lastAppliedTitle = nextTitle;
+        deps.markDirty(deps.state.sessionDateMap[sessionID]);
+        const updated = await deps.client.session
+            .update({
+            path: { id: sessionID },
+            query: { directory: deps.directory },
+            body: { title: nextTitle },
+            throwOnError: true,
+        })
+            .catch(swallow('applyTitle:update'));
+        if (!updated) {
+            pendingAppliedTitle.delete(sessionID);
+            sessionState.lastAppliedTitle = previousApplied;
+            deps.scheduleSave();
+            deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
+            return;
+        }
+        pendingAppliedTitle.delete(sessionID);
+        deps.scheduleSave();
+        deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
+    };
+    const handleSessionUpdatedTitle = async (args) => {
+        const pending = pendingAppliedTitle.get(args.sessionID);
+        if (pending) {
+            if (pending.expiresAt > Date.now()) {
+                if (canonicalizeTitleForCompare(args.incomingTitle) ===
+                    canonicalizeTitleForCompare(pending.title)) {
+                    pendingAppliedTitle.delete(args.sessionID);
+                    // Keep in sync with what the server actually stored.
+                    args.sessionState.lastAppliedTitle = args.incomingTitle;
+                    deps.markDirty(deps.state.sessionDateMap[args.sessionID]);
+                    deps.scheduleSave();
+                    return;
+                }
+            }
+            else {
+                pendingAppliedTitle.delete(args.sessionID);
+            }
+        }
+        // H3 fix: if the incoming title looks decorated, it's likely a late echo
+        // of our own update. Extract the base title from line 1 instead of
+        // treating the whole decorated string as the new base title.
+        if (canonicalizeTitleForCompare(args.incomingTitle) ===
+            canonicalizeTitleForCompare(args.sessionState.lastAppliedTitle || '')) {
+            return;
+        }
+        if (looksDecorated(args.incomingTitle)) {
+            debug(`ignoring late decorated echo for session ${args.sessionID}`);
+            return;
+        }
+        args.sessionState.baseTitle = normalizeBaseTitle(args.incomingTitle);
+        args.sessionState.lastAppliedTitle = undefined;
+        deps.markDirty(deps.state.sessionDateMap[args.sessionID]);
+        deps.scheduleSave();
+        args.scheduleRefresh(args.sessionID);
+    };
+    const restoreSessionTitle = async (sessionID) => {
+        const session = await deps.client.session
+            .get({
+            path: { id: sessionID },
+            query: { directory: deps.directory },
+            throwOnError: true,
+        })
+            .catch(swallow('restoreSessionTitle:get'));
+        if (!session)
+            return;
+        const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
+        const baseTitle = normalizeBaseTitle(sessionState.baseTitle);
+        if (session.data.title === baseTitle)
+            return;
+        await deps.client.session
+            .update({
+            path: { id: sessionID },
+            query: { directory: deps.directory },
+            body: { title: baseTitle },
+            throwOnError: true,
+        })
+            .catch(swallow('restoreSessionTitle:update'));
+        sessionState.lastAppliedTitle = undefined;
+        deps.markDirty(deps.state.sessionDateMap[sessionID]);
+        deps.scheduleSave();
+    };
+    const restoreAllVisibleTitles = async () => {
+        const list = await deps.client.session
+            .list({
+            query: { directory: deps.directory },
+            throwOnError: true,
+        })
+            .catch(swallow('restoreAllVisibleTitles:list'));
+        if (!list?.data)
+            return;
+        const touched = list.data.filter((s) => deps.state.sessions[s.id]?.lastAppliedTitle);
+        await mapConcurrent(touched, deps.restoreConcurrency, async (s) => {
+            await restoreSessionTitle(s.id);
+        });
+    };
+    return {
+        applyTitle,
+        handleSessionUpdatedTitle,
+        restoreSessionTitle,
+        restoreAllVisibleTitles,
+        forgetSession,
+    };
+}

package/dist/title_refresh.d.ts

@@ -0,0 +1,9 @@
+export declare function createTitleRefreshScheduler(options: {
+    apply: (sessionID: string) => Promise<void>;
+    onError?: (error: unknown) => void;
+}): {
+    schedule: (sessionID: string, delay?: number) => void;
+    apply: (sessionID: string) => Promise<void>;
+    cancel: (sessionID: string) => void;
+    dispose: () => void;
+};

package/dist/title_refresh.js

@@ -0,0 +1,46 @@
+export function createTitleRefreshScheduler(options) {
+    const refreshTimer = new Map();
+    const applyLocks = new Map();
+    const onError = options.onError || (() => { });
+    const applyLocked = async (sessionID) => {
+        const previous = applyLocks.get(sessionID) ?? Promise.resolve();
+        const promise = previous
+            .then(() => options.apply(sessionID))
+            .catch(onError)
+            .finally(() => {
+            if (applyLocks.get(sessionID) === promise) {
+                applyLocks.delete(sessionID);
+            }
+        });
+        applyLocks.set(sessionID, promise);
+        await promise;
+    };
+    const schedule = (sessionID, delay = 250) => {
+        const previous = refreshTimer.get(sessionID);
+        if (previous)
+            clearTimeout(previous);
+        const timer = setTimeout(() => {
+            refreshTimer.delete(sessionID);
+            void applyLocked(sessionID);
+        }, delay);
+        refreshTimer.set(sessionID, timer);
+    };
+    const cancel = (sessionID) => {
+        const timer = refreshTimer.get(sessionID);
+        if (timer)
+            clearTimeout(timer);
+        refreshTimer.delete(sessionID);
+    };
+    const dispose = () => {
+        for (const timer of refreshTimer.values())
+            clearTimeout(timer);
+        refreshTimer.clear();
+        applyLocks.clear();
+    };
+    return {
+        schedule,
+        apply: applyLocked,
+        cancel,
+        dispose,
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,56 @@
+import type { QuotaSnapshot } from './types.js';
+import type { UsageSummary } from './usage.js';
+export declare function createQuotaSidebarTools(deps: {
+    getTitleEnabled: () => boolean;
+    setTitleEnabled: (enabled: boolean) => void;
+    scheduleSave: () => void;
+    refreshSessionTitle: (sessionID: string, delay?: number) => void;
+    restoreAllVisibleTitles: () => Promise<void>;
+    showToast: (period: 'session' | 'day' | 'week' | 'month' | 'toggle', message: string) => Promise<void>;
+    summarizeForTool: (period: 'session' | 'day' | 'week' | 'month', sessionID: string, includeChildren: boolean) => Promise<UsageSummary>;
+    getQuotaSnapshots: (providerIDs: string[], options?: {
+        allowDefault?: boolean;
+    }) => Promise<QuotaSnapshot[]>;
+    renderMarkdownReport: (period: string, usage: UsageSummary, quotas: QuotaSnapshot[], options?: {
+        showCost?: boolean;
+    }) => string;
+    renderToastMessage: (period: string, usage: UsageSummary, quotas: QuotaSnapshot[], options?: {
+        showCost?: boolean;
+        width?: number;
+    }) => string;
+    config: {
+        sidebar: {
+            showCost: boolean;
+            width: number;
+            includeChildren: boolean;
+        };
+    };
+}): {
+    quota_summary: {
+        description: string;
+        args: {
+            period: import("zod").ZodOptional<import("zod").ZodEnum<{
+                day: "day";
+                week: "week";
+                month: "month";
+                session: "session";
+            }>>;
+            toast: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            includeChildren: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        };
+        execute(args: {
+            period?: "day" | "week" | "month" | "session" | undefined;
+            toast?: boolean | undefined;
+            includeChildren?: boolean | undefined;
+        }, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<string>;
+    };
+    quota_show: {
+        description: string;
+        args: {
+            enabled: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        };
+        execute(args: {
+            enabled?: boolean | undefined;
+        }, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<string>;
+    };
+};

package/dist/tools.js

@@ -0,0 +1,63 @@
+import { tool } from '@opencode-ai/plugin/tool';
+const z = tool.schema;
+export function createQuotaSidebarTools(deps) {
+    return {
+        quota_summary: tool({
+            description: 'Show usage and quota summary for session/day/week/month.',
+            args: {
+                period: z.enum(['session', 'day', 'week', 'month']).optional(),
+                toast: z.boolean().optional(),
+                includeChildren: z
+                    .boolean()
+                    .optional()
+                    .describe('For period=session, include descendant subagent sessions in usage aggregation.'),
+            },
+            execute: async (args, context) => {
+                const period = args.period || 'session';
+                const includeChildren = period === 'session'
+                    ? (args.includeChildren ?? deps.config.sidebar.includeChildren)
+                    : false;
+                const usage = await deps.summarizeForTool(period, context.sessionID, includeChildren);
+                deps.scheduleSave();
+                // For quota_summary, always show all subscription quota balances,
+                // regardless of which providers were used in the session.
+                const quotas = await deps.getQuotaSnapshots([], { allowDefault: true });
+                const markdown = deps.renderMarkdownReport(period, usage, quotas, {
+                    showCost: deps.config.sidebar.showCost,
+                });
+                if (args.toast !== false) {
+                    await deps.showToast(period, deps.renderToastMessage(period, usage, quotas, {
+                        showCost: deps.config.sidebar.showCost,
+                        width: Math.max(44, deps.config.sidebar.width + 18),
+                    }));
+                }
+                return markdown;
+            },
+        }),
+        quota_show: tool({
+            description: 'Toggle sidebar title display mode. When on, titles show token usage and quota; when off, titles revert to original.',
+            args: {
+                enabled: z
+                    .boolean()
+                    .optional()
+                    .describe('Explicit on/off. Omit to toggle current state.'),
+            },
+            execute: async (args, context) => {
+                const current = deps.getTitleEnabled();
+                const next = args.enabled !== undefined ? args.enabled : !current;
+                deps.setTitleEnabled(next);
+                deps.scheduleSave();
+                if (next) {
+                    // Turning on — re-render current session immediately
+                    deps.refreshSessionTitle(context.sessionID, 0);
+                    await deps.showToast('toggle', 'Sidebar usage display: ON');
+                    return 'Sidebar usage display is now ON. Session titles will show token usage and quota.';
+                }
+                // Turning off — restore all touched sessions to base titles
+                await deps.restoreAllVisibleTitles();
+                await deps.showToast('toggle', 'Sidebar usage display: OFF');
+                return 'Sidebar usage display is now OFF. Session titles restored to original.';
+            },
+        }),
+    };
+}

package/dist/types.d.ts

@@ -67,9 +67,13 @@ export type IncrementalCursor = {
     lastMessageId?: string;
     /** Timestamp of the last processed assistant message. */
     lastMessageTime?: number;
+    /** IDs processed at lastMessageTime (for same-timestamp correctness). */
+    lastMessageIdsAtTime?: string[];
 };
 export type SessionState = SessionTitleState & {
     createdAt: number;
+    /** Parent session ID for subagent child sessions. */
+    parentID?: string;
     usage?: CachedSessionUsage;
     /** Incremental aggregation cursor (P1). */
     cursor?: IncrementalCursor;
@@ -93,6 +97,14 @@ export type QuotaSidebarConfig = {
         width: number;
         showCost: boolean;
         showQuota: boolean;
+        /** Include descendant subagent sessions in session-scoped usage/quota. */
+        includeChildren: boolean;
+        /** Max descendant traversal depth when includeChildren is enabled. */
+        childrenMaxDepth: number;
+        /** Max number of descendant sessions to include when includeChildren is enabled. */
+        childrenMaxSessions: number;
+        /** Concurrency for fetching descendant session messages (bounded). */
+        childrenConcurrency: number;
     };
     quota: {
         refreshMs: number;