@simonren/quorum 0.9.1 → 0.11.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 (68) hide show
  1. package/README.md +91 -48
  2. package/commands/multi-consult.md +47 -72
  3. package/commands/multi-review.md +68 -99
  4. package/dist/adapters/base.d.ts +53 -70
  5. package/dist/adapters/base.js +21 -79
  6. package/dist/adapters/claude.d.ts +38 -17
  7. package/dist/adapters/claude.js +93 -185
  8. package/dist/adapters/cli-adapter.d.ts +78 -0
  9. package/dist/adapters/cli-adapter.js +220 -0
  10. package/dist/adapters/codex.d.ts +18 -13
  11. package/dist/adapters/codex.js +64 -200
  12. package/dist/adapters/gemini.d.ts +45 -21
  13. package/dist/adapters/gemini.js +81 -152
  14. package/dist/adapters/index.d.ts +8 -5
  15. package/dist/adapters/index.js +7 -8
  16. package/dist/config.d.ts +98 -28
  17. package/dist/config.js +44 -25
  18. package/dist/consult-prompt.d.ts +6 -5
  19. package/dist/consult-prompt.js +48 -23
  20. package/dist/decoders/claude.d.ts +6 -0
  21. package/dist/decoders/claude.js +10 -1
  22. package/dist/doctor.d.ts +20 -0
  23. package/dist/doctor.js +91 -0
  24. package/dist/executor.d.ts +58 -46
  25. package/dist/executor.js +218 -129
  26. package/dist/guards.d.ts +29 -0
  27. package/dist/guards.js +72 -0
  28. package/dist/handoff.d.ts +79 -229
  29. package/dist/handoff.js +411 -402
  30. package/dist/index.d.ts +8 -12
  31. package/dist/index.js +81 -106
  32. package/dist/integrity.d.ts +16 -0
  33. package/dist/integrity.js +49 -0
  34. package/dist/sections.d.ts +22 -0
  35. package/dist/sections.js +31 -0
  36. package/dist/server.d.ts +9 -0
  37. package/dist/server.js +36 -0
  38. package/dist/tools/consult.d.ts +17 -76
  39. package/dist/tools/consult.js +72 -188
  40. package/dist/tools/format.d.ts +35 -0
  41. package/dist/tools/format.js +85 -0
  42. package/dist/tools/review.d.ts +55 -0
  43. package/dist/tools/review.js +120 -0
  44. package/dist/types.d.ts +20 -103
  45. package/dist/types.js +18 -29
  46. package/package.json +7 -4
  47. package/dist/cli/check.d.ts +0 -20
  48. package/dist/cli/check.js +0 -78
  49. package/dist/cli/codex.d.ts +0 -11
  50. package/dist/cli/codex.js +0 -255
  51. package/dist/cli/gemini.d.ts +0 -12
  52. package/dist/cli/gemini.js +0 -253
  53. package/dist/context.d.ts +0 -1538
  54. package/dist/context.js +0 -383
  55. package/dist/decoders/gemini.d.ts +0 -33
  56. package/dist/decoders/gemini.js +0 -58
  57. package/dist/errors.d.ts +0 -46
  58. package/dist/errors.js +0 -198
  59. package/dist/pipeline.d.ts +0 -135
  60. package/dist/pipeline.js +0 -462
  61. package/dist/prompt-v2.d.ts +0 -38
  62. package/dist/prompt-v2.js +0 -391
  63. package/dist/prompt.d.ts +0 -71
  64. package/dist/prompt.js +0 -309
  65. package/dist/schema.d.ts +0 -660
  66. package/dist/schema.js +0 -536
  67. package/dist/tools/feedback.d.ts +0 -91
  68. package/dist/tools/feedback.js +0 -117
