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
@@ -73,10 +73,12 @@ import { createAgentHealth } from './agent-health.js'
73
73
  import { beginAgentOperation } from './control.js'
74
74
  import { validateFiles, validateMentions } from './composer.js'
75
75
  import { profileForDefault, userAgentEntry, userSettingsFile } from './user-settings.js'
76
+ import { uploadHashes } from './identity.js'
77
+ import { readIcon } from './icon-store.js'
76
78
  import { finishFix, projectChanged, projectSnapshot, stopReason } from './feedback-loop.js'
77
79
  import { ownerMcpServers } from './owner-mcp.js'
78
80
  import { RUN_MS_MAX, commentIdOf, runTurn } from './run.js'
79
- import { beginTurnChanges, finishTurnChanges, starterSummary, undoFiles, undoStarterBranch } from './turn-changes.js'
81
+ import { beginTurnChanges, finishTurnChanges, ignoredPaths, starterSummary, undoFiles, undoStarterBranch } from './turn-changes.js'
80
82
  import { latestChange, withUndoAvailability } from './undo-state.js'
81
83
  import { exportRatings, findAnswer, myRatings, raterOf, removeRating, reviewRatings, setRating } from './ratings.js'
82
84
  import { localRequest, sameOriginWrite, settingsRoutes, settingsTokenOk } from './settings-routes.js'
@@ -110,6 +112,8 @@ import { commentText } from '../comment-fields.js'
110
112
  // body this big, and only once the message is allowed to run.
111
113
  export const BODY_LIMIT = '28mb'
112
114
  const SMALL_BODY_LIMIT = '4kb'
115
+ // An uploaded agent icon: 512 KiB of PNG at most (src/accounts/avatar.js), in base64.
116
+ const ICON_BODY_LIMIT = '700kb'
113
117
  // Open GET /events streams at once; a new one ends the oldest.
114
118
  export const EVENT_STREAMS_MAX = 32
115
119
 
