@deepseek-ai/dsh-session 0.2.1-alpha.1 → 0.2.1-alpha.2

package/README.i18n.yaml

@@ -24,8 +24,11 @@
   en: aa5f1951ecf3ac0c
   zh: 62a599ace8f2bf15
 /deepseek-ai-dsh-session/use-this-package/read-the-log:
-  en: 2b29cfeac7a2baa8
-  zh: b535b04dcbc29d3d
+  en: c4bf3103b9762b6c
+  zh: 369c734bb20de2ea
+/deepseek-ai-dsh-session/use-this-package/write-experimental-plugin-records:
+  en: 6c758f98535b734c
+  zh: ac54342937477f37
 /deepseek-ai-dsh-session/use-this-package/fork-a-session:
   en: 1c40d17a786059d3
   zh: 81320ce118977c65
@@ -99,8 +102,8 @@
   en: 5eb30cfb410d52c0
   zh: da56365b8ab896da
 /deepseek-ai-dsh-session/known-limitations-and-deferred-work:
-  en: daaf56dda2bcaff1
-  zh: 7d24de2deb1c5dc5
+  en: 45afe96a4e252db9
+  zh: 920bcc011823817b
 /deepseek-ai-dsh-session/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -63,6 +63,18 @@ Append, seed/restore, and event adoption/snapshot reject any `header.system` and
 
 Session log positions use two numeric types. `SessionSeq` identifies an existing event or inclusive event watermark; `SessionLogOffset` identifies a gap, prefix length, or read boundary and may equal the event count. `SessionSeqCursor` adds the `-1` “no event yet” value, while `OptionalSessionSeq` uses `null` when absence is data. The constructors validate non-negative safe integers, and the brands disappear at runtime, so durable JSON and wire values remain ordinary numbers.
 
+<a id="write-experimental-plugin-records"></a>
+
+### Write experimental plugin records
+
+`appendPluginRecord(session, type, data)` appends one plugin record for a package under `packages/experimental/`; the `verify-plugin-record-callers` check rejects any other production caller in this repository. Plugins outside this repository must not call it either, although no repository check can inspect them.
+
+Declare each record in `PluginRecordMap` through `@deepseek-ai/dsh-session/types`, with a description and an explicit payload type annotation in the owning experimental package's `src/`. Names use `plugin:<owner>/<record>`, where `owner` is the suffix of the package name `@deepseek-ai/dsh-experimental-<owner>`; for example, `plugin:pi-extensions/entry`. TypeScript checks each name and payload against its declaration; the writer's runtime JSON snapshot rejects values that cannot be preserved losslessly. Put extension-defined or other dynamic names inside the payload of a declared record.
+
+The [experimental persistence catalog](../../../docs/experimental-persistence-catalog.md) lists current plugin-record declarations with their owners, descriptions, payload type annotations, and source files. These declarations remain separate from `SessionEventMap`, expanded persistence schemas, released type history, and `KNOWN_SESSION_EVENT_TYPES`. Records carry `ignorable: true`: a build that does not recognize one retains and skips it on read. Records never enter the model-visible surface. Resume and fork carry them with the rest of the log; Session format migration keeps them on a best-effort basis.
+
+`pluginRecordOf(event)` returns an event as a record, or `undefined` for any other event; a `ctx.sessionProjections` unit that passes each event to it rebuilds plugin state on resume. Its `data` remains `unknown` even when the current map declares the name. The owner validates it before use because earlier builds can write different payloads, and the V3-to-V4 format edge can rename an unknown ignorable V3 event into the same `plugin:` namespace. Removing or renaming a declaration does not discard stored records. The [ignorable events decision](../../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md) owns the compatibility policy.
+
 ### Fork a session
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` copies an exact inclusive event prefix (default: the last event) from a live source. `buildForkSeed` in `dsh-session/fork` places an inherited marker after the copied events, adds missing error tool results only for the open step, and closes that step and turn with a `forked` reason. Closed steps and turns remain unchanged, including historical missing results. The marker and closers belong to the child; `inheritedEventCount` counts only the copied prefix.
@@ -188,7 +200,7 @@ Logging causes no invalidation, and exact reconstruction preserves request-prefi
 These limits define when the session store needs special care. They are current package constraints, not a task backlog.
 
 - **Live-source Store API** — persisted-but-unloaded sources use the Host observation path. Fork closes only the open tail and does not repair missing results in previously closed steps.
-- **`SESSION_FORMAT_VERSION` names the [current logical representation](../../../docs/session-format-status.md)** — the current reader rejects retired `header.system` and validates `system/message` payloads and protected-head rewrites. Historical headers and events belong to adjacent format packages; the [adjacent migration chain](../../session/session-format-catalog/README.md) converts supported history before constructing `Session`, and the write-open path publishes only the current-format successor. Equal-version unknown events require the envelope's explicit `ignorable` marker, which does not promise safe structural migration ([mechanism](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md)).
+- **`SESSION_FORMAT_VERSION` names the [current logical representation](../../../docs/session-format-status.md)** — the current reader rejects retired `header.system` and validates `system/message` payloads and protected-head rewrites. Historical headers and events belong to adjacent format packages; the [adjacent migration chain](../../session/session-format-catalog/README.md) converts supported history before constructing `Session`, and the write-open path publishes only the current-format successor. Equal-version unknown events require the envelope's explicit `ignorable` marker, which does not promise safe structural migration ([mechanism](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md)). [Reader compatibility](../../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md) determines whether a change needs a version increase.
 - **`TurnEndReasonMap` omits the ACP-named `refusal` / `max_turn_requests` variants** — producer-gated: they land when an adapter or the loop first emits them.
 - **No session tree beyond fork** — a pi-style entry tree over branched sessions is deferred unless a consumer needs more than boundary-based forking.
 

package/README.zh.md

@@ -63,6 +63,18 @@ session.deriveMessages()         // the derived model history
 
 会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位；`SessionLogOffset` 标识间隙、前缀长度或读取边界，并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值，`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数，brand 在运行时会被擦除，因此持久 JSON 与 wire 值仍是普通数字。
 
