@sixb/server 0.1.21 → 0.1.23

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 (165) hide show
  1. package/dist/artifacts/frame.d.ts +5 -0
  2. package/dist/artifacts/frame.d.ts.map +1 -1
  3. package/dist/auth/browser-origin.d.ts +5 -1
  4. package/dist/auth/browser-origin.d.ts.map +1 -1
  5. package/dist/auth/experience.d.ts +1 -0
  6. package/dist/auth/experience.d.ts.map +1 -1
  7. package/dist/auth/public-routes.d.ts.map +1 -1
  8. package/dist/auth/responses.d.ts +1 -1
  9. package/dist/auth/responses.d.ts.map +1 -1
  10. package/dist/auth/scope.d.ts +19 -3
  11. package/dist/auth/scope.d.ts.map +1 -1
  12. package/dist/index.js +10093 -7553
  13. package/dist/index.js.map +51 -39
  14. package/dist/models/display.d.ts +27 -0
  15. package/dist/models/display.d.ts.map +1 -1
  16. package/dist/openapi/components.d.ts +14 -0
  17. package/dist/openapi/components.d.ts.map +1 -0
  18. package/dist/openapi/tags.d.ts +14 -2
  19. package/dist/openapi/tags.d.ts.map +1 -1
  20. package/dist/registerRoutes.d.ts.map +1 -1
  21. package/dist/routes/actions.d.ts +5 -5
  22. package/dist/routes/agent-api-gateway.d.ts.map +1 -1
  23. package/dist/routes/agent-approval-gate.d.ts +27 -0
  24. package/dist/routes/agent-approval-gate.d.ts.map +1 -0
  25. package/dist/routes/agent-approvals.d.ts +599 -0
  26. package/dist/routes/agent-approvals.d.ts.map +1 -0
  27. package/dist/routes/agent-children.d.ts +318 -0
  28. package/dist/routes/agent-children.d.ts.map +1 -0
  29. package/dist/routes/agent-memory.d.ts +267 -0
  30. package/dist/routes/agent-memory.d.ts.map +1 -0
  31. package/dist/routes/agents.d.ts +999 -80
  32. package/dist/routes/agents.d.ts.map +1 -1
  33. package/dist/routes/ai-accounting.d.ts.map +1 -1
  34. package/dist/routes/artifact-frames.d.ts +3 -3
  35. package/dist/routes/artifact-frames.d.ts.map +1 -1
  36. package/dist/routes/artifacts.d.ts +790 -134
  37. package/dist/routes/artifacts.d.ts.map +1 -1
  38. package/dist/routes/auth.d.ts +116 -10
  39. package/dist/routes/auth.d.ts.map +1 -1
  40. package/dist/routes/connector-connection-runs.d.ts +50 -50
  41. package/dist/routes/connectors.d.ts +2 -2
  42. package/dist/routes/datasets.d.ts +20 -20
  43. package/dist/routes/events.d.ts +4 -4
  44. package/dist/routes/files.d.ts +14 -14
  45. package/dist/routes/files.d.ts.map +1 -1
  46. package/dist/routes/links.d.ts +2 -2
  47. package/dist/routes/logs.d.ts +5 -5
  48. package/dist/routes/model-calls.d.ts +155 -0
  49. package/dist/routes/model-calls.d.ts.map +1 -0
  50. package/dist/routes/model-generations.d.ts +400 -0
  51. package/dist/routes/model-generations.d.ts.map +1 -0
  52. package/dist/routes/models.d.ts +434 -1
  53. package/dist/routes/models.d.ts.map +1 -1
  54. package/dist/routes/objects.d.ts +71 -40
  55. package/dist/routes/objects.d.ts.map +1 -1
  56. package/dist/routes/observed-agent-threads.d.ts +682 -0
  57. package/dist/routes/observed-agent-threads.d.ts.map +1 -0
  58. package/dist/routes/ontology.d.ts +66 -62
  59. package/dist/routes/ontology.d.ts.map +1 -1
  60. package/dist/routes/pipelines.d.ts +24 -24
  61. package/dist/routes/projections.d.ts +55 -55
  62. package/dist/routes/rules.d.ts +2 -2
  63. package/dist/routes/share-grants.d.ts +9 -9
  64. package/dist/routes/syncs.d.ts +46 -46
  65. package/dist/routes/users.d.ts +117 -0
  66. package/dist/routes/users.d.ts.map +1 -0
  67. package/dist/routes/webhook-runs.d.ts +1 -1
  68. package/dist/routes/workflows.d.ts +118 -52
  69. package/dist/routes/workflows.d.ts.map +1 -1
  70. package/dist/routes/ws/agents.d.ts +7 -2
  71. package/dist/routes/ws/agents.d.ts.map +1 -1
  72. package/dist/routes/ws/events.d.ts +6 -6
  73. package/dist/routes/ws/logs.d.ts +14 -14
  74. package/dist/schemas/actions.d.ts +15 -15
  75. package/dist/schemas/activity.d.ts +48 -28
  76. package/dist/schemas/activity.d.ts.map +1 -1
  77. package/dist/schemas/agent-approvals.d.ts +1091 -0
  78. package/dist/schemas/agent-approvals.d.ts.map +1 -0
  79. package/dist/schemas/agent-memory.d.ts +250 -0
  80. package/dist/schemas/agent-memory.d.ts.map +1 -0
  81. package/dist/schemas/agents.d.ts +5442 -369
  82. package/dist/schemas/agents.d.ts.map +1 -1
  83. package/dist/schemas/ai-accounting.d.ts +1290 -411
  84. package/dist/schemas/ai-accounting.d.ts.map +1 -1
  85. package/dist/schemas/ai-limits.d.ts +10 -10
  86. package/dist/schemas/ai-usage.d.ts +12 -0
  87. package/dist/schemas/ai-usage.d.ts.map +1 -1
  88. package/dist/schemas/artifacts.d.ts +650 -98
  89. package/dist/schemas/artifacts.d.ts.map +1 -1
  90. package/dist/schemas/auth.d.ts +119 -46
  91. package/dist/schemas/auth.d.ts.map +1 -1
  92. package/dist/schemas/connectors.d.ts +22 -22
  93. package/dist/schemas/datasets.d.ts +98 -98
  94. package/dist/schemas/event-payloads.d.ts +6 -6
  95. package/dist/schemas/events.d.ts +26 -26
  96. package/dist/schemas/events.d.ts.map +1 -1
  97. package/dist/schemas/files.d.ts +24 -24
  98. package/dist/schemas/links.d.ts +2 -2
  99. package/dist/schemas/logs.d.ts +32 -32
  100. package/dist/schemas/models.d.ts +8889 -10
  101. package/dist/schemas/models.d.ts.map +1 -1
  102. package/dist/schemas/objects.d.ts +48 -12
  103. package/dist/schemas/objects.d.ts.map +1 -1
  104. package/dist/schemas/ontology.d.ts +127 -104
  105. package/dist/schemas/ontology.d.ts.map +1 -1
  106. package/dist/schemas/pipelines.d.ts +132 -132
  107. package/dist/schemas/projections.d.ts +314 -314
  108. package/dist/schemas/rules.d.ts +4 -4
  109. package/dist/schemas/share-grants.d.ts +30 -30
  110. package/dist/schemas/syncs.d.ts +49 -49
  111. package/dist/schemas/users.d.ts +72 -0
  112. package/dist/schemas/users.d.ts.map +1 -0
  113. package/dist/schemas/webhook-runs.d.ts +6 -6
  114. package/dist/schemas/workflows.d.ts +701 -186
  115. package/dist/schemas/workflows.d.ts.map +1 -1
  116. package/dist/server.d.ts +1 -0
  117. package/dist/server.d.ts.map +1 -1
  118. package/dist/utils/http.d.ts.map +1 -1
  119. package/package.json +7 -7
  120. package/src/artifacts/frame.ts +6 -1
  121. package/src/auth/browser-origin.ts +8 -3
  122. package/src/auth/experience.ts +1 -1
  123. package/src/auth/guard.ts +2 -2
  124. package/src/auth/public-routes.ts +6 -0
  125. package/src/auth/responses.ts +7 -6
  126. package/src/auth/scope.ts +32 -3
  127. package/src/models/display.ts +61 -16
  128. package/src/openapi/components.ts +54 -0
  129. package/src/openapi/tags.ts +12 -0
  130. package/src/registerRoutes.ts +14 -0
  131. package/src/routes/agent-api-gateway.ts +115 -91
  132. package/src/routes/agent-approval-gate.ts +213 -0
  133. package/src/routes/agent-approvals.ts +299 -0
  134. package/src/routes/agent-children.ts +209 -0
  135. package/src/routes/agent-memory.ts +210 -0
  136. package/src/routes/agents.ts +363 -142
  137. package/src/routes/ai-accounting.ts +4 -0
  138. package/src/routes/artifact-frames.ts +14 -8
  139. package/src/routes/artifacts.ts +297 -22
  140. package/src/routes/auth.ts +306 -13
  141. package/src/routes/files.ts +6 -7
  142. package/src/routes/model-calls.ts +120 -0
  143. package/src/routes/model-generations.ts +245 -0
  144. package/src/routes/models.ts +116 -9
  145. package/src/routes/objects.ts +55 -61
  146. package/src/routes/observed-agent-threads.ts +253 -0
  147. package/src/routes/ontology.ts +1 -0
  148. package/src/routes/users.ts +73 -0
  149. package/src/routes/workflows.ts +6 -9
  150. package/src/routes/ws/agents.ts +10 -5
  151. package/src/schemas/activity.ts +2 -0
  152. package/src/schemas/agent-approvals.ts +129 -0
  153. package/src/schemas/agent-memory.ts +96 -0
  154. package/src/schemas/agents.ts +239 -0
  155. package/src/schemas/ai-accounting.ts +40 -4
  156. package/src/schemas/ai-usage.ts +10 -0
  157. package/src/schemas/artifacts.ts +91 -3
  158. package/src/schemas/auth.ts +25 -0
  159. package/src/schemas/models.ts +197 -1
  160. package/src/schemas/objects.ts +181 -0
  161. package/src/schemas/ontology.ts +1 -0
  162. package/src/schemas/users.ts +24 -0
  163. package/src/schemas/workflows.ts +2 -0
  164. package/src/server.ts +9 -10
  165. package/src/utils/http.ts +2 -0
