@mafdet/cli 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -6,6 +6,40 @@ The version is the contract for the JSON output shapes and the exit codes.
 Being 0.x, semver still permits a break in a minor bump; the intent is not to
 use that latitude, and the promise becomes binding at 1.0.0.
 
+## 0.4.2 - 2026-08-11
+
+Conversations are now saved on this computer, and a session's cost can be
+reconciled against the billing ledger.
+
+`mafdet sessions list|show|usage|delete` browses what is stored locally. None
+of it calls a model, so reading your own history is never charged. Recording
+is on by default for interactive sessions and off wherever a machine is
+reading the output; `--no-history` writes nothing at all.
+
+The transcript is plain text and stays on this machine - it is not uploaded,
+and Mafdet holds no copy. That is a statement about the archive, not about the
+model: the messages you send are still sent to the API to be answered and
+still appear in your usage records. The README says where the files live on
+each platform, and that deleting one is an ordinary file delete rather than a
+secure erase.
+
+`mafdet sessions usage <id> --refresh` asks the billing ledger what the
+requests actually cost and replaces the local estimate with the settled
+figure. It sends the request IDs already in the transcript and nothing else -
+no messages, no title, no workspace, no session ID. Requests paid for by a
+different API key are left alone and reported rather than guessed at, and a
+request the ledger has not settled stays `pending` rather than being shown as
+zero.
+
+The agent cannot read the CLI's own directories, even when you run `mafdet`
+from your home directory and the session store is technically inside the
+workspace.
+
+Fixed on the way: the value recorded to attribute usage to a key was the
+display fingerprint, which renders every live key identically - so a session
+that used two keys reported them as one. It is now a digest that actually
+differs per key, and still cannot be turned back into a key.
+
 ## 0.4.1 - 2026-08-07
 
 Fixes Ctrl+C in the interactive session, which did nothing while a model

package/README.md

@@ -88,6 +88,8 @@ prompt as an argument, or use `--input <file>`.
 | `mafdet embed [text\|<file>] --model <id> [--output <file>]`                                | Text to vector                                                             |
 | `mafdet speech [text\|<file>] --model <id> --output <file> --voice <name>`                  | Text to an audio file                                                      |
 | `mafdet account balance\|usage\|subscription`                                               | Wallet, spend and plan (needs the `account:read` scope)                    |
+| `mafdet sessions list\|show\|usage\|delete`                                                 | Conversations saved on this computer (never calls a model)                 |
+| `mafdet sessions usage <id> --refresh`                                                      | Replace the local estimate with the billing ledger's figure                |
 | `mafdet config list`                                                                        | The resolved settings and where each came from                             |
 
 `--json` on any query command emits one complete JSON document; `--plain`
@@ -181,6 +183,65 @@ flag: it would put the key into shell history and the process list. Keys are
 never written to a config file and never printed in full — only as a
 fingerprint like `sk-mafdet-live-<redacted>`.
 
+## Saved conversations
+
+Interactive sessions are saved on this computer, and only on this computer.
+They are not uploaded, and Mafdet holds no copy of them.
+
+That is a statement about the transcript, not about the model. The messages you
+send are still sent to the API to be answered and still appear in your usage
+records; what stays local is the saved copy.
+
+Where they live:
+
+| Platform    | Path                                                |
+| ----------- | --------------------------------------------------- |
+| Linux / WSL | `${XDG_STATE_HOME:-~/.local/state}/mafdet/sessions` |
+| macOS       | `~/Library/Application Support/mafdet/sessions`     |
+| Windows     | `%LOCALAPPDATA%\mafdet\sessions`                    |
+
+The files are **plain text**. A transcript contains your messages, the model's
+replies, and any source the agent read while working — so treat a session
+directory the way you would treat the project it came from. API keys are the
+one exception: everything is passed through redaction on the way to disk, so a
+key you paste into a prompt is stored as `<redacted>`. Files are created
+`0600` and directories `0700` on Linux and macOS; Windows has no equivalent
+mode bits and inherits the ACL of `%LOCALAPPDATA%`.
+
+The agent cannot read these directories, even when you run `mafdet` from your
+home directory and the store is technically inside the workspace. Otherwise an
+agent working on one project could read another project's transcript in full.
+
+Turning it off and cleaning up:
+
+```bash
+mafdet --no-history            # this run is not recorded at all
+mafdet sessions list           # what is saved, and the path when nothing is
+mafdet sessions delete <id> --yes
+```
+
+`--no-history` writes nothing — not an empty directory, not an index entry.
+
+Deleting removes the local messages and this session's usage mapping. It does
+**not** remove API usage, billing records or charges: those belong to the API
+key, not to the transcript. And it is an ordinary file delete, not a secure
+erase — backups, snapshots and the filesystem itself may still hold copies.
+
+## Reconciling what a session cost
+
+`mafdet sessions usage <id>` adds up what a conversation used from the local
+record. Those charges are estimates, computed with the gateway's own
+arithmetic but computed here.
+
+`--refresh` asks the billing ledger for the real figure. It sends the request
+IDs already in the transcript and nothing else — no messages, no title, no
+workspace, no session ID. Requests paid for by a different API key are left
+alone and reported, so you know to run it again with that key.
+
+A request that the ledger has not caught up with stays `pending`, and a request
+that never returned an ID stays `unknown`. Neither is ever shown as `0`, which
+would read as "it was free".
+
 ## Cost and cancellation
 
 `chat` prints tokens and an estimated charge to stderr, computed with the same

