shapewall 0.3.2 → 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 (119) hide show
  1. package/CHANGELOG.md +357 -0
  2. package/NOTICE +7 -0
  3. package/README.md +50 -4
  4. package/THIRD_PARTY.md +39 -0
  5. package/dist/agent/package-lock.json +2 -2
  6. package/dist/client/assets/BoardChat-DdwBcb2N.js +27 -0
  7. package/dist/client/assets/BuzzDialog-DpUcnU6S.js +1 -0
  8. package/dist/client/assets/ChecksPanel-CngYV4yz.js +1 -0
  9. package/dist/client/assets/History-CD0saQA5.js +1 -0
  10. package/dist/client/assets/LocalSettings-MZy2baig.js +1 -0
  11. package/dist/client/assets/{Management-DmTh1-tA.js → Management-CSvZ-SHO.js} +1 -1
  12. package/dist/client/assets/QuickConnect-foLh2QUm.js +1 -0
  13. package/dist/client/assets/ShareDialog-DPWDftoL.js +2 -0
  14. package/dist/client/assets/app-update-dialog-CtiXpTRD.js +1 -0
  15. package/dist/client/assets/{circle-x-3UxAvczM.js → circle-x-CteRBtXC.js} +1 -1
  16. package/dist/client/assets/index-Cxz1UVcV.css +2 -0
  17. package/dist/client/assets/index-uUZVBYUS.js +37 -0
  18. package/dist/client/assets/play-BjRNIGSf.js +1 -0
  19. package/dist/client/assets/{refresh-cw-BRHNyCnY.js → refresh-cw-r_tZiFfB.js} +1 -1
  20. package/dist/client/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  21. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  22. package/dist/client/assets/ui-zQpn-PdL.js +41 -0
  23. package/dist/client/build-info.json +1 -1
  24. package/dist/client/index.html +4 -3
  25. package/dist/client/sw.js +2 -2
  26. package/dist/console/assets/{LocalAccountsApp-IvHd9zWN.js → LocalAccountsApp-DIdy1KnN.js} +1 -1
  27. package/dist/console/assets/{LocalConsole-DOyLou56.js → LocalConsole-DfcQztF-.js} +1 -1
  28. package/dist/console/assets/{app-update-dialog-Da46CJpv.js → app-update-dialog-ttl9lF5A.js} +1 -1
  29. package/dist/console/assets/console-OqAjD0kV.js +55 -0
  30. package/dist/console/assets/console-kvjrAArQ.css +2 -0
  31. package/dist/console/build-info.json +1 -1
  32. package/dist/console/console.html +2 -2
  33. package/docs/agent-hardening.md +192 -0
  34. package/docs/agent-recipes.md +23 -0
  35. package/docs/agent-workflow.md +5 -0
  36. package/docs/agents.md +74 -6
  37. package/docs/config.md +1 -1
  38. package/docs/deployment.md +2 -0
  39. package/docs/design-system.md +20 -15
  40. package/docs/hosted.md +815 -3
  41. package/docs/where-to-run.md +123 -0
  42. package/package.json +2 -1
  43. package/src/agent/agent-logos.js +81 -0
  44. package/src/agent/backends/acp.js +528 -25
  45. package/src/agent/branch-mode.js +17 -3
  46. package/src/agent/card-hash.js +65 -0
  47. package/src/agent/config.js +27 -2
  48. package/src/agent/context.js +41 -0
  49. package/src/agent/exec-paths.js +105 -0
  50. package/src/agent/icon-store.js +100 -0
  51. package/src/agent/identity.js +77 -0
  52. package/src/agent/owner-mcp.js +19 -3
  53. package/src/agent/routes.js +82 -22
  54. package/src/agent/run.js +14 -2
  55. package/src/agent/settings-routes.js +233 -14
  56. package/src/agent/starter/cli.js +6 -1
  57. package/src/agent/test-timing.js +14 -0
  58. package/src/agent/tools.js +4 -2
  59. package/src/agent/turn-changes.js +70 -8
  60. package/src/agent/user-settings.js +51 -3
  61. package/src/capture/element-map.js +61 -4
  62. package/src/cli/args.js +13 -0
  63. package/src/cli/commands.js +20 -5
  64. package/src/cli/help.js +36 -1
  65. package/src/hosted/admin.js +7 -0
  66. package/src/hosted/agent-approvals.js +28 -3
  67. package/src/hosted/agent-link.js +1032 -0
  68. package/src/hosted/agent-policy.js +10 -3
  69. package/src/hosted/agent-presence.js +81 -0
  70. package/src/hosted/agent-routes.js +135 -0
  71. package/src/hosted/agents.js +1199 -0
  72. package/src/hosted/app.js +94 -4
  73. package/src/hosted/board-routes.js +134 -3
  74. package/src/hosted/chat-frames.js +256 -0
  75. package/src/hosted/chat-job.js +204 -0
  76. package/src/hosted/chat-permissions.js +191 -0
  77. package/src/hosted/chat-routes.js +1009 -0
  78. package/src/hosted/chat-store.js +460 -0
  79. package/src/hosted/comment-files.js +8 -1
  80. package/src/hosted/comments.js +1 -1
  81. package/src/hosted/console-routes.js +58 -1
  82. package/src/hosted/db.js +165 -0
  83. package/src/hosted/device-routes.js +64 -8
  84. package/src/hosted/device.js +35 -4
  85. package/src/hosted/events.js +8 -6
  86. package/src/hosted/membership.js +9 -1
  87. package/src/hosted/pages.js +2 -0
  88. package/src/hosted/permissions.js +38 -0
  89. package/src/hosted/presence.js +18 -1
  90. package/src/hosted/projects.js +60 -2
  91. package/src/hosted/ratelimit.js +8 -0
  92. package/src/hosted/tenancy.js +18 -0
  93. package/src/hosted/token-api.js +118 -15
  94. package/src/hosted/token-events.js +7 -2
  95. package/src/hosted/tokens.js +24 -7
  96. package/src/hosted/turn-hub.js +152 -0
  97. package/src/mcp.js +10 -2
  98. package/src/remote/agent-connect.js +433 -0
  99. package/src/remote/agent-fix.js +611 -0
  100. package/src/remote/agent-job.js +216 -0
  101. package/src/remote/agent-link.js +904 -0
  102. package/src/remote/agent-policy-file.js +242 -0
  103. package/src/remote/credentials.js +35 -1
  104. package/src/remote/login.js +12 -2
  105. package/src/store.js +5 -0
  106. package/dist/client/assets/BoardChat-BeRp6007.js +0 -27
  107. package/dist/client/assets/BuzzDialog-CrYy48hh.js +0 -1
  108. package/dist/client/assets/ChecksPanel-CB820mhj.js +0 -1
  109. package/dist/client/assets/History-Ba909bGJ.js +0 -1
  110. package/dist/client/assets/LocalSettings-ChMi9Zir.js +0 -1
  111. package/dist/client/assets/QuickConnect-CrVweWZB.js +0 -1
  112. package/dist/client/assets/ShareDialog-DO2HhY6g.js +0 -2
  113. package/dist/client/assets/app-update-dialog-C09ODdUQ.js +0 -1
  114. package/dist/client/assets/index-BIjfZKnp.js +0 -37
  115. package/dist/client/assets/index-CXtuJi1K.css +0 -2
  116. package/dist/client/assets/shield-check-DMpniYP6.js +0 -1
  117. package/dist/client/assets/ui-mhL9gsne.js +0 -41
  118. package/dist/console/assets/console-CIBv7cXU.js +0 -55
  119. package/dist/console/assets/console-Fp4k9iyx.css +0 -2
