@zhushanwen/subagent-core 0.5.1 → 0.6.0

package/dist/{types-Dv4QhSJ_.d.cts → types-C3fE3R9x.d.cts}

@@ -421,6 +421,14 @@ interface ExecutionRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 创建时确定不可变；undefined = async（缺省语义，旧记录零迁移）。持久化经
+     * subagent-record entry（record-entry.ts 序列化白名单，entry 唯一写点）。
+     * 消费方：U2 collectCoordinator 路由（sync→批缓冲）、U5 E1 重建投影。
+     * U2 接线点：service.createRecordForMode 从 ExecuteOptions.collect 读入 identity。
+     */
+    readonly collectMode?: "sync";
     status: ExecutionStatus;
     /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。表达「为什么关闭」。
      *  由 tryTransition(record, "closed", reason) 写入；投影层按需派生对外语义。
@@ -432,6 +440,13 @@ interface ExecutionRecord {
      * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
      */
     outcome?: ExecutionOutcome;
+    /**
+     * 离开批的终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 两出口统一落标：① 批闭合 flush 写账成功后；② E9 dispose 逐条转 async 写账后
+     * （均 appendEntry 持久化，U3/U5 写点）。undefined = 未离开批 / 旧记录零迁移。
+     * 消费方：U5 E1 重建扫描只收「collectMode=sync 且无本标记」的成员（防双重通知）。
+     */
+    batchFinalized?: boolean;
     /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
     turns: Turn[];
     /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -600,6 +615,17 @@ interface ExecuteOptions {
      * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
      */
     conversation?: boolean;
+    /**
+     * 同步收集模式（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * undefined = config collectSync.default（缺省 "async"，新 session 生效）。
+     * schema 层枚举限 "async"|"sync"；运行时宽收 string 与 engine 字段同风格
+     * （非法值 ≠ "sync" 按 async 处理）。
+     * "sync" + conversation:true 组合在 startHandler E4 校验即拒
+     * （immediate throw，不产生半启动 record）。
+     * U2 接线点：service.createRecordForMode 读入 createRecord identity.collectMode
+     * （U1 打通类型与 startHandler 透传，record 落点归 U2）。
+     */
+    collect?: string;
     /**
      * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
      * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
@@ -681,6 +707,16 @@ interface BgResponse {
      * 值语义由 U2（execution/notify-ledger.ts）兑现。
      */
     notifyContract: "ledger+at-least-once";
+    /**
+     * 同步收集登记回显段（subagent-sync-collect 设计 §3.1.1 交互样例，U1 foundation）。
+     * 仅 resolved 模式为 sync 时附带（async 响应字节零变化，G3）：mode = 生效模式；
+     * pendingSyncCount = 当前未闭合批的 sync 成员总数（含本条；跨轮派发续累不重置，
+     * 与 D2 隐式批一致）。
+     */
+    collect?: {
+        mode: "sync";
+        pendingSyncCount: number;
+    };
 }
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
 interface ListResponse {
@@ -850,6 +886,30 @@ interface SubagentRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（与 ExecutionRecord.collectMode 同源投影/重建，U1 foundation）。
+     * 缺省（存量 record）= async 投影，消费方零迁移。
+     */
+    collectMode?: "sync";
+    /**
+     * 离开批终局标记（与 ExecutionRecord.batchFinalized 同源投影/重建，U1 foundation）。
+     * 缺省 = 未离开批；U5 E1 重建扫描据此排除已离场成员。
+     */
+    batchFinalized?: boolean;
+}
+/**
+ * 同步收集（sync collect）配置节类型（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 权威默认值在 config.ts DEFAULT_COLLECT_SYNC；坏值 sanitize 回默认不炸启动（E5，
+ * 与 maxConcurrent 同判）。类型定义于 types.ts（避免 config → types 反向依赖成环），
+ * config.ts re-export。
+ */
+interface CollectSyncConfig {
+    /** start 未显式传 collect 时的缺省模式。新 session 生效（与 engine 配置时机一致）。 */
+    default: "async" | "sync";
+    /** 批通知单条目结果正文预算（字符）：超出截断并接 session_read 指针行。flush 时热读。 */
+    perItemChars: number;
+    /** 批通知结果正文总量预算（字符）：Σ 超限时统一收紧 effectivePerItem（U4 算法）。flush 时热读。 */
+    totalChars: number;
 }
 /**
  * 全局配置（~/.pi/agent/subagents/config.json）。
@@ -870,6 +930,11 @@ interface SubagentsGlobalConfig {
     engineRouting?: {
         strict: boolean;
     };
+    /**
+     * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
+     */
+    collectSync?: CollectSyncConfig;
 }
 /**
  * Record 的只读视图。store.snapshot() 返回。

package/dist/{types-Dv4QhSJ_.d.ts → types-C3fE3R9x.d.ts}

@@ -421,6 +421,14 @@ interface ExecutionRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 创建时确定不可变；undefined = async（缺省语义，旧记录零迁移）。持久化经
+     * subagent-record entry（record-entry.ts 序列化白名单，entry 唯一写点）。
+     * 消费方：U2 collectCoordinator 路由（sync→批缓冲）、U5 E1 重建投影。
+     * U2 接线点：service.createRecordForMode 从 ExecuteOptions.collect 读入 identity。
+     */
+    readonly collectMode?: "sync";
     status: ExecutionStatus;
     /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。表达「为什么关闭」。
      *  由 tryTransition(record, "closed", reason) 写入；投影层按需派生对外语义。
