@qilin-agent/usage-local 0.0.0-stage → 3.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,43 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/usage-local/README.md
+/:
+  en: dbf0e5e5d7c08187
+  zh: a5963a8ffe7816e2
+/qilin-agent-usage-local:
+  en: 2ac187d34f177a36
+  zh: dcab7d7cef712115
+/qilin-agent-usage-local/summary:
+  en: 833fd7efccc9e442
+  zh: 4250bc5bfa28a5d9
+/qilin-agent-usage-local/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 3a2f21ff0dc3420d
+/qilin-agent-usage-local/use-this-package:
+  en: 7bc68467c9c365fb
+  zh: 83fd40bfd017fc85
+/qilin-agent-usage-local/use-this-package/composition:
+  en: df871995f5a3ee5b
+  zh: 2d5cb440823f25ee
+/qilin-agent-usage-local/use-this-package/reading-it:
+  en: bfb88e0547476a33
+  zh: 29c6a8ae0af13239
+/qilin-agent-usage-local/understand-the-implementation:
+  en: 80e48fc6d6ca6ef2
+  zh: 1a97b661f278089b
+/qilin-agent-usage-local/further-exploration:
+  en: 4b043f0582e7af81
+  zh: c6cdb616ad105536
+/qilin-agent-usage-local/model-experience:
+  en: 1a91494c3ffe7217
+  zh: 0a42f8cd71cf6099
+/qilin-agent-usage-local/model-experience/kv-cache-effect:
+  en: b7b95585d578fcf3
+  zh: b197ff5a878b8207
+/qilin-agent-usage-local/known-limitations-and-deferred-work:
+  en: b3eb808c464d540d
+  zh: 35aa8113dc2ccc9a
+/qilin-agent-usage-local/known-limitations-and-deferred-work/dev-note:
+  en: a215c99c66527a86
+  zh: 0529f506877de754

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+---
+description: "Local usage ledger for single-user surfaces: derives /api/usage/me from this runtime's own session logs with the token-meter derivation"
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/usage-local
+
+English | [中文](README.zh.md)
+
+## Summary
+
+A single-user surface — the desktop, a hand-started web runtime — has no deployment ledger to read usage from. This plugin is that surface's local ledger: it registers `GET /api/usage/me` on the shared API channel and derives the answer from the session logs the runtime owns, folding every Turn with the token-meter derivation. A deployment that keeps a ledger of its own reports usage through the external ledger and does not mount this row.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the row in compositions whose surfaces read usage locally — the shipped Web/desktop bundle does. A deployment whose runtime reports to a supervisor ledger leaves the row out.
+
+### Composition
+
+```yaml
+- name: '@qilin-agent/session'
+- name: '@qilin-agent/session-query-sqlite'
+- name: '@qilin-agent/usage-local'
+```
+
+The row declares no configuration. It reads the account-session gate like any other `/api` caller, so an unauthenticated request is refused before it reaches the derivation.
+
+### Reading it
+
+`GET /api/usage/me?from=<epoch ms>&to=<epoch ms>` answers `accountId`, the whole-ledger `total` (every provable Turn, not just the window), the window's `records` in end-time order, and `truncated: false` — complete logs are read, so an answer is never truncated. A malformed window answers `400` with `{ "error": { "code": "invalid-window" } }`.
+
+## Understand the implementation
+
+The handler lists the corpus through the session-query service and reads each session's complete raw log, folding `turn/start` through `turn/end` with `deriveTurnTokenUsage`. A Turn whose attempt lifecycle cannot prove its usage yields no record rather than an estimate — the same rule the report side follows. The Turn-end event's own timestamp is the record's `at`.
+
+## Further Exploration
+
+- [Token meter](../../llm/token-meter/README.md) owns the derivation this ledger folds with.
+- [Usage report](../usage-report/README.md) is the deployment half: reporting Turns to a supervisor ledger.
+- [Session query](../../session-query/session-query/README.md) owns the corpus read this ledger derives from.
+
+## Model Experience
+
+None, as this row only derives an HTTP read from local session logs, adding no prompt, tool schema, or model-visible output.
+
+#### KV Cache effect
+
+The read never touches a Session's log or context, so every Session's cache footprint is unchanged.
+
+## Known Limitations and Deferred Work
+
+- **The ledger is per runtime.** Only Turns whose complete durable logs live in this runtime's home are counted; cross-runtime accounting belongs to a deployment's external ledger, which this row deliberately does not implement.
+- **Unprovable Turns are absent.** A Turn whose attempt lifecycle cannot prove its usage is skipped, never estimated, so the page can undercount crashed Turns.
+- **A windowed read scans complete logs.** There is no incremental index; the read costs one full-log pass per session and is meant for single-user history sizes.
+
+### Dev Note
+
+The row is mounted by the shipped Web and desktop bundles, the surfaces that have no external ledger to read; it needs no configuration and injects only `sessionQuery` and `connection`.

