@animalabs/agent-framework 0.7.0 → 0.7.3

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

@@ -0,0 +1,265 @@
+/**
+ * Python runtime for client-side programmatic tool calling (PTC).
+ *
+ * This is the interpreter-side half of the `code_execution` tool: a small
+ * asyncio REPL that mimics the environment Anthropic's server-side PTC was
+ * trained on (see docs/en/agents-and-tools/tool-use/programmatic-tool-calling):
+ *
+ *   - 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)
+ *   - 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)
+ *
+ * Embedded as a TS string because tsc does not copy non-TS assets to dist/;
+ * PyRunner materializes it to a temp file at spawn.
+ *
+ * Protocol (JSON lines):
+ *   host -> py : {op:"init", tools:[{py_name,tool_name}], call_timeout_s}
+ *                {op:"exec", id, code}
+ *                {op:"tool_result", id, result}
+ *                {op:"cancel", id, reason?}
+ *   py -> host : {op:"ready"}
+ *                {op:"tool_call", id, exec_id, name, args}
+ *                {op:"exec_result", id, stdout, stderr, return_code}
+ *
+ * IMPORTANT: the python source below must not contain backticks or the
+ * sequence dollar+brace (TS template literal syntax). String.raw preserves
+ * backslashes, so \n inside python string literals is fine.
+ */
+
+export const PYTHON_RUNTIME_SOURCE: string = String.raw`
+import ast
+import asyncio
+import inspect
+import io
+import json
+import sys
+import threading
+import traceback
+
+PROTO_OUT = sys.stdout          # protocol channel (real stdout)
+REAL_STDERR = sys.stderr        # runtime diagnostics outside execs
+CALL_TIMEOUT_S = 270.0
+OUTPUT_CAP_CHARS = 2_000_000
+
+_send_lock = threading.Lock()
+
+
+def send(obj):
+    line = json.dumps(obj, ensure_ascii=False, default=str)
+    with _send_lock:
+        PROTO_OUT.write(line + "\n")
+        PROTO_OUT.flush()
+
+
+class CappedIO(io.StringIO):
+    """StringIO that stops recording past a cap (keeps a truncation flag)."""
+
+    def __init__(self, cap):
+        super().__init__()
+        self._cap = cap
+        self.truncated = False
+
+    def write(self, s):
+        if not isinstance(s, str):
+            s = str(s)
+        if self.tell() >= self._cap:
+            self.truncated = True
+            return len(s)
+        remaining = self._cap - self.tell()
+        if len(s) > remaining:
+            self.truncated = True
+            return super().write(s[:remaining])
+        return super().write(s)
+
+
+# Persistent interpreter state (mirrors container reuse: variables survive
+# between exec calls until the host reclaims the interpreter).
+SCRIPT_GLOBALS = {"__name__": "__main__", "__builtins__": __builtins__}
+_injected_py_names = set()
+
+_pending_tool_futures = {}
+_next_tool_call_id = 0
+_current_exec_id = None
+_current_exec_task = None
+
+
+def _make_tool_fn(tool_name, py_name):
+    async def tool_fn(args=None):
+        global _next_tool_call_id
+        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 + "({...})"
+            )
+        _next_tool_call_id += 1
+        call_id = "t" + str(_next_tool_call_id)
+        fut = asyncio.get_running_loop().create_future()
+        _pending_tool_futures[call_id] = fut
+        send({
+            "op": "tool_call",
+            "id": call_id,
+            "exec_id": _current_exec_id,
+            "name": tool_name,
+            "args": args,
+        })
+        try:
+            return await asyncio.wait_for(fut, timeout=CALL_TIMEOUT_S)
+        except asyncio.TimeoutError:
+            raise TimeoutError(
+                "Calling tool ['" + tool_name + "'] timed out (no response after "
+                + str(int(CALL_TIMEOUT_S)) + "s)."
+            )
+        finally:
+            _pending_tool_futures.pop(call_id, None)
+
+    tool_fn.__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."
+    )
+    return tool_fn
+
+
+def handle_init(msg):
+    global CALL_TIMEOUT_S
+    timeout = msg.get("call_timeout_s")
+    if isinstance(timeout, (int, float)) and timeout > 0:
+        CALL_TIMEOUT_S = float(timeout)
+
+    # Remove functions injected by a previous init that are no longer present
+    # (tool list changed) without touching user-defined globals.
+    new_tools = msg.get("tools") or []
+    new_py_names = set()
+    tools_dict = {}
+    for entry in new_tools:
+        py_name = entry.get("py_name")
+        tool_name = entry.get("tool_name")
+        if not py_name or not tool_name:
+            continue
+        fn = _make_tool_fn(tool_name, py_name)
+        SCRIPT_GLOBALS[py_name] = fn
+        tools_dict[tool_name] = fn
+        new_py_names.add(py_name)
+    for stale in _injected_py_names - new_py_names:
+        SCRIPT_GLOBALS.pop(stale, None)
+    _injected_py_names.clear()
+    _injected_py_names.update(new_py_names)
+    # Exact-name escape hatch: tools["mcpl--server--tool"]({...})
+    SCRIPT_GLOBALS["tools"] = tools_dict
+
+
+async def _run_script(exec_id, code):
+    global _current_exec_id, _current_exec_task
+    out = CappedIO(OUTPUT_CAP_CHARS)
+    err = CappedIO(OUTPUT_CAP_CHARS)
+    old_out, old_err, old_in = sys.stdout, sys.stderr, sys.stdin
+    sys.stdout, sys.stderr = out, err
+    sys.stdin = io.StringIO("")  # input() must not steal the protocol channel
+    return_code = 0
+    try:
+        compiled = compile(code, "<script>", "exec", flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT)
+        result = eval(compiled, SCRIPT_GLOBALS)
+        if inspect.iscoroutine(result):
+            await result
+    except asyncio.CancelledError:
+        err.write("\nKeyboardInterrupt: script cancelled by host\n")
+        return_code = 1
+    except BaseException:
+        traceback.print_exc(file=err)
+        return_code = 1
+    finally:
+        sys.stdout, sys.stderr, sys.stdin = old_out, old_err, old_in
+        _current_exec_id = None
+        _current_exec_task = None
+        # Fail any tool futures still pending: their exec is gone.
+        for fut in list(_pending_tool_futures.values()):
+            if not fut.done():
+                fut.cancel()
+        _pending_tool_futures.clear()
+
+    stdout_text = out.getvalue()
+    if out.truncated:
+        stdout_text += "\n[stdout truncated at " + str(OUTPUT_CAP_CHARS) + " chars]"
+    stderr_text = err.getvalue()
+    if err.truncated:
+        stderr_text += "\n[stderr truncated at " + str(OUTPUT_CAP_CHARS) + " chars]"
+    send({
+        "op": "exec_result",
+        "id": exec_id,
+        "stdout": stdout_text,
+        "stderr": stderr_text,
+        "return_code": return_code,
+    })
+
+
+async def main():
+    global _current_exec_id, _current_exec_task
+    loop = asyncio.get_running_loop()
+    queue = asyncio.Queue()
+
+    def reader():
+        for raw_line in sys.stdin:
+            loop.call_soon_threadsafe(queue.put_nowait, raw_line)
+        loop.call_soon_threadsafe(queue.put_nowait, None)
+
+    threading.Thread(target=reader, daemon=True).start()
+    send({"op": "ready"})
+
+    while True:
+        line = await queue.get()
+        if line is None:
+            break
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except Exception:
+            REAL_STDERR.write("[pytc-runtime] bad protocol line\n")
+            REAL_STDERR.flush()
+            continue
+        op = msg.get("op")
+        if op == "init":
+            handle_init(msg)
+        elif op == "exec":
+            if _current_exec_task is not None and not _current_exec_task.done():
+                send({
+                    "op": "exec_result",
+                    "id": msg.get("id"),
+                    "stdout": "",
+                    "stderr": "RuntimeError: another script is already running in this interpreter",
+                    "return_code": 1,
+                })
+                continue
+            _current_exec_id = msg.get("id")
+            _current_exec_task = asyncio.ensure_future(
+                _run_script(msg.get("id"), msg.get("code") or "")
+            )
+        elif op == "tool_result":
+            fut = _pending_tool_futures.get(msg.get("id"))
+            if fut is not None and not fut.done():
+                fut.set_result(str(msg.get("result", "")))
+        elif op == "cancel":
+            if _current_exec_task is not None and not _current_exec_task.done():
+                _current_exec_task.cancel()
+        elif op == "exit":
+            break
+
+    # Drain: give a cancelled exec a moment to emit its exec_result.
+    if _current_exec_task is not None and not _current_exec_task.done():
+        _current_exec_task.cancel()
+        try:
+            await asyncio.wait_for(_current_exec_task, timeout=2)
+        except BaseException:
+            pass
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+`;

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

