visualproof 0.5.0 → 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 (58) hide show
  1. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  2. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  3. package/dist/assets/tips/tour-agent.webp +0 -0
  4. package/dist/assets/tips/tour-arrange.webp +0 -0
  5. package/dist/assets/tips/tour-artwork.webp +0 -0
  6. package/dist/assets/tips/tour-checks.webp +0 -0
  7. package/dist/assets/tips/tour-keys.webp +0 -0
  8. package/dist/assets/tips/tour-library.webp +0 -0
  9. package/dist/assets/tips/tour-project.webp +0 -0
  10. package/dist/assets/tips/tour-review.webp +0 -0
  11. package/dist/assets/tips/tour-share.webp +0 -0
  12. package/dist/assets/tips/tour-source.webp +0 -0
  13. package/dist/assets/tips/tour-target.webp +0 -0
  14. package/dist/assets/tips/tour-view.webp +0 -0
  15. package/dist/assets/tips/tour.json +125 -115
  16. package/dist/assets/tips/tour.webp +0 -0
  17. package/dist/mcp/visualproof-mcp.mjs +20 -9
  18. package/dist/server/access.js +28 -0
  19. package/dist/server/agent.js +137 -49
  20. package/dist/server/askfollow.js +1 -1
  21. package/dist/server/deploy.js +204 -53
  22. package/dist/server/invites.js +113 -20
  23. package/dist/server/live.js +125 -28
  24. package/dist/server/main.js +216 -69
  25. package/dist/server/mcptools.js +33 -20
  26. package/dist/server/presence.js +3 -3
  27. package/dist/server/prompt.js +8 -3
  28. package/dist/server/readonlygate.js +4 -4
  29. package/dist/server/reviewapi.js +51 -17
  30. package/dist/server/talk.js +231 -115
  31. package/dist/server/tokens.js +10 -2
  32. package/dist/shared/build.js +35 -1
  33. package/dist/shared/collab.js +8 -0
  34. package/dist/shared/keys.js +66 -37
  35. package/dist/shared/lostfound.js +1 -0
  36. package/dist/shared/mentions.js +83 -0
  37. package/dist/shared/query.js +13 -4
  38. package/dist/shared/review.js +91 -21
  39. package/dist/shared/reviewqueue.js +6 -1
  40. package/dist/web/bundle/app.js +3068 -1928
  41. package/dist/web/index.html +45 -9
  42. package/dist/web/src/reviewqueue.js +52 -19
  43. package/dist/web/src/trust.js +271 -0
  44. package/dist/web/style.css +181 -70
  45. package/docs/agent-api/README.md +13 -11
  46. package/docs/agent-api/advice.md +8 -2
  47. package/docs/agent-api/export.md +1 -1
  48. package/docs/agent-api/following.md +11 -12
  49. package/docs/agent-api/history.md +3 -2
  50. package/docs/agent-api/mcp.md +15 -15
  51. package/docs/agent-api/notes.md +1 -1
  52. package/docs/agent-api/reading.md +2 -2
  53. package/docs/agent-api/requests.md +12 -15
  54. package/docs/agent-api/talking.md +60 -55
  55. package/docs/agent-api/tcb.md +21 -21
  56. package/docs/agent-api/views.md +3 -4
  57. package/docs/agent-api/words.md +8 -8
  58. package/package.json +2 -1
@@ -13,7 +13,7 @@
13
13
  // written in, the exact contexts — come as the next version of the graph. Where every module's
14
14
  // result is cached, the merged graph is the first one served.
15
15
  import { randomBytes } from "node:crypto";
16
- import { sameName } from "../shared/collab.js";
16
+ import { madeBy, nameKey, sameName } from "../shared/collab.js";
17
17
  import { prepare } from "./pipeline.js";
18
18
  import { extract, loadSaved } from "./extract.js";
19
19
  import { DEFAULT_JOBS, UsagePass, mergeUsage, saveMerged } from "./usage.js";
