delivery: 'caller' is not persisted, so a cold-resumed child reverts to parent delivery

[prgrmrwy]

Version: @deepseek-ai/dsh-subagent 0.2.1-alpha.2 (introduced in the activation refactor, 3d852a1cea / 390fbe8852)

Observation

SubagentActivationSpec.delivery: 'caller' suppresses the parent settlement notice (manager.ts, notifySettlement: if (!activation.announced || activation.delivery === 'caller') return). The choice is only held on the in-memory Activation, though:

• the continuable descriptor records provider / label / agentProvider / agentModel / agentReasoningEffort / persona / toolFilter, but not delivery;
• coldResume calls materialize without delivery, which then defaults to inputs.delivery ?? 'parent'.

A local continuable child naturally settles (and is released) whenever it goes idle with an empty inbox and no owned children. So for a long-lived child, caller covers only the first residency. Every later turn, whether after a follow-up or a Host restart, settles with a notice to the parent.

Upstream scenario

The README says completed local workflow children "remain discoverable and can be opened or continued". If a user continues such a child from the browser, the prompt goes prompt → deliverToChild → coldResume and the activation becomes 'parent'. When that turn ends, a settlement notice is queued or steered into the session that ran the workflow, even though the workflow explicitly chose caller for this child. Is that intended?

Host scenario

A host owns several continuable children whose results go to their real audience through a channel the host owns (a chat surface). The parent is a long-lived session a human is working in. After the first turn, every child settlement is steered into whatever turn that session is running.

Ask

Persist the delivery policy for local continuable children the same way persona and toolFilter are persisted: write delivery into the descriptor when it is 'caller', and restore it in coldResume. Absent the field, the behavior stays 'parent', so existing children are unchanged.

If the intent is instead that a resumed child has no caller and therefore must report to its parent, then a separate durable opt-out such as "notice: none", distinct from "who awaits the result", would serve the host scenario. Either answer would help; we're currently carrying a local patch that persists exactly this field.

[PerryLink]

四条断言我逐条核了，全部成立，而且 master 上一处未改。但你的实现建议里有一个坑你没提到 —— 它会决定这个改动是"加一个可选字段"还是"一次有意的版本升级"。

1. 四条断言逐条成立

(a) delivery 只活在内存里的 activation 上

packages/subagent/subagent/src/types.ts:30-44：

/** One managed child execution and its result delivery policy. */
export interface SubagentActivationSpec {
  …
  /** Parent delivery notifies the model; caller delivery only returns the result. … */
  readonly delivery: 'parent' | 'caller'          // :43
}

而 descriptor 的键集里没有它：descriptor.ts:103-110 的 CONTINUABLE_DESCRIPTOR_KEYS = new Set([...DESCRIPTOR_BASE_KEYS, 'agentProvider', 'agentModel', 'agentReasoningEffort', 'persona', 'toolFilter'])（DESCRIPTOR_BASE_KEYS = version/mode/provider/label，:96-101）。写入点在 manager.ts:394-403。

(b) coldResume 不传 delivery ⇒ 回落 'parent'

manager.ts:1325-1376 的 coldResume(parent, childId, content, options)，其 :1355-1369 调 this.materialize({ kind: 'local', childId, provider: descriptor.provider, parent, agentOptions: {…}, composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter }, signal: options.signal }) —— 没有 delivery。默认值在 :924-937：

delivery: inputs.delivery ?? 'parent',            // :930

descriptor 的 provider / model / effort / persona / toolFilter 都还原了，唯独 delivery 没有。你说的这个不对称，完全准确。

(c) notifySettlement 的 caller 短路

manager.ts:1183-1184：

private notifySettlement(activation: Activation, terminal: SubagentResult): void {
  if (!activation.announced || activation.delivery === 'caller') return

(d) caller 只覆盖第一段驻留

manager.ts:1077-1087 的 settlementState()：:1084 if (activation.ownedChildren.size > 0) return 'wait'、:1085 if (activation.failureAt === undefined && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0)) return 'wait'、:1086 return 'ready'；finishDisposal 里 :1171 this.resident.delete(childId)；再投递时 :1252 if (activation === undefined) return this.coldResume(parent, childId, content, options)。

你引的 README 也准：packages/subagent/README.md:119（"completed local workflow children remain discoverable and can be opened or continued"）、:61（只描述两种 delivery 的语义，未说明它只对本次 activation 有效）、:160（"One notice per settled activation using parent delivery. Caller delivery adds no completion message…" —— "per settled activation" 正是问题所在）。

2. ⭐ 你没提到的坑：descriptor 会拒绝未知字段

这是我最想让你先知道的一条。packages/subagent/subagent/src/descriptor.ts:119-124：

function assertKnownKeys(value, keys, path) {
  const unknown = Object.keys(value).find(key => !keys.has(key))
  if (unknown !== undefined) throw new Error(`persisted subagent descriptor ${path} has unknown field "${unknown}"`)
}

调用点 :182-186。而模块头 :8-19 已经把规矩写明了：

