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
@@ -1,41 +1,55 @@
1
- // Talking with an agent in the page (AgentSpec decision 8): one conversation per agent token, shared
2
- // by everyone on the server; the agent's inbox, which it waits on; and its state, inferred from what
3
- // it does.
1
+ // Talking in the page (CollabSpec decision 13, AgentSpec decision 8; the owner's decisions of
2
+ // 2026-10-19): the public channel, where everyone with a name and every agent with a token talk; each
3
+ // agent's private channel, between it and the person who made its token (its maker, AgentSpec
4
+ // decision 7); the agent's inbox, which it waits on; and its state, inferred from what it does.
4
5
  //
5
6
  // Nothing is pushed to an agent: it listens by waiting on its inbox (GET /api/agent/inbox?wait=<s>,
6
7
  // which the wait_for_message tool of VisualProof's MCP server, mcp/visualproof-mcp.mjs, holds open
7
- // for it), so that any agent able to make an HTTP request can be talked to. A wait answers as soon
8
- // as a person writes, with every message that came since the last one handed over, in order; or
9
- // with none once its time is up. A message that comes while no wait is open waits for the next one.
8
+ // for it), so that any agent able to make an HTTP request can be talked to. A wait answers as soon as
9
+ // something is handed to the agent, with everything handed since the last answer, in order, each
10
+ // saying its channel; or with none once its time is up. Handed to it: its maker's messages in its
11
+ // private channel, and a person's message in the public channel that mentions it (shared/mentions.ts).
12
+ // Nothing else of the public channel: it reads the channel when it wants (GET /api/agent/channel). An
13
+ // agent's mention of an agent is shown and never handed, so that no two agents talk on without a
14
+ // person. What comes while no wait is open waits for the next one.
10
15
  //
11
16
  // The state each agent is shown in comes from what it does, not from what it says: *listening*
12
17
  // while a wait is open; *thinking* from the moment messages were handed to it until it replies, with
13
18
  // what its requests show it doing (server/agent.ts, doingOf) and the line it may set itself;
14
19
  // *working* when it makes requests with nothing to answer; *offline* once it has had no wait open
15
20
  // and made no request for its longest wait plus a minute — the time an agent that listens takes at
16
- // most to come back. Only an offline agent cannot be written to (409).
21
+ // most to come back. An offline agent's private channel cannot be written to (409); a mention of it
22
+ // in the public channel is written, and handed to it when it comes back.
17
23
  //
18
- // Conversations live apart from the review's logs, in `<site>/chat/<token id>.jsonl`, one message per
19
- // line, for 30 days; a message is at most a few thousand characters, and each sender may send only
20
- // so many a minute. Revoking a token, or its expiry, ends its wait at once.
24
+ // The channels live apart from the review's logs, in `<site>/chat/`: the public one in `public.jsonl`
25
+ // for 90 days, as the timeline is kept; each private one in `<token id>.jsonl` for 30 days; one
26
+ // message per line. A message is at most a few thousand characters, and each sender may send only so
27
+ // many a minute. A person's message in the public channel keeps the tokens of the agents it is handed
28
+ // to (`to`, the agents it mentions that were listed as it was written), which is told to nobody.
29
+ // Revoking a token, or its expiry, ends its wait at once. Who may read and write which channel is
30
+ // server/main.ts's to check (shared/collab.ts, madeBy), and which page is sent which message
31
+ // server/live.ts's.
21
32
  //
22
- // A session that replaces another knows nothing of the conversation the page still shows (the
23
- // owner's decisions of 2026-10-11). So the first wait after the agent was offline — it left, or went
24
- // offline by the rule, or another session of its MCP server waits now — answers at once with the
25
- // conversation so far, as one entry marked as earlier, before anything new. And anyone who can
26
- // write to the agent can start a new conversation: a divider in the same file, which the agent is
27
- // handed as a notice to disregard what came before, and before which a later session is told
28
- // nothing.
33
+ // A session that replaces another knows nothing of what the page still shows (the owner's decisions
34
+ // of 2026-10-11). So the first wait after the agent was offline — it left, or went offline by the
35
+ // rule, or another session of its MCP server waits now — answers at once with one entry marked as
36
+ // earlier, before anything new: its private channel so far, and the mentions of it that came while it
37
+ // was away. Its maker can start a new conversation in its private channel: a divider in the same
38
+ // file, which the agent is handed as a notice to disregard what came before, and before which a later
39
+ // session is told nothing. The public channel has no dividers.
29
40
  import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync } from "node:fs";
30
41
  import { join } from "node:path";
31
42
  import { utc } from "./mcptools.js";