package/dist/executor.js CHANGED
@@ -1,36 +1,115 @@
1
1
  /**
2
- * CliExecutor — Shared process management for external AI CLI tools.
2
+ * CliExecutor — shared process management for external AI CLI tools.
3
3
  *
4
- * Extracted from the duplicated spawn logic in codex.ts and gemini.ts to
5
- * provide a single, well-tested implementation of:
6
- * - Child-process spawning with stdin delivery
7
- * - Line-buffered stdout parsing (JSONL-friendly)
8
- * - Inactivity and absolute-max timeouts
9
- * - Max buffer size enforcement with truncation flag
10
- * - Settled guard to prevent double resolve/reject
11
- * - Dynamic inactivity timeout adjustment via setInactivityTimeout()
4
+ * One implementation of everything that is easy to get subtly wrong:
5
+ * - child-process spawning with stdin delivery
6
+ * - UTF-8-safe, line-buffered stdout parsing (JSONL-friendly)
7
+ * - inactivity and absolute-max timeouts, with out-of-band liveness resets
8
+ * - process-group SIGTERM → SIGKILL escalation so a stuck CLI — and anything
9
+ * it forked — cannot outlive its timeout
10
+ * - a registry of live children so the server can reap them on shutdown
11
+ * - max buffer enforcement with a truncation flag
12
+ * - a settled guard against double resolve/reject
12
13
  */
13
14
  import { spawn } from 'child_process';
15
+ import { StringDecoder } from 'string_decoder';
14
16
  // =============================================================================
15
- // EXECUTOR
17
+ // CHILD REGISTRY — reap children when the server dies
16
18
  // =============================================================================
