TAI42 — the OS for AI tools

Tools contract: the ToolInfo model + the AppTools tool/toolkit registration sub-protocol. Vendor return types (fastmcp Tool, langchain StructuredTool) are TYPE_CHECKING-only. AppTools is the app.tools namespace of the assembled facade (tai42_contract.app).

DEFAULT_RETRYABLE_KINDS

tai42_contract.tools.retry.DEFAULT_RETRYABLE_KINDS

DEFAULT_RETRYABLE_KINDS: frozenset[ErrorKind] = frozenset({ErrorKind.TIMED_OUT, ErrorKind.UNAVAILABLE})

MAX_ATTEMPTS_CEILING

tai42_contract.tools.retry.MAX_ATTEMPTS_CEILING

MAX_ATTEMPTS_CEILING = 10

NEVER_RETRYABLE_KINDS

tai42_contract.tools.retry.NEVER_RETRYABLE_KINDS

NEVER_RETRYABLE_KINDS: frozenset[ErrorKind] = frozenset({ErrorKind.UNKNOWN, ErrorKind.CANCELLED})

AppTools

tai42_contract.tools.AppTools

class AppTools(Protocol)

Tool + toolkit registration / lookup surface.

Members

tool_title

tai42_contract.tools.AppTools.tool_title

tool_title(self, func: Callable[..., object]) -> str

Return the human-facing title of the tool implemented by func. Parameters

Parameter	Type	Default	Description
`func`	`Callable[..., object]`	—	—

get_tool

tai42_contract.tools.AppTools.get_tool

async get_tool(self, key: str) -> Tool

Return the assembled tool registered under key. Parameters

Parameter	Type	Default	Description
`key`	`str`	—	—

get_tools

tai42_contract.tools.AppTools.get_tools

async get_tools(self) -> dict[str, Tool]

Return every assembled tool keyed by name.

get_client_tools

tai42_contract.tools.AppTools.get_client_tools

async get_client_tools(self, names: list[str] | None = None) -> list[StructuredTool]

Return the client-facing tool objects, restricted to names when given. Parameters

Parameter	Type	Default	Description
`names`	`list[str] \| None`	`None`	—

run_tool

tai42_contract.tools.AppTools.run_tool

async run_tool(
    self,
    key: str,
    arguments: dict[str, Any],
    *,
    offload_sync: bool = False,
    continues_chain: Sequence[str] | None = None,
    extras: Mapping[str, Any] | None = None,
) -> Any

Execute the tool registered under key with arguments and return its result. offload_sync runs a synchronous tool body off the event loop in a worker thread. continues_chain is an in-process seam keyword ONLY (no request model, MCP argument, or tool argument sets it): when given, the dispatch’s call frame SETS the ambient call chain to it rather than pushing key, so a continuation runner restores a parked run’s chain on the one dispatch that resumes it. extras is likewise an in-process seam keyword ONLY (no request model, MCP argument, or tool argument sets it): the mapping a door carries into the run it starts. It is set on the dispatch’s call frame — ambient and read-only for THAT frame, so the started tool reads it through extras and every nested frame starts empty. A visit checks the keys against the target’s declaration before the run; None binds an empty mapping. Parameters

Parameter	Type	Default	Description
`key`	`str`	—	—
`arguments`	`dict[str, Any]`	—	—
`offload_sync`	`bool`	`False`	—
`continues_chain`	`Sequence[str] \| None`	`None`	—
`extras`	`Mapping[str, Any] \| None`	`None`	—

extras

tai42_contract.tools.AppTools.extras

extras(self) -> Mapping[str, Any]

The ambient door extras mapping the current run was started with (empty when none). A door carries author-configured extras into a run; a tool reads the keys it declared (@app.tools.tool(extras_keys=...)) here. The mapping is read-only and scoped to the started target’s own frame — every nested dispatch reads an empty mapping, so nothing leaks down. No request model, MCP argument, or tool argument can set it.

declared_extras

tai42_contract.tools.AppTools.declared_extras

async declared_extras(self, name: str) -> frozenset[str]

The door extras keys tool name is declared to read (empty when it declares none). A preset inherits its base tool’s declared keys. The visit checks a door’s extras against this set before starting the target and refuses an undeclared key. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

remove_tool

