shapewall 0.3.3 → 0.6.0

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 (98) hide show
  1. package/CHANGELOG.md +249 -0
  2. package/README.md +49 -3
  3. package/dist/agent/package-lock.json +2 -2
  4. package/dist/client/assets/BoardChat-DdwBcb2N.js +27 -0
  5. package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-DpUcnU6S.js} +1 -1
  6. package/dist/client/assets/ChecksPanel-CngYV4yz.js +1 -0
  7. package/dist/client/assets/History-CD0saQA5.js +1 -0
  8. package/dist/client/assets/LocalSettings-MZy2baig.js +1 -0
  9. package/dist/client/assets/{Management-NVFDtSZB.js → Management-CSvZ-SHO.js} +1 -1
  10. package/dist/client/assets/QuickConnect-foLh2QUm.js +1 -0
  11. package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-DPWDftoL.js} +2 -2
  12. package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-CtiXpTRD.js} +1 -1
  13. package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-CteRBtXC.js} +1 -1
  14. package/dist/client/assets/index-Cxz1UVcV.css +2 -0
  15. package/dist/client/assets/index-uUZVBYUS.js +37 -0
  16. package/dist/client/assets/play-BjRNIGSf.js +1 -0
  17. package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-r_tZiFfB.js} +1 -1
  18. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  19. package/dist/client/assets/ui-zQpn-PdL.js +41 -0
  20. package/dist/client/build-info.json +1 -1
  21. package/dist/client/index.html +3 -3
  22. package/dist/client/sw.js +2 -2
  23. package/dist/console/assets/{LocalAccountsApp-VOCZg8dg.js → LocalAccountsApp-DIdy1KnN.js} +1 -1
  24. package/dist/console/assets/{LocalConsole-CMwAW-mF.js → LocalConsole-DfcQztF-.js} +1 -1
  25. package/dist/console/assets/{app-update-dialog-Cw6UDqNP.js → app-update-dialog-ttl9lF5A.js} +1 -1
  26. package/dist/console/assets/console-OqAjD0kV.js +55 -0
  27. package/dist/console/assets/console-kvjrAArQ.css +2 -0
  28. package/dist/console/build-info.json +1 -1
  29. package/dist/console/console.html +2 -2
  30. package/docs/agent-hardening.md +192 -0
  31. package/docs/agent-recipes.md +23 -0
  32. package/docs/agent-workflow.md +5 -0
  33. package/docs/agents.md +14 -6
  34. package/docs/hosted.md +804 -11
  35. package/docs/where-to-run.md +37 -2
  36. package/package.json +1 -1
  37. package/src/agent/backends/acp.js +528 -25
  38. package/src/agent/branch-mode.js +17 -3
  39. package/src/agent/card-hash.js +65 -0
  40. package/src/agent/context.js +41 -0
  41. package/src/agent/exec-paths.js +105 -0
  42. package/src/agent/routes.js +2 -2
  43. package/src/agent/run.js +11 -1
  44. package/src/agent/starter/cli.js +6 -1
  45. package/src/agent/turn-changes.js +70 -8
  46. package/src/cli/args.js +13 -0
  47. package/src/cli/commands.js +20 -5
  48. package/src/cli/help.js +36 -1
  49. package/src/hosted/admin.js +7 -0
  50. package/src/hosted/agent-approvals.js +28 -3
  51. package/src/hosted/agent-link.js +1032 -0
  52. package/src/hosted/agent-policy.js +10 -3
  53. package/src/hosted/agent-presence.js +63 -22
  54. package/src/hosted/agent-routes.js +135 -0
  55. package/src/hosted/agents.js +1199 -0
  56. package/src/hosted/app.js +89 -5
  57. package/src/hosted/board-routes.js +127 -3
  58. package/src/hosted/chat-frames.js +256 -0
  59. package/src/hosted/chat-job.js +204 -0
  60. package/src/hosted/chat-permissions.js +191 -0
  61. package/src/hosted/chat-routes.js +1009 -0
  62. package/src/hosted/chat-store.js +460 -0
  63. package/src/hosted/comment-files.js +8 -1
  64. package/src/hosted/comments.js +1 -1
  65. package/src/hosted/console-routes.js +11 -0
  66. package/src/hosted/db.js +165 -0
  67. package/src/hosted/device-routes.js +64 -8
  68. package/src/hosted/device.js +35 -4
  69. package/src/hosted/events.js +3 -3
  70. package/src/hosted/membership.js +9 -1
  71. package/src/hosted/pages.js +2 -0
  72. package/src/hosted/permissions.js +38 -0
  73. package/src/hosted/presence.js +17 -0
  74. package/src/hosted/projects.js +29 -2
  75. package/src/hosted/ratelimit.js +8 -0
  76. package/src/hosted/tenancy.js +18 -0
  77. package/src/hosted/token-api.js +118 -19
  78. package/src/hosted/token-events.js +5 -3
  79. package/src/hosted/tokens.js +21 -5
  80. package/src/hosted/turn-hub.js +152 -0
  81. package/src/remote/agent-connect.js +433 -0
  82. package/src/remote/agent-fix.js +611 -0
  83. package/src/remote/agent-job.js +216 -0
  84. package/src/remote/agent-link.js +904 -0
  85. package/src/remote/agent-policy-file.js +242 -0
  86. package/src/remote/credentials.js +35 -1
  87. package/src/remote/login.js +12 -2
  88. package/dist/client/assets/BoardChat-DxehB761.js +0 -27
  89. package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
  90. package/dist/client/assets/History-C9N32kCv.js +0 -1
  91. package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
  92. package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
  93. package/dist/client/assets/index-CsqLdqGx.css +0 -2
  94. package/dist/client/assets/index-DnZarJ3U.js +0 -37
  95. package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
  96. package/dist/client/assets/ui-DI-FGWWK.js +0 -41
  97. package/dist/console/assets/console-DgfWmUEx.js +0 -55
  98. package/dist/console/assets/console-Lis0vvdL.css +0 -2
