@sema-agent/settings-schema 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 1.6.0 — 2026-09-05 — `settings.json` 跨会话两键 `crossSessionInbound` / `dialogExpiry`(新模块/新导出=minor)
+
+成案:跨终端会话设计稿(design/385 §4.4/§8)把这两个 settings 键的属主定在 worker 服务侧,而键的**格式契约**
+按本包定位落这里(与 `hooks` 同姿势:本包出 zod 形,引擎出判定,宿主出装配)。此前 worker 服务的 settings 键闭集门
+不认这两个键 ⇒ 一份合法的 CC `settings.json` 带上它们会被整请求 400;本节是那条链的上游一格。
+
+**新模块 `src/cross-session.ts`(主 barrel 导出,无新 subpath ⇒ `exports` 表 21 项不变)**:
+
+- `crossSessionInbound` —— 显式闭集 `CROSS_SESSION_INBOUND_VALUES = ["accept","hold","refuse"]`,**顺序即收紧秩**
+  (accept < hold < refuse:层次解析只许沿此序收紧);UI 第四拼写 `CROSS_SESSION_INBOUND_UNSET = "default"`
+  = **未设**(不是第四种策略),未设 ⇒ mode-parity。CC describe 逐字锚:「Inbound cross-session peer messages
+  (SendMessage from your other sessions)」。
+- `dialogExpiry` —— `DIALOG_EXPIRY_VALUES = ["60s","5m","10m","never"]` + `DIALOG_EXPIRY_DEFAULT = "5m"`。
+  CC describe 明写**两个**消费面(远端停靠的审批对话框 / 停审的跨会话消息),本包只声明键形,宿主自陈消费哪一面。
+- zod 受理面 `CrossSessionInboundSetting` / `DialogExpirySetting`;片段 schema `CrossSessionSettings`
+  (两键可选 + `.passthrough()` —— 本片段**不是**整份 settings 的闭集门)。
+- 层读取器 `readCrossSessionInbound` / `readDialogExpiry` → `SettingLayerRead<T>` 三态(未设 / 显式值 / 词表外)。
+  **坏值方向 = 响亮**:词表外恒 `ok:false` 交调用方拒,与 CC 文件层的 `.catch(undefined)` 静默吞成未设有意分岔
+  (一个大小写拼错静默读成「未设」会把用户以为已关的入站车道悄悄打开)。
+
+**锁步义务(写进模块头注)**:引擎侧另有一份同词表(判定纯函数的输入域),两份必须逐字相等;等值由同时装了本包
+与引擎的消费方用一格锁步钉住——本包保持纯度不变量,不 import 引擎。
+
+红先:`test/cross-session-1.6.test.ts` 20 格,落 `src/cross-session.ts` 之前首跑红(模块不存在)。
+
 ## 1.5.0 — 2026-09-04 — 扩展命名空间 + 剥键告警截断标志(sema-server S-118 源头修;新键/新导出=minor)
 
 成案:sema-server 修 cli 用户 P1「`/model` 热加载被装饰键整拒」时在下游连打四层补丁(按 kind 放宽→按域→按键路径闭集→

package/dist/cross-session.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `settings.json` 的**跨会话两键** —— CC-parity 契约(`crossSessionInbound` / `dialogExpiry`)。
+ *
+ * 与 `hooks.ts` 同姿势:本包只出**格式契约**(纯 zod、零运行时依赖、浏览器安全),不做任何解释/判定。
+ * 判定(层次收紧、mode-parity、hold 因由)归引擎;写行、渲染、下发归各宿主。
+ *
+ * ## 两键的 CC 锚(逐字核过的语料读数,非转述)
+ *
+ * - `crossSessionInbound: enum(["accept","hold","refuse"])` —— describe:「Inbound cross-session peer
+ *   messages (SendMessage from your other sessions)」:`accept` 投递、`hold` 停在收件方的待审队列
+ *   (模型看不见、不能据此行动)、`refuse` 让本会话整体退出这条车道。**显式值恒赢**;未设 =
+ *   mode-parity(发送方与收件方的权限档位同类才自动投递,不同类停审)。
+ * - `dialogExpiry: enum(["60s","5m","10m","never"])`,缺省 `"5m"` —— describe:「Max time a
+ *   permission/user dialog forwarded to a remote client stays parked awaiting an answer, and how long a
+ *   HELD cross-session message awaits approval」。**注意它有两个消费面**:远端停靠的审批对话框,与
+ *   停审的跨会话消息;本模块只声明键形,哪个宿主消费哪一面由宿主自陈。
+ *
+ * ## `"default"` 这第四个拼写
+ *
+ * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第四种策略**:读取器
+ * (`readCrossSessionInbound` / `readDialogExpiry`)把它与 `null`/缺席一同折成 `undefined`。所以
+ * `CrossSessionInboundSetting` 的受理面是四拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有三个。
+ *
+ * ## 坏值方向 = 响亮,不静默
+ *
+ * 词表外的值一律 `ok:false`,由调用方拒(HTTP 门 400 / 文件层告警)。CC 在文件层用 `.catch(undefined)`
+ * 静默吞成未设;本栈的坏值响亮律与之有意分岔——一个 `crossSessionInbound: "Hold"`(大小写拼错)静默
+ * 读成「未设」会把用户以为已经关掉的入站车道悄悄打开,那正是保护型配置最不能有的沉默。
+ *
+ * ## 与引擎词表的锁步
+ *
+ * 引擎另有一份同词表(判定纯函数的输入域)。两份**必须逐字相等**;等值由消费方(同时装了本包与引擎
+ * 的那一侧)用一格锁步钉住 —— 任一侧加词/改序,那一格先红。本包不 import 引擎(纯度不变量)。
+ */
+import { z } from "zod";
+/** 显式三值,**顺序即收紧秩**(accept < hold < refuse):层次解析只许沿此序收紧,永不放宽。 */
+export declare const CROSS_SESSION_INBOUND_VALUES: readonly ["accept", "hold", "refuse"];
+export type CrossSessionInboundValue = (typeof CROSS_SESSION_INBOUND_VALUES)[number];
+/** 设置 UI 的「不设」拼写(见头注)——两键共用同一个字面量。 */
+export declare const CROSS_SESSION_INBOUND_UNSET: "default";
+/** 文件层受理面:三个显式值 + `"default"`(未设)。 */
+export declare const CrossSessionInboundSetting: z.ZodEnum<["accept", "hold", "refuse", "default"]>;
+export type CrossSessionInboundSettingValue = z.infer<typeof CrossSessionInboundSetting>;
+/** 四值闭集(CC 逐字)。`"never"` = 不设期限。 */
+export declare const DIALOG_EXPIRY_VALUES: readonly ["60s", "5m", "10m", "never"];
+export type DialogExpiryValue = (typeof DIALOG_EXPIRY_VALUES)[number];
+/** 未设时生效的值(CC 缺省)。 */
+export declare const DIALOG_EXPIRY_DEFAULT: DialogExpiryValue;
+/** 文件层受理面:四个值 + `"default"`(未设 ⇒ 落 {@link DIALOG_EXPIRY_DEFAULT})。 */
+export declare const DialogExpirySetting: z.ZodEnum<["60s", "5m", "10m", "never", "default"]>;
+export type DialogExpirySettingValue = z.infer<typeof DialogExpirySetting>;
+/**
+ * 整份 `settings.json` 里**本片段负责的两键**。刻意 `passthrough`:本片段不是整份 settings 的闭集门
+ * (那道门归各宿主的受理面——宿主消费哪些键、拒哪些键,是宿主的事)。它只保证:**这两个键若在场,
+ * 值必合法**。
+ */
+export declare const CrossSessionSettings: z.ZodObject<{
+    crossSessionInbound: z.ZodOptional<z.ZodEnum<["accept", "hold", "refuse", "default"]>>;
+    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    crossSessionInbound: z.ZodOptional<z.ZodEnum<["accept", "hold", "refuse", "default"]>>;
+    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    crossSessionInbound: z.ZodOptional<z.ZodEnum<["accept", "hold", "refuse", "default"]>>;
+    dialogExpiry: z.ZodOptional<z.ZodEnum<["60s", "5m", "10m", "never", "default"]>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type CrossSessionSettings = z.infer<typeof CrossSessionSettings>;
+/** 一层读数:`ok:false` = 词表外(调用方响亮拒);`ok:true` 无 `value` = 未设;有 `value` = 显式值。 */
+export type SettingLayerRead<T> = {
+    ok: true;
+    value?: T;
+} | {
+    ok: false;
+};
+/** 读一层的 `crossSessionInbound` 原始值。 */
+export declare function readCrossSessionInbound(raw: unknown): SettingLayerRead<CrossSessionInboundValue>;
+/** 读一层的 `dialogExpiry` 原始值(未设 ⇒ 由消费方落 {@link DIALOG_EXPIRY_DEFAULT},本函数不替它落)。 */
+export declare function readDialogExpiry(raw: unknown): SettingLayerRead<DialogExpiryValue>;

package/dist/cross-session.js

@@ -0,0 +1,74 @@
+/**
+ * `settings.json` 的**跨会话两键** —— CC-parity 契约(`crossSessionInbound` / `dialogExpiry`)。
+ *
+ * 与 `hooks.ts` 同姿势:本包只出**格式契约**(纯 zod、零运行时依赖、浏览器安全),不做任何解释/判定。
+ * 判定(层次收紧、mode-parity、hold 因由)归引擎;写行、渲染、下发归各宿主。
+ *
+ * ## 两键的 CC 锚(逐字核过的语料读数,非转述)
+ *
+ * - `crossSessionInbound: enum(["accept","hold","refuse"])` —— describe:「Inbound cross-session peer
+ *   messages (SendMessage from your other sessions)」:`accept` 投递、`hold` 停在收件方的待审队列
+ *   (模型看不见、不能据此行动)、`refuse` 让本会话整体退出这条车道。**显式值恒赢**;未设 =
+ *   mode-parity(发送方与收件方的权限档位同类才自动投递,不同类停审)。
+ * - `dialogExpiry: enum(["60s","5m","10m","never"])`,缺省 `"5m"` —— describe:「Max time a
+ *   permission/user dialog forwarded to a remote client stays parked awaiting an answer, and how long a
+ *   HELD cross-session message awaits approval」。**注意它有两个消费面**:远端停靠的审批对话框,与
+ *   停审的跨会话消息;本模块只声明键形,哪个宿主消费哪一面由宿主自陈。
+ *
+ * ## `"default"` 这第四个拼写
+ *
+ * 设置 UI 的选择器需要一个「不设」的可写值,CC 用字面量 `"default"`。它**不是第四种策略**:读取器
+ * (`readCrossSessionInbound` / `readDialogExpiry`)把它与 `null`/缺席一同折成 `undefined`。所以
+ * `CrossSessionInboundSetting` 的受理面是四拼写,而**值域闭集**(`CROSS_SESSION_INBOUND_VALUES`)只有三个。
+ *
+ * ## 坏值方向 = 响亮,不静默
+ *
+ * 词表外的值一律 `ok:false`,由调用方拒(HTTP 门 400 / 文件层告警)。CC 在文件层用 `.catch(undefined)`
+ * 静默吞成未设;本栈的坏值响亮律与之有意分岔——一个 `crossSessionInbound: "Hold"`(大小写拼错)静默
+ * 读成「未设」会把用户以为已经关掉的入站车道悄悄打开,那正是保护型配置最不能有的沉默。
+ *
+ * ## 与引擎词表的锁步
+ *
+ * 引擎另有一份同词表(判定纯函数的输入域)。两份**必须逐字相等**;等值由消费方(同时装了本包与引擎
+ * 的那一侧)用一格锁步钉住 —— 任一侧加词/改序,那一格先红。本包不 import 引擎(纯度不变量)。
+ */
+import { z } from "zod";
+// ── crossSessionInbound ────────────────────────────────────────────────────────────────────────────
+/** 显式三值,**顺序即收紧秩**(accept < hold < refuse):层次解析只许沿此序收紧,永不放宽。 */
+export const CROSS_SESSION_INBOUND_VALUES = ["accept", "hold", "refuse"];
+/** 设置 UI 的「不设」拼写(见头注)——两键共用同一个字面量。 */
+export const CROSS_SESSION_INBOUND_UNSET = "default";
+/** 文件层受理面:三个显式值 + `"default"`(未设)。 */
+export const CrossSessionInboundSetting = z.enum([...CROSS_SESSION_INBOUND_VALUES, CROSS_SESSION_INBOUND_UNSET]);
+// ── dialogExpiry ───────────────────────────────────────────────────────────────────────────────────
+/** 四值闭集(CC 逐字)。`"never"` = 不设期限。 */
+export const DIALOG_EXPIRY_VALUES = ["60s", "5m", "10m", "never"];
+/** 未设时生效的值(CC 缺省)。 */
+export const DIALOG_EXPIRY_DEFAULT = "5m";
+/** 文件层受理面:四个值 + `"default"`(未设 ⇒ 落 {@link DIALOG_EXPIRY_DEFAULT})。 */
+export const DialogExpirySetting = z.enum([...DIALOG_EXPIRY_VALUES, CROSS_SESSION_INBOUND_UNSET]);
+// ── settings 片段 ──────────────────────────────────────────────────────────────────────────────────
+/**
+ * 整份 `settings.json` 里**本片段负责的两键**。刻意 `passthrough`:本片段不是整份 settings 的闭集门
+ * (那道门归各宿主的受理面——宿主消费哪些键、拒哪些键,是宿主的事)。它只保证:**这两个键若在场,
+ * 值必合法**。
+ */
+export const CrossSessionSettings = z
+    .object({
+    crossSessionInbound: CrossSessionInboundSetting.optional(),
+    dialogExpiry: DialogExpirySetting.optional(),
+})
+    .passthrough();
+function readEnumLayer(raw, values) {
+    if (raw === undefined || raw === null || raw === CROSS_SESSION_INBOUND_UNSET)
+        return { ok: true };
+    return typeof raw === "string" && values.includes(raw) ? { ok: true, value: raw } : { ok: false };
+}
+/** 读一层的 `crossSessionInbound` 原始值。 */
+export function readCrossSessionInbound(raw) {
+    return readEnumLayer(raw, CROSS_SESSION_INBOUND_VALUES);
+}
+/** 读一层的 `dialogExpiry` 原始值(未设 ⇒ 由消费方落 {@link DIALOG_EXPIRY_DEFAULT},本函数不替它落)。 */
+export function readDialogExpiry(raw) {
+    return readEnumLayer(raw, DIALOG_EXPIRY_VALUES);
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./cross-domain.js";
 export * from "./remote-exec.js";
 export * from "./safety-merge-spec.js";
 export * from "./scheduler-store.js";
+export * from "./cross-session.js";
 export * from "./hooks.js";
 export * from "./fleet.js";
 export * from "./migrate.js";

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./cross-domain.js"; // pure half only (no fleet placement)
 export * from "./remote-exec.js";
 export * from "./safety-merge-spec.js"; // #14 per-category safety merge-spec (settings resolver authority)
 export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (pure: type + parse/serialize + SchedulerStore interface; fs binding in ./node)
+export * from "./cross-session.js"; // CC-parity `settings.json` cross-session keys (crossSessionInbound / dialogExpiry) — pure/browser-safe
 export * from "./hooks.js"; // CC-parity hooks contract (31-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
 export * from "./fleet.js"; // scheduling/fleet contract (drain protocol · instance discovery · dispatch policy · quota lease · usage report · quota reset event) — CONTROL-PLANE-SCHEDULING-DESIGN, pure/browser-safe
 export * from "./migrate.js"; // 0.5→0.6 migration tools (hosts grandfathering + worker.model→catalog migration PLAN — report/draft only, E1; EXPERT-REDESIGN §2-2/§3), pure/browser-safe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",