onionskin-cli 0.0.0-stage → 0.0.1

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 (117) hide show
  1. package/CHANGELOG.md +136 -0
  2. package/INSTALL.md +17 -0
  3. package/LICENSE +21 -0
  4. package/NOTICE +46 -0
  5. package/README.md +88 -2
  6. package/docs/contracts/batch.schema.json +839 -0
  7. package/docs/contracts/history.schema.json +126 -0
  8. package/docs/contracts/ops.schema.json +541 -0
  9. package/package.json +54 -4
  10. package/scripts/checker/check.py +411 -0
  11. package/scripts/checker/requirements.txt +5 -0
  12. package/scripts/install-check.mjs +9 -0
  13. package/scripts/requirements.txt +5 -0
  14. package/scripts/rewriter/apple/main.swift +135 -0
  15. package/scripts/rewriter/apple/onionskin-fm +0 -0
  16. package/scripts/rewriter/apple/onionskin-fm.json +6 -0
  17. package/skills/onionskin/SKILL.md +117 -0
  18. package/skills/onionskin/reference/batch.md +94 -0
  19. package/skills/onionskin/reference/formats.md +15 -0
  20. package/skills/onionskin/reference/ops.md +253 -0
  21. package/skills/onionskin/reference/troubleshooting.md +73 -0
  22. package/skills/onionskin/reference/voice-guide.md +86 -0
  23. package/skills/onionskin/voice.example.md +51 -0
  24. package/src/agent-detect.js +149 -0
  25. package/src/agent-events.js +159 -0
  26. package/src/agent-prompt.js +27 -0
  27. package/src/agent-runner.js +593 -0
  28. package/src/analyze.js +17 -0
  29. package/src/anchors.js +190 -0
  30. package/src/apply.js +387 -0
  31. package/src/auth.js +130 -0
  32. package/src/batch.js +322 -0
  33. package/src/check-worker.js +8 -0
  34. package/src/checker.js +293 -0
  35. package/src/cli.js +516 -0
  36. package/src/constants.js +20 -0
  37. package/src/diff.js +267 -0
  38. package/src/doctor.js +247 -0
  39. package/src/docx.js +438 -0
  40. package/src/fmt.js +30 -0
  41. package/src/fsutil.js +348 -0
  42. package/src/history-worker.js +16 -0
  43. package/src/history.js +576 -0
  44. package/src/lease.js +79 -0
  45. package/src/local.js +242 -0
  46. package/src/merge-pptx.js +198 -0
  47. package/src/merge-xlsx.js +453 -0
  48. package/src/merge.js +410 -0
  49. package/src/offload.js +34 -0
  50. package/src/ops/common.js +48 -0
  51. package/src/ops/docx-table.js +323 -0
  52. package/src/ops/docx.js +503 -0
  53. package/src/ops/engine.js +41 -0
  54. package/src/ops/pptx.js +336 -0
  55. package/src/ops/run.js +115 -0
  56. package/src/ops/runs.js +127 -0
  57. package/src/ops/schema.js +109 -0
  58. package/src/ops/xlsx.js +277 -0
  59. package/src/package.js +189 -0
  60. package/src/paths.js +64 -0
  61. package/src/person.js +66 -0
  62. package/src/pptx.js +194 -0
  63. package/src/question.js +47 -0
  64. package/src/quick-plan.js +107 -0
  65. package/src/quick.js +164 -0
  66. package/src/redline-check.js +251 -0
  67. package/src/redline-worker.js +29 -0
  68. package/src/redline.js +438 -0
  69. package/src/reply.js +410 -0
  70. package/src/review.js +274 -0
  71. package/src/rewrite-check.js +1014 -0
  72. package/src/rewriter-cleanup.js +105 -0
  73. package/src/rewriter-setup.js +104 -0
  74. package/src/rewriter.js +396 -0
  75. package/src/sanitize.js +42 -0
  76. package/src/sentence-span.js +25 -0
  77. package/src/server-entry.js +13 -0
  78. package/src/server.js +576 -0
  79. package/src/session.js +1910 -0
  80. package/src/settings.js +161 -0
  81. package/src/setup.js +160 -0
  82. package/src/stamp-words.js +10 -0
  83. package/src/stamps.js +59 -0
  84. package/src/style.js +110 -0
  85. package/src/suggest-reply.js +84 -0
  86. package/src/suggest.js +261 -0
  87. package/src/text.js +31 -0
  88. package/src/tracked-words.js +43 -0
  89. package/src/voice-guide.js +182 -0
  90. package/src/voice-learn.js +314 -0
  91. package/src/voice-sample-worker.js +95 -0
  92. package/src/voice-samples.js +329 -0
  93. package/src/voice-store.js +305 -0
  94. package/src/voice-worker.js +28 -0
  95. package/src/voice.js +297 -0
  96. package/src/xlsx.js +454 -0
  97. package/src/xml-tree.js +118 -0
  98. package/src/xml.js +127 -0
  99. package/src/zip-write.js +74 -0
  100. package/src/zip.js +88 -0
  101. package/vendor/engine/DocViewer-BZLXUcxJ.js +15137 -0
  102. package/vendor/engine/THIRD_PARTY_LICENSES.txt +79 -0
  103. package/vendor/engine/collab-BVynXMqc.js +2591 -0
  104. package/vendor/engine/collab.js +2 -0
  105. package/vendor/engine/core.js +4 -0
  106. package/vendor/engine/default-worker-DogNT09A.js +35625 -0
  107. package/vendor/engine/embed.js +107 -0
  108. package/vendor/engine/index.js +5 -0
  109. package/vendor/engine/office-engine.embed.js +184 -0
  110. package/vendor/engine/office-engine.worker.js +36030 -0
  111. package/vendor/engine/xlsx-ops-SYAv6V0f.js +939 -0
  112. package/vendor/engine-node/LICENSE +21 -0
  113. package/vendor/engine-node/engine-node.mjs +46618 -0
  114. package/vendor/engine.lock.json +26 -0
  115. package/web/dist/assets/index-CFISATkn.js +197 -0
  116. package/web/dist/assets/index-spXE4oTz.css +1 -0
  117. package/web/dist/index.html +14 -0
