第三方插件声明的持久会话事件类型永远不在 KNOWN_SESSION_EVENT_TYPES 里，导致带该事件的会话在任何官方 harness 上都拒绝加载

[migiboxAI]

中文摘要：我们开发并发布了一个第三方插件（@wy35002/dsh-model-fallback，模型限流/配额自动回退）。开发过程踩了三个坑，其中一个是机制层缺口（第三方插件声明的持久会话事件类型永远不在 KNOWN_SESSION_EVENT_TYPES 里，导致带该事件的会话在任何官方 harness 上都拒绝加载），另外两个是文档盲区（client 端 inject 与 ctx.remote.* 命名空间的对应关系；rc 升级对仓库外插件作者的破坏性变更没有 changelog 提示）。详细经过与建议如下，希望对其他插件作者有帮助，也欢迎维护者评估是否值得改进文档或机制。

Context

We built and published a third-party plugin: @wy35002/dsh-model-fallback (+ a companion UI settings card @wy35002/dsh-model-fallback-ui) — it auto-switches the model on rate-limit/quota failures by advancing a user-configured fallback chain, and ships a settings card for labeling models free/paid.

We developed it against 0.1.2-alpha.3 (master at the time), then adapted and republished it for 0.1.2-rc.1. It is now working end-to-end (define → publish to npm → dsh plugin add → settings card → model calls). The documentation was a big help: docs/user/develop/basic/publish.md (bundle/profile model) and docs/cookbook/adding-a-settings-card.md (the two halves + namespace-as-join-key) are excellent, and we followed them closely.

That said, three things cost us a lot of debugging time. Sharing them in case they help other plugin authors — and in case the maintainers want to close the gaps.

---

Gap 1 (mechanism): durable session events written by an npm-installed plugin are always "unknown" to the stock harness

Our plugin appends a durable event type model-fallback/switch (declared via declare module '@deepseek-ai/dsh-session/types' merging, folded by a session projection). Sessions written by the plugin then fail to load with:

failed to observe session "...": session "..." contains event type "model-fallback/switch" (seq N)
unknown to this harness and not marked ignorable; refusing to interpret the log
— it was likely written by a newer harness (gateway/internal)

Root cause: KNOWN_SESSION_EVENT_TYPES (packages/core/session/src/known-event-types.ts) is generated by scripts/gen-persistence-catalog.ts, which scans packages/*/*/src/**/*.ts — in-repo sources only. A plugin installed from npm into a profile's node_modules is never scanned, so:

• its event type is absent from the compile-time known set, and
• even the harness that has the plugin installed and running refuses to re-observe sessions containing those events, because the check happens against the compile-time set at load time, not against live registrations.

Our workaround was only possible because we develop the plugin inside a repo checkout: re-run gen-persistence-catalog with the plugin source present under packages/experimental/, force-rebuild (tsdown does not pick up the regenerated file on an incremental build:lib:host — we had to re-run the host-face bundling explicitly), and restart. A plugin author who only ships npm tarballs cannot do this.

Questions / suggestions:

1. Is the intended third-party path that plugin-owned durable events must set ignorable: true on the envelope? That keeps the log loadable on harnesses without the plugin, and our projection still folds them from the loaded log — but we could not find this documented anywhere as the contract for out-of-tree plugins. If it is the contract, a sentence in the plugin docs (docs/user/develop/) would prevent people from hitting a scary, log-poisoning failure.
2. If non-ignorable third-party events are meant to be supported someday, a runtime registration hook (e.g., plugins declaring their durable event types so the load-time check consults live registrations as well as the compile-time set) would close the gap.
3. Either way, the failure message could hint at the third-party case ("written by a plugin; if you uninstalled it, its sessions can no longer be opened").

---

Gap 2 (docs): the client-side inject → ctx.remote.* namespace mapping is undocumented

