AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Let a workflow action step act through one short script instead of many turns.
An action step's agent normally calls its tools one model turn at a time, so
"go through this Drive folder and file each document" costs a turn — tokens
and seconds — per file. ``run_script`` lets the agent write that loop once, in
Python, and get back only what the script returns.
The script runs in Monty (``pydantic-monty``), a sandboxed Python interpreter
for code a model wrote, in a worker process spawned per script (so no state
survives from one script to the next):
* **Nothing but the step's own tools.** A call to any function the script did
not define pauses the worker and comes back here, where it is answered
through the action step's own per-call path (``action_step._StepCalls.call``):
the allowlist (a name outside it is refused and audited, like a direct
``tool_use``), the call budget, the first-write target check (a held write
comes back to the script as the usual ``{"status": "held", …}`` result) and
the audit row. A script is a faster way to make the same calls, never a way
around them. There are no files, network, environment variables,
subprocesses or third-party imports; OS calls get Monty's refusal.
* **Driven from the event loop.** The worker is stepped with ``feed_start`` /
``resume``, so each call is awaited in the step's own task: cancelling the
run, or the wall clock below, stops the script and its in-flight call
together, and the engine sees each call's events as it happens.
* **Bounded.** Execution time (not counting time waiting on tools), memory and
recursion are capped inside the worker, the whole script has a wall-clock
limit, and the script's text and printed output are size-capped (printing
past the cap is dropped, not fatal).
* **Not stored.** The script lives only in this step's model turns, like any
other tool call's arguments; a workflow definition still holds no code.
Monty supports a subset of Python (no classes with inheritance, no
third-party packages), which is enough for loops, conditions, string and
data handling over tool results.
"""
from __future__ import annotations
import asyncio
import json
import logging
import re
from collections.abc import AsyncGenerator, Callable, Coroutine
from typing import Any
logger = logging.getLogger(__name__)
RUN_SCRIPT_TOOL = "run_script"
MAX_SCRIPT_CHARS = 20_000
_MAX_PRINTED_CHARS = 8_000
# Calls listed back to the model when a script fails partway (so it does not
# repeat writes that already ran).
_MAX_LISTED_CALLS = 200
# Worker-enforced limits. Execution time excludes time spent waiting on the
# host (tool calls). The number of tool calls is bounded by the step's own
# budget (``_StepCalls``); `max_suspensions` is only a backstop well above any
# step's budget, since name lookups and OS calls count towards it too.
_LIMITS = {
"max_feed_duration_secs": 20.0,
"max_memory": 128 * 1024 * 1024,
"max_recursion_depth": 200,
"max_suspensions": 5_000,
}
_WALL_CLOCK_S = 600.0
_POOL_REQUEST_TIMEOUT_S = 180.0
# Statuses a call answers with when it is held for a person's approval
# (action_step.HELD_TOOL_RESULT, take_the_lead's gate).
_WAITING = frozenset({"held", "waiting_for_approval"})
# One per event loop (tests run several): SCRIPT_MAX_WORKERS scripts at once.
_worker_slots: dict[int, tuple[int, asyncio.Semaphore]] = {}
def _slots() -> asyncio.Semaphore:
from openexecutive.config import get_settings
limit = get_settings().script_max_workers
key = id(asyncio.get_running_loop())
held = _worker_slots.get(key)
if held is None or held[0] != limit:
held = (limit, asyncio.Semaphore(limit))
_worker_slots[key] = held
return held[1]
CallFn = Callable[[str, dict[str, Any]], Coroutine[Any, Any, tuple[str, bool]]]
# What ``run_script`` yields: ("call", None) after each tool call (so the
# caller can hand that call's events to the engine), then exactly one
# ("done", (result text, is_error)).
ScriptYield = tuple[str, Any]
_IDENT_RE = re.compile(r"[^A-Za-z0-9_]")
def function_names(tools: list[str]) -> dict[str, str]:
"""Python function name → tool name, for the tools that map cleanly.
MCP names (``server__tool``) and built-ins (``oe__…``) are identifiers
already; one with a hyphen gets underscores. Two tools that would share a
function name get none — the script reaches them with ``call_tool``.
"""
mapped: dict[str, list[str]] = {}
for tool in tools:
fn = _IDENT_RE.sub("_", tool)
if fn[:1].isdigit():
fn = f"t_{fn}"
mapped.setdefault(fn, []).append(tool)
return {fn: names[0] for fn, names in mapped.items() if len(names) == 1 and fn != "call_tool"}
_INPUT_SCHEMA: dict[str, Any] = {
"type": "object",
"properties": {
"script": {
"type": "string",
"description": "Python source. End with an expression whose value you want back.",
},
"save_as": {
"type": "string",
"description": "Optional, with script: keep it as a saved tool under this snake_case name if the run succeeds.",
},
"description": {
"type": "string",
"description": "With save_as: one sentence on what the tool does and which inputs it takes.",
},
"tool": {
"type": "string",
"description": "Instead of script: the name of a saved tool to run.",
},
"inputs": {
"type": "object",
"description": "Values for this run, read by the script as the dict `inputs`.",
},
},
}
# A workflow step runs saved tools but never saves one (see run_script_tool).
_STEP_INPUT_SCHEMA: dict[str, Any] = {
"type": "object",
"properties": {
k: v for k, v in _INPUT_SCHEMA["properties"].items() if k not in ("save_as", "description")
},
}
_CALL_TEXT = (
"A call returns the tool's result, parsed from JSON when it is JSON (else "
"the text); a failed or refused call raises RuntimeError with the reason. "
'A call that comes back {"status": "held", ...} or {"status": '
'"waiting_for_approval", ...} is waiting for a person: do not retry it, '
"stop the loop if the rest depends on it, and say what is waiting."
)
_SAVED_TEXT = (
"To keep a script that worked for next time, also pass save_as (a "
"snake_case name) and description (one sentence on what it does and which "
"inputs it takes); it is saved only if this run succeeds, and only on the "
"principal's own turns. Write a script "
"you mean to reuse so it reads its per-run values (a folder, a date) from "
"the dict `inputs` rather than hard-coding them. Saving again under the same "
"name keeps a new version. Workflows run a kept tool only once the owner "
"turns that version on for them. To run a saved tool, pass tool (its name) "
"and inputs instead of script."
)
_SANDBOX_TEXT = (
"The script runs in a sandbox with a subset of Python: no imports beyond "
"json, re, math, datetime, collections, itertools and similar standard "
"modules; no files, network or classes with inheritance. The value of the "
"last expression is returned to you, along with anything printed and the "
"calls the script made. If it fails partway, the calls that already ran are "
"listed: do not repeat them. A call marked may_have_run was cut off by the "
"time limit and may have taken effect: check before repeating it."
)
def tool_definition(
tools: list[str], saved: list[Any] | None = None, *, call_budget: int | None = None
) -> dict[str, Any]:
"""The ``run_script`` tool for a workflow step with these tools.
``saved`` is the saved tools this step may run (every tool each uses is
one of the step's), listed by name and description. ``call_budget`` is
how many calls this step's scripts may make in all.
"""
budget_text = (
f"This step's scripts may make up to {call_budget} tool calls in all, a "
"budget of their own (larger than the direct-call budget, because a "
"script's calls cost no model turn); "
if call_budget is not None
else "Every call counts against this step's tool budget and "
)
funcs = function_names(tools)
listing = "\n".join(f"- {fn}(...) # calls {name}" for fn, name in sorted(funcs.items()))
saved_listing = ""
if saved:
saved_listing = (
"\n\nSaved tools this step can run: pass tool=<name> and inputs={...} "
"instead of script.\n"
) + "\n".join(
f"- {t.name}: {t.description}" for t in saved
)
return {
"name": RUN_SCRIPT_TOOL,
"description": (
"Run a short Python script that calls this step's tools, when the work "
"repeats over many items (every file in a folder, every row, every "
"email) or chains calls with simple logic. One script replaces many "
"separate tool calls; use the tools directly for a call or two.\n\n"
"Each tool is a function taking the tool's arguments as keywords:\n"
f"{listing}\n"
"call_tool(name, arguments) also reaches any of them by exact name. "
f"{_CALL_TEXT} {budget_text}each call "
"follows the same rules as calling the tool directly.\n\n"
f"{_SANDBOX_TEXT}{saved_listing}"
),
"input_schema": _STEP_INPUT_SCHEMA,
}
# The Executive's own tools a chat script may call as functions, besides the
# gateway's: reads, and actions that are useful item by item and keep their
# own checks (recipients, roster, approvals). Each call goes through the same
# handler (and Take the lead's gate) as a direct call, only when this turn is
# offered that tool. Not here: broadcasts, calendar changes, memory, skill,
# workflow and research tools, documents, and anything Act as me.
CHAT_OWN_TOOLS: tuple[str, ...] = (
"ack_alert",
"add_watchlist_entry",
"assign_open_loop",
"close_open_loop",
"create_alert",
"create_goal",
"find_alerts",
"list_department_goals",
"list_open_loops",
"list_people",
"list_watchlist",
"list_workflows",
"lookup_person",
"message_person",
"remove_watchlist_entry",
"schedule_followup",
"tune_watchlist_entry",
"update_department_goal",
"upsert_person",
)
# Per-turn caps on own tools a chat script could otherwise call in bulk:
# messaging everyone on the roster is a broadcast, which scripts don't get.
CHAT_OWN_TOOL_CAPS: dict[str, int] = {
"create_alert": 50,
"message_person": 10,
"upsert_person": 25,
}
# Added to a chat round's results (the user turn, never a cached block) when
# a tool came back with a list and run_script is on offer: the moment the
# model decides between one call per item and one built tool.
FANOUT_THRESHOLD = 5
FANOUT_HINT = (
"A tool above returned a list of items. If your next step checks, looks "
"up or acts on each of them, do the rest of the job (the per-item calls "
"and anything after them) in one run_script call instead of a round of "
"separate calls: every extra round re-reads this whole conversation, so "
"one script is much cheaper and faster."
)
def lists_many(text: str, threshold: int = FANOUT_THRESHOLD) -> bool:
"""Whether a tool result holds a list of at least ``threshold`` items:
the result itself, or a list one or two levels into a JSON object."""
try:
parsed = json.loads(text)
except (TypeError, ValueError):
return False
def many(value: Any, depth: int) -> bool:
if isinstance(value, list):
return len(value) >= threshold
if isinstance(value, dict) and depth < 2 and "error" not in value:
return any(many(v, depth + 1) for v in value.values())
return False
return many(parsed, 0)
# The chat version is a constant: chat's tool list is cached, so it can't
# name the tools a conversation happens to use.
CHAT_TOOL_DEFINITION: dict[str, Any] = {
"name": RUN_SCRIPT_TOOL,
"description": (
"Run a short Python script that calls tools. Use it instead of per-item "
"calls when a job looks something up and then checks or acts on each "
"result (list a folder, move each file), when results come in pages, or "
"for more than about ten items: each round of separate calls re-reads the "
"whole conversation. A handful of items named in the request go as direct "
"calls.\n\n"
"Call a tool as a function named exactly like it, arguments as keywords "
"(google_workspace__list_drive_items(folder_id=...)), or "
"call_tool(name, arguments) (needed for a name with a hyphen). Only tools "
"search_tools has returned can be called, each checked and recorded as a "
"call_tool would be. These of your own tools are functions too, with the "
f"same checks: {', '.join(CHAT_OWN_TOOLS)}. {_CALL_TEXT}\n\n"
f"{_SANDBOX_TEXT}\n\n{_SAVED_TEXT} list_saved_tools shows the saved tools."
),
"input_schema": _INPUT_SCHEMA,
}
def _parse_result(content: str) -> Any:
try:
return json.loads(content)
except (ValueError, TypeError):
return content
class _Printed:
"""Collects the script's printed output up to a cap, then drops the rest."""
def __init__(self) -> None:
self.parts: list[str] = []
self.size = 0
self.dropped = False
def __call__(self, stream: str, text: str) -> None:
room = _MAX_PRINTED_CHARS - self.size
if room <= 0:
self.dropped = True
return
piece = text[:room]
self.parts.append(piece)
self.size += len(piece)
if len(piece) < len(text):
self.dropped = True
def text(self) -> str:
out = "".join(self.parts)
return out + "\n…[more output not shown]" if self.dropped else out
def _call_arguments(name: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]:
"""(tool name, arguments) for a call the script made to ``name``.
``call_tool(name, arguments=None, **more)`` names the tool itself; any other
function takes the tool's arguments as keywords, or one positional dict.
Raises TypeError for a call shape the tool can't take.
"""
if name == "call_tool":
if not args or not isinstance(args[0], str):
raise TypeError("call_tool(name, arguments): name must be a string")
extra = args[1] if len(args) > 1 else kwargs.pop("arguments", None)
if len(args) > 2 or (extra is not None and not isinstance(extra, dict)):
raise TypeError("call_tool(name, arguments): arguments must be a dict")
return args[0], {**(extra or {}), **kwargs}
if args:
if len(args) == 1 and isinstance(args[0], dict) and not kwargs:
return name, dict(args[0])
raise TypeError(f"{name}: pass the tool's arguments by name")
return name, dict(kwargs)
# A gateway tool name (server__tool) used as a function in a chat script:
# non-empty on both sides of `__`, so dunders and stray underscores never
# become gateway calls.
_TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_]*__[A-Za-z0-9][A-Za-z0-9_]*$")
async def run_script(
script: str,
tools: list[str] | None,
call: CallFn,
*,
wall_clock_s: float = _WALL_CLOCK_S,
inputs: dict[str, Any] | None = None,
own: frozenset[str] = frozenset(),
) -> AsyncGenerator[ScriptYield, None]:
"""Run a script, yielding after each tool call and then its result.
``tools`` is a workflow step's allowlist: its tools are the script's
functions. ``None`` (chat) makes any tool-shaped function name a call by
that exact name, and each name in ``own`` (the Executive's own tools this
turn may use) too; ``call`` decides what may run. Never raises
(cancellation aside, which stops the worker with it).
"""
from pydantic_monty import (
AsyncFunctionSnapshot,
AsyncMonty,
AsyncNameLookupSnapshot,
MontyComplete,
MontyError,
)
if not script.strip():
yield ("done", (json.dumps({"error": "the script is empty"}), True))
return
if len(script) > MAX_SCRIPT_CHARS:
yield ("done", (
json.dumps({"error": f"the script is longer than {MAX_SCRIPT_CHARS} characters"}), True
))
return
names = function_names(tools) if tools is not None else {n: n for n in own}
loop = asyncio.get_running_loop()
deadline = loop.time() + wall_clock_s
async def bounded(awaitable: Any) -> Any:
# Not asyncio.timeout: a consumer may drive this generator one step
# per task (the chat route does), and a timeout scope only cancels the
# task that entered it. Each await gets what is left instead.
left = deadline - loop.time()
if left <= 0:
if asyncio.iscoroutine(awaitable):
awaitable.close()
raise TimeoutError
return await asyncio.wait_for(awaitable, timeout=left)
printed = _Printed()
made: list[dict[str, Any]] = []
slots = _slots()
def payload(**fields: Any) -> str:
# The record of calls first: a long result is cut from the end
# (TOOL_RESULT_MAX_CHARS), and the list of writes that already ran
# must survive the cut.
head: dict[str, Any] = {}
if "error" in fields:
head["error"] = fields.pop("error")
if made:
head["calls"] = made[:_MAX_LISTED_CALLS]
if len(made) > _MAX_LISTED_CALLS:
head["calls_not_listed"] = len(made) - _MAX_LISTED_CALLS
if printed.size or printed.dropped:
head["printed"] = printed.text()
return json.dumps({**head, **fields}, default=str, ensure_ascii=False)
try:
# A free worker slot first (SCRIPT_MAX_WORKERS), within the clock.
await bounded(slots.acquire())
except TimeoutError:
yield ("done", (payload(error="the server was busy running other scripts; try again shortly"), True))
return
try:
async with (
AsyncMonty(
min_processes=1, max_processes=1, request_timeout=_POOL_REQUEST_TIMEOUT_S
) as pool,
pool.checkout(
script_name="step_script.py",
limits=_LIMITS, # type: ignore[arg-type]
os_policy={"sleep": "zero"},
) as session,
):
snapshot: Any = await bounded(
session.feed_start(script, inputs={"inputs": dict(inputs or {})}, print_callback=printed)
)
while not isinstance(snapshot, MontyComplete):
if isinstance(snapshot, AsyncFunctionSnapshot):
if snapshot.is_os_function:
# open(), os.environ … — Monty's own refusal.
snapshot = await bounded(snapshot.resume_not_handled())
continue
fn = str(snapshot.function_name)
if (
tools is None
and fn != "call_tool"
and len(fn) <= 64
and _TOOL_NAME_RE.match(fn)
):
names[fn] = fn # chat: an MCP-shaped name is the tool's own name
if fn != "call_tool" and fn not in names:
snapshot = await bounded(snapshot.resume(
{"exception": NameError(f"name {fn!r} is not defined")}
))
continue
try:
tool, arguments = _call_arguments(
names.get(fn, fn), tuple(snapshot.args), dict(snapshot.kwargs)
)
except TypeError as exc:
snapshot = await bounded(snapshot.resume({"exception": exc}))
continue
try:
content, is_error = await bounded(call(tool, arguments))
except TimeoutError:
# Cut off mid-call by the clock: it may have taken
# effect, so it is listed for the model to check.
made.append({"tool": tool, "ok": False, "may_have_run": True})
raise
entry: dict[str, Any] = {"tool": tool, "ok": not is_error}
parsed = _parse_result(content)
if isinstance(parsed, dict) and parsed.get("status") in _WAITING:
entry["waiting_for_approval"] = True
made.append(entry)
yield ("call", None)
if is_error:
snapshot = await bounded(snapshot.resume(
{"exception": RuntimeError(f"{tool} failed: {content}")}
))
else:
snapshot = await bounded(snapshot.resume({"return_value": parsed}))
elif isinstance(snapshot, AsyncNameLookupSnapshot):
# An undefined name used as a value: leave it undefined.
snapshot = await bounded(snapshot.resume())
else:
# A future: the script awaited something it started
# without awaiting. Tools are plain calls here.
raise MontyScriptShape()
result = snapshot.output
except TimeoutError:
yield ("done", (payload(error="the script ran past its time limit"), True))
return
except MontyScriptShape:
yield ("done", (payload(error="call tools as plain functions, without async or await"), True))
return
except MontyError as exc:
# The script's own traceback, so the model can fix it. It names only
# the script's code and values it handled — data the model already saw.
try:
display = getattr(exc, "display", None)
detail = str(display()) if callable(display) else f"{type(exc).__name__}: {exc}"
except Exception: # noqa: BLE001
detail = type(exc).__name__
yield ("done", (payload(error="the script failed", detail=detail[-4_000:]), True))
return
except Exception as exc:
logger.warning("step script: runner failed (%s)", type(exc).__name__)
yield ("done", (payload(error="the script could not be run"), True))
return
finally:
slots.release()
yield ("done", (payload(result=result), False))
LIST_SAVED_TOOLS_TOOL = "list_saved_tools"
# Chat's view of the saved tools (constant definition, so the cached tool
# prefix is stable). Workflow steps get theirs in run_script's description.
LIST_SAVED_TOOLS_DEFINITION: dict[str, Any] = {
"name": LIST_SAVED_TOOLS_TOOL,
"description": (
"List the saved tools: scripts kept earlier with run_script(save_as=...) "
"and Python jobs kept with run_python_job(save_as=...). Each entry has its "
"name, what it does, the tools it calls and run_with, the tool that runs "
"it again: run_script(tool=<name>, inputs={...}) or "
"run_python_job(tool=<name>, inputs={...}, plus its files). Check here "
"before writing a script or a job you have done before."
),
"input_schema": {"type": "object", "properties": {}},
}
_MAX_INPUTS_CHARS = 20_000
_MAX_LISTED_SAVED_TOOLS = 30
def list_saved_tools_result() -> str:
"""The list_saved_tools answer: the enabled saved tools, never their scripts."""
from openexecutive.config import get_settings
from openexecutive.workflows import saved_tools
if not get_settings().saved_tools_enabled:
return json.dumps({"saved_tools": [], "note": "saved tools are turned off"})
try:
listed = saved_tools.list_tools(enabled_only=True)
except Exception:
logger.warning("saved tools: couldn't list them", exc_info=True)
return json.dumps({"error": "the saved tools couldn't be read just now"})
return json.dumps({"saved_tools": [t.summary() for t in listed]})
def usable_saved_tools(step_tools: list[str]) -> list[Any]:
"""The enabled saved tools a workflow step with these tools may run."""
from openexecutive.config import get_settings
from openexecutive.workflows import saved_tools
if not get_settings().saved_tools_enabled:
return []
allowed = set(step_tools)
try:
# Only versions the owner turned on for workflows.
listed = saved_tools.list_for_workflows()
except Exception:
logger.warning("saved tools: couldn't list them for a step", exc_info=True)
return []
# Most recently changed first, capped: the list rides in the step's tool
# definition. A tool past the cap still runs by name.
usable = [t for t in listed if set(t.tools) <= allowed]
usable.sort(key=lambda t: t.updated_at, reverse=True)
return usable[:_MAX_LISTED_SAVED_TOOLS]
def _done(fields: dict[str, Any], is_error: bool) -> ScriptYield:
return ("done", (json.dumps(fields, default=str, ensure_ascii=False), is_error))
async def run_script_tool(
arguments: dict[str, Any],
*,
tools: list[str] | None,
call: CallFn,
origin: str,
may_save: bool,
may_run_saved: bool = True,
wall_clock_s: float = _WALL_CLOCK_S,
own_tools: frozenset[str] = frozenset(),
) -> AsyncGenerator[ScriptYield, None]:
"""Answer one ``run_script`` tool use: a new script, or a saved tool.
A script that ran yields ``("stats", {calls, duration_ms})`` just before
its ``done``.
``may_save`` is whether this context may save (or re-version) a tool:
only the principal's own interactive chat turns. A saved tool runs with
the authority of whoever runs it, so its author must be trusted at least
as much as anyone who may run it — never an inbound email, a teammate, an
unattended run or a workflow step reading outside content.
``may_run_saved`` is whether it may run one: a workflow step (the owner
approved its tools) or the principal's own turn, never someone else's.
``tools`` is a workflow step's allowlist (None in chat). A saved tool runs
in a step only when every tool it used is one of the step's; in chat the
gateway checks each call as usual. With ``save_as``, a script that
succeeds is saved (approved automatically — it can only ever act through
whatever context runs it) with the tools it called. Yields like
``run_script``; never raises (cancellation aside).
"""
import time
from openexecutive.config import get_settings
from openexecutive.workflows import saved_tools
saving_on = get_settings().saved_tools_enabled
script = arguments.get("script")
tool_name = arguments.get("tool")
save_as = arguments.get("save_as")
description = arguments.get("description")
inputs = arguments.get("inputs")
if inputs is None:
inputs = {}
if not isinstance(inputs, dict):
yield _done({"error": "inputs must be an object"}, True)
return
if len(json.dumps(inputs, default=str)) > _MAX_INPUTS_CHARS:
yield _done({"error": "inputs are too large"}, True)
return
if (script is None) == (tool_name is None):
yield _done({"error": "pass either script or tool (a saved tool's name), not both"}, True)
return
saved: Any = None
if tool_name is not None:
if not saving_on:
yield _done({"error": "saved tools are turned off"}, True)
return
if save_as is not None:
yield _done({"error": "save_as goes with a new script, not a saved tool"}, True)
return
if not may_run_saved:
yield _done({"error": "saved tools run only on the principal's own turns"}, True)
return
try:
saved = (
saved_tools.get(str(tool_name))
if tools is None
else saved_tools.get_for_workflows(str(tool_name))
)
except Exception:
logger.warning("saved tool: couldn't read %r", str(tool_name)[:60], exc_info=True)
yield _done({"error": "the saved tool couldn't be read just now; nothing ran"}, True)
return
if saved is None and tools is not None:
yield _done({
"error": f"{str(tool_name)[:60]!r} is not turned on for workflows; the owner "
"turns it on in Settings → Advanced → Custom tools",
}, True)
return
if saved is None or not saved.enabled:
yield _done({"error": f"no saved tool named {str(tool_name)[:60]!r} is turned on"}, True)
return
if saved.kind != "script":
yield _done({
"error": f"{saved.name!r} is a Python tool: run it with run_python_job(tool=...)",
}, True)
return
if tools is not None and not set(saved.tools) <= set(tools):
missing = sorted(set(saved.tools) - set(tools))
yield _done({
"error": "this saved tool uses tools this step doesn't have",
"missing_tools": missing,
}, True)
return
script = saved.script
# The tools the script really reached, from every call (the result's
# calls list is capped). A step's refused names are not its tools; in
# chat a refused call (the gateway's error) is not counted either.
allowed = set(tools) if tools is not None else None
reached: set[str] = set()
call_count = 0
async def tracked(name: str, args: dict[str, Any]) -> tuple[str, bool]:
nonlocal call_count
call_count += 1
text, failed = await call(name, args)
if (name in allowed) if allowed is not None else not failed:
reached.add(name)
return text, failed
started = time.monotonic()
final: tuple[str, bool] | None = None
async for kind, payload in run_script(
str(script), tools, tracked, wall_clock_s=wall_clock_s, inputs=inputs, own=own_tools
):
if kind == "done":
final = payload
continue
yield (kind, payload)
if final is None: # run_script always ends with done; defensive
final = (json.dumps({"error": "the script did not finish"}), True)
content, is_error = final
try:
body = json.loads(content)
except ValueError:
body = {"result": content}
used = sorted(reached)
if saved is not None:
try:
saved_tools.record_run(
saved.name, saved.version, ok=not is_error, calls=call_count,
duration_ms=int((time.monotonic() - started) * 1000), origin=origin,
)
except Exception:
logger.warning("saved tool: run not recorded", exc_info=True)
if isinstance(body, dict):
body["saved_tool"] = {"name": saved.name, "version": saved.version}
elif save_as is not None:
if not saving_on:
body["save_error"] = "saved tools are turned off"
elif not may_save:
body["save_error"] = "not saved: only the principal's own turns can save tools"
elif is_error:
body["save_error"] = "not saved: the script failed"
else:
try:
kept = saved_tools.save(
str(save_as), str(description or ""), str(script), used, origin=origin
)
body["saved"] = {
"name": kept.name, "version": kept.version, "uses_tools": kept.tools,
"enabled": kept.enabled,
# Workflows run only a version the owner turned on.
"workflows": (
f"version {kept.workflow_version} is on for workflows; this one runs there "
"once the owner turns it on in Settings → Advanced → Custom tools"
if kept.workflow_version not in (None, kept.version)
else "on" if kept.workflow_version == kept.version
else "off until the owner turns it on in Settings → Advanced → Custom tools"
),
}
if not kept.enabled:
body["saved"]["note"] = "the owner turned this tool off; it won't run until they turn it on"
_audit_save(kept, origin)
except saved_tools.SavedToolError as exc:
body["save_error"] = str(exc)
except Exception:
logger.warning("saved tool: couldn't save %r", str(save_as)[:60], exc_info=True)
body["save_error"] = "not saved: storage error (the script itself ran)"
# For the audit row and the usage summary: what the script did, without
# adding to what the model reads.
yield ("stats", {
"calls": call_count,
"duration_ms": int((time.monotonic() - started) * 1000),
})
yield ("done", (json.dumps(body, default=str, ensure_ascii=False), is_error))
def _audit_save(kept: Any, origin: str) -> None:
"""One audit row per save, so a new version shows beside the owner's
own changes (saved_tool_changed)."""
from openexecutive.audit import log_event
try:
log_event(
"saved_tool_changed",
f"Custom tool {kept.name} kept (version {kept.version})",
actor="executive",
details={"name": kept.name, "version": kept.version, "uses_tools": kept.tools,
"origin": origin},
)
except Exception:
logger.warning("saved tool: couldn't audit a save", exc_info=True)
class MontyScriptShape(Exception):
"""The script awaited a future, which tools here never are."""
def available() -> bool:
"""Whether Monty is installed (it is a core dependency; this guards a
source checkout whose environment predates it)."""
try:
import pydantic_monty # noqa: F401
except ImportError:
return False
return True