TAI42 — the OS for AI tools

Execution-backend contract. Exposes the Backend ABC, the BackendRuntime ABC one launch subcommand implements, and the CallbackSchema.

BUS_APPLY_TIMEOUT_DEFAULT

tai42_contract.backend.runtime.BUS_APPLY_TIMEOUT_DEFAULT

BUS_APPLY_TIMEOUT_DEFAULT: Final[float] = 30.0

The apply window when the env var is unset. Mirrors the host’s own default; a drift guard on the host side keeps the two in step.

BUS_APPLY_TIMEOUT_ENV

tai42_contract.backend.runtime.BUS_APPLY_TIMEOUT_ENV

BUS_APPLY_TIMEOUT_ENV: Final[str] = 'TAI_BUS_APPLY_TIMEOUT'

Env var carrying the worker bus’s apply window — the deadline by which an op must report a terminal verdict. A pool turnover runs INSIDE that window, so the host derives the turnover’s budget from this value and a confirm-or-raise lands before the publisher’s report cut. A backend-runtime process is reached by the env, not by the bus settings object, so the NAME is the agreement.

CONSUMING_RUNTIME

tai42_contract.backend.runtime.CONSUMING_RUNTIME

CONSUMING_RUNTIME: Final[str] = 'worker'

Canonical launch-subcommand name of the runtime that pulls queued work. The host exports the resolved manifest into the env only for this runtime: the CLI sniffs argv BEFORE the plugin module is imported, so it cannot ask the backend. A backend that names its consuming runtime anything else does not get the manifest export.

POOL_TURNOVER_FLEET_OPS

tai42_contract.backend.runtime.POOL_TURNOVER_FLEET_OPS

POOL_TURNOVER_FLEET_OPS: Final[frozenset[str]] = REGISTRY_MUTATING_FLEET_OPS | TEMPLATE_EVICTION_FLEET_OPS

Worker-bus ops after which a pool that PERSISTS ACROSS JOBS must be turned over — the superset of “mutates the tool registry” and “evicts the compiled-template cache”. A registry mutation leaves persisted workers holding a stale snapshot; a template eviction leaves them holding a stale compilation; either way the fix is the same canonical pool turnover. The turnover gate reads THIS set, so a runtime whose workers hold a snapshot of the registry OR their own compiled cache turns its pool over after one of these applies.

REGISTRY_MUTATING_FLEET_OPS

tai42_contract.backend.runtime.REGISTRY_MUTATING_FLEET_OPS

REGISTRY_MUTATING_FLEET_OPS: Final[frozenset[str]] = frozenset({'reload_config', 'reload_mcp', 'deregister_mcp', 'reload_tool', 'remove_tool', 'reload_failed_mcps'})

Worker-bus ops that mutate this process’s tool registry. list_failed_mcps is a query and recycle ends the process, so neither is here. These are one input to POOL_TURNOVER_FLEET_OPS, the set the turnover gate actually reads.

TEMPLATE_EVICTION_FLEET_OPS

tai42_contract.backend.runtime.TEMPLATE_EVICTION_FLEET_OPS

TEMPLATE_EVICTION_FLEET_OPS: Final[frozenset[str]] = frozenset({'evict_template', 'clear_template_cache'})

Worker-bus ops that drop this process’s compiled-template cache. A runtime whose worker processes render templates and PERSIST ACROSS JOBS hold their own compiled cache; a store edit dispatched over the bus reaches only bus MEMBERS, so those workers keep serving a stale compilation until the pool turns over. One input to POOL_TURNOVER_FLEET_OPS.

Backend

tai42_contract.backend.base.Backend

class Backend(ABC)

Abstract execution backend for a Tai app. A backend runs the task runtime (launch) and executes the work its workers pull from the broker. The app core depends only on this interface and stays backend-agnostic; concrete backends (celery/rq/arq) implement it and register via @tai42_app.backends.register_backend. Fleet propagation of config changes is not a backend concern: it is the app’s own worker bus, internal to the app. A backend-runtime process receives fleet ops through the app’s bus subscription exactly like a serving HTTP worker — the backend carries no control-plane surface of its own.

Members

launch

tai42_contract.backend.base.Backend.launch

async launch(self, args: Sequence[str]) -> None

Start the worker runtime for the backend registered via @tai42_app.backends.register_backend. Parameters

