@animalabs/agent-framework 0.22.2 → 0.23.0

package/dist/src/code-execution/runtime-py.js

@@ -7,7 +7,8 @@
  *
  *   - scripts run with top-level `await` (PyCF_ALLOW_TOP_LEVEL_AWAIT)
  *   - host tools are injected as async functions taking a single dict and
- *     returning a string (the tool_result text)
+ *     returning the tool_result text as a str (ToolResult), which also
+ *     carries .is_error and .structured
  *   - a pending tool call that gets no response raises TimeoutError with the
  *     same message shape the managed runtime produces
  *   - interpreter globals persist across execs (container-reuse semantics)
@@ -29,7 +30,7 @@
  *   host -> py : {op:"init", tools:[{py_name,tool_name}], call_timeout_s,
  *                 background?, log_path?, tail_chars?}
  *                {op:"exec", id, code}
- *                {op:"tool_result", id, result}
+ *                {op:"tool_result", id, result, is_error?, structured_json?}
  *                {op:"wake_ack", id, error?}
  *                {op:"cancel", id, reason?}
  *   py -> host : {op:"ready"}
@@ -48,10 +49,12 @@
 export const PYTHON_RUNTIME_SOURCE = String.raw `
 import ast
 import asyncio
+import functools
 import inspect
 import io
 import json
 import os
+import re
 import signal
 import sys
 import threading
@@ -69,9 +72,16 @@ TAIL_CHARS = 4000
 
 _send_lock = threading.Lock()
 
+# A str can hold a lone surrogate, which UTF-8 can't encode: on POSIX,
+# os.fsdecode makes one of each byte in a filename that doesn't decode as
+# UTF-8, and json.loads makes one of a "\ud800" escape. PYTHONIOENCODING makes
+# the protocol channel strict UTF-8, so writing one would fail the whole
+# message, and a script's result would never arrive. Each goes as U+FFFD.
+_LONE_SURROGATE = re.compile(r"[\ud800-\udfff]")
+
 
 def send(obj):
-    line = json.dumps(obj, ensure_ascii=False, default=str)
+    line = _LONE_SURROGATE.sub("\ufffd", json.dumps(obj, ensure_ascii=False, default=str))
     with _send_lock:
         PROTO_OUT.write(line + "\n")
         PROTO_OUT.flush()
@@ -249,6 +259,31 @@ def _deliver_cancel(st):
     st.task.cancel()
 
 
+class ToolResult(str):
+    """A tool's result: the string the tool gave, with two attributes.
+
+    is_error: True if the result is an error, False if not, None if the
+    host didn't say.
+    structured: the parsed structuredContent of a structured result's JSON
+    object, or None.
+    """
+
+    # Defaults, since pickle and copy rebuild a str subclass from its text
+    # alone and then restore the attributes.
+    def __new__(cls, text="", is_error=None, structured_json=False):
+        self = str.__new__(cls, text)
+        self.is_error = is_error
+        self._structured_json = structured_json
+        return self
+
+    # Read from the string itself, the one copy sent, on first use only.
+    @functools.cached_property
+    def structured(self):
+        if not self._structured_json:
+            return None
+        return json.loads(self).get("structuredContent")
+
+
 def _resolve(fut, value):
     # Defense in depth: the script may have been cancelled since the lookup.
     if fut is not None and not fut.done():
@@ -258,15 +293,62 @@ 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. A tool's result counts
+            # as a str: ToolResult keeps str's repr, so no script code runs.
+            shown = ", ".join((repr(k) if (type(k) is str or type(k) is ToolResult) 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)
@@ -292,7 +374,8 @@ def _make_tool_fn(tool_name, py_name):
     tool_fn.__qualname__ = py_name
     tool_fn.__doc__ = (
         "Host tool '" + tool_name + "'. Takes a single dict of arguments and "
-        "returns the tool result as a string."
+        "returns the tool result as a string, with .is_error and .structured "
+        "beside it."
     )
     return tool_fn
 
@@ -482,7 +565,10 @@ def _dispatch(msg):
         )
         st.task = _current_exec_task
     elif op == "tool_result":
-        _resolve(_pending_tool_futures.get(msg.get("id")), str(msg.get("result", "")))
+        _resolve(
+            _pending_tool_futures.get(msg.get("id")),
+            ToolResult(str(msg.get("result", "")), msg.get("is_error"), msg.get("structured_json") is True),
+        )
     elif op == "wake_ack":
         _resolve(_pending_wake_futures.get(msg.get("id")), msg.get("error") or None)
     elif op == "cancel":

package/dist/src/code-execution/runtime-py.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-py.js","sourceRoot":"","sources":["../../../src/code-execution/runtime-py.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8hBtD,CAAC"}
+{"version":3,"file":"runtime-py.js","sourceRoot":"","sources":["../../../src/code-execution/runtime-py.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmnBtD,CAAC"}

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

@@ -29,9 +29,25 @@ export declare function scriptTimeLimits(opts?: {
     maxMs: number;
     backgroundMaxMs: number;
 };
-/** Refuse a configuration whose time limits contradict each other. */
+/**
+ * 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 or whose interpreter environment would be misread. 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. Likewise the runner passes the
+ * host's environment only for an `inheritEnv` of `true`, so a quoted "true"
+ * would quietly keep the allowlist. A null or false codeExecution, and a null
+ * setting, 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 declare function validateCodeExecutionConfig(cfg: {
+    enabled?: unknown;
     scriptTimeoutMs?: number;
     maxScriptTimeoutMs?: number;
+    env?: unknown;
+    inheritEnv?: unknown;
 }): void;
 //# sourceMappingURL=tool-definition.d.ts.map

package/dist/src/code-execution/tool-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,wBAAgB,gCAAgC,CAAC,IAAI,CAAC,EAAE;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,cAAc,CAwEjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAUhE;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQhH"}
+{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,wBAAgB,gCAAgC,CAAC,IAAI,CAAC,EAAE;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,cAAc,CAoFjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAWhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,IAAI,CA+CP"}

package/dist/src/code-execution/tool-definition.js

@@ -7,6 +7,7 @@
  * dict and returning a string, stdout as the return channel, persistent
  * interpreter state, asyncio.gather for fan-out.
  */
+import { assertBooleanSetting, holdsSettings, kindOf } from '../config-checks.js';
 import { formatLimit, MAX_TIMER_MS } from './py-runner.js';
 export const CODE_EXECUTION_TOOL_NAME = 'code_execution';
 export function buildCodeExecutionToolDefinition(opts) {
@@ -21,14 +22,26 @@ export function buildCodeExecutionToolDefinition(opts) {
             "non-identifier character replaced by '_' " +
             "(e.g. tool 'mcpl--discord--fetch_history' is the function mcpl__discord__fetch_history, " +
             "and tool 'mcpl--dog-events--status' is mcpl__dog_events__status). " +
-            'Each function takes a single dict of arguments and returns a string — the same text ' +
-            'the tool would have returned to you directly; parse structured results with json.loads. ' +
+            'Each function takes a single dict of arguments and returns a string: the text the tool ' +
+            'would have returned to you directly, or "Error: ..." if the call failed. For a result ' +
+            'with structured content, the string is a JSON object to parse with json.loads: ' +
+            '{"content": [...], "structuredContent": ..., "isError": false}, with "error" added when ' +
+            `"isError" is true. "content" holds the server's content blocks. A reference to a payload ` +
+            'appears there as {"type": ..., "refId": ..., "savedTo": ...}, where "savedTo" is the ' +
+            `workspace path the payload was saved to (null if it wasn't) and "refId" is fetch_reference's ` +
+            'ref_id. A structured result over 5 MB is saved to the workspace instead, and the string is ' +
+            '{"isError": ..., "oversized": {"chars": ..., "savedTo": ...}}. ' +
+            'Each string also carries .is_error (True if the result is an error, else False; test it ' +
+            'rather than an "Error:" prefix) and .structured (the parsed "structuredContent" of the ' +
+            'JSON object above, or None). ' +
             "An exact-name lookup dict is also available: tools['mcpl--discord--fetch_history']({...}). " +
             'Use top-level await; run independent calls in parallel with asyncio.gather. ' +
             'Only what you print() (plus stderr and the exit code) comes back to you — intermediate ' +
             'tool results stay in the script, so filter or aggregate large data there and print only ' +
             'what you need. Interpreter state (variables, imports) persists across code_execution ' +
