@sixb/server 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/README.md +3 -3
  2. package/dist/artifacts/frame.d.ts.map +1 -1
  3. package/dist/auth/scope.d.ts +3 -0
  4. package/dist/auth/scope.d.ts.map +1 -1
  5. package/dist/auth/shared-access.d.ts +23 -0
  6. package/dist/auth/shared-access.d.ts.map +1 -1
  7. package/dist/connectors/http.d.ts +6 -1
  8. package/dist/connectors/http.d.ts.map +1 -1
  9. package/dist/index.js +2777 -683
  10. package/dist/index.js.map +41 -34
  11. package/dist/live/awareness.d.ts +48 -0
  12. package/dist/live/awareness.d.ts.map +1 -0
  13. package/dist/live/room.d.ts +198 -0
  14. package/dist/live/room.d.ts.map +1 -0
  15. package/dist/live/rooms.d.ts +67 -0
  16. package/dist/live/rooms.d.ts.map +1 -0
  17. package/dist/registerRoutes.d.ts.map +1 -1
  18. package/dist/routes/actions.d.ts +3 -3
  19. package/dist/routes/agent-approvals.d.ts +10 -10
  20. package/dist/routes/agent-children.d.ts +2 -2
  21. package/dist/routes/agent-computers.d.ts +32 -0
  22. package/dist/routes/agent-computers.d.ts.map +1 -1
  23. package/dist/routes/agent-runners.d.ts.map +1 -1
  24. package/dist/routes/agents.d.ts +48 -48
  25. package/dist/routes/artifact-frames.d.ts +2 -1
  26. package/dist/routes/artifact-frames.d.ts.map +1 -1
  27. package/dist/routes/artifacts.d.ts +1713 -178
  28. package/dist/routes/artifacts.d.ts.map +1 -1
  29. package/dist/routes/auth.d.ts +21 -21
  30. package/dist/routes/connector-connection-runs.d.ts +124 -5
  31. package/dist/routes/connector-connection-runs.d.ts.map +1 -1
  32. package/dist/routes/connector-connections.d.ts +9 -1
  33. package/dist/routes/connector-connections.d.ts.map +1 -1
  34. package/dist/routes/datasets.d.ts +5 -5
  35. package/dist/routes/events.d.ts +4 -4
  36. package/dist/routes/lake.d.ts +91 -0
  37. package/dist/routes/lake.d.ts.map +1 -0
  38. package/dist/routes/links.d.ts +6 -6
  39. package/dist/routes/logs.d.ts +2 -2
  40. package/dist/routes/model-generations.d.ts +2 -2
  41. package/dist/routes/objects.d.ts +6 -6
  42. package/dist/routes/objects.d.ts.map +1 -1
  43. package/dist/routes/observed-agent-threads.d.ts +7 -7
  44. package/dist/routes/ontology.d.ts +6 -6
  45. package/dist/routes/pipelines.d.ts +8 -4
  46. package/dist/routes/pipelines.d.ts.map +1 -1
  47. package/dist/routes/projections.d.ts +2 -2
  48. package/dist/routes/share-grants.d.ts +9 -9
  49. package/dist/routes/shared-access.d.ts +57 -2
  50. package/dist/routes/shared-access.d.ts.map +1 -1
  51. package/dist/routes/status.d.ts +11 -15
  52. package/dist/routes/status.d.ts.map +1 -1
  53. package/dist/routes/syncs.d.ts +5 -2
  54. package/dist/routes/syncs.d.ts.map +1 -1
  55. package/dist/routes/telemetry.d.ts +7 -7
  56. package/dist/routes/webhooks.d.ts.map +1 -1
  57. package/dist/routes/workflows.d.ts +3 -3
  58. package/dist/routes/ws/artifacts.d.ts +57 -0
  59. package/dist/routes/ws/artifacts.d.ts.map +1 -0
  60. package/dist/routes/ws/events.d.ts +8 -7
  61. package/dist/routes/ws/events.d.ts.map +1 -1
  62. package/dist/routes/ws/index.d.ts +2 -1
  63. package/dist/routes/ws/index.d.ts.map +1 -1
  64. package/dist/routes/ws/logs.d.ts +10 -10
  65. package/dist/routes/ws/shared-sockets.d.ts +52 -0
  66. package/dist/routes/ws/shared-sockets.d.ts.map +1 -0
  67. package/dist/schemas/actions.d.ts +7 -7
  68. package/dist/schemas/activity.d.ts +8 -8
  69. package/dist/schemas/agent-approvals.d.ts +27 -27
  70. package/dist/schemas/agents.d.ts +195 -154
  71. package/dist/schemas/agents.d.ts.map +1 -1
  72. package/dist/schemas/ai-accounting.d.ts +12 -12
  73. package/dist/schemas/artifacts.d.ts +2106 -127
  74. package/dist/schemas/artifacts.d.ts.map +1 -1
  75. package/dist/schemas/auth.d.ts +63 -63
  76. package/dist/schemas/connectors.d.ts +180 -20
  77. package/dist/schemas/connectors.d.ts.map +1 -1
  78. package/dist/schemas/datasets.d.ts +44 -44
  79. package/dist/schemas/event-payloads.d.ts +2 -2
  80. package/dist/schemas/events.d.ts +26 -26
  81. package/dist/schemas/events.d.ts.map +1 -1
  82. package/dist/schemas/files.d.ts +12 -0
  83. package/dist/schemas/files.d.ts.map +1 -1
  84. package/dist/schemas/lake.d.ts +251 -0
  85. package/dist/schemas/lake.d.ts.map +1 -0
  86. package/dist/schemas/lineage.d.ts +56 -56
  87. package/dist/schemas/logs.d.ts +18 -18
  88. package/dist/schemas/models.d.ts +4 -4
  89. package/dist/schemas/objects.d.ts.map +1 -1
  90. package/dist/schemas/ontology.d.ts +14 -14
  91. package/dist/schemas/pipelines.d.ts +70 -48
  92. package/dist/schemas/pipelines.d.ts.map +1 -1
  93. package/dist/schemas/projections.d.ts +14 -14
  94. package/dist/schemas/projections.d.ts.map +1 -1
  95. package/dist/schemas/share-grants.d.ts +30 -30
  96. package/dist/schemas/shared-access.d.ts +17 -4
  97. package/dist/schemas/shared-access.d.ts.map +1 -1
  98. package/dist/schemas/status.d.ts +59 -79
  99. package/dist/schemas/status.d.ts.map +1 -1
  100. package/dist/schemas/syncs.d.ts +26 -10
  101. package/dist/schemas/syncs.d.ts.map +1 -1
  102. package/dist/schemas/telemetry.d.ts +26 -26
  103. package/dist/schemas/workflows.d.ts +19 -19
  104. package/dist/server.d.ts +13 -0
  105. package/dist/server.d.ts.map +1 -1
  106. package/dist/utils/ws.d.ts +3 -0
  107. package/dist/utils/ws.d.ts.map +1 -1
  108. package/package.json +11 -7
  109. package/src/artifacts/frame.ts +4 -13
  110. package/src/auth/scope.ts +10 -1
  111. package/src/auth/shared-access.ts +108 -12
  112. package/src/connectors/http.ts +35 -1
  113. package/src/live/README.md +136 -0
  114. package/src/live/awareness.ts +141 -0
  115. package/src/live/room.ts +933 -0
  116. package/src/live/rooms.ts +288 -0
  117. package/src/registerRoutes.ts +2 -0
  118. package/src/routes/agent-computers.ts +59 -1
  119. package/src/routes/agent-runners.ts +1 -0
  120. package/src/routes/artifact-frames.ts +40 -12
  121. package/src/routes/artifacts.ts +713 -28
  122. package/src/routes/connector-connection-runs.ts +7 -12
  123. package/src/routes/connector-connections.ts +10 -7
  124. package/src/routes/lake.ts +73 -0
  125. package/src/routes/objects.ts +3 -9
  126. package/src/routes/pipelines.ts +1 -0
  127. package/src/routes/shared-access.ts +53 -1
  128. package/src/routes/status.ts +9 -4
  129. package/src/routes/syncs.ts +1 -0
  130. package/src/routes/webhooks.ts +44 -3
  131. package/src/routes/ws/artifacts.ts +138 -0
  132. package/src/routes/ws/events.ts +7 -2
  133. package/src/routes/ws/index.ts +13 -2
  134. package/src/routes/ws/shared-sockets.ts +152 -0
  135. package/src/schemas/agents.ts +11 -0
  136. package/src/schemas/artifacts.ts +255 -18
  137. package/src/schemas/connectors.ts +17 -2
  138. package/src/schemas/files.ts +12 -0
  139. package/src/schemas/lake.ts +53 -0
  140. package/src/schemas/objects.ts +1 -0
  141. package/src/schemas/pipelines.ts +2 -0
  142. package/src/schemas/projections.ts +2 -2
  143. package/src/schemas/shared-access.ts +16 -0
  144. package/src/schemas/status.ts +16 -22
  145. package/src/schemas/syncs.ts +2 -0
  146. package/src/server.ts +35 -4
  147. package/src/utils/ws.ts +7 -0