Supporting another composition input is a deliberate version change, never an implicit extra field.

⇒ 只把 delivery 塞进 descriptor、不同步改 reader，会让别的运行时读该子会话时报 unknown field。 正确做法是走一次版本升级：

• descriptor.ts:48 的 SUBAGENT_DESCRIPTOR_VERSION = 3 → 4
• 四处同步：CONTINUABLE_DESCRIPTOR_KEYS（:103-110）、ContinuableSubagentDescriptorData（:72-86）、parseSubagentDescriptor（:204-221）、snapshotSubagentDescriptor（:230-249）

而且代价是明确的：parseSubagentDescriptor 在版本不符时返回 undefined（:176）⇒ 旧版本运行时会把该子代理判为不可续（manager.ts:1347-1352 → 'NOT_RESUMABLE'）。这就是"deliberate version change"的代价，应该在报告里点明 —— 否则维护者会以为这是零成本改动。

3. 关于你引用的"按 persona / toolFilter 的方式持久化"

方向对，但这三个字段不平权：

• persona / toolFilter 属于 composition，它们是随 descriptor 一起落盘的组成输入
• delivery 语义上不是"组成"，而是结果投递策略 —— 它更像"这次谁在等结果"

所以如果按你说的方式加，字段名与位置都还合理；但如果你愿意听一个建议：另一个正交方案是在同一次版本升级里加一个 notice?: 'none'（durable opt-out），把"谁在等结果"（delivery）与"要不要通知"（notice）分开。你提的第二方案在架构上是可行的，而且它能覆盖"a non-composing consumer"这个你说的场景 —— 只是它需要和 delivery 一起设计，避免两个字段语义重叠。

4. 版本

你写 @deepseek-ai/dsh-subagent 0.2.1-alpha.2 —— 这是当前 npm alpha dist-tag，就是最新。我核的是 origin/master = d743267388（= dsh-v0.2.1-alpha.2），上述行号全部一致 ⇒ 没有过期问题。

顺带确认了你说的"由 activation 重构引入"：git log -S "SubagentActivationSpec" -- packages/subagent/subagent/src/types.ts 命中 3d852a1cea（2026-09-17）与 390fbe8852（2026-09-21），两者 git tag --contains 都只有 dsh-v0.2.1-alpha.2；而 <dsh-v0.2.0-rc.2> 的 types.ts 里没有 delivery 字段 ⇒ caller 语义确为 alpha.2 新增。

5. 短期 workaround 的一条提醒

如果你要维持本地 patch，务必同时抬高 SUBAGENT_DESCRIPTOR_VERSION —— 否则他人运行时读你写出的子会话会因 unknown field 报错，并把该子代理降级为 NOT_RESUMABLE。这不是"多此一举"，是第 2 节那条 assertKnownKeys 的硬要求。

[prgrmrwy]

Thanks — the strict known-key validation and versioning cost are important points.

I checked our local compatibility patch. It does not add the field to descriptor v3. It introduces a versioned durable policy named settlementNotice: 'notify' | 'silent', bumps the ordinary continuable descriptor to v4, and restores that policy on both cold-resume paths. The default notify value is omitted from the snapshot, while silent is persisted. Our separate independent-composition extension uses another descriptor generation.

So our current implementation is closer to the orthogonal notice: 'none' option you described than to persisting delivery: 'caller' itself. That distinction seems cleaner: delivery describes who awaits a particular activation result, while settlementNotice describes whether every future activation should notify the durable parent.

I have also added an explicit fresh-runtime regression: create a silent continuable child, let it settle, dispose the entire Context, boot a new Context against the same persistence root, resume the parent, cold-resume the child with another prompt, and verify that the child runs while the parent still receives no settlement notice. The focused patched continuation suite now passes 161/161.

I agree that an upstream implementation should treat this as a deliberate descriptor version change and document that an older runtime will not resume children carrying the new descriptor version.

[prgrmrwy]

After thinking through the consumer semantics, I would now prefer the orthogonal durable notice policy over persisting delivery: 'caller'.

delivery answers who awaits the result of the current activation. On a later cold resume, the original caller no longer exists. Persisting caller suppresses the unwanted parent notice, but does so by turning an activation-local routing choice into a durable child policy.

Our actual Host use case is different: every activation's business result is delivered through a Host-owned channel, so the durable child must opt out of automatic parent settlement notices across resumes. A descriptor-versioned field such as settlementNotice?: 'silent' or notice?: 'none' models that directly. The initial activation can still use delivery: 'caller'; later cold activations restore the durable notice policy without pretending that the original caller still exists.

I would therefore rank the options as:

1. Preferred: keep delivery activation-local and add a durable, versioned parent-notice policy restored on cold resume.
2. Minimal fix: persist delivery, with an explicit descriptor version bump and the documented downgrade cost.

The original observation remains valid either way: today caller suppresses the first activation only, while subsequent activations silently revert to parent notification. This is a refinement of the proposed fix, not a withdrawal of the bug report.