package/README.zh.md

@@ -0,0 +1,75 @@
+---
+description: "单用户界面的本地用量账本：用 token-meter 派生，从本运行时自己的会话日志得到 /api/usage/me"
+kind: "package-reference"
+---
+
+# @qilin-agent/usage-local
+
+[English](README.md) | 中文
+
+## 概述
+
+单用户界面——桌面端、手工启动的 web 运行时——没有可读用量的部署账本。本插件就是这类界面的本地账本：在共享 API 通道上注册 `GET /api/usage/me`，并从本运行时拥有的会话日志推导答案，用 token-meter 派生折叠每一个 Turn。自带账本的部署通过外部账本上报用量，不挂载这一行。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在界面需要本地读取用量的组合中挂载这一行——随附的 Web/桌面 bundle 已经挂载。向监管者账本上报的部署组合不挂载它。
+
+### 组合方式
+
+```yaml
+- name: '@qilin-agent/session'
+- name: '@qilin-agent/session-query-sqlite'
+- name: '@qilin-agent/usage-local'
+```
+
+本行不声明配置。它与其他 `/api` 调用方一样接受账户会话门禁的保护，未认证的请求在进入派生逻辑之前就会被拒绝。
+
+### 读回用量
+
+`GET /api/usage/me?from=<epoch ms>&to=<epoch ms>` 应答 `accountId`、全账本 `total`（所有可证明的 Turn，而不仅是窗口内）、按结束时间排序的窗口内 `records`，以及 `truncated: false`——读取的是完整日志，应答永远不会被截断。格式错误的窗口应答 `400` 与 `{ "error": { "code": "invalid-window" } }`。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+处理器通过 session-query 服务枚举语料并读取每个会话的完整原始日志，把 `turn/start` 到 `turn/end` 交给 `deriveTurnTokenUsage` 折叠。尝试生命周期无法证明用量的 Turn 不会产生记录，也不会被估算——与上报侧遵循同一条规则。Turn 结束事件自身的时间戳就是记录的 `at`。
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Token meter](../../llm/token-meter/README.zh.md) 拥有本账本使用的派生逻辑。
+- [Usage report](../usage-report/README.zh.md) 是部署侧的一半：向监管者账本上报 Turn。
+- [Session query](../../session-query/session-query/README.zh.md) 拥有本账本派生所用的语料读取。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无：本行只从本地会话日志派生一次 HTTP 读取，不增加任何提示词、工具 schema 或模型可见输出。
+
+#### KV 缓存影响
+
+该读取从不触碰 Session 的日志或上下文，因此每个 Session 的缓存占用不变。
+
+<a id="known-limitations-and-deferred-work"></a>
+## 已知限制与待办
+
+- **账本按运行时计。** 只统计完整持久日志位于本运行时 home 中的 Turn；跨运行时的核算属于部署的外部账本，本行刻意不实现它。
+- **无法证明的 Turn 不出现。** 尝试生命周期无法证明用量的 Turn 会被跳过而不是估算，因此页面可能少计崩溃的 Turn。
+- **窗口读取扫描完整日志。** 没有增量索引；一次读取的成本是每个会话一次完整日志扫描，面向单用户的历史规模。
+
+<a id="dev-note"></a>
+### 开发备注
+
+随附的 Web 与桌面 bundle 会挂载这一行——这些界面没有可读的外部账本；它不需要配置，只注入 `sessionQuery` 与 `connection`。

