[Feature / Architecture] Provide a formal registration surface for downstream plugin SessionEvent types to avoid SessionFormatUnsupportedError

[chenmzh]

Summary

When an external / downstream Cordis plugin appends custom event types to a session (for example, a reasoning router recording reasoning-router/initial-consult), the live interaction works as expected. However, upon reopening the session or inspecting history via sessionPersistence.load / inspect, DSH refuses to read the session log with a SessionFormatUnsupportedError.

This renders previous session history completely inaccessible to users in the Web UI:

SessionFormatUnsupportedError: session "session-..." contains event type "reasoning-router/initial-consult" (seq 8) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness (raw log: .../session.jsonl.zstd)

---

Background & Context

In packages/core/session/src/known-event-types.ts and docs/subsystems/persistence.md, the design rationale notes:

"Downstream (out-of-repo) plugin events are outside this list by construction; a registration surface for them is deferred until such a consumer exists."

And in packages/session/session-persistence/src/coordinator.ts:

private assertEventsSupported(meta: SessionHeader, events: readonly SessionEvent[]): void {
  for (const event of events) {
    if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue
    throw this.unsupported(meta, `session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`)
  }
}

Now that the Cordis plugin ecosystem is actively growing with real-world plugins (such as LLM reasoning routers, verifiers, and multi-agent workflows), real consumers requiring custom SessionEvent logging have emerged.

---

Technical Challenges with Current Workarounds

When external plugins currently attempt to declare and register events:

1. Module Instance Isolation (Dual-Package / TSX Hazard):
   When running via tsx (which executes TypeScript source trees directly) alongside pre-compiled dependencies in node_modules/, mutating a locally imported KNOWN_SESSION_EVENT_TYPES Set only affects the copy within that specific package's bundle. The persistence coordinator in the runtime tree reads from its own module instance, causing the registration to be missed.
2. Missing Formal Registration API:
   There is currently no formal Cordis service API on SessionStore (e.g. ctx.sessions.registerEventType(...) or declarative plugin manifests) to register custom event types cleanly during lifecycle boot.

---

Proposed Solutions

1. Declarative / Service-level Registration API:
   Provide a method on SessionStore or Context (e.g. ctx.sessions.registerEventType(name: string, options?: { ignorable?: boolean })) allowing plugins to register custom vocabulary during apply(ctx).
2. Process-Global Shared Event Vocabulary:
   Store the runtime KNOWN_SESSION_EVENT_TYPES set using a process-wide Symbol (e.g. globalThis[Symbol.for('@deepseek-ai/dsh-session/known-event-types')]), ensuring that registrations across different package copies and TSX/CJS/ESM boundaries stay synchronized.
3. Envelope ignorable Guidance / Helper:
   Provide clear utilities or default conventions for plugins emitting purely advisory / non-structural records so they can easily set ignorable: true at write time (Session.append).

---

Benefits

• Prevents breaking user session history when installing ecosystem plugins.
• Fulfills the deferred registration surface envisioned in the original session log architecture design.
• Improves resilience and extensibility of the DSH plugin ecosystem.

[xiaoshenming]

和 #3802 / #2778 同一条路：仓外 type 不在生成的 KNOWN_SESSION_EVENT_TYPES 里，Session.append() 又写不了 ignorable，第二天从磁盘恢复就 SessionFormatUnsupportedError。

dsh-session-surgeon 的 inspect 会标 unknown-type。不会给别人的自定义事件补 ignorable，也不会删这些行（改语义）。根因还是官方要开登记口。

若同时还有 seq gap / torn / 缺 message.id，那些可以 dry-run 修：

dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"

[Phant0Meow]

Another real out-of-repo consumer here — and as far as I can tell, the only one currently running a registration implementation in production. Adding our data points to this thread since it is the most recent formal proposal.

Our consumer case

We ship a multi-agent theater engine as a DSH plugin: scripted flows drive several subagent actors plus a director main agent, and the plugin persists presentation-only chat lines to session logs as one custom type (dsh-femwa/chat — payload: actor name, a line kind covering role lines / engine notices / human-wait markers / node hints / errors / folded CoT / tool-invocation rows / speaker name rows / run receipts, and a scope-visibility list). A ConversationNodeDefinition matches the type so theater transcripts replay across restarts with the built-in ordering, folding, and view filtering.

• The events are not model-visible; most kinds have no official counterpart (orchestration-level facts plus actor-name mapping that official types cannot carry).
• One kind is written to main-session logs too (run receipts), so uninstalling the plugin or opening our sessions on a stock build reproduces exactly the poisoning scenario in Session logs become unreadable after a plugin that wrote session events is uninstalled #2228.

Our production implementation (running since 2026-08-21)

Our fork carries a ~40-line runtime registry on the session package, essentially the shape several threads have sketched:

const registeredEventTypes = new Set<string>()

export function registerSessionEventType(type: string): () => void {
  registeredEventTypes.add(type)
  return () => { registeredEventTypes.delete(type) }
}

export function isKnownSessionEventType(type: string): boolean {
  return KNOWN_SESSION_EVENT_TYPES.has(type) || registeredEventTypes.has(type)
}

