shapewall 0.3.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/CHANGELOG.md +501 -0
  2. package/README.md +87 -4
  3. package/THIRD_PARTY.md +15 -0
  4. package/dist/agent/package-lock.json +594 -2
  5. package/dist/client/assets/BoardChat-WS8mAIW6.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-Ix9qJvim.js → BuzzDialog-B-Mlr6wF.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-Dx1ZLBR6.js +1 -0
  8. package/dist/client/assets/History-sXhmpcvs.js +1 -0
  9. package/dist/client/assets/LocalSettings-CtGzz9F3.js +1 -0
  10. package/dist/client/assets/{Management-NVFDtSZB.js → Management-CGHe8Wt9.js} +1 -1
  11. package/dist/client/assets/QuickConnect-DEk84E4A.js +1 -0
  12. package/dist/client/assets/{ShareDialog-By0ETg6n.js → ShareDialog-CGGx-AYK.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-RGIw24iZ.js → app-update-dialog-_bVp8hnC.js} +1 -1
  14. package/dist/client/assets/{circle-x-B6KfScOE.js → circle-x-BWoHA1QY.js} +1 -1
  15. package/dist/client/assets/index-Bm-Xd3YN.js +37 -0
  16. package/dist/client/assets/index-C7Ostk3K.css +2 -0
  17. package/dist/client/assets/play-BzQ3tRTv.js +1 -0
  18. package/dist/client/assets/{refresh-cw-vkgvCCfR.js → refresh-cw-BYBMyDKT.js} +1 -1
  19. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  20. package/dist/client/assets/ui-CAY6myRA.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/LocalAccountsApp-CWRguRRL.js +1 -0
  25. package/dist/console/assets/LocalConsole--I2SaIpr.js +2 -0
  26. package/dist/console/assets/LocalUsage-BmpCZ36k.js +1 -0
  27. package/dist/console/assets/app-update-dialog-B8M9plaT.js +1 -0
  28. package/dist/console/assets/app-version-muKrQqbL.js +1 -0
  29. package/dist/console/assets/console-CrhTsPbz.css +2 -0
  30. package/dist/console/assets/console-DxapQ9oS.js +11 -0
  31. package/dist/console/assets/local-agents-CoqD4dSN.js +6 -0
  32. package/dist/console/assets/minus-DDQ0ydcM.js +1 -0
  33. package/dist/console/assets/tailnet-C5Flwl_d.js +2 -0
  34. package/dist/console/assets/theme-DCd0qh4l.js +1 -0
  35. package/dist/console/assets/ui-Bry1mnCY.js +41 -0
  36. package/dist/console/assets/usage-CIPWnHaS.css +1 -0
  37. package/dist/console/assets/usage-CqVjMb7m.js +5 -0
  38. package/dist/console/assets/usage-D1G0GgE3.js +56 -0
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -2
  41. package/docs/agent-hardening.md +206 -0
  42. package/docs/agent-recipes.md +23 -0
  43. package/docs/agent-workflow.md +5 -0
  44. package/docs/agents.md +49 -6
  45. package/docs/architecture.md +10 -4
  46. package/docs/deployment.md +39 -17
  47. package/docs/design-system.md +56 -7
  48. package/docs/hosted.md +1800 -46
  49. package/docs/images/board-overview.png +0 -0
  50. package/docs/images/journeys.png +0 -0
  51. package/docs/images/live-comment.png +0 -0
  52. package/docs/images/phone-comment.png +0 -0
  53. package/docs/images/phone-overview.png +0 -0
  54. package/docs/images/variant.png +0 -0
  55. package/docs/where-to-run.md +119 -3
  56. package/package.json +6 -1
  57. package/src/agent/backends/acp.js +745 -44
  58. package/src/agent/branch-mode.js +17 -3
  59. package/src/agent/card-hash.js +65 -0
  60. package/src/agent/context.js +41 -0
  61. package/src/agent/exec-paths.js +105 -0
  62. package/src/agent/routes.js +23 -2
  63. package/src/agent/run.js +11 -1
  64. package/src/agent/starter/cli.js +6 -1
  65. package/src/agent/turn-changes.js +70 -8
  66. package/src/agent/usage-log.js +251 -0
  67. package/src/cli/args.js +37 -0
  68. package/src/cli/commands.js +20 -5
  69. package/src/cli/help.js +73 -3
  70. package/src/cli/init.js +2 -1
  71. package/src/cli/serve.js +20 -5
  72. package/src/cli.js +8 -0
  73. package/src/hosted/access-cli.js +99 -1
  74. package/src/hosted/activity-core.js +232 -0
  75. package/src/hosted/activity.js +375 -0
  76. package/src/hosted/admin.js +87 -13
  77. package/src/hosted/agent-approvals.js +29 -4
  78. package/src/hosted/agent-link.js +1032 -0
  79. package/src/hosted/agent-policy.js +10 -3
  80. package/src/hosted/agent-presence.js +63 -22
  81. package/src/hosted/agent-routes.js +135 -0
  82. package/src/hosted/agents.js +1206 -0
  83. package/src/hosted/app.js +178 -12
  84. package/src/hosted/auth-routes.js +156 -15
  85. package/src/hosted/auth.js +123 -20
  86. package/src/hosted/board-routes.js +129 -5
  87. package/src/hosted/chat-frames.js +246 -0
  88. package/src/hosted/chat-job.js +204 -0
  89. package/src/hosted/chat-permissions.js +203 -0
  90. package/src/hosted/chat-routes.js +1009 -0
  91. package/src/hosted/chat-store.js +477 -0
  92. package/src/hosted/comment-files.js +11 -1
  93. package/src/hosted/comments.js +1 -1
  94. package/src/hosted/console-routes.js +122 -34
  95. package/src/hosted/db.js +295 -0
  96. package/src/hosted/device-routes.js +88 -10
  97. package/src/hosted/device.js +54 -4
  98. package/src/hosted/events.js +3 -3
  99. package/src/hosted/guards.js +337 -27
  100. package/src/hosted/http.js +6 -3
  101. package/src/hosted/membership.js +22 -3
  102. package/src/hosted/operator-access.js +418 -0
  103. package/src/hosted/operator.js +106 -2
  104. package/src/hosted/ops-cli.js +238 -3
  105. package/src/hosted/pages.js +4 -0
  106. package/src/hosted/passkey-policy.js +75 -0
  107. package/src/hosted/permissions.js +52 -6
  108. package/src/hosted/presence.js +31 -2
  109. package/src/hosted/projects.js +30 -2
  110. package/src/hosted/public.js +4 -4
  111. package/src/hosted/ratelimit.js +14 -0
  112. package/src/hosted/retention.js +18 -2
  113. package/src/hosted/server.js +123 -11
  114. package/src/hosted/shares.js +2 -2
  115. package/src/hosted/step-up-settings.js +68 -0
  116. package/src/hosted/step-up.js +135 -0
  117. package/src/hosted/tailnet-identity.js +24 -0
  118. package/src/hosted/tailnet-routes.js +342 -0
  119. package/src/hosted/tailnet.js +220 -0
  120. package/src/hosted/tailscale.js +75 -9
  121. package/src/hosted/tenancy.js +66 -1
  122. package/src/hosted/token-api.js +119 -20
  123. package/src/hosted/token-events.js +5 -3
  124. package/src/hosted/tokens.js +29 -6
  125. package/src/hosted/turn-hub.js +152 -0
  126. package/src/hosted/usage-core.js +624 -0
  127. package/src/hosted/usage-layout.js +724 -0
  128. package/src/hosted/usage-routes.js +375 -0
  129. package/src/hosted/usage-shape.js +256 -0
  130. package/src/hosted/usage.js +641 -0
  131. package/src/remote/agent-connect.js +469 -0
  132. package/src/remote/agent-fix.js +611 -0
  133. package/src/remote/agent-job.js +216 -0
  134. package/src/remote/agent-link.js +906 -0
  135. package/src/remote/agent-policy-file.js +242 -0
  136. package/src/remote/credentials.js +35 -1
  137. package/src/remote/login.js +44 -9
  138. package/src/remote/share.js +1 -1
  139. package/src/remote/tailnet-cli.js +547 -0
  140. package/src/server/app.js +15 -0
  141. package/src/server/pairing-routes.js +34 -5
  142. package/src/server/tailscale.js +97 -4
  143. package/src/tailnet-proof.js +766 -0
  144. package/dist/client/assets/BoardChat-DxehB761.js +0 -27
  145. package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +0 -1
  146. package/dist/client/assets/History-C9N32kCv.js +0 -1
  147. package/dist/client/assets/LocalSettings-DawtKnvi.js +0 -1
  148. package/dist/client/assets/QuickConnect-DO1TjS1t.js +0 -1
  149. package/dist/client/assets/index-CsqLdqGx.css +0 -2
  150. package/dist/client/assets/index-DnZarJ3U.js +0 -37
  151. package/dist/client/assets/shield-check-QzwGhz0t.js +0 -1
  152. package/dist/client/assets/ui-DI-FGWWK.js +0 -41
  153. package/dist/console/assets/LocalAccountsApp-VOCZg8dg.js +0 -1
  154. package/dist/console/assets/LocalConsole-CMwAW-mF.js +0 -1
  155. package/dist/console/assets/app-update-dialog-Cw6UDqNP.js +0 -1
  156. package/dist/console/assets/console-DgfWmUEx.js +0 -55
  157. package/dist/console/assets/console-Lis0vvdL.css +0 -2
