@sixb/agent 0.2.1 → 0.2.3

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 (107) hide show
  1. package/README.md +2 -1
  2. package/dist/agent-prompt.d.ts +13 -0
  3. package/dist/agent-prompt.d.ts.map +1 -1
  4. package/dist/agent-runtime/preflight.d.ts.map +1 -1
  5. package/dist/artifacts/board-previews.d.ts +41 -0
  6. package/dist/artifacts/board-previews.d.ts.map +1 -0
  7. package/dist/artifacts/layout-check/layout-check.d.ts +38 -6
  8. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  9. package/dist/artifacts/layout-check/overview.d.ts +17 -0
  10. package/dist/artifacts/layout-check/overview.d.ts.map +1 -0
  11. package/dist/artifacts/materialize.d.ts +56 -24
  12. package/dist/artifacts/materialize.d.ts.map +1 -1
  13. package/dist/artifacts/publish-tool.d.ts +35 -9
  14. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  15. package/dist/background-commands.d.ts +95 -0
  16. package/dist/background-commands.d.ts.map +1 -0
  17. package/dist/background-notices.d.ts +31 -0
  18. package/dist/background-notices.d.ts.map +1 -0
  19. package/dist/computer-runner.d.ts +63 -2
  20. package/dist/computer-runner.d.ts.map +1 -1
  21. package/dist/context-compaction.d.ts +3 -0
  22. package/dist/context-compaction.d.ts.map +1 -1
  23. package/dist/execution-plan.d.ts +12 -2
  24. package/dist/execution-plan.d.ts.map +1 -1
  25. package/dist/index.d.ts +3 -1
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +11814 -8722
  28. package/dist/index.js.map +35 -23
  29. package/dist/login-shell.d.ts +16 -0
  30. package/dist/login-shell.d.ts.map +1 -0
  31. package/dist/run-child.d.ts +3 -0
  32. package/dist/run-child.d.ts.map +1 -1
  33. package/dist/run-conversation-turn.d.ts +6 -2
  34. package/dist/run-conversation-turn.d.ts.map +1 -1
  35. package/dist/run-environment.d.ts +12 -2
  36. package/dist/run-environment.d.ts.map +1 -1
  37. package/dist/run-sandbox.d.ts +23 -0
  38. package/dist/run-sandbox.d.ts.map +1 -1
  39. package/dist/sandbox-files.d.ts +19 -0
  40. package/dist/sandbox-files.d.ts.map +1 -1
  41. package/dist/subagent-tools.d.ts +3 -1
  42. package/dist/subagent-tools.d.ts.map +1 -1
  43. package/dist/tools/background.d.ts +50 -0
  44. package/dist/tools/background.d.ts.map +1 -0
  45. package/dist/tools/bash.d.ts +12 -4
  46. package/dist/tools/bash.d.ts.map +1 -1
  47. package/dist/tools/model-spec.d.ts +9 -2
  48. package/dist/tools/model-spec.d.ts.map +1 -1
  49. package/dist/tools/tool-files.d.ts.map +1 -1
  50. package/dist/tools/tool-outputs.d.ts +12 -2
  51. package/dist/tools/tool-outputs.d.ts.map +1 -1
  52. package/dist/tools/web-fetch/cache.d.ts +33 -0
  53. package/dist/tools/web-fetch/cache.d.ts.map +1 -0
  54. package/dist/tools/web-fetch/html-markdown.d.ts +25 -0
  55. package/dist/tools/web-fetch/html-markdown.d.ts.map +1 -0
  56. package/dist/tools/web-fetch/network.d.ts +55 -0
  57. package/dist/tools/web-fetch/network.d.ts.map +1 -0
  58. package/dist/tools/web-fetch/tool.d.ts +96 -0
  59. package/dist/tools/web-fetch/tool.d.ts.map +1 -0
  60. package/dist/tools/web-search.d.ts +40 -0
  61. package/dist/tools/web-search.d.ts.map +1 -0
  62. package/dist/types.d.ts +5 -4
  63. package/dist/types.d.ts.map +1 -1
  64. package/dist/workspace-instructions.d.ts +15 -0
  65. package/dist/workspace-instructions.d.ts.map +1 -0
  66. package/package.json +15 -5
  67. package/src/agent-prompt.ts +64 -5
  68. package/src/agent-runtime/preflight.ts +2 -1
  69. package/src/artifacts/board-previews.ts +218 -0
  70. package/src/artifacts/layout-check/check.cjs +304 -80
  71. package/src/artifacts/layout-check/layout-check.ts +123 -13
  72. package/src/artifacts/layout-check/overview.ts +291 -0
  73. package/src/artifacts/materialize.ts +181 -55
  74. package/src/artifacts/publish-tool.ts +459 -129
  75. package/src/background-commands.ts +573 -0
  76. package/src/background-notices.ts +178 -0
  77. package/src/computer-runner.ts +211 -9
  78. package/src/context-compaction.ts +4 -1
  79. package/src/execution-plan.ts +15 -2
  80. package/src/index.ts +4 -0
  81. package/src/login-shell.ts +18 -0
  82. package/src/run-child.ts +5 -0
  83. package/src/run-conversation-turn.ts +23 -4
  84. package/src/run-environment.ts +96 -17
  85. package/src/run-sandbox.ts +41 -0
  86. package/src/sandbox-api-context.ts +1 -1
  87. package/src/sandbox-files.ts +88 -1
  88. package/src/skills/sixb-artifacts/SKILL.md +48 -25
  89. package/src/skills/sixb-artifacts/canvas.md +140 -18
  90. package/src/skills/sixb-artifacts/examples/canvas/onboarding-flow/canvas.json +1 -1
  91. package/src/skills/sixb-artifacts/page.md +1 -1
  92. package/src/skills/sixb-artifacts/references.md +15 -12
  93. package/src/skills/sixb-artifacts/sheet.md +1 -1
  94. package/src/skills/sixb-artifacts/slides.md +1 -1
  95. package/src/subagent-tools.ts +19 -7
  96. package/src/tools/background.ts +127 -0
  97. package/src/tools/bash.ts +80 -11
  98. package/src/tools/model-spec.ts +28 -5
  99. package/src/tools/tool-files.ts +3 -1
  100. package/src/tools/tool-outputs.ts +46 -6
  101. package/src/tools/web-fetch/cache.ts +91 -0
  102. package/src/tools/web-fetch/html-markdown.ts +479 -0
  103. package/src/tools/web-fetch/network.ts +452 -0
  104. package/src/tools/web-fetch/tool.ts +619 -0
  105. package/src/tools/web-search.ts +139 -0
  106. package/src/types.ts +5 -4
  107. package/src/workspace-instructions.ts +163 -0