@@ -0,0 +1,54 @@
+/**
+ * Synthesized `code_execution` tool definition.
+ *
+ * The name, input shape ({code}), and description framing deliberately track
+ * Anthropic's server-side programmatic tool calling so models' trained
+ * priors transfer: python scripts, tools as async functions taking a single
+ * dict and returning a string, stdout as the return channel, persistent
+ * interpreter state, asyncio.gather for fan-out.
+ */
+
+import type { ToolDefinition } from '../types/index.js';
+
+export const CODE_EXECUTION_TOOL_NAME = 'code_execution';
+
+export function buildCodeExecutionToolDefinition(opts?: {
+  idleReclaimMs?: number;
+  toolCallTimeoutMs?: number;
+}): ToolDefinition {
+  const idleMinutes = Math.max(1, Math.round((opts?.idleReclaimMs ?? 300_000) / 60_000));
+  const callTimeoutSeconds = Math.round((opts?.toolCallTimeoutMs ?? 270_000) / 1000);
+  return {
+    name: CODE_EXECUTION_TOOL_NAME,
+    description:
+      'Run Python code that can call your other tools programmatically. ' +
+      'Every tool you have is available inside the script as an async Python function: ' +
+      "the function name is the tool name with '--' replaced by '__' and any other " +
+      "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. ' +
+      "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 ` +
+      `response within ~${callTimeoutSeconds}s raises TimeoutError inside the script. ` +
+      'Use this when fanning out across many items, looping over tool calls, or when tool ' +
+      'results are large and you only need a slice or summary. Call tools directly (not via ' +
+      'code) when a single call answers the question or when you need to reason about each ' +
+      'result before deciding the next step.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        code: {
+          type: 'string',
+          description: 'Python code to execute. Top-level await is allowed.',
+        },
+      },
+      required: ['code'],
+    },
+  };
+}