@@ -17,6 +17,17 @@ import {
17
17
  createArtifactFrame,
18
18
  serializeArtifactQueryResult,
19
19
  } from "@sixb/core/internal/artifacts/frames"
20
+ import {
21
+ boardPreview,
22
+ boardPreviewStatuses,
23
+ boardPreviews,
24
+ boardsReadLiveData,
25
+ } from "@sixb/core/internal/artifacts/publish"
26
+ import type {
27
+ ArtifactCommentRecord,
28
+ ArtifactRestorePointRecord,
29
+ PublishedArtifactVersion,
30
+ } from "@sixb/core/storage"
20
31
  import type { Elysia } from "elysia"
21
32
  import { ZodError } from "zod"
22
33
  import { accessTokenSecurityRequirement } from "../auth/access-token-boundary"
@@ -26,34 +37,53 @@ import {
26
37
  fileContentGetResponses,
27
38
  fileContentHeadResponses,
28
39
  } from "../files/content"
40
+ import { principalName } from "../live/awareness"
29
41
  import { OPENAPI_TAGS } from "../openapi/tags"
30
42
  import {
43
+ AddArtifactCommentBodySchema,
44
+ ArtifactBoardPreviewParamsSchema,
45
+ ArtifactBoardPreviewQuerySchema,
46
+ ArtifactChangeResponseSchema,
47
+ ArtifactCommentListResponseSchema,
48
+ ArtifactCommentParamsSchema,
49
+ ArtifactCommentSchema,
31
50
  ArtifactErrorResponseSchema,
32
51
  ArtifactFrameResponseSchema,
52
+ ArtifactHolderListResponseSchema,
33
53
  ArtifactListQuerySchema,
34
54
  ArtifactListResponseSchema,
35
55
  ArtifactParamsSchema,
36
56
  ArtifactQueryParamsSchema,
37
57
  ArtifactResponseSchema,
58
+ ArtifactRestorePointListResponseSchema,
59
+ ArtifactRestorePointParamsSchema,
60
+ ArtifactRestorePointSchema,
38
61
  ArtifactStateParamsSchema,
39
62
  ArtifactStateResponseSchema,
40
63
  ArtifactVersionParamsSchema,
41
64
  ArtifactVersionSchema,
42
65
  ClearArtifactStateResponseSchema,
66
+ DeleteArtifactCommentResponseSchema,
43
67
  DeleteArtifactResponseSchema,
44
68
  DeleteArtifactStateResponseSchema,
69
+ FreezeArtifactBodySchema,
45
70
  PublishArtifactBodySchema,
46
- PublishArtifactVersionBodySchema,
47
71
  PublishedArtifactResponseSchema,
72
+ ResolveArtifactCommentBodySchema,
73
+ RestoreArtifactBodySchema,
48
74
  SetArtifactStateBodySchema,
49
75
  SetArtifactStateResponseSchema,
76
+ UpdateArtifactBodySchema,
50
77
  } from "../schemas/artifacts"
51
- import { FileContentQuerySchema } from "../schemas/files"
78
+ import { FileContentQuerySchema, ShareGrantQuerySchema } from "../schemas/files"
52
79
  import { handleRouteError, parseOptionalInt, toIsoString } from "../utils/http"
53
80
  import { handleObjectQueryError } from "./objects"
54
81
 
55
82
  type RouteSet = { status?: number | string }
56
83
 
84
+ /** A version's file, as an `<img>` loads it too: a shared link's session names its grant. */
85
+ const ArtifactFileContentQuerySchema = FileContentQuerySchema.extend(ShareGrantQuerySchema.shape)
86
+
57
87
  // The two below build response bodies; each route parses its whole response once.