• The plugin registers at apply time via ctx.effect(...) (before any session load); the disposer keeps it HMR-safe.
• On stock builds without the surface, the plugin degrades gracefully: live sessions keep working, only history loading of our sessions fails, with a diagnostic log pointing at the limitation.

Six days of production use, zero issues attributable to the registry itself.

What a week of production adds to the design discussion

1. Composition-dependent acceptance is manageable, not fatal. The concern in the fail-closed agent note (same log, different acceptance per runtime) is real, but our degradation path shows the failure mode can be made loud and survivable while a real design is pending. A runtime registry is a viable stopgap, not the destination.
2. We second both sides of the required/optional split (Required downstream Session events need an instance-scoped persistence recognition seam #1896): our chat lines are genuinely optional — skipping them loses presentation, not semantics — so an envelope-level skippable flag fits them perfectly. And we can confirm the write-side gap from Out-of-repo plugins cannot mark session events `ignorable` — every log they touch becomes unreadable (extensibility gap + minimal fix) #1538: Session.append() opts tuple currently accepts nothing for non-surface types, so even a willing writer cannot mark its own events today.
3. Consumer census for this request (from the discussions I could find): reasoning-router ([Feature / Architecture] Provide a formal registration surface for downstream plugin SessionEvent types to avoid SessionFormatUnsupportedError #4204), Avocado with 13 event types ([Feature / Architecture] Provide a formal registration surface for downstream plugin SessionEvent types to avoid SessionFormatUnsupportedError #4204 comments), pi2dsh and the Pi ecosystem (Let out-of-repo plugins write durable session events (the deferred registration surface) #2708), dsh-agent-teams (Out-of-repo plugins cannot mark session events `ignorable` — every log they touch becomes unreadable (extensibility gap + minimal fix) #1538), MyAgents-dsh with required non-skippable events (Required downstream Session events need an instance-scoped persistence recognition seam #1896), dsh-talk/speech (Bug: plugin-authored session event types without ignorable make sessions unreadable (SessionFormatUnsupportedError) - dsh-talk/speech #3416), dsh-click ([Proposal] Session event registration for out-of-tree plugins — unknown event types refuse resume (dsh-click/observed|action crashes rc.6/rc.7) #3191), @loserfox/distill (Session logs become unreadable after a plugin that wrote session events is uninstalled #2228), and ours. Nine independent consumers spanning at least three requirement shapes: optional presentation rows, required state transitions, and compatibility layers writing foreign types.

What we would contribute

Once the team lands on a direction — an envelope-level skippable field with an append option (as #1538 sketched), a type registration seam, a session-header manifest of plugin types, or something else — we are happy to prepare the PR, contribute our registry as reference, and run validation against our real sessions on an alpha branch.

[loggiqadmin]

Current-master update and a concrete SDD consumer

I am adding another out-of-repo consumer, with an important refinement to the original proposal.

I reviewed the current design on cd5ef81481 (0.1.2-alpha.1), after the per-record ignorable field was deliberately removed. I agree with the fail-closed invariant: a reader must not silently omit an unknown durable event because that event may affect request reconstruction, policy state, recovery, or a plugin-owned projection. A local prototype commit (e5be286e46) explored the older per-append ignorable approach against an rc.7 base; it is therefore evidence of the integration point, not a change I propose merging onto current master.

Consumer case

We are specifying an external Spec-Driven Development engine plugin. Its project state is Git-shareable and authoritative under .dsh/sdd/; the Session log separately records session-scoped selection, provenance, and every SDD input that becomes model-visible.

This produces both required semantics:

• sdd/selection identifies the project, feature, and run selected for one Session. It grants no authority, contains no model-visible content, and can be skipped when the plugin is absent because the Git artifacts remain authoritative.
• Later SDD snapshot/input events feed model requests. They must be reconstructable from the Session log. If the owning plugin is absent or cannot interpret them, restoration must fail loudly.

Consequently, a registration API that only adds arbitrary strings to a process-local “known” set is not sufficient. Optional versus required semantics must be explicit and durable; otherwise the same stored bytes can silently acquire different meaning under a different plugin composition.

Requested foundation

A safe external-event extension would provide:

1. Declarative, effect-scoped registration that is active before Session restoration.
2. A type-level classification of each external event as optional or required, instead of a per-append assertion.
3. Persisted classification (for example, a Session vocabulary manifest or equivalent durable metadata), so the writer’s semantics survive restart and plugin removal.
4. Required external events accepted only when a compatible owner is registered; otherwise restoration refuses them.
5. Optional external events skipped only when the durable declaration permits it.
6. Conflict detection for duplicate registrations with incompatible semantics.
7. Registration that works across source/built module copies rather than relying on mutation of one imported Set.

This does not request restoring the old call-site ignorable flag or weakening the default rejection of unknown events. It requests a formal vocabulary extension that preserves the current fail-closed rule while distinguishing events whose writer explicitly declared them safe to omit.

This refines the earlier consumer report in #802 and the registration proposal in this thread with a use case that needs both optional and required external records.