Parameter	Type	Default	Description
`args`	`Sequence[str]`	—	—

BackendRuntime

tai42_contract.backend.runtime.BackendRuntime

class BackendRuntime(ABC)

ONE launchable runtime of an execution backend, named by its launch subcommand. The vendor binding answers only “how MY engine starts, drains, and recycles”; readiness gating, signal wiring, drain-on-cancellation and pool turnover belong to the host base that drives this object.

Members

name

tai42_contract.backend.runtime.BackendRuntime.name

name: str

The launch subcommand that selects this runtime.

mode

tai42_contract.backend.runtime.BackendRuntime.mode

mode: ExecutionMode

How the host must drive the run body.

consumes_work

tai42_contract.backend.runtime.BackendRuntime.consumes_work

consumes_work: bool = False

True when this runtime pulls queued work. Only a consuming runtime is readiness-gated, drain-wired, and turnover-wired.

pool_turnover_required

tai42_contract.backend.runtime.BackendRuntime.pool_turnover_required

pool_turnover_required: bool = False

True when work executes in worker processes that PERSIST ACROSS JOBS and therefore hold a snapshot of this process’s tool registry: a registry mutation does not reach them, so the pool must be turned over. False for a runtime that runs work in-process, and for one that spawns a fresh child per job (the next child inherits the mutation). Declared per class like the rest, but deliberately NOT a ClassVar: a launch option can decide whether this engine’s pool persists, so an instance may set it. The host therefore reads it off the live runtime.

from_args

tai42_contract.backend.runtime.BackendRuntime.from_args

from_args(cls, args: Sequence[str]) -> Self

Parse this runtime’s own options and return the runtime. Strict — an unknown option aborts the launch loudly. Parses only; starts nothing. Parameters

Parameter	Type	Default	Description
`args`	`Sequence[str]`	—	—

build

tai42_contract.backend.runtime.BackendRuntime.build

async build(self) -> None

Construct engine objects. Runs BEFORE the readiness gate — building is not consuming — and before any run body. Default: nothing to build. Concrete rather than abstract: a runtime whose engine object is built by from_args alone must not be forced to declare an empty override.

run_on_loop

tai42_contract.backend.runtime.BackendRuntime.run_on_loop

async run_on_loop(self) -> None

Consume until stopped, driven by the serving loop. REQUIRED iff mode is on_loop.

run_blocking

tai42_contract.backend.runtime.BackendRuntime.run_blocking

run_blocking(self) -> None

Consume until stopped, blocking the calling thread. REQUIRED iff mode is worker_thread or inline.

request_drain

tai42_contract.backend.runtime.BackendRuntime.request_drain

request_drain(self) -> None

Stop accepting new work, let in-flight work finish, and make the run body RETURN once drained. Called from the loop thread — while a worker_thread body runs on another thread — so it MUST NOT block and MUST NOT touch main-thread-only APIs (signal.signal above all: the host owns the process’s signal disposition and a vendor rebind destroys it). MUST BE IDEMPOTENT: the host calls it on signal AND again on the cancellation path. Escalation belongs to request_terminate, never to a second request_drain. REQUIRED iff consumes_work.

request_terminate

tai42_contract.backend.runtime.BackendRuntime.request_terminate

request_terminate(self) -> None

Cold stop: abandon in-flight work now. Called on a repeated signal. Default: report that this runtime declares no cold stop and let the warm drain continue — the supervisor’s kill is the backstop.

turn_over_pool

tai42_contract.backend.runtime.BackendRuntime.turn_over_pool

async turn_over_pool(self, *, reason: str, budget: float) -> None

Replace every worker that predates the mutation named by reason, and CONFIRM it. On return, no pre-mutation worker may still serve work. Raise loudly if it cannot be confirmed within budget seconds — the caller is inside a fleet-op apply, and a raise makes that op report failed rather than a false applied. Called from the fleet-op hook, which the host wires BEFORE build so an op landing during a long boot is not missed. So this may run before the engine objects exist, and it runs CONCURRENTLY with the run body once they do. A no-op is the correct answer whenever there is no pool yet, or the live pool turns out not to hold a snapshot: the workers that do not exist cannot be stale, and the next ones are built after the mutation. REQUIRED iff pool_turnover_required. Parameters

