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

package/lib/types/index.js

@@ -11,7 +11,7 @@ import { brandString } from '@deepseek-ai/dsh-brand';
 import { assertNever, deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
-import { deriveEventMessage, SurfaceManager } from "./surface.js";
+import { deriveEventMessage, SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from "./surface.js";
 import { foldRequestHeader } from "./request-header.js";
 export * from "./types.js";
 export { SessionPreparation } from "./preparation.js";
@@ -91,13 +91,17 @@ function snapshotSessionHeader(id, source) {
  * Use {@link snapshotSessionEvent} when exclusive ownership is not guaranteed.
  * @param event - exclusively owned event imported across a trusted boundary.
  * @returns the same event object with a validated, deeply frozen message.
+ * @throws when event-local surface metadata, request-header fields, or message invariants are invalid; history relations are not checked.
  */
 export function adoptSessionEvent(event) {
+    validateSessionEventData(event, `session event at seq ${event.seq}`);
+    validateSurfaceMetadata(event);
     assertMessageEventShape(event, `session event at seq ${event.seq}`);
     switch (event.type) {
         case 'user/message':
             deepFreeze(event.data);
             break;
+        case 'system/message':
         case 'assistant/message':
         case 'tool/result':
             deepFreeze(event.data.message);
@@ -118,6 +122,9 @@ export function snapshotSessionEvent(event) {
 }
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value, index) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`seed event at index ${index} has an invalid event envelope`);
+    }
     const event = value;
     for (const key in event) {
         switch (key) {
@@ -143,8 +150,10 @@ function assertSessionEventEnvelope(value, index) {
         || (event['ignorable'] !== undefined && event['ignorable'] !== true)) {
         throw new Error(`seed event at index ${index} has an invalid event envelope`);
     }
+    validateSessionEventData(event, `seed ${type} at index ${index}`);
     switch (type) {
         case 'request/header':
+        case 'system/message':
         case 'user/message':
         case 'assistant/attempt':
         case 'assistant/message':
@@ -160,11 +169,8 @@ function assertCurrentLlmShape(event, index) {
         ? data
         : undefined;
     if (event['type'] === 'request/header') {
-        const header = record?.['header'];
-        const headerRecord = typeof header === 'object' && header !== null && !Array.isArray(header)
-            ? header
-            : undefined;
-        const config = headerRecord?.['config'];
+        const headerRecord = record?.['header'];
+        const config = headerRecord['config'];
         if (!hasProviderModel(config))
             throw new Error(`seed request/header at index ${index} lacks provider/model`);
         const configRecord = config;
@@ -173,7 +179,7 @@ function assertCurrentLlmShape(event, index) {
             && (typeof reasoningEffort !== 'string' || reasoningEffort.length === 0)) {
             throw new Error(`seed request/header at index ${index} has an invalid reasoningEffort`);
         }
-        assertAdapterDefaults(headerRecord?.['adapterDefaults'], configRecord, index);
+        assertAdapterDefaults(headerRecord['adapterDefaults'], configRecord, index);
         const reason = record?.['reason'];
         if (reason !== 'initial' && reason !== 'resume' && reason !== 'change' && reason !== 'series') {
             throw new Error(`seed request/header at index ${index} has an invalid reason`);
@@ -187,8 +193,7 @@ function assertCurrentLlmShape(event, index) {
         assertAssistantSettlementShape(record, type, index);
         return;
     }
-    if (type !== 'user/message' && type !== 'assistant/message'
-        && type !== 'tool/result')
+    if (!isMessageEventType(type))
         return;
     assertMessageEventShape(event, `seed ${type} at index ${index}`);
     if (type === 'assistant/message') {
@@ -221,11 +226,21 @@ function assertAdapterDefaults(value, config, index) {
         throw new Error(`seed request/header at index ${index} has invalid adapterDefaults`);
     }
 }
+/** The four surface event types whose payload carries an identified message. */
+function isMessageEventType(type) {
+    return type === 'system/message' || type === 'user/message'
+        || type === 'assistant/message' || type === 'tool/result';
+}
+const MESSAGE_ROLE_BY_TYPE = {
+    'system/message': 'system',
+    'user/message': 'user',
+    'assistant/message': 'assistant',
+    'tool/result': 'user',
+};
 /** Validate only the event-specific invariants needed to safely replay a message. */
 function assertMessageEventShape(event, subject) {
     const type = event['type'];
-    if (type !== 'user/message' && type !== 'assistant/message'
-        && type !== 'tool/result')
+    if (!isMessageEventType(type))
         return;
     const data = event['data'];
     const record = typeof data === 'object' && data !== null
@@ -238,7 +253,7 @@ function assertMessageEventShape(event, subject) {
         throw new Error(`${subject} lacks an identified message`);
     }
     const messageRecord = message;
-    const expectedRole = type === 'assistant/message' ? 'assistant' : 'user';
+    const expectedRole = MESSAGE_ROLE_BY_TYPE[type];
     if (messageRecord['role'] !== expectedRole) {
         throw new Error(`${subject} message must have role "${expectedRole}"`);
     }
@@ -252,6 +267,13 @@ function assertMessageEventShape(event, subject) {
         throw new Error(`${subject} message has invalid content`);
     }
     const sourceRecord = source;
+    if (type === 'system/message') {
+        if (sourceRecord['kind'] !== 'plugin' || typeof sourceRecord['plugin'] !== 'string'
+            || sourceRecord['plugin'] === '') {
+            throw new Error(`${subject} message must have plugin source`);
+        }
+        return;
+    }
     if (type === 'assistant/message') {
         if (sourceRecord['kind'] !== 'model' || !hasProviderModel(sourceRecord)) {
             throw new Error(`${subject} message must have model source`);
@@ -519,6 +541,7 @@ export class Session {
      *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
      *   circular reference, sparse array, or an exotic object such as
      *   Map/Set/Date/class instance), or when the candidate violates the
+     *   request-header empty-field or tool-error consistency rules, or the
      *   canonical surface contract (marker shape and eligibility, unique
      *   earlier source-event references, positional replacement validity, and complete
      *   shadowed-node coverage). One iterative pass reads, validates, and
@@ -554,6 +577,7 @@ export class Session {
             data: dataSnapshot,
             ...surfaceMetadataSnapshot,
         });
+        validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`);
         this.surfaceManager.validateNext(event);
         if (entry !== undefined)
             entry.appending = true;

package/lib/types/invariant.js

@@ -103,6 +103,10 @@ function validateEvent(trace, event, fail) {
             pendingCalls = { kind: 'delete', callId };
             break;
         }
+        case 'system/message': {
+            requireOpenStep(trace, 'system/message', event.data.turn, event.data.step, fail);
+            break;
+        }
         case 'user/message':
             break;
         case 'session/end-seed':

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

@@ -55,6 +55,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'step/start',
     'subagent/descriptor',
     'subagent/model-selection-policy',
+    'system/message',
     'team/member',
     'team/message/delivered',
     'team/message/queued',
@@ -65,8 +66,8 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'tool-workflow/run-end',
     'tool-workflow/run-start',
     'tool/call',
-    'tool/code-dispatch',
-    'tool/code-dispatch-start',
+    'tool/ptc-dispatch',
+    'tool/ptc-dispatch-start',
     'tool/result',
     'turn/end',
     'turn/start',

package/lib/types/request-header.d.ts

@@ -8,9 +8,9 @@
  */
 import type { EpochHeader, SessionEvent } from './types.ts';
 /**
- * Normalize a header to canonical form: an empty system prompt and empty tool
- * list become absent fields, matching how requests are built. Logging, folding,
- * and comparison use this one representation.
+ * Normalize a header to canonical form: an empty tool list becomes an absent
+ * field, matching how requests are built. Logging, folding, and comparison use
+ * this one representation.
  * @param header - the header to normalize (not mutated).
  * @returns the canonical header.
  */
@@ -19,7 +19,7 @@ export declare function canonicalHeader(header: EpochHeader): EpochHeader;
  * Field-wise equality over canonical headers. Tool schemas compare in order.
  * @param a - one canonical header.
  * @param b - the other.
- * @returns whether config, system, and tools all match.
+ * @returns whether config, adapter defaults, and tools all match.
  */
 export declare function headerEquals(a: EpochHeader, b: EpochHeader): boolean;
 /**

package/lib/types/request-header.js

@@ -8,9 +8,9 @@
  */
 import { callConfigEquals } from '@deepseek-ai/dsh-llm';
 /**
- * Normalize a header to canonical form: an empty system prompt and empty tool
- * list become absent fields, matching how requests are built. Logging, folding,
- * and comparison use this one representation.
+ * Normalize a header to canonical form: an empty tool list becomes an absent
+ * field, matching how requests are built. Logging, folding, and comparison use
+ * this one representation.
  * @param header - the header to normalize (not mutated).
  * @returns the canonical header.
  */
@@ -21,7 +21,6 @@ export function canonicalHeader(header) {
         ...adapterDefaults?.reasoningEffort === true || adapterDefaults?.maxTokens === true
             ? { adapterDefaults }
             : {},
-        ...header.system !== undefined && header.system.length > 0 ? { system: header.system } : {},
         ...header.tools !== undefined && header.tools.length > 0 ? { tools: header.tools } : {},
     };
 }
@@ -33,13 +32,12 @@ function sameSchema(a, b) {
  * Field-wise equality over canonical headers. Tool schemas compare in order.
  * @param a - one canonical header.
  * @param b - the other.
- * @returns whether config, system, and tools all match.
+ * @returns whether config, adapter defaults, and tools all match.
  */
 export function headerEquals(a, b) {
     if (!callConfigEquals(a.config, b.config)
         || a.adapterDefaults?.reasoningEffort !== b.adapterDefaults?.reasoningEffort
-        || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens
-        || a.system !== b.system)
+        || a.adapterDefaults?.maxTokens !== b.adapterDefaults?.maxTokens)
         return false;
     const at = a.tools ?? [];
     const bt = b.tools ?? [];

package/lib/types/surface.d.ts

@@ -13,7 +13,7 @@ import type { SessionEvent, SurfaceEvent, SurfaceOp } from './types.ts';
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
- * @returns true for one of the three message-producing event types.
+ * @returns true for one of the four message-producing event types.
  */
 export declare function isSurfaceEligibleType(type: string): boolean;
 /**
@@ -62,6 +62,14 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
  * @returns the derived message, or null when the event produces none.
  */
 export declare function deriveEventMessage(event: SessionEvent): Message | null;
+/**
+ * Reject noncanonical request-header fields and contradictory tool failure metadata.
+ * This does not validate complete event payloads or embedded provider streams.
+ * @param event - event whose locally related payload fields are inspected.
+ * @param subject - event location to include in validation errors.
+ * @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+ */
+export declare function validateSessionEventData(event: Pick<SessionEvent, 'type' | 'data'>, subject: string): void;
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
     /** Seq of the event that replaced the prior surface range. */
@@ -87,6 +95,14 @@ export interface SessionSurface {
     /** Monotonic count of committed positional replacements. */
     readonly replaceGeneration: number;
 }
+/**
+ * Validate one event's surface metadata without checking membership in a log or surface.
+ * @param event - event whose marker and source sequence values are inspected.
+ * Unknown ignorable records retain opaque metadata and never change the surface.
+ * @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+ * @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+ */
+export declare function validateSurfaceMetadata(event: SessionEvent): SurfaceOp | undefined;
 /**
  * Replay a complete session log through the canonical surface fold.
  * @param events - session events in contiguous seq order.

package/lib/types/surface.js

@@ -8,8 +8,10 @@
  * @module @deepseek-ai/dsh-session/surface
  */
 import { SessionLogOffset, SessionSeq } from "./types.js";
+import { KNOWN_SESSION_EVENT_TYPES } from "./known-event-types.js";
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
+    'system/message',
     'user/message',
     'assistant/message',
     'tool/result',
@@ -17,7 +19,7 @@ const SURFACE_EVENT_TYPES = new Set([
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
- * @returns true for one of the three message-producing event types.
+ * @returns true for one of the four message-producing event types.
  */
 export function isSurfaceEligibleType(type) {
     return SURFACE_EVENT_TYPES.has(type);
@@ -30,7 +32,8 @@ export function isSurfaceEligibleType(type) {
 export function isSurfaceEvent(event) {
     if (!SURFACE_EVENT_TYPES.has(event.type))
         return false;
-    return event.surfaceOp !== undefined;
+    const candidate = event;
+    return candidate.surfaceOp !== undefined;
 }
 /**
  * Narrow an event to an append-origin surface event: one that entered the
@@ -85,10 +88,13 @@ export function deriveEventMessage(event) {
         case 'user/message': {
             return event.data;
         }
+        // An empty-content message projects to no wire message. For
+        // system/message the node records "no system prompt" while keeping its
+        // surface position; for assistant/message the event exists only to host a
+        // max-tokens step's usage and must not inject a content-less assistant
+        // turn into the provider transcript.
+        case 'system/message':
         case 'assistant/message': {
-            // Skip an empty-content assistant/message: it exists only to host a
-            // max-tokens step's usage and must not inject a content-less assistant
-            // turn into the provider transcript.
             if (event.data.message.content.length === 0)
                 return null;
             return event.data.message;
@@ -102,6 +108,48 @@ export function deriveEventMessage(event) {
             return null;
     }
 }
+/** Whether a payload field is a JSON object rather than an array or scalar. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reject noncanonical request-header fields and contradictory tool failure metadata.
+ * This does not validate complete event payloads or embedded provider streams.
+ * @param event - event whose locally related payload fields are inspected.
+ * @param subject - event location to include in validation errors.
+ * @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+ */
+export function validateSessionEventData(event, subject) {
+    const data = event.data;
+    if (event.type === 'request/header') {
+        if (!isRecord(data))
+            throw new Error(`${subject} data must be an object`);
+        const header = data['header'];
+        if (!isRecord(header))
+            throw new Error(`${subject} header must be an object`);
+        if (Object.hasOwn(header, 'system'))
+            throw new Error(`${subject} must omit header.system; use system/message`);
+        if (Array.isArray(header['tools']) && header['tools'].length === 0) {
+            throw new Error(`${subject} must omit empty tools`);
+        }
+        const defaults = header['adapterDefaults'];
+        if (isRecord(defaults) && Object.keys(defaults).length === 0) {
+            throw new Error(`${subject} must omit empty adapterDefaults`);
+        }
+    }
+    else if (event.type === 'tool/result') {
+        if (!isRecord(data))
+            throw new Error(`${subject} data must be an object`);
+        if (data['error'] === undefined)
+            return;
+        const message = data['message'];
+        const content = isRecord(message) ? message['content'] : undefined;
+        const block = Array.isArray(content) ? content[0] : undefined;
+        if (!isRecord(block) || block['isError'] !== true) {
+            throw new Error(`${subject} error requires message content[0].isError === true`);
+        }
+    }
+}
 /** Create an empty surface fold state. */
 function createFoldState() {
     return { nodes: [], replaceGeneration: 0 };
@@ -118,16 +166,19 @@ function isReplaceOp(value) {
     const op = value;
     return Object.keys(op).length === 3
         && Object.hasOwn(op, 'op')
-        && Object.hasOwn(op, 'start')
-        && Object.hasOwn(op, 'end')
+        && Object.hasOwn(op, 'startSeq')
+        && Object.hasOwn(op, 'endSeq')
         && op['op'] === 'replace'
-        && isEventSeq(op['start'])
-        && isEventSeq(op['end']);
+        && isEventSeq(op['startSeq'])
+        && isEventSeq(op['endSeq']);
 }
 /** Validate event-local surface eligibility and return its operation. */
 function surfaceOpOf(event) {
     const raw = event;
     if (!isSurfaceEligibleType(event.type)) {
+        // Unknown ignorable records retain opaque metadata without affecting history.
+        if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true)
+            return;
         if (raw.surfaceOp !== undefined) {
             throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
         }
@@ -185,18 +236,35 @@ function assertProvenance(event, shadowedSeqs) {
         throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`);
     }
 }
+/**
+ * Validate one event's surface metadata without checking membership in a log or surface.
+ * @param event - event whose marker and source sequence values are inspected.
+ * Unknown ignorable records retain opaque metadata and never change the surface.
+ * @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+ * @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+ */
+export function validateSurfaceMetadata(event) {
+    const op = surfaceOpOf(event);
+    if (op !== undefined && op !== 'append'
+        && (op.startSeq >= event.seq || op.endSeq >= event.seq)) {
+        throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+    }
+    if (op !== undefined)
+        assertProvenance(event, []);
+    return op;
+}
 /** Locate one replacement range without mutating the current fold state. */
 function replacementRange(state, op) {
-    const startIdx = state.nodes.indexOf(op.start);
+    const startIdx = state.nodes.indexOf(op.startSeq);
     if (startIdx === -1) {
-        throw new Error(`surface replace: start seq ${op.start} not found in surface`);
+        throw new Error(`surface replace: start seq ${op.startSeq} not found in surface`);
     }
-    const endIdx = state.nodes.indexOf(op.end);
+    const endIdx = state.nodes.indexOf(op.endSeq);
     if (endIdx === -1) {
-        throw new Error(`surface replace: end seq ${op.end} not found in surface`);
+        throw new Error(`surface replace: end seq ${op.endSeq} not found in surface`);
     }
     if (startIdx > endIdx) {
-        throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+        throw new Error(`surface replace: start seq ${op.startSeq} (index ${startIdx}) is after end seq ${op.endSeq} (index ${endIdx})`);
     }
     return {
         startIdx,
@@ -254,26 +322,42 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
         }
     }
 }
+/**
+ * Protect the system prompt at surface node 0. A replacement covering node 0
+ * while that node is a `system/message` must itself be a `system/message` over
+ * exactly that node; later system nodes carry no protection and a compaction
+ * range may shadow them.
+ */
+function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
+    if (startIdx !== 0)
+        return;
+    const head = events[state.nodes[0] - baseSeq];
+    if (head?.type !== 'system/message')
+        return;
+    if (event.type !== 'system/message' || shadowedSeqs.length !== 1) {
+        throw new Error('surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node');
+    }
+}
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
 function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
     if (event.seq !== expectedSeq) {
         throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
     }
-    const surfaceOp = surfaceOpOf(event);
+    const surfaceOp = validateSurfaceMetadata(event);
     if (surfaceOp === undefined)
         return;
     if (surfaceOp === 'append') {
-        assertProvenance(event, []);
         return { kind: 'append', seq: event.seq };
     }
     const range = replacementRange(state, surfaceOp);
     assertProvenance(event, range.shadowedSeqs);
     assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+    assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
     return {
         kind: 'replace',
         seq: event.seq,
-        start: surfaceOp.start,
-        end: surfaceOp.end,
+        start: surfaceOp.startSeq,
+        end: surfaceOp.endSeq,
         ...range,
     };
 }

package/lib/types/types.d.ts

@@ -1,5 +1,5 @@
 import { type Branded, type BrandedNumber } from '@deepseek-ai/dsh-brand';
-import type { AssistantMessage, AssistantStreamRecord, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
+import type { AssistantMessage, AssistantStreamRecord, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, SystemMessage, SystemPromptUpdate, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>;
@@ -51,7 +51,7 @@ export type OptionalSessionSeq = SessionSeq | null;
  * immutable prior-generation, and current fast-path rules are recorded in
  * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
  */
-export declare const SESSION_FORMAT_VERSION = 2;
+export declare const SESSION_FORMAT_VERSION = 3;
 /**
  * Immutable validated storage metadata, kept outside the conversation event log.
  */
@@ -200,8 +200,9 @@ export interface TurnEndReasonMap {
 /** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];
 /**
- * Logged request state outside derived history: call config, system prompt, and
- * tools. The latest full `request/header` snapshot reconstructs it; canonical
+ * Logged request state outside derived history: call config and tools. The
+ * system prompt is derived history — surface node 0, a `system/message` event.
+ * The latest full `request/header` snapshot reconstructs the header; canonical
  * empty optional fields are absent.
  */
 export interface EpochHeader {
@@ -209,8 +210,6 @@ export interface EpochHeader {
     config: LlmCallConfig;
     /** Effective config fields materialized from the exact adapter rather than proposed by a caller. */
     adapterDefaults?: LlmCallConfigAdapterDefaults;
-    /** Rendered system prompt text; absent for a system-less request. */
-    system?: string;
     /** Assembled tool schemas; absent for a tool-less request. */
     tools?: ToolSchema[];
 }
@@ -222,6 +221,8 @@ export interface RequestContext {
     model: string;
     /** Maximum combined request and response context in tokens, when advertised. */
     contextWindow?: number;
+    /** `'in-history'` when the route reads the latest `system` message at any position as the effective system prompt. */
+    systemPromptUpdate?: SystemPromptUpdate;
 }
 /**
  * Why a `request/header` snapshot was appended: `'initial'` — the log's first
@@ -278,6 +279,23 @@ export interface SessionEventMap {
      * project their `content` verbatim; `source` tells them apart.
      */
     'user/message': UserMessage;
+    /**
+     * The rendered system prompt on the model-visible surface. The loop appends
+     * the first one as surface node 0 before the step's first `user/message`.
+     * A prepared in-history route can append nonempty changes in a continuing
+     * series. An incapable route or new series normalizes text to the first system
+     * node. Normalization empties nonempty later nodes, then rewrites the head if
+     * needed, through logged per-node replacements. An empty rendering always
+     * clears all active system nodes, leaving no older instructions model-visible.
+     * Empty later nodes are dormant and project to no message; an empty head with
+     * no active later node records "no system prompt". Restored nonempty text follows
+     * the same route and series rule; empty nodes never restore older text.
+     */
+    'system/message': {
+        turn: number;
+        step: number;
+        message: SystemMessage;
+    };
     /**
      * Assembled assistant message for one step (derived history uses this).
      * Carries the step's `usage` when the adapter reported token accounting, so
@@ -334,6 +352,7 @@ export interface SessionEventMap {
         turn: number;
         step: number;
         message: ToolResultMessage;
+        /** Optional failure identity; allowed only when the tool-result block has `isError: true`. */
         error?: {
             name: string;
             code: string;
@@ -351,8 +370,10 @@ export interface SessionEventMap {
         startsSeries?: true;
     };
     /**
-     * Route metadata for the next request, logged only when the route or capacity
-     * changes. It does not participate in request reconstruction or header equality.
+     * Route metadata for the next request, logged only when the route, capacity,
+     * or system prompt update mode changes. It does not participate in request
+     * reconstruction or header equality. Prompt admission uses the bound prepared
+     * call's capability, not this snapshot from an earlier request.
      */
     'request/context': RequestContext;
     /**
@@ -386,39 +407,29 @@ export type SessionEventType = keyof SessionEventMap;
 /**
  * The subset of {@link SessionEventType} values whose events produce LLM
  * messages and are eligible to appear on the ordered surface. Only these
- * event types may carry {@link SurfaceOp}; user and tool events may also cite
+ * event types may carry {@link SurfaceOp}; system, user, and tool events may also cite
  * earlier sources through {@link SessionEvent.sourceEventSeqs}.
  */
-export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';
-/**
- * A {@link SessionEvent} that is **on** the ordered surface — its
- * `surfaceOp` is guaranteed present (mandatory), narrowed from a
- * surface-eligible {@link SessionEvent} by checking both `type` and
- * `surfaceOp` at runtime.
- *
- * Use the `isSurfaceEvent` type guard (in `surface.ts`) to narrow a
- * `SessionEvent` to this type.
- */
-export type SurfaceEvent = SessionEvent<SurfaceEventType> & {
-    surfaceOp: SurfaceOp;
-};
+export type SurfaceEventType = 'system/message' | 'user/message' | 'assistant/message' | 'tool/result';
+/** A message-producing event carrying its required surface operation. */
+export type SurfaceEvent = SessionEvent<SurfaceEventType>;
 /**
  * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
  * - `'append'`: added to the tail — normal path for user/assistant/tool
  *   messages.
- * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
- *   (inclusive) through `end` (inclusive) with this node. Both must exist as
- *   surface nodes in the current surface. `start === end` replaces a single
+ * - `{ op: 'replace', startSeq, endSeq }`: replaces surface nodes from `startSeq`
+ *   (inclusive) through `endSeq` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `startSeq === endSeq` replaces a single
  *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
  *   shadowed surface node. Used by compaction; any surface-replacing producer
  *   may use it.
  */
 export type SurfaceOp = 'append' | {
     op: 'replace';
-    start: SessionSeq;
-    end: SessionSeq;
+    startSeq: SessionSeq;
+    endSeq: SessionSeq;
 };
 /**
  * Surface placement and cited source-event seqs for {@link Session.append}. Required on
@@ -427,7 +438,7 @@ export type SurfaceOp = 'append' | {
 export type SurfaceIntent<T extends SurfaceEventType = SurfaceEventType> = {
     surfaceOp: SurfaceOp;
 } & (T extends 'assistant/message' ? {
-    /** V2 Assistant messages embed their provider stream instead of citing source events. */
+    /** Assistant messages embed their provider stream instead of citing source events. */
     sourceEventSeqs?: never;
 } : {
     /** Complete non-empty set of known earlier source-event seqs. */
@@ -440,7 +451,7 @@ export type SurfaceIntent<T extends SurfaceEventType = SurfaceEventType> = {
  * unions), so `switch (event.type)` narrows `event.data` without casts.
  *
  * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * they only exist on {@link SurfaceEventType} variants (`system/message`, `user/message`,
  * `assistant/message`, `tool/result`).
  * Non-surface events (boundary markers, attempts, errors) never carry
  * surface metadata — the compiler enforces this at `Session.append()`
@@ -465,16 +476,10 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
          * inconvenience) rather than silently resuming a gutted session.
          */
         ignorable?: true;
-    } & (K extends SurfaceEventType ? {
-        /**
-         * Seq numbers of earlier events that this event cites as sources, such as
-         * the surface nodes shadowed by a compaction replacement. A v2
-         * `assistant/message` embeds its provider stream and cannot carry this field.
-         */
-        sourceEventSeqs?: SessionSeq[];
-        /** How this event entered the surface; absent for non-surface events. */
-        surfaceOp?: SurfaceOp;
-    } : object);
+    } & (K extends SurfaceEventType ? SurfaceIntent<K> : {
+        surfaceOp?: never;
+        sourceEventSeqs?: never;
+    });
 }[T];
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {

package/lib/types/types.js

@@ -51,5 +51,5 @@ export function SessionLogOffset(value) {
  * immutable prior-generation, and current fast-path rules are recorded in
  * `.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md`.
  */
-export const SESSION_FORMAT_VERSION = 2;
+export const SESSION_FORMAT_VERSION = 3;
 //# sourceMappingURL=types.js.map