@qlzt/dsh-subagent 0.2.1-alpha.3 → 0.2.1-rc.2

package/README.i18n.yaml

@@ -29,6 +29,9 @@
 /deepseek-ai-dsh-subagent/use-this-package/local-and-external-children:
   en: 013644290e74493e
   zh: 05014c3c3773edeb
+/deepseek-ai-dsh-subagent/use-this-package/child-presets:
+  en: a740e5e9bdd661d9
+  zh: 712a5458fc8b3615
 /deepseek-ai-dsh-subagent/use-this-package/messaging-interrupting-and-discovering:
   en: 050177fbbaade432
   zh: 99f2b9f98088314d
@@ -48,8 +51,11 @@
   en: f78c5e931f3a3676
   zh: 3c63f637dbaa8101
 /deepseek-ai-dsh-subagent/understand-the-implementation/activation-settlement:
-  en: 2ce43d94b6f7025b
-  zh: 970f35558aa1fab5
+  en: 3cac7a3d58cda7ea
+  zh: 74e3234e5101bd1d
+/deepseek-ai-dsh-subagent/understand-the-implementation/restoring-child-composition:
+  en: d338e68edd438f57
+  zh: 0496090cc567b19d
 /deepseek-ai-dsh-subagent/understand-the-implementation/ownership-and-invariants:
   en: b74886a091a327d4
   zh: 2124546878ba1aa2

package/README.md

