@eddyskywalker/dsh-chatgpt-subscription 0.21.0 → 0.22.0

package/lib/types/host/step-code/adapter.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Step Code（Step Plan 订阅）线路的 DSH 适配器。
+ *
+ * 形状与 GLM / WorkBuddy 同构（`extends LlmAdapter`：`listModels` / `resolveModel` /
+ * `prepareCall` / `stream` / `catalog` / `credentialFor`），但它**不碰任何协议细节**：
+ *
+ * - 请求体、流解析、用量与错误分类全部来自 `./mapper.ts`；
+ * - URL 全部来自 `./client.ts`（`stepChatCompletionsUrl` / `stepModelCatalogUrl`）；
+ * - 目录的归一化全部来自 `./model-catalog.ts`。
+ *
+ * 也就是说本文件只回答三件事：**这一行请求用哪个目录行**、**用哪把凭据**、
+ * **失败之后换不换账号**。任何一份 URL 拼接或 JSON 解析在这里出现第二遍，
+ * 就等于给线路造了第二条会漂移的真相。
+ *
+ * 三处刻意如此：
+ *
+ * 1. **凭据只在 `credentialFor()` 一处取。** 有号池时轮转，没有池时读单凭据存储
+ *    （无头 host 与测试的形态）。两条路径都**不刷新**：Step 的 api_key 永不过期，
+ *    号池的 refresh 钩子恒抛 `StepCodeCredentialRefreshError`，所以这里没有「捕获后重登」
+ *    这种分支——上游撤销一把 Key 的唯一诚实的处置是 401 时的 `markAuthFailed`。
+ * 2. **请求路径不联网。** 目录只读 `client.ts` 的进程内缓存，随包目录兜底；
+ *    实时目录是 `/catalog/refresh` 与登录/adopt 的产物。
+ * 3. **缓存用量在本进程累计。** 累计器住在本文件（流的末端是唯一知道用量帧的地方），
+ *    `/status` 由 `readStepCodeCacheStats()` 读它；路由不另算第二套口径。
+ */
+import { LlmAdapter, type GenerateOptions, type LlmModelInfo, type LlmProviderInfo, type LlmResolvedModelInfo, type PreparedAdapterCall, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentImageReader } from '../common/request-images.ts';
+import { type StepCodeCacheUsage } from './cache-stats.ts';
+import { type StepCodeCatalogEntry, type StepCodeUpstreamCredential } from './client.ts';
+import { type StepCodeModelEntry } from './model-catalog.ts';
+import { StepCodeCredentialStore, StepCodeModelSettingsStore, type StepCodePreferenceStore } from './token-store.ts';
+import type { StepCodeAccountPool } from './account-pool.ts';
+import { PROVIDER_ID, PROVIDER_NAME } from './types.ts';
+import type { StepCodeCacheStatsDto, StepCodeProfile } from '../../shared/step-code-contracts.ts';
+/**
+ * 这条路由的瞬时故障重试策略，与兄弟线路逐字一致。
+ *
+ * 刻意不在集合里：AUTH（被拒的 Key 每次都一样，而它只能重新授权）、
+ * PROVIDER_ERROR（400 或套餐拒绝）、ABORTED（调用方自己取消）。
+ */
+export declare const STEP_CODE_RETRY_POLICY_CONFIG: {
+    mode: 'normal';
+    maxRetries: number;
+    retryableCodes: string[];
+    backoff: {
+        initialDelayMs: number;
+        maxDelayMs: number;
+        jitterRatio: number;
+    };
+};
+/** 上游没有给 `Retry-After` 时，一次 429 按 5 分钟冷却。 */
+export declare const STEP_CODE_POOL_COOLDOWN_MS: number;
+/**
+ * 目录缓存 → 能力行。
+ *
+ * `client.ts` 的缓存装的是 `StepCodeCatalogEntry`（**只含端点真的报了的字段**），
+ * 而请求面与设置面要的是 `model-catalog.ts` 的 `StepCodeModelEntry`。
+ * 这里把前者还原成上游载荷再交给 {@link parseStepCodeModelListing}，而不是自己映射一遍：
+ * 档位表、`model_type` 过滤、上下文窗口兜底与 hint 生成都因此只有**一份**实现。
+ *
+ * 还原是等价的：缓存条目里每个字段都对应上游记录里的同名键，
+ * 而 `model_type` 的过滤在 `client.ts` 已经按同一条规则做过一次，
+ * 再跑一遍得到同一份集合（缓存里要么全带 `model_type` 要么全不带）。
+ */
+export declare function stepCodeModelCatalogFrom(entries: readonly StepCodeCatalogEntry[]): StepCodeModelEntry[];
+/**
+ * 这个部署能调的模型：**进程内缓存优先、随包目录兜底，请求路径上绝不联网**。
+ *
+ * 实时目录只由 `/catalog/refresh` 与登录/adopt 产生（见 `routes.ts`），
+ * 卡片打开时就能把它同步好；让每一次模型解析都去打上游只会把设置页变成一条压测。
+ */
+export declare function cachedStepCodeModelCatalog(profile?: StepCodeProfile): readonly StepCodeModelEntry[];
+/** 设置卡片渲染的模型总数（hub 概览与状态共用同一份读数）。 */
+export declare function stepCodeCatalogSize(): number;
+/**
+ * 记下一次请求的用量（流读到终止帧之后调用）。
+ *
+ * 口径全部借自 `cache-stats.ts` 的 {@link promptTokensOf}——它是本线路对
+ * 「聚合 prompt = 未命中 + 缓存读入 + 缓存写入」的唯一写法，这里不再复述一遍。
+ */
+export declare function rememberStepCodeCacheUsage(usage: StepCodeCacheUsage): void;
+/**
+ * 卡片要的那份切片；**尚无样本时返回 undefined**。
+ *
+ * 「还没有样本」与「样本全都没命中」必须能被区分：契约里 `cacheStats` 是可选的，
+ * 客户端把缺失渲染成占位符、把 0 渲染成真实的 0%，所以这里绝不下发一个全 0 的对象。
+ */
+export declare function readStepCodeCacheStats(): StepCodeCacheStatsDto | undefined;
+/** 一行请求要用的凭据：发请求只需要 `client.ts` 认得的那三件事。 */
+export interface StepCodePickedCredential {
+    /** 号池里的账号 id；无池（单凭据路径）时为 null。 */
+    accountId: string | null;
+    credentials: StepCodeUpstreamCredential;
+}
+export interface StepCodeAdapterOptions {
+    fetchFn?: typeof fetch;
+    attachments?: AttachmentImageReader;
+    /** 多账号号池；缺省走单凭据路径（无头 host 与测试）。 */
+    accountPool?: StepCodeAccountPool;
+}
+/**
+ * Step Code（Step Plan 订阅）线路的 LlmAdapter 实现。
+ *
+ * 请求面只有一个：四条 profile 全部走 OpenAI Chat Completions（官方
+ * `STEP_MODEL_API = "openai-completions"` 对所有模型一视同仁），所以本文件里
+ * **没有**协议面判定——而 region 也不在这里拼，URL 由 `client.ts` 从凭据的 profile 得出。
+ */
+export declare class StepCodeAdapter extends LlmAdapter {
+    private readonly store;
+    private readonly modelSettings;
+    private readonly preferences;
+    private readonly accountPool;
+    private readonly options;
+    constructor(store?: StepCodeCredentialStore, modelSettings?: StepCodeModelSettingsStore, preferences?: StepCodePreferenceStore, options?: StepCodeAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(): ResolvedRetryPolicy;
+    imageRequestPricing(): undefined;
+    private settings;
+    /** 这个部署的目录行（缓存优先，请求路径不联网）。 */
+    private catalog;
+    /**
+     * 这一行请求用哪份凭据。
+     *
+     * 有池时轮转；没有池时读单凭据存储（无头 host 与测试的形态）。
+     * 两条路径都**不刷新**：Step 的 api_key 永不过期，号池的 refresh 钩子恒抛
+     * `StepCodeCredentialRefreshError`，所以这里不存在「刷新失败后再试一次」的分支。
+     */
+    private credentialFor;
+    listModels(provider?: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * 一次请求的完整往返：选账号 → 定目录行 → 发 → 解析流。
+     *
+     * 账号轮转的循环只有一处：一次 429 或一次 AUTH 会把那个账号移出本次请求，
+     * 由另一个账号来发**同一份**请求体。没有池时这个循环只跑一次。
+     */
+    private requestStream;
+}
+export { PROVIDER_ID, PROVIDER_NAME };
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/host/step-code/adapter.d.ts.map

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

package/lib/types/host/step-code/adopt.d.ts

@@ -0,0 +1,201 @@
+/**
+ * adopt：只读导入本机已登录的 stepcode 客户端登录态。
+ *
+ * 上游落盘事实全部来自官方源码：`step/auth.ts`（路径、两代形状、占位符）、
+ * `step/environment.ts`（home / 配置根目录的解析），路径清单的骨架来自 `types.ts` 的
+ * STEPCODE_ADOPT_PATHS 与 STEPCODE_ADOPT_SHAPES。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 1 —— 本模块永不写入。它是 reader，而且只是 reader。
+ * ---------------------------------------------------------------------------
+ * 不得创建、修改、移动或删除任何属于 stepcode 客户端的文件：不以写方式打开任何文件、
+ * 不建目录、不改名、不 unlink。保证是**结构性**的而不是散文里的承诺——本模块从
+ * node:fs/promises **按名**只导入 readFile 与 stat 两个函数，不导入整个命名空间，
+ * 于是引入任何写操作都必须改动 import 列表，而那正是复审者第一行会看的地方。
+ *
+ * 官方自己的做法是**就地归一化**（`migrateLegacyStepCredential` 会改写 auth.json，
+ * `writeCanonicalCredentialFile` 还会 chmod 0600）。本插件明确不做那一步：
+ * 改写别人的文件是一次没有授权的写操作。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 2 —— 存在性与内容分成两个函数。
+ * ---------------------------------------------------------------------------
+ * `stepCodeAdoptPresence()` 便宜到可以在插件启动时调用，只 stat、从不 open：
+ * 没 opt in 的用户，他的令牌内容根本不会被读过。`adoptStepCodeSignIn()` 才是完整读取，
+ * 且只在用户显式选择之后才被调用。分开是全部意义所在：一个「顺手先读一下以防万一」
+ * 的启动路径会让 opt in 变成装饰。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 3 —— 认不出来的形状永远给一个**值**，永远不给异常。
+ * ---------------------------------------------------------------------------
+ * 没有文件、读不了、不是 JSON、形状不认识、解不出 profile、里面根本没有 Step 的条目——
+ * 全部落在 StepCodeAdoptResultDto 的 reason 枚举里。一个异常逃进设置路由只会变成 500，
+ * 而「没找到本机登录态」不是错误，是正常状态。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 4 —— **profile 缺失时不猜区域**。
+ * ---------------------------------------------------------------------------
+ * 区域是凭据的属性，而凭据里唯一说出区域的地方就是 profile（计划 §1、§10 风险 6）。
+ * 猜错的代价落在调用方身上：国区凭据打国际区端点会被拒，而国际区凭据打国区端点同样会，
+ * 且两次都是「鉴权失败」而不是「串区了」。所以缺 profile 的文件被判为 unsupported-shape，
+ * 让用户自己说这条登录态属于哪一区，而不是替他决定。
+ *
+ * ---------------------------------------------------------------------------
+ * 规则 5 —— 快照，不是活凭据。
+ * ---------------------------------------------------------------------------
+ * adopt 进来的是一份**快照**：用户在 Step 侧撤销之后它立刻失效，而本插件既不能刷新它
+ * （Step 的凭据没有刷新链）也不该改它。
+ */
+import { type StepCodeAdoptResultDto } from '../../shared/step-code-contracts.ts';
+import { type StepCodeStoredCredential } from './oauth.ts';
+/** stepcode 客户端改名前用的配置目录（逐字 LEGACY_RENAMED_CONFIG_DIR，environment.ts:9）。 */
+export declare const LEGACY_RENAMED_CONFIG_DIR = ".step-harness";
+/**
+ * 显式指定 auth.json 路径的环境变量（逐字 `getStepAuthPath`，auth.ts:18-20）。
+ *
+ * 有了它，本模块（以及测试）不必碰开发者的真实 profile 就能被驱动；
+ * 它也是官方自己给「嵌入式宿主」留的口子。
+ */
+export declare const STEPCODE_AUTH_PATH_ENV = "STEPCODE_AUTH_PATH";
+/** 显式指定旧登录态路径的环境变量（逐字 getLegacyStepAuthPaths，auth.ts:29-32）。 */
+export declare const STEPCODE_LEGACY_AUTH_PATH_ENV = "STEPCODE_LEGACY_AUTH_PATH";
+/** 配置目录名的环境覆盖（逐字 resolveStepConfigDir，environment.ts:30-32）。 */
+export declare const STEPCODE_CONFIG_DIR_ENV = "STEPCODE_CONFIG_DIR";
+/** agent 目录名的环境覆盖（逐字 resolveStepConfigRoot，environment.ts:48-57）。 */
+export declare const STEP_CODING_AGENT_DIR_ENV = "STEP_CODING_AGENT_DIR";
+/**
+ * stepcode 客户端的家目录（逐字 resolveStepHomeDir，environment.ts:25-27）。
+ *
+ * 读的是 HOME / USERPROFILE 再退到 os.homedir()——与官方同一口径，所以 Windows 上
+ * 拿到的是 %USERPROFILE%、POSIX 上是 ~。
+ */
+export declare function stepCodeHomeDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * stepcode 配置根目录（auth.json 与它同级放着，逐字 resolveStepConfigRoot）。
+ *
+ * 环境覆盖优先：官方把 `STEP_CODING_AGENT_DIR` 解析成绝对路径再取父目录，
+ * 因为「textual 的 ..」会落到进程工作目录旁边。本文件照抄那个顺序。
+ */
+export declare function stepCodeConfigRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * adopt 会读的每一个路径，按优先级排列。
+ *
+ * 顺序逐字照抄官方 `getLegacyStepAuthPaths`（auth.ts:29-44）给的理由：canonical root
+ * 那个文件排在最前，因为它是「需要就地归一化的旧形状」；剩下的覆盖上一个版本写下的文件。
+ *
+ * 前三条来自 `types.ts` 的 STEPCODE_ADOPT_PATHS（相对配置根目录的片段）；后两条是
+ * 改名前的 `.step-harness` 根，官方仍在扫，本插件也扫——多看一个只读文件没有代价。
+ *
+ * 纯函数、不碰文件系统：只为渲染卡片调它也是安全的，优先级因此可以脱离磁盘被测试。
+ */
+export declare function stepCodeAdoptPaths(env?: NodeJS.ProcessEnv): readonly string[];
+/**
+ * 客户端模板文件里的占位符（逐字 auth.ts:203,220）。
+ *
+ * 它是一个**看起来像凭据**的字符串：不排除它，`{ "apiKey": "<your_api_key>" }`
+ * 会被当成一次成功的 adopt，然后把一个 401 发到上游。
+ */
+export declare const STEPCODE_PLACEHOLDER_KEY = "<your_api_key>";
+/** adopt 成功时带走的凭据：凭据 + 它是从哪儿、哪个文件捡来的。 */
+export interface StepCodeAdoptedCredential {
+    /**
+     * 池里的判别式，恒为 true。
+     *
+     * 一个可被测试的布尔，好过一句需要人去读的注释：adopt 快照永不可刷新、且它的删除
+     * 语义与本插件自己登出来的账号不同（后者只删本插件自己的文件）。
+     */
+    readonly adopted: true;
+    /** 来源标识，供卡片与池记录。 */
+    readonly source: typeof STEPCODE_ADOPT_SOURCE;
+    /** 读到的确切路径，卡片可以把它显示给用户。 */
+    readonly sourcePath: string;
+    /** 本线路的凭据形态（oauth + 静态哨兵 + MAX_SAFE_INTEGER）。 */
+    readonly credentials: StepCodeStoredCredential;
+}
+/** adopt 快照的来源标识。 */
+export declare const STEPCODE_ADOPT_SOURCE = "stepcode-client";
+/** adopt 失败原因，直接取自冻结契约的 StepCodeAdoptResultDto['reason']，不另立一套。 */
+export type StepCodeAdoptReason = NonNullable<StepCodeAdoptResultDto['reason']>;
+/**
+ * 每个失败原因对应的一句可照做的下一步（给路由层与设置卡片用）。
+ *
+ * 四个取值各自的下一步不同，所以分开写而不是拼一句「导入失败」：
+ * 前两个是「本机没有 / 读不懂」，第三个是「这份登录态没有说自己是哪一区」，
+ * 第四个是「这个文件里根本没有 Step 的条目」。
+ */
+export declare const ADOPT_REASON_HINTS: Readonly<Record<StepCodeAdoptReason, string>>;
+/** 解析一份已读入的 JSON 的结论：要么带凭据，要么带一个 reason。 */
+export type StepCodeAdoptParse = {
+    readonly ok: true;
+    readonly adopted: StepCodeAdoptedCredential;
+} | {
+    readonly ok: false;
+    readonly reason: StepCodeAdoptReason;
+};
+/**
+ * 把一份已读入的登录态文档解析成本线路的 adopt 结果。
+ *
+ * 纯函数、导出：两代形状的规则可以脱离文件系统被测试（测试用夹具驱动它）。
+ *
+ * 顺序照抄官方 `readLegacyStepCredential`（auth.ts:193-235）：
+ *
+ * 1. 顶层 `{ apiKey, profile?, uid? }`（StepCode 自己写的老文件）；
+ * 2. `{ step: { type:'oauth', access|refresh|expires|profile|uid } }`（pi 形状；
+ *    官方在那里也认 `key`，auth.ts:214-220）；
+ * 3. 都不匹配时：有别的 provider 条目 → `not-a-stepcode-login`（契约给的那个例子），
+ *    否则 → `invalid-credentials`。
+ *
+ * 认出形状但**没有 profile** 时是 `unsupported-shape`：见模块头的规则 4。
+ * uid 不合格只丢弃 uid，不丢掉整份登录态（uid 只影响账号显示与去重）。
+ */
+export declare function parseAdoptedStepCodeCredential(value: unknown, sourcePath: string): StepCodeAdoptParse;
+/**
+ * 本机有没有可导入的 stepcode 登录态文件。
+ *
+ * 启动路径安全：它**从不**打开候选文件去读，所以没 opt in 的用户，令牌内容根本没被碰过——
+ * 既不被它读，也不被渲染卡片的路由读。只 stat，透露的是存在与时间戳，没有别的。
+ *
+ * 刻意**不**在这里回答「有效 / 过期 / 是不是 JSON」：那需要它存在的目的就是避免的那次读。
+ */
+export declare function stepCodeAdoptPresence(paths?: readonly string[]): Promise<boolean>;
+/**
+ * 一次 adopt 的结论：给卡片的切片 + （成功时）真正要落盘的凭据。
+ *
+ * 两者**刻意分开**：凭据只在这里，绝不进 StepCodeAdoptResultDto（那个类型要下发到客户端，
+ * 契约里的一切都是公开信息）。
+ */
+export interface StepCodeAdoptOutcome {
+    /** 卡片渲染用；不含任何凭据。 */
+    readonly result: StepCodeAdoptResultDto;
+    /** 成功时才有：带来源标记的凭据，交给号池或凭据存储落盘。 */
+    readonly adopted?: StepCodeAdoptedCredential;
+    /** 实际读到的文件（设置卡片要把它显示出来）。 */
+    readonly sourcePath?: string;
+}
+export interface StepCodeAdoptOptions {
+    /** 候选路径；缺省 stepCodeAdoptPaths()（测试注入夹具路径）。 */
+    paths?: readonly string[];
+    /** 环境变量读取处；缺省 process.env，且**调用时**读取。 */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * 只读导入本机 stepcode 登录态；第一个可用候选获胜。
+ *
+ * **只在用户显式 opt in 之后调用**（见模块头规则 2）。
+ *
+ * 永不抛出、永不拒绝：文件不存在、读不了、不是 JSON、形状不认识、解不出 profile——
+ * 全部是一个带 reason 的值。设置路由不能因为用户文件正在被写就整个失败。
+ *
+ * 两个候选路径的失败被区分开：一个文件读不出来（invalid-credentials）会继续看下一个，
+ * 而**全部**候选都失败时，返回的是第一个真实失败的原因——「有文件但读不出来」
+ * 与「根本没有文件」给用户的下一步不同。
+ */
+export declare function adoptStepCodeSignIn(options?: StepCodeAdoptOptions): Promise<StepCodeAdoptOutcome>;
+/**
+ * 只要那张给卡片的切片（不带走凭据）。
+ *
+ * 渲染「本机有没有可导入的东西」时用这个：它仍要读文件（所以仍要显式 opt in），
+ * 但把凭据留在本模块的返回值之外。
+ */
+export declare function readStepCodeAdoptResult(options?: StepCodeAdoptOptions): Promise<StepCodeAdoptResultDto>;
+//# sourceMappingURL=adopt.d.ts.map

package/lib/types/host/step-code/adopt.d.ts.map

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

package/lib/types/host/step-code/cache-stats.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Cache-waste diagnosis for the Step Code route: how many prompt tokens should
+ * have been cache reads and were billed fresh anyway.
+ *
+ * Ported from the official Step-Code client
+ * (`_ref-stepcode/packages/coding-agent/src/core/cache-stats.ts`, 164 lines).
+ * The arithmetic and the counting rules are kept as they are; only the data
+ * sources change, because this repository has no `SessionEntry` type and this
+ * route must not depend on one:
+ *
+ * - the official scan walks persisted session entries; here the caller hands in
+ *   an already-ordered list of {@link StepCodeCacheEntry} values,
+ * - the official message carries `usage.cost`; on this route every price is
+ *   zero, so {@link StepCodeCacheMiss.missedCost} is 0 and the card is told not
+ *   to render money at all.
+ *
+ * WHY the diagnosis is worth porting here rather than into the shared cache
+ * layer: Step's cache is automatic and invisible. The client gets no marker when
+ * a prefix stopped being reused, so the only evidence is the read number on the
+ * next turn — and the question "did we throw the prefix away, or did the server?"
+ * is answered by comparing against the previous request.
+ *
+ * Pure functions only: no state is retained here, so the caller owns the history
+ * and the lifetime of it.
+ *
+ * @module dsh-chatgpt-subscription/step-code-cache-stats
+ */
+/**
+ * Prompt-cache time-to-live.
+ *
+ * An idle gap longer than this is the likeliest explanation for a miss, and it
+ * is the only cheap hint this diagnosis can give: the upstream offers no
+ * "your entry expired" signal, so the idle period is the whole evidence.
+ * Five minutes is the TTL the official client uses for the same notice.
+ */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Misses at or below this are cache-breakpoint granularity, not waste.
+ *
+ * A prefix cache breaks at block boundaries, so a few hundred tokens of drift
+ * between two turns is normal re-shuffling. Reporting it teaches the user to
+ * ignore the notice, which costs the one notice that mattered.
+ */
+export declare const NOISE_FLOOR_TOKENS = 1024;
+/**
+ * Whether this route can put money on a cache number.
+ *
+ * Always false: the official model table hardwires every price to 0
+ * (`STEP_MODEL_DEFAULTS.cost`, `step-provider/index.ts:102`), and Step Plan is a
+ * subscription rather than a metered SKU. A caller that renders
+ * `missedCost` from a zero price shows a correct, useless "you saved $0"; the
+ * alternative — inventing a rate — would show a plausible, false number. So the
+ * card shows the token dimension alone.
+ */
+export declare function isCacheWasteCostPriced(): boolean;
+/** Disjoint token counts for one assistant turn, as this route reports them. */
+export interface StepCodeCacheUsage {
+    /** Uncached prompt tokens. */
+    inputTokens: number;
+    /** Output tokens, which reasoning is billed against. */
+    outputTokens?: number;
+    /** Prompt tokens served from the automatic prefix cache. */
+    cacheReadTokens?: number;
+    /**
+     * Always 0 on this route — the cache is automatic, so there is no client-side
+     * write to count. Kept in the shape because the arithmetic below reads it.
+     */
+    cacheWriteTokens?: number;
+}
+/** One assistant turn: what it spent, when, and on which model. */
+export interface StepCodeCacheTurn {
+    readonly usage: StepCodeCacheUsage;
+    /** Epoch milliseconds the request completed. */
+    readonly timestamp: number;
+    /**
+     * Identity of the model route, `{provider}/{model}`.
+     *
+     * Compared as a string rather than as two fields so a caller can extend it
+     * (region, profile, wire) without this file needing to know what a "route" is.
+     */
+    readonly modelKey: string;
+}
+/**
+ * What the previous request in this segment left behind.
+ *
+ * Everything in its prompt should be a cache read on the next turn; that is the
+ * premise the whole diagnosis rests on.
+ */
+export interface StepCodePreviousRequest {
+    /** Its aggregate prompt count. */
+    promptTokens: number;
+    readonly modelKey: string;
+    readonly timestamp: number;
+    /**
+     * Sticky: some earlier request in this segment reported cache activity.
+     *
+     * This is what separates two cases that look identical from the outside — a
+     * total miss on a read-reporting endpoint versus an endpoint that reports no
+     * caching at all. Without it, the second would be reported as a total miss on
+     * every single turn.
+     */
+    readonly reportedCache: boolean;
+}
+/** A counted cache miss on one assistant turn. */
+export interface StepCodeCacheMiss {
+    /** Tokens that were in the previous prompt and were NOT read from cache. */
+    missedTokens: number;
+    /** Always 0 on this route; see {@link isCacheWasteCostPriced}. */
+    missedCost: number;
+    /** Milliseconds since the previous request, which last refreshed the cache. */
+    idleMs: number;
+    /** True when the model changed relative to the previous request. */
+    modelChanged: boolean;
+}
+/** Cumulative waste across a segment. */
+export interface StepCodeCacheWasteTotals {
+    missedTokens: number;
+    missedCost: number;
+    /** Counted misses — turns above {@link NOISE_FLOOR_TOKENS}. */
+    missCount: number;
+}
+/**
+ * One entry of the ordered history this diagnosis scans.
+ *
+ * The two context-change kinds exist because compaction and branch summaries
+ * legitimately REPLACE the prompt: the next turn's context is new content, not
+ * re-billed content, so counting it as waste would be wrong.
+ */
+export type StepCodeCacheEntry = {
+    readonly kind: 'turn';
+    readonly turn: StepCodeCacheTurn;
+} | {
+    readonly kind: 'compaction';
+} | {
+    readonly kind: 'branch-summary';
+};
+/** Aggregate prompt count of one turn: uncached input plus both cache buckets. */
+export declare function promptTokensOf(usage: StepCodeCacheUsage): number;
+/**
+ * The segment state one turn leaves behind, or undefined when it carries no
+ * prompt and therefore cannot be a baseline.
+ */
+export declare function asPreviousRequest(turn: StepCodeCacheTurn, reportedCache: boolean): StepCodePreviousRequest | undefined;
+/**
+ * Cache miss for one turn relative to the previous request, or undefined when
+ * nothing is counted.
+ *
+ * Not counted: the first turn (no baseline), a turn with no prompt, a turn whose
+ * segment reported no cache activity at all (see
+ * {@link StepCodePreviousRequest.reportedCache}), and a miss at or below
+ * {@link NOISE_FLOOR_TOKENS}.
+ */
+export declare function detectCacheMiss(prev: StepCodePreviousRequest | undefined, turn: StepCodeCacheTurn): StepCodeCacheMiss | undefined;
+/**
+ * Whether an idle period is long enough to suspect the cache entry expired.
+ *
+ * Strictly greater: an entry alive exactly to its TTL has not expired, and
+ * rounding must not turn that into a warning.
+ */
+export declare function cacheLikelyExpired(idleMs: number): boolean;
+/**
+ * Cumulative cache waste across a segment: prompt tokens that should have been
+ * cache reads because they were in the previous turn's prompt, and were not.
+ */
+export declare function computeCacheWaste(entries: readonly StepCodeCacheEntry[]): StepCodeCacheWasteTotals;
+/**
+ * Every counted miss, keyed by the turn that paid for it (by reference).
+ *
+ * The key is the turn object, so a caller re-deriving notices while rebuilding a
+ * transcript can look a turn up without inventing a second identity for it.
+ */
+export declare function collectCacheMisses(entries: readonly StepCodeCacheEntry[]): ReadonlyMap<StepCodeCacheTurn, StepCodeCacheMiss>;
+/**
+ * The miss for a turn that has just completed.
+ *
+ * `entries` must NOT already contain `turn`: the caller passes the history as
+ * of before the turn. A turn that is present twice would be compared against
+ * itself, which always reads as a total miss.
+ */
+export declare function detectCacheMissForTurn(entries: readonly StepCodeCacheEntry[], turn: StepCodeCacheTurn): StepCodeCacheMiss | undefined;
+//# sourceMappingURL=cache-stats.d.ts.map

package/lib/types/host/step-code/cache-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../../../src/host/step-code/cache-stats.ts"],"names":[],"mappings":"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"}