package/src/session.js ADDED
@@ -0,0 +1,1910 @@
1
+ import crypto from "node:crypto";
2
+ import { EventEmitter } from "node:events";
3
+ import fs from "node:fs";
4
+ import path from "node:path";
5
+ import { REFUSED_EXTENSIONS, FORMATS, MAX_DOC_BYTES, PRODUCT, env } from "./constants.js";
6
+ import { buildDurable, readUnits, resolveDurableAny, resolveView, viewDurable } from "./anchors.js";
7
+ import { durableFromEngine, headingBefore, resolveDurable } from "./docx.js";
8
+ import { checkRegularOwned, readDoc, replaceGuarded, sha256, Snapshots, WriteConflict, writeSiblingCopy } from "./fsutil.js";
9
+ import { buildBatch, compactBatch, withOutline } from "./batch.js";
10
+ import { styleChangedOutside, styleNote } from "./style.js";
11
+ import { guideChangedOutside, voiceGuide, writeDraft } from "./voice-store.js";
12
+ import { cleanVoiceDraft } from "./voice-guide.js";
13
+ import { voiceJob } from "./voice-learn.js";
14
+ import { clearTickets, saveTicket, ticketOf } from "./lease.js";
15
+ import { analyze } from "./analyze.js";
16
+ import { deepNotice, validatePackage } from "./package.js";
17
+ import { execFile } from "node:child_process";
18
+ import { sessionKey, stateDir, sub, writeStateFile } from "./paths.js";
19
+ import { cleanFlag, hasControlChars, untrusted, userText } from "./sanitize.js";
20
+ import { addUpdate, historyDetail, historyList, visibleUpdates } from "./history.js";
21
+ import { BAD_QUESTION_NOTE, QUESTIONS_PER_BATCH, cleanQuestion } from "./question.js";
22
+ import { validateOps } from "./ops/schema.js";
23
+ import { Worker } from "node:worker_threads";
24
+ import { AUTHORS, wordDate } from "./redline.js";
25
+ import { deepRedline } from "./checker.js";
26
+ import { TRACKED, formattingText, savedText, unsupportedText } from "./tracked-words.js";
27
+ import { LOCAL_HOLDER } from "./local.js";
28
+ import { bgHolder, isAgentHolder, isBgHolder, termHolder, TERM_PREFIX } from "./agent-detect.js";
29
+ import { OUTLINE_FILE_MAX, REVIEW_ASKS, REVIEW_KINDS, SUGGESTIONS_MAX, UNITS_MAX, cardsFrom, outlineOf, reviewSummary, unitsOf } from "./review.js";
30
+ import { VOICE_BATCH_MAX_CHARS } from "./voice-samples.js";
31
+ import { STAMP_WORDS } from "./stamp-words.js";
32
+ import { USE_SUMMARY, buildUseReply, placeOf } from "./suggest-reply.js";
33
+
34
+ /** The line under a comment whose quick fixes could not be written on this Mac (docs/contracts/routes.md). */
35
+ export const LOCAL_HINT = "This could not be changed on this Mac, so nothing was written. Press Send to ask the agent.";
36
+
37
+ /**
38
+ * A batch that may not write the file: "review" (src/review.js) or "voice" ("Build my voice guide"), from the batch itself so it holds
39
+ * after a restart; null for an ordinary batch. While one is delivered, apply and commit are refused and `done` takes its own branch.
40
+ */
41
+ const readOnlyKind = (batch) => (batch?.instructions?.voice_request ? "voice" : batch?.instructions?.review ? "review" : null);
42
+ const READ_ONLY = {
43
+ review: "this batch is a review: nothing is written. Answer with `reply` and `suggest`.",
44
+ voice: "this batch asks for a draft of the voice guide: nothing is written. Answer with `reply` and `voice_draft`.",
45
+ };
46
+ // the activity summary of a voice run: fixed text, never the agent's own summary
47
+ /** The flag text for a file changed behind the lease by a direct save, in the words of whoever made the change (a run on this Mac has no agent). */
48
+ const directSave = (local) => `The file changed ${local ? "while the change was made on this Mac" : "during the agent's turn"} by a path other than apply or commit (a direct save). Nothing extra was copied: the earlier version is stored; Revert restores it.`;
49
+ const VOICE_KEPT = "The agent wrote a draft of your voice guide.";
50
+ const VOICE_REFUSED = "The agent's draft could not be shown.";
51
+ const VOICE_REPLACED = "Your Send replaced the voice guide request that was waiting for the agent. Build it again when you are ready.";
52
+
53
+ export class HttpError extends Error {
54
+ constructor(status, message, extra = {}) {
55
+ super(message);
56
+ this.status = status;
57
+ this.extra = extra;
58
+ }
59
+ }
60
+
61
+ const LEASE_MS = () => Number(env("LEASE_MS", 15 * 60 * 1000));
62
+ const MAX_BYTES = MAX_DOC_BYTES;
63
+ /** "Show in folder" exists on macOS (`open -R`); elsewhere the page shows the path. ONIONSKIN_NO_OPEN=1 turns it off, ONIONSKIN_OPEN_STUB=<file> records instead of launching. */
64
+ const canReveal = () => !!env("OPEN_STUB") || (process.platform === "darwin" && !env("NO_OPEN"));
65
+ /** readDoc with the size refusal as an HTTP error */
66
+ function readCapped(file) {
67
+ try {
68
+ return readDoc(file);
69
+ } catch (err) {
70
+ if (err.code === "TOO_LARGE") throw new HttpError(413, `document too large: ${err.message}`, { code: "too_large" });
71
+ throw err;
72
+ }
73
+ }
74
+
75
+ const num = (v) => (Number.isFinite(Number(v)) ? Math.round(Number(v) * 1000) / 1000 : 0);
76
+ /** A pin: x/y as fractions of the element it sits on (`yPx` is kept for DOCX paragraphs); `on` says what that element is. */
77
+ function cleanPin(p) {
78
+ const out = { xFrac: num(p.xFrac), yPx: num(p.yPx) };
79
+ if (p.yFrac != null) out.yFrac = num(p.yFrac);
80
+ if (["paragraph", "cell", "shape", "slide"].includes(p.on)) out.on = p.on;
81
+ if (p.sxFrac != null) {
82
+ out.sxFrac = num(p.sxFrac);
83
+ out.syFrac = num(p.syFrac);
84
+ }
85
+ return out;
86
+ }
87
+
88
+ const APPLY_STATUS = new Set(["refused", "skipped_protected", "anchor_not_found", "expect_mismatch", "not_applied"]);
89
+ // the three-way merge of each format (loaded on first use: they pull in the engine)
90
+ const MERGERS = { docx: { module: "./merge.js", fn: "mergeDocx" }, xlsx: { module: "./merge-xlsx.js", fn: "mergeXlsx" }, pptx: { module: "./merge-pptx.js", fn: "mergePptx" } };
91
+ const HELD_SHOWN = 5; // items the page's "not in the document" message lists (web/src/Banners.jsx)
92
+ const WRITES_KEPT = 20; // writes per file the merge can trace (src/merge-xlsx.js agentChanges); an older base finds no record and is handed back
93
+ /** What the page says the user did during the run: kinds and places only, used to hold edits back or to name what is not carried, never to write. */
94
+ const editKinds = (edits) => (Array.isArray(edits) ? edits.slice(0, 2000) : []).map((e) => ({ kind: String(e?.kind ?? "").slice(0, 40), sheet: typeof e?.sheet === "string" ? e.sheet.slice(0, 100) : null, slide: Number.isInteger(e?.slide) ? e.slide : null }));
95
+ /** One op `apply` did not apply, as the page shows it: codes and short reasons only (never document text). */
96
+ function cleanProblem(p, run = "") {
97
+ return {
98
+ key: untrusted(p?.key || `${p?.index ?? ""}:${p?.op ?? ""}`, 80),
99
+ run: untrusted(run, 40),
100
+ op: untrusted(p?.op, 40),
101
+ status: APPLY_STATUS.has(p?.status) ? p.status : "refused",
102
+ code: p?.code ? untrusted(p.code, 60) : null,
103
+ reason: untrusted(p?.reason, 200),
104
+ };
105
+ }
106
+
107
+ function shellQuote(s) {
108
+ return `'${String(s).replace(/'/g, `'\\''`)}'`;
109
+ }
110
+
111
+ /** A stored durable anchor re-resolved against `units` (the bytes the agent will read next); null when the unit is gone. Without a durable, one is built from the browser's anchor. */
112
+ function reanchor(units, c) {
113
+ const d = c.durable;
114
+ if (!d) return buildDurable(units, c.anchor);
115
+ const r = resolveDurableAny(units, d);
116
+ if (r.method === "none") return null;
117
+ if (units.format === "docx") return { ...d, ...r, format: "docx", quote: d.quote, prefix: d.prefix, suffix: d.suffix, paraText: r.text, engineDelta: r.engineDelta };
118
+ if (units.format === "xlsx") return buildDurable(units, { location: { sheetIndex: r.sheetIndex, sheetName: r.sheetName, range: r.range } });
119
+ return buildDurable(units, { location: { slideIndex: r.slideIndex, slideId: r.slideId, shapeId: r.shapeId ?? undefined, shapeName: r.shapeName, cell: d.cell || undefined }, quote: d.quote, prefix: d.prefix, suffix: d.suffix, hitKind: d.quote ? undefined : "shape" });
120
+ }
121
+
122
+ /**
123
+ * All session state and transitions, with no HTTP in it.
124
+ * States (derived): idle, listening, working, queued, stranded, closed. poll results add timeout and superseded.
125
+ * - Send with a poller waiting: batch delivered, session `working`, document locked.
126
+ * - Send with nobody polling: batch kept as `pending`, session `stranded`, document stays editable.
127
+ * - Send while working: comments only, kept as `queued`; released to the next poller after `done`.
128
+ * - Lease expiry or Take back: `delivered` is withdrawn, the document unlocks.
129
+ */
130
+ export class Sessions extends EventEmitter {
131
+ // delivered run -> styleChangedOutside() when it went out; memory only, so a run reloaded after a restart has none and is not flagged
132
+ #styleSeen = new WeakMap();
133
+ // delivered run -> guideChangedOutside() when it went out (the same idea for voice-guide.json); taking it also arms the guide's guard
134
+ #guideSeen = new WeakMap();
135
+ constructor({ now = Date.now } = {}) {
136
+ super();
137
+ this.now = now;
138
+ this.map = new Map(); // key -> session
139
+ this.createdCopies = new Set(); // absolute paths of conflict copies THIS server wrote: the only paths `showCopy` will reveal
140
+ this.editors = new Map(); // key -> id of the one browser tab that may edit (in memory only: a tab's id lives as long as its page)
141
+ this.briefed = new Map(); // key -> Set of holders that already received a complete batch in this session (memory only: a restarted server briefs again)
142
+ // key -> how the file got from one version to the next, oldest first: {from, to, route: "apply", ops, partial, anchors} for an agent's
143
+ // apply, {from, to, route: "commit"} for a commit, {from, to, route: "merge", stable} for a pass of the user's merge. The merge reads it
144
+ // to know whether cell addresses still hold. Memory only (ops carry document text): after a restart there is no record, and edits are handed back.
145
+ this.writes = new Map();
146
+ this.exporting = new Set(); // keys with a tracked-changes copy being made: one at a time per file
147
+ this.local = null; // the local runner's {wants(s, batch)} (src/local.js), set by the server; null: every batch goes to an agent
148
+ this.agent = null; // the background agent runner's {viewFor(key)} (src/agent-runner.js), set by the server; null: no background agent
149
+ }
150
+
151
+ // ---- one editable tab per file -----------------------------------------------------------------------------
152
+ /** A tab asks to be the editor. The first one wins; `takeover` is the user's explicit "Edit here instead". Returns whether this tab is the editor. */
153
+ claimEditor(key, tab, { takeover = false } = {}) {
154
+ const s = this.get(key);
155
+ const cur = this.editors.get(key);
156
+ if (cur && cur !== tab && !takeover) return false;
157
+ if (cur !== tab) {
158
+ this.editors.set(key, tab);
159
+ this.emit("change", s, "state");
160
+ }
161
+ return true;
162
+ }
163
+
164
+ /** The tab's event stream ended (closed, reloaded): the file has no editor until a tab claims it. */
165
+ releaseEditor(key, tab) {
166
+ if (this.editors.get(key) !== tab) return;
167
+ this.editors.delete(key);
168
+ const s = this.map.get(key);
169
+ if (s) this.emit("change", s, "state");
170
+ }
171
+
172
+ /** Browser routes that change the session refuse a tab that is not the editor (when a tab holds the file). */
173
+ requireEditor(key, tab) {
174
+ const cur = this.editors.get(key);
175
+ if (cur && cur !== tab) throw new HttpError(409, "This file is open for editing in another tab. Use Edit here instead to take over.", { code: "not_editor" });
176
+ }
177
+
178
+ // ---- open ------------------------------------------------------------------------------------------------
179
+ /** `opts.agent === "background"`: the person opened it from a terminal, so the server's background agent works on it (stored on the session). */
180
+ open(input, opts = {}) {
181
+ let real;
182
+ try {
183
+ real = fs.realpathSync(path.resolve(input));
184
+ } catch {
185
+ throw new HttpError(404, `File not found: ${JSON.stringify(untrusted(input, 200))}`);
186
+ }
187
+ // a path with control or bidi characters would sit in the commands printed for the agent: refuse it up front
188
+ if (hasControlChars(real)) throw new HttpError(400, "This file's path contains control or bidirectional-text characters. Rename or move the file and open it again.", { code: "unsafe_path" });
189
+ const ext = path.extname(real).toLowerCase();
190
+ if (REFUSED_EXTENSIONS.has(ext)) throw new HttpError(400, `${ext} (macro-enabled) files are refused`);
191
+ const format = ext.slice(1);
192
+ if (!FORMATS[format]) throw new HttpError(400, "Only .docx, .xlsx and .pptx files are supported");
193
+ let st;
194
+ try {
195
+ st = checkRegularOwned(real);
196
+ } catch (err) {
197
+ throw new HttpError(400, err.message);
198
+ }
199
+ const bytes = readCapped(real);
200
+ try {
201
+ validatePackage(bytes, format);
202
+ } catch (err) {
203
+ throw new HttpError(400, `Not a valid .${format}: ${err.message}`);
204
+ }
205
+ const key = sessionKey(real);
206
+ let s = this.map.get(key);
207
+ const sha = sha256(bytes);
208
+ if (!s) {
209
+ s = this.#load(key) || this.#fresh(key, real, format, sha);
210
+ s.file = real;
211
+ s.format = format;
212
+ this.map.set(key, s);
213
+ }
214
+ s.snapshots = new Snapshots(key);
215
+ if (!s.snapshots.index().some((e) => e.original)) s.snapshots.add(bytes, "original", { original: true });
216
+ if (!s.delivered && s.baseSha !== sha) s.baseSha = sha; // the user re-opened: the file on disk is the base
217
+ if (!s.delivered && s.histTip !== sha) {
218
+ // history starts from the version the user opened (kept as a snapshot so a later outside change has a "before")
219
+ try {
220
+ if (!s.snapshots.has(sha)) s.snapshots.add(bytes, "opened");
221
+ } catch {} // a full disk must not block opening
222
+ s.histTip = sha;
223
+ }
224
+ s.mtimeMs = st.mtimeMs;
225
+ s.closed = false;
226
+ if (opts.agent === "background") s.openedFor = "background";
227
+ s.mode = st.mode & 0o7777;
228
+ this.#save(s);
229
+ this.emit("change", s);
230
+ return s;
231
+ }
232
+
233
+ #fresh(key, file, format, sha) {
234
+ return {
235
+ key, file, format, baseSha: sha, comments: [], note: "", queuedNote: "", edits: [], pending: null, delivered: null, queued: false,
236
+ activity: [], view: null, closed: false, pollers: [], seq: 0, createdAt: this.now(), history: [], histTip: null,
237
+ };
238
+ }
239
+
240
+ #load(key) {
241
+ try {
242
+ const f = path.join(sub("sessions"), `${key}.json`);
243
+ const j = JSON.parse(fs.readFileSync(f, "utf8"));
244
+ const s = { ...this.#fresh(key, j.file, j.format, j.baseSha), ...j, pollers: [] };
245
+ // a hard kill can leave work in flight that no result will ever settle
246
+ if (s.delivered?.stage === "checking") s.delivered.stage = "writing";
247
+ if (s.delivered?.local) {
248
+ // the local runner died with the server. Not yet writing: the batch waits for an agent, as if handed back. Writing: the lease
249
+ // expires at the first tick, which records what was written (it needs the snapshots, which open() sets after this)
250
+ if (s.delivered.stage === "delivered") this.#unDeliver(s);
251
+ else s.delivered.lease.expiresAt = 0;
252
+ try {
253
+ this.#writeLease(s);
254
+ } catch {} // the lease file is a mirror: a failure must not lose the session
255
+ }
256
+ for (const a of s.activity || []) {
257
+ if (a.checks?.deep?.soffice !== "pending") continue;
258
+ const deep = { ...a.checks.deep };
259
+ delete deep.soffice;
260
+ deep.skipped = [...(deep.skipped || []), { check: "soffice-convert", reason: "the server stopped before the check finished" }];
261
+ a.checks = { ...a.checks, deep, notice: deepNotice(deep.skipped) };
262
+ }
263
+ return s;
264
+ } catch {
265
+ return null;
266
+ }
267
+ }
268
+
269
+ #save(s) {
270
+ const { pollers, snapshots, ...rest } = s;
271
+ writeStateFile(path.join(sub("sessions"), `${s.key}.json`), JSON.stringify(rest));
272
+ }
273
+
274
+ get(key) {
275
+ const s = this.map.get(key);
276
+ if (!s) throw new HttpError(404, "no such session");
277
+ return s;
278
+ }
279
+ byFile(input) {
280
+ let real;
281
+ try {
282
+ real = fs.realpathSync(path.resolve(input));
283
+ } catch {
284
+ throw new HttpError(404, `File not found: ${input}`);
285
+ }
286
+ return this.get(sessionKey(real));
287
+ }
288
+
289
+ // ---- derived state ---------------------------------------------------------------------------------------
290
+ state(s) {
291
+ if (s.closed) return "closed";
292
+ if (s.delivered) return s.queued ? "queued" : "working";
293
+ if (s.pending) return "stranded";
294
+ return s.pollers.length ? "listening" : "idle";
295
+ }
296
+
297
+ view(s) {
298
+ const state = this.state(s);
299
+ const lease = s.delivered ? s.delivered.lease : null;
300
+ return {
301
+ key: s.key,
302
+ name: path.basename(s.file),
303
+ format: s.format,
304
+ state,
305
+ locked: !!s.delivered,
306
+ local: !!s.delivered?.local, // the batch in flight is a run on this Mac (src/local.js), no agent: the page words the wait for it
307
+ baseSha: s.baseSha,
308
+ comments: s.comments,
309
+ note: s.note,
310
+ edits: s.edits.length,
311
+ activity: s.activity,
312
+ view: s.view,
313
+ pollers: s.pollers.length,
314
+ pendingBatchId: s.pending?.batch_id || null,
315
+ deliveredBatchId: s.delivered?.batch.batch_id || null,
316
+ leaseExpiresAt: lease?.expiresAt || null,
317
+ // where the delivered batch is: "delivered" (an agent has it) | "writing" (apply/commit arrived) | "checking" (done is running its checks) | null (no batch delivered)
318
+ stage: s.delivered?.local && s.delivered.stage === "delivered" ? "local" : (s.delivered?.stage ?? null),
319
+ // "voice" while the batch in flight (waiting or delivered) asks for a draft of the voice guide: the page words the wait for it
320
+ runKind: readOnlyKind(s.delivered?.batch ?? s.pending) === "voice" ? "voice" : null,
321
+ strandedCommand: state === "stranded" ? `${PRODUCT.bin} poll ${shellQuote(s.file)}` : null,
322
+ startCommand: state === "stranded" ? `${PRODUCT.bin} ${shellQuote(s.file)}` : null, // what a person types in a terminal to start an agent on this file
323
+ seq: s.seq,
324
+ editor: this.editors.get(s.key) || null,
325
+ conflict: s.conflict || null,
326
+ canReveal: canReveal(),
327
+ // the agent's review cards (src/review.js); their ops stay on the server
328
+ suggestions: (s.suggestions || []).map(({ op, acceptedBatch, ...c }) => c),
329
+ // the background agent (src/agent-runner.js): {state, cli, show, activity, failure}; never a path, a holder id or agent text
330
+ agent: this.agent ? this.agent.viewFor(s.key) : { state: "none", cli: null, show: false, activity: [], failure: null },
331
+ };
332
+ }
333
+
334
+ #changed(s, event = "state") {
335
+ s.seq++;
336
+ this.#save(s);
337
+ this.emit("change", s, event);
338
+ }
339
+
340
+ // ---- drafts ----------------------------------------------------------------------------------------------
341
+ /** Browser replaces its list of comments/pins and the overall note. Server-owned fields (status, results) are kept. */
342
+ setDraft(key, { comments, note }) {
343
+ const s = this.get(key);
344
+ if (!Array.isArray(comments)) throw new HttpError(400, "comments must be an array");
345
+ const prev = new Map(s.comments.map((c) => [c.id, c]));
346
+ s.comments = comments.slice(0, 500).map((c) => {
347
+ const old = prev.get(String(c.id));
348
+ const base = {
349
+ id: String(c.id).slice(0, 64),
350
+ kind: ["text", "element", "pin"].includes(c.kind) ? c.kind : "element",
351
+ text: userText(c.text),
352
+ anchor: c.anchor && typeof c.anchor === "object" ? c.anchor : null,
353
+ pin: c.pin && typeof c.pin === "object" ? cleanPin(c.pin) : null,
354
+ pinNo: Number.isInteger(c.pinNo) ? c.pinNo : null,
355
+ };
356
+ if (old && old.status !== "draft") return { ...old, text: old.text, kind: old.kind }; // sent/done comments are frozen
357
+ // an answered question: the words, the question and the answer stay as the person left them (the page cannot change them)
358
+ const keep = old?.skipLocal ? { skipLocal: true } : {}; // a reverted local run: the next Send of this comment goes to the agent
359
+ if (old?.localHint && userText(c.text) === old.text) keep.localHint = old.localHint; // the words changed: the hint no longer applies
360
+ if (old?.answer) return { ...base, text: old.text, status: "draft", durable: old.durable || null, question: old.question, answer: old.answer, ...keep };
361
+ return { ...base, status: "draft", durable: old?.durable || null, ...keep };
362
+ });
363
+ s.note = userText(typeof note === "string" ? note : "");
364
+ this.#changed(s, "draft");
365
+ return s;
366
+ }
367
+
368
+ // ---- send ------------------------------------------------------------------------------------------------
369
+ /**
370
+ * payload: { baseSha, bytes?: Buffer, comments, note, edits: [{kind,before,after,label,location}], viewState }
371
+ * Compare-and-swap on the disk hash. Returns the session.
372
+ */
373
+ send(key, payload) {
374
+ const s = this.get(key);
375
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
376
+ const hasBytes = !!payload.bytes?.length;
377
+ if (s.delivered && hasBytes) throw new HttpError(423, s.delivered.local ? "the document is locked while a change is made on this Mac" : "the document is locked while the agent works", { code: "locked" }); // before touching any state
378
+ this.setDraft(key, { comments: payload.comments ?? s.comments, note: payload.note ?? s.note });
379
+ if (s.delivered) {
380
+ // queue: comments and note only. A new comment gets its durable anchor from the bytes the page shows (the pre-agent snapshot),
381
+ // never from the disk, which the agent may already have changed; done() then moves it onto the post-agent file.
382
+ const fresh = s.comments.filter((c) => c.status === "draft");
383
+ if (fresh.some((c) => !c.durable)) {
384
+ let units = null;
385
+ try {
386
+ units = readUnits(s.format, s.snapshots.read(s.delivered.preSha));
387
+ } catch {
388
+ units = null; // no snapshot: done() falls back to building from the post-agent file
389
+ }
390
+ if (units) {
391
+ for (const c of fresh) {
392
+ if (c.durable) continue;
393
+ c.durable = buildDurable(units, c.anchor);
394
+ if (units.format === "pptx" && c.kind === "pin" && c.durable?.shapeId != null) c.durable.pinFallback = buildDurable(units, { location: { slideIndex: c.durable.slideIndex, slideId: c.durable.slideId } });
395
+ }
396
+ }
397
+ }
398
+ for (const c of fresh) c.status = "queued";
399
+ if (s.note) {
400
+ // the note belongs to the queued batch now; the stored note is cleared so the next Send does not repeat it
401
+ s.queuedNote = [s.queuedNote, s.note].filter(Boolean).join("\n\n");
402
+ s.note = "";
403
+ }
404
+ if (fresh.length || s.queuedNote) s.queued = true; // a Send with nothing new queues nothing (no empty batch after this one)
405
+ this.#changed(s);
406
+ this.#voice(s, { sent: fresh });
407
+ return s;
408
+ }
409
+ const { diskSha, written, writtenSha, writeInfo, lastUpdate } = this.#takePage(s, payload);
410
+
411
+ // user edits since the last Send (document-derived text) accumulate until a batch is delivered
412
+ for (const e of Array.isArray(payload.edits) ? payload.edits.slice(0, 2000) : []) s.edits.push({ kind: e.kind, before: e.before, after: e.after, label: e.label, location: e.location });
413
+
414
+ const units = readUnits(s.format, written);
415
+ const resolve = (anchor) => buildDurable(units, anchor);
416
+ const eligible = s.comments.filter((c) => c.status === "draft" || c.status === "sent");
417
+ for (const c of eligible) {
418
+ c.durable = resolve(c.anchor);
419
+ // a PPTX pin dropped on a shape also remembers its slide: if the shape is deleted the pin stays on the slide
420
+ if (units.format === "pptx" && c.kind === "pin" && c.durable?.shapeId != null) c.durable.pinFallback = buildDurable(units, { location: { slideIndex: c.durable.slideIndex, slideId: c.durable.slideId } });
421
+ }
422
+ for (const e of s.edits) e.durable = e.durable || resolve({ location: e.location, quote: e.after });
423
+ s.view = this.#resolveView(s, units, payload.viewState);
424
+
425
+ const batch = buildBatch({ file: s.file, format: s.format, baseSha: writtenSha, note: s.note, comments: eligible, edits: s.edits, style: styleNote(), guide: voiceGuide() });
426
+ const sent = eligible.filter((c) => c.status === "draft");
427
+ for (const c of eligible) {
428
+ c.status = "sent";
429
+ c.batchId = batch.batch_id;
430
+ }
431
+ s.note = ""; // the note moved into the batch: it is not asked for again
432
+ // a voice guide request still waiting for an agent is replaced by this Send (as a waiting review is); its pasted texts go with it, so say so
433
+ if (readOnlyKind(s.pending) === "voice") s.activity.unshift({ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "voice", at: this.now(), batchId: s.pending.batch_id, summary: VOICE_REPLACED, results: [], flags: [{ code: "voice_request_replaced", severity: "warn" }], checks: null, changes: null, reverted: false });
434
+ s.pending = batch;
435
+ s.lastWrite = writeInfo;
436
+ // a quick change (src/quick-plan.js): the note and the count the person saw on the button. Held for this Send only; it never enters the batch.
437
+ const qc = payload.quick;
438
+ if (qc && typeof qc === "object" && typeof qc.command === "string" && qc.command.length <= 300 && Number.isInteger(qc.count) && qc.count > 0 && qc.count <= 1e6) s.quickConfirm = { command: qc.command, count: qc.count };
439
+ this.#deliverIfPolled(s);
440
+ delete s.quickConfirm;
441
+ delete s.skipLocalNote; // it held for this Send only (the decision for its batch is made)
442
+ this.#changed(s);
443
+ this.#voice(s, { last: lastUpdate, diskSha, writtenSha, sent });
444
+ if (this.state(s) === "stranded" && !s.pollers.length) this.emit("stranded", s); // nobody took it: the server may start its background agent
445
+ return s;
446
+ }
447
+
448
+ /**
449
+ * The page's bytes become the file, as at Send (and at a quick fix's Use): the disk read, the compare-and-swap against the version
450
+ * the page loaded, the package check, the guarded replace, the "sent" snapshot, the new base and the person's own history update.
451
+ * `check(bytes)` (optional) sees the bytes that are about to be the file, after the package check and before anything is written, and
452
+ * may throw to refuse. Returns {disk, diskSha, written, writtenSha, writeInfo, lastUpdate}.
453
+ */
454
+ #takePage(s, payload, check = null) {
455
+ const hasBytes = !!payload.bytes?.length;
456
+ let disk;
457
+ try {
458
+ checkRegularOwned(s.file);
459
+ disk = readCapped(s.file);
460
+ } catch (err) {
461
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
462
+ }
463
+ const diskSha = sha256(disk);
464
+ if (diskSha !== payload.baseSha) {
465
+ throw this.#outsideChange(s, { side: "user", bytes: payload.bytes, diskSha, baseSha: payload.baseSha });
466
+ }
467
+ let written = disk;
468
+ let writeInfo = null;
469
+ if (hasBytes) {
470
+ if (payload.bytes.length > MAX_BYTES) throw new HttpError(413, "document too large");
471
+ try {
472
+ validatePackage(payload.bytes, s.format);
473
+ } catch (err) {
474
+ throw new HttpError(422, `refusing to write: ${err.message}`, { code: "invalid_package" });
475
+ }
476
+ }
477
+ if (check) check(hasBytes ? payload.bytes : disk);
478
+ if (hasBytes) {
479
+ writeInfo = this.#replace(s, payload.bytes, { expectSha: diskSha, label: "before send", side: "user" });
480
+ written = payload.bytes;
481
+ }
482
+ const writtenSha = sha256(written);
483
+ s.snapshots.add(written, "sent");
484
+ s.baseSha = writtenSha;
485
+ const lastUpdate = s.history?.at(-1); // learning pairs an agent run with the person's edits right after it
486
+ if (hasBytes && writtenSha !== diskSha) addUpdate(s, { kind: "user", before: diskSha, after: writtenSha }, this.now());
487
+ s.histTip = writtenSha;
488
+ return { disk, diskSha, written, writtenSha, writeInfo, lastUpdate };
489
+ }
490
+
491
+ /** Hands what this Send can teach (src/voice-learn.js) to the server's `voice` listener. Last in send(): learning never fails a Send. */
492
+ #voice(s, info) {
493
+ try {
494
+ const job = voiceJob(s, info);
495
+ if (job) this.emit("voice", job);
496
+ } catch {}
497
+ }
498
+
499
+ // ---- merge what the user typed while the agent worked ---------------------------------------------------
500
+ /**
501
+ * The page kept editing while a batch was delivered. `bytes` is the page's document: the version it loaded (`baseSha`) plus the
502
+ * user's edits; `edits` names the kinds of edits the page saw. The disk now holds the agent's version. What only the user changed
503
+ * (DOCX paragraphs, formatting and moves: src/merge.js; XLSX cells: src/merge-xlsx.js; PPTX shape text: src/merge-pptx.js) is carried onto it as ops (same engine, expect, protected and package checks
504
+ * as an agent's apply) and written as the user's own update. Refused while a batch is delivered (423): the page waits and asks
505
+ * again. Returns {merged, unplaced, sha, same, mineSha, copy_name}.
506
+ * Ceiling: the engine runs in the server process (about 0.1 s on a 300-paragraph file); move it to a worker if large files stall polls.
507
+ */
508
+ async mergeUserEdits(key, { baseSha, bytes, edits = [] }) {
509
+ const s = this.get(key);
510
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
511
+ if (s.delivered) throw new HttpError(423, s.delivered.local ? "a change is being made on this Mac" : "the agent is working", { code: "locked" });
512
+ const merger = MERGERS[s.format];
513
+ if (!/^[0-9a-f]{64}$/.test(baseSha)) throw new HttpError(400, "baseSha must be a sha256"); // it names a snapshot file
514
+ if (!bytes?.length) throw new HttpError(400, "no document bytes");
515
+ if (bytes.length > MAX_BYTES) throw new HttpError(413, "document too large");
516
+ try {
517
+ validatePackage(bytes, s.format);
518
+ } catch (err) {
519
+ throw new HttpError(422, `refusing to merge: ${err.message}`, { code: "invalid_package" });
520
+ }
521
+ let disk;
522
+ try {
523
+ checkRegularOwned(s.file);
524
+ disk = readCapped(s.file);
525
+ } catch (err) {
526
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
527
+ }
528
+ const diskSha = sha256(disk);
529
+ if (diskSha === baseSha) return { same: true, merged: 0, unplaced: [], sha: diskSha, mineSha: null }; // the file did not change under the page
530
+ if (diskSha !== s.baseSha) throw this.#outsideChange(s, { side: "user", bytes, diskSha, baseSha });
531
+ let base;
532
+ try {
533
+ base = s.snapshots.read(baseSha);
534
+ } catch {
535
+ throw new HttpError(409, "the version this page started from is no longer stored", { code: "no_base" });
536
+ }
537
+ const [mod, { runOps }] = await Promise.all([import(merger.module), import("./ops/run.js")]);
538
+ const r = await mod[merger.fn]({ base, mine: bytes, theirs: disk, name: path.basename(s.file), runOps, edits: editKinds(edits), agent: s.format === "xlsx" ? this.#writesBetween(s, baseSha, diskSha, disk) : null });
539
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
540
+ if (s.delivered) throw new HttpError(423, s.delivered.local ? "a change is being made on this Mac" : "the agent is working", { code: "locked" }); // a batch was delivered while the engine ran
541
+ // The page shows the first HELD_SHOWN items and drops its own version when it reloads. When the list stands for more than it
542
+ // shows, the user's whole file is saved next to the original first. No copy, no merge: the edits stay in the page.
543
+ let copy = null;
544
+ if (r.copy || r.unplaced.length > HELD_SHOWN) {
545
+ try {
546
+ copy = writeSiblingCopy(s.file, bytes);
547
+ this.createdCopies.add(copy.path);
548
+ } catch (err) {
549
+ throw new HttpError(409, `a copy of your version could not be saved: ${err.code || err.message}`, { code: "copy_failed" });
550
+ }
551
+ }
552
+ s.snapshots.add(bytes, "mine"); // a second pass (the user typed during this one) starts from this version
553
+ let sha = diskSha;
554
+ if (r.bytes) {
555
+ this.#replace(s, r.bytes, { expectSha: diskSha, label: "before merge", side: "user" });
556
+ sha = sha256(r.bytes);
557
+ s.snapshots.add(r.bytes, "merged");
558
+ s.baseSha = sha;
559
+ addUpdate(s, { kind: "user", before: diskSha, after: sha }, this.now());
560
+ s.histTip = sha;
561
+ this.#changed(s);
562
+ }
563
+ // the second pass compares this version of the page with the result: the sheets kept their addresses where this pass merged by address
564
+ if (Array.isArray(r.stable)) this.#logWrite(s, { from: sha256(bytes), to: sha, route: "merge", stable: r.stable });
565
+ return { same: false, merged: r.merged, unplaced: r.unplaced.slice(0, 50), sha, mineSha: sha256(bytes), copy_name: copy?.name ?? null };
566
+ }
567
+
568
+ #logWrite(s, entry) {
569
+ const list = this.writes.get(s.key) || [];
570
+ list.push(entry);
571
+ if (list.length > WRITES_KEPT) list.shift();
572
+ this.writes.set(s.key, list);
573
+ }
574
+
575
+ /**
576
+ * The recorded writes that lead from version `from` to version `to` (the file on disk, `disk`), oldest first, with the bytes an
577
+ * apply write started from and produced; null when no chain of records connects them (a revert, a direct save, a restart, a pruned
578
+ * snapshot). Hashes name content, so a chain found is what happened to the bytes, whatever the order of the runs.
579
+ */
580
+ #writesBetween(s, from, to, disk) {
581
+ const list = this.writes.get(s.key) || [];
582
+ const seen = new Set();
583
+ const walk = (sha) => {
584
+ if (sha === from) return [];
585
+ if (seen.has(sha)) return null;
586
+ seen.add(sha);
587
+ for (let i = list.length - 1; i >= 0; i--) {
588
+ if (list[i].to !== sha) continue;
589
+ const before = walk(list[i].from);
590
+ if (before) return [...before, list[i]];
591
+ }
592
+ return null;
593
+ };
594
+ const chain = walk(to);
595
+ if (!chain) return null;
596
+ try {
597
+ return chain.map((e) => (e.route === "apply" ? { ...e, from: s.snapshots.read(e.from), to: e.to === to ? disk : s.snapshots.read(e.to) } : e));
598
+ } catch {
599
+ return null;
600
+ }
601
+ }
602
+
603
+ /**
604
+ * The one write path of the session (Send, agent write, commit, revert): the advisory lock and the compare-and-swap cover the whole
605
+ * replacement (see replaceGuarded). `expectSha` is the hash the caller compared against; a file that is different now, or becomes
606
+ * different just before the rename, is not overwritten (the newer bytes are snapshotted) and the caller gets the 409 conflict.
607
+ */
608
+ #replace(s, bytes, { expectSha, label, side = null }) {
609
+ try {
610
+ return replaceGuarded(s.file, bytes, {
611
+ expectSha,
612
+ snapshotBefore: (disk) => s.snapshots.add(disk, label),
613
+ snapshotNewer: (newer) => s.snapshots.add(newer, "newer version found while writing"),
614
+ });
615
+ } catch (err) {
616
+ if (err instanceof WriteConflict) throw this.#outsideChange(s, { side, bytes, diskSha: err.diskSha, baseSha: err.baseSha, message: err.message });
617
+ if (err.code === "ENOSPC_SNAP") throw new HttpError(507, err.message);
618
+ if (err.code === "LOCK_BUSY") throw new HttpError(409, err.message, { code: "write_busy" });
619
+ if (err.code === "ACL_NOT_PRESERVED") throw new HttpError(409, err.message, { code: "acl_not_preserved" });
620
+ if (err.code === "SYMLINK") throw new HttpError(409, `write failed: ${err.message}`, { code: "symlink" });
621
+ throw new HttpError(500, `write failed: ${err.message}`, { code: "write_failed" });
622
+ }
623
+ }
624
+
625
+ /**
626
+ * The file on disk is not what the writer compared against: someone else changed it. The original is NOT touched. When `side` says whose
627
+ * bytes these are ("user": the page's current bytes; "agent": the agent's candidate), they are saved as a sibling copy so nothing is lost,
628
+ * and the 409 carries the copy's name and path (built by the server from the session's own file path). An agent-side conflict is also
629
+ * recorded for the page: an activity entry and a banner. Returns the HttpError to throw.
630
+ */
631
+ #outsideChange(s, { side, bytes, diskSha, baseSha, message }) {
632
+ let copy = null;
633
+ let copyError = null;
634
+ if (side && bytes?.length) {
635
+ try {
636
+ copy = writeSiblingCopy(s.file, bytes);
637
+ this.createdCopies.add(copy.path);
638
+ } catch (err) {
639
+ copyError = `the copy could not be saved: ${err.code || err.message}`;
640
+ }
641
+ }
642
+ const extra = { code: "conflict", diskSha, baseSha, side, copy_name: copy?.name ?? null, copy_path: copy?.path ?? null, copy_error: copyError, can_reveal: canReveal() };
643
+ if (side === "agent") {
644
+ const local = !!s.delivered?.local; // a change made on this Mac: no agent was involved
645
+ const what = local ? "The change made on this Mac" : "The agent's write";
646
+ const note = copy ? `Someone changed this file outside Onionskin. ${what} was not applied and your original file was left untouched. A copy with ${local ? "the change" : "the agent's edits"} was saved as ${copy.name} in the same folder.` : `Someone changed this file outside Onionskin. ${what} was not applied and your original file was left untouched.${copyError ? ` ${copyError}.` : ""}`;
647
+ s.conflict = { side: "agent", ...(local ? { local: true } : {}), copyName: copy?.name ?? null, copyPath: copy?.path ?? null, copyError, at: this.now() };
648
+ if (s.delivered) s.delivered.outsideChange = { copyName: copy?.name ?? null };
649
+ s.activity.unshift({ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "outside_change", at: this.now(), summary: userText(note, 600), flags: [{ code: "outside_change", severity: "warn" }], results: [] });
650
+ this.#changed(s);
651
+ }
652
+ return new HttpError(409, message || "the file changed on disk since it was loaded", extra);
653
+ }
654
+
655
+ /** Reveal a conflict copy in the Finder. Only a path this server itself wrote is accepted; `open -R` gets it as an argument (no shell). */
656
+ showCopy(p) {
657
+ if (!this.createdCopies.has(String(p)) || !fs.existsSync(p)) throw new HttpError(404, "no such copy");
658
+ const stub = env("OPEN_STUB"); // tests: record the path instead of launching Finder
659
+ if (stub) {
660
+ fs.appendFileSync(stub, `${p}\n`);
661
+ return { ok: true, opened: true };
662
+ }
663
+ if (!canReveal()) return { ok: true, opened: false };
664
+ execFile("/usr/bin/open", ["-R", p], () => {});
665
+ return { ok: true, opened: true };
666
+ }
667
+
668
+ dismissConflict(key) {
669
+ const s = this.get(key);
670
+ s.conflict = null;
671
+ this.#changed(s);
672
+ return s;
673
+ }
674
+
675
+ /** The cheap early check: does the disk still hold the version the page loaded? (Not asked while a batch is delivered: the agent changes the disk then.) */
676
+ staleCheck(key, loadedSha) {
677
+ const s = this.get(key);
678
+ const diskSha = sha256(readCapped(s.file));
679
+ return { stale: !s.delivered && !!loadedSha && diskSha !== loadedSha, diskSha };
680
+ }
681
+
682
+ #resolveView(s, units, vs) {
683
+ if (!vs) return null;
684
+ if (units.format === "docx" && vs.format !== "docx") return { format: s.format, raw: vs };
685
+ if (units.format !== "docx") return viewDurable(units, vs) || { format: s.format, raw: vs };
686
+ const d = durableFromEngine(units.paragraphs, { blockPath: vs.blockPath }, { quote: vs.quote });
687
+ return { format: "docx", durable: d, offsetPx: Number(vs.offsetPx) || 0, zoom: vs.zoom ?? "fit", fraction: vs.fraction };
688
+ }
689
+
690
+ // ---- poll / delivery -------------------------------------------------------------------------------------
691
+ /**
692
+ * Registers a poller. Returns a handle {promise, cancel}. Resolves with the batch object, or {status:'superseded'|'closed'}.
693
+ * ack=true acknowledges a finished run and renews the lease of a run in progress. compact=true (only `reply --then-poll` asks) lets a holder that was briefed already get the short form (see compactBatch);
694
+ * every other poll, including a new agent conversation on the same file that shares the saved holder, gets the complete batch. full=true overrides compact.
695
+ */
696
+ poll(key, { ack = false, holder = "agent", full = false, compact = false } = {}) {
697
+ const s = this.get(key);
698
+ if (holder === LOCAL_HOLDER) throw new HttpError(400, "this holder id is reserved for Onionskin itself; poll with another one", { code: "reserved_holder" });
699
+ // the background agent's holder is bound to its own file, and it never takes a file from an agent that polls it (that agent supersedes it instead)
700
+ if (isBgHolder(holder) && holder !== bgHolder(key)) throw new HttpError(400, "this holder id is reserved for Onionskin itself; poll with another one", { code: "reserved_holder" });
701
+ if (typeof holder === "string" && holder.startsWith(TERM_PREFIX) && holder !== termHolder(key)) throw new HttpError(400, "this holder id is reserved for Onionskin itself; poll with another one", { code: "reserved_holder" });
702
+ if (isBgHolder(holder) && (s.pollers.some((p) => p.holder !== holder) || (s.delivered && !s.delivered.local && s.delivered.lease.holder !== holder))) {
703
+ this.emit("superseded", s, holder);
704
+ return { promise: Promise.resolve({ status: "superseded", next_step: "Another poller took over this file." }), cancel: () => {} };
705
+ }
706
+ // a background poll with no agent process behind it (the agent ended, its poll child lived on): answered closed, so no Send goes to nobody
707
+ if (isBgHolder(holder) && this.agent?.alive && !this.agent.alive(key)) return { promise: Promise.resolve({ status: "closed", reason: "the agent was stopped" }), cancel: () => {} };
708
+ if (ack && s.delivered && s.delivered.lease.holder === holder) this.#renew(s);
709
+ let resolveFn;
710
+ const promise = new Promise((r) => (resolveFn = r));
711
+ for (const old of s.pollers.splice(0)) {
712
+ old.resolve({ status: "superseded", next_step: "Another poller took over this file." });
713
+ if (isBgHolder(old.holder) && old.holder !== holder) this.emit("superseded", s, old.holder);
714
+ }
715
+ const p = { holder, full, compact, resolve: resolveFn };
716
+ s.pollers.push(p);
717
+ if (s.closed) {
718
+ s.pollers = s.pollers.filter((x) => x !== p);
719
+ resolveFn({ status: "closed" });
720
+ } else {
721
+ this.#deliverIfPolled(s);
722
+ }
723
+ this.#changed(s);
724
+ return {
725
+ promise,
726
+ cancel: () => {
727
+ const before = s.pollers.length;
728
+ s.pollers = s.pollers.filter((x) => x !== p);
729
+ if (s.pollers.length !== before) this.#changed(s);
730
+ },
731
+ };
732
+ }
733
+
734
+ #deliverIfPolled(s) {
735
+ if (!s.pending || s.delivered) return;
736
+ if (this.#deliverLocal(s)) return;
737
+ if (!s.pollers.length) return;
738
+ const p = s.pollers.shift();
739
+ const batch = s.pending;
740
+ this.#deliverTo(s, batch, p.holder);
741
+ s.pending = null;
742
+ s.queued = false;
743
+ this.#writeLease(s);
744
+ this.#styleSeen.set(s.delivered, styleChangedOutside());
745
+ this.#guideSeen.set(s.delivered, guideChangedOutside());
746
+ // the poller gets a copy that carries this delivery's lease; the stored batch stays free of it
747
+ // the commands in it carry this delivery's ticket (`--lease`), so an agent that runs them as printed names its own delivery
748
+ const ticket = ticketOf(batch.batch_id, s.delivered.lease.token);
749
+ const lease = { holder: p.holder, token: s.delivered.lease.token };
750
+ const shown = this.#withOutline(s, batch, p.holder);
751
+ const briefed = this.briefed.get(s.key) || this.briefed.set(s.key, new Set()).get(s.key);
752
+ if (briefed.has(p.holder) && p.compact && !p.full) {
753
+ p.resolve(compactBatch(shown, { file: s.file, ticket, lease }));
754
+ return;
755
+ }
756
+ briefed.add(p.holder);
757
+ p.resolve({
758
+ ...shown,
759
+ // a voice batch writes nothing, so it has no how_to_apply
760
+ ...(batch.how_to_apply ? { how_to_apply: { ...batch.how_to_apply, command: batch.how_to_apply.command.replace(/( --ops \S+)/, `$1 --lease ${ticket}`), rules: batch.how_to_apply.rules.map((r) => r.replaceAll("<ticket>", ticket)) } } : {}),
761
+ next_step: batch.next_step.replace(/( --results \S+)$/, `$1 --lease ${ticket}`).replaceAll("<ticket>", ticket),
762
+ lease,
763
+ lease_ticket: ticket,
764
+ });
765
+ }
766
+
767
+ /**
768
+ * An agent Onionskin started (its background holder or the Terminal form) cannot open the file, so each edit batch it receives, complete or
769
+ * compact, also carries the outline of the file as it is now (the bytes its ops are checked against), with the target and expect of every
770
+ * unit. As much as fits one shell output is inline; when that is not all of it, the complete outline (up to OUTLINE_FILE_MAX units) is
771
+ * written to <state>/agents/<key>/outline/outline-<batch id>.jsonl (0600, atomic, one unit per line), the only folder that agent may read,
772
+ * and the batch names it. Older outline files of the session go at each such delivery, and with the folder on Close.
773
+ * Any other holder, a review (it has `units`) and a voice request (it quotes only the sources the person ticked) get the batch as stored.
774
+ * A file that cannot be read gets no outline (the agent declines what it cannot find); an outline file that cannot be written leaves the
775
+ * inline part with `outline_more`. Ceiling: read and parsed on the main thread at each such delivery, as a review is; upgrade path as in unitsOf.
776
+ */
777
+ #withOutline(s, batch, holder) {
778
+ if (!isAgentHolder(holder) || batch.instructions?.review || batch.instructions?.voice_request) return batch;
779
+ let all;
780
+ try {
781
+ checkRegularOwned(s.file);
782
+ all = outlineOf(s.format, readCapped(s.file), OUTLINE_FILE_MAX);
783
+ } catch {
784
+ return batch;
785
+ }
786
+ const inline = withOutline(batch, all, VOICE_BATCH_MAX_CHARS, { inlineMax: UNITS_MAX });
787
+ const name = `outline-${batch.batch_id}.jsonl`;
788
+ let dir = null;
789
+ try {
790
+ dir = fs.realpathSync(sub("agents", s.key, "outline")); // a real path: --restricted compares paths literally
791
+ for (const n of fs.readdirSync(dir)) if (/^outline-.*\.jsonl$/.test(n) && n !== name) fs.rmSync(path.join(dir, n), { force: true });
792
+ } catch {}
793
+ if (!inline.untrusted_document_evidence.outline_more || !dir) return inline;
794
+ const file = path.join(dir, name);
795
+ try {
796
+ writeStateFile(file, all.outline.map((u) => JSON.stringify(u)).join("\n") + "\n");
797
+ } catch {
798
+ return inline;
799
+ }
800
+ return withOutline(batch, all, VOICE_BATCH_MAX_CHARS, { inlineMax: UNITS_MAX, file: { path: file, units: all.outline.length } });
801
+ }
802
+
803
+ /**
804
+ * The local runner (src/local.js) is asked once per batch id whether it does this whole batch on this Mac. Yes: the batch is delivered to
805
+ * LOCAL_HOLDER with a fresh token, like an agent's delivery, and no poller is taken. The `local` event carries the ticket; the runner uses
806
+ * only that. A batch that comes back (hand-back, lease expiry, restart) is never asked again, so it goes to the agent.
807
+ */
808
+ #deliverLocal(s) {
809
+ const batch = s.pending;
810
+ if (!this.local || s.decidedBatch === batch.batch_id) return false;
811
+ s.decidedBatch = batch.batch_id;
812
+ let yes = false;
813
+ try {
814
+ yes = this.local.wants(s, batch) === true;
815
+ } catch {
816
+ yes = false; // a predicate that throws means no
817
+ }
818
+ if (!yes) return false;
819
+ this.#deliverTo(s, batch, LOCAL_HOLDER, { local: true, ...(s.quickConfirm ? { quick: s.quickConfirm } : {}) });
820
+ s.pending = null;
821
+ s.queued = false;
822
+ this.#writeLease(s);
823
+ this.emit("local", s, { batchId: batch.batch_id, token: s.delivered.lease.token });
824
+ return true;
825
+ }
826
+
827
+ #deliverTo(s, batch, holder, extra = {}) {
828
+ s.delivered = { batch, stage: "delivered", preSha: s.baseSha, knownSha: s.baseSha, deliveredAt: this.now(), edits: s.edits, lease: { holder, token: crypto.randomBytes(8).toString("hex"), expiresAt: this.now() + LEASE_MS() }, ...extra };
829
+ s.edits = [];
830
+ }
831
+
832
+ /** A delivery that wrote nothing goes back: the batch is pending again (decided: the next delivery is an agent's), the typed edits are evidence again, queued comments are drafts again (as at lease expiry). */
833
+ #unDeliver(s) {
834
+ const d = s.delivered;
835
+ if (!d.accept) s.pending = d.batch; // an accepted suggestion has nothing to ask an agent
836
+ this.#backToDraft(s, d, true);
837
+ s.decidedBatch = d.batch.batch_id;
838
+ s.edits = [...d.edits, ...s.edits];
839
+ s.delivered = null;
840
+ this.#queuedToDrafts(s);
841
+ }
842
+
843
+ #queuedToDrafts(s) {
844
+ if (s.queued) {
845
+ for (const c of s.comments) if (c.status === "queued") c.status = "draft";
846
+ s.note = [s.queuedNote, s.note].filter(Boolean).join("\n\n");
847
+ s.queuedNote = "";
848
+ }
849
+ s.queued = false;
850
+ }
851
+
852
+ /**
853
+ * The local runner could not finish and nothing was written: the batch goes to the agent exactly as it would have (same batch, a new
854
+ * lease when a poller takes it). Strict lease; refused (409 `written`) once the delivery wrote anything, which then finishes like a run.
855
+ */
856
+ handBack(key, claim) {
857
+ const s = this.get(key);
858
+ if (!s.delivered) throw new HttpError(409, "no batch is in progress for this file", { code: "no_batch" });
859
+ this.#assertLease(s, { ...claim, strict: true });
860
+ if (!s.delivered.local) throw new HttpError(409, "only a run on this Mac is handed back", { code: "not_local" });
861
+ if ((s.delivered.knownSha ?? s.delivered.preSha) !== s.delivered.preSha) throw new HttpError(409, "the file was already written for this batch", { code: "written" });
862
+ this.#unDeliver(s);
863
+ this.#writeLease(s);
864
+ this.#deliverIfPolled(s);
865
+ this.#changed(s);
866
+ return s;
867
+ }
868
+
869
+ /**
870
+ * A batch made by Onionskin itself (idea 21's Accept: no instructions, the stored ops) run on this Mac with an agent's powers. Refused
871
+ * while anything is delivered or waiting, so it never takes a Send's place. `job` stays in memory with the delivery and goes to the runner
872
+ * with the `local` event. Returns the ticket.
873
+ */
874
+ startLocal(key, batch, job = null) {
875
+ const s = this.get(key);
876
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
877
+ if (s.delivered || s.pending) throw new HttpError(409, "a batch is already waiting or in progress for this file", { code: "busy" });
878
+ if (!batch?.batch_id || batch.base_sha256 !== s.baseSha) throw new HttpError(409, "the batch is not for the current version of the file", { code: "stale_batch" });
879
+ this.#deliverTo(s, batch, LOCAL_HOLDER, { local: true, accept: true, ...(job?.model === true ? { model: true } : {}) }); // model: the words come from the local writing model
880
+ s.decidedBatch = batch.batch_id;
881
+ this.#writeLease(s);
882
+ this.#changed(s);
883
+ const ticket = { batchId: batch.batch_id, token: s.delivered.lease.token, job };
884
+ this.emit("local", s, ticket);
885
+ return ticket;
886
+ }
887
+
888
+ /** A startLocal delivery that wrote nothing ends with no trace: nothing goes to an agent (there is nothing to ask it). Strict lease, like handBack. */
889
+ dropLocal(key, claim) {
890
+ const s = this.get(key);
891
+ if (!s.delivered) throw new HttpError(409, "no batch is in progress for this file", { code: "no_batch" });
892
+ this.#assertLease(s, { ...claim, strict: true });
893
+ if (!s.delivered.accept) throw new HttpError(409, "only an accepted suggestion is dropped", { code: "not_local" });
894
+ if ((s.delivered.knownSha ?? s.delivered.preSha) !== s.delivered.preSha) throw new HttpError(409, "the file was already written for this batch", { code: "written" });
895
+ this.#settleCards(s, s.delivered, []); // nothing applied: the text there changed
896
+ this.#backToDraft(s, s.delivered, true);
897
+ s.edits = [...s.delivered.edits, ...s.edits];
898
+ s.delivered = null;
899
+ this.#writeLease(s);
900
+ this.#deliverIfPolled(s);
901
+ this.#changed(s);
902
+ return s;
903
+ }
904
+
905
+ /**
906
+ * An accepted run that ends without `done` (dropLocal, a restart, a lease expiry): the comment of a quick fix it carried is a draft
907
+ * again, so the person can send it to the agent. `hint`: nothing was written, and the comment says so.
908
+ */
909
+ #backToDraft(s, d, hint) {
910
+ if (!d?.accept) return;
911
+ for (const c of s.comments) {
912
+ if (c.batchId !== d.batch.batch_id || c.status !== "sent") continue;
913
+ c.status = "draft";
914
+ delete c.batchId;
915
+ if (hint) c.localHint = LOCAL_HINT;
916
+ }
917
+ }
918
+
919
+ #writeLease(s) {
920
+ const f = path.join(sub("leases"), `${s.key}.json`);
921
+ if (!s.delivered) {
922
+ try {
923
+ fs.unlinkSync(f);
924
+ } catch {}
925
+ clearTickets(s.key);
926
+ return;
927
+ }
928
+ // a local delivery's token lives in the server's memory only: no `status --ticket` can hand it to an agent
929
+ if (!s.delivered.local) saveTicket(s.key, { batchId: s.delivered.batch.batch_id, holder: s.delivered.lease.holder, token: s.delivered.lease.token });
930
+ writeStateFile(f, JSON.stringify({ holder: s.delivered.lease.holder, expiresAt: s.delivered.lease.expiresAt, baseSha256: s.delivered.preSha }));
931
+ }
932
+
933
+ #renew(s) {
934
+ s.delivered.lease.expiresAt = this.now() + LEASE_MS();
935
+ this.#writeLease(s);
936
+ this.#changed(s);
937
+ }
938
+
939
+ /** Called on a timer: a delivered batch whose lease expired goes back to pending (stranded) and the document unlocks. */
940
+ tick() {
941
+ for (const s of this.map.values()) if (s.delivered && s.delivered.lease.expiresAt <= this.now()) this.#expire(s);
942
+ }
943
+
944
+ /**
945
+ * The background agent stopped while it held this batch (a crash, a refusal): end the delivery now instead of at lease expiry, with the
946
+ * same steps as an expiry. A run that wrote is recorded with Revert; one that did not is pending again. Only the delivery's own holder.
947
+ */
948
+ releaseAgent(key, holder) {
949
+ const s = this.get(key);
950
+ if (!s.delivered) throw new HttpError(409, "no batch is in progress for this file", { code: "no_batch" });
951
+ if (!isBgHolder(holder) || s.delivered.local || s.delivered.lease.holder !== holder) throw new HttpError(403, "another agent holds the lease for this batch", { code: "not_lease_holder" });
952
+ this.#expire(s);
953
+ return s;
954
+ }
955
+
956
+ #expire(s) {
957
+ const local = !!s.delivered.local; // a run on this Mac: no agent in it
958
+ const wrote = this.#recordMidRun(s, local ? "The change on this Mac stopped after it changed the file." : "The agent stopped responding after changing the file.", "lease_expired_mid_run");
959
+ if (!s.delivered.accept) s.pending = s.delivered.batch; // a local run's batch was decided at its delivery: it goes to the agent now
960
+ this.#backToDraft(s, s.delivered, !wrote);
961
+ s.edits = [...s.delivered.edits, ...s.edits];
962
+ const accepted = !!s.delivered.accept;
963
+ s.delivered = null;
964
+ // comments queued behind the expired run have no batch to ride in: they go back to drafts (with their note) instead of waiting for a done that cannot come
965
+ this.#queuedToDrafts(s);
966
+ s.activity.unshift({ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "lease_expired", at: this.now(), summary: local ? (accepted ? (wrote ? "The change on this Mac stopped after it changed the file. Revert restores the earlier version." : "The change on this Mac did not finish. Nothing was written.") : "The change on this Mac did not finish. Your request is waiting for an agent.") : "The agent stopped responding. The batch is waiting for the next poll.", flags: [], results: [], ...(local ? { by: "local" } : {}) });
967
+ this.#writeLease(s);
968
+ this.#changed(s, wrote ? "reload" : "state");
969
+ }
970
+
971
+ // ---- agent write -----------------------------------------------------------------------------------------
972
+ /** Moves the delivered batch to `stage` (see view().stage) and tells the page. No-op without a delivery or when it is already there. */
973
+ setStage(key, stage) {
974
+ const s = this.get(key);
975
+ if (!s.delivered || s.delivered.stage === stage) return;
976
+ s.delivered.stage = stage;
977
+ this.#changed(s);
978
+ }
979
+
980
+ /**
981
+ * Who may act on the delivered batch. A stale agent (its lease expired and the batch went to another poll) carries the old delivery's
982
+ * token, so even the same batch id cannot be completed or written by it. Writers (agentWrite, noteApply) always pass `strict`: holder,
983
+ * batch id and token are all required, a missing one is `missing_lease`. `done` is strict at the server route.
984
+ */
985
+ #assertLease(s, { holder, token, batchId, strict = false }, { staleOnHolder = false } = {}) {
986
+ const d = s.delivered;
987
+ if (strict && (!holder || !token || !batchId)) throw new HttpError(400, "holder, batch_id and lease_token are required: they come from the output of `poll`", { code: "missing_lease" });
988
+ const stale = () => new HttpError(409, "this is not your delivery: the batch was taken back, finished or handed to another agent. Run poll again.", { code: "stale_batch" });
989
+ if (batchId != null && batchId !== d.batch.batch_id) throw stale();
990
+ if (holder != null && d.lease.holder !== holder) {
991
+ if (staleOnHolder) throw stale();
992
+ throw new HttpError(403, "another agent holds the lease for this batch", { code: "not_lease_holder" });
993
+ }
994
+ if (token != null && token !== d.lease.token) throw stale();
995
+ }
996
+
997
+ /**
998
+ * `apply` through a live session: the single authority for the write. Accepted only while a batch is delivered (state working or
999
+ * queued: both hold a live lease) and only for the lease holder; compare-and-swap on the disk hash; renews the lease.
1000
+ */
1001
+ agentWrite(key, { baseSha, bytes, holder, token, batchId, label = "before agent write", route = "commit", ops = null, partial = false }) {
1002
+ const s = this.get(key);
1003
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1004
+ const state = this.state(s);
1005
+ if (!s.delivered) throw new HttpError(409, `no batch is delivered to an agent (state: ${state}); run poll and wait for the user's Send`, { code: "not_working", state });
1006
+ this.#assertLease(s, { holder, token, batchId, strict: true });
1007
+ const readOnly = readOnlyKind(s.delivered.batch);
1008
+ if (readOnly) throw new HttpError(409, READ_ONLY[readOnly], { code: `${readOnly}_only` });
1009
+ // `commit` does not know the hash its candidate was edited from: the base is the last hash this server wrote or served for the delivery
1010
+ if (baseSha == null) baseSha = s.delivered.knownSha ?? s.delivered.preSha;
1011
+ if (!bytes?.length) throw new HttpError(400, "no bytes");
1012
+ if (bytes.length > MAX_BYTES) throw new HttpError(413, "document too large");
1013
+ try {
1014
+ validatePackage(bytes, s.format);
1015
+ } catch (err) {
1016
+ throw new HttpError(422, `refusing to write: ${err.message}`, { code: "invalid_package" });
1017
+ }
1018
+ let disk;
1019
+ try {
1020
+ checkRegularOwned(s.file);
1021
+ disk = readCapped(s.file);
1022
+ } catch (err) {
1023
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
1024
+ }
1025
+ const diskSha = sha256(disk);
1026
+ if (diskSha !== baseSha) throw this.#outsideChange(s, { side: "agent", bytes, diskSha, baseSha, message: "the file changed on disk since apply read it" });
1027
+ this.setStage(key, "writing"); // only once the checks passed: a refused write does not claim to be writing
1028
+ const info = this.#replace(s, bytes, { expectSha: diskSha, label, side: "agent" });
1029
+ const newSha = sha256(bytes);
1030
+ // what the merge may rely on later: the ops `apply` says it ran (checked against the bytes when a merge needs them), or that it was a commit
1031
+ const checked = route === "apply" && s.format === "xlsx" && Array.isArray(ops) && validateOps({ schema: "onionskin.ops/1", ops }).ok; // only the XLSX merge reads them
1032
+ this.#logWrite(s, checked ? { from: diskSha, to: newSha, route, ops, partial: partial === true, anchors: s.delivered.batch.untrusted_document_evidence?.anchors || [] } : { from: diskSha, to: newSha, route: route === "apply" ? "apply" : "commit", ops: null });
1033
+ s.delivered.knownSha = newSha;
1034
+ // the pre-agent version is what Revert restores: keep it the newest entry so many agent writes cannot prune it
1035
+ s.snapshots.touch(s.delivered.preSha);
1036
+ s.lastWrite = info;
1037
+ this.#renew(s);
1038
+ return { ok: true, sha256: newSha, lease_expires_at: s.delivered.lease.expiresAt };
1039
+ }
1040
+
1041
+ /**
1042
+ * What `apply` could not do (refused by the engine, protected, anchor or expectation mismatch), told by the lease holder after each run
1043
+ * (also when nothing was written). Shown to the user with the activity entry at `done`.
1044
+ */
1045
+ noteApply(key, { holder, token, batchId, run = "", problems = [], applied = [] }) {
1046
+ const s = this.get(key);
1047
+ if (!s.delivered) throw new HttpError(409, "no batch is delivered to an agent", { code: "not_working" });
1048
+ this.#assertLease(s, { holder, token, batchId, strict: true });
1049
+ this.setStage(key, "writing");
1050
+ // problems are keyed by op: a later run replaces what an earlier run said about the same op, and an op that now applied clears it
1051
+ const fresh = problems.slice(0, 40).map((p) => cleanProblem(p, run));
1052
+ const settled = new Set([...fresh.map((p) => p.key), ...applied.slice(0, 200).map((k) => untrusted(k, 80))]);
1053
+ s.delivered.applyProblems = [...(s.delivered.applyProblems || []).filter((p) => !settled.has(p.key)), ...fresh].slice(0, 40);
1054
+ this.#changed(s);
1055
+ return { ok: true };
1056
+ }
1057
+
1058
+ // ---- done ------------------------------------------------------------------------------------------------
1059
+ /** The bytes `done` will analyze (null when the pre-agent version is gone), for the server to analyze off the event loop. Asserts the lease first. */
1060
+ analysisInputs(key, claim) {
1061
+ const s = this.get(key);
1062
+ if (!s.delivered) throw new HttpError(409, "no batch is in progress for this file (taken back or already finished)", { code: "no_batch" });
1063
+ this.#assertLease(s, claim, { staleOnHolder: true });
1064
+ this.setStage(key, "checking");
1065
+ let post;
1066
+ let pre;
1067
+ try {
1068
+ post = readCapped(s.file);
1069
+ pre = s.snapshots.read(s.delivered.preSha);
1070
+ } catch {
1071
+ return null; // done() states what it could not read
1072
+ }
1073
+ const readOnly = readOnlyKind(s.delivered.batch);
1074
+ if (readOnly === "voice") return null; // a voice run writes nothing; a file changed anyway is recorded by done, not analyzed
1075
+ if (readOnly === "review" && sha256(post) === s.delivered.preSha) return null; // a review that wrote nothing: nothing to check
1076
+ // deferSoffice: the LibreOffice conversion runs after `done` returns (startLateSoffice); ONIONSKIN_SOFFICE_SYNC=1 keeps it inline
1077
+ return { pre, post, format: s.format, postSha: sha256(post), batchId: s.delivered.batch.batch_id, deferSoffice: env("SOFFICE_SYNC", "") !== "1" };
1078
+ }
1079
+
1080
+ done(key, results, claim = {}, analysis = null) {
1081
+ const s = this.get(key);
1082
+ if (!s.delivered) throw new HttpError(409, "no batch is in progress for this file (taken back or already finished)", { code: "no_batch" });
1083
+ this.#assertLease(s, claim, { staleOnHolder: true });
1084
+ if (!results || typeof results !== "object") throw new HttpError(400, "results must be an object");
1085
+ const list = Array.isArray(results.results) ? results.results : [];
1086
+ const run = s.delivered;
1087
+ let post;
1088
+ try {
1089
+ post = readCapped(s.file);
1090
+ } catch (err) {
1091
+ throw new HttpError(409, `cannot read the file: ${err.message}`);
1092
+ }
1093
+ const postSha = sha256(post);
1094
+ if (readOnlyKind(run.batch) === "voice") return this.#doneVoice(s, results, run, post, postSha);
1095
+ // a review that wrote nothing ends with cards. One whose file changed anyway (a direct save past review_only) is finished as a run below:
1096
+ // its write is flagged and can be reverted, and no card is kept
1097
+ if (run.batch.instructions?.review && postSha === run.preSha) return this.#doneReview(s, results, run, post);
1098
+ s.snapshots.add(post, "after agent");
1099
+
1100
+ // ---- plan: everything that can throw happens here, on locals; the session is not touched until the commit below ------
1101
+ let pre;
1102
+ try {
1103
+ pre = s.snapshots.read(run.preSha);
1104
+ } catch {
1105
+ pre = null;
1106
+ }
1107
+ // the analysis normally comes from the worker (server route); a call without one, or with one for other bytes, analyzes inline
1108
+ let found;
1109
+ if (!pre) found = { flags: [{ code: "no_pre_snapshot", severity: "warn" }], checks: { node: "skipped", deep: { status: "skipped", reason: "no pre-agent snapshot" }, notice: "Checks skipped: the pre-agent version is no longer stored." }, changes: null };
1110
+ else if (analysis && analysis.postSha === postSha && analysis.batchId === run.batch.batch_id) found = analysis;
1111
+ else found = analyze(pre, post, s.format);
1112
+ const flags = [...found.flags];
1113
+ const { checks, changes } = found;
1114
+ // the file must be what this server last wrote (apply/commit) or delivered; anything else changed it behind the lease (a direct save by
1115
+ // the agent's own library, or another program): the lost-update class the lease cannot see. Error severity, so Revert is recommended.
1116
+ if (postSha !== (run.knownSha ?? run.preSha)) flags.push({ code: "file_changed_outside_onionskin", severity: "error", detail: directSave(run.local) });
1117
+ if (run.outsideChange) flags.push({ code: "outside_change", severity: "warn", detail: run.local ? (run.outsideChange.copyName ? `The file was changed outside Onionskin while the change was made on this Mac; the changed version was saved as a copy: ${run.outsideChange.copyName}` : "The file was changed outside Onionskin while the change was made on this Mac; the change was not applied.") : run.outsideChange.copyName ? `The file was changed outside Onionskin while the agent worked; the agent's version was saved as a copy: ${run.outsideChange.copyName}` : "The file was changed outside Onionskin while the agent worked; the agent's write was not applied." });
1118
+ for (const p of run.applyProblems || []) flags.push({ code: p.status === "skipped_protected" ? "apply_skipped_protected" : "apply_not_applied", severity: p.status === "skipped_protected" ? "info" : "warn", op: p.op, status: p.status, ...(p.code ? { reason_code: p.code } : {}), detail: p.reason });
1119
+ const byId = new Map(s.comments.map((c) => [c.id, c]));
1120
+ const entries = [];
1121
+ const updates = [];
1122
+ const asks = this.#askPlan(s, run);
1123
+ for (const r of list.slice(0, 1000)) {
1124
+ const c = byId.get(String(r.comment_id));
1125
+ if (!c || !["done", "declined", "asked"].includes(r.status) || (r.status === "asked" && !asks.allowed(c))) {
1126
+ flags.push({ code: "unknown_result", severity: "warn", comment_id: String(r.comment_id).slice(0, 64) });
1127
+ continue;
1128
+ }
1129
+ if (r.status === "asked") {
1130
+ const q = asks.take(c, r);
1131
+ if (q.question) {
1132
+ updates.push({ c, status: "asked", result: undefined, question: q.question });
1133
+ entries.push({ comment_id: c.id, status: "asked", note: "" });
1134
+ } else {
1135
+ // the batch is not lost: the comment is declined with a fixed note, never the agent's text
1136
+ flags.push({ code: "bad_question", severity: "warn", comment_id: c.id, reason: q.code });
1137
+ updates.push({ c, status: "declined", result: BAD_QUESTION_NOTE });
1138
+ entries.push({ comment_id: c.id, status: "declined", note: BAD_QUESTION_NOTE });
1139
+ }
1140
+ continue;
1141
+ }
1142
+ const note = userText(r.note ?? "", 1000);
1143
+ updates.push({ c, status: r.status, result: note });
1144
+ entries.push({ comment_id: c.id, status: r.status, note });
1145
+ }
1146
+ for (const c of run.batch.instructions.comments) {
1147
+ if (!entries.some((e) => e.comment_id === c.id)) flags.push({ code: "no_result_for_comment", severity: "warn", comment_id: c.id });
1148
+ }
1149
+ // style.json changed by something else while this batch was out (an agent with a shell, say): already put back by src/style.js
1150
+ this.#guardFlags(run, flags);
1151
+ if (results.voice_draft !== undefined) flags.push({ code: "voice_draft_not_allowed", severity: "warn" }); // only a voice batch takes a draft; nothing is stored
1152
+ const queuedPlan = this.#planQueued(s, post, postSha, flags);
1153
+ const cleanFlags = flags.map(cleanFlag);
1154
+ const { list: ignored, more: ignoredMore } = ignoredInstructions(results.document_instructions_ignored);
1155
+ const entry = {
1156
+ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "agent", at: this.now(), batchId: run.batch.batch_id,
1157
+ summary: userText(typeof results.summary === "string" ? results.summary : "", 400), results: entries,
1158
+ // text in the document that tried to instruct the agent: agent-supplied, so sanitized like other untrusted text (5 items of 200 chars)
1159
+ ...(ignored.length ? { documentInstructionsIgnored: ignored, ...(ignoredMore ? { documentInstructionsIgnoredMore: true } : {}) } : {}), flags: cleanFlags, checks,
1160
+ revertRecommended: cleanFlags.some((f) => f.severity === "error"),
1161
+ changes,
1162
+ preSha: run.preSha, postSha, reverted: false,
1163
+ // a run on this Mac (src/local.js): the page titles it "Done on this Mac"; its note comes back to the box if the person reverts it
1164
+ ...(run.local ? { by: "local", localNote: userText(run.batch.instructions?.overall_note || "") } : {}),
1165
+ };
1166
+
1167
+ // ---- commit: assignments only ------------------------------------------------------------------------------------
1168
+ for (const u of updates) {
1169
+ u.c.status = u.status;
1170
+ u.c.result = u.result;
1171
+ if (u.question) u.c.question = u.question;
1172
+ }
1173
+ if (run.accept) {
1174
+ this.#settleCards(s, run, Array.isArray(results.accepted) ? results.accepted : []);
1175
+ s.edits = [...run.edits, ...s.edits]; // an accepted suggestion carried none of the person's edits: they ride with the next Send
1176
+ }
1177
+ s.activity.unshift(entry);
1178
+ addUpdate(s, { kind: run.local ? "local" : "agent", before: run.preSha, after: postSha, summary: entry.summary, model: run.model === true }, this.now());
1179
+ s.histTip = postSha;
1180
+ s.baseSha = postSha;
1181
+ s.delivered = null;
1182
+ s.conflict = null;
1183
+ if (s.queued) {
1184
+ s.queued = false;
1185
+ if (queuedPlan) {
1186
+ for (const c of queuedPlan.queued) {
1187
+ c.durable = queuedPlan.durables.get(c.id);
1188
+ c.status = "sent";
1189
+ c.batchId = queuedPlan.batch.batch_id;
1190
+ }
1191
+ s.pending = queuedPlan.batch;
1192
+ s.queuedNote = "";
1193
+ }
1194
+ }
1195
+ this.#writeLease(s);
1196
+ this.#deliverIfPolled(s);
1197
+ this.#changed(s, "reload");
1198
+ return { ok: true, flags: cleanFlags, checks };
1199
+ }
1200
+
1201
+ /**
1202
+ * The LibreOffice conversion result for a version `done` already accepted (activity entry checks.deep.soffice === "pending"). Recorded against
1203
+ * the entry of the version it checked. A failure that found something is an error flag (Revert offered like any error flag from done) only
1204
+ * while that run is still the latest and the file is still its version; after a newer write it is a warning on that run and changes nothing.
1205
+ * Never throws; false when the entry or session is gone or the entry was already settled.
1206
+ */
1207
+ recordLateCheck(key, { batchId, postSha, result }) {
1208
+ let s;
1209
+ try {
1210
+ s = this.get(key);
1211
+ } catch {
1212
+ return false;
1213
+ }
1214
+ const entry = s.activity.find((a) => a.kind === "agent" && a.batchId === batchId && a.postSha === postSha && a.checks?.deep?.soffice === "pending");
1215
+ if (!entry) return false;
1216
+ // current: still the latest run and the file is still its version. A next batch handed out meanwhile (comments queued during the run) changes nothing until its agent writes.
1217
+ const d = s.delivered;
1218
+ const current = s.baseSha === postSha && s.activity.find((a) => a.kind === "agent" && !a.reverted) === entry && (!d || (d.preSha === postSha && d.knownSha === postSha));
1219
+ const found = (result.flags || []).map((f) => cleanFlag(current || f.severity !== "error" ? f : { ...f, severity: "warn", detail: `${f.detail || ""} (the file has changed since this run)`.trim() }));
1220
+ const deep = { ...entry.checks.deep };
1221
+ delete deep.soffice;
1222
+ const skipped = [...(deep.skipped || [])];
1223
+ if (result.ran) deep.checks = [...(deep.checks || []), "soffice-convert"];
1224
+ else skipped.push({ check: "soffice-convert", reason: untrusted(result.reason || "did not run", 120) });
1225
+ deep.skipped = skipped;
1226
+ entry.checks = { ...entry.checks, deep, notice: deepNotice(skipped) };
1227
+ entry.flags = [...entry.flags, ...found];
1228
+ if (found.some((f) => f.severity === "error")) entry.revertRecommended = true;
1229
+ this.#changed(s);
1230
+ return true;
1231
+ }
1232
+
1233
+ /**
1234
+ * Who `done` may mark `asked`, and how many. Only a comment of the delivered batch (never an unsent draft), never one that already
1235
+ * carries an answer (one question per comment), and at most QUESTIONS_PER_BATCH per `done` (the rule `reply` can check up front).
1236
+ * Ceiling: questions left open from two runs and answered together put more than three entries in one batch's `questions[]`; counting
1237
+ * open questions here would refuse asks that `reply` accepted. Pure: reads the session, changes nothing.
1238
+ */
1239
+ #askPlan(s, run) {
1240
+ const inBatch = new Map(run.batch.instructions.comments.map((c) => [c.id, c]));
1241
+ let open = 0;
1242
+ return {
1243
+ allowed: (c) => inBatch.has(c.id) && c.batchId === run.batch.batch_id,
1244
+ take: (c, r) => {
1245
+ if (inBatch.get(c.id).answer || c.answer) return { code: "already_asked" };
1246
+ const q = cleanQuestion({ ask: r.ask, options: r.options });
1247
+ if (!q.question) return q;
1248
+ if (open >= QUESTIONS_PER_BATCH) return { code: "too_many_questions" };
1249
+ open++;
1250
+ return q;
1251
+ },
1252
+ };
1253
+ }
1254
+
1255
+ /**
1256
+ * The person tapped an option on a question card. `choice` is the index of the option (checked against the options this server
1257
+ * stored; option text is never taken from the page), or null for "Something else". An index keeps the question and sets the answer;
1258
+ * null drops the question. Either way the comment is a draft again, and the page sends it as usual.
1259
+ */
1260
+ answer(key, { id, choice }) {
1261
+ const s = this.get(key);
1262
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1263
+ const c = s.comments.find((x) => x.id === id);
1264
+ if (!c || c.status !== "asked" || !c.question) throw new HttpError(409, "this comment has no open question", { code: "not_asked" });
1265
+ if (choice !== null && !(Number.isInteger(choice) && choice >= 0 && choice < c.question.options.length)) throw new HttpError(400, "choice must be the number of one of the options, or null", { code: "bad_choice" });
1266
+ if (choice === null) {
1267
+ delete c.question;
1268
+ delete c.answer;
1269
+ } else c.answer = { choice };
1270
+ c.status = "draft";
1271
+ delete c.result;
1272
+ delete c.batchId;
1273
+ this.#changed(s, "draft");
1274
+ return s;
1275
+ }
1276
+
1277
+ /** Comments queued while the agent worked become the next pending batch, anchored on the file the agent leaves. Pure planning: touches no session state; re-anchoring problems are pushed onto `flags`. */
1278
+ #planQueued(s, post, postSha, flags) {
1279
+ let plan = null;
1280
+ if (s.queued) {
1281
+ const queued = s.comments.filter((c) => c.status === "queued");
1282
+ if (queued.length || s.queuedNote) {
1283
+ let units = null;
1284
+ try {
1285
+ units = readUnits(s.format, post);
1286
+ } catch (err) {
1287
+ flags.push({ code: "queued_reanchor_failed", severity: "warn", detail: err.message });
1288
+ }
1289
+ const durables = new Map();
1290
+ for (const c of queued) {
1291
+ let d = null;
1292
+ try {
1293
+ if (units) d = reanchor(units, c);
1294
+ } catch (err) {
1295
+ flags.push({ code: "queued_reanchor_failed", severity: "warn", comment_id: c.id, detail: err.message });
1296
+ }
1297
+ durables.set(c.id, d);
1298
+ }
1299
+ const batch = buildBatch({ file: s.file, format: s.format, baseSha: postSha, note: s.queuedNote, comments: queued.map((c) => ({ ...c, durable: durables.get(c.id) })), edits: [], style: styleNote(), guide: voiceGuide() });
1300
+ plan = { queued, durables, batch };
1301
+ }
1302
+ }
1303
+ return plan;
1304
+ }
1305
+
1306
+ // ---- review first (idea 21, src/review.js) ------------------------------------------------------------------
1307
+ /**
1308
+ * The person tapped a review button. The batch carries the fixed sentence for `kind` and the code-built outline of the file on disk; the
1309
+ * outline's index (where each unit is, its text hash) stays here. Refused while a batch waits or is delivered, and when the disk is not
1310
+ * the version the session knows. It goes to an agent, never to the local runner.
1311
+ */
1312
+ requestReview(key, kind) {
1313
+ const s = this.get(key);
1314
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1315
+ if (!REVIEW_KINDS.includes(kind)) throw new HttpError(400, `kind must be one of ${REVIEW_KINDS.join(", ")}`, { code: "bad_kind" });
1316
+ if (s.delivered || s.pending) throw new HttpError(409, s.delivered?.local ? "Wait for the change on this Mac to finish, then try again." : "Wait for the agent to finish, then try again.", { code: "busy" });
1317
+ let disk;
1318
+ try {
1319
+ checkRegularOwned(s.file);
1320
+ disk = readCapped(s.file);
1321
+ } catch (err) {
1322
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
1323
+ }
1324
+ if (sha256(disk) !== s.baseSha) throw new HttpError(409, "The file changed outside Onionskin. Reload it, then try again.", { code: "changed_since" });
1325
+ s.pending = this.#reviewBatch(s, kind, disk, s.baseSha);
1326
+ this.#deliverIfPolled(s);
1327
+ this.#changed(s);
1328
+ return s;
1329
+ }
1330
+
1331
+ #reviewBatch(s, kind, bytes, baseSha) {
1332
+ const { units, more, index } = unitsOf(s.format, bytes);
1333
+ const batch = buildBatch({ file: s.file, format: s.format, baseSha, note: "", comments: [], edits: [], review: { kind, ask: REVIEW_ASKS[kind] }, units, unitsMore: more });
1334
+ s.review = { batchId: batch.batch_id, kind, units: units.map((u) => ({ id: u.id, protected: u.protected })), index };
1335
+ s.decidedBatch = batch.batch_id; // never the local runner's: only an agent reads the file
1336
+ return batch;
1337
+ }
1338
+
1339
+ /** `done` of a review that wrote nothing: the suggestions become cards (checked against the file), an activity entry of kind "review", no history update. */
1340
+ #doneReview(s, results, run, post) {
1341
+ const flags = [];
1342
+ const ix = s.review?.batchId === run.batch.batch_id ? s.review : null;
1343
+ const { cards, dropped } = ix ? cardsFrom(results.suggestions, { bytes: post, format: s.format, units: ix.units, index: ix.index, reviewId: run.batch.batch_id }) : { cards: [], dropped: (Array.isArray(results.suggestions) ? results.suggestions : []).map((_, i) => ({ index: i, reason: "the review's outline is gone" })) };
1344
+ for (const d of dropped) flags.push({ code: "bad_suggestion", severity: "warn", ...(d.index != null ? { index: d.index } : {}), reason: d.reason });
1345
+ if (results.voice_draft !== undefined) flags.push({ code: "voice_draft_not_allowed", severity: "warn" });
1346
+ const queuedPlan = this.#planQueued(s, post, run.preSha, flags);
1347
+ const cleanFlags = flags.map(cleanFlag);
1348
+ const { list: ignored, more: ignoredMore } = ignoredInstructions(results.document_instructions_ignored); // a review reads the whole file: its report counts most here
1349
+ const entry = {
1350
+ ...(ignored.length ? { documentInstructionsIgnored: ignored, ...(ignoredMore ? { documentInstructionsIgnoredMore: true } : {}) } : {}),
1351
+ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "review", at: this.now(), batchId: run.batch.batch_id, reviewKind: run.batch.instructions.review.kind,
1352
+ summary: reviewSummary(cards.length), results: [], flags: cleanFlags, checks: null, changes: null, suggestions: cards.length, suggestionsDropped: dropped.length,
1353
+ preSha: run.preSha, postSha: run.preSha, reverted: false,
1354
+ };
1355
+ // ---- commit
1356
+ for (const g of s.suggestions || []) if (g.status === "open") g.status = "replaced";
1357
+ s.suggestions = [...cards, ...(s.suggestions || [])].slice(0, 3 * SUGGESTIONS_MAX);
1358
+ s.activity.unshift(entry);
1359
+ s.edits = [...run.edits, ...s.edits]; // the review carried none of the person's edits: they ride with the next Send
1360
+ s.delivered = null;
1361
+ s.review = null;
1362
+ if (s.queued) {
1363
+ s.queued = false;
1364
+ if (queuedPlan) {
1365
+ for (const c of queuedPlan.queued) {
1366
+ c.durable = queuedPlan.durables.get(c.id);
1367
+ c.status = "sent";
1368
+ c.batchId = queuedPlan.batch.batch_id;
1369
+ }
1370
+ s.pending = queuedPlan.batch;
1371
+ s.queuedNote = "";
1372
+ }
1373
+ }
1374
+ this.#writeLease(s);
1375
+ this.#deliverIfPolled(s);
1376
+ this.#changed(s); // nothing changed in the file: no reload
1377
+ return { ok: true, flags: cleanFlags, checks: null, suggestions: cards.length, dropped: dropped.length };
1378
+ }
1379
+
1380
+ /**
1381
+ * The person tapped a card button: `choice` 0 = Accept (edit cards), 1 = Reject or Dismiss. "Show me" never reaches the server. Only ids
1382
+ * and an integer come from the page. Accept runs the stored ops on this Mac (startLocal: the lease, apply with --partial, done, Revert);
1383
+ * the cards stay open until that run settles them (accepted, or stale when the text there changed).
1384
+ */
1385
+ answerSuggestions(key, { ids, choice }) {
1386
+ const s = this.get(key);
1387
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1388
+ if (choice !== 0 && choice !== 1) throw new HttpError(400, "choice must be 0 (accept) or 1 (reject)", { code: "bad_choice" });
1389
+ if (!Array.isArray(ids) || !ids.length || ids.length > SUGGESTIONS_MAX || !ids.every((x) => typeof x === "string") || new Set(ids).size !== ids.length) throw new HttpError(400, `ids must list 1 to ${SUGGESTIONS_MAX} different suggestion ids`, { code: "bad_ids" });
1390
+ const cards = ids.map((id) => (s.suggestions || []).find((g) => g.id === id));
1391
+ if (cards.some((g) => !g)) throw new HttpError(400, "no such suggestion", { code: "unknown_suggestion" });
1392
+ if (cards.some((g) => g.status !== "open")) throw new HttpError(409, "this suggestion was already answered", { code: "not_open" });
1393
+ if (choice === 1) {
1394
+ for (const g of cards) g.status = g.kind === "note" ? "dismissed" : "rejected";
1395
+ this.#changed(s);
1396
+ return s;
1397
+ }
1398
+ if (cards.some((g) => g.kind !== "edit" || !g.op)) throw new HttpError(400, "a note cannot be accepted", { code: "not_acceptable" });
1399
+ if (s.delivered) throw new HttpError(423, s.delivered?.local ? "Wait for the change on this Mac to finish, then try again." : "Wait for the agent to finish, then try again.", { code: "locked" });
1400
+ if (s.pending) throw new HttpError(409, s.delivered?.local ? "Wait for the change on this Mac to finish, then try again." : "Wait for the agent to finish, then try again.", { code: "busy" });
1401
+ let disk;
1402
+ try {
1403
+ checkRegularOwned(s.file);
1404
+ disk = readCapped(s.file);
1405
+ } catch (err) {
1406
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
1407
+ }
1408
+ if (sha256(disk) !== s.baseSha) throw new HttpError(409, "The file changed outside Onionskin. Reload it, then try again.", { code: "changed_since" });
1409
+ const batch = buildBatch({ file: s.file, format: s.format, baseSha: s.baseSha, note: "", comments: [], edits: [] });
1410
+ const n = cards.length;
1411
+ this.startLocal(key, batch, { ops: cards.map((g) => g.op), summary: `Accepted ${n} suggestion${n === 1 ? "" : "s"} from the agent's review.` });
1412
+ s.delivered.suggestionIds = ids; // settled by done or dropLocal
1413
+ this.#save(s);
1414
+ return s;
1415
+ }
1416
+
1417
+ /**
1418
+ * "Use this" on a quick fix (idea 10 option A, src/suggest.js). `suggestion` is the server's stored record ({task, quote, location,
1419
+ * before, after}, from memory, handed over by src/suggest.js); the page sends only ids, its comments and its bytes. The page's unsent edits
1420
+ * are taken first, exactly as a Send takes them (#takePage); then one comment, whose words must be the server's own stamp words for the
1421
+ * task and whose anchor must be the one the suggestion was made for, becomes a batch of its own. The local runner writes it through
1422
+ * `reply` (one find and replace inside that paragraph or text box, the anchor's text hash as `expect`), apply's checks, the lease, `done`
1423
+ * and Revert, as for any local run. The text written is the stored suggestion, never text from the page. Every refusal happens before
1424
+ * anything is written. Other comments and the overall note stay for the next Send; typed edits ride with it too.
1425
+ */
1426
+ useSuggestion(key, { suggestion: rec, commentId, comments, note, baseSha, bytes = null, edits = [] }) {
1427
+ const s = this.get(key);
1428
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1429
+ if (s.delivered || s.pending) throw new HttpError(409, "The agent started working on this file, so nothing was written. Ask the agent instead, or try again when it is done.", { code: "busy" });
1430
+ const words = rec && Object.hasOwn(STAMP_WORDS, rec.task) && rec.task !== "translate" ? STAMP_WORDS[rec.task] : null;
1431
+ if (!words || typeof rec.before !== "string" || typeof rec.after !== "string") throw new HttpError(409, "This suggestion is out of date. Tap the stamp again.", { code: "expired" });
1432
+ const id = String(commentId ?? "").slice(0, 64);
1433
+ const mine = Array.isArray(comments) ? comments.find((c) => c && String(c.id) === id) : null;
1434
+ const old = s.comments.find((c) => c.id === id);
1435
+ const sameAnchor = (a) => a && typeof a === "object" && a.quote === rec.quote && JSON.stringify(a.location ?? null) === JSON.stringify(rec.location ?? null);
1436
+ if (!mine || userText(mine.text) !== words || !sameAnchor(mine.anchor) || (old && old.status !== "draft")) throw new HttpError(409, "This comment is not the suggestion's stamp.", { code: "not_this_comment" });
1437
+
1438
+ this.setDraft(key, { comments, note: note ?? s.note });
1439
+ const c = s.comments.find((x) => x.id === id);
1440
+ const anchor = { location: c.anchor.location, quote: c.anchor.quote, prefix: c.anchor.prefix, suffix: c.anchor.suffix };
1441
+ let plan = null;
1442
+ // the place and the reply are worked out on the very bytes that are about to be the file; any refusal here writes nothing
1443
+ const check = (b) => {
1444
+ const units = readUnits(s.format, b);
1445
+ const durable = buildDurable(units, anchor);
1446
+ const place = placeOf(units, durable, rec.quote);
1447
+ if (!place.ok) throw new HttpError(409, place.code === "protected" ? "This part of the file is protected, so it cannot be changed here." : LOCAL_HINT, { code: place.code });
1448
+ const reply = buildUseReply(rec, id, place.text);
1449
+ const batch = buildBatch({ file: s.file, format: s.format, baseSha: sha256(b), note: "", comments: [{ ...c, durable }], edits: [] });
1450
+ if (!reply || batch.instructions.comments[0]?.reply_with !== "find_replace_or_text") throw new HttpError(409, LOCAL_HINT, { code: "not_here" });
1451
+ plan = { durable, reply, batch };
1452
+ };
1453
+ let taken;
1454
+ try {
1455
+ taken = this.#takePage(s, { baseSha, bytes }, check);
1456
+ } catch (err) {
1457
+ // nothing was written: the comment stays a draft, and says it can go to the agent
1458
+ if (["not_here", "not_eligible", "protected"].includes(err?.extra?.code)) {
1459
+ c.localHint = LOCAL_HINT;
1460
+ this.#changed(s);
1461
+ }
1462
+ throw err;
1463
+ }
1464
+ for (const e of Array.isArray(edits) ? edits.slice(0, 2000) : []) s.edits.push({ kind: e.kind, before: e.before, after: e.after, label: e.label, location: e.location });
1465
+ c.durable = plan.durable;
1466
+ c.status = "sent";
1467
+ c.batchId = plan.batch.batch_id;
1468
+ delete c.localHint;
1469
+ s.lastWrite = taken.writeInfo;
1470
+ try {
1471
+ this.startLocal(key, plan.batch, { reply: plan.reply, summary: USE_SUMMARY, model: true }); // saves, tells the page, starts the runner
1472
+ } catch (err) {
1473
+ // not reachable after the checks above; if it were, the page's bytes are kept (they are the person's) and the comment is a draft again
1474
+ c.status = "draft";
1475
+ delete c.batchId;
1476
+ this.#changed(s);
1477
+ throw err;
1478
+ }
1479
+ return s;
1480
+ }
1481
+
1482
+ /** An accepted run ended: its cards whose op applied are "accepted", the rest "stale". `applied` are op ids the runner read from apply's report. */
1483
+ #settleCards(s, run, applied) {
1484
+ const ids = new Set(run?.suggestionIds || []);
1485
+ const ok = new Set(applied.filter((x) => ids.has(x)));
1486
+ for (const g of s.suggestions || []) {
1487
+ if (!ids.has(g.id) || g.status !== "open") continue;
1488
+ g.status = ok.has(g.id) ? "accepted" : "stale";
1489
+ if (ok.has(g.id)) g.acceptedBatch = run.batch.batch_id;
1490
+ }
1491
+ }
1492
+
1493
+ // ---- "Build my voice guide" (stage 2, src/voice-learn.js builds the batch) ------------------------------------------------
1494
+ /**
1495
+ * The person asked the agent for a draft of their voice guide. `batch` is buildVoiceBatch's (src/batch.js): code constants, their
1496
+ * approved guide and preferences, and the samples they ticked as evidence. Refused while a batch waits or is delivered, and when the file
1497
+ * on disk or the session moved on since the samples were taken. It goes to an agent, never to the local runner. While it is delivered
1498
+ * nothing may be written (409 voice_only), and `done` keeps the draft for the person's review (#doneVoice).
1499
+ */
1500
+ requestVoice(key, batch) {
1501
+ const s = this.get(key);
1502
+ if (s.closed) throw new HttpError(409, "session closed", { code: "closed" });
1503
+ if (readOnlyKind(batch) !== "voice") throw new HttpError(400, "not a voice guide request", { code: "bad_request" });
1504
+ if (s.delivered || s.pending) throw new HttpError(409, s.delivered?.local ? "Wait for the change on this Mac to finish, then try again." : "Wait for the agent to finish, then try again.", { code: "busy" });
1505
+ let disk;
1506
+ try {
1507
+ checkRegularOwned(s.file);
1508
+ disk = readCapped(s.file);
1509
+ } catch (err) {
1510
+ throw new HttpError(409, `cannot read the file: ${err.message}`, { code: "gone" });
1511
+ }
1512
+ // a file changed outside Onionskin would otherwise be blamed on the voice run when it ends; samples taken from an older version are not sent
1513
+ if (sha256(disk) !== s.baseSha || batch.base_sha256 !== s.baseSha) throw new HttpError(409, "The file changed outside Onionskin. Reload it, then try again.", { code: "changed_since" });
1514
+ s.pending = batch;
1515
+ s.decidedBatch = batch.batch_id; // never the local runner's: only an agent drafts a guide
1516
+ this.#deliverIfPolled(s);
1517
+ this.#changed(s);
1518
+ return s;
1519
+ }
1520
+
1521
+ /**
1522
+ * `done` of a voice batch (the trust boundary for the draft). The draft is agent text: it is checked by cleanVoiceDraft and stored as
1523
+ * an untrusted draft (voice-draft.json) for the person to read, edit and approve, never copied into the saved guide: only their Save on
1524
+ * the page does that. Every other field the agent sends (a guide, `on`, `save`, results) changes nothing. An activity entry of kind
1525
+ * "voice" with a fixed summary, no history update and no analysis. A file that changed anyway (a direct save past voice_only) is
1526
+ * recorded as a withdrawn run would be: flagged, kept Revert-able.
1527
+ */
1528
+ #doneVoice(s, results, run, post, postSha) {
1529
+ const flags = [];
1530
+ for (const r of (Array.isArray(results.results) ? results.results : []).slice(0, 1000)) flags.push({ code: "unknown_result", severity: "warn", comment_id: String(r?.comment_id ?? "").slice(0, 64) });
1531
+ const check = cleanVoiceDraft(results.voice_draft); // size first, then hidden characters, links and markup, the layout, the caps
1532
+ if (check.code) flags.push({ code: "bad_voice_draft", severity: "warn", reason: check.code });
1533
+ this.#guardFlags(run, flags);
1534
+ const queuedPlan = this.#planQueued(s, post, postSha, flags);
1535
+ const { list: ignored, more: ignoredMore } = ignoredInstructions(results.document_instructions_ignored);
1536
+ // ---- commit: the draft file first (a failed write keeps nothing and says so), then the session
1537
+ let kept = false;
1538
+ if (!check.code) {
1539
+ try {
1540
+ writeDraft({ batch_id: run.batch.batch_id, text: results.voice_draft });
1541
+ kept = true;
1542
+ } catch {
1543
+ flags.push({ code: "voice_draft_not_saved", severity: "warn" });
1544
+ }
1545
+ }
1546
+ const cleanFlags = flags.map(cleanFlag);
1547
+ const wrote = postSha !== run.preSha && this.#recordMidRun(s, "The file changed while the agent drafted your voice guide.", "voice_run_changed_file");
1548
+ s.activity.unshift({
1549
+ ...(ignored.length ? { documentInstructionsIgnored: ignored, ...(ignoredMore ? { documentInstructionsIgnoredMore: true } : {}) } : {}),
1550
+ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "voice", at: this.now(), batchId: run.batch.batch_id,
1551
+ summary: kept ? VOICE_KEPT : VOICE_REFUSED, results: [], flags: cleanFlags, checks: null, changes: null,
1552
+ preSha: run.preSha, postSha: run.preSha, reverted: false,
1553
+ });
1554
+ s.edits = [...run.edits, ...s.edits]; // the voice batch carried none of the person's edits: they ride with the next Send
1555
+ s.delivered = null;
1556
+ if (s.queued) {
1557
+ s.queued = false;
1558
+ if (queuedPlan) {
1559
+ for (const c of queuedPlan.queued) {
1560
+ c.durable = queuedPlan.durables.get(c.id);
1561
+ c.status = "sent";
1562
+ c.batchId = queuedPlan.batch.batch_id;
1563
+ }
1564
+ s.pending = queuedPlan.batch;
1565
+ s.queuedNote = "";
1566
+ }
1567
+ }
1568
+ this.#writeLease(s);
1569
+ this.#deliverIfPolled(s);
1570
+ this.#changed(s, wrote ? "reload" : "state"); // nothing changed in the file: no reload (as a review)
1571
+ return { ok: true, flags: cleanFlags, checks: null, voice_draft: kept ? "kept" : "refused" };
1572
+ }
1573
+
1574
+ /** style.json and voice-guide.json changed by something else while this run was out (an agent with a shell, say): already put back by their stores. */
1575
+ #guardFlags(run, flags) {
1576
+ if (this.#styleSeen.has(run) && styleChangedOutside() > this.#styleSeen.get(run)) flags.push({ code: "style_changed_outside_onionskin", severity: "warn", detail: "Your writing preferences were changed outside Onionskin, so they were put back." });
1577
+ if (this.#guideSeen.has(run) && guideChangedOutside() > this.#guideSeen.get(run)) flags.push({ code: "voice_guide_changed_outside_onionskin", severity: "warn", detail: "Your voice guide was changed outside Onionskin, so it was put back." });
1578
+ }
1579
+
1580
+ // ---- take back / revert / close -------------------------------------------------------------------------
1581
+ takeBack(key) {
1582
+ const s = this.get(key);
1583
+ const batch = s.delivered?.batch || s.pending;
1584
+ if (!batch) throw new HttpError(409, "nothing to take back");
1585
+ // the note travels back with the comments: the withdrawn batch's note, then a queued one, then whatever was typed since
1586
+ const notes = [batch.instructions?.overall_note, s.queuedNote, s.note].filter(Boolean);
1587
+ s.note = [...new Set(notes)].join("\n\n");
1588
+ s.queuedNote = "";
1589
+ let event = "state";
1590
+ if (s.delivered) {
1591
+ // the typed edits stay as evidence for the next batch: they were saved into the file before this batch went out
1592
+ s.edits = [...s.delivered.edits, ...s.edits];
1593
+ if (this.#recordMidRun(s, s.delivered.local ? "Taken back mid-run: the change on this Mac had already changed the file." : "Taken back mid-run: the agent had already changed the file.", "taken_back_mid_run")) event = "reload";
1594
+ }
1595
+ for (const c of s.comments) if (["sent", "queued"].includes(c.status)) c.status = "draft";
1596
+ s.delivered = null;
1597
+ s.pending = null;
1598
+ s.conflict = null;
1599
+ s.queued = false;
1600
+ this.#writeLease(s);
1601
+ this.#changed(s, event);
1602
+ return s;
1603
+ }
1604
+
1605
+ /**
1606
+ * The agent may have written before its batch was withdrawn (Take back, lease expiry): the page still shows the pre-agent copy. When the
1607
+ * disk differs from the pre-agent snapshot, keep that run Revert-able (an `agent` entry with the original preSha), make the new bytes the
1608
+ * base and say so; the caller emits `reload`. Returns whether anything changed on disk.
1609
+ * Ceiling: after a lease expiry the redelivered batch starts from these partial bytes, so Revert on ITS run returns to the partial state.
1610
+ */
1611
+ #recordMidRun(s, summary, code) {
1612
+ let disk = null;
1613
+ try {
1614
+ disk = readCapped(s.file);
1615
+ } catch {
1616
+ return false;
1617
+ }
1618
+ if (sha256(disk) === s.delivered.preSha) return false;
1619
+ try {
1620
+ s.snapshots.add(disk, "after agent (withdrawn)");
1621
+ } catch {} // a full disk must not block withdrawing; Revert will say the version is not stored
1622
+ const postSha = sha256(disk);
1623
+ const flags = [{ code, severity: "warn" }];
1624
+ // the same rule as done: bytes this server never wrote or delivered came from a direct save, not the agent's apply or commit
1625
+ if (postSha !== (s.delivered.knownSha ?? s.delivered.preSha)) flags.push({ code: "file_changed_outside_onionskin", severity: "error", detail: directSave(s.delivered.local) });
1626
+ s.activity.unshift({
1627
+ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "agent", at: this.now(), batchId: s.delivered.batch.batch_id,
1628
+ summary, results: [], flags, checks: null,
1629
+ revertRecommended: true, changes: null, preSha: s.delivered.preSha, postSha, reverted: false,
1630
+ ...(s.delivered.local ? { by: "local", localNote: userText(s.delivered.batch.instructions?.overall_note || "") } : {}),
1631
+ });
1632
+ addUpdate(s, { kind: s.delivered.local ? "local" : "agent", before: s.delivered.preSha, after: postSha, summary }, this.now());
1633
+ s.histTip = postSha;
1634
+ s.baseSha = postSha;
1635
+ return true;
1636
+ }
1637
+
1638
+ revert(key, activityId) {
1639
+ const s = this.get(key);
1640
+ if (s.delivered) throw new HttpError(423, s.delivered.local ? "a change is being made on this Mac" : "the agent is working", { code: "locked" });
1641
+ const entry = s.activity.find((a) => a.id === activityId && a.kind === "agent");
1642
+ if (!entry || entry.reverted) throw new HttpError(404, "nothing to revert");
1643
+ const mac = entry.by === "local"; // a change made on this Mac: no agent was involved, so the words do not say one was
1644
+ const latest = s.activity.find((a) => a.kind === "agent" && !a.reverted);
1645
+ if (latest !== entry) throw new HttpError(409, mac ? "only the latest change can be reverted" : "only the latest agent run can be reverted", { code: "not_latest" });
1646
+ const disk = readCapped(s.file);
1647
+ if (sha256(disk) !== entry.postSha) throw new HttpError(409, mac ? "the file changed after the change was made; revert refused" : "the file changed after the agent finished; revert refused", { code: "changed_since" });
1648
+ if (!s.snapshots.has(entry.preSha)) throw new HttpError(410, mac ? "the version before this change is no longer stored" : "the pre-agent version is no longer stored");
1649
+ const pre = s.snapshots.read(entry.preSha);
1650
+ this.#replace(s, pre, { expectSha: entry.postSha, label: "before revert" }); // a revert is a new version
1651
+ s.snapshots.add(pre, "reverted");
1652
+ s.baseSha = entry.preSha;
1653
+ addUpdate(s, { kind: "revert", before: entry.postSha, after: entry.preSha, local: mac }, this.now());
1654
+ s.histTip = entry.preSha;
1655
+ entry.reverted = true;
1656
+ // the run's comments were answered against a version that no longer exists: they are drafts again
1657
+ for (const c of s.comments) {
1658
+ if (c.batchId === entry.batchId && ["done", "declined", "asked"].includes(c.status)) {
1659
+ if (c.status === "asked") delete c.question; // asked about a version that no longer exists
1660
+ c.status = "draft";
1661
+ delete c.result;
1662
+ delete c.batchId;
1663
+ if (entry.by === "local") c.skipLocal = true; // the person undid what this Mac did: the next Send asks the agent
1664
+ }
1665
+ }
1666
+ for (const g of s.suggestions || []) if (g.status === "accepted" && g.acceptedBatch === entry.batchId) g.status = "open"; // the text is back: it can be accepted again
1667
+ if (entry.by === "local" && entry.localNote && !s.note) {
1668
+ s.note = entry.localNote; // the request comes back to the box, and the same words go to the agent next time
1669
+ s.skipLocalNote = entry.localNote;
1670
+ }
1671
+ // a batch built against the reverted version is rebuilt against the restored bytes (a review: its outline is read again; a voice
1672
+ // request keeps its samples, which left out what that run wrote, and points at the restored version)
1673
+ if (readOnlyKind(s.pending) === "voice") s.pending = { ...s.pending, base_sha256: entry.preSha };
1674
+ else if (s.pending?.instructions?.review) s.pending = this.#reviewBatch(s, s.pending.instructions.review.kind, pre, entry.preSha);
1675
+ else if (s.pending) {
1676
+ const ids = new Set(s.pending.instructions.comments.map((c) => c.id));
1677
+ const cs = s.comments.filter((c) => ids.has(c.id));
1678
+ let units = null;
1679
+ try {
1680
+ units = readUnits(s.format, pre);
1681
+ } catch {
1682
+ units = null;
1683
+ }
1684
+ for (const c of cs) {
1685
+ try {
1686
+ if (units) c.durable = reanchor(units, c);
1687
+ } catch {
1688
+ c.durable = null;
1689
+ }
1690
+ }
1691
+ s.pending = buildBatch({ file: s.file, format: s.format, baseSha: entry.preSha, note: s.pending.instructions.overall_note, comments: cs, edits: [], style: styleNote(), guide: voiceGuide() });
1692
+ for (const c of cs) c.batchId = s.pending.batch_id;
1693
+ }
1694
+ s.activity.unshift({ id: `r_${crypto.randomBytes(4).toString("hex")}`, kind: "revert", at: this.now(), summary: mac ? "Reverted to the version before this change." : "Reverted to the version before the agent's run.", flags: [], results: [], postSha: entry.preSha });
1695
+ this.#changed(s, "reload");
1696
+ return s;
1697
+ }
1698
+
1699
+ close(key) {
1700
+ const s = this.get(key);
1701
+ s.closed = true;
1702
+ for (const p of s.pollers.splice(0)) p.resolve({ status: "closed" });
1703
+ fs.rmSync(path.join(stateDir(), "agents", s.key, "outline"), { recursive: true, force: true }); // the outline files of Onionskin's own agent
1704
+ this.emit("closed", s); // the server ends background checks for this file
1705
+ this.#changed(s);
1706
+ return s;
1707
+ }
1708
+
1709
+ /**
1710
+ * The page loads the file (first load, "Reload the changed file", a reload of the tab). When the disk holds a version history does not
1711
+ * know, someone changed it outside Onionskin and the user is now taking that version: store it and record an "outside" update
1712
+ * (before = the last version history knew, after = these bytes). Never while an agent works (the disk changes then by design).
1713
+ * Returns the same {diskSha, baseSha, bytes} as diskCheck.
1714
+ */
1715
+ loadForPage(key) {
1716
+ const out = this.diskCheck(key);
1717
+ const s = this.get(key);
1718
+ if (!s.delivered && !s.closed && s.histTip && out.diskSha !== s.histTip) {
1719
+ try {
1720
+ s.snapshots.add(out.bytes, "outside change");
1721
+ addUpdate(s, { kind: "outside", before: s.histTip, after: out.diskSha }, this.now());
1722
+ s.histTip = out.diskSha;
1723
+ this.#save(s);
1724
+ } catch {} // no space for the snapshot: nothing is recorded, the file still loads
1725
+ }
1726
+ return out;
1727
+ }
1728
+
1729
+ /** The history list and one update (browser routes, read-only; see src/history.js). */
1730
+ history(key) {
1731
+ return historyList(this.get(key));
1732
+ }
1733
+ async historyUpdate(key, id) {
1734
+ const d = await historyDetail(this.get(key), id);
1735
+ if (!d) throw new HttpError(404, "no such update", { code: "no_such_update" });
1736
+ return d;
1737
+ }
1738
+
1739
+ // ---- the tracked-changes copy (M4 Idea 16, docs/contracts/tracked-changes.md) ------------------------------------------
1740
+ /**
1741
+ * The versions a tracked-changes copy covers. `id` is one agent run (only while its result is the file on disk) or "all": everything
1742
+ * History holds, from the oldest stored update to the current version, refused when the chain has a gap or holds an outside change.
1743
+ * Returns {before, after, author, date}; throws HttpError with a plain message.
1744
+ */
1745
+ #exportSpan(s, id) {
1746
+ const vis = visibleUpdates(s); // newest first
1747
+ const run = (u) => u.kind === "agent" || u.kind === "local"; // a run on this Mac is recorded like an agent's (activity kind "agent", by "local")
1748
+ const outsideRun = (u) => run(u) && (s.activity || []).some((a) => a.kind === "agent" && a.preSha === u.before && a.postSha === u.after && (a.flags || []).some((f) => f.code === "file_changed_outside_onionskin"));
1749
+ const refuse = (status, code, msg = TRACKED[code]) => new HttpError(status, msg, { code });
1750
+ let list;
1751
+ if (id === "all") {
1752
+ if (!vis.length) throw refuse(404, "nothing");
1753
+ list = vis.slice().reverse();
1754
+ for (let k = 0; k + 1 < list.length; k++) {
1755
+ if (list[k].after === list[k + 1].before) continue;
1756
+ // a break in the chain: an outside change no longer listed, or an update whose versions were pruned
1757
+ const from = s.history.indexOf(list[k]);
1758
+ const to = s.history.indexOf(list[k + 1]);
1759
+ if (s.history.slice(from + 1, to).some((u) => u.kind === "outside")) throw refuse(409, "outside");
1760
+ throw refuse(409, "unsupported", unsupportedText(["pruned"]));
1761
+ }
1762
+ if (list[list.length - 1].after !== s.histTip) throw refuse(409, "outside"); // the file on disk is a version History never recorded
1763
+ } else {
1764
+ const u = vis.find((x) => x.id === id);
1765
+ if (!u) throw new HttpError(404, "no such update", { code: "no_such_update" });
1766
+ if (!run(u)) throw refuse(409, "not_agent");
1767
+ if (u.after !== s.histTip) throw refuse(409, "not_current");
1768
+ list = [u];
1769
+ }
1770
+ if (list.some((u) => u.kind === "outside" || outsideRun(u))) throw refuse(409, "outside");
1771
+ const newest = list[list.length - 1];
1772
+ return { before: list[0].before, after: newest.after, author: list.every((u) => u.kind === "agent" || u.kind === "revert") ? AUTHORS.agent : AUTHORS.mixed, date: wordDate(newest.at) };
1773
+ }
1774
+
1775
+ /**
1776
+ * "Save a copy with tracked changes": builds and checks the copy in a worker, then writes it NEXT TO the file (never over it, never the file
1777
+ * itself). Nothing is written unless every check passes: the span rules, the disk still holding the span's newest version before and after
1778
+ * the build, the builder's gates, the in-code round trip, and the deeper check when it is set up. Returns {ok, saved, name, path, ...}.
1779
+ */
1780
+ async exportTracked(key, id) {
1781
+ const s = this.get(key);
1782
+ if (s.format !== "docx") throw new HttpError(409, TRACKED.not_docx, { code: "not_docx" });
1783
+ if (s.delivered) throw new HttpError(423, TRACKED.locked, { code: "locked" });
1784
+ if (this.exporting.has(key)) throw new HttpError(409, TRACKED.busy, { code: "busy" });
1785
+ const span = this.#exportSpan(s, id);
1786
+ this.exporting.add(key);
1787
+ try {
1788
+ const current = () => {
1789
+ if (s.delivered) throw new HttpError(423, TRACKED.locked, { code: "locked" });
1790
+ let disk = null;
1791
+ try {
1792
+ disk = sha256(readCapped(s.file));
1793
+ } catch {} // moved, removed or unreadable: not the version the copy is made from
1794
+ if (s.histTip !== span.after || disk !== span.after) throw new HttpError(409, id === "all" ? TRACKED.outside : TRACKED.not_current, { code: id === "all" ? "outside" : "not_current" });
1795
+ };
1796
+ current();
1797
+ if (!s.snapshots.has(span.before) || !s.snapshots.has(span.after)) throw new HttpError(409, unsupportedText(["pruned"]), { code: "unsupported" });
1798
+ const r = await exportInWorker({ before: s.snapshots.blob(span.before), after: s.snapshots.blob(span.after), author: span.author, date: span.date });
1799
+ if (r.timeout) throw new HttpError(409, TRACKED.timeout, { code: "timeout" });
1800
+ if (r.refused?.includes("has_revisions")) throw new HttpError(409, TRACKED.has_revisions, { code: "has_revisions" });
1801
+ if (r.refused?.includes("no_changes")) throw new HttpError(409, TRACKED.no_changes, { code: "no_changes" });
1802
+ if (r.refused) throw new HttpError(409, unsupportedText(r.refused), { code: "unsupported", reasons: r.refused });
1803
+ if (!r.ok) throw new HttpError(409, TRACKED.check_failed, { code: "check_failed" });
1804
+ const bytes = Buffer.from(r.bytes);
1805
+ const deep = await deepRedline(s.snapshots.read(span.before), s.snapshots.read(span.after), bytes);
1806
+ if (deep.ran && !deep.ok) throw new HttpError(409, TRACKED.check_failed, { code: "check_failed" });
1807
+ current(); // the agent, a Send or another program may have changed the file while the copy was made
1808
+ const notes = [];
1809
+ if (r.counts.formatting) notes.push(formattingText(r.counts.formatting));
1810
+ if (r.counts.moved) notes.push(TRACKED.moves);
1811
+ if (!deep.ran) notes.push(TRACKED.not_set_up);
1812
+ const counts = r.counts;
1813
+ let copy;
1814
+ try {
1815
+ copy = writeSiblingCopy(s.file, bytes, { label: "tracked changes" });
1816
+ } catch (err) {
1817
+ if (!["EACCES", "EPERM", "EROFS", "ENOSPC", "EDQUOT"].includes(err.code)) throw err;
1818
+ const ext = path.extname(s.file);
1819
+ const name = `${path.basename(s.file, ext)} (tracked changes)${ext}`; // from the session's own path, never document text
1820
+ if (bytes.length > 25 * 1024 * 1024) return { ok: true, saved: false, code: "folder_too_large", message: TRACKED.folder_too_large, counts, notes };
1821
+ return { ok: true, saved: false, code: "folder_not_writable", message: TRACKED.folder, download: { name, bytesB64: bytes.toString("base64") }, counts, notes };
1822
+ }
1823
+ this.createdCopies.add(copy.path);
1824
+ return { ok: true, saved: true, name: copy.name, path: copy.path, can_reveal: canReveal(), message: savedText(copy.name), counts, notes };
1825
+ } finally {
1826
+ this.exporting.delete(key);
1827
+ }
1828
+ }
1829
+
1830
+ /** Unlocked document, current disk hash vs the base we hold; used by the page after a reconnect. */
1831
+ diskCheck(key) {
1832
+ const s = this.get(key);
1833
+ const disk = readCapped(s.file);
1834
+ return { diskSha: sha256(disk), baseSha: s.baseSha, bytes: disk };
1835
+ }
1836
+
1837
+ /**
1838
+ * Re-resolve durable anchors (comments + view) against the current disk bytes. DOCX results keep the shape docx.js returns; XLSX and
1839
+ * PPTX results are in terms of the current file (sheetIndex/sheetName/range, slideIndex/slideId/shapeId) so the page never reuses a stored location.
1840
+ */
1841
+ resolveAll(key) {
1842
+ const s = this.get(key);
1843
+ const bytes = readCapped(s.file);
1844
+ const out = { baseSha: sha256(bytes), format: s.format, anchors: {}, view: null };
1845
+ const units = readUnits(s.format, bytes);
1846
+ for (const c of s.comments) {
1847
+ if (!c.durable) continue;
1848
+ let r = resolveDurableAny(units, c.durable);
1849
+ if (r.method === "none" && units.format === "pptx" && c.durable.pinFallback) {
1850
+ const f = resolveDurableAny(units, c.durable.pinFallback);
1851
+ if (f.method !== "none") r = { ...f, tieLost: true };
1852
+ }
1853
+ if (units.format === "docx" && r.method !== "none") r.heading = headingBefore(units.paragraphs, r.ordinal);
1854
+ out.anchors[c.id] = r;
1855
+ }
1856
+ if (s.format === "pptx") out.slides = units.deck.slides.map((x) => ({ index: x.index, id: x.id }));
1857
+ if (s.format === "docx") {
1858
+ if (s.view?.durable) out.view = { ...resolveDurable(units.paragraphs, s.view.durable), offsetPx: s.view.offsetPx, zoom: s.view.zoom, fraction: s.view.fraction };
1859
+ } else out.view = resolveView(units, s.view);
1860
+ out.sheets = s.format === "xlsx" ? units.wb.sheets.map((x) => ({ index: x.index, name: x.name, sheetId: x.sheetId })) : undefined;
1861
+ return out;
1862
+ }
1863
+ }
1864
+
1865
+ /**
1866
+ * `document_instructions_ignored` from the agent's results. Only strings count (anything else is dropped), each sanitized as untrusted text,
1867
+ * empty ones dropped and repeats ignoring case counted once. Looks at the first 50 raw items; keeps the first 5 distinct ones and says in `more`
1868
+ * when a sixth distinct one was reported. The count is the agent's own report: it is never proof of how many orders the file held.
1869
+ */
1870
+ function ignoredInstructions(v) {
1871
+ const list = [];
1872
+ let more = false;
1873
+ if (!Array.isArray(v)) return { list, more };
1874
+ const seen = new Set();
1875
+ for (const x of v.slice(0, 50)) {
1876
+ if (typeof x !== "string") continue;
1877
+ const t = untrusted(x, 200);
1878
+ const k = t.toLowerCase();
1879
+ if (!t || seen.has(k)) continue;
1880
+ seen.add(k);
1881
+ if (list.length < 5) list.push(t);
1882
+ else more = true;
1883
+ }
1884
+ return { list, more };
1885
+ }
1886
+
1887
+ const EXPORT_TIMEOUT_MS = () => Number(env("EXPORT_TIMEOUT_MS", 60_000));
1888
+ /** Builds and checks one tracked-changes copy in a worker thread (src/redline-worker.js), so a large file never blocks the server. */
1889
+ function exportInWorker(job) {
1890
+ return new Promise((resolve) => {
1891
+ let worker;
1892
+ let settled = false;
1893
+ const finish = (r) => {
1894
+ if (settled) return;
1895
+ settled = true;
1896
+ clearTimeout(timer);
1897
+ worker?.terminate();
1898
+ resolve(r);
1899
+ };
1900
+ const timer = setTimeout(() => finish({ timeout: true }), EXPORT_TIMEOUT_MS());
1901
+ try {
1902
+ worker = new Worker(new URL("./redline-worker.js", import.meta.url), { workerData: job });
1903
+ } catch (err) {
1904
+ return finish({ check_failed: String(err?.message || err) });
1905
+ }
1906
+ worker.once("message", finish);
1907
+ worker.once("error", (err) => finish({ check_failed: String(err?.message || err) }));
1908
+ worker.once("exit", (code) => finish({ check_failed: `the worker exited (${code})` }));
1909
+ });
1910
+ }