@eddyskywalker/dsh-chatgpt-subscription 0.21.0 → 0.23.0

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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"}