@@ -242,7 +246,19 @@ export function agentRouter({
242
246
  }
243
247
  // How each agent is doing (agent-health.js): from the last turn or test.
244
248
  const health = createAgentHealth()
245
- const agentStatus = (current) => health.status(current, processPool)
249
+ // While an agent's connection test runs (settings-routes.js) its state is
250
+ // "testing": the chat header says so instead of "Ready".
251
+ const testedNow = (current) => {
252
+ const test = connectionTest()
253
+ if (!test) return false
254
+ if (current.profileId) return test.id === current.profileId
255
+ const runs = current.defaultProfile || profileForDefault(userAgentEntry(config.dir, env).entry)?.id || 'default'
256
+ return test.id === 'default' || test.id === runs
257
+ }
258
+ const agentStatus = (current) => {
259
+ const status = health.status(current, processPool)
260
+ return testedNow(current) ? { ...status, state: 'testing' } : status
261
+ }
246
262
  router.health = health
247
263
  const profiles = () => {
248
264
  const saved = userAgentEntry(config.dir, env)
@@ -284,9 +300,13 @@ export function agentRouter({
284
300
  'control_needs_owner',
285
301
  'This agent can run commands on this computer, so only its owner can use it. Open the private owner link from the terminal (or run shapewall serve --open), or use a paired device.',
286
302
  )
303
+ // What makes a backend the same one: everything but the agent's name,
304
+ // icon and tint (identity.js), which are display only. Renaming an agent
305
+ // must not stop its processes.
306
+ const fingerprintOf = (current) => JSON.stringify({ ...current, label: null, icon: null, tint: null })
287
307
  const backendFor = (current, ownerWrites = false) => {
288
308
  const key = JSON.stringify({ profileId: current.profileId || 'default', ownerWrites })
289
- const fingerprint = JSON.stringify(current)
309
+ const fingerprint = fingerprintOf(current)
290
310
  if (backends.has(key) && backends.get(key).fingerprint !== fingerprint) {
291
311
  backends.get(key).backend?.close?.()
292
312
  backends.delete(key)
@@ -294,32 +314,44 @@ export function agentRouter({
294
314
  if (!backends.has(key)) {
295
315
  // usage: an endpoint is asked for token counts (the composer's usage
296
316
  // ring); one that refuses stream_options is asked again without.
297
- const backend = createBackend(
298
- { ...current, usage: current.usage ?? true },
299
- {
300
- env,
301
- fetchImpl,
302
- processPool,
303
- root: config.dir,
304
- protect: [config.outputDir],
305
- // Files capture runs or logs in with: a write needs an approval card.
306
- sensitivePaths: () => authFiles(config),
307
- mcpServersFor: ownerWrites ? (thread) => ownerMcpServers(config, thread.split('/')[0], { allowCapture }) : null,
308
- // One agent process per thread, no more than answers at once.
309
- limits: { processesMax: limit.runsMax, ...limit.acp },
310
- log,
311
- },
312
- )
313
- backends.set(key, { key, fingerprint, backend })
317
+ const live = { ...current, usage: current.usage ?? true }
318
+ const backend = createBackend(live, {
319
+ env,
320
+ fetchImpl,
321
+ processPool,
322
+ root: config.dir,
323
+ protect: [config.outputDir],
324
+ // Files capture runs or logs in with: a write needs an approval card.
325
+ sensitivePaths: () => authFiles(config),
326
+ mcpServersFor: ownerWrites
327
+ ? (thread) =>
328
+ ownerMcpServers(config, thread.split('/')[0], {
329
+ allowCapture,
330
+ env,
331
+ // Whose replies these are, so they are signed with its name.
332
+ agent: {
333
+ which: live.profileId || (['flag', 'env'].includes(live.sources?.acpCommand) ? 'fixed' : 'default'),
334
+ name: live.label,
335
+ },
336
+ })
337
+ : null,
338
+ // One agent process per thread, no more than answers at once.
339
+ limits: { processesMax: limit.runsMax, ...limit.acp },
340
+ log,
341
+ })
342
+ backends.set(key, { key, fingerprint, backend, live })
314
343
  }
315
344
  cached = backends.get(key)
345
+ // A rename since the backend was made: what it says next ("Starting
346
+ // Harry") uses the new name. Nothing is restarted for it.
347
+ Object.assign(cached.live, { label: current.label, icon: current.icon, tint: current.tint })
316
348
  return cached.backend
317
349
  }
318
350
  // The owner backend already running for these settings, never a new one
319
351
  // (the composer's pickers read a live session's choices).
320
352
  const liveOwnerBackend = (current) => {
321
353
  const entry = backends.get(JSON.stringify({ profileId: current.profileId || 'default', ownerWrites: true }))
322
- return entry && entry.fingerprint === JSON.stringify(current) ? entry.backend : null
354
+ return entry && entry.fingerprint === fingerprintOf(current) ? entry.backend : null
323
355
  }
324
356
  // Server shutdown: stop agent processes (src/server/app.js stopChildren).
325
357
  router.close = () => {
@@ -396,6 +428,8 @@ export function agentRouter({
396
428
  const runs = new Map()
397
429
  const selecting = new Set()
398
430
  let connectionTesting = () => false
431
+ // { id } while a connection test runs, else null (settings-routes.js).
432
+ let connectionTest = () => null
399
433
  // Keep controls privileged for the lifetime of an owner thread/session,
400
434
  // including an idle ACP process. A tokenless turn cannot reset its memory.
401
435
  const ownerThreads = new Set()
@@ -863,6 +897,7 @@ export function agentRouter({
863
897
  requestedPages,
864
898
  // Branch mode: the agent's cwd, file sandbox and commands are the worktree.
865
899
  workdir: work ? worktreeWorkdir(work) : null,
900
+ agentName: current.label || null,
866
901
  })
867
902
  health.record(current, reply)
868
903
  // What the profile offers, as this turn's session saw it; a turn that
@@ -1195,8 +1230,32 @@ export function agentRouter({
1195
1230
 
1196
1231
  // ---- Everything else: small bodies only ------------------------------------
1197
1232
 
1233
+ // An uploaded agent icon (settings-routes.js POST /identity/icon) is a
1234
+ // 256 by 256 PNG in base64: larger than the small bodies below. Only a
1235
+ // request with the owner's settings token gets the larger parser.
1236
+ router.post('/settings/identity/icon', (req, res, next) =>
1237
+ settingsTokenOk(req, settingsToken) ? express.json({ limit: ICON_BODY_LIMIT })(req, res, next) : next(),
1238
+ )
1198
1239
  router.use(express.json({ limit: SMALL_BODY_LIMIT }))
1199
1240
 
1241
+ // An icon the owner uploaded for one of this project's agents
1242
+ // (icon-store.js), for everyone who can see the board: the agent info they
1243
+ // get names it by its content hash ("upload:<hash>"). Always a PNG this
1244
+ // server encoded itself, served as nothing but an image. A hash no agent
1245
+ // of this project uses is a 404, so the folder cannot be browsed.
1246
+ router.get('/icons/:hash', (req, res) => {
1247
+ const hash = String(req.params.hash)
1248
+ const used = uploadHashes(userAgentEntry(config.dir, env).entry)
1249
+ const png = used.has(hash) ? readIcon(hash, env) : null
1250
+ if (!png) return res.status(404).json({ error: { code: 'unknown_icon', message: 'No such agent icon.' } })
1251
+ // The name is the hash of the bytes: it never changes under one URL.
1252
+ res.setHeader('Cache-Control', 'private, max-age=31536000, immutable')
1253
+ res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox")
1254
+ res.setHeader('Cross-Origin-Resource-Policy', 'same-origin')
1255
+ res.setHeader('X-Content-Type-Options', 'nosniff')
1256
+ res.type('png').send(png)
1257
+ })
1258
+
1200
1259
  // The agent settings changed (here, in another tab, or in the file): a
1201
1260
  // nudge only, no settings in it; each view refetches what it shows.
1202
1261
  // The owner only (the settings token in its header, a paired device or the
@@ -1276,6 +1335,7 @@ export function agentRouter({
1276
1335
  },
1277
1336
  })
1278
1337
  connectionTesting = settingsApi.isTesting
1338
+ connectionTest = settingsApi.testing
1279
1339
  router.use('/settings', settingsApi)
1280
1340
  router.get(
1281
1341
  '/boards/:id/threads',
@@ -1562,7 +1622,7 @@ export function agentRouter({
1562
1622
  'Undo is no longer available for this answer: the board server restarted, or newer answers took its place.',
1563
1623
  )
1564
1624
  }
1565
- const files = undoFiles(config, record)
1625
+ const files = undoFiles(config, record, { ignored: await ignoredPaths(config.dir) })
1566
1626
  undoRecords.delete(key)
1567
1627
  undone = { kind: 'files', files: files.length }
1568
1628
  } else if (summary.undo.kind === 'branch' && summary.undo.available) {
package/src/agent/run.js CHANGED
@@ -117,6 +117,16 @@ export async function runTurn({
117
117
  choices = null,
118
118
  // Agent branch mode: the folder this turn's agent works in (acp.js stream).
119
119
  workdir = null,
120
+ // A turn that takes edits from a hosted board: who decides its requests (acp.js stream).
121
+ gate = null,
122
+ // The agent's first words for this turn's session, when not the backend's own.
123
+ preamble = null,
124
+ // What the owner called this agent (identity.js): the author of its replies.
125
+ agentName = null,
126
+ // The neutral messages, already built (a connected agent's turn, whose
127
+ // conversation comes from the hosted server: src/remote/agent-job.js).
128
+ // Without it they are built from this board's own store (modelMessages).
129
+ conversation: given = null,
120
130
  }) {
121
131
  const thread = `${board.id}/${threadId}`
122
132
  const runMs = backend.runMsMax || RUN_MS_MAX
@@ -177,7 +187,7 @@ export async function runTurn({
177
187
  note(text)
178
188
  }
179
189
  try {
180
- const conversation = modelMessages({ config, board, threadId, messages, comments: backend.tools !== 'shapewall', ownerTurn })
190
+ const conversation = given || modelMessages({ config, board, threadId, messages, comments: backend.tools !== 'shapewall', ownerTurn })
181
191
  // A model that does not take images (Settings > Agent): the images are
182
192
  // dropped here, and the chat says so, instead of the endpoint's 400.
183
193
  if (backend.vision === false && withoutImages(conversation)) noteOnce(NO_IMAGES_NOTE)
@@ -193,6 +203,8 @@ export async function runTurn({
193
203
  ...(modelOverride ? { model: modelOverride } : {}),
194
204
  ...(choices ? { choices } : {}),
195
205
  ...(workdir ? { workdir } : {}),
206
+ ...(gate ? { gate } : {}),
207
+ ...(preamble ? { preamble } : {}),
196
208
  signal,
197
209
  thread,
198
210
  })) {
@@ -279,7 +291,7 @@ export async function runTurn({
279
291
  for (const call of calls) {
280
292
  const id = call.id || newId('call')
281
293
  card({ id, kind: 'tool', name: call.name, label: call.name, state: 'running', detail: null })
282
- const result = await runTool({ config, board, ownerWrites, allowCapture, capture, requestedPages }, call)
294
+ const result = await runTool({ config, board, ownerWrites, allowCapture, capture, requestedPages, agentName }, call)
283
295
  card({ id, label: result.label, state: result.ok ? 'done' : 'error', detail: result.detail })
284
296
  if (result.ok) noteRefs(call.args)
285
297
  conversation.push({ role: 'tool', toolCallId: id, content: [{ type: 'text', text: result.text }] })
@@ -12,6 +12,11 @@
12
12
  // POST /api/agent/settings/profiles/:id/default make a connected agent (or "endpoint": the saved
13
13
  // OpenAI-compatible endpoint) the one new chats and fixes use
14
14
  // DELETE /api/agent/settings/profiles/:id remove a connected agent
15
+ // POST /api/agent/settings/identity { id, name?, icon?, tint? } what an agent is called and how
16
+ // it looks (identity.js). `id`: a connected agent, "endpoint", or
17
+ // "default" (the agent a flag or the environment fixes). Display only:
18
+ // no confirmation, no restart, no test, also while it answers
19
+ // POST /api/agent/settings/identity/icon { id, png } an uploaded icon (icon-store.js)
15
20
  //
16
21
  // These are the server owner's settings: which agent runs on their machine
17
22
  // and where their API key goes. Looking local is not enough (a proxy or TCP
@@ -50,9 +55,12 @@ import { legacyProfile, profileForDefault, projectKey, saveUserAgentEntry, userA
50
55
  import { DEFAULT_BRANCH_PREFIX, branchModeSettings, cleanBranchPrefix, repoFilters } from './branch-mode.js'
51
56
  import { batchFixSettings, cleanBatchFixes } from './batch-fixes.js'
52
57
  import { tokenEquals } from '../tokens.js'
58
+ import { cleanAgentName, identityOf, isAgentIcon, isAgentTint, isBuiltInIcon } from './identity.js'
59
+ import { IconError, pruneIcons, saveIcon } from './icon-store.js'
60
+ import { logoForAgent } from './agent-logos.js'
61
+ import { ACP_TEST_TIMEOUT_MS } from './test-timing.js'
53
62
 
54
63
  const TEST_TIMEOUT_MS = 15000
55
- const ACP_TEST_TIMEOUT_MS = 30000
56
64
  const VISION_PROBE_MS = 3000
57
65
  const LOOPBACK_NAMES = new Set(['127.0.0.1', 'localhost', '[::1]', '::1'])
58
66
  // Any of these means a proxy or tunnel stands between the person and us.
@@ -356,6 +364,9 @@ export function settingsRoutes({
356
364
  })
357
365
  const repo = () => config.agent || {}
358
366
  let testing = false
367
+ // Which agent the running test is of: a profile id, or "default" (the
368
+ // default connection). Shown as that agent's state ("Testing the connection").
369
+ let testingId = null
359
370
  let closing = false
360
371
  const pending = new Set()
361
372
  router.close = async () => {
@@ -364,6 +375,15 @@ export function settingsRoutes({
364
375
  }
365
376
  // Shared admission lock: a handshake must not overlap live turns or profile changes.
366
377
  router.isTesting = () => testing
378
+ // { id } while a test runs, else null (routes.js: the agent's state).
379
+ router.testing = () => (testing ? { id: testingId } : null)
380
+ // A test started or ended: every open view hears it, also the ones that
381
+ // did not start it (a reloaded page, another tab).
382
+ const setTesting = (on, id = null) => {
383
+ testing = on
384
+ testingId = on ? id || 'default' : null
385
+ events?.changed('state')
386
+ }
367
387
 
368
388
  const guard = (req, res, next) => {
369
389
  if (closing) return fail(res, 503, 'settings_stopping', 'Agent settings are stopping.')
@@ -378,6 +398,145 @@ export function settingsRoutes({
378
398
  next()
379
399
  }
380
400
 
401
+ // ---- What an agent is called and how it looks (identity.js) ----------------
402
+ //
403
+ // Registered before the admission step below on purpose: a name, an icon
404
+ // and a tint change nothing an agent runs with, so saving them never waits
405
+ // for a turn to end, never stops an agent process and never runs a test.
406
+ // A flag or environment command does not block them either: it fixes the
407
+ // command, not what the board calls it.
408
+
409
+ // The saved place `id` names: { entry, target, known } with `target` the
410
+ // object inside `entry` that holds its label, icon and tint, and `known`
411
+ // the built-in name an empty name falls back to (null: the name is needed).
412
+ const identityTarget = (id, current) => {
413
+ const entry = { ...current, profiles: (current.profiles || []).map((item) => ({ ...item })) }
414
+ const source = settings().sources?.acpCommand
415
+ const fixed = source === 'flag' || source === 'env'
416
+ const legacy = legacyProfile(current, KNOWN_AGENTS)
417
+ const builtIn = (profileId) => KNOWN_AGENTS.find((item) => item.id === profileId)?.label || null
418
+ if (id === 'default') {
419
+ if (fixed) {
420
+ entry.fixedAgent = { ...(current.fixedAgent || {}) }
421
+ return { entry, target: entry.fixedAgent, known: true }
422
+ }
423
+ const running = profileForDefault(current) || legacy
424
+ if (running) return identityTarget(running.id, current)
425
+ return endpointOf(current) ? identityTarget('endpoint', current) : null
426
+ }
427
+ if (id === 'endpoint') return endpointOf(current) ? { entry, target: entry, known: true } : null
428
+ // A default command saved before profiles becomes a profile, as on Connect.
429
+ if (legacy?.id === id) entry.profiles = [{ ...legacy }, ...entry.profiles]
430
+ const profile = entry.profiles.find((item) => item.id === id)
431
+ return profile ? { entry, target: profile, known: builtIn(id) } : null
432
+ }
433
+
434
+ // `current` with { name, icon, tint } (only the keys given) applied to the
435
+ // agent `id`: { entry }, or { status, code, message } when it is refused.
436
+ const withIdentity = (current, id, change) => {
437
+ const found = identityTarget(id, current)
438
+ if (!found) return { status: 404, code: 'unknown_profile', message: 'That agent is not connected.' }
439
+ const { entry, target } = found
440
+ if (Object.hasOwn(change, 'name')) {
441
+ const { name, problem } = cleanAgentName(change.name)
442
+ if (problem) return { status: 400, code: 'invalid_name', message: problem }
443
+ if (name) target.label = name
444
+ else if (found.known === true) delete target.label
445
+ else if (found.known) target.label = found.known
446
+ else return { status: 400, code: 'invalid_name', message: 'name: 1 to 40 characters' }
447
+ }
448
+ if (Object.hasOwn(change, 'icon')) {
449
+ if (change.icon === null || change.icon === '') delete target.icon
450
+ else if (isAgentIcon(change.icon)) target.icon = change.icon
451
+ else return { status: 400, code: 'invalid_icon', message: 'icon: one of the built-in icons, or null for none.' }
452
+ }
453
+ if (Object.hasOwn(change, 'tint')) {
454
+ if (change.tint === null || change.tint === '') delete target.tint
455
+ else if (isAgentTint(change.tint)) target.tint = change.tint
456
+ else return { status: 400, code: 'invalid_tint', message: 'tint: one of the accent colours, or null for none.' }
457
+ }
458
+ if (entry.fixedAgent && !Object.keys(entry.fixedAgent).length) delete entry.fixedAgent
459
+ if (!entry.profiles.length) delete entry.profiles
460
+ delete entry.updatedAt
461
+ return { entry }
462
+ }
463
+
464
+ // A one-click Connect saves the agent and then tests it, which with a real
465
+ // agent takes seconds, and puts the old settings back when the test fails.
466
+ // A name or an icon saved in that window must not be lost or refused:
467
+ // - for the agent being connected, the save waits for the test (the person
468
+ // sees "Saving when the connection test finishes..."), then is applied to
469
+ // the connected agent, or answers that it did not connect;
470
+ // - for any other agent it is saved at once, and remembered (`renamed`) so
471
+ // that a failed test, which writes the old settings back, applies it again.
472
+ // `connecting`: { id, done, renamed } while such a test runs, else null.
473
+ let connecting = null
474
+ const underTest = (id) => {
475
+ if (!connecting || typeof id !== 'string') return false
476
+ const found = identityTarget(id, userAgentEntry(config.dir, env).entry || {})
477
+ return found?.target?.id === connecting.id
478
+ }
479
+
480
+ // Saves the change for `id`. Returns true when saved; otherwise it answered.
481
+ const saveIdentity = async (req, res, id, change) => {
482
+ if (typeof id !== 'string' || !id) return fail(res, 400, 'invalid_identity', 'id: a connected agent, "endpoint" or "default".')
483
+ const waited = underTest(id) ? connecting : null
484
+ if (waited) await waited.done
485
+ const saved = userAgentEntry(config.dir, env)
486
+ if (saved.problem) return fail(res, 409, 'settings_file_invalid', saved.problem)
487
+ const next = withIdentity(saved.entry || {}, id, change)
488
+ if (!next.entry) {
489
+ // The agent it was for did not connect: said in those words.
490
+ if (waited && next.status === 404)
491
+ return fail(res, 409, 'agent_not_connected', `${waited.label} did not connect, so there is nothing to rename. Nothing was changed.`)
492
+ return fail(res, next.status, next.code, next.message)
493
+ }
494
+ try {
495
+ // No reload(): the agents keep running; the name is read fresh wherever it is shown.
496
+ saveUserAgentEntry(config.dir, next.entry, env)
497
+ if (connecting) connecting.renamed.push({ id, change })
498
+ pruneIcons(env)
499
+ } catch (error) {
500
+ return fail(res, 500, 'settings_not_saved', `The settings were not saved: ${error.message}`)
501
+ }
502
+ return true
503
+ }
504
+
505
+ router.post('/identity', guard, async (req, res) => {
506
+ const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {}
507
+ const change = Object.fromEntries(['name', 'icon', 'tint'].filter((key) => Object.hasOwn(body, key)).map((key) => [key, body[key]]))
508
+ // An uploaded icon is set by the upload itself, never named from outside.
509
+ if (typeof change.icon === 'string' && !isBuiltInIcon(change.icon))
510
+ return fail(res, 400, 'invalid_icon', 'icon: one of the built-in icons, or null for none.')
511
+ if ((await saveIdentity(req, res, body.id, change)) === true) res.json(view())
512
+ })
513
+
514
+ router.post('/identity/icon', guard, async (req, res) => {
515
+ const body = req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {}
516
+ // The agent is being connected: wait here, before the picture is stored
517
+ // (a file no agent uses yet would be cleaned up by another save).
518
+ const waited = underTest(body.id) ? connecting : null
519
+ if (waited) await waited.done
520
+ // Is the agent there? Before anything is stored.
521
+ const saved = userAgentEntry(config.dir, env)
522
+ if (saved.problem) return fail(res, 409, 'settings_file_invalid', saved.problem)
523
+ if (typeof body.id !== 'string' || !identityTarget(body.id, saved.entry || {})) {
524
+ if (waited)
525
+ return fail(res, 409, 'agent_not_connected', `${waited.label} did not connect, so its icon was not saved. Nothing was changed.`)
526
+ return fail(res, 404, 'unknown_profile', 'That agent is not connected.')
527
+ }
528
+ let hash
529
+ try {
530
+ hash = saveIcon(body.png, env)
531
+ } catch (error) {
532
+ if (error instanceof IconError) return fail(res, error.status, error.code, error.message)
533
+ return fail(res, 500, 'settings_not_saved', `The icon was not saved: ${error.message}`)
534
+ }
535
+ if ((await saveIdentity(req, res, body.id, { icon: `upload:${hash}` })) === true) res.json(view())
536
+ // Not saved after all: the file just written is not left behind.
537
+ else pruneIcons(env)
538
+ })
539
+
381
540
  router.use(async (req, res, next) => {
382
541
  if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) return next()
383
542
  // Authorize before taking admission so an outsider cannot block turns.
@@ -433,7 +592,12 @@ export function settingsRoutes({
433
592
  })
434
593
 
435
594
  // How an agent is doing (agent-health.js): { state, loginHint }.
436
- const statusOf = (profileId) => (health ? health.status(settings(profileId), processPool) : {})
595
+ // While its connection test runs an agent's state is "testing", not what
596
+ // the last turn left ("Ready"): the page must not look finished.
597
+ const statusOf = (profileId) => {
598
+ const status = health ? health.status(settings(profileId), processPool) : {}
599
+ return testing && testingId === (profileId || 'default') ? { ...status, state: 'testing' } : status
600
+ }
437
601
  const profileList = (entry) => {
438
602
  const legacy = legacyProfile(entry, KNOWN_AGENTS)
439
603
  // Profiles saved without a default connection: the first one (config.js agentSettings).
@@ -442,6 +606,8 @@ export function settingsRoutes({
442
606
  ...profile,
443
607
  command: acpCommand,
444
608
  default: (entry?.backend === 'acp' && entry.acpCommand === acpCommand) || profile.id === fallback,
609
+ // Its default icon: a known agent's product mark (agent-logos.js), or null.
610
+ logo: settings(profile.legacy ? null : profile.id).logo || null,
445
611
  // A legacy command runs as the default connection.
446
612
  ...statusOf(profile.legacy ? null : profile.id),
447
613
  }))
@@ -455,6 +621,7 @@ export function settingsRoutes({
455
621
  const isDefault = backend === 'openai-compatible' && !settings().defaultProfile
456
622
  return {
457
623
  label: entry.label || repo().label || model,
624
+ ...identityOf(entry),
458
625
  model,
459
626
  host: hostOf(baseUrl),
460
627
  default: isDefault,
@@ -482,6 +649,10 @@ export function settingsRoutes({
482
649
  configured: current.configured,
483
650
  problem: current.problem,
484
651
  label: current.label,
652
+ icon: current.icon || null,
653
+ tint: current.tint || null,
654
+ logo: current.logo || null,
655
+ builtInLabel: current.builtInLabel || null,
485
656
  baseUrl: current.baseUrl,
486
657
  model: current.model,
487
658
  host: current.host,
@@ -504,7 +675,12 @@ export function settingsRoutes({
504
675
  // one-click Connect in an unconnected chat panel.
505
676
  detected: detectAgents(env),
506
677
  // Every agent Shapewall knows how to run, found or not (the console's Agents page).
507
- known: KNOWN_AGENTS.map(({ id, label, adapter, cli, install }) => ({ id, label, adapter, cli, install })),
678
+ known: KNOWN_AGENTS.map(({ id, label, adapter, cli, install }) => ({ id, label, adapter, cli, install, logo: logoForAgent(id) })),
679
+ // Icons can be uploaded here (the demo has only the built-in ones).
680
+ iconUpload: true,
681
+ // { id } while a connection test runs (a Connect, or Test connection):
682
+ // the other changes of this page wait for it.
683
+ testing: testing ? { id: testingId } : null,
508
684
  knownKeyHosts: [...KNOWN_KEY_HOSTS],
509
685
  defaultKeyVar: DEFAULT_KEY_VAR,
510
686
  keyVarsSet: keyVarsSet(env),
@@ -571,16 +747,27 @@ export function settingsRoutes({
571
747
  return fail(res, 400, 'invalid_settings', 'The settings must be an object.')
572
748
  // Old clients save only the default connection. Keep their saved profiles.
573
749
  const preserved = input && !Object.hasOwn(input, 'profiles') ? userAgentEntry(config.dir, env).entry?.profiles : undefined
574
- // Branch mode and batch fixes have their own routes (/branch-mode,
575
- // /batch-fixes): a save of the connection keeps them.
750
+ // Branch mode, batch fixes and the icons have their own routes
751
+ // (/branch-mode, /batch-fixes, /identity): a save of the connection keeps them.
576
752
  const savedEntry = userAgentEntry(config.dir, env).entry || {}
577
753
  const branch = Object.fromEntries(
578
- ['branchMode', 'branchPrefix', 'batchFixes']
754
+ ['branchMode', 'branchPrefix', 'batchFixes', 'icon', 'tint', 'fixedAgent']
579
755
  .filter((key) => !Object.hasOwn(input, key) && savedEntry[key] !== undefined)
580
756
  .map((key) => [key, savedEntry[key]]),
581
757
  )
582
758
  const { entry, problems } = validateUserEntry({ ...input, ...(preserved ? { profiles: preserved } : {}), ...branch })
583
759
  if (!entry) return fail(res, 400, 'invalid_settings', problems.join('; '))
760
+ // The form's name field names the agent it saves. When that is a
761
+ // connected agent (the default command is one of the profiles), the name
762
+ // belongs to that agent, the same one the Agents page's Edit changes.
763
+ const named = Object.hasOwn(input, 'label') ? profileForDefault(entry) : null
764
+ if (named) {
765
+ const { name, problem } = cleanAgentName(input.label)
766
+ if (problem) return fail(res, 400, 'invalid_settings', problem.replace(/^name/, 'label'))
767
+ const builtIn = KNOWN_AGENTS.find((item) => item.id === named.id)?.label
768
+ entry.profiles = entry.profiles.map((item) => (item.id === named.id ? { ...item, label: name || builtIn || item.label } : item))
769
+ delete entry.label
770
+ }
584
771
  // A Connect is testing what it saved and may put the old settings back:
585
772
  // a save now would be lost.
586
773
  if (testing) return fail(res, 409, 'test_running', 'A connection test is running. Wait for it, then save.')
@@ -612,6 +799,21 @@ export function settingsRoutes({
612
799
  `The agent command comes from ${source === 'flag' ? '--agent-acp' : 'SHAPEWALL_AGENT_ACP'}, which wins over the board. Change it there, or restart shapewall serve without it.`,
613
800
  )
614
801
  }
802
+ // What the owner calls it, from the confirmation's Name field (empty:
803
+ // its built-in name), and optionally a built-in icon and a tint. An
804
+ // uploaded icon comes after the agent is connected (POST /identity/icon).
805
+ const { name, problem } = cleanAgentName(req.body?.name)
806
+ if (problem) return fail(res, 400, 'invalid_name', problem)
807
+ const look = {}
808
+ if (req.body?.icon) {
809
+ if (!isBuiltInIcon(req.body.icon)) return fail(res, 400, 'invalid_icon', 'icon: one of the built-in icons.')
810
+ look.icon = req.body.icon
811
+ }
812
+ if (req.body?.tint) {
813
+ if (!isAgentTint(req.body.tint)) return fail(res, 400, 'invalid_tint', 'tint: one of the accent colours.')
814
+ look.tint = req.body.tint
815
+ }
816
+ const called = (profileConnect && name) || agent.label
615
817
  const before = userAgentEntry(config.dir, env)
616
818
  // The label and the image toggle belong to the agent connected before.
617
819
  const entry = { ...(before.entry || {}) }
@@ -622,7 +824,7 @@ export function settingsRoutes({
622
824
  entry.profiles = [
623
825
  ...(legacy && legacy.id !== agent.id ? [legacy] : []),
624
826
  ...(entry.profiles || []).filter((item) => item.id !== agent.id),
625
- { id: agent.id, label: agent.label, acpCommand: agent.command },
827
+ { id: agent.id, label: called, acpCommand: agent.command, ...look },
626
828
  ]
627
829
  }
628
830
  if (!profileConnect || !settings().configured) {
@@ -632,21 +834,38 @@ export function settingsRoutes({
632
834
  delete entry.vision
633
835
  }
634
836
  if (!saveEntry(req, res, entry)) return
635
- // Back to what was there: the panel must not claim an agent that does not start.
837
+ let ended
838
+ const job = { id: agent.id, label: called, renamed: [], done: new Promise((resolve) => (ended = resolve)) }
839
+ // Back to what was there: the panel must not claim an agent that does not
840
+ // start. Names and icons other agents were given meanwhile are kept; one
841
+ // for an agent that is not there any more (this one) is dropped.
636
842
  const restore = () => {
637
843
  try {
638
- saveUserAgentEntry(config.dir, before.entry || {}, env)
844
+ let entry = before.entry || {}
845
+ for (const { id, change } of job.renamed) entry = withIdentity(entry, id, change).entry || entry
846
+ saveUserAgentEntry(config.dir, entry, env)
847
+ pruneIcons(env)
639
848
  } finally {
640
849
  reload()
641
850
  }
642
851
  }
643
- testing = true
852
+ connecting = job
853
+ setTesting(true, profileConnect ? agent.id : 'default')
854
+ // The test is over (after any restore): the saves that waited for it go
855
+ // on, and the answer below already shows the agent as it is, not "testing".
856
+ const over = () => {
857
+ if (connecting !== job) return
858
+ connecting = null
859
+ setTesting(false)
860
+ ended()
861
+ }
644
862
  try {
645
863
  const tested = settings(profileConnect ? agent.id : null)
646
864
  const result = await testConnection(tested, { env, fetchImpl, root: config.dir, processPool })
647
865
  health?.record(tested, result)
648
866
  if (!result.ok) restore()
649
- res.json({ connected: result.ok, result: { ...result, label: agent.label }, ...view() })
867
+ over()
868
+ res.json({ connected: result.ok, result: { ...result, label: called }, ...view() })
650
869
  } catch (error) {
651
870
  try {
652
871
  restore()
@@ -655,7 +874,7 @@ export function settingsRoutes({
655
874
  }
656
875
  fail(res, 500, 'test_failed', `The test did not finish: ${redact(error.message)}`)
657
876
  } finally {
658
- testing = false
877
+ over()
659
878
  await res.locals.releaseSettingsOperation?.()
660
879
  }
661
880
  })
@@ -776,7 +995,7 @@ export function settingsRoutes({
776
995
  const profileId = req.body?.profileId ?? null
777
996
  if (profileId !== null && !(userAgentEntry(config.dir, env).entry?.profiles || []).some((item) => item.id === profileId))
778
997
  return fail(res, 400, 'unknown_profile', 'profileId: one of the connected agents.')
779
- testing = true
998
+ setTesting(true, profileId)
780
999
  try {
781
1000
  const tested = settings(profileId)
782
1001
  const result = await testConnection(tested, { env, fetchImpl, root: config.dir, processPool })
@@ -785,7 +1004,7 @@ export function settingsRoutes({
785
1004
  } catch (error) {
786
1005
  fail(res, 500, 'test_failed', `The test did not finish: ${redact(error.message)}`)
787
1006
  } finally {
788
- testing = false
1007
+ setTesting(false)
789
1008
  await res.locals.releaseSettingsOperation?.()
790
1009
  }
791
1010
  })
@@ -72,6 +72,11 @@ function pullRequester(config, settings, source, env) {
72
72
 
73
73
  export async function agentCommand(positional, flags, out, err, { env = process.env } = {}) {
74
74
  const action = positional[0]
75
+ if (action === 'connect') {
76
+ // A connected agent of a hosted board: this machine's coding agent, read and answer only.
77
+ const { agentConnect } = await import('../../remote/agent-connect.js')
78
+ return agentConnect(flags, out, err, { env })
79
+ }
75
80
  if (action === 'sandbox') {
76
81
  // Inside the container only.
77
82
  const { runSandbox } = await import('./sandbox-main.js')
@@ -100,7 +105,7 @@ export async function agentCommand(positional, flags, out, err, { env = process.
100
105
  return 0
101
106
  }
102
107
  if (!['run', 'watch', 'doctor'].includes(action))
103
- throw new Error('usage: shapewall agent run --comment ID | agent watch | agent doctor | agent build-image')
108
+ throw new Error('usage: shapewall agent connect --remote URL | agent run --comment ID | agent watch | agent doctor | agent build-image')
104
109
  const config = configFor(flags)
105
110
  const settings = starterSettings(config, { env, flags })
106
111
  const image = agentImage({ flag: flags.image || null, env })
@@ -0,0 +1,14 @@
1
+ // How long a connection test may take, in one place for the server that
2
+ // runs it and the board that waits for it.
3
+ //
4
+ // A one-click Connect (and Test connection) starts the agent and waits for
5
+ // its ACP handshake. The stub used in tests answers at once; a real agent
6
+ // takes several seconds, and up to ACP_TEST_TIMEOUT_MS before the server
7
+ // gives up. While it runs the server takes no chat message and no other
8
+ // settings change, so the board waits rather than showing an error: for a
9
+ // little longer than the test can last (TEST_WAIT_MS).
10
+ //
11
+ // No Node imports: the board imports this file too.
12
+
13
+ export const ACP_TEST_TIMEOUT_MS = 30000
14
+ export const TEST_WAIT_MS = ACP_TEST_TIMEOUT_MS + 15000