32
- /** how long a message is kept */
43
+ /** how long a private channel's message is kept, and the public channel's (as the timeline) */
33
44
  export const KEEP_MS = 30 * 24 * 3600 * 1000;
34
- /** the longest message a person may send, and an agent's reply (it may explain at length) */
45
+ export const KEEP_PUBLIC_MS = 90 * 24 * 3600 * 1000;
46
+ /** the longest message a person may send, and an agent's (it may explain at length) */
35
47
  export const MAX_PERSON = 4000;
36
48
  export const MAX_AGENT = 10_000;
37
- /** what a page or an agent is given of a conversation at once */
49
+ /** what a page or an agent is given of a channel at once */
38
50
  export const THREAD = 200;
51
+ /** what the server holds of a channel in memory: what pages may page back through */
52
+ const HELD = 2000;
39
53
  /** the longest one wait may last, in seconds: Claude Code gives up on a stdio tool call idle for 30
40
54
  * minutes (progress resets it), and an agent that splits a longer wait asks again */
41
55
  export const MAX_WAIT_S = 1800;
@@ -47,17 +61,23 @@ export const EARLIER_MESSAGES = 50;
47
61
  export const EARLIER_CHARS = 20_000;
48
62
  /** a sender's messages: a burst of BURST, then one every REFILL_MS (people), or faster (agents) */
49
63
  const RATE = { person: { burst: 5, refillMs: 6000 }, agent: { burst: 10, refillMs: 2000 } };
64
+ /** the public channel's key, where a private channel's is its token's id (ten hex digits) */
65
+ export const PUBLIC = "public";
50
66
  const TIMING = { slackMs: 60_000, graceMs: 15_000, tickMs: 1000 };
