@spunto/build 0.16.0 → 0.17.0

package/src/commands/index.ts

@@ -0,0 +1,205 @@
+/**
+ * Background commands inside a box — the scripts, not the transport. Whoever can run a shell in
+ * the box (`docker exec`, the in-box agent's `exec`) runs these and parses what they print.
+ *
+ * The state of a command lives **in the box**, not in the control plane: it can restart (or be
+ * redeployed) mid-run, and the next poll picks the output back up from the files. **The layout is
+ * a format, not a preference** — a task started before a release must still be read after it:
+ *
+ *   ~/.spunto/commands/<id>/cmd.sh      the command, verbatim
+ *   ~/.spunto/commands/<id>/run.sh      the wrapper (cd + timeout + exit code)
+ *   ~/.spunto/commands/<id>/stdin       a FIFO, for an interactive harness only
+ *   ~/.spunto/commands/<id>/stdout.log  stdout of the wrapper
+ *   ~/.spunto/commands/<id>/stderr.log  stderr of the wrapper
+ *   ~/.spunto/commands/<id>/pid         pid of the wrapper, for cancellation
+ *   ~/.spunto/commands/<id>/exit_code   written last — its presence means "done"
+ *
+ * Every script prints `KEY:value` lines (`commandFields`), base64 for anything that is bytes.
+ */
+
+/** Where a box keeps the state of its background commands (inside $HOME). */
+export const COMMANDS_DIR = "$HOME/.spunto/commands"
+/** How long finished command directories are kept in the box before pruning. */
+export const COMMAND_RETENTION_DAYS = 7
+/** Default tail of each stream a poll returns. */
+export const DEFAULT_POLL_OUTPUT_BYTES = 64 * 1024
+/** Ceiling on one read — base64 inflates it by a third on the wire. */
+export const MAX_READ_BYTES = 256 * 1024
+
+/** POSIX single-quote quoting — the only safe way to inject a value into a shell string. */
+const shq = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+function base64(s: string): string {
+  const bytes = new TextEncoder().encode(s)
+  let bin = ""
+  for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  return btoa(bin)
+}
+
+/**
+ * Command ids end up in a shell-built path inside the box, so they are checked rather than trusted,
+ * whatever the caller sends. A security boundary, like `sanitizeSessionName`.
+ */
+export const isCommandId = (id: string) => /^[a-z0-9]{1,64}$/.test(id)
+
+export class InvalidCommandIdError extends Error {
+  constructor(id: string) {
+    super(`Invalid command id ${id}`)
+    this.name = "InvalidCommandIdError"
+  }
+}
+
+function dirOf(commandId: string): string {
+  if (!isCommandId(commandId)) throw new InvalidCommandIdError(commandId)
+  return `${COMMANDS_DIR}/${commandId}`
+}
+
+export type StartCommandScript = {
+  commandId: string
+  command: string
+  cwd: string
+  /** Exported in the wrapper, so the command itself sees it — not just the exec that launched it. */
+  env?: Record<string, string>
+  timeoutMs: number
+  /**
+   * A writable stdin — a FIFO under the command's directory, appended to with `stdinScript`. For a
+   * harness that reads instructions as a stream and stays alive between turns.
+   */
+  stdin?: boolean
+}
+
+/**
+ * Write the command and its wrapper into the box, detach it, print its pid. `setsid` puts the
+ * wrapper in its own process group so a cancel takes the whole tree down; an image without it gets
+ * `nohup`.
+ */
+export function startScript(p: StartCommandScript): string {
+  const dir = dirOf(p.commandId)
+  const timeoutSec = Math.max(1, Math.ceil(p.timeoutMs / 1000))
+  const exports = Object.entries(p.env ?? {})
+    .map(([k, v]) => `export ${k}=${shq(v)}`)
+    .join("\n")
+  // A file rather than an inline `-c`: the detached process depends on nothing of the exec that
+  // launched it, and `cmd.sh` stays readable in the box for whoever debugs a run afterwards.
+  // `exec 9<>fifo` is the load-bearing line of interactive mode: opening a FIFO for writing blocks
+  // until a reader shows up (`<>` never does), and holding it open for the wrapper's whole life is
+  // what stops the harness from seeing EOF between two turns.
+  const runner = [
+    `#!/usr/bin/env bash`,
+    exports,
+    `cd ${shq(p.cwd)} 2>/dev/null || cd "$HOME"`,
+    ...(p.stdin
+      ? [`exec 9<>"$(dirname "$0")/stdin"`, `timeout -k 5 ${timeoutSec}s bash -l "$(dirname "$0")/cmd.sh" < "$(dirname "$0")/stdin"`]
+      : [`timeout -k 5 ${timeoutSec}s bash -l "$(dirname "$0")/cmd.sh"`]),
+    `echo $? > "$(dirname "$0")/exit_code"`,
+  ].join("\n")
+  return [
+    `set -e`,
+    `mkdir -p ${dir}`,
+    ...(p.stdin ? [`[ -p ${dir}/stdin ] || mkfifo ${dir}/stdin`] : []),
+    // A box is long-lived: its command log must not grow forever.
+    `find ${COMMANDS_DIR} -mindepth 1 -maxdepth 1 -type d -mtime +${COMMAND_RETENTION_DAYS} -exec rm -rf {} + 2>/dev/null || true`,
+    `printf %s ${shq(base64(p.command))} | base64 -d > ${dir}/cmd.sh`,
+    `printf %s ${shq(base64(runner))} | base64 -d > ${dir}/run.sh`,
+    `: > ${dir}/stdout.log`,
+    `: > ${dir}/stderr.log`,
+    `if command -v setsid >/dev/null 2>&1; then`,
+    `  setsid bash ${dir}/run.sh > ${dir}/stdout.log 2> ${dir}/stderr.log < /dev/null &`,
+    `else`,
+    `  nohup bash ${dir}/run.sh > ${dir}/stdout.log 2> ${dir}/stderr.log < /dev/null &`,
+    `fi`,
+    `echo $! > ${dir}/pid`,
+    `cat ${dir}/pid`,
+  ].join("\n")
+}
+
+/**
+ * The state of a command and the tail of both streams. `exit_code` is written last by the wrapper,
+ * so its presence is the completion signal — the pid alone would call a command finished the
+ * instant its shell is replaced by an exec'd child.
+ * Prints `FOUND`, `EXIT` (`-` while running), `ALIVE`, `SIZEOUT`, `SIZEERR`, `OUT`, `ERR` (base64).
+ */
+export function pollScript(commandId: string, maxOutputBytes = DEFAULT_POLL_OUTPUT_BYTES): string {
+  const dir = dirOf(commandId)
+  return [
+    `if [ ! -d ${dir} ]; then echo "FOUND:0"; exit 0; fi`,
+    `echo "FOUND:1"`,
+    `if [ -f ${dir}/exit_code ]; then echo "EXIT:$(cat ${dir}/exit_code)"; else echo "EXIT:-"; fi`,
+    `pid=$(cat ${dir}/pid 2>/dev/null || echo "")`,
+    `if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then echo "ALIVE:1"; else echo "ALIVE:0"; fi`,
+    `echo "SIZEOUT:$(wc -c < ${dir}/stdout.log 2>/dev/null || echo 0)"`,
+    `echo "SIZEERR:$(wc -c < ${dir}/stderr.log 2>/dev/null || echo 0)"`,
+    `echo "OUT:$(tail -c ${maxOutputBytes} ${dir}/stdout.log 2>/dev/null | base64 | tr -d '\\n')"`,
+    `echo "ERR:$(tail -c ${maxOutputBytes} ${dir}/stderr.log 2>/dev/null | base64 | tr -d '\\n')"`,
+  ].join("\n")
+}
+
+/**
+ * A byte range of stdout, from `offset` on — for a reader that keeps a cursor (a harness streaming
+ * JSONL): every line, exactly once. Prints `FOUND`, `SIZE`, `EXIT`, `ALIVE`, `DATA` (base64).
+ */
+export function readScript(commandId: string, offset: number, maxBytes: number): string {
+  const dir = dirOf(commandId)
+  const from = Math.max(0, Math.floor(offset))
+  const bytes = Math.max(1, Math.floor(maxBytes))
+  return [
+    `if [ ! -d ${dir} ]; then echo "FOUND:0"; exit 0; fi`,
+    `echo "FOUND:1"`,
+    `echo "SIZE:$(wc -c < ${dir}/stdout.log 2>/dev/null || echo 0)"`,
+    `if [ -f ${dir}/exit_code ]; then echo "EXIT:$(cat ${dir}/exit_code)"; else echo "EXIT:-"; fi`,
+    `pid=$(cat ${dir}/pid 2>/dev/null || echo "")`,
+    `if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then echo "ALIVE:1"; else echo "ALIVE:0"; fi`,
+    // `tail -c +N` counts bytes from 1, so an offset of 0 is `+1`.
+    `echo "DATA:$(tail -c +${from + 1} ${dir}/stdout.log 2>/dev/null | head -c ${bytes} | base64 | tr -d '\\n')"`,
+  ].join("\n")
+}
+
+/**
+ * Append to a command's stdin FIFO (`dataB64`: the exact bytes, newline included). The wrapper holds
+ * the FIFO open, so there is always a reader; a write under PIPE_BUF (4 KiB) is atomic. Prints `WRITTEN`.
+ */
+export function stdinScript(commandId: string, dataB64: string): string {
+  const dir = dirOf(commandId)
+  return [`if [ ! -p ${dir}/stdin ]; then echo "WRITTEN:0"; exit 0; fi`, `printf %s ${shq(dataB64)} | base64 -d > ${dir}/stdin`, `echo "WRITTEN:1"`].join("\n")
+}
+
+/**
+ * TERM to the whole process group, then a KILL sweep for anything that ignored it. The wrapper is
+ * gone after that, so the cancellation is recorded as exit 143 for a later poll. Prints `SIGNALLED`.
+ */
+export function cancelScript(commandId: string): string {
+  const dir = dirOf(commandId)
+  return [
+    `pid=$(cat ${dir}/pid 2>/dev/null || echo "")`,
+    `[ -z "$pid" ] && { echo "SIGNALLED:0"; exit 0; }`,
+    `pgid=$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ')`,
+    `if [ -n "$pgid" ]; then kill -TERM -"$pgid" 2>/dev/null || true; fi`,
+    `kill -TERM "$pid" 2>/dev/null || true`,
+    `sleep 2`,
+    `if [ -n "$pgid" ]; then kill -KILL -"$pgid" 2>/dev/null || true; fi`,
+    `kill -KILL "$pid" 2>/dev/null || true`,
+    `[ -f ${dir}/exit_code ] || echo 143 > ${dir}/exit_code`,
+    `echo "SIGNALLED:1"`,
+  ].join("\n")
+}
+
+/** The `KEY:value` lines the scripts above print. */
+export function commandFields(stdout: string): Map<string, string> {
+  const fields = new Map<string, string>()
+  for (const line of stdout.split("\n")) {
+    const idx = line.indexOf(":")
+    if (idx > 0) fields.set(line.slice(0, idx), line.slice(idx + 1).trim())
+  }
+  return fields
+}
+
+/** `EXIT` of a poll or a read: null while the command runs (or its wrapper died without one). */
+export function commandExitCode(fields: Map<string, string>): number | null {
+  const raw = fields.get("EXIT")
+  if (!raw || raw === "-") return null
+  const n = parseInt(raw, 10)
+  return Number.isFinite(n) ? n : null
+}
+
+/** A wrapper still alive with an exit code already written is finishing up: done, not running. */
+export const commandRunning = (fields: Map<string, string>) => commandExitCode(fields) === null && fields.get("ALIVE") === "1"

package/src/index.ts

@@ -14,3 +14,6 @@ export * from "./catalogs/index"
 export * from "./script/index"
 export * from "./terminal/index"
 export * from "./agent-stream/index"
+export * from "./agent-protocol/index"
+export * from "./agent-connection/index"
+export * from "./commands/index"