58
88
  function artifactBody(artifact: ArtifactRecord) {
59
89
  return {
@@ -63,6 +93,7 @@ function artifactBody(artifact: ArtifactRecord) {
63
93
  title: artifact.title,
64
94
  owner: artifact.owner,
65
95
  latestVersion: artifact.latestVersion,
96
+ revision: artifact.revision,
66
97
  createdAt: toIsoString(artifact.createdAt),
67
98
  updatedAt: toIsoString(artifact.updatedAt),
68
99
  }
@@ -72,6 +103,8 @@ function versionBody(version: ArtifactVersionRecord) {
72
103
  return {
73
104
  artifactId: version.artifactId,
74
105
  version: version.version,
106
+ revision: version.revision,
107
+ frozen: version.frozenAt !== undefined,
75
108
  title: version.title,
76
109
  entry: version.entry,
77
110
  files: version.files,
@@ -80,13 +113,111 @@ function versionBody(version: ArtifactVersionRecord) {
80
113
  author: version.author,
81
114
  origin: version.origin,
82
115
  createdAt: toIsoString(version.createdAt),
116
+ updatedAt: toIsoString(version.updatedAt),
117
+ ...(version.frozenAt ? { frozenAt: toIsoString(version.frozenAt) } : {}),
118
+ ...(version.frozenBy ? { frozenBy: version.frozenBy } : {}),
119
+ }
120
+ }
121
+
122
+ /**
123
+ * Names the authors of these comments, each read once, as the live canvas names who is on it: a
124
+ * guest by the name they gave. A shared link's guest reads them too, and never learns a member's
125
+ * email from them.
126
+ */
127
+ function commentAuthors(host: SixbHostView, context: unknown) {
128
+ const email = !requestAuthState(context).sharedSession
129
+ const names = new Map<string, Promise<string | null>>()
130
+
131
+ return (comment: ArtifactCommentRecord) => {
132
+ const { author } = comment
133
+ if (author.type === "guest") return Promise.resolve(author.name)
134
+
135
+ const key = `${author.type}:${author.id}`
136
+ let name = names.get(key)
137
+ if (!name) {
138
+ name = principalName(host.storage, host.projectId, author, { email })
139
+ names.set(key, name)
140
+ }
141
+ return name
83
142
  }
84
143
  }
85
144
 
86
- function serializePublished(published: PublishedArtifact) {
145
+ async function commentBody(
146
+ comment: ArtifactCommentRecord,
147
+ nameOf: (comment: ArtifactCommentRecord) => Promise<string | null>
148
+ ) {
149
+ return {
150
+ authorName: await nameOf(comment),
151
+ ...(comment.origin ? { origin: comment.origin } : {}),
152
+ artifactId: comment.artifactId,
153
+ id: comment.id,
154
+ ...(comment.parentId === undefined ? {} : { parentId: comment.parentId }),
155
+ anchor: comment.anchor,
156
+ body: comment.body,
157
+ author: { type: comment.author.type, id: comment.author.id },
158
+ createdAt: toIsoString(comment.createdAt),
159
+ ...(comment.resolvedAt ? { resolvedAt: toIsoString(comment.resolvedAt) } : {}),
160
+ ...(comment.resolvedBy ? { resolvedBy: comment.resolvedBy } : {}),
161
+ }
162
+ }
163
+
164
+ function restorePointSummary(point: ArtifactRestorePointRecord) {
165
+ return {
166
+ artifactId: point.artifactId,
167
+ revision: point.revision,
168
+ version: point.version,
169
+ frozen: point.frozen,
170
+ title: point.title,
171
+ author: point.author,
172
+ origin: point.origin,
173
+ updatedAt: toIsoString(point.updatedAt),
174
+ reason: point.reason,
175
+ ...(point.turnRunId === undefined ? {} : { turnRunId: point.turnRunId }),
176
+ createdAt: toIsoString(point.createdAt),
177
+ }
178
+ }
179
+
180
+ /**
181
+ * A version as one is answered alone, or just written: a canvas's boards say whether their
182
+ * previews are worth waiting for, so a viewer seeded from either asks for them alike.
183
+ */
184
+ async function versionResponse(
185
+ host: SixbHostView,
186
+ version: ArtifactVersionRecord,
187
+ options: { readonly previews?: boolean } = {}
188
+ ) {
189
+ const storage = host.storage.artifacts
190
+ const stored =
191
+ storage && version.outline.kind === "canvas"
192
+ ? await boardPreviewStatuses(storage, version, {
193
+ renders: host.sandboxes !== undefined,
194
+ now: new Date(),
195
+ })
196
+ : undefined
197
+
198
+ // A reader shown no pictures sees each board's outline, until they open it.
199
+ const statuses =
200
+ stored && options.previews === false
201
+ ? new Map([...stored.keys()].map((board) => [board, "none" as const]))
202
+ : stored
203
+
204
+ return {
205
+ ...versionBody(version),
206
+ ...(statuses ? { boardPreviews: Object.fromEntries(statuses) } : {}),
207
+ }
208
+ }
209
+
210
+ async function serializeChange(host: SixbHostView, change: PublishedArtifactVersion) {
211
+ return ArtifactChangeResponseSchema.parse({
212
+ artifact: artifactBody(change.artifact),
213
+ version: await versionResponse(host, change.version),
214
+ })
215
+ }
216
+
217
+ async function serializePublished(host: SixbHostView, published: PublishedArtifact) {
87
218
  return PublishedArtifactResponseSchema.parse({
88
219
  artifact: artifactBody(published.artifact),
89
- version: versionBody(published.version),
220
+ version: await versionResponse(host, published.version),
90
221
  warnings: published.warnings,
91
222
  })
92
223
  }
@@ -134,11 +265,33 @@ async function runTokenArtifacts(
134
265
  const run = await host.storage.agents?.runs.getById({ projectId: host.id, id: runId })
135
266
  if (!run || !sixb) throw new AgentExecutionLostError(runId)
136
267
 
137
- return agentRunArtifacts({ projectId: host.id, storage: host.storage }, run, executionToken, () =>
138
- Promise.resolve(sixb)
268
+ return agentRunArtifacts(
269
+ { projectId: host.id, storage: host.storage, domainEvents: host.events, broker: host.broker },
270
+ run,
271
+ executionToken,
272
+ () => Promise.resolve(sixb)
139
273
  )
140
274
  }
141
275
 
276
+ /**
277
+ * The Agent's run a request with a run token comes from, and its conversation: a comment it writes
278
+ * says so. Undefined for anyone else, who writes as themselves.
279
+ */
280
+ async function runTokenOrigin(
281
+ host: SixbHostView,
282
+ context: unknown
283
+ ): Promise<{ readonly threadId: string; readonly runId: string } | undefined> {
284
+ const { agentExecution } = requestAuthState(context)
285
+ // A workflow's node has no conversation: its run token reaches no comment.
286
+ if (!agentExecution || agentExecution.kind === "workflow") return undefined
287
+
288
+ const run = await host.storage.agents?.runs.getById({
289
+ projectId: host.id,
290
+ id: agentExecution.runId,
291
+ })
292
+ return run?.threadId ? { threadId: run.threadId, runId: run.id } : undefined
293
+ }
294
+
142
295
  function versionParam(value: string): number | "latest" {
143
296
  return value === "latest" ? "latest" : Number(value)
144
297
  }
@@ -150,19 +303,28 @@ function notFound(set: RouteSet) {
150
303
 
151
304
  /**
152
305
  * Why a read found nothing: 404 when there is no such artifact, 403 `not_shared` when there is one
153
- * the caller cannot read, so a page can say it is not shared in this conversation.
306
+ * the caller cannot read, so a page can say it is not shared with them.
154
307
  */
155
308
  async function refusal(context: unknown, artifactId: string, set: RouteSet) {
156
309
  return refusalFor(await requireRequestSixb(context).artifacts.access(artifactId), set)
157
310
  }
158
311
 
312
+ /** Why a restore point was not found: its artifact is not readable, or keeps no such point. */
313
+ async function restorePointRefusal(context: unknown, artifactId: string, set: RouteSet) {
314
+ const access = await requireRequestSixb(context).artifacts.access(artifactId)
315
+ if (access === null || access === "none") return refusalFor(access, set)
316
+
317
+ set.status = 404
318
+ return { error: "Restore point not found", code: "restore_point_not_found" as const }
319
+ }
320
+
159
321
  /** The refusal for what the caller may do with an artifact, once that is known. */
160
322
  function refusalFor(access: ArtifactAccess | null, set: RouteSet) {
161
323
  if (access !== "none") return notFound(set)
162
324
 
163
325
  set.status = 403
164
326
  return {
165
- error: "Artifact not shared in a conversation you read",
327
+ error: "Artifact not shared with you",
166
328
  code: "not_shared" as const,
167
329
  }
168
330
  }
@@ -171,7 +333,9 @@ function handleArtifactRouteError(error: unknown, set: RouteSet) {
171
333
  if (error instanceof ArtifactRequestError) {
172
334
  switch (error.code) {
173
335
  case "artifact_not_found":
336
+ case "comment_not_found":
174
337
  case "query_not_found":
338
+ case "restore_point_not_found":
175
339
  set.status = 404
176
340
  break
177
341
  case "artifact_kind_mismatch":
@@ -180,9 +344,12 @@ function handleArtifactRouteError(error: unknown, set: RouteSet) {
180
344
  set.status = 409
181
345
  break
182
346
  case "invalid_artifact":
347
+ case "invalid_comment":
183
348
  case "invalid_state":
349
+ case "name_required":
184
350
  set.status = 400
185
351
  break
352
+ case "comments_full":
186
353
  case "state_full":
187
354
  set.status = 413
188
355
  break
@@ -225,8 +392,7 @@ function artifactErrorResponse(status: number) {
225
392
  }
226
393
  }
227
394
 
228
- const publishResponses = {
229
- 201: PublishedArtifactResponseSchema,
395
+ const writeRefusals = {
230
396
  400: ArtifactErrorResponseSchema,
231
397
  403: ArtifactErrorResponseSchema,
232
398
  404: ArtifactErrorResponseSchema,
@@ -234,6 +400,10 @@ const publishResponses = {
234
400
  501: ArtifactErrorResponseSchema,
235
401
  }
236
402
 
403
+ const createResponses = { 201: PublishedArtifactResponseSchema, ...writeRefusals }
404
+
405
+ const updateResponses = { 200: PublishedArtifactResponseSchema, ...writeRefusals }
406
+
237
407
  async function artifactFileContentResponse(
238
408
  host: SixbHostView,
239
409
  context: {
@@ -276,6 +446,150 @@ async function artifactFileContentResponse(
276
446
  }
277
447
  }
278
448
 
449
+ /** A file of a restore point, to whoever reads its artifact. */
450
+ async function restorePointFileContentResponse(
451
+ host: SixbHostView,
452
+ context: {
453
+ readonly params: { readonly artifactId: string; readonly revision: string }
454
+ readonly query: unknown
455
+ readonly request: Request
456
+ readonly set: RouteSet
457
+ }
458
+ ) {
459
+ try {
460
+ const query = FileContentQuerySchema.parse(context.query)
461
+ const { artifactId } = context.params
462
+ const point = await requireRequestSixb(context).artifacts.getRestorePoint(
463
+ artifactId,
464
+ Number(context.params.revision)
465
+ )
466
+ if (!point) return await restorePointRefusal(context, artifactId, context.set)
467
+
468
+ const file = point.files.find((candidate) => candidate.path === query.path)
469
+ const response =
470
+ file &&
471
+ (await createFileContentResponse({
472
+ blobStorage: host.blobStorage,
473
+ fileRef: file.file,
474
+ disposition: query.disposition,
475
+ request: context.request,
476
+ }))
477
+ if (!response) {
478
+ context.set.status = 404
479
+ return { error: "File not found" }
480
+ }
481
+ return response
482
+ } catch (error) {
483
+ if (error instanceof ZodError) {
484
+ context.set.status = 400
485
+ return { error: "Invalid file content query" }
486
+ }
487
+ return handleArtifactRouteError(error, context.set)
488
+ }
489
+ }
490
+
491
+ /**
492
+ * A board's preview, to whoever reads its version: reading the version as the caller is the
493
+ * check. Its render key names what the board shows, so a frozen version's preview never changes.
494
+ */
495
+ async function artifactBoardPreviewResponse(
496
+ host: SixbHostView,
497
+ context: {
498
+ readonly params: {
499
+ readonly artifactId: string
500
+ readonly version: string
501
+ readonly board: string
502
+ }
503
+ readonly query: unknown
504
+ readonly request: Request
505
+ readonly set: RouteSet & { headers: Record<string, string | number> }
506
+ }
507
+ ) {
508
+ try {
509
+ const query = ArtifactBoardPreviewQuerySchema.parse(context.query)
510
+ const { artifactId, board } = context.params
511
+ const number = versionParam(context.params.version)
512
+
513
+ const version = await requireRequestSixb(context).artifacts.getVersion(artifactId, number)
514
+ if (!version) return await refusal(context, artifactId, context.set)
515
+ if (!seesBoardPreviews(context, version)) {
516
+ context.set.status = 404
517
+ context.set.headers["cache-control"] = "no-store"
518
+ return { error: "Board preview not found", code: "preview_not_found" as const }
519
+ }
520
+
521
+ // A picture of a revision the version moved past, or of what the board showed before, is not
522
+ // this one's.
523
+ const current =
524
+ query.key !== undefined
525
+ ? boardRenderKey(version, board) === query.key
526
+ : query.revision === undefined || query.revision === version.revision
527
+
528
+ // The reader's mode, unless the canvas pins another.
529
+ const themes = version.outline.kind === "canvas" ? (version.outline.themes ?? []) : []
530
+ const theme = query.theme && themes.includes(query.theme) ? query.theme : themes[0]
531
+
532
+ const storage = host.storage.artifacts
533
+ const preview =
534
+ storage && theme && current
535
+ ? boardPreview(
536
+ (await boardPreviews(storage, version)).get(board),
537
+ theme,
538
+ query.size ?? "full"
539
+ )
540
+ : undefined
541
+ const response =
542
+ preview &&
543
+ (await createFileContentResponse({
544
+ blobStorage: host.blobStorage,
545
+ fileRef: preview.file,
546
+ request: context.request,
547
+ }))
548
+ if (!response) {
549
+ context.set.status = 404
550
+ // It may be rendered in a moment: nothing may keep this answer.
551
+ context.set.headers["cache-control"] = "no-store"
552
+ return { error: "Board preview not found", code: "preview_not_found" as const }
553
+ }
554
+
555
+ // A frozen version never changes, nor its boards' pictures, and neither does a revision; an
556
+ // open version asked for without one does at each write.
557
+ response.headers.set(
558
+ "cache-control",
559
+ (number !== "latest" && version.frozenAt) ||
560
+ query.revision !== undefined ||
561
+ query.key !== undefined
562
+ ? "private, max-age=31536000, immutable"
563
+ : "private, no-cache"
564
+ )
565
+ return response
566
+ } catch (error) {
567
+ return handleArtifactRouteError(error, context.set)
568
+ }
569
+ }
570
+
571
+ /**
572
+ * Whether the caller sees the pictures of a version's boards. A version that holds queries has its
573
+ * boards pictured with its author's answers, which a shared link's guest, whose link grants its
574
+ * objects alone, must not see: their boards show their outlines, and an opened board runs its
575
+ * queries with the guest's own rights.
576
+ */
577
+ function seesBoardPreviews(context: unknown, version: ArtifactVersionRecord): boolean {
578
+ return !requestAuthState(context).sharedSession || !boardsReadLiveData(version)
579
+ }
580
+
581
+ /** The render key a canvas version's outline gives one of its boards. */
582
+ function boardRenderKey(
583
+ version: { readonly outline: ArtifactVersionRecord["outline"] },
584
+ board: string
585
+ ): string | undefined {
586
+ if (version.outline.kind !== "canvas") return undefined
587
+ const item = version.outline.items.find(
588
+ (candidate) => candidate.type === "board" && candidate.id === board
589
+ )
590
+ return item?.type === "board" ? item.renderKey : undefined
591
+ }
592
+
279
593
  export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
280
594
  return app
281
595
  .get(
@@ -327,14 +641,14 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
327
641
  ? await run.publish(contentInput(body))
328
642
  : await requireRequestSixb(context).artifacts.create(contentInput(body))
329
643
  context.set.status = 201
330
- return serializePublished(published)
644
+ return await serializePublished(host, published)
331
645
  } catch (error) {
332
646
  return handleArtifactRouteError(error, context.set)
333
647
  }
334
648
  },
335
649
  {
336
650
  body: PublishArtifactBodySchema,
337
- response: publishResponses,
651
+ response: createResponses,
338
652
  detail: {
339
653
  summary: "Create an artifact",
340
654
  description:
@@ -390,6 +704,37 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
390
704
  },
391
705
  }
392
706
  )
707
+ .get(
708
+ "/api/artifacts/:artifactId/holders",
709
+ async (context) => {
710
+ try {
711
+ const { artifactId } = context.params
712
+ const holders = await requireRequestSixb(context).artifacts.holders(artifactId)
713
+ if (!holders) return await refusal(context, artifactId, context.set)
714
+
715
+ return ArtifactHolderListResponseSchema.parse(holders)
716
+ } catch (error) {
717
+ return handleArtifactRouteError(error, context.set)
718
+ }
719
+ },
720
+ {
721
+ params: ArtifactParamsSchema,
722
+ response: {
723
+ 200: ArtifactHolderListResponseSchema,
724
+ 403: ArtifactErrorResponseSchema,
725
+ 404: ArtifactErrorResponseSchema,
726
+ 501: ArtifactErrorResponseSchema,
727
+ },
728
+ detail: {
729
+ summary: "List the objects that hold an artifact",
730
+ description:
731
+ "The objects whose property holds the artifact, among those you read with that property, in a stable order. Whoever reads such an object reads the artifact.",
732
+ tags: [OPENAPI_TAGS.artifacts.name],
733
+ operationId: "listArtifactHolders",
734
+ security: accessTokenSecurityRequirement("listArtifactHolders"),
735
+ },
736
+ }
737
+ )
393
738
  .delete(
394
739
  "/api/artifacts/:artifactId",
395
740
  async (context) => {
@@ -562,37 +907,342 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
562
907
  },
563
908
  }
564
909
  )
565
- .post(
566
- "/api/artifacts/:artifactId/versions",
910
+ .put(
911
+ "/api/artifacts/:artifactId/content",
567
912
  async (context) => {
568
913
  try {
569
- const body = PublishArtifactVersionBodySchema.parse(context.body)
914
+ const body = UpdateArtifactBodySchema.parse(context.body)
570
915
  const { artifactId } = context.params
571
916
  const content = {
572
917
  ...contentInput(body),
573
- ...(body.baseVersion === undefined ? {} : { baseVersion: body.baseVersion }),
918
+ ...(body.baseRevision === undefined ? {} : { baseRevision: body.baseRevision }),
574
919
  }
575
920
  const run = await runTokenArtifacts(host, context)
576
921
  const published = run
577
922
  ? await run.publish({ ...content, artifactId })
578
- : await requireRequestSixb(context).artifacts.publish(artifactId, content)
923
+ : await requireRequestSixb(context).artifacts.update(artifactId, content)
924
+ return await serializePublished(host, published)
925
+ } catch (error) {
926
+ return handleArtifactRouteError(error, context.set)
927
+ }
928
+ },
929
+ {
930
+ params: ArtifactParamsSchema,
931
+ body: UpdateArtifactBodySchema,
932
+ response: updateResponses,
933
+ detail: {
934
+ summary: "Update an artifact",
935
+ description:
936
+ "Writes the artifact's latest version: its content is replaced while the version is open, and the next version opens when it is frozen. Either way the revision grows. The kind must be the artifact's. With baseRevision, it is refused with 409 artifact_moved when the artifact changed since. With a run token, only an artifact the run's conversation shares, its requester owns, or an object its requester edits holds; it is shared in that conversation, and the turn's first write to it keeps a restore point. A run that lost its execution gets 409 execution_lost.",
937
+ tags: [OPENAPI_TAGS.artifacts.name],
938
+ operationId: "updateArtifact",
939
+ security: accessTokenSecurityRequirement("updateArtifact"),
940
+ },
941
+ }
942
+ )
943
+ .post(
944
+ "/api/artifacts/:artifactId/freeze",
945
+ async (context) => {
946
+ try {
947
+ const body = FreezeArtifactBodySchema.parse(context.body ?? {})
948
+ const frozen = await requireRequestSixb(context).artifacts.freeze(
949
+ context.params.artifactId,
950
+ body.baseRevision === undefined ? {} : { baseRevision: body.baseRevision }
951
+ )
952
+ return await serializeChange(host, frozen)
953
+ } catch (error) {
954
+ return handleArtifactRouteError(error, context.set)
955
+ }
956
+ },
957
+ {
958
+ params: ArtifactParamsSchema,
959
+ body: FreezeArtifactBodySchema,
960
+ response: {
961
+ 200: ArtifactChangeResponseSchema,
962
+ 400: ArtifactErrorResponseSchema,
963
+ 403: ArtifactErrorResponseSchema,
964
+ 404: ArtifactErrorResponseSchema,
965
+ 409: ArtifactErrorResponseSchema,
966
+ 501: ArtifactErrorResponseSchema,
967
+ },
968
+ detail: {
969
+ summary: "Create a version",
970
+ description:
971
+ "Freezes the artifact's open latest version: it never changes again, and the next write opens the next version. A latest version already frozen is returned as it is. Whoever may update the artifact may create a version. With baseRevision, it is refused with 409 artifact_moved when the open version changed since.",
972
+ tags: [OPENAPI_TAGS.artifacts.name],
973
+ operationId: "freezeArtifactVersion",
974
+ security: accessTokenSecurityRequirement("freezeArtifactVersion"),
975
+ },
976
+ }
977
+ )
978
+ .get(
979
+ "/api/artifacts/:artifactId/comments",
980
+ async (context) => {
981
+ try {
982
+ const { artifactId } = context.params
983
+ const comments = await requireRequestSixb(context).artifacts.listComments(artifactId)
984
+ if (!comments) return await refusal(context, artifactId, context.set)
985
+
986
+ const nameOf = commentAuthors(host, context)
987
+ return ArtifactCommentListResponseSchema.parse({
988
+ comments: await Promise.all(comments.map((comment) => commentBody(comment, nameOf))),
989
+ })
990
+ } catch (error) {
991
+ return handleArtifactRouteError(error, context.set)
992
+ }
993
+ },
994
+ {
995
+ params: ArtifactParamsSchema,
996
+ response: {
997
+ 200: ArtifactCommentListResponseSchema,
998
+ 403: ArtifactErrorResponseSchema,
999
+ 404: ArtifactErrorResponseSchema,
1000
+ 501: ArtifactErrorResponseSchema,
1001
+ },
1002
+ detail: {
1003
+ summary: "List an artifact's comments",
1004
+ description:
1005
+ "Every comment and reply, oldest first, resolved ones included. Whoever reads the artifact reads them.",
1006
+ tags: [OPENAPI_TAGS.artifacts.name],
1007
+ operationId: "listArtifactComments",
1008
+ security: accessTokenSecurityRequirement("listArtifactComments"),
1009
+ },
1010
+ }
1011
+ )
1012
+ .post(
1013
+ "/api/artifacts/:artifactId/comments",
1014
+ async (context) => {
1015
+ try {
1016
+ const body = AddArtifactCommentBodySchema.parse(context.body)
1017
+ const origin = await runTokenOrigin(host, context)
1018
+ const comment = await requireRequestSixb(context).artifacts.addComment(
1019
+ context.params.artifactId,
1020
+ {
1021
+ body: body.body,
1022
+ ...(body.anchor ? { anchor: body.anchor } : {}),
1023
+ ...(body.parentId ? { parentId: body.parentId } : {}),
1024
+ ...(origin ? { origin } : {}),
1025
+ }
1026
+ )
579
1027
  context.set.status = 201
580
- return serializePublished(published)
1028
+ return ArtifactCommentSchema.parse(
1029
+ await commentBody(comment, commentAuthors(host, context))
1030
+ )
1031
+ } catch (error) {
1032
+ return handleArtifactRouteError(error, context.set)
1033
+ }
1034
+ },
1035
+ {
1036
+ params: ArtifactParamsSchema,
1037
+ body: AddArtifactCommentBodySchema,
1038
+ response: {
1039
+ 201: ArtifactCommentSchema,
1040
+ 400: ArtifactErrorResponseSchema,
1041
+ 403: ArtifactErrorResponseSchema,
1042
+ 404: ArtifactErrorResponseSchema,
1043
+ 413: ArtifactErrorResponseSchema,
1044
+ 501: ArtifactErrorResponseSchema,
1045
+ },
1046
+ detail: {
1047
+ summary: "Comment on an artifact",
1048
+ description:
1049
+ "Adds a comment, or a reply with parentId, as the caller. Whoever reads the artifact may, a shared link's guest included, under the name they gave its session (400 name_required until they give one). A canvas's comment can be about one of its boards, or an element of a board by its address. Readers receive artifact.commented.",
1050
+ tags: [OPENAPI_TAGS.artifacts.name],
1051
+ operationId: "addArtifactComment",
1052
+ security: accessTokenSecurityRequirement("addArtifactComment"),
1053
+ },
1054
+ }
1055
+ )
1056
+ .post(
1057
+ "/api/artifacts/:artifactId/comments/:commentId/resolve",
1058
+ async (context) => {
1059
+ try {
1060
+ const body = ResolveArtifactCommentBodySchema.parse(context.body ?? {})
1061
+ const comment = await requireRequestSixb(context).artifacts.resolveComment(
1062
+ context.params.artifactId,
1063
+ context.params.commentId,
1064
+ body.resolved
1065
+ )
1066
+ return ArtifactCommentSchema.parse(
1067
+ await commentBody(comment, commentAuthors(host, context))
1068
+ )
1069
+ } catch (error) {
1070
+ return handleArtifactRouteError(error, context.set)
1071
+ }
1072
+ },
1073
+ {
1074
+ params: ArtifactCommentParamsSchema,
1075
+ body: ResolveArtifactCommentBodySchema,
1076
+ response: {
1077
+ 200: ArtifactCommentSchema,
1078
+ 400: ArtifactErrorResponseSchema,
1079
+ 403: ArtifactErrorResponseSchema,
1080
+ 404: ArtifactErrorResponseSchema,
1081
+ 501: ArtifactErrorResponseSchema,
1082
+ },
1083
+ detail: {
1084
+ summary: "Resolve an artifact's comment",
1085
+ description:
1086
+ "Marks the comment resolved, or, with resolved false, opens it again. Its author, or whoever may update the artifact, may; anyone else is refused with 403 not_allowed. A guest's comment is resolved only by whoever may update the artifact.",
1087
+ tags: [OPENAPI_TAGS.artifacts.name],
1088
+ operationId: "resolveArtifactComment",
1089
+ security: accessTokenSecurityRequirement("resolveArtifactComment"),
1090
+ },
1091
+ }
1092
+ )
1093
+ .delete(
1094
+ "/api/artifacts/:artifactId/comments/:commentId",
1095
+ async (context) => {
1096
+ try {
1097
+ await requireRequestSixb(context).artifacts.deleteComment(
1098
+ context.params.artifactId,
1099
+ context.params.commentId
1100
+ )
1101
+ return DeleteArtifactCommentResponseSchema.parse({ deleted: true })
1102
+ } catch (error) {
1103
+ return handleArtifactRouteError(error, context.set)
1104
+ }
1105
+ },
1106
+ {
1107
+ params: ArtifactCommentParamsSchema,
1108
+ response: {
1109
+ 200: DeleteArtifactCommentResponseSchema,
1110
+ 403: ArtifactErrorResponseSchema,
1111
+ 404: ArtifactErrorResponseSchema,
1112
+ 501: ArtifactErrorResponseSchema,
1113
+ },
1114
+ detail: {
1115
+ summary: "Delete an artifact's comment",
1116
+ description:
1117
+ "Deletes the comment and its replies. Its author, or whoever may update the artifact, may.",
1118
+ tags: [OPENAPI_TAGS.artifacts.name],
1119
+ operationId: "deleteArtifactComment",
1120
+ security: accessTokenSecurityRequirement("deleteArtifactComment"),
1121
+ },
1122
+ }
1123
+ )
1124
+ .get(
1125
+ "/api/artifacts/:artifactId/restore-points",
1126
+ async (context) => {
1127
+ try {
1128
+ const { artifactId } = context.params
1129
+ const points = await requireRequestSixb(context).artifacts.listRestorePoints(artifactId)
1130
+ if (!points) return await refusal(context, artifactId, context.set)
1131
+
1132
+ return ArtifactRestorePointListResponseSchema.parse({
1133
+ restorePoints: points.map(restorePointSummary),
1134
+ })
581
1135
  } catch (error) {
582
1136
  return handleArtifactRouteError(error, context.set)
583
1137
  }
584
1138
  },
585
1139
  {
586
1140
  params: ArtifactParamsSchema,
587
- body: PublishArtifactVersionBodySchema,
588
- response: publishResponses,
1141
+ response: {
1142
+ 200: ArtifactRestorePointListResponseSchema,
1143
+ 403: ArtifactErrorResponseSchema,
1144
+ 404: ArtifactErrorResponseSchema,
1145
+ 501: ArtifactErrorResponseSchema,
1146
+ },
589
1147
  detail: {
590
- summary: "Publish an artifact's next version",
1148
+ summary: "List an artifact's restore points",
591
1149
  description:
592
- "The kind must be the artifact's. The new version becomes the latest. With baseVersion, it is refused with 409 artifact_moved when another version was published since. With a run token, only an artifact the run's conversation shares or its requester owns; the version is shared in that conversation. A run that lost its execution gets 409 execution_lost.",
1150
+ "What the artifact's latest version held before each Agent turn's first write to it, and before each restore, newest first. They are not versions: restoring one puts its content back in the latest version.",
593
1151
  tags: [OPENAPI_TAGS.artifacts.name],
594
- operationId: "publishArtifactVersion",
595
- security: accessTokenSecurityRequirement("publishArtifactVersion"),
1152
+ operationId: "listArtifactRestorePoints",
1153
+ security: accessTokenSecurityRequirement("listArtifactRestorePoints"),
1154
+ },
1155
+ }
1156
+ )
1157
+ .get(
1158
+ "/api/artifacts/:artifactId/restore-points/:revision",
1159
+ async (context) => {
1160
+ try {
1161
+ const { artifactId, revision } = context.params
1162
+ const point = await requireRequestSixb(context).artifacts.getRestorePoint(
1163
+ artifactId,
1164
+ Number(revision)
1165
+ )
1166
+ if (!point) return await restorePointRefusal(context, artifactId, context.set)
1167
+
1168
+ return ArtifactRestorePointSchema.parse({
1169
+ ...restorePointSummary(point),
1170
+ entry: point.entry,
1171
+ files: point.files,
1172
+ outline: point.outline,
1173
+ references: point.references,
1174
+ })
1175
+ } catch (error) {
1176
+ return handleArtifactRouteError(error, context.set)
1177
+ }
1178
+ },
1179
+ {
1180
+ params: ArtifactRestorePointParamsSchema,
1181
+ response: {
1182
+ 200: ArtifactRestorePointSchema,
1183
+ 403: ArtifactErrorResponseSchema,
1184
+ 404: ArtifactErrorResponseSchema,
1185
+ 501: ArtifactErrorResponseSchema,
1186
+ },
1187
+ detail: {
1188
+ summary: "Get an artifact's restore point",
1189
+ description:
1190
+ "Its files, outline, and references, as the latest version held them. Read a file's bytes with GET /api/artifacts/{artifactId}/restore-points/{revision}/content.",
1191
+ tags: [OPENAPI_TAGS.artifacts.name],
1192
+ operationId: "getArtifactRestorePoint",
1193
+ security: accessTokenSecurityRequirement("getArtifactRestorePoint"),
1194
+ },
1195
+ }
1196
+ )
1197
+ .get(
1198
+ "/api/artifacts/:artifactId/restore-points/:revision/content",
1199
+ async (context) => restorePointFileContentResponse(host, context),
1200
+ {
1201
+ params: ArtifactRestorePointParamsSchema,
1202
+ query: FileContentQuerySchema,
1203
+ detail: {
1204
+ summary: "Get a file of an artifact's restore point",
1205
+ tags: [OPENAPI_TAGS.artifacts.name],
1206
+ operationId: "getArtifactRestorePointFileContent",
1207
+ security: accessTokenSecurityRequirement("getArtifactRestorePointFileContent"),
1208
+ responses: fileContentGetResponses({ optionalStorage: true }),
1209
+ },
1210
+ }
1211
+ )
1212
+ .post(
1213
+ "/api/artifacts/:artifactId/restore-points/:revision/restore",
1214
+ async (context) => {
1215
+ try {
1216
+ const body = RestoreArtifactBodySchema.parse(context.body ?? {})
1217
+ const { artifactId, revision } = context.params
1218
+ const restored = await requireRequestSixb(context).artifacts.restore(
1219
+ artifactId,
1220
+ Number(revision),
1221
+ body.baseRevision === undefined ? {} : { baseRevision: body.baseRevision }
1222
+ )
1223
+ return await serializeChange(host, restored)
1224
+ } catch (error) {
1225
+ return handleArtifactRouteError(error, context.set)
1226
+ }
1227
+ },
1228
+ {
1229
+ params: ArtifactRestorePointParamsSchema,
1230
+ body: RestoreArtifactBodySchema,
1231
+ response: {
1232
+ 200: ArtifactChangeResponseSchema,
1233
+ 400: ArtifactErrorResponseSchema,
1234
+ 403: ArtifactErrorResponseSchema,
1235
+ 404: ArtifactErrorResponseSchema,
1236
+ 409: ArtifactErrorResponseSchema,
1237
+ 501: ArtifactErrorResponseSchema,
1238
+ },
1239
+ detail: {
1240
+ summary: "Restore an artifact",
1241
+ description:
1242
+ "Puts a restore point's content back in the latest version, as an update writes it: in place while it is open, as the next version when it is frozen. What it replaces becomes a restore point, so the restore can be undone. Whoever may update the artifact may restore it. With baseRevision, it is refused with 409 artifact_moved when the artifact changed since.",
1243
+ tags: [OPENAPI_TAGS.artifacts.name],
1244
+ operationId: "restoreArtifact",
1245
+ security: accessTokenSecurityRequirement("restoreArtifact"),
596
1246
  },
597
1247
  }
598
1248
  )
@@ -637,7 +1287,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
637
1287
  detail: {
638
1288
  summary: "Open a version in a frame",
639
1289
  description:
640
- "A short-lived path that serves the files of a version that opens in a sandboxed frame, as slides do. It expires within an hour. A kind that does not open in a frame is refused with 409 artifact_kind_mismatch.",
1290
+ "A short-lived path that serves the files of a version that opens in a sandboxed frame, as slides do, at the revision it has now: once the version is written again, the path serves nothing and a new one is needed. It expires within an hour. A kind that does not open in a frame is refused with 409 artifact_kind_mismatch.",
641
1291
  tags: [OPENAPI_TAGS.artifacts.name],
642
1292
  operationId: "createArtifactFrame",
643
1293
  security: accessTokenSecurityRequirement("createArtifactFrame"),
@@ -653,7 +1303,12 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
653
1303
  versionParam(context.params.version)
654
1304
  )
655
1305
  if (!version) return await refusal(context, context.params.artifactId, context.set)
656
- return ArtifactVersionSchema.parse(versionBody(version))
1306
+
1307
+ return ArtifactVersionSchema.parse(
1308
+ await versionResponse(host, version, {
1309
+ previews: seesBoardPreviews(context, version),
1310
+ })
1311
+ )
657
1312
  } catch (error) {
658
1313
  return handleArtifactRouteError(error, context.set)
659
1314
  }
@@ -675,6 +1330,36 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
675
1330
  },
676
1331
  }
677
1332
  )
1333
+ .get(
1334
+ "/api/artifacts/:artifactId/versions/:version/boards/:board/preview",
1335
+ async (context) => artifactBoardPreviewResponse(host, context),
1336
+ {
1337
+ params: ArtifactBoardPreviewParamsSchema,
1338
+ query: ArtifactBoardPreviewQuerySchema,
1339
+ detail: {
1340
+ summary: "Get the preview of a canvas's board",
1341
+ description:
1342
+ "A picture of the board as its version shows it, in the reader's mode: a PNG at its own size, or with size=small a WebP at most 480 pixels wide, which a viewer shows until the board is opened. It shows the data the version's author can see. A frozen version's preview never changes, and is cached as such, as is one asked for at a revision; an open version's otherwise, and \"latest\", are revalidated. 404 preview_not_found until it is rendered, when it never will be, or when revision is not the version's current one: the version says which.",
1343
+ tags: [OPENAPI_TAGS.artifacts.name],
1344
+ operationId: "getArtifactBoardPreview",
1345
+ security: accessTokenSecurityRequirement("getArtifactBoardPreview"),
1346
+ responses: {
1347
+ 200: {
1348
+ description: "The board's preview",
1349
+ content: {
1350
+ "image/png": { schema: { type: "string", format: "binary" } },
1351
+ "image/webp": { schema: { type: "string", format: "binary" } },
1352
+ },
1353
+ },
1354
+ 304: { description: "The preview is unchanged; reuse the privately cached one" },
1355
+ 400: artifactErrorResponse(400),
1356
+ 403: artifactErrorResponse(403),
1357
+ 404: artifactErrorResponse(404),
1358
+ 501: artifactErrorResponse(501),
1359
+ },
1360
+ },
1361
+ }
1362
+ )
678
1363
  .get(
679
1364
  "/api/artifacts/:artifactId/versions/:version/queries/:name",
680
1365
  async (context) => {
@@ -733,7 +1418,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
733
1418
  async (context) => artifactFileContentResponse(host, context),
734
1419
  {
735
1420
  params: ArtifactVersionParamsSchema,
736
- query: FileContentQuerySchema,
1421
+ query: ArtifactFileContentQuerySchema,
737
1422
  detail: {
738
1423
  summary: "Get a file of an artifact version",
739
1424
  tags: [OPENAPI_TAGS.artifacts.name],
@@ -748,7 +1433,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
748
1433
  async (context) => artifactFileContentResponse(host, context, { head: true }),
749
1434
  {
750
1435
  params: ArtifactVersionParamsSchema,
751
- query: FileContentQuerySchema,
1436
+ query: ArtifactFileContentQuerySchema,
752
1437
  detail: {
753
1438
  summary: "Head a file of an artifact version",
754
1439
  tags: [OPENAPI_TAGS.artifacts.name],