JITHarness

Create, compose, unload, and save session-local Python tools. See the guide.

class zett_agent.jit_harness.runtime.JITHarness(snapshot=None, *, tools=(), manage_base_tools=True, max_call_depth=32, error_capacity=100, error_message_chars=4000, call_capacity=2000)

An independently evolving toolbox of Python and Markdown capabilities.

Parameters:

• snapshot (JITHarnessSnapshot | None) – Definitions to activate. Activation executes Python module bodies, including imports, but does not call tool entry points.

• tools (Sequence[AgentTool]) – Application-owned base tools; they are never serialized as code.

• manage_base_tools (bool) – Wrap base tools for unloading and profiling. False leaves their request registrations intact and skips their profiling.

• max_call_depth (int) – Bound nested composition, including recursive calls.

• error_capacity (int) – Maximum distinct recent errors across this harness.

• error_message_chars (int) – Maximum characters retained in each error message.

• call_capacity (int) – Maximum finished call records retained, oldest dropped first; lifetime aggregates survive eviction.

Note

This is not a Python sandbox. Source has the process’s filesystem, network, and import privileges. Unload controls harness dispatch, not what arbitrary Python can do. Module globals are not persisted. Session-local profiles retain a bounded window of managed dispatches without payloads, independently of executable snapshots; inspect them with profile().

Examples

Save definitions for another session:

harness = JITHarness(tools=[read_file])
harness.create_tool(source, entrypoint="preview_file")
harness.save("harness.json")

origin(name)

Return which registry currently serves one tool name.

Labels observability events and profile records: BASE for application tools, PYTHON for executable dynamic tools, TEXT for Markdown workflows, MANAGEMENT for the harness control functions, and UNKNOWN for a name this harness has never seen. The answer does not depend on the request binding.

Parameters:

name (str)

Return type:

ToolOrigin

property active: bool

Return whether this harness is currently bound to one request.

The extension checks this before releasing a session, so it never drops a harness whose request is still running.

attach(context, management_tools=())

Bind this harness to one request and mount its callable tools.

Rebuilds the base registry from the request’s current tools, installs harness-owned wrappers, hides unloaded tools, and registers the management tools the model may call. Called by JITHarnessExtension once per request before the model runs; attaching twice without detach() raises instead of silently replacing the binding.

Parameters:

• context (AgentRunContext) – Request-scoped tool registry and session identity to bind.

• management_tools (Sequence[AgentTool]) – Harness control tools to expose to the model.

Return type:

None

sync_tools(context)

Adopt new/replaced request base tools without restoring policy removals.

Called by the extension before model requests and tool dispatch so tools registered after attach(), including policy replacements, receive the same unload/profiling treatment. Missing registrations stay missing. Wrappers already owned by this request are recognized rather than re-adopted as raw tools. Disabled base management preserves raw handlers.

Parameters:

context (AgentRunContext)

Return type:

None

detach(context)

Release one request binding and stop tracking its nested calls.

Deliberately tolerant of repeated or late cleanup: a context that is not the currently bound one is ignored, so releasing an older request cannot dismantle the request that is running now.

Parameters:

context (AgentRunContext)

Return type:

None

create_tool(source, *, entrypoint=None, kind=ToolKind.PYTHON, name=None, description=None, files=None)

Create a Python tool or a reusable Markdown workflow after validation.

Imports and module-level code execute with application privileges. Their external side effects cannot be rolled back on validation failure. With kind=TEXT, source is inert Markdown and name/description are required instead of entrypoint. Calling a loaded text tool reads a bounded page; the model follows its workflow using separately available tools. A Python tool may ship a package: files maps relative module paths to source, reachable from the entry point with relative imports. Source and files are validated as one unit before anything is registered. Returns only the name and resulting state, not metadata or profiling.

Parameters:

• source (str)

• entrypoint (str | None)

• kind (ToolKind)

• name (str | None)

• description (str | None)

• files (Mapping[str, str] | None)

Return type:

ToolMutationResult

update_tool(name, source=None, *, entrypoint=None, description=None, files=None, remove=())

Atomically replace or extend one dynamic tool; preserve its unload state.