@@ -432,6 +440,13 @@ interface ExecutionRecord {
      * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
      */
     outcome?: ExecutionOutcome;
+    /**
+     * 离开批的终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * 两出口统一落标：① 批闭合 flush 写账成功后；② E9 dispose 逐条转 async 写账后
+     * （均 appendEntry 持久化，U3/U5 写点）。undefined = 未离开批 / 旧记录零迁移。
+     * 消费方：U5 E1 重建扫描只收「collectMode=sync 且无本标记」的成员（防双重通知）。
+     */
+    batchFinalized?: boolean;
     /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
     turns: Turn[];
     /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -600,6 +615,17 @@ interface ExecuteOptions {
      * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
      */
     conversation?: boolean;
+    /**
+     * 同步收集模式（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+     * undefined = config collectSync.default（缺省 "async"，新 session 生效）。
+     * schema 层枚举限 "async"|"sync"；运行时宽收 string 与 engine 字段同风格
+     * （非法值 ≠ "sync" 按 async 处理）。
+     * "sync" + conversation:true 组合在 startHandler E4 校验即拒
+     * （immediate throw，不产生半启动 record）。
+     * U2 接线点：service.createRecordForMode 读入 createRecord identity.collectMode
+     * （U1 打通类型与 startHandler 透传，record 落点归 U2）。
+     */
+    collect?: string;
     /**
      * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
      * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
@@ -681,6 +707,16 @@ interface BgResponse {
      * 值语义由 U2（execution/notify-ledger.ts）兑现。
      */
     notifyContract: "ledger+at-least-once";
+    /**
+     * 同步收集登记回显段（subagent-sync-collect 设计 §3.1.1 交互样例，U1 foundation）。
+     * 仅 resolved 模式为 sync 时附带（async 响应字节零变化，G3）：mode = 生效模式；
+     * pendingSyncCount = 当前未闭合批的 sync 成员总数（含本条；跨轮派发续累不重置，
+     * 与 D2 隐式批一致）。
+     */
+    collect?: {
+        mode: "sync";
+        pendingSyncCount: number;
+    };
 }
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
 interface ListResponse {
@@ -850,6 +886,30 @@ interface SubagentRecord {
         journalPath?: string;
         poolKey: string;
     };
+    /**
+     * 同步收集模式标记（与 ExecutionRecord.collectMode 同源投影/重建，U1 foundation）。
+     * 缺省（存量 record）= async 投影，消费方零迁移。
+     */
+    collectMode?: "sync";
+    /**
+     * 离开批终局标记（与 ExecutionRecord.batchFinalized 同源投影/重建，U1 foundation）。
+     * 缺省 = 未离开批；U5 E1 重建扫描据此排除已离场成员。
+     */
+    batchFinalized?: boolean;
+}
+/**
+ * 同步收集（sync collect）配置节类型（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 权威默认值在 config.ts DEFAULT_COLLECT_SYNC；坏值 sanitize 回默认不炸启动（E5，
+ * 与 maxConcurrent 同判）。类型定义于 types.ts（避免 config → types 反向依赖成环），
+ * config.ts re-export。
+ */
+interface CollectSyncConfig {
+    /** start 未显式传 collect 时的缺省模式。新 session 生效（与 engine 配置时机一致）。 */
+    default: "async" | "sync";
+    /** 批通知单条目结果正文预算（字符）：超出截断并接 session_read 指针行。flush 时热读。 */
+    perItemChars: number;
+    /** 批通知结果正文总量预算（字符）：Σ 超限时统一收紧 effectivePerItem（U4 算法）。flush 时热读。 */
+    totalChars: number;
 }
 /**
  * 全局配置（~/.pi/agent/subagents/config.json）。
@@ -870,6 +930,11 @@ interface SubagentsGlobalConfig {
     engineRouting?: {
         strict: boolean;
     };
+    /**
+     * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+     * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
+     */
+    collectSync?: CollectSyncConfig;
 }
 /**
  * Record 的只读视图。store.snapshot() 返回。