@sema-agent/server 7.108.0 → 7.110.0

package/dist/user-input-ledger.d.ts

@@ -0,0 +1,296 @@
+/**
+ * S-928 —— **「已受理、未消费」的用户输入账本**(user-input acceptance ledger)的唯一属主:行形、判据、收敛、通告、读面投影。
+ * 设计稿 = sema-internal `server/design/` 的 S-928 稿(fable 主会话 2026-10-02);本文件是那份稿在代码里的**一处成文**。
+ *
+ * ## 病
+ * `POST /v1/runs/:id/steer` 对本副本的活 run 回 **200 `delivery:"applied"`**:输入只进了 core `TaskStream` 的**进程内**队列,
+ * 本服务此前不落任何字节。「你的输入丢了」今天唯一的告知是 core 在**腿终局**铸的 `task.user_steer_undrained`(`cause:"leg_end"`)——
+ * 进程被 SIGKILL / 崩溃时那个终局席跑不到 ⇒ **零告知**:壳手里只有一张 200 回执,重启后主请求与转录里都没有它。
+ * core 7.38.0 #1233 给了词:`detail.cause` 闭集 {@link USER_STEER_UNDRAINED_CAUSES} = `leg_end` / `crashed`,`crashed` 由**服务层**在
+ * 该会话下一条 run 之前铸。本文件 = 那个服务层。
+ *
+ * ## 对象(一只账本,一类输入)
+ * 「本服务以回执向调用方承诺已交给引擎、而消费只发生在进程内存里的用户输入」。今天只有 steer 一族(`kind:"steer"`)—— 两个入口同一个引擎动词
+ * `TaskStream.steer`:`POST /v1/runs/:id/steer` 的 live 腿(200 applied)与 `POST /v1/runs/:id/interrupt` 的带 text 形(202 queued-immediate,档位 now;
+ * 设计稿把后者划在病面外,车内亲核它进的是同一只进程内队列 ⇒ 同类同修,收车档登记);
+ * follow-up 在本仓**没有**进程内受理口(`src/http/routes` 零 follow-up 入口;steer 路由不下传 `priority`,core 缺省 `next` = steer 车道)
+ * ⇒ 闭集一词,不预留第二词。子代 steer(`/v1/runs/:id/subagents/:target/steer`)与 workflow agent steer 也回 200 applied,但它们投的是
+ * **子代**的队列,core 的 `task.user_steer_undrained` 只记 run 自己的用户 steer 队列 —— 不同族,不进本账(收车档候裁)。
+ *
+ * ## 四形行(append-only;行序 = 语义序;File 孪生的盘上形 = 下面的 {@link UserInputLedgerRecord},SQL 孪生 = 一行一受理 + CAS 列,同义)
+ *  · `accepted`  —— 受理点(`routes/runs.ts` 的 live 腿,**调 `TaskStream.steer` 之前**、回 200 之前)写;写不进 ⇒ 503
+ *                   `steering.ledger_unavailable`,引擎一个字节都没收到(fail-closed:没账的 200 是空头承诺)。身份 = `acceptId`
+ *                   (每次受理一枚;同 Idempotency-Key 的重放共享 `messageId`,但各是一次受理)。`writer` = 受理进程的 `instanceId`。
+ *  · `settled`   —— 本进程对这次受理的守护**正常结束**:`leg_end`(承载它的腿在本进程收场 —— done / suspended / needs_review / failed
+ *                   一律,未消费的那一半 core 已用 `leg_end` 自己告知,本仓不重算「消费了没有」)或 `not_applied`(`TaskStream.steer`
+ *                   抛了,这次受理没有变成 200;路由随即落这一行)。
+ *  · `converged` —— 收敛器判「受理它的进程已经不在、而它从没 settle」⇒ `cause:"crashed"`(core 闭集里服务层那一臂)。
+ *  · `announced` —— 通告**落进新 run 的事件账之后**写(`taskId` = 告知它的那条**新** run;`EngineNoticeRouter.routeConfirmed` 等口的落账结果,
+ *                   codex r1-F2):落账失败 ⇒ 不写,下一条 run 再说;重启再重启不重复。唯一的重复形 = 帧已落账而这一行没写成(写失败 / 进程死在两步之间)
+ *                   —— run 事件账与本账是两只店、没有共同事务,两害取「多说一遍」,不取「声称说过」。
+ * 转移只有四条(open → settled | converged;converged → announced),两只孪生都按 CAS 守它们(File 单进程 = 内存判;SQL = `WHERE state=…`)。
+ *
+ * ## 收敛判据(一条:**受理它的进程已经不在,而它从没 settle**)
+ * 「进程不在」的证据按车道各一句({@link WriterGoneEvidence},闭集穷举)—— 与 run 店自己的两臂同构:
+ *  · `exclusive_data_root`(local / File)—— 数据根的 `LOCK` 证明本进程之前的持有者已死(`FileRunStore.reclaimOrphanedAtBoot` 的同一条论证)
+ *    ⇒ 每一行 `writer ≠ 本进程` 的 open 受理都是前世的孤儿。
+ *  · `run_store_verdict`(SQL,多副本)—— 「本进程启动前写的」**不**证明写者已死(滚动发布 / 三副本时别的副本活着)。证据 = run 店**已经落盘**的
+ *    死亡判决:承载它的 run 行被 `reapStale`(写入时按心跳判「实例丢了」)翻成 `failed` 并落款 {@link RUN_STALLED_ERROR},持有者列仍是那个写者
+ *    (codex r1-F1 / r3-F1:读到的旧心跳不算 —— 读后写者可能恢复;判决落盘之后才收,收敛与 reap 的先后不再承重)。维护 tick 里收敛排在
+ *    reapStale **之后**(同一条腿串行:本拍刚 reap 的 run 本拍就收)。
+ *    同一份证据也说得出「腿已经正常收场」(行正常翻面 / 易手 / 不在)⇒ 那条没人 settle 的受理补落 `settled{leg_end}`(判词 `leg_over`,见 {@link OpenVerdict}),
+ *    open 集因此只装活腿上的受理。
+ * 两臂都排除 `writer = 本进程` 的行(活着的进程的受理归它自己的腿 settle)。触发 = boot 一次 + 每个维护 tick 一次(local 臂在 boot 之后恒空)。
+ *
+ * ## 两张脸
+ *  · **通告**(user 受众)—— 该会话**下一条 run 的首拍**(三条腿开通告口那一拍、模型调用之前;{@link UserInputLedger.announceUndrained}):
+ *    每条**旧 run** 一帧 `task.user_steer_undrained`,`detail` 逐字合 core 契约 `{ steer, cause, taskId?, sessionId?, runId? }`:
+ *    `steer` = 那条旧 run 丢掉的**条数**(按 `messageId` 去重),`cause:"crashed"`,`taskId` = 旧 run 的句柄(core 自己的 `leg_end` 臂在本仓
+ *    腿上铸的也是它:`spec.taskId` = 本服务的 run id),`sessionId` 同会话;`runId`(引擎 per-leg 身份)**缺席** —— 死掉那条腿的引擎 run id
+ *    服务层没有记录,core 契约原句「omitted when the caller has none, never fabricated」。经既有 `route()`(白名单 / 归属 / 消毒 / 隔离四件)。
+ *  · **读面**(session)—— `GET /v1/sessions/:id` 的 additive 键 `userInputUndrained`({@link UndrainedUserInputRow}),只列 `converged`
+ *    的受理;**缺席 = 这一次读没有可报的条目**:零条(不铸 `[]`),或账本这一次读不出(F 类留痕,视图照常 200 —— codex r2-F3 部分采:
+ *    契约改说真话;不另起「不可用」态,理由见收车档)。
+ *
+ * ## 不做
+ * 不开旋钮(没有「关掉告知」的正当需求)· 不改 steer 的 200 体(回执仍是「已交付」,账本是它的影子)· 不重放丢失的输入(core 明写
+ * NOT redelivered;本账只告知,不替人决定重发)· 不存输入正文(行里只有身份与时刻)。
+ */
+import { type EngineNoticeCode, type UserSteerUndrainedCause } from "@sema-agent/core";
+import { type RunRecord } from "./plugins/store-contracts.js";
+import { type EngineNoticeRouter } from "./trace/engine-notice-wire.js";
+/** local 数据根下的子目录(File 孪生;与 `approval-ask-audit/` 同层同形)。 */
+export declare const USER_INPUT_LEDGER_DIR = "user-input-ledger";
+/** 账本收的输入族(闭集)。follow-up 结论见顶注「对象」段。 */
+export type UserInputKind = "steer";
+/** 读盘词表(`satisfies Record<…, true>` ⇒ 闭集加词而本表没跟 = 编译红;判定走 `Object.hasOwn`)。 */
+export declare const USER_INPUT_KIND_WORDS: {
+    readonly steer: true;
+};
+/** `settled` 的两种收场(闭集,见顶注)。 */
+export type SettleHow = "leg_end" | "not_applied";
+export declare const SETTLE_HOW_WORDS: {
+    readonly leg_end: true;
+    readonly not_applied: true;
+};
+/** 本服务铸的那一臂(core 删掉这个词 ⇒ `Extract` 得 `never` ⇒ 下面的常量编译红)。 */
+export type CrashedCause = Extract<UserSteerUndrainedCause, "crashed">;
+export declare const CRASHED_CAUSE: CrashedCause;
+/** 盘上 / 行上的 cause 词判:必须是 core 闭集的成员,**且**铸者是服务层(词表外 / 引擎臂 ⇒ 不是本账能写的行)。 */
+export declare function isServingLayerUndrainedCause(v: unknown): v is CrashedCause;
+/** 一次受理此刻的状态(四形行的折叠结果)。 */
+export type UserInputAcceptanceState = {
+    readonly kind: "open";
+} | {
+    readonly kind: "settled";
+    readonly how: SettleHow;
+    readonly atMs: number;
+} | {
+    readonly kind: "converged";
+    readonly cause: CrashedCause;
+    readonly atMs: number;
+};
+/** 一次受理 + 它此刻的状态(两只孪生的读口都交这个形)。 */
+export interface UserInputAcceptance {
+    readonly acceptId: string;
+    readonly input: UserInputKind;
+    /** 调用方手里那张 200 回执上的 `messageId`(带 Idempotency-Key 时重放同值)。 */
+    readonly messageId: string;
+    readonly sessionId: string;
+    /** 受理时承载它的 run(本服务的 run 句柄 = `/v1/runs/:taskId`,steer 回执上的 `taskId`)。 */
+    readonly taskId: string;
+    /** 受理进程的 `instanceId`(收敛判据的「写者」)。 */
+    readonly writer: string;
+    readonly acceptedAtMs: number;
+    readonly state: UserInputAcceptanceState;
+    /** 已在哪条 run 上告知过(只在 `converged` 之后才可能在场)。 */
+    readonly announced?: {
+        readonly atMs: number;
+        readonly taskId: string;
+    };
+}
+/** `accept` 的入参(新受理恒 open、恒未告知)。 */
+export type NewUserInputAcceptance = Omit<UserInputAcceptance, "state" | "announced">;
+/**
+ * 四形行(closed set,`kind` 判别)—— File 孪生的盘上形,也是本账语义的成文形。SQL 孪生把同一组转移落在一行的列上。
+ * 键 `at` = 这件事发生的时刻(ms epoch,写者的墙钟)。
+ */
+export type UserInputLedgerRecord = {
+    readonly kind: "accepted";
+    readonly acceptId: string;
+    readonly input: UserInputKind;
+    readonly messageId: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly writer: string;
+    readonly at: number;
+} | {
+    readonly kind: "settled";
+    readonly acceptId: string;
+    readonly how: SettleHow;
+    readonly at: number;
+} | {
+    readonly kind: "converged";
+    readonly acceptId: string;
+    readonly cause: CrashedCause;
+    readonly at: number;
+} | {
+    readonly kind: "announced";
+    readonly acceptId: string;
+    readonly taskId: string;
+    readonly at: number;
+};
+/**
+ * 四条转移的**唯一**成文实现(纯内存折叠)。File 孪生用它重放盘、也用它判运行期 CAS;Memory 孪生就是它本身。
+ * SQL 孪生不调它,但它的 `WHERE state = …` 谓词逐条对应这里的四个守卫 —— 两边同一套断言见试剂盒格(`test/helpers/user-input-ledger-kit.ts`)。
+ */
+export declare class UserInputLedgerFold {
+    private readonly byId;
+    private readonly bySession;
+    has(acceptId: string): boolean;
+    get(acceptId: string): UserInputAcceptance | undefined;
+    /** 这一行能不能落(守卫判;**不**改状态)。重放与运行期写同用 —— 不能落的行在运行期不写,在重放里被忽略。 */
+    admits(rec: UserInputLedgerRecord): boolean;
+    /** 落一行(守卫不过 ⇒ 返回 false、状态不动)。 */
+    apply(rec: UserInputLedgerRecord): boolean;
+    /** open 受理的键集分页:按 (受理时刻, acceptId) 升序,严格在 `after` 之后,至多 `limit` 条(SQL 腿同一个谓词)。 */
+    listOpen(after: OpenScanCursor | undefined, limit: number): UserInputAcceptance[];
+    /** 一个会话里收敛过的受理:按受理时刻升序,至多**最新**的 `limit` 条(SQL 腿 `ORDER BY … DESC LIMIT` 后翻转,同义)—— 读面的窗。 */
+    listCrashed(sessionId: string, limit: number): UserInputAcceptance[];
+    /** 一个会话里收敛且**未告知**的受理:按受理时刻升序,从**最旧**起至多 `limit` 条(SQL 腿 `ORDER BY … ASC LIMIT`,同义)—— 通告的待办。
+     *  与读面的窗分开([ref] gpt-6 腿 [medium]):读面窗是「最新 N 条、含已告知」,已告知的行会把窗外更旧的未告知行永远挤在外面;
+     *  待办只看未告知、告知过的让位 ⇒ 每拍至少前进一页,窗外的最终可达。 */
+    listUnannounced(sessionId: string, limit: number): UserInputAcceptance[];
+}
+/** 两只读口(`listOpen` / `listUnannounced`)、两只孪生共用的页长校验:非正整数一律抛(SQL 腿把它插进 `LIMIT`,夹值 / 静默空页都是把坏参数吞掉)。 */
+export declare function assertPageLimit(op: string, limit: number): number;
+/** 两只孪生共用的排序(受理时刻,同刻按 acceptId)—— SQL 腿的 `ORDER BY accepted_at_ms, accept_id` 与它逐字同义。 */
+export declare function sortAcceptances(list: UserInputAcceptance[]): UserInputAcceptance[];
+/** open 受理的键集分页游标:上一页末行的 (受理时刻, acceptId);下一页从严格之后开始。 */
+export interface OpenScanCursor {
+    readonly acceptedAtMs: number;
+    readonly acceptId: string;
+}
+/** 收敛扫描的页长(open = 活腿上的受理 + 等收敛的孤儿,量级是人的手速)。 */
+export declare const USER_INPUT_OPEN_SCAN_MAX = 1000;
+/** 一趟收敛至多翻多少页(预算:十万条 open 行;到顶 ⇒ 断点留下,下一趟从断点续翻、扫到底再回绕 —— codex r3-F2)。 */
+export declare const USER_INPUT_OPEN_SCAN_PAGES = 100;
+/** 一个会话的「收敛过的受理」读口上限(读面 / 通告都经它;有界 wire)。收敛行 = 崩溃丢失,量级远小于受理总数;超出时取最新的这么多条。 */
+export declare const USER_INPUT_SESSION_READ_MAX = 500;
+/**
+ * **存储孪生契约**(Memory / File / TiDB / Pg 四只实现同一组断言,试剂盒格见 `test/helpers/user-input-ledger-kit.ts`)。
+ * 转移方法返回「这一次是不是我转的」(CAS 赢者):守卫不过 ⇒ `false`、零写。`accept` 写不进 ⇒ **抛**(调用方据此回 503)。
+ */
+export interface UserInputLedgerStore {
+    accept(a: NewUserInputAcceptance): Promise<void>;
+    settle(acceptId: string, how: SettleHow, atMs: number): Promise<boolean>;
+    converge(acceptId: string, atMs: number): Promise<boolean>;
+    announce(acceptId: string, taskId: string, atMs: number): Promise<boolean>;
+    /** open 受理的一页 —— 收敛扫描的读口。键集分页:按 (受理时刻, acceptId) 升序,严格在 `after` 之后(缺席 = 从头),至多 `limit` 条
+     *  (缺席 = {@link USER_INPUT_OPEN_SCAN_MAX})。收敛逐页翻到底(codex r2-F2:固定最旧一页会让活腿占满窗口时后面的崩溃丢失永远轮不到)。 */
+    listOpen(after?: OpenScanCursor, limit?: number): Promise<UserInputAcceptance[]>;
+    /** 一个会话里**收敛过**(崩溃丢失)的受理,含已告知的(按受理时刻升序,至多最新的 {@link USER_INPUT_SESSION_READ_MAX} 条)—— **读面**的读口。
+     *  只读收敛行是刻意的:一个长会话可以有成千上万条正常收场的受理,读口若按「会话的全部受理」截断,新的丢失会被旧的正常行挤出窗外。 */
+    listCrashed(sessionId: string): Promise<UserInputAcceptance[]>;
+    /** 一个会话里收敛且**未告知**的受理,从最旧起至多 `limit` 条(按受理时刻升序)—— **通告**的待办读口([ref] gpt-6 腿 [medium]:
+     *  通告若读读面那只「最新 N 条含已告知」的窗,已告知行占窗 ⇒ 窗外更旧的未告知行永远不被说;待办只看未告知,说过的让位,窗外的最终可达)。 */
+    listUnannounced(sessionId: string, limit: number): Promise<UserInputAcceptance[]>;
+}
+/**
+ * 「受理它的进程已经不在」的证据(闭集,穷举 switch;两臂各对应 run 店的一只死亡判据,见顶注「收敛判据」)。
+ */
+export type WriterGoneEvidence = {
+    readonly kind: "exclusive_data_root";
+} | {
+    /** SQL 车道:run 店**已经落盘**的死亡判决(reapStale 的落款)—— 见 {@link judgeOpen}。 */
+    readonly kind: "run_store_verdict";
+    readonly runs: {
+        getRun(taskId: string): Promise<RunRecord | null | undefined>;
+    };
+};
+/** 受理回执(路由持有;`withdraw` 凭它撤)。 */
+export interface UserInputAcceptReceipt {
+    readonly acceptId: string;
+    readonly leg: object;
+}
+/** `GET /v1/sessions/:id` 的 `userInputUndrained[]` 行(wire 形;时刻为 ISO,与同一应答体的 `createdAt` 同形)。 */
+export interface UndrainedUserInputRow {
+    readonly messageId: string;
+    readonly kind: UserInputKind;
+    /** 丢输入的那条旧 run(steer 回执上的 `taskId`)。 */
+    readonly taskId: string;
+    readonly acceptedAt: string;
+    readonly cause: CrashedCause;
+    /** 已在哪条 run 上告知过;缺席 = 还没有下一条 run 打开过这个会话。 */
+    readonly announced?: {
+        readonly at: string;
+        readonly taskId: string;
+    };
+}
+/** 账本的活对象(单写者:本进程对账本的一切写都经它)。 */
+export interface UserInputLedger {
+    /** 受理点:落 `accepted`(fsync / 提交之后才返回)。写不进 ⇒ 抛(路由回 503,不调引擎)。`leg` = 承载它的活 `TaskStream`。 */
+    accept(input: {
+        input: UserInputKind;
+        messageId: string;
+        sessionId: string;
+        taskId: string;
+        leg: object;
+    }): Promise<UserInputAcceptReceipt>;
+    /** 引擎没收下(`TaskStream.steer` 抛)⇒ 落 `settled{not_applied}`。不抛(失败留痕,受理仍挂在腿上,腿收场时照常 settle)。 */
+    withdraw(receipt: UserInputAcceptReceipt): Promise<void>;
+    /** 腿在本进程收场 ⇒ 这条腿上的每一次受理落 `settled{leg_end}`。不抛。 */
+    settleLeg(leg: object): Promise<void>;
+    /** 收敛扫描(boot 一次 + 每个维护 tick;判据见顶注)。不抛;返回本次收敛条数。 */
+    converge(): Promise<number>;
+    /** 新 run 首拍:把本会话已收敛、未告知的受理按旧 run 分组铸通告、投出后落 `announced`。不抛。 */
+    announceUndrained(at: {
+        sessionId: string;
+        taskId: string;
+    }, router?: EngineNoticeRouter): Promise<void>;
+    /** 读面投影;`undefined` = 零条(键缺席)。读失败 ⇒ 抛(调用方按读面纪律处置)。 */
+    readSession(sessionId: string): Promise<UndrainedUserInputRow[] | undefined>;
+}
+/**
+ * 一条旧 run 的 `crashed` 通告(纯数据)。`detail` 键集 = core 契约 `{ steer, cause, taskId?, sessionId?, runId? }` 的子集(`runId` 缺席,理由见顶注)。
+ * `message` 只是 fallback 展示(core 同族句的形,只换成因);消费端按 `code` + `detail.cause` 分支。
+ */
+export declare function buildCrashedSteerNotice(input: {
+    steer: number;
+    taskId: string;
+    sessionId: string;
+}): {
+    code: EngineNoticeCode;
+    message: string;
+    detail: Record<string, unknown>;
+    sessionId: string;
+};
+/**
+ * `create*`:账本活对象。`writer` = 本进程 `instanceId`;`evidence` 由装配层按车道给(local ⇒ `exclusive_data_root`,SQL ⇒ `run_store_verdict`)。
+ * 腿 → 受理的追踪是**进程内**的(`WeakMap` 以活 `TaskStream` 为键):收场 settle 只需要本进程自己受理过的那些,崩溃时它随进程消失 —— 那正是收敛要接的那一半。
+ */
+export declare function createUserInputLedger(opts: {
+    store: UserInputLedgerStore;
+    writer: string;
+    evidence: WriterGoneEvidence;
+    now?: () => number;
+    newId: () => string;
+    scanBudget?: {
+        pageSize: number;
+        maxPages: number;
+    };
+}): UserInputLedger;
+/** boot 装配点:造活对象并跑一次 boot 收敛(协调面开始服务之前)。收敛读数交给调用方的启动日志。 */
+export declare function createUserInputLedgerAtBoot(opts: Parameters<typeof createUserInputLedger>[0]): Promise<{
+    ledger: UserInputLedger;
+    converged: number;
+}>;
+/**
+ * 装配层按**车道**给证据(闭集穷举:`StoreBackend.kind` 加一个词而这里没跟 ⇒ 编译红)。
+ *  · `local` —— 数据根 LOCK 保证单进程 ⇒ `exclusive_data_root`;
+ *  · `mysql` / `pg` —— 多副本共享一张表,「我启动之前写的」证明不了写者已死 ⇒ `run_store_verdict`(run 店已落盘的 reap 判决)。
+ */
+export declare function writerGoneEvidenceFor(backendKind: "mysql" | "pg" | "local", runs: {
+    getRun(taskId: string): Promise<RunRecord | null | undefined>;
+}): WriterGoneEvidence;
+//# sourceMappingURL=user-input-ledger.d.ts.map

