@ycodium-ai/plugin-api 0.2.2690 → 0.2.2694

package/dist/usage.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `@ycodium-ai/plugin-api/usage` —— agent 插件按**实例**提供的额度与 token 用量（ADR-0034）。
+ *
+ * 全是 `type`，外加一个纯函数 {@link parseRetryAfterMs}。宿主只做调用、合并编排账本、按价格表
+ * 算费用、单飞与「稍后再试」，再经 RPC 交给客户端；账号目录、凭据、代理、厂商地址都是插件的事。
+ *
+ * 只在用户明确点了才读：宿主不定时、不按有效期自动重查。插件只管「一次读」「一次写」。
+ *
+ * @module @ycodium-ai/plugin-api/usage
+ */
+/**
+ * 一段可显示的文字。`key` 在这个插件自己的 `locales/<locale>.json`（宿主命名空间
+ * `plugin:<pluginId>`）里解析，`values` 填占位符，与名片表单的 `titleKey` 同一套机制：
+ * 宿主不带兜底文案，键缺失界面明确画成缺失。`text` 是厂商给的原文（套餐名、窗口名），
+ * 原样显示，不翻译。
+ */
+export type ExecutorUsageText = {
+    readonly key: string;
+    readonly values?: Readonly<Record<string, string | number>>;
+} | {
+    readonly text: string;
+};
+/** 一个额度窗口：已用比例 + 重置时间。 */
+export type ExecutorQuotaWindow = {
+    /** 实例内稳定的标识，客户端用作行的 key（如 `session`、`weekly`、`limit-0`）。 */
+    readonly id: string;
+    readonly label: ExecutorUsageText;
+    /** 已用百分比，0..100，由插件夹紧。 */
+    readonly usedPercent: number;
+    /** 重置时刻，ISO 8601；厂商没给就是 null。 */
+    readonly resetsAt: string | null;
+    /** 窗口长度（毫秒）；说不清就缺席，不要猜。 */
+    readonly windowMs?: number;
+};
+/**
+ * 一个金额类额度：剩余金额（API key 的账户余额、订阅里的积分池）。厂商没报的字段保持
+ * null，不推算。
+ */
+export type ExecutorQuotaBalance = {
+    readonly id: string;
+    readonly label: ExecutorUsageText;
+    readonly remaining: number | null;
+    readonly used: number | null;
+    readonly limit: number | null;
+    /** 金额带 ISO 4217 币种（如 DeepSeek 余额是 CNY 或 USD）；`credits` 是厂商自己的积分。 */
+    readonly unit: {
+        readonly kind: "money";
+        readonly currency: string;
+    } | {
+        readonly kind: "credits";
+    };
+    readonly resetsAt: string | null;
+};
+/**
+ * 读不了的原因：
+ * - `missingCredentials`：没登录，或凭据读不到、读不懂。
+ * - `authRejected`：厂商回 401/403；刷新登录是 CLI 的事，插件不刷新。
+ * - `customEndpoint`：这个实例连的是自己的模型地址或钥匙，订阅额度不是它花的。
+ * - `unreachable`：连不上，或回了读不懂的响应；进程数已满、本次没跑起来也算。
+ * - `unsupportedLogin`：这种登录方式厂商没有额度接口（例如某家 API key 没有余额接口）。
+ * - `rateLimited`：厂商要求稍后再试，配 `retryAfterMs`。
+ */
+export type ExecutorQuotaUnavailableReason = "missingCredentials" | "authRejected" | "customEndpoint" | "unreachable" | "unsupportedLogin" | "rateLimited";
+export type ExecutorQuotaReading = {
+    readonly status: "available";
+    /** 套餐名，厂商给什么写什么（如 `Max 20x`）；没有就缺席。 */
+    readonly plan?: string;
+    readonly windows: ReadonlyArray<ExecutorQuotaWindow>;
+    readonly balances: ReadonlyArray<ExecutorQuotaBalance>;
+    /**
+     * 非敏感的账号标识（凭据文件路径、账号 id 都行，不要放 token）。宿主与客户端用它把
+     * 「两个实例共用同一个登录」的行合成一行。
+     */
+    readonly accountKey?: string;
+    /** 可用的「重置额度」张数；只有支持 `redeemQuotaReset` 的 agent 填。 */
+    readonly resetCredits?: {
+        readonly availableCount: number;
+    };
+} | {
+    readonly status: "unavailable";
+    readonly reason: ExecutorQuotaUnavailableReason;
+    /** 只在 `rateLimited` 时有意义：厂商要求等多久（毫秒）。宿主取不小于 10 秒的值。 */
+    readonly retryAfterMs?: number;
+};
+export type ExecutorQuotaResetResult = {
+    /** 与 Codex app-server 的 `ConsumeAccountRateLimitResetCreditOutcome` 同集合。 */
+    readonly outcome: "reset" | "nothingToReset" | "noCredit" | "alreadyRedeemed";
+};
+/**
+ * token 计数，与宿主 `UsageTokenTotals` 同口径（提案 0023 甲）：三个输入桶互斥，相加是总输入；
+ * `reasoningTokens` 是 `outputTokens` 的子集，不要再加一次。没有的项填 0，不要缺席。
+ * CLI 报的 `input_tokens` 若含缓存（Codex 就是），插件在这里拆开再给。
+ */
+export type ExecutorTokenTotals = {
+    readonly uncachedInputTokens: number;
+    /** 缓存读。 */
+    readonly cachedInputTokens: number;
+    /** 缓存写。 */
+    readonly cacheCreationTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+};
+export type ExecutorTokenRecord = {
+    /** 这条记录发生的时刻，ISO 8601。 */
+    readonly at: string;
+    /** 计价用的模型名；宿主按它在价格表里查，与 endpoint 无关。 */
+    readonly model: string;
+    /** CLI 侧的会话标识，用来数「有多少会话产生了花费」；没有就缺席。 */
+    readonly sessionId?: string;
+    readonly totals: ExecutorTokenTotals;
+    /** 厂商自己报了费用才填；填了宿主就用它，不再按价格表算。 */
+    readonly reportedCostUsd?: number;
+};
+export type ExecutorTokenUsageReading = {
+    /** 已去重：宿主不再按任何键去重。 */
+    readonly records: ReadonlyArray<ExecutorTokenRecord>;
+    /**
+     * 这批记录来自哪里。`homePath` 与 `volumeId` 一起是「同一份磁盘记录」的身份：宿主把两个
+     * 实例报出相同身份的结果只算一次（两个实例共用同一个账号目录时，否则同一份转录会记两遍）。
+     */
+    readonly source: {
+        readonly homePath: string;
+        readonly volumeId?: string;
+        readonly status: "ok" | "missing" | "partial" | "failed";
+        readonly scannedFiles?: number;
+        readonly skippedFiles?: number;
+        readonly malformedRecords?: number;
+        /** 给用户看的一句说明（如目录不存在）；不走 catalog，宿主原样带出。 */
+        readonly message?: string;
+    };
+};
+export type ExecutorUsage = {
+    /**
+     * 当前登录账号的额度。订阅登录返回额度窗口，API key 返回剩余金额。读不了是数据
+     * （`unavailable`），不要抛；只有程序错才抛。绝不刷新或写回凭据（CLI 自己管登录的
+     * 生命周期）。CLI 自己有额度接口的优先用它。
+     */
+    readonly readQuota?: (input: {
+        readonly signal?: AbortSignal;
+    }) => Promise<ExecutorQuotaReading>;
+    /**
+     * 时间段 `[since, until)` 内的 token 记录，来源是 CLI 自己的会话记录。去重（同一条消息在
+     * 多个文件里重复出现、fork 复制历史等）和增量缓存由插件负责。没有磁盘记录的 agent 不实现
+     * 它，用量走编排账本。
+     */
+    readonly readTokenUsage?: (input: {
+        /** ISO 8601 时刻，含。 */
+        readonly since: string;
+        /** ISO 8601 时刻，不含。 */
+        readonly until: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<ExecutorTokenUsageReading>;
+    /**
+     * 用一次厂商给的「重置额度」把当前窗口清零。只在用户明确点了才调，不自动、不重试。
+     * `idempotencyKey` 由宿主每次点击生成，原样交给厂商。厂商明确回绝（没有可用额度、窗口
+     * 本来就没用）是数据（`outcome`），不是抛错。
+     */
+    readonly redeemQuotaReset?: (input: {
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<ExecutorQuotaResetResult>;
+};
+/**
+ * 解析厂商响应里的 `Retry-After`，返回要等的毫秒数；解不出返回 null。
+ *
+ * 只认 1*DIGIT 秒数或 HTTP-date（RFC 9110 §10.2.3 的两种形态）。数字开头却不是纯秒数的
+ * 一律当没给——`Date.parse("1.5")` 会 lenient 地解成一个真实日期，那是把非法值当成了
+ * 「等到某个时刻」。过去的时刻返回 0，不留负数。
+ */
+export declare const parseRetryAfterMs: (header: string | null, nowMs: number) => number | null;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

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

package/dist/usage.js

@@ -0,0 +1,29 @@
+/**
+ * `@ycodium-ai/plugin-api/usage` —— agent 插件按**实例**提供的额度与 token 用量（ADR-0034）。
+ *
+ * 全是 `type`，外加一个纯函数 {@link parseRetryAfterMs}。宿主只做调用、合并编排账本、按价格表
+ * 算费用、单飞与「稍后再试」，再经 RPC 交给客户端；账号目录、凭据、代理、厂商地址都是插件的事。
+ *
+ * 只在用户明确点了才读：宿主不定时、不按有效期自动重查。插件只管「一次读」「一次写」。
+ *
+ * @module @ycodium-ai/plugin-api/usage
+ */
+/**
+ * 解析厂商响应里的 `Retry-After`，返回要等的毫秒数；解不出返回 null。
+ *
+ * 只认 1*DIGIT 秒数或 HTTP-date（RFC 9110 §10.2.3 的两种形态）。数字开头却不是纯秒数的
+ * 一律当没给——`Date.parse("1.5")` 会 lenient 地解成一个真实日期，那是把非法值当成了
+ * 「等到某个时刻」。过去的时刻返回 0，不留负数。
+ */
+export const parseRetryAfterMs = (header, nowMs) => {
+    if (header === null)
+        return null;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    if (/^\d/.test(trimmed))
+        return null;
+    const date = Date.parse(trimmed);
+    return Number.isNaN(date) ? null : Math.max(date - nowMs, 0);
+};
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAqB,EAAE,KAAa,EAAiB,EAAE;IACvF,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;AAC/D,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/plugin-api",
-  "version": "0.2.2690",
+  "version": "0.2.2694",
   "description": "Types and definePlugin for authoring Ycodium plugins. Zero runtime dependencies.",
   "keywords": [
     "ycodium"
@@ -32,6 +32,10 @@
       "types": "./dist/account-usage.d.ts",
       "import": "./dist/account-usage.js"
     },
+    "./usage": {
+      "types": "./dist/usage.d.ts",
+      "import": "./dist/usage.js"
+    },
     "./executor": {
       "types": "./dist/executor.d.ts",
       "import": "./dist/executor.js"