Files
deepseek-harness/packages/session/session-format-v3-to-v4/tests/developer.spec.ts
T
Yixiang TuandTianyi Cui e0bd7e1960 feat(session): add developer changes using historical tool schemas
Session V4 reserves developer-role messages for incremental model-visible
session changes. The role, tool addition/removal blocks, and deferred-loading
marker need a durable representation before independent provider and UI
integrations can emit or consume them. Known developer events must match an
open turn and step; unsupported providers and UI consumers fail explicitly.

Request headers already capture full tool definitions. Persisting another
ToolSchema in each addition would duplicate Session information and create
two definitions that could drift. Additions therefore store toolName, and
the containing developer event uses headerSeq to select one earlier known
request/header for all its additions. A same-name replacement keeps its
historical definition identity through restart, fork and surface changes.
Removals require no definition copy, and ordinary developer messages omit
headerSeq. Generic sourceEventSeqs remains independent derivation metadata.

The rejected inline tool field is optional never with @persistenceReserved.
The schema extractor retains that uninhabited slot, so permitting a future
value requires a format bump instead of being mistaken for compatible
optional metadata. Unrelated optional fields remain additive and readable.

Native and Session admission reject missing, forward, non-header, unknown,
ambiguous and incomplete referenced definitions, and reject the retired
inline tool field. Validate complete schema fields only for referenced
definitions, preserving unrelated header behavior and extra JSON metadata.
Unknown ignorable records remain opaque. Empty developer nodes retain their
surface position without producing a message or shadowing the system head.
No automatic emitter, provider activation, UI implementation, or speculative
public resolver is added.

Keep the core-owned developer source binding beside the introduced role,
including the request-only type rejection and attribution round trips. Update
consumer guards, SDK/snapshot handling, bilingual owner documentation, and
the same unreleased V4 acknowledgement. Keep earlier tool/source migration
work and its documentation in the parent. Preserve the existing recorded
Cordis inspection generation from the original developer change.

Integration keeps the final source layer as the sole parent and preserves
master's Messages input filtering, empty-user omission, empty tool results,
and system-update placement. Developer/deferred guards still run before
conversion. Native V4 admission, header references, reservation declarations,
and generic tooling match the validated marker candidate. Parent-owned
fixture and generator fixes remain in the parent.

Earlier feature validation passed full build, full lint, 41 doc-sync gates,
and 16 hygiene gates. The unchanged native implementation retains that evidence.
The focused Session/V4/request-input run passes 884 tests across 38 files with
100% statement, branch, function and line coverage for the V3-to-V4 package
and Session surface. Consumer tests pass 482 with one existing skip; tool,
message and optional-field tests pass 146. Cordis inspection and compaction
replays pass in both source and built modes (two cases per mode). Ten invalid
referenced-definition/unknown-header controls failed before their scoped
guards and pass after them.

Reservation validation: the actual generated developer root records tool as
optional primitive never. Widening it requires a bump, while traceId remains
additive and preserved; all 85 focused reader/classifier tests pass.

Final-parent validation: 205 tests across eight provider, type, catalog,
Session and native-format files pass. The preserved parent fixture verifies
Messages input-history replay; runtime/declaration and parent-owned-file
comparisons show no loss during the final rebase.

Co-authored-by: Tianyi Cui <[email protected]>
2026-09-18 19:08:11 +08:00

303 lines
17 KiB
TypeScript

