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
@@ -15,7 +15,9 @@ import { joinUrl } from '../config.js'
15
15
  import { MENTION_HANDLE_RE } from '../mentions.js'
16
16
  import { captureFiles, listVersions, readManifest, resolveFile, variantsWithFiles } from '../store.js'
17
17
  import { agentPolicy, expandScopes, trustedMember } from './agent-policy.js'
18
+ import { COMMENT_ROUTING } from './agents.js'
18
19
  import { mountHostedApprovals } from './agent-approvals.js'
20
+ import { mountAgentLink } from './agent-link.js'
19
21
  import { sendPng } from './board-context.js'
20
22
  import { markupName } from '../comment-media.js'
21
23
  import { commentListsFile, createMarkupCache, readCommentFile, renderMarkupPng, sendImage } from './comment-files.js'
@@ -31,7 +33,7 @@ import { findApiToken, tenant } from './tenancy.js'
31
33
  import { mountTokenEvents } from './token-events.js'
32
34
 
33
35
  export function mountTokenApi({
34
- agentPresence = null,
36
+ agentsFor,
35
37
  db,
36
38
  dataDir,
37
39
  iso,
@@ -53,6 +55,13 @@ export function mountTokenApi({
53
55
  dispatchView,
54
56
  needFresh,
55
57
  approvalApi,
58
+ // Connected agents (src/hosted/agent-link.js): the chat store, the live
59
+ // turns, the open links and what ends a turn.
60
+ agentPresence = null,
61
+ chatFor = null,
62
+ hub = null,
63
+ links = null,
64
+ chat = null,
56
65
  }) {
57
66
  // ---- Token API ----
58
67
  const pushOptions = (t) => {
@@ -83,12 +92,16 @@ export function mountTokenApi({
83
92
  'This token was revoked or has expired, its maker is no longer an admin of the workspace, or it is wrong. Send a live project token: Authorization: Bearer swp_...',
84
93
  )
85
94
  }
86
- const hits = rateLimiter.hit('token', row.id, LIMITS.token)
95
+ // A connected agent's link has a bucket of its own: an answer streams
96
+ // in many small batches, and must not use up the token's budget.
97
+ const scopes = expandScopes(JSON.parse(row.scopes))
98
+ const onLink = scopes.includes('agent') && /^\/agent\//.test(req.path)
99
+ const hits = onLink ? rateLimiter.hit('agentLink', row.id, LIMITS.agentLink) : rateLimiter.hit('token', row.id, LIMITS.token)
87
100
  if (!hits.ok) {
88
101
  res.setHeader('Retry-After', String(hits.retryAfter))
89
102
  return fail(res, 429, 'rate_limited', 'Too many requests for this token.')
90
103
  }
91
- req.token = { id: row.id, name: row.name, scopes: expandScopes(JSON.parse(row.scopes)) }
104
+ req.token = { id: row.id, name: row.name, scopes }
92
105
  req.tokenHash = sha256(token)
93
106
  req.authTokenHash = row.token_hash
94
107
  req.t = tenant(db, row.workspace_id)
@@ -98,9 +111,18 @@ export function mountTokenApi({
98
111
  req.t.run('UPDATE api_tokens SET last_used_at = :at WHERE workspace_id = :ws AND id = :id', { at: iso(), id: row.id })
99
112
  }
100
113
  req.workspaceName = row.workspace_name
101
- // A token that may take work was heard from: an agent is listening for
102
- // this project (src/hosted/agent-presence.js; the name only).
103
- if (req.token.scopes.includes('claim')) agentPresence?.seen(row.workspace_id, row.project_id, row.name)
114
+ // A token that may take work is an agent (src/hosted/agents.js), and it
115
+ // was just heard from: it is online. A claim token made while an older
116
+ // build ran on this database becomes an agent here, on first sight.
117
+ if (req.token.scopes.includes('claim')) {
118
+ const agents = agentsFor(req.t)
119
+ const said = (action, target, detail) => auditOf(req, action, target, detail)
120
+ req.agent = agents.forToken(row.project_id, row.id, { audit: said })
121
+ // An agent of this project that is gone (revoked, expired, its maker
122
+ // no longer an admin) lets go of what it held before this one looks.
123
+ transaction(db, () => agents.releaseGone(row.project_id, said))
124
+ } else req.agent = null
125
+ if (req.agent) agentsFor(req.t).seen(req.agent)
104
126
  next()
105
127
  }
106
128
  v1.use(tokenAuth)
@@ -126,13 +148,20 @@ export function mountTokenApi({
126
148
  // Guest comments stay away from agents unless asked for, on every route
127
149
  // and not only in lists: reading one, replying, statuses, resolving and
128
150
  // reopening need the same opt-in (?guests=1) as listing them.
151
+ // A claim token works only on comments that are its agent's to take: sent
152
+ // to it or to any agent, by someone in its audience (agents.js claimCheck).
153
+ // A comment sent to another agent does not exist for it: 404, like one
154
+ // that was never dispatched, on every route.
155
+ // The token that holds a comment keeps it until it is done, whatever
156
+ // changed since (agents.js workCheck).
157
+ const mine = (req, row) => agentsFor(req.t).workCheck(req.agent, req.project.id, row).ok
129
158
  const v1Comment = (fn) =>
130
159
  handle(async (req, res) => {
131
160
  req.ctx = boardContext(req.t, req.project, req.params.bid)
132
161
  const row = req.ctx.comments.get(req.params.cid)
133
162
  if (
134
163
  req.token.scopes.includes('claim') &&
135
- !policyFor(req.t).state(req.project.id, req.ctx.board.id, { ...row, status: 'open' }).dispatchable
164
+ (!policyFor(req.t).state(req.project.id, req.ctx.board.id, { ...row, status: 'open' }).dispatchable || !mine(req, row))
136
165
  )
137
166
  throw new HttpError(404, 'unknown_comment', 'No dispatched comment at that id.')
138
167
  if (row.author_share_id && req.query.guests !== '1') {
@@ -149,7 +178,12 @@ export function mountTokenApi({
149
178
  // member vouched for the comment, not for what others added after, so only
150
179
  // replies by members the agent policy trusts and the token's own replies.
151
180
  // Guests, other tokens, untrusted members and imported replies never reach it.
152
- function agentReplies(req, ctx, replies = []) {
181
+ // And of those, only people in this agent's audience: someone it does not
182
+ // take work from cannot steer it through a reply (agents.js replyVisible).
183
+ function agentReplies(req, ctx, replies = [], commentId = null) {
184
+ if (!replies.length) return replies
185
+ const agents = agentsFor(req.t)
186
+ const row = commentId ? ctx.comments.get(commentId) : null
153
187
  const policy = agentPolicy(req.t, req.project.id, ctx.board.id)
154
188
  const handleFor = (user) => q.get('SELECT handle FROM users WHERE id = :id', { id: user })?.handle || null
155
189
  return replies.filter((reply) => {
@@ -157,15 +191,15 @@ export function mountTokenApi({
157
191
  if (reply.agent) return Boolean(by.token) && by.token === req.token.id
158
192
  if (reply.guest || reply.imported) return false
159
193
  const user = by.user || (reply.handle ? q.get('SELECT id FROM users WHERE handle = :handle', { handle: reply.handle })?.id : null)
160
- return trustedMember({ ...req.t, handleFor }, policy, user)
194
+ return trustedMember({ ...req.t, handleFor }, policy, user) && agents.replyVisible(req.agent, req.project.id, row, user)
161
195
  })
162
196
  }
163
197
 
164
198
  // The replies a token reads. A claim token: agentReplies above. Any other
165
199
  // token: everything but share link guests' replies, which (like guest
166
200
  // comments) come only when asked for (?guests=1), on every route.
167
- function tokenReplies(req, ctx, replies = []) {
168
- if (req.token.scopes.includes('claim')) return agentReplies(req, ctx, replies)
201
+ function tokenReplies(req, ctx, replies = [], commentId = null) {
202
+ if (req.token.scopes.includes('claim')) return agentReplies(req, ctx, replies, commentId)
169
203
  return req.query.guests === '1' ? replies : replies.filter((reply) => !reply.guest)
170
204
  }
171
205
 
@@ -188,9 +222,12 @@ export function mountTokenApi({
188
222
  // Feedback items with download URLs instead of server paths.
189
223
  function remoteItem(req, ctx, context, comment) {
190
224
  const item = {
191
- ...feedbackItem(context, { ...comment, replies: tokenReplies(req, ctx, comment.replies) }),
225
+ ...feedbackItem(context, { ...comment, replies: tokenReplies(req, ctx, comment.replies, comment.id) }),
192
226
  dispatchable: Boolean(comment.dispatchable),
193
227
  needsRunApproval: Boolean(comment.needsRunApproval),
228
+ // The agent it was sent to, for a token that may take work: its own
229
+ // agent's id, or null for any agent (one sent elsewhere is never listed).
230
+ ...(req.token.scopes.includes('claim') ? { agentId: comment.agentId || null } : {}),
194
231
  }
195
232
  // The capture a comment was made on can be an archived version (versions/).
196
233
  const url = (file) =>
@@ -232,12 +269,12 @@ export function mountTokenApi({
232
269
  const row = ctx.comments.get(number)
233
270
  if (
234
271
  req.token.scopes.includes('claim') &&
235
- !policyFor(req.t).state(req.project.id, ctx.board.id, { ...row, status: 'open' }).dispatchable
272
+ (!policyFor(req.t).state(req.project.id, ctx.board.id, { ...row, status: 'open' }).dispatchable || !mine(req, row))
236
273
  )
237
274
  return null
238
275
  const comment = dispatchView(req.t, req.project.id, ctx.board.id, rowToComment(row))
239
276
  if (comment.authorGuest && req.query.guests !== '1') return null
240
- const replies = tokenReplies(req, ctx, comment.replies)
277
+ const replies = tokenReplies(req, ctx, comment.replies, comment.id)
241
278
  if (replyId && !replies.some((reply) => Number(reply.id) === Number(replyId))) return null
242
279
  return { ...comment, replies }
243
280
  }
@@ -251,7 +288,7 @@ export function mountTokenApi({
251
288
  const comments = ctx.comments
252
289
  .list({ status: status === 'all' ? null : status, mention })
253
290
  .map((comment) => dispatchView(req.t, req.project.id, ctx.board.id, comment))
254
- .filter((comment) => !req.token.scopes.includes('claim') || comment.dispatchable)
291
+ .filter((comment) => !req.token.scopes.includes('claim') || (comment.dispatchable && mine(req, comment[COMMENT_ROUTING])))
255
292
  .filter((comment) => !pageId || comment.pageId === pageId || context.variants.get(comment.pageId)?.pageId === pageId)
256
293
  .filter((comment) => {
257
294
  if (guests || !comment.authorGuest) return true
@@ -278,7 +315,31 @@ export function mountTokenApi({
278
315
  // Any `author` in the request is ignored, so a token cannot pose as a person.
279
316
  const tokenAuthor = (req) => ({ name: cleanAuthor(req.token.name, 'agent'), agent: true })
280
317
 
281
- mountTokenEvents(v1, { db, iso, events, streams, scope, agentPresence })
318
+ mountTokenEvents(v1, { db, iso, events, streams, scope, agentsFor })
319
+ if (chatFor && hub && links && chat)
320
+ mountAgentLink(v1, {
321
+ db,
322
+ iso,
323
+ now,
324
+ events,
325
+ streams,
326
+ scope,
327
+ handle,
328
+ agentsFor,
329
+ agentPresence,
330
+ rateLimiter,
331
+ chatFor,
332
+ hub,
333
+ links,
334
+ chat,
335
+ auditOf,
336
+ boardContext,
337
+ policyFor,
338
+ dispatchView,
339
+ remoteItem,
340
+ contextFor,
341
+ quotaOf: (t) => workspaceQuota ?? quotas.of(t.workspaceId).storageBytes,
342
+ })
282
343
 
283
344
  v1.get(
284
345
  '/project',
@@ -495,14 +556,36 @@ export function mountTokenApi({
495
556
  v1Json,
496
557
  v1Comment((req, res, ctx) => {
497
558
  const { agentStatus = null, onlyFrom = null } = req.body || {}
559
+ // While a fix the server opened runs on this comment, where the comment
560
+ // stands is written with that turn, by the server (src/hosted/agent-link.js
561
+ // releaseFix). A write from the token, late from an earlier fix or not,
562
+ // would end the running fix's claim: it is not taken.
563
+ const fixing = hub?.ofThread(req.t.workspaceId, req.project.id, ctx.board.id, `comment-${Number(req.params.cid)}`)
564
+ if (fixing?.kind === 'fix')
565
+ throw new HttpError(409, 'fix_running', 'A fix is running on this comment: its status is written when that fix ends.')
498
566
  const result = transaction(db, () => {
499
567
  const row = ctx.comments.get(req.params.cid)
500
568
  const taking = ['queued', 'working'].includes(agentStatus) && !['queued', 'working'].includes(row.agent_status)
501
569
  if (taking && !req.token.scopes.includes('claim')) throw new HttpError(403, 'missing_scope', 'Taking work needs the claim scope.')
502
570
  // Only open comments are claimed (and counted against the budget).
503
571
  if (taking && row.status !== 'open') throw new HttpError(409, 'not_open', 'Only an open comment can be taken.')
504
- if (taking && row.status === 'open' && (!onlyFrom || onlyFrom.includes(row.agent_status || null)))
505
- policyFor(req.t).claim(req.project.id, ctx.board.id, row, req.token.id)
572
+ const agents = agentsFor(req.t)
573
+ if (taking && row.status === 'open' && (!onlyFrom || onlyFrom.includes(row.agent_status || null))) {
574
+ // Checked again on the row this transaction reads: a comment sent
575
+ // to another agent, or by someone outside this agent's audience,
576
+ // is never taken.
577
+ const check = agents.claimCheck(req.agent, req.project.id, row)
578
+ if (!check.ok) throw new HttpError(403, check.code, check.message)
579
+ const claimId = policyFor(req.t).claim(req.project.id, ctx.board.id, row, req.token.id, req.agent.id)
580
+ agents.startRun({
581
+ projectId: req.project.id,
582
+ boardId: ctx.board.id,
583
+ number: row.number,
584
+ agentId: req.agent.id,
585
+ claimId,
586
+ askedBy: row.dispatch_by,
587
+ })
588
+ }
506
589
  if (['queued', 'working'].includes(row.agent_status)) {
507
590
  const claim = req.t.get(
508
591
  'SELECT token_id FROM agent_claims WHERE workspace_id = :ws AND project_id = :project AND board_id = :board AND comment_number = :number AND ended_at IS NULL ORDER BY created_at DESC LIMIT 1',
@@ -516,6 +599,9 @@ export function mountTokenApi({
516
599
  'UPDATE agent_claims SET ended_at = :at WHERE workspace_id = :ws AND project_id = :project AND board_id = :board AND comment_number = :number AND ended_at IS NULL',
517
600
  { project: req.project.id, board: ctx.board.id, number: row.number, at: iso() },
518
601
  )
602
+ // The usage record of every run whose claim just ended (this one, or
603
+ // stale ones the claim above swept).
604
+ agents.closeRuns(req.project.id)
519
605
  return result
520
606
  })
521
607
  res.json({ comment: v1Item(req, ctx, result.comment), changed: result.changed })
@@ -553,7 +639,20 @@ export function mountTokenApi({
553
639
  }),
554
640
  )
555
641
  v1.use(v1Json)
556
- mountHostedApprovals({ v1, boardApi: approvalApi, handle, scope, db, transaction, policyFor, boardContext, needFresh, auditOf, now })
642
+ mountHostedApprovals({
643
+ v1,
644
+ boardApi: approvalApi,
645
+ handle,
646
+ scope,
647
+ db,
648
+ transaction,
649
+ policyFor,
650
+ agentsFor,
651
+ boardContext,
652
+ needFresh,
653
+ auditOf,
654
+ now,
655
+ })
557
656
  v1.use((req, res) => fail(res, 404, 'not_found', 'No such API route.'))
558
657
 
559
658
  return { v1, tokenAuth }
@@ -8,7 +8,7 @@ import { findApiToken } from './tenancy.js'
8
8
 
9
9
  const STREAMS_PER_WORKSPACE = 100
10
10
 
11
- export function mountTokenEvents(v1, { db, iso, events, streams, scope, agentPresence = null }) {
11
+ export function mountTokenEvents(v1, { db, iso, events, streams, scope, agentsFor = null }) {
12
12
  v1.get('/events', scope('read'), (req, res) => {
13
13
  if (streams.size >= 1000 || [...streams].filter((check) => check.tokenId === req.token.id).length >= 5)
14
14
  return fail(res, 429, 'stream_budget', 'Too many event streams for this token.')
@@ -41,6 +41,8 @@ export function mountTokenEvents(v1, { db, iso, events, streams, scope, agentPre
41
41
  // lookup; revocation is still caught here, by the keepalive and after
42
42
  // every mutating request.
43
43
  if (closed || event.workspace !== req.t.workspaceId || event.project !== req.project.id) return
44
+ // Chat turns and agents coming and going are the board's business, not a watcher's.
45
+ if (/^(chat|agent)\./.test(event.type)) return
44
46
  check()
45
47
  if (!closed) {
46
48
  if (
@@ -53,8 +55,8 @@ export function mountTokenEvents(v1, { db, iso, events, streams, scope, agentPre
53
55
  check()
54
56
  if (closed) return
55
57
  res.write(': keepalive\n\n')
56
- // An open stream of a token that may take work is an agent listening.
57
- if (req.token.scopes.includes('claim')) agentPresence?.seen(req.t.workspaceId, req.project.id, req.token.name)
58
+ // An open stream of a token that may take work is its agent listening.
59
+ if (req.agent) agentsFor?.(req.t).seen(req.agent)
58
60
  }, 15000)
59
61
  timer.unref()
60
62
  res.write(': connected\n\n')
@@ -6,14 +6,20 @@ import { expandScopes } from './agent-policy.js'
6
6
  import { newApiToken, newId } from './crypto.js'
7
7
  import { HttpError, cleanName } from './http.js'
8
8
 
9
- export const TOKEN_SCOPES = ['read', 'reply', 'status', 'claim', 'resolve', 'push', 'import']
9
+ // "agent": may hold the link of a connected agent (`shapewall agent connect`,
10
+ // src/hosted/agent-link.js). It opens the link routes only, and is granted
11
+ // only by approving an agent connection (or by an admin, on purpose, for a
12
+ // service's token); "claim" alone still means "may take dispatched comments".
13
+ export const TOKEN_SCOPES = ['read', 'reply', 'status', 'claim', 'resolve', 'push', 'import', 'agent']
10
14
  const DAY = 86_400_000
11
15
 
12
- export function createApiTokens({ iso, auditOf }) {
16
+ export function createApiTokens({ iso, auditOf, agentsFor = null }) {
13
17
  // A new project token for req.t / req.project, made by req.user. Returns
14
18
  // the token (shown once) and its listing. `via` marks how it was made
15
- // ("login" for `shapewall login`) in the audit log.
16
- function createApiToken(req, body, { via = null } = {}) {
19
+ // ("login" for `shapewall login`) in the audit log. A token that may take
20
+ // work (the claim scope) is an agent from the start (src/hosted/agents.js),
21
+ // for the person who made it only; `machine` is the label a login sent.
22
+ function createApiToken(req, body, { via = null, machine = null, agent = null } = {}) {
17
23
  // A name too long is refused, not cut (as on a rename): it is what people will see.
18
24
  const name = cleanName(body.name, 61)
19
25
  if (!name || name.length > 60) throw new HttpError(400, 'invalid_name', 'Token name: 1 to 60 characters.')
@@ -21,6 +27,10 @@ export function createApiTokens({ iso, auditOf }) {
21
27
  if (!scopes.length || scopes.some((scope) => !TOKEN_SCOPES.includes(scope))) {
22
28
  throw new HttpError(400, 'invalid_scopes', `Scopes: ${TOKEN_SCOPES.join(', ')}.`)
23
29
  }
30
+ // The link scope is an agent's: it never stands without the scopes an
31
+ // agent works with (it reads comments and answers them as itself).
32
+ if (scopes.includes('agent') && !['read', 'reply', 'status', 'claim'].every((scope) => scopes.includes(scope)))
33
+ throw new HttpError(400, 'invalid_scopes', 'The agent scope goes with read, reply, status and claim.')
24
34
  if (scopes.includes('import') && via !== 'import')
25
35
  throw new HttpError(403, 'import_login_required', 'Import is a one-time grant from a moving-project device login.')
26
36
  const days = body.expiresInDays
@@ -50,8 +60,14 @@ export function createApiTokens({ iso, auditOf }) {
50
60
  },
51
61
  )
52
62
  auditOf(req, 'token_created', id, { project: req.project.id, scopes, ...(days ? { days } : {}), ...(via ? { via } : {}) })
63
+ let agentId = null
64
+ if (scopes.includes('claim') && agentsFor)
65
+ agentId = agentsFor(req.t).create(
66
+ { userId: req.user.id, role: req.role, audit: (action, target, detail) => auditOf(req, action, target, detail) },
67
+ { projectId: req.project.id, tokenId: id, name, machine, ...(agent || {}) },
68
+ )
53
69
  const info = listTokens(req.t, { projectId: req.project.id, now: iso() }).find((item) => item.id === id)
54
- return { token, info }
70
+ return { token, info, agentId }
55
71
  }
56
72
 
57
73
  return createApiToken
@@ -0,0 +1,152 @@
1
+ // Chat turns in flight on a hosted server, in memory. A turn is one
2
+ // question on its way through a connected agent: the board posts it, the
3
+ // agent's machine picks it up over its link (src/hosted/agent-link.js),
4
+ // streams events back, and finishes it with the answer. This hub keeps what
5
+ // only matters while that happens:
6
+ //
7
+ // - the events so far (bounded), so a second viewer or a reloaded tab can
8
+ // replay them and follow on (subscribe with `after`)
9
+ // - who listens (the sender's response and any other viewer's)
10
+ // - the cancel flag (Stop), and when the machine was last heard from
11
+ //
12
+ // Stored state (the messages, the turn's row) lives in the database
13
+ // (src/hosted/chat-store.js). Nothing here survives a restart: turns that
14
+ // were running then are marked interrupted when their thread is next read.
15
+ //
16
+ // Keys carry the workspace, so one tenant's ids never meet another's.
17
+
18
+ export const TURN_LIMITS = {
19
+ // Live events kept per turn for replay. Past this the oldest text goes
20
+ // first; a late viewer then starts from what is left.
21
+ bufferBytes: 1024 * 1024,
22
+ // A running turn nobody has heard from in this long is interrupted when
23
+ // its agent has no link either.
24
+ lostMs: 45_000,
25
+ // However long the agent's machine allows, the server lets go after this.
26
+ maxMs: 30 * 60_000,
27
+ subscribers: 20,
28
+ }
29
+
30
+ const sizeOf = (data) => Buffer.byteLength(JSON.stringify(data))
31
+
32
+ export function createTurnHub({ now = () => Date.now(), limits = {} } = {}) {
33
+ const limit = { ...TURN_LIMITS, ...limits }
34
+ // turn id -> turn
35
+ const turns = new Map()
36
+ // `${workspace}:${project}:${board}:${thread}` -> turn id
37
+ const byThread = new Map()
38
+
39
+ const threadKey = (turn) => `${turn.workspaceId}:${turn.projectId}:${turn.boardId}:${turn.threadId}`
40
+
41
+ // A new turn. `seed`: events every subscriber sees first (the stored
42
+ // person's message). Returns the live turn.
43
+ function open({ id, workspaceId, projectId, boardId, threadId, agentId, kind = 'chat', startedBy = null, seed = [] }) {
44
+ const turn = {
45
+ id,
46
+ workspaceId,
47
+ projectId,
48
+ boardId,
49
+ threadId,
50
+ agentId,
51
+ kind,
52
+ startedBy,
53
+ state: 'queued',
54
+ cancel: false,
55
+ events: [],
56
+ bytes: 0,
57
+ // The next sequence number given to a browser event (1-based).
58
+ next: 1,
59
+ // The last batch the agent's machine sent, by its own numbering.
60
+ acked: 0,
61
+ subscribers: new Set(),
62
+ openedAt: now(),
63
+ heardAt: now(),
64
+ // What the answer's cards looked like last, by id: the stored answer
65
+ // is the machine's, but a turn that is cut short keeps these.
66
+ trimmed: false,
67
+ }
68
+ turns.set(id, turn)
69
+ byThread.set(threadKey(turn), id)
70
+ for (const event of seed) push(turn, event.name, event.data)
71
+ return turn
72
+ }
73
+
74
+ function push(turn, name, data) {
75
+ const event = { seq: turn.next, name, data }
76
+ turn.next += 1
77
+ const bytes = sizeOf(data) + name.length + 16
78
+ turn.events.push({ ...event, bytes })
79
+ turn.bytes += bytes
80
+ // Over the cap: streamed text and thinking go first (the stored answer
81
+ // will have them); cards and statuses stay as long as they fit.
82
+ while (turn.bytes > limit.bufferBytes && turn.events.length > 1) {
83
+ const index = turn.events.findIndex((item) => item.name === 'text' || item.name === 'reasoning')
84
+ const [gone] = turn.events.splice(index >= 0 ? index : 0, 1)
85
+ turn.bytes -= gone.bytes
86
+ turn.trimmed = true
87
+ }
88
+ for (const subscriber of [...turn.subscribers]) {
89
+ try {
90
+ subscriber(event)
91
+ } catch {
92
+ turn.subscribers.delete(subscriber)
93
+ }
94
+ }
95
+ return event
96
+ }
97
+
98
+ const get = (id) => turns.get(id) || null
99
+ const ofThread = (workspaceId, projectId, boardId, threadId) => get(byThread.get(`${workspaceId}:${projectId}:${boardId}:${threadId}`))
100
+ const ofAgent = (workspaceId, agentId) =>
101
+ [...turns.values()].filter((turn) => turn.workspaceId === workspaceId && turn.agentId === agentId)
102
+
103
+ // Events from `after` on, then every new one, until the turn ends (the
104
+ // listener then hears { name: 'end' } once). Returns the unsubscribe, or
105
+ // null when the turn has too many listeners.
106
+ function subscribe(turn, after, listener) {
107
+ if (turn.subscribers.size >= limit.subscribers) return null
108
+ for (const event of turn.events) if (event.seq > after) listener({ seq: event.seq, name: event.name, data: event.data })
109
+ turn.subscribers.add(listener)
110
+ return () => turn.subscribers.delete(listener)
111
+ }
112
+
113
+ // The turn is over: every listener hears the last event and `end`.
114
+ function close(turn, name = null, data = null) {
115
+ if (!turns.has(turn.id)) return
116
+ if (name) push(turn, name, data)
117
+ turns.delete(turn.id)
118
+ if (byThread.get(threadKey(turn)) === turn.id) byThread.delete(threadKey(turn))
119
+ const listeners = [...turn.subscribers]
120
+ turn.subscribers.clear()
121
+ for (const listener of listeners) {
122
+ try {
123
+ listener({ seq: turn.next, name: 'end', data: null })
124
+ } catch {
125
+ /* a listener that went away */
126
+ }
127
+ }
128
+ }
129
+
130
+ // Turns whose machine went quiet (`linked(turn)`: its agent still holds a
131
+ // link) or that ran past the limit: the caller interrupts them.
132
+ function stale(linked) {
133
+ const time = now()
134
+ return [...turns.values()].filter((turn) => time - turn.openedAt > limit.maxMs || (time - turn.heardAt > limit.lostMs && !linked(turn)))
135
+ }
136
+
137
+ return {
138
+ open,
139
+ push,
140
+ get,
141
+ ofThread,
142
+ ofAgent,
143
+ subscribe,
144
+ close,
145
+ stale,
146
+ heard: (turn) => {
147
+ turn.heardAt = now()
148
+ },
149
+ all: () => [...turns.values()],
150
+ size: () => turns.size,
151
+ }
152
+ }