V3 accepts {kind:'plugin'} but V4 refuses it — plugin-authored injected messages have no literal that satisfies both

[1420079678-ctrl]

V3 validation and V4 admission disagree about plugin-authored message sources, and there is no literal that satisfies both. Every out-of-tree plugin that injects messages the way the V3 tree taught will fail on 0.1.7 with format v4 message requires a producer-owned source kind. Reporting it with source citations; corrections welcome if I have misread something.

The two rules

V3 accepts 'plugin', and refuses anything it does not recognise. packages/session/session-format-v2-to-v3/src/payload.ts:

const SOURCE_KINDS = new Set(['user', 'plugin', 'model', 'tool', 'agent-instructions', 'session-reference', 'team-message', 'goal', 'skill-invocation', 'skill-catalog', 'coordinator', 'subagent-report', 'subagent-settled', 'webhook', 'agent-message'])

function assertSource(message) {
  const source = record(message['source'], 'message source')
  if (typeof source['kind'] !== 'string' || !SOURCE_KINDS.has(source['kind']))
    throw new SessionFormatUnsupportedMigrationError('cannot safely transform unclassified message source')
}

'plugin' is in that closed set; 'plugin:<name>' is not. Line 237 of the same file goes further and requires the retired literal for system messages: if (source['kind'] !== 'plugin' || typeof source['plugin'] !== 'string' …) throw new SessionFormatError('system message requires plugin source').

V4 refuses 'plugin' — packages/session/session-format-v3-to-v4/src/message-sources.ts, with the rejected set pinned by the spec (null, [], {}, {kind:''}, {kind:1}, {kind:'plugin',plugin:'compact'}):

if (!isSessionFormatJsonObject(value) || typeof value['kind'] !== 'string'
    || value['kind'].length === 0 || value['kind'] === 'plugin')
  throw new SessionFormatError('format v4 message requires a producer-owned source kind')

So on a V3 host, {kind:'plugin', plugin:'X'} is the only accepted form; on a V4 host it is the one refused form, and the accepted form ({kind:'plugin:X'}) fails V3 admission with cannot safely transform unclassified message source. Neither literal is portable.

Why this only bites out-of-tree plugins

In the 0.1.6 tree, every producer writes the retired literal — first-party included: session-title-llm (session-title-llm/src/index.ts:250), plan-mode (:461), cordis-host-runner (five sites), time-context (:217), tmux-context (:259), schedule (runtime.ts:271), hooks-codex / hooks-claude-code (PLUGIN_SOURCE), agent-instructions (state.ts:96), compaction-basic (summarizer.ts:148), tools-ptc (ptc.ts:635), plus the migration paths themselves. A code search of current master for that literal returns nothing: the repo-wide sweep happened in-tree, and the V3→V4 migration converts V3 rows on read — so nothing in the shipped configuration breaks.

An installed third-party plugin has neither benefit. It keeps emitting the retired literal on a V4 host, encodeCurrentEvent refuses it on the write path, and the user sees exactly the failure reported in #7546 — "本轮运行失败". Same for the read path, where assertV4SourceRowAdmission refuses retired wrappers in every declared message slot before recovery can discard them.

Measurement on a real machine (0.1.6-alpha.2)

I scanned this host's session logs for the pattern (multi-frame zstd, so the frames have to be walked — a single-frame decompressor misses everything after the first frame). One session, 12,019 rows: 85 messages still carry {kind:'plugin'}, from five producers — tool-jobs (76), repeat-tool-reminder (4), user-approval (2), @deepseek-ai/dsh-system-prompt (2), dsh-session-title-llm (1). That file is header version: 0, so the migration chain converts those rows on read and the session still opens — which is precisely why this stays invisible until a plugin writes under V4 rather than having its history read.

What would close the gap

Two things, either of which is sufficient for plugin authors:

1. State the migration in the plugin-facing docs — the mapping is already deterministic in producerKind(): third-party producers become plugin:<their name> and drop the plugin field; the 24 names in RELEASED_SAME_NAME_PRODUCERS keep their own name. Right now that rule is discoverable only by reading session-format-v3-to-v4 source, and the V3 tree still contains hundreds of counterexamples to imitate.
2. Expose a producer-side helper (e.g. a session-scoped injectedSource(name)) so a plugin asks the host for the version-correct source instead of hardcoding either literal. As long as the source is hand-built, a plugin that supports both harness generations has to branch on the session format version itself, and a plugin that does not branch is silently broken by an upgrade.

Happy to test a candidate helper on both generations if that is useful — I have a 0.1.6 install and a 0.1.7 target, and can report what each accepts. Disclosure so the report is not read as finger-pointing: our own organs write the retired literal too, so they are in the affected population; that is how I found this.

[1420079678-ctrl]

Correction to the report above — its central claim is wrong, and the correction is the useful part.

What I got wrong

I said "no literal satisfies both generations". That was read off the V3 source kind whitelist without checking which code path reads it. It does not govern native V3 traffic at all:

export function assertEvent(event, version: 2 | 3): void {
  if (version === 3) {
    assertV3Event(event)   // structural validation only
    return                 // ← returns before the source-kind checks below
  }
  ...
  if (event.type === 'user/message') assertSource(data)          // reached for version 2
  if (event.type === 'assistant/message' || event.type === 'tool/result') assertSource(...)
  if (event.type === 'agent/inbox/spliced' || …) for (const m of messages) assertSource(m)
}

So SOURCE_KINDS and assertSource() classify released V2 payloads during the V2→V3 migration. The native V3 write path (releasedV3SessionFormatCodec.encodeEvent → assertV3Event → assertV3StructuralRow + assertCanonicalPayload) classifies no message source. The one place a source requirement does exist on the native V3 path is system/message: assertSystem() demands kind === 'plugin' plus a non-empty plugin string.

Measured, not read

Instead of reading the validator again, I asked it. encodeCurrentEvent is the function the JSONL writer calls, so the matrix below is the host's own verdict on a real 0.1.6 install:

Slot	{ kind: 'plugin', plugin: 'x' }	{ kind: 'plugin:x' }
user/message	accepted	accepted
agent/inbox/spliced	accepted	accepted
system/message	accepted	refused — system message requires plugin source

Corrected conclusion

• { kind: 'plugin:<name>' } is portable for user/message, agent/inbox/spliced, assistant/message, tool/result and session/title-llm-request. It is accepted by V3 today and is exactly what V4 requires — so a third-party plugin can adopt it now, without waiting for a helper and without branching on the hosting generation.
• system/message is the only genuinely non-portable slot: V3 requires the retired wrapper, V4 refuses it. A producer that writes that slot has to know which generation is hosting.
• The producer-side helper I asked for is therefore a convenience for the one remaining slot and a guard against the next format change — not the thing blocking ecosystem migration. Downgrade that request accordingly; the migration itself is a one-line change per injection site.

What this means for the reports in #7546

Unchanged for the read path: existing rows with the retired wrapper are still converted by the migration, and assertV4SourceRowAdmission still refuses them on a V4 host if they arrive unconverted. But the remedy for plugin authors is simpler than I implied — rewriting {'kind':'plugin','plugin':'X'} to {'kind':'plugin:X'} and dropping the plugin field is not a workaround that trades one generation for the other; it is the target shape, accepted by both.

Verified on our side

Five injection sites here were writing the retired wrapper (all ordinary message slots — createUserMessage, subagents.followup, captain.send; none of them system/message). They now emit plugin:<package name>, reproduced from the values above, and the change is verified by the organ smoke suites (197 通过 / 0 失败 and 58 项断言全部满足) plus the encoder probe on this host. The reasoning and the probe are in the repository, along with the earlier revision this corrects.

Reproducing the matrix needs only the installed catalog path:

node scripts/probe-source-kind.mjs <path-to-installed-session-format-catalog>/lib/index.js

[wowlegend]

