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
@@ -149,8 +149,10 @@ export const OWNER_TOOLS = [
149
149
  required: ['id', 'body'],
150
150
  additionalProperties: false,
151
151
  },
152
- async run({ config, board }, args) {
153
- return (await addReply(config, board.id, args.id, { body: args.body, author: 'agent' })).comment
152
+ // Signed with the name the owner gave the agent, and marked as an agent's.
153
+ async run({ config, board, agentName }, args) {
154
+ const signed = agentName ? { author: agentName, agent: true } : { author: 'agent' }
155
+ return (await addReply(config, board.id, args.id, { body: args.body, ...signed })).comment
154
156
  },
155
157
  },
156
158
  {
@@ -6,7 +6,9 @@
6
6
  // or files that usually hold secrets, never through a symlink). After the
7
7
  // turn it compares: the files that were added, changed or deleted, each with
8
8
  // its +/- counts and a bounded diff, and an undo record kept in this
9
- // process's memory only. Nothing read here goes to the model or to a log;
9
+ // process's memory only. Files Git ignores are not the agent's work and are
10
+ // left out entirely (see ignoredPaths below): never read, listed, counted or
11
+ // undone. Nothing read here goes to the model or to a log;
10
12
  // the stored summary holds diffs of the changed text files only, and never
11
13
  // of a file that looks like it holds secrets.
12
14
  //
@@ -32,6 +34,8 @@ import { diffForCard } from './text-diff.js'
32
34
  import { AGENT_AUTHOR, git, readEntry } from './starter/worktree.js'
33
35
 
34
36
  const SKIP = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.cache', 'coverage', '.output', '.shapewall'])
37
+ // Shapewall's own folders, whatever they are called (.shapewall, .shapewall-export, ...).
38
+ const skipped = (name) => SKIP.has(name) || name.startsWith('.shapewall')
35
39
  export const ENTRIES_MAX = 30000
36
40
  export const FILE_KEEP_MAX = 1024 * 1024
37
41
  export const BASELINE_BYTES_MAX = 32 * 1024 * 1024
@@ -65,9 +69,53 @@ function readFile(full, stat) {
65
69
  }
66
70
  }
67
71
 