package/README.zh-CN.md

@@ -71,6 +71,8 @@ mafdet doctor
 | `mafdet agent "<目标>" [--allow-write] [--allow-command "<前缀>"]`                          | 本地 Agent，默认只读                                                |
 | `mafdet agent`（不带目标，需终端）                                                          | 交互会话                                                            |
 | `mafdet account balance\|usage\|subscription`                                               | 钱包、用量、套餐（需 `account:read` scope）                         |
+| `mafdet sessions list\|show\|usage\|delete`                                                 | 保存在这台电脑上的会话（不会调用模型）                              |
+| `mafdet sessions usage <id> --refresh`                                                      | 用账单账本的权威金额替换本地估算                                    |
 | `mafdet config list`                                                                        | 当前生效的配置及其来源                                              |
 
 查询类命令都支持 `--json`（输出一份完整 JSON 文档）与 `--plain`（无表头的 TSV，方便
@@ -156,6 +158,56 @@ Key 只从 `MAFDET_API_KEY` 读取。**刻意不提供 `--api-key` 参数**—
 shell 历史和进程列表。Key 不会被写入任何配置文件，也不会完整出现在任何输出里，
 只以 `sk-mafdet-live-<redacted>` 这样的指纹形式展示。
 
+## 保存下来的会话
+
+交互式会话会保存在这台电脑上，**也只在这台电脑上**。它们不会上传，Mafdet 没有副本。
+
+这是关于**存档**的说法，不是关于模型的。你发送的消息仍然会送到 API 去作答，
+仍然出现在你的用量记录里；留在本地的是那份保存下来的副本。
+
+存放位置：
+
+| 平台        | 路径                                                |
+| ----------- | --------------------------------------------------- |
+| Linux / WSL | `${XDG_STATE_HOME:-~/.local/state}/mafdet/sessions` |
+| macOS       | `~/Library/Application Support/mafdet/sessions`     |
+| Windows     | `%LOCALAPPDATA%\mafdet\sessions`                    |
+
+这些文件是**明文**。一份存档包含你的消息、模型的回复，以及 agent 工作时读过的任何源码——
+所以请把会话目录当作它所对应的那个项目本身来对待。API Key 是唯一的例外：
+所有内容在写盘前都会过一遍脱敏，你粘进提示词里的 Key 会以 `<redacted>` 的形式存下来。
+Linux 与 macOS 上文件权限 `0600`、目录 `0700`；**Windows 没有等价的权限位**，
+继承 `%LOCALAPPDATA%` 的 ACL。
+
+**Agent 读不到这些目录**——即使你在家目录里运行 `mafdet`、存档实际落在工作区内也一样。
+否则在 A 项目里工作的 agent 就能读到 B 项目会话的完整明文。
+
+关闭与清理：
+
+```bash
+mafdet --no-history            # 这一次运行完全不记录
+mafdet sessions list           # 已保存的会话；没有时会告诉你路径
+mafdet sessions delete <id> --yes
+```
+
+`--no-history` 什么都不留——不留空目录，也不留索引条目。
+
+删除会移除本地消息和这个会话的用量映射。它**不会**移除 API 用量、账单记录或扣费：
+那些属于 API Key，不属于存档。而且它只是一次普通的文件删除，**不是安全擦除**——
+备份、快照和文件系统本身仍可能保有副本。
+
+## 对账：这次会话到底花了多少
+
+`mafdet sessions usage <id>` 从本地记录累加一次会话的用量。那些金额是**估算**，
+算法与网关一致，但是在本地算的。
+
+`--refresh` 会去问账单账本要真实金额。它只发送存档里已有的 request ID，**别的什么都不发**——
+不发消息、不发标题、不发工作区路径、不发 session ID。由另一把 API Key 支付的请求会被跳过
+并如实告知，好让你知道该换那把 Key 再跑一次。
+
+账本还没跟上的请求保持 `pending`，从未拿到 ID 的请求保持 `unknown`。
+**两者都绝不显示为 `0`**——0 读起来像「免费」。
+
 ## 费用与取消
 
 `chat` 会在 stderr 打印 token 数与预估费用，算法与网关计费一致，但**以钱包为准**。