Our settings card needed session/modelCatalog (to list each provider's models). On the browser side, ctx.remote.session was undefined even though the Host serves the namespace fine — because our dsh.client.inject did not include the package that contributes that namespace.

What we learned by trial and error:

Browser-side namespace	Provided by injecting
ctx.remote.session (modelCatalog, prompt, …)	@deepseek-ai/dsh-api-session-controller
ctx.remote.llm (listProviders, …)	@deepseek-ai/dsh-api-remotes

docs/cookbook/adding-a-settings-card.md shows an example inject list, but does not explain which package contributes which ctx.remote.* namespace — and the failure mode is silent (our store swallowed the TypeError into an empty array, so the panel just showed no models). A small mapping table in that cookbook (or in the client modules README) would have saved us hours. Relatedly, session/modelCatalog is exactly the right API for "list currently routable models per provider" — worth mentioning there too, since llm.discoverModels only covers providers that registered model discovery (the built-in deepseek-official route has none, so it errors with no model discovery is registered for "llm-deepseek").

---

Gap 3 (docs/changelog): plugin-affecting breaking changes between 0.1.2-alpha.3 → rc.1 were invisible to out-of-tree authors

Adapting our plugin to rc.1 required discovering, by typecheck archaeology:

• session.events (public getter over the log) is gone — replaced by session.snapshotEvents() / session.surface / session.ownEvents().
• LlmModelInfo is exported from @deepseek-ai/dsh-llm/types, not re-exported from @deepseek-ai/dsh-api-remotes/client.
• For listing models per provider from a client card, session/modelCatalog is the supported path; llm.discoverModels(settingsNs, request) only works for providers that registered discovery.

None of these appear in any changelog/release note as plugin-affecting. Since "everything is a plugin" extends to out-of-tree authors, a short "changes affecting third-party plugins" section per release (or a docs/user/develop/ migration note per breaking release) would make rc-to-rc upgrades much cheaper.

---

What worked well

To be balanced: docs/user/develop/basic/ (first plugin → config → publish) is a genuinely good tutorial path; the bundle/profile two-manifest model is clean and dsh plugin add just works; and the settings-card cookbook's "namespace is the join key; a card renders when the Host serves its key" design made the two halves pair up automatically once we got the packaging right. The harness being fully source-runnable made every failure debuggable down to the generated catalog files.

Happy to expand any of this into concrete docs PRs if the maintainers tell me which direction they prefer (docs-first vs. mechanism change for Gap 1).

---

Plugin: @wy35002/dsh-model-fallback on npm (host plugin + client settings card). Developed on a source checkout of 0.1.2-alpha.3, now running against 0.1.2-rc.1 on Windows.

[argszero]

Great writeup — and the root cause is cleanly confirmed by the source. Your Gap 1 is not a bug, it's the documented (but under-publicized) contract, and it's worth making that explicit because the failure message genuinely reads like a bug.

The ignorable: true contract IS the intended third-party path — your question #1 is answered by the source, definitively:

• KNOWN_SESSION_EVENT_TYPES is generated by scripts/gen-persistence-catalog.ts, which globs packages/*/*/src/**/*.ts (in-repo sources only, line 176). An npm-installed plugin is never scanned — so its durable event type is structurally absent from the compile-time set.
• The generated module's own docstring says it explicitly, right on the type you hit:

  "Downstream (out-of-repo) plugin events are outside this list by construction. The persisted SessionEvent.ignorable marker is the compatibility mechanism; event-name registration was rejected because it does not classify omission safety and would make reads composition-dependent."

• The rationale is archived in .agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md, and the marker is SessionEvent.ignorable (packages/core/session/src/types.ts:465, ignorable?: true).

So the design is: a harness that lacks your plugin must still be able to read the log without breaking replay, because it cannot know what model-fallback/switch means. Marking it ignorable means "if you don't understand this event, you may skip it without corrupting the session" — which is exactly right for a plugin-owned, projection-folded event. Your projection still sees the event from the loaded log regardless, so ignorable costs you nothing on a harness that has the plugin.

What I'd add to the docs (your suggestion #3, and it dovetails with your #1): the current err message is tersely "unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness". That tail assumption ("newer harness") is wrong for the out-of-tree plugin case — it's more likely a plugin event from an uninstalled plugin. A runtime hint like:

"written by a plugin; if you uninstalled the plugin that owns this event, its sessions can no longer be opened" — or even just appending "a third-party plugin may own this event" to the existing tail — would turn a scary-looking failure into an actionable one. That's a one-line change in the storage-contract read path.

For your Gap 3 — the invisible session.events → snapshotEvents() / surface / ownEvents() and LlmModelInfo relocation, plus the session/modelCatalog vs llm.discoverModels split — this is the remove-without-signal family the community has hit repeatedly (plugin-visible API shifts that never make a changelog). Your "changes affecting third-party plugins" per-release section is a genuinely good proposal; if you write it up, I'd cite #5859 (same root: removals shipped without a signal to out-of-tree consumers).

One tool that would have caught Gap 1 immediately: a proactive completeness audit over the session log. @argszero/cordis-plugin-session-audit classifies the corruption surface before replay — its UNKNOWN_REQUIRED_TYPE code flags exactly this class: a type outside the known vocabulary not marked ignorable, which the read path will hard-refuse (your #5769-style failure mode). It prints error for it and tells you it's a reload-blocking condition, so you'd know the moment a log contains a plugin event whether it's going to refuse. It never fixes — it just classifies, which is the right tool for triaging whether a session is recoverable or needs the ignorable marker backfilled.

Happy to help turn Gap 1's doc sentence into a concrete PR, or review the docs-mapping table for Gap 2 if you draft it — the ctx.remote.* namespace → contributing-package table is genuinely missing from the settings-card cookbook.