Parameter	Type	Default	Description
`reason`	`str`	—	—
`budget`	`float`	—	—

aclose

tai42_contract.backend.runtime.BackendRuntime.aclose

async aclose(self) -> None

Release engine resources once the run body is done with them. Always awaited, on every exit path. Default: nothing to release. The run body has normally LEFT by then, but there is one exception the binding has to survive: a blocking body cannot be cancelled, so a cancellation that arrives while it is still on its thread abandons it there (the host reports this) and teardown runs anyway. Release what can be released without assuming the body let go. Concrete rather than abstract: a runtime that owns no resource must not be forced to declare an empty override.

CallbackSchema

tai42_contract.backend.callback.CallbackSchema

class CallbackSchema(ConditionMixin, ExprMixin)

A backend task’s follow-up: an optional guard condition and a follow-up tool kwargs expr. Attributes

Attribute	Type
`tool`	`str`
`carried_kwargs`	`dict[str, Any]`
`condition`	`Annotated[TemplatedText \| None, Field(json_schema_extra={EXPRESSION_ANNOTATION_KEY: expression_annotation(label='condition', blurb="the backend task's tool result", keys=[], returns='truthy to run the callback', sample={})})]`
`expr`	`Annotated[TemplatedText \| None, Field(json_schema_extra={EXPRESSION_ANNOTATION_KEY: expression_annotation(label='expression', blurb="the backend task's tool result", keys=[], returns="an object — the follow-up tool's kwargs", caveats=['an empty expression, or a jq pipeline producing no output, yields {} (the follow-up tool runs with empty kwargs) — not an error'], sample={})})]`

ExecutionMode

tai42_contract.backend.runtime.ExecutionMode

class ExecutionMode(StrEnum)

How a runtime’s run body must be driven.

Members

on_loop

tai42_contract.backend.runtime.ExecutionMode.on_loop

on_loop = 'on_loop'

The run body is a coroutine driven by the serving loop.

worker_thread

tai42_contract.backend.runtime.ExecutionMode.worker_thread

worker_thread = 'worker_thread'

The run body blocks; the host runs it on a dedicated daemon thread.

inline

tai42_contract.backend.runtime.ExecutionMode.inline

inline = 'inline'

The run body blocks the serving loop deliberately; the host wires nothing.

HTTP API

CLI

Settings

Capability map

Conversation bridge

Python SDK

Studio SDK

Backends (tai42_contract.backend)

BUS_APPLY_TIMEOUT_DEFAULT

BUS_APPLY_TIMEOUT_ENV

CONSUMING_RUNTIME

POOL_TURNOVER_FLEET_OPS

REGISTRY_MUTATING_FLEET_OPS

TEMPLATE_EVICTION_FLEET_OPS

Backend

Members

launch

BackendRuntime

Members

name

mode

consumes_work

pool_turnover_required

from_args

build

run_on_loop

run_blocking

request_drain

request_terminate

turn_over_pool

aclose

CallbackSchema

ExecutionMode

Members

on_loop

worker_thread

inline

​BUS_APPLY_TIMEOUT_DEFAULT

​BUS_APPLY_TIMEOUT_ENV

​CONSUMING_RUNTIME

​POOL_TURNOVER_FLEET_OPS

​REGISTRY_MUTATING_FLEET_OPS

​TEMPLATE_EVICTION_FLEET_OPS

​Backend

​Members

​launch

​BackendRuntime

​Members

​name

​mode

​consumes_work

​pool_turnover_required

​from_args

​build

​run_on_loop

​run_blocking

​request_drain

​request_terminate

​turn_over_pool

​aclose

​CallbackSchema

​ExecutionMode

​Members

​on_loop

​worker_thread

​inline

BUS_APPLY_TIMEOUT_DEFAULT

BUS_APPLY_TIMEOUT_ENV

CONSUMING_RUNTIME

POOL_TURNOVER_FLEET_OPS

REGISTRY_MUTATING_FLEET_OPS

TEMPLATE_EVICTION_FLEET_OPS

Backend

Members

launch

BackendRuntime

Members

name

mode

consumes_work

pool_turnover_required

from_args

build

run_on_loop

run_blocking

request_drain

request_terminate

turn_over_pool

aclose

CallbackSchema

ExecutionMode

Members

on_loop

worker_thread

inline