package/dist/user-input-ledger.js

@@ -0,0 +1,337 @@
+import { USER_STEER_UNDRAINED_CAUSES } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { RUN_STALLED_ERROR } from "./plugins/store-contracts.js";
+import { defaultEngineNoticeRouter } from "./trace/engine-notice-wire.js";
+export const USER_INPUT_LEDGER_DIR = "user-input-ledger";
+export const USER_INPUT_KIND_WORDS = { steer: true };
+export const SETTLE_HOW_WORDS = { leg_end: true, not_applied: true };
+const UNDRAINED_CAUSE_MINTER = { leg_end: "engine", crashed: "server" };
+export const CRASHED_CAUSE = "crashed";
+export function isServingLayerUndrainedCause(v) {
+    if (typeof v !== "string" || !USER_STEER_UNDRAINED_CAUSES.includes(v))
+        return false;
+    return UNDRAINED_CAUSE_MINTER[v] === "server";
+}
+export class UserInputLedgerFold {
+    byId = new Map();
+    bySession = new Map();
+    has(acceptId) {
+        return this.byId.has(acceptId);
+    }
+    get(acceptId) {
+        return this.byId.get(acceptId);
+    }
+    admits(rec) {
+        const cur = this.byId.get(rec.acceptId);
+        switch (rec.kind) {
+            case "accepted":
+                return cur === undefined;
+            case "settled":
+            case "converged":
+                return cur !== undefined && cur.state.kind === "open";
+            case "announced":
+                return cur !== undefined && cur.state.kind === "converged" && cur.announced === undefined;
+            default: {
+                const unreachable = rec;
+                return unreachable;
+            }
+        }
+    }
+    apply(rec) {
+        if (!this.admits(rec))
+            return false;
+        switch (rec.kind) {
+            case "accepted": {
+                this.byId.set(rec.acceptId, {
+                    acceptId: rec.acceptId,
+                    input: rec.input,
+                    messageId: rec.messageId,
+                    sessionId: rec.sessionId,
+                    taskId: rec.taskId,
+                    writer: rec.writer,
+                    acceptedAtMs: rec.at,
+                    state: { kind: "open" },
+                });
+                const list = this.bySession.get(rec.sessionId);
+                if (list)
+                    list.push(rec.acceptId);
+                else
+                    this.bySession.set(rec.sessionId, [rec.acceptId]);
+                return true;
+            }
+            case "settled": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, state: { kind: "settled", how: rec.how, atMs: rec.at } });
+                return true;
+            }
+            case "converged": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, state: { kind: "converged", cause: rec.cause, atMs: rec.at } });
+                return true;
+            }
+            case "announced": {
+                const cur = this.byId.get(rec.acceptId);
+                this.byId.set(rec.acceptId, { ...cur, announced: { atMs: rec.at, taskId: rec.taskId } });
+                return true;
+            }
+            default: {
+                const unreachable = rec;
+                return unreachable;
+            }
+        }
+    }
+    listOpen(after, limit) {
+        assertPageLimit("listOpen", limit);
+        const open = sortAcceptances([...this.byId.values()].filter((a) => a.state.kind === "open"));
+        const rest = after === undefined ? open : open.filter((a) => a.acceptedAtMs > after.acceptedAtMs || (a.acceptedAtMs === after.acceptedAtMs && a.acceptId > after.acceptId));
+        return rest.slice(0, limit);
+    }
+    listCrashed(sessionId, limit) {
+        const ids = this.bySession.get(sessionId) ?? [];
+        const crashed = sortAcceptances(ids.map((id) => this.byId.get(id)).filter((a) => a.state.kind === "converged"));
+        return crashed.slice(Math.max(0, crashed.length - limit));
+    }
+    listUnannounced(sessionId, limit) {
+        assertPageLimit("listUnannounced", limit);
+        const ids = this.bySession.get(sessionId) ?? [];
+        return sortAcceptances(ids.map((id) => this.byId.get(id)).filter((a) => a.state.kind === "converged" && a.announced === undefined)).slice(0, limit);
+    }
+}
+export function assertPageLimit(op, limit) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error(`user-input ledger ${op}: limit must be a positive integer (got ${String(limit)})`);
+    return limit;
+}
+export function sortAcceptances(list) {
+    return list.sort((a, b) => a.acceptedAtMs - b.acceptedAtMs || (a.acceptId < b.acceptId ? -1 : a.acceptId > b.acceptId ? 1 : 0));
+}
+export const USER_INPUT_OPEN_SCAN_MAX = 1000;
+export const USER_INPUT_OPEN_SCAN_PAGES = 100;
+export const USER_INPUT_SESSION_READ_MAX = 500;
+const USER_STEER_UNDRAINED = "task.user_steer_undrained";
+export function buildCrashedSteerNotice(input) {
+    return {
+        code: USER_STEER_UNDRAINED,
+        message: `${input.steer} user steer(s) accepted by the server for run ${input.taskId} (steer 200 applied / interrupt 202 queued-immediate) may not have reached the model — the server process running that run ended before the run settled, and whether the run consumed them before it ended is not known (the engine reports consumption only at leg end, not per steer). They are NOT redelivered; check that run's transcript and results before re-sending any of them against a live run.`,
+        detail: { steer: input.steer, cause: CRASHED_CAUSE, taskId: input.taskId, sessionId: input.sessionId },
+        sessionId: input.sessionId,
+    };
+}
+const errText = (e) => (e instanceof Error ? e.message : String(e));
+async function judgeOpen(a, me, liveHere, evidence) {
+    if (a.writer === me)
+        return liveHere.has(a.acceptId) ? "live" : "leg_over";
+    switch (evidence.kind) {
+        case "exclusive_data_root":
+            return "crashed";
+        case "run_store_verdict": {
+            const run = await evidence.runs.getRun(a.taskId);
+            if (run && run.instanceId === a.writer) {
+                if (run.status === "running")
+                    return "live";
+                if (run.status === "failed" && run.error === RUN_STALLED_ERROR)
+                    return "crashed";
+            }
+            return "leg_over";
+        }
+        default: {
+            const unreachable = evidence;
+            return unreachable;
+        }
+    }
+}
+export function createUserInputLedger(opts) {
+    const { store, writer, evidence } = opts;
+    const now = opts.now ?? Date.now;
+    const legs = new WeakMap();
+    const liveHere = new Set();
+    const track = (leg, acceptId) => {
+        const set = legs.get(leg);
+        if (set)
+            set.add(acceptId);
+        else
+            legs.set(leg, new Set([acceptId]));
+    };
+    const pageSize = opts.scanBudget?.pageSize ?? USER_INPUT_OPEN_SCAN_MAX;
+    const maxPages = opts.scanBudget?.maxPages ?? USER_INPUT_OPEN_SCAN_PAGES;
+    let scanCursor;
+    let inFlight;
+    const convergePass = async () => {
+        let n = 0;
+        for (let page = 0; page < maxPages; page++) {
+            let open;
+            try {
+                open = await store.listOpen(scanCursor, pageSize);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=converge ${errText(e)}`);
+                return n;
+            }
+            n += await convergePage(open);
+            if (open.length < pageSize) {
+                scanCursor = undefined;
+                return n;
+            }
+            const last = open[open.length - 1];
+            scanCursor = { acceptedAtMs: last.acceptedAtMs, acceptId: last.acceptId };
+        }
+        return n;
+    };
+    const convergePage = async (open) => {
+        let n = 0;
+        for (const a of open) {
+            let verdict;
+            try {
+                verdict = await judgeOpen(a, writer, liveHere, evidence);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=judge ${errText(e)}`);
+                continue;
+            }
+            try {
+                switch (verdict) {
+                    case "crashed":
+                        if (await store.converge(a.acceptId, now()))
+                            n += 1;
+                        break;
+                    case "leg_over":
+                        await store.settle(a.acceptId, "leg_end", now());
+                        break;
+                    case "live":
+                        break;
+                    default: {
+                        const unreachable = verdict;
+                        return unreachable;
+                    }
+                }
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.append-failed", `op=converge ${errText(e)}`);
+            }
+        }
+        return n;
+    };
+    return {
+        async accept(input) {
+            const acceptId = opts.newId();
+            liveHere.add(acceptId);
+            try {
+                await store.accept({ acceptId, input: input.input, messageId: input.messageId, sessionId: input.sessionId, taskId: input.taskId, writer, acceptedAtMs: now() });
+            }
+            catch (e) {
+                liveHere.delete(acceptId);
+                throw e;
+            }
+            track(input.leg, acceptId);
+            return { acceptId, leg: input.leg };
+        },
+        async withdraw(receipt) {
+            legs.get(receipt.leg)?.delete(receipt.acceptId);
+            try {
+                await store.settle(receipt.acceptId, "not_applied", now());
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.append-failed", `op=withdraw ${errText(e)}`);
+            }
+            finally {
+                liveHere.delete(receipt.acceptId);
+            }
+        },
+        async settleLeg(leg) {
+            const ids = legs.get(leg);
+            if (!ids)
+                return;
+            legs.delete(leg);
+            for (const acceptId of ids) {
+                try {
+                    await store.settle(acceptId, "leg_end", now());
+                }
+                catch (e) {
+                    recordFailOpen("server.user-input-ledger.append-failed", `op=settle ${errText(e)}`);
+                }
+                finally {
+                    liveHere.delete(acceptId);
+                }
+            }
+        },
+        converge() {
+            inFlight ??= convergePass().finally(() => {
+                inFlight = undefined;
+            });
+            return inFlight;
+        },
+        async announceUndrained(at, router = defaultEngineNoticeRouter) {
+            let rows;
+            try {
+                rows = await store.listUnannounced(at.sessionId, USER_INPUT_SESSION_READ_MAX);
+            }
+            catch (e) {
+                recordFailOpen("server.user-input-ledger.read-failed", `op=announce ${errText(e)}`);
+                return;
+            }
+            const groups = new Map();
+            for (const a of rows) {
+                const g = groups.get(a.taskId);
+                if (g)
+                    g.push(a);
+                else
+                    groups.set(a.taskId, [a]);
+            }
+            for (const [oldTaskId, group] of groups) {
+                const steer = new Set(group.map((a) => a.messageId)).size;
+                const delivered = await router.routeConfirmed(buildCrashedSteerNotice({ steer, taskId: oldTaskId, sessionId: at.sessionId }));
+                if (delivered === 0)
+                    continue;
+                for (const a of group) {
+                    try {
+                        await store.announce(a.acceptId, at.taskId, now());
+                    }
+                    catch (e) {
+                        recordFailOpen("server.user-input-ledger.append-failed", `op=announce ${errText(e)}`);
+                    }
+                }
+            }
+        },
+        async readSession(sessionId) {
+            const rows = await store.listCrashed(sessionId);
+            const seen = new Set();
+            const out = [];
+            for (const a of rows) {
+                if (a.state.kind !== "converged")
+                    continue;
+                const key = `${a.taskId}\u0000${a.messageId}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push({
+                    messageId: a.messageId,
+                    kind: a.input,
+                    taskId: a.taskId,
+                    acceptedAt: new Date(a.acceptedAtMs).toISOString(),
+                    cause: a.state.cause,
+                    ...(a.announced !== undefined ? { announced: { at: new Date(a.announced.atMs).toISOString(), taskId: a.announced.taskId } } : {}),
+                });
+            }
+            return out.length > 0 ? out : undefined;
+        },
+    };
+}
+export async function createUserInputLedgerAtBoot(opts) {
+    const ledger = createUserInputLedger(opts);
+    const converged = await ledger.converge();
+    return { ledger, converged };
+}
+export function writerGoneEvidenceFor(backendKind, runs) {
+    switch (backendKind) {
+        case "local":
+            return { kind: "exclusive_data_root" };
+        case "mysql":
+        case "pg":
+            return { kind: "run_store_verdict", runs };
+        default: {
+            const unreachable = backendKind;
+            return unreachable;
+        }
+    }
+}
+//# sourceMappingURL=user-input-ledger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.108.0",
+  "version": "7.110.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -61,8 +61,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.36.0",
-    "@sema-agent/settings-schema": "6.3.0",
+    "@sema-agent/core": "7.38.0",
+    "@sema-agent/settings-schema": "6.4.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",
@@ -77,7 +77,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "13.1.0",
+    "@sema-agent/sdk": "15.1.1",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",