@@ -25,10 +25,11 @@ import { agentKey, Presence } from "./presence.js";
25
25
  import { AgentTokens } from "./tokens.js";
26
26
  import { Invites } from "./invites.js";
27
27
  import { ReadOnlyLinks } from "./readonly.js";
28
- import { Talk } from "./talk.js";
28
+ import { forPages, PUBLIC, Talk } from "./talk.js";
29
29
  import { Asks } from "./askfollow.js";
30
30
  import { BuildTracker, compiling, importable, outputsOf, probeAll, scanModules, stampOf } from "./status.js";
31
31
  import { BuildWatch, moduleDirs, shouldLook } from "./buildwatch.js";
32
+ import { buildChanges } from "../shared/build.js";
32
33
  import { Views } from "./views.js";
33
34
  import { graphOf, memoryProblem, titleContext } from "./agentviews.js";
34
35
  import { ownName, rebinder, versionBase, versions, withVersions } from "./versions.js";
@@ -65,6 +66,13 @@ export const MAX_STREAMS_PER_SESSION = 4;
65
66
  export const MAX_BUFFERED = 4 << 20;
66
67
  /** the list of who is here goes out at most this often: a burst of heartbeats is one event */
67
68
  const PRESENCE_EVERY = 500;
69
+ /** A change of the build status larger than this, and than this part of the whole (about what the
70
+ * whole takes compressed: 42 KB of NavierStokesAndEuler's 362), goes out as its revision alone
71
+ * (`build-rev`), which every page reads compressed (GET /api/build) rather than take it uncompressed
72
+ * on its stream: the first look, an edit or a build that starts or fails under much of a large
73
+ * project. A smaller one is no saving worth a request. */
74
+ export const BUILD_DELTA_MAX = 64 << 10;
75
+ export const BUILD_DELTA_PART = 1 / 8;
68
76
  /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
69
77
  const moduleFiles = new WeakMap();