A concrete pointer for the "state the migration in the plugin-facing docs" item. At 0.1.7-alpha.2 (0010283), two cookbook pages still teach the retired wrapper that V4 refuses:

• docs/cookbook/adding-a-tool.md:49 (and adding-a-tool.zh.md:49): agent.inject({ content, source: { kind: 'plugin', plugin: '<name>' } })
• docs/cookbook/extension-cookbook.md:127 (and extension-cookbook.zh.md:131): followup(…, {source: {kind: 'plugin', plugin: 'schedule'}})

An author who follows those pages today writes messages that fail with format v4 message requires a producer-owned source kind. That is the error users are reporting in #7455 and #7546.

The literal those examples should show is already defined by the migration's source-kind table in packages/session/session-format-v3-to-v4/README.md:129-134: same-name first-party producers keep the bare string, and any other plugin name becomes plugin:<name>. For the generic example that is { kind: 'plugin:<name>' }. schedule is in the first-party same-name list, so the extension-cookbook row would become { kind: 'schedule' }.

Confirming the portability conclusion in the follow-up above from the other side: 0.1.6-alpha.2's assertEvent(event, 3) delegates to assertV3Event and returns (session-format-v2-to-v3/src/payload.ts:42-46). The SOURCE_KINDS check (assertSource) runs only on the version-2 migration path.

[mengge237]

给这条补三段迁移侧的实测 —— 中央主张你们已经自己更正过（作者 09-23 02:39 那条），剩下的缺口正好在「迁移路径」这一侧，而它没人写过。

一、迁移路径其实认 kind:"plugin"，而且会改写它。 packages/session/session-format-v3-to-v4 的产物里 rewriteV3MessageSource() 见到 kind === "plugin" 就转给 rewritePluginSource() → producerKind(plugin, role)：查两张表（RENAMED_PRODUCERS 2 项、RELEASED_SAME_NAME_PRODUCERS 25 项），都不在就落成 plugin:<name>。所以同一文件里 source() 那句对 kind === "plugin" 的硬拒，只在原生写侧生效、不在迁移侧生效 —— 正好接上 wowlegend 指的「cookbook 两页还在教被 V4 拒的写法」。

二、本机读数（全在副本，原件未动）：179 个存档 / list() 171 条会话里有 143 个存档、1,488 行 kind:"plugin"；用 0.1.7-alpha.2 的已发布产物逐条 open(write)+read()+close()：converted 171、failed 0，产出 171 个 session.v4.jsonl.zstd（104,904,541 字节），v0/v3 原件一个没动。但归属会退化：636 行落到 runtime-context，约 530 行落到 plugin:<name> 兜底（liangshen-tool-catalog、compact、dsh-auto-continue、anchored-tool-bootstrap、tools-ptc）—— 能读能迁，可这些注入消息在 V4 之后不再被按 producer 认出来。若 RELEASED_SAME_NAME_PRODUCERS 是封闭名单，这件事本身就该写进那两页 cookbook。

三、还有一件文档里肯定没有的（对所有双版本并存的人都是硬知识）：V4 是追加发布在旁边（与它自己脚本的自述一致：历史代次不动），但一个目录里一旦出现 session.v4.jsonl.zstd，0.1.5 运行时的 list() 就不再列出这条会话 —— 我方那 171 条被写过之后旧宿主看到 total 0，整张列表空掉且不报错；把 171 个 v4 文件挪走，旧宿主立刻恢复 171/171。所以"升级之前先跑 migrate:sessions-to-v4"是个陷阱：跑完旧宿主就读不到了。

判据 / 怎么复算这三段（不需要账号、不需要触屏）：在已发布产物里 grep -c "rewritePluginSource|producerKind" node_modules/@deepseek-ai/dsh-session-format-v3-to-v4/lib/index.js 非零（迁移侧会改写），再 grep -n "producer-owned source kind" 同一文件（原生写侧硬拒）—— 两处都在、结果相反，就是这条线程的形状。