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

package/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.subagent-delegate",
-	"pluginVersion": "0.87.0",
+	"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: {
@@ -85,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 {
@@ -194,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;
 /**
  * 解析当前方案的角色目录（**全部来自磁盘**，无编译内定义）。装载期一次性完成，
  * 任何会让"配置了但没生效"的情况都显式失败：