tai42_contract.tools.AppTools.remove_tool

remove_tool(self, name: str) -> None

Remove the tool registered under name. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

register_tool_info

tai42_contract.tools.AppTools.register_tool_info

register_tool_info(self, name: str, combos: Sequence[Sequence[ExtensionElement]] | None = None) -> None

Parameter	Type	Default	Description
`name`	`str`	—	—
`combos`	`Sequence[Sequence[ExtensionElement]] \| None`	`None`	—

unregister_tool_info

tai42_contract.tools.AppTools.unregister_tool_info

unregister_tool_info(self, name: str) -> None

Drop the registered tool-info for name. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

unregister_tool_base

tai42_contract.tools.AppTools.unregister_tool_base

unregister_tool_base(self, tool_name: str) -> list[str]

Unregister base tool tool_name and return the names removed. Parameters

Parameter	Type	Default	Description
`tool_name`	`str`	—	—

tool_refs_extractor

tai42_contract.tools.AppTools.tool_refs_extractor

tool_refs_extractor(self, name: str) -> ToolRefsExtractor | None

Return the tool-references extractor base tool name registered, or None when it declared none. Parameters

Parameter	Type	Default	Description
`name`	`str`	—	—

register_rename_referee

tai42_contract.tools.AppTools.register_rename_referee

register_rename_referee(self, provider: ToolRenameReferee) -> None

Register a ToolRenameReferee consulted before a tool rename. A plugin holding tool-name references calls this through the tai42_app handle when its module loads. Every registered referee is asked for the old name on a rename; any non-empty answer blocks the rename and its descriptions name the holders. Registering the same provider object twice raises loudly — a double registration is a plugin bug, never a silent duplicate consult. Parameters

Parameter	Type	Default	Description
`provider`	`ToolRenameReferee`	—	—

register_delete_referee

tai42_contract.tools.AppTools.register_delete_referee

register_delete_referee(self, provider: ToolDeleteReferee) -> None

Register a ToolDeleteReferee consulted before a preset delete. A plugin holding resources keyed on a preset/tool name (e.g. per-node state bindings that reference a preset) calls this through the tai42_app handle when its module loads. Every registered referee is asked for the name on a delete; a referee cascades its own cleanup and returns empty to allow, or returns non-empty descriptions to VETO — any non-empty answer blocks the delete and names the holders. Registering the same provider object twice raises loudly — a double registration is a plugin bug, never a silent duplicate consult. Parameters

Parameter	Type	Default	Description
`provider`	`ToolDeleteReferee`	—	—

register_detach_referee

tai42_contract.tools.AppTools.register_detach_referee

register_detach_referee(self, provider: StateTemplateDetachReferee) -> None

Register a StateTemplateDetachReferee consulted before a state-template detach. A holder of door bindings that name templates (e.g. per-node state bindings, or the platform’s own preset/route/hook/schedule bindings) calls this through the tai42_app handle when its module loads. Every registered referee is asked for the (state, template) on a detach; any non-empty answer blocks the detach and its descriptions name the referencing bindings. Registering the same provider object twice raises loudly — a double registration is a bug, never a silent duplicate consult. Parameters

Parameter	Type	Default	Description
`provider`	`StateTemplateDetachReferee`	—	—

register_tier

tai42_contract.tools.AppTools.register_tier

register_tier(self, base_tool: str, tier: RouteAction) -> None

Declare base_tool’s registration tier (a RouteAction). The authorization character enforced everywhere the tier is consulted. A fenced or secret tier gates BOTH authoring a preset over the base tool (admin-only) AND running the tool: a fenced/secret tool runs only for an administrator, at every execution door, and a preset authored over it inherits that fence at run time. read/write carry no execution gate. This is the programmatic form of @app.tools.tool(tier=...); both write the one shared registry (also read on the authoring side as app.presets.registration_tier). One declaration per base tool; a duplicate raises loudly. Parameters

Parameter	Type	Default	Description
`base_tool`	`str`	—	—
`tier`	`RouteAction`	—	—

tier

tai42_contract.tools.AppTools.tier

tier(self, base_tool: str) -> RouteAction | None

The registration tier base_tool declared, or None when it declared none. None means no execution fence; authoring keeps the presets’ default write action. Parameters