-            `calls but is reclaimed after ~${idleMinutes} minutes idle. A tool call that receives no ` +
+            `calls but is reclaimed after ~${idleMinutes} minutes idle. Relative paths resolve in a ` +
+            'scratch directory of the interpreter\'s, which goes whenever it stops or is reclaimed, so a file meant to ' +
+            'outlast the interpreter needs an absolute path. A tool call that receives no ' +
             `response within ~${callTimeoutSeconds}s raises TimeoutError inside the script. ` +
             `A foreground script is stopped after ${formatLimit(limits.defaultMs)}; pass time_limit_ms to set this call's limit ` +
             `(at most ${formatLimit(limits.maxMs)}; a background script runs up to ${formatLimit(limits.backgroundMaxMs)}). ` +
@@ -89,18 +102,71 @@ 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. */
+/**
+ * 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 or whose interpreter environment would be misread. 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. Likewise the runner passes the
+ * host's environment only for an `inheritEnv` of `true`, so a quoted "true"
+ * would quietly keep the allowlist. A null or false codeExecution, and a null
+ * setting, 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) {
+    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(`codeExecution.maxScriptTimeoutMs (${cfg.maxScriptTimeoutMs}) must be at least scriptTimeoutMs (${defaultMs}): ` +
             'it is the most an agent may ask for, and the default is always allowed');
     }
+    // None of the environment's refusals below shows the value it refuses,
+    // at most its kind: a substituted value can be a credential. null counts
+    // as not set, so a generated config that writes an unset setting as null
+    // keeps working.
+    assertBooleanSetting('codeExecution.inheritEnv', cfg.inheritEnv, "true hands the interpreter the host's whole environment, and false or leaving it out keeps the allowlist");
+    if (cfg.env !== undefined && cfg.env !== null) {
+        if (!isPlainObject(cfg.env)) {
+            throw new Error(`codeExecution.env must be an object of variable names and string values, not ${kindOf(cfg.env)}`);
+        }
+        for (const [name, value] of Object.entries(cfg.env)) {
+            // spawn writes each variable as name=value: a name that is empty or
+            // holds '=' doesn't reach the interpreter as written, and a NUL in a
+            // name or a value makes spawn throw at every start.
+            // Only what comes before an '=' or NUL is shown: what follows can be a
+            // value pasted into the name.
+            if (name === '' || name.includes('=') || name.includes('\0')) {
+                const shown = name === '' ? 'that is empty' : `starting ${JSON.stringify(name.split(/[=\0]/, 1)[0])} that holds '=' or NUL`;
+                throw new Error(`codeExecution.env has a variable name ${shown}, and a name can't be empty or hold '=' or NUL`);
+            }
+            if (typeof value !== 'string') {
+                throw new Error(`codeExecution.env.${name} must be a string, not ${kindOf(value)}: give its value as a string, or leave ${name} out`);
+            }
+            if (value.includes('\0')) {
+                throw new Error(`codeExecution.env.${name} holds a NUL character, which no environment variable can carry`);
+            }
+        }
+    }
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
 }
 //# sourceMappingURL=tool-definition.js.map

package/dist/src/code-execution/tool-definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"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"}

package/dist/src/config-checks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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, as a refusal names it in place of the value, which
+ *  can be a credential. */
+export declare function kindOf(value: unknown): string;
+/**
+ * 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 declare function assertBooleanSetting(setting: string, value: unknown, whatItDoes: string): void;
+/**
+ * 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 declare function holdsSettings<T>(setting: string, value: T, example: string): value is NonNullable<T>;
+//# sourceMappingURL=config-checks.d.ts.map

package/dist/src/config-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-checks.d.ts","sourceRoot":"","sources":["../../src/config-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;2BAC2B;AAC3B,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAU7C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAI9F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAMpG"}

package/dist/src/config-checks.js

@@ -0,0 +1,56 @@
+/**
+ * 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, as a refusal names it in place of the value, which
+ *  can be a credential. */
+export function kindOf(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value !== 'object')
+        return `a ${typeof value}`;
+    const prototype = Object.getPrototypeOf(value);
+    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, value, whatItDoes) {
+    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(setting, value, example) {
+    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;
+}
+//# sourceMappingURL=config-checks.js.map

package/dist/src/config-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-checks.js","sourceRoot":"","sources":["../../src/config-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;2BAC2B;AAC3B,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,OAAO,KAAK,EAAE,CAAC;IAC1D,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAA+C,CAAC;IAC7F,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS;QAAE,OAAO,WAAW,CAAC;IAC7E,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,6BAA6B,CAAC;IAChD,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,KAAc,EAAE,UAAkB;IACtF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO;IAChF,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACzF,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,YAAY,MAAM,QAAQ,MAAM,CAAC,KAAK,CAAC,KAAK,UAAU,EAAE,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAI,OAAe,EAAE,KAAQ,EAAE,OAAe;IACzE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,+BAA+B,OAAO,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/deadline-timer.d.ts

@@ -0,0 +1,21 @@
+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 declare function armAt(deadlineMs: number, hold: Hold, fire: () => void): void;
+/**
+ * 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 declare function armAfter(delayMs: number, hold: Hold, fire: () => void): void;
+export {};
+//# sourceMappingURL=deadline-timer.d.ts.map

package/dist/src/deadline-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline-timer.d.ts","sourceRoot":"","sources":["../../src/deadline-timer.ts"],"names":[],"mappings":"AAIA,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,CAAC;AAE3D;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAW5E;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAQ5E"}

package/dist/src/deadline-timer.js

@@ -0,0 +1,43 @@
+/** 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;
+/**
+ * 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, hold, fire) {
+    const arm = () => {
+        // 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 = () => {
+        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, hold, fire) {
+    let left = delayMs;
+    const arm = () => {
+        const step = Math.min(left, MAX_TIMER_MS);
+        left -= step;
+        hold(setTimeout(left > 0 ? arm : fire, step));
+    };
+    arm();
+}
+//# sourceMappingURL=deadline-timer.js.map

package/dist/src/deadline-timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline-timer.js","sourceRoot":"","sources":["../../src/deadline-timer.ts"],"names":[],"mappings":"AAAA;6EAC6E;AAC7E,MAAM,YAAY,GAAG,aAAa,CAAC;AAInC;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CAAC,UAAkB,EAAE,IAAU,EAAE,IAAgB;IACpE,MAAM,GAAG,GAAG,GAAS,EAAE;QACrB,0EAA0E;QAC1E,2CAA2C;QAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,GAAG,EAAE,CAAC;;YAClC,IAAI,EAAE,CAAC;IACd,CAAC,CAAC;IACF,GAAG,EAAE,CAAC;AACR,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAAU,EAAE,IAAgB;IACpE,IAAI,IAAI,GAAG,OAAO,CAAC;IACnB,MAAM,GAAG,GAAG,GAAS,EAAE;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC1C,IAAI,IAAI,IAAI,CAAC;QACb,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC;IACF,GAAG,EAAE,CAAC;AACR,CAAC"}

package/dist/src/error-message.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a thrown value says: an Error's message, or any other value as a
+ * string, without the "Error: " that `String(error)` puts in front.
+ *
+ * It never throws. Every inspection and coercion of the value is inside the
+ * try, so a revoked Proxy (whose instanceof throws), a hostile getter, an
+ * Error whose message isn't a string, or a value with no string form reads
+ * as text or as unreadable. It doesn't bound the text: a message the module
+ * wrote for the agent often ends with its remedy, which a bound would cut. A
+ * caller that writes it to a log or a server's answer bounds it there, with
+ * boundedErrorMessage.
+ */
+export declare function errorMessage(error: unknown): string;
+/**
+ * The most of a thrown value's text that reaches a log line, a server's error
+ * answer or an agent's frame around an error nobody expected.
+ */
+export declare const THROWN_TEXT_LIMIT = 500;
+/**
+ * errorMessage, cut to `limit` characters with the whole length said, for a
+ * value whose text nobody wrote for its reader: a handler's throw sent on as
+ * an answer, or an error a module didn't expect quoted inside its own frame,
+ * since a provider or handler error can carry a whole request body.
+ *
+ * Characters are code points, so a cut never leaves half of a surrogate pair
+ * at the end. The text is walked rather than spread into an array, which for
+ * a whole request body would hold every code point at once.
+ */
+export declare function boundedErrorMessage(error: unknown, limit?: number): string;
+//# sourceMappingURL=error-message.d.ts.map

package/dist/src/error-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-message.d.ts","sourceRoot":"","sources":["../../src/error-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMnD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAoB,GAAG,MAAM,CAWrF"}

package/dist/src/error-message.js

@@ -0,0 +1,50 @@
+/**
+ * What a thrown value says: an Error's message, or any other value as a
+ * string, without the "Error: " that `String(error)` puts in front.
+ *
+ * It never throws. Every inspection and coercion of the value is inside the
+ * try, so a revoked Proxy (whose instanceof throws), a hostile getter, an
+ * Error whose message isn't a string, or a value with no string form reads
+ * as text or as unreadable. It doesn't bound the text: a message the module
+ * wrote for the agent often ends with its remedy, which a bound would cut. A
+ * caller that writes it to a log or a server's answer bounds it there, with
+ * boundedErrorMessage.
+ */
+export function errorMessage(error) {
+    try {
+        return String(error instanceof Error ? error.message : error);
+    }
+    catch {
+        return '(a value that could not be read)';
+    }
+}
+/**
+ * The most of a thrown value's text that reaches a log line, a server's error
+ * answer or an agent's frame around an error nobody expected.
+ */
+export const THROWN_TEXT_LIMIT = 500;
+/**
+ * errorMessage, cut to `limit` characters with the whole length said, for a
+ * value whose text nobody wrote for its reader: a handler's throw sent on as
+ * an answer, or an error a module didn't expect quoted inside its own frame,
+ * since a provider or handler error can carry a whole request body.
+ *
+ * Characters are code points, so a cut never leaves half of a surrogate pair
+ * at the end. The text is walked rather than spread into an array, which for
+ * a whole request body would hold every code point at once.
+ */
+export function boundedErrorMessage(error, limit = THROWN_TEXT_LIMIT) {
+    const text = errorMessage(error);
+    // A code point takes one or two UTF-16 units, so text this short is within the limit.
+    if (text.length <= limit)
+        return text;
+    let points = 0;
+    let cut = 0;
+    for (const point of text) {
+        if (points < limit)
+            cut += point.length;
+        points++;
+    }
+    return points <= limit ? text : `${text.slice(0, cut)}… (${points} characters)`;
+}
+//# sourceMappingURL=error-message.js.map

package/dist/src/error-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-message.js","sourceRoot":"","sources":["../../src/error-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,kCAAkC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,KAAK,GAAG,iBAAiB;IAC3E,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,sFAAsF;IACtF,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,MAAM,GAAG,KAAK;YAAE,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC;QACxC,MAAM,EAAE,CAAC;IACX,CAAC;IACD,OAAO,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,MAAM,cAAc,CAAC;AAClF,CAAC"}