19
+ const activeChildren = new Set();
20
+ let exitHooksInstalled = false;
21
+ let shuttingDown = false;
22
+ const POSIX = process.platform !== 'win32';
23
+ /**
24
+ * Signal a child and, on POSIX, its whole process group. Children are spawned
25
+ * detached (own group) so that whatever the CLI forked — a launcher's native
26
+ * binary, a reviewer's shell or MCP children — dies with it. A wrapper can
27
+ * forward SIGTERM but never SIGKILL, so signalling only the direct pid would
28
+ * orphan the real worker on escalation.
29
+ */
30
+ export function killTree(child, signal) {
31
+ if (POSIX && child.pid) {
32
+ try {
33
+ process.kill(-child.pid, signal);
34
+ return true;
35
+ }
36
+ catch { /* group already gone — fall through */ }
37
+ }
38
+ try {
39
+ return child.kill(signal);
40
+ }
41
+ catch {
42
+ return false;
43
+ }
44
+ }
45
+ /** Number of CLI processes currently running under this server. */
46
+ export function activeChildCount() {
47
+ return activeChildren.size;
48
+ }
49
+ /**
50
+ * Send `signal` to every live child. Returns how many were signalled.
51
+ * Idempotent and safe to call when nothing is running.
52
+ */
53
+ export function shutdownChildren(signal = 'SIGTERM') {
54
+ let count = 0;
55
+ for (const child of activeChildren) {
56
+ if (killTree(child, signal))
57
+ count++;
58
+ }
59
+ return count;
60
+ }
61
+ /**
62
+ * Install process-level hooks (once) so that the server exiting — normally,
63
+ * on SIGINT/SIGTERM/SIGHUP, or because the MCP client hung up — never leaves
64
+ * a Codex/Claude/agy process behind burning tokens. Called lazily on the
65
+ * first spawn; `index.ts` also calls it explicitly.
66
+ */
67
+ export function installChildCleanupHooks() {
68
+ if (exitHooksInstalled)
69
+ return;
70
+ exitHooksInstalled = true;
71
+ // Last resort: synchronous SIGKILL at exit for anything still registered.
72
+ process.once('exit', () => {
73
+ for (const child of activeChildren)
74
+ killTree(child, 'SIGKILL');
75
+ });
76
+ const signals = [
77
+ { name: 'SIGINT', code: 130 },
78
+ { name: 'SIGTERM', code: 143 },
79
+ { name: 'SIGHUP', code: 129 },
80
+ ];
81
+ // `on`, not `once`: a second signal during the grace window must not fall
82
+ // back to Node's default disposition, which exits without running `exit`
83
+ // hooks and therefore without the SIGKILL sweep. It forces the sweep now.
84
+ for (const { name, code } of signals) {
85
+ process.on(name, () => {
86
+ if (shuttingDown) {
87
+ shutdownChildren('SIGKILL');
88
+ process.exit(code);
89
+ }
90
+ void gracefulExit(code);
91
+ });
92
+ }
93
+ }
94
+ /**
95
+ * Terminate children politely, wait briefly for them to go, then exit.
96
+ * Survivors are SIGKILLed by the `exit` hook.
97
+ */
98
+ export async function gracefulExit(code, graceMs = 2_000) {
99
+ shuttingDown = true;
100
+ shutdownChildren('SIGTERM');
101
+ const deadline = Date.now() + graceMs;
102
+ while (activeChildren.size > 0 && Date.now() < deadline) {
103
+ await new Promise((resolve) => setTimeout(resolve, 25));
104
+ }
105
+ process.exit(code);
106
+ }
17
107
  export class CliExecutor {
18
108
  opts;
19
- /**
20
- * Mutable inactivity timeout — callers can tighten it after first streaming
21
- * event via setInactivityTimeout(). Changing it clears and restarts the
22
- * currently running inactivity timer immediately.
23
- */
109
+ /** Mutable inactivity timeout — see setInactivityTimeout(). */
24
110
  currentInactivityMs;
25
- /**
26
- * Handle to the live inactivity timer (kept here so setInactivityTimeout
27
- * can reset it from outside the Promise closure via the shared ref below).
28
- */
29
111
  inactivityTimer;
30
- /**
31
- * Injected by run() so setInactivityTimeout can restart the timer using
32
- * the correct reject handle while the process is still running.
33
- */
112
+ /** Injected by run() so the timer can be restarted from outside the closure. */
34
113
  resetInactivityFn;
35
114
  constructor(options) {
36
115
  this.opts = {
@@ -44,36 +123,27 @@ export class CliExecutor {
44
123
  inactivityTimeoutMs: options.inactivityTimeoutMs ?? 120_000,
45
124
  maxTimeoutMs: options.maxTimeoutMs ?? 3_600_000,
46
125
  maxBufferSize: options.maxBufferSize ?? 1_048_576,
126
+ killGraceMs: options.killGraceMs ?? 5_000,
47
127
  };
48
128
  this.currentInactivityMs = this.opts.inactivityTimeoutMs;
49
129
  }
50
130
  /**
51
- * Dynamically adjust the inactivity timeout.
52
- *
53
- * If the process is currently running, the active inactivity timer is
54
- * cancelled and restarted with the new duration immediately. Subsequent
55
- * activity resets will also use this new value.
56
- *
57
- * Typical use: tighten the timeout once the first streaming event arrives,
58
- * so a stalled process is detected sooner after it starts responding.
131
+ * Dynamically adjust the inactivity timeout. If the process is running, the
132
+ * active timer is restarted with the new duration immediately.
59
133
  */
60
134
  setInactivityTimeout(ms) {
61
135
  this.currentInactivityMs = ms;
62
- // Restart the running timer (if any) with the new duration.
63
136
  this.resetInactivityFn?.();
64
137
  }
65
138
  /**
66
139
  * Reset the inactivity timer without any stdout/stderr byte having arrived.
67
140
  *
68
- * For a CLI whose event stream goes silent while it is still working — Codex
69
- * emits nothing on stdout for the whole of a reasoning block — stdout bytes
70
- * are not a liveness signal, and a timer driven only by them kills healthy
71
- * processes mid-thought. Callers that can prove liveness out of band (a
72
- * growing session/log file, a status socket) call this to keep the process
73
- * alive.
141
+ * For a CLI whose event stream goes silent while it is still working (Codex
142
+ * emits nothing during a reasoning block) stdout bytes are not a liveness
143
+ * signal. Callers that can prove liveness out of band (a growing rollout
144
+ * file) call this to keep the process alive.
74
145
  *
75
- * No-op before run() and after the process has settled, so a watcher that
76
- * fires late cannot resurrect a finished run's timer.
146
+ * No-op before run() and after the process has settled.
77
147
  */
78
148
  noteActivity() {
79
149
  this.resetInactivityFn?.();
@@ -86,11 +156,8 @@ export class CliExecutor {
86
156
  * - ENOENT / other spawn errors propagated from child_process
87
157
  */
88
158
  run() {
159
+ installChildCleanupHooks();
89
160
  return new Promise((resolve, reject) => {
90
- // ------------------------------------------------------------------
91
- // Settled guard — prevents double resolve/reject when, e.g., the
92
- // inactivity timer fires and then the `close` event also fires.
93
- // ------------------------------------------------------------------
94
161
  let settled = false;
95
162
  const settle = (fn) => {
96
163
  if (settled)
@@ -99,28 +166,38 @@ export class CliExecutor {
99
166
  fn();
100
167
  };
101
168
  // ------------------------------------------------------------------
102
- // Spawn
169
+ // Spawn + register
103
170
  // ------------------------------------------------------------------
104
171
  const proc = spawn(this.opts.command, this.opts.args, {
105
172
  cwd: this.opts.cwd,
106
173
  stdio: ['pipe', 'pipe', 'pipe'],
107
- env: this.opts.env
108
- ? { ...process.env, ...this.opts.env }
109
- : { ...process.env },
174
+ env: this.opts.env ? { ...process.env, ...this.opts.env } : { ...process.env },
175
+ // Own process group so killTree() can take the whole tree down.
176
+ detached: POSIX,
177
+ });
178
+ activeChildren.add(proc);
179
+ let exited = false;
180
+ proc.once('exit', () => {
181
+ exited = true;
182
+ activeChildren.delete(proc);
110
183
  });
184
+ /** SIGTERM now, SIGKILL if the process is still around after the grace period. */
185
+ const terminate = () => {
186
+ killTree(proc, 'SIGTERM');
187
+ const escalation = setTimeout(() => {
188
+ if (!exited)
189
+ killTree(proc, 'SIGKILL');
190
+ }, this.opts.killGraceMs);
191
+ escalation.unref?.();
192
+ };
111
193
  // ------------------------------------------------------------------
112
194
  // Stdin delivery
113
195
  // ------------------------------------------------------------------
114
- // Guard against EPIPE: log but do not reject — the close handler owns
115
- // the final resolution. EPIPE means the child exited before consuming
116
- // all of stdin, which is fine (e.g. the child crashed early).
196
+ // EPIPE means the child exited before consuming all of stdin (e.g. it
197
+ // crashed early). Log, don't reject — the close handler owns resolution.
117
198
  proc.stdin.on('error', (err) => {
118
- if (err.code === 'EPIPE') {
119
- console.error(`[executor] stdin EPIPE (child closed early): ${err.message}`);
120
- }
121
- else {
122
- console.error(`[executor] stdin error: ${err.message}`);
123
- }
199
+ const kind = err.code === 'EPIPE' ? 'stdin EPIPE (child closed early)' : 'stdin error';
200
+ console.error(`[executor] ${kind}: ${err.message}`);
124
201
  });
125
202
  if (this.opts.stdin !== undefined) {
126
203
  proc.stdin.write(this.opts.stdin);
@@ -132,33 +209,28 @@ export class CliExecutor {
132
209
  let rawStdout = '';
133
210
  let stderr = '';
134
211
  let truncated = false;
135
- /** Partial line buffer — accumulates data until a '\n' is seen. */
212
+ /** Partial line buffer — accumulates until a '\n' is seen. */
136
213
  let lineBuffer = '';
137
- // ------------------------------------------------------------------
138
- // Timers
139
- // ------------------------------------------------------------------
140
- const maxTimer = setTimeout(() => {
141
- proc.kill('SIGTERM');
142
- settle(() => reject(new Error('MAX_TIMEOUT')));
143
- }, this.opts.maxTimeoutMs);
144
- const resetInactivity = () => {
145
- clearTimeout(this.inactivityTimer);
146
- this.inactivityTimer = setTimeout(() => {
147
- proc.kill('SIGTERM');
148
- settle(() => reject(new Error('TIMEOUT')));
149
- }, this.currentInactivityMs);
214
+ // Multi-byte UTF-8 sequences can straddle chunk boundaries; a naive
215
+ // chunk.toString() would emit U+FFFD for the split character.
216
+ const stdoutDecoder = new StringDecoder('utf8');
217
+ const stderrDecoder = new StringDecoder('utf8');
218
+ // Nothing reaches the caller after settlement: a timeout has already
219
+ // rejected, so late output (the SIGTERM flush) must not trigger side
220
+ // effects such as starting a liveness watcher nobody will stop.
221
+ const emitLine = (line) => {
222
+ if (settled || !this.opts.onLine)
223
+ return;
224
+ try {
225
+ this.opts.onLine(line);
226
+ }
227
+ catch {
228
+ // Intentionally swallowed — callers must not break the executor.
229
+ }
150
230
  };
151
- // Expose reset function so setInactivityTimeout() can restart it.
152
- this.resetInactivityFn = resetInactivity;
153
- // Start the inactivity clock.
154
- resetInactivity();
155
- // ------------------------------------------------------------------
156
- // stdout handler — line buffering
157
- // ------------------------------------------------------------------
158
- proc.stdout.on('data', (chunk) => {
159
- resetInactivity();
160
- const incoming = chunk.toString();
161
- // Buffer management: cap rawStdout at maxBufferSize.
231
+ const consumeStdout = (incoming) => {
232
+ if (incoming.length === 0)
233
+ return;
162
234
  if (!truncated) {
163
235
  const remaining = this.opts.maxBufferSize - rawStdout.length;
164
236
  if (incoming.length <= remaining) {
@@ -169,42 +241,31 @@ export class CliExecutor {
169
241
  truncated = true;
170
242
  }
171
243
  }
172
- // Line splitting — process complete lines from the combined buffer.
173
244
  lineBuffer += incoming;
174
245
  const newlineIdx = lineBuffer.lastIndexOf('\n');
175
246
  if (newlineIdx === -1) {
176
- // No complete line yet — keep buffering.
247
+ // A single line longer than the buffer cap is not something any
248
+ // decoder can use; keep memory bounded rather than grow forever.
249
+ if (lineBuffer.length > this.opts.maxBufferSize) {
250
+ lineBuffer = lineBuffer.slice(-this.opts.maxBufferSize);
251
+ }
177
252
  return;
178
253
  }
179
- // Extract all complete lines (everything up to and including the last '\n').
180
254
  const completePart = lineBuffer.slice(0, newlineIdx + 1);
181
255
  lineBuffer = lineBuffer.slice(newlineIdx + 1);
182
256
  const lines = completePart.split('\n');
183
- // The last element is always '' because split on a trailing '\n' produces
184
- // an empty string — skip it.
185
- for (let i = 0; i < lines.length - 1; i++) {
186
- const line = lines[i];
187
- if (this.opts.onLine) {
188
- try {
189
- this.opts.onLine(line);
190
- }
191
- catch {
192
- // Intentionally swallowed — callers must not break the executor.
193
- }
194
- }
195
- }
196
- });
197
- // ------------------------------------------------------------------
198
- // stderr handler
199
- // ------------------------------------------------------------------
200
- proc.stderr.on('data', (chunk) => {
201
- resetInactivity();
202
- const data = chunk.toString();
257
+ // The last element is always '' (split on a trailing '\n').
258
+ for (let i = 0; i < lines.length - 1; i++)
259
+ emitLine(lines[i]);
260
+ };
261
+ const consumeStderr = (data) => {
262
+ if (data.length === 0)
263
+ return;
203
264
  if (stderr.length < this.opts.maxBufferSize) {
204
265
  const remaining = this.opts.maxBufferSize - stderr.length;
205
266
  stderr += data.length <= remaining ? data : data.slice(0, remaining);
206
267
  }
207
- if (this.opts.onStderr) {
268
+ if (this.opts.onStderr && !settled) {
208
269
  try {
209
270
  this.opts.onStderr(data);
210
271
  }
@@ -212,32 +273,61 @@ export class CliExecutor {
212
273
  // Intentionally swallowed.
213
274
  }
214
275
  }
215
- });
276
+ };
216
277
  // ------------------------------------------------------------------
217
- // close handler — normal resolution path
278
+ // Timers
218
279
  // ------------------------------------------------------------------
219
- proc.on('close', (code) => {
280
+ const maxTimer = setTimeout(() => {
281
+ clearTimers();
282
+ terminate();
283
+ settle(() => reject(new Error('MAX_TIMEOUT')));
284
+ }, this.opts.maxTimeoutMs);
285
+ const resetInactivity = () => {
286
+ clearTimeout(this.inactivityTimer);
287
+ this.inactivityTimer = setTimeout(() => {
288
+ clearTimers();
289
+ terminate();
290
+ settle(() => reject(new Error('TIMEOUT')));
291
+ }, this.currentInactivityMs);
292
+ };
293
+ this.resetInactivityFn = resetInactivity;
294
+ resetInactivity();
295
+ const clearTimers = () => {
220
296
  clearTimeout(this.inactivityTimer);
221
297
  clearTimeout(maxTimer);
222
298
  this.resetInactivityFn = undefined;
223
- // Flush any partial line still in the buffer.
224
- if (lineBuffer.length > 0) {
225
- if (this.opts.onLine) {
226
- try {
227
- this.opts.onLine(lineBuffer);
228
- }
229
- catch {
230
- // Intentionally swallowed.
231
- }
232
- }
233
- }
234
- // Build the final lines array from rawStdout (split after the fact so
235
- // the list is consistent with rawStdout even when truncated).
299
+ };
300
+ // ------------------------------------------------------------------
301
+ // Stream handlers
302
+ // ------------------------------------------------------------------
303
+ proc.stdout.on('data', (chunk) => {
304
+ if (settled)
305
+ return;
306
+ resetInactivity();
307
+ consumeStdout(stdoutDecoder.write(chunk));
308
+ });
309
+ proc.stderr.on('data', (chunk) => {
310
+ if (settled)
311
+ return;
312
+ resetInactivity();
313
+ consumeStderr(stderrDecoder.write(chunk));
314
+ });
315
+ // ------------------------------------------------------------------
316
+ // close — normal resolution path (all stdio flushed)
317
+ // ------------------------------------------------------------------
318
+ proc.on('close', (code) => {
319
+ clearTimers();
320
+ activeChildren.delete(proc);
321
+ // Flush decoder remainders and any partial final line.
322
+ consumeStdout(stdoutDecoder.end());
323
+ consumeStderr(stderrDecoder.end());
324
+ if (lineBuffer.length > 0)
325
+ emitLine(lineBuffer);
326
+ // Split after the fact so the list is consistent with rawStdout even
327
+ // when truncated.
236
328
  const rawLines = rawStdout.split('\n');
237
- // Drop a trailing empty string produced by a final '\n'.
238
- if (rawLines.length > 0 && rawLines[rawLines.length - 1] === '') {
329
+ if (rawLines.length > 0 && rawLines[rawLines.length - 1] === '')
239
330
  rawLines.pop();
240
- }
241
331
  settle(() => resolve({
242
332
  stdoutLines: rawLines,
243
333
  rawStdout,
@@ -247,12 +337,11 @@ export class CliExecutor {
247
337
  }));
248
338
  });
249
339
  // ------------------------------------------------------------------
250
- // error handler — spawn failures (e.g. ENOENT)
340
+ // error — spawn failures (e.g. ENOENT)
251
341
  // ------------------------------------------------------------------
252
342
  proc.on('error', (err) => {
253
- clearTimeout(this.inactivityTimer);
254
- clearTimeout(maxTimer);
255
- this.resetInactivityFn = undefined;
343
+ clearTimers();
344
+ activeChildren.delete(proc);
256
345
  settle(() => reject(err));
257
346
  });
258
347
  });
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Input guards shared by both tools.
3
+ */
4
+ export type WorkingDirCheck = {
5
+ ok: true;
6
+ resolved: string;
7
+ } | {
8
+ ok: false;
9
+ reason: string;
10
+ };
11
+ /**
12
+ * Returns the directory's canonical absolute path if it is safe to hand to an
13
+ * external CLI as its working directory, or a refusal if it resolves to a
14
+ * sensitive system location.
15
+ *
16
+ * Two kinds of roots: EXACT roots (`/`, `~`, `/usr`, `/var`, `~/.config`) are
17
+ * refused only when named directly, because ordinary projects live beneath
18
+ * them (`/var/www/app`, `~/.config/nvim`); SUBTREE roots (`/etc`, `~/.ssh`,
19
+ * `~/.aws`, `~/.claude`, …) are refused together with everything under them,
20
+ * because nothing there is a project and all of it is secret material.
21
+ * Symlinks are resolved on both sides so an alias of a sensitive directory is
22
+ * caught too. This is a scope check, not confinement: the reviewer CLIs can
23
+ * read outside the working directory regardless.
24
+ */
25
+ export declare function checkSensitiveWorkingDir(input: string): WorkingDirCheck;
26
+ /** Tool-result text for a refused working directory. */
27
+ export declare function refusalText(reason: string, command: string): string;
28
+ export declare function containsSteeringTag(value: string | undefined): boolean;
29
+ export declare const STEERING_TAG_MESSAGE = "customPrompt must not contain <user-steering> tags";
package/dist/guards.js ADDED
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Input guards shared by both tools.
3
+ */
4
+ import { realpathSync } from 'fs';
5
+ import { resolve, sep } from 'path';
6
+ import { homedir } from 'os';
7
+ /**
8
+ * Returns the directory's canonical absolute path if it is safe to hand to an
9
+ * external CLI as its working directory, or a refusal if it resolves to a
10
+ * sensitive system location.
11
+ *
12
+ * Two kinds of roots: EXACT roots (`/`, `~`, `/usr`, `/var`, `~/.config`) are
13
+ * refused only when named directly, because ordinary projects live beneath
14
+ * them (`/var/www/app`, `~/.config/nvim`); SUBTREE roots (`/etc`, `~/.ssh`,
15
+ * `~/.aws`, `~/.claude`, …) are refused together with everything under them,
16
+ * because nothing there is a project and all of it is secret material.
17
+ * Symlinks are resolved on both sides so an alias of a sensitive directory is
18
+ * caught too. This is a scope check, not confinement: the reviewer CLIs can
19
+ * read outside the working directory regardless.
20
+ */
21
+ export function checkSensitiveWorkingDir(input) {
22
+ let resolved;
23
+ try {
24
+ // realpath if it exists; otherwise resolve() so the adapter's
25
+ // cwd-existence check produces the user-visible error.
26
+ resolved = realpathSync(input);
27
+ }
28
+ catch {
29
+ resolved = resolve(input);
30
+ }
31
+ const home = homedir();
32
+ const exactRoots = ['/', '/var', '/usr', '/private/var', home, `${home}${sep}.config`];
33
+ const subtreeRoots = [
34
+ '/etc', '/private/etc', '/bin', '/sbin', '/boot', '/root',
35
+ `${home}${sep}.ssh`, `${home}${sep}.aws`, `${home}${sep}.gnupg`, `${home}${sep}.claude`, `${home}${sep}.codex`,
36
+ ];
37
+ const withRealpaths = (paths) => {
38
+ const out = new Set(paths);
39
+ for (const path of paths) {
40
+ try {
41
+ out.add(realpathSync(path));
42
+ }
43
+ catch { /* path doesn't exist */ }
44
+ }
45
+ return [...out];
46
+ };
47
+ if (withRealpaths(exactRoots).includes(resolved)) {
48
+ return { ok: false, reason: `workingDir resolves to a sensitive path: ${resolved}` };
49
+ }
50
+ const inside = withRealpaths(subtreeRoots).find((root) => resolved === root || resolved.startsWith(root + sep));
51
+ if (inside) {
52
+ return { ok: false, reason: `workingDir resolves inside a sensitive path: ${inside} (${resolved})` };
53
+ }
54
+ return { ok: true, resolved };
55
+ }
56
+ /** Tool-result text for a refused working directory. */
57
+ export function refusalText(reason, command) {
58
+ return `❌ Refused: ${reason}\n\nInvoke ${command} from a project root, not a sensitive system path.`;
59
+ }
60
+ // =============================================================================
61
+ // STEERING ENVELOPE
62
+ // =============================================================================
63
+ /**
64
+ * Free-form steering is embedded in a `<user-steering>` envelope in the
65
+ * prompts. Reject any literal opening/closing tag so a steering value cannot
66
+ * escape the envelope and inject instructions.
67
+ */
68
+ const STEERING_TAG = /<\/?user-steering/i;
69
+ export function containsSteeringTag(value) {
70
+ return typeof value === 'string' && STEERING_TAG.test(value);
71
+ }
72
+ export const STEERING_TAG_MESSAGE = 'customPrompt must not contain <user-steering> tags';