@sixb/server 0.2.1 → 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 (153) 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 +2876 -667
  10. package/dist/index.js.map +43 -36
  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 +21 -11
  20. package/dist/routes/agent-approvals.d.ts.map +1 -1
  21. package/dist/routes/agent-children.d.ts +4 -4
  22. package/dist/routes/agent-computers.d.ts +146 -1
  23. package/dist/routes/agent-computers.d.ts.map +1 -1
  24. package/dist/routes/agent-runners.d.ts.map +1 -1
  25. package/dist/routes/agents.d.ts +152 -60
  26. package/dist/routes/agents.d.ts.map +1 -1
  27. package/dist/routes/artifact-frames.d.ts +2 -1
  28. package/dist/routes/artifact-frames.d.ts.map +1 -1
  29. package/dist/routes/artifacts.d.ts +1713 -178
  30. package/dist/routes/artifacts.d.ts.map +1 -1
  31. package/dist/routes/auth.d.ts +21 -21
  32. package/dist/routes/connector-connection-runs.d.ts +124 -5
  33. package/dist/routes/connector-connection-runs.d.ts.map +1 -1
  34. package/dist/routes/connector-connections.d.ts +9 -1
  35. package/dist/routes/connector-connections.d.ts.map +1 -1
  36. package/dist/routes/datasets.d.ts +5 -5
  37. package/dist/routes/events.d.ts +4 -4
  38. package/dist/routes/lake.d.ts +91 -0
  39. package/dist/routes/lake.d.ts.map +1 -0
  40. package/dist/routes/links.d.ts +6 -6
  41. package/dist/routes/logs.d.ts +2 -2
  42. package/dist/routes/model-generations.d.ts +2 -2
  43. package/dist/routes/objects.d.ts +6 -6
  44. package/dist/routes/objects.d.ts.map +1 -1
  45. package/dist/routes/observed-agent-threads.d.ts +21 -11
  46. package/dist/routes/observed-agent-threads.d.ts.map +1 -1
  47. package/dist/routes/ontology.d.ts +6 -6
  48. package/dist/routes/pipelines.d.ts +13 -9
  49. package/dist/routes/pipelines.d.ts.map +1 -1
  50. package/dist/routes/projections.d.ts +27 -27
  51. package/dist/routes/share-grants.d.ts +9 -9
  52. package/dist/routes/shared-access.d.ts +57 -2
  53. package/dist/routes/shared-access.d.ts.map +1 -1
  54. package/dist/routes/status.d.ts +11 -15
  55. package/dist/routes/status.d.ts.map +1 -1
  56. package/dist/routes/syncs.d.ts +9 -6
  57. package/dist/routes/syncs.d.ts.map +1 -1
  58. package/dist/routes/telemetry.d.ts +7 -7
  59. package/dist/routes/webhooks.d.ts.map +1 -1
  60. package/dist/routes/workflows.d.ts +14 -14
  61. package/dist/routes/ws/artifacts.d.ts +57 -0
  62. package/dist/routes/ws/artifacts.d.ts.map +1 -0
  63. package/dist/routes/ws/events.d.ts +8 -7
  64. package/dist/routes/ws/events.d.ts.map +1 -1
  65. package/dist/routes/ws/index.d.ts +2 -1
  66. package/dist/routes/ws/index.d.ts.map +1 -1
  67. package/dist/routes/ws/logs.d.ts +10 -10
  68. package/dist/routes/ws/shared-sockets.d.ts +52 -0
  69. package/dist/routes/ws/shared-sockets.d.ts.map +1 -0
  70. package/dist/schemas/actions.d.ts +7 -7
  71. package/dist/schemas/activity.d.ts +16 -16
  72. package/dist/schemas/agent-approvals.d.ts +27 -27
  73. package/dist/schemas/agents.d.ts +642 -196
  74. package/dist/schemas/agents.d.ts.map +1 -1
  75. package/dist/schemas/ai-accounting.d.ts +41 -41
  76. package/dist/schemas/ai-accounting.d.ts.map +1 -1
  77. package/dist/schemas/artifacts.d.ts +2106 -127
  78. package/dist/schemas/artifacts.d.ts.map +1 -1
  79. package/dist/schemas/auth.d.ts +63 -63
  80. package/dist/schemas/connectors.d.ts +180 -20
  81. package/dist/schemas/connectors.d.ts.map +1 -1
  82. package/dist/schemas/datasets.d.ts +44 -44
  83. package/dist/schemas/event-payloads.d.ts +2 -2
  84. package/dist/schemas/events.d.ts +26 -26
  85. package/dist/schemas/events.d.ts.map +1 -1
  86. package/dist/schemas/files.d.ts +12 -0
  87. package/dist/schemas/files.d.ts.map +1 -1
  88. package/dist/schemas/lake.d.ts +251 -0
  89. package/dist/schemas/lake.d.ts.map +1 -0
  90. package/dist/schemas/lineage.d.ts +56 -56
  91. package/dist/schemas/logs.d.ts +18 -18
  92. package/dist/schemas/models.d.ts +4 -4
  93. package/dist/schemas/objects.d.ts.map +1 -1
  94. package/dist/schemas/ontology.d.ts +14 -14
  95. package/dist/schemas/pipelines.d.ts +86 -64
  96. package/dist/schemas/pipelines.d.ts.map +1 -1
  97. package/dist/schemas/projections.d.ts +160 -160
  98. package/dist/schemas/projections.d.ts.map +1 -1
  99. package/dist/schemas/share-grants.d.ts +30 -30
  100. package/dist/schemas/shared-access.d.ts +17 -4
  101. package/dist/schemas/shared-access.d.ts.map +1 -1
  102. package/dist/schemas/status.d.ts +59 -79
  103. package/dist/schemas/status.d.ts.map +1 -1
  104. package/dist/schemas/syncs.d.ts +38 -22
  105. package/dist/schemas/syncs.d.ts.map +1 -1
  106. package/dist/schemas/telemetry.d.ts +26 -26
  107. package/dist/schemas/workflows.d.ts +71 -71
  108. package/dist/server.d.ts +13 -0
  109. package/dist/server.d.ts.map +1 -1
  110. package/dist/utils/ws.d.ts +3 -0
  111. package/dist/utils/ws.d.ts.map +1 -1
  112. package/package.json +11 -7
  113. package/src/artifacts/frame.ts +4 -13
  114. package/src/auth/scope.ts +10 -1
  115. package/src/auth/shared-access.ts +108 -12
  116. package/src/connectors/http.ts +35 -1
  117. package/src/live/README.md +136 -0
  118. package/src/live/awareness.ts +141 -0
  119. package/src/live/room.ts +933 -0
  120. package/src/live/rooms.ts +288 -0
  121. package/src/registerRoutes.ts +2 -0
  122. package/src/routes/agent-computers.ts +208 -14
  123. package/src/routes/agent-runners.ts +1 -0
  124. package/src/routes/agents.ts +52 -7
  125. package/src/routes/artifact-frames.ts +40 -12
  126. package/src/routes/artifacts.ts +713 -28
  127. package/src/routes/connector-connection-runs.ts +7 -12
  128. package/src/routes/connector-connections.ts +10 -7
  129. package/src/routes/lake.ts +73 -0
  130. package/src/routes/objects.ts +3 -9
  131. package/src/routes/pipelines.ts +1 -0
  132. package/src/routes/shared-access.ts +53 -1
  133. package/src/routes/status.ts +9 -4
  134. package/src/routes/syncs.ts +1 -0
  135. package/src/routes/webhooks.ts +44 -3
  136. package/src/routes/ws/artifacts.ts +138 -0
  137. package/src/routes/ws/events.ts +7 -2
  138. package/src/routes/ws/index.ts +13 -2
  139. package/src/routes/ws/shared-sockets.ts +152 -0
  140. package/src/schemas/agents.ts +71 -1
  141. package/src/schemas/ai-accounting.ts +1 -0
  142. package/src/schemas/artifacts.ts +255 -18
  143. package/src/schemas/connectors.ts +17 -2
  144. package/src/schemas/files.ts +12 -0
  145. package/src/schemas/lake.ts +53 -0
  146. package/src/schemas/objects.ts +1 -0
  147. package/src/schemas/pipelines.ts +2 -0
  148. package/src/schemas/projections.ts +2 -2
  149. package/src/schemas/shared-access.ts +16 -0
  150. package/src/schemas/status.ts +16 -22
  151. package/src/schemas/syncs.ts +2 -0
  152. package/src/server.ts +35 -4
  153. package/src/utils/ws.ts +7 -0