Parameter	Type	Default	Description
`base_tool`	`str`	—	—

RunDelivery

tai42_contract.tools.call_frame.RunDelivery

class RunDelivery

The run’s single delivery identity and the starting door’s out-of-band address. run_delivery_id is the uuid4 minted once at the outermost run start, shared by every nested dispatch, sibling branch, and re-park of the run so its single terminal delivers once. delivery is the (tool, context) the starting door bound as the run’s completion address, or None when the door has no receiver. Attributes

Attribute	Type
`run_delivery_id`	`str`
`delivery`	`tuple[str \| None, Mapping[str, Any] \| None] \| None`

StateTemplateDetachReferee

tai42_contract.tools.StateTemplateDetachReferee

StateTemplateDetachReferee = Callable[[str, str], Awaitable[list[str]]]

ToolDeleteReferee

tai42_contract.tools.ToolDeleteReferee

ToolDeleteReferee = Callable[[str], Awaitable[list[str]]]

ToolInfo

tai42_contract.tools.ToolInfo

class ToolInfo(BaseModel)

Descriptor for a registered tool. name is the registered key; base is the underlying tool it was bound from (a branch tool names itself, e.g. name_chain). Attributes

Attribute	Type
`name`	`str`
`base`	`str`
`title`	`str`
`description`	`str`

ToolInvocation

tai42_contract.tools.invocation.ToolInvocation

class ToolInvocation(BaseModel)

The tool execution currently in flight. tool_name is the invoked tool’s registered name. Frozen — a deposited invocation is a fact of the active execution, never mutated in place. state_binding is the OPTIONAL door-layer binding a door deposits when it initiates a run (a channel route, a schedule fire, a hook, or none for a bare run-tool call): it rides the ambient context to the shared dispatch chokepoint, which carries it forward across its own re-deposit and merges it with the dispatched preset’s own binding before applying it around the run. The contract interprets nothing about it — a logic-free carrier. Attributes

Attribute	Type
`model_config`	—
`tool_name`	`str`
`state_binding`	`StateBinding \| None`

ToolRefsExtractor

tai42_contract.tools.ToolRefsExtractor

ToolRefsExtractor = Callable[[dict[str, Any]], Iterable[str]]

ToolRenameReferee

tai42_contract.tools.ToolRenameReferee

ToolRenameReferee = Callable[[str], Awaitable[list[str]]]

ToolRetryBackoff

tai42_contract.tools.retry.ToolRetryBackoff

class ToolRetryBackoff(BaseModel)

The exponential-backoff shape between attempts. Attempt n waits min(cap_seconds, initial_seconds * multiplier**(n-1)) before attempt n+1. A server-provided retry_after on the failed attempt’s error WIDENS the wait when it asks for longer (the medium’s own ask wins, even past the cap — the cap bounds the platform’s growth, not the server’s explicit request). Attributes

Attribute	Type
`model_config`	—
`initial_seconds`	`float`
`multiplier`	`float`
`cap_seconds`	`float`

ToolRetryPolicy

tai42_contract.tools.retry.ToolRetryPolicy

class ToolRetryPolicy(BaseModel)

A tool’s declared retry policy, consumed by the host dispatch seam. max_attempts is the TOTAL attempt budget, first attempt included (1 = no retry, just per-attempt monitoring). idempotent is the author’s explicit claim that re-firing the body is safe — REQUIRED, and a retrying policy (max_attempts > 1) without it is rejected (the double-send guard). retryable is the classification door — an explicit allowlist, never a blanket:

True — retry the DEFAULT_RETRYABLE_KINDS;
a tuple of ErrorKind — retry exactly those kinds (NEVER_RETRYABLE_KINDS are rejected at declaration);
False — no kind-based retry at all.

In every mode, an error carrying its OWN boolean retryable verdict (the ChannelDeliveryError shape) wins in BOTH directions: True admits it even off-list, False vetoes it even on-list — the raiser knows its failure better than any kind bucket. An error with neither a verdict nor an allowlisted kind is never retried. Attributes

Attribute	Type
`model_config`	—
`max_attempts`	`int`
`backoff`	`ToolRetryBackoff`
`retryable`	`bool \| tuple[ErrorKind, ...]`
`idempotent`	`bool`

current_call_chain