package/dist/agent/loop.d.ts

@@ -88,6 +88,20 @@ export type AgentEvent = {
 } | {
     type: "text";
     text: string;
+}
+/**
+ * One model request's accounting, as it happens. The summary already
+ * aggregates this; the event exists so a recorder can attribute each request
+ * to the ledger row it became (CLI-024/025) - `requestId` is the gateway's
+ * x-litellm-call-id, which is unique per row in request_ledger.
+ */
+ | {
+    type: "usage";
+    model: string;
+    requestId?: string;
+    promptTokens: number;
+    completionTokens: number;
+    costMicroUsd: bigint;
 } | {
     type: "rate_limited";
     waitMs: number;

package/dist/agent/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop.js

@@ -78,7 +78,18 @@ export async function runAgent(options) {
         report.completionTokens += usage?.completion_tokens ?? 0;
         // Cost comes from returned usage, never from the reservation: CLI-000B
         // showed the reserve cannot see the tool schema and under-counts badly.
-        report.costMicroUsd += priceTurn(options.pricing, usage);
+        const turnCost = priceTurn(options.pricing, usage);
+        report.costMicroUsd += turnCost;
+        options.onEvent?.({
+            type: "usage",
+            model: options.model,
+            ...(response.requestId === undefined
+                ? {}
+                : { requestId: response.requestId }),
+            promptTokens: usage?.prompt_tokens ?? 0,
+            completionTokens: usage?.completion_tokens ?? 0,
+            costMicroUsd: turnCost,
+        });
         const choice = response.choices?.[0];
         const message = choice?.message;
         const calls = message?.tool_calls ?? [];
@@ -198,8 +209,10 @@ async function requestWithRateLimitHandling(options, limits, body, report, clock
     for (let attempt = 0;; attempt += 1) {
         try {
             report.modelRequests += 1;
-            const { data } = await options.client.postJson("/chat/completions", body, { signal: options.signal });
-            return data;
+            const { data, requestId } = await options.client.postJson("/chat/completions", body, { signal: options.signal });
+            // Carried on the response so the caller can tie this turn to its ledger
+            // row without the loop needing to know what a session is.
+            return { ...data, requestId };
         }
         catch (error) {
             // Everything except an explicit 429 propagates. A timeout or a 5xx may

package/dist/agent/session.d.ts

@@ -32,6 +32,11 @@ export interface SessionOptions {
      * the same events are drawn.
      */
     onEvent?: (event: AgentEvent) => void;
+    /**
+     * A conversation to continue, rebuilt from a saved session (CLI-024).
+     * Appended to in place, exactly as the fresh array would be.
+     */
+    history?: ChatMessage[];
 }
 export interface SessionSummary {
     goals: number;

package/dist/agent/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAY,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAapE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAgHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CA2B7D"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAY,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAapE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAgHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CA2B7D"}

package/dist/agent/session.js

@@ -22,7 +22,7 @@ Anything else is sent to the model as the next goal.
  * rather than the last question.
  */
 export async function runSession(options) {
-    const history = [];
+    const history = options.history ?? [];
     const summary = {
         goals: 0,
         turns: 0,

package/dist/agent/tools/read-only.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/read-only.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,YAAY,CAAC;AAmB9D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYjD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBjD;AAmLD,eAAO,MAAM,eAAe,EAAE,cAAc,EAM3C,CAAC"}
+{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/read-only.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,YAAY,CAAC;AAmB9D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYjD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBjD;AAwLD,eAAO,MAAM,eAAe,EAAE,cAAc,EAM3C,CAAC"}

package/dist/agent/tools/read-only.js

@@ -87,6 +87,12 @@ function walk(workspace, onFile) {
             if (entry.isDirectory()) {
                 if (SKIPPED_DIRECTORIES.has(entry.name))
                     continue;
+                // The CLI's own directories, uniformly. Dot-directories are skipped
+                // anyway, which covers Linux and Windows by accident - but on macOS
+                // the state directory is `Library/Application Support/mafdet`, so
+                // without this the session ids would be listed there and nowhere else.
+                if (workspace.isOwnedByCli(full))
+                    continue;
                 stack.push(full);
                 continue;
             }

package/dist/api/account.d.ts

@@ -36,4 +36,47 @@ export interface Subscription {
 export declare function fetchWallet(client: HttpClient): Promise<Wallet>;
 export declare function fetchUsage(client: HttpClient, days?: number): Promise<UsageSummary>;
 export declare function fetchSubscription(client: HttpClient): Promise<Subscription>;
+/**
+ * CLI-027 · One settled request as the ledger holds it.
+ *
+ * The whole whitelist the server returns (CLI-026): no prompt, no response, no
+ * tool arguments, no file content, and no session id - the CLI matches on
+ * `request_id` alone, which is why none of that has to leave the machine.
+ */
+export interface LedgerUsageEvent {
+    request_id: string;
+    model_id: string;
+    input_tokens: number;
+    output_tokens: number;
+    platform_charge_micro_usd: string;
+    status: string;
+    created_at: string;
+}
+export interface UsageEventsResult {
+    readonly events: readonly LedgerUsageEvent[];
+    readonly pages: number;
+    /**
+     * True when the walk reached the end of the window.
+     *
+     * When it is false the caller stopped early, and "not found" then means "not
+     * found yet" - reporting it as "the ledger has no such request" would be a
+     * claim the walk did not earn.
+     */
+    readonly exhausted: boolean;
+}
+/** Hard stop on paging, so a busy key cannot turn one command into hundreds. */
+export declare const MAX_USAGE_EVENT_PAGES = 20;
+/**
+ * Walk this key's settled requests, newest first.
+ *
+ * Stops as soon as every id in `wanted` has been seen: a session of three
+ * requests should cost one page, not a full sweep of the window. Passing no
+ * `wanted` set walks until the pages run out.
+ */
+export declare function fetchUsageEvents(client: HttpClient, options?: {
+    days?: number;
+    wanted?: ReadonlySet<string>;
+    maxPages?: number;
+    signal?: AbortSignal;
+}): Promise<UsageEventsResult>;
 //# sourceMappingURL=account.d.ts.map

package/dist/api/account.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/api/account.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE;QACX,mBAAmB,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAyBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrE;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAMvB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,YAAY,CAAC,CAKvB"}
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/api/account.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE;QACX,mBAAmB,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAyBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrE;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAMvB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,YAAY,CAAC,CAKvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB,EAAE,MAAM,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACjB,GACL,OAAO,CAAC,iBAAiB,CAAC,CAgC5B"}

package/dist/api/account.js

@@ -37,3 +37,43 @@ export async function fetchSubscription(client) {
         .catch(explainScope);
     return data;
 }
+/** Hard stop on paging, so a busy key cannot turn one command into hundreds. */
+export const MAX_USAGE_EVENT_PAGES = 20;
+/**
+ * Walk this key's settled requests, newest first.
+ *
+ * Stops as soon as every id in `wanted` has been seen: a session of three
+ * requests should cost one page, not a full sweep of the window. Passing no
+ * `wanted` set walks until the pages run out.
+ */
+export async function fetchUsageEvents(client, options = {}) {
+    const maxPages = options.maxPages ?? MAX_USAGE_EVENT_PAGES;
+    const remaining = options.wanted ? new Set(options.wanted) : undefined;
+    const events = [];
+    let cursor = null;
+    let pages = 0;
+    while (pages < maxPages) {
+        const query = new URLSearchParams();
+        if (options.days !== undefined)
+            query.set("days", String(options.days));
+        if (cursor !== null)
+            query.set("cursor", cursor);
+        const { data } = await client
+            .getJson(`/keyinfo/usage-events?${query.toString()}`, {
+            signal: options.signal,
+        })
+            .catch(explainScope);
+        pages += 1;
+        for (const event of data.data ?? []) {
+            events.push(event);
+            remaining?.delete(event.request_id);
+        }
+        if (remaining !== undefined && remaining.size === 0) {
+            return { events, pages, exhausted: true };
+        }
+        cursor = data.next_cursor ?? null;
+        if (cursor === null)
+            return { events, pages, exhausted: true };
+    }
+    return { events, pages, exhausted: false };
+}

package/dist/commands/sessions.d.ts

@@ -0,0 +1,5 @@
+import { ExitCode } from "../output/exit-codes.js";
+import { type CommandIo } from "./runtime.js";
+export declare function sessionsCommand(argv: readonly string[], io: CommandIo): Promise<ExitCode>;
+export declare const DELETION_NOTICE: (id: string) => string;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/commands/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/commands/sessions.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAuBnD,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAgBtB,wBAAsB,eAAe,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC,QAAQ,CAAC,CAenB;AAqID,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAUX,CAAC"}