package/lib/index.js

@@ -0,0 +1,163 @@
+import { deriveTurnTokenUsage } from "@qilin-agent/token-meter";
+//#region lib/types/usage.js
+/**
+* The local usage ledger's pure half: fold one session's complete raw log into
+* per-Turn records with the token-meter derivation, keep the window a read
+* asked for, and total the whole ledger.
+*/
+/**
+* Fold one session's complete raw log into per-Turn usage records.
+* @param sessionId - session every record belongs to.
+* @param events - the complete replay-validated raw log, from its first event on.
+* @returns one record per Turn whose exact usage the derivation proves; a Turn
+* with an incomplete attempt lifecycle yields no record rather than an estimate.
+*/
+function collectSessionUsage(sessionId, events) {
+	const records = [];
+	let buffered;
+	for (const event of events) {
+		if (event.type === "turn/start") {
+			buffered = [event];
+			continue;
+		}
+		if (buffered === void 0) continue;
+		buffered.push(event);
+		if (event.type !== "turn/end") continue;
+		const end = event;
+		const usage = deriveTurnTokenUsage(buffered);
+		buffered = void 0;
+		if (usage === void 0) continue;
+		records.push({
+			sessionId,
+			turn: end.data.turn,
+			inputTokens: usage.uncachedInputTokens,
+			outputTokens: usage.outputTokens,
+			...usage.cacheReadTokens === void 0 ? {} : { cacheReadTokens: usage.cacheReadTokens },
+			...usage.cacheWriteTokens === void 0 ? {} : { cacheWriteTokens: usage.cacheWriteTokens },
+			at: end.time
+		});
+	}
+	return records;
+}
+/**
+* Keep the Turns whose end time the requested window covers.
+* @param records - the ledger's records.
+* @param from - inclusive window start in epoch milliseconds.
+* @param to - inclusive window end in epoch milliseconds, or undefined for no end.
+*/
+function withinWindow(records, from, to) {
+	return records.filter((record) => record.at >= from && (to === void 0 || record.at <= to));
+}
+/**
+* Total the whole ledger: every Turn, the distinct sessions they belong to, and
+* the prompt cache hit rate.
+* @param records - the ledger's records.
+*/
+function totalOf(records) {
+	const sessions = new Set(records.map((record) => record.sessionId));
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
+	for (const record of records) {
+		inputTokens += record.inputTokens;
+		outputTokens += record.outputTokens;
+		cacheReadTokens += record.cacheReadTokens ?? 0;
+		cacheWriteTokens += record.cacheWriteTokens ?? 0;
+	}
+	return {
+		sessions: sessions.size,
+		turns: records.length,
+		inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		cacheHitRate: inputTokens === 0 ? 0 : cacheReadTokens / inputTokens
+	};
+}
+/**
+* Assemble the answer the usage page reads.
+* @param accountId - account the ledger names for display.
+* @param all - every Turn this runtime's logs prove.
+* @param windowed - the Turns inside the requested window.
+*/
+function usageAnswer(accountId, all, windowed) {
+	return {
+		accountId,
+		total: totalOf(all),
+		records: [...windowed].sort((left, right) => left.at - right.at),
+		truncated: false
+	};
+}
+/**
+* Read the window from the request's query string. A missing bound means no
+* bound: the answer then covers the whole ledger.
+* @param url - request URL carrying from and optionally to, in epoch milliseconds.
+* @returns the window, or undefined when a bound is present but not a safe
+* non-negative epoch-milliseconds integer, or when to precedes from.
+*/
+function readWindow(url) {
+	const rawFrom = url.searchParams.get("from");
+	const from = rawFrom === null ? 0 : Number(rawFrom);
+	if (!Number.isSafeInteger(from) || from < 0) return void 0;
+	const rawTo = url.searchParams.get("to");
+	if (rawTo === null) return { from };
+	const to = Number(rawTo);
+	if (!Number.isSafeInteger(to) || to < from) return void 0;
+	return {
+		from,
+		to
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Serves the usage page's read from this runtime's own session logs.
+*
+* A deployment that keeps a ledger of its own reports usage through the
+* external ledger and does not mount this row. A single-user surface — the
+* desktop, a hand-started web runtime — has no ledger, so this plugin derives
+* the same answer from the session logs the runtime owns: every Turn the
+* token-meter derivation can prove, totalled over the whole ledger and listed
+* for the requested window.
+* @module @qilin-agent/usage-local
+*/
+/** Plugin name the Loader mounts. */
+const name = "usage-local";
+/** Services this plugin reads: the session-history query and the API route registry. */
+const inject = ["sessionQuery", "connection"];
+/**
+* Register the local usage read on the shared API channel.
+* @param ctx - plugin context carrying the query service and the route registry.
+*/
+function apply(ctx) {
+	const query = ctx.sessionQuery;
+	ctx.effect(() => ctx.connection.fetch.register({
+		path: "/api/usage/me",
+		methods: ["GET"],
+		requestBody: "buffered",
+		fetch: (request) => serveUsage(query, new URL(request.url))
+	}), "usage-local: /api/usage/me");
+}
+/**
+* Answer one usage read from the local session logs.
+* @param query - the session-history query service.
+* @param url - request URL carrying the window.
+* @returns the usage answer, or the refusal a malformed window owes.
+*/
+async function serveUsage(query, url) {
+	const window = readWindow(url);
+	if (window === void 0) return Response.json({ error: { code: "invalid-window" } }, {
+		status: 400,
+		headers: { "cache-control": "no-store" }
+	});
+	const records = [];
+	for (const session of await query.listSessions()) {
+		const snapshot = await query.readSession(session.header.id);
+		records.push(...collectSessionUsage(session.header.id, snapshot.events));
+	}
+	const answer = usageAnswer("local", records, withinWindow(records, window.from, window.to));
+	return Response.json(answer, { headers: { "cache-control": "no-store" } });
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Serves the usage page's read from this runtime's own session logs.
+ *
+ * A deployment that keeps a ledger of its own reports usage through the
+ * external ledger and does not mount this row. A single-user surface — the
+ * desktop, a hand-started web runtime — has no ledger, so this plugin derives
+ * the same answer from the session logs the runtime owns: every Turn the
+ * token-meter derivation can prove, totalled over the whole ledger and listed
+ * for the requested window.
+ * @module @qilin-agent/usage-local
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** Plugin name the Loader mounts. */
+export declare const name = "usage-local";
+/** Services this plugin reads: the session-history query and the API route registry. */
+export declare const inject: readonly string[];
+/**
+ * Register the local usage read on the shared API channel.
+ * @param ctx - plugin context carrying the query service and the route registry.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/usage.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The local usage ledger's pure half: fold one session's complete raw log into
+ * per-Turn records with the token-meter derivation, keep the window a read
+ * asked for, and total the whole ledger.
+ */
+import type { SessionEvent } from '@qilin-agent/session/types';
+/** One Turn as the local ledger records it. */
+export interface LocalUsageRecord {
+    /** Session the Turn belongs to. */
+    readonly sessionId: string;
+    /** Turn number inside that session. */
+    readonly turn: number;
+    /** Prompt tokens billed as uncached input. */
+    readonly inputTokens: number;
+    /** Completion tokens billed for the Turn. */
+    readonly outputTokens: number;
+    /** Prompt tokens the provider served from its cache, when it reported them. */
+    readonly cacheReadTokens?: number;
+    /** Prompt tokens written to that cache, when it reported them. */
+    readonly cacheWriteTokens?: number;
+    /** Turn-end time in epoch milliseconds. */
+    readonly at: number;
+}
+/** Whole-ledger totals the usage page's all-time card reads. */
+export interface LocalUsageTotal {
+    /** Distinct sessions the ledger's Turns belong to. */
+    readonly sessions: number;
+    readonly turns: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** Cache reads over uncached input; zero when no Turn billed input. */
+    readonly cacheHitRate: number;
+}
+/** The answer the usage page reads: whole-ledger totals plus the requested window. */
+export interface LocalUsageAnswer {
+    /** Account the ledger names for display. */
+    readonly accountId: string;
+    readonly total: LocalUsageTotal;
+    /** Turns inside the requested window, in end-time order. */
+    readonly records: readonly LocalUsageRecord[];
+    /** The local ledger reads complete logs, so an answer is never truncated. */
+    readonly truncated: false;
+}
+/**
+ * Fold one session's complete raw log into per-Turn usage records.
+ * @param sessionId - session every record belongs to.
+ * @param events - the complete replay-validated raw log, from its first event on.
+ * @returns one record per Turn whose exact usage the derivation proves; a Turn
+ * with an incomplete attempt lifecycle yields no record rather than an estimate.
+ */
+export declare function collectSessionUsage(sessionId: string, events: readonly SessionEvent[]): LocalUsageRecord[];
+/**
+ * Keep the Turns whose end time the requested window covers.
+ * @param records - the ledger's records.
+ * @param from - inclusive window start in epoch milliseconds.
+ * @param to - inclusive window end in epoch milliseconds, or undefined for no end.
+ */
+export declare function withinWindow(records: readonly LocalUsageRecord[], from: number, to?: number): readonly LocalUsageRecord[];
+/**
+ * Total the whole ledger: every Turn, the distinct sessions they belong to, and
+ * the prompt cache hit rate.
+ * @param records - the ledger's records.
+ */
+export declare function totalOf(records: readonly LocalUsageRecord[]): LocalUsageTotal;
+/**
+ * Assemble the answer the usage page reads.
+ * @param accountId - account the ledger names for display.
+ * @param all - every Turn this runtime's logs prove.
+ * @param windowed - the Turns inside the requested window.
+ */
+export declare function usageAnswer(accountId: string, all: readonly LocalUsageRecord[], windowed: readonly LocalUsageRecord[]): LocalUsageAnswer;
+/** The epoch-milliseconds window one request asked for. */
+export interface UsageWindow {
+    readonly from: number;
+    readonly to?: number;
+}
+/**
+ * Read the window from the request's query string. A missing bound means no
+ * bound: the answer then covers the whole ledger.
+ * @param url - request URL carrying from and optionally to, in epoch milliseconds.
+ * @returns the window, or undefined when a bound is present but not a safe
+ * non-negative epoch-milliseconds integer, or when to precedes from.
+ */
+export declare function readWindow(url: URL): UsageWindow | undefined;
+//# sourceMappingURL=usage.d.ts.map

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@qilin-agent/usage-local",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Local usage ledger for single-user surfaces: derives /api/usage/me from this runtime's own session logs with the token-meter derivation",
+  "version": "3.1.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/usage-local"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/client-connection": "3.1.6"
+  },
+  "dependencies": {
+    "@qilin-agent/token-meter": "3.1.6"
+  },
+  "devDependencies": {
+    "@qilin-agent/client-connection": "3.1.6",
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/session-query-sqlite": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/session-query": "3.1.6"
+  }
 }