tai42_contract.tools.call_frame.current_call_chain

current_call_chain() -> tuple[str, ...]

The ambient tool/agent call chain, outermost first; empty outside any run.

current_extras

tai42_contract.tools.call_frame.current_extras

current_extras() -> Mapping[str, Any]

The ambient dispatch extras, or an empty mapping when none is bound.

current_tool_invocation

tai42_contract.tools.invocation.current_tool_invocation

current_tool_invocation() -> ToolInvocation | None

The tool execution in flight for the current context, or None when no tool is executing.

get_run_delivery

tai42_contract.tools.call_frame.get_run_delivery

get_run_delivery() -> tuple[str | None, Mapping[str, Any] | None] | None

The current run’s out-of-band delivery address, or None when receiver-less or unbound.

get_run_delivery_id

tai42_contract.tools.call_frame.get_run_delivery_id

get_run_delivery_id() -> str | None

The current run’s delivery identity, or None outside a bound run.

reset_current_tool_invocation

tai42_contract.tools.invocation.reset_current_tool_invocation

reset_current_tool_invocation(token: Token[ToolInvocation | None]) -> None

Restore the in-flight tool to the value captured in token. token is the return value of the matching set_current_tool_invocation call. Parameters

Parameter	Type	Default	Description
`token`	`Token[ToolInvocation \| None]`	—	—

run_delivery

tai42_contract.tools.call_frame.run_delivery

run_delivery(delivery: RunDelivery | None) -> Generator[None]

Re-establish a stored run-delivery context as the ambient one for the wrapped drive. A continuation drive of a receiver-less resume (the detached answer/expiry/reaper drive, a hook/schedule inline resume) is a fresh outermost run start with NO ambient run-delivery context, yet it must keep the RESUMED run’s own delivery identity and address so its terminal delivers under the same completion_id and a re-park inside stores the same pair. The chokepoint binds the interaction’s stored RunDelivery here BEFORE the drive, so the resume’s outermost tool_call_frame finds one already ambient and does NOT re-mint. None binds nothing (a run that stored no delivery context). ContextVar token discipline: reset in the finally. Parameters

Parameter	Type	Default	Description
`delivery`	`RunDelivery \| None`	—	—

set_current_tool_invocation

tai42_contract.tools.invocation.set_current_tool_invocation

set_current_tool_invocation(invocation: ToolInvocation) -> Token[ToolInvocation | None]

Deposit invocation as the in-flight tool for the current context. Pass the returned token to reset_current_tool_invocation to restore the previous value. Nested deposits (a tool invoking another) re-set for the inner call and restore the outer value on reset — ContextVar token discipline. Parameters

Parameter	Type	Default	Description
`invocation`	`ToolInvocation`	—	—

tool_call_frame

tai42_contract.tools.call_frame.tool_call_frame

tool_call_frame(
    name: str | None = None,
    extras: Mapping[str, Any] | None = None,
    *,
    continues_chain: Sequence[str] | None = None,
) -> Generator[None]

Open a call frame for a tool/agent dispatch, restoring the prior context on exit. See the module docstring for the three chain forms and the run-delivery bind. ContextVar token discipline: every value set here is reset in the finally. Parameters

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	—
`extras`	`Mapping[str, Any] \| None`	`None`	—
`continues_chain`	`Sequence[str] \| None`	`None`	—

​DEFAULT_RETRYABLE_KINDS

​MAX_ATTEMPTS_CEILING

​NEVER_RETRYABLE_KINDS

​AppTools

​Members

​tool_title

​get_tool

​get_tools

​get_client_tools

​run_tool

​extras

​declared_extras

​remove_tool

​register_tool_info

​unregister_tool_info

​unregister_tool_base

​tool_refs_extractor

​register_rename_referee

​register_delete_referee

​register_detach_referee

​register_tier

​tier

​RunDelivery

​StateTemplateDetachReferee

​ToolDeleteReferee

​ToolInfo

​ToolInvocation

​ToolRefsExtractor

​ToolRenameReferee

​ToolRetryBackoff

​ToolRetryPolicy

​current_call_chain

​current_extras

​current_tool_invocation

​get_run_delivery

​get_run_delivery_id

​reset_current_tool_invocation

​run_delivery

​set_current_tool_invocation

​tool_call_frame