@nexus-aethra/dshell-usage 0.1.6

package/lib/types/route.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The usage route: one exact `/api` endpoint behind dsh's existing trust and
+ * authentication fence, mirroring the pipe and files routes' shape.
+ *
+ * Both halves of the feature go through it. Reading is the common case; the
+ * scan is offered here too because it is the host that owns the session events
+ * and the index, so the browser asks for one rather than doing one.
+ */
+import type { ConnectionFetchRoute } from '@deepseek-ai/dsh-client-connection';
+import type { UsageStore } from './index-store.js';
+import type { UsageScanner } from './scan.js';
+/** What the route needs from the plugin that owns it. */
+export interface UsageRouteDeps {
+    readonly store: UsageStore;
+    readonly scanner: UsageScanner;
+}
+/** Bind the route to the index and the scanner. */
+export declare function createUsageRoute(deps: UsageRouteDeps): ConnectionFetchRoute;
+//# sourceMappingURL=route.d.ts.map

package/lib/types/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/route.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA;AAG9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE7C,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAC/B;AAgBD,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAsC3E"}

package/lib/types/scan.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The scan: walk every session's durable log, count the token usage each model
+ * turn reported, and add it to the index.
+ *
+ * Where the numbers come from. dsh attaches provider-reported accounting to the
+ * `assistant/message` event itself — `data.usage` — and the same event's
+ * `data.message.source` names the route that produced it. Usage and route
+ * therefore travel together on one event and nothing has to be paired up or
+ * inferred, which is what makes a scan over history as reliable as one over a
+ * live session.
+ *
+ * Incremental by session. The index keeps the highest seq counted for each
+ * session, and a session whose log has not grown is skipped after a cheap
+ * metadata listing rather than a full read. A session that has grown is read
+ * whole and filtered down to the events past its cursor, so a rescan costs one
+ * decode per touched session and nothing for the rest.
+ *
+ * Writes are batched, never per event and never per session. A scan accumulates
+ * its rows in memory and hands them to the store once, and {@link UsageScanner.schedule}
+ * coalesces concurrent callers behind a single flight plus a minimum interval,
+ * so a page opened repeatedly still produces at most one transaction per
+ * interval rather than one per open.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { UsageBuckets, UsageKey } from './protocol.js';
+import { type UsageStore } from './index-store.js';
+/**
+ * The slice of `ctx.sessionQuery` a scan uses, typed structurally so this
+ * package does not depend on the query engine's full surface.
+ */
+export interface UsageSessionQuery {
+    listSessions: (signal?: AbortSignal) => Promise<readonly {
+        header: {
+            id: string;
+        };
+    }[]>;
+    listEvents: (sessionId: string) => Promise<readonly {
+        seq: number;
+    }[]>;
+    readSession: (sessionId: string) => Promise<{
+        events: readonly SessionEvent[];
+    }>;
+}
+/** Scan pacing. Both are deliberate: the host must not write per turn. */
+export interface UsageScanPolicy {
+    /** Triggers inside this window share one scan. */
+    readonly minIntervalMs: number;
+    /** How long a scan will wait for a burst of triggers to settle. */
+    readonly debounceMs: number;
+}
+/** Defaults: a page can be reopened freely without a second disk write. */
+export declare const DEFAULT_SCAN_POLICY: UsageScanPolicy;
+/** One counted turn, before it is folded into a bucket. */
+interface CountedTurn extends UsageBuckets {
+    readonly day: string;
+    readonly provider: string;
+    readonly model: string;
+}
+/** The route and usage one `assistant/message` carries, or undefined. */
+export declare function usageOf(event: SessionEvent): CountedTurn | undefined;
+/** Fold counted turns into one row per (day, route). */
+export declare function foldTurns(turns: readonly CountedTurn[]): (UsageKey & UsageBuckets)[];
+/** What one session contributed, for the caller's log line. */
+export interface ScanOutcome {
+    readonly sessions: number;
+    readonly read: number;
+    readonly turns: number;
+    /** Sessions whose log could not be decoded, so their usage is not counted. */
+    readonly skipped: number;
+    /** Why the first skipped session was skipped; absent when nothing was. */
+    readonly skipReason: string | undefined;
+    readonly written: boolean;
+}
+/** Serialises scans and holds the write-behind window. */
+export declare class UsageScanner {
+    #private;
+    private readonly store;
+    private readonly query;
+    private readonly policy;
+    constructor(store: UsageStore, query: UsageSessionQuery, policy?: UsageScanPolicy);
+    /**
+     * Ask for a scan, without waiting for one that is already running.
+     *
+     * A caller inside the minimum interval is answered with what the last scan
+     * did, so the page never blocks on a second pass it does not need.
+     */
+    schedule(): Promise<ScanOutcome>;
+    /** Scan now, ignoring pacing. The page's explicit rebuild action. */
+    rescan(): Promise<ScanOutcome>;
+    /** Stop a waiting trigger; the plugin's teardown path. */
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=scan.d.ts.map

package/lib/types/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE5D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS;QAAE,MAAM,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,CAAC,CAAA;IACtF,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;IACtE,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;KAAE,CAAC,CAAA;CACjF;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,EAAE,eAA4D,CAAA;AAE9F,2DAA2D;AAC3D,UAAU,WAAY,SAAQ,YAAY;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,CAqBpE;AAcD,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC,EAAE,CAyBpF;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,0DAA0D;AAC1D,qBAAa,YAAY;;IAMrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,iBAAiB,EACxB,MAAM,GAAE,eAAqC;IAGhE;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAoBtC,qEAAqE;IAC/D,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAIpC,0DAA0D;IAC1D,OAAO,IAAI,IAAI;CA2DhB"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@nexus-aethra/dshell-usage",
+  "version": "0.1.6",
+  "description": "dshell usage: a durable per-model token index over every session's reported usage, and the settings page that charts it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nexus-Aethra/Nexus-Terminal.git",
+    "directory": "packages/dshell/usage"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    }
+  },
+  "dsh": {
+    "client": {
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@nexus-aethra/dshell-std": "^0.1.6"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-connection": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-query": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-connection": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-query": "0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^24",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly false && tsdown --config-loader tsx",
+    "build:host": "tsc -p tsconfig.json --emitDeclarationOnly false",
+    "build:client": "tsdown --config-loader tsx"
+  }
+}