@qilin-agent/usage-report 0.0.0-stage → 3.1.4

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-report/README.md
+/:
+  en: add4f5d9e3647553
+  zh: caf7e5690c6e1c19
+/qilin-agent-usage-report:
+  en: 23f9d69bce105f30
+  zh: fd63b675803b2e10
+/qilin-agent-usage-report/summary:
+  en: fc367ea6226c2745
+  zh: 6bd5694f14f2e26d
+/qilin-agent-usage-report/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 3a2f21ff0dc3420d
+/qilin-agent-usage-report/use-this-package:
+  en: 6ab5be9b6c4932dc
+  zh: 6b6c8cb38dc482b5
+/qilin-agent-usage-report/use-this-package/delivery:
+  en: d655776fa5d639fe
+  zh: 7ffeb5e35292f3fc
+/qilin-agent-usage-report/use-this-package/reading-it-back:
+  en: 2fafcce90e8be0ec
+  zh: 21c9e2bc01656687
+/qilin-agent-usage-report/understand-the-implementation:
+  en: 92eab5d20c00bb14
+  zh: 410ec89aa8349c96
+/qilin-agent-usage-report/further-exploration:
+  en: 5b47ffebcd81cf93
+  zh: 1e0d15118024c165
+/qilin-agent-usage-report/model-experience:
+  en: c09aea9033676d8d
+  zh: cca033e311899e14
+/qilin-agent-usage-report/model-experience/kv-cache-effect:
+  en: a9ffb42d486fd22f
+  zh: d08cc33e1dfc9439
+/qilin-agent-usage-report/known-limitations-and-deferred-work:
+  en: 08d6482805679287
+  zh: c90c570aa63cc7d1
+/qilin-agent-usage-report/known-limitations-and-deferred-work/dev-note:
+  en: 108f22f2695e0f2e
+  zh: 78f1ef317b7bd5fb

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+---
+description: "Reports each settled Turn's exact token usage to the deployment supervisor that started the runtime, for the per-account ledger a multi-account deployment keeps."
+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-report
+
+English | [中文](README.zh.md)
+
+## Summary
+
+A deployment that serves one web entry gives every account a runtime of its own and needs to know what each one spent. This plugin is the runtime's half of that accounting: it follows the session event stream, folds one Turn's durable attempts into exact usage — the same derivation the transcript shows, which refuses to guess — and posts the result to the endpoint its supervisor named. A runtime no supervisor started carries no endpoint, and the plugin then does nothing at all.
+
+## 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 once per runtime. It declares no configuration: the deployment supplies two environment variables, and their absence is the only switch.
+
+| Variable | Meaning |
+|---|---|
+| `QILIN_USAGE_URL` | Endpoint that accepts one JSON report per settled Turn |
+| `QILIN_USAGE_TOKEN` | Credential that endpoint accepts; the deployment binds it to the account this runtime serves |
+
+The supervisor that starts a runtime writes both; a hand-started `qilin` carries neither. One report is one Turn, and delivery is best effort:
+
+```json
+{ "sessionId": "…", "turn": 3, "inputTokens": 4192, "outputTokens": 318,
+  "cacheReadTokens": 3072, "at": 1791725148421 }
+```
+
+`inputTokens` counts prompt tokens billed as uncached, `cacheReadTokens` and `cacheWriteTokens` appear only when every attempt of the Turn reported them, and `at` is this process's report time. The endpoint identifies the account from the credential, never from the body.
+
+### Delivery
+
+A report is sent once, when the Turn ends. A refused or unreachable endpoint is written to the log at warning level and dropped; the ledger is a report rather than an obligation, so telemetry trouble never delays a Turn or fails it.
+
+### Reading it back
+
+A runtime that serves a web transport also answers `GET /api/usage/me` for its own account, forwarding the query string (such as a report-time window, `?from=<epoch ms>&to=<epoch ms>`) to the ledger with the same credential. The answer carries the account's `total`, the `records` inside the window in report-time order, and `truncated` when the ledger held more Turns than one answer carries. The account gate protects the route like any other `/api` call, and the read is scoped by the credential, so one runtime can only ever read its own account. A ledger the runtime cannot reach answers `503` with `{ "error": { "code": "ledger-unavailable" } }` rather than an empty total.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The plugin buffers the durable events of the Turn each session is inside, from `turn/start` through `turn/end`, and folds them with the token-meter package's `deriveTurnTokenUsage`. That derivation refuses to infer usage: a Turn whose attempt lifecycle is incomplete, whose samples are unsafe, or whose exact total contradicts its parts yields nothing, and this plugin then reports nothing rather than an estimate. A Turn whose `turn/start` this process never saw — replayed history, or a session that began before the row mounted — is not one it can account for and is skipped.
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Token meter](../../llm/token-meter/README.md) owns the derivation this plugin reports.
+- [Accounts](../../identity/accounts-local/README.md) owns the roster the deployment's ledger attributes reports to.
+- [CLI reference](../../../apps/cli/reference/README.md) documents the deployment flags that start these runtimes.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this row only reads the session event stream and writes to a deployment endpoint, adding no prompt, tool schema, or model-visible output.
+
+#### KV Cache effect
+
+No request this row observes is altered, so every Session's cache footprint is unchanged.
+
+## Known Limitations and Deferred Work
+
+- **A report is not durable.** A process that dies before its Turn ends loses that Turn's report, and a dropped report is not retried; the ledger sums what arrived.
+- **Delivery is per Turn, not per request.** Retries inside a Turn are folded into its attempts, so the ledger shows what the Turn settled rather than what each call cost.
+- **The ledger's own attribution is the deployment's.** The credential decides which account a report lands under; a runtime started by hand cannot report at all.
+
+<a id="dev-note"></a>
+### Dev Note
+
+The row is mounted by every runtime, including single-account ones, and is inert without the two variables; that is why it needs no configuration and no per-deployment enabling.