51
67
  export class Talk {
52
68
  dir;
53
69
  timing;
54
70
  threads = new Map();
71
+ /** each channel's last id in this server's life: a channel whose messages all expired goes on
72
+ * counting from there, so that no agent's place in it (`read`) passes what comes next */
73
+ lastIds = new Map();
55
74
  agents = new Map();
56
75
  buckets = new Map();
57
76
  ticks = 0;
58
77
  /** told when an agent's state, what it does or its line changes (presence lists it so) */
59
78
  onState = () => { };
60
- /** told of every new message, to go to every page */
79
+ /** told of every new message, by its channel (`public`, or the token whose private channel it
80
+ * is): server/live.ts sends it to the pages that may read it */
61
81
  onMessage = () => { };
62
82
  /** whether a token is still in force, looked at while its agent waits (an expiry between the
63
83
  * minutes the tokens are looked at ends the wait) */
@@ -78,11 +98,15 @@ export class Talk {
78
98
  agent(token) {
79
99
  let a = this.agents.get(token);
80
100
  if (!a) {
81
- // what was written before the server started counts as read: it is never handed over as
82
- // new, and an agent that was offline meanwhile is handed it as the conversation so far
101
+ // what was written before the agent was first known here counts as read: it is never handed
102
+ // over as new, and an agent that was offline meanwhile is handed it as what came before. Each
103
+ // token in force is known as the server starts, and a new one as it is made (server/live.ts,
104
+ // presence), so that a mention of it written before its first request is handed to it
83
105
  const used = this.lastUsed(token);
84
106
  a = {
85
- wait: null, waitMs: 0, lastRequest: 0, lastSeen: null, graceUntil: 0, read: this.load(token).at(-1)?.id ?? 0, thinkingSince: null, doing: null, status: null, told: null,
107
+ wait: null, waitMs: 0, lastRequest: 0, lastSeen: null, graceUntil: 0,
108
+ read: this.load(token).at(-1)?.id ?? 0, readPublic: this.load(PUBLIC).at(-1)?.id ?? 0, lastChannel: "private",
109
+ thinkingSince: null, doing: null, status: null, told: null,
86
110
  away: false, before: used ? Date.parse(used) : null, session: null,
87
111
  };
88
112
  this.agents.set(token, a);
@@ -118,6 +142,7 @@ export class Talk {
118
142
  doing: busy ? a.doing : null,
119
143
  status: busy ? a.status : null,
120
144
  read: a.read,
145
+ readPublic: a.readPublic,
121
146
  lastSeen: a.lastSeen === null ? null : new Date(a.lastSeen).toISOString(),
122
147
  };
123
148
  }
@@ -125,13 +150,18 @@ export class Talk {
125
150
  state(token, now = Date.now()) {
126
151
  return this.talk(token, now).state;
127
152
  }
153
+ /** Where its reply goes when it names no channel: the channel of the last message handed to it
154
+ * that it was to answer, its private one before any. */
155
+ lastChannel(token) {
156
+ return this.agent(token).lastChannel;
157
+ }
128
158
  /** Tell presence when what pages show of the agent changed (not when it was last seen alone). */
129
159
  update(token, now = Date.now()) {
130
160
  const a = this.agent(token);
131
161
  const t = this.talk(token, now);
132
162
  const was = a.told;
133
163
  a.told = t;
134
- if (!was || was.state !== t.state || was.since !== t.since || was.doing !== t.doing || was.status !== t.status || was.read !== t.read)
164
+ if (!was || was.state !== t.state || was.since !== t.since || was.doing !== t.doing || was.status !== t.status || was.read !== t.read || was.readPublic !== t.readPublic)
135
165
  this.onState(token, t);
136
166
  }
137
167
  /** States change with time alone (the grace after a wait, going offline); and a token that ended
@@ -188,9 +218,10 @@ export class Talk {
188
218
  }
189
219
  /** The agent waits for messages, at most `ms`; `maxMs` is the longest it waits in all where it
190
220
  * splits a long wait into shorter requests. The answer comes at once with what is waiting, as
191
- * soon as a person writes, or with nothing at the end; `signal` says the one waiting went away.
192
- * The first wait after the agent was offline starts with the conversation so far, and so answers
193
- * at once where there is any; `session` is the one its MCP server says it is, where it says. */
221
+ * soon as something is handed to it, or with nothing at the end; `signal` says the one waiting
222
+ * went away. The first wait after the agent was offline starts with what came before, and so
223
+ * answers at once where there is any; `session` is the one its MCP server says it is, where it
224
+ * says. */
194
225
  wait(token, ms, opts = {}, now = Date.now()) {
195
226
  const a = this.agent(token);
196
227
  this.contact(a, now);
@@ -214,14 +245,13 @@ export class Talk {
214
245
  if (opts.signal?.aborted)
215
246
  return Promise.resolve({ gone: true });
216
247
  const queued = this.queued(token);
217
- let handed = queued;
248
+ let handed = queued.map(outward);
218
249
  if (a.away) {
219
- // once per return: the waits after it are as any
250
+ // once per return: the waits after it are as any. What was queued is accounted for, the
251
+ // dividers it was not handed among it: they are behind what it is told
220
252
  a.away = false;
221
253
  handed = this.rejoin(token, queued, now);
222
- // the dividers it was not handed are behind what it is told
223
- if (!handed.length && queued.length)
224
- a.read = queued.at(-1).id;
254
+ this.mark(a, queued);
225
255
  }
226
256
  if (handed.length || ms <= 0) {
227
257
  const r = this.hand(token, queued, handed, 0, now);
@@ -253,38 +283,64 @@ export class Talk {
253
283
  this.update(token, now);
254
284
  });
255
285
  }
256
- /** People's messages and dividers not yet handed to the agent, in order. */
286
+ /** What is to be handed to the agent and was not yet, in order: its private channel's messages
287
+ * but its own (its maker's and the dividers), and the people's messages of the public channel
288
+ * handed to it (`to`). */
257
289
  queued(token) {
258
290
  const a = this.agent(token);
259
- return this.load(token).filter((m) => m.kind !== "agent" && m.id > a.read);
291
+ const mine = this.load(token).filter((m) => m.kind !== "agent" && m.id > a.read);
292
+ const named = this.load(PUBLIC).filter((m) => m.id > a.readPublic && m.kind === "person" && !!m.to?.includes(token));
293
+ return inOrder(mine, named);
294
+ }
295
+ /** What `queued` holds is the agent's from now on: what comes after it is handed next. */
296
+ mark(a, queued) {
297
+ for (const m of queued) {
298
+ if (m.channel === "public")
299
+ a.readPublic = Math.max(a.readPublic, m.id);
300
+ else
301
+ a.read = Math.max(a.read, m.id);
302
+ }
260
303
  }
261
- /** What the first wait after the agent was offline hands over: the conversation since its last
262
- * divider, as one entry, then people's messages since that divider not handed over yet. A new
263
- * session needs no notice of a divider: nothing before it is told. */
304
+ /** What the first wait after the agent was offline hands over: its private channel since its last
305
+ * divider that it was handed before, and the mentions of it it was not handed (they came while it
306
+ * was away), as one entry; then its maker's messages since that divider not handed over yet. A
307
+ * new session needs no notice of a divider: nothing before it is told. */
264
308
  rejoin(token, queued, now) {
265
309
  const thread = this.load(token);
266
310
  const since = thread.slice(thread.findLastIndex((m) => m.kind === "divider") + 1);
267
- const fresh = new Set(queued.map((m) => m.id));
311
+ const fresh = new Set(queued.filter((m) => m.channel === "private").map((m) => m.id));
268
312
  const news = since.filter((m) => fresh.has(m.id));
269
313
  const told = since.filter((m) => !fresh.has(m.id));
270
- const earlier = earlierOf(told, news.length > 0, now);
271
- return earlier ? [earlier, ...news] : news;
314
+ const missed = queued.filter((m) => m.channel === "public");
315
+ const earlier = earlierOf(inOrder(told, missed), news.length > 0, now);
316
+ return earlier ? [earlier, ...news.map(outward)] : news.map(outward);
272
317
  }
273
- /** Hand over what a wait answers with: what is queued is the agent's from now on (`read`); people's
274
- * messages among it it thinks about from now until it replies, and what it does is what it does
275
- * from now (a request made while it waited, by another of its clients, is not). The conversation
276
- * so far and a divider's notice need no answer. */
318
+ /** Hand over what a wait answers with: what is queued is the agent's from now on; people's
319
+ * messages among it it thinks about from now until it replies, in the channel of the last of
320
+ * them, and what it does is what it does from now (a request made while it waited, by another
321
+ * of its clients, is not). What came before and a divider's notice need no answer. */
277
322
  hand(token, queued, handed, waitedMs, now) {
278
323
  const a = this.agent(token);
279
- if (queued.length)
280
- a.read = queued.at(-1).id;
281
- if (handed.some((m) => m.kind === "person")) {
324
+ this.mark(a, queued);
325
+ const asked = handed.filter((m) => m.kind === "person");
326
+ if (asked.length) {
282
327
  a.thinkingSince = now;
328
+ a.lastChannel = asked.at(-1).channel;
283
329
  a.doing = null;
284
330
  a.status = null;
285
331
  }
286
332
  return { messages: handed, waitedMs };
287
333
  }
334
+ /** Hand what is queued for the agent to its open wait, if it has one; else it waits for the next. */
335
+ wake(token, now) {
336
+ const a = this.agents.get(token);
337
+ const w = a?.wait;
338
+ if (!w)
339
+ return;
340
+ const q = this.queued(token);
341
+ if (q.length)
342
+ w.end(this.hand(token, q, q.map(outward), now - w.at, now));
343
+ }
288
344
  /** End a token's wait: it was revoked, or expired; and forget its agent. */
289
345
  close(token, why) {
290
346
  const a = this.agents.get(token);
@@ -301,42 +357,55 @@ export class Talk {
301
357
  n++;
302
358
  return n;
303
359
  }
304
- // ---------------------------------------------------------------- the conversation
305
- /** A conversation's messages, the last `limit`, of the last 30 days, dividers among them. */
306
- thread(token, limit = THREAD) {
307
- return this.load(token).slice(-limit);
360
+ // ---------------------------------------------------------------- the channels
361
+ /** A channel's messages (`public`, or a token's private channel): the last `limit` of those before
362
+ * message `before` (all, where it is left out), dividers among them. */
363
+ thread(channel, limit = THREAD, before = null) {
364
+ const t = this.load(channel);
365
+ const upTo = before === null ? t : t.filter((m) => m.id < before);
366
+ return upTo.slice(-limit).map(outward);
308
367
  }
309
- /** The conversation as the agent reads it (GET /api/agent/conversation): the last `limit` messages
310
- * since its last divider, with that divider and how many messages came before it; `all`, the last
311
- * `limit` whatever conversation they were in, dividers among them. */
368
+ /** The public channel after message `since`, as an agent reads it (GET /api/agent/channel): at most
369
+ * the newest `limit`. */
370
+ since(since, limit = THREAD) {
371
+ return this.load(PUBLIC).filter((m) => m.id > since).slice(-limit).map(outward);
372
+ }
373
+ /** The private channel as the agent reads it (GET /api/agent/conversation): the last `limit`
374
+ * messages since its last divider, with that divider and how many messages came before it; `all`,
375
+ * the last `limit` whatever conversation they were in, dividers among them. */
312
376
  conversation(token, limit = THREAD, all = false) {
313
377
  const thread = this.load(token);
314
378
  const k = thread.findLastIndex((m) => m.kind === "divider");
315
379
  return {
316
- messages: (all ? thread : thread.slice(k + 1)).slice(-limit),
317
- divider: k < 0 ? null : thread[k],
380
+ messages: (all ? thread : thread.slice(k + 1)).slice(-limit).map(outward),
381
+ divider: k < 0 ? null : outward(thread[k]),
318
382
  before: thread.slice(0, Math.max(k, 0)).filter((m) => m.kind !== "divider").length,
319
383
  };
320
384
  }
321
- /** Whether nothing was said since the conversation last began (or ever): a divider then would
322
- * divide nothing. */
385
+ /** Whether nothing was said in a private channel since its conversation last began (or ever): a
386
+ * divider then would divide nothing. */
323
387
  fresh(token) {
324
388
  const last = this.load(token).at(-1);
325
389
  return !last || last.kind === "divider";
326
390
  }
327
- /** Start a new conversation (the owner's decision of 2026-10-11): a divider, written and sent to
328
- * every page as a message is, which the agent is handed at its next wait, or at once where it
329
- * listens, as a notice to disregard what came before; a later session is told only what comes
330
- * after it. An offline agent's conversation is started anew too, so that its next session starts
331
- * clean. Null, and nothing written, where it is new already. */
391
+ /** Start a new conversation in a private channel (the owner's decision of 2026-10-11): a divider,
392
+ * written and sent to the maker's pages as a message is, which the agent is handed at its next
393
+ * wait, or at once where it listens, as a notice to disregard what came before; a later session
394
+ * is told only what comes after it. An offline agent's conversation is started anew too, so that
395
+ * its next session starts clean. Null, and nothing written, where it is new already. */
332
396
  restart(token, from, now = Date.now()) {
333
397
  if (this.fresh(token))
334
398
  return null;
335
- return this.post(token, { from, kind: "divider", text: `${from} started a new conversation: disregard what came before.`, where: null }, now);
399
+ return this.post(token, { from, kind: "divider", text: `${from} started a new conversation: disregard what came before.`, where: null }, null, now);
336
400
  }
337
401
  /** Whether `sender` (kind and name) may send now; if not, the seconds to wait. Taking one. */
338
402
  allow(kind, sender, now = Date.now()) {
339
403
  const r = RATE[kind];
404
+ // the senders whose bursts are full again are forgotten, so that the buckets stay few
405
+ if (this.buckets.size > 2000)
406
+ for (const [k, b] of this.buckets)
407
+ if (b.at + RATE[k.startsWith("agent") ? "agent" : "person"].burst * RATE[k.startsWith("agent") ? "agent" : "person"].refillMs < now)
408
+ this.buckets.delete(k);
340
409
  const key = `${kind}\u0000${sender}`;
341
410
  const b = this.buckets.get(key) ?? { tokens: r.burst, at: now };
342
411
  b.tokens = Math.min(r.burst, b.tokens + (now - b.at) / r.refillMs);
@@ -347,46 +416,60 @@ export class Talk {
347
416
  b.tokens -= 1;
348
417
  return 0;
349
418
  }
350
- /** Add a message to a conversation: written, and sent to every page. A person's, or a divider,
351
- * goes to the agent's open wait, if it has one, else waits for the next; the agent's answers
352
- * what it was thinking about. */
353
- post(token, m, now = Date.now()) {
354
- const thread = this.load(token);
355
- const msg = { id: (thread.at(-1)?.id ?? 0) + 1, at: new Date(now).toISOString(), ...m };
419
+ /** Write a message in a channel (`public`, or a token's private channel), and send it to the pages
420
+ * that read it. In a private channel, its maker's message or a divider goes to the agent's open
421
+ * wait, if it has one, else waits for the next; in the public channel, a person's message goes so
422
+ * to each agent it is handed to (`to`). An agent's message — the agent is `by`, its token, in the
423
+ * public channel — answers what it was thinking about. */
424
+ post(channel, m, by = null, now = Date.now()) {
425
+ const thread = this.load(channel);
426
+ const { to, ...rest } = m;
427
+ const id = Math.max(thread.at(-1)?.id ?? 0, this.lastIds.get(channel) ?? 0) + 1;
428
+ this.lastIds.set(channel, id);
429
+ const msg = { id, at: new Date(now).toISOString(), ...rest, channel: channel === PUBLIC ? "public" : "private", ...(to?.length ? { to } : {}) };
356
430
  thread.push(msg);
357
- if (thread.length > 4 * THREAD)
358
- thread.splice(0, thread.length - 2 * THREAD);
431
+ if (thread.length > 2 * HELD)
432
+ thread.splice(0, thread.length - HELD);
359
433
  mkdirSync(this.dir, { recursive: true });
360
- appendFileSync(this.file(token), JSON.stringify(msg) + "\n");
361
- this.onMessage(token, msg);
362
- const a = this.agent(token);
363
- if (msg.kind !== "agent") {
364
- const w = a.wait;
365
- if (w) {
366
- const q = this.queued(token);
367
- w.end(this.hand(token, q, q, now - w.at, now));
368
- }
369
- }
370
- else {
371
- this.contact(a, now);
372
- a.lastRequest = now;
373
- a.lastSeen = now;
374
- a.thinkingSince = null;
375
- a.status = null;
376
- a.doing = null;
377
- this.update(token, now);
434
+ appendFileSync(this.file(channel), JSON.stringify(msg) + "\n");
435
+ const out = outward(msg);
436
+ this.onMessage(channel, out);
437
+ const writer = channel === PUBLIC ? by : channel;
438
+ if (msg.kind === "agent") {
439
+ if (writer)
440
+ this.replied(writer, now);
378
441
  }
379
- return msg;
442
+ else if (channel !== PUBLIC)
443
+ this.wake(channel, now);
444
+ // an agent's mention of an agent is shown, never handed (AgentSpec decision 8): only a
445
+ // person's message is handed to anyone
446
+ else if (msg.kind === "person")
447
+ for (const t of msg.to ?? [])
448
+ this.wake(t, now);
449
+ return out;
450
+ }
451
+ /** The agent wrote: it is not offline, and what it was thinking about is answered. */
452
+ replied(token, now) {
453
+ const a = this.agent(token);
454
+ this.contact(a, now);
455
+ a.lastRequest = now;
456
+ a.lastSeen = now;
457
+ a.thinkingSince = null;
458
+ a.status = null;
459
+ a.doing = null;
460
+ this.update(token, now);
380
461
  }
381
- file(token) {
382
- return join(this.dir, `${token.replace(/[^0-9a-f]/g, "")}.jsonl`);
462
+ file(channel) {
463
+ return join(this.dir, channel === PUBLIC ? "public.jsonl" : `${channel.replace(/[^0-9a-f]/g, "")}.jsonl`);
383
464
  }
384
- /** A conversation as it is kept, read once: what is older than 30 days is left out, and the file
385
- * written again without it. */
386
- load(token) {
387
- let t = this.threads.get(token);
465
+ /** A channel as it is kept, read once: what is older than it keeps is left out, and the file
466
+ * written again without it. A line from before channels (0.5.0) is its file's channel's. */
467
+ load(channel) {
468
+ const keep = channel === PUBLIC ? KEEP_PUBLIC_MS : KEEP_MS;
469
+ const kind = channel === PUBLIC ? "public" : "private";
470
+ let t = this.threads.get(channel);
388
471
  if (t) {
389
- const old = t.findIndex((m) => Date.now() - Date.parse(m.at) < KEEP_MS);
472
+ const old = t.findIndex((m) => Date.now() - Date.parse(m.at) < keep);
390
473
  if (old > 0)
391
474
  t.splice(0, old);
392
475
  else if (old < 0)
@@ -394,37 +477,44 @@ export class Talk {
394
477
  return t;
395
478
  }
396
479
  t = [];
397
- const f = this.file(token);
480
+ const f = this.file(channel);
398
481
  if (existsSync(f)) {
399
482
  for (const line of readFileSync(f, "utf8").split("\n")) {
400
483
  if (!line.trim())
401
484
  continue;
402
485
  try {
403
- t.push(JSON.parse(line));
486
+ t.push({ ...JSON.parse(line), channel: kind });
404
487
  }
405
488
  catch {
406
489
  // a line cut short (the server stopped while writing): left out
407
490
  }
408
491
  }
409
- const kept = t.filter((m) => Date.now() - Date.parse(m.at) < KEEP_MS);
492
+ const kept = t.filter((m) => Date.now() - Date.parse(m.at) < keep);
410
493
  if (kept.length !== t.length) {
411
494
  t = kept;
412
495
  rewrite(f, kept);
413
496
  }
497
+ if (t.length > HELD)
498
+ t = t.slice(-HELD);
414
499
  }
415
- this.threads.set(token, t);
500
+ const last = t.at(-1)?.id ?? 0;
501
+ if (last > (this.lastIds.get(channel) ?? 0))
502
+ this.lastIds.set(channel, last);
503
+ this.threads.set(channel, t);
416
504
  return t;
417
505
  }
418
- /** Conversations nobody wrote in for 30 days go; the others lose what is older (when read). */
506
+ /** Channels nobody wrote in for as long as they are kept go; the others lose what is older (when
507
+ * read). */
419
508
  sweep(now = Date.now()) {
420
509
  if (!existsSync(this.dir))
421
510
  return;
422
511
  for (const name of readdirSync(this.dir)) {
423
512
  const f = join(this.dir, name);
513
+ const channel = name.replace(/\.jsonl$/, "");
424
514
  try {
425
- if (now - statSync(f).mtimeMs > KEEP_MS) {
515
+ if (now - statSync(f).mtimeMs > (channel === PUBLIC ? KEEP_PUBLIC_MS : KEEP_MS)) {
426
516
  rmSync(f, { force: true });
427
- this.threads.delete(name.replace(/\.jsonl$/, ""));
517
+ this.threads.delete(channel);
428
518
  }
429
519
  }
430
520
  catch {
@@ -433,10 +523,29 @@ export class Talk {
433
523
  }
434
524
  }
435
525
  }
436
- /** The conversation so far as the entry a returning agent is handed first, or null where there is
437
- * none: the newest of `told`, at most EARLIER_MESSAGES and EARLIER_CHARS characters of text, each
438
- * with who wrote it (the agent's own as its own), where they were and when; then what to do, as
439
- * `news` says whether anything new comes after it. */
526
+ /** A message as pages and agents are told it: without whom it is handed to. */
527
+ function outward(m) {
528
+ const { to: _to, ...rest } = m;
529
+ return rest;
530
+ }
531
+ /** A message as a page is told it (CollabSpec decision 13): where its writer was is handed to agents
532
+ * and never drawn, so a page is not sent it. */
533
+ export function forPages(m) {
534
+ const { where: _where, ...rest } = m;
535
+ return rest;
536
+ }
537
+ /** Two channels' messages as one list, in the order they were written. */
538
+ function inOrder(a, b) {
539
+ if (!b.length)
540
+ return a;
541
+ if (!a.length)
542
+ return b;
543
+ return [...a, ...b].sort((x, y) => (x.at < y.at ? -1 : x.at > y.at ? 1 : 0));
544
+ }
545
+ /** What came before as the entry a returning agent is handed first, or null where there is none: the
546
+ * newest of `told`, at most EARLIER_MESSAGES and EARLIER_CHARS characters of text, each with who
547
+ * wrote it (the agent's own as its own), where they were and when — the mentions of it in the public
548
+ * channel said so; then what to do, as `news` says whether anything new comes after it. */
440
549
  export function earlierOf(told, news, now = Date.now()) {
441
550
  let k = told.length;
442
551
  let chars = 0;
@@ -448,18 +557,25 @@ export function earlierOf(told, news, now = Date.now()) {
448
557
  const each = kept.map((m) => {
449
558
  const who = m.kind === "agent" ? `You (${m.from})` : m.from;
450
559
  const where = m.where?.inWords ? `, on ${m.where.inWords.replace(/\.$/, "")}` : "";
451
- return `— ${who}${where}, ${utc(m.at)} (message ${m.id}):\n${m.text}`;
560
+ const pub = m.channel === "public";
561
+ return `— ${who}${pub ? " in the public channel, mentioning you while you were away" : ""}${where}, ${utc(m.at)} (${pub ? "public " : ""}message ${m.id}):\n${m.text}`;
452
562
  });
453
- const cut = k ? ` (its last ${kept.length} messages; the conversation tool, GET /api/agent/conversation, gives the ${k} before them)` : "";
454
- const then = news ? "What came since follows: answer that." : "Nothing came since: there is nothing to answer. Listen again.";
563
+ const omitted = k;
564
+ const cut = omitted ? ` (its last ${kept.length} messages; the conversation tool, GET /api/agent/conversation, gives the ${omitted} before them)` : "";
565
+ const away = kept.filter((m) => m.channel === "public").length;
566
+ const missed = away
567
+ ? "Those in the public channel came while you were away and were never handed to you: answer one there (reply with channel public) only where it still asks something of you. "
568
+ : "";
569
+ const then = news ? "What came since follows: answer that." : missed ? "Nothing else came since: listen again after that." : "Nothing came since: there is nothing to answer. Listen again.";
455
570
  return {
456
571
  id: 0,
457
572
  at: new Date(now).toISOString(),
458
573
  from: "VisualProof",
459
574
  kind: "earlier",
460
- text: `Earlier in this conversation, before you joined${cut} — read it as context, and do not answer it again:\n\n${each.join("\n\n")}\n\nEnd of the earlier messages. ${then}`,
575
+ text: `Earlier in this conversation, before you joined${cut} — read it as context, and do not answer it again:\n\n${each.join("\n\n")}\n\nEnd of the earlier messages. ${missed}${then}`,
461
576
  count: kept.length,
462
- omitted: k,
577
+ omitted,
578
+ ...(away ? { missed: away } : {}),
463
579
  };
464
580
  }
465
581
  /** An agent's state at `now`, from what it did: a wait open (or one that ended at its time just
@@ -12,6 +12,11 @@
12
12
  // of their own. Tokens made before the secret was kept (only test tokens) are dropped when the file
13
13
  // is read.
14
14
  //
15
+ // Its maker is the person who made it: their personal link, where an invited person did, else the
16
+ // name they gave (shared/collab.ts, madeBy). Only they are shown its prompt again and read its
17
+ // private channel (the owner's decisions of 2026-10-19): whoever holds the token reads that channel.
18
+ // Revoking it stays anyone's with a name, so that anyone can stop an agent at once.
19
+ //
15
20
  // The identity is the token's, not the request's: the name is the one the person gave, "<their
16
21
  // name>'s AI" unless they wrote another, and stays the same for the token's life, being the name
17
22
  // its advice is logged under (shared/review.ts, logFileName). Among the tokens in force no two have
@@ -87,7 +92,8 @@ export class AgentTokens {
87
92
  }
88
93
  /** Make a token for an agent: the token (for its prompt) and its record. The name and level are
89
94
  * checked by the caller (server/main.ts); the name is used as given, numbered when an agent in
90
- * force has it already; `by` is a person's name. */
95
+ * force has it already; `by` is a person's name, and `person` their personal link's id where an
96
+ * invited person makes it (`makerPerson`: who its maker is, AgentSpec decision 7). */
91
97
  create(o) {
92
98
  const now = o.now ?? Date.now();
93
99
  this.expire(now);
@@ -101,6 +107,7 @@ export class AgentTokens {
101
107
  name: uniqueName(o.name, this.inForce(now).map((r) => r.name)),
102
108
  level: o.level,
103
109
  by: o.by,
110
+ ...(o.person ? { makerPerson: o.person } : {}),
104
111
  created: new Date(now).toISOString(),
105
112
  expires: new Date(now + o.days * 24 * 3600 * 1000).toISOString(),
106
113
  revoked: null,
@@ -217,5 +224,6 @@ export function invalidAgentName(s) {
217
224
  function isRecord(x) {
218
225
  const r = x;
219
226
  return !!r && typeof r === "object" && typeof r.id === "string" && ID.test(r.id) && typeof r.secret === "string" && SECRET.test(r.secret) &&
220
- typeof r.name === "string" && typeof r.by === "string" && typeof r.expires === "string" && ["read", "advise", "full"].includes(r.level);
227
+ typeof r.name === "string" && typeof r.by === "string" && typeof r.expires === "string" && ["read", "advise", "full"].includes(r.level) &&
228
+ (r.makerPerson === undefined || typeof r.makerPerson === "string");
221
229
  }
@@ -1,2 +1,36 @@
1
1
  // Build status, as the server reports it to the page.
2
- export {};
2
+ /** What changed from the files as last sent (`sent`: each file's status as JSON, by module) to
3
+ * `next`'s: the files changed or new, the modules gone, and `next`'s files as JSON, by module, for
4
+ * the next change. */
5
+ export function buildChanges(sent, next) {
6
+ const texts = new Map();
7
+ const files = [];
8
+ for (const f of next.files) {
9
+ const t = JSON.stringify(f);
10
+ texts.set(f.module, t);
11
+ if (sent.get(f.module) !== t)
12
+ files.push(f);
13
+ }
14
+ const gone = [...sent.keys()].filter((m) => !texts.has(m));
15
+ return { files, gone, texts };
16
+ }
17
+ /** `held` with change `d` applied: the files changed replaced where they are, those new added at the
18
+ * end, those gone taken out. Null where it is no change of what is held: of another run of the
19
+ * server's, or from another revision (a change missed between). */
20
+ export function applyBuildDelta(held, d) {
21
+ if (d.epoch !== held.epoch || d.base !== held.rev)
22
+ return null;
23
+ const changed = new Map(d.files.map((f) => [f.module, f]));
24
+ const gone = new Set(d.gone);
25
+ const files = [];
26
+ for (const f of held.status?.files ?? []) {
27
+ if (gone.has(f.module))
28
+ continue;
29
+ const c = changed.get(f.module);
30
+ files.push(c ?? f);
31
+ if (c)
32
+ changed.delete(f.module);
33
+ }
34
+ files.push(...changed.values());
35
+ return { epoch: d.epoch, rev: d.rev, status: { active: d.active, progress: d.progress, files, counts: d.counts } };
36
+ }