@sixb/server 0.2.3 → 0.2.5

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 (45) hide show
  1. package/dist/index.js +354 -30
  2. package/dist/index.js.map +12 -12
  3. package/dist/live/room.d.ts +2 -0
  4. package/dist/live/room.d.ts.map +1 -1
  5. package/dist/routes/agent-runners.d.ts +5 -1
  6. package/dist/routes/agent-runners.d.ts.map +1 -1
  7. package/dist/routes/agents.d.ts +898 -6
  8. package/dist/routes/agents.d.ts.map +1 -1
  9. package/dist/routes/artifact-frames.d.ts +3 -3
  10. package/dist/routes/artifact-frames.d.ts.map +1 -1
  11. package/dist/routes/artifacts.d.ts +287 -21
  12. package/dist/routes/artifacts.d.ts.map +1 -1
  13. package/dist/routes/auth.d.ts +7 -7
  14. package/dist/routes/events.d.ts +4 -4
  15. package/dist/routes/links.d.ts +8 -0
  16. package/dist/routes/links.d.ts.map +1 -1
  17. package/dist/routes/objects.d.ts +8 -0
  18. package/dist/routes/objects.d.ts.map +1 -1
  19. package/dist/routes/projections.d.ts +2 -0
  20. package/dist/routes/projections.d.ts.map +1 -1
  21. package/dist/routes/ws/events.d.ts +6 -6
  22. package/dist/schemas/agents.d.ts +5089 -250
  23. package/dist/schemas/agents.d.ts.map +1 -1
  24. package/dist/schemas/artifacts.d.ts +676 -36
  25. package/dist/schemas/artifacts.d.ts.map +1 -1
  26. package/dist/schemas/auth.d.ts +8 -8
  27. package/dist/schemas/events.d.ts +36 -24
  28. package/dist/schemas/events.d.ts.map +1 -1
  29. package/dist/schemas/lineage.d.ts +112 -0
  30. package/dist/schemas/lineage.d.ts.map +1 -1
  31. package/dist/schemas/projections.d.ts +11 -0
  32. package/dist/schemas/projections.d.ts.map +1 -1
  33. package/dist/server.d.ts.map +1 -1
  34. package/package.json +4 -4
  35. package/src/live/README.md +9 -6
  36. package/src/live/room.ts +16 -8
  37. package/src/routes/agent-runners.ts +15 -4
  38. package/src/routes/agents.ts +203 -5
  39. package/src/routes/artifact-frames.ts +22 -9
  40. package/src/routes/artifacts.ts +124 -3
  41. package/src/schemas/agents.ts +68 -2
  42. package/src/schemas/artifacts.ts +66 -1
  43. package/src/schemas/events.ts +1 -0
  44. package/src/schemas/projections.ts +1 -0
  45. package/src/server.ts +3 -1
@@ -22,6 +22,7 @@ import {
22
22
  boardPreviewStatuses,
23
23
  boardPreviews,
24
24
  boardsReadLiveData,
25
+ documentPdfKey,
25
26
  } from "@sixb/core/internal/artifacts/publish"
