@sema-agent/server 7.145.0 → 7.146.0

package/dist/session-resident-background.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `/health.inflight` 计法表第四类 —— **会话驻留的后台 shell / monitor**。
+ *
+ * ## 病
+ * 引擎在飞数原先只数 HTTP 腿与 leader 腿。模型在会话里起的后台 shell / monitor(`run_in_background`)活过起它的那一条腿 —— 腿一收,它在这份数里是 0:
+ * 读 `/health` 判「这台引擎是否空闲」的外部判官看不见它们,只好另拼一条谓词 —— 同一个事实两个读法。
+ *
+ * ## 两个事实(本文件只产总数里的第三项 `sessionResident`)
+ * `/health.inflight`(总数,{@link inflightTotal})= 引擎此刻托管着多少活 = `http + leader + sessionResident`,可观测事实;
+ * `drainState.blockingInflight`(阻断集,{@link blockingInflightOf})= 还有没有必须等完的活 = `http + leader`,排空 / 孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判停读它。
+ * 本文件产出的 `sessionResident` **只进总数、不进阻断集**:驻留 shell 不是一条腿,等它没有意义;一只不退出的 shell(`while true`)若阻断,崩溃孤儿引擎就永生。
+ * 窗到 / 排空完成,退出边界的后台收割收掉它们,retain 行按 retain 既有语义活过受控退。
+ *
+ * ## 读法(本文件是唯一属主)
+ * 行集 = core `TaskRegistry.liveTasks(access)` 的投影:`type ∈ {background_bash, monitor}` ∧ `status === "running"` ∧ `sessionScoped` ∧ 非 retain
+ * ({@link isSessionResidentShellRow})。
+ *  · **选座 `liveTasks`,不读 `list()`**:`list()` 是显示投影,硬帽 500 行(core 注:resolution must NEVER ride the display-capped list());
+ *    进程级的在飞总数是外部判官判「引擎是否空闲」的依据,不能骑显示帽 —— 超过 500 行时 `list()` 会静默少数,方向恰是「以为空闲」。`liveTasks` 无显示帽。
+ *  · **retain 行不计**:显式 retain 的行是「交付的活服务」,按 core 契约活过引擎的受控退(退出边界对它 `retained_skipped`),
+ *    不是「引擎托管着、会随它收掉」的活 —— 报它,判官会把一个本就该活过引擎的服务读成引擎的负载。
+ *  · **只数 shell 与 monitor**:后台 agent / workflow 行属计法表的别的类,不在这一类里。
+ *  · **非会话驻留行不数**:挂在 run 腿上的后台行(`sessionScoped` 为假)随腿登记在 HTTP 腿项里,数它是第二次。
+ *
+ * ## 枚举源
+ * core 的 `canAccess` 要求访问元组带 `scope`(缺 scope 一律拒),`list` / `liveTasks` 因此只读「调用方可达行」,没有进程总数的读口(core 不立新 getter)。
+ * 进程级的数要由本仓自己枚举「本进程有哪些会话」:枚举源 = **围栏表**(`boot/execution-env.ts` 的 `SessionScopedRegistries.sessionOwners`):
+ * 每次提交经 resolve-spec 写一笔(会话 id → 属主),删会话的 E21 级联清一笔,LRU 有界。scope 轴 = {@link sessionChildrenScope}(会话属主 `?? "default"`,
+ * 删除门 / 换绑门 / 结清口 / 会话后台读面同一个取法,不另取)。
+ *
+ * ## 读到的边界(成文,不静默)
+ *  · 围栏表是 LRU(上界 4096 会话):被挤出表的会话,它的驻留行在这里不可见 —— 回到改前的读数(不是新的错),不会多数;
+ *  · 不经 resolve-spec 的内部车道(服务为自己起的 run)不写围栏表,它们起的会话驻留行同样不可见;
+ *  · 删会话的级联在 `dropSessionScoped` 之后、后台收割之前失败(会话行因此没删)时,围栏表已先清:该会话还在跑的驻留行在下一次提交重新围栏之前不可见
+ *    (同样回到改前的读数;修法是把 `dropSession` 的「清秘密」与「忘身份」拆开,属围栏表的属主,不在本读法里);
+ *  · 每次读是 O(围栏表会话数 × 注册表行数)(`liveTasks` 逐会话走一遍注册表);表的上界 4096、注册表行数小,量级是毫秒。
+ *
+ * ## 读不出 ⇒ 非空闲(响亮,不替成 0)
+ * 本函数在 `/health` 应答和崩溃遗言(uncaught 处理器里读总数)里被调,**不许抛**(崩溃遗言里一次抛会吞掉遗言本身)。判停路径(排空 / 租约 / SIGHUP)读阻断集,
+ * 不求值本函数。某个会话的 `liveTasks` 读失败 ⇒ 该会话按 **1 只在跑**计(读不出 ⇒ 非空闲:判官宁可当有活)并经 `onUnreadable` 报出 ——
+ * 调用方必须给报口(装配层一会话一行 `session_resident_background_unreadable`),不存在静默的 0。
+ */
+import { type TaskListRow, type TaskRegistry } from "@sema-agent/core";
+/** 枚举源的形:会话 id → 会话属主(`null` = 匿名)。`Map` 满足它。 */
+export type SessionOwners = Iterable<readonly [sessionId: string, owner: string | null]>;
+/** 这一类里的行判:唯一写处(计数与单测同读)。 */
+export declare function isSessionResidentShellRow(row: TaskListRow): boolean;
+/** 一个会话的驻留行读失败的报口(由调用方给出:装配层记运维行)。 */
+export type UnreadableSessionReport = (sessionId: string, err: unknown) => void;
+/**
+ * 本进程里会话驻留的、仍在跑的后台 shell / monitor 行数。`registry` 缺省 = 进程级单例;参数只供测试换桩(只用到 `liveTasks`)。
+ * `onUnreadable` 必给:读失败的会话按 1 计并经它报出(文件头「读不出 ⇒ 非空闲」)。读法与边界见文件头。
+ */
+export declare function countSessionResidentBackground(sessions: SessionOwners, opts: {
+    readonly registry?: Pick<TaskRegistry, "liveTasks">;
+    readonly onUnreadable: UnreadableSessionReport;
+}): number;
+//# sourceMappingURL=session-resident-background.d.ts.map

