@njuptlzf/agent-chat-server 0.2.1 → 0.4.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.
Files changed (55) hide show
  1. package/dist/branding-ui.d.ts +16 -0
  2. package/dist/branding-ui.js +119 -0
  3. package/dist/checkpoint-store.d.ts +78 -0
  4. package/dist/checkpoint-store.js +52 -0
  5. package/dist/components.d.ts +15 -0
  6. package/dist/components.js +50 -0
  7. package/dist/extension-admission.d.ts +32 -0
  8. package/dist/extension-admission.js +155 -0
  9. package/dist/flows.d.ts +49 -0
  10. package/dist/flows.js +208 -0
  11. package/dist/ledger.d.ts +90 -0
  12. package/dist/ledger.js +115 -0
  13. package/dist/main.js +14 -2
  14. package/dist/manifest.js +27 -1
  15. package/dist/orchestrator/engine.d.ts +132 -0
  16. package/dist/orchestrator/engine.js +1 -0
  17. package/dist/orchestrator/engines/fake.d.ts +14 -0
  18. package/dist/orchestrator/engines/fake.js +282 -0
  19. package/dist/orchestrator/engines/taskflow.d.ts +4 -0
  20. package/dist/orchestrator/engines/taskflow.js +541 -0
  21. package/dist/orchestrator/run-spec.d.ts +154 -0
  22. package/dist/orchestrator/run-spec.js +11 -0
  23. package/dist/persona-config.js +12 -0
  24. package/dist/server.d.ts +27 -2
  25. package/dist/server.js +595 -187
  26. package/dist/session.js +2 -1
  27. package/dist/sqlite-stores.d.ts +46 -6
  28. package/dist/sqlite-stores.js +292 -33
  29. package/dist/stores.d.ts +0 -36
  30. package/dist/stores.js +0 -27
  31. package/dist/suggestions.d.ts +60 -0
  32. package/dist/suggestions.js +107 -0
  33. package/dist/testing.d.ts +5 -4
  34. package/dist/testing.js +5 -4
  35. package/package.json +65 -64
  36. package/scripts/agentchat-integrate.mjs +852 -852
  37. package/src/branding-ui.ts +126 -0
  38. package/src/checkpoint-store.ts +122 -0
  39. package/src/components.ts +66 -0
  40. package/src/extension-admission.ts +131 -0
  41. package/src/flows.ts +244 -0
  42. package/src/ledger.ts +171 -0
  43. package/src/main.ts +16 -2
  44. package/src/manifest.ts +27 -1
  45. package/src/orchestrator/engine.ts +134 -0
  46. package/src/orchestrator/engines/fake.ts +330 -0
  47. package/src/orchestrator/engines/taskflow.ts +626 -0
  48. package/src/orchestrator/run-spec.ts +171 -0
  49. package/src/persona-config.ts +12 -1
  50. package/src/server.ts +611 -183
  51. package/src/session.ts +2 -1
  52. package/src/sqlite-stores.ts +343 -35
  53. package/src/stores.ts +0 -41
  54. package/src/suggestions.ts +146 -0
  55. package/src/testing.ts +4 -4
package/dist/session.js CHANGED
@@ -445,7 +445,8 @@ export async function createProductSession(opts) {
445
445
  },
446
446
  ]
447
447
  : [];
448
- // scopedMemory (, plan B; vendored copy at 0.2.0): one factory per session,
448
+ // scopedMemory (plan B; npm 版本消费,正本在 github.com/njuptlzf/pi-scoped-memory):
449
+ // one factory per session,
449
450
  // pointed at the tenant/scope directory the host computes. The plugin itself only
450
451
  // knows a directory — no userId/scope inside it, so it stays open-sourceable
451
452
  // without business knowledge. `qual || "default"` keeps single-track products
@@ -1,7 +1,10 @@
1
1
  import { DatabaseSync } from "node:sqlite";
2
2
  import type { FileEntry } from "@earendil-works/pi-coding-agent";
3
- import type { SessionSummary, TokenUsage } from "@njuptlzf/agent-chat-protocol";
4
- import type { AccountStateStore, AuditEvent, AuditQuery, AuditRow, AuditStore, BillingAdjustOpts, BillingEntry, BillingOrder, BillingStore, NewOrderMeta, HistoryStore, MembershipStore, MemberPoolRow, MemberPoolStore, QuotaCaps, QuotaDecision, QuotaGate, RunLogRecord, RunLogStore, RunUsageReport, RunUsageSummary } from "./stores.ts";
3
+ import type { SessionSummary } from "@njuptlzf/agent-chat-protocol";
4
+ import type { AccountStateStore, AuditEvent, AuditQuery, AuditRow, AuditStore, BillingAdjustOpts, BillingEntry, BillingOrder, BillingStore, NewOrderMeta, HistoryStore, MembershipStore, MemberPoolRow, MemberPoolStore, RunLogRecord, RunLogStore, RunUsageReport, RunUsageSummary } from "./stores.ts";
5
+ import type { Ledger, ReserveInput, ReserveOutcome, SettleInput, SettleOutcome } from "./ledger.ts";
6
+ import type { CheckpointStore, RunCheckpoint, RunJobRow } from "./checkpoint-store.ts";
7
+ import type { PhaseCheckpoint } from "./orchestrator/run-spec.ts";
5
8
  import type { VerifyResult } from "./audit.ts";
