@njuptlzf/agent-chat-server 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,187 @@
1
+ /**
2
+ * 记忆提供方注册表。
3
+ *
4
+ * 服务器只认 id,不认实现:换记忆引擎 = 换 manifest 里的 `agent.memory.provider`,
5
+ * 本文件之外的服务器代码一行不动。
6
+ *
7
+ * 注册有两条路:
8
+ * 1. **内置**:`scoped-memory` 是平台自带的最小实现,作为默认值存在——没有它,
9
+ * 一个没声明 provider 的产品就会没有记忆,那是最糟的默认。
10
+ * 2. **外部**:产品在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是
11
+ * 产品目录内的相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions`
12
+ * 同一信任模型:仓库内代码、过准入扫描、进程内运行。
13
+ *
14
+ * 两条刻意选择:
15
+ * - **不可用即报错,不静默降级**。选了没装的 provider 就抛,并列出已注册 id。
16
+ * 静默回落默认实现,会让"我换了引擎"和"我忘了装"看起来一模一样。
17
+ * - **模块用动态 import**。静态导入会把提供方(可能是第三方包)的整棵源码拉进
18
+ * 本仓的 tsc program,跨仓源码进他人编译单元是最难收拾的一类耦合。
19
+ */
20
+
21
+ import { existsSync, readFileSync } from "node:fs";
22
+ import { createRequire } from "node:module";
23
+ import * as path from "node:path";
24
+ import { pathToFileURL } from "node:url";
25
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
26
+ import { scopedMemory } from "pi-scoped-memory";
27
+ import type { MemoryProvider, MemoryProviderModule } from "@njuptlzf/agent-chat-protocol";
28
+ import { auditExtensionSource } from "./extension-admission.ts";
29
+
30
+ /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
31
+ export const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
32
+
33
+ const requireFromRoot = createRequire(import.meta.url);
34
+
35
+ function installedVersion(pkg: string): string {
36
+ try {
37
+ const parsed = requireFromRoot(`${pkg}/package.json`) as { version?: unknown };
38
+ return typeof parsed.version === "string" ? parsed.version : "unknown";
39
+ } catch {
40
+ // Version is for logs, not behaviour: a missing package.json must not break open().
41
+ return "unknown";
42
+ }
43
+ }
44
+
45
+ const scopedMemoryProvider: MemoryProvider<ExtensionAPI> = {
46
+ id: DEFAULT_MEMORY_PROVIDER_ID,
47
+ version: installedVersion("pi-scoped-memory"),
48
+ async open(ctx) {
49
+ const dir = ctx.storageRoot;
50
+ const { rm } = await import("node:fs/promises");
51
+ return {
52
+ providerId: DEFAULT_MEMORY_PROVIDER_ID,
53
+ // scopedMemory appends its own snapshot in before_agent_start.
54
+ selfInjects: true,
55
+ factory: scopedMemory({ dir, autoCapture: true }),
56
+ async promptSection() {
57
+ return "";
58
+ },
59
+ async erase() {
60
+ // Its own file is <dir>/entries.jsonl; the directory is host-allocated,
61
+ // so removing it is exactly one tenant's worth of data.
62
+ await rm(dir, { recursive: true, force: true });
63
+ },
64
+ async dispose() {},
65
+ };
66
+ },
67
+ };
68
+
69
+ const registry = new Map<string, MemoryProvider<ExtensionAPI>>([
70
+ [scopedMemoryProvider.id, scopedMemoryProvider],
71
+ ]);
72
+
73
+ /** 已加载的外部模块,按解析后的绝对路径去重:同一文件 import 两次不该注册两次。 */
74
+ const loadedModules = new Map<string, Promise<MemoryProvider<ExtensionAPI>>>();
75
+
76
+ function assertProviderShape(candidate: unknown, source: string): MemoryProvider<ExtensionAPI> {
77
+ const provider = candidate as Partial<MemoryProvider<ExtensionAPI>> | null | undefined;
78
+ if (!provider || typeof provider !== "object") {
79
+ throw new Error(`${source}: default export must be a memory provider object`);
80
+ }
81
+ if (typeof provider.id !== "string" || provider.id.trim() === "") {
82
+ throw new Error(`${source}: provider.id must be a non-empty string`);
83
+ }
84
+ if (typeof provider.version !== "string") {
85
+ throw new Error(`${source}: provider.version must be a string`);
86
+ }
87
+ if (typeof provider.open !== "function") {
88
+ throw new Error(`${source}: provider.open must be a function`);
89
+ }
90
+ return provider as MemoryProvider<ExtensionAPI>;
91
+ }
92
+
93
+ /**
94
+ * 注册一个提供方。
95
+ *
96
+ * 同 id 重复注册直接抛:静默覆盖会让"哪个实现真的生效"变成必须读启动日志才能回答的
97
+ * 问题,而启动日志往往在出事后已经滚没了。
98
+ */
99
+ export function registerMemoryProvider(provider: MemoryProvider<ExtensionAPI>): void {
100
+ const existing = registry.get(provider.id);
101
+ if (existing && existing !== provider) {
102
+ throw new Error(`memory provider "${provider.id}" is already registered (${existing.version})`);
103
+ }
104
+ registry.set(provider.id, provider);
105
+ }
106
+
107
+ /**
108
+ * 解析 manifest 里的一条外部模块声明。
109
+ *
110
+ * 相对路径(`./x.ts`)必须落在产品目录内——与 `server.routes` 同一条纪律:写 `../`
111
+ * 等于让 manifest 加载任意文件。裸说明符(包名)交给 Node 解析,装在哪由依赖树决定。
112
+ */
113
+ export function resolveProviderModuleEntry(entry: string, productDir: string): string {
114
+ const trimmed = entry.trim();
115
+ if (trimmed === "") throw new Error("memory provider module path must not be empty");
116
+ if (trimmed.startsWith(".")) {
117
+ const resolved = path.resolve(productDir, trimmed);
118
+ const inside = path.resolve(productDir) + path.sep;
119
+ if (!resolved.startsWith(inside)) {
120
+ throw new Error(`memory provider module "${trimmed}" must stay inside the product directory`);
121
+ }
122
+ return resolved;
123
+ }
124
+ try {
125
+ return requireFromRoot.resolve(trimmed, { paths: [productDir] });
126
+ } catch (error) {
127
+ throw new Error(
128
+ `memory provider module "${trimmed}" is not resolvable from ${productDir}: ${(error as Error).message}`,
129
+ );
130
+ }
131
+ }
132
+
133
+ /**
134
+ * 从文件加载外部提供方。准入扫描与扩展同一套判据:提供方也在服务进程内运行,
135
+ * 读 env / 拉子进程在这里同样是跨层能力。
136
+ */
137
+ export async function loadMemoryProviderModule(
138
+ entry: string,
139
+ productDir: string,
140
+ ): Promise<MemoryProvider<ExtensionAPI>> {
141
+ const resolved = resolveProviderModuleEntry(entry, productDir);
142
+ const cached = loadedModules.get(resolved);
143
+ if (cached) return cached;
144
+
145
+ const loading = (async () => {
146
+ if (!existsSync(resolved)) {
147
+ throw new Error(`memory provider module "${entry}" does not exist (resolved: ${resolved})`);
148
+ }
149
+ const violations = auditExtensionSource(readFileSync(resolved, "utf8"), `memory provider "${entry}"`);
150
+ if (violations.length > 0) {
151
+ throw new Error(violations.map((v) => `criterion ${v.criterion}: ${v.reason}`).join("; "));
152
+ }
153
+ const mod = (await import(pathToFileURL(resolved).href)) as MemoryProviderModule<ExtensionAPI>;
154
+ const provider = assertProviderShape(mod.default, `memory provider "${entry}"`);
155
+ registerMemoryProvider(provider);
156
+ return provider;
157
+ })();
158
+
159
+ loadedModules.set(resolved, loading);
160
+ try {
161
+ return await loading;
162
+ } catch (error) {
163
+ // A failed load must not poison the cache: fixing the file and retrying is
164
+ // the normal path during development.
165
+ loadedModules.delete(resolved);
166
+ throw error;
167
+ }
168
+ }
169
+
170
+ export function listMemoryProviders(): Array<{ id: string; version: string; default: boolean }> {
171
+ return [...registry.values()].map((provider) => ({
172
+ id: provider.id,
173
+ version: provider.version,
174
+ default: provider.id === DEFAULT_MEMORY_PROVIDER_ID,
175
+ }));
176
+ }
177
+
178
+ export function resolveMemoryProvider(id: string | undefined): MemoryProvider<ExtensionAPI> {
179
+ const wanted = id ?? DEFAULT_MEMORY_PROVIDER_ID;
180
+ const provider = registry.get(wanted);
181
+ if (!provider) {
182
+ throw new Error(
183
+ `unknown memory provider "${wanted}" — available: ${[...registry.keys()].join(", ")}`,
184
+ );
185
+ }
186
+ return provider;
187
+ }
package/src/server.ts CHANGED
@@ -16,6 +16,7 @@ import { MCP_SPEC_ALLOWLIST_ENV, checkMcpDecl, mergedToolLabels, probeMcpProxy,
16
16
  import { baseUrlFromModelsJson, deleteProvider, keyEnvOf, modelToProbe, patchProvider, patchRouting, patchTiers, refreshProvider, testProvider, toModelsResponse, type ApiError } from "./models-api.ts";
17
17
  import { buildCommands, compileSystemPrompt, createProductSession, disposeProductSession, expandCommand, exportHistory, loadProductSkills, narrowMcpExposure, type UIPromptAnswer } from "./session.ts";
18
18
  import { auditPageWindow, toHistoryMessages, truncateLastTurn } from "./stores.ts";
19
+ import type { CostTable } from "./cost-model.ts";
19
20
  import type { AccountStateStore, AuditEvent, AuditRow, AuditStore, Authenticator, BillingOrder, BillingStore, HistoryStore, MembershipStore, MemberPoolStore, RunLogStore } from "./stores.ts";
20
21
  import type { Ledger } from "./ledger.ts";
21
22
  import type { Engine, EngineEvent, JobContext, JobRunResult } from "./orchestrator/engine.ts";
@@ -91,6 +92,11 @@ export interface ServerDeps {
91
92
  * 先占位再开跑,并发下不会超发(旧模型实测超发 140%)。
92
93
  */
93
94
  ledger: Ledger;
95
+ /**
96
+ * 成本表(统一成本模型)。omitted ⇒ settle 的 cu=0(CU 闸不启用,零行为变化);
97
+ * 主链 main.ts 由 loadCostTable 装配。按 run 起始 tier 模型折算,见 CostTable 注释。
98
+ */
99
+ costTable?: CostTable;
94
100
  /**
95
101
  * 编排引擎。omitted ⇒ 默认 `taskflow` 适配器(W1:单 phase 通路)。
96
102
  * 测试注入 `createFakeEngine()`,**不建 pi 会话、不调模型**——
@@ -1680,7 +1686,11 @@ export function createChatServer(deps: ServerDeps): Server {
1680
1686
  }, 15000);
1681
1687
 
1682
1688
  let session: Awaited<ReturnType<typeof createProductSession>> | undefined;
1683
- const mapper = createEventMapper();
1689
+ // costUsd 统一口径:装了 costTable 就按 run 起始 tier 模型折算 CU 写进 TokenUsage.costUsd;
1690
+ // 没装则传 undefined 让 mapper 回退 pi 的 cost.total(老部署零行为变化)。
1691
+ const mapper = createEventMapper(
1692
+ deps.costTable ? (u) => deps.costTable!.cuFor(tier.provider, tier.model, u) : undefined,
1693
+ );
1684
1694
  const accounting = createRunAccounting(limits.maxToolRounds);
1685
1695
  const toolCalls: Record<string, number> = {};
1686
1696
  let doneSent = false;
@@ -2130,7 +2140,9 @@ export function createChatServer(deps: ServerDeps): Server {
2130
2140
  const durationMs = Date.now() - startedAt.getTime();
2131
2141
  try {
2132
2142
  // 结算(I4):把占位换成实际消耗,多退少补。条件更新保证幂等(I6)。
2133
- await deps.ledger.settle({ operationId, userId, persona, tokens: usage.total });
2143
+ // CU 闸:按本次 run 的起始 tier 模型把 usage 折算成 CU(failover/多 phase 见 CostTable 边界)。
2144
+ const cu = deps.costTable?.cuFor(tier.provider, tier.model, usage) ?? 0;
2145
+ await deps.ledger.settle({ operationId, userId, persona, tokens: usage.total, cu });
2134
2146
  // Charge after the fact: the run already spent the tokens; the balance gate stops the next one.
2135
2147
  if (billingActive) {
2136
2148
  // 池优先拆账(结算=发放检查点之二):结算时**重读**池——
package/src/session.ts CHANGED
@@ -23,21 +23,27 @@ import {
23
23
  type Theme,
24
24
  type ToolDefinition,
25
25
  } from "@earendil-works/pi-coding-agent";
26
- import type { McpServerDecl } from "@njuptlzf/agent-chat-protocol";
26
+ import type { McpServerDecl, MemoryProviderSession } from "@njuptlzf/agent-chat-protocol";
27
27
  import { toProxySpawn, type McpConfigStore } from "./mcp-config.ts";
28
- import { scopedMemory } from "pi-scoped-memory";
28
+ import { loadMemoryProviderModule, resolveMemoryProvider } from "./memory-providers.ts";
29
29
  import type { LoadedProduct, ResolvedTier, ToolContext } from "./manifest.ts";
30
30
  import { agentFor, resolveTier } from "./manifest.ts";
31
31
  import { applyPersonaOverride, type PersonaConfigStore, type PersonaOverride } from "./persona-config.ts";
32
+ import { validateModelsCost } from "./cost-model.ts";
32
33
 
33
34
  /**
34
35
  * One shared ModelRuntime per process. Credentials live on the server only and
35
36
  * are injected from environment variables, never read from a user's home dir.
36
37
  */
37
38
  export async function createModelRuntime(dataDir: string, provider: string): Promise<ModelRuntime> {
39
+ // 成本模型校验:缺 costModel 声明放行(走全局倍率兜底),但声明了却非法的模型 fail fast。
40
+ // 2026-11-18 口径修订:ModelScope 这类按次计费模型不可能逐模型声明,统一 token×倍率兜底。
41
+ const modelsPath = `${dataDir}/models.json`;
42
+ const rawModels = JSON.parse(readFileSync(modelsPath, "utf8")) as unknown;
43
+ validateModelsCost(rawModels);
38
44
  const runtime = await ModelRuntime.create({
39
45
  authPath: `${dataDir}/auth.json`,
40
- modelsPath: `${dataDir}/models.json`,
46
+ modelsPath,
41
47
  });
42
48
  const envName = `${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
43
49
  const key = process.env[envName];
@@ -476,6 +482,15 @@ export function compileSystemPrompt(
476
482
  };
477
483
  }
478
484
 
485
+ /**
486
+ * Provider handle per live session.
487
+ *
488
+ * A WeakMap rather than a field on the session: the handle is host bookkeeping
489
+ * (store connection, lock file), and the session object belongs to pi. Keying by
490
+ * session also means a crashed session cannot leak a handle into the next one.
491
+ */
492
+ const memorySessionsByAgent = new WeakMap<AgentSession, MemoryProviderSession<ExtensionAPI>>();
493
+
479
494
  /**
480
495
  * Build a pi session locked down for multi-user serving:
481
496
  * - no built-in tools (no bash / read / write / edit), verified by test
@@ -583,17 +598,32 @@ export async function createProductSession(opts: CreateProductSessionOptions): P
583
598
  ]
584
599
  : [];
585
600
 
586
- // scopedMemory (plan B; npm 版本消费,正本在 github.com/njuptlzf/pi-scoped-memory):
587
- // one factory per session,
588
- // pointed at the tenant/scope directory the host computes. The plugin itself only
589
- // knows a directory — no userId/scope inside it, so it stays open-sourceable
590
- // without business knowledge. `qual || "default"` keeps single-track products
591
- // whole. `autoCapture` is host policy: every 10 turns one cheap completion
592
- // distils the tail of the transcript into a remembered point (secret-filtered,
593
- // silent on failure; the same opt-in stays false in the standalone CLI).
594
- const memoryExtensions = product.memoryEnabled
595
- ? [scopedMemory({ dir: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"), autoCapture: true })]
596
- : [];
601
+ // Memory comes from the provider registry, not from a hardcoded plugin:
602
+ // one open() per session, pointed at the tenant/scope directory the host
603
+ // computes. The provider never learns userId/scope semantics beyond that root,
604
+ // so an implementation can stay generic (and open-sourceable). Swapping the
605
+ // engine is a manifest edit — `agent.memory.provider`.
606
+ //
607
+ // External modules load here, before resolution: the platform does not know
608
+ // `hermes-scoped` exists until the product declares the module that provides
609
+ // it. Loading is per-file memoised, so this is one dynamic import per process.
610
+ if (product.memoryEnabled) {
611
+ for (const entry of product.memoryProviderModules) {
612
+ await loadMemoryProviderModule(entry, product.dir);
613
+ }
614
+ }
615
+ // Two disjoint roots per session: the scope (user × product × qual) and the
616
+ // user's cross-scope profile. Siblings, not nested — erasing one qualification
617
+ // must not delete the user's identity, and the provider enforces that too.
618
+ const memorySession = product.memoryEnabled
619
+ ? await resolveMemoryProvider(product.memoryProviderId).open({
620
+ storageRoot: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"),
621
+ sharedRoot: path.join(opts.dataDir, "memory", opts.userId, "profile"),
622
+ agentDir: opts.dataDir,
623
+ scope: { userId: opts.userId, productId: product.manifest.id, qual: opts.qual || "" },
624
+ })
625
+ : null;
626
+ const memoryExtensions = memorySession ? [memorySession.factory] : [];
597
627
 
598
628
  // pi prints the working directory into the system prompt, so use the per-product
599
629
  // data dir (empty of source code) rather than the product's source directory.
@@ -611,13 +641,19 @@ export async function createProductSession(opts: CreateProductSessionOptions): P
611
641
  // browser never has to remember to repeat it. `label` is display text the
612
642
  // operator wrote; ids alone would be meaningless to the model.
613
643
  const qualSection = qualSectionOf(product, opts.qual);
644
+ // A provider that does not inject on its own hands us the text; the host puts
645
+ // it where prompt sections belong. Asking for it here — before the session
646
+ // exists — is why `open()` and `mount()` are separate in the port.
647
+ const memorySection = memorySession && !memorySession.selfInjects
648
+ ? await memorySession.promptSection()
649
+ : "";
614
650
  const resourceLoader = new DefaultResourceLoader({
615
651
  cwd,
616
652
  agentDir: opts.dataDir,
617
653
  settingsManager,
618
654
  systemPrompt: effective.prompt,
619
655
  ...(() => {
620
- const extra = [qualSection, skillSupport.promptSection].filter((s) => s !== "");
656
+ const extra = [qualSection, memorySection, skillSupport.promptSection].filter((s) => s !== "");
621
657
  return extra.length > 0 ? { appendSystemPrompt: extra } : {};
622
658
  })(),
623
659
  // Manifest-declared extensions (operator-reviewed repo code). They load even
@@ -649,14 +685,18 @@ export async function createProductSession(opts: CreateProductSessionOptions): P
649
685
  sessionManager: SessionManager.inMemory(cwd, undefined, opts.history),
650
686
  settingsManager,
651
687
  });
652
- if (mcpExtensions.length > 0 || product.extensionPaths.length > 0) {
688
+ if (mcpExtensions.length > 0 || product.extensionPaths.length > 0 || memorySession) {
653
689
  // Emits session_start, which is when the MCP extension connects its servers
654
690
  // (in the background; the first prompt waits for "direct" servers) and when
655
691
  // manifest-declared extensions run their own startup handlers.
692
+ // A self-injecting memory provider needs this too: without the bind its
693
+ // before_agent_start hook never runs, and the failure mode is silence (tools
694
+ // work, the policy prompt never appears).
656
695
  // mode "rpc" is pi's own non-terminal contract: dialogs are data, not TUI
657
696
  // components — exactly what our SSE bridge below implements.
658
697
  await session.bindExtensions({ uiContext: createExtensionUIContext(opts), mode: "rpc" });
659
698
  }
699
+ if (memorySession) memorySessionsByAgent.set(session, memorySession);
660
700
  return session;
661
701
  }
662
702
 
@@ -675,6 +715,11 @@ export async function disposeProductSession(session: AgentSession): Promise<void
675
715
  }
676
716
  } finally {
677
717
  session.dispose();
718
+ // Provider handles go last and separately: the extension's shutdown handlers
719
+ // run inside a live session, while dispose() closes store/lock connections.
720
+ const memory = memorySessionsByAgent.get(session);
721
+ memorySessionsByAgent.delete(session);
722
+ if (memory) await memory.dispose();
678
723
  }
679
724
  }
680
725
 
@@ -3,7 +3,7 @@ import { DatabaseSync } from "node:sqlite";
3
3
  import type { FileEntry } from "@earendil-works/pi-coding-agent";
4
4
  import type { FeedbackEntry, FeedbackKind, FeedbackRating, FeedbackStatus, SessionSummary, TokenUsage } from "@njuptlzf/agent-chat-protocol";
5
5
  import { DEFAULT_PERSONA_ID } from "@njuptlzf/agent-chat-protocol";
6
- import { assertMembershipWrite, assertProductId, summarizeHistory, quotaBlockedReason } from "./stores.ts";
6
+ import { assertMembershipWrite, assertProductId, summarizeHistory, quotaBlockedCostReason, quotaBlockedReason } from "./stores.ts";
7
7
  import type { AccountStateStore, AuditEvent, AuditQuery, AuditRow, AuditStore, BillingAdjustOpts, BillingEntry, BillingOrder, BillingStore, NewOrderMeta, HistoryStore, MembershipStore, MemberPoolRow, MemberPoolStore, RunLogRecord, RunLogStore, RunUsageReport, RunUsageSummary } from "./stores.ts";
8
8
  import type { Ledger, ReserveInput, ReserveOutcome, SettleInput, SettleOutcome } from "./ledger.ts";
9
9
  import { RESERVATION_TTL_MS } from "./ledger.ts";
@@ -65,6 +65,8 @@ export function openDatabase(file: string, defaultScope = "", defaultPersona = D
65
65
  persona TEXT NOT NULL,
66
66
  day TEXT NOT NULL,
67
67
  tokens INTEGER NOT NULL DEFAULT 0,
68
+ -- 成本模型(CU 维度):独立额度闸,与 token 维度并列(用户拍板:不并入 T3)。
69
+ cost_units INTEGER NOT NULL DEFAULT 0,
68
70
  state TEXT NOT NULL,
69
71
  created_at INTEGER NOT NULL,
70
72
  expires_at INTEGER NOT NULL
@@ -315,6 +317,10 @@ function migrateScope(db: DatabaseSync, defaultScope: string, defaultPersona: st
315
317
  db.exec("ALTER TABLE feedback ADD COLUMN kind TEXT NOT NULL DEFAULT 'rating'");
316
318
  }
317
319
  if (!columns("feedback").includes("content")) db.exec("ALTER TABLE feedback ADD COLUMN content TEXT");
320
+ // 成本模型:预留账本加 CU 维度(独立额度闸)。老行 0 = 迁移前无成本计量,不回填。
321
+ if (!columns("quota_reservations").includes("cost_units")) {
322
+ db.exec("ALTER TABLE quota_reservations ADD COLUMN cost_units INTEGER NOT NULL DEFAULT 0");
323
+ }
318
324
  if (!columns("feedback").includes("status")) {
319
325
  db.exec("ALTER TABLE feedback ADD COLUMN status TEXT NOT NULL DEFAULT 'new'");
320
326
  }
@@ -565,6 +571,14 @@ export class SqliteLedger implements Ledger {
565
571
  return row?.tokens ?? 0;
566
572
  }
567
573
 
574
+ /** 今日已结算的 CU(成本模型独立闸)——结算后的预留仍留在表里,按 state='settled' 求和。 */
575
+ private cuUsed(userId: string, persona: string, day: string): number {
576
+ const row = this.db
577
+ .prepare("SELECT COALESCE(SUM(cost_units), 0) AS n FROM quota_reservations WHERE user_id = ? AND persona = ? AND day = ? AND state = 'settled'")
578
+ .get(userId, persona, day) as { n: number };
579
+ return row.n;
580
+ }
581
+
568
582
  async reserve(input: ReserveInput): Promise<ReserveOutcome> {
569
583
  const nowMs = this.now().getTime();
570
584
  const day = this.day();
@@ -594,10 +608,11 @@ export class SqliteLedger implements Ledger {
594
608
  }
595
609
 
596
610
  const tokenCap = input.caps?.tokenCap ?? this.dailyTokens;
611
+ let reserveTokens = 0;
597
612
  if (tokenCap !== undefined) {
598
613
  const used = this.tokensUsed(input.userId, input.persona, day);
599
- // 在飞预留的 tokens 目前恒为 0(一次 run 事前不可知)。保留这个求和,
600
- // 是为了将来有了「单次 run 的 token 上限」时能直接生效(§6.1 待办 T3)。
614
+ // T3:在飞预留的 token 上界已不再是恒 0——配了 perRunTokenCap 的 run 会按上界占位,
615
+ // 这里把它们计入总量判定,让 "已结算 + 在飞上界 <= tokenCap" 在并发下成立。
601
616
  const reserved = this.db
602
617
  .prepare(
603
618
  `SELECT COALESCE(SUM(tokens), 0) AS n FROM quota_reservations
@@ -608,15 +623,39 @@ export class SqliteLedger implements Ledger {
608
623
  this.db.exec("ROLLBACK");
609
624
  return { ok: false, reason: quotaBlockedReason("tokens", { runCap, tokenCap }) };
610
625
  }
626
+ // 钳制:上界不超过当日剩余量,保证不变量 I-T3-1;未配置则写 0(W3 现状)。
627
+ const cap = input.caps?.perRunTokenCap;
628
+ if (cap !== undefined && cap > 0) reserveTokens = Math.min(cap, tokenCap - used - reserved.n);
629
+ }
630
+
631
+ // 成本模型 CU 闸(独立于 token):同一 BEGIN IMMEDIATE 事务内判定,任一维触顶即拒。
632
+ let reserveCu = 0;
633
+ const dailyCostCap = input.caps?.dailyCostCap;
634
+ if (dailyCostCap !== undefined && dailyCostCap > 0) {
635
+ const usedCu = this.cuUsed(input.userId, input.persona, day);
636
+ const reservedCu = (
637
+ this.db
638
+ .prepare(
639
+ `SELECT COALESCE(SUM(cost_units), 0) AS n FROM quota_reservations
640
+ WHERE user_id = ? AND persona = ? AND day = ? AND state = 'reserved' AND expires_at > ?`,
641
+ )
642
+ .get(input.userId, input.persona, day, nowMs) as { n: number }
643
+ ).n;
644
+ if (usedCu + reservedCu >= dailyCostCap) {
645
+ this.db.exec("ROLLBACK");
646
+ return { ok: false, reason: quotaBlockedCostReason(input.caps ?? {}) };
647
+ }
648
+ const cap = input.caps?.perRunCostCap;
649
+ if (cap !== undefined && cap > 0) reserveCu = Math.min(cap, dailyCostCap - usedCu - reservedCu);
611
650
  }
612
651
 
613
652
  const expiresAt = nowMs + (input.ttlMs ?? RESERVATION_TTL_MS);
614
653
  this.db
615
654
  .prepare(
616
- `INSERT INTO quota_reservations (operation_id, user_id, persona, day, tokens, state, created_at, expires_at)
617
- VALUES (?, ?, ?, ?, 0, 'reserved', ?, ?)`,
655
+ `INSERT INTO quota_reservations (operation_id, user_id, persona, day, tokens, cost_units, state, created_at, expires_at)
656
+ VALUES (?, ?, ?, ?, ?, ?, 'reserved', ?, ?)`,
618
657
  )
619
- .run(input.operationId, input.userId, input.persona, day, nowMs, expiresAt);
658
+ .run(input.operationId, input.userId, input.persona, day, reserveTokens, reserveCu, nowMs, expiresAt);
620
659
  this.db.exec("COMMIT");
621
660
  return { ok: true, reservation: { operationId: input.operationId, expiresAt } };
622
661
  } catch (err) {
@@ -633,10 +672,10 @@ export class SqliteLedger implements Ledger {
633
672
  // 重复 settle 直接返回 already(不重复扣费)。
634
673
  const res = this.db
635
674
  .prepare(
636
- `UPDATE quota_reservations SET state = 'settled', tokens = ?
675
+ `UPDATE quota_reservations SET state = 'settled', tokens = ?, cost_units = ?
637
676
  WHERE operation_id = ? AND state = 'reserved'`,
638
677
  )
639
- .run(input.tokens, input.operationId) as { changes: number };
678
+ .run(input.tokens, input.cu ?? 0, input.operationId) as { changes: number };
640
679
  if (res.changes === 0) {
641
680
  this.db.exec("COMMIT");
642
681
  return "already";
package/src/stores.ts CHANGED
@@ -173,6 +173,23 @@ export class MemoryHistoryStore implements HistoryStore {
173
173
  export interface QuotaCaps {
174
174
  runCap?: number;
175
175
  tokenCap?: number;
176
+ /**
177
+ * 单次 run 的 token 上界(T3):reserve 时写入预留的 tokens,让在飞 run 参与
178
+ * 当日总量判定。<=0/缺省 = 不启用(预留写 0,W3 现状)。
179
+ */
180
+ perRunTokenCap?: number;
181
+ /**
182
+ * 成本模型(CU 维度,独立于 token 的第三闸):每 run 的 CU 上界与每日 CU 总量。
183
+ * 独立于 T3 的 tokenCap 体系——按次计费换算不成 token,并入会编造假 token 值导致失真。
184
+ */
185
+ perRunCostCap?: number;
186
+ dailyCostCap?: number;
187
+ }
188
+
189
+ /** 成本额度(CU)撞闸文案——与 token/run 并列,明示这是成本维度而非 token 维度。 */
190
+ export function quotaBlockedCostReason(caps: { dailyCostCap?: number }): string {
191
+ const cap = caps.dailyCostCap;
192
+ return `今日成本额度已用完${cap !== undefined && cap > 0 ? `(上限 ${cap} CU)` : ""},次日重置;如需提额请联系管理员`;
176
193
  }
177
194
 
178
195
  /** 万位读法:5000000 → 「500 万」(撞闸文案与权益卡共用,别在 UI 里二次造轮子)。 */