@@ -0,0 +1,251 @@
1
+ // Usage of agents on a local board: one line per agent turn in
2
+ // <outputDir>/agent-usage.jsonl, the same record a hosted server keeps
3
+ // (src/hosted/usage-shape.js usageRecordOf): when, which board and thread
4
+ // kind, who asked (the owner or a viewer, never a name), which agent profile,
5
+ // what kind of turn, how it ended, how long it took, its tool calls by type,
6
+ // and the numbers the agent reported, each null when it reported none.
7
+ // Never the question, the answer, a file or a diff.
8
+ //
9
+ // - Appended after each turn, to a file only its owner reads (0600), under
10
+ // the same kind of file lock as the event log; a line that cannot be
11
+ // written is dropped (a turn never fails over its usage record).
12
+ // - Bounded: past LOG_MAX_BYTES the file is renamed to agent-usage.1.jsonl
13
+ // (the one older file kept) and a new one starts.
14
+ // - Read by the owner's Usage view (Console > Usage on a local board).
15
+
16
+ import fs from 'node:fs'
17
+ import path from 'node:path'
18
+ import { randomBytes } from 'node:crypto'
19
+ import { withFileLock } from '../lock.js'
20
+ import { OUTCOME_GROUP_IDS, outcomeGroup, usageRecordOf } from '../hosted/usage-shape.js'
21
+
22
+ export const USAGE_FILE = 'agent-usage.jsonl'
23
+ export const USAGE_ROTATED = 'agent-usage.1.jsonl'
24
+ export const LOG_MAX_BYTES = 5 * 1024 * 1024
25
+
26
+ const fileOf = (config, name = USAGE_FILE) => path.join(config.outputDir, name)
27
+
28
+ // What one finished turn leaves in the log. `reply`: the answer as stored
29
+ // (its text is not read). `kind`: chat, review (a comment's thread) or fix.
30
+ export function localUsageRow({
31
+ reply,
32
+ boardId,
33
+ threadId,
34
+ commentId = null,
35
+ kind,
36
+ viewer = 'owner',
37
+ agent = {},
38
+ startedAt,
39
+ now = Date.now(),
40
+ }) {
41
+ const record = usageRecordOf(reply)
42
+ const permissions = (Array.isArray(reply.cards) ? reply.cards : []).filter((card) => card.kind === 'permission')
43
+ const allowed = permissions.filter((card) => card.state === 'approved').length
44
+ return {
45
+ id: `run_${randomBytes(12).toString('hex')}`,
46
+ kind,
47
+ startedAt: new Date(startedAt).toISOString(),
48
+ endedAt: new Date(now).toISOString(),
49
+ durationMs: Math.max(0, now - startedAt),
50
+ boardId,
51
+ // The kind of thread, and the comment for a comment's thread. A private
52
+ // chat's id stays out of the log.
53
+ thread: threadId === 'board' ? 'board' : commentId ? 'comment' : 'chat',
54
+ commentNumber: commentId,
55
+ // "owner" or "viewer": a local board has no accounts to name.
56
+ askedBy: viewer === 'owner' ? 'owner' : 'viewer',
57
+ agent: {
58
+ id: String(agent.id || 'default').slice(0, 80),
59
+ name: String(agent.label || agent.id || 'Agent').slice(0, 80),
60
+ backend: agent.backend || null,
61
+ },
62
+ outcome: record.outcome,
63
+ model: record.model || agent.model || null,
64
+ effort: record.effort,
65
+ inputTokens: record.inputTokens,
66
+ outputTokens: record.outputTokens,
67
+ cachedTokens: record.cachedTokens,
68
+ costMicros: record.costMicros,
69
+ contextUsed: record.contextUsed,
70
+ contextSize: record.contextSize,
71
+ steps: record.steps,
72
+ tools: Object.keys(record.tools).length ? record.tools : null,
73
+ approvals: permissions.length ? { asked: permissions.length, allowed, denied: permissions.length - allowed } : null,
74
+ }
75
+ }
76
+
77
+ // Appends one row. The file is the owner's alone (0600, like the event
78
+ // log), and the size check, the rename and the append happen under the
79
+ // file's lock, so two processes never rotate or write at once. Never throws.
80
+ export async function recordLocalTurn(config, row, { maxBytes = LOG_MAX_BYTES } = {}) {
81
+ try {
82
+ const file = fileOf(config)
83
+ const data = Buffer.from(`${JSON.stringify(row)}\n`)
84
+ fs.mkdirSync(config.outputDir, { recursive: true })
85
+ await withFileLock(file, () => {
86
+ let size = 0
87
+ try {
88
+ size = fs.statSync(file).size
89
+ } catch {
90
+ /* a new log */
91
+ }
92
+ if (size > 0 && size + data.length > maxBytes) fs.renameSync(file, fileOf(config, USAGE_ROTATED))
93
+ const fd = fs.openSync(file, 'a', 0o600)
94
+ try {
95
+ // A log that was made wider is narrowed again.
96
+ fs.fchmodSync(fd, 0o600)
97
+ fs.writeSync(fd, data)
98
+ } finally {
99
+ fs.closeSync(fd)
100
+ }
101
+ })
102
+ return true
103
+ } catch {
104
+ return false
105
+ }
106
+ }
107
+
108
+ // Every row newer than `since` (ms), oldest first. Unreadable lines are skipped.
109
+ export function readLocalUsage(config, { since = 0 } = {}) {
110
+ const rows = []
111
+ for (const name of [USAGE_ROTATED, USAGE_FILE]) {
112
+ let text
113
+ try {
114
+ text = fs.readFileSync(fileOf(config, name), 'utf8')
115
+ } catch {
116
+ continue
117
+ }
118
+ for (const line of text.split('\n')) {
119
+ if (!line) continue
120
+ try {
121
+ const row = JSON.parse(line)
122
+ if (row && typeof row.startedAt === 'string' && Date.parse(row.startedAt) >= since) rows.push(row)
123
+ } catch {
124
+ /* a torn line */
125
+ }
126
+ }
127
+ }
128
+ return rows
129
+ }
130
+
131
+ const pad = (value) => String(value).padStart(2, '0')
132
+ // The local day of an instant, in this machine's time zone.
133
+ const dayOf = (ms) => {
134
+ const date = new Date(ms)
135
+ return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
136
+ }
137
+ const sum = (a, b) => (a === null || a === undefined ? (b ?? null) : b === null || b === undefined ? a : a + b)
138
+
139
+ // A set of rows as one group of numbers, in the hosted server's shape
140
+ // (src/hosted/usage.js aggregate), so the same tiles and charts draw it.
141
+ function aggregate(rows) {
142
+ const out = {
143
+ calls: rows.length,
144
+ tokens: null,
145
+ input: null,
146
+ output: null,
147
+ cached: null,
148
+ cost: null,
149
+ duration: null,
150
+ steps: null,
151
+ reported: { tokens: 0, cost: 0, duration: 0 },
152
+ approvals: { asked: null, allowed: null, denied: null, auto: null },
153
+ outcomes: Object.fromEntries(OUTCOME_GROUP_IDS.map((id) => [id, 0])),
154
+ fixes: 0,
155
+ fixesDone: 0,
156
+ }
157
+ for (const row of rows) {
158
+ const tokens = row.inputTokens === null && row.outputTokens === null ? null : (row.inputTokens || 0) + (row.outputTokens || 0)
159
+ out.tokens = sum(out.tokens, tokens)
160
+ out.input = sum(out.input, row.inputTokens)
161
+ out.output = sum(out.output, row.outputTokens)
162
+ out.cached = sum(out.cached, row.cachedTokens)
163
+ out.cost = sum(out.cost, row.costMicros)
164
+ out.duration = sum(out.duration, row.durationMs)
165
+ out.steps = sum(out.steps, row.steps)
166
+ if (tokens !== null) out.reported.tokens += 1
167
+ if (row.costMicros !== null && row.costMicros !== undefined) out.reported.cost += 1
168
+ if (row.durationMs !== null && row.durationMs !== undefined) out.reported.duration += 1
169
+ if (row.approvals) for (const key of ['asked', 'allowed', 'denied']) out.approvals[key] = sum(out.approvals[key], row.approvals[key])
170
+ const group = outcomeGroup(row.outcome)
171
+ out.outcomes[group] += 1
172
+ if (row.kind === 'fix') {
173
+ out.fixes += 1
174
+ if (group === 'completed') out.fixesDone += 1
175
+ }
176
+ }
177
+ return out
178
+ }
179
+ function latency(rows) {
180
+ const values = rows
181
+ .map((row) => row.durationMs)
182
+ .filter((value) => Number.isFinite(value))
183
+ .sort((a, b) => a - b)
184
+ const rank = (share) => (values.length ? values[Math.max(1, Math.ceil(values.length * share)) - 1] : null)
185
+ return { turns: values.length, p50: rank(0.5), p95: rank(0.95), longest: values.at(-1) ?? null }
186
+ }
187
+
188
+ // What the local Usage view shows: the last `days` days against the days
189
+ // before, a series by day split by agent, and the newest turns.
190
+ export function summarizeLocalUsage(config, { days = 30, now = Date.now(), rowLimit = 200 } = {}) {
191
+ const today = new Date(now)
192
+ const end = new Date(today.getFullYear(), today.getMonth(), today.getDate() + 1).getTime()
193
+ const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - days + 1).getTime()
194
+ const before = start - (end - start)
195
+ const all = readLocalUsage(config, { since: before })
196
+ const current = all.filter((row) => Date.parse(row.startedAt) >= start && Date.parse(row.startedAt) < end)
197
+ const previous = all.filter((row) => Date.parse(row.startedAt) < start)
198
+ const buckets = []
199
+ for (let at = start; at < end; at = new Date(new Date(at).getFullYear(), new Date(at).getMonth(), new Date(at).getDate() + 1).getTime())
200
+ buckets.push(dayOf(at))
201
+ const byAgent = new Map()
202
+ const points = new Map()
203
+ for (const row of current) {
204
+ const key = row.agent?.id || 'default'
205
+ if (!byAgent.has(key)) byAgent.set(key, { key, label: row.agent?.name || key, rows: [] })
206
+ byAgent.get(key).rows.push(row)
207
+ const id = `${dayOf(Date.parse(row.startedAt))}\u0000${key}`
208
+ if (!points.has(id)) points.set(id, [])
209
+ points.get(id).push(row)
210
+ }
211
+ const groups = [...byAgent.values()]
212
+ .map((group) => ({ key: group.key, label: group.label, total: aggregate(group.rows) }))
213
+ .sort((a, b) => b.total.calls - a.total.calls)
214
+ const pointsOf = (map) =>
215
+ [...map.entries()].map(([id, rows]) => {
216
+ const [bucket, key] = id.split('\u0000')
217
+ return { bucket, key, ...aggregate(rows) }
218
+ })
219
+ const plain = new Map()
220
+ for (const row of current) {
221
+ const id = `${dayOf(Date.parse(row.startedAt))}\u0000`
222
+ if (!plain.has(id)) plain.set(id, [])
223
+ plain.get(id).push(row)
224
+ }
225
+ return {
226
+ days,
227
+ summary: {
228
+ period: { from: new Date(start).toISOString(), to: new Date(end).toISOString() },
229
+ current: { ...aggregate(current), latency: latency(current) },
230
+ previous: { ...aggregate(previous), latency: latency(previous) },
231
+ },
232
+ series: { bucket: 'day', groupBy: 'agent', buckets, groups, points: pointsOf(points) },
233
+ plain: {
234
+ bucket: 'day',
235
+ groupBy: 'none',
236
+ buckets,
237
+ groups: [{ key: '', label: '', total: aggregate(current) }],
238
+ points: pointsOf(plain),
239
+ },
240
+ rows: current
241
+ .slice()
242
+ .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
243
+ .slice(0, rowLimit)
244
+ .map((row) => ({
245
+ ...row,
246
+ outcomeGroup: outcomeGroup(row.outcome),
247
+ totalTokens: row.inputTokens === null && row.outputTokens === null ? null : (row.inputTokens || 0) + (row.outputTokens || 0),
248
+ })),
249
+ total: current.length,
250
+ }
251
+ }
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',
@@ -53,6 +54,10 @@ const BOOLEAN_FLAGS = new Set([
53
54
  'no-claim',
54
55
  'tailscale',
55
56
  'funnel',
57
+ 'tailnet-sign-in',
58
+ 'tailnet-passkeys',
59
+ 'yes',
60
+ 'link',
56
61
  'setup',
57
62
  'start',
58
63
  'print',
@@ -166,6 +171,23 @@ export const COMMAND_FLAGS = {
166
171
  'allow-ci-push',
167
172
  'json',
168
173
  'board',
174
+ // agent connect
175
+ 'agent',
176
+ 'name',
177
+ 'as',
178
+ 'audience',
179
+ 'concurrency',
180
+ 'takeover',
181
+ 'approvals',
182
+ 'project',
183
+ 'workspace',
184
+ 'used-by',
185
+ 'icon',
186
+ 'tint',
187
+ 'allow-command',
188
+ 'allow-path',
189
+ 'auto',
190
+ 'base',
169
191
  ...REMOTE_FLAGS,
170
192
  ],
171
193
  github: ['board', 'json'],
@@ -196,6 +218,9 @@ export const COMMAND_FLAGS = {
196
218
  export: ['out', 'no-comments', 'browser-comments', 'noindex', 'include-checks'],
197
219
  push: ['remote', 'token-file', 'board', 'include-checks'],
198
220
  share: ['remote', 'token-file', 'board', 'dry-run', 'no-comments', 'include-checks'],
221
+ login: ['remote', 'project', 'workspace'],
222
+ join: ['remote', 'invite'],
223
+ admin: ['remote', 'workspace', 'name', 'login', 'link', 'role', 'days', 'json', 'yes'],
199
224
  hosted: [
200
225
  'data',
201
226
  'origin',
@@ -211,10 +236,22 @@ export const COMMAND_FLAGS = {
211
236
  'tailscale',
212
237
  'tailscale-port',
213
238
  'funnel',
239
+ 'tailnet-sign-in',
240
+ 'tailnet-passkeys',
241
+ 'yes',
242
+ 'role',
243
+ 'workspace',
244
+ 'link',
245
+ 'workspace-name',
246
+ 'login',
247
+ 'handle',
248
+ 'setup-link',
214
249
  'funnel-port',
215
250
  'quotas',
216
251
  'retention-hours',
217
252
  'retention-keep',
253
+ 'usage-days',
254
+ 'owners-see-sign-ins',
218
255
  'setup',
219
256
  'domain',
220
257
  'usercontent-domain',
@@ -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,45 @@ 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
+ --project SLUG on a server with tailnet sign-in, run on a tailnet machine: no browser, your tailnet
144
+ user approves it. --project (and --workspace NAME) pick the project when there are
145
+ several; --used-by owner|trusted who may send it work (default owner: only you);
146
+ --icon NAME and --tint NAME as on the approval page
147
+ --as NAME a second connection from this machine (its own token; default "default")
148
+ --audience owner|server "owner": the server keeps it to the person who connects it even if its audience
149
+ there is widened, and this machine refuses a job the server says is someone else's
150
+ (no protection from a server that lies); "server" (default): its audience on the server
151
+ --approvals none|owner|admins edits from the board. "none" (default): never. "owner": the person who
152
+ connected it may allow each edit on the board. "admins": whoever the server lets
153
+ answer (admins by default). A fix is made on a new branch in a folder of its own,
154
+ never in this checkout. Saved for this connection; the server cannot widen it
155
+ --allow-command "CMD" one exact command the agent may ask to run, each time allowed on the board (adds to
156
+ the list; "none" empties it). Default: no commands at all. Not for Claude Code in
157
+ this release: with its shell tool it runs read-only commands without asking
158
+ --auto none|edits|commands|edits,commands what the server's "allow without asking" rule may apply to
159
+ (default none). Never a file that runs something. Such a fix stays on this machine:
160
+ it is pushed only after a person allows "Push this fix" on its whole diff. With
161
+ --approvals owner, only the person who connected it can switch the rule on
162
+ --allow-path FILE a file that runs on install, build, test or CI (a dotfile, package.json, a Makefile,
163
+ a *.config.js, a script, a test, CI config) the agent may ask to edit; such edits are
164
+ refused otherwise, a named one is always asked, and a fix that changes one is never
165
+ pushed (adds to the list; "none" empties it)
166
+ --base BRANCH the branch a fix starts from (default "head": the commit this checkout is on, and
167
+ then only while it has no uncommitted changes)
168
+ --git-remote NAME where a finished fix is pushed (default origin; "none": never pushed). A pull request
169
+ is opened when GitHub connect is set up here (docs/github.md)
170
+ --takeover close the link another machine holds for this agent, and take its place
171
+ --concurrency N answers at once, 1 to 4 (default 2)
172
+ --token-file FILE for a service: the agent's own token, no browser (docs/hosted.md)
173
+ agent run --comment ID the sandboxed starter agent on one comment: a container with only a fresh
136
174
  worktree, egress to the package registry only (the model is called from here), a branch
137
175
  --pr also push the branch and open a pull request (GitHub connect); not when it
138
176
  touches CI config, manifests or build files unless --allow-ci-push
@@ -204,7 +242,18 @@ export const SECTIONS = {
204
242
  --board ID move only this board (default all)
205
243
  --dry-run show counts; sends nothing
206
244
  --no-comments captures, history and journeys only`,
207
- login: ` login --remote URL get a project token through the browser; saved for the --remote commands`,
245
+ login: ` login --remote URL get a project token through the browser; saved for the --remote commands
246
+ --project SLUG on a server with tailnet sign-in, run on a tailnet machine: no code and no browser,
247
+ your tailnet user approves it (if its role may). --project, and --workspace NAME
248
+ when you are in several, pick the project; with one project neither is needed`,
249
+ join: ` join --remote URL join a workspace on a server with tailnet sign-in, from a tailnet machine: takes the
250
+ invite an admin made for your tailnet login. The role is the invite's
251
+ --invite LINK an invite link (or its code) instead`,
252
+ admin: ` admin projects list|create NAME | members list | agents list | invites create
253
+ a few admin commands on a server with tailnet sign-in, as your tailnet user (the
254
+ server checks your role). --remote URL; --workspace NAME when you are in several
255
+ --login LOGIN invites create: for one tailnet login (ada@example.com); or --link for a link
256
+ --role ROLE viewer, member (default), admin or owner; --days N until it expires; --name; --json`,
208
257
  push: ` push upload the latest captures to a hosted project
209
258
  --include-checks explicitly include private diagnostic reports
210
259
  --remote URL the hosted Shapewall (or $SHAPEWALL_REMOTE)
@@ -213,6 +262,7 @@ export const SECTIONS = {
213
262
  the same commands against a hosted board (--board ID picks one)
214
263
  token: $SHAPEWALL_TOKEN or --token-file FILE (a project token, swp_...)
215
264
  watch --exec commands get no token unless --pass-token
265
+ watch and mcp show on the board as an agent, by the token's name
216
266
  --include-guests comments and watch: also share link guests' comments (untrusted)`,
217
267
  hosted: ` hosted run the hosted server (accounts, workspaces, pushed boards)
218
268
  --data DIR default ./shapewall-hosted-data (or $SHAPEWALL_HOSTED_DATA)
@@ -223,12 +273,28 @@ export const SECTIONS = {
223
273
  --usercontent-origin URL serve live HTML only from this other origin (or $SHAPEWALL_USERCONTENT_ORIGIN)
224
274
  --previous-origin URL while moving to a new origin: the old one (sign-in moves, up to 30 days)
225
275
  --report-email ADDR where "Report this board" on public projects goes
276
+ --owners-see-sign-ins workspace owners see their members' sign-ins and devices in Activity
277
+ (off: each person sees only their own; for a server with one team)
226
278
  --tailscale on your tailnet through tailscale serve (https://<machine>.<tailnet>.ts.net)
227
279
  --tailscale-port N default 443; --funnel: share links public through Tailscale Funnel
228
280
  (share pages only, never the console), on --funnel-port 8443|443|10000
281
+ --tailnet-sign-in with --tailscale: a tailnet user is signed in as the account linked to their tailnet
282
+ login, no passkey (or $SHAPEWALL_HOSTED_TAILNET_SIGN_IN=1). An admin still decides
283
+ who is in a workspace. Needs Linux and Tailscale 1.98+ in its normal (TUN) mode, not
284
+ in a container; refuses to start where it cannot prove that a request came through
285
+ tailscale serve. An identity is per device: what runs as you there can act as you.
286
+ Tailscale is then the only sign-in: no passkeys, and the few things that always ask
287
+ take a typed confirmation
288
+ --tailnet-passkeys with --tailnet-sign-in: also allow passkeys ($SHAPEWALL_HOSTED_TAILNET_PASSKEYS=1, or
289
+ hosted admin passkeys on|off). An account that adds one confirms with it
229
290
  --quotas FILE per-workspace quotas (default <data>/quotas.json when it exists)
230
291
  --retention-hours N prune old versions every N hours (default 6, 0 = off); --retention-keep N (2)
231
292
  hosted setup-link print the first account's one-time link (it is not in the log)
293
+ hosted claim --data DIR --login LOGIN
294
+ with --tailnet-sign-in: make the first account on the server's own machine, no
295
+ browser. Whoever can read the data folder says whose server it is: --login is the
296
+ owner's tailnet login (ada@example.com); --workspace-name NAME. From another tailnet
297
+ device: hosted claim --setup-link URL (the server then sees who asks)
232
298
  --data DIR | --new --new: make a new link (the old one stops working)
233
299
  hosted move-origin --to URL move the server to a new origin (passkeys move with a rebind)
234
300
  --data DIR | --days N | --status window 1 to 30 days (default 30)
@@ -236,11 +302,13 @@ export const SECTIONS = {
236
302
  --usercontent-domain HOST live HTML on its own domain; --email (TLS); --dir (./shapewall-hosted)
237
303
  --source DIR a Shapewall checkout to build from; --dry-run; --force; --start (build, start, setup link)
238
304
  hosted admin list|suspend|resume|delete|export|reports|retention|log the operator's commands
305
+ hosted admin members|invites|projects|passkeys ... who is in a workspace and how people sign in, from the
306
+ server's own machine (shapewall hosted admin help lists them)
239
307
  hosted backup --to DIR [--keep-days N] a consistent copy while the server runs
240
308
  hosted restore --from BACKUP --data NEW | --from BACKUP --check (the restore drill)`,
241
309
  }
242
310
 
243
- const LOCAL_COMMANDS = Object.keys(SECTIONS).filter((name) => !['login', 'push', 'hosted'].includes(name))
311
+ const LOCAL_COMMANDS = Object.keys(SECTIONS).filter((name) => !['login', 'join', 'admin', 'push', 'hosted'].includes(name))
244
312
 
245
313
  const GLOBAL_HELP = `Global
246
314
  --config FILE default ./${CONFIG_FILE} (or $SHAPEWALL_CONFIG)
@@ -255,6 +323,8 @@ ${LOCAL_COMMANDS.map((name) => SECTIONS[name]).join('\n')}
255
323
 
256
324
  Hosted Shapewall (docs/hosted.md)
257
325
  ${SECTIONS.login}
326
+ ${SECTIONS.join}
327
+ ${SECTIONS.admin}
258
328
  ${SECTIONS.push}
259
329
  ${SECTIONS.hosted}
260
330
 
package/src/cli/init.js CHANGED
@@ -142,7 +142,8 @@ export async function init(flags, out, { fetch }) {
142
142
  const gitignore = path.join(path.dirname(file), '.gitignore')
143
143
  // .shapewall/agent-worktrees/ is inside .shapewall/; named too so it stays
144
144
  // ignored if someone narrows the first line (agent branch mode's checkouts).
145
- const wanted = ['.shapewall/', 'shapewall-export/', '*.auth.json', '.shapewall/agent-worktrees/']
145
+ // The agent usage log (who used which agent, when) is named too, for the same reason.
146
+ const wanted = ['.shapewall/', 'shapewall-export/', '*.auth.json', '.shapewall/agent-worktrees/', '.shapewall/agent-usage*.jsonl']
146
147
  const current = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf8') : ''
147
148
  const missing = wanted.filter((line) => !current.split(/\r?\n/).includes(line))
148
149
  if (missing.length) {
package/src/cli/serve.js CHANGED
@@ -3,6 +3,7 @@
3
3
  import fs from 'node:fs'
4
4
  import { randomBytes } from 'node:crypto'
5
5
  import { isLoopback } from '../net.js'
6
+ import http from 'node:http'
6
7
  import https from 'node:https'
7
8
  import { lanAccess, tailscaleAccess } from '../server/tailscale.js'
8
9
  import { loadConfig } from '../config.js'
@@ -94,7 +95,7 @@ export async function serve(flags, out) {
94
95
  const port = flags.port === undefined ? DEFAULT_PORT : Number(flags.port)
95
96
  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('--port must be a port number')
96
97
  if (flags.tailscale && port === 0) throw new Error('--tailscale needs a fixed --port, not 0.')
97
- const tail = flags.tailscale ? await tailscaleAccess({ port, noIdentity: Boolean(flags['no-identity']) }) : null
98
+ const tail = flags.tailscale ? await tailscaleAccess({ port, noIdentity: Boolean(flags['no-identity']), log: out }) : null
98
99
  if (flags.tailscale === 'print') {
99
100
  out(tail.command)
100
101
  out(tail.url)
@@ -150,7 +151,17 @@ export async function serve(flags, out) {
150
151
  log: (line) => out(line),
151
152
  })
152
153
  const tls = flags['tls-cert'] ? { cert: fs.readFileSync(flags['tls-cert']), key: fs.readFileSync(flags['tls-key']) } : null
153
- const server = tls ? https.createServer(tls, app).listen(port, host) : app.listen(port, host)
154
+ // With `--tailscale` and the identity proof, each request is first asked how it came in: the serve
155
+ // entry's secret comes off its path here, before Express and before anything can echo the URL.
156
+ const handler = tail?.gate
157
+ ? (req, res) => {
158
+ tail.gate.admit(req, res).then(
159
+ (ok) => ok && app(req, res),
160
+ () => res.writeHead(500).end(),
161
+ )
162
+ }
163
+ : app
164
+ const server = tls ? https.createServer(tls, handler).listen(port, host) : http.createServer(handler).listen(port, host)
154
165
  watchConfig(config, { log: out, server })
155
166
  await new Promise((resolve, reject) => {
156
167
  server.once('listening', resolve)
@@ -159,8 +170,8 @@ export async function serve(flags, out) {
159
170
  let hostServer = null
160
171
  if (lan && host !== '0.0.0.0') {
161
172
  hostServer = tls
162
- ? https.createServer(tls, app).listen(server.address().port, '127.0.0.1')
163
- : app.listen(server.address().port, '127.0.0.1')
173
+ ? https.createServer(tls, handler).listen(server.address().port, '127.0.0.1')
174
+ : http.createServer(handler).listen(server.address().port, '127.0.0.1')
164
175
  try {
165
176
  await new Promise((resolve, reject) => {
166
177
  hostServer.once('listening', resolve)
@@ -173,7 +184,7 @@ export async function serve(flags, out) {
173
184
  }
174
185
  }
175
186
  try {
176
- await tail?.start()
187
+ await tail?.start(server)
177
188
  } catch (error) {
178
189
  server.close()
179
190
  hostServer?.close()
@@ -188,6 +199,10 @@ export async function serve(flags, out) {
188
199
  `Shapewall is serving ${config.boards.length} board${config.boards.length === 1 ? '' : 's'} at ${accountUrl || `${tls ? 'https' : 'http'}://${shown}:${address.port}/`}`,
189
200
  )
190
201
  if (tail) out(`Private Tailscale board: ${tail.url}${tail.ownerLogin ? '' : ' (pairing required; node has no owner identity)'}`)
202
+ if (tail?.ownerLogin && !tail.gate)
203
+ out(
204
+ `Your other tailnet devices pair like any other device: this machine cannot prove that a request came through tailscale serve (${tail.identityOff}).`,
205
+ )
191
206
  if (lan)
192
207
  out(
193
208
  'LAN pairing is on. Plain HTTP on Wi-Fi exposes the device cookie to sniffing and replay; use --tailscale or --tls-cert/--tls-key. HTTP installs only as a bookmark.',
package/src/cli.js CHANGED
@@ -95,6 +95,14 @@ const COMMANDS = {
95
95
  await login(flags, out)
96
96
  return 0
97
97
  },
98
+ join: async ({ flags, out, fetch }) => {
99
+ const { joinCommand } = await import('./remote/tailnet-cli.js')
100
+ return joinCommand(flags, out, { fetchImpl: fetch })
101
+ },
102
+ admin: async ({ positional, flags, out, fetch }) => {
103
+ const { adminCommand } = await import('./remote/tailnet-cli.js')
104
+ return adminCommand(positional, flags, out, { fetchImpl: fetch })
105
+ },
98
106
  share: async ({ flags, out }) => {
99
107
  const { share } = await import('./remote/share.js')
100
108
  return (await share(flags, out)).code