Repository navigation
Expand file tree
/
Copy pathruntime.py
More file actions
1431 lines (1316 loc) · 60.9 KB
/
Copy pathruntime.py
File metadata and controls
1431 lines (1316 loc) · 60.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""Programmatic tool calling runtime backed by a pydantic-monty sandbox.
The model sees one tool, ``exec_sandbox``. Each run's code executes in a fresh Monty sandbox
where each agent tool is an async function; values a run keeps with ``store()`` are what later
runs can ``load()``. Nested calls are dispatched back through the agent's
normal tool path, so MCP routing, permissions and local runtimes still apply; only printed
output and the final expression value are returned to the model.
"""
from __future__ import annotations
import asyncio
import fnmatch
import json
import re
import time
from collections.abc import Awaitable, Callable, Mapping, Sequence
from contextlib import AsyncExitStack, suppress
from dataclasses import dataclass, field, replace
from io import StringIO
from typing import TYPE_CHECKING, Any, Literal
from mcp_types import CallToolResult, ContentBlock, TextContent, Tool
from fast_agent.constants import (
FAST_AGENT_PTC_CALLS,
FAST_AGENT_PTC_VALUE,
FAST_AGENT_SUBAGENT_RESULT_METADATA,
)
from fast_agent.core.logging.logger import get_logger
from fast_agent.mcp.tool_result_metadata import (
add_url_elicitation_required_payloads,
url_elicitation_required_payloads,
)
from fast_agent.ptc.catalog import (
PTC_SEARCH_EXTRA_BYTE_THRESHOLD,
PtcCatalog,
PtcNameLedger,
SourceRoster,
ToolRoute,
build_roster,
function_source,
unavailable_tool_message,
)
from fast_agent.ptc.output import (
OUTPUT_HELPER_NAMES,
OUTPUT_PRELUDE,
OUTPUT_STUBS,
PtcOutputGuidance,
shell_output_note,
)
from fast_agent.ptc.search import (
SEARCH_FUNCTION_NAME,
SEARCH_STUBS,
CellSearchState,
search_tools,
)
from fast_agent.ptc.store import STORE_STUBS, SandboxStore
from fast_agent.ptc.stubs import PtcFunction, build_functions, render_stubs, tool_ptc_options
from fast_agent.ptc.syntax import describe_syntax_error
from fast_agent.ptc.values import MediaStore, render_value, tool_result_to_value
from fast_agent.ptc.vocabulary import (
LEGACY_FUNCTIONS,
PTC_VOCABULARY_META,
PTC_VOCABULARY_VERSION,
is_builtin_tool,
legacy_name_hint,
undefined_names,
)
from fast_agent.tools.apply_patch_tool import (
APPLY_PATCH_INPUT_FIELD as FREEFORM_TOOL_INPUT_FIELD,
)
from fast_agent.tools.apply_patch_tool import OPENAI_RESPONSES_CUSTOM_TOOL_META_KEY
from fast_agent.tools.invocation_context import NESTED_PTC_CALL_SEPARATOR, programmatic_tool_call
from fast_agent.tools.tool_surface import (
ProgrammaticSurface,
SurfaceTool,
ToolExposure,
ToolSurface,
estimate_tokens,
tool_definition_tokens,
)
from fast_agent.utils.text import summarize_command
from fast_agent.utils.tool_names import (
POLL_PROCESS_TOOL_NAME,
PROCESS_TOOL_NAME,
)
if TYPE_CHECKING:
from pydantic_monty import AsyncMonty, AsyncMontySession
from fast_agent.config import ProgrammaticToolCallingSettings
from fast_agent.mcp.url_elicitation_required import URLElicitationRequiredDisplayPayload
from fast_agent.ptc.files import SandboxFilesystem
PTC_TOOL_NAME = "exec_sandbox"
PTC_TOOL_META = {"variant": "code", "code_arg": "code", "language": "python"}
PtcToolFormat = Literal["json", "freeform"]
# Responses custom tool calls carry their raw input under this argument name.
_FREEFORM_CODE_ARG = FREEFORM_TOOL_INPUT_FIELD
_FREEFORM_TOOL_META = {
**PTC_TOOL_META,
"code_arg": _FREEFORM_CODE_ARG,
"code_format": "raw",
}
_FREEFORM_GRAMMAR = r"""
start: SOURCE
SOURCE: /[\s\S]+/
"""
_MAX_SUSPENSIONS = 100_000
# Bound host-side print capture independently of Monty's sandbox memory limit. This protects
# host memory, not model context: bound_tool_result_for_llm still caps what the model sees, so
# do not tune this value for context size.
_MAX_PRINT_CHARS = 1_000_000
# Nested result metadata copied onto the exec_sandbox result, which is what history keeps.
_CARRIED_RESULT_META = (FAST_AGENT_SUBAGENT_RESULT_METADATA,)
ToolDispatcher = Callable[[str, dict[str, Any], str], Awaitable[CallToolResult]]
"""Dispatch a nested call: (tool name, arguments, nested call id) -> result."""
SearchObserver = Callable[[str, dict[str, Any], str], None]
"""Observe a ``search_tools`` call: (call id, arguments, result text)."""
PTC_BATCHING_INSTRUCTION_TEMPLATE = (
"Batch independent searches, file reads, and other read-only calls in a single "
"`{tool}` invocation using `asyncio.gather`. Prefer this over separate invocations "
"or sequential awaits when no result depends on another. Inspect every result; use "
"`settle()` when each result must be collected despite individual failures. Keep dependent "
"steps, approvals, and potentially conflicting mutations sequential."
)
PTC_BATCHING_INSTRUCTION = PTC_BATCHING_INSTRUCTION_TEMPLATE.format(tool=PTC_TOOL_NAME)
# The system prompt carries the batching guidance (PTC_BATCHING_INSTRUCTION); the description
# says what the sandbox is, how to call functions and what comes back. Keep every claim here
# checked against Monty: models act on it literally.
_INSTRUCTIONS = """\
Run a Python script in a sandbox: a restricted Python 3.14 interpreter (Monty), separate from \
the machine's Python. Only `print()` output and the final expression value come back to you \
(capped at about {output_limit}; longer output loses its middle): compute counts, sorts, \
filters, and compact per-item summaries in code rather than printing raw dumps.
{input_note}\
- Sandbox Python: the only importable modules are asyncio, base64, binascii, bisect, \
collections, copy, csv, dataclasses, datetime, decimal, fnmatch, functools, hashlib, itertools, json, \
math, os, os.path, pathlib, random, re, sys, time, tomllib, typing and unicodedata. No other \
standard library (difflib, heapq, io, string, struct, subprocess, ...), no packages, no \
environment variables. Unsupported syntax: class inheritance, `@staticmethod`/`@classmethod`/\
`@property`, `yield`, `del`, `async with`/`async for`, `except*`, `import *`.
{shell_python_note}\
{functions_note}\
{search_note}\
- Independent calls can run concurrently: `a, b = await asyncio.gather(f(x=1), g(y=2))` \
(asyncio, collections, datetime, itertools, json, math and re are pre-imported). `settle(aw)` returns an exception instead of raising, so \
`await asyncio.gather(*[settle(f(x=x)) for x in xs])` collects every result \
(`return_exceptions=` is unsupported).
{shell_batch_note}\
{shell_output_note}\
{io_note}\
{shared_note}\
- Function results: structured content as a dict, JSON text parsed, other text as a str. A \
failing call raises RuntimeError{shell_exit_note}.
- Images, audio and binary resources arrive as `{{"media_id": ...}}` handles: return them in \
the final expression to see them; printed handles are not attached. A structured result with \
such blocks is `{{"structured_content": ..., "content": [...]}}`.
- {store_note}{type_check_note}
"""
# Helpers defined in every sandbox session before model code runs. Common data/async
# modules are pre-imported because models routinely use them without importing in fresh runs.
_PRELUDE = """\
import asyncio
import collections
import datetime
import itertools
import json
import math
import re
async def settle(awaitable):
try:
return await awaitable
except Exception as exc:
return exc
"""
_FUNCTIONS_BLOCK = """
Available functions:
```python
{stubs}```
"""
_SEARCH_NOTE = (
"- Additional functions from connected tool sources are searchable on demand: run "
'`print(await search_tools(query="operation object"))` (or scope with `server="..."`) to '
"get full Python signatures, then call them in the next step or if you already know their "
"signature.\n"
)
_SEARCH_EXAMPLE_CALL = 'await search_tools(query="...")'
_FREEFORM_INPUT_NOTE = (
"This is a FREEFORM tool: send the Python source itself, not JSON, quotes or markdown fences.\n"
)
# The sandbox callables are always "functions"; "tool" means only something the model can call
# directly (the code tool, or a function also exposed as a direct tool). Models act on "tool"
# by emitting a direct tool call, so the wording must not blur the two.
_FUNCTIONS_NOTE = (
"- The functions below are defined in the sandbox{only_code}. Call them as "
'`r = await name(arg="value")` (async, keyword arguments only, no import). `= ...` marks an '
"optional parameter; pass `None` only where the type allows it. Where other instructions "
"{mapping}\n"
)
_TOOL_MAPPING = (
'say to use a tool of the same name (e.g. "use the `{tool}` tool"), call `{call}` here.'
)
# With only search_tools upfront, every tool other instructions name is a deferred function.
_SEARCH_MAPPING = "say to use a tool, call the function of the same name here."
_SEARCH_IO = "find them with `search_tools`"
_SHELL_BATCH_NOTE = (
"- Run independent shell commands as separate gathered `{function}` calls rather than "
"chained with `;` or `&&`, so each keeps its own stdout, stderr and exit_code: "
"`cmds = [...]` then `rs = await asyncio.gather(*[{function}(command=c) for c in cmds])`.\n"
)
_SHELL_EXIT_NOTE = (
"; a shell command that exits non-zero does not raise: check `r['exit_code']`, or pass "
"`check=True`"
)
# Running the machine's Python from a file avoids a heredoc inside a string inside a shell call.
_SHELL_PYTHON_NOTE = (
"- For other modules, packages or heavy computation, use the machine's Python: write the "
"script to a file, then run it with `{call_python}` (install `python3` if it is missing).\n"
)
_DIRECT_SHELL_PYTHON_NOTE = (
"- For other modules, packages or heavy computation, run a script with the machine's "
"`python3` using the `{tool}` tool (install `python3` if it is missing).\n"
)
_SHARED_NOTE = (
"- {functions} can also be called directly as tools: directly for a one-off step, "
"especially with quotes, heredocs or source code; from code for several steps or to "
"process results.\n"
)
_IO_NOTE = (
"- The functions are your only access to files, commands and the network, {how}; "
"`open()`, `os`, `pathlib` and `subprocess` cannot reach them here.\n"
)
_FILES_NOTE = (
"- Files are the machine's real files: `open()`, `pathlib.Path` and the `os` file functions "
"(`os.listdir`, `os.walk`, `os.path.exists`, `os.makedirs`, ...) read and write them, "
"relative to the working directory.{commands}\n"
)
_READ_LIMITS_NOTE = (
"- A read loads the whole file (at most {binary} binary or {text} text), even for `read(n)` "
"or `seek()`.{advice}\n"
)
_READ_LIMITS_ADVICE = (
" For larger or binary files, use commands such as `head -c` or `xxd` via `{shell}`."
)
_COMMANDS_NOTE = " Commands and the network go through the functions, {how}."
# Sandbox errors from trying to do I/O directly instead of through tool functions.
_DIRECT_IO_ERROR = re.compile(
r"PermissionError|`open` used when not defined|Module `os` has no member"
r"|Cannot resolve imported module `(?:subprocess|shutil|glob|io|socket|urllib|http|requests)"
)
# The same, when file operations are served by tools: only processes and other I/O are missing.
_UNSUPPORTED_IO_ERROR = re.compile(
r"Module `os` has no member"
r"|Cannot resolve imported module `(?:subprocess|shutil|glob|io|socket|urllib|http|requests)"
)
# Built-in methods and standard-library modules the sandbox lacks. Models otherwise work around
# them in sandbox code (e.g. a hand-rolled str.maketrans) instead of using the system Python.
_BUILTIN_TYPES = (
r"(?:str|bytes|bytearray|int|float|complex|list|dict|set|frozenset|tuple|bool|range)"
)
_MISSING_BUILTIN = re.compile(
rf"AttributeError: (?:type object '{_BUILTIN_TYPES}'|'{_BUILTIN_TYPES}' object) "
r"has no attribute"
)
_MISSING_MODULE = re.compile(r"(?:Cannot resolve imported module `|No module named ')([^'`\n]+)")
# A literal list inside `gather(*[... for x in [...]])` whose comprehension `]` was dropped.
_GATHER_BRACKETS = re.compile(r"closing parenthesis '\)' does not match opening parenthesis '\['")
_GATHER_HINT = (
"\nHint: in `asyncio.gather(*[f(x) for x in [...]])` the comprehension needs its own `]` "
"before `)`. Binding the list first (`items = [...]`) avoids this."
)
# pydantic-monty (1.3, 1.4) runs os.walk, os.scandir and map, but its type-checker stubs omit them.
_STUB_GAP = re.compile(
r"Module `os` has no member `(?:walk|scandir)`|Name `map` used when not defined"
)
# How Monty renders a coroutine from a function call that was never awaited.
_UNAWAITED_CALL = re.compile(r"<coroutine external_future\(\d+\)>")
_MAX_HINT_EXAMPLES = 4
_TYPE_CHECK_NOTE = " Code is type-checked against these signatures first; on errors nothing runs."
# Each run gets a fresh sandbox; the store is the only state that carries between runs.
_STORE_NOTE = (
"Each run starts in a fresh sandbox: variables, functions and imports do not carry over. "
'Keep values later runs need with `await store("rows", rows)` and get them back with '
'`rows = await load("rows")`; `await stored()` lists what is kept.'
)
@dataclass(slots=True)
class _ExecutionStats:
completed: list[str] = field(default_factory=list)
failed: list[str] = field(default_factory=list)
started: int = 0
calls: list[dict[str, Any]] = field(default_factory=list)
# Nested results are consumed in the sandbox, so URL elicitations must be carried to the
# exec_sandbox result for the user to see them.
url_elicitations: list[URLElicitationRequiredDisplayPayload] = field(default_factory=list)
# Commands the shell returned while still running, by process id, with their command
# text; a later wait or stop that sees them end removes them.
running: dict[str, str] = field(default_factory=dict)
def track_process(self, arguments: Mapping[str, Any], result: CallToolResult) -> None:
value = (result.meta or {}).get(FAST_AGENT_PTC_VALUE)
if not isinstance(value, Mapping) or not isinstance(value.get("process_id"), str):
return
process_id = value["process_id"]
if value.get("status") != "running":
self.running.pop(process_id, None)
elif process_id not in self.running:
self.running[process_id] = str(arguments.get("command") or "")
@dataclass(slots=True)
class _NestedCalls:
"""Runs one execution's nested tool calls, for sandbox functions and file operations."""
dispatch: ToolDispatcher
stats: _ExecutionStats
call_prefix: str
execution_started: float = field(default_factory=time.perf_counter)
# Outstanding dispatches only: a finished task holds its full result, which sandbox code may
# long since have discarded, so keeping them all would grow host memory with fetched data.
tasks: set[asyncio.Task[CallToolResult]] = field(default_factory=set)
async def call(
self, tool_name: str, arguments: dict[str, Any], *, function_name: str | None = None
) -> CallToolResult:
task = asyncio.create_task(self._run(tool_name, arguments, function_name or tool_name))
self.tasks.add(task)
task.add_done_callback(self.tasks.discard)
# Own dispatch lifetime independently of Monty's callback tasks. Script errors
# drain these tasks; turn cancellation explicitly cancels and settles them.
return await asyncio.shield(task)
async def _run(
self, tool_name: str, arguments: dict[str, Any], function_name: str
) -> CallToolResult:
stats = self.stats
stats.started += 1
call_id = f"{self.call_prefix}{stats.started}"
# Snapshot before dispatch: tools may mutate arguments, and parallel calls may
# finish out of order. This ledger is metadata, never model-visible output.
call_started = time.perf_counter()
record = _started_call_record(call_id, tool_name, arguments)
record["function"] = function_name
record["start_offset_ms"] = round(
max(0.0, (call_started - self.execution_started) * 1000), 2
)
stats.calls.append(record)
try:
with programmatic_tool_call(call_id):
result = await self.dispatch(tool_name, arguments, call_id)
except asyncio.CancelledError:
record["status"] = "cancelled"
raise
except Exception:
record.update(status="raised", is_error=True)
stats.failed.append(function_name)
raise
finally:
record["timing_ms"] = round(max(0.0, (time.perf_counter() - call_started) * 1000), 2)
record.update(_call_record(call_id, tool_name, result), status="completed")
(stats.failed if result.is_error else stats.completed).append(function_name)
stats.track_process(arguments, result)
stats.url_elicitations.extend(url_elicitation_required_payloads(result))
return result
@dataclass(slots=True)
class _PrintedOutput:
buffer: StringIO = field(default_factory=StringIO)
size: int = 0
truncated: bool = False
def append(self, _stream: str, text: str) -> None:
remaining = _MAX_PRINT_CHARS - self.size
if len(text) > remaining:
self.truncated = True
text = text[:remaining]
if text:
self.buffer.write(text)
self.size += len(text)
def render(self) -> str:
printed = self.buffer.getvalue().rstrip()
if self.truncated:
printed += "\n[Printed output truncated]"
return printed
class ProgrammaticToolRuntime:
"""Owns the Monty pool, a fresh sandbox per run, and the store that runs share."""
def __init__(
self, settings: ProgrammaticToolCallingSettings, *, ledger: PtcNameLedger | None = None
) -> None:
self._settings = settings
# ptc-vocab-v0: route override can change without resetting the sandbox store.
self.function_names = settings.function_names
# The name avoids "python": models treat a Python-named tool as the machine's Python.
self.tool_name = PTC_TOOL_NAME
# Defer extra function definitions behind search_tools; the agent applies CLI overrides.
self.search_enabled = settings.search
# When True (e.g. --ptc-search), defer extra functions even below the stub byte budget.
self.search_forced = False
self._direct_patterns = list(settings.direct_tools)
self._warned_patterns: set[str] = set()
self._ledger = ledger if ledger is not None else PtcNameLedger()
self._catalog = PtcCatalog(type_check_stubs=render_stubs({}))
self._direct_shell_tool: str | None = None
self._tool_format: PtcToolFormat = "json"
# Shell output guidance in effect: "off" unless sandbox code can run local shell commands.
self._output_guidance: PtcOutputGuidance = "off"
self._result_byte_limit = settings.output_byte_limit
self._pool: AsyncMonty | None = None
self._pool_stack = AsyncExitStack()
self._store = SandboxStore()
self._file_read = False
self._file_write = False
self._lock = asyncio.Lock()
self._executions = 0
self._media = MediaStore()
@property
def functions(self) -> Mapping[str, PtcFunction]:
"""Every function sandbox code can call, including deferred ones."""
return self._catalog.functions
@property
def catalog(self) -> PtcCatalog:
"""The catalogue built by the latest ``model_tools()`` call."""
return self._catalog
@property
def batching_instruction(self) -> str:
"""System-prompt guidance on batching calls in the code tool."""
return PTC_BATCHING_INSTRUCTION_TEMPLATE.format(tool=self.tool_name)
def resolve_tool_format(self, model_default: PtcToolFormat | None) -> PtcToolFormat:
"""Apply ``ptc.tool_format``, using the model's default when it is ``auto``."""
if self._settings.tool_format != "auto":
return self._settings.tool_format
return model_default or "json"
def resolve_output_guidance(self, model_default: PtcOutputGuidance | None) -> PtcOutputGuidance:
"""Apply ``ptc.output_guidance``, using the model's default when it is ``auto``."""
if self._settings.output_guidance != "auto":
return self._settings.output_guidance
return model_default or "helpers"
def model_tools(
self,
tools: Sequence[Tool],
*,
tool_format: PtcToolFormat = "json",
output_guidance: PtcOutputGuidance = "off",
result_byte_limit: int | None = None,
file_read: bool = False,
file_write: bool = False,
sources: Mapping[str, str] | None = None,
unavailable_sources: Mapping[str, str] | None = None,
routes: Mapping[str, ToolRoute] | None = None,
) -> list[Tool]:
"""Replace the agent's tools with the code tool, keeping configured direct tools.
``result_byte_limit`` is how much of a code tool result the model sees, for the
shell output guidance and search results. ``sources`` overrides the source group of
tools by listed name; ``unavailable_sources`` notes configured sources without
loaded functions; ``routes`` (the tools' origins by listed name) is kept with the
catalogue for dispatching its runs' calls.
"""
self._tool_format = tool_format
names = {tool.name for tool in tools}
builtin_names = {tool.name for tool in tools if is_builtin_tool(tool)}
self._direct_patterns = []
# ptc-vocab-v0: remove direct-selector migration after matched rollout.
for pattern in self._settings.direct_tools:
replacement = LEGACY_FUNCTIONS.get(pattern)
if self.vocabulary == 1 and pattern not in names and replacement in builtin_names:
self._direct_patterns.append(replacement)
if pattern not in self._warned_patterns:
get_logger(__name__).warning(
f"ptc.direct_tools: '{pattern}' is now '{replacement}'; update your config."
)
self._warned_patterns.add(pattern)
else:
self._direct_patterns.append(pattern)
direct = [tool for tool in tools if self._direct_reason(tool) is not None]
nested = [tool for tool in tools if self._is_nested(tool)]
local_shell = any(_returns_shell_output(tool) for tool in nested)
self._output_guidance = output_guidance if local_shell else "off"
self._result_byte_limit = (
self._settings.output_byte_limit if result_byte_limit is None else result_byte_limit
)
self._direct_shell_tool = next(
(tool.name for tool in direct if _returns_shell_output(tool)), None
)
self._file_read = file_read
self._file_write = file_write
self._catalog = self._build_catalog(
nested,
direct_names={tool.name for tool in direct},
sources=sources or {},
unavailable_sources=unavailable_sources or {},
routes=routes or {},
)
return [self.tool(), *direct]
def _build_catalog(
self,
nested: Sequence[Tool],
*,
direct_names: set[str],
sources: Mapping[str, str],
unavailable_sources: Mapping[str, str],
routes: Mapping[str, ToolRoute],
) -> PtcCatalog:
canonical = self.vocabulary == 1
reserved = OUTPUT_HELPER_NAMES if self._output_guidance != "off" else frozenset()
functions = build_functions(
nested,
profile_names=not canonical,
reserved_names=(reserved | {SEARCH_FUNCTION_NAME}) if canonical else reserved,
ledger=self._ledger if canonical else None,
routes=routes,
)
tools = {tool.name: tool for tool in nested}
function_sources = {
name: function_source(
tools[function.tool_name], sources, routes.get(function.tool_name)
)
for name, function in functions.items()
}
# Built-ins and functions the model can also call directly always stay upfront.
extras = [
name
for name, function in functions.items()
if not is_builtin_tool(tools[function.tool_name])
and function.tool_name not in direct_names
]
extra_stub_bytes = sum(len(functions[name].stub().encode("utf-8")) for name in extras)
search_active = (
self.search_enabled
and canonical
and bool(extras)
and (self.search_forced or extra_stub_bytes > PTC_SEARCH_EXTRA_BYTE_THRESHOLD)
)
deferred = frozenset(extras) if search_active else frozenset()
stubs = render_stubs(functions)
if self._output_guidance != "off":
stubs += OUTPUT_STUBS
if search_active:
stubs += SEARCH_STUBS
return PtcCatalog(
functions=functions,
tools=tools,
sources=function_sources,
deferred=deferred,
search_active=search_active,
roster=(
build_roster(function_sources, deferred, unavailable_sources)
if search_active
else SourceRoster()
),
shared_functions=tuple(
function.python_name
for function in functions.values()
if function.tool_name in direct_names
),
shell_function=next(
(
function
for name, function in functions.items()
if name not in deferred and _returns_shell_output(tools[function.tool_name])
),
None,
),
type_check_stubs=stubs,
retired=self._ledger.retired(functions) if canonical else frozenset(),
routes=routes,
)
def _prelude(self, catalog: PtcCatalog) -> str:
# Old calls stay catchable after a refresh, without advertising missing tools.
helpers = self._output_guidance != "off"
retired = catalog.retired - OUTPUT_HELPER_NAMES if helpers else catalog.retired
unavailable = "".join(
f"\nasync def {name}(*args, **kwargs):\n"
f" raise RuntimeError({unavailable_tool_message(name)!r})\n"
for name in sorted(retired)
)
return _PRELUDE + unavailable + (OUTPUT_PRELUDE if helpers else "")
def surface(
self, model_tools: Sequence[Tool], *, seen_signatures: frozenset[str] = frozenset()
) -> ToolSurface:
"""Describe ``model_tools`` (as returned by ``model_tools()``) and the sandbox functions."""
exposed = [
SurfaceTool(
tool=tool,
exposure=ToolExposure.MODEL,
context_tokens=tool_definition_tokens(tool),
direct_reason=self._direct_reason(tool),
)
for tool in model_tools
]
catalog = self._catalog
nested: list[SurfaceTool] = []
for name, function in catalog.functions.items():
stub = function.stub()
tokens = estimate_tokens(stub)
deferred = name in catalog.deferred
signature = function.signature()
nested.append(
SurfaceTool(
tool=catalog.tools[function.tool_name],
exposure=ToolExposure.PROGRAMMATIC,
context_tokens=0 if deferred else tokens,
python_name=function.python_name,
signature=signature,
stub=stub,
deferred=deferred,
stub_tokens=tokens,
source=catalog.sources[name],
seen=deferred and signature in seen_signatures,
)
)
return ToolSurface(
tools=(*exposed, *nested),
programmatic=ProgrammaticSurface(
tool_name=self.tool_name,
vocabulary=self.vocabulary,
tool_format=self._tool_format,
instructions=self._instructions(),
type_check=self._settings.type_check,
max_duration_seconds=self._settings.max_duration_seconds,
max_memory_mb=self._settings.max_memory_mb,
search_active=catalog.search_active,
retired=catalog.retired,
),
)
@property
def vocabulary(self) -> int:
"""Zero identifies the temporary per-model profile arm, one the canonical surface."""
return PTC_VOCABULARY_VERSION if self.function_names == "canonical" else 0
def _instructions(self) -> str:
catalog = self._catalog
shared = ", ".join(f"`{name}`" for name in catalog.shared_functions)
shell = catalog.shell_function
return _INSTRUCTIONS.format(
output_limit=f"{max(1, round(self._result_byte_limit / 1000))} KB",
shell_exit_note=_SHELL_EXIT_NOTE if shell else "",
functions_note=self._functions_note(catalog),
search_note=_SEARCH_NOTE if catalog.search_active else "",
io_note=self._io_note(catalog),
shell_python_note=self._shell_python_note(catalog),
shell_output_note=self._shell_output_note(catalog),
shell_batch_note=_SHELL_BATCH_NOTE.format(function=shell.python_name) if shell else "",
shared_note=_SHARED_NOTE.format(functions=shared) if shared else "",
input_note=_FREEFORM_INPUT_NOTE if self._tool_format == "freeform" else "",
store_note=_STORE_NOTE,
type_check_note=_TYPE_CHECK_NOTE if self._settings.type_check else "",
)
def _functions_note(self, catalog: PtcCatalog) -> str:
example = _example_function(catalog)
if example is not None:
mapping = _TOOL_MAPPING.format(tool=example.tool_name, call=example.example_call())
elif catalog.search_active:
mapping = _SEARCH_MAPPING
else:
return ""
return _FUNCTIONS_NOTE.format(
only_code="" if catalog.shared_functions else ", and code is the only way to call them",
mapping=mapping,
)
def _shell_output_note(self, catalog: PtcCatalog) -> str:
shell = catalog.shell_function
if self._output_guidance == "off" or shell is None:
return ""
wait, read = None, None
for function in catalog.upfront:
name = function.tool_name.casefold()
if name == PROCESS_TOOL_NAME:
wait = f"await {function.python_name}(action='wait', process_id=r['process_id'])"
read = (
f"await {function.python_name}(action='read_output', process_id=..., "
"query='error')"
)
break
if name == POLL_PROCESS_TOOL_NAME:
wait = f"await {function.python_name}(process_id=r['process_id'])"
break
return shell_output_note(
self._output_guidance,
call=shell.example_call(),
result_byte_limit=self._result_byte_limit,
wait=wait,
read=read,
)
def _shell_python_note(self, catalog: PtcCatalog) -> str:
if catalog.shell_function is not None:
return _SHELL_PYTHON_NOTE.format(
call_python=f'await {catalog.shell_function.python_name}(command="python3 script.py")'
)
if self._direct_shell_tool is not None:
return _DIRECT_SHELL_PYTHON_NOTE.format(tool=self._direct_shell_tool)
return ""
def _io_note(self, catalog: PtcCatalog) -> str:
example = _example_function(catalog)
how = f"e.g. `r = {example.example_call()}`" if example else None
if how is None and catalog.search_active:
how = _SEARCH_IO
if self._file_read or self._file_write:
from fast_agent.ptc.files import MAX_BINARY_READ_BYTES, MAX_TEXT_READ_BYTES, format_size
files_note = _FILES_NOTE.format(
commands=_COMMANDS_NOTE.format(how=how) if how else "",
)
return files_note + _READ_LIMITS_NOTE.format(
binary=format_size(MAX_BINARY_READ_BYTES),
text=format_size(MAX_TEXT_READ_BYTES),
advice=_READ_LIMITS_ADVICE.format(shell=catalog.shell_function.python_name)
if catalog.shell_function
else "",
)
return _IO_NOTE.format(how=how) if how else ""
def _io_guidance(self, catalog: PtcCatalog) -> str:
"""Tell sandbox code that cannot do some I/O itself which functions can."""
calls = [function.example_call() for function in catalog.upfront[:_MAX_HINT_EXAMPLES]]
if catalog.search_active:
calls.append(_SEARCH_EXAMPLE_CALL)
if not calls:
return "No functions are available to do it."
examples = ", ".join(f"`{call}`" for call in calls)
return f"Call the functions from this code instead, e.g. {examples}."
def _direct_io_hint(self, detail: str, catalog: PtcCatalog) -> str:
"""Point code that tried to do I/O itself at the tool functions that can."""
if not catalog.functions:
return ""
if self._file_read or self._file_write:
unsupported = (
line
for line in detail.splitlines()
if _UNSUPPORTED_IO_ERROR.search(line) and not _STUB_GAP.search(line)
)
if next(unsupported, None) is None:
return ""
return (
"\nHint: that is not available in the sandbox. Use `open()`, `pathlib.Path` "
"(including `Path.glob`) or `os` for files. " + self._io_guidance(catalog)
)
if _DIRECT_IO_ERROR.search(detail) is None:
return ""
return "\nHint: sandbox code cannot touch files or processes itself. " + self._io_guidance(
catalog
)
def unavailable_tool_hint(self, name: str) -> str | None:
"""Explain how to reach a tool the model called directly that only code can call."""
# ptc-vocab-v0: remove legacy direct-call lookup after matched rollout.
catalog = self._catalog
lookup_name = name
if self.vocabulary == 1 and name not in catalog.functions:
lookup_name = LEGACY_FUNCTIONS.get(name, name)
function = next(
(
function
for function in catalog.functions.values()
if lookup_name in (function.tool_name, function.python_name)
and function.python_name not in catalog.shared_functions
),
None,
)
if function is None:
return None
return (
f"`{name}` is not a direct tool; it is a function inside `{self.tool_name}`. "
f"Call `{self.tool_name}` with code such as `r = {function.example_call()}` "
"then `print(r)`."
)
def tool_meta(self) -> dict[str, Any]:
"""Display metadata for the code tool in its current input format."""
return {
**(_FREEFORM_TOOL_META if self._tool_format == "freeform" else PTC_TOOL_META),
PTC_VOCABULARY_META: self.vocabulary,
}
def tool(self) -> Tool:
catalog = self._catalog
stubs = "\n\n".join(
[
*(function.stub() for function in catalog.upfront),
*([SEARCH_STUBS.rstrip()] if catalog.search_active else []),
STORE_STUBS.rstrip(),
]
)
freeform = self._tool_format == "freeform"
code_arg = _FREEFORM_CODE_ARG if freeform else "code"
meta = self.tool_meta()
if freeform:
# Providers without custom tools ignore this and send the JSON schema below.
meta[OPENAI_RESPONSES_CUSTOM_TOOL_META_KEY] = {
"type": "custom",
"format": {"type": "grammar", "syntax": "lark", "definition": _FREEFORM_GRAMMAR},
}
return Tool(
name=self.tool_name,
description=self._instructions() + _FUNCTIONS_BLOCK.format(stubs=f"{stubs}\n"),
input_schema={
"type": "object",
"properties": {
code_arg: {
"type": "string",
"description": "Python source to run. Not JSON, not markdown fenced.",
}
},
"required": [code_arg],
"additionalProperties": False,
},
meta=meta,
)
async def execute(
self,
arguments: Mapping[str, Any],
dispatch: ToolDispatcher,
*,
catalog: PtcCatalog | None = None,
parent_call_id: str | None = None,
cwd: str | None = None,
on_search: SearchObserver | None = None,
) -> CallToolResult:
"""Run model code; nested call ids derive from ``parent_call_id`` when it is known.
``catalog`` is the catalogue the run uses, by default the latest; a caller that routes
nested calls by a catalogue's ``routes`` passes the one it captured. ``cwd`` is the
tools' working directory, against which sandbox code resolves relative file paths; it
must be an absolute POSIX path. ``on_search`` observes ``search_tools`` calls, which
the runtime answers itself rather than dispatching.
"""
result = await self._execute(
arguments,
dispatch,
catalog=catalog,
parent_call_id=parent_call_id,
cwd=cwd,
on_search=on_search,
)
result.meta = {**(result.meta or {}), PTC_VOCABULARY_META: self.vocabulary}
return result
async def _execute(
self,
arguments: Mapping[str, Any],
dispatch: ToolDispatcher,
*,
catalog: PtcCatalog | None,
parent_call_id: str | None,
cwd: str | None,
on_search: SearchObserver | None,
) -> CallToolResult:
"""Execute validated code and collect nested calls."""
# Accept both input formats: history can contain calls made before a model switch.
code = arguments.get("code", arguments.get(_FREEFORM_CODE_ARG))
if not isinstance(code, str) or not code.strip():
return _error_result("`code` must be a non-empty string of Python source.")
from pydantic_monty import (
MontyCrashedError,
MontyError,
MontyRuntimeError,
MontySyntaxError,
MontyTypingError,
)
async with self._lock:
# One catalogue for the whole run: a tool list refresh applies from the next run.
catalog = self._catalog if catalog is None else catalog
prelude = self._prelude(catalog)
self._executions += 1
stats = _ExecutionStats()
output = _PrintedOutput()
started = time.perf_counter()
calls = _NestedCalls(
dispatch,
stats,
call_prefix=(
f"{parent_call_id}{NESTED_PTC_CALL_SEPARATOR}"
if parent_call_id
else f"ptc-{self._executions}-"
),
execution_started=started,
)
from fast_agent.ptc.files import SandboxFilesystem
files = SandboxFilesystem(read=self._file_read, write=self._file_write)
dispatches = calls.tasks
lookup: dict[str, Callable[..., Awaitable[Any]]] = {
name: self._host_function(function, calls)
for name, function in catalog.functions.items()
}
if catalog.search_active:
lookup[SEARCH_FUNCTION_NAME] = _search_function(
catalog, calls, on_search, byte_limit=self._result_byte_limit
)
lookup.update(self._store.functions())
try:
async with await self._checkout(catalog) as session:
await session.feed_run(prelude)
try:
value = await self._feed(session, code, lookup, output, files, cwd)
except Exception:
# A failed gather can leave sibling tools running. Settle them before
# reporting completed side effects and copying nested result metadata.
await asyncio.gather(*dispatches, return_exceptions=True)
raise
await asyncio.gather(*dispatches, return_exceptions=True)
except asyncio.CancelledError:
for task in list(dispatches):
task.cancel()
await asyncio.gather(*dispatches, return_exceptions=True)
raise
except MontyTypingError as exc:
# The type checker also reports syntax errors, mixed with errors they cause.
detail = exc.display()
report = (
self._describe_syntax_error(code, catalog)
if "invalid-syntax" in detail
else None
)
if report is not None:
return _syntax_error_result(report)
return _error_result(
"Type check failed; the code was NOT executed. Fix it and retry.\n"
+ detail
+ self._error_hints(detail, catalog)
+ _argument_type_hints(detail, catalog)
+ self._name_hints(undefined_names(detail), catalog)
)
except MontySyntaxError as exc:
return _syntax_error_result(
self._describe_syntax_error(code, catalog) or exc.display()
)
except MontyRuntimeError as exc:
detail = exc.display()
return self._failure(
detail
+ self._error_hints(detail, catalog)
+ self._name_hints(undefined_names(detail, ran=True), catalog),
output,
stats,
started,
catalog,
)
except MontyCrashedError as exc:
return self._failure(
f"{exc}\nThe sandbox crashed.", output, stats, started, catalog
)
except MontyError as exc:
return self._failure(str(exc), output, stats, started, catalog)
finally:
await files.close()
return self._success(value, output, stats, started, catalog)
def _describe_syntax_error(self, code: str, catalog: PtcCatalog) -> str | None:
report = describe_syntax_error(code, direct_functions=catalog.shared_functions)
if report is not None and _GATHER_BRACKETS.search(report) and "gather(*[" in code:
report += _GATHER_HINT
return report
def _error_hints(self, detail: str, catalog: PtcCatalog) -> str:
return self._direct_io_hint(detail, catalog) or _sandbox_gap_hint(detail, catalog)
def _name_hints(self, undefined: set[str], catalog: PtcCatalog) -> str:
"""Explain renamed functions and inactive search."""
# ptc-vocab-v0: remove undefined-name hints after matched rollout.
legacy = legacy_name_hint(undefined, catalog.functions) if self.vocabulary == 1 else ""
if SEARCH_FUNCTION_NAME in undefined and not catalog.search_active:
return legacy + (
f"\nHint: `{SEARCH_FUNCTION_NAME}` is not active because all available functions "
f"are already listed in `{PTC_TOOL_NAME}`."
)
return legacy