@@ -60,6 +60,10 @@ At capacity, creation or cold resume rejects with `ACTIVATION_LIMIT_REACHED` (br
 
 `startActivation({ provider, label, request, signal, delivery })` returns `{ childId, messageId?, result, dispose }`. Supplying `childId` selects a local backend and guarantees `messageId`. Local children accept later messages and can cold-resume; external children expose one execution and reject continuation. `request.agentOptions` overrides supported child model settings. `delivery: 'parent'` supplies the model-facing completion notice; `delivery: 'caller'` lets workflows await the result without a parent notice or initial return guidance. Local parent delivery requires persistence; caller delivery can use an ephemeral local session. Cold resume requires persistence and Session query.
 
+### Child presets
+
+In-process spawn accepts an independent `agentPreset`; fork and external backends reject this option. Without a selection, a local child joins the parent's current preset revision. An explicit id mounts the currently available revision, even when that id matches the parent's. Configure model choices through [`dsh-tool-subagent`](../tool-subagent/README.md#selecting-a-child-preset) and persona and tools in the [preset composition](../../preset/agent-preset-registry/README.md). Cold resume preserves persona and tool restrictions recorded in historical child descriptors.
+
 ### Messaging, interrupting, and discovering
 
 Every exact live Agent can use `sendMessage()` with a direct continuable child; a resident continuable child can also use it with its direct parent. A working target receives the Agent message through Steer at its nearest step; an idle target starts a turn, and only a direct child can be cold-resumed. The parent can also interrupt a running descendant or list its children at any time. A browser continuation prompt independently selects Queue or Steer and may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Direct-child discovery reads the parent-owned `subagentCatalog` projection. `listChildren(parentSessionId, signal?)` owns a live-preferred Session observation and returns the catalog asynchronously without reading child logs. It forwards cancellation and releases the observation after materialization. Materialization preserves parent event order in O(D) time for D facts. External entries are leaves and require no child Session observation. Descendant discovery recursively reads local child catalogs in parent event order, observing each reachable Session once. It skips branches whose catalogs cannot be read and returns diagnostics for them; neither path loads or resumes a child Agent.
@@ -118,6 +122,13 @@ A local Agent failure without a subsequently committed `turn/end` settles as `er
 
 Successful local creation appends a `subagent/catalog` fact to the parent Session regardless of result delivery. External creation appends a catalog fact only with `delivery: 'parent'`; caller-owned external executions retain their caller's membership records. External entries use `mode: 'external'` to identify children without a local Session. Catalog entries record membership once at creation and carry no execution status. Complete results go to the caller or the parent completion notice. Projections exclude inherited facts. Direct lists read one parent projection, so completed local workflow children remain discoverable and can be opened or continued. Catalog payload v0 records local modes; v1 also accepts unknown mode; v2 records external executions. Readers support all three versions. Historical migration appends a v1 `subagent/catalog` from a readable child header when its descriptor is unavailable; local creation retains v0. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
 
+<a id="restoring-child-composition"></a>
+### Restoring child composition
+
+An independently selected spawn records `agent-preset/selected` before its first own `subagent/descriptor`. Cold resume excludes the inherited event prefix and checks that ordering, then reads the preset id from the existing `agentPreset` projection. It mounts that id without requiring the original subagent provider to remain registered. A missing or broken selected preset rejects restoration; it does not fall back to the parent or deployment default.
+
+Logs without that selection before the first own descriptor, including historical spawn and fork logs, retain `composeFrom` of the parent's current composition. A header preset id, an inherited selection, or a selection after the descriptor does not opt a child into independent restoration, including a fork with no inherited events. Session and descriptor formats are unchanged. Independent cold resume uses the currently registered preset definition, without preserving an earlier revision across restarts.
+
 ### Ownership and invariants
 
 - **The manager owns accepted work** — unpublished failures roll back; published handles cancel their exact activation and await child-first disposal.

package/README.zh.md

@@ -60,6 +60,10 @@ kind: "package-reference"
 
 `startActivation({ provider, label, request, signal, delivery })` 返回 `{ childId, messageId?, result, dispose }`。提供 `childId` 会选择本地后端，并保证返回 `messageId`。本地子级接受后续消息并支持冷恢复；外部子级只暴露一次执行，拒绝继续输入。`request.agentOptions` 覆盖后端支持的子级模型设置。`delivery: 'parent'` 提供面向模型的完成通知；`delivery: 'caller'` 让工作流等待结果，不发送父级通知，也不附加初始返回指导。本地父级投递需要持久化，调用方投递可以使用临时本地会话；冷恢复需要持久化与 Session 查询服务。
 
+### 子级 preset
+
+进程内 spawn 接受独立的 `agentPreset`；fork 与外部后端拒绝此选项。省略选择时，本地子级加入父方当前的 preset 代际。显式 id 挂载当前可用代际，即使该 id 与父方相同。通过 [`dsh-tool-subagent`](../tool-subagent/README.zh.md#selecting-a-child-preset) 配置模型可选项，并在 [preset 组装](../../preset/agent-preset-registry/README.zh.md)中配置 persona 与工具。冷恢复保留历史子级 descriptor 记录的 persona 和工具限制。
+
 ### 消息、中断与发现
 
 每个确切在线 Agent 都可以对直接可继续 child 使用 `sendMessage()`；驻留的可继续 child 还可以对自己的直接 parent 使用它。正在工作的目标通过 Steer 在最近 step 接收 Agent 消息；空闲目标启动轮次，且只有直接 child 可以冷恢复。parent 也可以随时中断正在运行的后代或列举自己的子级。浏览器发出的继续执行 prompt 会独立选择 Queue 或 Steer，并且可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。 直接子级发现读取 parent 自有的 `subagentCatalog` projection。`listChildren(parentSessionId, signal?)` 持有一次优先实时来源的 Session 观察，异步返回目录，不读取子级日志。它转发取消信号，并在物化后释放观察。物化以 O(D) 时间保留 D 条事实的父日志事件顺序。外部条目是叶节点，不需要观察子 Session。后代发现按父事件顺序递归读取子级目录，每个可达 Session 观察一次。无法读取目录的分支会被跳过，并返回诊断；两条路径都不加载或恢复子级 Agent。
@@ -118,6 +122,13 @@ kind: "package-reference"
 
 本地创建成功后，无论结果交付给谁，都会向父 Session 追加 `subagent/catalog` 事实。外部创建仅在使用 `delivery: 'parent'` 时追加目录事实；调用方拥有的外部执行保留调用方自己的成员记录。外部条目以 `mode: 'external'` 标记没有本地 Session 的子级。目录仅在创建时记录一次成员关系，不携带执行状态。完整结果交给调用方或父级完成通知。投影排除继承事实。直接列表读取一个父级投影，因此已完成的本地工作流子级仍可被发现、打开或继续。Catalog 载荷 v0 记录本地模式，v1 还接受未知模式，v2 记录外部执行，读取器支持三版。历史迁移在 descriptor 不可用时根据可读子 header 追加 v1 `subagent/catalog`；本地创建保留 v0。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
 
+<a id="restoring-child-composition"></a>
+### 恢复子级组装
+
+独立选择的 spawn 在首条自有 `subagent/descriptor` 之前记录 `agent-preset/selected`。冷恢复排除继承事件前缀并检查此顺序，再从已有 `agentPreset` 投影读取 preset id。恢复挂载该 id，不要求原始 subagent 提供方仍然注册。所选 preset 缺失或损坏时拒绝恢复，不回退到父方或部署默认值。
+
+首条自有 descriptor 前没有该选择的日志，包括历史 spawn 与 fork 日志，继续通过 `composeFrom` 加入父方当前组装。header 中的 preset id、继承的选择或 descriptor 之后的选择，都不会让子级采用独立恢复；没有继承事件的 fork 也遵守此规则。Session 与 descriptor 格式不变。独立冷恢复使用当前注册的 preset 定义，不跨重启保留旧代际。
+
 ### 所有权与不变式
 
 - **管理器拥有已接受工作**——未发布的失败会回滚；已发布句柄取消对应 activation，并等待子级优先释放。

package/lib/index.js

@@ -2,7 +2,7 @@ import z from "@deepseek-ai/schemastery";
 import { scopeTarget } from "@qlzt/dsh-scope";
 import { ToolArgsError, assertObjectJsonSchema, validateJsonSchemaValue } from "@qlzt/dsh-tools";
 import { canonicalClientTimeZone } from "@qlzt/dsh-util-time";
-import { Remote, RemoteError, TypertRemoteService } from "@qlzt/dsh-typert-protocol";
+import { Remote, RemoteError, TypertRemoteService, principalOf } from "@qlzt/dsh-typert-protocol";
 import { AttachmentError } from "@qlzt/dsh-attachment";
 import { z as z$1 } from "zod";
 import { HarnessError, ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain, joinAssistantStreamText } from "@qlzt/dsh-llm";
@@ -335,20 +335,17 @@ function resolveChildAgentOptions(parent, requested, childDepth) {
 * survive persistence, the seed boundary that separates inherited parent
 * history from child work, and the composition the child runs under.
 *
-* The preset is read from the parent's LIVE scope chain rather than from its
-* header, because a parent that switched preset while blank runs on the newer
-* composition and its header still names the older one. Recording it is what
-* makes a child's history reconstructable: without it a cold read of the child
-* resolves the deployment default and rebuilds turns under a tool set the
-* child never had.
+* Omitted selection uses the parent's live composition, including any switch
+* made while the parent was blank.
 * @param parent - the delegating parent agent.
 * @param childDepth - the resolved delegation depth to persist.
 * @param isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+* @param selectedPreset - independent selection, or omission to inherit the parent.
 * @returns the `meta` for `ctx.agents.create()`.
 */
-function childSessionMeta(parent, childDepth, isSeeded) {
+function childSessionMeta(parent, childDepth, isSeeded, selectedPreset) {
 	const parentHeader = parent.session.header;
-	const agentPreset = parent.ctx.get("agentPresets")?.composedPreset(parent.ctx);
+	const agentPreset = selectedPreset ?? parent.ctx.get("agentPresets")?.composedPreset(parent.ctx);
 	return {
 		...parentHeader.cwd !== void 0 ? { cwd: parentHeader.cwd } : {},
 		...agentPreset === void 0 ? {} : { agentPreset },
@@ -365,29 +362,26 @@ function childSessionMeta(parent, childDepth, isSeeded) {
 */
 const SUBAGENT_DELEGATION_CONTEXT = "You are a delegated subagent: your permission scope was fixed when you were started and cannot be widened from inside this session — operations that require approval are rejected automatically. When the task needs access beyond that scope, do not retry the denied operation; state the limitation in your reply so the delegating agent can handle it.";
 /**
-* Compose one child inside its creation window: join its parent's preset,
-* register the fixed delegation-scope statement, then apply the child's own
-* shadowing persona section and tool restriction, all owned by the child's
-* scope and therefore invisible to its parent and siblings. Creation and cold
-* resume both pass through here.
-*
-* The join comes first and the child's own registrations second, which is the
-* order the layering already implies — the nearest scope wins a name, and a
-* per-child restriction intersects with everything its chain admits — but
-* stating it here keeps the two steps from being read as independent.
-*
-* The join and the per-child registrations live in ONE call because a child
-* composed without the join is exactly the defect this function exists to
-* prevent: with every model-facing row on the agent plane, a child that joins
-* no preset sees an empty tool registry and none of its parent's prompt
-* sections. Taking the parent as a parameter is what makes that omission
-* unrepresentable at the call sites.
+* Compose a child before publication and restore historical descriptor overrides.
+* Explicit selection mounts the named preset; omission synchronously joins the
+* parent's current generation. Registrations belong to the child's scope.
 * @param childCtx - the child agent's scoped creation context.
-* @param parent - the delegating parent whose composition the child joins.
-* @param composition - the per-child persona and tool filter to install.
+* @param parent - the delegating parent used when no preset is selected.
+* @param composition - independent preset and any overrides read from a historical descriptor.
+* @returns A promise when mounting an independent preset; otherwise completes synchronously.
 */
 function applyChildComposition(childCtx, parent, composition) {
+	if (composition.agentPreset !== void 0) {
+		const presets = childCtx.get("agentPresets");
+		if (presets === void 0) throw new SubagentError("selecting a child agent preset requires the agent-presets service", "PRESET_UNAVAILABLE");
+		return presets.mount(childCtx, composition.agentPreset).then(() => {
+			applyChildOverrides(childCtx, composition);
+		});
+	}
 	childCtx.get("agentPresets")?.composeFrom(childCtx, parent.ctx);
+	applyChildOverrides(childCtx, composition);
+}
+function applyChildOverrides(childCtx, composition) {
 	childCtx.systemPrompt.context({
 		name: "subagent:delegation",
 		order: childCtx.systemPrompt.getContextOrder("SUBAGENT_DELEGATION"),
@@ -1413,9 +1407,7 @@ var SubagentManager = class {
 			label: spec.label,
 			...agentProvider !== void 0 ? { agentProvider } : {},
 			...agentModel !== void 0 ? { agentModel } : {},
-			...agentReasoningEffort !== void 0 ? { agentReasoningEffort } : {},
-			...request.persona !== void 0 ? { persona: request.persona } : {},
-			...request.toolFilter !== void 0 ? { toolFilter: request.toolFilter } : {}
+			...agentReasoningEffort !== void 0 ? { agentReasoningEffort } : {}
 		});
 		const delegatedPolicies = captureDelegatedPolicyOverrides(parent);
 		const releaseHold = this.holdOwnership(parent, childId);
@@ -1451,16 +1443,13 @@ var SubagentManager = class {
 					create: {
 						cwd,
 						seed,
-						meta: childSessionMeta(parent, childDepth, prepared.seed !== void 0),
+						meta: childSessionMeta(parent, childDepth, prepared.seed !== void 0, request.agentPreset),
 						inheritedEventCount,
 						delegatedPolicies,
 						descriptor
 					},
 					agentOptions,
-					composition: {
-						persona: request.persona,
-						toolFilter: request.toolFilter
-					},
+					composition: { agentPreset: request.agentPreset },
 					signal: spec.signal,
 					delivery: spec.delivery,
 					outputSchema: spec.request.outputSchema
@@ -1805,14 +1794,16 @@ var SubagentManager = class {
 			const { create } = inputs;
 			let structured;
 			const setup = async (childCtx, child) => {
+				if (inputs.composition.agentPreset !== void 0) await applyChildComposition(childCtx, parent, inputs.composition);
 				if (create !== void 0) {
+					if (inputs.composition.agentPreset !== void 0) child.session.append("agent-preset/selected", { agentPreset: inputs.composition.agentPreset });
 					child.session.append("subagent/descriptor", create.descriptor);
 					appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies);
 					const workingDirectory = childCtx.get("workingDirectory");
 					if (workingDirectory === void 0) throw new Error("local subagents require the working-directory service");
 					await workingDirectory.set(child, create.cwd, inputs.signal);
 				}
-				applyChildComposition(childCtx, parent, inputs.composition);
+				if (inputs.composition.agentPreset === void 0) await applyChildComposition(childCtx, parent, inputs.composition);
 				if (inputs.outputSchema !== void 0) structured = attachStructuredRuntime(childCtx, inputs.outputSchema, () => this.resident.get(childId)?.ownedChildren.size === 0 && child.inbox.nextStep.length === 0 && child.inbox.nextTurn.length === 0);
 			};
 			const handle = create === void 0 ? await this.ownerCtx.agents.resume({
@@ -2165,10 +2156,14 @@ var SubagentManager = class {
 			const source = __addDisposableResource$2(env_1, observation, false);
 			this.assertAdmitting(parent);
 			this.authorizeLineage(parent, childId, source.header.parentSession);
-			const descriptor = foldSubagentDescriptor(source.events.slice(source.inheritedEventCount));
+			const ownEvents = source.events.slice(source.inheritedEventCount);
+			const descriptor = foldSubagentDescriptor(ownEvents);
 			if (descriptor === void 0 || descriptor.mode !== "continuable") throw new SubagentError(`subagent "${childId}" has no supported continuation state and cannot be resumed; choose a different target`, "NOT_RESUMABLE");
 			let activation;
 			try {
+				const independentlySelected = hasIndependentPresetSelection(ownEvents);
+				const agentPreset = independentlySelected ? source.projections?.values.agentPreset : void 0;
+				if (independentlySelected && typeof agentPreset !== "string") throw new SubagentError(`subagent "${childId}" has no agent preset projection for restoration`, "NOT_RESUMABLE");
 				activation = await this.materialize({
 					kind: "local",
 					childId,
@@ -2180,6 +2175,7 @@ var SubagentManager = class {
 						...descriptor.agentReasoningEffort !== void 0 ? { reasoningEffort: ReasoningEffortId(descriptor.agentReasoningEffort) } : {}
 					},
 					composition: {
+						agentPreset: agentPreset ?? void 0,
 						persona: descriptor.persona,
 						toolFilter: descriptor.toolFilter
 					},
@@ -2258,6 +2254,15 @@ var SubagentManager = class {
 		return query;
 	}
 };
+/** Creation-time selection precedes the own descriptor; historical forks can select after it. */
+function hasIndependentPresetSelection(events) {
+	for (const event of events) {
+		if (event.type === "subagent/descriptor") return false;
+		if (event.type === "agent-preset/selected") return true;
+	}
+	/* v8 ignore next -- coldResume rejects logs without a supported own descriptor before this lookup. */
+	return false;
+}
 //#endregion
 //#region lib/types/list-children.js
 /**
@@ -2778,15 +2783,14 @@ function normalizeSubagentDiagnostic(result) {
 /**
 * The capability advertisement of an out-of-process backend: NONE. A child in
 * another process cannot honor parent-enforced start features
-* (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+* (`agentOptions`/`agentPreset`/`outputSchema`/`maxDepth`), so the service rejects a
 * request needing any of them before `start` runs — never accepted-then-ignored.
 */
 const NO_START_CAPABILITIES = Object.freeze({
 	agentOptions: false,
+	agentPreset: false,
 	outputSchema: false,
-	depthLimit: false,
-	toolFilter: false,
-	persona: false
+	depthLimit: false
 });
 /**
 * Assert a configured timing bound is a positive finite number (it bounds a
@@ -3187,10 +3191,12 @@ let SubagentRuntime = (() => {
 			if (clientTimeZone !== void 0 && canonicalTimeZone === void 0) throw new RemoteError("subagent/invalid-time-zone", "clientTimeZone must be UTC or a valid IANA Area/Location name", { value: clientTimeZone });
 			const parent = this.ctx.get("agents")?.get(parentSessionId);
 			if (parent === void 0) throw new RemoteError("subagent/parent-unavailable", `parent session "${parentSessionId}" is not live`, { parentSessionId });
+			const principal = principalOf(this.ctx.invocation);
 			const source = {
 				kind: "user",
 				rpcId: request.requestId,
-				...canonicalTimeZone === void 0 ? {} : { clientTimeZone: canonicalTimeZone }
+				...canonicalTimeZone === void 0 ? {} : { clientTimeZone: canonicalTimeZone },
+				...principal === void 0 ? {} : { principal }
 			};
 			try {
 				let content;
@@ -3303,6 +3309,7 @@ let SubagentRuntime = (() => {
 		}
 		/** Reject the first requested capability that the provider lacks. */
 		assertCapabilities(provider, request) {
+			if (request.agentPreset !== void 0 && (!provider.capabilities.agentPreset || provider.inheritsParentContext)) throw new SubagentError(`subagent provider "${provider.name}" does not support independent agent preset selection`, "UNSUPPORTED_CAPABILITY");
 			const needs = [
 				{
 					when: request.agentOptions !== void 0,
@@ -3315,14 +3322,6 @@ let SubagentRuntime = (() => {
 				{
 					when: request.maxDepth !== void 0,
 					cap: "depthLimit"
-				},
-				{
-					when: request.toolFilter !== void 0,
-					cap: "toolFilter"
-				},
-				{
-					when: request.persona !== void 0,
-					cap: "persona"
 				}
 			];
 			for (const { when, cap } of needs) if (when && !provider.capabilities[cap]) throw new SubagentError(`subagent provider "${provider.name}" does not support the "${cap}" capability`, "UNSUPPORTED_CAPABILITY");