[core/agent] 'compact' SessionStartSource is reserved but never emitted — no lifecycle signal for plugins to re-seed context after compaction

[YaoQC-Ai]

Summary

agent/session-start is the documented extension point for seeding model-facingcontext (agent.inject() at session start). Its SessionStartSource type reservesa 'compact' value, but compaction never re-fires agent/session-start, so a pluginwhose seeded context is later elided by compaction has no clean lifecycle hook tore-seed it. This is acknowledged in the maintainers' own Dev Note as pending work.

Evidence (source, 0.1.2-rc.1)

• packages/core/agent/src/runtime-types.ts:69 — export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'.
• packages/core/agent/README.md:179 (maintainers' Dev Note, non-authoritative) — "the SessionStartSource values 'clear'/'compact' are reserved with no emitter yet, pending the driving subsystems."
• agent/session-start fires once, before the first turn, with startup/resume only (index.ts:181, runtime-types.ts:214-224).
• Compaction runs and does record the fact, but only as durable session log events: session.append('compaction/start' | 'compaction/summary' | 'compaction/end', …) (packages/compaction/compaction-basic/src/region.ts:191,217,225). These are log entries observed via agent.session.snapshotEvents(); they are not dispatched as an agent-subject lifecycle event (emitAgentEvent), so ctx.on('agent/…') listeners never see a "compaction finished" callback.
• Compaction is head-anchored (selectCompactableRange returns { start: surfaceNodes[0], … }, region.ts:132-135), i.e. it elides from the oldest nodes forward — which is exactly where a session-start-injected context block sits. So a plugin's injected block is among the first things removed, with no re-injection notification.

Why it matters

Any plugin that seeds persistent context at session start — memory / RAG / standinginstructions / background-knowledge injectors — silently loses that context once thesurface compacts, and has no supported trigger to restore it. This is a growing class:the platform's own agent.inject() seam is designed for exactly this seeding.

Current workaround (plugin side)

Poll: on agent/pre-step, after await next(), test whether the seeded block is stillvisible on the agent surface (agent.session.surface.nodes / inbox / current-stepmessages); if not, re-inject() it. This works but is (a) O(steps) busywork, (b) apresence heuristic the plugin must reinvent, and (c) timing-sensitive to the waterfallorder relative to the compactor.

Suggested directions (not prescriptive)

1. Honor the reserved emission: after a compaction transaction commits(compaction/end without error), re-emit agent/session-start withsource: 'compact' for the affected agent. The enum value and the durable eventalready exist; this mostly wires the two.
2. Or expose a dedicated agent-subject event (e.g. agent/compacted) carrying thecompactionId / the seq range removed, dispatched through emitAgentEvent soctx.on('agent/compacted', …) listeners can react.
3. Either way, a short doc note pointing plugins at the intended re-seed hook wouldremove the need for the pre-step polling workaround.

Environment

• @deepseek-ai/dsh: 0.1.2-rc.1
• OS: Windows 11 25H2, Node.js LTS
• Observed building a context-injection plugin against agent/session-start + agent.inject(); verified against compaction-basic.

Note

Filed as an enhancement, not a defect — the platform behaves as currently documented(compaction records durable events; the 'compact' source is explicitly reserved-not-implemented). The ask is a plugin-facing notification seam for an ecosystem need.