/** Developer messages and deferred schemas survive native V4 persistence. */
import { describe, expect, it } from 'vitest'
import { SessionFormatEventCollector } from '@deepseek-ai/dsh-session-format'
import type { SessionFormatEvent, SessionFormatJsonObject } from '@deepseek-ai/dsh-session-format'
import { assertV4RowAdmission, releasedV4SessionFormatCodec as codec, restoreReleasedV4Artifact } from '../src/index.ts'
const header = { version: 4, id: 'developer', createdAt: 1, isSeeded: false, delegationDepth: 0 }
const message = { id: 'developer-1', role: 'developer', source: { kind: 'tool-registry' }, content: [{ type: 'tool-addition', toolName: 'search' }, { type: 'tool-removal', toolName: 'old' }] }
const developer: SessionFormatEvent = { type: 'developer/message', seq: 3, time: 4, surfaceOp: 'append', data: { turn: 1, step: 1, headerSeq: 2, message } }
const request: SessionFormatEvent = { type: 'request/header', seq: 2, time: 3, data: {
reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools: [{ name: 'search', description: 'Search', parameters: {}, deferLoading: true }] },
} }
function events(): SessionFormatEvent[] {
return [
{ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } },
{ type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
request, developer,
{ type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
{ type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
]
}
function roundTrip(input: SessionFormatEvent[]): SessionFormatEvent[] {
const decoder = codec.createDecoder(codec.encodeHeader(header, 0), 'strict')
const output = new SessionFormatEventCollector()
for (const event of input) decoder.decodeRow(codec.encodeEvent(event), output)
decoder.finish(output)
return output.values
}
describe('V4 developer messages', () => {
it('round trips native messages and deferred schemas without rewriting native payloads', () => {
const input = events()
expect(roundTrip(input)).toEqual(input)
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(restoreReleasedV4Artifact(artifact, new Set(input.map(event => event.type)))).toBe(artifact)
})
it('preserves additional JSON fields in developer data, messages, sources, and blocks', () => {
const input = events()
input[3] = { ...developer, data: { turn: 1, step: 1, headerSeq: 2, metadata: { future: true }, message: {
...message, metadata: ['retained'], source: { kind: 'tool-registry', future: 1 }, content: [
{ type: 'tool-addition', toolName: 'search', future: true },
{ type: 'tool-removal', toolName: 'old', future: true },
],
} } }
input[2] = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools: [{ name: 'search', description: 'Search', parameters: {}, deferLoading: true, future: { retained: true } }] } } }
expect(roundTrip(input)).toEqual(input)
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(restoreReleasedV4Artifact(artifact, new Set(input.map(event => event.type)))).toBe(artifact)
})
it.each([undefined, null, '', 1])('rejects a malformed addition name %#', (toolName) => {
const row = { ...developer, data: { turn: 1, step: 1, headerSeq: 2, message: {
...message, content: [{ type: 'tool-addition', ...(toolName === undefined ? {} : { toolName }) }],
} } }
expect(() => codec.encodeEvent(row)).toThrow('nonempty toolName')
expect(() => { assertV4RowAdmission(row) }).toThrow('nonempty toolName')
})
it('refuses an inline definition even when a header and name are present', () => {
const row = { ...developer, data: { turn: 1, step: 1, headerSeq: 2, message: {
...message, content: [{ type: 'tool-addition', toolName: 'search', tool: { name: 'search', description: 'Duplicate', parameters: {} } }],
} } }
expect(() => codec.encodeEvent(row)).toThrow('omit inline tool definitions')
expect(() => { assertV4RowAdmission(row) }).toThrow('omit inline tool definitions')
})
it.each([undefined, null, -1, -0, 1.5, '2'])('rejects an absent or invalid addition header sequence %#', (headerSeq) => {
const row = { ...developer, data: { turn: 1, step: 1, message, ...(headerSeq === undefined ? {} : { headerSeq }) } }
expect(() => codec.encodeEvent(row)).toThrow('headerSeq')
expect(() => { assertV4RowAdmission(row) }).toThrow('headerSeq')
})
it('requires removal-only messages to omit the header sequence', () => {
const row = { ...developer, data: { turn: 1, step: 1, headerSeq: 2, message: {
...message, content: [{ type: 'tool-removal', toolName: 'search' }],
} } }
expect(() => codec.encodeEvent(row)).toThrow('omit headerSeq')
})
it.each([0, 3, 50])('refuses a non-header or non-earlier schema reference %s', (headerSeq) => {
const input = events()
input[3] = { ...developer, data: { turn: 1, step: 1, headerSeq, message } }
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, new Set(input.map(event => event.type))))
.toThrow(/headerSeq.*earlier/)
})
it.each([
{ tools: undefined },
{ tools: [null] },
{ tools: [{ name: 'different', description: '', parameters: {} }] },
{ tools: [{ name: 'search', description: 'First', parameters: {} }, { name: 'search', description: 'Second', parameters: {} }] },
])('refuses missing or ambiguous names in the referenced header %#', ({ tools }) => {
const input = events()
input[2] = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, ...(tools === undefined ? {} : { tools }) } } }
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, new Set(input.map(event => event.type))))
.toThrow('exactly one tool')
})
it.each([
{ name: 'search' },
{ name: 'search', description: null, parameters: {} },
{ name: 'search', description: '', parameters: [] },
{ name: 'search', description: '', parameters: null },
])('refuses an incomplete referenced definition %#', (tool) => {
const input = events()
input[2] = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools: [tool] } } }
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, new Set(input.map(event => event.type))))
.toThrow('complete tool definition')
})
it.each([null, request.data])('does not interpret an unknown ignorable header referenced by a known developer event %#', (data) => {
const input = events()
input[2] = { ...request, ignorable: true, data }
const known = new Set(input.map(event => event.type))
known.delete('request/header')
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, known)).toThrow('known request/header')
input[3] = { ...developer, ignorable: true, data: { opaque: true, headerSeq: { future: true } }, surfaceOp: { future: true } }
known.delete('developer/message')
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(restoreReleasedV4Artifact(artifact, known)).toBe(artifact)
})
it('keeps historical schema references when compaction shadows their developer nodes', () => {
const input = [
...events().slice(0, 4),
{ type: 'compaction/prune', seq: 4, time: 5, data: { shadowedRange: { start: 3, end: 3 }, shadowedSeqs: [3], shadowedTokenCount: 0 } },
...events().slice(4).map(event => ({ ...event, seq: event.seq + 1 })),
]
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(restoreReleasedV4Artifact(artifact, new Set(input.map(event => event.type)))).toBe(artifact)
expect(input[2]).toEqual(request)
})
it.each([null, [], 'invalid'])('refuses non-object developer data %j before recovery', (data) => {
const row = { ...developer, data }
expect(() => codec.encodeEvent(row)).toThrow('developer/message data must be an object')
expect(() => { assertV4RowAdmission(row) }).toThrow('developer/message data must be an object')
})
it.each([{ turn: 1, step: 1 }, { turn: 1, step: 1, message: null }])(
'rejects malformed developer event fields %#', (data) => {
expect(() => codec.encodeEvent({ ...developer, data })).toThrow('requires turn, step, and a developer message')
},
)
it('leaves malformed legacy stream chunks to canonical decoding', () => {
expect(() => { assertV4RowAdmission({ type: 'assistant/attempt', seq: 2, time: 3,
data: { stream: [{ type: 'chunk', chunk: null }] },
}) }).not.toThrow()
})
it.each(['agent/inbox/spliced', 'session/title-llm-request'])('leaves malformed ordinary arrays in %s to canonical decoding', (type) => {
const key = type === 'agent/inbox/spliced' ? 'inserted' : 'messages'
expect(() => { assertV4RowAdmission({ type, seq: 2, time: 3, data: { [key]: null } }) }).not.toThrow()
})
it.each([false, true])('preserves ordinary tools alongside deferred tools: %s', (mixed) => {
const ordinary = { name: 'ordinary', description: 'Ordinary', parameters: {} }
const tools = mixed ? [ordinary, { ...ordinary, name: 'deferred', deferLoading: true }] : [ordinary]
const input = events()
input[2] = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools } } }
expect(roundTrip(input)).toEqual(input)
})
it('does not interpret tool entries without deferred markers', () => {
const row = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools: [null] } } }
expect(() => { assertV4RowAdmission(row) }).not.toThrow()
})
it('preserves the historical header while replacing a developer surface node', () => {
const replacement = { ...developer, seq: 4, time: 5, surfaceOp: { op: 'replace', startSeq: 3, endSeq: 3 }, sourceEventSeqs: [3],
data: { turn: 1, step: 1, headerSeq: 2, message: { ...message, id: 'developer-2' } } }
const input = [...events().slice(0, 4), replacement, ...events().slice(4).map(event => ({ ...event, seq: event.seq + 1 }))]
expect(roundTrip(input)).toEqual(input)
const restored = restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, new Set(input.map(event => event.type)))
expect(restored.events).toEqual(input)
})
it.each([false, null, 'true', 1])('rejects invalid deferred marker %j', (deferLoading) => {
const row = { ...request, data: { reason: 'initial', header: { config: { provider: 'test', model: 'test' }, tools: [{ name: 'search', description: '', parameters: {}, deferLoading }] } } }
expect(() => codec.encodeEvent(row)).toThrow('deferLoading')
expect(() => { assertV4RowAdmission(row) }).toThrow('deferLoading')
})
it.each([
{ ...message, role: 'user' },
{ ...message, id: '' },
{ ...message, source: { kind: 'plugin' } },
{ ...message, content: [{ type: 'tool-addition', toolName: '' }] },
{ ...message, content: [{ type: 'tool-removal', toolName: '' }] },
])('rejects malformed developer message %#', (invalid) => {
const row = { ...developer, data: { turn: 1, step: 1, message: invalid } }
expect(() => codec.encodeEvent(row)).toThrow()
expect(() => { assertV4RowAdmission(row) }).toThrow()
})
it('preserves developer messages inside an inherited prefix', () => {
const inheritedHeader = { ...header, isSeeded: true, parentSession: 'parent' }
const input = events()
const inherited = [
...input.slice(0, 4),
{ type: 'session/end-seed', seq: 4, time: 5, data: { inherited: true } },
...input.slice(4).map(event => ({ ...event, seq: event.seq + 1 })),
]
const decoder = codec.createDecoder(codec.encodeHeader(inheritedHeader, 4), 'strict')
const output = new SessionFormatEventCollector()
for (const event of inherited) decoder.decodeRow(codec.encodeEvent(event), output)
expect(decoder.finish(output)).toBe(4)
expect(output.values).toEqual(inherited)
const artifact = { header: inheritedHeader, events: output.values, inheritedEventCount: 4 }
expect(restoreReleasedV4Artifact(artifact, new Set(inherited.map(event => event.type)))).toBe(artifact)
})
it('refuses developer history when the reader does not know the event type', () => {
const input = events()
const known = new Set(input.map(event => event.type))
known.delete('developer/message')
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, known)).toThrow('unknown event type')
})
it('checks request coordinates and the open step', () => {
const input = events()
input[3] = { ...developer, data: { ...(developer.data as SessionFormatJsonObject), step: 2 } }
const known = new Set(input.map(event => event.type))
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, known)).toThrow(/open.*step/)
expect(() => codec.encodeEvent({ ...developer, data: { turn: 0, step: 1, message } })).toThrow('positive')
})
it.each(['user', 'system', 'assistant', 'tool'])('rejects tool-change blocks in %s messages', (role) => {
for (const type of ['tool-addition', 'tool-removal']) {
const source = role === 'system' ? { kind: 'system-prompt' }
: role === 'assistant' ? { kind: 'model', provider: 'test', model: 'test' }
: role === 'tool' ? { kind: 'tool', callId: 'call' } : { kind: 'user' }
const invalid = { ...message, role, source, content: [{ type, toolName: 'search' }],
...role === 'tool' ? { toolCallId: 'call', isError: false } : {},
}
const eventType = role === 'tool' ? 'tool/result' : `${role}/message`
const row = { ...developer, type: eventType, data: role === 'user' ? invalid : { turn: 1, step: 1, message: invalid } }
expect(() => codec.encodeEvent(row)).toThrow('developer role')
expect(() => { assertV4RowAdmission(row) }).toThrow('developer role')
const decoder = codec.createDecoder(codec.encodeHeader(header, 0), 'strict')
expect(() => { decoder.decodeRow(row, new SessionFormatEventCollector()) }).toThrow('developer role')
const input = events()
input[3] = row
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(() => restoreReleasedV4Artifact(artifact, new Set(input.map(event => event.type)))).toThrow('developer role')
}
})
it.each(['user/message', 'system/message', 'assistant/message', 'tool/result'])('rejects developer role inside %s before payload recovery', (type) => {
const row = { ...developer, type, data: type === 'user/message' ? message : { turn: 1, step: 1, message } }
expect(() => codec.encodeEvent(row)).toThrow(/must occur together|requires a tool-role message/)
expect(() => { assertV4RowAdmission(row) }).toThrow('must occur together')
const decoder = codec.createDecoder(codec.encodeHeader(header, 0), 'strict')
expect(() => { decoder.decodeRow(row, new SessionFormatEventCollector()) }).toThrow('must occur together')
})
it.each(['agent/inbox/spliced', 'session/title-llm-request'])('rejects developer role in %s message arrays', (type) => {
const key = type === 'agent/inbox/spliced' ? 'inserted' : 'messages'
const row = { type, seq: 3, time: 4, data: { [key]: [null, message] } }
expect(() => codec.encodeEvent(row)).toThrow('must occur together')
expect(() => { assertV4RowAdmission(row) }).toThrow('must occur together')
const decoder = codec.createDecoder(codec.encodeHeader(header, 0), 'strict')
expect(() => { decoder.decodeRow(row, new SessionFormatEventCollector()) }).toThrow('must occur together')
const input = events()
input[3] = row
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(() => restoreReleasedV4Artifact(artifact, new Set(input.map(event => event.type)))).toThrow('must occur together')
})
it('retains unknown ignorable developer records without interpreting their payload or surface', () => {
const input = events()
input[3] = { ...developer, ignorable: true, data: { future: true }, surfaceOp: { future: true } }
const known = new Set(input.map(event => event.type))
known.delete('developer/message')
const artifact = { header, events: input, inheritedEventCount: 0 }
expect(restoreReleasedV4Artifact(artifact, known)).toBe(artifact)
})
it('still validates known ignorable developer records', () => {
const input = events()
input[3] = { ...developer, ignorable: true, data: { turn: 1, step: 2, headerSeq: 2, message } }
const known = new Set(input.map(event => event.type))
expect(() => restoreReleasedV4Artifact({ header, events: input, inheritedEventCount: 0 }, known)).toThrow(/open.*step/)
})
it.each(['tool-addition', 'tool-removal'])('rejects %s outside developer content, including streamed blocks', (type) => {
const block = { type, toolName: 'search' }
const payloads = [
{ type: 'compaction/summary', data: { summary: [block] } },
{ type: 'compaction/summary', data: { rawOutput: [block] } },
{ type: 'assistant/attempt', data: { stream: [{ type: 'chunk', chunk: { type: 'block-end', block } }] } },
{ type: 'assistant/attempt', data: { stream: [{ type: 'chunk', chunk: { type: 'block-start', blockType: type } }] } },
{ type: 'agent/inbox/spliced', data: { inserted: [{ ...message, role: 'user', content: [block] }] } },
{ type: 'session/title-llm-request', data: { messages: [{ ...message, role: 'user', content: [block] }] } },
]
for (const payload of payloads) {
expect(() => { assertV4RowAdmission({ seq: 2, time: 3, ...payload }) }).toThrow('developer role')
}
})
})