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

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.
  */
@@ -102,7 +102,7 @@ export interface CreateSessionOptions {
     /** Initial replay or fork history supplied at construction. */
     readonly seed?: readonly SessionEvent[];
     /**
-     * Exact fork-inherited prefix length when `meta.isSeeded` is true. In v2 the
+     * 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.
      */
@@ -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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -41,19 +41,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-alpha.2"
   }
 }