@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/code-execution/py-runner.ts

@@ -19,6 +19,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface, type Interface } from 'node:readline';
+import { boundedErrorMessage } from '../error-message.js';
 import { PYTHON_RUNTIME_SOURCE } from './runtime-py.js';
 
 export interface InjectedTool {
@@ -91,6 +92,56 @@ export function formatLimit(ms: number): string {
   return `${Math.round(ms / 360_000) / 10} h`;
 }
 
+/**
+ * What a script stopped at its time limit is told after why: that the tool
+ * calls it made keep their effects, and whether a longer limit can help,
+ * which only the deployment's ceiling for its kind of script can say. A
+ * foreground script at its ceiling is offered background mode too, when its
+ * caller passes `backgroundCeilingMs` (the framework does for an agent that
+ * could start a background script as the script starts) and a background
+ * script may run longer.
+ */
+function limitRemedy(limitMs: number, ceilingMs: number | undefined, background: boolean, backgroundCeilingMs?: number): string {
+  const effects = 'Tool calls it had already made keep their effects, so check them before running it again.';
+  if (ceilingMs === undefined) return effects;
+  if (limitMs < ceilingMs) return `${effects} To give it longer, ${background ? 'start it with' : 'pass'} time_limit_ms up to ${ceilingMs} (${formatLimit(ceilingMs)}).`;
+  if (background) return `${effects} ${formatLimit(limitMs)} is the longest a background script runs here; starting it again runs it from the top.`;
+  const inBackground = backgroundCeilingMs !== undefined && backgroundCeilingMs > limitMs
+    ? `, or run it with background: true, where a script can run up to ${formatLimit(backgroundCeilingMs)}` : '';
+  return `${effects} ${formatLimit(limitMs)} is the longest a script can run here, so split the work across shorter scripts${inBackground}.`;
+}
+
+/**
+ * Why a script didn't run when its interpreter didn't start. A spawn that
+ * found nothing it could run (ENOENT, EACCES) fails the same way until the
+ * host changes, so that one says code_execution can't run here rather than
+ * to try again. A failure before the spawn, while creating or writing the
+ * runtime's files, is about those files rather than the interpreter, and
+ * keeps Node's own text, which names the path for an open or a mkdtemp.
+ */
+function startFailure(pythonPath: string, err: unknown): string {
+  const { code, syscall } = (err ?? {}) as { code?: unknown; syscall?: unknown };
+  const spawning = typeof syscall === 'string' && syscall.startsWith('spawn');
+  if (spawning && (code === 'ENOENT' || code === 'EACCES')) {
+    const until = code === 'ENOENT' ? 'installs it or points this host at one' : 'makes it executable or points this host at another';
+    return `script didn't run: this host can't start its Python interpreter, ${pythonPath} (${code}), so code_execution can't run scripts here until whoever runs this host ${until}. Calling it again before then fails the same way.`;
+  }
+  if (typeof syscall === 'string' && !spawning) {
+    return `script didn't run: this host couldn't create or write the files its Python runtime starts from (${boundedErrorMessage(err)}), so none of the script ran. Run it again; if it fails the same way, ask whoever runs this host.`;
+  }
+  const why = typeof code === 'string' ? `couldn't be started (${code})` : boundedErrorMessage(err);
+  return `script didn't run: the Python interpreter, ${pythonPath}, ${why}, so none of the script ran. Run it again; if it fails the same way, ask whoever runs this host.`;
+}
+
+/** Why a script stopped when its interpreter exited under it, and what running it again does. */
+function interpreterExit(exitCode: number | null, signal: NodeJS.Signals | null, background: boolean): string {
+  const how = signal ? `was ended by ${signal}` : `exited with code ${exitCode}`;
+  return `script stopped: the Python interpreter ${how} while it ran, so the rest of the script didn't run`
+    + `${background ? '' : ', and variables from earlier scripts are gone'}. Tool calls it had already made keep their effects, `
+    + 'so check them before you run it again in a new interpreter. If it stops the same way, check whether the script itself '
+    + `ends the process, for example ${signal ? 'by using too much memory' : 'with os._exit()'}; if not, ask whoever runs this host.`;
+}
+
 interface PendingExec {
   id: string;
   resolve: (result: ExecResult) => void;
@@ -101,6 +152,16 @@ interface PendingExec {
   settled: boolean;
   /** Set once the deadline fired: the result then says the script ran out of time. */
   deadlineMs: number | null;
+  /** The longest limit this exec could have had (exec's opts): whether a longer one would help. */
+  ceilingMs: number | undefined;
+  /** For a foreground exec, the longest a background script may run (exec's opts): whether background mode would help. */
+  backgroundCeilingMs: number | undefined;
+  /** A background exec has its interpreter to itself, so no earlier script's state is lost with it. */
+  background: boolean;
+  /** Set once the script went to the interpreter. Before that, the exec is
+   *  waiting for the interpreter to start, and an interpreter that exits then
+   *  failed to start (see exec). */
+  sent: boolean;
 }
 
 export class PyRunner {
@@ -121,8 +182,6 @@ export class PyRunner {
   private idleTimer: ReturnType<typeof setTimeout> | null = null;
   private execCounter = 0;
   private disposed = false;
-  /** An exec has passed the busy check but is still awaiting the interpreter. */
-  private starting = false;
 
   constructor(options: PyRunnerOptions) {
     this.pythonPath = options.pythonPath ?? 'python3';
@@ -135,7 +194,7 @@ export class PyRunner {
   }
 
   get busy(): boolean {
-    return this.pending !== null || this.starting;
+    return this.pending !== null;
   }
 
   /**
@@ -150,12 +209,18 @@ export class PyRunner {
    *
    * `opts.deadlineMs` replaces the runner's scriptTimeoutMs for this exec (a
    * per-call time limit); a background exec uses its `lifetimeMs` instead.
+   * `opts.ceilingMs` is the longest limit the deployment allows this kind of
+   * script: a script stopped at its limit is offered a longer one only below
+   * it. Without it, the stop doesn't say whether a longer limit would help.
+   * `opts.backgroundCeilingMs`, for a foreground exec, is the longest a
+   * background script may run: one stopped at its ceiling is offered
+   * background mode when that is longer.
    */
   async exec(
     code: string,
     tools: InjectedTool[],
     background?: BackgroundExecOptions,
-    opts?: { deadlineMs?: number },
+    opts?: { deadlineMs?: number; ceilingMs?: number; backgroundCeilingMs?: number },
   ): Promise<ExecResult> {
     if (this.disposed) {
       return { stdout: '', stderr: 'code_execution runner disposed', returnCode: 1, aborted: true };
@@ -163,83 +228,98 @@ export class PyRunner {
     if (this.busy) {
       return {
         stdout: '',
-        stderr: 'RuntimeError: another code_execution script is already running for this agent',
+        stderr: "script didn't run: another code_execution script of yours is already running, and they run one at a time. "
+          + 'Run this one again once that one has finished, or combine the two into one script.',
         returnCode: 1,
         aborted: true,
       };
     }
     this.clearIdleTimer();
 
-    this.starting = true; // claimed before the await: a same-tick second exec must see it
+    // The exec claims the runner before the await: a same-tick second exec
+    // sees it busy, and abort() or dispose() while the interpreter starts
+    // settles this exec, whose script then never runs.
+    let resolveResult!: (result: ExecResult) => void;
+    const settled = new Promise<ExecResult>((resolve) => {
+      resolveResult = resolve;
+    });
+    const pending: PendingExec = {
+      id: `e${++this.execCounter}`,
+      resolve: resolveResult,
+      deadlineTimer: null,
+      killTimer: null,
+      settled: false,
+      deadlineMs: null,
+      ceilingMs: opts?.ceilingMs,
+      backgroundCeilingMs: opts?.backgroundCeilingMs,
+      background: background !== undefined,
+      sent: false,
+    };
+    this.pending = pending;
     try {
       await this.ensureChild();
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.reclaim('spawn-failed');
-      return {
-        stdout: '',
-        stderr: `Failed to start python runtime (${this.pythonPath}): ${message}`,
-        returnCode: 1,
-        aborted: true,
-      };
-    } finally {
-      this.starting = false; // `pending` is set below, with no await in between
+      // Settled already when an abort or dispose reclaimed the interpreter
+      // as it started; another exec may have claimed the runner since.
+      if (!pending.settled) {
+        this.settlePending({
+          stdout: '',
+          stderr: startFailure(this.pythonPath, err),
+          returnCode: 1,
+          aborted: true,
+        });
+        this.reclaim('spawn-failed');
+      }
+      return settled;
     }
+    if (pending.settled) return settled;
 
-    const execId = `e${++this.execCounter}`;
+    const execId = pending.id;
     // Clamped: a deadline past Node's timer range would fire at once instead of never.
     const deadlineMs = Math.min(MAX_TIMER_MS, background?.lifetimeMs ?? opts?.deadlineMs ?? this.scriptTimeoutMs);
     this.onWake = background?.onWake ?? null;
-    const result = await new Promise<ExecResult>((resolve) => {
-      const pending: PendingExec = {
-        id: execId,
-        resolve,
-        deadlineTimer: null,
-        killTimer: null,
-        settled: false,
-        deadlineMs: null,
-      };
-      this.pending = pending;
-
-      pending.deadlineTimer = setTimeout(() => {
-        pending.deadlineMs = deadlineMs;
-        // Deadline: ask politely first (script sees CancelledError and its
-        // exec_result still flows back), then kill on unresponsiveness.
-        this.send({ op: 'cancel', id: execId, reason: 'deadline' });
-        // The cancel lands only when the script awaits. Blocking code (time.sleep, a
-        // busy loop, a blocking read) never does, so interrupt it as well: the runtime
-        // raises KeyboardInterrupt in the script's own code, or schedules the
-        // cancellation of a script that is waiting. Repeated, because a waiting script
-        // can resume into blocking code before that cancellation runs; the runtime
-        // ignores the repeats once the script was interrupted or cancelled.
-        this.interruptChild();
-        pending.interruptTimer = setInterval(() => this.interruptChild(), INTERRUPT_REPEAT_MS);
-        pending.killTimer = setTimeout(() => {
-          pending.deadlineMs = null; // this message already says why
-          this.settlePending({
-            stdout: '',
-            stderr:
-              `script stopped: it reached its ${formatLimit(deadlineMs)} time limit and did not respond, ` +
-              'so it was killed and the interpreter restarted (variables from earlier scripts are gone)',
-            returnCode: 1,
-            aborted: true,
-          });
-          this.reclaim('deadline-kill');
-        }, this.cancelGraceMs);
-      }, deadlineMs);
-      // A day-scale background deadline must not hold the process open.
-      if (background) pending.deadlineTimer.unref?.();
-
-      this.send({
-        op: 'init',
-        tools: tools.map((t) => ({ py_name: t.pyName, tool_name: t.toolName })),
-        call_timeout_s: Math.round(this.toolCallTimeoutMs / 1000),
-        ...(background
-          ? { background: true, log_path: background.logPath ?? null }
-          : {}),
-      });
-      this.send({ op: 'exec', id: execId, code });
+    pending.deadlineTimer = setTimeout(() => {
+      pending.deadlineMs = deadlineMs;
+      // Deadline: ask politely first (script sees CancelledError and its
+      // exec_result still flows back), then kill on unresponsiveness.
+      this.send({ op: 'cancel', id: execId, reason: 'deadline' });
+      // The cancel lands only when the script awaits. Blocking code (time.sleep, a
+      // busy loop, a blocking read) never does, so interrupt it as well: the runtime
+      // raises KeyboardInterrupt in the script's own code, or schedules the
+      // cancellation of a script that is waiting. Repeated, because a waiting script
+      // can resume into blocking code before that cancellation runs; the runtime
+      // ignores the repeats once the script was interrupted or cancelled.
+      this.interruptChild();
+      pending.interruptTimer = setInterval(() => this.interruptChild(), INTERRUPT_REPEAT_MS);
+      pending.killTimer = setTimeout(() => {
+        pending.deadlineMs = null; // this message already says why
+        this.settlePending({
+          stdout: '',
+          stderr:
+            `script stopped: it reached its ${formatLimit(deadlineMs)} time limit and did not respond, so it was killed` +
+            (pending.background ? '. ' : ' and the interpreter restarted (variables from earlier scripts are gone). ') +
+            limitRemedy(deadlineMs, pending.ceilingMs, pending.background, pending.backgroundCeilingMs),
+          returnCode: 1,
+          aborted: true,
+        });
+        this.reclaim('deadline-kill');
+      }, this.cancelGraceMs);
+    }, deadlineMs);
+    // A day-scale background deadline must not hold the process open.
+    if (background) pending.deadlineTimer.unref?.();
+
+    pending.sent = true;
+    this.send({
+      op: 'init',
+      tools: tools.map((t) => ({ py_name: t.pyName, tool_name: t.toolName })),
+      call_timeout_s: Math.round(this.toolCallTimeoutMs / 1000),
+      ...(background
+        ? { background: true, log_path: background.logPath ?? null }
+        : {}),
     });
+    this.send({ op: 'exec', id: execId, code });
+
+    const result = await settled;
 
     this.onWake = null;
     if (!background) this.armIdleTimer();
@@ -247,9 +327,12 @@ export class PyRunner {
   }
 
   /**
-   * Abort a running script (turn cancelled, agent reset/stopped). The
-   * interpreter is reclaimed: after an abort its state is suspect (a script
-   * died midway), and the next exec gets a fresh one.
+   * Abort the runner's script (its turn ended or is reset to run again, or the
+   * agent was reset or stopped), whether it's running or still waiting for its
+   * interpreter to start; a waiting script then never runs. The exec settles
+   * at once, and the interpreter is reclaimed, a starting one too: after an
+   * abort its state is suspect (a script died midway), and the next exec gets
+   * a fresh one.
    */
   abort(reason: string): void {
     if (!this.pending) return;
@@ -302,16 +385,38 @@ export class PyRunner {
       console.error(`[pytc:${this.label}] ${chunk.trimEnd()}`);
     });
 
+    // A write to an interpreter that no longer reads its input fails on the
+    // stream after write() returns; with no listener, that error is thrown as
+    // an uncaught exception. Such an interpreter can go on running, as after a
+    // script closes file descriptor 0, and every later message to it is lost:
+    // its exec would wait out its time limit. So end it, and its exit settles
+    // the exec now. One already dead or killed is left to its own exit.
+    let inputFailed = false;
+    child.stdin.on('error', (err) => {
+      console.error(`[pytc:${this.label}] write to the python runtime failed: ${err.message}`);
+      if (child.exitCode === null && !child.killed && child.pid !== undefined) {
+        inputFailed = true;
+        child.kill('SIGKILL');
+      }
+    });
+
     child.on('error', (err) => {
       // Spawn failure lands here (e.g. python3 missing); readiness rejects.
       console.error(`[pytc:${this.label}] python process error: ${err.message}`);
     });
 
     child.on('exit', (exitCode, signal) => {
-      if (this.pending) {
+      // An exec still waiting for the interpreter is settled by exec, as a
+      // runtime that failed to start.
+      if (this.pending?.sent) {
         this.settlePending({
           stdout: '',
-          stderr: `python runtime exited unexpectedly (code=${exitCode}, signal=${signal ?? 'none'})`,
+          stderr:
+            inputFailed && signal === 'SIGKILL'
+              ? 'python runtime stopped reading its input, so it was killed and the interpreter restarted ' +
+                '(variables from earlier scripts are gone). A script that closes its standard input ' +
+                '(file descriptor 0) does this.'
+              : interpreterExit(exitCode, signal, this.pending.background),
           returnCode: 1,
           aborted: true,
         });
@@ -331,7 +436,7 @@ export class PyRunner {
       };
       const onExit = () => {
         cleanup();
-        reject(new Error('python runtime exited before becoming ready'));
+        reject(new Error('exited as it started'));
       };
       const onError = (err: Error) => {
         cleanup();
@@ -339,15 +444,17 @@ export class PyRunner {
       };
       const timeout = setTimeout(() => {
         cleanup();
-        reject(new Error('python runtime did not become ready within 15s'));
+        reject(new Error("didn't start within 15 seconds"));
       }, 15_000);
       const cleanup = () => {
         clearTimeout(timeout);
         this.readyResolver = null;
+        this.readyFailer = null;
         child.off('exit', onExit);
         child.off('error', onError);
       };
       this.readyResolver = onReady;
+      this.readyFailer = onError;
       child.on('exit', onExit);
       child.on('error', onError);
     });
@@ -355,6 +462,8 @@ export class PyRunner {
   }
 
   private readyResolver: (() => void) | null = null;
+  /** Fails the readiness of an interpreter that is still starting (see reclaim). */
+  private readyFailer: ((err: Error) => void) | null = null;
 
   private handleLine(line: string, child: ChildProcessWithoutNullStreams): void {
     let msg: { op?: string; id?: string; name?: string; args?: unknown; stdout?: string; stderr?: string; return_code?: number };
@@ -431,9 +540,12 @@ export class PyRunner {
     // Only a script that ended unsuccessfully was stopped: one that caught the cancellation
     // and finished its work returns 0, and must not read as stopped.
     if (pending.deadlineMs !== null && result.returnCode !== 0) {
-      const note = `script stopped: it reached its ${formatLimit(pending.deadlineMs)} time limit\n`;
+      const note = `script stopped: it reached its ${formatLimit(pending.deadlineMs)} time limit. `
+        + `${limitRemedy(pending.deadlineMs, pending.ceilingMs, pending.background, pending.backgroundCeilingMs)}\n`;
+      // On a line of its own: the runner's own texts, such as an interpreter's exit, end without a newline.
+      const withNote = (text: string) => (text === '' || text.endsWith('\n') ? text : `${text}\n`) + note;
       // A background script reports its output tail, so the note goes there too.
-      result = { ...result, stderr: result.stderr + note, ...(result.tail !== undefined ? { tail: result.tail + note } : {}) };
+      result = { ...result, stderr: withNote(result.stderr), ...(result.tail !== undefined ? { tail: withNote(result.tail) } : {}) };
     }
     if (pending.deadlineTimer) clearTimeout(pending.deadlineTimer);
     if (pending.killTimer) clearTimeout(pending.killTimer);
@@ -492,6 +604,12 @@ export class PyRunner {
     if (this.child) {
       console.error(`[pytc:${this.label}] reclaiming python interpreter (${reason})`);
     }
+    // An interpreter killed as it starts never says it's ready: fail its
+    // readiness now, so an exec waiting on it returns at once rather than at
+    // the 15 s timeout. Here rather than in teardownChild, which an
+    // interpreter's own exit also runs, so that one still reads "exited as
+    // it started".
+    this.readyFailer?.(new Error(`python runtime reclaimed (${reason}) before it was ready`));
     this.teardownChild();
     this.clearIdleTimer();
   }
@@ -506,13 +624,19 @@ export class PyRunner {
       this.child = null;
       this.childReady = null;
       this.readyResolver = null;
+      this.readyFailer = null;
       child.removeAllListeners('exit');
       try {
         child.stdin.end();
       } catch {
         // stream may already be destroyed
       }
-      if (child.exitCode === null && !child.killed) {
+      // A child whose spawn failed has no pid, and its exitCode stays null
+      // until Node's 'error' for it, a tick later. A kill() in that tick, as
+      // from an abort or dispose on the tick exec was called, signals no
+      // child of ours but whatever pid Node's handle held: the host's own
+      // process group on Node 20.20.2, another process's pid on 24.19.
+      if (child.exitCode === null && !child.killed && child.pid !== undefined) {
         child.kill('SIGKILL');
       }
     }

package/src/code-execution/runtime-py.ts

@@ -259,15 +259,61 @@ def _resolve(fut, value):
             pass
 
 
+def _brief(value):
+    # A value as a refusal shows it: by its type, such as <str>, which fails
+    # loudly if copied rather than sending something else. The agent has its
+    # values in the call it just wrote. No value's own code runs here: its
+    # __repr__ isn't called, and its type is named through type's own
+    # descriptor, so a metaclass's __name__ doesn't run either.
+    return "<" + type.__dict__["__name__"].__get__(type(value)) + ">"
+
+
 def _make_tool_fn(tool_name, py_name):
-    async def tool_fn(args=None):
+    async def tool_fn(*positional, **kwargs):
         global _next_tool_call_id
+        if len(positional) > 1:
+            raise TypeError(
+                py_name + " wasn't called: a tool function takes one dict of "
+                "arguments, such as await " + py_name + "({...}), and this call "
+                "gave it " + str(len(positional)) + " positional arguments"
+            )
+        # args= on its own is the dict, as it has always been. Beside other
+        # keywords it's one of them, since a tool such as utils has a field
+        # of that name, so the suggested dict keeps it.
+        if positional:
+            args = positional[0]
+        elif list(kwargs) == ["args"]:
+            args = kwargs.pop("args")
+        else:
+            args = None
+        if kwargs:
+            if args is not None and not isinstance(args, dict):
+                raise TypeError(
+                    py_name + " wasn't called: a tool function takes one dict of "
+                    "arguments, not keyword arguments, and this call also gave it "
+                    + _brief(args) + ", so put every argument in one dict: await "
+                    + py_name + "({...})"
+                )
+            # The likely intent is plain: the same arguments in one dict.
+            meant = dict(args) if isinstance(args, dict) else {}
+            meant.update(kwargs)
+            # A key is what the agent has to write, so a str key is shown
+            # whole up to 60 characters, as names are elsewhere; a longer one,
+            # or any other key, is shown as a value is.
+            shown = ", ".join((repr(k) if type(k) is str and len(k) <= 60 else _brief(k)) + ": " + _brief(v)
+                              for k, v in meant.items())
+            raise TypeError(
+                py_name + " wasn't called: a tool function takes one dict of "
+                "arguments, not keyword arguments, so write await "
+                + py_name + "({" + shown + "})"
+            )
         if args is None:
             args = {}
         if not isinstance(args, dict):
             raise TypeError(
-                "tool functions take a single dict of arguments, e.g. await "
-                + py_name + "({...})"
+                py_name + " wasn't called: a tool function takes one dict of "
+                "arguments, such as await " + py_name + "({...}), and this call "
+                "gave it " + _brief(args)
             )
         _next_tool_call_id += 1
         call_id = "t" + str(_next_tool_call_id)

package/src/code-execution/tool-definition.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ToolDefinition } from '../types/index.js';
+import { assertBooleanSetting, holdsSettings } from '../config-checks.js';
 import { formatLimit, MAX_TIMER_MS } from './py-runner.js';
 
 export const CODE_EXECUTION_TOOL_NAME = 'code_execution';
@@ -106,15 +107,38 @@ export function scriptTimeLimits(opts?: {
   const defaultMs = Math.min(MAX_TIMER_MS, opts?.scriptTimeoutMs ?? 600_000);
   return {
     defaultMs,
-    // A ceiling below the default is refused when the framework is created
-    // (validateCodeExecutionConfig); never below the default here either.
+    // A ceiling below the default is refused when a framework with code
+    // execution on is created (validateCodeExecutionConfig); never below the
+    // default here either.
     maxMs: Math.min(MAX_TIMER_MS, Math.max(defaultMs, opts?.maxScriptTimeoutMs ?? defaultMs)),
     backgroundMaxMs: Math.min(MAX_TIMER_MS, opts?.backgroundMaxLifetimeMs ?? 86_400_000),
   };
 }
 
-/** Refuse a configuration whose time limits contradict each other. */
-export function validateCodeExecutionConfig(cfg: { scriptTimeoutMs?: number; maxScriptTimeoutMs?: number }): void {
+/**
+ * Refuse a codeExecution that isn't an object, or whose switch is set to
+ * anything but true or false, and, once it's on, one whose time limits
+ * contradict each other. A JSON config, or a `${VAR}` substituted as a string,
+ * can carry a quoted "false" where the type says boolean, and only `true` turns
+ * code execution on, so the quotes would hide what the value does; a bare
+ * `codeExecution: true` would be read as off. A null or false codeExecution,
+ * and a null switch, count as not set, as left-out ones do. The refusal names
+ * the value's kind, not the value. A configuration that isn't on has nothing
+ * else read.
+ */
+export function validateCodeExecutionConfig(cfg: {
+  enabled?: unknown;
+  scriptTimeoutMs?: number;
+  maxScriptTimeoutMs?: number;
+}): void {
+  if (!holdsSettings('codeExecution', cfg, '{ enabled: true }')) return;
+  assertBooleanSetting(
+    'codeExecution.enabled',
+    cfg.enabled,
+    'true gives agents the code_execution tool, which runs their scripts in a python interpreter on the host, ' +
+      'and false or leaving it out doesn\'t',
+  );
+  if (cfg.enabled !== true) return;
   const defaultMs = cfg.scriptTimeoutMs ?? 600_000;
   if (cfg.maxScriptTimeoutMs !== undefined && !(cfg.maxScriptTimeoutMs >= defaultMs)) {
     throw new Error(

package/src/config-checks.ts

@@ -0,0 +1,48 @@
+/**
+ * Refusals shared by the configuration checks. A setting read by truthiness
+ * turns on for a quoted "false", and a settings object such as `true`, which
+ * isn't an object, has every setting in it read as left out. A JSON config,
+ * or a `${VAR}` substituted as a string, can carry either where the type says
+ * otherwise, so each refusal says what the value would have done. Each names
+ * the setting and the value's kind, never the value, which could be a secret
+ * pasted into the wrong field.
+ */
+
+/** The kind of a value that isn't undefined, null or a boolean, as a refusal
+ *  names it in place of the value. */
+export function kindOf(value: unknown): string {
+  if (Array.isArray(value)) return 'an array';
+  if (typeof value !== 'object') return `a ${typeof value}`;
+  const prototype = Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null;
+  if (prototype === null || prototype === Object.prototype) return 'an object';
+  const name = prototype.constructor?.name;
+  if (!name) return 'an object that isn\'t plain';
+  return `${/^[aeiou]/i.test(name) ? 'an' : 'a'} ${name}`;
+}
+
+/**
+ * Refuse a boolean setting that holds anything but true or false. null counts
+ * as not set, as leaving it out does, so a generated config that writes an
+ * unset setting as null keeps working. `whatItDoes` ends the refusal: what
+ * true does, and what false or leaving it out does.
+ */
+export function assertBooleanSetting(setting: string, value: unknown, whatItDoes: string): void {
+  if (value === undefined || value === null || typeof value === 'boolean') return;
+  const wanted = typeof value === 'string' ? 'true or false, unquoted,' : 'true or false,';
+  throw new Error(`${setting} must be ${wanted} not ${kindOf(value)}: ${whatItDoes}`);
+}
+
+/**
+ * Whether a settings object holds settings to check: false when it's null,
+ * false or left out, which count as not set. Each of those has every setting
+ * in it read as left out, which is what null and false ask for. Anything else
+ * that isn't an object, `true` and an array included, is refused, since every
+ * setting in it would read as left out too, whatever it says.
+ */
+export function holdsSettings<T>(setting: string, value: T, example: string): value is NonNullable<T> {
+  if (value === undefined || value === null || value === false) return false;
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${setting} must be an object, such as ${example}, not ${kindOf(value)}`);
+  }
+  return true;
+}

package/src/deadline-timer.ts

@@ -0,0 +1,44 @@
+/** The longest delay one setTimeout holds (2^31 - 1 ms, about 24.8 days).
+ *  Node fires a longer one almost at once, with a TimeoutOverflowWarning. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+type Hold = (timer: ReturnType<typeof setTimeout>) => void;
+
+/**
+ * Call `fire` at `deadlineMs` (epoch ms) by the wall clock, through timers no
+ * longer than one holds, so a deadline weeks away fires then rather than at
+ * once. When a step ends, it reads the wall clock against the deadline and
+ * arms the next for what's left, so the steps' own delays don't add up, and a
+ * process that restarts and arms the same stored deadline aims at the same
+ * time. A step's own wait runs on Node's monotonic clock, so a change to the
+ * wall clock during a step is seen when that step ends. `hold` gets each
+ * step's timer: clearing the latest one stops the rest.
+ */
+export function armAt(deadlineMs: number, hold: Hold, fire: () => void): void {
+  const arm = (): void => {
+    // A deadline that has just passed arms a 0 ms step rather than a negative
+    // one, which Node 23 and later warn about.
+    hold(setTimeout(step, Math.min(Math.max(0, deadlineMs - Date.now()), MAX_TIMER_MS)));
+  };
+  const step = (): void => {
+    if (deadlineMs - Date.now() > 0) arm();
+    else fire();
+  };
+  arm();
+}
+
+/**
+ * Call `fire` after `delayMs`, counted on timers no longer than one holds, so
+ * a delay weeks long fires then rather than at once. The timers count the
+ * time, so setting the wall clock doesn't move it. `hold` gets each step's
+ * timer: clearing the latest one stops the rest.
+ */
+export function armAfter(delayMs: number, hold: Hold, fire: () => void): void {
+  let left = delayMs;
+  const arm = (): void => {
+    const step = Math.min(left, MAX_TIMER_MS);
+    left -= step;
+    hold(setTimeout(left > 0 ? arm : fire, step));
+  };
+  arm();
+}