package/src/hosted/app.js CHANGED
@@ -31,7 +31,7 @@ import { listTokens, mountAdmin } from './admin.js'
31
31
  import { createDeviceLogins } from './device.js'
32
32
  import { cleanEmail } from './mail.js'
33
33
  import { mountShareAdmin, mountSharePublic } from './shares.js'
34
- import { createCommentStore } from './comments.js'
34
+ import { REPLY_AUTHOR, createCommentStore } from './comments.js'
35
35
  import { createUsercontent } from './usercontent.js'
36
36
  import { mountRebind, prepareOrigins, previousHostGate } from './rebind.js'
37
37
  import { mountPublicAdmin } from './public.js'
@@ -61,6 +61,11 @@ import { createBoardContext } from './board-context.js'
61
61
  import { mountBoardRoutes } from './board-routes.js'
62
62
  import { mountTokenApi } from './token-api.js'
63
63
  import { createAgentPresence } from './agent-presence.js'
64
+ import { COMMENT_ROUTING, createAgentStore } from './agents.js'
65
+ import { mountAgentRoutes } from './agent-routes.js'
66
+ import { createAgentLinks, createChatService } from './agent-link.js'
67
+ import { createChatStore } from './chat-store.js'
68
+ import { createTurnHub } from './turn-hub.js'
64
69
  import { mountPages } from './pages.js'
65
70
 
66
71
  export { changeEventType, publicBoardView, TOKEN_SCOPES, INVITE_DAYS }