+<a id="write-experimental-plugin-records"></a>
+
+### 写入实验性插件记录
+
+`appendPluginRecord(session, type, data)` 为 `packages/experimental/` 下的包追加一条插件记录；`verify-plugin-record-callers` 检查拒绝本仓库中任何其他生产调用方。本仓库之外的插件同样不得调用它，尽管仓库检查无法检查它们。
+
+在所属实验性包的 `src/` 中，通过 `@deepseek-ai/dsh-session/types` 的 `PluginRecordMap` 为每条记录声明描述与显式 payload 类型注解。名称使用 `plugin:<owner>/<record>`，其中 `owner` 是包名 `@deepseek-ai/dsh-experimental-<owner>` 的后缀；例如 `plugin:pi-extensions/entry`。TypeScript 按声明检查每个名称与 payload；写入方运行时的 JSON 快照拒绝无法无损保留的值。扩展自定义名称或其他动态名称放在已声明记录的 payload 中。
+
+[实验性持久化目录](../../../docs/experimental-persistence-catalog.zh.md)列出当前插件记录声明及其所属包、描述、payload 类型注解与源文件。这些声明与 `SessionEventMap`、展开的持久化 schema、已发布类型历史及 `KNOWN_SESSION_EVENT_TYPES` 分开。记录带有 `ignorable: true`：不认识某条记录的构建在读取时保留并跳过它。记录从不进入模型可见的 surface。resume 与 fork 随日志其余部分一起携带它们；Session 格式迁移以尽力而为的方式保留它们。
+
+`pluginRecordOf(event)` 把事件作为记录返回，对其他任何事件返回 `undefined`；把每个事件都交给它的 `ctx.sessionProjections` 单元在 resume 时重建插件状态。即使当前映射声明了该名称，其 `data` 仍为 `unknown`。所属包在使用前校验数据，因为早先构建可能写入不同的 payload，V3-to-V4 格式迁移边也可能把未知的 ignorable V3 事件改名放入同一个 `plugin:` 命名空间。删除或重命名声明不会丢弃已存记录。[ignorable 事件决策](../../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.zh.md)定义兼容性策略。
+
 ### 派生会话的 fork
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` 从实时源会话复制包含切点的精确事件前缀（默认：最后一个事件）。`dsh-session/fork` 的 `buildForkSeed` 在复制事件之后放置继承标记，仅为开放步骤补缺失的错误工具结果，并以 `forked` 原因关闭步骤和轮次。已关闭的步骤与轮次保持原样，包括历史缺失结果。标记和结束事件属于子会话；`inheritedEventCount` 只统计复制的前缀。
@@ -188,7 +200,7 @@ session.deriveMessages()         // the derived model history
 这些限制说明会话存储何时需要特别留意。它们是当前包约束，不是任务积压。
 
 - **Store API 仅接受活跃源会话** — 已持久化但未加载的源会话通过 Host 观察路径处理。Fork 仅闭合开放尾部，不修复先前已闭合步骤中缺失的结果。
-- **`SESSION_FORMAT_VERSION` 命名[当前逻辑表示](../../../docs/session-format-status.zh.md)**——当前读取器拒绝已退役的 `header.system`，并校验 `system/message` 载荷与受保护头节点的重写。历史 header 与事件归相邻格式包所有；[相邻迁移链](../../session/session-format-catalog/README.zh.md)在构造 `Session` 前转换受支持的历史，写打开只发布当前格式的后继代际。同版本未知事件要求信封显式带有 `ignorable` 标记，但这不保证结构迁移的安全性（[机制](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md)）。
+- **`SESSION_FORMAT_VERSION` 命名[当前逻辑表示](../../../docs/session-format-status.zh.md)**——当前读取器拒绝已退役的 `header.system`，并校验 `system/message` 载荷与受保护头节点的重写。历史 header 与事件归相邻格式包所有；[相邻迁移链](../../session/session-format-catalog/README.zh.md)在构造 `Session` 前转换受支持的历史，写打开只发布当前格式的后继代际。同版本未知事件要求信封显式带有 `ignorable` 标记，但这不保证结构迁移的安全性（[机制](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md)）。[读取器兼容性](../../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.zh.md)决定变更是否需要升版本。
 - **`TurnEndReasonMap` 不含 ACP（Agent Client Protocol）命名的 `refusal`／`max_turn_requests` 变体**：受生产方约束；只有当适配器或循环首次产生这些变体时才加入。
 - **fork 之外没有会话树**：基于分支会话的 pi 风格条目树被推迟，除非消费方需要超越基于边界的 forking 的能力。
 

package/lib/index.js

@@ -38,20 +38,20 @@ function SessionLogOffset(value) {
 * event-body read composes the build-static adjacent chain and publishes only
 * this final generation before constructing a Session.
 *
-* The version is a single monotonic integer with no major/minor split. Whether
-* a bump is needed is decided by what the WRITER emits, never by what a newer
-* reader can accept: bump exactly when an older runtime could no longer handle
-* a new log with full semantic correctness ("parses without error" is not
-* correctness — silently skipping content that shapes reconstruction is a
-* wrong read). Only structural changes reach that bar: the header shape, the
-* {@link SessionEvent} envelope, core event semantics, or the surface
-* mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
-* Adding an ordinary event type does not bump — the per-event
-* {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
-* in doubt, bump: a near-identity upgrade step is almost free, a missed bump
-* makes older runtimes read new logs wrong silently. The released migration,
-* immutable prior-generation, and current fast-path rules are recorded in
-* `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
+* The version is a single monotonic integer with no major/minor split. Retain
+* it when older readers resume correctly, preserve safely ignorable records,
+* or refuse required features before execution, mutation, or tail repair.
+* New readers must preserve historical meanings, including logs mixing old
+* and new record representations. Bump when an existing discriminator cannot
+* prevent unsafe interpretation; a structural difference alone is insufficient.
+* Unknown fields and values require evidence of the released reader's actual
+* admission behavior. The per-event {@link SessionEvent.ignorable} marker
+* governs unknown event types, not arbitrary nested payload changes.
+* Same-version readers retain earlier representations: the adjacent migration
+* chain does not run when stored and current versions match. A subsequent
+* migration must account for all supported representations of its source.
+* Compatibility review and the retained migration obligations are recorded in
+* `.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md`.
 */
 const SESSION_FORMAT_VERSION = 4;
 //#endregion
