visualproof 0.8.2 → 0.10.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 (54) hide show
  1. package/README.md +12 -9
  2. package/dist/assets/tips/tour-library.webp +0 -0
  3. package/dist/assets/tips/tour-source.webp +0 -0
  4. package/dist/assets/tips/tour.json +90 -90
  5. package/dist/extractor/Extract.lean +34 -11
  6. package/dist/mcp/visualproof-mcp.mjs +30 -5
  7. package/dist/server/agent.js +19 -7
  8. package/dist/server/agententry.js +13 -6
  9. package/dist/server/agentexport.js +2 -1
  10. package/dist/server/agentfollow.js +13 -3
  11. package/dist/server/agentlean.js +91 -1
  12. package/dist/server/agentnotes.js +6 -4
  13. package/dist/server/agentread.js +33 -1
  14. package/dist/server/app.js +7 -3
  15. package/dist/server/appagent.js +1 -1
  16. package/dist/server/appgraph.js +24 -0
  17. package/dist/server/appshare.js +119 -1
  18. package/dist/server/apptalk.js +26 -0
  19. package/dist/server/boardspots.js +1 -1
  20. package/dist/server/children.js +6 -2
  21. package/dist/server/claudetokens.js +113 -0
  22. package/dist/server/doctor.js +7 -0
  23. package/dist/server/goals.js +224 -0
  24. package/dist/server/hosted.js +480 -0
  25. package/dist/server/hover.js +281 -8
  26. package/dist/server/live.js +34 -2
  27. package/dist/server/main.js +30 -2
  28. package/dist/server/mcptools.js +15 -7
  29. package/dist/server/options.js +30 -2
  30. package/dist/server/presence.js +2 -2
  31. package/dist/server/prompt.js +25 -0
  32. package/dist/server/readonlygate.js +2 -1
  33. package/dist/server/reviewapi.js +5 -2
  34. package/dist/server/status.js +43 -5
  35. package/dist/server/tokens.js +7 -4
  36. package/dist/shared/build.js +9 -0
  37. package/dist/shared/collab.js +17 -2
  38. package/dist/shared/declfind.js +23 -3
  39. package/dist/shared/goals.js +309 -0
  40. package/dist/shared/hygiene.js +18 -0
  41. package/dist/shared/noteplace.js +45 -19
  42. package/dist/shared/scope.js +74 -45
  43. package/dist/shared/sharesnap.js +4 -2
  44. package/dist/web/bundle/app.js +2368 -591
  45. package/dist/web/index.html +2 -1
  46. package/dist/web/src/highlight.js +53 -3
  47. package/dist/web/style.css +151 -0
  48. package/docs/agent-api/README.md +1 -1
  49. package/docs/agent-api/mcp.md +4 -2
  50. package/docs/agent-api/notes.md +3 -2
  51. package/docs/agent-api/reading.md +38 -2
  52. package/docs/agent-api/talking.md +7 -0
  53. package/docs/agent-api/words.md +3 -2
  54. package/package.json +1 -1
@@ -98,15 +98,19 @@ export function endpointList(api, a) {
98
98
  return fail(404, `No endpoint ${path}.`, "GET /api/agent/endpoints lists them all.");
99
99
  return ok({ endpoints: all.map((e) => ({ method: e.method, path: e.path, about: e.about, params: e.params, returns: e.returns, ...(e.needs ? { needs: `--agents ${e.needs === "advise" ? "advise or full" : "full"}` } : {}) })) });
100
100
  }
101
+ /** VisualProof's MCP server as it is served, carrying the version of the server it came from
102
+ * (UpdateSpec decision 11); the agents the server runs run it too (server/hosted.ts). Throws where
103
+ * the file is not beside the server. */
104
+ export function mcpServerText() {
105
+ return readFileSync(MCP_FILE, "utf8").replace(/^const VERSION = "[^"\n]*";$/m, `const VERSION = ${JSON.stringify(packageVersion())};`);
106
+ }
101
107
  /** VisualProof's MCP server, one file (mcp/visualproof-mcp.mjs). */
102
108
  export function mcpFile(api, a) {
103
109
  const t = talker(api, a);
104
110
  if (typeof t !== "string")
105
111
  return t;
106
112
  try {
107
- // the file carries the version of the server it came from (UpdateSpec decision 11)
108
- const body = readFileSync(MCP_FILE, "utf8").replace(/^const VERSION = "[^"\n]*";$/m, `const VERSION = ${JSON.stringify(packageVersion())};`);
109
- return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body } };
113
+ return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body: mcpServerText() } };
110
114
  }
