@ulm0/gonogo 0.0.0-stage → 0.1.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 (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +30 -2
  3. package/bin/gonogo.js +18 -0
  4. package/dist/client/THIRD-PARTY-NOTICES.md +409 -0
  5. package/dist/client/apple-touch-icon.png +0 -0
  6. package/dist/client/assets/doto-latin-900-normal-D1bF_x6I.woff +0 -0
  7. package/dist/client/assets/geist-latin-400-normal-B40WzpMT.woff2 +0 -0
  8. package/dist/client/assets/geist-latin-400-normal-akEymXtG.woff +0 -0
  9. package/dist/client/assets/geist-latin-500-normal-BDXIbFrL.woff +0 -0
  10. package/dist/client/assets/geist-latin-500-normal-CTWBw9NS.woff2 +0 -0
  11. package/dist/client/assets/geist-latin-600-normal-CSETrqM2.woff2 +0 -0
  12. package/dist/client/assets/geist-latin-600-normal-DsPlZH-9.woff +0 -0
  13. package/dist/client/assets/geist-mono-latin-400-normal-B2yvC1Cq.woff +0 -0
  14. package/dist/client/assets/geist-mono-latin-400-normal-DTRLJnHl.woff2 +0 -0
  15. package/dist/client/assets/geist-mono-latin-500-normal-D-GG86Jb.woff +0 -0
  16. package/dist/client/assets/geist-mono-latin-500-normal-YINYabwD.woff2 +0 -0
  17. package/dist/client/assets/geist-mono-latin-600-normal-V-KvD_pi.woff2 +0 -0
  18. package/dist/client/assets/geist-mono-latin-600-normal-bZn07FKM.woff +0 -0
  19. package/dist/client/assets/index-B6MsSoeo.css +1 -0
  20. package/dist/client/assets/index-DRtiRh1Y.js +31 -0
  21. package/dist/client/favicon.ico +0 -0
  22. package/dist/client/favicon.svg +1 -0
  23. package/dist/client/index.html +19 -0
  24. package/dist/server/cleanroom.js +214 -0
  25. package/dist/server/cli.js +630 -0
  26. package/dist/server/command.js +44 -0
  27. package/dist/server/constants.js +427 -0
  28. package/dist/server/docking.js +541 -0
  29. package/dist/server/downlink.js +191 -0
  30. package/dist/server/home.js +497 -0
  31. package/dist/server/hooks.js +166 -0
  32. package/dist/server/hub.js +2484 -0
  33. package/dist/server/launcher.js +542 -0
  34. package/dist/server/livery.js +210 -0
  35. package/dist/server/logsearch.js +112 -0
  36. package/dist/server/mcp.js +196 -0
  37. package/dist/server/migrate.js +119 -0
  38. package/dist/server/missionlog.js +209 -0
  39. package/dist/server/payload.js +168 -0
  40. package/dist/server/propellant.js +314 -0
  41. package/dist/server/providers.js +137 -0
  42. package/dist/server/relay.js +300 -0
  43. package/dist/server/relaykinds.js +182 -0
  44. package/dist/server/schedules.js +277 -0
  45. package/dist/server/tasks.js +272 -0
  46. package/dist/server/terminal.js +635 -0
  47. package/dist/server/uplinks.js +356 -0
  48. package/dist/server/web.js +1466 -0
  49. package/dist/shared/cron.js +149 -0
  50. package/dist/shared/fuel.js +18 -0
  51. package/dist/shared/livery.js +348 -0
  52. package/dist/shared/positions.js +132 -0
  53. package/dist/shared/protocol.js +212 -0
  54. package/package.json +84 -3
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Downlink: the Director's inbox (docs/downlink-spec.md).
3
+ *
4
+ * Two kinds of item: every message to "user" (the server keeps a copy of the newest DOWNLINK_MAIL_MAX, found again in
5
+ * messages.jsonl at start) and the events other parts of the server post (a Redline trip, a T-minus result, a failed Launch
6
+ * Window, an Uplink that was refused too often, a task an agent moved to blocked or review). downlink.json keeps the events
7
+ * with their text and one flag per item id, `read` or `archived` (archived is read too); no flag is unread. So phone and
8
+ * desktop agree: the browsers only show what the server says. The clock is injected for tests.
9
+ *
10
+ * shortcut: a message leaves the inbox when DOWNLINK_MAIL_MAX newer ones came (it stays in messages.jsonl), and the whole
11
+ * inbox is in every frame and every snapshot (at the limits that is about 700 KB); send only the changes if that ever hurts.
12
+ */
13
+ import { randomBytes } from 'node:crypto';
14
+ import { readFile, rename, writeFile } from 'node:fs/promises';
15
+ import { join } from 'node:path';
16
+ import { ACTIVITY_WIRE_BODY_CHARS, DOWNLINK_EVENT_KINDS } from '../shared/protocol.js';
17
+ import { DOWNLINK_EVENTS_MAX, DOWNLINK_FILE, DOWNLINK_IDS_MAX, DOWNLINK_MAIL_MAX, DOWNLINK_TEXT_MAX_CHARS, FILE_MODE } from './constants.js';
18
+ import { isRecord } from './hooks.js';
19
+ import { cutText, HubError } from './hub.js';
20
+ const ID_RE = /^[me][1-9]\d{0,9}$/;
21
+ const EVENT_ID_RE = /^e[1-9]\d{0,9}$/;
22
+ // C0, DEL, C1 and bidi controls: an event text comes from agents and must stay one clean line.
23
+ const UNSAFE_IN_TEXT = /[\u0000-\u001f\u007f-\u009f‎‏‪-‮⁦-⁩]/g;
24
+ const bad = (message, field) => new HubError('bad_request', message, field);
25
+ function idsOf(input) {
26
+ if (!isRecord(input))
27
+ throw bad('request body must be a JSON object');
28
+ for (const key of Object.keys(input))
29
+ if (key !== 'ids')
30
+ throw bad(`unknown field "${key}"`, key);
31
+ const ids = input.ids;
32
+ if (!Array.isArray(ids) || ids.length === 0 || ids.length > DOWNLINK_IDS_MAX || !ids.every((id) => typeof id === 'string' && ID_RE.test(id))) {
33
+ throw bad(`ids must be a list of 1 to ${DOWNLINK_IDS_MAX} item ids`, 'ids');
34
+ }
35
+ return ids;
36
+ }
37
+ export function createDownlink(options) {
38
+ const { dir, now, log } = options;
39
+ const path = join(dir, DOWNLINK_FILE);
40
+ /** Both lists are oldest first. */
41
+ let mail = [];
42
+ let events = [];
43
+ /** No entry is unread. */
44
+ const flags = new Map();
45
+ let seq = 0;
46
+ let chain = Promise.resolve();
47
+ const later = (fn) => {
48
+ const run = chain.then(fn);
49
+ chain = run.catch((error) => log.error('downlink could not write', error));
50
+ return run.then(() => undefined);
51
+ };
52
+ const save = () => {
53
+ // the mail is not stored: messages.jsonl has it, the file keeps what the Director did with it
54
+ const json = JSON.stringify({ version: 1, seq, events, flags: Object.fromEntries(flags) }, null, 2);
55
+ return later(async () => {
56
+ const tmp = join(dir, `.${DOWNLINK_FILE}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
57
+ await writeFile(tmp, json, { mode: FILE_MODE, flag: 'wx' });
58
+ await rename(tmp, path);
59
+ });
60
+ };
61
+ const view = () => {
62
+ const marks = (id) => ({ read: flags.has(id), archived: flags.get(id) === 'archived' });
63
+ // newest first: the lists are read from their ends, so that the sort (it is stable) leaves the later of two items of one millisecond first
64
+ const items = [
65
+ ...mail.map((m) => ({ ...m, type: 'message', ...marks(m.id) })).reverse(),
66
+ ...events.map((e) => ({ ...e, type: 'event', ...marks(e.id) })).reverse(),
67
+ ];
68
+ items.sort((a, b) => b.at - a.at);
69
+ return { unread: items.filter((item) => !item.read).length, items };
70
+ };
71
+ /** Tells the browsers and saves; a failed save is logged by `later`, so a caller that does not wait may ignore it. */
72
+ const changed = () => {
73
+ options.emit(view());
74
+ return save();
75
+ };
76
+ const addMail = (record) => {
77
+ if (mail.some((m) => m.id === record.id))
78
+ return false;
79
+ mail.push(record);
80
+ for (const old of mail.splice(0, Math.max(0, mail.length - DOWNLINK_MAIL_MAX)))
81
+ flags.delete(old.id);
82
+ return true;
83
+ };
84
+ /** A record of the log, or an activity item whose body the hub cut already (`truncated`). */
85
+ const toMail = (r) => {
86
+ const body = cutText(r.body, ACTIVITY_WIRE_BODY_CHARS);
87
+ return { id: r.id, at: r.at, from: r.from, subject: r.subject, body, truncated: r.truncated === true || body.length < r.body.length, inReplyTo: r.inReplyTo };
88
+ };
89
+ const setFlag = async (flag, input) => {
90
+ const ids = idsOf(input);
91
+ const held = new Set([...mail, ...events].map((item) => item.id));
92
+ let any = false;
93
+ for (const id of ids) {
94
+ if (!held.has(id) || flags.get(id) === 'archived' || flags.get(id) === flag)
95
+ continue;
96
+ flags.set(id, flag);
97
+ any = true;
98
+ }
99
+ if (any)
100
+ await changed();
101
+ return view();
102
+ };
103
+ return {
104
+ async load() {
105
+ let saved = null;
106
+ let fresh = false;
107
+ try {
108
+ saved = JSON.parse(await readFile(path, 'utf8'));
109
+ if (!isRecord(saved) || saved.version !== 1 || !Array.isArray(saved.events) || !isRecord(saved.flags))
110
+ throw new Error('not a version 1 downlink file');
111
+ }
112
+ catch (error) {
113
+ saved = null;
114
+ fresh = true;
115
+ if (error.code !== 'ENOENT') {
116
+ // kept aside, so that the next save cannot overwrite what the Director marked
117
+ log.error(`${DOWNLINK_FILE} could not be read; the inbox starts empty and the file is kept as ${DOWNLINK_FILE}.bad`, error instanceof SyntaxError ? 'not valid JSON' : error);
118
+ await rename(path, `${path}.bad`).catch(() => undefined);
119
+ }
120
+ }
121
+ if (isRecord(saved)) {
122
+ if (typeof saved.seq === 'number' && Number.isSafeInteger(saved.seq) && saved.seq > 0)
123
+ seq = saved.seq;
124
+ for (const raw of Array.isArray(saved.events) ? saved.events : []) {
125
+ const { id, at, kind, text } = isRecord(raw) ? raw : {};
126
+ if (typeof id !== 'string' ||
127
+ !EVENT_ID_RE.test(id) ||
128
+ typeof at !== 'number' ||
129
+ typeof text !== 'string' ||
130
+ !DOWNLINK_EVENT_KINDS.includes(kind) ||
131
+ events.some((e) => e.id === id)) {
132
+ log.warn(`${DOWNLINK_FILE}: an event was skipped`);
133
+ continue;
134
+ }
135
+ events.push({ id, at, kind: kind, text: cutText(text, DOWNLINK_TEXT_MAX_CHARS) });
136
+ seq = Math.max(seq, Number(id.slice(1)));
137
+ }
138
+ events = events.slice(-DOWNLINK_EVENTS_MAX);
139
+ }
140
+ for (const record of options.history())
141
+ if (record.to === 'user')
142
+ addMail(toMail(record));
143
+ if (isRecord(saved) && isRecord(saved.flags)) {
144
+ const held = new Set([...mail, ...events].map((item) => item.id));
145
+ for (const [id, flag] of Object.entries(saved.flags))
146
+ if (held.has(id) && (flag === 'read' || flag === 'archived'))
147
+ flags.set(id, flag);
148
+ }
149
+ if (fresh && mail.length > 0) {
150
+ // the first run: the mail that is already there was seen in the comm loop, so the badge does not start at 200
151
+ for (const m of mail)
152
+ flags.set(m.id, 'read');
153
+ await save();
154
+ }
155
+ },
156
+ view,
157
+ post(kind, text) {
158
+ const line = cutText(text.replace(UNSAFE_IN_TEXT, ' ').replace(/\s+/g, ' ').trim(), DOWNLINK_TEXT_MAX_CHARS);
159
+ if (line === '')
160
+ return;
161
+ seq += 1;
162
+ events.push({ id: `e${seq}`, at: now(), kind, text: line });
163
+ for (const old of events.splice(0, Math.max(0, events.length - DOWNLINK_EVENTS_MAX)))
164
+ flags.delete(old.id);
165
+ void changed().catch(() => undefined);
166
+ },
167
+ observe(event) {
168
+ if (event.t !== 'activity' || event.item.to !== 'user')
169
+ return;
170
+ if (addMail(toMail(event.item)))
171
+ options.emit(view());
172
+ },
173
+ read: (input) => setFlag('read', input),
174
+ archive: (input) => setFlag('archived', input),
175
+ async readAll() {
176
+ let any = false;
177
+ for (const item of [...mail, ...events]) {
178
+ if (flags.has(item.id))
179
+ continue;
180
+ flags.set(item.id, 'read');
181
+ any = true;
182
+ }
183
+ if (any)
184
+ await changed();
185
+ return view();
186
+ },
187
+ close() {
188
+ return chain.then(() => undefined);
189
+ },
190
+ };
191
+ }
@@ -0,0 +1,497 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
3
+ import { appendFile, rename, unlink, writeFile } from 'node:fs/promises';
4
+ import { join, resolve } from 'node:path';
5
+ import { POSITION_IDS } from '../shared/positions.js';
6
+ import { ACTIVITY_STATUSES, PERMISSION_MODES, PROVIDERS, RESERVED_NAMES } from '../shared/protocol.js';
7
+ import { AGENT_NAME_PATTERN, AGENTS_DIR, AGENTS_FILE, BROWSER_TOKEN_FILE, COMMAND_MAX_CHARS, DIR_MODE, FILE_MODE, LOCK_FILE, MESSAGES_FILE, MESSAGES_ROTATE_BYTES, MESSAGES_ROTATED_FILE, MESSAGES_TAIL_BYTES, TOKEN_BYTES, nullLogger, } from './constants.js';
8
+ import { readCustomCommand } from './command.js';
9
+ import { migrateHome } from './migrate.js';
10
+ import { parseCleanRoom } from './cleanroom.js';
11
+ import { parsePayload, payloadRefusal } from './payload.js';
12
+ const NAME_RE = new RegExp(AGENT_NAME_PATTERN);
13
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
14
+ const TOKEN_RE = /^[0-9a-f]{64}$/i;
15
+ const MESSAGE_ID_RE = /^m(\d+)$/;
16
+ const LOCK_ATTEMPTS = 5;
17
+ /**
18
+ * Directories this process holds a lock on. A pid in a lock file can name this very process (containers reuse pids), so
19
+ * the file alone cannot tell "my own lock" from "the lock of a previous run that had my pid".
20
+ */
21
+ const heldDirs = new Set();
22
+ function errMessage(e) {
23
+ return e instanceof Error ? e.message : String(e);
24
+ }
25
+ function errCode(e) {
26
+ if (typeof e === 'object' && e !== null && 'code' in e && typeof e.code === 'string')
27
+ return e.code;
28
+ return undefined;
29
+ }
30
+ function isRecord(x) {
31
+ return typeof x === 'object' && x !== null && !Array.isArray(x);
32
+ }
33
+ function lockError(dir, pid) {
34
+ return new Error(`another gonogo is using ${dir} (pid ${pid}). Stop it, or delete ${join(dir, LOCK_FILE)} if none is running.`);
35
+ }
36
+ /** The pid in a lock file, or null when the content is not a positive integer. Throws ENOENT when the file is gone. */
37
+ function readLockPid(path) {
38
+ const m = /^\s*(\d+)\s*$/.exec(readFileSync(path, 'utf8'));
39
+ const pid = m ? Number(m[1]) : 0;
40
+ return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
41
+ }
42
+ function isProcessAlive(pid) {
43
+ try {
44
+ process.kill(pid, 0);
45
+ return true;
46
+ }
47
+ catch (e) {
48
+ // EPERM means the process exists but belongs to someone else: still a live owner
49
+ return errCode(e) !== 'ESRCH';
50
+ }
51
+ }
52
+ /**
53
+ * A home or a token that another user owns, or that group and other can still reach after the chmod, is not private: the
54
+ * browser token and the roster would be theirs too, so the start is refused instead of carried on. A path that is not
55
+ * there yet is skipped (whoever creates it makes it private).
56
+ */
57
+ function requirePrivate(path, mode, what) {
58
+ const found = statSync(path, { throwIfNoEntry: false });
59
+ if (found === undefined)
60
+ return;
61
+ const own = 'use --home with a directory of your own';
62
+ if (what === 'directory' ? !found.isDirectory() : !found.isFile())
63
+ throw new Error(`${path} is not a ${what}; remove it or ${own}`);
64
+ const owner = process.getuid?.();
65
+ if (owner !== undefined && found.uid !== owner) {
66
+ throw new Error(`${path} belongs to another user (uid ${found.uid}); ${what === 'file' ? `delete it (a new token is made) or ${own}` : own}`);
67
+ }
68
+ let refused = '';
69
+ try {
70
+ chmodSync(path, mode);
71
+ }
72
+ catch (e) {
73
+ refused = ` (${errMessage(e)})`;
74
+ }
75
+ const bits = statSync(path).mode & 0o777;
76
+ if ((bits & 0o077) !== 0) {
77
+ throw new Error(`${path} is open to other users (mode ${bits.toString(8)}) and chmod ${mode.toString(8)} did not close it${refused}; have its owner run chmod ${mode.toString(8)} on it, or ${own}`);
78
+ }
79
+ }
80
+ function acquireLock(dir, key) {
81
+ if (heldDirs.has(key))
82
+ throw lockError(dir, process.pid);
83
+ const path = join(dir, LOCK_FILE);
84
+ let lastPid = '?';
85
+ for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
86
+ try {
87
+ const fd = openSync(path, 'wx', FILE_MODE);
88
+ try {
89
+ writeSync(fd, `${process.pid}\n`);
90
+ }
91
+ finally {
92
+ closeSync(fd);
93
+ }
94
+ heldDirs.add(key);
95
+ return;
96
+ }
97
+ catch (e) {
98
+ if (errCode(e) !== 'EEXIST')
99
+ throw e;
100
+ }
101
+ let pid;
102
+ try {
103
+ pid = readLockPid(path);
104
+ }
105
+ catch (e) {
106
+ if (errCode(e) === 'ENOENT')
107
+ continue;
108
+ throw e;
109
+ }
110
+ if (pid !== null) {
111
+ lastPid = pid;
112
+ // heldDirs does not have this directory, so a lock naming our own pid is a leftover of an earlier run
113
+ if (pid !== process.pid && isProcessAlive(pid))
114
+ throw lockError(dir, pid);
115
+ }
116
+ // shortcut: two servers that both find the same stale lock in the same millisecond can both win; use flock if that ever matters
117
+ try {
118
+ unlinkSync(path);
119
+ }
120
+ catch (e) {
121
+ if (errCode(e) !== 'ENOENT')
122
+ throw e;
123
+ }
124
+ }
125
+ throw lockError(dir, lastPid);
126
+ }
127
+ function isPermissionMode(x) {
128
+ return typeof x === 'string' && PERMISSION_MODES.includes(x);
129
+ }
130
+ function parseAgent(a) {
131
+ if (!isRecord(a))
132
+ return 'not an object';
133
+ const { name, role, dir, mode, sessionId, desk, boss, createdAt } = a;
134
+ if (typeof name !== 'string' || !NAME_RE.test(name))
135
+ return 'invalid name';
136
+ if (RESERVED_NAMES.includes(name))
137
+ return `${name}: a reserved name`;
138
+ if (typeof role !== 'string')
139
+ return `${name}: role must be a string`;
140
+ if (typeof dir !== 'string')
141
+ return `${name}: dir must be a string`;
142
+ if (!isPermissionMode(mode))
143
+ return `${name}: mode must be one of ${PERMISSION_MODES.join(', ')}`;
144
+ if (typeof sessionId !== 'string' || !UUID_RE.test(sessionId))
145
+ return `${name}: sessionId must be a UUID`;
146
+ if (typeof desk !== 'number' || !Number.isInteger(desk) || desk < 0)
147
+ return `${name}: desk must be a non-negative integer`;
148
+ if (typeof boss !== 'boolean')
149
+ return `${name}: boss must be true or false`;
150
+ if (typeof createdAt !== 'number' || !Number.isFinite(createdAt))
151
+ return `${name}: createdAt must be a number`;
152
+ const record = { name, role, dir, mode, sessionId, desk, boss, createdAt };
153
+ const { position, provider, command, payload, cleanRoom } = a;
154
+ if (position !== undefined) {
155
+ if (typeof position !== 'string' || !POSITION_IDS.includes(position))
156
+ return `${name}: unknown position`;
157
+ record.position = position;
158
+ }
159
+ if (provider !== undefined && !PROVIDERS.includes(provider)) {
160
+ return `${name}: provider must be one of ${PROVIDERS.join(', ')}`;
161
+ }
162
+ if (provider !== undefined && provider !== 'claude')
163
+ record.provider = provider;
164
+ if (command !== undefined) {
165
+ if (provider !== 'custom')
166
+ return `${name}: only a custom agent has a command`;
167
+ if (typeof command !== 'string' || command.length === 0 || command.length > COMMAND_MAX_CHARS) {
168
+ return `${name}: command must be 1 to ${COMMAND_MAX_CHARS} characters`;
169
+ }
170
+ try {
171
+ readCustomCommand(command);
172
+ }
173
+ catch (error) {
174
+ return `${name}: ${error instanceof Error ? error.message : String(error)}`;
175
+ }
176
+ record.command = command;
177
+ }
178
+ else if (provider === 'custom')
179
+ return `${name}: a custom agent needs a command`;
180
+ if (provider === 'custom' && boss)
181
+ return `${name}: the boss cannot be a custom agent`;
182
+ if (payload !== undefined) {
183
+ const checked = parsePayload(payload);
184
+ if (!checked.ok)
185
+ return `${name}: ${checked.error}`;
186
+ const refused = checked.payload && payloadRefusal(record.provider, checked.payload);
187
+ if (refused)
188
+ return `${name}: ${refused.error}`;
189
+ if (checked.payload)
190
+ record.payload = checked.payload;
191
+ }
192
+ if (cleanRoom !== undefined) {
193
+ const checked = parseCleanRoom(cleanRoom, record.provider);
194
+ if (!checked.ok)
195
+ return `${name}: ${checked.error}`;
196
+ record.cleanRoom = checked.cleanRoom;
197
+ }
198
+ return record;
199
+ }
200
+ function parseRoster(text, path) {
201
+ const fail = (reason) => new Error(`${path} is not usable (${reason}); fix or delete this file`);
202
+ let data;
203
+ try {
204
+ data = JSON.parse(text);
205
+ }
206
+ catch {
207
+ throw fail('not valid JSON');
208
+ }
209
+ if (!isRecord(data) || data.version !== 1 || !Array.isArray(data.agents)) {
210
+ throw fail('expected {"version":1,"agents":[...]}');
211
+ }
212
+ const seen = new Set();
213
+ const agents = data.agents.map((item, i) => {
214
+ const parsed = parseAgent(item);
215
+ if (typeof parsed === 'string')
216
+ throw fail(`agent ${i + 1}: ${parsed}`);
217
+ if (seen.has(parsed.name))
218
+ throw fail(`agent name "${parsed.name}" appears twice`);
219
+ seen.add(parsed.name);
220
+ return parsed;
221
+ });
222
+ return { version: 1, agents };
223
+ }
224
+ function isStatus(x) {
225
+ return typeof x === 'string' && ACTIVITY_STATUSES.includes(x);
226
+ }
227
+ /** A whole record opens an entry, a four-field line updates one. Anything else is unreadable (null). */
228
+ function parseMessageLine(line) {
229
+ let o;
230
+ try {
231
+ o = JSON.parse(line);
232
+ }
233
+ catch {
234
+ return null;
235
+ }
236
+ if (!isRecord(o) || typeof o.id !== 'string' || !isStatus(o.status))
237
+ return null;
238
+ const { id, status } = o;
239
+ const note = typeof o.note === 'string' ? o.note : null;
240
+ if (typeof o.from !== 'string') {
241
+ return typeof o.updatedAt === 'number' && Number.isFinite(o.updatedAt) ? { id, status, note, updatedAt: o.updatedAt } : null;
242
+ }
243
+ const { to, body, at } = o;
244
+ if (typeof to !== 'string' || typeof body !== 'string' || typeof at !== 'number' || !Number.isFinite(at))
245
+ return null;
246
+ return {
247
+ id,
248
+ from: o.from,
249
+ to,
250
+ subject: typeof o.subject === 'string' ? o.subject : '',
251
+ body,
252
+ inReplyTo: typeof o.inReplyTo === 'string' ? o.inReplyTo : null,
253
+ hops: typeof o.hops === 'number' && Number.isFinite(o.hops) ? o.hops : 0,
254
+ at,
255
+ status,
256
+ note,
257
+ updatedAt: typeof o.updatedAt === 'number' && Number.isFinite(o.updatedAt) ? o.updatedAt : at,
258
+ };
259
+ }
260
+ /**
261
+ * Whole lines inside the last `maxBytes` of a file; a line that starts before the window is dropped. null when the file
262
+ * does not exist. Reads only the window, so start-up stays fast whatever the file size.
263
+ */
264
+ function readTailLines(path, maxBytes) {
265
+ let fd;
266
+ try {
267
+ fd = openSync(path, 'r');
268
+ }
269
+ catch (e) {
270
+ if (errCode(e) === 'ENOENT')
271
+ return null;
272
+ throw e;
273
+ }
274
+ try {
275
+ const size = fstatSync(fd).size;
276
+ const start = Math.max(0, size - maxBytes);
277
+ // the byte before the window tells whether the window begins on a line boundary
278
+ const from = start > 0 ? start - 1 : 0;
279
+ const buf = Buffer.alloc(size - from);
280
+ let read = 0;
281
+ while (read < buf.length) {
282
+ const n = readSync(fd, buf, read, buf.length - read, from + read);
283
+ if (n === 0)
284
+ break;
285
+ read += n;
286
+ }
287
+ let begin = 0;
288
+ if (start > 0) {
289
+ const nl = buf.indexOf(0x0a);
290
+ if (nl === -1 || nl >= read)
291
+ return [];
292
+ begin = nl + 1;
293
+ }
294
+ return buf
295
+ .subarray(begin, read)
296
+ .toString('utf8')
297
+ .split('\n')
298
+ .filter((l) => l.trim() !== '');
299
+ }
300
+ finally {
301
+ closeSync(fd);
302
+ }
303
+ }
304
+ export function openHome(dir, log = nullLogger) {
305
+ const logger = log.child('home');
306
+ const root = resolve(dir);
307
+ const agentsRoot = join(root, AGENTS_DIR);
308
+ const rosterPath = join(root, AGENTS_FILE);
309
+ const messagesPath = join(root, MESSAGES_FILE);
310
+ const rotatedPath = join(root, MESSAGES_ROTATED_FILE);
311
+ const tokenPath = join(root, BROWSER_TOKEN_FILE);
312
+ // a home that exists is looked at before anything is put into it
313
+ requirePrivate(root, DIR_MODE, 'directory');
314
+ try {
315
+ mkdirSync(agentsRoot, { recursive: true, mode: DIR_MODE });
316
+ }
317
+ catch (e) {
318
+ throw new Error(`cannot create ${root}: ${errMessage(e)}`);
319
+ }
320
+ // mkdir's mode is cut by the umask and ignored for a directory that already exists (a restore or rsync may leave 0755)
321
+ for (const d of [root, agentsRoot])
322
+ requirePrivate(d, DIR_MODE, 'directory');
323
+ /** Sync on purpose: inside the append chain nothing can write between the check and the rename. Never throws. */
324
+ const rotateMessagesIfLarge = () => {
325
+ // shortcut: a rename that keeps failing warns on every append; add a latch if that ever floods the log
326
+ try {
327
+ if (statSync(messagesPath).size > MESSAGES_ROTATE_BYTES) {
328
+ renameSync(messagesPath, rotatedPath);
329
+ logger.info(`${MESSAGES_FILE} was larger than ${MESSAGES_ROTATE_BYTES} bytes; moved to ${MESSAGES_ROTATED_FILE}`);
330
+ }
331
+ }
332
+ catch (e) {
333
+ if (errCode(e) !== 'ENOENT')
334
+ logger.warn(`could not rotate ${MESSAGES_FILE}: ${errMessage(e)}`);
335
+ }
336
+ };
337
+ const lockKey = realpathSync(root);
338
+ acquireLock(root, lockKey);
339
+ const lockPath = join(root, LOCK_FILE);
340
+ const releaseLock = () => {
341
+ try {
342
+ if (readLockPid(lockPath) === process.pid)
343
+ unlinkSync(lockPath);
344
+ }
345
+ catch (e) {
346
+ if (errCode(e) !== 'ENOENT')
347
+ logger.warn(`could not remove ${lockPath}: ${errMessage(e)}`);
348
+ }
349
+ heldDirs.delete(lockKey);
350
+ };
351
+ let browserToken;
352
+ try {
353
+ requirePrivate(tokenPath, FILE_MODE, 'file');
354
+ let existing = '';
355
+ try {
356
+ existing = readFileSync(tokenPath, 'utf8').trim();
357
+ }
358
+ catch (e) {
359
+ if (errCode(e) !== 'ENOENT')
360
+ throw e;
361
+ }
362
+ if (TOKEN_RE.test(existing)) {
363
+ browserToken = existing;
364
+ }
365
+ else {
366
+ if (existing !== '')
367
+ logger.warn(`${tokenPath} did not hold a 64 character hex token; replacing it`);
368
+ browserToken = randomBytes(TOKEN_BYTES).toString('hex');
369
+ // only this process writes it (it holds the lock), and a torn write is replaced at the next start by the check above
370
+ writeFileSync(tokenPath, browserToken + '\n', { mode: FILE_MODE });
371
+ }
372
+ chmodSync(tokenPath, FILE_MODE);
373
+ // under the lock, before any store reads a file: an upgrade is written once, and a file of a newer gonogo stops the start
374
+ migrateHome(root, logger);
375
+ rotateMessagesIfLarge();
376
+ }
377
+ catch (e) {
378
+ releaseLock();
379
+ throw e;
380
+ }
381
+ let rosterChain = Promise.resolve();
382
+ let messageChain = Promise.resolve();
383
+ const writtenIds = new Set();
384
+ let closing = null;
385
+ // shortcut: no fsync before the rename, so a power cut can lose the last save but never leaves half a file; add one if that ever hurts
386
+ const writeRoster = async (data) => {
387
+ const tmp = join(root, `.${AGENTS_FILE}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
388
+ try {
389
+ await writeFile(tmp, data, { mode: FILE_MODE, flag: 'wx' });
390
+ await rename(tmp, rosterPath);
391
+ }
392
+ catch (e) {
393
+ await unlink(tmp).catch(() => undefined);
394
+ throw e;
395
+ }
396
+ };
397
+ const maxSeqIn = (path) => {
398
+ const lines = readTailLines(path, MESSAGES_TAIL_BYTES);
399
+ let max = 0;
400
+ for (const line of lines ?? []) {
401
+ let o;
402
+ try {
403
+ o = JSON.parse(line);
404
+ }
405
+ catch {
406
+ continue;
407
+ }
408
+ const m = isRecord(o) && typeof o.id === 'string' ? MESSAGE_ID_RE.exec(o.id) : null;
409
+ const n = m ? Number(m[1]) : 0;
410
+ if (Number.isSafeInteger(n) && n > max)
411
+ max = n;
412
+ }
413
+ return max;
414
+ };
415
+ return {
416
+ dir: root,
417
+ browserToken,
418
+ agentDir(name) {
419
+ if (typeof name !== 'string' || !NAME_RE.test(name))
420
+ throw new Error(`invalid agent name "${String(name)}"`);
421
+ return join(agentsRoot, name);
422
+ },
423
+ loadRoster() {
424
+ let text;
425
+ try {
426
+ text = readFileSync(rosterPath, 'utf8');
427
+ }
428
+ catch (e) {
429
+ if (errCode(e) === 'ENOENT')
430
+ return { version: 1, agents: [] };
431
+ throw new Error(`cannot read ${rosterPath}: ${errMessage(e)}; fix or delete this file`);
432
+ }
433
+ return parseRoster(text, rosterPath);
434
+ },
435
+ saveRoster(file) {
436
+ // serialised now: the caller may change the object before the chain gets to it
437
+ const json = JSON.stringify(file, null, 2);
438
+ const run = rosterChain.then(() => writeRoster(json));
439
+ rosterChain = run.catch(() => undefined);
440
+ return run;
441
+ },
442
+ appendMessage(record) {
443
+ let line;
444
+ try {
445
+ line = writtenIds.has(record.id)
446
+ ? JSON.stringify({ id: record.id, status: record.status, note: record.note, updatedAt: record.updatedAt })
447
+ : JSON.stringify(record);
448
+ }
449
+ catch (e) {
450
+ logger.error(`could not serialise message ${String(record.id)}: ${errMessage(e)}`);
451
+ return;
452
+ }
453
+ writtenIds.add(record.id);
454
+ messageChain = messageChain
455
+ .then(() => {
456
+ // a run adds lines for as long as it lives: the limit is checked here too, not only when the home is opened
457
+ rotateMessagesIfLarge();
458
+ return appendFile(messagesPath, line + '\n', { mode: FILE_MODE });
459
+ })
460
+ .catch((e) => logger.error(`could not append to ${MESSAGES_FILE}: ${errMessage(e)}`));
461
+ },
462
+ loadRecentMessages(limit) {
463
+ const lines = readTailLines(messagesPath, MESSAGES_TAIL_BYTES);
464
+ if (!lines || !(limit >= 1))
465
+ return [];
466
+ let unreadable = 0;
467
+ const byId = new Map();
468
+ for (const line of lines) {
469
+ const parsed = parseMessageLine(line);
470
+ if (parsed === null) {
471
+ unreadable += 1;
472
+ }
473
+ else if ('from' in parsed) {
474
+ byId.set(parsed.id, parsed);
475
+ }
476
+ else {
477
+ const current = byId.get(parsed.id);
478
+ if (current)
479
+ byId.set(parsed.id, { ...current, status: parsed.status, note: parsed.note, updatedAt: parsed.updatedAt });
480
+ }
481
+ }
482
+ if (unreadable > 0)
483
+ logger.warn(`${MESSAGES_FILE}: ignored ${unreadable} line(s) that could not be read`);
484
+ return [...byId.values()].sort((a, b) => a.at - b.at).slice(-Math.floor(limit));
485
+ },
486
+ lastMessageSeq() {
487
+ return maxSeqIn(messagesPath) || maxSeqIn(rotatedPath);
488
+ },
489
+ close() {
490
+ closing ??= (async () => {
491
+ await Promise.all([rosterChain, messageChain]);
492
+ releaseLock();
493
+ })();
494
+ return closing;
495
+ },
496
+ };
497
+ }