1/** Public Agent Teams identities, durable records, and service request values. */

2

3import type { Branded } from '@deepseek-ai/dsh-brand'

4import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'

5import type { SessionId } from '@deepseek-ai/dsh-session/types'

6

7/** Identifies the implicit team rooted at one top-level Session. */

8export type TeamId = Branded<'TeamId'>

9

10/**

11 * Brand one root Session identity as its implicit Team identity.

12 * @param id - Root Session identity.

13 * @returns the same string branded as a Team identity.

14 */

15export function TeamId(id: SessionId | string): TeamId {

16 return id as TeamId

17}

18

19/** Stable identifier for one task in a Team. */

20export type TeamTaskId = Branded<'TeamTaskId'>

21

22/**

23 * Brand a validated task id.

24 * @param id - Team-local task identity.

25 * @returns the same string branded as a Team task identity.

26 */

27export function TeamTaskId(id: string): TeamTaskId {

28 return id as TeamTaskId

29}

30

31/** Stable identifier for one durable peer message. */

32export type TeamMessageId = Branded<'TeamMessageId'>

33

34/**

35 * Brand a generated peer-message id.

36 * @param id - Durable mailbox message identity.

37 * @returns the same string branded as a Team message identity.

38 */

39export function TeamMessageId(id: string): TeamMessageId {

40 return id as TeamMessageId

41}

42

43/** Durable teammate lifecycle. */

44export type TeamMemberPhase = 'provisioning' | 'active' | 'failed'

45

46/** Whole durable value written on every teammate lifecycle change. */

47export interface TeamMemberSnapshot {

48 readonly id: SessionId

49 readonly name: string

50 readonly description: string

51 readonly provider: string

52 readonly context: 'fresh' | 'fork'

53 readonly phase: TeamMemberPhase

54 readonly error?: string

55}

56

57/** Current runtime-enriched roster row. */

58export interface TeamMemberView {

59 readonly id: SessionId

60 readonly name: string

61 readonly role: 'lead' | 'teammate'

62 readonly status: 'running' | 'inactive' | 'provisioning' | 'failed'

63 readonly description?: string

64 readonly provider?: string

65 readonly context?: 'fresh' | 'fork'

66 readonly model?: string

67 readonly diagnostics: string[]

68}

69

70/** Durable task lifecycle. */

71export type TeamTaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted'

72

73/** Whole durable task snapshot; every mutation increments {@link revision}. */

74export interface TeamTaskSnapshot {

75 readonly id: TeamTaskId

76 readonly revision: number

77 readonly subject: string

78 readonly description: string

79 readonly status: TeamTaskStatus

80 readonly ownerId?: SessionId

81 readonly blockedBy: TeamTaskId[]

82 readonly writeScopes: string[]

83}

84

85/** Runtime-enriched task view returned to tools and hosts. */

86export interface TeamTaskView {

87 readonly id: TeamTaskId

88 readonly revision: number

89 readonly subject: string

90 readonly description: string

91 readonly status: TeamTaskStatus

92 readonly blockedBy: TeamTaskId[]

93 readonly writeScopes: string[]

94 readonly ownerName?: string

95 readonly ready: boolean

96 readonly writeScopeWarnings: string[]

97}

98

99/** One durable roster row published through the `agentTeam` Session projection. */

100export interface TeamMemberProjection {

101 readonly id: SessionId

102 readonly name: string

103 readonly role: 'lead' | 'teammate'

104 /** Durable lifecycle; the Lead row is always `active`. Turn activity comes from Session status. */

105 readonly phase: TeamMemberPhase

106 readonly error?: string

107}

108

109/**

110 * Durable Team state published to browser clients through the Lead Session's

111 * `agentTeam` projection. `failure` names the first rejected persisted Team

112 * record; members and tasks then stay at the last valid state.

113 */

114export interface TeamProjection {

115 readonly members: TeamMemberProjection[]

116 readonly tasks: TeamTaskView[]

117 readonly failure?: string

118}

119

