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

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

@@ -32,6 +32,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'compaction/prune',
     'compaction/start',
     'compaction/summary',
+    'deliverables/presented',
     'feedback/message-delete',
     'feedback/message-put',
     'feedback/record',
@@ -53,8 +54,10 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'session/title-llm-request',
     'step/end',
     'step/start',
+    'subagent/catalog',
     'subagent/descriptor',
     'subagent/model-selection-policy',
+    'system/message',
     'team/member',
     'team/message/delivered',
     'team/message/queued',
@@ -65,8 +68,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,
     };
 }