6
9
  /**
7
10
  * SQLite-backed stores (node:sqlite, no extra dependency). One connection per
@@ -59,19 +62,35 @@ export declare class SqliteHistoryStore implements HistoryStore {
59
62
  scopeOf(userId: string, sessionId: string): Promise<string | undefined>;
60
63
  list(userId: string, scope?: string): Promise<SessionSummary[]>;
61
64
  }
62
- /** Per-user token budget per day, persisted in the quota table. */
63
- export declare class SqliteQuotaGate implements QuotaGate {
65
+ /**
66
+ * 预留-结算账本,SQLite 实现(M-14 W3)。
67
+ *
68
+ * 并发正确性靠三件事:
69
+ * ① `BEGIN IMMEDIATE` 把「数在飞 + 插入预留」放进同一个写事务(SQLite 串行化写);
70
+ * ② **计数口径只认 `quota_reservations`**(`settled` = 今日已跑,未过期 `reserved` = 在飞)。
71
+ * 不再用「查 runs 表 + 事后累加」——那正是并发超发的来源;
72
+ * ③ `expires_at` 让崩溃留下的孤儿预留自动失效,不需要「启动时清理」这种会漏的逻辑。
73
+ *
74
+ * token 上限的能力边界见 `ledger.ts` 文件头:run 位精确,token 只能保证「到顶就不再开新 run」。
75
+ */
76
+ export declare class SqliteLedger implements Ledger {
64
77
  private readonly db;
65
78
  private readonly dailyTokens;
66
79
  private readonly now;
67
80
  constructor(db: DatabaseSync, dailyTokens: number | undefined, now?: () => Date);
68
81
  private day;
69
- check(userId: string, caps: QuotaCaps | undefined, persona: string): Promise<QuotaDecision>;
82
+ /** 上限口径:今日已结算 + 未过期的在飞。 */
83
+ private countForCap;
84
+ private countSettled;
85
+ private tokensUsed;
86
+ reserve(input: ReserveInput): Promise<ReserveOutcome>;
87
+ settle(input: SettleInput): Promise<SettleOutcome>;
88
+ release(operationId: string): Promise<void>;
70
89
  todayStats(userId: string, persona: string): Promise<{
71
90
  runsToday: number;
72
91
  tokensToday: number;
73
92
  }>;
74
- record(userId: string, usage: TokenUsage, persona: string): Promise<void>;
93
+ sweepExpired(now?: number): Promise<number>;
75
94
  }
76
95
  /** 会员有效期,SQLite 实现。 */
77
96
  export declare class SqliteMembership implements MembershipStore {
@@ -171,3 +190,24 @@ export declare class SqliteAudit implements AuditStore {
171
190
  verify(): Promise<VerifyResult>;
172
191
  purge(cutoffIso: string): Promise<number>;
173
192
  }
193
+ /**
194
+ * 持久化 checkpoint 与 run_jobs(M-14 / R-010 W4)。
195
+ *
196
+ * 两条写入纪律,与 `SqliteLedger` 同源:
197
+ * ① `run_checkpoints` 用 `INSERT … ON CONFLICT DO UPDATE`——续跑成功后产物要更新,
198
+ * 但同一 `(run_id, phase_id)` 永远只有一行;
199
+ * ② `run_jobs` 的租约回收用**条件写**(`WHERE state='running' AND lease_until<=?`),
200
+ * 绝不先读后写:并发两个进程同时回收,条件更新让它们天然只生效一次。
201
+ */
202
+ export declare class SqliteCheckpointStore implements CheckpointStore {
203
+ private readonly db;
204
+ private readonly now;
205
+ constructor(db: DatabaseSync, now?: () => number);
206
+ saveJob(runId: string, job: RunJobRow): Promise<void>;
207
+ savePhase(checkpoint: PhaseCheckpoint & {
208
+ runId: string;
209
+ }): Promise<void>;
210
+ load(runId: string): Promise<RunCheckpoint | undefined>;
211
+ jobs(runId: string): Promise<RunJobRow[]>;
212
+ reclaimOrphans(runId: string, now?: number): Promise<number>;
213
+ }
@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
2
2
  import { DatabaseSync } from "node:sqlite";
3
3
  import { DEFAULT_PERSONA_ID } from "@njuptlzf/agent-chat-protocol";
4
4
  import { assertMembershipWrite, assertProductId, summarizeHistory, quotaBlockedReason } from "./stores.js";
5
+ import { RESERVATION_TTL_MS } from "./ledger.js";
5
6
  import { auditPageWindow } from "./stores.js";
6
7
  import { GENESIS_HASH, assertNoSensitiveKeys, canonicalize, rowHash, segmentsFrom, verifyChain } from "./audit.js";
7
8
  /**
@@ -21,6 +22,10 @@ export function openDatabase(file, defaultScope = "", defaultPersona = DEFAULT_P
21
22
  const db = new DatabaseSync(file);
22
23
  db.exec(`
23
24
  PRAGMA journal_mode = WAL;
25
+ -- 跨进程并发写必设(2026-11-16 压测实锤):默认 0 时,第二个写事务拿不到锁
26
+ -- 立刻抛 SQLITE_BUSY——多副本部署下 8 个并发 reserve 有 75% 直接炸成 500。
27
+ -- WAL 下这只影响写事务之间排队(读不阻塞),reserve/settle 临界区都是毫秒级。
28
+ PRAGMA busy_timeout = 5000;
24
29
  CREATE TABLE IF NOT EXISTS history (
25
30
  user_id TEXT NOT NULL,
26
31
  scope TEXT NOT NULL DEFAULT '',
@@ -43,11 +48,30 @@ export function openDatabase(file, defaultScope = "", defaultPersona = DEFAULT_P
43
48
  tokens INTEGER NOT NULL,
44
49
  PRIMARY KEY (user_id, persona, day)
45
50
  );
51
+ -- 预留-结算账本(M-14 W3)。**这是并发额度的唯一计数口径**:
52
+ -- 今日已结算的预留 = 今日已跑的 run;未过期的 reserved = 在飞。
53
+ -- 旧模型查 runs 表 + 事后累加,并发下必然超发,故不再作为上限依据。
54
+ CREATE TABLE IF NOT EXISTS quota_reservations (
55
+ operation_id TEXT PRIMARY KEY,
56
+ user_id TEXT NOT NULL,
57
+ persona TEXT NOT NULL,
58
+ day TEXT NOT NULL,
59
+ tokens INTEGER NOT NULL DEFAULT 0,
60
+ state TEXT NOT NULL,
61
+ created_at INTEGER NOT NULL,
62
+ expires_at INTEGER NOT NULL
63
+ );
64
+ CREATE INDEX IF NOT EXISTS quota_reservations_day ON quota_reservations (user_id, persona, day, state, expires_at);
46
65
  CREATE TABLE IF NOT EXISTS runs (
47
66
  id INTEGER PRIMARY KEY AUTOINCREMENT,
48
67
  user_id TEXT NOT NULL,
49
68
  session_id TEXT NOT NULL,
50
69
  product TEXT NOT NULL,
70
+ -- 编排层(M-14 W4):单 phase 的 run 恒为 NULL;多 phase 的 run 指向父 run。
71
+ -- 老库由下方幂等 ALTER 补列,值留空(= 都是单 phase 时代的行,语义正确)。
72
+ parent_run_id TEXT,
73
+ -- Run 六态里的终态;老行按 error 有无回填(见迁移)。
74
+ state TEXT,
51
75
  started_at TEXT NOT NULL,
52
76
  duration_ms INTEGER NOT NULL,
53
77
  tool_rounds INTEGER NOT NULL,
@@ -57,6 +81,38 @@ export function openDatabase(file, defaultScope = "", defaultPersona = DEFAULT_P
57
81
  error TEXT
58
82
  );
59
83
  CREATE INDEX IF NOT EXISTS runs_user_day ON runs (user_id, started_at);
84
+ -- 编排层:一次 Run 的子会话记录(M-14 W4)。
85
+ -- 与 run_checkpoints 分工见 checkpoint-store.ts 的文件头(基数不同,不能合成一张)。
86
+ -- lease_until 让「写这条的进程还活着吗」可判定:过期即孤儿,可回收。
87
+ CREATE TABLE IF NOT EXISTS run_jobs (
88
+ run_id TEXT NOT NULL,
89
+ phase_id TEXT NOT NULL,
90
+ job_id TEXT NOT NULL,
91
+ state TEXT NOT NULL,
92
+ tokens INTEGER NOT NULL DEFAULT 0,
93
+ cost_usd REAL NOT NULL DEFAULT 0,
94
+ attempt INTEGER,
95
+ lease_until INTEGER,
96
+ updated_at INTEGER NOT NULL,
97
+ PRIMARY KEY (run_id, job_id)
98
+ );
99
+ CREATE INDEX IF NOT EXISTS run_jobs_run ON run_jobs (run_id, phase_id);
100
+ CREATE INDEX IF NOT EXISTS run_jobs_lease ON run_jobs (state, lease_until);
101
+ -- 编排层:已完成 phase 的产物(续跑数据源,I7)。usage 四列分开存,
102
+ -- 因为续跑要能按 input/output/cache 分别加总——只存 total 会把账算丢。
103
+ CREATE TABLE IF NOT EXISTS run_checkpoints (
104
+ run_id TEXT NOT NULL,
105
+ phase_id TEXT NOT NULL,
106
+ output TEXT NOT NULL,
107
+ input_tokens INTEGER NOT NULL DEFAULT 0,
108
+ output_tokens INTEGER NOT NULL DEFAULT 0,
109
+ cache_read INTEGER NOT NULL DEFAULT 0,
110
+ cache_write INTEGER NOT NULL DEFAULT 0,
111
+ total_tokens INTEGER NOT NULL DEFAULT 0,
112
+ cost_usd REAL NOT NULL DEFAULT 0,
113
+ at INTEGER NOT NULL,
114
+ PRIMARY KEY (run_id, phase_id)
115
+ );
60
116
  CREATE TABLE IF NOT EXISTS billing_balance (
61
117
  user_id TEXT PRIMARY KEY,
62
118
  balance INTEGER NOT NULL DEFAULT 0
@@ -274,6 +330,18 @@ function migrateScope(db, defaultScope, defaultPersona) {
274
330
  // 钱与权益加产品维度(membership/member_pool 重建 + 两处加列)。
275
331
  // 迁移本身是幂等的:新库走 CREATE 已是新形状,这里直接跳过。
276
332
  migrateProductDimension(db, defaultPersona);
333
+ // 编排层(M-14 W4):runs 补 parent_run_id / state 两列。
334
+ // **不重建表**:两列都不进主键、都可空,`ALTER TABLE ADD COLUMN` 就够(同 persona 那次的口径)。
335
+ // 老行 `parent_run_id` 留 NULL 是对的(那时都是单 phase,没有父 run);
336
+ // `state` 按 error 有无回填——那时只有成功/失败两种结局,回填成
337
+ // completed / failed 是**还原当时的真实语义**,不是编数据。
338
+ if (!columns("runs").includes("parent_run_id")) {
339
+ db.exec("ALTER TABLE runs ADD COLUMN parent_run_id TEXT");
340
+ }
341
+ if (!columns("runs").includes("state")) {
342
+ db.exec("ALTER TABLE runs ADD COLUMN state TEXT");
343
+ db.exec("UPDATE runs SET state = CASE WHEN error IS NULL THEN 'completed' ELSE 'failed' END WHERE state IS NULL");
344
+ }
277
345
  }
278
346
  export function migrateProductDimension(db, defaultPersona) {
279
347
  const columns = (table) => db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
@@ -392,8 +460,18 @@ export class SqliteHistoryStore {
392
460
  });
393
461
  }
394
462
  }
395
- /** Per-user token budget per day, persisted in the quota table. */
396
- export class SqliteQuotaGate {
463
+ /**
464
+ * 预留-结算账本,SQLite 实现(M-14 W3)。
465
+ *
466
+ * 并发正确性靠三件事:
467
+ * ① `BEGIN IMMEDIATE` 把「数在飞 + 插入预留」放进同一个写事务(SQLite 串行化写);
468
+ * ② **计数口径只认 `quota_reservations`**(`settled` = 今日已跑,未过期 `reserved` = 在飞)。
469
+ * 不再用「查 runs 表 + 事后累加」——那正是并发超发的来源;
470
+ * ③ `expires_at` 让崩溃留下的孤儿预留自动失效,不需要「启动时清理」这种会漏的逻辑。
471
+ *
472
+ * token 上限的能力边界见 `ledger.ts` 文件头:run 位精确,token 只能保证「到顶就不再开新 run」。
473
+ */
474
+ export class SqliteLedger {
397
475
  db;
398
476
  dailyTokens;
399
477
  now;
@@ -405,42 +483,124 @@ export class SqliteQuotaGate {
405
483
  day() {
406
484
  return this.now().toISOString().slice(0, 10);
407
485
  }
408
- async check(userId, caps, persona) {
409
- // 轮数闸先查(429 文案要区分「次数到」与「额度到」);runCap<=0 视为不限。
410
- if (caps?.runCap !== undefined && caps.runCap > 0) {
411
- const runs = this.db
412
- .prepare("SELECT COUNT(*) AS n FROM runs WHERE user_id = ? AND persona = ? AND substr(started_at, 1, 10) = ?")
413
- .get(userId, persona, this.day());
414
- if (runs.n >= caps.runCap)
415
- return {
416
- ok: false,
417
- reason: quotaBlockedReason("runs", { runCap: caps.runCap, tokenCap: caps?.tokenCap ?? this.dailyTokens }),
418
- };
419
- }
420
- const tokenCap = caps?.tokenCap ?? this.dailyTokens;
421
- if (tokenCap === undefined)
422
- return { ok: true };
486
+ /** 上限口径:今日已结算 + 未过期的在飞。 */
487
+ countForCap(userId, persona, day, nowMs) {
423
488
  const row = this.db
424
- .prepare("SELECT tokens FROM quota WHERE user_id = ? AND persona = ? AND day = ?")
425
- .get(userId, persona, this.day());
426
- return (row?.tokens ?? 0) >= tokenCap
427
- ? { ok: false, reason: quotaBlockedReason("tokens", { runCap: caps?.runCap, tokenCap }) }
428
- : { ok: true };
489
+ .prepare(`SELECT COUNT(*) AS n FROM quota_reservations
490
+ WHERE user_id = ? AND persona = ? AND day = ?
491
+ AND (state = 'settled' OR (state = 'reserved' AND expires_at > ?))`)
492
+ .get(userId, persona, day, nowMs);
493
+ return row.n;
429
494
  }
430
- async todayStats(userId, persona) {
431
- const runs = this.db
432
- .prepare("SELECT COUNT(*) AS n FROM runs WHERE user_id = ? AND persona = ? AND substr(started_at, 1, 10) = ?")
433
- .get(userId, persona, this.day());
434
- const quota = this.db
495
+ countSettled(userId, persona, day) {
496
+ const row = this.db
497
+ .prepare(`SELECT COUNT(*) AS n FROM quota_reservations
498
+ WHERE user_id = ? AND persona = ? AND day = ? AND state = 'settled'`)
499
+ .get(userId, persona, day);
500
+ return row.n;
501
+ }
502
+ tokensUsed(userId, persona, day) {
503
+ const row = this.db
435
504
  .prepare("SELECT tokens FROM quota WHERE user_id = ? AND persona = ? AND day = ?")
436
- .get(userId, persona, this.day());
437
- return { runsToday: runs.n, tokensToday: quota?.tokens ?? 0 };
505
+ .get(userId, persona, day);
506
+ return row?.tokens ?? 0;
507
+ }
508
+ async reserve(input) {
509
+ const nowMs = this.now().getTime();
510
+ const day = this.day();
511
+ this.db.exec("BEGIN IMMEDIATE");
512
+ try {
513
+ // 幂等(I6):同一 operationId 重复投递返回同一预留,不重复占位。
514
+ const existing = this.db
515
+ .prepare("SELECT state, expires_at FROM quota_reservations WHERE operation_id = ?")
516
+ .get(input.operationId);
517
+ if (existing) {
518
+ this.db.exec("COMMIT");
519
+ if (existing.state === "reserved" && existing.expires_at > nowMs) {
520
+ return { ok: true, reservation: { operationId: input.operationId, expiresAt: existing.expires_at } };
521
+ }
522
+ return { ok: false, reason: "this operation already ran (duplicate request)" };
523
+ }
524
+ const runCap = input.caps?.runCap;
525
+ if (runCap !== undefined && runCap > 0) {
526
+ if (this.countForCap(input.userId, input.persona, day, nowMs) >= runCap) {
527
+ this.db.exec("ROLLBACK");
528
+ return {
529
+ ok: false,
530
+ reason: quotaBlockedReason("runs", { runCap, tokenCap: input.caps?.tokenCap ?? this.dailyTokens }),
531
+ };
532
+ }
533
+ }
534
+ const tokenCap = input.caps?.tokenCap ?? this.dailyTokens;
535
+ if (tokenCap !== undefined) {
536
+ const used = this.tokensUsed(input.userId, input.persona, day);
537
+ // 在飞预留的 tokens 目前恒为 0(一次 run 事前不可知)。保留这个求和,
538
+ // 是为了将来有了「单次 run 的 token 上限」时能直接生效(§6.1 待办 T3)。
539
+ const reserved = this.db
540
+ .prepare(`SELECT COALESCE(SUM(tokens), 0) AS n FROM quota_reservations
541
+ WHERE user_id = ? AND persona = ? AND day = ? AND state = 'reserved' AND expires_at > ?`)
542
+ .get(input.userId, input.persona, day, nowMs);
543
+ if (used + reserved.n >= tokenCap) {
544
+ this.db.exec("ROLLBACK");
545
+ return { ok: false, reason: quotaBlockedReason("tokens", { runCap, tokenCap }) };
546
+ }
547
+ }
548
+ const expiresAt = nowMs + (input.ttlMs ?? RESERVATION_TTL_MS);
549
+ this.db
550
+ .prepare(`INSERT INTO quota_reservations (operation_id, user_id, persona, day, tokens, state, created_at, expires_at)
551
+ VALUES (?, ?, ?, ?, 0, 'reserved', ?, ?)`)
552
+ .run(input.operationId, input.userId, input.persona, day, nowMs, expiresAt);
553
+ this.db.exec("COMMIT");
554
+ return { ok: true, reservation: { operationId: input.operationId, expiresAt } };
555
+ }
556
+ catch (err) {
557
+ this.db.exec("ROLLBACK");
558
+ throw err;
559
+ }
438
560
  }
439
- async record(userId, usage, persona) {
561
+ async settle(input) {
562
+ const day = this.day();
563
+ this.db.exec("BEGIN IMMEDIATE");
564
+ try {
565
+ // 条件更新 = 幂等闸:只有 `reserved → settled` 的那一次会写 quota,
566
+ // 重复 settle 直接返回 already(不重复扣费)。
567
+ const res = this.db
568
+ .prepare(`UPDATE quota_reservations SET state = 'settled', tokens = ?
569
+ WHERE operation_id = ? AND state = 'reserved'`)
570
+ .run(input.tokens, input.operationId);
571
+ if (res.changes === 0) {
572
+ this.db.exec("COMMIT");
573
+ return "already";
574
+ }
575
+ if (input.tokens > 0) {
576
+ this.db
577
+ .prepare(`INSERT INTO quota (user_id, persona, day, tokens) VALUES (?, ?, ?, ?)
578
+ ON CONFLICT (user_id, persona, day) DO UPDATE SET tokens = tokens + excluded.tokens`)
579
+ .run(input.userId, input.persona, day, input.tokens);
580
+ }
581
+ this.db.exec("COMMIT");
582
+ return "settled";
583
+ }
584
+ catch (err) {
585
+ this.db.exec("ROLLBACK");
586
+ throw err;
587
+ }
588
+ }
589
+ async release(operationId) {
440
590
  this.db
441
- .prepare(`INSERT INTO quota (user_id, persona, day, tokens) VALUES (?, ?, ?, ?)
442
- ON CONFLICT (user_id, persona, day) DO UPDATE SET tokens = tokens + excluded.tokens`)
443
- .run(userId, persona, this.day(), usage.total);
591
+ .prepare(`UPDATE quota_reservations SET state = 'released' WHERE operation_id = ? AND state = 'reserved'`)
592
+ .run(operationId);
593
+ }
594
+ async todayStats(userId, persona) {
595
+ const day = this.day();
596
+ // 展示口径只算已结算的(在飞不算「今天跑过」)。
597
+ return { runsToday: this.countSettled(userId, persona, day), tokensToday: this.tokensUsed(userId, persona, day) };
598
+ }
599
+ async sweepExpired(now = this.now().getTime()) {
600
+ const res = this.db
601
+ .prepare(`UPDATE quota_reservations SET state = 'expired' WHERE state = 'reserved' AND expires_at <= ?`)
602
+ .run(now);
603
+ return res.changes;
444
604
  }
445
605
  }
446
606
  /** 会员有效期,SQLite 实现。 */
@@ -919,3 +1079,102 @@ export class SqliteAudit {
919
1079
  return ids.length;
920
1080
  }
921
1081
  }
1082
+ /**
1083
+ * 持久化 checkpoint 与 run_jobs(M-14 / R-010 W4)。
1084
+ *
1085
+ * 两条写入纪律,与 `SqliteLedger` 同源:
1086
+ * ① `run_checkpoints` 用 `INSERT … ON CONFLICT DO UPDATE`——续跑成功后产物要更新,
1087
+ * 但同一 `(run_id, phase_id)` 永远只有一行;
1088
+ * ② `run_jobs` 的租约回收用**条件写**(`WHERE state='running' AND lease_until<=?`),
1089
+ * 绝不先读后写:并发两个进程同时回收,条件更新让它们天然只生效一次。
1090
+ */
1091
+ export class SqliteCheckpointStore {
1092
+ db;
1093
+ now;
1094
+ constructor(db, now = () => Date.now()) {
1095
+ this.db = db;
1096
+ this.now = now;
1097
+ }
1098
+ async saveJob(runId, job) {
1099
+ const now = this.now();
1100
+ this.db
1101
+ .prepare(`INSERT INTO run_jobs (run_id, phase_id, job_id, state, tokens, cost_usd, attempt, lease_until, updated_at)
1102
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
1103
+ ON CONFLICT (run_id, job_id) DO UPDATE SET
1104
+ state = excluded.state,
1105
+ tokens = excluded.tokens,
1106
+ cost_usd = excluded.cost_usd,
1107
+ attempt = excluded.attempt,
1108
+ lease_until = excluded.lease_until,
1109
+ updated_at = excluded.updated_at`)
1110
+ .run(runId, job.phaseId, job.jobId, job.state, job.usage.total, job.usage.costUsd, job.attempt ?? null, job.leaseUntil ?? null, now);
1111
+ }
1112
+ async savePhase(checkpoint) {
1113
+ const u = checkpoint.usage;
1114
+ this.db
1115
+ .prepare(`INSERT INTO run_checkpoints (run_id, phase_id, output, input_tokens, output_tokens, cache_read, cache_write, total_tokens, cost_usd, at)
1116
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
1117
+ ON CONFLICT (run_id, phase_id) DO UPDATE SET
1118
+ output = excluded.output,
1119
+ input_tokens = excluded.input_tokens,
1120
+ output_tokens = excluded.output_tokens,
1121
+ cache_read = excluded.cache_read,
1122
+ cache_write = excluded.cache_write,
1123
+ total_tokens = excluded.total_tokens,
1124
+ cost_usd = excluded.cost_usd,
1125
+ at = excluded.at`)
1126
+ .run(checkpoint.runId, checkpoint.phaseId, checkpoint.output, u.input, u.output, u.cacheRead, u.cacheWrite, u.total, u.costUsd, checkpoint.at);
1127
+ }
1128
+ async load(runId) {
1129
+ const rows = this.db
1130
+ .prepare("SELECT * FROM run_checkpoints WHERE run_id = ?")
1131
+ .all(runId);
1132
+ if (rows.length === 0)
1133
+ return undefined;
1134
+ const phases = {};
1135
+ for (const r of rows) {
1136
+ phases[String(r.phase_id)] = {
1137
+ phaseId: String(r.phase_id),
1138
+ output: String(r.output),
1139
+ usage: {
1140
+ input: Number(r.input_tokens),
1141
+ output: Number(r.output_tokens),
1142
+ cacheRead: Number(r.cache_read),
1143
+ cacheWrite: Number(r.cache_write),
1144
+ total: Number(r.total_tokens),
1145
+ costUsd: Number(r.cost_usd),
1146
+ },
1147
+ at: Number(r.at),
1148
+ };
1149
+ }
1150
+ return { runId, phases };
1151
+ }
1152
+ async jobs(runId) {
1153
+ const rows = this.db
1154
+ .prepare("SELECT * FROM run_jobs WHERE run_id = ? ORDER BY updated_at ASC")
1155
+ .all(runId);
1156
+ return rows.map((r) => ({
1157
+ runId: String(r.run_id),
1158
+ phaseId: String(r.phase_id),
1159
+ jobId: String(r.job_id),
1160
+ state: String(r.state),
1161
+ usage: {
1162
+ input: 0,
1163
+ output: 0,
1164
+ cacheRead: 0,
1165
+ cacheWrite: 0,
1166
+ total: Number(r.tokens),
1167
+ costUsd: Number(r.cost_usd),
1168
+ },
1169
+ ...(r.attempt == null ? {} : { attempt: Number(r.attempt) }),
1170
+ ...(r.lease_until == null ? {} : { leaseUntil: Number(r.lease_until) }),
1171
+ }));
1172
+ }
1173
+ async reclaimOrphans(runId, now = this.now()) {
1174
+ // 条件写,不先读后写:两个进程同时回收也只生效一次(第二次匹配 0 行)。
1175
+ const res = this.db
1176
+ .prepare("UPDATE run_jobs SET state = 'blocked', updated_at = ? WHERE run_id = ? AND state = 'running' AND lease_until IS NOT NULL AND lease_until <= ?")
1177
+ .run(now, runId, now);
1178
+ return Number(res.changes);
1179
+ }
1180
+ }
package/dist/stores.d.ts CHANGED
@@ -50,33 +50,10 @@ export declare class MemoryHistoryStore implements HistoryStore {
50
50
  scopeOf(userId: string, sessionId: string): Promise<string | undefined>;
51
51
  list(userId: string, scope?: string): Promise<SessionSummary[]>;
52
52
  }
53
- export type QuotaDecision = {
54
- ok: true;
55
- } | {
56
- ok: false;
57
- reason: string;
58
- };
59
- /** 按角色现算的当日上限;缺省项 = 沿用装配时的全局值/不限。 */
60
53
  export interface QuotaCaps {
61
54
  runCap?: number;
62
55
  tokenCap?: number;
63
56
  }
64
- export interface QuotaGate {
65
- /**
66
- * `persona` 分账:各个人格各算各的,互不吃对方的额度。
67
- *
68
- * **必填**(通用化):core 不设隐式默认键。账本键就是人格 id,谁省略谁就写进
69
- * 另一本账——实测过,改默认值会让老数据整片读不出来。调用方一律显式传
70
- * 产品 manifest 声明的 id(默认助手用 `product.defaultPersona`)。
71
- */
72
- check(userId: string, caps: QuotaCaps | undefined, persona: string): Promise<QuotaDecision>;
73
- record(userId: string, usage: TokenUsage, persona: string): Promise<void>;
74
- /** whoami 的配额展示:今日已用轮数/token(默认助手那本账)。 */
75
- todayStats?(userId: string, persona: string): Promise<{
76
- runsToday: number;
77
- tokensToday: number;
78
- }>;
79
- }
80
57
  /** 万位读法:5000000 → 「500 万」(撞闸文案与权益卡共用,别在 UI 里二次造轮子)。 */
81
58
  export declare function fmtTokensWan(n: number): string;
82
59
  /**
@@ -85,19 +62,6 @@ export declare function fmtTokensWan(n: number): string;
85
62
  * 数字取自现算 caps,档位自适应(免费 10/会员 50、500 万),缺省项省略分句。
86
63
  */
87
64
  export declare function quotaBlockedReason(hit: "runs" | "tokens", caps: QuotaCaps): string;
88
- /** Per-user token budget per day. Replace with a database-backed gate for real billing. */
89
- export declare class DailyTokenQuota implements QuotaGate {
90
- private readonly dailyTokens;
91
- private used;
92
- constructor(dailyTokens: number | undefined);
93
- private key;
94
- check(userId: string, caps: QuotaCaps | undefined, persona: string): Promise<QuotaDecision>;
95
- todayStats(userId: string, persona: string): Promise<{
96
- runsToday: number;
97
- tokensToday: number;
98
- }>;
99
- record(userId: string, usage: TokenUsage, persona: string): Promise<void>;
100
- }
101
65
  /**
102
66
  * 会员有效期。会员是**时间态**不是余额态——「充钱是充钱,会员是
103
67
  * 订阅制有效期」。存 member_until,rolesFor 每次现算,过期自动
package/dist/stores.js CHANGED
@@ -165,33 +165,6 @@ export function quotaBlockedReason(hit, caps) {
165
165
  }
166
166
  return `今日用量已达上限${both ? `(${both})` : ""}。触顶通常来自异常使用(脚本刷量或失控会话),次日自动重置;如认为判误请联系管理员`;
167
167
  }
168
- /** Per-user token budget per day. Replace with a database-backed gate for real billing. */
169
- export class DailyTokenQuota {
170
- dailyTokens;
171
- used = new Map();
172
- constructor(dailyTokens) {
173
- this.dailyTokens = dailyTokens;
174
- }
175
- key(userId, persona) {
176
- return `${userId}\u0000${persona}\u0000${new Date().toISOString().slice(0, 10)}`;
177
- }
178
- async check(userId, caps, persona) {
179
- // 角色 token 上限优先于装配值(会员兜底更高时公平阀随之抬)。
180
- const cap = caps?.tokenCap ?? this.dailyTokens;
181
- if (cap === undefined)
182
- return { ok: true };
183
- const used = this.used.get(this.key(userId, persona)) ?? 0;
184
- return used >= cap ? { ok: false, reason: quotaBlockedReason("tokens", { runCap: caps?.runCap, tokenCap: cap }) } : { ok: true };
185
- }
186
- async todayStats(userId, persona) {
187
- // 内存实现没有 runs 表概念——轮数据在配额闸之外,报 0 轮如实(开发态展示)。
188
- return { runsToday: 0, tokensToday: this.used.get(this.key(userId, persona)) ?? 0 };
189
- }
190
- async record(userId, usage, persona) {
191
- const k = this.key(userId, persona);
192
- this.used.set(k, (this.used.get(k) ?? 0) + usage.total);
193
- }
194
- }
195
168
  /**
196
169
  * 会员有效期。会员是**时间态**不是余额态——「充钱是充钱,会员是
197
170
  * 订阅制有效期」。存 member_until,rolesFor 每次现算,过期自动
@@ -0,0 +1,60 @@
1
+ /**
2
+ * 「下一步建议」的生成层:一轮对话结束后,把最近的**文本**消息拍平交给产品
3
+ * 默认模型,产出 N 条用户可能发出的简短追问。
4
+ *
5
+ * 定位与 `persona-trial` 不同:这是 run 结束后的附属产物——不建会话、不走 SSE、
6
+ * 不接配额与计费、不写 runLog。调用方(server.ts 路由)负责按人格复核生效模式,
7
+ * 并在**任何失败**时回落 `branding.ui.followUp.static`,绝不 4xx/5xx 冒泡。
8
+ *
9
+ * 与 `@assistant-ui/react` 的接法:前端实现自定义 `SuggestionAdapter.generate`
10
+ * 直接发结构化 messages(库自带的 `createSuggestionAdapter` 会把消息拍成单个
11
+ * prompt 字符串,服务端无法按 role 分离、无法强制中文指令,裁剪也不可测)。
12
+ */
13
+ import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
14
+ import { type LoadedProduct } from "./manifest.ts";
15
+ /** 裁剪后的单条对话消息:只有文本,图片/附件/工具细节从不离开前端。 */
16
+ export interface ClippedMessage {
17
+ role: "user" | "assistant";
18
+ text: string;
19
+ }
20
+ /** 生成层的输入。`personaId` 由路由用于复核生效模式,生成层本身不用它。 */
21
+ export interface SuggestionsInput {
22
+ messages: ClippedMessage[];
23
+ count: number;
24
+ /** 生成失败时的回落内容(`branding.ui.followUp.static`)。 */
25
+ staticFallback: string[];
26
+ /** 覆盖内置生成指令(`branding.ui.followUp.systemPrompt`)。 */
27
+ systemPrompt?: string;
28
+ timeoutMs: number;
29
+ }
30
+ /** 生成层的依赖。真实现读 `deps.modelRuntime`;测试注入替身避免真花钱。 */
31
+ export interface SuggestionsEnv {
32
+ product: LoadedProduct;
33
+ modelRuntime: ModelRuntime;
34
+ }
35
+ export type SuggestionsRunner = (env: SuggestionsEnv, input: SuggestionsInput) => Promise<string[]>;
36
+ /**
37
+ * 缺省值与硬上限。前端 `followUpConfigOf` 各持一份同名缺省(两个包不共享模块,
38
+ * 单测钉住两边一致)——改这里要同步那边。
39
+ */
40
+ export declare const SUGGESTIONS_DEFAULTS: {
41
+ readonly count: 3;
42
+ readonly maxMessages: 10;
43
+ readonly timeoutMs: 8000;
44
+ readonly maxTokens: 200;
45
+ /** 单条消息文本上限(超出截断)。 */
46
+ readonly messageChars: 500;
47
+ /** 整段对话字符上限(从最新往回收)。 */
48
+ readonly totalChars: 4000;
49
+ /** 单条建议字符上限。 */
50
+ readonly suggestionChars: 80;
51
+ };
52
+ /** 模型回复 → 建议列表:按行拆、去编号前缀、去空行、截到 count 条。 */
53
+ export declare function parseSuggestions(text: string, count: number): string[];
54
+ /**
55
+ * 服务端强制的输入裁剪——前端已裁一道,这里是权威层:
56
+ * 只留 user/assistant 的非空文本、单条截断、取最近 maxMessages 条、整段不超 totalChars。
57
+ */
58
+ export declare function clipMessages(raw: unknown, maxMessages: number): ClippedMessage[];
59
+ /** 真调模型。任何失败都抛给路由(统一 catch 后回落 static)。 */
60
+ export declare function runSuggestions(env: SuggestionsEnv, input: SuggestionsInput): Promise<string[]>;