[Ecosystem] Please open the deferred session-event registration surface — 12 threads, 9+ consumers, and 0.1.2-alpha left writers no path at all

[Phant0Meow]

Why a new thread when so many already exist

We knew about the existing discussions (census below) and deliberately did not add another voice to the pile. What changed our mind is the 0.1.2-alpha.1 update: instead of opening the deferred surface, it

• hardened the read guard further (fail-closed refusal is now the documented behavior for any out-of-repo event type), and
• removed the ignorable envelope field entirely — the one mechanism that could have let a willing writer mark its own records skippable. It was never exposed through Session.append(), no production writer used it, and it is now gone from the envelope, the SQLite schema, and the catalogs.

For a plugin ecosystem this is the hard version of an already hard constraint: any plugin that persists its own event type makes its users session histories permanently unreadable on every official build — and there is no longer any in-protocol exit for a willing writer.

The ecosystem stake

DeepSeek Harness identity is everything is a plugin. The session log is the only first-class durable channel in this architecture, and a growing family of plugins needs it for exactly the purpose the conversation system is built around: replaying their own rows through a ConversationNodeDefinition with the built-in ordering, folding, anchoring, and view filtering. Without a sanctioned path, every such plugin must either fork the harness (we did, reluctantly), invent a parallel store and re-implement replay (fragmentation the architecture explicitly avoids), or ship products whose users lose their history (the reports below).

Census of existing threads

Thread	Consumer	Need shape
#802	first report	general gap
#1584	rc.6 reporter	optional rows
#1538	dsh-agent-teams	optional rows + write-side analysis
#1896	MyAgents-dsh	required state events (must NOT be skipped)
#2228	@loserfox/distill	uninstall makes logs unreadable
#2708	pi2dsh (Pi ecosystem, 12 packages)	compatibility layer, foreign types
#3191	dsh-click	resume crash on rc.6/rc.7
#3416	dsh-talk/speech	ignorable unreachable
#3802	plugin events poison logs	optional rows
#4811	demo/hello	one unknown event aborts global reconciliation and search
#4204	reasoning-router + Avocado (13 types)	formal registration surface
ours	multi-agent theater engine	optional presentation rows + main-session receipts

Nine-plus independent consumers spanning at least three requirement shapes: optional presentation rows, required state transitions, and compatibility layers writing foreign types. Several report real user-facing breakage.

What we ask

