@animalabs/agent-framework 0.22.2 → 0.23.0

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

@@ -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"}
@@ -49,10 +50,12 @@
 export const PYTHON_RUNTIME_SOURCE: string = String.raw`
 import ast
 import asyncio
+import functools
 import inspect
 import io
 import json
 import os
+import re
 import signal
 import sys
 import threading
@@ -70,9 +73,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()
@@ -250,6 +260,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():
@@ -259,15 +294,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)
@@ -293,7 +375,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
 
@@ -483,7 +566,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/src/code-execution/tool-definition.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ToolDefinition } from '../types/index.js';
+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';
@@ -32,14 +33,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)}). ` +
@@ -106,15 +119,43 @@ 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 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: {
+  enabled?: unknown;
+  scriptTimeoutMs?: number;
+  maxScriptTimeoutMs?: number;
+  env?: unknown;
+  inheritEnv?: unknown;
+}): 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(
@@ -122,4 +163,41 @@ export function validateCodeExecutionConfig(cfg: { scriptTimeoutMs?: number; max
         '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: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }

package/src/config-checks.ts

@@ -0,0 +1,50 @@
+/**
+ * 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: unknown): string {
+  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) 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();
+}

package/src/error-message.ts

@@ -0,0 +1,48 @@
+/**
+ * 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: unknown): string {
+  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: unknown, limit = THROWN_TEXT_LIMIT): string {
+  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)`;
+}