@@ -132,16 +137,49 @@ export function createHostedApp({
132
137
  deviceLogins ||= createDeviceLogins({ db, now })
133
138
  const ownsEvents = !eventBus
134
139
  const events = eventBus || createEventBus()
135
- // Which projects have an agent listening right now (in memory only).
140
+ // Which agents are listening right now (in memory only).
136
141
  const agentPresence = createAgentPresence({ now })
137
142
  const streams = new Set()
143
+ // Connected agents (`shapewall agent connect`): the chat turns in flight
144
+ // and the open links, in memory (src/hosted/turn-hub.js, agent-link.js).
145
+ const turnHub = createTurnHub({ now: () => now().getTime() })
146
+ const links = createAgentLinks({ hub: turnHub })
147
+ const chatFor = (t) => createChatStore(t, { now })
138
148
  const policyFor = (t) =>
139
149
  createAgentPolicy(t, { now, handleFor: (user) => q.get('SELECT handle FROM users WHERE id = :id', { id: user })?.handle || null })
150
+ const handleFor = (user) => q.get('SELECT handle FROM users WHERE id = :id', { id: user })?.handle || null
151
+ // The agents of a workspace (src/hosted/agents.js), one store per tenant
152
+ // handle: a handle lives for one request, so what the store read once in
153
+ // a request is not read again.
154
+ const agentStores = new WeakMap()
155
+ const agentsFor = (t) => {
156
+ if (!agentStores.has(t)) agentStores.set(t, createAgentStore(t, { now, presence: agentPresence, handleFor, links }))
157
+ return agentStores.get(t)
158
+ }
140
159
  const dispatchView = (t, project, board, comment) => {
141
160
  const row = createCommentStore(t, project, board).get(comment.id)
161
+ const agents = agentsFor(t)
142
162
  // dispatchHash: what "Send to agent" must send back, so a vouch covers
143
163
  // the text its sender saw (src/hosted/board-routes.js).
144
- return { ...comment, ...policyFor(t).state(project, board, row), dispatchHash: dispatchHash(row) }
164
+ return {
165
+ ...comment,
166
+ ...policyFor(t).state(project, board, row),
167
+ dispatchHash: dispatchHash(row),
168
+ // The agent the comment was sent to (null: any agent), and which agent
169
+ // wrote each agent reply, for its face on the thread. Agent ids only.
170
+ agentId: agents.addressOf(project, row),
171
+ replies: comment.replies.map((reply) => {
172
+ const agentId = agents.idForToken(project, reply[REPLY_AUTHOR]?.token)
173
+ return agentId ? { ...reply, agentId } : reply
174
+ }),
175
+ // What decides whether a token may take it (never serialized).
176
+ [COMMENT_ROUTING]: {
177
+ agent_id: row.agent_id || null,
178
+ dispatch_by: row.dispatch_by || null,
179
+ board_id: row.board_id,
180
+ number: row.number,
181
+ },
182
+ }
145
183
  }
146
184
  const q = accounts(db)
147
185
  const iso = (offset = 0) => new Date(now().getTime() + offset).toISOString()
@@ -174,6 +212,10 @@ export function createHostedApp({
174
212
  const SESSION_COOKIE = sessionCookieName(secure)
175
213
  const CEREMONY_COOKIE = secure ? '__Host-sw_ceremony' : 'sw_ceremony'
176
214
 
215
+ // What ends a chat turn from the server's side (the machine went away, a
216
+ // revoked agent, a restart).
217
+ const chat = createChatService({ db, hub: turnHub, links, events, chatFor, now })
218
+
177
219
  const app = express()
178
220
  app.disable('x-powered-by')
179
221
  app.use(publishMutations({ events, streams }))
@@ -229,7 +271,13 @@ export function createHostedApp({
229
271
  // While moving: which origin a request is for; the old one serves only the move.
230
272
  app.use(previousHostGate(sites))
231
273
 
232
- const { publicUser, createWorkspace, acceptInvite, revokeGrantsOf, ownerCount } = createMembership({ db, quotas, iso, auditOf })
274
+ const { publicUser, createWorkspace, acceptInvite, revokeGrantsOf, ownerCount } = createMembership({
275
+ db,
276
+ quotas,
277
+ iso,
278
+ auditOf,
279
+ agentsFor,
280
+ })
233
281
 
234
282
  // ---- Health ----
235
283
  app.get('/api/health', (req, res) => res.json({ ok: true }))
@@ -333,7 +381,7 @@ export function createHostedApp({
333
381
  consoleApi.use(guardWrites)
334
382
  consoleApi.use(express.json({ limit: '64kb' }))
335
383
 
336
- const createApiToken = createApiTokens({ iso, auditOf })
384
+ const createApiToken = createApiTokens({ iso, auditOf, agentsFor })
337
385
  const consoleDeps = {
338
386
  db,
339
387
  dataDir,
@@ -361,6 +409,7 @@ export function createHostedApp({
361
409
  revokeGrantsOf,
362
410
  ownerCount,
363
411
  createApiToken,
412
+ agentsFor,
364
413
  }
365
414
  mountInviteLinks(consoleApi, consoleDeps)
366
415
  // Share link preview and opening: no session, the link is the secret.
@@ -371,6 +420,7 @@ export function createHostedApp({
371
420
  consoleApi.use(needSession)
372
421
  consoleApi.use(limit('session', (req) => req.user.id))
373
422
  mountConsoleRoutes(consoleApi, consoleDeps)
423
+ mountAgentRoutes(consoleApi, consoleDeps)
374
424
  mountAdmin(consoleApi, deps)
375
425
  mountShareAdmin(consoleApi, deps)
376
426
  mountPublicAdmin(consoleApi, deps)
@@ -394,12 +444,17 @@ export function createHostedApp({
394
444
  auditOf,
395
445
  clientIp,
396
446
  policyFor,
447
+ agentsFor,
397
448
  dispatchView,
398
449
  boardContext,
399
450
  cleaner,
400
451
  quotas,
401
452
  workspaceQuota,
402
453
  deps,
454
+ chatFor,
455
+ hub: turnHub,
456
+ links,
457
+ chat,
403
458
  })
404
459
 
405
460
  mountDeviceApi(app, consoleDeps)
@@ -423,10 +478,15 @@ export function createHostedApp({
423
478
  auditOf,
424
479
  clientIp,
425
480
  policyFor,
481
+ agentsFor,
426
482
  boardContext,
427
483
  dispatchView,
428
484
  needFresh,
429
485
  approvalApi,
486
+ chatFor,
487
+ hub: turnHub,
488
+ links,
489
+ chat,
430
490
  })
431
491
  // The token API first: it never falls through to the cookie-based console API.
432
492
  mountMcpHttp(app, { tokenAuth, origin: publicOrigin, dataDir, db })
@@ -486,6 +546,25 @@ export function createHostedApp({
486
546
  if (!guestOnly) sweep()
487
547
  const sweepTimer = !guestOnly && sweepEveryMs ? setInterval(sweep, sweepEveryMs) : null
488
548
  sweepTimer?.unref()
549
+ // No turn survives a restart: what the database still calls running ends here.
550
+ if (!guestOnly) {
551
+ try {
552
+ chat.sweepStale()
553
+ } catch (error) {
554
+ log(`turn sweep at start: ${error.message}`)
555
+ }
556
+ }
557
+ // Chat turns whose machine went away end as interrupted (unref'd too).
558
+ const turnTimer = guestOnly
559
+ ? null
560
+ : setInterval(() => {
561
+ try {
562
+ chat.sweep()
563
+ } catch (error) {
564
+ log(`turn sweep: ${error.message}`)
565
+ }
566
+ }, 5000)
567
+ turnTimer?.unref()
489
568
  const ownsPresence = !presenceHub
490
569
  const hub = presenceHub || createPresenceHub({ events })
491
570
  // A WebSocket upgrade never passes through Express, so its address is
@@ -508,6 +587,8 @@ export function createHostedApp({
508
587
  app.locals.presence = { attach: presence.attach, close: presence.close, hub }
509
588
  app.locals.events = events
510
589
  app.locals.agentPresence = agentPresence
590
+ app.locals.agentsFor = agentsFor
591
+ app.locals.chat = { hub: turnHub, links, service: chat, storeFor: chatFor }
511
592
  app.locals.sweep = sweep
512
593
  app.locals.close = async () => {
513
594
  presence.close()
@@ -515,6 +596,9 @@ export function createHostedApp({
515
596
  if (ownsEvents) events.close()
516
597
  for (const check of [...streams]) check(true)
517
598
  if (sweepTimer) clearInterval(sweepTimer)
599
+ if (turnTimer) clearInterval(turnTimer)
600
+ chat.close()
601
+ links.closeAll()
518
602
  await cleaner.close()
519
603
  }
520
604
  return app
@@ -13,6 +13,7 @@ import { avatarUrl } from '../accounts/avatar.js'
13
13
  import { checksView, readReport } from '../checks/store.js'
14
14
  import { agentPolicy } from './agent-policy.js'
15
15
  import { hostedBoardView, sendPng } from './board-context.js'
16
+ import { mountChatRoutes } from './chat-routes.js'
16
17
  import { guestView, rowToComment } from './comments.js'
17
18
  import { transaction } from './db.js'
18
19
  import { publicView } from './guest-view.js'
@@ -47,6 +48,7 @@ export function mountBoardRoutes(
47
48
  auditOf,
48
49
  clientIp,
49
50
  policyFor,
51
+ agentsFor,
50
52
  dispatchView,
51
53
  boardContext,
52
54
  // Cleans comment images off the event loop (src/hosted/cleaner.js).
@@ -56,6 +58,11 @@ export function mountBoardRoutes(
56
58
  workspaceQuota = undefined,
57
59
  // What readGuest needs (the shared deps of src/hosted/app.js).
58
60
  deps,
61
+ // Chat with connected agents (src/hosted/chat-routes.js): members only.
62
+ chatFor = null,
63
+ hub = null,
64
+ links = null,
65
+ chat = null,
59
66
  },
60
67
  ) {
61
68
  // ---- Usercontent: live HTML through signed URLs ----
@@ -76,7 +83,8 @@ export function mountBoardRoutes(
76
83
  // New comments and replies may carry images (base64, 4 of 5 MB): their
77
84
  // body is read after the session and role checks, with its own limit
78
85
  // (mediaBody); every other route keeps 64 kB.
79
- const MEDIA_POST_RE = /^\/boards\/[^/]+\/comments(?:\/[^/]+\/replies)?\/?$/
86
+ // A chat message to a connected agent has its own limit too (chat-routes.js).
87
+ const MEDIA_POST_RE = /^\/(?:boards\/[^/]+\/comments(?:\/[^/]+\/replies)?|agent\/boards\/[^/]+\/threads\/[^/]+\/messages)\/?$/
80
88
  const skipMedia = (parser) => (req, res, next) =>
81
89
  req.method === 'POST' && MEDIA_POST_RE.test(req.path) ? next() : parser(req, res, next)
82
90
  boardApi.use(skipMedia(express.json({ limit: '64kb' })))
@@ -110,11 +118,45 @@ export function mountBoardRoutes(
110
118
  }),
111
119
  )
112
120
 
121
+ // The project's agents as this person may see and use them, for the
122
+ // board's Agent panel and "Send to agent": names, faces, states, what each
123
+ // holds on this board, and whether this person may send it work (with the
124
+ // reason when not). Members and viewers only: this router is never
125
+ // mounted for a share link's guests or a public project's visitors. No
126
+ // token ids, prefixes or scopes, and no account ids.
127
+ boardApi.get(
128
+ '/boards/:bid/agents',
129
+ handle((req, res) => {
130
+ const ctx = boardContext(req.t, req.project, req.params.bid)
131
+ // Reading the list is also where an agent that is gone lets go of its
132
+ // work, and where a token from an older build is first seen.
133
+ const audit = (action, target, detail) => auditOf(req, action, target, detail)
134
+ res.json(
135
+ transaction(db, () =>
136
+ agentsFor(req.t).boardList(req.project.id, { userId: req.user.id, role: req.role }, { boardId: ctx.board.id, audit }),
137
+ ),
138
+ )
139
+ }),
140
+ )
141
+ const actorOf = (req) => ({
142
+ userId: req.user.id,
143
+ role: req.role,
144
+ audit: (action, target, detail) => auditOf(req, action, target, detail),
145
+ })
146
+
147
+ // Sends a comment to an agent. `agentId` names one agent of the project
148
+ // (the sender must be in its audience), null means any agent, and without
149
+ // it the project's default agent is used when the sender may use it (any
150
+ // agent otherwise). An admin's approval of a run someone else asked for
151
+ // keeps where that comment was going.
113
152
  boardApi.post(
114
153
  '/boards/:bid/comments/:cid/send-to-agent',
115
154
  handle((req, res) => {
116
155
  const ctx = boardContext(req.t, req.project, req.params.bid)
117
156
  const approve = req.body?.approve === true
157
+ const named = Object.hasOwn(req.body || {}, 'agentId')
158
+ if (named && req.body.agentId !== null && typeof req.body.agentId !== 'string')
159
+ throw new HttpError(400, 'invalid_agent', 'agentId: an agent id, or null for any agent.')
118
160
  // The vouch covers the text its sender saw: the body carries the
119
161
  // comment's dispatchHash (from the board API), compared with the row
120
162
  // in the transaction that writes the vouch. Edited meanwhile: 409
@@ -126,14 +168,75 @@ export function mountBoardRoutes(
126
168
  if (!roleAtLeast(req.role, 'admin')) throw new HttpError(403, 'forbidden', 'Only trusted admins approve runs.')
127
169
  freshOrThrow(req)
128
170
  }
171
+ const agents = agentsFor(req.t)
172
+ const going = agents.addressOf(req.project.id, current)
173
+ const wanted = named ? req.body.agentId : approve && current.dispatch_hash ? going : undefined
174
+ // Work an agent already took stays with it, and so does the approval
175
+ // it was taken under: sending it again changes nothing (not who
176
+ // vouched for it, not where it goes), and sending it elsewhere is
177
+ // refused. Without a named agent (an older board) it is "again".
178
+ if (['queued', 'working'].includes(current.agent_status)) {
179
+ if (!roleAtLeast(req.role, 'member') || !agents.trusted(req.project.id, ctx.board.id, req.user.id))
180
+ throw new HttpError(403, 'untrusted_member', 'Only a trusted member may send work to an agent.')
181
+ if (named && wanted !== going) throw new HttpError(409, 'agent_working', 'An agent is already working on this comment.')
182
+ return current
183
+ }
129
184
  policyFor(req.t).vouch(req.project.id, ctx.board.id, current, req.user.id, { role: req.role, approve, expect })
130
- auditOf(req, 'comment_vouched', `${ctx.board.id}#${current.number}`, { project: req.project.id, approve })
185
+ // After the vouch (which refuses people the agent policy does not
186
+ // trust): the audience of the agent it is sent to, checked for the
187
+ // sender, and for the admin who approves someone else's run.
188
+ const agent = agents.address(req.project.id, ctx.board.id, current, { userId: req.user.id, role: req.role }, wanted)
189
+ auditOf(req, 'comment_vouched', `${ctx.board.id}#${current.number}`, { project: req.project.id, approve, agent })
131
190
  return current
132
191
  })
133
192
  res.json({ comment: dispatchView(req.t, req.project.id, ctx.board.id, rowToComment(ctx.comments.get(row.number))) })
134
193
  }),
135
194
  )
136
195
 
196
+ // "Let any agent take it": a comment that waits for one agent (it is
197
+ // offline, say) goes to whichever agent takes it first. For the people who
198
+ // may send comments to an agent here; not once an agent has taken it.
199
+ boardApi.post(
200
+ '/boards/:bid/comments/:cid/release-agent',
201
+ handle((req, res) => {
202
+ const ctx = boardContext(req.t, req.project, req.params.bid)
203
+ const agents = agentsFor(req.t)
204
+ transaction(db, () => {
205
+ const current = ctx.comments.get(req.params.cid)
206
+ if (!roleAtLeast(req.role, 'member') || !agents.trusted(req.project.id, ctx.board.id, req.user.id))
207
+ throw new HttpError(403, 'untrusted_member', 'Only a trusted member may send work to an agent.')
208
+ if (['queued', 'working'].includes(current.agent_status))
209
+ throw new HttpError(409, 'agent_working', 'An agent is already working on this comment.')
210
+ agents.release(actorOf(req), req.project.id, ctx.board.id, current)
211
+ })
212
+ res.json({ comment: dispatchView(req.t, req.project.id, ctx.board.id, rowToComment(ctx.comments.get(req.params.cid))) })
213
+ }),
214
+ )
215
+
216
+ // Chat with the project's connected agents: on the members' API only.
217
+ // A share link's guests and a public project's visitors have no such
218
+ // routes at all (their routers below never mount them).
219
+ const chatApi =
220
+ chatFor && hub && links && chat
221
+ ? mountChatRoutes(boardApi, {
222
+ db,
223
+ handle,
224
+ auditOf,
225
+ agentsFor,
226
+ chatFor,
227
+ hub,
228
+ links,
229
+ chat,
230
+ boardContext,
231
+ rateLimiter,
232
+ quotas,
233
+ workspaceQuota,
234
+ policyFor,
235
+ freshOrThrow,
236
+ now,
237
+ })
238
+ : null
239
+
137
240
  const shareApi = express.Router({ mergeParams: true })
138
241
  shareApi.use((req, res, next) => {
139
242
  res.setHeader('Cache-Control', 'no-store')
@@ -302,6 +405,16 @@ export function mountBoardRoutes(
302
405
  app.use('/s/:sid/api', shareApi)
303
406
  app.use('/p/:pubid/api', publicApi)
304
407
 
408
+ function hostedAgentInfo(req) {
409
+ try {
410
+ const found = chatApi.chatAgents(req, null)
411
+ if (!found.agents.length) return {}
412
+ return { agent: chatApi.agentInfo(chatApi.defaultOf(found)) }
413
+ } catch {
414
+ return {}
415
+ }
416
+ }
417
+
305
418
  function boardRoutes(router) {
306
419
  router.get('/info', (req, res) =>
307
420
  res.json({
@@ -317,6 +430,10 @@ export function mountBoardRoutes(
317
430
  consoleUrl: `/w/${req.t.workspaceId}`,
318
431
  // The board header's way back to the project's page in the console.
319
432
  project: { id: req.project.id, name: req.project.name, url: `/w/${req.t.workspaceId}/projects/${req.project.id}` },
433
+ // Chat with a connected agent: for members and up, once an agent
434
+ // that chats is connected to the project (online or not). Never for
435
+ // a share link's guest or a public visitor (their /info is their own).
436
+ ...(router === boardApi && chatApi && roleAtLeast(req.role, 'member') ? hostedAgentInfo(req) : {}),
320
437
  }),
321
438
  )
322
439
 
@@ -436,7 +553,14 @@ export function mountBoardRoutes(
436
553
  const comment = transaction(db, () => {
437
554
  checkStorageQuota(req.t, imageBytes(media), quotaOf(req))
438
555
  const made = ctx.comments.create(ctx.config, ctx.board, req.body, authorOf(req), now(), media)
439
- if (!req.guest) policyFor(req.t).autoVouch(req.project.id, ctx.board.id, ctx.comments.get(made.id), req.user.id, req.role)
556
+ if (!req.guest) {
557
+ policyFor(req.t).autoVouch(req.project.id, ctx.board.id, ctx.comments.get(made.id), req.user.id, req.role)
558
+ // Vouched for as it was written: it goes to the project's default
559
+ // agent when its author may use that agent, to any agent otherwise.
560
+ const vouched = ctx.comments.get(made.id)
561
+ if (vouched.dispatch_hash)
562
+ agentsFor(req.t).address(req.project.id, ctx.board.id, vouched, { userId: req.user.id, role: req.role }, undefined)
563
+ }
440
564
  if (req.guest) auditOf(req, 'guest_commented', `${ctx.board.id}#${made.id}`, { project: req.project.id, guest: req.guest.name })
441
565
  return made
442
566
  })
@@ -0,0 +1,256 @@
1
+ // What a connected agent's machine may send the server about a chat turn
2
+ // (src/hosted/agent-link.js), cleaned and bounded before anything is shown
3
+ // or stored. The machine is not trusted to keep to the shapes: a stolen
4
+ // agent token can post here too. Everything is copied field by field into
5
+ // new objects with known keys, string lengths and counts capped, so the
6
+ // board renders only what its own components expect. Pure: no database, no
7
+ // request.
8
+
9
+ export const FRAME_LIMITS = {
10
+ // One POST of events.
11
+ batchBytes: 256 * 1024,
12
+ batchEvents: 100,
13
+ // One card (a tool step, the plan, a note).
14
+ cardBytes: 64 * 1024,
15
+ cards: 200,
16
+ text: 100_000,
17
+ reasoning: 20_000,
18
+ // One streamed piece of text.
19
+ chunk: 20_000,
20
+ // The whole job the machine fetches for a turn.
21
+ jobBytes: 2 * 1024 * 1024,
22
+ }
23
+
24
+ const str = (value, max) => (typeof value === 'string' ? value.slice(0, max) : '')
25
+ const optional = (value, max) => (typeof value === 'string' && value ? value.slice(0, max) : null)
26
+ const count = (value) => (Number.isFinite(Number(value)) && Number(value) >= 0 ? Math.min(Math.round(Number(value)), 1e12) : null)
27
+
28
+ // The run summary of a fix (src/remote/agent-fix.js): the branch, whether it
29
+ // was pushed, the pull request, and the files with their line counts. Never
30
+ // a diff: the cards showed those.
31
+ const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*(?:\/[A-Za-z0-9][A-Za-z0-9_-]*)*$/
32
+ const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/
33
+ export function cleanSummary(summary) {
34
+ if (!summary || typeof summary !== 'object' || summary.kind !== 'remote-branch') return null
35
+ const branch = summary.branch && typeof summary.branch === 'object' ? summary.branch : {}
36
+ const name = typeof branch.name === 'string' && branch.name.length <= 120 && BRANCH_RE.test(branch.name) ? branch.name : null
37
+ if (!name) return null
38
+ const lines = (value) => (Number.isSafeInteger(value) && value >= 0 ? Math.min(value, 1e7) : null)
39
+ const files = (Array.isArray(summary.files) ? summary.files : []).slice(0, 50).map((file) => ({
40
+ path: str(file?.path, 300),
41
+ status: ['added', 'modified'].includes(file?.status) ? file.status : 'modified',
42
+ added: lines(file?.added),
43
+ removed: lines(file?.removed),
44
+ diff: null,
45
+ }))
46
+ // A pull request: only a URL shaped like one (https://host/owner/repo/pull/7).
47
+ // It is a link only on github.com; on any other host it is shown as text,
48
+ // since this server cannot know which host the project's GitHub is on.
49
+ let pr = null
50
+ try {
51
+ const url = new URL(String(summary.pr?.url || ''))
52
+ if (
53
+ url.protocol === 'https:' &&
54
+ url.href.length <= 300 &&
55
+ !url.username &&
56
+ !url.password &&
57
+ !url.search &&
58
+ !url.hash &&
59
+ /^\/[\w.-]+\/[\w.-]+\/pull\/\d+$/.test(url.pathname)
60
+ )
61
+ pr = {
62
+ url: url.href,
63
+ number: Number(url.pathname.split('/').at(-1)),
64
+ link: url.hostname === 'github.com',
65
+ }
66
+ } catch {
67
+ pr = null
68
+ }
69
+ return {
70
+ kind: 'remote-branch',
71
+ files,
72
+ added: files.reduce((sum, file) => sum + (file.added || 0), 0),
73
+ removed: files.reduce((sum, file) => sum + (file.removed || 0), 0),
74
+ more: lines(summary.more) || 0,
75
+ branch: {
76
+ name,
77
+ commit: SHA_RE.test(String(branch.commit || '')) ? branch.commit : null,
78
+ baseName:
79
+ typeof branch.baseName === 'string' && branch.baseName.length <= 120 && /^[\w./-]+$/.test(branch.baseName) ? branch.baseName : null,
80
+ pushed: branch.pushed === true,
81
+ // Committed on the agent's machine and held there: an edit in it went
82
+ // without asking, so it is pushed only after "Push this fix".
83
+ held: branch.pushed !== true && branch.held === true,
84
+ remote: branch.pushed === true && typeof branch.remote === 'string' && /^[\w.-]{1,60}$/.test(branch.remote) ? branch.remote : null,
85
+ },
86
+ pr: branch.pushed === true ? pr : null,
87
+ }
88
+ }
89
+
90
+ const TOOL_STATES = ['running', 'done', 'error']
91
+ const PERMISSION_STATES = ['denied', 'expired', 'cancelled']
92
+
93
+ // A card of the answer: a tool step, the plan, a note, or a request the
94
+ // machine refused. A permission card is never taken as pending or approved
95
+ // on the machine's word here: one that was asked on the board comes from the
96
+ // server's own record of it (src/hosted/chat-permissions.js, put in its
97
+ // place by the caller), and anything else the machine calls pending or
98
+ // approved is shown as denied.
99
+ export function cleanCard(card) {
100
+ if (!card || typeof card !== 'object' || Array.isArray(card)) return null
101
+ const id = str(card.id, 120)
102
+ if (!id) return null
103
+ const kind = ['tool', 'plan', 'note', 'permission'].includes(card.kind) ? card.kind : 'tool'
104
+ const base = { id, kind, name: str(card.name, 80) || kind, label: str(card.label, 200) || 'Step' }
105
+ // Where the card sits in the answer's text (src/agent/reply-text.js).
106
+ if (Number.isSafeInteger(card.at) && card.at >= 0 && card.at <= FRAME_LIMITS.text) base.at = card.at
107
+ if (kind === 'plan') {
108
+ return {
109
+ ...base,
110
+ entries: (Array.isArray(card.entries) ? card.entries : []).slice(0, 30).map((entry) => ({
111
+ content: str(entry?.content, 200),
112
+ status: ['pending', 'in_progress', 'completed'].includes(entry?.status) ? entry.status : 'pending',
113
+ })),
114
+ }
115
+ }
116
+ if (kind === 'note') return base
117
+ if (kind === 'permission') {
118
+ return {
119
+ ...base,
120
+ detail: optional(card.detail, 5000),
121
+ diff: null,
122
+ state: PERMISSION_STATES.includes(card.state) ? card.state : 'denied',
123
+ options: [],
124
+ chosen: null,
125
+ answeredBy: null,
126
+ expiresAt: null,
127
+ // Nobody answers this card from the board.
128
+ answerable: false,
129
+ }
130
+ }
131
+ return { ...base, state: TOOL_STATES.includes(card.state) ? card.state : 'running', detail: optional(card.detail, 300) }
132
+ }
133
+
134
+ export function cleanUsage(usage) {
135
+ if (!usage || typeof usage !== 'object') return null
136
+ const out = {}
137
+ for (const key of ['input', 'output', 'total', 'cached', 'contextUsed', 'contextSize']) {
138
+ const value = count(usage[key])
139
+ if (value !== null) out[key] = value
140
+ }
141
+ // A cost only when the agent itself reported one (never worked out here).
142
+ const cost = count(usage.costMicros)
143
+ if (cost !== null) out.costMicros = cost
144
+ return Object.keys(out).length ? out : null
145
+ }
146
+
147
+ export function cleanOptions(options) {
148
+ return (Array.isArray(options) ? options : []).slice(0, 4).map((item) => ({
149
+ category: str(item?.category, 40),
150
+ name: str(item?.name, 60),
151
+ value: str(item?.value, 80),
152
+ ...(typeof item?.description === 'string' && item.description ? { description: item.description.slice(0, 160) } : {}),
153
+ }))
154
+ }
155
+
156
+ // One live event of a turn, as the board's stream carries it:
157
+ // [name, data], or null for anything else (dropped).
158
+ export function cleanEvent(event) {
159
+ if (!event || typeof event !== 'object') return null
160
+ const data = event.data && typeof event.data === 'object' ? event.data : {}
161
+ switch (event.name) {
162
+ case 'status':
163
+ return ['status', { text: str(data.text, 200) }]
164
+ case 'text':
165
+ case 'reasoning':
166
+ return typeof data.text === 'string' && data.text ? [event.name, { text: data.text.slice(0, FRAME_LIMITS.chunk) }] : null
167
+ case 'tool': {
168
+ const card = cleanCard(data)
169
+ if (!card || Buffer.byteLength(JSON.stringify(card)) > FRAME_LIMITS.cardBytes) return null
170
+ return ['tool', card]
171
+ }
172
+ case 'usage': {
173
+ const usage = cleanUsage(data)
174
+ return usage ? ['usage', usage] : null
175
+ }
176
+ case 'options':
177
+ return ['options', { options: cleanOptions(data.options) }]
178
+ default:
179
+ return null
180
+ }
181
+ }
182
+
183
+ const ERROR_CODES = /^[a-z][a-z0-9_]{0,39}$/
184
+
185
+ // The answer the machine finished with, as it is stored and shown.
186
+ export function cleanReply(message) {
187
+ const input = message && typeof message === 'object' && !Array.isArray(message) ? message : {}
188
+ const status = ['done', 'stopped', 'error'].includes(input.status) ? input.status : 'done'
189
+ const cards = []
190
+ for (const item of (Array.isArray(input.cards) ? input.cards : []).slice(0, FRAME_LIMITS.cards)) {
191
+ const card = cleanCard(item)
192
+ if (!card || Buffer.byteLength(JSON.stringify(card)) > FRAME_LIMITS.cardBytes) continue
193
+ // A finished answer has no step still running.
194
+ if (card.kind === 'tool' && card.state === 'running') card.state = status === 'done' ? 'done' : 'error'
195
+ cards.push(card)
196
+ }
197
+ const reply = {
198
+ text: str(input.text, FRAME_LIMITS.text),
199
+ cards,
200
+ status,
201
+ }
202
+ const summary = cleanSummary(input.summary)
203
+ if (summary && status === 'done' && !input.error) reply.summary = summary
204
+ const reasoning = str(input.reasoning, FRAME_LIMITS.reasoning)
205
+ if (reasoning) reply.reasoning = reasoning
206
+ const model = optional(input.model, 120)
207
+ if (model) reply.model = model
208
+ if (input.error && typeof input.error === 'object') {
209
+ reply.error = {
210
+ code: ERROR_CODES.test(String(input.error.code || '')) ? input.error.code : 'agent_error',
211
+ message: str(input.error.message, 500) || 'The agent could not answer.',
212
+ ...(optional(input.error.label, 60) ? { label: optional(input.error.label, 60) } : {}),
213
+ ...(optional(input.error.login, 80) ? { login: optional(input.error.login, 80) } : {}),
214
+ }
215
+ if (status === 'done') reply.status = 'error'
216
+ }
217
+ const usage = cleanUsage(input.usage)
218
+ if (usage) reply.usage = usage
219
+ const options = cleanOptions(input.options)
220
+ if (options.length) reply.options = options
221
+ const suggestions = (Array.isArray(input.suggestions) ? input.suggestions : [])
222
+ .filter((item) => typeof item === 'string' && item.trim())
223
+ .slice(0, 3)
224
+ .map((item) => item.trim().slice(0, 80))
225
+ if (suggestions.length && reply.status === 'done') reply.suggestions = suggestions
226
+ const duration = count(input.durationMs)
227
+ if (duration !== null) reply.durationMs = Math.min(duration, 24 * 60 * 60 * 1000)
228
+ if (['stored', 'length'].includes(input.limit)) reply.limit = input.limit
229
+ // Board references the answer's steps read: ids only, checked by the board.
230
+ const refs = input.refs && typeof input.refs === 'object' ? input.refs : null
231
+ if (refs) {
232
+ const comments = (Array.isArray(refs.comments) ? refs.comments : []).filter((id) => Number.isSafeInteger(id) && id > 0).slice(0, 20)
233
+ const pages = (Array.isArray(refs.pages) ? refs.pages : [])
234
+ .filter((id) => typeof id === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(id))
235
+ .slice(0, 20)
236
+ if (comments.length || pages.length) reply.refs = { comments, pages }
237
+ }
238
+ return reply
239
+ }
240
+
241
+ // What the usage record keeps of an answer (src/hosted/chat-store.js
242
+ // endRun): how it ended and the numbers the agent reported. Never text.
243
+ export function usageOf(reply) {
244
+ const find = (category) => reply.options?.find((item) => item.category === category)?.value || null
245
+ return {
246
+ // A fix that left a branch is "fix_ready".
247
+ outcome: reply.status === 'done' ? (reply.summary ? 'fix_ready' : 'answered') : reply.status === 'stopped' ? 'stopped' : 'failed',
248
+ model: find('model') || reply.model || null,
249
+ effort: find('thought_level'),
250
+ inputTokens: reply.usage?.input ?? null,
251
+ outputTokens: reply.usage?.output ?? null,
252
+ cachedTokens: reply.usage?.cached ?? null,
253
+ costMicros: reply.usage?.costMicros ?? null,
254
+ steps: reply.cards.filter((card) => card.kind === 'tool').length,
255
+ }
256
+ }