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

package/lib/types/fork.js

@@ -0,0 +1,28 @@
+/**
+ * Fork seed construction over an exact source-event prefix.
+ * @module @deepseek-ai/dsh-session/fork
+ */
+import { openTurnClosers } from "./repair.js";
+import { SessionSeq } from "./types.js";
+/**
+ * Copy an inclusive event prefix, mark its inherited cut, and close its open tail with forked results
+ * and step/turn endings. Closed steps and turns are preserved unchanged.
+ * The caller validates that the boundary is an existing contiguous event seq;
+ * Session construction snapshots the borrowed events before publication.
+ *
+ * @param events - source log with contiguous seqs from zero.
+ * @param boundary - inclusive source event seq the child inherits through.
+ * @returns a new array retaining the source event objects, followed by synthetic
+ *   closers outside the inherited prefix counted by `inheritedEventCount`.
+ */
+export function buildForkSeed(events, boundary) {
+    const prefix = events.slice(0, boundary + 1);
+    prefix.push({
+        type: 'session/end-seed', seq: SessionSeq(boundary + 1),
+        // oxlint-disable-next-line typescript/no-non-null-assertion -- the caller validated this exact source event.
+        time: events[boundary].time,
+        data: { inherited: true },
+    });
+    return prefix.concat(openTurnClosers(prefix, { kind: 'forked' }));
+}
+//# sourceMappingURL=fork.js.map

package/lib/types/index.d.ts

@@ -12,10 +12,11 @@ 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 { SessionSurface, SessionMessageProjection } from './surface.ts';
+export { buildForkSeed } from './fork.ts';
 export * from './types.ts';
 export { SessionPreparation } from './preparation.ts';
 export type { SessionPreparationOptions } from './preparation.ts';
