onionskin-cli 0.0.0-stage → 0.0.2

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 +144 -0
  2. package/INSTALL.md +25 -0
  3. package/LICENSE +21 -0
  4. package/NOTICE +49 -0
  5. package/README.md +148 -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 +67 -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 +288 -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 +1912 -0
  80. package/src/settings.js +161 -0
  81. package/src/setup.js +199 -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-BUtofdtr.js +197 -0
  116. package/web/dist/assets/index-Dfizlg0i.css +1 -0
  117. package/web/dist/index.html +14 -0
@@ -0,0 +1,593 @@
1
+ // Starts, restricts, supervises and stops one headless Claude Code agent per document: the "invisible" background agent that answers the
2
+ // person's Send when no agent of their own is listening. The agent runs the ordinary CLI (`onionskin poll`, `reply --file`, `status`) under
3
+ // the holder `onionskin-bg-<session key>`; the server treats it like any other agent, plus the guards in src/session.js and src/cli.js.
4
+ //
5
+ // Ownership: each agent is a detached process group (pgid = pid). Its record <state>/agents/<key>.json holds {pid, pgid, lstart, holder, key,
6
+ // cli, session_id}. A signal goes to the group only while `ps -o lstart=` of the pid still equals the recorded start time, so a pid the
7
+ // system reused is never signaled. A server that starts stops the groups its crashed predecessor left (reapOrphans).
8
+ //
9
+ // Lifecycle: started by an open from a person's terminal, by a Send that nobody took (at once for such a file, after a 20 s grace for any
10
+ // other), or by the page's Start button. Stopped on Close session, server stop, 20 minutes without a tab, or when an agent of the person's
11
+ // own polls the file (it supersedes the background one). A crash hands the batch back at once (Sessions.releaseAgent) and restarts with
12
+ // backoff 2, 4, 8, 16, 32 s, resuming the conversation; at most 5 starts per document per rolling hour. A sign-in, usage-limit or refusal
13
+ // failure never restarts by itself. At most 3 agents run at once (a ceiling, not a design limit: raise it when someone asks); a 4th waits.
14
+ //
15
+ // The stream (stream-json) is read line by line in memory for the page's activity list and kept as a private transcript
16
+ // <state>/agents/<key>/transcript.jsonl (0600). Close session removes the agent's folder and Claude Code's own copy of the conversation.
17
+ import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
18
+ import crypto from "node:crypto";
19
+ import fs from "node:fs";
20
+ import path from "node:path";
21
+ import { fileURLToPath } from "node:url";
22
+ import { env as cfg } from "./constants.js";
23
+ import { stateDir, sub, writeStateFile } from "./paths.js";
24
+ import * as settings from "./settings.js";
25
+ import { DEFAULT_MODEL, POLL_TIMEOUT, agentsDisabled, bgHolder, buildArgv, cleanEnv, findClaude, findCodex, isBgHolder, preflight } from "./agent-detect.js";
26
+ import { backgroundPrompt, readSkill, refDir } from "./agent-prompt.js";
27
+
28
+ const cliJs = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli.js");
29
+
30
+ // The stream parser (src/agent-events.js) is built alongside this file; until it is present, a minimal parser with the same exports keeps
31
+ // the runner working (session id, the final result, a sign-in or limit failure; no activity lines).
32
+ const fallbackEvents = {
33
+ parseLine(cli, line) {
34
+ let e;
35
+ try {
36
+ e = JSON.parse(line);
37
+ } catch {
38
+ return {};
39
+ }
40
+ const out = {};
41
+ if (typeof e?.session_id === "string") out.sessionId = e.session_id;
42
+ if (e?.type === "rate_limit_event" && e.rate_limit_info?.status === "rejected") out.failure = "limit";
43
+ if (e?.type === "assistant" && e.error === "authentication_failed") out.failure = "signed_out";
44
+ if (e?.type === "assistant" && (e.error === "rate_limit" || e.error === "billing_error")) out.failure = "limit";
45
+ if (e?.type === "result") out.result = { ok: e.is_error !== true, turnsExhausted: e.subtype === "error_max_turns", denials: Array.isArray(e.permission_denials) ? e.permission_denials.length : 0 };
46
+ return out;
47
+ },
48
+ classifyExit({ code = null, signal = null, sawResult = false, denials = 0, heldBatch = false, failure = null } = {}) {
49
+ if (failure === "signed_out" || failure === "limit") return failure;
50
+ if (denials > 0 && heldBatch) return "refused";
51
+ if (code === 0 && !signal && sawResult && !heldBatch) return null;
52
+ return "crashed";
53
+ },
54
+ };
55
+ const loadedEvents = await import("./agent-events.js").catch(() => fallbackEvents);
56
+
57
+ const HOUR = 60 * 60 * 1000;
58
+ export const LIMITS = { maxAgents: 3, startsPerHour: 5, graceMs: 20_000, idleMs: 20 * 60 * 1000, killMs: 4000, closeGraceMs: 10_000, activity: 50 };
59
+ const backoffMs = (n) => 1000 * 2 ** Math.min(Math.max(n, 1), 5); // 2, 4, 8, 16, 32 s
60
+
61
+ const agentsDir = () => sub("agents");
62
+ const recordFile = (key) => path.join(agentsDir(), `${key}.json`);
63
+
64
+ /**
65
+ * deps: {spawn, execFile, kill(pid, sig), now, setTimeout, env, events, tabs(key) -> number of open tabs, open(file) -> opens a .command
66
+ * file in Terminal, limits}. Everything that starts, signals or waits is injectable, so tests run with no process and a fake clock.
67
+ */
68
+ export function agentRunner(sessions, deps = {}) {
69
+ const spawn = deps.spawn || nodeSpawn;
70
+ const execFile = deps.execFile || nodeExecFile;
71
+ const kill = deps.kill || ((pid, sig) => process.kill(pid, sig));
72
+ const now = deps.now || Date.now;
73
+ const later = deps.setTimeout || setTimeout;
74
+ const env = deps.env || process.env;
75
+ const events = deps.events || loadedEvents;
76
+ const tabs = deps.tabs || (() => 0);
77
+ const L = { ...LIMITS, ...(deps.limits || {}) };
78
+ const entries = new Map(); // key -> entry
79
+ let stoppingAll = false;
80
+
81
+ const entry = (key) => {
82
+ let e = entries.get(key);
83
+ if (!e) {
84
+ e = { key, holder: bgHolder(key), child: null, state: "none", failure: null, activity: [], starts: [], crashes: 0, nextStartAt: 0, strandedAt: 0, idleSince: 0, waiting: false, external: false, sessionId: null, resumable: false, lastBatch: null };
85
+ entries.set(key, e);
86
+ }
87
+ return e;
88
+ };
89
+ const sessionOf = (key) => sessions.map.get(key) || null;
90
+ const notify = (key) => {
91
+ const s = sessionOf(key);
92
+ if (s) sessions.emit("change", s, "state");
93
+ };
94
+ const foreign = (s, holder) => !!s && (s.pollers.some((p) => p.holder !== holder) || (!!s.delivered && !s.delivered.local && s.delivered.lease.holder !== holder));
95
+ const holds = (s, holder) => !!s?.delivered && !s.delivered.local && s.delivered.lease.holder === holder;
96
+ const resident = () => [...entries.values()].filter((e) => e.child || e.state === "starting" && !e.waiting && !e.nextStartAt).length;
97
+ const fail = (e, code, extra = {}) => {
98
+ e.failure = { code, ...extra };
99
+ e.state = "failed";
100
+ e.waiting = false;
101
+ e.nextStartAt = 0;
102
+ notify(e.key);
103
+ };
104
+
105
+ // ---- process ownership --------------------------------------------------------------------------------
106
+ const lstartOf = (pid) =>
107
+ new Promise((resolve) => execFile("/bin/ps", ["-o", "lstart=", "-p", String(pid)], { timeout: 5000 }, (err, out) => resolve(err ? null : String(out).trim() || null)));
108
+
109
+ /** SIGTERM to the group, SIGKILL after 4 s; each only while the pid still started at `lstart`. Resolves after the first signal (or none). */
110
+ async function signalGroup(rec) {
111
+ if (!rec?.pgid || !rec.lstart || rec.pgid !== rec.pid) return false; // our agents lead their own group; any other record is not ours
112
+ if ((await lstartOf(rec.pid)) !== rec.lstart) return false;
113
+ try {
114
+ kill(-rec.pgid, "SIGTERM");
115
+ } catch {
116
+ return false;
117
+ }
118
+ const t = later(async () => {
119
+ if ((await lstartOf(rec.pid)) !== rec.lstart) return;
120
+ try {
121
+ kill(-rec.pgid, "SIGKILL");
122
+ } catch {}
123
+ }, L.killMs);
124
+ t?.unref?.();
125
+ return true;
126
+ }
127
+
128
+ /** Stops the groups a crashed server left behind (their records match a live pid and start time), and deletes every record. */
129
+ async function reapOrphans() {
130
+ let names = [];
131
+ try {
132
+ names = fs.readdirSync(agentsDir()).filter((n) => /^[0-9a-f]{16}\.json$/.test(n));
133
+ } catch {}
134
+ const out = [];
135
+ for (const n of names) {
136
+ let rec = null;
137
+ try {
138
+ rec = JSON.parse(fs.readFileSync(path.join(agentsDir(), n), "utf8"));
139
+ } catch {}
140
+ const stopped = rec ? await signalGroup(rec) : false;
141
+ out.push({ key: n.slice(0, -5), stopped });
142
+ fs.rmSync(path.join(agentsDir(), n), { force: true });
143
+ }
144
+ return out;
145
+ }
146
+
147
+ // ---- start ------------------------------------------------------------------------------------------------
148
+ /** One agent per document: does nothing when one runs, is starting, waits for a slot or backs off; never while another agent polls. */
149
+ function ensure(key, { now: immediate = false } = {}) {
150
+ if (agentsDisabled(env) || stoppingAll) return;
151
+ const s = sessionOf(key);
152
+ if (!s || s.closed) return;
153
+ const e = entry(key);
154
+ if (foreign(s, e.holder)) {
155
+ e.external = true;
156
+ notify(key);
157
+ return;
158
+ }
159
+ e.external = false;
160
+ if (e.child || e.launching || (e.state === "failed" && !immediate)) return;
161
+ if (e.nextStartAt && !immediate) return; // a restart is already scheduled
162
+ e.nextStartAt = 0;
163
+ e.state = "starting";
164
+ if (resident() > L.maxAgents) {
165
+ e.waiting = true; // started by tick() when a slot frees
166
+ notify(key);
167
+ return;
168
+ }
169
+ e.waiting = false;
170
+ launch(e, { counted: true });
171
+ }
172
+
173
+ async function launch(e, { counted, resume = false }) {
174
+ const s = sessionOf(e.key);
175
+ if (!s || s.closed) {
176
+ e.state = "none";
177
+ return;
178
+ }
179
+ e.launching = true;
180
+ e.state = "starting";
181
+ e.failure = null;
182
+ notify(e.key);
183
+ try {
184
+ if (counted) {
185
+ e.starts = e.starts.filter((t) => now() - t < HOUR);
186
+ if (e.starts.length >= L.startsPerHour) return fail(e, "too_many_restarts");
187
+ e.starts.push(now());
188
+ }
189
+ const bin = findClaude(env);
190
+ if (!bin) return fail(e, "not_installed", findCodex(env) ? { codex: true } : {});
191
+ const workDir = ensureWorkDir(e.key);
192
+ const binDir = ensureBin();
193
+ const childEnv = cleanEnv({ binDir, stateDir: fs.realpathSync(stateDir()), holder: e.holder, workDir, env });
194
+ const pre = await preflight(bin, { env: childEnv, execFile });
195
+ if (pre) return fail(e, pre.code, pre.update ? { update: true } : {});
196
+ if (!sessionOf(e.key) || sessionOf(e.key).closed || stoppingAll) {
197
+ e.state = "none";
198
+ return;
199
+ }
200
+ if (foreign(sessionOf(e.key), e.holder)) {
201
+ e.external = true;
202
+ e.state = "none";
203
+ return notify(e.key);
204
+ }
205
+ if (!resume || !e.sessionId) e.sessionId = crypto.randomUUID();
206
+ const model = settings.readSettings?.().agent?.model || DEFAULT_MODEL;
207
+ const argv = buildArgv({ prompt: backgroundPrompt({ file: s.file, workDir, timeout: POLL_TIMEOUT }), skill: readSkill(), model, sessionId: e.sessionId, resume: resume && e.resumable, workDir, refDir: refDir() });
208
+ const child = spawn(bin, argv, { cwd: workDir, env: childEnv, stdio: ["ignore", "pipe", "pipe"], detached: true });
209
+ attach(e, child, workDir, { resumed: resume && e.resumable });
210
+ } catch (err) {
211
+ fail(e, "crashed");
212
+ } finally {
213
+ e.launching = false;
214
+ }
215
+ }
216
+
217
+ function ensureWorkDir(key) {
218
+ const dir = path.join(agentsDir(), key);
219
+ fs.mkdirSync(path.join(dir, "outline"), { recursive: true, mode: 0o700 }); // the outline files the session writes, the one folder it may read
220
+ fs.chmodSync(dir, 0o700);
221
+ fs.chmodSync(path.join(dir, "outline"), 0o700);
222
+ return fs.realpathSync(dir); // a real path: --restricted compares paths literally
223
+ }
224
+
225
+ /** <state>/agents/bin/onionskin runs exactly this server's CLI, whatever `onionskin` is on the person's PATH. */
226
+ function ensureBin() {
227
+ const dir = path.join(agentsDir(), "bin");
228
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
229
+ const q = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
230
+ const body = `#!/bin/sh\nexec ${q(process.execPath)} ${q(cliJs)} "$@"\n`;
231
+ const f = path.join(dir, "onionskin");
232
+ let cur = null;
233
+ try {
234
+ cur = fs.readFileSync(f, "utf8");
235
+ } catch {}
236
+ if (cur !== body) {
237
+ writeStateFile(f, body);
238
+ fs.chmodSync(f, 0o700);
239
+ }
240
+ return fs.realpathSync(dir);
241
+ }
242
+
243
+ function attach(e, child, workDir, { resumed = false } = {}) {
244
+ e.child = child;
245
+ e.spawned = true;
246
+ e.run = { sawResult: false, denials: 0, failure: null, resetsAt: null, turnsExhausted: false, lines: 0, resumed };
247
+ e.idleSince = 0;
248
+ const rec = { pid: child.pid, pgid: child.pid, lstart: null, holder: e.holder, key: e.key, cli: "claude", session_id: e.sessionId };
249
+ e.record = rec;
250
+ const saveRec = () => {
251
+ try {
252
+ writeStateFile(recordFile(e.key), JSON.stringify(rec));
253
+ } catch {}
254
+ };
255
+ saveRec();
256
+ e.lstartReady = lstartOf(child.pid).then((l) => {
257
+ rec.lstart = l;
258
+ if (e.child === child) saveRec();
259
+ });
260
+ let transcript = null;
261
+ try {
262
+ transcript = fs.openSync(path.join(workDir, "transcript.jsonl"), "a", 0o600);
263
+ } catch {}
264
+ let buf = "";
265
+ child.stdout?.on("data", (d) => {
266
+ if (transcript !== null) {
267
+ try {
268
+ fs.writeSync(transcript, d);
269
+ } catch {}
270
+ }
271
+ buf += d.toString("utf8");
272
+ let i;
273
+ while ((i = buf.indexOf("\n")) >= 0) {
274
+ const line = buf.slice(0, i);
275
+ buf = buf.slice(i + 1);
276
+ onLine(e, line);
277
+ }
278
+ });
279
+ child.stderr?.on("data", () => {}); // drained; Claude Code writes nothing there that the page needs
280
+ child.on("error", () => {});
281
+ child.on("exit", (code, signal) => {
282
+ if (transcript !== null) {
283
+ try {
284
+ fs.closeSync(transcript);
285
+ } catch {}
286
+ }
287
+ if (buf) onLine(e, buf);
288
+ if (e.child === child) onExit(e, code, signal);
289
+ });
290
+ e.state = "starting";
291
+ notify(e.key);
292
+ }
293
+
294
+ function onLine(e, line) {
295
+ if (!line.trim()) return;
296
+ e.run.lines++;
297
+ const r = events.parseLine("claude", line) || {};
298
+ if (r.sessionId) e.resumable = true; // the conversation exists on disk: a restart can resume it
299
+ if (r.failure) {
300
+ e.run.failure = r.failure;
301
+ if (r.resetsAt) e.run.resetsAt = r.resetsAt;
302
+ }
303
+ if (r.result) {
304
+ e.run.sawResult = true;
305
+ e.run.denials += r.result.denials || 0;
306
+ e.run.turnsExhausted = !!r.result.turnsExhausted;
307
+ }
308
+ if (r.activity) {
309
+ e.activity.push({ at: now(), text: r.activity });
310
+ if (e.activity.length > L.activity) e.activity.splice(0, e.activity.length - L.activity);
311
+ notify(e.key);
312
+ }
313
+ }
314
+
315
+ function onExit(e, code, signal) {
316
+ e.child = null;
317
+ fs.rmSync(recordFile(e.key), { force: true });
318
+ const s = sessionOf(e.key);
319
+ // its `onionskin poll` child may outlive it (same group, still connected): that poll is answered closed, so a Send never goes to nobody
320
+ if (s) {
321
+ const mine = s.pollers.filter((p) => p.holder === e.holder);
322
+ if (mine.length) {
323
+ s.pollers.splice(0, s.pollers.length, ...s.pollers.filter((p) => p.holder !== e.holder));
324
+ for (const p of mine) p.resolve({ status: "closed", reason: "the agent was stopped" });
325
+ }
326
+ }
327
+ const held = holds(s, e.holder);
328
+ if (held && !s.closed) {
329
+ try {
330
+ sessions.releaseAgent(e.key, e.holder); // the page unlocks now, not after the 15-minute lease
331
+ } catch {}
332
+ }
333
+ const why = e.stopping;
334
+ e.stopping = null;
335
+ if (e.cleanupOnExit) {
336
+ e.cleanupOnExit = false;
337
+ cleanup(e.key);
338
+ }
339
+ if (why) {
340
+ e.state = why === "handover" ? "handover" : "none";
341
+ startWaiting();
342
+ return notify(e.key);
343
+ }
344
+ if (!s || s.closed || e.external || stoppingAll) {
345
+ e.state = "none";
346
+ startWaiting();
347
+ return notify(e.key);
348
+ }
349
+ if (e.run.turnsExhausted) {
350
+ // the turn cap of one process: a fresh conversation, not a crash, and it does not count toward the hourly cap
351
+ e.resumable = false;
352
+ e.sessionId = null;
353
+ launch(e, { counted: false });
354
+ return;
355
+ }
356
+ const code2 = events.classifyExit({ code, signal, sawResult: e.run.sawResult, denials: e.run.denials, heldBatch: held, failure: e.run.failure });
357
+ if (code2 === "signed_out" || code2 === "limit" || code2 === "refused") {
358
+ fail(e, code2, code2 === "limit" && e.run.resetsAt ? { resetsAt: e.run.resetsAt } : {});
359
+ return startWaiting();
360
+ }
361
+ // crashed, or ended its turn on its own while it should keep listening: restart with backoff, resuming the conversation
362
+ if (e.run.resumed && !e.run.lines) e.resumable = false; // the resume itself failed (no stream at all): the next start is a fresh conversation
363
+ e.crashes++;
364
+ e.nextStartAt = now() + backoffMs(e.crashes);
365
+ e.state = "starting";
366
+ notify(e.key);
367
+ startWaiting();
368
+ }
369
+
370
+ function startWaiting() {
371
+ for (const w of entries.values()) {
372
+ if (!w.waiting || resident() >= L.maxAgents) continue;
373
+ w.waiting = false;
374
+ launch(w, { counted: true });
375
+ }
376
+ }
377
+
378
+ // ---- stop -------------------------------------------------------------------------------------------------
379
+ /** Stops this document's agent (`why`: closed, stop, idle, superseded, handover, shutdown). Resolves once the first signal went out. */
380
+ async function stop(key, why = "stop") {
381
+ const e = entries.get(key);
382
+ if (!e) return false;
383
+ e.waiting = false;
384
+ e.nextStartAt = 0;
385
+ e.strandedAt = 0;
386
+ if (!e.child) {
387
+ if (why !== "superseded") e.state = why === "handover" ? "handover" : "none";
388
+ notify(key);
389
+ return false;
390
+ }
391
+ e.stopping = why;
392
+ await e.lstartReady;
393
+ return signalGroup(e.record);
394
+ }
395
+
396
+ /** Server shutdown: every agent's group is signaled; resolves when they all exited or after the kill delay. */
397
+ async function stopAll() {
398
+ stoppingAll = true;
399
+ const live = [...entries.values()].filter((e) => e.child);
400
+ const exits = live.map((e) => new Promise((r) => (e.child.once("exit", r), later(r, L.killMs + 500)?.unref?.())));
401
+ await Promise.all(live.map((e) => stop(e.key, "shutdown")));
402
+ await Promise.all(exits);
403
+ }
404
+
405
+ // ---- what the server tells it ------------------------------------------------------------------------------
406
+ sessions.on("stranded", (s) => {
407
+ const e = entry(s.key);
408
+ if (e.state === "handover") e.state = "none"; // the Terminal session ended: the background agent may start again
409
+ if (s.openedFor === "background") return ensure(s.key);
410
+ if (!e.strandedAt) e.strandedAt = now(); // someone's own agent may be between two polls: wait the grace first (tick)
411
+ });
412
+ sessions.on("superseded", (s, holder) => {
413
+ if (holder !== bgHolder(s.key)) return;
414
+ const e = entry(s.key);
415
+ e.external = true;
416
+ stop(s.key, "superseded");
417
+ notify(s.key);
418
+ });
419
+ sessions.on("closed", (s) => {
420
+ const e = entries.get(s.key);
421
+ if (e?.child) {
422
+ // its poll was answered "closed", so it ends by itself (and writes its last result); the group is stopped only if it has not after 10 s.
423
+ // The cleanup runs after the process is gone, so nothing writes into the folder again.
424
+ const child = e.child;
425
+ e.cleanupOnExit = true;
426
+ e.stopping = "closed";
427
+ e.waiting = false;
428
+ e.nextStartAt = 0;
429
+ later(() => e.child === child && stop(s.key, "closed"), L.closeGraceMs)?.unref?.();
430
+ } else cleanup(s.key);
431
+ });
432
+ sessions.on("change", (s) => {
433
+ const e = entries.get(s.key);
434
+ if (!e) return;
435
+ // a new delivery to this agent: older reply files are not needed any more (each batch writes a new one)
436
+ const id = holds(s, e.holder) ? s.delivered.batch.batch_id : null;
437
+ if (id && id !== e.lastBatch) {
438
+ e.lastBatch = id;
439
+ e.crashes = 0; // it got as far as a batch: the next crash backs off from the start again
440
+ try {
441
+ const dir = path.join(agentsDir(), s.key);
442
+ for (const n of fs.readdirSync(dir)) if (/^reply-.*\.json$/.test(n) && n !== `reply-${id}.json`) fs.rmSync(path.join(dir, n), { force: true });
443
+ } catch {}
444
+ }
445
+ });
446
+
447
+ /** Close session: the agent's folder (transcript, reply files) and Claude Code's own copy of the conversation are removed. */
448
+ function cleanup(key) {
449
+ const e = entries.get(key);
450
+ const dir = path.join(agentsDir(), key);
451
+ let real = null;
452
+ try {
453
+ real = fs.realpathSync(dir);
454
+ } catch {}
455
+ fs.rmSync(dir, { recursive: true, force: true });
456
+ if (e) {
457
+ e.activity = [];
458
+ e.sessionId = null;
459
+ e.resumable = false;
460
+ }
461
+ // also when this runner never started it (the server restarted since): Claude Code's copy of that conversation goes too
462
+ const bin = real && !agentsDisabled(env) ? findClaude(env) : null;
463
+ if (bin) execFile(bin, ["purge", real, "--yes"], { env: cleanEnv({ binDir: path.join(agentsDir(), "bin"), stateDir: stateDir(), holder: bgHolder(key), workDir: real, env }), timeout: 15000 }, () => {});
464
+ }
465
+
466
+ /** Called every server tick: the stranded grace, the backoff, the slot queue, the idle stop. */
467
+ function tick() {
468
+ for (const e of entries.values()) {
469
+ const s = sessionOf(e.key);
470
+ if (!s) continue;
471
+ if (e.strandedAt) {
472
+ if (s.pollers.length || sessions.state(s) !== "stranded") e.strandedAt = 0;
473
+ else if (now() - e.strandedAt >= L.graceMs) {
474
+ e.strandedAt = 0;
475
+ ensure(e.key);
476
+ }
477
+ }
478
+ if (e.nextStartAt && now() >= e.nextStartAt && !e.child) {
479
+ e.nextStartAt = 0;
480
+ if (foreign(s, e.holder) || s.closed) {
481
+ e.state = "none";
482
+ notify(e.key);
483
+ } else launch(e, { counted: true, resume: true });
484
+ }
485
+ if (e.child) {
486
+ if (tabs(e.key) > 0 || holds(s, e.holder)) e.idleSince = 0;
487
+ else if (!e.idleSince) e.idleSince = now();
488
+ else if (now() - e.idleSince >= L.idleMs) stop(e.key, "idle");
489
+ }
490
+ }
491
+ startWaiting();
492
+ }
493
+
494
+ /** The page's buttons (POST /api/agent). Returns nothing; the session view carries the result. */
495
+ async function action(key, { action: a, on, cli }) {
496
+ const s = sessions.get(key);
497
+ if (a === "start") {
498
+ const e = entry(key);
499
+ e.failure = null;
500
+ e.starts = []; // Try again: the person asked, so the hourly window starts over
501
+ e.crashes = 0;
502
+ if (e.state === "failed" || e.state === "handover") e.state = "none";
503
+ if (agentsDisabled(env)) return;
504
+ return ensure(key, { now: true });
505
+ }
506
+ if (a === "stop") return stop(key, "stop");
507
+ if (a === "use") {
508
+ settings.writeAgent?.({ cli });
509
+ return;
510
+ }
511
+ if (a === "show") {
512
+ settings.writeAgent?.({ show: on });
513
+ return notify(key);
514
+ }
515
+ if (a === "terminal") return handover(s);
516
+ }
517
+
518
+ /** Open in Terminal: the background agent stops and the same conversation opens in Terminal with the same limits. */
519
+ async function handover(s) {
520
+ const e = entry(s.key);
521
+ const bin = findClaude(env);
522
+ if (!bin || agentsDisabled(env)) return fail(e, "not_installed");
523
+ if (e.state === "failed" && e.failure?.code === "signed_out") return signIn(e, bin);
524
+ // the background process is gone before Terminal opens the same conversation (two processes never share one), at most 5 s
525
+ const gone = e.child ? new Promise((r) => (e.child.once("exit", r), later(r, L.killMs + 1000)?.unref?.())) : null;
526
+ await stop(s.key, "handover");
527
+ if (gone) await gone;
528
+ e.state = "handover";
529
+ const workDir = ensureWorkDir(s.key);
530
+ const binDir = ensureBin();
531
+ const holder = `onionskin-term-${s.key}`; // a foreign holder: the runner stays down while it polls
532
+ const childEnv = cleanEnv({ binDir, stateDir: fs.realpathSync(stateDir()), holder, workDir, env });
533
+ const resume = !!(e.sessionId && e.resumable);
534
+ if (!resume) e.sessionId = crypto.randomUUID();
535
+ const model = settings.readSettings?.().agent?.model || DEFAULT_MODEL;
536
+ const argv = buildArgv({ skill: readSkill(), model, sessionId: e.sessionId, resume, workDir, refDir: refDir(), print: false });
537
+ const q = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
538
+ const f = path.join(workDir, "open-agent.command");
539
+ writeStateFile(f, `#!/bin/sh\ncd ${q(workDir)} || exit 1\nexec /usr/bin/env -i ${Object.entries(childEnv).map(([k, v]) => q(`${k}=${v}`)).join(" ")} ${q(bin)} ${argv.map(q).join(" ")}\n`);
540
+ fs.chmodSync(f, 0o700);
541
+ (deps.open || openInTerminal)(f);
542
+ notify(s.key);
543
+ }
544
+
545
+ /** "Open Terminal to sign in": a Terminal window runs `claude auth login` (no agent, no conversation, no key); the page keeps Try again. */
546
+ function signIn(e, bin) {
547
+ const q = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
548
+ const dir = ensureWorkDir(e.key);
549
+ const vars = { HOME: env.HOME || "", USER: env.USER || "", LANG: "en_US.UTF-8", PATH: "/usr/bin:/bin" };
550
+ const f = path.join(dir, "sign-in.command");
551
+ writeStateFile(f, `#!/bin/sh\nexec /usr/bin/env -i ${Object.entries(vars).map(([k, v]) => q(`${k}=${v}`)).join(" ")} ${q(bin)} 'auth' 'login'\n`);
552
+ fs.chmodSync(f, 0o700);
553
+ (deps.open || openInTerminal)(f);
554
+ notify(e.key);
555
+ }
556
+
557
+ function openInTerminal(f) {
558
+ const stub = cfg("OPEN_STUB"); // tests: record the path instead of opening Terminal
559
+ if (stub) return fs.appendFileSync(stub, `${f}\n`);
560
+ execFile("/usr/bin/open", ["-a", "Terminal", f], () => {});
561
+ }
562
+
563
+ /** What the page sees (docs/contracts/routes.md, the `agent` field of the session). */
564
+ function viewFor(key) {
565
+ const s = sessionOf(key);
566
+ const e = entries.get(key);
567
+ let show = false;
568
+ try {
569
+ show = settings.readSettings?.().agent?.show === true;
570
+ } catch {}
571
+ const base = { cli: e ? "claude" : null, show, activity: e ? e.activity.slice() : [], failure: e?.failure ? { ...e.failure } : null };
572
+ let state = "none";
573
+ if (e?.state === "failed") state = "failed";
574
+ else if (e?.state === "handover") state = "handover";
575
+ else if (s && foreign(s, bgHolder(key))) state = "external";
576
+ else if (e?.child) state = holds(s, e.holder) ? "working" : s?.pollers.some((p) => p.holder === e.holder) ? "ready" : "starting";
577
+ else if (e && (e.launching || e.waiting || e.nextStartAt || e.state === "starting")) state = "starting";
578
+ if (state !== "failed") base.failure = null;
579
+ // waiting for one of the agent slots (LIMITS.maxAgents): the page adds "Another document's agent is busy."
580
+ return state === "starting" && e?.waiting ? { state, ...base, busy: true } : { state, ...base };
581
+ }
582
+
583
+ /**
584
+ * False when this runner started an agent for the file and no process of it runs now: src/session.js answers such a background poll
585
+ * "closed" (a poll child that outlived its agent). A file this runner never started an agent for is left to the other guards.
586
+ */
587
+ const alive = (key) => {
588
+ const e = entries.get(key);
589
+ return !e?.spawned || !!e.child;
590
+ };
591
+
592
+ return { ensure, stop, stopAll, reapOrphans, viewFor, handover, tick, action, alive, isBgHolder, entries };
593
+ }
package/src/analyze.js ADDED
@@ -0,0 +1,17 @@
1
+ import { changedRegions } from "./anchors.js";
2
+ import { checkPackages } from "./package.js";
3
+
4
+ /**
5
+ * What `done` learns from the before and after bytes: package checks (Node always, the deeper Python/LibreOffice check when set up) and the
6
+ * changed regions. Pure and synchronous, so the server can run it in a worker thread (src/offload.js) and keep answering while it works.
7
+ */
8
+ export function analyze(pre, post, format, opts = {}) {
9
+ const { flags, checks } = checkPackages(pre, post, format, opts);
10
+ let changes = null;
11
+ try {
12
+ changes = changedRegions(format, pre, post);
13
+ } catch {
14
+ changes = null; // unreadable: say nothing rather than guess
15
+ }
16
+ return { flags, checks, changes };
17
+ }