@itookit/dsht 0.5.1 → 0.6.0

package/dist/cost/ledger.js

@@ -1,9 +1,9 @@
-import { chargeFor, costDay, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
+import { chargeFor, costDay, costMonthStart, costWeekStart, costWindowStart, DEFAULT_PRICES, pricesDigest, PRICING_ENGINE_VERSION } from "./pricing.js";
 import { foldSamples } from "./records.js";
-import { loadLedgers, saveLedger } from "./ledger-files.js";
+import { loadLedgers, pruneLedgers, saveLedger } from "./ledger-files.js";
 /** Reasons one slice keeps at most, so a broken table cannot grow the ledger without bound. */
 const UNPRICED_LIMIT = 8;
-/** Per-origin cache of folded session totals; every scan replaces a session at its cut. */
+/** Per-origin cache of folded session totals and day buckets; every scan replaces a session at its cut. */
 export class CostLedger {
     prices;
     directory;
@@ -34,10 +34,19 @@ export class CostLedger {
             return 'partial';
         return this.scannedAt !== undefined || this.sessions.size > 0 ? 'complete' : 'partial';
     }
-    /** Load the newest cut per session; a stored total is read as it was decided. */
-    async load() {
+    /** Load the newest cut per session; a stored total is read as it was decided.
+     *
+     * Slices and dead files that have left the retention window are deleted in the same pass, so the
+     * directory cannot grow with every session this client has ever seen. A slice is a projection of the
+     * host log, so letting one go costs a rescan of that session, never data.
+     * @param now - Clock that names the window, so a caller or a test can pin the boundary.
+     */
+    async load(now = Date.now()) {
         this.totals.clear();
         this.sessions = await loadLedgers(this.directory);
+        for (const sessionId of await pruneLedgers(this.directory, costWindowStart(now), this.sessions)) {
+            this.sessions.delete(sessionId);
+        }
     }
     /** Replace one session using all billing events through the opening snapshot cut.
      *
@@ -54,16 +63,28 @@ export class CostLedger {
         const current = this.sessions.get(sessionId);
         if ((current?.cut ?? -2) > cut)
             return;
-        const day = costDay(now);
+        const scanDay = costDay(now);
+        const floor = costWindowStart(now);
         const total = { amount: 0, unknown: 0, records: 0 };
-        const today = { day, amount: 0, unknown: 0, records: 0 };
+        const days = new Map();
         const unpriced = new Set();
+        /** The day bucket to add to, created on first use so a session reports only the days it touched. */
+        const dayBucket = (day) => {
+            const found = days.get(day);
+            if (found !== undefined)
+                return found;
+            const created = { day, amount: 0, unknown: 0, records: 0 };
+            days.set(day, created);
+            return created;
+        };
         for (const sample of foldSamples(events)) {
             const decision = chargeFor(this.prices, sample.provider, sample.model, sample.time, sample.usage);
-            // A request belongs to the day it settled on, so the day bucket only counts the requests of
-            // the calendar day this scan is running on; another day reads as nothing spent today. A request
-            // with no settlement time belongs to no day, so it is counted as unknown wherever it is read.
-            const buckets = sample.time === undefined || costDay(sample.time) === day ? [total, today] : [total];
+            // A request belongs to the day it settled on. One with no settlement time is attributed to the
+            // day of this scan, which is the only day it can reach without guessing a tariff band, and is
+            // where a reader looks for what makes today's total inexact.
+            const day = sample.time === undefined ? scanDay : costDay(sample.time);
+            // Only the window is stored, so a session a year old writes days, not a year of them.
+            const buckets = day < floor ? [total] : [total, dayBucket(day)];
             for (const bucket of buckets) {
                 bucket.records++;
                 if (decision.amount === undefined)
@@ -74,8 +95,8 @@ export class CostLedger {
             if (decision.amount === undefined && unpriced.size < UNPRICED_LIMIT)
                 unpriced.add(`${sample.provider}/${sample.model}: ${decision.reason}`);
         }
-        const saved = { version: 3, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
-            total, day: today, unpriced: [...unpriced] };
+        const saved = { version: 4, sessionId, cut, engine: PRICING_ENGINE_VERSION, catalog: this.catalog,
+            total, days: [...days.values()].sort((a, b) => a.day < b.day ? -1 : a.day > b.day ? 1 : 0), unpriced: [...unpriced] };
         // Another process may have persisted a newer cut of this session since it was last read.
         if (this.directory && !await saveLedger(this.directory, saved))
             return;
@@ -117,25 +138,56 @@ export class CostLedger {
     }
     /** Every session's requests on one Beijing calendar day.
      *
-     * A slice keeps only the day its last scan ran on, so another day reads as nothing spent today
-     * rather than as the last day that was scanned.
+     * The day is a real bucket rather than only the day a scan ran on, so asking for another day
+     * reports that day's spend; the retention window is what limits how far back the answer reaches.
      * @param now - Clock that names the day to report.
      * @returns The day's total across cached sessions.
      */
     today(now = Date.now()) {
         const day = costDay(now);
-        const cached = this.totals.get(`d:${day}`);
+        return this.period(day, day);
+    }
+    /** Every session's requests in the natural week containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The week-to-date total across cached sessions.
+     */
+    week(now = Date.now()) {
+        const day = costDay(now);
+        return this.period(costWeekStart(day), day);
+    }
+    /** Every session's requests in the natural month containing a day, through that day.
+     * @param now - Clock that names the day to report.
+     * @returns The month-to-date total across cached sessions.
+     */
+    month(now = Date.now()) {
+        const day = costDay(now);
+        return this.period(costMonthStart(day), day);
+    }
+    /** Sum stored day buckets over a Beijing day range, inclusive at both ends.
+     *
+     * Days outside the retention window are absent rather than zero, so a range wider than the window
+     * reports what is still kept — which is why the fold and this sum share one window constant.
+     * @param from - First day to include, YYYY-MM-DD.
+     * @param to - Last day to include, YYYY-MM-DD.
+     * @returns The range's total across cached sessions.
+     */
+    period(from, to) {
+        const key = `p:${from}..${to}`;
+        const cached = this.totals.get(key);
         if (cached)
             return cached;
         const result = { amount: 0, unknown: 0, records: 0 };
         for (const session of this.sessions.values()) {
-            if (session.day.day !== day)
-                continue;
-            result.amount += session.day.amount;
-            result.unknown += session.day.unknown;
-            result.records += session.day.records;
+            for (const day of session.days) {
+                // ISO day strings compare chronologically, so a lexical range is the day range.
+                if (day.day < from || day.day > to)
+                    continue;
+                result.amount += day.amount;
+                result.unknown += day.unknown;
+                result.records += day.records;
+            }
         }
-        this.totals.set(`d:${day}`, result);
+        this.totals.set(key, result);
         return result;
     }
 }

package/dist/cost/pricing.d.ts

@@ -29,6 +29,45 @@ export declare function pricesFrom(value: unknown): PriceVersion[];
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export declare function costDay(time: number): string;
+/** Beijing days of cost the ledger keeps, folds and reports.
+ *
+ * One number decides three things that have to agree: how much per-session history a slice stores,
+ * which slices a retention pass may delete, and how far back the day/week/month totals reach. Sixty
+ * days covers a natural month with room to compare it against the previous one.
+ */
+export declare const COST_WINDOW_DAYS = 60;
+/** First millisecond of a Beijing calendar day.
+ *
+ * China has had no daylight saving since 1991, so a Beijing day is exactly 24 hours and an explicit
+ * offset is exact rather than an approximation.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Epoch milliseconds.
+ */
+export declare function costDayStart(day: string): number;
+/** The Beijing day a whole number of days before another.
+ *
+ * The arithmetic is on the calendar date, not on an instant, so it cannot drift across a month, a
+ * year or a leap day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @param days - Days to subtract, zero or more.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costDaysBefore(day: string, days: number): string;
+/** The Monday that begins the natural week containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date of that week's Monday.
+ */
+export declare function costWeekStart(day: string): string;
+/** The first day of the natural month containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date, YYYY-MM-01.
+ */
+export declare function costMonthStart(day: string): string;
+/** Oldest Beijing day a ledger still keeps, so every retention decision uses one boundary.
+ * @param now - Clock that names the current day.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export declare function costWindowStart(now: number): string;
 /** Canonical form of a model name before matching.
  *
  * The host reports names that differ from the published table by width, case, surrounding space, or

package/dist/cost/pricing.js

@@ -117,6 +117,52 @@ export function pricesFrom(value) {
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export function costDay(time) { return new Date(time + 8 * 3600_000).toISOString().slice(0, 10); }
+/** Beijing days of cost the ledger keeps, folds and reports.
+ *
+ * One number decides three things that have to agree: how much per-session history a slice stores,
+ * which slices a retention pass may delete, and how far back the day/week/month totals reach. Sixty
+ * days covers a natural month with room to compare it against the previous one.
+ */
+export const COST_WINDOW_DAYS = 60;
+/** First millisecond of a Beijing calendar day.
+ *
+ * China has had no daylight saving since 1991, so a Beijing day is exactly 24 hours and an explicit
+ * offset is exact rather than an approximation.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Epoch milliseconds.
+ */
+export function costDayStart(day) { return Date.parse(`${day}T00:00:00+08:00`); }
+/** The Beijing day a whole number of days before another.
+ *
+ * The arithmetic is on the calendar date, not on an instant, so it cannot drift across a month, a
+ * year or a leap day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @param days - Days to subtract, zero or more.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export function costDaysBefore(day, days) {
+    const [year, month, date] = day.split('-').map(Number);
+    return new Date(Date.UTC(year, month - 1, date - days)).toISOString().slice(0, 10);
+}
+/** The Monday that begins the natural week containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date of that week's Monday.
+ */
+export function costWeekStart(day) {
+    const [year, month, date] = day.split('-').map(Number);
+    const weekday = new Date(Date.UTC(year, month - 1, date)).getUTCDay();
+    return costDaysBefore(day, (weekday + 6) % 7);
+}
+/** The first day of the natural month containing a Beijing day.
+ * @param day - Beijing calendar date, YYYY-MM-DD.
+ * @returns Beijing calendar date, YYYY-MM-01.
+ */
+export function costMonthStart(day) { return `${day.slice(0, 8)}01`; }
+/** Oldest Beijing day a ledger still keeps, so every retention decision uses one boundary.
+ * @param now - Clock that names the current day.
+ * @returns Beijing calendar date, YYYY-MM-DD.
+ */
+export function costWindowStart(now) { return costDaysBefore(costDay(now), COST_WINDOW_DAYS - 1); }
 /** Canonical form of a model name before matching.
  *
  * The host reports names that differ from the published table by width, case, surrounding space, or

package/dist/cost/scanner.js

@@ -45,6 +45,7 @@ export async function sessionCostHistory(client, session, signal, onPage, onReco
 }
 /** Page one addressed session's history into the billing events the ledger folds. */
 async function readCostHistory(client, address, signal, onPage, onRecords) {
+    signal.throwIfAborted();
     onPage?.();
     const snapshot = await new Promise((resolve, reject) => {
         let sub;

package/dist/cost/types.d.ts

@@ -52,7 +52,7 @@ export interface CostTotal {
     unknown: number;
     records: number;
 }
-/** One Beijing calendar day's requests, kept only for the day a scan ran on. */
+/** One Beijing calendar day's requests, kept for every day inside the retention window. */
 export interface DayTotal extends CostTotal {
     day: string;
 }
@@ -64,14 +64,20 @@ export interface DayTotal extends CostTotal {
  * rules and the table behind these totals, so a process holding an older one cannot overwrite them.
  */
 export interface SavedCost {
-    version: 3;
+    version: 4;
     sessionId: string;
     /** Durable sequence the fold reached; a scan that opened an older cut may not replace this slice. */
     cut: number;
     engine: number;
     catalog: string;
     total: CostTotal;
-    day: DayTotal;
+    /** One entry per Beijing day this session spent inside the retention window, oldest first.
+     *
+     * Days older than the window are dropped as the slice is written, so the file cannot grow with a
+     * session's history. A day a later scan no longer reports is simply gone from the next slice: the
+     * host log, not this file, is what a day's total is re-derived from.
+     */
+    days: DayTotal[];
     /** Distinct reasons an amount is missing, bounded, so a panel can say what makes a total inexact. */
     unpriced: string[];
 }

package/dist/session/controller.d.ts

@@ -1,6 +1,6 @@
 import type { HostAccess } from '../transport/host.ts';
 import { type Json, type ObjectValue } from '../transport/wire.ts';
-import type { ControllerStore, State } from '../state.ts';
+import type { SessionStore } from './state.ts';
 import { type SessionRender } from './history.ts';
 import type { HistoryLimits } from './memory.ts';
 import { type FileReference } from './references.ts';
@@ -19,16 +19,18 @@ export declare class SessionController {
     private readonly connection;
     private readonly historyLimits;
     private follow;
-    private interactions;
+    private readonly history;
+    private readonly interactions;
+    private readonly navigation;
     /** Reading protection: reclamation pauses while the reader is away from the live end. */
     private historyPinned;
     /** Host runtime mirrors for every session this connection has seen. */
     private readonly runtime;
     /** Cancels the background prompt backfill of the previous selection. */
-    private promptBackfill?;
+    private readonly promptBackfill;
     /** Prompts of sessions this process has already read, so re-opening one costs no page request. */
     private readonly promptCache;
-    /** Prompt index, composer and reading view of the selected session; the instance `State.session` exposes. */
+    /** Prompt index, record, history window and interaction state of the selected session. */
     private get info();
     private get prompts();
     private stoppingSession?;
@@ -36,13 +38,13 @@ export declare class SessionController {
     private admission;
     /** Admission order of this session's writes, so two concurrent decisions cannot interleave. */
     private readonly mutations;
-    constructor(store: ControllerStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits, report?: (admission: MutationAdmission) => void);
+    constructor(store: SessionStore, host: HostAccess, connection: ConnectionView, historyLimits: HistoryLimits, report?: (admission: MutationAdmission) => void);
     /** Host running state covers model generation, tools, and waits between assistant attempts. */
     get running(): boolean;
     /** Current title projection, falling back to the list title and then the session ID. */
     get sessionName(): string | undefined;
     /** Current agent-preset name, matching the web header's built-in labels and custom metadata. */
-    get sessionMode(): string | undefined;
+    sessionMode(presets?: readonly ObjectValue[]): string | undefined;
     /** Epoch start from the retained turn log, or when this client first observed the run. */
     get workingSince(): number | undefined;
     /** Present only sessions explicitly accounted to the selected workspace. */
@@ -76,15 +78,15 @@ export declare class SessionController {
     beginGeneration(): void;
     /** Invalidate in-flight work and drop transient interactions when a generation ends. */
     endGeneration(): void;
-    /** Wait for an in-flight cancellation so shutdown leaves nothing running. */
+    /** Wait for cancellation and foreground history tasks before releasing their records. */
     settle(): Promise<void>;
     /** Release the selected transcript and its layout caches. */
     release(): void;
     /** Pending interactions for the selected chat session, derived independently of frame order.
-     * @param state - State being published.
+     * @param sessionId - Session whose pending interactions are being published.
      * @returns Retained question and approval frames for that session.
      */
-    pendingFor(state: State): PendingInteraction[];
+    pendingFor(sessionId: string | undefined): PendingInteraction[];
     /** Unanswered interactions by session, so a list can show who is waiting without opening them.
      *
      * The host delivers approval and question waterfalls for every session on one stream, and this
@@ -127,7 +129,9 @@ export declare class SessionController {
     /** Refresh both lists from the host, then show the requested picker.
      * @param screen - Picker to display after the refresh.
      */
-    showPicker(screen: 'workspaces' | 'sessions'): Promise<void>;
+    showPicker(screen: 'workspaces' | 'sessions', signal?: AbortSignal): Promise<void>;
+    /** Refresh navigation data without taking the reader to another screen. */
+    refreshLists(): Promise<void>;
     /** Return to the selected conversation without re-selecting it.
      *
      * A picker opened over a conversation is a detour: leaving it must not re-subscribe, reload the
@@ -152,11 +156,11 @@ export declare class SessionController {
     /** Open a workspace picker, or resolve a workspace by ID, exact title/path, or unique ID prefix.
      * @param query - Workspace target, if any.
      */
-    switchWorkspace(query?: string): Promise<void>;
+    switchWorkspace(query?: string, signal?: AbortSignal): Promise<void>;
     /** Guide workspace selection, list all sessions with `all`, or resolve an exact session target.
      * @param query - Session target, `all`, or nothing for the guided picker.
      */
-    switchSession(query?: string): Promise<void>;
+    switchSession(query?: string, signal?: AbortSignal): Promise<void>;
     /** Prompt for a host path without starting a local agent. */
     enterPath(): void;
     /** Adopt the workspace whose registered path contains the directory this client runs in.
@@ -171,9 +175,9 @@ export declare class SessionController {
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */
-    createWorkspace(path: string): Promise<void>;
+    createWorkspace(path: string, signal?: AbortSignal): Promise<void>;
     /** Create a session only after the user explicitly selects New session. */
-    createSession(): Promise<void>;
+    createSession(signal?: AbortSignal): Promise<void>;
     /** Create a session for another purpose without selecting it, named so a reader can tell it apart.
      *
      * A verifier runs in its own session while the reviewed session stays selected, so this never
@@ -193,6 +197,9 @@ export declare class SessionController {
      * @param sessionId - Session to follow.
      */
     selectSession(sessionId: string): Promise<void>;
+    /** Reattach the selected conversation after reconnect, keeping the current navigation context. */
+    restoreSelectedSession(): void;
+    private followSession;
     /** Wait for the selected follow snapshot, failing on disconnect or cancellation.
      * @param signal - Cancels waiting without closing the session.
      */
@@ -311,11 +318,6 @@ export declare class SessionController {
      * @returns Whether any older prompt was recovered.
      */
     refillRecall(): boolean;
-    /** Seed recall from a complete cached entry, so an open that follows a scan costs no request.
-     * @param sessionId - Session being opened.
-     * @returns Whether the cache covered this session.
-     */
-    private adoptCachedPrompts;
     /** Fold one history page the cost scan already read into the prompt cache.
      *
      * The scan reads every session's whole history on connect, so this is where two readers stop
@@ -328,29 +330,17 @@ export declare class SessionController {
      * @param sessionId - Session the scan finished.
      */
     rememberScanDone(sessionId: string): void;
-    /** Fold every prompt the host still holds into the recall index, in the background.
-     *
-     * Session start delivers only the newest window, so without this the arrows could reach older
-     * prompts but not show them without paging first. Each page is parsed into a temporary transcript
-     * and only its prompts are kept, so the live record, its memory window and the row cache never
-     * grow. The walk is bounded and the next selection cancels it; anything past the bound is still
-     * reachable through the lazy backward step.
-     * @param sessionId - Session being opened.
-     * @param selection - Selector generation that must still be current.
-     */
-    private backfillPrompts;
     /** Search one page at a time, preserving only the first 200 matches and releasing temporary content.
      * @param query - Literal, case-insensitive text including folded reasoning.
      * @param signal - Cancels HTTP and processing without cancelling the agent.
      * @returns Newest-first bounded summaries and an explicit truncation flag.
      */
     searchHistory(query: string, signal: AbortSignal): Promise<HistorySearch>;
-    /** Load a separate small window ending at a search target; the live transcript keeps following.
+    /** Select a readable window by sequence; temporary records never escape to the UI.
      * @param target - Durable message sequence to display.
      * @param signal - Cancels the target-page request.
-     * @returns A caller-owned historical window that must be disposed when closed.
      */
-    historyAt(target: number, signal: AbortSignal): Promise<Transcript>;
+    openHistory(target: number, signal: AbortSignal): Promise<void>;
     /** Load the prefix required for an explicit history jump; never loop on an unadvancing page.
      * @param target - Visible record sequence, or first for the oldest available history.
      * @param signal - Cancels local paging without interrupting the remote agent.
@@ -364,6 +354,4 @@ export declare class SessionController {
     private releaseTranscript;
     /** @returns The selected session identity, or a `Select a session first` failure. */
     private get sessionId();
-    /** Answer one retained waterfall through the connection's event-result endpoint. */
-    private reply;
 }