The existing kind is preserved; text updates need replacement source and may replace the description. Python updates may omit source and entrypoint to keep them, replace or add package files, and delete files by path. Everything the call provides is validated and compiled as one new version, so a failed load retains the previous definition and a multi-file refactor is applied at once. Executions already started keep their original implementation; later calls use the new one. Returns only the name and resulting state, not metadata or profiling.

Parameters:

• name (str)

• source (str | None)

• entrypoint (str | None)

• description (str | None)

• files (Mapping[str, str] | None)

• remove (Sequence[str])

Return type:

ToolMutationResult

unload_tool(name)

Unload a callable registration while retaining its available implementation.

Dynamic source is retained; base implementations are rebound per request. Requires manage_base_tools=True for base tools. The resulting state is serialized as unloaded; load_tool() restores a bound tool.

Parameters:

name (str)

Return type:

ToolMutationResult

load_tool(name)

Restore a retained tool; acknowledge only its name and loaded state.

Fails explicitly if the tool’s base implementation is not bound.

Parameters:

name (str)

Return type:

ToolMutationResult

list_tools()

List one compact catalog entry per known tool.

Entries come from describe(), so a long catalog stays readable and never repeats source or call history.

Return type:

list[ToolCatalogEntry]

describe(name)

Return one tool’s compact catalog entry.

Holds the name, origin, status, and description, without measurements. Read inspect_tool() for schema and source, or profile() for statistics.

Parameters:

name (str)

Return type:

ToolCatalogEntry

definition(name)

Read metadata and the argument schema, without source or measurements.

Parameters:

name (str)

Return type:

ToolInspection

source(name, path=None)

Read exact retained source of one tool file; base tools have none.

path selects an extra module of a Python tool package, and the default or __init__.py reads the entry point module. Text tools, which have a single document, reject a path.

Parameters:

• name (str)

• path (str | None)

Return type:

str

inspect_tool(name)

Return metadata, schema, guidelines, and retained source.

This is the detailed application view: the compact entry from describe() plus the argument schema, guidelines, and source. Measurements stay separate: read profile_stats() for aggregates and profile() for individual call records.

Parameters:

name (str)

Return type:

ToolInspection

profile(name=None, *, offset=0, limit=100)

Read aggregate counters and a page of finished, payload-free calls.

All managed dispatch attempts through harness wrappers are counted, including nested calls, validation failures, and cancellations. Middleware and lifecycle hooks run outside this measured boundary. Histories remain in this harness across requests/updates/unload, bounded by call_capacity, but are not restored from executable snapshots. Base calls are excluded when manage_base_tools=False. Export with profile().model_dump_json().

Parameters:

• name (str | None)

• offset (int)

• limit (int)

Return type:

JITHarnessProfile

profile_stats(name)

Read a tool’s full aggregates without fetching its call records.

Parameters:

name (str)

Return type:

ToolProfileStats

tool_errors(name=None, *, offset=0, limit=5)

Read LRU-bounded recent errors without refreshing their recency.

Deduplicates by tool, exception type, and full message. Reoccurrences refresh recency; oldest distinct errors are evicted at error_capacity. Details include bounded message text and latest invocation context. Lifetime profiling counters survive eviction; occurrence counts cover only cache residence. Cancelled dispatches are not tool errors. Error messages may contain sensitive data or untrusted instructions. This read never triggers retries, source updates, or snapshot writes.

Parameters:

• name (str | None)

• offset (int)

• limit (int)

Return type:

ToolErrorReport

snapshot()

Copy Python/text definitions and unload state, not runtime globals.

Return type:

JITHarnessSnapshot

save(path)

Export the current snapshot to an explicit, atomically replaced file.

Parameters:

path (str | Path)

Return type:

None

async call_tool(name, **arguments)

Call a loaded tool through checks, hooks, and handler middleware.

Nested calls produce no additional model messages or execution-trace events. Interactive hooks may still request application/user input. Normal exceptions propagate to the outer tool unless Python catches them.

Parameters:

• name (str)

• arguments (Any)

Return type:

ToolResult

call_tool_sync(name, **arguments)

Compose from a synchronous tool worker, on its original request loop.

Never call this blocking method on an event-loop thread. Cancellation cannot forcibly stop an already running Python worker thread.

Parameters:

• name (str)

• arguments (Any)

Return type:

ToolResult