@@ -0,0 +1,299 @@
1
+ import type { AgentApprovalRecord, SixbHostView } from "@sixb/core"
2
+ import { agentApprovalCallers } from "@sixb/core/internal/agents"
3
+ import type { AgentStorage } from "@sixb/core/storage"
4
+ import type { Elysia } from "elysia"
5
+ import { requireRequestSixb } from "../auth/scope"
6
+ import { SIXB_SESSION_MUTATION_SECURITY_REQUIREMENT } from "../openapi/security"
7
+ import { OPENAPI_TAGS } from "../openapi/tags"
8
+ import {
9
+ AgentApprovalListQuerySchema,
10
+ AgentApprovalListResponseSchema,
11
+ AgentApprovalParamsSchema,
12
+ AgentApprovalSchema,
13
+ AgentPreferencesBodySchema,
14
+ AgentPreferencesSchema,
15
+ AgentThreadApprovalModeBodySchema,
16
+ DecideAgentApprovalBodySchema,
17
+ MyAgentApprovalListQuerySchema,
18
+ } from "../schemas/agent-approvals"
19
+ import {
20
+ AgentRequestErrorResponseSchema,
21
+ AgentThreadParamsSchema,
22
+ AgentThreadSchema,
23
+ DecideAgentApprovalResponseSchema,
24
+ } from "../schemas/agents"
25
+ import { ErrorResponseSchema } from "../schemas/common"
26
+ import { parseOptionalInt, toIsoString, unconfiguredStorageResponse } from "../utils/http"
27
+ import { handleAgentRouteError, serializeAgentRun, serializeThread } from "./agents"
28
+
29
+ const DECIDING =
30
+ "Only whoever asked for the turn decides: an approved call runs now, as the turn, with the rights their request carries, and the approval comes back with its outcome. A turn paused on its calls resumes once all of them are decided: `run` is the turn that continues it, and the Agent reads how each call ended. Once the call ran, the decision never fails: when the turn cannot resume, `resume` says why, and whether Sixb tries again, as it does once an AI limit resets. A new message sets the calls still waiting aside. None of these routes is reachable from the Agent's sandbox."
31
+
32
+ type SerializedApproval = ReturnType<typeof AgentApprovalSchema.parse>
33
+
34
+ /** Each with the sub-agent that made it, when its turn did not make it itself. */
35
+ async function serializeApprovals(
36
+ agents: AgentStorage,
37
+ approvals: readonly AgentApprovalRecord[]
38
+ ): Promise<SerializedApproval[]> {
39
+ const projectId = approvals[0]?.projectId
40
+ const callers = projectId ? await agentApprovalCallers(agents, projectId, approvals) : new Map()
41
+
42
+ return approvals.map((approval) =>
43
+ serializeApproval(approval, callers.get(approval.callerRunId)?.key)
44
+ )
45
+ }
46
+
47
+ function serializeApproval(approval: AgentApprovalRecord, callerKey?: string): SerializedApproval {
48
+ return AgentApprovalSchema.parse({
49
+ id: approval.id,
50
+ threadId: approval.threadId,
51
+ runId: approval.runId,
52
+ callerRunId: approval.callerRunId,
53
+ caller: callerKey === undefined ? undefined : { runId: approval.callerRunId, key: callerKey },
54
+ requestedBy: approval.requestedBy,
55
+ mode: approval.mode,
56
+ status: approval.status,
57
+ call: approval.call,
58
+ createdAt: toIsoString(approval.createdAt),
59
+ expiresAt: toIsoString(approval.expiresAt),
60
+ decidedAt: approval.decidedAt ? toIsoString(approval.decidedAt) : undefined,
61
+ decidedBy: approval.decidedBy,
62
+ outcome: approval.outcome,
63
+ reported: approval.reportedInMessageId !== undefined,
64
+ })
65
+ }
66
+
67
+ /** Approval modes and held calls. Session routes only, and never on the agent API gateway. */
68
+ export function registerAgentApprovalRoutes(app: Elysia, host: SixbHostView) {
69
+ const missingStorage = (set: { status?: number | string }) =>
70
+ unconfiguredStorageResponse(set, "Agent storage")
71
+
72
+ return app
73
+ .get(
74
+ "/api/agent/preferences",
75
+ async (context) => {
76
+ const { set } = context
77
+ try {
78
+ if (!host.storage.agents) return missingStorage(set)
79
+ return AgentPreferencesSchema.parse(
80
+ await requireRequestSixb(context).agent.preferences.get()
81
+ )
82
+ } catch (error) {
83
+ return handleAgentRouteError(error, set)
84
+ }
85
+ },
86
+ {
87
+ response: {
88
+ 200: AgentPreferencesSchema,
89
+ 404: AgentRequestErrorResponseSchema,
90
+ 501: ErrorResponseSchema,
91
+ },
92
+ detail: {
93
+ summary: "Get your Agent preferences",
94
+ tags: [OPENAPI_TAGS.agents.name],
95
+ operationId: "getAgentPreferences",
96
+ },
97
+ }
98
+ )
99
+ .put(
100
+ "/api/agent/preferences",
101
+ async (context) => {
102
+ const { body, set } = context
103
+ try {
104
+ if (!host.storage.agents) return missingStorage(set)
105
+ const parsed = AgentPreferencesBodySchema.parse(body)
106
+ return AgentPreferencesSchema.parse(
107
+ await requireRequestSixb(context).agent.preferences.update(parsed)
108
+ )
109
+ } catch (error) {
110
+ return handleAgentRouteError(error, set)
111
+ }
112
+ },
113
+ {
114
+ body: AgentPreferencesBodySchema,
115
+ response: {
116
+ 200: AgentPreferencesSchema,
117
+ 400: AgentRequestErrorResponseSchema,
118
+ 404: AgentRequestErrorResponseSchema,
119
+ 501: ErrorResponseSchema,
120
+ },
121
+ detail: {
122
+ summary: "Update your Agent preferences",
123
+ description:
124
+ "`approvalMode` is your default in the threads where you chose none: `manual` asks before every action and workflow, `accept-edits` runs the actions that only change Sixb, `auto` runs everything.",
125
+ tags: [OPENAPI_TAGS.agents.name],
126
+ operationId: "updateAgentPreferences",
127
+ security: SIXB_SESSION_MUTATION_SECURITY_REQUIREMENT,
128
+ },
129
+ }
130
+ )
131
+ .put(
132
+ "/api/agent-threads/:threadId/approval-mode",
133
+ async (context) => {
134
+ const { params, body, set } = context
135
+ const sixb = requireRequestSixb(context)
136
+ try {
137
+ if (!host.storage.agents) return missingStorage(set)
138
+ const parsed = AgentThreadApprovalModeBodySchema.parse(body)
139
+ const approvalMode = await sixb.agent.threads.setApprovalMode(
140
+ params.threadId,
141
+ parsed.approvalMode
142
+ )
143
+ const thread = await sixb.agent.threads.getById(params.threadId)
144
+ if (!thread) {
145
+ set.status = 404
146
+ return { error: "Agent thread not found" }
147
+ }
148
+
149
+ return { ...(await serializeThread(host, thread)), ...approvalMode }
150
+ } catch (error) {
151
+ return handleAgentRouteError(error, set)
152
+ }
153
+ },
154
+ {
155
+ params: AgentThreadParamsSchema,
156
+ body: AgentThreadApprovalModeBodySchema,
157
+ response: {
158
+ 200: AgentThreadSchema,
159
+ 400: AgentRequestErrorResponseSchema,
160
+ 404: AgentRequestErrorResponseSchema,
161
+ 409: AgentRequestErrorResponseSchema,
162
+ 501: ErrorResponseSchema,
163
+ },
164
+ detail: {
165
+ summary: "Choose your approval mode in an agent thread",
166
+ description:
167
+ "Applies to your next turns in the thread; other participants keep theirs. `null` follows your default again. A message can still pass its own `approvalMode`.",
168
+ tags: [OPENAPI_TAGS.agentThreads.name],
169
+ operationId: "setAgentThreadApprovalMode",
170
+ security: SIXB_SESSION_MUTATION_SECURITY_REQUIREMENT,
171
+ },
172
+ }
173
+ )
174
+ .get(
175
+ "/api/agent-threads/:threadId/approvals",
176
+ async (context) => {
177
+ const { params, query, set } = context
178
+ const sixb = requireRequestSixb(context)
179
+ try {
180
+ if (!host.storage.agents) return missingStorage(set)
181
+ if (!(await sixb.agent.threads.getById(params.threadId))) {
182
+ set.status = 404
183
+ return { error: "Agent thread not found" }
184
+ }
185
+
186
+ const parsed = AgentApprovalListQuerySchema.parse(query)
187
+ const result = await sixb.agent.approvals.list({
188
+ threadId: params.threadId,
189
+ ...(parsed.runId === undefined ? {} : { runId: parsed.runId }),
190
+ ...(parsed.status === undefined ? {} : { statuses: [parsed.status] }),
191
+ limit: parseOptionalInt(parsed.limit),
192
+ offset: parseOptionalInt(parsed.offset),
193
+ })
194
+ return AgentApprovalListResponseSchema.parse({
195
+ ...result,
196
+ approvals: await serializeApprovals(host.storage.agents, result.approvals),
197
+ })
198
+ } catch (error) {
199
+ return handleAgentRouteError(error, set)
200
+ }
201
+ },
202
+ {
203
+ params: AgentThreadParamsSchema,
204
+ query: AgentApprovalListQuerySchema,
205
+ response: {
206
+ 200: AgentApprovalListResponseSchema,
207
+ 400: ErrorResponseSchema,
208
+ 404: ErrorResponseSchema,
209
+ 501: ErrorResponseSchema,
210
+ },
211
+ detail: {
212
+ summary: "List an agent thread's held calls",
213
+ description: "Oldest first. Whoever reads the thread reads its approvals.",
214
+ tags: [OPENAPI_TAGS.agentThreads.name],
215
+ operationId: "listAgentThreadApprovals",
216
+ },
217
+ }
218
+ )
219
+ .post(
220
+ "/api/agent-threads/:threadId/approvals/:approvalId/decision",
221
+ async (context) => {
222
+ const { params, body, set } = context
223
+ const sixb = requireRequestSixb(context)
224
+ try {
225
+ if (!host.storage.agents) return missingStorage(set)
226
+ const approval = await sixb.agent.approvals.getById(params.approvalId)
227
+ if (!approval || approval.threadId !== params.threadId) {
228
+ set.status = 404
229
+ return { error: "Agent approval not found" }
230
+ }
231
+
232
+ const parsed = DecideAgentApprovalBodySchema.parse(body)
233
+ const decided = await sixb.agent.approvals.decide(approval.id, parsed)
234
+ const [serialized] = await serializeApprovals(host.storage.agents, [decided.approval])
235
+ return DecideAgentApprovalResponseSchema.parse({
236
+ approval: serialized,
237
+ ...(decided.run === undefined ? {} : { run: serializeAgentRun(decided.run) }),
238
+ ...(decided.resume === undefined ? {} : { resume: decided.resume }),
239
+ })
240
+ } catch (error) {
241
+ return handleAgentRouteError(error, set)
242
+ }
243
+ },
244
+ {
245
+ params: AgentApprovalParamsSchema,
246
+ body: DecideAgentApprovalBodySchema,
247
+ response: {
248
+ 200: DecideAgentApprovalResponseSchema,
249
+ 400: AgentRequestErrorResponseSchema,
250
+ 403: AgentRequestErrorResponseSchema,
251
+ 404: ErrorResponseSchema,
252
+ 409: AgentRequestErrorResponseSchema,
253
+ 501: ErrorResponseSchema,
254
+ },
255
+ detail: {
256
+ summary: "Approve or deny a held agent call",
257
+ description: DECIDING,
258
+ tags: [OPENAPI_TAGS.agentRuns.name],
259
+ operationId: "decideAgentApproval",
260
+ security: SIXB_SESSION_MUTATION_SECURITY_REQUIREMENT,
261
+ },
262
+ }
263
+ )
264
+ .get(
265
+ "/api/agent-approvals",
266
+ async (context) => {
267
+ const { query, set } = context
268
+ try {
269
+ if (!host.storage.agents) return missingStorage(set)
270
+ const parsed = MyAgentApprovalListQuerySchema.parse(query)
271
+ const result = await requireRequestSixb(context).agent.approvals.list({
272
+ ...(parsed.status === undefined ? {} : { statuses: [parsed.status] }),
273
+ limit: parseOptionalInt(parsed.limit),
274
+ offset: parseOptionalInt(parsed.offset),
275
+ })
276
+ return AgentApprovalListResponseSchema.parse({
277
+ ...result,
278
+ approvals: await serializeApprovals(host.storage.agents, result.approvals),
279
+ })
280
+ } catch (error) {
281
+ return handleAgentRouteError(error, set)
282
+ }
283
+ },
284
+ {
285
+ query: MyAgentApprovalListQuerySchema,
286
+ response: {
287
+ 200: AgentApprovalListResponseSchema,
288
+ 400: ErrorResponseSchema,
289
+ 501: ErrorResponseSchema,
290
+ },
291
+ detail: {
292
+ summary: "List the calls held for your decision",
293
+ description: "Your own, across threads, oldest first.",
294
+ tags: [OPENAPI_TAGS.agentRuns.name],
295
+ operationId: "listAgentApprovals",
296
+ },
297
+ }
298
+ )
299
+ }
@@ -0,0 +1,209 @@
1
+ import type { AgentChildRunView, AgentChildView, SixbHostView } from "@sixb/core"
2
+ import { agentRunStreamId } from "@sixb/core/internal/agents/streams"
3
+ import type { Elysia } from "elysia"
4
+ import { z } from "zod"
5
+ import { accessTokenSecurityRequirement } from "../auth/access-token-boundary"
6
+ import { requireRequestSixb } from "../auth/scope"
7
+ import {
8
+ createContextualFileContentResponse,
9
+ fileContentGetResponses,
10
+ fileContentHeadResponses,
11
+ handleFileContentQueryValidationError,
12
+ } from "../files/content"
13
+ import { OPENAPI_TAGS } from "../openapi/tags"
14
+ import {
15
+ AgentChildListQuerySchema,
16
+ AgentChildListResponseSchema,
17
+ AgentChildSchema,
18
+ AgentThreadParamsSchema,
19
+ } from "../schemas/agents"
20
+ import { ErrorResponseSchema } from "../schemas/common"
21
+ import { FileContentQuerySchema } from "../schemas/files"
22
+ import { toIsoString, unconfiguredStorageResponse } from "../utils/http"
23
+ import { handleAgentRouteError } from "./agents"
24
+
25
+ /**
26
+ * A file of one run of a sub-agent: one its parent handed it (`/handedFiles/<n>/fileRef`), or one
27
+ * the run returned from `out/` (`/files/<n>/fileRef`). What a tool showed it is a file of its
28
+ * thread's messages.
29
+ */
30
+ export const AgentChildFileContentQuerySchema = FileContentQuerySchema.extend({
31
+ run: z.string().min(1),
32
+ path: z
33
+ .string()
34
+ .min(1)
35
+ .regex(
36
+ /^\/(?:handedFiles|files)(?:\/|$)/,
37
+ "Sub-agent file content paths must start with /handedFiles/ or /files/"
38
+ ),
39
+ })
40
+
41
+ const VISIBILITY =
42
+ "A sub-agent is visible exactly when its conversation is: to the thread's owner and participants; observers read it through the observed routes. What it did is its thread's messages, at `GET /api/agent-threads/:threadId/messages` with its `threadId`."
43
+
44
+ /** A sub-agent as the lists return it. */
45
+ export function serializeAgentChild(
46
+ child: AgentChildView
47
+ ): ReturnType<typeof AgentChildSchema.parse> {
48
+ return AgentChildSchema.parse({
49
+ id: child.id,
50
+ threadId: child.threadId,
51
+ projectId: child.projectId,
52
+ spawnedBy: child.spawnedBy,
53
+ key: child.key,
54
+ task: child.task,
55
+ model: child.model,
56
+ tier: child.tier,
57
+ reasoning: child.reasoning,
58
+ handedFiles: child.handedFiles,
59
+ status: child.status,
60
+ finishReason: child.finishReason,
61
+ error: child.error,
62
+ awaiting: child.awaiting,
63
+ ended: child.ended,
64
+ activeRunId: child.activeRunId,
65
+ createdAt: toIsoString(child.createdAt),
66
+ completedAt: child.completedAt ? toIsoString(child.completedAt) : undefined,
67
+ usage: child.usage,
68
+ cost: child.cost,
69
+ runs: child.runs.map(serializeAgentChildRun),
70
+ })
71
+ }
72
+
73
+ function serializeAgentChildRun(run: AgentChildRunView) {
74
+ return {
75
+ id: run.id,
76
+ parentRunId: run.parentRunId,
77
+ status: run.status,
78
+ finishReason: run.finishReason,
79
+ error: run.error,
80
+ modelId: run.modelId,
81
+ attempt: run.attempt,
82
+ streamId: agentRunStreamId(run.id),
83
+ createdAt: toIsoString(run.createdAt),
84
+ startedAt: run.startedAt ? toIsoString(run.startedAt) : undefined,
85
+ completedAt: run.completedAt ? toIsoString(run.completedAt) : undefined,
86
+ result: run.result,
87
+ usage: run.usage,
88
+ cost: run.cost,
89
+ }
90
+ }
91
+
92
+ /** A file of a sub-agent's run, read through whoever may read the sub-agent. */
93
+ export function agentChildFileContentResponse(
94
+ host: SixbHostView,
95
+ context: {
96
+ readonly query: unknown
97
+ readonly request: Request
98
+ readonly set: { status?: number | string }
99
+ },
100
+ readChild: () => Promise<AgentChildView | null>,
101
+ options: { readonly head?: boolean } = {}
102
+ ) {
103
+ if (!host.storage.agents) {
104
+ return unconfiguredStorageResponse(context.set, "Agent storage")
105
+ }
106
+
107
+ return createContextualFileContentResponse({
108
+ blobStorage: host.blobStorage,
109
+ query: context.query,
110
+ querySchema: AgentChildFileContentQuerySchema,
111
+ request: context.request,
112
+ set: context.set,
113
+ head: options.head,
114
+ resolveRoot: async (query) => {
115
+ const child = await readChild()
116
+ const run = child?.runs.find((candidate) => candidate.id === query.run)
117
+ return child && run
118
+ ? { handedFiles: child.handedFiles, files: run.result?.files ?? [] }
119
+ : null
120
+ },
121
+ })
122
+ }
123
+
124
+ /**
125
+ * A conversation's sub-agents, and their files. What one did is its thread's: the thread routes
126
+ * read it, and `/api/agent-runs/:runId` its runs.
127
+ */
128
+ export function registerAgentChildRoutes(app: Elysia, host: SixbHostView) {
129
+ const readChild = (context: { readonly params: { readonly threadId: string } }) => () =>
130
+ requireRequestSixb(context).agent.threads.getChild(context.params.threadId)
131
+
132
+ return app
133
+ .get(
134
+ "/api/agent-threads/:threadId/children",
135
+ async (context) => {
136
+ const { params, set } = context
137
+ try {
138
+ if (!host.storage.agents) {
139
+ return unconfiguredStorageResponse(set, "Agent storage")
140
+ }
141
+
142
+ const query = AgentChildListQuerySchema.parse(context.query)
143
+ const result = await requireRequestSixb(context).agent.threads.listChildren(
144
+ params.threadId,
145
+ query.runId === undefined ? {} : { runId: query.runId }
146
+ )
147
+ if (!result) {
148
+ set.status = 404
149
+ return { error: "Agent thread not found" }
150
+ }
151
+
152
+ return AgentChildListResponseSchema.parse({
153
+ children: result.children.map(serializeAgentChild),
154
+ })
155
+ } catch (error) {
156
+ return handleAgentRouteError(error, set)
157
+ }
158
+ },
159
+ {
160
+ params: AgentThreadParamsSchema,
161
+ query: AgentChildListQuerySchema,
162
+ response: {
163
+ 200: AgentChildListResponseSchema,
164
+ 400: ErrorResponseSchema,
165
+ 404: ErrorResponseSchema,
166
+ 501: ErrorResponseSchema,
167
+ },
168
+ detail: {
169
+ summary: "List the sub-agents of an agent conversation",
170
+ description: `${VISIBILITY} \`runId\` keeps those one turn spawned. Each lists every run it took, the one at work by \`activeRunId\`.`,
171
+ tags: [OPENAPI_TAGS.agentThreads.name],
172
+ operationId: "listAgentThreadChildren",
173
+ },
174
+ }
175
+ )
176
+ .get(
177
+ "/api/agent-threads/:threadId/child-files/content",
178
+ (context) => agentChildFileContentResponse(host, context, readChild(context)),
179
+ {
180
+ params: AgentThreadParamsSchema,
181
+ query: AgentChildFileContentQuerySchema,
182
+ error: handleFileContentQueryValidationError,
183
+ detail: {
184
+ summary: "Get a file of a sub-agent",
185
+ description: `${VISIBILITY} \`threadId\` is the sub-agent's thread, \`run\` one of its runs, and \`path\` points into it: \`/handedFiles/0/fileRef\`, or \`/files/0/fileRef\` for what the run returned.`,
186
+ tags: [OPENAPI_TAGS.agentThreads.name],
187
+ operationId: "getAgentChildFileContent",
188
+ security: accessTokenSecurityRequirement("getAgentChildFileContent"),
189
+ responses: fileContentGetResponses({ optionalStorage: true }),
190
+ },
191
+ }
192
+ )
193
+ .head(
194
+ "/api/agent-threads/:threadId/child-files/content",
195
+ (context) => agentChildFileContentResponse(host, context, readChild(context), { head: true }),
196
+ {
197
+ params: AgentThreadParamsSchema,
198
+ query: AgentChildFileContentQuerySchema,
199
+ error: handleFileContentQueryValidationError,
200
+ detail: {
201
+ summary: "Head a file of a sub-agent",
202
+ tags: [OPENAPI_TAGS.agentThreads.name],
203
+ operationId: "headAgentChildFileContent",
204
+ security: accessTokenSecurityRequirement("headAgentChildFileContent"),
205
+ responses: fileContentHeadResponses({ optionalStorage: true }),
206
+ },
207
+ }
208
+ )
209
+ }