@deepseek-ai/dsh-session 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/types/surface.js

@@ -12,6 +12,7 @@ import { KNOWN_SESSION_EVENT_TYPES, MESSAGE_PROJECTION_EVENT_TYPES } from "./kno
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
     'system/message',
+    'developer/message',
     'user/message',
     'assistant/message',
     'tool/result',
@@ -19,7 +20,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 four message-producing event types.
+ * @returns true for one of the message-producing event types.
  */
 export function isSurfaceEligibleType(type) {
     return SURFACE_EVENT_TYPES.has(type);
@@ -62,7 +63,7 @@ export function isReplacementSurfaceEvent(event) {
 /**
  * Project a single event into the LLM message it derives to, or null when it
  * produces none — a non-surface event (attempt, boundary, log-only record) or an
- * empty-content assistant/message (which exists only to host usage). A caller
+ * empty-content system, developer, or assistant message. A caller
  * reconstructing model input supplies the same prefix's `projectedMessages`
  * from {@link foldSurface}; without that map this function reads original
  * event content. Session instance methods apply the live projection. Messages
@@ -90,12 +91,11 @@ export function deriveEventMessage(event, projectedMessages) {
         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.
+        // Empty system and developer nodes retain their surface positions without
+        // adding wire messages. An empty assistant event hosts a max-tokens step's
+        // usage and must not inject a content-less turn into the provider transcript.
         case 'system/message':
+        case 'developer/message':
         case 'assistant/message': {
             if (event.data.message.content.length === 0)
                 return null;
@@ -115,14 +115,45 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
- * Reject noncanonical request-header fields and contradictory tool failure metadata.
+ * Reject noncanonical request-header fields, developer roles/content, 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.
+ * @throws when request-header fields, developer roles/content, or tool failure metadata are invalid.
  */
 export function validateSessionEventData(event, subject) {
     const data = event.data;
+    if (SURFACE_EVENT_TYPES.has(event.type) && isRecord(data)) {
+        const message = event.type === 'user/message' ? data : data['message'];
+        if (isRecord(message)) {
+            if ((event.type === 'developer/message') !== (message['role'] === 'developer')) {
+                throw new Error(`${subject} developer/message and developer role must occur together`);
+            }
+            if (message['role'] !== 'developer' && Array.isArray(message['content'])
+                && message['content'].some((block) => isRecord(block)
+                    && (block['type'] === 'tool-addition' || block['type'] === 'tool-removal'))) {
+                throw new Error(`${subject} tool-change blocks require developer role`);
+            }
+            if (event.type === 'developer/message' && Array.isArray(message['content'])) {
+                let hasAdditions = false;
+                for (const block of message['content']) {
+                    if (!isRecord(block) || (block['type'] !== 'tool-addition' && block['type'] !== 'tool-removal'))
+                        continue;
+                    if (typeof block['toolName'] !== 'string' || block['toolName'].length === 0) {
+                        throw new Error(`${subject} ${block['type']} requires a nonempty toolName`);
+                    }
+                    if (block['type'] === 'tool-addition') {
+                        hasAdditions = true;
+                        if (Object.hasOwn(block, 'tool'))
+                            throw new Error(`${subject} tool-addition must omit inline tool definitions`);
+                    }
+                }
+                if (hasAdditions ? !isEventSeq(data['headerSeq']) : Object.hasOwn(data, 'headerSeq')) {
+                    throw new Error(`${subject} requires headerSeq exactly when tool additions are present`);
+                }
+            }
+        }
+    }
     if (event.type === 'request/header') {
         if (!isRecord(data))
             throw new Error(`${subject} data must be an object`);
@@ -145,10 +176,8 @@ export function validateSessionEventData(event, subject) {
         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`);
+        if (!isRecord(message) || message['isError'] !== true) {
+            throw new Error(`${subject} error requires message.isError === true`);
         }
     }
 }
@@ -238,6 +267,34 @@ function assertSourceEventReferences(event, shadowedSeqs) {
         throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`);
     }
 }
+/** Resolve tool additions against their immutable historical request header. */
+function assertDeveloperHeader(event, events, baseSeq) {
+    if (event.type !== 'developer/message')
+        return;
+    validateSessionEventData(event, `developer/message at seq ${event.seq}`);
+    if (event.data.headerSeq === undefined)
+        return;
+    const headerSeq = event.data.headerSeq;
+    const headerEvent = events[headerSeq - baseSeq];
+    if (headerSeq >= event.seq || headerEvent?.type !== 'request/header') {
+        throw new Error('developer/message headerSeq must reference an earlier request/header');
+    }
+    for (const block of event.data.message.content) {
+        if (block.type !== 'tool-addition')
+            continue;
+        const definitions = headerEvent.data.header.tools?.filter(tool => tool.name === block.toolName) ?? [];
+        if (definitions.length !== 1) {
+            throw new Error(`developer/message tool-addition "${block.toolName}" must name exactly one tool in headerSeq ${headerSeq}`);
+        }
+        const definition = definitions[0];
+        if (typeof definition.description !== 'string' || !isRecord(definition.parameters)) {
+            throw new Error(`developer/message tool-addition "${block.toolName}" requires a complete tool definition in headerSeq ${headerSeq}`);
+        }
+        if (Object.hasOwn(definition, 'deferLoading') && definition.deferLoading !== true) {
+            throw new Error('developer/message referenced tool deferLoading must be true when present');
+        }
+    }
+}
 /**
  * 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.
@@ -309,15 +366,13 @@ function assertToolResultRewrite(event, shadowedSeqs, events, baseSeq) {
         }
         const originalRest = { ...original.data };
         const replacementRest = { ...event.data };
-        const originalResult = original.data.message.content[0];
-        const replacementResult = event.data.message.content[0];
         originalRest['message'] = {
             ...original.data.message,
-            content: [{ ...originalResult, content: null }],
+            content: null,
         };
         replacementRest['message'] = {
             ...event.data.message,
-            content: [{ ...replacementResult, content: null }],
+            content: null,
         };
         if (!isDeepEqualJson(originalRest, replacementRest)) {
             throw new Error('tool/result surface replacement may change only content');
@@ -346,6 +401,7 @@ function planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projection
         throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
     }
     const surfaceOp = validateSurfaceMetadata(event);
+    assertDeveloperHeader(event, events, baseSeq);
     const projection = projections.find(item => item.type === event.type);
     if (projection !== undefined) {
         return { kind: 'project', projection, messages: projection.project(event, {

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, SystemMessage, SystemPromptUpdate, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
+import type { AssistantMessage, DeveloperMessage, 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 = 3;
+export declare const SESSION_FORMAT_VERSION = 4;
 /**
  * Immutable validated storage metadata, kept outside the conversation event log.
  */
@@ -103,8 +103,8 @@ export interface CreateSessionOptions {
     readonly seed?: readonly SessionEvent[];
     /**
      * Exact fork-inherited prefix length when `meta.isSeeded` is true. The
-     * constructor seed is exactly this inherited prefix; the constructor
-     * appends the child-owned tagged marker at the cut.
+     * constructor appends the child-owned tagged marker at the cut unless
+     * the seed already includes it followed by child-owned fork closers.
      */
     readonly inheritedEventCount?: SessionLogOffset;
     /**
@@ -196,6 +196,15 @@ export interface TurnEndReasonMap {
     interrupted: {
         kind: 'interrupted';
     };
+    /**
+     * Fork-seed construction closed a turn that was still open at the fork
+     * boundary in the source session. Only fork seeds carry this marker — the
+     * loop never emits it — and the source events before the boundary remain
+     * intact in the child.
+     */
+    forked: {
+        kind: 'forked';
+    };
 }
 /** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];
@@ -212,6 +221,10 @@ export interface EpochHeader {
     adapterDefaults?: LlmCallConfigAdapterDefaults;
     /** Assembled tool schemas; absent for a tool-less request. */
     tools?: ToolSchema[];
+    /** Retired request text; system prompts belong to system/message events.
+     * @persistenceReserved
+     */
+    system?: never;
 }
 /** Registration-bound metadata for one resolved model route. */
 export interface RequestContext {
@@ -279,6 +292,14 @@ export interface SessionEventMap {
      * project their `content` verbatim; `source` tells them apart.
      */
     'user/message': UserMessage;
+    /** An incremental agent session change admitted at the named turn and step. */
+    'developer/message': {
+        turn: number;
+        step: number;
+        message: DeveloperMessage;
+        /** Earlier request/header defining every tool addition; required exactly when additions are present. */
+        headerSeq?: SessionSeq;
+    };
     /**
      * 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`.
@@ -356,7 +377,7 @@ export interface SessionEventMap {
         message: ToolResultMessage;
         /**
          * Optional failure identity and raw user-facing reason, outside model content;
-         * allowed only when the tool-result block has `isError: true`.
+         * allowed only when the message has `isError: true`.
          */
         error?: {
             name: string;
@@ -383,19 +404,21 @@ export interface SessionEventMap {
      */
     'request/context': RequestContext;
     /**
-     * Marks the end of a constructor seed. Events before it have smaller seq
-     * values and came from the seed (resume, fork, or replay); this lifecycle
-     * produced none of them. This log-only event is the durable projection of
-     * {@link Session.firstLiveSeq}.
+     * Separates inherited or restored history from later lifecycle-owned work.
+     * This log-only marker need not be at {@link Session.firstLiveSeq}: a fork
+     * seed can already contain its tagged marker and child-owned synthetic
+     * closers before construction.
      *
      * A fresh fork child owns one `{ inherited: true }` marker at its exact
      * inherited-prefix cut, even when that prefix ends in an ancestor marker.
-     * The last tagged marker is the current Session's cut; untagged markers keep
-     * ordinary restore and replay lifecycle boundaries.
+     * `buildForkSeed` appends that marker before any synthetic closers; the
+     * `Session` constructor supplies it when given only the inherited prefix.
+     * The last tagged marker is the current Session's cut; untagged markers
+     * keep ordinary restore and replay lifecycle boundaries.
      *
-     * `Session`'s constructor is the only legitimate writer. The invariant
-     * companion deliberately constrains nothing here, so a plugin appending one
-     * would silently classify every live bracket before it as seed history.
+     * Only the `Session` constructor and `buildForkSeed` may create this marker.
+     * The invariant companion deliberately constrains nothing here, so a plugin
+     * appending one would silently classify every live bracket before it as seed history.
      *
      * An owner of a standalone open/close bracket (`compaction/start` …
      * `compaction/end`) reads it because seed history and live work are otherwise
@@ -416,7 +439,7 @@ export type SessionEventType = keyof SessionEventMap;
  * event types may carry {@link SurfaceOp}; system, user, and tool events may also cite
  * earlier sources through {@link SessionEvent.sourceEventSeqs}.
  */
-export type SurfaceEventType = 'system/message' | 'user/message' | 'assistant/message' | 'tool/result';
+export type SurfaceEventType = 'system/message' | 'developer/message' | 'user/message' | 'assistant/message' | 'tool/result';
 /** A message-producing event carrying its required surface operation. */
 export type SurfaceEvent = SessionEvent<SurfaceEventType>;
 /**

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 = 3;
+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.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -26,6 +26,10 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
+    "./fork": {
+      "types": "./lib/types/fork.d.ts",
+      "default": "./lib/types/fork.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json",
     "./surface": {
@@ -41,19 +45,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-scope": "0.1.7-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-alpha.2"
   }
 }