1. Reconsider opening a formal surface, in the direction your own fail-closed note already points: distinguish required plugin state from genuinely optional records on disk. Concretely, one or both of:
   • an envelope-level origin/skippable field, exposed through Session.append(...) options (closing the write-side gap analyzed in Out-of-repo plugins cannot mark session events `ignorable` — every log they touch becomes unreadable (extensibility gap + minimal fix) #1538), so a reader that does not know a type can still honor the record own skip declaration;
   • a lightweight type-registration seam, so a runtime can admit the types it was built to interpret.
2. If the design needs a driving consumer: you have at least nine, several in production. We have run custom session events in production for nearly two weeks (a multi-agent theater engine replaying presentation rows through the conversation system), with a ~40-line runtime registry in our fork for the past week — idempotent, HMR-safe, and gracefully degrading on stock builds. We are glad to validate an alpha branch against real sessions and to prepare the PR.

We fully support the fail-closed goal of faithful reconstruction. The ask is purely to give willing writers a sanctioned, on-disk way to say this record is ours and skippable, so third-party plugins stop being one custom event away from bricking their users history.

[liyangbing]

The alpha.1 source diff supports the central claim here: this is no longer only a missing write-side option. ignorable was removed from the core event envelope and seed validator, the unknown-type guard now always refuses, and SQLite replaced the former logical/packing column with a distinct is_packed discriminator. A cast cannot recover a protocol that no longer exists.

I think a useful RFC should avoid making the first public surface only register(type: string). The census already contains three different semantic contracts:

class	reader without plugin	minimum contract
optional observation/presentation	core reconstruction may continue, named projections degrade	durable optionality + explicit degradation
required plugin state	must refuse before partial reconstruction	registered validator/decoder/migrator
foreign compatibility record	must not be treated as natively understood	versioned import/translation boundary

“Optional” also needs a projection definition. A record can be irrelevant to model-history reconstruction while still affecting surface ordering, source references, search, or plugin UI. If any later event depends on it, it is required.

A minimal registration record could carry:

interface SessionEventRegistration {
  type: `${string}/${string}`
  owner: { package: string; version: string }
  schemaVersion: number
  semantics: 'optional-observation' | 'required-state'
  validate(data: unknown): JsonValue
  upgrade?(from: number, data: JsonValue): JsonValue
  projections: {
    modelHistory: 'none' | 'required'
    surface: 'none' | 'optional' | 'required'
    search: 'none' | 'optional' | 'required'
  }
}

Not proposing that exact TypeScript API, but each fact needs an owner somewhere. The runtime lifecycle matters just as much:

1. registration completes before listing, persistence inspection, resume, search reconciliation, fork, or write;
2. one type has one owner; collisions fail atomically and name both packages;
3. registration is effect/HMR-safe, but cannot disappear while a live or stored required event depends on it;
4. write authority is limited to the registering namespace and schema version;
5. “plugin installed” is not read capability—activation and compatible interpreter availability must be proven;
6. JSONL/Zstandard and SQLite encode and enforce the same logical metadata;
7. absent optional interpreters produce explicit degraded projection/search coverage;
8. absent required interpreters produce a typed refusal with type, owner, schema, Session, and recovery direction.

The compatibility matrix should include same reader, plugin disabled, uninstall/reinstall, newer/older schema, duplicate registration, HMR disposal, mixed compatible/incompatible corpus, fork, export, and search—against both physical backends and from immutable stopped-process artifacts.

A ~40-line registry is valuable as a driving prototype, but a global mutable set by itself cannot validate payloads, express optionality, migrate versions, resolve ownership, or explain what uninstall means. Those are the differences between admitting a name and preserving durable semantics.

I turned the source diff and this review checklist into a fuller compatibility matrix here:
https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/plugin-development/custom-session-events.md#specify-a-compatibility-surface-not-only-a-mutable-set

[Phant0Meow]

补充一个关键设计诉求：信封级 skippable 要「透传」而不是「丢弃」

如果我们上一楼请愿的两个方向里，团队倾向「信封级 skippable 字段」（我们也倾向——它与 fail-closed note 指明的「在磁盘上区分必须的插件状态与真正可选的记录」完全同向），那么有一个设计决策对插件生态影响巨大，希望纳入考量：

读取器遇到「不认识但带 skippable 声明」的事件时，请把事件透传到客户端事件流，而不是静默丢弃。

为什么透传是关键

插件的客户端部分（比如注册 ConversationNodeDefinition、匹配自己的事件类型来渲染）本来就是插件自由，从来不需要官方许可。整个问题只在 host 侧的持久化读取：fail-closed 让「装了插件的构建」也无法打开含自定义事件的会话。skippable 字段只需要解决读取层的「不拒绝」，剩下的解释工作交给装了插件的客户端。于是：

• 装了插件的构建：事件流里有这条记录，客户端插件正常匹配渲染 → 历史回放完整；
• 没装插件的构建：会话能打开、官方行完整、未知行不显示 → 优雅缺失，而不是整份历史变砖（Session logs become unreadable after a plugin that wrote session events is uninstalled #2228 / [Bug report] One persisted session with an unsupported event (demo/hello) can abort global reconciliation and make session search report storage unavailable #4811 的场景）。

反过来，如果「跳过 = 丢弃」，那么即使装了插件，历史里的插件行也永远消失了——skippable 只剩「不报错」的价值，插件的回放能力实质上还是没了。早期版本的读路径曾经就是透传未知事件（core 折叠忽略它们），这个对插件最友好的行为值得以「声明制」的形式正式回归。

为什么透传不损害 fail-closed 的初衷

fail-closed 要防的是「读取器默默漏掉会影响请求重建、策略状态、投影恢复的事件」。skippable 声明恰好是写入方在磁盘上的显式表态：这条记录是插件私有的呈现层/状态数据，不参与这些语义。所以：

• 请求重建继续忽略它 —— fail-closed 保护的 core 语义毫发无损；
• 声明由插件作者负责：真有必须状态的插件（Required downstream Session events need an instance-scoped persistence recognition seam #1896 MyAgents 的场景）就不标 skippable，读取器遇到未知类型仍然拒绝，忠实重建的兜底完整保留。

一句话总结：fail-closed 管「会不会误解日志」，透传管「能不能被解释者接住」——两者正交，应该同时成立。

对写入方 API 形状的参考建议

session.append(type, data, { pluginOwned: true })（或 skippable: true）——落盘进事件信封（JSONL 一个字段 / SQLite 一列）。读取路径的判定：未知类型 + 无声明 → fail-closed 拒绝（现状）；未知类型 + 有声明 → 透传到客户端事件流，可附带「未解释」标注供调试。

这样插件生态得到一个完整的光谱：不装插件 = 优雅缺失；装了插件 = 完整体验；必须状态的插件用无声明事件 = 仍被忠实对待（或未来的注册面）。我们也愿意为信封字段这条路直接准备 PR（写入选项 + JSONL/SQLite/传输三处落盘 + 文档），并用我们真实的双端会话数据跑验证。

[tianyicui]

了解，我们正在积极考虑相关设计，让 session persistence 更好的支持插件作者

[yangfei222666-9]

补充核查：ignorable 字段已恢复，但公开 Session.append() 仍没有写入该标记的参数（对当前 master 的源码确认）

感谢团队在 alpha.2 恢复 SessionEvent.ignorable，也看到这里正在积极考虑相关设计。补一条使用者侧的源码核查，供设计参考。

当前 master 固定 SHA 的源码核查（2026-09-21）

对 deepseek-ai/deepseek-harness 的 master / ddefc45fbc7f8e46dd73185e68295696d1297887：

1. 字段在：SessionEvent 仍定义 ignorable?: true。其注释明确：遇到不认识的类型且没有该标记时，读者必须拒绝重建整份会话，而不是静默丢弃。
2. 读端 gate 在：validateStoredEvents() 只放行已知事件类型，或显式 ignorable === true 的未知事件。
3. 但公开写端仍无法写入该标记：公开 Session.append() 构造事件信封时只写 type / seq / time / data / surfaceOp? / sourceEventSeqs?，没有 ignorable；其可选参数类型 SurfaceIntent 也不含该字段，因此无法经由 opts 传入。

由此我目前只做一个窄判断：通过公开 agent.session.append() / Session.append() 路径，插件作者仍没有受支持的参数把「可忽略」标记写进事件信封。

范围说明：这是固定 SHA 的源码结论，不是当前版本的运行时复现，也没有穷尽内部或底层写入路径。本条相较本线程标题已经主张的「0.1.2-alpha 之后写端无路」，只增加「字段恢复之后、当前 master 上写端仍无路」的源码级确认，并不是一个新问题；如果这个增量对设计讨论没有帮助，请直接忽略。

请问：恢复信封字段之后，当前设计是否也计划向公开 Session.append() 开放这个写入选项？如果会，建议至少覆盖一条回归——显式标记的未知信息事件在持久化和冷恢复后仍可读取；未标记的未知事件继续 fail-closed。

边界：这里不声称本线程已被完整修复、当前版本运行时仍可复现、方案已采纳或已有路线图与 ETA；也不把上面的回复升级为承诺。