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,624 @@
1
+ // The parts of the usage queries that are not SQL: who may read what, time
2
+ // zones and buckets, the filter a request names, how grouped numbers become
3
+ // the answers the Usage pages draw, the export's columns, and what a saved
4
+ // view may hold.
5
+ //
6
+ // No imports beyond plain values, so two things share it: the server
7
+ // (src/hosted/usage.js runs the SQL and hands its rows to these functions)
8
+ // and the public demo's in-browser backend (client/src/demo/usage, which
9
+ // groups a fictional set of rows in memory and hands them to the same
10
+ // functions). test/demo-usage.test.js holds the two against each other.
11
+
12
+ import { HttpError } from './http.js'
13
+ import { roleAtLeast } from './permissions.js'
14
+ import { LayoutError, cleanLayout } from './usage-layout.js'
15
+ import {
16
+ KIND_LABEL,
17
+ OUTCOME_GROUP_LABEL,
18
+ OUTCOME_GROUP_IDS,
19
+ USAGE_BUCKETS,
20
+ USAGE_DIMENSIONS,
21
+ USAGE_KINDS,
22
+ USAGE_METRICS,
23
+ outcomeGroup,
24
+ } from './usage-shape.js'
25
+
26
+ export const USAGE_LIMITS = {
27
+ // The longest period one query covers.
28
+ days: 400,
29
+ page: 100,
30
+ pageMax: 500,
31
+ // Rows in one CSV or JSON export, and in a workspace export's usage.json.
32
+ exportRows: 50_000,
33
+ exportPage: 1000,
34
+ listValues: 50,
35
+ // Series drawn in one chart; the rest fold into "Other".
36
+ series: 7,
37
+ views: 30,
38
+ // Entries in one top list.
39
+ top: 10,
40
+ viewName: 60,
41
+ viewQuery: 2000,
42
+ }
43
+ // How long usage records are kept when a workspace has no setting of its own.
44
+ export const USAGE_RETENTION_DAYS = 400
45
+ export const OTHER_KEY = '__other'
46
+
47
+ const DAY = 86_400_000
48
+ const ID_VALUE = /^[A-Za-z0-9_.:@/~-]{1,120}$/
49
+
50
+ // ---- Who may read what ----
51
+
52
+ // null: nothing (the caller answers 403). { all: true }: the workspace.
53
+ // { userId }: that person's own turns and the agents they connected.
54
+ export function usageScope(role, userId) {
55
+ if (!roleAtLeast(role, 'member')) return null
56
+ return roleAtLeast(role, 'admin') ? { all: true, userId } : { all: false, userId }
57
+ }
58
+
59
+ // ---- Time zones ----
60
+
61
+ const formats = new Map()
62
+ function zoneFormat(tz) {
63
+ if (!formats.has(tz)) {
64
+ formats.set(
65
+ tz,
66
+ new Intl.DateTimeFormat('en-US', {
67
+ timeZone: tz,
68
+ hourCycle: 'h23',
69
+ year: 'numeric',
70
+ month: '2-digit',
71
+ day: '2-digit',
72
+ hour: '2-digit',
73
+ minute: '2-digit',
74
+ second: '2-digit',
75
+ }),
76
+ )
77
+ if (formats.size > 200) formats.delete(formats.keys().next().value)
78
+ }
79
+ return formats.get(tz)
80
+ }
81
+ export function validZone(tz) {
82
+ if (typeof tz !== 'string' || !tz || tz.length > 64 || !/^[A-Za-z0-9_+\-/]+$/.test(tz)) return false
83
+ try {
84
+ zoneFormat(tz)
85
+ return true
86
+ } catch {
87
+ return false
88
+ }
89
+ }
90
+ // Minutes a zone is ahead of UTC at an instant.
91
+ export function zoneOffset(tz, ms) {
92
+ const parts = Object.fromEntries(
93
+ zoneFormat(tz)
94
+ .formatToParts(new Date(ms))
95
+ .map((part) => [part.type, Number(part.value)]),
96
+ )
97
+ const local = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second)
98
+ return Math.round((local - Math.floor(ms / 1000) * 1000) / 60_000)
99
+ }
100
+ // The offsets a zone has between two instants, in order: [{ until, offset }]
101
+ // (`until`: the instant this offset ends, null for the last). Every clock
102
+ // change inside the period is kept, however many there are.
103
+ export function zoneSegments(tz, fromMs, toMs) {
104
+ const out = []
105
+ let at = fromMs
106
+ let offset = zoneOffset(tz, at)
107
+ while (at < toMs) {
108
+ const next = Math.min(at + DAY, toMs)
109
+ const after = zoneOffset(tz, next)
110
+ if (after !== offset) {
111
+ // The minute the clocks change.
112
+ let low = at
113
+ let high = next
114
+ while (high - low > 60_000) {
115
+ const middle = low + Math.floor((high - low) / 120_000) * 60_000
116
+ if (zoneOffset(tz, middle) === offset) low = middle
117
+ else high = middle
118
+ }
119
+ out.push({ until: high, offset })
120
+ offset = after
121
+ }
122
+ at = next
123
+ }
124
+ out.push({ until: null, offset })
125
+ return out
126
+ }
127
+ // The instant a wall-clock time (as if it were UTC) is in a zone.
128
+ function wallInstant(tz, wallMs) {
129
+ const guess = wallMs - zoneOffset(tz, wallMs) * 60_000
130
+ return wallMs - zoneOffset(tz, guess) * 60_000
131
+ }
132
+ const pad = (value) => String(value).padStart(2, '0')
133
+ const dateKey = (ms) => {
134
+ const date = new Date(ms)
135
+ return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`
136
+ }
137
+ // The local date of an instant, as "YYYY-MM-DD".
138
+ export function localDate(ms, segments) {
139
+ const segment = segments.find((item) => item.until === null || ms < item.until)
140
+ return dateKey(ms + segment.offset * 60_000)
141
+ }
142
+ // The bucket a local date falls in: itself, its Monday, or its month's first.
143
+ export function bucketOf(date, bucket) {
144
+ if (bucket === 'month') return `${date.slice(0, 7)}-01`
145
+ if (bucket !== 'week') return date
146
+ const ms = Date.parse(`${date}T00:00:00Z`)
147
+ const weekday = (new Date(ms).getUTCDay() + 6) % 7
148
+ return dateKey(ms - weekday * DAY)
149
+ }
150
+ // Every bucket of a period, in order (so a chart shows the empty ones too).
151
+ export function bucketKeys(filter, bucket) {
152
+ const first = bucketOf(localDate(filter.fromMs, filter.segments), bucket)
153
+ const last = bucketOf(localDate(Math.max(filter.fromMs, filter.toMs - 1), filter.segments), bucket)
154
+ const out = []
155
+ let key = first
156
+ while (key <= last && out.length < 1000) {
157
+ out.push(key)
158
+ const ms = Date.parse(`${key}T00:00:00Z`)
159
+ if (bucket === 'month') {
160
+ const date = new Date(ms)
161
+ key = dateKey(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 1))
162
+ } else key = dateKey(ms + (bucket === 'week' ? 7 : 1) * DAY)
163
+ }
164
+ return out
165
+ }
166
+
167
+ // ---- The filter ----
168
+
169
+ // One filter's values. Ids come as a comma list or as the parameter repeated
170
+ // (`split`); a model is whatever an agent reported (brackets, spaces,
171
+ // parentheses, commas), so it comes only as the parameter repeated and is
172
+ // never split. "~" is the empty value (nobody asked, no model reported).
173
+ // eslint-disable-next-line no-control-regex
174
+ const CONTROL = /[\u0000-\u001f\u007f]/
175
+ const list = (value, { allowed = null, split = true } = {}) => {
176
+ if (value === undefined || value === null || value === '') return null
177
+ const given = Array.isArray(value) ? value : [value]
178
+ const items = [
179
+ ...new Set(given.flatMap((item) => (split ? String(item).split(',') : [String(item)])).map((item) => (split ? item.trim() : item))),
180
+ ]
181
+ if (items.length > USAGE_LIMITS.listValues) throw new HttpError(400, 'invalid_filter', 'Too many values in one filter.')
182
+ for (const item of items) {
183
+ const valid = split ? ID_VALUE.test(item) : item.length <= 200 && !CONTROL.test(item)
184
+ if (!item || !valid) throw new HttpError(400, 'invalid_filter', 'A filter value is not valid.')
185
+ if (allowed && !allowed.includes(item))
186
+ throw new HttpError(400, 'invalid_filter', `A filter value is not one of: ${allowed.join(', ')}.`)
187
+ }
188
+ return items.length ? items.map((item) => (item === '~' ? '' : item)) : null
189
+ }
190
+ const instant = (value, name) => {
191
+ if (value === undefined || value === null || value === '') return null
192
+ const ms = typeof value === 'string' && value.length <= 40 ? Date.parse(value) : NaN
193
+ if (!Number.isFinite(ms)) throw new HttpError(400, 'invalid_date', `${name}: an ISO date and time.`)
194
+ return ms
195
+ }
196
+ const whole = (value, name) => {
197
+ if (value === undefined || value === null || value === '') return null
198
+ const number = Number(value)
199
+ if (!Number.isSafeInteger(number) || number < 0) throw new HttpError(400, 'invalid_filter', `${name}: a whole number, 0 and up.`)
200
+ return number
201
+ }
202
+
203
+ // A request's query as a filter. Without a period: the last 30 days.
204
+ export function cleanUsageFilter(query = {}, { now = () => new Date() } = {}) {
205
+ const tz = query.tz === undefined || query.tz === '' ? 'UTC' : query.tz
206
+ if (!validZone(tz)) throw new HttpError(400, 'invalid_zone', 'tz: an IANA time zone name, like Europe/Berlin.')
207
+ const toMs = instant(query.to, 'to') ?? now().getTime()
208
+ const fromMs = instant(query.from, 'from') ?? toMs - 30 * DAY
209
+ if (fromMs >= toMs) throw new HttpError(400, 'invalid_period', 'The period ends before it starts.')
210
+ if (toMs - fromMs > USAGE_LIMITS.days * DAY)
211
+ throw new HttpError(400, 'period_too_long', `A period covers at most ${USAGE_LIMITS.days} days.`)
212
+ const q = typeof query.q === 'string' ? query.q.trim().toLowerCase().slice(0, 80) : ''
213
+ // The period to compare with, when the page names one (the previous
214
+ // calendar month for "this month"): it ends no later than this one starts.
215
+ const prevFromMs = instant(query.prevFrom, 'prevFrom')
216
+ const prevToMs = instant(query.prevTo, 'prevTo')
217
+ if ((prevFromMs === null) !== (prevToMs === null)) throw new HttpError(400, 'invalid_period', 'prevFrom and prevTo go together.')
218
+ if (prevFromMs !== null && (prevFromMs >= prevToMs || prevToMs > fromMs || prevToMs - prevFromMs > USAGE_LIMITS.days * DAY))
219
+ throw new HttpError(400, 'invalid_period', 'The period to compare with ends before this one starts, and covers at most 400 days.')
220
+ return {
221
+ tz,
222
+ fromMs,
223
+ toMs,
224
+ previous: prevFromMs === null ? null : { fromMs: prevFromMs, toMs: prevToMs },
225
+ segments: zoneSegments(tz, fromMs, toMs),
226
+ agents: list(query.agent),
227
+ projects: list(query.project),
228
+ people: list(query.person),
229
+ kinds: list(query.kind, { allowed: USAGE_KINDS }),
230
+ models: list(query.model, { split: false }),
231
+ outcomes: list(query.outcome, { allowed: OUTCOME_GROUP_IDS }),
232
+ tokensMin: whole(query.tokensMin, 'tokensMin'),
233
+ tokensMax: whole(query.tokensMax, 'tokensMax'),
234
+ durationMin: whole(query.durationMin, 'durationMin'),
235
+ durationMax: whole(query.durationMax, 'durationMax'),
236
+ q,
237
+ }
238
+ }
239
+ // The same filter over the period to compare with: the one the page named,
240
+ // or the stretch just before this one that is as long on the wall clock
241
+ // (the same local days and hours, whatever the clocks did in between).
242
+ export function previousPeriod(filter) {
243
+ let { fromMs, toMs } = filter.previous || {}
244
+ if (!filter.previous) {
245
+ const wall = (ms) => ms + zoneOffset(filter.tz, ms) * 60_000
246
+ toMs = filter.fromMs
247
+ fromMs = wallInstant(filter.tz, wall(filter.fromMs) - (wall(filter.toMs) - wall(filter.fromMs)))
248
+ }
249
+ return { ...filter, previous: null, fromMs, toMs, segments: zoneSegments(filter.tz, fromMs, toMs) }
250
+ }
251
+ const oneOf = (value, allowed, fallback, name) => {
252
+ if (value === undefined || value === null || value === '') return fallback
253
+ if (!allowed.includes(value)) throw new HttpError(400, 'invalid_option', `${name}: one of ${allowed.join(', ')}.`)
254
+ return value
255
+ }
256
+ export const cleanBucket = (value) => oneOf(value, USAGE_BUCKETS, 'day', 'bucket')
257
+ export const cleanDimension = (value, fallback = 'agent') => oneOf(value, [...USAGE_DIMENSIONS, 'none'], fallback, 'groupBy')
258
+ export const cleanMetric = (value) => oneOf(value, USAGE_METRICS, 'calls', 'metric')
259
+
260
+ // ---- Views of grouped numbers ----
261
+ //
262
+ // `row` below is one group as the SQL counts it (usage.js AGGREGATES): calls,
263
+ // running, input, output, cached, tokens, tokens_n, cost, cost_n, duration,
264
+ // duration_n, steps, asked, allowed, denied, auto, completed, needs_person,
265
+ // failed, stopped, fixes, fixes_done. A sum over rows that reported nothing
266
+ // is null.
267
+
268
+ const sum = (a, b) => (a === null || a === undefined ? (b ?? null) : b === null || b === undefined ? a : a + b)
269
+ export function aggregate(row) {
270
+ const calls = row?.calls || 0
271
+ const outcomes = {
272
+ completed: row?.completed || 0,
273
+ needs_person: row?.needs_person || 0,
274
+ failed: row?.failed || 0,
275
+ stopped: row?.stopped || 0,
276
+ running: row?.running || 0,
277
+ }
278
+ outcomes.other = Math.max(0, calls - outcomes.completed - outcomes.needs_person - outcomes.failed - outcomes.stopped - outcomes.running)
279
+ return {
280
+ calls,
281
+ tokens: row?.tokens ?? null,
282
+ input: row?.input ?? null,
283
+ output: row?.output ?? null,
284
+ cached: row?.cached ?? null,
285
+ cost: row?.cost ?? null,
286
+ duration: row?.duration ?? null,
287
+ steps: row?.steps ?? null,
288
+ // How many of the turns reported each number ("not reported" is not zero).
289
+ reported: { tokens: row?.tokens_n || 0, cost: row?.cost_n || 0, duration: row?.duration_n || 0 },
290
+ approvals: { asked: row?.asked ?? null, allowed: row?.allowed ?? null, denied: row?.denied ?? null, auto: row?.auto ?? null },
291
+ outcomes,
292
+ fixes: row?.fixes || 0,
293
+ fixesDone: row?.fixes_done || 0,
294
+ }
295
+ }
296
+ export function addAggregates(a, b) {
297
+ if (!a) return b
298
+ const out = { ...a, calls: a.calls + b.calls, fixes: a.fixes + b.fixes, fixesDone: a.fixesDone + b.fixesDone }
299
+ for (const key of ['tokens', 'input', 'output', 'cached', 'cost', 'duration', 'steps']) out[key] = sum(a[key], b[key])
300
+ out.reported = Object.fromEntries(Object.keys(a.reported).map((key) => [key, a.reported[key] + b.reported[key]]))
301
+ out.approvals = Object.fromEntries(Object.keys(a.approvals).map((key) => [key, sum(a.approvals[key], b.approvals[key])]))
302
+ out.outcomes = Object.fromEntries(Object.keys(a.outcomes).map((key) => [key, a.outcomes[key] + b.outcomes[key]]))
303
+ return out
304
+ }
305
+ const metricOf = (item, metric) => (metric === 'calls' ? item.calls : (item[metric] ?? 0))
306
+ export const parseJson = (text, fallback) => {
307
+ try {
308
+ const value = JSON.parse(text)
309
+ return value && typeof value === 'object' ? value : fallback
310
+ } catch {
311
+ return fallback
312
+ }
313
+ }
314
+ export const threadKind = (id) => (!id ? null : id.startsWith('chat-') ? 'chat' : id.startsWith('comment-') ? 'comment' : 'board')
315
+
316
+ // A key of a dimension as people read it. An empty key is the missing value:
317
+ // no agent, nobody, no model reported. `names()`: { agent, project, person }
318
+ // maps of id to { label, ... }, read only when a name is needed.
319
+ export function dimensionLabel(dimension, key, names) {
320
+ if (key === OTHER_KEY) return { label: 'Other' }
321
+ if (dimension === 'agent') return key ? names().agent.get(key) || { label: 'Removed agent' } : { label: 'No agent' }
322
+ if (dimension === 'project') return names().project.get(key) || { label: 'Removed project' }
323
+ if (dimension === 'person') return key ? names().person.get(key) || { label: 'Former member' } : { label: 'Nobody (automatic)' }
324
+ if (dimension === 'model') return { label: key || 'Not reported' }
325
+ if (dimension === 'kind') return { label: KIND_LABEL[key] || key }
326
+ if (dimension === 'outcome') return { label: OUTCOME_GROUP_LABEL[key] || key }
327
+ return { label: key }
328
+ }
329
+
330
+ // One usage record as the pages read it. `row`: the record with its joined
331
+ // names (agent_name, agent_machine, agent_kind, project_name, person_name,
332
+ // person_handle, total_tokens). `labelOf(dimension, key)`; `isMember(userId)`;
333
+ // `linkUrl(row)`: the address of the board it happened on.
334
+ export function usageRowView(row, scope, { detail = false, labelOf, isMember, linkUrl }) {
335
+ const kind = threadKind(row.thread_id)
336
+ // A private chat is its starter's: nobody else gets its id or a link.
337
+ const ownThread = kind !== 'chat' || (Boolean(row.asked_by) && row.asked_by === scope.userId)
338
+ const view = {
339
+ id: row.id,
340
+ kind: row.kind,
341
+ startedAt: row.started_at,
342
+ endedAt: row.ended_at,
343
+ durationMs: row.duration_ms,
344
+ outcome: row.outcome,
345
+ outcomeGroup: outcomeGroup(row.outcome),
346
+ agent: row.agent_id
347
+ ? {
348
+ id: row.agent_id,
349
+ name: row.agent_name || 'Removed agent',
350
+ machine: row.agent_machine || null,
351
+ kind: row.agent_kind || null,
352
+ // Whether it still has a page to link to.
353
+ exists: Boolean(row.agent_name),
354
+ }
355
+ : null,
356
+ project: { id: row.project_id, name: row.project_name || 'Removed project' },
357
+ person: row.asked_by
358
+ ? {
359
+ id: row.asked_by,
360
+ name: row.person_name || 'Former member',
361
+ handle: row.person_handle || null,
362
+ // Still in this workspace (someone who left has no page here).
363
+ member: isMember(row.asked_by),
364
+ }
365
+ : null,
366
+ boardId: row.board_id,
367
+ commentNumber: row.comment_number,
368
+ thread: kind ? { kind, private: kind === 'chat', id: ownThread ? row.thread_id : null } : null,
369
+ model: row.model,
370
+ effort: row.effort,
371
+ inputTokens: row.input_tokens,
372
+ outputTokens: row.output_tokens,
373
+ cachedTokens: row.cached_tokens,
374
+ totalTokens: row.total_tokens ?? null,
375
+ costMicros: row.cost_micros,
376
+ steps: row.steps,
377
+ approvals: {
378
+ asked: row.approvals_asked,
379
+ allowed: row.approvals_allowed,
380
+ denied: row.approvals_denied,
381
+ auto: row.approvals_auto,
382
+ },
383
+ }
384
+ if (!detail) return view
385
+ const by = parseJson(row.approvals_by, {})
386
+ return {
387
+ ...view,
388
+ agentMs: row.agent_ms,
389
+ tools: parseJson(row.tools, null),
390
+ contextUsed: row.window_used,
391
+ contextSize: row.window_size,
392
+ claimId: row.claim_id,
393
+ approvals: {
394
+ ...view.approvals,
395
+ // Who answered the requests that waited for a person.
396
+ by: Object.entries(by).map(([userId, counts]) => ({
397
+ userId,
398
+ name: labelOf('person', userId).label,
399
+ allowed: Number(counts?.allowed) || 0,
400
+ denied: Number(counts?.denied) || 0,
401
+ })),
402
+ },
403
+ // Where it happened, for people who may read it there: members and up
404
+ // read a board's shared threads; a private chat only its starter.
405
+ link:
406
+ row.board_id && ownThread && row.project_name
407
+ ? {
408
+ url: linkUrl(row),
409
+ label: row.comment_number ? `Comment #${row.comment_number}` : kind === 'chat' ? 'Your chat on this board' : 'The board',
410
+ }
411
+ : null,
412
+ }
413
+ }
414
+
415
+ // Turn duration percentiles (nearest rank) of one group: the median, and
416
+ // the 90th, 95th and 99th. `row` { n, p50, p90, p95, p99, longest }, or
417
+ // nothing for a group with no turns.
418
+ export const latencyView = (row) => ({
419
+ turns: row?.n || 0,
420
+ p50: row?.p50 ?? null,
421
+ p90: row?.p90 ?? null,
422
+ p95: row?.p95 ?? null,
423
+ p99: row?.p99 ?? null,
424
+ longest: row?.longest ?? null,
425
+ })
426
+ // The rank (from 1) of the `percent`th percentile among `n` values, nearest rank.
427
+ export const percentileRank = (n, percent) => Math.max(1, Math.floor((n * percent + 99) / 100))
428
+ // How many entries a top list holds: 5 unless asked, at most USAGE_LIMITS.top.
429
+ export const cleanTopLimit = (value) => {
430
+ if (value === undefined || value === null || value === '') return 5
431
+ const count = Number(value)
432
+ if (!Number.isInteger(count) || count < 1 || count > USAGE_LIMITS.top)
433
+ throw new HttpError(400, 'invalid_option', `limit: 1 to ${USAGE_LIMITS.top}.`)
434
+ return count
435
+ }
436
+ // Per bucket, every bucket present. `rows`: [{ b, n, p50, p90, p95, p99, longest }].
437
+ export function latencyBuckets(rows, filter, bucket) {
438
+ const found = new Map(rows.map((row) => [row.b, row]))
439
+ return bucketKeys(filter, bucket).map((key) => ({ bucket: key, ...latencyView(found.get(key)) }))
440
+ }
441
+
442
+ // The period split by one dimension, largest first. `rows`: [{ k, ...group }].
443
+ export function breakdownView(rows, groupBy, labelOf) {
444
+ return rows
445
+ .map((row) => ({ key: row.k, ...labelOf(groupBy, row.k), ...aggregate(row) }))
446
+ .sort((a, b) => b.calls - a.calls || String(a.label).localeCompare(String(b.label)))
447
+ }
448
+
449
+ // The period over time: one point per bucket and group, every bucket
450
+ // present. More groups than a chart can show fold into "Other", ranked by
451
+ // `metric`. `rows`: [{ b, k, ...group }], one per bucket and key.
452
+ export function seriesView(rows, filter, { bucket, groupBy, metric }, labelOf) {
453
+ const byKey = new Map()
454
+ for (const row of rows) {
455
+ const item = aggregate(row)
456
+ byKey.set(row.k, addAggregates(byKey.get(row.k), item))
457
+ }
458
+ const ranked = [...byKey.entries()].sort((a, b) => metricOf(b[1], metric) - metricOf(a[1], metric) || b[1].calls - a[1].calls)
459
+ const keep = new Set(ranked.slice(0, USAGE_LIMITS.series).map(([key]) => key))
460
+ const folded = ranked.length > USAGE_LIMITS.series
461
+ const points = new Map()
462
+ for (const row of rows) {
463
+ const key = keep.has(row.k) ? row.k : OTHER_KEY
464
+ const id = `${row.b}\u0000${key}`
465
+ points.set(id, addAggregates(points.get(id), aggregate(row)))
466
+ }
467
+ const groups = ranked.slice(0, USAGE_LIMITS.series).map(([key, total]) => ({ key, ...labelOf(groupBy, key), total }))
468
+ if (folded)
469
+ groups.push({
470
+ key: OTHER_KEY,
471
+ label: `Other (${ranked.length - USAGE_LIMITS.series})`,
472
+ total: ranked.slice(USAGE_LIMITS.series).reduce((all, [, item]) => addAggregates(all, item), null),
473
+ })
474
+ return {
475
+ bucket,
476
+ groupBy,
477
+ buckets: bucketKeys(filter, bucket),
478
+ groups,
479
+ points: [...points.entries()].map(([id, item]) => {
480
+ const [at, key] = id.split('\u0000')
481
+ return { bucket: at, key, ...item }
482
+ }),
483
+ }
484
+ }
485
+
486
+ // The "top" lists that come from the split by agent (breakdownView).
487
+ export function topAgents(agents, limit = 5) {
488
+ return {
489
+ agents: agents.slice(0, limit).map((item) => ({ key: item.key, label: item.label, machine: item.machine || null, calls: item.calls })),
490
+ denied: agents
491
+ .filter((item) => (item.approvals.denied || 0) > 0)
492
+ .sort((a, b) => b.approvals.denied - a.approvals.denied)
493
+ .slice(0, limit)
494
+ .map((item) => ({ key: item.key, label: item.label, denied: item.approvals.denied, asked: item.approvals.asked })),
495
+ }
496
+ }
497
+ // One of the threads that used the most tokens. `item`: { project_id,
498
+ // project_name, board_id, thread_id, comment_number, asked_by, calls, tokens }.
499
+ export function topThread(item, scope) {
500
+ const kind = threadKind(item.thread_id)
501
+ return {
502
+ project: { id: item.project_id, name: item.project_name || 'Removed project' },
503
+ boardId: item.board_id,
504
+ commentNumber: item.comment_number,
505
+ thread: { kind, private: kind === 'chat', id: kind !== 'chat' || item.asked_by === scope.userId ? item.thread_id : null },
506
+ calls: item.calls,
507
+ tokens: item.tokens,
508
+ }
509
+ }
510
+
511
+ // One project's budgets with today's use (the day is UTC, as the policy
512
+ // counts it), the last week's daily average, and a forecast for the end of
513
+ // the day when enough of the day has passed to make one. `used`, `week`:
514
+ // { turns, fixes } counted today and over the seven days before.
515
+ export function budgetDay(at) {
516
+ const dayStart = `${at.toISOString().slice(0, 10)}T00:00:00.000Z`
517
+ return {
518
+ dayStart,
519
+ elapsed: (at.getTime() - Date.parse(dayStart)) / DAY,
520
+ weekStart: new Date(Date.parse(dayStart) - 7 * DAY).toISOString(),
521
+ }
522
+ }
523
+ export function projectBudgets(project, policy, used, week, { dayStart, elapsed }) {
524
+ const budget = (id, label, limit, count, weekly) => {
525
+ // A forecast only with a third of the day gone and a few turns to go by.
526
+ const forecast = elapsed >= 1 / 3 && count >= 5 ? Math.round(count / elapsed) : null
527
+ return {
528
+ id,
529
+ label,
530
+ limit,
531
+ used: count,
532
+ average: Math.round(((weekly || 0) / 7) * 10) / 10,
533
+ forecast,
534
+ resetsAt: new Date(Date.parse(dayStart) + DAY).toISOString(),
535
+ }
536
+ }
537
+ return {
538
+ project: { id: project.id, name: project.name },
539
+ budgets: [
540
+ budget('dailyTurns', 'Chat turns today', policy.dailyTurns, used?.turns || 0, week?.turns),
541
+ budget('dailyClaims', 'Fixes taken today', policy.dailyClaims, used?.fixes || 0, week?.fixes),
542
+ ],
543
+ }
544
+ }
545
+
546
+ // ---- Export formats ----
547
+
548
+ // A CSV cell: quoted, and never starting like a spreadsheet formula.
549
+ export function csvCell(value) {
550
+ let text = String(value ?? '')
551
+ if (/^[=+\-@\t\r]/.test(text)) text = `'${text}`
552
+ return `"${text.replace(/"/g, '""')}"`
553
+ }
554
+ export const USAGE_CSV_COLUMNS = [
555
+ ['started_at', (row) => row.startedAt],
556
+ ['ended_at', (row) => row.endedAt],
557
+ ['kind', (row) => row.kind],
558
+ ['outcome', (row) => row.outcome],
559
+ ['agent', (row) => row.agent?.name],
560
+ ['agent_id', (row) => row.agent?.id],
561
+ ['machine', (row) => row.agent?.machine],
562
+ ['project', (row) => row.project.name],
563
+ ['project_id', (row) => row.project.id],
564
+ ['board', (row) => row.boardId],
565
+ ['comment', (row) => row.commentNumber],
566
+ ['person', (row) => row.person?.name],
567
+ ['person_handle', (row) => row.person?.handle],
568
+ ['model', (row) => row.model],
569
+ ['effort', (row) => row.effort],
570
+ ['duration_ms', (row) => row.durationMs],
571
+ ['agent_reported_ms', (row) => row.agentMs],
572
+ ['input_tokens', (row) => row.inputTokens],
573
+ ['output_tokens', (row) => row.outputTokens],
574
+ ['cached_tokens', (row) => row.cachedTokens],
575
+ // Only a cost the agent reported; empty when it reported none.
576
+ ['reported_cost_usd', (row) => (row.costMicros === null || row.costMicros === undefined ? null : (row.costMicros / 1e6).toFixed(6))],
577
+ ['steps', (row) => row.steps],
578
+ ['tool_calls', (row) => (row.tools ? JSON.stringify(row.tools) : null)],
579
+ ['approvals_asked', (row) => row.approvals.asked],
580
+ ['approvals_allowed', (row) => row.approvals.allowed],
581
+ ['approvals_denied', (row) => row.approvals.denied],
582
+ ['approvals_auto', (row) => row.approvals.auto],
583
+ ['context_used', (row) => row.contextUsed],
584
+ ['context_size', (row) => row.contextSize],
585
+ ['run_id', (row) => row.id],
586
+ ]
587
+ export const usageCsvHeader = () => `${USAGE_CSV_COLUMNS.map(([name]) => csvCell(name)).join(',')}\r\n`
588
+ export const usageCsvLine = (row) => `${USAGE_CSV_COLUMNS.map(([, read]) => csvCell(read(row))).join(',')}\r\n`
589
+
590
+ // ---- Saved views ----
591
+
592
+ // A view is a name and a query string (the same one the page keeps in its
593
+ // address). What one may hold: { page, name, query } checked, or an HttpError.
594
+ const VIEW_PAGES = ['usage', 'activity']
595
+ const VIEW_QUERY = /^[A-Za-z0-9_\-.,:%=&+~*]*$/
596
+ export function cleanView({ page, name, query } = {}) {
597
+ if (!VIEW_PAGES.includes(page)) throw new HttpError(400, 'invalid_view', `page: one of ${VIEW_PAGES.join(', ')}.`)
598
+ const label = String(name ?? '')
599
+ .replace(/\s+/g, ' ')
600
+ // eslint-disable-next-line no-control-regex
601
+ .replace(/[\u0000-\u001f\u007f]/g, '')
602
+ .trim()
603
+ if (!label || label.length > USAGE_LIMITS.viewName)
604
+ throw new HttpError(400, 'invalid_view', `View name: 1 to ${USAGE_LIMITS.viewName} characters.`)
605
+ if (typeof query !== 'string' || query.length > USAGE_LIMITS.viewQuery || !VIEW_QUERY.test(query))
606
+ throw new HttpError(400, 'invalid_view', 'query: the filters as the page keeps them in its address.')
607
+ return { page, name: label, query }
608
+ }
609
+ // The layout a saved view of the Usage page may carry: checked, or nothing.
610
+ export function cleanViewLayout(page, layout) {
611
+ if (layout === null || layout === undefined) return null
612
+ if (page !== 'usage') throw new HttpError(400, 'invalid_view', 'Only a view of the Usage page carries a layout.')
613
+ return checkedLayout(layout)
614
+ }
615
+ // A dashboard layout as it may be stored (usage-layout.js), or an HttpError.
616
+ export function checkedLayout(layout) {
617
+ try {
618
+ return cleanLayout(layout)
619
+ } catch (error) {
620
+ if (error instanceof LayoutError) throw new HttpError(error.code === 'layout_too_large' ? 413 : 400, error.code, error.message)
621
+ throw error
622
+ }
623
+ }
624
+ export const tooManyViews = () => new HttpError(409, 'too_many_views', `You have ${USAGE_LIMITS.views} saved views here. Delete one first.`)