72
+ // What Git ignores in the project folder right now, by the working tree's own
73
+ // rules: .gitignore files as they are on disk (committed or not),
74
+ // .git/info/exclude and the person's global excludes. Another process on the
75
+ // machine often writes there during a turn (a dev server's data, logs, a
76
+ // cache): those files are not the agent's, so they are never listed or
77
+ // counted, and above all never touched by Undo, which would otherwise
78
+ // delete or roll back somebody else's data.
79
+ // Returns { files: Set, dirs: Set } of paths relative to the project folder
80
+ // (directories end in "/"), or null when Git cannot say: the folder is not
81
+ // in a repository, or the folder itself is ignored by the repository around
82
+ // it (then Git's rules say nothing useful about what is inside). Tracked
83
+ // files are never "ignored", whatever .gitignore says.
84
+ export async function ignoredPaths(dir) {
85
+ try {
86
+ const inside = await git(['check-ignore', '-q', '.'], { cwd: dir, timeoutMs: 10000, status: true })
87
+ // 1: not ignored. 0: the folder itself is ignored. 128: not a repository.
88
+ if (inside.code !== 1) return null
89
+ const out = await git(['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], { cwd: dir, timeoutMs: 20000 })
90
+ const ignored = { files: new Set(), dirs: new Set() }
91
+ for (const item of out.split('\0')) {
92
+ if (!item || item.startsWith('../')) continue
93
+ if (item.endsWith('/')) ignored.dirs.add(item)
94
+ else ignored.files.add(item)
95
+ }
96
+ return ignored
97
+ } catch {
98
+ return null
99
+ }
100
+ }
101
+
102
+ // Whether `rel` (a file) is ignored: itself, or any folder above it.
103
+ export function isIgnored(ignored, rel) {
104
+ if (!ignored) return false
105
+ if (ignored.files.has(rel)) return true
106
+ const parts = rel.split('/')
107
+ let prefix = ''
108
+ for (let index = 0; index < parts.length - 1; index += 1) {
109
+ prefix += `${parts[index]}/`
110
+ if (ignored.dirs.has(prefix)) return true
111
+ }
112
+ return false
113
+ }
114
+
68
115
  // The project's files: rel -> { stamp, mode, data? }. `keep`: read content
69
- // (bounded) for the files that may need restoring.
70
- export function scanProject(config, { keep = false, bytesMax = BASELINE_BYTES_MAX, entriesMax = ENTRIES_MAX } = {}) {
116
+ // (bounded) for the files that may need restoring. `ignored` (ignoredPaths):
117
+ // what Git ignores, skipped without being read or counted.
118
+ export function scanProject(config, { keep = false, bytesMax = BASELINE_BYTES_MAX, entriesMax = ENTRIES_MAX, ignored = null } = {}) {
71
119
  const files = new Map()
72
120
  let visited = 0
73
121
  let bytes = 0
@@ -86,12 +134,15 @@ export function scanProject(config, { keep = false, bytesMax = BASELINE_BYTES_MA
86
134
  incomplete = true
87
135
  return
88
136
  }
89
- if (entry.isSymbolicLink() || SKIP.has(entry.name)) continue
137
+ if (entry.isSymbolicLink() || skipped(entry.name)) continue
90
138
  const full = path.join(dir, entry.name)
139
+ const relPath = path.relative(config.dir, full).split(path.sep).join('/')
91
140
  if (entry.isDirectory()) {
141
+ if (ignored?.dirs.has(`${relPath}/`)) continue
92
142
  walk(full)
93
143
  continue
94
144
  }
145
+ if (ignored?.files.has(relPath)) continue
95
146
  if (!entry.isFile()) continue
96
147
  let stat
97
148
  try {
@@ -180,8 +231,10 @@ function fileEntry(rel, status, before, after, budget) {
180
231
 
181
232
  // Taken before an owner's turn. `comments`: the board's comments now.
182
233
  export async function beginTurnChanges(config, { comments = [], files = true } = {}) {
234
+ const ignored = files ? await ignoredPaths(config.dir) : null
183
235
  return {
184
- scan: files ? scanProject(config, { keep: true }) : null,
236
+ ignored,
237
+ scan: files ? scanProject(config, { keep: true, ignored }) : null,
185
238
  head: files ? await gitHead(config.dir) : null,
186
239
  statuses: new Map(comments.map((comment) => [comment.id, comment.status])),
187
240
  }
@@ -211,11 +264,16 @@ export async function finishTurnChanges(
211
264
  let undoReason = null
212
265
  let commit = null
213
266
  if (baseline.scan) {
214
- const after = scanProject(config)
267
+ // Ignored now or when the turn began: either way not the agent's to
268
+ // list or undo. (A file the turn itself made ignored, by editing
269
+ // .gitignore, would otherwise show as deleted.)
270
+ const ignored = await ignoredPaths(config.dir)
271
+ const after = scanProject(config, { ignored })
215
272
  const before = baseline.scan.files
216
273
  const budget = { files: 0, bytes: 0 }
217
274
  const paths = [...new Set([...before.keys(), ...after.files.keys()])].sort()
218
275
  for (const rel of paths) {
276
+ if (isIgnored(ignored, rel) || isIgnored(baseline.ignored, rel)) continue
219
277
  const was = before.get(rel)
220
278
  const now = after.files.get(rel)
221
279
  if (was && now && was.stamp === now.stamp) continue
@@ -316,14 +374,18 @@ const cleanRel = (rel) =>
316
374
  !rel.startsWith('/') &&
317
375
  !rel.includes('\\') &&
318
376
  !rel.includes('\0') &&
319
- rel.split('/').every((part) => part && part !== '.' && part !== '..' && !SKIP.has(part))
377
+ rel.split('/').every((part) => part && part !== '.' && part !== '..' && !skipped(part))
320
378
 
321
379
  // Restores the files of an undo record, all or nothing. Returns the paths.
322
- export function undoFiles(config, record) {
380
+ // `ignored` (ignoredPaths, read by the caller right before): a last check
381
+ // that nothing Git ignores is about to be written or removed.
382
+ export function undoFiles(config, record, { ignored = null } = {}) {
323
383
  const root = config.dir
324
384
  const files = record?.files || []
325
385
  if (!files.length) throw new AgentError('undo_unavailable', 'There is nothing to undo.', 409)
326
386
  for (const item of files) {
387
+ if (isIgnored(ignored, item.path))
388
+ throw new AgentError('undo_unavailable', `${item.path} is ignored by Git, so it is not the agent's to undo. Nothing was undone.`, 409)
327
389
  if (!cleanRel(item.path)) throw new AgentError('undo_unavailable', 'This change cannot be undone here.', 409)
328
390
  const current = readEntry(root, item.path)
329
391
  if (current.kind === 'refused' || (current.kind === 'entry' && current.mode === '120000'))
@@ -22,6 +22,7 @@ import { SETTINGS_SOURCE } from './acp/command.js'
22
22
  import { DENIED_KEY_VARS, KEY_VAR_RE, validateAgent } from './config.js'
23
23
  import { cleanBranchPrefix } from './branch-mode.js'
24
24
  import { cleanBatchFixes } from './batch-fixes.js'
25
+ import { IDENTITY_KEYS, cleanAgentName, isAgentIcon, isAgentTint } from './identity.js'
25
26
 
26
27
  export const SETTINGS_FILE_VAR = 'SHAPEWALL_AGENT_SETTINGS_FILE'
27
28
  export const ENTRY_KEYS = [
@@ -37,6 +38,12 @@ export const ENTRY_KEYS = [
37
38
  'branchMode',
38
39
  'branchPrefix',
39
40
  'batchFixes',
41
+ // How the agent looks on the board (identity.js): `icon` and `tint` here
42
+ // are the endpoint's; `fixedAgent` holds the name, icon and tint of an
43
+ // agent whose command a flag or the environment fixes.
44
+ 'icon',
45
+ 'tint',
46
+ 'fixedAgent',
40
47
  ]
41
48
  const SECRET_KEYS = ['apiKey', 'key', 'token', 'secret', 'password']
42
49
  const ACP_COMMAND_MAX = 2000
@@ -46,6 +53,18 @@ const HOST_RE = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9
46
53
 
47
54
  const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
48
55
 
56
+ // The icon and tint of `source` into `target`, each checked (identity.js).
57
+ function readLook(source, target, problems, where) {
58
+ if (source.icon !== undefined) {
59
+ if (!isAgentIcon(source.icon)) problems.push(`${where}icon: a built-in icon or an uploaded one`)
60
+ else target.icon = source.icon
61
+ }
62
+ if (source.tint !== undefined) {
63
+ if (!isAgentTint(source.tint)) problems.push(`${where}tint: one of the accent colours`)
64
+ else target.tint = source.tint
65
+ }
66
+ }
67
+
49
68
  // The settings file, or null when there is no home to put it in.
50
69
  export function userSettingsFile(env = process.env) {
51
70
  if (typeof env[SETTINGS_FILE_VAR] === 'string' && env[SETTINGS_FILE_VAR].trim()) return path.resolve(env[SETTINGS_FILE_VAR].trim())
@@ -78,7 +97,7 @@ export function validateUserEntry(raw) {
78
97
  problems.push(`${key}: keys are never saved; set the key in the environment and name its variable in apiKeyEnv`)
79
98
  else if (!ENTRY_KEYS.includes(key) && key !== 'updatedAt') problems.push(`${key}: not an agent setting`)
80
99
  }
81
- const { keyHosts, acpCommand, profiles, updatedAt, branchMode, branchPrefix, batchFixes, ...rest } = given
100
+ const { keyHosts, acpCommand, profiles, updatedAt, branchMode, branchPrefix, batchFixes, icon, tint, fixedAgent, ...rest } = given
82
101
  const fields = {}
83
102
  for (const key of ['backend', 'baseUrl', 'model', 'apiKeyEnv', 'label', 'vision']) if (rest[key] !== undefined) fields[key] = rest[key]
84
103
  const agentProblems = []
@@ -130,7 +149,7 @@ export function validateUserEntry(raw) {
130
149
  for (const profile of profiles) {
131
150
  if (
132
151
  !isObject(profile) ||
133
- Object.keys(profile).some((key) => !['id', 'label', 'acpCommand'].includes(key)) ||
152
+ Object.keys(profile).some((key) => !['id', 'label', 'acpCommand', 'icon', 'tint'].includes(key)) ||
134
153
  !/^[a-z][a-z0-9-]{0,39}$/.test(profile.id || '') ||
135
154
  profile.id === 'default' ||
136
155
  ids.has(profile.id) ||
@@ -144,12 +163,29 @@ export function validateUserEntry(raw) {
144
163
  }
145
164
  const validated = validateUserEntry({ acpCommand: profile.acpCommand })
146
165
  if (!validated.entry?.acpCommand) problems.push('profiles: each profile needs a valid ACP command')
147
- else checkedProfiles.push({ id: profile.id, label: profile.label.trim(), acpCommand: validated.entry.acpCommand })
166
+ else {
167
+ const checkedProfile = { id: profile.id, label: profile.label.trim(), acpCommand: validated.entry.acpCommand }
168
+ readLook(profile, checkedProfile, problems, 'profiles: ')
169
+ checkedProfiles.push(checkedProfile)
170
+ }
148
171
  ids.add(profile.id)
149
172
  }
150
173
  if (checkedProfiles.length) entry.profiles = checkedProfiles
151
174
  }
152
175
  }
176
+ readLook({ icon, tint }, entry, problems, '')
177
+ if (fixedAgent !== undefined) {
178
+ if (!isObject(fixedAgent) || Object.keys(fixedAgent).some((key) => !IDENTITY_KEYS.includes(key))) {
179
+ problems.push('fixedAgent: { label, icon, tint }')
180
+ } else {
181
+ const fixed = {}
182
+ const { name, problem } = cleanAgentName(fixedAgent.label)
183
+ if (problem) problems.push(`fixedAgent.${problem.replace(/^name/, 'label')}`)
184
+ else if (name) fixed.label = name
185
+ readLook(fixedAgent, fixed, problems, 'fixedAgent.')
186
+ if (Object.keys(fixed).length) entry.fixedAgent = fixed
187
+ }
188
+ }
153
189
  // Agent branch mode (branch-mode.js): the agent works on a branch in a worktree.
154
190
  if (branchMode !== undefined) {
155
191
  if (typeof branchMode !== 'boolean') problems.push('branchMode: true or false')
@@ -208,6 +244,18 @@ export function legacyProfile(entry, known = []) {
208
244
  return { id, label, acpCommand: entry.acpCommand }
209
245
  }
210
246
 
247
+ // The name saved for one of this project's agents, or null when none is
248
+ // saved (the caller then uses the agent's built-in name). `which`: "fixed"
249
+ // (the agent a flag or the environment fixes), "default" (the default
250
+ // connection) or a profile id.
251
+ export function savedAgentName(root, which, env = process.env) {
252
+ const { entry } = userAgentEntry(root, env)
253
+ if (!entry) return null
254
+ if (which === 'fixed') return entry.fixedAgent?.label || null
255
+ if (which === 'default') return (profileForDefault(entry) || implicitDefault(entry))?.label || entry.label || null
256
+ return (entry.profiles || []).find((profile) => profile.id === which)?.label || null
257
+ }
258
+
211
259
  // A file anyone else may write could redirect your key or start a command:
212
260
  // on POSIX the file and its folder must be yours and not group/world-writable.
213
261
  function unsafeOwnership(file) {
@@ -337,9 +337,64 @@ export function hitTest(map, x, y) {
337
337
  return target === undefined ? best : target
338
338
  }
339
339
 
340
- // A short label for the element a comment would pin to (as
341
- // anchors.js describeElement): the last selector step and its text, and
342
- // `large` when it covers a fifth of the page or more.
340
+ // What a reviewer would call an element, from its tag: "Heading", "Button",
341
+ // "Image". Containers are a "Section"; other tags with words in them are "Text".
342
+ const KINDS = {
343
+ h1: 'Heading',
344
+ h2: 'Heading',
345
+ h3: 'Heading',
346
+ h4: 'Heading',
347
+ h5: 'Heading',
348
+ h6: 'Heading',
349
+ a: 'Link',
350
+ button: 'Button',
351
+ summary: 'Button',
352
+ img: 'Image',
353
+ picture: 'Image',
354
+ svg: 'Image',
355
+ video: 'Video',
356
+ input: 'Field',
357
+ textarea: 'Field',
358
+ select: 'Field',
359
+ label: 'Label',
360
+ li: 'List item',
361
+ ul: 'List',
362
+ ol: 'List',
363
+ table: 'Table',
364
+ form: 'Form',
365
+ nav: 'Navigation',
366
+ header: 'Header',
367
+ footer: 'Footer',
368
+ section: 'Section',
369
+ article: 'Section',
370
+ main: 'Section',
371
+ aside: 'Section',
372
+ div: 'Section',
373
+ }
374
+
375
+ // The tag a selector ends on ('' when its last step is an #id).
376
+ export function selectorTag(selector) {
377
+ const last = String(selector || '')
378
+ .split(' > ')
379
+ .pop()
380
+ const match = /^([a-z][a-z0-9-]*)/.exec(last)
381
+ return match ? match[1] : ''
382
+ }
383
+
384
+ // A plain name for an element: its kind and its text ("Heading: Notes that
385
+ // keep up...", "Button: Start free", "Section"). `large`: it covers a big
386
+ // part of the page, so a section says it is the whole of it.
387
+ export function plainLabel(tag, text = '', { large = false, max = 32 } = {}) {
388
+ const words = String(text || '').trim()
389
+ let kind = KINDS[tag] || (words ? 'Text' : 'Element')
390
+ if (large && kind === 'Section') kind = 'Whole section'
391
+ return words ? `${kind}: ${clip(words, max)}` : kind
392
+ }
393
+
394
+ // What hovering shows for the element a comment would pin to (as
395
+ // anchors.js describeElement): `name`, its plain label; `label`, the last
396
+ // selector step and its text (for people who read selectors); and `large`
397
+ // when it covers a fifth of the page or more.
343
398
  export function describeAt(map, position, native) {
344
399
  const item = map.elements[position]
345
400
  const selector = selectorOf(map, position)
@@ -347,9 +402,11 @@ export function describeAt(map, position, native) {
347
402
  const text = item.x || ''
348
403
  const [left, top, width, height] = item.b
349
404
  const area = native?.width && native?.height ? (width * height) / (native.width * native.height) : 0
405
+ const large = area > 0.2
350
406
  return {
407
+ name: plainLabel(item.t, text, { large }),
351
408
  label: `${clip(step, 48)}${text ? ` "${clip(text, 28)}"` : ''}`,
352
- large: area > 0.2,
409
+ large,
353
410
  rect: { left, top, width, height },
354
411
  }
355
412
  }
package/src/cli/args.js CHANGED
@@ -36,6 +36,7 @@ const BOOLEAN_FLAGS = new Set([
36
36
  'new',
37
37
  'status',
38
38
  'pass-token',
39
+ 'takeover',
39
40
  'include-guests',
40
41
  'dry-run',
41
42
  'chat',
@@ -166,6 +167,18 @@ export const COMMAND_FLAGS = {
166
167
  'allow-ci-push',
167
168
  'json',
168
169
  'board',
170
+ // agent connect
171
+ 'agent',
172
+ 'name',
173
+ 'as',
174
+ 'audience',
175
+ 'concurrency',
176
+ 'takeover',
177
+ 'approvals',
178
+ 'allow-command',
179
+ 'allow-path',
180
+ 'auto',
181
+ 'base',
169
182
  ...REMOTE_FLAGS,
170
183
  ],
171
184
  github: ['board', 'json'],
@@ -20,19 +20,34 @@ export async function buzzBridge(flags, out) {
20
20
 
21
21
  export async function settings(flags, out, err) {
22
22
  const { startAgentManagement } = await import('../agent/manage.js')
23
- const management = await startAgentManagement({ config: loadConfig(flags.config), port: Number(flags.port ?? 0), out })
24
- if (flags.open) openBrowser(`${management.url}${management.app.locals.openLink()}`, out)
23
+ // The handlers go in before the server says it is ready. A script (or a
24
+ // quick Ctrl-C) may signal the moment it reads that line, and a signal
25
+ // with no handler yet kills the process outright: no cleanup, and an exit
26
+ // by signal where 0 is meant. A signal that lands while the server is
27
+ // still starting is remembered and acted on as soon as it is up.
28
+ let management = null
25
29
  let stopping = false
26
- const stop = () => {
27
- if (stopping) return
28
- stopping = true
30
+ const close = () =>
29
31
  management.close().catch((error) => {
30
32
  err(`Agent settings cleanup failed: ${error.message}`)
31
33
  process.exitCode = 1
32
34
  })
35
+ const stop = () => {
36
+ if (stopping) return
37
+ stopping = true
38
+ if (management) close()
33
39
  }
34
40
  process.on('SIGINT', stop)
35
41
  process.on('SIGTERM', stop)
42
+ try {
43
+ management = await startAgentManagement({ config: loadConfig(flags.config), port: Number(flags.port ?? 0), out })
44
+ } catch (error) {
45
+ process.removeListener('SIGINT', stop)
46
+ process.removeListener('SIGTERM', stop)
47
+ throw error
48
+ }
49
+ if (stopping) close()
50
+ else if (flags.open) openBrowser(`${management.url}${management.app.locals.openLink()}`, out)
36
51
  return null
37
52
  }
38
53
 
package/src/cli/help.js CHANGED
@@ -132,7 +132,41 @@ export const SECTIONS = {
132
132
  --no-claim hand out every open comment once without claiming it (no agent status, beside other watchers)
133
133
  a command that exits 0 must reply or set a status itself, else the
134
134
  comment becomes needs-human (docs/agent-workflow.md)`,
135
- agent: ` agent run --comment ID the sandboxed starter agent on one comment: a container with only a fresh
135
+ agent: ` agent connect make this machine's coding agent an agent of a hosted project: members chat with it
136
+ on the board, and it reads this folder and answers. Read and answer only unless this
137
+ machine says more (--approvals). The first run is approved in the browser by an admin.
138
+ --remote URL
139
+ --agent NAME which agent: claude, or a saved agent's id that runs Claude Code (default: this
140
+ project's agent, else Claude Code when found). Codex, goose and Gemini CLI are not
141
+ offered in this release. Never a command from the server
142
+ --name "Builder" the name to suggest on the approval page (the approver has the last word)
143
+ --as NAME a second connection from this machine (its own token; default "default")
144
+ --audience owner|server "owner": the server keeps it to the person who connects it even if its audience
145
+ there is widened, and this machine refuses a job the server says is someone else's
146
+ (no protection from a server that lies); "server" (default): its audience on the server
147
+ --approvals none|owner|admins edits from the board. "none" (default): never. "owner": the person who
148
+ connected it may allow each edit on the board. "admins": whoever the server lets
149
+ answer (admins by default). A fix is made on a new branch in a folder of its own,
150
+ never in this checkout. Saved for this connection; the server cannot widen it
151
+ --allow-command "CMD" one exact command the agent may ask to run, each time allowed on the board (adds to
152
+ the list; "none" empties it). Default: no commands at all. Not for Claude Code in
153
+ this release: with its shell tool it runs read-only commands without asking
154
+ --auto none|edits|commands|edits,commands what the server's "allow without asking" rule may apply to
155
+ (default none). Never a file that runs something. Such a fix stays on this machine:
156
+ it is pushed only after a person allows "Push this fix" on its whole diff. With
157
+ --approvals owner, only the person who connected it can switch the rule on
158
+ --allow-path FILE a file that runs on install, build, test or CI (a dotfile, package.json, a Makefile,
159
+ a *.config.js, a script, a test, CI config) the agent may ask to edit; such edits are
160
+ refused otherwise, a named one is always asked, and a fix that changes one is never
161
+ pushed (adds to the list; "none" empties it)
162
+ --base BRANCH the branch a fix starts from (default "head": the commit this checkout is on, and
163
+ then only while it has no uncommitted changes)
164
+ --git-remote NAME where a finished fix is pushed (default origin; "none": never pushed). A pull request
165
+ is opened when GitHub connect is set up here (docs/github.md)
166
+ --takeover close the link another machine holds for this agent, and take its place
167
+ --concurrency N answers at once, 1 to 4 (default 2)
168
+ --token-file FILE for a service: the agent's own token, no browser (docs/hosted.md)
169
+ agent run --comment ID the sandboxed starter agent on one comment: a container with only a fresh
136
170
  worktree, egress to the package registry only (the model is called from here), a branch
137
171
  --pr also push the branch and open a pull request (GitHub connect); not when it
138
172
  touches CI config, manifests or build files unless --allow-ci-push
@@ -213,6 +247,7 @@ export const SECTIONS = {
213
247
  the same commands against a hosted board (--board ID picks one)
214
248
  token: $SHAPEWALL_TOKEN or --token-file FILE (a project token, swp_...)
215
249
  watch --exec commands get no token unless --pass-token
250
+ watch and mcp show on the board as an agent, by the token's name
216
251
  --include-guests comments and watch: also share link guests' comments (untrusted)`,
217
252
  hosted: ` hosted run the hosted server (accounts, workspaces, pushed boards)
218
253
  --data DIR default ./shapewall-hosted-data (or $SHAPEWALL_HOSTED_DATA)
@@ -18,6 +18,7 @@ import { NEEDS, ROLE_ACCESS, tokenCreatorOk } from './permissions.js'
18
18
  import { projectDir } from './projects.js'
19
19
  import { auditAccount } from './tenancy.js'
20
20
  import { ZIP_MAX_BYTES, createZip } from './zip.js'
21
+ import { createChatStore } from './chat-store.js'
21
22
 
22
23
  const AUDIT_PAGE = 50
23
24
  const AUDIT_PAGE_MAX = 200
@@ -332,6 +333,12 @@ export async function writeWorkspaceExport(t, exported, { write, now, iso, expor
332
333
  JSON.stringify({ ...JSON.parse(row.definition), pushedAt: row.pushed_at, pushes: row.push_count }, null, 2),
333
334
  )
334
335
  await zip.add(`${base}comments.json`, JSON.stringify(comments, null, 2))
336
+ // Chat with connected agents: the threads every member reads (the
337
+ // board's and each comment's). A member's own chats are not in a copy
338
+ // an admin downloads; chats.json says how many there are.
339
+ const chats = createChatStore(t).shared(project.id, row.board_id)
340
+ if (chats.threads.length || chats.privateChats)
341
+ await zip.add(`${base}chats.json`, JSON.stringify({ threads: chats.threads, privateChatsNotIncluded: chats.privateChats }, null, 2))
335
342
  for (const [relative, file] of files) {
336
343
  let data
337
344
  try {
@@ -4,9 +4,22 @@ import { randomBytes } from 'node:crypto'
4
4
  import { sha256 } from './crypto.js'
5
5
  import { dispatchHash, AgentPolicyError, agentPolicy } from './agent-policy.js'
6
6
  import { findApiToken } from './tenancy.js'
7
- import { roleAtLeast } from './permissions.js'
7
+ import { canAnswerApproval, roleAtLeast } from './permissions.js'
8
8
 
9
- export function mountHostedApprovals({ v1, boardApi, handle, scope, db, transaction, policyFor, boardContext, needFresh, auditOf, now }) {
9
+ export function mountHostedApprovals({
10
+ v1,
11
+ boardApi,
12
+ handle,
13
+ scope,
14
+ db,
15
+ transaction,
16
+ policyFor,
17
+ agentsFor = null,
18
+ boardContext,
19
+ needFresh,
20
+ auditOf,
21
+ now,
22
+ }) {
10
23
  const error = (statusCode, code, message) => new AgentPolicyError(statusCode, code, message)
11
24
  const keyOf = (req) => ({ project: req.project.id, board: req.params.bid })
12
25
  function validate(req, row) {
@@ -35,6 +48,13 @@ export function mountHostedApprovals({ v1, boardApi, handle, scope, db, transact
35
48
  throw error(409, 'approval_expired', 'This approval no longer matches a live run.')
36
49
  return row
37
50
  }
51
+ // Who may answer an agent's approvals is a setting of that agent (admin by
52
+ // default, or owner): the same rule connected agents' cards will use
53
+ // (src/hosted/permissions.js canAnswerApproval).
54
+ const mayAnswer = (req, row) => {
55
+ const agent = agentsFor?.(req.t).forToken(req.project.id, row.token_id) || null
56
+ return canAnswerApproval(req.role, agent ? { approvalAnswerRole: agent.approval_answer_role } : null)
57
+ }
38
58
  const byId = (req) =>
39
59
  req.t.get('SELECT * FROM agent_approvals WHERE workspace_id = :ws AND project_id = :project AND board_id = :board AND id = :id', {
40
60
  ...keyOf(req),
@@ -49,6 +69,10 @@ export function mountHostedApprovals({ v1, boardApi, handle, scope, db, transact
49
69
  throw error(400, 'invalid_command', 'Command: 1 to 8000 characters.')
50
70
  const ctx = boardContext(req.t, req.project, req.params.bid)
51
71
  const comment = ctx.comments.get(req.params.cid)
72
+ // A comment sent to another agent does not exist for this token, here
73
+ // as on every other route.
74
+ if (agentsFor && !agentsFor(req.t).workCheck(req.agent, req.project.id, comment).ok)
75
+ throw error(404, 'unknown_comment', 'No dispatched comment at that id.')
52
76
  const at = now().toISOString()
53
77
  const id = `sa_${randomBytes(10).toString('hex')}`
54
78
  const claim = req.t.get(
@@ -119,7 +143,7 @@ export function mountHostedApprovals({ v1, boardApi, handle, scope, db, transact
119
143
  approvals: rows.filter((row) => {
120
144
  try {
121
145
  validate(req, row)
122
- return true
146
+ return mayAnswer(req, row)
123
147
  } catch {
124
148
  return false
125
149
  }
@@ -136,6 +160,7 @@ export function mountHostedApprovals({ v1, boardApi, handle, scope, db, transact
136
160
  if (!['approved', 'denied'].includes(req.body?.state)) throw error(400, 'invalid_approval', 'Choose approved or denied.')
137
161
  const row = transaction(db, () => {
138
162
  const row = validate(req, byId(req))
163
+ if (!mayAnswer(req, row)) throw error(403, 'forbidden', "Answering this agent's approvals needs the owner role.")
139
164
  if (row.state !== 'pending' || req.body?.hash !== row.command_hash)
140
165
  throw error(409, 'approval_changed', 'This exact command is no longer pending.')
141
166
  req.t.run(