shapewall 0.3.3 → 0.7.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 (157) hide show
  1. package/CHANGELOG.md +501 -0
  2. package/README.md +87 -4
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/BoardChat-WS8mAIW6.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-B-Mlr6wF.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-Dx1ZLBR6.js +1 -0
  8. package/dist/client/assets/History-sXhmpcvs.js +1 -0
  9. package/dist/client/assets/LocalSettings-CtGzz9F3.js +1 -0
  10. package/dist/client/assets/{Management-NVFDtSZB.js → Management-CGHe8Wt9.js} +1 -1
  11. package/dist/client/assets/QuickConnect-DEk84E4A.js +1 -0
  12. package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-CGGx-AYK.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-_bVp8hnC.js} +1 -1
  14. package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-BWoHA1QY.js} +1 -1
  15. package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
  16. package/dist/client/assets/index-C7Ostk3K.css +2 -0
  17. package/dist/client/assets/play-BzQ3tRTv.js +1 -0
  18. package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-BYBMyDKT.js} +1 -1
  19. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  20. package/dist/client/assets/ui-CAY6myRA.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
  25. package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
  26. package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
  27. package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
  28. package/dist/console/assets/app-version-muKrQqbL.js +1 -0
  29. package/dist/console/assets/console-CrhTsPbz.css +2 -0
  30. package/dist/console/assets/console-DxapQ9oS.js +11 -0
  31. package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
  32. package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
  33. package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
  34. package/dist/console/assets/theme-DCd0qh4l.js +1 -0
  35. package/dist/console/assets/ui-Bry1mnCY.js +41 -0
  36. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  37. package/dist/console/assets/usage-CqVjMb7m.js +5 -0
  38. package/dist/console/assets/usage-D1G0GgE3.js +56 -0
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -2
  41. package/docs/agent-hardening.md +206 -0
  42. package/docs/agent-recipes.md +23 -0
  43. package/docs/agent-workflow.md +5 -0
  44. package/docs/agents.md +49 -6
  45. package/docs/architecture.md +10 -4
  46. package/docs/deployment.md +39 -17
  47. package/docs/design-system.md +56 -7
  48. package/docs/hosted.md +1800 -46
  49. package/docs/images/board-overview.png +0 -0
  50. package/docs/images/journeys.png +0 -0
  51. package/docs/images/live-comment.png +0 -0
  52. package/docs/images/phone-comment.png +0 -0
  53. package/docs/images/phone-overview.png +0 -0
  54. package/docs/images/variant.png +0 -0
  55. package/docs/where-to-run.md +119 -3
  56. package/package.json +6 -1
  57. package/src/agent/backends/acp.js +745 -44
  58. package/src/agent/branch-mode.js +17 -3
  59. package/src/agent/card-hash.js +65 -0
  60. package/src/agent/context.js +41 -0
  61. package/src/agent/exec-paths.js +105 -0
  62. package/src/agent/routes.js +23 -2
  63. package/src/agent/run.js +11 -1
  64. package/src/agent/starter/cli.js +6 -1
  65. package/src/agent/turn-changes.js +70 -8
  66. package/src/agent/usage-log.js +251 -0
  67. package/src/cli/args.js +37 -0
  68. package/src/cli/commands.js +20 -5
  69. package/src/cli/help.js +73 -3
  70. package/src/cli/init.js +2 -1
  71. package/src/cli/serve.js +20 -5
  72. package/src/cli.js +8 -0
  73. package/src/hosted/access-cli.js +99 -1
  74. package/src/hosted/activity-core.js +232 -0
  75. package/src/hosted/activity.js +375 -0
  76. package/src/hosted/admin.js +87 -13
  77. package/src/hosted/agent-approvals.js +29 -4
  78. package/src/hosted/agent-link.js +1032 -0
  79. package/src/hosted/agent-policy.js +10 -3
  80. package/src/hosted/agent-presence.js +63 -22
  81. package/src/hosted/agent-routes.js +135 -0
  82. package/src/hosted/agents.js +1206 -0
  83. package/src/hosted/app.js +178 -12
  84. package/src/hosted/auth-routes.js +156 -15
  85. package/src/hosted/auth.js +123 -20
  86. package/src/hosted/board-routes.js +129 -5
  87. package/src/hosted/chat-frames.js +246 -0
  88. package/src/hosted/chat-job.js +204 -0
  89. package/src/hosted/chat-permissions.js +203 -0
  90. package/src/hosted/chat-routes.js +1009 -0
  91. package/src/hosted/chat-store.js +477 -0
  92. package/src/hosted/comment-files.js +11 -1
  93. package/src/hosted/comments.js +1 -1
  94. package/src/hosted/console-routes.js +122 -34
  95. package/src/hosted/db.js +295 -0
  96. package/src/hosted/device-routes.js +88 -10
  97. package/src/hosted/device.js +54 -4
  98. package/src/hosted/events.js +3 -3
  99. package/src/hosted/guards.js +337 -27
  100. package/src/hosted/http.js +6 -3
  101. package/src/hosted/membership.js +22 -3
  102. package/src/hosted/operator-access.js +418 -0
  103. package/src/hosted/operator.js +106 -2
  104. package/src/hosted/ops-cli.js +238 -3
  105. package/src/hosted/pages.js +4 -0
  106. package/src/hosted/passkey-policy.js +75 -0
  107. package/src/hosted/permissions.js +52 -6
  108. package/src/hosted/presence.js +31 -2
  109. package/src/hosted/projects.js +30 -2
  110. package/src/hosted/public.js +4 -4
  111. package/src/hosted/ratelimit.js +14 -0
  112. package/src/hosted/retention.js +18 -2
  113. package/src/hosted/server.js +123 -11
  114. package/src/hosted/shares.js +2 -2
  115. package/src/hosted/step-up-settings.js +68 -0
  116. package/src/hosted/step-up.js +135 -0
  117. package/src/hosted/tailnet-identity.js +24 -0
  118. package/src/hosted/tailnet-routes.js +342 -0
  119. package/src/hosted/tailnet.js +220 -0
  120. package/src/hosted/tailscale.js +75 -9
  121. package/src/hosted/tenancy.js +66 -1
  122. package/src/hosted/token-api.js +119 -20
  123. package/src/hosted/token-events.js +5 -3
  124. package/src/hosted/tokens.js +29 -6
  125. package/src/hosted/turn-hub.js +152 -0
  126. package/src/hosted/usage-core.js +624 -0
  127. package/src/hosted/usage-layout.js +724 -0
  128. package/src/hosted/usage-routes.js +375 -0
  129. package/src/hosted/usage-shape.js +256 -0
  130. package/src/hosted/usage.js +641 -0
  131. package/src/remote/agent-connect.js +469 -0
  132. package/src/remote/agent-fix.js +611 -0
  133. package/src/remote/agent-job.js +216 -0
  134. package/src/remote/agent-link.js +906 -0
  135. package/src/remote/agent-policy-file.js +242 -0
  136. package/src/remote/credentials.js +35 -1
  137. package/src/remote/login.js +44 -9
  138. package/src/remote/share.js +1 -1
  139. package/src/remote/tailnet-cli.js +547 -0
  140. package/src/server/app.js +15 -0
  141. package/src/server/pairing-routes.js +34 -5
  142. package/src/server/tailscale.js +97 -4
  143. package/src/tailnet-proof.js +766 -0
  144. package/dist/client/assets/BoardChat-DxehB761.js +0 -27
  145. package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
  146. package/dist/client/assets/History-C9N32kCv.js +0 -1
  147. package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
  148. package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
  149. package/dist/client/assets/index-CsqLdqGx.css +0 -2
  150. package/dist/client/assets/index-DnZarJ3U.js +0 -37
  151. package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
  152. package/dist/client/assets/ui-DI-FGWWK.js +0 -41
  153. package/dist/console/assets/LocalAccountsApp-VOCZg8dg.js +0 -1
  154. package/dist/console/assets/LocalConsole-CMwAW-mF.js +0 -1
  155. package/dist/console/assets/app-update-dialog-Cw6UDqNP.js +0 -1
  156. package/dist/console/assets/console-DgfWmUEx.js +0 -55
  157. package/dist/console/assets/console-Lis0vvdL.css +0 -2