-export type { AssistantMessage, SystemMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
+export type { AssistantMessage, DeveloperMessage, SystemMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult, SessionMessageProjection, SessionMessageProjectionContext } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
@@ -120,29 +121,25 @@ export declare class Session {
     /** The session identity, derived from its durable header's single copy. */
     get id(): SessionId;
     /**
-     * The first seq appended IN THIS PROCESS: the length of the constructor
-     * seed (0 without one). Events with smaller seq values entered through
-     * construction — replay, fork, or resume — and were never published on the
-     * `session/event` firehose (constructor seeds do not emit). This offset marks
-     * the constructor-input boundary for lifecycle ownership and persistence
-     * adoption; consumers that need complete canonical history still start at
-     * seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
-     * fork-lineage cut: a resumed session's constructor seed is its full stored
-     * log, while the inherited count keeps the original fork value — this field is the
-     * in-process construction fact.
+     * The constructor seed length (0 without one), before any marker appended
+     * during construction. Seed events never publish on `session/event`. A
+     * marker appended before the store attaches occupies this seq without
+     * publishing either; otherwise this seq is available for the next append.
      *
-     * Not persisted itself: a seeded session projects it into the log as the
-     * `session/end-seed` event, which is what a consumer reading STORED history
-     * reads. Locate the LAST such event, not necessarily one at this seq — a
-     * seed already ending in one is not re-marked, so reopening an untouched
-     * session leaves that event at a smaller seq than `firstLiveSeq`. Prefer
-     * this field in-process: it is exact before the marker reaches storage.
-     *
-     * When this lifecycle appends the marker, it occupies this seq before the
-     * store attaches and therefore does not publish either. Otherwise this seq
-     * holds an ordinary published write.
+     * This in-process offset is not persisted. A fork seed can already contain
+     * the child's inherited marker and synthetic closers, so its child-owned
+     * history starts at {@link inheritedEventCount}, before this offset. A
+     * resumed Session's seed contains its full stored log, while its inherited
+     * count keeps the durable fork cut. Consumers needing complete canonical
+     * history start at seq 0.
      */
     readonly firstLiveSeq: SessionLogOffset;
+    /**
+     * First event produced for this object lifecycle. A new fork includes its
+     * child-owned seed marker and closers; a restored Session starts after its
+     * complete stored prefix. This in-process capture offset is not persisted.
+     */
+    readonly firstLifecycleSeq: SessionLogOffset;
     /**
      * Create a detached session by validating and snapshotting borrowed seed
      * events and storage metadata.
@@ -307,11 +304,10 @@ export type SessionForkSource = Session | SessionId;
  * Rejection codes for session forking: the fork source id is unknown to the
  * live store (`SESSION_NOT_FOUND`) or names a session object that is not the
  * store's live instance (`SESSION_NOT_LIVE`); the requested child id is
- * already taken (`SESSION_ALREADY_EXISTS`); the boundary is not a contiguous
- * existing seq (`INVALID_BOUNDARY`); or the selected prefix ends inside an
- * open turn (`OPEN_TURN`).
+ * already taken (`SESSION_ALREADY_EXISTS`); or the boundary is not a contiguous
+ * existing seq (`INVALID_BOUNDARY`).
  */
-export type SessionForkErrorCode = 'SESSION_NOT_FOUND' | 'SESSION_NOT_LIVE' | 'SESSION_ALREADY_EXISTS' | 'INVALID_BOUNDARY' | 'OPEN_TURN';
+export type SessionForkErrorCode = 'SESSION_NOT_FOUND' | 'SESSION_NOT_LIVE' | 'SESSION_ALREADY_EXISTS' | 'INVALID_BOUNDARY';
 /** Typed error for session fork rejections. */
 export declare class SessionForkError extends Error {
     readonly code: SessionForkErrorCode;
@@ -444,10 +440,12 @@ export declare class SessionStore extends Service {
      */
     list(): Session[];
     /**
-     * Create a live child session from a stable prefix of a live source.
+     * Create a live child session from an exact prefix of a live source.
      * `boundary` is an inclusive source event seq; omitted means the source's
-     * current last event. The selected slice may end with a between-turn event
-     * but must not end inside an open turn.
+     * current last event. An open tail receives synthetic tool results and
+     * step/turn closers with the forked cause. Closed steps and turns remain
+     * unchanged, including any failed tool calls already missing results.
+     * `inheritedEventCount` counts only copied source events, excluding these closers.
      *
      * @param source - Live source session object or id.
      * @param boundary - Inclusive source event seq to fork through; omitted means
@@ -458,7 +456,7 @@ export declare class SessionStore extends Service {
      * @returns The created live child session.
      */
     fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session;
-    private _forkSeed;
+    private _forkBoundary;
     private _resolveForkSource;
 }
 export { decodeSeqRanges, encodeSeqRanges } from './seq-ranges.ts';

package/lib/types/index.js

@@ -13,6 +13,8 @@ import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
 import { SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from "./surface.js";
 import { foldRequestHeader } from "./request-header.js";
+import { buildForkSeed } from "./fork.js";
+export { buildForkSeed } from "./fork.js";
 export * from "./types.js";
 export { SessionPreparation } from "./preparation.js";
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from "./repair.js";
@@ -101,6 +103,7 @@ export function adoptSessionEvent(event) {
         case 'user/message':
             deepFreeze(event.data);
             break;
+        case 'developer/message':
         case 'system/message':
         case 'assistant/message':
         case 'tool/result':
@@ -153,6 +156,7 @@ function assertSessionEventEnvelope(value, index) {
     validateSessionEventData(event, `seed ${type} at index ${index}`);
     switch (type) {
         case 'request/header':
+        case 'developer/message':
         case 'system/message':
         case 'user/message':
         case 'assistant/attempt':
@@ -226,16 +230,17 @@ 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. */
+/** The surface event types whose payload carries an identified message. */
 function isMessageEventType(type) {
-    return type === 'system/message' || type === 'user/message'
+    return type === 'developer/message' || type === 'system/message' || type === 'user/message'
         || type === 'assistant/message' || type === 'tool/result';
 }
 const MESSAGE_ROLE_BY_TYPE = {
     'system/message': 'system',
+    'developer/message': 'developer',
     'user/message': 'user',
     'assistant/message': 'assistant',
-    'tool/result': 'user',
+    'tool/result': 'tool',
 };
 /** Validate only the event-specific invariants needed to safely replay a message. */
 function assertMessageEventShape(event, subject) {
@@ -268,9 +273,8 @@ function assertMessageEventShape(event, subject) {
     }
     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`);
+        if (sourceRecord['kind'] !== 'system-prompt') {
+            throw new Error(`${subject} message must have system-prompt source`);
         }
         return;
     }
@@ -287,14 +291,7 @@ function assertMessageEventShape(event, subject) {
         || sourceRecord['callId'] === '') {
         throw new Error(`${subject} message must have tool source`);
     }
-    const content = messageRecord['content'];
-    const block = content[0];
-    if (content.length !== 1 || typeof block !== 'object' || block === null
-        || block['type'] !== 'tool-result'
-        || !Array.isArray(block['content'])) {
-        throw new Error(`${subject} message must contain one tool-result block`);
-    }
-    if (block['toolCallId'] !== sourceRecord['callId']) {
+    if (messageRecord['toolCallId'] !== sourceRecord['callId']) {
         throw new Error(`${subject} message has mismatched tool call ids`);
     }
 }
@@ -358,29 +355,25 @@ export class Session {
         return this.header.id;
     }
     /**
-     * The first seq appended IN THIS PROCESS: the length of the constructor
-     * seed (0 without one). Events with smaller seq values entered through
-     * construction — replay, fork, or resume — and were never published on the
-     * `session/event` firehose (constructor seeds do not emit). This offset marks
-     * the constructor-input boundary for lifecycle ownership and persistence
-     * adoption; consumers that need complete canonical history still start at
-     * seq 0. Distinct from {@link inheritedEventCount}, the DURABLE
-     * fork-lineage cut: a resumed session's constructor seed is its full stored
-     * log, while the inherited count keeps the original fork value — this field is the
-     * in-process construction fact.
-     *
-     * Not persisted itself: a seeded session projects it into the log as the
-     * `session/end-seed` event, which is what a consumer reading STORED history
-     * reads. Locate the LAST such event, not necessarily one at this seq — a
-     * seed already ending in one is not re-marked, so reopening an untouched
-     * session leaves that event at a smaller seq than `firstLiveSeq`. Prefer
-     * this field in-process: it is exact before the marker reaches storage.
+     * The constructor seed length (0 without one), before any marker appended
+     * during construction. Seed events never publish on `session/event`. A
+     * marker appended before the store attaches occupies this seq without
+     * publishing either; otherwise this seq is available for the next append.
      *
-     * When this lifecycle appends the marker, it occupies this seq before the
-     * store attaches and therefore does not publish either. Otherwise this seq
-     * holds an ordinary published write.
+     * This in-process offset is not persisted. A fork seed can already contain
+     * the child's inherited marker and synthetic closers, so its child-owned
+     * history starts at {@link inheritedEventCount}, before this offset. A
+     * resumed Session's seed contains its full stored log, while its inherited
+     * count keeps the durable fork cut. Consumers needing complete canonical
+     * history start at seq 0.
      */
     firstLiveSeq;
+    /**
+     * First event produced for this object lifecycle. A new fork includes its
+     * child-owned seed marker and closers; a restored Session starts after its
+     * complete stored prefix. This in-process capture offset is not persisted.
+     */
+    firstLifecycleSeq;
     /**
      * Create a detached session by validating and snapshotting borrowed seed
      * events and storage metadata.
@@ -462,17 +455,23 @@ export class Session {
         if (inheritedEventCount > this.log.length) {
             throw new Error('session inherited event count exceeds its event log');
         }
-        if (mode === 'snapshot' && this.header.isSeeded && inheritedEventCount !== this.log.length) {
-            throw new Error('seeded session constructor seed must equal its inherited prefix');
+        const seedMarker = this.log[inheritedEventCount];
+        const markedSeed = seedMarker?.type === 'session/end-seed' && seedMarker.data.inherited === true;
+        if (mode === 'snapshot' && this.header.isSeeded && inheritedEventCount !== this.log.length && !markedSeed) {
+            throw new Error('seeded session constructor seed must equal its inherited prefix or mark its inherited cut');
+        }
+        if (markedSeed && this.log.slice(inheritedEventCount + 1).some(event => event.type === 'session/end-seed' && event.data.inherited === true)) {
+            throw new Error('session inherited event count must identify the final inherited marker');
         }
         this.inheritedEventCount = inheritedEventCount;
+        this.firstLifecycleSeq = mode === 'snapshot' && this.header.isSeeded ? inheritedEventCount : this.firstLiveSeq;
         // A fresh seeded child always owns one tagged marker at its inherited cut,
         // even when the copied prefix already ends in an ancestor marker. Restore
         // retains that durable marker and appends only the ordinary resume marker.
-        if (seed !== undefined && mode === 'snapshot' && this.header.isSeeded) {
+        if (seed !== undefined && mode === 'snapshot' && this.header.isSeeded && !markedSeed) {
             this.append('session/end-seed', { inherited: true });
         }
-        else if (seed !== undefined && this.log.at(-1)?.type !== 'session/end-seed') {
+        else if (seed !== undefined && !(mode === 'snapshot' && this.header.isSeeded) && this.log.at(-1)?.type !== 'session/end-seed') {
             this.append('session/end-seed', {});
         }
     }
@@ -1035,10 +1034,12 @@ export class SessionStore extends Service {
         return [...this.store.values()].map(entry => entry.session);
     }
     /**
-     * Create a live child session from a stable prefix of a live source.
+     * Create a live child session from an exact prefix of a live source.
      * `boundary` is an inclusive source event seq; omitted means the source's
-     * current last event. The selected slice may end with a between-turn event
-     * but must not end inside an open turn.
+     * current last event. An open tail receives synthetic tool results and
+     * step/turn closers with the forked cause. Closed steps and turns remain
+     * unchanged, including any failed tool calls already missing results.
+     * `inheritedEventCount` counts only copied source events, excluding these closers.
      *
      * @param source - Live source session object or id.
      * @param boundary - Inclusive source event seq to fork through; omitted means
@@ -1053,10 +1054,13 @@ export class SessionStore extends Service {
             throw new SessionForkError(`session "${childSessionId}" already exists`, 'SESSION_ALREADY_EXISTS');
         }
         const liveSource = this._resolveForkSource(source);
-        const seed = this._forkSeed(liveSource, boundary);
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing fork snapshot read; migration deferred.
+        const events = liveSource.snapshotEvents();
+        const resolved = this._forkBoundary(liveSource.id, events, boundary);
+        const seed = resolved === undefined ? [] : buildForkSeed(events, resolved);
         return this.create(childSessionId, {
             seed,
-            inheritedEventCount: SessionLogOffset(seed.length),
+            inheritedEventCount: SessionLogOffset(resolved === undefined ? 0 : resolved + 1),
             meta: {
                 ...liveSource.header.cwd !== undefined ? { cwd: liveSource.header.cwd } : {},
                 parentSession: liveSource.id,
@@ -1064,38 +1068,29 @@ export class SessionStore extends Service {
             },
         });
     }
-    _forkSeed(session, requestedBoundary) {
-        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
-        const lastEvent = session.snapshotEvents().at(-1);
+    _forkBoundary(sessionId, events, requestedBoundary) {
+        const lastEvent = events.at(-1);
         let boundary;
         if (requestedBoundary !== undefined) {
             boundary = requestedBoundary;
         }
         else {
             if (lastEvent === undefined)
-                return [];
+                return undefined;
             boundary = lastEvent.seq;
         }
         if (!Number.isSafeInteger(boundary) || boundary < 0) {
-            throw new SessionForkError(`fork boundary for session "${session.id}" must be a non-negative safe integer, got ${String(boundary)}`, 'INVALID_BOUNDARY');
+            throw new SessionForkError(`fork boundary for session "${sessionId}" must be a non-negative safe integer, got ${String(boundary)}`, 'INVALID_BOUNDARY');
         }
-        if (boundary >= session.seq) {
+        if (boundary >= events.length) {
             const lastSeq = lastEvent?.seq;
-            throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${session.id}" (last seq: ${lastSeq ?? 'none'})`, 'INVALID_BOUNDARY');
+            throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${sessionId}" (last seq: ${lastSeq ?? 'none'})`, 'INVALID_BOUNDARY');
         }
-        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
-        const boundaryEvent = session.eventAt(boundary);
+        const boundaryEvent = events[boundary];
         if (boundaryEvent === undefined || boundaryEvent.seq !== boundary) {
-            throw new SessionForkError(`fork boundary ${boundary} does not match a contiguous event seq in session "${session.id}"`, 'INVALID_BOUNDARY');
-        }
-        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
-        const events = session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(boundary + 1));
-        const lastTurnBoundary = events
-            .findLast(event => event.type === 'turn/start' || event.type === 'turn/end');
-        if (lastTurnBoundary?.type === 'turn/start') {
-            throw new SessionForkError(`fork boundary ${boundary} in session "${session.id}" ends inside open turn ${lastTurnBoundary.data.turn}`, 'OPEN_TURN');
+            throw new SessionForkError(`fork boundary ${boundary} does not match a contiguous event seq in session "${sessionId}"`, 'INVALID_BOUNDARY');
         }
-        return events;
+        return boundary;
     }
     _resolveForkSource(source) {
         if (typeof source === 'string') {

package/lib/types/invariant.js

@@ -65,6 +65,10 @@ function validateEvent(trace, event, fail) {
             openStep = event.data.step;
             break;
         }
+        case 'developer/message': {
+            requireOpenStep(trace, 'developer/message', event.data.turn, event.data.step, fail);
+            break;
+        }
         case 'step/end': {
             requireOpenStep(trace, 'step/end', event.data.turn, event.data.step, fail);
             pendingCalls = { kind: 'clear' };
@@ -96,7 +100,7 @@ function validateEvent(trace, event, fail) {
             }
             requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step, fail);
             const callId = event.data.message.source.callId;
-            const syntheticNotStarted = event.data.message.content[0].isError === true && event.data.error?.code === TOOL_NOT_STARTED;
+            const syntheticNotStarted = event.data.message.isError === true && event.data.error?.code === TOOL_NOT_STARTED;
             if (!trace.pendingCalls.has(callId) && !syntheticNotStarted) {
                 fail(`tool/result for ${callId} with no prior tool/call in this step`);
             }

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

@@ -33,6 +33,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'compaction/start',
     'compaction/summary',
     'deliverables/presented',
+    'developer/message',
     'feedback/message-delete',
     'feedback/message-put',
     'feedback/record',

package/lib/types/repair.d.ts

@@ -1,7 +1,10 @@
 /**
- * Crash-recovery repair for an interrupted session log. It preserves a fully
- * written final turn and supplies the missing tool, step, and turn boundaries
- * needed to resume with a provider-valid transcript.
+ * Synthetic closer events that balance a session log whose tail turn is open.
+ * Two producers share the mechanism: crash recovery closes an interrupted
+ * persisted log on reload, and fork-seed construction closes a prefix cut
+ * inside the source's open turn. Both preserve every fully written event and
+ * close the unfinished step and turn. Calls in already closed steps remain
+ * unchanged, including any missing results.
  * @module @deepseek-ai/dsh-session/repair
  */
 import type { SessionEvent } from './types.ts';
@@ -9,14 +12,46 @@ import type { SessionEvent } from './types.ts';
 export declare const TOOL_NOT_STARTED = "TOOL_NOT_STARTED";
 /** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
 export declare const TOOL_OUTCOME_UNKNOWN = "TOOL_OUTCOME_UNKNOWN";
+/**
+ * Why an open tail turn is closed with synthetic events: `interrupted` is
+ * crash recovery over a persisted log; `forked` is a fork seed cut inside the
+ * source's open turn. The cause selects the synthetic `turn/end` reason, the
+ * model-visible wording of synthetic error tool results, and the
+ * deterministic synthetic message-id prefix. The error codes
+ * ({@link TOOL_NOT_STARTED} / {@link TOOL_OUTCOME_UNKNOWN}) are shared: both
+ * causes state the same fact about the call's recorded lifecycle.
+ */
+export type OpenTurnCloseCause = {
+    readonly kind: 'interrupted';
+} | {
+    readonly kind: 'forked';
+};
 /**
  * Return deterministic synthetic events that close an open tail turn. Unmatched
- * calls receive error results first, followed by an open `step/end` and an
- * interrupted `turn/end`; sequences continue the log and timestamps reuse the
- * last real event. A balanced or empty log returns no events.
+ * calls in its open step receive error results, followed by `step/end` and a
+ * `turn/end` carrying the cause's reason. Calls in closed steps remain unchanged.
+ * Sequences continue the log and timestamps reuse the last real event. A balanced or empty log returns no
+ * events.
+ *
+ * Package-internal: each cause has exactly one owner, so external callers go
+ * through {@link interruptedTurnClosers} (persistence crash recovery) or
+ * `buildForkSeed` in `./fork.ts` (fork seeds) instead of selecting a cause.
  *
- * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @param events - the log to scan: a valid committed prefix, possibly ending
+ *   inside an open turn (a crash tail or a mid-turn fork cut).
+ * @param cause - why the turn is being closed; selects the `turn/end` reason
+ *   and the model-visible wording of synthetic error tool results.
  * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
+export declare function openTurnClosers(events: readonly SessionEvent[], cause: OpenTurnCloseCause): SessionEvent[];
+/**
+ * Crash-recovery entry point: synthetic closers that balance a persisted log
+ * whose tail turn was interrupted. Used by crash-recovery callers; fork
+ * seeds receive their `forked`-cause closers through `buildForkSeed` in
+ * `./fork.ts`, and cause selection stays internal to those two owners.
+ *
+ * @param events - the persisted log to scan, possibly ending inside an open turn.
+ * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.
+ */
 export declare function interruptedTurnClosers(events: readonly SessionEvent[]): SessionEvent[];
 //# sourceMappingURL=repair.d.ts.map

package/lib/types/repair.js

@@ -1,7 +1,10 @@
 /**
- * Crash-recovery repair for an interrupted session log. It preserves a fully
- * written final turn and supplies the missing tool, step, and turn boundaries
- * needed to resume with a provider-valid transcript.
+ * Synthetic closer events that balance a session log whose tail turn is open.
+ * Two producers share the mechanism: crash recovery closes an interrupted
+ * persisted log on reload, and fork-seed construction closes a prefix cut
+ * inside the source's open turn. Both preserve every fully written event and
+ * close the unfinished step and turn. Calls in already closed steps remain
+ * unchanged, including any missing results.
  * @module @deepseek-ai/dsh-session/repair
  */
 import { brandString } from '@deepseek-ai/dsh-brand';
@@ -11,16 +14,35 @@ import { SessionSeq } from "./types.js";
 export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED';
 /** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
 export const TOOL_OUTCOME_UNKNOWN = 'TOOL_OUTCOME_UNKNOWN';
+/** Model-visible wording of the synthetic error tool results, keyed by cause. */
+const CLOSER_TEXT = {
+    interrupted: {
+        started: 'The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+        notStarted: 'The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.',
+    },
+    forked: {
+        started: 'The history inherited by this branch records this tool call starting but does not include its result. The parent session may have completed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+        notStarted: 'The history inherited by this branch has no record of this tool call starting. The parent session may have executed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.',
+    },
+};
 /**
  * Return deterministic synthetic events that close an open tail turn. Unmatched
- * calls receive error results first, followed by an open `step/end` and an
- * interrupted `turn/end`; sequences continue the log and timestamps reuse the
- * last real event. A balanced or empty log returns no events.
+ * calls in its open step receive error results, followed by `step/end` and a
+ * `turn/end` carrying the cause's reason. Calls in closed steps remain unchanged.
+ * Sequences continue the log and timestamps reuse the last real event. A balanced or empty log returns no
+ * events.
  *
- * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * Package-internal: each cause has exactly one owner, so external callers go
+ * through {@link interruptedTurnClosers} (persistence crash recovery) or
+ * `buildForkSeed` in `./fork.ts` (fork seeds) instead of selecting a cause.
+ *
+ * @param events - the log to scan: a valid committed prefix, possibly ending
+ *   inside an open turn (a crash tail or a mid-turn fork cut).
+ * @param cause - why the turn is being closed; selects the `turn/end` reason
+ *   and the model-visible wording of synthetic error tool results.
  * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
-export function interruptedTurnClosers(events) {
+export function openTurnClosers(events, cause) {
     let openTurn = null;
     let openStep = null;
     // Reset at each turn boundary so earlier calls cannot leak into tail repair.
@@ -70,7 +92,7 @@ export function interruptedTurnClosers(events) {
                 break;
         }
     }
-    // Balanced log (no crash mid-turn): nothing to close. An open turn implies
+    // Balanced log (no open tail turn): nothing to close. An open turn implies
     // `events` is non-empty (its turn/start was logged), so `last` exists.
     const last = events.at(-1);
     if (openTurn === null || last === undefined)
@@ -81,24 +103,19 @@ export function interruptedTurnClosers(events) {
     let seq = last.seq + 1;
     const time = last.time;
     const closers = [];
-    // Close calls before their step: providers reject dangling assistant calls,
-    // and Map insertion order preserves their transcript order.
+    // Close calls before their step; Map insertion order preserves transcript order.
+    const text = CLOSER_TEXT[cause.kind];
     for (const [callId, { step, callSeq }] of pendingCalls) {
         const started = callSeq !== undefined;
         const message = deepFreeze({
-            id: brandString(`interrupted-tool-result-${callId}-${seq}`),
-            role: 'user',
+            id: brandString(`${cause.kind}-tool-result-${callId}-${seq}`),
+            role: 'tool',
+            toolCallId: callId,
+            isError: true,
             source: { kind: 'tool', callId },
             content: [{
-                    type: 'tool-result',
-                    toolCallId: callId,
-                    isError: true,
-                    content: [{
-                            type: 'text',
-                            text: started
-                                ? 'The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.'
-                                : 'The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.',
-                        }],
+                    type: 'text',
+                    text: started ? text.started : text.notStarted,
                 }],
         });
         closers.push({
@@ -122,7 +139,19 @@ export function interruptedTurnClosers(events) {
     if (openStep !== null) {
         closers.push({ type: 'step/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, step: openStep } });
     }
-    closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: 'interrupted' } } });
+    closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: cause.kind } } });
     return closers;
 }
+/**
+ * Crash-recovery entry point: synthetic closers that balance a persisted log
+ * whose tail turn was interrupted. Used by crash-recovery callers; fork
+ * seeds receive their `forked`-cause closers through `buildForkSeed` in
+ * `./fork.ts`, and cause selection stays internal to those two owners.
+ *
+ * @param events - the persisted log to scan, possibly ending inside an open turn.
+ * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.
+ */
+export function interruptedTurnClosers(events) {
+    return openTurnClosers(events, { kind: 'interrupted' });
+}
 //# sourceMappingURL=repair.js.map

package/lib/types/surface.d.ts

@@ -38,7 +38,7 @@ export interface SessionMessageProjection<T extends SessionEventType = SessionEv
 /**
  * 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 declare function isSurfaceEligibleType(type: string): boolean;
 /**
@@ -76,7 +76,7 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
 /**
  * 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
@@ -87,11 +87,11 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
  */
 export declare function deriveEventMessage(event: SessionEvent, projectedMessages?: ReadonlyMap<SessionSeq, Message>): Message | null;
 /**
- * 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 declare function validateSessionEventData(event: Pick<SessionEvent, 'type' | 'data'>, subject: string): void;
 /** One replacement operation observed while folding a session surface. */