package/dist/session-resident-background.js

@@ -0,0 +1,20 @@
+import { defaultTaskRegistry } from "@sema-agent/core";
+import { sessionChildrenScope } from "./session-children-retire.js";
+export function isSessionResidentShellRow(row) {
+    return (row.type === "background_bash" || row.type === "monitor") && row.status === "running" && row.sessionScoped && row.retained !== true;
+}
+export function countSessionResidentBackground(sessions, opts) {
+    const registry = opts.registry ?? defaultTaskRegistry;
+    let n = 0;
+    for (const [sessionId, owner] of sessions) {
+        try {
+            n += registry.liveTasks({ owner: sessionId, sessionId, scope: sessionChildrenScope(owner) }).filter(isSessionResidentShellRow).length;
+        }
+        catch (err) {
+            n += 1;
+            opts.onUnreadable(sessionId, err);
+        }
+    }
+    return n;
+}
+//# sourceMappingURL=session-resident-background.js.map

package/dist/session-sync-kernel.d.ts

@@ -1,16 +1,3 @@
-/**
- * 2c session-sync KERNEL ([ref] A2) — the PURE half of session-sync: the §7 relation classifier, the staging-id
- * scheme, the {@link StagingHandle}/{@link ImportStagingStore} contracts and the {@link SyncConflictError} type.
- * Moved VERBATIM out of session-sync.ts (which keeps the StoreBackend-coupled ORCHESTRATION: exportSession/
- * importSession/planSync) so the three DB session adapters (local/pg/tidb) and security.ts can depend on these
- * symbols WITHOUT touching the orchestration module — session-sync.ts value-imports StoreBackend and type-imports
- * security's OwnerAwareSessionStore, so importing it from security.ts formed the repo's only true type cycle
- * (security ↔ session-sync; lens2 §B/§E). This file imports nothing from the repo but TYPES from leaves (core types, and
- * the session-face type from `session-incarnation.ts`, itself a leaf) — a leaf, same shape as session-sync-content.ts. Its one VALUE import is
- * core's `SessionError` class (the closed-set store error the three adapters already throw). session-sync.ts re-exports everything here, so existing import sites
- * keep working unchanged. The import door's anchor judge ({@link readImportAnchors}) was written here, not moved: it is pure too, and the route and the
- * tests read it from the same leaf.
- */
 import { SessionError, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionFace } from "./session-incarnation.js";
 /**
@@ -111,9 +98,60 @@ export declare function realIdOfStaging(stagingId: string): string | null;
  * 抄一份**同值常量,PG 那份的注释甚至自称「twin of the TiDB store's STAGING_GC_GRACE_MS」——明知孪生却
  * 不共享。单边改值的后果是两个后端对「同一个中断的导入还能不能收」判定分家,而两边都按自己的常量静默
  * 正确工作。这里是两个店**本就都 import** 的那个叶子模块(店契约纪律:适配器不许 import 自己的孪生,
- * 共享常量必须落在中立处),同族先例见 `checkpoint-store-sql.ts` 的 `export const TERMINAL_GRACE_MS`。
+ * 共享常量必须落在中立处),同族先例见 `checkpoint-store-face.ts` 的 `export const TERMINAL_GRACE_MS`。
  */
 export declare const STAGING_GC_GRACE_MS = 3600000;