111
115
  catch {
112
116
  return fail(404, "The MCP server is not beside this server.", "Use the HTTP API (GET /api/agent).");
@@ -127,12 +131,15 @@ export function mcpTools(api, a) {
127
131
  const t = talker(api, a);
128
132
  if (typeof t !== "string")
129
133
  return t;
130
- const tools = TOOLS.map((d) => offered(d, (r) => mayCall(api, a.caller, r))).filter((x) => x !== null);
131
134
  const me = a.caller;
132
- const you = { name: me.name, level: api.levelOf(me), by: me.token.by, expires: me.token.expires };
135
+ // an agent the server runs is handed its messages as turns (AgentSpec decision 10): it has nothing
136
+ // to wait on
137
+ const hosted = me.token.runs === "server";
138
+ const tools = TOOLS.filter((d) => !(hosted && d.name === "wait_for_message")).map((d) => offered(d, (r) => mayCall(api, a.caller, r))).filter((x) => x !== null);
139
+ const you = { name: me.name, level: api.levelOf(me), by: me.token.by, expires: me.token.expires, ...(hosted ? { runs: "server" } : {}) };
133
140
  const v = api.world.graph ? api.graph() : null;
134
141
  const project = v instanceof View ? v.meta.project.name : null;
135
- return ok({ you, instructions: mcpInstructions({ ...you, address: a.base ?? "http://127.0.0.1:4173", project }), tools, docs: DOC_TOPICS });
142
+ return ok({ you, instructions: mcpInstructions({ ...you, address: a.base ?? "http://127.0.0.1:4173", project, hosted }), tools, docs: DOC_TOPICS });
136
143
  }
137
144
  /** Whether `caller` may make a tool's request: what its endpoint needs. A request no endpoint
138
145
  * answers is a mistake of the tools' list. */
@@ -26,6 +26,7 @@ import { SERVER_WRITER } from "./review.js";
26
26
  import { lakeTextHash } from "./status.js";
27
27
  import { View } from "./agentgraph.js";
28
28
  import { body, fail, needAgent, ok } from "./agent.js";
29
+ import { isCompiledText } from "../shared/build.js";
29
30
  /** The build the document of view `rec` is of (ExportSpec decision 16): the view's own where the
30
31
  * request names none — the past build it is kept at, if it is (HistorySpec decision 19) — else
31
32
  * the one `raw` names, as the Time Machine shows a view at another build than its own (null, 0 or
@@ -105,7 +106,7 @@ async function docInput(api, view, settings, retired = {}, version) {
105
106
  try {
106
107
  const text = readFileSync(join(root, rel), "utf8");
107
108
  const hash = lakeTextHash(text);
108
- return { lines: text.split("\n"), edited: !!m?.compiled && hash !== m.compiled, contexts: api.world.contextsOf?.(module) ?? null, hash };
109
+ return { lines: text.split("\n"), edited: !isCompiledText(m?.compiled, hash), contexts: api.world.contextsOf?.(module) ?? null, hash };
109
110
  }
110
111
  catch {
111
112
  return null;
@@ -82,6 +82,14 @@ export function followersOf(P, peers, key) {
82
82
  people.sort((a, b) => (a ?? "\uffff").localeCompare(b ?? "\uffff"));
83
83
  return { people, private: P.privateFollowers().get(key) ?? 0 };
84
84
  }
85
+ /** The pinned windows in words: the declarations whose source is pinned (the whole file of some,
86
+ * File mode), then the file windows. */
87
+ function pinnedWords(pinned) {
88
+ const decls = pinned.flatMap((w) => ("decl" in w ? [`${w.decl}${w.mode === "file" ? " (its whole file)" : ""}`] : []));
89
+ const files = pinned.flatMap((w) => ("file" in w ? [`the file ${w.file}`] : []));
90
+ const all = [...(decls.length ? [`the source of ${decls.join(", ")}`] : []), ...files];
91
+ return all.length ? `, with ${all.join(" and ")} pinned` : "";
92
+ }
85
93
  /** A page's or an agent's place, as the companion tells it (and a conversation's message, where
86
94
  * its writer was): with its source windows, the one following the selection and those pinned,
87
95
  * each collapsed or not (decided 2026-10-09: what a follower's windows mirror), the build it
@@ -98,9 +106,9 @@ export function placeOf(api, v) {
98
106
  const words = (on && on.id !== PROJECT ? `the view ${JSON.stringify(title)}` : v.scope ? `a view on ${v.scope}` : "the Project view") +
99
107
  (on?.targets ? `, ${on.targets.join(" and ")}'s view` : "") +
100
108
  (v.focus !== undefined ? (v.focus ? `, focused on ${v.focus} for themselves` : ", with no focus for themselves") : "") +
101
- (v.sel ? `, ${v.source ? "reading the source of" : "looking at"} ${v.sel}` : "") +
109
+ (v.sel ? `, ${v.source ? (v.sourceMode === "file" ? "reading the whole file of" : "reading the source of") : "looking at"} ${v.sel}` : "") +
102
110
  (v.selection ? `, with ${v.selection} selected` : "") +
103
- (v.pinned?.length ? `, with the source of ${v.pinned.map((w) => w.decl).join(", ")} pinned` : "");
111
+ pinnedWords(v.pinned ?? []);
104
112
  const built = v.history ? api.world.history?.get(v.history.snapshot)?.at ?? null : null;
105
113
  const then = v.history ? `, in the Time Machine at snapshot ${v.history.snapshot}${built ? ` (built ${built})` : ""}` : "";
106
114
  // the panels and the board besides, in words where they are not as a page starts
@@ -127,7 +135,9 @@ export function placeOf(api, v) {
127
135
  declaration: v.sel,
128
136
  source: v.source,
129
137
  sourceCollapsed: v.source && v.sourceCollapsed === true,
130
- pinned: (v.pinned ?? []).map((w) => ({ declaration: w.decl, collapsed: w.collapsed })),
138
+ // the whole file shown (File mode, the owner's decision of 2026-11-01), and a file window
139
+ ...(v.source && v.sourceMode === "file" ? { sourceMode: "file" } : {}),
140
+ pinned: (v.pinned ?? []).map((w) => ("file" in w ? { file: w.file, collapsed: w.collapsed } : { declaration: w.decl, collapsed: w.collapsed, ...(w.mode === "file" ? { mode: "file" } : {}) })),
131
141
  ...(v.history ? { history: { snapshot: v.history.snapshot, built } } : {}),
132
142
  ...(v.activity ? { activity: { ...v.activity } } : {}),
133
143
  ...(v.lostFound ? { lostAndFound: { open: v.lostFound.open } } : {}),
@@ -1,8 +1,11 @@
1
1
  // What Lean itself says of a name, the endpoints of server/agent.ts that ask Lean's language server
2
2
  // (server/hover.ts): its hover (describe) and what `#print` shows of it (print), asked where a module
3
3
  // of the project's graph is imported, and only there — the module is chosen from the graph, and only
4
- // a name that passes isDeclName is ever written into Lean source.
4
+ // a name that passes isDeclName is ever written into Lean source. And the goals at a place of a
5
+ // file (goals), as the InfoView shows them: only the place, numbers, reaches Lean.
5
6
  import { isDeclName } from "./hover.js";
7
+ import { excerptOf } from "../shared/excerpt.js";
8
+ import { goalText } from "../shared/goals.js";
6
9
  import { View } from "./agentgraph.js";
7
10
  import { clampInt, fail, flag, ok } from "./agent.js";
8
11
  /** The name Lean is asked about and the module imported to ask it: `module` when given (a module
@@ -142,3 +145,90 @@ export const MAX_WAIT = 60_000;
142
145
  /** the most of what `#print` says that an answer carries, in UTF-16 units: a theorem's proof term,
143
146
  * printed with `proofs=1`, can run to megabytes */
144
147
  export const MAX_PRINT = 50_000;
148
+ /** The goals at a place, as the InfoView shows them (ReviewSpec, "The InfoView"; the owner's decision
149
+ * of 2026-11-01), from Lean's language server: a line of a declaration's text (`name`) or of a
150
+ * module's file (`module`), and a column; each goal as Lean writes it. Only the place (numbers) and
151
+ * the module, one of the graph's, reach Lean. The build's text alone: a file changed since it was
152
+ * compiled has none. */
153
+ export async function goals(api, a) {
154
+ const v = api.graph();
155
+ if (!(v instanceof View))
156
+ return v;
157
+ if (!api.lean?.goals)
158
+ return fail(503, "There is no Lean to ask here.", "GET /api/agent/source gives the declaration's text.");
159
+ const q = a.query;
160
+ const name = q.get("name")?.trim() || null;
161
+ const given = q.get("module")?.trim() || null;
162
+ const line = Number(q.get("line"));
163
+ if (!Number.isInteger(line) || line < 1)
164
+ return fail(400, "line is missing, or not a line.", "Give line=<n>, from 1: of the declaration's text with name, of the file with module.");
165
+ const colRaw = q.get("column");
166
+ const column = colRaw === null || colRaw === "" ? null : Number(colRaw);
167
+ if (column !== null && (!Number.isInteger(column) || column < 1 || column > 100_000))
168
+ return fail(400, "column is not a column.", "Give column=<n>, from 1, or leave it out: where the line's code starts.");
169
+ // the file: the declaration's module's, or the module given
170
+ let module;
171
+ let start = 0;
172
+ let end = null;
173
+ if (name) {
174
+ const i = api.find(v, name);
175
+ if (typeof i !== "number")
176
+ return i;
177
+ const n = v.g.nodes[i];
178
+ if (!n.range)
179
+ return fail(404, `The graph records no place for ${n.name} in its file.`, "GET /api/agent/print gives what Lean elaborated.");
180
+ module = n.module;
181
+ const f = v.g.isExt(i) ? api.outsideText(module) : api.file(v, module);
182
+ if (!f)
183
+ return fail(404, `The file of ${module} cannot be read here.`, "GET /api/agent/declaration gives its statement.");
184
+ const at = excerptOf(f.lines, f.edited, n.name, n.range);
185
+ if (!at)
186
+ return fail(404, `${n.name} is no longer in ${f.rel}.`, "Wait for the build; GET /api/agent/declaration gives the compiled statement.");
187
+ start = at.start;
188
+ end = at.end;
189
+ }
190
+ else if (given) {
191
+ if (!isDeclName(given) || (!v.modules.has(given) && !api.world.outsideFile?.(given)))
192
+ return fail(404, `${given.slice(0, 300)} is not a module of the graph.`, "Give a module of the project's graph, or name=<a declaration> and a line of its text.");
193
+ module = given;
194
+ }
195
+ else
196
+ return fail(400, "name or module is missing.", "Give name=<a declaration> and line=<a line of its text, from 1>; or module=<a module> and line=<a line of its file>.");
197
+ // the file as Lean is given it: the project's, or a package's by its resolved path
198
+ const own = v.modules.get(module);
199
+ const out = own ? null : api.world.outsideFile?.(module) ?? null;
200
+ const f = own ? api.file(v, module) : api.outsideText(module);
201
+ if (!f || (!own && !out))
202
+ return fail(404, `The file of ${module} cannot be read here.`, "GET /api/agent/source gives a declaration's text.");
203
+ if (f.edited)
204
+ return fail(409, out ? `${out.file.package.name} is at another revision than the graph was read at: its goals would be another text's than Lean checked.` : `${f.rel} has changed since it was compiled: its goals would be the present text's, not what Lean checked.`, "Wait for the build; GET /api/agent/source gives the text.");
205
+ const fileLine = start + line - 1;
206
+ if (fileLine >= f.lines.length || (end !== null && fileLine > end))
207
+ return fail(400, `line ${line} is past the ${name ? `text of ${name} (${end - start + 1} lines)` : `file (${f.lines.length} lines)`}.`, name ? "Lines count from 1, the declaration's first line, as source gives its text." : "Lines count from 1.");
208
+ const text = f.lines[fileLine];
209
+ const ch = column !== null ? Math.min(column - 1, text.length) : /^\s*/.exec(text)[0].length;
210
+ const file = out ? { name: `${out.file.package.name}: ${out.file.file}`, path: out.file.path } : f.rel;
211
+ const r = await api.lean.goals(file, f.lines.join("\n"), f.hash, fileLine, ch, clampInt(q.get("wait"), 20_000, 1000, MAX_WAIT));
212
+ if (r.pending)
213
+ return fail(503, `Lean is still elaborating ${f.rel}: line ${r.pending.line.toLocaleString("en")} of ${r.pending.of.toLocaleString("en")}.`, "Ask again in a few seconds (Retry-After); the first question about a file can take a minute.", { elaborated: r.pending, retryAfter: 5 }, { "retry-after": "5" });
214
+ if (r.error)
215
+ return fail(502, `Lean could not answer: ${r.error}`, "GET /api/agent/source gives the text; /api/agent/print what Lean elaborated.");
216
+ // a tactic where Lean has a tactic state there: elsewhere the line is no tactic's
217
+ const t = r.tactic && r.tactic.to > r.tactic.from && (r.before || r.after) ? text.slice(r.tactic.from, r.tactic.to) : null;
218
+ return ok({
219
+ ...(name ? { name } : {}),
220
+ module,
221
+ file: f.rel,
222
+ line: fileLine + 1,
223
+ column: ch + 1,
224
+ text,
225
+ tactic: t,
226
+ before: r.before ? r.before.map(goalText) : null,
227
+ after: r.after ? r.after.map(goalText) : null,
228
+ // after a tactic that holds a proof of its own: the goals where the proof goes on, that line's
229
+ // (the owner's decision of 2026-11-01)
230
+ ...(r.afterFrom !== undefined && r.after ? { afterFrom: r.afterFrom + 1 } : {}),
231
+ expected: r.term ? goalText({ hyps: r.term.hyps, type: r.term.type }) : null,
232
+ ...(r.widgets ? { widgets: r.widgets, note: "A widget is here: its JavaScript is the project's code, and VisualProof never runs it. A person sees it in their editor." } : {}),
233
+ });
234
+ }
@@ -67,7 +67,9 @@ function spotShown(s, B) {
67
67
  if (s.at === "world")
68
68
  return { spot: [s.x, s.y] };
69
69
  const about = !s.about ? null : "links" in s.about ? { links: s.about.links } : { clustering: s.about.mode, cluster: s.about.key };
70
- return { ring: s.angle, about };
70
+ // `gone`: the declaration it is attached to, which this build does not have (the owner's decision
71
+ // of 2026-10-30)
72
+ return { ring: s.angle, about, ...(s.gone ? { gone: s.gone } : {}) };
71
73
  }
72
74
  /** what `why` says of a note of the project on a board, for an agent */
73
75
  const WHY_WORDS = {
@@ -97,7 +99,7 @@ export function noteEndpoints(world, refuse) {
97
99
  };
98
100
  const graph = () => graphOf(world) ?? fail(503, "The graph has not been read yet.", "The server is reading the project; ask again in a few seconds.", { retryAfter: 5 }, { "retry-after": "5" });
99
101
  /** whether a key is a cluster of the graph on show by a clustering, and whether a name is one of
100
- * its declarations (where a note attached to one falls back to its places when it is gone) */
102
+ * its declarations (a note attached to one that is gone is on the ring) */
101
103
  const keys = new WeakMap();
102
104
  const exists = (g) => {
103
105
  const f = (m, key) => {
@@ -179,7 +181,7 @@ export function noteEndpoints(world, refuse) {
179
181
  }
180
182
  const s = n;
181
183
  const index = new Map(B?.L.clusters.map((c, k) => [c.key, k]) ?? []);
182
- return { ...base, view, clustering: s.place.mode, here: B ? spotShown(viewSpot(s, B.nb, (key) => index.get(key) ?? -1), B) : null };
184
+ return { ...base, view, clustering: s.place.mode, here: B ? spotShown(viewSpot(s, B.nb, (key) => index.get(key) ?? -1, exists(graphOf(world).g)), B) : null };
183
185
  };
184
186
  /** Apply operations to view `v`'s notes, or the project's, as the agent's, through the path a
185
187
  * page's take. */
@@ -336,7 +338,7 @@ export function noteEndpoints(world, refuse) {
336
338
  * (its spot in its cluster, else its point on the ring). */
337
339
  const restOn = (kind, n, B) => {
338
340
  const index = new Map(B.L.clusters.map((c, k) => [c.key, k]));
339
- const s = kind === "project" ? projectHere(n, B)?.spot : viewSpot(n, B.nb, (key) => index.get(key) ?? -1);
341
+ const s = kind === "project" ? projectHere(n, B)?.spot : viewSpot(n, B.nb, (key) => index.get(key) ?? -1, exists(graphOf(world).g));
340
342
  if (!s)
341
343
  return null;
342
344
  // attached to a declaration: at its offset from the point, a place on the board, as the page
@@ -18,7 +18,10 @@ import { clampInt, fail, flag, ok } from "./agent.js";
18
18
  /** A module of the project (AgentSpec, after the trial of decision 7): its file's doc comments
19
19
  * (`/-! … -/`, where a project keeps the reasons behind its definitions) and every declaration
20
20
  * in it in the order of the file, so that what sits beside a declaration — a variant, a weaker
21
- * form — can be found without reading the file. */
21
+ * form — can be found without reading the file. With `lines`, the file itself, as the source
22
+ * window's File mode shows it (the owner's decision of 2026-11-01): a few hundred lines at a time,
23
+ * a module of the project's, or outside it one an outside declaration of the graph is in (the
24
+ * source window's bounds). */
22
25
  export function moduleGet(api, a) {
23
26
  const v = api.graph();
24
27
  if (!(v instanceof View))
@@ -33,7 +36,15 @@ export function moduleGet(api, a) {
33
36
  }
34
37
  if (!name)
35
38
  return fail(400, "name is missing.", "Give name=<a module of the project> (a declaration's module, as GET declaration says it), or of=<a declaration>.");
39
+ const want = a.query.get("lines");
40
+ const span = want === null ? null : readSpan(want);
41
+ if (want !== null && !span)
42
+ return fail(400, `lines is ${JSON.stringify(want.slice(0, 40))}: give lines=<from>-<to>, from 1, at most ${MAX_FILE_LINES} lines.`, "lines=1-400 gives the file's first 400 lines.");
36
43
  const m = v.modules.get(name);
44
+ // outside the project, the file alone, of a module an outside declaration of the graph is in
45
+ const out = !m && span ? api.outsideText(name) : null;
46
+ if (out)
47
+ return ok({ name, file: out.rel, outside: out.outside, compiled: !out.edited, ...fileLines(out.lines, span) });
37
48
  if (!m) {
38
49
  const last = name.split(".").pop().toLowerCase();
39
50
  const near = [...v.modules.keys()].filter((x) => x.toLowerCase().split(".").pop() === last || x.toLowerCase() === name.toLowerCase()).slice(0, 5);
@@ -81,6 +92,7 @@ export function moduleGet(api, a) {
81
92
  name,
82
93
  file: m.file,
83
94
  ...(f ? { compiled: !f.edited, ...(f.edited ? { note: "The file changed since it was compiled: its doc comments are read from the present text, its declarations are the compiled ones." } : {}) } : {}),
95
+ ...(f && span ? fileLines(f.lines, span) : {}),
84
96
  imports: m.imports,
85
97
  importedBy: [...v.modules].filter(([, x]) => x.imports.includes(name)).map(([k]) => k).sort(),
86
98
  docs,
@@ -92,6 +104,26 @@ export function moduleGet(api, a) {
92
104
  }),
93
105
  });
94
106
  }
107
+ /** the most lines of a file one request reads (`module`, `lines`) */
108
+ export const MAX_FILE_LINES = 400;
109
+ /** `lines=<from>-<to>` read: lines from 1, at most MAX_FILE_LINES of them; `<from>` alone, from
110
+ * there on. Null where it is not that. */
111
+ function readSpan(x) {
112
+ const m = /^(\d{1,7})(?:-(\d{1,7}))?$/.exec(x.trim());
113
+ if (!m)
114
+ return null;
115
+ const from = Number(m[1]), to = m[2] === undefined ? from + MAX_FILE_LINES - 1 : Number(m[2]);
116
+ return from >= 1 && to >= from && to - from < MAX_FILE_LINES ? { from, to } : null;
117
+ }
118
+ /** Lines `from`–`to` of a file (from 1), cut at its end: the text, where it is, and how to ask on. */
119
+ function fileLines(lines, { from, to }) {
120
+ const last = Math.min(to, lines.length);
121
+ return {
122
+ lines: { from, to: last, of: lines.length },
123
+ text: from > lines.length ? "" : lines.slice(from - 1, last).join("\n"),
124
+ ...(last < lines.length ? { more: `lines=${last + 1}-${Math.min(lines.length, last + MAX_FILE_LINES)}` } : {}),
125
+ };
126
+ }
95
127
  export function searchGet(api, a) {
96
128
  const v = api.graph();
97
129
  if (!(v instanceof View))
@@ -28,8 +28,8 @@ import { serveFilm } from "./film.js";
28
28
  import { readOnlyAllows, ReadOnlyBounds } from "./readonlygate.js";
29
29
  import { readBody, refused, sendFile, sendJson, sendRevision, sendText, TooLarge, tooLarge } from "./send.js";
30
30
  import { endedWords, enter, enterReadOnly, identity, identityGet, refuseHost, revokedWords } from "./appaccess.js";
31
- import { shareAgents, sharePeople, shareReadOnly } from "./appshare.js";
32
- import { ask, chat, chatNew, pointer, presence } from "./apptalk.js";
31
+ import { shareAgents, shareClaude, sharePeople, shareReadOnly } from "./appshare.js";
32
+ import { ask, chat, chatNew, chatStop, pointer, presence } from "./apptalk.js";
33
33
  import { history, layoutUndo, libraryRequest, reviewPost, views } from "./appsite.js";
34
34
  import { agentRoute, exportRoute } from "./appagent.js";
35
35
  import { git, graphParts, hover, source, status } from "./appgraph.js";
@@ -309,12 +309,16 @@ export class App {
309
309
  return shareReadOnly(this, req, res, url);
310
310
  if (path.startsWith("/api/share/agents"))
311
311
  return shareAgents(this, req, res, url);
312
+ if (path === "/api/share/claude" || path.startsWith("/api/share/claude/"))
313
+ return shareClaude(this, req, res, url);
312
314
  if (path === "/api/share/people" || path.startsWith("/api/share/people/"))
313
315
  return sharePeople(this, req, res, url);
314
316
  if (path === "/api/chat")
315
317
  return chat(this, req, res, url);
316
318
  if (path === "/api/chat/new")
317
319
  return chatNew(this, req, res);
320
+ if (path === "/api/chat/stop")
321
+ return chatStop(this, req, res);
318
322
  if (path === "/api/ask" || path === "/api/ask/answer")
319
323
  return ask(this, req, res, url);
320
324
  if (path === "/api/agent" || path.startsWith("/api/agent/"))
@@ -367,7 +371,7 @@ export class App {
367
371
  return git(this, res);
368
372
  if (path === "/api/meta" || path === "/api/edges")
369
373
  return graphParts(this, req, res, url);
370
- if (path === "/api/hover" || path === "/api/hover/open" || path === "/api/hover/names" || path === "/api/hover/describe" || path === "/api/hover/print")
374
+ if (path === "/api/hover" || path === "/api/hover/open" || path === "/api/hover/names" || path === "/api/hover/describe" || path === "/api/hover/print" || path === "/api/hover/goals" || path === "/api/hover/goals/info")
371
375
  return hover(this, req, res, url, reader);
372
376
  if (path === "/api/source")
373
377
  return source(this, res, url);
@@ -70,7 +70,7 @@ export async function exportRoute(app, req, res, url, agent, readOnly = false) {
70
70
  export async function agentRoute(app, req, res, url, token = null) {
71
71
  const said = app.ids.who(req);
72
72
  const caller = token
73
- ? { name: token.name, kind: "agent", token: { id: token.id, by: token.by, level: token.level, expires: token.expires }, ...(said && said !== token.name ? { ignoredName: said } : {}) }
73
+ ? { name: token.name, kind: "agent", token: { id: token.id, by: token.by, level: token.level, expires: token.expires, ...(token.runs ? { runs: token.runs } : {}) }, ...(said && said !== token.name ? { ignoredName: said } : {}) }
74
74
  : { name: said, kind: app.ids.kind(req) };
75
75
  let body = null;
76
76
  if (req.method === "POST" && url.pathname.replace(/\/+$/, "") === UPLOAD_PATH) {
@@ -6,11 +6,13 @@ import { gitSource } from "./history.js";
6
6
  import { readFileSync } from "node:fs";
7
7
  import { join } from "node:path";
8
8
  import { isDeclName } from "./hover.js";
9
+ import { MAX_TAGS } from "./goals.js";
9
10
  import { outsideSource } from "./outside.js";
10
11
  import { lakeTextHash } from "./status.js";
11
12
  import { finalAnswer } from "./readonlygate.js";
12
13
  import { slimDeploy } from "../shared/deploy.js";
13
14
  import { packedGz, sendGz, sendJson } from "./send.js";
15
+ import { isCompiledText } from "../shared/build.js";
14
16
  /** with Lean's language server as it is (server/hover.ts): what is open, what crashed
15
17
  * a read-only reader is told how the server is, not its log nor where its review is kept
16
18
  * `?brief`: the build status without its files, which the page reads by GET /api/build */
@@ -145,6 +147,28 @@ export async function hover(app, req, res, url, reader) {
145
147
  const want = url.searchParams.get("hash");
146
148
  if (want && want !== hash)
147
149
  return sendJson(res, { stale: true });
150
+ if (path === "/api/hover/goals" || path === "/api/hover/goals/info") {
151
+ // the InfoView (ReviewSpec, "The InfoView"; the owner's decisions of 2026-11-01): of the text the
152
+ // graph was read from alone. A file changed since it was compiled, or a package at another
153
+ // revision than the graph was read at, has none: its goals would be another text's than Lean
154
+ // checked. Only the place (numbers) and, for a subterm, its number in the answer reach Lean
155
+ const compiled = out ? undefined : live.compiledOf(mod);
156
+ if (out?.changed)
157
+ return reply({ off: `${out.file.package.name} is at another revision than when the graph was read: its goals would be another text's than Lean checked.` });
158
+ if (!out && !isCompiledText(compiled, hash))
159
+ return reply({ off: compiled ? "This file has changed since it was compiled: its goals would be the present text's, not what Lean checked." : "Nothing records which text this file was compiled from (a build restored from Lake's cache, the file modified since): its goals could be another text's than Lean checked." });
160
+ const gl = Number(url.searchParams.get("line")), gc = Number(url.searchParams.get("character"));
161
+ if (!Number.isInteger(gl) || !Number.isInteger(gc) || gl < 0 || gc < 0 || gl > 10_000_000 || gc > 100_000)
162
+ return sendJson(res, { error: "position" }, 400);
163
+ // a place Lean has not reached yet is said so after a moment, and asked again: the pane says how
164
+ // far Lean is meanwhile
165
+ if (path === "/api/hover/goals")
166
+ return reply(await app.hover.goals(file, text, hash, gl, gc, 2000));
167
+ const k = Number(url.searchParams.get("k"));
168
+ if (!Number.isInteger(k) || k < 0 || k >= MAX_TAGS)
169
+ return sendJson(res, { error: "k: a subterm's number in the answer" }, 400);
170
+ return reply(await app.hover.subterm(file, text, hash, gl, gc, k, 6000));
171
+ }
148
172
  if (path === "/api/hover/names") {
149
173
  // the positions of the names in a declaration's source, as JSON [[line, character], …]
150
174
  const r = await app.json(req, 1 << 20);
@@ -8,6 +8,8 @@ import { AGENT_LEVELS, lower } from "./agent.js";
8
8
  import { AgentTokens, DEFAULT_DAYS, invalidAgentName, TOKEN_DAYS } from "./tokens.js";
9
9
  import { agentPrompt } from "./prompt.js";
10
10
  import { reachedAt, sendJson } from "./send.js";
11
+ import { invalidClaudeToken } from "./claudetokens.js";
12
+ import { PER_PERSON } from "./hosted.js";
11
13
  /** Sharing with an AI agent (AgentSpec decision 7), for people: the tokens in force (GET), a new
12
14
  * one with its prompt (POST), a token's prompt shown again (POST …/prompt), and revoking one
13
15
  * (POST …/revoke). All but the list need a name: a token is made under it, and its prompt holds
@@ -25,7 +27,7 @@ export async function shareAgents(app, req, res, url) {
25
27
  const me = app.ids.who(req);
26
28
  const path = url.pathname.replace(/\/+$/, "");
27
29
  if (path === "/api/share/agents" && req.method === "GET")
28
- return sendJson(res, { level: top, levels: AGENT_LEVELS.slice(0, AGENT_LEVELS.indexOf(top) + 1), defaultLevel: lower("advise", top), days: TOKEN_DAYS, defaultDays: DEFAULT_DAYS, tokens: tokens.inForce().map(AgentTokens.info) });
30
+ return sendJson(res, { level: top, levels: AGENT_LEVELS.slice(0, AGENT_LEVELS.indexOf(top) + 1), defaultLevel: lower("advise", top), days: TOKEN_DAYS, defaultDays: DEFAULT_DAYS, tokens: tokens.inForce().map(AgentTokens.info), server: onServer(app, req) });
29
31
  if (req.method !== "POST")
30
32
  return sendJson(res, { error: `${path} answers POST.` }, 405);
31
33
  if (!me)
@@ -47,6 +49,9 @@ export async function shareAgents(app, req, res, url) {
47
49
  const t = typeof b.id === "string" ? tokens.token(b.id) : null;
48
50
  if (!t)
49
51
  return sendJson(res, { error: "There is no such token in force." }, 404);
52
+ // an agent the server runs has none: its token never leaves the server (AgentSpec decision 10)
53
+ if (t.record.runs === "server")
54
+ return sendJson(res, { error: `${t.record.name} runs on this server: it has no prompt, and its token never leaves the server.`, runs: "server" }, 400);
50
55
  if (!madeBy(t.record, { name: me, person: app.ids.person(req)?.id ?? null }))
51
56
  return sendJson(res, { error: `Only ${t.record.by}, who made it, is shown this token's prompt again: whoever holds a token reads its agent's private channel.`, maker: false }, 403);
52
57
  return sendJson(res, { token: AgentTokens.info(t.record), prompt: agentPrompt({ url: address, token: t.token, record: t.record }) });
@@ -66,10 +71,123 @@ export async function shareAgents(app, req, res, url) {
66
71
  const days = b.days ?? DEFAULT_DAYS;
67
72
  if (!TOKEN_DAYS.includes(days))
68
73
  return sendJson(res, { error: `days is one of ${TOKEN_DAYS.join(", ")}.` }, 400);
74
+ // an agent the server runs, on its maker's Claude Code (AgentSpec decision 10): no prompt, and its
75
+ // token lasts until revoked
76
+ if (b.runs === "server") {
77
+ const why = mayRunHere(app, req);
78
+ if (why)
79
+ return sendJson(res, { error: why }, 403);
80
+ const person = app.ids.person(req)?.id ?? null;
81
+ if (!app.live.claudeTokens.forMaker({ by: me, ...(person ? { makerPerson: person } : {}) }))
82
+ return sendJson(res, { error: app.live.claudeTokens.info({ person, name: me })?.refused ? "Claude Code refused your token: give a new one first." : "Give your Claude Code OAuth token first: the agent runs on it.", claudeToken: true }, 409);
83
+ const mine = tokens.inForce().filter((t) => t.runs === "server" && madeBy(t, { name: me, person }));
84
+ if (mine.length >= PER_PERSON)
85
+ return sendJson(res, { error: `You run ${PER_PERSON} agents on this server already: revoke one first.` }, 409);
86
+ const made = tokens.create({ name: name.trim(), by: me, person, level, days: DEFAULT_DAYS, runs: "server" });
87
+ app.live.hosted.start(made.record);
88
+ return sendJson(res, { token: AgentTokens.info(made.record), tokens: tokens.inForce().map(AgentTokens.info) });
89
+ }
90
+ if (b.runs !== undefined && b.runs !== null && b.runs !== "agent")
91
+ return sendJson(res, { error: 'runs is "server", or left out for a prompt.' }, 400);
69
92
  const made = tokens.create({ name: name.trim(), by: me, person: app.ids.person(req)?.id ?? null, level, days: days });
70
93
  const prompt = agentPrompt({ url: address, token: made.token, record: made.record });
71
94
  return sendJson(res, { token: AgentTokens.info(made.record), prompt, tokens: tokens.inForce().map(AgentTokens.info) });
72
95
  }
96
+ /** What Share's AI agent tab is told of running agents on this server (AgentSpec decision 10): null
97
+ * where it runs none (no --claude-oauth); else whether it can (Claude Code is here), whether the
98
+ * reader may (why not), and whether they gave a Claude token — when, and whether it was refused;
99
+ * never the token. */
100
+ function onServer(app, req) {
101
+ const hosted = app.live.hosted;
102
+ if (!hosted)
103
+ return null;
104
+ const me = app.ids.who(req);
105
+ const person = app.ids.person(req)?.id ?? null;
106
+ return {
107
+ available: hosted.available,
108
+ refused: mayRunHere(app, req),
109
+ token: me ? app.live.claudeTokens.info({ person, name: me }) : null,
110
+ perPerson: PER_PERSON,
111
+ };
112
+ }
113
+ /** Why the reader may not run an agent on this server, nor give a Claude token; null when they may:
114
+ * the server runs agents (--claude-oauth) and Claude Code is on its machine; the reader is a person
115
+ * whose name is theirs alone — their personal link's, the sign-in's in front of the server, or, on
116
+ * a server without a key reached on this machine only, whoever gives it — so that nobody runs agents
117
+ * on someone else's subscription by giving their name (the owner's decision of 2026-11-08). */
118
+ export function mayRunHere(app, req) {
119
+ const hosted = app.live.hosted;
120
+ if (!hosted)
121
+ return "This server runs no agents of its own: it was started without --claude-oauth.";
122
+ if (!hosted.available)
123
+ return "Claude Code (claude) is not on this server's machine: it runs no agents of its own.";
124
+ if (app.ids.kind(req) === "agent")
125
+ return "Agents cannot run agents.";
126
+ if (app.readOnlyOf.has(req))
127
+ return "This page is read-only.";
128
+ const here = !app.access && !app.ids.header && loopbackHost(req.headers.host) && loopbackAddress(req.socket.remoteAddress);
129
+ if (!app.ids.person(req) && !app.ids.header && !here)
130
+ return "Only someone whose name is theirs alone runs agents on this server: come by your personal link (Share, Invite a person), so that nobody can run one on your Claude Code by giving your name.";
131
+ return null;
132
+ }
133
+ /** A Claude Code OAuth token given in Share (AgentSpec decision 10), for people: POST
134
+ * /api/share/claude {token} gives it, in place of the one before; POST …/remove removes it. Never
135
+ * answered back: what Share is told of it is GET /api/share/agents's `server.token`. Only from a page
136
+ * over HTTPS or on this machine: a year of a subscription does not cross a network in the clear. */
137
+ export async function shareClaude(app, req, res, url) {
138
+ const path = url.pathname.replace(/\/+$/, "");
139
+ if (req.method !== "POST")
140
+ return sendJson(res, { error: `${path} answers POST.` }, 405);
141
+ const why = mayRunHere(app, req);
142
+ if (why)
143
+ return sendJson(res, { error: why }, app.live.hosted ? 403 : 404);
144
+ const me = app.ids.who(req);
145
+ if (!me)
146
+ return sendJson(res, { error: "Say who you are first: a Claude token is kept under your name.", who: true }, 401);
147
+ const who = { person: app.ids.person(req)?.id ?? null, name: me };
148
+ const claude = app.live.claudeTokens;
149
+ if (path === "/api/share/claude/remove") {
150
+ if (!claude.remove(who))
151
+ return sendJson(res, { error: "You gave no Claude Code token." }, 404);
152
+ return sendJson(res, { ok: true, token: null });
153
+ }
154
+ if (path !== "/api/share/claude")
155
+ return sendJson(res, { error: "not found" }, 404);
156
+ if (!securePage(req.headers.origin))
157
+ return sendJson(res, { error: "A Claude Code token is given from a page over HTTPS, or on this machine: over plain HTTP it would cross the network in the clear.", insecure: true }, 403);
158
+ const r = await app.json(req, 4096);
159
+ if (r.error !== undefined)
160
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
161
+ const token = r.body?.token;
162
+ const bad = invalidClaudeToken(token);
163
+ if (bad)
164
+ return sendJson(res, { error: bad }, 400);
165
+ claude.give(who, token.trim());
166
+ return sendJson(res, { ok: true, token: claude.info(who) });
167
+ }
168
+ /** Whether a page's Origin is over HTTPS, or on this machine. */
169
+ function securePage(origin) {
170
+ if (!origin)
171
+ return false;
172
+ try {
173
+ const u = new URL(origin);
174
+ return u.protocol === "https:" || (u.protocol === "http:" && loopbackHost(u.host));
175
+ }
176
+ catch {
177
+ return false;
178
+ }
179
+ }
180
+ /** Whether a Host names this machine: localhost (or a name under it), 127.x.y.z, [::1]. */
181
+ function loopbackHost(host) {
182
+ if (!host)
183
+ return false;
184
+ const name = host.replace(/:\d+$/, "").replace(/^\[|\]$/g, "").toLowerCase();
185
+ return name === "localhost" || name.endsWith(".localhost") || /^127\.\d+\.\d+\.\d+$/.test(name) || name === "::1";
186
+ }
187
+ /** Whether a connection comes from this machine. */
188
+ function loopbackAddress(a) {
189
+ return !!a && (/^127\./.test(a) || a === "::1" || /^::ffff:127\./.test(a));
190
+ }
73
191
  /** Inviting a person (CollabSpec decision 9), for people: the personal links in force (GET), a new
74
192
  * one for a person named in the body (POST), and revoking one (POST …/revoke). Making and
75
193
  * revoking need a name: who made a link, and who revoked it, is said in Share. The link itself
@@ -151,6 +151,32 @@ export async function chatNew(app, req, res) {
151
151
  const divider = live.talk.restart(tok, me);
152
152
  return sendJson(res, { ok: true, divider: divider && forPages(divider) });
153
153
  }
154
+ /** Stop the turn an agent the server runs is taking (AgentSpec decision 10): POST /api/chat/stop
155
+ * {agent}, from its maker alone, as Esc in a terminal stops an agent someone runs there. What it
156
+ * was answering ends with it; the agent listens again. */
157
+ export async function chatStop(app, req, res) {
158
+ const live = app.live;
159
+ if (req.method !== "POST")
160
+ return sendJson(res, { error: "/api/chat/stop answers POST." }, 405);
161
+ if (app.readOnlyOf.has(req))
162
+ return sendJson(res, { error: "This page is read-only.", readOnly: true }, 403);
163
+ if (app.ids.kind(req) === "agent")
164
+ return sendJson(res, { error: "An agent's turn is stopped by people." }, 403);
165
+ const me = app.ids.who(req);
166
+ if (!me)
167
+ return sendJson(res, { error: "Say who you are first.", who: true }, 401);
168
+ const r = await app.json(req, 1 << 12);
169
+ if (r.error !== undefined)
170
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
171
+ const b = (r.body ?? {});
172
+ const tok = typeof b.agent === "string" ? live.presence.tokenOf(b.agent) : null;
173
+ const record = tok ? live.tokens.get(tok) : undefined;
174
+ if (!tok || !record || record.runs !== "server")
175
+ return sendJson(res, { error: "There is no such agent running on this server." }, 404);
176
+ if (!madeBy(record, { name: me, person: app.ids.person(req)?.id ?? null }))
177
+ return sendJson(res, { error: `Only ${record.by}, who runs ${record.name}, stops its turn.` }, 403);
178
+ return sendJson(res, { ok: true, stopped: live.hosted?.stopTurn(tok) ?? false });
179
+ }
154
180
  /** Asking others to follow (CollabSpec decision 10, the owner's decision of 2026-10-12), for pages:
155
181
  * POST /api/ask {token, to?} — the page whose event stream holds `token` asks everyone on the
156
182
  * server, or the person whose page is listed as `to`, to follow its reader, who has a name and is
@@ -151,7 +151,7 @@ export function boardSpots(b) {
151
151
  place(n, "project", why ? itemSpot(n, nb, exists, linkedOn(n, nb, links)) : null);
152
152
  }
153
153
  for (const n of rec.notes ?? [])
154
- place(n, "view", viewSpot(n, nb, (key) => index.get(key) ?? -1));
154
+ place(n, "view", viewSpot(n, nb, (key) => index.get(key) ?? -1, exists));
155
155
  // in the order they were written, which is the order of those level on the board: the notes that
156
156
  // point nowhere on the ring, at its top
157
157
  notes.sort((x, y) => (x.note.at < y.note.at ? -1 : x.note.at > y.note.at ? 1 : 0));
@@ -47,14 +47,18 @@ export function tracked(child) {
47
47
  }
48
48
  /** The environment a program the server runs is given: the server's own, without what is the
49
49
  * server's alone (`VISUALPROOF_*`: the supervisor's word to it, its test hooks; UpdateSpec decision
50
- * 9), with `extra` over it. */
50
+ * 9) and without Claude's and Anthropic's credentials (CREDENTIAL), with `extra` over it. */
51
51
  export function childEnv(extra = {}) {
52
52
  const env = {};
53
53
  for (const [k, v] of Object.entries(process.env))
54
- if (!k.startsWith("VISUALPROOF_"))
54
+ if (!k.startsWith("VISUALPROOF_") && !CREDENTIAL(k))
55
55
  env[k] = v;
56
56
  return { ...env, ...extra };
57
57
  }
58
+ /** Claude's and Anthropic's credentials, where the server's environment has them: no program the
59
+ * server runs is given them (Lake, Lean, git, a branch's build, which runs whatever its code says);
60
+ * the agents the server runs are given their maker's token alone (server/hosted.ts). */
61
+ const CREDENTIAL = (k) => k === "CLAUDE_CODE_OAUTH_TOKEN" || k.startsWith("ANTHROPIC_");
58
62
  /** How many tracked programs run now. */
59
63
  export function childCount() {
60
64
  return running.size;