@ai-agent-forge/plugin-subagent-delegate 0.86.7 → 0.88.0

package/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.subagent-delegate",
-	"pluginVersion": "0.86.7",
+	"pluginVersion": "0.88.0",
 	"apiVersion": "1",
 	"minHostVersion": "0.84.4",
 	"platform": {

package/dist/delegate.d.ts

@@ -1,4 +1,4 @@
-import { type AgentTaskAdapter, type AgentTaskChildProfileV1, type CapabilityAPI, type DisposableRegistration, type SubagentCommunicationWiringV1 } from "@agent-forge/plugin-sdk";
+import { type AgentTaskAdapter, type AgentTaskChildProfileV1, type CapabilityAPI, type DisposableRegistration, type LoggerAPI, type SessionAPI, type SubagentCommunicationWiringV1 } from "@agent-forge/plugin-sdk";
 import { type SubagentRunnerSpawnHandleV1 } from "./runner-pool.ts";
 import { type SubagentRuntimeLimitsV1, type SubagentRuntimeStatus } from "./subagent-runtime.ts";
 export declare const capabilityManifest: {
@@ -77,18 +77,6 @@ export interface SubagentDelegateCapabilityOptions {
      */
     getTurnCorrelationId?: () => string | undefined;
 }
-/**
- * 通信面的方向开关（D-060 S4，**默认全关**）：`api.config.communication` 里逐项显式
- * `true` 才开启。开启项只决定工具注册，作用域与有界性由宿主接线与信箱硬上限保证。
- */
-export interface SubagentCommunicationConfigV1 {
-    /** 父→子：对已终态且已落盘的子会话按 sessionId 续跑（`subagent_resume`）。steer 的程序面不经此开关。 */
-    readonly resume?: true;
-    /** 子→父：有界上抛消息（`subagent_escalate`），落在父下一次工具结果，不抢占父。 */
-    readonly escalate?: true;
-    /** 子↔子：同父兄弟互发有界消息（`subagent_send`/`subagent_inbox`）。 */
-    readonly sibling?: true;
-}
 /** 结构化错误码：调用形状错误、批上限错误与未知角色分开表达，便于调用方分支。 */
 export type SubagentDelegateErrorCodesV1 = "subagent_invalid_input" | "subagent_batch_too_large" | "subagent_unknown_role"
 /** 宿主未落地或无法自证档案收窄：宁可失败，也不让"只读评审者"变成一句空话。 */
@@ -97,6 +85,10 @@ export type SubagentDelegateErrorCodesV1 = "subagent_invalid_input" | "subagent_
  | "subagent_depth_exceeded"
 /** 本会话累计创建的子代理达到每父级总量上限（提交侧执行）。 */
  | "subagent_child_quota"
+/** 会话角色与当前可见磁盘角色撞名：磁盘角色是用户资产，会话不隐式改写其含义（改用其他 id）。 */
+ | "subagent_role_conflict"
+/** 会话角色超过既有硬上限（16 个 / 菜单 ≤2000 字符，磁盘+会话合并计算）：拒绝注册并提示精简。 */
+ | "subagent_role_quota"
 /** submit 同步拒绝且无结构化 code 时的本地兜底码（与投影 reasonCode 同名）。 */
  | "subagent_submit_rejected";
 export declare class SubagentDelegateError extends Error {
@@ -129,6 +121,16 @@ export interface SubagentDelegateTaskProjectionV1 {
      * `subagent_result`），父回合不被打断；无积压时省略。
      */
     readonly escalations?: readonly string[];
+    /**
+     * 该子会话相关的兄弟消息流量摘录（D-060 裁决 14 父可见性）：from/to 命中的最新
+     * 至多 8 条，每条 text 截 256 utf-8 字节；无流量时省略。审计日志在信箱侧，drain
+     * 后摘录仍可回读（历史摘录以信箱日志滚动窗口为界）。
+     */
+    readonly siblingTraffic?: readonly {
+        from: string;
+        to: string;
+        text: string;
+    }[];
 }
 export interface SubagentDelegateResultV1 {
     readonly tasks: readonly SubagentDelegateTaskProjectionV1[];
@@ -196,6 +198,100 @@ export interface SubagentRoleCatalogResolutionV1 {
     /** 未被关联、但用户文件非法的角色文件：只在被关联时才致命，这里记录用于诊断。 */
     readonly brokenUnassociated: readonly string[];
 }
+/**
+ * 会话角色快照条目的 customType（跨插件契约，workflow 软校验按此字面量读取）：
+ * data = `{ version: 1, roles: [...] }` **全量快照**、append-only；恢复时反向扫描
+ * 最近一条可解析快照（与 goal/plan/todo/workflow 的 loadState 同构）。压缩只影响
+ * LLM 上下文投影，`getBranchEntries` 始终返回完整分支，按分支重建因此压缩安全。
+ */
+export declare const SESSION_ROLE_STATE_ENTRY: "subagent.roles.state";
+/**
+ * 快照里的单个角色：与角色文件同构的**平铺定义** + id（文件形态的 id 来自文件名，
+ * 条目里必须自带）。收窄字段平铺为 model/thinkingLevel/tools/mode/systemPromptAppend，
+ * 载入内存时仍归一化为 `SubagentDelegateRoleV1`（profile 嵌套形态）。
+ */
+export interface SubagentSessionRoleRecordV1 {
+    readonly id: string;
+    readonly description: string;
+    readonly instructions: string;
+    readonly model?: string;
+    readonly thinkingLevel?: string;
+    readonly tools?: readonly string[];
+    readonly mode?: "readonly" | "full-control";
+    readonly systemPromptAppend?: string;
+    readonly parentView?: boolean;
+}
+/** 会话角色快照条目 data 的形状（必须 JSON 可序列化）。 */
+export interface SubagentSessionRolesStateV1 {
+    readonly version: 1;
+    readonly roles: readonly SubagentSessionRoleRecordV1[];
+}
+/** `subagent_role_list`（无 id）的摘要条目：来源 + 一句话说明 + 收窄面有无。 */
+export interface SubagentRoleListEntryV1 {
+    readonly id: string;
+    readonly origin: "disk" | "session";
+    readonly description: string;
+    readonly hasProfile: boolean;
+    readonly hasParentView: boolean;
+}
+export interface SubagentRoleListResultV1 {
+    readonly roles: readonly SubagentRoleListEntryV1[];
+}
+/** `subagent_role_list({ id })` 的完整定义（含 instructions 与收窄字段，供读-改-写）。 */
+export interface SubagentRoleDefinitionViewV1 extends SubagentSessionRoleRecordV1 {
+    readonly origin: "disk" | "session";
+}
+export interface SubagentRoleViewResultV1 {
+    readonly role: SubagentRoleDefinitionViewV1;
+}
+/** `subagent_role_set` 的结果：created/updated + 合并后全部可用角色 id（排序）。 */
+export interface SubagentRoleSetResultV1 {
+    readonly id: string;
+    readonly status: "created" | "updated";
+    readonly roles: readonly string[];
+}
+/** `subagent_role_remove` 的结果：removed + 合并后全部可用角色 id（排序）。 */
+export interface SubagentRoleRemoveResultV1 {
+    readonly id: string;
+    readonly status: "removed";
+    readonly roles: readonly string[];
+}
+/** 运行期角色 → 会话快照条目（平铺收窄字段，读-改-写与角色文件同构）。 */
+export declare function toSessionRoleRecord(role: SubagentDelegateRoleV1): SubagentSessionRoleRecordV1;
+/**
+ * 恢复水合（D-081）：从 `getBranchEntries()` 反向扫描最近一条**可解析**的会话角色
+ * 快照。快照级损坏（非对象/版本不符/roles 非数组）→ warn 后继续向前找；快照合法但
+ * 个别角色非法（id 形状、字段/档案校验不过）→ 丢弃该角色并 warn、保留其余；全部
+ * 不可解析 → 空数组。损坏不阻断会话启动。
+ */
+export declare function readSessionRoles(session: Pick<SessionAPI, "getBranchEntries"> | undefined, logger?: LoggerAPI): readonly SubagentDelegateRoleV1[];
+/**
+ * 磁盘角色与会话角色的合并结果（装载期水合与注册期预算共用同一实现）。
+ *
+ * **数据与视图分离**：预算是**暴露**预算，不是数据删除——未被暴露的会话角色仍留在
+ * 会话文件里（后续任何一次 set/remove 重写全量快照都不会把它们抹掉），只是当前不进
+ * 可用集。监视语义 = 数据保留（sessionRoles）、视图收窄（roles）。
+ */
+export interface SubagentSessionRoleMergeV1 {
+    /**
+     * 快照读取到的**全部**合法会话角色（快照顺序）：含被磁盘遮蔽与超出暴露预算的项。
+     * 这是会话文件里的数据（持久化写它），不等于主代理当前可见的可用集。
+     */
+    readonly sessionRoles: ReadonlyMap<string, SubagentDelegateRoleV1>;
+    /** 可用集 = 可见磁盘角色 ∪ 通过暴露预算的会话角色（磁盘优先）——菜单/`role` 枚举只看它。 */
+    readonly roles: ReadonlyMap<string, SubagentDelegateRoleV1>;
+    /** 与可见磁盘角色撞名而被遮蔽的会话角色 id：保留在会话文件中，当前不暴露（诊断）。 */
+    readonly shadowedByDisk: readonly string[];
+    /** 超出 16 个 / 2000 字符**暴露**预算而未被暴露的会话角色 id：保留在会话文件中（诊断）。 */
+    readonly droppedForQuota: readonly string[];
+}
+/**
+ * 合并磁盘角色与会话角色（D-081）：**磁盘优先**——撞名的会话角色不暴露并 warn（磁盘
+ * 角色是用户资产），但其数据仍留在会话文件里；水合按快照顺序把会话角色收进暴露预算
+ * （≤16 个、菜单 ≤2000 字符，磁盘+会话合并计算），超出部分不暴露并 warn——历史快照
+ * 可能因上限收紧或磁盘角色增加而超限，但不阻断会话启动，也不删除数据。
+ */
+export declare function mergeSubagentRoles(diskRoles: ReadonlyMap<string, SubagentDelegateRoleV1>, sessionRoles: readonly SubagentDelegateRoleV1[], logger?: LoggerAPI): SubagentSessionRoleMergeV1;
 /**
  * 解析当前方案的角色目录（**全部来自磁盘**，无编译内定义）。装载期一次性完成，
  * 任何会让"配置了但没生效"的情况都显式失败：
@@ -255,6 +351,12 @@ export interface SubagentResultReadResultV1 {
     readonly messages?: readonly unknown[];
     /** 该子会话 escalate 上抛的有界消息（取后即清）；无积压时省略。 */
     readonly escalations?: readonly string[];
+    /** 该子会话相关的兄弟流量摘录（只读不删；D-060 裁决 14）；无流量时省略。 */
+    readonly siblingTraffic?: readonly {
+        from: string;
+        to: string;
+        text: string;
+    }[];
     /** taskId 已知但尚未结算（后台委派）：稍后再取或带 waitMs 等待。 */
     readonly knownTask?: true;
     /** 未结算任务的当前调度器状态（queued/admitted/running）。 */