@@ -135,6 +135,7 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"turn/start",
 	"user/message",
 	"web/deepseek-search-llm-request",
+	"working-directory/change",
 	"workspace/changes"
 ]);
 /** Event types whose model-visible effects require an explicit pure interpreter. */
@@ -1238,6 +1239,79 @@ function invokeContainedSessionObservers(ctx, name, id, args, callbacks) {
 /** Store attachment for the append path; module-private to keep Session store-agnostic publicly. */
 const attachments = /* @__PURE__ */ new WeakMap();
 /**
+* Grammar of a {@link PluginRecordType}: `plugin:` followed by
+* slash-separated segments of lowercase letters, digits, `.`, `_`, and `-`,
+* each segment starting with a letter or digit.
+*/
+const PLUGIN_RECORD_TYPE = /^plugin:[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/u;
+/**
+* Whether one event type name follows the plugin record grammar.
+* @param type - an event type name.
+* @returns whether the name is a {@link PluginRecordType}.
+*/
+function isPluginRecordType(type) {
+	return PLUGIN_RECORD_TYPE.test(type);
+}
+/**
+* Type one constructed plugin record as a log event after checking its type
+* against the plugin record grammar. A restored Session already holds events
+* whose types are outside `SessionEventMap` when they are marked ignorable;
+* a plugin record is such an event.
+* @param value - the frozen record envelope built by {@link Session}.
+* @throws when the record type is outside the plugin record grammar.
+*/
+function assertPluginRecordEvent(value) {
+	const { type } = value;
+	if (!isPluginRecordType(type)) throw new Error(`plugin record type "${type}" must be "plugin:" followed by lowercase slash-separated segments`);
+}
+/** Module-private access to {@link Session}'s record commit, assigned once by its static block. */
+let commitPluginRecord;
+/**
+* Append one experimental plugin record: an event marked `ignorable` whose
+* type is declared in {@link PluginRecordMap}, outside {@link SessionEventMap}.
+* The plugin record catalog lists it separately from released event schemas.
+* A reader that does not recognize the type retains and skips the record, which never
+* enters the model-visible surface, and fork and resume carry it with the rest
+* of the log. A Session format migration retains records on a best-effort
+* basis, so a record holds plugin-owned state that its owner can lose without
+* changing how the rest of the log is interpreted.
+*
+* Only production source under `packages/experimental/` may call this
+* function; the `verify-plugin-record-callers` gate rejects any other
+* production caller in this repository. Read records back with
+* {@link pluginRecordOf}.
+* @param session - the Session whose log receives the record.
+* @param type - declared record name: `plugin:` followed by slash-separated
+*   segments of lowercase letters, digits, `.`, `_`, and `-`, each starting
+*   with a letter or digit.
+* @param data - JSON payload, snapshotted before it enters the log.
+* @returns the sequence number of the committed record.
+* @throws when `type` is outside that grammar, when `data` is not losslessly
+*   JSON-serializable, or when the call reenters another append's publication;
+*   a rejected record does not change the log.
+*/
+function appendPluginRecord(session, type, data) {
+	return commitPluginRecord(session, type, data);
+}
+/**
+* Read one committed event as a plugin record. The V3-to-V4 format edge also
+* renames each unknown ignorable V3 event into the `plugin:` namespace, so an
+* owner names its records under its own package name and validates `data`.
+* @param event - any committed Session event, live or restored.
+* @returns the record, or undefined when the event is not an ignorable event
+*   whose type follows the plugin record grammar.
+*/
+function pluginRecordOf(event) {
+	const type = event.type;
+	if (event.ignorable !== true || !isPluginRecordType(type)) return void 0;
+	return {
+		type,
+		seq: event.seq,
+		time: event.time,
+		data: event.data
+	};
+}
+/**
 * An event-sourced session: an append-only log of {@link SessionEvent}s.
 *
 * Plain class (not a Service) — create live instances via
@@ -1448,8 +1522,7 @@ var Session = class Session {
 		if (dataSnapshot === void 0) throw new Error(`session event "${type}" carries non-JSON-serializable data`);
 		const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata);
 		if (surfaceMetadataSnapshot === void 0) throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`);
-		const entry = attachments.get(this);
-		if (entry?.appending) throw new Error("session append cannot reenter while another append is being published");
+		const entry = this.publicationEntry();
 		const event = deepFreeze({
 			type,
 			seq: SessionSeq(this.log.length),
@@ -1458,6 +1531,50 @@ var Session = class Session {
 			...surfaceMetadataSnapshot
 		});
 		validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
+		this.commit(event, entry);
+		return event;
+	}
+	static {
+		commitPluginRecord = (session, type, data) => session.#appendRecord(type, data);
+	}
+	/**
+	* Commit one plugin record; {@link appendPluginRecord} is the only caller.
+	* @param type - record type, checked against the plugin record grammar.
+	* @param data - JSON payload, snapshotted before it enters the log.
+	* @returns the record's sequence number.
+	*/
+	#appendRecord(type, data) {
+		const dataSnapshot = snapshotJsonValue(data);
+		if (dataSnapshot === void 0) throw new Error(`plugin record "${type}" carries non-JSON-serializable data`);
+		const entry = this.publicationEntry();
+		const record = deepFreeze({
+			type,
+			seq: SessionSeq(this.log.length),
+			time: Date.now(),
+			data: dataSnapshot,
+			ignorable: true
+		});
+		assertPluginRecordEvent(record);
+		this.commit(record, entry);
+		return record.seq;
+	}
+	/**
+	* Read the store attachment for one append, refusing an append that
+	* reenters while another append is being published.
+	* @returns the attachment, or undefined for a detached Session.
+	*/
+	publicationEntry() {
+		const entry = attachments.get(this);
+		if (entry?.appending) throw new Error("session append cannot reenter while another append is being published");
+		return entry;
+	}
+	/**
+	* Accept one frozen candidate at the next sequence number, enter it into the
+	* log, and notify `session/event` observers with per-listener containment.
+	* @param event - the candidate built at the current log length.
+	* @param entry - the attachment read before the candidate was built.
+	*/
+	commit(event, entry) {
 		this.surfaceManager.validateNext(event);
 		if (entry !== void 0) entry.appending = true;
 		try {
@@ -1471,7 +1588,6 @@ var Session = class Session {
 			this.log.push(event);
 			this.eventsSnapshot = void 0;
 			if (callbacks !== void 0 && entry !== void 0) invokeContainedSessionObservers(entry.emitCtx, "session/event", entry.id, callbackArgs, callbacks);
-			return event;
 		} finally {
 			if (entry !== void 0) {
 				entry.appending = false;
@@ -1930,4 +2046,4 @@ var SessionStore = class extends Service {
 	}
 };
 //#endregion
-export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, ToolCallRecovery, adoptSessionEvent, buildForkSeed, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, snapshotSessionEvent };
+export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, ToolCallRecovery, adoptSessionEvent, appendPluginRecord, buildForkSeed, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, pluginRecordOf, snapshotSessionEvent };

package/lib/types/index.d.ts

@@ -10,7 +10,7 @@ import type { Scoped } from '@deepseek-ai/dsh-scope';
 import type { Message } from '@deepseek-ai/dsh-llm';
 import { SessionLogOffset, SessionSeq } from './types.ts';
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol';
-import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts';
+import type { CreateSessionOptions, EpochHeader, PluginRecord, PluginRecordMap, PluginRecordType, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts';
 import type { SessionSurface, SessionMessageProjection } from './surface.ts';
 import type { ToolHistory } from '@deepseek-ai/dsh-llm';
 export { buildForkSeed } from './fork.ts';
@@ -90,6 +90,40 @@ export declare function adoptSessionEvent<T extends SessionEvent>(event: T): T;
  * @returns a detached event snapshot with a validated, deeply frozen message.
  */
 export declare function snapshotSessionEvent<T extends SessionEvent>(event: T): T;
+/**
+ * Append one experimental plugin record: an event marked `ignorable` whose
+ * type is declared in {@link PluginRecordMap}, outside {@link SessionEventMap}.
+ * The plugin record catalog lists it separately from released event schemas.
+ * A reader that does not recognize the type retains and skips the record, which never
+ * enters the model-visible surface, and fork and resume carry it with the rest
+ * of the log. A Session format migration retains records on a best-effort
+ * basis, so a record holds plugin-owned state that its owner can lose without
+ * changing how the rest of the log is interpreted.
+ *
+ * Only production source under `packages/experimental/` may call this
+ * function; the `verify-plugin-record-callers` gate rejects any other
+ * production caller in this repository. Read records back with
+ * {@link pluginRecordOf}.
+ * @param session - the Session whose log receives the record.
+ * @param type - declared record name: `plugin:` followed by slash-separated
+ *   segments of lowercase letters, digits, `.`, `_`, and `-`, each starting
+ *   with a letter or digit.
+ * @param data - JSON payload, snapshotted before it enters the log.
+ * @returns the sequence number of the committed record.
+ * @throws when `type` is outside that grammar, when `data` is not losslessly
+ *   JSON-serializable, or when the call reenters another append's publication;
+ *   a rejected record does not change the log.
+ */
+export declare function appendPluginRecord<K extends Extract<keyof PluginRecordMap, PluginRecordType>>(session: Session, type: K, data: NoInfer<PluginRecordMap[K]>): SessionSeq;
+/**
+ * Read one committed event as a plugin record. The V3-to-V4 format edge also
+ * renames each unknown ignorable V3 event into the `plugin:` namespace, so an
+ * owner names its records under its own package name and validates `data`.
+ * @param event - any committed Session event, live or restored.
+ * @returns the record, or undefined when the event is not an ignorable event
+ *   whose type follows the plugin record grammar.
+ */
+export declare function pluginRecordOf(event: SessionEvent): PluginRecord | undefined;
 /**
  * An event-sourced session: an append-only log of {@link SessionEvent}s.
  *
@@ -99,6 +133,7 @@ export declare function snapshotSessionEvent<T extends SessionEvent>(event: T):
  * @typert object
  */
 export declare class Session {
+    #private;
     private log;
     /** Single incremental owner of surface acceptance and projection state. */
     private readonly surfaceManager;
@@ -240,6 +275,19 @@ export declare class Session {
      *   rejects before the log changes.
      */
     append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []): SessionEvent<T>;
+    /**
+     * Read the store attachment for one append, refusing an append that
+     * reenters while another append is being published.
+     * @returns the attachment, or undefined for a detached Session.
+     */
+    private publicationEntry;
+    /**
+     * Accept one frozen candidate at the next sequence number, enter it into the
+     * log, and notify `session/event` observers with per-listener containment.
+     * @param event - the candidate built at the current log length.
+     * @param entry - the attachment read before the candidate was built.
+     */
+    private commit;
     /** Cached fold of the request-header events — see {@link requestHeader}. */
     private headerFold;
     /** Log position (events consumed) the header fold has reached. */

package/lib/types/index.js

@@ -324,6 +324,77 @@ function invokeContainedSessionObservers(ctx, name, id, args, callbacks) {
 }
 /** Store attachment for the append path; module-private to keep Session store-agnostic publicly. */
 const attachments = new WeakMap();
+/**
+ * Grammar of a {@link PluginRecordType}: `plugin:` followed by
+ * slash-separated segments of lowercase letters, digits, `.`, `_`, and `-`,
+ * each segment starting with a letter or digit.
+ */
+const PLUGIN_RECORD_TYPE = /^plugin:[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/u;
+/**
+ * Whether one event type name follows the plugin record grammar.
+ * @param type - an event type name.
+ * @returns whether the name is a {@link PluginRecordType}.
+ */
+function isPluginRecordType(type) {
+    return PLUGIN_RECORD_TYPE.test(type);
+}
+/**
+ * Type one constructed plugin record as a log event after checking its type
+ * against the plugin record grammar. A restored Session already holds events
+ * whose types are outside `SessionEventMap` when they are marked ignorable;
+ * a plugin record is such an event.
+ * @param value - the frozen record envelope built by {@link Session}.
+ * @throws when the record type is outside the plugin record grammar.
+ */
+function assertPluginRecordEvent(value) {
+    const { type } = value;
+    if (!isPluginRecordType(type)) {
+        throw new Error(`plugin record type "${type}" must be "plugin:" followed by lowercase slash-separated segments`);
+    }
+}
+/** Module-private access to {@link Session}'s record commit, assigned once by its static block. */
+let commitPluginRecord;
+/**
+ * Append one experimental plugin record: an event marked `ignorable` whose
+ * type is declared in {@link PluginRecordMap}, outside {@link SessionEventMap}.
+ * The plugin record catalog lists it separately from released event schemas.
+ * A reader that does not recognize the type retains and skips the record, which never
+ * enters the model-visible surface, and fork and resume carry it with the rest
+ * of the log. A Session format migration retains records on a best-effort
+ * basis, so a record holds plugin-owned state that its owner can lose without
+ * changing how the rest of the log is interpreted.
+ *
+ * Only production source under `packages/experimental/` may call this
+ * function; the `verify-plugin-record-callers` gate rejects any other
+ * production caller in this repository. Read records back with
+ * {@link pluginRecordOf}.
+ * @param session - the Session whose log receives the record.
+ * @param type - declared record name: `plugin:` followed by slash-separated
+ *   segments of lowercase letters, digits, `.`, `_`, and `-`, each starting
+ *   with a letter or digit.
+ * @param data - JSON payload, snapshotted before it enters the log.
+ * @returns the sequence number of the committed record.
+ * @throws when `type` is outside that grammar, when `data` is not losslessly
+ *   JSON-serializable, or when the call reenters another append's publication;
+ *   a rejected record does not change the log.
+ */
+export function appendPluginRecord(session, type, data) {
+    return commitPluginRecord(session, type, data);
+}
+/**
+ * Read one committed event as a plugin record. The V3-to-V4 format edge also
+ * renames each unknown ignorable V3 event into the `plugin:` namespace, so an
+ * owner names its records under its own package name and validates `data`.
+ * @param event - any committed Session event, live or restored.
+ * @returns the record, or undefined when the event is not an ignorable event
+ *   whose type follows the plugin record grammar.
+ */
+export function pluginRecordOf(event) {
+    const type = event.type;
+    if (event.ignorable !== true || !isPluginRecordType(type))
+        return undefined;
+    return { type, seq: event.seq, time: event.time, data: event.data };
+}
 /**
  * An event-sourced session: an append-only log of {@link SessionEvent}s.
  *
@@ -578,10 +649,7 @@ export class Session {
         if (surfaceMetadataSnapshot === undefined) {
             throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`);
         }
-        const entry = attachments.get(this);
-        if (entry?.appending) {
-            throw new Error('session append cannot reenter while another append is being published');
-        }
+        const entry = this.publicationEntry();
         const event = deepFreeze({
             type,
             seq: SessionSeq(this.log.length),
@@ -590,6 +658,54 @@ export class Session {
             ...surfaceMetadataSnapshot,
         });
         validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
+        this.commit(event, entry);
+        return event;
+    }
+    static {
+        commitPluginRecord = (session, type, data) => session.#appendRecord(type, data);
+    }
+    /**
+     * Commit one plugin record; {@link appendPluginRecord} is the only caller.
+     * @param type - record type, checked against the plugin record grammar.
+     * @param data - JSON payload, snapshotted before it enters the log.
+     * @returns the record's sequence number.
+     */
+    #appendRecord(type, data) {
+        const dataSnapshot = snapshotJsonValue(data);
+        if (dataSnapshot === undefined) {
+            throw new Error(`plugin record "${type}" carries non-JSON-serializable data`);
+        }
+        const entry = this.publicationEntry();
+        const record = deepFreeze({
+            type,
+            seq: SessionSeq(this.log.length),
+            time: Date.now(),
+            data: dataSnapshot,
+            ignorable: true,
+        });
+        assertPluginRecordEvent(record);
+        this.commit(record, entry);
+        return record.seq;
+    }
+    /**
+     * Read the store attachment for one append, refusing an append that
+     * reenters while another append is being published.
+     * @returns the attachment, or undefined for a detached Session.
+     */
+    publicationEntry() {
+        const entry = attachments.get(this);
+        if (entry?.appending) {
+            throw new Error('session append cannot reenter while another append is being published');
+        }
+        return entry;
+    }
+    /**
+     * Accept one frozen candidate at the next sequence number, enter it into the
+     * log, and notify `session/event` observers with per-listener containment.
+     * @param event - the candidate built at the current log length.
+     * @param entry - the attachment read before the candidate was built.
+     */
+    commit(event, entry) {
         this.surfaceManager.validateNext(event);
         if (entry !== undefined)
             entry.appending = true;
@@ -604,7 +720,6 @@ export class Session {
             if (callbacks !== undefined && entry !== undefined) {
                 invokeContainedSessionObservers(entry.emitCtx, 'session/event', entry.id, callbackArgs, callbacks);
             }
-            return event;
         }
         finally {
             if (entry !== undefined) {

package/lib/types/known-event-types.js

@@ -77,6 +77,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'turn/start',
     'user/message',
     'web/deepseek-search-llm-request',
+    'working-directory/change',
     'workspace/changes',
 ]);
 /** Event types whose model-visible effects require an explicit pure interpreter. */

package/lib/types/types.d.ts

@@ -36,20 +36,20 @@ export type OptionalSessionSeq = SessionSeq | null;
  * event-body read composes the build-static adjacent chain and publishes only
  * this final generation before constructing a Session.
  *
- * The version is a single monotonic integer with no major/minor split. Whether
- * a bump is needed is decided by what the WRITER emits, never by what a newer
- * reader can accept: bump exactly when an older runtime could no longer handle
- * a new log with full semantic correctness ("parses without error" is not
- * correctness — silently skipping content that shapes reconstruction is a
- * wrong read). Only structural changes reach that bar: the header shape, the
- * {@link SessionEvent} envelope, core event semantics, or the surface
- * mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
- * Adding an ordinary event type does not bump — the per-event
- * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
- * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
- * makes older runtimes read new logs wrong silently. The released migration,
- * immutable prior-generation, and current fast-path rules are recorded in
- * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
+ * The version is a single monotonic integer with no major/minor split. Retain
+ * it when older readers resume correctly, preserve safely ignorable records,
+ * or refuse required features before execution, mutation, or tail repair.
+ * New readers must preserve historical meanings, including logs mixing old
+ * and new record representations. Bump when an existing discriminator cannot
+ * prevent unsafe interpretation; a structural difference alone is insufficient.
+ * Unknown fields and values require evidence of the released reader's actual
+ * admission behavior. The per-event {@link SessionEvent.ignorable} marker
+ * governs unknown event types, not arbitrary nested payload changes.
+ * Same-version readers retain earlier representations: the adjacent migration
+ * chain does not run when stored and current versions match. A subsequent
+ * migration must account for all supported representations of its source.
+ * Compatibility review and the retained migration obligations are recorded in
+ * `.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md`.
  */
 export declare const SESSION_FORMAT_VERSION = 4;
 /**
@@ -510,6 +510,37 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
         sourceEventSeqs?: never;
     });
 }[T];
+/**
+ * Event type of an experimental plugin record: `plugin:` followed by
+ * slash-separated segments of lowercase letters, digits, `.`, `_`, and `-`,
+ * each starting with a letter or digit. A record type is never a
+ * {@link SessionEventMap} member.
+ */
+export type PluginRecordType = `plugin:${string}`;
+/**
+ * Payloads written by experimental packages, keyed by their `plugin:` record
+ * names. Packages augment this map to type writes and enter the current plugin
+ * record catalog; these declarations do not enter {@link SessionEventMap} or
+ * released persistence schemas. Stored records still require owner validation.
+ */
+export interface PluginRecordMap {
+}
+/**
+ * One committed experimental plugin record, read from the log by
+ * `pluginRecordOf`. The record's owner validates `data` before use, because a
+ * restored record carries whatever JSON an earlier build of its owner wrote,
+ * or a V3 event that a format migration renamed into the `plugin:` namespace held.
+ */
+export interface PluginRecord {
+    /** The record type, chosen by the owning plugin. */
+    readonly type: PluginRecordType;
+    /** The record's position in the Session log. */
+    readonly seq: SessionSeq;
+    /** Unix epoch milliseconds at append. */
+    readonly time: number;
+    /** The JSON payload as committed. */
+    readonly data: unknown;
+}
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
         /** The named Session does not exist; produced by every layer that resolves a SessionId. */

package/lib/types/types.js

@@ -36,20 +36,20 @@ export function SessionLogOffset(value) {
  * event-body read composes the build-static adjacent chain and publishes only
  * this final generation before constructing a Session.
  *
- * The version is a single monotonic integer with no major/minor split. Whether
- * a bump is needed is decided by what the WRITER emits, never by what a newer
- * reader can accept: bump exactly when an older runtime could no longer handle
- * a new log with full semantic correctness ("parses without error" is not
- * correctness — silently skipping content that shapes reconstruction is a
- * wrong read). Only structural changes reach that bar: the header shape, the
- * {@link SessionEvent} envelope, core event semantics, or the surface
- * mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
- * Adding an ordinary event type does not bump — the per-event
- * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
- * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
- * makes older runtimes read new logs wrong silently. The released migration,
- * immutable prior-generation, and current fast-path rules are recorded in
- * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
+ * The version is a single monotonic integer with no major/minor split. Retain
+ * it when older readers resume correctly, preserve safely ignorable records,
+ * or refuse required features before execution, mutation, or tail repair.
+ * New readers must preserve historical meanings, including logs mixing old
+ * and new record representations. Bump when an existing discriminator cannot
+ * prevent unsafe interpretation; a structural difference alone is insufficient.
+ * Unknown fields and values require evidence of the released reader's actual
+ * admission behavior. The per-event {@link SessionEvent.ignorable} marker
+ * governs unknown event types, not arbitrary nested payload changes.
+ * Same-version readers retain earlier representations: the adjacent migration
+ * chain does not run when stored and current versions match. A subsequent
+ * migration must account for all supported representations of its source.
+ * Compatibility review and the retained migration obligations are recorded in
+ * `.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md`.
  */
 export const SESSION_FORMAT_VERSION = 4;
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.2.1-alpha.1",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -40,18 +40,18 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-typert-registry": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "0.2.1-alpha.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1"
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.2"
   }
 }