@@ -0,0 +1,1032 @@
1
+ // The link of a connected agent (`shapewall agent connect`), on the token
2
+ // API under /api/v1/agent. The machine that has the code holds it open; the
3
+ // server never reaches into that machine and never runs anything there. It
4
+ // is the pattern `watch --remote` already uses: a bearer-authenticated
5
+ // server-sent event stream down, authenticated POSTs up, events that carry
6
+ // ids only, state refetched after every reconnect.
7
+ //
8
+ // POST /agent/hello what the agent is and can do (display, and
9
+ // what its own machine narrows)
10
+ // GET /agent/link the stream: `work` { turn }, `cancel`
11
+ // { turn }, `change` { type, board }, and a
12
+ // keepalive every 15 seconds
13
+ // GET /agent/work every open turn of this agent, with its
14
+ // cancel flag and the last batch acknowledged
15
+ // GET /agent/turns/:id the job: the conversation and the board
16
+ // around it, as structured data
17
+ // POST /agent/turns/:id/events { seq, events } -> { ack, cancel }
18
+ // POST /agent/turns/:id/finish { seq, message } -> the answer is stored
19
+ // POST /agent/turns { board, comment }: a turn the agent opens
20
+ // for a comment it took
21
+ //
22
+ // Approvals (a fix, on a machine that takes edits from the board): the
23
+ // machine sends a `permission` event with the card and its hash; the server
24
+ // checks the hash, stores the card (chat-permissions.js) and shows it. A
25
+ // person's answer goes down the stream as `answer` { turn, card, decision,
26
+ // hash, by }, and again in GET /agent/work for a machine that was
27
+ // reconnecting. The machine checks it once more. The server never invents a
28
+ // card and never calls one approved on the machine's word.
29
+ //
30
+ // Every route needs the "agent" scope and derives the workspace, project and
31
+ // agent from the token: no id in a request can name another tenant's turn.
32
+ // What the machine sends is cleaned field by field (chat-frames.js); batches
33
+ // are numbered per turn, applied in order, repeated ones dropped, a gap
34
+ // refused. Revoking the token closes the stream at once (the same recheck
35
+ // the event stream has) and interrupts what it was answering.
36
+
37
+ import express from 'express'
38
+ import { CARD_HASH_RE, CARD_ID_RE, cardContent, cardHash, cardSubjectHash, cardTtlMax } from '../agent/card-hash.js'
39
+ import { checkStorageQuota } from './comment-files.js'
40
+ import { FRAME_LIMITS, cleanEvent, cleanReply, usageOf } from './chat-frames.js'
41
+ import { createPermissionStore, permissionView } from './chat-permissions.js'
42
+ import { buildJob } from './chat-job.js'
43
+ import { INTERRUPTED_MESSAGE } from './chat-store.js'
44
+ import { LINK_KINDS, LINK_TURNS_MAX } from './agents.js'
45
+ import { rowToComment } from './comments.js'
46
+ import { transaction } from './db.js'
47
+ import { HttpError, fail } from './http.js'
48
+ import { LIMITS } from './ratelimit.js'
49
+ import { audit, findApiToken, tenant, workspacesWithOpenTurns } from './tenancy.js'
50
+ import { TURN_LIMITS } from './turn-hub.js'
51
+
52
+ export const LINK_LIMITS = {
53
+ // One process holds an agent's link (a second is refused, or takes over).
54
+ streamsPerToken: 1,
55
+ // agent.changed per agent, and link audit rows per agent and kind.
56
+ changedEveryMs: 3000,
57
+ auditEveryMs: 60_000,
58
+ streams: 500,
59
+ // Turns waiting for a busy agent, on top of the ones it runs.
60
+ queued: 5,
61
+ keepaliveMs: 15_000,
62
+ // After Stop: how long the agent's machine has to finish the turn itself.
63
+ stopGraceMs: 15_000,
64
+ }
65
+
66
+ // The open links, in memory: `${workspace}:${agent}` -> Set of streams.
67
+ export function createAgentLinks({ hub = null } = {}) {
68
+ const open = new Map()
69
+ const key = (workspaceId, agentId) => `${workspaceId}:${agentId}`
70
+ const list = (workspaceId, agentId) => [...(open.get(key(workspaceId, agentId)) || [])]
71
+ return {
72
+ add(workspaceId, agentId, stream) {
73
+ const id = key(workspaceId, agentId)
74
+ if (!open.has(id)) open.set(id, new Set())
75
+ open.get(id).add(stream)
76
+ },
77
+ // Returns how many streams the agent has left.
78
+ remove(workspaceId, agentId, stream) {
79
+ const id = key(workspaceId, agentId)
80
+ const set = open.get(id)
81
+ if (!set) return 0
82
+ set.delete(stream)
83
+ if (!set.size) open.delete(id)
84
+ return set.size
85
+ },
86
+ // { connectedAt, streams, machine } while the agent holds a link, else null.
87
+ of(workspaceId, agentId) {
88
+ const streams = list(workspaceId, agentId)
89
+ if (!streams.length) return null
90
+ const first = streams.sort((x, y) => String(x.connectedAt).localeCompare(String(y.connectedAt)))[0]
91
+ return { connectedAt: first.connectedAt, streams: streams.length, machine: first.machine || null }
92
+ },
93
+ // The agent's streams (one process holds one: `linkId` names the process).
94
+ streamsOf: list,
95
+ // Whether the process that calls itself `linkId` holds a stream for the agent.
96
+ holds: (workspaceId, agentId, linkId) => list(workspaceId, agentId).some((stream) => stream.linkId === linkId),
97
+ turns: (workspaceId, agentId) => hub?.ofAgent(workspaceId, agentId).length || 0,
98
+ // Sends one event to the agent's stream. False: it has none.
99
+ send(workspaceId, agentId, event, data) {
100
+ const streams = list(workspaceId, agentId)
101
+ if (!streams.length) return false
102
+ // One process per agent holds the link: work goes to exactly one stream.
103
+ streams.at(-1).send(event, data)
104
+ return true
105
+ },
106
+ count: () => [...open.values()].reduce((sum, set) => sum + set.size, 0),
107
+ closeAll() {
108
+ for (const set of [...open.values()]) for (const stream of [...set]) stream.close('shutdown')
109
+ },
110
+ }
111
+ }
112
+
113
+ // What the live events of a turn add up to so far: the text and the cards
114
+ // as last seen. Kept when a turn is cut short, so the thread shows what the
115
+ // agent had written.
116
+ export function partialOf(turn) {
117
+ let text = ''
118
+ const cards = new Map()
119
+ for (const event of turn?.events || []) {
120
+ if (event.name === 'text') text += event.data.text
121
+ else if (event.name === 'tool') cards.set(event.data.id, event.data)
122
+ }
123
+ return {
124
+ text: text.slice(0, FRAME_LIMITS.text),
125
+ cards: [...cards.values()].map((card) => (card.state === 'running' ? { ...card, state: 'error' } : card)),
126
+ }
127
+ }
128
+
129
+ // What ends a turn from the server's side (the machine went away, Stop with
130
+ // no machine to hear it, a revoked agent, a restart), in one place.
131
+ export function createChatService({ db, hub, links, events, chatFor, now = () => new Date() }) {
132
+ const permsFor = (t) => createPermissionStore(t, { now })
133
+ const nameOf = (t) => (userId) =>
134
+ t.get('SELECT u.display_name FROM memberships m JOIN users u ON u.id = m.user_id WHERE m.workspace_id = :ws AND m.user_id = :user', {
135
+ user: userId,
136
+ })?.display_name || 'someone who left'
137
+ // The turn is over: whatever cards still waited are cancelled, and every
138
+ // viewer sees it. Runs inside the caller's transaction.
139
+ function cancelCards(t, row, live = hub.get(row.id)) {
140
+ const cancelled = permsFor(t).cancelTurn(row.id)
141
+ if (live) for (const card of cancelled) hub.push(live, 'tool', permissionView(card, { name: nameOf(t) }))
142
+ return cancelled
143
+ }
144
+ // A fix that ended without its machine (it went away, was revoked, or the
145
+ // server restarted): the comment is not left "working" under a claim
146
+ // nobody holds. It needs a person; the claim ends with its usage record.
147
+ // `status`: where the comment stands ("branch-ready" when the fix left a branch).
148
+ function releaseFix(t, row, status = 'needs-human') {
149
+ if (row.kind !== 'fix' || !row.comment_number) return
150
+ const at = now().toISOString()
151
+ // Bound to this turn's own claim: when that claim is over already (the
152
+ // comment was taken again since, by another fix), this write is stale
153
+ // and changes nothing.
154
+ const claim = t.get('SELECT claim_id FROM agent_runs WHERE workspace_id = :ws AND id = :run', { run: row.run_id })?.claim_id || null
155
+ if (!claim) return
156
+ const ended = t.run('UPDATE agent_claims SET ended_at = :at WHERE workspace_id = :ws AND id = :claim AND ended_at IS NULL', {
157
+ claim,
158
+ at,
159
+ })
160
+ if (!Number(ended.changes)) return
161
+ t.run(
162
+ `UPDATE comments SET agent_status = :status, agent_status_at = :at WHERE workspace_id = :ws AND project_id = :project
163
+ AND board_id = :board AND number = :number AND status = 'open' AND agent_status IN ('queued', 'working')`,
164
+ { project: row.project_id, board: row.board_id, number: row.comment_number, at, status },
165
+ )
166
+ }
167
+ // The machine took the fix: the comment says "working", while this turn's claim is the open one.
168
+ function workingFix(t, row) {
169
+ if (row.kind !== 'fix' || !row.comment_number) return
170
+ const claim = t.get('SELECT claim_id FROM agent_runs WHERE workspace_id = :ws AND id = :run', { run: row.run_id })?.claim_id || null
171
+ if (!claim || !t.get('SELECT 1 AS x FROM agent_claims WHERE workspace_id = :ws AND id = :claim AND ended_at IS NULL', { claim })) return
172
+ t.run(
173
+ `UPDATE comments SET agent_status = 'working', agent_status_at = :at WHERE workspace_id = :ws AND project_id = :project
174
+ AND board_id = :board AND number = :number AND status = 'open' AND agent_status = 'queued'`,
175
+ { project: row.project_id, board: row.board_id, number: row.comment_number, at: now().toISOString() },
176
+ )
177
+ }
178
+ // "An agent came or went", for the boards of its project: at most once
179
+ // every few seconds per agent, however fast its link flaps. The last
180
+ // change always goes out (a trailing publish).
181
+ const changed = new Map()
182
+ const timers = new Set()
183
+ function agentChanged(workspaceId, projectId, agentId) {
184
+ const id = `${workspaceId}:${agentId}`
185
+ const publish = () => {
186
+ changed.set(id, Date.now())
187
+ // Ids only: which agent of which project.
188
+ events.publish({ type: 'agent.changed', workspace: workspaceId, project: projectId, agent: agentId })
189
+ }
190
+ const since = Date.now() - (changed.get(id) || 0)
191
+ if (since >= LINK_LIMITS.changedEveryMs) return publish()
192
+ if (changed.get(`${id}:pending`)) return
193
+ changed.set(`${id}:pending`, true)
194
+ const timer = setTimeout(() => {
195
+ timers.delete(timer)
196
+ changed.delete(`${id}:pending`)
197
+ publish()
198
+ }, LINK_LIMITS.changedEveryMs - since)
199
+ timer.unref()
200
+ timers.add(timer)
201
+ if (changed.size > 20_000) changed.clear()
202
+ }
203
+ // Link audit rows: a link that flaps writes one "connected" and one
204
+ // "disconnected" a minute, not one per attempt. True: write this one.
205
+ const audited = new Map()
206
+ function auditDue(action, agentId) {
207
+ const id = `${action}:${agentId}`
208
+ const due = Date.now() - (audited.get(id) || 0) >= LINK_LIMITS.auditEveryMs
209
+ if (due) audited.set(id, Date.now())
210
+ if (audited.size > 20_000) audited.clear()
211
+ return due
212
+ }
213
+ const close = () => {
214
+ for (const timer of timers) clearTimeout(timer)
215
+ timers.clear()
216
+ }
217
+ const notify = (workspaceId, projectId, boardId, threadId) =>
218
+ // Ids only; a private chat's id never goes to the board's room.
219
+ events.publish({
220
+ type: 'chat.turn',
221
+ workspace: workspaceId,
222
+ project: projectId,
223
+ board: boardId,
224
+ ...(threadId.startsWith('chat-') ? {} : { thread: threadId }),
225
+ })
226
+ // Ends a turn without the machine's answer. `row`: its chat_turns row.
227
+ function interrupt(t, row, { state = 'interrupted', message = INTERRUPTED_MESSAGE, agentName = null } = {}) {
228
+ const live = hub.get(row.id)
229
+ const stored = transaction(db, () => {
230
+ cancelCards(t, row, live)
231
+ const made = chatFor(t).interrupt(row, { state, message, agentName, partial: live ? partialOf(live) : null })
232
+ if (made) releaseFix(t, row)
233
+ return made
234
+ })
235
+ if (live) hub.close(live, 'done', stored ? { message: stored } : null)
236
+ if (stored) notify(row.workspace_id, row.project_id, row.board_id, row.thread_id)
237
+ return stored
238
+ }
239
+ // Every open turn of an agent that can no longer answer.
240
+ function interruptAgent(t, agent, reason) {
241
+ for (const row of chatFor(t).openTurnsOf(agent.id)) interrupt(t, row, { message: reason, agentName: agent.name })
242
+ }
243
+ // Turns whose machine went quiet with no link, or that ran too long; and
244
+ // turns a person stopped whose machine did not let go in time.
245
+ function sweep() {
246
+ // Cards nobody answered in time: expired here too, should the machine
247
+ // not say so itself. Every viewer sees it; the audit log keeps it.
248
+ for (const turn of hub.all()) {
249
+ if (!['fix', 'push'].includes(turn.kind)) continue
250
+ const t = tenant(db, turn.workspaceId)
251
+ const perms = permsFor(t)
252
+ const due = transaction(db, () => {
253
+ const rows = perms.expire(turn.id)
254
+ for (const row of rows) {
255
+ const card = perms.cardOf(row)
256
+ audit(t, {
257
+ userId: null,
258
+ tokenId: null,
259
+ shareId: null,
260
+ action: 'agent_permission_expired',
261
+ target: turn.id,
262
+ ip: null,
263
+ detail: {
264
+ project: turn.projectId,
265
+ agent: turn.agentId,
266
+ board: turn.boardId,
267
+ thread: turn.threadId,
268
+ card: row.id,
269
+ kind: card.name,
270
+ },
271
+ at: now().toISOString(),
272
+ })
273
+ }
274
+ return rows
275
+ })
276
+ for (const row of due) hub.push(turn, 'tool', permissionView(row, { name: nameOf(t) }))
277
+ }
278
+ for (const turn of hub.all()) {
279
+ if (!turn.cancel || Date.now() - (turn.cancelAt || 0) < LINK_LIMITS.stopGraceMs) continue
280
+ const t = tenant(db, turn.workspaceId)
281
+ const row = chatFor(t).turn(turn.id)
282
+ if (row) interrupt(t, row, { state: 'stopped' })
283
+ else hub.close(turn)
284
+ }
285
+ // "Linked": the process that took the turn still holds its link (a turn
286
+ // nobody took yet: the agent holds any link).
287
+ const linked = (item) =>
288
+ item.linkId ? links.holds(item.workspaceId, item.agentId, item.linkId) : Boolean(links.of(item.workspaceId, item.agentId))
289
+ for (const turn of hub.stale(linked)) {
290
+ const t = tenant(db, turn.workspaceId)
291
+ const row = chatFor(t).turn(turn.id)
292
+ if (row) interrupt(t, row)
293
+ else hub.close(turn)
294
+ }
295
+ }
296
+ // At server start nothing is running: every turn the database still calls
297
+ // queued or running was cut off by the stop, whether or not anyone opens
298
+ // its thread again. Each ends as interrupted, with its usage record.
299
+ function sweepStale() {
300
+ let ended = 0
301
+ for (const workspaceId of workspacesWithOpenTurns(db)) {
302
+ const t = tenant(db, workspaceId)
303
+ for (const row of chatFor(t).openTurns()) {
304
+ if (hub.get(row.id)) continue
305
+ if (interrupt(t, row, { message: 'The server restarted before the agent finished. Ask again.' })) ended += 1
306
+ }
307
+ }
308
+ return ended
309
+ }
310
+ return {
311
+ notify,
312
+ interrupt,
313
+ interruptAgent,
314
+ sweep,
315
+ sweepStale,
316
+ agentChanged,
317
+ auditDue,
318
+ close,
319
+ now,
320
+ permsFor,
321
+ nameOf,
322
+ cancelCards,
323
+ releaseFix,
324
+ workingFix,
325
+ }
326
+ }
327
+
328
+ const VERSION_RE = /^\d{1,4}\.\d{1,4}\.\d{1,4}(?:[-+][0-9A-Za-z.-]{1,40})?$/
329
+ const TURN_ID_RE = /^turn_[a-f0-9]{24}$/
330
+ // The name a connect process gives itself (random, per process): it tells
331
+ // a reconnect of the same process from a second process on the same token.
332
+ const LINK_ID_RE = /^[a-f0-9]{16,64}$/
333
+
334
+ // What hello may say, cleaned. What a machine says about edits, commands
335
+ // and "without asking" is its own ceiling, recorded so the board can show it
336
+ // and the approval rules can stay under it. Anything unclear reads as the
337
+ // narrowest: no approvals, no commands, nothing automatic.
338
+ export function cleanHello(body) {
339
+ const input = body && typeof body === 'object' && !Array.isArray(body) ? body : {}
340
+ if (!LINK_KINDS.includes(input.kind)) throw new HttpError(400, 'invalid_hello', `kind: ${LINK_KINDS.join(', ')}.`)
341
+ const maxTurns = input.maxTurns === undefined ? 2 : input.maxTurns
342
+ if (!Number.isInteger(maxTurns) || maxTurns < 1 || maxTurns > LINK_TURNS_MAX)
343
+ throw new HttpError(400, 'invalid_hello', `maxTurns: 1 to ${LINK_TURNS_MAX}.`)
344
+ if (input.version !== undefined && (typeof input.version !== 'string' || !VERSION_RE.test(input.version)))
345
+ throw new HttpError(400, 'invalid_hello', 'version: a version number.')
346
+ const policy = input.policy && typeof input.policy === 'object' ? input.policy : {}
347
+ const approvals = ['owner', 'admins'].includes(policy.approvals) ? policy.approvals : 'none'
348
+ const edits = approvals !== 'none'
349
+ const commands = edits
350
+ ? [
351
+ ...new Set(
352
+ (Array.isArray(policy.commands) ? policy.commands : []).filter((item) => typeof item === 'string' && item && item.length <= 200),
353
+ ),
354
+ ]
355
+ // eslint-disable-next-line no-control-regex
356
+ .filter((item) => !/[\u0000-\u001f\u007f]/.test(item))
357
+ .slice(0, 20)
358
+ : []
359
+ const auto = edits
360
+ ? ['edits', 'commands'].filter(
361
+ (kind) => Array.isArray(policy.auto) && policy.auto.includes(kind) && (kind !== 'commands' || commands.length),
362
+ )
363
+ : []
364
+ return {
365
+ kind: input.kind,
366
+ machine: typeof input.machine === 'string' ? input.machine.slice(0, 80) : null,
367
+ capabilities: {
368
+ chat: input.capabilities?.chat === true,
369
+ edits,
370
+ commands: commands.length > 0,
371
+ images: false,
372
+ version: input.version || null,
373
+ maxTurns,
374
+ policy: { audience: policy.audience === 'owner' ? 'owner' : 'server', approvals, commands, auto },
375
+ },
376
+ }
377
+ }
378
+
379
+ export function mountAgentLink(
380
+ v1,
381
+ {
382
+ db,
383
+ iso,
384
+ now,
385
+ events,
386
+ streams,
387
+ scope,
388
+ handle,
389
+ agentsFor,
390
+ agentPresence,
391
+ rateLimiter,
392
+ chatFor,
393
+ hub,
394
+ links,
395
+ chat,
396
+ auditOf,
397
+ boardContext,
398
+ policyFor,
399
+ dispatchView,
400
+ remoteItem,
401
+ contextFor,
402
+ quotaOf = null,
403
+ },
404
+ ) {
405
+ const router = express.Router()
406
+ // Only a connected agent's token: the scope, and the agent it stands for.
407
+ router.use(scope('agent'), (req, res, next) =>
408
+ req.agent ? next() : fail(res, 403, 'not_an_agent', 'This token is not an agent. Run "shapewall agent connect".'),
409
+ )
410
+ const small = express.json({ limit: '16kb' })
411
+ const batch = express.json({ limit: FRAME_LIMITS.batchBytes + 4096 })
412
+ const final = express.json({ limit: 1024 * 1024 })
413
+ const said = (req) => (action, target, detail) => auditOf(req, action, target, detail)
414
+
415
+ const linkIdOf = (req) => {
416
+ const value = String(req.headers['x-shapewall-link'] || '')
417
+ return LINK_ID_RE.test(value) ? value : null
418
+ }
419
+ // One process per agent. Another process already holds this agent's
420
+ // link: refused, with which machine and since when; or, with `takeover`,
421
+ // the other is told and closed first. The same process reconnecting
422
+ // replaces its own old stream quietly.
423
+ function onlyOne(req, linkId, takeover) {
424
+ const others = links.streamsOf(req.t.workspaceId, req.agent.id).filter((stream) => stream.linkId !== linkId)
425
+ if (!others.length) return
426
+ if (!takeover) {
427
+ const held = others[0]
428
+ throw new HttpError(
429
+ 409,
430
+ 'already_connected',
431
+ `${req.agent.name} is already connected from ${held.machine || 'another machine'} since ${held.connectedAt}. Stop "shapewall agent connect" there, or run this again with --takeover.`,
432
+ )
433
+ }
434
+ for (const stream of others) {
435
+ stream.send('bye', { reason: 'taken_over' })
436
+ stream.close('taken_over')
437
+ }
438
+ }
439
+
440
+ // This agent's own open turn, or 404 (another agent's, another project's,
441
+ // an ended one and a made-up id all look the same).
442
+ function ownTurn(req) {
443
+ const id = String(req.params.id || '')
444
+ const row = TURN_ID_RE.test(id) ? chatFor(req.t).turn(id) : null
445
+ if (!row || row.agent_id !== req.agent.id || row.project_id !== req.project.id)
446
+ throw new HttpError(404, 'unknown_turn', 'No such turn for this agent.')
447
+ return row
448
+ }
449
+ // The live turn of an open row. A row with no live turn was running when
450
+ // the server restarted: it is over.
451
+ function liveTurn(req, row) {
452
+ const live = hub.get(row.id)
453
+ if (live) return live
454
+ if (['queued', 'running'].includes(row.state)) chat.interrupt(req.t, row, { agentName: req.agent.name })
455
+ throw new HttpError(410, 'turn_ended', 'This turn is over.')
456
+ }
457
+
458
+ // A turn another process of this agent took is not this one's to write in.
459
+ function notAnothers(req, live) {
460
+ const linkId = linkIdOf(req)
461
+ if (live.linkId && linkId && live.linkId !== linkId)
462
+ throw new HttpError(409, 'not_your_turn', 'Another process of this agent is answering this turn.')
463
+ }
464
+
465
+ router.post(
466
+ '/hello',
467
+ small,
468
+ handle((req, res) => {
469
+ const hello = cleanHello(req.body)
470
+ const linkId = linkIdOf(req)
471
+ if (!linkId) throw new HttpError(400, 'invalid_hello', 'Send X-Shapewall-Link: the name this process gave itself.')
472
+ // Before anything is written: a second process does not rename the machine of the first.
473
+ onlyOne(req, linkId, req.body?.takeover === true)
474
+ const agents = agentsFor(req.t)
475
+ // What the machine allows now, against what it allowed before: a change
476
+ // is audited, and a stored "always allow" it no longer backs is reset.
477
+ const row = transaction(db, () => agents.helloPolicy(req.agent, agents.hello(req.agent, hello), said(req)))
478
+ res.json({
479
+ agent: {
480
+ id: row.id,
481
+ name: row.name,
482
+ project: { id: req.project.id, name: req.project.name },
483
+ workspace: { id: req.t.workspaceId, name: req.workspaceName },
484
+ // Who may use it, as in effect now (the server's setting, narrowed
485
+ // by what this machine just said).
486
+ audience: agents.audienceOf(row).text,
487
+ },
488
+ limits: {
489
+ batchBytes: FRAME_LIMITS.batchBytes,
490
+ batchEvents: FRAME_LIMITS.batchEvents,
491
+ text: FRAME_LIMITS.text,
492
+ jobBytes: FRAME_LIMITS.jobBytes,
493
+ maxTurns: hello.capabilities.maxTurns,
494
+ queued: LINK_LIMITS.queued,
495
+ keepaliveMs: LINK_LIMITS.keepaliveMs,
496
+ lostMs: TURN_LIMITS.lostMs,
497
+ },
498
+ })
499
+ }),
500
+ )
501
+
502
+ router.get('/link', (req, res) => {
503
+ const linkId = linkIdOf(req)
504
+ if (!linkId) return fail(res, 400, 'invalid_link', 'Send X-Shapewall-Link: the name this process gave itself.')
505
+ if (links.count() >= LINK_LIMITS.streams) return fail(res, 429, 'stream_budget', 'Too many agents are connected to this server.')
506
+ // A link that opens over and over is held back: each open is a write.
507
+ const opens = rateLimiter.hit('agentLinkOpen', req.token.id, LIMITS.agentLinkOpen)
508
+ if (!opens.ok) {
509
+ res.setHeader('Retry-After', String(opens.retryAfter))
510
+ return fail(res, 429, 'rate_limited', 'This agent reconnects too often. It may try again in a moment.')
511
+ }
512
+ try {
513
+ onlyOne(req, linkId, req.query.takeover === '1')
514
+ } catch (error) {
515
+ return fail(res, error.statusCode || 409, error.code || 'already_connected', error.message)
516
+ }
517
+ // The same process again (it reconnected before its old stream was noticed gone).
518
+ for (const old of links.streamsOf(req.t.workspaceId, req.agent.id)) old.close('replaced')
519
+ res.setHeader('Content-Type', 'text/event-stream')
520
+ res.setHeader('X-Accel-Buffering', 'no')
521
+ res.flushHeaders()
522
+ const { workspaceId } = req.t
523
+ const agent = req.agent
524
+ let closed = false
525
+ let timer
526
+ let unsubscribe = () => {}
527
+ const write = (text) => {
528
+ if (closed) return
529
+ // A reader that stopped reading does not get to fill this process.
530
+ if (!res.write(text)) close('slow')
531
+ }
532
+ const stream = {
533
+ tokenId: req.token.id,
534
+ linkId,
535
+ machine: req.agent.machine || null,
536
+ connectedAt: iso(),
537
+ send: (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
538
+ close: (reason) => close(reason),
539
+ }
540
+ function close(reason = 'closed') {
541
+ if (closed) return
542
+ closed = true
543
+ clearInterval(timer)
544
+ unsubscribe()
545
+ streams.delete(check)
546
+ const left = links.remove(workspaceId, agent.id, stream)
547
+ res.end()
548
+ // A fresh handle: this runs long after the request's own.
549
+ const t = tenant(db, workspaceId)
550
+ if (!left) agentPresence?.gone(workspaceId, agent.id)
551
+ // Always said when it matters (revoked, taken over); a flapping link is said once a minute.
552
+ if (['revoked', 'taken_over'].includes(reason) || chat.auditDue('agent_link_disconnected', agent.id))
553
+ auditOf(req, 'agent_link_disconnected', agent.id, { project: req.project.id, name: agent.name, reason }, t)
554
+ // A revoked agent answers nothing more: what it was answering ends now.
555
+ if (reason === 'revoked' && !left) chat.interruptAgent(t, agent, `${agent.name} was revoked before it finished.`)
556
+ chat.agentChanged(workspaceId, req.project.id, agent.id)
557
+ }
558
+ const check = (force = false) => {
559
+ if (force) return close('shutdown')
560
+ if (!findApiToken(db, req.tokenHash, iso())) close('revoked')
561
+ }
562
+ check.tokenId = req.token.id
563
+ check.workspaceId = workspaceId
564
+ streams.add(check)
565
+ links.add(workspaceId, agent.id, stream)
566
+ agentsFor(req.t).seen(agent)
567
+ const caps = agentsFor(req.t).linkView(agent)
568
+ if (chat.auditDue('agent_link_connected', agent.id) || req.query.takeover === '1')
569
+ auditOf(req, 'agent_link_connected', agent.id, {
570
+ project: req.project.id,
571
+ name: agent.name,
572
+ kind: agent.kind,
573
+ machine: agent.machine || null,
574
+ version: caps.version || null,
575
+ ...(req.query.takeover === '1' ? { takeover: true } : {}),
576
+ })
577
+ chat.agentChanged(workspaceId, req.project.id, agent.id)
578
+ unsubscribe = events.subscribe((event) => {
579
+ if (event.type === 'close') return close('shutdown')
580
+ if (closed || event.workspace !== workspaceId || event.project !== req.project.id) return
581
+ // Comments changed: the agent looks for work sent to it. Chat and
582
+ // agent events are not its business (its own turns come as `work`).
583
+ if (/^(chat|agent)\./.test(event.type)) return
584
+ stream.send('change', { type: event.type, board: event.board || null })
585
+ })
586
+ timer = setInterval(() => {
587
+ check()
588
+ if (closed) return
589
+ write(': keepalive\n\n')
590
+ agentsFor(tenant(db, workspaceId)).seen(agent)
591
+ }, LINK_LIMITS.keepaliveMs)
592
+ timer.unref()
593
+ write(': connected\n\n')
594
+ // Turns that waited for it (it was reconnecting): here they are.
595
+ for (const row of chatFor(req.t).openTurnsOf(agent.id)) if (hub.get(row.id)) stream.send('work', { turn: row.id })
596
+ res.once('close', () => close('closed'))
597
+ })
598
+
599
+ router.get(
600
+ '/work',
601
+ handle((req, res) => {
602
+ const turns = []
603
+ for (const row of chatFor(req.t).openTurnsOf(req.agent.id)) {
604
+ const live = hub.get(row.id)
605
+ // Open in the database, gone from memory: the server restarted.
606
+ if (!live) {
607
+ chat.interrupt(req.t, row, { agentName: req.agent.name })
608
+ continue
609
+ }
610
+ // `mine`: this process took it (it fetched its job). Another process's turn is not this one's to end.
611
+ const mine = !live.linkId || live.linkId === linkIdOf(req)
612
+ if (mine) hub.heard(live)
613
+ // Answers a person gave while this machine was reconnecting.
614
+ const answers = mine
615
+ ? chat
616
+ .permsFor(req.t)
617
+ .ofTurn(row.id)
618
+ .filter((card) => ['approved', 'denied'].includes(card.state) && card.answered_by)
619
+ .slice(-20)
620
+ .map((card) => answerFrame(req, card))
621
+ : []
622
+ turns.push({ id: row.id, state: live.state, cancel: live.cancel, ack: live.acked, mine, ...(answers.length ? { answers } : {}) })
623
+ }
624
+ res.json({ turns })
625
+ }),
626
+ )
627
+
628
+ router.get(
629
+ '/turns/:id',
630
+ handle((req, res) => {
631
+ const row = ownTurn(req)
632
+ const live = liveTurn(req, row)
633
+ const agents = agentsFor(req.t)
634
+ const ctx = boardContext(req.t, req.project, row.board_id)
635
+ const store = chatFor(req.t)
636
+ const rows = req.t.all(
637
+ 'SELECT * FROM chat_messages WHERE workspace_id = :ws AND project_id = :project AND board_id = :board AND thread_id = :thread ORDER BY created_at, rowid',
638
+ { project: req.project.id, board: row.board_id, thread: row.thread_id },
639
+ )
640
+ const person = row.started_by
641
+ ? req.t.get(
642
+ 'SELECT u.handle, u.display_name FROM memberships m JOIN users u ON u.id = m.user_id WHERE m.workspace_id = :ws AND m.user_id = :user',
643
+ {
644
+ user: row.started_by,
645
+ },
646
+ )
647
+ : null
648
+ const job = buildJob({
649
+ ctx,
650
+ turn: row,
651
+ agent: req.agent,
652
+ rows,
653
+ // The same rule as sending it a comment: in its audience, and
654
+ // trusted by the project's agent policy.
655
+ inAudience: (userId) =>
656
+ Boolean(userId) && agents.inAudience(req.agent, userId) && agents.trusted(req.project.id, row.board_id, userId),
657
+ asker: {
658
+ name: person?.display_name || null,
659
+ handle: person?.handle || null,
660
+ owner: Boolean(row.started_by) && row.started_by === req.agent.created_by,
661
+ },
662
+ // The approval rule in effect, per kind ("auto" only where this
663
+ // agent's machine said so itself; the machine checks again).
664
+ approvals: agents.approvalRules(req.agent),
665
+ // A comment reaches this agent only when the person asking wrote it,
666
+ // or the agent holds it, or its author is in the agent's audience
667
+ // and the token API would show it to this agent's token (sent to an
668
+ // agent, and not to another one). Never a guest's, an imported one
669
+ // or another agent's.
670
+ commentVisible: (comment) => {
671
+ let stored
672
+ try {
673
+ stored = ctx.comments.get(comment.id)
674
+ } catch {
675
+ return false
676
+ }
677
+ if (stored.author_share_id || !stored.author_user_id) return false
678
+ if (row.started_by && stored.author_user_id === row.started_by) return true
679
+ if (agents.holds(req.agent, req.project.id, stored)) return true
680
+ if (!agents.inAudience(req.agent, stored.author_user_id) || !agents.trusted(req.project.id, row.board_id, stored.author_user_id))
681
+ return false
682
+ return (
683
+ policyFor(req.t).state(req.project.id, ctx.board.id, { ...stored, status: 'open' }).dispatchable &&
684
+ agents.workCheck(req.agent, req.project.id, stored).ok
685
+ )
686
+ },
687
+ // The thread's comment as this token reads it: never a guest's, its
688
+ // replies only from people in the agent's audience, and no file URLs.
689
+ commentItem: (number) => {
690
+ let comment
691
+ try {
692
+ comment = rowToComment(ctx.comments.get(number))
693
+ } catch {
694
+ return null
695
+ }
696
+ if (comment.authorGuest) return null
697
+ const item = remoteItem(req, ctx, contextFor(ctx), dispatchView(req.t, req.project.id, ctx.board.id, comment))
698
+ // No file URLs: nothing is downloaded for a chat turn.
699
+ delete item.files
700
+ for (const reply of item.replies || []) {
701
+ delete reply.images
702
+ delete reply.markup
703
+ }
704
+ return item
705
+ },
706
+ })
707
+ if (Buffer.byteLength(JSON.stringify(job)) > FRAME_LIMITS.jobBytes)
708
+ throw new HttpError(413, 'job_too_large', 'This conversation is too large to send to the agent. Start a new chat.')
709
+ // The process that fetches the job is the one that answers it.
710
+ if (live.linkId && live.linkId !== linkIdOf(req))
711
+ throw new HttpError(409, 'not_your_turn', 'Another process of this agent is answering this turn.')
712
+ live.linkId = linkIdOf(req)
713
+ if (live.state === 'queued') {
714
+ live.state = 'running'
715
+ transaction(db, () => {
716
+ store.setRunning(row.id)
717
+ chat.workingFix(req.t, row)
718
+ })
719
+ }
720
+ hub.heard(live)
721
+ res.json({ job })
722
+ }),
723
+ )
724
+
725
+ router.post(
726
+ '/turns/:id/events',
727
+ batch,
728
+ handle((req, res) => {
729
+ const row = ownTurn(req)
730
+ const live = liveTurn(req, row)
731
+ notAnothers(req, live)
732
+ const seq = req.body?.seq
733
+ const list = req.body?.events
734
+ if (!Number.isSafeInteger(seq) || seq < 1) throw new HttpError(400, 'invalid_batch', 'seq: a whole number from 1.')
735
+ if (!Array.isArray(list) || list.length > FRAME_LIMITS.batchEvents)
736
+ throw new HttpError(400, 'invalid_batch', `events: at most ${FRAME_LIMITS.batchEvents} in a batch.`)
737
+ hub.heard(live)
738
+ // A repeat (the machine did not hear our answer) is acknowledged and dropped.
739
+ if (seq <= live.acked) return res.json({ ack: live.acked, cancel: live.cancel })
740
+ if (seq !== live.acked + 1) {
741
+ res.status(409).json({ error: { code: 'sequence_gap', message: 'A batch is missing.' }, expected: live.acked + 1 })
742
+ return
743
+ }
744
+ for (const item of list) {
745
+ // A permission card: asked now, or one the machine says was settled.
746
+ if (item?.name === 'permission') {
747
+ askCard(req, row, live, item.data)
748
+ continue
749
+ }
750
+ if (item?.name === 'tool' && item.data?.kind === 'permission' && settleCard(req, row, live, item.data)) continue
751
+ const event = cleanEvent(item)
752
+ if (event) hub.push(live, event[0], event[1])
753
+ }
754
+ live.acked = seq
755
+ res.json({ ack: live.acked, cancel: live.cancel })
756
+ }),
757
+ )
758
+
759
+ router.post(
760
+ '/turns/:id/finish',
761
+ final,
762
+ handle((req, res) => {
763
+ const row = ownTurn(req)
764
+ // Already stored (our answer was lost on the way): fine.
765
+ if (!['queued', 'running'].includes(row.state)) return res.json({ ok: true, already: true })
766
+ const live = liveTurn(req, row)
767
+ notAnothers(req, live)
768
+ const reply = cleanReply(req.body?.message)
769
+ // A turn the board stopped ends as stopped, whatever the machine says.
770
+ // One thing stands: a branch that was pushed before the Stop was heard exists, and the thread says so.
771
+ const pushedAnyway = ['fix', 'push'].includes(row.kind) && reply.summary?.branch.pushed === true
772
+ if (live.cancel && reply.status === 'done' && !pushedAnyway) reply.status = 'stopped'
773
+ // Only a fix leaves a branch.
774
+ if (!['fix', 'push'].includes(row.kind) || reply.status !== 'done') delete reply.summary
775
+ const stored = transaction(db, () => {
776
+ const store = chatFor(req.t)
777
+ const perms = chat.permsFor(req.t)
778
+ chat.cancelCards(req.t, row, live)
779
+ // The cards that were asked on the board are the server's record of
780
+ // them (who answered, how), never the machine's account.
781
+ const name = chat.nameOf(req.t)
782
+ const asked = new Map(perms.ofTurn(row.id).map((card) => [card.id, card]))
783
+ reply.cards = reply.cards.map((card) =>
784
+ card.kind === 'permission' && asked.has(card.id)
785
+ ? { ...permissionView(asked.get(card.id), { name }), ...(card.at !== undefined ? { at: card.at } : {}) }
786
+ : card,
787
+ )
788
+ // And every one of them is in the stored answer, whether the machine's
789
+ // answer lists it or not ("Push this fix" is the machine's own card,
790
+ // not the agent's): what was asked and how it ended is part of the thread.
791
+ const listed = new Set(reply.cards.map((card) => card.id))
792
+ for (const card of asked.values()) if (!listed.has(card.id)) reply.cards.push(permissionView(card, { name }))
793
+ const state = reply.status === 'done' ? 'done' : reply.status === 'stopped' ? 'stopped' : 'error'
794
+ if (!store.endTurn(row, state, { ...usageOf(reply), approvals: ['fix', 'push'].includes(row.kind) ? perms.counts(row.id) : null }))
795
+ return null
796
+ // A finished fix leaves its comment where it stands at once, should the
797
+ // machine go away before it says so itself (it posts its reply next).
798
+ chat.releaseFix(req.t, row, reply.summary ? 'branch-ready' : 'needs-human')
799
+ if (reply.summary) {
800
+ const detail = {
801
+ project: row.project_id,
802
+ agent: req.agent.id,
803
+ agentName: req.agent.name,
804
+ board: row.board_id,
805
+ comment: row.comment_number,
806
+ }
807
+ // As the agent's machine reported it: the server sees no repository.
808
+ said(req)('agent_fix_branch_ready', row.id, { ...detail, branch: reply.summary.branch.name, files: reply.summary.files.length })
809
+ if (reply.summary.branch.pushed)
810
+ said(req)('agent_branch_pushed', row.id, { ...detail, branch: reply.summary.branch.name, remote: reply.summary.branch.remote })
811
+ if (reply.summary.pr)
812
+ said(req)('agent_pull_request_opened', row.id, { ...detail, branch: reply.summary.branch.name, url: reply.summary.pr.url })
813
+ }
814
+ return store.append(row.project_id, row.board_id, row.thread_id, {
815
+ role: 'assistant',
816
+ agentId: req.agent.id,
817
+ turnId: row.id,
818
+ body: { ...reply, agent: { id: req.agent.id, name: req.agent.name } },
819
+ })
820
+ })
821
+ hub.close(live, 'done', stored ? { message: stored } : null)
822
+ chat.notify(req.t.workspaceId, row.project_id, row.board_id, row.thread_id)
823
+ res.json({ ok: true })
824
+ }),
825
+ )
826
+
827
+ // ---- Permission cards ----
828
+
829
+ // An answer as the machine hears it. `by.owner`: the person who connected
830
+ // this agent answered (a machine set to "owner" takes no other "allow").
831
+ const answerFrame = (req, card) => ({
832
+ turn: card.turn_id,
833
+ card: card.id,
834
+ decision: card.state === 'approved' ? 'allow' : 'deny',
835
+ hash: card.card_hash,
836
+ by: { owner: Boolean(card.answered_by) && card.answered_by === req.agent.created_by },
837
+ })
838
+ const auditCard = (req, action, row, card, extra = {}) =>
839
+ said(req)(action, row.id, {
840
+ project: row.project_id,
841
+ agent: req.agent.id,
842
+ agentName: req.agent.name,
843
+ board: row.board_id,
844
+ thread: row.thread_id,
845
+ card: card.id,
846
+ kind: card.name,
847
+ // The file an edit is about; a command only as its hash. Never content.
848
+ ...(card.name === 'edit'
849
+ ? { path: card.detail }
850
+ : card.name === 'push'
851
+ ? { branch: card.detail }
852
+ : { commandHash: cardSubjectHash(card) }),
853
+ ...extra,
854
+ })
855
+ // The machine asks: a card that waits for a person. Taken only for a fix
856
+ // of an agent whose machine takes edits, with a hash that matches what
857
+ // arrived, and within the turn's allowance. Anything else is answered
858
+ // "deny" at once (the machine is not left waiting) and shown as refused.
859
+ function askCard(req, row, live, data) {
860
+ const agents = agentsFor(req.t)
861
+ const id = typeof data?.id === 'string' && CARD_ID_RE.test(data.id) ? data.id : null
862
+ const refuse = () => {
863
+ if (id && typeof data.hash === 'string' && CARD_HASH_RE.test(data.hash))
864
+ links.send(req.t.workspaceId, req.agent.id, 'answer', {
865
+ turn: row.id,
866
+ card: id,
867
+ decision: 'deny',
868
+ hash: data.hash,
869
+ by: { owner: false },
870
+ })
871
+ const event = cleanEvent({ name: 'tool', data: { ...data, kind: 'permission', state: 'denied' } })
872
+ if (event) hub.push(live, event[0], event[1])
873
+ }
874
+ const content = cardContent(data)
875
+ if (!id || !content || agents.editMode(req.agent) === 'none') return refuse()
876
+ // Edits (and commands) in a fix; "Push this fix" in a fix or when it is asked again. Nothing in a chat.
877
+ if (!(row.kind === 'fix' || (row.kind === 'push' && content.name === 'push'))) return refuse()
878
+ if (content.name === 'execute' && !agents.machinePolicy(req.agent).commands.includes(content.detail)) return refuse()
879
+ if (cardHash(row.id, content) !== data.hash) return refuse()
880
+ // How long it waits is a length of time, counted here from now on this
881
+ // server's clock (the machine counts the same length on its own), and
882
+ // never longer than a card of its kind may wait.
883
+ const expiresAt = new Date(chat.now().getTime() + Math.min(content.ttlMs, cardTtlMax(content.name))).toISOString()
884
+ let stored = null
885
+ try {
886
+ stored = transaction(db, () => {
887
+ // A card with its diff is stored: it counts against the workspace's storage like anything else.
888
+ if (quotaOf) checkStorageQuota(req.t, Buffer.byteLength(JSON.stringify(content)), quotaOf(req.t))
889
+ const made = chat.permsFor(req.t).add(row, { card: content, hash: data.hash, expiresAt })
890
+ if (made) auditCard(req, 'agent_permission_asked', row, content)
891
+ return made
892
+ })
893
+ } catch (error) {
894
+ if (!error?.statusCode) throw error
895
+ stored = null
896
+ }
897
+ if (!stored) return refuse()
898
+ hub.push(live, 'tool', permissionView(stored, { name: chat.nameOf(req.t) }))
899
+ chat.notify(req.t.workspaceId, row.project_id, row.board_id, row.thread_id)
900
+ }
901
+ // The machine says what became of a card. True: handled here (the card is
902
+ // one the server knows, or one the machine allowed by itself under the
903
+ // "always allow" rule). False: an ordinary refused request (cleanEvent).
904
+ function settleCard(req, row, live, data) {
905
+ const perms = chat.permsFor(req.t)
906
+ const name = chat.nameOf(req.t)
907
+ const stored = typeof data?.id === 'string' ? perms.get(row.id, data.id) : null
908
+ if (stored) {
909
+ // Denied, expired or cancelled there: taken, also for a card a person
910
+ // allowed here a moment ago. The machine is the one that would act, so
911
+ // its "no" is final: an answer it took as late, or did not take, is not
912
+ // shown as "Allowed by ...", and is not counted as allowed.
913
+ // "Approved" is never taken from the machine: only a person's answer here does that.
914
+ if (['pending', 'approved'].includes(stored.state) && ['denied', 'expired', 'cancelled'].includes(data.state)) {
915
+ transaction(db, () => {
916
+ const changed =
917
+ stored.state === 'pending' ? perms.settle(row.id, stored.id, data.state) : perms.overrule(row.id, stored.id, data.state)
918
+ if (!changed) return
919
+ if (stored.state === 'approved')
920
+ auditCard(req, 'agent_permission_not_taken', row, perms.cardOf(stored), { answeredBy: stored.answered_by, became: data.state })
921
+ else if (data.state === 'expired') auditCard(req, 'agent_permission_expired', row, perms.cardOf(stored))
922
+ })
923
+ }
924
+ hub.push(live, 'tool', permissionView(perms.get(row.id, stored.id), { name }))
925
+ return true
926
+ }
927
+ // Allowed on the machine without asking: shown and counted only when
928
+ // this agent's rule here is "always allow" for that kind too.
929
+ if (data?.state !== 'approved' || row.kind !== 'fix') return false
930
+ const content = cardContent({ ...data, ttlMs: 1000 })
931
+ if (content?.name === 'push') return false
932
+ const agents = agentsFor(req.t)
933
+ if (!content || agents.approvalRules(req.agent)[content.name === 'edit' ? 'edits' : 'commands'] !== 'auto') return false
934
+ const made = transaction(db, () => {
935
+ const card = perms.add(row, { card: content, hash: cardHash(row.id, content), state: 'auto', expiresAt: chat.now().toISOString() })
936
+ if (card) auditCard(req, 'agent_permission_auto', row, content)
937
+ return card
938
+ })
939
+ if (!made) return false
940
+ hub.push(live, 'tool', permissionView(made, { name }))
941
+ return true
942
+ }
943
+
944
+ // A comment sent to this agent, taken by it (the claim is the token API's,
945
+ // unchanged): its answer streams into the comment's chat thread. The agent
946
+ // reads and answers; it posts its reply on the comment itself.
947
+ router.post(
948
+ '/turns',
949
+ small,
950
+ handle((req, res) => {
951
+ const ctx = boardContext(req.t, req.project, String(req.body?.board || ''))
952
+ const number = req.body?.comment
953
+ if (!Number.isSafeInteger(number) || number < 1) throw new HttpError(400, 'invalid_turn', 'comment: a comment number.')
954
+ const agents = agentsFor(req.t)
955
+ const made = transaction(db, () => {
956
+ const comment = ctx.comments.get(number)
957
+ if (!policyFor(req.t).state(req.project.id, ctx.board.id, { ...comment, status: 'open' }).dispatchable)
958
+ throw new HttpError(404, 'unknown_comment', 'No dispatched comment at that id.')
959
+ // Only the agent that holds the comment answers it in its thread.
960
+ if (!agents.holds(req.agent, req.project.id, comment))
961
+ throw new HttpError(403, 'claim_owner', 'Take the comment first (agent status queued).')
962
+ if (comment.author_share_id) throw new HttpError(403, 'guest_comment', 'A share link guest wrote this comment.')
963
+ const store = chatFor(req.t)
964
+ const threadId = `comment-${number}`
965
+ if (store.openTurn(req.project.id, ctx.board.id, threadId))
966
+ throw new HttpError(409, 'agent_running', 'This thread already has an answer on the way.')
967
+ if (hub.ofAgent(req.t.workspaceId, req.agent.id).length >= LINK_TURNS_MAX + LINK_LIMITS.queued)
968
+ throw new HttpError(429, 'agent_busy', 'This agent has too many turns open.')
969
+ const { created } = store.ensure(req.project.id, ctx.board.id, threadId, {
970
+ userId: comment.dispatch_by || null,
971
+ agentId: req.agent.id,
972
+ })
973
+ store.setAgent(req.project.id, ctx.board.id, threadId, req.agent.id)
974
+ if (created)
975
+ said(req)('chat_thread_created', `${ctx.board.id}/${threadId}`, { project: req.project.id, agent: req.agent.id, by: 'agent' })
976
+ const sender = comment.dispatch_by
977
+ ? req.t.get(
978
+ 'SELECT u.handle, u.display_name FROM memberships m JOIN users u ON u.id = m.user_id WHERE m.workspace_id = :ws AND m.user_id = :user',
979
+ {
980
+ user: comment.dispatch_by,
981
+ },
982
+ )
983
+ : null
984
+ const message = store.append(req.project.id, ctx.board.id, threadId, {
985
+ role: 'user',
986
+ userId: comment.dispatch_by || null,
987
+ body: {
988
+ text: `Comment #${number} was sent to ${req.agent.name}.`,
989
+ sent: { comment: number },
990
+ author: sender ? { name: sender.display_name, handle: sender.handle } : null,
991
+ },
992
+ })
993
+ const row = store.createTurn({
994
+ projectId: req.project.id,
995
+ boardId: ctx.board.id,
996
+ threadId,
997
+ agentId: req.agent.id,
998
+ kind: 'comment',
999
+ userId: comment.dispatch_by || null,
1000
+ userMessageId: message.id,
1001
+ commentNumber: number,
1002
+ })
1003
+ said(req)('agent_turn_started', row.id, {
1004
+ project: req.project.id,
1005
+ agent: req.agent.id,
1006
+ agentName: req.agent.name,
1007
+ board: ctx.board.id,
1008
+ thread: threadId,
1009
+ kind: 'comment',
1010
+ })
1011
+ return { row, message }
1012
+ })
1013
+ hub.open({
1014
+ id: made.row.id,
1015
+ workspaceId: req.t.workspaceId,
1016
+ projectId: req.project.id,
1017
+ boardId: ctx.board.id,
1018
+ threadId: made.row.thread_id,
1019
+ agentId: req.agent.id,
1020
+ kind: 'comment',
1021
+ startedBy: made.row.started_by,
1022
+ seed: [{ name: 'user', data: { message: made.message } }],
1023
+ })
1024
+ chat.notify(req.t.workspaceId, req.project.id, ctx.board.id, made.row.thread_id)
1025
+ res.status(201).json({ turn: { id: made.row.id, thread: made.row.thread_id } })
1026
+ }),
1027
+ )
1028
+
1029
+ router.use((req, res) => fail(res, 404, 'not_found', 'No such API route.'))
1030
+ v1.use('/agent', router)
1031
+ return { now }
1032
+ }