26
27
  import type {
27
28
  ArtifactCommentRecord,
@@ -53,6 +54,9 @@ import {
53
54
  ArtifactListQuerySchema,
54
55
  ArtifactListResponseSchema,
55
56
  ArtifactParamsSchema,
57
+ ArtifactPdfDownloadQuerySchema,
58
+ ArtifactPdfQuerySchema,
59
+ ArtifactPdfResponseSchema,
56
60
  ArtifactQueryParamsSchema,
57
61
  ArtifactResponseSchema,
58
62
  ArtifactRestorePointListResponseSchema,
@@ -204,6 +208,8 @@ async function versionResponse(
204
208
  return {
205
209
  ...versionBody(version),
206
210
  ...(statuses ? { boardPreviews: Object.fromEntries(statuses) } : {}),
211
+ // A designed document prints to PDF when asked, in a project that has sandboxes.
212
+ ...(host.sandboxes && documentPdfKey(version) ? { printable: true } : {}),
207
213
  }
208
214
  }
209
215
 
@@ -334,6 +340,7 @@ function handleArtifactRouteError(error: unknown, set: RouteSet) {
334
340
  switch (error.code) {
335
341
  case "artifact_not_found":
336
342
  case "comment_not_found":
343
+ case "holder_not_found":
337
344
  case "query_not_found":
338
345
  case "restore_point_not_found":
339
346
  set.status = 404
@@ -358,6 +365,7 @@ function handleArtifactRouteError(error: unknown, set: RouteSet) {
358
365
  case "read_only":
359
366
  set.status = 403
360
367
  break
368
+ case "pdf_unavailable":
361
369
  case "storage_unavailable":
362
370
  set.status = 501
363
371
  break
@@ -568,6 +576,56 @@ async function artifactBoardPreviewResponse(
568
576
  }
569
577
  }
570
578
 
579
+ /** A designed document's PDF as a download, once printed; 404 `pdf_not_found` until then. */
580
+ async function artifactPdfResponse(
581
+ host: SixbHostView,
582
+ context: {
583
+ readonly params: { readonly artifactId: string; readonly version: string }
584
+ readonly query: { readonly key?: string | undefined }
585
+ readonly request: Request
586
+ readonly set: RouteSet & { headers: Record<string, string | number> }
587
+ }
588
+ ) {
589
+ try {
590
+ const { artifactId } = context.params
591
+ const number = versionParam(context.params.version)
592
+ const sixb = requireRequestSixb(context)
593
+ const version = await sixb.artifacts.getVersion(artifactId, number)
594
+ if (!version) return await refusal(context, artifactId, context.set)
595
+
596
+ // As the caller reads it: a document that shows live data prints their values, which the key
597
+ // its POST answered with names.
598
+ const pdf = await sixb.artifacts.pdf(artifactId, {
599
+ version: number,
600
+ print: false,
601
+ ...(context.query.key ? { key: context.query.key } : {}),
602
+ })
603
+ const response =
604
+ pdf?.status === "ready" &&
605
+ (await createFileContentResponse({
606
+ blobStorage: host.blobStorage,
607
+ fileRef: pdf.file,
608
+ request: context.request,
609
+ disposition: "attachment",
610
+ }))
611
+ if (!response) {
612
+ context.set.status = 404
613
+ context.set.headers["cache-control"] = "no-store"
614
+ return { error: "PDF not found", code: "pdf_not_found" as const }
615
+ }
616
+ // What a version prints changes as its content does: a frozen one's never.
617
+ response.headers.set(
618
+ "cache-control",
619
+ number !== "latest" && version.frozenAt
620
+ ? "private, max-age=31536000, immutable"
621
+ : "private, no-cache"
622
+ )
623
+ return response
624
+ } catch (error) {
625
+ return handleArtifactRouteError(error, context.set)
626
+ }
627
+ }
628
+
571
629
  /**
572
630
  * Whether the caller sees the pictures of a version's boards. A version that holds queries has its
573
631
  * boards pictured with its author's answers, which a shared link's guest, whose link grants its
@@ -1002,7 +1060,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
1002
1060
  detail: {
1003
1061
  summary: "List an artifact's comments",
1004
1062
  description:
1005
- "Every comment and reply, oldest first, resolved ones included. Whoever reads the artifact reads them.",
1063
+ "Every comment and reply, oldest first, resolved ones included. Whoever reads the artifact reads them; a shared link's guest reads only the threads started by a guest of the same link, with every reply in them.",
1006
1064
  tags: [OPENAPI_TAGS.artifacts.name],
1007
1065
  operationId: "listArtifactComments",
1008
1066
  security: accessTokenSecurityRequirement("listArtifactComments"),
@@ -1046,7 +1104,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
1046
1104
  detail: {
1047
1105
  summary: "Comment on an artifact",
1048
1106
  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.",
1107
+ "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), and replies only in a thread they read (404 comment_not_found otherwise). A canvas's comment can be about one of its boards, or an element of a board by its address. Readers of the thread receive artifact.commented.",
1050
1108
  tags: [OPENAPI_TAGS.artifacts.name],
1051
1109
  operationId: "addArtifactComment",
1052
1110
  security: accessTokenSecurityRequirement("addArtifactComment"),
@@ -1330,6 +1388,69 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
1330
1388
  },
1331
1389
  }
1332
1390
  )
1391
+ .post(
1392
+ "/api/artifacts/:artifactId/versions/:version/pdf",
1393
+ async (context) => {
1394
+ try {
1395
+ const { artifactId } = context.params
1396
+ const pdf = await requireRequestSixb(context).artifacts.pdf(artifactId, {
1397
+ version: versionParam(context.params.version),
1398
+ retry: context.query.retry === "true",
1399
+ ...(context.query.key ? { key: context.query.key } : {}),
1400
+ })
1401
+ if (!pdf) return await refusal(context, artifactId, context.set)
1402
+ if (pdf.status !== "ready") return pdf
1403
+ const { file: _file, ...ready } = pdf
1404
+ return ready
1405
+ } catch (error) {
1406
+ return handleArtifactRouteError(error, context.set)
1407
+ }
1408
+ },
1409
+ {
1410
+ params: ArtifactVersionParamsSchema,
1411
+ query: ArtifactPdfQuerySchema,
1412
+ response: {
1413
+ 200: ArtifactPdfResponseSchema,
1414
+ 400: ArtifactErrorResponseSchema,
1415
+ 403: ArtifactErrorResponseSchema,
1416
+ 404: ArtifactErrorResponseSchema,
1417
+ 501: ArtifactErrorResponseSchema,
1418
+ },
1419
+ detail: {
1420
+ summary: "Print a designed document to PDF",
1421
+ description:
1422
+ "Answers ready once the version is printed, and printing until then, having asked for it: ask again after a few seconds, then get it. Failed with why when it could not be printed; retry=true asks again. A document that shows live data answers with a key: ask again and get it with that key, which names the values the first ask printed. It prints as its stylesheets' @page rule lays it out, in a sandbox of the project. Whoever reads the artifact may ask. 400 invalid_artifact when the version is not a designed document; 501 pdf_unavailable in a project without sandboxes.",
1423
+ tags: [OPENAPI_TAGS.artifacts.name],
1424
+ operationId: "printArtifactPdf",
1425
+ security: accessTokenSecurityRequirement("printArtifactPdf"),
1426
+ },
1427
+ }
1428
+ )
1429
+ .get(
1430
+ "/api/artifacts/:artifactId/versions/:version/pdf",
1431
+ async (context) => artifactPdfResponse(host, context),
1432
+ {
1433
+ params: ArtifactVersionParamsSchema,
1434
+ query: ArtifactPdfDownloadQuerySchema,
1435
+ detail: {
1436
+ summary: "Get a designed document's PDF",
1437
+ description:
1438
+ "The version printed to PDF, with the values its fields read as the caller reads them, as a download named after the title it printed with: for a document that shows live data, those its POST's key names. 404 pdf_not_found until it is printed: ask for it with POST first. A frozen version's PDF never changes, and is cached as such.",
1439
+ tags: [OPENAPI_TAGS.artifacts.name],
1440
+ operationId: "getArtifactPdf",
1441
+ security: accessTokenSecurityRequirement("getArtifactPdf"),
1442
+ responses: {
1443
+ 200: {
1444
+ description: "The PDF",
1445
+ content: { "application/pdf": { schema: { type: "string", format: "binary" } } },
1446
+ },
1447
+ 304: { description: "The PDF is unchanged; reuse the privately cached one" },
1448
+ 403: artifactErrorResponse(403),
1449
+ 404: artifactErrorResponse(404),
1450
+ },
1451
+ },
1452
+ }
1453
+ )
1333
1454
  .get(
1334
1455
  "/api/artifacts/:artifactId/versions/:version/boards/:board/preview",
1335
1456
  async (context) => artifactBoardPreviewResponse(host, context),
@@ -1384,7 +1505,7 @@ export function registerArtifactRoutes(app: Elysia, host: SixbHostView) {
1384
1505
  detail: {
1385
1506
  summary: "Run an artifact's query",
1386
1507
  description:
1387
- 'Runs the version\'s queries/<name>.json as the caller, with their rights: a type they cannot view is refused with 403, and a marked property they are not cleared for is left out of each row. Rows are serialized as POST /api/objects/query returns them, beside the schema of what they hold as the caller may view it. Use "latest" for the newest version. A query the ontology no longer admits is refused with 409 query_invalid.',
1508
+ 'Runs the version\'s queries/<name>.json as the caller, with their rights: a type they cannot view is refused with 403, and a marked property they are not cleared for is left out of each row. Rows are serialized as POST /api/objects/query returns them, beside the schema of what they hold as the caller may view it. Use "latest" for the newest version. A query the ontology no longer admits is refused with 409 query_invalid. A designed document\'s "holder" is the object that holds it, of the type it names, with the links its fields read through: 404 holder_not_found when no one such object the caller reads holds it.',
1388
1509
  tags: [OPENAPI_TAGS.artifacts.name],
1389
1510
  operationId: "getArtifactQuery",
1390
1511
  security: accessTokenSecurityRequirement("getArtifactQuery"),
@@ -1,4 +1,4 @@
1
- import { MAX_AGENT_CONTEXT_ENTRIES } from "@sixb/core"
1
+ import { AGENT_MESSAGE_DELIVERIES, MAX_AGENT_CONTEXT_ENTRIES } from "@sixb/core"
2
2
  import { MAX_AGENT_CONTEXT_LABEL_LENGTH } from "@sixb/core/agents/context"
3
3
  import { CONTROL_CHARACTER } from "@sixb/core/internal/agent-run-storage-provider"
4
4
  import { LANGUAGE_MODEL_TIERS } from "@sixb/core/models"
@@ -49,6 +49,9 @@ export const AgentAuthorizablePrincipalSchema = z.object({
49
49
  id: z.string().min(1),
50
50
  })
51
51
 
52
+ /** How a message sent to a thread is delivered while a turn runs. */
53
+ export const AgentMessageDeliverySchema = z.enum(AGENT_MESSAGE_DELIVERIES)
54
+
52
55
  export const AgentObjectContextSchema = z.object({
53
56
  kind: z.literal("object"),
54
57
  ref: z.object({
@@ -502,6 +505,11 @@ export const PostAgentMessageBodySchema = z
502
505
  attachments: z.array(FileRefSchema).optional(),
503
506
  context: z.array(AgentContextEntryInputSchema).max(MAX_AGENT_CONTEXT_ENTRIES).optional(),
504
507
  messageId: z.string().trim().min(1).optional(),
508
+ /**
509
+ * Where the message goes while a turn runs: `auto` starts a turn and refuses while one runs,
510
+ * `steer` reaches it, `queue` waits for the next, and `send_now` stops it and goes.
511
+ */
512
+ delivery: AgentMessageDeliverySchema.optional(),
505
513
  })
506
514
  .strict()
507
515
 
@@ -561,8 +569,66 @@ export const AgentRunSchema = z.object({
561
569
  completedAt: z.string().optional(),
562
570
  })
563
571
 
572
+ /** A message waiting in a thread's inbox: the steer or the queued turn it becomes. */
573
+ export const AgentInboxItemSchema = z.object({
574
+ id: z.string(),
575
+ projectId: z.string(),
576
+ threadId: z.string(),
577
+ /** The id its message takes once a turn writes it. */
578
+ messageId: z.string(),
579
+ seq: z.number(),
580
+ authorPrincipal: AgentPrincipalSchema,
581
+ mode: z.enum(["steer", "queue"]),
582
+ parts: z.array(AgentMessagePartSchema),
583
+ spec: z
584
+ .object({
585
+ model: LanguageModelRefSchema.optional(),
586
+ reasoning: ModelReasoningSchema.optional(),
587
+ approvalMode: AgentApprovalModeSchema.optional(),
588
+ })
589
+ .optional(),
590
+ /** The time zone and locale its message was sent in, which its time renders in. */
591
+ timeZone: z.string().optional(),
592
+ locale: z.string().optional(),
593
+ /** Sent now: it starts even when the turn it waited for ended without answering. */
594
+ immediate: z.boolean().optional(),
595
+ createdAt: z.string(),
596
+ updatedAt: z.string(),
597
+ })
598
+
599
+ export const AgentInboxListResponseSchema = z.object({
600
+ items: z.array(AgentInboxItemSchema),
601
+ })
602
+
603
+ export const AgentThreadInboxParamsSchema = AgentThreadParamsSchema.extend({
604
+ itemId: z.string().min(1),
605
+ })
606
+
607
+ /** What the person who sent a waiting message may change about it. */
608
+ export const UpdateAgentInboxItemBodySchema = z
609
+ .object({
610
+ text: z.string().trim().min(1).optional(),
611
+ model: LanguageModelRefSchema.optional(),
612
+ reasoning: ModelReasoningSchema.optional(),
613
+ approvalMode: AgentApprovalModeSchema.optional(),
614
+ /** Steer the running turn with it, or keep it for the next one. */
615
+ delivery: z.enum(["steer", "queue"]).optional(),
616
+ /** Stop the turn it waits behind and start it now. */
617
+ immediate: z.literal(true).optional(),
618
+ })
619
+ .strict()
620
+
621
+ export const UpdateAgentInboxItemResponseSchema = z.object({
622
+ item: AgentInboxItemSchema,
623
+ })
624
+
625
+ /**
626
+ * What a sent message became: the turn it started, or the inbox item that waits beside the turn
627
+ * that runs. A message that starts a turn carries `run`, as it always has.
628
+ */
564
629
  export const PostAgentMessageResponseSchema = z.object({
565
- run: AgentRunSchema,
630
+ run: AgentRunSchema.optional(),
631
+ item: AgentInboxItemSchema.optional(),
566
632
  })
567
633
 
568
634
  export const CancelAgentRunResponseSchema = z.object({
@@ -17,6 +17,34 @@ const ArtifactFileSchema = z.object({
17
17
  const DocumentOutlineSchema = z.object({
18
18
  kind: z.literal("document"),
19
19
  headings: z.array(z.object({ depth: z.number().int(), text: z.string(), slug: z.string() })),
20
+ format: z
21
+ .literal("html")
22
+ .optional()
23
+ .describe("html for a designed document, document.html with its own stylesheets"),
24
+ paper: z
25
+ .object({
26
+ width: z.number(),
27
+ height: z.number(),
28
+ margin: z.object({
29
+ top: z.number(),
30
+ right: z.number(),
31
+ bottom: z.number(),
32
+ left: z.number(),
33
+ }),
34
+ })
35
+ .optional()
36
+ .describe(
37
+ "The sheet a designed document's @page rule sets, in CSS pixels: its size and margins"
38
+ ),
39
+ holder: z
40
+ .object({
41
+ objectTypeId: z.string(),
42
+ links: z.array(z.string()).describe("The holder's links its fields read through"),
43
+ })
44
+ .optional()
45
+ .describe(
46
+ 'The object a designed document shows live data of, as <meta name="sixb:object-type"> names its type: the one object of that type that holds the document'
47
+ ),
20
48
  })
21
49
 
22
50
  const SheetOutlineSchema = z.object({
@@ -145,8 +173,45 @@ export const ArtifactVersionSchema = z.object({
145
173
  .describe(
146
174
  "A canvas's boards by id, as reading or publishing the version returns them: ready when its preview is, pending while it is rendered, none when none will come and the board shows its outline"
147
175
  ),
176
+ printable: z
177
+ .boolean()
178
+ .optional()
179
+ .describe(
180
+ "true for a designed document in a project that prints to PDF: POST to its pdf route to print it, with the values whoever asks reads"
181
+ ),
182
+ })
183
+
184
+ const ArtifactPdfKeySchema = z
185
+ .string()
186
+ .regex(/^sha256:[0-9a-f]{64}$/)
187
+ .describe(
188
+ "The values a document that shows live data prints: ask with it again, and get that PDF with it, whatever the values are by then"
189
+ )
190
+
191
+ export const ArtifactPdfResponseSchema = z.discriminatedUnion("status", [
192
+ z.object({
193
+ status: z.literal("ready"),
194
+ pages: z.number().int().min(1).describe("How many pages it printed on"),
195
+ key: ArtifactPdfKeySchema.optional(),
196
+ }),
197
+ z.object({ status: z.literal("printing"), key: ArtifactPdfKeySchema.optional() }),
198
+ z.object({
199
+ status: z.literal("failed"),
200
+ reason: z.string().describe("Why it could not be printed"),
201
+ key: ArtifactPdfKeySchema.optional(),
202
+ }),
203
+ ])
204
+
205
+ export const ArtifactPdfQuerySchema = z.object({
206
+ retry: z
207
+ .enum(["true", "false"])
208
+ .optional()
209
+ .describe("true asks again for a PDF that could not be printed, instead of hearing why"),
210
+ key: ArtifactPdfKeySchema.optional(),
148
211
  })
149
212
 
213
+ export const ArtifactPdfDownloadQuerySchema = z.object({ key: ArtifactPdfKeySchema.optional() })
214
+
150
215
  const ArtifactVersionSummarySchema = ArtifactVersionSchema.pick({
151
216
  version: true,
152
217
  revision: true,
@@ -391,7 +456,7 @@ export const ArtifactErrorResponseSchema = ErrorResponseSchema.extend({
391
456
  .string()
392
457
  .optional()
393
458
  .describe(
394
- "Stable machine-readable failure code: artifact_not_found, artifact_kind_mismatch, artifact_moved, restore_point_not_found, comment_not_found, invalid_artifact, invalid_comment, invalid_state, name_required (a shared link's guest gives their name before commenting), state_full, comments_full, not_allowed, not_shared (it exists but neither a conversation nor an object you read shares it), read_only (you only read it), query_not_found, query_invalid (the ontology no longer admits the query), preview_not_found (the board has no preview yet, or will have none), execution_lost (a run token's run ended or moved to another runner), or storage_unavailable."
459
+ "Stable machine-readable failure code: artifact_not_found, artifact_kind_mismatch, artifact_moved, restore_point_not_found, comment_not_found, invalid_artifact, invalid_comment, invalid_state, name_required (a shared link's guest gives their name before commenting), state_full, comments_full, not_allowed, not_shared (it exists but neither a conversation nor an object you read shares it), read_only (you only read it), query_not_found, holder_not_found (no one object of the type a designed document names that you read holds it), query_invalid (the ontology no longer admits the query), preview_not_found (the board has no preview yet, or will have none), pdf_not_found (the document is not printed yet: ask for it first), pdf_unavailable (the project has no sandboxes to print in), execution_lost (a run token's run ended or moved to another runner), or storage_unavailable."
395
460
  ),
396
461
  latest: z
397
462
  .object({
@@ -90,6 +90,7 @@ export const EventExecutorSchema = z.discriminatedUnion("type", [
90
90
  z.object({ type: z.literal("ontology.indexVectors"), indexingId: z.string() }),
91
91
  ]),
92
92
  }),
93
+ z.object({ type: z.literal("script"), runId: z.string(), path: z.string() }),
93
94
  ])
94
95
 
95
96
  const StoredAuthorableEventBaseSchema = StoredEventBaseSchema.extend({
@@ -100,6 +100,7 @@ export const ObjectProjectionSchema = z.object({
100
100
  users: z.record(z.enum(["email", "id"])).optional(),
101
101
  links: z.record(ForeignKeyDescriptorSchema),
102
102
  conflictResolution: SourceEditConflictResolutionSchema,
103
+ missing: z.literal("remove").optional(),
103
104
  latestRun: ProjectionRunSchema.nullable(),
104
105
  })
105
106
 
package/src/server.ts CHANGED
@@ -306,7 +306,9 @@ export function createSixbApi(server: SixbServer) {
306
306
  )
307
307
  // A runner's session requests, before anything parses them: a runner token speaks only there.
308
308
  const serveRunnerSession = agentRunSessionHandler(host)
309
- app.onRequest(async ({ request }) => (await serveRunnerSession(request)) ?? undefined)
309
+ app.onRequest(
310
+ async ({ request, server }) => (await serveRunnerSession(request, server)) ?? undefined
311
+ )
310
312
  app.onRequest(async ({ request }) => {
311
313
  // An Agent's commands, as their run: decided before Elysia parses the body, which the approval
312
314
  // gate reads from a copy. No session, share or cookie speaks for such a request.