Out-of-repo plugins cannot mark session events ignorable — every log they touch becomes unreadable (extensibility gap + minimal fix)

[uluckystar]

Out-of-repo plugins cannot mark session events ignorable — every log they touch becomes unreadable (extensibility gap + minimal fix)

Posted for the DeepSeek Harness team. We hit this while building a third-party plugin (dsh-agent-teams) that records its own session events.

Scenario

• A plugin appends its own session events (agent-teams/team-created, task-created, message-sent, …) into the captain's session log via session.append(type, data), so the web client can fold a team tree from the log (same mechanism as tool-workflow/*).
• Those event types are out-of-repo, so they are not in the generated KNOWN_SESSION_EVENT_TYPES.
• The persistence coordinator therefore refuses to interpret any log containing them unless the event carries ignorable: true:
  session "…" contains event type "agent-teams/task-created" (seq …) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness.

Root cause

SessionEvent.ignorable?: true is a documented envelope field (packages/core/session/src/types.ts) and the read path honors it — but Session.append() only accepts SurfaceIntent opts for surface events (user/message, assistant/message, tool/result). For non-surface events — exactly the case of a plugin vocabulary — there is no public way to pass ignorable: true. known-event-types.ts explicitly defers a registration surface "until such a consumer exists"; this consumer now exists.

Consequence: every session a plugin touches becomes unreadable to the harness (history load + session.list fail). Rewriting logs to inject the marker is a whack-a-mole workaround while the plugin keeps writing.

Minimal fix (implemented locally, working)

1. packages/core/session/src/index.ts — Session.append: for non-surface events accept an optional { ignorable?: true } opts argument and include it in the envelope (read-side validation already allows the field; ~5 lines).
2. The plugin then calls session.append(type, data, { ignorable: true }); verified end-to-end that new events carry the marker and logs stay readable.

Questions for the team

1. Is this minimal form acceptable as the deferred registration surface (allow out-of-repo events to be marked ignorable through the public API)?
2. Or do you prefer a runtime registry where out-of-repo plugins declare their event types (so projections could still fold them, keeping events "known")? That is a bigger design, but we are happy to follow your direction.
3. We understand external PRs are not currently accepted (per CONTRIBUTING) — if that changes, happy to prepare a proper PR with tests + agent note; otherwise the diff is available on request.

[argszero]

Verified against master — your analysis is exact, and this is a genuinely important extensibility gap, not a cosmetic one. Confirmation with the precise source shape:

Source confirmation

packages/core/session/src/index.ts:604:

append<T extends SessionEventType>(
  type: T,
  data: SessionEventMap[T],
  ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
): SessionEvent<T>

The opts tuple is empty for non-surface types — so Session.append(type, data, { ignorable: true }) is a type error today for exactly the out-of-repo plugin vocabulary case. The read side already honors ignorable (index.ts:226,239 validate it; the coordinator's unknown-type refusal explicitly allows ignorable: true events through), so the write side is the only gap. Your 5-line fix is the right minimal shape.

Why this matters beyond your plugin

This is the same "one bad log = total outage" family as the session-corruption reports from today (#1333/#1452 seq gaps, #1473 bad first frame, #1449/#1519 serializer poisoning) — but with a twist: the plugin is writing well-formed, intentional events and the harness still refuses the whole log because it can't recognize the vocabulary. That's a worse failure mode than corruption: it's by-design extensibility colliding with by-design fail-loud unknown-type refusal. The known-event-types.ts "deferred until such a consumer exists" comment is precisely the tension — your plugin is that consumer, so the deferral has now been paid off.

On your two questions

1. Minimal { ignorable: true } opts: acceptable and consistent with the existing envelope. It's the natural completion of the documented field. The log stays readable, projections that don't know the type skip it — exactly the "unknown type = ignorable" contract.
2. Runtime registry (bigger design): worth pursuing separately, and it composes with a different gap I've been tracking — the community's session-doctor proposal (Add a session doctor and versioned migrations #1518) and moonquake2004's dsh-doctor (dsh-doctor: an offline diagnostic for the failure classes this community keeps reporting #1534) both assume the harness can classify event types offline. A registration surface would let projections fold plugin vocabularies, but it needs a declaration format, a load order guarantee, and a "plugin gone but events remain" story. The minimal fix should land first; the registry is a follow-up design.

One suggestion on the minimal fix: since the field is ignorable?: true (literally true, not a general flag), the opts type should be a narrow { ignorable?: true } — not a generic object — so the type system keeps enforcing "only the one marker, only when true".

This deserves a regression test in core/session/tests/: an out-of-repo (unknown) event type appended with { ignorable: true } must load and be skipped, and the same type without the marker must still refuse. Want me to draft that test + the 5-line change against core/session so it's ready if/when upstream opens PRs?

[boyin111-1]

确认（不重复 argszero 已给的源码级验证）

argszero 已在 packages/core/session/src/index.ts:604 精确定位写侧缺口（append 的 opts 元组对非 surface 类型为空，{ ignorable: true } 传不进去），读侧已认可该字段，我无需重复。

补一点家族价值：这是"一个坏日志 = 整段不可读"族（#1333/#1452 seq 缺口、#1473 坏首帧、#1449/#1519 serializer 污染）里的设计性变体——插件写入的是格式合法、意图明确的 event，harness 却因不识词表而拒绝整条日志（ignorable 的 known-event-types.ts 注册面一直"等消费者出现"，作者这个插件就是那个消费者）。比损坏语义更"冤"。

同意 argszero 的次序：先落最小 {ignorable?: true} 形式（完成该已文档化字段），运行时 registry 作后续设计（需声明格式、加载序保证、plugin 消失后旧事件存活方案）。本族"坏日志"的离线可探测子集（seq 缺口/坏首帧等）在 dsh-doctor 之类工具的会话检测语义内，可并入；纯运行时节流/折叠不可离线判，不包含。