@@ -0,0 +1,152 @@
1
+ import type { SharedSessionContext } from "@sixb/core/internal/shares"
2
+ import type { SharedAccessBoundary } from "../../auth/shared-access"
3
+ import { wsSharedSession, wsStateKey } from "../../utils/ws"
4
+
5
+ /**
6
+ * How long a shared link's socket trusts its session before reading it again: on a timer, so a
7
+ * socket that only listens closes too, and on its next message past that.
8
+ */
9
+ export const SHARED_SOCKET_RECHECK_MS = 10_000
10
+
11
+ /**
12
+ * The close code of a socket whose shared link ended: revoked, expired, or left idle. The client
13
+ * stops reconnecting on it (`SHARED_ACCESS_ENDED_CLOSE_CODE` in `@sixb/client`).
14
+ */
15
+ export const SHARED_ACCESS_ENDED_CLOSE_CODE = 4401
16
+
17
+ /** A socket closed because its session could not be read: the client reconnects. */
18
+ const UNREADABLE_SESSION_CLOSE_CODE = 1011
19
+
20
+ /** A socket, as far as watching it goes: closing it. */
21
+ export interface ClosableSocket {
22
+ close(code?: number, reason?: string): void
23
+ }
24
+
25
+ interface Watch {
26
+ /** The session as last read; null once it ended. */
27
+ current: Promise<SharedSessionContext | null>
28
+ checkedAt: number
29
+ /** The name the visitor gave, as last read: a change is passed on to `onRenamed`. */
30
+ name: string | undefined
31
+ readonly timer: ReturnType<typeof setInterval>
32
+ readonly onRenamed: (() => void) | undefined
33
+ }
34
+
35
+ /**
36
+ * The sockets shared links' sessions opened, each kept open only while its session holds.
37
+ *
38
+ * The upgrade proved the session once, as any request does, and the socket's SDK keeps that
39
+ * authority. A link revoked or a session expired since would go unnoticed, so each socket reads its
40
+ * session again, by its id, at most every {@link SHARED_SOCKET_RECHECK_MS}, and is closed with
41
+ * {@link SHARED_ACCESS_ENDED_CLOSE_CODE} once it ended. Reading it renews nothing: only a visitor's
42
+ * own requests keep their session from idling out.
43
+ */
44
+ export class SharedSockets {
45
+ private readonly watches = new WeakMap<object, Watch>()
46
+ /**
47
+ * The open sockets of each session, read again at once when its visitor gives a name. Keyed by
48
+ * `wsStateKey`: Elysia hands each handler a wrapper of its own around the one raw socket.
49
+ */
50
+ private readonly sockets = new Map<string, Map<object, ClosableSocket>>()
51
+
52
+ constructor(private readonly boundary: SharedAccessBoundary) {
53
+ // A name given through this server reaches its sockets at once; through another, at the next
54
+ // read, within SHARED_SOCKET_RECHECK_MS.
55
+ boundary.onGuestNamed((sessionId) => {
56
+ for (const ws of this.sockets.get(sessionId)?.values() ?? []) {
57
+ const watch = this.watches.get(wsStateKey(ws))
58
+ const session = wsSharedSession(ws)
59
+ if (watch && session) this.read(ws, watch, session)
60
+ }
61
+ })
62
+ }
63
+
64
+ /**
65
+ * Starts watching a socket that a shared link's session opened; any other is left alone.
66
+ * `onRenamed` hears when its visitor gives a name, or another, read from their session.
67
+ */
68
+ open(ws: ClosableSocket, onRenamed?: () => void): void {
69
+ const session = wsSharedSession(ws)
70
+ if (!session) return
71
+
72
+ const watch: Watch = {
73
+ current: Promise.resolve(session),
74
+ checkedAt: Date.now(),
75
+ name: session.guestName,
76
+ timer: setInterval(() => void this.read(ws, watch, session), SHARED_SOCKET_RECHECK_MS),
77
+ onRenamed,
78
+ }
79
+ this.watches.set(wsStateKey(ws), watch)
80
+
81
+ const open = this.sockets.get(session.sessionId) ?? new Map<object, ClosableSocket>()
82
+ this.sockets.set(session.sessionId, open.set(wsStateKey(ws), ws))
83
+ }
84
+
85
+ /**
86
+ * Whether the socket may go on: false once the session that opened it ended, and the socket is
87
+ * closing. Always true for a socket no shared link opened.
88
+ */
89
+ async holds(ws: ClosableSocket): Promise<boolean> {
90
+ const watch = this.watches.get(wsStateKey(ws))
91
+ const session = wsSharedSession(ws)
92
+ if (!watch || !session) return true
93
+
94
+ if (Date.now() - watch.checkedAt >= SHARED_SOCKET_RECHECK_MS) this.read(ws, watch, session)
95
+ return (await watch.current) !== null
96
+ }
97
+
98
+ /** The session that opened the socket, as it is now: its visitor's name, once they gave one. */
99
+ async session(ws: ClosableSocket): Promise<SharedSessionContext | null> {
100
+ const watch = this.watches.get(wsStateKey(ws))
101
+ const session = wsSharedSession(ws)
102
+ if (!watch || !session) return null
103
+
104
+ this.read(ws, watch, session)
105
+ return watch.current
106
+ }
107
+
108
+ /** Stops watching a socket that closed. */
109
+ close(ws: ClosableSocket): void {
110
+ const key = wsStateKey(ws)
111
+ const watch = this.watches.get(key)
112
+ if (watch) clearInterval(watch.timer)
113
+ this.watches.delete(key)
114
+
115
+ const session = wsSharedSession(ws)
116
+ const open = session ? this.sockets.get(session.sessionId) : undefined
117
+ open?.delete(key)
118
+ if (session && open?.size === 0) this.sockets.delete(session.sessionId)
119
+ }
120
+
121
+ private read(ws: ClosableSocket, watch: Watch, session: SharedSessionContext): void {
122
+ watch.checkedAt = Date.now()
123
+ watch.current = this.boundary.current(session).then(
124
+ (current) => {
125
+ if (!current) {
126
+ this.end(ws, SHARED_ACCESS_ENDED_CLOSE_CODE, "Shared access ended")
127
+ return current
128
+ }
129
+
130
+ if (current.guestName !== watch.name) {
131
+ watch.name = current.guestName
132
+ watch.onRenamed?.()
133
+ }
134
+ return current
135
+ },
136
+ (error: unknown) => {
137
+ console.error("[SixbServer] A shared link's socket could not read its session:", error)
138
+ this.end(ws, UNREADABLE_SESSION_CLOSE_CODE, "Shared access could not be checked")
139
+ return null
140
+ }
141
+ )
142
+ }
143
+
144
+ private end(ws: ClosableSocket, code: number, reason: string): void {
145
+ this.close(ws)
146
+ try {
147
+ ws.close(code, reason)
148
+ } catch {
149
+ // Already closed.
150
+ }
151
+ }
152
+ }
@@ -121,6 +121,25 @@ export const AgentThreadComputerInputSchema = z
121
121
  })