@@ -0,0 +1,573 @@
1
+ import { randomBytes } from "node:crypto"
2
+ import { posix } from "node:path"
3
+ import { AgentToolPublicError, type CommandResult, type Sandbox } from "@sixb/core"
4
+ import { waitForAbort } from "./abort"
5
+ import { LOGIN_SHELL_SCRIPT } from "./login-shell"
6
+ import { type AgentSandboxHandle, contextPath } from "./sandbox-handle"
7
+
8
+ // A background command runs in the call that starts it, held open until it ends: a provider that
9
+ // kills what a call left behind once it returns (a cgroup, a PID namespace) leaves it alone, and
10
+ // it needs nothing of a provider but `runCommand`. It runs in a process group of its own, which
11
+ // `bash_stop` signals from inside the sandbox; the held call's abort is the fallback where another
12
+ // call cannot reach it. Its output goes to a file in the run's context directory, which the agent
13
+ // reads with `read` as any other file.
14
+
15
+ /** Where the commands' files go, in the run's context directory. */
16
+ export const BACKGROUND_DIRECTORY = "background"
17
+
18
+ /** At most this many of a run's background commands run at once. */
19
+ const MAX_RUNNING = 16
20
+
21
+ /** What one read returns of its output: its newest bytes, as `bash` bounds a stream. */
22
+ const OUTPUT_MAX_BYTES = 20_000
23
+
24
+ /**
25
+ * The held call's own bound, under every provider's 32-bit timer: a command that runs a week is
26
+ * stopped like any other.
27
+ */
28
+ const HELD_TIMEOUT_MS = 7 * 24 * 60 * 60 * 1000
29
+
30
+ /** How long a stopped command has to exit on SIGTERM before it is killed. */
31
+ const STOP_GRACE_MS = 3_000
32
+
33
+ /** The short calls that start, signal and read a command. */
34
+ const CONTROL_TIMEOUT_MS = 15_000
35
+
36
+ export type BackgroundCommandStatus = "running" | "exited" | "stopped"
37
+
38
+ /** A background command as its tools report it, and as a chat can show it. */
39
+ export interface BackgroundCommandState {
40
+ /** `bg_<hex>`: the id `bash_output` and `bash_stop` take, never the same in two runs. */
41
+ readonly id: string
42
+ readonly command: string
43
+ readonly status: BackgroundCommandStatus
44
+ /**
45
+ * Its exit code once it ended. A stopped command's is the signal's (143 for SIGTERM, 137 for
46
+ * SIGKILL), or absent when its sandbox went away under it.
47
+ */
48
+ readonly exitCode?: number
49
+ /** ISO timestamps. */
50
+ readonly startedAt: string
51
+ readonly endedAt?: string
52
+ /** The file holding everything it wrote, stdout and stderr together, as the agent names it. */
53
+ readonly outputPath: string
54
+ }
55
+
56
+ /** What `bash_output` and `bash_stop` return: its state, and what it wrote since the last read. */
57
+ export interface BackgroundCommandOutput extends BackgroundCommandState {
58
+ /** What it wrote since the last read: its newest 20,000 bytes at most. */
59
+ readonly output: string
60
+ /** What it wrote since the last read that `output` leaves out, ahead of it: in the file. */
61
+ readonly skippedBytes?: number
62
+ }
63
+
64
+ interface BackgroundCommand {
65
+ readonly id: string
66
+ readonly command: string
67
+ readonly startedAt: Date
68
+ readonly paths: { readonly output: string; readonly pid: string; readonly exit: string }
69
+ /** The sandbox it runs in, which signals it: a later run may have another. */
70
+ readonly sandbox: Sandbox
71
+ /** Aborts the held call: the provider kills what it ran. */
72
+ readonly abort: AbortController
73
+ /** Settles once its process group is known, or it ended without one. */
74
+ readonly started: Promise<void>
75
+ /** Settles once it ended, however it did. */
76
+ readonly ended: Promise<void>
77
+ /** Its process group, once it started. */
78
+ group?: number
79
+ status: BackgroundCommandStatus
80
+ exitCode?: number
81
+ endedAt?: Date
82
+ /** What the wrapper or the sandbox said, when it could not start the command. */
83
+ failure?: string
84
+ /** Its stop, once asked for. */
85
+ stopping?: Promise<void>
86
+ /** How many bytes of its output the agent has read. */
87
+ readBytes: number
88
+ /** Its end reached the model, through a tool's result or a notice. */
89
+ reported: boolean
90
+ }
91
+
92
+ /**
93
+ * The background commands of a run, or of a thread on the user's computer, where they outlive
94
+ * the turn that started them. Their state is in memory; their output, pid and exit code are files
95
+ * in the sandbox.
96
+ */
97
+ export class BackgroundCommands {
98
+ readonly #commands = new Map<string, BackgroundCommand>()
99
+
100
+ constructor(
101
+ private readonly options: {
102
+ /** Called as a command starts or ends: a computer reports its commands then. */
103
+ readonly onChange?: () => void
104
+ } = {}
105
+ ) {}
106
+
107
+ /** Whether it ever started one: their files are then worth keeping for a later turn. */
108
+ get hasCommands(): boolean {
109
+ return this.#commands.size > 0
110
+ }
111
+
112
+ /** Whether one of them runs now. */
113
+ get running(): boolean {
114
+ return [...this.#commands.values()].some((entry) => entry.status === "running")
115
+ }
116
+
117
+ /**
118
+ * Start `command` in the background and return once it runs, its output going to its file. One
119
+ * the sandbox could not start, as in a directory that does not exist, throws what it said. A
120
+ * `signal` that aborts before then stops it.
121
+ */
122
+ async start(input: {
123
+ readonly handle: AgentSandboxHandle
124
+ readonly command: string
125
+ readonly cwd?: string
126
+ readonly signal?: AbortSignal
127
+ }): Promise<BackgroundCommandState> {
128
+ const running = [...this.#commands.values()].filter((entry) => entry.status === "running")
129
+ if (running.length >= MAX_RUNNING) {
130
+ throw new AgentToolPublicError(
131
+ `[SixbAgent] ${MAX_RUNNING} background commands are running already: stop one with bash_stop first.`
132
+ )
133
+ }
134
+
135
+ const { handle } = input
136
+ const { sandbox } = handle
137
+ const id = this.#newId()
138
+ const directory = contextPath(handle, BACKGROUND_DIRECTORY)
139
+ const paths = {
140
+ output: posix.join(directory, `${id}.log`),
141
+ pid: posix.join(directory, `${id}.pid`),
142
+ exit: posix.join(directory, `${id}.exit`),
143
+ }
144
+ // The pid file names the start that wrote it: a file an earlier start left is never read.
145
+ const nonce = randomBytes(8).toString("hex")
146
+ const abort = new AbortController()
147
+
148
+ const held = sandbox.runCommand(
149
+ "bash",
150
+ [
151
+ "-c",
152
+ START_SCRIPT,
153
+ "sixb-background",
154
+ paths.output,
155
+ paths.pid,
156
+ paths.exit,
157
+ nonce,
158
+ input.command,
159
+ ],
160
+ {
161
+ ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
162
+ ...(handle.env === undefined ? {} : { env: handle.env }),
163
+ timeout: HELD_TIMEOUT_MS,
164
+ signal: abort.signal,
165
+ }
166
+ )
167
+ const ended = held.then(
168
+ (result) => this.#end(entry, result),
169
+ (error: unknown) => this.#end(entry, undefined, error)
170
+ )
171
+ // Its group is known once the wrapper wrote it, which it does first: until then nothing could
172
+ // signal it, so a stop and `start` itself wait for it, or for its end without one.
173
+ const started = Promise.race([
174
+ readGroup(sandbox, paths.pid, nonce, handle.env).then(
175
+ (group) => {
176
+ if (group !== undefined) entry.group = group
177
+ },
178
+ () => {}
179
+ ),
180
+ ended,
181
+ ])
182
+ const entry: BackgroundCommand = {
183
+ id,
184
+ command: input.command,
185
+ startedAt: new Date(),
186
+ paths,
187
+ sandbox,
188
+ abort,
189
+ started,
190
+ ended,
191
+ status: "running",
192
+ readBytes: 0,
193
+ reported: false,
194
+ }
195
+ this.#commands.set(id, entry)
196
+
197
+ try {
198
+ await waitForAbort(started, input.signal)
199
+ } catch (error) {
200
+ await this.stop(id)
201
+ throw error
202
+ }
203
+
204
+ if (entry.failure !== undefined) {
205
+ this.#commands.delete(id)
206
+ this.options.onChange?.()
207
+ throw new AgentToolPublicError(`[SixbAgent] The command could not start: ${entry.failure}`)
208
+ }
209
+ if (entry.status !== "running") entry.reported = true
210
+
211
+ this.options.onChange?.()
212
+ return state(entry)
213
+ }
214
+
215
+ /** Whether it knows a command by this id. */
216
+ has(id: string): boolean {
217
+ return this.#commands.has(id)
218
+ }
219
+
220
+ /** A command by id, or a public error the model can act on. */
221
+ get(id: string): BackgroundCommandState {
222
+ return state(this.#find(id))
223
+ }
224
+
225
+ /** Every command, oldest first. */
226
+ list(): readonly BackgroundCommandState[] {
227
+ return [...this.#commands.values()].map(state)
228
+ }
229
+
230
+ /**
231
+ * Wait until the command ends, `timeoutMs` elapses or `signal` aborts, which rejects with its
232
+ * reason.
233
+ */
234
+ async wait(id: string, timeoutMs: number, signal: AbortSignal): Promise<void> {
235
+ const entry = this.#find(id)
236
+ if (entry.status !== "running" || timeoutMs <= 0) return
237
+
238
+ signal.throwIfAborted()
239
+ await new Promise<void>((resolve, reject) => {
240
+ const timer = setTimeout(finish, timeoutMs)
241
+ void entry.ended.then(finish)
242
+ signal.addEventListener("abort", abort, { once: true })
243
+
244
+ function finish(): void {
245
+ clearTimeout(timer)
246
+ signal.removeEventListener("abort", abort)
247
+ resolve()
248
+ }
249
+ function abort(): void {
250
+ clearTimeout(timer)
251
+ reject(signal.reason)
252
+ }
253
+ })
254
+ }
255
+
256
+ /**
257
+ * Its state and what it wrote since the last read, read through `handle`: the sandbox of the run
258
+ * that asks. Once it reports the command ended, no notice repeats it.
259
+ */
260
+ async read(
261
+ id: string,
262
+ handle: AgentSandboxHandle,
263
+ signal: AbortSignal
264
+ ): Promise<BackgroundCommandOutput> {
265
+ const entry = this.#find(id)
266
+ // Its state before its output: a command that ended then wrote all it will.
267
+ const snapshot = state(entry)
268
+ const result = await handle.sandbox.runCommand(
269
+ "bash",
270
+ [
271
+ "-c",
272
+ READ_SCRIPT,
273
+ "sixb-background-read",
274
+ entry.paths.output,
275
+ String(entry.readBytes),
276
+ String(OUTPUT_MAX_BYTES),
277
+ ],
278
+ {
279
+ ...(handle.env === undefined ? {} : { env: handle.env }),
280
+ timeout: CONTROL_TIMEOUT_MS,
281
+ signal,
282
+ }
283
+ )
284
+ signal.throwIfAborted()
285
+ if (result.exitCode !== 0) {
286
+ throw new AgentToolPublicError(
287
+ `[SixbAgent] Could not read the output of ${id} at ${entry.paths.output}: ${result.stderr.trim() || `exit ${result.exitCode}`}`
288
+ )
289
+ }
290
+
291
+ const newline = result.stdout.indexOf("\n")
292
+ const size = Number(result.stdout.slice(0, newline === -1 ? undefined : newline))
293
+ const output = newline === -1 ? "" : result.stdout.slice(newline + 1)
294
+ const unread = Math.max(0, size - entry.readBytes)
295
+ const skippedBytes = Math.max(0, unread - OUTPUT_MAX_BYTES)
296
+ entry.readBytes = Math.max(entry.readBytes, size)
297
+ if (snapshot.status !== "running") entry.reported = true
298
+
299
+ return { ...snapshot, output, ...(skippedBytes > 0 ? { skippedBytes } : {}) }
300
+ }
301
+
302
+ /**
303
+ * Stop the command and everything it started: SIGTERM to its process group, SIGKILL after a
304
+ * grace period or where the sandbox cannot reach it, then the held call's abort. Resolves once
305
+ * it ended.
306
+ */
307
+ async stop(id: string): Promise<BackgroundCommandState> {
308
+ const entry = this.#find(id)
309
+ if (entry.status === "running") {
310
+ entry.stopping ??= this.#stop(entry)
311
+ await entry.stopping
312
+ }
313
+ return state(entry)
314
+ }
315
+
316
+ /** Stop every command still running. */
317
+ async stopAll(): Promise<void> {
318
+ const running = [...this.#commands.values()].filter((entry) => entry.status === "running")
319
+ await Promise.all(running.map((entry) => this.stop(entry.id)))
320
+ }
321
+
322
+ /**
323
+ * Settles once no command started in `sandbox` runs; undefined when none does now. A computer
324
+ * keeps a turn's sandbox until then.
325
+ */
326
+ endOf(sandbox: Sandbox): Promise<void> | undefined {
327
+ const running = [...this.#commands.values()].filter(
328
+ (entry) => entry.sandbox === sandbox && entry.status === "running"
329
+ )
330
+ if (running.length === 0) return undefined
331
+ return Promise.all(running.map((entry) => entry.ended)).then(() => {})
332
+ }
333
+
334
+ /** The commands that ended and the model has not heard of: each is reported once. */
335
+ takeEnded(): readonly BackgroundCommandState[] {
336
+ const ended = [...this.#commands.values()].filter(
337
+ (entry) => entry.status !== "running" && !entry.reported
338
+ )
339
+ for (const entry of ended) entry.reported = true
340
+ return ended.map(state)
341
+ }
342
+
343
+ #newId(): string {
344
+ for (;;) {
345
+ const id = `bg_${randomBytes(3).toString("hex")}`
346
+ if (!this.#commands.has(id)) return id
347
+ }
348
+ }
349
+
350
+ #find(id: string): BackgroundCommand {
351
+ const entry = this.#commands.get(id)
352
+ if (!entry) {
353
+ const known = [...this.#commands.keys()]
354
+ throw new AgentToolPublicError(
355
+ `[SixbAgent] No background command '${id}'${known.length > 0 ? `: the known ones are ${known.join(", ")}` : ""}. One an earlier run started ended with that run, or with the sixb that ran it.`
356
+ )
357
+ }
358
+ return entry
359
+ }
360
+
361
+ async #stop(entry: BackgroundCommand): Promise<void> {
362
+ // A stop asked for as it starts waits for its group: the held call's abort alone would stop
363
+ // the wrapper and leave the group it started running.
364
+ await entry.started
365
+
366
+ if (await signalGroup(entry, "TERM")) {
367
+ let timer: ReturnType<typeof setTimeout> | undefined
368
+ await Promise.race([
369
+ entry.ended,
370
+ new Promise<void>((resolve) => {
371
+ timer = setTimeout(resolve, STOP_GRACE_MS)
372
+ }),
373
+ ])
374
+ clearTimeout(timer)
375
+ }
376
+
377
+ if (entry.status === "running") {
378
+ await signalGroup(entry, "KILL")
379
+ entry.abort.abort()
380
+ await entry.ended
381
+ }
382
+ }
383
+
384
+ #end(entry: BackgroundCommand, result: CommandResult | undefined, error?: unknown): void {
385
+ entry.endedAt = new Date()
386
+ if (!result) {
387
+ // Its sandbox went away under it, or never ran it.
388
+ entry.status = "stopped"
389
+ console.warn(`[SixbAgent] Background command ${entry.id} ended with its sandbox:`, error)
390
+ this.options.onChange?.()
391
+ return
392
+ }
393
+
394
+ entry.exitCode = result.exitCode
395
+ // Stopped when a signal of its stop ended it, as its exit code says; one that exited by itself
396
+ // meanwhile, or caught the signal and exited, exited.
397
+ entry.status =
398
+ entry.stopping !== undefined && (result.exitCode > 128 || entry.abort.signal.aborted)
399
+ ? "stopped"
400
+ : "exited"
401
+ // The wrapper writes nothing of its own unless it, or the sandbox, could not run it.
402
+ if (result.stderr.trim() && entry.group === undefined) entry.failure = result.stderr.trim()
403
+
404
+ // Past its bound, the held call's abort stopped the wrapper, not the group it started.
405
+ if (result.timedOut) void signalGroup(entry, "KILL")
406
+
407
+ this.options.onChange?.()
408
+ }
409
+ }
410
+
411
+ /** A command's state, as its tools return it. */
412
+ function state(entry: BackgroundCommand): BackgroundCommandState {
413
+ return {
414
+ id: entry.id,
415
+ command: entry.command,
416
+ status: entry.status,
417
+ ...(entry.exitCode === undefined ? {} : { exitCode: entry.exitCode }),
418
+ startedAt: entry.startedAt.toISOString(),
419
+ ...(entry.endedAt === undefined ? {} : { endedAt: entry.endedAt.toISOString() }),
420
+ outputPath: entry.paths.output,
421
+ }
422
+ }
423
+
424
+ /** The process group the wrapper wrote with this start's nonce, waited for in the sandbox. */
425
+ async function readGroup(
426
+ sandbox: Sandbox,
427
+ path: string,
428
+ nonce: string,
429
+ env: Readonly<Record<string, string>> | undefined
430
+ ): Promise<number | undefined> {
431
+ const result = await sandbox.runCommand(
432
+ "bash",
433
+ ["-c", GROUP_SCRIPT, "sixb-background", path, nonce],
434
+ { ...(env === undefined ? {} : { env }), timeout: CONTROL_TIMEOUT_MS }
435
+ )
436
+ const group = Number(result.stdout.trim())
437
+ return result.exitCode === 0 && Number.isSafeInteger(group) && group > 1 ? group : undefined
438
+ }
439
+
440
+ /**
441
+ * Signal its process group from inside the sandbox it runs in. False when nothing received it:
442
+ * no group known, or one this sandbox cannot see, as a command run under a PID namespace of its
443
+ * own (bwrap): its stop is then the held call's abort, at once.
444
+ */
445
+ async function signalGroup(entry: BackgroundCommand, signal: "TERM" | "KILL"): Promise<boolean> {
446
+ if (entry.group === undefined) return false
447
+
448
+ try {
449
+ const result = await entry.sandbox.runCommand(
450
+ "bash",
451
+ ["-c", SIGNAL_SCRIPT, "sixb-background", signal, String(entry.group)],
452
+ { timeout: CONTROL_TIMEOUT_MS }
453
+ )
454
+ return result.exitCode === 0
455
+ } catch {
456
+ return false
457
+ }
458
+ }
459
+
460
+ /**
461
+ * Stop the commands a `sixb` that ended without stopping them left running: one killed, or that
462
+ * crashed. Their pid files are all that is left of them. Each group still running its command
463
+ * gets SIGTERM, then SIGKILL after the grace period `bash_stop` gives, in one call.
464
+ */
465
+ export async function stopLeftRunning(
466
+ sandbox: Sandbox,
467
+ pidFiles: readonly string[],
468
+ signal: AbortSignal
469
+ ): Promise<void> {
470
+ const result = await sandbox.runCommand(
471
+ "bash",
472
+ ["-c", REAP_SCRIPT, "sixb-background-reap", String(STOP_GRACE_MS / 50), ...pidFiles],
473
+ { timeout: CONTROL_TIMEOUT_MS, signal }
474
+ )
475
+ if (result.exitCode !== 0) {
476
+ throw new Error(`[SixbAgent] ${result.stderr.trim() || `exit ${result.exitCode}`}`)
477
+ }
478
+ }
479
+
480
+ /** Signal a process group. Arguments: the signal, the group. */
481
+ const SIGNAL_SCRIPT = 'kill -s "$1" -- "-$2" 2>/dev/null'
482
+
483
+ /**
484
+ * Started detached from the held call's own output, in a process group of its own (`set -m`: no
485
+ * `setsid` binary on macOS), its pid written first with the start's nonce, then its exit code once
486
+ * it ended. Its exit is the wrapper's. Arguments: output, pid and exit files, nonce, command.
487
+ */
488
+ const START_SCRIPT = `mkdir -p -- "$(dirname -- "$1")" || exit 1
489
+ : > "$1" && rm -f -- "$3" || exit 1
490
+ set -m
491
+ bash -lc '${LOGIN_SHELL_SCRIPT}' bash "$5" < /dev/null >> "$1" 2>&1 &
492
+ pid=$!
493
+ set +m
494
+ echo "$4 $pid" > "$2.tmp" && mv -f -- "$2.tmp" "$2"
495
+ wait "$pid"
496
+ code=$?
497
+ echo "$code" > "$3"
498
+ exit "$code"`
499
+
500
+ /** Wait up to ten seconds for the pid file this start's nonce names, then print the pid. */
501
+ const GROUP_SCRIPT = `i=0
502
+ while [ "$i" -lt 200 ]; do
503
+ { read -r nonce pid < "$1"; } 2>/dev/null && [ "$nonce" = "$2" ] && { echo "$pid"; exit 0; }
504
+ sleep 0.05
505
+ i=$((i + 1))
506
+ done
507
+ exit 1`
508
+
509
+ /**
510
+ * Print the output's size, a newline, then what follows the bytes already read: its newest
511
+ * bytes within the bound. Arguments: the file, the bytes read, the bound.
512
+ */
513
+ const READ_SCRIPT = `[ -f "$1" ] || { echo 0; exit 0; }
514
+ size=$(wc -c < "$1" | tr -d ' ')
515
+ start=$2
516
+ [ "$start" -gt "$size" ] && start=$size
517
+ [ $((size - start)) -gt "$3" ] && start=$((size - $3))
518
+ echo "$size"
519
+ [ "$size" -gt "$start" ] && tail -c +$((start + 1)) -- "$1" | head -c $((size - start))
520
+ exit 0`
521
+
522
+ /**
523
+ * SIGTERM to each group a pid file names that is still its command's, SIGKILL to those left after
524
+ * the grace period. Arguments: the grace period in 50 ms polls, then the pid files.
525
+ *
526
+ * A group is its command's only while one of its processes holds the command's output file, which
527
+ * the start opened for every process of it: a group id reused since, by anything else, holds no
528
+ * such file, and is never signalled. The start leaves nothing else to check on macOS: a command
529
+ * line keeps nothing of ours once bash runs the command in its own place, and `ps` shows no
530
+ * environment of Apple's own binaries, bash and sleep among them. Linux lists open files in
531
+ * `/proc`; macOS through `lsof`.
532
+ */
533
+ const REAP_SCRIPT = `signal() { ${SIGNAL_SCRIPT}; }
534
+ holds() {
535
+ if [ -d /proc/self/fd ]; then
536
+ for fd in "/proc/$1/fd/"*; do
537
+ [ "$(readlink "$fd" 2>/dev/null)" = "$2" ] && return 0
538
+ done
539
+ return 1
540
+ fi
541
+ lsof -a -p "$1" -- "$2" > /dev/null 2>&1
542
+ }
543
+ ours() {
544
+ case "$1" in ''|*[!0-9]*|0|1) return 1 ;; esac
545
+ for pid in $(ps -A -o pid= -o pgid= | awk -v group="$1" '$2 == group { print $1 }'); do
546
+ holds "$pid" "$2" && return 0
547
+ done
548
+ return 1
549
+ }
550
+ grace=$1
551
+ shift
552
+ termed=""
553
+ for file in "$@"; do
554
+ { read -r _ group < "$file"; } 2>/dev/null || continue
555
+ ours "$group" "\${file%.pid}.log" && signal TERM "$group" && termed="$termed $group"
556
+ done
557
+ i=0
558
+ while [ -n "$termed" ] && [ "$i" -lt "$grace" ]; do
559
+ left=""
560
+ for group in $termed; do
561
+ kill -0 -- "-$group" 2>/dev/null && left="$left $group"
562
+ done
563
+ termed=$left
564
+ [ -n "$termed" ] && sleep 0.05
565
+ i=$((i + 1))
566
+ done
567
+ for file in "$@"; do
568
+ { read -r _ group < "$file"; } 2>/dev/null || continue
569
+ case " $termed " in
570
+ *" $group "*) ours "$group" "\${file%.pid}.log" && signal KILL "$group" ;;
571
+ esac
572
+ done
573
+ exit 0`