@@ -0,0 +1,904 @@
1
+ // `shapewall agent connect`: this machine's end of a connected agent's link
2
+ // to a hosted Shapewall (the server's end: src/hosted/agent-link.js).
3
+ //
4
+ // It holds one server-sent event stream open and answers with POSTs. The
5
+ // server never reaches into this machine: every request goes out from here,
6
+ // to the one origin the person named, with the agent's own token. When the
7
+ // server says a turn waits (`work`), this fetches the job, checks it
8
+ // (agent-job.js), runs the local agent on it read-only (the ACP backend
9
+ // with `readOnly`), streams what the agent does back in numbered batches,
10
+ // and finishes with the answer.
11
+ //
12
+ // What this machine decides, whatever the server sends:
13
+ // - which program runs and where: the caller's backend, built from this
14
+ // machine's own saved agent. Nothing in a job names a command.
15
+ // - that the agent reads and answers only (the backend refuses the rest).
16
+ // - who it works for: with `policy.audience` "owner", a job the server
17
+ // labels as asked by someone else is refused here. The machine cannot
18
+ // check that label, so this narrows an honest server's audience and is
19
+ // no protection against a server that lies.
20
+ // - how many turns run at once, and for how long.
21
+ // - what leaves: the answer, with this agent's token removed from it.
22
+ //
23
+ // After any reconnect it asks the server what is open (GET /agent/work) and
24
+ // reconciles: a turn it no longer has is ended ("ask again"), a turn the
25
+ // server no longer has is stopped. Batches the server did not acknowledge
26
+ // are sent again; a repeated batch is harmless (the server drops it).
27
+
28
+ import { randomBytes } from 'node:crypto'
29
+ import { redact } from '../agent/backends/openai.js'
30
+ import { cardHash } from '../agent/card-hash.js'
31
+ import { tokensToText } from '../agent/plain-text.js'
32
+ import { runTurn } from '../agent/run.js'
33
+ import { git } from '../agent/starter/worktree.js'
34
+ import { FixRefusal, dropFixFolder, dropHeld, finishFix, heldDiff, heldSummary, prepareFix, pushFix, readHeld } from './agent-fix.js'
35
+ import { JobError, TURN_ID_RE, cleanJob, jobConversation } from './agent-job.js'
36
+ import { RemoteError, badTokenMessage, readBounded } from './remote.js'
37
+ import { ID_RE } from '../config.js'
38
+
39
+ export const LINK_DEFAULTS = {
40
+ // The server sends a keepalive every 15 seconds: quiet for this long
41
+ // means the stream is dead, whatever the socket says.
42
+ idleMs: 45_000,
43
+ backoffMinMs: 1000,
44
+ backoffMaxMs: 60_000,
45
+ batchMs: 150,
46
+ batchEvents: 100,
47
+ batchBytes: 200 * 1024,
48
+ // Events waiting for the server (it is unreachable): past this the turn stops.
49
+ pendingBytes: 2 * 1024 * 1024,
50
+ // How long a batch or the answer is retried before the turn is given up.
51
+ sendRetryMs: 60_000,
52
+ queued: 5,
53
+ commentRetryMs: 60_000,
54
+ // How long "Push this fix" waits for someone to look at the whole diff.
55
+ pushCardMs: 10 * 60_000,
56
+ }
57
+
58
+ // Errors that end the command: the token stopped working or was never an
59
+ // agent's. Everything else is retried.
60
+ export function fatalLinkError(error) {
61
+ if (!(error instanceof RemoteError)) return false
62
+ if (error.status === 401) return true
63
+ // Another process already holds this agent's link (it says which machine, since when).
64
+ if (error.status === 409 && error.code === 'already_connected') return true
65
+ return error.status === 403 && ['missing_scope', 'not_an_agent', 'forbidden'].includes(error.code)
66
+ }
67
+
68
+ const pause = (ms, signal) =>
69
+ new Promise((resolve) => {
70
+ if (signal?.aborted) return resolve()
71
+ const timer = setTimeout(done, ms)
72
+ function done() {
73
+ clearTimeout(timer)
74
+ signal?.removeEventListener('abort', done)
75
+ resolve()
76
+ }
77
+ signal?.addEventListener('abort', done, { once: true })
78
+ })
79
+
80
+ // The token API calls of the link, on one origin, with the agent's token.
81
+ // `linkId`: the name this process gives itself, sent with every call, so the
82
+ // server tells its reconnects from a second process on the same token.
83
+ export function createLinkClient({ origin, token, source = null, fetchImpl = fetch, linkId = randomBytes(16).toString('hex') }) {
84
+ async function call(method, pathname, { json, signal, limit = 4 * 1024 * 1024 } = {}) {
85
+ const response = await fetchImpl(`${origin}${pathname}`, {
86
+ method,
87
+ headers: {
88
+ Authorization: `Bearer ${token}`,
89
+ 'X-Shapewall-Link': linkId,
90
+ Accept: 'application/json',
91
+ ...(json !== undefined ? { 'Content-Type': 'application/json' } : {}),
92
+ },
93
+ body: json !== undefined ? JSON.stringify(json) : undefined,
94
+ redirect: 'error',
95
+ signal,
96
+ })
97
+ let data = null
98
+ try {
99
+ data = JSON.parse((await readBounded(response, limit)).toString('utf8'))
100
+ } catch {
101
+ data = null
102
+ }
103
+ if (!response.ok) {
104
+ if (response.status === 401) throw new RemoteError(401, data?.error?.code || 'bad_token', badTokenMessage(origin, source))
105
+ const error = new RemoteError(
106
+ response.status,
107
+ data?.error?.code || 'http_error',
108
+ String(data?.error?.message || `${method} ${pathname} failed (${response.status})`).slice(0, 300),
109
+ )
110
+ error.data = data
111
+ throw error
112
+ }
113
+ return data
114
+ }
115
+ const turn = (id) => `/api/v1/agent/turns/${encodeURIComponent(id)}`
116
+ return {
117
+ hello: (body, signal) => call('POST', '/api/v1/agent/hello', { json: body, signal }),
118
+ work: (signal) => call('GET', '/api/v1/agent/work', { signal }),
119
+ job: (id, signal) => call('GET', turn(id), { signal }),
120
+ events: (id, body, signal) => call('POST', `${turn(id)}/events`, { json: body, signal }),
121
+ finish: (id, body, signal) => call('POST', `${turn(id)}/finish`, { json: body, signal }),
122
+ openTurn: (body, signal) => call('POST', '/api/v1/agent/turns', { json: body, signal }),
123
+ // The stream itself: resolves to the response (its body is read by the caller).
124
+ link: (signal, { takeover = false } = {}) =>
125
+ fetchImpl(`${origin}/api/v1/agent/link${takeover ? '?takeover=1' : ''}`, {
126
+ headers: { Authorization: `Bearer ${token}`, 'X-Shapewall-Link': linkId, Accept: 'text/event-stream' },
127
+ redirect: 'error',
128
+ signal,
129
+ }),
130
+ }
131
+ }
132
+
133
+ // Runs until `signal` aborts (resolves) or the token stops working (throws).
134
+ //
135
+ // backend the local agent (src/agent/backends/acp.js, readOnly)
136
+ // hello { kind, machine, version, maxTurns } for the server's list
137
+ // policy { audience: 'owner' | 'server' }: this machine's own rule
138
+ // remote the token API client (src/remote/remote.js) for comments
139
+ // sent to this agent; null: chat only
140
+ export async function runAgentLink({
141
+ origin,
142
+ token,
143
+ source = null,
144
+ backend,
145
+ // The same agent started to take edits from the board (acp.js remoteEdit),
146
+ // for fixes; null: this machine reads and answers only.
147
+ editBackend = null,
148
+ // { config, env, fetchImpl }: the project a fix is made in (agent-fix.js).
149
+ fix = null,
150
+ hello,
151
+ policy: givenPolicy = {},
152
+ remote = null,
153
+ // Close a link another process holds for this agent, and take its place.
154
+ takeover = false,
155
+ signal = null,
156
+ fetchImpl = fetch,
157
+ log = () => {},
158
+ limits = {},
159
+ onReady = () => {},
160
+ }) {
161
+ const limit = { ...LINK_DEFAULTS, ...limits }
162
+ // Whatever is missing reads as the narrowest: no approvals, nothing automatic.
163
+ const policy = { audience: 'server', approvals: 'none', commands: [], auto: [], allowPaths: [], base: null, remote: null, ...givenPolicy }
164
+ if (!editBackend || !fix) policy.approvals = 'none'
165
+ const api = createLinkClient({ origin, token, source, fetchImpl })
166
+ const maxTurns = Math.min(Math.max(Number(hello.maxTurns) || 2, 1), 4)
167
+ // turn id -> { controller, done }
168
+ const running = new Map()
169
+ const waiting = []
170
+ const failedComments = new Map()
171
+ let agent = null
172
+ let stopping = false
173
+ // The error that ends the command (the token stopped working).
174
+ let fatal = null
175
+ // The server said another process took this agent's link: this one stops, cleanly.
176
+ let takenOver = false
177
+ // Only the first connect takes over; a reconnect is this same process.
178
+ let taking = Boolean(takeover)
179
+
180
+ const clean = (value) => redact(value, token)
181
+
182
+ // ---- One turn ----
183
+
184
+ async function runOne(id) {
185
+ const controller = new AbortController()
186
+ // `cards`: the permission cards of this turn that wait for an answer.
187
+ const entry = { controller, done: null, cards: new Map(), thread: null, backend }
188
+ running.set(id, entry)
189
+ // Events on their way to the server, in order.
190
+ let pending = []
191
+ let pendingBytes = 0
192
+ let seq = 0
193
+ let timer = null
194
+ let sending = Promise.resolve()
195
+ let gone = false
196
+ const stop = (reason) => {
197
+ if (!controller.signal.aborted) controller.abort(reason)
198
+ }
199
+ const push = (name, data) => {
200
+ if (gone) return
201
+ const last = pending.at(-1)
202
+ // Streamed text arrives in many small pieces: one event per batch.
203
+ if (last && last.name === name && (name === 'text' || name === 'reasoning')) last.data = { text: last.data.text + data.text }
204
+ else pending.push({ name, data })
205
+ pendingBytes += JSON.stringify(data).length
206
+ if (pendingBytes > limit.pendingBytes) return stop('link_lost')
207
+ timer ||= setTimeout(() => {
208
+ timer = null
209
+ sending = sending.then(flush)
210
+ }, limit.batchMs)
211
+ }
212
+ // Sends what is pending, one batch at a time, each until acknowledged.
213
+ async function flush() {
214
+ while (pending.length && !gone) {
215
+ const events = []
216
+ let bytes = 0
217
+ while (pending.length && events.length < limit.batchEvents) {
218
+ const size = JSON.stringify(pending[0].data).length
219
+ if (events.length && bytes + size > limit.batchBytes) break
220
+ events.push(pending.shift())
221
+ bytes += size
222
+ }
223
+ pendingBytes = Math.max(0, pendingBytes - bytes)
224
+ seq += 1
225
+ const began = Date.now()
226
+ for (let wait = 500; ; wait = Math.min(wait * 2, 5000)) {
227
+ try {
228
+ const answer = await api.events(id, { seq, events })
229
+ if (answer?.cancel) stop('stopped')
230
+ break
231
+ } catch (error) {
232
+ if (fatalLinkError(error)) {
233
+ gone = true
234
+ stop('revoked')
235
+ return
236
+ }
237
+ // The server no longer has this turn (ended, stopped, restarted): let go.
238
+ if (error instanceof RemoteError && [404, 410].includes(error.status)) {
239
+ gone = true
240
+ stop('ended')
241
+ return
242
+ }
243
+ // It expects another number: take its word and move on.
244
+ if (error instanceof RemoteError && error.status === 409 && Number.isSafeInteger(error.data?.expected)) {
245
+ const expected = error.data.expected
246
+ // Ahead of us: this batch (or its number) is already there.
247
+ if (expected > seq) {
248
+ seq = expected - 1
249
+ break
250
+ }
251
+ // Behind us: send this batch under the number it wants.
252
+ seq = expected
253
+ continue
254
+ }
255
+ if (error instanceof RemoteError && error.status >= 400 && error.status < 500 && error.status !== 429) break
256
+ if (Date.now() - began > limit.sendRetryMs) {
257
+ gone = true
258
+ stop('link_lost')
259
+ return
260
+ }
261
+ await pause(wait)
262
+ }
263
+ }
264
+ }
265
+ }
266
+ const drain = async () => {
267
+ clearTimeout(timer)
268
+ timer = null
269
+ sending = sending.then(flush)
270
+ await sending
271
+ }
272
+ const finish = async (message) => {
273
+ await drain()
274
+ if (gone) return
275
+ const began = Date.now()
276
+ for (let wait = 500; ; wait = Math.min(wait * 2, 5000)) {
277
+ try {
278
+ await api.finish(id, { seq: seq + 1, message })
279
+ return
280
+ } catch (error) {
281
+ if (error instanceof RemoteError && error.status < 500 && error.status !== 429) return
282
+ if (Date.now() - began > limit.sendRetryMs) return
283
+ await pause(wait)
284
+ }
285
+ }
286
+ }
287
+ const refused = (text, code = 'refused') => ({ text: '', cards: [], status: 'error', error: { code, message: text } })
288
+ // What the agent does, on its way to the server with this agent's token
289
+ // removed. A permission card that waits for an answer goes out at once,
290
+ // as `permission`, with the hash an answer must carry (card-hash.js). A
291
+ // card that cannot be hashed cannot be answered: it is denied here.
292
+ const emit = (name, data) => {
293
+ if (name === 'text' || name === 'reasoning') return push(name, { text: clean(data.text) })
294
+ const sent = JSON.parse(clean(JSON.stringify(data)))
295
+ if (name === 'tool' && sent?.kind === 'permission') {
296
+ if (sent.state !== 'pending') {
297
+ entry.cards.delete(sent.id)
298
+ return push('tool', sent)
299
+ }
300
+ // How long it waits, as a length of time: each end counts it on its
301
+ // own clock, so the two clocks need not agree (card-hash.js).
302
+ const ttlMs = Math.max(1000, Math.round((Date.parse(sent.expiresAt) - Date.now()) / 1000) * 1000)
303
+ const card = { ...sent, ttlMs }
304
+ delete card.expiresAt
305
+ const hash = cardHash(id, card)
306
+ if (!hash) {
307
+ setImmediate(() => entry.backend?.answerPermission(entry.thread, sent.id, 'deny'))
308
+ return
309
+ }
310
+ entry.cards.set(sent.id, { hash, expires: Date.now() + ttlMs })
311
+ push('permission', { ...card, hash })
312
+ clearTimeout(timer)
313
+ timer = null
314
+ sending = sending.then(flush)
315
+ return
316
+ }
317
+ push(name, sent)
318
+ }
319
+ // A card of this machine's own (not the agent's): shown on the board,
320
+ // answered like any other, with the same hash, expiry and recheck.
321
+ // Resolves 'approved' | 'denied' | 'expired' | 'cancelled'.
322
+ const askBoard = ({ name, label, detail, diff }, ttlMs) =>
323
+ new Promise((resolve) => {
324
+ const cardId = `perm_${randomBytes(12).toString('hex')}`
325
+ const card = JSON.parse(
326
+ clean(
327
+ JSON.stringify({
328
+ id: cardId,
329
+ kind: 'permission',
330
+ name,
331
+ label,
332
+ detail,
333
+ diff,
334
+ state: 'pending',
335
+ options: [],
336
+ chosen: null,
337
+ ttlMs,
338
+ }),
339
+ ),
340
+ )
341
+ const hash = cardHash(id, card)
342
+ if (!hash || controller.signal.aborted) return resolve(hash ? 'cancelled' : 'denied')
343
+ let waiting = null
344
+ const settle = (state) => {
345
+ if (!entry.cards.has(cardId)) return
346
+ entry.cards.delete(cardId)
347
+ clearTimeout(waiting)
348
+ controller.signal.removeEventListener('abort', onAbort)
349
+ push('tool', { ...card, state })
350
+ resolve(state)
351
+ }
352
+ const onAbort = () => settle('cancelled')
353
+ entry.cards.set(cardId, { hash, expires: Date.now() + ttlMs, settle })
354
+ waiting = setTimeout(() => settle('expired'), ttlMs)
355
+ waiting.unref?.()
356
+ controller.signal.addEventListener('abort', onAbort, { once: true })
357
+ push('permission', { ...card, hash })
358
+ clearTimeout(timer)
359
+ timer = null
360
+ sending = sending.then(flush)
361
+ })
362
+ // A fix that is held back (an edit in it went without asking): one card
363
+ // with its whole diff. Pushed only when a person allows that card.
364
+ // -> { summary, notes, line, pushed }
365
+ async function offerPush(record) {
366
+ const kept = async (note) => ({ summary: await heldSummary(record), notes: [note], line: null, pushed: false })
367
+ const hasRemote = policy.remote
368
+ ? (await git(['remote', 'get-url', policy.remote], { cwd: fix.config.dir, env: fix.env }).catch(() => '')).trim()
369
+ : ''
370
+ if (!hasRemote) {
371
+ // Nowhere to push: nothing is held back from anywhere.
372
+ dropHeld(record)
373
+ const summary = await heldSummary(record)
374
+ summary.branch.held = false
375
+ return { summary, notes: [], line: null, pushed: false }
376
+ }
377
+ const diff = await heldDiff(record)
378
+ if (!diff)
379
+ return kept("Not pushed: the fix is too large to show in full on the board. Review and push the branch on the agent's machine.")
380
+ push('status', { text: 'Waiting for someone to look at the whole diff before it is pushed' })
381
+ const state = await askBoard({ name: 'push', label: 'Push this fix', detail: record.branch, diff }, limit.pushCardMs)
382
+ if (state !== 'approved')
383
+ return kept(
384
+ `Not pushed: ${state === 'denied' ? 'the push was denied' : state === 'expired' ? 'nobody answered in time' : 'it was stopped'}. The fix is on its branch, on the agent's machine. "Push this fix" asks again.`,
385
+ )
386
+ const pushed = await pushFix({
387
+ config: fix.config,
388
+ policy,
389
+ record,
390
+ signal: controller.signal,
391
+ env: fix.env,
392
+ fetchImpl: fix.fetchImpl,
393
+ log,
394
+ })
395
+ if (pushed.pushed) dropHeld(record)
396
+ else pushed.summary.branch.held = true
397
+ return pushed
398
+ }
399
+
400
+ let job = null
401
+ // A fix: its folder (agent-fix.js), and what was allowed in it.
402
+ let prepared = null
403
+ const approved = new Map()
404
+ try {
405
+ const fetched = await api.job(id, controller.signal)
406
+ job = cleanJob(fetched?.job)
407
+ if (job.turn.id !== id) throw new JobError('The server sent another turn.')
408
+ // This machine's own rule: only the person who connected it.
409
+ if (policy.audience === 'owner' && !job.asker.owner) {
410
+ log(`turn ${id}: refused (this machine takes work from the person who connected it only)`)
411
+ await finish(
412
+ refused('This agent takes questions only from the person who connected it (set on its own machine).', 'agent_audience'),
413
+ )
414
+ if (job.turn.kind !== 'chat') await answerComment(job, null)
415
+ return
416
+ }
417
+ const fixing = job.turn.kind === 'fix'
418
+ // "Push this fix", asked again for a fix this machine holds back.
419
+ if (job.turn.kind === 'push') {
420
+ log(`turn ${id}: push the held fix of comment #${job.turn.comment} on ${job.turn.board}`)
421
+ const record =
422
+ policy.approvals === 'none' || !fix
423
+ ? null
424
+ : await readHeld({ config: fix.config, env: fix.env, board: job.turn.board, comment: job.turn.comment })
425
+ if (!record) {
426
+ await finish(refused("No fix of this comment is waiting to be pushed on the agent's machine.", 'no_held_fix'))
427
+ return
428
+ }
429
+ entry.thread = `${job.turn.board}/${job.turn.thread}`
430
+ const offered = await offerPush(record)
431
+ const stoppedNow = controller.signal.aborted && !offered.pushed
432
+ const message = JSON.parse(
433
+ clean(
434
+ JSON.stringify({
435
+ text: offered.pushed ? offered.line : '',
436
+ cards: offered.notes.map((text, index) => ({
437
+ id: `note-fix-${index + 1}`,
438
+ kind: 'note',
439
+ name: 'note',
440
+ label: String(text).slice(0, 200),
441
+ })),
442
+ status: stoppedNow ? 'stopped' : 'done',
443
+ summary: offered.summary,
444
+ }),
445
+ ),
446
+ )
447
+ await finish(message)
448
+ if (offered.pushed && remote) await remote.reply(job.turn.board, job.turn.comment, { body: offered.line }).catch(() => {})
449
+ return
450
+ }
451
+ log(
452
+ `turn ${id}: ${fixing ? `fix for comment #${job.turn.comment}` : job.turn.kind === 'comment' ? `comment #${job.turn.comment}` : 'chat'} on ${job.turn.board}`,
453
+ )
454
+ let fixTurn = {}
455
+ if (fixing) {
456
+ // This machine's own rule again: no fix unless it said so itself.
457
+ if (policy.approvals === 'none' || !editBackend || !fix) {
458
+ await finish(refused('This agent reads and answers only: its machine does not take edits from the board.', 'agent_read_only'))
459
+ await answerComment(job, null)
460
+ return
461
+ }
462
+ if (!job.context.comment) {
463
+ await finish(refused('This agent may not read that comment, so it cannot fix it.', 'agent_audience'))
464
+ await answerComment(job, null)
465
+ return
466
+ }
467
+ push('status', { text: 'Making a fresh copy of the project on a new branch' })
468
+ try {
469
+ prepared = await prepareFix({ config: fix.config, policy, job, env: fix.env })
470
+ } catch (error) {
471
+ if (!(error instanceof FixRefusal)) throw error
472
+ log(`turn ${id}: ${error.message}`)
473
+ await finish(refused(error.message, 'fix_refused'))
474
+ await answerComment(job, null, { why: error.message })
475
+ return
476
+ }
477
+ const kindOf = (kind) => (kind === 'edit' ? 'edits' : 'commands')
478
+ fixTurn = {
479
+ workdir: prepared.workdir,
480
+ gate: {
481
+ // Asked on the board, unless this machine and the server's rule both say "allow".
482
+ // On a machine that said "owner", the rule must also be the connecting person's own doing.
483
+ decide: ({ kind }) =>
484
+ job.approvals[kindOf(kind)] === 'auto' &&
485
+ policy.auto.includes(kindOf(kind)) &&
486
+ (policy.approvals !== 'owner' || job.approvals.byOwner === true)
487
+ ? 'allow'
488
+ : 'ask',
489
+ // `auto`: nobody looked at this edit (the fix is then held back from any remote).
490
+ approved: (rel, hash, { auto = false } = {}) => approved.set(rel, { hash, auto: auto || (approved.get(rel)?.auto ?? false) }),
491
+ expected: (rel) => approved.get(rel)?.hash || null,
492
+ ignored: (rel) => prepared.ignored(rel),
493
+ },
494
+ }
495
+ entry.backend = editBackend
496
+ }
497
+ entry.thread = `${job.turn.board}/${job.turn.thread}`
498
+ const reply = await runTurn({
499
+ config: null,
500
+ // The board's own store is not on this machine: the conversation is
501
+ // built from the job (agent-job.js), and no board tool runs here.
502
+ board: { id: job.turn.board, pages: [] },
503
+ threadId: job.turn.thread,
504
+ messages: [],
505
+ conversation: jobConversation(job),
506
+ backend: fixing ? editBackend : backend,
507
+ emit,
508
+ signal: controller.signal,
509
+ allowCapture: false,
510
+ agentName: job.agent.name,
511
+ ...fixTurn,
512
+ })
513
+ // Stopped from here (Ctrl+C, a lost link) reads differently from Stop on the board.
514
+ if (reply.status === 'stopped' && ['shutdown', 'link_lost'].includes(controller.signal.reason)) {
515
+ reply.status = 'error'
516
+ reply.error = { code: 'interrupted', message: "The agent's machine stopped before it finished. Ask again." }
517
+ }
518
+ let fixed = null
519
+ if (prepared) {
520
+ // The agent's session lived in the fix's folder: it ends with it.
521
+ editBackend.resetThread?.(entry.thread)
522
+ push('status', { text: 'Checking and committing the fix' })
523
+ const done = prepared
524
+ prepared = null
525
+ // A turn that was stopped, failed or allowed nothing leaves no branch.
526
+ if (reply.status !== 'done' || reply.error || !approved.size) await dropFixFolder(done)
527
+ else {
528
+ fixed = await finishFix({
529
+ config: fix.config,
530
+ policy,
531
+ prepared: done,
532
+ job,
533
+ approved,
534
+ // Stop is honoured between every step: nothing is committed, pushed or opened after it.
535
+ signal: controller.signal,
536
+ env: fix.env,
537
+ fetchImpl: fix.fetchImpl,
538
+ log,
539
+ })
540
+ if (fixed.held) {
541
+ const offered = await offerPush(fixed.held)
542
+ fixed.summary = offered.summary
543
+ fixed.notes.push(...offered.notes)
544
+ if (offered.line) fixed.line = offered.line
545
+ // Stop while it waited to be looked at: the fix is taken back, branch and all.
546
+ if (controller.signal.aborted && !offered.pushed) {
547
+ dropHeld(fixed.held)
548
+ await git(['--git-dir', fixed.held.gitDir, 'update-ref', '-d', `refs/heads/${fixed.held.branch}`, fixed.held.commit], {
549
+ cwd: fixed.held.repo,
550
+ env: fix.env,
551
+ }).catch(() => {})
552
+ fixed.status = 'stopped'
553
+ fixed.summary = null
554
+ fixed.notes.length = 0
555
+ }
556
+ }
557
+ if (fixed.status === 'stopped') reply.status = 'stopped'
558
+ else if (fixed.summary) reply.summary = fixed.summary
559
+ for (const [index, text] of fixed.notes.entries())
560
+ reply.cards.push({ id: `note-fix-${index + 1}`, kind: 'note', name: 'note', label: String(text).slice(0, 200) })
561
+ }
562
+ }
563
+ const message = JSON.parse(clean(JSON.stringify(reply)))
564
+ await finish(message)
565
+ if (job.turn.kind !== 'chat') await answerComment(job, message, { fixed })
566
+ } catch (error) {
567
+ if (fatalLinkError(error)) throw error
568
+ if (error instanceof RemoteError && [404, 410].includes(error.status)) return
569
+ log(`turn ${id}: ${error.message}`)
570
+ await finish(
571
+ refused(
572
+ error instanceof JobError ? 'This agent could not read the request the server sent.' : 'The agent could not answer. Ask again.',
573
+ ),
574
+ ).catch(() => {})
575
+ if (job && job.turn.kind !== 'chat') await answerComment(job, null).catch(() => {})
576
+ } finally {
577
+ clearTimeout(timer)
578
+ if (prepared) {
579
+ editBackend?.resetThread?.(entry.thread)
580
+ await dropFixFolder(prepared).catch(() => {})
581
+ }
582
+ running.delete(id)
583
+ next()
584
+ }
585
+ }
586
+
587
+ // A person's answer to a card, as the server relays it. It counts only for
588
+ // a card this machine asked and still waits on, with the hash of exactly
589
+ // what it asked, before the card expired, and once. An "allow" that fails
590
+ // any of that is a deny; an answer for a card that is not waiting here is
591
+ // nothing at all.
592
+ function onAnswer(data) {
593
+ const entry = running.get(String(data?.turn || ''))
594
+ const cardId = String(data?.card || '')
595
+ const card = entry?.cards.get(cardId)
596
+ if (!card) {
597
+ if (data?.turn) log(`answer for a card that is not waiting here (${cardId.slice(0, 40) || 'no id'}): ignored`)
598
+ return
599
+ }
600
+ let allow = data.decision === 'allow'
601
+ const why = !allow
602
+ ? null
603
+ : data.hash !== card.hash
604
+ ? 'it is not for what was asked'
605
+ : !(Date.now() < card.expires)
606
+ ? 'it came too late'
607
+ : policy.approvals === 'none'
608
+ ? 'this machine takes no approvals'
609
+ : policy.approvals === 'owner' && data.by?.owner !== true
610
+ ? 'only the person who connected this agent may allow'
611
+ : null
612
+ if (why) {
613
+ allow = false
614
+ log(`an "allow" was not taken: ${why}`)
615
+ }
616
+ // A card of this machine's own settles itself; the agent's go to the agent.
617
+ if (card.settle) return card.settle(allow ? 'approved' : 'denied')
618
+ entry.cards.delete(cardId)
619
+ entry.backend?.answerPermission(entry.thread, cardId, allow ? 'allow' : 'deny')
620
+ }
621
+
622
+ // The reply on a comment that was sent to this agent, and where it stands
623
+ // now: answered (done), a fix waiting on a branch, or left to a person.
624
+ // `fixed`: what a fix ended as (agent-fix.js finishFix). `why`: why a fix
625
+ // was not started.
626
+ async function answerComment(job, message, { fixed = null, why = null } = {}) {
627
+ if (!remote) return
628
+ const { board, comment } = job.turn
629
+ const fixing = job.turn.kind === 'fix'
630
+ const ok = message?.status === 'done' && !message.error && message.text?.trim()
631
+ const ready = fixing && fixed?.status === 'branch-ready'
632
+ const lines = []
633
+ // A comment shows text as typed: the chat's reference tokens become words.
634
+ if (ok) lines.push(tokensToText(message.text).slice(0, 8000))
635
+ if (fixing) {
636
+ if (ready) lines.push(fixed.line)
637
+ else if (message?.status === 'stopped') lines.push('This fix was stopped before it was finished. Nothing was committed or pushed.')
638
+ else if (why) lines.push(`I could not start this fix. ${why}`)
639
+ else if (!ok) lines.push('I could not make this fix from here. It needs a person.')
640
+ else lines.push('No change was committed.')
641
+ for (const note of fixed?.notes || []) lines.push(note)
642
+ } else if (!ok)
643
+ lines.push('I could not answer this comment from here. It needs a person, or an agent that can edit (shapewall watch --exec).')
644
+ try {
645
+ await remote.reply(board, comment, { body: lines.join('\n\n').slice(0, 9000) })
646
+ // Where a fixed comment stands is the server's to write, with the turn (a late
647
+ // write from here could land on the next fix). A comment this agent answered:
648
+ // only while it still holds it.
649
+ if (!fixing) await remote.setAgentStatus(board, comment, ok ? 'done' : 'needs-human', { onlyFrom: ['queued', 'working'] })
650
+ } catch (error) {
651
+ log(`comment #${comment}: ${error.message}`)
652
+ }
653
+ }
654
+
655
+ function start(id) {
656
+ if (!TURN_ID_RE.test(String(id || '')) || running.has(id) || waiting.includes(id)) return
657
+ if (running.size >= maxTurns) {
658
+ if (waiting.length < limit.queued) waiting.push(id)
659
+ return
660
+ }
661
+ const entry = runOne(id).catch((error) => {
662
+ if (fatalLinkError(error)) fatal = error
663
+ else log(`turn ${id}: ${error.message}`)
664
+ })
665
+ if (running.has(id)) running.get(id).done = entry
666
+ }
667
+ function next() {
668
+ while (!stopping && waiting.length && running.size < maxTurns) start(waiting.shift())
669
+ }
670
+ // ---- Reconcile after a (re)connect ----
671
+
672
+ async function reconcile(signalNow) {
673
+ const { turns = [] } = (await api.work(signalNow)) || {}
674
+ const open = new Set()
675
+ for (const turn of Array.isArray(turns) ? turns : []) {
676
+ if (!TURN_ID_RE.test(String(turn?.id || ''))) continue
677
+ open.add(turn.id)
678
+ if (running.has(turn.id)) {
679
+ if (turn.cancel) running.get(turn.id).controller.abort('stopped')
680
+ // Answers given while the link was down.
681
+ for (const answer of Array.isArray(turn.answers) ? turn.answers.slice(0, 20) : []) onAnswer({ ...answer, turn: turn.id })
682
+ continue
683
+ }
684
+ // Queued: ours to start. Running without us: this process restarted
685
+ // mid-answer and cannot pick it up; say so, so the person asks again.
686
+ if (turn.state === 'queued' && !turn.cancel) start(turn.id)
687
+ // Another process's turn (before a takeover, say) is not this one's to end.
688
+ else if (turn.mine === false) continue
689
+ else
690
+ await api
691
+ .finish(turn.id, {
692
+ seq: (Number(turn.ack) || 0) + 1,
693
+ message: {
694
+ text: '',
695
+ cards: [],
696
+ status: turn.cancel ? 'stopped' : 'error',
697
+ ...(turn.cancel
698
+ ? {}
699
+ : { error: { code: 'interrupted', message: "The agent's machine restarted before it finished. Ask again." } }),
700
+ },
701
+ })
702
+ .catch(() => {})
703
+ }
704
+ // A turn the server no longer has is over here too.
705
+ for (const [id, entry] of running) if (!open.has(id)) entry.controller.abort('ended')
706
+ }
707
+
708
+ // ---- Comments sent to this agent ----
709
+
710
+ let scanning = false
711
+ let scanAgain = false
712
+ async function scanComments() {
713
+ if (!remote || !agent || stopping) return
714
+ if (scanning) {
715
+ scanAgain = true
716
+ return
717
+ }
718
+ scanning = true
719
+ try {
720
+ const project = await remote.project()
721
+ for (const board of (project?.boards || []).slice(0, 50)) {
722
+ if (!ID_RE.test(String(board?.id || ''))) continue
723
+ const report = await remote.comments(board.id, { status: 'open' })
724
+ for (const item of report?.comments || []) {
725
+ const id = item?.id
726
+ if (!Number.isSafeInteger(id) || id < 1) continue
727
+ // Only a comment sent to this agent by name: "any agent" work
728
+ // stays with the watchers that can fix it.
729
+ if (!item.dispatchable || item.agentStatus || item.authorGuest || item.agentId !== agent.id) continue
730
+ const key = `${board.id}#${id}`
731
+ if (Date.now() - (failedComments.get(key) || 0) < limit.commentRetryMs) continue
732
+ if (running.size + waiting.length >= maxTurns + limit.queued) return
733
+ try {
734
+ const taken = await remote.setAgentStatus(board.id, id, 'queued', { onlyFrom: [null] })
735
+ if (!taken?.changed) continue
736
+ const opened = await api.openTurn({ board: board.id, comment: id })
737
+ await remote.setAgentStatus(board.id, id, 'working', { onlyFrom: ['queued'] }).catch(() => {})
738
+ start(opened?.turn?.id)
739
+ } catch (error) {
740
+ if (fatalLinkError(error)) throw error
741
+ failedComments.set(key, Date.now())
742
+ log(`comment #${id}: ${error.message}`)
743
+ }
744
+ }
745
+ }
746
+ } catch (error) {
747
+ if (fatalLinkError(error)) fatal = error
748
+ else log(`comments: ${error.message}`)
749
+ } finally {
750
+ scanning = false
751
+ if (scanAgain && !stopping) {
752
+ scanAgain = false
753
+ scanComments()
754
+ }
755
+ }
756
+ }
757
+
758
+ // ---- The stream ----
759
+
760
+ async function connectOnce() {
761
+ const controller = new AbortController()
762
+ let reader = null
763
+ // Native fetch can lose an abort while a stream read is pending: the
764
+ // reader is cancelled as well as the request (as waitForChange does).
765
+ const hangUp = () => {
766
+ controller.abort()
767
+ Promise.resolve(reader?.cancel()).catch(() => {})
768
+ }
769
+ const onAbort = () => hangUp()
770
+ signal?.addEventListener('abort', onAbort, { once: true })
771
+ let idle = null
772
+ const touch = () => {
773
+ clearTimeout(idle)
774
+ idle = setTimeout(hangUp, limit.idleMs)
775
+ }
776
+ try {
777
+ const said = await api.hello(
778
+ {
779
+ ...hello,
780
+ maxTurns,
781
+ capabilities: {
782
+ chat: true,
783
+ edits: policy.approvals !== 'none',
784
+ commands: policy.approvals !== 'none' && policy.commands.length > 0,
785
+ },
786
+ // What this machine allows, for the board to show. The server can only narrow it.
787
+ policy: { audience: policy.audience, approvals: policy.approvals, commands: policy.commands, auto: policy.auto },
788
+ ...(taking ? { takeover: true } : {}),
789
+ },
790
+ controller.signal,
791
+ )
792
+ agent = said?.agent && typeof said.agent.id === 'string' ? said.agent : null
793
+ if (!agent) throw new Error('The server did not say which agent this is.')
794
+ touch()
795
+ const response = await api.link(controller.signal, { takeover: taking })
796
+ if (response.status === 401) throw new RemoteError(401, 'bad_token', badTokenMessage(origin, source))
797
+ if (!response.ok || !String(response.headers.get('content-type')).includes('text/event-stream')) {
798
+ let data = null
799
+ try {
800
+ data = JSON.parse((await readBounded(response, 65536)).toString('utf8'))
801
+ } catch {
802
+ data = null
803
+ }
804
+ throw new RemoteError(
805
+ response.status,
806
+ data?.error?.code || 'http_error',
807
+ String(data?.error?.message || `The link was refused (${response.status}).`).slice(0, 300),
808
+ )
809
+ }
810
+ reader = response.body.getReader()
811
+ taking = false
812
+ onReady(said)
813
+ await reconcile(controller.signal)
814
+ scanComments()
815
+ const decoder = new TextDecoder()
816
+ let buffer = ''
817
+ for (;;) {
818
+ const { value, done } = await reader.read()
819
+ if (done) return
820
+ touch()
821
+ buffer += decoder.decode(value, { stream: true })
822
+ // One event is small: a stream that never ends a block is not ours.
823
+ if (buffer.length > 65536) return
824
+ let index
825
+ while ((index = buffer.indexOf('\n\n')) >= 0) {
826
+ const block = buffer.slice(0, index)
827
+ buffer = buffer.slice(index + 2)
828
+ const name = /^event: (.*)$/m.exec(block)?.[1]
829
+ const raw = /^data: (.*)$/m.exec(block)?.[1]
830
+ if (!name || raw === undefined) continue
831
+ let data
832
+ try {
833
+ data = JSON.parse(raw)
834
+ } catch {
835
+ continue
836
+ }
837
+ if (name === 'work') start(data?.turn)
838
+ else if (name === 'cancel') running.get(String(data?.turn || ''))?.controller.abort('stopped')
839
+ else if (name === 'answer') onAnswer(data)
840
+ else if (name === 'change') scanComments()
841
+ else if (name === 'bye') {
842
+ takenOver = true
843
+ return
844
+ }
845
+ }
846
+ if (fatal) throw fatal
847
+ }
848
+ } finally {
849
+ clearTimeout(idle)
850
+ signal?.removeEventListener('abort', onAbort)
851
+ controller.abort()
852
+ try {
853
+ await reader?.cancel()
854
+ } catch {
855
+ /* already closed */
856
+ }
857
+ }
858
+ }
859
+
860
+ let wait = limit.backoffMinMs
861
+ let held = 0
862
+ try {
863
+ while (!signal?.aborted) {
864
+ const began = Date.now()
865
+ try {
866
+ await connectOnce()
867
+ if (fatal) throw fatal
868
+ if (takenOver) break
869
+ if (!signal?.aborted) log('link closed by the server; reconnecting')
870
+ } catch (error) {
871
+ // "Already connected" right after another process stopped: the server
872
+ // may not have noticed its closed stream yet. A few tries, a second
873
+ // apart, before taking its word that another machine holds the link.
874
+ if (error?.code === 'already_connected' && held < 4 && !signal?.aborted) {
875
+ held += 1
876
+ await pause(1000, signal)
877
+ continue
878
+ }
879
+ if (fatalLinkError(error)) throw error
880
+ if (signal?.aborted) break
881
+ log(`link: ${error.name === 'AbortError' ? 'no word from the server; reconnecting' : `${error.message}; reconnecting`}`)
882
+ }
883
+ if (signal?.aborted) break
884
+ // A link that held for a while starts the backoff over.
885
+ if (Date.now() - began > 30_000) wait = limit.backoffMinMs
886
+ await pause(wait * (0.5 + Math.random() / 2), signal)
887
+ wait = Math.min(wait * 2, limit.backoffMaxMs)
888
+ }
889
+ } finally {
890
+ stopping = true
891
+ waiting.length = 0
892
+ for (const entry of running.values()) entry.controller.abort('shutdown')
893
+ // Each turn posts what it has (a stopped answer) before this returns.
894
+ let timer
895
+ await Promise.race([
896
+ Promise.allSettled([...running.values()].map((entry) => entry.done)),
897
+ new Promise((resolve) => {
898
+ timer = setTimeout(resolve, 8000)
899
+ }),
900
+ ])
901
+ clearTimeout(timer)
902
+ }
903
+ return { takenOver }
904
+ }