122
122
  .strict()
123
123
 
124
+ /**
125
+ * A background command `sixb` runs for one of your threads on your computer: it outlives the turn
126
+ * that started it, until it exits, the agent or you stop it, or `sixb` closes.
127
+ */
128
+ export const AgentBackgroundCommandSchema = z
129
+ .object({
130
+ threadId: z.string().min(1).max(200),
131
+ /** `bg_<hex>`, as the agent's tools name it: with `startedAt`, it names the command. */
132
+ id: z.string().min(1).max(200),
133
+ /** Its first 1,000 characters. */
134
+ command: z.string().max(1_000),
135
+ status: z.enum(["running", "exited", "stopped"]),
136
+ /** Once it ended: a stopped command's is its signal's, such as 143 for SIGTERM. */
137
+ exitCode: z.number().int().optional(),
138
+ startedAt: z.string().min(1).max(200),
139
+ endedAt: z.string().max(200).optional(),
140
+ })
141
+ .strict()
142
+
124
143
  export const CreateAgentThreadBodySchema = z
125
144
  .object({
126
145
  title: z.string().trim().min(1).optional(),
@@ -186,6 +205,14 @@ export const AgentThreadSchema = z.object({
186
205
  online: z.boolean(),
187
206
  })
188
207
  .optional(),
208
+ /**
209
+ * Its background commands on its owner's computer, as `sixb` reported them while open: the
210
+ * running ones, then the latest to end, wherever the thread runs now. `stopping` while a stop
211
+ * you asked for is on its way. Shown to its owner alone.
212
+ */
213
+ backgroundCommands: z
214
+ .array(AgentBackgroundCommandSchema.extend({ stopping: z.boolean().optional() }))
215
+ .optional(),
189
216
  /** When its turns last moved to where they run now: the files earlier turns used are not here. */
190
217
  movedAt: z.string().optional(),
191
218
  status: AgentThreadStatusSchema,
@@ -222,14 +249,57 @@ export const AgentComputerSessionParamsSchema = z.object({
222
249
  })
223
250
 
224
251
  export const HoldAgentComputerSessionBodySchema = z
225
- .object({ computer: AgentThreadComputerInputSchema })
252
+ .object({
253
+ computer: AgentThreadComputerInputSchema,
254
+ /**
255
+ * Your threads' background commands this `sixb` runs or ran: the running ones, then the latest
256
+ * to end. Absent, none.
257
+ */
258
+ backgroundCommands: z.array(AgentBackgroundCommandSchema).max(64).optional(),
259
+ })
226
260
  .strict()
227
261
 
262
+ /** A background command by its start, as its id comes again once `sixb` restarts. */
263
+ export const AgentBackgroundCommandRefSchema = z.object({
264
+ threadId: z.string(),
265
+ id: z.string(),
266
+ startedAt: z.string(),
267
+ })
268
+
228
269
  export const HoldAgentComputerSessionResponseSchema = z.object({
229
270
  /** Renew before then, or the session lapses and its threads read as offline. */
230
271
  expiresAt: z.string(),
231
272
  /** Queued turns of your threads on this computer, in this folder, for it to claim. */
232
273
  waiting: z.array(z.string()),
274
+ /** Running background commands someone asked to stop from elsewhere, for it to stop. */
275
+ stop: z.array(AgentBackgroundCommandRefSchema).optional(),
276
+ })
277
+
278
+ export const AgentBackgroundCommandParamsSchema = z.object({
279
+ threadId: z.string().trim().min(1),
280
+ commandId: z.string().trim().min(1).max(200),
281
+ })
282
+
283
+ export const StopAgentBackgroundCommandBodySchema = z
284
+ .object({
285
+ /** When it started, as reported: an id names another command once `sixb` restarts. */
286
+ startedAt: z.string().trim().min(1).max(200),
287
+ })
288
+ .strict()
289
+
290
+ export const StopAgentBackgroundCommandResponseSchema = z.object({
291
+ command: AgentBackgroundCommandSchema.extend({ stopping: z.boolean().optional() }),
292
+ })
293
+
294
+ /** One of your computers with `sixb` open on it now, and the folders it's open in. */
295
+ export const AgentComputerSchema = z.object({
296
+ id: z.string(),
297
+ name: z.string(),
298
+ folders: z.array(z.string()),
299
+ })
300
+
301
+ export const AgentComputerListResponseSchema = z.object({
302
+ computers: z.array(AgentComputerSchema),
233
303
  })
234
304
 
235
305
  export const AddAgentThreadParticipantsBodySchema = z
@@ -23,6 +23,7 @@ const ModelKindSchema = z.enum([
23
23
  "transcription",
24
24
  "speech",
25
25
  "reranking",
26
+ "web-search",
26
27
  ])
27
28
 
28
29
  export const AiAccountingRangeQuerySchema = z.object({
@@ -1,7 +1,8 @@
1
- import { ARTIFACT_KINDS, ARTIFACT_STATE_LIMITS } from "@sixb/core/artifacts"
1
+ import { ARTIFACT_HOLDERS_LIMIT, ARTIFACT_KINDS, ARTIFACT_STATE_LIMITS } from "@sixb/core/artifacts"
2
+ import { ARTIFACT_RESTORE_POINTS } from "@sixb/core/internal/storage"
2
3
  import { z } from "zod"
3
4
  import { ErrorResponseSchema, PrincipalSchema } from "./common"
4
- import { FileRefSchema } from "./files"
5
+ import { FileRefSchema, ShareGrantQuerySchema } from "./files"
5
6
 
6
7
  const ArtifactKindSchema = z.enum(ARTIFACT_KINDS)
7
8
 
@@ -41,6 +42,8 @@ const SlidesOutlineSchema = z.object({
41
42
 
42
43
  const PageOutlineSchema = z.object({ kind: z.literal("page"), title: z.string().optional() })
43
44
 
45
+ const ArtifactThemeModeSchema = z.enum(["light", "dark"])
46
+
44
47
  const CanvasOutlineSchema = z.object({
45
48
  kind: z.literal("canvas"),
46
49
  items: z.array(
@@ -52,10 +55,18 @@ const CanvasOutlineSchema = z.object({
52
55
  file: z.string(),
53
56
  w: z.number(),
54
57
  h: z.number(),
58
+ renderKey: z
59
+ .string()
60
+ .optional()
61
+ .describe("What the board's preview is a picture of: a board kept as it was keeps it"),
55
62
  }),
56
63
  z.object({ id: z.string(), type: z.literal("section"), title: z.string().optional() }),
57
64
  ])
58
65
  ),
66
+ themes: z
67
+ .array(ArtifactThemeModeSchema)
68
+ .optional()
69
+ .describe("The modes each board has a preview in: both, or the one its theme.json pins"),
59
70
  })
60
71
 
61
72
  const FileOutlineSchema = z.object({ kind: z.literal("file"), mediaType: z.string() })
@@ -82,6 +93,14 @@ const ArtifactWarningSchema = z.object({
82
93
  part: z.string().optional(),
83
94
  })
84
95
 
96
+ const RevisionSchema = z
97
+ .number()
98
+ .int()
99
+ .positive()
100
+ .describe(
101
+ "Counts the artifact's changes: a write, a version created, a restore. It only grows, so content read at one revision is that revision's for good"
102
+ )
103
+
85
104
  const ArtifactSchema = z.object({
86
105
  id: z.string(),
87
106
  projectId: z.string(),
@@ -89,8 +108,9 @@ const ArtifactSchema = z.object({
89
108
  title: z.string(),
90
109
  owner: PrincipalSchema,
91
110
  latestVersion: z.number().int().positive(),
111
+ revision: RevisionSchema,
92
112
  createdAt: z.string(),
93
- updatedAt: z.string(),
113
+ updatedAt: z.string().describe("When the artifact last changed"),
94
114
  })
95
115
 
96
116
  const ArtifactOriginSchema = z.object({ threadId: z.string(), runId: z.string() })
@@ -98,22 +118,46 @@ const ArtifactOriginSchema = z.object({ threadId: z.string(), runId: z.string()
98
118
  export const ArtifactVersionSchema = z.object({
99
119
  artifactId: z.string(),
100
120
  version: z.number().int().positive(),
121
+ revision: RevisionSchema.describe(
122
+ "The artifact's revision when this version last changed: the latest version's is the artifact's"
123
+ ),
124
+ frozen: z
125
+ .boolean()
126
+ .describe(
127
+ "Someone created this version: it never changes again. The latest version is open until then, and each write replaces its content"
128
+ ),
101
129
  title: z.string(),
102
130
  entry: z.string(),
103
131
  files: z.array(ArtifactFileSchema),
104
132
  outline: ArtifactOutlineSchema,
105
133
  references: z.array(ArtifactReferenceSchema),
106
- author: PrincipalSchema,
107
- origin: ArtifactOriginSchema.optional(),
108
- createdAt: z.string(),
134
+ author: PrincipalSchema.describe("Who last wrote its content"),
135
+ origin: ArtifactOriginSchema.optional().describe(
136
+ "The Agent turn and thread its content was last written from"
137
+ ),
138
+ createdAt: z.string().describe("When the version was opened"),
139
+ updatedAt: z.string().describe("When its content was last written"),
140
+ frozenAt: z.string().optional().describe("When it was created, which froze it"),
141
+ frozenBy: PrincipalSchema.optional().describe("Who created it"),
142
+ boardPreviews: z
143
+ .record(z.string(), z.enum(["ready", "pending", "none"]))
144
+ .optional()
145
+ .describe(
146
+ "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
+ ),
109
148
  })
110
149
 
111
150
  const ArtifactVersionSummarySchema = ArtifactVersionSchema.pick({
112
151
  version: true,
152
+ revision: true,
153
+ frozen: true,
113
154
  title: true,
114
155
  author: true,
115
156
  origin: true,
116
157
  createdAt: true,
158
+ updatedAt: true,
159
+ frozenAt: true,
160
+ frozenBy: true,
117
161
  })
118
162
 
119
163
  export const ArtifactParamsSchema = z.object({ artifactId: z.string().min(1) })
@@ -125,6 +169,41 @@ export const ArtifactVersionParamsSchema = ArtifactParamsSchema.extend({
125
169
  .describe('A version number, or "latest"'),
126
170
  })
127
171
 
172
+ export const ArtifactBoardPreviewParamsSchema = ArtifactVersionParamsSchema.extend({
173
+ board: z.string().min(1).describe("The board's id in the canvas"),
174
+ })
175
+
176
+ export const ArtifactBoardPreviewQuerySchema = z
177
+ .object({
178
+ theme: ArtifactThemeModeSchema.optional().describe(
179
+ "The reader's mode; a canvas whose theme.json pins one is pictured only in it"
180
+ ),
181
+ size: z
182
+ .enum(["full", "small"])
183
+ .optional()
184
+ .describe(
185
+ "full, the default: a PNG of the board at its own size. small: a WebP at most 480 pixels wide, for a canvas that shows many boards at once"
186
+ ),
187
+ revision: z.coerce
188
+ .number()
189
+ .int()
190
+ .min(1)
191
+ .optional()
192
+ .describe(
193
+ "The version's revision the picture is of. Another than the version's current one is 404 preview_not_found: the version changed, and says which pictures it has now. One that matches is cached for good"
194
+ ),
195
+ key: z
196
+ .string()
197
+ .min(1)
198
+ .max(200)
199
+ .optional()
200
+ .describe(
201
+ "The board's render key the picture is of, as the version's outline names it, in place of revision: the picture stays the same while the board shows the same, however often the canvas around it changes. Another than the board's current one is 404 preview_not_found. One that matches is cached for good"
202
+ ),
203
+ })
204
+ .extend(ShareGrantQuerySchema.shape)
205
+ .strict()
206
+
128
207
  export const ArtifactQueryParamsSchema = ArtifactVersionParamsSchema.extend({
129
208
  name: z.string().min(1).describe("The query's name: queries/<name>.json in the version"),
130
209
  })
@@ -135,7 +214,7 @@ export const ArtifactListQuerySchema = z
135
214
  .string()
136
215
  .min(1)
137
216
  .optional()
138
- .describe("Only artifacts with a version the Agent published in this thread"),
217
+ .describe("Only artifacts this conversation shares: the Agent wrote them in it"),
139
218
  kind: ArtifactKindSchema.optional().describe("Only artifacts of this kind"),
140
219
  limit: z.string().optional(),
141
220
  offset: z.string().optional(),
@@ -154,7 +233,7 @@ export const ArtifactResponseSchema = z.object({
154
233
  access: z
155
234
  .enum(["owner", "update", "read"])
156
235
  .describe(
157
- "What the caller may do with it: everything as its owner, publish and keep page data as a participant of a conversation that shares it, or only read as an observer of one"
236
+ "What the caller may do with it: everything as its owner, publish and keep page data as a participant of a conversation that shares it or an editor of an object that holds it, or only read as an observer of such a conversation or a reader of such an object"
158
237
  ),
159
238
  })
160
239
 
@@ -169,15 +248,90 @@ export const PublishArtifactBodySchema = z
169
248
  })
170
249
  .strict()
171
250
 
172
- export const PublishArtifactVersionBodySchema = PublishArtifactBodySchema.extend({
173
- baseVersion: z
174
- .number()
175
- .int()
176
- .positive()
177
- .optional()
251
+ const BaseRevisionSchema = z
252
+ .number()
253
+ .int()
254
+ .positive()
255
+ .optional()
256
+ .describe(
257
+ "The revision this was made from. When the artifact changed since, it is refused with 409 artifact_moved, naming the revision and who last wrote the latest version."
258
+ )
259
+
260
+ export const UpdateArtifactBodySchema = PublishArtifactBodySchema.extend({
261
+ baseRevision: BaseRevisionSchema,
262
+ })
263
+
264
+ export const FreezeArtifactBodySchema = z
265
+ .object({ baseRevision: BaseRevisionSchema })
266
+ .strict()
267
+ .default({})
268
+
269
+ export const RestoreArtifactBodySchema = z
270
+ .object({ baseRevision: BaseRevisionSchema })
271
+ .strict()
272
+ .default({})
273
+
274
+ export const ArtifactRestorePointParamsSchema = ArtifactParamsSchema.extend({
275
+ revision: z
276
+ .string()
277
+ .regex(/^[1-9]\d*$/)
278
+ .describe("The revision whose content the restore point holds"),
279
+ })
280
+
281
+ /** A restore point without its files: the list a Restore menu shows. */
282
+ const ArtifactRestorePointSummarySchema = z.object({
283
+ artifactId: z.string(),
284
+ revision: RevisionSchema.describe("The revision whose content it holds, which restores it"),
285
+ version: z.number().int().positive().describe("The version it was taken of"),
286
+ frozen: z
287
+ .boolean()
178
288
  .describe(
179
- "The version this one was made from. When another was published since, the publish is refused with 409 artifact_moved, naming the latest version."
289
+ "Whether that version was already created, and so frozen, when the point was taken: its content is then that version's"
180
290
  ),
291
+ title: z.string(),
292
+ author: PrincipalSchema.describe("Who had last written that content"),
293
+ origin: ArtifactOriginSchema.optional(),
294
+ updatedAt: z.string().describe("When that content was written"),
295
+ reason: z
296
+ .enum(["turn", "restore"])
297
+ .describe("Taken before an Agent turn's first write to the artifact, or before a restore"),
298
+ turnRunId: z.string().optional().describe("With turn: the turn's run"),
299
+ createdAt: z.string().describe("When it was taken"),
300
+ })
301
+
302
+ export const ArtifactRestorePointSchema = ArtifactRestorePointSummarySchema.extend({
303
+ entry: z.string(),
304
+ files: z.array(ArtifactFileSchema),
305
+ outline: ArtifactOutlineSchema,
306
+ references: z.array(ArtifactReferenceSchema),
307
+ })
308
+
309
+ export const ArtifactRestorePointListResponseSchema = z.object({
310
+ restorePoints: z
311
+ .array(ArtifactRestorePointSummarySchema)
312
+ .describe(`Newest first: an artifact keeps its last ${ARTIFACT_RESTORE_POINTS}`),
313
+ })
314
+
315
+ export const ArtifactHolderSchema = z.object({
316
+ objectTypeId: z.string(),
317
+ primaryId: z.string(),
318
+ propertyId: z.string().describe("The property whose value holds the artifact"),
319
+ title: z
320
+ .string()
321
+ .optional()
322
+ .describe("The object's value of its type's search title, when it has one you read"),
323
+ })
324
+
325
+ export const ArtifactHolderListResponseSchema = z.object({
326
+ holders: z
327
+ .array(ArtifactHolderSchema)
328
+ .describe(`The first ${ARTIFACT_HOLDERS_LIMIT} objects you read that hold the artifact`),
329
+ hasMore: z.boolean().describe("More objects you read hold it"),
330
+ })
331
+
332
+ export const ArtifactChangeResponseSchema = z.object({
333
+ artifact: ArtifactSchema,
334
+ version: ArtifactVersionSchema,
181
335
  })
182
336
 
183
337
  export const PublishedArtifactResponseSchema = z.object({
@@ -237,10 +391,93 @@ export const ArtifactErrorResponseSchema = ErrorResponseSchema.extend({
237
391
  .string()
238
392
  .optional()
239
393
  .describe(
240
- "Stable machine-readable failure code: artifact_not_found, artifact_kind_mismatch, artifact_moved, invalid_artifact, invalid_state, state_full, not_allowed, not_shared (it exists but no conversation you read shares it), read_only (you observe the conversation that shares it), query_not_found, query_invalid (the ontology no longer admits the query), execution_lost (a run token's run ended or moved to another runner), or storage_unavailable."
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."
241
395
  ),
242
396
  latest: z
243
- .object({ version: z.number().int(), author: PrincipalSchema })
397
+ .object({
398
+ version: z.number().int(),
399
+ revision: z.number().int(),
400
+ author: PrincipalSchema,
401
+ frozenBy: PrincipalSchema.optional(),
402
+ })
403
+ .optional()
404
+ .describe(
405
+ "With artifact_moved: the artifact's latest version, its revision, who last wrote it, and who created it once it is frozen"
406
+ ),
407
+ })
408
+
409
+ const ArtifactCommentAnchorSchema = z.object({
410
+ board: z.string().max(200).optional().describe("The id of the canvas's board it is about"),
411
+ element: z
412
+ .string()
413
+ .max(1024)
414
+ .optional()
415
+ .describe("The address of the board's element it is about, such as body>main:0>h1:0"),
416
+ label: z
417
+ .string()
418
+ .max(1000)
419
+ .optional()
420
+ .describe("The element's first words, which name it once it is gone; kept to 120 characters"),
421
+ point: z
422
+ .object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1) })
423
+ .optional()
424
+ .describe(
425
+ "Where on the board its pin is, as fractions of the board's width and height from its top left"
426
+ ),
427
+ revision: RevisionSchema.describe("The artifact's revision its author saw"),
428
+ })
429
+
430
+ const ArtifactCommentAuthorSchema = z
431
+ .object({
432
+ type: z.enum(["user", "serviceAccount", "system", "guest"]),
433
+ id: z.string().min(1),
434
+ })
435
+ .describe(
436
+ "Who wrote it: a principal, or a guest, someone without an account who opened a shared link, whose id is their link's session"
437
+ )
438
+
439
+ export const ArtifactCommentSchema = z.object({
440
+ artifactId: z.string(),
441
+ id: z.string(),
442
+ parentId: z.string().optional().describe("The comment it replies to, for a reply"),
443
+ anchor: ArtifactCommentAnchorSchema,
444
+ body: z.string().describe("Plain text"),
445
+ author: ArtifactCommentAuthorSchema,
446
+ authorName: z
447
+ .string()
448
+ .nullable()
449
+ .describe(
450
+ "Its author's name: a member's profile name or email, the project's for its own code, or the name a guest gave; null for anyone the project cannot name. A guest reading it never gets a member's email"
451
+ ),
452
+ origin: z
453
+ .object({ threadId: z.string(), runId: z.string() })
244
454
  .optional()
245
- .describe("With artifact_moved: the latest version and who published it"),
455
+ .describe("The Agent's run that wrote it for its author, and that run's conversation"),
456
+ createdAt: z.string(),
457
+ resolvedAt: z.string().optional().describe("When someone marked it resolved"),
458
+ resolvedBy: PrincipalSchema.optional().describe("Who marked it resolved"),
246
459
  })
460
+
461
+ export const ArtifactCommentListResponseSchema = z.object({
462
+ comments: z.array(ArtifactCommentSchema).describe("Comments and replies, oldest first"),
463
+ })
464
+
465
+ export const ArtifactCommentParamsSchema = ArtifactParamsSchema.extend({
466
+ commentId: z.string().min(1).max(64),
467
+ })
468
+
469
+ export const AddArtifactCommentBodySchema = z.object({
470
+ body: z.string().min(1).max(4_000).describe("Plain text"),
471
+ anchor: ArtifactCommentAnchorSchema.partial()
472
+ .optional()
473
+ .describe(
474
+ "What it is about: a board, an element of the board, or, without, the artifact; at the artifact's revision by default. A reply is about what it replies to."
475
+ ),
476
+ parentId: z.string().min(1).max(64).optional().describe("The comment it replies to"),
477
+ })
478
+
479
+ export const ResolveArtifactCommentBodySchema = z.object({
480
+ resolved: z.boolean().default(true).describe("False opens it again"),
481
+ })
482
+
483
+ export const DeleteArtifactCommentResponseSchema = z.object({ deleted: z.literal(true) })
@@ -84,10 +84,16 @@ export const ConnectorAccountSchema = z.object({
84
84
  avatarUrl: z.string().url().optional(),
85
85
  })
86
86
 
87
+ /** The project, or the one person whose own account the connection is. */
88
+ const ConnectorConnectionOwnerSchema = z.discriminatedUnion("type", [
89
+ z.object({ type: z.literal("project") }),
90
+ z.object({ type: z.literal("user"), id: z.string() }),
91
+ ])
92
+
87
93
  export const ConnectorConnectionSchema = z.object({
88
94
  id: z.string(),
89
95
  connectorId: z.string(),
90
- owner: z.object({ type: z.literal("project") }),
96
+ owner: ConnectorConnectionOwnerSchema,
91
97
  slot: z.string(),
92
98
  account: ConnectorAccountSchema,
93
99
  status: z.enum(["connected", "needs_reauthorization", "disconnected"]),
@@ -100,7 +106,7 @@ const ConnectorConnectionRunBaseSchema = z.object({
100
106
  id: z.string(),
101
107
  connectorId: z.string(),
102
108
  kind: z.enum(["connect", "reauthorize"]),
103
- owner: z.object({ type: z.literal("project") }),
109
+ owner: ConnectorConnectionOwnerSchema,
104
110
  slot: z.string(),
105
111
  createdAt: z.string().datetime(),
106
112
  updatedAt: z.string().datetime(),
@@ -136,12 +142,21 @@ export const ConnectorConnectionRunSchema = z.union([
136
142
  }),
137
143
  ])
138
144
 
145
+ /** `"me"` fills the caller's own connection, on a connector whose owners include `"user"`. */
146
+ const ConnectorConnectionOwnerChoiceSchema = z.enum(["project", "me"])
147
+
148
+ export const ListConnectorConnectionsQuerySchema = z.object({
149
+ owner: ConnectorConnectionOwnerChoiceSchema.optional(),
150
+ })
151
+
139
152
  export const StartConnectorConnectionRunBodySchema = z.object({
153
+ owner: ConnectorConnectionOwnerChoiceSchema.default("project"),
140
154
  slot: z.string().trim().min(1),
141
155
  returnTo: z.string().url(),
142
156
  })
143
157
 
144
158
  export const AddConnectorConnectionBodySchema = z.object({
159
+ owner: ConnectorConnectionOwnerChoiceSchema.default("project"),
145
160
  slot: z.string().trim().min(1),
146
161
  })
147
162