+/**
+ * The staging-id TOKEN — minted by the CALLER of {@link ImportStagingStore.beginImportStaging} (never by the store). A SHORT random hex
+ * (8 bytes = 16 chars), NOT a full uuidv7: the staging id is `${sessionId}#stg-${token}` and session_event.session_id is VARCHAR(64) —
+ * a 36-char session id + "#stg-" (5) leaves 23 chars, so a 16-char token fits (and is collision-resistant for the few in-flight
+ * stagings of ONE session). randomBytes is unguessable (the session-sync route hands the staging id back in a URL). The two callers
+ * (session-sync Phase A and the adoption bulk import) mint it here — one format, one width argument.
+ */
+export declare function newStagingToken(): string;
+/** The batch length a {@link StagedLogFeed} lands in one `appendBatch` (one bounded txn) — in-flight memory is O(batch), not O(session).
+ *  500 mirrors the PULL stream's keyset page size. */
+export declare const STAGED_LOG_BATCH = 500;
+/**
+ * The ROW contract a staged entry must meet before it is batched — what the stores need to persist it, not a session-tree invariant
+ * (those are core's): the SQL stores' `session_event` columns `entry_id` / `parent_id` are `VARCHAR(64)` and `type` is `VARCHAR(32) NOT NULL`
+ * (`plugins/tidb-pool.ts` and `plugins/pg-session-storage.ts`, the DDL both staged appends write into; both dialects count characters, not
+ * UTF-16 units). An entry outside it used to reach the staging write and fail there as a store fault (5xx) — a client's bad data read as an
+ * infrastructure failure. The local store holds the same contract (one gate for all stores: a log that cannot sync to SQL is refused at the door).
+ */
+export declare const STAGED_ENTRY_ID_MAX_CHARS = 64;
+export declare const STAGED_ENTRY_TYPE_MAX_CHARS = 32;
+/** The fixed sentence of a {@link STAGED_ENTRY_ID_MAX_CHARS row-contract} refusal (wire: session-sync Phase B 422 `invalid_entries`, adoption import `detail`). */
+export declare const STAGED_ENTRY_ROW_SENTENCE = "malformed entry (id and parentId must be strings of 1-64 characters, type a string of 1-32 characters)";
+/** Why an entry is refused at the feed's door (closed set; one fixed sentence each — the wire text). */
+declare const MALFORMED_ENTRY_SENTENCES: {
+    /** not an object carrying a string `id` (a `null` line would otherwise surface as an unmapped TypeError) */
+    readonly missing_id: "malformed entry (missing id)";
+    /** outside the {@link STAGED_ENTRY_ID_MAX_CHARS row contract} */
+    readonly row_contract: "malformed entry (id and parentId must be strings of 1-64 characters, type a string of 1-32 characters)";
+};
+export type MalformedEntryReason = keyof typeof MALFORMED_ENTRY_SENTENCES;
+/** A pushed entry refused at the feed's door — a TRANSPORT / row-shape refusal, never a session-tree invariant: it never reaches core's gate
+ *  nor the staging. `message` is the wire's fixed sentence for `reason`. */
+export declare class MalformedImportEntryError extends Error {
+    readonly reason: MalformedEntryReason;
+    constructor(reason: MalformedEntryReason);
+}
+/**
+ * The ONE way an entry log enters a staged import (session-sync Phase B and the adoption bulk import both drive it): every entry, oldest-first,
+ * is checked at the door (object with a string `id`, then the store row contract — {@link MalformedImportEntryError}), stepped through core's streaming invariant gate (`StreamingImportValidator.step` —
+ * duplicate id / parent-before-child / structural refs ⇒ `SessionError("invalid_session")`) and batched into the staging
+ * ({@link STAGED_LOG_BATCH} per `appendBatch`); {@link StagedLogFeed.finish} lands the tail batch and runs core's end-of-stream gate
+ * (exactly one root, leaf resolvable). The invariant gate belongs to core; neither caller re-states any of its rules. Commit / abort stay
+ * with the caller (each has its own gates between the last entry and the commit). Single-use.
+ */
+export interface StagedLogFeed {
+    /** One entry: door (shape + row contract) → core's gate → batch. Resolves with the entry's id. */
+    push(entry: unknown): Promise<string>;
+    /** End of log: land the tail batch, then core's end-of-stream gate. */
+    finish(): Promise<void>;
+}
+export declare function createStagedLogFeed(handle: StagingHandle): StagedLogFeed;
 /**
  * §7 — the relationship between a SOURCE bundle's entry log and the DESTINATION's CURRENT entry log, the gate that
  * decides whether an import is a safe sync or a data-losing overwrite. Five exhaustive cases:
@@ -221,4 +259,5 @@ export declare function anchorEntryDeclared(declared: ReadonlySet<string>, ancho
  * so a `null` element is a 400 at the door, not a TypeError in a replay leg.
  */
 export declare function readImportAnchors(raw: readonly unknown[], declaredEntryIds: readonly string[]): ImportAnchorsRead;
