@animalabs/agent-framework 0.22.3 → 0.23.0

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

@@ -15,9 +15,10 @@
  */
 
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { buildChildEnv } from '../mcpl/transport.js';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { createInterface, type Interface } from 'node:readline';
 import { boundedErrorMessage } from '../error-message.js';
 import { PYTHON_RUNTIME_SOURCE } from './runtime-py.js';
@@ -54,11 +55,30 @@ export interface BackgroundExecOptions {
   lifetimeMs: number;
 }
 
-/** Resolves inner tool calls. Must never reject — map errors to strings. */
+/**
+ * An inner tool call's result as the script gets it. `text` is the string
+ * its await returns, and the runner sets `.is_error` on that string from
+ * `isError`. With `structuredJson`, `text` is the JSON object a structured
+ * result reaches a script as, in any of its forms, and `.structured` reads
+ * its `structuredContent`, None for a form that holds none, such as one past
+ * the size cap; without it, `.structured` is None.
+ */
+export interface ScriptToolResult {
+  text: string;
+  isError: boolean;
+  structuredJson?: boolean;
+}
+
+/**
+ * Resolves inner tool calls. Must never reject — map errors to results; a
+ * rejection reaches the script as an `Error: …` result. A plain string is
+ * the result's text with nothing said about it, so the script's
+ * `.is_error` and `.structured` are None.
+ */
 export type ScriptToolCallHandler = (
   toolName: string,
   args: Record<string, unknown>,
-) => Promise<string>;
+) => Promise<string | ScriptToolResult>;
 
 export interface PyRunnerOptions {
   pythonPath?: string;
@@ -73,6 +93,19 @@ export interface PyRunnerOptions {
   onToolCall: ScriptToolCallHandler;
   /** Log prefix, typically the agent name. */
   label?: string;
+  /** Variables for the interpreter beyond what it inherits, such as
+   *  PYTHONPATH or a venv's. It inherits only what stdio MCPL children do
+   *  (CHILD_ENV_ALLOWLIST and LC_*, CA bundles and proxy variables among
+   *  them, and a proxy URL can carry credentials), then these, then
+   *  PYTHONUNBUFFERED and PYTHONIOENCODING, which the runner sets last.
+   *  Like the allowlist, this limits what the model's code inherits, not
+   *  what a process running as the same user can read. */
+  env?: Record<string, string>;
+  /** Pass the host's whole environment instead of the allowlist, as before
+   *  `env` existed. That hands every host variable, provider keys included,
+   *  to the model's code and to every subprocess a script starts; listing
+   *  what scripts need in `env` is the safer route. */
+  inheritEnv?: boolean;
 }
 
 const DEFAULT_TOOL_CALL_TIMEOUT_MS = 270_000;
@@ -164,6 +197,17 @@ interface PendingExec {
   sent: boolean;
 }
 
+/**
+ * The interpreter to spawn. A bare name is looked up on PATH. A path with a
+ * separator is resolved against the host's working directory, where it
+ * resolved before the interpreter got a working directory of its own: spawn
+ * would resolve it against the runtime directory instead.
+ */
+function spawnablePath(pythonPath: string): string {
+  const hasSeparator = pythonPath.includes('/') || (process.platform === 'win32' && pythonPath.includes('\\'));
+  return hasSeparator ? resolve(pythonPath) : pythonPath;
+}
+
 export class PyRunner {
   private readonly pythonPath: string;
   private readonly toolCallTimeoutMs: number;
@@ -172,6 +216,7 @@ export class PyRunner {
   private readonly idleReclaimMs: number;
   private readonly onToolCall: ScriptToolCallHandler;
   private readonly label: string;
+  private readonly envOptions: { env?: Record<string, string>; inheritEnv?: boolean };
 
   private onWake: ((line: number, payload: unknown) => Promise<string | null>) | null = null;
   private child: ChildProcessWithoutNullStreams | null = null;
@@ -191,6 +236,12 @@ export class PyRunner {
     this.idleReclaimMs = options.idleReclaimMs ?? DEFAULT_IDLE_RECLAIM_MS;
     this.onToolCall = options.onToolCall;
     this.label = options.label ?? 'pytc';
+    // The interpreter runs model-authored code: the same env discipline as an
+    // MCPL connector child (#175), for a child that deserves it more. Stored
+    // as options, not a snapshot — the env is rebuilt at every spawn so a
+    // respawn after idle reclaim sees current host values, as the old
+    // per-spawn `{ ...process.env }` did.
+    this.envOptions = { env: options.env, inheritEnv: options.inheritEnv };
   }
 
   get busy(): boolean {
@@ -368,13 +419,23 @@ export class PyRunner {
     }
     this.teardownChild();
 
-    this.runtimeDir = mkdtempSync(join(tmpdir(), 'af-pytc-'));
+    // Absolute, since the interpreter runs in it: from a relative TMPDIR,
+    // runtime.py's path would otherwise resolve against the directory itself.
+    this.runtimeDir = resolve(mkdtempSync(join(tmpdir(), 'af-pytc-')));
     const runtimePath = join(this.runtimeDir, 'runtime.py');
     writeFileSync(runtimePath, PYTHON_RUNTIME_SOURCE, 'utf8');
 
-    const child = spawn(this.pythonPath, [runtimePath], {
+    const child = spawn(spawnablePath(this.pythonPath), [runtimePath], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, PYTHONUNBUFFERED: '1' },
+      // The runtime directory, not the host's working directory: a script's
+      // relative paths land here, and go at teardown, rather than beside the
+      // host's .env and data. An absolute path still reaches the host's files.
+      cwd: this.runtimeDir,
+      // Set last, over a declared env: the protocol needs both. It writes
+      // non-ASCII JSON on piped stdio, which Python before 3.15 on Windows
+      // encodes in the ANSI code page unless told otherwise, and a host's
+      // own PYTHONUTF8 no longer reaches the interpreter.
+      env: { ...buildChildEnv(this.envOptions), PYTHONUNBUFFERED: '1', PYTHONIOENCODING: 'utf-8' },
     });
     this.child = child;
 
@@ -488,9 +549,24 @@ export class PyRunner {
             ? (msg.args as Record<string, unknown>)
             : {};
         this.onToolCall(toolName, args)
-          .catch((err) => `Error: ${err instanceof Error ? err.message : String(err)}`)
+          .catch((err): ScriptToolResult => ({
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+            isError: true,
+          }))
           .then((result) => {
-            this.reply(child, { op: 'tool_result', id: callId, result }, `result of ${toolName} call ${callId}`);
+            // Only an object is a ScriptToolResult. Anything else a handler
+            // resolves with, a string or a value its type rules out, is sent
+            // as it is, so the call is still answered.
+            const reply = typeof result === 'object' && result !== null
+              ? {
+                op: 'tool_result',
+                id: callId,
+                result: result.text,
+                is_error: result.isError,
+                ...(result.structuredJson ? { structured_json: true } : {}),
+              }
+              : { op: 'tool_result', id: callId, result };
+            this.reply(child, reply, `result of ${toolName} call ${callId}`);
           });
         return;
       }
@@ -619,8 +695,8 @@ export class PyRunner {
       this.reader.close();
       this.reader = null;
     }
-    if (this.child) {
-      const child = this.child;
+    const child = this.child;
+    if (child) {
       this.child = null;
       this.childReady = null;
       this.readyResolver = null;
@@ -640,13 +716,24 @@ export class PyRunner {
         child.kill('SIGKILL');
       }
     }
-    if (this.runtimeDir) {
-      try {
-        rmSync(this.runtimeDir, { recursive: true, force: true });
-      } catch {
-        // temp cleanup is best-effort
-      }
-      this.runtimeDir = null;
+    const dir = this.runtimeDir;
+    this.runtimeDir = null;
+    if (dir) {
+      const remove = (): void => {
+        try {
+          rmSync(dir, { recursive: true, force: true });
+        } catch {
+          // temp cleanup is best-effort
+        }
+      };
+      // The directory is the interpreter's working directory, which Windows
+      // won't remove while the process lives, so there it goes once the
+      // process has. Elsewhere it goes now, so a host that exits right after
+      // this doesn't leave it behind. A child that never started has no exit
+      // to wait for.
+      const running = child !== null && child.pid !== undefined && child.exitCode === null && child.signalCode === null;
+      if (running && process.platform === 'win32') child.once('exit', remove);
+      else remove();
     }
   }
 

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():
@@ -299,8 +334,9 @@ def _make_tool_fn(tool_name, py_name):
             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)
+            # 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 "
@@ -339,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
 
@@ -529,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,7 +9,7 @@
  */
 
 import type { ToolDefinition } from '../types/index.js';
-import { assertBooleanSetting, holdsSettings } from '../config-checks.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';
@@ -33,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)}). ` +
@@ -118,18 +130,23 @@ export function scriptTimeLimits(opts?: {
 /**
  * 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.
+ * 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(
@@ -146,4 +163,41 @@ export function validateCodeExecutionConfig(cfg: {
         '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

@@ -8,9 +8,11 @@
  * 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. */
+/** 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;