120declare module '@deepseek-ai/dsh-session-projection/types' {

121 interface SessionProjectionMap {

122 /** Durable roster and non-deleted task board of the Team rooted at the projected Session. */

123 agentTeam: TeamProjection

124 }

125}

126

127/** One peer message retained until its target Session records it. */

128export interface TeamMessageSnapshot {

129 readonly id: TeamMessageId

130 readonly senderId: SessionId

131 readonly senderName: string

132 readonly targetId: SessionId

133 readonly content: ContentBlock[]

134}

135

136/** Source retained by the target Session for durable mailbox de-duplication. */

137export interface TeamMessageSource {

138 readonly kind: 'team-message'

139 readonly teamId: TeamId

140 readonly messageId: TeamMessageId

141 readonly senderId: SessionId

142 readonly senderName: string

143}

144

145declare module '@deepseek-ai/dsh-llm' {

146 interface MessageSourceMap {

147 'team-message': TeamMessageSource

148 }

149}

150

151/** Team-service deployment limits. */

152export interface Config {

153 /** Maximum immutable teammate names retained by one Team. */

154 readonly maxMembers?: number

155 /** Maximum non-deleted tasks retained by one Team. */

156 readonly maxTasks?: number

157 /** Maximum queued-minus-delivered messages for one target member. */

158 readonly maxPendingMessagesPerMember?: number

159 /** Maximum UTF-8 bytes in one complete sender-framed delivery. */

160 readonly maxMessageBytes?: number

161 /** Maximum milliseconds allowed for Team-owned runtime disposal. */

162 readonly disposalTimeoutMs?: number

163}

164

165/** Input for creating one durable teammate. */

166export interface SpawnTeammateRequest {

167 readonly name: string

168 readonly description: string

169 readonly prompt: ContentBlock[]

170 readonly context: 'fresh' | 'fork'

171 readonly provider: string

172 readonly signal: AbortSignal

173}

174

175/** Result after one teammate reaches a durable active or failed edge. */

176export interface SpawnTeammateResult {

177 readonly member: TeamMemberView

178}

179

180/** Input for one durable peer message. */

181export interface SendTeamMessageRequest {

182 readonly target: string

183 readonly content: ContentBlock[]

184 readonly signal: AbortSignal

185}

186

187/** Result after a peer message enters the durable mailbox. */

188export interface SendTeamMessageResult {

189 readonly messageId: TeamMessageId

190 readonly status: 'accepted' | 'queued'

191}

192

193/** Input for creating one shared task. */

194export interface CreateTeamTaskRequest {

195 readonly subject: string

196 readonly description: string

197 readonly blockedBy?: readonly TeamTaskId[]

198 readonly writeScopes?: readonly string[]

199}

200

201/** Supported task mutation actions. */

202export type TeamTaskAction =

203 | 'claim'

204 | 'release'

205 | 'edit'

206 | 'set_dependencies'

207 | 'complete'

208 | 'reopen'

209 | 'reassign'

210 | 'delete'

211

212/** Compare-and-set mutation of one shared task. */

213export interface UpdateTeamTaskRequest {

214 readonly taskId: TeamTaskId

215 readonly expectedRevision: number

216 readonly action: TeamTaskAction

217 readonly subject?: string

218 readonly description?: string

219 readonly blockedBy?: readonly TeamTaskId[]

220 readonly writeScopes?: readonly string[]

221 readonly owner?: string

222}

223

224/** Result of waiting for Team activity. */

225export interface TeamWaitResult {

226 readonly timedOut: boolean

227}

228

229declare module '@deepseek-ai/dsh-session/types' {

230 interface SessionEventMap {

231 /** Whole teammate lifecycle value, stored only in the Team Lead Session. */

232 'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot }

233 /** Whole shared-task value, stored only in the Team Lead Session. */

234 'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot }

235 /** Durable mailbox enqueue, stored before delivery is attempted. */

236 'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot }

237 /** Durable acknowledgement that the target Session recorded the message. */

238 'team/message/delivered': {

239 version: 2

240 teamId: TeamId

241 messageId: TeamMessageId

242 targetId: SessionId

243 }

244 }

245}