+export {};
 //# sourceMappingURL=session-sync-kernel.d.ts.map

package/dist/session-sync-kernel.js

@@ -1,4 +1,5 @@
-import { SessionError } from "@sema-agent/core";
+import { randomBytes } from "node:crypto";
+import { SessionError, StreamingImportValidator } from "@sema-agent/core";
 export class StagedCommitOwnerChangedError extends SessionError {
     constructor(sessionId) {
         super("conflict", `session ${sessionId}: owner changed while the import streamed — the staged commit was rolled back`);
@@ -17,6 +18,74 @@ export function realIdOfStaging(stagingId) {
     return i < 0 ? null : stagingId.slice(0, i);
 }
 export const STAGING_GC_GRACE_MS = 3_600_000;
+export function newStagingToken() {
+    return randomBytes(8).toString("hex");
+}
+export const STAGED_LOG_BATCH = 500;
+export const STAGED_ENTRY_ID_MAX_CHARS = 64;
+export const STAGED_ENTRY_TYPE_MAX_CHARS = 32;
+export const STAGED_ENTRY_ROW_SENTENCE = `malformed entry (id and parentId must be strings of 1-${STAGED_ENTRY_ID_MAX_CHARS} characters, type a string of 1-${STAGED_ENTRY_TYPE_MAX_CHARS} characters)`;
+const MALFORMED_ENTRY_SENTENCES = {
+    missing_id: "malformed entry (missing id)",
+    row_contract: STAGED_ENTRY_ROW_SENTENCE,
+};
+export class MalformedImportEntryError extends Error {
+    reason;
+    constructor(reason) {
+        super(MALFORMED_ENTRY_SENTENCES[reason]);
+        this.reason = reason;
+        this.name = "MalformedImportEntryError";
+    }
+}
+function charsWithin(s, max) {
+    let n = 0;
+    for (const _ of s)
+        if (++n > max)
+            return false;
+    return n > 0;
+}
+function malformedEntryReason(entry) {
+    if (entry === null || typeof entry !== "object")
+        return "missing_id";
+    const { id, parentId, type } = entry;
+    if (typeof id !== "string")
+        return "missing_id";
+    if (!charsWithin(id, STAGED_ENTRY_ID_MAX_CHARS))
+        return "row_contract";
+    if (parentId !== undefined && parentId !== null && (typeof parentId !== "string" || !charsWithin(parentId, STAGED_ENTRY_ID_MAX_CHARS)))
+        return "row_contract";
+    if (typeof type !== "string" || !charsWithin(type, STAGED_ENTRY_TYPE_MAX_CHARS))
+        return "row_contract";
+    return undefined;
+}
+export function createStagedLogFeed(handle) {
+    const validator = new StreamingImportValidator();
+    let batch = [];
+    const flush = async () => {
+        if (batch.length === 0)
+            return;
+        const full = batch;
+        batch = [];
+        await handle.appendBatch(full);
+    };
+    return {
+        async push(entry) {
+            const refused = malformedEntryReason(entry);
+            if (refused !== undefined)
+                throw new MalformedImportEntryError(refused);
+            const e = entry;
+            validator.step(e);
+            batch.push(e);
+            if (batch.length >= STAGED_LOG_BATCH)
+                await flush();
+            return e.id;
+        },
+        async finish() {
+            await flush();
+            validator.finish();
+        },
+    };
+}
 export function classifySyncRelationship(srcEntries, dstEntries) {
     return classifySyncRelationshipByIds(srcEntries.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
 }

package/dist/session-sync.d.ts

@@ -107,9 +107,11 @@ export type FileHistoryReplayFailure = Extract<FileHistoryReplayResult, {
  * non-destructive-target law. `importHistory` refuses a target that already holds a DIFFERENT graph
  * (typed `conflict`; the identical envelope re-publishes idempotently). On that arm, when the store has
  * the purge seam, the sync's documented semantic (the destination converges to the source's state, same
- * posture as the policy/anchor replays) is applied: wipe the scope, then import once more. A store
- * WITHOUT `deleteBySession` (the local-lane core file store) surfaces the typed conflict unchanged —
- * an honest capability limit, never a silent half-state.
+ * posture as the policy/anchor replays) is applied: wipe the scope, then import once more. Every bundled
+ * store carries the verb (the SQL twins, and core's local File store from core 7.64.0), so the three backends
+ * read one rule; a store WITHOUT `deleteBySession` (an embedder's) surfaces the typed conflict unchanged —
+ * an honest capability limit, never a silent half-state. The wipe throws on a store fault (and core's stores
+ * refuse it while they run a write of the scope): the throw propagates, nothing is re-imported.
  *
  * Honest residual (recorded, not hidden): if the RE-import after the wipe fails (a blob corrupted in
  * transit past the Phase-A presence check), the destination's old graph is already gone and the target

package/dist/session-workspace.d.ts

@@ -56,6 +56,7 @@ export declare const SESSION_WORKSPACE_DISPOSITIONS: {
             readonly source: "forward";
         };
     };
+    readonly session: "strip";
     readonly remote: "forward";
     readonly eventId: "strip";
     readonly parentToolCallId: "strip";

package/dist/session-workspace.js

@@ -7,6 +7,7 @@ export const SESSION_WORKSPACE_DISPOSITIONS = {
     root: "forward",
     entered: { nested: { dir: "forward", byPath: "forward" } },
     project: { nested: { id: "forward", source: "forward" } },
+    session: "strip",
     remote: "forward",
     eventId: "strip",
     parentToolCallId: "strip",

package/dist/sighup-idle.d.ts

@@ -3,8 +3,9 @@
  *
  * SIGHUP(壳窗口关闭打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,引擎按
  * T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)且窗内
- * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——`inflight()`(bg/resume
- * legs + live streams)连续 idleGraceMs 为 0 才 shutdown,任何在飞 leg 重置窗口。真孤儿(最后一窗关掉)
+ * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——工作谓词连续 idleGraceMs
+ * 为假才 shutdown,任何工作重置窗口(谓词的在飞格读阻断集 `drainState.blockingInflight` = `http + leader`;会话驻留的后台 shell / monitor
+ * 在 `/health.inflight` 总数里、不阻断)。真孤儿(最后一窗关掉)
  * 有界自灭=T11 保留;第二个 SIGHUP 升级 escalate(既有 drain 路径,操作员硬梯子)。
  *
  * 诚实边界:idle-but-live 的 peer(两 turn 之间静默超过窗口)会碰到引擎已退→壳 dead-respawn 1-2s 自愈
@@ -12,13 +13,14 @@
  * [ref]:附着(打开着的 SSE 流)是判据的第二格 `attached` —— 只读订阅自此不进 inflight(排空不该等一个看着的壳),而一个只挂着订阅流的
  * peer 壳(cli 附着形:`GET /v1/approvals/stream` 常开)仍然是「有人在用」,靠这一格不被当成孤儿。修前这一形是订阅流被算进 inflight
  * 时顺带挡住的;拆开之后两件事各有一格,规则不变:inflight = 0 ∧ attached = 0 ∧ 活性静默满窗才关。
+ * [ref]([ref] v3 §9.4):「有没有工作」不再由本文件自己拼 —— 它读附着租约的**同一只**工作谓词(`boot/engine-lease.ts` 的 `laneWork`,
+ * 读者词 `"sighup"`),装配层经 {@link SighupIdleDeps.work} 递进来。于是附着租约的车道表在这里同样成立:交接车道(壳已把引擎交给后台)那一格
+ * 对 SIGHUP 读作「有工作」—— 终端关闭不会按另一套谓词把只剩后台 shell 在跑的引擎拆掉,寿命只归租约腿;别的车道读到的仍是附着 ∨ 在飞。
  */
 export interface SighupIdleDeps {
-    /** This replica's in-flight legs (drainState.inflight). */
-    inflight: () => number;
-    /** [ref]:打开着的 SSE 流条数(drainState.attachedStreams,附着租约同一只 getter)。> 0 ⇒ 有壳挂着,同 inflight 一样重置窗口。
-     *  缺席 ⇒ 视为 0(单测 / 嵌入形)。 */
-    attached?: () => number;
+    /** 此刻有没有工作 —— 附着租约的工作谓词(`laneWork(车道, 采样, "sighup")`:附着 > 0 ∨ 阻断集在飞 > 0,交接车道恒真)。真 ⇒ 重置窗口。
+     *  本文件不自拼判据([ref] 的附着格与在飞格都在那只谓词里)。 */
+    work: () => boolean;
     /** MONOTONIC-clock ms of the last non-probe HTTP request (drainState.lastActivityAt). Covers what inflight
      *  can't: admitted-but-not-yet-registered requests (auth/prepare/claim phases) and sub-tick short requests —
      *  and keeps an idle-but-live peer (still listing/browsing) alive. Absent ⇒ inflight-only semantics.

package/dist/sighup-idle.js

@@ -21,17 +21,16 @@ export function createSighupIdleHandler(deps) {
             return;
         }
         armedAt = now();
-        const inflight = deps.inflight();
-        const attached = deps.attached?.() ?? 0;
-        idleSince = inflight === 0 && attached === 0 ? now() : null;
-        deps.log("sighup_idle_watch_armed", { inflight, attached, idleGraceMs: deps.idleGraceMs });
+        const work = deps.work();
+        idleSince = work ? null : now();
+        deps.log("sighup_idle_watch_armed", { work, idleGraceMs: deps.idleGraceMs });
         watch = setInterval(() => {
             if (deps.isStopped()) {
                 clearInterval(watch);
                 watch = undefined;
                 return;
             }
-            if (deps.inflight() > 0 || (deps.attached?.() ?? 0) > 0) {
+            if (deps.work()) {
                 idleSince = null;
                 return;
             }

package/dist/spec-fields.d.ts

@@ -206,6 +206,22 @@ export declare function promptLeanSpecFragment(body: {
 }): {
     promptLean?: boolean;
 };
+/** 请求面能写进 `TaskSpec.compaction` 的成员(其余成员是运维轴,有意不在 wire 上)。型取自引擎本体:引擎改名 / 删这两位 ⇒ 本仓编译红。 */
+export type RequestCompaction = Pick<NonNullable<TaskSpec["compaction"]>, "clampTolerance" | "autoCompact">;
+/**
+ * `TaskSpec.compaction` 的座位片段 —— 调用方拥有的**两个成员**的唯一映射(一个事实一个座位、一只读法,不分两处各铸半个对象):
+ *  · `clampTolerance` ← 顶层 `body.compaction.clampTolerance`([ref] 的配套旋钮):`[0,1]` 闭区间的有限数才收,其余丢;
+ *  · `autoCompact` ← `settings.autoCompactEnabled`(CC 同名 settings 键,CC 只拿它闸**引擎自起**的压缩):布尔**逐字**(`false` 是「关」,有意义,不当作「没说」)。
+ *    引擎座 `autoCompact` 管引擎自起的三条道(窗阈值那一遍、prompt-too-long 恢复那一遍、任务尾摘要);调用方要的那一遍(`POST /v1/runs/:id/compact` → `TaskStream.compact()`)
+ *    归另一只座 `manualCompact`,本仓不写它 ⇒ 它取部署席 / 引擎缺省(开)—— 「只关自动」不连带关手动 `/compact`。
+ * `compaction` 里别的成员(`manualCompact` / `withinTask` / `reserveTokens` / `keepRecentTokens` / `instructions` / `attachWorkingFiles` / `staleToolResultOffload`)是运维轴,有意不开。
+ * 两成员都缺席 ⇒ **整键不写**(与改前字节同;座的缺省属主是引擎与它的部署席,本仓不复刻);只有一个成员在场 ⇒ `compaction` 里只有它。
+ * 每个成员只在**自己的入口**被判一次:`clampTolerance` 直接来自体(resume 重放不过 HTTP 400 门),在这里判;`autoCompact` 来自解析层,类型 `boolean | undefined` 就是合同 ——
+ * 它的判官只有 `task-settings.ts` 的 `autoCompactEnabledOk`(受理门与宽容解析层同问它),这里不再判第二遍。
+ */
+export declare function compactionSpecFragment(clampTolerance: unknown, autoCompact: boolean | undefined): {
+    compaction?: RequestCompaction;
+};
 /** [ref]②(core 5.14.0 `TaskSpec.toolMaterializeStrategy`):deferred 工具激活后的 schema 供给策略。
  *  与 {@link promptLeanFromBody} 同姿势的**防御性归一**——提交面的 fail-loud 400 在 HTTP 门,这里
  *  只负责 resume 重放存量 body 时把不认识的值静默 DROP(回落 core 的 env/缺省链),而不是把它带上 spec。 */

package/dist/spec-fields.js

@@ -325,6 +325,13 @@ export function promptLeanSpecFragment(body) {
     const lean = promptLeanFromBody(body.promptLean);
     return lean !== undefined ? { promptLean: lean } : {};
 }
+export function compactionSpecFragment(clampTolerance, autoCompact) {
+    const seat = {
+        ...(typeof clampTolerance === "number" && Number.isFinite(clampTolerance) && clampTolerance >= 0 && clampTolerance <= 1 ? { clampTolerance } : {}),
+        ...(autoCompact !== undefined ? { autoCompact } : {}),
+    };
+    return Object.keys(seat).length > 0 ? { compaction: seat } : {};
+}
 export function toolMaterializeStrategyFromBody(raw) {
     return raw === "static" || raw === "swap" ? raw : undefined;
 }

package/dist/stored-request-env-credentials-m38.d.ts

@@ -0,0 +1,3 @@
+/** M38 的窗在 `today`(UTC 日历日 YYYY-MM-DD)开着没有:开 ⇒ 续跑重放腿剥键照续;关 ⇒ 同一只判据拒。登记行不在 ⇒ 响亮抛(这只读者活过了它的登记行,该随那一行一起删)。 */
+export declare function storedEnvCredentialsDropM38(today: string): boolean;
+//# sourceMappingURL=stored-request-env-credentials-m38.d.ts.map

package/dist/stored-request-env-credentials-m38.js

@@ -0,0 +1,8 @@
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
+export function storedEnvCredentialsDropM38(today) {
+    const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M38");
+    if (window === undefined)
+        throw new Error("stored-request-env-credentials-m38: the one-time migration registry has no M38 row (the replay-leg settings.env credential drop window) — the drop arm outlived its registry row; delete it with that row");
+    return migrationWindowOpen(window, today);
+}
+//# sourceMappingURL=stored-request-env-credentials-m38.js.map

package/dist/stored-request-prompt-profile-m30.d.ts

@@ -23,7 +23,7 @@
  */
 import { type SealedCheckpointCtx } from "./http/checkpoint-ctx.js";
 import { type OneTimeMigrationWindow } from "./plugins/one-time-migrations.js";
-import type { CheckpointCtxRowsRewriter } from "./plugins/checkpoint-store-sql.js";
+import type { CheckpointCtxRowsRewriter } from "./plugins/checkpoint-store-face.js";
 /** M30 一次起服的读数(起服 info 行逐键打出;测试按它断言)。`window: "closed"` ⇒ 一行都没读(其余全 0)。`rowsLongFormKept` = 改写成 `promptLean: false` 的行。 */
 export interface PromptProfileRetireM30Report {
     readonly window: "open" | "closed";