package/README.zh.md

@@ -0,0 +1,83 @@
+---
+description: "把每个已结算 Turn 的精确 token 用量上报给启动该运行时的部署监督者，供多账户部署的按账户账本使用。"
+kind: "package-reference"
+---
+
+# @qilin-agent/usage-report
+
+[English](README.md) | 中文
+
+## 概述
+
+一个 web 入口服务多账户的部署给每个账户一个自己的运行时，因此需要知道各自花了多少。本插件是这笔记账在运行时一侧的那一半：它跟随会话事件流，把一个 Turn 的持久尝试折成精确用量——与转录页显示的是同一套推导，且拒绝猜测——再投递给监督者指定的端点。不是由监督者启动的运行时没有这个端点，插件于是什么都不做。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+每个运行时挂载一次。它不声明任何配置：部署提供两个环境变量，二者缺席就是唯一的开关。
+
+| 变量 | 含义 |
+|---|---|
+| `QILIN_USAGE_URL` | 接受「每个已结算 Turn 一份 JSON 报告」的端点 |
+| `QILIN_USAGE_TOKEN` | 该端点接受的凭据；部署把它绑定到本运行时服务的账户 |
+
+启动运行时的监督者会写入这两者；手工启动的 `qilin` 两者都没有。一份报告就是一个 Turn，投递为尽力而为：
+
+```json
+{ "sessionId": "…", "turn": 3, "inputTokens": 4192, "outputTokens": 318,
+  "cacheReadTokens": 3072, "at": 1791725148421 }
+```
+
+`inputTokens` 计的是按未命中计费的提示 token；`cacheReadTokens` 与 `cacheWriteTokens` 只在该 Turn 的每次尝试都报了它们时才出现；`at` 是本进程的上报时刻。端点**从凭据**判断账户，绝不从请求体判断。
+
+### 投递
+
+报告在 Turn 结束时发送一次。端点拒绝或不可达只写入 warning 级日志然后丢弃；账本是报告而非义务，因此遥测故障既不会拖延一个 Turn，也不会让它失败。
+
+### 读回自己的用量
+
+提供 web 传输的运行时还会为它自己的账户应答 `GET /api/usage/me`：把查询串（例如上报时间窗口 `?from=<epoch ms>&to=<epoch ms>`）连同同一凭据转发给账本。应答里带该账户的 `total`、窗口内按上报时间排序的 `records`，以及当账本里的 Turn 超过单次应答容量时的 `truncated`。该路由与其它 `/api` 调用一样受账户门禁保护，且读取由凭据限定作用域——一个运行时只可能读到自己的账户。账本不可达时返回 `503` 与 `{ "error": { "code": "ledger-unavailable" } }`，而不是一个空合计。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+插件缓冲每个会话当前所在 Turn 的持久事件（`turn/start` 到 `turn/end`），用 token-meter 包的 `deriveTurnTokenUsage` 折叠它们。该推导拒绝推断用量：尝试生命周期不完整、样本不安全、或精确总数与各部分矛盾的 Turn 一律得不出结果，此时本插件不上报而不是上报估计值。本进程没有见过 `turn/start` 的 Turn——重放的历史，或在本行挂载之前就开始的会话——不在它能记账的范围内，直接跳过。
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Token meter](../../llm/token-meter/README.zh.md) 拥有本插件所上报的那套推导。
+- [Accounts](../../identity/accounts-local/README.zh.md) 拥有部署账本据以归属报告的名册。
+- [CLI reference](../../../apps/cli/reference/README.zh.md) 记录了启动这些运行时的部署 flag。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无：本行只读取会话事件流并写入部署端点，不增加任何提示词、工具 schema 或模型可见输出。
+
+#### KV 缓存影响
+
+本行观察的请求都不被改动，因此每个 Session 的缓存占用不变。
+
+<a id="known-limitations-and-deferred-work"></a>
+## 已知限制与待办
+
+- **报告不是持久义务。** 在 Turn 结束前死掉的进程会丢掉该 Turn 的报告，被丢弃的报告不会重试；账本汇总的是已到达的那些。
+- **按 Turn 投递，而不是按请求。** 一个 Turn 内的重试被折进它的尝试里，因此账本显示的是该 Turn 结算的量，而不是每次调用的开销。
+- **账本的归属由部署决定。** 凭据决定报告落在哪个账户名下；手工启动的运行时根本无法上报。
+
+<a id="dev-note"></a>
+### 开发备注
+
+每个运行时都会挂载这一行（包括单账户的），而它在缺少那两个变量时是惰性的；这就是它不需要配置、也不需要按部署启用的原因。

