1/**

2 * Named wire types for the DeepSeek Harness SDK runtime protocol: the three

3 * request/result pairs and the four server-to-client notification payloads

4 * exchanged over the newline-delimited JSON-RPC stdio transport. The server

5 * plugin (`@deepseek-ai/dsh-sdk-jsonrpc-server`) and SDK clients share these shapes;

6 * `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.

7 *

8 * @module @deepseek-ai/dsh-sdk-protocol/types

9 */

10

11import type { ContentBlock, ReasoningEffortId } from '@deepseek-ai/dsh-llm'

12import type { SessionEvent } from '@deepseek-ai/dsh-session'

13import type { SubagentStopReason } from '@deepseek-ai/dsh-subagent'

14

15/** Parameters for the process-wide SDK handshake. */

16export interface InitializeParams {

17 /** Working directory recorded on every SDK-created session's header. */

18 cwd: string

19 /** Provider route every SDK-created agent runs on. */

20 provider: string

21 /** Model name every SDK-created agent runs on (the server may mount a fallback adapter; see `HarnessSdkJsonRpcServer.initialize`). */

22 model: string

23 /** Optional adapter-owned reasoning effort for the selected provider/model route. */

24 reasoningEffort?: ReasoningEffortId

25 /** Optional positive output-token cap inherited by SDK-created agents and their in-process descendants. */

26 maxTokens?: number

27}

28

29/** Wire-stable server identity returned by initialization. */

30export interface InitializeResult {

31 /** Wire-stable server identity (`deepseek-harness-sdk-runtime`) and version. */

32 serverInfo: { name: string; version: string }

33}

34

35/** One user turn on one SDK session. */

36export interface SessionPromptParams {

37 /** The SDK-side session id; an unknown id lazily creates the agent+session pair. */

38 sessionId: string

39 /** The prompt content blocks, sent verbatim as the user message. */

40 contentBlocks: SdkPromptContentBlock[]

41}

42

43/** Inline raster input admitted into the runtime's durable attachment store. */

44export interface SdkEncodedImageBlock {

45 type: 'image'

46 /** Canonical base64-encoded raster bytes. */

47 data: string

48 /** Declared raster MIME type, verified during admission. */

49 mimeType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'

50}

51

52/** SDK prompt input: ordinary durable blocks plus inline images awaiting admission. */

53export type SdkPromptContentBlock = ContentBlock | SdkEncodedImageBlock

54

55/** Durable enqueue receipt for one prompt. */

56export interface SessionPromptResult {

57 /** Identity of the queued user message. */

58 messageId: string

59}

60

61/** Deployment-mapped SDK outcome: `ok` for an accepted result, `error` otherwise. */

62export type SdkRunStatus = 'ok' | 'error'

63

64/** `session.event` payload: one session-log event, streamed as it is recorded. */

65export interface SessionEventNotification {

66 /** Session the event belongs to (every session in the runtime, not only SDK-created ones). */

67 sessionId: string

68 /** The full session-log event envelope. */

69 event: SessionEvent

70}

71

72/** Whole-agent lifecycle state for one session. */

73export interface SessionStatusNotification {

74 /** Session whose live agent changed status. */

75 sessionId: string

76 /** The whole-agent state after the transition. */

77 status: 'idle' | 'running'

78}

79

80/** `subagent.started` payload: an in-runtime child session was created. */

81export interface SubagentStartedNotification {

82 /** The delegating session. */

83 parentSessionId: string

84 /** The new child session. */

85 childSessionId: string

86}

87

88/** `subagent.finished` payload: an in-process subagent run ended (remote runs are not reported). */

89export interface SubagentFinishedNotification {

90 /** Subagent provider name that ran the child. */

91 provider: string

92 /** The child agent's id (equals {@link childSessionId} for local runs). */

93 agentId: string

94 /** The delegating session. */

95 parentSessionId: string

96 /** The child session. */

97 childSessionId: string

98 /** Deployment-mapped run outcome. */

99 status: SdkRunStatus

100 /** The provider-reported stop reason. */

101 stopReason: SubagentStopReason

102 /** The child's selected assistant output; absent when the child produced none. */

103 lastAssistantMessage?: ContentBlock[]

104}

105

106/** Server-to-client notifications by JSON-RPC method name. */

107export interface HarnessSdkNotificationMap {

108 'session.event': SessionEventNotification

109 'session.status': SessionStatusNotification

110 'subagent.started': SubagentStartedNotification

111 'subagent.finished': SubagentFinishedNotification

112}

113

114/** Client-to-server request methods with their param and result shapes. */

115export interface HarnessSdkRequestMap {

116 'initialize': { params: InitializeParams; result: InitializeResult }

117 'session/prompt': { params: SessionPromptParams; result: SessionPromptResult }

118 'shutdown': { params: undefined; result: Record<string, never> }

119}