@jetcrab/pi-desk-usage 0.0.0-stage → 1.0.0

package/dist/l4-usage-calendar.js

@@ -0,0 +1,186 @@
+export const HOUR_MS = 60 * 60 * 1000;
+export const DAY_MS = 24 * HOUR_MS;
+const EMPTY_TOTALS = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0
+};
+const formatters = new Map();
+function zonedParts(value, timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-CA', {
+            timeZone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hourCycle: 'h23'
+        });
+        if (formatters.size >= 8)
+            formatters.delete(formatters.keys().next().value);
+        formatters.set(timeZone, formatter);
+    }
+    return Object.fromEntries(formatter
+        .formatToParts(value)
+        .filter((part) => part.type !== 'literal')
+        .map((part) => [part.type, Number(part.value)]));
+}
+function dateKeyFromParts(year, month, day) {
+    return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+export function dateKeyAt(value, timeZone = 'UTC') {
+    const parts = zonedParts(value, timeZone);
+    return dateKeyFromParts(parts.year, parts.month, parts.day);
+}
+export function dateStart(date, timeZone = 'UTC') {
+    const [year, month, day] = date.split('-').map(Number);
+    const utc = Date.UTC(year, month - 1, day);
+    let low = utc - 2 * DAY_MS;
+    let high = utc + 2 * DAY_MS;
+    // 查找该日期的第一个真实时刻，午夜被夏令时跳过时也不假定固定偏移。
+    while (high - low > 1) {
+        const middle = Math.floor((low + high) / 2);
+        if (dateKeyAt(middle, timeZone) < date)
+            low = middle;
+        else
+            high = middle;
+    }
+    return high;
+}
+function offsetAt(value, timeZone) {
+    const parts = zonedParts(value, timeZone);
+    return (Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second) -
+        Math.floor(value / 1000) * 1000);
+}
+export function zonedHourStart(value, timeZone = 'UTC') {
+    const parts = zonedParts(value, timeZone);
+    let low = value - parts.minute * 60_000 - parts.second * 1000 - (value % 1000);
+    const offset = offsetAt(value, timeZone);
+    if (offsetAt(low, timeZone) === offset)
+        return low;
+    // 半小时切换可能使本次小时从 :30 开始；保留当前重复小时的实际边界。
+    let high = value;
+    while (high - low > 1) {
+        const middle = Math.floor((low + high) / 2);
+        if (offsetAt(middle, timeZone) === offset)
+            high = middle;
+        else
+            low = middle;
+    }
+    return high;
+}
+export function addDays(date, amount) {
+    const [year, month, day] = date.split('-').map(Number);
+    const value = new Date(Date.UTC(year, month - 1, day + amount));
+    return dateKeyFromParts(value.getUTCFullYear(), value.getUTCMonth() + 1, value.getUTCDate());
+}
+export function monthKeyAt(value, timeZone = 'UTC') {
+    return dateKeyAt(value, timeZone).slice(0, 7);
+}
+export function addMonths(monthKey, amount) {
+    const [year, month] = monthKey.split('-').map(Number);
+    const value = new Date(Date.UTC(year, month - 1 + amount, 1));
+    return `${value.getUTCFullYear()}-${String(value.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+export function monthRange(monthKey, timeZone = 'UTC') {
+    return {
+        startAt: dateStart(`${monthKey}-01`, timeZone),
+        endAt: dateStart(`${addMonths(monthKey, 1)}-01`, timeZone)
+    };
+}
+export function monthWeekdayOffset(monthKey) {
+    const weekday = new Date(`${monthKey}-01T00:00:00Z`).getUTCDay();
+    return weekday === 0 ? 6 : weekday - 1;
+}
+export function formatMonth(monthKey, timeZone = 'UTC') {
+    return new Intl.DateTimeFormat('zh-CN', {
+        timeZone,
+        year: 'numeric',
+        month: 'long'
+    }).format(monthRange(monthKey, timeZone).startAt);
+}
+export function usageBucketRanges(startAt, endAt, bucketMs, timeZone = 'UTC') {
+    const buckets = [];
+    let cursor = startAt;
+    while (cursor < endAt) {
+        const nextDay = dateStart(addDays(dateKeyAt(cursor, timeZone), 1), timeZone);
+        const dayEnd = Math.min(endAt, nextDay);
+        while (cursor < dayEnd) {
+            // 日粒度使用完整自然日；更细粒度在午夜截断，次日重新开始。
+            const bucketEnd = bucketMs === DAY_MS ? dayEnd : Math.min(dayEnd, cursor + bucketMs);
+            buckets.push({ startAt: cursor, endAt: bucketEnd });
+            cursor = bucketEnd;
+        }
+    }
+    return buckets;
+}
+export function usageBucketIndex(buckets, timestamp) {
+    let low = 0;
+    let high = buckets.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (buckets[middle].endAt <= timestamp)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+function pointTotals(point, modelKey) {
+    if (!modelKey)
+        return point.totals;
+    return point.models.find((model) => model.key === modelKey)?.totals ?? EMPTY_TOTALS;
+}
+function addTotals(target, value) {
+    target.input += value.input;
+    target.output += value.output;
+    target.cacheRead += value.cacheRead;
+    target.cacheWrite += value.cacheWrite;
+    target.cost += value.cost;
+}
+function aggregateTotalsByDate(points, modelKey, timeZone) {
+    const totalsByDate = new Map();
+    for (const point of points) {
+        const date = dateKeyAt(point.startAt, timeZone);
+        const totals = totalsByDate.get(date) ?? { ...EMPTY_TOTALS };
+        addTotals(totals, pointTotals(point, modelKey));
+        totalsByDate.set(date, totals);
+    }
+    return totalsByDate;
+}
+export function buildUsageCalendarRange(startAt, endAt, points, modelKey, timeZone = 'UTC') {
+    if (endAt <= startAt)
+        return [];
+    const totalsByDate = aggregateTotalsByDate(points, modelKey, timeZone);
+    const firstDate = dateKeyAt(startAt, timeZone);
+    const lastDate = dateKeyAt(endAt - 1, timeZone);
+    const days = [];
+    let date = firstDate;
+    let dayStart = dateStart(date, timeZone);
+    while (true) {
+        const dayEnd = dateStart(addDays(date, 1), timeZone);
+        days.push({
+            date,
+            startAt: Math.max(startAt, dayStart),
+            endAt: Math.min(endAt, dayEnd),
+            totals: totalsByDate.get(date) ?? { ...EMPTY_TOTALS }
+        });
+        if (date === lastDate)
+            break;
+        date = addDays(date, 1);
+        dayStart = dayEnd;
+    }
+    return days;
+}
+export function buildUsageCalendar(monthKey, points, modelKey, dataEndAt, timeZone = 'UTC') {
+    const range = monthRange(monthKey, timeZone);
+    const days = buildUsageCalendarRange(range.startAt, range.endAt, points, modelKey, timeZone);
+    if (dataEndAt === undefined || dataEndAt >= range.endAt)
+        return days;
+    return days.map((day) => day.startAt < dataEndAt ? { ...day, endAt: Math.min(day.endAt, dataEndAt) } : day);
+}

package/dist/l4-usage-files.d.ts

@@ -0,0 +1,5 @@
+import type { UsageFileDescriptor } from './usage-scan.js';
+export declare function pathKey(value: string): string;
+export declare function nestedParentSessionId(filePath: string): string | null;
+export declare function descriptor(path: string, nestedSubagent: boolean): Promise<UsageFileDescriptor | null>;
+export declare function listStandardSessionFiles(root: string): Promise<UsageFileDescriptor[]>;

package/dist/l4-usage-files.js

@@ -0,0 +1,97 @@
+import { readdir, stat } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+const DIRECTORY_CONCURRENCY = 4;
+export function pathKey(value) {
+    const normalized = resolve(value);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+export function nestedParentSessionId(filePath) {
+    const parts = resolve(filePath).split(/[\\/]+/);
+    const index = parts.lastIndexOf('subagents');
+    return index >= 0 ? (parts[index + 1] ?? null) : null;
+}
+async function mapWithConcurrency(values, limit, mapper) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    async function run() {
+        while (nextIndex < values.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await mapper(values[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, values.length) }, () => run()));
+    return results;
+}
+export async function descriptor(path, nestedSubagent) {
+    try {
+        const metadata = await stat(path);
+        if (!metadata.isFile())
+            return null;
+        return {
+            path: resolve(path),
+            size: metadata.size,
+            modifiedAt: metadata.mtime.getTime(),
+            nestedSubagent
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isSessionJsonlFile(name) {
+    return name.endsWith('.jsonl') && !name.includes('.jsonl.');
+}
+async function nestedSessionFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await nestedSessionFiles(path)));
+        }
+        else if (entry.isFile() && isSessionJsonlFile(entry.name)) {
+            const file = await descriptor(path, true);
+            if (file)
+                files.push(file);
+        }
+    }
+    return files;
+}
+async function projectSessionFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const directFiles = await mapWithConcurrency(entries.filter((entry) => entry.isFile() && isSessionJsonlFile(entry.name)), DIRECTORY_CONCURRENCY, (entry) => descriptor(join(directory, entry.name), false));
+    const subagentDirectory = entries.find((entry) => entry.isDirectory() && entry.name === 'subagents');
+    const nested = subagentDirectory
+        ? await nestedSessionFiles(join(directory, subagentDirectory.name))
+        : [];
+    return [...directFiles.filter((file) => file !== null), ...nested];
+}
+export async function listStandardSessionFiles(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const rootFiles = await mapWithConcurrency(entries.filter((entry) => entry.isFile() && isSessionJsonlFile(entry.name)), DIRECTORY_CONCURRENCY, (entry) => descriptor(join(root, entry.name), false));
+    const directories = entries.filter((entry) => entry.isDirectory());
+    const nested = await mapWithConcurrency(directories, DIRECTORY_CONCURRENCY, (entry) => projectSessionFiles(join(root, entry.name)));
+    return [
+        ...rootFiles.filter((file) => file !== null),
+        ...nested.flat()
+    ];
+}

package/dist/l4-usage-format.d.ts

@@ -0,0 +1 @@
+export declare function formatTokens(value: number): string;

package/dist/l4-usage-format.js

@@ -0,0 +1,12 @@
+export function formatTokens(value) {
+    if (value < 1_000)
+        return Math.round(value).toLocaleString('zh-CN');
+    if (value < 1_000_000)
+        return `${(value / 1_000).toFixed(value < 10_000 ? 1 : 0)}K`;
+    if (value < 100_000_000) {
+        return `${(value / 1_000_000).toFixed(value < 10_000_000 ? 2 : 1)}M`;
+    }
+    const precision = value < 1_000_000_000 ? 2 : 1;
+    const formatted = (value / 100_000_000).toFixed(precision).replace(/\.?0+$/, '');
+    return `${formatted}亿`;
+}

package/dist/pi-desk.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@jetcrab/pi-desk-sdk/entry").PiDeskPluginDefinition;
+export default _default;

package/dist/pi-desk.js

@@ -0,0 +1,18 @@
+import { definePiDeskPlugin } from '@jetcrab/pi-desk-sdk/entry';
+import { UsageRuntime } from './usage-runtime.js';
+export default definePiDeskPlugin({
+    name: 'usage',
+    setup(plugin) {
+        const runtime = new UsageRuntime({
+            workSessions: plugin.host.workSessions,
+            settings: plugin.host.settings
+        });
+        plugin.registerMethod('report-get', (input, context) => runtime.report(input, context.signal));
+        plugin.registerMethod('session-list', (input, context) => runtime.sessions(input, context.signal));
+        plugin.registerMethod('session-analysis-get', (input, context) => runtime.sessionAnalysis(input, context.signal));
+        plugin.registerMethod('session-timeline-get', (input, context) => runtime.sessionTimeline(input, context.signal));
+        plugin.registerMethod('session-activity-get', (input, context) => runtime.sessionActivities(input, context.signal));
+        plugin.registerBrowserEntry('./dist/browser/entry.js');
+        return () => runtime.dispose();
+    }
+});

package/dist/protocol.d.ts

@@ -0,0 +1,189 @@
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+export interface UsageModelSnapshot {
+    key: string;
+    provider: string | null;
+    model: string | null;
+    label: string;
+    calls: number;
+    totals: UsageTotals;
+}
+export interface UsageSeriesPoint {
+    startAt: number;
+    endAt: number;
+    totals: UsageTotals;
+    models: UsageModelSnapshot[];
+}
+export interface UsageReportSnapshot {
+    generatedAt: number;
+    startAt: number;
+    endAt: number;
+    bucketMs: number;
+    totals: UsageTotals;
+    series: UsageSeriesPoint[];
+    models: UsageModelSnapshot[];
+    skippedFiles: number;
+}
+export interface UsageSubagentSessionSnapshot {
+    sessionId: string;
+    taskId: string;
+    title: string;
+    agentType: string | null;
+    startedAt: number;
+    updatedAt: number;
+    totals: UsageTotals;
+    models: UsageModelSnapshot[];
+}
+export interface UsageSessionSnapshot {
+    sessionId: string;
+    cwd: string;
+    title: string;
+    startedAt: number;
+    updatedAt: number;
+    totals: UsageTotals;
+    mainTotals: UsageTotals;
+    models: UsageModelSnapshot[];
+    subagents: UsageSubagentSessionSnapshot[];
+}
+export interface UsageSessionPage {
+    total: number;
+    offset: number;
+    limit: number;
+    items: UsageSessionSnapshot[];
+}
+export interface UsageStructureCounts {
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    compactions: number;
+    branchSummaries: number;
+}
+export type UsageAnalysisCallKind = 'assistant' | 'tool-result' | 'compaction' | 'branch-summary' | 'cache-warm' | 'usage';
+export interface UsageAnalysisCall {
+    timestamp: number;
+    sourceKey: string;
+    kind: UsageAnalysisCallKind;
+    modelKey: string;
+    requestedModel: string | null;
+    actualModel: string;
+    totals: UsageTotals;
+}
+interface UsageAnalysisSourceBase {
+    key: string;
+    kind: 'main' | 'subagent';
+    title: string;
+    startedAt: number;
+    updatedAt: number;
+    totals: UsageTotals;
+    models: UsageModelSnapshot[];
+    counts: UsageStructureCounts;
+    error: string | null;
+}
+export interface UsageMainAnalysisSource extends UsageAnalysisSourceBase {
+    key: 'main';
+    kind: 'main';
+}
+export interface UsageSubagentAnalysisSource extends UsageAnalysisSourceBase {
+    kind: 'subagent';
+    taskId: string;
+    agentType: string;
+    status: 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+    runCount: number;
+}
+export type UsageAnalysisSource = UsageMainAnalysisSource | UsageSubagentAnalysisSource;
+export interface UsageSessionAnalysisSnapshot {
+    generatedAt: number;
+    session: {
+        sessionId: string;
+        title: string;
+        cwd: string;
+        startedAt: number;
+        updatedAt: number;
+    };
+    inherited: UsageTotals | null;
+    sources: UsageAnalysisSource[];
+    recentCalls: UsageAnalysisCall[];
+}
+export interface UsageTimelinePoint {
+    at: number;
+    prompt: number;
+    cacheRead: number;
+}
+export interface UsageTimelineRun {
+    startAt: number;
+    endAt: number | null;
+}
+export interface UsageTimelineSourceSnapshot {
+    key: string;
+    kind: 'main' | 'subagent';
+    title: string;
+    agentType: string | null;
+    calls: number;
+    segments: UsageTimelinePoint[][];
+    runs: UsageTimelineRun[];
+}
+export interface UsageTimelineBucketSource {
+    sourceKey: string;
+    totals: UsageTotals;
+    calls: number;
+}
+export interface UsageTimelineBucket {
+    startAt: number;
+    endAt: number;
+    totals: UsageTotals;
+    calls: number;
+    sources: UsageTimelineBucketSource[];
+}
+export type UsageActivityKind = 'model' | 'tool' | 'subagent-run' | 'context-ignore' | 'compaction';
+export interface UsageActivity {
+    id: string;
+    timestamp: number;
+    endAt: number | null;
+    sourceKey: string;
+    kind: UsageActivityKind;
+    label: string;
+    detail: string | null;
+    status: 'completed' | 'failed' | 'running' | null;
+    totals: UsageTotals | null;
+}
+export type UsageTimelineMarkerKind = 'context-ignore' | 'compaction';
+export type UsageTimelineIgnoreMode = 'user-turns' | 'internal-turns' | 'combined';
+export interface UsageTimelineMarker {
+    x: number;
+    sourceKey: string;
+    kind: UsageTimelineMarkerKind;
+    timestamp: number;
+    mode: UsageTimelineIgnoreMode | null;
+    beforePrompt: number | null;
+    projectedPrompt: number | null;
+    afterPrompt: number | null;
+    tokensBefore: number | null;
+}
+export interface UsageSessionTimelineSnapshot {
+    generatedAt: number;
+    startAt: number;
+    endAt: number;
+    bucketMs: number;
+    totalCalls: number;
+    displayedPoints: number;
+    sampled: boolean;
+    buckets: UsageTimelineBucket[];
+    sources: UsageTimelineSourceSnapshot[];
+    markers: UsageTimelineMarker[];
+    activities: UsageActivity[];
+}
+export interface UsageSessionActivityPage {
+    startAt: number;
+    endAt: number;
+    total: number;
+    offset: number;
+    limit: number;
+    items: UsageActivity[];
+}
+export {};

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/usage-runtime.d.ts

@@ -0,0 +1,53 @@
+import type { PiDeskWorkSessionCapability, PluginJsonObject } from '@jetcrab/pi-desk-sdk/entry';
+import type { HostSettings } from '@jetcrab/pi-desk-sdk/settings';
+import type { UsageFileDescriptor, UsageFileScanResult } from './usage-scan.js';
+interface UsageRuntimeOptions {
+    sessionsRoot?: string;
+    workSessions?: PiDeskWorkSessionCapability;
+    settings?: HostSettings;
+    scanFiles?: (files: readonly UsageFileDescriptor[], signal: AbortSignal) => Promise<UsageFileScanResult[]>;
+    logger?: Pick<Console, 'info' | 'warn'>;
+}
+export declare class UsageRuntime {
+    private readonly sessionsRoot;
+    private readonly scanFiles;
+    private readonly logger;
+    private readonly workSessions;
+    private readonly settings;
+    private readonly cache;
+    private operation;
+    private coverage;
+    private skippedFiles;
+    private activeWorker;
+    private disposed;
+    constructor(options?: UsageRuntimeOptions);
+    report(input: PluginJsonObject, signal: AbortSignal): Promise<PluginJsonObject>;
+    sessions(input: PluginJsonObject, signal: AbortSignal): Promise<PluginJsonObject>;
+    sessionAnalysis(input: PluginJsonObject, signal: AbortSignal): Promise<PluginJsonObject>;
+    sessionTimeline(input: PluginJsonObject, signal: AbortSignal): Promise<PluginJsonObject>;
+    sessionActivities(input: PluginJsonObject, signal: AbortSignal): Promise<PluginJsonObject>;
+    dispose(): Promise<void>;
+    private readModelNames;
+    private total;
+    private series;
+    private sessionSnapshots;
+    private loadSessionDetails;
+    private requireWorkSession;
+    private loadSessionById;
+    private loadExactFile;
+    private timelineInputs;
+    private analysisCall;
+    private ensureIndexed;
+    private isCovered;
+    private runExclusive;
+    private refreshIndex;
+    private shouldLoad;
+    private loadChanged;
+    private childMetadata;
+    private indexedFiles;
+    private ownedEvents;
+    private pruneCache;
+    private isWithinSessionsRoot;
+    private scanWithWorker;
+}
+export {};