package/lib/index.js

@@ -0,0 +1,90 @@
+import { deriveTurnTokenUsage } from "@qilin-agent/token-meter";
+//#region lib/types/index.js
+/**
+* Reports each settled Turn's token usage to the deployment that started this
+* runtime.
+*
+* A deployment that serves one web entry gives every account a runtime of its
+* own and keeps one ledger of what each account spent. This plugin is the
+* runtime's half of that: it folds one Turn's durable attempts into exact usage
+* — the same derivation the transcript shows — and posts it to the endpoint the
+* supervisor named in this process's environment. The browser reads that ledger
+* from the deployment itself, so a runtime started by hand carries no endpoint
+* and this plugin then does nothing at all.
+* @module @qilin-agent/usage-report
+*/
+/** Environment variable naming the deployment's usage endpoint. */
+const USAGE_URL_VARIABLE = "QILIN_USAGE_URL";
+/** Environment variable carrying the credential that endpoint accepts. */
+const USAGE_TOKEN_VARIABLE = "QILIN_USAGE_TOKEN";
+/** Plugin name the Loader mounts. */
+const name = "usage-report";
+/** This plugin reads no service; it only follows the session event stream. */
+const inject = [];
+/** How long one report may take before it is abandoned. */
+const REPORT_TIMEOUT_MS = 5e3;
+/**
+* Report every Turn this process settles to the deployment that started it.
+* @param ctx - plugin context carrying the session event stream.
+*/
+function apply(ctx) {
+	const url = process.env[USAGE_URL_VARIABLE];
+	const token = process.env[USAGE_TOKEN_VARIABLE];
+	if (url === void 0 || url === "" || token === void 0 || token === "") return;
+	/** Durable events of the Turn each session is inside, from `turn/start` on. */
+	const turns = /* @__PURE__ */ new Map();
+	ctx.effect(() => () => {
+		turns.clear();
+	});
+	ctx.on("session/event", (session, event) => {
+		const sessionId = session.id;
+		if (event.type === "turn/start") {
+			turns.set(sessionId, [event]);
+			return;
+		}
+		const buffered = turns.get(sessionId);
+		if (buffered === void 0) return;
+		buffered.push(event);
+		if (event.type !== "turn/end") return;
+		turns.delete(sessionId);
+		const usage = deriveTurnTokenUsage(buffered);
+		if (usage === void 0) return;
+		report(ctx, url, token, {
+			sessionId,
+			turn: event.data.turn,
+			inputTokens: usage.uncachedInputTokens,
+			outputTokens: usage.outputTokens,
+			...usage.cacheReadTokens === void 0 ? {} : { cacheReadTokens: usage.cacheReadTokens },
+			...usage.cacheWriteTokens === void 0 ? {} : { cacheWriteTokens: usage.cacheWriteTokens }
+		});
+	});
+}
+/**
+* Post one Turn's report, without letting the deployment's health reach the
+* session that produced it.
+* @param ctx - plugin context the diagnostic goes to.
+* @param url - endpoint the deployment named.
+* @param token - credential that endpoint accepts.
+* @param report - the Turn's usage.
+*/
+async function report(ctx, url, token, report) {
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${token}`
+			},
+			body: JSON.stringify({
+				...report,
+				at: Date.now()
+			}),
+			signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+		});
+		if (!response.ok) ctx.logger.warn(`usage-report: the deployment refused one report (HTTP ${String(response.status)})`);
+	} catch (error) {
+		ctx.logger.warn(`usage-report: one report failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+//#endregion
+export { USAGE_TOKEN_VARIABLE, USAGE_URL_VARIABLE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reports each settled Turn's token usage to the deployment that started this
+ * runtime.
+ *
+ * A deployment that serves one web entry gives every account a runtime of its
+ * own and keeps one ledger of what each account spent. This plugin is the
+ * runtime's half of that: it folds one Turn's durable attempts into exact usage
+ * — the same derivation the transcript shows — and posts it to the endpoint the
+ * supervisor named in this process's environment. The browser reads that ledger
+ * from the deployment itself, so a runtime started by hand carries no endpoint
+ * and this plugin then does nothing at all.
+ * @module @qilin-agent/usage-report
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** Environment variable naming the deployment's usage endpoint. */
+export declare const USAGE_URL_VARIABLE = "QILIN_USAGE_URL";
+/** Environment variable carrying the credential that endpoint accepts. */
+export declare const USAGE_TOKEN_VARIABLE = "QILIN_USAGE_TOKEN";
+/** Plugin name the Loader mounts. */
+export declare const name = "usage-report";
+/** This plugin reads no service; it only follows the session event stream. */
+export declare const inject: readonly string[];
+/**
+ * Report every Turn this process settles to the deployment that started it.
+ * @param ctx - plugin context carrying the session event stream.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@qilin-agent/usage-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Reports each settled Turn's token usage to the deployment that started the runtime",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/usage-report"
+  },
+  "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.3"
+  },
+  "dependencies": {
+    "@qilin-agent/token-meter": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-connection": "3.1.4",
+    "@qilin-agent/session": "3.1.4"
+  }
 }