70
78
  export class Live {
@@ -85,6 +93,12 @@ export class Live {
85
93
  lastLook = 0;
86
94
  lastRunning = "";
87
95
  buildText = "";
96
+ /** the build status's revision (`build-rev`, `build-delta`), counted from 0, before the first look,
97
+ * in this server's process; each file's status as last sent, as JSON, by module; and the whole as
98
+ * GET /api/build answers it, made when first asked */
99
+ buildRev = 0;
100
+ buildFiles = new Map();
101
+ buildWholeText = null;
88
102
  build = null;
89
103
  graph = null;
90
104
  extracting = false;
@@ -174,11 +188,13 @@ export class Live {
174
188
  this.invites = new Invites(dirs.site);
175
189
  // every page knows the names the people invited by a link go by, so that what each did shows
176
190
  // under the name they go by now; a link revoked cuts its pages off at once, as it does its
177
- // requests: their streams end, and come back only if the key lets them in
191
+ // requests: their streams end, and come back only if the key lets them in. A link made anew
192
+ // does the same, but to the page that made it anew (`keep`): the other pages of its browser,
193
+ // given the new cookie, come back as they were
178
194
  this.invites.onChanged = () => this.send("people", this.invites.people());
179
- this.invites.onEnded = (r) => {
195
+ this.invites.onEnded = (r, keep) => {
180
196
  for (const st of [...this.streams.values()])
181
- if (st.person === r.id)
197
+ if (st.person === r.id && (keep === undefined || st.token !== keep))
182
198
  this.close(st);
183
199
  };
184
200
  this.readOnly = new ReadOnlyLinks(dirs.site);
@@ -250,12 +266,8 @@ export class Live {
250
266
  this.tokens.onEnded = (r) => this.talk.close(r.id, r.revoked ? "revoked" : "expired");
251
267
  this.talk.inForce = (id) => this.tokens.inForce().some((r) => r.id === id);
252
268
  this.talk.onState = (id, talk) => this.presence.setTalk(id, talk);
253
- // a new message goes to every page, named by the agent's entry in presence
254
- this.talk.onMessage = (id, message) => {
255
- const r = this.tokens.get(id);
256
- if (r)
257
- this.send("chat", { agent: agentKey({ name: r.name, token: r.id }), message });
258
- };
269
+ // a new message goes to the pages that may read its channel (CollabSpec decision 13)
270
+ this.talk.onMessage = (channel, message) => this.sendChat(channel, message);
259
271
  this.views.pageOf = (token) => (typeof token === "string" ? this.byToken.get(token)?.id ?? null : null);
260
272
  // the views a private page holds live while a page of its session is open
261
273
  this.views.sessionOpen = (session) => [...this.streams.values()].some((st) => st.session === session);
@@ -306,10 +318,14 @@ export class Live {
306
318
  * stream that closed, a guess), and nothing changes. A private page's (`priv`, CollabSpec
307
319
  * decision 8) is counted and nothing more is kept of it: not its name, not where it is.
308
320
  * `verified`: the page of someone invited by a personal link (decision 9). */
309
- beat(token, name, view, idle, priv = false, verified = false) {
321
+ beat(token, name, view, idle, priv = false, verified = false, who = name) {
310
322
  const s = typeof token === "string" ? this.byToken.get(token) : undefined;
311
323
  if (!s)
312
324
  return false;
325
+ // the name the page goes by, said by its heartbeat's request, a private page's too (`who`): what
326
+ // of the channels its stream is sent (CollabSpec decision 13)
327
+ if (s.readOnly === null)
328
+ s.name = who;
313
329
  if (s.private !== priv)
314
330
  this.rename(s, priv, name, view, idle, verified);
315
331
  else if (priv)
@@ -397,6 +413,41 @@ export class Live {
397
413
  this.reversion();
398
414
  this.lostChanged();
399
415
  }
416
+ /** The build status a look found (the live loop's tick): where it changed, every page is told the
417
+ * files whose status changed, with the new revision (`build-delta`), which it applies to the
418
+ * status it holds; a large change (BUILD_DELTA_MAX) goes out as the revision alone (`build-rev`),
419
+ * at which each page reads the whole (GET /api/build). A page from before 0.6.0 is sent the
420
+ * whole (`build`), as it was. */
421
+ buildFound(build) {
422
+ const text = JSON.stringify(build);
423
+ this.build = build;
424
+ if (text === this.buildText)
425
+ return;
426
+ this.buildText = text;
427
+ this.buildWholeText = null;
428
+ const base = this.buildRev++;
429
+ const { files, gone, texts } = buildChanges(this.buildFiles, build);
430
+ this.buildFiles = texts;
431
+ if (this.streams.size) {
432
+ const delta = { epoch: this.instance, base, rev: this.buildRev, active: build.active, progress: build.progress, counts: build.counts, files, gone };
433
+ const d = JSON.stringify(delta);
434
+ const news = d.length > Math.max(BUILD_DELTA_MAX, text.length * BUILD_DELTA_PART) ? `event: build-rev\ndata: ${JSON.stringify(this.buildRevNow())}\n\n` : `event: build-delta\ndata: ${d}\n\n`;
435
+ let whole = null;
436
+ for (const st of [...this.streams.values()])
437
+ this.push(st, st.buildDeltas ? news : (whole ??= `event: build\ndata: ${text}\n\n`));
438
+ }
439
+ this.timeline.buildStatus(build);
440
+ }
441
+ /** Which build status the server holds (`build-rev`): its process and its revision. */
442
+ buildRevNow() {
443
+ return { epoch: this.instance, rev: this.buildRev };
444
+ }
445
+ /** The whole build status as GET /api/build answers it, with its revision, and the tag of that
446
+ * revision: written once a revision, whoever asks. */
447
+ buildWhole() {
448
+ this.buildWholeText ??= `{"epoch":${JSON.stringify(this.instance)},"rev":${this.buildRev},"status":${this.buildText || "null"}}`;
449
+ return { tag: `"b${this.instance}.${this.buildRev}"`, text: this.buildWholeText };
450
+ }
400
451
  say(line) {
401
452
  this.log.push(line);
402
453
  if (this.log.length > 200)
@@ -516,13 +567,7 @@ export class Live {
516
567
  const d = this.deploy;
517
568
  if (d && d.busy && !build.active)
518
569
  build = { ...build, active: true };
519
- const text = JSON.stringify(build);
520
- this.build = build;
521
- if (text !== this.buildText) {
522
- this.buildText = text;
523
- this.send("build", build);
524
- this.timeline.buildStatus(build);
525
- }
570
+ this.buildFound(build);
526
571
  // and its builds, beside the files: the one going on, the newest commit waiting, the last
527
572
  if (d) {
528
573
  const now = JSON.stringify(d.status(true));
@@ -1171,8 +1216,10 @@ export class Live {
1171
1216
  st.res.end(text);
1172
1217
  }
1173
1218
  }
1174
- /** What /api/status says: enough for the loader and for a page that just connected. */
1175
- status() {
1219
+ /** What /api/status says: enough for the loader and for a page that just connected. `brief`: the
1220
+ * build status without its files (the page's loader, which reads them by GET /api/build). */
1221
+ status(brief = false) {
1222
+ const b = this.build;
1176
1223
  return {
1177
1224
  state: this.graph ? "ready" : this.extractError ? "error" : "extracting",
1178
1225
  error: this.graph ? undefined : this.extractError ?? undefined,
@@ -1182,7 +1229,7 @@ export class Live {
1182
1229
  graph: this.graphInfo(),
1183
1230
  // the usage pass: how far it is, and the modules it could not elaborate
1184
1231
  usage: this.usage.status,
1185
- build: this.build,
1232
+ build: brief && b ? { active: b.active, progress: b.progress, counts: b.counts } : b,
1186
1233
  // the branch followed, where the server builds what it shows (DeploySpec)
1187
1234
  ...(this.deploy ? { deploy: this.deploy.status(true) } : {}),
1188
1235
  live: !this.saved,
@@ -1193,10 +1240,11 @@ export class Live {
1193
1240
  };
1194
1241
  }
1195
1242
  /** A page's event stream; `session` is what the page calls itself (its streams are kept few by
1196
- * it), `person` the personal link it came by. The stream is named by the server: the page is
1197
- * told its id, which everyone sees, and a secret for its heartbeats (`hello`); it is gone from
1198
- * presence when its stream closes. */
1199
- subscribe(res, session = null, person = null, readOnly = null, toldAll = readOnly === null) {
1243
+ * it), `person` the personal link it came by, `buildDeltas` whether it takes the build status as
1244
+ * changes (a page of 0.6.0 or later), `name` the name it gives (the conversations it is sent).
1245
+ * The stream is named by the server: the page is told its id, which everyone sees, and a secret
1246
+ * for its heartbeats (`hello`); it is gone from presence when its stream closes. */
1247
+ subscribe(res, session = null, person = null, readOnly = null, toldAll = readOnly === null, buildDeltas = false, name = null) {
1200
1248
  if (session) {
1201
1249
  // a page that opens one more than a page needs (a reload whose old stream lingers) loses
1202
1250
  // its oldest
@@ -1216,7 +1264,7 @@ export class Live {
1216
1264
  connection: "keep-alive",
1217
1265
  });
1218
1266
  res.write("retry: 2000\n\n");
1219
- const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, toldAll, room: Infinity, after: 0 };
1267
+ const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, name: readOnly === null ? name : null, toldAll, room: Infinity, after: 0, buildDeltas };
1220
1268
  this.streams.set(res, st);
1221
1269
  this.byToken.set(st.token, st);
1222
1270
  this.presence.open(st.id);
@@ -1230,7 +1278,11 @@ export class Live {
1230
1278
  // the views as they are: a page that was away (a restart, a lost connection) catches up, and
1231
1279
  // reads again the boards it has open
1232
1280
  this.write(res, "views", { views: this.views.list(), changes: [], all: true });
1233
- if (this.build)
1281
+ // the build status's revision: a page that holds another reads the whole (GET /api/build); what
1282
+ // changes after comes as deltas. A page from before 0.6.0 is sent it whole.
1283
+ if (buildDeltas)
1284
+ this.write(res, "build-rev", this.buildRevNow());
1285
+ else if (this.build)
1234
1286
  this.write(res, "build", this.build);
1235
1287
  if (this.deploy)
1236
1288
  this.write(res, "deploy", this.deploy.status(readOnly === null));
@@ -1269,6 +1321,41 @@ export class Live {
1269
1321
  for (const st of [...this.streams.values()])
1270
1322
  this.push(st, text);
1271
1323
  }
1324
+ /** A message of a channel, sent to the pages that read it (CollabSpec decision 13): a public one to
1325
+ * every page with a name, private readers' too; a private one only to the pages of the person
1326
+ * who made its agent's token (shared/collab.ts, madeBy), named by the agent's entry in presence;
1327
+ * nothing to a read-only reader's page, nor to a page without a name. */
1328
+ sendChat(channel, message) {
1329
+ if (!this.streams.size)
1330
+ return;
1331
+ const t = channel === PUBLIC ? null : (this.tokens.get(channel) ?? null);
1332
+ if (channel !== PUBLIC && !t)
1333
+ return;
1334
+ const text = `event: chat\ndata: ${JSON.stringify({ channel: t ? agentKey({ name: t.name, token: t.id }) : PUBLIC, message: forPages(message) })}\n\n`;
1335
+ for (const st of [...this.streams.values()])
1336
+ if (mayRead(st, t))
1337
+ this.push(st, text);
1338
+ }
1339
+ /** Who a message may mention (CollabSpec decision 13): the agents listed with a token in force, by
1340
+ * their tokens, and the people — with a page open, invited by a link, or who wrote in the public
1341
+ * channel lately — by the names they go by. */
1342
+ mentionable() {
1343
+ const agents = new Map();
1344
+ const names = [];
1345
+ for (const r of this.tokens.inForce()) {
1346
+ agents.set(nameKey(r.name), r.id);
1347
+ names.push(r.name);
1348
+ }
1349
+ for (const p of this.presence.list())
1350
+ if (!p.agent && p.name)
1351
+ names.push(p.name);
1352
+ for (const r of this.invites.inForce())
1353
+ names.push(r.name);
1354
+ for (const m of this.talk.thread(PUBLIC))
1355
+ if (m.kind === "person")
1356
+ names.push(m.from);
1357
+ return { names, agents };
1358
+ }
1272
1359
  /** Write to a stream, unless what it has not read yet passed MAX_BUFFERED beyond its hello (`room`):
1273
1360
  * then it is closed instead, and its page reconnects to the present state. A hello counted against
1274
1361
  * MAX_BUFFERED (in 0.4.3 it carried the whole review, 7 MB for 5,000 opinions on
@@ -1340,3 +1427,13 @@ function viewsCarried(views) {
1340
1427
  }
1341
1428
  return { notes, pins, scopes, reviewViews: 0 };
1342
1429
  }
1430
+ /** Whether a page's stream is sent a channel's messages (CollabSpec decision 13): the public channel
1431
+ * (`t` null) where it has a name, a private one where its reader made the agent's token; never a
1432
+ * read-only reader's. */
1433
+ function mayRead(st, t) {
1434
+ if (st.readOnly !== null)
1435
+ return false;
1436
+ if (!t)
1437
+ return st.name !== null || st.person !== null;
1438
+ return madeBy(t, { name: st.name, person: st.person });
1439
+ }